Skip to content

v0.7.5 — 4-tool Windows preflight + docs/INSTALL-WINDOWS + audit batch

Choose a tag to compare

View all tags
@daniloaguiarbr daniloaguiarbr released this 14 Jun 08:21
v0.7.5
f4d767c

Changelog

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[0.7.5] - 2026-06-14

Fixed (audit batch 2026-06-14)

  • P1-audit-1 (MEDIUM, error contract) — src/lib.rs execute_deep_research was using println!("{json}") directly, violating the documented rule that output.rs is the only module with println! (lib.rs doc-table line 34). Now delegates to output::print_line_stdout which handles BrokenPipe cleanly (silent success on | head, generic error on real I/O failure). Closes the audit finding that the JSON contract for deep-research was bypassing the central output abstraction.
  • P1-audit-2 (LOW, code clarity) — Removed the unreachable!("handled above") arm in the subcommand dispatch by folding the DeepResearch branch into the main match (and dropping the preceding if let Some(Subcommand::DeepResearch(...)) early-return). The compile-time exhaustiveness check now covers the variant without panicking on dispatch.
  • P1-audit-3 (LOW, exit code semantics) — CliError::Cancelled now maps to exit code 130 (POSIX: 128 + SIGINT(2)) instead of 1 (generic error). Shell sessions can now distinguish user-initiated Ctrl-C from real runtime failures, and process supervisors (e.g. CI runners, set -e scripts) treat cancellation as exit 130 per convention.
  • P1-audit-4 (LOW, error code mapping) — Three string error code mappings were semantically wrong: InvalidConfig → selector_config_invalid (should be invalid_config); PathError → selector_config_invalid (should be path_error); BrokenPipe → http_error (should be broken_pipe). New constants added: codes::INVALID_CONFIG, codes::PATH_ERROR, codes::BROKEN_PIPE. All three string mappings now use their dedicated constant. Consumers parsing the error field of the JSON output can now route on the precise failure mode.
  • P2-audit-5 (LOW, documentation drift) — #![doc(html_root_url = "https://docs.rs/duckduckgo-search-cli/0.7.4")] was lagging the Cargo.toml version. Updated to 0.7.5. Closes the docs.rs cross-link drift.
  • P2-audit-7 (MEDIUM, distribution hygiene) — Cargo.toml [build-dependencies] now includes clap and clap_mangen = "0.2". The existing build.rs was extended to call a new generate_man_page() function that emits duckduckgo-search-cli.1 in OUT_DIR using a best-effort mirror of the src/cli.rs CLI definition. The man page is a packaging convenience (not build-critical); failures are logged to stderr but do not panic the build. A future refactor will extract the CLI definition into a shared module to eliminate the mirror.
  • P3-audit-11 (LOW, CI drift) — Cross.toml listed armv7-unknown-linux-musleabihf as a developer convenience target, but the comment also claimed "5 principais" targets were covered by release.yml (false: release.yml only covers x86_64-unknown-linux-musl and aarch64-apple-darwin). Removed the armv7-unknown-linux-musleabihf block and updated the comments to accurately reflect which targets are CI-covered vs. dev-only. No release behavior change.

Test coverage delta

  • src/error.rs::tests — added assertions for Cancelled.exit_code() == 130, Cancelled.error_code() == "cancelled", BrokenPipe.error_code() == "broken_pipe", PathError.error_code() == "path_error", InvalidConfig.error_code() == "invalid_config". Total error::tests: 5 tests, all pass.

Fixed

  • GAP-WS-29 (CRITICAL, build experience, Windows) — cargo install on native Windows MSVC without the C++ CMake tools for Windows sub-component of the Visual Studio Installer previously failed minutes into the BoringSSL build with the cryptic failed to execute command: program not found / is 'cmake' not installed?. The build.rs preflight is now extended to detect this and abort in SECONDS with the exact fix (winget install -e --id Kitware.Cmake OR Visual Studio Installer → Modify → Workloads → Desktop development with C++ → expand → check C++ CMake tools for Windows). New escape hatch: DDG_SKIP_CMAKE_CHECK=1. Root cause: the workload C++ build tools does NOT include the C++ CMake tools sub-component — the latter must be selected manually.
  • GAP-WS-30 (CRITICAL, build experience, Windows) — BoringSSL CMake uses the Visual Studio 17 2022 generator which requires cl.exe (compiler) and link.exe (linker). The build.rs preflight now detects both and aborts with the fix (open a Developer PowerShell for VS 2022, or run Launch-VsDevShell.ps1). MSVC is NOT auto-installed (5+ GB download, too intrusive). New escape hatch: DDG_SKIP_MSVC_CHECK=1.
  • GAP-WS-31 (CRITICAL, build experience, Windows) — BoringSSL perlasm generator emits crypto assembly in NASM format and requires perl.exe. The build.rs preflight now detects perl and reports the fix (winget install -e --id StrawberryPerl.StrawberryPerl). New escape hatch: DDG_SKIP_PERL_CHECK=1.
  • GAP-WS-32 (CRITICAL, documentation) — skill/duckduckgo-search-cli-en/SKILL.md line 561 and skill/duckduckgo-search-cli-pt/SKILL.md line 565 still claimed "Pre-built binaries from cargo install are unaffected" / "Binários pré-compilados do cargo install não são afetados". This was already false in v0.7.4 (only llms.txt and README*.md were corrected); now corrected in the skills too. crates.io NEVER distributes binaries; cargo install always compiles from source.
  • GAP-WS-33 (MEDIUM, documentation) — Skill frontmatter said "Released 2026-06-08" (v0.7.3 date) while the binary is v0.7.4 of 2026-06-11. Now both EN and PT skills say "Released 2026-06-14 (v0.7.5)".
  • GAP-WS-34 (MEDIUM, documentation) — Skills only listed Linux build prerequisites. Now mention the four Windows prerequisites (NASM, CMake, MSVC, Perl) and the new build.rs preflight + escape hatches.
  • GAP-WS-35 (MEDIUM, documentation) — llms-full.txt (line 273-305, embedding of docs/HOW_TO_USE.md) claimed "Pre-built binaries require no Rust installation" without qualifying that this is ONLY true for GitHub Releases binaries. cargo install always requires Rust and always compiles from source. Now qualified.
  • GAP-WS-36 (MEDIUM, documentation) — docs/CROSS_PLATFORM.md line 193 and README.md line 336 and README.pt-BR.md line 428 claimed "VS Build Tools with C++ workload provides CMake". The C++ workload does NOT provide CMake — that is a separate sub-component. Now corrected in all three files.
  • GAP-WS-37 (MEDIUM, build) — build.rs v0.7.4 only checked for NASM. Now checks for the four BoringSSL build prerequisites (nasm, cmake, cl.exe, link.exe, perl) and supports four independent escape hatches.

Added

  • scripts/check-windows-toolchain.ps1 — standalone diagnostic (no installs) that checks all 7 tools (cargo, rustc, cmake, nasm, cl.exe, link.exe, perl) and emits text or JSON output. Exit code 0 if all present, 1 otherwise. Useful for support tickets and CI gates.
  • docs/INSTALL-WINDOWS.md (EN) + docs/INSTALL-WINDOWS.pt-BR.md (PT) — step-by-step guide covering 5 installation methods (VS Installer + standalone; all-winget standalone; Chocolatey; helper script; standalone diagnostic). Includes troubleshooting for each of the 4 GAPs and the DDG_SKIP_*_CHECK escape hatches.

Changed

  • scripts/install-windows.ps1 — refactored to use generic Find-Tool and Install-Tool helpers; now detects and auto-installs CMake (Kitware.Cmake) and Perl (StrawberryPerl.StrawberryPerl) in addition to NASM. MSVC is NOT auto-installed (too large); the script prints the exact Launch-VsDevShell.ps1 instruction instead. New --check-only mode produces a tabular report suitable for CI gates.
  • build.rs — 4 detector functions (nasm_in_path, cmake_in_path, cl_in_path, link_in_path, perl_in_path) + 2 known_*dir functions. The preflight fires 4 panic messages with actionable fixes when a tool is missing. 4 independent escape hatches.
  • .github/workflows/ci.yml + .github/workflows/release.yml — Windows jobs now verify CMake, install Perl, and verify MSVC Build Tools (in addition to the existing NASM step).
  • Cargo.toml version bump: 0.7.4 → 0.7.5.

No runtime changes

  • Same CLI flags, same JSON schema, same default behavior as v0.7.4. crates.io still ships NO pre-built binaries.

[0.7.4] - 2026-06-11

