jev-agent-tools 0.1.4 → 0.3.0

package/src/adapters/ask-files.ts

@@ -23,7 +23,7 @@ export async function collectAskFiles(
   paths: readonly string[],
   signal?: AbortSignal,
   exec?: GitExec,
-): Promise<Result<{ files: AskFile[]; skipped: string[] }>> {
+): Promise<Result<{ files: AskFile[]; skipped: string[]; secret: string[] }>> {
   if (!paths.length)
     return {
       ok: false,
@@ -42,6 +42,7 @@ export async function collectAskFiles(
       };
   }
   const skipped = new Set<string>();
+  const secret = new Set<string>();
   const candidates = new Set<string>();
   try {
     let inventory: Set<string> | undefined;
@@ -63,7 +64,9 @@ export async function collectAskFiles(
         inventory,
       );
       if (!admission.ok) {
-        skipped.add(`${path} (${admission.error})`);
+        const entry = `${path} (${admission.error})`;
+        skipped.add(entry);
+        if (admission.cause === "secret_pattern") secret.add(entry);
         return;
       }
       if (path.split("/").some((part) => excludedDirectories.has(part)))
@@ -229,7 +232,12 @@ export async function collectAskFiles(
         };
       }
     }
-    return { ok: true, files, skipped: [...skipped].sort() };
+    return {
+      ok: true,
+      files,
+      skipped: [...skipped].sort(),
+      secret: [...secret].sort(),
+    };
   } catch (error) {
     return { ok: false, error: `Cannot expand paths: ${String(error)}` };
   }

package/src/adapters/ask-proof.ts

