mainflow 0.28.0 → 0.29.0-alpha.1

package/dist/retro-formats-ECy0gGOL.js

@@ -0,0 +1,30 @@
+//#region ../schema/dist/retro-formats.js
+/** Roles a delegation label names: `{item} {role} r{round}`. */
+const LABEL_ROLES = [
+	"impl",
+	"review",
+	"check",
+	"survey",
+	"explore"
+];
+/** The fence of the block a reviewer appends, one JSON object per finding and line. */
+const FINDINGS_FENCE = "review-findings";
+const FINDING_SEVERITIES = [
+	"high",
+	"mid",
+	"low"
+];
+const FINDING_CLASSES = [
+	"preexisting",
+	"spec-gap",
+	"impl-bug"
+];
+/** Fields every finding line carries. */
+const FINDING_FIELDS = [
+	"id",
+	"sev",
+	"class",
+	"src"
+];
+//#endregion
+export { LABEL_ROLES as a, FINDING_SEVERITIES as i, FINDING_CLASSES as n, FINDING_FIELDS as r, FINDINGS_FENCE as t };

package/dist/ui-CiapFoik.js

@@ -0,0 +1,658 @@
+import { A as attributeTrace, C as transcriptPath, G as loadHub, J as linksInto, K as dependencyGraph, M as transcriptTitle, S as readSession, Y as refIndex, a as openInApp, at as ConflictError, et as readYaml, h as setArchivedMany, j as traceTranscript, m as ARCHIVE_KINDS, ot as DATA_DIR, q as mainlineEdges, st as WriteError, x as loadSessions } from "./host-BJnrv8xF.js";
+import { j as configSchema } from "./dist-BbamrIPW.js";
+import { t as listProgress } from "./progress-1BfPg2zN.js";
+import { a as remoteMode, b as isSynced, g as readDaemon, m as callDaemon, n as hubWriter, p as DaemonUnavailable, r as writtenLines, x as syncPaths, y as SYNC_DIR } from "./operation-Bp4U2bx3.js";
+import { l as CLI_VERSION } from "./launch-DefacJEL.js";
+import { createRequire } from "node:module";
+import { closeSync, existsSync, lstatSync, openSync, readFileSync, readSync, realpathSync, statSync, watch } from "node:fs";
+import { basename, dirname, extname, join, normalize, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+//#region src/server.ts
+/**
+* The header a write's response carries when the write did more than change the hub: in remote mode it waits in the
+* outbox for the sync server, maybe with no sync client to send it, or the operation noted something. Its value is
+* this shape as URI-encoded JSON.
+*/
+const WRITE_HEADER = "x-mainflow-write";
+/** Every reference with a hub prefix in the documents of `hub`: links, origins and replaced items. */
+function prefixedRefs(hub) {
+	const refs = [];
+	const doc = (d) => refs.push(d.origin, ...(d.links ?? []).map((l) => l.to));
+	for (const m of hub.mainlines) {
+		doc(m);
+		refs.push(...m.criteria.map((c) => c.supersededBy));
+		for (const d of m.decisions) doc(d);
+		for (const t of m.tasks) {
+			doc(t);
+			refs.push(...t.checklist.map((c) => c.supersededBy));
+		}
+	}
+	for (const d of [...hub.issues, ...hub.findings]) doc(d);
+	return [...new Set(refs.filter((r) => !!r && /^[a-z0-9-]+:/.test(r)))];
+}
+function relationsView(hub) {
+	const own = refIndex(hub);
+	const indexes = new Map(hub.remotes.flatMap((r) => r.hub ? [[r.name, refIndex(r.hub)]] : []));
+	const targets = {};
+	const graph = dependencyGraph(hub);
+	const depRefs = graph.edges.flatMap((e) => [e.from, e.to]);
+	for (const ref of /* @__PURE__ */ new Set([...prefixedRefs(hub), ...depRefs.filter((r) => r.includes(":"))])) {
+		const colon = ref.indexOf(":");
+		const name = ref.slice(0, colon);
+		const found = name === hub.config.hub ? own.get(ref.slice(colon + 1)) : indexes.get(name)?.get(ref.slice(colon + 1));
+		if (found) targets[ref] = found;
+	}
+	const backlinks = {};
+	const add = (to, link) => (backlinks[to] ??= []).push(link);
+	for (const { to, link } of linksInto(hub, void 0)) add(to, {
+		...link,
+		...pick(own.get(link.from))
+	});
+	for (const remote of hub.remotes) {
+		if (!remote.hub) continue;
+		const index = indexes.get(remote.name);
+		for (const { to, link } of linksInto(remote.hub, hub.config.hub)) add(to, {
+			...link,
+			from: `${remote.name}:${link.from}`,
+			...pick(index?.get(link.from))
+		});
+	}
+	return {
+		hubs: hub.remotes.map((r) => ({
+			name: r.name,
+			path: r.path,
+			available: !!r.hub,
+			...r.unavailable ? { reason: r.unavailable } : {}
+		})),
+		targets,
+		backlinks,
+		deps: graph.edges,
+		mainlineDeps: mainlineEdges(graph),
+		cycles: graph.cycles
+	};
+}
+const pick = (t) => t ? {
+	title: t.title,
+	status: t.status
+} : {};
+const CONTENT_TYPES = {
+	".html": "text/html; charset=utf-8",
+	".md": "text/markdown; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".vue": "text/plain; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".txt": "text/plain; charset=utf-8"
+};
+function summarize(m) {
+	return {
+		id: m.id,
+		title: m.title,
+		status: m.status,
+		created: m.created,
+		archivedAt: m.archivedAt ?? null,
+		category: m.category ?? null,
+		priority: m.priority ?? null,
+		labels: m.labels ?? [],
+		due: m.due ?? null,
+		updated: [
+			m,
+			...m.tasks,
+			...m.decisions
+		].map((d) => d.updated).reduce((a, b) => b > a ? b : a),
+		tasks: {
+			total: m.tasks.length,
+			done: m.tasks.filter((t) => t.status === "done").length
+		},
+		items: listProgress(m.tasks.flatMap((t) => t.checklist)),
+		criteria: listProgress(m.criteria),
+		decisions: m.decisions.length
+	};
+}
+/**
+* HTTP API over one hub. The CLI `ui` command and the web dev server both mount it, through createUiApp. Writes go
+* through the hub's writer (src/remote/operation.ts), so in remote mode they are operations the sync server applies;
+* `env` gives the sync server and token as the environment variables do, `{}` for a hub other than the process's own.
+*/
+function createApp(root, options = {}) {
+	const app = new Hono();
+	const mainlinesRoot = join(root, DATA_DIR, "mainlines");
+	const writer = hubWriter(root, options.env);
+	const notes = /* @__PURE__ */ new WeakMap();
+	const write = async (c, op, input) => {
+		const written = await writer(op, input);
+		for (const line of writtenLines(written)) if (line.startsWith("!")) console.log(`mainflow ui: ${line}`);
+		if (written.queued || written.notices.length) {
+			const before = notes.get(c) ?? {
+				queued: false,
+				notices: []
+			};
+			const note = {
+				queued: before.queued || written.queued,
+				...written.stopped ?? before.stopped ? { stopped: written.stopped ?? before.stopped } : {},
+				...written.restarted ?? before.restarted ? { restarted: written.restarted ?? before.restarted } : {},
+				notices: [...before.notices, ...written.notices]
+			};
+			notes.set(c, note);
+			c.header(WRITE_HEADER, encodeURIComponent(JSON.stringify(note)));
+		}
+		return written;
+	};
+	app.onError((error, c) => {
+		const message = error.message.replaceAll(`${root}${sep}`, "");
+		if (error instanceof ConflictError) return c.json({ error: message }, 409);
+		if (error instanceof WriteError) return c.json({ error: message }, 400);
+		throw error;
+	});
+	app.get("/api/hub", (c) => {
+		const hub = loadHub(root);
+		const body = {
+			hub: hub.config.hub,
+			version: CLI_VERSION,
+			repos: hub.config.repos,
+			mainlines: hub.mainlines.map(summarize),
+			openIssues: hub.issues.filter((i) => i.status !== "closed").length,
+			validFindings: hub.findings.filter((f) => f.status === "valid").length,
+			problems: hub.problems
+		};
+		return c.json(body);
+	});
+	app.get("/api/relations", (c) => c.json(relationsView(loadHub(root))));
+	const local = () => loadHub(root, { remotes: false });
+	app.get("/api/issues", (c) => c.json(local().issues));
+	app.get("/api/findings", (c) => c.json(local().findings));
+	app.get("/api/ops", (c) => c.json(local().ops));
+	app.post("/api/reveal", async (c) => {
+		const { path } = await c.req.json();
+		const known = loadSessions(root).sessions.some((s) => s.transcript === path);
+		const file = transcriptPath(root, path);
+		if (!known || !existsSync(file)) return c.json({ error: "only a transcript recorded on a session can be revealed" }, 400);
+		const opened = spawnSync("open", ["-R", file]);
+		return opened.status === 0 ? c.json({ revealed: file }) : c.json({ error: `open -R failed: ${opened.stderr}` }, 500);
+	});
+	app.get("/api/mainlines", (c) => {
+		const ids = c.req.query("ids")?.split(",").filter(Boolean);
+		const all = local().mainlines;
+		return c.json(ids ? all.filter((m) => ids.includes(m.id)) : all.filter((m) => !m.archivedAt));
+	});
+	app.get("/api/mainlines/:m", (c) => {
+		const mainline = local().mainlines.find((m) => m.id === c.req.param("m"));
+		return mainline ? c.json(mainline) : c.json({ error: `mainline ${c.req.param("m")} not found` }, 404);
+	});
+	const titles = /* @__PURE__ */ new Map();
+	const titleOf = (recorded) => {
+		const transcript = recorded && transcriptPath(root, recorded);
+		if (!transcript || !existsSync(transcript)) return void 0;
+		const { size, mtimeMs } = statSync(transcript);
+		const stamp = `${size}:${mtimeMs}`;
+		const cached = titles.get(transcript);
+		if (cached?.stamp === stamp) return cached.title;
+		const title = transcriptTitle(transcript);
+		titles.set(transcript, {
+			stamp,
+			title
+		});
+		return title;
+	};
+	app.get("/api/sessions", (c) => {
+		const { sessions, problems } = loadSessions(root);
+		const views = sessions.map((s) => {
+			const title = titleOf(s.transcript);
+			return {
+				...s,
+				...title ? { title } : {},
+				...runsElsewhere(root, s) ? { elsewhere: true } : {}
+			};
+		});
+		return c.json({
+			sessions: views,
+			problems
+		});
+	});
+	app.post("/api/archive", async (c) => {
+		const { kind, ids, archived } = await c.req.json();
+		if (!ARCHIVE_KINDS.includes(kind) || !Array.isArray(ids)) return c.json({ error: `kind must be one of ${ARCHIVE_KINDS.join(", ")} and ids a list` }, 400);
+		return c.json(await setArchivedMany(kind, ids, archived, (op, input) => write(c, op, input)));
+	});
+	app.post("/api/sessions/:id/archive", async (c) => {
+		const { archived } = await c.req.json();
+		return c.json((await write(c, "session.archive", {
+			id: c.req.param("id"),
+			archived
+		})).value);
+	});
+	app.post("/api/issues/:id/archive", async (c) => {
+		const { archived, version } = await c.req.json();
+		return c.json((await write(c, "issue.archive", {
+			id: c.req.param("id"),
+			archived,
+			expectedVersion: version
+		})).value);
+	});
+	app.post("/api/findings/:id/archive", async (c) => {
+		const { archived, version } = await c.req.json();
+		return c.json((await write(c, "finding.archive", {
+			id: c.req.param("id"),
+			archived,
+			expectedVersion: version
+		})).value);
+	});
+	app.get("/api/sessions/:id/trace", (c) => {
+		const session = readSession(root, c.req.param("id"));
+		if (!session) return c.json({ error: `session ${c.req.param("id")} not found` }, 404);
+		const transcript = session.transcript && transcriptPath(root, session.transcript);
+		if (!transcript || !existsSync(transcript)) return c.json({
+			available: false,
+			byAction: {},
+			unattributed: []
+		});
+		const trace = traceTranscript(transcript, { home: homedir() });
+		return c.json({
+			available: true,
+			model: trace.model ?? session.model,
+			...attributeTrace(trace, session.actions)
+		});
+	});
+	app.get("/api/files/*", (c) => {
+		const path = normalize(decodeURIComponent(c.req.path.slice(11)));
+		const file = join(root, path);
+		if (!file.startsWith(mainlinesRoot + sep) || !existsSync(file) || !statSync(file).isFile()) return c.json({ error: `file ${path} not found under ${relative(root, mainlinesRoot)}` }, 404);
+		return c.body(readFileSync(file), 200, { "content-type": CONTENT_TYPES[extname(file)] ?? "application/octet-stream" });
+	});
+	app.post("/api/mainlines/:m/archive", async (c) => {
+		const { archived, version } = await c.req.json();
+		return c.json((await write(c, "mainline.archive", {
+			id: c.req.param("m"),
+			archived,
+			expectedVersion: version
+		})).value);
+	});
+	app.post("/api/mainlines/:m/title", async (c) => {
+		const { title, version } = await c.req.json();
+		return c.json((await write(c, "mainline.title", {
+			id: c.req.param("m"),
+			title,
+			expectedVersion: version
+		})).value);
+	});
+	app.post("/api/mainlines/:m/status", async (c) => {
+		const { status, version } = await c.req.json();
+		return c.json((await write(c, "mainline.set", {
+			id: c.req.param("m"),
+			status,
+			expectedVersion: version
+		})).value);
+	});
+	app.post("/api/tasks/:m/:t/status", async (c) => {
+		const { status, version } = await c.req.json();
+		return c.json((await write(c, "task.set", {
+			ref: `${c.req.param("m")}/${c.req.param("t")}`,
+			patch: { status },
+			expectedVersion: version
+		})).value);
+	});
+	app.post("/api/check", async (c) => {
+		const { ref, done, evidence, version } = await c.req.json();
+		const input = {
+			ref,
+			done,
+			evidence,
+			expectedVersion: version
+		};
+		return c.json((ref.includes("/") ? await write(c, "item.check", input) : await write(c, "criterion.check", input)).value);
+	});
+	app.get("/api/sync", (c) => c.json({
+		remote: remoteMode(root, options.env),
+		running: readDaemon(root) !== null,
+		notices: readNotices(root)
+	}));
+	app.get("/api/sync/conflicts/:name", async (c) => {
+		const name = c.req.param("name");
+		const saved = `${SYNC_DIR}/conflicts/${name}`;
+		const file = join(syncPaths(root).conflicts, name);
+		const notice = readNotices(root).find((n) => n.saved === saved);
+		if (name.includes("/") || name.startsWith(".") || !existsSync(file) || !notice) return c.json({ error: `no saved text ${saved} named by a notice` }, 404);
+		if (lstatSync(file).isSymbolicLink() || !insideHub(root, file)) return c.json({ error: `${saved} is not a file the sync client saved in the hub` }, 400);
+		const target = isSynced(notice.path) ? join(root, DATA_DIR, notice.path) : null;
+		if (!target || !insideHub(root, target)) return c.json({ error: `the notice for ${saved} names ${JSON.stringify(notice.path)}, not a synced file of the hub` }, 400);
+		return c.json({
+			saved,
+			path: notice.path,
+			mine: readFileSync(file, "utf8"),
+			theirs: await serverVersion(root, notice.path, target)
+		});
+	});
+	app.get("/api/events", (c) => streamSSE(c, async (stream) => {
+		const stop = watchHub(root, (event) => void stream.writeSSE({
+			event: event.kind,
+			data: event.name
+		}));
+		stream.onAbort(stop);
+		while (!stream.aborted) await stream.sleep(3e4);
+	}));
+	return app;
+}
+/**
+* Whether a session runs in another environment: its working directory is not on this machine, and neither is a
+* transcript it recorded. A session of this machine whose worktree was removed still has its transcript here.
+*/
+function runsElsewhere(root, session) {
+	if (existsSync(session.cwd)) return false;
+	return !(session.transcript && existsSync(transcriptPath(root, session.transcript)));
+}
+/** Every warn-level line of .mainflow/local/sync/notices.jsonl, newest first; unreadable lines are skipped. */
+function readNotices(root) {
+	const file = syncPaths(root).notices;
+	if (!existsSync(file)) return [];
+	const notices = [];
+	for (const line of readFileSync(file, "utf8").split("\n")) {
+		const notice = parseWarn(line);
+		if (notice) notices.push(notice);
+	}
+	return notices.reverse();
+}
+function parseWarn(line) {
+	if (!line.trim()) return null;
+	try {
+		const { at, level, kind, path, message, saved } = JSON.parse(line);
+		if (level !== "warn" || typeof at !== "string" || typeof kind !== "string" || typeof message !== "string") return null;
+		return {
+			at,
+			kind,
+			path: typeof path === "string" ? path : "",
+			message,
+			...typeof saved === "string" ? { saved } : {}
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Whether `file` really is inside the hub's .mainflow/ once every symbolic link on the way is followed. A file that
+* does not exist yet is judged by the deepest directory above it that does.
+*/
+function insideHub(root, file) {
+	let data;
+	try {
+		data = realpathSync(join(root, DATA_DIR));
+	} catch {
+		return false;
+	}
+	let existing = resolve(file);
+	const rest = [];
+	for (;;) try {
+		return join(realpathSync(existing), ...rest).startsWith(`${data}${sep}`);
+	} catch {
+		if (lstatSync(existing, { throwIfNoEntry: false })) return false;
+		const parent = dirname(existing);
+		if (parent === existing) return false;
+		rest.unshift(basename(existing));
+		existing = parent;
+	}
+}
+/**
+* The file at `path` as the hub has it: from the running sync client's copy of the server's version, else this
+* machine's file at `file`, already checked to be inside the hub.
+*/
+async function serverVersion(root, path, file) {
+	const daemon = readDaemon(root);
+	if (daemon) try {
+		const { text } = await callDaemon(daemon, "/file", { path }, 5e3);
+		if (text !== void 0) return {
+			text,
+			source: "server"
+		};
+	} catch (error) {
+		if (!(error instanceof DaemonUnavailable)) throw error;
+	}
+	return {
+		text: existsSync(file) ? readFileSync(file, "utf8") : null,
+		source: "local"
+	};
+}
+/**
+* What the interface does about a change at `name`, relative to .mainflow/: reload (`change`), check the sync
+* client's notices (`notices`), or nothing. The sync client's own state under local/sync/ (known.json, queue.json,
+* the conflicts it saves, its tmp/) is not the hub's content, so writing it reloads nothing; notices.jsonl only
+* matters when a warn-level line arrives. Lock and temporary files are left out as well.
+*/
+function eventOf(name) {
+	const path = name.split(sep).join("/");
+	if (path === `local/sync/notices.jsonl`) return "notices";
+	if (path === "local/sync" || path.startsWith(`local/sync/`)) return null;
+	if (path.endsWith("write.lock") || path.endsWith(".tmp")) return null;
+	return "change";
+}
+/** One file watcher per hub, shared by every listener of that hub. */
+var HubWatch = class {
+	root;
+	listeners = /* @__PURE__ */ new Set();
+	watcher;
+	/** How far notices.jsonl has been read */
+	offset;
+	constructor(root) {
+		this.root = root;
+		this.offset = sizeOf(syncPaths(root).notices);
+		this.watcher = watch(join(root, DATA_DIR), { recursive: true }, (_event, name) => {
+			const kind = name ? eventOf(String(name)) : null;
+			if (kind === null || kind === "notices" && !this.newWarnings()) return;
+			const event = {
+				kind: kind === "change" ? "change" : "notice",
+				name: String(name)
+			};
+			for (const notify of this.listeners) notify(event);
+		});
+		this.watcher.on("error", () => void 0);
+	}
+	close() {
+		this.watcher.close();
+	}
+	/** Whether the lines added to notices.jsonl since the last read hold a warn-level notice. */
+	newWarnings() {
+		const file = syncPaths(this.root).notices;
+		const size = sizeOf(file);
+		if (size < this.offset) this.offset = 0;
+		if (size === this.offset) return false;
+		const buffer = Buffer.alloc(size - this.offset);
+		let fd;
+		try {
+			fd = openSync(file, "r");
+		} catch {
+			this.offset = 0;
+			return false;
+		}
+		let read;
+		try {
+			read = readSync(fd, buffer, 0, buffer.length, this.offset);
+		} finally {
+			closeSync(fd);
+		}
+		const complete = buffer.subarray(0, read).lastIndexOf(10) + 1;
+		this.offset += complete;
+		return buffer.subarray(0, complete).toString("utf8").split("\n").some((line) => parseWarn(line) !== null);
+	}
+};
+const watches = /* @__PURE__ */ new Map();
+/** The size of a file, 0 when it does not exist; it may be removed between any two calls, so it is read in one. */
+function sizeOf(file) {
+	try {
+		return statSync(file).size;
+	} catch {
+		return 0;
+	}
+}
+/**
+* Call `listener` for every change the interface reloads on, and once for each batch of new warn-level notices.
+* Every listener of a hub shares one file watcher, which closes with the last of them. Returns the unsubscribe.
+*/
+function watchHub(root, listener) {
+	const key = resolve(root);
+	const hub = watches.get(key) ?? new HubWatch(key);
+	watches.set(key, hub);
+	hub.listeners.add(listener);
+	return () => {
+		hub.listeners.delete(listener);
+		if (hub.listeners.size > 0) return;
+		hub.close();
+		watches.delete(key);
+	};
+}
+/** The hubs this interface serves: its own, then every hub registered in its config.yaml, with each one's root when it is here. */
+function servedHubs(root) {
+	const config = readYaml(join(root, DATA_DIR, "config.yaml"), configSchema).data;
+	const others = Object.entries(config.hubs ?? {}).map(([name, path]) => {
+		const base = `/h/${name}/`;
+		const other = resolve(root, path);
+		const file = join(other, DATA_DIR, "config.yaml");
+		if (name === config.hub) return {
+			name,
+			base,
+			available: false,
+			reason: "this hub"
+		};
+		if (!existsSync(file)) return {
+			name,
+			base,
+			available: false,
+			reason: `not found at ${path} on this machine`
+		};
+		try {
+			const found = readYaml(file, configSchema).data;
+			if (found.hub !== name) return {
+				name,
+				base,
+				available: false,
+				reason: `${path} holds hub "${found.hub}"`
+			};
+			if (found.formatVersion !== 2) return {
+				name,
+				base,
+				available: false,
+				reason: `format ${found.formatVersion}; this mainflow reads format 2`
+			};
+		} catch (error) {
+			return {
+				name,
+				base,
+				available: false,
+				reason: error.message
+			};
+		}
+		return {
+			name,
+			base,
+			available: true,
+			root: other
+		};
+	});
+	return [{
+		name: config.hub,
+		base: "/",
+		available: true,
+		root
+	}, ...others];
+}
+/**
+* The interface's API: this hub at /api, and every registered hub that is on this machine at /h/{name}/api, so one
+* interface follows several hubs and switches between them. /api/hubs lists them, and /api/hubs/events sends every
+* hub's changes and notices tagged with its name, so the switcher shows where something happened. Another hub is
+* written through its own sync settings only, never through this process's environment variables.
+*/
+function createUiApp(root) {
+	const app = new Hono();
+	const own = createApp(root);
+	const others = /* @__PURE__ */ new Map();
+	const appOf = (name) => {
+		const hub = servedHubs(root).find((h) => h.name === name && h.base !== "/");
+		if (!hub?.available || !hub.root) return null;
+		let sub = others.get(hub.root);
+		if (!sub) {
+			sub = createApp(hub.root, { env: {} });
+			others.set(hub.root, sub);
+		}
+		return sub;
+	};
+	app.get("/api/hubs", (c) => {
+		const hubs = servedHubs(root);
+		return c.json({
+			primary: hubs[0].name,
+			hubs: hubs.map(({ root: _root, ...link }) => link)
+		});
+	});
+	app.get("/api/hubs/events", (c) => streamSSE(c, async (stream) => {
+		const stops = servedHubs(root).flatMap((hub) => hub.available && hub.root ? [watchHub(hub.root, (event) => void stream.writeSSE({
+			event: event.kind,
+			data: JSON.stringify({
+				hub: hub.name,
+				name: event.name
+			})
+		}))] : []);
+		stream.onAbort(() => stops.forEach((stop) => stop()));
+		while (!stream.aborted) await stream.sleep(3e4);
+	}));
+	app.all("/h/:name/api/*", (c) => {
+		const name = c.req.param("name");
+		const sub = appOf(name);
+		if (!sub) return c.json({ error: `hub ${name} is not registered in this hub's config.yaml or is not on this machine` }, 404);
+		const url = new URL(c.req.url);
+		url.pathname = url.pathname.slice(`/h/${name}`.length);
+		return sub.fetch(new Request(url, c.req.raw));
+	});
+	app.route("/", own);
+	return app;
+}
+//#endregion
+//#region src/ui.ts
+/**
+* Where the built web client lives: `web/` beside the bundled CLI in the published package, or the
+* workspace's web package when running from source before a bundle exists.
+*/
+function webDir() {
+	const bundled = join(dirname(fileURLToPath(import.meta.url)), "web");
+	if (existsSync(join(bundled, "index.html"))) return bundled;
+	return join(dirname(createRequire(import.meta.url).resolve("@carlos-space/mainflow-web/package.json")), "dist");
+}
+/**
+* Serve the API plus the built web client; unknown paths fall back to index.html for client-side routing.
+* Resolves once the port is listening. A port taken between the free-port probe and here rejects with a
+* WriteError instead of Node's unhandled 'error' event and stack trace.
+*/
+function serveUi(root, port, open = openInApp) {
+	const app = createUiApp(root);
+	const dist = webDir();
+	const hub = loadHub(root, { remotes: false }).config.hub;
+	app.get("/open/*", (c) => {
+		const url = new URL(c.req.url);
+		const target = `${url.pathname.slice(5) || "/"}${url.search}`;
+		const opened = open(hub, target);
+		return c.html(openPage(target, opened));
+	});
+	app.get("*", (c) => {
+		let file = join(dist, normalize(decodeURIComponent(c.req.path)));
+		if (!file.startsWith(dist + sep) || !existsSync(file) || !statSync(file).isFile()) file = join(dist, "index.html");
+		return c.body(readFileSync(file), 200, { "content-type": CONTENT_TYPES[extname(file)] ?? "application/octet-stream" });
+	});
+	return new Promise((done, fail) => {
+		const server = serve({
+			fetch: app.fetch,
+			port
+		}, () => done(server));
+		server.once("error", (error) => fail(error.code === "EADDRINUSE" ? new WriteError(`port ${port} is already in use; run mainflow ui again to pick another`) : error));
+	});
+}
+/** The page an /open link leaves in the browser: blank in the interface's colours, or a jump to the address. */
+function openPage(target, opened) {
+	const escaped = target.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+	return `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark">${opened ? "" : `<meta http-equiv="refresh" content="0;url=${escaped}">`}<title>mainflow</title><style>html{background:#fff}@media (prefers-color-scheme: dark){html{background:#111113}}</style>`;
+}
+//#endregion
+export { serveUi };