@counterfact-labs/cli 0.1.2 → 0.2.3

package/dist/adapters/models.js

@@ -0,0 +1,51 @@
+import { executeStructuredRequest } from "../analysis-core/llm/execution.js";
+import { findingHeadlinesEnabled } from "../analysis-core/settings.js";
+import { headlineRequest } from "../analysis-core/analysis/headlines/input.js";
+import { retryCalls } from "../analysis-core/llm/slots.js";
+import { relayModel, ModelConfigurationError } from "../gatekeeper/model.js";
+import { readableRequestTools, readableInstructions } from "./instructions.js";
+import { loadPublicRequestTools } from "./public-instructions.js";
+export async function sourceModel(settings, apiKey, llm) {
+    if (!llm && !apiKey?.trim())
+        throw new ModelConfigurationError("Set ANTHROPIC_API_KEY to run local analysis.");
+    const provider = llm ?? (await import("./anthropic.js")).anthropicLlm(settings, { apiKey, sourceRetries: true });
+    return localModel(provider);
+}
+export { ModelConfigurationError } from "../gatekeeper/model.js";
+export function localModel(llm, requests = readableRequestTools()) {
+    return {
+        settleStartedOnError: llm.settleStartedOnError,
+        withRetry: retry => localModel(retryCalls(llm, retry), requests),
+        execute(request, options = {}) {
+            return executeStructuredRequest(llm, requests, request, options);
+        },
+    };
+}
+// Transport and planning must use the same release before any customer files are read.
+export async function selectAnalysisExecution(transport, source, relay) {
+    if (transport.CF_LOCAL_RELAY !== "1") {
+        return { model: await source(), requestTools: readableRequestTools(), instructions: async () => readableInstructions() };
+    }
+    if (!relay)
+        throw new ModelConfigurationError("Relay mode requires relay configuration");
+    if (!relay.instructions)
+        throw new ModelConfigurationError("Relay mode requires signed instruction metadata");
+    let requestTools;
+    try {
+        requestTools = loadPublicRequestTools(relay.instructions.bundle, relay.instructions.verificationKey);
+    }
+    catch {
+        throw new ModelConfigurationError("Invalid signed instruction metadata");
+    }
+    if (relay.bundleVersion !== requestTools.bundleVersion)
+        throw new ModelConfigurationError("Relay bundle version does not match signed instruction metadata");
+    return { model: relayModel({ ...relay, bundleVersion: requestTools.bundleVersion }), requestTools,
+        instructions: async () => { throw new Error("Readable instructions are unavailable in relay mode"); } };
+}
+export async function analysisExecution(model, options = {}, settings = {}) {
+    const execution = options.execution ?? await selectAnalysisExecution(options.transport ?? {}, () => "execute" in model ? model : localModel(model), options.relay);
+    // Validate enabled result support before earlier stages can spend, even for supplied executions.
+    if (findingHeadlinesEnabled(settings))
+        execution.requestTools.headlinePlan(headlineRequest([]));
+    return execution;
+}

package/dist/adapters/output-paths.js

