Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
653 changes: 651 additions & 2 deletions Cargo.lock

Large diffs are not rendered by default.

4 changes: 4 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@ opt-level = 3
[dependencies]
age = { version = "0.11", features = ["ssh"] }
aho-corasick = "1"
aube-registry = { version = "1.32", default-features = false, features = [
"rustls",
] }
aube = { version = "1.32", default-features = false, features = ["rustls"] }
async-backtrace = "0.2"
async-trait = "0.1"
aws-config = { version = "1.5", default-features = false, features = [
Expand Down
91 changes: 44 additions & 47 deletions docs/dev-tools/backends/npm.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,46 +7,44 @@ The code for this is inside of the mise repository at [`./src/backend/npm.rs`](h

## Dependencies

Version resolution (`mise ls-remote`, resolving `latest`) queries the npm
registry directly over HTTP, so no node/npm installation is needed for it. The
registry, scoped registries (`@scope:registry`), and auth tokens configured in
`~/.npmrc` (or `NPM_CONFIG_USERCONFIG`) and `NPM_CONFIG_*` environment
variables are honored. If your setup relies on npm-only configuration such as
`cafile`, client certificates, or an auth token helper, set
[`npm.use_npm_view`](/configuration/settings.html#npm_use_npm_view) to shell
out to `npm view` for version metadata instead (this requires npm to be
installed).

Installing packages relies on the configured package manager.
With the default `npm.package_manager = "auto"` setting, mise uses
[`aube`](https://aube.jdx.dev/) for installing npm packages when it is installed,
similar to how the pipx backend uses `uv` when available.
If you use `aube`, `pnpm`, or `bun` as the package manager, that package manager
must also be installed.
By default mise handles `npm:` tools without needing node or a package manager
CLI installed. Version resolution (`mise ls-remote`, resolving `latest`) queries
the npm registry directly over HTTP, and packages are installed with mise's
embedded [aube](https://github.com/jdx/aube) package manager. The registry,
scoped registries (`@scope:registry`), and auth tokens configured in `~/.npmrc`
(or `NPM_CONFIG_USERCONFIG`) and `NPM_CONFIG_*` environment variables are honored
by both. `node` is only needed to _run_ the installed tools (and any package
lifecycle scripts), not to install them.

To shell out to the npm CLI instead — `npm view` for metadata and
`npm install -g` for installs — set
[`npm.shell_out`](/configuration/settings.html#npm-shell-out) (requires npm to
be installed). Use it if you rely on npm-only configuration the built-in
implementation does not support, such as `cafile`, client certificates, or an
auth token helper.

You can also pick a specific installer with
[`npm.package_manager`](/configuration/settings.html#npm-package-manager). The
default `auto` uses the embedded aube; setting it to `bun`, `pnpm`, or `npm`
shells out to that tool, which must then be installed.

The npm backend forwards [`minimum_release_age`](/configuration/settings.html#minimum_release_age)
to transitive dependency resolution during install. This relies on the
configured package manager supporting its native release-age flag:
to transitive dependency resolution during install. The embedded aube installer
honors it natively. When shelling out, it relies on the package manager
supporting its release-age flag:

- `aube` using its `minimumReleaseAge` setting
- `pnpm >= 10.16.0` using `--config.minimumReleaseAge=<minutes>`
- `bun >= 1.3.0` using `--minimum-release-age <seconds>`
- `npm >= 11.10.0` using `--min-release-age=<days>`; `npm 6.9.0–11.9.x` using `--before <timestamp>` (sub-day `minimum_release_age` windows also use `--before` since `--min-release-age` is day-granular)

If you want transitive protection, install and use a package manager version that meets the
corresponding requirement above. Older versions may fail while processing the forwarded argument.
If you want transitive protection when shelling out, install and use a package
manager version that meets the corresponding requirement above. Older versions
may fail while processing the forwarded argument.

Here is how to install `npm` with mise:
`node` is installed automatically as a dependency. To use a specific package
manager CLI instead of the embedded installer:

```sh
mise use -g node
```

To install `aube`, `pnpm`, or `bun`:

```sh
mise use -g aube
# or
mise use -g pnpm
# or
mise use -g bun
Expand Down Expand Up @@ -86,32 +84,31 @@ package-provided commands such as `preinstall`, `install`, `postinstall`, and `p
allowing them means allowing code from the selected package and its dependencies to run during
installation.

With the default `npm.package_manager = "auto"` setting, mise installs through `aube` when `aube` is
installed. If `aube` is not installed, mise installs through `npm`. Setting
`npm.package_manager = "aube"`, `"pnpm"`, `"bun"`, or `"npm"` chooses that package manager
explicitly. The `allow_builds`, `trust_policy_excludes`, `aube_args`, `pnpm_args`, `bun_args`, and
`npm_args` options only affect the package manager that is actually used; an approval option for one
package manager does not change the behavior of another.
With the default `npm.package_manager = "auto"` setting, mise installs through its embedded `aube`
package manager. Setting `npm.package_manager = "aube"`, `"pnpm"`, `"bun"`, or `"npm"` chooses a
package manager explicitly (`aube` also uses the embedded one; the others shell out).
[`npm.shell_out`](/configuration/settings.html#npm-shell-out) forces the npm CLI. The `allow_builds`,
`trust_policy_excludes`, `pnpm_args`, `bun_args`, and `npm_args` options only affect the package
manager that is actually used; an approval option for one does not change the behavior of another.

For tools that need reviewed dependency build scripts, use `allow_builds` with `aube`, `pnpm`, or
npm 11.16.0+.
For tools that need reviewed dependency build scripts, use `allow_builds` with `aube` (default),
`pnpm`, or npm 11.16.0+.

### `aube`
### `aube` (default)

[`aube`](https://aube.jdx.dev/package-manager/lifecycle-scripts) follows the pnpm v11 build approval
model: dependency lifecycle scripts are denied unless explicitly allowlisted. Use `allow_builds` for
reviewed dependency builds:
The embedded [`aube`](https://aube.jdx.dev/package-manager/lifecycle-scripts) installer follows the
pnpm v11 build approval model: dependency lifecycle scripts are denied unless explicitly allowlisted.
Use `allow_builds` for reviewed dependency builds:

```toml
[tools]
"npm:some-tool" = { version = "latest", allow_builds = ["esbuild"] }
```

`allow_builds` is passed to `aube add --global` as one `--allow-build=<pkg>` flag per package.
Use `trust_policy_excludes` for reviewed aube trust-policy exceptions, or `aube_args` for other
raw aube flags.
Set `allow_builds = true` to pass `--dangerously-allow-all-builds` when you explicitly accept that
every dependency build script may run.
`allow_builds` is written to the install's `aube.allowBuilds` manifest field.
Use `trust_policy_excludes` for reviewed aube trust-policy exceptions.
Set `allow_builds = true` to allow every dependency build script when you explicitly accept the risk.
(The `aube_args` option is ignored now that installs run in-process rather than via the `aube` CLI.)

### `pnpm`

Expand Down
10 changes: 6 additions & 4 deletions e2e/backend/test_backend_missing_deps
Original file line number Diff line number Diff line change
Expand Up @@ -61,18 +61,20 @@ test_npm() {
MISE_NPM_PACKAGE_MANAGER=bun assert_contains "mise ls-remote npm:left-pad" "1.3.0"

# Legacy `npm view` mode still needs npm and warns when it is missing
export MISE_NPM_USE_NPM_VIEW=1
export MISE_NPM_SHELL_OUT=1
test_backend_warning "npm" "mise ls-remote npm:test-package" "npm may be required but was not found"

# Check for helpful install instructions
local output
output=$(MISE_LOG_LEVEL=warn mise ls-remote npm:test-package 2>&1 || true)
test_error_message "npm suggests installing node" "$output" "mise use node@latest"
test_error_message "npm mentions npm is needed for queries" "$output" "npm is required for querying package information"
unset MISE_NPM_USE_NPM_VIEW

# Test install - should show warning but continue
# Install through the npm CLI (shell_out) still needs npm and warns.
test_backend_warning "npm" "mise install npm:test-package@latest" "npm may be required but was not found"
unset MISE_NPM_SHELL_OUT

# The default install path uses the embedded aube package manager, which
# does not require an npm binary (only node, to run installed tools).
}

# Test cargo backend
Expand Down
15 changes: 10 additions & 5 deletions e2e/backend/test_npm_aube
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,13 @@

install_dir="$MISE_DATA_DIR/installs/npm-cowsay/1.6.0"

assert_contains "mise x node@20.11.1 aube@latest npm:cowsay@1.6.0 -- cowsay hello" "hello"
assert_succeed "test -d '$install_dir/global-aube'"
lockfile="$(find "$install_dir/global-aube" -mindepth 2 -maxdepth 2 -name aube-lock.yaml -print -quit)"
assert_succeed "test -f '$lockfile'"
assert_contains "cat '$lockfile'" "cowsay@1.6.0"
# npm: tools install via the embedded aube package manager in-process — no
# aube binary on PATH is required, only node to run the tool.
assert_contains "mise x node@20.11.1 npm:cowsay@1.6.0 -- cowsay hello" "hello"

# Embedded aube installs into a per-tool project dir: node_modules holds the
# package + bin shims, and an aube lockfile is written at the project root.
assert_succeed "test -d '$install_dir/node_modules'"
assert_succeed "test -x '$install_dir/node_modules/.bin/cowsay'"
assert_succeed "test -f '$install_dir/aube-lock.yaml'"
assert_contains "cat '$install_dir/aube-lock.yaml'" "cowsay@1.6.0"
26 changes: 11 additions & 15 deletions e2e/backend/test_npm_package_manager
Original file line number Diff line number Diff line change
Expand Up @@ -97,21 +97,13 @@ assert_contains "cat '$PNPM_DEBUG_LOG'" "--allow-build=tiny"
echo "✓ npm backend successfully installs package using pnpm (package_manager=pnpm)"
mise uninstall npm:tiny@latest >/dev/null 2>&1 || true

# Test 4: npm.package_manager = "aube"
# Test 4: npm.package_manager = "aube" (embedded — no aube binary needed)
echo "Testing npm.package_manager=aube..."
export MISE_NPM_PACKAGE_MANAGER=aube

# Ensure aube is available after the default package manager test, since
# npm.package_manager=auto uses aube when it is already installed.
# Pin to the current aube release checked for this test. Remove this test's
# MISE_MINIMUM_RELEASE_AGE override; the explicit version bypasses the default
# release-age filter.
AUBE_TEST_VERSION="1.16.0"
if ! command -v aube >/dev/null 2>&1; then
echo "aube not available in test environment, installing..."
assert_succeed "env -u MISE_MINIMUM_RELEASE_AGE mise use aube@$AUBE_TEST_VERSION"
fi

# The embedded aube installer runs in-process; there is no aube CLI to shell
# out to, so `aube_args` is ignored (with a warning) and `allow_builds` is
# written to the install's manifest rather than passed as a CLI flag.
cat >.mise.toml <<EOF
[tools]
"npm:tiny" = { version = "latest", aube_args = "--reporter append-only", allow_builds = "tiny" }
Expand All @@ -122,9 +114,13 @@ if ! MISE_DEBUG=1 mise install >"$AUBE_DEBUG_LOG" 2>&1; then
cat "$AUBE_DEBUG_LOG"
exit 1
fi
assert_contains "cat '$AUBE_DEBUG_LOG'" "--reporter"
assert_contains "cat '$AUBE_DEBUG_LOG'" "append-only"
assert_contains "cat '$AUBE_DEBUG_LOG'" "--allow-build=tiny"
# Installed via the embedded package manager (node_modules layout), not a
# shelled-out `aube add --global`.
tiny_install_dir="$MISE_DATA_DIR/installs/npm-tiny"
assert_succeed "test -d '$tiny_install_dir'"
assert_succeed "find '$tiny_install_dir' -type d -name node_modules -print -quit | grep -q ."
# aube_args is not forwarded to any CLI; mise warns that it is ignored.
assert_contains "cat '$AUBE_DEBUG_LOG'" "aube_args"
echo "✓ npm backend successfully installs package using aube (package_manager=aube)"
mise uninstall npm:tiny@latest >/dev/null 2>&1 || true

Expand Down
2 changes: 1 addition & 1 deletion e2e/backend/test_npm_shim_recursion_system_dir
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
# Version queries only shell out to `npm view` in legacy mode now; the
# default path queries the registry over HTTP and never spawns npm. Pin the
# legacy mode so this test keeps covering the shim-recursion guard.
export MISE_NPM_USE_NPM_VIEW=1
export MISE_NPM_SHELL_OUT=1

export MISE_SYSTEM_DATA_DIR="$HOME/.local/share/mise-system"
mkdir -p "$MISE_SYSTEM_DATA_DIR/shims"
Expand Down
4 changes: 2 additions & 2 deletions schema/mise.json
Original file line number Diff line number Diff line change
Expand Up @@ -1324,9 +1324,9 @@
"type": "string",
"enum": ["auto", "npm", "aube", "bun", "pnpm"]
},
"use_npm_view": {
"shell_out": {
"default": false,
"description": "Use the npm CLI (`npm view`) for version metadata queries instead of mise's built-in registry client.",
"description": "Shell out to the npm CLI for `npm:` version metadata and installs instead of mise's built-in aube-based implementation.",
"type": "boolean"
}
}
Expand Down
35 changes: 21 additions & 14 deletions settings.toml
Original file line number Diff line number Diff line change
Expand Up @@ -1781,21 +1781,28 @@ env = "MISE_NPM_PACKAGE_MANAGER"
rust_type = "NpmPackageManager"
type = "String"

[npm.use_npm_view]
[npm.shell_out]
default = false
description = "Use the npm CLI (`npm view`) for version metadata queries instead of mise's built-in registry client."
docs = """
By default, mise queries npm version metadata (`mise ls-remote`, `latest` resolution)
directly from the npm registry over HTTP, honoring the registry, scoped registries,
and auth tokens configured in `~/.npmrc` and `NPM_CONFIG_*` environment variables.
This means node/npm do not need to be installed to resolve `npm:` tool versions.

Enable this setting to shell out to `npm view` instead, e.g. if your setup relies on
npm-specific configuration that mise's registry client does not support, such as
`cafile`, client certificates, or an auth token helper. When enabled, npm must be
installed for version queries to work.
"""
env = "MISE_NPM_USE_NPM_VIEW"
description = "Shell out to the npm CLI for `npm:` version metadata and installs instead of mise's built-in aube-based implementation."
docs = """
By default, mise handles `npm:` tools without needing node/npm installed:
version metadata (`mise ls-remote`, `latest` resolution) is queried directly
from the npm registry over HTTP, and packages are installed with mise's
embedded [aube](https://github.com/jdx/aube) package manager. Both honor the
registry, scoped registries, and auth tokens configured in `~/.npmrc` and
`NPM_CONFIG_*` environment variables.

Enable this setting to shell out to the npm CLI instead — `npm view` for
metadata and `npm install -g` for installs. Use it if your setup relies on
npm-specific configuration the built-in implementation does not support (such
as `cafile`, client certificates, or an auth token helper). When enabled, npm
must be installed.

This applies to the default/`auto` package manager. Explicitly selecting a
package manager with [`npm.package_manager`](#npm-package-manager) (`bun`,
`pnpm`, or `npm`) always shells out to that tool regardless of this setting.
"""
env = "MISE_NPM_SHELL_OUT"
type = "Bool"

[oci.default_from]
Expand Down
Loading