Skills
skills/loonghao/vx/vx-provider-creator

vx-provider-creator

SKILL.md

VX Provider Creator

This skill guides the creation of new runtime providers for the vx universal tool manager.

When to Use

  • Creating a new provider for a tool (e.g., "add support for ripgrep")
  • Implementing a new runtime in vx
  • Adding a new tool to the vx ecosystem
  • Adding project analyzer support for a language/ecosystem
  • Adding tools that require system package manager installation

Workflow Overview

  1. Check license compatibility (MUST DO FIRST)
  2. Create a feature branch from remote main
  3. Determine installation type (direct download vs system package manager)
  4. Generate provider directory structure (including provider.toml)
  5. Implement core files (lib.rs, provider.rs, runtime.rs, config.rs)
  6. Add system package manager fallback if needed
  7. Register the provider in workspace and CLI
  8. (Optional) Add project analyzer integration for language-specific tools
  9. Update snapshot tests
  10. Verify and test

⚠️ License Compliance (MANDATORY - Step 0)

Before creating ANY provider, you MUST check the upstream tool's license.

Blocked Licenses (DO NOT integrate)

These licenses have "copyleft infection" that would require vx itself to change license:

License Risk Example
AGPL-3.0 Entire project must be AGPL x-cmd
SSPL Server-side copyleft MongoDB
CC BY-NC No commercial use -
Proprietary (no redistribution) Cannot bundle/distribute -

Allowed Licenses (Safe to integrate)

License Type Notes
MIT Permissive ✅ No restrictions
Apache-2.0 Permissive ✅ Patent grant included
BSD-2/BSD-3 Permissive ✅ Minimal restrictions
ISC Permissive ✅ Similar to MIT
MPL-2.0 Weak copyleft ✅ File-level copyleft only
Unlicense/CC0 Public domain ✅ No restrictions

Caution Licenses (Allowed with notes)

License Type Notes
GPL-2.0/GPL-3.0 Strong copyleft ⚠️ OK for vx since we only download and execute the tool (not link to it). Add license_note in provider.toml
LGPL-2.1/LGPL-3.0 Weak copyleft ⚠️ Same as GPL - OK for download/execute. Document in provider.toml
BSL-1.1 Source-available ⚠️ HashiCorp tools (terraform, vault). OK for version management. Document restriction
Proprietary (free to use) Proprietary ⚠️ OK if tool is free to download/use (e.g., dotnet, msvc). Add note

How to Check

  1. Visit the tool's GitHub repository
  2. Check the LICENSE file or repository metadata
  3. Search for license in the repo's About section
  4. If no license found, treat as proprietary and document

provider.toml License Fields

Every provider.toml MUST include:

[provider]
name = "example"
license = "MIT"              # SPDX identifier of upstream tool's license
# license_note = "..."       # Optional: any special notes about license implications

If the license is in the "Blocked" category, DO NOT create the provider. Inform the user:

⚠️ Cannot integrate {tool}: it uses {license} which has copyleft infection that would require the entire vx project to adopt the same license. Consider using it via system package manager instead.

Installation Type Decision Tree

Before creating a provider, determine the installation method:

Does the tool provide portable binaries for all platforms?
├─ Yes → Standard Download Provider
│   └─ Examples: terraform, just, kubectl, helm, go, node
└─ No → Check platform availability
    ├─ Some platforms have binaries → Hybrid Provider (download + package manager)
    │   └─ Examples: imagemagick (Linux AppImage, macOS/Windows via brew/winget)
    │   └─ Examples: ffmpeg (Windows binary, macOS/Linux via brew/apt)
    └─ No portable binaries → System Package Manager Only
        └─ Examples: make, git (on non-Windows), curl, openssl

Provider Types Summary

Type Direct Download Package Manager Fallback Examples
Standard ✅ All platforms ❌ Not needed terraform, just, go, node
Hybrid ✅ Some platforms ✅ For others imagemagick, ffmpeg, docker
System-only ❌ None ✅ All platforms make, curl, openssl
Detection-only ❌ None ❌ System-installed msbuild, xcodebuild, systemctl

Step 1: Create Feature Branch

git fetch origin main
git checkout -b feature/{name}-provider origin/main

Replace {name} with the tool name (lowercase, e.g., ripgrep, fd).

Step 2: Create Provider Directory Structure

Create the following structure under crates/vx-providers/{name}/:

crates/vx-providers/{name}/
├── Cargo.toml
├── provider.toml       # Provider manifest (metadata, runtimes, constraints)
├── src/
│   ├── lib.rs          # Module exports + create_provider() factory
│   ├── provider.rs     # Provider trait implementation
│   ├── runtime.rs      # Runtime trait implementation
│   └── config.rs       # URL builder and platform configuration
└── tests/
    └── runtime_tests.rs  # Unit tests (using rstest)

Step 2.1: Create provider.toml Manifest

The provider.toml file is the declarative manifest for the provider. It defines:

  • Provider metadata (name, description, homepage, ecosystem)
  • Runtime definitions (executable, aliases, bundled tools)
  • Version source configuration
  • RFC 0019: Layout configuration (for binary/archive downloads)
  • Platform-specific settings
  • Dependency constraints

Ecosystems available: nodejs, python, rust, go, ruby, java, dotnet, devtools, container, cloud, ai, cpp, zig, system

Version sources:

  • github-releases - GitHub Release API (most common)
  • github-tags - GitHub Tags API
  • nodejs-org - Node.js official releases
  • python-build-standalone - Python standalone builds
  • go-dev - Go official downloads
  • zig-download - Zig official downloads

