sift-light 1.0.0

package/src/ripgrep-executable.ts

@@ -0,0 +1,43 @@
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { SiftLightError } from "./errors.js";
+
+const OVERRIDE_ENV = "SIFT_LIGHT_RG_PATH";
+const BUNDLED_REPAIR = `Reinstall sift-light with optional dependencies enabled for this platform, or set ${OVERRIDE_ENV} to an absolute ripgrep executable path.`;
+
+/** One executable choice for content, filename and historical-source searches. */
+export async function resolveRipgrepExecutable(): Promise<string> {
+  const configured = process.env[OVERRIDE_ENV];
+  if (configured !== undefined && !isAbsolute(configured))
+    throw new SiftLightError(
+      `${OVERRIDE_ENV} must be an absolute executable file path; shell functions, aliases and relative paths are not supported.`,
+    );
+
+  let executable: string;
+  if (configured !== undefined) {
+    executable = configured;
+  } else {
+    try {
+      // Resolve lazily so a broken installation remains a visible tool error and an
+      // explicit executable can be used without loading the platform package.
+      executable = (await import("@vscode/ripgrep")).rgPath;
+    } catch (cause) {
+      throw new SiftLightError(`Bundled ripgrep is unavailable. ${BUNDLED_REPAIR}`, { cause });
+    }
+  }
+
+  try {
+    if (!(await stat(executable)).isFile()) throw new Error("Expected an executable file");
+    await access(executable, constants.X_OK);
+  } catch (cause) {
+    const repair =
+      configured === undefined
+        ? BUNDLED_REPAIR
+        : `Fix ${OVERRIDE_ENV} or unset it to use bundled ripgrep. No fallback was attempted.`;
+    throw new SiftLightError(`ripgrep executable is unavailable: ${executable}. ${repair}`, {
+      cause,
+    });
+  }
+  return executable;
+}

package/src/runtime.ts

@@ -0,0 +1,53 @@
+import type { SiftLightLocale } from "./config.js";
+import type { SiftLightInput, SiftLightSearchOptions, SiftLightService } from "./service.js";
+import { type SessionSummarySnapshot, SessionSummary } from "./session-summary.js";
+import type { ContextBudget, SiftLightResult } from "./types.js";
+
+export class SiftLightRuntime {
+  readonly #service: SiftLightService;
+  readonly #summary = new SessionSummary();
+
+  constructor(service: SiftLightService) {
+    this.#service = service;
+  }
+
+  async search(
+    input: SiftLightInput,
+    cwd: string,
+    signal?: AbortSignal,
+    contextBudget?: ContextBudget,
+  ): Promise<SiftLightResult> {
+    const searchOptions: SiftLightSearchOptions = {};
+    if (contextBudget) searchOptions.contextBudget = contextBudget;
+    const result = await this.#service.search(input, cwd, signal, searchOptions);
+    this.#summary.record(input, result);
+    return result;
+  }
+  recordFailure(): void {
+    this.#summary.recordFailure();
+  }
+
+  get sessionSummary(): SessionSummarySnapshot {
+    return this.#summary.snapshot;
+  }
+
+  formatSessionStatus(locale: SiftLightLocale): string | undefined {
+    return this.#summary.format(locale);
+  }
+
+  clear(): void {
+    this.#service.clear();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.#service.shutdown();
+  }
+
+  get snapshotCount(): number {
+    return this.#service.snapshotCount;
+  }
+
+  get storedMatches(): number {
+    return this.#service.storedMatches;
+  }
+}

package/src/scan-revisions.ts

