jev-agent-tools 0.2.0 → 0.3.0

package/dist/adapters/git.js

@@ -2,6 +2,7 @@ import { lstat, readlink } from "node:fs/promises";
 import { resolve } from "node:path";
 import { GIT_BLOB_BATCH_SIZE, STATE_MAX_CHARS, TIMEOUT_MS, } from "../constants.js";
 import { parseDiff } from "../core/diff.js";
+import { isSecretPath } from "../core/secret-path.js";
 import { buildUnits, } from "../core/units.js";
 import { admitGitPath, admitRepoMetadata, openRepoFile } from "./files.js";
 import { shareGitInventory } from "./git-inventory.js";
@@ -36,14 +37,23 @@ async function git(exec, options, args) {
         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)}`,
+        };
     }
 }
 async function readWorktree(options, exec, path, inventory) {
@@ -186,12 +196,21 @@ export async function collectDiff(exec, options) {
     catch {
         return {
             ok: false,
+            cause: "git_failure",
             error: "Inconsistent Git snapshots; collect again.",
             kind: "inconsistent_diff",
         };
     }
     const unsupported = [];
+    // 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 (!stat.isFile() &&
@@ -204,8 +223,11 @@ export async function collectDiff(exec, options) {
             /* Missing tracked paths remain deletions. */
         }
     }));
-    for (const path of unsupported)
+    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",
@@ -280,7 +302,11 @@ export async function collectDiff(exec, options) {
         !untracked.ok ||
         !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();
     for (const entry of base.text.split("\0")) {
@@ -301,16 +327,18 @@ export async function collectDiff(exec, options) {
     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();
     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(cwd, file.oldPath, options.base, exec, options.signal, baseInventory);
         if (!admission.ok)
@@ -328,6 +356,18 @@ export async function collectDiff(exec, options) {
     if (!loaded.ok)
         return loaded;
     const collectFile = async (file) => {
+        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(cwd, file.oldPath, options.base, exec, options.signal, baseInventory)
@@ -382,7 +422,11 @@ export async function collectDiff(exec, options) {
         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))

package/dist/adapters/locate-file.js

@@ -7,6 +7,7 @@ export async function readLocateFile(cwd, path, signal, exec) {
     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 });
@@ -16,7 +17,11 @@ export async function readLocateFile(cwd, path, signal, exec) {
     try {
         const stat = await handle.stat();
         if (!stat.isFile())
-            return { ok: false, error: `Not a file: ${path}.` };
+            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));
         let count = 0;
         while (count < buffer.length) {
@@ -27,11 +32,19 @@ export async function readLocateFile(cwd, path, signal, exec) {
             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}` };
