@alexkroman1/aai-cli 10.0.0 → 11.0.0

package/dist/{_bundler-B31MqYaD.mjs → _bundler-C31rlcYz.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { f as validateAgentExport } from "./_utils-B8QmtFhK.mjs";
-import { t as buildClient } from "./client-bundler-CWnG42cU.mjs";
+import { t as buildClient } from "./client-bundler-j5c46x0G.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/{_dev-server-Bo5dSBzQ.mjs → _dev-server-DWvkNoIS.mjs}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { i as outputSilenced, r as notify } from "./_ui-u7T4YooX.mjs";
 import { i as errorCode, o as errorMessage$1 } from "./_utils-B8QmtFhK.mjs";
-import { n as fallbackHtmlPlugin } from "./client-bundler-CWnG42cU.mjs";
-import { t as DEDUPED_PEERS } from "./_vite-env-BNveawd1.mjs";
+import { n as fallbackHtmlPlugin } from "./client-bundler-j5c46x0G.mjs";
+import { t as DEDUPED_PEERS } from "./_vite-env-D9Qj6KPX.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import { typecheckProject } from "./typecheck.mjs";
 import { n as ensureApiKey } from "./_config-CmJOFsAP.mjs";
-import { n as createWorkerEvaluator } from "./_bundler-B31MqYaD.mjs";
+import { n as createWorkerEvaluator } from "./_bundler-C31rlcYz.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
 import { existsSync, statSync } from "node:fs";
 import path from "node:path";

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

@@ -69,8 +69,10 @@ async function withPreservedNodeEnv(fn, env = process.env) {
 		return await fn();
 	} finally {
 		activeBuilds--;
-		if (activeBuilds === 0) if (savedNodeEnv === void 0) delete env.NODE_ENV;
-		else env.NODE_ENV = savedNodeEnv;
+		if (activeBuilds === 0) {
+			if (savedNodeEnv === void 0) delete env.NODE_ENV;
+			else env.NODE_ENV = savedNodeEnv;
+		}
 	}
 }
 //#endregion

