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
67 changes: 44 additions & 23 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,15 +93,15 @@ gh api repos/dtvem/dtvem/issues/<number>/dependencies/blocked_by/<blocker_id> -X
| Attribute | Value |
|-----------|-------|
| Version | dev (pre-1.0) |
| Runtimes | Python, Node.js |
| Tests | 230+ passing |
| Runtimes | Python, Node.js, Ruby |
| Tests | 160+ passing |
| Style | Google Go Style Guide |

**Key Concept**: Shims are Go executables that intercept runtime commands (like `python`, `node`), resolve versions, and execute the appropriate binary.

### Available Commands

`init`, `install`, `uninstall`, `list`, `list-all`, `global`, `local`, `current`, `freeze`, `migrate`, `reshim`, `which`, `where`, `version`, `help`
`init`, `install`, `uninstall`, `list`, `list-all`, `global`, `local`, `current`, `freeze`, `migrate`, `reshim`, `which`, `where`, `update`, `request`, `version`, `help`

---

Expand Down Expand Up @@ -152,10 +152,12 @@ Maps to runtime provider → Resolves version
| `internal/ui/` | Colored output, prompts, verbose/debug logging |
| `internal/tui/` | Table formatting and styles |
| `internal/download/` | File downloads with progress |
| `internal/manifest/` | Version manifest fetching and caching |
| `internal/migration/` | Migration detection and helpers |
| `internal/testutil/` | Shared test utility functions |
| `internal/constants/` | Platform constants |
| `src/cmd/` | CLI commands (one file per command) |
| `src/runtimes/` | Runtime providers (node/, python/) |
| `src/runtimes/` | Runtime providers (node/, python/, ruby/) |

---