Fixed

  • GAP-WS-28 — cargo install falhava no Windows nativo por NASM ausente.
    Erro literal: CMake Error at CMakeLists.txt:374 (enable_language): No CMAKE_ASM_NASM_COMPILER could be found, surgindo MINUTOS após o início do build do BoringSSL, sem indicar a correção. Causa raiz em 4 camadas: (CR1) o CMakeLists.txt do BoringSSL exige enable_language(ASM_NASM) quando NOT OPENSSL_NO_ASM em Windows x86/x86_64; (CR2) o build script do btls-sys v0.5.6 TEM um ramo OPENSSL_NO_ASM=YES para Windows (build/main.rs:314-318), mas ele é INALCANÇÁVEL em builds nativos pelo early-return host == target (build/main.rs:231); (CR3) o instalador do NASM não ajusta o PATH e o Visual Studio não inclui nasm.exe; (CR4) a documentação afirmava incorretamente que binários Windows eram pre-built (crates.io não distribui binários). Ver gaps.md GAP-WS-28.
  • Novo build.rs com preflight fail-fast: em target windows-msvc nativo, detecta nasm.exe ausente do PATH e aborta em SEGUNDOS com instrução exata (winget install -e --id NASM.NASM + ajuste de PATH + referência ao script). Detecta NASM instalado fora do PATH em diretórios conhecidos. Escape hatch: DDG_SKIP_NASM_CHECK=1. Cross-compile não é afetado (usa o caminho OPENSSL_NO_ASM do btls-sys).

Added

  • scripts/install-windows.ps1 — instalação automatizada e consentida no Windows: detecta NASM, instala via winget (fallback choco), corrige o PATH da sessão e roda cargo install duckduckgo-search-cli --locked repassando argumentos extras.
  • CI: passo explícito de verificação/instalação de NASM (choco install nasm -y) nos jobs Windows de ci.yml e release.yml — elimina a dependência implícita do NASM pré-instalado na imagem windows-2022 (se a imagem mudar, o build não quebra silenciosamente).

Changed

  • README.md, README.pt-BR.md, llms.txt, llms.pt-BR.txt e docs/CROSS_PLATFORM*.md: removido o claim FALSO de que binários Windows/macOS eram "pre-built and unaffected" — cargo install SEMPRE compila do source. Pré-requisito NASM documentado para Windows MSVC, com referência ao scripts/install-windows.ps1.

Notes

  • GAP-WS-28 FECHADO neste repositório (S1 preflight + S2 script + S3 docs + CI hardening). Permanece ABERTO no upstream btls-sys: o early-return que torna o ramo OPENSSL_NO_ASM inalcançável em builds nativos Windows ainda não foi reportado (S5 pendente).
  • Nenhuma mudança de comportamento em runtime: a release contém apenas preflight de build, script de instalação, hardening de CI e documentação.

[0.7.3] - 2026-06-08

Fixed

  • GAP-WS-27 — Bloqueio CAPTCHA no macOS que não ocorre no Windows.
    Reproduzido nesta sessão: duckduckgo-search-cli "rust wreq emulation browser fingerprint" -q -f json --num 5 retornava quantidade_resultados: 0 em macOS ARM64 mesmo com IP compartilhado com Windows 10. Causa raiz: fingerprint TLS do rustls é reconhecível pelo Cloudflare Bot Management (vetor JA4_o), disparando CAPTCHA interstitial em HTTP 200.
  • Substituído reqwest 0.12 + rustls-tls por wreq 6.0.0-rc.29 + BoringSSL (boring2 v4.15.11) + wreq-util 3.0.0-rc.12. BoringSSL embarcado produz JA4_o idêntico ao Chrome/Safari real, eliminando o CAPTCHA. Ver ADR docs/decisions/0001-tls-boring-via-wreq.md.
  • Mesma query após migração: 5 resultados, 735ms, sem fallback, sem CAPTCHA. Validação cross-OS pendente (operador deve testar em Windows / Linux).

Added

  • PR2 — feature session (cookie persistence + warm-up):
    • Flag --no-warmup para desabilitar a requisição GET https://duckduckgo.com/ de warm-up.
    • Flag --no-cookie-persistence para manter cookies apenas em memória.
    • Flag --cookies-path <PATH> para sobrescrever o local padrão do cookies.json.
    • Cookie jar persistido em ~/.config/duckduckgo-search-cli/cookies.json (Unix) ou %APPDATA%\duckduckgo-search-cli\cookies.json (Windows) ou ~/Library/Application Support/duckduckgo-search-cli/cookies.json (macOS).
    • Permissões 0o600 aplicadas no Unix (owner read+write only).
    • Módulo src/session_warmup.rs (XDG path resolution) e src/wreq_cookie_adapter.rs (JSON <-> wreq::cookie::Jar bridge).
  • PR3 — feature probe-deep (CAPTCHA interstitial detection):
    • Flag --probe-deep que executa uma query real e classifica o body como ok ou captcha baseado em marcadores Cloudflare/DuckDuckGo.
    • Flag --allow-lite-fallback (opt-in) para fallback automático do endpoint html para lite quando interstitial é detectado.
    • Módulo src/probe_deep.rs com detectar_interstitial() e sugestao_mitigacao().
    • Reporta JSON com status, cascata_motivo, sugestao_mitigacao, http_status, latency_ms.

Changed

  • Stack TLS trocada de rustls para BoringSSL via wreq. Build agora requer cmake, perl, pkg-config, libclang-dev no Linux. Documentado em docs/CROSS_PLATFORM.md e ADR-0001.
  • ADR docs/decisions/0001-tls-boring-via-wreq.md registra a decisão arquitetural e trade-offs aceitos.
  • Build time de release aumentou ~30s (BoringSSL estático). Binário final ~20 MB maior.

Removed

  • Dependência reqwest 0.12 (substituída por wreq).
  • time 0.3.47 agora é puramente transitivo (vinha como dep direta para sobrescrever transitivo do reqwest).

Notes

  • GAP-WS-27 causa raiz 1 (fingerprint TLS) FECHADA. Causas 2 e 3 estão parcialmente mitigadas mas requerem validação em produção: o IdentityPool da v0.6.4 já gera Accept-Language coerente com --country, e a persistência de cookies reduz a frequência de sessões "cold". O gaps.md mantém o status "RESOLVIDO PARCIALMENTE" até validação cross-OS do operador.
  • O time 0.3.47 pin em Cargo.toml foi removido. time agora é transitivo puro de wreq e suas deps. CI deve continuar verde porque wreq puxa time 0.3.47+.
  • Test count: 292 lib (vs 279 em v0.7.2) + 18 wiremock + outras integrações = 0 falhas.
  • Build verificado: cargo build --release verde (40s), cargo test --lib verde, cargo test --tests verde, cargo clippy --all-targets -- -D warnings verde.

[0.7.2] - 2026-06-07

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

Fixed

  • CI: 9 jobs failing on 10 E0599 compile errors (rand 0.10 trait
    reorg — the random_range / random_bool / random convenience
    methods moved from Rng to RngExt in rand 0.10.0). Updated the
    use lines in src/identity.rs, src/parallel.rs, and
    src/search.rs to import RngExt instead of Rng. This unblocks
    cargo check, build, test, clippy, doc, publish --dry-run,
    validate, musl smoke, msrv, and coverage jobs (all cascading
    failures of the same root cause).
  • CI: supply chain (audit + deny) job failing on RUSTSEC-2026-0009
    (time 0.3.40 denial-of-service via stack exhaustion when parsing
    RFC 2822 date headers, severity 6.8 medium). Resolved by upgrading
    time to 0.3.47 (the patched release). The defensive ignore in
    deny.toml for this advisory is now obsolete and has been removed.

Changed

  • rand bumped from 0.8 (used in published v0.7.1) to 0.10 in
    this hotfix. The dev-deps ecosystem (proptest 1.11+, getrandom
    0.4+) unified on 0.10, and 0.10 introduced the RngExt trait as
    the new home for the convenience methods.
  • rust-version bumped from 1.75 to 1.88 (matches time 0.3.47
    MSRV and the rand 0.10 ecosystem). All other crates still compile
    on 1.88+.
  • time pinned to 0.3.47 as a direct dependency to override the
    transitive time 0.3.40 pulled in by cookie_store 0.22.0 →
    reqwest 0.12.28 (RUSTSEC-2026-0009 stack-exhaustion DoS).

Notes

  • v0.7.1 was published with the source compiled against rand 0.9
    (the lock at the time resolved to a registry snapshot that no
    longer exists on crates.io). The CI subsequently failed because
    the registry was updated and the lock now resolves to rand 0.10.
    This hotfix migrates the source forward to match the registry
    state.
  • Test count: 402 (289 lib + 101 integration + 12 doctest), 0
    failures. Clippy clean, doc clean, fmt clean, deny clean, audit
    clean.

[0.7.1] - 2026-06-07

