feat(driver): one subcommand per translation unit

[16bit-ykiko]

Why

Upcoming features (clice lint with cross-TU caching, ahead-of-time indexing, documentation data generation) are all CLI applications over the same core, but the CLI surface lived as one monolithic clice.cc. This PR gives every subcommand its own home before those features land.

What

• src/driver/ holds one translation unit per subcommand: serve, query, worker, plus new stubs index, doc, lint, format. Each file owns its options struct and registers a deco command with the root SubCommander through an add_* builder.
• clice.cc shrinks to collection and registration (206 → ~60 lines). Behavior parity everywhere: dispatch, --version, root/per-command --help, missing/unknown subcommand handling, worker defaults, query port validation.
• Stubs print a one-line self-description to stderr and exit non-zero, so scripts can detect the command is unavailable while humans learn what it will do.
• Commands are constructed inside the builders and moved into the SubCommander (owning overload); help re-constructs a fresh command for usage printing, so no closure captures a moved-from object.
• New tests/integration/lifecycle/test_subcommands.py pins the whole surface: all seven names registered in root usage, stub messages and exit codes, per-command help, unknown-subcommand failure.

Tests

• Unit: 1059; Integration: 304 (incl. 4 new CLI surface tests); Smoke: 3/3.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: aaf0381b-f082-4d60-85c7-5b9a66f3febc

📥 Commits

Reviewing files that changed from the base of the PR and between b32bdbb and b35c8cf.

📒 Files selected for processing (1)

• src/driver/driver.h

🚧 Files skipped from review as they are similar to previous changes (1)

• src/driver/driver.h

---

📝 Walkthrough

Walkthrough

Changes

CLI driver extraction

Layer / File(s)	Summary
Driver API and shared CLI helpers src/driver/driver.h	Adds subcommand registration declarations, log-level application, and usage-printing helpers.
Root dispatch and executable sources CMakeLists.txt, src/clice.cc	Builds driver sources and delegates root subcommand registration and error handling to driver functions.
Implemented command dispatch src/driver/serve.cc, src/driver/query.cc, src/driver/worker.cc	Adds option parsing, help handling, logging configuration, and execution dispatch for serve, query, and worker.
Stub commands and lifecycle validation src/driver/{index,doc,lint,format}.cc, tests/integration/lifecycle/test_subcommands.py	Adds placeholder commands and tests for usage, help, stub failures, and unknown commands.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• clice-io/clice#447: Also restructures src/clice.cc around SubCommander-based subcommand dispatch.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main refactor to split subcommands into separate translation units.
Description check	✅ Passed	The description clearly matches the changeset and describes the CLI refactor, new subcommand files, and tests.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/driver-subcommands

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/driver/driver.h`:
- Around line 28-33: Update apply_log_level to create a lowercased copy of
level_str and compare that normalized value with "off" when detecting unknown
levels. Preserve the parser’s mixed-case acceptance while keeping the existing
error message’s accepted names aligned with spdlog::level::from_str.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 50e92f55-4b43-4495-be9f-c1eab867b55a

📥 Commits

Reviewing files that changed from the base of the PR and between bb6d11d and b32bdbb.

📒 Files selected for processing (11)

• CMakeLists.txt
• src/clice.cc
• src/driver/doc.cc
• src/driver/driver.h
• src/driver/format.cc
• src/driver/index.cc
• src/driver/lint.cc
• src/driver/query.cc
• src/driver/serve.cc
• src/driver/worker.cc
• tests/integration/lifecycle/test_subcommands.py