RFC 0019 Layout Types:

  • binary - Single file download (needs renaming/placement)
  • archive - Compressed archive (tar.gz, zip, tar.xz)
  • git_clone - Git repository clone (for tools like vcpkg that install via git clone)

Note on download_type values: Use snake_case (e.g., git_clone), NOT kebab-case (e.g., git-clone). The manifest parser uses #[serde(rename_all = "snake_case")].

See references/templates.md for complete provider.toml template. See references/rfc-0019-layout.md for RFC 0019 layout configuration guide.

Step 2.2: Create provider.star (Starlark Script)

provider.star is the preferred way to implement providers. It replaces the need for Rust code (runtime.rs, config.rs) for most providers. The Starlark script is pure computation — all real I/O (HTTP, filesystem, msiexec) is performed by the Rust runtime based on descriptor dicts returned by the script.

File Location

crates/vx-providers/{name}/
├── provider.toml   # Metadata only (name, description, ecosystem, license)
└── provider.star   # Logic: fetch_versions, download_url, install_layout, etc.

When to use provider.star vs provider.toml layout:

  • provider.star — for any custom logic: platform-specific URLs, MSI installs, system package manager fallback, complex version parsing
  • provider.toml layout fields — only for simple standard archive/binary downloads with no custom logic

Starlark Standard Library

Load helpers from @vx//stdlib::

Module Key Functions Use Case
github.star make_fetch_versions, make_download_url, make_github_provider, github_asset_url GitHub releases
http.star github_releases, releases_to_versions, parse_github_tag HTTP descriptors
platform.star is_windows, is_macos, is_linux, is_x64, is_arm64, platform_triple, platform_ext, exe_ext, arch_to_gnu, arch_to_go, os_to_go Platform detection
install.star msi_install, archive_install, binary_install, platform_install Install descriptors
semver.star semver_compare, semver_gt, semver_lt, semver_parse, semver_sort, semver_strip_v Version comparison

provider.star Structure

A complete provider.star has these top-level symbols:

# ── Metadata (required) ──────────────────────────────────────────────────
def name():        return "mytool"
def description(): return "My awesome tool"
def homepage():    return "https://example.com"
def repository():  return "https://github.com/owner/repo"
def license():     return "MIT"          # SPDX identifier
def ecosystem():   return "devtools"     # nodejs/python/rust/go/devtools/system/...
def aliases():     return ["mt"]         # optional

# ── Platform constraint (optional, provider-level) ────────────────────────
platforms = {"os": ["windows"]}         # omit if cross-platform

# ── Runtime definitions (required) ───────────────────────────────────────
runtimes = [
    {
        "name":        "mytool",
        "executable":  "mytool",
        "description": "My tool CLI",
        "aliases":     ["mt"],
        "priority":    100,
        # optional: "platform_constraint": {"os": ["windows"]},
        # optional: "bundled_with": "other-runtime",
        # optional: "system_paths": ["C:/Program Files/MyTool"],
        # optional: "system_install": [{"manager": "brew", "package": "mytool", "priority": 90, "platforms": ["macos"]}],
    },
]

# ── Permissions (sandbox declaration) ────────────────────────────────────
permissions = {
    "http": ["api.github.com", "github.com"],
    "fs":   [],
    "exec": [],
}

# ── fetch_versions (required) ─────────────────────────────────────────────
# Option A: inherit from github.star (zero code)
fetch_versions = make_fetch_versions("owner", "repo")

# Option B: custom logic
def fetch_versions(ctx):
    releases = ctx["http"]["get_json"]("https://api.github.com/repos/owner/repo/releases?per_page=30")
    versions = []
    for release in releases:
        if release.get("draft") or release.get("prerelease"):
            continue
        tag = release.get("tag_name", "")
        v = tag.lstrip("v")
        if v:
            versions.append({"version": v, "lts": True, "prerelease": False})
    return versions

# ── download_url (required) ───────────────────────────────────────────────
# Option A: inherit from github.star
download_url = make_download_url("owner", "repo", "mytool-{vversion}-{triple}.{ext}")

# Option B: custom logic
def download_url(ctx, version):
    os   = ctx["platform"]["os"]
    arch = ctx["platform"]["arch"]
    # ... build URL ...
    return url_string  # or None if unsupported

# ── install_layout (required for non-trivial installs) ────────────────────
def install_layout(ctx, version):
    # Returns a descriptor dict; Rust runtime performs actual extraction
    return {
        "type":             "archive",   # or "binary", "msi"
        "strip_prefix":     "mytool-{}".format(version),
        "executable_paths": ["bin/mytool.exe", "bin/mytool"],
    }

# ── environment (optional) ────────────────────────────────────────────────
def environment(ctx, version, install_dir):
    return {"PATH": install_dir}  # prepend install_dir to PATH

# ── system_install (optional, for package manager fallback) ───────────────
def system_install(ctx):
    os = ctx["platform"]["os"]
    if os == "windows":
        return {"strategies": [{"manager": "winget", "package": "Publisher.MyTool", "priority": 95}]}
    elif os == "macos":
        return {"strategies": [{"manager": "brew", "package": "mytool", "priority": 90}]}
    return {}

# ── constraints (optional) ────────────────────────────────────────────────
constraints = [
    {
        "when": "*",
        "recommends": [{"runtime": "git", "version": ">=2.0", "reason": "Used as backend"}],
    },
]

# ── deps (optional) ───────────────────────────────────────────────────────
def deps(ctx, version):
    return []  # list of {"runtime": "node", "version": ">=18"}

