docs: add MQTT message format contract with closed-network architecture

Defines topic hierarchy, payload schemas, QoS levels, heartbeat protocol, camera auto-discovery via announce topic, offline buffering strategy, and command/response flow for start/stop. Architecture: travel router subnet (192.168.4.x), Pi Zero 2 W runs Mosquitto + Go backend, ESP32s dual-STA to GoPro AP + travel router. No internet dependency. Closes CUB-238.
2026-05-21 21:08:38 +00:00
parent 02fa6e4d4f
commit df212796d2
2 changed files with 445 additions and 0 deletions
@@ -0,0 +1,172 @@
+# RemoteRig Gitea CI/CD Implementation Plan
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** Set up Gitea Actions CI/CD pipeline with build → test → deploy stages for the RemoteRig React dashboard.
+
+**Architecture:** Gitea Actions (GitHub Actions compatible) running in `.gitea/workflows/`. Single workflow file with three jobs: lint+typecheck, test, build, and a manual deploy step. The app is a Vite SPA that builds to `dist/` — deploy serves those static files.
+
+**Tech Stack:** Gitea Actions, Node 22, Vite, Vitest, TypeScript, Tailwind
+
+**Success criteria:**
+- Build step completes successfully (`tsc -b && vite build`)
+- All unit tests pass (`vitest run`)
+- Deploy step exists (manual trigger for now)
+
+---
+
+### Task 1: Verify Gitea Actions runner availability
+
+**Objective:** Confirm the Gitea instance has at least one Actions runner registered.
+
+**Files:** None (read-only check)
+
+**Step 1:** Check Gitea Actions runners
+
+```bash
+curl -s "https://code.cubecraftcreations.com/api/v1/admin/runners" \
+  -H "Authorization: bearer ${HERMES_GITEA_TOKEN}" | jq '.'
+```
+
+If this returns a list with runners, we're good. If 404 or empty, we need to register a runner.
+
+**Step 2:** Check org-level runners
+
+```bash
+curl -s "https://code.cubecraftcreations.com/api/v1/orgs/CubeCraft-Creations/actions/runners" \
+  -H "Authorization: bearer ${HERMES_GITEA_TOKEN}" | jq '.'
+```
+
+**Expected output:** At least one runner with `"is_online": true` at either admin or org level.
+
+**Verification:** Confirm runners exist before proceeding.
+
+---
+
+### Task 2: Create Gitea Actions CI/CD workflow
+
+**Objective:** Create `.gitea/workflows/ci.yaml` with jobs for lint, typecheck, test, build, and deploy.
+
+**Files:**
+- Create: `.gitea/workflows/ci.yaml`
+
+**Workflow structure:**
+
+```yaml
+name: CI/CD
+
+on:
+  push:
+    branches: [dev, main]
+  pull_request:
+    branches: [dev, main]
+
+jobs:
+  # ── Quality Gates ──────────────────────────────────────────
+  lint-and-typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npx tsc --noEmit
+
+  # ── Unit Tests ─────────────────────────────────────────────
+  test:
+    needs: lint-and-typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm test
+
+  # ── Build ──────────────────────────────────────────────────
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # ── Deploy ─────────────────────────────────────────────────
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment: production
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Deploy static files
+        run: |
+          echo "Deploying to production..."
+          # Replace with actual deploy command (rsync, scp, S3, etc.)
+          echo "Deploy target: /var/www/remote-rig/"
+          echo "Placeholder — configure deploy target before merging to main"
+```
+
+**Step 1:** Create the directory and file
+
+```bash
+mkdir -p /mnt/ai-storage/projects/remote-rig/.gitea/workflows
+```
+
+**Step 2:** Write the workflow file with the content above
+
+**Step 3:** Verify YAML syntax
+
+```bash
+python3 -c "import yaml; yaml.safe_load(open('/mnt/ai-storage/projects/remote-rig/.gitea/workflows/ci.yaml'))" && echo "YAML: OK"
+```
+
+**Step 4:** Commit
+
+```bash
+cd /mnt/ai-storage/projects/remote-rig
+git add .gitea/
+git commit -m "ci: add Gitea Actions pipeline (lint, typecheck, test, build, deploy)"
+```
+
+---
+
+### Task 3: Verify workflow triggers on push
+
+**Objective:** Push the workflow and verify it appears in Gitea Actions.
+
+**Step 1:** Push the branch
+
+```bash
+cd /mnt/ai-storage/projects/remote-rig
+git push
+```
+
+**Step 2:** Check if the workflow registered
+
+```bash
+curl -s "https://code.cubecraftcreations.com/api/v1/repos/CubeCraft-Creations/remote-rig/actions/workflows" \
+  -H "Authorization: bearer ${HERMES_GITEA_TOKEN}" | jq '.workflows[] | {name, state, path}'
+```
+
+**Expected:** The CI/CD workflow appears with state "active".
+
+**Verification:** Workflow is listed and active on the repo.