Add npm run dev:stack — one command to run the full stack from source (closes #65)

.github/workflows/dev-stack.yml

@@ -0,0 +1,60 @@
+name: Dev stack
+
+# End-to-end check for `npm run dev:stack` (issue: one command to run the
+# full SpaceApp stack from source). Runs the stack without a TTY, completes
+# owner setup over HTTP, checks the starter room's CLI pane, then resets
+# and verifies nothing is left behind.
+on:
+  pull_request:
+    paths:
+      - "scripts/dev-stack.mjs"
+      - "scripts/dev-stack-ci.mjs"
+      - "scripts/dev-stack.compose.yml"
+      - "package.json"
+      - ".github/workflows/dev-stack.yml"
+  workflow_dispatch:
+
+jobs:
+  dev-stack:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm ci
+
+      - name: Run the dev stack end to end
+        run: node scripts/dev-stack-ci.mjs
+
+  # Same end-to-end check on macOS (acceptance asks for Linux and
+  # macOS/WSL2 run outputs). GitHub's macOS runners ship no Docker, so
+  # Colima provides the daemon; the stack itself is unchanged.
+  dev-stack-macos:
+    runs-on: macos-14
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install Docker via Colima
+        run: |
+          brew install colima docker docker-compose
+          mkdir -p ~/.docker/cli-plugins
+          ln -sfn "$(brew --prefix docker-compose)/bin/docker-compose" ~/.docker/cli-plugins/docker-compose
+          colima start --cpu 4 --memory 6
+
+      - name: Install dependencies
+        run: ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm ci
+
+      - name: Run the dev stack end to end
+        run: node scripts/dev-stack-ci.mjs

.gitignore

@@ -1,6 +1,7 @@
 # Generated outputs and local tool reports. These are safe to regenerate; do
 # not commit them, and clean them only with an allowlist.
 node_modules/
+.dev-stack/
 dist/
 dist-mock/
 dist-types/

CONTRIBUTING.md

@@ -27,6 +27,61 @@ packaging requires its normal toolchain and separate platform acceptance.
 Dependency installation may use the network; the smoke command below does not
 need a provider account, API key, Docker, PostgreSQL or Temporal.
 
+## Run the full app from source
+
+One command starts the whole application from a fresh clone — no image
+builds, no manual service wiring:
+
+```sh
+ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm ci   # once, if node_modules is missing
+npm run dev:stack                        # start everything
+npm run dev:stack -- down                # stop processes and Docker services
+npm run dev:stack -- reset               # stop + remove containers, volumes and state
+```
+
+**Prerequisites.** Node >=22.12 <23 and npm (as above), plus a running
+Docker with Compose v2 — only PostgreSQL (pgvector) and Temporal run in
+Docker, using the same digest-pinned images as
+`packages/run-spaceapp/templates/compose.yml` (the digests are read from
+that file at startup, never copied). The API (watch mode), the Vite web dev
+server, the Temporal worker and the CLI host all run from source.
+
+**What it does.** The command creates a `.dev-stack/` state directory
+(git-ignored) holding per-install secrets (mode 0600), the rendered compose
+file, logs, the CLI provider state, the `*-vscode-parity` wrapper commands
+and the pinned OpenCode build from the `Dockerfile`, installed into the
+state directory rather than globally. It runs the migrations, starts the
+processes in dependency order and waits until `/readyz` reports `ok: true`
+with workflows enabled. It then prints the web URL and the one-time owner
+setup token — complete the usual owner setup in the browser (setup token →
+create owner → sign in; the token is valid for about 15 minutes after the
+API starts, restart the stack if it lapses). The dev-login shortcut is
+never enabled. If any process exits, the command says which one and where
+its log is instead of hanging silently.
+
+**Ports.** Everything binds to `127.0.0.1` only, on its own ports so an
+installed SpaceApp on 4910/4911 is never touched: web 14911, API 14910,
+PostgreSQL 15432, Temporal 7233. Override any of them with
+`SPACE_DEV_WEB_PORT`, `SPACE_DEV_API_PORT`, `SPACE_DEV_POSTGRES_PORT` and
+`SPACE_DEV_TEMPORAL_PORT`.
+
+**Hot reload.** Editing `apps/api/src` restarts the API, editing
+`apps/web/src` hot-reloads in the browser, and editing `packages/*` or the
+worker rebuilds that package and restarts the processes that consume it.
+
+**Platform notes.** Linux works as-is. On macOS, Docker Desktop or Colima
+both work (`colima start` before the command). On Windows 11, run
+everything inside WSL2, including Docker Desktop's WSL2 backend; the
+commands above are run from the WSL2 shell, not from PowerShell.
+
+**Troubleshooting.** "Docker is not reachable" — start Docker Desktop /
+Colima / dockerd and retry. A port is already in use — another dev stack or
+an unrelated process holds it; pick another port with the variables above.
+The setup token expired — stop and start again, then claim promptly. Logs
+for every process are in `.dev-stack/logs/`. `npm run dev:stack -- status`
+shows what is currently running; `reset` returns the machine to a clean
+slate.
+
 ## First executed task, without a provider
 
 ```sh

apps/web/vite.config.ts

@@ -33,12 +33,14 @@ export default defineConfig({
   server: {
     host: process.env.SPACE_WEB_HOST ?? "0.0.0.0",
     port: Number.parseInt(process.env.SPACE_WEB_PORT ?? "4911", 10),
+    // SPACE_API_ORIGIN lets `npm run dev:stack` point the dev proxy at its own
+    // API port; the default is the installed app's API on 4910, as before.
     proxy: {
-      "/api": "http://127.0.0.1:4910",
-      "/plugins": "http://127.0.0.1:4910",
-      "/healthz": "http://127.0.0.1:4910",
-      "/readyz": "http://127.0.0.1:4910",
-      "/version": "http://127.0.0.1:4910"
+      "/api": process.env.SPACE_API_ORIGIN ?? "http://127.0.0.1:4910",
+      "/plugins": process.env.SPACE_API_ORIGIN ?? "http://127.0.0.1:4910",
+      "/healthz": process.env.SPACE_API_ORIGIN ?? "http://127.0.0.1:4910",
+      "/readyz": process.env.SPACE_API_ORIGIN ?? "http://127.0.0.1:4910",
+      "/version": process.env.SPACE_API_ORIGIN ?? "http://127.0.0.1:4910"
     }
   },
   test: {

package.json

@@ -43,6 +43,7 @@
     "@napi-rs/canvas": "1.0.9"
   },
   "scripts": {
+    "dev:stack": "node scripts/dev-stack.mjs",
     "dev:api": "npm run dev -w @space/api",
     "dev:web": "npm run dev -w @space/web",
     "dev:worker": "npm run dev -w @space/worker",

scripts/dev-stack-ci.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * CI driver for the dev stack (.github/workflows/dev-stack.yml):
+ * start `npm run dev:stack` without a TTY, wait for /readyz, complete the
+ * owner setup over HTTP, ensure the starter room and its CLI pane exist,
+ * then run `reset` and verify nothing is left behind (no container, no
+ * volume, no state directory, no supervised process).
+ */
+import { spawn, execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { buildConfig } from "./dev-stack.mjs";
+
+const execFileAsync = promisify(execFile);
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const config = buildConfig();
+const webOrigin = `http://127.0.0.1:${config.webPort}`;
+const apiOrigin = `http://127.0.0.1:${config.apiPort}`;
+
+function step(message) {
+  process.stdout.write(`\n=== ${message}\n`);
+}
+
+async function sleep(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+async function waitForReadyz(timeoutMs = 300_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`${webOrigin}/readyz`);
+      const body = await response.json().catch(() => ({}));
+      if (body && body.ok === true) return body;
+    } catch { /* not up yet */ }
+    await sleep(3_000);
+  }
+  throw new Error(`dev stack did not become ready within ${timeoutMs}ms`);
+}
+
+async function main() {
+  step("Starting the dev stack (background, no TTY)");
+  const stack = spawn("npm", ["run", "dev:stack"], {
+    cwd: repoRoot,
+    env: process.env,
+    shell: process.platform === "win32",
+    detached: process.platform !== "win32",
+    stdio: "inherit"
+  });
+  let stackExit = null;
+  stack.on("exit", (code) => { stackExit = code; });
+
+  try {
+    step("Waiting for /readyz through the web port");
+    const ready = await waitForReadyz();
+    if (stackExit !== null) throw new Error(`dev stack exited early with code ${stackExit}`);
+    process.stdout.write(`readyz: ${JSON.stringify(ready)}\n`);
+
+    step("Completing owner setup over HTTP");
+    const setupToken = readFileSync(join(config.secretsDir, "setup-token"), "utf8").trim();
+    const claimResponse = await fetch(`${apiOrigin}/api/setup/claim`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        token: setupToken,
+        email: "dev-stack-ci@example.com",
+        password: "dev-stack-ci-password-1"
+      })
+    });
+    if (!claimResponse.ok) {
+      throw new Error(`Owner claim failed: ${claimResponse.status} ${await claimResponse.text()}`);
+    }
+    const claim = await claimResponse.json();
+    const cookie = claimResponse.headers.get("set-cookie");
+    if (!cookie) throw new Error("Owner claim did not return a session cookie.");
+    const authHeaders = { cookie, "content-type": "application/json" };
+    process.stdout.write(`Owner claimed; starter room: ${claim.starterRoomId}\n`);
+
+    step("Ensuring the starter room and its CLI pane");
+    const starterResponse = await fetch(`${apiOrigin}/api/setup/starter-room`, {
+      method: "POST",
+      headers: authHeaders,
+      body: "{}"
+    });
+    if (!starterResponse.ok) {
+      throw new Error(`Starter room failed: ${starterResponse.status} ${await starterResponse.text()}`);
+    }
+    const starter = await starterResponse.json();
+    const roomId = starter.room?.id ?? claim.starterRoomId;
+    const roomResponse = await fetch(`${apiOrigin}/api/rooms/${roomId}`, { headers: authHeaders });
+    if (!roomResponse.ok) {
+      throw new Error(`Room fetch failed: ${roomResponse.status} ${await roomResponse.text()}`);
+    }
+    const room = await roomResponse.json();
+    const panes = room.panes ?? room.room?.panes ?? [];
+    const cliPane = panes.find((pane) => pane.mode === "TERMINAL" || pane.terminalRuntimeId);
+    if (!cliPane) {
+      throw new Error(`Starter room ${roomId} has no CLI pane. Panes: ${JSON.stringify(panes).slice(0, 500)}`);
+    }
+    process.stdout.write(`CLI pane present: ${cliPane.id} (mode ${cliPane.mode ?? "?"}, runtime ${cliPane.terminalRuntimeId ?? "?"})\n`);
+
+    const tasksResponse = await fetch(`${apiOrigin}/api/cli/tasks`, { headers: authHeaders });
+    if (!tasksResponse.ok) {
+      throw new Error(`CLI tasks endpoint failed: ${tasksResponse.status}`);
+    }
+    process.stdout.write("CLI host answers through the API.\n");
+  } finally {
+    step("Resetting the dev stack and verifying nothing is left");
+    try { process.kill(process.platform === "win32" ? stack.pid : -stack.pid, "SIGTERM"); } catch { /* already down */ }
+    await sleep(2_000);
+    const reset = spawn("npm", ["run", "dev:stack", "--", "reset"], {
+      cwd: repoRoot, env: process.env, shell: process.platform === "win32", stdio: "inherit"
+    });
+    await new Promise((resolvePromise) => reset.on("exit", resolvePromise));
+
+    const { stdout: containers } = await execFileAsync("docker", ["ps", "-aq", "--filter", "name=spaceapp-dev"]).catch(() => ({ stdout: "" }));
+    if (containers.trim().length > 0) throw new Error(`Containers left behind: ${containers.trim()}`);
+    const { stdout: volumes } = await execFileAsync("docker", ["volume", "ls", "-q", "--filter", "name=spaceapp-dev"]).catch(() => ({ stdout: "" }));
+    if (volumes.trim().length > 0) throw new Error(`Volumes left behind: ${volumes.trim()}`);
+    if (existsSync(config.stateDir)) throw new Error(`State directory left behind: ${config.stateDir}`);
+    process.stdout.write("Reset verified: no container, volume, process or state left.\n");
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`dev-stack CI failed: ${error.message}\n`);
+  process.exit(1);
+});

