From 4069d0b9f5220e20935ab0bb526860f8c85fe686 Mon Sep 17 00:00:00 2001 From: default <216188+jdx@users.noreply.github.com> Date: Thu, 20 Aug 2026 08:07:45 +0000 Subject: [PATCH 1/4] fix(spec): preserve required root subcommands --- argv/src/spec.rs | 6 ++++++ lib/src/spec/mod.rs | 8 ++++++++ usage-rs/tests/facade.rs | 9 +++++++++ 3 files changed, 23 insertions(+) diff --git a/argv/src/spec.rs b/argv/src/spec.rs index 46c42996b..03858e9a3 100644 --- a/argv/src/spec.rs +++ b/argv/src/spec.rs @@ -1182,6 +1182,12 @@ impl Spec<'_> { if self.root.cmd.allow_missing_positional { writeln!(out, "allow_missing_positional #true")?; } + // Root metadata is written separately from `write_command`, so keep the required + // subcommand bit here as well. Without it a required typed enum still parsed correctly, + // but its emitted portable spec rendered `[COMMAND]` and accepted an empty invocation. + if self.root.subcommand_required && !self.root.cmd.subcommands.is_empty() { + writeln!(out, "subcommand_required #true")?; + } if let Some(heading) = self.root.subcommand_help_heading { prop(out, "subcommand_help_heading", heading)?; } diff --git a/lib/src/spec/mod.rs b/lib/src/spec/mod.rs index f3e331e4a..49fb6eb04 100644 --- a/lib/src/spec/mod.rs +++ b/lib/src/spec/mod.rs @@ -319,6 +319,9 @@ impl Spec { "allow_missing_positional" => { schema.cmd.allow_missing_positional = node.arg(0)?.ensure_bool()?; } + "subcommand_required" => { + schema.cmd.subcommand_required = node.arg(0)?.ensure_bool()?; + } "subcommand_help_heading" => { schema.cmd.subcommand_help_heading = Some(node.arg(0)?.ensure_string()?); } @@ -644,6 +647,11 @@ impl Display for Spec { node.push(true); nodes.push(node); } + if self.cmd.subcommand_required && !self.cmd.subcommands.is_empty() { + let mut node = KdlNode::new("subcommand_required"); + node.push(true); + nodes.push(node); + } if let Some(heading) = &self.cmd.subcommand_help_heading { let mut node = KdlNode::new("subcommand_help_heading"); node.push(string_entry(None, heading)); diff --git a/usage-rs/tests/facade.rs b/usage-rs/tests/facade.rs index 5864b84e3..e6b58c314 100644 --- a/usage-rs/tests/facade.rs +++ b/usage-rs/tests/facade.rs @@ -23,6 +23,15 @@ enum Command { Version, } +#[test] +fn required_root_subcommand_survives_spec_emission() { + let kdl = Ex::to_kdl(); + assert!(kdl.contains("subcommand_required #true"), "{kdl}"); + + let spec: usage_parser::Spec = kdl.parse().expect("usage-lib should read derive output"); + assert!(spec.cmd.subcommand_required); +} + #[derive(Cli)] #[command(bin = "negated-requirements", subcommand_negates_reqs)] #[allow(dead_code)] From 7503c6d9c8e52441ced7fb05f3165c277e4df82f Mon Sep 17 00:00:00 2001 From: default <216188+jdx@users.noreply.github.com> Date: Thu, 20 Aug 2026 08:07:45 +0000 Subject: [PATCH 2/4] test(fleet): refresh typed adopter fixtures --- PLAN.md | 12 +- benches/fleet/README.md | 13 +- benches/fleet/aube.usage.kdl | 4966 +++++++-------------- benches/fleet/communique.usage.kdl | 51 +- benches/fleet/fnox.usage.kdl | 189 +- benches/fleet/hk.usage.kdl | 868 ++-- benches/fleet/pitchfork.usage.kdl | 797 +--- benches/fleet/tak.usage.kdl | 97 +- benches/shadows/aube/src/lib.rs | 5683 +++++++++++++++---------- benches/shadows/communique/src/lib.rs | 3 +- benches/shadows/fnox/src/lib.rs | 69 +- benches/shadows/hk/src/lib.rs | 1134 +++-- benches/shadows/pitchfork/src/lib.rs | 630 ++- benches/shadows/tak/src/lib.rs | 143 +- 14 files changed, 7174 insertions(+), 7481 deletions(-) diff --git a/PLAN.md b/PLAN.md index 092422be8..d8fda3228 100644 --- a/PLAN.md +++ b/PLAN.md @@ -957,6 +957,11 @@ looking at the clap surface, not only at the spec. `--usage-spec` solely to expose the new canonical metadata; that new entry point has no clap-era behavior to preserve and is excluded from tak's compatibility baseline. + The six completed typed adopters now supply current `usage-rs` fixtures and + regenerated shadows for hk, fnox, pitchfork, aube, tak, and communique. Their + delimiter, optional-value, relationship, and command-policy metadata is therefore + visible to the gate. mise remains on its clap-era fixture until its router port can + emit the replacement metadata. - [x] **Docs and manpages on a fleet spec.** communique's checked-in spec and the KDL its shadow emits render the same markdown (index and every command) and the same manpage. usage-cli's own @@ -1042,9 +1047,10 @@ a prerequisite for trying a CLI. parsers. Adoption is measured by what it lets mise delete, listed below. Do not start this until the clap-only rows in **Trying the fleet** that mise actually uses are either implemented or accepted as lost. -- [ ] **pitchfork** — not part of the five typed experiments, but already - generates its spec from clap. It is the next small adopter after those - experiment branches become mergeable. +- [x] **pitchfork** — jdx/Pitchfork#754 removes clap, parses its typed command tree + with `usage-rs`, uses the built-in completion protocol, and passes its Rust and + bats suites against the stacked usage revision. Its refreshed spec is part of the + fleet gate alongside the five original typed experiments. - [~] **Other languages** — Go now parses, validates, renders help and answers completions from generated static tables, verified against the shared corpus. JavaScript and Python implementations remain open. diff --git a/benches/fleet/README.md b/benches/fleet/README.md index 313d1a14f..710f17f65 100644 --- a/benches/fleet/README.md +++ b/benches/fleet/README.md @@ -2,10 +2,11 @@ One spec per jdx CLI, checked in as a fixture. -Each is the output of that CLI's own `usage` subcommand — `clap_usage` over its clap -definition — copied verbatim. They are here for the same reason `benches/mise.usage.kdl` is: -the comparison needs a fixed input, and a reviewer needs to be able to read the diff when one -of them changes. +Each is the output of that CLI's own `usage` subcommand, copied verbatim. The fixtures now come +from the typed `usage-rs` fleet rewrites; they therefore exercise the metadata the replacement +actually emits instead of the subset an older `clap_usage` bridge could recover. They are here +for the same reason `benches/mise.usage.kdl` is: the comparison needs a fixed input, and a +reviewer needs to be able to read the diff when one of them changes. ## Why more than mise @@ -26,5 +27,5 @@ None of the three is exotic. Each was simply outside one CLI's vocabulary. These are snapshots, not links. A CLI that changes its own flags will not update the copy here, and that is fine — the fixture's job is to hold a shape the renderers must agree on, not to -track a moving target. Refresh one by re-running its `usage` subcommand and committing the -diff, the same way `benches/mise.usage.kdl` is refreshed. +track a moving target. Refresh one from its usage-migration branch by re-running its `usage` +subcommand and committing the diff, the same way `benches/mise.usage.kdl` is refreshed. diff --git a/benches/fleet/aube.usage.kdl b/benches/fleet/aube.usage.kdl index 4266ecd3d..31c0cfda0 100644 --- a/benches/fleet/aube.usage.kdl +++ b/benches/fleet/aube.usage.kdl @@ -1,1329 +1,770 @@ -// @generated by usage-cli from clap metadata +// @generated by usage-rs metadata min_usage_version "4.0" name aube bin aube -version "1.36.0" about "A fast Node.js package manager" -usage "Usage: aube [OPTIONS] [COMMAND]" +external_subcommand #true flag "-C --dir --cd --prefix" help="Change to directory before running (like `make -C` or `mise --cd`)" global=#true { arg } -flag "-F --filter" help="Scope command execution to workspace packages matching PATTERN" var=#true global=#true { - long_help #""" -Scope command execution to workspace packages matching PATTERN. - -Supports exact names (`my-pkg`), globs (`@scope/*`, `*-plugin`), paths (`./packages/api`), graph selectors (`pkg...`, `...pkg`), git-ref selectors (`[origin/main]`), and exclusions (`!pkg`). Repeatable; matches are OR-ed. - -Currently honored by `run`, `test`, `start`, `stop`, `restart`, `install`, `exec`, `list`, `publish`, `deploy`, `add`, `remove`, `update`, `why`, and implicit-script invocations. -"""# +flag "-F --filter" help="Scope command execution to workspace packages matching PATTERN." global=#true var=#true { + long_help "Scope command execution to workspace packages matching PATTERN.\n\nSupports exact names (`my-pkg`), globs (`@scope/*`, `*-plugin`),\npaths (`./packages/api`), graph selectors (`pkg...`, `...pkg`),\ngit-ref selectors (`[origin/main]`), and exclusions (`!pkg`).\nRepeatable; matches are OR-ed.\n\nCurrently honored by `run`, `test`, `start`, `stop`, `restart`,\n`install`, `exec`, `list`, `publish`, `deploy`, `add`, `remove`,\n`update`, `why`, and implicit-script invocations." arg } -flag "-r --recursive" help="Run the command across every workspace package" global=#true { - long_help #""" -Run the command across every workspace package. - -Equivalent to `--filter=*`; if `--filter` is also given, `--recursive` is a no-op and the explicit filter wins. Honored by the same commands as `--filter`. -"""# +flag "-r --recursive" help="Run the command across every workspace package." global=#true { + long_help "Run the command across every workspace package.\n\nEquivalent to `--filter=*`; if `--filter` is also given,\n`--recursive` is a no-op and the explicit filter wins. Honored\nby the same commands as `--filter`." } flag "-v --verbose" help="Enable verbose/debug logging (shortcut for `--loglevel debug`)" global=#true -flag "-V --version" help="Print version and check for updates" global=#true { - long_help #""" -Print version and check for updates. - -Manual flag so we can run the async update notifier alongside the version print — clap's auto `Action::Version` exits inside `parse_from`, before the tokio runtime is built. -"""# +flag "-V --version" help="Print version and check for updates." global=#true { + long_help "Print version and check for updates.\n\nManual flag so we can run the async update notifier alongside\nthe version print — clap's auto `Action::Version` exits inside\n`parse_from`, before the tokio runtime is built." } -flag --aggregate-output help="Group workspace command output after each package finishes" hide=#true global=#true { - long_help #""" -Group workspace command output after each package finishes. - -Accepted for pnpm compatibility; aube's workspace fanout is currently sequential, so output is already grouped. -"""# +flag --aggregate-output help="Group workspace command output after each package finishes." global=#true hide=#true conflicts=--stream { + long_help "Group workspace command output after each package finishes.\n\nAccepted for pnpm compatibility; aube's workspace fanout is\ncurrently sequential, so output is already grouped." } -flag --color help="Force colored output even when stderr is not a TTY" global=#true { - long_help #""" -Force colored output even when stderr is not a TTY. - -Overrides `NO_COLOR` / `CLICOLOR=0`. Mutually exclusive with `--no-color`. -"""# +flag --color help="Force colored output even when stderr is not a TTY." global=#true conflicts=--no-color { + long_help "Force colored output even when stderr is not a TTY.\n\nOverrides `NO_COLOR` / `CLICOLOR=0`. Mutually exclusive with\n`--no-color`." } -flag --diag help="Enable cold-install deep diagnostics. Modes: summary — sum_ms / mean / max / %wall table at end trace — summary + critical path + starvation + what-if + lifecycle live — like trace, plus print every span >= 100ms to stderr live full — like trace, plus write JSONL trace to a file (defaults to ./aube-diag.jsonl)" global=#true { - long_help #""" -Enable cold-install deep diagnostics. Modes: summary — sum_ms / mean / max / %wall table at end trace — summary + critical path + starvation + what-if + lifecycle live — like trace, plus print every span >= 100ms to stderr live full — like trace, plus write JSONL trace to a file (defaults to ./aube-diag.jsonl) - -Quick form: `--diag` with no value defaults to `trace`. Output file path can be set via `--diag-file`. Threshold for live mode via `--diag-threshold-ms`. -"""# - arg +flag --diag help="Enable cold-install deep diagnostics. Modes: summary — sum_ms / mean / max / %wall table at end trace — summary + critical path + starvation + what-if + lifecycle live — like trace, plus print every span >= 100ms to stderr live full — like trace, plus write JSONL trace to a file (defaults to ./aube-diag.jsonl)" global=#true value_optional=#true default_missing=trace { + long_help "Enable cold-install deep diagnostics. Modes:\n summary — sum_ms / mean / max / %wall table at end\n trace — summary + critical path + starvation + what-if + lifecycle\n live — like trace, plus print every span >= 100ms to stderr live\n full — like trace, plus write JSONL trace to a file (defaults to ./aube-diag.jsonl)\n\nQuick form: `--diag` with no value defaults to `trace`.\nOutput file path can be set via `--diag-file`. Threshold for live\nmode via `--diag-threshold-ms`." + arg "[MODE]" required=#false } flag --diag-file help="Path for `--diag full` JSONL trace (default: ./aube-diag.jsonl)" global=#true { arg } -flag --diag-threshold-ms help="Live-mode threshold: only print spans whose duration is >= N ms (default 100)" global=#true { +flag --diag-threshold-ms help="Live-mode threshold: only print spans whose duration is >= N ms (default 100)." global=#true { arg } -flag --fail-if-no-match help="Error when a workspace selector matches no packages" global=#true { - long_help #""" -Error when a workspace selector matches no packages. - -Accepted globally; selected commands already fail on empty matches. -"""# +flag --fail-if-no-match help="Error when a workspace selector matches no packages." global=#true { + long_help "Error when a workspace selector matches no packages.\n\nAccepted globally; selected commands already fail on empty matches." } -flag --filter-prod help="Production-only variant of `--filter`" var=#true global=#true { - long_help #""" -Production-only variant of `--filter`. - -Same selector grammar as `--filter`, but graph walks (`pkg...`, `...pkg`) only follow `dependencies` / `optionalDependencies` / `peerDependencies` edges — `devDependencies` (and packages reachable solely through them) are skipped. Non-graph forms (exact name, glob, path, `[git-ref]`) behave identically to `--filter`. Repeatable; can be combined with `--filter`. -"""# +flag --filter-prod help="Production-only variant of `--filter`." global=#true var=#true { + long_help "Production-only variant of `--filter`.\n\nSame selector grammar as `--filter`, but graph walks (`pkg...`,\n`...pkg`) only follow `dependencies` / `optionalDependencies` /\n`peerDependencies` edges — `devDependencies` (and packages\nreachable solely through them) are skipped. Non-graph forms\n(exact name, glob, path, `[git-ref]`) behave identically to\n`--filter`. Repeatable; can be combined with `--filter`." arg } -flag --ignore-workspace help="Ignore workspace discovery for commands that support workspace fanout" hide=#true global=#true { - long_help #""" -Ignore workspace discovery for commands that support workspace fanout. - -Parsed for pnpm compatibility. -"""# +flag --ignore-workspace help="Ignore workspace discovery for commands that support workspace fanout." global=#true hide=#true { + long_help "Ignore workspace discovery for commands that support workspace fanout.\n\nParsed for pnpm compatibility." } -flag --include-workspace-root help="Include the workspace root in recursive workspace operations" hide=#true global=#true { - long_help #""" -Include the workspace root in recursive workspace operations. - -Parsed for pnpm compatibility. -"""# +flag --include-workspace-root help="Include the workspace root in recursive workspace operations." global=#true hide=#true { + long_help "Include the workspace root in recursive workspace operations.\n\nParsed for pnpm compatibility." } -flag --loglevel help="Set the log level. Logs at or above this level are shown" global=#true { +flag --loglevel help="Set the log level. Logs at or above this level are shown." global=#true { arg { - choices trace debug info warn error silent + choices { + choice trace + choice debug + choice info + choice warn + choice error + choice silent + } } } -flag --no-color help="Disable colored output" global=#true { - long_help #""" -Disable colored output. - -Overrides `FORCE_COLOR` / `CLICOLOR_FORCE` and sets `NO_COLOR=1` so downstream libraries (miette, clx, child processes) all see the same choice. -"""# +flag --no-color help="Disable colored output." global=#true { + long_help "Disable colored output.\n\nOverrides `FORCE_COLOR` / `CLICOLOR_FORCE` and sets `NO_COLOR=1`\nso downstream libraries (miette, clx, child processes) all see\nthe same choice." } -flag --reporter help="Output format: default, append-only, ndjson, silent" global=#true { - long_help #""" -Output format: default, append-only, ndjson, silent. - -`default` renders the progress UI when stderr is a TTY; `append-only` disables the progress UI in favor of plain line-at-a-time logs; `ndjson` swaps the tracing fmt layer for the JSON formatter (one JSON object per log event on stderr) and is what tooling wrappers should consume; `silent` suppresses all non-error output (alias for `--loglevel silent`). -"""# +flag --reporter help="Output format: default, append-only, ndjson, silent." global=#true { + long_help "Output format: default, append-only, ndjson, silent.\n\n`default` renders the progress UI when stderr is a TTY;\n`append-only` disables the progress UI in favor of plain\nline-at-a-time logs; `ndjson` swaps the tracing fmt layer for\nthe JSON formatter (one JSON object per log event on stderr)\nand is what tooling wrappers should consume; `silent`\nsuppresses all non-error output (alias for `--loglevel silent`)." arg { - choices default append-only ndjson silent + choices { + choice default + choice append-only + choice ndjson + choice silent + } } } flag --silent help="Suppress all non-error output (alias for `--loglevel silent`)" global=#true -flag --stream help="Stream workspace command output as each child process writes it" hide=#true global=#true { - long_help #""" -Stream workspace command output as each child process writes it. - -Accepted for pnpm compatibility; aube's workspace fanout is currently sequential. -"""# +flag --stream help="Stream workspace command output as each child process writes it." global=#true hide=#true conflicts=--aggregate-output { + long_help "Stream workspace command output as each child process writes it.\n\nAccepted for pnpm compatibility; aube's workspace fanout is\ncurrently sequential." } -flag --use-stderr help="Route lifecycle and workspace command output through stderr" hide=#true global=#true { - long_help #""" -Route lifecycle and workspace command output through stderr. - -Accepted for pnpm compatibility. -"""# +flag --use-stderr help="Route lifecycle and workspace command output through stderr." global=#true hide=#true { + long_help "Route lifecycle and workspace command output through stderr.\n\nAccepted for pnpm compatibility." } -flag --workspace-packages help="Prefer workspace packages when resolving dependencies" hide=#true global=#true { - long_help #""" -Prefer workspace packages when resolving dependencies. - -Parsed for pnpm compatibility; aube already resolves workspace packages when a workspace is present. -"""# +flag --workspace-packages help="Prefer workspace packages when resolving dependencies." global=#true hide=#true { + long_help "Prefer workspace packages when resolving dependencies.\n\nParsed for pnpm compatibility; aube already resolves workspace\npackages when a workspace is present." } -flag --workspace-root help="Run from the workspace root regardless of the current package" global=#true -flag "-y --yes" help="Automatically answer yes to prompts" hide=#true global=#true { - long_help #""" -Automatically answer yes to prompts. - -Parsed for pnpm compatibility; aube does not currently prompt on these paths. -"""# +flag --workspace-root help="Run from the workspace root regardless of the current package." global=#true +flag "-y --yes" help="Automatically answer yes to prompts." global=#true hide=#true { + long_help "Automatically answer yes to prompts.\n\nParsed for pnpm compatibility; aube does not currently prompt\non these paths." } -cmd __node-gyp-bootstrap hide=#true help="Bootstrap aube's cached node-gyp and print the executable path" effect=write { +cmd __node-gyp-bootstrap help="Bootstrap aube's cached node-gyp and print the executable path." hide=#true effect=write { arg } -cmd access subcommand_required=#true help="Manage package access and visibility on the registry" effect=read { - flag --json help="Emit registry responses as JSON when the subcommand has a result" - flag --otp help="One-time password from a 2FA authenticator; sent as `npm-otp`" { +cmd access help="Manage package access and visibility on the registry" effect=read subcommand_required=#true { + flag --json help="Emit registry responses as JSON when the subcommand has a result." + flag --otp help="One-time password from a 2FA authenticator; sent as `npm-otp`." { arg } - flag --fetch-retries help="Number of retry attempts for failed registry fetches" { - long_help #""" -Number of retry attempts for failed registry fetches. - -Overrides `fetchRetries` / `fetch-retries` from `.npmrc` / `aube-workspace.yaml` when set. Pair with `--fetch-timeout` to fail fast in scripted test runs. -"""# + flag --fetch-retries help="Number of retry attempts for failed registry fetches." help_heading=Network { + long_help "Number of retry attempts for failed registry fetches.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs." arg } - flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" { - long_help #""" -Exponential backoff factor between retry attempts. - -Overrides `fetchRetryFactor` / `fetch-retry-factor` from `.npmrc` / `aube-workspace.yaml` when set. Integer-only — the underlying `FetchPolicy.retry_factor` is `u32`. Fractional values like `1.5` are rejected by clap. -"""# + flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network { + long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser." arg } - flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" { - long_help #""" -Upper bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Upper bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" { - long_help #""" -Lower bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Lower bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" { - long_help #""" -Per-request HTTP timeout in milliseconds. - -Overrides `fetchTimeout` / `fetch-timeout` from `.npmrc` / `aube-workspace.yaml` when set. Applied via `reqwest`'s `.timeout()` so it covers headers + body together. -"""# + flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network { + long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together." arg } - flag --registry help="Override the default registry URL for this invocation" { - long_help #""" -Override the default registry URL for this invocation. - -Use this npm registry URL for package metadata, tarballs, audit requests, dist-tags, and registry writes. -"""# + flag --registry help="Override the default registry URL for this invocation." help_heading=Network { + long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes." arg } - cmd get subcommand_required=#true help="Get package visibility status" effect=read { - cmd status help="Get a package's public or restricted status" effect=read { - arg help="Package name" + cmd get help="Get package visibility status." effect=read subcommand_required=#true { + cmd status help="Get a package's public or restricted status." effect=read { + arg help="Package name." } } - cmd grant help="Grant a team read-only or read-write access to a package" effect=write { - arg help="`read-only` or `read-write`" - arg help="Team in `@scope:team` form" - arg help="Package name" + cmd grant help="Grant a team read-only or read-write access to a package." effect=write { + arg help="`read-only` or `read-write`." + arg help="Team in `@scope:team` form." + arg help="Package name." } - cmd list subcommand_required=#true help="List packages visible to a user, organization, or team" effect=read { - cmd collaborators help="List collaborators for a package, optionally filtering to one user" effect=read { - arg help="Package name" - arg "[USER]" help="Optional user name" required=#false + cmd list help="List packages visible to a user, organization, or team." effect=read subcommand_required=#true { + cmd collaborators help="List collaborators for a package, optionally filtering to one user." effect=read { + arg help="Package name." + arg "[USER]" help="Optional user name." } - cmd packages help="List packages visible to the current user or an optional entity" effect=read { - arg "[ENTITY]" help="User, `@organization`, or `@scope:team`" required=#false + cmd packages help="List packages visible to the current user or an optional entity." effect=read { + arg "[ENTITY]" help="User, `@organization`, or `@scope:team`." } } - cmd ls help="Alias for `list packages`" effect=read { - arg "[ENTITIES]…" help="User, `@organization`, or `@scope:team`. Also accepts pnpm's `packages [ENTITY]` compatibility form. Accepted forms are `aube access ls [ENTITY]` and `aube access ls packages [ENTITY]`" required=#false var=#true + cmd ls help="Alias for `list packages`." effect=read { + arg "[ENTITIES]..." help="User, `@organization`, or `@scope:team`. Also accepts pnpm's `packages [ENTITY]` compatibility form. Accepted forms are `aube access ls [ENTITY]` and `aube access ls packages [ENTITY]`." var_max=2 { + long_help "User, `@organization`, or `@scope:team`. Also accepts pnpm's\n`packages [ENTITY]` compatibility form. Accepted forms are\n`aube access ls [ENTITY]` and `aube access ls packages [ENTITY]`." + } } - cmd revoke help="Revoke a team's access to a package" effect=destructive { - arg help="Team in `@scope:team` form" - arg help="Package name" + cmd revoke help="Revoke a team's access to a package." effect=destructive { + arg help="Team in `@scope:team` form." + arg help="Package name." } - cmd set help="Set package visibility or a publish MFA requirement" effect=write { - arg help="`status=public|private|restricted` or `mfa=none|publish|automation`" - arg help="Package name" + cmd set help="Set package visibility or a publish MFA requirement." effect=write { + arg help="`status=public|private|restricted` or `mfa=none|publish|automation`." + arg help="Package name." } } cmd activate help="Emit shell activation code for runtime tool shims" effect=write { - arg help="Shell to emit activation code for" { - choices bash fish zsh - } + arg help="Shell to emit activation code for" } cmd add help="Add a dependency" effect=write { alias a flag "-D --save-dev" help="Add as dev dependency" flag "-E --save-exact" help="Pin the exact resolved version (no `^` prefix)" - flag "-g --global" help="Install the package globally" { - long_help #""" -Install the package globally. - -Installs into the aube/pnpm global directory and links its binaries into the global bin directory. Mirrors `pnpm add -g`. -"""# + flag "-g --global" help="Install the package globally." { + long_help "Install the package globally.\n\nInstalls into the aube/pnpm global directory and links its\nbinaries into the global bin directory. Mirrors `pnpm add -g`." } flag "-O --save-optional" help="Add as optional dependency" - flag --allow-build help="Pre-approve a dependency's lifecycle scripts as part of the add" var=#true { - long_help #""" -Pre-approve a dependency's lifecycle scripts as part of the add. - -Writes `allowBuilds: { : true }` into the workspace yaml (or `package.json#aube.allowBuilds`) before the install runs, so the named package's `preinstall` / `install` / `postinstall` scripts execute on this invocation. Repeatable — pass the flag once per package. Mirrors `pnpm add --allow-build=`. - -Conflicts with `--no-save`, which only snapshots `package.json` and the lockfile and would leave an orphaned approval in the workspace yaml on restore. Also conflicts with `--deny-build` for the same package name. -"""# - arg + flag --allow-build help="Pre-approve a dependency's lifecycle scripts as part of the add." var=#true conflicts=--no-save require_equals=#true { + long_help "Pre-approve a dependency's lifecycle scripts as part of the add.\n\nWrites `allowBuilds: { : true }` into the workspace yaml\n(or `package.json#aube.allowBuilds`) before the install runs,\nso the named package's `preinstall` / `install` / `postinstall`\nscripts execute on this invocation. Repeatable — pass the flag\nonce per package. Mirrors `pnpm add --allow-build=`.\n\nConflicts with `--no-save`, which only snapshots `package.json`\nand the lockfile and would leave an orphaned approval in the\nworkspace yaml on restore. Also conflicts with `--deny-build` for\nthe same package name." + arg validate="value != ''" validate_error="The --allow-build flag is missing a package name. Please specify the package name(s) that are allowed to run installation scripts." } - flag --allow-low-downloads help="Bypass the similar-name, new-name, and [`lowDownloadThreshold`] confirm prompts / refusals for this invocation" { - long_help #""" -Bypass the similar-name, new-name, and [`lowDownloadThreshold`] confirm prompts / refusals for this invocation. - -`aube add` looks up each candidate's weekly download count and prompts (interactive) or fails (CI) when the count is below [`lowDownloadThreshold`], resembles a top-100,000 npm package, or is newer than [`minimumPackageAge`]. The flag is intended for cases where you've already verified the package out-of-band. It does not affect the OSV malicious-package check, which remains a hard block. -"""# + flag --allow-low-downloads help="Bypass the similar-name, new-name, and [`lowDownloadThreshold`] confirm prompts / refusals for this invocation." { + long_help "Bypass the similar-name, new-name, and [`lowDownloadThreshold`]\nconfirm prompts / refusals for this invocation.\n\n`aube add` looks up each candidate's weekly download count and\nprompts (interactive) or fails (CI) when the count is below\n[`lowDownloadThreshold`], resembles a top-100,000 npm package,\nor is newer than [`minimumPackageAge`]. The flag is intended\nfor cases where you've already verified the package out-of-band.\nIt does not affect the OSV malicious-package check, which remains\na hard block." } - flag --dangerously-allow-all-builds help="Allow every dependency's lifecycle scripts to run" { - long_help #""" -Allow every dependency's lifecycle scripts to run. - -Bypasses the `allowBuilds` allowlist for this invocation. Do not use in CI. Mirrors pnpm's `--dangerously-allow-all-builds`. -"""# + flag --dangerously-allow-all-builds help="Allow every dependency's lifecycle scripts to run." { + long_help "Allow every dependency's lifecycle scripts to run.\n\nBypasses the `allowBuilds` allowlist for this invocation. Do not\nuse in CI. Mirrors pnpm's `--dangerously-allow-all-builds`." } - flag --deny-build help="Mark a dependency's lifecycle scripts as reviewed and denied" var=#true { - long_help #""" -Mark a dependency's lifecycle scripts as reviewed and denied. - -Writes `allowBuilds: { : false }` into the workspace yaml (or `package.json#aube.allowBuilds`) before the install runs, so the named package's lifecycle scripts stay skipped without tripping `strictDepBuilds=true`. Repeatable — pass the flag once per package. - -Conflicts with `--no-save`, which only snapshots `package.json` and the lockfile and would leave an orphaned denial in the workspace yaml on restore. Also conflicts with `--allow-build` for the same package name and with `--dangerously-allow-all-builds`. -"""# - arg - } - flag --ignore-scripts help="Skip root and approved dependency lifecycle scripts" hide=#true - flag --no-save help="Install without persisting the dependency to `package.json`" { - long_help #""" -Install without persisting the dependency to `package.json`. - -Snapshots `package.json` and the lockfile, links the named packages into `node_modules`, and then restores both files — so the dependency is usable for the current process but the project's committed state is untouched. - -Handy for one-off experiments and for scripts that install a tool transiently. Mirrors `pnpm add --no-save`. Conflicts with `-g`/`--global`, which has to persist the install to its global manifest. -"""# + flag --deny-build help="Mark a dependency's lifecycle scripts as reviewed and denied." var=#true require_equals=#true { + long_help "Mark a dependency's lifecycle scripts as reviewed and denied.\n\nWrites `allowBuilds: { : false }` into the workspace yaml\n(or `package.json#aube.allowBuilds`) before the install runs,\nso the named package's lifecycle scripts stay skipped without\ntripping `strictDepBuilds=true`. Repeatable — pass the flag\nonce per package.\n\nConflicts with `--no-save`, which only snapshots `package.json`\nand the lockfile and would leave an orphaned denial in the\nworkspace yaml on restore. Also conflicts with `--allow-build` for\nthe same package name and with `--dangerously-allow-all-builds`." + conflicts --no-save --dangerously-allow-all-builds + arg validate="value != ''" validate_error="The --deny-build flag is missing a package name. Please specify the package name(s) that are denied from running installation scripts." } - flag --no-save-workspace-protocol help="Inverse of `--save-workspace-protocol`" { - long_help #""" -Inverse of `--save-workspace-protocol`. - -Forces the manifest specifier into a registry-style spec (`^`) for this invocation, even when `linkWorkspacePackages` matched a local sibling. The install pipeline still prefers the local workspace copy at resolve time — this flag only controls what's written to `package.json`. Mirrors `pnpm add --no-save-workspace-protocol`. -"""# + flag --ignore-scripts help="Skip root and approved dependency lifecycle scripts." hide=#true + flag --no-save help="Install without persisting the dependency to `package.json`." conflicts=--global { + long_help "Install without persisting the dependency to `package.json`.\n\nSnapshots `package.json` and the lockfile, links the named\npackages into `node_modules`, and then restores both files —\nso the dependency is usable for the current process but the\nproject's committed state is untouched.\n\nHandy for one-off experiments and for scripts that install a\ntool transiently. Mirrors `pnpm add --no-save`. Conflicts with\n`-g`/`--global`, which has to persist the install to its global\nmanifest." } - flag --save-catalog help="Save the new dependency into the workspace's default catalog" { - long_help #""" -Save the new dependency into the workspace's default catalog. - -Writes `catalog:` into `package.json` and seeds/upserts the resolved range under `catalog:` in the workspace yaml. Mirrors `pnpm add --save-catalog`. - -Workspace and aliased specs (`workspace:*`, `npm:`, `jsr:`) are never catalogized — the manifest gets the original spec and the catalog yaml is left alone. If the package is already in the target catalog, the existing entry is preserved (never overwritten); the manifest then gets `catalog:` only when the existing entry is compatible with the user's range. - -Conflicts with `--no-save`: catalog mutations write to the workspace yaml, which the `--no-save` restore path doesn't snapshot — combining the two would silently leave an orphaned catalog entry behind. -"""# + flag --no-save-workspace-protocol help="Inverse of `--save-workspace-protocol`." overrides=--save-workspace-protocol { + long_help "Inverse of `--save-workspace-protocol`.\n\nForces the manifest specifier into a registry-style spec\n(`^`) for this invocation, even when\n`linkWorkspacePackages` matched a local sibling. The install\npipeline still prefers the local workspace copy at resolve\ntime — this flag only controls what's written to\n`package.json`. Mirrors `pnpm add --no-save-workspace-protocol`." } - flag --save-catalog-name help="Save the new dependency into a *named* catalog" { - long_help #""" -Save the new dependency into a *named* catalog. - -Writes the entry to `catalogs.` in the workspace yaml and `catalog:` into `package.json`. Same workspace/alias exclusions and `--no-save` conflict as `--save-catalog`. Mirrors `pnpm add --save-catalog-name=`. -"""# + flag --save-catalog help="Save the new dependency into the workspace's default catalog." { + long_help "Save the new dependency into the workspace's default catalog.\n\nWrites `catalog:` into `package.json` and seeds/upserts the\nresolved range under `catalog:` in the workspace yaml. Mirrors\n`pnpm add --save-catalog`.\n\nWorkspace and aliased specs (`workspace:*`, `npm:`, `jsr:`) are\nnever catalogized — the manifest gets the original spec and\nthe catalog yaml is left alone. If the package is already in\nthe target catalog, the existing entry is preserved (never\noverwritten); the manifest then gets `catalog:` only when the\nexisting entry is compatible with the user's range.\n\nConflicts with `--no-save`: catalog mutations write to the\nworkspace yaml, which the `--no-save` restore path doesn't\nsnapshot — combining the two would silently leave an orphaned\ncatalog entry behind." + conflicts --save-catalog-name --no-save + } + flag --save-catalog-name help="Save the new dependency into a *named* catalog." conflicts=--no-save { + long_help "Save the new dependency into a *named* catalog.\n\nWrites the entry to `catalogs.` in the workspace yaml and\n`catalog:` into `package.json`. Same workspace/alias\nexclusions and `--no-save` conflict as `--save-catalog`. Mirrors\n`pnpm add --save-catalog-name=`." arg } - flag --save-peer help="Add as a peer dependency (written to `peerDependencies` in package.json)" { - long_help #""" -Add as a peer dependency (written to `peerDependencies` in package.json). - -By convention you usually pair this with `--save-dev` so the peer is also installed for local development; that's what pnpm does. -"""# + flag --save-peer help="Add as a peer dependency (written to `peerDependencies` in package.json)." conflicts=--save-optional { + long_help "Add as a peer dependency (written to `peerDependencies` in\npackage.json).\n\nBy convention you usually pair this with `--save-dev` so the\npeer is also installed for local development; that's what pnpm\ndoes." } - flag --save-workspace-protocol help="Force the manifest specifier into `workspace:` form for this invocation, overriding `saveWorkspaceProtocol` from the workspace yaml / `.npmrc` / env" { - long_help #""" -Force the manifest specifier into `workspace:` form for this invocation, overriding `saveWorkspaceProtocol` from the workspace yaml / `.npmrc` / env. - -Only meaningful when `linkWorkspacePackages` (or a workspace sibling already exists for the named package). With this flag the entry written to `package.json` is `workspace:^` (rolling) or `workspace:^` (pinned), depending on the resolved `saveWorkspaceProtocol` value. -"""# + flag --save-workspace-protocol help="Force the manifest specifier into `workspace:` form for this invocation, overriding `saveWorkspaceProtocol` from the workspace yaml / `.npmrc` / env." overrides=--no-save-workspace-protocol { + long_help "Force the manifest specifier into `workspace:` form for this\ninvocation, overriding `saveWorkspaceProtocol` from the\nworkspace yaml / `.npmrc` / env.\n\nOnly meaningful when `linkWorkspacePackages` (or a workspace\nsibling already exists for the named package). With this flag\nthe entry written to `package.json` is `workspace:^` (rolling)\nor `workspace:^` (pinned), depending on the resolved\n`saveWorkspaceProtocol` value." } - flag "-w --workspace" help="Add the dependency to the workspace root's `package.json`" { - long_help #""" -Add the dependency to the workspace root's `package.json`. - -Applies regardless of the current working directory: walks up from cwd looking for `aube-workspace.yaml`, `pnpm-workspace.yaml`, or a `package.json` with a `workspaces` field and runs the add against that directory. -"""# + flag "-w --workspace" help="Add the dependency to the workspace root's `package.json`." conflicts=--global { + long_help "Add the dependency to the workspace root's `package.json`.\n\nApplies regardless of the current working directory: walks up\nfrom cwd looking for `aube-workspace.yaml`, `pnpm-workspace.yaml`,\nor a `package.json` with a `workspaces` field and runs the add\nagainst that directory." } - flag "-W --ignore-workspace-root-check" help="Allow `add` to run in a workspace root" { - long_help #""" -Allow `add` to run in a workspace root. - -By default aube refuses to add dependencies to the root `package.json` of a workspace (a directory containing `aube-workspace.yaml`, `pnpm-workspace.yaml`, or a `package.json` with a `workspaces` field) because deps added there end up shared by every package and usually reflect a mistake. Pass this flag to opt in. Mirrors `pnpm add -W`. -"""# - } - flag --frozen-lockfile help="Error if the lockfile drifts from package.json" - flag --no-frozen-lockfile help="Always re-resolve, even if the lockfile is up to date" - flag --prefer-frozen-lockfile help="Use the lockfile when fresh, re-resolve when stale" - flag --fetch-retries help="Number of retry attempts for failed registry fetches" { - long_help #""" -Number of retry attempts for failed registry fetches. - -Overrides `fetchRetries` / `fetch-retries` from `.npmrc` / `aube-workspace.yaml` when set. Pair with `--fetch-timeout` to fail fast in scripted test runs. -"""# + flag "-W --ignore-workspace-root-check" help="Allow `add` to run in a workspace root." { + long_help "Allow `add` to run in a workspace root.\n\nBy default aube refuses to add dependencies to the root\n`package.json` of a workspace (a directory containing\n`aube-workspace.yaml`, `pnpm-workspace.yaml`, or a `package.json`\nwith a `workspaces` field) because deps added there end up\nshared by every package and usually reflect a mistake. Pass\nthis flag to opt in. Mirrors `pnpm add -W`." + } + flag --frozen-lockfile help="Error if the lockfile drifts from package.json." help_heading=Lockfile { + conflicts --no-frozen-lockfile --prefer-frozen-lockfile + } + flag --no-frozen-lockfile help="Always re-resolve, even if the lockfile is up to date." help_heading=Lockfile { + conflicts --frozen-lockfile --prefer-frozen-lockfile + } + flag --prefer-frozen-lockfile help="Use the lockfile when fresh, re-resolve when stale." help_heading=Lockfile { + conflicts --frozen-lockfile --no-frozen-lockfile + } + flag --fetch-retries help="Number of retry attempts for failed registry fetches." help_heading=Network { + long_help "Number of retry attempts for failed registry fetches.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs." arg } - flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" { - long_help #""" -Exponential backoff factor between retry attempts. - -Overrides `fetchRetryFactor` / `fetch-retry-factor` from `.npmrc` / `aube-workspace.yaml` when set. Integer-only — the underlying `FetchPolicy.retry_factor` is `u32`. Fractional values like `1.5` are rejected by clap. -"""# + flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network { + long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser." arg } - flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" { - long_help #""" -Upper bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Upper bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" { - long_help #""" -Lower bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Lower bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" { - long_help #""" -Per-request HTTP timeout in milliseconds. - -Overrides `fetchTimeout` / `fetch-timeout` from `.npmrc` / `aube-workspace.yaml` when set. Applied via `reqwest`'s `.timeout()` so it covers headers + body together. -"""# + flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network { + long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together." arg } - flag --registry help="Override the default registry URL for this invocation" { - long_help #""" -Override the default registry URL for this invocation. - -Use this npm registry URL for package metadata, tarballs, audit requests, dist-tags, and registry writes. -"""# + flag --registry help="Override the default registry URL for this invocation." help_heading=Network { + long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes." arg } - flag "--disable-global-virtual-store --disable-gvs" help="Force the shared global virtual store off for this invocation" { - long_help #""" -Force the shared global virtual store off for this invocation. - -Packages are materialized inside the project's virtual store instead of symlinked from `~/.cache/aube/virtual-store/`. -"""# + flag "--disable-global-virtual-store --disable-gvs" help="Force the shared global virtual store off for this invocation." help_heading="Virtual store" conflicts=--enable-global-virtual-store { + long_help "Force the shared global virtual store off for this invocation.\n\nPackages are materialized inside the project's virtual store\ninstead of symlinked from `~/.cache/aube/virtual-store/`." } - flag "--enable-global-virtual-store --enable-gvs" help="Force the shared global virtual store on for this invocation" { - long_help #""" -Force the shared global virtual store on for this invocation. - -Overrides CI's default per-project materialization and the `disableGlobalVirtualStoreForPackages` auto-disable heuristic. -"""# + flag "--enable-global-virtual-store --enable-gvs" help="Force the shared global virtual store on for this invocation." help_heading="Virtual store" conflicts=--disable-global-virtual-store { + long_help "Force the shared global virtual store on for this invocation.\n\nOverrides CI's default per-project materialization and the\n`disableGlobalVirtualStoreForPackages` auto-disable heuristic." } - arg "[PACKAGES]…" help="Package(s) to add" required=#false var=#true + arg "[PACKAGES]..." help="Package(s) to add" } -cmd approve-builds help="Approve ignored dependency build scripts" effect=write { - long_help #""" -Approve ignored dependency build scripts. - -Writes entries under `allowBuilds` in `aube-workspace.yaml` (or `pnpm-workspace.yaml` if present). -"""# - flag --all help="Approve every pending ignored build without prompting" - flag "-g --global" help="Operate on globally-installed packages instead of the current project" - arg "[PKG]…" help="Packages to approve directly, skipping the picker" help_long=#""" -Packages to approve directly, skipping the picker. - -Each name must match a currently-ignored build. Unknown names are rejected so a typo cannot silently no-op. -"""# required=#false var=#true +cmd approve-builds help="Approve ignored dependency build scripts." effect=write { + long_help "Approve ignored dependency build scripts.\n\nWrites entries under `allowBuilds` in `aube-workspace.yaml` (or\n`pnpm-workspace.yaml` if present)." + flag --all help="Approve every pending ignored build without prompting." + flag "-g --global" help="Operate on globally-installed packages instead of the current project." + arg "[PKG]..." help="Packages to approve directly, skipping the picker." { + long_help "Packages to approve directly, skipping the picker.\n\nEach name must match a currently-ignored build. Unknown names\nare rejected so a typo cannot silently no-op." + } } cmd audit help="Check installed packages against the registry advisory DB" effect=read { - after_long_help #""" -Examples: - - $ aube audit - Severity Package Vulnerable Title - moderate minimatch <3.0.5 Regular Expression Denial of Service - https://github.com/advisories/GHSA-f8q6-p94x - - 1 vulnerability found - - # Only fail on high and above - $ aube audit --audit-level high - - # Skip optional deps and dev deps - $ aube audit --prod --no-optional - - # Pipe into jq - $ aube audit --json | jq '.advisories | length' - - # Clean - $ aube audit - No known vulnerabilities found - -"""# - flag --audit-level help="Only print advisories at or above this severity" { - long_help #""" -Only print advisories at or above this severity. - -One of: `info`, `low`, `moderate`, `high`, `critical`. Defaults to `audit.level` (or legacy `auditLevel`), then `low`. -"""# + flag --audit-level help="Only print advisories at or above this severity." { + long_help "Only print advisories at or above this severity.\n\nOne of: `info`, `low`, `moderate`, `high`, `critical`.\nDefaults to `audit.level` (or legacy `auditLevel`), then `low`." arg { - choices info low moderate high critical + choices { + choice info + choice low + choice moderate + choice high + choice critical + } } } - flag "-D --dev" help="Only audit `devDependencies`" - flag --fix help="Fix advisories" { - long_help #""" -Fix advisories. - -Bare `--fix` writes package.json overrides for backwards compatibility. `--fix=update` refreshes the lockfile without writing overrides. -"""# - arg { - choices update override + flag "-D --dev" help="Only audit `devDependencies`." conflicts=--prod + flag --fix help="Fix advisories." value_optional=#true default_missing=override { + long_help "Fix advisories.\n\nBare `--fix` writes package.json overrides for backwards compatibility.\n`--fix=update` refreshes the lockfile without writing overrides." + arg "[FIX]" required=#false { + choices { + choice update help="Refresh the lockfile to patched versions allowed by existing ranges." + choice override help="Write package.json overrides that force patched versions." + } } } - flag --ignore help="Drop advisories whose ID matches one of these values" var=#true { - long_help #""" -Drop advisories whose ID matches one of these values. - -Matches against the numeric npm advisory `id`, `github_advisory_id` (`GHSA-…`), and any entry in `cves[]` (case-insensitive). Repeatable; comma-separated values are also accepted. -"""# + flag --ignore help="Drop advisories whose ID matches one of these values." var=#true delimiter=, { + long_help "Drop advisories whose ID matches one of these values.\n\nMatches against the numeric npm advisory `id`,\n`github_advisory_id` (`GHSA-…`), and any entry in `cves[]`\n(case-insensitive). Repeatable; comma-separated values are also\naccepted." arg } - flag --ignore-registry-errors help="Use exit code 0 if the registry responds with an error" { - long_help #""" -Use exit code 0 if the registry responds with an error. - -Useful when audit checks run in CI and the registry has a hiccup. -"""# + flag --ignore-registry-errors help="Use exit code 0 if the registry responds with an error." { + long_help "Use exit code 0 if the registry responds with an error.\n\nUseful when audit checks run in CI and the registry has a hiccup." } - flag --ignore-unfixable help="Drop advisories that have no non-vulnerable upgrade" { - long_help #""" -Drop advisories that have no non-vulnerable upgrade. - -Filters out advisories for which no non-vulnerable version is available in the package's packument. Same "best non-vulnerable" logic as `--fix`: an advisory is kept only when an upgrade path exists. -"""# + flag --ignore-unfixable help="Drop advisories that have no non-vulnerable upgrade." { + long_help "Drop advisories that have no non-vulnerable upgrade.\n\nFilters out advisories for which no non-vulnerable version is\navailable in the package's packument. Same \"best non-vulnerable\"\nlogic as `--fix`: an advisory is kept only when an upgrade path\nexists." } - flag "-i --interactive" help="Pick which advisories to fix interactively" - flag --json help="Emit the report as JSON (pnpm-compatible shape) instead of a table" - flag --no-optional help="Skip `optionalDependencies`" - flag "-P --prod --production" help="Only audit `dependencies` and `optionalDependencies`" - flag --fetch-retries help="Number of retry attempts for failed registry fetches" { - long_help #""" -Number of retry attempts for failed registry fetches. - -Overrides `fetchRetries` / `fetch-retries` from `.npmrc` / `aube-workspace.yaml` when set. Pair with `--fetch-timeout` to fail fast in scripted test runs. -"""# + flag "-i --interactive" help="Pick which advisories to fix interactively." + flag --json help="Emit the report as JSON (pnpm-compatible shape) instead of a table." + flag --no-optional help="Skip `optionalDependencies`." + flag "-P --prod --production" help="Only audit `dependencies` and `optionalDependencies`." conflicts=--dev + flag --fetch-retries help="Number of retry attempts for failed registry fetches." help_heading=Network { + long_help "Number of retry attempts for failed registry fetches.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs." arg } - flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" { - long_help #""" -Exponential backoff factor between retry attempts. - -Overrides `fetchRetryFactor` / `fetch-retry-factor` from `.npmrc` / `aube-workspace.yaml` when set. Integer-only — the underlying `FetchPolicy.retry_factor` is `u32`. Fractional values like `1.5` are rejected by clap. -"""# + flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network { + long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser." arg } - flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" { - long_help #""" -Upper bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Upper bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" { - long_help #""" -Lower bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Lower bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" { - long_help #""" -Per-request HTTP timeout in milliseconds. - -Overrides `fetchTimeout` / `fetch-timeout` from `.npmrc` / `aube-workspace.yaml` when set. Applied via `reqwest`'s `.timeout()` so it covers headers + body together. -"""# + flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network { + long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together." arg } - flag --registry help="Override the default registry URL for this invocation" { - long_help #""" -Override the default registry URL for this invocation. - -Use this npm registry URL for package metadata, tarballs, audit requests, dist-tags, and registry writes. -"""# + flag --registry help="Override the default registry URL for this invocation." help_heading=Network { + long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes." arg } } cmd bin help="Print the path to `node_modules/.bin`" effect=read { - after_long_help #""" -Examples: - - $ aube bin - /home/user/project/node_modules/.bin - - $ aube bin -g - /home/user/.local/share/aube/global/node_modules/.bin - - # From a workspace package, -w prints the workspace-root bin directory - $ cd packages/app - $ aube bin - /home/user/project/packages/app/node_modules/.bin - $ aube bin -w - /home/user/project/node_modules/.bin - - # Extend PATH with the project bin directory - $ export PATH="$(aube bin):$PATH" - -"""# - flag "-g --global" help="Print the global bin directory instead of the project's" - flag "-w --workspace-root --workspace" help="Print the workspace-root bin directory instead of the current package's" { - long_help #""" -Print the workspace-root bin directory instead of the current package's. - -Mirrors `pnpm bin -w`: from a sub-package, resolves the enclosing workspace root and prints its `node_modules/.bin`. No-op when no workspace root exists above cwd (single-project install), so the flag is safe to leave in shell aliases. -"""# + flag "-g --global" help="Print the global bin directory instead of the project's" conflicts=--workspace-root + flag "-w --workspace-root --workspace" help="Print the workspace-root bin directory instead of the current package's." { + long_help "Print the workspace-root bin directory instead of the current\npackage's.\n\nMirrors `pnpm bin -w`: from a sub-package, resolves the enclosing\nworkspace root and prints its `node_modules/.bin`. No-op when no\nworkspace root exists above cwd (single-project install), so the\nflag is safe to leave in shell aliases." } } cmd bugs help="Open package bug tracker URLs" effect=read { alias issues - after_long_help #""" -Examples: - - $ aube bugs - - $ aube bugs react - - $ aube issues react react-dom - -"""# - flag --fetch-retries help="Number of retry attempts for failed registry fetches" { - long_help #""" -Number of retry attempts for failed registry fetches. - -Overrides `fetchRetries` / `fetch-retries` from `.npmrc` / `aube-workspace.yaml` when set. Pair with `--fetch-timeout` to fail fast in scripted test runs. -"""# + after_long_help "Examples:\n\n $ aube bugs\n\n $ aube bugs react\n\n $ aube issues react react-dom\n" + flag --fetch-retries help="Number of retry attempts for failed registry fetches." help_heading=Network { + long_help "Number of retry attempts for failed registry fetches.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs." arg } - flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" { - long_help #""" -Exponential backoff factor between retry attempts. - -Overrides `fetchRetryFactor` / `fetch-retry-factor` from `.npmrc` / `aube-workspace.yaml` when set. Integer-only — the underlying `FetchPolicy.retry_factor` is `u32`. Fractional values like `1.5` are rejected by clap. -"""# + flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network { + long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser." arg } - flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" { - long_help #""" -Upper bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Upper bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" { - long_help #""" -Lower bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Lower bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" { - long_help #""" -Per-request HTTP timeout in milliseconds. - -Overrides `fetchTimeout` / `fetch-timeout` from `.npmrc` / `aube-workspace.yaml` when set. Applied via `reqwest`'s `.timeout()` so it covers headers + body together. -"""# + flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network { + long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together." arg } - flag --registry help="Override the default registry URL for this invocation" { - long_help #""" -Override the default registry URL for this invocation. - -Use this npm registry URL for package metadata, tarballs, audit requests, dist-tags, and registry writes. -"""# + flag --registry help="Override the default registry URL for this invocation." help_heading=Network { + long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes." arg } - arg "[PACKAGES]…" help="Packages to open bug trackers for. Defaults to the current project" required=#false var=#true + arg "[PACKAGES]..." help="Packages to open bug trackers for. Defaults to the current project." } -cmd cache subcommand_required=#true help="Inspect and manage the packument metadata cache" effect=read { - cmd delete help="Delete metadata cache for the specified package(s)" effect=write { - long_help #""" -Delete metadata cache for the specified package(s). - -Supports glob patterns; matches against the package name (e.g. `lodash`, `@babel/*`). -"""# - arg … help="One or more package name patterns" help_long=#""" -One or more package name patterns. - -Glob metacharacters (`*`, `?`, `[...]`) are supported. -"""# var=#true +cmd cache help="Inspect and manage the packument metadata cache" effect=read subcommand_required=#true { + cmd delete help="Delete metadata cache for the specified package(s)." effect=write { + long_help "Delete metadata cache for the specified package(s).\n\nSupports glob patterns; matches against the package name (e.g.\n`lodash`, `@babel/*`)." + arg ... help="One or more package name patterns." { + long_help "One or more package name patterns.\n\nGlob metacharacters (`*`, `?`, `[...]`) are supported." + } } - cmd list help="List the available packages in the metadata cache" effect=read { - long_help #""" -List the available packages in the metadata cache. - -Optional glob filters narrow the result; with no filter every cached package is listed. -"""# - arg "[PATTERNS]…" help="Optional glob patterns to filter the listing" help_long=#""" -Optional glob patterns to filter the listing. - -With no patterns, every cached package is printed. -"""# required=#false var=#true + cmd list help="List the available packages in the metadata cache." effect=read { + long_help "List the available packages in the metadata cache.\n\nOptional glob filters narrow the result; with no filter every\ncached package is listed." + arg "[PATTERNS]..." help="Optional glob patterns to filter the listing." { + long_help "Optional glob patterns to filter the listing.\n\nWith no patterns, every cached package is printed." + } } - cmd list-registries help="List configured registries from the project + user `.npmrc`" effect=read { - long_help #""" -List configured registries from the project + user `.npmrc`. - -Aube stores all packuments in a single flat directory (unlike pnpm's per-host layout), so this prints the registries you're currently configured to talk to rather than the registries that happen to be in the cache. -"""# + cmd list-registries help="List configured registries from the project + user `.npmrc`." effect=read { + long_help "List configured registries from the project + user `.npmrc`.\n\nAube stores all packuments in a single flat directory (unlike\npnpm's per-host layout), so this prints the registries you're\ncurrently configured to talk to rather than the registries that\nhappen to be in the cache." } - cmd prune help="Remove stale extracted primer files from the metadata cache" effect=write { - flag --age-days help="Minimum age in days before an old primer file is removed" default="30" { + cmd path help="Print the directory used for metadata and policy caches." effect=read { + } + cmd prune help="Remove stale extracted primer files from the metadata cache." effect=write { + flag --age-days help="Minimum age in days before an old primer file is removed." default="30" { arg } - flag --dry-run help="Do not actually delete anything" + flag --dry-run help="Do not actually delete anything." } - cmd view help="View the cached metadata for a single package" effect=read { - long_help #""" -View the cached metadata for a single package. - -Prints a summary (versions, dist-tags, ETag, fetched-at) by default; `--json` dumps the raw cache file. -"""# - flag --json help="Dump the raw on-disk cache JSON instead of a summary" - arg help="Package name (scoped names like `@babel/core` are accepted)" + cmd view help="View the cached metadata for a single package." effect=read { + long_help "View the cached metadata for a single package.\n\nPrints a summary (versions, dist-tags, ETag, fetched-at) by\ndefault; `--json` dumps the raw cache file." + flag --json help="Dump the raw on-disk cache JSON instead of a summary." + arg help="Package name (scoped names like `@babel/core` are accepted)." } } cmd cat-file help="Print a file from the global store by integrity or hex hash" effect=read { - arg help="File hash to look up" help_long=#""" -File hash to look up. - -Accepts `sha512-` (pnpm integrity format) or a raw hex CAS digest. -"""# + arg help="File hash to look up." { + long_help "File hash to look up.\n\nAccepts `sha512-` (pnpm integrity format) or a raw hex\nCAS digest." + } } cmd cat-index help="Print the cached package index JSON for `@`" effect=read { - arg help="Package to inspect, in `name@version` form (e.g. `lodash@4.17.21`, `@babel/core@7.26.0`)" help_long=#""" -Package to inspect, in `name@version` form (e.g. `lodash@4.17.21`, `@babel/core@7.26.0`). - -An exact version is required — ranges and dist-tags aren't resolved here. -"""# + arg help="Package to inspect, in `name@version` form (e.g. `lodash@4.17.21`, `@babel/core@7.26.0`)." { + long_help "Package to inspect, in `name@version` form (e.g. `lodash@4.17.21`,\n`@babel/core@7.26.0`).\n\nAn exact version is required — ranges and dist-tags aren't\nresolved here." + } } -cmd check help="Verify installed packages can resolve their declared deps" effect=read { - long_help #""" -Verify installed packages can resolve their declared deps. - -Walks the `node_modules/` symlink tree and confirms every dependency in each `package.json` resolves to a real entry. -"""# - after_long_help #""" -Examples: - - $ aube check - node_modules symlink tree is consistent (checked 248 packages). - - # With issues - $ aube check - 2 broken dependency links found: - - vscode-languageserver@9.0.1 - ✕ cannot resolve: vscode-languageserver-protocol@3.17.5 - - vscode-languageserver-protocol@3.17.5 - ✕ cannot resolve: vscode-languageserver-types@3.17.5 - ✕ cannot resolve: vscode-jsonrpc@8.2.1 - - # Machine-readable - $ aube check --json - -"""# - flag --json help="Emit a JSON report instead of the human-readable list" +cmd check help="Verify installed packages can resolve their declared deps." effect=read { + long_help "Verify installed packages can resolve their declared deps.\n\nWalks the `node_modules/` symlink tree and confirms every\ndependency in each `package.json` resolves to a real entry." + flag --json help="Emit a JSON report instead of the human-readable list." } -cmd ci help="Clean install: delete node_modules, then install with frozen lockfile" effect=write { +cmd ci help="Clean install: delete node_modules, then install with frozen lockfile." effect=write { alias clean-install - alias ic install-clean hide=#true - long_help #""" -Clean install: delete node_modules, then install with frozen lockfile. - -Use in CI to guarantee a reproducible install from the committed lockfile. -"""# + alias ic + alias install-clean + long_help "Clean install: delete node_modules, then install with frozen lockfile.\n\nUse in CI to guarantee a reproducible install from the committed lockfile." flag --ignore-scripts help="Skip lifecycle scripts (no-op; aube already skips by default)" flag --no-optional help="Skip optionalDependencies; don't install optional native modules" - flag --frozen-lockfile help="Error if the lockfile drifts from package.json" - flag --no-frozen-lockfile help="Always re-resolve, even if the lockfile is up to date" - flag --prefer-frozen-lockfile help="Use the lockfile when fresh, re-resolve when stale" - flag --fetch-retries help="Number of retry attempts for failed registry fetches" { - long_help #""" -Number of retry attempts for failed registry fetches. - -Overrides `fetchRetries` / `fetch-retries` from `.npmrc` / `aube-workspace.yaml` when set. Pair with `--fetch-timeout` to fail fast in scripted test runs. -"""# + flag --frozen-lockfile help="Error if the lockfile drifts from package.json." help_heading=Lockfile { + conflicts --no-frozen-lockfile --prefer-frozen-lockfile + } + flag --no-frozen-lockfile help="Always re-resolve, even if the lockfile is up to date." help_heading=Lockfile { + conflicts --frozen-lockfile --prefer-frozen-lockfile + } + flag --prefer-frozen-lockfile help="Use the lockfile when fresh, re-resolve when stale." help_heading=Lockfile { + conflicts --frozen-lockfile --no-frozen-lockfile + } + flag --fetch-retries help="Number of retry attempts for failed registry fetches." help_heading=Network { + long_help "Number of retry attempts for failed registry fetches.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs." arg } - flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" { - long_help #""" -Exponential backoff factor between retry attempts. - -Overrides `fetchRetryFactor` / `fetch-retry-factor` from `.npmrc` / `aube-workspace.yaml` when set. Integer-only — the underlying `FetchPolicy.retry_factor` is `u32`. Fractional values like `1.5` are rejected by clap. -"""# + flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network { + long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser." arg } - flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" { - long_help #""" -Upper bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Upper bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" { - long_help #""" -Lower bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Lower bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" { - long_help #""" -Per-request HTTP timeout in milliseconds. - -Overrides `fetchTimeout` / `fetch-timeout` from `.npmrc` / `aube-workspace.yaml` when set. Applied via `reqwest`'s `.timeout()` so it covers headers + body together. -"""# + flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network { + long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together." arg } - flag --registry help="Override the default registry URL for this invocation" { - long_help #""" -Override the default registry URL for this invocation. - -Use this npm registry URL for package metadata, tarballs, audit requests, dist-tags, and registry writes. -"""# + flag --registry help="Override the default registry URL for this invocation." help_heading=Network { + long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes." arg } - flag "--disable-global-virtual-store --disable-gvs" help="Force the shared global virtual store off for this invocation" { - long_help #""" -Force the shared global virtual store off for this invocation. - -Packages are materialized inside the project's virtual store instead of symlinked from `~/.cache/aube/virtual-store/`. -"""# + flag "--disable-global-virtual-store --disable-gvs" help="Force the shared global virtual store off for this invocation." help_heading="Virtual store" conflicts=--enable-global-virtual-store { + long_help "Force the shared global virtual store off for this invocation.\n\nPackages are materialized inside the project's virtual store\ninstead of symlinked from `~/.cache/aube/virtual-store/`." } - flag "--enable-global-virtual-store --enable-gvs" help="Force the shared global virtual store on for this invocation" { - long_help #""" -Force the shared global virtual store on for this invocation. - -Overrides CI's default per-project materialization and the `disableGlobalVirtualStoreForPackages` auto-disable heuristic. -"""# + flag "--enable-global-virtual-store --enable-gvs" help="Force the shared global virtual store on for this invocation." help_heading="Virtual store" conflicts=--disable-global-virtual-store { + long_help "Force the shared global virtual store on for this invocation.\n\nOverrides CI's default per-project materialization and the\n`disableGlobalVirtualStoreForPackages` auto-disable heuristic." } } -cmd clean help="Remove `node_modules` across every workspace project" effect=write { - long_help #""" -Remove `node_modules` across every workspace project. - -`--lockfile` / `-l` also deletes lockfiles. A `clean` script in the root `package.json` overrides the built-in. -"""# - flag "-l --lockfile" help="Also remove lockfiles at the workspace root" { - long_help #""" -Also remove lockfiles at the workspace root. - -Targets `aube-lock.yaml`, `pnpm-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, and `bun.lock`. -"""# +cmd clean help="Remove `node_modules` across every workspace project." effect=write { + long_help "Remove `node_modules` across every workspace project.\n\n`--lockfile` / `-l` also deletes lockfiles. A `clean` script in\nthe root `package.json` overrides the built-in." + flag "-l --lockfile" help="Also remove lockfiles at the workspace root." { + long_help "Also remove lockfiles at the workspace root.\n\nTargets `aube-lock.yaml`, `pnpm-lock.yaml`, `package-lock.json`,\n`npm-shrinkwrap.json`, `yarn.lock`, and `bun.lock`." } } cmd completion help="Generate shell completions (bash, zsh, fish)" effect=read { - flag --complete help="Emit dynamic candidates for the shell completion engine" hide=#true { - arg { - choices package bin workspace setting patch - } - } - flag --query help="Current word being completed" hide=#true default="" { - arg - } arg help="The shell to generate completions for (bash, zsh, fish)" } cmd config help="Read and write settings in `.npmrc`" effect=read { - alias c hide=#true - flag --all help="Also list settings that have no value set" { - long_help #""" -Also list settings that have no value set. - -Renders one row per setting in `settings.toml`, with the default and description shown for unset entries. - -Only valid with `--location merged` (the default), since a per-file view can't distinguish "not set anywhere" from "set in the other file" and would render misleading defaults. -"""# + alias c + flag --all help="Also list settings that have no value set." { + long_help "Also list settings that have no value set.\n\nRenders one row per setting in `settings.toml`, with the\ndefault and description shown for unset entries.\n\nOnly valid with `--location merged` (the default), since a\nper-file view can't distinguish \"not set anywhere\" from \"set in\nthe other file\" and would render misleading defaults." } - flag --json help="Emit all entries as a JSON object keyed by setting name" { - long_help #""" -Emit all entries as a JSON object keyed by setting name. - -Matches `pnpm config list --json`. Honors `--all` and `--location` the same way the default text output does. -"""# + flag --json help="Emit all entries as a JSON object keyed by setting name." { + long_help "Emit all entries as a JSON object keyed by setting name.\n\nMatches `pnpm config list --json`. Honors `--all` and\n`--location` the same way the default text output does." } - flag --local help="Shortcut for `--location project`" { - long_help #""" -Shortcut for `--location project`. - -Conflicts with `--all` since `--all` only makes sense against the merged view — see the `--all` docs for why. -"""# + flag --local help="Shortcut for `--location project`." { + long_help "Shortcut for `--location project`.\n\nConflicts with `--all` since `--all` only makes sense against\nthe merged view — see the `--all` docs for why." + conflicts --location --all } - flag --location help="Which config location(s) to list" { - long_help #""" -Which config location(s) to list. - -`merged` (default) walks `~/.npmrc`, user aube config, then the project's `.npmrc` with last-write-wins precedence, matching how install reads config. -"""# + flag --location help="Which config location(s) to list." { + long_help "Which config location(s) to list.\n\n`merged` (default) walks `~/.npmrc`, user aube config, then\nthe project's `.npmrc` with last-write-wins precedence,\nmatching how install reads config." arg { - choices merged user project global + choices { + choice merged help="Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses)." + choice user help="Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)" + choice project help="Only `/.npmrc`" + choice global help="Alias for `user`." + } } } cmd delete help="Delete a key from aube config or the selected `.npmrc` file" effect=destructive { - alias rm remove unset - flag --local help="Shortcut for `--location project`" - flag --location help="Which config location to act on" default=user { - long_help #""" -Which config location to act on. - -Defaults to `user`. Delete sweeps both aube's own config (`~/.config/aube/config.toml` at user-scope, `/.config/aube/config.toml` at project-scope) and the matching `.npmrc`, so the call works regardless of which file the value was originally written to. -"""# + alias rm + alias remove + alias unset + flag --local help="Shortcut for `--location project`." conflicts=--location + flag --location help="Which config location to act on." default=user { + long_help "Which config location to act on.\n\nDefaults to `user`. Delete sweeps both aube's own config\n(`~/.config/aube/config.toml` at user-scope,\n`/.config/aube/config.toml` at project-scope) and the\nmatching `.npmrc`, so the call works regardless of which file\nthe value was originally written to." arg { - choices user project global + choices { + choice user help="User config (`~/.config/aube/config.toml` for known aube settings, `~/.npmrc` for registry/auth and unknown keys)" + choice project help="`/.npmrc`" + choice global help="Alias for `user` — aube has no separate global config file." + } } } - arg help="The setting key" help_long=#""" -The setting key. - -Accepts either a pnpm canonical name (e.g. `autoInstallPeers`) or an `.npmrc` alias (e.g. `auto-install-peers`). -"""# + arg help="The setting key." { + long_help "The setting key.\n\nAccepts either a pnpm canonical name (e.g. `autoInstallPeers`)\nor an `.npmrc` alias (e.g. `auto-install-peers`)." + } } cmd explain help="Explain a known setting, including defaults and supported config sources" effect=read { - arg help="Setting key, `.npmrc` alias, env var, workspace YAML key, or CLI flag" + arg help="Setting key, `.npmrc` alias, env var, workspace YAML key, or CLI flag." } cmd find help="Search known settings by name, source key, or description" effect=read { alias search - arg … help="Words to search for" var=#true + arg ... help="Words to search for." } cmd get help="Print the effective value of a key" effect=read { - flag --json help="Emit the value as JSON" { - long_help #""" -Emit the value as JSON. - -Matches `pnpm config get --json`: a missing key renders as `undefined`, a found value is JSON-encoded. -"""# + flag --json help="Emit the value as JSON." { + long_help "Emit the value as JSON.\n\nMatches `pnpm config get --json`: a missing key renders as\n`undefined`, a found value is JSON-encoded." } - flag --local help="Shortcut for `--location project`" - flag --location help="Which config location(s) to read" default=merged { - long_help #""" -Which config location(s) to read. - -Defaults to `merged` — the last-write-wins view of user aube config, `~/.npmrc`, then `./.npmrc`, matching what install actually sees. Use `user` or `project` to restrict the lookup. -"""# + flag --local help="Shortcut for `--location project`." conflicts=--location + flag --location help="Which config location(s) to read." default=merged { + long_help "Which config location(s) to read.\n\nDefaults to `merged` — the last-write-wins view of user aube\nconfig, `~/.npmrc`, then `./.npmrc`, matching what install\nactually sees. Use `user` or `project` to restrict the lookup." arg { - choices merged user project global + choices { + choice merged help="Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses)." + choice user help="Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)" + choice project help="Only `/.npmrc`" + choice global help="Alias for `user`." + } } } - arg help="The setting key" help_long=#""" -The setting key. - -Accepts either a pnpm canonical name (e.g. `autoInstallPeers`) or an `.npmrc` alias (e.g. `auto-install-peers`). -"""# + arg help="The setting key." { + long_help "The setting key.\n\nAccepts either a pnpm canonical name (e.g. `autoInstallPeers`)\nor an `.npmrc` alias (e.g. `auto-install-peers`)." + } } cmd list help="Print every key/value from aube config and selected `.npmrc` file(s)" effect=read { alias ls - flag --all help="Also list settings that have no value set" { - long_help #""" -Also list settings that have no value set. - -Renders one row per setting in `settings.toml`, with the default and description shown for unset entries. - -Only valid with `--location merged` (the default), since a per-file view can't distinguish "not set anywhere" from "set in the other file" and would render misleading defaults. -"""# + flag --all help="Also list settings that have no value set." { + long_help "Also list settings that have no value set.\n\nRenders one row per setting in `settings.toml`, with the\ndefault and description shown for unset entries.\n\nOnly valid with `--location merged` (the default), since a\nper-file view can't distinguish \"not set anywhere\" from \"set in\nthe other file\" and would render misleading defaults." } - flag --json help="Emit all entries as a JSON object keyed by setting name" { - long_help #""" -Emit all entries as a JSON object keyed by setting name. - -Matches `pnpm config list --json`. Honors `--all` and `--location` the same way the default text output does. -"""# + flag --json help="Emit all entries as a JSON object keyed by setting name." { + long_help "Emit all entries as a JSON object keyed by setting name.\n\nMatches `pnpm config list --json`. Honors `--all` and\n`--location` the same way the default text output does." } - flag --local help="Shortcut for `--location project`" { - long_help #""" -Shortcut for `--location project`. - -Conflicts with `--all` since `--all` only makes sense against the merged view — see the `--all` docs for why. -"""# + flag --local help="Shortcut for `--location project`." { + long_help "Shortcut for `--location project`.\n\nConflicts with `--all` since `--all` only makes sense against\nthe merged view — see the `--all` docs for why." + conflicts --location --all } - flag --location help="Which config location(s) to list" { - long_help #""" -Which config location(s) to list. - -`merged` (default) walks `~/.npmrc`, user aube config, then the project's `.npmrc` with last-write-wins precedence, matching how install reads config. -"""# + flag --location help="Which config location(s) to list." { + long_help "Which config location(s) to list.\n\n`merged` (default) walks `~/.npmrc`, user aube config, then\nthe project's `.npmrc` with last-write-wins precedence,\nmatching how install reads config." arg { - choices merged user project global + choices { + choice merged help="Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses)." + choice user help="Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)" + choice project help="Only `/.npmrc`" + choice global help="Alias for `user`." + } } } } cmd set help="Write a key=value pair to aube config or the selected `.npmrc` file" effect=write { - flag --local help="Shortcut for `--location project`" - flag --location help="Which config location to write to" default=user { - long_help #""" -Which config location to write to. - -Defaults to `user`. Writes land in `.npmrc` for the npm-shared surface — per-host auth/cert templates, scoped registries, and settings tagged `npmShared = true` in the settings registry (`registry`, `proxy` / `https-proxy`, `engine-strict`, `ignore-scripts`, etc.) — so npm and yarn read the same value. Aube-only and pnpm-only settings, plus unknown keys, land in aube's own config (`~/.config/aube/config.toml` at user scope, `/.config/aube/config.toml` at project scope) where sibling tools don't see them. - -Dotted writes for aube map settings (`allowBuilds.`, `overrides.`, …) edit one entry at a time. At project scope (`--local`) they land in `pnpm-workspace.yaml#.` or `package.json#aube..` if no workspace yaml exists, the same place install reads from. User-scope dotted writes for these maps error: aube only reads them per project. -"""# + flag --local help="Shortcut for `--location project`." conflicts=--location + flag --location help="Which config location to write to." default=user { + long_help "Which config location to write to.\n\nDefaults to `user`. Writes land in `.npmrc` for the npm-shared\nsurface — per-host auth/cert templates, scoped registries, and\nsettings tagged `npmShared = true` in the settings registry\n(`registry`, `proxy` / `https-proxy`, `engine-strict`,\n`ignore-scripts`, etc.) — so npm and yarn read the same value.\nAube-only and pnpm-only settings, plus unknown keys, land in\naube's own config (`~/.config/aube/config.toml` at user scope,\n`/.config/aube/config.toml` at project scope) where\nsibling tools don't see them.\n\nDotted writes for aube map settings (`allowBuilds.`,\n`overrides.`, …) edit one entry at a time. At project\nscope (`--local`) they land in\n`pnpm-workspace.yaml#.` or\n`package.json#aube..` if no workspace yaml exists,\nthe same place install reads from. User-scope dotted writes\nfor these maps error: aube only reads them per project." arg { - choices user project global + choices { + choice user help="User config (`~/.config/aube/config.toml` for known aube settings, `~/.npmrc` for registry/auth and unknown keys)" + choice project help="`/.npmrc`" + choice global help="Alias for `user` — aube has no separate global config file." + } } } - arg help="Setting key (canonical name or `.npmrc` alias)" - arg help="Value to write. Stored verbatim after `key=`" + arg help="Setting key (canonical name or `.npmrc` alias)." + arg help="Value to write. Stored verbatim after `key=`." + } + cmd tui help="Browse known settings in an interactive terminal UI" effect=write { } - cmd tui help="Browse known settings in an interactive terminal UI" effect=write } cmd create help="Scaffold a project from a `create-*` starter kit (via dlx)" { - flag --fetch-retries help="Number of retry attempts for failed registry fetches" { - long_help #""" -Number of retry attempts for failed registry fetches. - -Overrides `fetchRetries` / `fetch-retries` from `.npmrc` / `aube-workspace.yaml` when set. Pair with `--fetch-timeout` to fail fast in scripted test runs. -"""# + flag --fetch-retries help="Number of retry attempts for failed registry fetches." help_heading=Network { + long_help "Number of retry attempts for failed registry fetches.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs." arg } - flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" { - long_help #""" -Exponential backoff factor between retry attempts. - -Overrides `fetchRetryFactor` / `fetch-retry-factor` from `.npmrc` / `aube-workspace.yaml` when set. Integer-only — the underlying `FetchPolicy.retry_factor` is `u32`. Fractional values like `1.5` are rejected by clap. -"""# + flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network { + long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser." arg } - flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" { - long_help #""" -Upper bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Upper bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" { - long_help #""" -Lower bound (ms) on the computed retry backoff. - -Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set. -"""# + flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff." help_heading=Network { + long_help "Lower bound (ms) on the computed retry backoff.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set." arg } - flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" { - long_help #""" -Per-request HTTP timeout in milliseconds. - -Overrides `fetchTimeout` / `fetch-timeout` from `.npmrc` / `aube-workspace.yaml` when set. Applied via `reqwest`'s `.timeout()` so it covers headers + body together. -"""# + flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network { + long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together." arg } - flag --registry help="Override the default registry URL for this invocation" { - long_help #""" -Override the default registry URL for this invocation. - -Use this npm registry URL for package metadata, tarballs, audit requests, dist-tags, and registry writes. -"""# + flag --registry help="Override the default registry URL for this invocation." help_heading=Network { + long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes." arg } - arg "[PARAMS]…" help="Template package name followed by any args to pass through to the scaffold binary" help_long=#""" -Template package name followed by any args to pass through to the scaffold binary. - -The first positional is the template; the rest are forwarded verbatim to `create-