@@ -0,0 +1,92 @@
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { FINISH_FAILURE_MESSAGE } from "../contract/cli-refusals.js";
+import { resolveFolderPath } from "./folder-path.js";
+import { durableWrite } from "./durable-write.js";
+export class OutputPathError extends Error {
+    constructor() {
+        super(FINISH_FAILURE_MESSAGE);
+    }
+}
+const missing = (error) => error.code === "ENOENT";
+const within = (base, path) => {
+    const rel = relative(base, path);
+    return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+};
+/** Validate the selected anchor and every output component before creating or replacing files. */
+export async function outputPaths(folder, names, outputDir, create = false) {
+    const selected = resolve(folder), root = await resolveFolderPath(folder);
+    const requested = resolve(outputDir ?? join(selected, ".counterfact"));
+    let directory = within(selected, requested) ? resolve(root, relative(selected, requested)) : requested;
+    const external = !within(root, directory);
+    const userUid = process.getuid?.();
+    let systemUid;
+    let anchor = root;
+    while (!within(anchor, directory))
+        anchor = dirname(anchor);
+    try {
+        // Canonicalize both coordinates before comparing them; aliases of the selected base are safe.
+        const canonicalAnchor = await realpath(anchor);
+        directory = resolve(canonicalAnchor, relative(anchor, directory));
+        anchor = canonicalAnchor;
+        const components = [anchor];
+        for (const part of relative(anchor, directory).split(sep).filter(Boolean))
+            components.push(join(components.at(-1), part));
+        for (const path of components) {
+            if (create && path !== anchor) {
+                try {
+                    await mkdir(path, { mode: 0o700 });
+                }
+                catch (error) {
+                    if (error.code !== "EEXIST")
+                        throw error;
+                }
+            }
+            const info = await lstat(path);
+            if (!info.isDirectory())
+                throw new OutputPathError();
+            if (userUid !== undefined && info.uid !== userUid) {
+                // External output may cross protected system parents, including sticky temporary directories.
+                const sharedSystemParent = external && path !== directory &&
+                    ((info.mode & 0o022) === 0 || (info.mode & 0o1000) !== 0);
+                if (!sharedSystemParent)
+                    throw new OutputPathError();
+                // Containers can map system uids. User-owned trees need no access outside their permission boundary.
+                systemUid ??= (await lstat(parse(directory).root)).uid;
+                if (info.uid !== systemUid)
+                    throw new OutputPathError();
+            }
+        }
+        const paths = [];
+        for (const name of names) {
+            if (!name || name === "." || name === ".." || /[\\/]/.test(name))
+                throw new OutputPathError();
+            const path = join(directory, name);
+            try {
+                const info = await lstat(path);
+                if (!info.isFile() || userUid !== undefined && info.uid !== userUid)
+                    throw new OutputPathError();
+            }
+            catch (error) {
+                if (!missing(error))
+                    throw error;
+            }
+            paths.push(path);
+        }
+        return paths;
+    }
+    catch (error) {
+        if (!create && missing(error))
+            throw error;
+        throw new OutputPathError();
+    }
+}
+export async function writeOutputFiles(folder, files, outputDir) {
+    const names = Object.keys(files);
+    const paths = await outputPaths(folder, names, outputDir, true);
+    for (let index = 0; index < paths.length; index++) {
+        await outputPaths(folder, names, outputDir);
+        await durableWrite(paths[index], files[names[index]]);
+    }
+    return paths;
+}

package/dist/adapters/prompt-cache.js

@@ -0,0 +1,28 @@
+import { readJobSettings } from "./settings.js";
+export { promptCacheEnabled } from "../analysis-core/llm/cache-policy.js";
+import { promptCachePolicy } from "../analysis-core/llm/cache-policy.js";
+export function promptCacheSettings(enabled) {
+    return readJobSettings({ CF_PROMPT_CACHE: enabled ? "1" : "0" });
+}
+/** A block boundary must never insert whitespace into the original text. */
+export function textOf(text) {
+    return typeof text === "string" ? text : text.map(b => b.text).join("");
+}
+export function anthropicText(text) {
+    if (typeof text === "string")
+        return text;
+    if (text.filter(block => block.cache).length > 4)
+        throw new Error("A request can have at most four cache breakpoints.");
+    return text.map(block => ({ type: "text", text: block.text,
+        ...(block.cache ? { cache_control: { type: "ephemeral" } } : {}) }));
+}
+/** Validate even with caching off so estimates and the request cannot drift. */
+export function structuredPromptOf(settings, call) {
+    if (call.promptBlocks && textOf(call.promptBlocks) !== call.prompt)
+        throw new Error("Structured text blocks must match the prompt.");
+    const policy = promptCachePolicy(settings, { promptBlocks: call.promptBlocks });
+    return anthropicText(policy.enabled ? call.promptBlocks ?? call.prompt : call.prompt);
+}
+export function requestCachesInput(settings, call) {
+    return promptCachePolicy(settings, { promptBlocks: call.promptBlocks }).ttl !== null;
+}

