tasks

Fix MVP Validation CLI Issues

Goal

Fix CLI issues found during the first MVP validation pass.

Sources

Context

The MVP validation used a clean temporary Forma workspace and the local target/debug/forma binary. Core create, check, index, list, inspect, serve, RPC, and WebApp read-only browsing flows passed. Two CLI usability gaps were found in the install and then-current initialization validation path.

In scope

  • Add standard forma --version support.
  • Keep the existing no-argument forma version output working.
  • Improve non-JSON failed command output so diagnostics include useful code and message details instead of only <operation> failed.
  • Add focused CLI tests for the changed behavior.

Out of scope

  • Release artifact download testing.
  • Install script changes.
  • WebApp feature changes.
  • Knowledge Workflow migration cleanup.

Acceptance criteria

  • forma --version exits successfully and prints forma 0.1.0.
  • Failed non-interactive initialization output includes useful diagnostic details.
  • Existing JSON output for failed operations remains unchanged.
  • Focused Rust CLI tests pass.

Relationship notes

Release artifact and install-script validation is a separate follow-up validation step after these CLI behavior fixes.

Validation notes

  • Added forma --version and forma -V.
  • Improved human-readable failed operation output to include diagnostic severity, code, message, and path when available.
  • Verified target/debug/forma --version prints forma 0.1.0.
  • Verified the then-current non-interactive initialization path printed useful diagnostic details in non-JSON output.
  • Verified cargo test -p forma-cli, cargo check -p forma-cli, and cargo fmt --check pass.
  • Release artifact validation passed after network recovery:
    • downloaded forma-macos-arm64.tar.gz and matching .sha256;
    • verified checksum with shasum -a 256 -c;
    • extracted forma-macos-arm64/bin/forma;
    • verified the release binary can run create, check, list, inspect, config inspect, and serve flows;
    • verified forma serve serves embedded WebApp assets and RPC;
    • opened the release WebApp in the in-app browser and confirmed overview, spaces, views, diagnostics, and rpc: connected.

Open questions