feat(dev): add npm run dev:stack one-command source stack (#65)

.gitignore

@@ -52,3 +52,6 @@ projects/
 .local/
 
 run-spaceapp-*.tgz
+
+# Dev stack state directory (git-ignored, per-developer local state)
+.dev-stack/

CONTRIBUTING.md

@@ -50,6 +50,46 @@ select a short temporary directory you own and set `TMPDIR` for the command.
 On Windows run this particular smoke check inside WSL or a Linux development
 container. It does not certify the Windows/macOS installer.
 
+## Run the full app from source
+
+After `npm ci`, one command starts a complete SpaceApp from source with hot reload:
+
+```sh
+npm run dev:stack
+```
+
+This starts PostgreSQL (pgvector) and Temporal in Docker, runs database migrations,
+then starts the API (watch mode), Vite web dev server, Temporal worker, and CLI
+host from source. All services bind to `127.0.0.1` only.
+
+State lives in `.dev-stack/` (git-ignored), so an installed SpaceApp is never
+disturbed. Ports and directories can be overridden through environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `SPACEAPP_DEV_API_PORT` | 4910 | API port |
+| `SPACEAPP_DEV_WEB_PORT` | 4911 | Web dev server port |
+| `SPACEAPP_DEV_POSTGRES_PORT` | 5432 | PostgreSQL port |
+| `SPACEAPP_DEV_TEMPORAL_PORT` | 7233 | Temporal port |
+| `SPACEAPP_DEV_BIND_HOST` | 127.0.0.1 | Bind host for all services |
+
+When the API `/readyz` endpoint reports ok, the command prints the URL and a
+one-time owner setup token. Open the URL, create the owner, then start an
+OpenCode pane through the Getting Started room.
+
+Hot reload: a change in `apps/api/src` restarts the API, a change in
+`apps/web/src` hot-reloads in the browser. Internal `@space/*` packages must
+be built before starting the stack (`npm run build`); changes to package code
+require rebuilding, since dev:stack starts no package watcher.
+
+```sh
+npm run dev:stack -- down    # stop all services
+npm run dev:stack -- reset   # stop and remove the state directory
+```
+
+Docker is required for PostgreSQL and Temporal. Linux is the reference
+development environment; Windows contributors can use WSL.
+
 ## Make and verify a small change
 
 Work on a branch, not on `main`, so the change can become a pull request:

apps/api/src/__tests__/trace-context.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { childTraceparent, createRequestTraceContext, requestTraceContexts, traceparentForTraceId, withTurnTraceparent, workflowCorrelationMemo } from "../trace-context.js";
+import { parseTraceparent } from "@space/contracts";
+
+describe("trace context propagation", () => {
+  it("creates a W3C trace context from scratch", () => {
+    const context = createRequestTraceContext(undefined);
+    expect(context.w3cTraceId).toMatch(/^[0-9a-f]{32}$/);
+    expect(context.spanId).toMatch(/^[0-9a-f]{16}$/);
+    expect(context.parentSpanId).toBeNull();
+    expect(context.inbound).toBe(false);
+    expect(parseTraceparent(context.traceparent)).not.toBeNull();
+  });
+
+  it("creates a child traceparent sharing the trace id with new span", () => {
+    const context = createRequestTraceContext(undefined);
+    const child = childTraceparent(context.traceparent);
+    expect(child).not.toBeNull();
+    const parsed = parseTraceparent(child!);
+    expect(parsed!.traceId).toBe(context.w3cTraceId);
+    expect(parsed!.parentId).not.toBe(context.spanId);
+  });
+
+  it("traceparentForTraceId returns null for unknown request id", () => {
+    expect(traceparentForTraceId("req:unknown")).toBeNull();
+  });
+
+  it("traceparentForTraceId returns child traceparent for known request id", () => {
+    const context = createRequestTraceContext(undefined);
+    requestTraceContexts.remember("req:test-1", context);
+    const child = traceparentForTraceId("req:test-1");
+    expect(child).not.toBeNull();
+    const parsed = parseTraceparent(child!);
+    expect(parsed!.traceId).toBe(context.w3cTraceId);
+    expect(parsed!.parentId).not.toBe(context.spanId);
+  });
+
+  it("workflowCorrelationMemo encodes traceId and traceparent", () => {
+    const context = createRequestTraceContext(undefined);
+    const memo = workflowCorrelationMemo({ traceId: "req:test-1", traceparent: context.traceparent });
+    expect(memo.spaceTraceId).toBe("req:test-1");
+    expect(memo.traceparent).toBe(context.traceparent);
+    expect(memo.w3cTraceId).toBe(context.w3cTraceId);
+  });
+
+  it("workflowCorrelationMemo omits unset fields", () => {
+    const memo = workflowCorrelationMemo({ traceId: null });
+    expect(memo.spaceTraceId).toBeUndefined();
+    expect(memo.traceparent).toBeUndefined();
+    expect(memo.w3cTraceId).toBeUndefined();
+  });
+
+  it("workflowCorrelationMemo filters invalid traceId", () => {
+    const memo = workflowCorrelationMemo({ traceId: "invalid id with spaces" });
+    expect(memo.spaceTraceId).toBeUndefined();
+  });
+
+  it("withTurnTraceparent adds traceparent when missing", () => {
+    const context = createRequestTraceContext(undefined);
+    requestTraceContexts.remember("req:test-2", context);
+    const turn = { traceId: "req:test-2" };
+    const result = withTurnTraceparent(turn);
+    const parsed = parseTraceparent(result.traceparent!);
+    expect(parsed!.traceId).toBe(context.w3cTraceId);
+    expect(parsed!.parentId).not.toBe(context.spanId);
+  });
+
+  it("withTurnTraceparent keeps existing valid traceparent", () => {
+    const context = createRequestTraceContext(undefined);
+    const turn = { traceId: "req:any", traceparent: context.traceparent };
+    const result = withTurnTraceparent(turn);
+    expect(result.traceparent).toBe(context.traceparent);
+  });
+});

apps/api/src/dot-goals.ts

@@ -16,6 +16,7 @@ import {
 } from "@space/contracts";
 import { SpaceConflictError, SpaceNotFoundError, type SpaceStore } from "@space/runtime";
 import type { DotGoalsRepository, DotsRepository } from "@space/db";
+import { traceparentForTraceId, workflowCorrelationMemo } from "./trace-context.js";
 
 /**
  * Space Dots Stage 4: Goals.
@@ -26,10 +27,10 @@ import type { DotGoalsRepository, DotsRepository } from "@space/db";
  * blocking question, cancellation, three consecutive failures or the budget.
  */
 export interface DotGoalWorkflowCoordinator {
-  start(goalId: string): Promise<void>;
-  wake(goalId: string): Promise<void>;
+  start(goalId: string, traceId?: string | null, traceparent?: string | null): Promise<void>;
+  wake(goalId: string, traceId?: string | null, traceparent?: string | null): Promise<void>;
   /** Starts the Goal's workflow when none is running; true when it had to start one. */
-  ensure?(goalId: string): Promise<boolean>;
+  ensure?(goalId: string, traceId?: string | null, traceparent?: string | null): Promise<boolean>;
 }
 export class TemporalDotGoalWorkflowCoordinator implements DotGoalWorkflowCoordinator {
   constructor(private readonly options: { address: string; namespace: string; taskQueue: string }) {}
@@ -38,25 +39,27 @@ export class TemporalDotGoalWorkflowCoordinator implements DotGoalWorkflowCoordi
     try { return await action(new Client({ connection, namespace: this.options.namespace })); }
     finally { await connection.close(); }
   }
-  start(goalId: string) {
+  start(goalId: string, traceId?: string | null, traceparent?: string | null) {
     return this.client(async (client) => {
       try {
         await client.workflow.start("dotGoalWorkflow", { workflowId: dotGoalWorkflowId(goalId), taskQueue: this.options.taskQueue,
-          args: [{ goalId }], workflowIdReusePolicy: "REJECT_DUPLICATE" });
+          args: [{ goalId, traceparent }], workflowIdReusePolicy: "REJECT_DUPLICATE",
+          memo: workflowCorrelationMemo({ traceId, traceparent }) });
       } catch (error) { if (!(error instanceof WorkflowExecutionAlreadyStartedError)) throw error; }
     });
   }