Inheritance Levels

Choose the level that fits your provider:

Level 0 — Fully inherited (2 lines)

load("@vx//stdlib:github.star", "make_github_provider")
_p = make_github_provider("owner", "repo", "mytool-{vversion}-{triple}.{ext}")
fetch_versions = _p["fetch_versions"]
download_url   = _p["download_url"]

Level 1 — Inherit fetch_versions, custom download_url

load("@vx//stdlib:github.star", "make_fetch_versions", "github_asset_url")
load("@vx//stdlib:platform.star", "is_windows")

fetch_versions = make_fetch_versions("owner", "repo")

def download_url(ctx, version):
    os = ctx["platform"]["os"]
    ext = "zip" if os == "windows" else "tar.gz"
    asset = "mytool-v{}-{}.{}".format(version, os, ext)
    return github_asset_url("owner", "repo", "v" + version, asset)

Level 2 — Fully custom (non-GitHub source)

def fetch_versions(ctx):
    data = ctx["http"]["get_json"]("https://example.com/api/versions")
    return [{"version": v["name"], "lts": True, "prerelease": False} for v in data]

def download_url(ctx, version):
    os = ctx["platform"]["os"]
    return "https://example.com/download/{}/{}".format(version, os)

MSI Install (Windows)

For tools that distribute .msi installers on Windows, use msi_install() from install.star:

load("@vx//stdlib:install.star", "msi_install", "archive_install")
load("@vx//stdlib:platform.star", "is_windows")

def download_url(ctx, version):
    os = ctx["platform"]["os"]
    if os == "windows":
        return "https://example.com/tool-{}.msi".format(version)
    elif os == "macos":
        return "https://example.com/tool-{}-macos.tar.gz".format(version)
    elif os == "linux":
        return "https://example.com/tool-{}-linux.tar.gz".format(version)
    return None

def install_layout(ctx, version):
    os = ctx["platform"]["os"]
    if os == "windows":
        url = download_url(ctx, version)
        # msi_install uses msiexec /a (administrative install, no registry changes)
        return msi_install(
            url,
            executable_paths = ["bin/tool.exe", "tool.exe"],
            strip_prefix = "PFiles/Tool",  # optional: strip msiexec extraction prefix
        )
    else:
        url = download_url(ctx, version)
        return archive_install(
            url,
            strip_prefix = "tool-{}".format(version),
            executable_paths = ["bin/tool"],
        )

How MSI install works: msi_install() returns a descriptor dict. The Rust runtime runs: msiexec /a <file.msi> /qn /norestart TARGETDIR=<install_dir> This extracts the MSI contents without modifying the Windows registry.

platform_install() Convenience Helper

For tools with different URLs per platform (including MSI on Windows):

load("@vx//stdlib:install.star", "platform_install")

def install_layout(ctx, version):
    return platform_install(
        ctx,
        windows_url = "https://example.com/tool-{}.msi".format(version),
        macos_url   = "https://example.com/tool-{}-macos.tar.gz".format(version),
        linux_url   = "https://example.com/tool-{}-linux.tar.gz".format(version),
        windows_msi = True,                          # use msi_install on Windows
        executable_paths = ["bin/tool.exe", "bin/tool"],
        strip_prefix = "tool-{}".format(version),
    )

System Package Manager Fallback

For tools without portable binaries on some platforms:

def download_url(ctx, version):
    os = ctx["platform"]["os"]
    if os == "linux":
        return "https://github.com/owner/repo/releases/download/v{}/tool-linux.tar.gz".format(version)
    # Windows/macOS: no portable binary → return None → triggers system_install
    return None

def system_install(ctx):
    os = ctx["platform"]["os"]
    if os == "windows":
        return {
            "strategies": [
                {"manager": "winget", "package": "Publisher.Tool", "priority": 95},
                {"manager": "choco",  "package": "tool",           "priority": 80},
                {"manager": "scoop",  "package": "tool",           "priority": 60},
            ],
        }
    elif os == "macos":
        return {
            "strategies": [
                {"manager": "brew", "package": "tool", "priority": 90},
            ],
        }
    elif os == "linux":
        return {
            "strategies": [
                {"manager": "apt", "package": "tool", "priority": 80},
                {"manager": "dnf", "package": "tool", "priority": 80},
            ],
        }
    return {}

ctx Object Reference

The ctx dict injected by the vx runtime:

ctx = {
    "platform": {
        "os":     "windows" | "macos" | "linux",
        "arch":   "x64" | "arm64" | "x86",
        "target": "x86_64-pc-windows-msvc" | ...,  # Rust target triple
    },
    "http": {
        "get_json": lambda url: ...,   # returns parsed JSON (list or dict)
    },
    "paths": {
        "install_dir": "/path/to/install",
        "cache_dir":   "/path/to/cache",
    },
}

install_layout Return Values

Type Fields Description
"archive" strip_prefix, executable_paths ZIP/TAR.GZ/TAR.XZ archive
"binary" executable_name, source_name (opt), permissions (opt) Single file download
"msi" url, executable_paths (opt), strip_prefix (opt), extra_args (opt) Windows MSI installer

Complete Example: Standard GitHub Provider

# provider.star - ripgrep provider
load("@vx//stdlib:github.star",   "make_fetch_versions", "github_asset_url")
load("@vx//stdlib:platform.star", "is_windows")

