Repository navigation
v0.9.0
Immutable
release. Only release title and notes can be modified.
CONGA v0.9.0 is a broad reliability release covering strict configuration key matching, source-aware error classification, stricter flag and input parsing, and cross-shell completion fixes.
🚀 Highlights
- Exact config key matching & casing options: Configuration files match keys strictly by
configtag or flag name, withconga.ConfigKeyCase(KebabCase,SnakeCase,CamelCase) for app-wide casing (#183). - Source-aware error classification: Environment-, config-, and default-sourced value and group failures now classify consistently under
ErrConfig(exit 1, no usage block) instead of usage errors (exit 2) (#190, #192, #205). - Stricter parsing & safer executables:
Counterrejects=Non the CLI, empty boolean values fail cleanly, repeated stdin reads are caught before coercion, and./toolexecutables resolve in the working directory rather than$PATH(#186, #187, #193, #203). - Cross-shell completion &
LS_COLORS: Multibyte cursor handling, quote/escape handling across Bash/Zsh/Fish/PowerShell/Nushell,keepordersupport, andLS_COLORSSGR styling (#198, #199, #201).
⚠ Breaking Changes & Migration
Schema & startup guards
- Built-in and
Featuresflag collisions (#189, closes #148):- An ancestor
--jsonflag with a mountedVersionCommand, or an ancestor flag colliding with a CLI-exposedFeaturesflag, now fails schema build withErrSchema. Rename the ancestor flag or rely on--version.
- An ancestor
featureonimplicit:"true"commands (#194, closes #160, #161):- Declaring a
featuretag on animplicit:"true"command fails schema build withErrSchema; gate the parent command or make the subcommand explicit.
- Declaring a
bootstraponFileContent(#187):bootstrap:"true"on aFileContentfield now fails schema build withErrSchema; useconga.Fileand read it inBootstrap.
Configuration
- Exact config keys and nested sections (#183, closes #142, #143, #182):
- Config keys must match the flag name or
configtag exactly (api_endpointno longer binds--api-endpointby default and fails withErrConfig, exit 1). Update your config file, setconga.ConfigKeyCase(conga.SnakeCase), or addconfig:"<key>". - Flag/subcommand aliases no longer work as config keys, dotted
configtags map only to nested sections, and flags with an explicitconfigtag no longer fall back to their flag name.
- Config keys must match the flag name or
<PREFIX>_CONFIGoutranksconga.ConfigExplicit(#135, closes #117):- Config targets now resolve in order:
--config-file><PREFIX>_CONFIG>ConfigExplicit(path)> search paths. When<PREFIX>_CONFIGis set, a missingConfigExplicitfile is no longer read or errored on.
- Config targets now resolve in order:
- Stricter HCL, JSON, and YAML decoding (#184, closes #145, #146):
- HCL labeled blocks and attribute/block name collisions fail to load instead of being dropped.
- Integers outside the
int64anduint64ranges fail to load in JSON, YAML, and HCL withErrConfig(exit 1), and the cause matches the decoder's ownErrParse(for examplejson.ErrParse). JSON and HCL also reject numbers that overflowfloat64.
.envescaped dollars (#195, closes #159):\$inside a double-quoted.envvalue is now a literal$instead of starting variable expansion.
Command-line behaviour
- Strict
Counterflags (#186, closes #149):Counterrejects attached CLI values (--verbose=2,-v=2); repeat the flag (-vv), set via env/config, or useOptionalFlag[int].- Negative and signed counts from env/config are rejected, and counter errors now say
"unsigned integer".
- Empty booleans rejected (#193, closes #171):
--flag=, emptymap[string]boolvalues, and empty boolean config strings no longer meantrue. Pass--flagor--flag=true.
FileContent, stdin, and repeated scalar flags (#187, closes #147, #150, #151, #152):- A scalar
FileContentflag can only be given once on the CLI, and a second value reading-(acrossFileContentorFilewithstdin:"true") is a usage error. - Repeated scalar flags coerce every occurrence instead of only the last, so an earlier invalid value now fails the run.
- A scalar
Filewithexecutable:"true"resolves relative paths cleanly (#203, closes #188):./toolresolves in the working directory instead of$PATH, all executable paths are normalized to absolute paths, and missing/non-executable./namefails withErrValidationinstead ofErrCoerce.
Errors & diagnostics
- Source-based error categories (#190, closes #133, #162):
- Env-, config-, and default-sourced value failures match
ErrConfigonly (exit 1,IsUsageErrorfalse) instead ofErrCoerce/ErrValidation(exit 2). - This replaces the
v0.8.0change that made config-sourced feature errors usage errors. - Unexpected arguments and negated flags with values match
ErrParse; wrong path kinds matchErrValidation; missingRunnermatchesErrSchema.
- Env-, config-, and default-sourced value failures match
- Group conflict attribution &
--why(#192, closes #170):xor,oneof, andandconflicts whose members all come from env/config matchErrConfigonly (exit 1,IsUsageErrorfalse). Messages identify non-CLI members by source and CLI members by typed spelling;--whyno longer aborts on group conflicts.
- Updated error &
--why=jsonformats:--why=jsonreports bypassed search paths and overridden named files withpaths[].statusset to"skipped"(#137, #185).- Feature errors drop the
"config error:"prefix, name their source, and render compound/negated gates in words (#194). - Unknown-flag suggestions use
'unknown flag: --prot (did you mean "--port"?)'(#196).
✨ Features
- config: Add
conga.ConfigKeyCase(KebabCase,SnakeCase,CamelCase) for derived config keys (#183). - completion: Honour
LS_COLORSSGR codes and file-kind indicators (di,ln,or,ex,*<suffix>) in path predictors (#201, closes #156).
🐛 Bug Fixes
- api:
conga.TypeParseris again an alias offunc(string) (U, error), soRegisterTypeaccepts named function types as beforev0.8.0(#141). - completion: Write the bash lazy-load completion file under
${XDG_DATA_HOME:-$HOME/.local/share}and add anfpathfallback to the Homebrew zsh install steps (#141). - lint:
conga-lintprints related notes, and its-testflag wins over a same-named analyzer flag (#141). - validation: Compare
float32rangebounds atfloat64precision and report exactByteSizeoverflow limits and accepted units (#187, closes #147, #152). - cli: Allow repeated identical
-stdin claims on a single scalarFile/FileContentflag (#205). - config: Report errors in dotted namespace sections the same way as command sections (#205).
- errors: Let
errors.Isreach the underlying cause of config-sourcedErrConfigerrors (#205). - cli: Fix pluralization and natural list joining in
and-group errors, remove[command]fromRawArgsusage lines, and routehelp <unknown>through command suggestions (#140, #196, closes #111, #124, #164). - features: Ignore config keys whose feature gate was disabled by a higher-precedence tier and exclude inactive members from suggestions (#194, closes #161).
- why: Report skipped search paths and overridden named config targets cleanly, preserve comma-containing
ConfigExplicitpaths, and alignFeatures:section spacing (#137, #185, closes #108, #122, #144). - dotenv: Accept a closing quote on the final line when no trailing newline is present (#195, closes #159).
- predict: Apply
Predictor.Excludeuniformly acrossBatch,MultiParts, callbacks, and timeouts, let a predictor's ownUsagetake precedence overhelp, complete..to../, and ignoreknown_hostspattern lines (#138, #202, closes #114, #116, #158). - completion: Support
keeporderin Bash (compopt -o nosort) and Zsh (-V), convert BashCOMP_POINTfrom characters to bytes, handle quotes/escapes across Bash/Zsh/Fish/PowerShell, and quote tabs, Unicode dashes, and empty args safely in PowerShell and Nushell (#198, #199, #201, closes #153, #154, #155, #157).
Full Changelog: v0.8.0...v0.9.0
Requirements: Go 1.27+ · Docs · pkg.go.dev