@cassiomc1/forgeloop 1.10.2 → 1.11.0

package/src/repository-index/manifest.js

@@ -0,0 +1,132 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  REPOSITORY_INDEX_ENGINE,
+  REPOSITORY_INDEX_SUPPORTED_PLATFORMS,
+} from "./constants.js";
+import { REPOSITORY_INDEX_ERROR_CODES, repositoryIndexError } from "./errors.js";
+import { getPackageRoot } from "../core/templates.js";
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const ARCHIVES = new Set(["tar.gz", "zip"]);
+
+function manifestError(source, message, code = REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING) {
+  throw repositoryIndexError(code, `${source} ${message}`);
+}
+
+function assertManifestObject(value, source) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    manifestError(source, "must be a JSON object");
+  }
+  if (value.schemaVersion !== 1) {
+    manifestError(source, "schemaVersion must be 1");
+  }
+}
+
+function assertManifestIdentity(value, source) {
+  if (value.engine !== REPOSITORY_INDEX_ENGINE) {
+    manifestError(source, `engine must be ${REPOSITORY_INDEX_ENGINE}`);
+  }
+  if (typeof value.repository !== "string" || value.repository !== "microsoft/tgrep") {
+    manifestError(source, "repository must be microsoft/tgrep");
+  }
+  if (typeof value.version !== "string" || !SEMVER.test(value.version)) {
+    manifestError(source, "version is invalid");
+  }
+}
+
+function assertManifestRelease(value, source) {
+  if (typeof value.releaseBaseUrl !== "string"
+    || value.releaseBaseUrl !== `https://github.com/microsoft/tgrep/releases/download/v${value.version}`) {
+    manifestError(source, "releaseBaseUrl must be the pinned Microsoft tgrep release URL");
+  }
+}
+
+function assertManifestAsset(asset, platformKey, source) {
+  if (!asset || typeof asset !== "object") manifestError(source, `is missing ${platformKey}`);
+  if (typeof asset.assetName !== "string" || asset.assetName.trim() === "") {
+    manifestError(source, `${platformKey} assetName is required`);
+  }
+  const assetName = asset.assetName.replaceAll("\\", "/");
+  if (path.posix.isAbsolute(assetName) || path.win32.isAbsolute(assetName)
+    || path.posix.basename(assetName) !== assetName || path.posix.normalize(assetName) !== assetName
+    || !/^[A-Za-z0-9._-]+$/u.test(assetName)) {
+    manifestError(source, `${platformKey} assetName must be a single safe filename`);
+  }
+  if (!ARCHIVES.has(asset.archive)) manifestError(source, `${platformKey} archive is unsupported`);
+  if (typeof asset.binaryName !== "string" || asset.binaryName.trim() === "") {
+    manifestError(source, `${platformKey} binaryName is required`);
+  }
+  const expectedBinaryName = platformKey === "windows-x64" ? "tgrep.exe" : "tgrep";
+  if (asset.binaryName !== expectedBinaryName) {
+    manifestError(source, `${platformKey} binaryName must be ${expectedBinaryName}`);
+  }
+  if (!SHA256.test(asset.sha256) || /^0+$/.test(asset.sha256) || /replace|todo|placeholder/i.test(asset.sha256)) {
+    manifestError(source, `${platformKey} checksum is not a verified SHA-256`, REPOSITORY_INDEX_ERROR_CODES.ENGINE_CHECKSUM_MISMATCH);
+  }
+  if (!SHA256.test(asset.binarySha256) || /^0+$/.test(asset.binarySha256) || /replace|todo|placeholder/i.test(asset.binarySha256)) {
+    manifestError(source, `${platformKey} binarySha256 is not a verified SHA-256`, REPOSITORY_INDEX_ERROR_CODES.ENGINE_BINARY_CHECKSUM_MISMATCH);
+  }
+}
+
+function assertManifestAssets(value, source) {
+  if (!value.assets || typeof value.assets !== "object" || Array.isArray(value.assets)) {
+    manifestError(source, "assets are required");
+  }
+  for (const key of REPOSITORY_INDEX_SUPPORTED_PLATFORMS) {
+    assertManifestAsset(value.assets[key], key, source);
+  }
+  const unsupportedKeys = Object.keys(value.assets).filter((key) => !REPOSITORY_INDEX_SUPPORTED_PLATFORMS.includes(key));
+  if (unsupportedKeys.length > 0) {
+    manifestError(source, `contains unsupported platforms: ${unsupportedKeys.join(", ")}`);
+  }
+}
+
+function assertManifest(value, source = "tgrep manifest") {
+  assertManifestObject(value, source);
+  assertManifestIdentity(value, source);
+  assertManifestRelease(value, source);
+  assertManifestAssets(value, source);
+  return Object.freeze({
+    ...value,
+    assets: Object.freeze(Object.fromEntries(Object.entries(value.assets).map(([key, asset]) => [key, Object.freeze({ ...asset })]))),
+  });
+}
+
+export async function loadTgrepManifest(packageRoot = getPackageRoot()) {
+  if (typeof packageRoot !== "string" || packageRoot.trim() === "") {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING, "ForgeLoop package root is required to load the tgrep manifest");
+  }
+  const manifestPath = path.join(packageRoot, "src", "repository-index", "tgrep-manifest.json");
+  let value;
+  try {
+    value = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (cause) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING, `Unable to read ${manifestPath}: ${cause.message}`, { cause, manifestPath });
+  }
+  return assertManifest(value, manifestPath);
+}
+
+export function validateTgrepManifest(value) {
+  return assertManifest(value);
+}
+
+export async function getPinnedTgrepVersion(packageRoot) {
+  return (await loadTgrepManifest(packageRoot)).version;
+}
+
+export async function getTgrepAsset(platformKey, packageRoot) {
+  const manifest = await loadTgrepManifest(packageRoot);
+  const asset = manifest.assets[platformKey];
+  if (!asset) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.PLATFORM_UNSUPPORTED, `No tgrep asset is available for ${platformKey}`);
+  }
+  return Object.freeze({
+    ...asset,
+    url: `${manifest.releaseBaseUrl}/${asset.assetName}`,
+    version: manifest.version,
+    engine: manifest.engine,
+  });
+}

