@aid-framework/cli 0.1.62 → 0.1.64

package/dist/commands/cost.d.ts

@@ -1,5 +1,5 @@
 /**
- * `aid cost` — a cost and latency report read from the local trace sink.
+ * `aid cost` — a cost and latency report read from the local trace sink.
  *
  * The numbers already exist. `runtimes/{python,typescript}` write one JSONL span per line
  * whenever `AID_TRACE_DIR` is set, and those spans carry the GenAI token attributes and

package/dist/commands/cost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/commands/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAyDD,wBAAgB,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,cAAc,CA4I9E"}
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/commands/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMnD,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AA0CD,wBAAgB,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,GAAG,cAAc,CAuF9E"}

package/dist/commands/cost.js

@@ -1,5 +1,5 @@
 /**
- * `aid cost` — a cost and latency report read from the local trace sink.
+ * `aid cost` — a cost and latency report read from the local trace sink.
  *
  * The numbers already exist. `runtimes/{python,typescript}` write one JSONL span per line
  * whenever `AID_TRACE_DIR` is set, and those spans carry the GenAI token attributes and
@@ -18,28 +18,11 @@
  * - `0` otherwise, including for an empty directory: a report of zero spans is true, and
  *   the warning on stderr says why it is zero.
  */
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { CLI_DIAGNOSTIC_CODES, cliError, cliWarning } from '../diagnostics.js';
 import { EXIT_FAILURE, EXIT_OK, EXIT_USAGE } from '../exit.js';
-import { outcome } from '../output.js';
-import { parseSince, parseTraceLines, summariseSpans } from '../trace.js';
-/** The variable the runtimes read. Named here, not imported, because it is a runtime knob. */
-const TRACE_DIR_ENV = 'AID_TRACE_DIR';
-function displayPath(cwd, absolute) {
-    const path = relative(cwd, absolute);
-    if (path === '')
-        return '.';
-    if (path.startsWith('..') || isAbsolute(path))
-        return absolute;
-    return path.split(sep).join('/');
-}
-function group(value) {
-    return String(Math.trunc(value)).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
-}
-function usd(value) {
-    return `$${value.toFixed(6)}`;
-}
+import { group, outcome, usd } from '../output.js';
+import { parseSince, summariseSpans } from '../trace.js';
+import { confirmTraceDir, locateTraceDir, readTraceDir, TRACE_DIR_ENV } from '../trace-dir.js';
 function modelLines(models) {
     if (models.length === 0)
         return [];
@@ -52,7 +35,7 @@ function modelLines(models) {
             `${String(model.calls).padStart(4)} calls`,
             `${group(model.inputTokens).padStart(9)} in`,
             `${group(model.outputTokens).padStart(9)} out`,
-            usd(model.costUsd).padStart(14),
+            usd(model.costUsd, 6).padStart(14),
             unpriced,
         ].join('  '));
     }
@@ -64,8 +47,8 @@ function reportLines(summary, dir, since) {
         `dir: ${dir}`,
         `spans: ${group(summary.spans)} in ${group(summary.traces)} trace(s)${scope}`,
         summary.unpricedSpans === 0
-            ? `cost: ${usd(summary.costUsd)}`
-            : `cost: ${usd(summary.costUsd)} (${summary.unpricedSpans} unpriced span(s) not included)`,
+            ? `cost: ${usd(summary.costUsd, 6)}`
+            : `cost: ${usd(summary.costUsd, 6)} (${summary.unpricedSpans} unpriced span(s) not included)`,
         `tokens: ${group(summary.inputTokens)} input, ${group(summary.outputTokens)} output`,
     ];
     if (summary.latency !== undefined) {
@@ -78,21 +61,10 @@ function reportLines(summary, dir, since) {
 }
 export function cost(context, options) {
     const command = 'cost';
-    const configured = options.dir ?? context.env[TRACE_DIR_ENV]?.trim();
-    if (configured === undefined || configured === '') {
-        return outcome({
-            command,
-            exitCode: EXIT_USAGE,
-            diagnostics: [
-                cliError({
-                    code: CLI_DIAGNOSTIC_CODES.traceDirMissing,
-                    message: `no trace directory: \`aid cost\` needs one to read.`,
-                    hint: `Pass it as \`aid ${command} <dir>\`, or set ${TRACE_DIR_ENV} to the directory the runtime writes to.`,
-                }),
-            ],
-            text: `aid: no trace directory. Pass one, or set ${TRACE_DIR_ENV}.\n`,
-        });
-    }
+    const located = locateTraceDir(context, options.dir, command);
+    if (located.kind === 'refused')
+        return located.outcome;
+    const shown = located.shown;
     let since;
     if (options.since !== undefined) {
         since = parseSince(options.since);
@@ -111,51 +83,11 @@ export function cost(context, options) {
             });
         }
     }
