Service: job event stream, async in-memory backend, preview routes

Ported from PR #15 (packages-side surface only; the fork's dev UI page is
intentionally dropped - the API surface is the product):
- job_events table + repository, worker emits stage transitions, additive
  GET /v1/clones/:id/events polling route. The fork's hand-written
  migration was never registered in Drizzle's journal (it silently never
  applied); regenerated properly via drizzle-kit from schema.ts with the
  (job_id, seq) index declared, and verified against a live Postgres
- In-memory backend moves to the documented enqueue-202 + poll contract
  with single-flight BUSY guard; POST honors backend httpStatus
- app-preview static serving routes; the preview BUILD half is deferred
  until the compiler exports buildApp/DEFAULT_HARNESS_DIR - routes 404
  cleanly until then
- preview option threaded through core types; cache key intentionally
  unchanged while the flag is inert

All workspaces typecheck; api 18/18, core 13/13, worker 1/1 pass;
migration verified applying (table + index + FK) on postgres:16.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

packages/api/src/app.ts

@@ -15,6 +15,7 @@ const OptionsSchema = z
     mode: z.enum(["single", "multi"]).optional(),
     styling: z.enum(["tailwind", "css"]).optional(),
     framework: z.enum(["next", "vite"]).optional(),
+    preview: z.boolean().optional(),
     verify: z.boolean().optional(),
     asyncVerify: z.boolean().optional(),
     maxRoutes: z.number().int().positive().optional(),
@@ -238,10 +239,12 @@ export function createApp(deps: AppDeps): Hono {
 
     try {
       const out = await backend.submit(url, opts);
-      if (out.status === "queued") return c.json({ jobId: out.jobId, status: "queued" }, 202);
+      if (out.status === "queued") return c.json({ jobId: out.jobId, status: "queued" }, out.httpStatus);
       return c.json(out.result, 200);
     } catch (e) {
-      return c.json({ status: "failed", error: String(e).slice(0, 500) }, 500);
+      const msg = String(e);
+      if (msg.startsWith("BUSY:")) return c.json({ error: msg.slice(5).trim() }, 429);
+      return c.json({ status: "failed", error: msg.slice(0, 500) }, 500);
     }
   });
 
@@ -282,6 +285,40 @@ export function createApp(deps: AppDeps): Hono {
     return c.body(file.bytes);
   });
 
