feat(aqua): add symlink_bins option to filter exposed binaries #7076

jdx · 2025-11-26T23:50:29Z

Summary

Add symlink_bins option for aqua backend tools that creates a .mise-bins directory with symlinks only to binaries explicitly defined in the aqua registry
Enable symlink_bins=true by default for aws-cli in registry, preventing bundled Python from being exposed on PATH
Add e2e test that verifies Python is not exposed through aws-cli (runs on Linux)

Problem

Tools like aws-cli and azure-cli bundle Python internally. When mise adds these tools to PATH, all binaries in their bin directories get exposed (including bundled Python), which conflicts with the user's intended Python version.

Aqua's registry already defines exactly which binaries should be exposed (e.g., aws and aws_completer for aws-cli via the files field), but mise currently exposes entire bin directories.

Solution

The new symlink_bins option (boolean) creates a filtered .mise-bins directory containing symlinks only to the binaries defined in the aqua registry:

[tools]
aws-cli = { version = "latest", symlink_bins = true }

For aws-cli, this is now enabled by default in the registry.

Test plan

Verify aws-cli exposes only aws and aws_completer in .mise-bins directory
Verify Python is NOT exposed on PATH through aws-cli
e2e test passes (Linux-only due to macOS pkg extraction limitations)
Lint passes

Closes #6972, #4675

🤖 Generated with Claude Code

Note

Introduces symlink_bins in the aqua backend to expose only registry-defined binaries (enabled for aws-cli), with docs and an e2e test.

Backend (Aqua):
- Add symlink_bins option; when set, list_bin_paths returns /.mise-bins and install creates /.mise-bins with symlinks only to registry-defined binaries.
- Implement create_symlink_bin_dir and symlink_bins helpers; wire into install flow; minor refactors in symlink/copy logic.
Registry:
- Enable symlink_bins = "true" for aqua:aws/aws-cli in registry.toml.
Docs:
- Document symlink_bins option and behavior in docs/dev-tools/backends/aqua.md.
Tests:
- Add e2e e2e/backend/test_aqua_symlink_bins verifying only aws/aws_completer are exposed and Python is not (Linux-only).

^{Written by Cursor Bugbot for commit 68329f7. This will update automatically on new commits. Configure here.}

Copilot

Pull request overview

This PR introduces a symlink_bins option for aqua backend tools to filter exposed binaries, preventing bundled dependencies from being exposed on PATH. The feature is enabled by default for aws-cli to avoid conflicts with user-installed Python versions.

Key Changes:

Added symlink_bins option to aqua backend that creates a .mise-bins directory with symlinks only to registry-defined binaries
Enabled symlink_bins=true by default for aws-cli in the registry
Added Linux-only e2e test verifying Python is not exposed through aws-cli

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/backend/aqua.rs	Implements `symlink_bins` option and `create_symlink_bin_dir` method to filter exposed binaries
registry.toml	Enables `symlink_bins` by default for aws-cli tool
e2e/backend/test_aqua_symlink_bins	Adds e2e test verifying symlink filtering works correctly (Linux-only)
docs/dev-tools/backends/aqua.md	Documents the new `symlink_bins` option with usage examples

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-26T23:50:54Z

src/backend/aqua.rs

