[terrafirmbot-source]

Summary

• add an authenticated Local Corpus settings API that stores one canonical root path while leaving source content in place
• add a bounded, incremental in-memory text index with extension allowlisting, denied-directory filtering, symlink skipping, and canonical path-containment checks
• expose read-only local_corpus_status, local_corpus_search, and local_corpus_read MCP tools behind read:local-corpus
• register the tools in MCP discovery/search and refresh the code-derived inventory to 99 unique tools / 32 scopes
• document configuration, safety limits, generated inventory, and synchronized llm.txt mirrors

Verification

• node --import tsx/esm --test tests/unit/local-corpus-index.test.ts tests/unit/local-corpus-tools.test.ts tests/unit/mcp-tool-count-dedup-6854.test.ts (9 passed)
• npm run typecheck:core
• changed-file ESLint (passed)
• npm run test:vitest -- --maxWorkers=4 with a writable DATA_DIR (254 passed)
• npm run check:docs-all
• route-validation, DB-rules, error-helper, public-credentials, file-size, test-discovery, and tracked-artifact checks
• pre-commit Prettier, ESLint, docs-sync, any-budget, and tracked-artifact hooks

Notes

• No corpus content is included in this PR. The SQLite setting contains only the configured root path; indexed content is process-memory only.
• Binary formats such as PDF and DOCX are intentionally out of scope for this first read-only implementation.
• npm run test:unit exceeded the 10-minute local execution limit while still running, so it did not produce a final suite result.
• npm run check:changelog-integrity reports the existing branch baseline: 294 bullets present on origin/release/v3.8.49 are absent from upstream main. This PR does not edit CHANGELOG.md and adds the required changelog fragment instead.

[gemini-code-assist]

Code Review

This pull request introduces a read-only Local Corpus context source feature, allowing operators to expose an approved directory of text files to OmniRoute's MCP server. This includes bounded incremental text indexing, path-containment controls, an authenticated settings API, and three new scoped MCP tools (local_corpus_status, local_corpus_search, and local_corpus_read). Feedback on the implementation highlights opportunities to optimize directory traversal when file limits are reached, correct out-of-bounds line clamping during file reads, and adhere to the repository style guide by moving the inline Zod schema validation to the shared schemas file.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Once the number of collected candidates reaches maxFiles, any further files encountered will be skipped. However, the current implementation continues to traverse the entire remaining directory tree, calling fs.readdir and processing entries, which is highly inefficient for large directories. We can optimize this by clearing the directories stack and breaking out of the loop immediately when the limit is reached.

        if (candidates.length >= this.limits.maxFiles) {
          truncated = true;
          directories.length = 0;
          break;
        }

[gemini-code-assist]

When requestedStart is greater than the total number of lines in the file, the current implementation clamps startLine to lines.length and returns the last line of the file. This is incorrect because the requested range is entirely out of bounds and should return an empty string. We can improve this by checking if startLine is within bounds before slicing.

    const startLine = requestedStart;
    const endLine = Math.min(lines.length, requestedEnd, startLine + this.limits.maxReadLines - 1);
    const hasContent = startLine <= lines.length;
    const contentSlice = hasContent ? lines.slice(startLine - 1, endLine).join("\n") : "";
    return {
      relativePath: normalizeRelativePath(path.relative(root, canonicalFile)),
      content: contentSlice,
      startLine: hasContent ? startLine : lines.length,
      endLine: hasContent ? endLine : lines.length,
      totalLines: lines.length,
      truncated: startLine > 1 || endLine < lines.length,
    };

[gemini-code-assist]

Hard Rule #8 of the Repository Style Guide states: "Always validate inputs with Zod schemas from src/shared/validation/schemas.ts." Defining localCorpusSchema inline in the route file violates this rule. Please move this schema definition to src/shared/validation/schemas.ts and import it here.

References

1. Always validate inputs with Zod schemas from src/shared/validation/schemas.ts. ^(link)

[diegosouzapw]

Reviewed this end-to-end (code, tests, docs, security posture) and ran the test/typecheck/lint suite plus a merge-conflict probe against release/v3.8.49 in an isolated worktree. This is a clean, well-scoped feature.

What's solid

• Path safety is layered correctly: absolute-path input required for the root, fs.realpath canonicalization, symlink rejection both during the directory walk and on the final read target, path.relative-based containment checks, an extension allowlist, and a denied-segment filter (.git, .env, .ssh, node_modules, secrets, etc).
• The MCP tools are only reachable through /api/mcp/, which is already loopback-gated in routeGuard.ts — so a leaked JWT can't remotely trigger local_corpus_search/local_corpus_read even though the settings API itself is normal remote-authenticated (matches how the rest of /api/settings/* works).
• Settings route: authenticated, z.strict()-validated, errors routed through sanitizeErrorMessage().
• Persistence reuses the existing generic key_value table — no new migration needed.
• 8 new unit tests pass (local-corpus-index.test.ts, local-corpus-tools.test.ts), and the tool-count dedup test correctly reflects 99 unique tools. typecheck:core and ESLint are clean on every changed file.
• Docs (docs/frameworks/LOCAL_CORPUS_CONTEXT.md) are accurate and match the actual code behavior.

One real (non-blocking) bug found while probing: LocalCorpusIndex.read() clamps an out-of-range startLine to the last line instead of erroring. Repro: a 3-line file, read('a.txt', {startLine:1000, endLine:1010}) returns {content:"", startLine:4, endLine:4, totalLines:4, truncated:true} instead of signaling the requested range doesn't exist. Not a security issue (no data leak; totalLines lets a caller self-correct), but worth tightening — this matches what the automated Gemini review already flagged.

Minor perf nit: collectCandidates() keeps walking every subdirectory even after the maxFiles/maxTotalBytes cap is hit (only individual files are skipped past the cap). Low severity since the corpus root is operator-configured, not attacker-controlled, but a short-circuit would bound scan time better on very large trees.

Process note: this PR targets main; the active development branch is release/v3.8.49. A dry-run merge against it produced zero conflicts in any file this PR touches (conflicts only appear in unrelated files from normal branch drift), so retargeting should be mechanical.

Nice work — happy to see this merged with the base retargeted; the two code nits above can land as a fast follow-up if you'd rather not touch this PR again.

[mergify]

⚠️ The sha of the head commit of this PR conflicts with #7076. Mergify cannot evaluate rules on this PR. Once #7076 is merged or closed, Mergify will resume processing this PR. ⚠️

[diegosouzapw]

Superseded by #8685 (merged). Merge conflicts resolved against latest release/v3.8.49.