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
23 changes: 22 additions & 1 deletion .agent-os/instructions/mise-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## Project Overview

**Mise** is a powerful Rust CLI tool for development environment management that serves as "the front-end to your dev env." It manages:

- **Development tools** (node, python, go, java, etc.) like asdf/nvm/pyenv but for any language
- **Environment variables** for different project directories like direnv
- **Tasks** for building and testing projects like make
Expand Down Expand Up @@ -30,24 +31,28 @@ mise/
### Key Systems

#### 1. Backend Architecture

- **Unified Backend Interface**: All tools implement the `Backend` trait
- **Multiple Sources**: Tools can come from ASDF plugins, vfox plugins, cargo, npm, GitHub releases, aqua registry, etc.
- **Core Plugins**: Built-in implementations for major languages (Node, Python, Go, Ruby, Java, etc.)
- **External Plugins**: Support for ASDF and vfox plugin ecosystems

#### 2. Configuration System

- **Hierarchical Loading**: system → global → local with environment-specific overrides
- **Multiple Formats**: `mise.toml` (primary), `.tool-versions` (ASDF compat), idiomatic files
- **Environment Variables**: Template system with Tera for dynamic values
- **Tool Management**: Version specifications with semver, latest, system, etc.

#### 3. Toolset Management

- **ToolVersion**: Represents an installed/installable tool version
- **Toolset**: Collection of tool versions with installation state tracking
- **Installation Context**: Manages parallel installations with progress reporting
- **Runtime Symlinks**: Creates symlinks for tool binaries in PATH

#### 4. Task System

- **Dependency Graph**: Tasks can depend on other tasks using petgraph
- **Multiple Sources**: Tasks from `mise.toml`, `tasks.toml`, or external files
- **Environment Handling**: Task-specific environment variables and PATH modifications
Expand All @@ -56,24 +61,29 @@ mise/
## Development Standards

### Code Organization

- **Modular Architecture**: Clear separation between CLI, backend, config, and core systems
- **Async/Await**: Heavy use of tokio for concurrent operations
- **Error Handling**: Comprehensive error handling with eyre and custom error types
- **Testing Strategy**: Unit tests in source + comprehensive e2e tests

### Backend Implementation Pattern

When implementing new backends, follow this pattern:

1. Create struct implementing `Backend` trait in `src/backend/`
2. Implement required methods: `id()`, `get_type()`, `list_remote_versions()`, `install_version()`, etc.
3. Add to backend registry in `src/backend/mod.rs`
4. Add comprehensive tests

### Plugin Development

- **Core plugins** go in `src/plugins/core/` for built-in tools
- **External plugins** use ASDF or vfox compatibility layers
- **Plugin metadata** defined in `mise.plugin.toml` files

### Configuration Parsing

- Uses `confique` crate for configuration management
- Settings defined in `settings.toml` (generates code/docs)
- Tool registry mappings in `registry.toml`
Expand All @@ -82,6 +92,7 @@ When implementing new backends, follow this pattern:
## Key Files and Directories

### Essential Source Files

- `src/main.rs` - Entry point with panic handlers and async runtime
- `src/cli/mod.rs` - Main CLI router and command definitions
- `src/backend/mod.rs` - Backend system and tool loading logic
Expand All @@ -90,12 +101,14 @@ When implementing new backends, follow this pattern:
- `src/task/mod.rs` - Task execution system

### Configuration Files

- `mise.toml` - Main project configuration file
- `settings.toml` - Global settings definitions (source of truth)
- `registry.toml` - Tool registry mappings (2000+ tools)
- `tasks.toml` - Project task definitions

### Build System

- `Cargo.toml` - Main package with workspace for vfox crate
- `build.rs` - Custom build script for generating metadata
- Cross-compilation support via `Cross.toml`
Expand All @@ -104,6 +117,7 @@ When implementing new backends, follow this pattern:
## Development Workflow

### Build Commands

```bash
mise run build # Build with cargo
mise run test # Run all tests (unit + e2e)
Expand All @@ -113,12 +127,14 @@ mise run ci # Run format, build, and test
```

### Documentation Generation