package/src/repository-index/metrics.js

@@ -0,0 +1,30 @@
+/**
+ * Repository-index measurements are operational telemetry only. They never
+ * become protocol evidence, completion proof, or claims about token/cost
+ * savings.
+ */
+export function buildRepositorySearchMetrics({ durationMs, nativeDurationMs, result, engine, engineVersion, serverUsed }) {
+  return {
+    queryDurationMs: durationMs,
+    nativeDurationMs,
+    matchCount: result.matches.length,
+    matchedFileCount: result.files.length,
+    engine,
+    engineVersion,
+    serverUsed,
+    exitCode: result.exitCode,
+    ignoredNativeEvents: result.ignoredEvents,
+    ...(result.stats.bytesSearched !== undefined ? { bytesSearched: result.stats.bytesSearched } : {}),
+    ...(result.stats.matchedLines !== undefined ? { matchedLines: result.stats.matchedLines } : {}),
+  };
+}
+export function buildRepositoryIndexMetrics(status) {
+  return {
+    engine: status.engine,
+    engineVersion: status.engineVersion,
+    indexedFiles: status.index.files,
+    indexedTrigrams: status.index.trigrams,
+    health: status.health,
+    serverUsed: status.server.running,
+  };
+}

package/src/repository-index/normalize-json.js

