context7-cli 0.2.3

# Changelog / Registro de Mudanças

All notable changes to `context7-cli` will be documented in this file.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## English

---

## [0.2.3] — 2026-04-09

### Added

- **Library-not-found UX hint**: when `context7 docs <id>` fails with HTTP 404, the CLI now prints a yellow hint suggesting `context7 library <name>` to look up the correct ID — in addition to the existing structured error message.
- **`exibir_dica_biblioteca_nao_encontrada()`** — new public function in `output.rs` that renders the hint using `colored::Colorize`.

### Changed

- **`--help` parameter names in English**: renamed clap identifiers from Portuguese to English for a better experience for non-PT users: `<NOME>` → `<NAME>`, `<CHAVE>` → `<KEY>`, `<INDICE>` → `<INDEX>`, `<ARQUIVO>` → `<FILE>`.
- **Library list format**: `exibir_bibliotecas_formatado` now renders title in bold (primary focus), library ID in dimmed below it, and trust score inline as `(trust X.X/10)` instead of a separate `Trust:` label on its own line.
- **Trust score label**: `"Trust:"` → `"trust"` (lowercase, no colon — displayed inline inside parentheses).
- **README tagline**: updated to reflect the single-binary, zero-runtime nature of the tool more concisely.
- **User agent**: bumped from `context7-cli/0.2.2` to `context7-cli/0.2.3`.

---

## [0.2.2] — 2026-04-09

### Fixed

- **`docs` subcommand UX for missing libraries**: HTTP 404 responses from the Context7 API used to be reported as `No valid API key available after 5 attempts`, misleading users into thinking their keys were invalid. Now surfaces a dedicated `BibliotecaNaoEncontrada` error with a clear message suggesting `context7 library <name>` to look up the correct ID.
- **`executar_com_retry` short-circuits on 404**: the retry loop now aborts immediately when a library is not found (no point trying other keys).
- **Documentation stale references**: removed 19 legacy `trust_score` (snake_case) mentions across `docs/HOW_TO_USE.md`, `docs/context7-skill.md`, and `docs/context7-llm-rules.md` — the API returns `trustScore` (camelCase) since v0.2.1.
- **Documentation stale schema**: removed 6 references to `source_urls` and `content` (legacy snippet fields) in `docs/context7-skill.md` and `docs/context7-llm-rules.md`, replaced with the current schema (`codeId`, `codeTitle`, `codeDescription`, `codeList`, `pageTitle`, `relevance`, `model`).
- **Documentation references to removed command**: removed 6 references to `context7 keys rotate` across the 3 docs files (this command was deleted in v0.2.1 but still appeared in examples).
- **`context7-skill.md` frontmatter**: `version: 0.2.0` → `version: 0.2.2`.

### Added

- **`ErroContext7::BibliotecaNaoEncontrada`** — new structured error variant for HTTP 404 on the docs endpoint.
- **`Mensagem::BibliotecaNaoEncontradaApi`** — new i18n variant with EN + PT translations.
- Wiremock integration tests covering HTTP 404 handling and the `executar_com_retry` short-circuit.

### Changed

- **User agent**: bumped from `context7-cli/0.2.1` to `context7-cli/0.2.2`.

---

## [0.2.1] — 2026-04-09

### Fixed

- **`docs` subcommand schema**: `DocumentationSnippet` struct expected `content`, `type`, `source_urls` but the Context7 API returns `codeTitle`, `codeDescription`, `codeList`, `pageTitle`, `codeId`, `relevance`, `model` (camelCase). Schema now matches the real API response.
- **`--text` flag**: was always failing because the code called `.json()` on the plain-text response body. Now uses `.text().await` directly and prints the raw markdown.
- **`LibrarySearchResult.trust_score`**: was always `null` because the API returns `trustScore` (camelCase) but the struct expected `trust_score` (snake_case). Fixed with `#[serde(rename_all = "camelCase")]`.
- **Retry logic**: was artificially limited to 3 attempts via `3usize.min(chaves.len())`. Now uses up to 5 keys. Also short-circuits when the response is HTTP 200 with a parse error (schema issue, not a key issue).
- **Error messages i18n**: now respect the `--lang`/`CONTEXT7_LANG` setting (previously hardcoded in Portuguese).

