jev-agent-tools 0.2.0 → 0.3.0

package/src/adapters/evidence-context.ts

@@ -0,0 +1,169 @@
+import { lstat, realpath } from "node:fs/promises";
+import { parse, resolve, sep } from "node:path";
+import { TIMEOUT_MS } from "../constants.ts";
+import type { GitExec } from "../core/git.ts";
+import type { State } from "../jev/types.ts";
+import type { Cause } from "../result-types.ts";
+
+export type EvidenceContext = {
+  authority: { path: string; origin: "host" | "server" };
+  authorityReason?: string;
+  requestedRoot?: string;
+  effectiveRoot?: {
+    path: string;
+    origin: "host" | "server" | "override";
+    commonDir?: string;
+  };
+  requestedBase?: string;
+  resolvedBase?: string;
+};
+export interface ContextDependencies {
+  exec: GitExec;
+  signal?: AbortSignal;
+  origin?: "host" | "server";
+  lstat?: typeof lstat;
+  realpath?: typeof realpath;
+}
+export type EvidenceContextResult =
+  | { ok: true; cwd: string; context: EvidenceContext }
+  | { ok: false; error: string; cause: Cause; context: EvidenceContext };
+
+/** Bind each judgment (including controls) to its admitted per-call provenance. */
+export function withEvidenceContext(
+  state: State,
+  context: EvidenceContext,
+): State {
+  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: string,
+  root: string | undefined,
+  deps: ContextDependencies,
+): Promise<EvidenceContextResult> {
+  const canonical = deps.realpath ?? realpath;
+  const inspect = deps.lstat ?? lstat;
+  let initial: string;
+  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: EvidenceContext = {
+    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: string,
+    cause: Cause = "invalid_root",
+  ): EvidenceContextResult => ({
+    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: string, args: string[]) => {
+      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/src/adapters/files.ts

@@ -19,7 +19,9 @@ import {
 import { createExcerptCollector } from "../core/find.ts";
 import type { GitExec } from "../core/git.ts";
 import type { FileIdentity } from "../core/integrity.ts";
+import { isSecretPath, secretRefusal } from "../core/secret-path.ts";
 import type { Result } from "../result.ts";
+import type { Cause } from "../result-types.ts";
 import { createUtf8Decoder, decodeUtf8 } from "./utf8.ts";
 
 export async function checkFileAdmission(
@@ -30,11 +32,22 @@ export async function checkFileAdmission(
   inventory?: ReadonlySet<string>,
 ): Promise<Result<object>> {
   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",
@@ -50,9 +63,17 @@ export async function checkFileAdmission(
     { 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 };
 }
 
@@ -64,6 +85,7 @@ export async function resolveInsideRepo(
   if (isAbsolute(path) || path.split(/[\\/]/).includes(".."))
     return {
       ok: false,
+      cause: "forbidden_path",
       error: `Path must remain inside the repository: ${path}.`,
     };
   try {
@@ -71,23 +93,39 @@ export async function resolveInsideRepo(
     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)}`,
+    };
   }
 }
 
@@ -125,6 +163,7 @@ export async function admitGitPath(
   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);
@@ -138,13 +177,21 @@ export async function admitGitPath(
       { 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 };
 }
 
@@ -178,7 +225,11 @@ export async function openRepoFile(
       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 };
     } catch (error) {
@@ -186,7 +237,15 @@ export async function openRepoFile(
       throw error;
     }
   } catch (error) {
-    return { ok: false, error: `Cannot read ${path}: ${String(error)}` };
+    return {
+      ok: false,
+      cause: options.signal?.aborted
+        ? "cancelled"
+        : (error as NodeJS.ErrnoException).code === "ELOOP"
+          ? "symlink"
+          : "file_unavailable",
+      error: `Cannot read ${path}: ${String(error)}`,
+    };
   }
 }
 
@@ -207,9 +266,27 @@ export async function collectFiles(
     skipped: string[];
   }>
 > {
+  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(
@@ -217,6 +294,7 @@ export async function collectFiles(
       if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path))
         return {
           ok: false as const,
+          cause: "forbidden_path" as const,
           error: `Internal URLs are not files; use read for ${path}.`,
         };
       let handle: FileHandle | undefined;
@@ -247,23 +325,30 @@ export async function collectFiles(
         if (count === bytes.length)
           return {
             ok: false as const,
+            cause: "evidence_too_large" as const,
             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 as const,
             invalidUtf8: true,
+            cause: "binary_or_non_utf8" as const,
             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 as const,
+            cause: "evidence_too_large" as const,
             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 as const, error: `${path} is empty.` };
+          return {
+            ok: false as const,
+            cause: "empty_required" as const,
+            error: `${path} is empty.`,
+          };
         return {
           ok: true as const,
           path,
@@ -282,6 +367,9 @@ export async function collectFiles(
       } catch (error) {
         return {
           ok: false as const,
+          cause: signal?.aborted
+            ? ("cancelled" as const)
+            : ("file_unavailable" as const),
           error: `Cannot read ${path}: ${String(error)}`,
         };
       } finally {
@@ -322,23 +410,31 @@ export async function collectSearchExcerpts(
     pointers: Record<string, string>;
     ignored: string[];
     limits: { path: string; reason: string }[];
+    omissions: { path: string; cause: Cause; reason: string }[];
   }>
 > {
   const files: Record<string, string> = {},
     pointers: Record<string, string> = {};
   const ignored: string[] = [];
   const limits: { path: string; reason: string }[] = [];
+  const omissions: { path: string; cause: Cause; reason: string }[] = [];
   const results = await Promise.all(
     paths.map(async (path) => {
       if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path))
         return {
           ok: false as const,
+          cause: "forbidden_path" as const,
           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 as const };
         }
         if ((await lstat(location.abs)).isSymbolicLink()) {
@@ -350,6 +446,11 @@ export async function collectSearchExcerpts(
         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 as const };
         }
         const handle = opened.handle;
@@ -367,6 +468,11 @@ export async function collectSearchExcerpts(
           const decoded = decode(chunk as Buffer);
           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 as const };
@@ -374,6 +480,11 @@ export async function collectSearchExcerpts(
           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 as const };
           }
@@ -383,6 +494,11 @@ export async function collectSearchExcerpts(
         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 as const };
         }
@@ -391,6 +507,11 @@ export async function collectSearchExcerpts(
         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 as const };
         }
         files[path] = excerpt;
@@ -398,8 +519,17 @@ export async function collectSearchExcerpts(
         return { ok: true as const };
       } catch (error) {
         if (signal?.aborted)
-          return { ok: false as const, error: String(error) };
+          return {
+            ok: false as const,
+            cause: "cancelled" as const,
+            error: String(error),
+          };
         ignored.push(path);
+        omissions.push({
+          path,
+          cause: "file_unavailable",
+          reason: String(error),
+        });
         return { ok: true as const };
       }
     }),
@@ -407,5 +537,5 @@ export async function collectSearchExcerpts(
   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/src/adapters/find.ts

@@ -1,3 +1,4 @@
+import { isAbsolute } from "node:path";
 import type { FileFinder, GrepCursor } from "@ff-labs/fff-node";
 import {
   FIND_GREP_PAGE_SIZE,
@@ -6,6 +7,7 @@ import {
 } from "../constants.ts";
 import { pathAllowed } from "../core/find.ts";
 import type { GitExec } from "../core/git.ts";
+import { isSecretPath, SECRET_NAME_GLOBS } from "../core/secret-path.ts";
 import type { Result } from "../result.ts";
 
 export async function prefilter(
@@ -17,7 +19,24 @@ export async function prefilter(
   exclude?: readonly string[],
   signal?: AbortSignal,
   native = true,
-): Promise<Result<{ paths: string[]; scopeFiles: number }>> {
+): Promise<Result<{ paths: string[]; scopeFiles: number; secret: string[] }>> {
+  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",
@@ -27,19 +46,25 @@ export async function prefilter(
     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)),
       ),
     ];
-    if (!paths.length) return { ok: true, paths: [], scopeFiles: 0 };
+    // 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, secret };
     const allowed = new Set(paths);
     let finder: FileFinder | undefined;
-    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");
@@ -97,8 +122,8 @@ export async function prefilter(
               "--files-with-matches",
               "--hidden",
               "--null",
-              "--fixed-strings",
-              "--ignore-case",
+              "--glob-case-insensitive",
+              ...SECRET_NAME_GLOBS.flatMap((glob) => ["--glob", `!${glob}`]),
               "--",
               word,
               ".",
@@ -141,11 +166,16 @@ export async function prefilter(
           .slice(0, limit)
           .map((item) => item.path),
         scopeFiles: paths.length,
+        secret,
       };
     } finally {
       finder?.destroy();
     }
   } 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/src/adapters/git-base.ts

@@ -16,16 +16,22 @@ export async function resolveBase(
       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)}`,
     };
   }