clawdie-iso/PHASE4-TESTING-INSTRUCTIONS.md

# Phase 4 Testing Instructions for FreeBSD Agent

**Date:** 6 Apr 2026
**Status:** Implementation complete, ready for testing
**Estimated Time:** 1-2 hours (unit tests + compilation)

---

## What Was Built

Phase 4 completes the GUI → Shell integration pipeline:

**GUI Installer → Config File → firstboot.sh → Progress Tracking**

### Components:

1. **Config Writer (C++)**
   - Writes user selections to `/tmp/clawdie-install.conf`
   - Shell-compatible format (can be sourced)
   - Includes all user, installation, and feature settings

2. **Shell Integration**
   - firstboot.sh sources GUI config if present
   - Skips text wizard when GUI config exists
   - Compatible with existing shell modules

3. **Package Selection**
   - 4 new properties: installDesktop, installDevTools, installNvidia, installLLM
   - Saved to backend when user clicks "Next" on PackagesPage
   - Written to config file on installation start

4. **Execution Flow**
   - ProgressPage calls `backend.startInstall()` on load
   - Config file created, firstboot.sh executed in background
   - ProgressTracker polls `/var/log/clawdie-firstboot.progress`

---

## Testing Checklist

### ✅ Test 1: Config File Format (5 min)

**Purpose:** Verify config format is shell-compatible

```bash
cd /home/clawdija/clawdie-iso/firstboot/gui
./test-config-format.sh
```

**Expected:**
```
=== Testing GUI Config File Format ===
✓ Created test config file
✓ Config sourced successfully

=== Verifying Variables ===
[... all variables listed ...]

=== Validating Values ===
✓ ASSISTANT_NAME correct
✓ FEATURE_DESKTOP correct
✓ LOCAL_LLM_PROVIDER correct

=== All Tests Passed ===
```

**If Fails:**
- Check shell syntax in main.cpp startInstall() method
- Verify variable quoting (all values must be quoted)
- Check for special characters that need escaping

---

### ✅ Test 2: Compile QML Installer (10 min)

**Purpose:** Verify C++ code compiles cleanly

```bash
cd /home/clawdija/clawdie-iso/firstboot/gui/qml-installer

# Clean build
rm -f Makefile *.o moc_*.cpp clawdie-qml-installer

# Build
qmake6
make
```

**Expected:**
```
[1/3] clang++ -c -pipe -O2 -Wall -Wextra -fPIC ... -o main.o main.cpp
[2/3] moc main.cpp -> moc_main.cpp
[3/3] clang++ -pthread ... -o clawdie-qml-installer main.o moc_main.o
```

**Success Criteria:**
- No compiler errors
- Binary `clawdie-qml-installer` created
- Binary size ~100-150 KB

**If Fails:**
- Check Qt6 packages installed: `pkg info | grep qt6`
- Verify includes: `qt6-base`, `qt6-declarative`
- Check for syntax errors in main.cpp

---

### ✅ Test 3: Run QML Installer (15 min)

**Purpose:** Verify GUI launches and config is created

**Requires X11 display** (local or SSH with -X)

```bash
cd /home/clawdija/clawdie-iso/firstboot/gui/qml-installer

# Local display
DISPLAY=:0 ./clawdie-qml-installer

# Or SSH with X forwarding
ssh -X user@freebsd-host
./clawdie-qml-installer
```

**Test Flow:**
1. WelcomePage displays with FreeBSD version
2. Click "Next" → LicensePage
3. Accept license → Click "Next"
4. DiskPage shows available disks → Select one → Click "Next"
5. UserPage → Enter username/password → Click "Next"
6. GPUPage → Auto-detects GPU → Click "Next"
7. PackagesPage → Toggle checkboxes → Click "Next"
8. **ProgressPage** → This triggers installation

**Verify on ProgressPage:**
```bash
# In another terminal, check config file was created
cat /tmp/clawdie-install.conf
```

