Add .github/copilot-instructions.md for AI-assisted development
Documents build commands, architecture, WKWebView constraints, conventions, the protocol addition checklist, and database migration patterns.
This commit is contained in:
@@ -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)
|
||||
@@ -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)">>_</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>
|
||||
|
After Width: | Height: | Size: 5.4 KiB |
Reference in New Issue
Block a user