Modernize CLI UX and add first-class CI/GitHub Actions reporting

[Teakowa]

Goal

Establish a reusable CLI presentation foundation for Wright with mature Rust ecosystem components, shell completion, environment-aware rendering, and first-class GitHub Actions reporting without changing Wright's semantic or machine-readable result contracts.

Context

wright-cli currently owns a hand-written argv parser/help surface while the driver already exposes typed result envelopes and stable exit-code / wright-result/v1 contracts. This is the right point to separate command parsing and human/CI presentation from semantic execution.

The CLI should provide a good default experience in interactive terminals, generic CI, pipes, and GitHub Actions. GitHub Actions should be treated as a native presentation target rather than only as a terminal with colors.

Scope

• Replace the hand-written CLI argument/help layer with a mature Rust CLI framework (prefer clap unless implementation evidence suggests otherwise).
• Generate static shell completion for Bash, Zsh, Fish, and PowerShell from the authoritative command model.
• Introduce explicit presentation concepts for:
  • output format (text / stable machine-readable json),
  • renderer/environment (auto, interactive terminal, plain/non-interactive, GitHub Actions),
  • color policy (auto, always, never).
• Detect GitHub Actions and generic CI environments without relying only on TTY heuristics.
• Add a GitHub Actions renderer that can use native workflow presentation facilities where appropriate:
  • source-linked error/warning/notice annotations from Wright diagnostics,
  • grouped logs,
  • job/step summary output with concise PASS/WARN/ERROR results.
• Keep human output readable when color/ANSI is disabled.
• Ensure progress/spinner output, when introduced for long-running operations, never contaminates command stdout or machine output.
• Add configuration/override points so CI-specific presentation can be disabled or forced explicitly.
• Document the CLI output and CI behavior expected by users and automation.

Non-goals

• Do not require all Wright commands, analyzers, lint rules, or language frontends to be feature-complete before implementing this foundation.
• Do not move GitHub Actions knowledge into semantic, analyzer, frontend, or driver layers.
• Do not make ANSI/color the correctness mechanism for CI reporting.
• Do not implement shell-native history autosuggestion; only Wright-owned completion candidates are in scope.
• Do not introduce dynamic/semantic shell completion until a concrete need justifies the extra runtime integration complexity.
• Do not redesign wright-result/v1, existing exit-code semantics, or command result ownership merely to support richer human presentation.

Acceptance criteria

• wright command parsing/help is driven by one authoritative structured command model rather than duplicated hand-written argv/help logic.
• Bash, Zsh, Fish, and PowerShell completion can be generated from that model.
• Interactive terminal, generic CI/non-TTY, and GitHub Actions execution have deterministic documented renderer behavior.
• Users can disable color and GitHub-specific presentation; explicit overrides take precedence over auto-detection.
• GitHub Actions diagnostics can surface as native source annotations when file/span information is available.
• GitHub Actions runs can produce a concise summary suitable for successful and failing check/lint-style workflows, with PASS/WARN/ERROR remaining understandable without color.
• JSON mode preserves a clean, stable wright-result/v1 stdout contract with no ANSI, workflow commands, progress text, or other human decoration mixed into stdout.
• Compiled/reconstructed source artifacts written to stdout remain byte-for-byte presentation-safe from progress/CI decoration.
• Tests cover environment detection, renderer selection/override precedence, JSON purity, and GitHub workflow-command escaping/formatting.
• Existing CLI command behavior and exit-code contracts remain compatible unless an intentional user-facing CLI change is documented.

Dependencies

This work depends on the existing typed driver result/diagnostic envelope, not on complete implementation of every Wright feature. Current check, lint, analyze, and related result paths are sufficient to establish and test the presentation architecture.

Future commands and diagnostics should be able to adopt the same renderer without adding GitHub-specific logic to their semantic implementation.

Planning notes

Prefer a thin wright-cli presentation layer over adding CI concepts to wright-driver. A likely shape is a shared presentation model feeding terminal/plain/GitHub/JSON renderers, but the exact internal module structure should be chosen from implementation evidence rather than frozen by this issue.

Mature ecosystem crates should be preferred for generic CLI infrastructure (argument parsing, shell completion, terminal capability/color handling, progress, tracing) while Wright retains ownership of semantic diagnostics, result envelopes, output contracts, and CI presentation policy.

[Teakowa]

Implemented on branch codex/issue-164-cli-presentation, commit 7b400bb, and opened Draft PR #165.

Evidence:

• one clap command model now drives parsing, generated help, and completion;
• Bash/Zsh/Fish/PowerShell completion verified;
• auto renderer selection covers terminal, non-TTY/generic CI, and GitHub Actions, with explicit renderer/color overrides;
• JSON remains one clean wright-result/v1 envelope;
• compile/convert source artifacts are byte-exact in plain and GitHub renderers, and compile -o keeps stdout empty;
• structured diagnostics/findings produce escaped GitHub annotations, groups, and PASS/WARN/ERROR summary output;
• top-level help retains the existing common/lint option surface;
• cargo fmt --all -- --check, git diff --check, workspace check/clippy, CLI 63-test suite, and cargo test --workspace pass;
• independent QA final verdict: VERIFIED.

Current dependency: PR #165 is still Draft and its remote CI checks/review are pending. The issue should remain open until that PR is reviewed and merged; no release claim is made from local evidence alone.

[Teakowa]

Remote CI initially exposed a test-harness regression: default black-box tests inherited GITHUB_ACTIONS and failed five existing text stdout/stderr assertions. Commit 7c25fe3 isolates default test environment while preserving explicit renderer environment tests; simulated runner command passed all 63 CLI tests. PR #165 is pushed and waiting for checks to rerun.

[Teakowa]

Final remote evidence: PR #165 head 7c25fe38dc2aa884dac02cc1da6b331a3d1062dd has all 13 checks passing, including both Rust toolchains, all three distribution platforms, LPP, OverPy/OSTW/native differential gates, and v1 release gates. Implementation and independent QA are complete. Remaining dependency is human review/merge of the Draft PR; #164 remains open and no release claim is made before that approval.