Add zsh, bash and fish tab completion to the privacycommand CLI

[adamXbot]

Why

The privacycommand CLI (#28) had no tab completion. This adds it for zsh (macOS's default shell), bash and fish. Homebrew installs set it up automatically, and everyone else adds one line to their shell's startup file.

What changes

privacycommand completion <zsh|bash|fish> prints a completion script. Its --help lists the line to add for each shell. For zsh, in ~/.zshrc after compinit:

eval "$(privacycommand completion zsh)"

The scripts are generated from command tables in privacycommandCLIKit/ShellCompletion.swift, so all three complete the same things:

• subcommands (with descriptions in zsh and fish) and the top-level options.
• installed app names: the same top-level *.app names in /Applications, ~/Applications and /System/Applications that privacycommand <name> matches. Names with spaces are escaped. Directories complete too.
• audit options after audit <app> or a bare <app>.
• preview options, --min-tier levels, --apps-dir directories, and the outdated cask tokens from brew outdated --cask.
• the shell names after completion.

The zsh script works both autoloaded from fpath and eval'd from ~/.zshrc. The bash script works with macOS's bash 3.2: it avoids compopt and relies on complete -o filenames for escaping.

Bundled for Homebrew. The Embed command-line tool phase writes the three scripts to Contents/Resources/completions. The cask links them with bash_completion, zsh_completion and fish_completion. Those stanzas need Homebrew 4.4.24 (March 2025) or later. I avoided the newer generate_completions_from_executable, which older Homebrew can't parse. brew style reports no new offences; the two it flags were already there.

A macOS quirk this hit. The first run of a binary from inside a freshly built .app silently loses whatever it writes into that same bundle. Swift's print ignores the failed writes, so it still exits 0. Generating with the embedded copy left _privacycommand empty on every fresh build. The phase now generates with the identical SwiftPM build output and copies the files in, and it fails the build if any script comes out empty.

This doesn't affect users: their output goes to the terminal or to files outside the app. I reproduced it outside Xcode and confirmed the same binary run from outside the bundle writes fine.

Docs.

• The Install Command Line Tool… success alert, README, in-app manual, CONTRIBUTING and the source-tree README describe completion setup.
• CONTRIBUTING tells contributors to add new subcommands and flags to the completion tables. This matters for the in-flight upgrade/--greedy work.
• While there, README and CONTRIBUTING stop claiming preview "never runs brew" and "always exits 0". It runs read-only brew queries and exits 2 on usage errors or missing Homebrew.
• CONTRIBUTING's --min-tier warn example, which exits 2, now uses high.

Verification

• swift test: 290 Core tests (4 skipped, as before) and 52 CLI-kit tests (5 new), 0 failures. ShellCompletionTests checks that:
  • every table entry reaches every shell.
  • zsh -n and bash -n accept the scripts (fish -n too, when fish is installed).
  • bash completes subcommands, options, tiers and shells correctly for fixed inputs.
• zsh, driven interactively through a pty, both from fpath and via eval after compinit:
  • lists subcommands, app names and directories.
  • prev→preview, preview --f→--fetch, --min-tier → the four tiers.
  • completion b→bash, Calc→Calculator, Calculator --s→--short.
• bash 3.2 (/bin/bash): subcommands plus app names with spaces (App S→App Store), preview options, tiers, --apps-dir directories, and audit options after a bare app name.
• Fresh xcodebuild bundles, signed (ad-hoc) and unsigned, universal: all three files are present and byte-identical to privacycommand completion <shell>, and the signed bundle passes codesign --verify --deep --strict.
• just lint passes.

Not verified

• fish isn't installed on this Mac. Its script uses long-standing helpers (__fish_use_subcommand, __fish_seen_subcommand_from, __fish_complete_directories), and the content test covers it, but it hasn't been run.
• A real brew install --cask with the new stanzas needs a release.

🤖 Generated with Claude Code