@ankurhalder/codebase-snapshot 2.1.1 → 2.2.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 = "2.2.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 = "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.1";
+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-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-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

@@ -82,7 +82,7 @@ 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@2.2.0 generate
 ```
 
 ## Verified clients

package/package.json

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