@cassiomc1/forgeloop 1.10.2 → 1.11.0

package/src/repository-index/search.js

@@ -0,0 +1,262 @@
+import { realpath } from "node:fs/promises";
+
+import { getCanonicalRepositorySearchArgs, appendSearchFilters } from "./args.js";
+import { REPOSITORY_INDEX_DEFAULTS, REPOSITORY_INDEX_ENV_BINARY } from "./constants.js";
+import { REPOSITORY_INDEX_ERROR_CODES, repositoryIndexError } from "./errors.js";
+import { getManagedTgrepBinaryPath, getTgrepIndexPath } from "./paths.js";
+import { getRepositoryIndexPlatform } from "./platform.js";
+import { loadTgrepManifest } from "./manifest.js";
+import { createTgrepBinaryHandle, runTgrep } from "./process.js";
+import { normalizeTgrepJson } from "./normalize-json.js";
+import { setupRepositoryIndex } from "./server.js";
+import { getRepositoryIndexStatus } from "./status.js";
+import { buildRepositorySearchMetrics } from "./metrics.js";
+import {
+  getRepositoryIndexReadiness,
+  invalidateRepositoryIndexReadiness,
+  isRepositoryIndexReadinessUsable,
+  markRepositoryIndexSearchSucceeded,
+  rememberRepositoryIndexReadiness,
+} from "./readiness.js";
+
+const MAX_PATTERN_CHARS = 4_096;
+const MAX_FILTERS = 32;
+
+function validateSearchRequest({ pattern, globs = [], types = [], context, beforeContext, afterContext, maxCount } = {}) {
+  if (typeof pattern !== "string" || pattern.length === 0 || pattern.length > MAX_PATTERN_CHARS) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.REQUEST_INVALID, `Search pattern must contain 1-${MAX_PATTERN_CHARS} characters`);
+  }
+  for (const [label, values] of [["globs", globs], ["types", types]]) {
+    if (!Array.isArray(values) || values.length > MAX_FILTERS || values.some((value) => typeof value !== "string" || value.length === 0 || value.length > 256)) {
+      throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.REQUEST_INVALID, `Search ${label} must contain at most ${MAX_FILTERS} bounded strings`);
+    }
+  }
+  for (const [label, value] of [["context", context], ["beforeContext", beforeContext], ["afterContext", afterContext], ["maxCount", maxCount]]) {
+    if (value !== undefined && value !== null && (!Number.isSafeInteger(value) || value < 0 || (label === "maxCount" && value === 0))) {
+      throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.REQUEST_INVALID, `Search ${label} must be a valid positive or non-negative integer`);
+    }
+  }
+}
+
+function normalizeSearchInvocation(repositoryRoot, request) {
+  if (repositoryRoot && typeof repositoryRoot === "object" && request && Object.keys(request).length === 0) {
+    const normalizedRequest = { ...repositoryRoot };
+    return {
+      repositoryRoot: normalizedRequest.repoRoot ?? normalizedRequest.repositoryRoot ?? normalizedRequest.projectPath,
+      request: normalizedRequest,
+    };
+  }
+  return { repositoryRoot, request };
+}
+
+async function prepareSearch(repositoryRoot, request) {
+  const canonicalRoot = await realpath(repositoryRoot);
+  const setupImpl = request.setupRepositoryIndexImpl ?? setupRepositoryIndex;
+  const cached = getRepositoryIndexReadiness(canonicalRoot, request.platform ?? process.platform);
+  if (cached) {
+    const expected = await expectedReadiness(canonicalRoot, request);
+    if (isRepositoryIndexReadinessUsable(cached, expected, { isAlive: request.processIsAliveImpl })) {
+      return {
+        status: cached.status,
+        canonicalRoot,
+        indexPath: cached.indexPath,
+        binaryPath: cached.binaryPath,
+        cacheHit: true,
+      };
+    }
+    invalidateRepositoryIndexReadiness(canonicalRoot, request.platform ?? process.platform);
+  }
+
+  const setup = await setupImpl(repositoryRoot, request);
+  const status = setup.status?.repositoryRoot
+    ? setup.status
+    : await (request.getRepositoryIndexStatusImpl ?? getRepositoryIndexStatus)(canonicalRoot, { ...request, includeLocalPaths: true });
+  if (status.health !== "READY") {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.SERVER_UNHEALTHY, "Repository Index is not ready for search", { status });
+  }
+  const indexPath = status.indexPath;
+  const binaryPath = status.binaryPath ?? request.binaryPath;
+  if (!indexPath || !binaryPath) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.SERVER_UNHEALTHY, "Repository Index readiness did not provide executable paths", { status });
+  }
+  rememberRepositoryIndexReadiness({ canonicalRoot, status, platform: request.platform });
+  return { status, canonicalRoot, indexPath, binaryPath, cacheHit: false };
+}
+
+async function expectedReadiness(canonicalRoot, request) {
+  const manifest = await loadTgrepManifest(request.packageRoot);
+  const selectedPlatform = getRepositoryIndexPlatform({ platform: request.platform, arch: request.arch });
+  const override = request.binaryPath
+    ?? (request.env === undefined ? process.env[REPOSITORY_INDEX_ENV_BINARY] : request.env?.[REPOSITORY_INDEX_ENV_BINARY]);
+  const binaryPath = override ?? getManagedTgrepBinaryPath(manifest.version, selectedPlatform.key, {
+    homeDirectory: request.homeDirectory,
+    windows: selectedPlatform.platform === "win32",
+  });
+  return {
+    canonicalRoot,
+    indexPath: getTgrepIndexPath(canonicalRoot),
+    binaryPath,
+    engineVersion: manifest.version,
+    platform: selectedPlatform.platform,
+  };
+}
+
+function assertSearchInvocation(repositoryRoot, request) {
+  if (typeof repositoryRoot !== "string" || repositoryRoot.length === 0) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.REQUEST_INVALID, "Search repoRoot is required");
+  }
+  if (!request || typeof request !== "object" || Array.isArray(request)) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.REQUEST_INVALID, "Search request must be an object");
+  }
+}
+
+function buildSearchArgs({ indexPath, canonicalRoot, request }) {
+  const args = [...getCanonicalRepositorySearchArgs({
+    indexPath,
+    pattern: request.pattern,
+    options: request,
+    config: request.config,
+  })];
+  appendSearchFilters(args, { globs: request.globs, types: request.types });
+  args.push(canonicalRoot);
+  return args;
+}
+
+async function runSearch({ binaryPath, status, canonicalRoot, request, args }) {
+  const startedAt = Date.now();
+  const result = await (request.runTgrepImpl ?? runTgrep)({
+    binary: createTgrepBinaryHandle(binaryPath),
+    repoRoot: canonicalRoot,
+    args,
+    env: request.env,
+    spawnImpl: request.spawnImpl,
+    timeoutMs: request.commandTimeoutMs ?? REPOSITORY_INDEX_DEFAULTS.commandTimeoutMs,
+    maxOutputBytes: request.maxProcessOutputBytes ?? REPOSITORY_INDEX_DEFAULTS.maxProcessOutputBytes,
+  });
+  if (result.timedOut || ![0, 1].includes(result.exitCode)) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.SEARCH_FAILED, `tgrep search failed with exit code ${result.exitCode ?? "unknown"}`, {
+      exitCode: result.exitCode,
+      stderr: result.stderr.slice(0, 4000),
+    });
+  }
+  const normalized = await normalizeTgrepJson(result.stdout, {
+    repositoryRoot: canonicalRoot,
+    filesWithMatches: request.filesWithMatches === true,
+  });
+  return { result, normalized, startedAt, status };
+}
+
+function isRecoverableSearchFailure(error) {
+  if (error?.code === REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED) return true;
+  if (error?.code !== REPOSITORY_INDEX_ERROR_CODES.SEARCH_FAILED) return false;
+  return /server|index|connect|connection|not running|metadata|broken pipe|no such file|unavailable/i.test(error.stderr ?? "");
+}
+
+function collectErrorPaths(error) {
+  const paths = [];
+  const seen = new Set();
+  for (let current = error; current && !seen.has(current); current = current.cause) {
+    seen.add(current);
+    for (const key of ["path", "binaryPath", "repositoryRoot", "indexPath", "statePath", "archivePath", "manifestPath", "source"]) {
+      if (typeof current[key] === "string") paths.push(current[key]);
+    }
+    const status = current.status;
+    if (status && typeof status === "object") {
+      for (const value of [status.binaryPath, status.repositoryRoot, status.indexPath, status.statePath, status.index?.rootPath]) {
+        if (typeof value === "string") paths.push(value);
+      }
+    }
+  }
+  return [...new Set(paths)].sort((left, right) => right.length - left.length);
+}
+
+function sanitizeSearchError(error, request, repositoryRoot) {
+  const localPaths = [...new Set([
+    repositoryRoot,
+    request.binaryPath,
+    request.homeDirectory,
+    request.assetPath,
+    process.cwd(),
+    ...collectErrorPaths(error),
+  ].filter((value) => typeof value === "string" && value.length > 0))].sort((left, right) => right.length - left.length);
+  const redact = (value) => localPaths.reduce((result, localPath) => result.replaceAll(localPath, "<local-path>"), String(value ?? ""));
+  if (localPaths.length === 0) return error;
+  const sanitized = repositoryIndexError(error.code ?? REPOSITORY_INDEX_ERROR_CODES.SEARCH_FAILED, redact(error.message));
+  for (const key of ["exitCode", "signal", "timedOut", "stderr", "stdout", "expectedVersion", "actualVersion"]) {
+    if (error[key] !== undefined) sanitized[key] = typeof error[key] === "string" ? redact(error[key]) : error[key];
+  }
+  return sanitized;
+}
+
+function buildSearchResult({ request, status, result, normalized, startedAt }) {
+  return {
+    schemaVersion: 1,
+    query: {
+      pattern: request.pattern,
+      globs: [...(request.globs ?? [])],
+      types: [...(request.types ?? [])],
+      filesWithMatches: request.filesWithMatches === true,
+      stats: request.stats === true,
+      fixedStrings: request.fixedStrings === true,
+      ignoreCase: request.ignoreCase === true,
+      smartCase: request.smartCase === true,
+      wordRegexp: request.wordRegexp === true,
+      context: request.context ?? null,
+      beforeContext: request.beforeContext ?? null,
+      afterContext: request.afterContext ?? null,
+      maxCount: request.maxCount ?? null,
+    },
+    repositoryIndex: {
+      engine: status?.engine ?? "tgrep",
+      engineVersion: status?.engineVersion ?? null,
+      indexed: true,
+      server: status?.server?.running === true,
+    },
+    matches: normalized.matches,
+    contexts: normalized.contexts,
+    files: normalized.files,
+    stats: normalized.stats,
+    metrics: buildRepositorySearchMetrics({
+      durationMs: Date.now() - startedAt,
+      nativeDurationMs: result.durationMs,
+      result: { ...normalized, exitCode: result.exitCode },
+      engine: status?.engine ?? "tgrep",
+      engineVersion: status?.engineVersion ?? null,
+      serverUsed: status?.server?.running === true,
+    }),
+  };
+}
+
+export async function searchRepository(repositoryRoot, request = {}) {
+  ({ repositoryRoot, request } = normalizeSearchInvocation(repositoryRoot, request));
+  assertSearchInvocation(repositoryRoot, request);
+  validateSearchRequest(request);
+  let prepared;
+  try {
+    prepared = await prepareSearch(repositoryRoot, request);
+  } catch (error) {
+    throw sanitizeSearchError(error, request, repositoryRoot);
+  }
+  let args = buildSearchArgs({ indexPath: prepared.indexPath, canonicalRoot: prepared.canonicalRoot, request });
+  try {
+    const execution = await runSearch({ binaryPath: prepared.binaryPath, status: prepared.status, canonicalRoot: prepared.canonicalRoot, request, args });
+    markRepositoryIndexSearchSucceeded(prepared.canonicalRoot, request.platform ?? process.platform);
+    return buildSearchResult({ request, ...execution });
+  } catch (error) {
+    if (!isRecoverableSearchFailure(error)) throw sanitizeSearchError(error, request, prepared.canonicalRoot);
+    invalidateRepositoryIndexReadiness(prepared.canonicalRoot, request.platform ?? process.platform);
+    try {
+      prepared = await prepareSearch(prepared.canonicalRoot, request);
+    } catch (recoveryError) {
+      throw sanitizeSearchError(recoveryError, request, prepared.canonicalRoot);
+    }
+    args = buildSearchArgs({ indexPath: prepared.indexPath, canonicalRoot: prepared.canonicalRoot, request });
+    try {
+      const execution = await runSearch({ binaryPath: prepared.binaryPath, status: prepared.status, canonicalRoot: prepared.canonicalRoot, request, args });
+      markRepositoryIndexSearchSucceeded(prepared.canonicalRoot, request.platform ?? process.platform);
+      return buildSearchResult({ request, ...execution });
+    } catch (retryError) {
+      throw sanitizeSearchError(retryError, request, prepared.canonicalRoot);
+    }
+  }
+}

