feat(cli): groups can declare inheritable flags

[bradfair]

Summary

Groups can now declare flags that descend to every leaf via a ctx-carried registrar stack:

• Group.Flags func(*flag.FlagSet) — optional group-level closure.
• WithAncestorFlags / ApplyAncestorFlags — ctx stack append / replay.
• DeclareString / DeclareBool — Lookup-guarded wrappers for ancestor closures (stdlib panics on duplicate declarations). Leaves declare first, ancestors no-op on conflicts, so "leaf wins."
• Flagger interface — opt-in: leaves that implement Flags(fs) get an auto Flags: block in --help, enumerating own + ancestor flags via renderFlagsAsText.
• Group.Help() surfaces group-level flags so ana <group> --help shows them too.

Unblocks the connector-tree phase where dialect Groups will own common flags (--name, --account, --warehouse) reused across auth-mode leaves.

Independent of fix/global-flags-help-visibility; can merge in either order.

Summary by CodeRabbit

• New Features

  • Command groups can declare flags that are inherited by descendant subcommands; leaf help now lists inherited flags alongside local ones.
  • Group help output includes a formatted "Flags:" section showing group-level flags.

• Bug Fixes

  • Prevented duplicate-flag registration errors when flags are re-declared across hierarchy.

• Tests

  • Added comprehensive tests for flag inheritance, ordering, precedence, rendering, and help output.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1d0eca26-7f0e-40cb-998b-b39287579768

📥 Commits

Reviewing files that changed from the base of the PR and between bdd30f0 and fef75ff.

📒 Files selected for processing (1)

• internal/cli/root.go

---

📝 Walkthrough

Walkthrough

Adds context-backed stacking of ancestor flag registrars and propagates group-declared flags to descendant leaf commands; introduces guarded flag declaration helpers, a Flagger interface, help rendering of accumulated flags, and tests covering propagation, rendering, and precedence.

Changes

Cohort / File(s)	Summary
Flag stacking & helpers internal/cli/root.go	Add WithAncestorFlags(ctx, reg), ApplyAncestorFlags(ctx, fs), DeclareString, DeclareBool, and Flagger interface to accumulate/apply ancestor flag registrars and avoid duplicate registrations.
Group-level flags & help rendering internal/cli/cli.go	Add Group.Flags func(*flag.FlagSet) field; inject group flags into context in Group.Run; augment Group.Help and leaf help flow to apply ancestor flags and append a formatted Flags: block. Add renderFlagsAsText(*flag.FlagSet) and import flag.
Tests for propagation, rendering, precedence internal/cli/cli_test.go	Add flagLeaf test helper and Phase-2 tests verifying ancestor flag application order, non-panicking application with no registrars, guarded declarations, renderFlagsAsText output rules, group->leaf propagation (including nested groups), and leaf-overrides-ancestor precedence.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Group
  participant Context
  participant Leaf
  participant FlagSet

  User->>Group: invoke command
  Group->>Context: WithAncestorFlags(g.Flags) (push registrar)
  Group->>Leaf: dispatch named child
  Leaf->>FlagSet: create temporary FlagSet
  Leaf->>Context: ApplyAncestorFlags(ctx, FlagSet) (invoke registrars in order)
  Leaf->>FlagSet: declare leaf flags (DeclareString/Bool guards)
  alt help requested
    Leaf->>FlagSet: parse/format flags
    Leaf-->>User: help + renderFlagsAsText(FlagSet)
  else run
    Leaf->>FlagSet: parse args
    Leaf-->>User: execute
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat(e2e): comprehensive live-smoke coverage across all captured verbs #18: Modifies leaf help dispatch and Group.Run behavior; closely related to changes that detect and render help for leaf commands with ancestor flags.

Poem

🐰 I stack my flags in tunnels neat,
Ancestors pass down every treat,
Leaves read the map and choose their own,
Order kept in every stone —
Happy hops for flags complete!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%.	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 accurately summarizes the main change: enabling groups to declare flags that can be inherited by leaf commands.
Description check	✅ Passed	The description comprehensively covers the feature, including new types, functions, and mechanisms, with clear implementation details and context about blocked features.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 feat/group-inheritable-flags

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/cli/root.go`:
- Around line 10-35: The call in WithAncestorFlags performs an unnecessary type
conversion when appending reg; remove the redundant conversion and append reg
directly (i.e., replace flagRegistrar(reg) with reg) so the function still
builds next from prior and reg; check symbols: WithAncestorFlags, flagRegistrar,
ancestorFlagsKey, prior, next to locate the change.

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4d94c5b8-9aef-45b7-b9a4-e00c9948edf6

📥 Commits

Reviewing files that changed from the base of the PR and between d027d39 and bdd30f0.

⛔ Files ignored due to path filters (1)

• internal/cli/CLAUDE.md is excluded by !**/*.md

📒 Files selected for processing (3)

• internal/cli/cli.go
• internal/cli/cli_test.go
• internal/cli/root.go