# N-API Multi-Platform CI/CD - Complete Setup

## Executive Summary

A complete multi-platform CI/CD pipeline has been configured for building N-API native modules across 9+ platforms using GitHub Actions. This document describes the implementation, usage, and troubleshooting.

## What Was Implemented

### 1. GitHub Actions Workflow (`.github/workflows/build-napi.yml`)

**Features:**
- ✅ Matrix build for 9 platforms (macOS, Linux, Windows)
- ✅ Parallel execution with fail-fast disabled
- ✅ Docker-based builds for musl targets (Alpine)
- ✅ Comprehensive caching (Cargo registry, build artifacts, npm packages)
- ✅ Automated testing on native architectures
- ✅ Artifact management and retention
- ✅ npm publishing on releases
- ✅ GitHub Release asset creation
- ✅ Security scanning with npm audit

**Build Matrix:**

| Platform | Host Runner | Target Triple | Docker | Artifact Name |
|----------|-------------|---------------|--------|---------------|
| macOS Intel | macos-latest | x86_64-apple-darwin | No | agentic-jujutsu-darwin-x64 |
| macOS ARM | macos-latest | aarch64-apple-darwin | No | agentic-jujutsu-darwin-arm64 |
| Linux x64 | ubuntu-latest | x86_64-unknown-linux-gnu | No | agentic-jujutsu-linux-x64-gnu |
| Linux ARM64 | ubuntu-latest | aarch64-unknown-linux-gnu | No | agentic-jujutsu-linux-arm64-gnu |
| Linux ARMv7 | ubuntu-latest | armv7-unknown-linux-gnueabihf | No | agentic-jujutsu-linux-arm-gnueabihf |
| Alpine x64 | ubuntu-latest | x86_64-unknown-linux-musl | Yes | agentic-jujutsu-linux-x64-musl |
| Alpine ARM64 | ubuntu-latest | aarch64-unknown-linux-musl | Yes | agentic-jujutsu-linux-arm64-musl |
| Windows x64 | windows-latest | x86_64-pc-windows-msvc | No | agentic-jujutsu-win32-x64-msvc |
| Windows ARM64 | windows-latest | aarch64-pc-windows-msvc | No | agentic-jujutsu-win32-arm64-msvc |

### 2. Package Configuration (`package.json`)

**Updated sections:**

```json
{
  "napi": {
    "name": "agentic-jujutsu",
    "triples": {
      "defaults": true,
      "additional": [
        "x86_64-unknown-linux-musl",
        "aarch64-unknown-linux-musl",
        "aarch64-unknown-linux-gnu",
        "armv7-unknown-linux-gnueabihf",
        "aarch64-apple-darwin",
        "x86_64-pc-windows-msvc",
        "aarch64-pc-windows-msvc"
      ]
    }
  },
  "optionalDependencies": {
    "@jj-vcs/agentic-jujutsu-darwin-x64": "1.0.0",
    "@jj-vcs/agentic-jujutsu-darwin-arm64": "1.0.0",
    "@jj-vcs/agentic-jujutsu-linux-x64-gnu": "1.0.0",
    "@jj-vcs/agentic-jujutsu-linux-arm64-gnu": "1.0.0",
    "@jj-vcs/agentic-jujutsu-linux-arm-gnueabihf": "1.0.0",
    "@jj-vcs/agentic-jujutsu-win32-x64-msvc": "1.0.0",
    "@jj-vcs/agentic-jujutsu-win32-arm64-msvc": "1.0.0",
    "@jj-vcs/agentic-jujutsu-linux-x64-musl": "1.0.0",
    "@jj-vcs/agentic-jujutsu-linux-arm64-musl": "1.0.0"
  }
}
```

### 3. Platform Documentation (`docs/PLATFORMS.md`)

**Contents:**
- Complete platform support matrix
- Installation instructions
- Performance characteristics
- Troubleshooting guide
- Docker support
- Future platform plans

## Current Build Status

### ⚠️ Known Issues

The local build currently fails with Rust compilation errors:

1. **Import errors:**
   - `JJOperationInternal` unresolved import in `hooks.rs`
   - Should use `crate::operations::JJOperationInternal`

