diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8e3dcc7..1c588d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,7 +15,7 @@ A repository created from this template must provide one ready-to-use workspace - bare `firstdraft` on the Codespace PATH resolves to `bin/firstdraft`, and AGENTS.md routes Skill-issued commands through that wrapper; and - the same container carries the current generated Foundation's Ruby and Node toolchain plus healthy PostgreSQL; - generated browser tests start the pinned Selenium service on demand, so the generated application can be + generated browser tests start Selenium on demand, so the generated application can be developed without a second Codespace. PostgreSQL health checks use TCP so the entrypoint's temporary Unix-socket-only initialization server cannot @@ -60,7 +60,7 @@ The accepted cross-repository sequence and its safety boundaries live in | `script/devcontainer-smoke` | Runtime smoke executed inside the built Dev Container | | `script/refresh-codespaces-private-port` | Safe post-attach refresh for the private Rails forwarded-port registration | | `script/initialize-application` | Parentless nested Git initialization for direct-download output | -| `script/selenium` | On-demand Selenium start, status, and stop inside the Dev Container | +| `script/selenium` | Selenium lifecycle for template and optional nested-application qualification | | `script/application-smoke` | Setup, PostgreSQL, readiness, and full CI proof for a generated `./application` | The nested initializer follows the generated application's own ignore rules. The only artifact-owned paths allowed to @@ -136,10 +136,16 @@ The candidate workflow does not move a stable or `latest` tag. The image receipt tree, workflow run, platforms, and manifest digest consumed by the template. The current receipt records both anonymous access and the retained comparison Codespace as passed. That exact Codespace also proved that `script/selenium` resolves the Compose project from its runtime container identity; no speculative fallback was -needed. The Docker-outside-of-Docker Feature reaches the host daemon: that host is a disposable VM in Codespaces, -but it is the developer's own machine on the supported local path. Do not run an untrusted workspace or agent with -that socket mounted. The workspace starts only its exact Compose-owned Selenium service when -`script/application-smoke` or `script/selenium start` requests browser proof. +needed. The helper remains in use by `script/application-smoke` for the optional nested application and by +`script/devcontainer-smoke` to verify that browser tests have not started Selenium during workspace setup. +Root-adopted applications instead use their generated `.devcontainer/compose.yaml` and the running container's +Compose project, as shown in the [browser-testing instructions](README.md#7-open-your-app). The generated health +check uses Selenium's supplied `/opt/bin/check-grid.sh`; Compose owns readiness for both that command and fresh +generated Dev Container startup. + +The Docker-outside-of-Docker Feature reaches the host daemon: that host is a disposable VM in Codespaces, but it is +the developer's own machine on the supported local path. Do not run an untrusted workspace or agent with that socket +mounted. The planning workspace starts Selenium only when browser proof requests it. The runtime Dev Container opts the remote extension host into Node's supported `navigator` global through `extensions.supportNodeGlobalNavigator`. A 2026-09-01 browser-Codespaces observation found VS Code 1.133.0 and the diff --git a/DIRECT_COMPILATION_PLAN.md b/DIRECT_COMPILATION_PLAN.md index c4e4688..eb77c5e 100644 --- a/DIRECT_COMPILATION_PLAN.md +++ b/DIRECT_COMPILATION_PLAN.md @@ -374,8 +374,9 @@ It never creates a Git repository, starts Publication, deploys, or substitutes f Drawing Board now selects root adoption for the internal-alpha handoff so the same conversation can move from Plan to inspectable source and an ordinary feature commit in one repository. The older nested path retains its separate -initializer/smoke workflow. Root mode instead uses generated `bin/setup` and `bin/ci` at the root, with -`design/script/selenium` for browser checks in the original running container; see the current README. +initializer/smoke workflow. Root mode instead uses generated `bin/setup` and `bin/ci` at the root, starting Selenium +through the generated `.devcontainer/compose.yaml` in the original running container's Compose project. Compose +waits for Selenium's supplied health check; see the [current browser-testing instructions](README.md#7-open-your-app). ### Observed current-root qualification on 2026-09-02 @@ -441,8 +442,8 @@ that time: The comparison supports the existing mode split. Current-root adoption preserves one Git history and lets one agent carry the reviewed design directly into ordinary Rails work without a nested repository or second workspace. It also replaces the workspace layout in place, moves First Draft commands under `design/`, requires an immediate inspection -and commit, and currently needs the relocated Selenium helper when qualification continues inside the container that -predated the move. `./application` has a dedicated nested repository initializer followed by one-command smoke +and commit, and uses the generated `.devcontainer/compose.yaml` in the current running container's Compose project +for browser qualification. `./application` has a dedicated nested repository initializer followed by one-command smoke orchestration. The internal-alpha guide now favors `--output .` for its one-repository handoff and teaches the structural transition explicitly; no new CLI transaction or orchestration layer is implied by that choice. diff --git a/README.md b/README.md index 31fb754..1ff69a4 100644 --- a/README.md +++ b/README.md @@ -241,17 +241,23 @@ Before changing anything, open those JSON files and read the generated models, c migrations, and tests. Ask which Rails APIs and established gems the app uses, and whether you would write it this way by hand. You do not need a separate First Draft web editor. -Run the broader checks against the committed baseline. In the still-running Drawing Board container, start its -existing browser-test service through the relocated helper: +Run the broader checks against the committed baseline. In the still-running Drawing Board container, use the +generated application's Compose file to start Selenium in the current container's Compose project: ```sh -design/script/selenium start +project="$(docker inspect --format '{{ index .Config.Labels "com.docker.compose.project" }}' "$HOSTNAME")" +docker compose --project-name "$project" --file .devcontainer/compose.yaml up --detach --wait selenium CI=1 bin/ci -design/script/selenium stop +docker compose --project-name "$project" --file .devcontainer/compose.yaml stop selenium ``` -Stop Selenium after the run, including after a failure. Its first image download can take a few minutes. This is -the observed current-container path; do not rebuild the container or add a custom browser service to use it. +Run the stop command even if CI fails; do not join it to the CI command with `&&`. Stopping only Selenium leaves +Rails and PostgreSQL running. Its first image download can take a few minutes, then Compose waits for Selenium's +supplied health check. Selecting the current project puts the browser on the existing workspace's network. + +These commands use the Docker tooling already in the running Drawing Board container. A fresh Dev Container opened +from the generated application starts Selenium through its normal Compose dependencies and waits for the same +health check; follow that application's README for testing. If you explicitly chose Publication, open the private repository from the URL the agent provides. Create a Codespace there and follow its README instead; the original Drawing Board remains a separate planning workspace.