@termfleet/lucarne 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @termfleet/lucarne
+
+The **optional bridge** between [`lucarne`](https://www.npmjs.com/package/lucarne)
+(a standalone browser-session engine) and a **termfleet** console.
+
+termfleet does not depend on lucarne, and lucarne knows nothing of termfleet —
+this small process is the *only* thing that speaks both. It presents a running
+lucarne daemon to a termfleet console as a **bare-pointer provider** whose windows
+are the session **portholes**. Browser sessions then appear on the canvas next to
+your terminals, reachable from your phone through the console's existing tunnel.
+
+```
+termfleet console ──proxy──▶ @termfleet/lucarne ──proxy──▶ lucarne daemon
+   (you, remote)              (the bridge)                  (browsers, local)
+```
+
+## Run
+
+```sh
+# 1. a lucarne daemon (browsers live here, on your machine)
+npx lucarne serve
+
+# 2. the bridge (registers with your console, reflects sessions as windows)
+LUCARNE_URL=http://127.0.0.1:7800 \
+TERMFLEET_CONSOLE_URL=http://127.0.0.1:7373 \
+npx @termfleet/lucarne
+
+# 3. create a browser session — it shows up as a window in the console
+npx lucarne create -b native -p work
+```
+
+## What it serves
+
+- `GET /healthz` — the termfleet identity gate (`{ ok, provider: "lucarne" }`)
+- `GET /api/mirror/snapshot` — one iframe window per lucarne session
+- `/sessions/:id/view*` — reverse-proxied to lucarne's porthole (the bridge injects
+  the `LUCARNE_TOKEN`, so it never appears in the browser)
+
+## Env
+
+| var | default | purpose |
+|---|---|---|
+| `LUCARNE_URL` | `http://127.0.0.1:7800` | the lucarne daemon |
+| `LUCARNE_TOKEN` | — | lucarne bearer token (injected when proxying) |
+| `TERMFLEET_CONSOLE_URL` | `http://127.0.0.1:7373` | console to self-register with |
+| `BRIDGE_HOST` / `BRIDGE_PORT` | `127.0.0.1` / `7950` | bind address |
+| `BRIDGE_PUBLIC_URL` | `http://HOST:PORT` | the origin it registers as |
+
+## Boundaries
+
+This package depends on neither termfleet core nor lucarne at build time (it talks
+to both over HTTP). It is **optional** — uninstall it and termfleet is terminals-only,
+lucarne is standalone, and nothing breaks. Drive remains local (an agent hits
+lucarne's CDP on the same host); only the *view* crosses the tunnel.
+
+MIT © Aaron Volter

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// @termfleet/lucarne — the optional bridge. Presents a running lucarne daemon to
+// a termfleet console as a bare-pointer provider whose windows are the session
+// portholes. termfleet never imports lucarne; lucarne never imports termfleet;
+// THIS is the only process that speaks both.
+//
+//   • GET /healthz                 → identity gate ({ ok, provider })
+//   • GET /api/mirror/snapshot     → one iframe window per lucarne session
+//   • /sessions/:id/view*          → reverse-proxied to lucarne's porthole
+//                                    (so the console can proxy it over the tunnel)
+import http from "node:http";
+const LUCARNE_URL = process.env.LUCARNE_URL ?? "http://127.0.0.1:7800";
+const LUCARNE_TOKEN = process.env.LUCARNE_TOKEN;
+const CONSOLE_URL = process.env.TERMFLEET_CONSOLE_URL ?? "http://127.0.0.1:7373";
+const HOST = process.env.BRIDGE_HOST ?? "127.0.0.1";
+const PORT = Number(process.env.BRIDGE_PORT ?? 7950);
+const PUBLIC_URL = process.env.BRIDGE_PUBLIC_URL ?? `http://${HOST}:${PORT}`;
+const PROVIDER_KEY = encodeURIComponent(PUBLIC_URL);
+const windowIds = new Map();
+let nextWindowId = 1;
+let revision = 0;
+async function lucarne(path) {
+    const headers = {};
+    if (LUCARNE_TOKEN)
+        headers["authorization"] = `Bearer ${LUCARNE_TOKEN}`;
+    const res = await fetch(LUCARNE_URL + path, { headers });
+    return res.json();
+}
+function makeWindow(sessionId, name) {
+    let wid = windowIds.get(sessionId);
+    if (wid === undefined) {
+        wid = nextWindowId++;
+        windowIds.set(sessionId, wid);
+    }
+    const i = wid - 1, col = i % 2, row = Math.floor(i / 2);
+    const W = 960, H = 680, gx = 40, gy = 40;
+    const left = 40 + col * (W + gx), top = 40 + row * (H + gy);
+    const tbH = 30;
+    return {
+        id: wid,
+        name,
+        windowKind: "iframe",
+        iframe: {
+            src: `/sessions/${sessionId}/view/`,
+            // load through the console proxy → this bridge → lucarne
+            resolvedSrc: `/providers/${PROVIDER_KEY}/sessions/${sessionId}/view/`,
+        },
+        bounds: { left, top, right: left + W, bottom: top + H, width: W, height: H },
+        chrome: {
+            id: wid,
+            title: name,
+            titlebar: { left, top, width: W, height: tbH },
+            closeButton: { left: left + W - 30, top: top + 8, width: 16, height: 16 },
+            minimizeButton: { left: left + W - 54, top: top + 8, width: 16, height: 16 },
+            fullscreenButton: { left: left + W - 78, top: top + 8, width: 16, height: 16 },
+            terminalViewport: { left, top: top + tbH, width: W, height: H - tbH },
+            textArea: { left, top: top + tbH, width: W, height: H - tbH },
+            scrollbar: { left: left + W - 10, top: top + tbH, width: 10, height: H - tbH },
+        },
+        terminalArea: { left, top: top + tbH, width: W, height: H - tbH },
+        terminalSize: { columns: 120, rows: 32 },
+    };
+}
+async function snapshot() {
+    const sessions = (await lucarne("/sessions").catch(() => []));
+    const windows = sessions.map((s) => makeWindow(s.id, `${s.id} (${s.backend})`));
+    return {
+        epoch: "lucarne-bridge",
+        instanceId: "lucarne-bridge",
+        provider: "lucarne",
+        revision: ++revision,
+        observedAt: new Date().toISOString(),
+        displayBounds: { left: 0, top: 0, right: 1920, bottom: 1080, width: 1920, height: 1080 },
+        windows,
+        lifecycle: { pid: process.pid, panes: [] },
+    };
+}
+// reverse-proxy /sessions/:id/view* → lucarne (inject the lucarne token here)
+function proxyView(req, res, rest) {
+    const target = new URL(LUCARNE_URL);
+    const qs = LUCARNE_TOKEN ? `?token=${encodeURIComponent(LUCARNE_TOKEN)}` : "";
+    const preq = http.request({
+        hostname: target.hostname,
+        port: target.port,
+        method: req.method,
+        path: `/sessions/${rest}${qs}`,
+        headers: { ...req.headers, host: target.host },
+    }, (pres) => {
+        res.writeHead(pres.statusCode ?? 502, pres.headers);
+        pres.pipe(res);
+    });
+    preq.on("error", () => { try {
+        res.writeHead(502);
+        res.end("bridge: lucarne unreachable");
+    }
+    catch { /* */ } });
+    req.pipe(preq);
+}
+const server = http.createServer(async (req, res) => {
+    try {
+        const pathname = new URL(req.url ?? "/", "http://x").pathname;
+        if (pathname === "/healthz") {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify({ ok: true, provider: "lucarne", instanceId: "lucarne-bridge", build: { version: "0.1.0" } }));
+            return;
+        }
+        if (pathname === "/api/mirror/snapshot") {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify(await snapshot()));
+            return;
+        }
+        const view = pathname.match(/^\/sessions\/(.*)$/);
+        if (view) {
+            proxyView(req, res, view[1]);
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    }
+    catch (e) {
+        res.writeHead(500, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: String(e.message ?? e) }));
+    }
+});
+async function registerWithConsole() {
+    for (let i = 0; i < 5; i++) {
+        try {
+            const r = await fetch(`${CONSOLE_URL}/api/registry/local-providers`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ baseUrl: PUBLIC_URL, label: "lucarne" }),
+            });
+            if (r.ok) {
+                process.stdout.write(`registered with console ${CONSOLE_URL}\n`);
+                return;
+            }
+            process.stderr.write(`register attempt ${i + 1}: HTTP ${r.status} ${await r.text()}\n`);
+        }
+        catch (e) {
+            process.stderr.write(`register attempt ${i + 1}: ${e.message}\n`);
+        }
+        await new Promise((res) => setTimeout(res, 1000));
+    }
+}
+server.listen(PORT, HOST, () => {
+    process.stdout.write(`@termfleet/lucarne bridge on ${PUBLIC_URL} → lucarne ${LUCARNE_URL}\n`);
+    void registerWithConsole();
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@termfleet/lucarne",
+  "version": "0.1.0",
+  "description": "Optional bridge that surfaces a lucarne browser-session engine inside a termfleet console as iframe-porthole windows. termfleet and lucarne stay independent; this is the only module that knows both.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aaron Volter",
+  "engines": { "node": ">=22" },
+  "bin": { "termfleet-lucarne": "dist/index.js" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "lucarne": ">=0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "lucarne": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}