Changed

  • Migrated from rand 0.8 to rand 0.10 to align with the dev-deps
    ecosystem (proptest 1.11+, getrandom 0.4+) and the new RngExt trait
    surface in 0.10.0. Code now imports rand::RngExt for the
    random_range / random_bool / random methods.
  • rust-version bumped from 1.75 to 1.88 (matches time 0.3.47 MSRV
    and the rand 0.10 ecosystem). All other crates still compile on 1.88+.
  • reqwest features gzip and brotli removed: reqwest 0.12 dropped
    the ClientBuilder::gzip/brotli builder methods. Decompression is now
    enabled via the standard Accept-Encoding: gzip, br request header (which
    reqwest handles transparently).
  • Replaced rand::thread_rng() with rand::rng() in 4 sites (the
    former is deprecated since rand 0.9).
  • Replaced Rng::gen_range → RngExt::random_range in 7 sites.
  • Replaced Rng::gen_bool → RngExt::random_bool in 2 sites.
  • Replaced Rng::gen::<T>() → RngExt::random::<T>() in 1 site.
  • Replaced rand::seq::SliceRandom with rand::seq::IndexedRandom for
    choose calls on slices (the choose method moved traits in 0.9).
    IteratorRandom::choose is still used for Iterator types (e.g.
    slice.iter().filter().choose).
  • Pinned time = "0.3.47" as a direct dependency to override the
    transitive time 0.3.40 pulled in by cookie_store 0.22.0 →
    reqwest 0.12.28 (RUSTSEC-2026-0009 stack-exhaustion DoS).

Fixed

  • CI: 9 jobs failing on 10 E0599 errors (no method named random_range/random_bool/random found for struct ThreadRng in the current scope) caused by the rand 0.10 trait reorganisation (the convenience
    methods moved from Rng to RngExt). Updated the use lines in
    src/identity.rs, src/parallel.rs, and src/search.rs to import
    RngExt instead of Rng.
  • CI: supply chain (audit + deny) job failing on RUSTSEC-2026-0009
    (time 0.3.40 denial-of-service via stack exhaustion when parsing RFC
    2822 date headers, severity 6.8 medium). Resolved by upgrading
    time to 0.3.47 (the patched release). The defensive ignore in
    deny.toml for this advisory is now obsolete and has been removed.
  • CI: 5 jobs failing on E0599 no method named choose (caused by the
    trait move of choose from IteratorRandom to IndexedRandom in
    rand 0.9). Updated import in src/http.rs and src/identity.rs.
  • CI: msrv job failing on assert_cmd 2.2.0 edition 2024 parse.
    After the rust-version bump to 1.88, this is now parseable.
  • CI: workflow syntax check (actionlint) failing on
    SC2046 (ci.yml:520) and SC2035 (release.yml:505)    . Quoted the
    unquoted command substitution and prefixed the glob with -- to
    prevent option-like name expansion.

[0.7.0] - 2026-06-07

