@aid-framework/cli 0.0.0 → 0.1.48

package/dist/commands/eval.js

@@ -0,0 +1,257 @@
+/**
+ * `aid eval` — run the eval gate, or record the baseline it measures against.
+ *
+ * **What this shells out to, and why.**
+ *
+ * The assignment sketched `uv run python -m aid_runtime.evals ...`, but that module is not
+ * runnable: there is no `__main__.py`, no console script, and no `argparse` anywhere under
+ * `runtimes/python/src/aid_runtime/evals/`. The command it names does not exist.
+ *
+ * What does exist, one per eval, is the module the generator emits:
+ * `app/generated/evals/<id>.py`, with a `main()` that prints `result.summary()` and exits
+ * non-zero when the gate fails. That module is the intended surface -- it is generated code
+ * the spec already declares, and it is what the committed `app/evals/*.baseline.json` was
+ * produced by. So `aid eval` runs `python -m app.generated.evals.<id>` from the project
+ * root, which is also what a person would type by hand.
+ *
+ * The alternative was adding an entry point to `runtimes/`, and that was rejected: the
+ * runtime is a landed layer whose published surface other layers depend on, and the
+ * assignment says not to modify it. A missing runtime entry point is this layer's problem
+ * to route around, not a reason to change a shipped one.
+ *
+ * **`--baseline` delegates the sampling.** The gate is statistical (`maxRegression` against
+ * a stored distribution), so a baseline from a single run is noise shaped like a fact. The
+ * generated module's `run()` already samples the dataset `SAMPLES` times -- the N the spec
+ * declares -- so recording a baseline calls that, then the runtime's own documented recipe
+ * (`EvalBaseline.from_run(await run(), model=...).to_json()`, which is literally the string
+ * in the generated `load_baseline`'s error message). Re-sampling here would invent a second
+ * N and let the CLI and the module disagree about how many runs a baseline means.
+ *
+ * That recipe is the one place in the CLI that writes Python. It is a script piped to the
+ * interpreter over stdin rather than an API call because the runtime has no such entry
+ * point, and it is deliberately short: anything longer would be this layer reimplementing
+ * the runtime's measurement.
+ */
+import { existsSync } from 'node:fs';
+import { sortDiagnostics } 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 { absolutePath } from '../paths.js';
+import { lowerSpec, readSpec } from '../pipeline.js';
+import { discoverInterpreter, INTERPRETERS, interpreterCommand, invoke } from '../python.js';
+import { resolveTarget, unknownTargetDiagnostic } from '../targets.js';
+/** Eval ids the spec declares, or the diagnostics that stopped it from declaring any. */
+function declaredSuites(text, specPath) {
+    const lowered = lowerSpec(text, specPath);
+    if (!lowered.ok)
+        return { ok: false, diagnostics: lowered.diagnostics };
+    const ir = lowered.ir;
+    return {
+        ok: true,
+        ids: ir.evals.map((entry) => entry.id),
+        warnings: lowered.diagnostics,
+    };
+}
+/**
+ * The baseline recorder, run as `python -`. `python` puts the current directory on
+ * `sys.path`, so `import app.generated.evals.<id>` resolves against the project root and
+ * each module's own `BASELINE_PATH` decides where its baseline goes -- the same path
+ * `load_baseline()` reads back, because it is the same constant.
+ */
+function baselineScript(modules) {
+    return [
+        'import asyncio',
+        'import importlib',
+        'import pathlib',
+        '',
+        'from aid_runtime.evals import EvalBaseline',
+        '',
+        `MODULES = ${JSON.stringify(modules)}`,
+        '',
+        'for name in MODULES:',
+        '    module = importlib.import_module(name)',
+        '    # run() already samples the dataset SAMPLES times, the N the spec declares.',
+        '    baseline = EvalBaseline.from_run(',
+        '        asyncio.run(module.run()),',
+        '        model=module.MODEL,',
+        "        note='recorded by `aid eval --baseline`',",
+        '    )',
+        '    path = pathlib.Path(module.BASELINE_PATH)',
+        '    path.parent.mkdir(parents=True, exist_ok=True)',
+        '    path.write_text(baseline.to_json(), encoding="utf-8")',
+        '    print(f"wrote {path}")',
+        '',
+    ].join('\n');
+}
+export function evaluate(context, options) {
+    const command = 'eval';
+    const target = resolveTarget(options.target);
+    if (target === undefined) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            diagnostics: [unknownTargetDiagnostic(options.target ?? '')],
+        });
+    }
+    const specPath = options.spec ?? target.specPath;
+    const fields = { target: target.name, spec: specPath, suite: options.suite ?? null };
+    const read = readSpec(context, specPath);
+    if (!read.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: read.diagnostics });
+    }
+    const declared = declaredSuites(read.text, specPath);
+    if (!declared.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: declared.diagnostics });
+    }
+    // `--suite` is checked against the ids the spec declares, not against filenames on
+    // disk: the set of evals is a property of the spec, so a typo is a usage error and
+    // should say which ids exist.
+    if (options.suite !== undefined && !declared.ids.includes(options.suite)) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            fields,
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.suiteNotFound,
+                    message: `No eval named "${options.suite}" in ${specPath}.`,
+                    path: [specPath],
+                    hint: declared.ids.length > 0
+                        ? `Declared evals: ${declared.ids.join(', ')}.`
+                        : 'The spec declares no evals.',
+                }),
+            ],
+        });
+    }
+    const suites = options.suite === undefined ? declared.ids : [options.suite];
+    const missing = suites.filter((id) => !existsSync(absolutePath(context.cwd, target.evalModuleFile(id))));
+    if (missing.length > 0) {
+        return outcome({
+            command,
+            exitCode: EXIT_FAILURE,
+            fields: { ...fields, suites },
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.evalModulesMissing,
+                    message: `No generated eval module for ${missing.map((id) => `"${id}"`).join(', ')}.`,
+                    path: missing.map((id) => target.evalModuleFile(id)),
+                    hint: 'Run `aid gen`: the evals that run are the modules the generator emits.',
+                }),
+            ],
+        });
+    }
+    if (target.runner !== 'python') {
+        return outcome({
+            command,
+            // Exit 2, not 1: this command has no runner for this target, so no eval ran and
+            // nothing about the project was judged. `1` would read as "the evals failed".
+            exitCode: EXIT_USAGE,
+            fields: { ...fields, suites },
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.runnerUnsupported,
+                    message: `\`aid eval\` runs generated Python modules, and ${target.name} emits TypeScript.`,
+                    hint: 'The emitted eval module exports `sample()` and `evaluate(run, baseline)`; run it with Node.',
+                }),
+            ],
+        });
+    }
+    const interpreter = discoverInterpreter(context);
+    if (interpreter === undefined) {
+        return outcome({
+            command,
+            // Exit 2, not 1: nothing about the project was judged. The gate has no verdict when
+            // the thing that would run it cannot start, and `1` would read as "the evals failed".
+            exitCode: EXIT_USAGE,
+            fields: { ...fields, suites },
+            diagnostics: [
+                cliError({
+                    code: CLI_DIAGNOSTIC_CODES.pythonMissing,
+                    message: `No interpreter could import aid_runtime (tried ${INTERPRETERS.join(', ')}).`,
+                    hint: 'Install the runtime into the interpreter you run with, or run the generated eval modules yourself.',
+                }),
+            ],
+        });
+    }
+    const modules = suites.map((id) => target.evalModule(id));
+    const base = interpreterCommand(interpreter);
+    const common = { ...fields, suites, interpreter };
+    if (options.baseline) {
+        const recorded = invoke(context, [...base, '-'], baselineScript(modules));
+        if (recorded === undefined || recorded.status !== 0) {
+            return outcome({
+                command,
+                exitCode: EXIT_FAILURE,
+                fields: common,
+                diagnostics: [
+                    cliError({
+                        code: CLI_DIAGNOSTIC_CODES.runnerFailed,
+                        message: `Could not record a baseline with ${interpreter}.`,
+                        hint: 'Recording a baseline runs the evals, so it needs whatever they need; see the output for why they did not run.',
+                    }),
+                ],
+                text: recorded?.stdout.trimEnd() ?? '',
+                stderr: recorded?.stderr ?? '',
+            });
+        }
+        return outcome({
+            command,
+            exitCode: EXIT_OK,
+            fields: common,
+            text: recorded.stdout.trimEnd(),
+            stderr: recorded.stderr,
+        });
+    }
+    const results = [];
+    const output = [];
+    const spoken = [];
+    const diagnostics = [...declared.warnings];
+    for (const [index, module] of modules.entries()) {
+        const run = invoke(context, [...base, '-m', module]);
+        if (run === undefined) {
+            return outcome({
+                command,
+                exitCode: EXIT_USAGE,
+                fields: common,
+                diagnostics: [
+                    cliError({
+                        code: CLI_DIAGNOSTIC_CODES.runnerFailed,
+                        message: `Could not start ${interpreter} to run "${module}".`,
+                    }),
+                ],
+            });
+        }
+        const suite = suites[index] ?? module;
+        results.push({ suite, module, status: run.status ?? EXIT_FAILURE });
+        if (run.stdout.trim() !== '')
+            output.push(run.stdout.trimEnd());
+        // The generated `main()` prints its summary to stdout and exits non-zero on a
+        // regression; anything on stderr is the eval reporting something that did not fit in
+        // a metric. It is surfaced rather than swallowed, because a gate that hides what it
+        // could not measure is a gate that passes for the wrong reason -- and it is surfaced
+        // on stderr, including under `--json`, because that is where the process that wrote it
+        // wrote it, and `--json` replaces stdout with a document rather than with nothing.
+        if (run.stderr.trim() !== '') {
+            spoken.push(run.stderr.trimEnd());
+            diagnostics.push(cliWarning({
+                code: CLI_DIAGNOSTIC_CODES.runnerWarned,
+                message: `"${suite}" wrote to stderr.`,
+            }));
+        }
+    }
+    // A non-zero exit from a generated module *is* the gate's verdict, so it propagates
+    // rather than being reinterpreted here. The CLI reports the gate; it has no opinion
+    // about the numbers, and forming one would be the second implementation of the gate
+    // that this layer exists to avoid.
+    const failed = results.some((result) => result.status !== 0);
+    return outcome({
+        command,
+        exitCode: failed ? EXIT_FAILURE : EXIT_OK,
+        fields: { ...common, results },
+        diagnostics: sortDiagnostics(diagnostics),
+        text: output.join('\n'),
+        stderr: spoken.join('\n'),
+    });
+}
+//# sourceMappingURL=eval.js.map