```bash
mise run render # Generate all docs and completions
mise run docs # Start dev server
```

### Testing Strategy

- **Unit Tests**: Within source files using standard Rust testing
- **E2E Tests**: In `e2e/` directory with real tool installations
- **Snapshot Tests**: Using `insta` crate for CLI output verification
Expand All @@ -127,22 +143,26 @@ mise run docs # Start dev server
## Commit and PR Guidelines

### Conventional Commits (REQUIRED)

Format: `<type>(<scope>): <description>`

**Types:** feat, fix, refactor, docs, style, perf, test, chore, registry
**Scopes:** aqua, cli, config, backend, tool, env, task, api, ui, core, deps, schema, doctor, shim, security

**Examples:**

- `feat(cli): add new command for tool management`
- `fix(config): resolve parsing issue with nested tables`
- `registry: add trunk metalinter (#5875)`

### Pre-commit Requirements

1. Run `mise run lint-fix` and commit any fixes
2. Use `mise run test:e2e [test_filename]...` for specific tests
3. Never run e2e tests directly - always use mise task

## Technology Stack

- **Language**: Rust 2024 edition (min version 1.85)
- **Runtime**: Tokio async runtime with multi-threading
- **CLI Framework**: clap with derive features
Expand All @@ -153,8 +173,9 @@ Format: `<type>(<scope>): <description>`
- **Testing**: insta for snapshots, ctor for test setup

## Architecture Principles

1. **Performance**: Parallel operations where possible, efficient caching
2. **Reliability**: Comprehensive error handling and recovery
3. **Extensibility**: Plugin system supporting multiple backends
4. **Compatibility**: ASDF compatibility while adding modern features
5. **User Experience**: Rich progress reporting and helpful error messages
5. **User Experience**: Rich progress reporting and helpful error messages
38 changes: 35 additions & 3 deletions .agent-os/instructions/mise-product-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Mise (pronounced "mise-en-place") is a comprehensive development environment management tool that combines three essential functions:

1. **Tool Version Manager** - Like asdf, nvm, or pyenv but for any language
2. **Environment Variable Manager** - Like direnv for project-specific environments
2. **Environment Variable Manager** - Like direnv for project-specific environments
3. **Task Runner** - Like make for building and testing projects

**Tagline**: "The front-end to your dev env"
Expand All @@ -15,19 +15,22 @@ Mise (pronounced "mise-en-place") is a comprehensive development environment man
### 1. Development Tool Management

**Supported Tools**: 2000+ tools including:

- **Languages**: Node.js, Python, Go, Java, Ruby, Rust, Swift, Zig, Elixir, Erlang, Deno, Bun
- **CLI Tools**: terraform, kubectl, docker, git, jq, ripgrep, shellcheck
- **Build Tools**: cmake, ninja, gradle, maven
- **Cloud Tools**: aws-cli, gcloud, azure-cli

**Key Capabilities**:

- Install multiple versions of any tool simultaneously
- Automatic version switching per project directory
- Real binaries (no shims) with fast performance
- Global and project-specific tool versions
- Idiomatic version files (`.node-version`, `.python-version`, etc.)

**Example Usage**:

```bash
# Install and use specific versions
mise use node@20 python@3.12 go@latest
Expand All @@ -42,13 +45,15 @@ mise install
### 2. Environment Variable Management

**Features**:

- Project-specific environment variables
- Template system with Tera for dynamic values
- `.env` file loading support
- Environment inheritance and overrides
- Shell integration for automatic activation

**Configuration Example**:

```toml
# mise.toml
[env]
Expand All @@ -61,13 +66,15 @@ PATH = ["./node_modules/.bin", "$PATH"]
### 3. Task Management System

**Features**:

- Task dependencies with directed acyclic graph
- Multiple execution environments
- File watching for automatic task execution
- Parallel task execution
- Task inheritance and overrides

**Configuration Example**:

