agent-scenario-loop 0.1.0

package/dist/runner/check-plan.d.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+type CliArgs = {
+    providers: string[];
+    scenario?: string | boolean;
+    runner?: string | boolean;
+    platform?: string | boolean;
+    out?: string | boolean;
+    'run-id'?: string | boolean;
+    [key: string]: string | boolean | string[] | undefined;
+};
+type PlanArtifacts = {
+    compatibility: Record<string, unknown>;
+    health: Record<string, unknown>;
+    verdict: Record<string, unknown>;
+    agentSummary: string;
+};
+/**
+ * Prints CLI usage to stderr.
+ *
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Parses the small flag surface for the plan-check CLI.
+ *
+ * @param {string[]} argv
+ * @returns {{providers: string[], [key: string]: string | boolean | string[]}}
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Builds pre-execution planner artifacts from validated scenario and runner manifests.
+ *
+ * @param {{scenarioPath: string, runnerPath: string, providerPaths?: string[], platform?: string | null, runId?: string}} options
+ * @returns {Promise<{compatibility: Record<string, unknown>, health: Record<string, unknown>, verdict: Record<string, unknown>, agentSummary: string}>}
+ */
+declare function buildPlanArtifacts({ scenarioPath, runnerPath, providerPaths, platform, runId, }: {
+    scenarioPath: string;
+    runnerPath: string;
+    providerPaths?: string[];
+    platform?: string | null;
+    runId?: string;
+}): Promise<PlanArtifacts>;
+export { buildPlanArtifacts, parseArgs, usage, };

