fix(settings): route flext-cli Field through m facade

[marlon-costa-dc]

Summary

• Replace direct pydantic.Field in _settings.py with flext_core.m.Field.
• Absorb concurrent Makefile custom-WHAT dispatch projection.

Test plan

• make check PROJECT=flext-cli CHECK_GATES=lint,format,pyrefly
• CI green

Made with Cursor

---

Summary by cubic

Routed flext-cli settings Field declarations through flext_core.m.Field to unify settings metadata and avoid direct pydantic usage. Also extended the Makefile dispatcher to support _custom_<verb>_<what> targets and tightened submodule setup behavior.

• Refactors

  • Replace pydantic.Field with flext_core.m.Field in FlextCliSettings.

• New Features

  • Makefile: Support _custom_<verb>_<what> and list them in help; submodule setup now skips unnecessary fetches, attaches the branch when appropriate, and shows clearer errors without discarding commits.

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

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Makefile now supports project-defined custom handlers, uses ancestry-based submodule setup checks, and documents both behaviors. CLI settings now use flext_core.m.Field without changing their field definitions.

Changes

Custom handler dispatch

Layer / File(s)	Summary
Custom handler resolution and help Makefile	_dispatch checks for _custom_<verb>_<what> handlers before validation and built-in execution. Help output documents and lists these handlers.

Submodule setup validation

Layer / File(s)	Summary
Ancestry-based submodule setup Makefile	Submodule setup uses gitlink and remote-branch ancestry checks to suppress fetches and conditionally attach detached HEADs. Divergence from the recorded gitlink remains rejected.

CLI settings metadata

Layer / File(s)	Summary
Shared field metadata src/flext_cli/_settings.py	CLI settings use m.Field from flext_core. Existing types, defaults, descriptions, and optionality remain unchanged.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the settings change and identifies the specific Field routing update.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bugfix/pydantic-settings-facade-cutover

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Makefile`:
- Around line 655-659: Guard both attach_branch_at_head call sites in the
detached-HEAD handling flow so an existing declared branch is accepted only when
it already points to the intended commit; if refs/heads/$$branch exists at a
different commit, reject the state and require manual reconciliation before
attaching HEAD. Preserve attachment when the branch is absent or already
matches, and ensure attach_branch_at_head is never allowed to overwrite
divergent local commits.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a2c0d444-efca-4b35-9659-81f26f535d86

📥 Commits

Reviewing files that changed from the base of the PR and between 922ebee and be013e0.

📒 Files selected for processing (2)

• Makefile
• src/flext_cli/_settings.py

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Do not force-move an existing declared branch.

attach_branch_at_head runs git branch -f "$$branch" HEAD. If refs/heads/$$branch already points to local commits, either detached-HEAD path can replace that ref with $$head. The prior commits become unreachable and can later be garbage-collected. This conflicts with the stated rule that setup does not discard commits.

Reject this state when the declared local branch exists at a different commit. Require the user to reconcile it before attaching HEAD.

Proposed safeguard

 attach_branch_at_head() { \
   child_root="$$1"; \
   branch="$$2"; \
+  head=$$(git -C "$$child_root" rev-parse HEAD); \
+  existing=$$(git -C "$$child_root" rev-parse --verify "refs/heads/$$branch" 2>/dev/null || :); \
+  if [ -n "$$existing" ] && [ "$$existing" != "$$head" ]; then \
+    printf 'ERROR: %s: local branch %s points to %s, not detached HEAD %s; reconcile it yourself\n' "$$child_root" "$$branch" "$$existing" "$$head" >&2; \
+    exit 1; \
+  fi; \
   git -C "$$child_root" branch --quiet -f "$$branch" HEAD || { \

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Makefile` around lines 655 - 659, Guard both attach_branch_at_head call sites
in the detached-HEAD handling flow so an existing declared branch is accepted
only when it already points to the intended commit; if refs/heads/$$branch
exists at a different commit, reject the state and require manual reconciliation
before attaching HEAD. Preserve attachment when the branch is absent or already
matches, and ensure attach_branch_at_head is never allowed to overwrite
divergent local commits.