+  // Pipeline progress events (poll every ~300ms while a clone runs).
+  app.get("/v1/clones/:id/events", async (c) => {
+    const after = Math.max(0, Number(c.req.query("after") ?? "0") || 0);
+    const events = backend.events ? await backend.events(c.req.param("id"), after) : null;
+    if (!events) return c.json({ error: "not found" }, 404);
+    return c.json({ jobId: c.req.param("id"), events });
+  });
+
+  // Browsable preview of the built clone (static export published by the preview
+  // build under public/app-preview/). References are relative, so the export works
+  // from this mount — the only requirement is a trailing slash on the root.
+  const previewFile = async (c: Context, sub: string) => {
+    const id = c.req.param("id") ?? "";
+    const tryPaths = sub.includes(".")
+      ? [`public/app-preview/${sub}`]
+      : [
+          `public/app-preview/${sub}`.replace(/\/$/, "") + "/index.html",
+          `public/app-preview/${sub}`,
+          `public/app-preview/${sub}.html`,
+        ];
+    for (const p of tryPaths) {
+      const file = await backend.file(id, p);
+      if (file) {
+        c.header("content-type", file.contentType);
+        c.header("content-length", String(file.bytes.length));
+        return c.body(file.bytes);
+      }
+    }
+    return c.json({ error: "no app preview for this clone (preview builds are on by default for single-page clones; pass options.preview=true otherwise)" }, 404);
+  };
+  app.get("/v1/clones/:id/app-preview", (c) => c.redirect(`/v1/clones/${c.req.param("id")}/app-preview/`, 302));
+  app.get("/v1/clones/:id/app-preview/", (c) => previewFile(c, "index.html"));
+  app.get("/v1/clones/:id/app-preview/:path{.+}", (c) => previewFile(c, c.req.param("path") ?? ""));
+
   app.delete("/v1/clones/:id", async (c) => {
     const ok = await backend.remove(c.req.param("id"));
     return c.json({ deleted: ok }, ok ? 200 : 404);

packages/api/src/backend.ts

@@ -1,5 +1,5 @@
 import type { CloneOptions, RouteInfo } from "@cloner/core";
-import type { RestCloneResult } from "./rest.js";
+import type { RestCloneResult, RestCloneSummary } from "./rest.js";
 
 export type JobStatus = "queued" | "running" | "succeeded" | "failed" | "cached";
 
@@ -22,7 +22,7 @@ export type JobView = {
 };
 
 export type SubmitOutcome =
-  | { jobId: string; status: "succeeded" | "cached"; httpStatus: 200; result: RestCloneResult }
+  | { jobId: string; status: "succeeded" | "cached"; httpStatus: 200; result: RestCloneResult | RestCloneSummary }
   | { jobId: string; status: "queued"; httpStatus: 202 };
 
 export type ResultOutcome =
@@ -56,4 +56,6 @@ export interface Backend {
   facets(jobId: string): Promise<FileFacet[] | null>;
   /** The whole app as one compressed archive (null if not ready/found). */
   bundle(jobId: string, format?: BundleFormat): Promise<CloneBundle | null>;
+  /** Pipeline progress events for polling UIs (null if unsupported or job unknown). */
+  events?(jobId: string, after?: number): Promise<Array<Record<string, unknown>> | null>;
 }

packages/api/src/backends/db.ts

@@ -142,4 +142,10 @@ export class DbBackend implements Backend {
     const url = this.deps.store.uploadBundle ? await this.deps.store.uploadBundle(jobId, format, bytes) : undefined;
     return { bytes, sha256: sha256hex(bytes), format, url };
   }
+
+  async events(jobId: string, after = 0): Promise<Array<Record<string, unknown>> | null> {
+    const job = await repo.getJob(this.deps.db, jobId);
+    if (!job) return null;
+    return repo.listJobEvents(this.deps.db, jobId, after);
+  }
 }

packages/api/src/backends/inMemory.ts

@@ -10,24 +10,51 @@ import type { Backend, BundleFormat, CloneBundle, FileFacet, JobView, ResultOutc
 
 export type RunJob = (input: RunCloneJobInput) => Promise<CloneJobResult>;
 
-/** Sync, in-memory backend (M1): runs the clone INLINE on submit and holds results
- *  in memory. POST returns the file map immediately (200). */
+/** In-memory backend: enqueues a clone (202) and runs it in the background so long
+ *  captures (multi-viewport + verify) never hold a single HTTP connection open for
+ *  minutes — which browsers surface as `TypeError: Failed to fetch` when the link
+ *  drops (server restart, hot-reload, idle timeout). Poll /v1/clones/:id + /events. */
 export class InMemoryBackend implements Backend {
   constructor(private deps: { store: InMemoryStore; runJob: RunJob; makeTempBase?: () => string; captureCacheDir?: string }) {}
 
+  private activeClones = 0;
+
   private makeBase(): string {
     return (this.deps.makeTempBase ?? (() => mkdtempSync(join(tmpdir(), "api-clone-"))))();
   }
 
   async submit(url: string, options: CloneOptions | undefined): Promise<SubmitOutcome> {
+    if (this.activeClones > 0 || this.deps.store.list().some((j) => j.status === "running")) {
+      throw new Error("BUSY: another clone is already running — wait for it to finish (use npm run dev:api:stable to avoid hot-reload killing Playwright)");
+    }
     const id = randomUUID();
     const base = this.makeBase();
+    const events: Array<Record<string, unknown>> = [];
+    const kind: "clone" | "clone_site" = resolveCloneMode(options) === "multi" ? "clone_site" : "clone";
+    const rec = { id, status: "running" as const, url, kind, options: options ?? {}, createdAt: Date.now(), base, events };
+    this.deps.store.put(rec);
+    void this.runInBackground(id, url, options, rec, base, events, kind);
+    return { jobId: id, status: "queued", httpStatus: 202 };
+  }
+
+  private async runInBackground(
+    id: string,
+    url: string,
+    options: CloneOptions | undefined,
+    rec: { id: string; status: "running"; url: string; kind: "clone" | "clone_site"; options: CloneOptions; createdAt: number; base: string; events: Array<Record<string, unknown>> },
+    base: string,
+    events: Array<Record<string, unknown>>,
+    kind: "clone" | "clone_site",
+  ): Promise<void> {
+    this.activeClones++;
+    const log = (e: Record<string, unknown>) => {
+      events.push({ t: Date.now(), ...e });
+      this.deps.store.put({ ...rec, events: [...events] });
+    };
     try {
-      // captureCacheDir (persistent, shared across submits) powers the single→multi
-      // reuse: a single-page submit stashes its capture; a later multi-page submit for
-      // the same URL reuses it as the entry route (no re-capture) and expands the site.
-      const result = await this.deps.runJob({ url, options, runsDir: base, captureCacheDir: this.deps.captureCacheDir });
-      this.deps.store.put({ id, status: "succeeded", url, kind: result.kind, options: result.options, createdAt: Date.now(), result, base });
+      const result = await this.deps.runJob({ url, options, runsDir: base, captureCacheDir: this.deps.captureCacheDir, log });
+      log({ event: "clone_done" });
+      this.deps.store.put({ id, status: "succeeded", url, kind: result.kind, options: result.options, createdAt: rec.createdAt, result, base, events });
       if (result.options.asyncVerify) {
         void verifyCloneJobResult(result, {
           validationConcurrency: result.options.validationConcurrency,
@@ -39,18 +66,25 @@ export class InMemoryBackend implements Backend {
           result.verify = { error: String(e).slice(0, 500), async: true };
         });
       }
-      return { jobId: id, status: "succeeded", httpStatus: 200, result: buildRestResult(id, result, `/v1/clones/${id}/files`) };
     } catch (e) {
       try {
         rmSync(base, { recursive: true, force: true });
       } catch {
         /* best effort */
       }
-      this.deps.store.put({ id, status: "failed", url, kind: resolveCloneMode(options) === "multi" ? "clone_site" : "clone", options: options ?? {}, createdAt: Date.now(), error: String(e) });
-      throw e;
+      log({ event: "clone_error", error: String(e).slice(0, 300) });
+      this.deps.store.put({ id, status: "failed", url, kind, options: options ?? {}, createdAt: rec.createdAt, error: String(e), events });
+    } finally {
+      this.activeClones = Math.max(0, this.activeClones - 1);
     }
   }
 
+  async events(jobId: string): Promise<Array<Record<string, unknown>> | null> {
+    const rec = this.deps.store.get(jobId);
+    if (!rec) return null;
+    return rec.events ?? [];
+  }
+
   async status(jobId: string): Promise<JobView | null> {
     const rec = this.deps.store.get(jobId);
     if (!rec) return null;

packages/api/src/store.ts

@@ -6,7 +6,7 @@ import type { CloneJobResult, CloneOptions } from "@cloner/core";
  *  it is removed on eviction. M2/M4 replace this with DB rows + S3 objects. */
 export type JobRecord = {
   id: string;
-  status: "succeeded" | "failed";
+  status: "running" | "succeeded" | "failed";
   url: string;
   kind: "clone" | "clone_site";
   options: CloneOptions;
@@ -14,6 +14,8 @@ export type JobRecord = {
   result?: CloneJobResult;
   base?: string;
   error?: string;
+  /** pipeline progress events (compiler log stream + service phases), poll via /events */
+  events?: Array<Record<string, unknown>>;
 };
 
 /** In-memory result store with TTL eviction. Swapped for a DB-backed store in M2. */