89 lines
5.2 KiB
Markdown
89 lines
5.2 KiB
Markdown
# CommandKit v0.3.0
|
|
|
|
## Summary
|
|
|
|
CommandKit v0.3.0 moves core to `go.maximumdirect.net/commandkit`, adds
|
|
application-owned command and flag aliases, shared invocation reporting, and
|
|
shell completion. 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.
|
|
- Install the optional `Completion` command and declare static choices or
|
|
path hints for interactive shell completion. Bash, Zsh, and Fish scripts
|
|
use the application's captured commands and routing metadata.
|
|
- Maintainer release tooling now uses the root-selected ReleaseKit v0.9.0 tool,
|
|
with separate source publication and optional page-only hosted delivery.
|
|
|
|
## Compatibility and migration
|
|
|
|
Change core imports from `gitea.maximumdirect.net/eric/CommandKit` to
|
|
`go.maximumdirect.net/commandkit` and select v0.3.0. These paths identify
|
|
different Go packages, so their types cannot be mixed. Applications using the
|
|
integrations should migrate together to the forthcoming matched
|
|
`go.maximumdirect.net/ckconfig v0.2.0` and
|
|
`go.maximumdirect.net/ckprompt v0.2.0` releases, which depend on the new core;
|
|
the existing integration releases retain their old identities.
|
|
|
|
`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://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/docs/consumers/guide.md),
|
|
[CLI reference](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/docs/cli.md),
|
|
and [maintainer release procedure](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/docs/release.md).
|
|
|
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/COPYRIGHT) |
|
|
[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/LICENSE) |
|
|
[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.3.0/docs/oss/attribution.md)
|