Decide: keep the JVM CLI or reimplement `ccas` as a lightweight non-JVM client

[Sootopolis]

Decision needed

Should ccas (the CLI) stay a JVM binary, or be reimplemented as a lightweight non-JVM client? Settle this before further CLI-v0 investment (it reshapes #70, #43, #67).

Context

The CLI is a thin HTTP client to a local CcasServer: parse args → POST/GET → stream logs → print. It has zero domain logic. Yet every ccas <cmd> boots a JVM (~1s + startup noise — the noise is addressed in #79, the ~1s cold start is not). Booting a JVM to make a localhost HTTP call is the same category of cost we just removed from completion (JVM-per-<TAB> → pure-shell, #49/#78).

Crucially, the server's value is not "reuse the JVM for the CLI." It is:

• one ChessComClient = one adaptive rate limiter (two ZIOAppDefault apps at once = two limiters hammering Chess.com — the original epic Epic: CLI v0 (Phase 1) #40 driver),
• the background scheduler,
• the Phase-2 foundation (OAuth bearer, hosted, multi-device).

JVM reuse helps the work (jobs run in the warm server). The CLI front-end being a cold JVM is pure overhead that none of the above needs.

Options

1. Keep the JVM CLI (status quo).

   • Pros: shares the private[ccas] wire DTOs (type-safe), reuses zio-cli parsing/help (CLI subcommand tree via decline #46), one language/build.
   • Cons: ~1s cold start on every command; heavyweight for a localhost HTTP call; completion already had to go pure-shell to escape it.

2. Lightweight non-JVM CLI (shell / Go / Rust).

   • Pros: instant commands; no JVM; consistent with "server is the one warm worker"; completion is already pure-shell; the standalone ZIOAppDefault apps stay for IntelliJ dev so the JVM dev path isn't lost.
   • Cons: reimplement arg parsing + help; hardcode the JSON DTO shapes (small/stable, but a drift risk — mitigable via a generated schema or a contract test); possibly a new toolchain in the repo (Go/Rust) — or pure-shell with curl/jq (no new toolchain, clunkier streaming/JSON).

3. Native-image the JVM CLI (GraalVM).

   • Pros: near-instant start, keep Scala + DTOs.
   • Cons: zio-http/netty under native-image is painful (reflection/JNI config); high effort/risk for a thin client. Likely not worth it.

Why decide now

• Unify app + CLI argument parsing on shared zio-cli command defs (parse into the wire DTOs) #70 (unify app + CLI argument parsing on shared zio-cli command defs) only makes sense if the CLI stays JVM. Doing it before this decision risks throwaway work.
• CLI config file resolution #43 (CLI config file) and ccas config command to manage CCAS settings (DB connection, contact email, …) #67 (ccas config + serve reads the file): the config file is the contract either way, but who writes/reads it differs (a non-JVM CLI writes a file the JVM server reads — a clean split).
• Avoid piling more onto the JVM-CLI assumption before the target is set.

Recommendation

Lean toward Option 2 (lightweight client) as the end-state — it matches the server-as-warm-worker model and the pure-shell-completion precedent — but validate the DTO-drift and parsing/help trade-offs first. Don't pivot mid-epic; decide the target so the remaining CLI-v0 sub-issues build toward it rather than away from it.

References

• Epic Epic: CLI v0 (Phase 1) #40 (CLI v0). Pure-shell precedent: Shell completions for ccas #49 / feat(cli): cached shell completion (bash/zsh/fish) #78. Startup noise: chore(cli): silence JVM startup noise + clean serve config error #79. Config: CLI config file resolution #43, ccas config command to manage CCAS settings (DB connection, contact email, …) #67, app_setting table for DB-owned app settings (start with cache_retention_days) #57.

[Sootopolis]

Decision: keep the JVM CLI (Option 1)

Resolved in favour of Option 1 — keep the JVM ccas CLI, reversing the earlier lean toward Option 2 after grounding the trade-offs in the code (empirical cold-start measurement + adversarial review).

What flipped it

• The CLI already shares compile-checked DTOs with the server. Dispatcher.scala imports all 12 wire DTOs directly from ccas.server.routes.{JobRoutes,BlacklistRoutes,ScheduleRoutes} (private[ccas] case classes; single-module build). A DTO change the CLI doesn't handle fails to compile. Option 2 would replace this free, compile-time contract with 12 hand-synced structs across a language/git boundary — a self-inflicted drift/bug class — and it kills Unify app + CLI argument parsing on shared zio-cli command defs (parse into the wire DTOs) #70 (unify app+CLI parsing on shared defs).
• ccas serve boots the full JVM server regardless, so Option 2's "no JVM" only applies to the thin HTTP-client commands, not the workflow end-to-end. The JVM never actually leaves.
• Measured cold start ≈ 0.5–0.85s (median ~850ms, staged binary), but JVM boot itself is only ~15ms — ~98% is zio-cli + ZIO-runtime/classload init. The cost is the framework stack, not the JVM. ⇒ GraalVM (Option 3) barely helps (it cuts boot/JIT, not layer construction), and the cost is trimmable without leaving the JVM.
• The pure-shell-completion precedent (feat(cli): cached shell completion (bash/zsh/fish) #78) doesn't carry. Completion fires per-keystroke (JVM-per-TAB intolerable, hence feat(cli): cached shell completion (bash/zsh/fish) #78). A command fires once and then waits on a network round-trip + a long-running job, where ~0.85s is noise.

Net

Option 2's gain (~0.7s per rare, network-bound command) does not justify losing the compile-time DTO contract + solo-dev dual-language maintenance + killing #70. Option 3 is high-effort for a metric it barely moves.

Consequences

• Unify app + CLI argument parsing on shared zio-cli command defs (parse into the wire DTOs) #70 (shared zio-cli parsing) is now unblocked on the Decide: keep the JVM CLI or reimplement ccas as a lightweight non-JVM client #80 axis — proceed.
• CLI config file resolution #43 / ccas config command to manage CCAS settings (DB connection, contact email, …) #67 / ccas serve lifecycle (serve, serve --detach, stop) #48 proceed on the JVM-CLI assumption, no throwaway risk.
• Escape hatch if startup ever becomes a real complaint: trim zio-cli/ZIO-runtime init (98% of the cost) — not a language rewrite, not GraalVM. File a "profile + trim CLI cold start" issue only if it bites.

Closing as decided.