-  wake(goalId: string) {
+  wake(goalId: string, traceId?: string | null, traceparent?: string | null) {
     return this.client(async (client) => {
-      try { await client.workflow.getHandle(dotGoalWorkflowId(goalId)).signal(DOT_GOAL_SIGNAL); }
+      try { await client.workflow.getHandle(dotGoalWorkflowId(goalId)).signal(DOT_GOAL_SIGNAL, { traceId, traceparent }); }
       catch (error) { if (!(error instanceof WorkflowNotFoundError)) throw error; }
     });
   }
-  ensure(goalId: string) {
+  ensure(goalId: string, traceId?: string | null, traceparent?: string | null) {
     return this.client(async (client) => {
       try {
         await client.workflow.start("dotGoalWorkflow", { workflowId: dotGoalWorkflowId(goalId), taskQueue: this.options.taskQueue,
-          args: [{ goalId }], workflowIdReusePolicy: "ALLOW_DUPLICATE" });
+          args: [{ goalId, traceparent }], workflowIdReusePolicy: "ALLOW_DUPLICATE",
+          memo: workflowCorrelationMemo({ traceId, traceparent }) });
         return true;
       } catch (error) {
         if (error instanceof WorkflowExecutionAlreadyStartedError) return false;
@@ -125,7 +128,7 @@ export function createDotGoalService(deps: DotGoalServiceDeps) {
       if ((error as { code?: string }).code === "DOT_GOAL_OPEN") throw new DotGoalError(409, "DOT_GOAL_OPEN", "This conversation already has an open Goal.");
       throw error;
     }
-    try { await deps.workflow.start(goal.goalId); }
+    try { await deps.workflow.start(goal.goalId, request?.id ?? null, traceparentForTraceId(request?.id)); }
     catch {
       goal = await finish(goal, "FAILED", "The Goal runtime could not start. Try again.");
       throw new DotGoalError(503, "DOT_GOAL_RUNTIME", "The Goal runtime could not start. Try again.");
@@ -147,7 +150,7 @@ export function createDotGoalService(deps: DotGoalServiceDeps) {
       const run = session ? await deps.store.getLatestSpaceAgentRun(session.sessionId) : null;
       if (session && run && (run.status === "QUEUED" || run.status === "RUNNING")) await deps.interrupt(session.paneId, "Goal cancelled by the user.").catch(() => undefined);
     }
-    await deps.workflow?.wake(goalId).catch(() => undefined);
+    await deps.workflow?.wake(goalId, request?.id ?? null, traceparentForTraceId(request?.id)).catch(() => undefined);
     await deps.audit(request, "dot.goal.control", goal.roomId, { dotId, goalId, action });
     return next;
   }
@@ -158,7 +161,7 @@ export function createDotGoalService(deps: DotGoalServiceDeps) {
     if (!goal) throw new DotGoalError(404, "DOT_GOAL_NOT_FOUND", "Goal was not found.");
     const next = await deps.goals.addSteering(goalId, text);
     if (!next) throw new DotGoalError(409, "DOT_GOAL_STATE", "Guidance can be added only to an open Goal, up to 50 notes.");
-    await deps.workflow?.wake(goalId).catch(() => undefined);
+    await deps.workflow?.wake(goalId, request?.id ?? null, traceparentForTraceId(request?.id)).catch(() => undefined);
     await deps.audit(request, "dot.goal.steer", goal.roomId, { dotId, goalId });
     return next;
   }

apps/worker/package.json

@@ -10,7 +10,8 @@
     "start": "node dist/worker.js",
     "build": "tsc -p tsconfig.json",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "temporal:record-histories": "node ./scripts/record-workflow-histories.mjs"
   },
   "dependencies": {
     "@space/codex-app-server": "0.2.5",
@@ -26,6 +27,8 @@
     "undici": "8.10.2"
   },
   "devDependencies": {
+    "@temporalio/proto": "1.24.0",
+    "@temporalio/testing": "1.24.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.12"
   },