feat(cli): visual and UX polish across all commands

[chrisdeeming]

Summary

• Full visual/UX pass over every command: one output language (single ✓ summary box per outcome, → hints, consistent empty states, dates, plurals, punctuation), grouped and styled --help, a native styled ps table, and TTY-gated spinners/progress so piped output is ANSI-free and NO_COLOR is respected.
• New error model: styled ✗ renderer with remediation hints, internal classification sentinels never leak into messages, prompt/menu cancellation exits 0 silently, and passthrough commands (php, composer, compose, exec, direct XF commands) propagate the child's exit code with no redundant Error: trailer.
• Fixes five real bugs found during the audit: init step counting ([8/7] drift), xf debug dropping all arguments after the first, an unchecked checksum slice panic in download, review-screen validation warnings being wiped before they could be read, and the keychain missing-entry sentinel.

Testing

• go build ./... && go vet ./... && gofmt -l . && go test ./... — all green.
• Full output audit of every command against the style rules, piped (| cat -v, NO_COLOR=1) and on a TTY.
• Manual runs: doctor, auth status (all token states), cache list/purge/path, worktree list/prune, lifecycle (up/ps/down), error and exit-code paths.
• Not exercised live: self-update install and a full upgrade run (no target install available); verified by reading and unit tests.

Visual evidence

Errors, before → after:

  

auth status with an expired token, before → after:

  

--help is now grouped with styled headings instead of one flat alphabetical list of 22 commands, before → after:

  

Notes

• Stacked on feat(worktree): create and manage development worktrees #14 (worktree management) — that branch created the worktree/init code this PR restyles. Retarget to main once feat(worktree): create and manage development worktrees #14 merges.
• Deliberate behaviour changes: choosing Cancel in the review menu exits 0 (Ctrl-C at any prompt exits 130, and a prompt that cannot open a terminal is reported as an error); a failing passthrough child, including the local non-Docker fallback, exits with its own code; cache purge without flags is now a usage error (exit 1); doctor failure exits 1 without a duplicate error line; xf -v <xenforo-command> is now an unknown-command usage error instead of root help with exit 0.
• CHANGELOG updated under Unreleased.

Checklist

• The change is focused and does not include unrelated work.
• Relevant automated and/or manual testing has been performed.
• UI changes include screenshots or video where appropriate.
• Upgrade, compatibility, and performance implications have been considered.

Note

Polish visual output and UX across all CLI commands

• Adds structured command groups ("Getting started", "Environment", "Run tools", "Maintenance") to help output with styled headings via a custom Cobra usage template in cmd/xf/root.go.
• Standardises terminal output across all commands: spinners use a single shared instance per operation, success results use SuccessBox, empty states use PrintEmpty, hints use PrintHint, and dates use FormatDate/FormatDateTime.
• Adds new ui utilities in internal/ui/ui.go: Plural, FormatDate, FormatDateTime, IsTerminal, ShortHome, PrintHint, PrintEmpty, ClearScreen, and ProgressBar.Abandon; removes Box, Subheader, Italic, Underline, and StatusTableStyle.
• Propagates child process exit codes via passthroughError and exitCodeError so CLI exits mirror subprocess status; SIGTERM is now handled alongside SIGINT with signal-derived exit codes (128+signum).
• Adds runner.PSInfo to internal/dockercompose/runner.go for structured container status, and rewrites xf ps to render a formatted table with colored state columns.
• xf doctor now exits non-zero when checks fail and prints an aggregated summary; xf cache purge now errors when called without --all or --license.
• Risk: several commands change exit codes — xf doctor now exits 1 on failures, child-command wrappers now forward subprocess exit codes instead of always exiting 1, and ErrCancelled now exits 0.

^{Macroscope summarized 3c7004b.}

Summary by CodeRabbit

• New Features

  • Added clearer command grouping and improved help documentation.
  • Added -n, --no-interaction and -c, --config <path> global options.
  • Added container status tables showing services, states, statuses and ports.
  • Added contextual hints, empty states and structured progress feedback across setup, downloads and updates.
  • Expanded authentication status details, including expiry, scope, timestamps and username.

• Bug Fixes

  • Improved cancellation handling and preservation of command exit codes.
  • Improved Docker, authentication, checksum, installation and configuration error reporting.
  • Fixed validation warnings and progress notifications.

[coderabbitai]

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The CLI now uses grouped commands, terminal-aware output, structured errors, signal-specific exit codes, stable authentication status data, improved initialisation progress, Docker Compose container tables, and tracked .default files. Tests cover the new parsing, validation, output, and error contracts.

Changes

CLI behaviour and interface refresh

Layer / File(s)	Summary
Shared UI and error handling internal/ui/*, cmd/xf/errors.go, cmd/xf/root.go, cmd/xf/main.go	Added terminal-aware formatting, structured errors, cancellation handling, exit-code passthrough, command grouping, and updated root error rendering.
Authentication and initialisation flows cmd/xf/auth.go, cmd/xf/init*.go, cmd/xf/auth_json_test.go, cmd/xf/init_*_test.go	Updated authentication status output, initialisation planning, validation, progress reporting, default-file reporting, and interactive error handling.
Command and platform integration internal/docker/*, internal/dockercompose/*, internal/extract/*, internal/xfcmd/*, cmd/xf/*.go, README.md, CHANGELOG.md	Added structured container status parsing, Composer archive detection, .default file tracking, refreshed command output and help metadata, and updated documentation.

Priority: ⬇️ Low

Merge Risk: 🟠 High · up to e2866

This should not merge yet: initialization weakens local file protections, worktree removal can fail to protect user-managed files, and supported Windows test runs can fail.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 34.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 229 functions across 50 files. (1 skipped…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: visual and user-experience improvements across the CLI commands.
Description check	✅ Passed	The description includes the required Summary, Testing, Visual evidence, Notes, and Checklist sections. It states the tested commands, identifies untested live scenarios, documents behaviour changes, …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 34.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 229 functions across 50 files. (1 skipped: 1 unsupported.)

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 32.74611% with 649 lines in your changes missing coverage. Please review.
✅ Project coverage is 43.44%. Comparing base (5667d66) to head (7cbb155).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #15      +/-   ##
==========================================
+ Coverage   40.60%   43.44%   +2.84%     
==========================================
  Files          62       63       +1     
  Lines        6224     6565     +341     
==========================================
+ Hits         2527     2852     +325     
- Misses       3697     3713      +16     

🚀 New features to boost your workflow:

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