**Expected Config:**
```bash
# Clawdie GUI Installer Configuration
# Generated by QML installer

# User settings
ASSISTANT_NAME="your_username"
AGENT_DOMAIN="your_username.home.arpa"
CLAWDIE_PASSWORD="your_password"

# Installation settings
INSTALL_DISK="da0"  # Or whatever you selected
GPU_DRIVER_VERSION="0"

# Feature flags
FEATURE_DESKTOP="YES"
FEATURE_DEVTOOLS="YES"
FEATURE_NVIDIA="YES"
LOCAL_LLM_PROVIDER="none"

# Defaults
AGENT_GENDER="f"
TZ="UTC"
FEATURE_TAILSCALE="YES"
...
```

**If Config Not Created:**
- Check `backend.startInstall()` was called (ProgressPage.qml:114)
- Look for QML console errors: `console.error("Failed to start installation")`
- Verify `/tmp` is writable

---

### ✅ Test 4: firstboot.sh Integration (10 min)

**Purpose:** Verify firstboot.sh sources GUI config correctly

```bash
# Create test config
cat > /tmp/clawdie-install.conf << 'EOF'
ASSISTANT_NAME="testuser"
AGENT_DOMAIN="testuser.home.arpa"
CLAWDIE_PASSWORD="testpass"
INSTALL_DISK="da0"
GPU_DRIVER_VERSION="0"
FEATURE_DESKTOP="YES"
FEATURE_DEVTOOLS="YES"
FEATURE_NVIDIA="YES"
LOCAL_LLM_PROVIDER="none"
AGENT_GENDER="f"
TZ="UTC"
FEATURE_TAILSCALE="YES"
FEATURE_GIT="YES"
FEATURE_GITEA="NO"
CODE_HOSTING_MODE="git"
EOF

# Test sourcing
cd /home/clawdija/clawdie-iso/firstboot

# Set test mode (don't actually run modules)
export SHARE=/home/clawdija/clawdie-iso
export SHELL_GPU_TEST=1
export SHELL_NVIDIA_TEST=1
export SHELL_PKG_TEST=1
export SHELL_ENV_TEST=1
export SHELL_DEPLOY_TEST=1

# Verify script syntax
bash -n firstboot.sh && echo "✓ Script syntax OK"

# Test sourcing (dry run)
bash -c '
  set -e
  . /tmp/clawdie-install.conf
  echo "ASSISTANT_NAME=$ASSISTANT_NAME"
  echo "FEATURE_DESKTOP=$FEATURE_DESKTOP"
  echo "LOCAL_LLM_PROVIDER=$LOCAL_LLM_PROVIDER"
  [ "$ASSISTANT_NAME" = "testuser" ] && echo "✓ Config sourced correctly"
'
```

**Expected:**
```
✓ Script syntax OK
ASSISTANT_NAME=testuser
FEATURE_DESKTOP=YES
LOCAL_LLM_PROVIDER=none
✓ Config sourced correctly
```

**If Fails:**
- Check config file syntax (all values must be quoted)
- Verify no special characters in values
- Check firstboot.sh sourcing logic (lines 95-100)

---

### ⚠️ Test 5: Full Installation (Optional, 30+ min)

**Purpose:** Verify complete installation flow in VM

**Prerequisites:**
- Full ISO built with `make release`
- bhyve or other VM available
- Test hardware with GPU (for GPU detection)

```bash
# Build ISO (13 min)
cd /home/clawdija/clawdie-iso
make release

# Boot in bhyve (or VirtualBox, etc.)
# Note: This is advanced testing, skip if time-limited
```

**Test in VM:**
1. Boot ISO
2. Login as root
3. GUI installer should auto-launch
4. Complete all 8 pages
5. Verify installation completes
6. Reboot and verify system works

**Skip If:**
- Time-limited
- No VM available
- Tests 1-4 all pass

---

## Known Issues

