mainflow 0.6.0

package/dist/launch-BR70uSMc.js

@@ -0,0 +1,584 @@
+import { B as refIndex, G as DATA_DIR, I as setIssueArchived, P as setFindingArchived, R as loadHub, U as ConflictError, W as WriteError, b as setSessionArchived, d as setChecklistItem, f as setCriterion, h as updateTask, p as setMainlineStatus, u as setArchived, v as loadSessions, w as transcriptPath, y as readSession, z as linksInto } from "./dist-BktkzRuK.js";
+import { DEFAULT_UI_PORT, syncHost } from "./host.js";
+import { createRequire } from "node:module";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, watch, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, normalize, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import { serve } from "@hono/node-server";
+import { homedir } from "node:os";
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+//#region ../core/dist/trace.js
+const HOOK_BLOCK = /^(\w+:\w+) hook error:\s*(.*)$/s;
+const SCRIPT_IN_COMMAND = /(\S+\.(?:mjs|cjs|js|sh|py|ts))\b/;
+/**
+* Rules live under a rules/ directory. Everything else the instructions record loads at session start is
+* an instruction, including files CLAUDE.md pulls in with @imports. A nested memory outside rules/ is an
+* instruction only when it is a CLAUDE.md or AGENTS.md of a subdirectory.
+*/
+const isRule = (path) => /\/rules\//.test(path);
+const startupKind = (path) => isRule(path) ? "rule" : "instruction";
+const nestedKind = (path) => isRule(path) ? "rule" : /(^|\/)(CLAUDE|AGENTS)(\.local)?\.md$/.test(path) ? "instruction" : "file";
+/** Where an installed skill or agent definition sits: the project's .claude first, then the user's. */
+function installed(kind, name, cwd, home) {
+	const leaf = kind === "skills" ? join(name, "SKILL.md") : `${name}.md`;
+	return [...cwd ? [join(cwd, ".claude", kind, leaf)] : [], join(home, ".claude", kind, leaf)].find((p) => existsSync(p));
+}
+function traceTranscript(file, options) {
+	const entries = [];
+	let model;
+	if (!existsSync(file)) return { entries };
+	for (const line of readFileSync(file, "utf8").split("\n")) {
+		if (!line.trim()) continue;
+		let record;
+		try {
+			record = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		const at = record.timestamp;
+		if (!at) continue;
+		const a = record.attachment;
+		if (a?.type === "model" && a.identity?.modelId) model = a.identity.modelId;
+		if (a?.type === "nested_memory" && a.path) entries.push({
+			at,
+			kind: nestedKind(a.path),
+			name: basename(a.path),
+			path: a.path
+		});
+		if (a?.type === "instructions") {
+			for (const f of a.files ?? []) if (f.path) entries.push({
+				at,
+				kind: startupKind(f.path),
+				name: basename(f.path),
+				path: f.path
+			});
+		}
+		if ((a?.type === "hook_success" || a?.type === "hook_additional_context") && a.hookName) {
+			const script = a.command?.match(SCRIPT_IN_COMMAND)?.[1]?.replace("$HOME", options.home);
+			entries.push({
+				at,
+				kind: "hook",
+				name: a.hookName,
+				...script ? { path: script } : {},
+				...a.exitCode !== void 0 ? { detail: `exit ${a.exitCode}` } : {}
+			});
+		}
+		const content = Array.isArray(record.message?.content) ? record.message.content : [];
+		if (record.type === "assistant" && record.message?.model && record.message.model !== "<synthetic>") model = record.message.model;
+		for (const block of content) {
+			if (block.type === "tool_use") {
+				const input = block.input ?? {};
+				if (block.name === "Skill" && typeof input.skill === "string") {
+					const path = installed("skills", input.skill, record.cwd, options.home);
+					entries.push({
+						at,
+						kind: "skill",
+						name: input.skill,
+						...path ? { path } : {}
+					});
+				}
+				if ((block.name === "Agent" || block.name === "Task") && typeof input.subagent_type === "string") {
+					const path = installed("agents", input.subagent_type, record.cwd, options.home);
+					entries.push({
+						at,
+						kind: "agent",
+						name: input.subagent_type,
+						...path ? { path } : {}
+					});
+				}
+				if (block.name === "Read" && typeof input.file_path === "string") entries.push({
+					at,
+					kind: "file",
+					name: basename(input.file_path),
+					path: input.file_path
+				});
+			}
+			if (block.type === "tool_result" && block.is_error) {
+				const blocked = (typeof block.content === "string" ? block.content : JSON.stringify(block.content ?? "")).match(HOOK_BLOCK);
+				if (blocked) entries.push({
+					at,
+					kind: "hook",
+					name: blocked[1],
+					detail: `blocked: ${blocked[2].slice(0, 120)}`
+				});
+			}
+		}
+	}
+	return {
+		...model ? { model } : {},
+		entries
+	};
+}
+/** Titles are appended again as the conversation goes on, so the end of the file almost always holds the latest. */
+const TITLE_TAIL_BYTES = 262144;
+function readTail(file, bytes) {
+	const size = statSync(file).size;
+	if (size <= bytes) return {
+		text: readFileSync(file, "utf8"),
+		whole: true
+	};
+	const fd = openSync(file, "r");
+	try {
+		const buffer = Buffer.alloc(bytes);
+		readSync(fd, buffer, 0, bytes, size - bytes);
+		return {
+			text: buffer.subarray(buffer.indexOf(10) + 1).toString("utf8"),
+			whole: false
+		};
+	} finally {
+		closeSync(fd);
+	}
+}
+function latestTitle(text) {
+	let custom;
+	let agent;
+	for (const line of text.split("\n")) {
+		if (!line.includes("\"custom-title\"") && !line.includes("\"agent-name\"")) continue;
+		let record;
+		try {
+			record = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (record.type === "custom-title" && record.customTitle?.trim()) custom = record.customTitle.trim();
+		if (record.type === "agent-name" && record.agentName?.trim()) agent = record.agentName.trim();
+	}
+	return custom ?? agent;
+}
+/**
+* The name the conversation goes by: the latest title the user gave it, else the latest name the platform
+* generated. Only the end of the file is read unless it holds no title.
+*/
+function transcriptTitle(file) {
+	if (!existsSync(file)) return void 0;
+	const tail = readTail(file, TITLE_TAIL_BYTES);
+	return latestTitle(tail.text) ?? (tail.whole ? void 0 : latestTitle(readFileSync(file, "utf8")));
+}
+/** Action stamps are local time to the minute; the window closes at the end of the finishing minute. */
+const localMinute = (stamp) => {
+	const [date = "", time = ""] = stamp.split("T");
+	const [y, m, d] = date.split("-").map(Number);
+	const [hh, mm] = time.split(":").map(Number);
+	return new Date(y, m - 1, d, hh, mm).getTime();
+};
+function summarize$1(entries) {
+	const uses = /* @__PURE__ */ new Map();
+	for (const e of entries) {
+		const key = `${e.kind}\u0000${e.path ?? e.name}`;
+		const use = uses.get(key);
+		if (use) use.count += 1;
+		else uses.set(key, {
+			kind: e.kind,
+			name: e.name,
+			...e.path ? { path: e.path } : {},
+			count: 1,
+			first: e.at,
+			...e.detail ? { detail: e.detail } : {}
+		});
+	}
+	return [...uses.values()];
+}
+/**
+* Group trace entries by the action that was doing when they happened. Actions without a start stamp
+* get nothing; entries outside every window are returned as unattributed.
+*/
+function attributeTrace(trace, actions, now = Date.now()) {
+	const windows = actions.filter((a) => a.startedAt).map((a) => ({
+		id: a.id,
+		from: localMinute(a.startedAt),
+		to: a.doneAt ? localMinute(a.doneAt) + 6e4 : now
+	}));
+	const grouped = {};
+	const rest = [];
+	for (const entry of trace.entries) {
+		const t = Date.parse(entry.at);
+		const owner = windows.filter((w) => t >= w.from && t < w.to).sort((x, y) => y.from - x.from)[0];
+		if (owner) (grouped[owner.id] ??= []).push(entry);
+		else rest.push(entry);
+	}
+	return {
+		byAction: Object.fromEntries(Object.entries(grouped).map(([id, list]) => [id, summarize$1(list)])),
+		unattributed: summarize$1(rest)
+	};
+}
+//#endregion
+//#region ../core/dist/progress.js
+function listProgress(items) {
+	const counted = items.filter((item) => !item.dropped);
+	return {
+		done: counted.filter((item) => item.done).length,
+		total: counted.length
+	};
+}
+//#endregion
+//#region src/server.ts
+/** 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 = {};
+	for (const ref of prefixedRefs(hub)) {
+		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
+	};
+}
+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. */
+function createApp(root) {
+	const app = new Hono();
+	const mainlinesRoot = join(root, DATA_DIR, "mainlines");
+	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,
+			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/: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 title ? {
+				...s,
+				title
+			} : s;
+		});
+		return c.json({
+			sessions: views,
+			problems
+		});
+	});
+	app.post("/api/sessions/:id/archive", async (c) => {
+		const { archived } = await c.req.json();
+		return c.json(setSessionArchived(root, c.req.param("id"), archived));
+	});
+	app.post("/api/issues/:id/archive", async (c) => {
+		const { archived, version } = await c.req.json();
+		return c.json(setIssueArchived(root, c.req.param("id"), archived, version));
+	});
+	app.post("/api/findings/:id/archive", async (c) => {
+		const { archived, version } = await c.req.json();
+		return c.json(setFindingArchived(root, c.req.param("id"), archived, version));
+	});
+	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(setArchived(root, c.req.param("m"), archived, version));
+	});
+	app.post("/api/mainlines/:m/status", async (c) => {
+		const { status, version } = await c.req.json();
+		return c.json(setMainlineStatus(root, c.req.param("m"), status, version));
+	});
+	app.post("/api/tasks/:m/:t/status", async (c) => {
+		const { status, version } = await c.req.json();
+		return c.json(updateTask(root, `${c.req.param("m")}/${c.req.param("t")}`, { status }, version));
+	});
+	app.post("/api/check", async (c) => {
+		const { ref, done, evidence, version } = await c.req.json();
+		const result = ref.includes("/") ? setChecklistItem(root, ref, done, evidence, version) : setCriterion(root, ref, done, evidence, version);
+		return c.json(result);
+	});
+	app.get("/api/events", (c) => streamSSE(c, async (stream) => {
+		const watcher = watch(join(root, DATA_DIR), { recursive: true }, (_event, name) => {
+			if (name && !String(name).endsWith("write.lock") && !String(name).endsWith(".tmp")) stream.writeSSE({
+				event: "change",
+				data: String(name)
+			});
+		});
+		stream.onAbort(() => watcher.close());
+		while (!stream.aborted) await stream.sleep(3e4);
+	}));
+	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) {
+	const app = createApp(root);
+	const dist = webDir();
+	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));
+	});
+}
+//#endregion
+//#region src/launch.ts
+/** How many ports above DEFAULT_UI_PORT are tried before giving up. */
+const PORT_SPAN = 100;
+/** Where the last port used is remembered: machine-specific, so under the unversioned local/ folder. */
+const lastPortFile = (root) => join(root, DATA_DIR, "local", "ui.json");
+function readLastPort(root) {
+	try {
+		const port = JSON.parse(readFileSync(lastPortFile(root), "utf8")).port;
+		return Number.isInteger(port) ? port : void 0;
+	} catch {
+		return;
+	}
+}
+function writeLastPort(root, port) {
+	mkdirSync(join(root, DATA_DIR, "local"), { recursive: true });
+	writeFileSync(lastPortFile(root), `${JSON.stringify({ port })}\n`);
+}
+/**
+* Ports to try, in order. An explicit --port is the only candidate: the user asked for that port. Otherwise
+* the hub's configured port, then the last one used, then the default range.
+*/
+function portCandidates(options) {
+	if (options.explicit !== void 0) return [options.explicit];
+	const range = Array.from({ length: 100 }, (_, i) => DEFAULT_UI_PORT + i);
+	return [...new Set([
+		options.configured,
+		options.last,
+		...range
+	].filter((p) => p !== void 0))];
+}
+const networkProbe = {
+	async hubAt(port) {
+		try {
+			const res = await fetch(`http://localhost:${port}/api/hub`, { signal: AbortSignal.timeout(500) });
+			if (!res.ok) return null;
+			const body = await res.json();
+			return typeof body.hub === "string" ? body.hub : null;
+		} catch {
+			return null;
+		}
+	},
+	isFree: (port) => new Promise((done) => {
+		const probe = createServer().once("error", () => done(false));
+		probe.listen(port, () => probe.close(() => done(true)));
+	})
+};
+/**
+* A candidate already serving this hub wins wherever it sits in the order, so a lost last-port record or a
+* changed ui.port never starts a second copy; all candidates are asked at once, bounding the wait by one
+* probe timeout. Otherwise the first free candidate; ports held by another hub or program are skipped.
+*/
+async function choosePort(hub, candidates, probe = networkProbe) {
+	const owners = await Promise.all(candidates.map((port) => probe.hubAt(port)));
+	const running = candidates.find((_, i) => owners[i] === hub);
+	if (running !== void 0) return {
+		port: running,
+		running: true
+	};
+	for (const [i, port] of candidates.entries()) if (owners[i] === null && await probe.isFree(port)) return {
+		port,
+		running: false
+	};
+	const tried = candidates.length === 1 ? `port ${candidates[0]} is` : `ports ${candidates[0]} to ${candidates.at(-1)} are`;
+	throw new WriteError(`${tried} taken by other programs; free one, or pass --port <port>`);
+}
+/** Open a URL in the default browser without waiting for it. */
+function openUrl(url) {
+	const [command, ...args] = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? [
+		"cmd",
+		"/c",
+		"start",
+		"",
+		url
+	] : ["xdg-open", url];
+	spawn(command, args, {
+		detached: true,
+		stdio: "ignore"
+	}).on("error", () => console.log(`open ${url} in a browser`)).unref();
+}
+/** Start or reuse this hub's interface: the URL it is reached at, and the server when this call started one. */
+async function launchUi(root, hub, configured, options) {
+	const log = options.log ?? console.log;
+	let explicit;
+	if (options.port !== void 0) {
+		explicit = Number(options.port);
+		if (!Number.isInteger(explicit) || explicit < 1024 || explicit > 65535) throw new WriteError("--port must be an integer from 1024 to 65535, e.g. --port 4320");
+	}
+	const choice = await choosePort(hub, portCandidates({
+		explicit,
+		configured,
+		last: readLastPort(root)
+	}), options.probe);
+	let server;
+	if (!choice.running) {
+		server = await serveUi(root, choice.port);
+		writeLastPort(root, choice.port);
+	}
+	const host = await syncHost(root, hub, choice.port, options.host);
+	if (host.url === null) log(`! host name not available: ${host.reason}`);
+	const url = host.url ?? `http://localhost:${choice.port}`;
+	log(`${choice.running ? "already running" : "mainflow ui"}: ${url} (localhost:${choice.port})`);
+	if (options.open) openUrl(url);
+	return {
+		url,
+		server
+	};
+}
+//#endregion
+export { portCandidates as a, networkProbe as i, choosePort as n, readLastPort as o, launchUi as r, listProgress as s, PORT_SPAN as t };

