context7-cli 0.2.7

# 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.7] — 2026-04-09

### Fixed (CI / Build)

- **MSRV CI job**: pinned `assert_cmd = "=2.1.2"` in `[dev-dependencies]` (last version using `edition = "2021"` before the crate migrated to `edition = "2024"` requiring Rust 1.85). Restores MSRV 1.75 compatibility while preserving the canonical decision from Session 09.
- **Coverage gate**: `cargo llvm-cov` now ignores structural dispatcher files (`src/cli.rs`, `src/lib.rs`, `src/main.rs`) via `--ignore-filename-regex`. These files contain async dispatchers and entry points with ~0% coverage by design, and were dragging the 80% total threshold down below 79%. Business-logic files (`src/storage.rs` 95%, `src/errors.rs` 94%, `src/output.rs`, `src/i18n.rs`) continue to be fully validated.
- **Release workflow startup failure**: unified the two Apple codesign steps (adhoc vs Developer ID) into a single step with secrets injected via `env:` and shell-level `if`. The previous `if: ${{ secrets.APPLE_TEAM_ID == '' }}` conditions referenced the `secrets` context in a step-level `if:`, which is **not allowed** by GitHub Actions (see context availability docs). This was causing the release workflow to fail at startup in 0s on every push to `main`.

### Technical

- **Zero runtime changes**: the binary behavior is **identical** to v0.2.6. Users already on v0.2.6 gain nothing by upgrading functionally — this release exists solely to restore a green CI pipeline.
- **Zero runtime dependency changes**: only the `[dev-dependencies]` section was touched (`assert_cmd` pin).
- **190 tests passing, 0 failing** (unchanged from v0.2.6).
- **Zero CVEs**, `cargo deny` PASS on 4 checks (advisories, licenses, bans, sources).
- **All 9 canonical decisions preserved**: rand 0.8, colored 2, thiserror 2, directories 6, rust-version 1.75, 842-byte anti-bot hook, `added_at: String`, `stars: i64 -1`, crate-vs-binary names.

---

## [0.2.6] — 2026-04-09

### Fixed

- **`keys remove` exit code on failure**: `cmd_keys_remove` now returns `Err(ErroContext7::OperacaoKeysFalhou)` (exit code 1) when the index is invalid (0 or out of range) or when the storage is empty. Previously all three error paths returned `Ok(())`, silently reporting success (exit code 0) — a regression spotted in v0.2.4 QA. The user-facing colored message is unchanged; only the process exit code is corrected.
- **"No API key configured" message hardcoded in Portuguese**: `carregar_chaves_api` in `storage.rs` now calls `t(Mensagem::NenhumaChaveConfigurada)` instead of a hardcoded Portuguese string, so the error message correctly respects the `--lang` flag and `CONTEXT7_LANG` environment variable.
- **`keys list` timestamp display**: timestamps were rendered as full RFC3339 strings with 9-digit nanosecond precision (e.g., `2026-04-09T13:34:59.060818734+00:00`). Now formatted as `YYYY-MM-DD HH:MM:SS` (e.g., `2026-04-09 13:34:59`) via the new `formatar_added_at_display` helper in `output.rs`. The on-disk `added_at` format is preserved (canonical RFC3339 — display-only change).

### Security

- **Path traversal regression test** (`LOW-01`): added `testa_context7_home_rejeita_path_traversal` covering `..`, `../../../etc`, and `/tmp/../etc`. Confirms that `resolver_home_override` rejects all `Component::ParentDir` paths and falls back to XDG defaults. The rejection logic was already in place since v0.2.5; this test makes it explicit and prevents regression.

### Technical

- 173 tests passing (up from 172 in v0.2.5).
- Zero breaking changes — all subcommand behavior, storage formats, and public API remain identical.
- `formatar_added_at_display` is a new public function in `output.rs`, testable in isolation.
- Documentation corrected: `CONTEXT7_HOME` creates missing directories automatically on first use (was documented as silent XDG fallback).

---

## [0.2.5] — 2026-04-09

### Fixed

