@cassiomc1/forgeloop 1.10.1 → 1.11.0

package/src/adapters/ripwire/provider.js

@@ -0,0 +1,245 @@
+import path from "node:path";
+
+import { assertSafePath } from "../../core/filesystem.js";
+import {
+  normalizeAdvisoryRecallOptions,
+} from "../../core/advisory-context/constants.js";
+import {
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+} from "../../core/error-codes.js";
+import {
+  RIPWIRE_PROCESS_LIMITS,
+  parseRipwireVersion,
+  runRipwireCommand,
+} from "./process.js";
+import {
+  extractCandidateRows,
+  getRipwireRowPath,
+  normalizeReportedPath,
+  normalizeRipwireResult,
+} from "./normalize.js";
+
+function providerError(code, message) {
+  const error = new Error(message);
+  error.name = "RipwireAdvisoryProviderError";
+  error.code = code;
+  return error;
+}
+
+function assertAbsoluteExecutablePath(value) {
+  if (typeof value !== "string" || value.trim() === "" || !path.isAbsolute(value) || /\p{Cc}/u.test(value)) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire executablePath must be an absolute portable path");
+  }
+  return value;
+}
+
+function assertExpectedVersion(value) {
+  if (
+    typeof value !== "string"
+    || value.trim() === ""
+    || value.length > 64
+    || !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/u.test(value)
+  ) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire expectedVersion must be a qualified version token under 64 characters");
+  }
+  return value;
+}
+
+function assertProcessLimit(value, maximum, label) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, `${label} must be an integer between 1 and ${maximum}`);
+  }
+  return value;
+}
+
+function remainingTimeout(deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining < 1) {
+    throw providerError(E_ADVISORY_CONTEXT_TIMEOUT, "Ripwire advisory recall deadline expired");
+  }
+  return remaining;
+}
+
+function reportTransport(callback, payload) {
+  if (typeof callback !== "function") return;
+  try {
+    callback(Object.freeze({ ...payload }));
+  } catch {
+    // Observability hooks cannot change advisory correctness or failure mapping.
+  }
+}
+
+async function runAndReport(executablePath, args, {
+  cwd,
+  timeoutMs,
+  spawnImpl,
+  env,
+  maxStdoutBytes,
+  maxStderrBytes,
+  onTransport,
+  kind,
+} = {}) {
+  const result = await runRipwireCommand(executablePath, args, {
+    cwd,
+    timeoutMs,
+    spawnImpl,
+    env,
+    maxStdoutBytes,
+    maxStderrBytes,
+  });
+  reportTransport(onTransport, {
+    kind,
+    stdoutBytes: result.stdoutBytes,
+    stderrBytes: result.stderrBytes,
+    durationMs: result.durationMs,
+  });
+  return result;
+}
+
+function queryArguments(projectPath, query) {
+  return [
+    projectPath,
+    `--for=${query}`,
+    "--signatures-only",
+    "--json",
+    "--no-cache",
+    "--exclude=.forgeloop",
+  ];
+}
+
+/**
+ * Create an optional host-injected Ripwire adapter.
+ *
+ * Construction is inert: it validates the explicit executable/version pair
+ * but does not discover binaries, spawn processes, access the network, or
+ * write lifecycle state. Version qualification is repeated lazily before a
+ * query so a changed executable cannot silently change the provider identity.
+ */
+export function createRipwireAdvisoryContextProvider({
+  executablePath,
+  expectedVersion,
+  spawnImpl,
+  env,
+  maxStdoutBytes = RIPWIRE_PROCESS_LIMITS.maxStdoutBytes,
+  maxStderrBytes = RIPWIRE_PROCESS_LIMITS.maxStderrBytes,
+  onTransport,
+} = {}) {
+  const qualifiedExecutablePath = assertAbsoluteExecutablePath(executablePath);
+  const qualifiedExpectedVersion = assertExpectedVersion(expectedVersion);
+  const qualifiedStdoutLimit = assertProcessLimit(maxStdoutBytes, RIPWIRE_PROCESS_LIMITS.maxStdoutBytes, "Ripwire stdout limit");
+  const qualifiedStderrLimit = assertProcessLimit(maxStderrBytes, RIPWIRE_PROCESS_LIMITS.maxStderrBytes, "Ripwire stderr limit");
+
+  const provider = {
+    id: "ripwire",
+    version: qualifiedExpectedVersion,
+    async recall({
+      projectPath,
+      taskId,
+      query,
+      limit,
+      maxItemChars,
+      maxTotalChars,
+      timeoutMs,
+    } = {}) {
+      if (typeof projectPath !== "string" || !path.isAbsolute(projectPath) || /\p{Cc}/u.test(projectPath)) {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire projectPath must be an absolute path");
+      }
+      if (typeof taskId !== "string" || taskId.trim() === "") {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire taskId must be a non-empty string");
+      }
+      if (typeof query !== "string" || query.trim() === "" || /\p{Cc}/u.test(query)) {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire query must be a non-empty portable string");
+      }
+      const options = normalizeAdvisoryRecallOptions({ limit, maxItemChars, maxTotalChars, timeoutMs });
+      const projectRoot = path.resolve(projectPath);
+      try {
+        await assertSafePath(projectRoot, ".");
+      } catch {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "Ripwire target directory is unavailable or unsafe");
+      }
+
+      const deadline = Date.now() + options.timeoutMs;
+      let versionResult;
+      try {
+        versionResult = await runAndReport(qualifiedExecutablePath, ["--version"], {
+          cwd: projectRoot,
+          timeoutMs: remainingTimeout(deadline),
+          spawnImpl,
+          env,
+          maxStdoutBytes: Math.min(qualifiedStdoutLimit, 64 * 1024),
+          maxStderrBytes: qualifiedStderrLimit,
+          onTransport,
+          kind: "version",
+        });
+      } catch (error) {
+        throw error.code ? error : providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "Ripwire version probe failed");
+      }
+
+      let actualVersion;
+      try {
+        actualVersion = parseRipwireVersion(versionResult.stdout);
+      } catch {
+        throw providerError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire version probe was not qualified");
+      }
+      if (actualVersion !== qualifiedExpectedVersion) {
+        throw providerError(
+          E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+          "Ripwire executable version does not match the expected qualified version",
+        );
+      }
+
+      let queryResult;
+      try {
+        queryResult = await runAndReport(qualifiedExecutablePath, queryArguments(projectRoot, query), {
+          cwd: projectRoot,
+          timeoutMs: remainingTimeout(deadline),
+          spawnImpl,
+          env,
+          maxStdoutBytes: qualifiedStdoutLimit,
+          maxStderrBytes: qualifiedStderrLimit,
+          onTransport,
+          kind: "query",
+        });
+      } catch (error) {
+        throw error.code ? error : providerError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "Ripwire query failed");
+      }
+
+      let raw;
+      try {
+        raw = JSON.parse(queryResult.stdout);
+      } catch {
+        throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "Ripwire query did not return valid JSON");
+      }
+
+      if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw providerError(E_ADVISORY_CONTEXT_RESULT_INVALID, "Ripwire query JSON root must be an object");
+      }
+
+      const safeSourcePaths = new Set();
+      const rows = extractCandidateRows(raw) ?? [];
+      for (const row of rows) {
+        const relativePath = normalizeReportedPath(getRipwireRowPath(row), projectRoot);
+        if (!relativePath) continue;
+        try {
+          await assertSafePath(projectRoot, relativePath);
+          safeSourcePaths.add(relativePath);
+        } catch {
+          // The normalizer will disclose and drop this candidate.
+        }
+      }
+
+      return normalizeRipwireResult(raw, {
+        projectPath: projectRoot,
+        ...options,
+        sourcePathValidator: (relativePath) => safeSourcePaths.has(relativePath),
+      });
+    },
+  };
+
+  return Object.freeze(provider);
+}
+
+export { queryArguments };

