feat!: consolidate cot cli commands into one

[ElijahAhianyo]

Background

cot currently exposes CLI commands through two separate entry points:

• cot-cli crate (cot <command>): handles project scaffolding, migration listing, migration generation, and shell completions.
• Compiled binary (invoked directly): exposes runtime commands such as check, running migrations (which is also triggered implicitly at startup), and any custom user-defined task commands.

In addition, running and building a cot app relies on Cargo tooling. In summary, there are three ways to invoke CLI commands today:

1. cot <command> via the cot-cli crate
2. Invoking the compiled binary directly for commands not available in cot-cli
3. Using Cargo to build and run apps

This PR focuses on unifying 1 and 2 for ergonomics: cot now acts as the single entry point for all commands, proxying any unrecognized command to the compiled binary if it exists there. Option 3 (Cargo invocation) is out of scope for this PR and can be revisited in a follow-up if proxying those commands makes sense.

Approach

When cot receives a command it does not recognize, it resolves the target binary (target/debug by default, or target/release if --release is passed), queries it for its available commands via a metadata flag, and either forwards the command along with all provided arguments or returns an error if the command is not found in the binary either.

Metadata

To support proxying, the cot crate exposes a --metadata flag. At runtime, the binary uses reflection to enumerate all registered CLI commands and prints them as JSON to stdout. This serves two purposes: it tells cot-cli whether a given command should be forwarded, and it provides the information needed to render accurate help text.

Example:

$ ./target/debug/forms --metadata
{
  "binary_name": "forms",
  "commands": [
    {
      "name": "check",
      "about": "Verifies the configuration, including connections to the database and other services",
      "aliases": [],
      "subcommands": []
    },
    {
      "name": "collect-static",
      "about": "Collects all static files into a static directory",
      "aliases": [],
      "subcommands": []
    }
  ]
}

Caching

Querying the binary on every invocation would be wasteful, so the metadata response is cached in .cot/command-cache.json. The cache stores the binary's modified time (mtime) alongside the metadata and is invalidated automatically whenever the binary is rebuilt.

Workspaces

When working inside a Cargo workspace, a --package (-p) flag must be provided to specify which package's binary should be targeted.

Type of change

• Bug fix
• New feature
• Documentation
• Refactor / cleanup
• Performance improvement
• Other (describe above)

[github-actions]

Bencher Report

Project	cot
Branch	elijah/cot-proxy-cmd
Testbed	github-ubuntu-latest

Click to view all benchmark results

Benchmark	Latency	Benchmark Result milliseconds (ms) (Result Δ%)	Upper Boundary milliseconds (ms) (Limit %)
empty_router/empty_router	📈 view plot 🚷 view threshold	14.27 ms (+68.95%) Baseline: 8.44 ms	15.97 ms (89.34%)
json_api/json_api	📈 view plot 🚷 view threshold	1.16 ms (+10.04%) Baseline: 1.05 ms	1.38 ms (84.16%)
nested_routers/nested_routers	📈 view plot 🚷 view threshold	1.04 ms (+6.16%) Baseline: 0.98 ms	1.26 ms (82.92%)
single_root_route/single_root_route	📈 view plot 🚷 view threshold	1.02 ms (+7.54%) Baseline: 0.95 ms	1.22 ms (83.36%)
single_root_route_burst/single_root_route_burst	📈 view plot 🚷 view threshold	17.55 ms (+2.64%) Baseline: 17.10 ms	21.57 ms (81.35%)

🐰 View full continuous benchmarking report in Bencher

[codecov]

Codecov Report

❌ Patch coverage is 87.56331% with 221 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cot-cli/src/test_harness.rs	66.16%	119 Missing and 17 partials ⚠️
cot-cli/src/project.rs	89.91%	43 Missing and 14 partials ⚠️
cot-cli/src/main.rs	87.67%	15 Missing and 3 partials ⚠️
cot/src/project.rs	0.00%	5 Missing ⚠️
cot/src/cli.rs	0.00%	3 Missing ⚠️
cot-cli/src/handlers.rs	99.56%	0 Missing and 2 partials ⚠️

Flag	Coverage Δ
rust	90.05% <87.56%> (-0.17%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cot-cli/src/args.rs	100.00% <100.00%> (ø)
cot-cli/src/utils.rs	96.14% <100.00%> (+2.13%)	⬆️
cot/src/metadata.rs	100.00% <100.00%> (ø)
cot-cli/src/handlers.rs	98.79% <99.56%> (+2.86%)	⬆️
cot/src/cli.rs	86.49% <0.00%> (-0.85%)	⬇️
cot/src/project.rs	88.21% <0.00%> (-0.56%)	⬇️
cot-cli/src/main.rs	88.95% <87.67%> (-11.05%)	⬇️
cot-cli/src/project.rs	89.91% <89.91%> (ø)
cot-cli/src/test_harness.rs	66.16% <66.16%> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[m4tx]

Where's the difference between Unix-like and non-Unix-like platforms coming from? Why do we need separate code paths here?

[ElijahAhianyo]

The idea here is to replace the cot process with that of the child(the binary) whenever we forward to(or run) the binary. The exec call is only available on POSIX. Windows doesn't provide a way to do this, so we just spawn the child and block until it exits. Left a comment to outline this behavior as well.
On a side note, one issue i think isnt being handled is signal forwarding in the non-Unix case

[m4tx]

Do we need all this machinery here? Any chance that running cargo run would suffice instead?