- **CI matrix — MSRV job**: the `cargo check` step now regenerates `Cargo.lock` using the 1.75 toolchain before running checks, fixing a build failure caused by the v4 lockfile format being incompatible with Rust 1.75.
- **Storage tests leaking state on Windows/macOS**: 18 tests in `storage::testes` that resolved `directories::ProjectDirs` to real user paths now use `CONTEXT7_HOME` env-var override for full isolation — no more cross-test contamination on non-Linux CI runners.
- **`commit-check` job used `grep -iE`**: replaced with `rg -qi` / `rg -i` to comply with the project's CLI tools policy (no `grep` allowed).

### Added

- **`CONTEXT7_HOME` environment variable** — set a custom directory for the `context7` config file, overriding the default XDG path. Useful for dotfiles, NixOS configs, Docker containers, and isolated test environments. Precedence: `CONTEXT7_HOME` > `ProjectDirs` default.
- **Alpine musl CI job**: validates that the binary builds correctly on musl libc (via `x86_64-unknown-linux-musl` target).
- **Universal Binary for macOS** (`release.yml`): runs `lipo` to combine `x86_64-apple-darwin` and `aarch64-apple-darwin` slices; applies ad-hoc code signing; optionally uses `notarytool` when credentials are available.
- **Flatpak manifest** at `packaging/flatpak/` for distribution via Flathub.
- **Snap manifest** (`packaging/snap/snapcraft.yaml`) for distribution via the Snap Store.
- **CI jobs**: `cargo-audit` (vulnerability scan), `cargo deny check` (license + advisory), `cargo-llvm-cov` (coverage gate at 80% lines).
- **Prebuilt artifacts** uploaded to each GitHub Release: `tar.gz` for Linux (gnu + musl), `.zip` for Windows, Universal Binary for macOS.

### Changed

- **`dependabot.yml`**: added `ignore` entries for `rand 0.9.x`, `colored 3.x`, `toml 2.x`, `actions/checkout 5.x`/`6.x`, and `dtolnay/rust-toolchain 1.100` — all major-bump versions that would violate MSRV or break canonical API decisions.

### Security

- Closed 4 Dependabot PRs (`#1` dtolnay toolchain bump, `#2` actions/checkout v5, `#3` colored 3.x, `#4` rand 0.9.x) — all major upgrades that would violate MSRV or break the project's canonical dependency decisions.

---

## [0.2.4] — 2026-04-09

### Fixed

- **Windows UTF-8 output**: enabled UTF-8 console mode on Windows via `SetConsoleOutputCP(65001)` at startup so that accented characters and box-drawing symbols render correctly in CMD and PowerShell.
- **Windows ANSI colors**: enabled Virtual Terminal Processing via `SetConsoleMode` so that `colored` escape sequences render as colors instead of raw codes on Windows consoles.
- **`keys clear` confirmation**: the interactive prompt now accepts both `y` and `yes` (case-insensitive), fixing a usability issue where typing `yes` was rejected.
- **`keys remove 0` message**: the 1-based index check now shows a clear error ("index must be ≥ 1") instead of silently failing with a generic message.

### Added

- **CI pipeline** (`ci.yml`): matrix build on `ubuntu-latest`, `windows-latest`, `macos-latest` for Rust stable; runs `cargo check`, `cargo clippy -- -D warnings`, `cargo fmt --check`, and `cargo test`.
- **Release workflow** (`release.yml`): triggered on `v*` tags; publishes to crates.io and creates a GitHub Release.
- **Dependabot** (`dependabot.yml`): weekly Cargo dependency updates.
- **PR template** (`.github/PULL_REQUEST_TEMPLATE.md`): bilingual checklist reminding contributors to use "Squash and merge" for bot PRs.
- **`deny.toml`**: `cargo-deny` configuration for license allow-list and advisory database checks.

### Docs

