# syntaxis Provisioning Quick Reference

Fast reference for provisioning, distribution, and CI/CD commands.

## Local Development

### Create Bundle (Current Platform)
```bash
nu scripts/provisioning/pack.nu
# Output: dist/syntaxis-v0.1.0-x86_64-linux.tar.gz
```

### Create Bundle (Specific Platform)
```bash
nu scripts/provisioning/pack.nu --target aarch64-apple-darwin --output dist/
```

### List Available Targets
```bash
nu scripts/provisioning/pack.nu --list-targets
```

### Dry Run (Preview)
```bash
nu scripts/provisioning/pack.nu --dry-run
```

### Install from Bundle (Complete)
```bash
nu scripts/provisioning/provctl.nu full-install --bundle bundle.tar.gz
```

### Install Binaries Only
```bash
tar -xzf bundle.tar.gz
cd syntaxis-v0.1.0-*
nu scripts/provisioning/install.nu --source ./bin --prefix ~/.local
```

### Deploy Configs Only
```bash
nu scripts/provisioning/deploy.nu --source ./bundle/configs
```

### Check Installation Status
```bash
nu scripts/provisioning/provctl.nu status
```

### Verify Bundle Integrity
```bash
nu scripts/provisioning/provctl.nu verify-bundle --bundle bundle.tar.gz
```

## Bash Installer (Offline)

For systems without NuShell installed:

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

# Interactive installation
cd syntaxis-v0.1.0-*
./install.sh

# Verify before installing
./install.sh --verify

# Install to custom location
./install.sh --prefix /opt/syntaxis

# Force overwrite without prompts
./install.sh --force --no-backup

# Dry run to preview
./install.sh --dry-run

# Unattended mode
./install.sh --unattended --prefix ~/.local
```

## GitHub Releases

### Create Release (Local)
```bash
# 1. Tag your release
git tag v0.2.0
git push origin v0.2.0

# 2. GitHub Actions automatically:
#    - Builds all 5 platforms
#    - Creates bundles
#    - Generates checksums
#    - Creates GitHub Release
#    - Publishes documentation
```

### Download from Release
```bash
# Get latest bundle for your platform
curl -L https://github.com/syntaxis/syntaxis/releases/latest/download/syntaxis-x86_64-linux-v0.1.0.tar.gz -o bundle.tar.gz

# Verify checksums
sha256sum -c SHA256SUMS

# Install
tar -xzf bundle.tar.gz
cd syntaxis-*
./install.sh
```

## Provisioning Configuration

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

### Key Sections
- `[targets]` - Platforms to build (x86_64-linux, aarch64-macos, etc.)
- `[artifacts]` - What to include (binaries, configs, docs)
- `[packaging]` - Format options (tar.gz, zip, deb, rpm)
- `[build]` - Cargo build options (release, optimization)
- `[bundle]` - Bundle structure and manifest

### Modify Configuration
```bash
nano configs/provisioning.toml
```

## Workflows

### Build Workflow (On Every Commit)
- **File**: `.github/workflows/build.yml`
- **Triggers**: Push to main/develop, all PRs
- **Jobs**: Format, lint, test, check, audit, builds
- **Artifacts**: Debug/release binaries (Ubuntu, macOS, Windows)

### Release Workflow (On Version Tag)
- **File**: `.github/workflows/release.yml`
- **Triggers**: Push tags (v*)
- **Jobs**: Multi-platform builds, bundle creation, GitHub release
- **Artifacts**: bundles, checksums, documentation

## Utilities

### Detect Platform
```bash
use scripts/provisioning/common/platform.nu

current-target              # Get current platform target
detect-os                   # Get OS: linux, macos, windows
detect-arch                 # Get arch: x86_64, aarch64
available-targets config    # List enabled targets
```

### Manifest Operations
```bash
use scripts/provisioning/common/manifest.nu

load manifest.toml          # Read manifest
create version target fmt   # Create new manifest
validate manifest            # Check manifest validity
info manifest.toml          # Display manifest info
```

### Validation
```bash
use scripts/provisioning/common/validate.nu

