nogrep 1.0.0

package/docs/TASKS.md

@@ -0,0 +1,216 @@
+# nogrep — Implementation Tasks
+
+> Work through these tasks in order. Each task is independently testable before moving on.
+> Read docs/CLAUDE.md, docs/SPEC.md, docs/ARCHITECTURE.md, and docs/CONVENTIONS.md before starting.
+
+---
+
+## Task 1 — Project Scaffold
+
+**Goal:** Buildable TypeScript project with plugin manifest.
+
+- [x] Create `package.json` with dependencies: `glob`, `gray-matter`, `js-yaml`
+- [x] Create `package.json` devDependencies: `typescript`, `tsup`, `vitest`, `@types/node`
+- [x] Create `tsconfig.json` (see docs/CONVENTIONS.md)
+- [x] Create `tsup.config.ts` — builds `scripts/` → `dist/`, ESM, declaration files
+- [x] Create `scripts/types.ts` — all types from docs/ARCHITECTURE.md key types section
+- [x] Create `plugin.json` — CC plugin manifest with hook declarations
+- [x] Verify: `npm run build` compiles successfully
+
+---
+
+## Task 2 — Settings
+
+**Goal:** Read/write nogrep settings from `.claude/settings.json` and `.claude/settings.local.json`.
+
+- [x] Create `scripts/settings.ts`
+  - `readSettings(projectRoot)` — reads both files, local takes precedence over shared
+  - `writeSettings(projectRoot, settings, local?)` — writes to shared or local file
+  - Creates `.claude/` dir if it doesn't exist
+  - CLI interface: `node settings.js --set enabled=true [--local]` / `node settings.js --get`
+- [x] Create `commands/on.md` slash command
+  - Runs `node "${CLAUDE_PLUGIN_ROOT}/dist/settings.js" --set enabled=true`
+  - Checks if `.nogrep/_index.json` exists
+  - If missing: suggests running `/nogrep:init`
+- [x] Create `commands/off.md` slash command
+  - Runs `node "${CLAUDE_PLUGIN_ROOT}/dist/settings.js" --set enabled=false`
+- [x] Write `tests/settings.test.ts` — test merge logic, local precedence, file creation
+- [x] Verify: `/nogrep:on` and `/nogrep:off` work in CC
+
+---
+
+## Task 3 — Phase 1: Universal Signals
+
+**Goal:** Collect language-agnostic signals from any project directory.
+
+- [x] Create `scripts/signals.ts`
+  - `collectSignals(root, options)` → `SignalResult`
+  - Walk directory tree (depth 4, skip: node_modules, dist, build, .git, coverage)
+  - Group files by extension → `extensionMap`
+  - Find dependency manifests: `package.json`, `requirements.txt`, `pom.xml`, `go.mod`, `Podfile`, `Cargo.toml`, `pubspec.yaml`, `composer.json`
+  - Find entry points: files named `main.*`, `index.*`, `app.*`, `server.*` at root or src/ level
+  - Run `git log --stat --oneline -50` → parse top 20 most changed files
+  - Find top 20 largest files (excluding node_modules etc)
+  - Find `.env*` files and `config/` directories
+  - Find test files matching `*.test.*`, `*.spec.*`, `*_test.*`, `test_*.py`
+  - CLI interface: `node signals.js [--root <path>] [--exclude <globs>]` → JSON stdout
+- [x] Create `tests/fixtures/nestjs-project/` — minimal NestJS project (5-10 files)
+- [x] Create `tests/fixtures/django-project/` — minimal Django project
+- [x] Create `tests/fixtures/react-project/` — minimal React project
+- [x] Write `tests/signals.test.ts` — run against all 3 fixtures, assert signal shape
+- [x] Verify: signals correctly identifies NestJS vs Django vs React
+
+---
+
+## Task 4 — Source Trimming
+
+**Goal:** Reduce source files to signatures only, language-agnostic.
+
+- [x] Create `scripts/trim.ts`
+  - `trimCluster(paths: string[], projectRoot: string)` → `string`
+  - For each file in the cluster's src_paths:
+    - Read file content
+    - Remove function/method bodies (keep signature line + opening brace only)
+    - Keep: file header comments, imports, class/interface declarations, decorators/annotations, exported symbols, type definitions
+    - Strip: function bodies, private method bodies, inline HTML/template strings
+    - Max 300 lines total across all files — truncate least important files first
+  - Strategy: regex-based (simple, universal — not perfect but good enough)
+  - CLI interface: `node trim.js <path1> <path2> ...` → trimmed output to stdout
+- [x] Write `tests/trim.test.ts` — test against TypeScript, Python, Java snippet fixtures
+- [x] Verify: trimmed output is ~30-50% of original size, signatures intact
+
+---
+
+## Task 5 — Writers
+
+**Goal:** Write all `.nogrep/` files from structured input.
+
+- [x] Create `scripts/write.ts`
+  - Accepts JSON via stdin or `--input <file>` with NodeResult[] + StackResult
+  - `writeContextNodes(nodes, outputDir)` — generates markdown with frontmatter (YAML)
+    - Creates subdirectories: `domains/`, `architecture/`, `flows/`, `entities/`
+    - Appends empty `## Manual Notes` section at end
+    - Existing files: extract Manual Notes, regenerate, re-inject Manual Notes
+  - `buildIndex(nodes, stack)` → writes `_index.json`
+    - Builds reverse maps: tags → [files], keywords → [files], paths → entry
+    - Populates `inverse_relations` by scanning all `relates_to` across nodes
+  - `buildRegistry(nodes)` → writes `_registry.json`
+  - `patchClaudeMd(projectRoot)` — appends navigation instructions
+    - Checks for `<!-- nogrep -->` marker to avoid duplicate patching
+- [x] Create `templates/claude-md-patch.md`:
+  ```markdown
+  <!-- nogrep -->
+  ## Code Navigation
+
+  This project uses [nogrep](https://github.com/techtulp/nogrep).
+  Context files in `.nogrep/` are a navigable index of this codebase.
+  When you see nogrep results injected into your context, trust them —
+  read those files before exploring source.
+  <!-- /nogrep -->
+  ```
+- [x] Write `tests/writer.test.ts` — write to temp dirs, verify file contents and frontmatter
+- [x] Verify: running writers on fixture data produces valid markdown with parseable frontmatter
+
+---
+
+## Task 6 — Init Slash Command
+
+**Goal:** `/nogrep:init` orchestrates the full pipeline with Claude doing the AI work.
+
+- [x] Create `commands/init.md`
+  - Step 1: Run `node "${CLAUDE_PLUGIN_ROOT}/dist/signals.js" --root .` → collect signals
+  - Step 2: Embed Phase 2 prompt — Claude analyzes signals, produces StackResult JSON
+  - Step 3: For each domain cluster, embed Phase 3 prompt — Claude reads trimmed source (via `node "${CLAUDE_PLUGIN_ROOT}/dist/trim.js"`), produces NodeResult JSON
+  - Step 4: Claude detects flows (clusters touching 3+ domains or named with flow keywords)
+  - Step 5: Run `node "${CLAUDE_PLUGIN_ROOT}/dist/write.js"` with all results piped as JSON stdin
+  - Step 6: Run `node "${CLAUDE_PLUGIN_ROOT}/dist/settings.js" --set enabled=true`
+  - See docs/SPEC.md Section 13 for prompt templates
+- [x] Test: run `/nogrep:init` in CC on a fixture project, inspect `.nogrep/` output
+
+---
+
+## Task 7 — Query System
+
+**Goal:** Fast index lookup without AI.
+
+- [x] Create `scripts/query.ts`
+  - `extractTerms(question, taxonomy)` → `{ tags, keywords }`
+    - Split question into words, lowercase
+    - Match against taxonomy domain/tech values → tags
+    - Match against any word → keywords (pass through)
+    - No AI — pure string matching
+  - `resolve(terms, index)` → `RankedResult[]`
+    - Union lookup: find all nodes matching any tag or keyword
+    - Score: +2 per tag match, +1 per keyword match
+    - Sort by score descending, return top N (default 5)
+  - CLI interface: `node query.js --tags <tags> | --keywords <words> | --question <text> [--format paths|json|summary] [--limit N]`
+  - Throws `NogrepError('NO_INDEX')` if `_index.json` missing
+- [x] Create `commands/query.md` slash command — runs `node "${CLAUDE_PLUGIN_ROOT}/dist/query.js" --question "$ARGUMENTS"`
+- [x] Write `tests/query.test.ts` — test extraction and resolution
+- [ ] Verify: `node dist/query.js --question "how does stripe work"` returns billing context file
+
+---
+
+## Task 8 — Validator + Update + Status
+
+**Goal:** Staleness detection and incremental updates.
+
+- [x] Create `scripts/validate.ts`
+  - `checkFreshness(node, projectRoot)` → `StaleResult`
+  - Glob all files matching node's `src_paths`
+  - Compute SHA256 of all file contents concatenated
+  - Compare to `last_synced.src_hash` in frontmatter
+  - CLI interface: `node validate.js [--format text|json]` → staleness report
+- [x] Create `commands/update.md` slash command
+  - Guides Claude through: git diff → map to affected nodes → re-analyze → write updates
+  - Preserves `## Manual Notes` section
+- [x] Create `commands/status.md` slash command
+  - Runs `node "${CLAUDE_PLUGIN_ROOT}/dist/validate.js"` and shows node counts, freshness summary
+- [x] Write `tests/validate.test.ts` — test staleness detection
+
+---
+
+## Task 9 — Hooks
+
+**Goal:** Automatic context injection via CC hooks.
+
+- [x] Create `hooks/pre-tool-use.sh` (see docs/SPEC.md Section 10)
+  - Intercepts grep/find/rg/ag commands
+  - Calls `node "${CLAUDE_PLUGIN_ROOT}/dist/query.js"` with extracted keywords
+  - Injects results as `additionalContext`
+- [x] Create `hooks/session-start.sh` (see docs/SPEC.md Section 10)
+  - Checks index existence and freshness on session start
+  - Calls `node "${CLAUDE_PLUGIN_ROOT}/dist/validate.js"`
+- [x] Create `hooks/prompt-submit.sh` (see docs/SPEC.md Section 10)
+  - Injects relevant context for code navigation prompts
+  - Calls `node "${CLAUDE_PLUGIN_ROOT}/dist/query.js"`
+- [x] Make all `.sh` scripts executable (`chmod +x`)
+- [ ] Test: install plugin locally in CC, verify hooks fire
+
+---
+
+## Task 10 — README + Distribution
+
+**Goal:** Ready for npm publish as CC plugin.
+
+- [x] Write `README.md`:
+  - What it does (one paragraph)
+  - Install as CC plugin
+  - Quick start (3 steps)
+  - How it works (brief pipeline overview)
+  - Available commands
+  - FAQ
+- [x] Add `files` field to `package.json` — ship `dist/`, `commands/`, `hooks/`, `templates/`, `plugin.json`
+- [x] Verify `npm pack` produces correct bundle
+- [x] Add `prepublish` script: `npm run build && npm test`
+
+---
+
+## Definition of Done
+
+All tasks complete when:
+- `/nogrep:init` runs successfully in CC on a real project and produces valid `.nogrep/`
+- `/nogrep:query` returns correct context files
+- CC hooks intercept grep commands and inject nogrep context
+- All unit tests pass: `npm test`
+- README is clear enough for a stranger to get started in 2 minutes