Expand All @@ -173,6 +175,7 @@ func init() {
import (
_ "github.com/dtvem/dtvem/src/runtimes/node"
_ "github.com/dtvem/dtvem/src/runtimes/python"
_ "github.com/dtvem/dtvem/src/runtimes/ruby"
)
```

Expand Down Expand Up @@ -273,7 +276,7 @@ cd src && go test -cover ./... # With coverage

### Provider Test Harness

`internal/runtime/provider_test_harness.go` validates all Provider implementations consistently. Used by node and python providers.
`internal/runtime/provider_test_harness.go` validates all Provider implementations consistently. Used by node, python, and ruby providers.

### Import Cycle Avoidance

Expand All @@ -285,22 +288,40 @@ cd src && go test -cover ./... # With coverage

## CI/CD

### Build Workflow (`.github/workflows/build.yml`)

1. **golangci-lint** - Linting (errcheck, govet, unused, misspell, etc.)
2. **go-mod** - Verify go.mod/go.sum are tidy
3. **build** - Matrix build/test on Windows, macOS, Linux

PRs get automatic coverage reports posted as comments.

### Release Workflow (`.github/workflows/release.yml`)

Triggered manually via workflow dispatch:

1. **validate** - Check build passed, version format valid
2. **build** - Matrix build for 5 platforms
3. **release** - Create tag, GitHub Release with artifacts
4. **notify** - Post to GitHub Discussions and BlueSky
### Workflows in This Repo (`.github/workflows/`)

| Workflow | Trigger | Purpose |
|----------|---------|---------|
| `build.yml` | PR, push to main | Lint, build, test on Windows/macOS/Linux. Posts coverage reports on PRs |
| `release.yml` | Manual dispatch | Full release: validate, build 5 platforms, create GitHub Release, notify |
| `commit-lint.yml` | PR | Validate PR titles follow conventional commits |
| `script-lint.yml` | PR (install scripts) | Lint install.sh and install.ps1 with shellcheck/PSScriptAnalyzer |
| `contributors.yml` | Push to main | Auto-update contributors section in README |
| `preview-changelog.yml` | PR | Preview release notes for PRs |
| `integration-test.yml` | Manual dispatch | Full integration test suite (runtimes + migrations) |
| `integration-test-runtimes.yml` | Manual dispatch | Runtime install/uninstall tests only |
| `integration-test-migrations.yml` | Manual dispatch | Migration tests only (all platforms/managers) |
| `generate-manifests-from-r2.yml` | Manual/scheduled | Generate version manifests from R2 mirror |
| `deploy-manifests.yml` | Push to main (manifests/) | Deploy manifest files to R2 |
| `mirror-all.yml` | Manual dispatch | Mirror all runtime binaries to R2 |
| `mirror-sync.yml` | Scheduled | Sync new versions to R2 mirror |

### Reusable Workflows (from `dtvem/.github` repo)

Integration tests and changelog generation use reusable workflows stored in the separate `dtvem/.github` repository:

**Runtime Tests:**
- `integration-test-node.yml` - Node.js install/global/local/uninstall
- `integration-test-python.yml` - Python install/global/local/uninstall
- `integration-test-ruby.yml` - Ruby install/global/local/uninstall

**Migration Tests** (per runtime × platform × version manager):
- `integration-test-migrate-{runtime}-{platform}-{manager}.yml`
- Platforms: ubuntu, macos, windows
- Managers: system, nvm, fnm, pyenv, rbenv, uru

**Utilities:**
- `generate-changelog.yml` - Generate release notes from commits

Version injected at build time; main branch always shows `Version = "dev"`.

Expand All @@ -312,12 +333,12 @@ Version injected at build time; main branch always shows `Version = "dev"`.

**Unix:**
```bash
curl -fsSL https://github.com/dtvem/dtvem/releases/latest/download/install.sh | bash
curl -fsSL dtvem.io/install.sh | bash
```

**Windows:**
```powershell
irm https://github.com/dtvem/dtvem/releases/latest/download/install.ps1 | iex
irm dtvem.io/install.ps1 | iex
```

Features: Auto platform detection, PATH configuration, runs `dtvem init`.
Expand Down
2 changes: 1 addition & 1 deletion .commitlintrc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -77,4 +77,4 @@ rules:
- 100

# Help URL shown in error messages
helpUrl: 'https://github.com/dtvem/dtvem/blob/main/docs/COMMIT_CONVENTION.md'
helpUrl: 'https://www.conventionalcommits.org/'
7 changes: 4 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
4. **Use a conventional commit format for your PR title** (e.g., `feat(node): add version caching`)
5. Submit your pull request!

**Note:** We use squash merges, so your PR title becomes the commit message on main. Make sure it follows the [commit convention](docs/COMMIT_CONVENTION.md).
**Note:** We use squash merges, so your PR title becomes the commit message on main. Make sure it follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.

## Development Setup

Expand Down Expand Up @@ -172,8 +172,9 @@ src/
│ ├── runtime/ # Core plugin system
│ └── shim/ # Shim management
└── runtimes/ # Runtime provider implementations
├── node/
├── python/
└── node/
└── ruby/
```

### Commit Messages
Expand All @@ -196,7 +197,7 @@ test(migrate): add tests for package preservation

**Common scopes:** `node`, `python`, `cli`, `install`, `migrate`, `shim`, `config`, `path`, `ui`, `test`, `docs`

For detailed guidelines and examples, see [Commit Convention Guide](docs/COMMIT_CONVENTION.md).
For detailed guidelines, see the [Conventional Commits specification](https://www.conventionalcommits.org/).

**Note:** PR titles are automatically validated for conventional commit compliance. Non-conforming titles will fail CI checks. Since we use squash merges, your PR title becomes the final commit message.

Expand Down
32 changes: 15 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
[![Build & Test](https://img.shields.io/github/actions/workflow/status/dtvem/dtvem/build.yml?style=for-the-badge&label=Build%20%26%20Test)](https://github.com/dtvem/dtvem/actions)
[![Release](https://img.shields.io/github/actions/workflow/status/dtvem/dtvem/release.yml?style=for-the-badge&label=Release)](https://github.com/dtvem/dtvem/actions)

**[Documentation](https://github.com/dtvem/dtvem/wiki)** · **[Installation](https://github.com/dtvem/dtvem/wiki/Installation)** · **[Quick Start](https://github.com/dtvem/dtvem/wiki/Quick-Start)** · **[Commands](https://github.com/dtvem/dtvem/wiki/Commands)**
**[Documentation](https://dtvem.io/docs)** · **[Installation](https://dtvem.io/docs/user-guide/getting-started)** · **[Quick Start](https://dtvem.io/docs/user-guide/getting-started)** · **[Commands](https://dtvem.io/docs/user-guide/commands/overview)**

</div>

Expand All @@ -25,7 +25,7 @@ Managing multiple versions of Python, Node.js, Ruby, and other runtimes across d

✅ **Cross-Platform**: Windows, Linux, and macOS with identical behavior

✅ **Multiple Runtimes**: Python, Node.js (Ruby, Go, and more coming)
✅ **Multiple Runtimes**: Python, Node.js, Ruby (Go, Rust, Java coming soon)

✅ **Shim-Based**: Automatic version switching without shell integration

Expand All @@ -35,21 +35,21 @@ Managing multiple versions of Python, Node.js, Ruby, and other runtimes across d

✅ **No Shell Hooks**: Works in cmd.exe, PowerShell, bash, zsh, fish, etc.

See [Competitive Analysis](https://github.com/dtvem/dtvem/wiki/Competitive-Analysis) for how dtvem compares to nvm, pyenv, asdf, and mise.
See [Compare](https://dtvem.io/compare) for how dtvem compares to nvm, pyenv, asdf, and mise.

## 📦 Installation

**macOS / Linux:**
```bash
curl -fsSL https://github.com/dtvem/dtvem/releases/latest/download/install.sh | bash
curl -fsSL dtvem.io/install.sh | bash
```

**Windows (PowerShell):**
```powershell
irm https://github.com/dtvem/dtvem/releases/latest/download/install.ps1 | iex
irm dtvem.io/install.ps1 | iex
```

See [Installation Guide](https://github.com/dtvem/dtvem/wiki/Installation) for manual installation, building from source, and PATH configuration.
See [Getting Started](https://dtvem.io/docs/user-guide/getting-started) for manual installation, building from source, and PATH configuration.

## 🚀 Quick Start

Expand All @@ -72,25 +72,23 @@ dtvem migrate node
dtvem migrate python
```

See [Quick Start Guide](https://github.com/dtvem/dtvem/wiki/Quick-Start) for more examples.
See [Getting Started](https://dtvem.io/docs/user-guide/getting-started) for more examples.

## 📚 Documentation

| Topic | Description |
|-------|-------------|
| [Installation](https://github.com/dtvem/dtvem/wiki/Installation) | Install on Windows, macOS, or Linux |
| [Quick Start](https://github.com/dtvem/dtvem/wiki/Quick-Start) | Get up and running in 5 minutes |
| [Commands](https://github.com/dtvem/dtvem/wiki/Commands) | Complete command reference |
| [Configuration](https://github.com/dtvem/dtvem/wiki/Configuration) | Config files and environment variables |
| [Architecture](https://github.com/dtvem/dtvem/wiki/Architecture) | How dtvem works (shims, version resolution) |
| [Migration](https://github.com/dtvem/dtvem/wiki/Migration) | Import from nvm, pyenv, fnm, etc. |
| [FAQ](https://github.com/dtvem/dtvem/wiki/FAQ) | Frequently asked questions |
| [Competitive Analysis](https://github.com/dtvem/dtvem/wiki/Competitive-Analysis) | vs nvm, pyenv, asdf, mise |
| [Roadmap](https://github.com/dtvem/dtvem/wiki/Roadmap) | Planned features and runtimes |
| [Getting Started](https://dtvem.io/docs/user-guide/getting-started) | Install and get up and running |
| [Commands](https://dtvem.io/docs/user-guide/commands/overview) | Complete command reference |
| [Configuration](https://dtvem.io/docs/user-guide/configuration) | Config files and environment variables |
| [Concepts](https://dtvem.io/docs/user-guide/concepts) | How dtvem works (shims, version resolution) |
| [Migration](https://dtvem.io/docs/user-guide/migration) | Import from nvm, pyenv, fnm, etc. |
| [Compare](https://dtvem.io/compare) | vs nvm, pyenv, asdf, mise |
| [Runtimes](https://dtvem.io/docs/user-guide/runtimes/overview) | Supported runtimes and roadmap |

## 🤝 Contributing

Contributions are welcome! See the [Development Guide](https://github.com/dtvem/dtvem/wiki/Development) for:
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for:

- Setting up your development environment
- npm scripts for building and testing
Expand Down