Shared debug binding and reporting-mode access

Status: implemented and verified. OD-1 and OD-2 are resolved; no significant open decisions remain. The implementation plan owns the ordered stages and verification. Baseline: 69257066e21c12ea3492237ebee072598adea60c.

Purpose and authority

Applications should be able to receive the boolean value of CommandKit's --debug flag through normal typed input binding. Applications that need the resolved reporting mode should also have a read-only invocation API.

The original Audita request motivated this work. Subsequent discussion selected a broader distinction: application debug behavior and CLI reporting visibility are separate choices. Audita's original requirement that capture follow reporting mode is an application policy, not a CommandKit requirement. This roadmap records the agreed direction from that discussion; it does not treat every proposal in the original request as accepted.

The architecture policy and ADR 0006 already assign CLI mechanics to core and domain behavior to applications. This work fits those boundaries and does not require another ADR. Implemented behavior remains documented in Go declarations and the CLI reference until this work lands.

Current baseline

Area	Current implementation	Work needed
Typed binding	`BoolFlag` in binding.go converts supplied occurrences and applies the last boolean with `Supplied[bool]` presence.	Let a binding receive the existing core debug flag's input.
Registration	`FlagMeta` and `validateBindings` in command.go reserve every reporting name, including `debug`.	Recognize the selected shared-binding form without treating it as an independent competing flag.
Parser metadata	commandmeta separates `CoreFlags` from consumer-indexed `Flags`; parser.go supplies core flags to each command.	Preserve consumer binding identity and indexes while sharing one parser declaration.
Backend	internal/cobra/parse.go registers both lists, records occurrences, and extracts indexed values only for consumer flags.	Supply shared debug values and spellings to the participating binding without duplicate backend registration.
Reporting	`reduceReportingOccurrences` in parser.go resolves the mutually exclusive mode from ordered occurrences.	Preserve that reduction independently of the bound debug boolean.
Invocation	execute.go applies reporting selection before input preparation and execution. reporter.go stores the mode privately; Invocation exposes no mode query.	Expose the already resolved selection through a CommandKit-owned public type.

Simply permitting the name in registration is insufficient: the backend would otherwise receive two declarations for debug. Existing occurrence capture is the starting point; applications should not scan or reparse arguments.

Targeted end state

Bind the debug boolean independently

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. Application metadata follows the accepted OD-2 decision below. 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 shared binding receives Supplied[bool]: omission produces the application's declared default with Set=false; an explicitly supplied false produces Value=false, Set=true. Repeated debug occurrences follow ordinary boolean binding semantics: every supplied value must be valid, and the last value wins. Other reporting flags do not rewrite the bound debug value.

Shared bindings retain ordinary capture, identity, presence, and application semantics through CaptureFlags, FlagValues.ApplyTo, and ApplySuppliedTo. Renaming the boolean to an ordinary application name makes it independent of core debug input while retaining its ordinary binding behavior.

The following examples appear after a complete command path. They show the ordinary false-default binding and the existing mode-selection rules together:

Arguments	Debug value	Supplied	Resolved reporting mode
None	false	false	Ordinary
`--debug`	true	true	Debug
`--debug --quiet`	true	true	Quiet
`--quiet --debug`	true	true	Debug
`--debug --verbose`	true	true	Verbose
`--debug --debug=false`	false	true	Ordinary
`--verbose --debug --debug=false`	false	true	Ordinary
`--debug --quiet=false`	true	true	Debug
`--debug --progress=false`	true	true	Debug

Aliases use the same canonical debug input. Tokens consumed as other flag values or appearing after -- keep their existing meaning. Invalid reporting booleans remain usage failures without handler execution. Existing placement, help, and input-preparation timing continue to apply.

Application code can use the bound value for diagnostic artifacts even when quiet mode suppresses ordinary CLI output. Core continues to own reporting visibility; applications own capture, redaction, file lifecycle, and any other domain effects. No capture policy is imposed on Audita or other applications.

Honor application binding settings, help, and aliases