### Added

- **`LibrarySearchResult`** now exposes `stars`, `total_snippets`, `total_tokens`, `verified`, `branch`, `state` from the API.
- **`buscar_documentacao_texto`**: new public function in `api.rs` for raw text output.

### Removed

- **`context7 keys rotate`** subcommand — rotation has always been automatic (random shuffle per request); the explicit command was dead code that was only referenced in docs, never implemented.

### Changed

- **User agent**: bumped from `context7-cli/0.2.0` to `context7-cli/0.2.1`.

---

## [0.2.0] — 2026-04-09

### Added

- **Bilingual runtime UI** — English and Brazilian Portuguese output with auto-detect via system locale (`sys-locale` crate). Override at runtime with `--lang en` or `--lang pt`, or permanently with `CONTEXT7_LANG` environment variable.
- **Public library API** — `context7_cli` crate now published on [docs.rs](https://docs.rs/context7-cli). Programmatic usage is now possible by adding `context7-cli` as a dependency. Public API docstrings written in English (Rust ecosystem convention).
- **`[lib]` target in Cargo.toml** — resolves the docs.rs build failure from v0.1.0 (`error: no library targets found in package`, build #3116184). The `src/lib.rs` module now exposes the public API.
- **`[package.metadata.docs.rs]` section** — proper feature documentation generation on docs.rs.
- **`docs/HOW_TO_USE.md`** — complete bilingual step-by-step guide covering Linux, macOS, and Windows (replaces `como_usa.md`).
- **`docs/context7-skill.md`** — LLM skill file for invoking `context7-cli` from AI assistants. Includes YAML frontmatter, usage patterns, output parsing guide, and error handling.
- **`docs/context7-llm-rules.md`** — 7 prescriptive rules and 5 prompt templates for LLM agents using `context7-cli`.
- **`context7 keys rotate`** — new key operation that manually advances the active key pointer to the next available key in the pool.
- **`-q` short flag** — short alias for `--query` in both the `library` and `docs` subcommands.
- **`CONTEXT7_HOME` environment variable** — alternative XDG base directory for config (primarily useful for testing and CI environments).
- **New dependency** — `sys-locale 0.3` for language auto-detect.
- **New dev dependencies** — `assert_cmd 2` and `predicates 3` for CLI integration tests.
- **`rust-version = "1.75"`** declared in Cargo.toml (MSRV).
- **Integration tests** in `tests/` directory using `assert_cmd` and `predicates`.

### Changed

- **Modular architecture** — refactored from monolithic `context7.rs` (3006 lines) to `src/` with 8 files:
  - `src/lib.rs` — public API exports
  - `src/main.rs` — binary entry point
  - `src/cli.rs` — clap argument parsing
  - `src/api.rs` — HTTP client and Context7 API calls
  - `src/storage.rs` — XDG config persistence
  - `src/output.rs` — colored/JSON/text formatting
  - `src/errors.rs` — structured error types with `thiserror`
  - `src/i18n.rs` — bilingual message lookup table
- **Public API docstrings** — now in English to match docs.rs audience expectations (internal comments and user-facing messages remain in Brazilian Portuguese).
- **README.md** — complete rewrite with bilingual structure (English first, then Português). Added "Why use it?" section with 8 benefits, quick install for 3 OS, and links to new docs files.

### Fixed

- **docs.rs build failure** — v0.1.0 build #3116184 failed with `error: no library targets found in package`. Resolved by adding `[lib]` target in Cargo.toml.
- **`como_usa.md` consolidation** — content migrated and improved in `docs/HOW_TO_USE.md` with bilingual structure and 3-OS coverage.

### Preserved

All v0.1.0 CLI behavior is preserved without breaking changes:
- Subcommands: `library`, `docs`, `keys`
- Aliases: `lib`, `search`, `doc`, `context`, `key`
- XDG storage layout (Linux/macOS/Windows)
- Key file permissions (`0o600` on Unix)
- API key hierarchy (env var → XDG → `.env` → compile-time)
- Retry logic (3 attempts, 500ms → 1s → 2s backoff)
- `--json` and `--text` flags
- All v0.1.0 `keys` suboperations: `add`, `list`, `remove`, `clear`, `path`, `import`, `export` (plus new `rotate`, which was later removed in v0.2.1 — rotation is automatic)

---

## [0.1.0] — 2026-04-08

### Added

- Initial release published on [crates.io](https://crates.io/crates/context7-cli) and [GitHub](https://github.com/daniloaguiarbr/context7-cli).
- Native Rust binary `context7` — single file, no runtime dependencies.
- Subcommand `library` (aliases: `lib`, `search`) — search Context7 libraries by name with optional semantic context.
- Subcommand `docs` (aliases: `doc`, `context`) — fetch library documentation by ID with `--query`, `--text`, `--json` flags.
- Subcommand `keys` (alias: `key`) — manage API keys locally via operations `add`, `list`, `remove`, `clear`, `path`, `import`, `export`.
- XDG-compliant config storage (`~/.config/context7/config.toml` on Linux) with `chmod 600` on Unix.
- Multi-key rotation with shuffle without replacement.
- Exponential backoff retry: 3 attempts, 500ms → 1s → 2s.
- Dual logging: stderr with ANSI colors + XDG state file with rotation-by-deletion.
- `--json` global flag for machine-readable output.
- `como_usa.md` — usage guide in Brazilian Portuguese (791 lines).
- License: MIT OR Apache-2.0.

---

## Português

---

## [0.2.3] — 2026-04-09

### Adicionado

- **Dica UX para biblioteca não encontrada**: quando `context7 docs <id>` falha com HTTP 404, a CLI agora exibe uma dica em amarelo sugerindo `context7 library <nome>` para consultar o ID correto — além da mensagem de erro estruturada já existente.
- **`exibir_dica_biblioteca_nao_encontrada()`** — nova função pública em `output.rs` que renderiza a dica usando `colored::Colorize`.

### Alterado

- **Nomes de parâmetros no `--help` em inglês**: renomeados os identificadores clap de português para inglês para melhor experiência de usuários não-PT: `<NOME>` → `<NAME>`, `<CHAVE>` → `<KEY>`, `<INDICE>` → `<INDEX>`, `<ARQUIVO>` → `<FILE>`.
- **Formato da lista de bibliotecas**: `exibir_bibliotecas_formatado` agora renderiza o título em negrito (foco principal), o ID da biblioteca em dimmed abaixo, e o trust score inline como `(confiança X.X/10)` em vez de uma label `Confiança:` separada.
- **Label de trust score**: `"Confiança:"` → `"confiança"` (minúsculo, sem dois-pontos — exibido inline entre parênteses).
- **Tagline do README**: atualizada para refletir de forma mais concisa a natureza single-binary e zero-runtime da ferramenta.
- **User agent**: atualizado de `context7-cli/0.2.2` para `context7-cli/0.2.3`.

---

## [0.2.2] — 2026-04-09

### Corrigido

- **UX do subcomando `docs` para bibliotecas inexistentes**: respostas HTTP 404 da API Context7 eram reportadas como `Nenhuma chave de API válida disponível após 5 tentativas`, fazendo o usuário pensar que as chaves estavam inválidas. Agora expõe um erro dedicado `BibliotecaNaoEncontrada` com mensagem clara sugerindo `context7 library <nome>` para consultar o ID correto.
- **`executar_com_retry` aborta imediatamente em 404**: o loop de retry agora para logo quando uma biblioteca não é encontrada (não adianta tentar outra chave).
- **Referências stale na documentação**: removidas 19 ocorrências legadas de `trust_score` (snake_case) em `docs/HOW_TO_USE.md`, `docs/context7-skill.md` e `docs/context7-llm-rules.md` — a API retorna `trustScore` (camelCase) desde a v0.2.1.
- **Schema stale na documentação**: removidas 6 referências a `source_urls` e `content` (campos legados de snippet) em `docs/context7-skill.md` e `docs/context7-llm-rules.md`, substituídas pelo schema atual (`codeId`, `codeTitle`, `codeDescription`, `codeList`, `pageTitle`, `relevance`, `model`).
- **Referências ao comando removido**: eliminadas 6 menções a `context7 keys rotate` nos 3 arquivos de docs (este comando foi deletado na v0.2.1 mas ainda aparecia nos exemplos).
- **Frontmatter do `context7-skill.md`**: `version: 0.2.0` → `version: 0.2.2`.

### Adicionado

- **`ErroContext7::BibliotecaNaoEncontrada`** — nova variante estruturada para HTTP 404 no endpoint de docs.
- **`Mensagem::BibliotecaNaoEncontradaApi`** — nova variante i18n com traduções EN + PT.
- Testes de integração com wiremock cobrindo o handling de HTTP 404 e o short-circuit no `executar_com_retry`.

### Alterado

- **User agent**: atualizado de `context7-cli/0.2.1` para `context7-cli/0.2.2`.

---

## [0.2.1] — 2026-04-09

### Corrigido

- **Schema do subcomando `docs`**: a struct `DocumentationSnippet` esperava `content`, `type`, `source_urls` mas a API do Context7 retorna `codeTitle`, `codeDescription`, `codeList`, `pageTitle`, `codeId`, `relevance`, `model` (camelCase). Schema agora reflete a resposta real da API.
- **Flag `--text`**: sempre falhava porque o código chamava `.json()` no corpo de texto plano. Agora usa `.text().await` diretamente e imprime o markdown bruto.
- **`LibrarySearchResult.trust_score`**: era sempre `null` porque a API retorna `trustScore` (camelCase) mas o struct esperava `trust_score` (snake_case). Corrigido com `#[serde(rename_all = "camelCase")]`.
- **Lógica de retry**: estava artificialmente limitada a 3 tentativas via `3usize.min(chaves.len())`. Agora usa até 5 chaves. Também aborta imediatamente quando a resposta é HTTP 200 com erro de parse (problema de schema, não de chave).
- **Mensagens de erro i18n**: agora respeitam a configuração `--lang`/`CONTEXT7_LANG` (antes eram hardcoded em português).

### Adicionado

- **`LibrarySearchResult`** agora expõe `stars`, `total_snippets`, `total_tokens`, `verified`, `branch`, `state` da API.
- **`buscar_documentacao_texto`**: nova função pública em `api.rs` para saída de texto bruto.

### Removido

- **Subcomando `context7 keys rotate`** — rotação sempre foi automática (shuffle aleatório por requisição); o comando explícito era código morto que só era referenciado na documentação, nunca implementado.

### Alterado

- **User agent**: atualizado de `context7-cli/0.2.0` para `context7-cli/0.2.1`.

---

## [0.2.0] — 2026-04-09

### Adicionado

- **Interface bilíngue em runtime** — saída em inglês e português brasileiro com auto-detect via locale do sistema (crate `sys-locale`). Override em runtime com `--lang en` ou `--lang pt`, ou permanentemente com a variável de ambiente `CONTEXT7_LANG`.
- **API pública de biblioteca** — o crate `context7_cli` agora está publicado no [docs.rs](https://docs.rs/context7-cli). Uso programático agora é possível adicionando `context7-cli` como dependência. Docstrings da API pública escritas em inglês (convenção do ecossistema Rust).
- **Target `[lib]` no Cargo.toml** — resolve a falha de build no docs.rs da v0.1.0 (`error: no library targets found in package`, build #3116184). O módulo `src/lib.rs` agora expõe a API pública.
- **Seção `[package.metadata.docs.rs]`** — geração correta de documentação de features no docs.rs.
- **`docs/HOW_TO_USE.md`** — guia passo a passo bilíngue completo cobrindo Linux, macOS e Windows (substitui `como_usa.md`).
- **`docs/context7-skill.md`** — arquivo de skill para LLMs invocarem o `context7-cli` a partir de assistentes de IA. Inclui frontmatter YAML, padrões de uso, guia de parsing de output e tratamento de erros.
- **`docs/context7-llm-rules.md`** — 7 regras prescritivas e 5 templates de prompt para agentes LLM usando `context7-cli`.
- **`context7 keys rotate`** — nova operação de chave que avança manualmente o ponteiro da chave ativa para a próxima disponível no pool.
- **Flag curta `-q`** — alias curto para `--query` nos subcomandos `library` e `docs`.
- **Variável de ambiente `CONTEXT7_HOME`** — diretório base XDG alternativo para configuração (principalmente útil para testes e ambientes de CI).
- **Nova dependência** — `sys-locale 0.3` para auto-detect de idioma.
- **Novas dev-dependencies** — `assert_cmd 2` e `predicates 3` para testes de integração da CLI.
- **`rust-version = "1.75"`** declarado no Cargo.toml (MSRV).
- **Testes de integração** no diretório `tests/` usando `assert_cmd` e `predicates`.

### Alterado

- **Arquitetura modular** — refatorado de `context7.rs` monolítico (3006 linhas) para `src/` com 8 arquivos:
  - `src/lib.rs` — exports da API pública
  - `src/main.rs` — ponto de entrada do binário
  - `src/cli.rs` — parsing de argumentos com clap
  - `src/api.rs` — cliente HTTP e chamadas à API Context7
  - `src/storage.rs` — persistência de config XDG
  - `src/output.rs` — formatação colorida/JSON/texto
  - `src/errors.rs` — tipos de erro estruturados com `thiserror`
  - `src/i18n.rs` — tabela de lookup de mensagens bilíngues
- **Docstrings da API pública** — agora em inglês para corresponder às expectativas do público do docs.rs (comentários internos e mensagens para o usuário permanecem em português brasileiro).
- **README.md** — reescrita completa com estrutura bilíngue (inglês primeiro, depois Português). Adicionada seção "Por que usar?" com 8 benefícios, instalação rápida para 3 OS e links para os novos arquivos de docs.

### Corrigido

- **Falha de build no docs.rs** — build #3116184 da v0.1.0 falhou com `error: no library targets found in package`. Resolvido adicionando target `[lib]` no Cargo.toml.
- **Consolidação do `como_usa.md`** — conteúdo migrado e melhorado em `docs/HOW_TO_USE.md` com estrutura bilíngue e cobertura de 3 OS.

### Preservado

Todo comportamento CLI da v0.1.0 está preservado sem breaking changes:
- Subcomandos: `library`, `docs`, `keys`
- Aliases: `lib`, `search`, `doc`, `context`, `key`
- Layout de armazenamento XDG (Linux/macOS/Windows)
- Permissões do arquivo de chaves (`0o600` no Unix)
- Hierarquia de chaves de API (env var → XDG → `.env` → compile-time)
- Lógica de retry (3 tentativas, backoff 500ms → 1s → 2s)
- Flags `--json` e `--text`
- Todas as suboperações de `keys` da v0.1.0: `add`, `list`, `remove`, `clear`, `path`, `import`, `export` (mais a nova `rotate`, que foi posteriormente removida na v0.2.1 — a rotação é automática)

---

## [0.1.0] — 2026-04-08

### Adicionado

- Lançamento inicial publicado no [crates.io](https://crates.io/crates/context7-cli) e [GitHub](https://github.com/daniloaguiarbr/context7-cli).
- Binário Rust nativo `context7` — arquivo único, sem dependências de runtime.
- Subcomando `library` (aliases: `lib`, `search`) — busca bibliotecas Context7 por nome com contexto semântico opcional.
- Subcomando `docs` (aliases: `doc`, `context`) — busca documentação de biblioteca por ID com flags `--query`, `--text`, `--json`.
- Subcomando `keys` (alias: `key`) — gerencia chaves de API localmente via operações `add`, `list`, `remove`, `clear`, `path`, `import`, `export`.
- Armazenamento de config compatível com XDG (`~/.config/context7/config.toml` no Linux) com `chmod 600` no Unix.
- Rotação multi-chave com shuffle sem reposição.
- Retry com backoff exponencial: 3 tentativas, 500ms → 1s → 2s.
- Logging dual: stderr com cores ANSI + arquivo de estado XDG com rotação por deleção.
- Flag global `--json` para saída legível por máquina.
- `como_usa.md` — guia de uso em português brasileiro (791 linhas).
- Licença: MIT OR Apache-2.0.