- **Step 4 output format** (HOW_TO_USE.md): updated all examples to match the v0.2.3 format — library title in bold, ID dimmed on the line below, trust score inline as `(trust X.X/10)`.
- **Retry count** (HOW_TO_USE.md, context7-llm-rules.md): corrected all references from "3 attempts/retries" to "5 attempts" to match the actual `MAX_TENTATIVAS = 5` constant.
- **Step 3 keys list format** (HOW_TO_USE.md): updated the `keys list` example to the current `[N]  ctx7sk-...  (added: ISO-timestamp)` format.
- **Library ID `/reactjs/react.dev`** (all docs): replaced all 60 occurrences of the stale `/facebook/react` ID across `HOW_TO_USE.md`, `README.md`, `context7-skill.md`, and `context7-llm-rules.md`.
- **Anchor fix** (HOW_TO_USE.md): corrected a broken link pointing to a renamed heading.
- **LLM rules link** (HOW_TO_USE.md): the "LLM rules" reference now links to `docs/context7-llm-rules.md` (was linking to a stale `docs/llm-rules.md` path).
- **Stale v0.2.0 troubleshooting note** (HOW_TO_USE.md §8): replaced with an instruction to upgrade via `cargo install context7-cli --force`.
- **TOC** (HOW_TO_USE.md): added a bilingual Table of Contents with anchor links to each major section.
- **`context7-skill.md` version bump**: `0.2.3` → `0.2.4`.
- **Cargo.toml description**: improved to reflect the bilingual and multi-key nature of the tool.

### Changed

- **User agent**: bumped from `context7-cli/0.2.3` to `context7-cli/0.2.4`.

### Dependencies

- Bump `reqwest` from 0.12.8 to 0.12.9
- Bump `chrono` from 0.4.38 to 0.4.44
- Bump `directories` from 5.x to 6.0.0
- Bump `toml` from 0.8.x to 1.1.2

---

## [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.7] — 2026-04-09

### Corrigido (CI / Build)

- **Job de CI MSRV**: `assert_cmd` pinado em `"=2.1.2"` em `[dev-dependencies]` (última versão usando `edition = "2021"` antes de a crate migrar para `edition = "2024"` exigindo Rust 1.85). Restaura compatibilidade com MSRV 1.75 preservando a decisão canônica da Sessão 09.
- **Gate de cobertura**: `cargo llvm-cov` agora ignora arquivos de dispatcher estrutural (`src/cli.rs`, `src/lib.rs`, `src/main.rs`) via `--ignore-filename-regex`. Esses arquivos contêm dispatchers async e entry points com ~0% de cobertura por design, e estavam puxando o threshold total de 80% para abaixo de 79%. Arquivos de lógica de negócio (`src/storage.rs` 95%, `src/errors.rs` 94%, `src/output.rs`, `src/i18n.rs`) continuam sendo totalmente validados.
- **Startup failure do workflow de release**: unificamos os dois steps de codesign da Apple (adhoc vs Developer ID) em um único step com secrets injetados via `env:` e `if` em shell. As condições anteriores `if: ${{ secrets.APPLE_TEAM_ID == '' }}` referenciavam o contexto `secrets` em `if:` de step, o que **não é permitido** pelo GitHub Actions (ver docs oficiais de context availability). Isso causava falha do workflow de release no startup, em 0s, a cada push para `main`.

### Técnico

- **Zero mudanças em runtime**: o comportamento do binário é **idêntico** ao v0.2.6. Usuários que já estão na v0.2.6 não ganham nada funcionalmente com o upgrade — este release existe apenas para restaurar um pipeline de CI verde.
- **Zero mudanças em dependências de runtime**: apenas a seção `[dev-dependencies]` foi tocada (pin do `assert_cmd`).
- **190 testes passando, 0 falhando** (inalterado em relação a v0.2.6).
- **Zero CVEs**, `cargo deny` PASS nos 4 checks (advisories, licenses, bans, sources).
- **Todas as 9 decisões canônicas preservadas**: rand 0.8, colored 2, thiserror 2, directories 6, rust-version 1.75, hook anti-bot 842 bytes, `added_at: String`, `stars: i64 -1`, nomes crate-vs-binário.

---

## [0.2.6] — 2026-04-09

### Corrigido