-    const absolute = resolve(context.cwd, configured);
-    const shown = displayPath(context.cwd, absolute);
+    const confirmed = confirmTraceDir(located, command);
+    if (confirmed.kind === 'refused')
+        return confirmed.outcome;
     const diagnostics = [];
-    let isDirectory = false;
-    try {
-        isDirectory = statSync(absolute).isDirectory();
-    }
-    catch {
-        isDirectory = false;
-    }
-    if (!isDirectory) {
-        return outcome({
-            command,
-            exitCode: EXIT_USAGE,
-            diagnostics: [
-                cliError({
-                    code: CLI_DIAGNOSTIC_CODES.traceDirNotFound,
-                    message: `"${shown}" is not a directory.`,
-                    hint: `Point \`aid ${command}\` at the directory ${TRACE_DIR_ENV} names, or unset it to be told which is missing.`,
-                }),
-            ],
-            text: `aid: "${shown}" is not a directory.\n`,
-        });
-    }
-    const names = readdirSync(absolute, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && entry.name.endsWith('.jsonl'))
-        .map((entry) => entry.name)
-        .sort();
-    let skipped = 0;
-    const all = [];
-    let unreadable = 0;
-    for (const name of names) {
-        let text;
-        try {
-            text = readFileSync(join(absolute, name), 'utf8');
-        }
-        catch {
-            // Counted, not thrown: one unreadable file should not hide the spans in the rest.
-            unreadable += 1;
-            continue;
-        }
-        const parsed = parseTraceLines(text);
-        all.push(...parsed.spans);
-        skipped += parsed.skipped;
-    }
+    const { files: names, spans: all, skipped, unreadable } = readTraceDir(confirmed.absolute);
     if (unreadable > 0) {
         diagnostics.push(cliError({
             code: CLI_DIAGNOSTIC_CODES.traceUnreadable,

package/dist/commands/cost.js.map

@@ -1 +1 @@
-{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../src/commands/cost.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../src/commands/cost.ts"],"names":[],"mappings":"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"}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `aid migrate` — emit the SQL the declared stores need, for an operator to apply once.
+ *
+ * Both runtimes create their own schema on first connect (`CREATE ... IF NOT EXISTS`), so
+ * this command is not how the application works; it is how the application is allowed to
+ * *stop* creating schema. A production role that only needs `INSERT`/`SELECT` should not
+ * hold `CREATE TABLE` because the first request happened to arrive before the table did.
+ * Emitting the same schema as a reviewable file moves that one-time act to the operator
+ * and leaves the application's `IF NOT EXISTS` as a no-op.
+ *
+ * Four decisions worth stating:
+ *
+ * - **Bootstrap only.** Every statement is idempotent, so re-applying is harmless. The file
+ *   creates and never alters: once `aid_chunks` exists, `IF NOT EXISTS` skips the table,
+ *   so an edited vector dimension would report success while the column kept its old type.
+ *   A changed dimension is a *new* migration, and the header says so where the person
+ *   editing the file will read it.
+ * - **No target flag.** The SQL is identical for both runtimes -- they declare the same
+ *   table, the same columns and the same operators -- so a `--target` option would imply a
+ *   per-target difference that does not exist.
+ * - **One file, whatever the store count.** The runtimes use a single shared `aid_chunks`
+ *   table and do not key rows by store id, so a second `pgvector` store is not a second
+ *   table. Emitting one file per store would print the same DDL twice and invite a reader
+ *   to believe the stores are isolated.
+ * - **The file is identified by its own header.** `migrations/` is a directory people keep
+ *   their own migrations in. `aid migrate` only rewrites or deletes a file that carries the
+ *   header it writes, so a hand-written `aid-schema.sql` is refused rather than replaced.
+ *
+ * The table DDL is restated here because neither runtime publishes it as a value the CLI
+ * can import -- Python holds it in a module constant, TypeScript in another. That is a
+ * third copy, so `migrate.test.ts` reads both runtimes' sources and fails when either one
+ * stops agreeing with {@link AID_CHUNKS_TABLE}: the duplication is guarded rather than
+ * hoped for.
+ */
+import type { CliContext } from '../context.js';
+import type { CommandOutcome } from '../output.js';
+export interface MigrateOptions {
+    readonly spec: string | undefined;
+    /** Directory for the migration file, repo-relative; defaults to `migrations`. */
+    readonly out: string | undefined;
+    /** Fail when the committed file does not match the spec; writes nothing. */
+    readonly check: boolean;
+    readonly dryRun: boolean;
+}
+/** The header that marks a file as this command's to rewrite. */
+export declare const MIGRATION_MARKER = "-- Generated by aid migrate. Do not edit.";
+/**
+ * The table both runtimes declare, verbatim apart from the embedding type.
+ *
+ * `{embedding}` is replaced with `vector(N)` when the spec pins one dimension and with
+ * `vector` when it does not. The column list, its types and its `NOT NULL`s are what the
+ * runtimes' insert and select statements assume; a driver that added or renamed a column
+ * would fail at runtime, not here.
+ */
+export declare const AID_CHUNKS_TABLE = "CREATE TABLE IF NOT EXISTS aid_chunks (\n    chunk_id text PRIMARY KEY,\n    doc_id text NOT NULL,\n    uri text NOT NULL,\n    chunk_index integer NOT NULL,\n    start_offset integer NOT NULL,\n    end_offset integer NOT NULL,\n    body text NOT NULL,\n    metadata jsonb NOT NULL DEFAULT '{}'::jsonb,\n    embedding {embedding} NOT NULL\n);";
+export declare function migrate(context: CliContext, options: MigrateOptions): CommandOutcome;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/commands/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAQH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,iFAAiF;IACjF,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,iEAAiE;AACjE,eAAO,MAAM,gBAAgB,8CAA8C,CAAC;AAK5E;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,2VAU1B,CAAC;AAuLJ,wBAAgB,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,GAAG,cAAc,CA+GpF"}

package/dist/commands/migrate.js

@@ -0,0 +1,305 @@
+/**
+ * `aid migrate` — emit the SQL the declared stores need, for an operator to apply once.
+ *
+ * Both runtimes create their own schema on first connect (`CREATE ... IF NOT EXISTS`), so
+ * this command is not how the application works; it is how the application is allowed to
+ * *stop* creating schema. A production role that only needs `INSERT`/`SELECT` should not
+ * hold `CREATE TABLE` because the first request happened to arrive before the table did.
+ * Emitting the same schema as a reviewable file moves that one-time act to the operator
+ * and leaves the application's `IF NOT EXISTS` as a no-op.
+ *
+ * Four decisions worth stating:
+ *
+ * - **Bootstrap only.** Every statement is idempotent, so re-applying is harmless. The file
+ *   creates and never alters: once `aid_chunks` exists, `IF NOT EXISTS` skips the table,
+ *   so an edited vector dimension would report success while the column kept its old type.
+ *   A changed dimension is a *new* migration, and the header says so where the person
+ *   editing the file will read it.
+ * - **No target flag.** The SQL is identical for both runtimes -- they declare the same
+ *   table, the same columns and the same operators -- so a `--target` option would imply a
+ *   per-target difference that does not exist.
+ * - **One file, whatever the store count.** The runtimes use a single shared `aid_chunks`
+ *   table and do not key rows by store id, so a second `pgvector` store is not a second
+ *   table. Emitting one file per store would print the same DDL twice and invite a reader
+ *   to believe the stores are isolated.
+ * - **The file is identified by its own header.** `migrations/` is a directory people keep
+ *   their own migrations in. `aid migrate` only rewrites or deletes a file that carries the
+ *   header it writes, so a hand-written `aid-schema.sql` is refused rather than replaced.
+ *
+ * The table DDL is restated here because neither runtime publishes it as a value the CLI
+ * can import -- Python holds it in a module constant, TypeScript in another. That is a
+ * third copy, so `migrate.test.ts` reads both runtimes' sources and fails when either one
+ * stops agreeing with {@link AID_CHUNKS_TABLE}: the duplication is guarded rather than
+ * hoped for.
+ */
+import { resolve, sep } from 'node:path';
+import { createNodeSink } from '@aid-framework/generator-sdk';
+import { hasErrors } from '@aid-framework/spec';
+import { CLI_DIAGNOSTIC_CODES, cliError, cliWarning } from '../diagnostics.js';
+import { EXIT_FAILURE, EXIT_OK, EXIT_USAGE } from '../exit.js';
+import { outcome } from '../output.js';
+import { lowerSpec, readSpec } from '../pipeline.js';
+import { DEFAULT_SPEC_PATH } from '../targets.js';
+/** The header that marks a file as this command's to rewrite. */
+export const MIGRATION_MARKER = '-- Generated by aid migrate. Do not edit.';
+const DEFAULT_OUT_DIR = 'migrations';
+const FILE_NAME = 'aid-schema.sql';
+/**
+ * The table both runtimes declare, verbatim apart from the embedding type.
+ *
+ * `{embedding}` is replaced with `vector(N)` when the spec pins one dimension and with
+ * `vector` when it does not. The column list, its types and its `NOT NULL`s are what the
+ * runtimes' insert and select statements assume; a driver that added or renamed a column
+ * would fail at runtime, not here.
+ */
+export const AID_CHUNKS_TABLE = `CREATE TABLE IF NOT EXISTS aid_chunks (
+    chunk_id text PRIMARY KEY,
+    doc_id text NOT NULL,
+    uri text NOT NULL,
+    chunk_index integer NOT NULL,
+    start_offset integer NOT NULL,
+    end_offset integer NOT NULL,
+    body text NOT NULL,
+    metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+    embedding {embedding} NOT NULL
+);`;
+const EXTENSION = 'CREATE EXTENSION IF NOT EXISTS vector;';
+/** pgvector's operator classes, one per metric the IR models. */
+const OPERATOR_CLASS = {
+    cosine: 'vector_cosine_ops',
+    dot: 'vector_ip_ops',
+    l2: 'vector_l2_ops',
+};
+/** Shared by both runtimes as the order in which a distance is written in a query. */
+const METRIC_ORDER = ['cosine', 'dot', 'l2'];
+function skipReason(store) {
+    switch (store.kind) {
+        case 'memory':
+            return 'in-process, so there is nothing to provision';
+        case 'custom':
+            return 'the runtime supplies it, so `aid migrate` cannot know its schema';
+        default:
+            return 'a managed service that owns its own schema';
+    }
+}
+/**
+ * The dimension to pin, or `undefined` to leave the column dimensionless.
+ *
+ * Pinning is strictly better when it is possible: the database then rejects a record of
+ * the wrong width at insert time, instead of storing two incompatible vectors in one
+ * table. It is not possible when two stores disagree, because they share the table --
+ * so that case warns instead of silently picking one.
+ */
+function dimensionOf(stores, specPath) {
+    const declared = [...new Set(stores.map((store) => store.dimensions))].filter((value) => value !== undefined);
+    if (declared.length === 0)
+        return { value: undefined, warnings: [] };
+    if (declared.length === 1)
+        return { value: declared[0], warnings: [] };
+    return {
+        value: undefined,
+        warnings: [
+            cliWarning({
+                code: CLI_DIAGNOSTIC_CODES.migrateDimensionAmbiguous,
+                message: `The declared pgvector stores pin different dimensions (${declared.join(', ')}), so the shared \`aid_chunks\` table is left dimensionless.`,
+                path: [specPath],
+                hint: 'One table cannot hold two widths; declare one dimension, or give the stores separate tables by hand.',
+            }),
+        ],
+    };
+}
+/**
+ * One HNSW index per metric a `pgvector`-backed retriever searches with.
+ *
+ * The runtimes never create an index -- a scan over `aid_chunks` is exact, which is fine
+ * for a fixture corpus and quadratic for a real one -- so this is the one part of the file
+ * that is a performance decision rather than a correctness one. HNSW is chosen because it
+ * is the index pgvector ships that needs no training step; `ivfflat` would need data
+ * before it could be built, which is the wrong shape for a first migration.
+ */
+function indexesFor(ir) {
+    const pgvectorIds = new Set(ir.stores.filter((store) => store.kind === 'pgvector').map((store) => store.id));
+    const metrics = new Set();
+    for (const retriever of ir.retrievers) {
+        if (pgvectorIds.has(retriever.store))
+            metrics.add(retriever.index.metric);
+    }
+    return METRIC_ORDER.filter((metric) => metrics.has(metric)).map((metric) => ({
+        name: `aid_chunks_embedding_${metric}_idx`,
+        metric,
+    }));
+}
+function renderSql(dimension, indexes) {
+    const table = AID_CHUNKS_TABLE.replace('{embedding}', dimension === undefined ? 'vector' : `vector(${dimension})`);
+    const statements = [EXTENSION, table];
+    for (const index of indexes) {
+        statements.push(`CREATE INDEX IF NOT EXISTS ${index.name}\n    ON aid_chunks USING hnsw (embedding ${OPERATOR_CLASS[index.metric]});`);
+    }
+    const header = [
+        MIGRATION_MARKER,
+        '--',
+        '-- The schema the declared vector stores need. Apply it once, with DDL rights; the',
+        '-- application itself only needs DML. Every statement is idempotent, so applying this',
+        '-- file again is a no-op.',
+        '--',
+        '-- This file creates, and never alters. Changing a vector dimension or a distance',
+        '-- metric is a new migration, not an edit to this one: the table already exists, so',
+        '-- `IF NOT EXISTS` would skip the statement and report success over the old column.',
+    ];
+    return `${[...header, '', ...statements].join('\n')}\n`;
+}
+function plan(ir, specPath) {
+    const pgvector = ir.stores.filter((store) => store.kind === 'pgvector');
+    const skipped = ir.stores
+        .filter((store) => store.kind !== 'pgvector')
+        .map((store) => ({ id: store.id, kind: store.kind, reason: skipReason(store) }));
+    const dimension = dimensionOf(pgvector, specPath);
+    const indexes = indexesFor(ir);
+    return {
+        pgvector,
+        skipped,
+        dimension: dimension.value,
+        indexes,
+        sql: pgvector.length === 0 ? undefined : renderSql(dimension.value, indexes),
+        warnings: dimension.warnings,
+    };
+}
+/** Strip trailing path separators, falling back to the default when nothing is left. */
+function stripTrailingSeparators(directory) {
+    let end = directory.length;
+    while (end > 0 && (directory[end - 1] === '/' || directory[end - 1] === '\\'))
+        end -= 1;
+    return end === 0 ? DEFAULT_OUT_DIR : directory.slice(0, end);
+}
+/** Whether `relative`, resolved against `cwd`, lands outside the project. */
+function escapes(cwd, relative) {
+    const root = resolve(cwd);
+    const target = resolve(root, relative);
+    return target !== root && !target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+function describe(plan) {
+    const text = [`stores: ${plan.pgvector.length + plan.skipped.length} declared`];
+    for (const store of plan.pgvector)
+        text.push(`  ${store.id} (pgvector)`);
+    for (const store of plan.skipped) {
+        text.push(`  ${store.id} (${store.kind}) -- ${store.reason}`);
+    }
+    if (plan.sql === undefined) {
+        text.push('no pgvector store is declared, so there is no SQL to emit');
+    }
+    else {
+        text.push(`dimension: ${plan.dimension === undefined ? 'not pinned' : `${plan.dimension} (pinned)`}`);
+        if (plan.indexes.length > 0) {
+            text.push(`indexes: ${plan.indexes.map((index) => `${index.name} (${index.metric})`).join(', ')}`);
+        }
+        else {
+            text.push('indexes: none -- no pgvector-backed retriever declares a distance');
+        }
+    }
+    return text;
+}
+export function migrate(context, options) {
+    const command = 'migrate';
+    const specPath = options.spec ?? DEFAULT_SPEC_PATH;
+    const outDir = stripTrailingSeparators(options.out ?? DEFAULT_OUT_DIR);
+    const path = `${outDir}/${FILE_NAME}`;
+    const fields = { spec: specPath, path, check: options.check, dryRun: options.dryRun };
+    // The sink refuses an escaping path by throwing, which reads as an internal error. A
+    // caller who typed an absolute path gets the same refusal, but as an invocation error
+    // that names the flag.
+    if (escapes(context.cwd, path)) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            fields,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.migrateOutEscapes,
+                    message: `\`--out\` resolves to "${path}", which is outside the project.`,
+                    hint: 'Give a directory inside the project, such as `migrations`.',
+                }),
+            ],
+        });
+    }
+    const read = readSpec(context, specPath);
+    if (!read.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: read.diagnostics });
+    }
+    const lowered = lowerSpec(read.text, specPath);
+    if (!lowered.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: lowered.diagnostics });
+    }
+    const sink = createNodeSink(context.cwd);
+    const planned = plan(lowered.ir, specPath);
+    const existing = sink.read(path);
+    const owned = existing?.startsWith(MIGRATION_MARKER) === true;
+    const diagnostics = [...planned.warnings];
+    let action;
+    if (planned.sql === undefined) {
+        action = owned ? 'removed' : 'none';
+    }
+    else if (existing === undefined) {
+        action = 'created';
+    }
+    else if (owned) {
+        action = existing === planned.sql ? 'unchanged' : 'updated';
+    }
+    else {
+        // Someone else's file. Refusing is the whole safety property of this command: the
+        // point of a migrations directory is that its contents are reviewed once and applied
+        // in order, so silently replacing an entry would rewrite history a database already
+        // recorded.
+        diagnostics.push(cliError({
+            code: CLI_DIAGNOSTIC_CODES.refusingToOverwrite,
+            message: `"${path}" exists and was not written by \`aid migrate\`.`,
+            path: [path],
+            hint: 'Move it aside, or pass `--out` to write the generated schema somewhere else.',
+        }));
+        action = 'none';
+    }
+    const pending = action === 'created' || action === 'updated' || action === 'removed';
+    const failed = hasErrors(diagnostics);
+    if (pending && !options.check && !options.dryRun) {
+        // `remove` and `write` are the sink's, so the path-escape guard and the atomic rename
+        // are the ones every generated file already goes through.
+        if (planned.sql === undefined)
+            sink.remove(path);
+        else
+            sink.write(path, planned.sql);
+    }
+    const text = describe(planned);
+    text.push(`${path}: ${action}`);
+    if (options.check && pending) {
+        text.push('the migration does not match the spec; run `aid migrate` and commit the result:');
+        text.push(`  ${path}`);
+    }
+    const verb = action === 'unchanged' || action === 'none'
+        ? 'migrate: ok'
+        : options.check || options.dryRun
+            ? `migrate: would be ${action}`
+            : `migrate: ${action}`;
+    text.push(verb);
+    return outcome({
+        command,
+        exitCode: failed || (options.check && pending) ? EXIT_FAILURE : EXIT_OK,
+        diagnostics,
+        text: text.join('\n'),
+        fields: {
+            ...fields,
+            action,
+            written: pending && !options.check && !options.dryRun,
+            dimension: planned.dimension ?? null,
+            indexes: planned.indexes,
+            stores: [
+                ...planned.pgvector.map((store) => ({ id: store.id, kind: store.kind, status: 'emitted' })),
+                ...planned.skipped.map((store) => ({
+                    id: store.id,
+                    kind: store.kind,
+                    status: 'skipped',
+                    reason: store.reason,
+                })),
+            ],
+        },
+    });
+}
+//# sourceMappingURL=migrate.js.map