package/dist/_workflow-determinism-f9J-5Zlj.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+//#region _workflow-determinism.ts
+/**
+* A COMPUTED step identity in the project's own `workflows/`.
+*
+* `guard-invariants` rule 32 is this same check over the repo's own shipped
+* template bodies; this is it pointed at a USER's project, at `aai build` and
+* `aai deploy`. The two exist together because the gate holds the examples and
+* held nothing written from them.
+*
+* It is also the half of rule 30 ("no clock, random number, uuid or network
+* read at body level") that ports at all — and the half the type system
+* provably leaves open.
+*
+* ## What it catches, and why the type does not
+*
+* `ctx.step`, `ctx.sleep` and `ctx.waitFor` all constrain their identity with
+* `Literal<Name>` (`string extends Name ? never : Name`), which rejects a name
+* that has widened to `string`. **A template literal passes it**: the type of
+* `` `charge-${coin}` `` is a template-literal type, not `string`, so this
+* compiles — and it is checked rather than claimed, `check:doc-examples`
+* compiling every fence in this repo's shipped docs:
+*
+* ```ts
+* import type { WorkflowCtx } 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`.
+*   await ctx.step(`charge-${coin}`, charge);
+* }
+* ```
+*
+* And it is exactly
+* the shape of the engine's own measured defect: a body-level `Math.random()`
+* feeding a step name executed the side effect twice in **7 of 10 runs, with
+* all 10 reporting `completed`** (`aai-runtime/workflow-replay-divergence.ts`).
+* Substitute "charge the customer" for the side effect.
+*
+* A computed identity has no legitimate use in this engine, which is what makes
+* the check cheap AND precise. Identity is `(name, occurrence)`: a fan-out
+* reuses ONE name and the per-name occurrence counter distinguishes the calls,
+* so every step in all fourteen shipped templates — the seven-way transcription
+* fan-out included — is a plain string literal. The scan finds zero occurrences
+* across them.
+*
+* ## Why rule 30's OTHER half is deliberately not ported
+*
+* That half scans for the reads themselves, anywhere in a `workflows/` file,
+* and it pays for the breadth with seven baselined occurrences in this repo.
+* Measured before writing this: a faithful port reports **all seven and nothing
+* else** — and all seven are correct code. Each is a read inside a step-called
+* helper (`timed`, `pollTranscript`, `file`), which `link-digest`'s own comment
+* explains: "the `ctx.step` callback boundary is not decidable from a line …
+* Anything at BODY level is the bug, not an exception."
+*
+* A user's project has no baseline to carry, so that port would be a 100%
+* false-positive rate on the only corpus anyone can measure — and a checker
+* that is always wrong is one an author learns to scroll past, which costs the
+* precise finding below as well as itself. Deciding that boundary needs a real
+* parse; the repo does that with `oxc-parser`
+* (`scripts/_test-assertions-parse.mjs`, whose doc argues it against the ~140
+* lines of hand-written lexer it replaced), and a native parser cannot join a
+* published CLI's runtime dependencies — a new one fails the artifact-size
+* budget on its own, regardless of bytes. So the reads half stays in the repo
+* gate, where the baseline mechanism it needs already exists.
+*
+* ## It WARNS
+*
+* `assertTypechecks` throws and `aai build` stops. This does not, because one
+* shape is legitimate: a name interpolating a CONSTANT (`` `${PREFIX}-fetch` ``
+* over a `const` string) is the same on every walk. It is rare enough not to
+* shape the message and real enough not to fail a build over.
+*
+* Same posture and the same call site as `agentConfigWarnings`, whose comment
+* in `build.ts` states it: "Legal, and worth saying".
+*
+* @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
+* accepted; a bare identifier is already the type system's job (`Literal<Name>`
+* refuses one that widened to `string`, and one that did not is a `const`
+* literal and deterministic); a template literal is what neither of them sees.
+*
+* 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.
+*/
+const identityPattern = () => new RegExp(`\\.(${IDENTITY_METHODS.join("|")})\\(\``, "g");
+/** Whether a template literal actually INTERPOLATES, or is merely quoted oddly. */
+const INTERPOLATES = /\$\{/;
+/**
+* Whether this line is only a comment.
+*
+* A method NAMED IN PROSE is prose: this module's own doc shows the banned
+* shape, and rule 30 carries the same skip for the same reason. Block-comment
+* continuations (`*`) count, which is what covers a paragraph rather than only
+* its first line.
+*/
+function isCommentOnly(line) {
+	const trimmed = line.trimStart();
+	return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
+}
+/**
+* Every computed identity in one source file.
+*
+* The interpolation is looked for in the REST of the line rather than inside a
+* balanced template: a template-literal name long enough to wrap is not a shape
+* this needs to resolve, and reporting one whose `${` sits on the next line is
+* the safer direction for a warning.
+*/
+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())) {
+			const method = match[1];
+			if (method === void 0) continue;
+			if (!INTERPOLATES.test(line.slice((match.index ?? 0) + match[0].length))) continue;
+			findings.push({
+				file,
+				line: n + 1,
+				method,
+				text: line.trim()
+			});
+		}
+	}
+	return findings;
+}
+/** Every workflow body under `cwd`, or nothing when the project declares none. */
+async function workflowFiles(cwd) {
+	const dir = path.join(cwd, "workflows");
+	let entries;
+	try {
+		entries = await readdir(dir);
+	} catch {
+		return [];
+	}
+	return entries.filter((name) => name.endsWith(".ts")).filter((name) => !(name.endsWith(".test.ts") || name.endsWith(".test-d.ts"))).map((name) => path.join("workflows", name));
+}
+/**
+* Scan the project's workflow bodies.
+*
+* FLAT, matching both the shape every template uses and rule 30's own pathspec
+* (`templates/*` + `/workflows/*.ts`). A nested file is missed, which is the
+* same gap the rule has; widening both together is the change to make, rather
+* than widening one and having the two disagree about their own corpus.
+*
+* A file that will not READ is skipped rather than failing the build: this is a
+* 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;
+		try {
+			source = await readFile(path.join(cwd, rel), "utf-8");
+		} catch {
+			continue;
+		}
+		findings.push(...findComputedIdentities(source, rel));
+	}
+	return findings;
+}
+/**
+* The remedy, once, however many findings there are.
+*
+* Repeating it per finding is how a warning becomes a wall an author scrolls
+* past, and the fix is the same for all three methods. It names the OCCURRENCE
+* counter, because "use a literal" alone reads as a restriction on fan-outs —
+* the one case an author will think they need this for, and the case the
+* counter already handles.
+*/
+const REMEDY = "A workflow identity is a journal KEY, and a body is replayed — so a computed one mints a key no earlier walk reached, and the engine either re-executes the step or refuses the run. Measured on a one-line body: 7 of 10 runs ran the side effect twice, all 10 reporting completed. Use a plain string literal. A fan-out does not need a unique name: identity is (name, occurrence), so N calls under one name are N distinct rows — ctx.step(\"transcribeSegment\", …) inside the loop is right.";
+/**
+* One warning line per finding, plus the remedy — or nothing at all.
+*
+* Shaped as strings rather than printed here for the reason every reporter in
+* this package takes an injected one: `build` and `deploy` notify, and a spec
+* reads what an author would have seen without capturing stdout.
+*/
+function determinismWarnings(findings) {
+	if (findings.length === 0) return [];
+	return [...findings.map((found) => `${found.file}:${found.line} computes a ctx.${found.method} identity: ${found.text}`), REMEDY];
+}
+//#endregion
+export { scanWorkflowDeterminism as n, determinismWarnings as t };

