Shell completions for ccas

[Sootopolis]

Depends on

• Decline subcommand tree (hidden __complete subcommand is part of the tree)
• GET /api/clubs endpoint (slug source)

Blocks

None.

What

Tab completion for ccas in bash, zsh, fish. Two layers:

1. Hidden ccas __complete <args> subcommand. Given a partial argv, prints space-separated match candidates. Examples:
   • ccas __complete → list of top-level subcommands.
   • ccas __complete membership → list of club slugs.
   • ccas __complete logs → list of recent job IDs.
2. ccas completion <shell> prints a shell completion script (bash, zsh, fish) to stdout. Each script wires its native completion system to call ccas __complete for dynamic results.

Sources for dynamic completions:

• Club slugs: read from cache file ${XDG_CACHE_HOME:-~/.cache}/ccas/clubs.txt, refreshed after every successful command (Phase 1: write the response of GET /api/clubs to the cache after any non-__complete command finishes). Fallback to default_clubs from config if cache missing.
• Job IDs: cache file ${XDG_CACHE_HOME}/ccas/recent-jobs.txt, written by the CLI's poll loop on every job submission.

Completion must not block on network. Cache reads only.

Acceptance

• eval "$(ccas completion bash)" enables ccas <TAB> completion in bash.
• ccas <TAB><TAB> lists all subcommands.
• ccas membership <TAB><TAB> lists known club slugs from cache.
• ccas logs <TAB><TAB> lists recent job IDs.
• With an empty cache, falls back to default_clubs from config.
• Completion latency under 50ms.

Files

• src/main/scala/ccas/cli/complete/ — __complete subcommand, cache read/write.
• new src/main/scala/ccas/cli/completion/ — bash.sh, zsh.sh, fish.sh templates emitted by ccas completion <shell>.

Out of scope

• PowerShell.
• Completion for --since / --until date flags. Free-form dates aren't productively completable.

Reference

Tracked under epic #40 (CLI v0). Discussed in the planning thread; folded into the CLI epic.

[Sootopolis]

Interim: instant static bash completion landed in #75 (completions/ccas.bash) — pure-shell, no JVM, immediate <TAB>. Covers all subcommands and flags; a TestCcasCompletion drift guard keeps it in sync with the command tree and asserts it stays valid bash (bash -n). Install is a symlink (see README).

This does not close the issue — the full design here is still open:

• Hidden ccas __complete <args> subcommand.
• ccas completion <shell> emitter (bash/zsh/fish).
• Dynamic cache-based sources: club slugs (needs GET /api/clubs, GET /api/clubs endpoint #44) and recent job IDs; cache-only, <50ms.
• zsh/fish still use zio-cli's dynamic script (~1.5s per <TAB>).

The static bash script is a stopgap for bash users until the cached __complete design lands.

[Sootopolis]

#44 (GET /api/clubs) merged in #77 — the club-slug source dependency is satisfied. Both blockers (#46 decline subcommand tree, #44 clubs endpoint) are now done, so this is unblocked; only the hidden __complete subcommand + completion-script templates remain to implement.