docs: add bash and zsh autocompletion recipe - #215

Summary

Closes #200 — adds a bash and zsh shell autocompletion recipe to docs/reference/cli/README.md.

docs/reference/cli/README.md documented every ranu subcommand and flag but had no autocompletion recipe, so macOS and Linux developers had to memorise flags or fall back to ranu help.

What was added

A new §5 Shell Autocompletion section containing:

• §5.1 Bash — a ~60-line compgen-based completion script, registered for both ranu and the ranujs alias. Handles value-taking flags (--root completes directories, --adapter completes vercel / @ranujs/adapter-vercel, --port/--host complete nothing), per-subcommand flag sets, and a bare - offering only short flags.
• §5.2 Zsh — an _arguments/_describe widget with descriptions for every command and flag, plus a note that compinit must run before the file is sourced (so it cannot live in ~/.oh-my-zsh/completions).
• §5.3 Verification — the complete -p ranu / whence -w _ranu checks a reader can run to confirm the script loaded, and the exact expected output of pressing Tab.
• Per-platform install steps: Linux (via bash-completion, or explicitly sourced), macOS system bash 3.2 (which ships no completion loader, so it must be sourced from ~/.bash_profile), and Homebrew bash.

Flag sets are derived from the real CLI, not guessed

The repo does not use commander or yargs — it has a hand-rolled parser in packages/cli/src/args.ts and per-command help text in packages/cli/src/commands/help.ts. Each completion set mirrors ranu help <command> exactly:

Two details worth noting, both taken from source rather than assumption:

• --host's shorthand is -h, not --help — an easy trap for a completion script to get wrong.
• --port, --host, --root, --adapter and --open are parsed globally, but help.ts documents --open only for dev and --adapter only for deploy. The scripts follow the documented per-command surface rather than the parser's laxer global behaviour, so the suggestions match what ranu help <cmd> tells the user.

ranu help <TAB> completes the seven subcommand names, matching runHelpCommand.

Testing — both scripts were actually executed

Not just written; both were run against real completion systems:

• bash (32/32 passing) — a harness sets COMP_WORDS/COMP_CWORD and calls _ranu directly, asserting COMPREPLY for subcommand completion, prefix filtering (--p → --port, --por → --port, --po on build → nothing), value-position behaviour, ranu help b → build, and flags after an already-typed --clean.
• zsh (8/8 passing) — a genuine interactive zsh -f -i inside a socat-allocated pty. compinit runs, _ranu is compdef'd, a literal Tab is sent, and the completions the real zsh completion system prints on screen are parsed and compared per subcommand.

Both bugs the tests caught were fixed rather than papered over: the zsh widget originally offered the full flag set at root level and for help/version, and build lost its --clean during a refactor. The scripts embedded in the README are byte-identical to the tested ones (verified by diffing the extracted code blocks).

Both shells also pass syntax checks (bash -n, zsh -n).

Checks

• node scripts/sync-docs-version.mjs --check → passes.
• Prettier: §5 alone is clean (prettier --check on the isolated section passes). Sections 1–4 of this file were already non-compliant on main — I verified this on the stashed baseline — so I deliberately did not reformat them, which would have turned a 244-line additive docs change into an unrelated whole-file reformat.
• Documentation-only change: no changeset needed per CONTRIBUTING.md.

Left for the maintainer

• The completion is opt-in per-developer (sourced from a shell profile), which keeps the repo free of new package files. If you would rather @ranujs/core ship a completions/ directory consumed by a loader, that is a package-layout change and a different issue.
• The zsh --host entry uses (-h --host), so -h expands to --host. That matches the CLI, but if the project ever wants the conventional -h = --help, the CLI parser needs to change first.
• Verified on Linux bash 5.2 and zsh 5.9. Not run on macOS — the macOS instructions follow the documented behaviour of system bash 3.2 and Homebrew bash, but I had no macOS host to confirm against.