@specship/specship 0.11.0

package/dist/server/routes/status.js

@@ -0,0 +1,112 @@
+/**
+ * GET /api/status — backend, journal mode, node/edge counts, drift count,
+ * last index time. Drives the UI's persistent status strip.
+ *
+ * POST /api/refresh — force-sync the SpecShip index AND trigger an
+ * immediate Claude Code transcript re-ingest. Wired to the global
+ * refresh button in the dashboard's status strip so users can pull
+ * Sessions / Heatmap / Costs / Memory current without waiting on the
+ * watcher's debounce.
+ *
+ * Project-scoped: accepts `?project=<slug>` and serves the matching
+ * SpecShip instance from the registry. When no project is selectable
+ * (no `?project=`, no primary), returns a 409 with `code: 'no_project'`
+ * so the UI can show the picker without blowing up.
+ */
+export async function registerStatusRoutes(app) {
+    app.get('/api/status', async (req, reply) => {
+        const cg = await app.activeCg(req);
+        if (!cg) {
+            return reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+        }
+        const stats = cg.getStats();
+        const lastIndexed = cg.getLastIndexedAt();
+        const drift = cg
+            .getSpecQueries()
+            .getLinksByState(['drifted', 'broken', 'orphaned']).length;
+        return {
+            projectPath: cg.getProjectRoot ? cg.getProjectRoot() : '',
+            backend: cg.getBackend(),
+            journalMode: cg.getJournalMode(),
+            nodeCount: stats.nodeCount,
+            edgeCount: stats.edgeCount,
+            fileCount: stats.fileCount,
+            drift,
+            lastIndexed: lastIndexed != null ? new Date(lastIndexed).toISOString() : null,
+            nodesByKind: stats.nodesByKind,
+            filesByLanguage: stats.filesByLanguage,
+            dbSizeBytes: stats.dbSizeBytes,
+        };
+    });
+    /**
+     * Force a synchronous re-sync of the project's SpecShip index AND a
+     * fresh Claude Code transcript ingest pass. The status strip's
+     * refresh button calls this so users can pull every project-scoped
+     * surface (Sessions, Heatmap, Costs, Memory, Drift, Graph) to
+     * current without waiting on the JSONL watcher's debounce window or
+     * the next file-watcher tick.
+     *
+     * Returns the same shape as GET /api/status (so the UI can update
+     * its strip and `lastIndexed` label in one round-trip) plus the
+     * ingest stats for surfaces interested in "how many new sessions
+     * landed."
+     *
+     * Both steps run sequentially. Errors in either are surfaced under
+     * `syncError` / `ingestError` so a transient ingest hiccup doesn't
+     * mask a successful index sync (or vice versa) — and the UI can
+     * decide whether to retry or surface the failure.
+     */
+    app.post('/api/refresh', async (req, reply) => {
+        const cg = await app.activeCg(req);
+        if (!cg) {
+            return reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+        }
+        let syncError = null;
+        let ingestError = null;
+        let ingestStats = null;
+        // 1. Re-index the project. Picks up code AND specs/ changes the
+        //    auto-sync hook may not have caught yet.
+        try {
+            await cg.sync();
+        }
+        catch (e) {
+            syncError = e instanceof Error ? e.message : String(e);
+        }
+        // 2. Re-ingest Claude Code transcripts. Skipped silently when the
+        //    server was booted with `--no-ingest` (app.watcher == null).
+        if (app.watcher) {
+            try {
+                ingestStats = await app.watcher.ingestNow();
+            }
+            catch (e) {
+                ingestError = e instanceof Error ? e.message : String(e);
+            }
+        }
+        // 3. Echo the new status so the UI updates its strip + lastIndexed
+        //    label without a separate GET.
+        const stats = cg.getStats();
+        const lastIndexed = cg.getLastIndexedAt();
+        const drift = cg
+            .getSpecQueries()
+            .getLinksByState(['drifted', 'broken', 'orphaned']).length;
+        return {
+            ok: syncError === null && ingestError === null,
+            syncError,
+            ingestError,
+            ingestStats,
+            status: {
+                projectPath: cg.getProjectRoot ? cg.getProjectRoot() : '',
+                backend: cg.getBackend(),
+                journalMode: cg.getJournalMode(),
+                nodeCount: stats.nodeCount,
+                edgeCount: stats.edgeCount,
+                fileCount: stats.fileCount,
+                drift,
+                lastIndexed: lastIndexed != null ? new Date(lastIndexed).toISOString() : null,
+                nodesByKind: stats.nodesByKind,
+                filesByLanguage: stats.filesByLanguage,
+                dbSizeBytes: stats.dbSizeBytes,
+            },
+        };
+    });
+}

