feat(completions): print snippet to stdout instead of writing to dotfiles

[sachiniyer]

Summary

• detail completions [SHELL] now prints the activation snippet (eval ... / source <(...) / etc.) to stdout and exits, instead of appending it to a chosen rc file.
• Users wire it up however they want — e.g. source <(detail completions bash) in .bashrc, or copy the line into .bash_profile for login shells. This sidesteps the .bashrc-vs-.bash_profile login-shell question entirely (issue [Detail Bug] CLI Completions: Bash login shells don't load installed completions when both .bashrc and .bash_profile exist #267).
• Same pattern as kubectl completion, gh completion, terraform -install-autocomplete peers — well-trodden territory and easy to document.
• SHELL is an optional positional arg; default is still auto-detected from $SHELL. Supported shells unchanged: bash, zsh, fish, elvish, powershell.
• Completions is now is_silent() == true so the auto-update notice on stderr doesn't fire every time a shell rc file evaluates source <(detail completions bash) at startup.

Closes #267. Supersedes #288 (which tried a rustup-style multi-file install — closed in favour of this simpler pattern).

Migration

If you previously ran detail completions and it appended a # Detail CLI shell completions block to your rc file, you can leave it in place (the snippet is identical) or delete it and re-wire via source <(detail completions bash) instead.

Test plan

• cargo fmt --check
• cargo clippy -- -D warnings (matches CI)
• cargo test — 290 lib + 18 integration passing, including new print_snippet_* tests and the silent_for_completions / completions_*shell_arg parser tests
• cargo xtask check-help — docs/HELP.md regenerated and in sync
• Manual: cargo run -- completions bash prints eval "\$(COMPLETE=bash detail 2>/dev/null)" to stdout

🤖 Generated with Claude Code

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/commands/completions.rs">

<violation number="1" location="src/commands/completions.rs:110">
P2: This test mutates the global `SHELL` environment variable without synchronization, which can race with other tests and cause flaky results in parallel test runs.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9e9f87cd89

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Correct the cross-shell completion example

This help text tells users to add the bash-specific invocation to any rc file, including .zshrc; in a zsh/fish/powershell setup that command still prints the bash activation snippet (COMPLETE=bash), so users following the generated help install the wrong completion script or a syntax that their shell cannot source. Please make the example shell-specific or use the auto-detected form where appropriate.

Useful? React with 👍 / 👎.

[sachiniyer]

Addressed both review comments in 127e4a8:

cubic (P2, completions.rs:110) — agreed, fixed. The new print_snippet_uses_detected_shell_when_none test mutated $SHELL and would race with the existing detect_shell_from_env test under parallel cargo test. Restructured so print_snippet takes a resolved &str and handle() is the only caller of detect_shell() — no env mutation needed for the helper, racy test deleted. detect_shell_from_env is now the single test that touches $SHELL, so there's nothing to race against.

codex (P2, lib.rs:147) — agreed, fixed. The old example mixed source <(detail completions bash) with "add to .bashrc, .zshrc, etc.", which would have a zsh user sourcing the bash snippet. Replaced with shell-specific lines for bash, zsh, fish, and powershell (each pointing at the right rc file with the right invocation). Had to move the help into a COMPLETIONS_LONG_ABOUT constant — clap collapses line breaks inside /// doc-comment paragraphs, so the previous /// formatting rendered as one mashed-together line in --help. The constant approach mirrors the existing top-level LONG_ABOUT.

cargo fmt, cargo clippy -- -D warnings, cargo test (289 lib + 18 integration), and cargo xtask check-help all green.