@petepetrash/circuit 0.1.0

package/dist/cli/memory.js

@@ -0,0 +1,327 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { Command, CommanderError } from 'commander';
+import { listCandidateRunFolders } from '../app/history/indexer.js';
+import { catalogFlowIds } from '../flows/catalog.js';
+import { resolveProjectId, stampMemoryManifest } from '../memory/project-identity.js';
+import { appendProjectFact, forgetProjectFact, readProjectFacts } from '../memory/project-store.js';
+import { CompiledFlowId, MemoryHintAppliesTo, MemoryInputV0 as MemoryInputV0Schema, Ref as RefSchema, } from '../schemas/index.js';
+import { runsRoot } from '../shared/control-plane-paths.js';
+function writeJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function commanderErrorMessage(err) {
+    if (err instanceof CommanderError)
+        return err.message.replace(/^error: /, '');
+    return err instanceof Error ? err.message : String(err);
+}
+function sha256Text(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+function parseMemoryArgs(argv) {
+    let parsed;
+    const program = new Command('circuit memory')
+        .exitOverride()
+        .configureOutput({ writeErr: () => { } });
+    program
+        .command('note')
+        .argument('<text...>')
+        .requiredOption('--flow <flow-id>')
+        .option('--applies-to <kind>', 'hint category', 'operator_note')
+        .option('--json')
+        .option('--runs-base <path>')
+        .option('--memory-dir <path>')
+        .option('--run-folder <path>', 'cite a specific run folder instead of the latest')
+        .action((textParts, options) => {
+        const appliesTo = options.appliesTo ?? 'operator_note';
+        if (!MemoryHintAppliesTo.safeParse(appliesTo).success) {
+            throw new Error(`--applies-to must be one of ${MemoryHintAppliesTo.options.join(', ')}`);
+        }
+        if (!CompiledFlowId.safeParse(options.flow).success) {
+            throw new Error('--flow must be a valid flow id');
+        }
+        // `CompiledFlowId` only validates the slug shape; a well-formed but
+        // unknown id (a typo or a renamed flow) would otherwise be persisted
+        // under a flow recall can never match. Reject it like an unknown
+        // --applies-to so the asymmetry the surface test found is closed.
+        if (!catalogFlowIds.includes(options.flow)) {
+            throw new Error(`--flow must be one of ${catalogFlowIds.join(', ')}`);
+        }
+        const text = textParts.join(' ').trim();
+        if (text.length === 0)
+            throw new Error('note text must be non-empty');
+        parsed = {
+            command: 'note',
+            json: options.json === true,
+            flow: options.flow,
+            appliesTo: appliesTo,
+            text,
+            ...(options.runsBase === undefined ? {} : { runsBase: options.runsBase }),
+            ...(options.memoryDir === undefined ? {} : { memoryDir: options.memoryDir }),
+            ...(options.runFolder === undefined ? {} : { runFolder: options.runFolder }),
+        };
+    });
+    program
+        .command('list')
+        .option('--flow <flow-id>')
+        .option('--json')
+        .option('--runs-base <path>')
+        .option('--memory-dir <path>')
+        .action((options) => {
+        parsed = {
+            command: 'list',
+            json: options.json === true,
+            ...(options.flow === undefined ? {} : { flow: options.flow }),
+            ...(options.runsBase === undefined ? {} : { runsBase: options.runsBase }),
+            ...(options.memoryDir === undefined ? {} : { memoryDir: options.memoryDir }),
+        };
+    });
+    program
+        .command('forget')
+        .argument('<memory-id>')
+        .option('--json')
+        .option('--runs-base <path>')
+        .option('--memory-dir <path>')
+        .action((memoryId, options) => {
+        parsed = {
+            command: 'forget',
+            json: options.json === true,
+            memoryId,
+            ...(options.runsBase === undefined ? {} : { runsBase: options.runsBase }),
+            ...(options.memoryDir === undefined ? {} : { memoryDir: options.memoryDir }),
+        };
+    });
+    try {
+        program.parse(argv, { from: 'user' });
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            // `-h`/`--help` prints help and exits cleanly.
+            if (err.code === 'commander.helpDisplayed')
+                process.exit(0);
+            // Invoking `circuit memory` with no subcommand makes commander emit its
+            // help via an error (code `commander.help`, message `(outputHelp)`) before
+            // any action runs. Surface the intended hint instead of leaking the raw
+            // commander token (F-L-1).
+            if (err.code === 'commander.help') {
+                return 'memory requires a subcommand: note, list, or forget';
+            }
+        }
+        return commanderErrorMessage(err);
+    }
+    if (parsed === undefined)
+        return 'memory requires a subcommand: note, list, or forget';
+    return parsed;
+}
+// Resolve a real run artifact to cite. Prefers the run envelope (a report ref
+// with sha256), then the result report, then the trace file (a trace ref). The
+// returned ref carries the flow_id so readProjectFacts({flowId}) can scope it.
+function resolveNoteSource(input) {
+    const candidates = [
+        { rel: 'reports/run-envelope.json', kind: 'report' },
+        { rel: 'reports/result.json', kind: 'report' },
+    ];
+    for (const candidate of candidates) {
+        const abs = join(input.runFolder, candidate.rel);
+        if (!existsSync(abs))
+            continue;
+        const sha256 = sha256Text(readFileSync(abs, 'utf8'));
+        const ref = RefSchema.parse({
+            kind: candidate.kind,
+            ref: candidate.rel,
+            sha256,
+            flow_id: input.flowId,
+        });
+        return { ref, sha256 };
+    }
+    // Trace fallback: a trace ref keys on run_id+sequence and carries no
+    // ref.sha256; cite sequence 0 (the bootstrap) with the trace file hash on
+    // source.sha256. Only reachable when neither report exists.
+    const tracePath = join(input.runFolder, 'trace.ndjson');
+    if (existsSync(tracePath)) {
+        const runId = basename(input.runFolder);
+        const sha256 = sha256Text(readFileSync(tracePath, 'utf8'));
+        const trace = RefSchema.safeParse({
+            kind: 'trace',
+            ref: 'trace.ndjson#sequence=0',
+            run_id: runId,
+            flow_id: input.flowId,
+            sequence: 0,
+        });
+        if (trace.success)
+            return { ref: trace.data, sha256 };
+    }
+    return undefined;
+}
+function buildOperatorNote(input) {
+    // A stable-but-distinct id per note: hash the flow, category, text, and the
+    // cited source sha so two identical notes against the same source derive the
+    // SAME memory_id (and `appendProjectFact` upserts on that id, so re-filing an
+    // identical note is idempotent — it replaces rather than duplicates) while
+    // genuinely distinct notes derive distinct ids.
+    const basis = `${input.flowId}\u0000${input.appliesTo}\u0000${input.text}\u0000${input.source.sha256}`;
+    const memoryId = `project-note-${sha256Text(basis).slice(0, 16)}`;
+    // A trace ref carries no ref.sha256, so bind source.sha256 to ref.sha256 only
+    // when the cited ref actually carries one (a report ref); otherwise the trace
+    // file hash sits on source.sha256 and the equality refine does not fire.
+    const sourceSha = input.source.ref.sha256 ?? input.source.sha256;
+    return MemoryInputV0Schema.parse({
+        schema_version: 1,
+        memory_id: memoryId,
+        kind: 'project',
+        source: {
+            ref: input.source.ref,
+            captured_at: input.capturedAt,
+            sha256: sourceSha,
+        },
+        summary: input.text,
+        hints: [
+            {
+                id: `operator-note-${sha256Text(memoryId).slice(0, 12)}`,
+                text: input.text,
+                applies_to: input.appliesTo,
+            },
+        ],
+        // Operator-filed facts are verified at capture against a present, hashed
+        // source; the injection path re-checks freshness later.
+        staleness: {
+            status: 'fresh',
+            checked_at: input.capturedAt,
+            reason_codes: ['source_hash_verified'],
+        },
+        authority: 'hint_only',
+    });
+}
+function factSummary(record) {
+    return {
+        memory_id: record.memory_id,
+        kind: record.kind,
+        summary: record.summary,
+        applies_to: record.hints[0]?.applies_to,
+        flow_id: record.source.ref.flow_id ?? null,
+        source_ref: { kind: record.source.ref.kind, ref: record.source.ref.ref },
+        staleness: record.staleness.status,
+    };
+}
+export async function runMemoryCommand(argv, options = {}) {
+    const parsed = parseMemoryArgs(argv);
+    if (typeof parsed === 'string') {
+        process.stderr.write(`error: ${parsed}\n`);
+        return 2;
+    }
+    const now = options.now ?? (() => new Date());
+    // The store + identity both key off the memory dir (the local store IS the
+    // project scope, D1) and the repo root (git-remote inference). repoRoot
+    // defaults to cwd; memoryDir, when supplied, wins.
+    const storeOptions = parsed.memoryDir === undefined ? {} : { memoryDir: parsed.memoryDir };
+    try {
+        if (parsed.command === 'note') {
+            const runFolder = parsed.runFolder ?? latestRunFolder(parsed.runsBase);
+            if (runFolder === undefined) {
+                process.stderr.write('error: no run folder to cite; run a flow first or pass --run-folder\n');
+                return 2;
+            }
+            const source = resolveNoteSource({ runFolder, flowId: parsed.flow });
+            if (source === undefined) {
+                process.stderr.write(`error: run folder has no citable artifact (run-envelope, result, or trace): ${runFolder}\n`);
+                return 2;
+            }
+            const record = buildOperatorNote({
+                flowId: parsed.flow,
+                appliesTo: parsed.appliesTo,
+                text: parsed.text,
+                source,
+                capturedAt: now().toISOString(),
+            });
+            appendProjectFact(record, storeOptions);
+            // Stamp the resolved project identity once (provenance for a future
+            // cross-worktree shared store). The unstable warning surfaces in output.
+            const resolved = resolveProjectId(storeOptions);
+            stampMemoryManifest(resolved, storeOptions);
+            const payload = {
+                recorded: true,
+                memory_id: record.memory_id,
+                flow_id: parsed.flow,
+                project_id: resolved.projectId,
+                project_id_source: resolved.source,
+                source_ref: { kind: record.source.ref.kind, ref: record.source.ref.ref },
+                warnings: resolved.warnings.map((warning) => ({
+                    code: warning.code,
+                    message: warning.message,
+                })),
+            };
+            if (parsed.json) {
+                writeJson(payload);
+            }
+            else {
+                process.stdout.write(`Recorded project memory ${record.memory_id} for flow ${parsed.flow} (project ${resolved.projectId}, citing ${record.source.ref.kind} ${record.source.ref.ref}).\n`);
+                for (const warning of resolved.warnings) {
+                    process.stdout.write(`warning: ${warning.message}\n`);
+                }
+            }
+            return 0;
+        }
+        if (parsed.command === 'list') {
+            const { facts, warnings } = readProjectFacts({
+                ...(parsed.memoryDir === undefined ? {} : { memoryDir: parsed.memoryDir }),
+                ...(parsed.flow === undefined ? {} : { flowId: parsed.flow }),
+            });
+            const payload = {
+                count: facts.length,
+                facts: facts.map(factSummary),
+                warnings: warnings.map((warning) => ({
+                    code: warning.code,
+                    message: warning.message,
+                    line: warning.line,
+                })),
+            };
+            if (parsed.json) {
+                writeJson(payload);
+            }
+            else if (facts.length === 0) {
+                // Endings point forward: name the command that records the first fact.
+                process.stdout.write('No project memory recorded. Record one with: circuit memory note "<what you learned>" --flow <flow-id>\n');
+            }
+            else {
+                for (const fact of facts) {
+                    process.stdout.write(`${fact.memory_id} [${fact.source.ref.flow_id ?? 'no-flow'}] ${fact.summary}\n`);
+                }
+            }
+            return 0;
+        }
+        // forget
+        const result = forgetProjectFact(parsed.memoryId, {
+            ...(parsed.memoryDir === undefined ? {} : { memoryDir: parsed.memoryDir }),
+        });
+        const payload = { forgotten: result.removed, memory_id: parsed.memoryId };
+        if (parsed.json) {
+            writeJson(payload);
+        }
+        else if (result.removed) {
+            process.stdout.write(`Forgot project memory ${parsed.memoryId}.\n`);
+        }
+        else {
+            process.stdout.write(`No project memory with id ${parsed.memoryId}.\n`);
+        }
+        return result.removed ? 0 : 1;
+    }
+    catch (error) {
+        process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+// The latest run folder by ascending basename order (matching the history
+// indexer's ordering); the last entry is the most recent. Returns undefined
+// when there is no runs base or no run folder.
+function latestRunFolder(runsBase) {
+    const base = runsBase ?? runsRoot(process.cwd());
+    try {
+        const folders = listCandidateRunFolders(base);
+        return folders.length === 0 ? undefined : folders[folders.length - 1];
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/cli/memory.js.map

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

package/dist/cli/post-run-artifacts.d.ts

@@ -0,0 +1,45 @@
+import type { OperatorSummaryWriteResult } from '../app/operator-summary/writer.js';
+import { type WriteRunEnvelopeShadowRecordInput } from '../app/run-envelope/shadow-record.js';
+import { type WriteRunEnvelopeRecordInput, type WriteRunEnvelopeRecordResult } from '../app/run-envelope/source-record.js';
+import type { ProcessEvidenceProjection as ProcessEvidenceProjectionValue } from '../schemas/process-evidence.js';
+export type PostRunArtifactWarning = {
+    readonly label: string;
+    readonly message: string;
+};
+export type PostRunArtifactContext = {
+    readonly progressJsonl: boolean;
+    readonly warnings: PostRunArtifactWarning[];
+};
+export declare function tryPostRunArtifact<T>(label: string, context: PostRunArtifactContext, write: () => T): T | undefined;
+export declare function postRunArtifactWarningOutputFields(warnings: readonly PostRunArtifactWarning[]): Record<string, unknown>;
+type WrittenProcessEvidence = {
+    readonly path: string;
+    readonly projection: ProcessEvidenceProjectionValue;
+};
+export declare function resolveFlowPrimaryResult(input: {
+    readonly runFolder: string;
+    readonly flowId: string;
+}): {
+    readonly outcome?: string;
+    readonly summary?: string;
+};
+export interface EmitPostRunArtifactsInput {
+    readonly context: PostRunArtifactContext;
+    readonly runFolder: string;
+    readonly operatorIntent: string;
+    readonly recordedAt: string;
+    readonly selectedProcess: WriteRunEnvelopeShadowRecordInput['selectedProcess'];
+    readonly child: WriteRunEnvelopeShadowRecordInput['child'];
+    readonly writeOperatorSummary: () => OperatorSummaryWriteResult;
+    readonly buildProcessEvidenceProjection: () => ProcessEvidenceProjectionValue;
+    readonly memoryContext: WriteRunEnvelopeRecordInput['memoryContext'];
+    readonly recallMemoryIndicator?: WriteRunEnvelopeRecordInput['recallMemoryIndicator'];
+}
+export interface EmitPostRunArtifactsResult {
+    readonly operatorSummary: OperatorSummaryWriteResult | undefined;
+    readonly processEvidence: WrittenProcessEvidence | undefined;
+    readonly runEnvelope: WriteRunEnvelopeRecordResult | undefined;
+}
+export declare function emitPostRunArtifacts(input: EmitPostRunArtifactsInput): EmitPostRunArtifactsResult;
+export {};
+//# sourceMappingURL=post-run-artifacts.d.ts.map

package/dist/cli/post-run-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-run-artifacts.d.ts","sourceRoot":"","sources":["../../src/cli/post-run-artifacts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,OAAO,EACL,KAAK,iCAAiC,EAEvC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EAElC,MAAM,sCAAsC,CAAC;AAe9C,OAAO,KAAK,EAAE,yBAAyB,IAAI,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAElH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CAC7C,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,MAAM,CAAC,GACb,CAAC,GAAG,SAAS,CAWf;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED,KAAK,sBAAsB,GAAG;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,8BAA8B,CAAC;CACrD,CAAC;AAcF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAe3D;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,iCAAiC,CAAC,iBAAiB,CAAC,CAAC;IAC/E,QAAQ,CAAC,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,CAAC;IAC3D,QAAQ,CAAC,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;IAChE,QAAQ,CAAC,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;IAI9E,QAAQ,CAAC,aAAa,EAAE,2BAA2B,CAAC,eAAe,CAAC,CAAC;IAIrE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,2BAA2B,CAAC,uBAAuB,CAAC,CAAC;CACvF;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,eAAe,EAAE,0BAA0B,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,eAAe,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,WAAW,EAAE,4BAA4B,GAAG,SAAS,CAAC;CAChE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,0BAA0B,CAoDjG"}

package/dist/cli/post-run-artifacts.js

@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeProcessEvidenceProjection } from '../app/process-evidence/projection.js';
+import { writeRunEnvelopeShadowRecord, } from '../app/run-envelope/shadow-record.js';
+import { writeRunEnvelopeRecord as writeSourceRunEnvelopeRecord, } from '../app/run-envelope/source-record.js';
+import { findFlowRuntimeSurfaceById } from '../flows/catalog.js';
+export function tryPostRunArtifact(label, context, write) {
+    try {
+        return write();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        context.warnings.push({ label, message });
+        if (!context.progressJsonl) {
+            process.stderr.write(`warning: post-run artifact ${label} failed: ${message}\n`);
+        }
+        return undefined;
+    }
+}
+export function postRunArtifactWarningOutputFields(warnings) {
+    if (warnings.length === 0)
+        return {};
+    return {
+        post_run_artifact_warnings: warnings.map((warning) => ({
+            label: warning.label,
+            message: warning.message,
+        })),
+    };
+}
+// Resolve the flow's own primary-result outcome word (e.g. a Fix `partial`) and
+// its stated summary so the source run-envelope can name a degraded-but-complete
+// run — and say why — without itself importing the flow catalog (that would
+// break the projection-only boundary the envelope is held to). The flow's
+// runtime surface names where its primary result lives; we read that outcome and
+// summary here, in the CLI layer that is allowed to know it. Reading both from
+// the one artifact keeps the caveat word and its reason from ever disagreeing.
+//
+// Fail open: a flow without a primary result, or a missing or malformed result
+// file, returns an empty object and leaves the surface exactly as before. The
+// two fields are read independently, so a result with an outcome but no summary
+// (or the reverse) still yields whichever field is present.
+export function resolveFlowPrimaryResult(input) {
+    const primaryResultPath = findFlowRuntimeSurfaceById(input.flowId)?.primaryResult?.path;
+    if (primaryResultPath === undefined)
+        return {};
+    let primaryResult;
+    try {
+        primaryResult = JSON.parse(readFileSync(join(input.runFolder, primaryResultPath), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    if (typeof primaryResult !== 'object' || primaryResult === null)
+        return {};
+    const record = primaryResult;
+    return {
+        ...(typeof record.outcome === 'string' ? { outcome: record.outcome } : {}),
+        ...(typeof record.summary === 'string' ? { summary: record.summary } : {}),
+    };
+}
+export function emitPostRunArtifacts(input) {
+    const { context, runFolder, operatorIntent, recordedAt, selectedProcess, child } = input;
+    const operatorSummary = tryPostRunArtifact('operator-summary', context, input.writeOperatorSummary);
+    tryPostRunArtifact('run-envelope-shadow', context, () => writeRunEnvelopeShadowRecord({
+        runFolder,
+        operatorIntent,
+        selectedProcess,
+        child,
+        recordedAt,
+    }));
+    const processEvidence = tryPostRunArtifact('process-evidence', context, () => writeProcessEvidenceProjection({
+        runFolder,
+        projection: input.buildProcessEvidenceProjection(),
+    }));
+    const runEnvelope = processEvidence === undefined
+        ? undefined
+        : tryPostRunArtifact('run-envelope', context, () => {
+            const flowPrimary = resolveFlowPrimaryResult({
+                runFolder,
+                flowId: processEvidence.projection.flow_id,
+            });
+            return writeSourceRunEnvelopeRecord({
+                runFolder,
+                operatorIntent,
+                selectedProcess,
+                processEvidence,
+                recordedAt,
+                ...(flowPrimary.outcome === undefined ? {} : { flowOutcome: flowPrimary.outcome }),
+                ...(flowPrimary.summary === undefined
+                    ? {}
+                    : { flowOutcomeReason: flowPrimary.summary }),
+                ...(input.memoryContext === undefined ? {} : { memoryContext: input.memoryContext }),
+                ...(input.recallMemoryIndicator === undefined
+                    ? {}
+                    : { recallMemoryIndicator: input.recallMemoryIndicator }),
+            });
+        });
+    return { operatorSummary, processEvidence, runEnvelope };
+}
+//# sourceMappingURL=post-run-artifacts.js.map

package/dist/cli/post-run-artifacts.js.map

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

package/dist/cli/preview.d.ts

@@ -0,0 +1,9 @@
+import { type HostKind as HostKindValue } from '../schemas/host.js';
+import { type FlowSelectionPreview, type PreviewEffortSource, type PreviewModelSource } from './flow-selection-preview.js';
+import { type TerminalPalette } from './terminal-style.js';
+export declare function hostKindFromEnv(): HostKindValue | undefined;
+export declare function sourceCellText(modelSource: PreviewModelSource, effortSource: PreviewEffortSource): string;
+export declare function renderSinglePreview(palette: TerminalPalette, preview: FlowSelectionPreview): string;
+export declare function renderMatrix(palette: TerminalPalette, previews: readonly FlowSelectionPreview[]): string;
+export declare function runPreviewCommand(argv: readonly string[]): number;
+//# sourceMappingURL=preview.d.ts.map

package/dist/cli/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/cli/preview.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,QAAQ,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG9E,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAGxB,MAAM,6BAA6B,CAAC;AASrC,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,qBAAqB,CAAC;AA0E7B,wBAAgB,eAAe,IAAI,aAAa,GAAG,SAAS,CAK3D;AA0BD,wBAAgB,cAAc,CAC5B,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,mBAAmB,GAChC,MAAM,CAKR;AAkDD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CA6CR;AA8DD,wBAAgB,YAAY,CAC1B,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,SAAS,oBAAoB,EAAE,GACxC,MAAM,CAkDR;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAkDjE"}