@ankurhalder/codebase-snapshot 2.0.0 → 2.1.1

package/docs/configuration.md

@@ -38,6 +38,81 @@ export default {
 };
 ```
 
+## Project presets
+
+A preset is a detected project shape: layers, kinds, ecosystem ignores and a
+recommended part budget. Detection reads the repository **once** and the first
+matching preset wins, ordered by specificity — so a Next.js app inside a pnpm
+workspace is still a Next.js project.
+
+| Preset | Detected from |
+| :--- | :--- |
+| `nextjs` | `next.config.*`, or `next` |
+| `nuxt` | `nuxt.config.*`, or `nuxt` |
+| `sveltekit` | `svelte.config.*`, `@sveltejs/kit` |
+| `remix` | `@remix-run/*` |
+| `astro` | `astro.config.*`, `astro` |
+| `angular` | `angular.json`, `@angular/core` |
+| `solid` | `solid-js` |
+| `vue-vite` | `vue` + vite |
+| `react-vite` | `react` + vite |
+| `nest` | `@nestjs/core` |
+| `node-express` | `express`, `fastify`, `koa` |
+| `node-lib` | any `package.json` |
+| `python-django` | `manage.py`, or django in the manifest |
+| `python-fastapi` | fastapi / flask in the manifest |
+| `python-lib` | `pyproject.toml`, `setup.py`, `.py` files |
+| `go` | `go.mod` |
+| `rust` | `Cargo.toml` |
+| `java-spring` | `pom.xml`, `build.gradle` |
+| `dotnet` | `*.csproj`, `*.sln` |
+| `php-laravel` | `artisan`, `composer.json` |
+| `ruby-rails` | `Gemfile`, `config.ru` |
+| `monorepo` | `pnpm-workspace.yaml`, `workspaces`, `nx.json`, `turbo.json` |
+| `infra` | `*.tf`, `Chart.yaml`, `docker-compose.yml` |
+| `docs` | mostly Markdown, no `package.json` |
+| `generic` | anything else |
+
+Force one when detection is wrong:
+
+```javascript
+export default {
+  preset: "react-vite",
+};
+```
+
+An unknown name is an error listing every valid preset — never a silent fallback.
+Each preset also contributes ignore patterns the generic list cannot know
+(`__pycache__`, `target`, `vendor`, `bin`/`obj`, …). The resolved preset is
+recorded in `manifest.config.preset`, so changing it shows up as config drift.
+
+---
+
+## Interactive setup
+
+```bash
+npm create codebase-snapshot        # or: npx @ankurhalder/codebase-snapshot init
+```
+
+Detects the project, asks seven questions with real defaults, and writes the
+config. It never prompts when either end is not a TTY: every answer has a flag.
+
+| Flag | Question it answers |
+| :--- | :--- |
+| `--preset <name>` | project type |
+| `--include <globs>` / `--exclude <globs>` | scope |
+| `--max-part-bytes <size>` | part size |
+| `--skip-artifacts` / `--only-artifacts` | artifacts |
+| `--include-sensitive-files` | safety |
+| `--minimal` | write only what differs from the defaults |
+| `--yes` | accept everything, do not prompt |
+| `--force` | overwrite an existing config |
+| `--dry-run` | print the config, write nothing |
+
+The generated config lists **every setting at its current value**, commented and
+grouped. That is deliberate: most people never open the documentation, and a
+config that only records their changes cannot tell them what else exists.
+Deleting any line is safe — the defaults are real.
 ## Classification: layers and kinds
 
 ```javascript
@@ -60,7 +135,11 @@ Rules are evaluated in order, **first match wins**, with an `other` fallback.
 `layersMode: "merge"` (the default) keeps the detected preset's rules and lets
 yours win by being evaluated first. `"replace"` discards the preset entirely.
 
-Presets are auto-detected: **nextjs** → **vite** → **node** → **default**.
+Presets are auto-detected by specificity: the first match in descending priority wins,
+and `generic` is the fallback. There are 25 of them — see the table above. A framework
+that depends on `vite` still resolves to `react-vite` / `vue-vite` because those detectors
+outrank `node-lib`, and a Next.js app inside a pnpm workspace is still `nextjs`, not
+`monorepo`.
 
 ## Sizing: byte budgets
 
@@ -149,6 +228,13 @@ export default {
 and `outDir`/`tmpDir` may not contain each other. Writes are atomic: the previous
 snapshot survives until the new one is fully in place.
 
+Both directories are also **refused if they already exist and this generator did
+not write them** — a typo such as `outDir: "src"` would otherwise replace your
+source tree. Ownership is proved by a `.codebase-snapshot` marker (plus a
+parseable `manifest.json` for older output), never by filenames, so an existing
+`docs/README.md` is never mistaken for a previous snapshot. An empty directory,
+or one holding only `.gitkeep`/`.gitignore`/`.DS_Store`, is always accepted.
+
 ## Hooks
 
 ```javascript
@@ -164,6 +250,16 @@ export default {
 A throwing hook becomes a warning on the manifest — it never loses a snapshot
 that was already written.
 
+A hook may write its own files into the output directory. That is safe across
+reruns: ownership of the directory is established by a `.codebase-snapshot`
+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,
+not the target repo. Use the absolute paths on `manifest` (or resolve against
+`outDir` yourself) when passing `--cwd`.
+
 ---
 
 # Commands

package/docs/install.md

@@ -0,0 +1,150 @@
+# Installation
+
+`@ankurhalder/codebase-snapshot` is published to the public npm registry, so it installs
+with **any** npm-compatible client. There is nothing extra to configure and no second
+registry to add.
+
+Requires **Node.js 18 or newer**.
+
+## One-off use (no install)
+
+```bash
+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
+yarn dlx -p @ankurhalder/codebase-snapshot snap generate   # yarn Berry
+yarn global add @ankurhalder/codebase-snapshot             # yarn classic (installs globally)
+pnpm dlx @ankurhalder/codebase-snapshot generate
+bunx @ankurhalder/codebase-snapshot generate
+```
+
+## Add to a project
+
+```bash
+npm install -D @ankurhalder/codebase-snapshot
+yarn add -D @ankurhalder/codebase-snapshot        # yarn classic and Berry
+pnpm add -D @ankurhalder/codebase-snapshot
+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
+```
+
+Both `snap` and `codebase-snapshot` are exposed as binaries — pick whichever you prefer.
+
+Adding it to `package.json` scripts works the same everywhere:
+
+```json
+{
+  "scripts": {
+    "snapshot": "codebase-snapshot generate",
+    "snapshot:validate": "codebase-snapshot validate"
+  }
+}
+```
+
+## Global install
+
+```bash
+npm install -g @ankurhalder/codebase-snapshot
+pnpm add -g @ankurhalder/codebase-snapshot
+bun add -g @ankurhalder/codebase-snapshot
+```
+
+A global install exists for convenience, but pinning the version per project (the
+`-D`/`--save-dev` examples above) is the better default: snapshots are only reproducible
+if the generator version is reproducible.
+
+## Version pinning
+
+```bash
+npx @ankurhalder/codebase-snapshot@2 generate
+pnpm dlx @ankurhalder/codebase-snapshot@2.1.1 generate
+```
+
+## Verified clients
+
+Every client below was used to install the published package and run
+`snap --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` |
+
+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.
+
+## Package manager workspaces
+
+The binary is resolved from the workspace it is installed in. In a monorepo, install it
+in the package that runs the snapshot (usually the root), or use any client's one-off
+runner (`npx` / `pnpm dlx` / `yarn dlx` / `bunx`) which works from any subdirectory.
+
+## Uninstalling
+
+Standard for your client (`npm uninstall`, `yarn remove`, `pnpm remove`, `bun remove`).
+Snapshots already written to `snapshot/` are ordinary files and are left alone.
+
+## Not supported yet
+
+- **`pip`, `brew`, `scoop`, `docker`, and standalone binaries.** These require shipping a
+  prebuilt executable rather than JavaScript, and are tracked as future work in
+  [docs/plans/distribution](../plans/distribution/README.md). Until then, any machine
+  running the tool needs Node 18+.
+- **Deno.** The API can be imported under Deno's npm compatibility, but running the CLI
+  needs a `./bin` subpath export that is not published yet.
+
+## Troubleshooting
+
+**`snap: 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`.
+
+**`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
+`--ignore-scripts` CI setups do), rerun a clean install, or pin `typescript@^5` yourself.
+
+**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
+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:
+
+```bash
+./node_modules/.bin/snap generate
+npx snap generate          # same, without the yarn wrapper
+```
+
+This is why the CI job in this repository reads the version from a line that *is* the
+version rather than taking the first or last line of output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankurhalder/codebase-snapshot",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Production-grade LLM codebase snapshot generator, auditor, and AST partitioner",
   "keywords": [
     "codebase",
@@ -77,7 +77,8 @@
     "test": "node --test tests/*.test.js",
     "test:coverage": "node --test --experimental-test-coverage tests/*.test.js",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "publish:create": "npm publish packages/create --access public"
   },
   "dependencies": {
     "typescript": "^5.0.0"