@gr8ful/spf 0.1.0

package/dist/ui/server/app.js

@@ -0,0 +1,98 @@
+/**
+ * SPF visualizer app — JSON API over a target repo's spf.db, plus the packaged
+ * SPA. Reads are read-only; the single write is POST
+ * /api/sessions/:adw_id/archive, which sets one review flag on a row.
+ *
+ * There is no ingest endpoint and no websocket. The data path is
+ * agents -> sqlite -> web ui, and the UI gets there by polling.
+ *
+ * Ported from a Bun.serve({routes}) app — Hono's :param routes are the same
+ * shape, so every route transcribes directly. Two deliberate behavior
+ * changes from the Bun version: a GET to the archive route now 404s as JSON
+ * (it used to fall through to the SPA, since Bun's routes object only wires
+ * POST there); and the manual decodeURIComponent() on route params is
+ * dropped — Hono decodes them itself, so keeping it would double-decode.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { Hono } from "hono";
+import { SfDb } from "./db.js";
+import { serveStatic } from "./static.js";
+/**
+ * adw_ids and agent names are path segments on disk, so anything that isn't a
+ * plain identifier is rejected outright rather than sanitized into something
+ * that might still escape the sessions directory.
+ */
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+function isSafeSegment(value) {
+    return SAFE_SEGMENT.test(value) && value !== "." && value !== "..";
+}
+function intQueryParam(value, fallback) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+export function createApp(db, webDir) {
+    const app = new Hono();
+    app.use("/api/*", async (c, next) => {
+        await next();
+        c.header("cache-control", "no-store");
+    });
+    app.get("/api/health", (c) => c.json({ ok: true, db: db.path, journal_mode: db.journalMode, sessions: db.sessionCount() }));
+    app.get("/api/sessions", (c) => c.json(db.sessions(intQueryParam(c.req.query("limit"), 200))));
+    app.get("/api/sessions/:adw_id", (c) => {
+        const adwId = c.req.param("adw_id");
+        const detail = db.sessionDetail(adwId);
+        if (!detail)
+            return c.json({ error: `no session ${adwId}` }, 404);
+        return c.json(detail);
+    });
+    // The one write. Archiving is review triage — it belongs to the reader, not
+    // to the run — so it never touches anything a tracer wrote.
+    app.post("/api/sessions/:adw_id/archive", async (c) => {
+        const adwId = c.req.param("adw_id");
+        if (!isSafeSegment(adwId))
+            return c.json({ error: "invalid adw_id" }, 400);
+        const body = (await c.req.json().catch(() => ({})));
+        const archived = body.archived === undefined ? true : Boolean(body.archived);
+        if (!db.setArchived(adwId, archived))
+            return c.json({ error: `no session ${adwId}` }, 404);
+        return c.json({ adw_id: adwId, archived });
+    });
+    app.get("/api/sessions/:adw_id/events", (c) => c.json(db.events(c.req.param("adw_id"), intQueryParam(c.req.query("after"), 0), intQueryParam(c.req.query("limit"), 500))));
+    app.get("/api/sessions/:adw_id/envelopes", (c) => c.json(db.envelopes(c.req.param("adw_id"))));
+    app.get("/api/sessions/:adw_id/gates", (c) => c.json(db.gates(c.req.param("adw_id"))));
+    // The exact prompts an agent was sent, read from the session dir. Files are
+    // the raw record; the db has no copy of them.
+    app.get("/api/sessions/:adw_id/agents/:agent/prompts", (c) => {
+        const adwId = c.req.param("adw_id");
+        const agent = c.req.param("agent");
+        if (!isSafeSegment(adwId) || !isSafeSegment(agent)) {
+            return c.json({ error: "invalid adw_id or agent" }, 400);
+        }
+        if (!db.session(adwId))
+            return c.json({ error: `no session ${adwId}` }, 404);
+        const dir = resolve(db.sessionsDir, adwId, agent, "prompts");
+        // Defense in depth: the segment check already forbids traversal.
+        if (dir !== db.sessionsDir && !dir.startsWith(db.sessionsDir + sep)) {
+            return c.json({ error: "invalid path" }, 400);
+        }
+        // A prompt file is absent whenever the agent never ran in this session —
+        // a normal state, so it reads as null rather than an error.
+        const read = (name) => {
+            const file = resolve(dir, `${name}.md`);
+            return existsSync(file) ? readFileSync(file, "utf-8") : null;
+        };
+        return c.json({ system: read("system"), user: read("user") });
+    });
+    // Registered after every real /api/* route: a miss under /api/ is a 404,
+    // never the SPA fallback.
+    app.all("/api/*", (c) => c.json({ error: `no route ${c.req.path}` }, 404));
+    app.get("*", serveStatic(webDir));
+    app.onError((err, c) => {
+        console.error(`[spf] ${c.req.method} ${c.req.path}:`, err);
+        return c.json({ error: err.message }, 500);
+    });
+    return app;
+}