@@ -0,0 +1,187 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { REPOSITORY_INDEX_ERROR_CODES, repositoryIndexError } from "./errors.js";
+
+function invalid(message, details = {}) {
+  return repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.OUTPUT_INVALID, message, details);
+}
+
+function finiteInteger(value, label, { min = 0, optional = false } = {}) {
+  if (value === undefined || value === null) {
+    if (optional) return null;
+    throw invalid(`tgrep JSON field ${label} is required`);
+  }
+  if (!Number.isSafeInteger(value) || value < min) throw invalid(`tgrep JSON field ${label} is invalid`);
+  return value;
+}
+
+function extractData(event) {
+  return event && typeof event === "object" && event.data && typeof event.data === "object"
+    ? event.data
+    : event;
+}
+
+function usesWindowsPath(value, repositoryRoot, pathStyle) {
+  return pathStyle === "win32"
+    || /^[A-Za-z]:[\\/]/u.test(value)
+    || /^\\\\/u.test(value)
+    || /^[A-Za-z]:[\\/]/u.test(repositoryRoot)
+    || /^\\\\/u.test(repositoryRoot);
+}
+
+async function normalizePath(value, repositoryRoot, { pathStyle = null } = {}) {
+  if (typeof value !== "string" || value.length === 0) throw invalid("tgrep JSON match path is missing");
+  const windows = usesWindowsPath(value, repositoryRoot, pathStyle);
+  const pathApi = windows ? path.win32 : path;
+  const normalizedRoot = pathApi.normalize(repositoryRoot);
+  const normalizedValue = value.replaceAll("/", pathApi.sep);
+  const candidate = pathApi.isAbsolute(normalizedValue)
+    ? pathApi.normalize(normalizedValue)
+    : pathApi.resolve(normalizedRoot, normalizedValue);
+  const comparisonRoot = windows ? normalizedRoot.toLowerCase() : normalizedRoot;
+  const comparisonCandidate = windows ? candidate.toLowerCase() : candidate;
+  const relative = pathApi.relative(comparisonRoot, comparisonCandidate);
+  if (relative === ".." || relative.startsWith(`..${pathApi.sep}`) || pathApi.isAbsolute(relative)) {
+    throw invalid(`tgrep JSON path escapes the repository root: ${value}`);
+  }
+  return relative ? relative.split(pathApi.sep).join("/") : ".";
+}
+
+function pathText(data) {
+  if (typeof data.path === "string") return data.path;
+  if (data.path && typeof data.path.text === "string") return data.path.text;
+  return null;
+}
+
+function lineText(data) {
+  if (typeof data.text === "string") return data.text;
+  if (data.lines && typeof data.lines.text === "string") return data.lines.text;
+  return "";
+}
+
+function normalizeSubmatches(data) {
+  if (data.submatches === undefined) return [];
+  if (!Array.isArray(data.submatches)) throw invalid("tgrep JSON submatches must be an array");
+  return data.submatches.map((submatch, index) => {
+    if (!submatch || typeof submatch !== "object") throw invalid(`tgrep JSON submatch ${index} is invalid`);
+    const start = finiteInteger(submatch.start, `submatches[${index}].start`);
+    const end = finiteInteger(submatch.end, `submatches[${index}].end`);
+    if (end < start) throw invalid(`tgrep JSON submatch ${index} has a reversed range`);
+    const match = typeof submatch.match === "string" ? submatch.match : submatch.match?.text;
+    return { start, end, match: typeof match === "string" ? match : null };
+  });
+}
+
+async function normalizeMatch(event, repositoryRoot, options) {
+  const data = extractData(event);
+  const relativePath = await normalizePath(pathText(data), repositoryRoot, options);
+  const lineNumber = finiteInteger(data.line_number ?? data.lineNumber, "line_number", { min: 1 });
+  const absoluteOffset = finiteInteger(data.absolute_offset ?? data.absoluteOffset, "absolute_offset", { optional: true });
+  return {
+    path: relativePath,
+    line: lineNumber,
+    column: finiteInteger(data.column, "column", { min: 1, optional: true }),
+    offset: absoluteOffset,
+    text: lineText(data),
+    submatches: normalizeSubmatches(data),
+  };
+}
+
+function addStats(target, data) {
+  const stats = data?.stats && typeof data.stats === "object" ? data.stats : data;
+  if (!stats || typeof stats !== "object") return;
+  const values = {
+    bytesSearched: stats.bytes_searched,
+    bytesPrinted: stats.bytes_printed,
+    matchedLines: stats.matched_lines,
+    matches: stats.matches,
+    searches: stats.searches,
+    searchesWithMatch: stats.searches_with_match,
+    elapsedNanos: stats.elapsed?.nanos,
+  };
+  for (const [key, value] of Object.entries(values)) {
+    if (Number.isSafeInteger(value) && value >= 0) target[key] = value;
+  }
+}
+
+function looksLikeStatsLine(line) {
+  return /^(?:Query plan:|Search completed in |Walking |Found \d+ text files|Extracting trigrams|Writing index|Index built successfully|Indexed in )/i.test(line.trim());
+}
+
+async function parseFileLines(lines, repositoryRoot, options) {
+  const files = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    if (looksLikeStatsLine(line)) continue;
+    let value;
+    try { value = JSON.parse(line); } catch {
+      files.push(await normalizePath(line.trim(), repositoryRoot, options));
+      continue;
+    }
+    const text = pathText(extractData(value));
+    if (value.type === "match" || value.type === "context") {
+      files.push(await normalizePath(text, repositoryRoot, options));
+    } else if (text) {
+      files.push(await normalizePath(text, repositoryRoot));
+    }
+  }
+  return [...new Set(files)].sort();
+}
+
+/**
+ * Converts tgrep's versioned JSON-lines stream into ForgeLoop's stable,
+ * provider-neutral repository-search result. Native output is never treated
+ * as evidence or lifecycle state; malformed lines fail closed.
+ */
+export async function normalizeTgrepJson(stdout, {
+  repositoryRoot,
+  filesWithMatches = false,
+  realpathImpl = realpath,
+  pathStyle = null,
+} = {}) {
+  if (typeof stdout !== "string" || typeof repositoryRoot !== "string") throw invalid("tgrep JSON output requires text and repositoryRoot");
+  const canonicalRoot = await realpathImpl(repositoryRoot);
+  const pathOptions = { pathStyle };
+  const lines = stdout.split(/\r?\n/).filter((line) => line.trim());
+  if (filesWithMatches) {
+    return {
+      matches: [],
+      contexts: [],
+      files: await parseFileLines(lines, canonicalRoot, pathOptions),
+      stats: {},
+      events: { begin: 0, match: 0, context: 0, end: 0, summary: 0 },
+      ignoredEvents: 0,
+    };
+  }
+
+  const matches = [];
+  const contexts = [];
+  const stats = {};
+  const files = new Set();
+  const events = { begin: 0, match: 0, context: 0, end: 0, summary: 0 };
+  let ignoredEvents = 0;
+  for (const line of lines) {
+    let event;
+    try { event = JSON.parse(line); } catch {
+      if (looksLikeStatsLine(line)) continue;
+      throw invalid("tgrep emitted a non-JSON line in JSON search mode", { line: line.slice(0, 500) });
+    }
+    if (!event || typeof event !== "object" || typeof event.type !== "string") {
+      throw invalid("tgrep emitted a JSON value without an event type");
+    }
+    if (!Object.hasOwn(events, event.type)) {
+      ignoredEvents += 1;
+      continue;
+    }
+    events[event.type] += 1;
+    if (event.type === "match" || event.type === "context") {
+      const normalized = await normalizeMatch(event, canonicalRoot, pathOptions);
+      files.add(normalized.path);
+      (event.type === "match" ? matches : contexts).push(normalized);
+    } else if (event.type === "end" || event.type === "summary") {
+      addStats(stats, extractData(event));
+    }
+  }
+  return { matches, contexts, files: [...files].sort(), stats, events, ignoredEvents };
+}

