diff --git a/README.md b/README.md index 989864d..76da440 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Local repository maps, code search and symbol references for coding agents. Code ## Published beta: 2.3.1-beta.0 (stable: 2.2.0) -As checked on **4 November 2026**, npm `beta` points to **`2.3.1-beta.0`**, while npm `latest` remains **`2.2.0`**. The beta requires **Node.js 22 or newer**. An unpinned `npx -y codebase-context` may use an already installed local version; without one, it resolves npm `latest` (currently the stable `2.2.0`). To select the published beta explicitly, use `npx -y codebase-context@2.3.1-beta.0 --version`. A source checkout or a local tarball is separate from a verified registry release. +As checked on **6 November 2026**, npm `beta` points to **`2.3.1-beta.0`**, while npm `latest` remains **`2.2.0`**. The beta requires **Node.js 22 or newer**. An unpinned `npx -y codebase-context` may use an already installed local version; without one, it resolves npm `latest` (currently the stable `2.2.0`). To select the published beta explicitly, use `npx -y codebase-context@2.3.1-beta.0 --version`. A source checkout or a local tarball is separate from a verified registry release. **Fresh beta indexes use keyword search without downloading an embedding or reranker model.** Existing indexes keep their recorded mode. Semantic indexing is an explicit option; its optional runtimes and model downloads are separate from the default path. @@ -39,6 +39,12 @@ node /path/to/codebase-context/dist/index.js init --client codex --root /path/to The wizard recognizes Claude Code, Codex, Cursor and OpenCode. It saves the Node binary and package entrypoint that ran setup. If that installation or its npx cache is moved or removed, rerun setup. Writing a config does not prove that a native client connected or completed a coding task. +For manual Codex registration, the CLI help selects the published beta explicitly: + +```bash +codex mcp add codebase-context -- npx -y codebase-context@2.3.1-beta.0 +``` + After registration, restart the client and ask: > 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. diff --git a/src/cli-formatters.ts b/src/cli-formatters.ts index 678d4ae..eb1619b 100644 --- a/src/cli-formatters.ts +++ b/src/cli-formatters.ts @@ -287,7 +287,13 @@ export function formatSearch( intent?: string ): void { const g = getGlyphs(); - const { searchQuality: quality, preflight, results, relatedMemories: memories } = data; + const { + searchQuality: quality, + sourceCoverage, + preflight, + results, + relatedMemories: memories + } = data; const boxLines: string[] = []; @@ -303,6 +309,18 @@ export function formatSearch( } } + if (sourceCoverage && sourceCoverage.status !== 'current') { + boxLines.push( + `Source coverage: ${sourceCoverage.status}; checked ${sourceCoverage.checkedFiles} files, skipped ${sourceCoverage.skippedFiles}.` + ); + if (sourceCoverage.candidateBudgetExhausted) { + boxLines.push('Search stopped early (candidate budget exhausted); narrow the query.'); + } + if (sourceCoverage.refreshAction) { + boxLines.push(`Next: ${sourceCoverage.refreshAction}`); + } + } + if (preflight && showPreflight) { const readyLabel = preflight.ready ? 'YES' : 'NO'; boxLines.push(`Ready to edit: ${readyLabel}`); diff --git a/src/cli-init.ts b/src/cli-init.ts index 4641e84..7e7fef6 100644 --- a/src/cli-init.ts +++ b/src/cli-init.ts @@ -19,6 +19,9 @@ import { checkbox } from '@inquirer/prompts'; import { homedir } from 'node:os'; import { constants } from 'node:fs'; +export const CODEX_BETA_SETUP_COMMAND = + 'codex mcp add codebase-context -- npx -y codebase-context@2.3.1-beta.0'; + export type Client = (typeof CLIENTS)[number]['id']; export type McpConfigResult = { kind: 'file'; path: string; content: string }; @@ -507,7 +510,7 @@ function printInitUsage(): void { console.log( 'Each config saves this Node binary and the package file from the npx cache, plus the project folder.' ); - console.log('Codex setup line: codex mcp add codebase-context -- npx -y codebase-context'); + console.log(`Codex beta setup line: ${CODEX_BETA_SETUP_COMMAND}`); console.log( ' --client Choose a tool (repeatable): ' + CLIENTS.map((client) => client.id).join(', ') diff --git a/src/cli.ts b/src/cli.ts index 2121e73..0a6a489 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -22,7 +22,7 @@ import { GenericAnalyzer } from './analyzers/generic/index.js'; import { formatJson } from './cli-formatters.js'; import { handleMemoryCli } from './cli-memory.js'; export { handleMemoryCli } from './cli-memory.js'; -import { handleInitCli } from './cli-init.js'; +import { CODEX_BETA_SETUP_COMMAND, handleInitCli } from './cli-init.js'; import { handleMapCli } from './cli-map.js'; import { loadProjectConfig } from './server/config.js'; import { cliProjectOptions } from './cli-project-options.js'; @@ -91,8 +91,8 @@ function printUsage(): void { console.log(' --version Print the package version'); console.log(' --help Show this help'); console.log(''); - console.log('Codex setup line:'); - console.log(' codex mcp add codebase-context -- npx -y codebase-context'); + console.log('Codex beta setup line:'); + console.log(` ${CODEX_BETA_SETUP_COMMAND}`); console.log(''); console.log('Environment:'); console.log(' CODEBASE_ROOT Project root path (default: cwd for CLI only)'); diff --git a/tests/cli-init.test.ts b/tests/cli-init.test.ts index bfff804..be4d4a4 100644 --- a/tests/cli-init.test.ts +++ b/tests/cli-init.test.ts @@ -657,7 +657,7 @@ describe('handleInitCli', () => { try { await handleInitCli(['--help']); expect(log.mock.calls.flat().join('\n')).toContain( - 'codex mcp add codebase-context -- npx -y codebase-context' + 'codex mcp add codebase-context -- npx -y codebase-context@2.3.1-beta.0' ); } finally { log.mockRestore(); diff --git a/tests/cli.test.ts b/tests/cli.test.ts index 2debe67..1f27930 100644 --- a/tests/cli.test.ts +++ b/tests/cli.test.ts @@ -108,6 +108,128 @@ describe('CLI', () => { expect(toolMocks.dispatchTool).not.toHaveBeenCalled(); }); + it('help gives the same pinned beta setup command as the README', async () => { + await handleCliCommand(['--help']); + + const command = 'codex mcp add codebase-context -- npx -y codebase-context@2.3.1-beta.0'; + const output = logSpy.mock.calls.map((call) => String(call[0] ?? '')).join('\n'); + expect(output).toContain(command); + expect(await fs.readFile(new URL('../README.md', import.meta.url), 'utf8')).toContain(command); + expect(cliContextMocks.loadProjectConfig).not.toHaveBeenCalled(); + expect(toolMocks.dispatchTool).not.toHaveBeenCalled(); + }); + + it.each([ + { results: [] }, + { results: [{ file: 'src/example.ts:1-3', summary: 'Example', score: 0.2 }] } + ])('discloses exhausted search coverage with $results.length results', async ({ results }) => { + toolMocks.dispatchTool.mockResolvedValue({ + content: [ + { + type: 'text', + text: JSON.stringify({ + status: 'success', + searchQuality: { status: 'low_confidence', confidence: 0.2 }, + sourceCoverage: { + status: results.length ? 'partial' : 'no_fresh_results', + checkedFiles: 30, + skippedFiles: 0, + candidateBudgetExhausted: true + }, + results + }) + } + ] + }); + + await handleCliCommand(['search', '--query', 'example']); + + const output = logSpy.mock.calls + .map((call) => String(call[0] ?? '')) + .join('\n') + .replace(/[│|]/g, '') + .replace(/\s+/g, ' '); + expect(output).toContain('checked 30 files'); + expect(output).toContain('Search stopped early'); + expect(output).toContain('candidate budget exhausted'); + expect(output).toContain('narrow the query'); + }); + + it('reports skipped search sources without claiming the candidate budget was exhausted', async () => { + toolMocks.dispatchTool.mockResolvedValue({ + content: [ + { + type: 'text', + text: JSON.stringify({ + status: 'success', + searchQuality: { status: 'low_confidence', confidence: 0 }, + sourceCoverage: { + status: 'partial', + checkedFiles: 2, + skippedFiles: 1, + refreshAction: 'Refresh changed sources, then retry.' + }, + results: [] + }) + } + ] + }); + + await handleCliCommand(['search', '--query', 'example']); + + const output = logSpy.mock.calls + .map((call) => String(call[0] ?? '')) + .join('\n') + .replace(/[│|]/g, '') + .replace(/\s+/g, ' '); + expect(output).toContain('checked 2 files, skipped 1'); + expect(output).toContain('Refresh changed sources, then retry.'); + expect(output).not.toContain('Search stopped early'); + }); + + it('does not claim an early stop for current search coverage', async () => { + toolMocks.dispatchTool.mockResolvedValue({ + content: [ + { + type: 'text', + text: JSON.stringify({ + status: 'success', + searchQuality: { status: 'low_confidence', confidence: 0.2 }, + sourceCoverage: { status: 'current', checkedFiles: 2, skippedFiles: 0 }, + results: [] + }) + } + ] + }); + + await handleCliCommand(['search', '--query', 'example']); + + const output = logSpy.mock.calls.map((call) => String(call[0] ?? '')).join('\n'); + expect(output).not.toContain('Search stopped early'); + expect(output).toContain('low confidence'); + }); + + it('preserves the raw search coverage response with --json', async () => { + const payload = { + status: 'success', + searchQuality: { status: 'low_confidence', confidence: 0.2 }, + sourceCoverage: { + status: 'partial', + checkedFiles: 30, + skippedFiles: 0, + candidateBudgetExhausted: true + }, + results: [] + }; + toolMocks.dispatchTool.mockResolvedValue({ + content: [{ type: 'text', text: JSON.stringify(payload) }] + }); + + await handleCliCommand(['search', '--query', 'example', '--json']); + + expect(JSON.parse(String(logSpy.mock.calls.at(-1)?.[0]))).toEqual(payload); + }); + it('search dispatches with typed args', async () => { toolMocks.dispatchTool.mockResolvedValue({ content: [{ type: 'text', text: JSON.stringify({ ok: true }) }]