+        for (_, dst) in &srcs {
+            if !dst.exists() {
+                continue;
+            }
+            let bin_name = dst.file_name().unwrap();


The unwrap() on line 1098 could panic if dst ends with ... Consider using proper error handling with a descriptive message, such as dst.file_name().ok_or_else(|| eyre!("Invalid binary path: {}", dst.display()))?.

Copilot · 2025-11-26T23:50:54Z

e2e/backend/test_aqua_symlink_bins

+	# Verify Python is NOT in the .mise-bins directory
+	assert_not_contains "echo '$bins'" "Python"
+	assert_not_contains "echo '$bins'" "python"


The test checks for 'Python' and 'python' but doesn't verify that other bundled executables (like python3, pip, etc.) are also not exposed. Consider adding assertions for common Python-related binaries to ensure comprehensive filtering.

src/backend/aqua.rs

github-actions · 2025-11-27T00:15:50Z

Hyperfine Performance

`mise x -- echo`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2025.11.8 x -- echo`	20.1 ± 0.4	19.5	24.4	1.00
`mise x -- echo`	20.4 ± 0.3	19.8	21.7	1.01 ± 0.02

`mise env`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2025.11.8 env`	19.8 ± 0.6	19.0	24.5	1.00
`mise env`	19.9 ± 0.5	19.2	21.9	1.01 ± 0.04

`mise hook-env`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2025.11.8 hook-env`	19.6 ± 0.3	19.0	21.9	1.00
`mise hook-env`	19.9 ± 0.3	19.3	21.0	1.01 ± 0.02

`mise ls`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2025.11.8 ls`	17.1 ± 0.6	16.5	25.9	1.00
`mise ls`	17.4 ± 0.4	16.6	19.0	1.01 ± 0.04

`xtasks/test/perf`

Command	mise-2025.11.8	mise	Variance
install (cached)	112ms	112ms	+0%
ls (cached)	68ms	68ms	+0%
bin-paths (cached)	75ms	74ms	+1%
task-ls (cached)	434ms	432ms	+0%

jdx · 2025-11-27T00:39:58Z

bugbot run

cursor

Bug: Find predicate may skip existing binaries when creating symlinks

The find() call in create_symlink_bin_dir only matches entries by filename, with the dst.exists() check outside the predicate. For packages without version_prefix, srcs() generates multiple entries with different version path formats (e.g., "1.0.0" and "v1.0.0"). Since find() returns the first match, if that entry's dst doesn't exist (because the extracted files use the other version format), the existence check fails and no symlink is created—even though a later entry's dst does exist. Moving dst.exists() into the find predicate would ensure only existing binaries are considered.

src/backend/aqua.rs#L1051-L1055

mise/src/backend/aqua.rs

Lines 1051 to 1055 in c42e87d

    
           // Find the binary by searching for it in the install path 
        
           if let Some(bin_path) = all_files.iter().find(|p| { 
        
               p.file_name() 
        
                   .is_some_and(|n| n.to_string_lossy() == *bin_name)

Tools like aws-cli bundle Python internally which gets exposed on PATH, conflicting with the user's intended Python version. The new symlink_bins option creates a .mise-bins directory with symlinks only to binaries explicitly defined in the aqua registry's files field. - Add symlink_bins option check in list_bin_paths() - Add create_symlink_bin_dir() method to create filtered bin directory - Enable symlink_bins=true by default for aws-cli in registry - Add e2e test (runs on Linux where aws-cli uses zip format) Closes #6972, #4675 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

src/backend/aqua.rs

e2e/backend/test_aqua_symlink_bins

@ev-the-dev

### 📦 Registry - add charmbracelet/crush by @ev-the-dev in [#7075](#7075) ### 🚀 Features - **(aqua)** add symlink_bins option to filter exposed binaries by @jdx in [#7076](#7076) ### 🐛 Bug Fixes - **(aqua)** skip whitespace before pipe token in template parser by @jdx in [#7069](#7069) - **(docs)** link github backends to github repo URLs by @SKalt in [#7071](#7071) ### 📚 Documentation - update node examples from 22 to 24 by @jdx in [#7074](#7074) ### ⚡ Performance - **(hook-env)** add fast-path to skip initialization when nothing changed by @jdx in [#7073](#7073) ### New Contributors - @ev-the-dev made their first contribution in [#7075](#7075) - @SKalt made their first contribution in [#7071](#7071) ## 📦 Aqua Registry Updates #### New Packages (3) - [`SonarSource/sonar-scanner-cli`](https://github.com/SonarSource/sonar-scanner-cli) - [`Stranger6667/jsonschema`](https://github.com/Stranger6667/jsonschema) - [`peteretelej/tree`](https://github.com/peteretelej/tree) #### Updated Packages (2) - [`astral-sh/uv`](https://github.com/astral-sh/uv) - [`pre-commit/pre-commit`](https://github.com/pre-commit/pre-commit)

Adds `filter_bins` option to `github`/`gitlab` backends to exclude unwanted binaries. ref: #5788 (comment) (`pypa/hatch` is not compatible with GitHub backend, so this doesn't directly solve that problem.) This is basically the same as Aqua backend's [`symlink_bins`](#7076), but binaries listed `filter_bins` are found from the bin paths, respecting `bin_path` option too. https://mise.jdx.dev/dev-tools/backends/github.html#bin-path Gemini pointed out that we need wrapper scripts to change `$0`, but I reverted it as it seemed redundant. Aqua has `link` option for tools that depend on `$0`, but it seems such tools are not common. https://aquaproj.github.io/docs/reference/registry-config/files/#link  --- > [!NOTE] > Adds `filter_bins` to GitHub/GitLab backends to expose only specified binaries via a `.mise-bins` directory; updates docs and adds an e2e test. > > - **Backend**: > - Implement `filter_bins` in `src/backend/github.rs`: > - After install, create `.mise-bins` with symlinks only to specified binaries (`create_symlink_bin_dir`, `get_filter_bins`). > - `list_bin_paths` returns `/.mise-bins` when `filter_bins` is set. > - Bin discovery now first respects `bin_path` before fallback search. > - **Docs**: > - Add `filter_bins` option to `docs/dev-tools/backends/github.md` and `docs/dev-tools/backends/gitlab.md` with examples and behavior notes. > - **Tests**: > - Add `e2e/backend/test_github_filter_bins` validating `.mise-bins` contains only `pandoc` for `github:jgm/pandoc`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 4647df4. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>  --------- Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Copilot AI review requested due to automatic review settings November 26, 2025 23:50

Copilot AI reviewed Nov 26, 2025

View reviewed changes

jdx force-pushed the feat/symlink-bins-option branch 4 times, most recently from b326d62 to 271ca76 Compare November 27, 2025 00:00

cursor bot reviewed Nov 27, 2025

View reviewed changes

src/backend/aqua.rs Show resolved Hide resolved

jdx force-pushed the feat/symlink-bins-option branch 3 times, most recently from 732f7f1 to c809f18 Compare November 27, 2025 00:32

jdx force-pushed the feat/symlink-bins-option branch from d7d66ac to c42e87d Compare November 27, 2025 00:47

cursor bot reviewed Nov 27, 2025

View reviewed changes

jdx force-pushed the feat/symlink-bins-option branch from 27687b1 to fae7f9d Compare November 27, 2025 00:51

chore: add debug logging to diagnose CI failure

0809bc2

cursor bot reviewed Nov 27, 2025

View reviewed changes

src/backend/aqua.rs Outdated Show resolved Hide resolved

chore: add more debug logging for symlink_bins

9c4194a

cursor bot reviewed Nov 27, 2025

View reviewed changes

e2e/backend/test_aqua_symlink_bins Outdated Show resolved Hide resolved

jdx added 2 commits November 26, 2025 17:33

chore: add debug output to test

654ba9c

fix(aqua): use assert_directory_exists in symlink_bins test

68329f7

jdx enabled auto-merge (squash) November 27, 2025 01:44

jdx merged commit 8d68822 into main Nov 27, 2025
36 checks passed

jdx deleted the feat/symlink-bins-option branch November 27, 2025 01:47

mise-en-dev mentioned this pull request Nov 27, 2025

chore: release 2025.11.9 #7066

Merged

BrewTestBot mentioned this pull request Nov 27, 2025

mise 2025.11.9 Homebrew/homebrew-core#256167

Merged

risu729 mentioned this pull request Nov 28, 2025

feat(backend): add filter_bins option to github/gitlab backends #7105

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(aqua): add symlink_bins option to filter exposed binaries #7076

feat(aqua): add symlink_bins option to filter exposed binaries #7076

Uh oh!

jdx commented Nov 26, 2025 •

edited by cursor bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 26, 2025

Uh oh!

Copilot AI Nov 26, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 27, 2025 •

edited

Loading

Uh oh!

jdx commented Nov 27, 2025

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


	// Find the binary by searching for it in the install path
	if let Some(bin_path) = all_files.iter().find(\|p\| {
	p.file_name()
	.is_some_and(\|n\| n.to_string_lossy() == *bin_name)

Uh oh!

feat(aqua): add symlink_bins option to filter exposed binaries #7076

feat(aqua): add symlink_bins option to filter exposed binaries #7076

Uh oh!

Conversation

jdx commented Nov 26, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Solution

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Hyperfine Performance

mise x -- echo

mise env

mise hook-env

mise ls

xtasks/test/perf

Uh oh!

jdx commented Nov 27, 2025

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: Find predicate may skip existing binaries when creating symlinks

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jdx commented Nov 26, 2025 •

edited by cursor bot

Loading

github-actions bot commented Nov 27, 2025 •

edited

Loading

`mise x -- echo`

`mise env`

`mise hook-env`

`mise ls`

`xtasks/test/perf`