@cassiomc1/forgeloop 1.10.2 → 1.11.0

package/src/repository-index/binary-manager.js

@@ -0,0 +1,413 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile as nodeExecFile } from "node:child_process";
+import { createReadStream } from "node:fs";
+import {
+  access,
+  chmod,
+  constants as fsConstants,
+  copyFile,
+  mkdir,
+  mkdtemp,
+  readdir,
+  lstat,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { REPOSITORY_INDEX_DEFAULTS, REPOSITORY_INDEX_ENV_BINARY } from "./constants.js";
+import { REPOSITORY_INDEX_ERROR_CODES, repositoryIndexError } from "./errors.js";
+import { getRepositoryIndexPlatform } from "./platform.js";
+import { getManagedTgrepBinaryPath, getManagedTgrepDirectory, getEngineHome } from "./paths.js";
+import { getTgrepAsset, loadTgrepManifest } from "./manifest.js";
+import { createTgrepBinaryHandle, runTgrep } from "./process.js";
+import { acquireRepositoryIndexLock } from "./lock.js";
+
+const VERSION_PATTERN = /\btgrep\s+(?:v)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/i;
+const ALLOWED_DOWNLOAD_HOSTS = new Set([
+  "github.com",
+  "objects.githubusercontent.com",
+  "release-assets.githubusercontent.com",
+]);
+
+function assertTrustedDownloadUrl(value) {
+  let parsed;
+  try { parsed = new URL(value); } catch (cause) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, "Pinned tgrep asset URL is invalid", { cause, url: value });
+  }
+  if (parsed.protocol !== "https:" || !ALLOWED_DOWNLOAD_HOSTS.has(parsed.hostname)) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, `Pinned tgrep asset URL is not trusted: ${parsed.hostname}`, { url: value });
+  }
+  return parsed;
+}
+
+function absolutePath(value, label) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING, `${label} must be an absolute path`);
+  }
+  return path.normalize(value);
+}
+
+async function ensureRegularFile(filePath, code, label) {
+  let info;
+  try {
+    info = await lstat(filePath);
+  } catch (cause) {
+    if (cause.code === "ENOENT") throw repositoryIndexError(code, `${label} is missing: ${filePath}`, { cause, path: filePath });
+    throw repositoryIndexError(code, `${label} cannot be inspected: ${filePath}: ${cause.message}`, { cause, path: filePath });
+  }
+  if (info.isSymbolicLink() || !info.isFile()) {
+    throw repositoryIndexError(code, `${label} must be a regular file: ${filePath}`, { path: filePath });
+  }
+  return info;
+}
+
+async function verifyExecutable(filePath, { platform = process.platform } = {}) {
+  await ensureRegularFile(filePath, REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING, "Managed tgrep binary");
+  if (platform !== "win32") {
+    try {
+      await access(filePath, fsConstants.X_OK);
+    } catch (cause) {
+      throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING, `Managed tgrep binary is not executable: ${filePath}`, { cause, path: filePath });
+    }
+  }
+}
+
+function parseVersion(output) {
+  return output.match(VERSION_PATTERN)?.[1] ?? null;
+}
+
+export async function verifyTgrepVersion({ binaryPath, expectedVersion, repoRoot = process.cwd(), spawnImpl, timeoutMs = 15_000 } = {}) {
+  const result = await runTgrep({
+    binary: createTgrepBinaryHandle(binaryPath),
+    repoRoot,
+    args: ["--version"],
+    spawnImpl,
+    timeoutMs,
+    maxOutputBytes: 64 * 1024,
+  });
+  if (result.timedOut || result.exitCode !== 0) {
+    throw repositoryIndexError(
+      REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED,
+      `Unable to verify tgrep version at ${binaryPath}`,
+      { result: { exitCode: result.exitCode, stderr: result.stderr.slice(0, 2000), timedOut: result.timedOut } },
+    );
+  }
+  const actualVersion = parseVersion(`${result.stdout}\n${result.stderr}`);
+  if (actualVersion !== expectedVersion) {
+    throw repositoryIndexError(
+      REPOSITORY_INDEX_ERROR_CODES.ENGINE_VERSION_MISMATCH,
+      `Managed tgrep version is ${actualVersion ?? "unknown"}; expected ${expectedVersion}`,
+      { actualVersion, expectedVersion, binaryPath },
+    );
+  }
+  return actualVersion;
+}
+
+export async function verifyManagedTgrep({ packageRoot, repoRoot = process.cwd(), platform, arch, env = process.env, binaryPath: explicitBinaryPath, homeDirectory = os.homedir(), spawnImpl } = {}) {
+  const manifest = await loadTgrepManifest(packageRoot);
+  const selectedPlatform = platform && arch
+    ? getRepositoryIndexPlatform({ platform, arch })
+    : getRepositoryIndexPlatform();
+  const override = explicitBinaryPath ?? env?.[REPOSITORY_INDEX_ENV_BINARY];
+  if (override) {
+    const overridePath = absolutePath(override, REPOSITORY_INDEX_ENV_BINARY);
+    await ensureRegularFile(overridePath, REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING, "Explicit tgrep override");
+    if (selectedPlatform.platform !== "win32") {
+      try { await access(overridePath, fsConstants.X_OK); } catch (cause) {
+        throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING, `Explicit tgrep override is not executable: ${overridePath}`, { cause, path: overridePath });
+      }
+    }
+    const version = await verifyTgrepVersion({ binaryPath: overridePath, expectedVersion: manifest.version, repoRoot, spawnImpl });
+    return Object.freeze({
+      engine: manifest.engine,
+      engineVersion: version,
+      platform: selectedPlatform,
+      binaryPath: overridePath,
+      managed: false,
+      overridden: true,
+      canonical: false,
+      asset: null,
+    });
+  }
+
+  const binaryPath = getManagedTgrepBinaryPath(manifest.version, selectedPlatform.key, {
+    homeDirectory,
+    windows: selectedPlatform.platform === "win32",
+  });
+  const asset = manifest.assets[selectedPlatform.key];
+  await verifyExecutable(binaryPath, { platform: selectedPlatform.platform });
+  await verifyBinaryChecksum(binaryPath, asset.binarySha256);
+  const version = await verifyTgrepVersion({ binaryPath, expectedVersion: manifest.version, repoRoot, spawnImpl });
+  return Object.freeze({
+    engine: manifest.engine,
+    engineVersion: version,
+    platform: selectedPlatform,
+    binaryPath,
+    managed: true,
+    overridden: false,
+    canonical: true,
+    asset,
+  });
+}
+
+function execFileAsync(execFileImpl, file, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    execFileImpl(file, args, { shell: false, ...options }, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+export function validateArchiveEntry(entry) {
+  const portable = entry.replaceAll("\\", "/").replace(/^\.\//, "") || ".";
+  if (portable.includes("\0") || path.posix.isAbsolute(portable) || path.win32.isAbsolute(portable)) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, `Archive contains an absolute path: ${entry}`);
+  }
+  const normalized = path.posix.normalize(portable);
+  if (normalized === ".." || normalized.startsWith("../")) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, `Archive path escapes extraction directory: ${entry}`);
+  }
+  return normalized;
+}
+
+async function listArchiveEntries(archivePath, { archive = "tar.gz", execFileImpl = nodeExecFile } = {}) {
+  const listCommand = archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const listArgs = listCommand === "unzip" ? ["-Z1", archivePath] : ["-tf", archivePath];
+  try {
+    const listed = await execFileAsync(execFileImpl, listCommand, listArgs, { maxBuffer: 2 * 1024 * 1024 });
+    return listed.stdout.split(/\r?\n/).filter(Boolean).map(validateArchiveEntry);
+  } catch (cause) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, `Unable to inspect tgrep archive: ${cause.message}`, { cause });
+  }
+}
+
+async function extractArchive(archivePath, extractionDirectory, { archive = "tar.gz", execFileImpl = nodeExecFile } = {}) {
+  await listArchiveEntries(archivePath, { archive, execFileImpl });
+  const extractCommand = archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const extractArgs = extractCommand === "unzip"
+    ? ["-q", archivePath, "-d", extractionDirectory]
+    : ["-xf", archivePath, "-C", extractionDirectory];
+  try {
+    await execFileAsync(execFileImpl, extractCommand, extractArgs, { maxBuffer: 2 * 1024 * 1024 });
+  } catch (cause) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, `Unable to extract tgrep archive: ${cause.message}`, { cause });
+  }
+}
+
+async function findBinary(root, binaryName) {
+  const found = [];
+  async function visit(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) {
+        throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, `Archive contains a symbolic link: ${entry.name}`);
+      }
+      if (entry.isDirectory()) {
+        await visit(entryPath);
+      } else if (entry.isFile() && entry.name === binaryName) {
+        found.push(entryPath);
+      }
+    }
+  }
+  await visit(root);
+  if (found.length !== 1) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, `Expected exactly one ${binaryName} in tgrep archive; found ${found.length}`);
+  }
+  return found[0];
+}
+
+export async function verifyArchiveChecksum(archivePath, expectedSha256) {
+  const actual = await sha256File(archivePath);
+  if (actual !== expectedSha256) {
+    throw repositoryIndexError(
+      REPOSITORY_INDEX_ERROR_CODES.ENGINE_CHECKSUM_MISMATCH,
+      `tgrep archive checksum mismatch: expected ${expectedSha256}, got ${actual}`,
+      { expectedSha256, actualSha256: actual, archivePath },
+    );
+  }
+  return actual;
+}
+
+export async function sha256File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", () => resolve(hash.digest("hex")));
+  });
+}
+
+export async function verifyBinaryChecksum(binaryPath, expectedSha256) {
+  const actual = await sha256File(binaryPath);
+  if (actual !== expectedSha256) {
+    throw repositoryIndexError(
+      REPOSITORY_INDEX_ERROR_CODES.ENGINE_BINARY_CHECKSUM_MISMATCH,
+      `tgrep binary checksum mismatch: expected ${expectedSha256}, got ${actual}`,
+      { expectedSha256, actualSha256: actual, binaryPath },
+    );
+  }
+  return actual;
+}
+
+async function downloadResponse(url, { fetchImpl = fetch, maxBytes = REPOSITORY_INDEX_DEFAULTS.maxAssetBytes } = {}) {
+  assertTrustedDownloadUrl(url);
+  let response;
+  try {
+    response = await fetchImpl(url, { redirect: "follow" });
+  } catch (cause) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, `Unable to download pinned tgrep asset: ${cause.message}`, { cause, url });
+  }
+  if (!response?.ok) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, `Pinned tgrep asset download returned HTTP ${response?.status ?? "unknown"}`, { url, status: response?.status ?? null });
+  }
+  if (response.url) {
+    assertTrustedDownloadUrl(response.url);
+  }
+  let bytes;
+  try {
+    bytes = Buffer.from(await response.arrayBuffer());
+  } catch (cause) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, `Unable to read pinned tgrep asset: ${cause.message}`, { cause, url });
+  }
+  if (bytes.byteLength > maxBytes) {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, `Pinned tgrep asset exceeds ${maxBytes} bytes`, { url, maxBytes });
+  }
+  return bytes;
+}
+
+export async function downloadTgrepAsset({ asset, destinationDirectory, assetPath, fetchImpl, maxBytes = REPOSITORY_INDEX_DEFAULTS.maxAssetBytes } = {}) {
+  if (!asset || typeof asset.assetName !== "string") {
+    throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, "A pinned tgrep asset descriptor is required");
+  }
+  await mkdir(destinationDirectory, { recursive: true });
+  const destination = path.join(destinationDirectory, asset.assetName);
+  let bytes;
+  if (assetPath) {
+    const source = absolutePath(assetPath, "--asset");
+    try {
+      await ensureRegularFile(source, REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, "Preloaded tgrep asset");
+      const info = await stat(source);
+      if (info.size > maxBytes) throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, `Preloaded tgrep asset exceeds ${maxBytes} bytes`, { source, maxBytes });
+      bytes = await readFile(source);
+    } catch (cause) {
+      if (cause.code?.startsWith?.("E_REPOSITORY_INDEX")) throw cause;
+      throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.ENGINE_DOWNLOAD_FAILED, `Unable to read preloaded tgrep asset: ${cause.message}`, { cause, source });
+    }
+  } else {
+    bytes = await downloadResponse(asset.url, { fetchImpl, maxBytes });
+  }
+  await writeFile(destination, bytes, { flag: "w" });
+  await verifyArchiveChecksum(destination, asset.sha256);
+  return destination;
+}
+
+function binaryDescriptor({ manifest, selectedPlatform, binaryPath, managed, overridden, asset }) {
+  return Object.freeze({
+    engine: manifest.engine,
+    engineVersion: manifest.version,
+    platform: selectedPlatform,
+    binaryPath,
+    managed,
+    overridden,
+    canonical: managed && !overridden,
+    asset: asset ?? null,
+  });
+}
+
+export async function ensureManagedTgrep({ packageRoot, repoRoot = process.cwd(), platform, arch, env = process.env, binaryPath: explicitBinaryPath, assetPath, homeDirectory = os.homedir(), fetchImpl, spawnImpl, execFileImpl } = {}) {
+  const manifest = await loadTgrepManifest(packageRoot);
+  const selectedPlatform = platform && arch
+    ? getRepositoryIndexPlatform({ platform, arch })
+    : getRepositoryIndexPlatform();
+  const override = explicitBinaryPath ?? env?.[REPOSITORY_INDEX_ENV_BINARY];
+  if (override) {
+    const verified = await verifyManagedTgrep({ packageRoot, repoRoot, platform: selectedPlatform.platform, arch: selectedPlatform.arch, env: { ...env, [REPOSITORY_INDEX_ENV_BINARY]: override }, binaryPath: override, spawnImpl });
+    return verified;
+  }
+
+  const binaryPath = getManagedTgrepBinaryPath(manifest.version, selectedPlatform.key, {
+    homeDirectory,
+    windows: selectedPlatform.platform === "win32",
+  });
+  const finalDirectory = getManagedTgrepDirectory(manifest.version, selectedPlatform.key, { homeDirectory });
+  const provisionLockPath = path.join(getEngineHome({ homeDirectory }), ".provision.lock");
+  const lease = await acquireRepositoryIndexLock(provisionLockPath, "tgrep-provision", { timeoutMs: 120_000 });
+  try {
+    let repairRequired = false;
+    try {
+      await verifyExecutable(binaryPath, { platform: selectedPlatform.platform });
+      await verifyBinaryChecksum(binaryPath, manifest.assets[selectedPlatform.key].binarySha256);
+      await verifyTgrepVersion({ binaryPath, expectedVersion: manifest.version, repoRoot, spawnImpl });
+      return binaryDescriptor({ manifest, selectedPlatform, binaryPath, managed: true, overridden: false, asset: manifest.assets[selectedPlatform.key] });
+    } catch (cause) {
+      if (cause.code !== REPOSITORY_INDEX_ERROR_CODES.ENGINE_MISSING
+        && cause.code !== REPOSITORY_INDEX_ERROR_CODES.ENGINE_VERSION_MISMATCH
+        && cause.code !== REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXECUTION_FAILED
+        && cause.code !== REPOSITORY_INDEX_ERROR_CODES.ENGINE_BINARY_CHECKSUM_MISMATCH) throw cause;
+      repairRequired = true;
+    }
+
+    const asset = await getTgrepAsset(selectedPlatform.key, packageRoot);
+    const temporaryRoot = await mkdtemp(path.join(getEngineHome({ homeDirectory }), "tmp-"));
+    try {
+      const archivePath = await downloadTgrepAsset({
+        asset,
+        destinationDirectory: temporaryRoot,
+        assetPath,
+        fetchImpl,
+      });
+      await verifyArchiveChecksum(archivePath, asset.sha256);
+      const extractionDirectory = path.join(temporaryRoot, "extract");
+      await mkdir(extractionDirectory);
+      await extractArchive(archivePath, extractionDirectory, { archive: asset.archive, execFileImpl });
+      const extractedBinary = await findBinary(extractionDirectory, asset.binaryName);
+      await ensureRegularFile(extractedBinary, REPOSITORY_INDEX_ERROR_CODES.ENGINE_EXTRACTION_FAILED, "Extracted tgrep binary");
+      await verifyBinaryChecksum(extractedBinary, asset.binarySha256);
+      const stagedBinary = path.join(temporaryRoot, asset.binaryName);
+      await copyFile(extractedBinary, stagedBinary);
+      if (selectedPlatform.platform !== "win32") await chmod(stagedBinary, 0o755);
+      await mkdir(finalDirectory, { recursive: true });
+      const quarantinePath = `${binaryPath}.invalid-${randomUUID()}`;
+      let quarantined = false;
+      let installed = false;
+      try {
+        if (repairRequired) {
+          try {
+            await rename(binaryPath, quarantinePath);
+            quarantined = true;
+          } catch (cause) {
+            if (cause.code !== "ENOENT") throw cause;
+          }
+        }
+        await rename(stagedBinary, binaryPath);
+        installed = true;
+        if (selectedPlatform.platform !== "win32") await chmod(binaryPath, 0o755);
+        await verifyExecutable(binaryPath, { platform: selectedPlatform.platform });
+        await verifyBinaryChecksum(binaryPath, asset.binarySha256);
+        await verifyTgrepVersion({ binaryPath, expectedVersion: manifest.version, repoRoot, spawnImpl });
+      } catch (cause) {
+        if (installed) await rm(binaryPath, { force: true }).catch(() => {});
+        if (quarantined) await rename(quarantinePath, binaryPath).catch(() => {});
+        throw cause;
+      }
+      if (quarantined) await rm(quarantinePath, { force: true });
+      return binaryDescriptor({ manifest, selectedPlatform, binaryPath, managed: true, overridden: false, asset });
+    } finally {
+      await rm(temporaryRoot, { recursive: true, force: true });
+    }
+  } finally {
+    await lease.release();
+  }
+}

