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

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

Click to view all benchmark results

Benchmark	Latency	Benchmark Result microseconds (µs) (Result Δ%)	Upper Boundary microseconds (µs) (Limit %)
empty_router/empty_router	📈 view plot 🚷 view threshold	5,606.60 µs (-9.60%) Baseline: 6,202.14 µs	7,769.64 µs (72.16%)
json_api/json_api	📈 view plot 🚷 view threshold	998.73 µs (-7.70%) Baseline: 1,082.01 µs	1,324.38 µs (75.41%)
nested_routers/nested_routers	📈 view plot 🚷 view threshold	951.40 µs (-5.20%) Baseline: 1,003.62 µs	1,204.76 µs (78.97%)
single_root_route/single_root_route	📈 view plot 🚷 view threshold	925.39 µs (-4.20%) Baseline: 965.95 µs	1,168.76 µs (79.18%)
single_root_route_burst/single_root_route_burst	📈 view plot 🚷 view threshold	17,133.00 µs (-2.63%) Baseline: 17,595.05 µs	21,141.65 µs (81.04%)

🐰 View full continuous benchmarking report in Bencher

[codecov]

Codecov Report

❌ Patch coverage is 94.53237% with 38 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cot-cli/src/project.rs	96.36%	5 Missing and 10 partials ⚠️
cot-cli/src/handlers.rs	92.74%	6 Missing and 3 partials ⚠️
cot-cli/src/main.rs	90.16%	4 Missing and 2 partials ⚠️
cot/src/project.rs	0.00%	5 Missing ⚠️
cot/src/cli.rs	0.00%	3 Missing ⚠️

Flag	Coverage Δ
rust	90.41% <94.53%> (+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	95.41% <100.00%> (+1.93%)	⬆️
cot/src/metadata.rs	100.00% <100.00%> (ø)
cot/src/cli.rs	82.14% <0.00%> (-1.12%)	⬇️
cot/src/project.rs	88.21% <0.00%> (-0.56%)	⬇️
cot-cli/src/main.rs	92.40% <90.16%> (-7.60%)	⬇️
cot-cli/src/handlers.rs	94.33% <92.74%> (-1.61%)	⬇️
cot-cli/src/project.rs	96.36% <96.36%> (ø)

🚀 New features to boost your workflow:

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