jev-agent-tools 0.2.0 → 0.3.0

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/files.js

@@ -4,14 +4,26 @@ import { lstat, open, readlink, realpath, } from "node:fs/promises";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { ASK_MAX_FILES, FIND_EXCERPT_CHARS, FIND_POINTER_EXCERPT_CHARS, FIND_READ_CHUNK_BYTES, STATE_MAX_CHARS, TIMEOUT_MS, } from "../constants.js";
 import { createExcerptCollector } from "../core/find.js";
+import { isSecretPath, secretRefusal } from "../core/secret-path.js";
 import { createUtf8Decoder, decodeUtf8 } from "./utf8.js";
 export async function checkFileAdmission(cwd, path, exec, signal, inventory) {
     if (path.split(/[\\/]/).includes(".git"))
-        return { ok: false, error: `${path}: .git metadata: not sent to Jev` };
+        return {
+            ok: false,
+            cause: "forbidden_path",
+            error: `${path}: .git metadata: not sent to Jev`,
+        };
+    // Before any inventory lookup or read: secret names are never admitted.
+    if (isSecretPath(path))
+        return { ok: false, cause: "secret_pattern", error: secretRefusal(path) };
     if (inventory)
         return inventory.has(path)
             ? { ok: true }
-            : { ok: false, error: `${path}: gitignored: not sent to Jev` };
+            : {
+                ok: false,
+                cause: "ignored_path",
+                error: `${path}: outside admitted inventory: not sent to Jev`,
+            };
     if (!exec)
         return { ok: true };
     const listed = await exec("git", [
@@ -24,15 +36,24 @@ export async function checkFileAdmission(cwd, path, exec, signal, inventory) {
         path,
     ], { cwd, timeout: TIMEOUT_MS, signal });
     if (listed.killed)
-        return { ok: false, error: `${path}: file admission interrupted` };
+        return {
+            ok: false,
+            cause: signal?.aborted ? "cancelled" : "git_failure",
+            error: `${path}: file admission interrupted`,
+        };
     if (listed.code === 0 && !listed.stdout.split("\0").includes(path))
-        return { ok: false, error: `${path}: gitignored: not sent to Jev` };
+        return {
+            ok: false,
+            cause: "ignored_path",
+            error: `${path}: gitignored: not sent to Jev`,
+        };
     return { ok: true };
 }
 export async function resolveInsideRepo(root, path, options = {}) {
     if (isAbsolute(path) || path.split(/[\\/]/).includes(".."))
         return {
             ok: false,
+            cause: "forbidden_path",
             error: `Path must remain inside the repository: ${path}.`,
         };
     try {
@@ -40,24 +61,40 @@ export async function resolveInsideRepo(root, path, options = {}) {
         const requested = resolve(base, path);
         const rel = relative(base, requested);
         if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
-            return { ok: false, error: `Path escapes the repository: ${path}.` };
+            return {
+                ok: false,
+                cause: "forbidden_path",
+                error: `Path escapes the repository: ${path}.`,
+            };
         let current = base;
         for (const part of rel.split(sep).filter(Boolean)) {
             current = resolve(current, part);
             if ((await lstat(current)).isSymbolicLink()) {
                 if (options.allowLeafSymlink && current === requested)
                     return { ok: true, abs: requested, rel: rel.replaceAll(sep, "/") };
-                return { ok: false, error: `Symbolic links are not read: ${path}.` };
+                return {
+                    ok: false,
+                    cause: "symlink",
+                    error: `Symbolic links are not read: ${path}.`,
+                };
             }
         }
         const abs = await realpath(requested);
         const actual = relative(base, abs);
         if (actual === ".." || actual.startsWith(`..${sep}`) || isAbsolute(actual))
-            return { ok: false, error: `Path escapes the repository: ${path}.` };
+            return {
+                ok: false,
+                cause: "forbidden_path",
+                error: `Path escapes the repository: ${path}.`,
+            };
         return { ok: true, abs, rel: actual.replaceAll(sep, "/") };
     }
     catch (error) {
-        return { ok: false, error: `Cannot resolve ${path}: ${String(error)}` };
+        return {
+            ok: false,
+            cause: "file_unavailable",
+            error: `Cannot resolve ${path}: ${String(error)}`,
+        };
     }
 }
 /** Leaf-link metadata is admitted without following the target. */
@@ -75,6 +112,7 @@ export async function admitGitPath(cwd, path, base, exec, signal, inventory) {
     if (isAbsolute(path) || path.split(/[\\/]/).includes(".."))
         return {
             ok: false,
+            cause: "forbidden_path",
             error: `Path must remain inside the repository: ${path}.`,
         };
     const admission = await checkFileAdmission(cwd, path, undefined, signal);
@@ -85,13 +123,21 @@ export async function admitGitPath(cwd, path, base, exec, signal, inventory) {
     if (!inventory) {
         const tree = await exec("git", ["ls-tree", "-z", "--full-tree", "--end-of-options", base, "--", path], { cwd, timeout: TIMEOUT_MS, signal });
         if (tree.code !== 0 || tree.killed)
-            return { ok: false, error: `${path}: not a file at comparison base` };
+            return {
+                ok: false,
+                cause: signal?.aborted ? "cancelled" : "git_failure",
+                error: `${path}: comparison base tree unavailable`,
+            };
         entry = tree.stdout
             .split("\0")
             .find((item) => item.slice(item.indexOf("\t") + 1) === path);
     }
     if (!entry || !/^(?:100644|100755|120000) blob /.test(entry))
-        return { ok: false, error: `${path}: not a file at comparison base` };
+        return {
+            ok: false,
+            cause: "file_unavailable",
+            error: `${path}: not a file at comparison base`,
+        };
     return { ok: true };
 }
 /** The only content opener for repository files. Callers own and close the handle. */
@@ -109,7 +155,11 @@ export async function openRepoFile(cwd, path, options = {}) {
             const stat = await handle.stat();
             if (!stat.isFile()) {
                 await handle.close();
-                return { ok: false, error: `Not a file: ${path}.` };
+                return {
+                    ok: false,
+                    cause: "file_unavailable",
+                    error: `Not a file: ${path}.`,
+                };
             }
             return { ok: true, handle, size: stat.size };
         }
@@ -119,19 +169,43 @@ export async function openRepoFile(cwd, path, options = {}) {
         }
     }
     catch (error) {
-        return { ok: false, error: `Cannot read ${path}: ${String(error)}` };
+        return {
+            ok: false,
+            cause: options.signal?.aborted
+                ? "cancelled"
+                : error.code === "ELOOP"
+                    ? "symlink"
+                    : "file_unavailable",
+            error: `Cannot read ${path}: ${String(error)}`,
+        };
     }
 }
 export async function collectFiles(cwd, paths, signal, options = {}) {
+    for (const path of paths) {
+        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 admission = await resolveInsideRepo(cwd, path);
+        if (!admission.ok)
+            return admission;
+    }
+    paths = [
+        ...new Set(paths.map((path) => relative(cwd, resolve(cwd, path)).split("\\").join("/"))),
+    ].sort();
     if (paths.length > ASK_MAX_FILES)
         return {
             ok: false,
+            cause: "evidence_too_large",
             error: `paths exceeds ${ASK_MAX_FILES} files; split paths into several calls.`,
         };
     const results = await Promise.all(paths.map(async (path) => {
         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}.`,
             };
         let handle;
@@ -157,23 +231,30 @@ export async function collectFiles(cwd, paths, signal, options = {}) {
             if (count === bytes.length)
                 return {
                     ok: false,
+                    cause: "evidence_too_large",
                     error: `File exceeds ${STATE_MAX_CHARS} chars: ${path}; files are never truncated. Split paths into several calls.`,
                 };
             const decoded = decodeUtf8(bytes.subarray(0, count));
-            if (!decoded.ok)
+            if (!decoded.ok || (decoded.ok && decoded.text.includes("\0")))
                 return {
                     ok: false,
                     invalidUtf8: true,
+                    cause: "binary_or_non_utf8",
                     error: `${path} is not UTF-8 text; provide a UTF-8 text file instead.`,
                 };
             const text = decoded.text;
             if (count === bytes.length || text.length > STATE_MAX_CHARS)
                 return {
                     ok: false,
+                    cause: "evidence_too_large",
                     error: `File exceeds ${STATE_MAX_CHARS} chars: ${path}; files are never truncated. Split paths into several calls.`,
                 };
             if (!text.length && !options.allowEmpty)
-                return { ok: false, error: `${path} is empty.` };
+                return {
+                    ok: false,
+                    cause: "empty_required",
+                    error: `${path} is empty.`,
+                };
             return {
                 ok: true,
                 path,
@@ -193,6 +274,9 @@ export async function collectFiles(cwd, paths, signal, options = {}) {
         catch (error) {
             return {
                 ok: false,
+                cause: signal?.aborted
+                    ? "cancelled"
+                    : "file_unavailable",
                 error: `Cannot read ${path}: ${String(error)}`,
             };
         }
@@ -214,16 +298,23 @@ export async function collectSearchExcerpts(cwd, paths, keywords, signal, exec)
     const files = {}, pointers = {};
     const ignored = [];
     const limits = [];
+    const omissions = [];
     const results = await Promise.all(paths.map(async (path) => {
         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}.`,
             };
         try {
             const location = await admitRepoMetadata(cwd, path, exec, signal);
             if (!location.ok) {
                 ignored.push(path);
+                omissions.push({
+                    path,
+                    cause: location.cause ?? "file_unavailable",
+                    reason: location.error,
+                });
                 return { ok: true };
             }
             if ((await lstat(location.abs)).isSymbolicLink()) {
@@ -235,6 +326,11 @@ export async function collectSearchExcerpts(cwd, paths, keywords, signal, exec)
             const opened = await openRepoFile(cwd, path, { exec, signal });
             if (!opened.ok) {
                 ignored.push(path);
+                omissions.push({
+                    path,
+                    cause: opened.cause ?? "file_unavailable",
+                    reason: opened.error,
+                });
                 return { ok: true };
             }
             const handle = opened.handle;
@@ -249,6 +345,11 @@ export async function collectSearchExcerpts(cwd, paths, keywords, signal, exec)
                 const decoded = decode(chunk);
                 if (!decoded.ok) {
                     limits.push({ path, reason: decoded.error });
+                    omissions.push({
+                        path,
+                        cause: "binary_or_non_utf8",
+                        reason: decoded.error,
+                    });
                     ignored.push(path);
                     stream.destroy();
                     return { ok: true };
@@ -256,6 +357,11 @@ export async function collectSearchExcerpts(cwd, paths, keywords, signal, exec)
                 const text = decoded.text;
                 if (text.includes("\0")) {
                     ignored.push(path);
+                    omissions.push({
+                        path,
+                        cause: "binary_or_non_utf8",
+                        reason: "Binary NUL content is not sent to Jev",
+                    });
                     stream.destroy();
                     return { ok: true };
                 }
@@ -265,6 +371,11 @@ export async function collectSearchExcerpts(cwd, paths, keywords, signal, exec)
             const end = decode();
             if (!end.ok) {
                 limits.push({ path, reason: end.error });
+                omissions.push({
+                    path,
+                    cause: "binary_or_non_utf8",
+                    reason: end.error,
+                });
                 ignored.push(path);
                 return { ok: true };
             }
@@ -273,6 +384,11 @@ export async function collectSearchExcerpts(cwd, paths, keywords, signal, exec)
             const excerpt = content.finish();
             if (!excerpt.length) {
                 ignored.push(path);
+                omissions.push({
+                    path,
+                    cause: "collection_empty",
+                    reason: "No non-empty search excerpt was collected",
+                });
                 return { ok: true };
             }
             files[path] = excerpt;
@@ -281,13 +397,22 @@ export async function collectSearchExcerpts(cwd, paths, keywords, signal, exec)
         }
         catch (error) {
             if (signal?.aborted)
-                return { ok: false, error: String(error) };
+                return {
+                    ok: false,
+                    cause: "cancelled",
+                    error: String(error),
+                };
             ignored.push(path);
+            omissions.push({
+                path,
+                cause: "file_unavailable",
+                reason: String(error),
+            });
             return { ok: true };
         }
     }));
     const failure = results.find((result) => !result.ok);
     return failure && !failure.ok
         ? failure
-        : { ok: true, files, pointers, ignored, limits };
+        : { ok: true, files, pointers, ignored, limits, omissions };
 }

package/dist/adapters/find.js

@@ -1,23 +1,46 @@
+import { isAbsolute } from "node:path";
 import { FIND_GREP_PAGE_SIZE, FIND_PATH_WEIGHT, TIMEOUT_MS, } from "../constants.js";
 import { pathAllowed } from "../core/find.js";
+import { isSecretPath, SECRET_NAME_GLOBS } from "../core/secret-path.js";
 export async function prefilter(exec, cwd, keywords, limit, scope, exclude, signal, native = true) {
+    const restrictions = [
+        ...(typeof scope === "string" ? [scope] : (scope ?? [])),
+        ...(exclude ?? []),
+    ];
+    for (const restriction of restrictions) {
+        if (isAbsolute(restriction) ||
+            restriction
+                .split(/[\\/]/)
+                .some((segment) => segment === ".." || segment === ".git"))
+            return {
+                ok: false,
+                cause: "forbidden_path",
+                error: `Discovery restriction must remain inside admitted files: ${restriction}`,
+            };
+    }
     try {
         const listed = await exec("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { cwd, timeout: TIMEOUT_MS, signal });
         if (listed.killed || listed.code !== 0)
             return {
                 ok: false,
+                cause: signal?.aborted ? "cancelled" : "git_failure",
                 error: `Cannot list repository files: ${listed.stderr || "git interrupted"}`,
             };
-        const paths = [
+        const inScope = [
             ...new Set(listed.stdout
                 .split("\0")
                 .filter((path) => path && pathAllowed(path, scope, exclude))),
         ];
+        // Secret-named files are neither ranked, read nor named to Jev.
+        const secret = inScope.filter(isSecretPath);
+        const paths = inScope.filter((path) => !isSecretPath(path));
         if (!paths.length)
-            return { ok: true, paths: [], scopeFiles: 0 };
+            return { ok: true, paths: [], scopeFiles: 0, secret };
         const allowed = new Set(paths);
         let finder;
-        if (native) {
+        // The native index cannot skip files, so it never scans a scope that
+        // holds secret-named files; rg excludes them by name instead.
+        if (native && !secret.length) {
             try {
                 // Static loading would break hosts where this optional native package is absent.
                 const { FileFinder } = await import("@ff-labs/fff-node");
@@ -74,8 +97,8 @@ export async function prefilter(exec, cwd, keywords, limit, scope, exclude, sign
                     "--files-with-matches",
                     "--hidden",
                     "--null",
-                    "--fixed-strings",
-                    "--ignore-case",
+                    "--glob-case-insensitive",
+                    ...SECRET_NAME_GLOBS.flatMap((glob) => ["--glob", `!${glob}`]),
                     "--",
                     word,
                     ".",
@@ -110,6 +133,7 @@ export async function prefilter(exec, cwd, keywords, limit, scope, exclude, sign
                     .slice(0, limit)
                     .map((item) => item.path),
                 scopeFiles: paths.length,
+                secret,
             };
         }
         finally {
@@ -117,6 +141,10 @@ export async function prefilter(exec, cwd, keywords, limit, scope, exclude, sign
         }
     }
     catch (error) {
-        return { ok: false, error: `Cannot prefilter files: ${String(error)}` };
+        return {
+            ok: false,
+            cause: signal?.aborted ? "cancelled" : "git_failure",
+            error: `Cannot prefilter files: ${String(error)}`,
+        };
     }
 }

package/dist/adapters/git-base.js

@@ -9,17 +9,23 @@ export async function resolveBase(exec, cwd, base, signal) {
             signal,
         });
         if (result.killed)
-            return { ok: false, error: "Git interrupted (cancelled or timed out)." };
+            return {
+                ok: false,
+                cause: signal?.aborted ? "cancelled" : "git_failure",
+                error: "Git interrupted (cancelled or timed out).",
+            };
         if (result.code === 0 && result.stdout.trim())
             return { ok: true, base: result.stdout.trim() };
         return {
             ok: false,
+            cause: "invalid_base",
             error: `Cannot resolve base=${base}: history may be truncated or no shared ancestor is available. Run git fetch --unshallow (or git fetch --deepen=<count>), or choose a base that is an ancestor of HEAD.${result.stderr.trim() ? ` Git: ${result.stderr.trim()}` : ""}`,
         };
     }
     catch (error) {
         return {
             ok: false,
+            cause: signal?.aborted ? "cancelled" : "git_failure",
             error: `Unable to resolve base=${base}: ${String(error)}`,
         };
     }