Skip to content

v0.9.0

Choose a tag to compare

@github-actions github-actions released this 13 Nov 17:34
Immutable release. Only release title and notes can be modified.
4965321

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 config tag or flag name, with conga.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: Counter rejects =N on the CLI, empty boolean values fail cleanly, repeated stdin reads are caught before coercion, and ./tool executables 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, keeporder support, and LS_COLORS SGR styling (#198, #199, #201).

⚠ Breaking Changes & Migration

Schema & startup guards

  • Built-in and Features flag collisions (#189, closes #148):
    • An ancestor --json flag with a mounted VersionCommand, or an ancestor flag colliding with a CLI-exposed Features flag, now fails schema build with ErrSchema. Rename the ancestor flag or rely on --version.
  • feature on implicit:"true" commands (#194, closes #160, #161):
    • Declaring a feature tag on an implicit:"true" command fails schema build with ErrSchema; gate the parent command or make the subcommand explicit.
  • bootstrap on FileContent (#187):
    • bootstrap:"true" on a FileContent field now fails schema build with ErrSchema; use conga.File and read it in Bootstrap.

Configuration

  • Exact config keys and nested sections (#183, closes #142, #143, #182):
    • Config keys must match the flag name or config tag exactly (api_endpoint no longer binds --api-endpoint by default and fails with ErrConfig, exit 1). Update your config file, set conga.ConfigKeyCase(conga.SnakeCase), or add config:"<key>".
    • Flag/subcommand aliases no longer work as config keys, dotted config tags map only to nested sections, and flags with an explicit config tag no longer fall back to their flag name.
  • <PREFIX>_CONFIG outranks conga.ConfigExplicit (#135, closes #117):
    • Config targets now resolve in order: --config-file > <PREFIX>_CONFIG > ConfigExplicit(path) > search paths. When <PREFIX>_CONFIG is set, a missing ConfigExplicit file is no longer read or errored on.
  • 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 int64 and uint64 ranges fail to load in JSON, YAML, and HCL with ErrConfig (exit 1), and the cause matches the decoder's own ErrParse (for example json.ErrParse). JSON and HCL also reject numbers that overflow float64.
  • .env escaped dollars (#195, closes #159):
    • \$ inside a double-quoted .env value is now a literal $ instead of starting variable expansion.

Command-line behaviour

  • Strict Counter flags (#186, closes #149):
    • Counter rejects attached CLI values (--verbose=2, -v=2); repeat the flag (-vv), set via env/config, or use OptionalFlag[int].
    • Negative and signed counts from env/config are rejected, and counter errors now say "unsigned integer".
  • Empty booleans rejected (#193, closes #171):
    • --flag=, empty map[string]bool values, and empty boolean config strings no longer mean true. Pass --flag or --flag=true.
  • FileContent, stdin, and repeated scalar flags (#187, closes #147, #150, #151, #152):
    • A scalar FileContent flag can only be given once on the CLI, and a second value reading - (across FileContent or File with stdin:"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.
  • File with executable:"true" resolves relative paths cleanly (#203, closes #188):
    • ./tool resolves in the working directory instead of $PATH, all executable paths are normalized to absolute paths, and missing/non-executable ./name fails with ErrValidation instead of ErrCoerce.

Errors & diagnostics

  • Source-based error categories (#190, closes #133, #162):
    • Env-, config-, and default-sourced value failures match ErrConfig only (exit 1, IsUsageError false) instead of ErrCoerce/ErrValidation (exit 2).
    • This replaces the v0.8.0 change that made config-sourced feature errors usage errors.
    • Unexpected arguments and negated flags with values match ErrParse; wrong path kinds match ErrValidation; missing Runner matches ErrSchema.
  • Group conflict attribution & --why (#192, closes #170):
    • xor, oneof, and and conflicts whose members all come from env/config match ErrConfig only (exit 1, IsUsageError false). Messages identify non-CLI members by source and CLI members by typed spelling; --why no longer aborts on group conflicts.
  • Updated error & --why=json formats:
    • --why=json reports bypassed search paths and overridden named files with paths[].status set 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_COLORS SGR codes and file-kind indicators (di, ln, or, ex, *<suffix>) in path predictors (#201, closes #156).

🐛 Bug Fixes

  • api: conga.TypeParser is again an alias of func(string) (U, error), so RegisterType accepts named function types as before v0.8.0 (#141).
  • completion: Write the bash lazy-load completion file under ${XDG_DATA_HOME:-$HOME/.local/share} and add an fpath fallback to the Homebrew zsh install steps (#141).
  • lint: conga-lint prints related notes, and its -test flag wins over a same-named analyzer flag (#141).
  • validation: Compare float32 range bounds at float64 precision and report exact ByteSize overflow limits and accepted units (#187, closes #147, #152).
  • cli: Allow repeated identical - stdin claims on a single scalar File/FileContent flag (#205).
  • config: Report errors in dotted namespace sections the same way as command sections (#205).
  • errors: Let errors.Is reach the underlying cause of config-sourced ErrConfig errors (#205).
  • cli: Fix pluralization and natural list joining in and-group errors, remove [command] from RawArgs usage lines, and route help <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 ConfigExplicit paths, and align Features: 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.Exclude uniformly across Batch, MultiParts, callbacks, and timeouts, let a predictor's own Usage take precedence over help, complete .. to ../, and ignore known_hosts pattern lines (#138, #202, closes #114, #116, #158).
  • completion: Support keeporder in Bash (compopt -o nosort) and Zsh (-V), convert Bash COMP_POINT from 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