package/src/repository-index/paths.js

@@ -0,0 +1,39 @@
+import os from "node:os";
+import path from "node:path";
+
+import { REPOSITORY_INDEX_RELATIVE_PATH, REPOSITORY_INDEX_STATE_FILE } from "./constants.js";
+
+export function getEngineHome({ homeDirectory = os.homedir() } = {}) {
+  return path.join(homeDirectory, ".forgeloop", "engines", "tgrep");
+}
+export function getTgrepVersionDirectory(version, options = {}) {
+  return path.join(getEngineHome(options), version);
+}
+
+export function getManagedTgrepDirectory(version, platformKey, options = {}) {
+  return path.join(getTgrepVersionDirectory(version, options), platformKey);
+}
+
+export function getManagedTgrepBinaryPath(version, platformKey, { windows = platformKey.startsWith("windows-") || process.platform === "win32", ...options } = {}) {
+  return path.join(getManagedTgrepDirectory(version, platformKey, options), windows ? "tgrep.exe" : "tgrep");
+}
+
+export function getRepositoryIndexRoot(repoRoot) {
+  return path.join(repoRoot, REPOSITORY_INDEX_RELATIVE_PATH);
+}
+
+export function getTgrepIndexPath(repoRoot) {
+  return path.join(getRepositoryIndexRoot(repoRoot), "tgrep");
+}
+
+export function getRepositoryIndexStatePath(repoRoot) {
+  return path.join(getRepositoryIndexRoot(repoRoot), REPOSITORY_INDEX_STATE_FILE);
+}
+
+export function getRepositoryIndexMetricsPath(repoRoot) {
+  return path.join(getRepositoryIndexRoot(repoRoot), "metrics");
+}
+
+export function getRepositoryIndexLockPath(repoRoot) {
+  return path.join(getRepositoryIndexRoot(repoRoot), "operation.lock");
+}

package/src/repository-index/platform.js