def name():        return "ripgrep"
def description(): return "ripgrep - recursively searches directories for a regex pattern"
def homepage():    return "https://github.com/BurntSushi/ripgrep"
def repository():  return "https://github.com/BurntSushi/ripgrep"
def license():     return "MIT"
def ecosystem():   return "devtools"
def aliases():     return ["rg"]

runtimes = [
    {
        "name":        "rg",
        "executable":  "rg",
        "description": "ripgrep - fast regex search",
        "aliases":     ["ripgrep"],
        "priority":    100,
    },
]

permissions = {
    "http": ["api.github.com", "github.com"],
    "fs":   [],
    "exec": [],
}

fetch_versions = make_fetch_versions("BurntSushi", "ripgrep")

def _rg_triple(ctx):
    os   = ctx["platform"]["os"]
    arch = ctx["platform"]["arch"]
    triples = {
        "windows/x64":  "x86_64-pc-windows-msvc",
        "macos/x64":    "x86_64-apple-darwin",
        "macos/arm64":  "aarch64-apple-darwin",
        "linux/x64":    "x86_64-unknown-linux-musl",
        "linux/arm64":  "aarch64-unknown-linux-musl",
    }
    return triples.get("{}/{}".format(os, arch))

def download_url(ctx, version):
    triple = _rg_triple(ctx)
    if not triple:
        return None
    os  = ctx["platform"]["os"]
    ext = "zip" if os == "windows" else "tar.gz"
    asset = "ripgrep-{}-{}.{}".format(version, triple, ext)
    return github_asset_url("BurntSushi", "ripgrep", "v" + version, asset)

def install_layout(ctx, version):
    os  = ctx["platform"]["os"]
    exe = "rg.exe" if os == "windows" else "rg"
    triple = _rg_triple(ctx)
    return {
        "type":             "archive",
        "strip_prefix":     "ripgrep-{}-{}".format(version, triple) if triple else "",
        "executable_paths": [exe, "rg"],
    }

def environment(ctx, version, install_dir):
    return {"PATH": install_dir}

def deps(ctx, version):
    return []

Complete Example: MSI on Windows + Archive on Other Platforms

# provider.star - tool with MSI on Windows
load("@vx//stdlib:install.star",  "msi_install", "archive_install")
load("@vx//stdlib:github.star",   "make_fetch_versions", "github_asset_url")
load("@vx//stdlib:platform.star", "is_windows")

def name():        return "mytool"
def description(): return "My tool with MSI installer on Windows"
def homepage():    return "https://example.com"
def repository():  return "https://github.com/owner/mytool"
def license():     return "MIT"
def ecosystem():   return "devtools"

runtimes = [{"name": "mytool", "executable": "mytool", "description": "My tool", "priority": 100}]
permissions = {"http": ["api.github.com", "github.com"], "fs": [], "exec": []}

fetch_versions = make_fetch_versions("owner", "mytool")

def download_url(ctx, version):
    os = ctx["platform"]["os"]
    if os == "windows":
        return "https://github.com/owner/mytool/releases/download/v{}/mytool-{}-x64.msi".format(version, version)
    elif os == "macos":
        return github_asset_url("owner", "mytool", "v" + version, "mytool-{}-macos.tar.gz".format(version))
    elif os == "linux":
        return github_asset_url("owner", "mytool", "v" + version, "mytool-{}-linux.tar.gz".format(version))
    return None

def install_layout(ctx, version):
    os = ctx["platform"]["os"]
    url = download_url(ctx, version)
    if os == "windows":
        # MSI: msiexec /a extracts to TARGETDIR, no registry changes
        return msi_install(
            url,
            executable_paths = ["bin/mytool.exe", "mytool.exe"],
            # strip_prefix = "PFiles/MyTool",  # uncomment if msiexec extracts to a subdir
        )
    else:
        return archive_install(
            url,
            strip_prefix = "mytool-{}".format(version),
            executable_paths = ["bin/mytool"],
        )

def environment(ctx, version, install_dir):
    return {"PATH": install_dir}

def deps(ctx, version):
    return []

Step 3: Implement Core Files

Preferred approach: Use provider.star (Starlark) instead of Rust files for most providers. Only create Rust files (runtime.rs, config.rs) when you need capabilities not available in Starlark.

Option A: Starlark-only Provider (Recommended)

For most providers, you only need:

crates/vx-providers/{name}/
├── Cargo.toml      # minimal, no custom Rust code
├── provider.toml   # metadata: name, description, ecosystem, license
└── provider.star   # all logic: fetch_versions, download_url, install_layout

The provider.toml for a Starlark provider only needs metadata:

[provider]
name = "mytool"
description = "My awesome tool"
homepage = "https://example.com"
repository = "https://github.com/owner/repo"
ecosystem = "devtools"
license = "MIT"

All logic (versions, URLs, install layout, system_install) goes in provider.star. See Step 2.2 for the complete Starlark guide.

Option B: Rust Provider (for advanced cases)

Refer to references/templates.md for complete code templates.

Cargo.toml: Use workspace dependencies, package name vx-provider-{name}

lib.rs: Export types and provide create_provider() factory function

provider.rs: Implement Provider trait with:

  • name() - Provider name (lowercase)
  • description() - Human-readable description
  • runtimes() - Return all Runtime instances
  • supports(name) - Check if runtime name is supported
  • get_runtime(name) - Get Runtime by name