package/dist/ui/server/db.d.ts

@@ -0,0 +1,82 @@
+import type { AgentSession, Envelope, EventsPage, GateResult, Phase, Session, SessionDetail, SessionSummary, SessionUsage } from "../shared/types.ts";
+export declare class SfDb {
+    readonly path: string;
+    /**
+     * Where the ADW session dirs live: `{data_dir}/sessions/{adw_id}/{agent}/`.
+     * The db sits in the same data_dir (config's `observability.db` defaults to
+     * `adws/adw_data/spf.db`), so deriving it as a sibling of the db file keeps
+     * working when the whole data_dir is relocated.
+     */
+    readonly sessionsDir: string;
+    readonly journalMode: string;
+    private readonly db;
+    /** Opened on first archive and kept; null until then. */
+    private writer;
+    /** Cache for optionalColumn(), keyed "table.column". Only ever false → true. */
+    private readonly columnCache;
+    /** `path` is always absolute — resolved upstream by the ui command via paths.resolveAnchor/resolveDataPaths. */
+    constructor(path: string);
+    /**
+     * A SELECT fragment for a column the tracer adds by migration.
+     *
+     * We open readonly and cannot run those ALTERs ourselves, so selecting one
+     * blindly would throw "no such column" on every request against a db an older
+     * tracer wrote. Instead we probe and substitute NULL, which reads downstream
+     * as "this db predates the column" — the same thing the UI shows for a row
+     * the migration didn't backfill.
+     *
+     * The probe re-runs while the column is missing, because the tracer's ALTER
+     * can land while we're serving: a startup-only check would keep returning
+     * NULL for the rest of the process even after the data arrived. Once seen,
+     * a column never goes away, so it latches.
+     */
+    private hasColumn;
+    private optionalColumn;
+    close(): void;
+    /**
+     * Archive or restore a session — the only write in this process.
+     *
+     * busy_timeout matters: a run may be mid-insert on the same WAL db, and a
+     * click should wait its turn rather than fail. Returns false when the id
+     * does not exist, so the route can 404 instead of silently succeeding.
+     */
+    setArchived(adwId: string, archived: boolean): boolean;
+    /** Sessions, most recent first, each with its phase statuses for the progress dots. */
+    sessions(limit?: number): SessionSummary[];
+    session(adwId: string): Session | null;
+    phases(adwId: string): Phase[];
+    agentSessions(adwId: string): AgentSession[];
+    /**
+     * Agents per session, for a set of ids at once: the agent_sessions rows plus
+     * anything that has started but not finished.
+     *
+     * agents.ts writes the agent_sessions row only after the envelope persists, so
+     * a running agent has no row there — precisely the case the live view exists
+     * for. Its model, color and session_id are already on the agent_start event,
+     * so a lane is labelled and colored from the moment the agent spawns.
+     */
+    private agentsFor;
+    /** Session + phases + agents in one shot — L2 needs all three to draw lanes. */
+    sessionDetail(adwId: string): SessionDetail | null;
+    /**
+     * Raw tokens read and written, beside the billed headline.
+     *
+     * Derived from the `agent_end` payloads rather than stored, so every run
+     * already in the db gets the split without a migration or a re-run.
+     *
+     * `total_tokens` is a SPEND number: every turn re-sends the whole
+     * conversation, so an 86k conversation over 49 turns bills millions. These
+     * two say what actually moved — material read for the first time, and
+     * material generated. The gap between them and the headline is cached
+     * re-reads, which is usually most of it.
+     */
+    usage(adwId: string): SessionUsage;
+    /**
+     * The polling query. Rowid cursor, insertion order, bounded page — the same
+     * mechanism serves the live tail and lazy-paged history.
+     */
+    events(adwId: string, after?: number, limit?: number): EventsPage;
+    envelopes(adwId: string): Envelope[];
+    gates(adwId: string): GateResult[];
+    sessionCount(): number;
+}

