feat(cli): shell completions — hidden completions subcommand + post-init hint (v3.2.19)

[kengio]

Summary

Last open item of the v3.3 batch (the other three shipped in v3.2.18 / #60). Adds shell completion support so the Homebrew formula can auto-install completions and npm/cargo users get a discovery path.

• Hidden onebrain completions <SHELL> subcommand — emits a completion script to stdout via clap_complete::generate() over Cli::command(). #[command(hide = true)] keeps it out of --help but still dispatchable (so the Homebrew formula's generate_completions_from_executable can call it). Supports all five shells clap_complete provides: bash · zsh · fish · powershell · elvish.
• Shell-aware optional hint after interactive onebrain init — detects the login shell from $SHELL and prints a copy-pasteable onebrain completions <detected> line (falls back to a <shell> placeholder + list when undetectable). Gated to exit_code == 0 && !yes && !structured_output so machine/JSON output stays clean. Lives in the CLI layer, not the fs lib.

Version: patch v3.2.19 (the command is hidden → no advertised surface → patch, not minor).

Out of scope (follow-up)

• Homebrew tap formula (generate_completions_from_executable) — separate PR in homebrew-onebrain, lands after v3.2.19 is released (the formula needs a released binary that carries the subcommand).

Testing

• Integration (tests/completions.rs): per-shell marker assertions (#compdef onebrain, _onebrain(), complete -c onebrain) — not snapshots (brittle across clap bumps) — unknown-shell rejection, and init --yes hint absence.
• Unit (commands::completions): login-shell detection (incl. bare-name, case-insensitive, trailing-slash/whitespace edge cases) + hint builder.
• Full suite: 582 passed, 1 ignored. Verified --help hides completions and completions zsh emits clean stdout (0 bytes stderr — banner is stderr-only, so brew-captured completion files won't be corrupted).

Design / plan

• Design: 01-projects/onebrain/cli/2026-05-29-shell-completions-design.md
• Plan: 01-projects/onebrain/cli/2026-05-29-shell-completions-plan.md
• 3-round review (spec / Rust quality / adversarial integration) — all approve; one consensus fix applied (login-shell detection robustness + edge-case tests).

🤖 Generated with Claude Code