runtime.rs: Implement Runtime trait with:

  • name() - Runtime name
  • description() - Description
  • aliases() - Alternative names (if any)
  • ecosystem() - One of: System, NodeJs, Python, Rust, Go
  • metadata() - Homepage, documentation, category
  • fetch_versions(ctx) - Fetch available versions
  • download_url(version, platform) - Build download URL
  • Executable Path Configuration (layered approach, most providers only need 1-2):
    • executable_name() - Base name of executable (default: name())
    • executable_extensions() - Windows extensions (default: [".exe"], use [".cmd", ".exe"] for npm/yarn)
    • executable_dir_path(version, platform) - Directory containing executable (default: install root)
    • executable_relative_path(version, platform) - Full path (auto-generated from above, rarely override)
  • verify_installation(version, install_path, platform) - Verify installation

config.rs: Implement URL builder with:

  • download_url(version, platform) - Full download URL
  • get_target_triple(platform) - Platform target triple
  • get_archive_extension(platform) - Archive extension (zip/tar.gz)
  • get_executable_name(platform) - Executable name with extension

Step 4: Register Provider

4.1 Update Root Cargo.toml

Add to [workspace] members:

"crates/vx-providers/{name}",

Add to [workspace.dependencies]:

vx-provider-{name} = { path = "crates/vx-providers/{name}" }

4.2 Update vx-cli/Cargo.toml

Add dependency:

vx-provider-{name} = { workspace = true }

4.3 Update registry.rs

In crates/vx-cli/src/registry.rs, add:

// Register {Name} provider
registry.register(vx_provider_{name}::create_provider());

Step 5: Project Analyzer Integration (Optional)

If the new tool corresponds to a language/ecosystem (e.g., Go, Java, PHP), add project analyzer support.

5.1 Create Language Analyzer Directory

crates/vx-project-analyzer/src/languages/{lang}/
├── mod.rs          # Module exports
├── analyzer.rs     # {Lang}Analyzer implementation
├── dependencies.rs # Dependency parsing
├── rules.rs        # Script detection rules
└── scripts.rs      # Explicit script parsing

5.2 Define Script Detection Rules

// rules.rs
use crate::languages::rules::ScriptRule;

pub const {LANG}_RULES: &[ScriptRule] = &[
    ScriptRule::new("build", "{build_command}", "Build the project")
        .triggers(&["{config_file}"])
        .priority(50),
    ScriptRule::new("test", "{test_command}", "Run tests")
        .triggers(&["{test_config}", "tests"])
        .priority(50),
    ScriptRule::new("lint", "{lint_command}", "Run linter")
        .triggers(&["{lint_config}"])
        .excludes(&["{task_runner_config}"])
        .priority(50),
];

5.3 Implement LanguageAnalyzer

// analyzer.rs
use super::rules::{LANG}_RULES;
use crate::languages::rules::{apply_rules, merge_scripts};
use crate::languages::LanguageAnalyzer;

pub struct {Lang}Analyzer {
    script_parser: ScriptParser,
}

#[async_trait]
impl LanguageAnalyzer for {Lang}Analyzer {
    fn detect(&self, root: &Path) -> bool {
        root.join("{config_file}").exists()
    }

    fn name(&self) -> &'static str {
        "{Lang}"
    }

    async fn analyze_dependencies(&self, root: &Path) -> AnalyzerResult<Vec<Dependency>> {
        // Parse {config_file} for dependencies
    }

    async fn analyze_scripts(&self, root: &Path) -> AnalyzerResult<Vec<Script>> {
        // 1. Parse explicit scripts from config
        let explicit = parse_config_scripts(root, &self.script_parser).await?;
        
        // 2. Apply detection rules
        let detected = apply_rules(root, {LANG}_RULES, &self.script_parser);
        
        // 3. Merge (explicit takes priority)
        Ok(merge_scripts(explicit, detected))
    }

    fn required_tools(&self, _deps: &[Dependency], _scripts: &[Script]) -> Vec<RequiredTool> {
        vec![RequiredTool::new(
            "{tool}",
            Ecosystem::{Ecosystem},
            "{Tool} runtime",
            InstallMethod::vx("{tool}"),
        )]
    }

    fn install_command(&self, dep: &Dependency) -> Option<String> {
        Some(format!("{package_manager} add {}", dep.name))
    }
}

5.4 Register Analyzer

In crates/vx-project-analyzer/src/languages/mod.rs:

mod {lang};
pub use {lang}::{Lang}Analyzer;

pub fn all_analyzers() -> Vec<Box<dyn LanguageAnalyzer>> {
    vec![
        // ... existing analyzers
        Box::new({Lang}Analyzer::new()),
    ]
}

5.5 Add Analyzer Tests

// crates/vx-project-analyzer/tests/analyzer_tests.rs

#[tokio::test]
async fn test_{lang}_project_detection() {
    let temp = TempDir::new().unwrap();
    std::fs::write(temp.path().join("{config_file}"), "...").unwrap();
    
    let analyzer = {Lang}Analyzer::new();
    assert!(analyzer.detect(temp.path()));
}

#[tokio::test]
async fn test_{lang}_scripts() {
    let temp = TempDir::new().unwrap();
    std::fs::write(temp.path().join("{config_file}"), "...").unwrap();
    
    let analyzer = {Lang}Analyzer::new();
    let scripts = analyzer.analyze_scripts(temp.path()).await.unwrap();
    
    assert!(scripts.iter().any(|s| s.name == "test"));
}

Step 6: Update Snapshot Tests

Update provider/runtime counts in:

  • tests/cmd/plugin/plugin-stats.md - Increment "Total providers" and "Total runtimes"
  • tests/cmd/search/search.md - Add the new runtime to the search results

Step 7: Add Documentation

Add documentation for the new tool in the appropriate category:

English Documentation (docs/tools/)

