codebase-snapshot 0.9.1 → 0.9.4

package/dist/chunk-EWZYK3VX.js

@@ -0,0 +1,2577 @@
+import { GENERATOR_VERSION, MIN_MAX_PART_BYTES, SCHEMA_VERSION, GENERATOR_NAME, ARTIFACT_NAMES, PRESETS, generateSnapshot, validateSnapshot, explainPath, renderExplainText, describeManifestShapeProblem, loadConfigFileDetailed, parseByteSize, resolveConfig } from './chunk-FCWD4LY7.js';
+import * as fs from 'fs';
+import * as path2 from 'path';
+
+// src/mcp/protocol.ts
+var LEGACY_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18"];
+var MODERN_PROTOCOL_VERSIONS = ["2026-07-28"];
+var SUPPORTED_PROTOCOL_VERSIONS = [
+  ...MODERN_PROTOCOL_VERSIONS,
+  ...LEGACY_PROTOCOL_VERSIONS
+];
+var DEFAULT_LEGACY_PROTOCOL_VERSION = LEGACY_PROTOCOL_VERSIONS[0];
+var ERROR_CODES = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+  unsupportedProtocolVersion: -32022
+};
+var METHOD = {
+  initialize: "initialize",
+  initialized: "notifications/initialized",
+  discover: "server/discover",
+  ping: "ping",
+  toolsList: "tools/list",
+  toolsCall: "tools/call",
+  resourcesList: "resources/list",
+  resourcesRead: "resources/read",
+  resourceTemplatesList: "resources/templates/list",
+  promptsList: "prompts/list",
+  promptsGet: "prompts/get",
+  cancelled: "notifications/cancelled"
+};
+var META_KEYS = {
+  protocolVersion: "io.modelcontextprotocol/protocolVersion",
+  clientCapabilities: "io.modelcontextprotocol/clientCapabilities",
+  clientInfo: "io.modelcontextprotocol/clientInfo",
+  serverInfo: "io.modelcontextprotocol/serverInfo"};
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function serverInfoMeta(info) {
+  const value = { name: info.name, version: info.version };
+  if (info.title) value.title = info.title;
+  return { [META_KEYS.serverInfo]: value };
+}
+function successResponse(id, result, modern, info) {
+  if (!modern) return { jsonrpc: "2.0", id, result };
+  const withMeta = {
+    ...result,
+    resultType: "complete",
+    _meta: { ...isJsonObject(result._meta) ? result._meta : {}, ...serverInfoMeta(info) }
+  };
+  return { jsonrpc: "2.0", id, result: withMeta };
+}
+function errorResponse(id, code, message, data) {
+  const error = { code, message };
+  if (data !== void 0) error.data = data;
+  return { jsonrpc: "2.0", id, error };
+}
+
+// src/mcp/era.ts
+function createSession() {
+  return { era: null, protocolVersion: null, ready: false };
+}
+function isLegacyVersion(version) {
+  return LEGACY_PROTOCOL_VERSIONS.includes(version);
+}
+function isModernVersion(version) {
+  return MODERN_PROTOCOL_VERSIONS.includes(version);
+}
+function inspectModernMeta(params) {
+  const raw = params?._meta;
+  if (!isJsonObject(raw)) return { kind: "absent" };
+  const version = raw[META_KEYS.protocolVersion];
+  if (typeof version !== "string" || version.length === 0) {
+    return { kind: "incomplete", missing: META_KEYS.protocolVersion };
+  }
+  const capabilities2 = raw[META_KEYS.clientCapabilities];
+  if (!isJsonObject(capabilities2)) {
+    return { kind: "incomplete", missing: META_KEYS.clientCapabilities };
+  }
+  const info = raw[META_KEYS.clientInfo];
+  return {
+    kind: "present",
+    meta: {
+      version,
+      clientCapabilities: capabilities2,
+      clientInfo: isJsonObject(info) ? info : null
+    }
+  };
+}
+function unsupportedVersionData(requested) {
+  return { requested, supported: [...SUPPORTED_PROTOCOL_VERSIONS] };
+}
+function classifyRequest(method, params, session) {
+  const inspection = inspectModernMeta(params);
+  if (session.era === "modern") {
+    if (inspection.kind === "absent") {
+      return {
+        kind: "error",
+        code: ERROR_CODES.invalidRequest,
+        message: `This request has no _meta. The modern era requires "${META_KEYS.protocolVersion}" and "${META_KEYS.clientCapabilities}" on every request.`
+      };
+    }
+    if (inspection.kind === "incomplete") {
+      return {
+        kind: "error",
+        code: ERROR_CODES.invalidParams,
+        message: `The request _meta is missing the required key "${inspection.missing}".`
+      };
+    }
+    if (!isModernVersion(inspection.meta.version)) {
+      return {
+        kind: "error",
+        code: ERROR_CODES.unsupportedProtocolVersion,
+        message: `Unsupported protocol version "${inspection.meta.version}".`,
+        data: unsupportedVersionData(inspection.meta.version)
+      };
+    }
+    return { kind: "era", era: "modern", version: inspection.meta.version };
+  }
+  if (session.era === "legacy") {
+    return { kind: "era", era: "legacy", version: session.protocolVersion };
+  }
+  if (method === METHOD.initialize) {
+    return { kind: "era", era: "legacy", version: null };
+  }
+  if (inspection.kind === "present") {
+    if (!isModernVersion(inspection.meta.version)) {
+      return {
+        kind: "error",
+        code: ERROR_CODES.unsupportedProtocolVersion,
+        message: `Unsupported protocol version "${inspection.meta.version}".`,
+        data: unsupportedVersionData(inspection.meta.version)
+      };
+    }
+    return { kind: "era", era: "modern", version: inspection.meta.version };
+  }
+  if (inspection.kind === "incomplete") {
+    return {
+      kind: "error",
+      code: ERROR_CODES.invalidParams,
+      message: `The request _meta is missing the required key "${inspection.missing}".`
+    };
+  }
+  if (method === METHOD.discover) {
+    return { kind: "era", era: "modern", version: MODERN_PROTOCOL_VERSIONS[0] };
+  }
+  return { kind: "era", era: "legacy", version: null };
+}
+function negotiateLegacyVersion(requested) {
+  if (typeof requested === "string" && isLegacyVersion(requested)) {
+    return { version: requested, matched: true };
+  }
+  return { version: DEFAULT_LEGACY_PROTOCOL_VERSION, matched: false };
+}
+
+// src/mcp/schema.ts
+function validateArguments(schema, value) {
+  if (value === void 0) value = {};
+  if (!isJsonObject(value)) return ["arguments must be a JSON object"];
+  const problems = [];
+  const known = new Set(Object.keys(schema.properties));
+  for (const key of Object.keys(value)) {
+    if (!known.has(key) && schema.additionalProperties !== true) {
+      const allowed = [...known].sort().join(", ");
+      problems.push(`unknown argument "${key}" (accepted: ${allowed || "none"})`);
+    }
+  }
+  for (const required of schema.required ?? []) {
+    if (value[required] === void 0) problems.push(`missing required argument "${required}"`);
+  }
+  for (const [key, propertySchema] of Object.entries(schema.properties)) {
+    const argument = value[key];
+    if (argument === void 0) continue;
+    problems.push(...checkValue(key, propertySchema, argument));
+  }
+  return problems;
+}
+function checkValue(path4, schema, value) {
+  if (schema.enum && !schema.enum.includes(value)) {
+    return [`"${path4}" must be one of: ${schema.enum.join(", ")}`];
+  }
+  switch (schema.type) {
+    case "string": {
+      if (typeof value !== "string") return [`"${path4}" must be a string`];
+      const problems = [];
+      if (schema.minLength !== void 0 && value.length < schema.minLength) {
+        problems.push(`"${path4}" must be at least ${schema.minLength} character(s)`);
+      }
+      if (schema.maxLength !== void 0 && value.length > schema.maxLength) {
+        problems.push(`"${path4}" must be at most ${schema.maxLength} character(s)`);
+      }
+      return problems;
+    }
+    case "number":
+    case "integer": {
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        return [`"${path4}" must be a number`];
+      }
+      if (schema.type === "integer" && !Number.isInteger(value)) {
+        return [`"${path4}" must be an integer`];
+      }
+      const problems = [];
+      if (schema.minimum !== void 0 && value < schema.minimum) {
+        problems.push(`"${path4}" must be >= ${schema.minimum}`);
+      }
+      if (schema.maximum !== void 0 && value > schema.maximum) {
+        problems.push(`"${path4}" must be <= ${schema.maximum}`);
+      }
+      return problems;
+    }
+    case "boolean":
+      return typeof value === "boolean" ? [] : [`"${path4}" must be a boolean`];
+    case "array": {
+      if (!Array.isArray(value)) return [`"${path4}" must be an array`];
+      if (!schema.items) return [];
+      const problems = [];
+      value.forEach((item, index) => {
+        problems.push(...checkValue(`${path4}[${index}]`, schema.items, item));
+      });
+      return problems;
+    }
+    case "object":
+      return isJsonObject(value) ? [] : [`"${path4}" must be an object`];
+    default:
+      return [];
+  }
+}
+function applyDefaults(schema, value) {
+  const out = { ...value };
+  for (const [key, propertySchema] of Object.entries(schema.properties)) {
+    if (out[key] === void 0 && propertySchema.default !== void 0) {
+      out[key] = propertySchema.default;
+    }
+  }
+  return out;
+}
+
+// src/mcp/server.ts
+function capabilities() {
+  return {
+    tools: { listChanged: false },
+    resources: { subscribe: false, listChanged: false },
+    prompts: { listChanged: false }
+  };
+}
+function requestIdOf(message) {
+  const raw = message.id;
+  return typeof raw === "string" || typeof raw === "number" ? raw : null;
+}
+function createMcpServer(options) {
+  const session = createSession();
+  const toolsByName = new Map(options.tools.map((tool) => [tool.name, tool]));
+  const promptsByName = new Map(options.prompts.map((prompt) => [prompt.name, prompt]));
+  const identity = () => ({
+    name: options.info.name,
+    title: options.info.title,
+    version: options.info.version,
+    websiteUrl: options.info.websiteUrl
+  });
+  const ok = (id, result, modern) => successResponse(id, result, modern, options.info);
+  function handleNotification(method) {
+    if (method === METHOD.initialized && session.era === "legacy") session.ready = true;
+  }
+  function initialize(id, params) {
+    const negotiation = negotiateLegacyVersion(params?.protocolVersion);
+    session.era = "legacy";
+    session.protocolVersion = negotiation.version;
+    session.ready = true;
+    options.context.log(
+      negotiation.matched ? `mcp: client initialized with protocol ${negotiation.version}` : `mcp: client asked for an unsupported version and was offered ${negotiation.version}`
+    );
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion: negotiation.version,
+        capabilities: capabilities(),
+        serverInfo: identity(),
+        instructions: options.instructions
+      }
+    };
+  }
+  function discover(id) {
+    session.era = "modern";
+    session.ready = true;
+    return ok(
+      id,
+      {
+        supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+        capabilities: capabilities(),
+        instructions: options.instructions,
+        // The capability set depends on which repository the server was started for, so the answer
+        // may be cached only by the client that asked, and not at all after this response.
+        cacheScope: "private",
+        ttlMs: 0
+      },
+      true
+    );
+  }
+  function listTools(id, modern) {
+    const tools = options.tools.map((tool) => ({
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      ...tool.outputSchema ? { outputSchema: tool.outputSchema } : {},
+      annotations: tool.annotations
+    }));
+    return ok(id, { tools }, modern);
+  }
+  async function callTool(id, modern, params) {
+    const name = params?.name;
+    if (typeof name !== "string") {
+      return errorResponse(id, ERROR_CODES.invalidParams, 'tools/call requires a "name" string.');
+    }
+    const tool = toolsByName.get(name);
+    if (!tool) {
+      const known = [...toolsByName.keys()].sort().join(", ");
+      return errorResponse(id, ERROR_CODES.invalidParams, `Unknown tool "${name}". Available: ${known}.`);
+    }
+    const rawArguments = params?.arguments ?? {};
+    if (!isJsonObject(rawArguments)) {
+      return errorResponse(id, ERROR_CODES.invalidParams, '"arguments" must be a JSON object.');
+    }
+    const problems = validateArguments(tool.inputSchema, rawArguments);
+    if (problems.length > 0) {
+      return ok(
+        id,
+        {
+          content: [{ type: "text", text: `Invalid arguments for ${tool.name}:
+- ${problems.join("\n- ")}` }],
+          isError: true
+        },
+        modern
+      );
+    }
+    const args = applyDefaults(tool.inputSchema, rawArguments);
+    let outcome;
+    try {
+      outcome = await tool.handler(args, options.context);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      options.context.log(`mcp: tool ${tool.name} failed: ${detail}`);
+      return ok(
+        id,
+        { content: [{ type: "text", text: `${tool.name} failed: ${detail}` }], isError: true },
+        modern
+      );
+    }
+    return ok(
+      id,
+      {
+        content: [{ type: "text", text: outcome.text }],
+        ...outcome.structured ? { structuredContent: outcome.structured } : {},
+        ...outcome.isError ? { isError: true } : {}
+      },
+      modern
+    );
+  }
+  async function listResources(id, modern) {
+    const resources = await options.resources.list(options.context);
+    return ok(id, { resources }, modern);
+  }
+  async function readResource(id, modern, params) {
+    const uri = params?.uri;
+    if (typeof uri !== "string") {
+      return errorResponse(id, ERROR_CODES.invalidParams, 'resources/read requires a "uri" string.');
+    }
+    const contents = await options.resources.read(uri, options.context);
+    if (!contents) {
+      return errorResponse(id, ERROR_CODES.invalidParams, `Unknown resource "${uri}".`);
+    }
+    return ok(id, { contents: [contents] }, modern);
+  }
+  function listPrompts(id, modern) {
+    const prompts = options.prompts.map((prompt) => ({
+      name: prompt.name,
+      ...prompt.title ? { title: prompt.title } : {},
+      description: prompt.description,
+      arguments: prompt.arguments
+    }));
+    return ok(id, { prompts }, modern);
+  }
+  function getPrompt(id, modern, params) {
+    const name = params?.name;
+    if (typeof name !== "string") {
+      return errorResponse(id, ERROR_CODES.invalidParams, 'prompts/get requires a "name" string.');
+    }
+    const prompt = promptsByName.get(name);
+    if (!prompt) {
+      const known = [...promptsByName.keys()].sort().join(", ");
+      return errorResponse(id, ERROR_CODES.invalidParams, `Unknown prompt "${name}". Available: ${known}.`);
+    }
+    const rawArguments = params?.arguments ?? {};
+    if (!isJsonObject(rawArguments)) {
+      return errorResponse(id, ERROR_CODES.invalidParams, '"arguments" must be a JSON object.');
+    }
+    const built = prompt.build(rawArguments);
+    const messages = built.messages.map((message) => ({
+      role: message.role,
+      content: { type: "text", text: message.content.text }
+    }));
+    return ok(id, { description: built.description, messages }, modern);
+  }
+  async function route(name, id, modern, params) {
+    switch (name) {
+      case METHOD.initialize:
+        return modern ? errorResponse(
+          id,
+          ERROR_CODES.methodNotFound,
+          '"initialize" does not exist in this protocol revision; call "server/discover".'
+        ) : initialize(id, params);
+      case METHOD.discover:
+        return discover(id);
+      case METHOD.ping:
+        return modern ? errorResponse(
+          id,
+          ERROR_CODES.methodNotFound,
+          '"ping" was removed in this protocol revision; call "server/discover".'
+        ) : ok(id, {}, modern);
+    }
+    if (!session.ready) {
+      return errorResponse(
+        id,
+        ERROR_CODES.invalidRequest,
+        'This connection has not been initialized. Send "initialize" first.'
+      );
+    }
+    switch (name) {
+      case METHOD.toolsList:
+        return listTools(id, modern);
+      case METHOD.toolsCall:
+        return callTool(id, modern, params);
+      case METHOD.resourcesList:
+        return listResources(id, modern);
+      case METHOD.resourcesRead:
+        return readResource(id, modern, params);
+      case METHOD.resourceTemplatesList:
+        return ok(id, { resourceTemplates: options.resources.templates() }, modern);
+      case METHOD.promptsList:
+        return listPrompts(id, modern);
+      case METHOD.promptsGet:
+        return getPrompt(id, modern, params);
+      default:
+        return errorResponse(id, ERROR_CODES.methodNotFound, `Unknown method "${name}".`);
+    }
+  }
+  async function dispatch(message) {
+    if (!isJsonObject(message)) {
+      return errorResponse(null, ERROR_CODES.parseError, "Message is not a JSON object.");
+    }
+    const isRequest = Object.prototype.hasOwnProperty.call(message, "id");
+    const method = message.method;
+    const params = message.params;
+    if (message.jsonrpc !== "2.0" && isRequest) {
+      return errorResponse(requestIdOf(message), ERROR_CODES.invalidRequest, 'Message must carry "jsonrpc": "2.0".');
+    }
+    if (typeof method !== "string" || method.length === 0) {
+      return isRequest ? errorResponse(requestIdOf(message), ERROR_CODES.invalidRequest, 'Message must carry a "method" string.') : null;
+    }
+    if (params !== void 0 && !isJsonObject(params)) {
+      return isRequest ? errorResponse(requestIdOf(message), ERROR_CODES.invalidRequest, '"params" must be a JSON object when present.') : null;
+    }
+    const named = params;
+    const decision = classifyRequest(method, named, session);
+    const modern = decision.kind === "era" ? decision.era === "modern" : session.era === "modern";
+    if (!isRequest) {
+      if (decision.kind === "era" && session.era === null) {
+        session.era = decision.era;
+        session.protocolVersion = decision.version;
+      }
+      handleNotification(method);
+      return null;
+    }
+    const id = requestIdOf(message);
+    if (id === null) {
+      return errorResponse(null, ERROR_CODES.invalidRequest, 'A request "id" must be a string or a number.');
+    }
+    if (decision.kind === "error") {
+      return errorResponse(id, decision.code, decision.message, decision.data);
+    }
+    if (session.era === null) {
+      session.era = decision.era;
+      session.protocolVersion = decision.version;
+    }
+    return route(method, id, modern, named);
+  }
+  return {
+    session,
+    async handle(message) {
+      try {
+        return await dispatch(message);
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        options.context.log(`mcp: internal error: ${detail}`);
+        const id = isJsonObject(message) ? requestIdOf(message) : null;
+        return errorResponse(id, ERROR_CODES.internalError, "Internal server error.");
+      }
+    }
+  };
+}
+
+// src/mcp/part.ts
+var FILE_HEADING = "### FILE: ";
+var CONTENT_MARKERS = /* @__PURE__ */ new Set(["#### Content", "#### Bounded Preview"]);
+function parsePartSections(partText) {
+  const lines = partText.split("\n");
+  const sections = [];
+  let index = 0;
+  while (index < lines.length) {
+    if (!lines[index].startsWith(FILE_HEADING)) {
+      index += 1;
+      continue;
+    }
+    const heading = lines[index].slice(FILE_HEADING.length);
+    let cursor = index + 1;
+    let inclusion = null;
+    let sha256 = null;
+    let includedLines = null;
+    while (cursor < lines.length && !CONTENT_MARKERS.has(lines[cursor])) {
+      const line = lines[cursor];
+      if (line.startsWith(FILE_HEADING)) break;
+      if (line.startsWith("- Inclusion: ")) inclusion = line.slice("- Inclusion: ".length).trim();
+      else if (line.startsWith("- SHA-256: ")) sha256 = line.slice("- SHA-256: ".length).trim();
+      else if (line.startsWith("- Included Lines: ")) {
+        const value = Number(line.slice("- Included Lines: ".length).trim());
+        includedLines = Number.isFinite(value) ? value : null;
+      }
+      cursor += 1;
+    }
+    if (cursor >= lines.length || !CONTENT_MARKERS.has(lines[cursor])) {
+      index = cursor + 1;
+      continue;
+    }
+    let fenceLine = cursor + 1;
+    while (fenceLine < lines.length && lines[fenceLine].trim().length === 0) fenceLine += 1;
+    const fenceMatch = /^(`{4,})/.exec(lines[fenceLine] ?? "");
+    if (!fenceMatch) {
+      index = cursor + 1;
+      continue;
+    }
+    const fence = fenceMatch[1];
+    const body = [];
+    let bodyLine = fenceLine + 1;
+    while (bodyLine < lines.length && lines[bodyLine] !== fence) {
+      body.push(lines[bodyLine]);
+      bodyLine += 1;
+    }
+    sections.push({ path: heading, body: body.join("\n"), inclusion, sha256, includedLines });
+    index = bodyLine + 1;
+  }
+  return sections;
+}
+function findSection(sections, relativePath, sha256) {
+  const exact = sections.find((section) => section.path === relativePath);
+  if (exact) return exact;
+  if (sha256) {
+    const byHash = sections.filter((section) => section.sha256 === sha256);
+    if (byHash.length === 1) return byHash[0];
+    if (byHash.length > 1) {
+      const byPath = byHash.find(
+        (section) => section.path.toLowerCase() === relativePath.toLowerCase()
+      );
+      if (byPath) return byPath;
+    }
+  }
+  const folded = sections.filter((section) => section.path.toLowerCase() === relativePath.toLowerCase());
+  return folded.length === 1 ? folded[0] : null;
+}
+function windowText(body, fromLine, lineCount) {
+  const lines = body.split("\n");
+  const total = lines.length;
+  const start = Math.min(Math.max(1, Math.trunc(fromLine)), Math.max(1, total));
+  const end = Math.min(total, start + Math.max(1, Math.trunc(lineCount)) - 1);
+  const slice = lines.slice(start - 1, end);
+  return {
+    text: slice.join("\n"),
+    fromLine: start,
+    returnedLines: slice.length,
+    totalLines: total,
+    truncated: end < total,
+    nextFromLine: end < total ? end + 1 : null
+  };
+}
+function foldForComparison(value) {
+  return process.platform === "win32" || process.platform === "darwin" ? value.toLowerCase() : value;
+}
+function canonicalPath(value) {
+  const absolute = path2.resolve(value);
+  try {
+    return fs.realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+function isInside(parent, child) {
+  const foldedParent = foldForComparison(parent);
+  const foldedChild = foldForComparison(child);
+  return foldedChild === foldedParent || foldedChild.startsWith(`${foldedParent}${path2.sep}`);
+}
+function resolveRoot(requested, context) {
+  if (requested !== void 0 && (typeof requested !== "string" || requested.trim().length === 0)) {
+    return { ok: false, message: '"root" must be a non-empty string when provided.' };
+  }
+  const wanted = typeof requested === "string" ? requested.trim() : context.cwd;
+  const absolute = path2.resolve(context.cwd, wanted);
+  let stats;
+  try {
+    stats = fs.statSync(absolute);
+  } catch {
+    return { ok: false, message: `"${wanted}" does not exist, so it cannot be a repository root.` };
+  }
+  if (!stats.isDirectory()) {
+    return { ok: false, message: `"${wanted}" is not a directory.` };
+  }
+  const resolved = canonicalPath(absolute);
+  for (const allowed of context.roots) {
+    if (isInside(canonicalPath(allowed), resolved)) return { ok: true, root: resolved };
+  }
+  const shown = context.roots.join(", ");
+  return {
+    ok: false,
+    message: `"${wanted}" resolves outside the directories this server may read (${shown}). Restart it with --root <path> to add a repository.`
+  };
+}
+async function openWorkspace(root, overrides = {}) {
+  const loaded = await loadConfigFileDetailed(root);
+  if (loaded.errors.length > 0) {
+    return {
+      ok: false,
+      message: `The config file could not be read: ${loaded.errors.join("; ")} Fix it, or delete it to use the defaults \u2014 this server will not silently ignore it.`
+    };
+  }
+  const cliOptions = { cwd: root };
+  if (overrides.maxPartBytes !== void 0) {
+    const parsed = parseByteSize(overrides.maxPartBytes);
+    if (parsed === void 0) {
+      return {
+        ok: false,
+        message: '"maxPartBytes" must be a byte count, for example 307200 or "300k".'
+      };
+    }
+    cliOptions.maxPartBytes = parsed;
+  }
+  if (overrides.outDir !== void 0) {
+    if (typeof overrides.outDir !== "string" || overrides.outDir.trim().length === 0) {
+      return { ok: false, message: '"outDir" must be a non-empty string.' };
+    }
+    cliOptions.outDir = overrides.outDir.trim();
+  }
+  try {
+    const config = resolveConfig(loaded.config, cliOptions, root);
+    return { ok: true, workspace: { root, config, configFile: loaded.file } };
+  } catch (error) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+  }
+}
+var manifestCache = /* @__PURE__ */ new Map();
+function manifestPathFor(workspace) {
+  return path2.resolve(workspace.root, workspace.config.outDir, "manifest.json");
+}
+function readManifest(workspace) {
+  const file = manifestPathFor(workspace);
+  const shown = path2.relative(workspace.root, file).split(path2.sep).join("/") || file;
+  let stats;
+  try {
+    stats = fs.statSync(file);
+  } catch {
+    return {
+      ok: false,
+      missing: true,
+      message: `There is no snapshot manifest at ${shown}. Call snapshot_plan to preview what would be included, or snapshot_generate to write it.`
+    };
+  }
+  const cached = manifestCache.get(file);
+  if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size) {
+    return { ok: true, manifest: cached.manifest, file };
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    return {
+      ok: false,
+      missing: false,
+      message: `${shown} exists but could not be read: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, missing: false, message: `${shown} is not valid JSON.` };
+  }
+  const problem = describeManifestShapeProblem(parsed);
+  if (problem) {
+    return { ok: false, missing: false, message: `${shown} is not a snapshot manifest: ${problem}` };
+  }
+  const manifest = parsed;
+  manifestCache.set(file, { mtimeMs: stats.mtimeMs, size: stats.size, manifest });
+  return { ok: true, manifest, file };
+}
+function forgetManifest(file) {
+  manifestCache.delete(file);
+}
+
+// src/mcp/tools.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var WRITES = {
+  readOnlyHint: false,
+  // It replaces the snapshot directory but never anything it did not write, so it is additive with
+  // respect to the user's files.
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var MAX_RESULT_BYTES = 64 * 1024;
+var ROOT_PROPERTY = {
+  type: "string",
+  description: "Repository root. Defaults to the directory this server was started in."
+};
+function failure(message) {
+  return { text: message, isError: true };
+}
+function plural(count, word) {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} kB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function relativeFor(workspace, absolute) {
+  return path2.relative(workspace.root, absolute).split(path2.sep).join("/");
+}
+function capped(values, limit = 20) {
+  return { count: values.length, sample: values.slice(0, limit) };
+}
+function summarizeDrift(drift) {
+  return {
+    missingInSnapshot: capped(drift.missingInSnapshot),
+    missingOnDisk: capped(drift.missingOnDisk),
+    unreadable: capped(drift.unreadable),
+    hashMismatches: capped(drift.hashMismatches),
+    partIssues: capped(drift.partIssues),
+    totalsMismatches: capped(drift.totalsMismatches),
+    configMismatches: capped(drift.configMismatches)
+  };
+}
+function toRelativePath(root, value) {
+  const cleaned = value.trim();
+  if (cleaned.length === 0) return null;
+  if (!path2.isAbsolute(cleaned)) {
+    return cleaned.replace(/\\/g, "/").replace(/^\.\//, "");
+  }
+  const relative3 = path2.relative(root, cleaned);
+  if (relative3.startsWith("..") || path2.isAbsolute(relative3)) return null;
+  return relative3.split(path2.sep).join("/");
+}
+function symbolsOf(entry) {
+  const summary = entry.summary;
+  if (!summary || typeof summary !== "object" || !("exports" in summary)) return [];
+  const source = summary;
+  return [...source.exports, ...source.reactComponents, ...source.routeHandlers];
+}
+async function prepare(args, context, overrides = {}) {
+  const rootOutcome = resolveRoot(args.root, context);
+  if (!rootOutcome.ok) return { ok: false, outcome: failure(rootOutcome.message) };
+  const opened = await openWorkspace(rootOutcome.root, overrides);
+  if (!opened.ok) return { ok: false, outcome: failure(opened.message) };
+  return { ok: true, workspace: opened.workspace };
+}
+var statusTool = {
+  name: "snapshot_status",
+  title: "Snapshot status",
+  description: "Report whether a snapshot exists for this repository, when it was built, and what it covers. Reads the manifest rather than the repository, so it is cheap. Call it before deciding whether a snapshot needs to be generated.",
+  inputSchema: {
+    type: "object",
+    properties: { root: ROOT_PROPERTY },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      present: { type: "boolean" },
+      root: { type: "string" },
+      outDir: { type: "string" },
+      fingerprint: { type: "string" },
+      generatedAt: { type: "string" },
+      generatorVersion: { type: "string" },
+      generatorVersionMatches: { type: "boolean" },
+      includedFiles: { type: "integer" },
+      skippedFiles: { type: "integer" },
+      partCount: { type: "integer" },
+      warningCount: { type: "integer" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    const read = readManifest(workspace);
+    if (!read.ok) {
+      return {
+        text: read.message,
+        structured: {
+          present: false,
+          root: workspace.root,
+          outDir: workspace.config.outDir,
+          message: read.message
+        }
+      };
+    }
+    const manifest = read.manifest;
+    const versionMatches = manifest.generator.version === GENERATOR_VERSION;
+    const lines = [
+      `Snapshot: ${workspace.config.outDir}/`,
+      `Generated: ${manifest.generatedAt} by ${manifest.generator.name} ${manifest.generator.version}`,
+      `Files: ${manifest.counts.totalFiles} included, ${manifest.counts.skippedCount} skipped, ${plural(manifest.counts.partsCount, "part")}`,
+      `Content: ${formatBytes(manifest.counts.totalSizeBytes)} of source in ${formatBytes(manifest.totals.totalContentBytes)} emitted`,
+      `Fingerprint: ${manifest.fingerprint}`,
+      `Git: ${manifest.git.branch} @ ${manifest.git.commit}${manifest.git.isDirty ? " (dirty)" : " (clean)"}`
+    ];
+    if (manifest.totals.warningCount > 0) lines.push(`Warnings: ${manifest.totals.warningCount}`);
+    if (!versionMatches) {
+      lines.push(
+        `Note: written by ${manifest.generator.version}, this server is ${GENERATOR_VERSION}. Re-run snapshot_generate if the difference matters.`
+      );
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        present: true,
+        root: workspace.root,
+        outDir: workspace.config.outDir,
+        fingerprint: manifest.fingerprint,
+        generatedAt: manifest.generatedAt,
+        generatorVersion: manifest.generator.version,
+        generatorVersionMatches: versionMatches,
+        includedFiles: manifest.counts.totalFiles,
+        skippedFiles: manifest.counts.skippedCount,
+        partCount: manifest.counts.partsCount,
+        warningCount: manifest.totals.warningCount,
+        preset: manifest.config.preset,
+        maxPartBytes: manifest.budgets.maxPartBytes
+      }
+    };
+  }
+};
+var planTool = {
+  name: "snapshot_plan",
+  title: "Preview a snapshot",
+  description: "Preview a snapshot without writing anything: how many files and parts it would contain, and why every excluded file was excluded. Use it to choose a part budget before generating.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      root: ROOT_PROPERTY,
+      maxPartBytes: {
+        type: "string",
+        description: 'Byte budget per part, for example 307200 or "300k". Defaults to the project configuration.'
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      files: { type: "integer" },
+      skipped: { type: "integer" },
+      parts: { type: "integer" },
+      sourceBytes: { type: "integer" },
+      emittedBytes: { type: "integer" },
+      preset: { type: "string" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context, { maxPartBytes: args.maxPartBytes });
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    let manifest;
+    try {
+      manifest = generateSnapshot(workspace.config, { dryRun: true });
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    const reasons = /* @__PURE__ */ new Map();
+    for (const record of manifest.skipped) {
+      reasons.set(record.reason, (reasons.get(record.reason) ?? 0) + 1);
+    }
+    const topReasons = [...reasons.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).slice(0, 8).map(([reason, count]) => ({ reason, count }));
+    const lines = [
+      "Dry run \u2014 nothing was written.",
+      `Preset: ${manifest.config.preset}`,
+      `Would include ${plural(manifest.counts.totalFiles, "file")} in ${plural(manifest.counts.partsCount, "part")} (${formatBytes(manifest.counts.totalSizeBytes)} of source, ${formatBytes(manifest.totals.totalContentBytes)} emitted).`,
+      `Would skip ${plural(manifest.counts.skippedCount, "file")}.`
+    ];
+    if (topReasons.length > 0) {
+      lines.push("Top skip reasons:");
+      for (const entry of topReasons) lines.push(`  - ${entry.reason} (${entry.count})`);
+    }
+    if (manifest.warnings.length > 0) {
+      lines.push(`Warnings (${manifest.warnings.length}):`);
+      for (const warning of manifest.warnings.slice(0, 5)) lines.push(`  - ${warning}`);
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        files: manifest.counts.totalFiles,
+        skipped: manifest.counts.skippedCount,
+        parts: manifest.counts.partsCount,
+        sourceBytes: manifest.counts.totalSizeBytes,
+        emittedBytes: manifest.totals.totalContentBytes,
+        preset: manifest.config.preset,
+        maxPartBytes: manifest.budgets.maxPartBytes,
+        layers: manifest.layers,
+        skipReasons: topReasons,
+        warnings: manifest.warnings.slice(0, 5),
+        warningCount: manifest.warnings.length
+      }
+    };
+  }
+};
+var generateTool = {
+  name: "snapshot_generate",
+  title: "Generate the snapshot",
+  description: "Write the snapshot to its output directory and return its fingerprint, parts and counts. Replaces the previous snapshot in that directory. A large repository can take several seconds.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      root: ROOT_PROPERTY,
+      maxPartBytes: {
+        type: "string",
+        description: 'Byte budget per part, for example 307200 or "300k". Defaults to the project configuration.'
+      },
+      outDir: {
+        type: "string",
+        description: "Output directory relative to the root. Defaults to the project configuration."
+      }
+    },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      fingerprint: { type: "string" },
+      files: { type: "integer" },
+      skipped: { type: "integer" },
+      parts: { type: "integer" },
+      emittedBytes: { type: "integer" }
+    }
+  },
+  annotations: WRITES,
+  async handler(args, context) {
+    const prepared = await prepare(args, context, {
+      maxPartBytes: args.maxPartBytes,
+      outDir: args.outDir
+    });
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    let manifest;
+    try {
+      manifest = generateSnapshot(workspace.config);
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    forgetManifest(manifestPathFor(workspace));
+    const written = relativeFor(workspace, path2.resolve(workspace.root, workspace.config.outDir));
+    const lines = [
+      `Wrote ${written}/`,
+      `Files: ${manifest.counts.totalFiles} included, ${manifest.counts.skippedCount} skipped, ${plural(manifest.counts.partsCount, "part")}`,
+      `Parts: ${manifest.parts.map((part) => `${part.filename} (${formatBytes(part.byteSize)})`).join(", ")}`,
+      `Fingerprint: ${manifest.fingerprint}`
+    ];
+    if (manifest.warnings.length > 0) {
+      lines.push(`Warnings (${manifest.warnings.length}):`);
+      for (const warning of manifest.warnings.slice(0, 5)) lines.push(`  - ${warning}`);
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        fingerprint: manifest.fingerprint,
+        files: manifest.counts.totalFiles,
+        skipped: manifest.counts.skippedCount,
+        parts: manifest.counts.partsCount,
+        emittedBytes: manifest.totals.totalContentBytes,
+        outDir: written,
+        partFiles: manifest.parts.map((part) => part.filename),
+        warningCount: manifest.warnings.length
+      }
+    };
+  }
+};
+var validateTool = {
+  name: "snapshot_validate",
+  title: "Validate the snapshot",
+  description: "Re-read the repository and report whether the snapshot on disk still matches it. Use it before trusting context that came from an earlier session, or after changing the config.",
+  inputSchema: {
+    type: "object",
+    properties: { root: ROOT_PROPERTY },
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      current: { type: "boolean" },
+      manifestPresent: { type: "boolean" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    let result;
+    try {
+      result = validateSnapshot(workspace.config);
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    const lines = [];
+    if (result.valid) {
+      lines.push("The snapshot matches the repository.");
+    } else {
+      lines.push("The snapshot is out of date.");
+      const drift = result.drift;
+      const observations = [
+        ["file(s) changed on disk", drift.hashMismatches.length],
+        ["file(s) added since the snapshot", drift.missingInSnapshot.length],
+        ["file(s) gone since the snapshot", drift.missingOnDisk.length],
+        ["part file(s) damaged or missing", drift.partIssues.length],
+        ["setting(s) changed since the snapshot", drift.configMismatches.length],
+        ["internal count(s) disagreeing", drift.totalsMismatches.length]
+      ];
+      for (const [label, count] of observations) {
+        if (count > 0) lines.push(`  - ${count} ${label}`);
+      }
+      for (const error of result.errors.slice(0, 5)) lines.push(`  - ${error}`);
+      lines.push("Run snapshot_generate to refresh it.");
+    }
+    for (const warning of result.warnings.slice(0, 5)) lines.push(`Note: ${warning}`);
+    return {
+      text: lines.join("\n"),
+      structured: {
+        current: result.valid,
+        manifestPresent: result.manifestPresent,
+        drift: summarizeDrift(result.drift),
+        errors: result.errors.slice(0, 10),
+        warnings: result.warnings.slice(0, 10)
+      }
+      // A stale snapshot is an answer, not a tool failure: the caller asked whether it is current.
+    };
+  }
+};
+var locateTool = {
+  name: "snapshot_locate",
+  title: "Locate code in the snapshot",
+  description: "Find which part holds the code you need. Matches file paths, exported symbols, component names and routes from the snapshot's index, so one part can be read instead of all of them.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Text to match, case-insensitively, against paths and exported symbols."
+      },
+      by: {
+        type: "string",
+        enum: ["auto", "path", "symbol", "route", "layer", "kind"],
+        default: "auto",
+        description: "Restrict what is matched. Defaults to every category."
+      },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        maximum: 100,
+        default: 20,
+        description: "Maximum matches to return."
+      },
+      root: ROOT_PROPERTY
+    },
+    required: ["query"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: { total: { type: "integer" } }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    const read = readManifest(workspace);
+    if (!read.ok) return failure(read.message);
+    const query = String(args.query ?? "").trim();
+    if (query.length === 0) return failure('"query" must not be empty.');
+    const needle = query.toLowerCase();
+    const by = typeof args.by === "string" ? args.by : "auto";
+    const limit = typeof args.limit === "number" ? args.limit : 20;
+    const manifest = read.manifest;
+    const matches = [];
+    const add = (entry, matchedBy, detail) => {
+      matches.push({
+        path: entry.relativePath,
+        part: entry.part,
+        layer: entry.layer,
+        kind: entry.kind,
+        matchedBy,
+        ...detail ? { detail } : {}
+      });
+    };
+    const wants = (category) => by === "auto" || by === category;
+    for (const entry of manifest.files) {
+      if (wants("path") && entry.relativePath.toLowerCase().includes(needle)) {
+        add(entry, "path");
+        continue;
+      }
+      if (wants("symbol")) {
+        const symbol = symbolsOf(entry).find((name) => name.toLowerCase().includes(needle));
+        if (symbol) {
+          add(entry, "symbol", symbol);
+          continue;
+        }
+      }
+      if (wants("layer") && entry.layer.toLowerCase() === needle) add(entry, "layer");
+      else if (wants("kind") && entry.kind.toLowerCase() === needle) add(entry, "kind");
+    }
+    if (wants("route")) {
+      for (const route of manifest.indexes.routes) {
+        if (!route.path.toLowerCase().includes(needle)) continue;
+        if (matches.some((match) => match.path === route.path)) continue;
+        matches.push({
+          path: route.path,
+          part: route.part,
+          layer: "route",
+          kind: "route",
+          matchedBy: "route",
+          detail: route.methods.join(", ")
+        });
+      }
+    }
+    if (matches.length === 0) {
+      return {
+        text: `Nothing in the snapshot matches "${query}". Try a shorter fragment, or snapshot_explain a path to see whether it is included at all.`,
+        structured: { total: 0, matches: [] }
+      };
+    }
+    const shown = matches.slice(0, limit);
+    const lines = [
+      `${matches.length} match${matches.length === 1 ? "" : "es"} for "${query}"` + (matches.length > shown.length ? ` (showing ${shown.length})` : "") + ":"
+    ];
+    for (const match of shown) {
+      const detail = match.detail ? ` \u2014 ${match.detail}` : "";
+      lines.push(`  ${match.path}${detail}  [${match.part}, ${match.layer}/${match.kind}]`);
+    }
+    if (matches.length > shown.length) {
+      lines.push("Raise `limit` to see more.");
+    }
+    return {
+      text: lines.join("\n"),
+      structured: { total: matches.length, returned: shown.length, matches: shown }
+    };
+  }
+};
+var readTool = {
+  name: "snapshot_read",
+  title: "Read a file from the snapshot",
+  description: "Return a line window of one file as the snapshot contains it: redacted, and bounded to a preview when the source is large. Reports the next `fromLine` when more remains.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "File path relative to the repository root, as snapshot_locate reports it."
+      },
+      fromLine: {
+        type: "integer",
+        minimum: 1,
+        default: 1,
+        description: "First line to return, 1-based."
+      },
+      lines: {
+        type: "integer",
+        minimum: 1,
+        maximum: 2e3,
+        default: 200,
+        description: "How many lines to return."
+      },
+      root: ROOT_PROPERTY
+    },
+    required: ["path"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      part: { type: "string" },
+      fromLine: { type: "integer" },
+      returnedLines: { type: "integer" },
+      totalLines: { type: "integer" },
+      nextFromLine: { type: "integer" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    if (typeof args.path !== "string") return failure('"path" must be a string.');
+    const relativePath = toRelativePath(workspace.root, args.path);
+    if (!relativePath) {
+      return failure(
+        `"${args.path}" is outside ${workspace.root}. Paths are read relative to the repository root.`
+      );
+    }
+    const read = readManifest(workspace);
+    if (!read.ok) return failure(read.message);
+    const manifest = read.manifest;
+    const entry = manifest.files.find((file) => file.relativePath === relativePath) ?? manifest.files.find((file) => file.relativePath.toLowerCase() === relativePath.toLowerCase());
+    if (!entry) {
+      const skipped = manifest.skipped.find((record) => record.path === relativePath);
+      if (skipped) {
+        const detail = skipped.detail ? ` (${skipped.detail})` : "";
+        return failure(
+          `${relativePath} is not in the snapshot: ${skipped.reason}${detail}. Sensitive and ignored files stay out unless they are included explicitly.`
+        );
+      }
+      return failure(
+        `${relativePath} is not in the snapshot. Call snapshot_locate to find the path, or snapshot_explain to learn why it was excluded.`
+      );
+    }
+    const partPath = path2.resolve(workspace.root, workspace.config.outDir, "parts", entry.part);
+    let partText;
+    try {
+      partText = fs.readFileSync(partPath, "utf8");
+    } catch {
+      return failure(
+        `${entry.part} could not be read, so the snapshot is damaged. Run snapshot_generate to rebuild it.`
+      );
+    }
+    const section = findSection(parsePartSections(partText), entry.relativePath, entry.hashSha256);
+    if (!section) {
+      return failure(
+        `${relativePath} is recorded in ${entry.part} but its section could not be located there. Run snapshot_generate to rebuild the snapshot.`
+      );
+    }
+    const fromLine = typeof args.fromLine === "number" ? args.fromLine : 1;
+    const lineCount = typeof args.lines === "number" ? args.lines : 200;
+    const window = windowText(section.body, fromLine, lineCount);
+    let body = window.text;
+    let truncatedByBytes = false;
+    if (Buffer.byteLength(body, "utf8") > MAX_RESULT_BYTES) {
+      body = body.slice(0, MAX_RESULT_BYTES);
+      const lastBreak = body.lastIndexOf("\n");
+      body = lastBreak > 0 ? body.slice(0, lastBreak) : body;
+      truncatedByBytes = true;
+    }
+    const returnedLines = body.length === 0 ? 0 : body.split("\n").length;
+    const moreRemain = window.truncated || truncatedByBytes;
+    const header = [
+      `${entry.relativePath} \u2014 ${entry.part}, ${entry.layer}/${entry.kind}, ${entry.language}`,
+      section.inclusion === "preview" ? "Bounded preview: this source file is large, so the snapshot holds only its head and tail." : `Lines ${window.fromLine}\u2013${window.fromLine + returnedLines - 1} of ${window.totalLines}.`
+    ];
+    const lines = [...header, "", body];
+    if (moreRemain) {
+      const next = window.fromLine + returnedLines;
+      lines.push("", `Truncated. Call snapshot_read with fromLine=${next} for the rest.`);
+    }
+    return {
+      text: lines.join("\n"),
+      structured: {
+        path: entry.relativePath,
+        part: entry.part,
+        layer: entry.layer,
+        kind: entry.kind,
+        language: entry.language,
+        inclusion: section.inclusion ?? entry.inclusionMode,
+        fromLine: window.fromLine,
+        returnedLines,
+        totalLines: window.totalLines,
+        truncated: moreRemain,
+        nextFromLine: moreRemain ? window.fromLine + returnedLines : null,
+        sha256: entry.hashSha256
+      }
+    };
+  }
+};
+var explainTool = {
+  name: "snapshot_explain",
+  title: "Explain one path",
+  description: 'Explain how the next snapshot would treat one path: its layer, kind, language and part, or the exact reason it is excluded. Answers "why is this file missing".',
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Path relative to the repository root. Directories are explained as a whole."
+      },
+      root: ROOT_PROPERTY
+    },
+    required: ["path"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      included: { type: "boolean" },
+      reason: { type: "string" }
+    }
+  },
+  annotations: READ_ONLY,
+  async handler(args, context) {
+    const prepared = await prepare(args, context);
+    if (!prepared.ok) return prepared.outcome;
+    const workspace = prepared.workspace;
+    if (typeof args.path !== "string") return failure('"path" must be a string.');
+    const relativePath = toRelativePath(workspace.root, args.path);
+    if (!relativePath) {
+      return failure(`"${args.path}" is outside ${workspace.root}.`);
+    }
+    let result;
+    try {
+      result = explainPath(workspace.config, relativePath);
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+    return {
+      text: renderExplainText(result),
+      structured: {
+        path: result.path,
+        included: result.included,
+        ...result.reason ? { reason: result.reason } : {},
+        ...result.detail ? { detail: result.detail } : {},
+        ...result.layer ? { layer: result.layer } : {},
+        ...result.kind ? { kind: result.kind } : {},
+        ...result.language ? { language: result.language } : {},
+        ...result.part ? { part: result.part } : {},
+        ...result.inclusionMode ? { inclusion: result.inclusionMode } : {},
+        ...typeof result.lines === "number" ? { lines: result.lines } : {},
+        ...typeof result.bytes === "number" ? { bytes: result.bytes } : {},
+        ...typeof result.secretCount === "number" ? { secretCount: result.secretCount } : {}
+      }
+    };
+  }
+};
+function buildTools() {
+  return [
+    statusTool,
+    planTool,
+    generateTool,
+    validateTool,
+    locateTool,
+    readTool,
+    explainTool
+  ];
+}
+
+// src/mcp/prompts.ts
+var ORIENT = `You have a codebase-snapshot server for this repository. Build a map of it before reading any code.
+
+1. Call snapshot_status. If no snapshot exists, call snapshot_plan to preview it, then snapshot_generate.
+2. Call snapshot_locate for the areas that matter. Search by exported symbol, route or path fragment rather than guessing filenames.
+3. Report back: the layers present, the entry points, and the files that matter here \u2014 cited as paths with their part.
+4. Read one file at a time with snapshot_read, one window at a time. Do not read a part end to end.`;
+var KEEP_CURRENT = `Keep the context you were given provably current while you work.
+
+1. Before relying on a snapshot from an earlier session, call snapshot_validate.
+2. If it reports drift, call snapshot_generate once, then snapshot_validate again.
+3. After changes you make, call snapshot_validate and report what it said.
+4. Never call a snapshot current unless snapshot_validate said so in this session.`;
+function withFocus(base, focus) {
+  return typeof focus === "string" && focus.trim().length > 0 ? `${base}
+
+Focus for this pass: ${focus.trim()}` : base;
+}
+function buildPrompts() {
+  return [
+    {
+      name: "orient",
+      title: "Orient in this repository",
+      description: "Map the repository from the snapshot before reading any of it.",
+      arguments: [
+        {
+          name: "focus",
+          description: 'Optional area to concentrate on, for example "authentication".',
+          required: false
+        }
+      ],
+      build(args) {
+        return {
+          description: "Map the repository before reading it.",
+          messages: [{ role: "user", content: { type: "text", text: withFocus(ORIENT, args.focus) } }]
+        };
+      }
+    },
+    {
+      name: "keep-current",
+      title: "Keep the snapshot current",
+      description: "Validate before trusting earlier context, and again after making changes.",
+      arguments: [],
+      build() {
+        return {
+          description: "Keep the context current.",
+          messages: [{ role: "user", content: { type: "text", text: KEEP_CURRENT } }]
+        };
+      }
+    }
+  ];
+}
+
+// src/mcp/uris.ts
+var STATIC_RESOURCE_URIS = [
+  "snapshot://manifest",
+  "snapshot://contract",
+  "snapshot://skill",
+  "snapshot://reports/audit",
+  "snapshot://reports/tree",
+  "snapshot://reports/navigation"
+];
+var RESOURCE_TEMPLATE_URIS = ["snapshot://parts/{index}"];
+
+// src/agent/option-scope.ts
+var VALIDATE_OPTIONS = [
+  "cwd",
+  "out-dir",
+  "max-part-bytes",
+  "large-file-bytes",
+  "max-monolith-bytes",
+  "include-monolith",
+  "include-sensitive-files",
+  "skip-artifacts",
+  "only-artifacts",
+  "no-config",
+  "discovery",
+  "format",
+  "mode",
+  "help",
+  "version"
+];
+var COMMAND_OPTION_SCOPE = {
+  generate: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "discovery",
+    "format",
+    "mode",
+    "dry-run",
+    "watch",
+    "autopilot",
+    "no-install",
+    "help",
+    "version"
+  ],
+  validate: VALIDATE_OPTIONS,
+  report: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  explain: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "large-file-bytes",
+    "max-monolith-bytes",
+    "include-monolith",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "no-config",
+    "discovery",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  diff: ["format", "mode", "no-config", "help", "version"],
+  describe: ["format", "mode", "help", "version"],
+  init: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "preset",
+    "include",
+    "exclude",
+    "yes",
+    "force",
+    "dry-run",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ],
+  skill: ["cwd", "format", "mode", "install", "target", "help", "version"],
+  // `mcp` reads the repository, so it takes --cwd. It has no --format: stdout carries JSON-RPC
+  // messages, and there is no second shape to choose, so offering the flag would be a lie.
+  mcp: ["cwd", "mode", "help", "version"],
+  setup: [
+    "cwd",
+    "out-dir",
+    "max-part-bytes",
+    "include-sensitive-files",
+    "skip-artifacts",
+    "only-artifacts",
+    "preset",
+    "include",
+    "exclude",
+    "yes",
+    "force",
+    "no-install",
+    "dry-run",
+    "format",
+    "mode",
+    "help",
+    "version"
+  ]
+};
+var COMMAND_ORDER = [
+  "generate",
+  "validate",
+  "report",
+  "explain",
+  "init",
+  "setup",
+  "diff",
+  "describe",
+  "skill",
+  "mcp"
+];
+function commandsForOption(option) {
+  return COMMAND_ORDER.filter((command) => COMMAND_OPTION_SCOPE[command].includes(option));
+}
+function optionAppliesTo(option) {
+  return commandsForOption(option).join("/");
+}
+
+// src/agent/contract.ts
+var CONTRACT_VERSION = "1.0.0";
+var PACKAGE_NAME = "codebase-snapshot";
+var MAJOR_VERSION = GENERATOR_VERSION.split(".")[0];
+var ARTIFACT_SUMMARY = {
+  readme: "README.md describing the snapshot at the output root.",
+  manifest: "manifest.json: machine-readable index of every file, part, hash and config.",
+  parts: "parts/*.md: the packed, budget-limited markdown parts that carry the code.",
+  navigation: "reports/navigation.md: links between parts and layers.",
+  projectTree: "reports/project-tree.md: the directory tree of included files.",
+  audit: "reports/audit.md: secret findings, large files, parse diagnostics, git state.",
+  monolith: "full-codebase.json and full-codebase.md: the whole repository in one file (off by default)."
+};
+var ARTIFACT_DEFAULTS = {
+  readme: true,
+  manifest: true,
+  parts: true,
+  navigation: true,
+  projectTree: true,
+  audit: true,
+  monolith: false
+};
+function renderContractText(contract) {
+  const lines = [];
+  lines.push(`${contract.package} v${contract.version}`);
+  lines.push(contract.summary);
+  lines.push("");
+  lines.push(`Node        : ${contract.requires.node}`);
+  lines.push(`Schema      : ${contract.schemaVersion} (contract ${contract.contractVersion})`);
+  lines.push(`One-shot    : ${contract.invocation.oneShot} <command>`);
+  lines.push(`Installed   : ${contract.invocation.installed} <command>`);
+  lines.push("");
+  lines.push("Workflow:");
+  for (const step of contract.workflow) {
+    lines.push(`  ${step.step}. ${step.id}`);
+    lines.push(`     run    : ${step.run}`);
+    lines.push(`     expect : ${step.expect}`);
+    if (step.notes) lines.push(`     note   : ${step.notes}`);
+  }
+  lines.push("");
+  lines.push("Commands:");
+  for (const command of contract.commands) {
+    const args = command.positionals.length > 0 ? ` ${command.positionals.join(" ")}` : "";
+    lines.push(`  ${(command.name + args).padEnd(26)} ${command.summary}`);
+  }
+  lines.push("");
+  lines.push("Exit codes:");
+  for (const [code, meaning] of Object.entries(contract.exitCodes)) {
+    lines.push(`  ${code}  ${meaning}`);
+  }
+  lines.push("");
+  lines.push(`Presets (${contract.presets.length}): ${contract.presets.map((p) => p.name).join(", ")}`);
+  lines.push("");
+  lines.push("Artifacts:");
+  for (const artifact of contract.artifacts) {
+    lines.push(`  ${artifact.name.padEnd(12)} ${artifact.default ? "on " : "off"}  ${artifact.summary}`);
+  }
+  lines.push("");
+  lines.push("Options:");
+  for (const option of contract.options) {
+    const fallback = option.default === void 0 ? "" : ` [${JSON.stringify(option.default)}]`;
+    lines.push(`  ${option.flag.padEnd(24)} ${option.appliesTo.padEnd(32)}${fallback}`);
+    lines.push(`  ${"".padEnd(24)} ${option.summary}`);
+  }
+  lines.push("");
+  lines.push("MCP:");
+  lines.push(`  command    ${contract.mcp.command}`);
+  lines.push(`  transport  ${contract.mcp.transport}`);
+  lines.push(
+    `  versions   modern ${contract.mcp.protocolVersions.modern.join(", ")} / legacy ${contract.mcp.protocolVersions.legacy.join(", ")}`
+  );
+  lines.push(
+    `  tools      ${contract.mcp.tools.map((tool) => tool.readOnly ? tool.name : `${tool.name} (writes)`).join(", ")}`
+  );
+  lines.push(`  prompts    ${contract.mcp.prompts.map((prompt) => prompt.name).join(", ")}`);
+  lines.push(`  resources  ${contract.mcp.resources.join(", ")}`);
+  lines.push(`  templates  ${contract.mcp.resourceTemplates.join(", ")}`);
+  lines.push("");
+  lines.push("Safety:");
+  for (const note of contract.safety) lines.push(`  - ${note}`);
+  lines.push("");
+  lines.push("Troubleshooting:");
+  for (const item of contract.troubleshooting) {
+    lines.push(`  ${item.symptom}`);
+    lines.push(`     cause: ${item.cause}`);
+    lines.push(`     fix  : ${item.fix}`);
+  }
+  lines.push("");
+  lines.push("This is the human rendering. Agents should use: describe --format json");
+  return lines.join("\n");
+}
+function buildAgentContract() {
+  return {
+    generator: GENERATOR_NAME,
+    package: PACKAGE_NAME,
+    version: GENERATOR_VERSION,
+    schemaVersion: SCHEMA_VERSION,
+    contractVersion: CONTRACT_VERSION,
+    summary: "Turns a repository into an LLM-ready snapshot: code packed into size-budgeted markdown parts, plus a manifest, a project tree, navigation and a secret audit. Auto-detects the project shape (framework, language, monorepo, docs, infra).",
+    requires: { node: ">=18.0.0", dependencies: ["typescript"] },
+    invocation: {
+      oneShot: `npx ${PACKAGE_NAME}@latest`,
+      installed: "npx codebase-snapshot",
+      bins: ["codebase-snapshot", "snapshot"],
+      notes: [
+        `The bare package name also works: npx ${PACKAGE_NAME} <command>.`,
+        "`codebase-snapshot` is the canonical name and the one to script against. `snapshot` is the short alias a global install provides; in a project that has the package installed, `npx snapshot` resolves the local bin first.",
+        `Pin an exact version \u2014 for example \`npx ${PACKAGE_NAME}@${GENERATOR_VERSION} --version\` \u2014 when you need the same build on every machine. A major range is not enough before 1.0: npm's caret on a 0.x version pins the minor, and 0.x minors are breaking by convention.`,
+        "Both bin names point at the same file. npm resolves a package by its bin entries, so they must stay aliases of one executable.",
+        "A bare run in a project with no configuration asks once, sets the project up and generates \u2014 but only at a terminal. With no TTY it exits 2 and names the alternatives, so an unattended caller must say what it wants: `generate` after `init --yes`, or `--autopilot`.",
+        "Human progress goes to stderr. With --format json the payload on stdout is pure JSON.",
+        "A failing run also writes pure JSON to stdout: { error: { message, exitCode } }. The exit code and the stderr line are unchanged."
+      ]
+    },
+    workflow: [
+      {
+        step: 1,
+        id: "verify",
+        run: `npx ${PACKAGE_NAME}@latest --version`,
+        // The requirement is the major version; the exact build is context. A
+        // floating tag may print a different patch today than next week, and an agent
+        // must not conclude that a working tool is broken because of a patch.
+        expect: `prints v${MAJOR_VERSION} or newer on stdout and exits 0 (this build is v${GENERATOR_VERSION}: compare the major version, not the patch)`,
+        notes: `If it prints an older major than this contract's, the @latest tag is behind the release: pin the exact version with \`npx ${PACKAGE_NAME}@${GENERATOR_VERSION} --version\` instead of retrying @latest. If it prints nothing, clear the npm cache and retry, or use \`npx -p <pkg> codebase-snapshot\`.`
+      },
+      {
+        step: 2,
+        id: "understand",
+        run: `npx ${PACKAGE_NAME}@latest describe --format json`,
+        expect: "the full contract as JSON: commands, options, presets, exit codes",
+        notes: "Read this before acting if you have no prior knowledge of the tool."
+      },
+      {
+        step: 3,
+        id: "configure",
+        run: `npx ${PACKAGE_NAME}@latest init --yes`,
+        expect: 'writes a commented config file listing every setting at its current value: snapshot.config.ts only when the running Node can strip types (>= 22.6) and the project is an ES module (`"type": "module"` in package.json); snapshot.config.mjs otherwise',
+        notes: "Non-interactive. The detected preset is chosen automatically; override with --preset <name>. Skip this step to run on built-in defaults."
+      },
+      {
+        step: 4,
+        id: "generate",
+        run: `npx ${PACKAGE_NAME}@latest generate`,
+        expect: "exit 0, and ./snapshot/ written with parts, reports and manifest.json"
+      },
+      {
+        step: 5,
+        id: "verify-output",
+        run: `npx ${PACKAGE_NAME}@latest validate`,
+        expect: "exit 0 means the snapshot matches the files on disk",
+        notes: "Exit 1 means drift or a damaged snapshot; re-run generate."
+      },
+      {
+        step: 6,
+        id: "consume",
+        run: "read ./snapshot/parts/*.md, then ./snapshot/manifest.json, then ./snapshot/reports/audit.md",
+        expect: "the code, the index of what was included, and the risk findings",
+        notes: "manifest.json.files[] lists every included file with layer, kind, language, part and summary. manifest.skipped[] explains every file that was left out and why."
+      }
+    ],
+    commands: [
+      {
+        name: "generate",
+        aliases: ["default"],
+        summary: "Write the snapshot. This is the command you normally want. In a project with no configuration, a terminal asks once and sets the project up first; without a terminal it exits 2 and names `--autopilot` and `init --yes`.",
+        positionals: [],
+        exits: [0, 1, 2]
+      },
+      {
+        name: "validate",
+        aliases: ["check"],
+        summary: "Compare the snapshot on disk with the repository; exit 1 on drift. `check` is an alias of `validate`.",
+        positionals: [],
+        exits: [0, 1]
+      },
+      {
+        name: "report",
+        aliases: [],
+        summary: "Print snapshot health, layer metrics and the secret audit.",
+        positionals: [],
+        exits: [0, 1]
+      },
+      {
+        name: "setup",
+        aliases: [],
+        summary: "Everything a repository needs in one command, with defaults: write the config when there is none (an existing one is kept), add the npm scripts, devDependency and .gitignore entries, install dependencies with the project's package manager, then generate the snapshot. --no-install skips the install; --dry-run writes nothing.",
+        positionals: [],
+        exits: [0, 1, 2]
+      },
+      {
+        name: "init",
+        aliases: [],
+        summary: "Write a commented config file (snapshot.config.ts only when Node can strip types and the project is an ES module; snapshot.config.mjs otherwise), add the snapshot scripts and the devDependency, and ignore the snapshot directories. Nothing else is written. Interactive, or --yes for CI.",
+        positionals: [],
+        exits: [0, 1, 2]
+      },
+      {
+        name: "explain",
+        aliases: [],
+        summary: "Explain how one path would be treated: layer, kind, part, skip reason. Always exits 0 when it can report; read `included` and `reason` instead of the exit code.",
+        positionals: ["<path>"],
+        exits: [0]
+      },
+      {
+        name: "diff",
+        aliases: [],
+        summary: "Compare two snapshots (directories or manifest.json files).",
+        positionals: ["<before>", "<after>"],
+        exits: [0, 1]
+      },
+      {
+        name: "describe",
+        aliases: [],
+        summary: "Print this contract. --format json for machines, text for humans.",
+        positionals: [],
+        exits: [0]
+      },
+      {
+        name: "skill",
+        aliases: [],
+        summary: "Print the agent skill, or --install it into the tool registries this repository's agent reads (.claude/skills, .cursor/rules). Files it creates are added to .gitignore. It never writes AGENTS.md: that file belongs to the repository.",
+        positionals: [],
+        exits: [0, 1, 2]
+      },
+      {
+        name: "mcp",
+        aliases: [],
+        summary: "Serve this repository to an MCP client over stdio. The tools, resources and protocol versions it offers are listed in this contract's `mcp` block.",
+        positionals: [],
+        exits: [0, 2]
+      }
+    ],
+    exitCodes: {
+      "0": "success (and validate: no drift)",
+      "1": "drift detected, or generation refused/failed (nothing was written)",
+      "2": "usage error: unknown flag/command, bad value, wrong argument count"
+    },
+    options: [
+      {
+        flag: "--out-dir",
+        type: "string",
+        default: "snapshot",
+        appliesTo: optionAppliesTo("out-dir"),
+        summary: "Where the snapshot is written. Must not be the repo root or a directory the tool did not create."
+      },
+      {
+        flag: "--max-part-bytes",
+        type: "string",
+        default: 307200,
+        appliesTo: optionAppliesTo("max-part-bytes"),
+        summary: 'Byte budget per markdown part. Accepts "120k" / "1.5mb". Minimum 4096.'
+      },
+      {
+        flag: "--large-file-bytes",
+        type: "string",
+        default: 204800,
+        appliesTo: optionAppliesTo("large-file-bytes"),
+        summary: "Above this size a file gets a head/tail preview instead of the full body."
+      },
+      {
+        flag: "--max-monolith-bytes",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("max-monolith-bytes"),
+        summary: "Skip the monolith artifacts when they would exceed this size."
+      },
+      {
+        flag: "--include-monolith",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("include-monolith"),
+        summary: "Also write full-codebase.json and full-codebase.md."
+      },
+      {
+        flag: "--include-sensitive-files",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("include-sensitive-files"),
+        summary: "Also emit .env / *.pem / .npmrc style files. Off by default; they are recorded as skipped."
+      },
+      {
+        flag: "--discovery",
+        type: "string",
+        default: "auto",
+        appliesTo: optionAppliesTo("discovery"),
+        summary: "How files are discovered: auto (git when usable), git (require git), walk (read the root .gitignore directly; the escape hatch for a .git that cannot be listed)."
+      },
+      {
+        flag: "--skip-artifacts",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("skip-artifacts"),
+        summary: "Comma-separated artifacts to omit (readme, manifest, parts, navigation, projectTree, audit, monolith)."
+      },
+      {
+        flag: "--only-artifacts",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("only-artifacts"),
+        summary: "Write only these artifacts. Cannot be combined with --skip-artifacts."
+      },
+      {
+        flag: "--format",
+        type: "string",
+        default: "text",
+        // `optionAppliesTo` always returns the explicit slash list, so this is the same scoped form
+        // as every other option — no prose sentinel a machine consumer could misread.
+        appliesTo: optionAppliesTo("format"),
+        summary: 'Output format: "text" or "json". JSON goes to stdout, progress to stderr.'
+      },
+      {
+        flag: "--mode",
+        type: "string",
+        default: "generate",
+        appliesTo: optionAppliesTo("mode"),
+        summary: "Select the command when no command word is given. Values: generate, validate, check, report, init, setup, explain, diff, describe, skill. A command word and --mode must name the same command; a contradiction is a usage error (exit 2)."
+      },
+      {
+        flag: "--cwd",
+        type: "string",
+        default: "process.cwd()",
+        appliesTo: optionAppliesTo("cwd"),
+        summary: "Repository to operate on. Must be an existing directory."
+      },
+      {
+        flag: "--dry-run",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("dry-run"),
+        summary: "Compute everything and print the result without writing."
+      },
+      {
+        flag: "--watch",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("watch"),
+        summary: "Regenerate on every change until interrupted."
+      },
+      {
+        flag: "--no-config",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("no-config"),
+        summary: "Ignore the config file and run on the built-in defaults."
+      },
+      {
+        flag: "--preset",
+        type: "string",
+        default: "detected",
+        appliesTo: optionAppliesTo("preset"),
+        summary: "Force a project preset instead of detecting one. Unknown names are a usage error."
+      },
+      {
+        flag: "--include",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("include"),
+        summary: "Comma-separated allow-list of globs to record in the generated config."
+      },
+      {
+        flag: "--exclude",
+        type: "string",
+        default: "unset",
+        appliesTo: optionAppliesTo("exclude"),
+        summary: "Comma-separated globs to record in the generated config."
+      },
+      {
+        flag: "--yes",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("yes"),
+        summary: "Accept every default without prompting. Required in a non-TTY."
+      },
+      {
+        flag: "--force",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("force"),
+        summary: "Overwrite an existing config file."
+      },
+      {
+        flag: "--autopilot",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("autopilot"),
+        summary: "Set the project up without asking, then generate: detect the preset, write the config and .gitignore, add the npm scripts and devDependency, install with the project's own package manager, generate. Never overwrites an existing config, and never prompts. Refuses an empty directory (exit 1); contradicts --no-config (exit 2)."
+      },
+      {
+        flag: "--install",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("install"),
+        summary: "Write the skill into the repository instead of printing it."
+      },
+      {
+        flag: "--target",
+        type: "string",
+        default: "all",
+        appliesTo: optionAppliesTo("target"),
+        summary: 'Where to install: "claude", "cursor" or "all".'
+      },
+      {
+        flag: "--no-install",
+        type: "boolean",
+        default: false,
+        appliesTo: optionAppliesTo("no-install"),
+        summary: "Skip installing the dependency before generating: `setup`, or `generate --autopilot` (CI, offline, or a lockfile you do not want a package manager to touch)."
+      }
+    ],
+    presets: PRESETS.map((preset) => ({
+      name: preset.name,
+      priority: preset.priority,
+      recommendedBudget: preset.recommendedBudget ?? "300k",
+      excludes: preset.exclude ? [...preset.exclude] : []
+    })),
+    artifacts: ARTIFACT_NAMES.map((name) => ({
+      name,
+      default: ARTIFACT_DEFAULTS[name] ?? true,
+      summary: ARTIFACT_SUMMARY[name] ?? name
+    })),
+    config: {
+      fileNames: [
+        "snapshot.config.ts",
+        "snapshot.config.js",
+        "snapshot.config.mjs",
+        "snapshot.config.cjs",
+        "snapshot.config.json",
+        ".snapshotrc.json",
+        ".snapshotrc",
+        'package.json \u2192 "snapshot" key'
+      ],
+      settings: [
+        { key: "outDir", type: "string", default: "snapshot", summary: "Snapshot output directory." },
+        { key: "tmpDir", type: "string", default: "snapshot.tmp", summary: "Scratch directory used for the atomic swap." },
+        { key: "branch", type: "string", default: "main", summary: "Branch recorded when git cannot report one." },
+        { key: "preset", type: "string", default: "detected", summary: "Force a preset. Unknown names are an error." },
+        { key: "maxPartBytes", type: "number | string", default: 307200, summary: "Per-part byte budget." },
+        { key: "largeFileBytes", type: "number | string", default: 204800, summary: "Preview threshold for large files." },
+        { key: "previewHeadLines", type: "number", default: 80, summary: "Lines kept from the head of a large file." },
+        { key: "previewTailLines", type: "number", default: 40, summary: "Lines kept from the tail of a large file." },
+        { key: "includeMonolith", type: "boolean", default: false, summary: "Also write the single-file monolith." },
+        { key: "maxMonolithBytes", type: "number | string | null", default: null, summary: "Skip the monolith above this size." },
+        { key: "includeSensitiveFiles", type: "boolean", default: false, summary: "Emit .env / *.pem / credential files." },
+        { key: "include", type: "string[]", default: "[]", summary: "Allow-list of globs; empty means everything." },
+        { key: "excludePatterns", type: "string[]", default: "[]", summary: "Extra exclude globs." },
+        { key: "discovery", type: '"auto" | "git" | "walk"', default: "auto", summary: "How files are discovered; `walk` scans the tree and reads .gitignore directly when a .git directory cannot be listed." },
+        { key: "artifacts", type: "object", default: "all on except monolith", summary: "Per-artifact opt-out." },
+        { key: "budgets", type: "object", default: "{ default, byLayer }", summary: "Per-layer byte budgets." },
+        { key: "layersMode", type: '"merge" | "replace"', default: "merge", summary: "Whether custom layers extend or replace the preset's." },
+        { key: "layers", type: "array", default: "preset layers", summary: "Custom layer rules (glob or RegExp)." },
+        { key: "kinds", type: "array", default: "preset kinds", summary: "Custom kind rules." },
+        { key: "secrets", type: "object", default: "{}", summary: "Custom secret patterns, or disable the defaults." },
+        { key: "hooks", type: "object", default: "{}", summary: "afterGenerate(manifest) runs after a successful generate." }
+      ]
+    },
+    output: {
+      layout: [
+        "<outDir>/README.md",
+        "<outDir>/manifest.json",
+        "<outDir>/parts/part-NNN.md",
+        "<outDir>/reports/project-tree.md",
+        "<outDir>/reports/navigation.md",
+        "<outDir>/reports/audit.md",
+        "<outDir>/.codebase-snapshot  (ownership marker, always written)"
+      ],
+      notes: [
+        "Parts are ordered and budget-limited; a single file larger than the budget becomes a head/tail preview.",
+        "manifest.json.files[] carries relativePath, layer, kind, language, part, inclusionMode and hash; `summary` is conditional \u2014 it is absent for languages with no structural summary, and `summaryOmitted: true` marks a summary dropped to fit the part budget; encoding appears when the file was not plain UTF-8.",
+        "manifest.skipped[] carries the path and the exact reason it was excluded.",
+        `The output directory is replaced atomically; ${MIN_MAX_PART_BYTES} bytes is the smallest legal budget.`
+      ]
+    },
+    safety: [
+      "Sensitive files (.env, *.pem, .npmrc, .ssh/, .tfstate) are excluded by default and listed in manifest.skipped[].",
+      "Secret-shaped strings in ordinary source files are redacted in the emitted parts.",
+      "The tool refuses to replace an outDir that it did not create, so a mistyped outDir cannot delete source code.",
+      "Nothing is ever written above the repository root; --out-dir may not be the root or an ancestor."
+    ],
+    mcp: {
+      command: `npx ${PACKAGE_NAME} mcp`,
+      transport: "stdio",
+      protocolVersions: {
+        modern: [...MODERN_PROTOCOL_VERSIONS],
+        legacy: [...LEGACY_PROTOCOL_VERSIONS],
+        default: DEFAULT_LEGACY_PROTOCOL_VERSION
+      },
+      tools: buildTools().map((tool) => ({
+        name: tool.name,
+        title: tool.title,
+        summary: tool.description,
+        readOnly: tool.annotations.readOnlyHint,
+        parameters: Object.keys(tool.inputSchema.properties),
+        required: tool.inputSchema.required ?? []
+      })),
+      prompts: buildPrompts().map((prompt) => ({
+        name: prompt.name,
+        summary: prompt.description,
+        arguments: prompt.arguments.map((argument) => argument.name)
+      })),
+      resources: [...STATIC_RESOURCE_URIS],
+      resourceTemplates: [...RESOURCE_TEMPLATE_URIS],
+      notes: [
+        "stdout carries JSON-RPC messages only; every note and log line goes to stderr.",
+        "The server speaks both protocol eras: the legacy `initialize` handshake and the stateless revision, which is detected from `server/discover` or from per-request `_meta`.",
+        "Everything it can do is a subset of the CLI. It never installs packages and never writes a config file.",
+        "A `root` argument may name a sub-directory of the server's --cwd, and nothing outside it is readable."
+      ]
+    },
+    troubleshooting: [
+      {
+        symptom: "Command prints nothing and exits 0",
+        cause: "A stale global install of this package (often a leftover `npm link`) is shadowing npx: npm runs the global binary instead of installing the published one.",
+        fix: "Check `npm ls -g --depth=0` for codebase-snapshot and remove it with `npm rm -g codebase-snapshot`. If it is not installed globally, clear the npx cache with `npm cache clean --force` and retry."
+      },
+      {
+        symptom: "Exit 1 with 'Refusing to replace outDir'",
+        cause: "The outDir exists and contains files this tool did not write.",
+        fix: "Choose a new/empty --out-dir, or delete the existing directory yourself."
+      },
+      {
+        symptom: "Exit 1 with 'The config file could not be read'",
+        cause: "snapshot.config.* exists but does not parse.",
+        fix: "Fix the syntax, or delete the config to use the defaults."
+      },
+      {
+        symptom: "Exit 1 from validate",
+        cause: "The snapshot no longer matches the files on disk.",
+        fix: "Re-run generate."
+      },
+      {
+        symptom: "A directory you expected is missing from the snapshot",
+        cause: "It is excluded by the preset, by default ignores, or by your own globs.",
+        fix: "Run `explain <path>`; manifest.skipped[] also records the reason for every file."
+      }
+    ]
+  };
+}
+
+// src/agent/skill.ts
+var PACKAGE_NAME2 = "codebase-snapshot";
+var MAJOR_VERSION2 = GENERATOR_VERSION.split(".")[0];
+var SKILL_NAME = "codebase-snapshot";
+function renderSkill() {
+  return `---
+name: ${SKILL_NAME}
+description: Create an LLM-ready snapshot of a repository (size-budgeted markdown parts, a JSON manifest, project tree, navigation and a secret audit) when a whole codebase has to be read, summarized or handed to a model that cannot clone it. Use when asked to snapshot a codebase, prepare repository context, or analyze a project's structure.
+version: ${GENERATOR_VERSION}
+---
+
+# codebase-snapshot
+
+Turns a repository into an LLM-ready snapshot under \`./snapshot/\`: code packed into
+size-budgeted markdown parts, plus a manifest that indexes every file, a project tree, a
+navigation index and a secret audit.
+
+Use it when you need to understand a whole repository, or produce repository context for
+another model, and reading files one by one would not fit in context.
+
+## Before you start
+
+This tool is a Node CLI. It needs **Node.js 18 or newer**. You do not need to install it
+globally, and you do not need to clone anything.
+
+**Pin a version** \u2014 \`npx ${PACKAGE_NAME2}@${GENERATOR_VERSION} <command>\` \u2014 when you
+need the same version on every machine. The bare package name works too: this package ships
+one executable file, published under two names (\`codebase-snapshot\` and \`snapshot\`), which is
+what lets npm pick it. A global install gives the short command \`snapshot\`; inside a project
+that has this package installed, \`npx snapshot\` resolves the local copy first. If a command
+exits 0 printing nothing, the executable was not resolved \u2014 clear the npm cache and retry;
+do not assume the repository is broken.
+
+## Step by step
+
+1. **Verify the tool.** Run \`npx ${PACKAGE_NAME2}@latest --version\`. Expect \`v${MAJOR_VERSION2}\` or
+   newer on stdout \u2014 compare the major version, not the patch, because the
+   \`@latest\` tag can lag this release. If what it prints is older, pin the exact
+   release (\`@${GENERATOR_VERSION}\`) instead of retrying. Empty output means you hit the
+   bare-spec problem above.
+
+2. **Read the contract, not the prose.** Run
+   \`npx ${PACKAGE_NAME2}@latest describe --format json\`. It returns the full machine
+   contract: every command, every option with its default, the exit-code meanings, the
+   25 project presets, the artifact list, the config settings and a troubleshooting
+   table. Read it before you make decisions; do not guess option names.
+
+3. **Look before you leap (optional but cheap).** To see how a specific file or directory
+   would be treated, run \`npx ${PACKAGE_NAME2}@latest explain <path>\`. It reports the
+   layer, kind, language, target part, and the exact reason a path would be skipped.
+   \`--format json\` if you want to parse it.
+
+3b. **One command, if the user just wants it working.** \`npx ${PACKAGE_NAME2}@latest setup\`
+   does steps 4\u20136 in one go with defaults: it writes the config (an existing one is kept),
+   adds the npm scripts and the devDependency, installs with the project's package manager,
+   and generates. Use \`--no-install\` when the machine is offline or the user does not want
+   their lockfile touched. \`--autopilot\` does exactly the same thing from the default
+   command (\`npx ${PACKAGE_NAME2}@latest --autopilot\`) and is the form to reach for when a
+   single invocation must both set the project up and produce the snapshot. Prefer the
+   explicit steps below when you need to control any of those, or when something fails and
+   you want to see which part.
+
+4. **Configure (recommended).** Run \`npx ${PACKAGE_NAME2}@latest init --yes\`. It detects
+   the project shape, then writes a commented config file listing **every** setting at its
+   current value. The filename depends on the project: \`snapshot.config.ts\` only when
+   the running Node can strip types (Node >= 22.6) **and** the project is an ES module
+   (\`"type": "module"\` in package.json); otherwise \`snapshot.config.mjs\`. Pass
+   \`--preset <name>\` only if detection is wrong; the preset names are in the contract.
+   Skipping this step is safe **at a terminal**: the first \`generate\` asks once, can write
+   the config for you and then generates. Unattended, a \`generate\` with no config exits 2 \u2014
+   run this step, or \`--autopilot\`, or pass \`--no-config\` to run deliberately on the
+   built-in defaults.
+
+5. **Generate.** Run \`npx ${PACKAGE_NAME2}@latest generate\`. Expect exit 0 and a
+   \`./snapshot/\` directory. If you need a different location use \`--out-dir <path>\`; if
+   you need smaller or larger parts use \`--max-part-bytes 120k\`.
+
+6. **Verify.** Run \`npx ${PACKAGE_NAME2}@latest validate\`. Exit 0 means the snapshot
+   matches the files on disk. Exit 1 means drift \u2014 re-run step 5.
+
+7. **Read the output in this order:**
+   - \`snapshot/parts/part-*.md\` \u2014 the code itself, each file tagged with its layer, kind,
+     language and, when it fits the budget, a structural summary (imports, exports,
+     classes, functions). A dropped summary appears as a \`Summary: (omitted \u2026)\` line.
+   - \`snapshot/manifest.json\` \u2014 the index. \`files[]\` has \`relativePath\`, \`layer\`,
+     \`kind\`, \`language\`, \`part\`, \`inclusionMode\` and \`hashSha256\`, plus \`encoding\`
+     when the file was not plain UTF-8. \`summary\` is **optional**: it is absent for
+     languages with no structural summary, and \`summaryOmitted: true\` marks one dropped
+     to fit the part budget \u2014 never assume it exists.
+     \`skipped[]\` records every excluded file **and why**. Prefer querying this over
+     re-reading the parts.
+   - \`snapshot/reports/audit.md\` \u2014 secrets found, large files, parse diagnostics, git
+     state. Read this before you quote code back to a user.
+   - \`snapshot/reports/project-tree.md\` and \`navigation.md\` \u2014 structure and cross-links.
+
+## Project types
+
+Detection is automatic and covers Next.js, Nuxt, SvelteKit, Remix, Astro, Angular, Solid,
+Vue+React with Vite, Nest, Express/Fastify/Koa, any Node library, monorepos, Django,
+FastAPI/Flask, plain Python, Go, Rust, Java/Spring, .NET, PHP/Laravel, Ruby/Rails,
+Terraform/Docker infra, docs-only repositories, and a generic fallback. It sets sensible
+layers, kinds, ecosystem ignore patterns and a recommended part budget. For non-TypeScript
+languages it extracts imports, exports, classes and functions structurally; Vue, Svelte and
+Astro script blocks go through the real TypeScript compiler. You do not need to configure
+any of this to get a good first snapshot.
+
+## Things that will surprise you
+
+- **Sensitive files are excluded by default** (\`.env\`, \`*.pem\`, \`.npmrc\`, \`.ssh/\`,
+  \`.tfstate\`) and are listed in \`manifest.skipped[]\`. Add \`--include-sensitive-files\` only
+  if the user asks for them explicitly.
+- **Secret-shaped strings inside normal source files are redacted** in the emitted parts.
+  If the user needs the raw value, say so rather than working around it.
+- **The output directory is owned by the tool.** It is replaced atomically, and the tool
+  refuses to replace a directory it did not create. Never point \`--out-dir\` at source
+  code; if you see \`Refusing to replace outDir\`, choose a new directory rather than
+  deleting anything.
+- **Exit 2 is a usage error**, not a failure of the repository. Re-read the contract
+  before retrying.
+- **A first run refuses rather than guessing.** In a project with no config and no previous
+  snapshot, \`generate\` without a terminal exits 2 instead of silently using defaults. That
+  is deliberate: say which set-up you want (\`--autopilot\`, \`init --yes\`, or \`--no-config\`)
+  rather than retrying the same command.
+- **\`--format json\` keeps stdout pure.** Progress goes to stderr, so \`stdout\` is safe to
+  pipe into a JSON parser.
+
+## Making this available to other agents
+
+Run \`npx ${PACKAGE_NAME2}@latest skill --install\`. It writes this skill into the two
+registries agent tools read by name \u2014 \`.claude/skills/${SKILL_NAME}/SKILL.md\` and
+\`.cursor/rules/${SKILL_NAME}.mdc\` \u2014 and appends exactly those files to \`.gitignore\`, so the
+install leaves nothing untracked. It is idempotent, and it refuses a target that resolves
+outside the repository, so a linked \`.claude/\` cannot be used to write elsewhere.
+
+It never writes \`AGENTS.md\`. That file is the repository's own agent contract \u2014 build
+commands, conventions, house rules \u2014 and this tool has no business editing it. If you want
+this skill in there, run \`npx ${PACKAGE_NAME2}@latest skill\` and paste the text yourself: the
+diff, and the commit, are then yours.
+
+## When the client speaks MCP
+
+If the agent runs inside an MCP client, \`npx ${PACKAGE_NAME2}@latest mcp\` serves this repository
+as seven tools over stdio instead of shelling out. Its reads come from the snapshot rather than
+the working tree, so excluded files and redacted values never reach the context. Use
+\`snapshot_locate\` before \`snapshot_read\`, and \`snapshot_validate\` before trusting a snapshot
+from an earlier session.
+`;
+}
+
+// src/mcp/resources.ts
+var MAX_RESOURCE_BYTES = 512 * 1024;
+var PART_URI = /^snapshot:\/\/parts\/(\d+)$/;
+var REPORT_URIS = /* @__PURE__ */ new Map([
+  ["snapshot://reports/audit", { file: "audit.md", title: "Secret audit and risk findings" }],
+  ["snapshot://reports/tree", { file: "project-tree.md", title: "Project tree" }],
+  ["snapshot://reports/navigation", { file: "navigation.md", title: "Navigation index" }]
+]);
+function formatBytes2(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} kB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function truncationMarker(originalBytes) {
+  return `
+
+[truncated: ${formatBytes2(originalBytes)} total. Use the snapshot_read tool for a line window.]
+`;
+}
+function capUtf8(text, limit) {
+  const size = Buffer.byteLength(text, "utf8");
+  if (size <= limit) return { text, truncated: false };
+  const cut = Buffer.from(text, "utf8").subarray(0, limit).toString("utf8").replace(/\uFFFD+$/, "");
+  return { text: `${cut}${truncationMarker(size)}`, truncated: true };
+}
+async function workspaceFor(context) {
+  const root = resolveRoot(void 0, context);
+  if (!root.ok) return { error: root.message };
+  const opened = await openWorkspace(root.root);
+  if (!opened.ok) return { error: opened.message };
+  return opened.workspace;
+}
+function readFileIfPresent(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+function buildResourceProvider() {
+  return {
+    async list(context) {
+      const resources = [
+        {
+          uri: "snapshot://manifest",
+          name: "manifest",
+          title: "Snapshot manifest",
+          description: "Every file in the snapshot with its layer, kind, language, part and hash, plus the reason each excluded file was excluded.",
+          mimeType: "application/json"
+        },
+        {
+          uri: "snapshot://contract",
+          name: "contract",
+          title: "Tool contract",
+          description: "The machine-readable description of the codebase-snapshot command line.",
+          mimeType: "application/json"
+        },
+        {
+          uri: "snapshot://skill",
+          name: "skill",
+          title: "Agent skill",
+          description: "Usage guidance for an agent working with this tool.",
+          mimeType: "text/markdown"
+        }
+      ];
+      for (const [uri, report] of REPORT_URIS) {
+        resources.push({
+          uri,
+          name: report.file.replace(/\.md$/, ""),
+          title: report.title,
+          description: `${report.title} from the most recent snapshot.`,
+          mimeType: "text/markdown"
+        });
+      }
+      const workspace = await workspaceFor(context);
+      if ("error" in workspace) return resources;
+      const read = readManifest(workspace);
+      if (!read.ok) return resources;
+      for (const part of read.manifest.parts) {
+        resources.push({
+          uri: `snapshot://parts/${part.index}`,
+          name: `part-${String(part.index).padStart(3, "0")}`,
+          title: `Part ${part.index} (${part.fileCount} files, ${formatBytes2(part.byteSize)})`,
+          description: `Part ${part.index} of ${read.manifest.parts.length}: ${part.fileCount} file(s), ${part.lines} line(s), ${formatBytes2(part.byteSize)}.`,
+          mimeType: "text/markdown"
+        });
+      }
+      return resources;
+    },
+    templates() {
+      return [
+        {
+          uriTemplate: "snapshot://parts/{index}",
+          name: "part",
+          title: "Snapshot part",
+          description: "One budgeted part of the snapshot, by its 1-based index.",
+          mimeType: "text/markdown"
+        }
+      ];
+    },
+    async read(uri, context) {
+      if (uri === "snapshot://contract") {
+        const contract = buildAgentContract();
+        return { uri, mimeType: "application/json", text: JSON.stringify(contract, null, 2) };
+      }
+      if (uri === "snapshot://skill") {
+        return { uri, mimeType: "text/markdown", text: renderSkill() };
+      }
+      const workspace = await workspaceFor(context);
+      if ("error" in workspace) return null;
+      const report = REPORT_URIS.get(uri);
+      if (report) {
+        const text = readFileIfPresent(
+          path2.resolve(workspace.root, workspace.config.outDir, "reports", report.file)
+        );
+        if (text === null) return null;
+        return { uri, mimeType: "text/markdown", text: capUtf8(text, MAX_RESOURCE_BYTES).text };
+      }
+      if (uri === "snapshot://manifest") {
+        const read = readManifest(workspace);
+        if (!read.ok) return null;
+        const text = readFileIfPresent(read.file) ?? JSON.stringify(read.manifest, null, 2);
+        return { uri, mimeType: "application/json", text: capUtf8(text, MAX_RESOURCE_BYTES).text };
+      }
+      const partMatch = PART_URI.exec(uri);
+      if (partMatch) {
+        const read = readManifest(workspace);
+        if (!read.ok) return null;
+        const index = Number(partMatch[1]);
+        const part = read.manifest.parts.find((candidate) => candidate.index === index);
+        if (!part) return null;
+        const text = readFileIfPresent(
+          path2.resolve(workspace.root, workspace.config.outDir, "parts", part.filename)
+        );
+        if (text === null) return null;
+        return { uri, mimeType: "text/markdown", text: capUtf8(text, MAX_RESOURCE_BYTES).text };
+      }
+      return null;
+    }
+  };
+}
+
+// src/mcp/instructions.ts
+var SERVER_INSTRUCTIONS = [
+  "codebase-snapshot serves this repository as a size-budgeted snapshot, not as a directory walk.",
+  "",
+  "Work in this order:",
+  "1. snapshot_status \u2014 is there a snapshot here, and has the tree moved since it was built?",
+  "2. snapshot_locate \u2014 find which part holds the code you need.",
+  "3. snapshot_read \u2014 read a window of one file. Never read a part end to end.",
+  "4. snapshot_validate \u2014 before trusting context that came from an earlier conversation.",
+  "",
+  "Rules that matter:",
+  "- Parts are budgeted, not small: a 12-part snapshot is hundreds of kilobytes. Use snapshot_locate first.",
+  "- A file absent from the snapshot has a recorded reason. Ask snapshot_explain, do not assume.",
+  "- snapshot_generate is the only tool that writes. It never installs packages and never writes config.",
+  "- Paths are relative to the repository root the server was started for, and nothing outside it is readable."
+].join("\n");
+
+// src/mcp/stdio.ts
+var MAX_LINE_BYTES = 32 * 1024 * 1024;
+function createWriter(output) {
+  return {
+    write(value) {
+      return new Promise((resolve4, reject) => {
+        output.write(`${JSON.stringify(value)}
+`, (error) => {
+          if (error) reject(error);
+          else resolve4();
+        });
+      });
+    }
+  };
+}
+function createLineReader(input, options) {
+  let buffer = "";
+  let discarding = false;
+  let discardedBytes = 0;
+  const deliver = (line) => {
+    if (discarding) {
+      discarding = false;
+      discardedBytes = 0;
+      return;
+    }
+    const trimmed = line.endsWith("\r") ? line.slice(0, -1) : line;
+    if (trimmed.trim().length === 0) return;
+    options.onLine(trimmed);
+  };
+  const drain = () => {
+    let index = buffer.indexOf("\n");
+    while (index >= 0) {
+      const line = buffer.slice(0, index);
+      buffer = buffer.slice(index + 1);
+      deliver(line);
+      index = buffer.indexOf("\n");
+    }
+  };
+  const onData = (chunk) => {
+    if (discarding) {
+      const index = chunk.indexOf("\n");
+      if (index < 0) {
+        discardedBytes += chunk.length;
+        return;
+      }
+      buffer = chunk.slice(index + 1);
+      deliver("");
+      drain();
+      return;
+    }
+    buffer += chunk;
+    if (buffer.length > MAX_LINE_BYTES && buffer.indexOf("\n") < 0) {
+      discarding = true;
+      discardedBytes = buffer.length;
+      buffer = "";
+      options.onOverflow?.(discardedBytes);
+      return;
+    }
+    drain();
+  };
+  const onEnd = () => {
+    if (buffer.length > 0) {
+      const rest = buffer;
+      buffer = "";
+      deliver(rest);
+    }
+  };
+  input.setEncoding("utf8");
+  input.on("data", onData);
+  input.on("end", onEnd);
+  return () => {
+    input.off("data", onData);
+    input.off("end", onEnd);
+  };
+}
+
+// src/mcp/run.ts
+var PROJECT_URL = "https://ankurhalder.github.io/codebase-snapshot/";
+function createServer(options) {
+  const cwd = options.cwd;
+  const roots = options.roots && options.roots.length > 0 ? options.roots : [cwd];
+  const context = {
+    cwd,
+    roots,
+    log: options.log ?? ((line) => process.stderr.write(`${line}
+`))
+  };
+  return createMcpServer({
+    info: {
+      name: GENERATOR_NAME,
+      title: "codebase-snapshot",
+      version: GENERATOR_VERSION,
+      websiteUrl: PROJECT_URL
+    },
+    instructions: SERVER_INSTRUCTIONS,
+    tools: buildTools(),
+    resources: buildResourceProvider(),
+    prompts: buildPrompts(),
+    context
+  });
+}
+async function runStdioServer(options) {
+  const log = options.log ?? ((line) => process.stderr.write(`${line}
+`));
+  const server = createServer(options);
+  const writer = createWriter(process.stdout);
+  let writeChain = Promise.resolve();
+  const send = (message) => {
+    writeChain = writeChain.then(() => writer.write(message)).catch((error) => {
+      log(`mcp: could not write a response: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return writeChain;
+  };
+  let inFlight = 0;
+  let inputEnded = false;
+  let resolveDone = () => void 0;
+  const finished = new Promise((resolve4) => {
+    resolveDone = resolve4;
+  });
+  const finishIfIdle = () => {
+    if (inputEnded && inFlight === 0) resolveDone(0);
+  };
+  const handleLine = async (line) => {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      await send(errorResponse(null, ERROR_CODES.parseError, "Message is not valid JSON."));
+      return;
+    }
+    const response = await server.handle(message);
+    if (response) await send(response);
+  };
+  const stopReading = createLineReader(process.stdin, {
+    onOverflow: (bytes) => log(`mcp: discarded an oversized message (${bytes} bytes)`),
+    onLine: (line) => {
+      inFlight += 1;
+      void handleLine(line).finally(() => {
+        inFlight -= 1;
+        finishIfIdle();
+      });
+    }
+  });
+  const onEnd = () => {
+    inputEnded = true;
+    finishIfIdle();
+  };
+  process.stdin.on("end", onEnd);
+  process.stdin.on("close", onEnd);
+  log(`mcp: serving ${options.cwd} over stdio`);
+  const code = await finished;
+  stopReading();
+  process.stdin.off("end", onEnd);
+  process.stdin.off("close", onEnd);
+  await writeChain;
+  return code;
+}
+
+export { COMMAND_OPTION_SCOPE, ERROR_CODES, LEGACY_PROTOCOL_VERSIONS, MAX_LINE_BYTES, METHOD, MODERN_PROTOCOL_VERSIONS, SERVER_INSTRUCTIONS, SKILL_NAME, SUPPORTED_PROTOCOL_VERSIONS, buildAgentContract, buildPrompts, buildResourceProvider, buildTools, classifyRequest, commandsForOption, createLineReader, createMcpServer, createServer, createSession, createWriter, inspectModernMeta, negotiateLegacyVersion, renderContractText, renderSkill, runStdioServer, validateArguments };
+//# sourceMappingURL=chunk-EWZYK3VX.js.map
+//# sourceMappingURL=chunk-EWZYK3VX.js.map