@@ -0,0 +1,148 @@
+import { resolve } from "node:path";
+import { abortError, SiftLightError } from "./errors.js";
+import { runOwnedProcess } from "./owned-process.js";
+import {
+  boundedRipgrepDiagnostic,
+  classifyRipgrepDiagnostics,
+  createRipgrepInputError,
+  type RipgrepUnreadableDiagnostic,
+} from "./ripgrep-diagnostics.js";
+import { getSourceRevision, sameSourceRevision } from "./source.js";
+import {
+  MAX_PROTOCOL_LINE_BYTES,
+  MAX_SOURCE_REVISION_CONCURRENCY,
+  type SourceRevision,
+} from "./types.js";
+
+async function captureRevision(
+  path: string,
+  revisions: Map<string, SourceRevision>,
+  onRevisionError?: (path: string, error: unknown) => void,
+): Promise<void> {
+  let failed = false;
+  let failure: unknown;
+  const revision = await getSourceRevision(path, (error) => {
+    failed = true;
+    failure = error;
+  });
+  if (revision) revisions.set(path, revision);
+  if (failed) onRevisionError?.(path, failure);
+}
+
+async function captureBatch(
+  paths: string[],
+  revisions: Map<string, SourceRevision>,
+  signal?: AbortSignal,
+  onRevisionError?: (path: string, error: unknown) => void,
+): Promise<void> {
+  if (signal?.aborted) throw abortError();
+  await Promise.all(paths.map((path) => captureRevision(path, revisions, onRevisionError)));
+  if (signal?.aborted) throw abortError();
+}
+
+/** Enumerate names only; finish all retained metadata reads before starting content search. */
+export async function captureCandidateRevisions(
+  executable: string,
+  args: string[],
+  cwd: string,
+  maxFiles: number,
+  signal?: AbortSignal,
+  redact = false,
+): Promise<{
+  revisions: Map<string, SourceRevision>;
+  unreadable: RipgrepUnreadableDiagnostic[];
+  enumerationTruncated: boolean;
+  invalidPathCount: number;
+}> {
+  const revisions = new Map<string, SourceRevision>();
+  let candidateCount = 0;
+  let enumerationTruncated = false;
+  let invalidPathCount = 0;
+  const metadataFailures: RipgrepUnreadableDiagnostic[] = [];
+  const recordMetadataFailure = (path: string, error: unknown): void => {
+    const reason = error instanceof Error ? error.message : String(error);
+    metadataFailures.push({
+      path,
+      message: `Source metadata unavailable: ${boundedRipgrepDiagnostic(reason, redact)}`,
+    });
+  };
+  const result = await runOwnedProcess(
+    { executable, args, cwd, ...(signal ? { signal } : {}) },
+    async (stdout) => {
+      let pending = Buffer.alloc(0);
+      let batch: string[] = [];
+      for await (const chunk of stdout) {
+        if (signal?.aborted) throw abortError();
+        pending = Buffer.concat([pending, chunk]);
+        let delimiter = pending.indexOf(0);
+        while (delimiter >= 0) {
+          const rawPath = pending.subarray(0, delimiter);
+          if (rawPath.length > MAX_PROTOCOL_LINE_BYTES) {
+            throw new SiftLightError("ripgrep file path exceeds the protocol byte limit");
+          }
+          const path = rawPath.toString("utf8");
+          // Lossy file names cannot provide trustworthy path-based revision evidence.
+          if (Buffer.from(path, "utf8").equals(rawPath)) {
+            if (candidateCount < maxFiles) {
+              candidateCount += 1;
+              batch.push(resolve(cwd, path));
+            } else {
+              enumerationTruncated = true;
+            }
+            if (batch.length === MAX_SOURCE_REVISION_CONCURRENCY) {
+              // oxlint-disable-next-line no-await-in-loop -- backpressure bounds concurrent metadata reads.
+              await captureBatch(batch, revisions, signal, recordMetadataFailure);
+              batch = [];
+            }
+          } else {
+            invalidPathCount += 1;
+          }
+          pending = pending.subarray(delimiter + 1);
+          delimiter = pending.indexOf(0);
+        }
+        if (pending.length > MAX_PROTOCOL_LINE_BYTES) {
+          throw new SiftLightError("ripgrep file path exceeds the protocol byte limit");
+        }
+      }
+      if (pending.length > 0) {
+        throw new SiftLightError("ripgrep file enumeration ended without a NUL delimiter");
+      }
+      await captureBatch(batch, revisions, signal, recordMetadataFailure);
+    },
+  );
+  const diagnostics = classifyRipgrepDiagnostics(result.stderr);
+  const inputError = createRipgrepInputError(result.stderr, redact);
+  const unreadable = [...diagnostics.unreadable, ...metadataFailures];
+  if (inputError) throw inputError;
+  if (result.code === 2 && diagnostics.other.length === 0 && unreadable.length > 0)
+    return { revisions, unreadable, enumerationTruncated, invalidPathCount };
+  if (result.code !== 0 && result.code !== 1) {
+    throw new SiftLightError(
+      result.stderr.trim() || `ripgrep file enumeration exited with status ${String(result.code)}`,
+    );
+  }
+  return { revisions, unreadable, enumerationTruncated, invalidPathCount };
+}
+
+export async function retainStableSourceRevisions(
+  paths: ReadonlySet<string>,
+  before: ReadonlyMap<string, SourceRevision>,
+  signal?: AbortSignal,
+): Promise<Map<string, SourceRevision>> {
+  const after = new Map<string, SourceRevision>();
+  const candidates = [...paths].filter((path) => before.has(path));
+  for (let offset = 0; offset < candidates.length; offset += MAX_SOURCE_REVISION_CONCURRENCY) {
+    // oxlint-disable-next-line no-await-in-loop -- batches keep source metadata concurrency bounded.
+    await captureBatch(
+      candidates.slice(offset, offset + MAX_SOURCE_REVISION_CONCURRENCY),
+      after,
+      signal,
+    );
+  }
+  return new Map(
+    [...after].filter(([path, revision]) => {
+      const initial = before.get(path);
+      return initial !== undefined && sameSourceRevision(initial, revision);
+    }),
+  );
+}

