syntaxis/.github/PROVISIONING_QUICK_REFERENCE.md

syntaxis Provisioning Quick Reference

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

Local Development

Create Bundle (Current Platform)

nu scripts/provisioning/pack.nu
# Output: dist/syntaxis-v0.1.0-x86_64-linux.tar.gz

Create Bundle (Specific Platform)

nu scripts/provisioning/pack.nu --target aarch64-apple-darwin --output dist/

List Available Targets

nu scripts/provisioning/pack.nu --list-targets

Dry Run (Preview)

nu scripts/provisioning/pack.nu --dry-run

Install from Bundle (Complete)

nu scripts/provisioning/provctl.nu full-install --bundle bundle.tar.gz

Install Binaries Only

tar -xzf bundle.tar.gz
cd syntaxis-v0.1.0-*
nu scripts/provisioning/install.nu --source ./bin --prefix ~/.local

Deploy Configs Only

nu scripts/provisioning/deploy.nu --source ./bundle/configs

Check Installation Status

nu scripts/provisioning/provctl.nu status

Verify Bundle Integrity

nu scripts/provisioning/provctl.nu verify-bundle --bundle bundle.tar.gz

Bash Installer (Offline)

For systems without NuShell installed:

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

# 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

# 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

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

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

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

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

# 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

# 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

# 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

# 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

# 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

#!/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

# 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

# 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

# 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