2. **Type mismatches:**
   - `Duration::from_millis()` expects `u64`, receiving `u32`
   - `timeout_ms` field type mismatch
   - `max_log_entries` expects `u32`, receiving `usize`

3. **N-API trait bounds:**
   - `u64` doesn't implement `ToNapiValue` / `FromNapiValue`
   - `JJDiff` doesn't implement `ToNapiValue`
   - Custom error types need conversion to `napi::Error`

### Required Fixes

Before the CI/CD pipeline can successfully build, these Rust code issues must be resolved:

**File: `src/hooks.rs` (Line 7)**
```rust
// Current (incorrect):
use crate::{JJOperation, JJOperationInternal, JJWrapper, OperationType, Result};

// Fix:
use crate::{JJOperation, JJWrapper, OperationType, Result};
use crate::operations::JJOperationInternal;
```

**File: `src/wrapper.rs` (Line 100)**
```rust
// Current (incorrect):
let timeout = std::time::Duration::from_millis(self.config.timeout_ms);

// Fix (cast to u64):
let timeout = std::time::Duration::from_millis(self.config.timeout_ms as u64);
```

**File: `src/config.rs` (Lines 102, 114)**
```rust
// Fix timeout_ms type:
self.timeout_ms = timeout_ms as u32;

// Fix max_log_entries type:
self.max_log_entries = max as u32;
```

**File: `src/operations.rs` (Line 280)**
```rust
// N-API doesn't support u64 directly, use BigInt or f64:
#[napi(object)]
pub struct JJOperationMetrics {
    // Change from u64 to f64 for N-API compatibility:
    pub duration_ms: f64,  // or use BigInt type
}
```

**File: `src/types.rs` and `src/wrapper.rs`**
```rust
// Add #[napi(object)] attribute to JJDiff struct:
#[napi(object)]
pub struct JJDiff {
    // ... fields
}

// Convert custom Result<T> to napi::Result<T>:
pub async fn diff(&self, from: String, to: String) -> napi::Result<JJDiff> {
    self.wrapper.diff(from, to)
        .await
        .map_err(|e| napi::Error::from_reason(e.to_string()))
}
```

## How to Use the CI/CD Pipeline

### Trigger Workflows

**1. Push to main or develop:**
```bash
git push origin main
# Triggers full build matrix
```

**2. Pull Request:**
```bash
git push origin feature-branch
gh pr create --title "Add feature" --body "Description"
# Triggers build and test verification
```

**3. Manual Trigger:**
```bash
# Via GitHub UI:
# Actions → Build N-API Native Modules → Run workflow

# Via gh CLI:
gh workflow run build-napi.yml
```

**4. Release:**
```bash
# Create release via GitHub UI or:
gh release create v1.0.1 --title "Release 1.0.1" --notes "Release notes"
# Triggers build, test, publish to npm, and GitHub release assets
```

### Monitor Builds

**Check workflow status:**
```bash
# List recent runs:
gh run list --workflow=build-napi.yml

# Watch specific run:
gh run watch <run-id>

# View logs:
gh run view <run-id> --log
```

**Download artifacts:**
```bash
# Download all artifacts from latest run:
gh run download --dir artifacts

# Download specific platform:
gh run download --name agentic-jujutsu-darwin-arm64
```

### Testing Locally

**Prerequisites:**
```bash
# Install Rust:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Node.js 18+:
# (Use nvm, asdf, or download from nodejs.org)

# Install N-API CLI:
npm install -g @napi-rs/cli
```

**Build for current platform:**
```bash
npm run build
ls -lh *.node
```

**Cross-compile (example for ARM64 on x64 Linux):**
```bash
# Install cross-compilation toolchain:
sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

# Add Rust target:
rustup target add aarch64-unknown-linux-gnu

# Build:
npm run build -- --target aarch64-unknown-linux-gnu
```

**Test build:**
```bash
npm run test:basic
```

## CI/CD Pipeline Architecture

### Workflow Jobs