package/src/script-runtime.ts

@@ -0,0 +1,11 @@
+/**
+ * Children executing JavaScript must run the runtime, not a compiled host's
+ * bundled entrypoint. Bun's documented CLI mode preserves the host runtime
+ * without requiring a second executable on PATH. Never mutate the host env.
+ */
+export function scriptRuntimeEnvironment(): NodeJS.ProcessEnv {
+  const env = { ...process.env };
+  delete env.NODE_OPTIONS;
+  if (process.versions.bun) env.BUN_BE_BUN = "1";
+  return env;
+}

package/src/search-policy-commands.ts

@@ -0,0 +1,170 @@
+export type SearchKind = "content" | "files";
+export type ShellLanguage = "bash" | "powershell";
+
+export interface CommandDecision {
+  kind?: SearchKind;
+  command?: string;
+  nested?: { command: string; language: ShellLanguage };
+}
+
+const contentCommands = new Set([
+  "rg",
+  "ripgrep",
+  "grep",
+  "egrep",
+  "fgrep",
+  "ag",
+  "ack",
+  "ack-grep",
+  "ugrep",
+  "pt",
+  "sift",
+  "findstr",
+]);
+const fileCommands = new Set(["find", "fd", "fdfind", "locate", "mlocate", "plocate"]);
+
+export function executableName(value: string): string {
+  return (
+    value
+      .split(/[\\/]/u)
+      .at(-1)
+      ?.replace(/\.(?:exe|cmd|bat)$/iu, "") ?? value
+  );
+}
+
+function afterOptions(args: readonly (string | null)[], valueOptions: ReadonlySet<string>): number {
+  let index = 0;
+  while (index < args.length) {
+    const value = args[index];
+    if (value === null || value === undefined) return args.length;
+    if (value === "--") return index + 1;
+    if (!value.startsWith("-")) return index;
+    index += valueOptions.has(value) ? 2 : 1;
+  }
+  return index;
+}
+
+const gitValueOptions = new Set([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--config-env",
+]);
+const envValueOptions = new Set(["-u", "--unset", "-C", "--chdir"]);
+const wrapperValueOptions: Readonly<Record<string, ReadonlySet<string>>> = {
+  env: envValueOptions,
+  sudo: new Set([
+    "-u",
+    "--user",
+    "-g",
+    "--group",
+    "-h",
+    "--host",
+    "-p",
+    "--prompt",
+    "-C",
+    "--close-from",
+    "-T",
+    "--command-timeout",
+    "-r",
+    "--role",
+    "-t",
+    "--type",
+  ]),
+  nice: new Set(["-n", "--adjustment"]),
+  timeout: new Set(["-s", "--signal", "-k", "--kill-after"]),
+  time: new Set(["-f", "--format", "-o", "--output"]),
+  xargs: new Set([
+    "-a",
+    "--arg-file",
+    "-d",
+    "--delimiter",
+    "-E",
+    "-I",
+    "-L",
+    "-n",
+    "--max-args",
+    "-P",
+    "--max-procs",
+    "-s",
+    "--max-chars",
+  ]),
+  exec: new Set(["-a"]),
+  command: new Set(),
+  nohup: new Set(),
+  busybox: new Set(),
+};
+
+/** Classify executable positions only; never inspect ordinary argument text as a command. */
+export function classifyCommand(
+  argv: readonly (string | null)[],
+  language: ShellLanguage,
+  depth = 0,
+): CommandDecision {
+  if (depth > 8)
+    throw new Error("Search policy wrapper nesting exceeds 8 levels; simplify the command");
+  const first = argv[0];
+  if (first === null || first === undefined) return {};
+  const rawName = executableName(first);
+  const name = language === "powershell" ? rawName.toLowerCase() : rawName;
+  const args = argv.slice(1);
+  if (args.length === 1 && (args[0] === "--help" || args[0] === "--version")) return {};
+  if (contentCommands.has(name)) return { kind: "content", command: name };
+  if (fileCommands.has(name)) return { kind: "files", command: name };
+  if (language === "powershell") {
+    if (name === "select-string" || name === "sls") return { kind: "content", command: name };
+    if (
+      ["get-childitem", "gci", "dir", "ls"].includes(name) &&
+      args.some((arg, index) => {
+        if (arg === null) return false;
+        if (/^-(?:recurse|r|filter|include)(?::|$)/iu.test(arg)) return true;
+        // LiteralPath treats brackets and wildcard characters as ordinary path text.
+        if (/^-literalpath(?::|$)/iu.test(arg) || /^-literalpath$/iu.test(args[index - 1] ?? ""))
+          return false;
+        return /[*?[]/u.test(arg);
+      })
+    )
+      return { kind: "files", command: name };
+  }
+  if (name === "git") {
+    return args[afterOptions(args, gitValueOptions)] === "grep"
+      ? { kind: "content", command: "git grep" }
+      : {};
+  }
+  if (["bash", "sh", "zsh", "dash", "ksh"].includes(name)) {
+    const index = args.findIndex((arg) => arg !== null && /^-[a-z]*c[a-z]*$/u.test(arg));
+    const command = index >= 0 ? args[index + 1] : undefined;
+    return typeof command === "string" ? { nested: { command, language: "bash" } } : {};
+  }
+  if (name === "pwsh" || name === "powershell") {
+    const index = args.findIndex((arg) => arg !== null && /^-(?:command|c)$/iu.test(arg));
+    const command = index >= 0 ? args[index + 1] : undefined;
+    return typeof command === "string" ? { nested: { command, language: "powershell" } } : {};
+  }
+  if (name === "env") {
+    const split = args
+      .slice(0, afterOptions(args, envValueOptions))
+      .findIndex(
+        (arg) => arg === "-S" || arg === "--split-string" || arg?.startsWith("--split-string="),
+      );
+    const option = split >= 0 ? args[split] : undefined;
+    const command = option?.startsWith("--split-string=")
+      ? option.slice("--split-string=".length)
+      : split >= 0
+        ? args[split + 1]
+        : undefined;
+    if (typeof command === "string") return { nested: { command, language: "bash" } };
+  }
+  const options = wrapperValueOptions[name];
+  if (!options) return {};
+  if (name === "command" && args.some((arg) => arg === "-v" || arg === "-V")) return {};
+  let start = afterOptions(args, options);
+  if (name === "timeout") start += 1;
+  if (name === "env") {
+    while (typeof args[start] === "string" && /^[A-Za-z_][A-Za-z0-9_]*=/u.test(args[start] ?? ""))
+      start += 1;
+  }
+  return classifyCommand(args.slice(start), language, depth + 1);
+}

package/src/search-policy-hook.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { SearchPolicy } from "./search-policy.js";
+import { readNativeSearchEnforcement } from "./config-reader.js";
+
+const MAX_HOOK_INPUT_BYTES = 256 * 1024;
+
+async function hookInput(): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+    size += bytes.byteLength;
+    if (size > MAX_HOOK_INPUT_BYTES) throw new Error("Search policy hook input exceeds 256 KiB");
+    chunks.push(bytes);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function deny(reason: string): void {
+  process.stdout.write(
+    `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } })}\n`,
+  );
+}
+
+const inputTimer = setTimeout(() => {
+  process.stderr.write("sift-light search policy: hook input timed out\n");
+  process.exit(2);
+}, 3000);
+try {
+  const input = await hookInput();
+  clearTimeout(inputTimer);
+  const enforcement = readNativeSearchEnforcement();
+  if (
+    typeof input !== "object" ||
+    input === null ||
+    !("hook_event_name" in input) ||
+    input.hook_event_name !== "PreToolUse" ||
+    !("tool_name" in input) ||
+    typeof input.tool_name !== "string" ||
+    !("tool_input" in input)
+  )
+    throw new Error("Search policy received an invalid PreToolUse payload");
+  const decision =
+    enforcement === "hard"
+      ? await new SearchPolicy(new URL("./", import.meta.url)).check(
+          input.tool_name,
+          input.tool_input,
+        )
+      : undefined;
+  if (decision) deny(decision.reason);
+} catch (error) {
+  clearTimeout(inputTimer);
+  // Do not echo command text, paths, or JSON parse errors that could contain credentials.
+  deny(
+    error instanceof Error &&
+      (error.message.startsWith("Search policy") ||
+        error.message.startsWith("Invalid sift-light environment variable"))
+      ? error.message
+      : "sift-light search policy failed; repair or disable this plugin before retrying",
+  );
+}