[renovate]

This PR contains the following updates:

Package	Type	Update	Change	Pending
usage	tools	major	6.12.1 → 7.1.0	7.1.1

Release notes are maintained in a PR comment by the renovate-release-notes-comment workflow.

---

Configuration

📅 Schedule: (in timezone America/Los_Angeles)

• Branch creation
  • Between 03:00 AM and 05:59 AM (* 3-5 * * *)
• Automerge
  • At any time (no schedule defined)

🚦 Automerge: Enabled.

♻ Rebasing: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.

[scottames-github-bot]

Renovate Release Notes

Generated from Renovate's update table by the renovate-release-notes-comment workflow.

Packages that cannot be summarized from GitHub releases are listed explicitly below.

jdx/usage (usage)

v7.1.0: v7.1.0: Effect v4 CLI exporter and bash completion escaping

Compare Source

This release adds usage-spec-effect, a new npm package that turns Effect v4 effect/cli command trees into usage specs. It also fixes bash completions from usage-argv, which could pass the command a different value than the one offered when a candidate contained quotes, spaces or other shell syntax.

Added

• (spec) usage-spec-effect exports a usage spec from an Effect v4 effect/cli command tree (#1564, @​jdx). Effect still parses and runs the CLI, and the spec drives shell completions, markdown docs and man pages. It requires effect 4.x.

  npm install usage-spec-effect

  import { generate } from "usage-spec-effect";
  
  if (process.argv.includes("--usage-spec")) {
    process.stdout.write(generate(app, { version: "1.0.0" }));
    process.exit(0);
  }

  mycli --usage-spec | usage generate completion bash mycli --file -

  The exporter handles nested subcommands, aliases, unlisted commands, examples, shared flags (exported as global), flag aliases, boolean and valued flags, choices, defaults, and optional and variadic args. Some constructs can only be exported approximately: orElse alternatives, file, redacted and key-value types (exported as strings), non-primitive defaults, and flags with an optional value. generateWithReport returns these in an unsupported list so they aren't dropped without notice. Effect's public Command type doesn't expose flags or arguments, so the exporter reads the command's runtime config. If a future Effect release changes that shape, generate throws an error that names the command. See the Effect integration guide.

Fixed

• (bash) usage-argv and usage-dynamic now escape bash completion candidates so the command gets the value that was offered (#1566, @​jdx). Before this fix, Readline put candidates on the line unescaped, so a candidate like tasks."hello.sh" reached the command as tasks.hello.sh, and it's here left an unclosed quote on the line. Candidates are now backslash-escaped. When a quote is already open in the word (', " or $'), each candidate is escaped for that quote style instead. Path completions still use Readline's own filename quoting, and zsh and fish were already correct. Hosts handling __complete_word__ should call render_request(&answer, &request) instead of render(&answer, shell) so the open-quote state is used. App::completion_request in usage-dynamic already does this. The script-based bash completions behind usage complete-word are unchanged, since compgen -W can't carry spaces or quotes in candidates.

Full Changelog: jdx/usage@v7.0.2...v7.1.0

💚 Sponsor usage

usage is built and maintained by @​jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

v7.0.2: v7.0.2: Completion honors .usage.kdl sidecars and shows help for short flags

Compare Source

Two completion fixes: completing a script now uses the same .<script>.usage.kdl sidecar spec that usage exec runs with, and short flags show their help text in completion menus.

Fixed

• (complete) usage complete-word -f <script> now reads a .<script>.usage.kdl file next to the script before falling back to its USAGE comments, the same lookup usage exec already did (#1558, @​jdx). Before this, a script with a sidecar completed against the comment spec, or against nothing at all. The bash, zsh and fish scripts from usage generate completion-init call complete-word, so they get the fix without being regenerated. Other usage generate subcommands that take -f <script>, such as completion and markdown, now prefer the sidecar too. When the sidecar doesn't set name or bin, the script's basename is used. Inline specs and stdin input work as before.
• (complete) Short flags now show their help text in completion menus, as long flags already did (#1561, @​Ehsan-hash). For flag "-v --verbose" help="Verbose output", completing -v used to show no description and now shows Verbose output. If a root command and a subcommand both define the same short flag, the menu shows the help for the flag that actually applies. Bash completions still list flag names only, with no descriptions.

New Contributors

• @​Ehsan-hash made their first contribution in #1561

Full Changelog: jdx/usage@v7.0.1...v7.0.2

💚 Sponsor usage

usage is built and maintained by @​jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

v7.0.1: v7.0.1: Smaller usage-argv help, completion and error rendering code

Compare Source

This release reduces how much code usage-argv adds to CLIs that embed it. Help, -h, version, completion and parse-error output stay byte-for-byte the same, and startup and parse speed are unchanged.

Changed

• (lib) Help, completion and error rendering in usage-argv produce less machine code (#1551, #1553, #1554, @​jdx). String appends, text wrapping, slicing, searching, completion splitting and error suggestions now go through shared helpers instead of being expanded at every call site. In stripped release builds of oxlint and oxfmt, the three PRs together removed about 85 KB from each binary. That covers most of the size those CLIs gained when they moved from bpaf to usage-rs.

Fixed

• (complete) Split::walked and Split::argv no longer panic when cword is out of range. They now return the whole word list and an empty slice (#1554, @​jdx).

Full Changelog: jdx/usage@v7.0.0...v7.0.1

💚 Sponsor usage

usage is built and maintained by @​jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

v7.0.0: v7.0.0: Derive macros no longer read Cargo.toml; usage generate fig removed

Compare Source

The derive macros now generate code against usage_rs directly instead of reading your Cargo.toml, usage generate fig has been removed, and the fields on argv metadata types are no longer public API. usage exec now accepts interpreter arguments, and this release also fixes how -- is handled by the shell runners and how multi-line examples are indented in help.

Breaking Changes

All of these come from #1532 (@​jdx).

• The derive macros always generate paths through ::usage_rs. In 6.12, usage-derive parsed your Cargo.toml to work out how usage-rs was imported. That put toml and related crates into every downstream build. The macros no longer read the manifest, so toml is out of the dependency tree. If a derive can't find the facade crate, compilation fails with unresolved import usage_rs. To upgrade:
  • Depend on usage-rs under its own name: usage-rs = { version = "7" }.
  • If you import it under another name, such as usage = { package = "usage-rs", ... }, add #[usage(crate = usage)] to each derive that needs it. The attribute works on Cli, Args, Subcommands, ValueEnum, ArgGroup and Config, and you have to repeat it on every derive.

    #[derive(usage::Cli)]
    #[usage(crate = usage, bin = "ex")]
    struct Ex { /* ... */ }

  • If you depend directly on usage-argv, usage-derive, usage-config or usage-validation, also add usage-rs = { version = "7", default-features = false, features = ["spec"] }. Turn on the config or validation features if you use those crates, since they're now reached through usage_rs::config and usage_rs::validation.
  • schema_from = T now always generates ::schemars. If you renamed the schemars dependency, change it back to its real name.
  • The derives no longer look up workspace-inherited or target-specific dependencies.
• usage generate fig is removed. Fig shut down in 2024. Use usage generate completion <shell> instead.
• Fields on FlagMeta, CommandMeta and ArgMeta in usage-argv are now #[doc(hidden)]. Their struct layout is no longer covered by semver. Use the existing accessor methods instead, for example flag.env_fallback() rather than flag.env_fallback.

Added

• (cli) usage exec takes a quoted interpreter followed by its own arguments, and splits them the way a shell would (#1537, @​jdx). Before this, there was no shebang form for interpreters that need flags before the script path, such as Deno's run and its permission flags. Values without whitespace, values that are paths to existing files, and the unquoted form all work as before.

  #!/usr/bin/env -S usage exec "deno run --allow-env=usage_*"
  //USAGE arg "<name>" help="Name to greet"

Fixed

• (cli) In usage bash, zsh, fish and powershell, words after -- now reach the script as values (#1541, @​jdx). Previously, usage bash script.sh positional -- --help printed the script's help with an Error: prefix and exited with status 1. -h and --help still show help when they come before --.
• (cli) In --help output, every line of a multi-line example is now indented (#1548, @​jdx). Before, sample output lines after the first started at column 0.

Full Changelog: jdx/usage@v6.12.1...v7.0.0

💚 Sponsor usage

usage is built and maintained by @​jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.