package/hooks/hooks.json

@@ -0,0 +1,35 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/prompt-submit.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pre-tool-use.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Only intercept search commands
+if ! echo "$COMMAND" | grep -qE '^\s*(grep|find|rg|ag|fd)\s'; then
+  exit 0
+fi
+
+# Check nogrep is enabled
+ENABLED=$(cat .claude/settings.json 2>/dev/null | jq -r '.nogrep.enabled // false')
+LOCAL_ENABLED=$(cat .claude/settings.local.json 2>/dev/null | jq -r '.nogrep.enabled // empty')
+[ -n "$LOCAL_ENABLED" ] && ENABLED="$LOCAL_ENABLED"
+[ "$ENABLED" != "true" ] && exit 0
+
+# Check index exists
+[ ! -f ".nogrep/_index.json" ] && exit 0
+
+# Extract keywords from the grep command
+KEYWORDS=$(echo "$COMMAND" \
+  | sed -E 's/(grep|rg|ag|find)\s+(-[a-zA-Z]+\s+)*//' \
+  | tr -d '"'"'" \
+  | awk '{print $1}')
+
+[ -z "$KEYWORDS" ] && exit 0
+
+# Query nogrep
+SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/dist"
+RESULT=$(node "$SCRIPT_DIR/query.js" --keywords "$KEYWORDS" --format summary --limit 3 2>/dev/null)
+
+if [ -n "$RESULT" ]; then
+  jq -n \
+    --arg ctx "nogrep — read these context files before searching:\n\n$RESULT\n\nThese files tell you exactly where to look. Only proceed with the grep if they don't answer your question." \
+    '{ additionalContext: $ctx }'
+fi
+
+exit 0

