feat(completions): add bash, zsh, and fish shell completions for mgw CLI

[snipcodeit]

Summary

• Adds completions/mgw.bash, completions/mgw.zsh, and completions/mgw.fish — hand-authored completion scripts covering all 12 subcommands and their flags
• Adds bin/generate-completions.cjs — a programmatic generator that rebuilds all three scripts from a single command-definition object, keeping completions in sync as the CLI evolves
• Bash completions use _mgw() + complete -F; zsh uses #compdef mgw with _arguments; fish uses complete -c mgw directives
• Global flags (--dry-run, --json, --verbose, --debug, --model) are wired to all subcommands; per-command flags handled individually

Closes #123

Milestone Context

• Milestone: v4 — Interactive CLI & TUI
• Phase: 29 — Shell Completions and Config Wizard
• Issue: 7 of 9 in milestone

Changes

completions/

• completions/mgw.bash — bash completion via _mgw() function with complete -F _mgw mgw; covers all subcommands, per-command flags, and --state/--assignee/--model value hints
• completions/mgw.zsh — zsh completion via #compdef mgw; uses _arguments -C with subcommand dispatch, _mgw_subcommands helper, and _mgw_issue_numbers that reads .mgw/active/*.json for live issue completion
• completions/mgw.fish — fish completion using complete -c mgw directives with __fish_use_subcommand and __fish_seen_subcommand_from guards; includes choice lists for --state, --limit, --assignee

bin/

• bin/generate-completions.cjs — Node.js generator script; defines COMMANDS and GLOBAL_FLAGS arrays as source-of-truth; exposes generateBash(), generateZsh(), generateFish() functions; CLI usage: node bin/generate-completions.cjs [--out-dir <dir>]

Test Plan

• source completions/mgw.bash then mgw <TAB> shows all 12 subcommands
• mgw run <TAB> shows --quiet, --auto, and global flags
• mgw issues --state <TAB> shows open closed all
• Zsh: copy completions/mgw.zsh to $fpath, run compinit, verify mgw <TAB> and subcommand flag completion
• Fish: copy completions/mgw.fish to ~/.config/fish/completions/, verify mgw <TAB> and per-subcommand flag suggestions
• node bin/generate-completions.cjs regenerates all three files into completions/ without errors
• node bin/generate-completions.cjs --out-dir /tmp/test writes to custom output directory

[snipcodeit]

Review: PR #167 — bash, zsh, and fish shell completions

The generator approach is the right design — single source-of-truth prevents drift. There are two blocking issues before this is ready to ship.

---

🔴 completions/ not in package.json files array

package.json has:

"files": ["dist/", "bin/mgw-install.cjs", "commands/", "templates/"]

completions/ is not listed. When the package is published to npm, the completion scripts will not be included. The init completion installer (PR #168) references require.resolve("mgw/package.json") to locate the completions directory — but if the completions are not in the published package, that lookup will fail for all npm-installed users.

Fix: add "completions/" to the files array in package.json.

---

🔴 Generated completion files not committed

The diff shows bin/generate-completions.cjs but the actual generated files (completions/mgw.bash, completions/mgw.zsh, completions/mgw.fish) do not appear in the diff. Are they committed to the branch? If not, the completions/ directory will be empty when the PR is merged, making the shell completion feature non-functional.

Run node bin/generate-completions.cjs and commit the output files.

---

🟡 No npm run completions script

There is no npm script to regenerate completions. Add to package.json:

"completions": "node bin/generate-completions.cjs"

This makes it easy for contributors to regenerate after adding commands. Could also add it to the build script.

---

🟡 Hardcoded model names may go stale

The bash/zsh completions offer claude-opus-4-5 claude-sonnet-4-5 claude-haiku-4-5 as model hints. The actual model IDs use versioned suffixes (e.g. claude-haiku-4-5-20251001). Using the shorter alias names for completion is fine — but document that these are display hints, not validated model IDs. If mgw already has a --model validation path, ensure it accepts both forms.

---

🟡 Bash completion uses _init_completion from bash-completion v2

_init_completion is provided by the bash-completion package (v2+). On macOS default bash (3.x) or systems without bash-completion installed, the function will be undefined and the completion will silently fail. Consider adding a fallback:

_init_completion 2>/dev/null || {
  COMPREPLY=()
  cur="${COMP_WORDS[COMP_CWORD]}"
  prev="${COMP_WORDS[COMP_CWORD-1]}"
}

---

✅ Good points

• Generator pattern is the right architecture — completions stay in sync with commands
• All 12 subcommands covered
• Per-command flags correctly scoped (not all flags shown for all commands)
• __fish_use_subcommand / __fish_seen_subcommand_from guards are correct fish idioms
• --state, --assignee, --model get value hint completions — exactly right
• Fish completions auto-load from ~/.config/fish/completions/ — no activation needed