khal-os 1.260324.2

package/CLAUDE.md

@@ -0,0 +1,117 @@
+# Khal
+
+Next.js desktop environment with NATS-based services.
+
+## Running
+
+All processes managed via PM2 from project root:
+
+```bash
+pm2 start ecosystem.config.cjs   # start all
+pm2 restart <name>                # restart one (does NOT reload config)
+pm2 delete <name> && pm2 start ecosystem.config.cjs --only <name>  # reload config
+pm2 logs <name> --lines 20       # view logs
+pm2 flush <name>                  # clear logs
+```
+
+### PM2 Processes
+
+| Name | What | Port |
+|------|------|------|
+| `khal-nats` | NATS server (`nats.conf`, JetStream enabled) | 4222 (localhost only) |
+| `khal-services` | Service loader — auto-discovers `**/service/index.ts` under `src/components/apps/`. The dev3000 service spawns d3k which runs `bun dev` (headless Chrome + log capture). | 8888 (via d3k) |
+| `khal-ws-bridge` | WebSocket-to-NATS bridge (`src/lib/ws-server.ts`) | 4280 |
+
+### Service Loader Runtime
+
+Services run under **Bun** by default. Services that need Node.js (e.g. `node-pty`) place a `service/runtime` file containing `node` — the loader spawns them via `npx tsx` instead.
+
+- `node-pty` does NOT work under Bun (PTY gets SIGHUP immediately). The terminal service uses `runtime: node`.
+- `import.meta.dir` is Bun-only. Use `import.meta.dirname ?? dirname(fileURLToPath(import.meta.url))` for cross-runtime compat.
+- `import pty from 'node-pty'` fails under tsx (CJS compat). Use `import * as pty from 'node-pty'`.
+
+### Caddy (reverse proxy)
+
+- `dev.khal.namastex.io` → Next.js (:8888) + WS bridge (:4280 at `/ws/*`)
+- Caddyfile at `/etc/caddy/Caddyfile` (needs `sudo` to edit)
+- `sudo caddy validate --config /etc/caddy/Caddyfile && sudo caddy reload --config /etc/caddy/Caddyfile`
+
+## Architecture
+
+```
+Browser ↔ Caddy ↔ Next.js (UI, SSR)
+                ↔ WS bridge ↔ NATS ↔ Services (PTY, echo, …)
+```
+
+- **Browser**: `NatsClient` singleton connects to `/ws/nats`, provides `subscribe/publish/request`
+- **WS bridge**: multiplexes browser WS frames to NATS subjects (sub/unsub/pub/req)
+- **Services**: colocated with their UI app under `src/components/apps/<name>/service/`
+- **NATS subjects**: all prefixed `khal.` — see `src/lib/subjects.ts`
+
+### dev3000 (d3k — browser monitoring)
+
+- Service: `src/components/apps/dev3000/service/` (runs under Node/tsx)
+- UI: `src/components/apps/dev3000/` (Dev3000App, TimelineLog, ErrorsPanel, Sidebar)
+- d3k spawns headless Chrome + `bun dev` on port 8888, captures server logs, browser console, network requests, DOM events, and screenshots via CDP
+- Logs are tailed from `~/.d3k/khal-*/logs/` and published to NATS `khal.{orgId}.d3k.log`
+- d3k binary and Chrome are discovered at runtime (`findBin()`, `findChromeBin()`)
+- `VERCEL_SANDBOX=1` env disables d3k's health check (prevents crash loop under PM2)
+- Auto-restarts d3k on crash with 5s delay
+
+#### Machine auth bypass (OS_SECRET)
+
+d3k's headless Chrome needs to render `/desktop` without logging in. When `OS_SECRET` is set in `.env`:
+
+- **Middleware** (`src/middleware.ts`): detects `HeadlessChrome` User-Agent, sets `x-workos-middleware: true` header, skips WorkOS redirect. `withAuth()` returns `{ user: null }` gracefully.
+- **WS bridge** (`src/lib/ws-server.ts`): detects `HeadlessChrome` User-Agent, creates synthetic machine session (`userId: 'machine'`, `role: 'admin'`).
+- Desktop renders in `LOCAL_WORKSPACE_ID` mode (no real user context).
+- Only active on localhost; external traffic goes through Caddy → WorkOS auth as normal.
+
+#### agent-browser (CDP automation)
+
+```bash
+d3k cdp-port                                    # show CDP port (default 9222)
+d3k agent-browser --cdp 9222 screenshot out.png  # screenshot d3k's Chrome
+d3k agent-browser --cdp 9222 snapshot -i         # accessibility tree
+d3k agent-browser --cdp 9222 get url             # current URL
+d3k agent-browser --cdp 9222 get title           # page title
+d3k agent-browser --cdp 9222 click <selector>    # click element
+d3k agent-browser --cdp 9222 eval "document.title" # run JS
+```
+
+Requires `agent-browser` installed globally (`bun install -g agent-browser`).
+
+### Terminal (PTY via NATS)
+
+- Service: `src/components/apps/terminal/service/` (runs under Node/tsx)
+- UI: `src/components/apps/terminal/ui/`
+- Schemas: `src/components/apps/terminal/schema.ts` (TypeBox)
+- Sessions persist across page reloads (72h TTL, 1MB ring buffer)
+- Buffer replay is **client-initiated**: client subscribes first, then publishes `.replay`
+- `useNats()` hook → `subscribe/publish/request` over the WS bridge
+
+## Lint / Build
+
+```bash
+bun biome check --write .    # lint + format
+bunx tsc --noEmit             # typecheck
+bun next build               # production build
+```
+
+- Biome config: `biome.json` — `**/service/**` override allows console.log
+- `serverExternalPackages: ['node-pty']` in `next.config.ts`
+
+## Verification Gate
+
+Before claiming any work is complete, **run verification first**:
+
+1. `bun biome check .` — lint + format clean
+2. `bunx tsc --noEmit` — no type errors
+
+Never say "tests pass", "build succeeds", or "should work now" without showing command output.
+These hooks run automatically on Stop (after each response that edits .ts/.tsx files).
+
+## Hooks
+
+- **git-safety** (`PreToolUse/Bash`): blocks `push --force`, `reset --hard`, `checkout .`, `clean -f`, `branch -D`
+- **verify-build** (`Stop`): runs Biome + TypeScript check if .ts/.tsx files were modified in the last 60s

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vercel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# Khal
+
+A desktop-in-browser OS shell built with Next.js, React, and Tailwind CSS.
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm dev          # Next.js on port 1111
+node pty-server.mjs  # PTY + WebSocket on port 1112
+```
+
+Open http://localhost:1111 to see the desktop.
+
+## Default Apps
+
+- **Terminal** — Full terminal emulator (xterm.js + node-pty)
+- **Settings** — Theme switcher and desktop configuration
+- **Files** — Example stub app (replace with your own)
+
+## Adding a New App
+
+1. Create a component in `src/components/apps/<your-app>/`
+   - Must accept `{ windowId: string; meta?: Record<string, unknown> }`
+2. Register in `src/components/apps/app-registry.ts`
+3. Add a `DesktopEntry` in `src/stores/desktop-store.ts`
+4. (Optional) Set default window size in `src/lib/hooks/use-launch-app.ts`
+5. (Optional) Add a keyboard shortcut in `src/lib/keyboard/defaults.ts`
+
+## Architecture
+
+- **Window Manager** — Draggable, resizable windows with snap, minimize, maximize
+- **Taskbar** — App launcher, running apps, system tray, workspace switcher
+- **Workspaces** — Virtual desktops
+- **Keyboard Shortcuts** — Configurable global hotkeys
+- **Notifications** — Toast + notification center
+- **PTY Server** — WebSocket-based terminal backend with session persistence
+- **Theme System** — Light/dark mode via CSS custom properties

package/biome.json

@@ -0,0 +1,124 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.2/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true,
+		"defaultBranch": "main"
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab",
+		"indentWidth": 2,
+		"lineWidth": 120
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"a11y": {
+				"useButtonType": "off",
+				"useSemanticElements": "off",
+				"noStaticElementInteractions": "off",
+				"useKeyWithClickEvents": "off",
+				"noSvgWithoutTitle": "off",
+				"useFocusableInteractive": "off",
+				"useAriaPropsForRole": "off",
+				"noLabelWithoutControl": "off",
+				"useAriaPropsSupportedByRole": "off",
+				"noNoninteractiveTabindex": "off"
+			},
+			"suspicious": {
+				"noExplicitAny": "error",
+				"noConsole": "warn",
+				"noTsIgnore": "off",
+				"useBiomeIgnoreFolder": "off"
+			},
+			"style": {
+				"noUnusedTemplateLiteral": "error",
+				"useImportType": "off",
+				"noNonNullAssertion": "off",
+				"useTemplate": "off",
+				"useNodejsImportProtocol": "off",
+				"useConst": "error"
+			},
+			"correctness": {
+				"noUnusedImports": "error",
+				"noUnusedVariables": "error",
+				"noUnusedFunctionParameters": "error",
+				"useExhaustiveDependencies": "off",
+				"useHookAtTopLevel": "off"
+			},
+			"complexity": {
+				"useLiteralKeys": "off",
+				"noImportantStyles": "off",
+				"useOptionalChain": "off",
+				"noExcessiveCognitiveComplexity": "warn",
+				"useFlatMap": "error"
+			},
+			"performance": {
+				"noImgElement": "off"
+			}
+		}
+	},
+	"css": {
+		"parser": {
+			"cssModules": false,
+			"allowWrongLineComments": false
+		},
+		"linter": {
+			"enabled": false
+		}
+	},
+	"javascript": {
+		"globals": ["React"],
+		"formatter": {
+			"quoteStyle": "single",
+			"trailingCommas": "es5",
+			"semicolons": "always"
+		}
+	},
+	"files": {
+		"includes": [
+			"**",
+			"!node_modules/**",
+			"!.next/**",
+			"!**/dist/**",
+			"!.genie/**",
+			"!src/types/use-descendants.d.ts",
+			"!**/*.css"
+		]
+	},
+	"overrides": [
+		{
+			"includes": [
+				"scripts/**",
+				"src/lib/service-loader.ts",
+				"src/lib/nats.ts",
+				"src/lib/ws-bridge.ts",
+				"src/lib/ws-server.ts",
+				"**/service/**",
+				"src/app/api/webhooks/**",
+				"src/lib/auth/webhook-handler.ts",
+				"packages/os-cli/**"
+			],
+			"linter": {
+				"rules": {
+					"suspicious": {
+						"noConsole": "off"
+					}
+				}
+			}
+		},
+		{
+			"includes": ["sentry.*.config.ts", "instrumentation.ts"],
+			"linter": {
+				"rules": {
+					"style": {
+						"useImportType": "off"
+					}
+				}
+			}
+		}
+	]
+}