@alexkroman1/aai-cli 13.2.0 → 14.0.0

package/dist/{_init-BURbdHNM.mjs → _init-CQ8idAwo.mjs}

@@ -1,10 +1,25 @@
 #!/usr/bin/env node
-import { c as isEexist, l as readJson, p as writeJson } from "./_utils-B8QmtFhK.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-BTwZJu4P.mjs";
-import { REPO_URL, downloadAndMergeTemplate } from "./_templates-0Zr2z6yA.mjs";
+import { d as readJson, g as writeJson, i as compareCodeUnits, u as isEexist } from "./_utils-D5JGcjiW.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-BzUeqOdj.mjs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-CK4oKoeX.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
-//#region _init.ts
+//#region src/_init.ts
+/**
+* The README every scaffolded project gets, and the first thing a new author
+* reads. Three things in it are corrections rather than prose:
+*
+* - **`npm run dev`, never a bare `aai dev`.** The CLI is a devDependency, so
+*   after `npm install` the binary is in `node_modules/.bin` and NOT on
+*   `PATH`. The old quickstart said `aai dev`, which fails with
+*   `command not found` for everyone who has not installed the CLI globally.
+* - **The key `aai dev` needs is named, with the two LOCAL ways first.** No
+*   step of local development needs a platform account; a twenty-persona DX
+*   audit read the account-shaped failure it used to get and concluded the
+*   opposite, then stopped using the loop this file documents.
+* - **`aai login` appears where it is actually required.** It was in no
+*   user-facing doc at all, while the quickstart's own publish step needs it.
+*/
 function readmeContent(slug) {
 	return `# ${slug}
 
@@ -14,8 +29,41 @@ A voice agent built with [aai](${REPO_URL}).
 
 \`\`\`sh
 npm install        # Install dependencies
-aai dev            # Run locally (opens browser)
-aai publish        # Publish to production (and sync to the studio)
+npm run dev        # Run locally on http://localhost:3000 (opens browser)
+\`\`\`
+
+The \`aai\` CLI is a devDependency of this project, so it lives in
+\`node_modules/.bin\` rather than on your \`PATH\`. Run it through npm
+(\`npm run dev\`, \`npm test\`, \`npm run build\`) or with \`npx aai <command>\`.
+
+### The one key local development needs
+
+The default pipeline (speech-to-text → LLM → text-to-speech) runs on a single
+AssemblyAI key. **Any one of these is enough, and the first two need no aai
+account** — nothing about running this agent locally is gated on one:
+
+1. Put \`ASSEMBLYAI_API_KEY=<your key>\` in \`.env\` (this project's \`.env.example\`
+   documents it, and it is the same file \`aai publish\` uploads as secrets).
+2. Or export it in your shell: \`export ASSEMBLYAI_API_KEY=<your key>\`.
+3. Or run \`npx aai login\`, and \`aai dev\` will use your account's key.
+
+Get a key at <https://www.assemblyai.com/dashboard>.
+
+## Publishing
+
+Publishing (and the studio it syncs to) is the one part that does need an
+account:
+
+\`\`\`sh
+npx aai login          # Link your account — once per machine
+npm run publish:agent  # Publish to production (and sync to the studio)
+\`\`\`
+
+You can also run this agent as a plain Node server, with no aai account and
+nothing managed:
+
+\`\`\`sh
+npm start              # Builds, then serves on http://127.0.0.1:3000
 \`\`\`
 
 ## Secrets
@@ -32,9 +80,9 @@ MY_API_KEY=secret-value
 **Production** — set secrets on the server:
 
 \`\`\`sh
-aai secret put MY_KEY    # Set a secret (prompts for value)
-aai secret list          # List secret names
-aai secret delete MY_KEY # Remove a secret
+npx aai secret put MY_KEY    # Set a secret (prompts for value)
+npx aai secret list          # List secret names
+npx aai secret delete MY_KEY # Remove a secret
 \`\`\`
 
 `;
@@ -71,17 +119,6 @@ async function patchPackageJsonForWorkspace(targetDir) {
 	await pinSharedDeps(targetDir, packagesDir, pkgJson);
 }
 /**
-* Code-unit ordering, never `localeCompare`.
-*
-* With no explicit locale that answers to the runtime's ICU default, so the same
-* project would scaffold a differently-ordered file on a different machine —
-* which is the reason the repo's own generated artifacts sort this way too.
-*/
-function compareNames(a, b) {
-	if (a === b) return 0;
-	return a < b ? -1 : 1;
-}
-/**
 * Pin every THIRD-PARTY dependency this project shares with a linked workspace
 * package to the copy that workspace package resolved.
 *
@@ -114,17 +151,14 @@ async function pinSharedDeps(targetDir, packagesDir, pkgJson) {
 		...pkgJson.devDependencies
 	};
 	const linked = Object.entries(WORKSPACE_PKG_DIRS).filter(([name]) => name in declared).map(([, dir]) => dir);
-	const pins = /* @__PURE__ */ new Map();
-	for (const name of Object.keys(declared)) {
-		if (name in WORKSPACE_PKG_DIRS) continue;
+	const resolved = await Promise.all(Object.keys(declared).filter((name) => !(name in WORKSPACE_PKG_DIRS)).map(async (name) => {
 		for (const dir of linked) {
 			const manifest = await readJson(path.join(packagesDir, dir, "node_modules", name, "package.json"));
-			if (typeof manifest?.version === "string") {
-				pins.set(name, manifest.version);
-				break;
-			}
+			if (typeof manifest?.version === "string") return [name, manifest.version];
 		}
-	}
+		return null;
+	}));
+	const pins = new Map(resolved.filter((entry) => entry !== null));
 	if (pins.size === 0) return;
 	const file = path.join(targetDir, "pnpm-workspace.yaml");
 	let existing;
@@ -133,8 +167,8 @@ async function pinSharedDeps(targetDir, packagesDir, pkgJson) {
 	} catch {
 		return;
 	}
-	const block = [...pins].sort(([a], [b]) => compareNames(a, b)).map(([name, version]) => `  "${name}": "${version}"`).join("\n");
-	await fs.writeFile(file, `${existing.trimEnd()}\n\n# Added by \`aai init\` in DEV MODE only — see pinSharedDeps in\n# packages/aai-cli/_init.ts. The @alexkroman1/* packages above are LINKED to
+	const block = [...pins].sort(([a], [b]) => compareCodeUnits(a, b)).map(([name, version]) => `  "${name}": "${version}"`).join("\n");
+	await fs.writeFile(file, `${existing.trimEnd()}\n\n# Added by \`aai init\` in DEV MODE only — see pinSharedDeps in\n# packages/aai-cli/src/_init.ts. The @alexkroman1/* packages above are LINKED to
 # this checkout, so anything they and this project both depend on has to be
 # ONE copy: two copies of xstate are two incompatible sets of types, and the
 # typecheck gate refuses the deploy.\noverrides:\n${block}\n`);

package/dist/{_output-CKkmWs7i.mjs → _output-DBP9Op_d.mjs}

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-//#region _output.ts
+import { stripVTControlCharacters } from "node:util";
+//#region src/_output.ts
+/**
+* Structured output support for CLI commands.
+*
+* In JSON mode (non-TTY or --json), commands emit exactly one JSON line to
+* stdout. In human mode (TTY, default), commands use @clack/prompts as before.
+*/
 /**
 * Determine output mode from CLI flags and TTY state.
 *
@@ -11,7 +18,39 @@ function getOutputMode(args, isTTY = Boolean(process.stdout.isTTY)) {
 	return isTTY ? "human" : "json";
 }
 /**
-* Write a line to stdout, resolving only once it has been flushed.
+* A terminal escape sequence AFTER `JSON.stringify`, which escapes the ESC
+* byte as the six characters `\u001b`. Needed alongside the raw form because a
+* caller stringifies a whole result and hands the line here — see
+* {@link writeLine} — and no builtin reads that spelling.
+*/
+const ANSI_JSON = /\\u001[bB]\[[0-?]*[ -/]*[@-~]/g;
+/**
+* Remove ANSI escape sequences, in raw or JSON-escaped form.
+*
+* A bundler colours its own diagnostics unconditionally, so `aai build`'s
+* failure reached the JSON envelope as per-character SGR pairs — illegible in a
+* CI log and meaningless to a `jq` consumer, which is the audience JSON mode
+* has.
+*
+* The raw half is `node:util`'s, not a local CSI regex. A/B'd on Node 26: the
+* two agree on every SGR pair and cursor move the hand-built pattern was
+* written for, and the builtin ALSO strips OSC-8 hyperlinks (`ESC ] 8 ;; url`)
+* and charset selects (`ESC ( B`), which that pattern left in the envelope — so
+* its claim to cover what a diagnostic arrives wearing was the incomplete part.
+* The JSON-escaped half has no builtin and stays.
+*/
+function stripAnsi(text) {
+	return stripVTControlCharacters(text).replace(ANSI_JSON, "");
+}
+/**
+* Write a machine-readable line to stdout, resolving only once it has been
+* flushed.
+*
+* ANSI escapes are stripped on the way out. This function carries JSON mode's
+* one result line and nothing else — human output goes through `log.*` in
+* `_ui.ts`, which is where colour belongs — so stripping here is what keeps
+* the envelope clean no matter which module built the string inside it, and
+* leaves a TTY's coloured diagnostic intact.
 *
 * Resolves (never rejects) even when the write fails: the common failure is
 * EPIPE — the consumer closed the pipe (`aai … --json | head -1`) — and there
@@ -19,8 +58,9 @@ function getOutputMode(args, isTTY = Boolean(process.stdout.isTTY)) {
 * Stream-level `'error'` events are handled by {@link installStdoutGuard}.
 */
 function writeLine(line) {
+	const clean = stripAnsi(line);
 	return new Promise((resolve) => {
-		process.stdout.write(line, () => resolve());
+		process.stdout.write(clean, () => resolve());
 	});
 }
 /**

package/dist/_output.d.ts

@@ -1,9 +1,3 @@
-/**
- * Structured output support for CLI commands.
- *
- * In JSON mode (non-TTY or --json), commands emit exactly one JSON line to
- * stdout. In human mode (TTY, default), commands use @clack/prompts as before.
- */
 export type OutputMode = "json" | "human";
 export type CommandResult<T> = {
     ok: true;
@@ -23,7 +17,30 @@ export declare function getOutputMode(args: {
     json?: boolean | undefined;
 }, isTTY?: boolean): OutputMode;
 /**
- * Write a line to stdout, resolving only once it has been flushed.
+ * Remove ANSI escape sequences, in raw or JSON-escaped form.
+ *
+ * A bundler colours its own diagnostics unconditionally, so `aai build`'s
+ * failure reached the JSON envelope as per-character SGR pairs — illegible in a
+ * CI log and meaningless to a `jq` consumer, which is the audience JSON mode
+ * has.
+ *
+ * The raw half is `node:util`'s, not a local CSI regex. A/B'd on Node 26: the
+ * two agree on every SGR pair and cursor move the hand-built pattern was
+ * written for, and the builtin ALSO strips OSC-8 hyperlinks (`ESC ] 8 ;; url`)
+ * and charset selects (`ESC ( B`), which that pattern left in the envelope — so
+ * its claim to cover what a diagnostic arrives wearing was the incomplete part.
+ * The JSON-escaped half has no builtin and stays.
+ */
+export declare function stripAnsi(text: string): string;
+/**
+ * Write a machine-readable line to stdout, resolving only once it has been
+ * flushed.
+ *
+ * ANSI escapes are stripped on the way out. This function carries JSON mode's
+ * one result line and nothing else — human output goes through `log.*` in
+ * `_ui.ts`, which is where colour belongs — so stripping here is what keeps
+ * the envelope clean no matter which module built the string inside it, and
+ * leaves a TTY's coloured diagnostic intact.
  *
  * Resolves (never rejects) even when the write fails: the common failure is
  * EPIPE — the consumer closed the pipe (`aai … --json | head -1`) — and there

package/dist/{_preflight-Co1G9Jww.mjs → _preflight-CcAR577V.mjs}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { plural } from "@alexkroman1/aai/utils";
 import { requiredProviderEnvVars } from "@alexkroman1/aai-runtime";
-//#region _preflight.ts
+//#region src/_preflight.ts
 /**
 * The deploy-time credential preflight — the classic dev/prod failure, caught
 * before the upload instead of at the deployed agent's first session.
@@ -39,8 +40,7 @@ function missingCredentials(config, env) {
 }
 /** One line naming the missing keys and what to do about them. */
 function missingCredentialMessage(missing) {
-	const plural = missing.length > 1;
-	return `Missing credential${plural ? "s" : ""} the agent needs to start: ${missing.join(", ")}. Declare ${plural ? "them" : "it"} in .env and redeploy (already set on the platform with \`aai secret put\`? then this is already handled).`;
+	return `Missing ${plural(missing.length, "credential")} the agent needs to start: ${missing.join(", ")}. Declare ${plural(missing.length, "it", "them")} in .env and redeploy (already set on the platform with \`aai secret put\`? then this is already handled).`;
 }
 //#endregion
 export { missingCredentialMessage, missingCredentials };

package/dist/_resource-commands.d.ts

@@ -1,5 +1,14 @@
 export declare const secret: import("citty").CommandDef<import("citty").ArgsDef>;
 export declare const logs: import("citty").CommandDef<{
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
     readonly dir: {
         readonly type: "positional";
         readonly description: "Project directory";
@@ -10,13 +19,4 @@ export declare const logs: import("citty").CommandDef<{
         readonly alias: "f";
         readonly description: "Keep printing new output";
     };
-    readonly server: {
-        readonly type: "string";
-        readonly alias: "s";
-        readonly description: "Platform server URL";
-    };
-    readonly json: {
-        readonly type: "boolean";
-        readonly description: "Output JSON (auto-detected in non-TTY)";
-    };
 }>;

package/dist/{_server-common-6e0QI4mq.mjs → _server-common-vILJp3it.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { i as errorCode } from "./_utils-B8QmtFhK.mjs";
+import { a as errorCode } from "./_utils-D5JGcjiW.mjs";
 import path from "node:path";
 import { parseEnv } from "node:util";
 import fs from "node:fs/promises";
-//#region _server-common.ts
+//#region src/_server-common.ts
 /**
 * Build the `ctx.env` record that agent tools will see at runtime.
 *
@@ -35,7 +35,7 @@ async function resolveServerEnv(cwd, baseEnv) {
 	const env = {};
 	for (const [key, fileVal] of Object.entries(fileEntries)) {
 		const val = source[key] ?? fileVal;
-		if (val !== void 0) env[key] = val;
+		if (val !== void 0 && val !== "") env[key] = val;
 	}
 	return env;
 }

package/dist/{_slug-api-CfGQq1Tt.mjs → _slug-api-CGvc2YSQ.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { n as getServerInfo } from "./_agent-BTwZJu4P.mjs";
-import { l as HINT_NOT_DEPLOYED, s as studioProjectApiUrl, u as apiRequest } from "./_studio-B1waXMuR.mjs";
-//#region _slug-api.ts
+import { n as getServerInfo } from "./_agent-BzUeqOdj.mjs";
+import { l as HINT_NOT_DEPLOYED, s as studioProjectApiUrl, u as apiRequest } from "./_studio-DnR_BqFp.mjs";
+//#region src/_slug-api.ts
 /**
 * Authenticated request against a deployed agent's slug-scoped resource
 * (`${serverUrl}/${slug}${resourcePath}`) — the one shape every per-agent
@@ -43,12 +43,21 @@ async function secretRequest(cwd, resourcePath, init, server) {
 		target: studioProject ?? slug
 	};
 }
-async function slugRequest(cwd, resourcePath, init, server) {
-	const { serverUrl, slug, apiKey } = await getServerInfo(cwd, server);
-	return {
-		data: await deployedAgentRequest(`${serverUrl}/${slug}${resourcePath}`, init, apiKey),
-		slug
-	};
+/**
+* A slug-scoped request against an ALREADY-resolved target.
+*
+* {@link slugRequest} resolves per call, which is right for a command that
+* issues one request and wrong for one that POLLS. `aai logs --follow` re-entered
+* `getServerInfo` on every tick — a read and zod parse of `.aai/project.json`, a
+* read of the global config, a `new URL` trust check, a slug-shape test, and with
+* `--server` an `approveServer` that takes the CROSS-PROCESS config lock — once a
+* second for the life of the follow, all of it re-deriving an immutable answer.
+* `delete.ts` documents the same cost and answers it the same way, by hand; this
+* is the general version, so the next polling command inherits it.
+*/
+async function slugRequestOn(target, resourcePath, init) {
+	const { serverUrl, slug, apiKey } = target;
+	return deployedAgentRequest(`${serverUrl}/${slug}${resourcePath}`, init, apiKey);
 }
 //#endregion
-export { slugRequest as n, secretRequest as t };
+export { slugRequestOn as n, secretRequest as t };

package/dist/_slug-api.d.ts

@@ -27,6 +27,25 @@ export declare function secretRequest<T = unknown>(cwd: string, resourcePath: st
     data: T;
     target: string;
 }>;
+/** An already-resolved deployed target — what {@link slugRequestOn} needs. */
+export type SlugTarget = {
+    serverUrl: string;
+    slug: string;
+    apiKey: string;
+};
+/**
+ * A slug-scoped request against an ALREADY-resolved target.
+ *
+ * {@link slugRequest} resolves per call, which is right for a command that
+ * issues one request and wrong for one that POLLS. `aai logs --follow` re-entered
+ * `getServerInfo` on every tick — a read and zod parse of `.aai/project.json`, a
+ * read of the global config, a `new URL` trust check, a slug-shape test, and with
+ * `--server` an `approveServer` that takes the CROSS-PROCESS config lock — once a
+ * second for the life of the follow, all of it re-deriving an immutable answer.
+ * `delete.ts` documents the same cost and answers it the same way, by hand; this
+ * is the general version, so the next polling command inherits it.
+ */
+export declare function slugRequestOn<T = unknown>(target: SlugTarget, resourcePath: string, init: SlugRequestInit): Promise<T>;
 export declare function slugRequest<T = unknown>(cwd: string, resourcePath: string, init: SlugRequestInit, server?: string): Promise<{
     data: T;
     slug: string;

package/dist/{_studio-B1waXMuR.mjs → _studio-DnR_BqFp.mjs}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-import { t as CliError } from "./_output-CKkmWs7i.mjs";
+import { t as CliError } from "./_output-DBP9Op_d.mjs";
 import path from "node:path";
 import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { MAX_SLUG_LENGTH, PREVIEW_SLUG_SUFFIX, VALID_SLUG_RE } from "@alexkroman1/aai/internal";
 import { isLocalOnlyFile, snapshotWorkspaceFiles } from "@alexkroman1/aai/workspace-files";
 import { FetchError, ofetch } from "ofetch";
 import { slugifyName } from "@alexkroman1/aai/slugify";
-//#region _api-client.ts
+//#region src/_api-client.ts
 /**
 * Shared HTTP helper for platform API calls (deploy, delete, secrets).
 *
@@ -143,7 +143,7 @@ function toApiError(err, url, opts) {
 	return new Error(`${opts.action} failed: could not reach ${url}\n  ${hint}`, { cause });
 }
 //#endregion
-//#region _studio.ts
+//#region src/_studio.ts
 /**
 * Internals of the studio-workspace commands (`aai list/pull/push/publish`):
 * the local source-file walk and the thin clients for the platform's
@@ -221,7 +221,11 @@ function fetchStudioProject(serverUrl, apiKey, project) {
 		apiKey,
 		action: "pull",
 		allow404: true
-	});
+	}).then((res) => res === null ? null : checkedResponse(res, isStudioProject, `the studio project ${project} at ${serverUrl}`));
+}
+/** A pulled workspace, as the wire must actually carry it. */
+function isStudioProject(value) {
+	return isRecord(value) && isRecord(value.files) && Object.values(value.files).every((v) => typeof v === "string") && typeof value.sourceHash === "string";
 }
 /** `PUT /studio/projects/:project/source` — the atomic whole-tree push. */
 function pushStudioSource(serverUrl, apiKey, project, body) {
@@ -231,7 +235,7 @@ function pushStudioSource(serverUrl, apiKey, project, body) {
 		method: "PUT",
 		body,
 		hints: { 409: "The studio has newer changes. Run `aai pull` to fetch them, or `aai push --force` to overwrite." }
-	});
+	}).then((res) => checkedResponse(res, (value) => isRecord(value) && typeof value.sourceHash === "string" && typeof value.created === "boolean", `the studio push route at ${serverUrl}`));
 }
 /** `POST /studio/projects/:project/deploy` — Publish, in the project's sandbox. */
 function publishStudioProject(serverUrl, apiKey, project, opts = {}) {

package/dist/_studio-commands.d.ts

@@ -10,6 +10,15 @@ export declare const list: import("citty").CommandDef<{
     };
 }>;
 export declare const pull: import("citty").CommandDef<{
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
     readonly project: {
         readonly type: "positional";
         readonly description: "Studio project name (see `aai list`)";
@@ -25,6 +34,8 @@ export declare const pull: import("citty").CommandDef<{
         readonly alias: "f";
         readonly description: "Overwrite files in a non-empty directory";
     };
+}>;
+export declare const push: import("citty").CommandDef<{
     readonly server: {
         readonly type: "string";
         readonly alias: "s";
@@ -34,13 +45,13 @@ export declare const pull: import("citty").CommandDef<{
         readonly type: "boolean";
         readonly description: "Output JSON (auto-detected in non-TTY)";
     };
-}>;
-export declare const push: import("citty").CommandDef<{
     readonly force: {
         readonly type: "boolean";
         readonly alias: "f";
         readonly description: "Overwrite studio-side changes instead of failing the fast-forward check";
     };
+}>;
+export declare const publish: import("citty").CommandDef<{
     readonly server: {
         readonly type: "string";
         readonly alias: "s";
@@ -50,22 +61,11 @@ export declare const push: import("citty").CommandDef<{
         readonly type: "boolean";
         readonly description: "Output JSON (auto-detected in non-TTY)";
     };
-}>;
-export declare const publish: import("citty").CommandDef<{
     readonly force: {
         readonly type: "boolean";
         readonly alias: "f";
         readonly description: "Overwrite studio-side changes instead of failing the fast-forward check";
     };
-    readonly server: {
-        readonly type: "string";
-        readonly alias: "s";
-        readonly description: "Platform server URL";
-    };
-    readonly json: {
-        readonly type: "boolean";
-        readonly description: "Output JSON (auto-detected in non-TTY)";
-    };
     readonly skipTypecheck: {
         readonly type: "boolean";
         readonly description: "Skip type checking before publishing";

package/dist/{_templates-0Zr2z6yA.mjs → _templates-CK4oKoeX.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { o as errorMessage$1 } from "./_utils-B8QmtFhK.mjs";
-import { t as getMonorepoRoot } from "./_agent-BTwZJu4P.mjs";
+import { g as writeJson, s as errorMessage$1 } from "./_utils-D5JGcjiW.mjs";
+import { t as getMonorepoRoot } from "./_agent-BzUeqOdj.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { isRecord } from "@alexkroman1/aai/utils";
@@ -106,7 +106,7 @@ async function layerScaffoldManifest(scaffoldDir, targetDir) {
 	const [mine, theirs] = await Promise.all([readJsonFile(target), readJsonFile(path.join(scaffoldDir, "package.json"))]);
 	if (!(mine && theirs)) return;
 	const merged = mergeScaffoldManifest(mine, theirs);
-	if (merged) await fs.writeFile(target, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+	if (merged) await writeJson(target, merged);
 }
 /** Parse a JSON file, or null when it is missing or unparseable. */
 async function readJsonFile(file) {

package/dist/{_typecheck-gate-BXvUNnfs.mjs → _typecheck-gate-U3jcil8L.mjs}

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import { t as CliError } from "./_output-CKkmWs7i.mjs";
-import { n as log } from "./_ui-u7T4YooX.mjs";
+import { t as CliError } from "./_output-DBP9Op_d.mjs";
+import { n as log } from "./_ui-DCt4qZrk.mjs";
 import { typecheckProject } from "./typecheck.mjs";
-//#region _typecheck-gate.ts
+//#region src/_typecheck-gate.ts
 /**
 * The build/deploy typecheck gate: run the project's own `tsc --noEmit`
 * (see `typecheck.ts`) and turn a failure into a structured CliError. The
 * bundlers strip types unchecked, so without this a type-broken agent
 * ships and misbehaves at runtime instead of failing here.
 */
-async function assertTypechecks(cwd) {
+async function assertTypechecks(cwd, opts = {}) {
+	if (opts.skip) return;
 	log.step("Type checking…");
 	const result = await typecheckProject(cwd);
 	if (!result.ok) throw new CliError("typecheck_failed", result.output, "Fix the type errors, or pass --skipTypecheck to build anyway");

package/dist/_typecheck-gate.d.ts

@@ -4,4 +4,6 @@
  * bundlers strip types unchecked, so without this a type-broken agent
  * ships and misbehaves at runtime instead of failing here.
  */
-export declare function assertTypechecks(cwd: string): Promise<void>;
+export declare function assertTypechecks(cwd: string, opts?: {
+    skip?: boolean | undefined;
+}): Promise<void>;

package/dist/{_ui-u7T4YooX.mjs → _ui-DCt4qZrk.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { styleText } from "node:util";
 import * as p from "@clack/prompts";
-//#region _ui.ts
+//#region src/_ui.ts
 const noop = () => {};
 let silenced = false;
 /** Log instance that delegates to clack (human mode) or no-ops (JSON mode). */

package/dist/{_utils-B8QmtFhK.mjs → _utils-D5JGcjiW.mjs}

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { errorDetail, errorMessage, errorMessage as errorMessage$1, omitUndefined } from "@alexkroman1/aai/utils";
 import fs from "node:fs/promises";
-//#region _utils.ts
+//#region src/_utils.ts
 /**
 * The file that marks a directory as an agent project — the single source
 * for the entry filename every command checks or scaffolds.
@@ -115,5 +115,47 @@ async function writeJson(filePath, data, opts = {}) {
 		throw err;
 	}
 }
+/**
+* Code-unit ordering, never `localeCompare`.
+*
+* With no explicit locale `localeCompare` answers to the runtime's ICU default,
+* so the same project would produce a differently-ordered artifact on a
+* different machine — which is why the repo's own generated files sort this way.
+* The reproducibility this protects is real in both callers: the scaffold's
+* `pnpm-workspace.yaml` overrides, and the unrun-spec report.
+*/
+function compareCodeUnits(a, b) {
+	if (a === b) return 0;
+	return a < b ? -1 : 1;
+}
+/**
+* Strip trailing slashes, so a `${base}/...` join cannot produce `//path`.
+*
+* Here rather than beside its first caller because BOTH callers need it and
+* `_agent.ts` — where it lived — is a module `workflow.test.ts` mocks whole, so
+* importing a pure helper from there breaks the mock. `workflow.ts`'s local copy
+* took `/\/$/` — ONE slash — against this `/\/+$/`, so the two disagreed on the
+* only input either was written for.
+*/
+function stripTrailingSlash(url) {
+	return url.replace(/\/+$/, "");
+}
+/**
+* A list as one phrase — the first {@link MAX_NAMED_ITEMS} names, then a count.
+*
+* One definition because a user reads this wording from two different commands:
+* the unrun-spec report (`aai test`) and the "no such project" hint
+* (`aai pull`). Both open-coded the same slice, the same arithmetic and the same
+* `, and N more`, so the cap could drift between two messages one CLI prints.
+*
+* Here rather than in `_ui.ts` because this is a pure formatter and that module
+* is the OUTPUT seam specs mock — `studio.test.ts` replaces it with a bare
+* factory, which drops every export the factory does not list.
+*/
+function formatCappedList(items, max = 10) {
+	const named = items.slice(0, max).join(", ");
+	const rest = items.length - max;
+	return rest > 0 ? `${named}, and ${rest} more` : named;
+}
 //#endregion
-export { errorDetail as a, isEexist as c, resolveCwd as d, validateAgentExport as f, errorCode as i, readJson as l, binFromManifest as n, errorMessage$1 as o, writeJson as p, binFromPackageJson as r, fileExists as s, AGENT_ENTRY as t, readPackageJson as u };
+export { errorCode as a, fileExists as c, readJson as d, readPackageJson as f, writeJson as g, validateAgentExport as h, compareCodeUnits as i, formatCappedList as l, stripTrailingSlash as m, binFromManifest as n, errorDetail as o, resolveCwd as p, binFromPackageJson as r, errorMessage$1 as s, AGENT_ENTRY as t, isEexist as u };

package/dist/_utils.d.ts

@@ -69,3 +69,38 @@ export declare function readJson(filePath: string): Promise<unknown>;
 export declare function writeJson(filePath: string, data: unknown, opts?: {
     mode?: number;
 }): Promise<void>;
+/**
+ * Code-unit ordering, never `localeCompare`.
+ *
+ * With no explicit locale `localeCompare` answers to the runtime's ICU default,
+ * so the same project would produce a differently-ordered artifact on a
+ * different machine — which is why the repo's own generated files sort this way.
+ * The reproducibility this protects is real in both callers: the scaffold's
+ * `pnpm-workspace.yaml` overrides, and the unrun-spec report.
+ */
+export declare function compareCodeUnits(a: string, b: string): number;
+/**
+ * Strip trailing slashes, so a `${base}/...` join cannot produce `//path`.
+ *
+ * Here rather than beside its first caller because BOTH callers need it and
+ * `_agent.ts` — where it lived — is a module `workflow.test.ts` mocks whole, so
+ * importing a pure helper from there breaks the mock. `workflow.ts`'s local copy
+ * took `/\/$/` — ONE slash — against this `/\/+$/`, so the two disagreed on the
+ * only input either was written for.
+ */
+export declare function stripTrailingSlash(url: string): string;
+/** How many names a capped list prints before it starts counting. */
+export declare const MAX_NAMED_ITEMS = 10;
+/**
+ * A list as one phrase — the first {@link MAX_NAMED_ITEMS} names, then a count.
+ *
+ * One definition because a user reads this wording from two different commands:
+ * the unrun-spec report (`aai test`) and the "no such project" hint
+ * (`aai pull`). Both open-coded the same slice, the same arithmetic and the same
+ * `, and N more`, so the cap could drift between two messages one CLI prints.
+ *
+ * Here rather than in `_ui.ts` because this is a pure formatter and that module
+ * is the OUTPUT seam specs mock — `studio.test.ts` replaces it with a bare
+ * factory, which drops every export the factory does not list.
+ */
+export declare function formatCappedList(items: readonly string[], max?: number): string;

package/dist/{_vite-env-D9Qj6KPX.mjs → _vite-env-kejF0p2L.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-//#region _vite-env.ts
+//#region src/_vite-env.ts
 /**
 * Packages resolved from the project root rather than from whichever
 * `node_modules` happens to sit above the importing file.