package/dist/commands/eval.js.map

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

package/dist/commands/gen.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `aid gen` — compile the spec and reconcile the tree with it.
+ *
+ * Every decision about *what* changes belongs to `@aid-framework/generator-sdk`: `planRegeneration`
+ * decides the actions, `regenerate` applies them, and the drift rule that refuses to
+ * overwrite an edited generated file is the SDK's. The CLI decides four things and
+ * nothing else: which target, which spec, whether to write, and what the run's exit code
+ * means. In particular it does not re-derive ownership, re-hash a file, or re-implement
+ * drift -- two implementations of that rule would eventually disagree, and the one that
+ * disagreed would be the one holding a developer's edits.
+ *
+ * One deliberate divergence from `generate-example.mjs`, noted because it is a choice: the
+ * manifest is written even when the run reports drift. `regenerate` records the *previous*
+ * hash for a file it refused to overwrite, so a run that refuses an edit and a run that
+ * discards one cannot disagree about what is on the tree; skipping the manifest write
+ * instead leaves files that this run did create unrecorded, and the next run then reports
+ * those as drift even though the generator was the one that wrote them.
+ */
+import type { RegenerationReport } from '@aid-framework/generator-sdk';
+import type { CliContext } from '../context.js';
+import type { CliDiagnostic } from '../diagnostics.js';
+import type { CommandOutcome } from '../output.js';
+import type { Target } from '../targets.js';
+export interface GenerateOptions {
+    readonly spec: string | undefined;
+    readonly target: string | undefined;
+    readonly dryRun: boolean;
+    readonly force: boolean;
+}
+/** A spec that compiled and a plan that was reconciled, or the reason it was not. */
+export interface GenerateSuccess {
+    readonly target: Target;
+    readonly specPath: string;
+    readonly report: RegenerationReport;
+    readonly warnings: readonly CliDiagnostic[];
+    readonly dryRun: boolean;
+    readonly force: boolean;
+    readonly manifestWritten: boolean;
+}
+/** The public entry point, and the one `aid init --gen` folds into its own report. */
+export declare function generate(context: CliContext, options: GenerateOptions): CommandOutcome;
+//# sourceMappingURL=gen.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gen.d.ts","sourceRoot":"","sources":["../../src/commands/gen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAYvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAG5C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAwED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAEtF"}

