archy/.cursor/rules/Development-Workflow.mdc

# Archipelago Development Workflow

## Overview

Development happens on Mac (editing in Cursor), with the HP ProDesk running Archipelago as the live test target via SSH.

## Architecture

```
┌─────────────────────┐         SSH/rsync          ┌─────────────────────┐
│   Mac (Dev Host)    │ ──────────────────────────▶│  HP ProDesk (Target)│
│                     │                            │                     │
│  • Cursor IDE       │                            │  • Archipelago OS   │
│  • Source code      │                            │  • Live testing     │
│  • ISO builds       │                            │  • Vue.js dev server│
│                     │                            │  • Rust backend     │
└─────────────────────┘                            └─────────────────────┘
```

## Target Machine Setup

**SSH Access:**
```bash
ssh archipelago@192.168.1.228
# Password: archipelago
```

**Required packages on target (install once):**
```bash
sudo apt update && sudo apt install -y \
    nodejs npm \
    rustc cargo \
    git \
    build-essential
```

## Development Commands

### Sync Code to Target
```bash
# From Mac - sync entire project
rsync -avz --exclude 'node_modules' --exclude 'target' --exclude 'dist' \
    /Users/dorian/Projects/archy/ \
    archipelago@192.168.1.228:/home/archipelago/archy/

# Or just the frontend
rsync -avz --exclude 'node_modules' \
    /Users/dorian/Projects/archy/neode-ui/ \
    archipelago@192.168.1.228:/home/archipelago/archy/neode-ui/
```

### Frontend Development (Vue.js)
```bash
# On target via SSH
cd ~/archy/neode-ui
npm install
npm run dev -- --host 0.0.0.0

# Access from Mac browser: http://192.168.1.228:5173
```

### Backend Development (Rust)
```bash
# On target via SSH
cd ~/archy/core
cargo build --release

# Test run
./target/release/archipelago
```

### Quick Deploy Script
Create `~/deploy.sh` on Mac:
```bash
#!/bin/bash
TARGET="archipelago@192.168.1.228"
PROJECT="/Users/dorian/Projects/archy"

# Sync code
rsync -avz --exclude 'node_modules' --exclude 'target' --exclude 'dist' \
    "$PROJECT/" "$TARGET:/home/archipelago/archy/"

# Rebuild on target
ssh $TARGET "cd ~/archy/neode-ui && npm install && npm run build"
ssh $TARGET "cd ~/archy/core && cargo build --release"

# Deploy to live system
ssh $TARGET "sudo cp ~/archy/core/target/release/archipelago /usr/local/bin/"
ssh $TARGET "sudo cp -r ~/archy/neode-ui/dist/* /opt/archipelago/web-ui/"
ssh $TARGET "sudo systemctl restart archipelago"

echo "Deployed! Check http://192.168.1.228"
```

## ISO Builds

ISO builds still happen on Mac (requires Docker Desktop for creating rootfs):

```bash
cd /Users/dorian/Projects/archy/image-recipe
./build-auto-installer-iso.sh
```

**Docker Desktop is required for:**
- Building the Debian rootfs tarball
- Creating squashfs overlay modules
- Pulling/saving container images for bundling

## File Locations

| Component | Mac (Source) | Target (Dev) | Target (Live) |
|-----------|--------------|--------------|---------------|
| Frontend | `neode-ui/` | `~/archy/neode-ui/` | `/opt/archipelago/web-ui/` |
| Backend | `core/` | `~/archy/core/` | `/usr/local/bin/archipelago` |
| App manifests | `apps/` | `~/archy/apps/` | `/etc/archipelago/apps/` |

## What You Can Remove from Mac

**Keep:**
- Docker Desktop (needed for ISO builds)
- Node.js/npm (for local editing/linting)
- Cursor IDE

**Can remove:**
- Any local test containers
- Podman (if installed)
- Local development servers (test on target instead)

## Workflow Summary

1. **Edit** code in Cursor on Mac
2. **Sync** to HP ProDesk with rsync
3. **Test** on target (run dev server or deploy to live)
4. **Iterate** until working
5. **Build ISO** on Mac when ready for distribution
6. **Flash & test** ISO on HP ProDesk