syntaxis/docs/pack.md

# SYNTAXIS Provisioning System

Complete reference for the SYNTAXIS provisioning and bundling system.

## Overview

The provisioning system creates self-contained distribution bundles that users can extract and install without internet or external dependencies.

**Key Features:**
- Multi-platform support (Linux, macOS, Windows)
- Optional orchestration with `provision` script (install + config)
- Traditional installers for each step (install.sh, setup-config.sh)
- SHA256 checksums for integrity verification
- Manifest metadata for bundle contents

---

## Bundle Structure

Each bundle contains everything needed for installation:

```
syntaxis-v0.1.0-<target>/
├── README.md              # Bundle overview
├── QUICK_START.md         # 5-minute guide
├── docs/installation.md             # Installation reference
├── provision              # Master provisioner (recommended)
├── install.sh             # Bash installer (optional)
├── install.nu             # NuShell installer (optional)
├── setup-config.sh        # Configuration helper
├── manifest.toml          # Bundle metadata
│
├── bin/                   # Compiled binaries
│   ├── syntaxis-cli
│   ├── syntaxis-tui
│   └── syntaxis-api
│
├── configs/               # Configuration templates
│   ├── database-default.toml
│   ├── database-surrealdb.toml
│   ├── syntaxis-cli.toml
│   └── ... (more configs)
│
└── docs/                  # Additional documentation
    ├── CONFIG.md          # Configuration guide
    └── TROUBLESHOOTING.md # Common issues
```

---

## Installation Flows

### 1. Recommended: Master Provisioner (One Command)

```bash
./provision full         # Install + configure everything
./provision install      # Just install binaries
./provision config       # Just configure
./provision              # Interactive menu
```

**Advantages:**
- Single command for full setup
- Interactive menu for guidance
- Automatic shell detection
- One-step configuration

### 2. Traditional: Step-by-Step

```bash
# Step 1: Install binaries
bash install.sh --interactive

# Step 2: Configure
bash setup-config.sh --interactive
```

**Advantages:**
- Full control over each step
- Can skip configuration if desired
- Traditional installer experience

### 3. NuShell Users

```bash
nu install.nu --prefix ~/.local
nu setup-config.sh --interactive
```

**Advantages:**
- Better compatibility with NuShell shells
- Exact same functionality as bash

### 4. Manual

```bash
# Copy files manually, set permissions, update PATH
# See docs/installation.md for details
```

**Advantages:**
- Maximum control
- Works anywhere
- No dependencies

---

## Provisioning Configuration

The provisioning system is configured in `configs/provisioning.toml`:

### Targets

Defines supported platforms and formats:

```toml
[targets.x86_64-unknown-linux-gnu]
enabled = true
os = "linux"
arch = "x86_64"
libc = "glibc"
formats = ["tar.gz", "deb"]
```

### Artifacts

Specifies what goes into bundles:

```toml
[artifacts]
binaries = [
    { name = "syntaxis-cli", crate = "cli", description = "..." },
    ...
]

configs = [
    "configs/database-default.toml",
    ...
]

docs = [
    "docs/BUNDLE_README.md",    # Becomes README.md at root
    "docs/docs/installation.md",          # Root level
    "docs/QUICK_START.md",      # Root level
    "docs/CONFIG.md",           # In docs/
    "docs/TROUBLESHOOTING.md",  # In docs/
]

scripts = [
    "scripts/provisioning/provision.sh",     # Master provisioner
    "scripts/provisioning/install.sh",       # Bash installer
    "scripts/provisioning/install.nu",       # NuShell installer
    "scripts/provisioning/setup-config.sh",  # Configuration
]
```

---

## Pack Workflow

### Creating Bundles

```bash
# For current platform
nu scripts/provisioning/pack.nu

# For specific target
nu scripts/provisioning/pack.nu --target x86_64-unknown-linux-gnu

# Different formats
nu scripts/provisioning/pack.nu --format zip

# Verify after creation
nu scripts/provisioning/pack.nu --verify

# Dry run to preview
nu scripts/provisioning/pack.nu --dry-run
```

### Pack Process

1. **Validate Configuration** - Check provisioning.toml
2. **Build Binaries** - Compile for target platform
3. **Collect Artifacts** - Find all files to bundle
   - Binaries from target/release/
   - Configs from configs/
   - Docs from docs/
   - Scripts from scripts/provisioning/
4. **Create Bundle**
   - Create staging directory with structure
   - Copy binaries to bin/
   - Copy configs to configs/ (preserving structure)
   - Copy docs (special placement for README, QUICK_START, INSTALL)
   - Copy scripts to root level (executable)
5. **Generate Manifest** - Create manifest.toml with artifact list
6. **Calculate Checksums** - SHA256 for all files
7. **Create Archive** - tar.gz or zip file
8. **Cleanup** - Remove staging directory

### Output Files

```bash
dist/
├── syntaxis-v0.1.0-aarch64-apple-darwin.tar.gz    # Bundle
├── syntaxis-v0.1.0-aarch64-apple-darwin.checksums.toml  # Checksums
```