package/dist/commands/gen.js

@@ -0,0 +1,138 @@
+/**
+ * `aid gen` — compile the spec and reconcile the tree with it.
+ *
+ * Every decision about *what* changes belongs to `@aid-framework/generator-sdk`: `planRegeneration`
+ * decides the actions, `regenerate` applies them, and the drift rule that refuses to
+ * overwrite an edited generated file is the SDK's. The CLI decides four things and
+ * nothing else: which target, which spec, whether to write, and what the run's exit code
+ * means. In particular it does not re-derive ownership, re-hash a file, or re-implement
+ * drift -- two implementations of that rule would eventually disagree, and the one that
+ * disagreed would be the one holding a developer's edits.
+ *
+ * One deliberate divergence from `generate-example.mjs`, noted because it is a choice: the
+ * manifest is written even when the run reports drift. `regenerate` records the *previous*
+ * hash for a file it refused to overwrite, so a run that refuses an edit and a run that
+ * discards one cannot disagree about what is on the tree; skipping the manifest write
+ * instead leaves files that this run did create unrecorded, and the next run then reports
+ * those as drift even though the generator was the one that wrote them.
+ */
+import { createNodeSink, formatRegenerationSummary, hasDrift, planRegeneration, regenerate, rejectionPath, serializeAidManifest, } from '@aid-framework/generator-sdk';
+import { hasErrors, sortDiagnostics } from '@aid-framework/spec';
+import { EXIT_FAILURE, EXIT_OK, EXIT_USAGE } from '../exit.js';
+import { outcome } from '../output.js';
+import { compile, provenanceFor, readManifest, readSpec } from '../pipeline.js';
+import { resolveTarget, unknownTargetDiagnostic } from '../targets.js';
+function lines(label, paths) {
+    if (paths.length === 0)
+        return [];
+    return [label, ...paths.map((path) => `  ${path}`)];
+}
+function render(context, options) {
+    const command = 'gen';
+    const target = resolveTarget(options.target);
+    if (target === undefined) {
+        return outcome({
+            command,
+            exitCode: EXIT_USAGE,
+            diagnostics: [unknownTargetDiagnostic(options.target ?? '')],
+        });
+    }
+    const specPath = options.spec ?? target.specPath;
+    const fields = { target: target.name, spec: specPath };
+    const read = readSpec(context, specPath);
+    if (!read.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: read.diagnostics });
+    }
+    const compiled = compile(read.text, specPath, target);
+    if (!compiled.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: compiled.diagnostics });
+    }
+    const sink = createNodeSink(context.cwd);
+    const manifest = readManifest(sink, target);
+    if (!manifest.ok) {
+        return outcome({ command, exitCode: EXIT_FAILURE, fields, diagnostics: manifest.diagnostics });
+    }
+    const reconciliation = { sink, manifest: manifest.manifest, force: options.force };
+    if (options.dryRun) {
+        // A dry run takes the branch in which no write call exists at all, rather than the
+        // branch that writes and is then trusted not to. `planRegeneration` is the SDK's
+        // planner without its writer, so "writes nothing" is a property of the code path
+        // and not a promise in a comment.
+        return summarize({
+            target,
+            specPath,
+            report: planRegeneration(compiled.plan, reconciliation),
+            warnings: compiled.diagnostics,
+            dryRun: true,
+            force: options.force,
+            manifestWritten: false,
+        });
+    }
+    const applied = regenerate(compiled.plan, {
+        ...reconciliation,
+        provenance: provenanceFor(target, compiled.ir),
+    });
+    sink.write(target.manifestPath, serializeAidManifest(applied.manifest));
+    return summarize({
+        target,
+        specPath,
+        report: applied.report,
+        warnings: compiled.diagnostics,
+        dryRun: false,
+        force: options.force,
+        manifestWritten: true,
+    });
+}
+/** The public entry point, and the one `aid init --gen` folds into its own report. */
+export function generate(context, options) {
+    return render(context, options);
+}
+function summarize(success) {
+    const { report, target, specPath, warnings, dryRun, force, manifestWritten } = success;
+    const diagnostics = sortDiagnostics([...warnings, ...report.diagnostics]);
+    // Two ways to fail, and neither is redundant. `hasErrors` is the SDK's verdict on the
+    // run; `hasDrift` is checked alongside it rather than instead of it because drift is
+    // reported as an error today, and a gate that would stop failing if that changed is not
+    // a gate -- and drift is the one failure that silently destroys a developer's edits.
+    // `--force` is the caller answering it, so a run that discarded the edits did what it
+    // was told and exits 0; only an unforced run leaves drift outstanding.
+    const failed = hasErrors(diagnostics) || (!force && hasDrift(report));
+    const text = [
+        `${target.name}: ${dryRun ? 'dry run, ' : ''}${formatRegenerationSummary(report)}`,
+    ];
+    text.push(...lines('created:', report.created));
+    text.push(...lines('updated:', report.updated));
+    if (report.drifted.length > 0) {
+        text.push(dryRun ? 'would refuse to overwrite:' : 'refused to overwrite, the new content is beside it:');
+        for (const drift of report.drifted) {
+            text.push(`  ${drift.path}  ->  ${rejectionPath(drift.path)}`);
+        }
+    }
+    text.push(...lines('no longer generated:', report.stale));
+    return outcome({
+        command: 'gen',
+        exitCode: failed ? EXIT_FAILURE : EXIT_OK,
+        diagnostics,
+        text: text.join('\n'),
+        fields: {
+            target: target.name,
+            spec: specPath,
+            dryRun,
+            manifest: { path: target.manifestPath, written: manifestWritten },
+            changes: {
+                created: report.created,
+                updated: report.updated,
+                unchanged: report.unchanged,
+                kept: report.kept,
+                // Paths, like every sibling here: the report answers "which files", and the
+                // rejected content is on disk at the deterministic `rejectionPath` the human
+                // summary prints. Mixing record objects into one entry and strings into the rest
+                // makes the one shape a consumer has to special-case the one about conflicts.
+                conflicts: report.drifted.map((file) => file.path),
+                stale: report.stale,
+                pruned: report.pruned,
+            },
+        },
+    });
+}
+//# sourceMappingURL=gen.js.map