package/dist/runner/check-plan.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPlanArtifacts = buildPlanArtifacts;
+exports.parseArgs = parseArgs;
+exports.usage = usage;
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { buildAgentSummaryMarkdown } = require('../core/agent-summary');
+const { createArtifactLayout } = require('../core/artifact-layout');
+const { writeJsonArtifact, writeTextArtifact } = require('../core/artifact-writer');
+const { buildCompatibilityHealth, buildUnevaluatedVerdict, evaluateRunnerCompatibility, } = require('../core/planner');
+const { SCHEMAS, SchemaValidationError, assertValidJson, } = require('../core/schema-validator');
+const { hasHelpFlag, writeUsage } = require('./cli');
+/**
+ * Prints CLI usage to stderr.
+ *
+ * @returns {void}
+ */
+function usage(output = process.stderr) {
+    writeUsage([
+        'Usage: agent-scenario-loop --scenario <path> --runner <path> [--provider <path> ...] [--platform <ios|android>] [--run-id <id>] [--out <dir>]',
+        '',
+        'Aliases: asl-check-plan',
+        'Writes health.json and verdict.json to --out when provided.',
+        'Without --out, prints the planned artifacts as JSON.',
+    ], output);
+}
+/**
+ * Parses the small flag surface for the plan-check CLI.
+ *
+ * @param {string[]} argv
+ * @returns {{providers: string[], [key: string]: string | boolean | string[]}}
+ */
+function parseArgs(argv) {
+    const args = {
+        providers: [],
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token) {
+            continue;
+        }
+        if (!token.startsWith('--')) {
+            continue;
+        }
+        const key = token.slice(2);
+        if (key === 'provider') {
+            const value = argv[index + 1];
+            if (value && !value.startsWith('--')) {
+                args.providers.push(value);
+                index += 1;
+            }
+            continue;
+        }
+        const value = argv[index + 1];
+        if (value && !value.startsWith('--')) {
+            args[key] = value;
+            index += 1;
+        }
+        else {
+            args[key] = true;
+        }
+    }
+    return args;
+}
+/**
+ * Reads a JSON file and reports parse failures with the manifest label.
+ *
+ * @param {string} filePath
+ * @param {string} [label]
+ * @returns {unknown}
+ */
+function readJson(filePath, label) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        const prefix = label ? `${label} ` : '';
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${prefix}could not be parsed as JSON: ${filePath}\n${message}`);
+    }
+}
+/**
+ * Reads a JSON file and validates it against a public contract schema.
+ *
+ * @param {string} filePath
+ * @param {Record<string, unknown>} schema
+ * @param {string} label
+ * @returns {unknown}
+ */
+function readValidatedJson(filePath, schema, label) {
+    return assertValidJson(readJson(filePath, label), schema, label);
+}
+/**
+ * Creates a short random run id for ad-hoc plan checks.
+ *
+ * @returns {string}
+ */
+function createRunId() {
+    return crypto.randomBytes(6).toString('hex');
+}
+/**
+ * Builds pre-execution planner artifacts from validated scenario and runner manifests.
+ *
+ * @param {{scenarioPath: string, runnerPath: string, providerPaths?: string[], platform?: string | null, runId?: string}} options
+ * @returns {Promise<{compatibility: Record<string, unknown>, health: Record<string, unknown>, verdict: Record<string, unknown>, agentSummary: string}>}
+ */
+async function buildPlanArtifacts({ scenarioPath, runnerPath, providerPaths = [], platform = null, runId = createRunId(), }) {
+    const scenario = readValidatedJson(path.resolve(scenarioPath), SCHEMAS.scenario, 'Scenario manifest');
+    const runner = readValidatedJson(path.resolve(runnerPath), SCHEMAS.runnerCapabilities, 'Runner capability manifest');
+    const evidenceProviders = providerPaths.map((providerPath, index) => readValidatedJson(path.resolve(providerPath), SCHEMAS.runnerCapabilities, `Evidence provider manifest ${index + 1}`));
+    const compatibility = evaluateRunnerCompatibility({
+        scenario,
+        runner,
+        evidenceProviders,
+        platform,
+    });
+    const health = buildCompatibilityHealth({
+        scenario,
+        runId,
+        compatibility,
+    });
+    const verdict = buildUnevaluatedVerdict({
+        scenario,
+        runId,
+        health,
+    });
+    const agentSummary = buildAgentSummaryMarkdown({
+        health,
+        verdict,
+    });
+    assertValidJson(health, SCHEMAS.health, 'Health artifact');
+    assertValidJson(verdict, SCHEMAS.verdict, 'Verdict artifact');
+    return {
+        agentSummary,
+        compatibility,
+        health,
+        verdict,
+    };
+}
+/**
+ * Runs the check-plan CLI.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+    const argv = process.argv.slice(2);
+    if (hasHelpFlag(argv)) {
+        usage(process.stdout);
+        return;
+    }
+    const args = parseArgs(argv);
+    if (typeof args.scenario !== 'string' || typeof args.runner !== 'string') {
+        usage();
+        process.exitCode = 1;
+        return;
+    }
+    const artifacts = await buildPlanArtifacts({
+        scenarioPath: args.scenario,
+        runnerPath: args.runner,
+        providerPaths: args.providers,
+        platform: typeof args.platform === 'string' ? args.platform : null,
+        ...(typeof args['run-id'] === 'string' ? { runId: args['run-id'] } : {}),
+    });
+    if (typeof args.out === 'string' && args.out.length > 0) {
+        const outputDir = path.resolve(args.out);
+        const layout = createArtifactLayout({ outputDir });
+        await writeJsonArtifact({
+            filePath: layout.health,
+            value: artifacts.health,
+            schema: SCHEMAS.health,
+            label: 'Health artifact',
+        });
+        await writeJsonArtifact({
+            filePath: layout.verdict,
+            value: artifacts.verdict,
+            schema: SCHEMAS.verdict,
+            label: 'Verdict artifact',
+        });
+        await writeJsonArtifact({
+            filePath: layout.plannerCompatibility,
+            value: artifacts.compatibility,
+            schema: {
+                type: 'object',
+                additionalProperties: true,
+            },
+            label: 'Planner compatibility artifact',
+        });
+        await writeTextArtifact({
+            filePath: layout.agentSummary,
+            content: artifacts.agentSummary,
+        });
+        process.stdout.write(`${outputDir}\n`);
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(artifacts, null, 2)}\n`);
+}
+if (require.main === module) {
+    main().catch((error) => {
+        if (error instanceof SchemaValidationError) {
+            console.error(error.message);
+        }
+        else {
+            console.error(error instanceof Error ? error.message : String(error));
+        }
+        process.exitCode = 1;
+    });
+}

package/dist/runner/cli.d.ts

