soup-chop 1.0.0

package/dist/index.js

@@ -0,0 +1,2056 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/lib/clientConfig.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+var CLIENT_ALIASES = {
+  "claude": "claude-desktop",
+  "claude_desktop": "claude-desktop",
+  "claude-desktop": "claude-desktop",
+  "claudecode": "claude-code",
+  "claude_code": "claude-code",
+  "claude-code": "claude-code",
+  "vscode": "vscode-copilot",
+  "vscode_copilot": "vscode-copilot",
+  "vscode-copilot": "vscode-copilot",
+  "copilot": "vscode-copilot",
+  "gemini": "gemini-cli",
+  "geminicli": "gemini-cli",
+  "gemini_cli": "gemini-cli",
+  "gemini-code-assist": "gemini-code-assist",
+  "gemini_code_assist": "gemini-code-assist",
+  "firebase": "firebase-studio",
+  "firebase_studio": "firebase-studio",
+  "firebase-studio": "firebase-studio"
+};
+var DEFAULT_SOUP_CHOP_SERVER = {
+  command: "npx",
+  args: ["soup-chop", "serve"]
+};
+function buildSoupChopServer(options = {}) {
+  if (!options.localBuild) {
+    return DEFAULT_SOUP_CHOP_SERVER;
+  }
+  return {
+    command: "node",
+    args: [resolve(options.cwd ?? process.cwd(), "dist", "index.js"), "serve"]
+  };
+}
+var CLIENTS = [
+  {
+    id: "windsurf",
+    name: "Windsurf",
+    status: "implemented",
+    configPath: "~/.codeium/windsurf/mcp_config.json",
+    scope: "global",
+    notes: "Official Windsurf docs use mcp_config.json with an mcpServers object.",
+    format: "mcpServers"
+  },
+  {
+    id: "cursor",
+    name: "Cursor",
+    status: "implemented",
+    configPath: "~/.cursor/mcp.json",
+    projectConfigPath: ".cursor/mcp.json",
+    scope: "global",
+    notes: "Official docs also support per-project .cursor/mcp.json.",
+    format: "mcpServers"
+  },
+  {
+    id: "claude-desktop",
+    name: "Claude Desktop",
+    status: "implemented",
+    scope: "global",
+    notes: "Official docs expose this file via Claude > Settings > Developer > Edit Config on macOS and Windows.",
+    format: "mcpServers"
+  },
+  {
+    id: "claude-code",
+    name: "Claude Code",
+    status: "documented",
+    scope: "ui",
+    notes: "Official docs recommend claude mcp add or plugin installation rather than direct file editing.",
+    format: "manual"
+  },
+  {
+    id: "antigravity",
+    name: "Antigravity",
+    status: "documented",
+    scope: "ui",
+    notes: "Official docs describe MCP Store / View raw config flow, but do not expose a stable file path.",
+    format: "manual"
+  },
+  {
+    id: "cline",
+    name: "Cline",
+    status: "documented",
+    scope: "ui",
+    notes: "Official docs expose cline_mcp_settings.json from the MCP Servers UI, but path varies by install.",
+    format: "manual"
+  },
+  {
+    id: "vscode-copilot",
+    name: "VS Code Copilot",
+    status: "implemented",
+    configPath: ".vscode/mcp.json",
+    scope: "project",
+    notes: "Official docs support project .vscode/mcp.json or user settings under mcp.servers.",
+    format: "servers"
+  },
+  {
+    id: "gemini-cli",
+    name: "Gemini CLI",
+    status: "documented",
+    configPath: "~/.gemini/settings.json",
+    scope: "global",
+    notes: "Official docs also support project .gemini/settings.json.",
+    format: "mcpServers"
+  },
+  {
+    id: "gemini-code-assist",
+    name: "Gemini Code Assist",
+    status: "documented",
+    configPath: "~/.gemini/settings.json",
+    scope: "global",
+    notes: "Official docs share the Gemini settings format with Gemini CLI.",
+    format: "mcpServers"
+  },
+  {
+    id: "firebase-studio",
+    name: "Firebase Studio",
+    status: "implemented",
+    configPath: ".idx/mcp.json",
+    scope: "project",
+    notes: "Official docs use a project-local .idx/mcp.json file.",
+    format: "mcpServers"
+  }
+];
+function expandHome(path) {
+  return path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+}
+function resolvePathForScope(path, scope, cwd) {
+  if (path.startsWith("~/")) {
+    return expandHome(path);
+  }
+  if (scope === "project" && !isAbsolute(path)) {
+    return join(cwd, path);
+  }
+  return path;
+}
+function resolveClaudeDesktopConfigPath(scope) {
+  if (scope !== "global") {
+    return null;
+  }
+  if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  if (process.platform === "win32") {
+    const appData = process.env["APPDATA"];
+    return appData ? join(appData, "Claude", "claude_desktop_config.json") : null;
+  }
+  return null;
+}
+function getClientConfigScopes(client) {
+  const scopes = /* @__PURE__ */ new Set();
+  if (client.scope === "global" && client.configPath) {
+    scopes.add("global");
+  }
+  if (client.scope === "project" && client.configPath) {
+    scopes.add("project");
+  }
+  if (client.globalConfigPath) {
+    scopes.add("global");
+  }
+  if (client.projectConfigPath) {
+    scopes.add("project");
+  }
+  if (client.id === "claude-desktop") {
+    scopes.add("global");
+  }
+  return [...scopes];
+}
+function getDefaultClientConfigScope(client) {
+  if (client.scope === "global" || client.scope === "project") {
+    return client.scope;
+  }
+  const [first] = getClientConfigScopes(client);
+  return first ?? null;
+}
+function getDocumentedClientTargets(client) {
+  const targets = /* @__PURE__ */ new Set();
+  if (client.configPath) {
+    targets.add(client.configPath);
+  }
+  if (client.globalConfigPath) {
+    targets.add(client.globalConfigPath);
+  }
+  if (client.projectConfigPath) {
+    targets.add(client.projectConfigPath);
+  }
+  return [...targets];
+}
+function getClientDisplayPath(client, options = {}) {
+  return resolveClientConfigPath(client, options) ?? getDocumentedClientTargets(client)[0] ?? "UI-managed";
+}
+function getClientMode(client, options = {}) {
+  if (client.status === "implemented" && resolveClientConfigPath(client, options) !== null) {
+    return "auto-config";
+  }
+  if (client.status === "implemented") {
+    return "implemented elsewhere";
+  }
+  return client.status;
+}
+function listClientEntries(options = {}) {
+  return CLIENTS.map((client) => ({
+    id: client.id,
+    name: client.name,
+    status: client.status,
+    mode: getClientMode(client, options),
+    format: client.format,
+    supportedScopes: getClientConfigScopes(client),
+    defaultScope: getDefaultClientConfigScope(client),
+    displayPath: getClientDisplayPath(client, options),
+    resolvedPath: resolveClientConfigPath(client, options),
+    notes: client.notes
+  }));
+}
+function getClientSetupGuidance(client, options = {}) {
+  const entry = listClientEntries(options).find((candidate) => candidate.id === client.id);
+  const targets = getDocumentedClientTargets(client);
+  const targetText = targets.length > 0 ? targets.join(", ") : entry?.displayPath ?? "UI-managed";
+  return `Documented target: ${targetText}. ${client.notes} See \`soup-chop clients\` for the full client matrix.`;
+}
+function resolveClientConfigPath(client, options = {}) {
+  const scope = options.scope ?? getDefaultClientConfigScope(client);
+  if (!scope) {
+    return null;
+  }
+  if (client.id === "claude-desktop") {
+    return resolveClaudeDesktopConfigPath(scope);
+  }
+  const template = scope === "global" ? client.globalConfigPath ?? (client.scope === "global" ? client.configPath : void 0) : client.projectConfigPath ?? (client.scope === "project" ? client.configPath : void 0);
+  if (!template) {
+    return null;
+  }
+  return resolvePathForScope(template, scope, options.cwd ?? process.cwd());
+}
+function normalizeClientId(input) {
+  const normalized = input.trim().toLowerCase();
+  return CLIENT_ALIASES[normalized] ?? normalized;
+}
+function resolveClient(input) {
+  const id = normalizeClientId(input);
+  const client = CLIENTS.find((entry) => entry.id === id);
+  if (!client) {
+    throw new Error(`Unknown client: "${input}". Run \`soup-chop clients\` to see supported client IDs.`);
+  }
+  return client;
+}
+function getSupportedScopeOrThrow(client, requestedScope) {
+  if (!requestedScope) {
+    const defaultScope = getDefaultClientConfigScope(client);
+    if (defaultScope) {
+      return defaultScope;
+    }
+    if (client.format === "manual") {
+      throw new Error(`Client ${client.name} is documented but not file-configurable automatically. ${getClientSetupGuidance(client)}`);
+    }
+    throw new Error(`Client ${client.name} is not auto-configurable on this platform. ${getClientSetupGuidance(client)}`);
+  }
+  const supportedScopes = getClientConfigScopes(client);
+  if (supportedScopes.includes(requestedScope)) {
+    return requestedScope;
+  }
+  const supported = supportedScopes.length > 0 ? supportedScopes.join(", ") : "none";
+  const suggestedScope = getDefaultClientConfigScope(client);
+  const suggestion = suggestedScope ? ` Try \`soup-chop configure ${client.id}${suggestedScope === "project" ? " --project" : " --global"}\` or omit the scope.` : "";
+  throw new Error(`Client ${client.name} does not support ${requestedScope} configuration. Supported scopes: ${supported}.${suggestion} ${getClientSetupGuidance(client)}`);
+}
+function parseJsonObject(content) {
+  const parsed = JSON.parse(content);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Expected a JSON object at config root");
+  }
+  return parsed;
+}
+async function configureClient(id, options = {}) {
+  const prepared = await prepareClientConfig(id, options);
+  await mkdir(dirname(prepared.path), { recursive: true });
+  await writeFile(prepared.path, prepared.content, "utf8");
+  return {
+    client: prepared.client,
+    path: prepared.path,
+    created: prepared.created
+  };
+}
+async function prepareClientConfig(id, options = {}) {
+  const client = resolveClient(id);
+  const scope = getSupportedScopeOrThrow(client, options.scope);
+  const path = resolveClientConfigPath(client, { ...options, scope });
+  if (!path) {
+    throw new Error(`Client ${client.name} does not expose a stable file path for automatic configuration`);
+  }
+  const { root, existed } = await readConfig(path);
+  const updated = buildConfiguredRoot(root, client, options);
+  return {
+    client,
+    path,
+    created: !existed,
+    root: updated,
+    content: `${JSON.stringify(updated, null, 2)}
+`
+  };
+}
+function buildConfigSnippet(client, options = {}) {
+  return buildConfiguredRoot({}, client, options);
+}
+function buildConfiguredRoot(root, client, options = {}) {
+  if (client.format === "manual") {
+    throw new Error(`Client ${client.name} is documented but not file-configurable automatically. ${getClientSetupGuidance(client, options)}`);
+  }
+  const key = client.format;
+  const existing = root[key];
+  const servers = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  servers["soup-chop"] = buildSoupChopServer(options);
+  return { ...root, [key]: servers };
+}
+async function readConfig(path) {
+  try {
+    const content = await readFile(path, "utf8");
+    return { root: parseJsonObject(content), existed: true };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { root: {}, existed: false };
+    }
+    throw error;
+  }
+}
+function getSupportedAutoConfigClients(options = {}) {
+  return CLIENTS.filter((client) => getClientMode(client, options) === "auto-config");
+}
+function getSupportedAutoConfigClientIds(options = {}) {
+  return getSupportedAutoConfigClients(options).map((client) => client.id);
+}
+
+// src/lib/configureArgs.ts
+function parseConfigureArgs(args, supportedClientIds) {
+  const [client, ...flags] = args;
+  if (!client) {
+    throw new Error(`Missing client name.
+
+Usage: soup-chop configure <client> [--project|--global] [--dry-run|--print] [--local-build]
+Supported clients: ${supportedClientIds.join(", ")}`);
+  }
+  let scope;
+  let localBuild = false;
+  let outputMode = "write";
+  for (const flag of flags) {
+    if (flag === "--project") {
+      if (scope && scope !== "project") {
+        throw new Error("Choose only one configure scope: --project or --global");
+      }
+      scope = "project";
+      continue;
+    }
+    if (flag === "--global") {
+      if (scope && scope !== "global") {
+        throw new Error("Choose only one configure scope: --project or --global");
+      }
+      scope = "global";
+      continue;
+    }
+    if (flag === "--dry-run") {
+      if (outputMode !== "write") {
+        throw new Error("Choose only one configure output mode: --dry-run or --print");
+      }
+      outputMode = "dry-run";
+      continue;
+    }
+    if (flag === "--print") {
+      if (outputMode !== "write") {
+        throw new Error("Choose only one configure output mode: --dry-run or --print");
+      }
+      outputMode = "print";
+      continue;
+    }
+    if (flag === "--local-build") {
+      localBuild = true;
+      continue;
+    }
+    throw new Error(`Unknown configure option: "${flag}"
+
+Usage: soup-chop configure <client> [--project|--global] [--dry-run|--print] [--local-build]`);
+  }
+  return { client, scope, localBuild, outputMode };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/lib/cache.ts
+import envPaths from "env-paths";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+var paths = envPaths("soup-chop");
+function cachePath(pkg, version, filename) {
+  return join2(paths.cache, pkg, version, filename);
+}
+async function readCached(pkg, version, filename) {
+  try {
+    return await readFile2(cachePath(pkg, version, filename), "utf-8");
+  } catch {
+    return null;
+  }
+}
+async function writeCache(pkg, version, filename, content) {
+  const dir = join2(paths.cache, pkg, version);
+  await mkdir2(dir, { recursive: true });
+  await writeFile2(join2(dir, filename), content, "utf-8");
+}
+
+// src/lib/isExactVersion.ts
+var EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function isExactVersion(version) {
+  return EXACT_VERSION_RE.test(version);
+}
+
+// src/lib/fetchReadme.ts
+var UNPKG_BASE = "https://unpkg.com";
+function normalizeMarkdownOrigin(origin = "README.md") {
+  const normalized = origin.replace(/^\/+/, "");
+  return normalized.length > 0 ? normalized : "README.md";
+}
+function markdownCacheFile(origin = "README.md") {
+  const normalized = normalizeMarkdownOrigin(origin);
+  return normalized === "README.md" ? normalized : `source__${normalized.replace(/\//g, "__")}`;
+}
+async function fetchMarkdownFile(pkg, version, origin = "README.md") {
+  const normalizedOrigin = normalizeMarkdownOrigin(origin);
+  const cacheFile = markdownCacheFile(normalizedOrigin);
+  const canCache = isExactVersion(version);
+  if (canCache) {
+    const cached = await readCached(pkg, version, cacheFile);
+    if (cached !== null) return cached;
+  }
+  const url = `${UNPKG_BASE}/${pkg}@${version}/${normalizedOrigin}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch markdown file ${normalizedOrigin} for ${pkg}@${version}: ${res.status} ${res.statusText}`);
+  }
+  const content = await res.text();
+  if (canCache) {
+    await writeCache(pkg, version, cacheFile, content);
+  }
+  return content;
+}
+async function fetchReadme(pkg, version) {
+  return fetchMarkdownFile(pkg, version, "README.md");
+}
+
+// src/lib/discoverSources.ts
+import { posix } from "node:path";
+var UNPKG_BASE2 = "https://unpkg.com";
+var SOURCE_MANIFEST_VERSION = 1;
+var TOP_LEVEL_DOC_ALLOWLIST = /* @__PURE__ */ new Set(["API.MD", "FAQ.MD", "MIGRATING.MD", "UPGRADING.MD", "CHANGELOG.MD", "CONTRIBUTING.MD"]);
+function normalizeOrigin(origin) {
+  return origin.replace(/^\//, "");
+}
+function canonicalTopLevelDocName(path) {
+  return path.replace(/\.md$/i, ".md").toUpperCase();
+}
+function isSearchSource(source) {
+  return source !== null;
+}
+function cacheFileForOrigin(origin) {
+  const normalized = normalizeOrigin(origin);
+  if (normalized === "README.md") {
+    return normalized;
+  }
+  return `source__${normalized.replace(/\//g, "__")}`;
+}
+function createSourceId(origin) {
+  return normalizeOrigin(origin).replace(/[^a-zA-Z0-9]+/g, "__").replace(/^__+|__+$/g, "").toLowerCase();
+}
+function createSource(sourceKind, origin, content) {
+  const normalized = normalizeOrigin(origin);
+  return {
+    sourceId: createSourceId(normalized),
+    sourceKind,
+    origin: normalized,
+    title: posix.basename(normalized),
+    content
+  };
+}
+async function readManifestSources(pkg, version) {
+  const raw = await readCached(pkg, version, "sources-manifest.json");
+  if (raw === null) {
+    return null;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (manifest.version !== SOURCE_MANIFEST_VERSION) {
+    return null;
+  }
+  const sources = await Promise.all(
+    manifest.sources.map(async (entry) => {
+      const content = await readCached(pkg, version, entry.cacheFile);
+      if (content === null) {
+        return null;
+      }
+      return {
+        sourceId: entry.sourceId,
+        sourceKind: entry.sourceKind,
+        origin: entry.origin,
+        title: entry.title,
+        content
+      };
+    })
+  );
+  return sources.every(isSearchSource) ? sources : null;
+}
+async function writeManifestSources(pkg, version, sources) {
+  await Promise.all(
+    sources.map((source) => writeCache(pkg, version, cacheFileForOrigin(source.origin), source.content))
+  );
+  const manifest = {
+    version: SOURCE_MANIFEST_VERSION,
+    sources: sources.map((source) => ({
+      sourceId: source.sourceId,
+      sourceKind: source.sourceKind,
+      origin: source.origin,
+      title: source.title,
+      cacheFile: cacheFileForOrigin(source.origin)
+    }))
+  };
+  await writeCache(pkg, version, "sources-manifest.json", JSON.stringify(manifest, null, 2));
+}
+async function fetchMetaFiles(pkg, version, dir, canCache) {
+  const cacheKey = `meta__${dir}.json`;
+  if (canCache) {
+    const cached = await readCached(pkg, version, cacheKey);
+    if (cached !== null) {
+      const parsed = JSON.parse(cached);
+      return Array.isArray(parsed) ? parsed : [];
+    }
+  }
+  const response = await fetch(`${UNPKG_BASE2}/${pkg}@${version}/${dir}/?meta`);
+  if (response.status === 404) {
+    return [];
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to fetch package docs metadata for ${pkg}@${version} in ${dir}/: ${response.status} ${response.statusText}`);
+  }
+  const meta = await response.json();
+  const paths2 = selectPackageDocPaths(
+    (meta.files ?? []).flatMap((file) => typeof file.path === "string" ? [file.path] : [])
+  );
+  if (canCache) {
+    await writeCache(pkg, version, cacheKey, JSON.stringify(paths2));
+  }
+  return paths2;
+}
+async function fetchRootMetaFiles(pkg, version, canCache) {
+  const cacheKey = "meta__root.json";
+  if (canCache) {
+    const cached = await readCached(pkg, version, cacheKey);
+    if (cached !== null) {
+      const parsed = JSON.parse(cached);
+      return Array.isArray(parsed) ? parsed : [];
+    }
+  }
+  const response = await fetch(`${UNPKG_BASE2}/${pkg}@${version}/?meta`);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch package root metadata for ${pkg}@${version}: ${response.status} ${response.statusText}`);
+  }
+  const meta = await response.json();
+  const paths2 = selectTopLevelDocPaths(
+    (meta.files ?? []).flatMap((file) => typeof file.path === "string" ? [file.path] : [])
+  );
+  if (canCache) {
+    await writeCache(pkg, version, cacheKey, JSON.stringify(paths2));
+  }
+  return paths2;
+}
+async function fetchSource(pkg, version, sourceKind, origin) {
+  const normalized = normalizeOrigin(origin);
+  const content = await fetchMarkdownFile(pkg, version, normalized);
+  return createSource(sourceKind, normalized, content);
+}
+function selectPackageDocPaths(paths2) {
+  return [...new Set(
+    paths2.map((path) => normalizeOrigin(path)).filter((path) => /^(?:docs|doc)\//.test(path)).filter((path) => /\.md$/i.test(path))
+  )].sort((left, right) => left.localeCompare(right));
+}
+function selectTopLevelDocPaths(paths2) {
+  return [...new Set(
+    paths2.map((path) => normalizeOrigin(path)).filter((path) => !path.includes("/")).filter((path) => /\.md$/i.test(path)).filter((path) => TOP_LEVEL_DOC_ALLOWLIST.has(canonicalTopLevelDocName(path)))
+  )].sort((left, right) => left.localeCompare(right));
+}
+async function discoverSources(pkg, version) {
+  const canCache = isExactVersion(version);
+  if (canCache) {
+    const cached = await readManifestSources(pkg, version);
+    if (cached !== null) {
+      return cached;
+    }
+  }
+  const readme = await fetchReadme(pkg, version);
+  const [docPaths, docsPaths, topLevelDocPaths] = await Promise.all([
+    fetchMetaFiles(pkg, version, "doc", canCache),
+    fetchMetaFiles(pkg, version, "docs", canCache),
+    fetchRootMetaFiles(pkg, version, canCache)
+  ]);
+  const packageDocOrigins = [.../* @__PURE__ */ new Set([...docPaths, ...docsPaths])];
+  const sources = [
+    createSource("readme", "README.md", readme),
+    ...await Promise.all(packageDocOrigins.map((origin) => fetchSource(pkg, version, "package_doc", origin))),
+    ...await Promise.all(topLevelDocPaths.map((origin) => fetchSource(pkg, version, "top_level_doc", origin)))
+  ];
+  if (canCache) {
+    await writeManifestSources(pkg, version, sources);
+  }
+  return sources;
+}
+
+// src/lib/extractToc.ts
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+function hasPhrasingChildren(node) {
+  return "children" in node && Array.isArray(node.children);
+}
+function phrasingText(node) {
+  if (node.type === "text" || node.type === "inlineCode") {
+    return node.value;
+  }
+  if (hasPhrasingChildren(node)) {
+    return node.children.map((child) => phrasingText(child)).join("");
+  }
+  return "";
+}
+function headingText(node) {
+  return node.children.map((child) => phrasingText(child)).join("");
+}
+function buildPath(stack, current) {
+  const ancestors = stack.filter((s) => s.depth < current.depth);
+  return [...ancestors.map((s) => s.title), current.title].join("/");
+}
+function extractToc(markdown) {
+  const tree = unified().use(remarkParse).parse(markdown);
+  const totalLines = markdown.split("\n").length;
+  const rawHeadings = [];
+  for (const node of tree.children) {
+    if (node.type === "heading" && node.position) {
+      rawHeadings.push({
+        depth: node.depth,
+        title: headingText(node),
+        startLine: node.position.start.line
+      });
+    }
+  }
+  const entries = [];
+  const stack = [];
+  for (let i = 0; i < rawHeadings.length; i++) {
+    const h = rawHeadings[i];
+    const endLine = i + 1 < rawHeadings.length ? rawHeadings[i + 1].startLine - 1 : totalLines;
+    while (stack.length > 0 && stack[stack.length - 1].depth >= h.depth) {
+      stack.pop();
+    }
+    const path = buildPath(stack, h);
+    stack.push({ depth: h.depth, title: h.title });
+    entries.push({ depth: h.depth, title: h.title, path, startLine: h.startLine, endLine });
+  }
+  return entries;
+}
+
+// src/lib/getTopic.ts
+function getTopic(markdown, path, documentPath) {
+  if (documentPath === path) {
+    return markdown.trim();
+  }
+  const entries = extractToc(markdown);
+  const entry = entries.find((e) => e.path === path);
+  if (!entry) {
+    const available = entries.map((e) => e.path).join("\n  ");
+    throw new Error(`Topic not found: "${path}"
+Available paths:
+  ${available}`);
+  }
+  return sliceLines(markdown, entry);
+}
+function sliceLines(markdown, entry) {
+  const lines = markdown.split("\n");
+  return lines.slice(entry.startLine - 1, entry.endLine).join("\n").trim();
+}
+
+// src/lib/extractChunks.ts
+function extractMarkdownChunks(source) {
+  const entries = extractToc(source.content);
+  if (entries.length === 0) {
+    const content = source.content.trim();
+    if (content.length === 0) {
+      return [];
+    }
+    const totalLines = source.content.split("\n").length;
+    return [{
+      chunkId: `${source.sourceId}#1`,
+      sourceId: source.sourceId,
+      sourceKind: source.sourceKind,
+      sourceTitle: source.title,
+      origin: source.origin,
+      title: source.title,
+      path: source.origin,
+      startLine: 1,
+      endLine: totalLines,
+      content
+    }];
+  }
+  return entries.map((entry, index) => ({
+    chunkId: `${source.sourceId}#${index + 1}`,
+    sourceId: source.sourceId,
+    sourceKind: source.sourceKind,
+    sourceTitle: source.title,
+    origin: source.origin,
+    title: entry.title,
+    path: entry.path,
+    startLine: entry.startLine,
+    endLine: entry.endLine,
+    content: sliceLines(source.content, entry)
+  }));
+}
+
+// src/lib/tocUtils.ts
+import { posix as posix2 } from "node:path";
+function buildTopicId(origin, path) {
+  const normalizedOrigin = normalizeMarkdownOrigin(origin);
+  if (path === void 0 || path === normalizedOrigin) {
+    return normalizedOrigin;
+  }
+  return `${normalizedOrigin}#${path}`;
+}
+function parseTopicId(topicId) {
+  const trimmed = topicId.trim();
+  if (trimmed.length === 0) {
+    throw new Error("Topic id must not be empty.");
+  }
+  const separatorIndex = trimmed.indexOf("#");
+  if (separatorIndex === -1) {
+    const origin2 = normalizeMarkdownOrigin(trimmed);
+    return { origin: origin2, path: origin2, topicId: buildTopicId(origin2) };
+  }
+  const origin = normalizeMarkdownOrigin(trimmed.slice(0, separatorIndex));
+  const path = trimmed.slice(separatorIndex + 1).trim();
+  if (path.length === 0) {
+    throw new Error(`Topic id "${topicId}" is missing a path after "#".`);
+  }
+  return { origin, path, topicId: buildTopicId(origin, path) };
+}
+function resolveTopicSelection(path, origin, topicId) {
+  if (topicId !== void 0) {
+    const selection = parseTopicId(topicId);
+    if (origin !== void 0 && normalizeMarkdownOrigin(origin) !== selection.origin) {
+      throw new Error(`Provided origin "${origin}" does not match topic_id origin "${selection.origin}".`);
+    }
+    if (path !== void 0 && path !== selection.path) {
+      throw new Error(`Provided path "${path}" does not match topic_id path "${selection.path}".`);
+    }
+    return selection;
+  }
+  if (path === void 0) {
+    if (origin === void 0) {
+      throw new Error("Either `topic_id` or `path` must be provided.");
+    }
+    const normalizedOrigin2 = normalizeMarkdownOrigin(origin);
+    return { origin: normalizedOrigin2, path: normalizedOrigin2, topicId: buildTopicId(normalizedOrigin2) };
+  }
+  const normalizedOrigin = normalizeMarkdownOrigin(origin);
+  return { origin: normalizedOrigin, path, topicId: buildTopicId(normalizedOrigin, path) };
+}
+function buildDocumentTocEntries(markdown, origin = "README.md", title = posix2.basename(normalizeMarkdownOrigin(origin))) {
+  const normalizedOrigin = normalizeMarkdownOrigin(origin);
+  const entries = extractToc(markdown);
+  if (entries.length === 0) {
+    return [{
+      depth: 0,
+      title,
+      path: normalizedOrigin,
+      startLine: 1,
+      endLine: markdown.split("\n").length,
+      origin: normalizedOrigin,
+      topicId: buildTopicId(normalizedOrigin)
+    }];
+  }
+  return entries.map((entry) => ({
+    ...entry,
+    origin: normalizedOrigin,
+    topicId: buildTopicId(normalizedOrigin, entry.path)
+  }));
+}
+function buildPackageTocEntries(sources) {
+  return sources.flatMap((source) => {
+    const totalLines = source.content.split("\n").length;
+    const documentEntry = {
+      depth: 0,
+      title: source.title,
+      path: source.origin,
+      startLine: 1,
+      endLine: totalLines,
+      origin: source.origin,
+      topicId: buildTopicId(source.origin)
+    };
+    const entries = extractToc(source.content);
+    if (entries.length === 0) {
+      return [documentEntry];
+    }
+    return [
+      documentEntry,
+      ...entries.map((entry) => ({
+        ...entry,
+        origin: source.origin,
+        topicId: buildTopicId(source.origin, entry.path)
+      }))
+    ];
+  });
+}
+
+// src/lib/searchDocs.ts
+var STOPWORDS = /* @__PURE__ */ new Set(["a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "how", "in", "is", "it", "of", "on", "or", "that", "the", "to", "with"]);
+var FIELD_WEIGHTS = { title: 5, path: 3, body: 1 };
+var SEARCH_INDEX_VERSION = 1;
+function searchIndexCacheFile() {
+  return "search-index.json";
+}
+function normalizeText(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+function tokenize(text) {
+  return normalizeText(text).split(/\s+/).filter((token) => token.length > 0).filter((token) => !STOPWORDS.has(token));
+}
+function countTokens(tokens) {
+  const frequencies = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+  }
+  return frequencies;
+}
+function buildSearchIndex(chunks) {
+  const documentFrequencies = /* @__PURE__ */ new Map();
+  const indexedChunks = chunks.map((chunk) => {
+    const titleTokens = tokenize(chunk.title);
+    const pathTokens = tokenize(chunk.path);
+    const bodyTokens = tokenize(chunk.content);
+    const seenTokens = /* @__PURE__ */ new Set([...titleTokens, ...pathTokens, ...bodyTokens]);
+    for (const token of seenTokens) {
+      documentFrequencies.set(token, (documentFrequencies.get(token) ?? 0) + 1);
+    }
+    return {
+      chunk,
+      normalizedTitle: normalizeText(chunk.title),
+      normalizedPath: normalizeText(chunk.path),
+      normalizedBody: normalizeText(chunk.content),
+      titleFrequencies: countTokens(titleTokens),
+      pathFrequencies: countTokens(pathTokens),
+      bodyFrequencies: countTokens(bodyTokens)
+    };
+  });
+  return { chunks: indexedChunks, documentFrequencies };
+}
+function serializeSearchIndex(index) {
+  const serialized = {
+    version: SEARCH_INDEX_VERSION,
+    chunks: index.chunks.map((entry) => ({
+      chunk: entry.chunk,
+      normalizedTitle: entry.normalizedTitle,
+      normalizedPath: entry.normalizedPath,
+      normalizedBody: entry.normalizedBody,
+      titleFrequencies: [...entry.titleFrequencies.entries()],
+      pathFrequencies: [...entry.pathFrequencies.entries()],
+      bodyFrequencies: [...entry.bodyFrequencies.entries()]
+    })),
+    documentFrequencies: [...index.documentFrequencies.entries()]
+  };
+  return JSON.stringify(serialized);
+}
+function deserializeSearchIndex(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (parsed.version !== SEARCH_INDEX_VERSION) {
+    return null;
+  }
+  return {
+    chunks: parsed.chunks.map((entry) => ({
+      chunk: entry.chunk,
+      normalizedTitle: entry.normalizedTitle,
+      normalizedPath: entry.normalizedPath,
+      normalizedBody: entry.normalizedBody,
+      titleFrequencies: new Map(entry.titleFrequencies),
+      pathFrequencies: new Map(entry.pathFrequencies),
+      bodyFrequencies: new Map(entry.bodyFrequencies)
+    })),
+    documentFrequencies: new Map(parsed.documentFrequencies)
+  };
+}
+async function readCachedSearchIndex(pkg, version) {
+  const raw = await readCached(pkg, version, searchIndexCacheFile());
+  if (raw === null) {
+    return null;
+  }
+  return deserializeSearchIndex(raw);
+}
+async function writeCachedSearchIndex(pkg, version, index) {
+  await writeCache(pkg, version, searchIndexCacheFile(), serializeSearchIndex(index));
+}
+async function resolveSearchIndex(pkg, version) {
+  const canCache = isExactVersion(version);
+  if (canCache) {
+    const cached = await readCachedSearchIndex(pkg, version);
+    if (cached !== null) {
+      return cached;
+    }
+  }
+  const sources = await discoverSources(pkg, version);
+  const chunks = sources.flatMap((source) => extractMarkdownChunks(source));
+  const index = buildSearchIndex(chunks);
+  if (canCache) {
+    await writeCachedSearchIndex(pkg, version, index);
+  }
+  return index;
+}
+function inverseDocumentFrequency(documentCount, documentFrequency) {
+  return Math.log((documentCount + 1) / (documentFrequency + 1)) + 1;
+}
+function createPreview(content, queryTokens, maxLength = 220) {
+  const collapsed = content.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= maxLength) {
+    return collapsed;
+  }
+  const lowerCollapsed = collapsed.toLowerCase();
+  const matchIndex = queryTokens.reduce((best, token) => {
+    const index = lowerCollapsed.indexOf(token.toLowerCase());
+    if (index === -1) {
+      return best;
+    }
+    return best === -1 ? index : Math.min(best, index);
+  }, -1);
+  if (matchIndex === -1) {
+    return `${collapsed.slice(0, maxLength - 3).trimEnd()}...`;
+  }
+  const start = Math.max(0, matchIndex - Math.floor((maxLength - 3) / 2));
+  const snippet = collapsed.slice(start, start + maxLength - 3).trim();
+  return start === 0 ? `${snippet}...` : `...${snippet}`;
+}
+function searchIndex(index, query, limit = 5) {
+  const queryTokens = [...new Set(tokenize(query))];
+  if (queryTokens.length === 0) {
+    return [];
+  }
+  const normalizedQuery = normalizeText(query);
+  const documentCount = index.chunks.length;
+  const ranked = index.chunks.map((entry, indexPosition) => {
+    let score = 0;
+    let matchedTokens = 0;
+    for (const token of queryTokens) {
+      const titleFrequency = entry.titleFrequencies.get(token) ?? 0;
+      const pathFrequency = entry.pathFrequencies.get(token) ?? 0;
+      const bodyFrequency = entry.bodyFrequencies.get(token) ?? 0;
+      const weightedFrequency = titleFrequency * FIELD_WEIGHTS.title + pathFrequency * FIELD_WEIGHTS.path + bodyFrequency * FIELD_WEIGHTS.body;
+      if (weightedFrequency === 0) {
+        continue;
+      }
+      matchedTokens += 1;
+      score += weightedFrequency * inverseDocumentFrequency(documentCount, index.documentFrequencies.get(token) ?? 0);
+    }
+    if (matchedTokens === 0) {
+      return null;
+    }
+    const coverage = matchedTokens / queryTokens.length;
+    score += coverage * 2;
+    if (normalizedQuery.length > 0) {
+      if (entry.normalizedTitle.includes(normalizedQuery) || entry.normalizedPath.includes(normalizedQuery)) {
+        score += 3;
+      } else if (entry.normalizedBody.includes(normalizedQuery)) {
+        score += 1.5;
+      }
+    }
+    return {
+      indexPosition,
+      score,
+      result: {
+        sourceKind: entry.chunk.sourceKind,
+        sourceTitle: entry.chunk.sourceTitle,
+        path: entry.chunk.path,
+        score,
+        startLine: entry.chunk.startLine,
+        endLine: entry.chunk.endLine,
+        preview: createPreview(entry.chunk.content, queryTokens),
+        origin: entry.chunk.origin,
+        topicId: buildTopicId(entry.chunk.origin, entry.chunk.path)
+      }
+    };
+  }).filter((entry) => entry !== null).sort((left, right) => {
+    if (right.score !== left.score) {
+      return right.score - left.score;
+    }
+    if (left.result.origin !== right.result.origin) {
+      return left.result.origin.localeCompare(right.result.origin);
+    }
+    if (left.result.path !== right.result.path) {
+      return left.result.path.localeCompare(right.result.path);
+    }
+    return left.indexPosition - right.indexPosition;
+  }).slice(0, Math.max(1, limit));
+  const maxScore = ranked[0]?.score ?? 1;
+  return ranked.map(({ result, score }) => ({
+    ...result,
+    score: Number((score / maxScore).toFixed(3))
+  }));
+}
+async function searchDocs(pkg, version, query, limit = 5) {
+  const index = await resolveSearchIndex(pkg, version);
+  return {
+    package: pkg,
+    version,
+    query,
+    results: searchIndex(index, query, limit)
+  };
+}
+
+// src/lib/fetchDts.ts
+import { posix as posix3 } from "node:path";
+var UNPKG_BASE3 = "https://unpkg.com";
+var EXPORT_FROM_RE_SOURCE = `^export\\s+(?:\\*|\\{[^}]*\\})\\s+from\\s+['"]([^'"]+)['"]`;
+var IMPORT_STAR_RE_SOURCE = `^import\\s+\\*\\s+as\\s+\\w+\\s+from\\s+['"]([^'"]+)['"]`;
+function createSpecifierRegexes() {
+  return [
+    new RegExp(EXPORT_FROM_RE_SOURCE, "gm"),
+    new RegExp(IMPORT_STAR_RE_SOURCE, "gm")
+  ];
+}
+async function fetchText(url, cacheKey) {
+  if (cacheKey) {
+    const cached = await readCached(...cacheKey);
+    if (cached !== null) return cached;
+  }
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText} \u2014 ${url}`);
+  const content = await res.text();
+  if (cacheKey) {
+    await writeCache(...cacheKey, content);
+  }
+  return content;
+}
+async function resolveTypesPath(pkg, version) {
+  const cacheVersion = isExactVersion(version) ? version : null;
+  const pkgJsonUrl = `${UNPKG_BASE3}/${pkg}@${version}/package.json`;
+  const raw = await fetchText(pkgJsonUrl, cacheVersion ? [pkg, cacheVersion, "package.json"] : null);
+  const meta = JSON.parse(raw);
+  const typesField = meta["types"] ?? meta["typings"];
+  if (!typesField) throw new Error(`Package ${pkg}@${version} does not declare a "types" or "typings" field`);
+  return typesField.startsWith("./") ? typesField.slice(2) : typesField;
+}
+function resolveRelativePath(currentFile, specifier) {
+  const dir = posix3.dirname(currentFile);
+  return posix3.normalize(posix3.join(dir, specifier));
+}
+function normalizeToDts(path) {
+  if (path.endsWith(".d.ts")) return path;
+  if (path.endsWith(".d.cts")) return path;
+  if (path.endsWith(".d.mts")) return path;
+  if (path.endsWith(".cjs")) return path.slice(0, -4) + ".d.cts";
+  if (path.endsWith(".mjs")) return path.slice(0, -4) + ".d.mts";
+  if (path.endsWith(".js")) return path.slice(0, -3) + ".d.ts";
+  if (path.endsWith(".ts")) return path;
+  if (path.endsWith(".cts")) return path;
+  if (path.endsWith(".mts")) return path;
+  return path + ".d.ts";
+}
+function candidateDtsPaths(filePath) {
+  const normalized = normalizeToDts(filePath);
+  const candidates = [normalized];
+  if (!/\.(?:d\.ts|d\.cts|d\.mts|ts|cts|mts)$/.test(filePath) && !/\.(?:js|cjs|mjs)$/.test(filePath)) {
+    candidates.push(posix3.join(filePath, "index.d.ts"));
+    candidates.push(posix3.join(filePath, "index.d.cts"));
+    candidates.push(posix3.join(filePath, "index.d.mts"));
+  }
+  return [...new Set(candidates)];
+}
+async function collectDts(pkg, version, cacheVersion, filePath, visited, chunks) {
+  let resolvedPath = null;
+  let content = null;
+  for (const candidate of candidateDtsPaths(filePath)) {
+    if (visited.has(candidate)) return;
+    const url = `${UNPKG_BASE3}/${pkg}@${version}/${candidate}`;
+    const cacheKey = `dts__${candidate.replace(/\//g, "__")}`;
+    try {
+      content = await fetchText(url, cacheVersion ? [pkg, cacheVersion, cacheKey] : null);
+      resolvedPath = candidate;
+      break;
+    } catch {
+      continue;
+    }
+  }
+  if (!resolvedPath || content === null) return;
+  visited.add(resolvedPath);
+  chunks.push(content);
+  const specifiers = /* @__PURE__ */ new Set();
+  for (const re of createSpecifierRegexes()) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const spec = m[1];
+      if (spec.startsWith(".")) specifiers.add(spec);
+    }
+  }
+  await Promise.all(
+    [...specifiers].map((spec) => {
+      const resolved = resolveRelativePath(resolvedPath, spec);
+      return collectDts(pkg, version, cacheVersion, resolved, visited, chunks);
+    })
+  );
+}
+async function fetchDts(pkg, version) {
+  const typesPath = await resolveTypesPath(pkg, version);
+  const cacheVersion = isExactVersion(version) ? version : null;
+  const visited = /* @__PURE__ */ new Set();
+  const chunks = [];
+  await collectDts(pkg, version, cacheVersion, typesPath, visited, chunks);
+  return chunks.join("\n");
+}
+
+// src/lib/extractApiRef.ts
+var PATTERNS = [
+  { kind: "function", re: /^export\s+(?:declare\s+)?function\s+(\w+)[^;{]*/gm },
+  { kind: "class", re: /^export\s+(?:declare\s+)?(?:abstract\s+)?class\s+(\w+)[^{]*/gm },
+  { kind: "interface", re: /^export\s+(?:declare\s+)?interface\s+(\w+)[^{]*/gm },
+  { kind: "type", re: /^export\s+(?:declare\s+)?type\s+(\w+)\s*(?:<[^=]*>)?\s*=[^;]*/gm },
+  { kind: "const", re: /^export\s+(?:declare\s+)?const\s+(\w+)\s*:[^;]*/gm },
+  { kind: "enum", re: /^export\s+(?:declare\s+)?(?:const\s+)?enum\s+(\w+)/gm }
+];
+function extractApiRef(dts, pkg, version) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const { kind, re } of PATTERNS) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(dts)) !== null) {
+      const name = m[1];
+      const kinds = grouped.get(name) ?? /* @__PURE__ */ new Set();
+      kinds.add(kind);
+      grouped.set(name, kinds);
+    }
+  }
+  const entries = [...grouped.entries()].map(([name, kinds]) => ({
+    name,
+    kinds: [...kinds].sort()
+  }));
+  entries.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+  return { package: pkg, version, entries };
+}
+function collectMatches(dts, pattern) {
+  pattern.lastIndex = 0;
+  const matches = [];
+  let match;
+  while ((match = pattern.exec(dts)) !== null) {
+    matches.push(match[0].trim());
+  }
+  return matches;
+}
+function blockPattern(prefix, name) {
+  return new RegExp(`^export\\s+(?:declare\\s+)?${prefix}\\s+${name}(?:[^\\n{]*)\\{[\\s\\S]*?^\\}`, "gm");
+}
+function linePattern(prefix, name) {
+  return new RegExp(`^export\\s+(?:declare\\s+)?${prefix}\\s+${name}[^;]*;`, "gm");
+}
+function extractDeclaration(dts, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const declarations = [
+    ...collectMatches(dts, blockPattern("(?:abstract\\s+)?class", escaped)),
+    ...collectMatches(dts, blockPattern("interface", escaped)),
+    ...collectMatches(dts, blockPattern("(?:const\\s+)?enum", escaped)),
+    ...collectMatches(dts, linePattern("function", escaped)),
+    ...collectMatches(dts, linePattern("type", escaped)),
+    ...collectMatches(dts, linePattern("const", escaped))
+  ];
+  const unique = [...new Set(declarations)];
+  if (unique.length === 0) {
+    throw new Error(`Declaration not found: "${name}"`);
+  }
+  return unique.join("\n\n");
+}
+
+// src/lib/compareVersions.ts
+function compareTocs(oldMd, newMd) {
+  const oldEntries = extractToc(oldMd);
+  const newEntries = extractToc(newMd);
+  const oldPaths = new Set(oldEntries.map((e) => e.path));
+  const newPaths = new Set(newEntries.map((e) => e.path));
+  return {
+    added: newEntries.filter((e) => !oldPaths.has(e.path)),
+    removed: oldEntries.filter((e) => !newPaths.has(e.path)),
+    unchanged: newEntries.filter((e) => oldPaths.has(e.path))
+  };
+}
+
+// src/lib/mincer/cache.ts
+var MINCER_CACHE_VERSION = 9;
+function mincerCacheFile() {
+  return "mincer-findings.json";
+}
+function serializeMincerCache(findings) {
+  const serialized = {
+    findings,
+    version: MINCER_CACHE_VERSION
+  };
+  return JSON.stringify(serialized);
+}
+function deserializeMincerCache(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (parsed.version !== MINCER_CACHE_VERSION) {
+    return null;
+  }
+  return parsed.findings;
+}
+async function readCachedFindings(pkg, version) {
+  const raw = await readCached(pkg, version, mincerCacheFile());
+  if (raw === null) {
+    return null;
+  }
+  return deserializeMincerCache(raw);
+}
+async function writeCachedFindings(pkg, version, findings) {
+  await writeCache(pkg, version, mincerCacheFile(), serializeMincerCache(findings));
+}
+
+// src/lib/mincer/profiles.ts
+var PROFILES = {
+  traps: {
+    defaultTitle: "Potential trap or caveat",
+    kind: "traps",
+    mergeWindowLines: 1,
+    rules: [
+      { confidence: "high", detector: "trap.warning", kind: "traps", pattern: /\bwarning(?:s)?\b/i, severity: "warning", title: "Warning noted in documentation" },
+      { confidence: "high", detector: "trap.important", kind: "traps", pattern: /\b(?:important|caveat(?:s)?|important limitation(?:s)?|known limitation(?:s)?)\b/i, severity: "warning", title: "Important caveat noted in documentation" },
+      { confidence: "high", detector: "trap.operational_risk", kind: "traps", pattern: /\b(?:may fail|less robust|not thread-safe|not safe for concurrent access|modif(?:y|ies) [^.]* globally|only enable if|context leaks?|context leak|monkey-patching|monkey patching|keep an eye on|crippling bugs?|race conditions? (?:can|may|might|could|will)|risk of race conditions?)\b/i, severity: "warning", title: "Operational risk noted in documentation" },
+      { confidence: "high", detector: "trap.do_not", kind: "traps", pattern: /\bdo not (?:use|call|pass|mutate|rely|assume|expect|forget|mix)\b/i, severity: "warning", title: "Explicit do-not guidance detected" },
+      { confidence: "medium", detector: "trap.avoid", kind: "traps", pattern: /\bavoid(?: using| calling)?\b/i, severity: "warning", title: "Avoidance guidance detected" },
+      { confidence: "medium", detector: "trap.careful", kind: "traps", pattern: /\b(?:be careful|careful when|careful with)\b/i, severity: "warning", title: "Careful-use guidance detected" },
+      { confidence: "medium", detector: "trap.pitfall", kind: "traps", pattern: /\bpitfall(?:s)?\b/i, severity: "warning", title: "Pitfall detected in documentation" },
+      { confidence: "medium", detector: "trap.gotcha", kind: "traps", pattern: /\bgotcha(?:s)?\b/i, severity: "warning", title: "Gotcha detected in documentation" }
+    ],
+    sectionSignalPattern: /(?:^|\/)(?:warnings?|caveats?|gotchas?|pitfalls?|important|limitations?)(?:$|\/)/i
+  },
+  performance: {
+    defaultTitle: "Performance-sensitive behavior",
+    kind: "performance",
+    mergeWindowLines: 1,
+    rules: [
+      { confidence: "high", detector: "performance.big_o", kind: "performance", pattern: /\bO\([^\n]+\)/, severity: "warning", title: "Algorithmic complexity mentioned" },
+      { confidence: "high", detector: "performance.expensive", kind: "performance", pattern: /\bexpensive\b/i, severity: "warning", title: "Expensive operation noted" },
+      { confidence: "medium", detector: "performance.performance", kind: "performance", pattern: /\bperformance\b/i, severity: "info", title: "Performance-sensitive behavior noted" },
+      { confidence: "medium", detector: "performance.slow", kind: "performance", pattern: /\bslow(?:er|ly)?\b/i, severity: "info", title: "Slow behavior noted" },
+      { confidence: "medium", detector: "performance.memory", kind: "performance", pattern: /\bmemory(?: usage| overhead| leak)?\b/i, severity: "info", title: "Memory behavior noted" },
+      { confidence: "medium", detector: "performance.cache", kind: "performance", pattern: /\bcach(?:e|ed|ing)\b/i, severity: "info", title: "Cache-related behavior noted" },
+      { confidence: "medium", detector: "performance.hot_path", kind: "performance", pattern: /\bhot path\b/i, severity: "warning", title: "Hot path behavior noted" }
+    ],
+    sectionSignalPattern: /(?:^|\/)(?:performance|complexity|optimization|optimizations|memory|cache|caching|hot path)(?:$|\/)/i
+  },
+  deprecations: {
+    defaultTitle: "Deprecation or replacement guidance",
+    kind: "deprecations",
+    mergeWindowLines: 2,
+    rules: [
+      { confidence: "high", detector: "deprecation.deprecated", kind: "deprecations", pattern: /\bdeprecated\b/i, severity: "warning", title: "Deprecated behavior or API noted" },
+      { confidence: "high", detector: "deprecation.use_instead", kind: "deprecations", pattern: /\b(?:deprecated|legacy|obsolete|removed)\b.+\buse\b.+\binstead\b|\buse\b.+\binstead\b.+\b(?:deprecated|legacy|obsolete|removed)\b/i, severity: "warning", title: "Replacement guidance detected" },
+      { confidence: "high", detector: "deprecation.removed", kind: "deprecations", pattern: /\b(?:will be removed|has been removed|was removed in|removed in v?\d|removed from (?:the )?(?:api|public api|surface)|deprecated and removed|no longer available|no longer supported)\b/i, severity: "warning", title: "Removal noted in documentation" },
+      { confidence: "medium", detector: "deprecation.legacy", kind: "deprecations", pattern: /\blegacy\b/i, severity: "warning", title: "Legacy status noted" },
+      { confidence: "medium", detector: "deprecation.obsolete", kind: "deprecations", pattern: /\bobsolete\b/i, severity: "warning", title: "Obsolete behavior or API noted" }
+    ],
+    sectionSignalPattern: /(?:^|\/)(?:deprecated|deprecations?|legacy|obsolete|migration|migrating|upgrade|upgrading|breaking changes?)(?:$|\/)/i
+  },
+  constraints: {
+    defaultTitle: "Operational constraint",
+    kind: "constraints",
+    mergeWindowLines: 1,
+    rules: [
+      { confidence: "high", detector: "constraint.requires", kind: "constraints", pattern: /\b(?:requires?|required)\b/i, severity: "info", title: "Required precondition noted" },
+      { confidence: "high", detector: "constraint.only_works", kind: "constraints", pattern: /\bonly works\b/i, severity: "warning", title: "Limited support constraint detected" },
+      { confidence: "high", detector: "constraint.not_supported", kind: "constraints", pattern: /\bnot supported\b/i, severity: "warning", title: "Unsupported scenario detected" },
+      { confidence: "high", detector: "constraint.must_be_called", kind: "constraints", pattern: /\bmust be called\b/i, severity: "warning", title: "Required call ordering detected" },
+      { confidence: "medium", detector: "constraint.before_use", kind: "constraints", pattern: /\bbefore (?:using|calling|invoking|initializing|setup|setup is complete)\b/i, severity: "info", title: "Before-ordering constraint noted" },
+      { confidence: "medium", detector: "constraint.after_setup", kind: "constraints", pattern: /\bafter (?:setup|initialization|calling|mounting|creation)\b/i, severity: "info", title: "After-ordering constraint noted" }
+    ],
+    sectionSignalPattern: /(?:^|\/)(?:requirements?|constraints?|supported|support|compatibility|prerequisites?|setup|limitations?)(?:$|\/)/i
+  }
+};
+var PROFILE_ORDER = ["traps", "performance", "deprecations", "constraints"];
+function getProfile(kind) {
+  return PROFILES[kind];
+}
+function listProfiles() {
+  return PROFILE_ORDER.map((kind) => PROFILES[kind]);
+}
+function hasSectionSignal(kind, path) {
+  return getProfile(kind).sectionSignalPattern.test(path);
+}
+
+// src/lib/mincer/detectors.ts
+function isFenceLine(line) {
+  return /^\s*(?:```|~~~)/.test(line);
+}
+function isCodeLikeLine(trimmed) {
+  return /^['"`][^'"`]+['"`]\s*:/.test(trimmed) || /^(?:export|import|const|let|var|function|class|interface|type)\b/.test(trimmed) || /=>/.test(trimmed) || /^[A-Za-z_$][\w$]*\s*:\s*(?:true|false|null|undefined|['"`[{\d-])/.test(trimmed);
+}
+function collectRuleHits(chunk, kind) {
+  const { rules } = getProfile(kind);
+  let insideCodeFence = false;
+  return chunk.content.split("\n").flatMap((line, index) => {
+    if (isFenceLine(line)) {
+      insideCodeFence = !insideCodeFence;
+      return [];
+    }
+    const trimmed = line.trim();
+    if (insideCodeFence || trimmed.length === 0 || isCodeLikeLine(trimmed)) {
+      return [];
+    }
+    return rules.filter((rule) => rule.pattern.test(line)).map((rule) => ({
+      detector: rule.detector,
+      kind: rule.kind,
+      severity: rule.severity,
+      confidence: rule.confidence,
+      title: rule.title,
+      sourceId: chunk.sourceId,
+      sourceKind: chunk.sourceKind,
+      sourceTitle: chunk.sourceTitle,
+      origin: chunk.origin,
+      path: chunk.path,
+      startLine: chunk.startLine + index,
+      endLine: chunk.startLine + index,
+      snippet: trimmed
+    }));
+  });
+}
+function detectFindingsByKind(chunk, kind) {
+  return collectRuleHits(chunk, kind).sort((left, right) => {
+    if (left.startLine !== right.startLine) {
+      return left.startLine - right.startLine;
+    }
+    return left.detector.localeCompare(right.detector);
+  });
+}
+function detectFindings(chunk) {
+  return listProfiles().flatMap((profile) => detectFindingsByKind(chunk, profile.kind)).sort((left, right) => {
+    if (left.startLine !== right.startLine) {
+      return left.startLine - right.startLine;
+    }
+    if (left.kind !== right.kind) {
+      return left.kind.localeCompare(right.kind);
+    }
+    return left.detector.localeCompare(right.detector);
+  });
+}
+
+// src/lib/mincer/extractFindings.ts
+var CONFIDENCE_RANK = {
+  high: 3,
+  medium: 2,
+  low: 1
+};
+var SEVERITY_RANK = {
+  critical: 3,
+  warning: 2,
+  info: 1
+};
+function mergeTitleFromDetectors(detectors) {
+  const [first] = detectors;
+  if (first === void 0) {
+    return "Documentation finding";
+  }
+  const prefix = first.split(".", 1)[0];
+  if (prefix === "trap") {
+    return getProfile("traps").defaultTitle;
+  }
+  if (prefix === "performance") {
+    return getProfile("performance").defaultTitle;
+  }
+  if (prefix === "deprecation") {
+    return getProfile("deprecations").defaultTitle;
+  }
+  if (prefix === "constraint") {
+    return getProfile("constraints").defaultTitle;
+  }
+  return "Documentation finding";
+}
+function buildSummary(hit) {
+  return hit.snippet;
+}
+function compareDetectors(left, right) {
+  return left.localeCompare(right);
+}
+function normalizeSnippet(snippet) {
+  return snippet.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+function promoteConfidence(confidence, kind, path) {
+  if (!hasSectionSignal(kind, path)) {
+    return confidence;
+  }
+  if (confidence === "low") {
+    return "medium";
+  }
+  return "high";
+}
+function deriveTitle(kind, fallbackTitle, evidence) {
+  const detectors = [...new Set(evidence.flatMap((item) => item.detectors))].sort(compareDetectors);
+  if (detectors.length <= 1) {
+    return fallbackTitle;
+  }
+  return getProfile(kind).defaultTitle;
+}
+function sortEvidence(evidence) {
+  return [...evidence].sort((left, right) => {
+    if (left.origin !== right.origin) {
+      return left.origin.localeCompare(right.origin);
+    }
+    if (left.path !== right.path) {
+      return left.path.localeCompare(right.path);
+    }
+    if (left.startLine !== right.startLine) {
+      return left.startLine - right.startLine;
+    }
+    if (left.endLine !== right.endLine) {
+      return left.endLine - right.endLine;
+    }
+    return left.detectors.join(",").localeCompare(right.detectors.join(","));
+  });
+}
+function mergeEvidence(existing, hit) {
+  const match = existing.find((item) => item.origin === hit.origin && item.path === hit.path && item.startLine === hit.startLine && item.endLine === hit.endLine && item.snippet === hit.snippet);
+  if (match === void 0) {
+    return sortEvidence([
+      ...existing,
+      {
+        sourceId: hit.sourceId,
+        sourceKind: hit.sourceKind,
+        sourceTitle: hit.sourceTitle,
+        origin: hit.origin,
+        path: hit.path,
+        startLine: hit.startLine,
+        endLine: hit.endLine,
+        snippet: hit.snippet,
+        detectors: [hit.detector]
+      }
+    ]);
+  }
+  match.detectors = [.../* @__PURE__ */ new Set([...match.detectors, hit.detector])].sort(compareDetectors);
+  return sortEvidence(existing);
+}
+function isSameFindingWindow(left, right) {
+  if (left.kind !== right.kind || left.origin !== right.origin || left.path !== right.path) {
+    return false;
+  }
+  const profile = getProfile(left.kind);
+  const distance = Math.abs(left.startLine - right.startLine);
+  if (distance === 0) {
+    return true;
+  }
+  if (distance > profile.mergeWindowLines) {
+    return false;
+  }
+  if (normalizeSnippet(left.snippet) === normalizeSnippet(right.snippet)) {
+    return true;
+  }
+  return left.kind === "deprecations";
+}
+function selectHigherSeverity(left, right) {
+  return SEVERITY_RANK[left] >= SEVERITY_RANK[right] ? left : right;
+}
+function selectHigherConfidence(left, right) {
+  return CONFIDENCE_RANK[left] >= CONFIDENCE_RANK[right] ? left : right;
+}
+function normalizeHits(hits) {
+  const sortedHits = [...hits].sort((left, right) => {
+    if (left.origin !== right.origin) {
+      return left.origin.localeCompare(right.origin);
+    }
+    if (left.path !== right.path) {
+      return left.path.localeCompare(right.path);
+    }
+    if (left.startLine !== right.startLine) {
+      return left.startLine - right.startLine;
+    }
+    if (left.kind !== right.kind) {
+      return left.kind.localeCompare(right.kind);
+    }
+    return left.detector.localeCompare(right.detector);
+  });
+  const drafts = [];
+  for (const hit of sortedHits) {
+    const existing = drafts.find((draft) => isSameFindingWindow(draft.anchor, hit));
+    if (existing === void 0) {
+      drafts.push({
+        anchor: hit,
+        finding: {
+          confidence: promoteConfidence(hit.confidence, hit.kind, hit.path),
+          evidence: [{
+            sourceId: hit.sourceId,
+            sourceKind: hit.sourceKind,
+            sourceTitle: hit.sourceTitle,
+            origin: hit.origin,
+            path: hit.path,
+            startLine: hit.startLine,
+            endLine: hit.endLine,
+            snippet: hit.snippet,
+            detectors: [hit.detector]
+          }],
+          kind: hit.kind,
+          severity: hit.severity,
+          summary: buildSummary(hit),
+          title: deriveTitle(hit.kind, hit.title, [{
+            sourceId: hit.sourceId,
+            sourceKind: hit.sourceKind,
+            sourceTitle: hit.sourceTitle,
+            origin: hit.origin,
+            path: hit.path,
+            startLine: hit.startLine,
+            endLine: hit.endLine,
+            snippet: hit.snippet,
+            detectors: [hit.detector]
+          }])
+        }
+      });
+      continue;
+    }
+    existing.finding.severity = selectHigherSeverity(existing.finding.severity, hit.severity);
+    existing.finding.confidence = selectHigherConfidence(existing.finding.confidence, promoteConfidence(hit.confidence, hit.kind, hit.path));
+    existing.finding.evidence = mergeEvidence(existing.finding.evidence, hit);
+    const mergedDetectors = existing.finding.evidence.flatMap((item) => item.detectors).sort(compareDetectors);
+    existing.finding.title = mergedDetectors.length <= 1 ? hit.title : mergeTitleFromDetectors(mergedDetectors);
+  }
+  return drafts.map((draft) => ({
+    ...draft.finding,
+    evidence: sortEvidence(draft.finding.evidence)
+  }));
+}
+function extractFindingsFromHits(pkg, version, hits) {
+  return normalizeHits(hits).map((finding) => ({
+    package: pkg,
+    version,
+    kind: finding.kind,
+    severity: finding.severity,
+    confidence: finding.confidence,
+    title: finding.title,
+    summary: finding.summary,
+    evidence: finding.evidence
+  }));
+}
+function extractFindings(pkg, version, chunks) {
+  return extractFindingsFromHits(
+    pkg,
+    version,
+    chunks.flatMap((chunk) => detectFindings(chunk))
+  );
+}
+
+// src/lib/mincer/rankFindings.ts
+var CONFIDENCE_RANK2 = {
+  high: 3,
+  medium: 2,
+  low: 1
+};
+var SEVERITY_RANK2 = {
+  critical: 3,
+  warning: 2,
+  info: 1
+};
+function sectionSignalScore(finding) {
+  return finding.evidence.some((evidence) => hasSectionSignal(finding.kind, evidence.path)) ? 1 : 0;
+}
+function isHeadingOnlySnippet(snippet) {
+  return /^#{1,6}\s+/.test(snippet) || /^>\s*\[!(?:WARNING|IMPORTANT)\]\s*$/i.test(snippet) || /^\*\*Important Note:?\*\*$/i.test(snippet) || /^Important notes? about .+:$/i.test(snippet) || /^Important notes?$/i.test(snippet);
+}
+function headingOnlyScore(finding) {
+  return finding.evidence.every((evidence) => isHeadingOnlySnippet(evidence.snippet)) ? 1 : 0;
+}
+function operationalRiskScore(finding) {
+  return finding.evidence.some((evidence) => evidence.detectors.includes("trap.operational_risk")) ? 1 : 0;
+}
+function rankFindings(findings) {
+  return [...findings].sort((left, right) => {
+    if (SEVERITY_RANK2[right.severity] !== SEVERITY_RANK2[left.severity]) {
+      return SEVERITY_RANK2[right.severity] - SEVERITY_RANK2[left.severity];
+    }
+    if (CONFIDENCE_RANK2[right.confidence] !== CONFIDENCE_RANK2[left.confidence]) {
+      return CONFIDENCE_RANK2[right.confidence] - CONFIDENCE_RANK2[left.confidence];
+    }
+    if (operationalRiskScore(right) !== operationalRiskScore(left)) {
+      return operationalRiskScore(right) - operationalRiskScore(left);
+    }
+    if (headingOnlyScore(left) !== headingOnlyScore(right)) {
+      return headingOnlyScore(left) - headingOnlyScore(right);
+    }
+    if (sectionSignalScore(right) !== sectionSignalScore(left)) {
+      return sectionSignalScore(right) - sectionSignalScore(left);
+    }
+    const leftEvidence = left.evidence[0];
+    const rightEvidence = right.evidence[0];
+    if (leftEvidence !== void 0 && rightEvidence !== void 0) {
+      if (leftEvidence.origin !== rightEvidence.origin) {
+        return leftEvidence.origin.localeCompare(rightEvidence.origin);
+      }
+      if (leftEvidence.path !== rightEvidence.path) {
+        return leftEvidence.path.localeCompare(rightEvidence.path);
+      }
+      if (leftEvidence.startLine !== rightEvidence.startLine) {
+        return leftEvidence.startLine - rightEvidence.startLine;
+      }
+    }
+    if (left.kind !== right.kind) {
+      return left.kind.localeCompare(right.kind);
+    }
+    return left.title.localeCompare(right.title);
+  });
+}
+
+// src/lib/mincer/analyzeFindings.ts
+function selectFindingsByKind(findings, kind) {
+  return findings.filter((finding) => finding.kind === kind);
+}
+async function analyzeFindings(pkg, version) {
+  const canCache = isExactVersion(version);
+  if (canCache) {
+    const cached = await readCachedFindings(pkg, version);
+    if (cached !== null) {
+      return cached;
+    }
+  }
+  const sources = await discoverSources(pkg, version);
+  const chunks = sources.flatMap((source) => extractMarkdownChunks(source));
+  const findings = rankFindings(extractFindings(pkg, version, chunks));
+  if (canCache) {
+    await writeCachedFindings(pkg, version, findings);
+  }
+  return findings;
+}
+async function analyzeFindingsByKind(pkg, version, kind, limit = 10) {
+  const findings = await analyzeFindings(pkg, version);
+  return {
+    package: pkg,
+    version,
+    kind,
+    findings: selectFindingsByKind(findings, kind).slice(0, Math.max(1, limit))
+  };
+}
+
+// src/lib/mincer/getConstraints.ts
+async function getConstraints(pkg, version, limit = 10) {
+  return analyzeFindingsByKind(pkg, version, "constraints", limit);
+}
+
+// src/lib/mincer/getDeprecations.ts
+async function getDeprecations(pkg, version, limit = 10) {
+  return analyzeFindingsByKind(pkg, version, "deprecations", limit);
+}
+
+// src/lib/mincer/getPerformanceNotes.ts
+async function getPerformanceNotes(pkg, version, limit = 10) {
+  return analyzeFindingsByKind(pkg, version, "performance", limit);
+}
+
+// src/lib/mincer/getTraps.ts
+async function getTraps(pkg, version, limit = 10) {
+  return analyzeFindingsByKind(pkg, version, "traps", limit);
+}
+
+// src/server.ts
+function createServer() {
+  const server = new McpServer({
+    name: "soup-chop",
+    version: "1.0.0"
+  });
+  server.registerResource(
+    "capabilities",
+    "soup-chop://capabilities",
+    {
+      title: "soup-chop capabilities",
+      description: "Overview of the soup-chop MCP surface and the recommended tool-first workflow.",
+      mimeType: "text/plain"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "soup-chop://capabilities",
+          text: [
+            "soup-chop is a tool-first MCP server for version-accurate NPM documentation.",
+            "",
+            "Main tools:",
+            "- search_docs: ranked cross-document discovery over README.md, doc/, docs/, and a narrow top-level markdown allowlist.",
+            "- get_toc: package-wide TOC when origin is omitted, or single-document TOC when origin is provided.",
+            "- get_topic: fetch a section or whole document via topic_id, or via path plus optional origin.",
+            "- get_traps / get_deprecations / get_constraints / get_performance_notes: evidence-backed findings mined deterministically from markdown docs.",
+            "- get_api_ref / get_declaration: inspect published TypeScript declarations.",
+            "- compare_versions: diff documentation structure between two package versions.",
+            "",
+            "Recommended flow:",
+            "1. Call search_docs when you do not know the exact section yet.",
+            "2. Use the returned topicId directly with get_topic, or inspect the document with get_toc(origin).",
+            "3. Use get_api_ref / get_declaration for exact type-level answers.",
+            "",
+            "Current search behavior: lexical ranking is optimized for English tokenization today."
+          ].join("\n")
+        }
+      ]
+    })
+  );
+  server.registerTool(
+    "get_toc",
+    {
+      description: "Returns a structured table of contents for an NPM package markdown corpus or a specific markdown doc. Omit origin for a package-wide multi-document TOC, or pass origin to inspect one non-README doc directly.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")'),
+        origin: z.string().optional().describe('Optional markdown source path from search_docs (e.g., "docs/faq.md" or "CHANGELOG.md"). Omit it for a package-wide TOC.')
+      }
+    },
+    async ({ package: pkg, version, origin }) => {
+      const response = origin ? {
+        package: pkg,
+        version,
+        origin,
+        entries: buildDocumentTocEntries(await fetchMarkdownFile(pkg, version, origin), origin)
+      } : {
+        package: pkg,
+        version,
+        entries: buildPackageTocEntries(await discoverSources(pkg, version))
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(response, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_topic",
+    {
+      description: "Returns the raw markdown content for a specific section of an NPM package markdown doc. Use get_toc or search_docs first to discover the exact section path, and pass origin or topic_id when the section comes from a non-README doc.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")'),
+        path: z.string().optional().describe('Section path from get_toc (e.g., "Installation" or "API/Methods/parse")'),
+        origin: z.string().optional().describe('Optional markdown source path from search_docs (e.g., "docs/faq.md" or "API.md"). Defaults to README.md'),
+        topic_id: z.string().optional().describe('Stable topic identifier from search_docs or aggregated get_toc (e.g., "README.md#Installation" or "CHANGELOG.md").')
+      }
+    },
+    async ({ package: pkg, version, path, origin, topic_id }) => {
+      const selection = resolveTopicSelection(path, origin, topic_id);
+      const markdown = await fetchMarkdownFile(pkg, version, selection.origin);
+      const content = getTopic(markdown, selection.path, selection.origin);
+      return {
+        content: [
+          {
+            type: "text",
+            text: content
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "search_docs",
+    {
+      description: "Searches README and package-local markdown docs for an NPM package using local lexical ranking. Use this when you have keywords or a natural-language question but do not know the exact section path yet.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")'),
+        query: z.string().describe('Keywords or natural-language search query (e.g., "track state changes")'),
+        limit: z.number().int().min(1).max(20).optional().describe("Maximum number of ranked results to return (default: 5)")
+      }
+    },
+    async ({ package: pkg, version, query, limit }) => {
+      const results = await searchDocs(pkg, version, query, limit ?? 5);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_traps",
+    {
+      description: "Returns compact, evidence-backed trap findings extracted deterministically from package markdown docs. Use this to surface warnings, caveats, and operational gotchas with source lines and origin paths.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")'),
+        limit: z.number().int().min(1).max(50).optional().describe("Maximum number of ranked trap findings to return (default: 10)")
+      }
+    },
+    async ({ package: pkg, version, limit }) => {
+      const results = await getTraps(pkg, version, limit ?? 10);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_deprecations",
+    {
+      description: "Returns evidence-backed deprecation findings extracted deterministically from package markdown docs. Use this to surface deprecated APIs, legacy guidance, removals, and suggested replacements.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")'),
+        limit: z.number().int().min(1).max(50).optional().describe("Maximum number of ranked deprecation findings to return (default: 10)")
+      }
+    },
+    async ({ package: pkg, version, limit }) => {
+      const results = await getDeprecations(pkg, version, limit ?? 10);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_constraints",
+    {
+      description: "Returns evidence-backed operational constraints extracted deterministically from package markdown docs. Use this to surface prerequisites, unsupported scenarios, and ordering requirements.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")'),
+        limit: z.number().int().min(1).max(50).optional().describe("Maximum number of ranked constraint findings to return (default: 10)")
+      }
+    },
+    async ({ package: pkg, version, limit }) => {
+      const results = await getConstraints(pkg, version, limit ?? 10);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_performance_notes",
+    {
+      description: "Returns evidence-backed performance findings extracted deterministically from package markdown docs. Use this to surface complexity notes, expensive operations, cache behavior, and hot paths.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")'),
+        limit: z.number().int().min(1).max(50).optional().describe("Maximum number of ranked performance findings to return (default: 10)")
+      }
+    },
+    async ({ package: pkg, version, limit }) => {
+      const results = await getPerformanceNotes(pkg, version, limit ?? 10);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(results, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_api_ref",
+    {
+      description: "Returns a compact TypeScript API index grouped by identifier name. Each entry lists the compile-time and runtime kinds associated with that name.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")')
+      }
+    },
+    async ({ package: pkg, version }) => {
+      const dts = await fetchDts(pkg, version);
+      const apiRef = extractApiRef(dts, pkg, version);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(apiRef, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_declaration",
+    {
+      description: "Returns the explicit TypeScript declaration text for a given exported identifier name. Use get_api_ref first to discover names and kinds, then call this for the full declaration body.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        version: z.string().describe('NPM version string: exact version or published dist-tag (e.g., "3.23.8", "latest")'),
+        name: z.string().describe('Exported identifier name (e.g., "ZodSchema", "parse", "ZodTypeAny")')
+      }
+    },
+    async ({ package: pkg, version, name }) => {
+      const dts = await fetchDts(pkg, version);
+      const declaration = extractDeclaration(dts, name);
+      return {
+        content: [
+          {
+            type: "text",
+            text: declaration
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "compare_versions",
+    {
+      description: "Returns a structural diff of documentation headings between two versions of an NPM package. Shows which sections were added, removed, or unchanged \u2014 useful for spotting breaking changes.",
+      inputSchema: {
+        package: z.string().describe('NPM package name (e.g., "zod", "express")'),
+        v_old: z.string().describe('Older version to compare from (e.g., "3.22.0")'),
+        v_new: z.string().describe('Newer version to compare to (e.g., "3.23.8")')
+      }
+    },
+    async ({ package: pkg, v_old, v_new }) => {
+      const [oldReadme, newReadme] = await Promise.all([
+        fetchReadme(pkg, v_old),
+        fetchReadme(pkg, v_new)
+      ]);
+      const diff = compareTocs(oldReadme, newReadme);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ package: pkg, v_old, v_new, diff }, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  return server;
+}
+async function runStdioServer() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("[soup-chop] MCP server running on stdio \u2014 connect your client via stdio transport\n");
+}
+
+// src/index.ts
+function parseClientsArgs(args) {
+  let json = false;
+  for (const flag of args) {
+    if (flag === "--json") {
+      json = true;
+      continue;
+    }
+    throw new Error(`Unknown clients option: "${flag}"
+
+Usage: soup-chop clients [--json]`);
+  }
+  return { json };
+}
+function usage() {
+  const supported = getSupportedAutoConfigClientIds().join(", ");
+  return [
+    "soup-chop <command>",
+    "",
+    "Commands:",
+    "  serve                     Run the MCP server over stdio",
+    "  configure <client> [--project|--global] [--dry-run|--print] [--local-build]",
+    "                            Write soup-chop into a supported client config",
+    "  clients [--json]          List documented clients and auto-config support",
+    "  help                      Show this help message",
+    "",
+    `Auto-config clients: ${supported}`
+  ].join("\n");
+}
+function printClients(json) {
+  const entries = listClientEntries();
+  if (json) {
+    process.stdout.write(`${JSON.stringify(entries, null, 2)}
+`);
+    return;
+  }
+  const lines = entries.map((entry) => {
+    const suffix = entry.mode === "implemented elsewhere" ? " (not auto-configurable on this platform)" : "";
+    return `- ${entry.name} [${entry.mode}] \u2014 ${entry.displayPath}${suffix}`;
+  });
+  process.stdout.write(`${lines.join("\n")}
+`);
+}
+async function main() {
+  const [command = "serve", ...rest] = process.argv.slice(2);
+  if (command === "serve") {
+    await runStdioServer();
+    return;
+  }
+  if (command === "configure") {
+    const { client, scope, localBuild, outputMode } = parseConfigureArgs(rest, getSupportedAutoConfigClientIds());
+    if (outputMode === "print") {
+      const resolvedClient = resolveClient(client);
+      const snippet = buildConfigSnippet(resolvedClient, { scope, localBuild });
+      process.stdout.write(`${JSON.stringify(snippet, null, 2)}
+`);
+      return;
+    }
+    if (outputMode === "dry-run") {
+      const prepared = await prepareClientConfig(client, { scope, localBuild });
+      process.stdout.write(`Would configure ${prepared.client.name} at ${prepared.path}
+`);
+      process.stdout.write(prepared.content);
+      return;
+    }
+    const result = await configureClient(client, { scope, localBuild });
+    process.stdout.write(`Configured ${result.client.name} at ${result.path}
+`);
+    return;
+  }
+  if (command === "clients") {
+    const { json } = parseClientsArgs(rest);
+    printClients(json);
+    return;
+  }
+  if (command === "help" || command === "--help" || command === "-h") {
+    process.stdout.write(`${usage()}
+`);
+    return;
+  }
+  throw new Error(`Unknown command: "${command}"
+
+${usage()}`);
+}
+await main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}
+`);
+  process.exitCode = 1;
+});