package/src/cli.js

@@ -85,6 +85,11 @@ import { formatAttestationCreateResult } from "./commands/attestation-create.js"
 import { formatAttestationVerifyResult } from "./commands/attestation-verify.js";
 import { formatAttestationStatusResult } from "./commands/attestation-status.js";
 import { formatAttestationVerifyRangeResult } from "./commands/attestation-verify-range.js";
+import {
+  formatRepositoryIndexResult,
+  formatRepositoryIndexStatus,
+  formatSearchResult,
+} from "./commands/repository-index.js";
 import { defaultCommandInputValues, validateForgeLoopCommandInput } from "./core/command-input.js";
 import { COMMAND_EXECUTORS } from "./core/command-executors.js";
 import { resolveTarget } from "./core/filesystem.js";
@@ -368,6 +373,36 @@ export const COMMAND_HANDLERS = Object.freeze({
     }
     return result.ok ? 0 : 1;
   },
+  "index-setup": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-setup"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexResult);
+    return 0;
+  },
+  "index-start": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-start"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexResult);
+    return 0;
+  },
+  "index-stop": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-stop"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexResult);
+    return 0;
+  },
+  "index-status": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-status"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexStatus);
+    return 0;
+  },
+  "index-rebuild": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-rebuild"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexResult);
+    return 0;
+  },
+  search: async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS.search({ target, packageRoot, options, transport: "cli" });
+    renderJsonOr(options, result, formatSearchResult);
+    return exitCode;
+  },
   route: async ({ target, packageRoot, options }) => {
     const { result } = await COMMAND_EXECUTORS.route({ target, packageRoot, options });
     renderJsonOr(options, result, formatRouteResult);

package/src/commands/doctor.js

@@ -5,6 +5,10 @@ import { createEvidence } from "../core/evidence.js";
 import { LAYOUT_VERSION } from "../core/target-layout.js";
 import { inspectNativeAdapter, validateNativeAdapterTargets } from "../core/native-adapters.js";
 import { findIncompleteTransactions, recoverIncompleteTransactions } from "../core/transaction.js";
+import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
+import { getRepositoryIndexStatus, sanitizeRepositoryIndexStatus } from "../repository-index/status.js";
+import { searchRepository } from "../repository-index/search.js";
+import { getPersistentTransportStatus } from "../persistent-transport/client.js";
 
 function finding(code, severity, relativePath, message, remediation = null, evidence = null) {
   const evidenceRecord = evidence && typeof evidence === "object"
@@ -114,7 +118,69 @@ async function adoptAdapters({ target, manifest, adoptPaths, findings }) {
   return nextManifest;
 }
 
-export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false, fix = false }) {
+async function inspectRepositoryIndexForDoctor({ target, packageRoot, repositoryIndex, repositoryIndexOptions, findings }) {
+  const persistentTransport = await getPersistentTransportStatus({ homeDirectory: repositoryIndexOptions?.homeDirectory });
+  if (!repositoryIndex) return { status: "DISABLED", required: false, persistentTransport };
+  if (!(await isRepositoryCandidate(target))) {
+    return { status: "DEFERRED", required: true, reason: "target is not a Git repository", persistentTransport };
+  }
+
+  const status = await getRepositoryIndexStatus(target, { packageRoot, ...repositoryIndexOptions, includeLocalPaths: true });
+  const publicStatus = sanitizeRepositoryIndexStatus(status);
+  const result = {
+    status: publicStatus.health,
+    required: true,
+    engine: publicStatus.engine,
+    engineVersion: publicStatus.engineVersion,
+    indexPath: ".forgeloop/repository-index/tgrep",
+    server: publicStatus.server,
+    diagnostics: publicStatus.diagnostics,
+    persistentTransport,
+  };
+  if (status.health === "READY") {
+    try {
+      const smoke = await searchRepository(target, {
+        ...repositoryIndexOptions,
+        packageRoot,
+        pattern: "__FORGELOOP_DOCTOR_INDEX_SMOKE__",
+        fixedStrings: true,
+        maxCount: 1,
+      });
+      result.smokeSearch = {
+        status: "OK",
+        matchCount: smoke.matches.length,
+        nativeExitCode: smoke.metrics.exitCode,
+      };
+    } catch (error) {
+      result.smokeSearch = {
+        status: "ERROR",
+        code: error.code ?? "E_REPOSITORY_INDEX_SEARCH_FAILED",
+        message: error.message,
+      };
+      findings.push(finding(
+        error.code ?? "E_REPOSITORY_INDEX_SEARCH_FAILED",
+        "error",
+        ".forgeloop/repository-index",
+        `Repository Index smoke search failed: ${error.message}`,
+        "Run forgeloop index-status --json, then index-rebuild if the managed search service is unhealthy.",
+        error.message,
+      ));
+    }
+  }
+  if (status.health !== "READY") {
+    findings.push(finding(
+      publicStatus.diagnostics?.[0]?.code ?? "E_REPOSITORY_INDEX_SERVER_UNHEALTHY",
+      "error",
+      ".forgeloop/repository-index",
+      `Repository Index is ${status.health}; ${publicStatus.diagnostics?.[0]?.message ?? "native index health is not ready"}`,
+      "Run forgeloop index-setup or forgeloop index-rebuild with an approved managed tgrep asset.",
+      publicStatus,
+    ));
+  }
+  return result;
+}
+
+export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false, fix = false, repositoryIndex, repositoryIndexOptions }) {
   const findings = [];
   let incompleteTransactions = await findIncompleteTransactions(target);
   if (fix && incompleteTransactions.some((transaction) => transaction.status === "COMMITTING")) {
@@ -318,11 +384,20 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
     await writeManifest(target, manifest);
   }
 
+  const repositoryIndexResult = await inspectRepositoryIndexForDoctor({
+    target,
+    packageRoot,
+    repositoryIndex,
+    repositoryIndexOptions,
+    findings,
+  });
+
   const ok = findings.every((item) => item.severity !== "error")
     && (!strict || findings.every((item) => item.severity !== "warning"));
   return {
     ok,
     findings,
+    repositoryIndex: repositoryIndexResult,
     evidence: [createEvidence({
       kind: "OBSERVED",
       source: "ForgeLoop doctor",

package/src/commands/index-rebuild.js

@@ -0,0 +1 @@
+export { runRepositoryIndexRebuild, formatRepositoryIndexResult } from "./repository-index.js";

package/src/commands/index-setup.js

@@ -0,0 +1 @@
+export { runRepositoryIndexSetup, formatRepositoryIndexResult } from "./repository-index.js";

package/src/commands/index-start.js

@@ -0,0 +1 @@
+export { runRepositoryIndexStart, formatRepositoryIndexResult } from "./repository-index.js";

package/src/commands/index-status.js

@@ -0,0 +1 @@
+export { runRepositoryIndexStatus, formatRepositoryIndexStatus } from "./repository-index.js";

package/src/commands/index-stop.js

@@ -0,0 +1 @@
+export { runRepositoryIndexStop, formatRepositoryIndexResult } from "./repository-index.js";

package/src/commands/init.js

@@ -9,6 +9,8 @@ import { readTemplateEntries } from "../core/templates.js";
 import { PROJECT_ARTIFACT_PATHS } from "../core/task-paths.js";
 import { isKitPath } from "../core/target-layout.js";
 import { E_INIT_KIT_CONFLICT, E_POLICY_INITIALIZATION_FAILED } from "../core/error-codes.js";
+import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
+import { setupRepositoryIndex } from "../repository-index/server.js";
 
 // Compatibility re-exports: the canonical semantic definitions live in
 // src/core/error-codes.js; this keeps existing import paths working while
@@ -107,6 +109,31 @@ function kitConflictError(relativePath) {
   return error;
 }
 
+async function prepareRepositoryIndexForInit({ target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions, actions }) {
+  if (!repositoryIndex) return { status: "DISABLED", required: false };
+  if (!(await isRepositoryCandidate(target))) {
+    return { status: "DEFERRED", required: true, reason: "target is not a Git repository" };
+  }
+  if (dryRun) {
+    return {
+      status: "WOULD_SETUP",
+      required: true,
+      reason: "dry-run does not provision or execute the native index engine",
+    };
+  }
+
+  const setup = await setupRepositoryIndex(target, { ...repositoryIndexOptions, packageRoot });
+  actions.push({ action: "repository-index-ready", path: ".forgeloop/repository-index", reason: "managed tgrep index and watcher are ready" });
+  return {
+    status: "READY",
+    required: true,
+    health: setup.status?.health ?? "READY",
+    engine: setup.status?.engine ?? "tgrep",
+    engineVersion: setup.status?.engineVersion ?? null,
+    server: setup.status?.server ?? null,
+  };
+}
+
 /**
  * Initializes a target project with the ForgeLoop kit and executable-policy
  * bootstrap, committing manifest authority LAST.
@@ -152,6 +179,8 @@ export async function runInit({
   packageRoot,
   packageVersion,
   hooks = {},
+  repositoryIndex,
+  repositoryIndexOptions,
 } = {}) {
   const entries = await readTemplateEntries(packageRoot);
   const existingManifest = await readManifest(target);
@@ -332,6 +361,15 @@ export async function runInit({
     }
   }
 
+  const repositoryIndexResult = await prepareRepositoryIndexForInit({
+    target,
+    dryRun,
+    packageRoot,
+    repositoryIndex,
+    repositoryIndexOptions,
+    actions,
+  });
+
   // 10. Commit manifest authority LAST: successful initialization is only
   // real once the manifest exists.
   if (hooks.beforeManifestWrite) {
@@ -343,5 +381,5 @@ export async function runInit({
   }
   await writeManifest(target, manifest, { dryRun });
 
-  return { actions, manifest };
+  return { actions, manifest, repositoryIndex: repositoryIndexResult };
 }

package/src/commands/repository-index.js

@@ -0,0 +1,111 @@
+import { rebuildRepositoryIndex, setupRepositoryIndex, startRepositoryIndexServer, stopRepositoryIndexServer } from "../repository-index/server.js";
+import { searchRepository } from "../repository-index/search.js";
+import { formatRepositoryIndexStatus, getRepositoryIndexStatus, sanitizeRepositoryIndexStatus } from "../repository-index/status.js";
+import { searchViaPersistentTransport } from "../persistent-transport/client.js";
+
+function sanitizeLifecycleResult(result) {
+  const { status, indexed, ...rest } = result ?? {};
+  const publicIndexed = indexed && typeof indexed === "object"
+    ? Object.fromEntries(Object.entries(indexed).filter(([key]) => !["root_path", "rootPath", "indexPath", "repositoryRoot"].includes(key)))
+    : indexed;
+  return {
+    ...rest,
+    ...(status ? { status: sanitizeRepositoryIndexStatus(status) } : {}),
+    ...(indexed ? { indexed: publicIndexed } : {}),
+  };
+}
+
+function nativeOptions(options, packageRoot) {
+  return {
+    packageRoot,
+    assetPath: options.assetPath ?? undefined,
+    binaryPath: options.binaryPath ?? undefined,
+    homeDirectory: options.homeDirectory ?? undefined,
+    force: options.force === true,
+    config: options.indexConfig ?? undefined,
+  };
+}
+
+export async function runRepositoryIndexSetup({ target, packageRoot, options = {} } = {}) {
+  const native = nativeOptions(options, packageRoot);
+  const result = await setupRepositoryIndex(target, native);
+  return sanitizeLifecycleResult({ ...result, status: result.status ?? await getRepositoryIndexStatus(target, { ...native, packageRoot, includeLocalPaths: true }) });
+}
+
+export async function runRepositoryIndexStart({ target, packageRoot, options = {} } = {}) {
+  const native = nativeOptions(options, packageRoot);
+  const result = await startRepositoryIndexServer(target, native);
+  return sanitizeLifecycleResult({ ...result, status: result.status ?? await getRepositoryIndexStatus(target, { ...native, packageRoot, includeLocalPaths: true }) });
+}
+
+export async function runRepositoryIndexStop({ target, packageRoot, options = {} } = {}) {
+  const native = nativeOptions(options, packageRoot);
+  const result = await stopRepositoryIndexServer(target, native);
+  return sanitizeLifecycleResult({ ...result, status: await getRepositoryIndexStatus(target, { ...native, packageRoot, skipNativeStatus: true }) });
+}
+
+export async function runRepositoryIndexStatus({ target, packageRoot, options = {} } = {}) {
+  return getRepositoryIndexStatus(target, { ...nativeOptions(options, packageRoot), packageRoot });
+}
+
+export async function runRepositoryIndexRebuild({ target, packageRoot, options = {} } = {}) {
+  const native = nativeOptions(options, packageRoot);
+  const result = await rebuildRepositoryIndex(target, native);
+  const status = result.status ?? await getRepositoryIndexStatus(target, { ...native, packageRoot });
+  const smoke = await searchRepository(target, {
+    ...native,
+    pattern: "__FORGELOOP_INDEX_REBUILD_SMOKE__",
+    fixedStrings: true,
+    maxCount: 1,
+  });
+  return sanitizeLifecycleResult({
+    ...result,
+    status: sanitizeRepositoryIndexStatus(status),
+    smokeSearch: {
+      status: "OK",
+      matchCount: smoke.matches.length,
+      nativeExitCode: smoke.metrics.exitCode,
+    },
+  });
+}
+
+export async function runSearch({ target, packageRoot, options = {}, transport = "integration" } = {}) {
+  if (transport === "cli") {
+    return searchViaPersistentTransport(target, options, {
+      homeDirectory: options.homeDirectory,
+      idleTimeoutMs: options.persistentTransportIdleTimeoutMs,
+      startupTimeoutMs: options.persistentTransportStartupTimeoutMs,
+      requestTimeoutMs: options.persistentTransportRequestTimeoutMs,
+      env: options.env,
+    });
+  }
+  return searchRepository(target, {
+    ...options,
+    packageRoot,
+    pattern: options.pattern,
+    globs: options.globs ?? [],
+    types: options.types ?? [],
+  });
+}
+
+export function formatRepositoryIndexResult(result) {
+  const status = result.status ?? result;
+  const lines = [
+    `Repository Index: ${status.health ?? "READY"}`,
+    `Engine: ${status.engine ?? "tgrep"} ${status.engineVersion ?? "unknown"}`,
+    `Index: ${status.indexPath ?? "unknown"}`,
+    `Server: ${status.server?.running ? `running (pid ${status.server.pid ?? "unknown"})` : "not running"}`,
+  ];
+  if (result.rebuilt) lines.push("Rebuilt: yes");
+  if (result.setup) lines.push(`Setup: ${result.rebuilt ? "rebuilt" : "reused"}`);
+  if (result.stopped !== undefined) lines.push(`Stopped: ${result.stopped ? "yes" : "no"}`);
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatSearchResult(result) {
+  if (result.query.filesWithMatches) return `${(result.files ?? []).join("\n")}${result.files?.length ? "\n" : "no matches\n"}`;
+  const lines = (result.matches ?? []).map((match) => `${match.path}:${match.line}${match.column ? `:${match.column}` : ""}:${match.text}`);
+  return `${lines.join("\n")}${lines.length ? "\n" : "no matches\n"}`;
+}
+
+export { formatRepositoryIndexStatus };

package/src/commands/search.js

@@ -0,0 +1 @@
+export { runSearch, formatSearchResult } from "./repository-index.js";

package/src/commands/update.js

@@ -10,6 +10,8 @@ import {
 } from "../core/manifest.js";
 import { readTemplateEntries } from "../core/templates.js";
 import { isNativeAdapterPath, LAYOUT_VERSION, LEGACY_PROFILE_PATH } from "../core/target-layout.js";
+import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
+import { setupRepositoryIndex } from "../repository-index/server.js";
 
 const LEGACY_CLEANUP_DIRECTORIES = Object.freeze(["ENG", "schemas"]);
 
@@ -295,7 +297,32 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
   return { actions, conflicts, manifest: nextManifest };
 }
 
-export async function runUpdate({ target, dryRun, packageRoot, packageVersion, hooks = {} }) {
+async function attachRepositoryIndexResult(result, { target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions = {} }) {
+  if (!repositoryIndex) return result;
+  if (!(await isRepositoryCandidate(target))) {
+    return { ...result, repositoryIndex: { status: "DEFERRED", required: true, reason: "target is not a Git repository" } };
+  }
+  if (dryRun) {
+    return { ...result, repositoryIndex: { status: "WOULD_SETUP", required: true, reason: "dry-run does not provision or execute the native index engine" } };
+  }
+  if (result.conflicts?.length > 0) {
+    return { ...result, repositoryIndex: { status: "BLOCKED", required: true, reason: "update conflicts must be resolved before index maintenance" } };
+  }
+  const setup = await setupRepositoryIndex(target, { ...repositoryIndexOptions, packageRoot });
+  return {
+    ...result,
+    repositoryIndex: {
+      status: "READY",
+      required: true,
+      health: setup.status?.health ?? "READY",
+      engine: setup.status?.engine ?? "tgrep",
+      engineVersion: setup.status?.engineVersion ?? null,
+      server: setup.status?.server ?? null,
+    },
+  };
+}
+
+export async function runUpdate({ target, dryRun, packageRoot, packageVersion, hooks = {}, repositoryIndex, repositoryIndexOptions }) {
   const currentManifest = await readManifest(target);
   if (!currentManifest) {
     throw new Error("No .forgeloop/manifest.json found; run forgeloop init first.");
@@ -303,7 +330,8 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion, h
 
   const entries = await readTemplateEntries(packageRoot);
   if ((currentManifest.layoutVersion ?? 1) < LAYOUT_VERSION) {
-    return migrateLegacyLayout({ target, dryRun, packageVersion, currentManifest, entries, hooks });
+    const result = await migrateLegacyLayout({ target, dryRun, packageVersion, currentManifest, entries, hooks });
+    return attachRepositoryIndexResult(result, { target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions });
   }
 
   const nextManifest = structuredClone(currentManifest);
@@ -405,7 +433,7 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion, h
   }
 
   if (conflicts.length > 0) {
-    return { actions, conflicts, manifest: currentManifest };
+    return attachRepositoryIndexResult({ actions, conflicts, manifest: currentManifest }, { target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions });
   }
 
   for (const relativePath of Object.keys(nextManifest.files)) {
@@ -423,5 +451,5 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion, h
   nextManifest.packageVersion = packageVersion;
   await writeManifest(target, nextManifest, { dryRun });
   await cleanupLegacyFiles({ target, dryRun, cleanupFiles, cleanupDirectories, hooks, actions, conflicts });
-  return { actions, conflicts, manifest: nextManifest };
+  return attachRepositoryIndexResult({ actions, conflicts, manifest: nextManifest }, { target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions });
 }