codebase-context 1.6.2 → 1.8.0

package/docs/cli.md

@@ -0,0 +1,196 @@
+# CLI Gallery (Human-readable)
+
+`codebase-context` exposes its MCP tools as a local CLI so humans can:
+
+- Onboard themselves onto an unfamiliar repo
+- Debug what the MCP server is doing
+- Use outputs in CI/scripts (via `--json`)
+
+> Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary).
+
+## How to run
+
+```bash
+# Run from a repo root, or set CODEBASE_ROOT explicitly:
+CODEBASE_ROOT=/path/to/repo npx -y codebase-context status
+
+# Every command supports --json (machine output). Human mode is default.
+npx -y codebase-context patterns --json
+```
+
+### ASCII fallback
+
+If your terminal doesn’t render Unicode box-drawing cleanly:
+
+```bash
+CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context patterns
+```
+
+## Commands
+
+- `metadata` — tech stack overview
+- `patterns` — team conventions + adoption/trends
+- `search --query <q>` — ranked results; add `--intent edit` for a preflight card
+- `refs --symbol <name>` — concrete reference evidence
+- `cycles` — circular dependency detection
+- `status` — index status/progress
+- `reindex` — rebuild index (full or incremental)
+- `style-guide` — find style guide sections in docs
+- `memory list|add|remove` — manage team memory (stored in `.codebase-context/memory.json`)
+
+---
+
+## `metadata`
+
+```bash
+npx -y codebase-context metadata
+```
+
+Example output:
+
+```text
+┌─ codebase-context [monorepo] ────────────────────────────────────────┐
+│                                                                      │
+│ Framework: Angular unknown   Architecture: mixed                     │
+│ 130 files · 24,211 lines · 1077 components                           │
+│                                                                      │
+│ Dependencies: @huggingface/transformers · @lancedb/lancedb ·         │
+│ @modelcontextprotocol/sdk · @typescript-eslint/typescript-estree ·   │
+│ chokidar · fuse.js (+14 more)                                        │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `patterns`
+
+```bash
+npx -y codebase-context patterns
+```
+
+Example output (truncated):
+
+```text
+┌─ Team Patterns ──────────────────────────────────────────────────────┐
+│                                                                      │
+│ UNIT TEST FRAMEWORK                                                  │
+│      USE: Vitest – 96% adoption                                      │
+│ alt  CAUTION: Jest – 4% minority pattern                             │
+│                                                                      │
+│ STATE MANAGEMENT                                                     │
+│      PREFER: RxJS – 63% adoption                                     │
+│ alt  Redux-style store – 25%                                         │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `search`
+
+```bash
+npx -y codebase-context search --query "file watcher" --intent edit --limit 3
+```
+
+Example output (truncated):
+
+```text
+┌─ Search: "file watcher" ─── intent: edit ────────────────────────────┐
+│ Quality: ok (1.00)                                                   │
+│ Ready to edit: YES                                                   │
+│                                                                      │
+│ Best example: index.ts                                               │
+└──────────────────────────────────────────────────────────────────────┘
+
+1.  src/core/file-watcher.ts:44-74
+    confidence: ██████████ 1.18
+    typescript module in file-watcher.ts: startFileWatcher :: (...)
+```
+
+## `refs`
+
+```bash
+npx -y codebase-context refs --symbol "startFileWatcher" --limit 10
+```
+
+Example output (truncated):
+
+```text
+┌─ startFileWatcher ─── 11 references ─── static analysis ─────────────┐
+│                                                                      │
+│ startFileWatcher                                                     │
+│ │                                                                    │
+│ ├─ file-watcher.test.ts:5                                            │
+│ │   import { startFileWatcher } from '../src/core/file-watcher....   │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `cycles`
+
+```bash
+npx -y codebase-context cycles --scope src
+```
+
+Example output:
+
+```text
+┌─ Circular Dependencies ──────────────────────────────────────────────┐
+│                                                                      │
+│ No cycles found  ·  98 files  ·  260 edges  ·  2.7 avg deps          │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `status`
+
+```bash
+npx -y codebase-context status
+```
+
+Example output:
+
+```text
+┌─ Index Status ───────────────────────────────────────────────────────┐
+│                                                                      │
+│ State: ready                                                         │
+│ Root:  /path/to/repo                                                 │
+│                                                                      │
+│ → Run `reindex` to re-index (`--incremental` skips unchanged).       │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## `reindex`
+
+```bash
+npx -y codebase-context reindex
+npx -y codebase-context reindex --incremental --reason "changed watcher logic"
+```
+
+> **MCP server mode**: if you're running codebase-context as an MCP server (long-running process), the index auto-refreshes via a file watcher — you don't need to call `reindex` between edits. Use `reindex` for one-shot CLI runs or to force a full rebuild.
+
+## `style-guide`
+
+```bash
+npx -y codebase-context style-guide --query "naming"
+```
+
+Example output:
+
+```text
+No style guides found.
+  Hint: Try broader terms like 'naming', 'patterns', 'testing', 'components'
+```
+
+## `memory`
+
+```bash
+npx -y codebase-context memory list
+npx -y codebase-context memory list --query "watcher"
+
+npx -y codebase-context memory add \
+  --type gotcha \
+  --category tooling \
+  --memory "Use pnpm, not npm" \
+  --reason "Workspace support and speed"
+
+npx -y codebase-context memory remove <id>
+```

package/package.json

@@ -1,158 +1,154 @@
-{
-  "name": "codebase-context",
-  "version": "1.6.2",
-  "description": "Second brain for AI agents working on your codebase - team coding patterns detection, persistent memory, preflight checks, and hybrid search with evidence scoring. Local-first MCP server",
-  "type": "module",
-  "main": "./dist/lib.js",
-  "types": "./dist/lib.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/lib.js",
-      "types": "./dist/lib.d.ts"
-    },
-    "./server": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./analyzers/angular": {
-      "import": "./dist/analyzers/angular/index.js",
-      "types": "./dist/analyzers/angular/index.d.ts"
-    },
-    "./analyzers/generic": {
-      "import": "./dist/analyzers/generic/index.js",
-      "types": "./dist/analyzers/generic/index.d.ts"
-    },
-    "./embeddings": {
-      "import": "./dist/embeddings/index.js",
-      "types": "./dist/embeddings/index.d.ts"
-    },
-    "./storage": {
-      "import": "./dist/storage/index.js",
-      "types": "./dist/storage/index.d.ts"
-    }
-  },
-  "bin": {
-    "codebase-context": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "docs"
-  ],
-  "packageManager": "pnpm@10.27.0",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
-    "codebase-context",
-    "code-intelligence",
-    "code-patterns",
-    "team-conventions",
-    "pattern-detection",
-    "semantic-search",
-    "vector-search",
-    "hybrid-search",
-    "retrieval",
-    "reranking",
-    "rrf",
-    "cross-encoder",
-    "context-engineering",
-    "local-first",
-    "privacy-first",
-    "embeddings",
-    "preflight",
-    "evidence-scoring",
-    "golden-files",
-    "ai-coding",
-    "ai-agents",
-    "llm",
-    "claude",
-    "claude-code",
-    "cursor",
-    "copilot",
-    "windsurf",
-    "angular",
-    "react",
-    "typescript",
-    "developer-tools",
-    "static-analysis",
-    "code-quality",
-    "team-memory",
-    "second-brain",
-    "code-search",
-    "codebase-intelligence"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/PatrickSys/codebase-context.git"
-  },
-  "bugs": {
-    "url": "https://github.com/PatrickSys/codebase-context/issues"
-  },
-  "homepage": "https://github.com/PatrickSys/codebase-context#readme",
-  "author": {
-    "name": "Patrick Rosselló",
-    "email": "rossellocolompatrick@gmail.com",
-    "url": "https://github.com/PatrickSys"
-  },
-  "license": "MIT",
-  "scripts": {
-    "preinstall": "npx only-allow pnpm",
-    "build": "tsc",
-    "prepublishOnly": "pnpm run build",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "watch": "tsc -w",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint \"src/**/*.ts\"",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\"",
-    "type-check": "tsc --noEmit",
-    "mcp:inspect": "npx -y @modelcontextprotocol/inspector node dist/index.js ."
-  },
-  "dependencies": {
-    "@huggingface/transformers": "^3.8.1",
-    "@lancedb/lancedb": "^0.4.0",
-    "@modelcontextprotocol/sdk": "^1.25.2",
-    "@typescript-eslint/typescript-estree": "^7.0.0",
-    "fuse.js": "^7.0.0",
-    "glob": "^10.3.10",
-    "hono": "4.11.7",
-    "ignore": "^5.3.1",
-    "typescript": "^5.3.3",
-    "uuid": "^9.0.1",
-    "zod": "^4.3.4"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@types/glob": "^8.1.0",
-    "@types/node": "^20.11.24",
-    "@types/uuid": "^9.0.8",
-    "@typescript-eslint/eslint-plugin": "^8.51.0",
-    "@typescript-eslint/parser": "^8.51.0",
-    "eslint": "^9.39.2",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import": "^2.32.0",
-    "globals": "^17.0.0",
-    "prettier": "^3.7.4",
-    "tsx": "^4.21.0",
-    "typescript-eslint": "^8.51.0",
-    "vitest": "^4.0.16"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "onnxruntime-node",
-      "protobufjs",
-      "sharp"
-    ],
-    "overrides": {
-      "@modelcontextprotocol/sdk>ajv": "8.18.0"
-    }
-  }
+{
+  "name": "codebase-context",
+  "version": "1.8.0",
+  "description": "Second brain for AI agents working on your codebase - team coding patterns detection, persistent memory, edit readiness checks, and hybrid search with evidence scoring. Local-first MCP server",
+  "type": "module",
+  "main": "./dist/lib.js",
+  "types": "./dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/lib.js",
+      "types": "./dist/lib.d.ts"
+    },
+    "./server": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./analyzers/angular": {
+      "import": "./dist/analyzers/angular/index.js",
+      "types": "./dist/analyzers/angular/index.d.ts"
+    },
+    "./analyzers/generic": {
+      "import": "./dist/analyzers/generic/index.js",
+      "types": "./dist/analyzers/generic/index.d.ts"
+    },
+    "./embeddings": {
+      "import": "./dist/embeddings/index.js",
+      "types": "./dist/embeddings/index.d.ts"
+    },
+    "./storage": {
+      "import": "./dist/storage/index.js",
+      "types": "./dist/storage/index.d.ts"
+    }
+  },
+  "bin": {
+    "codebase-context": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "grammars",
+    "README.md",
+    "LICENSE",
+    "docs/cli.md",
+    "docs/capabilities.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "codebase-context",
+    "code-intelligence",
+    "code-patterns",
+    "team-conventions",
+    "pattern-detection",
+    "semantic-search",
+    "vector-search",
+    "hybrid-search",
+    "retrieval",
+    "reranking",
+    "rrf",
+    "cross-encoder",
+    "context-engineering",
+    "local-first",
+    "privacy-first",
+    "embeddings",
+    "preflight",
+    "evidence-scoring",
+    "golden-files",
+    "ai-coding",
+    "ai-agents",
+    "llm",
+    "claude",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "windsurf",
+    "angular",
+    "react",
+    "typescript",
+    "developer-tools",
+    "static-analysis",
+    "code-quality",
+    "team-memory",
+    "second-brain",
+    "code-search",
+    "codebase-intelligence"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PatrickSys/codebase-context.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PatrickSys/codebase-context/issues"
+  },
+  "homepage": "https://github.com/PatrickSys/codebase-context#readme",
+  "author": {
+    "name": "Patrick Rosselló",
+    "email": "rossellocolompatrick@gmail.com",
+    "url": "https://github.com/PatrickSys"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@lancedb/lancedb": "^0.4.0",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@typescript-eslint/typescript-estree": "^7.0.0",
+    "chokidar": "^3.6.0",
+    "fuse.js": "^7.0.0",
+    "glob": "^10.3.10",
+    "hono": "^4.12.2",
+    "ignore": "^5.3.1",
+    "typescript": "^5.3.3",
+    "uuid": "^9.0.1",
+    "web-tree-sitter": "^0.25.10",
+    "zod": "^4.3.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/glob": "^8.1.0",
+    "@types/node": "^20.11.24",
+    "@types/uuid": "^9.0.8",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^17.0.0",
+    "prettier": "^3.7.4",
+    "tree-sitter-wasms": "^0.1.13",
+    "tsx": "^4.21.0",
+    "typescript-eslint": "^8.51.0",
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "sync:grammars": "node scripts/sync-grammars.mjs",
+    "prebuild": "pnpm run sync:grammars",
+    "build": "tsc",
+    "pretest": "pnpm run sync:grammars",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "watch": "tsc -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint \"src/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "type-check": "tsc --noEmit",
+    "mcp:inspect": "npx -y @modelcontextprotocol/inspector node dist/index.js .",
+    "eval": "pnpm run build && node scripts/run-eval.mjs"
+  }
 }