syntaxis/docs/provisioning.md

# syntaxis Provisioning & Distribution Guide

Complete guide to building, packaging, and distributing syntaxis using the modular provisioning system and automated CI/CD.

## Overview

The syntaxis project includes a **complete distribution pipeline**:

```
┌─────────────────┐
│  Source Code    │
└────────┬────────┘
         │
    ┌────▼────────────────────┐
    │  Local Development      │
    │  (pack.nu via scripts)  │
    └────┬──────────┬─────────┘
         │          │
    ┌────▼───┐  ┌───▼──────────┐
    │ Bundle │  │ GitHub Tags  │
    │ (local)│  │ (trigger CI) │
    └────┬───┘  └───┬──────────┘
         │          │
         │    ┌─────▼────────────────────┐
         │    │ GitHub Actions CI/CD     │
         │    │ (.github/workflows/)     │
         │    └─────┬──────────┬─────────┘
         │          │          │
         │    ┌─────▼────┐  ┌──▼────────┐
         │    │ Multi-   │  │ Auto-     │
         │    │ platform │  │ Release   │
         │    │ builds   │  │ on GitHub │
         │    └─────┬────┘  └──┬────────┘
         │          │          │
         └──────────┬──────────┘
                    │
            ┌───────▼────────┐
            │ User Downloads │
            │ & Installs     │
            └────────────────┘
```

## Quick Start

### For Developers (Build & Test Locally)

```bash
# 1. View available targets
nu scripts/provisioning/pack.nu --list-targets

# 2. Create bundle for your platform
nu scripts/provisioning/pack.nu

# 3. Bundle appears in: dist/syntaxis-v0.1.0-x86_64-linux.tar.gz

# 4. Test installation locally
nu scripts/provisioning/provctl.nu full-install --bundle dist/*.tar.gz --prefix ~/.local-test

# 5. Test the binaries
~/.local-test/bin/syntaxis-cli --version
```

### For CI/CD (Automated Releases)

1. **Make changes and commit** to `main` or `develop` branch
2. **Create a tag** to trigger release:
   ```bash
   git tag v0.2.0
   git push origin v0.2.0
   ```
3. **GitHub Actions automatically:**
   - Builds binaries for all 5 platforms
   - Creates bundles with configs and docs
   - Generates checksums
   - Creates GitHub Release with downloads
   - Publishes documentation

## Workflows

### GitHub Actions Workflows

Two main workflows are provided:

#### 1. `build.yml` - Continuous Integration
Runs on **every push to main/develop** and **all pull requests**:

- ✅ Code formatting check (`cargo fmt`)
- ✅ Linting (`cargo clippy`)
- ✅ Unit tests (`cargo test`)
- ✅ Build check (`cargo check`)
- ✅ Security audit (`cargo audit`)
- ✅ Debug builds on all platforms (Linux, macOS, Windows)
- ✅ Release builds on main branch

**When to check build artifacts:**
- Go to workflow run → Artifacts
- Download `release-ubuntu-latest`, `release-macos-latest`, or `release-windows-latest`

#### 2. `release.yml` - Release & Distribution
Runs **on git tags** (when you push `v*` tag):

- 🔨 Builds for 5 platforms in parallel
- 📦 Creates self-contained bundles
- 📋 Generates manifests and checksums
- 🚀 Creates GitHub Release
- 📄 Publishes documentation
- 🔗 Generates release notes

**Platforms built:**
1. Linux x86_64 (glibc) - Ubuntu latest
2. Linux ARM64 (aarch64) - Via cross-compilation
3. macOS Intel (x86_64) - macOS latest
4. macOS Apple Silicon (aarch64) - macOS latest
5. Windows x86_64 (MSVC) - Windows latest

## Distribution Methods

### Method 1: GitHub Releases (Recommended for End Users)

**For users:**
```bash
# Download latest release
curl -L https://github.com/syntaxis/syntaxis/releases/latest/download/syntaxis-x86_64-linux-v0.1.0.tar.gz -o bundle.tar.gz

# Verify integrity
curl -L https://github.com/syntaxis/syntaxis/releases/latest/download/SHA256SUMS | sha256sum -c -

# Install
tar -xzf bundle.tar.gz
cd syntaxis-v0.1.0-x86_64-linux
./install.sh
```

### Method 2: Package Managers (Homebrew, apt, etc.)

**For macOS (Homebrew) - Future implementation:**
```bash
brew install syntaxis/syntaxis/syntaxis
```

**For Linux (Debian/Ubuntu) - Future implementation:**
```bash
sudo apt-get install syntaxis
```

### Method 3: Container/Docker

**For containerized deployments - Future implementation:**
```bash
docker pull syntaxis:latest
docker run -p 3000:3000 syntaxis:latest
```

### Method 4: Manual Build from Source