package/dist/adapters/public-instructions.js

@@ -0,0 +1,36 @@
+import { findingHeadlinesEnabled } from "../analysis-core/settings.js";
+import { callInputBytes } from "../analysis-core/requests/registry.js";
+import { createTemplateVersion } from "../analysis-core/requests/template-version.js";
+import { checkDiagnosticsText } from "../analysis-core/requests/check-diagnostics.js";
+import { shapeFindingData, assertShapeFindingBytes } from "../analysis-core/requests/shape-finding-input.js";
+import { HEADLINE_RESULT_VERSION } from "../analysis-core/analysis/headlines/types.js";
+import { sealedBundle } from "../contract/messages.js";
+import { verifyRelease } from "../bundle/seal/signature.js";
+export function loadPublicRequestTools(value, verificationKey, settings = {}) {
+    const bundle = sealedBundle.parse(value);
+    verifyRelease(bundle, verificationKey);
+    const versions = createTemplateVersion(bundle.metadata);
+    const renderingUnavailable = () => { throw new Error("Instruction rendering requires the sealed relay"); };
+    if (findingHeadlinesEnabled(settings) && bundle.metadata.headlinePlan?.resultVersion !== HEADLINE_RESULT_VERSION)
+        renderingUnavailable();
+    return { ...versions, bundleVersion: bundle.version, modelReaderPrompt: renderingUnavailable, callInputBytes, checkDiagnosticsText,
+        buildAnalysisCall: renderingUnavailable,
+        headlinePlan(request) {
+            const plan = bundle.metadata.headlinePlan;
+            if (plan?.resultVersion !== HEADLINE_RESULT_VERSION)
+                return renderingUnavailable();
+            const data = JSON.stringify(request.inputs.evidence);
+            return { inputBytes: plan.inputOverheadBytes + plan.evidenceCopies * Buffer.byteLength(data),
+                identity: { registry: plan.fingerprint, resultVersion: plan.resultVersion, data }, relayValidated: true };
+        },
+        // Relay audit counts describe the envelope; rendered ceilings are enforced inside the relay.
+        checkPayloadBytes: input => Buffer.byteLength(JSON.stringify(input)),
+        validateShapeInput({ findings }) {
+            if (!findings.length)
+                return;
+            const bytes = versions.templateBytes("analysis-split-check-finding-input-1") - Buffer.byteLength("{{v0}}")
+                + Buffer.byteLength(shapeFindingData(findings)) + Buffer.byteLength("\n\n");
+            assertShapeFindingBytes(bytes);
+        },
+    };
+}

package/dist/adapters/quality.js

@@ -0,0 +1,6 @@
+import { readFindingQualityConfig as readSharedConfig } from "../analysis-core/analysis/finding-quality/config.js";
+import { readableRequestTools } from "./instructions.js";
+// Local startup has one provider and has not approved recall or imported code evidence.
+export function readLocalQualityConfig(settings, tools = readableRequestTools()) {
+    return readSharedConfig(settings, tools, { codeInputs: false, recall: false, secondOpinion: false });
+}

package/dist/adapters/relay-plan.js

