nogrep 1.0.0

package/docs/CLAUDE.md

@@ -0,0 +1,161 @@
+# nogrep — Implementation Guide for Claude Code
+
+## What You Are Building
+
+`nogrep` is a Claude Code plugin that gives AI agents a navigable index of any codebase, so they stop doing blind grep/find exploration.
+
+**The one thing it does:** Generate and maintain a structured `.nogrep/` directory with a reverse index (`_index.json`) and thin context nodes (markdown files), so CC can find the right files in 2 reads instead of 20.
+
+**What it is NOT:** A documentation generator, a code search engine, a standalone CLI, or a replacement for GSD or Compodoc. It is a navigation layer — intentionally minimal, fully scoped to Claude Code.
+
+---
+
+## Before You Start
+
+Read these files in order before writing any code:
+
+1. `docs/SPEC.md` — full technical specification, schemas, pipeline details
+2. `docs/ARCHITECTURE.md` — project structure and module boundaries
+3. `docs/CONVENTIONS.md` — code style, naming, patterns to follow
+
+---
+
+## Project Stack
+
+- **Language:** TypeScript (strict mode)
+- **Runtime:** Node.js 20+
+- **Package manager:** npm
+- **Testing:** Vitest
+- **Build:** `tsup`
+- **Distribution:** CC plugin (npm package)
+
+---
+
+## Repository Structure to Create
+
+```
+nogrep/
+├── scripts/
+│   ├── signals.ts        # Phase 1: universal signal collection
+│   ├── query.ts          # index lookup (called by hooks)
+│   ├── validate.ts       # staleness check (called by hooks)
+│   ├── write.ts          # structured file writer (context nodes, index, registry)
+│   ├── settings.ts       # read/write .claude/settings.json
+│   ├── trim.ts           # language-agnostic source trimming
+│   └── types.ts          # all shared TypeScript types
+├── commands/
+│   ├── init.md           # orchestrates full init pipeline
+│   ├── update.md         # diff-based update of stale nodes
+│   ├── query.md          # manual index lookup
+│   ├── status.md         # coverage + freshness summary
+│   ├── on.md             # enable nogrep
+│   └── off.md            # disable nogrep
+├── hooks/
+│   ├── pre-tool-use.sh   # intercepts grep/find/rg
+│   ├── session-start.sh  # checks index freshness on session start
+│   └── prompt-submit.sh  # injects context on every user prompt
+├── templates/
+│   └── claude-md-patch.md  # snippet appended to target project CLAUDE.md
+├── tests/
+│   ├── fixtures/           # sample mini-projects for testing
+│   │   ├── nestjs-project/
+│   │   ├── django-project/
+│   │   └── react-project/
+│   ├── signals.test.ts
+│   ├── query.test.ts
+│   └── writer.test.ts
+├── docs/
+│   ├── CLAUDE.md           # this file
+│   ├── SPEC.md             # full technical spec
+│   ├── ARCHITECTURE.md     # internal architecture doc
+│   ├── CONVENTIONS.md      # coding conventions
+│   └── TASKS.md            # implementation tasks
+├── plugin.json
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## Implementation Order
+
+Implement in this exact order — each step is testable before moving on:
+
+### Step 1 — Scaffold
+- `package.json`, `tsconfig.json`, `tsup.config.ts`
+- `scripts/types.ts` — all types first
+- `plugin.json` — CC plugin manifest
+
+### Step 2 — Settings
+- `scripts/settings.ts` — read/write `.claude/settings.json` and `.claude/settings.local.json`
+- `commands/on.md` and `commands/off.md` slash commands
+
+### Step 3 — Phase 1: Signals (no AI)
+- `scripts/signals.ts` — universal signal collection
+- Test against the fixtures in `tests/fixtures/`
+
+### Step 4 — Source Trimming
+- `scripts/trim.ts` — language-agnostic source trimming
+- Test against TypeScript, Python, Java snippet fixtures
+
+### Step 5 — Writers
+- `scripts/write.ts` — context files, index builder, registry, CLAUDE.md patcher
+- `templates/claude-md-patch.md`
+- Test: write to temp dirs, verify file contents
+
+### Step 6 — Init Slash Command
+- `commands/init.md` — orchestrates the full pipeline
+- Embeds Phase 2 + Phase 3 prompts (Claude does the AI work)
+- Calls `dist/signals.js` for data, `dist/write.js` for output via `${CLAUDE_PLUGIN_ROOT}`
+
+### Step 7 — Query System
+- `scripts/query.ts` — extractor + resolver
+- `commands/query.md` slash command
+
+### Step 8 — Validate + Update + Status
+- `scripts/validate.ts` — staleness detection
+- `commands/update.md` — guided incremental update
+- `commands/status.md` — index health summary
+
+### Step 9 — Hooks
+- `hooks/pre-tool-use.sh` — intercepts grep/find
+- `hooks/session-start.sh` — freshness check
+- `hooks/prompt-submit.sh` — context injection
+
+### Step 10 — README + Distribution
+- `README.md`
+- Verify `npm pack` ships correct files
+
+---
+
+## Key Decisions Already Made
+
+- **No standalone CLI.** Everything runs inside CC via slash commands and hooks.
+- **No AI client / SDK.** Claude IS the AI — slash commands contain the analysis prompts, Claude executes them directly.
+- **No database.** Everything is files. `.nogrep/` lives in the repo.
+- **Scripts are mechanical.** They collect data, write files, query indexes — no AI work.
+- **Nodes are intentionally thin** — 3 sentences of purpose, public surface, does-not-own, gotchas. Not comprehensive docs.
+- **Manual Notes section** in each node is never overwritten by update.
+- **Hooks intercept at tool-call level** — not just CLAUDE.md instructions, so CC cannot bypass.
+- **Per-project settings** — `.claude/settings.json` (team, committed) or `.claude/settings.local.json` (personal, gitignored).
+- **CI is out of scope for v1** — index maintained via `/nogrep:update` during CC sessions.
+
+---
+
+## Environment Variables
+
+```bash
+NOGREP_DEBUG         # optional, set to 1 for verbose script output
+```
+
+No `ANTHROPIC_API_KEY` needed — Claude does the AI work directly.
+
+---
+
+## Testing Approach
+
+- Use **Vitest** for all tests
+- Fixture projects in `tests/fixtures/` are minimal — 5-10 files each, enough to test detection
+- No AI mocking needed — scripts are pure data/IO
+- Run: `npm test`

package/docs/CONVENTIONS.md

@@ -0,0 +1,162 @@
+# nogrep — Coding Conventions
+
+## Language & Runtime
+
+- TypeScript strict mode — `"strict": true` in tsconfig
+- Node.js 20+
+- ESM modules (`"type": "module"` in package.json)
+- No `any` — use `unknown` and narrow
+
+---
+
+## Naming
+
+```typescript
+// Files: kebab-case
+signals.ts
+index-builder.ts
+pre-tool-use.sh
+
+// Types/Interfaces: PascalCase
+interface StackResult { ... }
+interface NodeResult { ... }
+
+// Functions: camelCase, verb-first
+collectSignals()
+buildIndex()
+resolveQuery()
+extractTerms()
+checkFreshness()
+
+// Constants: UPPER_SNAKE_CASE
+const MAX_CLUSTER_LINES = 300
+```
+
+---
+
+## Functions
+
+- Small and focused — one responsibility
+- Pure functions where possible (especially in scripts)
+- Prefer named parameters for 3+ args:
+
+```typescript
+// ✅
+writeContextFiles({ nodes, outputDir, preserveManualNotes })
+
+// ❌
+writeContextFiles(nodes, outputDir, true)
+```
+
+- Always type return values explicitly on exported functions
+- Async/await everywhere — no raw Promise chains
+
+---
+
+## Error Handling
+
+Always use `NogrepError` with a code for expected failures:
+
+```typescript
+// ✅
+throw new NogrepError('No .nogrep/_index.json found. Run /nogrep:init first.', 'NO_INDEX')
+
+// ❌
+throw new Error('not found')
+```
+
+Scripts catch `NogrepError` and output JSON errors to stderr.
+Hooks fail silently (exit 0) — never block the CC session.
+
+---
+
+## File I/O
+
+- All file paths are absolute — resolve early, pass around as absolute
+- Use `fs/promises` — no sync fs calls
+- Writer functions take `outputDir` as explicit parameter — never hardcode `.nogrep/`
+
+---
+
+## Script Output
+
+Scripts communicate via stdout (JSON for data, plain text for human-readable).
+
+```
+# ✅ Good
+{ "nodes": 17, "stale": 1 }
+
+# ❌ Too chatty
+🚀 Starting signal collection...
+📁 Found 42 files...
+```
+
+Verbose output only when `NOGREP_DEBUG=1`, and goes to stderr.
+
+---
+
+## Package Structure
+
+```json
+{
+  "type": "module",
+  "files": ["dist/", "commands/", "hooks/", "templates/", "plugin.json"]
+}
+```
+
+---
+
+## Dependencies
+
+Keep dependencies minimal. Approved list:
+
+| Package | Purpose |
+|---------|---------|
+| `glob` | file glob matching |
+| `gray-matter` | frontmatter parsing |
+| `js-yaml` | YAML serialization |
+| `vitest` | testing (dev) |
+| `tsup` | build (dev) |
+| `typescript` | type checking (dev) |
+| `@types/node` | Node type defs (dev) |
+
+Do not add new dependencies without a strong reason.
+
+---
+
+## tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "outDir": "./dist",
+    "rootDir": "./scripts",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["scripts/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+---
+
+## Tests
+
+- Test files in `tests/` directory
+- Use `describe` + `it` — not `test`
+- Each test file is independent — no shared state between files
+- Use `vitest`'s `vi.mock` sparingly — prefer dependency injection
+
+```typescript
+// ✅ injectable
+const result = collectSignals('/path/to/fixture', { exclude: [] })
+
+// ❌ global mock
+vi.mock('fs/promises')
+```