@counterfact-labs/cli 0.1.3 → 0.2.4

package/dist/adapters/anthropic.js

@@ -0,0 +1,151 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
+import { JobError } from "../analysis-core/errors.js";
+import { estimateTokensFromBytes } from "../analysis-core/llm/cost.js";
+import { anthropicStructuredLimit, supportsReasoningControls } from "../analysis-core/llm/output-limit.js";
+import { requestCachesInput, structuredPromptOf } from "./prompt-cache.js";
+import { StructuredOutputError } from "../analysis-core/llm/structured-output-error.js";
+export function anthropicLlm(settings, opts = {}) {
+    const client = opts.client ?? new Anthropic({ ...(opts.apiKey === undefined ? {} : { apiKey: opts.apiKey }) });
+    return { structured: call => structuredCall(settings, client, call, opts.onUsage, opts.sourceRetries) };
+}
+/** The recorder shares one client for counting and generation, with transport retries disabled. */
+export function anthropicCaptureBackend(client = new Anthropic({ maxRetries: 0 }), onProviderError) {
+    return { countInputTokens: (call) => anthropicInputTokens({}, client, call),
+        createModel: (onUsage) => ({
+            structured: call => structuredCall({}, client, call, onUsage, false, onProviderError),
+        }) };
+}
+function canceled() {
+    return new JobError("canceled", "The model call was canceled.");
+}
+export class ProviderCallError extends JobError {
+    payment;
+    constructor(code, message, retryable, payment) {
+        super(code, message, { retryable });
+        this.payment = payment;
+    }
+}
+/** Provider messages can quote private inputs, so retain only safe classifications. */
+function providerFailure(error, signal) {
+    if (signal?.aborted || error instanceof Anthropic.APIUserAbortError)
+        return canceled();
+    if (error instanceof Anthropic.RateLimitError) {
+        return new ProviderCallError("rate_limited", "The model provider is busy. Wait a minute and try again.", true, "unpaid");
+    }
+    if (error instanceof Anthropic.APIConnectionError) {
+        return new ProviderCallError("llm", "The model could not be reached. Try again.", true, "unknown");
+    }
+    const directive = error instanceof Anthropic.APIError ? error.headers?.get("x-should-retry") : undefined;
+    const status = error instanceof Anthropic.APIError ? error.status : undefined;
+    const retryable = directive === "true" || directive !== "false" && (status === 408 || status === 409 || status !== undefined && status >= 500);
+    const payment = status !== undefined && [400, 401, 403, 404, 413, 422].includes(status) ? "unpaid" : "unknown";
+    return new ProviderCallError("llm", "The model call failed. Try again.", retryable, payment);
+}
+function reportUsage(onUsage, call, usage, requestStartedAt, estimated = false) {
+    if (!onUsage || !usage)
+        return;
+    try {
+        onUsage({
+            route: call.route, model: call.model,
+            inputTokens: usage.input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0,
+            cacheReadTokens: usage.cache_read_input_tokens ?? 0, cacheWriteTokens: usage.cache_creation_input_tokens ?? 0,
+            ...(usage.cache_creation ? {
+                cacheWrite5mTokens: usage.cache_creation.ephemeral_5m_input_tokens,
+                cacheWrite1hTokens: usage.cache_creation.ephemeral_1h_input_tokens,
+            } : {}),
+            requestStartedAt, ...(estimated ? { estimated: true } : {}),
+        });
+    }
+    catch {
+        // Losing a usage count must not discard a completed answer. Never log sink errors.
+    }
+}
+function providerRequest(settings, call) {
+    const format = zodOutputFormat(call.schema);
+    const streamed = supportsReasoningControls(call.model);
+    const params = {
+        model: call.model, max_tokens: anthropicStructuredLimit(call),
+        ...(streamed ? { thinking: { type: call.thinking ?? "adaptive" } } : {}),
+        ...(call.system ? { system: call.system } : {}),
+        messages: [{ role: "user", content: structuredPromptOf(settings, call) }],
+        output_config: {
+            // SDK stream parsing can throw before returning usage for incomplete JSON.
+            format: { type: format.type, schema: format.schema },
+            ...(call.effort && streamed && call.thinking !== "disabled" ? { effort: call.effort } : {}),
+        },
+    };
+    return { params, format, streamed };
+}
+/** Include the provider-transformed schema and cache blocks in reservation byte admission. */
+export function anthropicInputBytes(settings, call) {
+    const { params } = providerRequest(settings, call);
+    return Buffer.byteLength(JSON.stringify({ system: params.system, messages: params.messages,
+        thinking: params.thinking, output_config: params.output_config }));
+}
+/** Capture admission counts the same SDK-transformed schema and prompt that generation sends. */
+export async function anthropicInputTokens(settings, client, call) {
+    const { params } = providerRequest(settings, call);
+    const usage = await client.messages.countTokens({ model: params.model, system: params.system, messages: params.messages,
+        thinking: params.thinking, output_config: params.output_config });
+    if (!Number.isSafeInteger(usage.input_tokens) || usage.input_tokens < 0)
+        throw new JobError("llm", "The model input could not be counted.");
+    return usage.input_tokens;
+}
+async function structuredCall(settings, client, call, onUsage, sourceRetries = false, onProviderError) {
+    const { params, format, streamed } = providerRequest(settings, call);
+    if (call.signal?.aborted)
+        throw canceled();
+    const requestStartedAt = new Date();
+    let usageReported = false;
+    const estimateOnAbort = () => {
+        if (usageReported)
+            return;
+        usageReported = true;
+        const inputTokens = estimateTokensFromBytes(Buffer.byteLength(JSON.stringify({ system: params.system,
+            messages: params.messages, output_config: { format: params.output_config.format } })));
+        const cached = requestCachesInput(settings, call);
+        reportUsage(onUsage, call, { input_tokens: cached ? 0 : inputTokens, output_tokens: params.max_tokens,
+            cache_creation_input_tokens: cached ? inputTokens : 0 }, requestStartedAt, true);
+    };
+    // Deadlines may settle before the SDK rejects; report cancellation synchronously.
+    call.signal?.addEventListener("abort", estimateOnAbort, { once: true });
+    let message;
+    try {
+        // Relay retries need fresh authorization. Only the source-checkout factory preserves its earlier SDK policy.
+        const options = { ...(!sourceRetries ? { maxRetries: 0 } : {}), ...(call.signal ? { signal: call.signal } : {}) };
+        message = streamed
+            ? await client.messages.stream(params, options).finalMessage()
+            : await client.messages.create(params, options);
+        if (!usageReported) {
+            usageReported = true;
+            reportUsage(onUsage, call, message.usage, requestStartedAt);
+        }
+    }
+    catch (error) {
+        // Only explicit capture tools retain provider diagnostics for fictional inputs.
+        try {
+            onProviderError?.(error);
+        }
+        catch { /* A diagnostic sink cannot change settlement. */ }
+        throw providerFailure(error, call.signal);
+    }
+    finally {
+        call.signal?.removeEventListener("abort", estimateOnAbort);
+    }
+    if (message.stop_reason === "refusal")
+        throw new JobError("llm", "The model declined this request. Try again.");
+    const text = message.content.find(block => block.type === "text");
+    if (text) {
+        try {
+            return format.parse(text.text);
+        }
+        catch (error) {
+            if (!(error instanceof Anthropic.AnthropicError))
+                throw error;
+        }
+    }
+    throw new StructuredOutputError(message.stop_reason === "max_tokens"
+        ? "The model ran out of room for this step's answer. Try again."
+        : "The model returned nothing usable for this step. Try again.");
+}

