codebase-onboarder 0.5.0 → 0.7.0

package/server/mcp/analysis.js

@@ -9,10 +9,8 @@
 //
 // It reuses the same `shared/` analyzers the browser runs, rather than a second
 // implementation: a number in an MCP response is the same number the UI shows.
-
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-
 import { scanRepo } from '../../shared/analyzer/scan.js';
 import { computeFacts, scanIndex } from '../../shared/analyzer/graph.js';
 import { detectManifest } from '../../shared/analyzer/services.js';
@@ -29,180 +27,161 @@ import { nodeFileSource } from '../fileSourceNode.js';
 import { gitLog, parseGitLog } from '../gitHistory.js';
 import { analyzeHistory, unavailableHistory } from '../../shared/analyzer/history.js';
 import { expandHome, resolveInside } from '../paths.js';
-
 // How many repositories stay warm. One is the common case — a client points at a
 // repo and works in it — but an agent comparing two projects should not pay for a
 // rescan when it alternates between them. Each entry holds a parsed file list, so
 // the cap is about memory, not count.
 const MAX_CACHED = 4;
-
 const cache = new Map();
-
 // Root path -> the finished analysis. Resolving the path first means `/Users/x/~
 // repo` and `/Users/x/repo` are one entry, not two that evict each other.
 export function cachedAnalysis(root) {
-  return cache.get(path.resolve(root)) || null;
+    return cache.get(path.resolve(root)) || null;
 }
-
 export function cachedRoots() {
-  return [...cache.keys()];
+    return [...cache.keys()];
 }
-
 export function clearAnalysisCache() {
-  cache.clear();
+    cache.clear();
 }
-
 // A tool error is a message the agent can act on, not a stack trace. The protocol
 // layer turns these into `isError` results so the model sees the sentence and can
 // correct itself, rather than the call failing opaquely.
 export class ToolError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'ToolError';
-  }
+    name;
+    constructor(message) {
+        super(message);
+        this.name = 'ToolError';
+    }
 }
-
 function buildPatterns(scan, facts, manifest) {
-  const layersInfo = computeLayers(scan, facts);
-  return {
-    layersInfo,
-    findings: detectPatterns(scan, facts, manifest, layersInfo),
-    coupling: couplingMatrix(scan, facts),
-  };
+    const layersInfo = computeLayers(scan, facts);
+    return {
+        layersInfo,
+        findings: detectPatterns(scan, facts, manifest, layersInfo),
+        coupling: couplingMatrix(scan, facts),
+    };
 }
-
 async function collectHistory(root, scan) {
-  try {
-    const log = await gitLog(root);
-    if (!log.ok) return unavailableHistory(log.reason);
-    return analyzeHistory(scan, parseGitLog(log.text), { totalCommits: log.totalCommits });
-  } catch {
-    return unavailableHistory('The history could not be read — the scan itself is unaffected.');
-  }
+    try {
+        const log = await gitLog(root);
+        if (!log.ok)
+            return unavailableHistory(log.reason);
+        return analyzeHistory(scan, parseGitLog(log.text), { totalCommits: log.totalCommits });
+    }
+    catch {
+        return unavailableHistory('The history could not be read — the scan itself is unaffected.');
+    }
 }
