jev-agent-tools 0.1.4 → 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/exec.ts

@@ -0,0 +1,226 @@
+import { type ChildProcess, execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import {
+  PROCESS_KILL_GRACE_MS,
+  PROCESS_PIPE_GRACE_MS,
+  PROCESS_TREE_TIMEOUT_MS,
+} from "../constants.ts";
+import type { GitExec } from "../core/git.ts";
+
+/** Signal the managed process group, or await Windows process-tree termination. */
+export async function killTree(
+  child: ChildProcess,
+  signal: NodeJS.Signals = "SIGTERM",
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  const pid = child.pid;
+  if (pid === undefined) return;
+  if (platform === "win32") {
+    const taskkill = join(
+      process.env.SystemRoot ?? "C:\\Windows",
+      "System32",
+      "taskkill.exe",
+    );
+    const pids = [pid];
+    // MSYS fork/exec can leave Windows parent IDs pointing at vanished helper
+    // processes. Use the same Bash installation's POSIX table before killing
+    // the root; taskkill /T alone cannot find those ordinary descendants.
+    if (basename(child.spawnfile).toLowerCase() === "bash.exe") {
+      const directory = dirname(child.spawnfile);
+      const ps = [
+        join(directory, "ps.exe"),
+        join(directory, "..", "usr", "bin", "ps.exe"),
+      ].find(existsSync);
+      if (ps) {
+        const snapshot = Promise.withResolvers<string>();
+        execFile(
+          ps,
+          ["-e"],
+          { windowsHide: true, timeout: PROCESS_TREE_TIMEOUT_MS },
+          (error, stdout) => snapshot.resolve(error ? "" : stdout),
+        );
+        const rows = [];
+        for (const line of (await snapshot.promise).split("\n")) {
+          const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s/.exec(line);
+          if (!match) continue;
+          rows.push({
+            pid: Number(match[1]),
+            parent: Number(match[2]),
+            windows: Number(match[4]),
+          });
+        }
+        const root = rows.find((row) => row.windows === pid);
+        if (root) {
+          const managed = new Set([root.pid]);
+          let added = true;
+          while (added) {
+            added = false;
+            for (const row of rows) {
+              if (!managed.has(row.pid) && managed.has(row.parent)) {
+                managed.add(row.pid);
+                if (row.windows > 0) pids.push(row.windows);
+                added = true;
+              }
+            }
+          }
+        }
+      }
+    }
+    const { promise, resolve } = Promise.withResolvers<void>();
+    execFile(
+      taskkill,
+      [...new Set(pids)]
+        .flatMap((target) => ["/PID", String(target)])
+        .concat("/T", "/F"),
+      { windowsHide: true, timeout: PROCESS_TREE_TIMEOUT_MS },
+      (error) => {
+        if (error) child.kill();
+        resolve();
+      },
+    );
+    await promise;
+    return;
+  }
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    child.kill(signal);
+  }
+  return;
+}
+
+function groupExists(child: ChildProcess): boolean {
+  if (child.pid === undefined) return false;
+  try {
+    process.kill(-child.pid, 0);
+    return true;
+  } catch (error) {
+    return !(
+      error instanceof Error &&
+      "code" in error &&
+      error.code === "ESRCH"
+    );
+  }
+}
+
+/**
+ * Capture a process without a shell. Timeout and abort finish tree termination
+ * before resolving, even when the direct child exits before its descendants.
+ * Deliberately detached descendants are not sandboxed or tracked.
+ */
+export const spawnExec: GitExec = (command, args, options) => {
+  const { promise, resolve, reject } = Promise.withResolvers<{
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+  }>();
+  const posix = process.platform !== "win32";
+  // Git's bin/bash.exe forwards to usr/bin/bash.exe. Spawn the MSYS process
+  // directly so its Windows PID can be matched in the POSIX process table.
+  if (!posix && basename(command).toLowerCase() === "bash.exe") {
+    const direct = join(dirname(command), "..", "usr", "bin", "bash.exe");
+    if (existsSync(direct)) command = direct;
+  }
+  const child = spawn(command, args, {
+    cwd: options.cwd,
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+    detached: posix,
+  });
+  let stdout = "";
+  let stderr = "";
+  let killed = false;
+  let spawned = false;
+  let settled = false;
+  let finishing = false;
+  let force: NodeJS.Timeout | undefined;
+  let pipes: NodeJS.Timeout | undefined;
+  let termination: Promise<void> | undefined;
+  let terminated: (() => void) | undefined;
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk: string) => {
+    stdout += chunk;
+  });
+  child.stderr.on("data", (chunk: string) => {
+    stderr += chunk;
+  });
+  const kill = () => {
+    if (killed || settled) return;
+    killed = true;
+    if (posix) {
+      void killTree(child, "SIGTERM");
+      const completion = Promise.withResolvers<void>();
+      termination = completion.promise;
+      terminated = completion.resolve;
+      // Keep this timer referenced: a closing transport must not exit
+      // before a surviving member of the managed group receives SIGKILL.
+      force = setTimeout(() => {
+        void killTree(child, "SIGKILL");
+        completion.resolve();
+      }, PROCESS_KILL_GRACE_MS);
+    } else termination = killTree(child);
+  };
+  const timer =
+    options.timeout > 0 ? setTimeout(kill, options.timeout) : undefined;
+  if (options.signal?.aborted) kill();
+  else options.signal?.addEventListener("abort", kill, { once: true });
+  const cleanup = () => {
+    clearTimeout(timer);
+    clearTimeout(force);
+    clearTimeout(pipes);
+    options.signal?.removeEventListener("abort", kill);
+  };
+  const finish = async (code: number | null, signal: NodeJS.Signals | null) => {
+    if (settled || finishing) return;
+    finishing = true;
+    clearTimeout(pipes);
+    if (posix && terminated && !groupExists(child)) {
+      clearTimeout(force);
+      terminated();
+    }
+    if (termination) await termination;
+    settled = true;
+    cleanup();
+    resolve({
+      stdout,
+      stderr,
+      code: code ?? (signal ? 128 + signalNumber(signal) : 1),
+      killed,
+    });
+  };
+  child.on("spawn", () => {
+    spawned = true;
+  });
+  child.on("error", (error) => {
+    if (spawned) return;
+    settled = true;
+    cleanup();
+    reject(error);
+  });
+  child.on("exit", (code, signal) => {
+    // An escaped descendant may hold inherited pipes open indefinitely.
+    pipes = setTimeout(() => {
+      child.stdout.destroy();
+      child.stderr.destroy();
+      void finish(code, signal);
+    }, PROCESS_PIPE_GRACE_MS);
+  });
+  child.on("close", (code, signal) => {
+    void finish(code, signal);
+  });
+  return promise;
+};
+
+function signalNumber(signal: NodeJS.Signals): number {
+  const numbers: Partial<Record<NodeJS.Signals, number>> = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGKILL: 9,
+    SIGTERM: 15,
+  };
+  return numbers[signal] ?? 0;
+}