package/dist/_workflow-determinism.d.ts

@@ -0,0 +1,118 @@
+/**
+ * A COMPUTED step identity in the project's own `workflows/`.
+ *
+ * `guard-invariants` rule 32 is this same check over the repo's own shipped
+ * template bodies; this is it pointed at a USER's project, at `aai build` and
+ * `aai deploy`. The two exist together because the gate holds the examples and
+ * held nothing written from them.
+ *
+ * It is also the half of rule 30 ("no clock, random number, uuid or network
+ * read at body level") that ports at all — and the half the type system
+ * provably leaves open.
+ *
+ * ## What it catches, and why the type does not
+ *
+ * `ctx.step`, `ctx.sleep` and `ctx.waitFor` all constrain their identity with
+ * `Literal<Name>` (`string extends Name ? never : Name`), which rejects a name
+ * that has widened to `string`. **A template literal passes it**: the type of
+ * `` `charge-${coin}` `` is a template-literal type, not `string`, so this
+ * compiles — and it is checked rather than claimed, `check:doc-examples`
+ * compiling every fence in this repo's shipped docs:
+ *
+ * ```ts
+ * import type { WorkflowCtx } 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`.
+ *   await ctx.step(`charge-${coin}`, charge);
+ * }
+ * ```
+ *
+ * And it is exactly
+ * the shape of the engine's own measured defect: a body-level `Math.random()`
+ * feeding a step name executed the side effect twice in **7 of 10 runs, with
+ * all 10 reporting `completed`** (`aai-runtime/workflow-replay-divergence.ts`).
+ * Substitute "charge the customer" for the side effect.
+ *
+ * A computed identity has no legitimate use in this engine, which is what makes
+ * the check cheap AND precise. Identity is `(name, occurrence)`: a fan-out
+ * reuses ONE name and the per-name occurrence counter distinguishes the calls,
+ * so every step in all fourteen shipped templates — the seven-way transcription
+ * fan-out included — is a plain string literal. The scan finds zero occurrences
+ * across them.
+ *
+ * ## Why rule 30's OTHER half is deliberately not ported
+ *
+ * That half scans for the reads themselves, anywhere in a `workflows/` file,
+ * and it pays for the breadth with seven baselined occurrences in this repo.
+ * Measured before writing this: a faithful port reports **all seven and nothing
+ * else** — and all seven are correct code. Each is a read inside a step-called
+ * helper (`timed`, `pollTranscript`, `file`), which `link-digest`'s own comment
+ * explains: "the `ctx.step` callback boundary is not decidable from a line …
+ * Anything at BODY level is the bug, not an exception."
+ *
+ * A user's project has no baseline to carry, so that port would be a 100%
+ * false-positive rate on the only corpus anyone can measure — and a checker
+ * that is always wrong is one an author learns to scroll past, which costs the
+ * precise finding below as well as itself. Deciding that boundary needs a real
+ * parse; the repo does that with `oxc-parser`
+ * (`scripts/_test-assertions-parse.mjs`, whose doc argues it against the ~140
+ * lines of hand-written lexer it replaced), and a native parser cannot join a
+ * published CLI's runtime dependencies — a new one fails the artifact-size
+ * budget on its own, regardless of bytes. So the reads half stays in the repo
+ * gate, where the baseline mechanism it needs already exists.
+ *
+ * ## It WARNS
+ *
+ * `assertTypechecks` throws and `aai build` stops. This does not, because one
+ * shape is legitimate: a name interpolating a CONSTANT (`` `${PREFIX}-fetch` ``
+ * over a `const` string) is the same on every walk. It is rare enough not to
+ * shape the message and real enough not to fail a build over.
+ *
+ * Same posture and the same call site as `agentConfigWarnings`, whose comment
+ * in `build.ts` states it: "Legal, and worth saying".
+ *
+ * @module
+ */
+/** One computed identity the scan found. */
+export type DeterminismFinding = {
+    /** Relative to the project root, so a message is copy-pasteable. */
+    file: string;
+    /** 1-indexed, so `file:line` opens in an editor. */
+    line: number;
+    /** `step`, `sleep` or `waitFor` — which identity this is. */
+    method: string;
+    /** The source line, trimmed — what makes the warning actionable unopened. */
+    text: string;
+};
+/**
+ * Every computed identity in one source file.
+ *
+ * The interpolation is looked for in the REST of the line rather than inside a
+ * balanced template: a template-literal name long enough to wrap is not a shape
+ * this needs to resolve, and reporting one whose `${` sits on the next line is
+ * the safer direction for a warning.
+ */
+export declare function findComputedIdentities(source: string, file: string): DeterminismFinding[];
+/**
+ * Scan the project's workflow bodies.
+ *
+ * FLAT, matching both the shape every template uses and rule 30's own pathspec
+ * (`templates/*` + `/workflows/*.ts`). A nested file is missed, which is the
+ * same gap the rule has; widening both together is the change to make, rather
+ * than widening one and having the two disagree about their own corpus.
+ *
+ * A file that will not READ is skipped rather than failing the build: this is a
+ * warning pass beside a typecheck that has already run on the same tree.
+ */
+export declare function scanWorkflowDeterminism(cwd: string): Promise<DeterminismFinding[]>;
+/**
+ * One warning line per finding, plus the remedy — or nothing at all.
+ *
+ * Shaped as strings rather than printed here for the reason every reporter in
+ * this package takes an injected one: `build` and `deploy` notify, and a spec
+ * reads what an author would have seen without capturing stdout.
+ */
+export declare function determinismWarnings(findings: readonly DeterminismFinding[]): string[];

package/dist/{build-DKC2e9o_.mjs → build-BLlLOrng.mjs}

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { a as ok, t as CliError } from "./_output-CKkmWs7i.mjs";
 import { n as log, r as notify } from "./_ui-u7T4YooX.mjs";
-import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-B31MqYaD.mjs";
+import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-C31rlcYz.mjs";
 import { assertTypechecks } from "./_typecheck-gate-BXvUNnfs.mjs";
-import { classifyVitestError, runVitest } from "./test-CvwgeVSQ.mjs";
+import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-f9J-5Zlj.mjs";
+import { classifyVitestError, runVitest } from "./test-CiLab-AA.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
@@ -50,6 +51,7 @@ async function executeBuild(opts) {
 	const bundle = await buildAgentBundle(cwd, { minify: true });
 	const agentDef = await evalWorkerBundle(bundle.worker);
 	for (const warning of agentConfigWarnings(agentDef)) notify("warn", warning);
+	for (const warning of determinismWarnings(await scanWorkflowDeterminism(cwd))) notify("warn", warning);
 	const worker = path.join(cwd, WORKER_ARTIFACT_REL);
 	await fs.mkdir(path.dirname(worker), { recursive: true });
 	await fs.writeFile(worker, bundle.worker, "utf-8");