ARW Release Manager

Build, test, and release orchestration for the ARW (Agent-Ready Web) CLI package supporting multiple build targets and publishing to npm and crates.io.

Build Targets

The ARW CLI supports three distinct build targets:

Target	Command	Output	Use Case
napi-rs	npm run build	arw-cli.darwin-arm64.node	Node.js native addon (require in JS)
Standalone CLI	cargo build --release --features native	target/release/arw	Executable binary
WASM	npm run build:wasm	wasm-pkg/	Browser/bundler usage

Prerequisites

• Node.js 18+ and npm 8+
• Rust toolchain (rustc, cargo) for Rust builds
• Git repository
• wasm-pack (for WASM builds): cargo install wasm-pack

For publishing only:

• npm account with publish access
• crates.io account with API token

What This Skill Does

1. Local development - Watch mode, hot reload, iterative builds
2. Testing - Unit tests, integration tests, WASM tests, linting
3. Building - napi-rs native addon, standalone CLI, and WASM builds
4. Pre-release validation - Git status, version checks, secrets scanning
5. Documentation - CHANGELOG generation, API docs
6. Version management - Semantic versioning, git tagging
7. Publishing - npm publish, cargo publish with dry-run validation

---

Quick Start

Local Development (No Publishing)

# Build napi-rs native addon (Node.js bindings)
npm install && npm run build

# Build standalone CLI binary
cargo build --release --features native
./target/release/arw --version

# Run tests
npm test && npm run test:wasm && cargo test

Full Release Workflow

# 1. Verify, test, and build (dry run)
./scripts/quick-publish.sh --dry-run

# 2. If checks pass, publish
./scripts/quick-publish.sh

---

Build Targets Explained

1. napi-rs Native Addon (Node.js)

This builds a native Node.js addon using napi-rs. The result is a .node file that can be require()'d from JavaScript.

npm run build                    # Release build
npm run build:debug              # Debug build (faster)

# Test the module
node -e "const cli = require('./index.js'); console.log(cli.getVersionInfo());"

Exports: validateManifest, checkCompatibility, generateManifest, getVersionInfo

2. Standalone CLI Binary

This builds a standalone executable that can be run directly from the command line.

cargo build --release --features native

# Run directly
./target/release/arw --version
./target/release/arw --help
./target/release/arw validate path/to/manifest.json
./target/release/arw init
./target/release/arw generate

CLI Commands: init, generate, sitemap, validate, serve, scan, policy, robots, watch, actions, build

3. WASM Build

For browser and bundler usage.

npm run build:wasm              # Node.js target
npm run build:wasm:web          # Browser target
npm run build:wasm:bundler      # Bundler target

# Test WASM
npm run test:wasm

---

Local Development Guide

Node.js Native Addon Development

# Install dependencies
npm install

# Build native addon (napi-rs)
npm run build              # Release
npm run build:debug        # Debug (faster iteration)

# Test module loading
node -e "const {validateManifest, getVersionInfo} = require('./index.js'); console.log(getVersionInfo());"

# Link for testing in other projects
npm link

Standalone CLI Development

# Debug build (fast compilation)
cargo build --features native

# Run without installing
cargo run --features native -- --version
cargo run --features native -- --help
cargo run --features native -- validate ./test-manifest.json

# Release build
cargo build --release --features native
./target/release/arw --version

# Install globally
cargo install --path . --features native
arw --version

# Watch mode (requires cargo-watch)
cargo install cargo-watch
cargo watch -x "run --features native -- --help"

WASM Development

# Build WASM
npm run build:wasm

# Run WASM tests
npm run test:wasm

Development Workflow

1. Make code changes in src/
2. Run tests: cargo test / npm run test:wasm
3. Build target you need:
   • Node.js addon: npm run build
   • Standalone CLI: cargo build --release --features native
   • WASM: npm run build:wasm
4. Test locally
5. Repeat

---

Testing

Node.js Tests

# Run Node.js native tests
npm test

# Run WASM-specific tests
npm run test:wasm

Rust Tests

# Format check
cargo fmt --check

# Linting with clippy
cargo clippy -- -D warnings

# Run all tests
cargo test

