@aid-framework/cli 0.1.60 → 0.1.62

package/dist/commands/dev.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `aid dev` -- compile the spec, reconcile the tree, and run the application.
+ *
+ * **Why generation is part of it.** The command's whole promise is "the spec you just
+ * edited is the thing serving requests", and a `dev` that started a server against a tree
+ * compiled from an older spec would answer from code the developer is no longer looking
+ * at. So it runs the same generator the `gen` command does, and if generation fails it
+ * does not start the server: a tree that could not be reconciled is not a tree to serve.
+ *
+ * **Why it starts the target's own server instead of one of its own.** The Python target
+ * emits routers; the application owns `app/main.py` and decides what to mount and how to
+ * run it (the generator says so in its own comments). A dev server implemented here would
+ * be a second, competing way to run the same app, and it would drift. So this command
+ * spawns the module the application already declares, which is also what a person types by
+ * hand: `python -m uvicorn app.main:app`. `-m uvicorn` rather than the `uvicorn` binary,
+ * because the probe that proved the interpreter can import the runtime also proves it can
+ * import uvicorn; a `uvicorn` script on `PATH` proves neither.
+ *
+ * **Why a target may refuse.** `ts-vercel` is a deployment target: it emits route handlers
+ * that Next mounts, and ships no server of its own to start. Inventing one here would be
+ * exactly the competing dev server the previous paragraph rules out. The registry declares
+ * that per target, so this command refuses with a reason rather than guessing.
+ *
+ * **Why the start banner is printed by the command.** Every other command returns text and
+ * lets the dispatcher print it. This one hands the terminal to a child for an unbounded
+ * time, so a banner returned after the server exits would arrive after the log it was
+ * meant to introduce. The banner and the generation summary are therefore written as they
+ * happen, and the returned text is only the farewell.
+ *
+ * **Why there is no `--json`.** A JSON document is a verdict about a finished run. `dev`
+ * produces a running process and a stream of server output, so the honest answers are "a
+ * document that lies about when the run ended" or "a document interrupted by logs". It
+ * refuses `--json` as a usage error instead of emitting something that cannot be parsed.
+ *
+ * **What is not watched.** uvicorn's `--reload` reloads on changes to the code it imported,
+ * and that is left on by default. The *spec* is not watched: regenerating it needs the
+ * generator to run again, and doing that from a synchronous command would mean the
+ * dispatcher grew an event loop for one command. Restart `aid dev` after editing the spec;
+ * the generation step makes that restart cheap and the tree correct either way.
+ */
+import type { CliContext } from '../context.js';
+import type { CommandOutcome } from '../output.js';
+export interface DevOptions {
+    readonly spec: string | undefined;
+    readonly target: string | undefined;
+    readonly port: string | undefined;
+    /** Skip regeneration and serve the tree as it is. */
+    readonly noGen: boolean;
+    /** Turn off uvicorn's own reloader. */
+    readonly noReload: boolean;
+}
+export declare function dev(context: CliContext, options: DevOptions): CommandOutcome;
+//# sourceMappingURL=dev.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAOnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAaD,wBAAgB,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,cAAc,CA6L5E"}

package/dist/commands/dev.js

