@alexkroman1/aai-cli 1.9.2 → 1.10.0

package/dist/_dev-server-DZl-xNwH.mjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+import { n as log } from "./_ui-CKEIHAtB.mjs";
+import { r as errorMessage, t as errorCode } from "./_utils-ECl2je7-.mjs";
+import { n as fallbackHtmlPlugin } from "./client-bundler-VdcgFcos.mjs";
+import { buildWorker } from "./worker-bundler.mjs";
+import { createWorkerEvaluator } from "./_bundler-CKz9Q15i.mjs";
+import { n as ensureApiKey } from "./_config-BMjZt5hG.mjs";
+import { t as resolveServerEnv } from "./_server-common-Bv-4Rskq.mjs";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
+import { watch } from "chokidar";
+import getPort, { portNumbers } from "get-port";
+import pDebounce from "p-debounce";
+//#region _dev-bundler.ts
+/**
+* Incremental worker builds for `aai dev`.
+*
+* The deploy path (`buildWorker` in `worker-bundler.ts`) is a from-scratch
+* Vite/Rollup pass — right for a one-shot `aai deploy`, but 1–3 s per save
+* when the dev watcher runs it on every change. This module keeps a
+* long-lived esbuild `context()` whose `rebuild()` reuses the previous
+* build's work, cutting rebuilds to tens of ms. Deploy keeps Vite untouched,
+* so nothing that ships is produced by esbuild.
+*
+* Parity with `buildWorker` where it matters for dev:
+*
+* - single-file ESM output, unminified (dev builds never minify);
+* - `node:` builtins external (esbuild's `platform: "node"`), everything
+*   else — zod, workspace deps, local imports — bundled in;
+* - `.md` imports resolve to their raw text (esbuild's `text` loader is
+*   `rawMdPlugin`'s transform), and Vite-style `?raw` suffix imports are
+*   honored via `rawSuffixPlugin` below.
+*
+* Known dev/deploy differences, accepted: Rollup and esbuild can disagree on
+* `exports`-condition ordering for exotic dual-format packages, and Vite's
+* lib build applies `define`/`import.meta.env` replacements esbuild does not.
+* When a rebuild fails for anything other than a compile error in the agent's
+* code, the caller falls back to the cold Vite path (see `_dev-server.ts`),
+* so an esbuild-specific resolution gap degrades to the old slow-but-correct
+* behavior rather than a broken dev server.
+*
+* esbuild does not touch `process.env` (verified: no NODE_ENV write in its
+* JS API), so the `withPreservedNodeEnv` wrapper Vite builds need is not
+* required here.
+*/
+/**
+* Vite serves `import x from "./file?raw"` as the file's text. esbuild treats
+* the suffix as part of the filename, so resolve it explicitly and load the
+* real file with the `text` loader.
+*/
+const rawSuffixPlugin = {
+	name: "raw-suffix",
+	setup(build) {
+		build.onResolve({ filter: /\?raw$/ }, (args) => ({
+			path: path.resolve(args.resolveDir, args.path.slice(0, -4)),
+			namespace: "aai-raw"
+		}));
+		build.onLoad({
+			filter: /.*/,
+			namespace: "aai-raw"
+		}, async (args) => ({
+			contents: await fs.readFile(args.path, "utf8"),
+			loader: "text"
+		}));
+	}
+};
+/**
+* True for esbuild build failures — compile/resolve errors in the code being
+* built (the esbuild analog of a Rollup diagnostic). Anything else coming out
+* of `rebuild()` is an esbuild-infrastructure problem, which callers treat as
+* "fall back to the cold Vite path" rather than "the user's code is broken".
+*/
+function isEsbuildBuildFailure(err) {
+	return err instanceof Error && "errors" in err && Array.isArray(err.errors);
+}
+/**
+* Create an incremental dev builder for the agent at `cwd`.
+*
+* The context is created lazily on first `build()` and kept across calls —
+* that reuse is the entire point. A rebuild that fails for a non-compile
+* reason drops the context so the next call starts from a clean one.
+*/
+function createDevWorkerBuilder(cwd) {
+	let ctx;
+	async function ensureContext() {
+		if (ctx) return ctx;
+		const { context } = await import("esbuild");
+		ctx = await context({
+			entryPoints: [path.join(cwd, "agent.ts")],
+			absWorkingDir: cwd,
+			bundle: true,
+			format: "esm",
+			platform: "node",
+			target: "node20",
+			write: false,
+			outfile: "worker.js",
+			minify: false,
+			logLevel: "silent",
+			loader: { ".md": "text" },
+			plugins: [rawSuffixPlugin]
+		});
+		return ctx;
+	}
+	return {
+		async build() {
+			const active = await ensureContext();
+			let result;
+			try {
+				result = await active.rebuild();
+			} catch (err) {
+				if (!isEsbuildBuildFailure(err)) {
+					ctx = void 0;
+					await active.dispose().catch(() => void 0);
+				}
+				throw err;
+			}
+			const file = result.outputFiles?.[0];
+			if (!file) throw new Error("esbuild produced no output for agent.ts");
+			return file.text;
+		},
+		async dispose() {
+			const active = ctx;
+			ctx = void 0;
+			await active?.dispose().catch(() => void 0);
+		}
+	};
+}
+//#endregion
+//#region _dev-server.ts
+/**
+* Dev server for directory-based agents.
+*
+* Imports agent.ts directly for the full agent definition,
+* builds a runtime, and starts an HTTP+WebSocket server. Watches for
+* file changes and restarts automatically. Optionally runs Vite for
+* client SPA HMR.
+*/
+async function resolveAgentEnv(root, agentDef) {
+	const env = await resolveServerEnv(root);
+	const required = requiredProviderEnvVars(agentDef);
+	if (required.includes("ASSEMBLYAI_API_KEY") && !env.ASSEMBLYAI_API_KEY) env.ASSEMBLYAI_API_KEY = await ensureApiKey();
+	const missing = required.filter((name) => !(env[name] || process.env[name]));
+	if (missing.length > 0) log.warn(`Missing provider credential${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}. Set ${missing.length > 1 ? "them" : "it"} in .env or the environment.`);
+	return env;
+}
+/**
+* The env handed to `createServer` for host-mode connections: provider
+* credentials plus the `AAI_ALLOW_HOST` gate read straight from the shell
+* (it is a control variable, not something an agent declares in `.env`).
+*/
+function hostModeEnv(providerEnv) {
+	const gate = process.env.AAI_ALLOW_HOST;
+	return gate === void 0 ? providerEnv : {
+		...providerEnv,
+		AAI_ALLOW_HOST: gate
+	};
+}
+/**
+* Explicit bind host for the dev server, or `undefined` to take the
+* loopback default. An empty `AAI_DEV_HOST` means "unset", not "every
+* interface" — Node treats `listen(port, "")` as 0.0.0.0, which would quietly
+* undo the loopback default this exists to guard.
+*/
+function devBindHost() {
+	const host = process.env.AAI_DEV_HOST?.trim();
+	return host ? host : void 0;
+}
+/**
+* Load the agent definition by bundling agent.ts (and all its local imports)
+* into a single ESM file, then importing that. A raw `import(agent.ts?t=...)`
+* only cache-busts agent.ts itself — transitive imports (./tools.ts, etc.)
+* stay in Node's ESM registry, so edits to them are ignored on reload.
+* Bundling picks them up.
+*
+* The bundle comes from the incremental esbuild builder (`_dev-bundler.ts`)
+* rather than the deploy path's cold Vite build — a save rebuilds in tens of
+* ms instead of 1–3 s. Compile errors in the agent's code propagate (the
+* restart loop reports them and keeps the old server); any other builder
+* failure falls back to the cold Vite build so an esbuild-specific gap can't
+* take the dev loop down. Evaluation goes through the memoizing evaluator so
+* a no-op save doesn't leak another module into the ESM registry.
+*/
+async function loadAgentDefWith(cwd, builder, evaluate) {
+	let code;
+	try {
+		code = await builder.build();
+	} catch (err) {
+		if (isEsbuildBuildFailure(err)) throw err;
+		code = await buildWorker(cwd);
+	}
+	return evaluate(code);
+}
+/**
+* True for paths that should never trigger a restart: anything inside
+* `node_modules/` and any dot-entry (`.git/`, `.aai/`, `.DS_Store`, …).
+* `.git/` especially matters — commits and status checks churn the index
+* and would otherwise cause spurious full backend restarts.
+*
+* Exception: `.env` / `.env.*` files stay watched — env edits should
+* restart the server with the new values.
+*/
+function isIgnoredPath(dir, filePath) {
+	const rel = path.relative(dir, filePath);
+	if (!rel || rel.startsWith("..")) return false;
+	return rel.split(path.sep).some((segment) => {
+		if (segment === "node_modules") return true;
+		if (segment === ".env" || segment.startsWith(".env.")) return false;
+		return segment.startsWith(".");
+	});
+}
+/**
+* Watch the agent directory for changes and call `onChange` when detected.
+* Debounces to avoid rapid restarts. Uses chokidar for reliable recursive
+* watching across platforms (raw `fs.watch` misses events on Linux).
+*/
+function watchDirectory(dir, onChange) {
+	const debouncedChange = pDebounce(() => {
+		log.info("File change detected, restarting...");
+		onChange();
+	}, 300);
+	const watcher = watch(dir, {
+		ignored: (filePath) => isIgnoredPath(dir, filePath),
+		ignoreInitial: true,
+		persistent: false
+	});
+	watcher.on("error", (err) => {
+		const hint = errorCode(err) === "ENOSPC" ? " The inotify watch limit was reached — raise the fs.inotify max_user_watches sysctl." : "";
+		log.error(`File watcher error: ${errorMessage(err)}.${hint} Auto-restart on file changes may have stopped; restart \`aai dev\` after fixing.`);
+	});
+	watcher.on("all", () => {
+		debouncedChange().catch((err) => {
+			log.error(`Watch handler failed: ${errorMessage(err)}`);
+		});
+	});
+	return watcher;
+}
+/** Locate the pre-built default aai-ui client (served when no custom client.tsx). */
+function resolveDefaultClientDir() {
+	const require = createRequire(import.meta.url);
+	let pkgPath;
+	try {
+		pkgPath = require.resolve("@alexkroman1/aai-ui/package.json");
+	} catch (err) {
+		throw new Error(`Could not locate the default client UI (${errorMessage(err)}) — is @alexkroman1/aai-ui installed? Try reinstalling dependencies (pnpm install).`, { cause: err });
+	}
+	return path.join(path.dirname(pkgPath), "dist", "default-client");
+}
+/**
+* Vite dev-server config for the client SPA. Extracted so the proxy wiring
+* is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
+* with a `client.tsx` serves a page whose WebSocket never connects.
+*
+* `strictPort` because the reported URL is `http://localhost:<port>` —
+* without it, Vite silently binds port+N when the port is busy and the
+* printed/JSON-returned URL points at whatever else was listening.
+*/
+function viteDevConfig(cwd, vitePort, backendPort) {
+	const target = `http://localhost:${backendPort}`;
+	return {
+		root: cwd,
+		plugins: [fallbackHtmlPlugin(cwd)],
+		server: {
+			port: vitePort,
+			strictPort: true,
+			proxy: {
+				"/health": target,
+				"/websocket": {
+					target,
+					ws: true
+				}
+			}
+		}
+	};
+}
+/**
+* Start the dev server for a directory-based agent.
+*
+* Returns a cleanup function to shut down the server and watchers.
+*/
+async function startDevServer(opts) {
+	const { cwd, port } = opts;
+	const { createRuntime, createServer } = await import("@alexkroman1/aai/runtime");
+	const hasClient = existsSync(path.join(cwd, "client.tsx"));
+	const backendPort = hasClient ? await getPort({ port: portNumbers(port + 1, port + 100) }) : port;
+	const vitePort = port;
+	const clientDirOpt = hasClient ? {} : { clientDir: resolveDefaultClientDir() };
+	const devBuilder = createDevWorkerBuilder(cwd);
+	const evaluateWorker = createWorkerEvaluator(cwd);
+	/** Full build sequence, shared by initial startup and every restart. */
+	async function buildServer() {
+		const agentDef = await loadAgentDefWith(cwd, devBuilder, evaluateWorker);
+		const env = await resolveAgentEnv(cwd, agentDef);
+		const providerEnv = withHostCredentialFallback(env);
+		const runtime = createRuntime({
+			agent: agentDef,
+			env,
+			providerEnv
+		});
+		return createServer({
+			runtime,
+			name: agentDef.name,
+			env: hostModeEnv(providerEnv),
+			hostBaseAgent: agentDef,
+			...clientDirOpt
+		});
+	}
+	let restarting = true;
+	let pendingRestart = false;
+	let closed = false;
+	let currentServer;
+	function kickRestart() {
+		if (restarting) {
+			pendingRestart = true;
+			return;
+		}
+		restarting = true;
+		restart().catch((err) => {
+			log.error(`Restart failed: ${errorMessage(err)}`);
+		}).finally(() => {
+			restarting = false;
+		});
+	}
+	const watcher = watchDirectory(cwd, kickRestart);
+	let viteServer;
+	try {
+		currentServer = await buildServer();
+		await currentServer.listen(backendPort, devBindHost());
+		if (hasClient) {
+			const { createServer: createViteServer } = await import("vite");
+			viteServer = await createViteServer(viteDevConfig(cwd, vitePort, backendPort));
+			await viteServer.listen();
+			viteServer.httpServer?.on("error", (err) => {
+				log.error(`Vite dev server error: ${errorMessage(err)}`);
+			});
+		}
+	} catch (err) {
+		await watcher.close().catch(() => void 0);
+		await devBuilder.dispose().catch(() => void 0);
+		await viteServer?.close().catch(() => void 0);
+		throw err;
+	}
+	restarting = false;
+	if (pendingRestart) kickRestart();
+	async function restart() {
+		do {
+			pendingRestart = false;
+			await restartOnce();
+		} while (pendingRestart && !closed);
+	}
+	async function restartOnce() {
+		let newServer;
+		try {
+			newServer = await buildServer();
+		} catch (err) {
+			log.error(`Restart failed: ${errorMessage(err)} (previous server still running)`);
+			return;
+		}
+		if (closed) {
+			await newServer.close().catch(() => void 0);
+			return;
+		}
+		try {
+			await currentServer.close();
+		} catch {}
+		try {
+			await listenWithRetry(newServer);
+			currentServer = newServer;
+			if (closed) {
+				await newServer.close().catch(() => void 0);
+				return;
+			}
+			log.success("Restarted");
+		} catch (err) {
+			log.error(`Restart failed: ${errorMessage(err)} — dev server is down; save a file to retry.`);
+			await newServer.close().catch(() => void 0);
+		}
+	}
+	/**
+	* Listen with a few short-backoff retries. During the close→listen swap the
+	* port is momentarily free, so another process can snatch it (or the OS can
+	* hold it in TIME_WAIT); one blind attempt would leave the dev server down
+	* until the next file change.
+	*/
+	async function listenWithRetry(server) {
+		const LISTEN_ATTEMPTS = 3;
+		const LISTEN_RETRY_DELAY_MS = 250;
+		for (let attempt = 1;; attempt++) try {
+			await server.listen(backendPort, devBindHost());
+			return;
+		} catch (err) {
+			if (attempt >= LISTEN_ATTEMPTS || closed) throw err;
+			await new Promise((resolve) => setTimeout(resolve, LISTEN_RETRY_DELAY_MS));
+		}
+	}
+	let cleanupPromise;
+	return () => {
+		cleanupPromise ??= (async () => {
+			closed = true;
+			await watcher.close().catch(() => void 0);
+			await devBuilder.dispose().catch(() => void 0);
+			await viteServer?.close().catch(() => void 0);
+			await currentServer.close().catch(() => void 0);
+		})();
+		return cleanupPromise;
+	};
+}
+//#endregion
+export { startDevServer };

