@alexkroman1/aai-cli 13.3.0 → 14.0.0

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-DTi3EdXQ.mjs → _studio-DnR_BqFp.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as CliError } from "./_output-DbJt9gsl.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";
@@ -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-V4l5sZJy.mjs → _templates-CK4oKoeX.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { o as errorMessage$1 } from "./_utils-Dhd058D9.mjs";
-import { t as getMonorepoRoot } from "./_agent-Clbq3a4h.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-sV4N5F93.mjs → _typecheck-gate-U3jcil8L.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as CliError } from "./_output-DbJt9gsl.mjs";
+import { t as CliError } from "./_output-DBP9Op_d.mjs";
 import { n as log } from "./_ui-DCt4qZrk.mjs";
 import { typecheckProject } from "./typecheck.mjs";
 //#region src/_typecheck-gate.ts
@@ -9,7 +9,8 @@ import { typecheckProject } from "./typecheck.mjs";
 * 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/{_utils-Dhd058D9.mjs → _utils-D5JGcjiW.mjs}

@@ -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/{_workflow-determinism-C9l8uC2R.mjs → _workflow-determinism-CvpqMpdh.mjs}

@@ -24,12 +24,12 @@ import { readFile, readdir } from "node:fs/promises";
 * compiling every fence in this repo's shipped docs:
 *
 * ```ts
-* import type { WorkflowCtx } from "@alexkroman1/aai";
+* import type { WorkflowContext } from "@alexkroman1/aai";
 *
 * declare const charge: () => Promise<string>;
 *
-* export async function body(ctx: WorkflowCtx, coin: string): Promise<void> {
-*   // No error. The banned shape, against the real `WorkflowCtx`.
+* export async function body(ctx: WorkflowContext, coin: string): Promise<void> {
+*   // No error. The banned shape, against the real `WorkflowContext`.
 *   await ctx.step(`charge-${coin}`, charge);
 * }
 * ```
@@ -81,19 +81,6 @@ import { readFile, readdir } from "node:fs/promises";
 * @module
 */
 /**
-* The three `ctx` methods whose first argument is a journal identity.
-*
-* All three key a journal row by it — `name#occurrence` for a step,
-* `sleep!<label>#<n>` and `hook!<token>#<n>` for the waits — so a computed one
-* mints a row no earlier walk reached in exactly the same way. Kept as a list
-* so the message can name the method that was called.
-*/
-const IDENTITY_METHODS = [
-	"step",
-	"sleep",
-	"waitFor"
-];
-/**
 * A `ctx.<method>(` immediately followed by a BACKTICK.
 *
 * The whole check, and its narrowness is the point. A quoted literal is
@@ -104,8 +91,17 @@ const IDENTITY_METHODS = [
 * The receiver is not pinned to `ctx` — a body may destructure or rename it —
 * and a `.step(` on anything else taking a template-literal first argument is
 * not a shape worth excluding.
+*
+* Shared rather than built per call, which is safe ONLY because the single
+* reader is `matchAll`: that method species-constructs its own clone and never
+* advances this object's `lastIndex`. A `.exec` or `.test` added against a `/g`
+* regex would carry state between lines — build a fresh one there.
 */
