APVM — Automation Plugin Version Manager

A Rust CLI tool and library for building and managing multiple versions of WordPress plugins from any git reference (branch, tag, commit, or PR).

Built for developers and QA engineers who need to quickly build plugins from specific PRs, switch between versions, and automate version management.

Available commands

Command	Description
build	Build a plugin from a git reference (branch, tag, commit, PR)
list	List all available plugins
info	Show detailed information about a plugin
config	View or change configuration settings

Run apvm --help for full usage or apvm <command> --help for command-specific options.

Features

• Build from any git ref — branch, tag, or commit SHA, PR number (PR number is WIP)
• Automatic ref detection — v1.0.0 to a tag, develop to a branch, 123 resolves to PR #123 (when a GitHub token is provided or when this tool auto-detects one)
• Multi-variant builds — e.g., BackWPup produces free, pro-de, and pro-en variants. You can choose which ones you want to build (free and pro-en are defaults for BackWPup).
• Version handling — required, embedded (auto-detected), or optional per plugin (BackWPup requires version to be specified at build time, and WP Rocket does not require this)

Supported Plugins

Plugin	Variants	Version	Repository
BackWPup	free, pro-de, pro-en	Required	Private
WP Rocket	(single)	Embedded	Public

Requirements

• Rust ≥ 1.85 (2024 edition)
• Git installed and in PATH
• GitHub authentication for private repositories (optional for public). This tool attempts to auto-detect.
• Plugin-specific build tools (npm, composer, gulp, rsync, zip, etc.) as needed (try apvm info [plugin-name] to learn more about a specific plugin)

Installation

Install the apvm binary globally via cargo install:

cargo install --path crates/cli

This compiles in release mode and places the apvm binary in ~/.cargo/bin/, which should already be in your PATH.

Updating After Changes

After pulling changes or switching branches, reinstall with --force to overwrite the existing binary:

cargo install --path crates/cli --force

The --force flag is required when reinstalling a package at the same version number.

Development Build

For local development (unoptimized, faster compile):

cargo build

Binary at target/debug/apvm.

Node.js / N-API bindings (apvm-napi)

This repository now includes a Node.js package powered by napi-rs, exposed as apvm-napi.

Node.js and build requirements — short summary

• Runtime (using the package): apvm-napi supports Node.js 18 and later at runtime. For platforms where a pre-compiled .node binary is provided, no native build is required on the consumer machine.
• Build-time (only when a prebuilt binary is NOT available): building the native addon requires a Rust toolchain (cargo, rustc) and Node.js 20+ for the build scripts. Some helper scripts used during the build process rely on Node 20+ APIs (for example certain node:util helpers). The resulting compiled addon can still run on Node.js 18+ provided the addon is built for a compatible N-API level.

In short: if your platform/arch matches a prebuilt binary included in this repository you only need Node.js 18+ at runtime; if no prebuilt binary exists for your platform you must build from source, which requires Node.js 20+ and the Rust toolchain.

Included pre-compiled binaries in this repository (these are shipped with the package and used automatically by the loader):

• apvm-napi.darwin-arm64.node — macOS (Apple Silicon / arm64)
• apvm-napi.linux-x64-gnu.node — Linux x86_64 (GNU/glibc)
• apvm-napi.linux-arm64-gnu.node — Linux arm64 (GNU/glibc)
• apvm-napi.win32-x64-msvc.node — Windows x64 (MSVC)

If your platform/arch is not listed above, the package install will attempt to compile the native addon locally.

Build from source (only required if your platform is not prebuilt)

If a prebuilt .node binary for your platform is not present, the package's install step will compile the native addon locally. Building from source requires:

• Node.js 20+ (required during the build step only; runtime can be Node.js 18+)
• Rust toolchain (rustup, cargo, rustc) installed and available on PATH
• Platform development tools and headers (C compiler, linker). On Debian/Ubuntu, install build-essential, pkg-config, and libssl-dev.

To build locally (release):

# ensure Node 20+ is active for the build step
node -v # should be v20.x or later

# From repository root
npm i
npm run build

Notes:

• Using Node 20 for the build step does not force runtime Node 20 for users — the compiled addon can be used on Node 18+ when the addon is built against a compatible N-API level.

Quick API usage (TypeScript/Node.js)

import { Apvm } from 'apvm-napi';

const apvm = await Apvm.create();