---

## Manifest Format

Each bundle includes `manifest.toml` with metadata:

```toml
[bundle]
version = "0.1.0"
target = "aarch64-apple-darwin"
created_at = "2025-11-17T19:31:23Z"
format = "tar.gz"

[artifacts]
binaries = ["syntaxis-cli", "syntaxis-tui", "syntaxis-api"]
configs = ["database-default.toml", ...]
docs = ["BUNDLE_README.md", "docs/installation.md", ...]
scripts = ["provision.sh", "install.sh", ...]

[checksums]
"bin/syntaxis-cli" = "sha256hash..."
"README.md" = "sha256hash..."
...
```

---

## Script Descriptions

### provision (Master Orchestrator)

**Purpose:** Coordinate complete installation + configuration

**Features:**
- Detects available shells (bash/zsh or NuShell)
- Offers interactive menu
- Runs install → configure sequence
- Handles PATH setup automatically

**Usage:**
```bash
./provision             # Interactive menu
./provision full        # Install + configure (automatic)
./provision install     # Just install
./provision config      # Just configure
./provision help        # Show help
```

### install.sh (Bash Installer)

**Purpose:** Install binaries to system

**Features:**
- Interactive or unattended modes
- Backup existing binaries
- Verify checksums
- Dry-run mode
- Custom installation prefix

**Usage:**
```bash
bash install.sh --interactive
bash install.sh --prefix ~/.local --dry-run
```

### install.nu (NuShell Installer)

**Purpose:** Alternative installer for NuShell users

**Equivalent to:** install.sh but using NuShell

**Usage:**
```bash
nu install.nu --prefix ~/.local
```

### setup-config.sh (Configuration Helper)

**Purpose:** Create initial TOML configurations

**Features:**
- Interactive mode (choose which to configure)
- Automatic mode (configure all)
- Sensible defaults
- Custom config directory

**Usage:**
```bash
bash setup-config.sh --interactive
bash setup-config.sh  # Auto-configure all
```

---

## Building Bundles

### Prerequisites

```bash
# Need Rust toolchain
rustup target add x86_64-unknown-linux-gnu aarch64-apple-darwin

# Need NuShell for pack.nu
# See: https://www.nushell.sh/book/installation.html
```

### Build for All Targets

```bash
# Single platform (current system)
nu scripts/provisioning/pack.nu

# Linux x86_64
nu scripts/provisioning/pack.nu --target x86_64-unknown-linux-gnu

# macOS Apple Silicon
nu scripts/provisioning/pack.nu --target aarch64-apple-darwin

# Windows
nu scripts/provisioning/pack.nu --target x86_64-pc-windows-msvc
```

### Build with Verification

```bash
# Include integrity check
nu scripts/provisioning/pack.nu --verify

# Show what would happen
nu scripts/provisioning/pack.nu --dry-run
```

---

## Distribution

### Sharing Bundles

1. **Create bundle** with `pack.nu`
2. **Share these files:**
   ```
   syntaxis-v0.1.0-<target>.tar.gz      (Main bundle)
   syntaxis-v0.1.0-<target>.checksums.toml  (Optional, for verification)
   ```
3. **User extracts and runs** `./provision full`

### Verification

Users can verify bundle integrity:

```bash
# Verify all checksums
sha256sum -c syntaxis-v0.1.0-*.checksums.toml
```

---

## Customization

### Changing What's Included

Edit `configs/provisioning.toml`:

```toml
[artifacts]
# Add/remove files here

docs = [
    "docs/your-file.md",    # Included in bundle
]

scripts = [
    "scripts/provisioning/custom.sh",  # Added to bundle
]
```

### Custom Installation Scripts

Replace install.sh or create new ones:

```bash
# Edit scripts/provisioning/install.sh
# Update provisioning.toml to reference it
```

### Custom Documentation

Add to `docs/` and reference in provisioning.toml.

---

## Troubleshooting

### Bundle Creation Fails

```bash
# Check config syntax
cat configs/provisioning.toml | nu -c 'open --raw - | from toml'

# Verify files exist
ls docs/BUNDLE_README.md
ls scripts/provisioning/provision.sh

# Check build
cargo build --release
```

### Missing Files in Bundle

```bash
# Verify artifact paths in provisioning.toml
# Paths are relative to repository root

# Check pack.nu logic
nu scripts/provisioning/pack.nu --dry-run
```

### Installation Script Fails

```bash
# Make scripts executable
chmod +x scripts/provisioning/*.sh

# Test in isolation
bash scripts/provisioning/install.sh --help
```

---

## Related Documentation

- **README.md** - Project overview
- **docs/installation.md** - User installation guide
- **CONFIG.md** - Configuration reference
- **TROUBLESHOOTING.md** - Common user issues

---

**SYNTAXIS** v0.1.0 • [syntaxis.dev](https://syntaxis.dev)