@@ -0,0 +1,20 @@
+type UsageOutput = {
+    write: (message: string) => unknown;
+};
+/**
+ * Returns true when argv asks for CLI help.
+ *
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+declare function hasHelpFlag(argv: string[]): boolean;
+/**
+ * Writes newline-terminated usage text to the chosen output stream.
+ *
+ * @param {string[]} lines
+ * @param {UsageOutput} [output]
+ * @returns {void}
+ */
+declare function writeUsage(lines: string[], output?: UsageOutput): void;
+export { hasHelpFlag, writeUsage, };
+export type { UsageOutput, };

package/dist/runner/cli.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasHelpFlag = hasHelpFlag;
+exports.writeUsage = writeUsage;
+/**
+ * Returns true when argv asks for CLI help.
+ *
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+function hasHelpFlag(argv) {
+    return argv.includes('--help') || argv.includes('-h');
+}
+/**
+ * Writes newline-terminated usage text to the chosen output stream.
+ *
+ * @param {string[]} lines
+ * @param {UsageOutput} [output]
+ * @returns {void}
+ */
+function writeUsage(lines, output = process.stderr) {
+    output.write(`${lines.join('\n')}\n`);
+}

package/dist/runner/compare-latest.d.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import type { RunIndex, RunIndexEntry } from '../core/run-index';
+type CompareLatestOptions = {
+    comparisonLane?: string;
+    currentDir: string;
+    rootDir: string;
+    scenarioId: string;
+};
+type CompareLatestResult = {
+    baselineDir: string;
+    comparison: Record<string, unknown>;
+    currentDir: string;
+};
+type LatestTrustedSelection = {
+    artifactRoot: string;
+    candidatesInspected: number;
+    scenarioId: string;
+    selectedRunDir: string;
+    selectedRunId: string;
+    skippedCurrentRun: boolean;
+    comparisonLane?: string;
+    scenarioHash?: string;
+    trustedCandidates: number;
+    trustedComparableCandidates?: number;
+    trustedScenarioContractCandidates?: number;
+    trustedPriorCandidates: number;
+};
+/**
+ * Prints CLI usage to stderr.
+ *
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Validates that the current run can be compared against trusted historical evidence.
+ *
+ * @param {{currentDir: string, scenarioId: string}} options
+ * @returns {{health: Record<string, unknown>, verdict: Record<string, unknown>}}
+ */
+declare function assertComparableCurrentRun({ currentDir, scenarioId, }: {
+    currentDir: string;
+    scenarioId: string;
+}): {
+    health: Record<string, unknown>;
+    verdict: Record<string, unknown>;
+};
+/**
+ * Returns whether a historical run used the same scenario contract as the current run.
+ * Runs without a current scenario hash keep legacy behavior for old artifacts.
+ *
+ * @param {RunIndexEntry} entry
+ * @param {string | undefined} scenarioHash
+ * @returns {boolean}
+ */
+declare function isComparableScenarioContract(entry: RunIndexEntry, scenarioHash: string | undefined): boolean;
+/**
+ * Finds the newest trusted run for a scenario while excluding the current run directory.
+ *
+ * @param {{index: RunIndex, scenarioId: string, currentDir: string, comparisonLane?: string, scenarioHash?: string}} options
+ * @returns {RunIndexEntry | null}
+ */
+declare function findLatestTrustedPriorRun({ comparisonLane, index, scenarioHash, scenarioId, currentDir, }: {
+    comparisonLane?: string;
+    index: RunIndex;
+    scenarioHash?: string;
+    scenarioId: string;
+    currentDir: string;
+}): RunIndexEntry | null;
+/**
+ * Builds stable provenance for the latest-trusted baseline selection.
+ *
+ * @param {{baseline: RunIndexEntry, comparisonLane?: string, currentDir: string, index: RunIndex, rootDir: string, scenarioHash?: string, scenarioId: string}} options
+ * @returns {LatestTrustedSelection}
+ */
+declare function buildLatestTrustedSelection({ baseline, comparisonLane, currentDir, index, rootDir, scenarioHash, scenarioId, }: {
+    baseline: RunIndexEntry;
+    comparisonLane?: string;
+    currentDir: string;
+    index: RunIndex;
+    rootDir: string;
+    scenarioHash?: string;
+    scenarioId: string;
+}): LatestTrustedSelection;
+/**
+ * Builds a comparison against the latest trusted prior run in an artifact root.
+ *
+ * @param {CompareLatestOptions} options
+ * @returns {CompareLatestResult}
+ */
+declare function compareLatestTrustedRun({ comparisonLane, currentDir, rootDir, scenarioId, }: CompareLatestOptions): CompareLatestResult;
+/**
+ * Runs the compare-latest CLI.
+ *
+ * @returns {Promise<void>}
+ */
+declare function main(): Promise<void>;
+export { assertComparableCurrentRun, buildLatestTrustedSelection, compareLatestTrustedRun, findLatestTrustedPriorRun, isComparableScenarioContract, main, usage, };