Added

  • New subcommand deep-research — query fan-out pipeline for LLM
    consumption. Splits the user query into 1..=12 sub-queries via five
    canonical heuristic templates (aspect, comparison, timeline, opinion,
    cause), fans them out through the existing parallel executor, aggregates
    the per-sub-query results with Reciprocal Rank Fusion (K=60) or
    canonical-URL deduplication, and optionally produces a synthesised
    report in Markdown, PlainText, or JSON with numbered references.
  • New module src/deep_research.rs — pipeline orchestrator
    (run_deep_research(args, cfg, cancel)).
  • New module src/decomposition.rs — heuristic + manual sub-query
    generation. Reads explicit sub-queries from a file when the
    --sub-query-strategy manual flag is set; comments (#) and blank
    lines are ignored.
  • New module src/aggregation.rs — Rrf(K=60) and DedupeByUrl
    strategies. URL canonicalisation strips utm_* and other tracking
    parameters, lowercases the host and scheme, sorts query parameters,
    and collapses repeated slashes. The canonical form is hashed with
    blake3 (first 16 hex chars) to serve as the dedup key.
  • New module src/synthesis.rs — three output formats
    (Markdown, PlainText, Json) with a configurable token budget
    (1 token ≈ 4 chars heuristic) and a 20-reference cap per report.
  • New dependencies:
    • url = "2" — URL canonicalisation in aggregation.rs.
    • regex = "1" — used by decomposition::is_composite_query to
      detect composite-query signals and suppress redundant templates.
    • proptest = "1" (dev) — property-based tests for new modules.

Changed

  • Version bumped from 0.6.11 to 0.7.0 (minor: new public
    subcommand deep-research and four new public modules
    deep_research, decomposition, aggregation, synthesis). No
    breaking changes to the existing buscar subcommand or the default
    SearchOutput / MultiSearchOutput schemas — additive only.
  • Config construction in lib::execute_deep_research builds a
    default config from the global flags — parallelism = 5,
    retries = 2, endpoint = Html, language = en, country = us,
    global_timeout = 120s. The pipeline inherits these defaults and
    does NOT require the operator to pass a full CliArgs.

Internal

  • Cargo.toml exclude block — gaps.md and docs_prd/ are
    excluded from the published crate.
  • [profile.release] panic = "abort" — smaller binary, harder to
    leak panic payloads across the FFI boundary if one is ever added.
  • .gitignore — added proptest-regressions/, coverage/,
    tarpaulin-report.html, and .cargo-deny-state.json to match the
    real artifacts produced by the new test suite and CI tooling.

Gap closure pass

  • Doctests added to all four new modules (12 doctests total):
    aggregation::canonicalize_url, synthesis::estimate_tokens,
    synthesis::trim_to_budget, decomposition::HeuristicTemplate::suffix,
    deep_research::DeepResearchArgs::validate, and a usage example in
    deep_research::run_deep_research.
  • Property-based tests with proptest (7 tests) covering
    canonicalize_url (idempotence, fragment strip, tracking-param strip,
    host lowercasing) and synthesis (estimate_tokens monotonicity,
    trim_to_budget ceiling + idempotence). proptest-regressions/ is
    captured in .gitignore.
  • regex integrated in decomposition::is_composite_query with
    CompositeSignal enum (Comparison, Aspect, Timeline, Opinion, Cause,
    Topic) and OnceLock-cached compiled patterns. The heuristic strategy
    now suppresses redundant templates (e.g. Comparison is skipped when
    the query already contains vs or or).
  • Wiremock integration tests in tests/integration_deep_research.rs
    (17 tests): pipeline smoke, query-param matching, HTTP 202 anomaly
    observability, 404 observability, and 13 surface-coverage tests.
  • cargo deny check — all four gates pass: advisories ok, bans ok, licenses ok, sources ok.
  • cargo publish --dry-run — package created and verified
    (1.1 MiB, 14.00 s on a warm cache).
  • Latent UTF-8 bug fixed in synthesis::trim_to_budget — was using
    byte indexing without a char-boundary check, which panicked on
    multi-byte inputs (the same panic shape that the proptest book
    highlights). Replaced with a private floor_char_boundary helper.
    Three proptests lock in the invariant
    is_char_boundary(out.len()) for arbitrary inputs.

Validation

  • cargo build --release — clean.
  • cargo clippy --all-targets --all-features -- -D warnings — clean.
  • cargo test --lib — 279 tests passing, 0 failing.
  • cargo test --doc — 12 doctests passing.
  • cargo test --tests — 101 integration tests passing (24 + 3 + 17 + 5 + 10 + 10 + 14 + 18).
  • Total: 392 tests passing (279 lib + 12 doc + 101 integration), 0 failing.
  • RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --lib — clean.
  • cargo fmt --all -- --check — clean.
  • cargo audit — no new advisories (pre-existing RUSTSEC-2025-0057
    on selectors 0.25.0 is the only warning and is tracked separately).
  • cargo deny check — all four gates ok.
  • cargo publish --dry-run — ok.

[0.6.11] - 2026-06-05

Fixed

  • CI: crates_io step 6 Check if version already published failed with unbound variable exit 1 on tag v0.6.10

    • Root cause: the VERSION variable was referenced as VERSION="${VERSION}"
      on the first line of the script, but it was never defined in the step's
      env: block. With set -euo pipefail active, accessing an undefined
      variable caused bash: VERSION: unbound variable with exit 1, marking
      the step as conclusion: failure and short-circuiting the rest of the
      publish path. crates.io v0.6.10 was published manually via
      cargo publish --allow-dirty as a workaround.
    • Solution: passed VERSION: ${{ steps.detect_version.outputs.version }}
      in the step's env: block, mirroring the pattern already used by
      Verify tag matches Cargo.toml version. Also hardened the script
      with NO_COLOR=1 and a sed ANSI-strip as defense-in-depth against
      color codes that would break the parsing regex. Bumped retries from
      3 to 5 with linear backoff (5s/10s/15s/20s) to absorb transient
      crates.io rate limits.

  • CI: cargo search parsing is now resilient to ANSI color codes

    • The cargo search output is wrapped in ANSI escape codes when
      CARGO_TERM_COLOR=always is set (as it is in this workflow). On
      some color schemes the regex = "[0-9]+\.[0-9]+\.[0-9]+" was
      still matched, but on others the color codes were injected between
      characters and broke parsing.
    • Solution: strip ANSI escapes with sed -E 's/\x1b\[[0-9;]*[a-zA-Z]//g'
      before applying the regex, and set NO_COLOR=1 to disable color
      output explicitly. Both layers ensure the regex sees clean ASCII.

[0.6.10] - 2026-06-05

Fixed

  • CI: Publish to crates.io job rejected by environment protection rules — tag v0.6.9 not allowed in environment release

    • Root cause: the GitHub release environment had only branch_policy configured
      (protection_rules: [{"type": "branch_policy"}]), which causes GitHub Actions to
      reject any ref that is NOT a branch — including refs/tags/v0.6.9. The run ended
      with conclusion: failure and steps_count: 0 (job never even started), showing
      the annotation Tag "v0.6.9" is not allowed to deploy to release due to environment protection rules.
    • Solution: created a new release-publish environment (id 16308925736) with no
      protection_rules, which accepts ANY ref — including SemVer tags. The crates_io
      job now uses environment: name: release-publish.

  • CI: actionlint exit 3 — is a directory error when invoking actionlint .github/workflows/

    • Root cause: actionlint v1.x does NOT accept a directory as a positional argument;
      it expects individual files (e.g. *.yml) or to be invoked with no arguments
      (recursive auto-discovery of .github/workflows/). The incorrect invocation
      produced the error could not read ".github/workflows/": is a directory with
      exit 3, marking the workflow syntax check (actionlint) job as failed.
    • Solution: corrected the invocation to actionlint (no arguments) in the
      Run actionlint step of ci.yml. Local validation confirmed exit 0 with
      zero syntax errors.

  • CI: zizmor exit 13 — 2 secrets-outside-env findings (medium) in the github_release job

    • Root cause: the github_release job referenced secrets.GPG_PRIVATE_KEY and
      secrets.GPG_PASSPHRASE in env: without a dedicated environment:. The
      zizmor >= 1.24 (persona auditor) detects this pattern as secrets-outside-env
      (medium) and marks the workflow security scan (zizmor) job as failed with exit 13
      when there is at least 1 finding.
    • Solution: (1) removed the GPG secrets from the github_release env: and added
      the GPG_SIGNING_ENABLED: "false" gate at workflow level; (2) the
      Sign SHA256SUMS with GPG step was renamed to (DESABILITADO) and never
      executes; (3) created a .github/zizmor.yml config with
      rules.secrets-outside-env.config.allow listing CRATES_IO_TOKEN (which is
      at repo level for compatibility). Cosign keyless (job attest) already provides
      cryptographic integrity via Sigstore, covering the role GPG signing would play.

  • CI: package list now includes .github/zizmor.yml (intentional zizmor configuration)

    • Added .github/zizmor.yml with allow rules for the CRATES_IO_TOKEN secret at
      repo level. This file is a static config, contains no credentials and is safe
      to version.

[0.6.9] - 2026-06-05

Fixed

  • CI: Windows .zip release asset was empty (209 bytes) — bug in Package (Windows) PowerShell script

    • Root cause: the script used ${TARGET} / ${BIN} / ${EXT} syntax, which is bash interpolation.
      In PowerShell, ${VAR} is a string literal — env vars are interpolated as $env:VAR.
      Result: Copy-Item failed silently (source path became target//release/) and
      Compress-Archive produced an almost-empty zip (only SHA256SUMS.txt).
    • Solution: replaced all ${VAR} with $env:VAR in PowerShell run: blocks
      (Package (Windows) and Generate SHA256SUMS (Windows)).
    • Reference: incident-jaq-not-found-runner-2026-06-05 + cross-cutting audit on 2026-06-05

  • CI: sbom.cdx.json CycloneDX SBOM was 0 bytes (file not actually generated)

    • Root cause: cargo cyclonedx --override-filename sbom.cdx.json actually writes
      sbom.cdx.json.json because the --override-filename flag auto-appends .json.
      The wc -c < sbom.cdx.json step then read 0 bytes from the non-existent file and
      the Upload SBOM as artifact step uploaded an empty file (artifact ignored downstream).
    • Solution: changed invocation to cargo cyclonedx --format json --override-filename sbom
      (stem only), then mv sbom.json sbom.cdx.json to match the expected filename.

  • CI: GitHub Release for v0.6.8 was incomplete (missing Windows zip + sbom)

    • Root cause: the above two bugs combined meant the v0.6.8 release workflow produced
      a Windows zip with only the SHA256SUMS stub and an empty SBOM. Manually uploaded
      the real SBOM after the fact; Windows zip requires a full re-run.

Unreleased

Fixed

  • CI: exit 101 crate already exists on Publish to crates.io job (post-mortem 2026-06-05)

    • Root cause: trigger duplicado do workflow para tag v0.6.6 já publicada causou cargo publish
      exit 101 com error: crate duckduckgo-search-cli@0.6.6 already exists on crates.io index.
      crates.io é append-only immutable, versões NUNCA podem ser sobrescritas.
    • Solution: added preflight + crates_io guard jobs with:
      • Tag-vs-Cargo.toml version consistency check
      • SemVer format validation
      • CHANGELOG entry presence check
      • Co-authored-by AI agent block in recent commits
      • cargo search with timeout + retry to detect already-published version
      • cargo publish skip with warning + evidence upload when already published
      • Timeout (300s) + retry (3 attempts, backoff 10s/20s/30s) on cargo publish
    • Resolution pattern: idempotent release workflow with explicit skip path

  • CI: 18+ Node.js 20 deprecation warnings in all jobs

    • Root cause: actions/checkout@v4, actions/upload-artifact@v4, actions/download-artifact@v4
      use Node 20. Node 20 deprecated 2025-09-19, removed 2026-09-16.
    • Solution:
      • Updated all actions to v6 (Node 24 native)
      • Updated softprops/action-gh-release from v2 to v3
      • Added FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" as belt-and-suspenders
    • Migration path: v6 is Node 24 native, v4 needs explicit env var

  • CI: exit 141 SIGPIPE intermittent in validate (ubuntu-latest)

    • Root cause: cargo test writes to pipe whose consumer closes early
    • Solution: explicit || { ec=$?; if [ $ec -eq 141 ]; then exit 0; fi; exit $ec; } guard
    • Trade-off: 141 silently becomes warning, may mask real test bugs

  • CI: exit 1 in validate (windows-latest) from VS2022→VS2026 redirect

    • Root cause: GitHub redirects windows-latest to windows-2025-vs2026 since 2025-06-15.
      VS2026 has breaking changes in MSVC toolchain that affect Rust stable.
    • Solution: pinned windows-2022 in ci.yml matrix and release.yml build target
    • Re-evaluate pin after 2026-07-15 once VS2026 stabilizes

Added

  • SBOM CycloneDX generation in release workflow — cargo cyclonedx --format json produces
    sbom.cdx.json uploaded as artifact. Enables compliance with EU Cyber Resilience Act.
  • SLSA provenance attestation — actions/attest-build-provenance@v2 creates signed
    provenance for all release artifacts. Level 3 SLSA compliance.
  • cosign keyless OIDC signing — every binary + SHA256SUMS.txt signed with cosign sign-blob
    using GitHub OIDC token. No private key management required.
  • SHA256SUMS published with every release — sha256sum generated per target, combined
    into single SHA256SUMS.txt, uploaded as release asset and as part of every binary tarball/zip.
  • GPG tag signing — optional gpg --detach-sign SHA256SUMS.txt if GPG_PRIVATE_KEY secret
    is configured. continue-on-error: true to avoid blocking release on missing key.
  • Concurrency control — concurrency.group: release-${{ github.ref }}-${{ github.sha }}
    prevents parallel runs for same tag+SHA. cancel-in-progress: false (release) / conditional
    on PR (CI) ensures publish is never aborted mid-flight.
  • Pre-flight job in release workflow — validates tag version == Cargo.toml version,
    SemVer format, CHANGELOG entry, no AI agent Co-authored-by BEFORE any build runs.
  • Cron weekly dependency update — scheduled_update job runs Sundays 03:00 UTC,
    executes cargo update --workspace, creates PR if changes detected.
  • Zizmor security scan — static analysis of GitHub Actions workflows detects
    injection, untrusted input, and other security anti-patterns. Runs only on PRs.
  • Actionlint syntax check — validates YAML syntax of all workflow files. Runs only on PRs.
  • Dependabot for actions and crates — .github/dependabot.yml creates weekly PRs
    for GitHub Actions updates and Rust crate updates. Groups by major/minor/patch.
  • .gitattributes LF normalization — forces LF line endings in all text files,
    preventing CRLF issues on Windows that break cargo fmt --check.

Security

  • Permissions hardened per job — top-level permissions: contents: write packages: write id-token: write attestations: write checks: write discussions: write for release;
    per-job permissions: blocks in CI for least-privilege.
  • continue-on-error: true on GPG step — missing GPG key does not block release;
    optional enhancement.
  • No pull_request_target triggers — workflows never run with write permissions
    on PRs from forks.

[0.6.8] - 2026-06-05

Fixed

  • CI: exit 127 jaq: command not found in github_release job of release workflow
    • Root cause: release.yml (lines 625-626) used jaq (Rust binary) to parse JSON
      response from GitHub REST API, but the GitHub Actions Ubuntu 24.04 runner only
      has jq 1.7 pre-installed — jaq is not part of the standard runner image.
      Bug introduced by commit 7f489b5 (2026-06-05) when bypassing the broken
      softprops/action-gh-release action.
    • Solution: replaced jaq with jq (pre-installed, syntax-compatible) and added
      explicit fail-fast validation for extracted UPLOAD_URL and RELEASE_ID values
      to surface clear diagnostic messages on malformed API responses.
    • Reference: <https://github.com/actions/runner-images/blob/main/images/ubuntu/
      Ubuntu2404-Readme.md> (Tools section lists jq 1.7, jaq is absent)

[0.6.7] - 2026-06-05

Fixed

  • CI: post-mortem completo do incident-publish-101-2026-06-05 (hardening release pipeline)
    • Added preflight job validating tag==Cargo.toml, SemVer, CHANGELOG, no AI Co-authored-by
    • Added guard de versão duplicada em crates_io job (zizmor: secrets-outside-env resolvido)
    • cargo publish com timeout 300s + 3 retries (network resilience)
    • Concurrency group por tag+sha (impede runs paralelos)
  • CI: 18+ Node.js 20 deprecation warnings
    • Updated actions to v6 (Node 24 native)
    • Updated softprops/action-gh-release v2 → v3
    • Added FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 as belt-and-suspenders
  • CI: zizmor security scan: 134 findings → 0
    • SHA pinning para 11 actions (unpinned-uses)
    • per-job least-privilege permissions (excessive-permissions)
    • comments + inline trailing em todas as permissions
    • secrets em env: job-level + GitHub Environments dedicados
    • ${{ ... }} em run: mitigated via env vars (template-injection)
    • dtolnay/rust-toolchain substituído por setup via rustup (superfluous-actions)
    • caches removidos do release.yml (cache-poisoning)
  • CI: actionlint 0 erros em ambos workflows
  • CI: zizmor zero findings (exit 0)
  • CI: dependabot.yml para auto-update semanal de actions e crates
  • CI: .gitattributes força LF line endings em todos os arquivos de texto
  • clippy: #[cfg(feature = "chrome")] redundante removido de src/lib.rs:74
    • browser.rs:25 já tem #![cfg(feature = "chrome")] que cobre o módulo
  • clippy: SAFETY comments adicionados a todos os Windows unsafe blocks em src/platform.rs
    • 5 blocos unsafe agora têm // SAFETY: comments explicando precondições
    • Necessário para clippy::undocumented_unsafe_blocks (deny em rust 1.96+)
  • test: tests incompatíveis com Windows marcados com #[cfg(unix)]
    • rejeita_path_absoluto_etc (testa /etc/shadow)
    • rejeita_path_absoluto_usr (testa /usr/bin/evil)
    • Ambos passam em Linux/macOS, pulam em Windows onde os paths são regulares

Added

  • SBOM CycloneDX generation em release workflow
    • cargo cyclonedx --format json produz sbom.cdx.json
    • Compliance com EU Cyber Resilience Act
  • SLSA build provenance via actions/attest-build-provenance@v2
  • cosign keyless OIDC signing (todos os binários + SHA256SUMS.txt)
  • SHA256SUMS publicado com cada release (gerado por target)
  • GPG tag signing (opcional, continue-on-error: true se chave ausente)
  • Pre-flight job em release workflow (9 gates + 1 dry-run)
  • Attestation job (SBOM + cosign + SLSA em 1 job)
  • scheduled_update Cron semanal (cargo update automático)
  • Zizmor security scan em CI (zero findings)
  • Actionlint syntax check em CI (zero erros)
  • Dependabot para actions e Rust crates (PRs semanais)

Security

  • Permissions endurecidas per-job (least-privilege)
  • Persist-credentials: false em 18/18 actions/checkout (artipacked)
  • Sem triggers pull_request_target (forks não rodam com write)
  • SHA pinning completo (11 actions com 40 chars + version comment)

[0.6.6] - 2026-06-05

Fixed

  • docs.rs build failure (Build #3487310) caused by #[doc(cfg(...))] becoming unstable
    • Removed #[cfg_attr(docsrs, doc(cfg(feature = "chrome")))] from src/lib.rs:70
    • Root cause: in Oct 2025 the Rust team merged doc_auto_cfg into doc_cfg (rust-lang/rust#43781),
      making #[doc(cfg(...))] require #![feature(doc_cfg)] (nightly-only) on the crate root.
      The build failed with error[E0658]: #[doc(cfg)] is experimental on nightly 1.98.0.
    • The feature gating itself is preserved: #[cfg(feature = "chrome")] still excludes
      pub mod browser from default builds. The module-level docstring in src/browser.rs
      already documents the feature requirement explicitly.
    • cargo doc --all-features and RUSTDOCFLAGS="--cfg docsrs" cargo doc --all-features
      both pass without warning or error.

[0.6.5] - 2026-06-05

Fixed

  • MP-26 — Windows HANDLE cast broken in windows-sys 0.59+ (src/platform.rs:51-63)
    • HANDLE mudou de isize para *mut c_void upstream (microsoft/windows-rs, raw-window-handle#171)
    • Substituído handle != 0 && handle != usize::MAX por !handle.is_null() && handle != INVALID_HANDLE_VALUE
    • Removidos casts inválidos handle as isize (a assinatura moderna aceita HANDLE direto)
    • Atualizado o // SAFETY: comment para documentar nulidade e sentinela Win32
  • CI: validate falhava em todos os 3 SOs (Linux/macOS/Windows) por 6 erros de clippy
    • 3× clippy::doc_markdown (PowerShell, rules_rust.md, TempDir) em src/platform.rs e src/browser.rs
    • 1× clippy::needless_return em src/browser.rs:149
    • 2× missing_debug_implementations em src/browser.rs:223 (ChromeBrowser) e src/content_fetch.rs (CircuitBreakerMap)

Added

  • WS-11 — Property-based invariants for HTML parsers (src/extraction.rs +5 testes)
    • Invariante: inputs vazios/quebrados retornam Vec vazio sem panic
    • Invariante: positions são densos e 1-based
    • Invariante: URLs absolutos (http/https) ou vazios
    • Invariante: extração é idempotente
    • Invariante: HTML malformado não causa panic
    • Zero dependência nova (apenas stdlib + #[test])
  • WS-12 — Per-host circuit breaker (src/content_fetch.rs)
    • Threshold: 3 falhas consecutivas abrem o circuito
    • Cooldown: 30s antes de half-open probe
    • Integração em enrich_with_content antes de cada fetch
    • BreakerDecision::{Allow, Reject} para inspeção
    • Zero dependência nova (std::sync::Mutex<HashMap>)
  • WS-23 — Retry-After header test (tests/integration_wiremock.rs)
    • Mock retorna 429 com retry-after: 2
    • Asserção: elapsed_ms >= 1500 (delay mínimo respeitado)
    • Usa wiremock 0.6 já em dev-deps
  • WS-25 — indicatif ProgressBar para crawls longos (src/content_fetch.rs)
    • indicatif = "0.18" adicionado
    • Bar com template [{elapsed_precise}] {bar:40.cyan/blue} {pos:>4}/{len:4} {msg}
    • Auto-detecta TTY (esconde em pipes)
    • progress.finish_and_clear() ao final
  • Lints preventivos FFI (Cargo.toml)
    • improper_ctypes = "deny" (rejeita casts FFI inválidos)
    • improper_ctypes_definitions = "deny" (rejeita definições incorretas)

Tests

  • 333 testes passando (243 lib + 24 + 3 + 5 + 10 + 10 + 14 + 18 + 6 doc)
  • 6 novos testes de invariantes em extraction.rs (WS-11)
  • 4 novos testes de circuit breaker em content_fetch.rs (WS-12)
  • 1 novo teste de Retry-After em integration_wiremock.rs (WS-23)
  • cargo fmt --all --check clean
  • cargo clippy --all-targets --all-features --locked -- -D warnings clean
  • cargo publish --dry-run --locked --allow-dirty clean

[0.6.4] - 2026-06-03

Added

  • WS-26 — Adaptive anti-bot identity rotation (new src/identity.rs module)
    • 12-identity pool (4 browser families × 3 platforms) for adaptive rotation
    • IdentityProfile::shuffled_headers() produces seed-deterministic header order
    • IdentityPool::rotate_on_block() implements a 5-level cascade: same identity → same family/different platform → different family/same platform → different family+platform → random
    • BrowserFamily and Platform enums with canonical English names
    • 5 unit tests covering pool size, cascade level, determinism, header shape, tag stability
  • New CLI flags (additive, no breaking changes)
    • --probe — pre-flight health check (sends 1 minimal request, reports status/latency/Set-Cookie as JSON)
    • --identity-profile — pin the session to a specific identity (auto, chrome-win, chrome-mac, chrome-linux, edge-win, firefox-linux, safari-mac). auto is default.
  • New JSON metadata fields (additive, Option + skip_serializing_if = "Option::is_none")
    • metadados.identidade_usada — string tag of the identity that produced the response
    • metadados.nivel_cascata — cascade level reached during the request

Changed

  • Version rollback: 0.7.0 (unpublished) → 0.6.4 to preserve the in-development feature set under a stable patch number
  • All existing CLI flags, JSON output schemas, and exit codes remain unchanged — strictly additive changes

Tests

  • 5 new identity unit tests (313 total tests passing, up from 308)
  • All 224 lib tests + 83 integration tests + 6 doc tests pass
  • cargo clippy --lib --bins -- -D warnings clean
  • cargo fmt --check clean

[0.7.0] - 2026-06-01

Changed

  • Complete internationalization: ~600 identifiers renamed PT→EN across 15 source files (struct fields, local variables, parameters, production functions, test functions)
  • Module fetch_conteudo renamed to content_fetch
  • Test files integracao_*.rs renamed to integration_*.rs
  • Replaced anyhow with typed CliError across all 11 modules — zero external error crate dependency
  • output.rs: all formatting functions renamed (formatar_* → format_*, escrever_* → write_*)
  • config_init.rs: struct fields renamed with #[serde(rename)] to preserve JSON backwards compatibility
  • search.rs: RetryResult and AggregatedSearchResult fields renamed PT→EN
  • types.rs: Config fields perfil_browser/corresponde_plataforma_ua/caminho_chrome → browser_profile/match_platform_ua/chrome_path

Added

  • Loom concurrency tests (tests/loom_atomics.rs) — validates AtomicBool visibility across threads
  • Criterion benchmarks (benches/extraction_bench.rs) — HTML extraction performance baselines
  • Doc comments for all 70 previously undocumented public items — zero missing_docs warnings
  • .ingest-queue.sqlite added to .gitignore and Cargo.toml exclude

Fixed

  • RUSTSEC-2026-0097: updated rand 0.8.5 → 0.8.6
  • RUSTSEC-2026-0104: updated rustls-webpki 0.103.12 → 0.103.13

Security

  • deny.toml: added skip-tree for 30 transitive duplicate crates (chromiumoxide, scraper, console-subscriber ecosystems)

Known Limitations

  • Loom tests require RUSTFLAGS="--cfg loom" which conflicts with hyper-util — tests compile but cannot run until upstream resolves the cfg conflict
  • JSON output field names remain in Portuguese Brazilian (posicao, titulo, resultados, etc.) — BY DESIGN since v0.2.0

[0.6.3] - 2026-04-17

Changed

  • Translated all 96 doc comments (/// and //!) across 19 source files from Portuguese to English — docs.rs now renders fully in English for international crates.io audience.
  • No code behavior, public API, or JSON output fields changed.

[0.6.2] - 2026-04-17

Added

  • 19 novos arquivos de documentação — conformidade completa com rules_rust_documentacao.md (28 gaps G01-G28)
  • Documentação bilíngue EN+PT: HOW_TO_USE, CROSS_PLATFORM, AGENTS-GUIDE, COOKBOOK.pt-BR, INTEGRATIONS.pt-BR
  • CODE_OF_CONDUCT.md + CODE_OF_CONDUCT.pt-BR.md — Contributor Covenant 2.1
  • README.pt-BR.md, CHANGELOG.pt-BR.md, CONTRIBUTING.pt-BR.md, SECURITY.pt-BR.md
  • docs/AGENTS.pt-BR.md — guia imperativo para LLMs em português
  • docs/AGENTS-GUIDE.md + docs/AGENTS-GUIDE.pt-BR.md — guia persuasivo bilíngue
  • llms.txt — arquivo compacto de orientação para LLMs (< 50 KB)
  • llms-full.txt — concatenação completa de docs para contexto longo de LLMs
  • eval-queries.json × 2 — 20 queries de avaliação EN + 20 PT-BR para skill testing

Changed

  • README.md — link para README.pt-BR.md + quick install antes da linha 30
  • CONTRIBUTING.md — MSRV Rust 1.75 explícito + PR checklist 8 itens + branching strategy + nextest
  • SECURITY.md — tabela de versão específica v0.6.2 + política de embargo 90 dias + zero bold + zero emojis
  • skill/SKILL.md (EN+PT) — seção Workflow com 5 passos numerados verificáveis

[0.6.1] - 2026-04-17

Fixed

  • --timeout 0 now returns exit 2 (invalid config) instead of executing a search with zero timeout and returning exit 5.
  • --output /tmp/../../etc/passwd now returns exit 2 (invalid config) instead of exit 1 (runtime OS error) — path traversal validation moved to montar_configuracoes(), before the pipeline starts.

Added

  • validar_timeout_segundos() method on CliArgs — rejects values of 0 with a descriptive error.
  • Early path traversal check in montar_configuracoes() — calls paths::validate_output_path() at config validation time, not at write time.
  • 2 E2E regression tests: timeout_zero_retorna_exit_2 and output_com_path_traversal_retorna_exit_2.
  • 1 unit test: validar_timeout_segundos_rejeita_zero.

[0.6.0] - 2026-04-16

Security

  • Browser fingerprint profiles per-family previnem detecção anti-bot do DuckDuckGo.
  • Headers Sec-Fetch-* e Client Hints por família imitam sessão de navegador real.
  • Accept-Language com q-values RFC 7231 elimina fingerprint de UA genérico.
  • Detecção de bloqueio silencioso com limiar de 5 KB previne resultados truncados.

Added

  • BrowserFamily enum — variantes Chrome, Firefox, Edge, Safari.
  • BrowserProfile struct — encapsula família, versão e conjunto de headers por família.
  • Headers Sec-Fetch-Dest, Sec-Fetch-Mode, Sec-Fetch-Site por família em http.rs.
  • Client Hints (Sec-Ch-Ua, Sec-Ch-Ua-Mobile, Sec-Ch-Ua-Platform) para Chrome e Edge.
  • Detecção de HTTP 202 anomaly em search.rs com backoff exponencial automático.
  • Detecção de bloqueio silencioso — resposta com menos de 5 000 bytes é tratada como bloqueio.
  • BrowserProfile propagado via Config para todos os módulos da pipeline.
  • Headers de paginação com Sec-Fetch-Site: same-origin para imitar navegação real.

Changed

  • Accept-Language atualizado para pt-BR,pt;q=0.9,en-US;q=0.8,en;q=0.7 conforme RFC 7231.
  • Accept header agora reflete o perfil completo do browser por família.
  • Delays de paginação aumentados de 500–1 000 ms para 800–1 500 ms.
  • Limiar de bloqueio silencioso aumentado de 100 para 5 000 bytes.

[0.5.0] - 2026-04-16

Security

  • Path traversal validation on --output — rejects .. components and writes to system directories (/etc, /usr, C:\Windows).
  • Proxy credential masking — error messages no longer expose passwords from --proxy http://user:pass@host URLs.

Added

  • src/paths.rs — centralized path validation, parent directory creation, and Unix permission application.
  • src/signals.rs — centralized SIGPIPE restoration (Unix) and Ctrl+C/SIGINT handler (cross-platform).
  • ErroCliDdg enum with thiserror — 11 typed error variants with exit_code() and codigo_erro() methods.
  • mascarar_url_proxy() in http.rs — redacts credentials from proxy URLs in error context.
  • 21 new unit tests across paths.rs, signals.rs, error.rs, and http.rs.

Changed

  • thiserror = "2" added to dependencies for structured domain errors.
  • src/main.rs reduced from 63 to 23 lines — signal handling extracted to signals.rs.
  • src/output.rs file writes now validate paths via paths::validate_output_path() before I/O.
  • deny.toml updated with RUSTSEC-2026-0097 exception (rand 0.8 unsound with custom logger — not applicable).

[0.4.4] - 2026-04-16

Fixed

  • SIGPIPE restored to SIG_DFL on Unix — pipes to jaq, head, and other consumers no longer lose stdout silently.
  • BrokenPipe errors detected in anyhow chain and treated as exit 0 (not exit 1) at all output boundaries.

Added

  • --help now shows EXIT CODES (0–5) and PIPE USAGE sections via after_long_help.
  • 3 E2E tests for pipe regression: exit codes in help, short help exclusion, stdout byte count.
  • README troubleshooting item 7: "Pipe to jaq/jq returns empty" with PIPESTATUS diagnostic (EN + PT).
  • docs_rules/rules_rust.md: SIGPIPE + BrokenPipe added to I/O checklist.
  • docs/AGENT_RULES.md: R24 pipe safety rule with PIPESTATUS diagnostic.
  • docs/COOKBOOK.md: Recipe 16 pipe diagnostic (EN + PT).
  • docs/INTEGRATIONS.md: pipe safety clause in baseline contract.
  • Exit code branching section in both skill files (EN + PT).

[0.4.3] - 2026-04-15

Changed

  • README.md — Nova seção persuasiva "Agent Skill" (EN + PT) posicionada
    entre a tabela de agentes e a seção de Documentação, no pico de atenção do
    leitor. Copywriting AIDA destacando a skill bilíngue empacotada em skill/:
    auto-ativação semântica sem slash command, 14 seções canônicas MUST/NEVER,
    contrato JSON anti-alucinação, economia de tokens em cada turno de busca,
    instalação em um comando (git clone + cp -r). Benefícios explícitos para
    LLMs (decisão automática de quando buscar) e desenvolvedores (zero prompt
    engineering, zero tool registration). Tarball do crates.io inalterado —
    skills continuam vivendo apenas no GitHub.

[0.4.2] - 2026-04-15

Added

  • skill/duckduckgo-search-cli-pt/SKILL.md e
    skill/duckduckgo-search-cli-en/SKILL.md — Skills bilíngues para Claude
    Code, Claude Agent SDK e plataformas compatíveis com Agent Skills. Cada
    skill traz frontmatter YAML com name único por idioma e description
    carregado de triggers semânticos para auto-invocação, além de 14 seções
    H2 canônicas (Missão, Contrato de Invocação, Proibições Absolutas,
    Parsing com jaq, Schema JSON, Exit Codes, Batch, Fetch-Content,
    Endpoint, Retries, Receitas, Validação, Memória, Regra de Ouro).
    Publicadas no GitHub, excluídas do tarball do crates.io.

Changed

  • docs/AGENT_RULES.md (833 linhas, +7,6%) — Reescrita editorial
    aplicando copywriting AIDA: cada regra abre com benefício mensurável,
    linguagem imperativa MUST/NEVER reforçada, zero narrativa decorativa,
    zero negrito com asteriscos duplos, zero separador visual --- entre
    seções. Bilíngue EN+PT espelhado com tom idêntico.
  • docs/COOKBOOK.md (1082 linhas, −3,1%) — Cada receita abre com o
    ganho concreto antes do comando, bullets curtos de 8 a 15 palavras,
    pipelines jaq + xh + sd preservados intactos.
  • docs/INTEGRATIONS.md (1212 linhas, +1,3%) — 16 agentes com tabela
    comparativa textual, snippets determinísticos por agente, zero emoji.

Meta

  • Cargo.toml exclude ampliado para cobrir skill/ e skill/** — skills
    ficam no GitHub e fora do tarball publicado em crates.io.

[0.4.1] - 2026-04-14

Added

  • docs/AGENT_RULES.md (773 linhas) — Regras imperativas bilíngue (EN+PT)
    com 30+ rules MUST/NEVER (R01..R30) para LLMs/agentes invocarem a CLI
    em produção. Cobre: invariantes core, contrato JSON, rate limiting, error
    handling, performance, segurança, anti-patterns. Quick Reference Card no
    final.
  • docs/COOKBOOK.md (1117 linhas) — 15 receitas copy-paste bilíngue
    combinando duckduckgo-search-cli + jaq + xh + sd para casos reais:
    research consolidado, ETL multi-query, extração de domínios, monitoramento
    com filtro temporal, content extraction com --fetch-content, comparação
    top 5 vs top 15, NDJSON para pipelines, function wrappers para bash.
  • docs/INTEGRATIONS.md (1196 linhas) — Snippets prontos para 16
    agentes/LLMs: Claude Code, OpenAI Codex, Gemini CLI, Cursor, Windsurf,
    Aider, Continue.dev, MiniMax, OpenCode, Paperclip, OpenClaw, Google
    Antigravity, GitHub Copilot CLI, Devin, Cline, Roo Code. Cada agente
    documenta: pitch, mecanismo de shell, setup, snippet básico, snippet
    multi-query, system prompt rule, caveats.
  • Seção Documentation no README.md (EN + PT) linkando os 3 guias.

Fixed

  • README.md badge cluster e referências internas conferidas contra
    daniloaguiarbr/duckduckgo-search-cli (repo canônico).

[0.4.0] - 2026-04-14

Changed (BREAKING)

  • Default de --num / -n: alterado de "todos os resultados da primeira
    página" (~11) para 15, com auto-paginação automática. Quando o
    número efetivo excede 10, o binário agora busca 2 páginas por query
    para satisfazer o teto solicitado, desde que --pages não tenha sido
    customizado pelo usuário.
  • Auto-paginação automática: se --num > 10 (seja porque o usuário
    passou explicitamente ou porque o default 15 foi aplicado) E --pages
    não foi customizado (continua no default 1), o binário auto-eleva
    --pages para ceil(num/10) respeitando o teto de 5 páginas validado
    por validar_paginas. Impacto: mais requests por query (2x no caso
    default) e latência marginalmente maior, porém com cobertura completa
    dos resultados solicitados.

Added

  • Documentação no comentário do flag --num em cli.rs descrevendo a
    nova semântica de default e auto-paginação.
  • 4 novos testes unitários em lib.rs::testes:
    montar_configuracoes_aplica_default_num_15_quando_omitido,
    montar_configuracoes_respeita_pages_explicito_acima_de_1,
    montar_configuracoes_auto_pagina_quando_num_maior_que_10,
    montar_configuracoes_nao_auto_pagina_quando_num_10_ou_menos.
  • 2 novos testes wiremock em tests/integracao_wiremock.rs:
    testa_default_num_15_auto_pagina_2_paginas,
    testa_auto_paginacao_respeita_pages_explicito.

Migration Guide

  • Quem quer o comportamento antigo (1 página, ~11 resultados):
    passe --pages 1 --num 10 explicitamente. O --pages 1 explícito é
    indistinguível do default (trade-off aceito: paginas > 1 é o único
    sinal de "customização"), então o mais seguro é combinar com --num 10
    para garantir que nada será auto-paginado.
  • Quem já passava --num 5 (ou qualquer valor <= 10): comportamento
    inalterado (sem auto-paginação, 1 página).
  • Quem já passava --num 20 --pages 2 ou similar: comportamento
    inalterado (respeita explícito do usuário).
  • Quem confiava no default sem flags: agora recebe até 15 resultados
    em vez de ~11, com 1 request extra por query. Para restaurar o antigo,
    passe --pages 1 --num 10.

[0.3.0] - 2026-04-14

Changed (BREAKING)

  • Schema JSON: campo buscas_relacionadas REMOVIDO de SearchOutput e
    MultiSearchOutput.buscas[i]. O endpoint html.duckduckgo.com/html/ não
    expõe related searches no DOM atual; manter o campo sempre vazio era ruído.
    Pipelines que parseavam .buscas_relacionadas precisam ajuste.
  • Pool de User-Agents: removidos UAs de browsers de texto (Lynx 2.9.0,
    w3m/0.5.3, Links 2.29, ELinks 0.16.1.1) que faziam DuckDuckGo retornar
    HTML degradado. Substituídos por 6 UAs modernos validados empiricamente
    contra o /html/ endpoint: Chrome 146 (Win/Mac/Linux), Edge 145 Windows,
    Firefox 134 Linux, Safari 17.6 macOS. Firefox Win/Mac foram REMOVIDOS após
    retornarem HTTP 202 anomaly em validação real (heurística anti-bot do DDG).

Fixed

  • Snippet duplicava título e URL no início: o seletor padrão tinha
    fallback .result__body (container pai) que fazia text() recursivo
    capturar título+URL+snippet concatenados. Trocado por .result__snippet
    puro. Pipelines como jaq '.resultados[].snippet' agora retornam apenas
    o texto descritivo do resultado.
  • Título "Official site": DuckDuckGo renderiza literalmente este texto
    como label para domínios verificados (ex: prefeituras). O scraper agora
    detecta este caso e substitui pelo url_exibicao (ex: saofidelis.rj.gov.br).
    O texto original é preservado no novo campo opcional titulo_original
    para auditoria.

Added

  • Campo titulo_original: Option<String> em SearchResult. Presente
    apenas quando o título foi substituído por heurística (atualmente: caso
    "Official site"). Serializado com #[serde(skip_serializing_if = "Option::is_none")]
    — não aparece no JSON quando ausente.
  • Resultados patrocinados (.result--ad) excluídos do container default
    via seletor .result:not(.result--ad).

Removed

  • Função extrair_buscas_relacionadas em src/search.rs (dead code com
    seletor hardcoded que nunca encontrava nada).
  • Seção [related_searches] em selectors default.

Migration Guide (v0.2.x → v0.3.0)

  • Pipelines jaq '.buscas_relacionadas[]': campo não existe mais.
    Remover do filtro ou tratar null.
  • Esperando snippet com prefixo título+URL? Agora vem só o texto descritivo
    — ajuste regex/parsing downstream se necessário.
  • Confiando em titulo == "Official site" para detectar sites verificados?
    Use titulo_original.as_deref() == Some("Official site").
  • CONFIG EXTERNO LEGADO: usuários que rodaram init-config em versões
    anteriores possuem ~/.config/duckduckgo-search-cli/{selectors,user-agents}.toml
    com defaults antigos (snippet com .result__body + UAs Lynx/w3m/etc.).
    Esses arquivos OVERRIDE os defaults embutidos. Para aplicar as correções
    desta versão, execute APÓS atualizar: 
    duckduckgo-search-cli init-config --force
    O flag --force sobrescreve os arquivos externos. Backup recomendado se
    você editou manualmente para hotfix de seletores.

[0.2.0] - 2026-04-14

Changed (BREAKING)

Schema JSON serializado agora usa nomes de campo em português brasileiro,
alinhado com os exemplos jaq do README e com o invariante INVIOLÁVEL do
blueprint v2 do projeto ("Logs e nomes de campo em português brasileiro").

Pipelines que dependiam do schema em inglês da v0.1.0 precisam atualizar
os seletores jaq. Tabela de renomeações:

Antes (v0.1.0) Depois (v0.2.0)
position posicao
title titulo
displayed_url url_exibicao
content conteudo
content_length tamanho_conteudo
content_extraction_method metodo_extracao_conteudo
execution_time_ms tempo_execucao_ms
selectors_hash hash_seletores
retries retentativas
fallback_endpoint_used usou_endpoint_fallback
concurrent_fetches fetches_simultaneos
fetch_successes sucessos_fetch
fetch_failures falhas_fetch
chrome_used usou_chrome
proxy_used usou_proxy
engine motor
region regiao
results_count quantidade_resultados
results resultados
related_searches buscas_relacionadas
pages_fetched paginas_buscadas
error erro
message mensagem
metadata metadados
queries_count quantidade_queries
parallel paralelismo
searches buscas

Campos inalterados: url, snippet, query, endpoint, timestamp, user_agent.

Fixed

  • Pipelines documentados no README (jaq '.resultados[].titulo', etc.) agora
    funcionam end-to-end. Em v0.1.0 retornavam null por divergência do schema
    (bug reportado pelo usuário).

Unreleased

Added

  • LICENSE-MIT and LICENSE-APACHE (dual-licensed per Cargo.toml, aligning the tarball with the SPDX declaration).
  • .pre-commit-config.yaml with three hook groups: (1) pre-commit-hooks standard (trailing whitespace, EOF, YAML/TOML validity, mixed line endings), (2) Rust hooks (cargo fmt + cargo clippy -D warnings), (3) local commit-msg hook blocking Co-authored-by: from AI agents (mirrors the CI commit_check job). Reduces CI round-trips for trivial violations.
  • .gitattributes forcing LF on .rs / .toml / .sh / .yml / .md / fixture HTML — prevents silent corruption when cloning on Windows with core.autocrlf=true (which would otherwise break shebangs, rustfmt, and content-extraction tests). Binary extensions (.png, .woff2, etc.) marked explicitly. Cargo.lock and target/ flagged linguist-generated to exclude from GitHub language stats.
  • .editorconfig normalizing UTF-8, LF, trailing-whitespace trim, and per-language indent (Rust/TOML 4, YAML/JSON/MD 2, Makefile tab) across VS Code, RustRover, vim, and other editors — eliminates spurious formatting diffs caused by per-dev settings drift.
  • .github/PULL_REQUEST_TEMPLATE.md with the 10-gate checklist + project-specific constraints (no cache, no MCP, rustls-only, println! confined to output.rs, PT-BR identifiers).
  • .github/ISSUE_TEMPLATE/bug_report.yml + feature_request.yml + config.yml — structured triage with platform dropdown (glibc/musl/NixOS/Flatpak/Snap/macOS ARM/macOS Intel/Windows/WSL), install method, and constraint verification. config.yml redirects security reports to Security Advisories and usage questions to Discussions.
  • Cross.toml enabling cross build --target <t> for ARM64/ARMv7 Linux targets (musl + glibc + hard-float) from any x86_64 host with Docker/Podman — complements the native CI pipeline for developers without a GitHub Actions runner.
  • CONTRIBUTING.md with the 10-gate validation matrix, coding standards (Brazilian Portuguese identifiers, rustls-only TLS, output.rs as the sole println! site), three-layer testing strategy, supply-chain guardrails, and the tag-driven release process.
  • .cargo/config.toml exposing 8 developer aliases (cargo check-all, cargo lint, cargo docs, cargo test-all, cargo cov, cargo cov-html, cargo publish-check, cargo pkg-list) — each mirrors a CI job for local reproduction.
  • Doctests in public API: pipeline::combine_and_dedup_queries, content_fetch::extract_host, and search::format_kl — compilable examples on docs.rs that double as regression tests.
  • SECURITY.md documenting the private-disclosure workflow via GitHub Security Advisories, response SLA (72 h), scope (HTTP/HTML parsing, credential leaks, path traversal, TLS) and security design assumptions (stateless, rustls-only, no JS for search).
  • .github/dependabot.yml enabling weekly automatic dependency updates for both cargo and github-actions ecosystems, with semantic grouping (dev-deps, tokio-ecosystem, tracing-ecosystem) and PR count limits.
  • rust-toolchain.toml pinning stable with rustfmt + clippy components for reproducible dev/CI builds.
  • .github/workflows/release.yml triggered by v*.*.* tags (and workflow_dispatch with dry_run) running the 5-stage release pipeline per rules_rust.md §19: validate → build_matrix (5 targets) → macos_universal (lipo) → github_release (with generated notes) → crates_io (publish gated on CRATES_IO_TOKEN secret).
  • msrv job in ci.yml extracting rust-version from Cargo.toml and running cargo check on that toolchain to detect MSRV drift on every PR.
  • .github/workflows/ci.yml enforcing the 10-gate validation matrix across Ubuntu, macOS, and Windows:
    • cargo check / clippy -D warnings / fmt --check / doc -D warnings / test --all-features on all three OSes.
    • cargo llvm-cov --fail-under-lines 80 dedicated job on Ubuntu.
    • cargo audit + cargo deny check advisories licenses bans sources supply-chain gate.
    • cargo publish --dry-run + cargo package --list sensitive-file guard.
    • Static musl binary smoke test (x86_64-unknown-linux-musl) covering Alpine Linux and minimal containers.
    • commit_check job blocking Co-authored-by: trailers from AI agents in PRs.
  • deny.toml with full four-axis supply-chain policy (advisories/licenses/bans/sources) and documented ignores for three transitive unmaintained advisories (RUSTSEC-2025-0057 fxhash, RUSTSEC-2025-0052 async-std, RUSTSEC-2026-0097 rand) with justification and revisit notes.
  • 22 new tests raising coverage from 77.4% to 86.4% (lines): tests/integration_pipeline.rs (10), tests/integracao_fetch_conteudo.rs (3), and 9 inline tests for output.rs covering emit_ndjson, emit_stream_text, emit_stream_markdown, and the PipelineResult variants via tempfile.

Changed

  • parallel.rs coverage 50% → 81%; pipeline.rs 55% → 82%; content_fetch.rs 68% → 85%; output.rs 70% → 87%.

0.1.0 - 2026-04-14

Added

  • Core search pipeline against DuckDuckGo HTML endpoint via pure HTTP (html.duckduckgo.com/html/).
  • Lite endpoint fallback via --endpoint lite for JavaScript-less pages.
  • Multi-query mode with automatic deduplication, positional args, --queries-file, and stdin.
  • Parallel fan-out of queries with --parallel (1..=20), bounded by tokio::JoinSet + Semaphore.
  • --pages (1..=5) to collect multiple result pages per query.
  • --fetch-content fetches each result URL via pure HTTP, applies readability, and embeds the cleaned text in the JSON output.
  • --max-content-length (1..=100_000) truncates extracted content respecting word boundaries.
  • Chrome headless fallback under --features chrome with cross-platform detection (Linux including Flatpak/Snap, macOS including Apple Silicon, Windows including registry paths) and stealth flags (--disable-blink-features=AutomationControlled, --window-size=1920,1080, --no-first-run, platform-specific --no-sandbox, --disable-gpu).
  • --chrome-path flag to manually specify the Chrome/Chromium executable.
  • --proxy URL + --no-proxy (HTTP/HTTPS/SOCKS5) with precedence over env vars.
  • --global-timeout (1..=3600 s) wraps the whole pipeline in tokio::time::timeout.
  • --per-host-limit (1..=10) rate-limits fetches per host via a per-host Semaphore map.
  • --match-platform-ua narrows the user-agent pool to the current platform.
  • --stream NDJSON mode emits one result per line as they are extracted.
  • Four output formats: json (default), text, markdown, auto (TTY-aware).
  • External configuration files: selectors.toml and user-agents.toml under XDG config dir, overriding embedded defaults.
  • Subcommand init-config with --force and --dry-run to bootstrap user config files.
  • Exit codes: 0 success, 1 runtime, 2 config, 3 block (HTTP 202 anomaly), 4 global timeout, 5 zero results.
  • UTF-8 console initialization on Windows via SetConsoleOutputCP(65001).
  • Rustls-TLS everywhere for dependency-free cross-platform builds.
  • tracing + tracing-subscriber with RUST_LOG honored; --verbose / --quiet flags.
  • 163 unit + integration tests covering CLI parsing, config montage, HTTP extraction, parallel fan-out, selectors, and wiremock-backed search flows.

Security

  • All credentials (--proxy user:pass@host) are masked in logs.
  • Output file creation applies Unix permissions 0o644.
Assets 2
Loading