feat(prepare): add mise prepare command for dependency preparation

[jdx]

Summary

Adds a new "prepare" system to mise that ensures project dependencies are ready before running commands. When running mise x npm run dev, mise checks if node_modules/ is stale relative to package-lock.json and runs npm install if needed.

• New mise prepare command with --dry-run, --force, --list options
• Auto-prepare before mise x and mise run (can disable with --no-prepare)
• Built-in NPM provider that detects npm/yarn/pnpm/bun from lockfiles
• Custom prepare rules via [prepare.rules.*] in mise.toml
• Stateless mtime-based freshness checking (compares lockfile vs node_modules mtime)
• Extensible framework for future providers (cargo, go, pip, etc.)

Example usage

# Explicit prepare
mise prepare                    # Run all applicable prepare steps
mise prepare --dry-run          # Show what would run without executing
mise prepare --force            # Force run even if outputs are fresh
mise prepare --list             # List available prepare providers

# Automatic (default behavior)
mise x npm run dev              # Runs npm install if stale, then npm run dev
mise run build                  # Runs prepare steps, then build task

# Disable auto-prepare
mise x --no-prepare npm run dev
MISE_PREPARE_AUTO=false mise x npm run dev

Configuration

# mise.toml
[prepare]
auto = true              # Enable auto-prepare (default)
disable = ["cargo"]      # Disable specific providers

[prepare.rules.codegen]
sources = ["schema/*.graphql"]
outputs = ["src/generated/"]
run = "npm run codegen"
description = "Generate GraphQL types"

Test plan

• Builds successfully
• Unit tests pass
• Lint passes
• Manual testing with a Node.js project

🤖 Generated with Claude Code

---

Note

Adds an experimental mise prepare command and auto-prepare before mise x/mise run, with built-in/custom providers and docs/completions/manpage updates.

• CLI/Behavior:
  • Add experimental mise prepare (prep) command with --force, --list, --dry-run, --only, --skip.
  • Auto-run prepare before mise exec and mise run; opt out via --no-prepare (shims skip by default).
  • Show staleness warnings in hook-env; new setting settings.status.show_prepare_stale.
• Engine/Providers:
  • Implement prepare engine with mtime freshness checks and parallel execution.
  • Built-in providers: npm, yarn, pnpm, bun, go, pip, poetry, uv, bundler, composer.
  • Support custom providers via [prepare.<id>] in mise.toml (sources/outputs/run/env/dir/auto/description; disable list).
• Docs/Spec/Completions:
  • Add docs/dev-tools/prepare.md; update CLI docs, manpage, usage spec (mise.usage.kdl), VitePress sidebar, and Fig completions.
• Tests:
  • Add e2e tests for prepare (Linux) and basic Windows checks; adjust Windows vfox/task tests setup.

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

[Copilot]

Pull request overview

This PR introduces a new prepare system to mise that automatically ensures project dependencies are ready before running commands. When executing commands like mise x npm run dev, mise now checks if dependencies are stale by comparing modification times of lockfiles against output directories, running install commands only when needed.

Key changes:

• Adds mise prepare command with options for dry-run, force execution, and provider listing
• Integrates auto-prepare into mise x and mise run workflows with opt-out via --no-prepare flag
• Implements NPM provider with detection for npm/yarn/pnpm/bun through lockfile patterns

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/prepare/mod.rs	Defines core PrepareProvider trait and PrepareCommand structure
src/prepare/engine.rs	Implements PrepareEngine for discovering, checking, and executing prepare steps
src/prepare/rule.rs	Defines configuration structures for prepare rules and provider overrides
src/prepare/providers/npm.rs	Implements NPM prepare provider with package manager detection
src/prepare/providers/custom.rs	Implements custom prepare provider for user-defined rules with glob support
src/prepare/providers/mod.rs	Exports prepare provider implementations
src/cli/prepare.rs	Implements prepare CLI command with list, dry-run, and force options
src/cli/exec.rs	Integrates auto-prepare into exec command flow
src/cli/run.rs	Integrates auto-prepare into run command flow
src/cli/en.rs	Adds no_prepare field to en command
src/cli/mod.rs	Registers prepare command in CLI
src/config/config_file/mod.rs	Adds prepare_config method to ConfigFile trait
src/config/config_file/mise_toml.rs	Adds prepare configuration support to MiseToml
src/shims.rs	Disables prepare for shims to avoid performance impact
src/main.rs	Registers prepare module
settings.toml	Adds prepare.auto and prepare.auto_timeout settings

---

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

[Copilot]

The function returns a PathBuf for the lockfile but then later code can fall back to package.json which is misleading. When PackageManager::Npm is returned with package.json (lines 78-80), the returned PathBuf represents package.json not a lockfile, making the return type semantically inconsistent with the function's purpose of detecting a package manager from lockfiles.

[Copilot]

Shell command parsing with split_whitespace() doesn't handle quoted arguments correctly. For example, a command like npm run \"my script\" would be split into separate arguments incorrectly. Consider using a proper shell parser or documenting that complex commands aren't supported.

[Copilot]

Shell command parsing with split_whitespace() doesn't handle quoted arguments correctly. Commands with quoted strings like sh -c \"echo hello\" will be incorrectly split. Consider using a proper shell parser or documenting this limitation.

