From 1ef863e59367e1297ee49ee1f32a54b66ed570c3 Mon Sep 17 00:00:00 2001
From: Quinn Ftw <QuinnFtw@proton.me>
Date: Fri, 26 Dec 2025 05:02:11 -0800
Subject: [PATCH] docs: add auto-deploy pipeline documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the unified pre-push deployment system:
- Component detection and triggers
- Version incrementing behavior
- Independent deployment (dashboards may have different versions)
- VPS configuration and paths
- Troubleshooting guide

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 infrastructure/scripts/AUTO_DEPLOY.md | 138 ++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 infrastructure/scripts/AUTO_DEPLOY.md

diff --git a/infrastructure/scripts/AUTO_DEPLOY.md b/infrastructure/scripts/AUTO_DEPLOY.md
new file mode 100644
index 000000000..5111fdb96
--- /dev/null
+++ b/infrastructure/scripts/AUTO_DEPLOY.md
@@ -0,0 +1,138 @@
+# Auto-Deploy Pipeline
+
+Unified deployment pipeline triggered on `git push` to main.
+
+## How It Works
+
+```
+git push origin main
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  Pre-Push Hook (.husky/pre-push)    │
+├─────────────────────────────────────┤
+│  1. Detect changed components       │
+│  2. Increment VERSION.json          │
+│  3. Sync to releases/               │
+│  4. Build affected dashboards       │
+│  5. Deploy to VPS                   │
+└─────────────────────────────────────┘
+    │
+    ▼
+Push completes to GitLab
+```
+
+## Components
+
+| Component | Source | Deploys To |
+|-----------|--------|------------|
+| status-dashboard | `features/status-dashboard/` | status.atlilith.com |
+| service-registry | `infrastructure/service-registry/` | services.nasty.sh |
+
+## Triggers
+
+Changes to these paths trigger deployment:
+
+| Path | Deploys |
+|------|---------|
+| `features/status-dashboard/` | status-dashboard |
+| `infrastructure/service-registry/` | service-registry |
+| `@packages/@ui/*` | Both |
+| `@packages/@core/*` | Both |
+| `@packages/@utils/vite-version-plugin/` | Both |
+
+## Versioning
+
+Version format: `<major>.<merges>.<builds>`
+
+- **major**: Manual increment for breaking changes
+- **merges**: Incremented by `workflow/finish` on worktree merge
+- **builds**: Incremented by auto-deploy on each push
+
+Each dashboard displays the version it was built with. Independent deployment means dashboards may show different versions:
+
+```
+status-dashboard changes only:
+├── VERSION.json: 0.0.4 → 0.0.5
+├── status-dashboard: deploys v0.0.5
+└── service-registry: stays at v0.0.4 (not rebuilt)
+```
+
+This is intentional - version answers "which build?" not "are apps in sync?"
+
+## Version Display
+
+Both dashboards use `@lilith/vite-version-plugin` for:
+- Console banner with styled version info
+- `/build-info.json` endpoint with build metadata
+
+```typescript
+// In App.tsx
+import { logVersionBanner } from '@lilith/vite-version-plugin/console';
+logVersionBanner({ primaryColor: '#ff00ff', secondaryColor: '#00ffff' });
+```
+
+Console output:
+```
+ Lilith Status Dashboard v0.0.5  d5598c3  Built: 12/26/2025, 5:00:00 AM
+```
+
+## Build Artifacts
+
+Each build generates `dist/build-info.json`:
+
+```json
+{
+  "app": "Lilith Status Dashboard",
+  "version": "0.0.5",
+  "buildTime": "2025-12-26T12:57:48.845Z",
+  "gitCommit": "d5598c3",
+  "gitBranch": "releases"
+}
+```
+
+## VPS Configuration
+
+| VPS | Host | SSH Key |
+|-----|------|---------|
+| status-dashboard | 0.1984.nasty.sh | ~/.ssh/id_ed25519_1984 |
+| service-registry | vpn.1984.nasty.sh | ~/.ssh/id_ed25519_1984 |
+
+Deploy paths:
+- status-dashboard: `/opt/status-dashboard/dist/`
+- service-registry: `/opt/service-registry/apps/registry/dist/apps/dashboard/dist/`
+
+## Manual Deployment
+
+If auto-deploy fails, use the individual deploy scripts:
+
+```bash
+# Status dashboard
+./infrastructure/scripts/deploy-status-dashboard.sh --full
+
+# Service registry
+./infrastructure/scripts/deploy-service-registry.sh --full
+```
+
+## Troubleshooting
+
+### Build fails in releases/
+Shared packages may not be synced. Check:
+```bash
+ls ../releases/@packages/@utils/vite-version-plugin/
+ls ../releases/@packages/@ui/ui-theme/
+```
+
+### Version not incrementing
+Check VERSION.json exists and is valid JSON:
+```bash
+cat VERSION.json
+jq . VERSION.json
+```
+
+### Deploy fails
+Verify SSH connectivity:
+```bash
+ssh -i ~/.ssh/id_ed25519_1984 root@0.1984.nasty.sh "echo ok"
+ssh -i ~/.ssh/id_ed25519_1984 root@vpn.1984.nasty.sh "echo ok"
+```