+                return {
+                    ok: false,
+                    cause: "binary_or_non_utf8",
+                    error: `${path}: ${decoded.error}`,
+                };
             const text = decoded.text;
             if (text.length <= LOCATE_WHOLE_MAX_CHARS)
                 return {
@@ -56,7 +69,11 @@ export async function readLocateFile(cwd, path, signal, exec) {
             : 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();
@@ -127,14 +144,23 @@ export async function scanRange(cwd, path, range, signal, exec) {
                 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}` };
+                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)
@@ -142,16 +168,28 @@ export async function scanRange(cwd, path, range, signal, exec) {
         }
         const end = reachedEof ? decode() : { ok: true, text: "" };
         if (!end.ok)
-            return { ok: false, error: `${path}: ${end.error}` };
+            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/dist/adapters/private-storage.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { join } from "node:path";
 import { PRIVATE_STORAGE_TIMEOUT_MS } from "../constants.js";
+import { withoutApiKey } from "./shell.js";
 const SYSTEM = "S-1-5-18";
 const ADMINISTRATORS = "S-1-5-32-544";
 const CREATOR_OWNER = "S-1-3-0";
@@ -49,16 +50,23 @@ foreach ($id in @($me.Value, '${SYSTEM}', '${ADMINISTRATORS}')) {
   $acl.AddAccessRule($rule)
 }
 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, env) {
+    const childEnv = withoutApiKey({ ...host, ...env });
+    for (const key of Object.keys(childEnv))
+        if (key.toLowerCase() === "psmodulepath")
+            delete childEnv[key];
+    return childEnv;
+}
 function powershell(script, env) {
     const root = process.env.SystemRoot ?? "C:\\Windows";
     // A fixed system path, so a powershell.exe earlier on PATH is never used.
     const executable = join(root, "System32", "WindowsPowerShell", "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 = { ...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();
     execFile(executable, [
         "-NoProfile",

package/dist/adapters/risk-callers.js

@@ -2,6 +2,7 @@ import { lstat } from "node:fs/promises";
 import { posix } from "node:path";
 import { CONCURRENCY, STATE_MAX_CHARS, TIMEOUT_MS } from "../constants.js";
 import { prepareRiskCallers, } from "../core/risk-callers.js";
+import { SECRET_NAME_GLOBS } from "../core/secret-path.js";
 import { admitGitPath, checkFileAdmission, openRepoFile, resolveInsideRepo, } from "./files.js";
 import { loadSyntaxRootParser } from "./syntax.js";
 import { decodeUtf8, verifyGitUtf8 } from "./utf8.js";
@@ -151,6 +152,8 @@ export async function collectRiskCallers(exec, options, units, changedFiles = []
             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) => ({
             stdout: "",
             stderr: String(error),

package/dist/adapters/shell.js

@@ -47,20 +47,31 @@ export function windowsBashCandidates(env) {
     return [...new Set(candidates)].filter((candidate) => win32.isAbsolute(candidate) && !isWslLauncher(candidate));
 }
 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) {
+    const copy = { ...env };
+    for (const key of Object.keys(copy))
+        if (key.toUpperCase() === API_KEY_VARIABLE)
+            delete copy[key];
+    return copy;
+}
 let cached;
 /**
- * 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 = process.platform, env = process.env, isExecutable = executable) {
     if (platform !== "win32")
         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;
@@ -68,7 +79,12 @@ export function resolveShell(platform = process.platform, env = process.env, isE
         return cached;
     const found = windowsBashCandidates(env).find((path) => isExecutable(path));
     const resolved = 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;

package/dist/adapters/test-inventory.js

@@ -1,5 +1,6 @@
 import { lstat } from "node:fs/promises";
 import { TEST_SOURCE_MAX_BYTES, TIMEOUT_MS } from "../constants.js";
+import { isSecretPath } from "../core/secret-path.js";
 import { checkFileAdmission, openRepoFile, resolveInsideRepo, } from "./files.js";
 import { decodeUtf8 } from "./utf8.js";
 export async function collectTestInventory(exec, cwd, signal) {
@@ -11,6 +12,7 @@ export async function collectTestInventory(exec, cwd, signal) {
     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$/, "");
@@ -25,22 +27,28 @@ export async function collectTestInventory(exec, cwd, signal) {
     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("git", ["ls-files", "--cached", "--ignored", "--exclude-standard", "-z"], { cwd, timeout: TIMEOUT_MS, signal });
     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) => path &&
         (!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 = [];
+    const limits = listedPaths
+        .filter(isSecretPath)
+        .map((path) => ({ path, kind: "secret_pattern" }));
     const cache = new Map();
     for (let offset = 0; offset < paths.length; offset += 16) {
         const inspected = await Promise.all(paths.slice(offset, offset + 16).map(async (path) => {

package/dist/configuration.js

@@ -13,23 +13,33 @@ function nonempty(value) {
 }
 function validate(values) {
     let validUrl = false;
+    let insecureTransport = false;
     try {
         const url = new URL(values.url);
-        validUrl =
-            /^https?:\/\//i.test(values.url) &&
-                (url.protocol === "http:" || url.protocol === "https:") &&
-                url.hostname !== "" &&
-                url.username === "" &&
-                url.password === "";
+        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) ||
         /[^\x20-\x7e\x80-\xff]/.test(values.apiKey) ||
         !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.");
+        throw new Error("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.");
     }
 }
 /** Effective configuration and its client move together, only after a save succeeds. */

package/dist/constants.js

@@ -109,11 +109,32 @@ export const GIT_BLOB_BATCH_SIZE = 400;
 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": [],
 };