arw-release-manager

name	ARW Release Manager
description	Build and release manager for ARW CLI package. Handles local development, testing, building, documentation, version tagging, and publishing to npm and crates.io. Use when developing locally, running tests, building packages, releasing new versions, or publishing packages.

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