```
┌─────────────────────────────────────────────────────────┐
│                     Build Matrix (9x)                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │  macOS   │  │  Linux   │  │ Windows  │             │
│  │  x64+ARM │  │ GNU+musl │  │  x64+ARM │             │
│  └──────────┘  └──────────┘  └──────────┘             │
│       ↓              ↓              ↓                   │
│  ┌─────────────────────────────────────┐               │
│  │    Upload Artifacts (9 packages)     │               │
│  └─────────────────────────────────────┘               │
└─────────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────┐
│               Test Build Artifacts                       │
│  • Download all 9 platform binaries                     │
│  • Verify file sizes and integrity                      │
│  • Validate .node module format                         │
└─────────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────┐
│            Parallel: Publish & Security                  │
│  ┌──────────────┐          ┌──────────────┐            │
│  │ Publish npm  │          │ Security Scan│            │
│  │ (on release) │          │ npm audit    │            │
│  └──────────────┘          └──────────────┘            │
└─────────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────┐
│        Create GitHub Release Assets (on release)         │
│  • Generate .tar.gz and .zip archives                   │
│  • Upload to GitHub Releases                            │
└─────────────────────────────────────────────────────────┘
```

### Caching Strategy

**1. Cargo Registry Cache:**
```yaml
~/.cargo/registry
~/.cargo/git
target/
Key: ${{ matrix.settings.target }}-cargo-${{ hashFiles('**/Cargo.lock') }}
```

**2. npm Cache:**
```yaml
~/.npm
Key: Managed by actions/setup-node@v4
```

**3. Build Artifacts:**
```yaml
Retention: 7 days
Upload: All .node files, index.js, index.d.ts
```

### Security Measures

**1. Dependency Scanning:**
- `npm audit` runs on every build
- Fails on moderate+ vulnerabilities
- Reports uploaded as artifacts

**2. Branch Protection:**
- Require PR reviews
- Require passing CI checks
- Restrict force pushes to main

**3. Secret Management:**
```yaml
Required Secrets:
- GITHUB_TOKEN (automatic)
- NPM_TOKEN (manual - for npm publish)
```

**4. Docker Security:**
- Official `ghcr.io/napi-rs` images
- Pinned to specific tags
- No privileged containers

## Required GitHub Secrets

### Setting Up Secrets

**1. NPM Token:**
```bash
# Generate token at https://www.npmjs.com/settings/<username>/tokens
# Type: Automation (for CI/CD publishing)

# Add to repository:
gh secret set NPM_TOKEN
# Paste token when prompted
```

**2. Verify secrets:**
```bash
gh secret list
```

### Secret Usage

```yaml
- name: Publish to npm
  run: npm publish --access public
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

## Performance Optimization

### Build Time Metrics

| Job | Duration | Parallelization |
|-----|----------|-----------------|
| Matrix builds (9x) | ~8-12 min | Fully parallel |
| Test artifacts | ~1-2 min | After builds complete |
| npm publish | ~2-3 min | On release only |
| Security scan | ~2-3 min | Parallel with publish |
| **Total (PR)** | **~8-12 min** | - |
| **Total (Release)** | **~15-20 min** | - |

### Optimization Techniques

**1. Fail-fast disabled:**
- All platforms build independently
- One failure doesn't stop others
- Maximizes artifact collection

**2. Aggressive caching:**
- Cargo registry cached per platform
- npm packages cached globally
- Rust target directory cached

**3. Conditional execution:**
- Testing skipped for cross-compiled ARM targets
- Publishing only on releases
- Security scan runs in parallel

**4. Docker optimization:**
- Pre-built napi-rs images
- Minimal Alpine base
- Volume mounts for source code

## Troubleshooting

### Build Failures

**Symptom:** Rust compilation errors

**Diagnosis:**
```bash
# Check error logs in GitHub Actions
gh run view <run-id> --log | grep "error\["

# Reproduce locally:
npm run build
```

**Solutions:**
1. Fix Rust code issues (see "Required Fixes" above)
2. Update dependencies: `cargo update`
3. Check Rust version: `rustc --version` (should be stable)

### Cross-Compilation Failures

**Symptom:** ARM64 build fails on x64 host

**Diagnosis:**
```bash
# Check if target is installed:
rustup target list --installed | grep aarch64

# Check if cross-compiler exists:
which aarch64-linux-gnu-gcc
```

**Solutions:**
```bash
# Install Rust target:
rustup target add aarch64-unknown-linux-gnu

# Install cross-compiler (Ubuntu/Debian):
sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

