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:

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

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

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