commandkit/docs/releases/v0.3.0.md

CommandKit v0.3.0

Summary

CommandKit v0.3.0 adds application-owned command and flag aliases and shared invocation reporting. This pre-1.0 minor release also updates the installation declaration type and Invocation struct shape, replaces the error-first outcome and diagnostic-delivery APIs, and reserves reporting flag names; review the migration guidance before upgrading.

Changes

• Declare command shortcuts and global or canonical-command-scoped flag spellings with Alias, FlagAlias, and FlagAliasFor. Install routing rules beside canonical commands through New or App.Register. Aliases route to existing handlers and preserve the target command's operand and binding behavior.
• Read the entered and canonical command paths from Invocation with EnteredPath and CanonicalPath.
• Interpret a canonical short value flag such as -c= as an explicitly supplied empty value, consistent with --color= and -c "".
• Obtain an invocation-scoped Reporter from each handler's Invocation for substantive output, Warning/Info/Progress/Debug messages, deferred messages, and managed report rendering. The shared --quiet, --verbose, --debug, and --progress flags apply across core and integration commands.
• Return terminal explanation text with Failure, Usage, or Outcome.WithExplanation; attach an optional operation error separately with Outcome.WithCause. Returned Outcome.Presentation records output and diagnostic delivery observations without changing the operation cause.

Compatibility and migration

New and App.Register now accept ...Declaration instead of ...Command. Command, group, and integration command factories still return Command, so individual factory calls can be passed directly. A []Command cannot be expanded into ...Declaration; use a []Declaration for mixed reusable collections or convert each command element before expanding it. Function values whose parameter type is ...Command, including wrappers assigned from New or Register, must update their signature to ...Declaration.

Adding private route fields to Invocation means positional struct literals no longer compile. Invocation no longer contains Streams; App.Execute supplies the reporter and route paths to handlers. Streams remains the argument to App.Execute, where the caller owns the result and diagnostic writers.

Handlers that used invocation.Streams.Out or .Err should use invocation.Reporter().Output() or the categorized reporting methods. Replace Failure(err) and Usage(err) with an operator-facing explanation and an optional .WithCause(err); causes alone are not rendered. Replace Outcome.Diagnostics submissions and terminal SeverityError records with reporter messages and an Outcome explanation. Provider-returned Acquired.Diagnostics remain passive data for the owning integration to submit. Replace ReportIncomplete, DiagnosticDelivery, and DeliveryError with Outcome.Presentation.Output and .Diagnostics, whose DeliveryResult contains a state plus first render and write errors.

The long flags --quiet, --verbose, --debug, and --progress are reserved for CommandKit reporting and cannot be declared by applications. Application aliases may target them. See the current CLI reporting contract and consumer migration guide for their behavior and API examples.

The consumer minimum remains Go 1.26.0 and the maintainer release toolchain remains Go 1.26.8. Core v0.3.0 must be published before preparing dependent integration releases that adopt it and record downloaded dependency sums; this release does not change their v0.1.0 release records.

See the consumer guide, CLI reference, and maintainer release procedure.

COPYRIGHT | LICENSE | ATTRIBUTION