package/dist/ui/server/db.js

@@ -0,0 +1,333 @@
+/**
+ * SQLite reader over a target repo's spf.db.
+ *
+ * The read connection is opened readonly and every query on it is a SELECT —
+ * the writers are the tracers of running ADW processes, and WAL lets us read
+ * straight through their inserts.
+ *
+ * ONE exception, opened lazily on its own connection: `setArchived`. Archiving
+ * is review triage — "I have looked at this run" — which has to outlive a
+ * browser, so it lives on the session row rather than in localStorage. It is
+ * the only write this process can make, it touches exactly one column, and it
+ * never runs unless a human clicks the button.
+ */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { Database } from "../../core/sqlite.js";
+const MAX_LIMIT = 1000;
+const DEFAULT_LIMIT = 500;
+export class SfDb {
+    path;
+    /**
+     * Where the ADW session dirs live: `{data_dir}/sessions/{adw_id}/{agent}/`.
+     * The db sits in the same data_dir (config's `observability.db` defaults to
+     * `adws/adw_data/spf.db`), so deriving it as a sibling of the db file keeps
+     * working when the whole data_dir is relocated.
+     */
+    sessionsDir;
+    journalMode;
+    db;
+    /** Opened on first archive and kept; null until then. */
+    writer = null;
+    /** Cache for optionalColumn(), keyed "table.column". Only ever false → true. */
+    columnCache = new Map();
+    /** `path` is always absolute — resolved upstream by the ui command via paths.resolveAnchor/resolveDataPaths. */
+    constructor(path) {
+        if (!existsSync(path)) {
+            throw new Error(`spf.db not found at ${path}\n` +
+                `Point spf ui at a target repo: --db <path>, SF_DB=<path>, --cwd <repo>, or run it from inside one.`);
+        }
+        this.path = path;
+        this.sessionsDir = resolve(dirname(path), "sessions");
+        this.db = new Database(path, { readonly: true });
+        // WAL is set by the tracer when it creates the db; a readonly connection
+        // cannot change it, so we assert rather than set, and always take the
+        // busy_timeout so a concurrent writer never turns into a failed request.
+        this.db.exec("PRAGMA busy_timeout = 5000");
+        this.db.exec("PRAGMA synchronous = NORMAL");
+        const mode = this.db
+            .query("PRAGMA journal_mode")
+            .get();
+        this.journalMode = mode?.journal_mode ?? "unknown";
+        if (this.journalMode.toLowerCase() !== "wal") {
+            console.warn(`[db] journal_mode is "${this.journalMode}", expected "wal" — ` +
+                `live reads during agent writes may block`);
+        }
+    }
+    /**
+     * A SELECT fragment for a column the tracer adds by migration.
+     *
+     * We open readonly and cannot run those ALTERs ourselves, so selecting one
+     * blindly would throw "no such column" on every request against a db an older
+     * tracer wrote. Instead we probe and substitute NULL, which reads downstream
+     * as "this db predates the column" — the same thing the UI shows for a row
+     * the migration didn't backfill.
+     *
+     * The probe re-runs while the column is missing, because the tracer's ALTER
+     * can land while we're serving: a startup-only check would keep returning
+     * NULL for the rest of the process even after the data arrived. Once seen,
+     * a column never goes away, so it latches.
+     */
+    hasColumn(table, column) {
+        const key = `${table}.${column}`;
+        if (!this.columnCache.get(key)) {
+            const cols = this.db
+                .query(`PRAGMA table_info(${table})`)
+                .all();
+            this.columnCache.set(key, cols.some((c) => c.name === column));
+        }
+        return this.columnCache.get(key) ?? false;
+    }
+    optionalColumn(table, column) {
+        return this.hasColumn(table, column) ? column : `NULL AS ${column}`;
+    }
+    close() {
+        this.writer?.close();
+        this.db.close();
+    }
+    /**
+     * Archive or restore a session — the only write in this process.
+     *
+     * busy_timeout matters: a run may be mid-insert on the same WAL db, and a
+     * click should wait its turn rather than fail. Returns false when the id
+     * does not exist, so the route can 404 instead of silently succeeding.
+     */
+    setArchived(adwId, archived) {
+        if (!this.hasColumn("sessions", "archived")) {
+            throw new Error("this db predates the archived column — run any ADW once to migrate it");
+        }
+        if (!this.writer) {
+            this.writer = new Database(this.path);
+            this.writer.exec("PRAGMA busy_timeout=5000;");
+        }
+        this.writer
+            .query("UPDATE sessions SET archived = ? WHERE adw_id = ?")
+            .run(archived ? 1 : 0, adwId);
+        return this.session(adwId) !== null;
+    }
+    /** Sessions, most recent first, each with its phase statuses for the progress dots. */
+    sessions(limit = 200) {
+        const rows = this.db
+            .query(`SELECT adw_id, ${this.optionalColumn("sessions", "adw_name")}, request,
+                status, engineer, started_at, ended_at,
+                total_tokens, total_cost,
+                ${this.optionalColumn("sessions", "archived")}
+           FROM sessions
+          WHERE COALESCE(${this.hasColumn("sessions", "archived") ? "archived" : "0"}, 0) = 0
+          ORDER BY started_at DESC, rowid DESC
+          LIMIT ?`)
+            .all(clamp(limit, 1, MAX_LIMIT));
+        if (rows.length === 0)
+            return [];
+        // Embed each session's phases so the L1 progress dots cost no extra request.
+        const ids = rows.map((row) => row.adw_id);
+        const placeholders = ids.map(() => "?").join(", ");
+        const phaseRows = this.db
+            .query(`SELECT phase_id, adw_id, seq, name, kind, owner, description, status,
+                attempt, retries, error, started_at, ended_at
+           FROM phases WHERE adw_id IN (${placeholders}) ORDER BY seq, rowid`)
+            .all(...ids);
+        const byAdw = new Map();
+        for (const phase of phaseRows) {
+            const list = byAdw.get(phase.adw_id);
+            if (list)
+                list.push(phase);
+            else
+                byAdw.set(phase.adw_id, [phase]);
+        }
+        // Agents come along too: an L1 card draws a per-agent dot timeline, and its
+        // dots are colored per agent — without this it would be one request per card.
+        const agentsByAdw = this.agentsFor(ids);
+        const summaries = [];
+        for (const session of rows) {
+            const phases = byAdw.get(session.adw_id) ?? [];
+            summaries.push(Object.assign(session, {
+                phases,
+                phase_count: phases.length,
+                agents: agentsByAdw.get(session.adw_id) ?? [],
+            }));
+        }
+        return summaries;
+    }
+    session(adwId) {
+        return (this.db
+            .query(`SELECT adw_id, ${this.optionalColumn("sessions", "adw_name")}, request,
+                  status, engineer, started_at, ended_at,
+                  total_tokens, total_cost
+             FROM sessions WHERE adw_id = ?`)
+            .get(adwId) ?? null);
+    }
+    phases(adwId) {
+        return this.db
+            .query(`SELECT phase_id, adw_id, seq, name, kind, owner, description, status,
+                attempt, retries, error, started_at, ended_at
+           FROM phases WHERE adw_id = ? ORDER BY seq, rowid`)
+            .all(adwId);
+    }
+    agentSessions(adwId) {
+        return this.agentsFor([adwId]).get(adwId) ?? [];
+    }
+    /**
+     * Agents per session, for a set of ids at once: the agent_sessions rows plus
+     * anything that has started but not finished.
+     *
+     * agents.ts writes the agent_sessions row only after the envelope persists, so
+     * a running agent has no row there — precisely the case the live view exists
+     * for. Its model, color and session_id are already on the agent_start event,
+     * so a lane is labelled and colored from the moment the agent spawns.
+     */
+    agentsFor(adwIds) {
+        const byAdw = new Map();
+        if (adwIds.length === 0)
+            return byAdw;
+        const placeholders = adwIds.map(() => "?").join(", ");
+        const append = (adwId, agent) => {
+            const list = byAdw.get(adwId);
+            if (list)
+                list.push(agent);
+            else
+                byAdw.set(adwId, [agent]);
+        };
+        const color = this.optionalColumn("agent_sessions", "color");
+        const ctxUsed = this.optionalColumn("agent_sessions", "context_tokens");
+        const ctxWindow = this.optionalColumn("agent_sessions", "context_window");
+        const completed = this.db
+            .query(`SELECT adw_id, agent, coding_agent, model, session_id, ${color},
+                ${ctxUsed}, ${ctxWindow}, created_at, last_used_at
+           FROM agent_sessions WHERE adw_id IN (${placeholders})
+          ORDER BY created_at, agent`)
+            .all(...adwIds);
+        for (const row of completed)
+            append(row.adw_id, row);
+        const started = this.db
+            .query(`SELECT e.adw_id, p.owner AS agent, e.payload_json, e.started_at
+           FROM events e JOIN phases p ON p.phase_id = e.phase_id
+          WHERE e.adw_id IN (${placeholders}) AND e.type = 'agent_start'
+          ORDER BY e.rowid`)
+            .all(...adwIds);
+        for (const row of started) {
+            if (!row.agent)
+                continue;
+            // A finished row is authoritative; only fill genuine gaps.
+            if (byAdw.get(row.adw_id)?.some((a) => a.agent === row.agent))
+                continue;
+            let payload = {};
+            try {
+                payload = JSON.parse(row.payload_json ?? "{}");
+            }
+            catch {
+                // A malformed payload just means no label — never a failed request.
+            }
+            append(row.adw_id, {
+                adw_id: row.adw_id,
+                agent: row.agent,
+                coding_agent: null,
+                model: payload.model ?? null,
+                session_id: payload.session_id ?? null,
+                color: payload.color ?? null,
+                // Occupancy is only known once the agent's turn closes.
+                context_tokens: null,
+                context_window: null,
+                created_at: row.started_at,
+                last_used_at: row.started_at,
+            });
+        }
+        return byAdw;
+    }
+    /** Session + phases + agents in one shot — L2 needs all three to draw lanes. */
+    sessionDetail(adwId) {
+        const session = this.session(adwId);
+        if (!session)
+            return null;
+        return {
+            session,
+            usage: this.usage(adwId),
+            phases: this.phases(adwId),
+            agents: this.agentSessions(adwId),
+        };
+    }
+    /**
+     * Raw tokens read and written, beside the billed headline.
+     *
+     * Derived from the `agent_end` payloads rather than stored, so every run
+     * already in the db gets the split without a migration or a re-run.
+     *
+     * `total_tokens` is a SPEND number: every turn re-sends the whole
+     * conversation, so an 86k conversation over 49 turns bills millions. These
+     * two say what actually moved — material read for the first time, and
+     * material generated. The gap between them and the headline is cached
+     * re-reads, which is usually most of it.
+     */
+    usage(adwId) {
+        const rows = this.db
+            .query("SELECT payload_json FROM events WHERE adw_id = ? AND type = 'agent_end'")
+            .all(adwId);
+        let read = 0;
+        let written = 0;
+        for (const row of rows) {
+            if (!row.payload_json)
+                continue;
+            try {
+                const u = JSON.parse(row.payload_json).usage;
+                if (!u)
+                    continue;
+                // RAW reads only: material entering the context for the first time,
+                // billed either as uncached input or as a cache write. Cache reads are
+                // the same tokens served again on later turns — counting them here
+                // would rebuild the very inflation this split exists to expose.
+                read += (u.input_tokens ?? 0) + (u.cache_write_tokens ?? 0);
+                written += u.output_tokens ?? 0;
+            }
+            catch {
+                /* a payload written by an older tracer simply contributes nothing */
+            }
+        }
+        return { read, written };
+    }
+    /**
+     * The polling query. Rowid cursor, insertion order, bounded page — the same
+     * mechanism serves the live tail and lazy-paged history.
+     */
+    events(adwId, after = 0, limit = DEFAULT_LIMIT) {
+        const cappedLimit = clamp(limit, 1, MAX_LIMIT);
+        const events = this.db
+            .query(`SELECT rowid, event_id, adw_id, phase_id, parent_id, type, name,
+                payload_json, tokens, started_at, ended_at
+           FROM events
+          WHERE adw_id = ? AND rowid > ?
+          ORDER BY rowid
+          LIMIT ?`)
+            .all(adwId, Math.max(0, after), cappedLimit);
+        return {
+            events,
+            cursor: events.length > 0 ? events[events.length - 1].rowid : Math.max(0, after),
+            has_more: events.length === cappedLimit,
+        };
+    }
+    envelopes(adwId) {
+        return this.db
+            .query(`SELECT envelope_id, adw_id, phase_id, agent, output_type, payload_json,
+                valid, attempt, created_at
+           FROM envelopes WHERE adw_id = ? ORDER BY created_at, rowid`)
+            .all(adwId);
+    }
+    gates(adwId) {
+        const checks = this.optionalColumn("gate_results", "checks_json");
+        return this.db
+            .query(`SELECT id, adw_id, phase_id, attempt, gate, passed, violations_json,
+                ${checks}, created_at
+           FROM gate_results WHERE adw_id = ? ORDER BY id`)
+            .all(adwId);
+    }
+    sessionCount() {
+        const row = this.db
+            .query("SELECT COUNT(*) AS n FROM sessions")
+            .get();
+        return row?.n ?? 0;
+    }
+}
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, Math.trunc(value)));
+}