package/dist/{_init-y7K-dzni.mjs → _init-BznoJC91.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { a as readJson, c as writeJson, i as isEexist } from "./_utils-BeU10C7O.mjs";
-import { i as isDevMode, n as getMonorepoRoot } from "./_agent-cHGzbDVG.mjs";
+import { a as isEexist, l as writeJson, o as readJson, r as errorMessage } from "./_utils-ECl2je7-.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-Ba5Ykp05.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -9,37 +9,70 @@ import { downloadTemplate } from "giget";
 //#region _templates.ts
 const GIGET_SOURCE = "github:alexkroman/agent/packages/aai-templates";
 const GIGET_REF = process.env.AAI_TEMPLATES_REF ?? "main";
+const VALID_REF_RE = /^[\w./-]+$/;
+const noCleanup = async () => void 0;
 /** Resolve the templates directory — local in dev, giget download in prod. */
 async function resolveTemplatesDir() {
-	if (process.env.AAI_TEMPLATES_DIR) return process.env.AAI_TEMPLATES_DIR;
+	if (process.env.AAI_TEMPLATES_DIR) return {
+		root: process.env.AAI_TEMPLATES_DIR,
+		cleanup: noCleanup
+	};
 	const monorepoRoot = isDevMode() ? getMonorepoRoot() : null;
-	if (monorepoRoot) return path.join(monorepoRoot, "packages", "aai-templates");
+	if (monorepoRoot) return {
+		root: path.join(monorepoRoot, "packages", "aai-templates"),
+		cleanup: noCleanup
+	};
+	if (!VALID_REF_RE.test(GIGET_REF)) throw new Error(`Invalid AAI_TEMPLATES_REF: ${JSON.stringify(GIGET_REF)} is not a git ref.`);
 	const extractDir = await fs.mkdtemp(path.join(os.tmpdir(), "aai-templates-"));
-	const { dir } = await downloadTemplate(`${GIGET_SOURCE}#${GIGET_REF}`, {
-		dir: extractDir,
-		force: true,
-		forceClean: true
-	});
-	return dir;
+	const cleanup = async () => {
+		await fs.rm(extractDir, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+	};
+	try {
+		const { dir } = await downloadTemplate(`${GIGET_SOURCE}#${GIGET_REF}`, {
+			dir: extractDir,
+			force: true,
+			forceClean: true
+		});
+		return {
+			root: dir,
+			cleanup
+		};
+	} catch (err) {
+		await cleanup();
+		throw new Error(`Failed to download templates from ${GIGET_SOURCE}#${GIGET_REF}: ${errorMessage(err)}`, { cause: err });
+	}
 }
 /**
 * Download a template into targetDir, merging scaffold files underneath.
 */
 async function downloadAndMergeTemplate(template, targetDir) {
-	const root = await resolveTemplatesDir();
-	const templatesDir = path.join(root, "templates");
-	const names = (await fs.readdir(templatesDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
-	if (!names.includes(template)) throw new Error(`Unknown template "${template}". Available templates: ${names.join(", ")}`);
-	await fs.cp(path.join(templatesDir, template), targetDir, {
-		recursive: true,
-		force: true
-	});
-	const scaffoldDir = path.join(root, "scaffold");
-	if (existsSync(scaffoldDir)) await fs.cp(scaffoldDir, targetDir, {
-		recursive: true,
-		force: false,
-		errorOnExist: false
-	});
+	const { root, cleanup } = await resolveTemplatesDir();
+	try {
+		const templatesDir = path.join(root, "templates");
+		let available;
+		try {
+			available = await fs.readdir(templatesDir, { withFileTypes: true });
+		} catch (err) {
+			throw new Error(`Templates directory is missing or unreadable at ${templatesDir} (corrupt or incomplete template download?): ${errorMessage(err)}`, { cause: err });
+		}
+		const names = available.filter((e) => e.isDirectory()).map((e) => e.name);
+		if (!names.includes(template)) throw new Error(`Unknown template "${template}". Available templates: ${names.join(", ")}`);
+		await fs.cp(path.join(templatesDir, template), targetDir, {
+			recursive: true,
+			force: true
+		});
+		const scaffoldDir = path.join(root, "scaffold");
+		if (existsSync(scaffoldDir)) await fs.cp(scaffoldDir, targetDir, {
+			recursive: true,
+			force: false,
+			errorOnExist: false
+		});
+	} finally {
+		await cleanup();
+	}
 }
 //#endregion
 //#region _init.ts
@@ -95,7 +128,6 @@ async function patchPackageJsonForWorkspace(targetDir) {
 	if (!pkgJson) return;
 	pkgJson.name = path.basename(targetDir);
 	delete pkgJson.packageManager;
-	const { getMonorepoRoot } = await import("./_agent-cHGzbDVG.mjs").then((n) => n.t);
 	const root = getMonorepoRoot();
 	if (!root) return;
 	const packagesDir = path.join(root, "packages");

package/dist/{_server-common-QpOTRZgi.mjs → _server-common-Bv-4Rskq.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import path from "node:path";
 import fs from "node:fs/promises";
-import { parse } from "dotenv";
+import { parseEnv } from "node:util";
 //#region _server-common.ts
 /**
 * Build the `ctx.env` record that agent tools will see at runtime.
@@ -22,7 +22,7 @@ import { parse } from "dotenv";
 async function resolveServerEnv(cwd, baseEnv) {
 	let fileEntries = {};
 	if (cwd) try {
-		fileEntries = parse(await fs.readFile(path.join(cwd, ".env"), "utf-8"));
+		fileEntries = parseEnv(await fs.readFile(path.join(cwd, ".env"), "utf-8"));
 	} catch {}
 	const source = baseEnv ?? process.env;
 	const env = {};

package/dist/_ui-CKEIHAtB.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+//#region _output.ts
+/**
+* Determine output mode from CLI flags and TTY state.
+*
+* Priority: --json flag > --no-json flag > TTY auto-detection.
+*/
+function getOutputMode(args, isTTY = Boolean(process.stdout.isTTY)) {
+	if (args.json === true) return "json";
+	if (args.json === false) return "human";
+	return isTTY ? "human" : "json";
+}
+/**
+* Write a line to stdout, resolving only once it has been flushed.
+*
+* Resolves (never rejects) even when the write fails: the common failure is
+* EPIPE — the consumer closed the pipe (`aai … --json | head -1`) — and there
+* is nothing useful to do about a broken stdout except carry on and exit.
+* Stream-level `'error'` events are handled by {@link installStdoutGuard}.
+*/
+function writeLine(line) {
+	return new Promise((resolve) => {
+		process.stdout.write(line, () => resolve());
+	});
+}
+/**
+* Install an `'error'` listener on stdout so a broken pipe doesn't crash the
+* CLI with an unhandled `'error'` event. EPIPE (consumer went away, e.g.
+* `aai … --json | head -1`) exits quietly; anything else is reported on
+* stderr and exits non-zero.
+*/
+function installStdoutGuard(stream = process.stdout) {
+	stream.on("error", (err) => {
+		if (err.code === "EPIPE") process.exit(0);
+		else {
+			process.stderr.write(`stdout error: ${err.message}\n`);
+			process.exit(1);
+		}
+	});
+}
+/** Create an ok result. */
+function ok(data) {
+	return {
+		ok: true,
+		data
+	};
+}
+/** Create an error result. */
+function fail(code, error, hint) {
+	return hint ? {
+		ok: false,
+		error,
+		code,
+		hint
+	} : {
+		ok: false,
+		error,
+		code
+	};
+}
+/** Typed CLI error that carries a structured error code and optional hint. */
+var CliError = class extends Error {
+	code;
+	hint;
+	constructor(code, message, hint, options) {
+		super(message, options);
+		this.name = "CliError";
+		this.code = code;
+		if (hint !== void 0) this.hint = hint;
+	}
+};
+//#endregion
+//#region _ui.ts
+const noop = () => {};
+let silenced = false;
+/** Log instance that delegates to clack (human mode) or no-ops (JSON mode). */
+const log = new Proxy(p.log, { get(target, prop, receiver) {
+	return silenced ? noop : Reflect.get(target, prop, receiver);
+} });
+/** Replace all log methods with no-ops. Call once in JSON mode. */
+function silenceOutput() {
+	silenced = true;
+}
+/** Unwrap a clack prompt result, exiting cleanly if the user cancelled. */
+function unwrapCancel(result) {
+	if (p.isCancel(result)) {
+		p.cancel("Setup cancelled");
+		process.exit(0);
+	}
+	return result;
+}
+/** Format a URL for display. */
+function fmtUrl(url) {
+	return pc.cyanBright(url);
+}
+/**
+* Parse and validate a port string. Returns the numeric port or throws.
+*
+* Deliberately zod-free: this module loads on every CLI invocation
+* (including `aai --help`), and keeping zod off that path is the same
+* startup-cost invariant `_utils.ts` documents for its error helpers.
+*/
+function parsePort(raw) {
+	const port = raw.trim() === "" ? NaN : Number(raw);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`Invalid port: ${raw}. Must be a number between 0 and 65535.`);
+	return port;
+}
+//#endregion
+export { unwrapCancel as a, getOutputMode as c, writeLine as d, silenceOutput as i, installStdoutGuard as l, log as n, CliError as o, parsePort as r, fail as s, fmtUrl as t, ok as u };