scripts/dev-stack.compose.yml

@@ -0,0 +1,58 @@
+# Dev-stack services for `npm run dev:stack` (scripts/dev-stack.mjs).
+# Only PostgreSQL and Temporal run in Docker; everything else runs from source.
+# The ALL-CAPS placeholder tokens are substituted by scripts/dev-stack.mjs:
+# the images (with digests) are parsed out of
+# packages/run-spaceapp/templates/compose.yml so they are never copied by hand.
+name: spaceapp-dev
+
+services:
+  postgres:
+    image: __POSTGRES_IMAGE__
+    restart: "no"
+    environment:
+      POSTGRES_DB: spaceapp
+      POSTGRES_USER: spaceapp
+      POSTGRES_PASSWORD_FILE: /run/secrets/postgres-password
+    ports:
+      - "127.0.0.1:__POSTGRES_PORT__:5432"
+    volumes:
+      - spaceapp-dev-postgres:/var/lib/postgresql/data
+    secrets:
+      - postgres-password
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U spaceapp -d spaceapp"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  temporal:
+    image: __TEMPORAL_IMAGE__
+    restart: "no"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      DB: postgres12
+      DB_PORT: 5432
+      POSTGRES_USER: spaceapp
+      POSTGRES_SEEDS: postgres
+      DYNAMIC_CONFIG_FILE_PATH: config/dynamicconfig/docker.yaml
+    entrypoint: ["/bin/sh", "-ec"]
+    command:
+      - export POSTGRES_PWD="$$(cat /run/secrets/postgres-password)"; exec /etc/temporal/entrypoint.sh autosetup
+    ports:
+      - "127.0.0.1:__TEMPORAL_PORT__:7233"
+    secrets:
+      - postgres-password
+    healthcheck:
+      test: ["CMD-SHELL", "temporal operator cluster health --address temporal:7233 >/dev/null && temporal operator namespace describe --namespace default --address temporal:7233 >/dev/null"]
+      interval: 10s
+      timeout: 5s
+      retries: 20
+
+secrets:
+  postgres-password:
+    file: __SECRETS_DIR__/postgres-password
+
+volumes:
+  spaceapp-dev-postgres: