[345942185-eng]

Problem and user impact

Contributors currently have to reconstruct installed-container configuration to run the complete application from their checkout. This adds an isolated source-development entry point for #65.

Closes #65.

Change

• Add npm run dev:stack with down, reset and rebuild: PostgreSQL/Temporal in a checkout-specific Compose project, migrations, source API watch/Vite, built-from-source worker and CLI host.
• Read dependency image digests from the existing launcher template. Generate private state and mode-0600 secrets, use separate loopback ports/sockets, disable dev-login and isolate provider homes.
• Install the exact OpenCode package pinned in Dockerfile into local state; support the current @opencode/cli pin as well as the older opencode-ai spelling.
• Forward terminal WebSockets through Vite and prevent dev authentication from discovering an installed operator's Google OAuth files.
• Add a real Docker/HTTP/PTY/reset acceptance script and Ubuntu workflow, targeted regression tests, public-export registration, and contributor instructions for Linux/macOS/WSL2.

Verification

Executed locally on Linux x86_64 with Node 22.23.0:

• npm run check — passed.
• npm run build — passed.
• npm run hygiene:preflight — passed before commit.
• node --test scripts/tests/dev-stack.test.mjs scripts/tests/dev-stack-vite.test.mjs scripts/tests/public-export.test.mjs scripts/tests/public-package-metadata.test.mjs — 47 passed. This includes real HTTP and WebSocket proxy transport.
• API vitest run tests/auth-dev-isolation.test.ts tests/auth.test.ts — 15 passed.
• ESLint for the new launcher/modules/tests — passed.
• npm test — blocked by the existing credential-agent test: listen EPERM for its Unix socket in this execution environment. The full workspace suite therefore has not completed.

Additional verification (2026-10-22)

• Fixed readiness to require a RUNNING database and worker with Temporal enabled, rather than accepting ok: true alone.
• Fixed acceptance cleanup to reset resources even after the launcher has already exited. Cleanup failures fail the smoke run while preserving the original startup error.
• Added regression coverage for disabled/missing/unhealthy dependencies and a failed-launcher cleanup scenario. The latter uses a simulated failed launcher to verify cleanup orchestration; it is not Docker acceptance.
• Restored .github/workflows/ci.yml and its workflow assertions to the upstream version. Issue [$450] One command to run the full SpaceApp stack from source for contributors #65 explicitly says the expected external-PR export provenance failure is ignored by reviewers.
• Re-ran the five relevant test files (dev-stack, Vite, workflows, export, package metadata): 55 passed, 0 failed under Node 22.23.0. ESLint with zero warnings, syntax/diff checks and hygiene preflight passed.
• All five uploaded file contents were fetched back from GitHub and matched the locally verified commit exactly.

CI failure fixes (2026-10-22)

• Ubuntu job 119704861837 completed database migrations but the web child exited with MODULE_NOT_FOUND: Vite was resolved relative to apps/web instead of the hoisted root node_modules. The launcher now starts the absolute root executable while retaining apps/web as cwd.
• Added a real child-process Vite startup and HTTP readiness-proxy regression, sharing the production startWeb function. Five relevant test files passed: 56/56; ESLint with zero warnings and hygiene preflight passed.
• macOS job 119704862221 exposed /var versus /private/var in temporary test roots. Fixtures now resolve their root exactly as the production launcher does. The 12 source-stack tests passed locally, and all 10 state/process tests also passed with a symlinked TMPDIR. State-directory symlink rejection remains intact.
• The four uploaded files were fetched back and matched the local verified tree exactly. New CI runs are pending; these local checks do not yet establish full Docker/macOS acceptance.

GitHub-hosted Linux acceptance (2026-10-22)

Source commit: bc12e2a.
Ubuntu job: https://github.com/345942185-eng/spaceapp/actions/runs/39744865646/job/119710702648 — passed.

PASS: normal owner claim/login, Getting Started room, real OpenCode terminal.
PASS: reset removed every dev-stack container, volume and source process.

This is real Docker/PostgreSQL/Temporal and OpenCode PTY acceptance, with no provider credentials. The source quality job has also passed typechecking; its remaining tests/build and macOS acceptance are still running. The earlier local Docker limitation below describes the local sandbox only, not this successful GitHub-hosted Linux run.

Dependency audit follow-up (2026-10-22)

• Commit 3541d69 updates only the Vite lock entry from 7.3.6 to 7.3.7, retaining the existing supported dependency range.
• Local npm audit --audit-level=high exits successfully: 0 high/critical, 7 moderate findings remain. No audit thresholds or scanning jobs were disabled. The moderate findings still need review.
• The two real Vite HTTP/WebSocket and child-process startup tests passed with Vite 7.3.7 under Node 24.19.0. Required Node 22 and full CI revalidation are pending.
• Uploaded package-lock.json was fetched back and its Git blob hash matched the verified local Vite-only patch (23b07eaa77f5b4310329f1e759d08cefe694e3ff).
• Fork Dependency review currently fails because its Dependency graph is disabled. This repository setting is not changed by this PR.

Draft acceptance gaps

• This environment has no Docker executable/daemon and restricts Unix sockets. dev:stack was checked to fail clearly at Docker preflight; a complete Docker startup/owner/OpenCode/reset run has not been executed.
• Ubuntu acceptance is now green, with the logs linked above.
• macOS or WSL2 terminal output, browser hot-reload evidence and human manual acceptance remain outstanding.

AI-assisted implementation and automated verification were performed with Codex. The submitting contributor's own review/manual testing remains pending. This PR stays a draft until the outstanding acceptance evidence is supplied.

Security, migration, resources and rollback

The development command creates only its own state/Compose resources and runs the existing migrations against a separate development database. It requires network access for pinned images/OpenCode and consumes local Docker resources. Temporal runs as container UID 0 to read the mode-0600 host-mounted Compose secret; no privileged mode or host-root mount is added. down retains development data; reset removes this checkout's development resources. Published installer/image behavior is unchanged.

• Every commit has a Signed-off-by: line; contribution under MIT.
• Runtime state and generated secrets are excluded from Git and Docker context.
• Contributor documentation updated.
• Full test suite, Docker acceptance and required platform evidence completed.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}