-
 // The entry point. `force` is how `onboarder_rescan` differs from every other
 // tool: the same call twice returns the same answer until it is asked not to.
 export async function analyzeRepository(rootInput, { force = false } = {}) {
-  const trimmed = String(rootInput || '').trim();
-  if (!trimmed) throw new ToolError('A repository path is required.');
-
-  const root = expandHome(trimmed);
-  if (!force) {
-    const hit = cache.get(root);
-    if (hit) {
-      // Re-insert so the eviction below drops a genuinely cold repo rather than
-      // whichever one happened to be scanned first.
-      cache.delete(root);
-      cache.set(root, hit);
-      return hit;
+    const trimmed = String(rootInput || '').trim();
+    if (!trimmed)
+        throw new ToolError('A repository path is required.');
+    const root = expandHome(trimmed);
+    if (!force) {
+        const hit = cache.get(root);
+        if (hit) {
+            // Re-insert so the eviction below drops a genuinely cold repo rather than
+            // whichever one happened to be scanned first.
+            cache.delete(root);
+            cache.set(root, hit);
+            return hit;
+        }
+    }
+    const stat = await fs.stat(root).catch(() => null);
+    if (!stat?.isDirectory()) {
+        throw new ToolError(`No folder at ${root}. Check the path and try again.`);
     }
-  }
-
-  const stat = await fs.stat(root).catch(() => null);
-  if (!stat?.isDirectory()) {
-    throw new ToolError(`No folder at ${root}. Check the path and try again.`);
-  }
-
-  const source = nodeFileSource(root);
-  const scan = await scanRepo(source);
-  const manifest = await detectManifest(source);
-  const facts = computeFacts(scan, manifest);
-
-  // Built here rather than on first search for the same reason the HTTP route
-  // builds it at scan time: a search that reads every file is a search whose cost
-  // depends on what was asked, and an agent asks repeatedly.
-  const searchIndexData = await buildSearchIndex(source, scan.files.map((f) => f.path));
-
-  const analysis = {
-    root,
-    scannedAt: Date.now(),
-    scan,
-    facts,
-    manifest,
-    stack: analyzeStack(manifest, scan.stats.languages),
-    patterns: buildPatterns(scan, facts, manifest),
-    health: analyzeHealth(scan, facts),
-    security: summarizeSecurity(scan),
-    history: await collectHistory(root, scan),
-    searchIndex: searchIndexData,
-    // The prose the overview panel shows, computed here so an agent gets the same
-    // onboarding summary a person reads rather than a pile of raw arrays.
-    overview: explainOverview(scan, facts, manifest),
-    caveats: scanCaveats(scan),
-  };
-
-  cache.set(root, analysis);
-  // Map preserves insertion order, so the first key is the least recently used.
-  while (cache.size > MAX_CACHED) cache.delete(cache.keys().next().value);
-  return analysis;
+    const source = nodeFileSource(root);
+    const scan = await scanRepo(source);
+    const manifest = await detectManifest(source);
+    const facts = computeFacts(scan, manifest);
+    // Built here rather than on first search for the same reason the HTTP route
+    // builds it at scan time: a search that reads every file is a search whose cost
+    // depends on what was asked, and an agent asks repeatedly.
+    const searchIndexData = await buildSearchIndex(source, scan.files.map((f) => f.path));
+    const analysis = {
+        root,
+        scannedAt: Date.now(),
+        scan,
+        facts,
+        manifest,
+        stack: analyzeStack(manifest, scan.stats.languages),
+        patterns: buildPatterns(scan, facts, manifest),
+        health: analyzeHealth(scan, facts),
+        security: summarizeSecurity(scan),
+        history: await collectHistory(root, scan),
+        searchIndex: searchIndexData,
+        // The prose the overview panel shows, computed here so an agent gets the same
+        // onboarding summary a person reads rather than a pile of raw arrays.
+        overview: explainOverview(scan, facts, manifest),
+        caveats: scanCaveats(scan),
+    };
+    cache.set(root, analysis);
+    // Map preserves insertion order, so the first key is the least recently used.
+    while (cache.size > MAX_CACHED)
+        cache.delete(cache.keys().next().value);
+    return analysis;
 }
-
-
 // Files anywhere under a folder, parsed or not. `scanIndex().filesIn` is an exact
 // directory lookup over the *parsed* files, which is the right thing for a diagram
 // of one directory and the wrong thing for "what is in this folder" — an agent
 // asking about `public` wants the stylesheet and the icons too.
 export function filesUnder(analysis, folder) {
-  const prefix = folder ? String(folder).replace(/\/+$/, '') + '/' : '';
-  return analysis.scan.allFiles.filter((p) => p.startsWith(prefix));
+    const prefix = folder ? String(folder).replace(/\/+$/, '') + '/' : '';
+    return analysis.scan.allFiles.filter((p) => p.startsWith(prefix));
 }
-
 // The files under a folder that the parser understood, as file objects. The same
 // containment rule, so the two cannot disagree about what a folder holds.
 export function parsedFilesUnder(analysis, folder) {
-  const paths = new Set(filesUnder(analysis, folder));
-  return analysis.scan.files.filter((f) => paths.has(f.path));
+    const paths = new Set(filesUnder(analysis, folder));
+    return analysis.scan.files.filter((f) => paths.has(f.path));
 }
-
 // Resolves a repository-relative path to an absolute one, refusing anything that
 // lands outside the root. This is the same check `/api/file` makes, and it is the
 // only thing standing between an agent and the rest of the disk: an MCP client is
 // another program on this machine, not a browser tab, so the cross-origin guards
 // do not apply here. Containment is the boundary, not the scan.
 export function resolveIn(analysis, relPath) {
-  if (typeof relPath !== 'string' || !relPath.trim()) {
-    throw new ToolError('A file path is required.');
-  }
-  const abs = resolveInside(analysis.root, relPath.trim());
-  if (!abs) throw new ToolError(`${relPath} is outside ${analysis.root}.`);
-  return { abs, rel: path.relative(analysis.root, abs).split(path.sep).join('/') };
+    if (typeof relPath !== 'string' || !relPath.trim()) {
+        throw new ToolError('A file path is required.');
+    }
+    const abs = resolveInside(analysis.root, relPath.trim());
+    if (!abs)
+        throw new ToolError(`${relPath} is outside ${analysis.root}.`);
+    return { abs, rel: path.relative(analysis.root, abs).split(path.sep).join('/') };
 }
-
 // The same, but also insists the parser looked at the file. The analysis tools
 // (`explain_file`, `explain_folder`) need a parsed file because every field they
 // return came from parsing it; saying "package.json is not a file in the scanned
 // repository" for a JSON manifest would be technically true and practically
 // useless, so those tools check this and `read_file` does not.
 export function fileIn(analysis, relPath) {
-  const { abs, rel } = resolveIn(analysis, relPath);
-  const file = scanIndex(analysis.scan).fileAt(rel);
-  if (!file) {
-    throw new ToolError(`${rel} is not a source file in the scan. Use onboarder_read_file to read it as text.`);
-  }
-  return { abs, rel, file };
+    const { abs, rel } = resolveIn(analysis, relPath);
+    const file = scanIndex(analysis.scan).fileAt(rel);
+    if (!file) {
+        throw new ToolError(`${rel} is not a source file in the scan. Use onboarder_read_file to read it as text.`);
+    }
+    return { abs, rel, file };
 }
-
 export async function readFileText(analysis, relPath) {
-  const { abs, rel } = resolveIn(analysis, relPath);
-  const stat = await fs.stat(abs).catch(() => null);
-  if (!stat?.isFile()) throw new ToolError(`${rel} could not be read.`);
-  // Matches the HTTP route's ceiling. A tool that returns a 200 MB file has not
-  // answered the question, it has exhausted the context window.
-  if (stat.size > 200 * 1024) {
-    throw new ToolError(`${rel} is ${Math.round(stat.size / 1024)} KB — too large to return whole.`);
-  }
-  return { path: rel, text: await fs.readFile(abs, 'utf8') };
+    const { abs, rel } = resolveIn(analysis, relPath);
+    const stat = await fs.stat(abs).catch(() => null);
+    if (!stat?.isFile())
+        throw new ToolError(`${rel} could not be read.`);
+    // Matches the HTTP route's ceiling. A tool that returns a 200 MB file has not
+    // answered the question, it has exhausted the context window.
+    if (stat.size > 200 * 1024) {
+        throw new ToolError(`${rel} is ${Math.round(stat.size / 1024)} KB — too large to return whole.`);
+    }
+    return { path: rel, text: await fs.readFile(abs, 'utf8') };
 }
-
 // Re-exported so tools build their payloads from the same helpers the views do,
 // rather than re-deriving "which files are in this folder" a third time.
 //
 // `importsOf`/`importers` are the plain-object maps `computeFacts` returns, not
 // methods on the scan index — the index only answers questions about files.
-export {
-  scanIndex, dirOf, baseName,
-  explainFile, explainFolder,
-  docFileRow, fileFactsLine, fileStaticDoc, folderStaticDoc,
-  searchDocuments,
-};
+export { scanIndex, dirOf, baseName, explainFile, explainFolder, docFileRow, fileFactsLine, fileStaticDoc, folderStaticDoc, searchDocuments, };
+//# sourceMappingURL=analysis.js.map

package/server/mcp/analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../../src/server/mcp/analysis.ts"],"names":[],"mappings":"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","sourcesContent":["// The analysis every MCP tool reads from, computed once per repository.\n//\n// The HTTP app already knows this shape: `apiScan.js` returns `scan`, `facts` and\n// `manifest`, and each view derives the rest on demand. An MCP client has no\n// session to hold a scan id in and no view to trigger those derivations, so this\n// module does the whole derivation up front, once, and hands the result to every\n// tool. The tools are then pure projections — a tool cannot disagree with another\n// about what the repository looks like, because there is only one answer cached.\n//\n// It reuses the same `shared/` analyzers the browser runs, rather than a second\n// implementation: a number in an MCP response is the same number the UI shows.\n\nimport { promises as fs } from 'node:fs';\nimport path from 'node:path';\n\nimport { scanRepo } from '../../shared/analyzer/scan.js';\nimport { computeFacts, scanIndex } from '../../shared/analyzer/graph.js';\nimport { detectManifest } from '../../shared/analyzer/services.js';\nimport { analyzeStack } from '../../shared/analyzer/stack.js';\nimport { computeLayers, detectPatterns, couplingMatrix } from '../../shared/analyzer/patterns.js';\nimport { analyzeHealth } from '../../shared/analyzer/health.js';\nimport { summarizeSecurity } from '../../shared/analyzer/security.js';\nimport { explainOverview, explainFile, explainFolder, scanCaveats } from '../../shared/analyzer/explainLocal.js';\nimport { docFileRow, fileFactsLine, fileStaticDoc, folderStaticDoc } from '../../shared/analyzer/docs.js';\nimport { baseName, dirOf } from '../../shared/analyzer/pathUtil.js';\nimport { buildSearchIndex } from '../searchIndex.js';\nimport { searchDocuments } from '../apiSearch.js';\nimport { nodeFileSource } from '../fileSourceNode.js';\nimport { gitLog, parseGitLog } from '../gitHistory.js';\nimport { analyzeHistory, unavailableHistory } from '../../shared/analyzer/history.js';\nimport { expandHome, resolveInside } from '../paths.js';\n\n// How many repositories stay warm. One is the common case — a client points at a\n// repo and works in it — but an agent comparing two projects should not pay for a\n// rescan when it alternates between them. Each entry holds a parsed file list, so\n// the cap is about memory, not count.\nconst MAX_CACHED = 4;\n\nconst cache = new Map();\n\n// Root path -> the finished analysis. Resolving the path first means `/Users/x/~\n// repo` and `/Users/x/repo` are one entry, not two that evict each other.\nexport function cachedAnalysis(root) {\n  return cache.get(path.resolve(root)) || null;\n}\n\nexport function cachedRoots() {\n  return [...cache.keys()];\n}\n\nexport function clearAnalysisCache() {\n  cache.clear();\n}\n\n// A tool error is a message the agent can act on, not a stack trace. The protocol\n// layer turns these into `isError` results so the model sees the sentence and can\n// correct itself, rather than the call failing opaquely.\nexport class ToolError extends Error {\n  name: string;\n\n  constructor(message) {\n    super(message);\n    this.name = 'ToolError';\n  }\n}\n\nfunction buildPatterns(scan, facts, manifest) {\n  const layersInfo = computeLayers(scan, facts);\n  return {\n    layersInfo,\n    findings: detectPatterns(scan, facts, manifest, layersInfo),\n    coupling: couplingMatrix(scan, facts),\n  };\n}\n\nasync function collectHistory(root, scan) {\n  try {\n    const log = await gitLog(root);\n    if (!log.ok) return unavailableHistory(log.reason);\n    return analyzeHistory(scan, parseGitLog(log.text), { totalCommits: log.totalCommits });\n  } catch {\n    return unavailableHistory('The history could not be read — the scan itself is unaffected.');\n  }\n}\n\n// The entry point. `force` is how `onboarder_rescan` differs from every other\n// tool: the same call twice returns the same answer until it is asked not to.\nexport async function analyzeRepository(rootInput, { force = false }: Record<string, any> = {}) {\n  const trimmed = String(rootInput || '').trim();\n  if (!trimmed) throw new ToolError('A repository path is required.');\n\n  const root = expandHome(trimmed);\n  if (!force) {\n    const hit = cache.get(root);\n    if (hit) {\n      // Re-insert so the eviction below drops a genuinely cold repo rather than\n      // whichever one happened to be scanned first.\n      cache.delete(root);\n      cache.set(root, hit);\n      return hit;\n    }\n  }\n\n  const stat = await fs.stat(root).catch(() => null);\n  if (!stat?.isDirectory()) {\n    throw new ToolError(`No folder at ${root}. Check the path and try again.`);\n  }\n\n  const source = nodeFileSource(root);\n  const scan = await scanRepo(source);\n  const manifest = await detectManifest(source);\n  const facts = computeFacts(scan, manifest);\n\n  // Built here rather than on first search for the same reason the HTTP route\n  // builds it at scan time: a search that reads every file is a search whose cost\n  // depends on what was asked, and an agent asks repeatedly.\n  const searchIndexData = await buildSearchIndex(source, scan.files.map((f) => f.path));\n\n  const analysis = {\n    root,\n    scannedAt: Date.now(),\n    scan,\n    facts,\n    manifest,\n    stack: analyzeStack(manifest, scan.stats.languages),\n    patterns: buildPatterns(scan, facts, manifest),\n    health: analyzeHealth(scan, facts),\n    security: summarizeSecurity(scan),\n    history: await collectHistory(root, scan),\n    searchIndex: searchIndexData,\n    // The prose the overview panel shows, computed here so an agent gets the same\n    // onboarding summary a person reads rather than a pile of raw arrays.\n    overview: explainOverview(scan, facts, manifest),\n    caveats: scanCaveats(scan),\n  };\n\n  cache.set(root, analysis);\n  // Map preserves insertion order, so the first key is the least recently used.\n  while (cache.size > MAX_CACHED) cache.delete(cache.keys().next().value);\n  return analysis;\n}\n\n\n// Files anywhere under a folder, parsed or not. `scanIndex().filesIn` is an exact\n// directory lookup over the *parsed* files, which is the right thing for a diagram\n// of one directory and the wrong thing for \"what is in this folder\" — an agent\n// asking about `public` wants the stylesheet and the icons too.\nexport function filesUnder(analysis, folder) {\n  const prefix = folder ? String(folder).replace(/\\/+$/, '') + '/' : '';\n  return analysis.scan.allFiles.filter((p) => p.startsWith(prefix));\n}\n\n// The files under a folder that the parser understood, as file objects. The same\n// containment rule, so the two cannot disagree about what a folder holds.\nexport function parsedFilesUnder(analysis, folder) {\n  const paths = new Set(filesUnder(analysis, folder));\n  return analysis.scan.files.filter((f) => paths.has(f.path));\n}\n\n// Resolves a repository-relative path to an absolute one, refusing anything that\n// lands outside the root. This is the same check `/api/file` makes, and it is the\n// only thing standing between an agent and the rest of the disk: an MCP client is\n// another program on this machine, not a browser tab, so the cross-origin guards\n// do not apply here. Containment is the boundary, not the scan.\nexport function resolveIn(analysis, relPath) {\n  if (typeof relPath !== 'string' || !relPath.trim()) {\n    throw new ToolError('A file path is required.');\n  }\n  const abs = resolveInside(analysis.root, relPath.trim());\n  if (!abs) throw new ToolError(`${relPath} is outside ${analysis.root}.`);\n  return { abs, rel: path.relative(analysis.root, abs).split(path.sep).join('/') };\n}\n\n// The same, but also insists the parser looked at the file. The analysis tools\n// (`explain_file`, `explain_folder`) need a parsed file because every field they\n// return came from parsing it; saying \"package.json is not a file in the scanned\n// repository\" for a JSON manifest would be technically true and practically\n// useless, so those tools check this and `read_file` does not.\nexport function fileIn(analysis, relPath) {\n  const { abs, rel } = resolveIn(analysis, relPath);\n  const file = scanIndex(analysis.scan).fileAt(rel);\n  if (!file) {\n    throw new ToolError(`${rel} is not a source file in the scan. Use onboarder_read_file to read it as text.`);\n  }\n  return { abs, rel, file };\n}\n\nexport async function readFileText(analysis, relPath) {\n  const { abs, rel } = resolveIn(analysis, relPath);\n  const stat = await fs.stat(abs).catch(() => null);\n  if (!stat?.isFile()) throw new ToolError(`${rel} could not be read.`);\n  // Matches the HTTP route's ceiling. A tool that returns a 200 MB file has not\n  // answered the question, it has exhausted the context window.\n  if (stat.size > 200 * 1024) {\n    throw new ToolError(`${rel} is ${Math.round(stat.size / 1024)} KB — too large to return whole.`);\n  }\n  return { path: rel, text: await fs.readFile(abs, 'utf8') };\n}\n\n// Re-exported so tools build their payloads from the same helpers the views do,\n// rather than re-deriving \"which files are in this folder\" a third time.\n//\n// `importsOf`/`importers` are the plain-object maps `computeFacts` returns, not\n// methods on the scan index — the index only answers questions about files.\nexport {\n  scanIndex, dirOf, baseName,\n  explainFile, explainFolder,\n  docFileRow, fileFactsLine, fileStaticDoc, folderStaticDoc,\n  searchDocuments,\n};\n"]}

package/server/mcp/http.d.ts

@@ -0,0 +1,9 @@
+export declare const HTTP_HOST = "127.0.0.1";
+export declare const DEFAULT_PORT = 8790;
+export declare function handleMcpHttpRequest(req: any, res: any): void | Promise<void>;
+/**
+ * Start the Streamable HTTP transport. Returns `{ url, port, server, close }`, and
+ * `port` is the port actually bound — which matters because the caller may have
+ * asked for 0 and gets a free one back.
+ */
+export declare function createHttpTransport({ port, host }?: Record<string, any>): Promise<unknown>;