**For developers and advanced users:**
```bash
# Clone repository
git clone https://github.com/syntaxis/syntaxis.git
cd syntaxis

# Build locally
cargo build --release

# Create bundle
nu scripts/provisioning/pack.nu --output dist/

# Install from bundle
nu scripts/provisioning/provctl.nu full-install --bundle dist/*.tar.gz
```

## Creating a Release

### Step-by-Step Guide

1. **Ensure everything is committed:**
   ```bash
   git status  # Should be clean
   ```

2. **Run full test suite:**
   ```bash
   cargo test --all
   cargo clippy --all-targets
   cargo fmt --all
   cargo audit
   ```

3. **Update version numbers** (if needed):
   - `Cargo.toml` (workspace)
   - `configs/provisioning.toml`
   - Documentation if applicable

4. **Create and push tag:**
   ```bash
   # Semantic versioning: MAJOR.MINOR.PATCH
   git tag v0.2.0

   # Push to GitHub (triggers release workflow)
   git push origin v0.2.0
   ```

5. **Wait for GitHub Actions:**
   - Go to https://github.com/syntaxis/syntaxis/actions
   - Watch `release.yml` workflow
   - Builds will run in parallel for all 5 platforms (~10-15 minutes)

6. **Check Release:**
   - Go to Releases: https://github.com/syntaxis/syntaxis/releases
   - New release `v0.2.0` should appear
   - Contains bundles, checksums, and release notes

## Installing from Different Sources

### From GitHub Release (Online)

```bash
# Detect your platform automatically
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/aarch64/aarch64/;s/x86_64/x86_64/')

# Download
VERSION="0.1.0"
BUNDLE="syntaxis-${ARCH}-${OS}-v${VERSION}.tar.gz"
curl -L "https://github.com/syntaxis/syntaxis/releases/download/v${VERSION}/${BUNDLE}" -o /tmp/bundle.tar.gz

# Install
tar -xzf /tmp/bundle.tar.gz -C /tmp
/tmp/syntaxis-*/install.sh --prefix ~/.local
```

### From Local Bundle (Offline)

```bash
# Unpack bundle
tar -xzf bundle.tar.gz

# Install with verification
cd syntaxis-v0.1.0-*
./install.sh --verify --prefix ~/.local

# Or use NuShell provisioning commands
provctl full-install --bundle ../../bundle.tar.gz
```

### From Source with Custom Build

```bash
# Build for specific target
cargo build --release --target aarch64-apple-darwin

# Create bundle for that target
nu scripts/provisioning/pack.nu --target aarch64-apple-darwin --output dist/

# Share bundle with others
scp dist/syntaxis-v0.1.0-aarch64-darwin.tar.gz user@remote:/tmp/
```

## Bundle Verification

### Verify Download Integrity

```bash
# Download checksums file
curl -O https://github.com/syntaxis/syntaxis/releases/download/v0.1.0/SHA256SUMS

# Verify bundle
sha256sum -c SHA256SUMS --ignore-missing

# Or with individual checksum
EXPECTED=$(grep 'syntaxis-x86_64-linux' SHA256SUMS | awk '{print $1}')
ACTUAL=$(sha256sum syntaxis-x86_64-linux-v0.1.0.tar.gz | awk '{print $1}')

if [[ "$EXPECTED" == "$ACTUAL" ]]; then
    echo "✅ Integrity verified"
else
    echo "❌ Checksum mismatch - bundle may be corrupted"
fi
```

### Verify Bundle Contents

```bash
# Extract and inspect
tar -tzf bundle.tar.gz | head -20

# Check manifest
tar -xzOf bundle.tar.gz syntaxis-v0.1.0-x86_64-linux/manifest.toml

# Dry run installation to see what would be installed
./bundle/install.sh --dry-run
```

## Provisioning Configuration

All provisioning behavior is controlled by `configs/provisioning.toml`:

### Key Sections

```toml
[targets]
# Define which platforms to build for
# Example: x86_64-unknown-linux-gnu, aarch64-apple-darwin, etc.

[artifacts]
# What gets included in bundles
binaries = [...]
configs = [...]
docs = [...]

[packaging]
# How to package for each format
tar_gz, zip, deb, rpm

[build]
# Cargo build options
release = true
opt_level = 3
lto = "thin"
```

## Troubleshooting

### Release workflow fails

1. **Check GitHub Actions logs:**
   - Go to https://github.com/syntaxis/syntaxis/actions/workflows/release.yml
   - Click failed run
   - Expand failed job for error details

2. **Common issues:**
   - **"tag already exists"** - Delete and recreate: `git tag -d v0.1.0 && git push origin :v0.1.0`
   - **"build failed"** - Check local build: `cargo build --release`
   - **"permission denied"** - Ensure `install.sh` is executable: `chmod +x scripts/provisioning/install.sh`

### Installation fails

