@ankurhalder/codebase-snapshot 2.1.1 → 3.0.0

package/dist/index.cjs

@@ -3943,11 +3943,12 @@ var PRESET_NAMES = [
   "java-spring \xB7 dotnet \xB7 php-laravel \xB7 ruby-rails",
   "monorepo \xB7 docs \xB7 infra \xB7 generic"
 ];
+var CONFIG_HEADER = `// Generated by codebase-snapshot. A plain object on purpose: this file must load
+// even when the package itself is only run through npx.
+`;
 function renderConfig(answers) {
   const { artifacts } = answers;
-  return `import { defineConfig } from "@ankurhalder/codebase-snapshot";
-
-export default defineConfig({
+  return `${CONFIG_HEADER}export default {
   // \u2500\u2500 Project \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   // Which project shape to use. Detected from the repo when omitted.
   // ${PRESET_NAMES.join("\n  // ")}
@@ -4016,7 +4017,7 @@ export default defineConfig({
   // \u2500\u2500 Advanced \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   // afterGenerate: (manifest) => { /* write your own artifact */ }
   hooks: {},
-});
+};
 `;
 }
 function renderMinimalConfig(answers) {
@@ -4044,16 +4045,12 @@ ${entries},
   },`);
   }
   if (lines.length === 0) {
-    return `import { defineConfig } from "@ankurhalder/codebase-snapshot";
-
-export default defineConfig({});
+    return `${CONFIG_HEADER}export default {};
 `;
   }
-  return `import { defineConfig } from "@ankurhalder/codebase-snapshot";
-
-export default defineConfig({
+  return `${CONFIG_HEADER}export default {
 ${lines.join("\n")}
-});
+};
 `;
 }
 var PromptCancelled = class extends Error {
@@ -4314,6 +4311,17 @@ var CONFIG_CANDIDATES = [
   ".snapshotrc.json",
   ".snapshotrc"
 ];
+function chooseConfigFileName(cwd) {
+  if (!supportsTypeScriptImports()) return "snapshot.config.mjs";
+  const pkgPath = path10__namespace.join(cwd, "package.json");
+  if (!fs9__namespace.existsSync(pkgPath)) return "snapshot.config.mjs";
+  try {
+    const parsed = JSON.parse(fs9__namespace.readFileSync(pkgPath, "utf8"));
+    return parsed.type === "module" ? "snapshot.config.ts" : "snapshot.config.mjs";
+  } catch {
+    return "snapshot.config.mjs";
+  }
+}
 var SIZE_CHOICES = [
   { value: "60k", label: "Small", hint: "60 KB \xB7 ~15k tokens \xB7 tight context windows" },
   { value: "120k", label: "Medium", hint: "120 KB \xB7 ~30k tokens \xB7 recommended" },
@@ -4519,7 +4527,7 @@ async function runInit(options) {
     if (!proceed) throw new PromptCancelled();
   }
   const configText = options.minimal ? renderMinimalConfig(answers) : renderConfig(answers);
-  const configName = supportsTypeScriptImports() ? "snapshot.config.ts" : "snapshot.config.mjs";
+  const configName = chooseConfigFileName(options.cwd);
   const configPath = path10__namespace.join(options.cwd, configName);
   if (options.dryRun) {
     return {
@@ -4557,7 +4565,7 @@ async function runInit(options) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.1.1";
+var GENERATOR_VERSION = "3.0.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto__namespace.createHash("sha256").update(input).digest("hex");

package/dist/index.d.cts

@@ -497,7 +497,7 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "2.1.1";
+declare const GENERATOR_VERSION = "3.0.0";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */

package/dist/index.d.ts

@@ -497,7 +497,7 @@ declare function matchesExclude(relativePath: string, pattern: string): boolean;
 declare function collectFiles(cwd: string, options?: CollectOptions): CollectResult;
 
 declare const GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-declare const GENERATOR_VERSION = "2.1.1";
+declare const GENERATOR_VERSION = "3.0.0";
 declare const SCHEMA_VERSION = "3.0.0";
 interface GenerateOptions {
     /** Compute the full manifest but write nothing to disk. */

package/dist/index.js

@@ -1,3 +1,3 @@
-export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-SUOJL5EX.js';
+export { ARTIFACT_NAMES, DEFAULT_ANSWERS, DEFAULT_SECRET_PATTERNS, GENERATOR_NAME, GENERATOR_VERSION, LANGUAGE_PROFILES, MIN_MAX_PART_BYTES, PRESETS, PromptCancelled, SCHEMA_VERSION, anchorForPath, assertReplaceable, assertUsableConfigInput, collectFiles, compareManifests, countLines, defineConfig, detectLanguage, detectPreset, explainPath, fenceForContent, generateProjectTree, generateSnapshot, generateSnapshotAsync, getPreset, globToRegExp, isBinaryBuffer, isBinaryExtension, isBinaryFile, isInteractive, isResolvedConfig, isSensitivePath, listPresetNames, loadConfigFile, loadConfigFileDetailed, loadManifest, markResolvedConfig, matchRule, matchesExclude, normalizeResolvedConfig, parseByteSize, partitionFiles, profileForPath, renderConfig, renderDiffText, renderExplainText, renderMinimalConfig, renumberParts, resolveConfig, resolveSafeOutputDirs, runInit, scanAndRedactSecrets, stripJsonComments, summarizeJson, summarizeMarkdown, summarizeTypeScriptSource, summarizeWithProfile, supportsTypeScriptImports, truncatePreview, truncateToBytes, validateSnapshot } from './chunk-5B4UVQLR.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/docs/agent.md

@@ -0,0 +1,80 @@
+# Using this with an AI agent
+
+The package ships two things that make it usable by an agent that has never heard of it:
+a **machine-readable contract** and a **bundled skill**.
+
+Nothing here needs to be installed globally, and no prior knowledge of the tool is
+required.
+
+## The three commands an agent needs
+
+```bash
+# 1. Read the contract. This is the machine-readable replacement for --help.
+npx @ankurhalder/codebase-snapshot@latest describe --format json
+
+# 2. Write a commented config that lists every setting (non-interactive).
+npx @ankurhalder/codebase-snapshot@latest init --yes
+
+# 3. Generate and verify.
+npx @ankurhalder/codebase-snapshot@latest generate
+npx @ankurhalder/codebase-snapshot@latest validate
+```
+
+`describe` returns the invocation that works, an ordered `workflow` array, every command,
+every option with its default, the exit-code contract, all 25 presets, the artifact list,
+the config file names, the output layout, safety rules and a troubleshooting table — all
+as JSON on stdout.
+
+**Always pin the tag** (`@latest` or `@2`). A bare scoped spec can resolve to a bin-less
+placeholder manifest on some npm builds and exit 0 printing nothing; the pinned form
+cannot.
+
+## The skill
+
+```bash
+npx @ankurhalder/codebase-snapshot@latest skill            # print it (stdout)
+npx @ankurhalder/codebase-snapshot@latest skill --install  # write it into the repo
+```
+
+Printing goes to stdout deliberately, so it can be redirected:
+
+```bash
+npx @ankurhalder/codebase-snapshot@latest skill > SKILL.md
+```
+
+`--install` writes the same skill to every location agents look at by default:
+
+| Target | Path | Read by |
+| :--- | :--- | :--- |
+| `agents` | `AGENTS.md` (a marked section) | most tools, by convention |
+| `claude` | `.claude/skills/codebase-snapshot/SKILL.md` | Claude Code auto-discovery |
+| `cursor` | `.cursor/rules/codebase-snapshot.mdc` | Cursor rules |
+
+```bash
+skill --install --target claude    # one location
+skill --install                    # all three (default)
+```
+
+The install is **idempotent and non-destructive**: re-running replaces only the block
+between `<!-- codebase-snapshot:skill:start -->` and
+`<!-- codebase-snapshot:skill:end -->`, so an `AGENTS.md` that already documents your
+conventions keeps them. `--format json` reports what was created, updated or unchanged.
+
+`codebase-snapshot init` prints a reminder about this; it never installs the skill on its own.
+
+## Why both a contract and a skill
+
+The contract is for **doing** — it is the data an agent needs to pick correct commands and
+options, and it is asserted against the real defaults in the test suite so it cannot drift
+into lying.
+
+The skill is for **knowing when to act** — it carries the trigger conditions, the ordered
+workflow, and the surprises (sensitive files excluded by default, secrets redacted, the
+output directory being tool-owned) that an agent cannot infer from a schema.
+
+## Keeping the contract honest
+
+`describe` is generated from the same code the CLI runs — the preset list, artifact names,
+schema version and generator version are read directly, and a test compares its documented
+defaults against a real `generate --dry-run` manifest. If a default changes, the test fails
+rather than the contract silently misleading an agent.

package/docs/configuration.md

@@ -256,7 +256,7 @@ marker written before any artifact, not by the set of filenames present, so
 custom artifacts never look like someone else's data.
 
 Note that a hook runs in the **process** working directory, so with
-`snap --cwd elsewhere` a relative path resolves against your shell's directory,
+`codebase-snapshot --cwd elsewhere` a relative path resolves against your shell's directory,
 not the target repo. Use the absolute paths on `manifest` (or resolve against
 `outDir` yourself) when passing `--cwd`.
 
@@ -276,7 +276,7 @@ not the target repo. Use the absolute paths on `manifest` (or resolve against
 ## `explain`
 
 ```
-$ snap explain src/app/page.tsx
+$ codebase-snapshot explain src/app/page.tsx
 
 src/app/page.tsx
 
@@ -293,7 +293,7 @@ src/app/page.tsx
 Excluded paths say why:
 
 ```
-$ snap explain .env
+$ codebase-snapshot explain .env
 
 .env
 
@@ -308,7 +308,7 @@ same data as an object.
 ## `diff`
 
 ```
-$ snap diff old-snapshot new-snapshot
+$ codebase-snapshot diff old-snapshot new-snapshot
 
 before  2026-11-03T10:00:00.000Z  812 file(s), 4 part(s)
 after   2026-11-03T11:30:00.000Z  820 file(s), 4 part(s)

package/docs/install.md

@@ -12,24 +12,27 @@ Requires **Node.js 18 or newer**.
 npx @ankurhalder/codebase-snapshot generate
 ```
 
-If that exits with **no output and no error** instead of generating, your npm has
-resolved the bare spec to a placeholder manifest that carries no executable — npm creates
-a `0.0.0-stage` placeholder version during staged publishing, and some npm builds pick it
-when no version is given. Pin the version or the tag and it works:
+Pin the version when you need the same build on every machine:
 
 ```bash
 npx @ankurhalder/codebase-snapshot@latest generate
-npx @ankurhalder/codebase-snapshot@2 generate
+npx @ankurhalder/codebase-snapshot@3 generate
 ```
 
+The bare form works because this package ships **exactly one executable**
+(`codebase-snapshot`). That is deliberate: npm resolves which binary to run by matching the
+typed command against the package's `bin` keys, and no key can contain an `@scope/`, so a
+scoped package with several executables cannot be run by its bare name. If a command ever
+exits with no output, clear the npm cache and retry — see troubleshooting.
+
 `npx -p @ankurhalder/codebase-snapshot codebase-snapshot generate`, `pnpm dlx`,
-`yarn dlx` and `bunx` are unaffected. A normal `npm install -D` followed by `npx snap`
-is unaffected too, and is the more reproducible choice for a project.
+`yarn dlx` and `bunx` are equivalent. A normal `npm install -D` followed by
+`npx codebase-snapshot` is the more reproducible choice for a project.
 
 Equivalent one-liners for other clients:
 
 ```bash
-yarn dlx -p @ankurhalder/codebase-snapshot snap generate   # yarn Berry
+yarn dlx -p @ankurhalder/codebase-snapshot codebase-snapshot generate   # yarn Berry
 yarn global add @ankurhalder/codebase-snapshot             # yarn classic (installs globally)
 pnpm dlx @ankurhalder/codebase-snapshot generate
 bunx @ankurhalder/codebase-snapshot generate
@@ -47,13 +50,13 @@ bun add -d @ankurhalder/codebase-snapshot
 Then run it through your client so it resolves from the project's `node_modules`:
 
 ```bash
-npx snap generate
-yarn snap generate
-pnpm exec snap generate
-bun run snap generate
+npx codebase-snapshot generate
+yarn codebase-snapshot generate
+pnpm exec codebase-snapshot generate
+bun run codebase-snapshot generate
 ```
 
-Both `snap` and `codebase-snapshot` are exposed as binaries — pick whichever you prefer.
+Both `codebase-snapshot` and `codebase-snapshot` are exposed as binaries — pick whichever you prefer.
 
 Adding it to `package.json` scripts works the same everywhere:
 
@@ -82,23 +85,23 @@ if the generator version is reproducible.
 
 ```bash
 npx @ankurhalder/codebase-snapshot@2 generate
-pnpm dlx @ankurhalder/codebase-snapshot@2.1.1 generate
+pnpm dlx @ankurhalder/codebase-snapshot@3.0.0 generate
 ```
 
 ## Verified clients
 
 Every client below was used to install the published package and run
-`snap --version` successfully. This matrix is enforced in CI
+`codebase-snapshot --version` successfully. This matrix is enforced in CI
 (`.github/workflows/ci.yml` → `client-install`), so a change that breaks a client fails
 the build rather than a user's terminal.
 
 | Client | Version tested | Run installed binary with |
 | :--- | :--- | :--- |
-| npm | 10.x | `npx snap` |
-| yarn (classic) | 1.22.22 | `yarn snap` |
-| yarn (Berry, `nodeLinker: pnp`) | 4.6.0 | `yarn snap` |
-| pnpm | 10.28.0 | `pnpm exec snap` |
-| bun | 1.4.4 | `bun run snap` |
+| npm | 10.x | `npx codebase-snapshot` |
+| yarn (classic) | 1.22.22 | `yarn codebase-snapshot` |
+| yarn (Berry, `nodeLinker: pnp`) | 4.6.0 | `yarn codebase-snapshot` |
+| pnpm | 10.28.0 | `pnpm exec codebase-snapshot` |
+| bun | 1.4.4 | `bun run codebase-snapshot` |
 
 Yarn Berry's default **strict PnP** mode works: there is no `node_modules` directory, and
 the runtime `typescript` dependency still resolves through yarn's `.pnp.cjs` loader.
@@ -125,9 +128,9 @@ Snapshots already written to `snapshot/` are ordinary files and are left alone.
 
 ## Troubleshooting
 
-**`snap: command not found`** — when installed locally (not globally), the binary lives
+**`codebase-snapshot: command not found`** — when installed locally (not globally), the binary lives
 in `node_modules/.bin` and is only on your `PATH` inside a package script or a client
-runner. Use `npx snap`, `pnpm exec snap`, `yarn snap`, or `bun run snap`.
+runner. Use `npx codebase-snapshot`, `pnpm exec codebase-snapshot`, `yarn codebase-snapshot`, or `bun run codebase-snapshot`.
 
 **`Cannot find module 'typescript'`** — the package declares `typescript` as a runtime
 dependency for AST analysis. If your client prunes or externalizes it (some bundlers and
@@ -136,14 +139,14 @@ dependency for AST analysis. If your client prunes or externalizes it (some bund
 **CI has no Node** — that is not supported yet; this package is JavaScript and needs a
 Node runtime. See the future-work note above.
 
-**`yarn snap` prints extra lines, or breaks a script that parses output** — yarn classic
+**`yarn codebase-snapshot` prints extra lines, or breaks a script that parses output** — yarn classic
 wraps everything: it echoes `yarn run 1.22.22`, the resolved command, your tool's output,
 and a `Done in 0.37s.` trailer. For a human that is harmless; for anything that parses
-`snap`'s stdout it is not. In scripts and CI, call the binary directly:
+`codebase-snapshot`'s stdout it is not. In scripts and CI, call the binary directly:
 
 ```bash
-./node_modules/.bin/snap generate
-npx snap generate          # same, without the yarn wrapper
+./node_modules/.bin/codebase-snapshot generate
+npx codebase-snapshot generate          # same, without the yarn wrapper
 ```
 
 This is why the CI job in this repository reads the version from a line that *is* the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankurhalder/codebase-snapshot",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "Production-grade LLM codebase snapshot generator, auditor, and AST partitioner",
   "keywords": [
     "codebase",
@@ -32,8 +32,7 @@
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "bin": {
-    "codebase-snapshot": "./dist/bin.js",
-    "snap": "./dist/bin.js"
+    "codebase-snapshot": "./dist/bin.js"
   },
   "exports": {
     ".": {