sha256 file                 # Calculate checksum
generate-checksums dir      # Batch checksums
verify-checksums file dir   # Verify all checksums
validate-bundle-structure   # Check bundle format
validate-config file        # Check provisioning.toml
```

## Manifests

### Installation Manifest
Location: `~/.syntaxis/manifest.toml`
Created by: `install.nu`
Contains: Installed binaries, timestamps, installation prefix

### Deployment Manifest
Location: `~/.syntaxis/deployment.toml`
Created by: `deploy.nu`
Contains: Deployed configs, timestamps, config directory

### Bundle Manifest
Location: Inside bundle: `manifest.toml`
Created by: `pack.nu`
Contains: Bundle metadata, artifact list, checksums

## Environment Variables

```bash
# Configuration directory
export SYNTAXIS_CONFIG_DIR=~/.config/syntaxis

# Data directory
export SYNTAXIS_DATA_DIR=~/.local/share/syntaxis

# Provisioning config
export PROVISIONING_CONFIG=configs/provisioning.toml
```

## Common Tasks

### Build & Test Locally
```bash
# 1. Build
cargo build --release

# 2. Create bundle
nu scripts/provisioning/pack.nu --verify

# 3. Test install
mkdir -p /tmp/test-install
nu scripts/provisioning/provctl.nu full-install \
  --bundle dist/*.tar.gz \
  --prefix /tmp/test-install

# 4. Verify
/tmp/test-install/bin/syntaxis-cli --version
```

### Prepare Release
```bash
# 1. Test all checks
cargo test --all
cargo clippy --all-targets
cargo fmt --all
cargo audit

# 2. Create and push tag
git tag v0.2.0
git push origin v0.2.0

# 3. Wait for CI/CD to complete
# 4. Check GitHub Releases page
```

### Install for Development
```bash
# Unattended install to ~/.local
nu scripts/provisioning/provctl.nu full-install \
  --bundle dist/syntaxis-v0.1.0-*.tar.gz \
  --prefix ~/.local \
  --verify

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Verify
syntaxis-cli --version
```

### Upgrade Existing Installation
```bash
# Download new bundle
curl -O https://github.com/syntaxis/syntaxis/releases/download/v0.2.0/bundle.tar.gz

# Install with backup
nu scripts/provisioning/provctl.nu full-install --bundle bundle.tar.gz

# Verify new version
syntaxis-cli --version
```

### Deploy to Multiple Machines
```bash
#!/bin/bash
# distribute.sh

BUNDLE="$1"
SERVERS=("server1" "server2" "server3")

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

## Scripts Location

```
scripts/provisioning/
├── pack.nu              # Create bundles
├── unpack.nu            # Extract bundles
├── install.nu           # Install binaries
├── deploy.nu            # Deploy configs
├── provctl.nu           # Orchestrator
├── install.sh           # Bash offline installer
├── common/
│   ├── platform.nu      # Platform detection
│   ├── manifest.nu      # Manifest handling
│   └── validate.nu      # Integrity checking
└── README.md            # Full documentation
```

## Troubleshooting

### Bundle creation fails
```bash
# Check if binaries are built
ls target/release/syntaxis-*

# Run build first if needed
cargo build --release

# Try with dry-run
nu scripts/provisioning/pack.nu --dry-run
```

### Installation fails
```bash
# Check permissions
ls -la ~/.local/bin
ls -la ~/.config/syntaxis

# Try with sudo (not recommended)
# Or install to different prefix
./install.sh --prefix ~/local-install

# Check manifest
cat ~/.syntaxis/manifest.toml
```

### Checksum mismatch
```bash
# Download new checksums
curl -O https://github.com/.../SHA256SUMS

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

# If still fails, bundle may be corrupted
rm bundle.tar.gz && wget ... # re-download
```

## Key Files

| File | Purpose |
|------|---------|
| `configs/provisioning.toml` | Provisioning configuration |
| `scripts/provisioning/` | Provisioning scripts (pack, install, etc) |
| `.github/workflows/build.yml` | Continuous integration |
| `.github/workflows/release.yml` | Release automation |
| `docs/provisioning.md` | Complete provisioning guide |
| `scripts/provisioning/README.md` | Detailed provisioning docs |

## Documentation

- **Full Guide**: See `docs/provisioning.md`
- **Provisioning System**: See `scripts/provisioning/README.md`
- **Project Guide**: See `CLAUDE.md`
- **Quick Start**: See `README.md`

---

**Last Updated**: 2025-11-17
**Version**: 0.1.0