codebase-snapshot 0.9.0 → 0.9.4

package/dist/cli.js

@@ -1,750 +1,10 @@
-import { GENERATOR_VERSION, loadConfigFileDetailed, resolveConfig, validateSnapshot, describeManifestShapeProblem, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, formatNumber, isDiscoveryMode, ARTIFACT_NAMES, getPreset, unknownPresetMessage, GENERATOR_NAME, runInit, PromptCancelled, MIN_MAX_PART_BYTES, SCHEMA_VERSION, PRESETS, parseByteSize, gitignorePath, appendGitignoreEntries, escapeControls, renderExplainText } from './chunk-FJ4RQYY2.js';
+import { buildAgentContract, runStdioServer, COMMAND_OPTION_SCOPE, commandsForOption, SKILL_NAME, renderSkill, renderContractText } from './chunk-EWZYK3VX.js';
+import { loadConfigFileDetailed, resolveConfig, validateSnapshot, describeManifestShapeProblem, explainPath, compareManifests, loadManifest, renderDiffText, generateSnapshot, formatNumber, GENERATOR_VERSION, isDiscoveryMode, ARTIFACT_NAMES, getPreset, unknownPresetMessage, GENERATOR_NAME, runInit, PromptCancelled, planFirstRun, isEffectivelyEmpty, isInteractive, defaultIO, hasPriorSnapshot, DEFAULT_ANSWERS, findConfigFile, firstRunMessage, parseByteSize, gitignorePath, appendGitignoreEntries, escapeControls, MIN_MAX_PART_BYTES, renderExplainText } from './chunk-FCWD4LY7.js';
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path2 from 'path';
 import { parseArgs } from 'util';
 
-// 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",
-    "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"],
-  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"
-];
-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("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", "snap"],
-      notes: [
-        `The bare package name also works: npx ${PACKAGE_NAME} <command>.`,
-        "Pin an exact version \u2014 for example `codebase-snapshot@0.9.0` \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.",
-        "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 4.0.7 today and 4.0.9 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.",
-        positionals: [],
-        exits: [0, 1]
-      },
-      {
-        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]
-      }
-    ],
-    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: "--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: "setup only: skip installing the dependency before generating (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."
-    ],
-    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 \`snap\`), which is what
-lets npm pick it. 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. 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.
-   This step is optional: without a config the tool runs on the same 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.
-- **\`--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.
-`;
-}
-
-// src/agent/install-skill.ts
 var SKILL_TARGETS = ["claude", "cursor", "all"];
 var REFUSED = "Refusing to install the agent skill";
 var LEGACY_AGENTS_MARKER = "<!-- codebase-snapshot:skill:start -->";
