ARW Release Manager

# 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)

```bash
# 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

```bash
# 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.

```bash
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.

```bash
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.

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Run Node.js native tests
npm test

# Run WASM-specific tests
npm run test:wasm
```

### Rust Tests

```bash
# 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

```bash
# 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

```bash
# Debug build
cargo build --features native

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

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

### WASM Builds

```bash
# 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

```bash
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:

```bash
./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

```bash
# 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`.

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

---

## Publishing

### npm

```bash
# 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

```bash
# 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](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](https://keepachangelog.com)
- [Semantic Versioning](https://semver.org)
- [npm publish docs](https://docs.npmjs.com/cli/publish)
- [Cargo publish docs](https://doc.rust-lang.org/cargo/reference/publishing.html)