@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/build.d.ts

@@ -4,32 +4,45 @@
  * artifact and its failures alike.
  *
  * It also LEAVES that artifact on disk, at {@link WORKER_ARTIFACT_REL}, which is
- * what makes self-hosting work: `server.mjs` loads the built worker rather than
+ * what makes self-hosting work: `aai start` loads the built worker rather than
  * `agent.ts`, because a tool is discovered by the bundler enumerating `tools/`
- * and no un-bundled loader can see that directory. See the scaffold's own
- * `server.mjs` and "Self-hosting runs the built worker" in
- * `packages/aai-templates/CLAUDE.md`.
+ * and no un-bundled loader can see that directory. See `start.ts` and
+ * "Self-hosting is the scaffold's default" in `packages/aai-cli/CLAUDE.md`.
+ *
+ * `--target` decides what else it emits — see `_build-target.ts`.
  */
+import { type BuildTarget } from "./_build-target.ts";
 import { type CommandResult } from "./_output.ts";
 /**
  * Where the built worker lands, relative to the project root — under `.aai/`,
  * beside the built client, so one gitignore rule covers every build output.
  *
- * `server.mjs` hardcodes this path: it is a plain `.mjs` file in a user's
- * project and may not import from the CLI (which a deployed project does not
- * install at all). The pair is covered end-to-end by the `npm start` leg of
- * `e2e.test.ts` — the only tier that runs both halves as a user does.
+ * `start.ts` imports this constant rather than restating the path, which it
+ * could not do while the loader was a `.mjs` file in the user's project. The
+ * pair is covered end-to-end by the `npm start` leg of `e2e.test.ts` — the only
+ * tier that runs both halves as a user does.
  */
-export declare const WORKER_ARTIFACT_REL: string;
+export { WORKER_ARTIFACT_REL } from "./_artifacts.ts";
 type BuildData = {
     name: string;
     workerBytes: number;
     /** Absolute path of the worker written — what `npm start` boots. */
     worker: string;
+    /**
+     * WHERE the prompt this bundle carries came from — see
+     * {@link systemPromptSource}.
+     */
+    systemPrompt: string;
+    /** Which deployment shape this build emitted — see `_build-target.ts`. */
+    target: BuildTarget;
 };
 export declare function executeBuild(opts: {
     cwd: string;
     skipTests?: boolean | undefined;
     skipTypecheck?: boolean | undefined;
+    /**
+     * Which deployment shape to emit beside the worker. Absent, it is detected
+     * from the host's own build environment — see `resolveBuildTarget`.
+     */
+    target?: string | undefined;
 }): Promise<CommandResult<BuildData>>;
-export {};

package/dist/cli.d.ts

@@ -1,2 +1 @@
-import { type ArgsDef, type CommandDef } from "citty";
-export declare const mainCommand: CommandDef<ArgsDef>;
+export declare const mainCommand: import("citty").CommandDef<import("citty").ArgsDef>;

package/dist/cli.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-import { i as installStdoutGuard, n as fail, o as writeLine, r as getOutputMode, t as CliError } from "./_output-DbJt9gsl.mjs";
-import { n as log, o as silenceOutput } from "./_ui-DCt4qZrk.mjs";
-import { d as resolveCwd, o as errorMessage$1, s as fileExists, t as AGENT_ENTRY, u as readPackageJson } from "./_utils-Dhd058D9.mjs";
+import { i as installStdoutGuard, n as fail, o as writeLine, r as getOutputMode, t as CliError } from "./_output-DBP9Op_d.mjs";
+import { a as parsePort, n as log, o as silenceOutput } from "./_ui-DCt4qZrk.mjs";
+import { c as fileExists, f as readPackageJson, p as resolveCwd, s as errorMessage$1, t as AGENT_ENTRY } from "./_utils-D5JGcjiW.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isRecord, omitUndefined, plural } from "@alexkroman1/aai/utils";
 import { defineCommand, runMain, showUsage } from "citty";