# Run with output visible
cargo test -- --nocapture

# All checks
cargo fmt --check && cargo clippy -- -D warnings && cargo test

---

Building

napi-rs Native Addon

# Release build (optimized)
npm run build

# Debug build (faster compilation)
npm run build:debug

Output: arw-cli.<platform>.node + index.js + index.d.ts

Standalone CLI Binary

# Debug build
cargo build --features native

# Release build (optimized)
cargo build --release --features native

Output: target/release/arw or target/debug/arw

WASM Builds

# Node.js WASM
npm run build:wasm

# Browser WASM
npm run build:wasm:web

# Bundler WASM
npm run build:wasm:bundler

Output: wasm-pkg/nodejs/, wasm-pkg/web/, wasm-pkg/bundler/

Cross-Platform Standalone CLI Builds

cargo build --release --features native --target x86_64-unknown-linux-gnu
cargo build --release --features native --target x86_64-apple-darwin
cargo build --release --features native --target aarch64-apple-darwin
cargo build --release --features native --target x86_64-pc-windows-msvc

---

Pre-Release Validation

Run before any release:

./scripts/verify-package.sh

This checks:

• package.json validity and required fields
• Semantic version format
• Built files exist
• CLI executables have shebangs
• No hardcoded secrets
• Documentation files present
• Package size reasonable

---

Version Management

Semantic Versioning Rules

Change Type	Version Bump	Example
Breaking changes	MAJOR	1.0.0 → 2.0.0
New features (backwards compatible)	MINOR	1.0.0 → 1.1.0
Bug fixes	PATCH	1.0.0 → 1.0.1

Bump Version

# TypeScript - auto-bump in package.json
npm version patch --no-git-tag-version  # or minor/major

# Rust - manual edit Cargo.toml
# Change: version = "x.y.z"

Update CHANGELOG

Use Keep a Changelog format. See resources/templates/CHANGELOG.template.md.

# Generate commit log since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

---

Publishing

npm

# Check login
npm whoami

# Preview package contents
npm pack --dry-run

# Dry run publish
npm publish --dry-run --access public

# Publish for real
npm publish --access public

# Verify
npm view arw-cli

crates.io

# Login (one-time setup)
cargo login

# Dry run
cargo publish --dry-run

# Publish
cargo publish

# Verify
cargo search arw-cli

---

Available Scripts

Script	Purpose
scripts/build-all.sh	Build all packages
scripts/build-all.sh --dev	Development build only
scripts/build-all.sh --release	Production release build
scripts/verify-package.sh	Pre-release validation
scripts/quick-publish.sh --dry-run	Preview release
scripts/quick-publish.sh	Full release workflow
scripts/quick-publish.sh --skip-tests	Release without tests
scripts/quick-publish.sh --npm-only	Publish to npm only
scripts/quick-publish.sh --cargo-only	Publish to crates.io only

---

Troubleshooting

npm Issues

403 Forbidden

• Check npm whoami - must be logged in
• Verify package name isn't taken
• Ensure --access public for scoped packages

Version Already Exists

• npm doesn't allow republishing same version
• Bump version and try again

EPERM / Permission Denied

• Fix npm prefix: npm config set prefix ~/.npm-global
• Or use sudo (not recommended)

Cargo Issues

Not Logged In

• Run cargo login with API token from crates.io
• Token stored in ~/.cargo/credentials.toml

Version Already Published

• crates.io doesn't allow version overwrites
• Must bump version

Missing Required Fields

• Cargo.toml needs: name, version, edition, description, license, repository

Git Issues

Dirty Working Tree

• Commit or stash changes before release
• git stash or git add -A && git commit

Tag Already Exists

• Delete and recreate: git tag -d v1.0.0 && git tag v1.0.0
• Or use different version

---

Advanced Configuration

See docs/ADVANCED.md for:

• CI/CD integration with GitHub Actions
• Multi-platform release builds
• Automated changelog generation
• GPG signing releases
• Pre-release channels (alpha, beta, rc)

---

Resources

• Templates: resources/templates/
• Advanced docs: docs/ADVANCED.md
• Keep a Changelog
• Semantic Versioning
• npm publish docs
• Cargo publish docs