- **Exit code de `keys remove` em caso de falha**: `cmd_keys_remove` agora retorna `Err(ErroContext7::OperacaoKeysFalhou)` (exit code 1) quando o índice é inválido (0 ou fora do intervalo) ou quando o storage está vazio. Anteriormente os três caminhos de erro retornavam `Ok(())`, reportando sucesso silenciosamente (exit code 0) — regressão identificada no QA da v0.2.4. A mensagem colorida exibida ao usuário permanece inalterada; apenas o exit code foi corrigido.
- **Mensagem "Nenhuma chave de API configurada" hardcoded em português**: `carregar_chaves_api` em `storage.rs` agora usa `t(Mensagem::NenhumaChaveConfigurada)` em vez de uma string PT hardcoded, garantindo que a mensagem de erro respeite a flag `--lang` e a variável de ambiente `CONTEXT7_LANG`.
- **Exibição de timestamp em `keys list`**: os timestamps eram exibidos como strings RFC3339 completas com 9 dígitos de nanosegundos (ex.: `2026-04-09T13:34:59.060818734+00:00`). Agora formatados como `AAAA-MM-DD HH:MM:SS` (ex.: `2026-04-09 13:34:59`) pelo novo helper `formatar_added_at_display` em `output.rs`. O formato de disco de `added_at` é preservado (RFC3339 canônico — mudança apenas de exibição).

### Segurança

- **Teste de regressão para path traversal** (`LOW-01`): adicionado `testa_context7_home_rejeita_path_traversal` cobrindo `..`, `../../../etc` e `/tmp/../etc`. Confirma que `resolver_home_override` rejeita todos os caminhos com `Component::ParentDir` e cai no fallback XDG. A lógica de rejeição já existia desde a v0.2.5; este teste a torna explícita e previne regressões.

### Técnico

- 173 testes passando (ante 172 na v0.2.5).
- Zero breaking changes — comportamento dos subcomandos, formatos de storage e API pública permanecem idênticos.
- `formatar_added_at_display` é uma nova função pública em `output.rs`, testável de forma isolada.
- Documentação corrigida: `CONTEXT7_HOME` cria diretórios inexistentes automaticamente no primeiro uso (era documentado como fallback XDG silencioso).

---

## [0.2.5] — 2026-04-09

### Corrigido

- **CI matrix — job MSRV**: o passo `cargo check` agora regenera o `Cargo.lock` usando a toolchain 1.75 antes de rodar as verificações, corrigindo falha de build causada pelo formato v4 do lockfile ser incompatível com o Rust 1.75.
- **Testes de storage com vazamento de estado no Windows/macOS**: 18 testes em `storage::testes` que resolviam caminhos reais via `directories::ProjectDirs` agora usam a variável `CONTEXT7_HOME` para isolamento completo — sem mais contaminação entre testes nos runners de CI não-Linux.
- **Job `commit-check` usava `grep -iE`**: substituído por `rg -qi` / `rg -i` para cumprir a política de ferramentas CLI do projeto (proibido usar `grep`).

### Adicionado

- **Variável de ambiente `CONTEXT7_HOME`** — define um diretório customizado para o arquivo de configuração do `context7`, sobrepondo o caminho XDG padrão. Útil para dotfiles, configurações NixOS, contêineres Docker e ambientes de teste isolados. Precedência: `CONTEXT7_HOME` > padrão `ProjectDirs`.
- **Job Alpine musl no CI**: valida que o binário compila corretamente com musl libc (via target `x86_64-unknown-linux-musl`).
- **Universal Binary para macOS** (`release.yml`): executa `lipo` para combinar as slices `x86_64-apple-darwin` e `aarch64-apple-darwin`; aplica assinatura ad-hoc; usa `notarytool` quando as credenciais estão disponíveis.
- **Manifesto Flatpak** em `packaging/flatpak/` para distribuição via Flathub.
- **Manifesto Snap** (`packaging/snap/snapcraft.yaml`) para distribuição via Snap Store.
- **Jobs de CI**: `cargo-audit` (varredura de vulnerabilidades), `cargo deny check` (licenças + advisories), `cargo-llvm-cov` (gate de cobertura em 80% de linhas).
- **Artefatos pré-compilados** publicados em cada GitHub Release: `tar.gz` para Linux (gnu + musl), `.zip` para Windows, Universal Binary para macOS.

### Alterado

- **`dependabot.yml`**: adicionadas entradas `ignore` para `rand 0.9.x`, `colored 3.x`, `toml 2.x`, `actions/checkout 5.x`/`6.x` e `dtolnay/rust-toolchain 1.100` — versões com major bump que violariam o MSRV ou quebrariam decisões canônicas de API.

### Segurança

