@treeport/treeport 0.1.0

package/dist/node/cli/index.js

@@ -0,0 +1,865 @@
+#!/usr/bin/env node
+import { E as parseTerminalRuntimeMetadata, _ as SOCKET_IO_PATH, g as parseProductEvent, h as parseEventsSnapshot, t as TERMINAL_CAPTURE_MAX_LINES } from "../../dist-CUkImh2W.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Command, CommanderError } from "commander";
+import { io } from "socket.io-client";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import fsSync from "node:fs";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+//#region src/cli/args.ts
+function extractJsonOutput(args) {
+	const separator = args.indexOf("--");
+	const index = args.findIndex((value, valueIndex) => value === "--json" && (separator === -1 || valueIndex < separator));
+	if (index === -1) return false;
+	args.splice(index, 1);
+	return true;
+}
+//#endregion
+//#region src/cli/lifecycle.ts
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 8733;
+function listenerUrl(host, port) {
+	return `http://${host.includes(":") && !host.startsWith("[") ? `[${host}]` : host}:${port}`;
+}
+function expandHome(value) {
+	return value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+}
+function localPaths(env = process.env) {
+	const defaultDataDir = env.XDG_DATA_HOME ? path.join(expandHome(env.XDG_DATA_HOME), "treeport") : process.platform === "darwin" ? path.join(os.homedir(), "Library", "Application Support", "treeport") : path.join(os.homedir(), ".local", "share", "treeport");
+	const dataDir = path.resolve(expandHome(env.TREEPORT_DATA_DIR?.trim() || defaultDataDir));
+	const runtimeDir = path.resolve(expandHome(env.TREEPORT_RUNTIME_DIR?.trim() || (env.XDG_RUNTIME_DIR ? path.join(env.XDG_RUNTIME_DIR, "treeport") : path.join(os.tmpdir(), `treeport-${process.getuid?.() ?? "user"}`))));
+	return {
+		dataDir,
+		runtimeDir,
+		preferencesPath: path.join(dataDir, "config.json"),
+		statePath: path.join(runtimeDir, "daemon.json"),
+		lockPath: path.join(dataDir, "daemon.lock"),
+		logPath: path.join(dataDir, "logs", "daemon.log")
+	};
+}
+async function readJson(filePath) {
+	return fs.readFile(filePath, "utf8").then((value) => JSON.parse(value)).catch(() => null);
+}
+async function preferences() {
+	return await readJson(localPaths().preferencesPath) ?? {};
+}
+async function resolveLocalApiUrl() {
+	const explicit = process.env.TREEPORT_API_URL?.trim();
+	if (explicit) return explicit.replace(/\/$/, "");
+	const saved = await preferences();
+	return listenerUrl(process.env.TREEPORT_HOST?.trim() || process.env.HOST?.trim() || saved.host || DEFAULT_HOST, Number.parseInt(process.env.TREEPORT_PORT?.trim() || process.env.PORT?.trim() || String(saved.port ?? DEFAULT_PORT), 10));
+}
+async function resolvePackagePath(...segments) {
+	const candidates = [fileURLToPath(new URL("../../../", import.meta.url)), fileURLToPath(new URL("../../", import.meta.url))];
+	for (const candidate of candidates) if (await fs.access(path.join(candidate, "package.json")).then(() => true).catch(() => false)) return path.join(candidate, ...segments);
+	throw new Error("Could not locate the Treeport package directory");
+}
+async function treeportVersion() {
+	return (await readJson(await resolvePackagePath("package.json")))?.version ?? "development";
+}
+function processExists(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+async function health(apiUrl, timeoutMs = 1500) {
+	const signal = AbortSignal.timeout(timeoutMs);
+	return fetch(`${apiUrl}/api/health`, { signal }).then(async (response) => {
+		if (!response.ok) return null;
+		const value = await response.json();
+		return value.ok && typeof value.pid === "number" ? value : null;
+	}).catch(() => null);
+}
+function matchesOwnership(state, observed) {
+	return observed.pid === state.pid && observed.instanceId === state.instanceId && path.resolve(state.dataDir) === localPaths().dataDir;
+}
+async function readState() {
+	const value = await readJson(localPaths().statePath);
+	return value && typeof value.pid === "number" && typeof value.instanceId === "string" && typeof value.apiUrl === "string" && typeof value.dataDir === "string" ? value : null;
+}
+async function removeStaleState(state) {
+	const paths = localPaths();
+	for (const filePath of [paths.statePath, paths.lockPath]) if ((await readJson(filePath))?.instanceId === state.instanceId) await fs.rm(filePath, { force: true });
+}
+async function stopOwned(state) {
+	if (!processExists(state.pid)) {
+		await removeStaleState(state);
+		return;
+	}
+	const observed = await health(state.apiUrl);
+	if (!observed || !matchesOwnership(state, observed)) throw new Error(`Refusing to stop PID ${state.pid}: Treeport could not verify ownership. Check ${localPaths().statePath}.`);
+	process.kill(state.pid, "SIGTERM");
+	const deadline = Date.now() + 7e3;
+	while (Date.now() < deadline) {
+		if (!processExists(state.pid)) {
+			await removeStaleState(state);
+			return;
+		}
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	throw new Error(`Treeport did not stop within 7 seconds. See ${localPaths().logPath}.`);
+}
+async function executableCheck(executable, args) {
+	return new Promise((resolve) => {
+		const child = spawn(executable, args, { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		let output = "";
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (chunk) => {
+			output += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			output += chunk;
+		});
+		child.once("error", (error) => resolve({
+			ok: false,
+			detail: error.message
+		}));
+		child.once("close", (code) => resolve({
+			ok: code === 0,
+			detail: output.trim() || `exited with status ${code ?? 1}`
+		}));
+	});
+}
+async function runDoctor() {
+	const paths = localPaths();
+	const gitPath = process.env.TREEPORT_GIT_PATH?.trim() || "git";
+	const tmuxPath = process.env.TREEPORT_TMUX_PATH?.trim() || "tmux";
+	const [git, tmux] = await Promise.all([executableCheck(gitPath, ["--version"]), executableCheck(tmuxPath, ["-V"])]);
+	const tmuxMatch = /tmux\s+(\d+)\.(\d+)/i.exec(tmux.detail);
+	const tmuxSupported = Boolean(tmux.ok && tmuxMatch && (Number(tmuxMatch[1]) > 3 || Number(tmuxMatch[1]) === 3 && Number(tmuxMatch[2]) >= 2));
+	const checkDirectory = (directoryPath) => fs.mkdir(directoryPath, {
+		recursive: true,
+		mode: 448
+	}).then(() => ({
+		ok: true,
+		detail: directoryPath
+	})).catch((error) => ({
+		ok: false,
+		detail: `${directoryPath}: ${error instanceof Error ? error.message : String(error)}`
+	}));
+	const [dataDirectory, runtimeDirectory] = await Promise.all([checkDirectory(paths.dataDir), checkDirectory(paths.runtimeDir)]);
+	return [
+		{
+			name: "Node",
+			ok: true,
+			detail: process.version
+		},
+		{
+			name: "Git",
+			...git
+		},
+		{
+			name: "tmux",
+			ok: tmuxSupported,
+			detail: tmuxSupported ? tmux.detail : `${tmux.detail}. Treeport requires tmux 3.2 or newer.`
+		},
+		{
+			name: "Data directory",
+			...dataDirectory
+		},
+		{
+			name: "Runtime directory",
+			...runtimeDirectory
+		}
+	];
+}
+async function daemonStatus() {
+	const state = await readState();
+	if (!state) return {
+		running: false,
+		state: null,
+		health: null,
+		verified: false
+	};
+	if (!processExists(state.pid)) {
+		await removeStaleState(state);
+		return {
+			running: false,
+			state: null,
+			health: null,
+			verified: false
+		};
+	}
+	const observed = await health(state.apiUrl);
+	return {
+		running: Boolean(observed),
+		state,
+		health: observed,
+		verified: Boolean(observed && matchesOwnership(state, observed))
+	};
+}
+async function daemonUp(options) {
+	if (options.port !== void 0 && (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535)) throw new Error("--port must be an integer between 1 and 65535");
+	const paths = localPaths();
+	const saved = await preferences();
+	const next = {
+		host: options.host?.trim() || saved.host || DEFAULT_HOST,
+		port: options.port ?? saved.port ?? DEFAULT_PORT
+	};
+	if (options.host !== void 0 || options.port !== void 0) {
+		await fs.mkdir(paths.dataDir, {
+			recursive: true,
+			mode: 448
+		});
+		const temporaryPath = `${paths.preferencesPath}.${process.pid}.tmp`;
+		await fs.writeFile(temporaryPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 384 });
+		await fs.rename(temporaryPath, paths.preferencesPath);
+	}
+	const host = options.host?.trim() || process.env.TREEPORT_HOST?.trim() || next.host;
+	const port = Number.parseInt(options.port === void 0 ? process.env.TREEPORT_PORT?.trim() || String(next.port) : String(options.port), 10);
+	const apiUrl = options.host !== void 0 || options.port !== void 0 ? listenerUrl(host, port) : process.env.TREEPORT_API_URL?.trim() || listenerUrl(host, port);
+	const currentVersion = await treeportVersion();
+	const existing = await daemonStatus();
+	if (existing.state) {
+		if (!existing.running || !existing.verified) throw new Error(`Treeport PID ${existing.state.pid} is running but ownership or health could not be verified. See ${paths.logPath}.`);
+		if (existing.health?.version === currentVersion && existing.state.apiUrl === apiUrl) return {
+			alreadyRunning: true,
+			apiUrl: existing.state.apiUrl,
+			pid: existing.state.pid
+		};
+		await stopOwned(existing.state);
+	}
+	const failedChecks = (await runDoctor()).filter((check) => !check.ok);
+	if (failedChecks.length) throw new Error(failedChecks.map((check) => `${check.name}: ${check.detail}`).join("\n"));
+	const serverEntry = await resolvePackagePath("dist", "node", "server", "index.js");
+	const webDist = await resolvePackagePath("dist", "web");
+	await fs.access(serverEntry);
+	await fs.mkdir(path.dirname(paths.logPath), {
+		recursive: true,
+		mode: 448
+	});
+	if (await fs.stat(paths.logPath).then((value) => value.size).catch(() => 0) > 5 * 1024 * 1024) {
+		await fs.rm(`${paths.logPath}.1`, { force: true });
+		await fs.rename(paths.logPath, `${paths.logPath}.1`);
+	}
+	const instanceId = crypto.randomUUID();
+	const childEnvironment = {
+		...process.env,
+		TREEPORT_HOST: host,
+		TREEPORT_PORT: String(port),
+		TREEPORT_API_URL: apiUrl,
+		TREEPORT_DATA_DIR: paths.dataDir,
+		TREEPORT_RUNTIME_DIR: paths.runtimeDir,
+		TREEPORT_APP_VERSION: currentVersion,
+		TREEPORT_INSTANCE_ID: instanceId,
+		TREEPORT_INSTALLATION_METHOD: process.env.TREEPORT_INSTALLATION_METHOD?.trim() || "npm",
+		TREEPORT_WEB_DIST: webDist
+	};
+	if (options.foreground) {
+		console.log(`Treeport will listen on ${apiUrl}`);
+		const child = spawn(process.execPath, [serverEntry], {
+			env: childEnvironment,
+			stdio: "inherit"
+		});
+		const code = await new Promise((resolve, reject) => {
+			child.once("error", reject);
+			child.once("close", (value) => resolve(value ?? 1));
+		});
+		if (code !== 0) throw new Error(`Treeport exited with status ${code}`);
+		return {
+			alreadyRunning: false,
+			apiUrl,
+			pid: child.pid ?? 0
+		};
+	}
+	const log = fsSync.openSync(paths.logPath, "a", 384);
+	const child = spawn(process.execPath, [serverEntry], {
+		env: childEnvironment,
+		detached: true,
+		stdio: [
+			"ignore",
+			log,
+			log
+		]
+	});
+	child.unref();
+	fsSync.closeSync(log);
+	const deadline = Date.now() + 15e3;
+	while (Date.now() < deadline) {
+		const observed = await health(apiUrl, 500);
+		if (observed && observed.pid === child.pid && observed.instanceId === instanceId && observed.version === currentVersion) return {
+			alreadyRunning: false,
+			apiUrl,
+			pid: child.pid ?? observed.pid
+		};
+		if (child.pid && !processExists(child.pid)) break;
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	const recentLog = await fs.readFile(paths.logPath, "utf8").then((value) => value.split("\n").slice(-20).join("\n").trim()).catch(() => "");
+	throw new Error(`Treeport did not become ready at ${apiUrl}. See ${paths.logPath}.${recentLog ? `\n\n${recentLog}` : ""}`);
+}
+async function daemonDown() {
+	const state = await readState();
+	if (!state) return { wasRunning: false };
+	await stopOwned(state);
+	return { wasRunning: true };
+}
+async function readDaemonLogs(lines = 100) {
+	return (await fs.readFile(localPaths().logPath, "utf8").catch((error) => {
+		if (error.code === "ENOENT") return "";
+		throw error;
+	})).split("\n").slice(-lines - 1).join("\n");
+}
+//#endregion
+//#region src/cli/index.ts
+const configuredApiUrl = process.env.TREEPORT_API_URL?.trim();
+const apiUrl = (await resolveLocalApiUrl()).replace(/\/$/, "");
+const contextPrefix = "TREEPORT";
+const contextProjectId = process.env.TREEPORT_PROJECT_ID?.trim();
+const contextWorktreeId = process.env.TREEPORT_WORKTREE_ID?.trim();
+const contextTerminalId = process.env.TREEPORT_TERMINAL_ID?.trim();
+const rawArgs = process.argv.slice(2);
+const jsonOutput = extractJsonOutput(rawArgs);
+var CliError = class extends Error {
+	exitCode;
+	code;
+	details;
+	constructor(message, exitCode, code, details) {
+		super(message);
+		this.exitCode = exitCode;
+		this.code = code ?? (exitCode === 2 ? "USAGE_ERROR" : exitCode === 3 ? "DAEMON_UNREACHABLE" : exitCode === 4 ? "WAIT_TIMEOUT" : exitCode === 5 ? "DOMAIN_ERROR" : "UNEXPECTED_ERROR");
+		this.details = details;
+	}
+};
+async function request(pathname, options = {}) {
+	const controller = new AbortController();
+	const externalSignal = options.signal;
+	const abort = () => controller.abort();
+	if (externalSignal?.aborted) controller.abort();
+	else externalSignal?.addEventListener("abort", abort, { once: true });
+	const timeout = setTimeout(abort, 9e4);
+	try {
+		const response = await fetch(`${apiUrl}${pathname}`, {
+			...options,
+			signal: controller.signal,
+			headers: {
+				accept: "application/json",
+				...options.body ? { "content-type": "application/json" } : {},
+				...options.headers
+			}
+		});
+		const body = await response.json().catch(() => ({}));
+		if (!response.ok) {
+			const error = body.error;
+			throw new CliError(error?.message || `HTTP ${response.status}`, 5, error?.code || "API_ERROR", error?.details);
+		}
+		return body;
+	} catch (error) {
+		if (error instanceof CliError) throw error;
+		throw new CliError(`Cannot reach Treeport daemon at ${apiUrl}: ${error instanceof Error ? error.message : String(error)}`, 3, "DAEMON_UNREACHABLE");
+	} finally {
+		clearTimeout(timeout);
+		externalSignal?.removeEventListener("abort", abort);
+	}
+}
+function commandArgv(args) {
+	const separator = args.indexOf("--");
+	if (separator === -1) return;
+	const argv = args.slice(separator + 1);
+	args.splice(separator);
+	if (!argv.length) throw new CliError("Expected a command after --", 2);
+	return argv;
+}
+async function canonical(value) {
+	return fs.realpath(path.resolve(value)).catch(() => path.resolve(value));
+}
+async function projects() {
+	return (await request("/api/projects")).projects;
+}
+function pathContains(candidate, parent) {
+	const relative = path.relative(parent, candidate);
+	return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+async function resolveProject(identifier) {
+	const list = await projects();
+	const direct = list.find((project) => project.id === identifier);
+	if (direct) return direct;
+	if (identifier === "." && contextProjectId) {
+		const environmentMatch = list.find((project) => project.id === contextProjectId);
+		if (environmentMatch) return environmentMatch;
+	}
+	const candidate = await canonical(identifier);
+	const match = list.find((project) => pathContains(candidate, project.repositoryPath) || project.worktrees.some((worktree) => pathContains(candidate, worktree.path)));
+	if (!match) throw new CliError(`No registered project matches ${identifier}`, 5);
+	return match;
+}
+async function resolveWorktree(identifier) {
+	const all = (await projects()).flatMap((project) => project.worktrees);
+	const direct = all.find((worktree) => worktree.id === identifier);
+	if (direct) return direct;
+	if (identifier === "." && contextWorktreeId) {
+		const environmentMatch = all.find((worktree) => worktree.id === contextWorktreeId);
+		if (environmentMatch) return environmentMatch;
+	}
+	const candidate = await canonical(identifier);
+	const match = all.filter((worktree) => pathContains(candidate, worktree.path)).sort((a, b) => b.path.length - a.path.length)[0];
+	if (!match) throw new CliError(`No registered worktree matches ${identifier}`, 5);
+	return match;
+}
+function resolveTerminalId(identifier) {
+	if (identifier !== ".") return identifier;
+	const terminalId = contextTerminalId;
+	if (!terminalId) {
+		const variable = `${contextPrefix}_TERMINAL_ID`;
+		throw new CliError(`Cannot resolve . without ${variable}`, 5, "TREEPORT_CONTEXT_INCOMPLETE", { missing: [variable] });
+	}
+	return terminalId;
+}
+function parseCaptureLines(value) {
+	if (!/^[1-9]\d*$/.test(value)) throw new CliError(`--lines must be an integer between 1 and ${TERMINAL_CAPTURE_MAX_LINES}`, 2);
+	const lines = Number(value);
+	if (!Number.isSafeInteger(lines) || lines > 5e3) throw new CliError(`--lines must be an integer between 1 and ${TERMINAL_CAPTURE_MAX_LINES}`, 2);
+	return lines;
+}
+function parseDuration(value) {
+	const match = /^(\d+)(ms|s|m|h)$/.exec(value);
+	if (!match) throw new CliError("Timeout must be a positive duration such as 500ms, 30s, 5m, or 1h", 2);
+	const timeoutMs = Number(match[1]) * {
+		ms: 1,
+		s: 1e3,
+		m: 6e4,
+		h: 36e5
+	}[match[2]];
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) throw new CliError("Timeout must be between 1ms and 2147483647ms", 2);
+	return timeoutMs;
+}
+async function inspectTerminal(terminalId, signal) {
+	return request(`/api/terminals/${encodeURIComponent(terminalId)}`, signal ? { signal } : {});
+}
+async function waitForTerminal(terminalId, condition, timeoutMs) {
+	let observation = null;
+	let bellBaseline = null;
+	const matched = (observedAt) => {
+		if (!observation) return null;
+		if (!(condition === "idle" && observation.metadata.progress === null || condition === "working" && observation.metadata.progress !== null || condition === "exit" && observation.terminal.status === "exited" || condition === "bell" && bellBaseline !== null && (observation.metadata.bell?.sequence ?? 0) > bellBaseline)) return null;
+		return {
+			condition,
+			observedAt: condition === "bell" ? observation.metadata.bell?.at ?? observedAt : observedAt,
+			...observation
+		};
+	};
+	const controller = new AbortController();
+	let cancellation = null;
+	const interrupt = () => {
+		cancellation = "interrupt";
+		controller.abort();
+	};
+	process.once("SIGINT", interrupt);
+	const timeout = timeoutMs === void 0 ? null : setTimeout(() => {
+		cancellation = "timeout";
+		controller.abort();
+	}, timeoutMs);
+	timeout?.unref();
+	let events = null;
+	try {
+		observation = await inspectTerminal(terminalId, controller.signal);
+		if (condition === "bell") bellBaseline = observation.metadata.bell?.sequence ?? 0;
+		const immediate = matched((/* @__PURE__ */ new Date()).toISOString());
+		if (immediate) return immediate;
+		events = io(`${apiUrl}/events`, {
+			path: SOCKET_IO_PATH,
+			transports: ["websocket"],
+			forceNew: true,
+			autoConnect: false,
+			reconnection: false,
+			retries: 0
+		});
+		return await new Promise((resolve, reject) => {
+			let settled = false;
+			let queue = Promise.resolve();
+			const finish = (result) => {
+				if (!settled) {
+					settled = true;
+					resolve(result);
+				}
+			};
+			const fail = (error) => {
+				if (!settled) {
+					settled = true;
+					reject(error);
+				}
+			};
+			const enqueue = (task) => {
+				queue = queue.then(task);
+				queue.catch(fail);
+			};
+			controller.signal.addEventListener("abort", () => fail(/* @__PURE__ */ new Error("Terminal wait cancelled")), { once: true });
+			events.on("snapshot", (value) => enqueue(async () => {
+				const snapshot = parseEventsSnapshot(value);
+				if (!snapshot || !observation) throw new CliError("Treeport daemon sent an invalid event snapshot", 3, "DAEMON_PROTOCOL_ERROR");
+				const metadata = snapshot.terminalMetadata.find((item) => item.terminalId === terminalId);
+				if (metadata) observation = {
+					...observation,
+					metadata
+				};
+				const snapshotMatch = matched(snapshot.at);
+				if (snapshotMatch) {
+					finish(snapshotMatch);
+					return;
+				}
+				observation = await inspectTerminal(terminalId, controller.signal);
+				if (cancellation) throw new Error("Terminal wait cancelled");
+				const refreshedMatch = matched((/* @__PURE__ */ new Date()).toISOString());
+				if (refreshedMatch) finish(refreshedMatch);
+			}));
+			events.on("product_event", (value) => enqueue(async () => {
+				const event = parseProductEvent(value);
+				if (!event) throw new CliError("Treeport daemon sent an invalid product event", 3, "DAEMON_PROTOCOL_ERROR");
+				if (event.type !== "terminal.metadata" && event.type !== "terminal.updated" && event.type !== "terminal.removed") return;
+				if (event.data.terminalId !== terminalId) return;
+				if (event.type === "terminal.removed") throw new CliError(`Terminal ${terminalId} was removed while waiting`, 5, "TERMINAL_REMOVED", {
+					terminalId,
+					condition
+				});
+				if (event.type === "terminal.metadata") {
+					const metadata = parseTerminalRuntimeMetadata(event.data);
+					if (!metadata || !observation) throw new CliError("Treeport daemon sent invalid terminal metadata", 3, "DAEMON_PROTOCOL_ERROR");
+					observation = {
+						...observation,
+						metadata
+					};
+				} else {
+					observation = await inspectTerminal(terminalId, controller.signal);
+					if (cancellation) throw new Error("Terminal wait cancelled");
+				}
+				const result = matched(event.at);
+				if (result) finish(result);
+			}));
+			events.on("connect_error", (error) => fail(new CliError(`Cannot reach Treeport daemon at ${apiUrl}: ${error.message}`, 3, "DAEMON_UNREACHABLE")));
+			events.on("disconnect", () => fail(new CliError("Treeport daemon event channel disconnected before the condition was observed", 3, "DAEMON_DISCONNECTED")));
+			events.connect();
+		});
+	} catch (error) {
+		if (cancellation === "timeout") throw new CliError(`Timed out waiting for terminal ${terminalId} to reach ${condition}`, 4, "WAIT_TIMEOUT", {
+			terminalId,
+			until: condition,
+			timeoutMs,
+			lastObservation: observation
+		});
+		if (cancellation === "interrupt") throw new CliError("Interrupted", 130, "INTERRUPTED");
+		if (error instanceof CliError) throw error;
+		throw new CliError(`Treeport daemon event channel failed: ${error instanceof Error ? error.message : String(error)}`, 3, "DAEMON_DISCONNECTED");
+	} finally {
+		if (timeout) clearTimeout(timeout);
+		process.off("SIGINT", interrupt);
+		controller.abort();
+		events?.removeAllListeners();
+		events?.disconnect();
+	}
+}
+function print(value, human) {
+	if (jsonOutput) console.log(JSON.stringify(value));
+	else console.log(human ? human() : JSON.stringify(value, null, 2));
+}
+const agentGuidance = `AI agents:
+  If you're an AI agent, use \`treeport skills\` to see the usage guide.
+`;
+async function main(args) {
+	const argv = args[0] === "spawn" || args[0] === "terminal" && args[1] === "create" ? commandArgv(args) : void 0;
+	let parserError = "";
+	const program = new Command().name("treeport").description("Manage Treeport projects, worktrees, and terminals.").option("--json", "emit machine-readable JSON").addHelpText("beforeAll", agentGuidance).configureOutput({ writeErr: (value) => {
+		parserError += value;
+	} }).showHelpAfterError().exitOverride();
+	program.action(() => {
+		process.stdout.write(program.helpInformation());
+	});
+	const upCommand = program.command("up").description("Ensure the local Treeport daemon is running").option("--host <address>", "listener address").option("--port <port>", "listener port").option("--foreground", "run in the foreground").option("--json", "emit machine-readable JSON");
+	upCommand.action(async () => {
+		const options = upCommand.opts();
+		const port = options.port === void 0 ? void 0 : Number(options.port);
+		const result = await daemonUp({
+			...options.host === void 0 ? {} : { host: options.host },
+			...port === void 0 ? {} : { port },
+			...options.foreground === void 0 ? {} : { foreground: options.foreground }
+		});
+		if (options.foreground) return;
+		print(result, () => `Treeport is up\n${result.apiUrl}`);
+		const listenerHost = new URL(result.apiUrl).hostname;
+		if (![
+			"127.0.0.1",
+			"::1",
+			"[::1]",
+			"localhost"
+		].includes(listenerHost)) process.stderr.write("Warning: Treeport has no authentication. Use only a trusted private network.\n");
+	});
+	const downCommand = program.command("down").description("Stop the local daemon and preserve terminal sessions").option("--terminate-terminals", "terminate every Treeport-owned tmux server").option("--force", "confirm termination of all terminals").option("--json", "emit machine-readable JSON");
+	downCommand.action(async () => {
+		const options = downCommand.opts();
+		if (options.terminateTerminals && !options.force) throw new CliError("Re-run with --terminate-terminals --force to confirm termination of every terminal.", 2);
+		if (options.terminateTerminals) await request("/api/admin/terminate-terminals", { method: "POST" });
+		const result = await daemonDown();
+		print(result, () => result.wasRunning ? "Treeport is down" : "Treeport is already down");
+	});
+	program.command("status").description("Show local daemon status").option("--json", "emit machine-readable JSON").action(async () => {
+		const status = await daemonStatus();
+		const projectList = status.verified ? await projects() : [];
+		const result = {
+			...status,
+			projects: projectList.length,
+			worktrees: projectList.reduce((count, project) => count + project.worktrees.length, 0),
+			terminals: projectList.reduce((count, project) => count + project.worktrees.reduce((worktreeCount, worktree) => worktreeCount + worktree.terminals.length, 0), 0)
+		};
+		print(result, () => {
+			if (!status.state) return "Treeport is down";
+			if (!status.running || !status.verified) return `Treeport is unhealthy (PID ${status.state.pid})\nLogs: ${path.join(status.state.dataDir, "logs", "daemon.log")}`;
+			return `Treeport is up\n${status.state.apiUrl}\nVersion: ${status.health?.version}\nPID: ${status.state.pid}\nProjects: ${result.projects}\nWorktrees: ${result.worktrees}\nTerminals: ${result.terminals}`;
+		});
+	});
+	const logsCommand = program.command("logs").description("Show recent daemon logs").option("--lines <count>", "number of lines", "100");
+	logsCommand.action(async () => {
+		const lines = Number(logsCommand.opts().lines);
+		if (!Number.isInteger(lines) || lines < 1 || lines > 1e4) throw new CliError("--lines must be an integer between 1 and 10000", 2);
+		process.stdout.write(await readDaemonLogs(lines));
+	});
+	program.command("doctor").description("Diagnose local requirements and paths").option("--json", "emit machine-readable JSON").action(async () => {
+		const checks = await runDoctor();
+		print(checks, () => checks.map((check) => `${check.ok ? "ok" : "error"}\t${check.name}\t${check.detail}`).join("\n"));
+		if (checks.some((check) => !check.ok)) process.exitCode = 1;
+	});
+	program.command("version").description("Show CLI and daemon versions").option("--json", "emit machine-readable JSON").action(async () => {
+		const [cli, status] = await Promise.all([treeportVersion(), daemonStatus()]);
+		const result = {
+			cli,
+			daemon: status.verified ? status.health?.version ?? null : null
+		};
+		print(result, () => `CLI: ${result.cli}\nDaemon: ${result.daemon ?? "not running"}`);
+	});
+	program.command("skills").description("Print the Treeport usage guide for AI agents").action(async () => {
+		process.stdout.write(await fs.readFile(await resolvePackagePath("skills", "treeport", "SKILL.md"), "utf8"));
+	});
+	program.command("context").description("Show the current Treeport-managed terminal context").option("--json", "emit machine-readable JSON").action(async () => {
+		const projectId = contextProjectId;
+		const worktreeId = contextWorktreeId;
+		const terminalId = contextTerminalId;
+		if (![
+			projectId,
+			worktreeId,
+			terminalId
+		].filter(Boolean).length) {
+			print({
+				managed: false,
+				reason: "outside_treeport"
+			}, () => "Not running in a Treeport-managed terminal.");
+			return;
+		}
+		const missing = [
+			...!configuredApiUrl ? [`${contextPrefix}_API_URL`] : [],
+			...!projectId ? [`${contextPrefix}_PROJECT_ID`] : [],
+			...!worktreeId ? [`${contextPrefix}_WORKTREE_ID`] : [],
+			...!terminalId ? [`${contextPrefix}_TERMINAL_ID`] : []
+		];
+		if (missing.length) throw new CliError(`Incomplete Treeport context; missing ${missing.join(", ")}`, 5, "TREEPORT_CONTEXT_INCOMPLETE", { missing });
+		const project = (await request(`/api/projects/${encodeURIComponent(projectId)}`)).project;
+		const worktree = project.worktrees.find((candidate) => candidate.id === worktreeId);
+		if (!worktree) throw new CliError("Treeport context worktree does not belong to the current project", 5, "TREEPORT_CONTEXT_INVALID", {
+			projectId,
+			worktreeId
+		});
+		const terminal = worktree.terminals.find((candidate) => candidate.id === terminalId);
+		if (!terminal) throw new CliError("Treeport context terminal does not belong to the current worktree", 5, "TREEPORT_CONTEXT_INVALID", {
+			worktreeId,
+			terminalId
+		});
+		const context = {
+			managed: true,
+			apiUrl,
+			project: {
+				id: project.id,
+				name: project.name,
+				repositoryPath: project.repositoryPath,
+				mainWorktreePath: project.mainWorktreePath,
+				defaultBranch: project.defaultBranch,
+				availability: project.availability
+			},
+			worktree: {
+				id: worktree.id,
+				projectId: worktree.projectId,
+				name: worktree.name,
+				path: worktree.path,
+				head: worktree.head,
+				branch: worktree.branch,
+				detached: worktree.detached,
+				kind: worktree.kind,
+				status: worktree.status
+			},
+			terminal: {
+				id: terminal.id,
+				worktreeId: terminal.worktreeId,
+				name: terminal.name,
+				status: terminal.status,
+				exitCode: terminal.exitCode
+			}
+		};
+		print(context, () => `Treeport context\n\nProject:  ${context.project.name} (${context.project.id})\nWorktree: ${context.worktree.name} (${context.worktree.id})\nPath:     ${context.worktree.path}\nTerminal: ${context.terminal.name} (${context.terminal.id}) — ${context.terminal.status}\nAPI:      ${context.apiUrl}`);
+	});
+	const projectCommand = program.command("project").description("Register and list projects");
+	projectCommand.action(() => {
+		throw new CliError(projectCommand.helpInformation(), 2);
+	});
+	projectCommand.command("add").description("Register a Git repository").argument("<path>", "repository path").option("--json", "emit machine-readable JSON").action(async (repository) => {
+		const body = await request("/api/projects", {
+			method: "POST",
+			body: JSON.stringify({ path: await canonical(repository) })
+		});
+		print(body.project, () => `Registered ${body.project.name} (${body.project.id})\n${body.project.repositoryPath}`);
+	});
+	projectCommand.command("list").description("List registered projects").option("--json", "emit machine-readable JSON").action(async () => {
+		const list = await projects();
+		print(list, () => list.map((project) => `${project.id}\t${project.name}\t${project.repositoryPath}`).join("\n"));
+	});
+	const worktreeCommand = program.command("worktree").description("List, create, and remove worktrees");
+	worktreeCommand.action(() => {
+		throw new CliError(worktreeCommand.helpInformation(), 2);
+	});
+	const worktreeListCommand = worktreeCommand.command("list").description("List discovered worktrees").option("--project <id-or-path>", "limit results to a project").option("--json", "emit machine-readable JSON");
+	worktreeListCommand.action(async () => {
+		const { project: projectIdentifier } = worktreeListCommand.opts();
+		const list = projectIdentifier ? (await resolveProject(projectIdentifier)).worktrees : (await projects()).flatMap((project) => project.worktrees);
+		print(list, () => list.map((worktree) => `${worktree.id}\t${worktree.name}\t${worktree.branch ?? `detached@${worktree.head.slice(0, 8)}`}\t${worktree.status}\t${worktree.path}`).join("\n"));
+	});
+	const worktreeCreateCommand = worktreeCommand.command("create").description("Create a linked worktree").requiredOption("--project <id-or-path>", "project to create from").requiredOption("--name <name>", "worktree name").option("--from-current", "base the worktree on the current worktree").option("--json", "emit machine-readable JSON");
+	worktreeCreateCommand.action(async () => {
+		const options = worktreeCreateCommand.opts();
+		const project = await resolveProject(options.project);
+		const sourceWorktreeId = options.fromCurrent ? (await resolveWorktree(".")).id : void 0;
+		const result = await request(`/api/projects/${project.id}/worktrees`, {
+			method: "POST",
+			body: JSON.stringify({
+				name: options.name,
+				base: options.fromCurrent ? "current" : "default",
+				...sourceWorktreeId ? { sourceWorktreeId } : {}
+			})
+		});
+		print(result, () => `Created ${result.worktree.name} (${result.worktree.id})\n${result.worktree.path}${result.setupError ? `\nSetup error: ${result.setupError}` : ""}`);
+	});
+	const worktreeRemoveCommand = worktreeCommand.command("remove").description("Remove a linked worktree").argument("<id-or-path-or-dot>", "worktree to remove").option("--force", "confirm destructive removal warnings").option("--json", "emit machine-readable JSON");
+	worktreeRemoveCommand.action(async (identifier) => {
+		const { force: confirmed } = worktreeRemoveCommand.opts();
+		const worktree = await resolveWorktree(identifier);
+		const preview = (await request(`/api/worktrees/${worktree.id}/remove-preview`)).preview;
+		if (!preview.eligible) throw new CliError(preview.reasons.join("\n"), 5);
+		if (preview.warnings.length && !confirmed) throw new CliError(`${preview.warnings.join("\n")}\nRe-run with --force to confirm removal.`, 5);
+		const result = await request(`/api/worktrees/${worktree.id}/remove`, {
+			method: "POST",
+			body: JSON.stringify({
+				confirmationToken: preview.confirmationToken,
+				confirmDestructive: preview.warnings.length > 0
+			})
+		});
+		print(result.operation, () => `Remove accepted: ${result.operation.id}`);
+	});
+	const terminalCommand = program.command("terminal").description("Manage persistent worktree terminals");
+	terminalCommand.action(() => {
+		throw new CliError(terminalCommand.helpInformation(), 2);
+	});
+	const terminalListCommand = terminalCommand.command("list").description("List terminals").option("--worktree <id-or-path>", "limit results to a worktree").option("--json", "emit machine-readable JSON");
+	terminalListCommand.action(async () => {
+		const { worktree: identifier } = terminalListCommand.opts();
+		const list = identifier ? (await resolveWorktree(identifier)).terminals : (await projects()).flatMap((project) => project.worktrees.flatMap((worktree) => worktree.terminals));
+		print(list, () => list.map((terminal) => `${terminal.id}\t${terminal.name}\t${terminal.status}\t${JSON.stringify(terminal.argv)}`).join("\n"));
+	});
+	const terminalCreateCommand = terminalCommand.command("create").description("Create a persistent terminal").usage("[options] [-- <command> args...]").requiredOption("--worktree <id-or-path-or-dot>", "owning worktree").requiredOption("--name <name>", "terminal name").option("--json", "emit machine-readable JSON").addHelpText("after", "\nCommand arguments may be passed after --.\n");
+	terminalCreateCommand.action(async () => {
+		const options = terminalCreateCommand.opts();
+		const result = await request(`/api/worktrees/${(await resolveWorktree(options.worktree)).id}/terminals`, {
+			method: "POST",
+			body: JSON.stringify({
+				name: options.name,
+				...argv ? { argv } : {}
+			})
+		});
+		print(result.terminal, () => `Created ${result.terminal.name} (${result.terminal.id})`);
+	});
+	terminalCommand.command("inspect").description("Inspect terminal status and runtime metadata").argument("<terminal-id-or-dot>", "terminal to inspect").option("--json", "emit machine-readable JSON").action(async (identifier) => {
+		const observation = await inspectTerminal(resolveTerminalId(identifier));
+		print(observation, () => {
+			const { terminal, metadata } = observation;
+			const progress = metadata.progress ? `working (${metadata.progress.state}${metadata.progress.value === null ? "" : ` ${metadata.progress.value}%`})` : "idle";
+			const status = terminal.status === "exited" ? `exited${terminal.exitCode === null ? "" : ` (${terminal.exitCode})`}` : terminal.status;
+			return `Terminal: ${terminal.name} (${terminal.id})\nStatus:   ${status}\nTitle:    ${metadata.title ?? "—"}\nProgress: ${progress}\nStarted:  ${metadata.progressStartedAt ?? "—"}\nCleared:  ${metadata.progressClearedAt ?? "—"}\nBell:     ${metadata.bell ? `${metadata.bell.at} (#${metadata.bell.sequence})` : "—"}`;
+		});
+	});
+	const terminalCaptureCommand = terminalCommand.command("capture").description("Capture recent terminal output").argument("<terminal-id-or-dot>", "terminal to capture").option("--lines <count>", "number of lines to capture").option("--json", "emit machine-readable JSON");
+	terminalCaptureCommand.action(async (identifier) => {
+		const { lines: rawLines } = terminalCaptureCommand.opts();
+		const lines = rawLines === void 0 ? 200 : parseCaptureLines(rawLines);
+		const terminalId = resolveTerminalId(identifier);
+		const capture = await request(`/api/terminals/${encodeURIComponent(terminalId)}/capture?lines=${lines}`);
+		if (jsonOutput) print(capture);
+		else {
+			process.stdout.write(capture.content);
+			if (capture.content && !capture.content.endsWith("\n")) process.stdout.write("\n");
+		}
+	});
+	const terminalWaitCommand = terminalCommand.command("wait").description("Wait for a terminal runtime condition").argument("<terminal-id-or-dot>", "terminal to observe").requiredOption("--until <idle|working|bell|exit>", "condition to wait for").option("--timeout <duration>", "maximum wait, such as 30s or 5m").option("--json", "emit machine-readable JSON");
+	terminalWaitCommand.action(async (identifier) => {
+		const options = terminalWaitCommand.opts();
+		if (![
+			"idle",
+			"working",
+			"bell",
+			"exit"
+		].includes(options.until)) throw new CliError("--until must be one of idle, working, bell, or exit", 2);
+		const result = await waitForTerminal(resolveTerminalId(identifier), options.until, options.timeout === void 0 ? void 0 : parseDuration(options.timeout));
+		print(result, () => `${result.terminal.name} (${result.terminal.id}) reached ${result.condition} at ${result.observedAt}`);
+	});
+	terminalCommand.command("delete").description("Delete a terminal").argument("<terminal-id>", "terminal to delete").option("--json", "emit machine-readable JSON").action(async (terminalId) => {
+		await request(`/api/terminals/${terminalId}`, { method: "DELETE" });
+		print({
+			ok: true,
+			terminalId
+		}, () => `Deleted ${terminalId}`);
+	});
+	const spawnCommand = program.command("spawn").description("Create a worktree and its first terminal").usage("[options] [-- <command> args...]").requiredOption("--project <id-or-path-or-dot>", "project to create from").requiredOption("--worktree-name <name>", "worktree name").requiredOption("--name <terminal-name>", "terminal name").option("--from-current", "base the worktree on the current worktree").option("--json", "emit machine-readable JSON").addHelpText("after", "\nCommand arguments may be passed after --.\n");
+	spawnCommand.action(async () => {
+		const options = spawnCommand.opts();
+		const project = await resolveProject(options.project);
+		const sourceWorktreeId = options.fromCurrent ? (await resolveWorktree(".")).id : void 0;
+		const result = await request("/api/spawn", {
+			method: "POST",
+			body: JSON.stringify({
+				project: project.id,
+				worktreeName: options.worktreeName,
+				name: options.name,
+				base: options.fromCurrent ? "current" : "default",
+				...sourceWorktreeId ? { sourceWorktreeId } : {},
+				...argv ? { argv } : {}
+			})
+		});
+		print(result, () => `Created worktree ${result.worktree.name} (${result.worktree.id})\nPath: ${result.worktree.path}\n${result.terminal ? `Terminal: ${result.terminal.name} (${result.terminal.id}) — ${result.terminal.status}` : "Terminal: not created"}${result.setupError ? `\nSetup error: ${result.setupError}` : ""}${result.terminalError ? `\nTerminal error: ${result.terminalError}` : ""}`);
+	});
+	try {
+		await program.parseAsync(args, { from: "user" });
+	} catch (error) {
+		if (error instanceof CommanderError) {
+			if (error.exitCode === 0) return;
+			throw new CliError(parserError.trim() || error.message, 2, "USAGE_ERROR");
+		}
+		throw error;
+	}
+}
+main(rawArgs).catch((error) => {
+	const cliError = error instanceof CliError ? error : new CliError(error instanceof Error ? error.message : String(error), 1);
+	if (jsonOutput) {
+		const body = { error: {
+			code: cliError.code,
+			message: cliError.message,
+			...cliError.details === void 0 ? {} : { details: cliError.details }
+		} };
+		process.stderr.write(`${JSON.stringify(body)}\n`);
+	} else process.stderr.write(`${cliError.message}\n`);
+	process.exitCode = cliError.exitCode;
+});
+//#endregion
+export {};