From 2cf45c952b0c5cc0b745ff9d20b5f2379d97ace5 Mon Sep 17 00:00:00 2001 From: PatrickSys Date: Sat, 7 Nov 2026 00:45:31 +0100 Subject: [PATCH 1/2] fix(cli): disclose incomplete search coverage Agent: codex-cli jobOR2 --- src/cli-formatters.ts | 20 +++++++- tests/cli.test.ts | 111 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 1 deletion(-) diff --git a/src/cli-formatters.ts b/src/cli-formatters.ts index 678d4aed..eb1619b0 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/tests/cli.test.ts b/tests/cli.test.ts index 2debe679..ba7ddcf8 100644 --- a/tests/cli.test.ts +++ b/tests/cli.test.ts @@ -108,6 +108,117 @@ describe('CLI', () => { 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 }) }] From 7a3f4c644c7606ded363c4e5e52f8a2eaf9af5de Mon Sep 17 00:00:00 2001 From: PatrickSys Date: Sat, 7 Nov 2026 00:45:33 +0100 Subject: [PATCH 2/2] fix(cli): pin Codex setup help to the published beta Agent: codex-cli jobOR2 --- README.md | 8 +++++++- src/cli-init.ts | 5 ++++- src/cli.ts | 6 +++--- tests/cli-init.test.ts | 2 +- tests/cli.test.ts | 11 +++++++++++ 5 files changed, 26 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 989864da..76da4401 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-init.ts b/src/cli-init.ts index 4641e841..7e7fef6e 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 2121e737..0a6a4895 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 bfff8046..be4d4a43 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 ba7ddcf8..1f27930f 100644 --- a/tests/cli.test.ts +++ b/tests/cli.test.ts @@ -108,6 +108,17 @@ 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 }] }