feat: set up a project on add (scaffold + analyze with Claude), observably

Adding a repo that has no .webmux.yaml now runs setup automatically instead
of registering an unconfigured project: scaffold a starter .webmux.yaml →
analyze the repo with Claude to fill it in → register. Each phase is surfaced
in the dashboard and the CLI ("Creating .webmux.yaml" → "Analyzing project
structure with Claude" → ready).

Backend:
- ProjectInitTracker + runProjectInit (services/project-init-service.ts):
  hub-level, keyed by repo path; phases creating_config → analyzing → ready,
  or failed. Analysis is best-effort (skipped if no agent on PATH, non-fatal
  on error) so the starter config always ships. Terminal states TTL-expire.
- apiAddProject: repos with config (or already served) register immediately;
  repos without kick off the async job and return { initializing: true }.
  New GET /api/projects/init reports progress. The setup uses the lifted
  init-authoring helpers with a timeout so a hung agent can't stall it.

Contract: AddProjectResponse ({ initializing, path, project }), ProjectInit
phase/state schemas, and the projectInits endpoint.

Frontend: setUpProject() POSTs then polls projectInits, reporting phases;
EmptyProjects + ProjectSwitcher show the steps and open the project when ready.

CLI: `webmux project add` on an unconfigured repo prints the same phases via a
DI-seamed awaitProjectSetup(), then the added line. Parity with the UI.

Tests cover the tracker, orchestration (skip/best-effort/failure), and the CLI
poller; init-authoring gains a run timeout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hugocasa

backend/src/__tests__/project-init-service.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "bun:test";
+import {
+  ProjectInitTracker,
+  runProjectInit,
+  type ProjectInitDeps,
+} from "../services/project-init-service";
+
+describe("ProjectInitTracker", () => {
+  it("upserts phase transitions and carries prefix/name into ready", () => {
+    const tracker = new ProjectInitTracker();
+    tracker.set("/repo/a", { phase: "creating_config" });
+    expect(tracker.isActive("/repo/a")).toBe(true);
+
+    tracker.set("/repo/a", { phase: "analyzing" });
+    tracker.set("/repo/a", { phase: "ready", prefix: "a", name: "A" });
+
+    const state = tracker.get("/repo/a");
+    expect(state).toMatchObject({ phase: "ready", prefix: "a", name: "A", error: null });
+    expect(tracker.isActive("/repo/a")).toBe(false);
+  });
+
+  it("evicts terminal entries past the TTL but keeps in-flight ones", () => {
+    let clock = 1000;
+    const tracker = new ProjectInitTracker({ ttlMs: 100, now: () => clock });
+
+    tracker.set("/repo/done", { phase: "ready", prefix: "done", name: "Done" });
+    tracker.set("/repo/busy", { phase: "analyzing" });
+
+    clock = 1050; // within TTL — both visible
+    expect(tracker.list().map((s) => s.path).sort()).toEqual(["/repo/busy", "/repo/done"]);
+
+    clock = 1200; // terminal entry now past TTL; in-flight stays
+    expect(tracker.list().map((s) => s.path)).toEqual(["/repo/busy"]);
+  });
+});
+
+function makeDeps(overrides: Partial<ProjectInitDeps> & { calls?: string[] } = {}): ProjectInitDeps {
+  const calls = overrides.calls ?? [];
+  return {
+    analyzerAvailable: overrides.analyzerAvailable ?? ((): boolean => true),
+    scaffold: overrides.scaffold ?? (async (): Promise<void> => { calls.push("scaffold"); }),
+    analyze: overrides.analyze ?? (async (): Promise<void> => { calls.push("analyze"); }),
+    register: overrides.register ?? ((): { prefix: string; name: string } => {
+      calls.push("register");
+      return { prefix: "a", name: "A" };
+    }),
+  };
+}
+
+describe("runProjectInit", () => {
+  it("scaffolds, analyzes, registers, then marks ready (in order)", async () => {
+    const calls: string[] = [];
+    const tracker = new ProjectInitTracker();
+    await runProjectInit(tracker, "/repo/a", makeDeps({ calls }));
+
+    expect(calls).toEqual(["scaffold", "analyze", "register"]);
+    expect(tracker.get("/repo/a")).toMatchObject({ phase: "ready", prefix: "a", name: "A" });
+  });
+
+  it("skips analysis when no analyzer is available but still registers", async () => {
+    const calls: string[] = [];
+    const tracker = new ProjectInitTracker();
+    await runProjectInit(tracker, "/repo/a", makeDeps({ calls, analyzerAvailable: () => false }));
+
+    expect(calls).toEqual(["scaffold", "register"]);
+    expect(tracker.get("/repo/a")?.phase).toBe("ready");
+  });
+
+  it("registers anyway when analysis throws (best-effort enrichment)", async () => {
+    const calls: string[] = [];
+    const tracker = new ProjectInitTracker();
+    await runProjectInit(tracker, "/repo/a", makeDeps({
+      calls,
+      analyze: async () => { throw new Error("claude blew up"); },
+    }));
+
+    expect(calls).toEqual(["scaffold", "register"]);
+    expect(tracker.get("/repo/a")?.phase).toBe("ready");
+  });
+
+  it("marks failed and does not register when scaffold throws", async () => {
+    const calls: string[] = [];
+    const tracker = new ProjectInitTracker();
+    await runProjectInit(tracker, "/repo/a", makeDeps({
+      calls,
+      scaffold: async () => { throw new Error("cannot write .webmux.yaml"); },
+    }));
+
+    expect(calls).toEqual([]);
+    expect(tracker.get("/repo/a")).toMatchObject({ phase: "failed", error: "cannot write .webmux.yaml" });
+  });
+});

backend/src/server.ts

@@ -54,6 +54,20 @@ import {
   type ProjectConfig,
 } from "./adapters/config";
 import { jsonResponse, errorResponse } from "./lib/http";
+import { which } from "./lib/shell";
+import {
+  buildInitAgentCommand,
+  buildInitPromptSpec,
+  buildStarterTemplate,
+  detectInitProjectContext,
+  runInitAgentCommand,
+  type InitAgent,
+} from "./services/init-authoring";
+import {
+  ProjectInitTracker,
+  runProjectInit,
+  type ProjectInitDeps,
+} from "./services/project-init-service";
 import { isRecord, isStringArray } from "./lib/type-guards";
 import { parseJsonBody, parseParams, parseQuery } from "./api-validation";
 import { hasRecentDashboardActivity, touchDashboardActivity } from "./services/dashboard-activity";
@@ -118,7 +132,7 @@ import { isValidBranchName, isValidWorktreeName } from "./domain/policies";
 import { createWebmuxRuntime, type WebmuxRuntime } from "./runtime";
 import { createInstanceRegistry, type InstanceEntry } from "./adapters/instance-registry";
 import { createProjectsRegistry } from "./adapters/projects-registry";
-import { ProjectManager, type ProjectLoopController } from "./services/project-manager";
+import { ProjectManager, type ManagedProject, type ProjectLoopController } from "./services/project-manager";
 
 const PORT = parseInt(Bun.env.PORT || "5111", 10);
 const STATIC_DIR = Bun.env.WEBMUX_STATIC_DIR || "";
@@ -2328,6 +2342,9 @@ const apps = new Map<string, ProjectApp>();
 // removed and track whether a project is currently being viewed (`active`).
 const openSockets = new Map<string, Set<ServerWebSocket<WsData>>>();
 const instanceRegistry = createInstanceRegistry();
+// Tracks on-add project setups (scaffold config → analyze with Claude → ready)
+// so the UI + CLI can show progress. Hub-level: one per machine, keyed by repo.
+const projectInitTracker = new ProjectInitTracker();
 let manager: ProjectManager;
 let server: Server<WsData>;
 let BOUND_PORT = 0;
@@ -2341,31 +2358,84 @@ async function catchingRoute(label: string, fn: () => Promise<Response>): Promis
   }
 }
 
