Skip to content

v0.3.0 — Shell completion (bash, zsh, fish)

Choose a tag to compare

View all tags
@Juliocbm Juliocbm released this 24 May 15:00
v0.3.0
5bf38f0

Second minor release. New top-level command — beacon completion <shell> — that prints a TAB-completion script for bash, zsh, or fish.

✨ beacon completion <shell>

Install once per shell:

# bash (Linux, Git Bash on Windows)
beacon completion bash > ~/.local/share/bash-completion/completions/beacon

# zsh (macOS default since 2019)
beacon completion zsh > "${fpath[1]}/_beacon"
# then: autoload -U compinit && compinit

# fish
beacon completion fish > ~/.config/fish/completions/beacon.fish

Then everything is TAB-completable:

$ beacon <TAB>
archive  completion  disable  doctor  enable  init  lint  new  sync

$ beacon doctor --explain <TAB>
backlog-balance  old-evaluations  proposed-adrs  stale-plans

$ beacon enable <TAB>
business  compliance  integrations  modules  operations  roadmaps

$ beacon init --type <TAB>
backend-service  cli-tool  custom  library  mobile-app  monorepo  web-app

$ beacon archive plan <TAB>          # reads docs/plans/ in your current project!
billing-integration  refactor-auth  shipping-v2

What gets completed

Surface Static Source
Top-level commands ✅ hardcoded
Per-command flags ✅ hardcoded
--type, --agents, --with, --without values ✅ from core/project-types.ts
lint --explain <rule> rule names ✅ from linter/rule-docs.ts
doctor --explain <check> check names ✅ from doctor/check-docs.ts
enable <addon> / disable <addon> ✅ from add-on registry
archive plan <slug> 🔄 dynamic ls docs/plans/*.plan.md inline
archive roadmap <slug> 🔄 dynamic ls docs/roadmaps/*.roadmap.md inline

Typo correction for the shell name itself: beacon completion bsh → "Did you mean bash?"

🏗️ Architecture

  • Single source-of-truth schema in src/completion/schema.ts feeds three idiomatic shell generators (bash compgen -W, zsh _values with name:description, fish complete -c -n).
  • Static, not callback-based — no Node startup latency per TAB press. The 100ms cold-start cost would feel broken; embedding lists at script-generation time keeps completion instant. Tradeoffs are documented in ADR-009.
  • 29 new unit tests grep-assert each shell's script for expected words to detect schema drift. Test suite at 255 passing across 42 files.

Install / upgrade

npm install -g beacon-docs@0.3.0
# then:
beacon completion <your-shell> > <path-from-table-above>

Full changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md

Assets 2
Loading