[Copilot]

The comment states 'Fresh if outputs newer than sources' but the comparison src < out returns true when source mtime is less than (older than) output mtime. While this is correct, the phrasing could be clearer: 'Fresh if sources older than outputs' would match the actual comparison direction.

Suggested change

	(Some(src), Some(out)) => Ok(src < out), // Fresh if outputs newer than sources
	(Some(src), Some(out)) => Ok(src < out), // Fresh if sources older than outputs

[Copilot]

The prepare.auto_timeout setting is defined but never used in the PrepareEngine implementation. The timeout is not enforced when running prepare commands in engine.rs, making this configuration non-functional.

Suggested change

	[prepare.auto_timeout]
	default = "5m"
	description = "Timeout for auto-prepare operations."
	env = "MISE_PREPARE_AUTO_TIMEOUT"
	type = "Duration"

[cursor]

Bug: Prepare freshness check loops on equal mtimes

check_freshness treats outputs as fresh only when sources_mtime < outputs_mtime. On filesystems with coarse timestamp resolution, install steps can leave equal mtimes, causing prepare to re-run repeatedly even when nothing changed.

 

[cursor]

Bug: Project prepare.auto config is ignored

Auto-prepare gating checks Settings::get().prepare.auto, but the per-project [prepare] auto = false value parsed into PrepareConfig.auto is never consulted. This makes the documented project-level auto toggle ineffective for mise x/mise run.

Additional Locations (1)

• src/cli/run.rs#L218-L229

 

[cursor]

Bug: Merging prepare configs unintentionally flips auto

PrepareConfig::merge always assigns auto: other.auto. Because auto defaults to true, any config file that defines prepare rules/providers but omits auto will override an earlier auto = false from another config, re-enabling auto-prepare unintentionally.

 

[cursor]

Bug: Run help triggers installs and prepare

mise run -h/--help now builds a Toolset, installs missing versions, and may run PrepareEngine before checking the help flags. This introduces unexpected side effects and latency for help output, and can install dependencies/tools when the user only requested help.

src/cli/run.rs#L200-L239

mise/src/cli/run.rs

Lines 200 to 239 in 135af4b

	impl Run {
	pub async fn run(mut self) -> Result<()> {
	let mut config = Config::get().await?;
	// Build and install toolset so tools like npm are available for prepare
	let mut ts = ToolsetBuilder::new()
	.with_args(&self.tool)
	.with_default_to_latest(true)
	.build(&config)
	.await?;
	let opts = InstallOptions {
	jobs: self.jobs,
	raw: self.raw,
	..Default::default()
	};
	ts.install_missing_versions(&mut config, &opts).await?;
	// Run prepare with toolset environment (includes tools PATH)
	if !self.no_prepare && Settings::get().prepare.auto {
	let env = ts.env_with_path(&config).await?;
	let engine = PrepareEngine::new(config.clone())?;
	engine
	.run(PrepareOptions {
	env,
	..Default::default()
	})
	.await?;
	}
	if self.task == "-h" {
	self.get_clap_command().print_help()?;
	return Ok(());
	}
	if self.task == "--help" {
	self.get_clap_command().print_long_help()?;
	return Ok(());
	}

 

---

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.12.7 x -- echo	20.2 ± 0.2	19.7	22.3	1.03 ± 0.02
mise x -- echo	19.7 ± 0.3	19.0	20.8	1.00

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.12.7 env	19.7 ± 0.3	19.3	21.2	1.03 ± 0.03
mise env	19.2 ± 0.5	18.5	23.4	1.00

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.12.7 hook-env	19.7 ± 0.6	19.2	27.9	1.03 ± 0.03
mise hook-env	19.2 ± 0.3	18.7	21.3	1.00

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.12.7 ls	16.5 ± 0.2	16.1	17.9	1.00
mise ls	16.7 ± 0.2	16.2	18.2	1.02 ± 0.02

xtasks/test/perf

Command	mise-2025.12.7	mise	Variance
install (cached)	108ms	107ms	+0%
ls (cached)	65ms	65ms	+0%
bin-paths (cached)	70ms	71ms	-1%
task-ls (cached)	433ms	✅ 275ms	+57%

✅ Performance improvement: task-ls cached is 57%

[jdx]

bugbot run

[cursor]

Bug: Command parsing uses naive split instead of shell parsing

The PrepareCommand::from_string function uses split_whitespace() to parse commands, which doesn't handle quoted arguments or shell escaping. Commands like npm run "my script" or sh -c 'complex command' would be incorrectly split into ["npm", "run", "\"my", "script\""] instead of ["npm", "run", "my script"]. The rest of the codebase uses shell_words::split() for proper shell-aware parsing (e.g., in en.rs, settings.rs). Custom prepare rules and provider overrides with quoted arguments will fail silently with incorrect argument splitting.

 

[cursor]

Bug: Poetry provider assumes non-default venv location

The poetry provider checks .venv as the output directory, but Poetry's default behavior creates virtual environments in {cache-dir}/virtualenvs/, not in the project's .venv. Only when virtualenvs.in-project = true is explicitly configured does Poetry use .venv. With the default configuration, .venv won't exist, causing freshness checks to always return stale and poetry install to run on every mise run or mise x invocation when auto = true.