jev-agent-tools 0.2.0 → 0.3.0

package/src/adapters/git.ts

@@ -7,6 +7,7 @@ import {
 } from "../constants.ts";
 import { type DiffFile, parseDiff } from "../core/diff.ts";
 import type { GitExec } from "../core/git.ts";
+import { isSecretPath } from "../core/secret-path.ts";
 import {
   buildUnits,
   type EvidenceUnit,
@@ -22,7 +23,12 @@ import { decodeUtf8, verifyGitUtf8 } from "./utf8.ts";
 
 export type CollectionResult<T> =
   | Result<T>
-  | { ok: false; kind: "inconsistent_diff"; error: string };
+  | {
+      ok: false;
+      kind: "inconsistent_diff";
+      cause: "git_failure";
+      error: string;
+    };
 export interface DiffOptions {
   cwd: string;
   base: string;
@@ -62,13 +68,22 @@ async function git(
     if (result.killed)
       return {
         ok: false,
+        cause: options.signal?.aborted ? "cancelled" : "git_failure",
         error: "Git interrupted (cancelled or timed out).",
       };
     if (result.code !== 0)
-      return { ok: false, error: `Git failed: ${result.stderr}` };
+      return {
+        ok: false,
+        cause: "git_failure",
+        error: `Git failed: ${result.stderr}`,
+      };
     return { ok: true, text: result.stdout };
   } catch (error) {
-    return { ok: false, error: `Unable to execute git: ${String(error)}` };
+    return {
+      ok: false,
+      cause: options.signal?.aborted ? "cancelled" : "git_failure",
+      error: `Unable to execute git: ${String(error)}`,
+    };
   }
 }
 type ReadSource = {
@@ -233,13 +248,21 @@ export async function collectDiff(
   } catch {
     return {
       ok: false,
+      cause: "git_failure",
       error: "Inconsistent Git snapshots; collect again.",
       kind: "inconsistent_diff",
     };
   }
   const unsupported: string[] = [];
+  // Secret-named paths (either side of a rename) stay named exclusions;
+  // excluding them from every later pathspec keeps Git from emitting their
+  // patch text or pairing them into a rename.
+  const secret = candidates
+    .filter((file) => isSecretPath(file.path) || isSecretPath(file.oldPath))
+    .map((file) => file.path);
   await Promise.all(
     candidates.map(async (file) => {
+      if (secret.includes(file.path)) return;
       try {
         const stat = await lstat(resolve(cwd, file.path));
         if (
@@ -254,7 +277,11 @@ export async function collectDiff(
       }
     }),
   );
-  for (const path of unsupported) paths.push(`:(top,exclude,literal)${path}`);
+  for (const path of [...unsupported, ...secret])
+    paths.push(`:(top,exclude,literal)${path}`);
+  for (const file of candidates)
+    if (secret.includes(file.path) && file.oldPath !== file.path)
+      paths.push(`:(top,exclude,literal)${file.oldPath}`);
   const prefix = [
     "diff",
     "--no-color",
@@ -329,7 +356,11 @@ export async function collectDiff(
     !current.ok ||
     !base.ok
   )
-    return { ok: false, error: "Incomplete Git collection." };
+    return {
+      ok: false,
+      cause: "git_failure",
+      error: "Incomplete Git collection.",
+    };
   const currentInventory = new Set(current.text.split("\0").filter(Boolean));
   const baseInventory = new Map<string, string>();
   for (const entry of base.text.split("\0")) {
@@ -348,17 +379,23 @@ export async function collectDiff(
   } catch {
     return {
       ok: false,
+      cause: "git_failure",
       error: "Inconsistent Git snapshots; collect again.",
       kind: "inconsistent_diff",
     };
   }
-  files.push(...candidates.filter((file) => unsupported.includes(file.path)));
+  files.push(
+    ...candidates.filter(
+      (file) => unsupported.includes(file.path) || secret.includes(file.path),
+    ),
+  );
   const objects = new Map<string, { id: string; size: number }>();
   for (const file of files) {
     if (
       /^[A?]/.test(file.status) ||
       file.binary ||
-      unsupported.includes(file.path)
+      unsupported.includes(file.path) ||
+      secret.includes(file.path)
     )
       continue;
     const admission = await admitGitPath(
@@ -387,6 +424,18 @@ export async function collectDiff(
   const collectFile = async (
     file: DiffFile,
   ): Promise<CollectionResult<{ file: SourceFile }>> => {
+    if (secret.includes(file.path))
+      return {
+        ok: true,
+        file: {
+          ...file,
+          hunks: [],
+          binary: false,
+          before: null,
+          after: null,
+          limitation: "secret_pattern",
+        },
+      };
     const historical = !/^[A?]/.test(file.status);
     const admission = historical
       ? await admitGitPath(
@@ -453,7 +502,11 @@ export async function collectDiff(
     if (!/^[A?]/.test(file.status)) {
       const object = objects.get(file.oldPath);
       if (!object)
-        return { ok: false, error: "Incomplete Git base tree; collect again." };
+        return {
+          ok: false,
+          cause: "git_failure",
+          error: "Incomplete Git base tree; collect again.",
+        };
       if (object.size > STATE_MAX_CHARS) limitation = "too_large";
       else if (loaded.invalid.has(object.id)) limitation = "not UTF-8 text";
       else before = loaded.blobs.get(object.id) ?? "";

package/src/adapters/locate-file.ts

@@ -34,6 +34,7 @@ export async function readLocateFile(
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path))
     return {
       ok: false,
+      cause: "forbidden_path",
       error: `Internal URLs are not files; use read for ${path}.`,
     };
   const opened = await openRepoFile(cwd, path, { exec, signal });
@@ -41,7 +42,12 @@ export async function readLocateFile(
   const handle = opened.handle;
   try {
     const stat = await handle.stat();
-    if (!stat.isFile()) return { ok: false, error: `Not a file: ${path}.` };
+    if (!stat.isFile())
+      return {
+        ok: false,
+        cause: "file_unavailable",
+        error: `Not a file: ${path}.`,
+      };
     const buffer = Buffer.alloc(
       Math.min(stat.size + 1, LOCATE_WHOLE_MAX_BYTES + 1),
     );
@@ -58,10 +64,19 @@ export async function readLocateFile(
       count += read.bytesRead;
     }
     if (buffer.subarray(0, count).includes(0))
-      return { ok: false, error: `Not a text file: ${path}.` };
+      return {
+        ok: false,
+        cause: "binary_or_non_utf8",
+        error: `Not a text file: ${path}.`,
+      };
     if (count < buffer.length) {
       const decoded = decodeUtf8(buffer.subarray(0, count));
-      if (!decoded.ok) return { ok: false, error: `${path}: ${decoded.error}` };
+      if (!decoded.ok)
+        return {
+          ok: false,
+          cause: "binary_or_non_utf8",
+          error: `${path}: ${decoded.error}`,
+        };
       const text = decoded.text;
       if (text.length <= LOCATE_WHOLE_MAX_CHARS)
         return {
@@ -85,7 +100,11 @@ export async function readLocateFile(
         }
       : scan;
   } catch (error) {
-    return { ok: false, error: `Cannot read ${path}: ${String(error)}` };
+    return {
+      ok: false,
+      cause: signal?.aborted ? "cancelled" : "file_unavailable",
+      error: `Cannot read ${path}: ${String(error)}`,
+    };
   } finally {
     await handle.close();
   }
@@ -171,26 +190,49 @@ export async function scanRange(
         break;
       }
       if (buffer.subarray(0, read.bytesRead).includes(0))
-        return { ok: false, error: `Not a text file: ${path}.` };
+        return {
+          ok: false,
+          cause: "binary_or_non_utf8",
+          error: `Not a text file: ${path}.`,
+        };
       bytes += read.bytesRead;
       const decoded = decode(buffer.subarray(0, read.bytesRead));
-      if (!decoded.ok) return { ok: false, error: `${path}: ${decoded.error}` };
+      if (!decoded.ok)
+        return {
+          ok: false,
+          cause: "binary_or_non_utf8",
+          error: `${path}: ${decoded.error}`,
+        };
       if (!consume(decoded.text))
         return {
           ok: false,
+          cause: "evidence_too_large",
           error: `Selected range exceeds ${STATE_MAX_CHARS} chars; read a narrower range directly.`,
         };
       if (range && line > range.end) break;
     }
     const end = reachedEof ? decode() : { ok: true as const, text: "" };
-    if (!end.ok) return { ok: false, error: `${path}: ${end.error}` };
+    if (!end.ok)
+      return {
+        ok: false,
+        cause: "binary_or_non_utf8",
+        error: `${path}: ${end.error}`,
+      };
     if (!consume(end.text))
-      return { ok: false, error: "Selected range too large." };
+      return {
+        ok: false,
+        cause: "evidence_too_large",
+        error: "Selected range too large.",
+      };
     const lines = line - Number(!pending);
     if (lines > 0 && (windows.at(-1)?.end ?? 0) < lines) finishWindow(lines);
     return { ok: true, bytes, lines, windows, text };
   } catch (error) {
-    return { ok: false, error: `Cannot read ${path}: ${String(error)}` };
+    return {
+      ok: false,
+      cause: signal?.aborted ? "cancelled" : "file_unavailable",
+      error: `Cannot read ${path}: ${String(error)}`,
+    };
   } finally {
     await handle.close();
   }

package/src/adapters/private-storage.ts

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import type { Stats } from "node:fs";
 import { join } from "node:path";
 import { PRIVATE_STORAGE_TIMEOUT_MS } from "../constants.ts";
+import { withoutApiKey } from "./shell.ts";
 
 /**
  * Owner-only storage, checked with each operating system's own model.
@@ -77,6 +78,21 @@ foreach ($id in @($me.Value, '${SYSTEM}', '${ADMINISTRATORS}')) {
 }
 Set-Acl -LiteralPath $path -AclObject $acl`;
 
+/**
+ * Host environment for the ACL helper, without the Jev API key. PowerShell 7
+ * parents export PSModulePath, which stops Windows PowerShell 5.1 from loading
+ * its own Get-Acl module; 5.1 rebuilds it when unset.
+ */
+export function powershellEnv(
+  host: NodeJS.ProcessEnv,
+  env: Record<string, string>,
+): NodeJS.ProcessEnv {
+  const childEnv = withoutApiKey({ ...host, ...env });
+  for (const key of Object.keys(childEnv))
+    if (key.toLowerCase() === "psmodulepath") delete childEnv[key];
+  return childEnv;
+}
+
 function powershell(
   script: string,
   env: Record<string, string>,
@@ -90,11 +106,7 @@ function powershell(
     "v1.0",
     "powershell.exe",
   );
-  // PowerShell 7 parents export PSModulePath, which stops Windows PowerShell
-  // 5.1 from loading its own Get-Acl module; 5.1 rebuilds it when unset.
-  const childEnv: NodeJS.ProcessEnv = { ...process.env, ...env };
-  for (const key of Object.keys(childEnv))
-    if (key.toLowerCase() === "psmodulepath") delete childEnv[key];
+  const childEnv = powershellEnv(process.env, env);
   const { promise, resolve, reject } = Promise.withResolvers<string>();
   execFile(
     executable,

package/src/adapters/risk-callers.ts

@@ -9,6 +9,7 @@ import {
   type CallerSource,
   prepareRiskCallers,
 } from "../core/risk-callers.ts";
+import { SECRET_NAME_GLOBS } from "../core/secret-path.ts";
 import type { SyntaxRootParser } from "../core/syntax.ts";
 import type { EvidenceUnit, SourceFile } from "../core/units.ts";
 import {
@@ -201,6 +202,8 @@ export async function collectRiskCallers(
         ref,
         "--",
         ...extensions.map((extension) => `*.${extension}`),
+        // Base-tree secret-named files are never searched or read.
+        ...SECRET_NAME_GLOBS.map((glob) => `:(exclude,icase,glob)**/${glob}`),
       ],
       { cwd, timeout: TIMEOUT_MS, signal: options.signal },
     ).catch((error: unknown) => ({

package/src/adapters/shell.ts

@@ -65,14 +65,25 @@ export function windowsBashCandidates(env: NodeJS.ProcessEnv): string[] {
 
 const UNAVAILABLE =
   "No permitted bash found: install Git for Windows or set JEV_TOOLS_BASH to the full path of a bash that is not the WSL launcher.";
+/** Never handed to command children: the Jev API key stays with the extension. */
+export const API_KEY_VARIABLE = "JEV_TOOLS_API_KEY";
+
+/** Copy of `env` without the Jev API key (any case, for Windows). */
+export function withoutApiKey(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const copy = { ...env };
+  for (const key of Object.keys(copy))
+    if (key.toUpperCase() === API_KEY_VARIABLE) delete copy[key];
+  return copy;
+}
 let cached: ShellResolution | undefined;
 
 /**
- * POSIX hosts keep `env CI=1 bash -c`. Windows has no `env` and its default
- * `bash` is the WSL launcher, so resolve Git for Windows bash (or
- * JEV_TOOLS_BASH) to an absolute, permitted path and export CI inside the
- * script. When none is found this fails closed: no bare name is returned,
- * because spawning one would search PATH again without the WSL exclusion.
+ * POSIX hosts run `env -u JEV_TOOLS_API_KEY CI=1 bash -c`. Windows has no
+ * `env` and its default `bash` is the WSL launcher, so resolve Git for Windows
+ * bash (or JEV_TOOLS_BASH) to an absolute, permitted path, and unset the key
+ * and export CI inside the script. When none is found this fails closed: no
+ * bare name is returned, because spawning one would search PATH again without
+ * the WSL exclusion.
  */
 export function resolveShell(
   platform: NodeJS.Platform = process.platform,
@@ -83,14 +94,19 @@ export function resolveShell(
     return {
       ok: true,
       executable: "env",
-      prefix: ["CI=1", "bash"],
+      prefix: ["-u", API_KEY_VARIABLE, "CI=1", "bash"],
       scriptPrefix: "",
     };
   const useCache = isExecutable === executable && env === process.env;
   if (useCache && cached) return cached;
   const found = windowsBashCandidates(env).find((path) => isExecutable(path));
   const resolved: ShellResolution = found
-    ? { ok: true, executable: found, prefix: [], scriptPrefix: "export CI=1; " }
+    ? {
+        ok: true,
+        executable: found,
+        prefix: [],
+        scriptPrefix: `unset ${API_KEY_VARIABLE}; export CI=1; `,
+      }
     : { ok: false, error: UNAVAILABLE };
   if (useCache && found) cached = resolved;
   return resolved;

package/src/adapters/test-inventory.ts

@@ -2,6 +2,7 @@ import { type FileHandle, lstat } from "node:fs/promises";
 import { TEST_SOURCE_MAX_BYTES, TIMEOUT_MS } from "../constants.ts";
 import type { GitExec } from "../core/git.ts";
 import type { ImportSource } from "../core/imports.ts";
+import { isSecretPath } from "../core/secret-path.ts";
 import type { Result } from "../result.ts";
 import {
   checkFileAdmission,
@@ -21,7 +22,7 @@ export async function collectTestInventory(
     read(path: string): Promise<ImportSource | undefined>;
     limits: readonly {
       path: string;
-      kind: "unreadable" | "too_large" | "not UTF-8 text";
+      kind: "unreadable" | "too_large" | "not UTF-8 text" | "secret_pattern";
     }[];
   }>
 > {
@@ -33,6 +34,7 @@ export async function collectTestInventory(
   if (root.code !== 0 || root.killed)
     return {
       ok: false,
+      cause: signal?.aborted ? "cancelled" : "git_failure",
       error: root.stderr || "Cannot identify repository root.",
     };
   cwd = root.stdout.replace(/\n$/, "");
@@ -51,6 +53,7 @@ export async function collectTestInventory(
   if (listed.code !== 0 || listed.killed)
     return {
       ok: false,
+      cause: signal?.aborted ? "cancelled" : "git_failure",
       error: listed.stderr || "Cannot inventory repository files.",
     };
   const ignored = await exec(
@@ -61,10 +64,11 @@ export async function collectTestInventory(
   if (ignored.code !== 0 || ignored.killed)
     return {
       ok: false,
+      cause: signal?.aborted ? "cancelled" : "git_failure",
       error: ignored.stderr || "Cannot identify ignored tracked files.",
     };
   const excluded = new Set(ignored.stdout.split("\0").filter(Boolean));
-  const paths = listed.stdout
+  const listedPaths = listed.stdout
     .split("\0")
     .filter(
       (path) =>
@@ -72,11 +76,15 @@ export async function collectTestInventory(
         (!excluded.has(path) ||
           /(?:^|\/)(?:package|tsconfig[^/]*)\.json$/.test(path)),
     );
+  // Secret-named files are named exclusions, never inventory members to read.
+  const paths = listedPaths.filter((path) => !isSecretPath(path));
   const admitted = new Set(paths);
   const limits: {
     path: string;
-    kind: "unreadable" | "too_large" | "not UTF-8 text";
-  }[] = [];
+    kind: "unreadable" | "too_large" | "not UTF-8 text" | "secret_pattern";
+  }[] = listedPaths
+    .filter(isSecretPath)
+    .map((path) => ({ path, kind: "secret_pattern" as const }));
   const cache = new Map<string, Promise<ImportSource | undefined>>();
   for (let offset = 0; offset < paths.length; offset += 16) {
     const inspected = await Promise.all(

package/src/configuration.ts

@@ -30,17 +30,31 @@ function nonempty(value: string | undefined): value is string {
 
 function validate(values: ConfigurationValues): void {
   let validUrl = false;
+  let insecureTransport = false;
   try {
     const url = new URL(values.url);
-    validUrl =
+    const host = url.hostname.toLowerCase();
+    const loopback =
+      host === "127.0.0.1" ||
+      host === "localhost" ||
+      host === "::1" ||
+      host === "[::1]";
+    const wellFormed =
       /^https?:\/\//i.test(values.url) &&
       (url.protocol === "http:" || url.protocol === "https:") &&
       url.hostname !== "" &&
       url.username === "" &&
       url.password === "";
+    insecureTransport = wellFormed && url.protocol === "http:" && !loopback;
+    validUrl = wellFormed && (url.protocol === "https:" || loopback);
   } catch {
     // Keep user-controlled URL and credentials out of error messages.
   }
+  if (insecureTransport) {
+    throw new Error(
+      "Jev configuration refuses plain http: to a non-loopback host; use https: or an http: loopback URL (127.0.0.1, ::1 or localhost).",
+    );
+  }
   if (
     !validUrl ||
     !nonempty(values.apiKey) ||
@@ -48,7 +62,7 @@ function validate(values: ConfigurationValues): void {
     !nonempty(values.model)
   ) {
     throw new Error(
-      "Jev configuration requires a full HTTP(S) URL without embedded credentials, a nonempty HTTP-header-compatible API key, and a nonempty model.",
+      "Jev configuration requires a full https: URL (or http: to 127.0.0.1, ::1 or localhost) without embedded credentials, a nonempty HTTP-header-compatible API key, and a nonempty model.",
     );
   }
 }

package/src/constants.ts

@@ -110,11 +110,32 @@ export const RUNNER_PACKAGE_MAX_BYTES = 64 * 1024;
 
 // ADR 0001: allowed local dependencies, including erased type imports.
 export const IMPORT_LAYERS = {
-  core: ["core", "constants.ts", "result.ts", "jev/types.ts"],
-  presets: ["presets", "core", "constants.ts", "result.ts", "jev/types.ts"],
-  adapters: ["adapters", "core", "constants.ts", "result.ts", "jev/types.ts"],
-  jev: ["jev", "core", "constants.ts", "result.ts"],
+  core: [
+    "core",
+    "constants.ts",
+    "result.ts",
+    "result-types.ts",
+    "jev/types.ts",
+  ],
+  presets: [
+    "presets",
+    "core",
+    "constants.ts",
+    "result.ts",
+    "result-types.ts",
+    "jev/types.ts",
+  ],
+  adapters: [
+    "adapters",
+    "core",
+    "constants.ts",
+    "result.ts",
+    "result-types.ts",
+    "jev/types.ts",
+  ],
+  jev: ["jev", "core", "constants.ts", "result.ts", "result-types.ts"],
   texts: ["texts", "constants.ts", "presets"],
   "constants.ts": [],
-  "result.ts": [],
+  "result.ts": ["result-types.ts"],
+  "result-types.ts": [],
 } as const;