@@ -0,0 +1,235 @@
+/**
+ * `aid dev` -- compile the spec, reconcile the tree, and run the application.
+ *
+ * **Why generation is part of it.** The command's whole promise is "the spec you just
+ * edited is the thing serving requests", and a `dev` that started a server against a tree
+ * compiled from an older spec would answer from code the developer is no longer looking
+ * at. So it runs the same generator the `gen` command does, and if generation fails it
+ * does not start the server: a tree that could not be reconciled is not a tree to serve.
+ *
+ * **Why it starts the target's own server instead of one of its own.** The Python target
+ * emits routers; the application owns `app/main.py` and decides what to mount and how to
+ * run it (the generator says so in its own comments). A dev server implemented here would
+ * be a second, competing way to run the same app, and it would drift. So this command
+ * spawns the module the application already declares, which is also what a person types by
+ * hand: `python -m uvicorn app.main:app`. `-m uvicorn` rather than the `uvicorn` binary,
+ * because the probe that proved the interpreter can import the runtime also proves it can
+ * import uvicorn; a `uvicorn` script on `PATH` proves neither.
+ *
+ * **Why a target may refuse.** `ts-vercel` is a deployment target: it emits route handlers
+ * that Next mounts, and ships no server of its own to start. Inventing one here would be
+ * exactly the competing dev server the previous paragraph rules out. The registry declares
+ * that per target, so this command refuses with a reason rather than guessing.
+ *
+ * **Why the start banner is printed by the command.** Every other command returns text and
+ * lets the dispatcher print it. This one hands the terminal to a child for an unbounded
+ * time, so a banner returned after the server exits would arrive after the log it was
+ * meant to introduce. The banner and the generation summary are therefore written as they
+ * happen, and the returned text is only the farewell.
+ *
+ * **Why there is no `--json`.** A JSON document is a verdict about a finished run. `dev`
+ * produces a running process and a stream of server output, so the honest answers are "a
+ * document that lies about when the run ended" or "a document interrupted by logs". It
+ * refuses `--json` as a usage error instead of emitting something that cannot be parsed.
+ *
+ * **What is not watched.** uvicorn's `--reload` reloads on changes to the code it imported,
+ * and that is left on by default. The *spec* is not watched: regenerating it needs the
+ * generator to run again, and doing that from a synchronous command would mean the
+ * dispatcher grew an event loop for one command. Restart `aid dev` after editing the spec;
+ * the generation step makes that restart cheap and the tree correct either way.
+ */
+import { existsSync } from 'node:fs';
+import { sortDiagnostics } from '@aid-framework/spec';
+import { CLI_DIAGNOSTIC_CODES, cliError } from '../diagnostics.js';
+import { EXIT_FAILURE, EXIT_OK, EXIT_USAGE } from '../exit.js';
+import { outcome } from '../output.js';
+import { absolutePath } from '../paths.js';
+import { DEV_PROBE, discoverInterpreter, INTERPRETERS, interpreterCommand } from '../python.js';
+import { resolveTarget, unknownTargetDiagnostic } from '../targets.js';
+import { generate } from './gen.js';
+/** uvicorn's own default, so `aid dev` and `uvicorn app.main:app` agree. */
+const DEFAULT_PORT = 8000;
+/** The port, or `undefined` when the flag could not have meant one. */
+function parsePort(raw) {
+    if (raw === undefined)
+        return DEFAULT_PORT;
+    if (!/^\d+$/.test(raw))
+        return undefined;
+    const port = Number(raw);
+    return port >= 1 && port <= 65_535 ? port : undefined;
+}
+export function dev(context, options) {
+    const command = 'dev';
+    const target = resolveTarget(options.target);
+    if (target === undefined) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            diagnostics: [unknownTargetDiagnostic(options.target ?? '')],
+        });
+    }
+    // Before the project is touched: a port that is not a port is a mistake in the
+    // invocation, and reporting a spec problem instead would bury the actual mistake.
+    const port = parsePort(options.port);
+    if (port === undefined) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.devPortInvalid,
+                    message: `\`--port\` needs an integer between 1 and 65535, got "${options.port}".`,
+                }),
+            ],
+        });
+    }
+    const specPath = options.spec ?? target.specPath;
+    const fields = { target: target.name, spec: specPath, port };
+    const surface = target.dev;
+    if (surface.kind === 'none') {
+        return outcome({
+            command,
+            // Exit 2, not 1: no server was started and no project was judged, so nothing here
+            // is a verdict about the tree.
+            exitCode: EXIT_USAGE,
+            fields,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.runnerUnsupported,
+                    message: `\`aid dev\` cannot start ${target.name}: ${surface.reason}.`,
+                    hint: 'Run the application with the server its platform provides; `aid gen` still compiles and reconciles the tree.',
+                }),
+            ],
+        });
+    }
+    const diagnostics = [];
+    if (!options.noGen) {
+        const generated = generate(context, {
+            spec: options.spec,
+            target: options.target,
+            dryRun: false,
+            force: false,
+            check: false,
+        });
+        if (generated.exitCode !== EXIT_OK) {
+            // The generator's own summary and diagnostics are the answer: it is the same
+            // failure `aid gen` would have reported, and renaming it here would hide that.
+            return outcome({
+                command,
+                exitCode: generated.exitCode,
+                fields,
+                diagnostics: generated.diagnostics,
+                text: generated.text,
+            });
+        }
+        if (generated.text !== '')
+            context.stdout(`${generated.text}\n`);
+        diagnostics.push(...generated.diagnostics);
+    }
+    // The entry point is the application's own file, not a generated one, so its absence
+    // means the project was never set up rather than never regenerated. Named explicitly
+    // because "app/main.py is missing" is the one thing the reader needs to know.
+    const entry = absolutePath(context.cwd, surface.entry);
+    if (!existsSync(entry)) {
+        return outcome({
+            command,
+            exitCode: EXIT_FAILURE,
+            fields,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.devEntryMissing,
+                    message: `No ASGI entry point at ${surface.entry}.`,
+                    path: [surface.entry],
+                    hint: 'Run `aid init` for a starter entry point, or run `aid dev` from the directory that contains the generated app.',
+                }),
+            ],
+        });
+    }
+    const interpreter = discoverInterpreter(context, DEV_PROBE);
+    if (interpreter === undefined) {
+        return outcome({
+            command,
+            // Exit 2: the project was not judged, because nothing could start it.
+            exitCode: EXIT_USAGE,
+            fields,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.devUvicornMissing,
+                    message: `No interpreter can import both aid_runtime and uvicorn (tried ${INTERPRETERS.join(', ')}).`,
+                    hint: 'Install the runtime and uvicorn into the interpreter you run with, or run `python -m uvicorn` yourself.',
+                }),
+            ],
+        });
+    }
+    const argv = [
+        ...interpreterCommand(interpreter),
+        '-m',
+        'uvicorn',
+        surface.module,
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        ...(options.noReload ? [] : ['--reload']),
+    ];
+    // Bound to loopback on purpose: a dev server is for the machine it runs on, and a
+    // `0.0.0.0` default quietly exposes a half-built app to the network.
+    context.stdout([
+        `${target.name}: serving ${surface.module} on http://127.0.0.1:${port}${options.noReload ? '' : ' (reload on)'}`,
+        `  ${argv.join(' ')}`,
+        'Press Ctrl-C to stop.',
+        '',
+    ].join('\n'));
+    const run = context.spawn(argv[0] ?? interpreter, argv.slice(1), {
+        cwd: context.cwd,
+        stdio: 'inherit',
+        env: context.env,
+    });
+    if (run.error !== undefined) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            fields: { ...fields, interpreter },
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.runnerFailed,
+                    message: `Could not start ${interpreter} to run "${surface.module}": ${run.error.message}`,
+                }),
+            ],
+        });
+    }
+    // A null status means the child was ended by a signal, which for a foreground server is
+    // how Ctrl-C arrives. Reporting that as a failure would make stopping the dev server
+    // look like the server broke.
+    if (run.status === null) {
+        return outcome({
+            command,
+            exitCode: EXIT_OK,
+            fields: { ...fields, interpreter, stopped: true },
+            diagnostics: sortDiagnostics(diagnostics),
+            text: 'server stopped.',
+        });
+    }
+    if (run.status !== 0) {
+        return outcome({
+            command,
+            exitCode: EXIT_FAILURE,
+            fields: { ...fields, interpreter, status: run.status },
+            diagnostics: sortDiagnostics([
+                ...diagnostics,
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.runnerFailed,
+                    message: `The server exited with status ${run.status}.`,
+                }),
+            ]),
+        });
+    }
+    return outcome({
+        command,
+        exitCode: EXIT_OK,
+        fields: { ...fields, interpreter },
+        diagnostics: sortDiagnostics(diagnostics),
+        text: 'server stopped.',
+    });
+}
+//# sourceMappingURL=dev.js.map