+function toProjectSummary(p: ManagedProject): { prefix: string; name: string; path: string; active: boolean } {
+  return { prefix: p.prefix, name: p.entry.name, path: p.entry.path, active: p.active };
+}
+
 function apiListProjects(): Response {
-  return jsonResponse({
-    projects: manager.list().map((p) => ({
-      prefix: p.prefix,
-      name: p.entry.name,
-      path: p.entry.path,
-      active: p.active,
-    })),
-  });
+  return jsonResponse({ projects: manager.list().map(toProjectSummary) });
 }
 
+/** A repo is a webmux project once it has a config file. */
+function hasProjectConfig(root: string): boolean {
+  return existsSync(join(root, ".webmux.yaml")) || existsSync(join(root, ".webmux.local.yaml"));
+}
+
+/** Agent used to author config on setup: prefer Claude, fall back to Codex. */
+function authoringAgent(): InitAgent {
+  return which("claude") ? "claude" : "codex";
+}
+
+const ANALYZE_TIMEOUT_MS = 120_000;
+
+/** I/O for the on-add setup flow. The server is local, so it spawns the agent
+ *  with the repo as cwd to scaffold + flesh out `.webmux.yaml`, then registers. */
+const projectInitDeps: ProjectInitDeps = {
+  analyzerAvailable: () => which("claude") || which("codex"),
+  scaffold: async (root) => {
+    const context = detectInitProjectContext(root, authoringAgent());
+    await Bun.write(join(root, ".webmux.yaml"), buildStarterTemplate(context));
+  },
+  analyze: async (root) => {
+    const agent = authoringAgent();
+    const spec = buildInitAgentCommand(agent, buildInitPromptSpec(detectInitProjectContext(root, agent)));
+    await runInitAgentCommand(spec, root, { timeoutMs: ANALYZE_TIMEOUT_MS });
+  },
+  register: (root) => {
+    const project = manager.add(root);
+    reloadRoutes();
+    return { prefix: project.prefix, name: project.entry.name };
+  },
+};
+
 async function apiAddProject(req: BunRequest): Promise<Response> {
   const body: unknown = await req.json().catch(() => null);
   if (!isRecord(body) || typeof body.path !== "string" || body.path.trim() === "") {
     return errorResponse("Request body must be { path: string }", 400);
   }
   const inputPath = body.path.trim();
   if (!isGitRepo(inputPath)) return errorResponse(`Not a git repository: ${inputPath}`, 400);
-  const project = manager.add(inputPath);
-  reloadRoutes();
+  const root = projectRoot(inputPath);
+
+  // Already served, or already a webmux project → register now, no setup job.
+  const existing = manager.getByPath(root);
+  if (existing) {
+    return jsonResponse({ initializing: false, path: root, project: toProjectSummary(existing) });
+  }
+  if (hasProjectConfig(root)) {
+    const project = manager.add(root);
+    reloadRoutes();
+    return jsonResponse({ initializing: false, path: root, project: toProjectSummary(project) });
+  }
+
+  // No config → scaffold + analyze + register asynchronously; the client polls
+  // `projectInits` for progress and the resulting prefix.
+  if (!projectInitTracker.isActive(root)) {
+    projectInitTracker.set(root, { phase: "creating_config" });
+    void runProjectInit(projectInitTracker, root, projectInitDeps);
+  }
+  return jsonResponse({ initializing: true, path: root, project: null });
+}
+
+function apiListProjectInits(): Response {
   return jsonResponse({
-    prefix: project.prefix,
-    name: project.entry.name,
-    path: project.entry.path,
-    active: project.active,
+    inits: projectInitTracker.list().map((s) => ({
+      path: s.path,
+      phase: s.phase,
+      prefix: s.prefix,
+      name: s.name,
+      error: s.error,
+    })),
   });
 }
 
