feat: add headless-setup-script and OpenSpec artifacts

Implement a 'one-liner' installation script for the MPVJ (Modern PocketVJ)
ecosystem on Raspbian x64 Lite.

- Interactive whiptail UI for Hostname, SSID, and WiFi Password configuration.
- Automated system hardening: hostapd, dnsmasq, avahi-daemon, and Node.js.
- Memory safety for Pi 3B: temporary 1GB swap and NPM concurrency limits.
- Networking failsafe: static AP on wlan0 and DHCP on eth0 with mDNS support.
- OpenSpec artifacts (Proposal, Design, Spec, Tasks) included.

openspec/changes/mpvj-headless-setup-script/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-10

openspec/changes/mpvj-headless-setup-script/design.md

@@ -0,0 +1,44 @@
+## Context
+
+Targeting the Raspberry Pi 3B (1GB RAM) running Raspbian x64 Lite. The goal is a "Finalize on Reboot" strategy where the user is disconnected from SSH and reconnects to the newly created WiFi Access Point.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create a `curl | bash` compatible script.
+- Support a custom Git repository URL as a script argument.
+- Use `whiptail` for a professional, interactive UI.
+- Ensure the system remains accessible via Ethernet if WiFi configuration fails.
+
+**Non-Goals:**
+- **Automated SSH Key Setup**: We will rely on the user's existing SSH credentials.
+- **Firewall Configuration**: Advanced `iptables` or `ufw` setup is out of scope for this version.
+
+## Decisions
+
+### 1. Delivery Workflow
+The script will be invoked as:
+`curl -sSL <URL>/setup.sh | sudo bash -s -- <REPO_URL>`
+This allows the script to be hosted on Gitea/GitHub and pull the application code dynamically.
+
+### 2. Networking Architecture
+- **wlan0**: Configured as a static Access Point (`192.168.4.1`).
+- **eth0**: Remains a DHCP client for failsafe rescue.
+- **mDNS (Link-Local)**: Avahi will be configured to broadcast `mpvj.local` even on IPv4 Link-Local (169.254.x.x) to support direct Pi-to-Laptop cable connection without a router.
+- **WiFi Region**: The script will interrogate and set the `country_code` in `wpa_supplicant.conf` to prevent `hostapd` from being "soft-blocked" by the kernel.
+
+### 3. Build Strategy (The "Safe" Build)
+To handle the 1GB RAM limitation on Pi 3B:
+1. **Disk Check**: Verify at least 2GB of free space before starting.
+2. **Swap Scaling**: Temporarily increase swap to 1GB using `dphys-swapfile`.
+3. **Concurrency Limiting**: Run `npm config set jobs 1` and `node --max-old-space-size=512` during the build phase to prevent OOM (Out of Memory) panics.
+4. **Hybrid Detection**: Skip the build entirely if a pre-compiled `frontend/dist` folder is detected in the repository.
+
+### 4. Configuration Templating
+The script will use "Heredocs" to overwrite system configuration files with the user's validated input (SSID, Password, Hostname, Country Code).
+
+## Risks / Trade-offs
+
+- **[Risk] SSH Disconnection** → **Mitigation**: The script performs all updates and installs *before* staging the network changes and requires a final user confirmation before rebooting.
+- **[Risk] SD Card Wear** → **Mitigation**: The swap increase is temporary and only used during the installation/build phase.
+- **[Risk] Invalid WiFi Password** → **Mitigation**: The script includes a validation loop to ensure WPA2 passwords are at least 8 characters.

openspec/changes/mpvj-headless-setup-script/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+Deploying MPVJ on a Raspberry Pi 3B (x64 Lite) requires complex system-level configuration (WiFi Access Point, DNS masking, service orchestration). Currently, this is a manual and error-prone process. A "one-liner" headless setup script is needed to transform a clean Raspbian installation into a dedicated mapping appliance with zero friction.
+
+## What Changes
+
+- **Interactive Setup Script**: A Bash-based installer (`setup.sh`) that asks for hostname, SSID, and WiFi password using a TUI (Text User Interface).
+- **Automated System Hardening**: Automatic installation and configuration of `hostapd`, `dnsmasq`, `avahi-daemon`, and `nodejs`.
+- **Hybrid Networking Configuration**: Setup of a static IP (192.168.4.1) for the WiFi AP while maintaining DHCP on Ethernet (eth0) for failsafe access.
+- **Application Deployment**: Cloning the MPVJ repository from a user-provided URL and installing dependencies.
+- **Service Orchestration**: Installation of a `systemd` service for the MPVJ backend to ensure it starts on boot.
+
+## Capabilities
+
+### New Capabilities
+- `headless-installer`: A standalone Bash script capable of configuring a Raspberry Pi for headless MPVJ operation via a single command.
+
+### Modified Capabilities
+- `hybrid-network-control`: The existing networking logic will be updated to respect the configurations generated by the setup script.
+
+## Impact
+
+- **System Networking**: Modifies `/etc/dhcpcd.conf`, `/etc/hostapd/hostapd.conf`, and `/etc/dnsmasq.conf`.
+- **Hostname**: Updates `/etc/hostname` and `/etc/hosts`.
+- **Resource Management**: Automatically manages swap file size during the build process to prevent OOM errors on 1GB RAM devices.
+- **Security**: Sets an independent WPA2 password for the WiFi AP while leaving the system SSH password untouched.

