Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: jdx/usage
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v3.1.0
Choose a base ref
...
head repository: jdx/usage
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: v3.2.0
Choose a head ref
  • 3 commits
  • 26 files changed
  • 4 contributors

Commits on Mar 23, 2026

  1. fix(zsh): escape parentheses and brackets in completion descriptions (#… 

    …559)

## Summary

- Escape `(`, `)`, `[`, `]` in zsh completion output to prevent
`_describe` from interpreting them as glob qualifiers/character classes
- Extract a `zsh_escape()` helper that handles all zsh-special
characters (colons, parens, brackets)
- Add test fixture and integration test verifying the escaping

Fixes #558

## Test plan

- [x] New test `complete_word_zsh_escapes_parens_and_brackets` verifies
escaped output
- [x] Verified test fails without the fix (parentheses/brackets passed
through unescaped)
- [x] Full test suite passes
- [x] Clippy clean

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: only adjusts zsh completion output formatting by adding
additional escaping, with coverage via a new integration test.
> 
> **Overview**
> Fixes zsh completion output for `_describe` by escaping additional
special characters in `name:description` entries. The previous inline
colon escaping is replaced with a shared `zsh_escape()` helper that also
escapes `(`, `)`, `[` and `]` to prevent glob/character-class
interpretation.
> 
> Adds an integration test plus a new example spec to verify zsh output
is correctly escaped for descriptions containing parentheses/brackets
(and colons).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
f165847. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
    @jdx @claude
    jdx and claude authored Mar 23, 2026
    Configuration menu
    Copy the full SHA
    1f26b3d View commit details
    Browse the repository at this point in the history

  2. feat: Support env-backed choices with choices env=... (#548) 

    ## Summary
- add `env` support to `choices` so specs can source allowed values from
an environment variable
- honor `Parser::with_env(...)` without falling back to the process
environment when a custom env map is provided
- reject explicit values when `choices env=...` resolves to no values
instead of silently disabling validation
- preserve `choices env=...` when `SpecArgBuilder::choices()` is called
after `choices_env(...)`
- resolve env-backed choices for interactive shell completion at
completion time
- preserve `choices env=...` in help/docs instead of snapshotting live
env-backed values into generated output
- keep Fig suggestions literal-only so `usage generate fig` does not
bake generation-time environment values into a static file

## Example
```kdl
arg "<env>" {
  choices env="DEPLOY_ENVS"
}
```

With `DEPLOY_ENVS="foo,bar baz"`, valid values become `foo`, `bar`, and
`baz`.

## Implementation notes
- `choices` now accepts an optional `env` property and preserves it when
serializing back to KDL
- env-backed values are split on commas and/or whitespace, with empty
entries ignored
- env-backed values are appended after literal choices and deduplicated
against existing entries
- parsing uses the caller-provided env map when `Parser::with_env(...)`
is used; it only consults the process environment when no custom env map
is provided
- env-backed choices that resolve to no values now fail validation for
explicit CLI input with a targeted error message instead of accepting
any value
- `SpecArgBuilder::choices()` now preserves any previously configured
`choices_env(...)`
- help/docs render literal choices as before and also surface the
controlling env var for env-backed choices

## Tests
- unit tests for env choice splitting and deduplication
- parser tests covering arg/flag validation with `Parser::with_env(...)`
- parser test covering the empty env-backed choice set case
- builder test covering `.choices_env(...).choices(...)` ordering
- completion test covering env-backed choices
- dump test covering KDL round-tripping
    @mustafa0x
    mustafa0x authored Mar 23, 2026
    Configuration menu
    Copy the full SHA
    f1af365 View commit details
    Browse the repository at this point in the history

  3. chore: release v3.2.0 (#560) 

    ### 🚀 Features

- Support env-backed choices with `choices env=...` by
[@mustafa0x](https://github.com/mustafa0x) in
[#548](#548)

### 🐛 Bug Fixes

- **(zsh)** escape parentheses and brackets in completion descriptions
by [@jdx](https://github.com/jdx) in
[#559](#559)

### New Contributors

- @mustafa0x made their first contribution in
[#548](#548)
    @mise-en-dev
    mise-en-dev authored Mar 23, 2026
    Configuration menu
    Copy the full SHA
    1b428b7 View commit details
    Browse the repository at this point in the history
Loading