package/dist/commands/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAItD,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAYpC,4EAA4E;AAC5E,MAAM,YAAY,GAAG,IAAI,CAAC;AAE1B,uEAAuE;AACvE,SAAS,SAAS,CAAC,GAAuB;IACxC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAC3C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,OAAO,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,OAAmB,EAAE,OAAmB;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC;IAEtB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC;YACb,OAAO;YACP,QAAQ,EAAE,UAAU;YACpB,WAAW,EAAE,CAAC,uBAAuB,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED,+EAA+E;IAC/E,kFAAkF;IAClF,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,OAAO,CAAC;YACb,OAAO;YACP,QAAQ,EAAE,UAAU;YACpB,WAAW,EAAE;gBACX,QAAQ,CAAC;oBACP,IAAI,EAAE,oBAAoB,CAAC,cAAc;oBACzC,OAAO,EAAE,yDAAyD,OAAO,CAAC,IAAI,IAAI;iBACnF,CAAC;aACH;SACF,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IACjD,MAAM,MAAM,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC7D,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC;IAE3B,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO,OAAO,CAAC;YACb,OAAO;YACP,kFAAkF;YAClF,+BAA+B;YAC/B,QAAQ,EAAE,UAAU;YACpB,MAAM;YACN,WAAW,EAAE;gBACX,QAAQ,CAAC;oBACP,IAAI,EAAE,oBAAoB,CAAC,iBAAiB;oBAC5C,OAAO,EAAE,4BAA4B,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG;oBACtE,IAAI,EAAE,8GAA8G;iBACrH,CAAC;aACH;SACF,CAAC,CAAC;IACL,CAAC;IAED,MAAM,WAAW,GAAoB,EAAE,CAAC;IAExC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,EAAE;YAClC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,KAAK;YACb,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACnC,6EAA6E;YAC7E,+EAA+E;YAC/E,OAAO,OAAO,CAAC;gBACb,OAAO;gBACP,QAAQ,EAAE,SAAS,CAAC,QAAQ;gBAC5B,MAAM;gBACN,WAAW,EAAE,SAAS,CAAC,WAAW;gBAClC,IAAI,EAAE,SAAS,CAAC,IAAI;aACrB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,SAAS,CAAC,IAAI,KAAK,EAAE;YAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,IAAI,CAAC,CAAC;QACjE,WAAW,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED,qFAAqF;IACrF,qFAAqF;IACrF,8EAA8E;IAC9E,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvD,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,OAAO,CAAC;YACb,OAAO;YACP,QAAQ,EAAE,YAAY;YACtB,MAAM;YACN,WAAW,EAAE;gBACX,QAAQ,CAAC;oBACP,IAAI,EAAE,oBAAoB,CAAC,eAAe;oBAC1C,OAAO,EAAE,0BAA0B,OAAO,CAAC,KAAK,GAAG;oBACnD,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;oBACrB,IAAI,EAAE,gHAAgH;iBACvH,CAAC;aACH;SACF,CAAC,CAAC;IACL,CAAC;IAED,MAAM,WAAW,GAAG,mBAAmB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5D,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC;YACb,OAAO;YACP,sEAAsE;YACtE,QAAQ,EAAE,UAAU;YACpB,MAAM;YACN,WAAW,EAAE;gBACX,QAAQ,CAAC;oBACP,IAAI,EAAE,oBAAoB,CAAC,iBAAiB;oBAC5C,OAAO,EAAE,iEAAiE,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;oBACrG,IAAI,EAAE,yGAAyG;iBAChH,CAAC;aACH;SACF,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG;QACX,GAAG,kBAAkB,CAAC,WAAW,CAAC;QAClC,IAAI;QACJ,SAAS;QACT,OAAO,CAAC,MAAM;QACd,QAAQ;QACR,WAAW;QACX,QAAQ;QACR,MAAM,CAAC,IAAI,CAAC;QACZ,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;KAC1C,CAAC;IAEF,kFAAkF;IAClF,qEAAqE;IACrE,OAAO,CAAC,MAAM,CACZ;QACE,GAAG,MAAM,CAAC,IAAI,aAAa,OAAO,CAAC,MAAM,wBAAwB,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,EAAE;QAChH,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;QACrB,uBAAuB;QACvB,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IAEF,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QAC/D,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,SAAS;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IAEH,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,OAAO,CAAC;YACb,OAAO;YACP,QAAQ,EAAE,UAAU;YACpB,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE;YAClC,WAAW,EAAE;gBACX,QAAQ,CAAC;oBACP,IAAI,EAAE,oBAAoB,CAAC,YAAY;oBACvC,OAAO,EAAE,mBAAmB,WAAW,YAAY,OAAO,CAAC,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE;iBAC3F,CAAC;aACH;SACF,CAAC,CAAC;IACL,CAAC;IAED,wFAAwF;IACxF,qFAAqF;IACrF,8BAA8B;IAC9B,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;YACb,OAAO;YACP,QAAQ,EAAE,OAAO;YACjB,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE;YACjD,WAAW,EAAE,eAAe,CAAC,WAAW,CAAC;YACzC,IAAI,EAAE,iBAAiB;SACxB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,OAAO,CAAC;YACb,OAAO;YACP,QAAQ,EAAE,YAAY;YACtB,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;YACtD,WAAW,EAAE,eAAe,CAAC;gBAC3B,GAAG,WAAW;gBACd,QAAQ,CAAC;oBACP,IAAI,EAAE,oBAAoB,CAAC,YAAY;oBACvC,OAAO,EAAE,iCAAiC,GAAG,CAAC,MAAM,GAAG;iBACxD,CAAC;aACH,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;QACb,OAAO;QACP,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE;QAClC,WAAW,EAAE,eAAe,CAAC,WAAW,CAAC;QACzC,IAAI,EAAE,iBAAiB;KACxB,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `aid guard` -- measure an app's guardrails against a red-team corpus.
+ *
+ * **What is measured, and why it is measured here.** The runtime's `GuardrailEngine` is
+ * the thing that decides whether text is a jailbreak, a secret, or an injection, and the
+ * generated `generated/guardrails.py` is the table of declarations the routes enforce.
+ * This command joins the two and reports, per fixture, whether the table the app actually
+ * shipped caught it. Detection is not reimplemented: a second implementation here would
+ * drift from the one the routes run, and the number it produced would describe the CLI
+ * rather than the application.
+ *
+ * **Why the corpus is an input.** The framework's own corpus lives in
+ * `runtimes/python/tests/redteam/fixtures.json` and is not shipped with any package.
+ * Copying it into the CLI would create a second copy that drifts from the one
+ * `test_redteam.py` gates on, and shipping it with the runtime would change a landed
+ * layer's published contents for one command's convenience. So the format is the
+ * contract: `--red-team` names a file, and without it the command looks for
+ * `redteam.json` beside the spec and then at the project root.
+ *
+ * **Why it evaluates the declared table, not one synthesized definition per fixture.**
+ * `test_redteam.py` builds a `GuardrailDefinition` for each fixture and runs it alone,
+ * because it is testing the detectors. This command is answering a different question --
+ * "would *this app* have caught this?" -- so it hands the engine every declaration that
+ * covers the fixture's stage, exactly as a route does, and a fixture counts as caught
+ * when any of them fires. A declaration that names the wrong policy still counts as a
+ * catch if its other policy fires: the app stopped the payload, which is what matters.
+ *
+ * **Why `covered` is a separate fact from `caught`.** "No declaration at this stage names
+ * this policy" is a spec gap the developer can close by editing the YAML; "declared but
+ * the detector missed" is a detector gap they cannot. Folding both into one recall number
+ * would send a reader to the wrong file, so the undeclared pairs are listed on their own
+ * line and in the `--json` document.
+ *
+ * **Why nothing is regenerated.** A gate measures the tree it is given, and `aid eval`
+ * already sets that precedent: this command reads `generated/guardrails.py`, and a tree
+ * that predates the spec is reported as a missing or stale module rather than silently
+ * replaced. Run `aid gen` first, as CI does.
+ *
+ * **When it does not run, and what it exits with.** Exit 2 is "this command could not
+ * judge the project": an unknown target, a target with no driver, a corpus that is
+ * missing or malformed, or no interpreter that can import the runtime. Exit 1 is a
+ * verdict about the project: it declares no guardrails, its tree has no guardrail module,
+ * the run failed, or the measured recall / false-positive rate misses what the corpus
+ * asks for.
+ */
+import type { CliContext } from '../context.js';
+import type { CommandOutcome } from '../output.js';
+export interface GuardOptions {
+    readonly spec: string | undefined;
+    readonly target: string | undefined;
+    /** The corpus to measure against; discovered beside the spec when omitted. */
+    readonly redTeam: string | undefined;
+}
+export declare function guard(context: CliContext, options: GuardOptions): CommandOutcome;
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/commands/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAOnD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAwZD,wBAAgB,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,GAAG,cAAc,CAkYhF"}