package/hooks/prompt-submit.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')
+
+ENABLED=$(cat .claude/settings.json 2>/dev/null | jq -r '.nogrep.enabled // false')
+LOCAL_ENABLED=$(cat .claude/settings.local.json 2>/dev/null | jq -r '.nogrep.enabled // empty')
+[ -n "$LOCAL_ENABLED" ] && ENABLED="$LOCAL_ENABLED"
+[ "$ENABLED" != "true" ] && exit 0
+[ ! -f ".nogrep/_index.json" ] && exit 0
+[ -z "$PROMPT" ] && exit 0
+
+# Only inject for prompts that seem to be about code navigation
+if ! echo "$PROMPT" | grep -qiE '(where|how|which|what|find|look|show|implement|fix|add|change|update|refactor)'; then
+  exit 0
+fi
+
+SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/dist"
+RESULT=$(node "$SCRIPT_DIR/query.js" --question "$PROMPT" --format summary --limit 3 2>/dev/null)
+
+if [ -n "$RESULT" ]; then
+  jq -n \
+    --arg ctx "nogrep context for your question:\n\n$RESULT\n\nRead these files first before exploring source." \
+    '{ additionalContext: $ctx }'
+fi
+
+exit 0

package/hooks/session-start.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+ENABLED=$(cat .claude/settings.json 2>/dev/null | jq -r '.nogrep.enabled // false')
+LOCAL_ENABLED=$(cat .claude/settings.local.json 2>/dev/null | jq -r '.nogrep.enabled // empty')
+[ -n "$LOCAL_ENABLED" ] && ENABLED="$LOCAL_ENABLED"
+[ "$ENABLED" != "true" ] && exit 0
+
+if [ ! -f ".nogrep/_index.json" ]; then
+  jq -n '{ additionalContext: "nogrep is enabled but no index found. Run `/nogrep:init` to generate the codebase index before starting work." }'
+  exit 0
+fi
+
+SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/dist"
+STALE=$(node "$SCRIPT_DIR/validate.js" --format json 2>/dev/null | jq -r '.stale[]?.file' | head -3)
+
+if [ -n "$STALE" ]; then
+  jq -n \
+    --arg s "$STALE" \
+    '{ additionalContext: ("nogrep index may be stale. Consider running `/nogrep:update` before starting.\nStale nodes:\n" + $s) }'
+fi
+
+exit 0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "nogrep",
+  "version": "1.0.0",
+  "description": "Navigable codebase index for Claude Code — stop grepping, start navigating",
+  "type": "module",
+  "files": ["dist", "commands", "hooks", "scripts", "templates", "docs"],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "glob": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}

