fix(cli): mapping/structured model fields as Pydantic-validated JSON options; fail-loud prompt printing

[marlon-costa-dc]

Summary

Resolves the known residual from #200: a model field typed as a mapping became a dict Typer option, which Typer rejects at invocation, so the mapping branch of u.Cli.field_default never produced a usable command.

Decision (Pydantic law: owned payloads are Pydantic two-way; JSON enters through Pydantic validation): a field without a native CLI form — a mapping, a nested model, or a collection/union that carries one — is exposed as one string option carrying JSON, validated by Pydantic into the field's declared type.

Design

• u.Cli.is_json_option(annotation) (new, _options_parts/…part_01) is the single decision owner. It strips aliases and Annotated (u.Cli.unwrap_annotation, shared with the resolver), resolves subscripted type-alias origins (t.MappingKV[...] → Mapping), and flags Mapping subclasses, m.BaseModel subclasses, and generics/unions carrying them.
• u.Cli.resolve_typer_annotation returns str for those fields (the old dict branch is gone).
• u.Cli.framework_build_parameter(..., json_annotation=...) sets the Typer parser and the JSON metavar. The parser builds TypeAdapter(<declared type>) only at parse time and runs validate_json; a Pydantic error becomes typer.BadParameter chained from the ValidationError (Click's parser hook otherwise drops a ValueError's text). cli.execute_app returns it as e.fail_validation with the Pydantic cause; cli.invoke_app exits 2 before the handler runs.
• u.Cli.field_default renders a JSON option's default (settings first, then model default/factory, including nested model instances) as JSON text through u.to_json; the old per-entry mapping normalization and the now-unused t.Cli.MutableDefaultMapping alias are removed.
• Help appends c.Cli.CLI_JSON_OPTION_HELP to the field description and shows the JSON metavar and the JSON default.

Fail-loud fix

FlextCliPromptsSupport._print_message caught a logger failure and returned a formatted failed Result. The catch is removed so the failure propagates with its cause; the per-caller error templates that only fed that branch are removed from prompts.py.

Tests (behavioural, public surface, no mocks)

New tests/unit/test_model_command_json_options.py registers cli.model_command in a real app:

• valid JSON mapping reaches the model; nested model and list[model] options reach the model;
• omitted JSON options deliver model defaults, or settings values when a settings model is given;
• malformed JSON (json_invalid) and wrong types (int_parsing) fail: invoke_app not succeeded and handler not called; execute_app is a failed Result carrying the Pydantic error type;
• --help renders the JSON options with the JSON metavar.

test_options_public_cov updated to the new contract (mapping resolves to str; mapping default is JSON text that decodes to the settings value).

Validation (lane worktree /home/marlonsc/flext-work/v8-cli-mapping/flext-cli)

• make gen ×2: exit 0 both, identical diff (fixed point).
• make check: exit 0, Total: 1 Success: 1 Failed: 0 (lint, pyrefly, mypy, pyright, silent-failure, security, … OK; duplication/codemod/boundary/namespace/runtime-census are SUSPENDED by the check owner under flext-itpd1.3).
• make test-full: exit 0, incremental 78 passed, full 1202 passed, 0 failures.

Residuals (not changed here)

• u.Cli.build_model_command (_utilities/model_commands.py Builder) is a second model-command path that passes raw field annotations to Typer, so it still cannot handle mapping fields; it duplicates cli.model_command.
• u.Cli.field_default still catches c.EXC_VALIDATION_TYPE_VALUE and maps a non-CLI default to None.
• Other CLI_SAFE_EXCEPTIONS catches in _prompts_support.py (_run_or_fail) were not flagged and remain.

🤖 Generated with Claude Code

---

Summary by cubic

Fixes model commands with mapping fields — previously a dict Typer option that Typer rejects at invocation — and makes prompt printing fail loud.

A model field without a native CLI form (a mapping, a nested model, or a collection/union carrying one) now becomes one string option with the JSON metavar. Pydantic validates the text into the field's declared type at parse time.

• Malformed JSON or a schema mismatch is a usage error, and execute_app returns it with the Pydantic cause.
• Defaults (settings first, then the model) render as JSON text; help shows the format marker and never builds an adapter.
• _print_message no longer swallows logger failures — they propagate with their cause, and the per-caller error templates are removed.

^{Written for commit dbcdb0e. Summary will update on new commits.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud