feat(phase-3): improve structured errors and help examples

[overtrue]

Summary

• add structured JSON error envelopes while keeping the legacy error field
• add explicit recovery hints for high-value mutating commands such as cp, rm, mb, event, replicate, and admin user add
• make help output more example-first for the main mutating workflows and extend help contract coverage

Testing

• cargo fmt --all
• cargo clippy --workspace -- -D warnings
• cargo test --workspace

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 18a447f147

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR enhances the CLI’s user-facing ergonomics by introducing a structured JSON error envelope (while preserving the legacy "error" field) and by making --help output more example-driven for key mutating workflows.

Changes:

• Add structured JSON error output with typed details, retryability, and optional exit code/suggestions.
• Introduce Formatter helpers (fail*, error_with_code, error_with_suggestion) and adopt them across high-value mutating commands to provide recovery hints.
• Expand help contract tests and add after_help examples to several commands.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
crates/cli/src/output/formatter.rs	Introduces structured JSON error envelopes + new formatter APIs for consistent coded/suggested failures.
crates/cli/src/commands/cp.rs	Adds example-first help footer and more actionable, coded/suggested errors for copy workflows.
crates/cli/src/commands/rm.rs	Adds help examples and recovery hints; switches many errors to coded/suggested formatter helpers.
crates/cli/src/commands/mb.rs	Adds help examples and recovery hints for bucket creation failures (usage, auth, conflict).
crates/cli/src/commands/event.rs	Adds help examples and recovery hints around notifications; updates errors to use formatter helpers.
crates/cli/src/commands/replicate.rs	Adds help examples and recovery hints; refactors errors to use formatter helpers.
crates/cli/src/commands/admin/user.rs	Adds help examples and improves usage validation errors with suggestions.
crates/cli/tests/help_contract.rs	Extends help contract coverage to assert presence of new Examples sections/tokens.
crates/cli/tests/snapshots/golden__alias_tests__alias_remove_not_found.snap	Updates golden snapshot for new structured JSON error output shape.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.