Category File Tools
DevOps devops.md terraform, docker, kubectl, helm, git
Cloud CLI cloud.md aws, az, gcloud
Build Tools build-tools.md just, task, cmake, ninja, protoc, vite
AI Tools ai.md ollama
Scientific/HPC scientific.md spack, rez
Code Quality quality.md pre-commit
Other other.md deno, zig, java, vscode, rcedit, choco

Chinese Documentation (docs/zh/tools/)

Create corresponding Chinese documentation with the same structure.

Documentation Template

## {Tool Name}

{Brief description}

```bash
vx install {name} latest

vx {name} --version
vx {name} {common-command-1}
vx {name} {common-command-2}

Key Features: (optional)

  • Feature 1
  • Feature 2

Platform Support: (if special)

  • Windows: {notes}
  • Linux/macOS: {notes}

## Step 8: Version Fetching Strategies

### GitHub Releases (Preferred)

```rust
ctx.fetch_github_releases(
    "runtime-name",
    "owner",
    "repo",
    GitHubReleaseOptions::new()
        .strip_v_prefix(false)  // Set true if versions have 'v' prefix
        .skip_prereleases(true),
).await

Manual GitHub API

let url = "https://api.github.com/repos/{owner}/{repo}/releases";
let response = ctx.http.get_json_value(url).await?;
// Parse response and build VersionInfo

Step 9: Verification and Testing

# Check compilation
cargo check -p vx-provider-{name}

# Run tests
cargo test -p vx-provider-{name}

# If analyzer was added
cargo test -p vx-project-analyzer

# Verify full workspace
cargo check

# Run snapshot tests
cargo test --test cli_tests

Common Patterns

VersionInfo Construction

VersionInfo::new(version)
    .with_lts(false)
    .with_prerelease(false)
    .with_release_date(date_string)

VerificationResult

// Success
VerificationResult::success(exe_path)

// Failure
VerificationResult::failure(
    vec!["Error message".to_string()],
    vec!["Suggested fix".to_string()],
)

Platform Matching

match (&platform.os, &platform.arch) {
    (Os::Windows, Arch::X86_64) => Some("x86_64-pc-windows-msvc"),
    (Os::Windows, Arch::Aarch64) => Some("aarch64-pc-windows-msvc"),
    (Os::MacOS, Arch::X86_64) => Some("x86_64-apple-darwin"),
    (Os::MacOS, Arch::Aarch64) => Some("aarch64-apple-darwin"),
    (Os::Linux, Arch::X86_64) => Some("x86_64-unknown-linux-musl"),
    (Os::Linux, Arch::Aarch64) => Some("aarch64-unknown-linux-musl"),
    _ => None,
}

Executable Path Configuration (Layered API)

The framework provides a layered approach - most providers only need 1-2 overrides:

// 1. Simple case: executable in root with standard .exe
// No overrides needed, defaults work

// 2. Tool uses .cmd on Windows (npm, yarn, npx)
fn executable_extensions(&self) -> &[&str] {
    &[".cmd", ".exe"]
}

// 3. Executable in subdirectory
fn executable_dir_path(&self, version: &str, _platform: &Platform) -> Option<String> {
    Some(format!("myapp-{}", version))
}

// 4. Different executable name than runtime name
fn executable_name(&self) -> &str {
    "python3"  // Runtime name is "python"
}

// 5. Complex platform-specific paths (Node.js style)
fn executable_dir_path(&self, version: &str, platform: &Platform) -> Option<String> {
    let dir = format!("node-v{}-{}", version, platform.as_str());
    if platform.is_windows() {
        Some(dir)  // Windows: no bin subdir
    } else {
        Some(format!("{}/bin", dir))  // Unix: has bin subdir
    }
}

ScriptRule Priority Guidelines

Priority Use Case
100 Task runners (nox, tox, just, make)
90 Secondary task runners
50 Default tools (pytest, ruff, cargo)

System Package Manager Integration

For tools without portable binaries on all platforms, implement system package manager fallback.

When to Use System Package Manager

Platform No Direct Download Package Manager Options
macOS No portable binary brew (priority 90)
Windows No portable binary winget (95), choco (80), scoop (60)
Linux No portable binary apt (90), dnf (85), pacman (80)

Step 1: Add system_deps.pre_depends in provider.toml

Declare which package managers are required as dependencies:

# macOS requires Homebrew
[[runtimes.system_deps.pre_depends]]
type = "runtime"
id = "brew"
platforms = ["macos"]
reason = "Required to install {tool} on macOS (no portable binary available)"
optional = false  # brew is required

# Windows: winget (preferred), choco, or scoop (any one is sufficient)
[[runtimes.system_deps.pre_depends]]
type = "runtime"
id = "winget"
platforms = ["windows"]
reason = "Preferred package manager for Windows (built-in on Windows 11)"
optional = true  # any one of winget/choco/scoop is sufficient

[[runtimes.system_deps.pre_depends]]
type = "runtime"
id = "choco"
platforms = ["windows"]
reason = "Alternative to winget for Windows installation"
optional = true

[[runtimes.system_deps.pre_depends]]
type = "runtime"
id = "scoop"
platforms = ["windows"]
reason = "Alternative to winget for Windows installation"
optional = true

Step 2: Add system_install.strategies in provider.toml

Define how to install via each package manager:

# System installation strategies for platforms without direct download
[[runtimes.system_install.strategies]]
type = "package_manager"
manager = "brew"
package = "mytool"  # Homebrew package name
platforms = ["macos"]
priority = 90

