diff --git a/.github/workflows/publish-npm-on-release.yml b/.github/workflows/publish-npm-on-release.yml index 4ca7cf4..68755f1 100644 --- a/.github/workflows/publish-npm-on-release.yml +++ b/.github/workflows/publish-npm-on-release.yml @@ -8,9 +8,9 @@ on: workflow_dispatch: inputs: tag: - description: 'Tag to publish (e.g. v2.3.0)' + description: 'Release tag to publish' required: true - default: 'v2.3.0' + type: string permissions: contents: read diff --git a/README.md b/README.md index 6249c02..a6ee760 100644 --- a/README.md +++ b/README.md @@ -2,39 +2,47 @@ [![npm version](https://img.shields.io/npm/v/codebase-context)](https://www.npmjs.com/package/codebase-context) [![license](https://img.shields.io/npm/l/codebase-context)](./LICENSE) [![node](https://img.shields.io/node/v/codebase-context)](https://github.com/PatrickSys/codebase-context/blob/master/package.json) -## Your coding agent doesn't understand your codebase. - -Coding agents can read files, but they still have to discover how your repository is organized, which patterns your team follows, and which examples are worth copying. - -Codebase Context gives an agent a local view of that information through code search, team patterns, strong examples, and project memory. It runs as an MCP server - a local tool that your editor or command-line agent can call while it works - and keeps the index on your machine by default. +Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns. Search, examples and project memory run locally by default. ## Set up your AI client -Choose your coding tool and run its command once. Use Node.js 22 or newer. These commands use published npm `2.2.0` and do not require a project folder in your configuration: +**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md). + +Use Node.js 22 or newer. Choose your coding tool and run its command once; the examples target the 2.4.0 release: ```bash # Claude Code -claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.2.0 +claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0 # Codex CLI -codex mcp add codebase-context -- npx -y codebase-context@2.2.0 +codex mcp add codebase-context -- npx -y codebase-context@2.4.0 # OpenCode 1.x (keep the quoted separator on Windows) -opencode mcp add codebase-context '--' npx -y codebase-context@2.2.0 +opencode mcp add codebase-context '--' npx -y codebase-context@2.4.0 ``` Start a new agent session in your project, then ask: -> Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files. +> Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project, wait for indexing if needed, and open the relevant source files. + +Replace `[feature]` with something you want to find. The first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. + +### New in 2.4.0 -Replace `[feature]` with something you want to find. The agent supplies the repository path in its tool calls, so the registration can serve different projects. Initial indexing may need a local model download. The October 6 isolated checks proved these client registrations and published-package project selection/search; they did not establish a full native agent investigation. +- Opt-in NestJS support from community contributor Aaron Olin. See the [analyzer options](./docs/capabilities.md#analyzers). +- Better React/Next.js detection and a fix for reranker passage scoring. +- Transformers.js v4 for local models. + +Known limits: [Intel Mac indexing crash (#68)](https://github.com/PatrickSys/codebase-context/issues/68), [custom OpenAI endpoints (#70)](https://github.com/PatrickSys/codebase-context/issues/70) and [Ollama (#71)](https://github.com/PatrickSys/codebase-context/issues/71) remain open. + +The existing [benchmark](https://github.com/PatrickSys/codebase-context/blob/master/docs/benchmark.md) reports 25.7% expected-file recovery versus jCodeMunch's 27.1% in a fixed retrieval comparison; it does not establish a winner or coding quality. For Codex Desktop, create or merge `.codex/config.toml` in the project you want to search: ```toml [mcp_servers.codebase-context] command = "npx" -args = ["-y", "codebase-context@2.2.0"] +args = ["-y", "codebase-context@2.4.0"] startup_timeout_sec = 120 ``` @@ -44,13 +52,13 @@ Other clients use their own setup commands: | Client | Shortest current setup | | --------------------------- | ---------------------------------------------------------------------------- | -| Gemini CLI | `gemini mcp add --scope user codebase-context npx -y codebase-context@2.2.0` | +| Gemini CLI | `gemini mcp add --scope user codebase-context npx -y codebase-context@2.4.0` | | Cursor | Add `.cursor/mcp.json` | | VS Code with GitHub Copilot | Add `.vscode/mcp.json` | -| GitHub Copilot CLI | `copilot mcp add codebase-context -- npx -y codebase-context@2.2.0` | +| GitHub Copilot CLI | `copilot mcp add codebase-context -- npx -y codebase-context@2.4.0` | | Windsurf | Add `~/.codeium/windsurf/mcp_config.json` | -Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the `npx` arguments. The [client setup guide](./docs/client-setup.md) covers scopes, optional fixed-folder configuration, verification limits and the unreleased installer. Published `2.2.0`'s interactive `init` has registration bugs; use the commands above. +Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the `npx` arguments. The [client setup guide](./docs/client-setup.md) covers scopes, optional fixed-folder configuration and the interactive setup wizard's limitations. The [client setup guide](./docs/client-setup.md) has the exact commands and config for every client, plus what was checked locally and what still relies on official instructions. @@ -64,32 +72,36 @@ The default connection is `stdio` (standard input/output): your client starts th ### Team patterns and examples -`get_team_patterns` shows the approaches used in the repository and points to representative files. Published `2.2.0` includes dedicated analyzers for Angular, React and Next.js, with a generic analyzer for other stacks. NestJS support belongs to the newer source candidate. +`get_team_patterns` shows the approaches used in the repository and points to representative files. Version `2.4.0` includes dedicated analyzers for Angular, React, Next.js and opt-in NestJS, with a generic analyzer for other stacks. ### Project memory `remember` stores a convention, decision, gotcha, or past failure for the project. `get_memory` retrieves relevant entries in later sessions, including when the agent or editor changes. +### Review context + +The `codebase-context-review` CLI creates a bounded context packet from a committed Git diff. It gives a reviewer context; it does not review code or prove review quality. See the [review-context guide](./docs/review-context.md). + ## How it works 1. **Index locally.** Codebase Context scans the project, builds a keyword index, and creates local semantic embeddings - numeric representations used to match code by meaning as well as exact words. 2. **Understand the repository.** The agent can request a compact codebase map with structure, patterns, and representative files. 3. **Find the code for the task.** Search returns ranked files and symbols; the agent reads the selected files before editing. -The same information is available from the terminal. Run these commands from your project root. The first index can take a while because it scans the project and creates local embeddings; once it is ready, inspect the map and search for the code you need: +The same information is available from the terminal. Run these commands from your project root. The first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. Once it is ready, inspect the map and search for the code you need: ```bash # Build or refresh the local index -npx -y codebase-context@2.2.0 reindex +npx -y codebase-context@2.4.0 reindex # Repository structure, patterns, and representative files -npx -y codebase-context@2.2.0 map +npx -y codebase-context@2.4.0 map # Ranked code search -npx -y codebase-context@2.2.0 search --query "auth middleware" +npx -y codebase-context@2.4.0 search --query "auth middleware" # Current team patterns -npx -y codebase-context@2.2.0 patterns +npx -y codebase-context@2.4.0 patterns ``` One stdio server can route across several repositories. Supply `project` in tool calls to select the intended repository; a successful selection becomes the default for later calls in that process. Some clients also announce workspace roots: one root can auto-select, while an ambiguous selection asks for a project instead of guessing. MCP deprecated Roots in its July 2026 revision, so explicit project selection is the documented default rather than a dependency on client discovery. @@ -145,8 +157,8 @@ The method and failures are documented so the measurements can be inspected with - Retrieval measurements describe expected-file coverage, file precision, and reported `peakPrivateGb`, not patch correctness or end-to-end coding quality. - The paired token observation covers two frozen investigation tasks and records observed agent behavior; it is not a universal token or time guarantee. - Setup checks differ by client. The detailed guide distinguishes a written config, a config recognized by the client, a local connection, and instructions checked only against official docs. -- Published `2.2.0` has dedicated Angular, React and Next.js analyzers; NestJS support is in the newer source candidate. Other projects use the generic analyzer and the language parsers available for that stack. -- The default searchable-chunk limit is 5,000 per project. Larger repositories can raise it in `.codebase-context/config.json`. +- Version `2.4.0` has dedicated Angular, React, Next.js and opt-in NestJS analyzers. Other projects use the generic analyzer and the language parsers available for that stack. +- The default searchable-chunk limit is 5,000 per project. In `~/.codebase-context/config.json`, set `projects[].parsing.maxChunks` for a project that needs a higher limit. - The agent must identify its repository in tool calls when no default or unambiguous client root is available. Concurrent HTTP client isolation is not established by the stdio routing checks. ## Reference diff --git a/docs/capabilities.md b/docs/capabilities.md index 748d5a1..59806d6 100644 --- a/docs/capabilities.md +++ b/docs/capabilities.md @@ -1,6 +1,8 @@ # Capabilities Reference -Technical reference for what `codebase-context` ships today. The public product posture is map first, find second: the bounded conventions map is the first-call surface, and search narrows to the right local example after that. For the user-facing overview, see [README.md](../README.md). +Technical reference for the 2.4.0 setup preview. The public product posture is map first, find second: the bounded conventions map is the first-call surface, and search narrows to the right local example after that. For the user-facing overview, see [README.md](../README.md). + +**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md). ## Transport Modes @@ -8,8 +10,8 @@ The server supports two transport modes: | Mode | Command | MCP endpoint | | ------------------- | ------------------------------------------------- | ---------------------------- | -| **stdio** (default) | `npx -y codebase-context@2.2.0` | Spawned process stdin/stdout | -| **HTTP** | `npx -y codebase-context@2.2.0 --http [--port N]` | `http://127.0.0.1:3100/mcp` | +| **stdio** (default) | `npx -y codebase-context@2.4.0` | Spawned process stdin/stdout | +| **HTTP** | `npx -y codebase-context@2.4.0 --http [--port N]` | `http://127.0.0.1:3100/mcp` | HTTP defaults to `127.0.0.1:3100`. Override with `--port`, `CODEBASE_CONTEXT_PORT`, or `server.port` in `~/.codebase-context/config.json`. @@ -20,13 +22,14 @@ Per-project config overrides supported today: - `projects[].excludePatterns`: merged with the built-in exclusion set for that project at index time - `projects[].analyzerHints.analyzer`: prefers a registered analyzer by name for that project and falls back safely when the name is missing or invalid - `projects[].analyzerHints.extensions`: adds project-local source extensions for indexing and auto-refresh watching without changing defaults for other projects +- `projects[].parsing.maxChunks`: sets the maximum number of searchable chunks indexed for that project Copy-pasteable client config templates are shipped in the package: - `templates/mcp/stdio/.mcp.json` — stdio setup for `.mcp.json`-style clients - `templates/mcp/http/.mcp.json` — HTTP setup for `.mcp.json`-style clients -Use Node.js 22 or newer with the published 2.2.0 commands shown here. For client registration recipes and their verification limits, see the [client setup guide](./client-setup.md). +Use Node.js 22 or newer with the 2.4.0 commands shown here. For 2.4.0 setup preview recipes and their verification limits, see the [client setup guide](./client-setup.md). ## CLI Reference @@ -49,15 +52,15 @@ For a command gallery with examples, see `docs/cli.md`. | `memory add` | `--type`, `--category`, `--memory`, `--reason` | `remember` | | `memory remove ` | — | — | -Commands that list `--json` above support raw JSON output. For MCP client registration, follow the [published client setup recipes](./client-setup.md); do not use the broken `init` setup command in published 2.2.0. Errors go to stderr with exit code 1. +Commands that list `--json` above support raw JSON output. For MCP client registration, follow the [2.4.0 setup preview recipes](./client-setup.md). The existing `init` wizard is interactive and generates HTTP setup; see that guide for its current limitations. Errors go to stderr with exit code 1. ```bash # Quick examples -npx -y codebase-context@2.2.0 status -npx -y codebase-context@2.2.0 search --query "auth middleware" --intent edit -npx -y codebase-context@2.2.0 refs --symbol "UserService" --limit 10 -npx -y codebase-context@2.2.0 cycles --scope src/features -npx -y codebase-context@2.2.0 reindex --incremental +npx -y codebase-context@2.4.0 status +npx -y codebase-context@2.4.0 search --query "auth middleware" --intent edit +npx -y codebase-context@2.4.0 refs --symbol "UserService" --limit 10 +npx -y codebase-context@2.4.0 cycles --scope src/features +npx -y codebase-context@2.4.0 reindex --incremental ``` ## Tool Surface @@ -273,6 +276,7 @@ Impact is 2-hop transitive: direct importers (hop 1) and their importers (hop 2) - **Angular**: signals, standalone components, control flow syntax, lifecycle hooks, DI patterns, component metadata - **React**: function/class components, custom hooks, context usage, memoization, Suspense, ecosystem signal extraction - **Next.js**: App Router and Pages Router detection, route/API classification, route paths, `"use client"`, metadata exports +- **NestJS (opt-in)**: modules, controllers, providers and route handlers, contributed by Aaron Olin. The library indexer accepts `config: { analyzers: { nestjs: { enabled: true } } }`; the CLI/server project configuration does not currently expose analyzer enablement. - **Generic**: 30+ have indexing/retrieval coverage including PHP, Ruby, Swift, Scala, Shell, config/markup., 10 languages have full symbol extraction (Tree-sitter: TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust). Notes: @@ -301,6 +305,6 @@ Reproducible evaluation is shipped as a CLI entrypoint backed by shared scoring - **Symbol refs are not a call-graph.** `get_symbol_references` counts identifier-node occurrences in the AST (comments/strings excluded via Tree-sitter). It does not distinguish call sites from type annotations, variable assignments, or imports. Full call-site-specific analysis (`call_expression` nodes only) is a roadmap item. - **Impact is 2-hop max.** `computeImpactCandidates` walks direct importers then their importers. Full BFS reachability is on the roadmap. -- **Published 2.2.0 has dedicated Angular, React, and Next.js analyzers.** NestJS support is in a newer source candidate and is not part of published 2.2.0. Other languages use the Generic analyzer (30+ languages, chunking + import graph, no framework-specific signal extraction). +- **The 2.4.0 preview source has dedicated Angular, React, Next.js and NestJS analyzers.** Other languages use the Generic analyzer (30+ languages, chunking + import graph, no framework-specific signal extraction). - **Default embedding model is `bge-small-en-v1.5` (512-token context).** Granite (8192 context) is opt-in via `EMBEDDING_MODEL`. OpenAI is opt-in via `EMBEDDING_PROVIDER=openai` — sends code externally. - **Patterns are file-level frequency counts.** Not semantic clustering. Rising/Declining trend is derived from git commit recency for files using each pattern, not from usage semantics. diff --git a/docs/cli.md b/docs/cli.md index dfda760..88d5b96 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -10,18 +10,20 @@ > Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary). > -> These examples show an earlier CLI run; they do not verify the current package or an MCP connection. +> **These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md). > -> The commands below use published `codebase-context@2.2.0` and require Node.js 22 or newer. The CLI is intentionally single-project per invocation and targets one root via `CODEBASE_ROOT` or the current working directory. MCP registration and project selection are covered in the [client setup guide](./client-setup.md). +> These output examples come from an earlier CLI run; they were not captured from `2.4.0` and do not verify an MCP connection. +> +> The commands below use `codebase-context@2.4.0` and require Node.js 22 or newer. The CLI is intentionally single-project per invocation and targets one root via `CODEBASE_ROOT` or the current working directory. MCP registration and project selection are covered in the [client setup guide](./client-setup.md). ## How to run ```bash # CLI only: run from a repo root, or set CODEBASE_ROOT explicitly: -CODEBASE_ROOT=/path/to/repo npx -y codebase-context@2.2.0 status +CODEBASE_ROOT=/path/to/repo npx -y codebase-context@2.4.0 status # Commands that show --json in their help support machine output. Human mode is default. -npx -y codebase-context@2.2.0 patterns --json +npx -y codebase-context@2.4.0 patterns --json ``` ### ASCII fallback @@ -29,7 +31,7 @@ npx -y codebase-context@2.2.0 patterns --json If your terminal doesn’t render Unicode box-drawing cleanly: ```bash -CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.2.0 patterns +CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.4.0 patterns ``` ## Commands @@ -44,18 +46,18 @@ CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.2.0 patterns - `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`) -- MCP client registration — use the published 2.2.0 commands in the [client setup guide](./client-setup.md); published `init` is not a reliable setup route +- MCP client registration — use the 2.4.0 recipes in the [client setup guide](./client-setup.md); `init` is an interactive HTTP setup wizard with the limitations described there --- ## First use -Run these CLI commands from the project root. Build or refresh the local index first; the first index may take a while while the project is scanned and local embeddings are created. Then inspect the conventions map and search for the code you need: +Run these CLI commands from the project root. Build or refresh the local index first; the first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. Then inspect the conventions map and search for the code you need: ```bash -npx -y codebase-context@2.2.0 reindex -npx -y codebase-context@2.2.0 map -npx -y codebase-context@2.2.0 search --query "auth middleware" +npx -y codebase-context@2.4.0 reindex +npx -y codebase-context@2.4.0 map +npx -y codebase-context@2.4.0 search --query "auth middleware" ``` This is the CLI preparation flow. It is separate from MCP client registration and does not by itself show that an MCP client connected successfully. @@ -63,8 +65,8 @@ This is the CLI preparation flow. It is separate from MCP client registration an ## `map` ```bash -npx -y codebase-context@2.2.0 reindex -npx -y codebase-context@2.2.0 map +npx -y codebase-context@2.4.0 reindex +npx -y codebase-context@2.4.0 map ``` The conventions map - run this first on an unfamiliar repo. It shows architecture layers, active patterns with adoption rates and trend direction, and the golden files the team treats as the strongest examples. This is also what the MCP server delivers to AI agents via the `codebase://context` resource on first call, before search narrows to a specific local example. @@ -99,7 +101,7 @@ Example output (truncated): ## `metadata` ```bash -npx -y codebase-context@2.2.0 metadata +npx -y codebase-context@2.4.0 metadata ``` Example output: @@ -120,7 +122,7 @@ Example output: ## `patterns` ```bash -npx -y codebase-context@2.2.0 patterns +npx -y codebase-context@2.4.0 patterns ``` Example output (truncated): @@ -142,8 +144,8 @@ Example output (truncated): ## `search` ```bash -npx -y codebase-context@2.2.0 reindex -npx -y codebase-context@2.2.0 search --query "file watcher" --intent edit --limit 3 +npx -y codebase-context@2.4.0 reindex +npx -y codebase-context@2.4.0 search --query "file watcher" --intent edit --limit 3 ``` Example output (truncated): @@ -164,7 +166,7 @@ Example output (truncated): ## `refs` ```bash -npx -y codebase-context@2.2.0 refs --symbol "startFileWatcher" --limit 10 +npx -y codebase-context@2.4.0 refs --symbol "startFileWatcher" --limit 10 ``` Example output (truncated): @@ -183,7 +185,7 @@ Example output (truncated): ## `cycles` ```bash -npx -y codebase-context@2.2.0 cycles --scope src +npx -y codebase-context@2.4.0 cycles --scope src ``` Example output: @@ -199,7 +201,7 @@ Example output: ## `status` ```bash -npx -y codebase-context@2.2.0 status +npx -y codebase-context@2.4.0 status ``` Example output: @@ -218,8 +220,8 @@ Example output: ## `reindex` ```bash -npx -y codebase-context@2.2.0 reindex -npx -y codebase-context@2.2.0 reindex --incremental --reason "changed watcher logic" +npx -y codebase-context@2.4.0 reindex +npx -y codebase-context@2.4.0 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. @@ -227,7 +229,7 @@ npx -y codebase-context@2.2.0 reindex --incremental --reason "changed watcher lo ## `style-guide` ```bash -npx -y codebase-context@2.2.0 style-guide --query "naming" +npx -y codebase-context@2.4.0 style-guide --query "naming" ``` Example output: @@ -240,14 +242,14 @@ No style guides found. ## `memory` ```bash -npx -y codebase-context@2.2.0 memory list -npx -y codebase-context@2.2.0 memory list --query "watcher" +npx -y codebase-context@2.4.0 memory list +npx -y codebase-context@2.4.0 memory list --query "watcher" -npx -y codebase-context@2.2.0 memory add \ +npx -y codebase-context@2.4.0 memory add \ --type gotcha \ --category tooling \ --memory "Use pnpm, not npm" \ --reason "Workspace support and speed" -npx -y codebase-context@2.2.0 memory remove +npx -y codebase-context@2.4.0 memory remove ``` diff --git a/docs/client-setup.md b/docs/client-setup.md index 7770e7f..3d47d49 100644 --- a/docs/client-setup.md +++ b/docs/client-setup.md @@ -1,12 +1,14 @@ # Client Setup -Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These examples use published npm `2.2.0`. +**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md). -Use Node.js 22 or newer for these recipes. The package declares Node 18+, but native dependency requirements are narrower than that broad declaration; these checks do not establish Node 18.0 compatibility. +Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These recipes target the 2.4.0 release. + +Use Node.js 22 or newer for these recipes. The package still declares Node 18+, but the built pack failed to index source on Node 18.20.4 with `ReferenceError: crypto is not defined` in UUID chunk creation. Node 22 is the lowest version used successfully in the package check; the engine declaration remains an open compatibility issue. The copyable registration commands target PowerShell or a POSIX terminal. Windows Command Prompt was not tested; OpenCode's quoted separator is shell-dependent. -## Current published-package recipes (updated 2026-10-06) +## Client recipes for 2.4.0 Claude Code, Codex CLI and OpenCode registration commands were checked again on October 6 without a project argument. The other clients retain their older config-shape evidence; no-folder native agent use is unverified for them. See the dated notes below. @@ -25,7 +27,7 @@ After registration, start a new agent session in your project and ask: > Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files. -The first index may take a while and download a local model. You can prepare it separately with `npx -y codebase-context@2.2.0 reindex` from the project folder. Index readiness, client connection and useful agent behavior are separate checks. +The first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. You can prepare it separately with `npx -y codebase-context@2.4.0 reindex` from the project folder. Index readiness, client connection and useful agent behavior are separate checks. ## Claude Code @@ -38,13 +40,13 @@ The first index may take a while and download a local model. You can prepare it User setup: ```bash -claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.2.0 +claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0 ``` Optional shared project setup: ```bash -claude mcp add --scope project --transport stdio codebase-context -- npx -y codebase-context@2.2.0 +claude mcp add --scope project --transport stdio codebase-context -- npx -y codebase-context@2.4.0 ``` `--scope project` writes shared `.mcp.json` and requires project-server approval. `--scope local` instead stores a private association for the current project in `~/.claude.json`; it does not write `.mcp.json`. @@ -64,7 +66,7 @@ claude mcp add --scope project --transport stdio codebase-context -- npx -y code **Scope:** The command writes user config. A trusted project can use a project `.codex/config.toml` instead. ```bash -codex mcp add codebase-context -- npx -y codebase-context@2.2.0 +codex mcp add codebase-context -- npx -y codebase-context@2.4.0 ``` Equivalent project config: @@ -72,7 +74,7 @@ Equivalent project config: ```toml [mcp_servers.codebase-context] command = "npx" -args = ["-y", "codebase-context@2.2.0"] +args = ["-y", "codebase-context@2.4.0"] startup_timeout_sec = 120 ``` @@ -82,58 +84,40 @@ startup_timeout_sec = 120 **Official docs:** [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). The supported `startup_timeout_sec` option defaults to ten seconds; the project example allows 120 seconds for initial `npx` package preparation. This does not prove Desktop startup or guarantee completion of a cold download. -## Codex Desktop: published 2.2.0 +## Codex Desktop: 2.4.0 recipe Create or merge `.codex/config.toml` in the project you want to search. Preserve any existing settings: ```toml [mcp_servers.codebase-context] command = "npx" -args = ["-y", "codebase-context@2.2.0"] +args = ["-y", "codebase-context@2.4.0"] startup_timeout_sec = 120 ``` Trust the project if asked, restart Codex and start a new task there. Use the first-use prompt above so the agent selects the current repository. The CLI command in the preceding section writes user-level config; this recipe uses a trusted project's config instead. -**Verification boundary:** isolated Windows CLI and SDK/MCP checks on October 5 indexed a six-file fixture with published `2.2.0`, selected its project, retrieved context and found a source that the host could open. The exact `npx -y codebase-context@2.2.0 ` entrypoint also passed using a warmed isolated npm cache and prepared index. This does not establish a fully cold download or a fresh Codex Desktop agent session. The September Desktop session below used a packed candidate; keep it separate from published-package acceptance. - -On October 6 the exact published `npx` entrypoint was also tested without a folder, environment root or MCP roots, launched from an unrelated directory. Its first tool call returned `selection_required`; an explicit `project` call selected the prepared fixture, search found the expected symbol, context returned its map, and the runner host opened the returned source. A later call without `project` retained that selection. This is SDK/protocol and runner-host evidence with warmed caches and a pre-indexed fixture, not a native Desktop task. - -## Unreleased installer candidate - -The next release is expected to support one project-only command from the target project: - -The `init --client codex --yes` flow is an unreleased source candidate. Published npm `2.2.0` does not include these flags. Use the published configuration above rather than an `@latest` installer command; candidate verification uses an exact built or installed candidate. +**Verification boundary:** isolated Windows CLI and SDK/MCP checks on October 5 exercised published `2.2.0` on a six-file fixture; the exact `npx -y codebase-context@2.2.0 ` entrypoint passed with a warmed isolated npm cache and prepared index. This is historical evidence for `2.2.0`, not verification of `2.4.0`, a fully cold download or a fresh Codex Desktop agent session. -A successful `init --client codex --yes` writes the project-scoped `.codex/config.toml` and prepares the index for that root. If config writing or index preparation fails, setup is incomplete and Codex is not ready to use. - -For candidate verification before publication, build the source checkout and run its absolute `dist/index.js` path from the project you want to configure: - -```powershell -# In the codebase-context source checkout -npm run build - -# In the target project, using the built CLI path -node C:\path\to\codebase-context\dist\index.js init --client codex --yes -``` +On October 6 the exact published `2.2.0` `npx` entrypoint was tested without a folder, environment root or MCP roots, launched from an unrelated directory. That check does not verify the `2.4.0` package. Its first tool call returned `selection_required`; an explicit `project` call selected the prepared fixture, search found the expected symbol, context returned its map, and the runner host opened the returned source. A later call without `project` retained that selection. This is SDK/protocol and runner-host evidence with warmed caches and a pre-indexed fixture, not a native Desktop task. -Use `--root C:\path\to\project` when the command is run from elsewhere. Here, `root` means the project folder to configure and index. The candidate writes the project-scoped `/.codex/config.toml`, preserves unrelated Codex settings, prepares the index for that folder, and does not write `AGENTS.md` or global client configuration. After a successful result, trust the project in Codex Desktop if prompted, restart or reopen Codex, start a new task in that project, and ask a small project question. A written config and ready index do not prove that Codex loaded or queried the server. +## Interactive setup wizard -Before release, the generated `npx` server command still resolves the published package unless the candidate is installed in the target project's `node_modules`. Our packaged test installs the candidate in a disposable project and checks its file hash. Running the built setup command alone does not prove that Codex will launch that same candidate. +Run `npx -y codebase-context@2.4.0 init` from the target project to open the existing interactive wizard. It asks you to choose Claude Code, Cursor, Codex or OpenCode, previews HTTP configuration and asks before applying it. It separately offers to write an instruction block to `CLAUDE.md`, `.cursorrules` or `AGENTS.md` where applicable. -**Checked on 2026-09-15:** the packed candidate installed and indexed an isolated Windows project. A fresh Codex Desktop task then called the actual `search_codebase` MCP tool and located the requested chart component with its source file and lines. The normal Desktop task flow established project trust; no trust-file edits or replacement CLI/SDK search were used for that answer. This covers the small prepared project with shared caches, not a cold-machine install or the published npm package. +The wizard does not accept non-interactive client/root flags or prepare an index. Its HTTP configurations need a separately started server. In the current source, Claude/Codex registration attempts to execute `mcp` directly and can report failure while the wizard still exits successfully. Use the direct stdio commands or configuration above for those clients; the wizard is not a verified one-step setup. ## Optional fixed-folder setup and CLI preparation -To set a default project before the first tool call, append its full path to the server arguments, for example `args = ["-y", "codebase-context@2.2.0", "C:/projects/my-app"]`. Use a quoted literal shell argument in registration commands. This makes the default fixed across repositories when the registration is user-scoped; explicit tool selection can still choose another allowed project. +To set a default project before the first tool call, append its full path to the server arguments, for example `args = ["-y", "codebase-context@2.4.0", "C:/projects/my-app"]`. Use a quoted literal shell argument in registration commands. This makes the default fixed across repositories when the registration is user-scoped; explicit tool selection can still choose another allowed project. To prepare the index separately, run from the project folder: ```powershell -npx -y codebase-context@2.2.0 reindex +npx -y codebase-context@2.4.0 reindex ``` -Do not use published `2.2.0`'s interactive `init` as the setup route. October 6 isolated checks found that it ignores `--help`, `--client` and `--yes`; its Claude/Codex registration executes `mcp` instead of the client executable, and its HTTP recipes require a separately started server. It can exit zero after registration fails. The unreleased installer above is a separate implementation. +The interactive wizard limitations described above are still present in the 2.4.0 source. A successful wizard exit alone does not establish working client registration. ## Gemini CLI @@ -146,13 +130,13 @@ Do not use published `2.2.0`'s interactive `init` as the setup route. October 6 User setup: ```bash -gemini mcp add --scope user codebase-context npx -y codebase-context@2.2.0 +gemini mcp add --scope user codebase-context npx -y codebase-context@2.4.0 ``` Project setup: ```bash -gemini mcp add --scope project codebase-context npx -y codebase-context@2.2.0 +gemini mcp add --scope project codebase-context npx -y codebase-context@2.4.0 ``` Gemini writes an `mcpServers` entry in its settings. Claude, Codex, and Copilot CLI use `--`; Gemini does not. @@ -178,7 +162,7 @@ Create `.cursor/mcp.json`: "mcpServers": { "codebase-context": { "command": "npx", - "args": ["-y", "codebase-context@2.2.0"] + "args": ["-y", "codebase-context@2.4.0"] } } } @@ -203,7 +187,7 @@ Checked config shape: `.cursor/mcp.json with mcpServers.codebase-context command Official user command: ```powershell -code --add-mcp '{"name":"codebase-context","command":"npx","args":["-y","codebase-context@2.2.0"]}' +code --add-mcp '{"name":"codebase-context","command":"npx","args":["-y","codebase-context@2.4.0"]}' ``` Deterministic workspace config at `.vscode/mcp.json`: @@ -213,7 +197,7 @@ Deterministic workspace config at `.vscode/mcp.json`: "servers": { "codebase-context": { "command": "npx", - "args": ["-y", "codebase-context@2.2.0"] + "args": ["-y", "codebase-context@2.4.0"] } } } @@ -234,7 +218,7 @@ Deterministic workspace config at `.vscode/mcp.json`: **Scope:** User config. ```bash -copilot mcp add codebase-context -- npx -y codebase-context@2.2.0 +copilot mcp add codebase-context -- npx -y codebase-context@2.4.0 ``` **What was checked:** The command ran with an isolated `--config-dir` and wrote the expected `mcp-config.json` command, arguments, and tool filter. @@ -254,7 +238,7 @@ copilot mcp add codebase-context -- npx -y codebase-context@2.2.0 Run once: ```bash -opencode mcp add codebase-context '--' npx -y codebase-context@2.2.0 +opencode mcp add codebase-context '--' npx -y codebase-context@2.4.0 ``` Keep the quoted `'--'`: the installed Windows PowerShell npm shim consumes an unquoted separator. The quoted form also works in POSIX shells. @@ -267,7 +251,7 @@ For a project-local alternative, merge this into `opencode.json`: "mcp": { "codebase-context": { "type": "local", - "command": ["npx", "-y", "codebase-context@2.2.0"], + "command": ["npx", "-y", "codebase-context@2.4.0"], "enabled": true, "timeout": 120000 } @@ -277,7 +261,7 @@ For a project-local alternative, merge this into `opencode.json`: Checked config shape: `opencode.json with a local command array and timeout 120000`. -The longer timeout is intentional because the isolated cold start took about 38 seconds while `npx` prepared the package and server. +The longer timeout allows for initial `npx` package preparation and server startup; that time varies with the machine, network and cache. **What was checked:** With home, config, data, cache, temporary and workspace paths redirected, the no-folder command wrote user configuration and `opencode mcp list` reported Connected. An August 11 check with OpenCode 1.18.5 also connected using the project config shape and an explicit folder; the no-folder project variant is not a new native acceptance check. @@ -300,7 +284,7 @@ Create `~/.codeium/windsurf/mcp_config.json`: "mcpServers": { "codebase-context": { "command": "npx", - "args": ["-y", "codebase-context@2.2.0"] + "args": ["-y", "codebase-context@2.4.0"] } } } @@ -319,8 +303,8 @@ Checked config shape: `~/.codeium/windsurf/mcp_config.json with mcpServers.codeb Use `stdio` for the simplest setup. HTTP can let several clients share one long-running local process, but support depends on the client and this path is not part of the default setup proof: ```bash -npx -y codebase-context@2.2.0 --http -npx -y codebase-context@2.2.0 --http --port 4000 +npx -y codebase-context@2.4.0 --http +npx -y codebase-context@2.4.0 --http --port 4000 ``` The documented default endpoint is `http://127.0.0.1:3100/mcp`. Config-shape templates are available in [`templates/mcp/stdio/.mcp.json`](../templates/mcp/stdio/.mcp.json) and [`templates/mcp/http/.mcp.json`](../templates/mcp/http/.mcp.json); pin the published package as in the recipes above. HTTP does not discover a client's project folder; the agent still has to select its repository. @@ -339,7 +323,7 @@ Some clients also announce workspace roots. One valid root can auto-select; seve [MCP deprecated Roots on July 28, 2026](https://modelcontextprotocol.io/specification/2026-07-28/client/roots), recommending explicit directories/files in tool parameters, resource URIs or server configuration. CBC's older Roots support remains a compatibility aid rather than a required setup step. -October 6 verification: 18 focused current-source routing tests passed, including ambiguous roots, explicit selection, subsequent calls and root changes. The exact published server also switched between two isolated prepared repositories A to B to A in one no-roots stdio process: search paths, context map and subsequent status calls followed each selection. The runner host opened the expected distinct sources. A native agent session across real repositories remains a validation step; stdio process-local selection does not establish concurrent HTTP isolation. +October 6 verification: 18 focused current-source routing tests passed, including ambiguous roots, explicit selection, subsequent calls and root changes. The exact published `2.2.0` server also switched between two isolated prepared repositories A to B to A in one no-roots stdio process; search paths, context map and subsequent status calls followed each selection, and the runner host opened the expected distinct sources. This historical package check does not verify `2.4.0` or establish concurrent HTTP isolation. A native agent session across real repositories remains a validation step; stdio process-local selection does not establish concurrent HTTP isolation. A follow-up recorded raw `search_codebase` calls containing only `query` and `mode`, with no `project`: they returned A, B and A after those explicit selections. The caller does not automatically add the full path; CBC routes omitted-project calls using its selected project. This state lasts for that stdio process. Select again after a server restart or when changing repositories. diff --git a/docs/demo.md b/docs/demo.md index 8b06f23..81d0021 100644 --- a/docs/demo.md +++ b/docs/demo.md @@ -2,14 +2,16 @@ This walkthrough shows real CLI output captured from the open-source `angular-spotify` repository during a local proof run. That sample checkout is not bundled here. -To try the same CLI flow, use Node.js 22 or newer and open a terminal in the repository you want to inspect. These commands use published `codebase-context@2.2.0`; the CLI uses the current directory as the project root. MCP registration and project selection are covered in the [client setup guide](./client-setup.md). +**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md). -The saved output below is from an earlier CLI run, not the published-package commands shown here. The machine-specific repository root is omitted from the returned file path. This capture does not verify the current package or an MCP connection. +To try the same CLI flow, use Node.js 22 or newer and open a terminal in the repository you want to inspect. These commands target `codebase-context@2.4.0`; the CLI uses the current directory as the project root. MCP registration and project selection are covered in the [client setup guide](./client-setup.md). + +The saved output below is from an earlier CLI run, not from `2.4.0` or the commands shown here. The machine-specific repository root is omitted from the returned file path. This capture does not verify the current package or an MCP connection. ## 0. Build The Local Index ```bash -npx -y codebase-context@2.2.0 reindex +npx -y codebase-context@2.4.0 reindex ``` Run this before the first map or search in a repository. Later runs can use `reindex --incremental` after the code changes. @@ -17,7 +19,7 @@ Run this before the first map or search in a repository. Later runs can use `rei ## 1. Start With The Conventions Map ```bash -npx -y codebase-context@2.2.0 map --json +npx -y codebase-context@2.4.0 map --json ``` Captured output excerpt: @@ -50,7 +52,7 @@ What this shows: ## 2. Search With Edit Intent ```bash -npx -y codebase-context@2.2.0 search --query "auth headers" --intent edit --limit 3 --json +npx -y codebase-context@2.4.0 search --query "auth headers" --intent edit --limit 3 --json ``` Captured output excerpt: @@ -91,7 +93,7 @@ What this shows: ## 3. Check A Team Pattern Directly ```bash -npx -y codebase-context@2.2.0 patterns --category state --json +npx -y codebase-context@2.4.0 patterns --category state --json ``` Captured output excerpt: diff --git a/docs/review-context.md b/docs/review-context.md index e35df6a..f21b3d6 100644 --- a/docs/review-context.md +++ b/docs/review-context.md @@ -4,6 +4,8 @@ It is deliberately **not** an AI reviewer. It does not call an LLM, decide whether code is correct, or post comments. Its job is narrower and testable: compile the changed surface, stable diff signals, related codebase context, and current conventions into a versioned input for a reviewer or evaluation harness. +**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md). + ## Why this exists A PR reviewer needs more than the patch, but dumping an entire repository into a model is expensive and hard to reproduce. The review-context path creates a clean boundary between: @@ -26,13 +28,13 @@ node dist/review-bin.js --base origin/main --head HEAD After package publication, the package also exposes: ```bash -npx codebase-context-review --base origin/main --head HEAD +npm exec --yes --package=codebase-context@2.4.0 -- codebase-context-review --base origin/main --head HEAD ``` Use `--json` for the complete machine-readable packet: ```bash -npx codebase-context-review \ +npm exec --yes --package=codebase-context@2.4.0 -- codebase-context-review \ --base origin/main \ --head HEAD \ --max-queries 8 \ diff --git a/tests/release-truth-surfaces.test.ts b/tests/release-truth-surfaces.test.ts index f362ba4..49d56d4 100644 --- a/tests/release-truth-surfaces.test.ts +++ b/tests/release-truth-surfaces.test.ts @@ -114,8 +114,65 @@ describe('release truth surfaces', () => { expect(visualsDoc).toContain('Historical snapshot'); }); - it('keeps the manual publish fallback aligned to the package version', () => { - expect(workflow).toContain(`description: 'Tag to publish (e.g. v${expectedVersion})'`); - expect(workflow).toContain(`default: 'v${expectedVersion}'`); + it('requires an explicit release tag for the manual publish fallback', () => { + const manualTagInput = workflow.match(/^ {6}tag:\r?\n((?: {8}[^\r\n]*\r?\n)+)/m)?.[1] ?? ''; + + expect(manualTagInput).toMatch(/^\s*required:\s*true\s*$/m); + expect(manualTagInput).toMatch(/^\s*type:\s*string\s*$/m); + expect(manualTagInput).not.toMatch(/^\s*default:/m); + expect(workflow).toMatch(/^ release:\r?\n {4}types: \[published\]/m); + expect(workflow).toContain( + 'ref: ${{ github.event.inputs.tag || github.event.release.tag_name }}' + ); + }); + + it('keeps 2.4.0 setup guidance accurate before and after publication', () => { + const versionNotice = 'These commands use 2.4.0.'; + const fallbackNotice = 'If that version is not available on npm yet, use the published 2.2.0'; + const currentVersionGuide = + 'https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md'; + const setupPages = [ + [ + 'README.md', + 'claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0' + ], + [ + 'docs/client-setup.md', + 'claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0' + ], + ['docs/capabilities.md', '| **stdio** (default) |'], + ['docs/cli.md', 'CODEBASE_ROOT=/path/to/repo npx -y codebase-context@2.4.0 status'], + ['docs/demo.md', 'npx -y codebase-context@2.4.0 reindex'], + ['docs/review-context.md', 'pnpm build'] + ] as const; + + for (const [path, firstCommand] of setupPages) { + const page = readText(path); + const noticeIndex = page.indexOf(versionNotice); + const guideIndex = page.indexOf(currentVersionGuide); + const commandIndex = page.indexOf(firstCommand); + + expect( + noticeIndex, + `${path} should explain the current-version fallback` + ).toBeGreaterThanOrEqual(0); + expect(guideIndex, `${path} should link the published 2.2.0 setup`).toBeGreaterThan( + noticeIndex + ); + expect(page.slice(noticeIndex, guideIndex)).toContain(fallbackNotice); + expect(page.slice(noticeIndex, guideIndex)).toContain('[setup guide]('); + expect(page).not.toContain('**2.4.0 setup preview:**'); + expect(commandIndex, `${path} should retain its first runnable command`).toBeGreaterThan(0); + expect(noticeIndex, `${path} should qualify commands before they appear`).toBeLessThan( + commandIndex + ); + } + }); + + it('does not describe the unpublished 2.4.0 preview as current or published', () => { + const capabilities = readText('docs/capabilities.md'); + + expect(capabilities).not.toContain('what `codebase-context` ships today'); + expect(capabilities).not.toContain('Published 2.4.0 has'); }); });