feat(phase-6): add codebase-context init wizard

[PatrickSys]

Summary

Implements Phase 6 of the v2.0.0 milestone: an interactive first-run setup wizard (codebase-context init) for new users.

What ships

• src/cli-init.ts: new wizard module (209 lines, 5 exports): interactive client selector, MCP config generator, instruction block scaffolding with delimiter-based dedup, preview-first UX before any file writes
• tests/cli-init.test.ts: 12 unit tests covering all four clients, instruction block invariants, path resolution, and file-write scenarios (all pass)
• src/cli.ts + src/index.ts: init subcommand wired; existing npx codebase-context path flow untouched
• package.json: @inquirer/prompts ^3.0.0 added to dependencies (resolved to 3.3.2)

Supported clients (first wave)

Claude Code, Cursor, Codex, OpenCode - as scoped in the Phase 6 requirements.

Behavior contract

• Preview-first: full MCP config and instruction block shown before any confirm prompt
• Nothing written without explicit user confirmation (default: false)
• Delimiter-based dedup: re-running init on an existing instructions file does not double-append
• Cursor and OpenCode write JSON config files; Claude Code and Codex exec their CLI config command
• npx codebase-context path (HTTP/MCP startup) is unaffected

Verification

Phase 6 verified in .planning/phases/06-bootstrap-first-run-adoption/06-VERIFICATION.md - 10/10 must-haves, 12/12 tests pass. One standing human-verification item (interactive TTY smoke test) non-blocking.

[greptile-apps]

Greptile Summary

This PR implements Phase 6 of the v2.0.0 milestone: an interactive codebase-context init wizard (src/cli-init.ts) that configures MCP settings and scaffolds instruction blocks for Claude Code, Cursor, Codex, and OpenCode. The core logic is clean — preview-first UX, delimiter-based deduplication for instruction blocks, good unit test coverage (12 tests). The subcommand is wired correctly through src/cli.ts.

• Dead import in src/index.ts (line 41): handleInitCli is imported but never called directly. The init subcommand already routes via handleCliCommand → src/cli.ts; the direct import is dead code and violates the project's AGENTS.md rule that CLI code must not appear in src/index.ts.
• Silent config overwrite (src/cli-init.ts, lines 163–168): For cursor and opencode, the wizard writes the MCP JSON config file without checking whether it already exists. An existing .cursor/mcp.json with other MCP server entries will be silently replaced with a single-entry file — a real data-loss risk for users who already have Cursor configured.
• Instruction-block deduplication is correct and idempotent.
• @inquirer/prompts ^3.0.0 is an appropriate new dependency.

Confidence Score: 4/5

Mostly safe to merge — core wizard logic is correct, but the MCP JSON overwrite issue is a real data-loss risk for users with existing Cursor/OpenCode configs that should be fixed.

One P1 finding (silent overwrite of existing MCP config files, which can destroy users' existing MCP server entries) keeps this at 4/5. The P2 unused-import issue is minor. All other logic is sound and well-tested.

src/cli-init.ts (MCP file-write logic, lines 163–168) and src/index.ts (dead handleInitCli import, line 41)

Important Files Changed

Filename	Overview
src/cli-init.ts	New 208-line wizard module; correct deduplication and preview-first UX, but MCP JSON configs for cursor/opencode silently overwrite existing files without merge.
src/cli.ts	Minor additions: handleInitCli import, 'init' added to CLI commands array, usage line, and dispatch branch. Clean and correct.
src/index.ts	Adds unused handleInitCli import (dead code, violates AGENTS.md) and 'init' to CLI_SUBCOMMANDS — the import should be removed.
tests/cli-init.test.ts	12 vitest tests covering all 4 clients, instruction block invariants, path resolution, and file-write scenarios; correct and thorough.
package.json	@inquirer/prompts ^3.0.0 added to dependencies; appropriate addition for interactive CLI prompts.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as codebase-context init
    participant FS as File System
    participant Shell as execFileSync

    User->>CLI: codebase-context init
    CLI->>User: Which client? (select)
    User->>CLI: claude-code | cursor | codex | opencode
    CLI->>User: Preview MCP config
    CLI->>User: Apply MCP config? [y/N]
    alt kind === file (cursor / opencode)
        CLI->>FS: mkdir -p dir
        CLI->>FS: writeFile — OVERWRITES existing!
    else kind === command (claude-code / codex)
        CLI->>Shell: execFileSync('mcp', [...])
    end
    alt instructionPath !== null
        CLI->>FS: access(instructionPath)
        CLI->>User: Preview instruction block
        CLI->>User: Write instruction block? [y/N]
        CLI->>FS: readFile(instructionPath)
        alt delimiter already present
            CLI->>User: Skipped (idempotent)
        else not present
            CLI->>FS: writeFile (append block)
        end
    end
    CLI->>User: Next steps message

Loading

_{Reviews (1): Last reviewed commit: "feat(phase-6): add codebase-context init..." | Re-trigger Greptile}