package/src/repository-index/server.js

@@ -0,0 +1,432 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rm, unlink } from "node:fs/promises";
+import path from "node:path";
+
+import { assertSafePath, realpathWithTransientWindowsRetry, writeFileAtomic } from "../core/filesystem.js";
+import { REPOSITORY_INDEX_DEFAULTS } from "./constants.js";
+import { REPOSITORY_INDEX_ERROR_CODES as ERROR_CODES, repositoryIndexError, wrapRepositoryIndexError } from "./errors.js";
+import { ensureManagedTgrep } from "./binary-manager.js";
+import { getCanonicalRepositoryIndexArgs } from "./args.js";
+import { withRepositoryIndexLock } from "./lock.js";
+import { createTgrepBinaryHandle, runTgrep, spawnTgrepServer } from "./process.js";
+import {
+  getRepositoryIndexRoot,
+  getRepositoryIndexStatePath,
+  getTgrepIndexPath,
+} from "./paths.js";
+import { getRepositoryIndexStatus, inspectRepositoryIndexServer, processIsAlive } from "./status.js";
+import { invalidateRepositoryIndexReadiness, rememberRepositoryIndexReadiness } from "./readiness.js";
+
+async function readJson(filePath) {
+  try {
+    const info = await lstat(filePath);
+    if (info.isSymbolicLink() || !info.isFile()) return null;
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await writeFileAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function removeFileIfPresent(filePath) {
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+
+function serverArgs(indexPath, config) {
+  return [
+    "serve",
+    ...getCanonicalRepositoryIndexArgs({ mode: "serve", indexPath, config }),
+  ];
+}
+
+function indexArgs(indexPath, config, force) {
+  return [
+    "index",
+    ...(force ? ["--force"] : []),
+    ...getCanonicalRepositoryIndexArgs({ mode: "index", indexPath, config }),
+  ];
+}
+
+async function assertIndexPaths(repositoryRoot) {
+  await assertSafePath(repositoryRoot, ".forgeloop/repository-index");
+  await assertSafePath(repositoryRoot, ".forgeloop/repository-index/tgrep");
+  await assertSafePath(repositoryRoot, ".forgeloop/repository-index/engine-state.json");
+  await mkdir(getRepositoryIndexRoot(repositoryRoot), { recursive: true });
+}
+
+async function readIndexMetadata(repositoryRoot) {
+  const indexPath = getTgrepIndexPath(repositoryRoot);
+  const statePath = getRepositoryIndexStatePath(repositoryRoot);
+  return {
+    meta: await readJson(path.join(indexPath, "meta.json")),
+    state: await readJson(statePath),
+    serve: await readJson(path.join(indexPath, "serve.json")),
+  };
+}
+
+function comparableRepositoryPath(value, platform = process.platform) {
+  const pathApi = platform === "win32" ? path.win32 : path;
+  let normalized = pathApi.normalize(value);
+  if (platform === "win32") {
+    normalized = normalized.replace(/^\\\\\?\\/u, "").replace(/^\\\\\.\\/u, "");
+    normalized = normalized.toLowerCase();
+  }
+  return normalized;
+}
+
+function sameRepositoryPath(left, right, platform = process.platform) {
+  return typeof left === "string"
+    && typeof right === "string"
+    && comparableRepositoryPath(left, platform) === comparableRepositoryPath(right, platform);
+}
+
+function indexIsUsable({ meta, state, repositoryRoot, engineVersion, platform = process.platform }) {
+  return meta?.complete === true
+    && typeof meta.root_path === "string"
+    && sameRepositoryPath(meta.root_path, repositoryRoot, platform)
+    && state?.schemaVersion === 1
+    && state?.engine === "tgrep"
+    && state?.engineVersion === engineVersion
+    && sameRepositoryPath(state?.repositoryRoot, repositoryRoot, platform)
+    && sameRepositoryPath(state?.indexPath, getTgrepIndexPath(repositoryRoot), platform);
+}
+
+async function waitForServerReady({ repositoryRoot, indexPath, child, engine, timeoutMs, processInspector }) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    if (child?.pid && !processIsAlive(child.pid)) {
+      throw repositoryIndexError(ERROR_CODES.SERVER_START_FAILED, "tgrep server exited before becoming ready", { pid: child.pid });
+    }
+    try {
+      const { serve, state, meta } = await readIndexMetadata(repositoryRoot);
+      const ownership = await inspectRepositoryIndexServer({
+        state,
+        serve,
+        repositoryRoot,
+        indexPath,
+        processInspector,
+      });
+      if (ownership.running && meta?.complete === true) {
+        return { serve, state, meta, ownership };
+      }
+      lastError = ownership.reason ?? "metadata not ready";
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw repositoryIndexError(
+    ERROR_CODES.SERVER_START_FAILED,
+    `tgrep server did not become ready within ${timeoutMs}ms${lastError ? `: ${lastError.message ?? lastError}` : ""}`,
+    { binaryPath: engine.binaryPath, repositoryRoot, indexPath },
+  );
+}
+
+async function terminateOwnedServer({ repositoryRoot, indexPath, statePath, processInspector = {}, timeoutMs = 15_000 }) {
+  const { state, serve } = await readIndexMetadata(repositoryRoot);
+  if (state?.startedByForgeLoop === true && !serve) {
+    throw repositoryIndexError(ERROR_CODES.SERVER_STOP_FAILED, "ForgeLoop server state has no matching tgrep serve metadata; refusing to guess the process identity");
+  }
+  const ownership = await inspectRepositoryIndexServer({
+    state,
+    serve,
+    repositoryRoot,
+    indexPath,
+    processInspector,
+  });
+  if (ownership.running) {
+    try {
+      process.kill(ownership.pid);
+    } catch (error) {
+      if (error.code !== "ESRCH") {
+        throw repositoryIndexError(ERROR_CODES.SERVER_STOP_FAILED, `Unable to stop owned tgrep server: ${error.message}`, { cause: error, pid: ownership.pid });
+      }
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && processIsAlive(ownership.pid)) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (processIsAlive(ownership.pid)) {
+      throw repositoryIndexError(ERROR_CODES.SERVER_STOP_FAILED, `Owned tgrep server did not stop within ${timeoutMs}ms`, { pid: ownership.pid });
+    }
+  } else if (serve && !ownership.owned) {
+    throw repositoryIndexError(ERROR_CODES.SERVER_STOP_FAILED, "Refusing to remove tgrep server metadata without verifiable ForgeLoop ownership", { reason: ownership.reason });
+  }
+  if (ownership.owned || !serve) {
+    await removeFileIfPresent(path.join(indexPath, "serve.json"));
+    const currentState = await readJson(statePath);
+    if (currentState?.startedByForgeLoop === true && currentState.repositoryRoot === repositoryRoot) {
+      await removeFileIfPresent(statePath);
+    }
+  }
+  return { stopped: ownership.running || ownership.owned, pid: ownership.pid ?? null };
+}
+
+async function startUnderLock(repositoryRoot, options, engine) {
+  const indexPath = getTgrepIndexPath(repositoryRoot);
+  const statePath = getRepositoryIndexStatePath(repositoryRoot);
+  const metadata = await readIndexMetadata(repositoryRoot);
+  if (!metadata.meta?.complete) {
+    throw repositoryIndexError(ERROR_CODES.NOT_INITIALIZED, "Repository Index has not been built; run forgeloop index-setup first");
+  }
+
+  if (metadata.serve || metadata.state) {
+    const ownership = await inspectRepositoryIndexServer({
+      state: metadata.state,
+      serve: metadata.serve,
+      repositoryRoot,
+      indexPath,
+      processInspector: options.processInspector,
+    });
+    if (ownership.running) {
+      return {
+        started: false,
+        alreadyRunning: true,
+        pid: ownership.pid,
+        port: ownership.port,
+        status: await getRepositoryIndexStatus(repositoryRoot, { ...options, packageRoot: options.packageRoot, binaryPath: engine.overridden ? engine.binaryPath : undefined, skipNativeStatus: true, includeLocalPaths: true }),
+      };
+    }
+    if (metadata.serve && !ownership.owned) {
+      throw repositoryIndexError(ERROR_CODES.SERVER_START_FAILED, "Refusing to replace a tgrep server without verifiable ForgeLoop ownership", { reason: ownership.reason });
+    }
+    if (metadata.state?.startedByForgeLoop === true && !metadata.serve) {
+      throw repositoryIndexError(ERROR_CODES.SERVER_START_FAILED, "ForgeLoop server state has no matching tgrep serve metadata; refusing to guess the process identity");
+    }
+    if (ownership.owned || !metadata.serve) await terminateOwnedServer({ repositoryRoot, indexPath, statePath, processInspector: options.processInspector });
+  }
+
+  const startedAt = new Date().toISOString();
+  const child = spawnTgrepServer({
+    binary: createTgrepBinaryHandle(engine.binaryPath),
+    repoRoot: repositoryRoot,
+    args: serverArgs(indexPath, options.config),
+    env: options.env,
+    spawnImpl: options.spawnImpl,
+    stdio: options.stdio ?? "ignore",
+  });
+  if (!Number.isInteger(child.pid) || child.pid <= 0) {
+    throw repositoryIndexError(ERROR_CODES.SERVER_START_FAILED, "tgrep server did not provide a valid process ID");
+  }
+  const state = {
+    schemaVersion: 1,
+    engine: "tgrep",
+    engineVersion: engine.engineVersion,
+    binaryPath: engine.binaryPath,
+    repositoryRoot,
+    indexPath,
+    observedPid: child.pid,
+    startedByForgeLoop: true,
+    watcher: true,
+    startedAt,
+    stateId: randomUUID(),
+  };
+  await writeJson(statePath, state);
+  try {
+    const ready = await waitForServerReady({
+      repositoryRoot,
+      indexPath,
+      child,
+      engine,
+      timeoutMs: options.startupTimeoutMs ?? REPOSITORY_INDEX_DEFAULTS.startupTimeoutMs,
+      processInspector: options.processInspector,
+    });
+    await writeJson(statePath, {
+      ...(ready.state ?? state),
+      lastReadyAt: new Date().toISOString(),
+    });
+    return {
+      started: true,
+      alreadyRunning: false,
+      pid: ready.ownership.pid,
+      port: ready.ownership.port,
+      status: await getRepositoryIndexStatus(repositoryRoot, { ...options, packageRoot: options.packageRoot, binaryPath: engine.overridden ? engine.binaryPath : undefined, skipNativeStatus: true, includeLocalPaths: true }),
+    };
+  } catch (error) {
+    try { process.kill(child.pid); } catch { /* best effort for the exact child only */ }
+    await removeFileIfPresent(statePath);
+    throw error;
+  }
+}
+
+async function buildUnderLock(repositoryRoot, options, engine, { force = false } = {}) {
+  const indexPath = getTgrepIndexPath(repositoryRoot);
+  const result = await runTgrep({
+    binary: createTgrepBinaryHandle(engine.binaryPath),
+    repoRoot: repositoryRoot,
+    args: indexArgs(indexPath, options.config, force),
+    env: options.env,
+    spawnImpl: options.spawnImpl,
+    timeoutMs: options.commandTimeoutMs ?? REPOSITORY_INDEX_DEFAULTS.commandTimeoutMs,
+    maxOutputBytes: options.maxProcessOutputBytes ?? REPOSITORY_INDEX_DEFAULTS.maxProcessOutputBytes,
+  });
+  if (result.timedOut || result.exitCode !== 0) {
+    throw repositoryIndexError(ERROR_CODES.REBUILD_FAILED, `tgrep index failed with exit code ${result.exitCode ?? "unknown"}`, {
+      exitCode: result.exitCode,
+      stderr: result.stderr.slice(0, 4000),
+      stdout: result.stdout.slice(0, 4000),
+    });
+  }
+  const meta = await readJson(path.join(indexPath, "meta.json"));
+  if (!meta?.complete || typeof meta.root_path !== "string" || !sameRepositoryPath(meta.root_path, repositoryRoot, options.platform ?? process.platform)) {
+    throw repositoryIndexError(ERROR_CODES.REBUILD_FAILED, "tgrep index completed without valid repository metadata");
+  }
+  return { result, meta };
+}
+
+function engineOptions(options) {
+  return {
+    packageRoot: options.packageRoot,
+    repoRoot: options.repositoryRoot,
+    platform: options.platform,
+    arch: options.arch,
+    env: options.env,
+    binaryPath: options.binaryPath,
+    assetPath: options.assetPath,
+    homeDirectory: options.homeDirectory,
+    fetchImpl: options.fetchImpl,
+    spawnImpl: options.spawnImpl,
+    execFileImpl: options.execFileImpl,
+  };
+}
+
+async function prepareEngine(repositoryRoot, options) {
+  try {
+    return await ensureManagedTgrep(engineOptions({ ...options, repositoryRoot }));
+  } catch (error) {
+    if (error.code?.startsWith?.("E_REPOSITORY_INDEX_")) throw error;
+    throw wrapRepositoryIndexError(ERROR_CODES.ENGINE_EXECUTION_FAILED, "Unable to prepare managed tgrep", error);
+  }
+}
+
+export async function startRepositoryIndexServer(repositoryRoot, options = {}) {
+  const canonicalRoot = await realpathWithTransientWindowsRetry(repositoryRoot);
+  invalidateRepositoryIndexReadiness(canonicalRoot, options.platform ?? process.platform);
+  await assertIndexPaths(canonicalRoot);
+  const result = await withRepositoryIndexLock(canonicalRoot, "index-start", async () => {
+    const engine = await prepareEngine(canonicalRoot, options);
+    return startUnderLock(canonicalRoot, { ...options, repositoryRoot: canonicalRoot }, engine);
+  }, options);
+  rememberRepositoryIndexReadiness({ canonicalRoot, status: result.status, platform: options.platform });
+  return result;
+}
+
+export async function restartRepositoryIndexServer(repositoryRoot, options = {}) {
+  await stopRepositoryIndexServer(repositoryRoot, options);
+  return startRepositoryIndexServer(repositoryRoot, options);
+}
+
+export async function stopRepositoryIndexServer(repositoryRoot, options = {}) {
+  const canonicalRoot = await realpathWithTransientWindowsRetry(repositoryRoot);
+  invalidateRepositoryIndexReadiness(canonicalRoot, options.platform ?? process.platform);
+  await assertIndexPaths(canonicalRoot);
+  return withRepositoryIndexLock(canonicalRoot, "index-stop", async () => {
+    const indexPath = getTgrepIndexPath(canonicalRoot);
+    return terminateOwnedServer({
+      repositoryRoot: canonicalRoot,
+      indexPath,
+      statePath: getRepositoryIndexStatePath(canonicalRoot),
+      processInspector: options.processInspector,
+      timeoutMs: options.stopTimeoutMs ?? 15_000,
+    });
+  }, options);
+}
+
+export async function rebuildRepositoryIndex(repositoryRoot, options = {}) {
+  const canonicalRoot = await realpathWithTransientWindowsRetry(repositoryRoot);
+  invalidateRepositoryIndexReadiness(canonicalRoot, options.platform ?? process.platform);
+  await assertIndexPaths(canonicalRoot);
+  const result = await withRepositoryIndexLock(canonicalRoot, "index-rebuild", async () => {
+    const engine = await prepareEngine(canonicalRoot, options);
+    const indexPath = getTgrepIndexPath(canonicalRoot);
+    const metadata = await readIndexMetadata(canonicalRoot);
+    if (metadata.serve || metadata.state) {
+      await terminateOwnedServer({
+        repositoryRoot: canonicalRoot,
+        indexPath,
+        statePath: getRepositoryIndexStatePath(canonicalRoot),
+        processInspector: options.processInspector,
+        timeoutMs: options.stopTimeoutMs ?? 15_000,
+      });
+    }
+    await assertSafePath(canonicalRoot, ".forgeloop/repository-index/tgrep");
+    await rm(indexPath, { recursive: true, force: true });
+    await mkdir(indexPath, { recursive: true });
+    const built = await buildUnderLock(canonicalRoot, { ...options, repositoryRoot: canonicalRoot }, engine, { force: true });
+    const statePath = getRepositoryIndexStatePath(canonicalRoot);
+    await writeJson(statePath, {
+      schemaVersion: 1,
+      engine: "tgrep",
+      engineVersion: engine.engineVersion,
+      binaryPath: engine.binaryPath,
+      repositoryRoot: canonicalRoot,
+      indexPath,
+      indexEngineVersion: engine.engineVersion,
+      builtAt: new Date().toISOString(),
+      startedByForgeLoop: false,
+    });
+    const started = await startUnderLock(canonicalRoot, { ...options, repositoryRoot: canonicalRoot }, engine);
+    return { ...started, rebuilt: true, indexed: built.meta };
+  }, options);
+  rememberRepositoryIndexReadiness({ canonicalRoot, status: result.status, platform: options.platform });
+  return result;
+}
+
+export async function setupRepositoryIndex(repositoryRoot, options = {}) {
+  const canonicalRoot = await realpathWithTransientWindowsRetry(repositoryRoot);
+  invalidateRepositoryIndexReadiness(canonicalRoot, options.platform ?? process.platform);
+  await assertIndexPaths(canonicalRoot);
+  const result = await withRepositoryIndexLock(canonicalRoot, "index-setup", async () => {
+    const engine = await prepareEngine(canonicalRoot, options);
+    const indexPath = getTgrepIndexPath(canonicalRoot);
+    const metadata = await readIndexMetadata(canonicalRoot);
+    if (options.force === true || !indexIsUsable({
+      ...metadata,
+      repositoryRoot: canonicalRoot,
+      engineVersion: engine.engineVersion,
+      platform: options.platform ?? process.platform,
+    })) {
+      if (metadata.serve || metadata.state) {
+        await terminateOwnedServer({
+          repositoryRoot: canonicalRoot,
+          indexPath,
+          statePath: getRepositoryIndexStatePath(canonicalRoot),
+          processInspector: options.processInspector,
+          timeoutMs: options.stopTimeoutMs ?? 15_000,
+        });
+      }
+      if (options.force === true) {
+        await assertSafePath(canonicalRoot, ".forgeloop/repository-index/tgrep");
+        await rm(indexPath, { recursive: true, force: true });
+      }
+      await mkdir(indexPath, { recursive: true });
+      const built = await buildUnderLock(canonicalRoot, { ...options, repositoryRoot: canonicalRoot }, engine, { force: true });
+      await writeJson(getRepositoryIndexStatePath(canonicalRoot), {
+        schemaVersion: 1,
+        engine: "tgrep",
+        engineVersion: engine.engineVersion,
+        binaryPath: engine.binaryPath,
+        repositoryRoot: canonicalRoot,
+        indexPath,
+        indexEngineVersion: engine.engineVersion,
+        builtAt: new Date().toISOString(),
+        startedByForgeLoop: false,
+      });
+      const started = await startUnderLock(canonicalRoot, { ...options, repositoryRoot: canonicalRoot }, engine);
+      return { ...started, setup: true, rebuilt: true, indexed: built.meta };
+    }
+    const started = await startUnderLock(canonicalRoot, { ...options, repositoryRoot: canonicalRoot }, engine);
+    return { ...started, setup: true, rebuilt: false, indexed: metadata.meta };
+  }, options);
+  rememberRepositoryIndexReadiness({ canonicalRoot, status: result.status, platform: options.platform });
+  return result;
+}