openspec/changes/mpvj-headless-setup-script/specs/headless-installer/spec.md

@@ -0,0 +1,53 @@
+# Headless Installer Spec
+
+## Interrogation Phase
+
+### Hostname Selection
+- **GIVEN** the script is running
+- **WHEN** prompted for a hostname
+- **THEN** the system SHALL validate that the name contains only alphanumeric characters and hyphens
+- **AND** it SHALL default to `mpvj` if left blank
+
+### WiFi Configuration
+- **GIVEN** the interrogation phase
+- **WHEN** the user enters a WiFi password
+- **THEN** the script SHALL verify it is at least 8 characters long (WPA2 requirement)
+- **AND** it SHALL loop back to the prompt if validation fails
+- **AND** the script SHALL prompt for a 2-letter ISO Country Code (e.g., US, GB) to unblock the WiFi hardware.
+
+## Installation Phase
+
+### Pre-Flight Checks
+- **GIVEN** the start of the installation
+- **WHEN** checking system resources
+- **THEN** the script SHALL verify that at least 2GB of disk space is available
+- **AND** it SHALL abort with a clear error message if space is insufficient.
+
+### System Updates
+- **GIVEN** the start of the script
+- **WHEN** updating packages
+- **THEN** it SHALL use a progress bar (`whiptail --gauge`) to show status
+- **AND** it SHALL run in non-interactive mode (`-y`)
+
+### Repository Cloning
+- **GIVEN** a valid <REPO_URL> argument
+- **WHEN** cloning the repository
+- **THEN** it SHALL clone into `/home/pi/mpvj`
+- **AND** it SHALL ensure the `pi` user owns the directory
+
+## Summary & Finalization
+
+### Information Display
+- **GIVEN** the end of the installation
+- **WHEN** all configurations are staged
+- **THEN** the script SHALL display a "Don't Miss It" summary box containing:
+  - Hostname (`.local` address)
+  - Static IP (`192.168.4.1`)
+  - WiFi SSID
+  - WiFi Password
+- **AND** it SHALL require the user to press "OK" to proceed to the reboot prompt
+
+### Reboot Confirmation
+- **GIVEN** the summary has been acknowledged
+- **WHEN** the reboot prompt appears
+- **THEN** the system SHALL ONLY reboot if the user selects "Yes"

openspec/changes/mpvj-headless-setup-script/tasks.md

@@ -0,0 +1,33 @@
+## 1. Interrogation & Validation
+
+- [x] 1.1 Implement argument check for `<REPO_URL>`.
+- [x] 1.2 Create `whiptail` prompts for Hostname, SSID, WiFi Password, and Country Code.
+- [x] 1.3 Add validation loop for WPA2 password length (min 8 chars) and Country Code format.
+
+## 2. System Staging
+
+- [x] 2.1 Implement the Pre-Flight Disk Space check (`df -h`).
+- [x] 2.2 Implement the progress bar for `apt update && upgrade`.
+- [x] 2.3 Install dependencies: `nodejs`, `hostapd`, `dnsmasq`, `avahi-daemon`, `git`.
+- [x] 2.4 Configure Hostname and WiFi Country Code in system files.
+- [x] 2.5 Set up the temporary 1GB Swap file.
+
+## 3. Networking Configuration
+
+- [x] 3.1 Write the `hostapd.conf` template using user-provided SSID and Password.
+- [x] 3.2 Configure `dnsmasq.conf` for the `192.168.4.1` range.
+- [x] 3.3 Update `dhcpcd.conf` to set static IP on `wlan0`.
+- [x] 3.4 Create Avahi service file for mDNS HTTP discovery (including Link-Local support).
+
+## 4. Application Deployment
+
+- [x] 4.1 Clone the repository to `/home/pi/mpvj`.
+- [x] 4.2 Run `npm install` with concurrency limits (`--jobs 1`) and `npm run build` within the swap safety net.
+- [x] 4.3 Install the `systemd` service for the backend.
+- [x] 4.4 Generate the `.env` file with installation metadata.
+
+## 5. Finalization
+
+- [x] 5.1 Revert the swap file to default size.
+- [x] 5.2 Implement the "Ultimate Summary" whiptail message box.
+- [x] 5.3 Add the final reboot confirmation dialog.