package/dist/runner/compare-latest.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertComparableCurrentRun = assertComparableCurrentRun;
+exports.buildLatestTrustedSelection = buildLatestTrustedSelection;
+exports.compareLatestTrustedRun = compareLatestTrustedRun;
+exports.findLatestTrustedPriorRun = findLatestTrustedPriorRun;
+exports.isComparableScenarioContract = isComparableScenarioContract;
+exports.main = main;
+exports.usage = usage;
+const path = require('node:path');
+const { buildAgentSummaryMarkdown } = require('../core/agent-summary');
+const { compareRunDirectories, readRunArtifacts } = require('../core/comparison');
+const { buildRunIndex, readRunIndexEntry } = require('../core/run-index');
+const { writeJsonArtifact, writeTextArtifact } = require('../core/artifact-writer');
+const { SCHEMAS } = require('../core/schema-validator');
+const { hasHelpFlag, writeUsage } = require('./cli');
+const { assertNoRegressedComparison, isEnabledFlag, parseArgs, resolveOutput } = require('./compare');
+/**
+ * Prints CLI usage to stderr.
+ *
+ * @returns {void}
+ */
+function usage(output = process.stderr) {
+    writeUsage([
+        'Usage: asl-compare-latest --root <artifact-root> --scenario <id> --current <run-dir> [--comparison-lane <id>] [--out <comparison.json|run-dir>] [--fail-on-regression]',
+        '',
+        'Finds the latest trusted prior run for the scenario, then compares it with the current run.',
+        'A trusted prior run must have passed health and passed verdict artifacts.',
+        'The current run must pass scenario health before timing or budget comparison is allowed.',
+        'Use --fail-on-regression to exit nonzero after writing evidence when comparisonStatus is worse.',
+    ], output);
+}
+/**
+ * Returns the scenario id recorded by a run artifact set.
+ *
+ * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>}} artifacts
+ * @returns {string}
+ */
+function readScenarioId(artifacts) {
+    return String(artifacts.health.scenarioId ?? artifacts.verdict.scenarioId ?? 'unknown-scenario');
+}
+/**
+ * Validates that the current run can be compared against trusted historical evidence.
+ *
+ * @param {{currentDir: string, scenarioId: string}} options
+ * @returns {{health: Record<string, unknown>, verdict: Record<string, unknown>}}
+ */
+function assertComparableCurrentRun({ currentDir, scenarioId, }) {
+    const current = readRunArtifacts(currentDir);
+    if (current.health.healthStatus !== 'passed') {
+        throw new Error(`Current run health did not pass: ${currentDir}`);
+    }
+    const currentScenarioId = readScenarioId(current);
+    if (currentScenarioId !== scenarioId) {
+        throw new Error(`Current run scenario '${currentScenarioId}' does not match requested scenario '${scenarioId}'.`);
+    }
+    return current;
+}
+/**
+ * Returns whether a historical run belongs to the requested comparison lane.
+ * Runs without an explicit lane are compared only with other unlabeled runs.
+ *
+ * @param {RunIndexEntry} entry
+ * @param {string | undefined} comparisonLane
+ * @returns {boolean}
+ */
+function isComparableLane(entry, comparisonLane) {
+    return comparisonLane ? entry.comparisonLane === comparisonLane : entry.comparisonLane === undefined;
+}
+/**
+ * Returns whether a historical run used the same scenario contract as the current run.
+ * Runs without a current scenario hash keep legacy behavior for old artifacts.
+ *
+ * @param {RunIndexEntry} entry
+ * @param {string | undefined} scenarioHash
+ * @returns {boolean}
+ */
+function isComparableScenarioContract(entry, scenarioHash) {
+    return scenarioHash ? entry.scenarioHash === scenarioHash : true;
+}
+/**
+ * Finds the newest trusted run for a scenario while excluding the current run directory.
+ *
+ * @param {{index: RunIndex, scenarioId: string, currentDir: string, comparisonLane?: string, scenarioHash?: string}} options
+ * @returns {RunIndexEntry | null}
+ */
+function findLatestTrustedPriorRun({ comparisonLane, index, scenarioHash, scenarioId, currentDir, }) {
+    const resolvedCurrentDir = path.resolve(currentDir);
+    return index.trusted.find((entry) => (entry.scenarioId === scenarioId &&
+        isComparableLane(entry, comparisonLane) &&
+        isComparableScenarioContract(entry, scenarioHash) &&
+        path.resolve(entry.runDir) !== resolvedCurrentDir)) ?? null;
+}
+/**
+ * Builds stable provenance for the latest-trusted baseline selection.
+ *
+ * @param {{baseline: RunIndexEntry, comparisonLane?: string, currentDir: string, index: RunIndex, rootDir: string, scenarioHash?: string, scenarioId: string}} options
+ * @returns {LatestTrustedSelection}
+ */
+function buildLatestTrustedSelection({ baseline, comparisonLane, currentDir, index, rootDir, scenarioHash, scenarioId, }) {
+    const resolvedCurrentDir = path.resolve(currentDir);
+    const trustedPriorCandidates = index.trusted.filter((entry) => (entry.scenarioId === scenarioId &&
+        path.resolve(entry.runDir) !== resolvedCurrentDir));
+    const trustedComparableCandidates = trustedPriorCandidates.filter((entry) => (isComparableLane(entry, comparisonLane)));
+    const trustedScenarioContractCandidates = trustedComparableCandidates.filter((entry) => (isComparableScenarioContract(entry, scenarioHash)));
+    return {
+        artifactRoot: rootDir,
+        candidatesInspected: index.entries.length,
+        scenarioId,
+        selectedRunDir: baseline.runDir,
+        selectedRunId: baseline.runId,
+        skippedCurrentRun: index.entries.some((entry) => path.resolve(entry.runDir) === resolvedCurrentDir),
+        ...(comparisonLane ? { comparisonLane } : {}),
+        ...(scenarioHash ? { scenarioHash } : {}),
+        trustedCandidates: index.trusted.length,
+        trustedComparableCandidates: trustedComparableCandidates.length,
+        ...(scenarioHash ? { trustedScenarioContractCandidates: trustedScenarioContractCandidates.length } : {}),
+        trustedPriorCandidates: trustedPriorCandidates.length,
+    };
+}
+/**
+ * Builds a comparison against the latest trusted prior run in an artifact root.
+ *
+ * @param {CompareLatestOptions} options
+ * @returns {CompareLatestResult}
+ */
+function compareLatestTrustedRun({ comparisonLane, currentDir, rootDir, scenarioId, }) {
+    const resolvedCurrentDir = path.resolve(currentDir);
+    const resolvedRootDir = path.resolve(rootDir);
+    assertComparableCurrentRun({ currentDir: resolvedCurrentDir, scenarioId });
+    const currentEntry = readRunIndexEntry(resolvedCurrentDir);
+    const resolvedComparisonLane = comparisonLane ?? currentEntry.comparisonLane;
+    const scenarioHash = currentEntry.scenarioHash;
+    const index = buildRunIndex({ rootDir: resolvedRootDir, scenarioId });
+    const baseline = findLatestTrustedPriorRun({
+        ...(resolvedComparisonLane ? { comparisonLane: resolvedComparisonLane } : {}),
+        ...(scenarioHash ? { scenarioHash } : {}),
+        index,
+        scenarioId,
+        currentDir: resolvedCurrentDir,
+    });
+    if (!baseline) {
+        const laneSuffix = resolvedComparisonLane
+            ? ` in comparison lane '${resolvedComparisonLane}'`
+            : ' without a comparison lane';
+        const scenarioHashSuffix = scenarioHash ? ` and scenario hash '${scenarioHash}'` : '';
+        throw new Error(`No trusted prior run found for scenario '${scenarioId}'${laneSuffix}${scenarioHashSuffix} under ${resolvedRootDir}; inspected ${index.entries.length} candidate run(s), ${index.trusted.length} trusted.`);
+    }
+    return {
+        baselineDir: baseline.runDir,
+        comparison: compareRunDirectories({
+            baselineDir: baseline.runDir,
+            currentDir: resolvedCurrentDir,
+            selection: buildLatestTrustedSelection({
+                baseline,
+                ...(resolvedComparisonLane ? { comparisonLane: resolvedComparisonLane } : {}),
+                currentDir: resolvedCurrentDir,
+                index,
+                rootDir: resolvedRootDir,
+                ...(scenarioHash ? { scenarioHash } : {}),
+                scenarioId,
+            }),
+            strategy: 'latest_trusted_prior',
+        }),
+        currentDir: resolvedCurrentDir,
+    };
+}
+/**
+ * Runs the compare-latest CLI.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+    const argv = process.argv.slice(2);
+    if (hasHelpFlag(argv)) {
+        usage(process.stdout);
+        return;
+    }
+    const args = parseArgs(argv);
+    if (typeof args.root !== 'string' ||
+        typeof args.scenario !== 'string' ||
+        typeof args.current !== 'string') {
+        usage();
+        process.exitCode = 1;
+        return;
+    }
+    const result = compareLatestTrustedRun({
+        rootDir: args.root,
+        scenarioId: args.scenario,
+        currentDir: args.current,
+        ...(typeof args['comparison-lane'] === 'string' ? { comparisonLane: args['comparison-lane'] } : {}),
+    });
+    const failOnRegression = isEnabledFlag(args['fail-on-regression']);
+    if (typeof args.out === 'string' && args.out.length > 0) {
+        const { comparisonPath, summaryPath, printedPath } = resolveOutput(args.out);
+        await writeJsonArtifact({
+            filePath: comparisonPath,
+            value: result.comparison,
+            schema: SCHEMAS.comparison,
+            label: 'Comparison artifact',
+        });
+        if (summaryPath) {
+            const current = readRunArtifacts(result.currentDir);
+            await writeTextArtifact({
+                filePath: summaryPath,
+                content: buildAgentSummaryMarkdown({
+                    health: current.health,
+                    verdict: current.verdict,
+                    comparison: result.comparison,
+                }),
+            });
+        }
+        process.stdout.write(`${printedPath}\n`);
+        if (failOnRegression) {
+            assertNoRegressedComparison({
+                comparison: result.comparison,
+                evidencePath: printedPath,
+            });
+        }
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(result.comparison, null, 2)}\n`);
+    if (failOnRegression) {
+        assertNoRegressedComparison({ comparison: result.comparison });
+    }
+}
+if (require.main === module) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist/runner/compare.d.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+type CliArgs = {
+    baseline?: string | boolean;
+    current?: string | boolean;
+    'fail-on-regression'?: string | boolean;
+    out?: string | boolean;
+    [key: string]: string | boolean | undefined;
+};
+/**
+ * Prints CLI usage to stderr.
+ *
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Parses `--key value` arguments for the comparison CLI.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Resolves `--out` as either an explicit JSON file or a run directory.
+ *
+ * @param {string} out
+ * @returns {{comparisonPath: string, summaryPath: string | null, printedPath: string}}
+ */
+declare function resolveOutput(out: string): {
+    comparisonPath: string;
+    summaryPath: string | null;
+    printedPath: string;
+};
+/**
+ * Returns whether a boolean CLI flag was provided.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+declare function isEnabledFlag(value: unknown): boolean;
+/**
+ * Throws when a comparison result should fail a strict regression gate.
+ *
+ * @param {{comparison: Record<string, unknown>, evidencePath?: string}} options
+ * @returns {void}
+ */
+declare function assertNoRegressedComparison({ comparison, evidencePath, }: {
+    comparison: Record<string, unknown>;
+    evidencePath?: string;
+}): void;
+/**
+ * Runs the compare CLI.
+ *
+ * @returns {Promise<void>}
+ */
+declare function main(): Promise<void>;
+export { assertNoRegressedComparison, isEnabledFlag, main, parseArgs, resolveOutput, usage, };