const output = await apvm.buildFromBranch('wp-rocket', 'develop', '/tmp/apvm-output');

console.log(output.description);
console.log(output.result.artifacts.map((a) => a.filename));

API overview

• Apvm.create(config?) → creates an instance (async)
• Apvm.createWithTokenResolution(config?) → resolves token from config/env/gh CLI (async)
• apvm.hasToken() / apvm.tokenSource() / apvm.listProjects()
• Build methods:
  • apvm.build(options, onProgress?)
  • apvm.buildFromPr(...)
  • apvm.buildFromBranch(...)
  • apvm.buildFromTag(...)
  • apvm.buildFromCommit(...)

You can pass any gitref (branch, commit or tag) to apvm.build

ApvmConfig fields are optional:

• buildsDir?: string
• githubToken?: string

For full signatures and event/result types, see index.d.ts.

Why is apvm.create() async?

This rust project uses tokio runtime (for asynchronous operations in rust), and some dependencies heavily rely on tokio, so, to keep things simple, creating an instance is asynchronous.

Usage

Build a Plugin

# Build from a branch
apvm build backwpup develop -v 5.1.0

# Build from a tag
apvm build backwpup v5.1.0 -v 5.1.0

# Build from a PR number
apvm build backwpup 123 -v 5.1.0

# Build from a commit SHA
apvm build backwpup abc1234 -v 5.1.0

# Explicit ref prefixes
apvm build backwpup tag:v5.1.0 -v 5.1.0
apvm build backwpup branch:develop -v 5.1.0
apvm build backwpup commit:abc1234 -v 5.1.0
apvm build backwpup pr:123 -v 5.1.0

# Build specific variants only
apvm build backwpup 123 -v 5.1.0 --variants free,pro-en

# Specify output directory (default: current directory)
apvm build backwpup 123 -v 5.1.0 ./dist

# Verbose output (shows commands and full output)
apvm --verbose build backwpup 123 -v 5.1.0

Ref auto-detection rules:

Input	Resolved as
develop	Branch
v1.0.0	Tag (if exists), else branch
abc1234	Commit SHA (7-40 hex)
123	PR #123
#123	PR #123 (# stripped)

List Plugins

apvm list

Plugin Details

apvm info backwpup

apvm info wp-rocket

Shows repository, version requirement, available variants, and required build tools.

Configuration

# Show all settings
apvm config

# Get a specific value
apvm config get token

# Set GitHub token (For building from PR numbers)
apvm config set token ghp_xxxxxxxxxxxx

# Set custom builds directory
apvm config set builds-dir /path/to/builds

# Remove a value (revert to default)
apvm config unset token

# Show config file path
apvm config path

NOTE: builds-dir is not used/implemented at the moment

Debug Logging

RUST_LOG=debug apvm build backwpup 123 -v 5.1.0
RUST_LOG=trace apvm build backwpup 123 -v 5.1.0

Tracing is only enabled when RUST_LOG is set. See the tracing-subscriber EnvFilter docs for filter syntax.

Project Structure

crates/
├── cli/        CLI binary (clap-based), owns defaults and user interaction
├── config/     Pure configuration types (no I/O, no defaults)
├── core/       Core library: building, git, GitHub API, version detection
└── storage/    Artifact storage, deduplication, manifests, queries (CURRENTLY NOT USED BY CLI)

Architecture

• Config — pure serde types for configuration. No file I/O, no hardcoded paths.
• Core — orchestrates builds (clone → fetch → resolve ref → checkout → detect version → build → collect artifacts), git operations, GitHub API via octocrab, and project registry.
• Storage — manages artifacts with commit-based deduplication, cross-platform links (symlinks on Unix, junctions on Windows), and a fluent query API.
• CLI — owns default paths (~/.apvm, ~/apvm-builds), provides progress display via indicatif, and delegates all logic to core.

Running Tests

# All tests
cargo test

# Specific crate
cargo test -p apvm-core
cargo test -p apvm-storage
cargo test -p apvm-config
cargo test -p apvm

# Node.js tests (Vitest)
npm test

Key Dependencies

Crate	Version	Purpose
clap	4.5	CLI argument parsing
tokio	1.49	Async runtime
octocrab	0.49	GitHub API client
serde	1.0	Serialization/deserialization
indicatif	0.18	Progress bars and spinners
thiserror	2.0	Error type derivation
tracing	0.1	Structured logging

License

Private — WP Media.