agent-scenario-loop 0.1.0

package/dist/runner/live-proof.d.ts

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+type CliArgs = {
+    'artifact-base-dir'?: string | boolean;
+    file?: string | string[] | boolean;
+    'fail-on-regression'?: string | boolean;
+    out?: string | boolean;
+    'require-artifacts'?: string | boolean;
+    'require-platforms'?: string | boolean;
+    'run-id'?: string | boolean;
+    [key: string]: string | string[] | boolean | undefined;
+};
+type LiveProofArtifact = {
+    comparisonCounts: {
+        better: number;
+        inconclusive: number;
+        mixed: number;
+        skipped: number;
+        unchanged: number;
+        worse: number;
+    };
+    comparisonStatus: string;
+    comparisons: LiveProofComparisonPointer[];
+    nextAction: {
+        code: string;
+        summary: string;
+    };
+    interactionProofs?: Array<{
+        captures?: {
+            screenshots?: string[];
+        };
+        healthStatus: string;
+        label: string;
+        runDir: string;
+        runId: string;
+        runnerId: string;
+        scenarioId: string;
+        summaryPath: string;
+        verdictStatus: string;
+        warnings?: {
+            checks?: Array<{
+                code?: string;
+                message?: string;
+                name?: string;
+                nextAction?: {
+                    code?: string;
+                    summary?: string;
+                };
+            }>;
+            count?: number;
+        };
+    }>;
+    skippedInteractionProofs?: Array<{
+        label: string;
+        nextAction: {
+            code: string;
+            summary: string;
+        };
+        reason: string;
+        runId: string;
+        runnerId: string;
+        scenarioId: string;
+    }>;
+    platform: 'android' | 'ios';
+    preflight: {
+        healthStatus: string;
+        runId: string;
+        runDir: string;
+        summaryPath: string;
+        verdictStatus: string;
+    };
+    profiles: Array<{
+        healthStatus: string;
+        label: string;
+        runId: string;
+        runDir: string;
+        scenarioId: string;
+        summaryPath: string;
+        verdictStatus: string;
+    }>;
+    runId: string;
+    status: string;
+    summary: string;
+};
+type LiveProofComparisonCounts = LiveProofArtifact['comparisonCounts'];
+type LiveProofMetricStatus = 'better' | 'worse' | 'unchanged' | 'inconclusive';
+type LiveProofPlatform = LiveProofArtifact['platform'];
+type LiveProofComparisonPointer = {
+    baselineDir?: string | null;
+    comparisonDir?: string | null;
+    label?: string;
+    metricSummary?: {
+        counts?: Record<LiveProofMetricStatus, number>;
+        notableMetrics?: Array<{
+            delta?: number | null;
+            name?: string;
+            status?: Exclude<LiveProofMetricStatus, 'unchanged'>;
+            unit?: string;
+        }>;
+    };
+    runId?: string;
+    scenarioId?: string;
+    status?: string;
+    summaryPath?: string | null;
+};
+type LiveProofAggregateStatus = ('baseline_missing' | 'improved' | 'inconclusive' | 'mixed' | 'not_compared' | 'regressed' | 'unchanged');
+type LiveProofNextActionCode = LiveProofArtifact['nextAction']['code'];
+type LiveProofSetArtifact = {
+    failureReasons: string[];
+    missingPlatforms: LiveProofPlatform[];
+    nextAction: {
+        code: string;
+        summary: string;
+    };
+    presentPlatforms: LiveProofPlatform[];
+    proofCount: number;
+    proofs: LiveProofSetProofPointer[];
+    requiredPlatforms: LiveProofPlatform[];
+    runId: string;
+    schemaVersion: '1.0.0';
+    status: 'failed' | 'passed';
+    summary: string;
+};
+type LiveProofSetProofPointer = {
+    comparisonStatus: string;
+    filePath: string;
+    interactionProofCount: number;
+    interactionWarnings?: LiveProofSetInteractionWarningPointer[];
+    interactionWarningCount: number;
+    nextAction: {
+        code: string;
+        summary: string;
+    };
+    platform: LiveProofPlatform;
+    profileCount: number;
+    runId: string;
+    status: string;
+    summaryPath: string;
+};
+type LiveProofSetInteractionWarningPointer = {
+    checks: Array<{
+        code: string;
+        message: string;
+        name: string;
+        nextAction?: {
+            code: string;
+            summary: string;
+        };
+    }>;
+    label: string;
+    runId: string;
+    runnerId: string;
+    scenarioId: string;
+};
+type LiveProofArtifactPointerIssue = {
+    expected: 'directory' | 'file';
+    label: string;
+    path: string;
+    reason: string;
+};
+type LiveProofArtifactReadOptions = {
+    artifactBaseDir?: string;
+    requireArtifacts?: boolean;
+};
+/**
+ * Prints CLI usage.
+ *
+ * @param {{write: (message: string) => unknown}} [output]
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Parses a small flag set for the live-proof CLI.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Resolves one or more --file values into a stable list.
+ *
+ * @param {CliArgs} args
+ * @returns {string[]}
+ */
+declare function resolveLiveProofFiles(args: CliArgs): string[];
+/**
+ * Parses required platform names for a live-proof set gate.
+ *
+ * @param {string | boolean | undefined} value
+ * @returns {LiveProofPlatform[]}
+ */
+declare function parseRequiredPlatforms(value: string | boolean | undefined): LiveProofPlatform[];
+/**
+ * Counts comparison outcomes from one live-proof comparison list.
+ *
+ * @param {Array<{status?: string}>} comparisons
+ * @returns {LiveProofComparisonCounts}
+ */
+declare function countLiveProofComparisons(comparisons: Array<{
+    status?: string;
+}>): LiveProofComparisonCounts;
+/**
+ * Collapses live-proof comparison pointers into the expected aggregate status.
+ *
+ * @param {Array<{status?: string}>} comparisons
+ * @returns {LiveProofAggregateStatus}
+ */
+declare function deriveLiveProofComparisonStatus(comparisons: Array<{
+    status?: string;
+}>): LiveProofAggregateStatus;
+/**
+ * Resolves the expected next-action code for an aggregate proof status.
+ *
+ * @param {LiveProofAggregateStatus} comparisonStatus
+ * @param {string} [status]
+ * @returns {LiveProofNextActionCode}
+ */
+declare function expectedLiveProofNextActionCode(comparisonStatus: LiveProofAggregateStatus, status?: string): LiveProofNextActionCode;
+/**
+ * Verifies that aggregate comparison counts match the comparison pointers.
+ *
+ * @param {LiveProofArtifact} proof
+ * @returns {void}
+ */
+declare function assertLiveProofComparisonCounts(proof: LiveProofArtifact): void;
+/**
+ * Verifies that aggregate comparison status and next action match the pointers.
+ *
+ * @param {LiveProofArtifact} proof
+ * @returns {void}
+ */
+declare function assertLiveProofAggregateSignals(proof: LiveProofArtifact): void;
+/**
+ * Collects missing local evidence pointers from one live-proof artifact.
+ *
+ * @param {LiveProofArtifact} proof
+ * @param {{artifactBaseDir?: string}} [options]
+ * @returns {LiveProofArtifactPointerIssue[]}
+ */
+declare function collectLiveProofArtifactPointerIssues(proof: LiveProofArtifact, { artifactBaseDir }?: {
+    artifactBaseDir?: string;
+}): LiveProofArtifactPointerIssue[];
+/**
+ * Fails when a live-proof artifact references missing local evidence.
+ *
+ * @param {LiveProofArtifact} proof
+ * @param {{artifactBaseDir?: string}} [options]
+ * @returns {void}
+ */
+declare function assertLiveProofArtifactPointers(proof: LiveProofArtifact, options?: {
+    artifactBaseDir?: string;
+}): void;
+/**
+ * Formats compact metric summary details for one comparison pointer.
+ *
+ * @param {LiveProofComparisonPointer} comparison
+ * @returns {string}
+ */
+declare function formatComparisonPointerMetrics(comparison: LiveProofComparisonPointer): string;
+/**
+ * Formats capture counts for one interaction proof pointer.
+ *
+ * @param {{captures?: {screenshots?: string[]}}} proofPointer
+ * @returns {string}
+ */
+declare function formatInteractionProofCaptures(proofPointer: {
+    captures?: {
+        screenshots?: string[];
+    };
+}): string;
+/**
+ * Formats warning counts for one interaction proof pointer.
+ *
+ * @param {{warnings?: {count?: number}}} proofPointer
+ * @returns {string}
+ */
+declare function formatInteractionProofWarnings(proofPointer: {
+    warnings?: {
+        count?: number;
+    };
+}): string;
+/**
+ * Formats warning check details for one interaction proof pointer.
+ *
+ * @param {{warnings?: {checks?: Array<{code?: string, message?: string, name?: string, nextAction?: {code?: string, summary?: string}}>}}} proofPointer
+ * @returns {string[]}
+ */
+declare function formatInteractionProofWarningDetails(proofPointer: {
+    warnings?: {
+        checks?: Array<{
+            code?: string;
+            message?: string;
+            name?: string;
+            nextAction?: {
+                code?: string;
+                summary?: string;
+            };
+        }>;
+    };
+}): string[];
+/**
+ * Reads and validates a live-proof artifact.
+ *
+ * @param {string} filePath
+ * @param {LiveProofArtifactReadOptions} [options]
+ * @returns {LiveProofArtifact}
+ */
+declare function readLiveProof(filePath: string, options?: LiveProofArtifactReadOptions): LiveProofArtifact;
+/**
+ * Verifies that a multi-proof gate includes every required platform.
+ *
+ * @param {LiveProofArtifact[]} proofs
+ * @param {LiveProofPlatform[]} requiredPlatforms
+ * @returns {void}
+ */
+declare function assertLiveProofSetRequiredPlatforms(proofs: LiveProofArtifact[], requiredPlatforms: LiveProofPlatform[]): void;
+/**
+ * Reads and validates a platform proof set.
+ *
+ * @param {{artifactBaseDir?: string, files: string[], requiredPlatforms?: LiveProofPlatform[], requireArtifacts?: boolean}} options
+ * @returns {LiveProofArtifact[]}
+ */
+declare function readLiveProofSet({ artifactBaseDir, files, requiredPlatforms, requireArtifacts, }: {
+    artifactBaseDir?: string;
+    files: string[];
+    requiredPlatforms?: LiveProofPlatform[];
+    requireArtifacts?: boolean;
+}): LiveProofArtifact[];
+/**
+ * Resolves the optional proof-set artifact output directory.
+ *
+ * @param {CliArgs} args
+ * @returns {string | null}
+ */
+declare function resolveLiveProofSetOutputDir(args: CliArgs): string | null;
+/**
+ * Resolves the proof-set run id used for written artifacts.
+ *
+ * @param {CliArgs} args
+ * @returns {string}
+ */
+declare function resolveLiveProofSetRunId(args: CliArgs): string;
+/**
+ * Resolves the base directory for local artifact pointer checks.
+ *
+ * @param {CliArgs} args
+ * @returns {string | undefined}
+ */
+declare function resolveLiveProofArtifactBaseDir(args: CliArgs): string | undefined;
+/**
+ * Returns whether the caller requested local artifact pointer checks.
+ *
+ * @param {CliArgs} args
+ * @returns {boolean}
+ */
+declare function shouldRequireArtifacts(args: CliArgs): boolean;
+/**
+ * Builds human-readable failure reasons for one proof set.
+ *
+ * @param {{failOnRegression: boolean, missingPlatforms: LiveProofPlatform[], proofs: LiveProofArtifact[]}} options
+ * @returns {string[]}
+ */
+declare function buildLiveProofSetFailureReasons({ failOnRegression, missingPlatforms, proofs, }: {
+    failOnRegression: boolean;
+    missingPlatforms: LiveProofPlatform[];
+    proofs: LiveProofArtifact[];
+}): string[];
+/**
+ * Builds the next action for a proof-set artifact.
+ *
+ * @param {{failureReasons: string[], missingPlatforms: LiveProofPlatform[], proofs: LiveProofArtifact[]}} options
+ * @returns {{code: string, summary: string}}
+ */
+declare function buildLiveProofSetNextAction({ failureReasons, missingPlatforms, proofs, }: {
+    failureReasons: string[];
+    missingPlatforms: LiveProofPlatform[];
+    proofs: LiveProofArtifact[];
+}): {
+    code: string;
+    summary: string;
+};
+/**
+ * Builds the durable platform proof-set artifact.
+ *
+ * @param {{failOnRegression: boolean, files: string[], proofs: LiveProofArtifact[], requiredPlatforms?: LiveProofPlatform[], runId?: string}} options
+ * @returns {LiveProofSetArtifact}
+ */
+declare function buildLiveProofSetArtifact({ failOnRegression, files, proofs, requiredPlatforms, runId, }: {
+    failOnRegression: boolean;
+    files: string[];
+    proofs: LiveProofArtifact[];
+    requiredPlatforms?: LiveProofPlatform[];
+    runId?: string;
+}): LiveProofSetArtifact;
+/**
+ * Formats proof-set interaction warning details for agent-readable markdown.
+ *
+ * @param {LiveProofSetProofPointer} proof
+ * @returns {string[]}
+ */
+declare function formatLiveProofSetWarningDetails(proof: LiveProofSetProofPointer): string[];
+/**
+ * Formats a proof-set artifact for agent-readable markdown.
+ *
+ * @param {LiveProofSetArtifact} artifact
+ * @returns {string}
+ */
+declare function formatLiveProofSetArtifactMarkdown(artifact: LiveProofSetArtifact): string;
+/**
+ * Writes durable proof-set artifacts under an output directory.
+ *
+ * @param {{artifact: LiveProofSetArtifact, outputDir: string}} options
+ * @returns {Promise<{liveProofSetPath: string, summaryPath: string}>}
+ */
+declare function writeLiveProofSetArtifact({ artifact, outputDir, }: {
+    artifact: LiveProofSetArtifact;
+    outputDir: string;
+}): Promise<{
+    liveProofSetPath: string;
+    summaryPath: string;
+}>;
+/**
+ * Formats a live-proof artifact for CLI output.
+ *
+ * @param {LiveProofArtifact} proof
+ * @returns {string}
+ */
+declare function formatLiveProof(proof: LiveProofArtifact): string;
+/**
+ * Formats one or more live-proof artifacts for CLI output.
+ *
+ * @param {{proofs: LiveProofArtifact[], requiredPlatforms?: LiveProofPlatform[]}} options
+ * @returns {string}
+ */
+declare function formatLiveProofSet({ proofs, requiredPlatforms, }: {
+    proofs: LiveProofArtifact[];
+    requiredPlatforms?: LiveProofPlatform[];
+}): string;
+/**
+ * Returns whether the caller requested a regression gate and the proof regressed.
+ *
+ * @param {{failOnRegression: boolean, proof: LiveProofArtifact}} options
+ * @returns {boolean}
+ */
+declare function shouldFailOnRegression({ failOnRegression, proof, }: {
+    failOnRegression: boolean;
+    proof: LiveProofArtifact;
+}): boolean;
+/**
+ * Returns whether a live-proof set should make the CLI exit nonzero.
+ *
+ * @param {{failOnRegression: boolean, proofs: LiveProofArtifact[]}} options
+ * @returns {boolean}
+ */
+declare function shouldFailLiveProofSet({ failOnRegression, proofs, }: {
+    failOnRegression: boolean;
+    proofs: LiveProofArtifact[];
+}): boolean;
+/**
+ * Runs the live-proof inspection CLI.
+ *
+ * @returns {Promise<void>}
+ */
+declare function main(): Promise<void>;
+export { assertLiveProofArtifactPointers, assertLiveProofAggregateSignals, assertLiveProofComparisonCounts, assertLiveProofSetRequiredPlatforms, buildLiveProofSetArtifact, buildLiveProofSetFailureReasons, buildLiveProofSetNextAction, collectLiveProofArtifactPointerIssues, countLiveProofComparisons, deriveLiveProofComparisonStatus, expectedLiveProofNextActionCode, formatComparisonPointerMetrics, formatInteractionProofCaptures, formatInteractionProofWarningDetails, formatInteractionProofWarnings, formatLiveProofSetWarningDetails, formatLiveProof, formatLiveProofSet, formatLiveProofSetArtifactMarkdown, main, parseArgs, parseRequiredPlatforms, readLiveProof, readLiveProofSet, resolveLiveProofSetOutputDir, resolveLiveProofArtifactBaseDir, resolveLiveProofFiles, resolveLiveProofSetRunId, shouldRequireArtifacts, shouldFailLiveProofSet, shouldFailOnRegression, usage, writeLiveProofSetArtifact, };
+export type { CliArgs, LiveProofArtifact, LiveProofArtifactPointerIssue, LiveProofArtifactReadOptions, LiveProofSetArtifact, LiveProofSetProofPointer, };