[tunahorse]

Summary

Adds a bootstrap-owned provider catalog as the source of truth for real provider identity, CLI tokens, display names, environment variable names, stable ordering, and production construction.

What changed

• Added src/bootstrap/provider_catalog.rs with ordered Brave and Exa catalog entries and production builders.
• Refactored ProviderRegistry to build configured providers and stable order from the catalog.
• Refactored CLI provider parsing to use catalog-backed ProviderId values while keeping all as a CLI-only aggregate mode.
• Added architecture and integration tests covering catalog ownership, metadata, CLI parsing, unknown-provider errors, and provider order.
• Updated README, mdBook architecture/quickstart docs, harness docs, and provider-catalog evidence/memory artifacts.

Validation

• Captured failing-first catalog architecture regression before implementation.
• cargo test --test architecture_test
• cargo test --test provider_registry_integration
• cargo test --test cli_integration
• cargo test cli::args
• python3 scripts/check_markdown_frontmatter.py
• mdbook build
• cargo run -- --help
• just check passed locally and in the pre-push hook.

Notes

No live Brave or Exa API calls were run; live provider calls remain outside automated evidence. The existing generated scripts/__pycache__/ and the pre-existing staged architecture-exploration artifacts were left out of this PR.

Summary by CodeRabbit

• Refactor

  • Centralized provider identity, CLI token resolution, and environment variable configuration into a unified provider catalog system for improved consistency and maintainability.

• Documentation

  • Updated project documentation to clarify provider selection semantics, environment variable wiring, and the CLI-only nature of the --provider all mode.
  • Improved guidance on supported providers and their configuration requirements.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces a provider catalog as the single source of truth for provider identity, CLI tokens, display names, environment variables, and production construction. The new src/bootstrap/provider_catalog.rs module is imported by the provider registry, CLI argument parser, and CLI runner, replacing scattered hardcoded definitions. Architecture tests enforce catalog ownership, and comprehensive documentation updates clarify the new responsibilities.

Changes

Provider Catalog Refactoring

Layer / File(s)	Summary
Provider Catalog Core Definition src/bootstrap/mod.rs, src/bootstrap/provider_catalog.rs	ProviderId enum and ProviderCatalogEntry struct define provider metadata (CLI tokens, display names, env var names). Static PROVIDER_CATALOG array registers Brave and Exa with production builders. Public accessors support token lookup, default provider selection, and environment variable hint generation.
Provider Registry Refactoring src/bootstrap/provider_registry.rs, tests/integration/provider_registry_test.rs	ProviderId and ProviderBuilder are re-exported from catalog via pub use. production_from_env() iterates the catalog instead of hardcoding provider parsing. available_providers() derives order from catalog. Error display uses provider_env_var_hint(). New test asserts catalog stability and correct metadata across all entries.
CLI Provider Parsing Refactoring src/cli/args.rs, tests/integration/cli_test.rs	New CliProvider type uses Single(ProviderId) or All. Custom value parser validates tokens against catalog-derived list, mapping them back to ProviderId via find_provider_by_cli_token(). Defaults to catalog default provider. Tests verify parsing correctness, unknown token rejection, and error messages listing valid tokens.
CLI Runner Integration src/cli/runner.rs	Provider dispatch changes to handle CliProvider::Single(provider_id) by routing through run_single_provider(). About text dynamically formats supported provider display names from provider_catalog::provider_display_names() instead of hardcoding the provider string.
Architecture & Contract Tests tests/architecture_test.rs	New test test_provider_catalog_is_provider_wiring_source_of_truth verifies catalog module exists, is exported, and enforces that provider registry, CLI args, and runner do not contain hardcoded provider wiring. Helper function implementation_region() filters code to non-test sections for focused pattern checking.
User-Facing Documentation README.md, docs/architecture.md, docs/intro.md, docs/project/ARCHITECTURE.md, docs/quickstart.md, docs/dependency-architecture-map.*, CHANGELOG.md, HARNESS.md	Provider selection flow clarified to show catalog-backed token→ProviderId resolution, conditional inclusion by API keys, --provider all as a CLI-only aggregate mode, and catalog order for stable provider ordering. Changelog documents new bootstrap provider catalog entry. Architecture docs redirect provider registration guidance to src/bootstrap/provider_catalog.rs.
Session Tracking Artifacts docs/artifacts/active/CHARTER-*.md, docs/artifacts/active/EXEC-*.md, docs/artifacts/decisions/ADR-0001-*.md, docs/artifacts/evidence/EVID-*.md, docs/artifacts/explorations/EXP-*.md, docs/artifacts/memory/MEM-*.md	Session charter defines scope and regression checks. Execution log records implementation timeline and bugs fixed. ADR-0001 documents the architecture decision. Evidence pack proves catalog ownership and test coverage. Exploration and memory documents capture research context and implementation decisions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• alchemiststudiosDOTai/sophon#7: Earlier refactor of provider wiring in src/bootstrap/provider_registry.rs where this PR further centralizes those definitions into a new catalog module.
• alchemiststudiosDOTai/sophon#12: Adds integration tests for CLI and ProviderRegistry behavior; this PR extends those test patterns to verify catalog-driven provider selection and ordering.

Poem

🐰 A rabbit hops through scattered code with care,
Gathers provider facts from here and there,
One catalog true, all sources agree,
Brave and Exa now dwell in harmony.
No more duplication, one source to see! 🎯

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.92% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '[codex] Add provider catalog' clearly and concisely describes the main change—introducing a provider catalog as a source of truth for provider identity and configuration.
Description check	✅ Passed	The description includes all required template sections: summary, what changed, validation (with specific test commands and checks), and relevant context notes, demonstrating comprehensive coverage.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/provider-catalog

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}