OD-2 is resolved: honor ordinary application binding settings while keeping core reporting selection independent. Application defaults and requiredness affect the receiving binding; they do not select a reporting mode. Core continues to resolve reporting from explicit CLI occurrences under the existing rules.

For example, a non-required binding with a true default receives Value=true, Set=false when debug is omitted, while reporting remains ordinary in the absence of mode flags. An explicit --debug=false overrides that default. With --debug --quiet, the binding receives true while reporting is quiet. Requiredness follows ordinary presence semantics: if required, omission is a usage failure, while an explicit false satisfies the presence requirement. An application default does not count as explicit input.

Honor the application's short spelling through existing alias and collision rules. Both that spelling and other registered aliases feed the same canonical debug input and reporting occurrence sequence.

Show one debug option in command help, combining the core reporting explanation with any application-specific usage text. Clearly label an application default that differs from core behavior, so a true application default does not imply that debug reporting is enabled by default. Show application requiredness using the existing help conventions. Keep ordinary boolean binding completion behavior and metadata handling; this feature adds no special rejection of completion settings. Completion suggestions do not change the shared boolean grammar.

This choice keeps ordinary BoolFlag settings useful without adding restrictions solely for shared registration. The distinction between application input and reporting selection must be clear in help and consumer guidance. Implement this small combination directly; a general metadata-merging framework is unnecessary.

Query the resolved reporting mode

Add a CommandKit-owned ReportingMode type with ordinary, quiet, verbose, and debug values, and one canonical accessor:

func (inv Invocation) ReportingMode() ReportingMode

Use ReportingModeOrdinary, ReportingModeQuiet, ReportingModeVerbose, and ReportingModeDebug as the planned constant names, with ordinary as zero. The accessor reads the existing selection without output or mutation. The mode is final when the handler receives the invocation and remains its selection after execution finishes. A manually constructed zero-value invocation returns ordinary. Reads are compatible with concurrent reporting on that invocation; this does not add concurrent dispatch support or extend writer lifetimes.

An application deliberately following reporting visibility can use:

captureArtifacts := inv.ReportingMode() == commandkit.ReportingModeDebug

This reports the selected mode, not whether output was delivered successfully. Progress and report format remain separate selections. Keep the public type independent of internal/backend types and avoid a second mutable copy of the resolved mode. A second accessor on Reporter is unnecessary for this scope.

Scope and documentation

This is core work. It does not require ConfigKit or PromptKit API additions or adoption of Audita's artifact implementation. Binding other core flags, adding mode setters, or creating a general flag-sharing framework is not part of this sprint; that scope limit is not a permanent prohibition on later capabilities.

Completion criteria

The table above supplies representative boundary expectations. The implementation plan assigns test ownership and verification under the testing policy.

A registered application command receives the shared debug boolean and presence through normal typed input preparation, including when quiet or verbose becomes the resolved reporting mode.
The public query returns the selected mode without changing visibility; cover zero value, retained invocation, and fresh selection on subsequent runs.
Focused coverage establishes safe mode reads during existing concurrent reporter use, without asserting concurrent dispatch support.
Exercise aliases, explicit false, repeated values, invalid booleans, and option-looking operands/values where they establish the new binding boundary. Preserve existing failure precedence and no-handler-on-parse-failure behavior.
A command with both shared debug and ordinary flags receives the correct values; help and completion describe one effective debug option. Exercise representative capture/application composition and any affected rename path.
Cover a true application default without debug reporting, explicit false overriding that default, and ordinary requiredness/presence behavior. Help combines core and application explanations and distinguishes the application default; local short spellings use existing collision and alias rules.
The allowed boolean binding is accepted while unsupported/custom-parser debug declarations and other reserved reporting declarations retain their ordinary validation. Metadata handling adds no debug-specific restrictions beyond the selected boolean binding contract.
GoDoc and consumer guidance distinguish boolean input from reporting mode, and canonical docs describe the implemented registration exception.

Canonical binding and invocation GoDoc, the CLI reference, consumer guidance, and the applicable core release note will describe the implemented exception and mode query. The implementation plan records the completed work and verification.

11 KiB Raw Blame History