package/dist/commands/gen.js.map

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

package/dist/commands/ingest.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `aid ingest` -- run the generated ingest entry point for a retriever's corpus.
+ *
+ * **What this shells out to, and why.** Indexing is a batch job, not a request, so the
+ * generator emits one runnable module per declared retriever at
+ * `app/generated/retrieval/ingest/<id>.py`, with a `main()` that chunks, embeds and writes
+ * the corpus. That module is the interface: it already knows the chunking and the store the
+ * spec declared, and re-deriving either here would be a second implementation of the
+ * runtime's rules. So the command runs `python -m app.generated.retrieval.ingest.<id>` from
+ * the project root, which is also what a person would type by hand.
+ *
+ * **The flag shape is a usage error, not a project verdict.** `--retriever` and `--all` are
+ * the two ways to say what to ingest; passing both, or neither, is a mistake in the
+ * invocation and exits 2 before the spec is even read. An id the spec does not declare is
+ * the same kind of mistake, and its message names the ids that do exist -- a typo should
+ * not require opening the spec.
+ *
+ * **A missing module is a failure, not a usage error.** `--retriever handbook` in a project
+ * that has never been generated is a well-formed command that cannot do its job; it exits 1
+ * and points at `aid gen`. Exit 2 would tell a script that it passed the wrong arguments,
+ * which is false and hides the one action that fixes it.
+ *
+ * **`--dry-run` is forwarded, not implemented here.** The generated module already grows
+ * its own `--dry-run`, which applies the chunker and reports the counts a real run would
+ * write without opening a store or calling an embedder. Answering the same question in
+ * the CLI would mean re-chunking the corpus, and a second dry run that drifted from the
+ * one the module performs is worse than no dry run at all.
+ *
+ * **Idempotence is the runtime's, not a rescan this command performs.** A chunk id is a
+ * content hash, and the store upserts on it, so a second run over unchanged documents
+ * replaces rather than appends. The CLI adds no diffing of its own: it would have to
+ * reimplement the chunker to know what changed.
+ */
+import type { CliContext } from '../context.js';
+import type { CommandOutcome } from '../output.js';
+export interface IngestOptions {
+    readonly spec: string | undefined;
+    readonly target: string | undefined;
+    readonly retriever: string | undefined;
+    readonly all: boolean;
+    readonly dryRun: boolean;
+}
+export declare function ingest(context: CliContext, options: IngestOptions): CommandOutcome;
+//# sourceMappingURL=ingest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/commands/ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAOnD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AA+CD,wBAAgB,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,GAAG,cAAc,CAiLlF"}