jev-agent-tools 0.1.4 → 0.3.0

package/dist/adapters/docs.js

@@ -0,0 +1,192 @@
+import { STATE_MAX_CHARS, TIMEOUT_MS } from "../constants.js";
+import { attributeDocsDeclarations, docsDeclarationPattern, } from "../core/docs.js";
+import { checkFileAdmission, openRepoFile, resolveInsideRepo, } from "./files.js";
+import { decodeUtf8 } from "./utf8.js";
+/** Inventory paths eagerly, but load only Markdown/configuration and subsequently reached sources. */
+export async function collectDocsInventory(exec, cwd, signal) {
+    const root = await exec("git", ["rev-parse", "--show-toplevel"], {
+        cwd,
+        timeout: TIMEOUT_MS,
+        signal,
+    });
+    if (root.code || root.killed)
+        return {
+            ok: false,
+            cause: signal?.aborted ? "cancelled" : "git_failure",
+            error: root.stderr.trim() || "Repository root not found.",
+        };
+    cwd = root.stdout.trim();
+    const list = await exec("git", ["ls-files", "-z"], {
+        cwd,
+        timeout: TIMEOUT_MS,
+        signal,
+    });
+    if (list.code || list.killed)
+        return {
+            ok: false,
+            cause: signal?.aborted ? "cancelled" : "git_failure",
+            error: list.stderr.trim() || "Unable to inventory tracked files.",
+        };
+    const tracked = new Set(list.stdout.split("\0").filter(Boolean));
+    const limits = [];
+    const cache = new Map();
+    const read = (path) => {
+        const previous = cache.get(path);
+        if (previous)
+            return previous;
+        const pending = (async () => {
+            if (!tracked.has(path) || path.split("/").includes(".git"))
+                return undefined;
+            if (signal?.aborted) {
+                limits.push({ path, reason: "collection interrupted" });
+                return undefined;
+            }
+            try {
+                const opened = await openRepoFile(cwd, path, {
+                    exec,
+                    signal,
+                    inventory: tracked,
+                });
+                if (!opened.ok) {
+                    limits.push({
+                        path,
+                        reason: opened.error,
+                        ...(opened.cause ? { cause: opened.cause } : {}),
+                    });
+                    return undefined;
+                }
+                const handle = opened.handle;
+                try {
+                    const stat = await handle.stat();
+                    if (!stat.isFile() || stat.size > STATE_MAX_CHARS * 4) {
+                        limits.push({
+                            path,
+                            reason: "not a regular file or file too large",
+                        });
+                        return undefined;
+                    }
+                    const buffer = Buffer.alloc(stat.size + 1);
+                    let bytesRead = 0;
+                    while (bytesRead < buffer.length) {
+                        signal?.throwIfAborted();
+                        const chunk = await handle.read(buffer, bytesRead, buffer.length - bytesRead, null);
+                        if (!chunk.bytesRead)
+                            break;
+                        bytesRead += chunk.bytesRead;
+                    }
+                    if (bytesRead > stat.size) {
+                        limits.push({ path, reason: "file changed during reading" });
+                        return undefined;
+                    }
+                    const decoded = decodeUtf8(buffer.subarray(0, bytesRead));
+                    if (!decoded.ok) {
+                        limits.push({ path, reason: decoded.error });
+                        return undefined;
+                    }
+                    const text = decoded.text;
+                    if (text.includes("\0")) {
+                        limits.push({ path, reason: "binary file" });
+                        return undefined;
+                    }
+                    return { path, text };
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch (error) {
+                limits.push({ path, reason: `unable to read: ${String(error)}` });
+                return undefined;
+            }
+        })();
+        cache.set(path, pending);
+        return pending;
+    };
+    const paths = [...tracked].filter((path) => /\.(?:md|mdx|markdown)$/i.test(path) ||
+        /(?:^|\/)(?:package|tsconfig[^/]*)\.json$/.test(path));
+    const files = [];
+    let index = 0;
+    await Promise.all(Array.from({ length: Math.min(8, paths.length) }, async () => {
+        for (;;) {
+            const path = paths[index++];
+            if (path === undefined)
+                return;
+            const source = await read(path);
+            if (source)
+                files.push(source);
+        }
+    }));
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return { ok: true, cwd, files, tracked, limits, read };
+}
+/** Admitted paths only; one batch search transports declaration lines to the pure core. */
+export function docsDeclarationSearch(exec, inventory, signal) {
+    let admittedPaths;
+    return async (names) => {
+        if (!names.length)
+            return new Map();
+        admittedPaths ??= (async () => {
+            const candidates = [...inventory.tracked].filter((path) => /\.[cm]?[jt]sx?$|\.py$|\.go$/i.test(path) &&
+                !path.split("/").some((part) => part === ".." || part === ".git"));
+            const paths = [];
+            let index = 0;
+            await Promise.all(Array.from({ length: Math.min(16, candidates.length) }, async () => {
+                for (;;) {
+                    const path = candidates[index++];
+                    if (path === undefined)
+                        return;
+                    const location = await resolveInsideRepo(inventory.cwd, path);
+                    const admission = location.ok
+                        ? await checkFileAdmission(inventory.cwd, location.rel, exec, signal, inventory.tracked)
+                        : location;
+                    if (admission.ok)
+                        paths.push(path);
+                    else if (admission.cause === "secret_pattern")
+                        inventory.limits.push({
+                            path,
+                            reason: admission.error,
+                            cause: admission.cause,
+                        });
+                }
+            }));
+            return paths;
+        })();
+        const paths = await admittedPaths;
+        if (!paths.length)
+            return new Map();
+        const patterns = ["-e", docsDeclarationPattern(names)];
+        let result;
+        try {
+            result = await exec("rg", ["--json", ...patterns, "--", ...paths], {
+                cwd: inventory.cwd,
+                timeout: TIMEOUT_MS,
+                signal,
+            });
+        }
+        catch {
+            // A missing or unstartable rg is an unavailable search, not a failure.
+            signal?.throwIfAborted();
+        }
+        if (!result || result.killed || (result.code !== 0 && result.code !== 1)) {
+            inventory.limits.push({
+                path: "documentation",
+                reason: "declaration search unavailable",
+            });
+            return new Map(names.map((name) => [
+                name,
+                paths.length > 1 ? paths : [...paths, "<unknown declaration owner>"],
+            ]));
+        }
+        const admitted = new Set(paths);
+        const rows = [];
+        for (const line of result.stdout.split("\n")) {
+            if (!line)
+                continue;
+            const item = JSON.parse(line);
+            const path = item.data?.path?.text;
+            if (item.type === "match" && path && admitted.has(path))
+                rows.push({ path, text: item.data?.lines?.text ?? "" });
+        }
+        return attributeDocsDeclarations(names, rows);
+    };
+}

package/dist/adapters/evidence-context.js

@@ -0,0 +1,119 @@
+import { lstat, realpath } from "node:fs/promises";
+import { parse, resolve, sep } from "node:path";
+import { TIMEOUT_MS } from "../constants.js";
+/** Bind each judgment (including controls) to its admitted per-call provenance. */
+export function withEvidenceContext(state, context) {
+    const provenance = {
+        ...context,
+        authority: { ...context.authority },
+        ...(context.effectiveRoot
+            ? { effectiveRoot: { ...context.effectiveRoot } }
+            : {}),
+    };
+    const evidence = state.evidence;
+    // A producer's non-object evidence is content, not a metadata container.
+    if (evidence !== undefined &&
+        (evidence === null ||
+            typeof evidence !== "object" ||
+            Array.isArray(evidence)))
+        return { ...state, evidenceContext: provenance };
+    return { ...state, evidence: { ...evidence, context: provenance } };
+}
+/** Metadata-only admission. No evidence, commands, caches or judgments precede this. */
+export async function resolveEvidenceContext(initialCwd, root, deps) {
+    const canonical = deps.realpath ?? realpath;
+    const inspect = deps.lstat ?? lstat;
+    let initial;
+    try {
+        initial = await canonical(initialCwd);
+    }
+    catch {
+        return {
+            ok: false,
+            cause: "file_unavailable",
+            error: "Initial evidence authority cannot be canonicalized",
+            context: {
+                authority: { path: "", origin: deps.origin ?? "host" },
+                authorityReason: "Initial evidence authority cannot be canonicalized",
+                ...(root !== undefined ? { requestedRoot: root } : {}),
+            },
+        };
+    }
+    const origin = deps.origin ?? "host";
+    const context = {
+        authority: { path: initial, origin },
+        ...(root !== undefined ? { requestedRoot: root } : {}),
+    };
+    if (root === undefined) {
+        context.effectiveRoot = { path: initial, origin };
+        return { ok: true, cwd: initial, context };
+    }
+    const refuse = (reason, cause = "invalid_root") => ({
+        ok: false,
+        cause,
+        error: `Invalid root: ${reason}`,
+        context,
+    });
+    if (!root.trim())
+        return refuse("provide a non-empty directory");
+    if (root.split(/[\\/]/).includes(".."))
+        return refuse("parent traversal is forbidden");
+    const candidate = resolve(initial, root);
+    try {
+        let component = parse(candidate).root;
+        for (const part of candidate
+            .slice(component.length)
+            .split(sep)
+            .filter(Boolean)) {
+            component = resolve(component, part);
+            const metadata = await inspect(component);
+            if (metadata.isSymbolicLink())
+                return refuse("symbolic links are forbidden");
+            if (!metadata.isDirectory())
+                return refuse("root must be an existing directory");
+        }
+        const path = await canonical(candidate);
+        const git = async (cwd, args) => {
+            const result = await deps.exec("git", args, {
+                cwd,
+                timeout: TIMEOUT_MS,
+                signal: deps.signal,
+            });
+            if (result.code || result.killed)
+                throw new Error("Git metadata unavailable");
+            return args.includes("-z")
+                ? result.stdout
+                : result.stdout.replace(/\r?\n$/, "");
+        };
+        const initialTop = await canonical(await git(initial, ["rev-parse", "--show-toplevel"]));
+        const candidateTop = await canonical(await git(path, ["rev-parse", "--show-toplevel"]));
+        if (candidateTop !== path)
+            return refuse("root must equal a Git top-level directory");
+        const common = await canonical(resolve(initial, await git(initial, ["rev-parse", "--git-common-dir"])));
+        const candidateCommon = await canonical(resolve(path, await git(path, ["rev-parse", "--git-common-dir"])));
+        if (candidateCommon !== common)
+            return refuse("root belongs to a different repository");
+        const listed = await git(initial, [
+            "worktree",
+            "list",
+            "--porcelain",
+            "-z",
+        ]);
+        const registered = listed.split("\0\0").some((block) => {
+            const fields = block.split("\0");
+            const worktree = fields
+                .find((field) => field.startsWith("worktree "))
+                ?.slice(9);
+            return (worktree !== undefined &&
+                resolve(worktree) === path &&
+                !fields.some((field) => /^prunable(?: |$)/.test(field)));
+        });
+        if (path !== initialTop && !registered)
+            return refuse("root is not a registered live worktree");
+        context.effectiveRoot = { path, origin: "override", commonDir: common };
+        return { ok: true, cwd: path, context };
+    }
+    catch (error) {
+        return refuse(`cannot admit directory (${error instanceof Error ? error.message : String(error)})`, deps.signal?.aborted ? "cancelled" : "invalid_root");
+    }
+}

package/dist/adapters/exec.js

@@ -0,0 +1,207 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { PROCESS_KILL_GRACE_MS, PROCESS_PIPE_GRACE_MS, PROCESS_TREE_TIMEOUT_MS, } from "../constants.js";
+/** Signal the managed process group, or await Windows process-tree termination. */
+export async function killTree(child, signal = "SIGTERM", platform = process.platform) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    if (platform === "win32") {
+        const taskkill = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe");
+        const pids = [pid];
+        // MSYS fork/exec can leave Windows parent IDs pointing at vanished helper
+        // processes. Use the same Bash installation's POSIX table before killing
+        // the root; taskkill /T alone cannot find those ordinary descendants.
+        if (basename(child.spawnfile).toLowerCase() === "bash.exe") {
+            const directory = dirname(child.spawnfile);
+            const ps = [
+                join(directory, "ps.exe"),
+                join(directory, "..", "usr", "bin", "ps.exe"),
+            ].find(existsSync);
+            if (ps) {
+                const snapshot = Promise.withResolvers();
+                execFile(ps, ["-e"], { windowsHide: true, timeout: PROCESS_TREE_TIMEOUT_MS }, (error, stdout) => snapshot.resolve(error ? "" : stdout));
+                const rows = [];
+                for (const line of (await snapshot.promise).split("\n")) {
+                    const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s/.exec(line);
+                    if (!match)
+                        continue;
+                    rows.push({
+                        pid: Number(match[1]),
+                        parent: Number(match[2]),
+                        windows: Number(match[4]),
+                    });
+                }
+                const root = rows.find((row) => row.windows === pid);
+                if (root) {
+                    const managed = new Set([root.pid]);
+                    let added = true;
+                    while (added) {
+                        added = false;
+                        for (const row of rows) {
+                            if (!managed.has(row.pid) && managed.has(row.parent)) {
+                                managed.add(row.pid);
+                                if (row.windows > 0)
+                                    pids.push(row.windows);
+                                added = true;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        const { promise, resolve } = Promise.withResolvers();
+        execFile(taskkill, [...new Set(pids)]
+            .flatMap((target) => ["/PID", String(target)])
+            .concat("/T", "/F"), { windowsHide: true, timeout: PROCESS_TREE_TIMEOUT_MS }, (error) => {
+            if (error)
+                child.kill();
+            resolve();
+        });
+        await promise;
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        child.kill(signal);
+    }
+    return;
+}
+function groupExists(child) {
+    if (child.pid === undefined)
+        return false;
+    try {
+        process.kill(-child.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof Error &&
+            "code" in error &&
+            error.code === "ESRCH");
+    }
+}
+/**
+ * Capture a process without a shell. Timeout and abort finish tree termination
+ * before resolving, even when the direct child exits before its descendants.
+ * Deliberately detached descendants are not sandboxed or tracked.
+ */
+export const spawnExec = (command, args, options) => {
+    const { promise, resolve, reject } = Promise.withResolvers();
+    const posix = process.platform !== "win32";
+    // Git's bin/bash.exe forwards to usr/bin/bash.exe. Spawn the MSYS process
+    // directly so its Windows PID can be matched in the POSIX process table.
+    if (!posix && basename(command).toLowerCase() === "bash.exe") {
+        const direct = join(dirname(command), "..", "usr", "bin", "bash.exe");
+        if (existsSync(direct))
+            command = direct;
+    }
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        detached: posix,
+    });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    let spawned = false;
+    let settled = false;
+    let finishing = false;
+    let force;
+    let pipes;
+    let termination;
+    let terminated;
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    const kill = () => {
+        if (killed || settled)
+            return;
+        killed = true;
+        if (posix) {
+            void killTree(child, "SIGTERM");
+            const completion = Promise.withResolvers();
+            termination = completion.promise;
+            terminated = completion.resolve;
+            // Keep this timer referenced: a closing transport must not exit
+            // before a surviving member of the managed group receives SIGKILL.
+            force = setTimeout(() => {
+                void killTree(child, "SIGKILL");
+                completion.resolve();
+            }, PROCESS_KILL_GRACE_MS);
+        }
+        else
+            termination = killTree(child);
+    };
+    const timer = options.timeout > 0 ? setTimeout(kill, options.timeout) : undefined;
+    if (options.signal?.aborted)
+        kill();
+    else
+        options.signal?.addEventListener("abort", kill, { once: true });
+    const cleanup = () => {
+        clearTimeout(timer);
+        clearTimeout(force);
+        clearTimeout(pipes);
+        options.signal?.removeEventListener("abort", kill);
+    };
+    const finish = async (code, signal) => {
+        if (settled || finishing)
+            return;
+        finishing = true;
+        clearTimeout(pipes);
+        if (posix && terminated && !groupExists(child)) {
+            clearTimeout(force);
+            terminated();
+        }
+        if (termination)
+            await termination;
+        settled = true;
+        cleanup();
+        resolve({
+            stdout,
+            stderr,
+            code: code ?? (signal ? 128 + signalNumber(signal) : 1),
+            killed,
+        });
+    };
+    child.on("spawn", () => {
+        spawned = true;
+    });
+    child.on("error", (error) => {
+        if (spawned)
+            return;
+        settled = true;
+        cleanup();
+        reject(error);
+    });
+    child.on("exit", (code, signal) => {
+        // An escaped descendant may hold inherited pipes open indefinitely.
+        pipes = setTimeout(() => {
+            child.stdout.destroy();
+            child.stderr.destroy();
+            void finish(code, signal);
+        }, PROCESS_PIPE_GRACE_MS);
+    });
+    child.on("close", (code, signal) => {
+        void finish(code, signal);
+    });
+    return promise;
+};
+function signalNumber(signal) {
+    const numbers = {
+        SIGHUP: 1,
+        SIGINT: 2,
+        SIGKILL: 9,
+        SIGTERM: 15,
+    };
+    return numbers[signal] ?? 0;
+}