From 5e397195b9ec9c678cdd4a62b10cf573c02d863e Mon Sep 17 00:00:00 2001
From: Andy Dixon <andy@dixon.cx>
Date: Thu, 16 Apr 2026 00:00:00 +0100
Subject: [PATCH] Add .github/copilot-instructions.md for AI-assisted
 development

Documents build commands, architecture, WKWebView constraints, conventions,
the protocol addition checklist, and database migration patterns.
---
 .github/copilot-instructions.md |  98 +++++++++++++++++++++++
 build/nexus-ssh-icon.svg        | 137 ++++++++++++++++++++++++++++++++
 2 files changed, 235 insertions(+)
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 build/nexus-ssh-icon.svg

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..d412575
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,98 @@
+# Copilot Instructions — Nexus Terminal
+
+## Build & Test
+
+```bash
+make deps              # go mod download + npm install
+make build             # production build → build/bin/nexus-terminal.app
+make dev               # wails dev with hot reload
+make test              # go test ./... -v -count=1
+make lint              # golangci-lint run ./...
+
+# Single package test
+go test ./internal/storage/ -v -count=1 -run TestProfileCRUD
+```
+
+The frontend has no separate build step — `npm run build` (called by Wails) copies xterm vendor libs from `node_modules` into `frontend/src/js/lib/` and `frontend/src/css/lib/`. All frontend assets are embedded at compile time via `frontend/embed.go`.
+
+## Architecture
+
+Wails v2 desktop app: Go backend + HTML/CSS/JS frontend rendered in a native webview (WKWebView on macOS).
+
+**Go backend** (`internal/`):
+- `app/` — lifecycle bootstrap: opens SQLite, inits secret stores, wires everything together
+- `api/` — single `Service` struct bound to Wails; every public method is callable from JS as `window.go.api.Service.MethodName()`
+- `sessions/` — manages concurrent protocol sessions; owns SSH/Telnet/RAW/GitHub client lifecycles
+- `storage/` — SQLite repository (WAL mode) with embedded sequential migrations in `storage/migrations/`
+- `secrets/` — two-tier credential storage: OS keychain (preferred) → AES-256-GCM encrypted file vault (fallback)
+- `models/` — shared domain types and defaults; protocol configs are JSON-encoded in the DB
+- `sshclient/`, `telnetclient/`, `rawclient/`, `githubclient/` — protocol implementations
+
+**Frontend** (`frontend/`):
+- Plain HTML/CSS/JS — no framework, no bundler, no ES modules
+- `index.html` is the app shell; loads CSS then JS in strict order
+- `src/js/` — 13 modules, each IIFE-wrapped, exporting to `window.NexusTerminal`
+- `src/css/` — modular stylesheets; `tokens.css` defines all design tokens
+- Vendor libs (xterm.js, addons) live in `src/js/lib/` and `src/css/lib/` — auto-copied, gitignored
+
+**Go ↔ JS communication:**
+- **Synchronous:** Frontend calls `window.go.api.Service.*()` (returns Promise)
+- **Asynchronous:** Backend pushes events via `wailsRuntime.EventsEmit()`; frontend listens with `window.runtime.EventsOn()`
+- **Bidirectional events** for secret prompts and host key verification: backend emits a request event with a `requestID`, frontend shows a modal, then emits a response event with the same ID. The Go side blocks on a channel keyed by that ID.
+
+Key events: `session:data`, `session:state`, `session:closed`, `session:raw:data`, `session:github:repos`, `session:secret:prompt`/`session:secret:response`, `session:hostkey:verify`/`session:hostkey:response`.
+
+## WKWebView Constraints (Critical)
+
+The macOS webview silently blocks or breaks several standard web APIs. These constraints affect every frontend change:
+
+1. **No `window.confirm()`, `window.prompt()`, `window.alert()`** — they either return false/null silently or do nothing. All user prompts must use the custom modal system (DOM-based backdrop + modal with `is-visible` class toggling).
+
+2. **No ES modules** — `<script type="module">` fails silently. All JS files use plain `<script>` tags and IIFE wrappers: `(function() { ... })();`
+
+3. **Click swallowing on text-selectable elements** — WKWebView initiates a text selection gesture on `mousedown` for `<div>` elements, which swallows the first `click` event (appears to require double-click). Fix: add `mousedown` handler with `e.preventDefault()` on any clickable non-input element (section headers, list items, etc.).
+
+4. **Modal visibility pattern** — both `.modal-backdrop` AND `.modal` elements start with `opacity: 0; visibility: hidden` in CSS. You must add the `is-visible` class to **both** elements, not just the backdrop.
+
+5. **Wails runtime injection** — `window.go` and `window.runtime` are injected by Wails before scripts execute. Do NOT add explicit script tags for Wails scripts. The frontend polls for their availability at startup (max 5s).
+
+## Conventions
+
+**Language:** All code comments in British English (colour, initialise, behaviour, etc.).
+
+**Go patterns:**
+- String-typed enums: `type Protocol string` with `const ProtocolSSH Protocol = "ssh"` etc.
+- Protocol configs are pointer fields on `Profile` (`SSH *SSHConfig`, `Telnet *TelnetConfig`, etc.) — nil when not applicable
+- `NewProfile(protocol)` factory in `defaults.go` populates sensible defaults per protocol
+- Storage uses `nullableJSON()` helper to write nil for unused config columns
+- Tests use `t.TempDir()` for isolation, `t.Fatalf()` for setup failures
+
+**Frontend patterns:**
+- Every JS file is IIFE-wrapped and exports to `window.NexusTerminal` namespace
+- Script load order matters (defined in `index.html`) — utils → state → notifications → sidebar → tabs → terminal → profiles → raw → github → settings → commands → secrets → app
+- DOM helpers: `createElement(tag, className, attrs)` from utils.js (supports `textContent`, `innerHTML`, `dataset`, `on*` event handlers)
+- Profile editor uses `_renderSection(title, fields)` pattern with `_field(type, name, label, value, opts)` helper for form generation
+- `protocolColour()` returns CSS class names like `proto-ssh`; tab badges use `badge-ssh` class naming (different pattern)
+
+**CSS patterns:**
+- Design tokens in `tokens.css`: `--bg-base`, `--bg-surface`, `--bg-elevated`, `--text-primary`, `--accent`, `--protocol-ssh`, etc.
+- Dark charcoal palette — not Material Design literally, but Material-inspired layering
+- Protocol colours: SSH=teal `#4ecdc4`, Telnet=amber `#ffa726`, RAW=purple `#ab47bc`, GitHub=indigo `#7c8aff`
+
+**Adding a new protocol:**
+1. Add `Protocol` constant + config struct in `models/models.go`
+2. Add defaults in `models/defaults.go` `NewProfile()` switch
+3. Create client package in `internal/<proto>client/`
+4. Add `connect<Proto>()` in `sessions/manager.go` + case in `Connect()` switch
+5. Add API methods in `api/api.go` if needed
+6. Add DB migration in `storage/migrations/` (update CHECK constraint, add config column)
+7. Update `storage/store.go`: all SELECT/INSERT/UPDATE queries + both scan functions
+8. Frontend: add DEFAULTS in `profiles.js`, render sections, collect form values, protocol tab
+9. Frontend: add viewer in new JS file (IIFE-wrapped), include in `index.html`, wire in `app.js`
+10. Add CSS: protocol colour token, sidebar indicator, tab badge, viewer styles
+
+**Database migrations:**
+- Numbered SQL files: `001_initial.sql`, `002_github_protocol.sql`, etc.
+- Each must `INSERT INTO schema_version (version, applied_at) VALUES (N, datetime('now'))` at the end
+- SQLite has no `ALTER COLUMN` — use the recreate-table pattern (CREATE new → INSERT INTO new SELECT FROM old → DROP old → ALTER TABLE RENAME)
+- Every query in `store.go` that touches the profiles table must be updated when columns change (there are ~8 SELECT column lists + 2 scan functions)
diff --git a/build/nexus-ssh-icon.svg b/build/nexus-ssh-icon.svg
new file mode 100644
index 0000000..00c16bf
--- /dev/null
+++ b/build/nexus-ssh-icon.svg
@@ -0,0 +1,137 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024">
+  <defs>
+    <!-- Background gradient: deep navy -->
+    <linearGradient id="bgGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0D1117;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#1A1F2E;stop-opacity:1" />
+    </linearGradient>
+
+    <!-- Cyan glow for terminal elements -->
+    <linearGradient id="cyanGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#00D4FF;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#00FF88;stop-opacity:1" />
+    </linearGradient>
+
+    <!-- Inner glow effect for terminal text -->
+    <filter id="glow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="8" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+
+    <!-- Subtle glow for grid lines -->
+    <filter id="softGlow" x="-10%" y="-10%" width="120%" height="120%">
+      <feGaussianBlur stdDeviation="3" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+
+    <!-- Clip to rounded rect -->
+    <clipPath id="roundedClip">
+      <rect x="0" y="0" width="1024" height="1024" rx="224" ry="224"/>
+    </clipPath>
+  </defs>
+
+  <!-- Rounded rectangle background -->
+  <rect x="0" y="0" width="1024" height="1024" rx="224" ry="224" fill="url(#bgGrad)"/>
+
+  <!-- Clipped content group -->
+  <g clip-path="url(#roundedClip)">
+
+    <!-- Subtle grid lines (circuit board / network feel) -->
+    <g opacity="0.07" stroke="#00D4FF" stroke-width="1.5" filter="url(#softGlow)">
+      <!-- Horizontal lines -->
+      <line x1="0" y1="200" x2="1024" y2="200"/>
+      <line x1="0" y1="350" x2="1024" y2="350"/>
+      <line x1="0" y1="500" x2="1024" y2="500"/>
+      <line x1="0" y1="650" x2="1024" y2="650"/>
+      <line x1="0" y1="800" x2="1024" y2="800"/>
+      <!-- Vertical lines -->
+      <line x1="200" y1="0" x2="200" y2="1024"/>
+      <line x1="350" y1="0" x2="350" y2="1024"/>
+      <line x1="500" y1="0" x2="500" y2="1024"/>
+      <line x1="650" y1="0" x2="650" y2="1024"/>
+      <line x1="800" y1="0" x2="800" y2="1024"/>
+    </g>
+
+    <!-- Network node dots at grid intersections (subtle) -->
+    <g opacity="0.12" fill="#00D4FF">
+      <circle cx="200" cy="200" r="4"/>
+      <circle cx="350" cy="200" r="4"/>
+      <circle cx="500" cy="200" r="4"/>
+      <circle cx="650" cy="200" r="4"/>
+      <circle cx="800" cy="200" r="4"/>
+      <circle cx="200" cy="350" r="4"/>
+      <circle cx="350" cy="350" r="4"/>
+      <circle cx="650" cy="350" r="4"/>
+      <circle cx="800" cy="350" r="4"/>
+      <circle cx="200" cy="500" r="4"/>
+      <circle cx="800" cy="500" r="4"/>
+      <circle cx="200" cy="650" r="4"/>
+      <circle cx="350" cy="650" r="4"/>
+      <circle cx="650" cy="650" r="4"/>
+      <circle cx="800" cy="650" r="4"/>
+      <circle cx="200" cy="800" r="4"/>
+      <circle cx="350" cy="800" r="4"/>
+      <circle cx="500" cy="800" r="4"/>
+      <circle cx="650" cy="800" r="4"/>
+      <circle cx="800" cy="800" r="4"/>
+    </g>
+
+    <!-- Central terminal window panel -->
+    <rect x="112" y="240" width="800" height="544" rx="16" ry="16"
+          fill="#0A0E17" fill-opacity="0.85"
+          stroke="#00D4FF" stroke-width="1.5" stroke-opacity="0.3"/>
+
+    <!-- Terminal title bar -->
+    <rect x="112" y="240" width="800" height="52" rx="16" ry="16"
+          fill="#161B27" fill-opacity="0.9"/>
+    <!-- Fix bottom corners of title bar -->
+    <rect x="112" y="268" width="800" height="24"
+          fill="#161B27" fill-opacity="0.9"/>
+
+    <!-- Window control dots -->
+    <circle cx="162" cy="266" r="10" fill="#FF5F57"/>
+    <circle cx="198" cy="266" r="10" fill="#FFBD2E"/>
+    <circle cx="234" cy="266" r="10" fill="#28C840"/>
+
+    <!-- Title bar text: "nexus ssh" -->
+    <text x="512" y="273" font-family="'SF Mono', 'Courier New', monospace"
+          font-size="20" fill="#8892A4" text-anchor="middle" dominant-baseline="middle"
+          letter-spacing="3">nexus — ssh</text>
+
+    <!-- Terminal separator line -->
+    <line x1="112" y1="292" x2="912" y2="292" stroke="#00D4FF" stroke-width="1" stroke-opacity="0.2"/>
+
+    <!-- MAIN TERMINAL CONTENT -->
+    <!-- Line 1: prompt line -->
+    <text x="152" y="360" font-family="'SF Mono', 'Courier New', monospace"
+          font-size="38" fill="#8892A4" filter="url(#softGlow)">user@nexus:~$</text>
+
+    <!-- THE BIG PROMPT SYMBOL: ">_" — cyan glowing, centered -->
+    <text x="512" y="560" font-family="'SF Mono', 'Courier New', monospace"
+          font-size="260" font-weight="bold"
+          fill="url(#cyanGrad)"
+          text-anchor="middle" dominant-baseline="middle"
+          filter="url(#glow)">&gt;_</text>
+
+    <!-- Blinking cursor line at bottom of terminal -->
+    <rect x="152" y="726" width="22" height="36" rx="2" ry="2"
+          fill="#00D4FF" opacity="0.9" filter="url(#softGlow)"/>
+
+    <!-- Bottom status line -->
+    <text x="740" y="748" font-family="'SF Mono', 'Courier New', monospace"
+          font-size="22" fill="#00FF88" fill-opacity="0.6" text-anchor="end">SSH v2  AES-256</text>
+
+  </g>
+
+  <!-- Outer border glow (subtle cyan rim) -->
+  <rect x="2" y="2" width="1020" height="1020" rx="223" ry="223"
+        fill="none"
+        stroke="url(#cyanGrad)" stroke-width="4" stroke-opacity="0.25"/>
+</svg>