feat(lockfile): add options field for tool artifact identity

[jdx]

Summary

• Adds an options field to LockfileTool to properly account for tool options that affect which artifact is downloaded or compiled
• This ensures lockfiles correctly differentiate between installations with different options (e.g., exe=rg,matching=musl for ripgrep)
• Supports core plugins with settings-based compiler conditionals (python.compile, node.flavor, etc.)

Note: This PR is based on #7091 (cross-platform lockfile support)

Key Changes

Core Infrastructure:

• Add resolve_lockfile_options() method to Backend trait with default empty implementation
• Add options field to LockfileTool struct (only serialized when non-empty via skip_serializing_if)
• Update get_locked_version() to require exact options match
• Update merge logic to match on version AND options
• Add is_current() method to PlatformTarget
• Add mise lock call to xtasks/release-plz script

Simple Backend Implementations:

Backend	Options tracked
ubi	exe, matching, matching_regex, provider
cargo	features, default-features, bin
github	asset_pattern, url, version_prefix
go	tags
pipx	extras, pipx_args, uvx_args, uvx

Core Plugin Implementations:

Plugin	Settings resolved	Default for other platforms
python	compile, precompiled_arch, precompiled_os, precompiled_flavor	compile=false
node	compile, flavor	compile=false
erlang	compile	compile=false
ruby	ruby_install	ruby_install=false

New Lockfile Format

[[tools.ripgrep]]
version = "14.0.0"
backend = "ubi:BurntSushi/ripgrep"
options = { exe = "rg", matching = "musl" }

[tools.ripgrep.platforms.linux-x64]
checksum = "blake3:abc123"

Test plan

• All existing tests pass
• Added 4 new tests for options field parsing, serialization, and matching
• Ran mise lock successfully in repo
• Manual testing with different tool options

🤖 Generated with Claude Code

---

Note

Add options to lockfile and implement backend/plugin hooks to resolve and persist artifacts based on option-sensitive identities; update CLI lock flow and tests.

• Lockfile/Core:
  • Add options to LockfileTool; serialize only when non-empty; parse from TOML.
  • Match lock entries by version AND exact options; merge logic updated accordingly.
  • Expose Backend::resolve_lockfile_options (default empty) and PlatformTarget::is_current().
  • ToolRequest.lockfile_resolve passes resolved options; get_locked_backend added for discovery.
• Backends:
  • github, ubi, cargo, go, pipx implement resolve_lockfile_options (e.g., asset_pattern/url/version_prefix, exe/matching/provider, features/default-features/bin, tags, extras/pipx_args/uvx[_args]).
  • Minor: aqua improves version-prefix detection from existing URLs.
• Core Plugins:
  • python, node, erlang, ruby return settings-derived options (e.g., compile, flavor, ruby_install, precompiled selectors) for current platform only.
• CLI:
  • mise lock resolves per-platform URLs and stores alongside resolved options.
  • Defaults to common platforms + existing + current; parallelizes tasks; summarizes updates.
• Tool resolution:
  • backend_arg prefers backend from lockfile when present.
• Scripts/Lock:
  • xtasks/release-plz now runs mise lock and stages mise.lock et al.
  • mise.lock refreshed with explicit platform assets.
• Tests:
  • Add tests for options parsing/serialization and matching; ensure array format preserved.

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

[Copilot]

Pull request overview

This PR adds an options field to the lockfile format to properly differentiate tool installations with different configuration options that affect which artifact is downloaded or compiled. This ensures lockfiles correctly track tools like ripgrep with options exe=rg,matching=musl separately from installations without these options, and supports core plugins with settings-based compiler conditionals.

Key Changes:

• Added resolve_lockfile_options() method to Backend trait with implementations across 9 backends (ubi, cargo, github, go, pipx) and 4 core plugins (python, node, erlang, ruby)
• Extended LockfileTool struct with options field and updated lockfile matching logic to require exact options match
• Added is_current() helper method to PlatformTarget for determining if a target represents the current platform

Reviewed changes

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

Show a summary per file

File	Description
src/backend/mod.rs	Adds resolve_lockfile_options() trait method with default empty implementation
src/backend/platform_target.rs	Adds is_current() helper method for platform comparison
src/backend/ubi.rs	Implements options tracking for exe, matching, matching_regex, provider
src/backend/cargo.rs	Implements options tracking for features, default-features, bin
src/backend/github.rs	Implements options tracking for asset_pattern, url, version_prefix
src/backend/go.rs	Implements options tracking for tags
src/backend/pipx.rs	Implements options tracking for extras, pipx_args, uvx_args, uvx
src/plugins/core/python.rs	Resolves compile and precompiled options from settings
src/plugins/core/node.rs	Resolves compile and flavor options from settings
src/plugins/core/erlang.rs	Resolves compile option from settings
src/plugins/core/ruby.rs	Resolves ruby_install option from settings
src/lockfile.rs	Adds options field to LockfileTool, updates parsing/serialization/matching logic
src/toolset/tool_request.rs	Updates lockfile_resolve to pass options to get_locked_version
src/cli/args/backend_arg.rs	Updates backend discovery to use empty options map

---

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

[Copilot]

The version matching logic using starts_with can cause issues when you have versions like '3.1' and '3.12'. A prefix of '3.1' would incorrectly match '3.12'. Consider using semantic version comparison or ensuring the prefix is followed by a version separator (e.g., '.', '-', or end of string).

[Copilot]

The documentation should clarify what 'sensible defaults' means for cross-platform scenarios. It would be helpful to explicitly state what the expected behavior is when target.is_current() is false, such as whether it should use minimal/conservative options or platform-specific defaults.

Suggested change

	/// For the current platform: resolves from Settings and ToolRequest options
	/// For other platforms (cross-platform mise lock): uses sensible defaults
	/// For the current platform (`target.is_current()` is true): resolves from Settings and ToolRequest options.
	/// For other platforms (cross-platform mise lock, where `target.is_current()` is false): the default implementation returns an empty set of options (i.e., minimal/conservative options).
	/// Backends may override this method to provide platform-specific defaults if certain options are required for artifact resolution on non-host platforms.

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.10 x -- echo	20.3 ± 0.5	19.3	24.0	1.00
mise x -- echo	20.9 ± 0.6	19.4	22.7	1.03 ± 0.04

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.10 env	19.7 ± 0.7	18.8	28.6	1.00
mise env	20.4 ± 0.6	19.2	25.3	1.04 ± 0.05

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.10 hook-env	19.7 ± 0.4	18.6	20.9	1.00
mise hook-env	20.5 ± 0.7	19.2	24.1	1.04 ± 0.04

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.10 ls	16.8 ± 0.4	16.0	18.3	1.00
mise ls	17.8 ± 0.5	16.3	19.3	1.05 ± 0.04

xtasks/test/perf

Command	mise-2025.11.10	mise	Variance
install (cached)	107ms	108ms	+0%
ls (cached)	65ms	66ms	-1%
bin-paths (cached)	72ms	72ms	+0%
task-ls (cached)	423ms	433ms	-2%