@@ -0,0 +1,15 @@
+import { sealedBundleHash } from "../bundle/seal/signature.js";
+import { checkPlannedCallsAgainstBundle } from "../bundle/seal/planned-calls.js";
+import { localCallPlan } from "../analysis-core/requests/local-plan.js";
+import { relayPlanSchema } from "../contract/console.js";
+/** Callers authenticate the release before reading files; only this owner turns source facts into a paid plan. */
+export function prepareRelayPlan({ bundle, tools, relayVersion, settings, source }) {
+    const files = Object.entries(source.files).map(([path, text]) => ({ path, size: Buffer.byteLength(text) }));
+    const calls = localCallPlan(settings, files, {
+        structureState: { repos: [{ key: source.repoKey, kind: "fs", files: source.files, ...(source.root !== undefined ? { root: source.root } : {}) }], mapped: [source.fragment] },
+    });
+    checkPlannedCallsAgainstBundle(bundle, calls);
+    return { files, plan: relayPlanSchema.parse({ bundleVersion: tools.bundleVersion,
+            bundleHash: sealedBundleHash(bundle), relayVersion,
+            calls: calls.map(({ routeId, model, calls, maxInputBytes, maxInputTokens, maxOutputTokens }) => ({ routeId, model, calls, maxInputBytes, maxInputTokens, maxOutputTokens })) }) };
+}

package/dist/adapters/release.js

@@ -0,0 +1,57 @@
+import { createHash, createPublicKey } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { sealedBundle } from "../contract/messages.js";
+import { loadPublicRequestTools } from "./public-instructions.js";
+import { relayOrigin } from "../gatekeeper/connection.js";
+import { z } from "zod";
+import { cliRefusals } from "../contract/cli-refusals.js";
+import { RELEASE_KEY_SPKI_SHA256 } from "../contract/release-key.js";
+const releasePins = z.object({ verificationKey: z.string().min(1), relayVersion: z.string().min(1), localVersion: z.string().min(1),
+    relayUrl: z.string().min(1), projectContext: z.literal("checks") });
+export function readClientReleasePins(value) {
+    const pins = releasePins.parse(value);
+    relayOrigin(pins.relayUrl);
+    return Object.freeze(pins);
+}
+/** Injected releases must pass the same checks as releases loaded from disk. */
+export function validateClientRelease(release, settings = {}) {
+    const bundle = sealedBundle.parse(release.bundle);
+    const tools = loadPublicRequestTools(bundle, release.verificationKey, settings);
+    if (!bundle.relayVersions.includes(release.relayVersion))
+        throw new Error();
+    return { bundle, tools };
+}
+export function readClientReleaseKey(pem) {
+    const key = createPublicKey(pem);
+    const hash = createHash("sha256").update(key.export({ type: "spki", format: "der" })).digest("hex");
+    if (hash !== RELEASE_KEY_SPKI_SHA256)
+        throw new Error(cliRefusals.release_unavailable);
+    return key;
+}
+/** Installed releases always use the separately reviewed signing key. */
+export function loadInstalledRelease(paths) {
+    return loadRelease(paths, false);
+}
+/** Source-only development startup already requires explicit paths and development trust. */
+export function loadDevelopmentRelease(paths) {
+    return loadRelease(paths, true);
+}
+async function loadRelease(paths, development) {
+    try {
+        const base = new URL(import.meta.url.endsWith(".ts") ? "../bundle/" : "../../bundle/", import.meta.url);
+        const metadata = JSON.parse(await readFile(paths?.metadata ?? new URL("client-release.json", base), "utf8"));
+        const pins = paths ? metadata : readClientReleasePins(metadata);
+        if (typeof pins.verificationKey !== "string" || typeof pins.relayVersion !== "string" || !pins.relayVersion ||
+            typeof pins.localVersion !== "string" || !pins.localVersion)
+            throw new Error();
+        const verificationKey = development ? createPublicKey(pins.verificationKey) : readClientReleaseKey(pins.verificationKey);
+        const bundle = JSON.parse(await readFile(paths?.bundle ?? new URL("sealed.json", base), "utf8"));
+        const release = { bundle, verificationKey, relayVersion: pins.relayVersion, localVersion: pins.localVersion,
+            relayUrl: pins.relayUrl, projectContext: pins.projectContext };
+        validateClientRelease(release);
+        return release;
+    }
+    catch {
+        throw new Error(cliRefusals.release_unavailable);
+    }
+}

package/dist/adapters/report.js

