Epic: CLI v0 (Phase 1)

[Sootopolis]

Goal

Ship ccas as a real CLI binary, backed by an explicit local CcasServer process. Single user, no auth, loopback only. CLI = thin HTTP client.

Why

Today CCAS is seven ZIOAppDefault apps. Running two concurrently means two independent ChessComClient instances with no shared rate limit. The CLI shape collapses everything onto one server-mediated path so the rate limiter stays singular, and sets up the foundation for the OAuth phase that follows.

Open decisions

• Classify JobKinds: user-facing vs server-internal #50 — Classify JobKinds: user-facing vs server-internal. Affects CLI subcommand tree via decline #46 (subcommand scope) and Bootstrap default JobSchedule rows for server-internal kinds at first boot #45 (route scope, possible pivot to schedule-bootstrap). Resolve before starting either.

Dependency graph

flowchart LR
  classDef ready  fill:#d4edda,stroke:#28a745,color:#000
  classDef next   fill:#fff3cd,stroke:#ffc107,color:#000
  classDef final  fill:#f8d7da,stroke:#dc3545,color:#000
  classDef decide fill:#e7e1ff,stroke:#6f42c1,color:#000,stroke-dasharray:5 3
  classDef done   fill:#e2e3e5,stroke:#6c757d,color:#000,stroke-dasharray:0
  P1["#41 Packaging"]:::done
  P4["#45 seed global schedules"]:::done
  P6["#42 JobLogTransport refactor"]:::done
  P7["#43 CLI config file"]:::done
  P8["#44 GET /api/clubs"]:::done
  P2["#46 decline subcommands"]:::done
  P5["#47 File-tail logs endpoint"]:::done
  P3["#48 ccas serve lifecycle"]:::done
  P9["#49 Shell completions"]:::done
  D1["#50 Decide: user-facing vs internal JobKinds"]:::decide
  P1 --> P2
  P2 --> P3
  P2 --> P9
  P6 --> P5
  P8 --> P9
  D1 -.affects.-> P2
  D1 -.affects.-> P4

Loading

Green = no open deps; amber = unblocked once a green closes; red = final tier; purple dashed = decision pending; grey = done.

Sub-issues

Start here (no open dependencies)

• Packaging via sbt-native-packager #41 — Packaging via sbt-native-packager (chore, ~3h)
• Bootstrap default JobSchedule rows for server-internal kinds at first boot #45 — Seed default global JobSchedule rows at boot (MatchRef + ClubData), config-driven via application.conf — rescoped after Classify JobKinds: user-facing vs server-internal #50; per-club seeding split out to First-class managed_club marker (server-scoped, forward-compatible to per-user) #101/Seed default History/Membership schedules per managed club #102 — shipped in feat(scheduler): seed global maintenance schedules at boot (#45) #103 (31d8874)
• Refactor ProgressDisplay to accept a configurable log sink (JobLogTransport) #42 — Refactor ProgressDisplay for a configurable log sink (JobLogTransport) (~2h)
• CLI config file resolution #43 — CLI config file resolution (--server → api_url → default) — done in feat(cli): config file resolution + command split #85 (HOCON config.conf, not TOML)
• GET /api/clubs endpoint #44 — GET /api/clubs endpoint (~30m)
• File-tail logs endpoint GET /api/jobs/{id}/logs #47 — File-tail logs endpoint GET /api/jobs/{id}/logs (unblocked by Refactor ProgressDisplay to accept a configurable log sink (JobLogTransport) #42)
• CLI subcommand tree via decline #46 — CLI subcommand tree via decline (after Packaging via sbt-native-packager #41 ✓) — scope may shrink pending Classify JobKinds: user-facing vs server-internal #50
• ccas serve lifecycle (serve, serve --detach, stop) #48 — ccas serve lifecycle (serve, serve --detach, stop) (after Packaging via sbt-native-packager #41 ✓, CLI subcommand tree via decline #46 ✓)
• Shell completions for ccas #49 — Shell completions for ccas (after CLI subcommand tree via decline #46 ✓, GET /api/clubs endpoint #44 ✓) — done in feat(cli): cached shell completion (bash/zsh/fish) #78 (pure-shell pivot)

Follow-ups

• CLI club-context: current_club + ccas use <slug> #86 — CLI club-context (current_club + ccas use <slug>) — from CLI config file resolution #43; supersedes the default_clubs-as-slug-fallback
• First-class managed_club marker (server-scoped, forward-compatible to per-user) #101 — First-class managed_club marker (server-scoped, forward-compatible to per-user) — split from Bootstrap default JobSchedule rows for server-internal kinds at first boot #45; does not gate on Backend auth, authz & abuse defenses (Phase 2 server hardening) #66/CLI club-context: current_club + ccas use <slug> #86
• Seed default History/Membership schedules per managed club #102 — Seed default History/Membership schedules per managed club — split from Bootstrap default JobSchedule rows for server-internal kinds at first boot #45; depends on First-class managed_club marker (server-scoped, forward-compatible to per-user) #101

Done when

• All sub-issues closed.
• bin/ccas membership team-alpha runs end to end locally with live progress streaming.
• bin/ccas serve --detach + bin/ccas stop round-trip cleanly.
• Tab completion for ccas and ccas membership works in bash and zsh.

Reference

Full roadmap: ~/.claude/plans/ultra-sparkling-unicorn.md, section "Phase 1 — Local CLI ↔ local server".

Maintenance

When a sub-issue closes:

1. Tick its box above.
2. Move any of its dependents from a later tier into "Start here" if they have no other open deps.
3. Update the mermaid graph node colours.

Edits to this body should happen mid-session, not as homework.