package/dist/server/routes/workflow.js

@@ -0,0 +1,253 @@
+/**
+ * Workflow routes — discover / run / resume / cancel / approve / reject /
+ * runs list / run detail + SSE event stream.
+ *
+ * All project-scoped via `?project=<slug>` (falls back to primary). Each
+ * handler resolves the active SpecShip instance from the registry and
+ * constructs the WorktreeProvider + WorkflowExecutor on demand against
+ * that instance's queries. Construction is cheap (both classes just stash
+ * references), and pinning a single executor across all projects would
+ * tie the entire surface to whichever instance loaded first.
+ *
+ * The SSE endpoint streams workflow_events as they're appended to the DB
+ * (polling 500ms). For v1 polling the same SQLite the executor writes to is
+ * faster + more reliable than wiring an in-process event bus across packages.
+ */
+import path from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+async function resolveCg(app, req, reply) {
+    const cg = await app.activeCg(req);
+    if (!cg) {
+        reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+        return null;
+    }
+    return cg;
+}
+export async function registerWorkflowRoutes(app) {
+    // Lazy import — keeps the server bootable even if the workflow engine
+    // is disabled in the current build profile.
+    //
+    // Two delivery shapes (same pattern as loadSpecShip() in ../server.ts):
+    //   1. **Bundled** — `dist/server/routes/workflow.js` sits two levels under
+    //      `dist/`, so the core workflow modules live at `../../workflows/*.js`
+    //      and `../../isolation/*.js`. We try this relative path first because
+    //      the bundled tarball stages the specship core without a resolvable
+    //      `@selvakumaresra/specship` package on Node's module graph (offline
+    //      installs hit this — see scripts/offline-install.sh).
+    //   2. **Workspace / dev** — the `file:../..` workspace dep resolves the
+    //      named import via Node's normal package resolution.
+    let discovery;
+    let executorMod;
+    let worktreeMod;
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const bundledDiscovery = path.resolve(here, '..', '..', 'workflows', 'discovery.js');
+    if (existsSync(bundledDiscovery)) {
+        discovery = await import(pathToFileURL(bundledDiscovery).href);
+        executorMod = await import(pathToFileURL(path.resolve(here, '..', '..', 'workflows', 'executor.js')).href);
+        worktreeMod = await import(pathToFileURL(path.resolve(here, '..', '..', 'isolation', 'worktree.js')).href);
+    }
+    else {
+        discovery = await import('@selvakumaresra/specship/dist/workflows/discovery.js');
+        executorMod = await import('@selvakumaresra/specship/dist/workflows/executor.js');
+        worktreeMod = await import('@selvakumaresra/specship/dist/isolation/worktree.js');
+    }
+    const { discoverWorkflows, loadWorkflowByName } = discovery;
+    const { WorkflowExecutor } = executorMod;
+    const { WorktreeProvider } = worktreeMod;
+    const executorCache = new WeakMap();
+    /** Build (or fetch cached) executor + worktree provider for a project. */
+    function executorFor(cg) {
+        const sq = cg.getSpecQueries();
+        const cached = executorCache.get(sq);
+        if (cached)
+            return { sq, executor: cached.executor, projectRoot: cached.projectRoot };
+        const projectRoot = cg.getProjectRoot ? cg.getProjectRoot() : process.cwd();
+        const worktrees = new WorktreeProvider(sq);
+        const executor = new WorkflowExecutor(sq, worktrees);
+        executorCache.set(sq, { executor, projectRoot });
+        return { sq, executor, projectRoot };
+    }
+    app.get('/api/workflows', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { projectRoot } = executorFor(cg);
+        return discoverWorkflows(projectRoot);
+    });
+    app.post('/api/workflows/runs', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { executor, projectRoot } = executorFor(cg);
+        const body = req.body;
+        if (!body?.workflowName)
+            return reply.code(400).send({ error: 'workflowName required' });
+        const loaded = loadWorkflowByName(projectRoot, body.workflowName);
+        if (!loaded)
+            return reply.code(404).send({ error: 'workflow not found' });
+        const startPromise = executor.start(loaded.workflow, {
+            projectRoot,
+            inputs: body.inputs,
+            variables: body.variables,
+        });
+        const result = await Promise.race([
+            startPromise,
+            new Promise((resolve) => setTimeout(() => resolve({ run: { id: 'pending', status: 'starting' } }), 50)),
+        ]);
+        startPromise.catch(() => { });
+        return { runId: result.run.id, status: result.run.status };
+    });
+    app.get('/api/workflows/runs', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { sq } = executorFor(cg);
+        const limit = Math.min(parseInt(req.query.limit ?? '50', 10) || 50, 500);
+        return { runs: sq.getAllWorkflowRuns(limit) };
+    });
+    app.get('/api/workflows/runs/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { sq } = executorFor(cg);
+        const run = sq.getWorkflowRunById(req.params.id);
+        if (!run)
+            return reply.code(404).send({ error: 'run not found' });
+        const events = sq.getEventsByRun(req.params.id, 500);
+        return { run, events };
+    });
+    /**
+     * Read-only artifacts for a run. The executor writes each completed node's
+     * output to `<.specship>/artifacts/runs/<id>/nodes/<nodeId>.{md,meta.json}`;
+     * this lists + returns them (body inline — a run has a handful of nodes). No
+     * execution-path change: it only reads what's already on disk.
+     */
+    app.get('/api/workflows/runs/:id/artifacts', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { projectRoot } = executorFor(cg);
+        const dir = path.join(projectRoot, '.specship', 'artifacts', 'runs', req.params.id, 'nodes');
+        const artifacts = [];
+        if (existsSync(dir)) {
+            try {
+                for (const file of readdirSync(dir).filter((f) => f.endsWith('.md')).sort()) {
+                    const stem = file.slice(0, -3);
+                    let meta = {};
+                    try {
+                        meta = JSON.parse(readFileSync(path.join(dir, `${stem}.meta.json`), 'utf8'));
+                    }
+                    catch { /* no/invalid meta */ }
+                    let body = '';
+                    try {
+                        body = readFileSync(path.join(dir, file), 'utf8');
+                    }
+                    catch { /* unreadable */ }
+                    artifacts.push({
+                        nodeId: meta.nodeId ?? stem,
+                        name: file,
+                        kind: meta.kind,
+                        outputType: meta.outputType,
+                        length: meta.length ?? body.length,
+                        body,
+                    });
+                }
+            }
+            catch { /* dir vanished mid-read — return what we have */ }
+        }
+        return { artifacts };
+    });
+    /**
+     * SSE event stream. Polls the events table every 500ms for any events
+     * newer than the last id sent. Closes when the run hits a terminal state.
+     */
+    app.get('/api/workflows/runs/:id/events', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { sq } = executorFor(cg);
+        const runId = req.params.id;
+        let lastId = parseInt(req.query.since ?? '0', 10) || 0;
+        reply.raw.setHeader('Content-Type', 'text/event-stream');
+        reply.raw.setHeader('Cache-Control', 'no-cache');
+        reply.raw.setHeader('Connection', 'keep-alive');
+        reply.raw.flushHeaders();
+        let closed = false;
+        req.raw.on('close', () => { closed = true; });
+        const tick = async () => {
+            if (closed)
+                return;
+            const events = sq.getEventsByRun(runId, 1000);
+            const fresh = events.filter((e) => e.id > lastId);
+            for (const e of fresh) {
+                reply.raw.write(`id: ${e.id}\n`);
+                reply.raw.write(`event: ${e.eventType}\n`);
+                reply.raw.write(`data: ${JSON.stringify(e)}\n\n`);
+                lastId = e.id;
+            }
+            const run = sq.getWorkflowRunById(runId);
+            if (!run || ['completed', 'failed', 'cancelled'].includes(run.status)) {
+                reply.raw.write(`event: done\ndata: ${JSON.stringify({ status: run?.status })}\n\n`);
+                reply.raw.end();
+                return;
+            }
+            setTimeout(() => { void tick(); }, 500);
+        };
+        void tick();
+    });
+    app.post('/api/workflows/runs/:id/approve', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { executor } = executorFor(cg);
+        try {
+            executor.approve(req.params.id, req.body?.comment);
+            return { ok: true };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    app.post('/api/workflows/runs/:id/reject', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { executor } = executorFor(cg);
+        try {
+            executor.reject(req.params.id, req.body?.reason);
+            return { ok: true };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    app.post('/api/workflows/runs/:id/cancel', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { executor } = executorFor(cg);
+        try {
+            executor.cancel(req.params.id, req.body?.reason);
+            return { ok: true };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    app.post('/api/workflows/runs/:id/resume', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { sq, executor, projectRoot } = executorFor(cg);
+        const run = sq.getWorkflowRunById(req.params.id);
+        if (!run)
+            return reply.code(404).send({ error: 'run not found' });
+        const loaded = loadWorkflowByName(projectRoot, run.workflowName);
+        if (!loaded)
+            return reply.code(404).send({ error: 'workflow definition missing' });
+        const promise = executor.resume(loaded.workflow, req.params.id, { projectRoot });
+        promise.catch(() => { });
+        return { ok: true };
+    });
+}

package/dist/server/server.js

@@ -0,0 +1,238 @@
+/**
+ * Fastify HTTP server for specship + SpecShip Desktop UI.
+ *
+ * Routes follow the design spec — `/api/graph/*`, `/api/spec/*`,
+ * `/api/drift`, `/api/workflows/*`, `/api/claude/*`. Each route group lives
+ * in its own file under `./routes/` and registers itself on a passed
+ * Fastify instance.
+ *
+ * Why Fastify: lighter than Express, faster, first-class TypeScript types,
+ * built-in JSON schema validation, plugins for CORS + SSE. The 30K LoC
+ * Archon UI port pulls ~20+ API routes — Fastify's plugin model keeps the
+ * registration code tidy.
+ */
+import path from 'node:path';
+import { existsSync, promises as fs } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import { startWatcher, primaryProjectMatcher } from './ingest/index.js';
+import { backfillDisplaced } from './ingest/impact-backfill.js';
+import { ProjectRegistry } from './project-registry.js';
+import { makeStaticHandler } from './static-handler.js';
+import { registerGraphRoutes } from './routes/graph.js';
+import { registerSpecRoutes } from './routes/spec.js';
+import { registerWorkflowRoutes } from './routes/workflow.js';
+import { registerClaudeRoutes } from './routes/claude.js';
+import { registerStatusRoutes } from './routes/status.js';
+import { registerMemoryRoutes } from './routes/memory.js';
+import { registerProjectsRoutes } from './routes/projects.js';
+import { registerEventsRoutes } from './routes/events.js';
+import { registerReflectRoutes } from './routes/reflect.js';
+import { registerMaintainabilityRoutes } from './routes/maintainability.js';
+import { registerDomainRoutes } from './routes/domain.js';
+/**
+ * Lazy-import the specship core. Two delivery shapes are supported:
+ *
+ *   1. **Bundled** — the platform-specific npm tarball lays the compiled
+ *      server out at `<bundle>/lib/dist/server/server.js` and the specship
+ *      core at `<bundle>/lib/dist/index.js`. We try this relative path
+ *      first so the bundled mode never depends on Node's package
+ *      resolution finding `@selvakumaresra/specship` (it won't, the
+ *      bundle stages a single package by name `@selvakumaresra/specship`).
+ *
+ *   2. **Workspace / dev** — `packages/server/dist/server.js` imports via
+ *      the workspace `file:../..` dep. Falls through to the named import.
+ *
+ * The function caches the resolved module so the lookup only runs once.
+ */
+let cachedSpecShip = null;
+async function loadSpecShip() {
+    if (cachedSpecShip)
+        return cachedSpecShip;
+    // Bundled mode: dist/server/server.js → ../index.js (root dist/index.js).
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const candidate = path.resolve(here, '..', 'index.js');
+        if (existsSync(candidate)) {
+            cachedSpecShip = (await import(pathToFileURL(candidate).href));
+            return cachedSpecShip;
+        }
+    }
+    catch { /* fall through */ }
+    // Workspace/dev: resolve via the named dep.
+    cachedSpecShip = await import('@selvakumaresra/specship');
+    return cachedSpecShip;
+}
+export async function createServer(options) {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? 4242;
+    const verbose = options.verbose ?? false;
+    const app = Fastify({
+        logger: verbose
+            ? { transport: { target: 'pino-pretty', options: { translateTime: 'HH:MM:ss.l' } } }
+            : false,
+    });
+    if (options.cors !== false) {
+        // Permissive CORS for local dev. The server is bound to loopback by
+        // default, so the broad allowlist is fine — Browsers won't get to it
+        // from a non-localhost origin without explicit user override.
+        await app.register(cors, {
+            origin: true,
+            credentials: false,
+        });
+    }
+    // Lazy-load specship. Used as the open() impl for the registry, and
+    // (only when a primary path is set) to open the primary instance below.
+    const cgMod = await loadSpecShip();
+    const registry = new ProjectRegistry({ verbose }, (p) => cgMod.SpecShip.open(p));
+    // Primary project (optional). When set, specship-scoped routes default to
+    // it when no `?project=<slug>` is provided, and the analytics ingest
+    // hooks into its SQLite handle.
+    let primaryCg = null;
+    if (options.projectRoot) {
+        primaryCg = await registry.get(options.projectRoot);
+        if (!primaryCg && verbose) {
+            console.error(`[specship-server] primary project ${options.projectRoot} not initialized — booting projectless`);
+        }
+    }
+    // Start the JSONL ingest watcher in-process unless the caller already
+    // provided one or explicitly opted out. Hooks into the primary project's
+    // SQLite handle — when there's no primary, analytics endpoints will return
+    // 409 until one is set (typically the next server restart with -p).
+    let watcher = options.watcher ?? null;
+    let ownedWatcher = false;
+    if (!watcher && options.ingest !== false && primaryCg) {
+        const cgAny = primaryCg;
+        const dbHandle = cgAny.db?.getDb ? cgAny.db.getDb() : cgAny.queries?.db;
+        if (dbHandle) {
+            // Build a sync resolveGraph: for the primary project path return the
+            // already-open SpecShip instance (which satisfies GraphLike).
+            // Sessions from other project paths resolve to null — they'll be left
+            // as 'unresolved' and retried on the next boot when that project is primary.
+            // The stored project_path is the lossy-decoded slug (every '-' → '/'), so
+            // an exact compare against the real primaryPath never matched and savings
+            // stayed 0. primaryProjectMatcher accepts both the real path and its
+            // mangled stored form. Sessions from OTHER projects still resolve to null
+            // (left 'unresolved', retried when that project is primary).
+            const primaryPath = options.projectRoot ?? null;
+            const isPrimary = primaryPath ? primaryProjectMatcher(primaryPath) : () => false;
+            const resolveGraph = (projectPath) => primaryPath && isPrimary(projectPath) ? primaryCg : null;
+            watcher = startWatcher(dbHandle, { verbose, resolveGraph });
+            ownedWatcher = true;
+            if (verbose)
+                console.error('[specship-server] JSONL ingest watcher started');
+            // Backfill displaced_files / resolution for pre-upgrade rows (is_specship=1,
+            // resolution IS NULL). Idempotent — safe to run on every boot. Non-fatal:
+            // a failure here must never abort server startup.
+            try {
+                backfillDisplaced(dbHandle, resolveGraph);
+                if (verbose)
+                    console.error('[specship-server] specship-impact backfill complete');
+            }
+            catch (err) {
+                console.error('[specship-server] specship-impact backfill failed (non-fatal):', err instanceof Error ? err.message : String(err));
+            }
+        }
+    }
+    else if (!primaryCg && options.ingest !== false && verbose) {
+        console.error('[specship-server] no primary project — analytics will be empty until one is set');
+    }
+    // Decorate the Fastify instance so route handlers can access shared state
+    // without globals or DI containers.
+    app.decorate('projects', registry);
+    app.decorate('primaryCg', primaryCg);
+    app.decorate('watcher', watcher);
+    // activeCg(req): resolve `?project=<slug>` → SpecShip instance, with the
+    // primary as fallback. Returns null when nothing is selectable; route
+    // handlers respond 409 in that case.
+    app.decorate('activeCg', async function (req) {
+        const q = (req.query ?? {});
+        if (q.project) {
+            const bySlug = await registry.getBySlug(q.project);
+            if (bySlug)
+                return bySlug;
+        }
+        if (q.projectPath) {
+            const byPath = await registry.get(q.projectPath);
+            if (byPath)
+                return byPath;
+        }
+        return primaryCg;
+    });
+    // Register route groups.
+    await registerStatusRoutes(app);
+    await registerGraphRoutes(app);
+    await registerSpecRoutes(app);
+    await registerWorkflowRoutes(app);
+    await registerClaudeRoutes(app);
+    await registerMemoryRoutes(app);
+    await registerProjectsRoutes(app);
+    await registerEventsRoutes(app);
+    await registerReflectRoutes(app);
+    await registerMaintainabilityRoutes(app);
+    await registerDomainRoutes(app);
+    // Optional: serve the built Angular UI from `webDir` and fall back to
+    // index.html for client-side routes. Must register AFTER the /api/*
+    // routes so they take precedence over the SPA wildcard.
+    if (options.webDir) {
+        const indexPath = path.join(options.webDir, 'index.html');
+        let indexBuffer = null;
+        try {
+            indexBuffer = await fs.readFile(indexPath);
+        }
+        catch {
+            if (verbose) {
+                console.error(`[specship-server] webDir provided but index.html not found at ${indexPath} — skipping static mount`);
+            }
+        }
+        if (indexBuffer) {
+            const cachedIndex = indexBuffer;
+            const serveStatic = makeStaticHandler(options.webDir);
+            // A single 404 handler does both jobs:
+            //   1. Try the requested URL as a real file under webDir → serve it
+            //      with the right content-type. Covers the SPA's chunk-*.js,
+            //      styles.css, favicons, fonts, etc.
+            //   2. Fall through to index.html for any other GET so Angular's
+            //      client-side router can take over (`/memory`, `/graph`, …).
+            // Non-GET methods and `/api/*` paths still 404 cleanly so the UI
+            // can surface them.
+            app.setNotFoundHandler((request, reply) => {
+                if (request.method !== 'GET') {
+                    reply.code(404).send({ error: 'not found' });
+                    return;
+                }
+                if (request.url.startsWith('/api/')) {
+                    reply.code(404).send({ error: 'not found' });
+                    return;
+                }
+                const hit = serveStatic(request.url);
+                if (hit) {
+                    reply.code(200).type(hit.contentType).send(hit.body);
+                    return;
+                }
+                reply.code(200).type('text/html').send(cachedIndex);
+            });
+            if (verbose)
+                console.error(`[specship-server] serving SPA from ${options.webDir}`);
+        }
+    }
+    await app.listen({ host, port });
+    const url = `http://${host}:${port}`;
+    return {
+        app,
+        url,
+        host,
+        port,
+        stop: async () => {
+            if (ownedWatcher && watcher) {
+                try {
+                    watcher.stop();
+                }
+                catch { /* ignore */ }
+            }
+            registry.closeAll();
+            await app.close();
+        },
+    };
+}