@@ -0,0 +1,29 @@
+import { rankFindings } from "../analysis-core/analysis/finding-quality/policy.js";
+import { attachHeadlineResults } from "../analysis-core/analysis/headlines/attachment.js";
+/** The local view keeps presentation ranking and reading diagnostics beside the shared result. */
+export function buildLocalReport(repoKey, result, state) {
+    const quality = result.findingQuality;
+    const checked = { ...(state.findingCheck?.state?.result ?? { kept: result.findings, dropped: [], warnings: [] }) };
+    // Source explanations refresh the audit without changing the saved checker decision.
+    if (quality?.assessments && checked.qualityAudit)
+        checked.qualityAudit = {
+            coverage: quality.coverage ?? [], verdicts: quality.verdicts ?? [], assessments: quality.assessments,
+            ...(quality.shadow ? { shadow: quality.shadow } : {}),
+        };
+    const attached = attachHeadlineResults(result.findings, result.structures, result.findingHeadlines ?? [], result.findingHeadlineDiagnostics);
+    const wording = new Map(attached.rows.filter(row => row.target === "finding")
+        .map(row => [row.index, { headline: row.headline, ifLeft: row.ifLeft }]));
+    const structureWording = new Map(attached.rows.filter(row => row.target === "structure")
+        .map(row => [row.index, { headline: row.headline, ifLeft: row.ifLeft }]));
+    const structures = structureWording.size ? result.structures.map((proposal, index) => structureWording.has(index)
+        ? { ...proposal, ...structureWording.get(index) } : proposal) : result.structures;
+    const findings = wording.size
+        ? result.findings.map((finding, index) => wording.has(index) ? { ...finding, ...wording.get(index) } : finding)
+        : result.findings;
+    const ranked = state.findingQuality?.config.switches.ranking ? rankFindings(findings, quality?.assessments ?? []) : undefined;
+    return { repoKey, findings: ranked?.ordered ?? findings, structures, graph: result.graph, warnings: result.warnings,
+        ...(attached.diagnostics ? { findingHeadlineDiagnostics: attached.diagnostics } : {}),
+        skippedFiles: state.inspectPlan?.skipped ?? [], passes: state.inspectPlan?.passes.length ?? 1, findingCheck: checked,
+        ...(ranked ? { ranking: { defaultIds: ranked.defaultIds, hiddenIds: ranked.hiddenIds, emptyMessage: ranked.emptyMessage } } : {}),
+    };
+}

package/dist/adapters/repository-files.js