- Fechados 4 PRs do Dependabot (`#1` bump dtolnay toolchain, `#2` actions/checkout v5, `#3` colored 3.x, `#4` rand 0.9.x) — todos upgrades major que violariam o MSRV ou quebrariam as decisões canônicas de dependências do projeto.

---

## [0.2.4] — 2026-04-09

### Corrigido

- **Saída UTF-8 no Windows**: habilitado modo UTF-8 no console Windows via `SetConsoleOutputCP(65001)` na inicialização, para que caracteres acentuados e símbolos sejam exibidos corretamente no CMD e PowerShell.
- **Cores ANSI no Windows**: habilitado Virtual Terminal Processing via `SetConsoleMode` para que as sequências de escape do `colored` sejam renderizadas como cores em vez de códigos brutos no console Windows.
- **Confirmação no `keys clear`**: o prompt interativo agora aceita `y` e `yes` (sem distinção de maiúsculas/minúsculas), corrigindo um problema em que digitar `yes` era rejeitado.
- **Mensagem de `keys remove 0`**: a verificação de índice 1-based agora exibe uma mensagem clara ("o índice deve ser ≥ 1") em vez de falhar silenciosamente com mensagem genérica.

### Adicionado

- **Pipeline de CI** (`ci.yml`): build em matriz em `ubuntu-latest`, `windows-latest`, `macos-latest` com Rust estável; executa `cargo check`, `cargo clippy -- -D warnings`, `cargo fmt --check` e `cargo test`.
- **Workflow de release** (`release.yml`): acionado em tags `v*`; publica no crates.io e cria um GitHub Release.
- **Dependabot** (`dependabot.yml`): atualizações semanais de dependências Cargo.
- **Template de PR** (`.github/PULL_REQUEST_TEMPLATE.md`): checklist bilíngue lembrando contribuidores de usar "Squash and merge" para PRs de bots.
- **`deny.toml`**: configuração do `cargo-deny` para lista de licenças permitidas e verificação de advisories de segurança.

### Documentação

- **Formato de saída do Passo 4** (HOW_TO_USE.md): todos os exemplos atualizados para o formato v0.2.3 — título da biblioteca em negrito, ID em dimmed na linha abaixo, trust score inline como `(confiança X.X/10)`.
- **Contagem de tentativas** (HOW_TO_USE.md, context7-llm-rules.md): corrigidas todas as referências de "3 tentativas/retries" para "5 tentativas" para corresponder à constante real `MAX_TENTATIVAS = 5`.
- **Formato da lista de chaves no Passo 3** (HOW_TO_USE.md): exemplo de `keys list` atualizado para o formato atual `[N]  ctx7sk-...  (added: ISO-timestamp)`.
- **ID de biblioteca `/reactjs/react.dev`** (todos os docs): substituídas 60 ocorrências do ID obsoleto `/facebook/react` em `HOW_TO_USE.md`, `README.md`, `context7-skill.md` e `context7-llm-rules.md`.
- **Correção de âncora** (HOW_TO_USE.md): corrigido link quebrado apontando para um heading renomeado.
- **Link para LLM rules** (HOW_TO_USE.md): a referência "LLM rules" agora aponta para `docs/context7-llm-rules.md` (estava apontando para o caminho obsoleto `docs/llm-rules.md`).
- **Nota obsoleta de troubleshooting v0.2.0** (HOW_TO_USE.md §8): substituída por instrução de upgrade via `cargo install context7-cli --force`.
- **Sumário** (HOW_TO_USE.md): adicionado sumário bilíngue com links de âncora para cada seção principal.
- **Bump de versão do `context7-skill.md`**: `0.2.3` → `0.2.4`.
- **Descrição do Cargo.toml**: melhorada para refletir a natureza bilíngue e de múltiplas chaves da ferramenta.

### Alterado

- **User agent**: atualizado de `context7-cli/0.2.3` para `context7-cli/0.2.4`.

### Dependências

- Atualização do `reqwest` de 0.12.8 para 0.12.9
- Atualização do `chrono` de 0.4.38 para 0.4.44
- Atualização do `directories` de 5.x para 6.0.0
- Atualização do `toml` de 0.8.x para 1.1.2

---

## [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.