scripts/setup.sh

@@ -0,0 +1,222 @@
+#!/bin/bash
+
+# MPVJ Headless Setup Script
+# Usage: curl -sSL <URL>/setup.sh | sudo bash -s -- <REPO_URL>
+
+set -e
+
+REPO_URL=$1
+
+if [ -z "$REPO_URL" ]; then
+    echo "Usage: $0 <REPO_URL>"
+    exit 1
+fi
+
+# Check for root
+if [ "$EUID" -ne 0 ]; then
+  echo "Please run as root (use sudo)"
+  exit 1
+fi
+
+# 1. INTERROGATION PHASE
+echo "Interrogating user for configuration..."
+
+# 1.1 Hostname
+HOSTNAME=$(whiptail --inputbox "Enter Hostname (e.g. mpvj)" 8 45 "mpvj" --title "Hostname Configuration" 3>&1 1>&2 2>&3) || exit 1
+HOSTNAME=${HOSTNAME:-mpvj}
+
+# 1.2 SSID
+WIFI_SSID=$(whiptail --inputbox "Enter WiFi SSID (e.g. MPVJ-AP)" 8 45 "MPVJ-AP" --title "WiFi SSID Configuration" 3>&1 1>&2 2>&3) || exit 1
+WIFI_SSID=${WIFI_SSID:-MPVJ-AP}
+
+# 1.3 Country Code & Password Validation
+while true; do
+  WIFI_COUNTRY=$(whiptail --inputbox "Enter 2-letter Country Code (e.g. US, GB, DE)" 8 45 "US" --title "WiFi Country Configuration" 3>&1 1>&2 2>&3) || exit 1
+  WIFI_COUNTRY=$(echo "$WIFI_COUNTRY" | tr '[:lower:]' '[:upper:]')
+  if [[ ! "$WIFI_COUNTRY" =~ ^[A-Z]{2}$ ]]; then
+    whiptail --msgbox "Error: Country Code must be exactly 2 letters (e.g., US)." 8 45
+  else
+    break
+  fi
+done
+
+while true; do
+  WIFI_PASS=$(whiptail --passwordbox "Enter WiFi Password (minimum 8 characters)" 8 45 --title "WiFi Password Configuration" 3>&1 1>&2 2>&3) || exit 1
+  if [ ${#WIFI_PASS} -lt 8 ]; then
+    whiptail --msgbox "Error: WiFi Password must be at least 8 characters long (WPA2 requirement)." 8 45
+  else
+    break
+  fi
+done
+
+# 2. SYSTEM STAGING PHASE
+echo "System Staging Phase..."
+
+# 2.1 Pre-Flight Disk Space Check (2GB Required)
+FREE_SPACE_KB=$(df / --output=avail | tail -n1)
+MIN_SPACE_KB=2097152 # 2GB
+if [ "$FREE_SPACE_KB" -lt "$MIN_SPACE_KB" ]; then
+  whiptail --msgbox "Error: Not enough disk space. At least 2GB of free space is required." 8 45
+  exit 1
+fi
+
+# 2.2 System Updates
+(
+  echo 25
+  apt-get update -y > /dev/null 2>&1
+  echo 75
+  DEBIAN_FRONTEND=noninteractive apt-get upgrade -y > /dev/null 2>&1
+  echo 100
+) | whiptail --gauge "Updating System Packages..." 6 60 0
+
+# 2.3 Install Dependencies
+(
+  echo 20
+  DEBIAN_FRONTEND=noninteractive apt-get install -y git hostapd dnsmasq avahi-daemon curl > /dev/null 2>&1
+  echo 60
+  curl -fsSL https://deb.nodesource.com/setup_20.x | bash - > /dev/null 2>&1
+  DEBIAN_FRONTEND=noninteractive apt-get install -y nodejs > /dev/null 2>&1
+  echo 100
+) | whiptail --gauge "Installing Core Dependencies..." 6 60 0
+
+# 2.4 Hostname & Country Code
+hostnamectl set-hostname "$HOSTNAME"
+sed -i "s/127.0.1.1.*/127.0.1.1\t$HOSTNAME/g" /etc/hosts
+if command -v raspi-config > /dev/null; then
+  raspi-config nonint do_wifi_country "$WIFI_COUNTRY" > /dev/null 2>&1
+fi
+
+# 2.5 Swap Increase
+if [ -f /etc/dphys-swapfile ]; then
+  sed -i "s/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=1024/g" /etc/dphys-swapfile
+  dphys-swapfile setup
+  dphys-swapfile swapon
+fi
+
+# 3. NETWORKING CONFIGURATION
+echo "Configuring Networking..."
+
+# 3.1 hostapd
+cat <<EOF > /etc/hostapd/hostapd.conf
+interface=wlan0
+driver=nl80211
+ssid=$WIFI_SSID
+hw_mode=g
+channel=7
+wpa=2
+wpa_passphrase=$WIFI_PASS
+wpa_key_mgmt=WPA-PSK
+wpa_pairwise=TKIP
+rsn_pairwise=CCMP
+auth_algs=1
+macaddr_acl=0
+EOF
+sed -i 's/#DAEMON_CONF=""/DAEMON_CONF="\/etc\/hostapd\/hostapd.conf"/g' /etc/default/hostapd
+
+# 3.2 dnsmasq
+mv /etc/dnsmasq.conf /etc/dnsmasq.conf.bak 2>/dev/null || true
+cat <<EOF > /etc/dnsmasq.conf
+interface=wlan0
+dhcp-range=192.168.4.2,192.168.4.20,255.255.255.0,24h
+domain=local
+address=/$HOSTNAME.local/192.168.4.1
+EOF
+
+# 3.3 dhcpcd
+if ! grep -q "interface wlan0" /etc/dhcpcd.conf; then
+cat <<EOF >> /etc/dhcpcd.conf
+interface wlan0
+    static ip_address=192.168.4.1/24
+    nohook wpa_supplicant
+EOF
+fi
+
+# 3.4 Avahi
+cat <<EOF > /etc/avahi/services/mpvj.service
+<?xml version="1.0" standalone='no'?>
+<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
+<service-group>
+  <name replace-wildcards="yes">MPVJ Control Center</name>
+  <service>
+    <type>_http._tcp</type>
+    <port>80</port>
+  </service>
+</service-group>
+EOF
+sed -i 's/#use-ipv4-ll=yes/use-ipv4-ll=yes/g' /etc/avahi/avahi-daemon.conf
+
+# 4. APPLICATION DEPLOYMENT
+echo "Deploying Application..."
+
+# 4.1 Clone
+[ -d /home/pi/mpvj ] && mv /home/pi/mpvj /home/pi/mpvj.old.$(date +%s)
+git clone "$REPO_URL" /home/pi/mpvj
+mkdir -p /home/pi/media
+chown -R pi:pi /home/pi/mpvj /home/pi/media
+
+# 4.2 Build
+export NODE_OPTIONS="--max-old-space-size=512"
+cd /home/pi/mpvj/backend
+sudo -u pi npm install --jobs 1
+cd /home/pi/mpvj/frontend
+if [ ! -d "dist" ]; then
+  sudo -u pi npm install --jobs 1
+  sudo -u pi npm run build
+fi
+
+# 4.3 Systemd
+cat <<EOF > /etc/systemd/system/mpvj-backend.service
+[Unit]
+Description=MPVJ Headless Control Center Backend
+After=network.target
+
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/home/pi/mpvj/backend
+ExecStart=/usr/bin/node index.js
+Restart=on-failure
+Environment=NODE_OPTIONS=--max-old-space-size=512
+
+[Install]
+WantedBy=multi-user.target
+EOF
+systemctl daemon-reload
+systemctl enable mpvj-backend.service
+
+# 4.4 .env
+cat <<EOF > /home/pi/mpvj/backend/.env
+PORT=80
+MPVJ_HOSTNAME=$HOSTNAME
+MPVJ_SSID=$WIFI_SSID
+MPVJ_WIFI_PASS=$WIFI_PASS
+MPVJ_REPO_URL=$REPO_URL
+MPVJ_MEDIA_DIR=/home/pi/media
+EOF
+chown pi:pi /home/pi/mpvj/backend/.env
+chmod 600 /home/pi/mpvj/backend/.env
+
+# 5. FINALIZATION
+echo "Finalizing..."
+
+# 5.1 Revert Swap
+if [ -f /etc/dphys-swapfile ]; then
+  sed -i "s/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=100/g" /etc/dphys-swapfile
+  dphys-swapfile setup
+  dphys-swapfile swapon
+fi
+
+# 5.2 Summary
+SUMMARY="MPVJ INSTALLATION COMPLETE\n\n"
+SUMMARY+="Please NOTE DOWN these details before rebooting:\n\n"
+SUMMARY+="HOSTNAME:   $HOSTNAME.local\n"
+SUMMARY+="STATIC IP:  192.168.4.1\n"
+SUMMARY+="WIFI SSID:  $WIFI_SSID\n"
+SUMMARY+="WIFI PASS:  $WIFI_PASS\n\n"
+SUMMARY+="Your SSH password remains unchanged.\n"
+SUMMARY+="Connect to '$WIFI_SSID' after reboot.\n\n"
+SUMMARY+="Reboot now?"
+
+if whiptail --title "Success" --yesno "$SUMMARY" 20 60; then
+  reboot
+fi