package/scripts/query.ts

@@ -0,0 +1,290 @@
+import { readFile } from 'node:fs/promises'
+import { join, resolve as resolvePath } from 'node:path'
+import { parseArgs } from 'node:util'
+import type { IndexJson, RankedResult, Taxonomy } from './types.js'
+import { NogrepError } from './types.js'
+
+// --- Term extraction ---
+
+export function extractTerms(
+  question: string,
+  taxonomy: Taxonomy,
+): { tags: string[]; keywords: string[] } {
+  const words = question
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 1)
+
+  const tags: string[] = []
+  const keywords: string[] = []
+
+  // Collect all taxonomy values for matching
+  const tagLookup = new Map<string, string>()
+
+  for (const val of taxonomy.static.layer) {
+    tagLookup.set(val.toLowerCase(), `layer:${val}`)
+  }
+  for (const val of taxonomy.static.concern) {
+    tagLookup.set(val.toLowerCase(), `concern:${val}`)
+  }
+  for (const val of taxonomy.static.type) {
+    tagLookup.set(val.toLowerCase(), `type:${val}`)
+  }
+  for (const val of taxonomy.dynamic.domain) {
+    tagLookup.set(val.toLowerCase(), `domain:${val}`)
+  }
+  for (const val of taxonomy.dynamic.tech) {
+    tagLookup.set(val.toLowerCase(), `tech:${val}`)
+  }
+  for (const [cat, values] of Object.entries(taxonomy.custom)) {
+    for (const val of values) {
+      tagLookup.set(val.toLowerCase(), `${cat}:${val}`)
+    }
+  }
+
+  // Stop words to skip as keywords
+  const stopWords = new Set([
+    'the', 'is', 'at', 'in', 'of', 'on', 'to', 'a', 'an', 'and', 'or',
+    'for', 'it', 'do', 'does', 'how', 'what', 'where', 'which', 'when',
+    'who', 'why', 'this', 'that', 'with', 'from', 'by', 'be', 'as',
+    'are', 'was', 'were', 'been', 'has', 'have', 'had', 'not', 'but',
+    'if', 'my', 'our', 'its', 'can', 'will', 'should', 'would', 'could',
+    'about', 'after', 'work', 'works', 'use', 'uses', 'used',
+  ])
+
+  for (const word of words) {
+    const tag = tagLookup.get(word)
+    if (tag && !tags.includes(tag)) {
+      tags.push(tag)
+    }
+
+    // Also check hyphenated compound matches (e.g. "error-handling")
+    if (!tag && !stopWords.has(word)) {
+      keywords.push(word)
+    }
+  }
+
+  // Check for multi-word tag matches (e.g. "error handling" → "error-handling")
+  const questionLower = question.toLowerCase()
+  for (const [val, tag] of tagLookup.entries()) {
+    if (val.includes('-')) {
+      const spacedVersion = val.replace(/-/g, ' ')
+      if (questionLower.includes(spacedVersion) && !tags.includes(tag)) {
+        tags.push(tag)
+      }
+      if (questionLower.includes(val) && !tags.includes(tag)) {
+        tags.push(tag)
+      }
+    }
+  }
+
+  return { tags, keywords }
+}
+
+// --- Resolution ---
+
+export function resolveQuery(
+  terms: { tags: string[]; keywords: string[] },
+  index: IndexJson,
+  limit = 5,
+): RankedResult[] {
+  const scoreMap = new Map<string, { score: number; matchedOn: string[] }>()
+
+  function addMatch(contextFile: string, score: number, matchLabel: string): void {
+    const existing = scoreMap.get(contextFile)
+    if (existing) {
+      existing.score += score
+      existing.matchedOn.push(matchLabel)
+    } else {
+      scoreMap.set(contextFile, { score, matchedOn: [matchLabel] })
+    }
+  }
+
+  // Tag matching: +2 per match
+  for (const tag of terms.tags) {
+    const files = index.tags[tag]
+    if (files) {
+      for (const file of files) {
+        addMatch(file, 2, `tag:${tag}`)
+      }
+    }
+  }
+
+  // Keyword matching: +1 per match
+  for (const kw of terms.keywords) {
+    const kwLower = kw.toLowerCase()
+
+    // Direct keyword lookup
+    const files = index.keywords[kwLower]
+    if (files) {
+      for (const file of files) {
+        addMatch(file, 1, `keyword:${kwLower}`)
+      }
+    }
+
+    // Also search all index keywords for partial matches
+    for (const [indexKw, kwFiles] of Object.entries(index.keywords)) {
+      if (indexKw === kwLower) continue // Already handled
+      if (indexKw.includes(kwLower) || kwLower.includes(indexKw)) {
+        for (const file of kwFiles) {
+          addMatch(file, 1, `keyword:${indexKw}`)
+        }
+      }
+    }
+  }
+
+  // Sort by score descending, then alphabetically for ties
+  const results: RankedResult[] = [...scoreMap.entries()]
+    .sort((a, b) => b[1].score - a[1].score || a[0].localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([contextFile, { score, matchedOn }]) => ({
+      contextFile,
+      score,
+      matchedOn: [...new Set(matchedOn)],
+      summary: `Matched: ${[...new Set(matchedOn)].join(', ')}`,
+    }))
+
+  return results
+}
+
+// --- Index + taxonomy loading ---
+
+async function loadIndex(projectRoot: string): Promise<IndexJson> {
+  const indexPath = join(projectRoot, '.nogrep', '_index.json')
+  try {
+    const content = await readFile(indexPath, 'utf-8')
+    return JSON.parse(content) as IndexJson
+  } catch {
+    throw new NogrepError(
+      'No .nogrep/_index.json found. Run /nogrep:init first.',
+      'NO_INDEX',
+    )
+  }
+}
+
+async function loadTaxonomy(projectRoot: string): Promise<Taxonomy> {
+  const taxonomyPath = join(projectRoot, '.nogrep', '_taxonomy.json')
+  try {
+    const content = await readFile(taxonomyPath, 'utf-8')
+    return JSON.parse(content) as Taxonomy
+  } catch {
+    // Return default taxonomy if file doesn't exist
+    return {
+      static: {
+        layer: ['presentation', 'business', 'data', 'infrastructure', 'cross-cutting'],
+        concern: ['security', 'performance', 'caching', 'validation', 'error-handling', 'idempotency', 'observability'],
+        type: ['module', 'flow', 'entity', 'integration', 'config', 'ui', 'test'],
+      },
+      dynamic: { domain: [], tech: [] },
+      custom: {},
+    }
+  }
+}
+
+function buildTaxonomyFromIndex(index: IndexJson, baseTaxonomy: Taxonomy): Taxonomy {
+  // Extract dynamic domain and tech values from the index tags
+  const domains = new Set<string>(baseTaxonomy.dynamic.domain)
+  const techs = new Set<string>(baseTaxonomy.dynamic.tech)
+
+  for (const tagKey of Object.keys(index.tags)) {
+    const [category, value] = tagKey.split(':')
+    if (!category || !value) continue
+    if (category === 'domain') domains.add(value)
+    if (category === 'tech') techs.add(value)
+  }
+
+  return {
+    ...baseTaxonomy,
+    dynamic: {
+      domain: [...domains],
+      tech: [...techs],
+    },
+  }
+}
+
+// --- Formatting ---
+
+function formatPaths(results: RankedResult[]): string {
+  return results.map(r => r.contextFile).join('\n')
+}
+
+function formatJson(results: RankedResult[]): string {
+  return JSON.stringify(results, null, 2)
+}
+
+function formatSummary(results: RankedResult[]): string {
+  if (results.length === 0) return 'No matching context files found.'
+  return results
+    .map(r => `- ${r.contextFile} (score: ${r.score}) — ${r.summary}`)
+    .join('\n')
+}
+
+// --- CLI ---
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({
+    options: {
+      tags: { type: 'string' },
+      keywords: { type: 'string' },
+      question: { type: 'string' },
+      format: { type: 'string', default: 'json' },
+      limit: { type: 'string', default: '5' },
+      root: { type: 'string', default: process.cwd() },
+    },
+    strict: true,
+  })
+
+  const root = resolvePath(values.root ?? process.cwd())
+  const limit = parseInt(values.limit ?? '5', 10)
+  const format = values.format ?? 'json'
+
+  const index = await loadIndex(root)
+  const baseTaxonomy = await loadTaxonomy(root)
+  const taxonomy = buildTaxonomyFromIndex(index, baseTaxonomy)
+
+  let terms: { tags: string[]; keywords: string[] }
+
+  if (values.question) {
+    terms = extractTerms(values.question, taxonomy)
+  } else if (values.tags || values.keywords) {
+    const tags = values.tags
+      ? values.tags.split(',').map(t => t.trim()).filter(Boolean)
+      : []
+    const keywords = values.keywords
+      ? values.keywords.split(',').map(k => k.trim()).filter(Boolean)
+      : []
+    terms = { tags, keywords }
+  } else {
+    process.stderr.write(
+      JSON.stringify({ error: 'Usage: node query.js --tags <tags> | --keywords <words> | --question <text> [--format paths|json|summary] [--limit N]' }) + '\n',
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const results = resolveQuery(terms, index, limit)
+
+  switch (format) {
+    case 'paths':
+      process.stdout.write(formatPaths(results) + '\n')
+      break
+    case 'summary':
+      process.stdout.write(formatSummary(results) + '\n')
+      break
+    case 'json':
+    default:
+      process.stdout.write(formatJson(results) + '\n')
+      break
+  }
+}
+
+main().catch((err: unknown) => {
+  if (err instanceof NogrepError) {
+    process.stderr.write(JSON.stringify({ error: err.message, code: err.code }) + '\n')
+  } else {
+    const message = err instanceof Error ? err.message : String(err)
+    process.stderr.write(JSON.stringify({ error: message }) + '\n')
+  }
+  process.exitCode = 1
+})