# Install cross-compiler (macOS):
brew install messense/macos-cross-toolchains/aarch64-unknown-linux-gnu
```

### Docker Build Issues

**Symptom:** musl builds fail in Docker

**Diagnosis:**
```bash
# Test Docker image locally:
docker run --rm -it ghcr.io/napi-rs/napi-rs/nodejs-rust:lts-alpine sh
```

**Solutions:**
1. Update Docker image tag
2. Check volume mounts in workflow
3. Verify file permissions in container

### npm Publish Failures

**Symptom:** Publishing to npm fails with auth error

**Diagnosis:**
```bash
# Verify NPM_TOKEN secret is set:
gh secret list | grep NPM_TOKEN

# Test token locally:
echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc
npm whoami
```

**Solutions:**
1. Regenerate npm token with Automation type
2. Update GitHub secret
3. Check package.json `publishConfig.access: "public"`

## Best Practices

### Workflow Maintenance

**1. Regular updates:**
```yaml
# Update action versions quarterly:
actions/checkout@v4 → v5
actions/setup-node@v4 → v5
dtolnay/rust-toolchain@stable → @v2
```

**2. Security patches:**
- Monitor Dependabot alerts
- Update Rust toolchain: `rustup update`
- Update npm packages: `npm update`

**3. Platform testing:**
- Test all platforms before releases
- Validate cross-compilation regularly
- Check Docker image availability

### Release Process

**Recommended workflow:**

1. **Prepare release:**
```bash
# Update version in Cargo.toml and package.json
npm version patch  # or minor/major

# Test local build
npm run build && npm test
```

2. **Create release branch:**
```bash
git checkout -b release/v1.0.1
git commit -am "chore: bump version to 1.0.1"
git push origin release/v1.0.1
```

3. **Create PR and verify CI:**
```bash
gh pr create --title "Release v1.0.1" --body "Release notes..."
# Wait for CI to pass
```

4. **Merge and create GitHub release:**
```bash
git checkout main
git merge release/v1.0.1
gh release create v1.0.1 --title "v1.0.1" --notes "Release notes..."
# CI automatically publishes to npm and creates release assets
```

5. **Verify publication:**
```bash
npm view agentic-jujutsu version
npm info agentic-jujutsu
```

## Advanced Configuration

### Custom Build Flags

Modify build command in workflow:

```yaml
build: |
  RUSTFLAGS="-C target-cpu=native -C opt-level=3" \
  npm run build -- --target x86_64-unknown-linux-gnu
```

### Additional Platforms

Add new platform to matrix:

```yaml
- host: ubuntu-latest
  target: riscv64gc-unknown-linux-gnu
  docker: ghcr.io/riscv-cross-toolchains/riscv64
  build: npm run build -- --target riscv64gc-unknown-linux-gnu
  artifact: agentic-jujutsu-linux-riscv64
```

### Conditional Publishing

Publish to different registries:

```yaml
- name: Publish to GitHub Packages
  if: github.event_name == 'release' && contains(github.ref, 'alpha')
  run: npm publish --registry https://npm.pkg.github.com
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Monitoring and Observability

### Metrics to Track

**Build metrics:**
- Build duration per platform
- Cache hit rates
- Artifact sizes
- Failure rates

**Release metrics:**
- Time from commit to npm
- Number of successful platforms
- Download counts per platform

### Alerts

Set up GitHub Actions status checks:

```bash
# Create status check requirement:
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --field required_status_checks.strict=true \
  --field required_status_checks.contexts[]="Build x86_64-apple-darwin"
```

## Documentation

Related documentation:
- [Platform Support Matrix](./PLATFORMS.md)
- [Build Status](./BUILD_STATUS.md)
- [CI/CD Setup](./CI_CD_SETUP.md)
- [GitHub Secrets](./GITHUB_SECRETS.md)

## Support

For CI/CD issues:
1. Check GitHub Actions logs
2. Review [GitHub Issues](https://github.com/ruvnet/agentic-flow/issues)
3. Contact: team@ruv.io

---

**Status:** ⚠️ Workflow configured, Rust code fixes required
**Last Updated:** 2025-11-10
**Workflow Version:** 1.0
**Platforms:** 9 (macOS, Linux, Windows)