```toml
# mise.toml
[tasks.build]
Expand All @@ -94,7 +101,9 @@ kubectl apply -f k8s/
## Backend Ecosystem

### Core Plugins (Built-in)

Fast, native implementations for major languages:

- Node.js with npm/yarn/pnpm support
- Python with pyenv compatibility
- Go with version management
Expand All @@ -103,13 +112,15 @@ Fast, native implementations for major languages:
- Rust via rustup integration

### External Plugin Support

- **ASDF Plugins**: 500+ community plugins
- **Vfox Plugins**: Modern Lua-based plugin system
- **Aqua Registry**: 1000+ tools with security verification
- **GitHub Releases**: Direct installation from GitHub
- **Package Managers**: npm, cargo, gem, pipx, go install

### Backend Prioritization

1. Core plugins (fastest, native Rust)
2. Aqua registry (secure, verified)
3. GitHub releases (direct, simple)
Expand All @@ -119,17 +130,20 @@ Fast, native implementations for major languages:
## Configuration System

### File Hierarchy (in order of precedence)

1. `mise.toml` - Project configuration
2. `.mise.toml` - Hidden project configuration
3. `~/.config/mise/config.toml` - Global configuration
4. `/etc/mise/config.toml` - System configuration

### Configuration Formats

- **mise.toml**: Modern TOML format (recommended)
- **.tool-versions**: ASDF compatibility
- **Idiomatic files**: `.node-version`, `.python-version`, etc.

### Environment-Specific Configuration

```toml
[env]
NODE_ENV = "development"
Expand All @@ -148,46 +162,54 @@ node = "18" # Use LTS in production
## Shell Integration

### Activation Hook

Add to shell configuration:

```bash
# ~/.bashrc, ~/.zshrc
eval "$(mise activate)"
```

### Shims (Optional)

For compatibility with tools expecting shims:

```bash
mise reshim
```

## Advanced Features

### 1. Lockfile Support

- `mise.lock` - Lock exact tool versions
- Reproducible builds across environments
- CI/CD integration

### 2. Task Dependencies

```toml
[tasks.ci]
depends = ["format", "lint", "test", "build"]

[tasks.format]
run = "cargo fmt"

[tasks.lint]
[tasks.lint]
depends = ["format"]
run = "cargo clippy"
```

### 3. Watch Mode

```bash
# Watch files and run tasks automatically
mise watch -t test
mise watch -t build src/**/*.rs
```

### 4. Environment Templates

```toml
[env]
PROJECT_ROOT = "{{config_root}}"
Expand All @@ -198,21 +220,25 @@ BUILD_DATE = "{{date(format='%Y-%m-%d')}}"
## Use Cases

### 1. Individual Developer

- Manage tool versions across multiple projects
- Consistent development environment
- Simplified tool installation and updates

### 2. Team Development

- Shared tool versions via version control
- Consistent CI/CD environments
- Standardized development workflows

### 3. Multi-Project Environments

- Different tool versions per project
- Automatic environment switching
- Reduced context switching overhead

### 4. CI/CD Integration

```yaml
# GitHub Actions
- name: Setup mise
Expand All @@ -226,25 +252,29 @@ BUILD_DATE = "{{date(format='%Y-%m-%d')}}"
## Performance Characteristics

### Speed Optimizations

- Parallel tool installations
- Efficient PATH manipulation (no shims by default)
- Cached version lookups
- Lazy loading of plugins

### Resource Usage

- Minimal runtime overhead
- Efficient disk usage with shared tool installations
- Memory-efficient tool detection

## Security Features

### Tool Verification

- Checksum verification for downloads
- GPG signature checking where supported
- Aqua registry with security scanning
- minisign verification for mise releases

### Trust System

```bash
# Trust configuration files
mise trust
Expand All @@ -256,13 +286,15 @@ mise trust ~/projects/myapp
## Migration and Compatibility

### From ASDF

- Direct `.tool-versions` file support
- Plugin compatibility layer
- Migration helper: `mise migrate`

### From Other Tools

- Import from `.node-version`, `.python-version`
- Environment variable compatibility
- Existing workflow integration

This comprehensive feature set makes mise a powerful all-in-one solution for development environment management, combining the best aspects of multiple specialized tools into a cohesive, fast, and reliable system.
This comprehensive feature set makes mise a powerful all-in-one solution for development environment management, combining the best aspects of multiple specialized tools into a cohesive, fast, and reliable system.
Loading
Loading