package/dist/adapters/completion.js

@@ -0,0 +1,112 @@
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { lstat, open, realpath } from "node:fs/promises";
+import os from "node:os";
+import { basename, dirname, join } from "node:path";
+import { z } from "zod";
+import { LOCAL_FINDINGS_BODY_LIMIT, localFindingsPayloadSchema } from "../contract/console.js";
+import { OutputPathError, outputPaths, writeOutputFiles } from "./output-paths.js";
+import { standaloneGitFailure } from "./repository-root.js";
+import { runGit } from "./git.js";
+import { resolveFolderPath } from "./folder-path.js";
+import { matchesSnapshotProvenance } from "./snapshot.js";
+const record = z.strictObject({ version: z.literal(1), consoleOrigin: z.url().optional(), uploaded: z.boolean().optional(),
+    finished: z.boolean().optional(), payload: localFindingsPayloadSchema });
+const maxBytes = LOCAL_FINDINGS_BODY_LIMIT + 1024;
+/** Recovery belongs to this checkout and origin, and survives edits and new commits. */
+export async function completionPath(folder) {
+    const root = await resolveFolderPath(folder);
+    let repository = null;
+    let common;
+    try {
+        common = (await runGit(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"])).toString("utf8").trim();
+    }
+    // Standalone folders need no Git identity; a usable checkout must never silently lose its identity.
+    catch (error) {
+        if (!await standaloneGitFailure(root, error))
+            throw error;
+    }
+    if (common !== undefined) {
+        let origin = "";
+        try {
+            origin = (await runGit(root, ["config", "--get", "remote.origin.url"])).toString("utf8").trim();
+        }
+        catch (error) {
+            if (error.code !== 1)
+                throw error;
+        }
+        repository = [await realpath(common), origin];
+    }
+    const key = createHash("sha256").update(JSON.stringify([root, repository])).digest("hex");
+    const home = await realpath(os.homedir());
+    return { home, path: join(home, ".config/counterfact-labs/completions", `${key}.json`) };
+}
+export async function saveCompletion(folder, payload, consoleOrigin, uploaded = false, finished = false) {
+    const value = record.parse({ version: 1, payload, consoleOrigin, uploaded, finished });
+    const bytes = JSON.stringify(value);
+    if (Buffer.byteLength(bytes) > maxBytes)
+        throw new Error("Invalid completion record");
+    const { home, path } = await completionPath(folder);
+    await writeOutputFiles(home, { [basename(path)]: bytes }, dirname(path));
+    return path;
+}
+const INVALID_COMPLETION_MESSAGE = "The saved completion record is invalid. Keep the local report and choose a new output directory.";
+async function readCompletion(path) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+        const info = await file.stat();
+        if (!info.isFile() || info.size > maxBytes)
+            throw new Error();
+        const bytes = Buffer.alloc(maxBytes + 1);
+        const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+        if (bytesRead > maxBytes)
+            throw new Error();
+        return record.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, bytesRead))));
+    }
+    finally {
+        await file?.close();
+    }
+}
+export async function loadCompletion(folder) {
+    try {
+        const { home, path } = await completionPath(folder);
+        await outputPaths(home, [basename(path)], dirname(path));
+        return await readCompletion(path);
+    }
+    catch (error) {
+        if (error instanceof OutputPathError)
+            throw error;
+        if (error.code !== "ENOENT") {
+            throw new Error(INVALID_COMPLETION_MESSAGE);
+        }
+    }
+    // Repository-owned records cannot supply recovery data, even with matching provenance.
+    let legacy;
+    try {
+        await lstat(join(folder, ".counterfact/completion.json"));
+        try {
+            await runGit(folder, ["ls-files", "--error-unmatch", "--with-tree=HEAD", "--", ".counterfact/completion.json"]);
+            return null;
+        }
+        catch (error) {
+            // Without Git there is no provenance to verify, and uncertain legacy data must not block analysis.
+            if (await standaloneGitFailure(folder, error))
+                return null;
+            if (error.code !== 1)
+                throw error;
+        }
+        const [path] = await outputPaths(folder, ["completion.json"]);
+        legacy = await readCompletion(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new Error(INVALID_COMPLETION_MESSAGE);
+    }
+    if (!await matchesSnapshotProvenance(folder, legacy.payload.agent))
+        throw new Error(INVALID_COMPLETION_MESSAGE);
+    // Attempt imported recovery once automatically; uncertain legacy data must not block later analyses.
+    await saveCompletion(folder, legacy.payload, legacy.consoleOrigin, legacy.uploaded, true);
+    return legacy;
+}

package/dist/adapters/durable-write.js

@@ -0,0 +1,34 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { open, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+export async function durableWrite(path, bytes) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const permission = process.permission !== undefined;
+    // The permission model disables fsync, so sync data on each write and skip the unavailable directory sync.
+    const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW | (permission ? constants.O_DSYNC : 0);
+    try {
+        const file = await open(temporary, flags, 0o600);
+        try {
+            await file.writeFile(bytes);
+            if (!permission)
+                await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+        if (!permission) {
+            const parent = await open(dirname(path), "r");
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/adapters/files.js

@@ -0,0 +1,144 @@
+import { opendir, realpath, stat, readFile } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+import { admitFile, fileRefusalWarning, localSymlinkGuardEnabled, respectGitignore, readRepoFile, resolveLocalExclusions } from "../analysis-core/conventions/file-admission.js";
+import { assessAnalysisSize, measureAnalysisSize } from "../analysis-core/conventions/analysis-fit.js";
+import { localRepoKeyFor } from "../analysis-core/github/repo-key.js";
+import { fetchLocalSources } from "../analysis-core/index.js";
+import { repoPathFrom } from "../analysis-core/import/outside-loader-sources.js";
+import { mergeSkippedFiles, mergeUnlistedFileWarnings } from "../analysis-core/analysis/code-agents/skipped-files.js";
+import { createGitIgnore } from "./git-ignore.js";
+import { createIgnoredFileCollector } from "./ignored-files.js";
+import { resolveFolderPath } from "./folder-path.js";
+import { createRepositoryFiles } from "./repository-files.js";
+export const FOLDER_ENTRY_LIMIT = 10_000;
+export const FOLDER_ENTRY_LIMIT_MESSAGE = "The folder has too many entries to analyze. Choose a smaller folder.";
+export async function readLocalFolder(settings, folder, admission = {}, options = {}) {
+    const root = await resolveFolderPath(folder);
+    if (!(await stat(root)).isDirectory())
+        throw new Error("Select a folder to analyze.");
+    const entries = [];
+    const warnings = [];
+    const refused = [];
+    const gitSkipped = [];
+    const ignoredPaths = createGitIgnore(settings, root);
+    const ignoredFiles = createIgnoredFileCollector(FOLDER_ENTRY_LIMIT);
+    const guarded = localSymlinkGuardEnabled(settings) || !!admission.exclusions?.length || respectGitignore(settings);
+    const excludedTargets = await resolveLocalExclusions(admission, async (path) => {
+        try {
+            return await realpath(join(root, path));
+        }
+        catch (error) {
+            if (["ENOENT", "ELOOP"].includes(error.code ?? ""))
+                return null;
+            throw error;
+        }
+    });
+    const targets = new Map();
+    const snapshot = {};
+    let visited = 0;
+    const targetOf = async (path, purpose, directory = false) => {
+        const target = await realpath(join(root, path));
+        const result = admitFile(settings, { path, directory }, { purpose, route: "local-folder", ...admission, localTarget: { root, path: target, excludedTargets } });
+        if (!result.admitted) {
+            refused.push({ path, reason: result.reason });
+            if (result.reason === "secret" || result.reason === "out-of-scope")
+                warnings.push({ path, reason: result.reason });
+            return null;
+        }
+        const gitIgnored = await ignoredPaths([target]);
+        const parent = gitIgnored === undefined ? undefined : await realpath(dirname(join(root, path)));
+        const allowed = admitFile(settings, { path, directory }, { purpose, route: "local-folder", ...admission,
+            gitIgnored, localTarget: { root, path: target, parent, excludedTargets } });
+        if (!allowed.admitted) {
+            if (directory)
+                gitSkipped.push(...await ignoredFiles(join(root, path), path));
+            else
+                gitSkipped.push({ path, reason: allowed.reason });
+            return null;
+        }
+        return target;
+    };
+    async function walk(dir, prefix, ancestors) {
+        const target = await realpath(dir);
+        if (ancestors.has(target))
+            return;
+        const parents = new Set([...ancestors, target]);
+        // Stream and count even excluded entries, so a huge directory cannot exhaust memory before the cap.
+        const items = [];
+        for await (const entry of await opendir(target)) {
+            if (++visited > FOLDER_ENTRY_LIMIT)
+                throw new Error(FOLDER_ENTRY_LIMIT_MESSAGE);
+            items.push(entry);
+        }
+        const names = items.map(item => item.name);
+        const facts = await ignoredPaths(names.map(name => join(target, name)));
+        const gitIgnored = facts && new Set(names.filter(name => facts.has(join(target, name))).map(name => prefix ? `${prefix}/${name}` : name));
+        for (const item of items.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+            const name = item.name;
+            const path = prefix ? `${prefix}/${name}` : name;
+            // A link's filename-only refusal waits until its target type is known.
+            const listed = { path, directory: item.isDirectory() || item.isSymbolicLink() };
+            if (!admitFile(settings, listed, { purpose: "listing", route: "local-folder", ...admission }).admitted)
+                continue;
+            const allowed = admitFile(settings, listed, { purpose: "listing", route: "local-folder", ...admission, gitIgnored });
+            if (!allowed.admitted) {
+                if (item.isDirectory())
+                    gitSkipped.push(...await ignoredFiles(join(dir, name), path));
+                else if (item.isFile() || item.isSymbolicLink())
+                    gitSkipped.push({ path, reason: allowed.reason });
+                continue;
+            }
+            let file;
+            let info;
+            try {
+                info = await stat(join(dir, name));
+                const directory = info.isDirectory();
+                if (!admitFile(settings, { path, directory }, { purpose: "listing", route: "local-folder", ...admission }).admitted)
+                    continue;
+                file = guarded ? await targetOf(path, "listing", directory) : join(root, path);
+            }
+            catch (error) {
+                if (["ENOENT", "ELOOP"].includes(error.code ?? ""))
+                    continue;
+                throw error;
+            }
+            if (!file)
+                continue;
+            if (info.isDirectory())
+                await walk(file, path, parents);
+            else if (info.isFile()) {
+                entries.push({ path, size: info.size, ref: path });
+                targets.set(path, file);
+            }
+        }
+    }
+    const selectedRoot = admitFile(settings, { path: ".", directory: true }, { purpose: "override", route: "local-folder",
+        gitIgnored: await ignoredPaths(["."]), localTarget: { root, path: root } });
+    if (selectedRoot.admitted)
+        await walk(root, "", new Set());
+    else
+        gitSkipped.push(...await ignoredFiles(root, ""));
+    const analysisSize = measureAnalysisSize(settings, entries, admission);
+    // The service makes the final decision; local prediction never changes retained files.
+    const analysisFit = settings.CF_REFUSE_TOO_LARGE === "0" ? undefined : assessAnalysisSize(analysisSize);
+    const listing = new Set(entries.map(entry => entry.path));
+    const repoKey = localRepoKeyFor(root);
+    const repository = createRepositoryFiles(settings, root, admission, options);
+    const discovered = await fetchLocalSources(settings, { repoKey, entries, admission, repository, read: async (entry) => {
+            const target = guarded ? await targetOf(entry.path, "override") : targets.get(entry.path);
+            return target ? readRepoFile(settings, entry, async () => {
+                if (!options.captureSnapshot)
+                    return readFile(target, "utf8");
+                const bytes = snapshot[entry.path] ?? await readFile(target);
+                snapshot[entry.path] = bytes;
+                return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            }, { ...admission, listing, route: "local-folder", localTarget: { root, path: target, excludedTargets } }) : null;
+        } });
+    const expanded = discovered.root !== undefined;
+    const ignored = mergeSkippedFiles(expanded ? gitSkipped.map(file => ({ ...file, path: repoPathFrom(file.path, discovered.root) })) : gitSkipped, repository.skippedFiles.map(file => ({ ...file, path: expanded ? file.path : posix.relative(repository.selectedRoot ?? "", file.path) })));
+    const captured = { ...Object.fromEntries(Object.entries(snapshot).map(([path, bytes]) => [repoPathFrom(path, discovered.root), bytes])), ...repository.snapshot };
+    return { repoKey, files: discovered.files, analysisSize, ...(analysisFit ? { analysisFit } : {}), ...(expanded ? { root: discovered.root, sourceBase: repository.sourceBase } : {}),
+        ...(options.captureSnapshot ? { snapshot: Object.fromEntries(Object.keys(discovered.files).map(path => [path, captured[path]])) } : {}), fragment: discovered.fragment, selection: discovered.selection,
+        skippedFiles: mergeSkippedFiles(discovered.skippedFiles, ignored, expanded ? refused.map(file => ({ ...file, path: repoPathFrom(file.path, discovered.root) })) : refused),
+        warnings: [...new Set(mergeUnlistedFileWarnings([...warnings.map(file => fileRefusalWarning(repoPathFrom(file.path, discovered.root), file.reason)), ...discovered.warnings], ignored.length))] };
+}

package/dist/adapters/folder-path.js

@@ -0,0 +1,6 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+/** Folder consumers share the same canonical coordinate for reads and output. */
+export async function resolveFolderPath(folder) {
+    return realpath(resolve(folder));
+}

package/dist/adapters/git-ignore.js

@@ -0,0 +1,49 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { mapLimit } from "../analysis-core/map-limit.js";
+import { respectGitignore } from "../analysis-core/conventions/file-admission.js";
+import { runGit } from "./git.js";
+import { gitRepositoryRoot, searchBaseMatches, searchBoundary } from "./repository-root.js";
+/** Query path facts only; admission owns whether an ignored path can be read. */
+export function createGitIgnore(settings, folder) {
+    const cache = new Map();
+    let root;
+    return async (paths) => {
+        if (!respectGitignore(settings))
+            return undefined;
+        if (!paths.length)
+            return new Set();
+        const base = await (root ??= (async () => {
+            const [boundary, reported] = await Promise.all([searchBoundary(folder),
+                gitRepositoryRoot(async (args) => (await runGit(folder, args)).toString("utf8"))]);
+            return boundary && await searchBaseMatches(boundary.base, reported) ? boundary.base : null;
+        })());
+        if (!base)
+            return undefined;
+        const candidates = paths.filter(path => {
+            const rel = relative(base, resolve(folder, path));
+            return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+        });
+        const pending = [...new Set(candidates.map(path => resolve(folder, path)))].filter(path => !cache.has(path));
+        // Bound each process's input and output without losing unusual filenames to line quoting.
+        const batches = Array.from({ length: Math.ceil(pending.length / 100) }, (_, index) => pending.slice(index * 100, (index + 1) * 100));
+        await mapLimit(batches, 4, async (batch) => {
+            const input = Buffer.from(batch.map(path => resolve(folder, path)).join("\0") + "\0");
+            let output;
+            try {
+                output = await runGit(folder, ["check-ignore", "-z", "--stdin"], { userConfig: true, input, maxBuffer: input.length + 1024 });
+            }
+            catch (error) {
+                if (error.code === 1) {
+                    for (const path of batch)
+                        cache.set(path, false);
+                    return;
+                }
+                throw error;
+            }
+            const matches = new Set(output.toString("utf8").split("\0"));
+            for (const path of batch)
+                cache.set(path, matches.has(path));
+        });
+        return new Set(candidates.filter(path => cache.get(resolve(folder, path))));
+    };
+}

package/dist/adapters/git.js

@@ -0,0 +1,44 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+/** All repository subprocesses use the same local-only, non-executable Git policy. */
+export async function runGit(folder, args, options = {}) {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")));
+    const execute = async (command, overrides = [], maxBuffer = options.maxBuffer ?? 16_384, input) => {
+        const running = promisify(execFile)("git", ["--no-pager", "--no-optional-locks",
+            "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "core.sshCommand=",
+            "-c", "protocol.ext.allow=never", "-c", "diff.external=", "-c", "core.attributesFile=/dev/null",
+            ...overrides, "-C", folder, ...command], {
+            encoding: "buffer", timeout: options.timeout ?? 3000, maxBuffer,
+            env: { ...env, GIT_ATTR_NOSYSTEM: "1", GIT_NO_REPLACE_OBJECTS: "1", GIT_NO_LAZY_FETCH: "1", GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1",
+                GIT_CONFIG_GLOBAL: options.userConfig ? process.env.GIT_CONFIG_GLOBAL : "/dev/null", GIT_PAGER: "cat" },
+        });
+        if (input)
+            running.child.stdin?.end(input);
+        return (await running).stdout;
+    };
+    // Reading configuration runs no filters. Disable every filter and diff driver before any command touches working files.
+    let configured;
+    try {
+        configured = await execute(["config", "--null", "--name-only", "--get-regexp", "^(filter|diff)\\."], [], 1024 * 1024);
+    }
+    catch (error) {
+        if (error.code !== 1)
+            throw error;
+        configured = Buffer.alloc(0);
+    }
+    const filters = new Set(), diffs = new Set();
+    for (const key of configured.toString("utf8").split("\0")) {
+        const match = /^(filter|diff)\.([\s\S]+)\.[^.]+$/i.exec(key);
+        if (match)
+            (match[1].toLowerCase() === "filter" ? filters : diffs).add(match[2]);
+    }
+    const overrides = [
+        ...[...filters].flatMap(name => ["clean=", "smudge=", "process=", "required=false"].flatMap(value => ["-c", `filter.${name}.${value}`])),
+        ...[...diffs].flatMap(name => ["command=", "textconv="].flatMap(value => ["-c", `diff.${name}.${value}`])),
+    ];
+    // These commands can consult named diff drivers even when diff.external is empty.
+    const diffCommand = ["diff", "diff-files", "diff-index", "diff-tree", "show", "log"].includes(args[0]);
+    const boundary = args.indexOf("--"), endOptions = boundary === -1 ? args.length : boundary;
+    const command = diffCommand ? [...args.slice(0, endOptions), "--no-ext-diff", "--no-textconv", ...args.slice(endOptions)] : args;
+    return execute(command, overrides, options.maxBuffer, options.input);
+}

package/dist/adapters/ignored-files.js

@@ -0,0 +1,36 @@
+import { lstat, opendir } from "node:fs/promises";
+import { join } from "node:path";
+/** Count metadata only, sharing a walk-sized budget across all ignored trees. */
+export function createIgnoredFileCollector(limit) {
+    let remaining = limit;
+    return async (folder, prefix) => {
+        const files = [];
+        const pending = [{ folder, prefix }];
+        while (pending.length && remaining > 0) {
+            const directory = pending.pop();
+            let handle;
+            try {
+                if ((await lstat(directory.folder)).isSymbolicLink()) {
+                    remaining--;
+                    files.push({ path: directory.prefix, reason: "excluded" });
+                    continue;
+                }
+                handle = await opendir(directory.folder);
+            }
+            catch {
+                continue;
+            }
+            for await (const entry of handle) {
+                if (remaining-- <= 0)
+                    return files;
+                const path = directory.prefix ? `${directory.prefix}/${entry.name}` : entry.name;
+                if (entry.isDirectory())
+                    pending.push({ folder: join(directory.folder, entry.name), prefix: path });
+                // Git stores a link as a file; following it could leave the ignored tree or loop.
+                else if (entry.isFile() || entry.isSymbolicLink())
+                    files.push({ path, reason: "excluded" });
+            }
+        }
+        return files;
+    };
+}

package/dist/adapters/instructions.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInstructionText } from "../analysis-core/requests/instruction-text.js";
+import { createRequestTools } from "../analysis-core/requests/tools.js";
+import { createTemplateVersion } from "../analysis-core/requests/template-version.js";
+import { sealedBundle } from "../contract/messages.js";
+import { verifyRelease } from "../bundle/seal/signature.js";
+export { loadPublicRequestTools } from "./public-instructions.js";
+export { openBundle as loadEncryptedInstructions } from "../bundle/seal/open.js";
+export function loadPublicInstructionVersions(value, verificationKey) {
+    const bundle = sealedBundle.parse(value);
+    verifyRelease(bundle, verificationKey);
+    return createTemplateVersion(bundle.metadata);
+}
+export function loadReadableInstructions(folder) {
+    const root = resolve(folder ?? fileURLToPath(new URL("../packages/core/instructions/", import.meta.url)));
+    const templatesPath = join(root, "templates");
+    if (!existsSync(templatesPath))
+        throw new Error("This package needs the sealed relay for analysis. Use a source checkout for local analysis.");
+    const templates = Object.freeze(Object.fromEntries(readdirSync(templatesPath).filter(name => name.endsWith(".md")).map(name => [
+        name.slice(0, -3), readFileSync(join(templatesPath, name), "utf8"),
+    ])));
+    const descriptions = Object.freeze(JSON.parse(readFileSync(join(root, "descriptions.json"), "utf8")));
+    return createInstructionText({ templates, descriptions });
+}
+let readable;
+let tools;
+// Loading is lazy so a relay can open encrypted instructions without readable assets.
+export function readableInstructions() {
+    return readable ??= loadReadableInstructions();
+}
+export function readableRequestTools() {
+    return tools ??= createRequestTools(readableInstructions());
+}