[[runtimes.system_install.strategies]]
type = "package_manager"
manager = "winget"
package = "Publisher.Package"  # winget uses Publisher.Package format
platforms = ["windows"]
priority = 95  # Highest priority on Windows (built-in on Win11)

[[runtimes.system_install.strategies]]
type = "package_manager"
manager = "choco"
package = "mytool"
platforms = ["windows"]
priority = 80

[[runtimes.system_install.strategies]]
type = "package_manager"
manager = "scoop"
package = "mytool"
platforms = ["windows"]
priority = 60

Step 3: Implement install() Method with Fallback

For hybrid providers, override install() to try direct download first, then fall back to package manager:

use vx_system_pm::{PackageInstallSpec, PackageManagerRegistry};
use vx_runtime::{InstallResult, Runtime, RuntimeContext};

impl MyRuntime {
    /// Get package name for specific package manager
    fn get_package_name_for_manager(manager: &str) -> &'static str {
        match manager {
            "winget" => "Publisher.MyTool",  // winget uses Publisher.Package format
            "brew" | "choco" | "scoop" | "apt" => "mytool",
            "dnf" | "yum" => "MyTool",  // Some use different casing
            _ => "mytool",
        }
    }

    /// Install via system package manager
    async fn install_via_package_manager(
        &self,
        version: &str,
        _ctx: &RuntimeContext,
    ) -> Result<InstallResult> {
        let registry = PackageManagerRegistry::new();
        let available_managers = registry.get_available().await;

        if available_managers.is_empty() {
            return Err(anyhow::anyhow!(
                "No package manager available. Please install brew (macOS) or winget/choco/scoop (Windows)"
            ));
        }

        // Try each available package manager (sorted by priority)
        for pm in &available_managers {
            let package_name = Self::get_package_name_for_manager(pm.name());
            let spec = PackageInstallSpec {
                package: package_name.to_string(),
                ..Default::default()
            };

            match pm.install_package(&spec).await {
                Ok(_) => {
                    // Return system-installed result with actual executable path
                    let exe_path = which::which("mytool").ok();
                    return Ok(InstallResult::system_installed(
                        format!("{} (via {})", version, pm.name()),
                        exe_path,
                    ));
                }
                Err(e) => {
                    tracing::warn!("Failed to install via {}: {}", pm.name(), e);
                    continue;
                }
            }
        }

        Err(anyhow::anyhow!("All package managers failed"))
    }
}

#[async_trait]
impl Runtime for MyRuntime {
    async fn install(&self, version: &str, ctx: &RuntimeContext) -> Result<InstallResult> {
        let platform = Platform::current();

        // Try direct download first (if available for this platform)
        if let Some(url) = self.download_url(version, &platform).await? {
            return self.install_via_download(version, &url, ctx).await;
        }

        // Fall back to system package manager
        self.install_via_package_manager(version, ctx).await
    }
}

Step 4: Handle InstallResult Correctly

Important: System-installed tools have different paths than store-installed tools:

// Store-installed: executable in ~/.vx/store/{tool}/{version}/bin/
InstallResult::success(install_path, exe_path, version)

// System-installed: executable in system PATH (e.g., /opt/homebrew/bin/)
InstallResult::system_installed(version, Some(exe_path))

The test handler and other code must check executable_path from InstallResult rather than computing store paths.

Package Manager Priority Reference

Manager Platform Priority Notes
winget Windows 95 Built-in on Win11, App Installer on Win10
brew macOS 90 De-facto standard for macOS
apt Linux (Debian) 90 Debian/Ubuntu default
dnf Linux (Fedora) 85 Fedora/RHEL default
choco Windows 80 Popular third-party
pacman Linux (Arch) 80 Arch Linux default
scoop Windows 60 Developer-focused

Common Package Names

Tool brew winget choco scoop apt
ImageMagick imagemagick ImageMagick.ImageMagick imagemagick imagemagick imagemagick
FFmpeg ffmpeg Gyan.FFmpeg ffmpeg ffmpeg ffmpeg
Git git Git.Git git git git
AWS CLI awscli Amazon.AWSCLI awscli aws awscli
Azure CLI azure-cli Microsoft.AzureCLI azure-cli - azure-cli
Docker docker Docker.DockerDesktop docker-desktop - docker.io

provider.toml Quick Reference

Minimal Example (GitHub Releases with Layout)

[provider]
name = "mytool"
description = "My awesome tool"
homepage = "https://github.com/owner/repo"
repository = "https://github.com/owner/repo"
ecosystem = "devtools"

[[runtimes]]
name = "mytool"
description = "My tool CLI"
executable = "mytool"

[runtimes.versions]
source = "github-releases"
owner = "owner"
repo = "repo"
strip_v_prefix = true

# RFC 0019: Executable Layout Configuration
[runtimes.layout]
download_type = "archive"  # or "binary"

[runtimes.layout.archive]
strip_prefix = "mytool-{version}"
executable_paths = [
    "bin/mytool.exe",  # Windows
    "bin/mytool"       # Unix
]

[runtimes.platforms.windows]
executable_extensions = [".exe"]

[runtimes.platforms.unix]
executable_extensions = []

Binary Download Example

[runtimes.layout]
download_type = "binary"

[runtimes.layout.binary."windows-x86_64"]
source_name = "mytool-{version}-win64.exe"
target_name = "mytool.exe"
target_dir = "bin"

[runtimes.layout.binary."linux-x86_64"]
source_name = "mytool-{version}-linux"
target_name = "mytool"
target_dir = "bin"
target_permissions = "755"

