jev-agent-tools 0.1.3 → 0.2.0

package/dist/adapters/command.js

@@ -0,0 +1,181 @@
+import { chmod, mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ASK_TIMEOUT_S, OUTPUT_CHUNK_CHARS, OUTPUT_FAILURE_WINDOW_LINES, OUTPUT_FILE_MAX_BYTES, OUTPUT_FIND_MAX_CALLS, OUTPUT_LINE_MAX_CHARS, OUTPUT_REPEAT_MIN, OUTPUT_SHAPE_MAX_COUNT, } from "../constants.js";
+import { cleanOutput, createRarityCompressor, failureTargets, lineShape, } from "../core/command-output.js";
+import { outputLines } from "./output-lines.js";
+import { resolveShell } from "./shell.js";
+export async function captureCommand(exec, cwd, command, timeoutS = ASK_TIMEOUT_S, signal) {
+    const directory = await mkdtemp(join(tmpdir(), "jev-output-"));
+    try {
+        await chmod(directory, 0o700);
+        const stdoutPath = join(directory, "stdout");
+        const stderrPath = join(directory, "stderr");
+        signal?.throwIfAborted();
+        let executed;
+        try {
+            const shell = resolveShell();
+            // Fail closed: never spawn a bare name that PATH could resolve to WSL.
+            if (!shell.ok)
+                throw new Error(shell.error);
+            executed = await exec(shell.executable, [
+                ...shell.prefix,
+                "-c",
+                `${shell.scriptPrefix}exec >"$1" 2>"$2"; set --; (\n${command}\n)\nexit $?`,
+                "jev",
+                stdoutPath,
+                stderrPath,
+            ], { cwd, timeout: timeoutS * 1000, signal });
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            return {
+                ok: true,
+                output: {
+                    command,
+                    exit_code: null,
+                    timed_out: false,
+                    stdout: "",
+                    stderr: `Command executable unavailable: ${String(error)}`,
+                    compressed: true,
+                    truncated: false,
+                },
+                originalBytes: 0,
+                compressedChars: 0,
+                lineOmittedChars: 0,
+                shapeLimitExceeded: false,
+                selectedPassages: false,
+                assertion: false,
+                targets: [],
+            };
+        }
+        signal?.throwIfAborted();
+        const sizes = await Promise.all([stdoutPath, stderrPath].map(async (path) => {
+            try {
+                return (await stat(path)).size;
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT")
+                    return 0;
+                throw error;
+            }
+        }));
+        if (sizes.some((size) => size > OUTPUT_FILE_MAX_BYTES))
+            return {
+                ok: false,
+                error: `output exceeded ${OUTPUT_FILE_MAX_BYTES} bytes per stream; narrow command`,
+            };
+        const targets = [];
+        let signature;
+        let compressedChars = 0;
+        let linesTruncated = false;
+        let lineOmittedChars = 0;
+        let shapeLimitExceeded = false;
+        const texts = [];
+        for (const [index, path] of [stdoutPath, stderrPath].entries()) {
+            if (!sizes[index]) {
+                texts.push(index === 0 ? executed.stdout : executed.stderr);
+                continue;
+            }
+            const frequencies = new Map();
+            let shapeLimit = false;
+            for await (const raw of outputLines(path, signal)) {
+                signal?.throwIfAborted();
+                const line = cleanOutput(raw);
+                linesTruncated ||= raw.endsWith(`…[line truncated at ${OUTPUT_LINE_MAX_CHARS} chars]`);
+                const shape = lineShape(line);
+                if (!frequencies.has(shape) &&
+                    frequencies.size >= OUTPUT_SHAPE_MAX_COUNT) {
+                    shapeLimit = true;
+                    shapeLimitExceeded = true;
+                    frequencies.clear();
+                    break;
+                }
+                frequencies.set(shape, Math.min(OUTPUT_REPEAT_MIN, (frequencies.get(shape) ?? 0) + 1));
+            }
+            let text = "";
+            const compressor = createRarityCompressor(frequencies, (line) => {
+                compressedChars += line.length + 1;
+                const remaining = OUTPUT_CHUNK_CHARS * OUTPUT_FIND_MAX_CALLS + 1 - text.length;
+                if (remaining > 0)
+                    text += `${line}\n`.slice(0, remaining);
+            });
+            const failureWindow = [];
+            let failureSeen = false;
+            let afterFailure = 0;
+            // node:test prints its failing-test block ("✖ failing tests:" then
+            // "test at <file>:<line>:<col>") after one summary line per test, so
+            // the block can sit more than one window past the first anchor. Once
+            // the first window closes, keep scanning for that header and collect
+            // the next window after it. At most two windows (2 * (WINDOW + 1)
+            // lines) are ever buffered per stream.
+            let secondSeen = false;
+            let afterSecond = 0;
+            const isAnchor = (line) => failureTargets(line).signature !== undefined ||
+                /^\s*(?:✖|ERROR |FAIL |test at )/.test(line);
+            const isFailingTestsHeader = (line) => /^\s*(?:✖\s+)?failing tests:?\s*$/.test(line);
+            if (shapeLimit)
+                compressor.line(`…[shape limit exceeded at ${OUTPUT_SHAPE_MAX_COUNT}; rarity grouping disabled]`);
+            for await (const raw of outputLines(path, signal, (chars) => {
+                lineOmittedChars += chars;
+            })) {
+                signal?.throwIfAborted();
+                linesTruncated ||= raw.endsWith(`…[line truncated at ${OUTPUT_LINE_MAX_CHARS} chars]`);
+                compressor.line(cleanOutput(raw));
+                if (!failureSeen) {
+                    failureWindow.push(cleanOutput(raw));
+                    if (failureWindow.length > OUTPUT_FAILURE_WINDOW_LINES + 1)
+                        failureWindow.shift();
+                    if (isAnchor(raw))
+                        failureSeen = true;
+                }
+                else if (afterFailure++ < OUTPUT_FAILURE_WINDOW_LINES) {
+                    failureWindow.push(cleanOutput(raw));
+                    if (!secondSeen && afterFailure > 1 && isFailingTestsHeader(raw)) {
+                        secondSeen = true;
+                        afterSecond = 0;
+                    }
+                }
+                else if (!secondSeen) {
+                    if (isFailingTestsHeader(raw)) {
+                        secondSeen = true;
+                        afterSecond = 0;
+                        failureWindow.push(cleanOutput(raw));
+                    }
+                }
+                else if (afterSecond++ < OUTPUT_FAILURE_WINDOW_LINES) {
+                    failureWindow.push(cleanOutput(raw));
+                }
+            }
+            compressor.finish();
+            const failure = failureTargets(failureWindow.join("\n"));
+            signature ??= failure.signature;
+            targets.push(...failure.targets.slice(0, 20 - targets.length));
+            texts.push(text);
+        }
+        return {
+            ok: true,
+            output: {
+                command,
+                exit_code: executed.killed ? null : executed.code,
+                timed_out: executed.killed,
+                stdout: texts[0] ?? "",
+                stderr: texts[1] ?? "",
+                compressed: true,
+                truncated: linesTruncated,
+            },
+            originalBytes: sizes.reduce((sum, size) => sum + size, 0),
+            compressedChars,
+            lineOmittedChars,
+            shapeLimitExceeded,
+            selectedPassages: false,
+            assertion: signature === "assertion",
+            targets,
+        };
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}

package/dist/adapters/docs.js

@@ -0,0 +1,172 @@
+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,
+            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,
+            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 });
+                    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 admitted = location.ok &&
+                        (await checkFileAdmission(inventory.cwd, location.rel, exec, signal, inventory.tracked)).ok;
+                    if (admitted)
+                        paths.push(path);
+                }
+            }));
+            return paths;
+        })();
+        const paths = await admittedPaths;
+        if (!paths.length)
+            return new Map();
+        const patterns = ["-e", docsDeclarationPattern(names)];
+        const result = await exec("rg", ["--json", ...patterns, "--", ...paths], {
+            cwd: inventory.cwd,
+            timeout: TIMEOUT_MS,
+            signal,
+        });
+        if (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/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;
+}