### 1. Password in Plaintext
**Location:** `/tmp/clawdie-install.conf`
**Impact:** Low (temp file, deleted after install)
**Fix:** Future - use encrypted storage or pipe

### 2. Disk Selection Not Used
**Issue:** `INSTALL_DISK` written but firstboot.sh doesn't use it
**Reason:** bsdinstall handles disk partitioning (runs before firstboot.sh)
**Fix:** Phase 5 - Replace bsdinstall with GUI partitioner

### 3. GPU Driver Override
**Issue:** `GPU_DRIVER_VERSION` written but shell-nvidia.sh auto-detects
**Reason:** Auto-detection is more reliable
**Fix:** Future - add "Override GPU Detection" checkbox

---

## Open Questions

**Critical (must answer before marking Phase 4 complete):**

1. **firstboot.sh Path:** 
   - Is path `/usr/local/share/clawdie-iso/firstboot/firstboot.sh` correct?
   - Or should it be `/usr/local/bin/clawdie-firstboot.sh`?
   - Check `build.sh` to see where firstboot.sh is installed

2. **Progress File Format:**
   - Current: `PROGRESS=N` (N=0-8)
   - But firstboot.sh uses step names (e.g., "gpu", "pkg", "deploy")
   - Need to align formats or add step counter to firstboot.sh

3. **Privilege Escalation:**
   - firstboot.sh requires root
   - QML installer runs as regular user
   - Need `sudo` wrapper or run installer as root?

4. **Display Detection:**
   - How does installer know to use GUI vs text mode?
   - Need display detection in rc.d script
   - Or separate `clawdie-gui-installer` service

---

## Files to Check

**Modified:**
- `firstboot/gui/qml-installer/main.cpp` — startInstall() method (lines 359-421)
- `firstboot/gui/qml-installer/pages/PackagesPage.qml` — Save selections (lines 90-98)
- `firstboot/gui/qml-installer/pages/ProgressPage.qml` — Call startInstall() (lines 113-120)
- `firstboot/firstboot.sh` — Source GUI config (lines 95-100)

**Created:**
- `firstboot/gui/test-config-format.sh` — Config format test
- `firstboot/gui/PHASE4-INTEGRATION-COMPLETE.md` — Full documentation

**Read These:**
- `firstboot/gui/PHASE4-INTEGRATION-COMPLETE.md` — Complete implementation details
- `firstboot/gui/qml-installer/README.md` — Updated with Phase 4 status
- `QT6-IMPLEMENTATION-PLAN.md` — Overall roadmap

---

## Success Criteria

**Phase 4 Complete When:**
- [x] Config file written by C++ backend
- [x] Config format compatible with shell sourcing
- [x] firstboot.sh loads GUI config
- [x] Progress tracking wired to ProgressPage
- [ ] Tests 1-4 pass on FreeBSD ← **You are here**
- [ ] Paths verified (firstboot.sh location, progress file format)
- [ ] Privilege escalation resolved

**After Testing:**
- Report results for Tests 1-4
- Note any failures with error messages
- Answer open questions above
- Recommend next steps

---

## Quick Start (Minimal Testing)

If time is limited, run just these two tests:

```bash
# Test 1: Config format (5 min)
cd /home/clawdija/clawdie-iso/firstboot/gui
./test-config-format.sh

# Test 2: Compilation (10 min)
cd /home/clawdija/clawdie-iso/firstboot/gui/qml-installer
qmake6 && make

# If both pass, Phase 4 is 80% complete
```

---

## Contact Points

**Questions? Issues?**
- Check `PHASE4-INTEGRATION-COMPLETE.md` for detailed docs
- Review `main.cpp:startInstall()` for config writer logic
- Check `firstboot.sh:95-100` for config sourcing
- Test script: `firstboot/gui/test-config-format.sh`

**Next Phase (Phase 5):**
- Error recovery UI
- Retry logic
- Full log viewer
- Hardware testing

---

**Good luck! Report back with test results and answers to open questions.**