feat: add shell completion (#132)

[bwl21]

Tab completion by calling ct back, not by generating a script

Reworked from the generated-script approach. ct completion zsh|bash|fish now prints a ~15-line hook that hands the command line back to ct on every Tab; candidates are computed live from the Commander tree of the binary that is actually installed. This repo owns no shell syntax — the zsh/bash/fish dialects come from omelette.

Why not a generated script. It has to be re-emitted whenever a command changes, it needs a hand-written emitter per shell (232 of the previous 338 lines were exactly that), and it structurally cannot offer candidates that depend on the user's files.

What the delegation buys.

• --env completes the environments this config repo declares in ct.envs.json
• ct state rm <type> <key> completes registry types and the keys actually under management, following the --env/--state already on the line
• --config, --state, --backup-dir complete from the filesystem
• plus static parity: commands, nested subcommands, options, enumerated option and argument values

Completion is offline by construction. It reads local, non-secret files and nothing else — no client, no token store, no prepareEnv. Every source is wrapped so a missing, malformed or slow file yields no candidates rather than an error or a hang: a completion that spills a stack trace into the command line is worse than one that offers nothing. The test suite mocks the session module to throw, so any route to the network fails CI.

Why omelette over @pnpm/tabtab. tabtab is the better-featured library, but it reads its hook templates off disk at runtime (path.join(__dirname, 'templates', …)). In the bun build --compile binaries this project releases, __dirname resolves to the build machine's node_modules, so ct completion zsh works on the CI runner and fails with ENOENT on every user's machine — verified by compiling a probe and removing node_modules. Our smoke tests would not have caught it, because they run on a checkout that has node_modules. omelette inlines its hooks as strings and has zero dependencies, so the same code path works from npm, from dist/, and from a standalone binary with no node_modules in sight.

The trade-off is no per-candidate description text in zsh: omelette uses compadd, tabtab would use _describe. Working standalone binaries win that trade.

omelette's maintenance status, accepted deliberately. Last release 0.4.17 in September 2021, last commit January 2022 — effectively frozen. Accepted because it is ~350 lines of MIT-licensed, dependency-free CommonJS whose entire job is emitting three static hook strings, so the realistic failure mode is "never gains a feature", not "breaks". If it ever does break, vendoring it is an afternoon's work and the licence allows it. The reasoning is recorded in src/completion/shell.ts rather than only here.

<shell> stays an explicit required argument. zsh and bash receive the same hook (it branches on compdef/complete itself); only fish differs. Detecting the shell from $SHELL would be unreliable and wrong whenever someone generates for a different shell on purpose.

Also: README install docs rewritten for the hook-based flow. The /reference/ and /reports/ .gitignore lines are dropped — they belong to #133.

Verification

• npm test — 828 passed, 5 skipped
• npm run typecheck, npm run lint, npm run format:check, npm run build
• node .github/scripts/docs-staleness.mjs — all pages current
• hooks checked with bash -n, zsh -n and fish -n (fish 4.8.1)
• driven end-to-end as live completions in bash and fish against a fixture config repo:
  ct plan --env <Tab> → dev prod, ct state rm --env dev campus <Tab> → the managed keys
• exercised from a bun --compile binary run outside any node_modules

Closes #132

[2000game]

Hey, ich habe hier direkt auf deinem Branch umgebaut statt lange zu kommentieren — sag Bescheid, wenn dir das zu weit ging. Dein ursprünglicher Commit e78e8f4 ist über das Force-Push-Ereignis in der Timeline weiter erreichbar.

Was mich am generierten Skript gestört hat

Von den 338 Zeilen in src/completion.ts waren 232 handgeschriebene Shell-Emitter, einer pro Shell. Die müssen wir dann dauerhaft pflegen, und sie müssen bei jeder Kommandoänderung neu ausgegeben werden. Der eigentliche Punkt ist aber: Ein statisches Skript kann prinzipiell nichts vervollständigen, was von den Dateien des Nutzers abhängt.

Jetzt gibt ct completion <shell> nur noch einen ~15-Zeilen-Hook aus, der bei jedem Tab auf ct zurückruft; die Kandidaten kommen live aus dem Commander-Baum. Shell-Dialekt-Zeilen in unserem Repo: 0. Und damit geht das hier:

ct plan --env <Tab>                  → dev prod          (aus ct.envs.json)
ct state rm --env dev campus <Tab>   → die tatsächlich verwalteten Keys

Warum omelette und nicht @pnpm/tabtab

tabtab ist die bessere Bibliothek, fällt hier aber aus einem Grund raus, der genau unsere Release-Pipeline trifft: Sie lädt ihre Hook-Templates zur Laufzeit von der Platte (path.join(__dirname, 'templates', …)). In den bun build --compile-Binaries zeigt __dirname auf die node_modules der Build-Maschine. ct completion zsh hätte also auf dem CI-Runner funktioniert und wäre bei jedem Nutzer mit ENOENT gestorben — und unsere Smoke-Tests hätten das nie gefangen, weil die auf einem Checkout mit node_modules laufen. Ich habe das mit einer kompilierten Probe nachgestellt, ist kein theoretisches Bedenken.

Preis dafür: keine Beschreibungstexte an den Kandidaten in zsh (omelette nutzt compadd, tabtab _describe). Funktionierende Standalone-Binaries waren mir wichtiger.

Und ja, omelette ist praktisch eingefroren — letztes Release September 2021, letzter Commit Januar 2022. Bewusst in Kauf genommen: ~350 Zeilen MIT, ohne Dependencies, deren ganzer Job das Ausgeben von drei statischen Hook-Strings ist. Der realistische Ausfallmodus ist "bekommt nie ein Feature", nicht "geht kaputt", und im Notfall ist Vendoring ein Nachmittag. Die Begründung steht im Code, nicht nur hier.

Kleinigkeiten: Die /reference/- und /reports/-Zeilen in .gitignore sind raus, die gehören zu #133. <shell> bleibt Pflichtargument — zsh und bash bekommen denselben Hook, der branched selbst, nur fish ist anders; $SHELL-Erkennung wäre unzuverlässig und genau dann falsch, wenn jemand absichtlich für eine andere Shell generiert.

fish habe ich installiert und die Completion dort auch wirklich durchgetrieben, nicht nur fish -n laufen lassen. Alles grün: 828 Tests, typecheck, lint, format:check, build, docs-staleness.

Schau bitte drüber, ob du das so mittragen kannst — vor allem beim Verzicht auf die Beschreibungstexte hätte ich gern deine Meinung.