-const identityPattern = () => new RegExp(`\\.(${IDENTITY_METHODS.join("|")})\\(\``, "g");
+const IDENTITY_PATTERN = new RegExp(`\\.(${[
+	"step",
+	"sleep",
+	"waitFor"
+].join("|")})\\(\``, "g");
 /** Whether a template literal actually INTERPOLATES, or is merely quoted oddly. */
 const INTERPOLATES = /\$\{/;
 /**
@@ -132,7 +128,7 @@ function findComputedIdentities(source, file) {
 	const findings = [];
 	for (const [n, line] of source.split("\n").entries()) {
 		if (isCommentOnly(line)) continue;
-		for (const match of line.matchAll(identityPattern())) {
+		for (const match of line.matchAll(IDENTITY_PATTERN)) {
 			const method = match[1];
 			if (method === void 0) continue;
 			if (!INTERPOLATES.test(line.slice((match.index ?? 0) + match[0].length))) continue;
@@ -169,17 +165,13 @@ async function workflowFiles(cwd) {
 * warning pass beside a typecheck that has already run on the same tree.
 */
 async function scanWorkflowDeterminism(cwd) {
-	const findings = [];
-	for (const rel of await workflowFiles(cwd)) {
-		let source;
+	return (await Promise.all((await workflowFiles(cwd)).map(async (rel) => {
 		try {
-			source = await readFile(path.join(cwd, rel), "utf-8");
+			return findComputedIdentities(await readFile(path.join(cwd, rel), "utf-8"), rel);
 		} catch {
-			continue;
+			return [];
 		}
-		findings.push(...findComputedIdentities(source, rel));
-	}
-	return findings;
+	}))).flat();
 }
 /**
 * The remedy, once, however many findings there are.

package/dist/_workflow-determinism.d.ts

@@ -20,12 +20,12 @@
  * compiling every fence in this repo's shipped docs:
  *
  * ```ts
- * import type { WorkflowCtx } from "@alexkroman1/aai";
+ * import type { WorkflowContext } from "@alexkroman1/aai";
  *
  * declare const charge: () => Promise<string>;
  *
- * export async function body(ctx: WorkflowCtx, coin: string): Promise<void> {
- *   // No error. The banned shape, against the real `WorkflowCtx`.
+ * export async function body(ctx: WorkflowContext, coin: string): Promise<void> {
+ *   // No error. The banned shape, against the real `WorkflowContext`.
  *   await ctx.step(`charge-${coin}`, charge);
  * }
  * ```

package/dist/{build-CWyFGe-W.mjs → build-Mxk8gWvX.mjs}

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-import { a as ok, t as CliError } from "./_output-DbJt9gsl.mjs";
+import { a as ok, t as CliError } from "./_output-DBP9Op_d.mjs";
 import { n as log, r as notify } from "./_ui-DCt4qZrk.mjs";
-import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-DEkjO1d8.mjs";
-import { assertTypechecks } from "./_typecheck-gate-sV4N5F93.mjs";
-import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-C9l8uC2R.mjs";
-import { TEST_FILES, classifyVitestError, runVitest } from "./test-guenJUxi.mjs";
+import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-DolUCMxu.mjs";
+import { assertTypechecks } from "./_typecheck-gate-U3jcil8L.mjs";
+import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-CvpqMpdh.mjs";
+import { TEST_FILES, classifyVitestError, runVitest } from "./test-D032V2cA.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
+import { DEFAULT_SYSTEM_PROMPT } from "@alexkroman1/aai";
 //#region src/build.ts
 /**
 * `aai build` — bundle the agent without deploying, behind the same gates
@@ -32,6 +33,41 @@ import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
 */
 const WORKER_ARTIFACT_REL = path.join(".aai", "worker.mjs");
 /**
+* The prose slot, named by convention. Mirrors `worker-bundler.ts`'s constant of
+* the same name — the two cannot share one without an import cycle
+* (`build.ts` → `_bundler.ts` → `worker-bundler.ts`), so `_build.test.ts` pins
+* the pair end to end instead: a build whose prompt really came from the file
+* has to report the file.
+*/
+const SYSTEM_PROMPT_FILE = "system-prompt.md";
+/** What {@link systemPromptSource} reports when nothing declared a prompt. */
+const FRAMEWORK_DEFAULT_PROMPT_SOURCE = "the framework default (DEFAULT_SYSTEM_PROMPT)";
+/**
+* Which of the three possible authors of this agent's system prompt actually
+* wrote the one in the bundle.
+*
+* `aai build` reported `name` and `workerBytes` and nothing about the prompt,
+* and the prompt is the one field that can change COMPLETELY without any
+* config changing: deleting `system-prompt.md` swaps in
+* `DEFAULT_SYSTEM_PROMPT` — a total personality change — with exit 0 and no
+* line anywhere. `withSystemPrompt` refuses the case where a file exists and
+* nothing reads it; it cannot refuse a file that is simply GONE, because that
+* is what an agent with no file legitimately looks like. So this is a report
+* rather than a check.
+*
+* Decided by comparing VALUES against the built agent's resolved prompt, which
+* is the same method `withSystemPrompt` uses and for the same reason — the
+* alternative asks the bundler's module graph a question, and the author may
+* have imported the file and composed it, which is neither "the file" nor
+* "agent.ts" alone.
+*/
+async function systemPromptSource(cwd, resolved) {
+	if (resolved === DEFAULT_SYSTEM_PROMPT) return FRAMEWORK_DEFAULT_PROMPT_SOURCE;
+	const trimmed = (await fs.readFile(path.join(cwd, SYSTEM_PROMPT_FILE), "utf-8").catch(() => void 0))?.trim();
+	if (trimmed === void 0 || trimmed === "" || !resolved.includes(trimmed)) return "agent.ts";
+	return resolved.trim() === trimmed ? SYSTEM_PROMPT_FILE : `agent.ts (composing ${SYSTEM_PROMPT_FILE})`;
+}
+/**
 * Map a {@link runVitest} failure to a CliError — distinguishing a real test
 * failure (test_failed) from the runner not spawning (spawn_failed) instead
 * of a generic command_failed.
@@ -50,7 +86,7 @@ async function executeBuild(opts) {
 	} catch (err) {
 		throw testGateError(err);
 	}
-	if (!opts.skipTypecheck) await assertTypechecks(cwd);
+	await assertTypechecks(cwd, { skip: opts.skipTypecheck });
 	const bundle = await buildAgentBundle(cwd, { minify: true });
 	const agentDef = await evalWorkerBundle(bundle.worker);
 	for (const warning of agentConfigWarnings(agentDef)) notify("warn", warning);
@@ -58,11 +94,14 @@ async function executeBuild(opts) {
 	const worker = path.join(cwd, WORKER_ARTIFACT_REL);
 	await fs.mkdir(path.dirname(worker), { recursive: true });
 	await fs.writeFile(worker, bundle.worker, "utf-8");
+	const systemPrompt = await systemPromptSource(cwd, agentDef.systemPrompt);
+	log.info(`System prompt: ${systemPrompt}`);
 	log.success("Build complete");
 	return ok({
 		name: agentDef.name,
 		workerBytes: bundle.worker.length,
-		worker
+		worker,
+		systemPrompt
 	});
 }
 //#endregion

package/dist/build.d.ts

@@ -26,6 +26,11 @@ type BuildData = {
     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;
 };
 export declare function executeBuild(opts: {
     cwd: string;

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>;