@@ -1,14 +1,15 @@
-import { relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import { STATE_MAX_CHARS, TIMEOUT_MS } from "../constants.ts";
 import type { GitExec } from "../core/git.ts";
 import type { ImportSource } from "../core/imports.ts";
 import type { Result } from "../result.ts";
-import { collectFiles } from "./files.ts";
+import { checkFileAdmission, collectFiles } from "./files.ts";
 import { verifyGitUtf8 } from "./utf8.ts";
 
 export interface AskRepository {
   root: string;
   known: ReadonlySet<string>;
+  beforeKnown: ReadonlySet<string>;
   baseSha?: string;
   read(path: string): Promise<Result<ImportSource>>;
   readBefore(path: string): Promise<Result<{ text: string | null }>>;
@@ -69,18 +70,20 @@ export async function collectAskRepository(
     for (const path of ignored.stdout.split("\0")) known.delete(path);
     const baseSha = revision?.stdout.trim();
     const basePaths = baseSha
-      ? await exec(
-          "git",
-          ["ls-tree", "-r", "--name-only", "-z", baseSha],
-          gitOptions,
-        )
+      ? await exec("git", ["ls-tree", "-r", "-z", baseSha], gitOptions)
       : undefined;
     if (basePaths && (basePaths.code !== 0 || basePaths.killed))
       return {
         ok: false,
         error: basePaths.stderr || "Cannot list base paths.",
       };
-    const beforeKnown = new Set(basePaths?.stdout.split("\0").filter(Boolean));
+    const beforeEntries = new Map(
+      (basePaths?.stdout.split("\0").filter(Boolean) ?? []).map((entry) => [
+        entry.slice(entry.indexOf("\t") + 1),
+        entry,
+      ]),
+    );
+    const beforeKnown = new Set(beforeEntries.keys());
     const reads = new Map<string, Promise<Result<ImportSource>>>();
     const beforeReads = new Map<
       string,
@@ -90,6 +93,7 @@ export async function collectAskRepository(
       ok: true,
       root,
       known,
+      beforeKnown,
       baseSha,
       read(path) {
         let pending = reads.get(path);
@@ -117,9 +121,53 @@ export async function collectAskRepository(
         let pending = beforeReads.get(path);
         if (!pending) {
           pending = (async () => {
-            if (!baseSha || !beforeKnown.has(path))
-              return { ok: true as const, text: null };
             try {
+              if (isAbsolute(path) || path.split(/[\\/]/).includes(".."))
+                return {
+                  ok: false as const,
+                  cause: "forbidden_path" as const,
+                  error: `Path must remain inside the repository: ${path}.`,
+                };
+              const admission = await checkFileAdmission(root, path);
+              if (!admission.ok) return admission;
+              const ignoredPath = await exec(
+                "git",
+                ["check-ignore", "--no-index", "--", path],
+                gitOptions,
+              );
+              if (ignoredPath.killed || ![0, 1].includes(ignoredPath.code))
+                return {
+                  ok: false as const,
+                  cause: "git_failure" as const,
+                  error: `${path}: historical admission unavailable`,
+                };
+              if (ignoredPath.code === 0)
+                return {
+                  ok: false as const,
+                  cause: "ignored_path" as const,
+                  error: `${path}: gitignored: not sent to Jev`,
+                };
+              if (!baseSha)
+                return {
+                  ok: false as const,
+                  error: `${path}: comparison base unavailable`,
+                };
+              if (!beforeKnown.has(path))
+                return known.has(path)
+                  ? { ok: true as const, text: null }
+                  : {
+                      ok: false as const,
+                      error: `${path}: not in current or comparison base inventory`,
+                    };
+              const entry = beforeEntries.get(path) ?? "";
+              if (!/^(?:100644|100755) blob /.test(entry))
+                return {
+                  ok: false as const,
+                  cause: entry.startsWith("120000 ")
+                    ? ("symlink" as const)
+                    : ("file_unavailable" as const),
+                  error: `${path}: not a regular file at comparison base: not sent to Jev`,
+                };
               const object = await exec(
                 "git",
                 [
@@ -172,10 +220,20 @@ export async function collectAskRepository(
                   ok: false as const,
                   error: `before evidence unavailable for ${path}`,
                 };
+              if (loaded.stdout.includes("\0"))
+                return {
+                  ok: false as const,
+                  cause: "binary_or_non_utf8" as const,
+                  error: `${path}: binary content: not sent to Jev`,
+                };
               const decoded = verifyGitUtf8(loaded.stdout, id, size);
               return decoded.ok
                 ? decoded
-                : { ok: false as const, error: `${path}: ${decoded.error}` };
+                : {
+                    ok: false as const,
+                    cause: "binary_or_non_utf8" as const,
+                    error: `${path}: ${decoded.error}`,
+                  };
             } catch (error) {
               return { ok: false as const, error: String(error) };
             }

package/src/adapters/canonical-path.ts

@@ -0,0 +1,18 @@
+import { realpath } from "node:fs";
+import { promisify } from "node:util";
+
+const nativeRealpath = promisify(realpath.native);
+
+/**
+ * Canonical form of an existing path: resolves symlinks and, on Windows,
+ * expands 8.3 short names (C:\Users\NAME~1) so the path relates correctly to
+ * `git rev-parse --show-toplevel`, which always reports the long form. Falls
+ * back to the input when the path cannot be resolved.
+ */
+export async function canonicalPath(path: string): Promise<string> {
+  try {
+    return await nativeRealpath(path);
+  } catch {
+    return path;
+  }
+}

package/src/adapters/command.ts

@@ -21,6 +21,7 @@ import {
 import type { GitExec } from "../core/git.ts";
 import type { Result } from "../result.ts";
 import { outputLines } from "./output-lines.ts";
+import { resolveShell } from "./shell.ts";
 
 export interface CommandOutput {
   command: string;
@@ -31,12 +32,47 @@ export interface CommandOutput {
   compressed: boolean;
   truncated: boolean;
 }
+const TRUNCATION_MARK = `…[line truncated at ${OUTPUT_LINE_MAX_CHARS} chars]`;
+/** Shortest key prefix worth redacting when a line cut leaves only its start. */
+const SECRET_PREFIX_MIN = 4;
+/**
+ * Replace every occurrence of `secret` in `text`, counting replacements. A
+ * line cut at OUTPUT_LINE_MAX_CHARS can end inside the key; that trailing key
+ * prefix is redacted too.
+ */
+export function redactSecret(
+  text: string,
+  secret: string | undefined,
+): { text: string; count: number } {
+  if (!secret) return { text, count: 0 };
+  const parts = text.split(secret);
+  let result = parts.join("[redacted]");
+  let count = parts.length - 1;
+  if (result.endsWith(TRUNCATION_MARK)) {
+    const kept = result.slice(0, -TRUNCATION_MARK.length);
+    const min = Math.min(SECRET_PREFIX_MIN, secret.length);
+    for (
+      let length = Math.min(secret.length - 1, kept.length);
+      length >= min;
+      length--
+    ) {
+      if (kept.endsWith(secret.slice(0, length))) {
+        result = `${kept.slice(0, -length)}[redacted]${TRUNCATION_MARK}`;
+        count++;
+        break;
+      }
+    }
+  }
+  return { text: result, count };
+}
 export async function captureCommand(
   exec: GitExec,
   cwd: string,
   command: string,
   timeoutS = ASK_TIMEOUT_S,
   signal?: AbortSignal,
+  /** Configured Jev API key, replaced in the captured command and output. */
+  secret?: string,
 ): Promise<
   Result<{
     output: CommandOutput;
@@ -47,9 +83,19 @@ export async function captureCommand(
     selectedPassages: boolean;
     assertion: boolean;
     targets: FailureTarget[];
-  }>
+    /** Occurrences of `secret` replaced with `[redacted]`. */
+    redactions: number;
+  }> & {
+    commandExecution: "not_started" | "unknown" | "finished";
+    commandExitCode?: number | null;
+    commandTimedOut?: boolean;
+  }
 > {
   const directory = await mkdtemp(join(tmpdir(), "jev-output-"));
+  let commandExecution: "not_started" | "unknown" | "finished" = "not_started";
+  let completion:
+    | { commandExitCode: number | null; commandTimedOut: boolean }
+    | undefined;
   try {
     await chmod(directory, 0o700);
     const stdoutPath = join(directory, "stdout");
@@ -62,39 +108,40 @@ export async function captureCommand(
       killed: boolean;
     };
     try {
+      const shell = resolveShell();
+      // Fail closed: never spawn a bare name that PATH could resolve to WSL.
+      if (!shell.ok)
+        return {
+          ok: false,
+          cause: "file_unavailable",
+          commandExecution: "not_started",
+          error: shell.error,
+        };
+      commandExecution = "unknown";
       executed = await exec(
-        "env",
+        shell.executable,
         [
-          "CI=1",
-          "bash",
+          ...shell.prefix,
           "-c",
-          `exec >"$1" 2>"$2"; set --; (\n${command}\n)\nexit $?`,
+          `${shell.scriptPrefix}exec >"$1" 2>"$2"; set --; (\n${command}\n)\nexit $?`,
           "jev",
           stdoutPath,
           stderrPath,
         ],
         { cwd, timeout: timeoutS * 1000, signal },
       );
+      commandExecution = "finished";
+      completion = {
+        commandExitCode: executed.killed ? null : executed.code,
+        commandTimedOut: executed.killed,
+      };
     } 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: [],
+        ok: false,
+        cause: "file_unavailable",
+        commandExecution,
+        error: `Command executable unavailable: ${String(error)}`,
       };
     }
     signal?.throwIfAborted();
@@ -116,6 +163,9 @@ export async function captureCommand(
     if (sizes.some((size) => size > OUTPUT_FILE_MAX_BYTES))
       return {
         ok: false,
+        cause: "evidence_too_large",
+        commandExecution: "finished",
+        ...completion,
         error: `output exceeded ${OUTPUT_FILE_MAX_BYTES} bytes per stream; narrow command`,
       };
     const targets: FailureTarget[] = [];
@@ -125,19 +175,23 @@ export async function captureCommand(
     let lineOmittedChars = 0;
     let shapeLimitExceeded = false;
     const texts: string[] = [];
+    let redactions = 0;
+    const redacted = (text: string): string => {
+      const result = redactSecret(text, secret);
+      redactions += result.count;
+      return result.text;
+    };
     for (const [index, path] of [stdoutPath, stderrPath].entries()) {
       if (!sizes[index]) {
-        texts.push(index === 0 ? executed.stdout : executed.stderr);
+        texts.push(redacted(index === 0 ? executed.stdout : executed.stderr));
         continue;
       }
       const frequencies = new Map<string, number>();
       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 line = redactSecret(cleanOutput(raw), secret).text;
+        linesTruncated ||= raw.endsWith(TRUNCATION_MARK);
         const shape = lineShape(line);
         if (
           !frequencies.has(shape) &&
@@ -184,17 +238,17 @@ export async function captureCommand(
         lineOmittedChars += chars;
       })) {
         signal?.throwIfAborted();
-        linesTruncated ||= raw.endsWith(
-          `…[line truncated at ${OUTPUT_LINE_MAX_CHARS} chars]`,
-        );
-        compressor.line(cleanOutput(raw));
+        linesTruncated ||= raw.endsWith(TRUNCATION_MARK);
+        // Redact before compression, failure windows and state assembly.
+        const line = redacted(cleanOutput(raw));
+        compressor.line(line);
         if (!failureSeen) {
-          failureWindow.push(cleanOutput(raw));
+          failureWindow.push(line);
           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));
+          failureWindow.push(line);
           if (!secondSeen && afterFailure > 1 && isFailingTestsHeader(raw)) {
             secondSeen = true;
             afterSecond = 0;
@@ -203,10 +257,10 @@ export async function captureCommand(
           if (isFailingTestsHeader(raw)) {
             secondSeen = true;
             afterSecond = 0;
-            failureWindow.push(cleanOutput(raw));
+            failureWindow.push(line);
           }
         } else if (afterSecond++ < OUTPUT_FAILURE_WINDOW_LINES) {
-          failureWindow.push(cleanOutput(raw));
+          failureWindow.push(line);
         }
       }
       compressor.finish();
@@ -217,8 +271,10 @@ export async function captureCommand(
     }
     return {
       ok: true,
+      commandExecution: "finished",
+      ...completion,
       output: {
-        command,
+        command: redacted(command),
         exit_code: executed.killed ? null : executed.code,
         timed_out: executed.killed,
         stdout: texts[0] ?? "",
@@ -233,6 +289,16 @@ export async function captureCommand(
       selectedPassages: false,
       assertion: signature === "assertion",
       targets,
+      redactions,
+    };
+  } catch (error) {
+    signal?.throwIfAborted();
+    return {
+      ok: false,
+      cause: "file_unavailable",
+      commandExecution,
+      ...completion,
+      error: `Command capture unavailable: ${String(error)}`,
     };
   } finally {
     await rm(directory, { recursive: true, force: true });

package/src/adapters/docs.ts

@@ -5,6 +5,7 @@ import {
 } from "../core/docs.ts";
 import type { GitExec } from "../core/git.ts";
 import type { Result } from "../result.ts";
+import type { Cause } from "../result-types.ts";
 import {
   checkFileAdmission,
   openRepoFile,
@@ -20,7 +21,7 @@ export interface DocsInventory {
   cwd: string;
   files: DocsSource[];
   tracked: ReadonlySet<string>;
-  limits: { path: string; reason: string }[];
+  limits: { path: string; reason: string; cause?: Cause }[];
   read: (path: string) => Promise<DocsSource | undefined>;
 }
 /** Inventory paths eagerly, but load only Markdown/configuration and subsequently reached sources. */
@@ -37,6 +38,7 @@ export async function collectDocsInventory(
   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();
@@ -48,6 +50,7 @@ export async function collectDocsInventory(
   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));
@@ -70,7 +73,11 @@ export async function collectDocsInventory(
           inventory: tracked,
         });
         if (!opened.ok) {
-          limits.push({ path, reason: opened.error });
+          limits.push({
+            path,
+            reason: opened.error,
+            ...(opened.cause ? { cause: opened.cause } : {}),
+          });
           return undefined;
         }
         const handle = opened.handle;
@@ -168,18 +175,22 @@ export function docsDeclarationSearch(
             const path = candidates[index++];
             if (path === undefined) return;
             const location = await resolveInsideRepo(inventory.cwd, path);
-            const admitted =
-              location.ok &&
-              (
-                await checkFileAdmission(
+            const admission = location.ok
+              ? await checkFileAdmission(
                   inventory.cwd,
                   location.rel,
                   exec,
                   signal,
                   inventory.tracked,
                 )
-              ).ok;
-            if (admitted) paths.push(path);
+              : location;
+            if (admission.ok) paths.push(path);
+            else if (admission.cause === "secret_pattern")
+              inventory.limits.push({
+                path,
+                reason: admission.error,
+                cause: admission.cause,
+              });
           }
         }),
       );
@@ -188,12 +199,20 @@ export function docsDeclarationSearch(
     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)) {
+    let result:
+      | { stdout: string; stderr: string; code: number; killed: boolean }
+      | undefined;
+    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",