Реализовать поддержку hostScript как host-side pre-launch step

[flancer64]

Контекст

Когнитивный контекст библиотеки уже зафиксировал целевую модель runtime preparation:

• hostScript — optional host-side pre-launch step;
• setupScript — optional container-side startup step.

По принятой модели:

• hostScript входит в resolved execution model и в Launch Contract;
• hostScript выполняется на хосте до docker run;
• setupScript выполняется внутри контейнера после container startup и до handler launch;
• Docker runtime adapter не исполняет hostScript;
• hostScript не создаёт отдельного execution unit и не меняет profile selection semantics.

Сейчас продуктовая реализация поддерживает только setupScript как container-side preparation step. Нужно довести реализацию до модели, уже принятой в контексте.

Задача

Реализовать в @teqfw/github-flows поддержку hostScript в execution profile и runtime execution path в соответствии с актуальным когнитивным контекстом.

Что нужно сделать

1. Расширить модель profile/runtime

Нужно добавить поддержку execution.runtime.hostScript в product implementation:

• profile parsing/validation;
• internal selected profile model;
• launch contract materialization;
• public types, если они отражают shape профиля или launch contract.

Ожидаемая модель:

• hostScript — optional string;
• setupScript остаётся optional/required ровно в том виде, который согласован с текущей моделью продукта;
• оба поля должны быть доступны downstream execution path без неявных преобразований semantics.

2. Обновить Launch Contract

Нужно довести runtime contract до shape, согласованного с контекстом:

• environment.hostScript
• environment.setupScript

При этом важно сохранить существующую границу ответственности:

• contract materialization только резолвит startup parameters;
• contract не становится workflow description.

3. Реализовать host-side execution шага hostScript

Нужно внедрить реальный host-side pre-launch step в execution path.

Целевая последовательность:

1. selected profile resolved;
2. workspace prepared;
3. launch contract materialized;
4. если environment.hostScript задан, он выполняется на хосте;
5. затем запускается Docker runtime;
6. внутри контейнера выполняется environment.setupScript;
7. затем стартует handler.

Важно:

• hostScript не должен исполняться Docker runtime adapter;
• hostScript должен исполняться в host environment;
• ошибка hostScript должна останавливать запуск до container startup;
• observability/logging должен сохранять понятную границу между host pre-launch failure и container runtime failure.

4. Сохранить boundary Docker runtime adapter

Текущий Docker runtime adapter должен остаться container execution component.

Нужно убедиться, что после реализации:

• Docker runtime adapter не исполняет hostScript;
• он по-прежнему отвечает только за container step;
• setupScript остаётся container-side preparation step.

Если для этого нужно вынести host-side запуск в coordinator или другой pre-runtime слой, это нужно сделать явно, а не через скрытое расширение Docker adapter responsibilities.

5. Обновить logging и execution result semantics

Нужно проверить и при необходимости доработать logging/observability для нового шага:

• отдельные сообщения/стадии для host-side hostScript;
• понятное различие между failure на этапе host pre-launch и failure внутри container runtime;
• отсутствие утечки чувствительных значений из команд и окружения, если hostScript работает с credentials.

6. Добавить/обновить тесты

Нужно покрыть как минимум:

• profile/launch-contract support for hostScript;
• успешный execution path: hostScript -> Docker runtime -> setupScript -> handler;
• failure path, когда hostScript завершается с ошибкой и container startup не происходит;
• invariants, что Docker runtime adapter не исполняет hostScript;
• backward compatibility для профилей без hostScript.

Если для этого достаточно unit/integration tests, выбрать минимально достаточный набор, но поведение должно быть верифицировано явно.

7. Обновить product-facing documentation

Нужно обновить repository-level docs, которые описывают profile configuration и single-event launch, чтобы они соответствовали новой реализации.

Минимум проверить и обновить:

• docs про profile.json / launch / runtime configuration;
• examples, где сейчас фигурирует только setupScript.

Ограничения

• Реализация должна следовать уже принятому когнитивному контексту, а не переопределять его.
• Не превращать hostScript в общий orchestration framework.
• Не переносить выполнение hostScript внутрь контейнера.
• Не смешивать hostScript с profile selection logic.

Критерии приёмки

Задача считается выполненной, если:

• execution.runtime.hostScript поддерживается в продукте end-to-end;
• hostScript реально выполняется на хосте до container startup;
• setupScript по-прежнему выполняется внутри контейнера;
• Docker runtime adapter не исполняет hostScript;
• ошибки hostScript корректно прерывают запуск и наблюдаемы в логах;
• тесты покрывают success/failure paths и backward compatibility;
• repository-level docs и examples согласованы с новой реализацией.

Что нужно указать в итоговом отчёте

В комментарии или PR summary нужно указать:

• какие product/code changes были внесены;
• где именно теперь исполняется hostScript;
• как обеспечено различие между host-side и container-side startup steps;
• какие тесты были добавлены или обновлены;
• какие ограничения или follow-up задачи остались после реализации.