@ankurhalder/codebase-snapshot 2.1.0 → 2.2.0

package/dist/index.cjs

@@ -1707,11 +1707,12 @@ function detectPreset(cwd, forced) {
 }
 function getGitInfo(cwd, fallbackBranch = "main") {
   try {
-    const branch = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
+    const reported = childProcess__namespace.execSync("git rev-parse --abbrev-ref HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
       encoding: "utf8"
-    }).trim() || fallbackBranch;
+    }).trim();
+    const branch = !reported || reported === "HEAD" ? fallbackBranch : reported;
     const commit = childProcess__namespace.execSync("git rev-parse HEAD", {
       cwd,
       stdio: ["ignore", "pipe", "ignore"],
@@ -2332,6 +2333,9 @@ async function loadConfigFileDetailed(cwd) {
       if (snapshotKey && typeof snapshotKey === "object") {
         return { config: snapshotKey, file: pkgJsonPath, warnings, errors };
       }
+      if (snapshotKey !== void 0) {
+        warnings.push(`${pkgJsonPath}: the "snapshot" key must be an object; it was ignored.`);
+      }
     } catch (err) {
       const message = err.message;
       warnings.push(message);
@@ -3446,6 +3450,7 @@ function validateSnapshot(configInput) {
       drift.missingOnDisk.push(snapshotFile);
     }
   }
+  drift.missingOnDisk = [...new Set(drift.missingOnDisk)];
   const maxEffectiveBudget = Math.max(
     config.maxPartBytes,
     config.budgets.default,
@@ -3857,7 +3862,13 @@ function compareManifests(before, after) {
   };
 }
 function loadManifest(target) {
-  const manifestPath = fs9__namespace.statSync(target).isDirectory() ? path10__namespace.join(target, "manifest.json") : target;
+  let isDirectory;
+  try {
+    isDirectory = fs9__namespace.statSync(target).isDirectory();
+  } catch {
+    throw new Error(`No snapshot found at ${target}: the path does not exist.`);
+  }
+  const manifestPath = isDirectory ? path10__namespace.join(target, "manifest.json") : target;
   let raw;
   try {
     raw = fs9__namespace.readFileSync(manifestPath, "utf8");
@@ -3873,6 +3884,9 @@ function loadManifest(target) {
   if (!parsed || !Array.isArray(parsed.files)) {
     throw new Error(`${manifestPath} is not a snapshot manifest (no "files" array).`);
   }
+  if (!parsed.counts || typeof parsed.counts !== "object") {
+    throw new Error(`${manifestPath} is not a snapshot manifest (no "counts" object).`);
+  }
   return parsed;
 }
 function renderDiffText(diff) {
@@ -3929,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  // ")}
@@ -4002,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) {
@@ -4030,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 {
@@ -4300,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" },
@@ -4505,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 {
@@ -4543,7 +4565,7 @@ async function runInit(options) {
 
 // src/index.ts
 var GENERATOR_NAME = "@ankurhalder/codebase-snapshot";
-var GENERATOR_VERSION = "2.1.0";
+var GENERATOR_VERSION = "2.2.0";
 var SCHEMA_VERSION = "3.0.0";
 function sha256Hex2(input) {
   return crypto__namespace.createHash("sha256").update(input).digest("hex");
@@ -4787,7 +4809,9 @@ function artifactWarnings(artifacts) {
     );
   }
   if (ARTIFACT_NAMES.every((name) => artifacts[name] === false)) {
-    messages.push("every artifact is disabled: the snapshot directory will be empty.");
+    messages.push(
+      "every artifact is disabled: only the .codebase-snapshot ownership marker will be written."
+    );
   }
   return messages;
 }

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.0";
+declare const GENERATOR_VERSION = "2.2.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.0";
+declare const GENERATOR_VERSION = "2.2.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-QEIOXPMU.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-5I564BGX.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.
+
+`snap 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/install.md

@@ -12,6 +12,20 @@ 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:
+
+```bash
+npx @ankurhalder/codebase-snapshot@latest generate
+npx @ankurhalder/codebase-snapshot@2 generate
+```
+
+`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.
+
 Equivalent one-liners for other clients:
 
 ```bash
@@ -68,7 +82,7 @@ if the generator version is reproducible.
 
 ```bash
 npx @ankurhalder/codebase-snapshot@2 generate
-pnpm dlx @ankurhalder/codebase-snapshot@2.1.0 generate
+pnpm dlx @ankurhalder/codebase-snapshot@2.2.0 generate
 ```
 
 ## Verified clients

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankurhalder/codebase-snapshot",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Production-grade LLM codebase snapshot generator, auditor, and AST partitioner",
   "keywords": [
     "codebase",