package/src/repository-index/constants.js

@@ -0,0 +1,45 @@
+export const REPOSITORY_INDEX_SCHEMA_VERSION = 1;
+export const REPOSITORY_INDEX_ENGINE = "tgrep";
+export const REPOSITORY_INDEX_REQUIRED = true;
+export const REPOSITORY_INDEX_RELATIVE_PATH = ".forgeloop/repository-index";
+export const REPOSITORY_INDEX_STATE_FILE = "engine-state.json";
+export const REPOSITORY_INDEX_METRICS_DIRECTORY = "metrics";
+
+export const REPOSITORY_INDEX_DEFAULTS = Object.freeze({
+  maxFileSize: "64M",
+  maxCpuPercent: 50,
+  watcherQueueCap: 16_384,
+  autoSaveMutations: 5_000,
+  startupTimeoutMs: 60_000,
+  commandTimeoutMs: 120_000,
+  maxProcessOutputBytes: 8 * 1024 * 1024,
+  maxAssetBytes: 100 * 1024 * 1024,
+});
+
+export const REPOSITORY_INDEX_SUPPORTED_PLATFORMS = Object.freeze([
+  "darwin-arm64",
+  "darwin-x64",
+  "linux-x64",
+  "windows-x64",
+]);
+
+export const REPOSITORY_INDEX_SEARCH_EVENT_TYPES = Object.freeze([
+  "begin",
+  "match",
+  "context",
+  "end",
+  "summary",
+]);
+
+export const REPOSITORY_INDEX_HEALTH = Object.freeze([
+  "READY",
+  "INDEXING",
+  "NOT_INITIALIZED",
+  "ENGINE_MISSING",
+  "ENGINE_INVALID",
+  "SERVER_DOWN",
+  "SERVER_UNHEALTHY",
+  "ERROR",
+]);
+
+export const REPOSITORY_INDEX_ENV_BINARY = "FORGELOOP_TGREP_BINARY";