package/dist/launch.d.ts

@@ -0,0 +1,44 @@
+import { HostOptions } from "./host.js";
+import { ServerType } from "@hono/node-server";
+//#region src/launch.d.ts
+/** How many ports above DEFAULT_UI_PORT are tried before giving up. */
+export declare const PORT_SPAN = 100;
+export declare function readLastPort(root: string): number | undefined;
+/**
+ * Ports to try, in order. An explicit --port is the only candidate: the user asked for that port. Otherwise
+ * the hub's configured port, then the last one used, then the default range.
+ */
+export declare function portCandidates(options: {
+  explicit?: number;
+  configured?: number;
+  last?: number;
+}): number[];
+export interface PortProbe {
+  /** The hub name a mainflow interface on this port reports, or null when nothing mainflow answers. */
+  hubAt: (port: number) => Promise<string | null>;
+  isFree: (port: number) => Promise<boolean>;
+}
+export declare const networkProbe: PortProbe;
+export type PortChoice = {
+  port: number;
+  running: boolean;
+};
+/**
+ * A candidate already serving this hub wins wherever it sits in the order, so a lost last-port record or a
+ * changed ui.port never starts a second copy; all candidates are asked at once, bounding the wait by one
+ * probe timeout. Otherwise the first free candidate; ports held by another hub or program are skipped.
+ */
+export declare function choosePort(hub: string, candidates: number[], probe?: PortProbe): Promise<PortChoice>;
+export interface LaunchOptions {
+  port?: string;
+  open: boolean;
+  probe?: PortProbe;
+  host?: HostOptions;
+  log?: (line: string) => void;
+}
+/** Start or reuse this hub's interface: the URL it is reached at, and the server when this call started one. */
+export declare function launchUi(root: string, hub: string, configured: number | undefined, options: LaunchOptions): Promise<{
+  url: string;
+  server?: ServerType;
+}>;
+//#endregion

package/dist/launch.js

@@ -0,0 +1,2 @@
+import { a as portCandidates, i as networkProbe, n as choosePort, o as readLastPort, r as launchUi, t as PORT_SPAN } from "./launch-BR70uSMc.js";
+export { PORT_SPAN, choosePort, launchUi, networkProbe, portCandidates, readLastPort };