@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/working-with-mise/references/dev-tools/backends/vfox.md

@@ -0,0 +1,173 @@
+Vfox Backend
+
+Vfox Backend [​](#vfox-backend)
+
+TIP
+
+vfox is the recommended plugin system for mise. It provides cross-platform support, built-in modules, and a modern hook-based architecture.
+
+Plugins for [vfox](https://github.com/version-fox/vfox) can be used in mise to install tools.
+
+## Why vfox? [​](#why-vfox)
+
+- **Cross-platform** — Lua hooks run on Windows, macOS, and Linux; plugins still need compatible artifacts and platform handling
+- **Built-in modules** — HTTP, JSON, HTML parsing, archive extraction, semver comparison, and logging are all available out of the box, with no external dependencies needed
+- **Security** — [tool plugins](https://mise.jdx.dev/tool-plugin-development.html) support attestation verification (GitHub artifact attestations, cosign signatures, SLSA provenance) for downloaded artifacts. When a tool plugin's `PreInstall` hook returns an `attestation` table, mise verifies it during install and records the result in `mise.lock`, protecting against downgrade attacks on subsequent installs. Backend plugins do not currently support attestation
+- **Structured hooks** — contexts for version discovery, installation, and environment setup; backend plugins can manage multiple tools
+
+The code for this is inside the mise repository at [`./src/backend/vfox.rs`](https://github.com/jdx/mise/blob/main/src/backend/vfox.rs).
+
+## Dependencies [​](#dependencies)
+
+The Lua interpreter is built into mise. A plugin may still invoke external commands or install software that needs system libraries. Read that plugin's requirements; the built-in interpreter does not make every plugin portable.
+
+## Usage [​](#usage)
+
+Install cmake from an explicit vfox plugin and verify the selected executable:
+
+sh
+
+```
+mise use vfox:version-fox/vfox-cmake
+mise exec -- cmake --version
+```
+
+This writes the following project configuration. Add `-g` for a global tool.
+
+toml
+
+```
+[tools]
+"vfox:version-fox/vfox-cmake" = "latest"
+```
+
+The explicit prefix selects that plugin even if the `cmake` registry shorthand prefers another backend.
+
+## Default plugin backend [​](#default-plugin-backend)
+
+Windows excludes asdf from default backend selection. On Linux and macOS, you can exclude it with `mise settings add disable_backends asdf`, but this does not make vfox take precedence over built-in, Packslip, Aqua, or release backends. Check `mise registry cmake` for the shorthand's available sources, or use an explicit `vfox:` identifier when you intend to use a particular plugin.
+
+## Plugins [​](#plugins)
+
+In addition to the standard vfox tool plugins, mise supports backend plugins that can manage multiple tools using the `plugin:tool` format. These plugins are well suited to:
+
+- Installing tools from private repositories
+- Package managers (npm, pip, etc.)
+- Custom tool families
+
+### Example: Plugin Usage [​](#example-plugin-usage)
+
+bash
+
+```
+# Install a plugin
+mise plugins install my-plugin https://github.com/username/my-plugin
+
+# Use the plugin:tool format
+mise install my-plugin:some-tool@1.0.0
+mise use my-plugin:some-tool@latest
+```
+
+### Install from Zip File [​](#install-from-zip-file)
+
+Replace `PLUGIN_NAME` and `HTTPS_ZIP_URL` with the plugin name and archive URL.
+
+bash
+
+```
+# Install a plugin from a zip file over HTTPS
+mise plugins install PLUGIN_NAME HTTPS_ZIP_URL
+# Example: Installing a plugin from a zip file
+mise plugins install vfox-cmake https://github.com/mise-plugins/vfox-cmake/archive/refs/heads/main.zip
+```
+
+### Install from a signed packslip [​](#install-from-a-signed-packslip)
+
+A publisher can distribute a vfox plugin for a non-registry tool as a signed, portable archive. Select that source explicitly, keeping the plugin release separate from tool versions:
+
+sh
+
+```
+mise plugins install vfox:PLUGIN_NAME 'packslip:OWNER/REPO#PLUGIN_VERSION'
+```
+
+Or configure it:
+
+toml
+
+```
+[plugins]
+"vfox:PLUGIN_NAME" = "packslip:OWNER/REPO#PLUGIN_VERSION"
+```
+
+Omit `#PLUGIN_VERSION` to resolve the latest eligible plugin release through the packslip backend. `mise plugins update PLUGIN_NAME` preserves an explicit pin; reinstall with another source version to change it. The installed plugin records its resolved version, artifact digest, and signer. Reinstalling the same version checks those pins again.
+
+This initially supports GitHub repositories publishing `packslip.sigstore.json` with a portable `tar.gz` artifact declaring `extensions.mise.plugin = "vfox"` and no executables or host requirements. The archive must have `metadata.lua` at its root and contain no links, special files, Git metadata, or unsafe paths. Mise uses the packslip backend's signature, digest, signer, and release policy checks. It verifies and stages replacements before removing the previous plugin.
+
+The [bfs publisher example](https://github.com/mise-plugins/vfox-bfs/releases/tag/v0.1.0) demonstrates the format, verified on Linux and macOS. Normal bfs usage continues to use its embedded plugin without downloading a plugin release. Packslip is an explicit source option; existing registry defaults, Git and ZIP sources remain unchanged.
+
+For more information, see:
+
+- [Using Plugins](https://mise.jdx.dev/plugin-usage.html) - End-user guide
+- [Plugin Development](https://mise.jdx.dev/tool-plugin-development.html) - Developer guide
+- [Plugin Template](https://github.com/jdx/mise-tool-plugin-template) - Quick start template for creating plugins
+
+## URL replacements [​](#url-replacements)
+
+The vfox backend honors mise's [`url_replacements`](https://mise.jdx.dev/url-replacements.html) setting for both tool artifact downloads and requests made through the plugin's built-in Lua HTTP module. This includes `http.get`, `http.head`, `http.download_file`, and their `try_*` variants.
+
+After applying URL replacements, vfox also uses mise's [`netrc`](https://mise.jdx.dev/configuration/settings.html#netrc) setting to add HTTP Basic authentication for the destination host. An explicit `Authorization` header supplied by a plugin takes precedence when the request stays on the same origin.
+
+## Tool Options [​](#tool-options)
+
+The following [tool-options](https://mise.jdx.dev/dev-tools/#tool-options) are available for the `vfox` backend—these go in `[tools]` in `mise.toml`.
+
+Traditional vfox `PreInstall` and `PostInstall` hooks receive custom options in the structured `ctx.options` table. Scalar values use mise's existing string representation, while arrays and tables remain structured:
+
+toml
+
+```
+[tools]
+"vfox:example/plugin" = { version = "1.0.0", bundled = false, channels = ["stable", "beta"] }
+```
+
+lua
+
+```
+function PLUGIN:PreInstall(ctx)
+    local bundled = ctx.options.bundled == "false"
+    local channels = ctx.options.channels
+    -- ...
+end
+```
+
+Existing plugins can continue reading custom options from their hook environment with the `MISE_TOOL_OPTS__` prefix. Those variables are available only while mise runs the plugin hook and are not exported to the user's shell. New plugins should use `ctx.options`.
+
+### `install_env` [​](#install-env)
+
+Set environment variables for commands that a vfox plugin starts with `cmd.exec` during install hooks. vfox's built-in Lua HTTP, archive, and JSON helpers do not use these variables directly.
+
+toml
+
+```
+[tools]
+"vfox:version-fox/vfox-cmake" = { version = "latest", install_env = { HTTPS_PROXY = "http://proxy.example" } }
+```
+
+### Install dependencies [​](#install-dependencies)
+
+Plugin authors should declare intrinsic install requirements with `PLUGIN.depends` in `metadata.lua`. Users can supplement those declarations with the [`depends` tool option](https://mise.jdx.dev/dev-tools/#tool-dependencies). Matching configured tools from both sources share one install dependency context: they are ordered before the dependent tool, and their paths and `tools = true` values are available to install hooks launched through `os.execute` or `cmd.exec`.
+
+Declarations do not configure or automatically install a tool. A matching configured dependency must resolve and be installed; an unconfigured dependency can still be supplied by the existing system or configuration `PATH`. `io.popen` does not receive this install environment.
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/backends/vfox.md)
+
+Last updated:
+
+Pager
+
+[Previous pageubi](https://mise.jdx.dev/dev-tools/backends/ubi.html)
+
+[Next pageOverview](https://mise.jdx.dev/bootstrap.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)

package/skills/working-with-mise/references/dev-tools/backends.md

@@ -0,0 +1,32 @@
+---
+title: "Backends | mise-en-place"
+meta:
+  description: "mise-en-place documentation"
+---
+
+# Backends [​](#backends)
+
+Backends are package managers or ecosystems that mise uses to install [tools](https://mise.jdx.dev/dev-tools/index.html) and [plugins](https://mise.jdx.dev/plugins.html). Each backend can install and manage multiple tools from its ecosystem. For example, the `npm` backend can install many different tools like `npm:prettier`, or the `pipx` backend can install tools like `pipx:black`. This allows mise to support a wide variety of tools and languages by leveraging different package managers and their ecosystems.
+
+When you run the [`mise use`](https://mise.jdx.dev/cli/use.html) command, mise will determine the appropriate backend to use based on the tool you are trying to manage. The backend will then handle the installation, configuration, and any other necessary steps to ensure the tool is ready to use.
+
+For more details on how backends fit into mise's overall design, see the [backend architecture documentation](https://mise.jdx.dev/dev-tools/backend_architecture.html).
+
+Below is a list of the available backends in mise:
+
+- [asdf](https://mise.jdx.dev/dev-tools/backends/asdf.html) (provide tools through [plugins](https://mise.jdx.dev/plugins.html))
+- [aqua](https://mise.jdx.dev/dev-tools/backends/aqua.html)
+- [cargo](https://mise.jdx.dev/dev-tools/backends/cargo.html)
+- [conda](https://mise.jdx.dev/dev-tools/backends/conda.html) experimental
+- [dotnet](https://mise.jdx.dev/dev-tools/backends/dotnet.html) experimental
+- [gem](https://mise.jdx.dev/dev-tools/backends/gem.html)
+- [github](https://mise.jdx.dev/dev-tools/backends/github.html)
+- [gitlab](https://mise.jdx.dev/dev-tools/backends/gitlab.html)
+- [go](https://mise.jdx.dev/dev-tools/backends/go.html)
+- [http](https://mise.jdx.dev/dev-tools/backends/http.html)
+- [npm](https://mise.jdx.dev/dev-tools/backends/npm.html)
+- [pipx](https://mise.jdx.dev/dev-tools/backends/pipx.html)
+- [spm](https://mise.jdx.dev/dev-tools/backends/spm.html) experimental
+- [ubi](https://mise.jdx.dev/dev-tools/backends/ubi.html)
+- [vfox](https://mise.jdx.dev/dev-tools/backends/vfox.html) (provide tools through [plugins](https://mise.jdx.dev/plugins.html))
+- [custom backends](https://mise.jdx.dev/backend-plugin-development.html) (build your own backend with a plugin which itself provides many tools)

package/skills/working-with-mise/references/dev-tools/comparison-to-asdf-html.md

@@ -0,0 +1,112 @@
+Comparison to asdf
+
+Comparison to asdf [​](#comparison-to-asdf)
+
+mise reads `.tool-versions` and supports [legacy asdf plugins](https://mise.jdx.dev/dev-tools/backends/asdf.html). You can start with an existing project's version declarations, then adopt `mise.toml` for [environment variables](https://mise.jdx.dev/environments/) and [tasks](https://mise.jdx.dev/tasks/). CLI and plugin compatibility are best-effort; mise has its own commands, installation directories, and backend selection.
+
+## Migrate from asdf to mise [​](#migrate-from-asdf-to-mise)
+
+Start in one project before changing your shell defaults:
+
+1. [Install mise](https://mise.jdx.dev/installing-mise.html).
+2. From the project directory, run `mise config ls` and `mise ls --current` to inspect how mise reads the existing `.tool-versions`.
+3. Run `mise install`, then verify a project command through mise:sh
+
+   ```
+   mise exec -- node --version
+   ```
+
+   Replace `node --version` with a command from your project's tools. mise uses its own installations; it does not automatically reuse asdf's install directory.
+4. Once the project works, remove asdf activation and shim `PATH` entries from your shell startup files and [activate mise](https://mise.jdx.dev/getting-started.html#activate-mise). Start a new shell and check `mise doctor` and `command -v node`.
+
+Keep shared `.tool-versions` files if teammates still use asdf. To update one with mise, specify the file and pin a concrete version:
+
+sh
+
+```
+mise use --path .tool-versions --pin node@24
+```
+
+Avoid mise-specific prefixes or backend identifiers in a file that asdf must read. A `mise.toml` in the same directory takes precedence for tools it declares, so check for conflicting declarations before keeping both files.
+
+For personal defaults, use `mise use -g node@24` or edit `~/.config/mise/config.toml`. Inspect `mise config ls` from outside a project to see which home/global files are contributing to your environment. Copy the versions you need explicitly instead of moving or rewriting your asdf installation.
+
+## asdf in go (0.16+) [​](#asdf-in-go-0-16)
+
+asdf 0.16 replaced the older Bash implementation with Go and changed parts of its CLI. In particular, current asdf uses `asdf set` to write versions. See [asdf's version commands](https://asdf-vm.com/manage/versions.html). `mise set` has a different purpose: it writes environment variables. Use `mise use` for tool versions.
+
+## UX [​](#ux)
+
+`mise use` combines installation and configuration. For example:
+
+sh
+
+```
+mise use node@24 python@3.14
+mise exec -- node --version
+```
+
+This records version requests for both tools and installs them if necessary. After cloning a configured project, `mise install` installs its tools without changing the declarations. You usually do not need to install plugins separately: the registry selects a backend, and many tools use built-in backends.
+
+## Command Compatibility [​](#command-compatibility)
+
+Prefer mise's documented command syntax in scripts. Some legacy asdf spellings are accepted, but compatibility aliases are not a complete emulation of asdf.
+
+| Goal | asdf command | mise command |
+| --- | --- | --- |
+| Install a specific version | `asdf install nodejs 24.0.0` | `mise install node@24.0.0` |
+| Select a project version | `asdf set nodejs 24.0.0` | `mise use node@24.0.0` (also installs) |
+| Select a personal default | `asdf set -u nodejs 24.0.0` | `mise use -g node@24.0.0` |
+| List available versions | `asdf list all nodejs` | `mise ls-remote node` |
+| Inspect selected versions | `asdf current` | `mise ls --current` |
+| Find the selected executable | `asdf which node` | `mise which node` |
+| Rebuild shims | `asdf reshim` | `mise reshim` |
+
+mise recognizes the legacy tool names `nodejs` and `golang`, while its TOML configuration uses the canonical names `node` and `go`.
+
+## Performance [​](#performance)
+
+The main difference is when version selection runs. With normal `mise activate`, mise updates `PATH` and environment variables at the shell prompt or supported directory-change hooks. Subsequent tool calls use those executable paths directly. asdf resolves a tool through a shim when it is called.
+
+mise also provides shims for programs that need stable executable paths. Their cost depends on how often commands pass through mise; use `mise exec -- <script>` to prepare the environment once for a script and its child processes. Historical benchmarks of Bash-based asdf do not describe current asdf performance. See [shims](https://mise.jdx.dev/dev-tools/shims.html) for the behavioral tradeoffs.
+
+## Windows support [​](#windows-support)
+
+mise supports native Windows for compatible tools and backends. Availability still depends on the tool's release artifacts and installation logic. Legacy asdf shell plugins generally require a Unix environment; using mise does not make those plugins native Windows installers. See [Windows](https://mise.jdx.dev/installing-mise.html#windows-scoop).
+
+## Supply chain security [​](#supply-chain-security)
+
+An asdf plugin executes shell code during tool management. When using one through either manager, you trust the plugin's maintainers in addition to the tool's publisher. mise can install many tools through built-in download backends without an external plugin.
+
+## Security [​](#security)
+
+Verification varies by distribution. For example, packslip verifies signed manifests, and aqua supports verification methods described by its registry entries. A tool or backend name alone is not a guarantee that a particular artifact has a signature. See the [security guide](https://mise.jdx.dev/security.html) for trust, verification, and configuration controls.
+
+## Extra backends [​](#extra-backends)
+
+Use the registry shorthand when available, or select a package source explicitly:
+
+mise.toml
+
+toml
+
+```
+[tools]
+node = "24"
+ripgrep = "latest"
+"npm:prettier" = "3"
+```
+
+Here the npm backend needs Node.js, so both are declared. Other backends can install release binaries, Python CLIs, Rust crates, or private tools. See the [backend reference](https://mise.jdx.dev/dev-tools/backends/) for prerequisites and options.
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/comparison-to-asdf.md)
+
+Last updated:
+
+Pager
+
+[Previous pageDev Tools Overview](https://mise.jdx.dev/dev-tools/)
+
+[Next pageShims](https://mise.jdx.dev/dev-tools/shims.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)