-import { isRecord } from "@alexkroman1/aai/utils";
 //#region src/_cli-common.ts
 /** Shared arg definitions for citty commands. */
 const sharedArgs = {
@@ -25,6 +25,19 @@ const sharedArgs = {
 		description: "Output JSON (auto-detected in non-TTY)"
 	}
 };
+/**
+* What every PLATFORM command accepts — the pair, as a group to spread.
+*
+* `sharedArgs` supplies the field VALUES, so each of the twelve credentialed
+* commands still restated the shape (`server: sharedArgs.server, json:
+* sharedArgs.json`). A flag all of them should take is then twelve edits, and
+* `assertKnownArgv` refuses the flag on whichever one was missed — after
+* release. `cli-workflow.ts`'s `workflowArgs` is the same pattern for its group.
+*/
+const platformArgs = {
+	server: sharedArgs.server,
+	json: sharedArgs.json
+};
 /** Flags citty handles itself, so no command declares them. */
 const BUILTIN_FLAGS = /* @__PURE__ */ new Set([
 	"help",
@@ -106,31 +119,42 @@ function commandPath(cmd, parent) {
 	return named.startsWith("aai") ? named : `aai ${named}`.trim();
 }
 /**
-* Unknown flags in `argv` for whichever (possibly nested) subcommand it
-* selects — `[]` when everything is declared.
+* Walk the real command tree for `argv` and report everything the pre-parse
+* guards in `cli.ts` need: which command it selects, what that command
+* declares, and whether a token mistyped a subcommand.
 *
-* Walks the real command tree rather than re-listing flags, so this cannot
-* drift from what the commands accept. An unknown SUBCOMMAND is not reported:
-* citty already answers that with usage text and a non-zero exit.
+* ONE walk, because there used to be two — this one and a copy in `cli.ts`,
+* each with its own `Resolvable` narrowing, whose only difference was the
+* terminal action. The copies also had an ORDERING dependency nothing
+* enforced: the flag guard reports nothing for a mistyped subcommand (the
+* flags would be matched against the wrong command's definition), which is
+* only safe because the command guard ran first. Answering both from one
+* result removes the ordering rather than documenting it.
 */
-async function unknownFlagsForArgv(root, argv) {
+async function resolveArgv(root, argv) {
 	let cmd = root;
+	const named = ["aai"];
 	let i = 0;
 	for (; i < argv.length; i++) {
 		const token = argv[i];
 		if (token === void 0 || token.startsWith("-")) break;
 		const subCommands = await resolve(cmd.subCommands);
-		const next = subCommands?.[token];
-		if (next === void 0) {
-			if (subCommands && Object.keys(subCommands).length > 0) return [];
-			break;
-		}
-		const resolved = await resolve(next);
-		if (resolved === void 0) break;
-		cmd = resolved;
+		if (!subCommands || Object.keys(subCommands).length === 0) break;
+		const next = await resolve(subCommands[token]);
+		if (next === void 0) return {
+			named,
+			unknownCommand: token,
+			argsDef: await resolve(cmd.args) ?? {},
+			rest: []
+		};
+		cmd = next;
+		named.push(token);
 	}
-	const argsDef = await resolve(cmd.args) ?? {};
-	return findUnknownFlags(argv.slice(i), argsDef);
+	return {
+		named,
+		argsDef: await resolve(cmd.args) ?? {},
+		rest: argv.slice(i)
+	};
 }
 /** Shared command setup: resolve cwd, optionally require agent.ts. */
 async function setup(opts) {
@@ -267,13 +291,12 @@ const secretPut = defineExec({
 			description: "Secret name. The VALUE is not an argument — pipe it in (`printf %s \"$VALUE\" | aai secret put NAME`), or be prompted, masked, when stdin is a terminal",
 			required: true
 		},
-		server: sharedArgs.server,
-		json: sharedArgs.json
+		...platformArgs
 	},
 	cwd: "any",
 	async run({ args, mode, cwd }) {
 		refuseValueInArgv(args._);
-		const { executeSecretPut, resolveSecretValue } = await import("./secret-V1w7y9-j.mjs");
+		const { executeSecretPut, resolveSecretValue } = await import("./secret-Cjp912yF.mjs");
 		const value = await resolveSecretValue(args.name, mode);
 		return executeSecretPut(cwd, args.name, value, args.server);
 	}
@@ -289,12 +312,11 @@ const secretDelete = defineExec({
 			description: "Secret name",
 			required: true
 		},
-		server: sharedArgs.server,
-		json: sharedArgs.json
+		...platformArgs
 	},
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeSecretDelete } = await import("./secret-V1w7y9-j.mjs");
+		const { executeSecretDelete } = await import("./secret-Cjp912yF.mjs");
 		return executeSecretDelete(cwd, args.name, args.server);
 	}
 });
