refactor(tui): adopt command shapes in utility group (FEAT-018)

[aboimpinto]

Summary

FEAT-018 converts the complete TUI utility command group to the external command shapes introduced by FEAT-014 and hosted by FEAT-015. The seven command files remain under codewhale-tui; this PR changes their execution boundary without physically moving them.

This PR:

• registers /attach, /automation, /jobs, /mcp, /network, /task, and /update through RegisterCommand<CommandResult> and the existing ContextualCommand::from_contract bridge;
• removes concrete App and executable TUI-helper access from every utility handler;
• adds narrowly scoped presentation, atomic media-attachment, and canonical operation-digest capabilities to codewhale-command-contract;
• keeps /jobs, /network, and /update argument-only (CommandHandler::Pure), while /attach, /automation, /mcp, and /task declare and receive only their exact minimum external facets;
• removes utility from the migration frontier only after the whole group is portable;
• preserves the existing registry, precedence, aliases, messages, localization, actions, persistence behavior, and safety checks.

Tracking: EPIC-005 / EPIC-006 / FEAT-018 in #5316.

No-Issue: FEAT-018 is tracked in umbrella #5316, which must remain open for the remaining decomposition FEATs.

Dependency boundary

The intended dependency direction remains acyclic:

future codewhale-commands utility group
                 |
                 v
codewhale-command-contract ---> codewhale-core / other acyclic leaf crates
                 ^
                 |
codewhale-tui implements the host facets

Utility handlers no longer name or call concrete App, TUI services, TUI state, localization enums, composer helpers, work-runtime helpers, config-persistence helpers, or other executable TUI behavior. The concrete implementations remain on the TUI-owned adapter side and expose only external trait objects to handlers. codewhale-command-contract has no dependency on codewhale-tui, enforced by the existing boundary gate.

Temporary FEAT-037 compatibility references

This PR intentionally does not move shared command outcome/action ownership. The following TUI-owned data-only references remain temporarily:

• CommandResult in all seven utility modules;
• AppAction in automation.rs, jobs.rs, mcp.rs, and task.rs;
• AutomationAction in automation.rs;
• ShellJobAction in jobs.rs;
• McpUiAction in mcp.rs.

These types describe handler outputs; they provide no access to App or executable TUI behavior. They are therefore the bounded compatibility exception defined by FEAT-018, not a reverse executable dependency and not circular-dependency debt.

The mandatory retirement sequence is:

1. FEAT-018 through FEAT-035 remove executable TUI dependencies while command files remain in TUI.
2. FEAT-036 moves localization ownership behind its compatibility path.
3. FEAT-037 moves CommandResult, AppAction, and only the proven action payload data into external ownership, retaining compatibility re-exports as needed.
4. FEAT-016 bootstraps codewhale-commands after those ownership prerequisites are external.
5. FEAT-038 physically moves the utility group only after the temporary data references are gone.

Keeping that ownership move out of FEAT-018 is deliberate: one FEAT remains one independently reviewable structural PR, without mixing command rewiring, shared-type relocation, and physical file movement.

Capability additions

• CommandPresentationContext: stable translation keys with exact named replacements and safe failure behavior.
• CommandMediaContext: validates and inserts media atomically, returning only a portable receipt.
• CommandWorkspaceContext::operation_digest: delegates session-aware capture and canonical digest formatting to the host.
• CommandCapabilities: each contextual registration declares its exact minimum external facet set; the dispatcher exposes only those facets, rejects empty contextual declarations, and pure handlers build no host bundle.
• CommandContexts / ContextParts: add presentation and media slots without a command-specific envelope, host escape hatch, or second registry.

Review hardening

Commit 643b76c5f incorporates the first-production-slice review findings: exact capability declarations are enforced by the external contract; undeclared facets remain absent; missing required facets return safe command errors; malformed localized placeholder contracts fall back through the authoritative English catalog; the nine-facet comment is current; and the attachment validation rationale is retained beside the moved validation block. The same invariant is now recorded for FEAT-019 through FEAT-046 and the EPIC-006 final gate. Commit e4aad4c06 repairs the Rust 1.98 strict-Clippy diagnostics exposed after rebasing onto current main, without changing the FEAT-018 behavior or dependency boundary. The complete GitHub Actions matrix is green on this head.

Scope and behavior

• Only groups/utility is migrated.
• No command file moves out of codewhale-tui.
• No shared result/action type moves in this PR.
• No localization system extraction occurs.
• Names, aliases, usage strings, registry order, discovery, returned actions, user messages, network redaction, attachment validation, operation-digest semantics, and bounded updater output remain unchanged.

Testing

• cargo fmt --all -- --check
• cargo test -p codewhale-command-contract --lib --locked — 10 passed
• cargo test -p codewhale-tui --lib --locked — 10,865 passed, 13 ignored in the review-hardening gate
• Focused FEAT-018 public-dispatch tests — 3 passed
• TUI command-adapter tests — 17 passed
• Utility-group tests — 37 passed
• python3 scripts/test_check_command_crate_boundaries.py — 8 passed
• python3 scripts/check-command-crate-boundaries.py
• python3 scripts/test_check_command_migration_manifest.py — 54 passed
• python3 scripts/check-command-migration-manifest.py --baseline-ref origin/main
• python3 scripts/test_ci_migration_wiring.py — 11 passed
• Strict workspace Clippy with -D warnings — 0 warnings
• cargo test --workspace --all-features --locked — 13,074 passed in the final serialized gate
• Release build for codewhale-cli and codewhale-tui
• git diff --check