Hybrid Provider Example (Direct Download + Package Manager Fallback)

For tools like ImageMagick that have direct download on some platforms but need package managers on others:

[provider]
name = "mytool"
description = "My awesome tool"
homepage = "https://example.com"
ecosystem = "devtools"

[[runtimes]]
name = "mytool"
description = "My tool CLI"
executable = "mytool"

[runtimes.versions]
source = "github-releases"
owner = "owner"
repo = "repo"

# Linux: Direct download available (AppImage, binary, etc.)
[runtimes.layout]
download_type = "binary"

[runtimes.layout.binary."linux-x86_64"]
source_name = "mytool-{version}-linux-x64"
target_name = "mytool"
target_dir = "bin"
target_permissions = "755"

# Note: No Windows/macOS binary configs = download_url returns None
# Triggers package manager fallback

# macOS requires Homebrew
[[runtimes.system_deps.pre_depends]]
type = "runtime"
id = "brew"
platforms = ["macos"]
reason = "Required to install mytool on macOS (no portable binary available)"
optional = false

# Windows: winget (preferred) or choco/scoop
[[runtimes.system_deps.pre_depends]]
type = "runtime"
id = "winget"
platforms = ["windows"]
reason = "Preferred package manager for Windows (built-in on Windows 11)"
optional = true

[[runtimes.system_deps.pre_depends]]
type = "runtime"
id = "choco"
platforms = ["windows"]
reason = "Alternative to winget for Windows installation"
optional = true

# System installation strategies
[[runtimes.system_install.strategies]]
type = "package_manager"
manager = "brew"
package = "mytool"
platforms = ["macos"]
priority = 90

[[runtimes.system_install.strategies]]
type = "package_manager"
manager = "winget"
package = "Publisher.MyTool"
platforms = ["windows"]
priority = 95

[[runtimes.system_install.strategies]]
type = "package_manager"
manager = "choco"
package = "mytool"
platforms = ["windows"]
priority = 80

provider.toml Fields Reference

Section Field Description
[provider] name Provider name (required)
description Human-readable description
homepage Project homepage URL
repository Source repository URL
ecosystem nodejs, python, rust, go, ruby, java, dotnet, devtools, container, cloud, ai, cpp, zig, system
[provider.platforms] os Restrict to platforms: ["windows"], ["macos"], ["linux"]
[[runtimes]] name Runtime name (required)
description Runtime description
executable Executable file name (required)
aliases Alternative names list
bundled_with If bundled with another runtime
[runtimes.versions] source Version source type
owner GitHub owner (for github-releases/tags)
repo GitHub repo name
strip_v_prefix Remove 'v' from version tags
[runtimes.layout] download_type "binary", "archive", or "git_clone" (RFC 0019)
[runtimes.layout.binary."{platform}"] source_name Downloaded file name (supports {version})
target_name Final executable name
target_dir Target directory (e.g., "bin")
target_permissions Unix permissions (e.g., "755")
[runtimes.layout.archive] strip_prefix Directory prefix to remove (supports {version}, {os}, {arch})
executable_paths Paths to executables after stripping
[runtimes.executable_config] dir_pattern Directory pattern (e.g., {name}-{version})
extensions Executable extensions list
[[runtimes.system_deps.pre_depends]] type "runtime" (dependency type)
id Package manager runtime id (brew, winget, choco, scoop)
platforms Array of platforms: ["macos"], ["windows"], ["linux"]
reason Human-readable reason for dependency
optional true if any one of multiple options is sufficient
[[runtimes.system_install.strategies]] type "package_manager" or "manual"
manager Package manager name (brew, winget, choco, scoop, apt, dnf)
package Package name in that manager
platforms Array of platforms this strategy applies to
priority Priority (higher = preferred). winget=95, brew=90, choco=80, scoop=60
[[runtimes.constraints]] when Version condition (e.g., *, ^1, >=2)
requires Required dependencies list
recommends Recommended dependencies list

Manifest Error Diagnostics

When developing a new provider, if your provider.toml has issues, the vx error system provides structured diagnostics:

Error Categories

  1. Parse Errors (with context) - TOML parsing failures with provider name and hints:

    • Unknown enum variants (e.g., wrong ecosystem or download_type value)
    • Type mismatches (e.g., using when = { os = "windows" } instead of when = "*")
    • Missing required fields
    • kebab-case vs snake_case confusion

  2. Build Errors - Provider registration failures:

    • NoFactory (manifest-only): Provider has a provider.toml but no Rust implementation yet. This is expected for new providers that only have manifests.
    • FactoryFailed: The Rust factory function failed to create the provider.

Common Mistakes and Auto-Hints

Error Pattern Auto-Hint
unknown variant "cpp" for ecosystem Lists all valid ecosystem values
invalid type: map, expected a string for when Suggests using when = "*" with separate platform field
unknown variant "git-clone" for download_type Suggests using git_clone (snake_case)
missing field "name" Points to the required field
invalid type: integer, expected a string Suggests quoting version numbers

Debug Output

The build summary shows:

INFO: registered 53 lazy providers (0 errors, 9 manifest-only, 0 warnings)
  • errors: Real configuration errors that need fixing
  • manifest-only: Providers with manifests but no Rust factory (expected during development)
  • warnings: Non-fatal issues

Reference Files

For complete code templates, see references/templates.md.

Weekly Installs
5
Repository
loonghao/vx
GitHub Stars
18
First Seen
Feb 16, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
cursor5
gemini-cli5
replit5
antigravity5
claude-code5
github-copilot5