1. **Check bundle integrity:**
   ```bash
   ./install.sh --verify --dry-run
   ```

2. **Check write permissions:**
   ```bash
   ls -la ~/.local/bin
   ls -la ~/.config/syntaxis
   ```

3. **Check manifest:**
   ```bash
   cat ~/.syntaxis/manifest.toml
   ```

### Bundle structure invalid

```bash
# Verify bundle structure
tar -tzf bundle.tar.gz | grep -E '(bin|configs|docs|manifest)'

# Should see:
# syntaxis-v0.1.0-x86_64-linux/manifest.toml
# syntaxis-v0.1.0-x86_64-linux/bin/syntaxis-cli
# syntaxis-v0.1.0-x86_64-linux/configs/...
# syntaxis-v0.1.0-x86_64-linux/docs/...
```

## Automation Examples

### Example 1: Build Bundle for Distribution

```bash
#!/bin/bash
# build-release.sh - Create distribution bundles locally

set -e

VERSION="0.1.0"
OUTPUT_DIR="dist/v${VERSION}"
mkdir -p "$OUTPUT_DIR"

echo "📦 Building distribution bundles..."

# Build for all targets
for target in x86_64-unknown-linux-gnu aarch64-apple-darwin x86_64-apple-darwin x86_64-pc-windows-msvc; do
    echo "  Building: $target"
    nu scripts/provisioning/pack.nu --target "$target" --output "$OUTPUT_DIR" --verify
done

echo ""
echo "✅ Bundles created in: $OUTPUT_DIR"
ls -lh "$OUTPUT_DIR"
```

### Example 2: Distribute to Team

```bash
#!/bin/bash
# distribute-to-team.sh - Deploy bundles to team infrastructure

BUNDLE="$1"
SERVERS=("dev-server-1" "dev-server-2" "staging-server")

for server in "${SERVERS[@]}"; do
    echo "🚀 Deploying to: $server"
    scp "$BUNDLE" "deploy@$server:/tmp/"
    ssh "deploy@$server" "
        cd /tmp
        tar -xzf $(basename $BUNDLE)
        ./syntaxis-*/install.sh --force --prefix /opt/syntaxis
    "
done

echo "✅ Deployment complete"
```

### Example 3: Test Installation Locally

```bash
#!/bin/bash
# test-install.sh - Test installation in clean environment

BUNDLE="$1"
TEST_DIR="/tmp/syntaxis-test-$$"

mkdir -p "$TEST_DIR"
cd "$TEST_DIR"

echo "🧪 Testing installation: $BUNDLE"
tar -xzf "$BUNDLE"
cd syntaxis-v*

# Test 1: Dry run
echo "  Test 1: Dry run..."
./install.sh --dry-run

# Test 2: Verify checksums
echo "  Test 2: Verify checksums..."
./install.sh --verify --dry-run

# Test 3: Install to test directory
echo "  Test 3: Install to test prefix..."
./install.sh --prefix "$TEST_DIR/install" --unattended --force

# Test 4: Run binaries
echo "  Test 4: Run binaries..."
$TEST_DIR/install/bin/syntaxis-cli --version
$TEST_DIR/install/bin/syntaxis-tui --help || true

echo "✅ All tests passed"
cleanup() { rm -rf "$TEST_DIR"; }
trap cleanup EXIT
```

## Next Steps

### Enhance Distribution

- [ ] Create Homebrew formula for macOS distribution
- [ ] Generate deb/rpm packages for Linux distributions
- [ ] Create Docker images for containerized deployment
- [ ] Set up artifact repository (artifactory, nexus, etc.)
- [ ] Implement auto-update mechanism in binaries
- [ ] Create installation wizard (TUI for first-time setup)

### Improve CI/CD

- [ ] Add code coverage reporting
- [ ] Implement semantic versioning auto-bumping
- [ ] Add automatic changelog generation
- [ ] Set up automated deployments to staging
- [ ] Add performance benchmarking
- [ ] Implement canary deployments

### Expand Documentation

- [ ] Create installation video tutorials
- [ ] Add troubleshooting guide
- [ ] Document configuration examples
- [ ] Create case studies
- [ ] Build quick-start templates

## References

- **Provisioning System**: See `scripts/provisioning/README.md`
- **Configuration**: See `configs/provisioning.toml`
- **Installation Script**: See `scripts/provisioning/install.sh`
- **Workflows**: See `.github/workflows/`
- **Project Guide**: See `CLAUDE.md`

## Support

- 📖 **Documentation**: https://github.com/syntaxis/syntaxis
- 🐛 **Issues**: https://github.com/syntaxis/syntaxis/issues
- 💬 **Discussions**: https://github.com/syntaxis/syntaxis/discussions
- 📧 **Email**: support@syntaxis.dev

---

**Last Updated**: 2025-11-17
**Status**: Complete - Ready for distribution
**Version**: 0.1.0