CLI Tool Implementation

[Kinflou]

CLI Tool Implementation

Priority

P2 (Medium) - User-facing interface

Status

Landed in #2 (merged); the check fast path shipped as
ComlineProject/core#21 (merged). The only item left is crates.io publishing,
which is blocked on a released comline-core.

Description

comline is a command-line interface for Comline that exposes the common
development workflows built on top of comline-core. This issue tracks rounding
out its command set, output and packaging.

Note: This issue was originally filed in ComlineProject/core when the CLI
was still hypothetical. It has been transferred here and rescoped against the
code that now exists in this repo.

Starting point

A working binary already existed in this repo (clap + miette + tracing,
comline-core pulled in via git):

Command	State at filing
comline build [--release]	Runs the full build pipeline; prints the version bump and a formatted breaking / new-feature / modification changelog. --release plumbed through but unused.
comline check	Validated the project by delegating to build() — no dedicated fast path.
comline generate	Builds, then discovers generators via codelib_gen::find_generator and writes one output file per schema namespace.
comline new <name>	Scaffolded a directory containing a minimal config.idp.

Global flags: --path <dir> to run outside the CWD, -v/-vv for log verbosity.
Covered by tests/cli_tests.rs with fixtures under tests/fixtures/, plus a CI
workflow.

Gaps

Commands

• comline diff <old> <new> — standalone subcommand. The diffing logic
  already exists (comline_core::schema::ir::diff); expose it directly for
  comparing two versions/refs instead of only via build.
• comline clean — remove build artifacts / clear the CAS store / reset state.
• comline check — a real validation-only path instead of calling build()
  (no codegen, no CAS writes). Needs a comline-core helper — core#21.
• comline new scaffold — decide new vs init (kept new); flesh out the
  scaffold with an example schema under src/ and optional git init.
• comline generate --target <lang> — select one configured generator
  instead of running every one.

UX

• Colored output (errors red, success green) independent of the tracing
  layer — status lines no longer ride on log records.
• Progress indication for long builds.
• Non-zero exit codes on failure that are stable for CI (audit miette::bail!
  / Err paths).
• -q / quiet mode.
• --watch for rebuild-on-change.

Packaging & docs

• Publish to crates.io so cargo install comline works. Cargo.toml
  currently depends on comline-core via a git URL, which blocks
  publishing — needs a released comline-core version.
• Cargo.toml metadata: repository and description were stale.
• Shell completions (bash, zsh, fish, …) via clap_complete.
• Man pages via clap_mangen.
• --help review for every subcommand.
• CLI guide. docs/cli.md is the full guide — every command, the
  versioning model, output and exit codes, watch mode and packaging;
  README.md is the quick tour and links to it. A dedicated docs site is
  still wanted, as a separate effort.

Example Usage

# Scaffold and enter a project
comline new my-api
cd my-api

# Build schemas
comline build

# Generate bindings
comline generate --target rust

# Validate without building
comline check

# Compare two schema versions
comline diff 0.1.0 0.2.0

Dependencies

Tracks comline-core capability work in ComlineProject/core:

• Package configuration system (ComlineProject/core#6)
• Schema diffing & auto-versioning (ComlineProject/core#7)
• Code generation plugin system (ComlineProject/core#8)

Publishing (cargo install comline) is additionally blocked on comline-core
being released to crates.io rather than consumed via git.

[Kinflou]

#2 is merged (552127c). What landed:

• Commands — diff, clean, a real validate-only check (via the merged ComlineProject/core#21), generate --target, richer new scaffold + --git, completions.
• UX — -q/--quiet, --watch for build/generate, progress spinner, colored stderr output decoupled from tracing, stable exit codes (0/1/2), a long_about with examples on every subcommand.
• Packaging & docs — Cargo.toml metadata fixed, tokio dropped; man pages + 5-shell completions generated at build time; README.md rewritten; docs/cli.md added as the full guide; CI gains a fmt + clippy -D warnings job.
• Tests: 6 → 17.

Left open for the one remaining checkbox: publish to crates.io, blocked on comline-core being released (it is currently a git dependency). A dedicated docs site is wanted eventually but is tracked separately.