@@ -845,7 +105,8 @@ var COMMAND_ALIASES = /* @__PURE__ */ new Map([
   ["explain", "explain"],
   ["diff", "diff"],
   ["describe", "describe"],
-  ["skill", "skill"]
+  ["skill", "skill"],
+  ["mcp", "mcp"]
 ]);
 var COMMAND_ARITY = {
   generate: 0,
@@ -856,7 +117,8 @@ var COMMAND_ARITY = {
   explain: 1,
   diff: 2,
   describe: 0,
-  skill: 0
+  skill: 0,
+  mcp: 0
 };
 var CLI_OPTIONS = {
   cwd: { type: "string" },
@@ -879,6 +141,7 @@ var CLI_OPTIONS = {
   exclude: { type: "string" },
   yes: { type: "boolean" },
   force: { type: "boolean" },
+  autopilot: { type: "boolean" },
   install: { type: "boolean" },
   "no-install": { type: "boolean" },
   target: { type: "string" },
@@ -894,6 +157,14 @@ Production-grade LLM codebase snapshot generator, auditor, and AST partitioner
 Usage:
   codebase-snapshot [command] [options]
 
+First run:
+  codebase-snapshot                No config yet: asks once, sets the project up, generates.
+                                   A configured project just generates. It never falls back
+                                   to defaults it was not given.
+  codebase-snapshot --autopilot    The same without questions: detect the preset, write the
+                                   config, add the npm scripts and devDependency, install,
+                                   then generate.
+
 Commands:
   setup                Everything at once: config, scripts, dependency, install, generate
   generate (default)   Generate a complete partitioned codebase snapshot
@@ -904,6 +175,7 @@ Commands:
   diff <a> <b>         Compare two snapshots (directories or manifest.json files)
   describe             Print the machine-readable contract (--format json for agents)
   skill                Print the bundled agent skill; --install writes it into the repo
+  mcp                  Serve this repository to an MCP client over stdio
 
 Options:
   --cwd <path>                  Target repository directory (default: current directory)
@@ -926,6 +198,12 @@ Options:
                                 auto: git when usable. git: require git. walk: read
                                 .gitignore directly (escape hatch for a broken .git)
 
+  generate only:
+  --autopilot                   Set the project up without asking, then generate: write the
+                                config and .gitignore, add the npm scripts and devDependency,
+                                and install with the project's own package manager.
+  --no-install                  With --autopilot: skip the dependency install.
+
   init only:
   --preset <name>               Force a project preset instead of detecting one
   --include <globs>             Comma-separated allow-list
@@ -1140,8 +418,17 @@ function parseCliArgs(argv) {
       `--target must be one of: ${SKILL_TARGETS.join(", ")} (received "${String(values.target)}").`
     );
   }
+  if (values["no-install"] === true && command === "generate" && values.autopilot !== true) {
+    throw new UsageError("--no-install only applies to `setup`, or to `generate --autopilot`.");
+  }
+  if (values.autopilot === true && values["no-config"] === true) {
+    throw new UsageError(
+      "--autopilot sets a project up and writes a config; --no-config ignores config files. Pass one or the other."
+    );
+  }
   return {
     command,
+    explicitCommand: firstPositional !== void 0 || explicitMode !== void 0,
     args,
     format: rawFormat,
     dryRun: values["dry-run"] === true,
@@ -1153,6 +440,7 @@ function parseCliArgs(argv) {
     exclude: values.exclude === void 0 ? void 0 : String(values.exclude),
     yes: values.yes === true,
     force: values.force === true,
+    autopilot: values.autopilot === true,
     install: values.install === true,
     noInstall: values["no-install"] === true,
     target: values.target === void 0 ? void 0 : String(values.target),
@@ -1233,6 +521,9 @@ function nextStepHint(cwd, scriptsAddedNow) {
   const installed = fs.existsSync(bin) || fs.existsSync(`${bin}.cmd`);
   return installed ? "npm run snapshot" : "npm install && npm run snapshot";
 }
+function presetSummary(init) {
+  return init.reason === null ? `preset: ${init.preset}` : `preset: ${init.preset}, because ${init.reason}`;
+}
 async function runInitCommand(invocation) {
   try {
     const result = await runInit({
@@ -1257,7 +548,7 @@ async function runInitCommand(invocation) {
       info(result.configText);
       return 0;
     }
-    info(`\u2705 Created ${path2.basename(result.configPath)} (preset: ${result.preset})`);
+    info(`\u2705 Created ${path2.basename(result.configPath)} (${presetSummary(result)})`);
     if (result.scripts.length > 0) info(`   Added npm scripts: ${result.scripts.join(", ")}`);
     if (result.dependency.added && result.dependency.range !== null) {
       info(`   Added devDependency: ${result.dependency.name} ${result.dependency.range}`);
@@ -1328,8 +619,9 @@ async function captureStdout(fn) {
     process.stdout.write = original;
   }
 }
-async function runSetupCommand(invocation) {
+async function runSetupCommand(invocation, options = {}) {
   try {
+    const interactive = options.interactive === true;
     const init = await runInit({
       cwd: invocation.cwd,
       preset: invocation.preset,
@@ -1339,7 +631,7 @@ async function runSetupCommand(invocation) {
       exclude: splitList(invocation.exclude),
       skipArtifacts: invocation.skipArtifacts,
       includeSensitiveFiles: invocation.includeSensitiveFiles,
-      yes: true,
+      yes: !interactive,
       force: invocation.force,
       reuseConfig: true,
       dryRun: invocation.dryRun
@@ -1376,11 +668,11 @@ async function runSetupCommand(invocation) {
       return 0;
     }
     if (invocation.format !== "json") {
-      info(`\u{1F680} Setup for: ${invocation.cwd}`);
+      if (!interactive) info(`\u{1F680} Setup for: ${invocation.cwd}`);
       if (init.reused) {
-        info(`\u267B  Keeping ${path2.basename(init.configPath)} (preset: ${init.preset})`);
+        info(`\u267B  Keeping ${path2.basename(init.configPath)} (${presetSummary(init)})`);
       } else {
-        info(`\u2705 Created ${path2.basename(init.configPath)} (preset: ${init.preset})`);
+        info(`\u2705 Created ${path2.basename(init.configPath)} (${presetSummary(init)})`);
       }
       if (init.scripts.length > 0) info(`   Added npm scripts: ${init.scripts.join(", ")}`);
       if (init.dependency.added && init.dependency.range !== null) {
@@ -1409,6 +701,7 @@ async function runSetupCommand(invocation) {
     if ((invocation.skipArtifacts ?? []).length > 0) {
       generateArgs.push("--skip-artifacts", (invocation.skipArtifacts ?? []).join(","));
     }
+    if (invocation.watch) generateArgs.push("--watch");
     if (invocation.format === "json") {
       const generated = await captureStdout(() => main(generateArgs));
       let manifest = null;
@@ -1448,6 +741,24 @@ async function runSetupCommand(invocation) {
     return fail(invocation.format, err.message);
   }
 }
+async function firstRun(invocation) {
+  const plan = planFirstRun({
+    hasConfig: findConfigFile(invocation.cwd) !== null,
+    hasPriorSnapshot: hasPriorSnapshot(invocation.cwd, invocation.outDir ?? DEFAULT_ANSWERS.outDir),
+    // A machine must never be asked a question, and `--format json` is how a machine says so.
+    interactive: invocation.format === "text" && isInteractive(defaultIO()),
+    autopilot: invocation.autopilot,
+    emptyTarget: isEffectivelyEmpty(invocation.cwd)
+  });
+  if (plan.action === "generate") return null;
+  if (plan.action === "refuse") {
+    return fail(invocation.format, firstRunMessage(plan.reason, invocation.cwd), plan.exitCode);
+  }
+  info(
+    plan.interactive ? "\u2699  This project has no snapshot configuration yet." : "\u2699  --autopilot: setting this project up before generating."
+  );
+  return await runSetupCommand(invocation, { interactive: plan.interactive });
+}
 function runSkillCommand(invocation) {
   if (!invocation.install) {
     if (invocation.format === "json") {
@@ -1564,9 +875,16 @@ ${USAGE}
   if (invocation.command === "skill") {
     return runSkillCommand(invocation);
   }
+  if (invocation.command === "mcp") {
+    return await runStdioServer({ cwd: path2.resolve(invocation.cwd) });
+  }
   if (invocation.command === "setup") {
     return runSetupCommand(invocation);
   }
+  if (invocation.command === "generate" && !invocation.noConfig && (!invocation.explicitCommand || invocation.autopilot)) {
+    const decided = await firstRun(invocation);
+    if (decided !== null) return decided;
+  }
   const skipConfig = invocation.noConfig || invocation.command === "diff";
   const loaded = skipConfig ? { config: null, warnings: [], errors: [], file: null } : await loadConfigFileDetailed(invocation.cwd);
   if (invocation.noConfig) info("\u2699  --no-config: using built-in defaults, config file ignored");