package/dist/ui/server/serve.d.ts

@@ -0,0 +1,13 @@
+export interface UiOptions {
+    dbPath: string;
+    webDir: string;
+    /** Explicit port. Omit to try the default and probe upward on collision. */
+    port?: number;
+    open?: boolean;
+}
+export interface UiHandle {
+    url: string;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function runUi(options: UiOptions): Promise<UiHandle>;

package/dist/ui/server/serve.js

@@ -0,0 +1,80 @@
+/**
+ * `spf ui` bootstrap: bind the app to a real port, print the URL, optionally
+ * open a browser, and shut down cleanly on SIGINT/SIGTERM.
+ *
+ * Binds loopback-only (127.0.0.1) deliberately — this server can flip a
+ * database column and reveal agent prompts, and a companion CLI has no
+ * reason to listen on every interface.
+ */
+import { spawn } from "node:child_process";
+import { serve } from "@hono/node-server";
+import { createApp } from "./app.js";
+import { SfDb } from "./db.js";
+const DEFAULT_PORT = 4600;
+const PORT_PROBE_ATTEMPTS = 10;
+function isAddrInUse(error) {
+    return typeof error === "object" && error !== null && error.code === "EADDRINUSE";
+}
+function listen(app, port) {
+    return new Promise((resolvePromise, reject) => {
+        const server = serve({ fetch: app.fetch, port, hostname: "127.0.0.1" }, () => resolvePromise(server));
+        server.on("error", reject);
+    });
+}
+/** Best-effort only — a failure here (no GUI, unknown platform) is never fatal. */
+function openUrl(url) {
+    const platform = process.platform;
+    const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { }); // e.g. xdg-open not installed — swallow, url is already printed
+        child.unref();
+    }
+    catch {
+        // swallow — the URL is already printed either way
+    }
+}
+export async function runUi(options) {
+    const db = new SfDb(options.dbPath);
+    const app = createApp(db, options.webDir);
+    const explicit = options.port !== undefined;
+    const startPort = options.port ?? DEFAULT_PORT;
+    let server;
+    let port = startPort;
+    const attempts = explicit ? 1 : PORT_PROBE_ATTEMPTS;
+    for (let i = 0; i < attempts; i++) {
+        port = startPort + i;
+        try {
+            server = await listen(app, port);
+            break;
+        }
+        catch (error) {
+            if (!isAddrInUse(error))
+                throw error;
+            if (i === attempts - 1) {
+                db.close();
+                throw new Error(explicit
+                    ? `port ${port} is already in use — pick another with --port`
+                    : `ports ${startPort}-${port} are all in use — pick one explicitly with --port`);
+            }
+        }
+    }
+    const info = server.address();
+    const boundPort = info?.port ?? port;
+    const url = `http://127.0.0.1:${boundPort}`;
+    const shouldOpen = options.open !== false && process.stdout.isTTY && !process.env.CI && !process.env.SSH_CONNECTION;
+    if (shouldOpen)
+        openUrl(url);
+    const close = () => new Promise((resolvePromise) => {
+        server.close(() => {
+            db.close();
+            resolvePromise();
+        });
+    });
+    const shutdown = () => {
+        void close().then(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    return { url, port: boundPort, close };
+}

package/dist/ui/server/static.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from "hono";
+/** Throws if `webDir` has no index.html — call this at startup, before serving anything. */
+export declare function assertWebDir(webDir: string): void;
+/** `assertWebDir` runs once, here, at app-construction time — not per request. */
+export declare function serveStatic(webDir: string): (c: Context) => Response;

package/dist/ui/server/static.js

@@ -0,0 +1,55 @@
+/**
+ * Serves the packaged SPA (built once, at publish time — see app/vite.config.ts)
+ * from web/, a sibling of dist/ in the published package. Hand-rolled rather
+ * than @hono/node-server/serve-static, whose `root` option resolves against
+ * process.cwd() — wrong here, since `spf ui` runs from an arbitrary target repo,
+ * not from inside the package.
+ *
+ * A missing web/ (no dist/index.html) is a hard startup error, not a
+ * plaintext fallback response: the SPA is always prebuilt before publish, so
+ * its absence can only mean a corrupt install.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, join, resolve, sep } from "node:path";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".json": "application/json; charset=utf-8",
+    ".ico": "image/x-icon",
+    ".txt": "text/plain; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+};
+/** Throws if `webDir` has no index.html — call this at startup, before serving anything. */
+export function assertWebDir(webDir) {
+    if (!existsSync(join(webDir, "index.html"))) {
+        throw new Error(`spf ui: no packaged UI found at ${webDir} (missing index.html) — this looks like a corrupt install; try reinstalling.`);
+    }
+}
+/** `assertWebDir` runs once, here, at app-construction time — not per request. */
+export function serveStatic(webDir) {
+    assertWebDir(webDir);
+    return (c) => {
+        const pathname = new URL(c.req.url).pathname;
+        // Reject traversal before touching the filesystem.
+        const candidate = resolve(join(webDir, pathname));
+        if (candidate === webDir || candidate.startsWith(webDir + sep)) {
+            if (existsSync(candidate) && statSync(candidate).isFile()) {
+                const headers = { "content-type": MIME[extname(candidate)] ?? "application/octet-stream" };
+                // Vite content-hashes everything under assets/ — safe to cache forever.
+                headers["cache-control"] = pathname.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "no-store";
+                return new Response(readFileSync(candidate), { headers });
+            }
+        }
+        // SPA fallback: breadcrumb routes are client-side.
+        return new Response(readFileSync(join(webDir, "index.html"), "utf-8"), {
+            headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+        });
+    };
+}