package/src/repository-index/errors.js

@@ -0,0 +1,38 @@
+export const REPOSITORY_INDEX_ERROR_CODES = Object.freeze({
+  PLATFORM_UNSUPPORTED: "E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED",
+  ENGINE_MISSING: "E_REPOSITORY_INDEX_ENGINE_MISSING",
+  ENGINE_DOWNLOAD_FAILED: "E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED",
+  ENGINE_CHECKSUM_MISMATCH: "E_REPOSITORY_INDEX_ENGINE_CHECKSUM_MISMATCH",
+  ENGINE_BINARY_CHECKSUM_MISMATCH: "E_REPOSITORY_INDEX_ENGINE_BINARY_CHECKSUM_MISMATCH",
+  ENGINE_EXTRACTION_FAILED: "E_REPOSITORY_INDEX_ENGINE_EXTRACTION_FAILED",
+  ENGINE_VERSION_MISMATCH: "E_REPOSITORY_INDEX_ENGINE_VERSION_MISMATCH",
+  ENGINE_EXECUTION_FAILED: "E_REPOSITORY_INDEX_ENGINE_EXECUTION_FAILED",
+  ENGINE_OUTPUT_LIMIT: "E_REPOSITORY_INDEX_OUTPUT_LIMIT",
+  NOT_INITIALIZED: "E_REPOSITORY_INDEX_NOT_INITIALIZED",
+  INDEXING: "E_REPOSITORY_INDEX_INDEXING",
+  SERVER_START_FAILED: "E_REPOSITORY_INDEX_SERVER_START_FAILED",
+  SERVER_STOP_FAILED: "E_REPOSITORY_INDEX_SERVER_STOP_FAILED",
+  SERVER_UNHEALTHY: "E_REPOSITORY_INDEX_SERVER_UNHEALTHY",
+  SEARCH_FAILED: "E_REPOSITORY_INDEX_SEARCH_FAILED",
+  OUTPUT_INVALID: "E_REPOSITORY_INDEX_OUTPUT_INVALID",
+  REBUILD_FAILED: "E_REPOSITORY_INDEX_REBUILD_FAILED",
+  REQUEST_INVALID: "E_REPOSITORY_INDEX_REQUEST_INVALID",
+  LOCK_UNSAFE: "E_REPOSITORY_INDEX_LOCK_UNSAFE",
+});
+
+export function repositoryIndexError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  for (const [key, value] of Object.entries(details)) {
+    if (value !== undefined) error[key] = value;
+  }
+  return error;
+}
+
+export function wrapRepositoryIndexError(code, message, cause, details = {}) {
+  const error = repositoryIndexError(code, `${message}: ${cause?.message ?? cause}`, {
+    ...details,
+    cause,
+  });
+  return error;
+}