@@ -2455,6 +2525,9 @@ function buildServeRoutes(): ProjectRoutes {
       GET: () => apiListProjects(),
       POST: (req) => catchingRoute("POST /api/projects", () => apiAddProject(req)),
     },
+    [apiPaths.projectInits]: {
+      GET: () => apiListProjectInits(),
+    },
     [apiPaths.migrateProjects]: {
       POST: (req) => catchingRoute("POST /api/projects/migrate", () => apiMigrateProjects(req)),
     },

backend/src/services/init-authoring.ts

@@ -41,6 +41,9 @@ export interface InitAgentRunResult {
 
 export interface InitAgentRunHandlers {
   onEvent?: (event: InitAgentStreamEvent) => void;
+  /** Kill the agent if it runs longer than this (ms). Used server-side so a
+   *  hung analysis can't stall project setup forever. */
+  timeoutMs?: number;
 }
 
 interface InitAgentStreamState {
@@ -506,11 +509,31 @@ export async function runInitAgentCommand(
     stderr: "pipe",
   });
 
-  const [exitCode, stdoutResult, stderr] = await Promise.all([
-    proc.exited,
-    consumeStructuredStream(proc.stdout, spec.agent, handlers.onEvent),
-    consumeRawStream(proc.stderr),
-  ]);
+  const timeout = handlers.timeoutMs
+    ? setTimeout(() => {
+        try { proc.kill(); } catch { /* already exited */ }
+      }, handlers.timeoutMs)
+    : null;
+
+  try {
+    const [exitCode, stdoutResult, stderr] = await Promise.all([
+      proc.exited,
+      consumeStructuredStream(proc.stdout, spec.agent, handlers.onEvent),
+      consumeRawStream(proc.stderr),
+    ]);
+
+    return finalizeAgentRun(spec, exitCode, stdoutResult, stderr);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+function finalizeAgentRun(
+  spec: InitAgentCommandSpec,
+  exitCode: number,
+  stdoutResult: { raw: string; assistantText: string },
+  stderr: string,
+): InitAgentRunResult {
 
   let summary = stdoutResult.assistantText.trim();
   if (spec.summaryPath && existsSync(spec.summaryPath)) {