@@ -0,0 +1,199 @@
+import { constants } from "node:fs";
+import { lstat, open, opendir, realpath, stat } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { READ_LIMITS } from "../analysis-core/import/outside-loader-sources.js";
+import { admitFile, FileReadRefusal, readRepoFile, resolveLocalExclusions } from "../analysis-core/conventions/file-admission.js";
+import { createGitIgnore } from "./git-ignore.js";
+import { createIgnoredFileCollector } from "./ignored-files.js";
+import { searchBaseMatches, searchBoundary } from "./repository-root.js";
+/** Construction does no I/O. Discovery is initialized only by the owner's request. */
+export function createRepositoryFiles(settings, folder, admission = {}, options = {}) {
+    const guarded = { ...settings, CF_LOCAL_SYMLINK_GUARD: "1" };
+    let contextPromise;
+    let accepted = null;
+    let listingPromise;
+    const listed = new Set();
+    const snapshot = {};
+    const skippedFiles = [];
+    const ignoredPaths = createGitIgnore(settings, folder);
+    const ignoredFiles = createIgnoredFileCollector(READ_LIMITS.archive.files);
+    const context = () => contextPromise ??= (async () => {
+        if (Object.hasOwn(options, "expectedRepositoryRoot") && !options.expectedRepositoryRoot)
+            return null;
+        const boundary = await searchBoundary(folder);
+        if (!boundary || Object.hasOwn(options, "expectedRepositoryRoot") && !await searchBaseMatches(boundary.base, options.expectedRepositoryRoot))
+            return null;
+        const rebased = { ...admission, ...(admission.exclusions ? { exclusions: admission.exclusions.map(path => boundary.selectedRoot ? `${boundary.selectedRoot}/${path}` : path) } : {}) };
+        const excludedTargets = await resolveLocalExclusions(rebased, async (path) => {
+            try {
+                return await realpath(join(boundary.base, path));
+            }
+            catch {
+                return null;
+            }
+        });
+        accepted = { ...boundary, admission: rebased, excludedTargets };
+        return accepted;
+    })();
+    const repoPath = (base, target) => relative(base, target).split(sep).join("/");
+    const admit = async (ctx, path, target, size, directory = false) => {
+        const ask = { purpose: "listing", route: "local-folder", ...ctx.admission, localTarget: { root: ctx.base, path: target, excludedTargets: ctx.excludedTargets } };
+        const lexical = admitFile(guarded, { path, size, directory }, ask);
+        // An innocent alias cannot hide a secret or a hidden directory in its target.
+        const canonical = lexical.admitted ? admitFile(guarded, { path: repoPath(ctx.base, target), size, directory }, ask) : lexical;
+        if (!canonical.admitted)
+            return canonical;
+        const gitIgnored = await ignoredPaths([join(ctx.base, path), target]);
+        const allowed = admitFile(guarded, { path, size, directory }, { ...ask, gitIgnored });
+        if (!allowed.admitted) {
+            if (directory)
+                skippedFiles.push(...await ignoredFiles(join(ctx.base, path), path));
+            else
+                skippedFiles.push({ path, reason: allowed.reason });
+        }
+        return allowed;
+    };
+    const list = () => listingPromise ??= (async () => {
+        const ctx = await context();
+        if (!ctx)
+            return { entries: [], entriesVisited: 0, truncated: false };
+        const candidates = [];
+        const directories = new Set();
+        let entriesVisited = 0, truncated = false;
+        async function walk(dir, prefix) {
+            if (directories.has(dir))
+                return;
+            directories.add(dir);
+            let handle;
+            try {
+                handle = await opendir(dir);
+            }
+            catch {
+                return;
+            }
+            try {
+                while (true) {
+                    if (entriesVisited >= READ_LIMITS.archive.files) {
+                        truncated = true;
+                        return;
+                    }
+                    const item = await handle.read();
+                    if (!item)
+                        return;
+                    entriesVisited++;
+                    const path = prefix ? `${prefix}/${item.name}` : item.name;
+                    // A link's filename-only refusal waits until its target type is known.
+                    const listed = { path, directory: item.isDirectory() || item.isSymbolicLink() };
+                    if (!admitFile(guarded, listed, { purpose: "listing", route: "local-folder", ...ctx.admission }).admitted)
+                        continue;
+                    try {
+                        const lexical = join(dir, item.name);
+                        const facts = await ignoredPaths([lexical]);
+                        const gitIgnored = facts && new Set(facts.has(lexical) ? [path] : []);
+                        const allowed = admitFile(guarded, listed, { purpose: "listing", route: "local-folder", ...ctx.admission, gitIgnored });
+                        if (!allowed.admitted) {
+                            if (item.isDirectory())
+                                skippedFiles.push(...await ignoredFiles(join(dir, item.name), path));
+                            else if (item.isFile() || item.isSymbolicLink())
+                                skippedFiles.push({ path, reason: allowed.reason });
+                            continue;
+                        }
+                        const target = await realpath(join(dir, item.name));
+                        const info = await stat(target);
+                        if (!(await admit(ctx, path, target, undefined, info.isDirectory())).admitted)
+                            continue;
+                        if (info.isDirectory()) {
+                            // A nested marker establishes a different search boundary, even if invalid.
+                            try {
+                                await lstat(join(target, ".git"));
+                                continue;
+                            }
+                            catch (error) {
+                                if (error.code !== "ENOENT")
+                                    continue;
+                            }
+                            await walk(target, repoPath(ctx.base, target));
+                            if (truncated)
+                                return;
+                        }
+                        else if (info.isFile()) {
+                            const canonical = repoPath(ctx.base, target);
+                            candidates.push({ entry: { path: canonical, size: info.size, ref: canonical }, target });
+                        }
+                    }
+                    catch { /* Missing, looping and unreadable targets supply no metadata. */ }
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        await walk(ctx.base, "");
+        candidates.sort((a, b) => a.entry.path < b.entry.path ? -1 : a.entry.path > b.entry.path ? 1 : 0);
+        const targets = new Set();
+        const entries = [];
+        for (const { entry, target } of candidates) {
+            if (targets.has(target))
+                continue;
+            targets.add(target);
+            listed.add(entry.path);
+            entries.push(entry);
+        }
+        return { entries, entriesVisited, truncated };
+    })();
+    return {
+        snapshot, skippedFiles, get sourceBase() { return accepted?.base; }, get selectedRoot() { return accepted?.selectedRoot; },
+        finish(paths) {
+            const keep = new Set(paths);
+            for (const path of Object.keys(snapshot))
+                if (!keep.has(path))
+                    delete snapshot[path];
+        },
+        context: async () => { const ctx = await context(); return ctx ? { selectedRoot: ctx.selectedRoot } : null; },
+        list,
+        async read(entry, maxBytes) {
+            let bytesRead = 0;
+            let handle;
+            try {
+                const ctx = await context();
+                if (!ctx || !listed.has(entry.path))
+                    return { text: null, bytesRead, refusal: "out-of-scope" };
+                const target = await realpath(join(ctx.base, entry.path));
+                const allowed = await admit(ctx, entry.path, target, entry.size);
+                if (!allowed.admitted)
+                    return { text: null, bytesRead, refusal: allowed.reason };
+                const boundary = await searchBoundary(dirname(target));
+                if (!boundary || !await searchBaseMatches(boundary.base, ctx.base))
+                    return { text: null, bytesRead, refusal: "out-of-scope" };
+                const capacity = Math.min(maxBytes, READ_LIMITS.codeScan.fileBytes + 1);
+                if (!Number.isSafeInteger(capacity) || capacity <= 0)
+                    return { text: null, bytesRead, refusal: "scan-limit" };
+                handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                if (!(await handle.stat()).isFile())
+                    return { text: null, bytesRead, refusal: "unreadable" };
+                const buffer = Buffer.alloc(capacity);
+                let complete = false;
+                while (bytesRead < capacity) {
+                    const result = await handle.read(buffer, bytesRead, Math.min(65_536, capacity - bytesRead), null);
+                    bytesRead += result.bytesRead;
+                    if (!result.bytesRead) {
+                        complete = true;
+                        break;
+                    }
+                }
+                if (!complete || bytesRead > entry.size || bytesRead > READ_LIMITS.codeScan.fileBytes)
+                    return { text: null, bytesRead, refusal: "too-large" };
+                const bytes = buffer.subarray(0, bytesRead);
+                const text = await readRepoFile(guarded, entry, async () => new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes), { ...ctx.admission, route: "local-folder", listing: listed, localTarget: { root: ctx.base, path: target, excludedTargets: ctx.excludedTargets } });
+                snapshot[entry.path] = bytes;
+                return { text, bytesRead };
+            }
+            catch (error) {
+                return { text: null, bytesRead, refusal: error instanceof FileReadRefusal && error.reason === "secret-content" ? error.reason : "unreadable" };
+            }
+            finally {
+                await handle?.close();
+            }
+        },
+    };
+}

package/dist/adapters/repository-root.js

@@ -0,0 +1,120 @@
+import { access, constants, lstat, open, realpath, stat } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+export async function gitRepositoryRoot(git) {
+    try {
+        return (await git(["rev-parse", "--show-toplevel"])).replace(/\n$/, "");
+    }
+    catch {
+        return null;
+    }
+}
+/** A marker bounds filesystem discovery; it does not establish a valid Git checkout. */
+export async function searchBoundary(folder) {
+    try {
+        const selected = await realpath(resolve(folder));
+        if (!(await stat(selected)).isDirectory())
+            return null;
+        let base = selected;
+        for (let inspected = 0; inspected < 64; inspected++) {
+            try {
+                // Inspect the marker itself, never its administrative pointer or a symlink target.
+                const marker = await lstat(join(base, ".git"));
+                if (!marker.isDirectory() && !marker.isFile())
+                    return null;
+                return { base, selectedRoot: relative(base, selected).split(sep).join("/") };
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    return null;
+            }
+            const parent = dirname(base);
+            if (parent === base)
+                break;
+            base = parent;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a .git marker is one Git could use: a directory with a HEAD entry, or a "gitdir: " file. */
+async function usableMarker(marker) {
+    try {
+        if ((await lstat(marker)).isDirectory()) {
+            try {
+                await lstat(join(marker, "HEAD"));
+                return true;
+            }
+            catch (error) {
+                return error.code !== "ENOENT";
+            }
+        }
+        const file = await open(marker, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const head = Buffer.alloc(8);
+            await file.read(head, 0, 8, 0);
+            return head.toString("utf8") === "gitdir: ";
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        // Only a confirmed absence rules a marker out; anything unreadable is still treated as a checkout.
+        return error.code !== "ENOENT";
+    }
+}
+/**
+ * Whether a checkout Git could use bounds this folder. Like Git, it skips stray markers (an empty
+ * .git directory, for example a leftover /tmp/.git) and keeps looking upward.
+ */
+export async function usableCheckoutBoundary(folder) {
+    let base;
+    try {
+        base = await realpath(resolve(folder));
+    }
+    catch {
+        return false;
+    }
+    for (let inspected = 0; inspected < 64; inspected++) {
+        try {
+            await lstat(join(base, ".git"));
+            if (await usableMarker(join(base, ".git")))
+                return true;
+        }
+        catch (error) {
+            const { code } = error;
+            // Outside a Node permission grant nothing can be inspected, as in searchBoundary; other errors are unknown checkouts.
+            if (code === "ERR_ACCESS_DENIED")
+                return false;
+            if (code !== "ENOENT")
+                return true;
+        }
+        const parent = dirname(base);
+        if (parent === base)
+            return false;
+        base = parent;
+    }
+    return true;
+}
+/** A Git failure means "standalone folder" only when no usable checkout bounds it. */
+export async function standaloneGitFailure(folder, error) {
+    return [128, "ENOENT", "ERR_ACCESS_DENIED"].includes(error.code) && !await usableCheckoutBoundary(folder);
+}
+/** Relay coordinates are safe only when Git and the conservative boundary agree. */
+export async function searchBaseMatches(base, repoRoot) {
+    if (!repoRoot)
+        return false;
+    try {
+        const [canonicalBase, canonicalRoot] = await Promise.all([realpath(base), realpath(repoRoot)]);
+        if (canonicalBase !== canonicalRoot || !(await stat(canonicalBase)).isDirectory())
+            return false;
+        // Metadata can resolve even when this directory cannot be read or traversed.
+        await access(canonicalBase, constants.R_OK | constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/adapters/results.js

@@ -0,0 +1,9 @@
+import { formatSummary } from "../cli/summary.js";
+import { writeOutputFiles } from "./output-paths.js";
+export async function saveLocalResults(folder, report, refusedFiles, outputDir) {
+    const [findingsPath, summaryPath] = await writeOutputFiles(folder, {
+        "findings.json": `${JSON.stringify({ ...report, refusedFiles }, null, 2)}\n`,
+        "summary.md": formatSummary(report),
+    }, outputDir);
+    return { findingsPath, summaryPath };
+}