diff --git a/docs/roadmap/shared-debug-binding.md b/docs/roadmap/shared-debug-binding.md index a2aa256..7222a66 100644 --- a/docs/roadmap/shared-debug-binding.md +++ b/docs/roadmap/shared-debug-binding.md @@ -42,10 +42,18 @@ the starting point; applications should not scan or reparse arguments. ### Bind the debug boolean independently -An application opts into receiving `--debug` in its command input through a -`Flag[I]` and the existing typed setter model. Exact construction and metadata -rules are subject to OD-1 and OD-2. Commands without such a binding retain the -standard core flag and reporting behavior. +OD-1 is resolved: an application declares a normal `BoolFlag` with +`FlagMeta.Name` set to `debug`. CommandKit attaches that binding to the existing +core flag. The application uses the same `Flag[I]`, `Supplied[bool]`, command +binding list, and typed setter model as for other boolean flags. No dedicated +`DebugFlag` constructor is planned. Metadata rules remain open in OD-2. +Commands without such a binding retain the standard core flag and reporting +behavior. + +This choice keeps the application API familiar and avoids another public +constructor. Core handles shared registration internally; an arbitrary +string-valued or custom-parser flag named `debug` is not equivalent to the +selected boolean binding merely because its name matches. The ordinary shared binding receives `Supplied[bool]`: omission produces `Value=false, Set=false`; an explicitly supplied false produces @@ -108,9 +116,9 @@ resolved mode. A second accessor on `Reporter` is unnecessary for this scope. ## Implementation work -1. **Settle binding construction and metadata.** Resolve OD-1 and OD-2 before - making the registration exception. Document which declaration attaches to - the core flag and how its application metadata is handled. Preserve ordinary +1. **Implement ordinary binding attachment and settle metadata.** Use the + selected `BoolFlag` form and resolve OD-2 before making the registration + exception. Document how its application metadata is handled. Preserve ordinary validation for unrelated names and bindings; do not broadly disable reserved name or collision checks. 2. **Connect shared parsing to typed input.** Update declaration validation, @@ -179,27 +187,6 @@ whitespace only. Implementation and the unchecked items above remain future work ## Open Decisions -### OD-1: How does an application declare the shared binding? - -**Recommendation:** recognize a normal `BoolFlag` with `FlagMeta.Name` set to -`debug` as attachment to the existing core flag. It returns the same `Flag[I]`, -uses `Supplied[bool]`, and occupies the normal command binding list. This most -directly meets the request that using debug should feel like using other flags -and avoids another public constructor. The cost is special handling of a -core-owned name, particularly the metadata rules in OD-2. Do not interpret an -arbitrary string-valued or custom-parser flag named `debug` as equivalent merely -because its name matches. - -**Viable alternative:** add a dedicated constructor such as -`DebugFlag[I](set func(*I, Supplied[bool])) Flag[I]`. This still uses the ordinary -typed binding and composition path, but makes attachment explicit and avoids -exposing conflicting declaration options. It adds public API vocabulary and -makes debug construction different from other booleans. Prefer this if ordinary -`BoolFlag` reuse needs substantial metadata reconciliation or confusing exceptions. - -The example constructor name is illustrative; choose one binding form rather -than adding both entry points without a demonstrated need. - ### OD-2: Which application metadata can accompany a shared flag? **Recommendation:** retain the core boolean grammar and false default. Allow @@ -208,9 +195,8 @@ core reporting help, and allow a local short spelling through existing alias and collision rules. Keep one displayed option. Continue using core boolean completion. Under the ordinary `BoolFlag` approach, report conflicting default, requiredness, or completion overrides as declaration errors rather than silently -ignoring them. A dedicated constructor could instead omit those options. These -are proposed rules for the shared attachment only, not accepted new restrictions -on ordinary application flags. +ignoring them. These are proposed rules for the shared attachment only, not +accepted new restrictions on ordinary application flags. This preserves consistent debug input across applications and avoids help that claims a default or requirement different from the shared flag. Its tradeoff is @@ -229,5 +215,6 @@ allow local metadata to change core reporting selection. **Simpler help alternative:** retain core flag help unchanged and put application effects in the command description, with short spellings supplied through the existing `FlagAliasFor` mechanism. This avoids help merging, at the cost of less -convenient flag-local documentation. It combines naturally with the dedicated -constructor in OD-1. There is no need for a general metadata-merging framework. +convenient flag-local documentation. With ordinary `BoolFlag` registration, +this alternative would also need to explain how supplied usage text and short +spellings are handled. There is no need for a general metadata-merging framework.