Checklist

• All seven utility registrations use the portable contract path
• Zero concrete-App utility handlers
• Zero executable TUI dependencies in utility handlers
• Exact least-capability declarations; undeclared facets unavailable; pure handlers build no host bundle
• Exact temporary FEAT-037 data references documented
• utility removed from both migration-frontier representations
• No physical group move or shared-type ownership move
• No manual UI verification required for this structural change

Paulo Aboim Pinto

[Lstarsky0]

Went at the preservation claim first. Bare App is gone from all seven handlers — 31 references down to 0 — while AppAction and the rest stay exactly where the body says they do. Comparing string literals outside the test modules, the messages that left the handlers land verbatim in contract.rs: Attachment not found:, Attachment is not a file:, the unsupported-type sentence, both operation-digest strings. attach_media also keeps the original check order, so "not found" still prints the pre-canonicalize path and the other two print the canonical one. /automation's --confirm parsing is byte-identical apart from the parameter swap.

One thing isn't preserved. Base rendered the MCP recommendations with chained .replace("{restart_command}", …), which tolerates a locale entry whose placeholders don't line up — you get that locale's text, possibly with a literal {restart_command} sitting in it. apply_named_replacements (contract.rs:550) instead requires the placeholder set to equal the supplied names exactly; missing, extra and duplicate all return None, and the handler then falls back to a hardcoded English string. So a translator who drops {restart_command} from mcp_recommendations_safety turns that whole line English instead of leaving a visible artifact. kimi_import_and_new_mcp_recommendations_have_complete_locale_parity (localization.rs:4548) does cover those keys, but only for non-empty and different-from-English — placeholder parity is asserted for the Automation* and Coordination* packs (:3917) and the permission messages, not for these. So nothing in CI catches the drift, and the four fallback strings are hand-copies of the en catalog with nothing holding them to it.

Second one is about the shape rather than this diff. CommandContexts makes every facet an Option, but the only production builder — CommandContextBundle::contexts() at contract.rs:648 — sets all nine unconditionally, so None never happens and each migrated handler pays for it with .expect("… facet"). Five of those now. Nothing connects what a command declares it needs to what the host actually filled in; it's convention held in place by there being exactly one builder. This is FEAT-018 of about twenty, so whatever it settles is what the rest inherit.

Small: the doc comment right above that builder still says "Owns seven facet objects" (contract.rs:630) — this PR makes it nine. And the five-line comment explaining why an image is validated at command time rather than at send time didn't travel with the block into MediaAdapter::attach_media.

[aboimpinto]

Thank you for tracing both behavior preservation and the boundary shape so carefully. Addressed in 643b76c5f.

The weak full-envelope convention is now an enforced least-capability contract:

• CommandHandler::Contextual carries a contract-owned CommandCapabilities declaration.
• /attach receives only WORKSPACE | MEDIA; /automation and /mcp receive only PRESENTATION; /task receives only WORKSPACE.
• /jobs, /network, and /update remain Pure, and the dispatcher does not construct a host bundle on that branch.
• CommandContextBundle::contexts populates only declared slots. There is deliberately no public ALL shortcut.
• Empty contextual declarations are rejected during registration, and a missing required facet returns a safe command error instead of panicking.
• Focused tests assert every declaration, restricted envelope exposure, empty-declaration rejection, and safe missing-facet behavior.

On localization: the existing kimi_import_and_new_mcp_recommendations_have_complete_locale_parity test already compares message_placeholders(translated) with message_placeholders(english_value) for these MCP recommendation keys (localization.rs:4608-4609), so shipped complete locale packs were already guarded against placeholder drift. Even so, the runtime path is now stronger: if a selected locale entry has a malformed placeholder contract, rendering retries through the authoritative tr(Locale::En, message_id) catalog entry rather than a hand-copied fallback string.

I also updated the stale seven-facet comments to nine and restored the rationale for validating image bytes at command time beside the moved validation block.

The strengthened invariant has been added to EPIC-006 and FEAT-019 through FEAT-046 so later migration slices and physical moves preserve the same pattern. Local verification is green: contract 10/10, TUI library 10,865 passed with 13 ignored, strict workspace Clippy with zero warnings, plus boundary 8/8, migration 54/54, CI-wiring 11/11, and live architecture gates.

The temporary TUI-owned result/action data references are unchanged and remain explicitly assigned to FEAT-037 before the FEAT-038 physical utility-group move.

Paulo Aboim Pinto

[aboimpinto]

CI follow-up complete. The Rust 1.98 strict-Clippy failure was repaired in e4aad4c06, and the complete matrix is now green on the rebased head: 17 successful checks, 6 expected skips, and no failed, cancelled, or pending checks. The PR reports a clean merge state.

Paulo Aboim Pinto

[Hmbown]

Thank you @aboimpinto — this shipped in v0.9.11 🎉

Your FEAT-018 utility-group command-shapes work (contract-backed dispatch seam, capability facets) is in the released tag v0.9.11 (96d13a0b): the pr-5525 integration merge plus the FEAT-018 acceptance/test commits (e.g. b8c3bbf06, ccdb77909), and you're credited in the CHANGELOG ("Thanks to Paulo Aboim Pinto (@aboimpinto) for PR #5525").

It landed via the v0.9.11 release integration branch rather than this PR's merge button, so GitHub left this one open + conflicting against the released tree. Closing it as shipped — not rejected. Your EPIC-006 command-decomposition work is live and credited; thanks for driving it, and apologies this PR sat open.