codebase-snapshot 0.0.0-stage → 4.5.0

package/dist/cli.js

@@ -0,0 +1,1931 @@
+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-SSCFLILW.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 @latest (or @4) when you need the exact same version on every machine.",
+        "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 major with \`npx ${PACKAGE_NAME}@${MAJOR_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}@${MAJOR_VERSION2} <command>\` (or an exact release) \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 the printed major is older, pin the
+   major (\`@${MAJOR_VERSION2}\`) 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 -->";
+function targetPath(cwd, target) {
+  switch (target) {
+    case "claude":
+      return path2.join(cwd, ".claude", "skills", SKILL_NAME, "SKILL.md");
+    case "cursor":
+      return path2.join(cwd, ".cursor", "rules", `${SKILL_NAME}.mdc`);
+  }
+}
+function assertWritableInsideRepository(cwd, filePath) {
+  const root = fs.realpathSync(cwd);
+  const shown = path2.relative(root, filePath) || filePath;
+  let stat = null;
+  try {
+    stat = fs.lstatSync(filePath);
+  } catch {
+    stat = null;
+  }
+  if (stat !== null && stat.isSymbolicLink()) {
+    throw new Error(
+      `${REFUSED}: ${shown} is a symbolic link or junction. Remove the link, or write the skill into the directory it points at yourself, and run again.`
+    );
+  }
+  if (stat !== null && stat.isFile() && stat.nlink > 1) {
+    throw new Error(
+      `${REFUSED}: ${shown} has ${stat.nlink} hard links, so writing it would also rewrite a file outside the repository. Replace it with an ordinary file and run again.`
+    );
+  }
+  let existing = filePath;
+  const missing = [];
+  while (!fs.existsSync(existing)) {
+    missing.unshift(path2.basename(existing));
+    const parent = path2.dirname(existing);
+    if (parent === existing) break;
+    existing = parent;
+  }
+  const realAncestor = fs.realpathSync(existing);
+  const resolved = missing.length === 0 ? realAncestor : path2.join(realAncestor, ...missing);
+  if (resolved !== root && !resolved.startsWith(`${root}${path2.sep}`)) {
+    throw new Error(
+      `${REFUSED}: ${shown} resolves outside the repository (${resolved}). Move it back inside ${root}, or remove the link, and run again.`
+    );
+  }
+}
+function writeIfChanged(target, filePath, content) {
+  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
+  if (existing === content) return { target, path: filePath, action: "unchanged" };
+  fs.mkdirSync(path2.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+  return { target, path: filePath, action: existing === null ? "created" : "updated" };
+}
+function legacyAgentsNote(cwd) {
+  const filePath = path2.join(cwd, "AGENTS.md");
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    if (!fs.readFileSync(filePath, "utf8").includes(LEGACY_AGENTS_MARKER)) return null;
+  } catch {
+    return null;
+  }
+  return `AGENTS.md still contains the section an earlier version installed (between the "${LEGACY_AGENTS_MARKER}" markers). This command no longer edits that file: it is your project's own agent instructions. Delete the block if you do not want it.`;
+}
+function installSkill(cwd, target = "all") {
+  const skill = renderSkill();
+  const written = [];
+  const notes = [];
+  const wanted = target === "all" ? ["claude", "cursor"] : [target];
+  for (const item of wanted) assertWritableInsideRepository(cwd, targetPath(cwd, item));
+  const createsSomething = wanted.some((item) => !fs.existsSync(targetPath(cwd, item)));
+  if (createsSomething) {
+    assertWritableInsideRepository(cwd, path2.join(cwd, ".gitignore"));
+  }
+  for (const item of wanted) {
+    written.push(writeIfChanged(item, targetPath(cwd, item), skill));
+  }
+  const created = written.filter((item) => item.action === "created").map((item) => gitignorePath(cwd, item.path));
+  const ignore = appendGitignoreEntries(cwd, created);
+  if (ignore.note !== null) notes.push(ignore.note);
+  const legacy = legacyAgentsNote(cwd);
+  if (legacy !== null) notes.push(legacy);
+  return { cwd, written, gitignored: ignore.added, notes };
+}
+function isSkillTarget(value) {
+  return SKILL_TARGETS.includes(value);
+}
+
+// src/cli.ts
+var VERSION = GENERATOR_VERSION;
+var INSTALL_TIMEOUT_MS = 5 * 60 * 1e3;
+var COMMAND_ALIASES = /* @__PURE__ */ new Map([
+  ["generate", "generate"],
+  ["validate", "validate"],
+  ["check", "validate"],
+  ["report", "report"],
+  ["init", "init"],
+  ["setup", "setup"],
+  ["explain", "explain"],
+  ["diff", "diff"],
+  ["describe", "describe"],
+  ["skill", "skill"]
+]);
+var COMMAND_ARITY = {
+  generate: 0,
+  validate: 0,
+  report: 0,
+  init: 0,
+  setup: 0,
+  explain: 1,
+  diff: 2,
+  describe: 0,
+  skill: 0
+};
+var CLI_OPTIONS = {
+  cwd: { type: "string" },
+  "out-dir": { type: "string" },
+  "max-part-bytes": { type: "string" },
+  "large-file-bytes": { type: "string" },
+  "max-monolith-bytes": { type: "string" },
+  "include-monolith": { type: "boolean" },
+  "include-sensitive-files": { type: "boolean" },
+  "skip-artifacts": { type: "string" },
+  "only-artifacts": { type: "string" },
+  format: { type: "string" },
+  mode: { type: "string" },
+  "dry-run": { type: "boolean" },
+  watch: { type: "boolean" },
+  "no-config": { type: "boolean" },
+  discovery: { type: "string" },
+  preset: { type: "string" },
+  include: { type: "string" },
+  exclude: { type: "string" },
+  yes: { type: "boolean" },
+  force: { type: "boolean" },
+  install: { type: "boolean" },
+  "no-install": { type: "boolean" },
+  target: { type: "string" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" }
+};
+var UsageError = class extends Error {
+};
+var USAGE = `
+${GENERATOR_NAME} v${VERSION}
+Production-grade LLM codebase snapshot generator, auditor, and AST partitioner
+
+Usage:
+  codebase-snapshot [command] [options]
+
+Commands:
+  setup                Everything at once: config, scripts, dependency, install, generate
+  generate (default)   Generate a complete partitioned codebase snapshot
+  validate, check      Validate snapshot integrity and check for drift
+  init                 Generate a starter snapshot.config file
+  report               Print codebase health, layer metrics, and secret audit
+  explain <path>       Show how one path would be treated: layer, kind, part, skips
+  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
+
+Options:
+  --cwd <path>                  Target repository directory (default: current directory)
+  --out-dir <path>              Snapshot output directory (default: snapshot)
+  --include-monolith            Also generate full-codebase.json and full-codebase.md
+  --max-monolith-bytes <n>      Skip monolith artefacts larger than n bytes
+  --max-part-bytes <n>          Maximum byte budget per markdown part (default: 307200).
+                                Accepts units: 120k, 1.5mb
+  --large-file-bytes <n>        Threshold for head/tail truncation (default: 204800)
+  --include-sensitive-files     Emit .env / *.pem / .npmrc / credential files
+  --skip-artifacts <names>      Comma-separated artifacts to omit
+                                (readme, manifest, parts, navigation,
+                                 projectTree, audit, monolith)
+  --only-artifacts <names>      Write *only* these artifacts
+  --format <text|json>          CLI output format (default: text)
+  --dry-run                     Compute the snapshot without writing anything
+  --watch                       Re-generate whenever the repository changes
+  --no-config                   Ignore snapshot.config.* and use the built-in defaults
+  --discovery <mode>            auto | git | walk \u2014 how files are discovered.
+                                auto: git when usable. git: require git. walk: read
+                                .gitignore directly (escape hatch for a broken .git)
+
+  init only:
+  --preset <name>               Force a project preset instead of detecting one
+  --include <globs>             Comma-separated allow-list
+  --exclude <globs>             Comma-separated exclude patterns
+  --yes                         Accept every default without prompting
+  --force                       Overwrite an existing config
+
+  setup only:
+  --no-install                  Skip installing the dependency before generating
+  --preset / --include / --exclude / --force   As for init
+
+  skill only:
+  --install                     Write the skill into the repository instead of printing
+  --target <name>               claude | cursor | all (default: all)
+
+  -h, --help                    Display this help message
+  -v, --version                 Display version
+
+All value-taking options also accept the --option=value form.
+Human-readable progress is written to stderr; payloads (--format json) go to stdout.
+Agents with no prior knowledge of this tool should start with: describe --format json
+`.trim();
+function parsePositiveInteger(raw, optionName, minimum) {
+  if (raw === void 0) return void 0;
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new UsageError(`--${optionName} expects a whole number, received "${raw}".`);
+  }
+  const value = Number(trimmed);
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new UsageError(`--${optionName} must be at least ${minimum}, received "${raw}".`);
+  }
+  return value;
+}
+function parseByteOption(raw, optionName, minimum) {
+  if (raw === void 0) return void 0;
+  const value = parseByteSize(raw);
+  if (value === void 0 || !Number.isSafeInteger(value)) {
+    throw new UsageError(
+      `--${optionName} expects a byte count such as 120000 or "120k", received "${raw}".`
+    );
+  }
+  if (value < minimum) {
+    throw new UsageError(`--${optionName} must be at least ${minimum}, received "${raw}".`);
+  }
+  return value;
+}
+function parseArtifactList(raw, flag) {
+  const names = raw.split(",").map((name) => name.trim()).filter(Boolean);
+  if (names.length === 0) {
+    throw new UsageError(
+      `${flag} expects at least one artifact name (${ARTIFACT_NAMES.join(", ")}).`
+    );
+  }
+  const unknown = names.filter((name) => !ARTIFACT_NAMES.includes(name));
+  if (unknown.length > 0) {
+    throw new UsageError(
+      `Unknown artifact(s): ${unknown.join(", ")}. Expected one of: ${ARTIFACT_NAMES.join(", ")}.`
+    );
+  }
+  return names;
+}
+function parseCliArgs(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: CLI_OPTIONS,
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (err) {
+    const message = err.message;
+    const ambiguous = /^Option '(--[^']+)' argument is ambiguous/i.exec(message);
+    if (ambiguous) {
+      throw new UsageError(
+        `${ambiguous[1]} received a value that looks like another flag (for example a negative number). Use the "--option=value" form, and note that sizes must be positive.`
+      );
+    }
+    throw new UsageError(message);
+  }
+  const values = parsed.values;
+  for (const [name, spec] of Object.entries(CLI_OPTIONS)) {
+    if (spec.type !== "string") continue;
+    const raw = values[name];
+    if (raw !== void 0 && String(raw).trim() === "") {
+      throw new UsageError(`--${name} requires a value (received an empty string).`);
+    }
+  }
+  if (values.cwd !== void 0) {
+    const target = String(values.cwd);
+    if (!fs.existsSync(target)) {
+      throw new UsageError(`--cwd directory does not exist: ${target}`);
+    }
+    if (!fs.statSync(target).isDirectory()) {
+      throw new UsageError(`--cwd is not a directory: ${target}`);
+    }
+  }
+  if (values.help) {
+    process.stdout.write(`${USAGE}
+`);
+    throw new HelpRequested();
+  }
+  if (values.version) {
+    process.stdout.write(`v${VERSION}
+`);
+    throw new HelpRequested();
+  }
+  const positionals = parsed.positionals;
+  let command = "generate";
+  let args = [];
+  const explicitMode = values.mode ? String(values.mode) : void 0;
+  const firstPositional = positionals[0];
+  if (firstPositional !== void 0) {
+    const resolved = COMMAND_ALIASES.get(firstPositional);
+    if (!resolved) {
+      throw new UsageError(
+        `Unknown command "${firstPositional}". Expected one of: ${Array.from(COMMAND_ALIASES.keys()).join(", ")}.`
+      );
+    }
+    command = resolved;
+    args = positionals.slice(1);
+  } else if (explicitMode !== void 0) {
+    const resolved = COMMAND_ALIASES.get(explicitMode);
+    if (!resolved) {
+      throw new UsageError(
+        `Unknown --mode "${explicitMode}". Expected one of: ${Array.from(COMMAND_ALIASES.keys()).join(", ")}.`
+      );
+    }
+    command = resolved;
+  }
+  if (explicitMode !== void 0) {
+    const resolvedMode = COMMAND_ALIASES.get(explicitMode);
+    if (!resolvedMode) {
+      throw new UsageError(
+        `Unknown --mode "${explicitMode}". Expected one of: ${Array.from(COMMAND_ALIASES.keys()).join(", ")}.`
+      );
+    }
+    if (firstPositional !== void 0 && resolvedMode !== command) {
+      throw new UsageError(
+        `--mode ${explicitMode} contradicts the command "${firstPositional}". Pass one or the other.`
+      );
+    }
+  }
+  const expectedArgs = COMMAND_ARITY[command];
+  if (args.length !== expectedArgs) {
+    if (command === "explain") {
+      throw new UsageError("explain expects exactly one path.");
+    }
+    if (command === "diff") {
+      throw new UsageError(
+        "diff expects exactly two arguments: two snapshot directories or manifest.json files."
+      );
+    }
+    throw new UsageError(
+      `Unexpected argument(s): ${args.join(" ")}. ${command} takes no positional arguments.`
+    );
+  }
+  const rawFormat = values.format === void 0 ? "text" : String(values.format);
+  if (rawFormat !== "text" && rawFormat !== "json") {
+    throw new UsageError(`--format must be "text" or "json", received "${rawFormat}".`);
+  }
+  const rawDiscovery = values.discovery === void 0 ? void 0 : String(values.discovery);
+  if (rawDiscovery !== void 0 && !isDiscoveryMode(rawDiscovery)) {
+    throw new UsageError(
+      `--discovery must be one of: auto, git, walk (received "${rawDiscovery}").`
+    );
+  }
+  let onlyNamesMonolith = false;
+  const rawSkip = values["skip-artifacts"];
+  const rawOnly = values["only-artifacts"];
+  if (rawSkip !== void 0 && rawOnly !== void 0) {
+    throw new UsageError("--skip-artifacts and --only-artifacts cannot be combined.");
+  }
+  let skipArtifacts;
+  if (rawOnly !== void 0) {
+    const keep = parseArtifactList(String(rawOnly), "--only-artifacts");
+    onlyNamesMonolith = keep.includes("monolith");
+    skipArtifacts = ARTIFACT_NAMES.filter(
+      (name) => !keep.includes(name)
+    );
+  } else if (rawSkip !== void 0) {
+    skipArtifacts = parseArtifactList(String(rawSkip), "--skip-artifacts");
+  }
+  const scope = COMMAND_OPTION_SCOPE[command];
+  const ignored = [];
+  for (const name of Object.keys(CLI_OPTIONS)) {
+    if (scope.includes(name)) continue;
+    const value = values[name];
+    if (value === void 0 || value === false) continue;
+    ignored.push(`--${name}`);
+  }
+  if (ignored.length > 0) {
+    const owners = Array.from(
+      new Set(
+        ignored.flatMap(
+          (flag) => commandsForOption(flag.replace(/^--/, "")).map((owner) => `\`${owner}\``)
+        )
+      )
+    );
+    const hint = ignored.some((flag) => ["--preset", "--include", "--exclude"].includes(flag)) ? " To scope a run, set include/excludePatterns/preset in snapshot.config.ts (or run `codebase-snapshot init` to generate one)." : "";
+    throw new UsageError(
+      `${ignored.join(", ")} ${ignored.length === 1 ? "does" : "do"} not apply to \`${command}\` and ${ignored.length === 1 ? "was" : "were"} not applied. ${ignored.length === 1 ? "It is" : "They are"} accepted by: ${owners.join(", ")}.${hint}`
+    );
+  }
+  if (command === "init" && values.preset !== void 0) {
+    const requested = String(values.preset);
+    if (!getPreset(requested)) throw new UsageError(unknownPresetMessage(requested));
+  }
+  if (command === "skill" && values.target !== void 0 && !isSkillTarget(String(values.target))) {
+    throw new UsageError(
+      `--target must be one of: ${SKILL_TARGETS.join(", ")} (received "${String(values.target)}").`
+    );
+  }
+  return {
+    command,
+    args,
+    format: rawFormat,
+    dryRun: values["dry-run"] === true,
+    watch: values.watch === true,
+    noConfig: values["no-config"] === true,
+    preset: values.preset === void 0 ? void 0 : String(values.preset),
+    maxPartBytesRaw: values["max-part-bytes"] === void 0 ? void 0 : String(values["max-part-bytes"]),
+    include: values.include === void 0 ? void 0 : String(values.include),
+    exclude: values.exclude === void 0 ? void 0 : String(values.exclude),
+    yes: values.yes === true,
+    force: values.force === true,
+    install: values.install === true,
+    noInstall: values["no-install"] === true,
+    target: values.target === void 0 ? void 0 : String(values.target),
+    cwd: values.cwd === void 0 ? process.cwd() : path2.resolve(String(values.cwd)),
+    outDir: values["out-dir"] === void 0 ? void 0 : String(values["out-dir"]),
+    includeMonolith: values["include-monolith"] === true || onlyNamesMonolith === true ? true : void 0,
+    includeSensitiveFiles: values["include-sensitive-files"] === true ? true : void 0,
+    maxPartBytes: parseByteOption(
+      values["max-part-bytes"],
+      "max-part-bytes",
+      MIN_MAX_PART_BYTES
+    ),
+    largeFileBytes: parseByteOption(
+      values["large-file-bytes"],
+      "large-file-bytes",
+      1
+    ),
+    maxMonolithBytes: parseByteOption(
+      values["max-monolith-bytes"],
+      "max-monolith-bytes",
+      1
+    ),
+    skipArtifacts,
+    discovery: isDiscoveryMode(rawDiscovery) ? rawDiscovery : void 0
+  };
+}
+var HelpRequested = class extends Error {
+};
+function escapeForTerminal(message) {
+  return message.split("\n").map((line) => escapeControls(line)).join("\n");
+}
+function info(message) {
+  process.stderr.write(`${escapeForTerminal(message)}
+`);
+}
+function warn(message) {
+  process.stderr.write(`${escapeForTerminal(message)}
+`);
+}
+function emit(format, payload, textRenderer) {
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+    return;
+  }
+  textRenderer();
+}
+function fail(format, message, exitCode = 1) {
+  warn(`\u274C ${message}`);
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify({ error: { message, exitCode } }, null, 2)}
+`);
+  }
+  return exitCode;
+}
+function splitList(value) {
+  if (value === void 0) return void 0;
+  return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+function displayOutPath(cwd, outDir, ...segments) {
+  const absolute = path2.resolve(cwd, outDir, ...segments);
+  const relative3 = path2.relative(cwd, absolute);
+  if (relative3 && !relative3.startsWith("..") && !path2.isAbsolute(relative3)) return relative3;
+  return absolute;
+}
+function nextStepHint(cwd, scriptsAddedNow) {
+  let hasScript = scriptsAddedNow;
+  if (!hasScript) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path2.join(cwd, "package.json"), "utf8"));
+      hasScript = typeof parsed.scripts?.snapshot === "string";
+    } catch {
+      hasScript = false;
+    }
+  }
+  if (!hasScript) return `npx ${GENERATOR_NAME} generate`;
+  const bin = path2.join(cwd, "node_modules", ".bin", "codebase-snapshot");
+  const installed = fs.existsSync(bin) || fs.existsSync(`${bin}.cmd`);
+  return installed ? "npm run snapshot" : "npm install && npm run snapshot";
+}
+async function runInitCommand(invocation) {
+  try {
+    const result = await runInit({
+      cwd: invocation.cwd,
+      preset: invocation.preset,
+      outDir: invocation.outDir,
+      maxPartBytes: invocation.maxPartBytesRaw ?? invocation.maxPartBytes,
+      include: splitList(invocation.include),
+      exclude: splitList(invocation.exclude),
+      skipArtifacts: invocation.skipArtifacts,
+      includeSensitiveFiles: invocation.includeSensitiveFiles,
+      yes: invocation.yes,
+      force: invocation.force,
+      dryRun: invocation.dryRun
+    });
+    if (invocation.format === "json") {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return 0;
+    }
+    if (!result.written) {
+      info(result.configText);
+      return 0;
+    }
+    info(`\u2705 Created ${path2.basename(result.configPath)} (preset: ${result.preset})`);
+    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}`);
+    }
+    if (result.gitignoreEntries.length > 0) {
+      info(`   Added to .gitignore: ${result.gitignoreEntries.join(", ")}`);
+    }
+    for (const note of result.notes) info(`   \u26A0 ${note}`);
+    info("");
+    info(`   Next:  ${nextStepHint(invocation.cwd, result.scripts.length > 0)}`);
+    return 0;
+  } catch (err) {
+    if (err instanceof PromptCancelled) {
+      return fail(invocation.format, "Cancelled.");
+    }
+    return fail(invocation.format, err.message);
+  }
+}
+function detectPackageManager(cwd) {
+  const has = (name) => fs.existsSync(path2.join(cwd, name));
+  if (has("bun.lockb") || has("bun.lock")) return { name: "bun", command: "bun", args: ["install"] };
+  if (has("pnpm-lock.yaml")) return { name: "pnpm", command: "pnpm", args: ["install"] };
+  if (has("yarn.lock")) return { name: "yarn", command: "yarn", args: ["install"] };
+  return { name: "npm", command: "npm", args: ["install"] };
+}
+function cleanInstallEnv(env = process.env) {
+  const cleaned = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (/^npm_config_/i.test(key)) continue;
+    if (key === "npm_lifecycle_event" || key === "npm_lifecycle_script") continue;
+    cleaned[key] = value;
+  }
+  return cleaned;
+}
+function installDependencies(cwd) {
+  const manager = detectPackageManager(cwd);
+  const command = `${manager.command} ${manager.args.join(" ")}`;
+  const started = performance.now();
+  const result = spawnSync(manager.command, manager.args, {
+    cwd,
+    encoding: "utf8",
+    // npm, pnpm and yarn ship as `.cmd` shims on Windows, which spawnSync cannot exec directly.
+    shell: process.platform === "win32",
+    timeout: INSTALL_TIMEOUT_MS,
+    env: cleanInstallEnv()
+  });
+  const seconds = `${((performance.now() - started) / 1e3).toFixed(1)}s`;
+  if (result.error) {
+    return { manager: manager.name, command, ok: false, detail: `${result.error.message} (${seconds})` };
+  }
+  if (result.status !== 0) {
+    const tail = `${result.stderr ?? ""}${result.stdout ?? ""}`.trim().split(/\r?\n/).slice(-3).join(" | ");
+    return { manager: manager.name, command, ok: false, detail: `exit ${result.status}: ${tail} (${seconds})` };
+  }
+  return { manager: manager.name, command, ok: true, detail: seconds };
+}
+async function captureStdout(fn) {
+  const original = process.stdout.write.bind(process.stdout);
+  let text = "";
+  process.stdout.write = ((chunk) => {
+    text += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return true;
+  });
+  try {
+    const code = await fn();
+    return { code, text };
+  } finally {
+    process.stdout.write = original;
+  }
+}
+async function runSetupCommand(invocation) {
+  try {
+    const init = await runInit({
+      cwd: invocation.cwd,
+      preset: invocation.preset,
+      outDir: invocation.outDir,
+      maxPartBytes: invocation.maxPartBytesRaw ?? invocation.maxPartBytes,
+      include: splitList(invocation.include),
+      exclude: splitList(invocation.exclude),
+      skipArtifacts: invocation.skipArtifacts,
+      includeSensitiveFiles: invocation.includeSensitiveFiles,
+      yes: true,
+      force: invocation.force,
+      reuseConfig: true,
+      dryRun: invocation.dryRun
+    });
+    if (invocation.dryRun) {
+      const manager = invocation.noInstall ? null : detectPackageManager(invocation.cwd).name;
+      if (invocation.format === "json") {
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              dryRun: true,
+              configPath: init.configPath,
+              configReused: init.reused,
+              preset: init.preset,
+              install: manager,
+              configText: init.configText
+            },
+            null,
+            2
+          )}
+`
+        );
+        return 0;
+      }
+      info("\n\u{1F9EA} Dry run \u2014 setup would:");
+      info(
+        `   1. ${init.reused ? `keep ${path2.basename(init.configPath)}` : `write ${path2.basename(init.configPath)} (preset: ${init.preset})`}`
+      );
+      info("   2. add the npm scripts, the devDependency and the .gitignore entries");
+      if (manager !== null) info(`   3. install with ${manager}`);
+      info("   4. generate the snapshot");
+      info("");
+      info(init.configText);
+      return 0;
+    }
+    if (invocation.format !== "json") {
+      info(`\u{1F680} Setup for: ${invocation.cwd}`);
+      if (init.reused) {
+        info(`\u267B  Keeping ${path2.basename(init.configPath)} (preset: ${init.preset})`);
+      } else {
+        info(`\u2705 Created ${path2.basename(init.configPath)} (preset: ${init.preset})`);
+      }
+      if (init.scripts.length > 0) info(`   Added npm scripts: ${init.scripts.join(", ")}`);
+      if (init.dependency.added && init.dependency.range !== null) {
+        info(`   Added devDependency: ${init.dependency.name} ${init.dependency.range}`);
+      }
+      if (init.gitignoreEntries.length > 0) {
+        info(`   Added to .gitignore: ${init.gitignoreEntries.join(", ")}`);
+      }
+    }
+    let install = null;
+    if (invocation.noInstall) {
+      if (invocation.format !== "json") info("   Skipped the install (--no-install)");
+    } else {
+      if (invocation.format !== "json") info("\u23F3 Installing dependencies\u2026");
+      install = installDependencies(invocation.cwd);
+      if (invocation.format !== "json") {
+        if (install.ok) info(`\u2705 Installed dependencies (${install.command}, ${install.detail})`);
+        else info(`\u26A0 ${install.command} failed (${install.detail}); generating anyway`);
+      }
+    }
+    const generateArgs = ["generate", "--cwd", invocation.cwd, "--format", invocation.format];
+    if (invocation.outDir !== void 0) generateArgs.push("--out-dir", invocation.outDir);
+    if (invocation.includeSensitiveFiles === true) generateArgs.push("--include-sensitive-files");
+    const budget = invocation.maxPartBytesRaw ?? invocation.maxPartBytes;
+    if (budget !== void 0) generateArgs.push("--max-part-bytes", String(budget));
+    if ((invocation.skipArtifacts ?? []).length > 0) {
+      generateArgs.push("--skip-artifacts", (invocation.skipArtifacts ?? []).join(","));
+    }
+    if (invocation.format === "json") {
+      const generated = await captureStdout(() => main(generateArgs));
+      let manifest = null;
+      try {
+        manifest = JSON.parse(generated.text);
+      } catch {
+        manifest = null;
+      }
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            setup: {
+              configPath: init.configPath,
+              configReused: init.reused,
+              preset: init.preset,
+              scripts: init.scripts,
+              dependency: init.dependency,
+              gitignoreEntries: init.gitignoreEntries,
+              install,
+              notes: init.notes
+            },
+            manifest
+          },
+          null,
+          2
+        )}
+`
+      );
+      return generated.code;
+    }
+    const code = await main(generateArgs);
+    info("");
+    info(`   Next:  ${nextStepHint(invocation.cwd, false)}`);
+    return code;
+  } catch (err) {
+    if (err instanceof PromptCancelled) return fail(invocation.format, "Cancelled.");
+    return fail(invocation.format, err.message);
+  }
+}
+function runSkillCommand(invocation) {
+  if (!invocation.install) {
+    if (invocation.format === "json") {
+      process.stdout.write(
+        `${JSON.stringify({ name: SKILL_NAME, version: GENERATOR_VERSION, skill: renderSkill() }, null, 2)}
+`
+      );
+      return 0;
+    }
+    process.stdout.write(renderSkill());
+    return 0;
+  }
+  try {
+    const result = installSkill(invocation.cwd, invocation.target);
+    if (invocation.format === "json") {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return 0;
+    }
+    info(`\u2705 Agent skill installed (${SKILL_NAME}):`);
+    for (const item of result.written) {
+      const shown = path2.relative(invocation.cwd, item.path) || item.path;
+      info(`   - ${item.action.padEnd(9)} ${shown}`);
+    }
+    if (result.gitignored.length > 0) {
+      info("");
+      info(`   Added to .gitignore: ${result.gitignored.join(", ")}`);
+      info("   These files are this tool's own documentation, so they stay out of git.");
+    }
+    for (const note of result.notes) info(`   \u26A0 ${note}`);
+    info("");
+    info("   Agents that read .claude/skills or .cursor/rules will pick this up automatically.");
+    return 0;
+  } catch (err) {
+    return fail(invocation.format, `Could not install the skill: ${err.message}`);
+  }
+}
+function renderValidateText(result) {
+  if (result.valid) {
+    info("\u2705 Snapshot is valid and up to date with disk.");
+  } else {
+    warn("\u274C Snapshot validation failed:");
+    for (const error of result.errors) warn(`  - ${error}`);
+    for (const unreadable of result.drift.unreadable.slice(0, 20)) {
+      warn(`  - unreadable: ${unreadable}`);
+    }
+    for (const drift of result.drift.hashMismatches.slice(0, 20)) {
+      warn(`  - modified: ${drift.path}`);
+    }
+    for (const issue of result.drift.partIssues.slice(0, 20)) {
+      warn(`  - part: ${issue.part} (${issue.issue})`);
+    }
+    for (const mismatch of result.drift.configMismatches.slice(0, 20)) {
+      warn(`  - config: ${mismatch}`);
+    }
+    for (const missing of result.drift.missingInSnapshot.slice(0, 20)) {
+      warn(`  - new file: ${missing}`);
+    }
+    for (const missing of result.drift.missingOnDisk.slice(0, 20)) {
+      warn(`  - deleted: ${missing}`);
+    }
+    for (const mismatch of result.drift.totalsMismatches.slice(0, 20)) {
+      warn(`  - counts: ${mismatch}`);
+    }
+  }
+  for (const warning of result.warnings) warn(`  \u26A0 ${warning}`);
+}
+function requestsJsonFormat(argv) {
+  let format;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--") break;
+    if (argument === "--format") {
+      const next = argv[index + 1];
+      if (next !== void 0 && !next.startsWith("-")) {
+        format = next;
+        index += 1;
+      }
+      continue;
+    }
+    if (argument.startsWith("--format=")) format = argument.slice("--format=".length);
+  }
+  return format === "json";
+}
+async function main(argv = process.argv.slice(2)) {
+  let invocation;
+  try {
+    invocation = parseCliArgs(argv);
+  } catch (err) {
+    if (err instanceof HelpRequested) return 0;
+    if (err instanceof UsageError) {
+      process.stderr.write(`\u274C ${err.message}
+
+${USAGE}
+`);
+      if (requestsJsonFormat(argv)) {
+        process.stdout.write(
+          `${JSON.stringify({ error: { message: err.message, exitCode: 2 } }, null, 2)}
+`
+        );
+      }
+      return 2;
+    }
+    throw err;
+  }
+  if (invocation.command === "init") {
+    return await runInitCommand(invocation);
+  }
+  if (invocation.command === "describe") {
+    const contract = buildAgentContract();
+    emit(invocation.format, contract, () => info(renderContractText(contract)));
+    return 0;
+  }
+  if (invocation.command === "skill") {
+    return runSkillCommand(invocation);
+  }
+  if (invocation.command === "setup") {
+    return runSetupCommand(invocation);
+  }
+  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");
+  for (const warning of loaded.warnings) warn(`\u26A0 Config: ${warning}`);
+  if (loaded.errors.length > 0) {
+    warn("\u274C The config file could not be read. Fix it, or delete it to use the defaults.");
+    return 1;
+  }
+  if (loaded.file) info(`\u2699  Using config ${path2.relative(process.cwd(), loaded.file) || loaded.file}`);
+  const resolved = resolveConfig(
+    loaded.config,
+    {
+      mode: invocation.command,
+      format: invocation.format,
+      dryRun: invocation.dryRun,
+      cwd: invocation.cwd,
+      outDir: invocation.outDir,
+      includeMonolith: invocation.includeMonolith,
+      includeSensitiveFiles: invocation.includeSensitiveFiles,
+      maxPartBytes: invocation.maxPartBytes,
+      largeFileBytes: invocation.largeFileBytes,
+      maxMonolithBytes: invocation.maxMonolithBytes,
+      skipArtifacts: invocation.skipArtifacts,
+      discovery: invocation.discovery
+    },
+    invocation.cwd
+  );
+  if (invocation.command === "validate") {
+    const result = validateSnapshot(resolved);
+    if (result.valid) {
+      const manifestPath = path2.resolve(resolved.cwd, resolved.outDir, "manifest.json");
+      let manifest;
+      try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      } catch {
+        manifest = void 0;
+      }
+      const shapeError = manifest === void 0 ? null : describeManifestShapeProblem(manifest);
+      if (shapeError) {
+        return fail(invocation.format, `${manifestPath} is not a snapshot manifest: ${shapeError}`);
+      }
+    }
+    emit(invocation.format, result, () => renderValidateText(result));
+    return result.valid ? 0 : 1;
+  }
+  if (invocation.command === "report") {
+    const manifestPath = path2.resolve(resolved.cwd, resolved.outDir, "manifest.json");
+    if (!fs.existsSync(manifestPath)) {
+      return fail(invocation.format, `Manifest not found at ${manifestPath}. Run generate first.`);
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    } catch (err) {
+      return fail(invocation.format, `Could not read ${manifestPath}: ${err.message}`);
+    }
+    const shapeError = describeManifestShapeProblem(manifest);
+    if (shapeError) {
+      return fail(invocation.format, `${manifestPath} is not a snapshot manifest: ${shapeError}`);
+    }
+    emit(invocation.format, { manifest, validation: null }, () => {
+      info(`
+\u{1F4CA} Codebase Snapshot Report (${resolved.cwd})`);
+      info(`   - Generated at:   ${manifest.generatedAt}`);
+      info(`   - Schema:         ${manifest.schemaVersion}`);
+      info(`   - Fingerprint:    ${manifest.fingerprint}`);
+      info(`   - Files included: ${manifest.counts.totalFiles}`);
+      info(`   - Total lines:    ${formatNumber(manifest.counts.totalLines)}`);
+      info(
+        `   - Total size:     ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB`
+      );
+      info(`   - Total parts:    ${manifest.counts.partsCount}`);
+      info("   - Integrity:      not checked (run `codebase-snapshot validate`)");
+      info(`   - Warnings:       ${manifest.warnings?.length ?? 0}`);
+      if ((manifest.totals.redactedLines ?? 0) > 0) {
+        info(`   - Redacted:       ${manifest.totals.redactedLines} line(s)`);
+      }
+      info("\n   Layers:");
+      for (const [layer, count] of Object.entries(manifest.layers)) {
+        info(`     - ${layer.padEnd(16)}: ${count} files`);
+      }
+    });
+    return 0;
+  }
+  if (invocation.command === "explain") {
+    const result = explainPath(resolved, invocation.args[0]);
+    emit(invocation.format, result, () => info(renderExplainText(result)));
+    return 0;
+  }
+  if (invocation.command === "diff") {
+    try {
+      const [beforePath, afterPath] = invocation.args;
+      const diff = compareManifests(loadManifest(beforePath), loadManifest(afterPath));
+      emit(invocation.format, diff, () => info(renderDiffText(diff)));
+      return 0;
+    } catch (err) {
+      return fail(invocation.format, err.message);
+    }
+  }
+  const started = performance.now();
+  info(`\u{1F4F8} ${invocation.dryRun ? "Planning snapshot (dry run)" : "Generating snapshot"} for: ${resolved.cwd}`);
+  info(
+    `   Branch: ${resolved.branch} | Part budget: ${(resolved.maxPartBytes / 1024).toFixed(0)} KB`
+  );
+  try {
+    const manifest = generateSnapshot(resolved, { dryRun: invocation.dryRun });
+    const elapsed = ((performance.now() - started) / 1e3).toFixed(2);
+    if (invocation.dryRun) {
+      info("\n\u{1F9EA} Dry run \u2014 nothing was written:");
+      info(`   - Would track:  ${manifest.counts.totalFiles} files`);
+      info(
+        `   - Would write:  ${manifest.counts.partsCount} part(s) under ${displayOutPath(resolved.cwd, resolved.outDir, "parts")}`
+      );
+      info(`   - Skipped:      ${manifest.counts.skippedCount} file(s)`);
+      info(`   - Warnings:     ${manifest.warnings.length}`);
+      if ((manifest.totals.redactedLines ?? 0) > 0) {
+        info(
+          `   - Redacted:     ${manifest.totals.redactedLines} line(s) \u2014 a real run lists them in ` + displayOutPath(resolved.cwd, resolved.outDir, "reports/audit.md")
+        );
+      }
+      info(`   - Integrity:    ${manifest.validation.status}`);
+      for (const error of manifest.validation.errors.slice(0, 10)) info(`     - ${error}`);
+    } else {
+      info(`
+\u2705 Snapshot generated in ${elapsed}s:`);
+      info(`   - Tracked files: ${manifest.counts.totalFiles}`);
+      info(`   - Total lines:   ${formatNumber(manifest.counts.totalLines)}`);
+      info(
+        `   - Total size:    ${(manifest.counts.totalSizeBytes / (1024 * 1024)).toFixed(2)} MB`
+      );
+      const { artifacts } = resolved;
+      if (artifacts.parts) {
+        info(
+          `   - Parts written: ${manifest.counts.partsCount} under ${displayOutPath(resolved.cwd, resolved.outDir, "parts")}`
+        );
+      }
+      const reports = [
+        artifacts.projectTree && "project-tree",
+        artifacts.navigation && "navigation",
+        artifacts.audit && "audit"
+      ].filter(Boolean);
+      if (reports.length > 0) {
+        info(
+          `   - Reports:       ${displayOutPath(resolved.cwd, resolved.outDir, "reports")} (${reports.join(", ")})`
+        );
+      }
+      if (artifacts.manifest) {
+        info(`   - Manifest:      ${displayOutPath(resolved.cwd, resolved.outDir, "manifest.json")}`);
+      }
+      if (artifacts.monolith) {
+        const monolithFiles = [
+          manifest.artifacts?.fullJson ? "full-codebase.json" : null,
+          manifest.artifacts?.fullMarkdown ? "full-codebase.md" : null
+        ].filter((name) => name !== null);
+        if (monolithFiles.length === 2) {
+          info(
+            `   - Monolith:      ${displayOutPath(resolved.cwd, resolved.outDir, "full-codebase.{json,md}")}`
+          );
+        } else if (monolithFiles.length === 1) {
+          info(
+            `   - Monolith:      ${displayOutPath(resolved.cwd, resolved.outDir, monolithFiles[0])} (the other was skipped by --max-monolith-bytes)`
+          );
+        }
+      }
+      if (reports.length === 0 && !artifacts.parts && !artifacts.manifest && !artifacts.monolith) {
+        info(`   - Artifacts:     all disabled (only the ownership marker was written)`);
+      }
+      info(`   - Fingerprint:   ${manifest.fingerprint}`);
+      info(`   - Integrity:     ${manifest.validation.status}`);
+      if ((manifest.totals.redactedLines ?? 0) > 0) {
+        const where = artifacts.audit ? `see ${displayOutPath(resolved.cwd, resolved.outDir, "reports/audit.md")}` : "reports/audit.md is disabled";
+        info(`   - Redacted:      ${manifest.totals.redactedLines} line(s) \u2014 values masked; ${where}`);
+      }
+      if (manifest.warnings.length > 0) {
+        info(`   - Warnings:      ${manifest.warnings.length}`);
+        for (const warning of manifest.warnings.slice(0, 10)) info(`     - ${warning}`);
+        if (manifest.warnings.length > 10) {
+          info(`     \u2026 and ${manifest.warnings.length - 10} more in manifest.warnings[]`);
+        }
+      }
+    }
+    if (invocation.format === "json") {
+      process.stdout.write(`${JSON.stringify(manifest, null, 2)}
+`);
+    }
+    if (invocation.watch) {
+      return await runWatchLoop(invocation, resolved);
+    }
+    return manifest.validation.status === "passed" ? 0 : 1;
+  } catch (err) {
+    const code = err.code;
+    if (code === "EPERM" || code === "EACCES") {
+      return fail(
+        invocation.format,
+        `Cannot write the snapshot: permission denied under ${resolved.outDir}. Check the directory's permissions or choose another --out-dir. (${err.message})`
+      );
+    }
+    return fail(invocation.format, `Failed to generate snapshot: ${err.message}`);
+  }
+}
+var WATCH_DEBOUNCE_MS = 250;
+var WATCH_SETTLE_MS = 1500;
+var VCS_SEGMENTS = /* @__PURE__ */ new Set([".git", ".hg", ".svn", ".bzr"]);
+function initialWatchState() {
+  return { running: false, pending: false, settleUntil: 0 };
+}
+function beginWatchRun(state) {
+  return { ...state, running: true, pending: false };
+}
+function finishWatchRun(state, now) {
+  return {
+    state: { running: false, pending: false, settleUntil: now + WATCH_SETTLE_MS },
+    schedule: state.pending
+  };
+}
+function comparablePath(value) {
+  const absolute = path2.resolve(value);
+  return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+}
+function isSameOrInside(parent, candidate) {
+  const relative3 = path2.relative(parent, candidate);
+  return relative3 === "" || relative3 !== ".." && !relative3.startsWith(`..${path2.sep}`) && !path2.isAbsolute(relative3);
+}
+function isGeneratedWatchPath(candidate, paths) {
+  const absolute = comparablePath(path2.resolve(paths.cwd, candidate));
+  const outDir = comparablePath(path2.resolve(paths.cwd, paths.outDir));
+  const tmpDir = comparablePath(path2.resolve(paths.cwd, paths.tmpDir));
+  if (isSameOrInside(outDir, absolute) || isSameOrInside(tmpDir, absolute)) return true;
+  const parent = path2.dirname(absolute);
+  if (parent === path2.dirname(outDir) && path2.basename(absolute).startsWith(`${path2.basename(outDir)}.backup-`)) {
+    return true;
+  }
+  return absolute.split(/[\\/]+/).some((segment) => VCS_SEGMENTS.has(segment));
+}
+function decideWatchEvent(state, event, paths) {
+  if (event.path !== null) {
+    if (isGeneratedWatchPath(event.path, paths)) return { state, action: "ignore" };
+  } else if (state.running || event.now < state.settleUntil) {
+    return { state, action: "ignore" };
+  }
+  if (state.running) {
+    return { state: { ...state, pending: true }, action: "pending" };
+  }
+  return { state, action: "schedule" };
+}
+async function runWatchLoop(invocation, resolved) {
+  const outDir = path2.resolve(resolved.cwd, resolved.outDir);
+  const tmpDir = path2.resolve(resolved.cwd, resolved.tmpDir);
+  const paths = { cwd: resolved.cwd, outDir, tmpDir };
+  let state = initialWatchState();
+  let timer = null;
+  let stopped = false;
+  const schedule = (delay = WATCH_DEBOUNCE_MS) => {
+    if (stopped) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void regenerate();
+    }, delay);
+  };
+  const regenerate = async () => {
+    if (state.running) {
+      state = { ...state, pending: true };
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      return;
+    }
+    state = beginWatchRun(state);
+    const started = performance.now();
+    try {
+      const loaded = invocation.noConfig ? { config: null, warnings: [], errors: [], file: null } : await loadConfigFileDetailed(invocation.cwd);
+      if (loaded.errors.length > 0) {
+        for (const error of loaded.errors) warn(`\u26A0 Config: ${error}`);
+        warn("\u274C The config file could not be read. Fix it, or delete it to use the defaults.");
+        return;
+      }
+      for (const warning of loaded.warnings) warn(`\u26A0 Config: ${warning}`);
+      const next = resolveConfig(
+        loaded.config,
+        {
+          mode: invocation.command,
+          format: invocation.format,
+          dryRun: invocation.dryRun,
+          cwd: invocation.cwd,
+          outDir: invocation.outDir,
+          includeMonolith: invocation.includeMonolith,
+          includeSensitiveFiles: invocation.includeSensitiveFiles,
+          maxPartBytes: invocation.maxPartBytes,
+          largeFileBytes: invocation.largeFileBytes,
+          maxMonolithBytes: invocation.maxMonolithBytes,
+          skipArtifacts: invocation.skipArtifacts,
+          discovery: invocation.discovery
+        },
+        invocation.cwd
+      );
+      const manifest = generateSnapshot(next, { dryRun: invocation.dryRun });
+      const elapsed = ((performance.now() - started) / 1e3).toFixed(2);
+      info(
+        `\u267B\uFE0F  ${(/* @__PURE__ */ new Date()).toISOString()}  ${manifest.counts.totalFiles} file(s), ${manifest.counts.partsCount} part(s), ${manifest.validation.status} (${elapsed}s)`
+      );
+    } catch (err) {
+      warn(`\u274C ${err.message}`);
+    } finally {
+      const finished = finishWatchRun(state, performance.now());
+      state = finished.state;
+      if (finished.schedule) schedule(0);
+    }
+  };
+  info("\u{1F440} Watching for changes. Press Ctrl+C to stop.");
+  void regenerate();
+  const watcher = fs.watch(resolved.cwd, { recursive: true }, (_event, filename) => {
+    const decision = decideWatchEvent(
+      state,
+      {
+        path: filename ? path2.resolve(resolved.cwd, filename.toString()) : null,
+        now: performance.now()
+      },
+      paths
+    );
+    state = decision.state;
+    if (decision.action === "pending") {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      return;
+    }
+    if (decision.action === "schedule") schedule();
+  });
+  await new Promise((resolve2) => {
+    const stop = () => {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      watcher.close();
+      resolve2();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  return 0;
+}
+var entryFile = process.argv[1] ?? "";
+var entryName = path2.basename(entryFile).toLowerCase();
+var invokedDirectly = entryName === "cli.js" || entryName === "cli.cjs";
+if (invokedDirectly) {
+  void main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (err) => {
+      process.stderr.write(`\u274C ${err.message}
+`);
+      process.exitCode = 1;
+    }
+  );
+}
+
+export { UsageError, WATCH_DEBOUNCE_MS, WATCH_SETTLE_MS, beginWatchRun, cleanInstallEnv, decideWatchEvent, finishWatchRun, initialWatchState, isGeneratedWatchPath, main, parseByteOption, parseCliArgs, parsePositiveInteger };
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map