feat(ui): migrate to Vite React with Heidi backend integration

.github/workflows/ci.yml

@@ -7,6 +7,41 @@ on:
     branches: [main]
 
 jobs:
+  ui-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: "ui/package-lock.json"
+      - name: Install UI dependencies
+        run: |
+          cd ui
+          npm ci
+      - name: Build UI
+        run: |
+          cd ui
+          npm run build
+      - name: Verify UI build output
+        run: |
+          if [ ! -f "ui/dist/index.html" ]; then
+            echo "ERROR: UI build failed - index.html not found"
+            exit 1
+          fi
+          if [ ! -d "ui/dist/assets" ]; then
+            echo "ERROR: UI build failed - assets directory not found"
+            exit 1
+          fi
+          echo "UI build successful"
+          ls -la ui/dist/
+      - name: Cache UI build
+        uses: actions/cache@v4
+        with:
+          path: ui/dist
+          key: ${{ runner.os }}-ui-build-${{ github.sha }}
+
   test:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -43,10 +43,21 @@ htmlcov/
 .DS_Store
 Thumbs.db
 
-# Local development
-.local/
-.heidi/
-.memory
+# Local development - granular .local/ policy
+# Track: documentation and worklogs
+!.local/
+!.local/README.md
+!.local/worklog
+!.local/worklog/**
+# Ignore: secrets, state, cache, and other sensitive files
+.local/secrets/
+.local/state/
+.local/cache/
+.local/*.json
+.local/*.key
+.local/*.pem
+.heidi/
+.memory
 
 # Backup files
 *~
@@ -75,4 +86,6 @@ openwebui/backend/data/
 
 # Memory / context
 .memory/
-heidi_cli/src/heidi_cli/ui_dist/
+
+# Packaged UI dist (built from ui/, included in package but not git)
+src/heidi_cli/ui_dist/

.local/worklog

@@ -0,0 +1,64 @@
+# Heidi CLI UI Migration Worklog
+## Date: 2026-02-17
+## Branch: feat/ui-work-theme (migrating to feat/ui-packaging)
+
+### Summary
+Successfully migrated Heidi CLI UI from legacy architecture to new Vite-based React application, integrated with Heidi backend API, and established production packaging/release pipeline.
+
+### Commit Range
+Base: bfd38de (Merge pull request #69 - palette-ux-improvements)
+Changes: Working tree modifications (not yet committed as single squashed commit)
+Estimated files changed: 36 files, +2682/-3648 lines
+
+### Key Deliverables
+
+1. **UI Migration (dev_1_ui_migrator)**
+   - Cloned work UI repo (commit: d512c199) as visual base
+   - Removed Next.js server.ts, socket.io, SSH dependencies
+   - Created Vite React app structure (src/main.tsx entry)
+   - Implemented Heidi API client layer:
+     - src/api/heidi.ts: health(), listAgents(), listRuns(), getRun(), runOnce(), runLoop(), chat(), cancelRun()
+     - src/api/stream.ts: SSE streaming with polling fallback
+   - Migrated components: Sidebar, ChatArea, AgentArea, TerminalArea, SettingsModal, RightSidebar
+   - Terminal tab: Safe MVP placeholder (no SSH, no socket.io)
+
+2. **Configuration**
+   - vite.config.ts: port 3002, strictPort, allowedHosts (heidiai.com.au)
+   - Proxy routes to backend: /health, /agents, /run, /loop, /chat, /runs, /api
+   - No direct Gemini/OpenAI keys in browser (all through Heidi backend)
+
+3. **Packaging & Release (dev_3_packaging_release)**
+   - UI builds to ui/dist (Vite standard output)
+   - CLI command: `heidi ui build` (builds with --base=/ui/, copies to ~/.cache/heidi/ui/dist)
+   - Backend serves SPA at /ui/ with fallback routing
+   - Package data: pyproject.toml includes ui_dist/**/* in setuptools package-data
+   - Dist resolution order: HEIDI_UI_DIST env -> HEIDI_HOME/ui/dist -> XDG_CACHE/heidi/ui/dist -> bundled ui_dist
+   - CI guardrail: GitHub Actions job ui-build (Node 20, npm cache, verifies dist artifacts)
+   - Git policy: src/heidi_cli/ui_dist/ ignored (line 80 in .gitignore)
+
+4. **Documentation**
+   - README.md: Added Web UI section with dev/prod instructions
+   - Port reference table: 3002 (Vite dev), 7777 (backend)
+   - CORS/allowedHosts documentation for custom domains
+
+### Verification Steps Completed
+1. ✓ UI builds: npm ci && npm run build → ui/dist/index.html + assets/
+2. ✓ CLI build: heidi ui build --force → ~/.cache/heidi/ui/dist/
+3. ✓ Backend serve: HEIDI_UI_DIST=... heidi serve → /ui/ accessible
+4. ✓ Package install: pip install -e '.[dev]' → heidi ui --help works
+5. ✓ CI job: .github/workflows/ci.yml includes ui-build job
+6. ✓ Git ignore: src/heidi_cli/ui_dist/ properly excluded
+
+### Notes
+- UI assets are built during packaging and included in wheel/sdist
+- Source UI in ui/ remains in git (source code)
+- Built UI in src/heidi_cli/ui_dist/ is git-ignored but setuptools-included
+- Default behavior: heidi serve falls back to bundled ui_dist if no cache built
+
+### Breaking Changes
+None - this is additive. Legacy CLI commands remain functional.
+
+### Testing Required Before Merge
+1. Clean install smoke test (container/fresh venv)
+2. Verify no 404s on asset paths with correct base=/ui/
+3. Confirm SPA routing works (refresh on /ui/ doesn't 404)

README.md

@@ -106,6 +106,66 @@ heidi openwebui status
 heidi openwebui guide
 ```
 
+### Web UI
+
+Heidi includes a modern React-based web UI for interacting with agents through a chat interface.
+
+**Development Mode (separate ports):**
+```bash
+# Terminal 1: Start the backend API server
+heidi serve
+
+# Terminal 2: Start the UI dev server (with hot reload)
+heidi start ui
+# Or manually: cd ui && npm run dev
+
+# Access UI at http://localhost:3002
+# Backend runs at http://localhost:7777
+```
+
+**Production Mode (single port):**
+```bash
+# Build the UI for production
+heidi ui build
+
+# Start the backend server (serves UI at /ui/)
+heidi serve
+
+# Access the UI at http://localhost:7777/ui/
+```
+
+**UI Commands:**
+```bash
+heidi ui build       # Build the UI for production
+heidi ui path        # Show UI build path
+heidi ui status      # Check UI build status
+```
+
+**Configuration:**
+- UI dev server runs on port 3002 (Vite)
+- Backend API runs on port 7777 (FastAPI)
+- Vite proxy forwards API calls from :3002 → :7777 during development
+- Production UI is served at `/ui/` by the backend server
+- Set `HEIDI_UI_DIST` env var to override the UI dist directory
+
+**Production Deployment with Custom Domain:**
+
+When deploying with a reverse proxy (e.g., Cloudflare Tunnel, Nginx), the Vite dev server needs to trust your domain:
+
+1. The `vite.config.ts` already includes `heidiai.com.au` in `allowedHosts`
+2. For other domains, set the `HEIDI_CORS_ORIGINS` environment variable:
+   ```bash
+   export HEIDI_CORS_ORIGINS="https://your-domain.com,https://www.your-domain.com"
+   heidi serve
+   ```
+3. Or use the `--cors-origins` flag when starting the server
+
+**Port Reference:**
+| Service | Port | Purpose |
+|---------|------|---------|
+| Vite Dev Server | 3002 | Development UI with hot reload |
+| Heidi Backend | 7777 | API server + production UI |
+
 ## CLI Commands
 
 | Command | Description |

pyproject.toml

@@ -33,6 +33,9 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+heidi_cli = ["ui_dist/**/*", "ui_dist/*"]
+
 [tool.ruff]
 line-length = 100