rea-agents 0.3.0 → 0.5.0

package/dist/artifacts/SafeOutputTree.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rm } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { streamChunkToBuffer } from "./StreamBytes.js";
+import { ArtifactPathRegistry, normalizeArtifactPath, } from "./ArtifactPaths.js";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+/** Symlink-resistant materialization in an exclusively owned, initially absent tree. */
+export class SafeOutputTree {
+    #registry = new ArtifactPathRegistry();
+    #limits;
+    #outputRoot;
+    #stagingRoot;
+    #totalBytes = 0;
+    #published = false;
+    #cleanup = {
+        attempted: false,
+        verified: false,
+        residualPaths: [],
+    };
+    constructor(outputRoot, stagingRoot, limits) {
+        this.#outputRoot = outputRoot;
+        this.#stagingRoot = stagingRoot;
+        this.#limits = limits;
+    }
+    /** Exclusively create the absent destination as this operation's owned tree. */
+    static async create(outputRoot, limits) {
+        if (!isAbsolute(outputRoot))
+            throw new ArtifactReaderFailure("path", "Extraction output root must be absolute");
+        const requested = resolve(outputRoot);
+        const name = basename(requested);
+        if (name === "." || name === "..")
+            throw new ArtifactReaderFailure("path", "Invalid extraction output root");
+        const parent = await realpath(dirname(requested)).catch((cause) => {
+            throw new ArtifactReaderFailure("unavailable", "Extraction output parent is unavailable", { cause });
+        });
+        const canonicalOutput = join(parent, name);
+        await mkdir(canonicalOutput, { mode: 0o700 }).catch((cause) => {
+            if (isAlreadyExists(cause))
+                throw new ArtifactReaderFailure("path", "Extraction output root already exists", { cause });
+            throw cause;
+        });
+        try {
+            const stagingHandle = await open(canonicalOutput, constants.O_RDONLY | constants.O_DIRECTORY);
+            try {
+                await stagingHandle.chmod(0o700);
+            }
+            finally {
+                await stagingHandle.close();
+            }
+            return new SafeOutputTree(canonicalOutput, canonicalOutput, limits);
+        }
+        catch (cause) {
+            await rm(canonicalOutput, { recursive: true, force: true });
+            throw cause;
+        }
+    }
+    get outputRoot() {
+        return this.#outputRoot;
+    }
+    get cleanup() {
+        return this.#cleanup;
+    }
+    /** Stream one selected regular file with exact byte and digest verification. */
+    async write(relativePath, source, expectedSha256, signal) {
+        this.#assertWritable();
+        const path = normalizeArtifactPath(relativePath, this.#limits);
+        this.#registry.add(path, "file");
+        const destination = await this.#prepareParent(path);
+        const handle = await open(destination, constants.O_CREAT |
+            constants.O_EXCL |
+            constants.O_WRONLY |
+            constants.O_NOFOLLOW, 0o600).catch((cause) => {
+            throw new ArtifactReaderFailure("path", `Could not exclusively create extraction path: ${path}`, { cause });
+        });
+        const hash = createHash("sha256");
+        let bytes = 0;
+        try {
+            for await (const raw of source) {
+                abortIfNeeded(signal);
+                const chunk = streamChunkToBuffer(raw);
+                bytes += chunk.length;
+                if (bytes > this.#limits.maxEntryBytes)
+                    throw new ArtifactReaderFailure("limit", `Observed entry bytes exceed limit: ${path}`);
+                if (this.#totalBytes + bytes > this.#limits.maxTotalBytes)
+                    throw new ArtifactReaderFailure("limit", "Observed extraction bytes exceed cumulative limit");
+                hash.update(chunk);
+                await writeAll(handle, chunk);
+            }
+            const sha256 = hash.digest("hex");
+            if (sha256 !== expectedSha256)
+                throw new ArtifactReaderFailure("integrity", `Extracted content disagrees with inventory: ${path}`);
+            await handle.sync();
+            await handle.close();
+            const readback = await hashFile(destination, bytes, signal);
+            if (readback.sha256 !== sha256 || readback.bytes !== bytes)
+                throw new ArtifactReaderFailure("integrity", `Durable readback verification failed: ${path}`);
+            this.#totalBytes += bytes;
+            return { relativePath: path, sha256, bytesWritten: bytes };
+        }
+        catch (cause) {
+            await handle.close().catch(() => undefined);
+            throw cause;
+        }
+    }
+    /** Sync the owned output tree and prevent further writes through this instance. */
+    async commit() {
+        this.#assertWritable();
+        const parent = await open(dirname(this.#outputRoot), constants.O_RDONLY | constants.O_DIRECTORY);
+        const staging = await open(this.#stagingRoot, constants.O_RDONLY | constants.O_DIRECTORY);
+        try {
+            await staging.sync();
+            await parent.sync();
+            this.#published = true;
+        }
+        catch (cause) {
+            throw new ArtifactReaderFailure("path", "Could not durably sync extraction output", { cause });
+        }
+        finally {
+            await Promise.allSettled([parent.close(), staging.close()]);
+        }
+    }
+    /** Remove only this operation's unsealed tree and verify absence. */
+    async rollback() {
+        if (this.#published)
+            return this.#cleanup;
+        await rm(this.#stagingRoot, { recursive: true, force: true });
+        const absent = await isAbsent(this.#stagingRoot);
+        this.#cleanup = {
+            attempted: true,
+            verified: absent,
+            residualPaths: absent ? [] : [basename(this.#stagingRoot)],
+        };
+        if (!absent)
+            throw new ArtifactReaderFailure("integrity", "Extraction output cleanup could not be verified");
+        return this.#cleanup;
+    }
+    async #prepareParent(relativePath) {
+        const parts = relativePath.split("/");
+        const fileName = parts.pop();
+        if (fileName === undefined)
+            throw new ArtifactReaderFailure("path", "Invalid extraction path");
+        let current = this.#stagingRoot;
+        for (const part of parts) {
+            current = join(current, part);
+            await mkdir(current, { mode: 0o700 }).catch((cause) => {
+                if (!isAlreadyExists(cause))
+                    throw cause;
+            });
+            const metadata = await lstat(current);
+            if (!metadata.isDirectory() || metadata.isSymbolicLink())
+                throw new ArtifactReaderFailure("path", `Unsafe extraction parent: ${relativePath}`);
+        }
+        return join(current, fileName);
+    }
+    #assertWritable() {
+        if (this.#published)
+            throw new ArtifactReaderFailure("integrity", "Extraction tree is already committed");
+    }
+}
+const hashFile = async (path, maximum, signal) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const hash = createHash("sha256");
+    let bytes = 0;
+    try {
+        for await (const raw of handle.createReadStream({ autoClose: false })) {
+            abortIfNeeded(signal);
+            const chunk = streamChunkToBuffer(raw);
+            bytes += chunk.length;
+            if (bytes > maximum)
+                throw new ArtifactReaderFailure("integrity", "Readback exceeded the bytes written");
+            hash.update(chunk);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return { sha256: hash.digest("hex"), bytes };
+};
+const writeAll = async (handle, chunk) => {
+    let offset = 0;
+    while (offset < chunk.length) {
+        const { bytesWritten } = await handle.write(chunk, offset, chunk.length - offset);
+        if (bytesWritten === 0)
+            throw new ArtifactReaderFailure("unavailable", "Extraction output stopped accepting bytes");
+        offset += bytesWritten;
+    }
+};
+const isAbsent = async (path) => lstat(path).then(() => false, (cause) => {
+    if (isNotFound(cause))
+        return true;
+    throw cause;
+});
+const isNotFound = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const isAlreadyExists = (cause) => cause instanceof Error && "code" in cause && cause.code === "EEXIST";
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "Artifact extraction cancelled");
+};

package/dist/artifacts/StreamBytes.js

@@ -0,0 +1,10 @@
+/** Parse a Node readable chunk without unchecked coercion. */
+export const streamChunkToBuffer = (value) => {
+    if (Buffer.isBuffer(value))
+        return value;
+    if (value instanceof Uint8Array)
+        return Buffer.from(value);
+    if (typeof value === "string")
+        return Buffer.from(value);
+    throw new TypeError("Readable stream emitted a non-byte chunk");
+};

package/dist/artifacts/ZipArtifactReader.js

@@ -0,0 +1,109 @@
+import { open } from "node:fs/promises";
+import { PassThrough } from "node:stream";
+import { once } from "node:events";
+import { Reader, ZipReader } from "@zip.js/zip.js";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+class NodeFileReader extends Reader {
+    path;
+    #handle;
+    constructor(path) {
+        super(path);
+        this.path = path;
+    }
+    async init() {
+        this.#handle = await open(this.path, "r");
+        this.size = (await this.#handle.stat()).size;
+    }
+    async readUint8Array(index, length) {
+        const handle = this.#handle;
+        if (handle === undefined)
+            throw new Error("ZIP reader is not initialized");
+        const bytes = Buffer.alloc(Math.min(length, this.size - index));
+        const read = await handle.read(bytes, 0, bytes.length, index);
+        return bytes.subarray(0, read.bytesRead);
+    }
+    async closeHandle() {
+        await this.#handle?.close();
+        this.#handle = undefined;
+    }
+}
+/** Lazy Zip64-capable reader with CRC and overlap verification on every read. */
+export class ZipArtifactReader {
+    format;
+    #source;
+    #reader;
+    #entries = new Map();
+    constructor(path, format) {
+        this.format = format;
+        this.#source = new NodeFileReader(path);
+        this.#reader = new ZipReader(this.#source, {
+            checkSignature: true,
+            checkOverlappingEntry: true,
+        });
+    }
+    async *entries(signal) {
+        for await (const entry of this.#reader.getEntriesGenerator()) {
+            abortIfNeeded(signal);
+            this.#entries.set(entry.filename, entry);
+            const symlink = isSymlink(entry);
+            yield {
+                path: entry.filename,
+                kind: entry.directory ? "directory" : symlink ? "symlink" : "file",
+                declaredSize: entry.directory ? null : entry.uncompressedSize,
+                compressedSize: entry.directory ? null : entry.compressedSize,
+                executable: entry.executable,
+                encrypted: entry.encrypted,
+                byteOffset: null,
+                declaredSha256: null,
+                limitations: symlink ? ["Archive symlink target was not read."] : [],
+                adapterKey: entry.filename,
+            };
+        }
+    }
+    open(entry, signal) {
+        abortIfNeeded(signal);
+        const stored = this.#entries.get(entry.adapterKey);
+        if (stored === undefined || stored.directory || isSymlink(stored))
+            return Promise.reject(new ArtifactReaderFailure("format", "ZIP entry is not a regular file"));
+        if (stored.encrypted)
+            return Promise.reject(new ArtifactReaderFailure("unavailable", "Encrypted ZIP entry is unsupported"));
+        return Promise.resolve(extractStream(stored, signal));
+    }
+    async close() {
+        await this.#reader.close().catch(() => undefined);
+        await this.#source.closeHandle();
+    }
+    provenance() {
+        return [];
+    }
+}
+const extractStream = (entry, signal) => {
+    const output = new PassThrough();
+    const writable = new WritableStream({
+        write: async (chunk) => {
+            abortIfNeeded(signal);
+            if (!output.write(Buffer.from(chunk)))
+                await once(output, "drain");
+        },
+        close: () => {
+            output.end();
+        },
+        abort: (reason) => {
+            output.destroy(toError(reason));
+        },
+    });
+    void entry
+        .getData(writable, {
+        checkSignature: true,
+        checkOverlappingEntry: true,
+        onprogress: () => abortIfNeeded(signal),
+    })
+        .catch((cause) => output.destroy(toError(cause)));
+    return output;
+};
+const isSymlink = (entry) => entry.unixMode !== undefined && (entry.unixMode & 0o170000) === 0o120000;
+const abortIfNeeded = (signal) => {
+    if (signal?.aborted === true)
+        throw new ArtifactReaderFailure("cancelled", "ZIP operation cancelled");
+};
+const toError = (cause) => cause instanceof Error ? cause : new Error("ZIP extraction failed");

package/dist/cli.js

@@ -1,10 +1,15 @@
 import { Cli, z } from "incur";
 import { fileURLToPath } from "node:url";
 import { runDoctor } from "./application/Doctor.js";
-import { runDirectAnalysis } from "./application/DirectAnalysis.js";
+import { runDirectAnalysis, runProviderAnalysis, runSessionStatus, } from "./application/DirectAnalysis.js";
 import { runSetup } from "./application/Setup.js";
+import { runUninstall } from "./application/Uninstall.js";
 import { PRODUCT_IDENTITY } from "./identity.js";
 import { createLogger, parseLogLevel } from "./logger.js";
+import { logCliCommand } from "./cliLogging.js";
+import { parseConfig } from "./config.js";
+import { importReferenceSource } from "./application/ReferenceSourceImport.js";
+import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
  * Analysis commands acquire and close their own sessions; bare `mcp` and
@@ -15,7 +20,7 @@ export const createCli = () => {
         ? "silent"
         : parseLogLevel(process.env.REA_LOG_LEVEL));
     const cli = Cli.create(PRODUCT_IDENTITY.cliBinary, {
-        version: "0.1.0",
+        version: process.env.REA_PACKAGE_VERSION ?? "0.0.0-development",
         description: "Reverse engineer anything from your terminal or coding agent.",
         mcp: {
             command: PRODUCT_IDENTITY.mcpCommand,
@@ -31,6 +36,23 @@ export const createCli = () => {
             ],
         },
     });
+    registerCoreCommands(cli, logger);
+    registerFunctionCommand(cli, logger);
+    registerSearchCommand(cli, logger);
+    registerXrefsCommand(cli, logger);
+    registerTraceCommand(cli, logger);
+    registerCapabilityCommands(cli, logger);
+    registerNativeCommands(cli, logger);
+    registerArtifactCommands(cli, logger);
+    registerEvidenceCommands(cli, logger);
+    registerReferenceSourceCommand(cli, logger);
+    return cli;
+};
+const registerCoreCommands = (cli, logger) => {
+    const overviewOptions = z.object({
+        detail: z.enum(["concise", "detailed"]).default("concise"),
+        limit: z.number().int().min(1).max(50).default(10),
+    });
     cli.command("setup", {
         description: "Install requirements and configure coding agents",
         options: z.object({
@@ -49,12 +71,32 @@ export const createCli = () => {
         }),
         run: ({ options }) => logCliCommand(logger, "doctor", () => runDoctor(options.target)),
     });
+    cli.command("uninstall", {
+        description: "Remove REA-owned agent configuration and skill files",
+        options: z.object({
+            purgeData: z
+                .boolean()
+                .default(false)
+                .describe("Also remove REA caches and state"),
+        }),
+        alias: { purgeData: "purge-data" },
+        run: ({ options }) => logCliCommand(logger, "uninstall", () => runUninstall(options.purgeData)),
+    });
     cli.command("analyze", {
         description: "Get an overview of an app",
         args: z.object({
             path: z.string().describe("App, program, or Hopper database path"),
         }),
-        run: ({ args }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", {}, logger)),
+        options: overviewOptions,
+        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
+    });
+    cli.command("inspect", {
+        description: "Inspect an app overview with evidence",
+        args: z.object({
+            path: z.string().describe("App, program, or Hopper database path"),
+        }),
+        options: overviewOptions,
+        run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
     });
     cli.command("decompile", {
         description: "Read one part of an app as code",
@@ -64,25 +106,191 @@ export const createCli = () => {
         }),
         run: ({ args }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, logger)),
     });
-    return cli;
 };
-const logCliCommand = async (logger, command, execute) => {
-    const startedAt = performance.now();
-    try {
-        const value = await execute();
-        logger.info({
-            command,
-            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
-            status: "ok",
-        }, "CLI command completed");
-        return value;
+const registerXrefsCommand = (cli, logger) => {
+    cli.command("xrefs", {
+        description: "List bounded references to an analyzed address",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Hexadecimal address"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", { address: args.address }, logger)),
+    });
+};
+const registerTraceCommand = (cli, logger) => {
+    cli.command("trace", {
+        description: "Trace a bounded literal feature through analyzed references",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            query: z.string().min(1).describe("Literal feature query"),
+        }),
+        options: z.object({
+            caseSensitive: z.boolean().default(false),
+            limit: z.number().int().min(1).max(100).default(20),
+            maxOperations: z.number().int().min(1).max(100).default(20),
+        }),
+        alias: {
+            caseSensitive: "case-sensitive",
+            maxOperations: "max-operations",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "trace", () => runDirectAnalysis(args.path, "trace_feature", {
+            query: args.query,
+            case_sensitive: options.caseSensitive,
+            limit: options.limit,
+            max_operations: options.maxOperations,
+        }, logger)),
+    });
+};
+const registerCapabilityCommands = (cli, logger) => {
+    for (const command of ["capabilities", "providers"]) {
+        cli.command(command, {
+            description: command === "capabilities"
+                ? "List provider capabilities and side effects"
+                : "List configured analysis providers",
+            run: () => logCliCommand(logger, command, () => runSessionStatus(logger)),
+        });
     }
-    catch (cause) {
-        logger.error({
-            command,
-            durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
-            status: "error",
-        }, "CLI command failed");
-        throw cause;
+};
+const registerFunctionCommand = (cli, logger) => {
+    cli.command("function", {
+        description: "Analyze one bounded function with evidence",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Procedure name or address"),
+        }),
+        options: z.object({
+            includeAssembly: z.boolean().default(false),
+            limit: z.number().int().min(1).max(500).default(100),
+            maxPseudocodeChars: z.number().int().min(1).max(100_000).default(20_000),
+            maxInstructions: z.number().int().min(1).max(5_000).default(500),
+        }),
+        alias: {
+            includeAssembly: "include-assembly",
+            maxPseudocodeChars: "max-pseudocode-chars",
+            maxInstructions: "max-instructions",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "function", () => runDirectAnalysis(args.path, "analyze_function", {
+            procedure: args.address,
+            include_assembly: options.includeAssembly,
+            limit: options.limit,
+            max_pseudocode_chars: options.maxPseudocodeChars,
+            max_instructions: options.maxInstructions,
+        }, logger)),
+    });
+};
+const registerSearchCommand = (cli, logger) => {
+    cli.command("search", {
+        description: "Search bounded analyzed strings or procedure names",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            pattern: z.string().min(1).describe("Literal text or regex pattern"),
+        }),
+        options: z.object({
+            kind: z.enum(["strings", "procedures"]).default("strings"),
+            mode: z.enum(["literal", "regex"]).default("literal"),
+            caseSensitive: z.boolean().default(false),
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().min(1).max(100).default(100),
+        }),
+        alias: { caseSensitive: "case-sensitive" },
+        run: ({ args, options }) => logCliCommand(logger, "search", () => runDirectAnalysis(args.path, options.kind === "strings" ? "search_strings" : "search_procedures", {
+            pattern: args.pattern,
+            mode: options.mode,
+            case_sensitive: options.caseSensitive,
+            offset: options.offset,
+            limit: options.limit,
+        }, logger)),
+    });
+};
+const registerReferenceSourceCommand = (cli, logger) => {
+    cli.command("import-reference-source", {
+        description: "Import a bounded source tree as historical reference only",
+        args: z.object({
+            root: z
+                .string()
+                .describe("Source root allowed by REA_REFERENCE_ROOTS_JSON"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "import-reference-source", async () => {
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return { error: config.error._tag, message: config.error.message };
+            const imported = await importReferenceSource({
+                root: args.root,
+                caller: "rea-cli",
+                policy: config.value.referenceSourcePolicy,
+                importer: PRODUCT_IDENTITY.packageName,
+                importerVersion: null,
+            });
+            return imported.ok
+                ? imported.value
+                : { error: imported.error.code, message: imported.error.message };
+        }),
+    });
+};
+const registerArtifactCommands = (cli, logger) => {
+    cli.command("inventory-artifact", {
+        description: "Build a bounded deterministic artifact graph",
+        args: z.object({
+            path: z.string().describe("Application or package path"),
+        }),
+        options: z.object({
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().min(1).max(500).default(100),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "inventory-artifact", () => runProviderAnalysis(args.path, "inventory_artifact", {
+            node_offset: options.offset,
+            node_limit: options.limit,
+            occurrence_offset: options.offset,
+            occurrence_limit: options.limit,
+            edge_offset: options.offset,
+            edge_limit: options.limit,
+        }, logger)),
+    });
+    cli.command("extract-artifact", {
+        description: "Extract explicitly selected artifact occurrences safely",
+        args: z.object({
+            path: z.string().describe("Application or package path"),
+            outputRoot: z.string().describe("Absent absolute output root"),
+            occurrenceIds: z
+                .array(z.string().regex(/^occ_[a-f0-9]{64}$/u))
+                .min(1)
+                .max(500),
+        }),
+        alias: { outputRoot: "output-root", occurrenceIds: "occurrence-ids" },
+        run: ({ args }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
+            approved: true,
+            output_root: args.outputRoot,
+            occurrence_ids: args.occurrenceIds,
+        }, logger)),
+    });
+};
+const registerNativeCommands = (cli, logger) => {
+    for (const [command, tool] of [
+        ["inspect-macho", "inspect_macho"],
+        ["inspect-signature", "inspect_signature"],
+        ["list-architectures", "list_architectures"],
+    ]) {
+        cli.command(command, {
+            description: `Run ${tool} without launching Hopper`,
+            args: z.object({ path: z.string().describe("Mach-O or app path") }),
+            run: ({ args }) => logCliCommand(logger, command, () => runProviderAnalysis(args.path, tool, {}, logger)),
+        });
     }
+    cli.command("inspect-plist", {
+        description: "Parse app plist metadata without launching Hopper",
+        args: z.object({ path: z.string().describe("App or Mach-O path") }),
+        options: z.object({
+            relativePath: z.string().default("Contents/Info.plist"),
+        }),
+        alias: { relativePath: "relative-path" },
+        run: ({ args, options }) => logCliCommand(logger, "inspect-plist", () => runProviderAnalysis(args.path, "inspect_plist", { relative_path: options.relativePath }, logger)),
+    });
+    cli.command("demangle-swift", {
+        description: "Demangle a bounded Swift symbol batch without Hopper",
+        args: z.object({
+            path: z.string().describe("Artifact path used for evidence identity"),
+            symbols: z.array(z.string().min(1)).min(1).max(500),
+        }),
+        run: ({ args }) => logCliCommand(logger, "demangle-swift", () => runProviderAnalysis(args.path, "demangle_swift", { symbols: args.symbols }, logger)),
+    });
 };

package/dist/cliEvidenceCommands.js

@@ -0,0 +1,68 @@
+import { Cli, z } from "incur";
+import { compareEvidenceBundlesCommand, exportEvidenceBundleCommand, importEvidenceBundleCommand, } from "./application/EvidenceBundleCommands.js";
+import { parseConfig } from "./config.js";
+import { logCliCommand } from "./cliLogging.js";
+/** Register filesystem-gated Evidence v2 commands. */
+export const registerEvidenceCommands = (cli, logger) => {
+    cli.command("evidence-import", {
+        description: "Validate and import a bounded local Evidence v2 bundle",
+        args: z.object({
+            path: z.string().describe("Evidence bundle JSON path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "evidence-import", async () => {
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return { error: config.error._tag, message: config.error.message };
+            const imported = await importEvidenceBundleCommand(args.path, config.value.evidenceFilePolicy);
+            return imported.ok
+                ? imported.value
+                : { error: imported.error._tag, message: imported.error.message };
+        }),
+    });
+    cli.command("evidence-export", {
+        description: "Validate and atomically export canonical Evidence v2 JSON",
+        args: z.object({
+            source: z.string().describe("Existing evidence bundle JSON path"),
+            output: z.string().describe("Canonical output JSON path"),
+        }),
+        options: z.object({
+            overwrite: z.boolean().default(false).describe("Replace output file"),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "evidence-export", async () => {
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return { error: config.error._tag, message: config.error.message };
+            const exported = await exportEvidenceBundleCommand(args.source, args.output, options.overwrite, config.value.evidenceFilePolicy);
+            return exported.ok
+                ? exported.value
+                : { error: exported.error._tag, message: exported.error.message };
+        }),
+    });
+    cli.command("compare", {
+        aliases: ["compare-bundles"],
+        description: "Compare two canonical Evidence v2 bundles",
+        args: z.object({
+            left: z.string().describe("Left Evidence bundle JSON path"),
+            right: z.string().describe("Right Evidence bundle JSON path"),
+        }),
+        options: z.object({
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().min(1).max(500).default(100),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "compare", async () => {
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return { error: config.error._tag, message: config.error.message };
+            const compared = await compareEvidenceBundlesCommand({
+                leftPath: args.left,
+                rightPath: args.right,
+                offset: options.offset,
+                limit: options.limit,
+                policy: config.value.evidenceFilePolicy,
+            });
+            return compared.ok
+                ? compared.value
+                : { error: compared.error._tag, message: compared.error.message };
+        }),
+    });
+};