@aid-framework/cli 0.0.0 → 0.1.48

package/dist/context.js

@@ -0,0 +1,36 @@
+/**
+ * Everything the CLI touches outside of itself, behind one injectable object.
+ *
+ * A CLI is mostly side effects, and side effects are what makes a command hard to test.
+ * Naming them in one place keeps every command a pure function of its arguments and
+ * this context, so a test can run a whole command against a temporary directory and
+ * assert on what it printed, what it wrote, and what it exited with -- without a
+ * subprocess, and without a mock for the parts that are not I/O.
+ */
+import { spawnSync } from 'node:child_process';
+function spawnWith(command, args, options) {
+    const result = spawnSync(command, [...args], {
+        cwd: options.cwd,
+        env: { ...options.env },
+        stdio: options.stdio === 'pipe' ? ['pipe', 'pipe', 'pipe'] : 'inherit',
+        encoding: 'utf8',
+        ...(options.stdin === undefined ? {} : { input: options.stdin }),
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        ...(result.error === undefined ? {} : { error: result.error }),
+    };
+}
+/** The real world: the process streams, the process environment, and real children. */
+export function createContext(overrides = {}) {
+    return {
+        cwd: overrides.cwd ?? process.cwd(),
+        env: overrides.env ?? process.env,
+        stdout: overrides.stdout ?? ((text) => process.stdout.write(text)),
+        stderr: overrides.stderr ?? ((text) => process.stderr.write(text)),
+        spawn: overrides.spawn ?? spawnWith,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAmC/C,SAAS,SAAS,CAAC,OAAe,EAAE,IAAuB,EAAE,OAAqB;IAChF,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;QAC3C,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAuB;QAC5C,KAAK,EAAE,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;QACtE,QAAQ,EAAE,MAAM;QAChB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;KACjE,CAAC,CAAC;IACH,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;QAC3B,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,aAAa,CAAC,SAAS,GAAwB,EAAE;IAC/D,OAAO;QACL,GAAG,EAAE,SAAS,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;QACnC,GAAG,EAAE,SAAS,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG;QACjC,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1E,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1E,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,SAAS;KACpC,CAAC;AACJ,CAAC"}

package/dist/diagnostics.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Diagnostics, the one currency every layer already speaks.
+ *
+ * `@aid-framework/spec` defines the shape and the renderer, and `@aid-framework/ir` and
+ * `@aid-framework/generator-sdk` re-declare the same shape nominally with their own closed code
+ * unions. The CLI reads all of them through the widened `Diagnostic<string>` view and
+ * renders them with the spec package's renderer: it renames no code, re-ranks no
+ * severity, and re-checks nothing a gate already decided.
+ *
+ * The codes below are the ones *this* layer originates -- a file that could not be
+ * read, a target that does not exist, a Python interpreter that is not there. They
+ * follow the same `<layer>/<slug>` convention so that a reader cannot tell which layer
+ * produced a code from its shape, which is the point.
+ */
+import type { Diagnostic } from '@aid-framework/spec';
+/** The shared diagnostic shape, widened over the code union. */
+export type CliDiagnostic = Diagnostic<string>;
+export declare const CLI_DIAGNOSTIC_CODES: {
+    readonly specUnreadable: 'cli/spec-unreadable';
+    readonly unknownTarget: 'cli/unknown-target';
+    readonly refusingToOverwrite: 'cli/refusing-to-overwrite';
+    readonly pythonMissing: 'cli/python-missing';
+    readonly suiteNotFound: 'cli/suite-not-found';
+    readonly evalModulesMissing: 'cli/eval-modules-missing';
+    readonly retrieverRequired: 'cli/retriever-required';
+    readonly retrieverConflict: 'cli/retriever-conflict';
+    readonly retrieverNotFound: 'cli/retriever-not-found';
+    readonly ingestModulesMissing: 'cli/ingest-modules-missing';
+    readonly runnerUnsupported: 'cli/runner-unsupported';
+    readonly runnerFailed: 'cli/runner-failed';
+    readonly runnerWarned: 'cli/runner-warned';
+};
+export type CliDiagnosticCode = (typeof CLI_DIAGNOSTIC_CODES)[keyof typeof CLI_DIAGNOSTIC_CODES];
+export interface CliDiagnosticInit {
+    readonly code: CliDiagnosticCode;
+    readonly message: string;
+    readonly path?: readonly string[];
+    readonly hint?: string;
+}
+export declare function cliError(init: CliDiagnosticInit): CliDiagnostic;
+export declare function cliWarning(init: CliDiagnosticInit): CliDiagnostic;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;AAE/C,eAAO,MAAM,oBAAoB;aAC/B,cAAc,EAAE,qBAAqB;aACrC,aAAa,EAAE,oBAAoB;aACnC,mBAAmB,EAAE,2BAA2B;aAChD,aAAa,EAAE,oBAAoB;aACnC,aAAa,EAAE,qBAAqB;aACpC,kBAAkB,EAAE,0BAA0B;aAC9C,iBAAiB,EAAE,wBAAwB;aAC3C,iBAAiB,EAAE,wBAAwB;aAC3C,iBAAiB,EAAE,yBAAyB;aAC5C,oBAAoB,EAAE,4BAA4B;aAClD,iBAAiB,EAAE,wBAAwB;aAC3C,YAAY,EAAE,mBAAmB;aACjC,YAAY,EAAE,mBAAmB;CACzB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAEjG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAO/D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAOjE"}

package/dist/diagnostics.js

@@ -0,0 +1,47 @@
+/**
+ * Diagnostics, the one currency every layer already speaks.
+ *
+ * `@aid-framework/spec` defines the shape and the renderer, and `@aid-framework/ir` and
+ * `@aid-framework/generator-sdk` re-declare the same shape nominally with their own closed code
+ * unions. The CLI reads all of them through the widened `Diagnostic<string>` view and
+ * renders them with the spec package's renderer: it renames no code, re-ranks no
+ * severity, and re-checks nothing a gate already decided.
+ *
+ * The codes below are the ones *this* layer originates -- a file that could not be
+ * read, a target that does not exist, a Python interpreter that is not there. They
+ * follow the same `<layer>/<slug>` convention so that a reader cannot tell which layer
+ * produced a code from its shape, which is the point.
+ */
+import { errorDiagnostic, warningDiagnostic } from '@aid-framework/spec';
+export const CLI_DIAGNOSTIC_CODES = {
+    specUnreadable: 'cli/spec-unreadable',
+    unknownTarget: 'cli/unknown-target',
+    refusingToOverwrite: 'cli/refusing-to-overwrite',
+    pythonMissing: 'cli/python-missing',
+    suiteNotFound: 'cli/suite-not-found',
+    evalModulesMissing: 'cli/eval-modules-missing',
+    retrieverRequired: 'cli/retriever-required',
+    retrieverConflict: 'cli/retriever-conflict',
+    retrieverNotFound: 'cli/retriever-not-found',
+    ingestModulesMissing: 'cli/ingest-modules-missing',
+    runnerUnsupported: 'cli/runner-unsupported',
+    runnerFailed: 'cli/runner-failed',
+    runnerWarned: 'cli/runner-warned',
+};
+export function cliError(init) {
+    return errorDiagnostic({
+        code: init.code,
+        message: init.message,
+        path: init.path ?? [],
+        ...(init.hint === undefined ? {} : { hint: init.hint }),
+    });
+}
+export function cliWarning(init) {
+    return warningDiagnostic({
+        code: init.code,
+        message: init.message,
+        path: init.path ?? [],
+        ...(init.hint === undefined ? {} : { hint: init.hint }),
+    });
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAKzE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,cAAc,EAAE,qBAAqB;IACrC,aAAa,EAAE,oBAAoB;IACnC,mBAAmB,EAAE,2BAA2B;IAChD,aAAa,EAAE,oBAAoB;IACnC,aAAa,EAAE,qBAAqB;IACpC,kBAAkB,EAAE,0BAA0B;IAC9C,iBAAiB,EAAE,wBAAwB;IAC3C,iBAAiB,EAAE,wBAAwB;IAC3C,iBAAiB,EAAE,yBAAyB;IAC5C,oBAAoB,EAAE,4BAA4B;IAClD,iBAAiB,EAAE,wBAAwB;IAC3C,YAAY,EAAE,mBAAmB;IACjC,YAAY,EAAE,mBAAmB;CACzB,CAAC;AAWX,MAAM,UAAU,QAAQ,CAAC,IAAuB;IAC9C,OAAO,eAAe,CAAC;QACrB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;KACxD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,OAAO,iBAAiB,CAAC;QACvB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;KACxD,CAAC,CAAC;AACL,CAAC"}

package/dist/exit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The CLI's exit-code taxonomy, which is a contract with CI rather than a convention.
+ *
+ * `0` means the command finished *and* the project is in the shape the command asked
+ * for; `1` means the command ran but the spec, a gate, the target's compiler or the
+ * working tree rejected it; `2` means the command line itself was wrong, or the CLI
+ * could not get far enough to judge the project at all. Nothing else is ever returned,
+ * and no command maps two different outcomes onto the same code.
+ */
+export declare const EXIT_OK = 0;
+/** The spec, the gates, the target's plan, or the working tree said no. */
+export declare const EXIT_FAILURE = 1;
+/** The invocation was wrong, or the CLI hit an internal failure. */
+export declare const EXIT_USAGE = 2;
+export type ExitCode = typeof EXIT_OK | typeof EXIT_FAILURE | typeof EXIT_USAGE;
+//# sourceMappingURL=exit.d.ts.map

package/dist/exit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../src/exit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,OAAO,IAAI,CAAC;AAEzB,2EAA2E;AAC3E,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,oEAAoE;AACpE,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,MAAM,MAAM,QAAQ,GAAG,OAAO,OAAO,GAAG,OAAO,YAAY,GAAG,OAAO,UAAU,CAAC"}

package/dist/exit.js

@@ -0,0 +1,15 @@
+/**
+ * The CLI's exit-code taxonomy, which is a contract with CI rather than a convention.
+ *
+ * `0` means the command finished *and* the project is in the shape the command asked
+ * for; `1` means the command ran but the spec, a gate, the target's compiler or the
+ * working tree rejected it; `2` means the command line itself was wrong, or the CLI
+ * could not get far enough to judge the project at all. Nothing else is ever returned,
+ * and no command maps two different outcomes onto the same code.
+ */
+export const EXIT_OK = 0;
+/** The spec, the gates, the target's plan, or the working tree said no. */
+export const EXIT_FAILURE = 1;
+/** The invocation was wrong, or the CLI hit an internal failure. */
+export const EXIT_USAGE = 2;
+//# sourceMappingURL=exit.js.map

package/dist/exit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.js","sourceRoot":"","sources":["../src/exit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AAEzB,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B,oEAAoE;AACpE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `@aid-framework/cli` - the `aid` command: init, validate, gen, ingest and eval.
+ *
+ * The CLI is glue. Every judgement it reports -- whether a spec parses, what the IR is,
+ * what a target can emit, which generated file was hand-edited, whether an eval regressed
+ * -- is made by a package below it, and this layer's job is to route arguments into those
+ * packages and their answers back out as text, JSON and an exit code. It reimplements no
+ * gate, no hash and no drift rule, because a second implementation of a rule is a defect:
+ * the two will disagree, and only one of them will be right.
+ *
+ * The layering is `spec <- ir <- generator-sdk <- generators <- cli`.
+ */
+export type { FlagSpec, ParsedArguments, ParseOutcome } from './args.js';
+export { booleanFlag, JSON_FLAG, parseArguments, valueFlag } from './args.js';
+export type { EvalOptions } from './commands/eval.js';
+export { evaluate } from './commands/eval.js';
+export type { GenerateOptions, GenerateSuccess } from './commands/gen.js';
+export { generate } from './commands/gen.js';
+export type { IngestOptions } from './commands/ingest.js';
+export { ingest } from './commands/ingest.js';
+export type { InitOptions } from './commands/init.js';
+export { init, projectNameFor, starterSpec } from './commands/init.js';
+export type { ValidateOptions } from './commands/validate.js';
+export { validate } from './commands/validate.js';
+export type { CliContext, Spawn, SpawnOptions, SpawnResult } from './context.js';
+export { createContext } from './context.js';
+export type { CliDiagnostic, CliDiagnosticCode, CliDiagnosticInit } from './diagnostics.js';
+export { CLI_DIAGNOSTIC_CODES, cliError, cliWarning } from './diagnostics.js';
+export type { ExitCode } from './exit.js';
+export { EXIT_FAILURE, EXIT_OK, EXIT_USAGE } from './exit.js';
+export { COMMANDS, run } from './main.js';
+export type { CommandOutcome, OutcomeInit } from './output.js';
+export { emit, outcome } from './output.js';
+export { absolutePath, parentPath } from './paths.js';
+export type { Compiled, CompileOutcome, Failed, Lowered, LowerOutcome, ManifestOutcome, ReadManifest, ReadSpec, } from './pipeline.js';
+export { compile, lowerSpec, provenanceFor, readManifest, readSpec } from './pipeline.js';
+export { discoverInterpreter, INTERPRETERS, interpreterCommand, invoke } from './python.js';
+export type { Target } from './targets.js';
+export { DEFAULT_SPEC_PATH, DEFAULT_TARGET, resolveTarget, TARGETS, targetCapabilities, targetNames, unknownTargetDiagnostic, } from './targets.js';
+export type { CommandSpec } from './usage.js';
+export { commandUsage, globalUsage } from './usage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC9E,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EACV,QAAQ,EACR,cAAc,EACd,MAAM,EACN,OAAO,EACP,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC5F,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,OAAO,EACP,kBAAkB,EAClB,WAAW,EACX,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@aid-framework/cli` - the `aid` command: init, validate, gen, ingest and eval.
+ *
+ * The CLI is glue. Every judgement it reports -- whether a spec parses, what the IR is,
+ * what a target can emit, which generated file was hand-edited, whether an eval regressed
+ * -- is made by a package below it, and this layer's job is to route arguments into those
+ * packages and their answers back out as text, JSON and an exit code. It reimplements no
+ * gate, no hash and no drift rule, because a second implementation of a rule is a defect:
+ * the two will disagree, and only one of them will be right.
+ *
+ * The layering is `spec <- ir <- generator-sdk <- generators <- cli`.
+ */
+export { booleanFlag, JSON_FLAG, parseArguments, valueFlag } from './args.js';
+export { evaluate } from './commands/eval.js';
+export { generate } from './commands/gen.js';
+export { ingest } from './commands/ingest.js';
+export { init, projectNameFor, starterSpec } from './commands/init.js';
+export { validate } from './commands/validate.js';
+export { createContext } from './context.js';
+export { CLI_DIAGNOSTIC_CODES, cliError, cliWarning } from './diagnostics.js';
+export { EXIT_FAILURE, EXIT_OK, EXIT_USAGE } from './exit.js';
+export { COMMANDS, run } from './main.js';
+export { emit, outcome } from './output.js';
+export { absolutePath, parentPath } from './paths.js';
+export { compile, lowerSpec, provenanceFor, readManifest, readSpec } from './pipeline.js';
+export { discoverInterpreter, INTERPRETERS, interpreterCommand, invoke } from './python.js';
+export { DEFAULT_SPEC_PATH, DEFAULT_TARGET, resolveTarget, TARGETS, targetCapabilities, targetNames, unknownTargetDiagnostic, } from './targets.js';
+export { commandUsage, globalUsage } from './usage.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE9E,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAWtD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE5F,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,OAAO,EACP,kBAAkB,EAClB,WAAW,EACX,uBAAuB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/main.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The dispatcher: argv in, exit code out.
+ *
+ * It is a pure function of the argv and a `CliContext`, so the whole CLI can be driven in
+ * a test by calling `run([...], context)` against a temporary directory and asserting on
+ * the captured streams -- no subprocess, no `process.exit`, no spawning the built binary
+ * to find out what a flag does.
+ *
+ * `run` decides only what is genuinely global: which command, whether the invocation was
+ * well formed, whether help was asked for, and how an unforeseen exception maps onto an
+ * exit code. Everything else belongs to the command, which is why each entry in the table
+ * below is a two-line adapter and not a flag handler.
+ */
+import type { ParsedArguments } from './args.js';
+import type { CliContext } from './context.js';
+import type { ExitCode } from './exit.js';
+import type { CommandOutcome } from './output.js';
+import type { CommandSpec } from './usage.js';
+interface Command extends CommandSpec {
+    readonly run: (context: CliContext, args: ParsedArguments) => CommandOutcome;
+}
+export declare const COMMANDS: readonly Command[];
+export declare function run(argv: readonly string[], context: CliContext): ExitCode;
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAOjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,UAAU,OAAQ,SAAQ,WAAW;IACnC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,KAAK,cAAc,CAAC;CAC9E;AAQD,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EAoFtC,CAAC;AA0BF,wBAAgB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,CAuC1E"}

package/dist/main.js

@@ -0,0 +1,155 @@
+/**
+ * The dispatcher: argv in, exit code out.
+ *
+ * It is a pure function of the argv and a `CliContext`, so the whole CLI can be driven in
+ * a test by calling `run([...], context)` against a temporary directory and asserting on
+ * the captured streams -- no subprocess, no `process.exit`, no spawning the built binary
+ * to find out what a flag does.
+ *
+ * `run` decides only what is genuinely global: which command, whether the invocation was
+ * well formed, whether help was asked for, and how an unforeseen exception maps onto an
+ * exit code. Everything else belongs to the command, which is why each entry in the table
+ * below is a two-line adapter and not a flag handler.
+ */
+import { booleanFlag, JSON_FLAG, parseArguments, valueFlag } from './args.js';
+import { evaluate } from './commands/eval.js';
+import { generate } from './commands/gen.js';
+import { ingest } from './commands/ingest.js';
+import { init } from './commands/init.js';
+import { validate } from './commands/validate.js';
+import { EXIT_OK, EXIT_USAGE } from './exit.js';
+import { emit } from './output.js';
+import { targetNames } from './targets.js';
+import { commandUsage, globalUsage } from './usage.js';
+const TARGET_FLAG = valueFlag('target', 'name', `generator target; one of ${targetNames().join(', ')}`);
+export const COMMANDS = [
+    {
+        name: 'init',
+        summary: 'scaffold a project: a starter spec and a README',
+        usage: 'init [dir] [--from <spec>] [--target <name>] [--force] [--gen]',
+        flags: [
+            valueFlag('from', 'spec', 'import an existing spec instead of writing the starter'),
+            TARGET_FLAG,
+            booleanFlag('force', 'replace a spec or README that is already there'),
+            booleanFlag('gen', 'generate immediately after scaffolding'),
+            JSON_FLAG,
+        ],
+        run: (context, args) => init(context, {
+            dir: args.positionals[0],
+            from: args.values.get('from'),
+            target: args.values.get('target'),
+            force: args.booleans.has('force'),
+            gen: args.booleans.has('gen'),
+        }),
+    },
+    {
+        name: 'validate',
+        summary: 'parse the spec, build the IR, and run every build-time gate',
+        usage: 'validate [spec]',
+        flags: [JSON_FLAG],
+        run: (context, args) => validate(context, { spec: args.positionals[0] }),
+    },
+    {
+        name: 'gen',
+        summary: 'compile the spec and reconcile the tree with it',
+        usage: 'gen [spec] [--target <name>] [--dry-run] [--force]',
+        flags: [
+            TARGET_FLAG,
+            booleanFlag('dry-run', 'report what would change, and write nothing'),
+            booleanFlag('force', 'overwrite generated files that were edited by hand'),
+            JSON_FLAG,
+        ],
+        run: (context, args) => generate(context, {
+            spec: args.positionals[0],
+            target: args.values.get('target'),
+            dryRun: args.booleans.has('dry-run'),
+            force: args.booleans.has('force'),
+        }),
+    },
+    {
+        name: 'ingest',
+        summary: 'index a retriever corpus into the store the spec declares',
+        usage: 'ingest [spec] [--target <name>] [--retriever <id> | --all] [--dry-run]',
+        flags: [
+            valueFlag('retriever', 'id', 'ingest one declared retriever, by the id the spec used'),
+            booleanFlag('all', 'ingest every retriever the spec declares'),
+            booleanFlag('dry-run', 'report what a run would write, and write nothing'),
+            TARGET_FLAG,
+            JSON_FLAG,
+        ],
+        run: (context, args) => ingest(context, {
+            spec: args.positionals[0],
+            target: args.values.get('target'),
+            retriever: args.values.get('retriever'),
+            all: args.booleans.has('all'),
+            dryRun: args.booleans.has('dry-run'),
+        }),
+    },
+    {
+        name: 'eval',
+        summary: 'run the eval gate, or record the baseline it measures against',
+        usage: 'eval [spec] [--target <name>] [--suite <id>] [--baseline]',
+        flags: [
+            valueFlag('suite', 'id', 'run one eval instead of all of them'),
+            TARGET_FLAG,
+            booleanFlag('baseline', 'record a fresh baseline instead of gating'),
+            JSON_FLAG,
+        ],
+        run: (context, args) => evaluate(context, {
+            spec: args.positionals[0],
+            target: args.values.get('target'),
+            suite: args.values.get('suite'),
+            baseline: args.booleans.has('baseline'),
+        }),
+    },
+];
+function usageError(context, message, usage) {
+    context.stderr(`aid: ${message}\n\n${usage ?? globalUsage(COMMANDS)}`);
+    return EXIT_USAGE;
+}
+/**
+ * Map an unexpected throw onto exit 2. A command that crashed has not judged the project,
+ * so it must not report `1` -- that code means "the project is wrong", and a crash
+ * claiming it would send a reader looking for a spec problem that does not exist.
+ */
+function internalError(context, json, command, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.stderr(`aid: internal error in \`${command}\`: ${message}\n`);
+    if (json) {
+        context.stdout(`${JSON.stringify({ command, ok: false, diagnostics: [] }, null, 2)}\n`);
+    }
+    return EXIT_USAGE;
+}
+export function run(argv, context) {
+    const [name, ...rest] = argv;
+    if (name === undefined || name === '--help' || name === '-h' || name === 'help') {
+        context.stdout(globalUsage(COMMANDS));
+        // No command at all is a usage error; explicitly asking for help is not.
+        return name === undefined ? EXIT_USAGE : EXIT_OK;
+    }
+    const command = COMMANDS.find((candidate) => candidate.name === name);
+    if (command === undefined) {
+        return usageError(context, `unknown command \`${name}\``);
+    }
+    const parsed = parseArguments(rest, command.flags);
+    if (!parsed.ok) {
+        return usageError(context, parsed.message, commandUsage(command));
+    }
+    if (parsed.args.help) {
+        context.stdout(commandUsage(command));
+        return EXIT_OK;
+    }
+    // Every command takes at most one positional (a spec, or the directory to scaffold
+    // into), so the arity rule lives here rather than four times in four commands.
+    if (parsed.args.positionals.length > 1) {
+        return usageError(context, `\`aid ${command.name}\` takes at most one path, got ${parsed.args.positionals.length}`, commandUsage(command));
+    }
+    const json = parsed.args.booleans.has('json');
+    try {
+        return emit(context, json, command.run(context, parsed.args));
+    }
+    catch (error) {
+        return internalError(context, json, command.name, error);
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

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

package/dist/output.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The command's whole result: what to print, what to embed in `--json`, and what to
+ * exit with.
+ *
+ * Commands return this instead of printing and exiting themselves, so that a command
+ * can be asserted on directly and so that `init --gen` can run the generation pipeline
+ * and fold its outcome into its own. `ok` is derived from the exit code rather than
+ * passed alongside it, because two fields that can disagree eventually will.
+ */
+import type { CliContext } from './context.js';
+import type { CliDiagnostic } from './diagnostics.js';
+import type { ExitCode } from './exit.js';
+export interface CommandOutcome {
+    readonly exitCode: ExitCode;
+    /** The `--json` document. */
+    readonly report: Record<string, unknown>;
+    readonly diagnostics: readonly CliDiagnostic[];
+    /** The human rendering on stdout. Empty when there is nothing to say. */
+    readonly text: string;
+    /**
+     * Text a subprocess wrote to its own stderr, carried through to the CLI's stderr.
+     *
+     * `aid eval` is the only user. It cannot be folded into {@link text}: `--json` swaps
+     * stdout for a single JSON document, and an eval that explains on stderr why it could
+     * not measure something would have that explanation dropped by the one mode a machine
+     * reads.
+     */
+    readonly stderr?: string;
+}
+export interface OutcomeInit {
+    readonly command: string;
+    readonly exitCode: ExitCode;
+    readonly fields?: Record<string, unknown>;
+    readonly diagnostics?: readonly CliDiagnostic[];
+    readonly text?: string;
+    readonly stderr?: string;
+}
+export declare function outcome(init: OutcomeInit): CommandOutcome;
+/**
+ * Print an outcome and hand back its exit code.
+ *
+ * Diagnostics go to stderr in both modes. In `--json` mode stdout carries exactly one
+ * JSON document and nothing else, so that `aid ... --json | jq` is always well formed;
+ * the diagnostics are in that document *and* on stderr, which is what a caller piping
+ * stdout wants and what a human watching a terminal wants.
+ */
+export declare function emit(context: CliContext, json: boolean, command: CommandOutcome): ExitCode;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,cAAc,CAczD;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,QAAQ,CAa1F"}

package/dist/output.js

@@ -0,0 +1,50 @@
+/**
+ * The command's whole result: what to print, what to embed in `--json`, and what to
+ * exit with.
+ *
+ * Commands return this instead of printing and exiting themselves, so that a command
+ * can be asserted on directly and so that `init --gen` can run the generation pipeline
+ * and fold its outcome into its own. `ok` is derived from the exit code rather than
+ * passed alongside it, because two fields that can disagree eventually will.
+ */
+import { formatDiagnostics } from '@aid-framework/spec';
+import { EXIT_OK } from './exit.js';
+export function outcome(init) {
+    const diagnostics = init.diagnostics ?? [];
+    return {
+        exitCode: init.exitCode,
+        diagnostics,
+        text: init.text ?? '',
+        ...(init.stderr === undefined ? {} : { stderr: init.stderr }),
+        report: {
+            command: init.command,
+            ok: init.exitCode === EXIT_OK,
+            ...init.fields,
+            diagnostics,
+        },
+    };
+}
+/**
+ * Print an outcome and hand back its exit code.
+ *
+ * Diagnostics go to stderr in both modes. In `--json` mode stdout carries exactly one
+ * JSON document and nothing else, so that `aid ... --json | jq` is always well formed;
+ * the diagnostics are in that document *and* on stderr, which is what a caller piping
+ * stdout wants and what a human watching a terminal wants.
+ */
+export function emit(context, json, command) {
+    if (json) {
+        context.stdout(`${JSON.stringify(command.report, null, 2)}\n`);
+    }
+    else if (command.text !== '') {
+        context.stdout(command.text.endsWith('\n') ? command.text : `${command.text}\n`);
+    }
+    if (command.stderr !== undefined && command.stderr !== '') {
+        context.stderr(command.stderr.endsWith('\n') ? command.stderr : `${command.stderr}\n`);
+    }
+    if (command.diagnostics.length > 0) {
+        context.stderr(formatDiagnostics(command.diagnostics));
+    }
+    return command.exitCode;
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAIxD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;IAC3C,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,WAAW;QACX,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QAC7D,MAAM,EAAE;YACN,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,EAAE,EAAE,IAAI,CAAC,QAAQ,KAAK,OAAO;YAC7B,GAAG,IAAI,CAAC,MAAM;YACd,WAAW;SACZ;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAAC,OAAmB,EAAE,IAAa,EAAE,OAAuB;IAC9E,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC;SAAM,IAAI,OAAO,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC1D,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,OAAO,CAAC,QAAQ,CAAC;AAC1B,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The repository-relative POSIX paths every package in this repository speaks, and the
+ * one place they become operating-system paths.
+ *
+ * A plan's paths, a manifest's records and a generator's path helpers are all
+ * `app/generated/...`, joined with `/`. They are converted at the filesystem boundary
+ * and nowhere else, so no comparison in the CLI can be defeated by a separator.
+ */
+/**
+ * The absolute path `posixPath` names under `root`.
+ *
+ * An absolute path is taken as it is. `aid init --from C:\specs\app.spec.yaml` and
+ * `aid validate /srv/app/app.spec.yaml` are ordinary invocations, and joining an absolute
+ * path onto the working directory does not fail loudly -- it produces a well-formed path
+ * to a file that cannot exist, so the caller reads a "no such file" for a file that is
+ * right there.
+ */
+export declare function absolutePath(root: string, posixPath: string): string;
+/** The parent of a repository-relative POSIX path, or `''` for a top-level one. */
+export declare function parentPath(posixPath: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/paths.js

@@ -0,0 +1,31 @@
+/**
+ * The repository-relative POSIX paths every package in this repository speaks, and the
+ * one place they become operating-system paths.
+ *
+ * A plan's paths, a manifest's records and a generator's path helpers are all
+ * `app/generated/...`, joined with `/`. They are converted at the filesystem boundary
+ * and nowhere else, so no comparison in the CLI can be defeated by a separator.
+ */
+import { isAbsolute, join, resolve } from 'node:path';
+/**
+ * The absolute path `posixPath` names under `root`.
+ *
+ * An absolute path is taken as it is. `aid init --from C:\specs\app.spec.yaml` and
+ * `aid validate /srv/app/app.spec.yaml` are ordinary invocations, and joining an absolute
+ * path onto the working directory does not fail loudly -- it produces a well-formed path
+ * to a file that cannot exist, so the caller reads a "no such file" for a file that is
+ * right there.
+ */
+export function absolutePath(root, posixPath) {
+    if (posixPath === '')
+        return root;
+    if (isAbsolute(posixPath))
+        return resolve(posixPath);
+    return join(root, ...posixPath.split('/'));
+}
+/** The parent of a repository-relative POSIX path, or `''` for a top-level one. */
+export function parentPath(posixPath) {
+    const index = posixPath.lastIndexOf('/');
+    return index === -1 ? '' : posixPath.slice(0, index);
+}
+//# sourceMappingURL=paths.js.map