@@ -0,0 +1,20 @@
+import { REPOSITORY_INDEX_ERROR_CODES, repositoryIndexError } from "./errors.js";
+
+const SUPPORTED = new Map([
+  ["darwin:arm64", "darwin-arm64"],
+  ["darwin:x64", "darwin-x64"],
+  ["linux:x64", "linux-x64"],
+  ["win32:x64", "windows-x64"],
+]);
+
+export function getRepositoryIndexPlatform({ platform = process.platform, arch = process.arch } = {}) {
+  const key = SUPPORTED.get(`${platform}:${arch}`);
+  if (!key) {
+    throw repositoryIndexError(
+      REPOSITORY_INDEX_ERROR_CODES.PLATFORM_UNSUPPORTED,
+      `Repository Index does not support platform ${platform}/${arch}`,
+      { platform, arch },
+    );
+  }
+  return Object.freeze({ platform, arch, key });
+}

package/src/repository-index/process.js

@@ -0,0 +1,140 @@
+import { spawn } from "node:child_process";
+import { clearInterval, setInterval } from "node:timers";
+import path from "node:path";
+
+import { REPOSITORY_INDEX_DEFAULTS } from "./constants.js";
+import { REPOSITORY_INDEX_ERROR_CODES, repositoryIndexError } from "./errors.js";
+
+const MAX_COMMAND_TIMEOUT_MS = 120_000;
+const PROCESS_TIMER_INTERVAL_MS = 50;
+const trustedBinaryPaths = new WeakMap();
+
+function assertArgs(args) {
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || arg.length === 0)) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED, "tgrep arguments must be a non-empty string array");
+  }
+}
+
+function assertExecutablePath(binaryPath) {
+  if (typeof binaryPath !== "string" || binaryPath.trim() === "") {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED, "A verified managed tgrep binary path is required");
+  }
+  if (!path.isAbsolute(binaryPath) || !binaryPath.match(/^[\w./\\: @%+=~-]+$/u)) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED, "The managed tgrep binary path contains unsafe command characters");
+  }
+  return binaryPath;
+}
+
+export function createTgrepBinaryHandle(binaryPath) {
+  const handle = Object.freeze({});
+  trustedBinaryPaths.set(handle, assertExecutablePath(binaryPath));
+  return handle;
+}
+
+function resolveTgrepBinaryHandle(handle) {
+  const binaryPath = trustedBinaryPaths.get(handle);
+  if (!binaryPath) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED, "A validated managed tgrep binary handle is required");
+  }
+  return binaryPath;
+}
+
+export async function runTgrep({ binary, repoRoot, args, stdin = null, timeoutMs = REPOSITORY_INDEX_DEFAULTS.commandTimeoutMs, env = {}, spawnImpl = spawn, maxOutputBytes = REPOSITORY_INDEX_DEFAULTS.maxProcessOutputBytes } = {}) {
+  const binaryPath = resolveTgrepBinaryHandle(binary);
+  if (typeof repoRoot !== "string" || repoRoot.trim() === "") {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED, "A repository root is required to execute tgrep");
+  }
+  assertArgs(args);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED, "tgrep timeoutMs must be a positive integer");
+  }
+  const effectiveTimeoutMs = Math.min(timeoutMs, MAX_COMMAND_TIMEOUT_MS);
+
+  const startedAt = Date.now();
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawnImpl(binaryPath, args, {
+        cwd: repoRoot,
+        env: { ...process.env, ...env },
+        shell: false,
+        windowsHide: true,
+      });
+    } catch (cause) {
+      reject(repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED, `Unable to launch managed tgrep: ${cause.message}`, { cause }));
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    const timeoutDeadline = startedAt + effectiveTimeoutMs;
+    const timer = setInterval(() => {
+      if (Date.now() < timeoutDeadline) return;
+      timedOut = true;
+      clearInterval(timer);
+      try { child.kill("SIGTERM"); } catch { /* process may already be gone */ }
+    }, PROCESS_TIMER_INTERVAL_MS);
+    timer.unref?.();
+
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearInterval(timer);
+      fn(value);
+    };
+    const append = (current, chunk) => {
+      const next = `${current}${chunk.toString("utf8")}`;
+      if (Buffer.byteLength(next, "utf8") > maxOutputBytes) {
+        try { child.kill("SIGTERM"); } catch { /* process may already be gone */ }
+        finish(reject, repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_OUTPUT_LIMIT, `tgrep output exceeded ${maxOutputBytes} bytes`));
+        return current;
+      }
+      return next;
+    };
+    child.stdout?.on("data", (chunk) => { stdout = append(stdout, chunk); });
+    child.stderr?.on("data", (chunk) => { stderr = append(stderr, chunk); });
+    child.once("error", (cause) => finish(reject, repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED, `Managed tgrep failed to start: ${cause.message}`, { cause })));
+    child.once("close", (exitCode, signal) => {
+      if (settled) return;
+      const result = {
+        exitCode: Number.isInteger(exitCode) ? exitCode : null,
+        signal: signal ?? null,
+        stdout,
+        stderr,
+        durationMs: Date.now() - startedAt,
+        timedOut,
+      };
+      finish(resolve, result);
+    });
+    if (stdin !== null && stdin !== undefined) {
+      child.stdin?.end(stdin);
+    } else {
+      child.stdin?.end();
+    }
+  });
+}
+
+export function spawnTgrepServer({ binary, repoRoot, args, env = {}, spawnImpl = spawn, stdio = "ignore" } = {}) {
+  const binaryPath = resolveTgrepBinaryHandle(binary);
+  if (typeof repoRoot !== "string" || !repoRoot) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.SERVER_START_FAILED, "A verified managed tgrep binary and repository root are required");
+  }
+  assertArgs(args);
+  let child;
+  try {
+    child = spawnImpl(binaryPath, args, {
+      cwd: repoRoot,
+      env: { ...process.env, ...env },
+      shell: false,
+      detached: true,
+      stdio,
+      windowsHide: true,
+    });
+  } catch (cause) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.SERVER_START_FAILED, `Unable to launch managed tgrep server: ${cause.message}`, { cause });
+  }
+  child.unref?.();
+  return child;
+}

