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](../cli.md#reporting)
and [consumer migration guide](../consumers/guide.md#invocation-reporting) 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](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.3.0/docs/consumers/guide.md),
[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.3.0/docs/cli.md),
and [maintainer release procedure](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.3.0/docs/release.md).

[COPYRIGHT](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.3.0/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.3.0/LICENSE) |
[ATTRIBUTION](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/v0.3.0/docs/oss/attribution.md)