package/src/repository-index/lifecycle.js

@@ -0,0 +1,17 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Repository-index provisioning is only automatic for an actual repository.
+ * Keeping the candidate test narrow avoids turning ForgeLoop's fixture and
+ * protocol-only targets into implicit native-tool installations.
+ */
+export async function isRepositoryCandidate(repositoryRoot) {
+  try {
+    const info = await lstat(path.join(repositoryRoot, ".git"));
+    return info.isDirectory() || info.isFile();
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}

package/src/repository-index/lock.js

@@ -0,0 +1,113 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+
+import { REPOSITORY_INDEX_ERROR_CODES, repositoryIndexError } from "./errors.js";
+
+const LOCK_POLL_INTERVAL_MS = 50;
+const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
+const MAX_LOCK_TIMEOUT_MS = 120_000;
+
+function readLock(lockPath) {
+  return readFile(lockPath, "utf8")
+    .then((value) => JSON.parse(value))
+    .catch((error) => {
+      if (error.code === "ENOENT") return null;
+      // A competing process can observe the tiny interval between creation
+      // of the exclusive lock file and completion of its metadata write. An
+      // unreadable lock is never stale-released; callers retry until the
+      // owner has published valid metadata or the bounded lease expires.
+      if (error instanceof SyntaxError) return { invalid: true };
+      throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.LOCK_UNSAFE, `Repository Index lock cannot be read: ${lockPath}`, { cause: error });
+    });
+}
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+async function releaseDeadLock(lockPath, observed) {
+  if (observed?.invalid === true) return false;
+  if (observed && processIsAlive(observed.pid)) return false;
+  const quarantine = `${lockPath}.stale-${randomUUID()}`;
+  try {
+    await rename(lockPath, quarantine);
+  } catch (error) {
+    if (error.code === "ENOENT") return true;
+    throw error;
+  }
+  const current = await readLock(quarantine);
+  if (current?.invalid === true) {
+    await rename(quarantine, lockPath);
+    return false;
+  }
+  if (current && JSON.stringify(current) !== JSON.stringify(observed)) {
+    await rename(quarantine, lockPath);
+    return false;
+  }
+  await unlink(quarantine);
+  return true;
+}
+
+export async function acquireRepositoryIndexLock(lockPath, operation, { timeoutMs = DEFAULT_LOCK_TIMEOUT_MS, tryOnly = false } = {}) {
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  const lock = {
+    schemaVersion: 1,
+    lockId: randomUUID(),
+    pid: process.pid,
+    operation,
+    acquiredAt: new Date().toISOString(),
+  };
+  const boundedTimeoutMs = Number.isSafeInteger(timeoutMs) && timeoutMs > 0
+    ? Math.min(timeoutMs, MAX_LOCK_TIMEOUT_MS)
+    : DEFAULT_LOCK_TIMEOUT_MS;
+  const deadline = Date.now() + boundedTimeoutMs;
+  while (true) {
+    let handle = null;
+    try {
+      handle = await open(lockPath, "wx");
+      await handle.writeFile(`${JSON.stringify(lock)}\n`, "utf8");
+      await handle.close();
+      return {
+        lock,
+        release: async () => {
+          const current = await readLock(lockPath);
+          if (current?.lockId === lock.lockId) await unlink(lockPath);
+        },
+      };
+    } catch (error) {
+      if (handle) {
+        try { await handle.close(); } catch { /* preserve original failure */ }
+      }
+      if (error.code !== "EEXIST") throw error;
+      if (tryOnly) {
+        const observed = await readLock(lockPath);
+        if (observed && await releaseDeadLock(lockPath, observed)) continue;
+        return null;
+      }
+      const observed = await readLock(lockPath);
+      if (!observed || !(await releaseDeadLock(lockPath, observed))) {
+        if (Date.now() >= deadline) {
+          throw repositoryIndexError(REPOSITORY_INDEX_ERROR_CODES.LOCK_UNSAFE, `Repository Index operation lock is busy: ${lockPath}`, { lock: observed });
+        }
+        await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_INTERVAL_MS));
+      }
+    }
+  }
+}
+
+export async function withRepositoryIndexLock(repoRoot, operation, callback, options = {}) {
+  const lockPath = options.lockPath ?? path.join(repoRoot, ".forgeloop", "repository-index", "operation.lock");
+  const lease = await acquireRepositoryIndexLock(lockPath, operation, options);
+  try {
+    return await callback(lease.lock);
+  } finally {
+    await lease.release();
+  }
+}