package/src/repository-index/readiness.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+
+import { processIsAlive } from "./status.js";
+
+const readinessByRepository = new Map();
+
+function normalize(value, platform = process.platform) {
+  if (typeof value !== "string" || value.length === 0) return value;
+  const pathApi = platform === "win32" ? path.win32 : path;
+  const normalized = pathApi.normalize(value);
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+export function rememberRepositoryIndexReadiness({ canonicalRoot, status, platform } = {}) {
+  if (typeof canonicalRoot !== "string" || !status?.indexPath || !status?.binaryPath || status.server?.running !== true) return null;
+  const selectedPlatform = platform ?? status.platform?.platform ?? process.platform;
+  const readiness = Object.freeze({
+    canonicalRoot,
+    indexPath: status.indexPath,
+    binaryPath: status.binaryPath,
+    engineVersion: status.engineVersion ?? null,
+    serverRunning: true,
+    pid: Number.isInteger(status.server?.pid) ? status.server.pid : null,
+    platform: selectedPlatform,
+    status,
+    lastSuccessfulSearchAt: null,
+  });
+  readinessByRepository.set(normalize(canonicalRoot, selectedPlatform), readiness);
+  return readiness;
+}
+
+export function getRepositoryIndexReadiness(canonicalRoot, platform = process.platform) {
+  return readinessByRepository.get(normalize(canonicalRoot, platform)) ?? null;
+}
+
+export function invalidateRepositoryIndexReadiness(canonicalRoot, platform = process.platform) {
+  if (typeof canonicalRoot !== "string") return;
+  readinessByRepository.delete(normalize(canonicalRoot, platform));
+}
+
+export function clearRepositoryIndexReadiness() {
+  readinessByRepository.clear();
+}
+
+export function markRepositoryIndexSearchSucceeded(canonicalRoot, platform = process.platform) {
+  const current = getRepositoryIndexReadiness(canonicalRoot, platform);
+  if (!current) return null;
+  const next = Object.freeze({ ...current, lastSuccessfulSearchAt: new Date().toISOString() });
+  readinessByRepository.set(normalize(canonicalRoot, platform), next);
+  return next;
+}
+
+export function isRepositoryIndexReadinessUsable(readiness, expected = {}, { isAlive = processIsAlive } = {}) {
+  if (!readiness || readiness.serverRunning !== true || typeof readiness.canonicalRoot !== "string") return false;
+  const platform = expected.platform ?? readiness.platform ?? process.platform;
+  if (expected.canonicalRoot && normalize(readiness.canonicalRoot, platform) !== normalize(expected.canonicalRoot, platform)) return false;
+  if (expected.indexPath && normalize(readiness.indexPath, platform) !== normalize(expected.indexPath, platform)) return false;
+  if (expected.binaryPath && normalize(readiness.binaryPath, platform) !== normalize(expected.binaryPath, platform)) return false;
+  if (expected.engineVersion && readiness.engineVersion !== expected.engineVersion) return false;
+  if (!Number.isInteger(readiness.pid) || !isAlive(readiness.pid)) return false;
+  return true;
+}