@@ -303,13 +325,10 @@ const secretList = defineExec({
 		name: "list",
 		description: "List all secrets"
 	},
-	args: {
-		server: sharedArgs.server,
-		json: sharedArgs.json
-	},
+	args: { ...platformArgs },
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeSecretList } = await import("./secret-V1w7y9-j.mjs");
+		const { executeSecretList } = await import("./secret-Cjp912yF.mjs");
 		return executeSecretList(cwd, args.server);
 	}
 });
@@ -344,12 +363,11 @@ const logs = defineExec({
 			alias: "f",
 			description: "Keep printing new output"
 		},
-		server: sharedArgs.server,
-		json: sharedArgs.json
+		...platformArgs
 	},
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeLogs } = await import("./logs-DGwPNCzB.mjs");
+		const { executeLogs } = await import("./logs-7BRwq0cG.mjs");
 		return executeLogs(resolveDirArg(cwd, args.dir), {
 			server: args.server,
 			follow: args.follow
@@ -374,13 +392,10 @@ const list = defineExec({
 		name: "list",
 		description: "List your studio projects"
 	},
-	args: {
-		server: sharedArgs.server,
-		json: sharedArgs.json
-	},
+	args: { ...platformArgs },
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeList } = await import("./studio-BpMCfUNx.mjs");
+		const { executeList } = await import("./studio-C_zuRC_z.mjs");
 		return executeList({
 			cwd,
 			server: args.server
@@ -408,12 +423,11 @@ const pull = defineExec({
 			alias: "f",
 			description: "Overwrite files in a non-empty directory"
 		},
-		server: sharedArgs.server,
-		json: sharedArgs.json
+		...platformArgs
 	},
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executePull } = await import("./studio-BpMCfUNx.mjs");
+		const { executePull } = await import("./studio-C_zuRC_z.mjs");
 		return executePull({
 			cwd,
 			project: args.project,
@@ -430,12 +444,11 @@ const push = defineExec({
 	},
 	args: {
 		force: forceArg,
-		server: sharedArgs.server,
-		json: sharedArgs.json
+		...platformArgs
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executePush } = await import("./studio-BpMCfUNx.mjs");
+		const { executePush } = await import("./studio-C_zuRC_z.mjs");
 		return executePush({
 			cwd,
 			server: args.server,
@@ -450,8 +463,7 @@ const publish = defineExec({
 	},
 	args: {
 		force: forceArg,
-		server: sharedArgs.server,
-		json: sharedArgs.json,
+		...platformArgs,
 		skipTypecheck: {
 			type: "boolean",
 			description: "Skip type checking before publishing"
@@ -459,7 +471,7 @@ const publish = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executePublish } = await import("./studio-BpMCfUNx.mjs");
+		const { executePublish } = await import("./studio-C_zuRC_z.mjs");
 		return executePublish({
 			cwd,
 			server: args.server,
@@ -497,7 +509,7 @@ const workflowToken = {
 * and until this flag existed there was no way to say so: every verb resolved a
 * platform origin plus a PUBLISHED slug, so an undeployed project was told to
 * `aai publish` while the runs it asked about were answering on localhost. A
-* dev server also has no slug segment at all (`createServer` mounts the API on
+* dev server also has no slug segment at all (`createRuntimeServer` mounts the API on
 * the origin), so a different `--server` could not express it either.
 *
 * Separate from `--server` rather than a mode of it, because the two carry
@@ -521,8 +533,7 @@ const runIdArg = {
 * without `--token`.
 */
 const workflowArgs = {
-	server: sharedArgs.server,
-	json: sharedArgs.json,
+	...platformArgs,
 	token: workflowToken,
 	agent: workflowAgent
 };
@@ -532,6 +543,19 @@ const workflowArgs = {
 * never edited still names a deployed agent whose runs are worth asking about.
 */
 const WORKFLOW_CWD = "any";
+/**
+* The group flags, forwarded.
+*
+* The declaration side is DRY (`workflowArgs`) and the forwarding side was not:
+* four hand-copied `{ server, token, agent }` triples, in the module whose own
+* doc argues that "four hand-copied triples is how one of them ends up without
+* `--token`". A fifth group flag is one edit here rather than four below.
+*/
+const workflowOpts = (args) => ({
+	server: args.server,
+	token: args.token,
+	agent: args.agent
+});
 const workflowList = defineExec({
 	meta: {
 		name: "list",
@@ -540,12 +564,8 @@ const workflowList = defineExec({
 	args: workflowArgs,
 	cwd: WORKFLOW_CWD,
 	async run({ args, cwd }) {
-		const { executeWorkflowList } = await import("./workflow-BZyKLkhV.mjs");
-		return executeWorkflowList(cwd, {
-			server: args.server,
-			token: args.token,
-			agent: args.agent
-		});
+		const { executeWorkflowList } = await import("./workflow-CVioyO3V.mjs");
+		return executeWorkflowList(cwd, workflowOpts(args));
 	}
 });
 const workflowRuns = defineExec({
@@ -567,13 +587,11 @@ const workflowRuns = defineExec({
 	},
 	cwd: WORKFLOW_CWD,
 	async run({ args, cwd }) {
-		const { executeWorkflowRuns } = await import("./workflow-BZyKLkhV.mjs");
+		const { executeWorkflowRuns } = await import("./workflow-CVioyO3V.mjs");
 		const limit = args.limit === void 0 ? void 0 : Number(args.limit);
 		if (limit !== void 0 && !Number.isFinite(limit)) throw new CliError("bad_limit", "--limit must be a number");
 		return executeWorkflowRuns(cwd, args.workflow, {
-			server: args.server,
-			token: args.token,
-			agent: args.agent,
+			...workflowOpts(args),
 			limit
 		});
 	}
@@ -589,12 +607,8 @@ const workflowShow = defineExec({
 	},
 	cwd: WORKFLOW_CWD,
 	async run({ args, cwd }) {
-		const { executeWorkflowShow } = await import("./workflow-BZyKLkhV.mjs");
-		return executeWorkflowShow(cwd, args.runId, {
-			server: args.server,
-			token: args.token,
-			agent: args.agent
-		});
+		const { executeWorkflowShow } = await import("./workflow-CVioyO3V.mjs");
+		return executeWorkflowShow(cwd, args.runId, workflowOpts(args));
 	}
 });
 const workflowCancel = defineExec({
@@ -608,12 +622,8 @@ const workflowCancel = defineExec({
 	},
 	cwd: WORKFLOW_CWD,
 	async run({ args, cwd }) {
-		const { executeWorkflowCancel } = await import("./workflow-BZyKLkhV.mjs");
-		return executeWorkflowCancel(cwd, args.runId, {
-			server: args.server,
-			token: args.token,
-			agent: args.agent
-		});
+		const { executeWorkflowCancel } = await import("./workflow-CVioyO3V.mjs");
+		return executeWorkflowCancel(cwd, args.runId, workflowOpts(args));
 	}
 });
 const workflow = defineCommand({
@@ -683,7 +693,7 @@ const init = defineExec({
 		template: {
 			type: "string",
 			alias: "t",
-			description: "Template to use (run `aai templates` for the list)"
+			description: "Template to use (prompted when omitted)"
 		},
 		server: sharedArgs.server,
 		yes: sharedArgs.yes,
@@ -695,7 +705,7 @@ const init = defineExec({
 	},
 	cwd: "none",
 	async run({ args, mode }) {
-		const { executeInit } = await import("./init-D-vFrV8h.mjs");
+		const { executeInit } = await import("./init-CFyusRbq.mjs");
 		return executeInit({
 			dir: args.dir,
 			force: args.force,
@@ -726,7 +736,7 @@ const dev = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeDev } = await import("./dev-DamXieW_.mjs");
+		const { executeDev } = await import("./dev-Bx9gYBHM.mjs");
 		return executeDev({
 			cwd,
 			port: args.port,
@@ -734,6 +744,35 @@ const dev = defineExec({
 		});
 	}
 });
+const start = defineExec({
+	meta: {
+		name: "start",
+		description: "Serve the built agent (production)"
+	},
+	args: {
+		port: {
+			type: "string",
+			alias: "p",
+			description: "Port to listen on"
+		},
+		host: {
+			type: "string",
+			description: "Address to bind (default: loopback)"
+		},
+		json: sharedArgs.json
+	},
+	cwd: "agent",
+	async run({ args, cwd }) {
+		const { executeStart } = await import("./start.mjs");
+		return executeStart({
+			cwd,
+			...omitUndefined({
+				port: args.port === void 0 ? void 0 : parsePort(args.port),
+				host: args.host?.trim() || void 0
+			})
+		});
+	}
+});
 const test = defineExec({
 	meta: {
 		name: "test",
@@ -748,7 +787,7 @@ const test = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeTest } = await import("./test-guenJUxi.mjs");
+		const { executeTest } = await import("./test-D032V2cA.mjs");
 		return executeTest(cwd, { all: args.all === true });
 	}
 });
@@ -760,7 +799,7 @@ const evalCommand = defineExec({
 	args: { json: sharedArgs.json },
 	cwd: "agent",
 	async run({ cwd }) {
-		const { executeEval } = await import("./eval-h3DTVfRw.mjs");
+		const { executeEval } = await import("./eval-B3I7FqN9.mjs");
 		return executeEval(cwd);
 	}
 });
@@ -778,15 +817,20 @@ const build = defineExec({
 		skipTypecheck: {
 			type: "boolean",
 			description: "Skip type checking before build"
+		},
+		target: {
+			type: "string",
+			description: "Deployment shape to emit (node, vercel; default: detected)"
 		}
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeBuild } = await import("./build-CWyFGe-W.mjs");
+		const { executeBuild } = await import("./build-BhEaxBPu.mjs");
 		return executeBuild({
 			cwd,
 			skipTests: args.skipTests,
-			skipTypecheck: args.skipTypecheck
+			skipTypecheck: args.skipTypecheck,
+			target: args.target
 		});
 	}
 });
@@ -797,8 +841,7 @@ const deploy = defineExec({
 		hidden: true
 	},
 	args: {
-		server: sharedArgs.server,
-		json: sharedArgs.json,
+		...platformArgs,
 		allowPreviewSlug: {
 			type: "boolean",
 			description: "Permit a `-preview`-suffixed slug (reserved for studio auto-previews; studio-internal — a slug you claim this way is subject to the preview reaper)"
@@ -810,7 +853,7 @@ const deploy = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeDeploy } = await import("./deploy-B7f3CK7v.mjs");
+		const { executeDeploy } = await import("./deploy-CGqPU5U-.mjs");
 		return executeDeploy({
 			cwd,
 			server: args.server,
@@ -824,13 +867,10 @@ const del = defineExec({
 		name: "delete",
 		description: "Delete the studio project and its deployed agents"
 	},
-	args: {
-		server: sharedArgs.server,
-		json: sharedArgs.json
-	},
+	args: { ...platformArgs },
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeDelete } = await import("./delete-RqlQZ6Y_.mjs");
+		const { executeDelete } = await import("./delete-BdFnbnVR.mjs");
 		return executeDelete({
 			cwd,
 			server: args.server
@@ -842,13 +882,10 @@ const login = defineExec({
 		name: "login",
 		description: "Link your signed-in browser account and save your API key"
 	},
-	args: {
-		server: sharedArgs.server,
-		json: sharedArgs.json
-	},
+	args: { ...platformArgs },
 	cwd: "none",
 	async run({ args }) {
-		const { executeLogin } = await import("./login-CDiemNmC.mjs");
+		const { executeLogin } = await import("./login-DaLrPOFg.mjs");
 		return executeLogin({ server: args.server });
 	}
 });
@@ -860,7 +897,7 @@ const templates = defineExec({
 	args: { json: sharedArgs.json },
 	cwd: "none",
 	async run({ mode }) {
-		const { listTemplates } = await import("./_templates-V4l5sZJy.mjs");
+		const { listTemplates } = await import("./_templates-CIlJ3Vay.mjs");
 		const names = await listTemplates();
 		if (mode === "human") {
 			for (const name of names) log.message(name);
@@ -877,6 +914,7 @@ const mainCommand = defineCommand({
 	subCommands: {
 		init,
 		dev,
+		start,
 		test,
 		eval: evalCommand,
 		build,
@@ -955,57 +993,36 @@ if (process.env.VITEST !== "true") {
 		process.exit(1);
 	};
 	/**
-	* Resolve a citty `Resolvable` field. The cast is `Resolvable<T>` admitting
-	* `T` itself, so `typeof value === "function"` narrows to `T & Function`
-	* alongside the two thunk signatures; `_cli-common.ts`'s copy does the same.
-	*/
-	const resolveField = async (value) => typeof value === "function" ? await value() : await value;
-	/**
-	* Answer an unknown SUBCOMMAND here rather than leaving it to citty.
+	* Refuse a mistyped command or an unrecognized flag instead of letting
+	* either through — both read off ONE walk of the command tree.
 	*
-	* citty throws `Unknown command ${cyan(name)}` and its own catch writes that
-	* message with `console.error` — colour escapes and all, whatever the output
-	* mode and whether or not stderr is a terminal — AFTER `showUsage` has
-	* already emitted the result line. So `aai deploy-now | jq` produced an
-	* envelope that named `aai` instead of the token the user typed, plus an
-	* ANSI-studded sentence on stderr that no JSON consumer asked for. Reported
-	* here instead: the envelope names the command, and nothing colours a pipe.
+	* An unknown SUBCOMMAND is answered here rather than by citty, which throws
+	* `Unknown command ${cyan(name)}` and writes it with `console.error` —
+	* colour escapes and all, whatever the output mode and whether or not stderr
+	* is a terminal — AFTER `showUsage` has already emitted the result line. So
+	* `aai deploy-now | jq` produced an envelope that named `aai` instead of the
+	* token the user typed, plus an ANSI-studded sentence on stderr that no JSON
+	* consumer asked for. Reported here instead: the envelope names the command,
+	* and nothing colours a pipe.
 	*
-	* The tree walk is the same one `unknownFlagsForArgv` does in
-	* `_cli-common.ts`, which cannot report this case (it returns `[]` for it,
-	* because the flags would be matched against the wrong command). Worth
-	* hoisting into that module next to it.
-	*/
-	const assertKnownCommand = async () => {
-		let cmd = mainCommand;
-		const named = ["aai"];
-		for (const token of process.argv.slice(2)) {
-			if (token.startsWith("-")) return;
-			const subCommands = await resolveField(cmd.subCommands);
-			if (!subCommands || Object.keys(subCommands).length === 0) return;
-			const next = await resolveField(subCommands[token]);
-			if (next === void 0) {
-				await reportAndExit(`Unknown command: ${token}`, `Run \`${named.join(" ")} --help\` to see the commands it accepts.`);
-				return;
-			}
-			cmd = next;
-			named.push(token);
-		}
-	};
-	/**
-	* Refuse an unrecognized flag instead of ignoring it.
+	* An unknown FLAG is refused because citty drops one silently, so
+	* `aai push --serverr=http://x` exited 0 having pushed to the DEFAULT server.
+	* `--server` decides where the API key and secret values go, so a typo that
+	* quietly retargets it is worth failing on.
 	*
-	* citty drops one silently, so `aai push --serverr=http://x` exited 0 having
-	* pushed to the DEFAULT server. `--server` decides where the API key and
-	* secret values go, so a typo that quietly retargets it is worth failing on.
+	* The command check comes first because a flag can only be judged against
+	* the right command's `argsDef` — which is why `resolveArgv` reports the two
+	* together instead of leaving the order to this call site.
 	*/
-	const assertKnownFlags = async () => {
-		const unknown = await unknownFlagsForArgv(mainCommand, process.argv.slice(2));
+	const assertKnownArgv = async () => {
+		const { named, unknownCommand, argsDef, rest } = await resolveArgv(mainCommand, process.argv.slice(2));
+		if (unknownCommand !== void 0) await reportAndExit(`Unknown command: ${unknownCommand}`, `Run \`${named.join(" ")} --help\` to see the commands it accepts.`);
+		const unknown = findUnknownFlags(rest, argsDef);
 		if (unknown.length === 0) return;
-		const label = `Unknown ${unknown.length === 1 ? "option" : "options"}: ${unknown.join(", ")}`;
+		const label = `Unknown ${plural(unknown.length, "option")}: ${unknown.join(", ")}`;
 		await reportAndExit(label, "Run `aai <command> --help` to see the options it accepts.");
 	};
-	runDefault().then(assertKnownCommand).then(assertKnownFlags).then(() => runMain(mainCommand, { showUsage: usageForMode })).catch((err) => {
+	runDefault().then(assertKnownArgv).then(() => runMain(mainCommand, { showUsage: usageForMode })).catch((err) => {
 		log.error(errorMessage$1(err));
 		process.exitCode = 1;
 	});

package/dist/{client-bundler-CT-_26c5.mjs → client-bundler-6mTLs6ny.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { o as errorMessage$1, s as fileExists } from "./_utils-Dhd058D9.mjs";
+import { c as fileExists, s as errorMessage$1 } from "./_utils-D5JGcjiW.mjs";
 import { n as withPreservedNodeEnv, t as DEDUPED_PEERS } from "./_vite-env-kejF0p2L.mjs";
 import { existsSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -81,10 +81,10 @@ const DEFAULT_OUT_DIR = ".aai/client";
 * @internal — build hook for aai-server/the studio; not a supported public
 * API and not covered by semver.
 */
-async function buildClient(cwd, opts = {}) {
+async function buildClient(cwd, options = {}) {
 	const clientEntry = path.join(cwd, "client.tsx");
 	if (!await fileExists(clientEntry)) return {};
-	const outDir = opts.outDir ?? DEFAULT_OUT_DIR;
+	const outDir = options.outDir ?? DEFAULT_OUT_DIR;
 	const clientDir = path.join(cwd, outDir);
 	let cleanupHtml = () => {};
 	try {
@@ -93,8 +93,8 @@ async function buildClient(cwd, opts = {}) {
 			root: cwd,
 			base: "./",
 			logLevel: "silent",
-			...opts.configFile === false && { configFile: false },
-			...omitUndefined({ plugins: opts.plugins }),
+			...options.configFile === false && { configFile: false },
+			...omitUndefined({ plugins: options.plugins }),
 			resolve: { dedupe: DEDUPED_PEERS },
 			build: {
 				outDir,

package/dist/client-bundler.d.ts

@@ -27,4 +27,4 @@ export type BuildClientOptions = {
  * @internal — build hook for aai-server/the studio; not a supported public
  * API and not covered by semver.
  */
-export declare function buildClient(cwd: string, opts?: BuildClientOptions): Promise<Record<string, string>>;
+export declare function buildClient(cwd: string, options?: BuildClientOptions): Promise<Record<string, string>>;

package/dist/client-bundler.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { t as buildClient } from "./client-bundler-CT-_26c5.mjs";
+import { t as buildClient } from "./client-bundler-6mTLs6ny.mjs";
 export { buildClient };