package/dist/commands/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"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"}

package/dist/commands/trace.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `aid trace` — read a traced run back out of the local trace sink.
+ *
+ * The sink records *what happened*, not *what was said*: spans carry timing, kind, model,
+ * token counts and priced cost, but no prompts and no completions. So this command
+ * **inspects** a run; it does not replay one. A replay needs the request payloads, and
+ * inventing them -- asking the model again -- would answer a different question than "what
+ * happened here", while looking like an answer to it. Replay stays unimplemented until the
+ * sink records payloads, and the help text says so rather than letting a reader assume.
+ *
+ * Exit codes:
+ *
+ * - `2` when the invocation is wrong: no directory, a selector that matches no run or more
+ *   than one, or `--run` together with `--all`.
+ * - `1` only when a trace file exists and could not be read. The tree still prints: what
+ *   was readable is worth seeing.
+ * - `0` otherwise, including a directory with no runs yet -- "nothing ran" is a true
+ *   answer, and the warning on stderr says why it is empty.
+ */
+import type { CliContext } from '../context.js';
+import type { CommandOutcome } from '../output.js';
+export interface TraceOptions {
+    /** The directory to read; defaults to `$AID_TRACE_DIR`. */
+    readonly dir: string | undefined;
+    /** A full trace id, or an unambiguous prefix of one. */
+    readonly run: string | undefined;
+    /** Print every run's tree instead of the run list. */
+    readonly all: boolean;
+}
+export declare function trace(context: CliContext, options: TraceOptions): CommandOutcome;
+//# sourceMappingURL=trace.d.ts.map

package/dist/commands/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/commands/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMnD,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAgJD,wBAAgB,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,GAAG,cAAc,CA6GhF"}