From 268d4978b9a2c0d5704dfcfaeb75c8d88f64e591 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Tue, 22 Sep 2026 23:47:13 -0500 Subject: [PATCH] Use generated Compose for browser checks Ordinary application checks should use their own Compose files. Keep the browser in the existing workspace project and stop it after failed checks while preserving historical qualification. --- CONTRIBUTING.md | 17 +++++++++++------ DIRECT_COMPILATION_PLAN.md | 27 +++++++++++++++++---------- README.md | 18 ++++++++++++------ 3 files changed, 40 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92889bd..892d251 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 @@ -63,7 +63,7 @@ The accepted cross-repository sequence and its safety boundaries live in | `script/agent-smoke` | Agent versions, PATH, commands, configuration, and shared Skill installation/discovery | | `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 @@ -172,10 +172,15 @@ 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 workspace setup has not started Selenium. Root-adopted applications 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 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 9dd9ca3..14209f4 100644 --- a/DIRECT_COMPILATION_PLAN.md +++ b/DIRECT_COMPILATION_PLAN.md @@ -515,7 +515,11 @@ Codespace after proof or a recorded abort. Do not treat a local Docker rehearsal ## Compile into an existing root -CLI 0.2.2 implements POSIX current-root adoption in any eligible real directory rather than recognizing Drawing +For current root eligibility, archive paths, and later authoring commands, use the +[root-Compile instructions](README.md#5-describe-your-app). The CLI owns the transaction details. The following +contract records CLI 0.2.2 for the dated qualification below; it is historical. + +CLI 0.2.2 implemented POSIX current-root adoption in any eligible real directory rather than recognizing Drawing Board specially: ```sh @@ -536,8 +540,12 @@ 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 uses generated `bin/setup` and `bin/ci` at the root, starting Selenium through +the generated `.devcontainer/compose.yaml` in the running container's Compose project. Compose waits for Selenium's +health check; see the [current browser-testing instructions](README.md#7-open-your-app). The dated observations +below retain the helpers and source they exercised. Current fallback qualification remains under +[Service #729](https://github.com/firstdraft/firstdraft/issues/729) and +[#730](https://github.com/firstdraft/firstdraft/issues/730), including private preview and fresh-template attachment. ### Observed current-root qualification on 2026-09-02 @@ -600,13 +608,12 @@ that time: private; and the exact Codespace reached `Shutdown` after one stop request. No Publication, package release, deployment, or application-repository push occurred. -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 -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. +The comparison supported the mode split. At that checkpoint, root adoption preserved one Git history and let one +agent carry the reviewed design into ordinary Rails work without a nested repository or second workspace. It moved +First Draft commands under `design/`, required an immediate inspection and commit, and used the relocated Selenium +helper inside the container that predated the move. The nested path used its dedicated initializer and smoke. +Those observed paths remain historical. Use the current [root-Compile instructions](README.md#5-describe-your-app) +and [browser-testing instructions](README.md#7-open-your-app). ## Ownership and sequencing diff --git a/README.md b/README.md index 68c4339..a242a14 100644 --- a/README.md +++ b/README.md @@ -285,17 +285,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. From the application root in the still-running Drawing +Board container, use the generated application's Compose file to start Selenium in the current container's project: ```sh -.firstdraft/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 -.firstdraft/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 +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.