@atolljs/devtools 0.1.7

package/dist/protocol.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The wire protocol between instrumented apps, the devtools server, and
+ * dashboard viewers — all JSON text frames over WebSocket.
+ *
+ *   app      → server  /events   { hello } then { batch } frames
+ *   server   → viewer  /view     { sessions } on connect, then { batch } per app frame
+ */
+import type { EmittedDevtoolsEvent } from '@atolljs/core';
+/** Identifies one connected app (one page, one Node process). */
+export interface SessionInfo {
+    /** Client-generated id — stable for the socket's lifetime. */
+    id: string;
+    /** Human label — config `name`, app title, process argv, etc. */
+    name?: string;
+    runtime: 'browser' | 'node';
+    /** Browser location.href / process title — whatever helps identify it. */
+    hint?: string;
+    /**
+     * Set by the server once the app's socket closes. Closed sessions are
+     * retained (bounded) so dashboards can keep post-mortem history instead of
+     * orphaning their pools/tasks/memory state.
+     */
+    closed?: boolean;
+    /** Server clock (ms) when the socket closed — drives the cleanup sweep. */
+    closedAt?: number;
+    /** Viewer-pinned closed sessions are exempt from the retention sweep. */
+    pinned?: boolean;
+}
+export interface HelloMessage {
+    type: 'hello';
+    session: SessionInfo;
+}
+export interface BatchMessage {
+    type: 'batch';
+    events: EmittedDevtoolsEvent[];
+}
+/** What an instrumented app sends on /events. */
+export type ClientMessage = HelloMessage | BatchMessage;
+/** What a dashboard viewer receives on /view. */
+export type ViewerMessage = {
+    type: 'sessions';
+    sessions: SessionInfo[];
+} | {
+    type: 'batch';
+    session: SessionInfo;
+    events: EmittedDevtoolsEvent[];
+};
+/** What a dashboard viewer sends on /view. */
+export type ViewerRequest = 
+/** Drop a closed session and its replayed history. Live sessions are ignored. */
+{
+    type: 'dismiss';
+    sessionId: string;
+}
+/** Exempt a closed session from the retention sweep (or release it). */
+ | {
+    type: 'pin';
+    sessionId: string;
+    pinned: boolean;
+};
+/**
+ * Pure-client transport: frames on a same-origin BroadcastChannel named
+ * 'atoll-devtools'. Origin scoping replaces the server's session list —
+ * a dashboard on the app's own origin sees exactly the apps on that origin.
+ */
+export declare const DEVTOOLS_CHANNEL = "atoll-devtools";
+export type BroadcastMessage = {
+    type: 'hello';
+    session: SessionInfo;
+} | {
+    type: 'batch';
+    session: SessionInfo;
+    events: EmittedDevtoolsEvent[];
+}
+/** Posted on close/pagehide so dashboards can mark the session ended. */
+ | {
+    type: 'bye';
+    sessionId: string;
+}
+/** Dashboard announcing itself — apps re-hello and replay their tail. */
+ | {
+    type: 'view';
+};

package/dist/server.d.ts

@@ -0,0 +1,23 @@
+import type { SessionInfo } from './protocol.js';
+export interface DevtoolsServerOptions {
+    /** Default 4780. 0 picks an ephemeral port (tests). */
+    port?: number;
+    /** Host — bound to loopback only; the dashboard has no auth. */
+    host?: string;
+    /** Static dashboard directory — defaults to the packaged app/. */
+    appDir?: string;
+    /** Batches kept for viewer replay (default 500). */
+    replayBatches?: number;
+    /** Closed-session retention before auto-cleanup (default 30min). */
+    closedTtlMs?: number;
+    /** How often the retention sweep runs (default 60s — tests lower it). */
+    sweepMs?: number;
+    onListen?: (url: string) => void;
+}
+export interface DevtoolsServer {
+    readonly port: number;
+    readonly url: string;
+    sessions(): SessionInfo[];
+    close(): Promise<void>;
+}
+export declare function createDevtoolsServer(opts?: DevtoolsServerOptions): Promise<DevtoolsServer>;

package/dist/server.js

@@ -0,0 +1,296 @@
+// src/server.ts
+import { createServer } from "node:http";
+import { existsSync, readFileSync } from "node:fs";
+import { join, normalize, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/ws.ts
+import { createHash, randomBytes } from "node:crypto";
+var WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+var OPCODES = { continuation: 0, text: 1, close: 8, ping: 9, pong: 10 };
+var acceptKey = (key) => createHash("sha1").update(key + WS_GUID).digest("base64");
+function encodeTextFrame(text) {
+  const payload = Buffer.from(text, "utf8");
+  const len = payload.length;
+  let header;
+  if (len < 126) {
+    header = Buffer.from([128 | OPCODES.text, len]);
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 128 | OPCODES.text;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 128 | OPCODES.text;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  return Buffer.concat([header, payload]);
+}
+var encodeControl = (opcode, payload = Buffer.alloc(0)) => Buffer.concat([Buffer.from([128 | opcode, payload.length]), payload]);
+function decodeFrames(buf) {
+  const frames = [];
+  for (; ; ) {
+    if (buf.length < 2) break;
+    const fin = (buf[0] & 128) !== 0;
+    const opcode = buf[0] & 15;
+    const masked = (buf[1] & 128) !== 0;
+    let len = buf[1] & 127;
+    let off = 2;
+    if (len === 126) {
+      if (buf.length < off + 2) break;
+      len = buf.readUInt16BE(off);
+      off += 2;
+    } else if (len === 127) {
+      if (buf.length < off + 8) break;
+      len = Number(buf.readBigUInt64BE(off));
+      off += 8;
+    }
+    const maskLen = masked ? 4 : 0;
+    if (buf.length < off + maskLen + len) break;
+    let payload = buf.subarray(off + maskLen, off + maskLen + len);
+    if (masked) {
+      const mask = buf.subarray(off, off + 4);
+      const un = Buffer.alloc(len);
+      for (let i = 0; i < len; i++) un[i] = payload[i] ^ mask[i & 3];
+      payload = un;
+    }
+    buf = buf.subarray(off + maskLen + len);
+    frames.push({ fin, opcode, payload });
+  }
+  return { frames, rest: buf };
+}
+function acceptWebSocket(req, socket) {
+  const key = req.headers["sec-websocket-key"];
+  socket.write(
+    `HTTP/1.1 101 Switching Protocols\r
+Upgrade: websocket\r
+Connection: Upgrade\r
+Sec-WebSocket-Accept: ${acceptKey(String(key ?? randomBytes(16).toString("base64")))}\r
+\r
+`
+  );
+  let buf = Buffer.alloc(0);
+  let fragments = [];
+  let closed = false;
+  const conn = {
+    send(text) {
+      if (!closed) socket.write(encodeTextFrame(text));
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      try {
+        socket.write(encodeControl(OPCODES.close));
+        socket.end();
+      } catch {
+      }
+      conn.onClose?.();
+    },
+    onMessage: null,
+    onClose: null,
+    get closed() {
+      return closed;
+    }
+  };
+  const die = () => {
+    if (!closed) {
+      closed = true;
+      conn.onClose?.();
+    }
+  };
+  const drain = () => {
+    const { frames, rest } = decodeFrames(buf);
+    buf = rest;
+    for (const { fin, opcode, payload } of frames) {
+      if (opcode === OPCODES.close) {
+        conn.close();
+        return;
+      }
+      if (opcode === OPCODES.ping) {
+        socket.write(encodeControl(OPCODES.pong, payload));
+        continue;
+      }
+      if (opcode === OPCODES.pong) continue;
+      if (opcode === OPCODES.text || opcode === OPCODES.continuation) {
+        fragments.push(payload);
+        if (fin) {
+          const text = Buffer.concat(fragments).toString("utf8");
+          fragments = [];
+          conn.onMessage?.(text);
+        }
+      }
+    }
+  };
+  socket.on("data", (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    drain();
+  });
+  socket.on("error", die);
+  socket.on("close", die);
+  return conn;
+}
+
+// src/server.ts
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".map": "application/json"
+};
+var defaultAppDir = () => fileURLToPath(new URL("../app/", import.meta.url));
+var serveStatic = (appDir, req, res) => {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  let path = normalize(decodeURIComponent(url.pathname)).replace(/^([/\\])+/, "");
+  if (path === "" || path === ".") path = "index.html";
+  const file = join(appDir, path);
+  if (!file.startsWith(normalize(appDir)) || !existsSync(file)) {
+    res.writeHead(404).end("not found");
+    return;
+  }
+  res.writeHead(200, { "content-type": MIME[extname(file)] ?? "application/octet-stream" });
+  res.end(readFileSync(file));
+};
+function createDevtoolsServer(opts = {}) {
+  const host = opts.host ?? "127.0.0.1";
+  const appDir = opts.appDir ?? defaultAppDir();
+  const replayCap = opts.replayBatches ?? 500;
+  const viewers = /* @__PURE__ */ new Set();
+  const sessions = /* @__PURE__ */ new Map();
+  const closedSessions = [];
+  const closedCap = 20;
+  const closedTtlMs = opts.closedTtlMs ?? 30 * 60 * 1e3;
+  const tail = [];
+  const sessionList = () => [...sessions.values(), ...closedSessions];
+  const evictClosed = (sessionId) => {
+    const i = closedSessions.findIndex((s) => s.id === sessionId);
+    if (i < 0) return false;
+    closedSessions.splice(i, 1);
+    for (let j = tail.length - 1; j >= 0; j--) {
+      const m = tail[j];
+      if (m.type === "batch" && m.session.id === sessionId) tail.splice(j, 1);
+    }
+    return true;
+  };
+  const broadcast = (msg) => {
+    if (msg.type === "batch") {
+      tail.push(msg);
+      if (tail.length > replayCap) tail.shift();
+    }
+    const text = JSON.stringify(msg);
+    for (const v of viewers) v.send(text);
+  };
+  const server = createServer((req, res) => {
+    if (req.url === "/health") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ ok: true, sessions: sessions.size }));
+      return;
+    }
+    serveStatic(appDir, req, res);
+  });
+  server.on("upgrade", (req, socket, head) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname !== "/events" && url.pathname !== "/view") {
+      socket.destroy();
+      return;
+    }
+    const conn = acceptWebSocket(req, socket);
+    if (head?.length) socket.unshift(head);
+    if (url.pathname === "/view") {
+      viewers.add(conn);
+      conn.onClose = () => viewers.delete(conn);
+      conn.onMessage = (text) => {
+        let msg;
+        try {
+          msg = JSON.parse(text);
+        } catch {
+          return;
+        }
+        if (msg.type === "dismiss") {
+          if (evictClosed(msg.sessionId)) {
+            broadcast({ type: "sessions", sessions: sessionList() });
+          }
+        } else if (msg.type === "pin") {
+          const s = closedSessions.find((s2) => s2.id === msg.sessionId);
+          if (!s || s.pinned === msg.pinned) return;
+          s.pinned = msg.pinned;
+          broadcast({ type: "sessions", sessions: sessionList() });
+        }
+      };
+      conn.send(JSON.stringify({ type: "sessions", sessions: sessionList() }));
+      for (const msg of tail) conn.send(JSON.stringify(msg));
+      return;
+    }
+    let greeted = false;
+    conn.onMessage = (text) => {
+      let msg;
+      try {
+        msg = JSON.parse(text);
+      } catch {
+        return;
+      }
+      if (msg.type === "hello") {
+        greeted = true;
+        sessions.set(conn, msg.session);
+        broadcast({ type: "sessions", sessions: sessionList() });
+        return;
+      }
+      if (msg.type === "batch" && greeted) {
+        broadcast({ type: "batch", session: sessions.get(conn), events: msg.events });
+      }
+    };
+    conn.onClose = () => {
+      const info = sessions.get(conn);
+      if (sessions.delete(conn) && info) {
+        info.closed = true;
+        info.closedAt = Date.now();
+        closedSessions.push(info);
+        if (closedSessions.length > closedCap) {
+          const i = closedSessions.findIndex((s) => !s.pinned);
+          if (i >= 0) evictClosed(closedSessions[i].id);
+        }
+        broadcast({ type: "sessions", sessions: sessionList() });
+      }
+    };
+  });
+  const sweep = setInterval(() => {
+    const cutoff = Date.now() - closedTtlMs;
+    let changed = false;
+    for (const s of [...closedSessions]) {
+      if (!s.pinned && s.closedAt !== void 0 && s.closedAt < cutoff) {
+        changed = evictClosed(s.id) || changed;
+      }
+    }
+    if (changed) broadcast({ type: "sessions", sessions: sessionList() });
+  }, opts.sweepMs ?? 6e4);
+  sweep.unref();
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(opts.port ?? 4780, host, () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : opts.port ?? 4780;
+      const url = `http://${host}:${port}`;
+      opts.onListen?.(url);
+      resolve({
+        port,
+        url,
+        sessions: () => [...sessions.values()],
+        close: () => new Promise((done) => {
+          clearInterval(sweep);
+          for (const v of viewers) v.close();
+          for (const c of sessions.keys()) c.close();
+          server.close(() => done());
+        })
+      });
+    });
+  });
+}
+export {
+  createDevtoolsServer
+};

package/dist/ws.d.ts

@@ -0,0 +1,43 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+export declare const OPCODES: {
+    readonly continuation: 0;
+    readonly text: 1;
+    readonly close: 8;
+    readonly ping: 9;
+    readonly pong: 10;
+};
+export interface WsConnection {
+    /** Queue a text frame — safe before/without concern for socket state. */
+    send(text: string): void;
+    close(): void;
+    onMessage: ((text: string) => void) | null;
+    onClose: (() => void) | null;
+    readonly closed: boolean;
+}
+/** Sec-WebSocket-Accept for a client key. */
+export declare const acceptKey: (key: string) => string;
+/** One unmasked text frame (server→client frames MUST NOT be masked). */
+export declare function encodeTextFrame(text: string): Buffer;
+export interface WsFrame {
+    fin: boolean;
+    opcode: number;
+    payload: Buffer<ArrayBufferLike>;
+}
+/**
+ * Decode as many complete frames as `buf` holds — shared by the server-side
+ * drain (masked client frames) and the Node client (unmasked server frames).
+ * Returns the frames plus the unconsumed remainder.
+ */
+export declare function decodeFrames(buf: Buffer<ArrayBufferLike>): {
+    frames: WsFrame[];
+    rest: Buffer<ArrayBufferLike>;
+};
+/** One masked text frame (client→server frames MUST be masked per RFC6455). */
+export declare function encodeMaskedTextFrame(text: string): Buffer;
+export declare const encodeMaskedControl: (opcode: number, payload?: Buffer<ArrayBufferLike>) => Buffer;
+/**
+ * Complete the upgrade handshake on `socket` and return a framed connection.
+ * Caller routes on req.url first — this writes the 101 response.
+ */
+export declare function acceptWebSocket(req: IncomingMessage, socket: Duplex): WsConnection;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@atolljs/devtools",
+  "version": "0.1.7",
+  "description": "Devtools transport + local dashboard server for AtollJS instrumentation events",
+  "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "atoll-devtools": "./dist/bin.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "app"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build-lib.mjs && esbuild src/bin.ts --bundle --format=esm --platform=node --target=node20.12 --outfile=dist/bin.js",
+    "dev": "esbuild src/bin.ts --bundle --format=esm --platform=node --target=node20.12 --outfile=dist/bin.js && node dist/bin.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "peerDependencies": {
+    "@atolljs/core": "0.1.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwhenry3/atolljs",
+    "directory": "packages/devtools"
+  },
+  "bugs": {
+    "url": "https://github.com/jwhenry3/atolljs/issues"
+  },
+  "license": "MIT"
+}

package/src/bin.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/** `atoll-devtools [--port N]` — boot the local devtools server + dashboard. */
+import { createDevtoolsServer } from './server';
+
+const arg = (name: string): string | undefined => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+};
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log('usage: atoll-devtools [--port N]  — serve the devtools dashboard + event ingest (default port 4780)');
+  process.exit(0);
+}
+
+const port = Number(arg('port') ?? 4780);
+const server = await createDevtoolsServer({
+  port: Number.isFinite(port) ? port : 4780,
+});
+
+console.log(`atoll devtools → ${server.url}`);
+console.log('  dashboard: ' + server.url);
+console.log('  ingest:    ' + server.url.replace('http://', 'ws://') + '/events');
+console.log('\nIn the app:  import { connectDevtools } from \'@atolljs/devtools\'; connectDevtools()');

package/src/broadcast.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure-client transport: instead of a WebSocket to a devtools server, the
+ * app publishes session/hello/batch/bye frames on a same-origin
+ * BroadcastChannel. Dashboards open on the app's own origin (the vite
+ * plugin serves the dashboard at /__atoll/) and listen on the same
+ * channel — so a dashboard can only ever see apps on its own origin, and
+ * no backend process is involved at all.
+ *
+ * Late-joining dashboards post { type: 'view' }; the app re-hellos and
+ * replays a bounded tail of recent batches so the view isn't empty.
+ */
+import {
+  installFetchProbe,
+  installMemoryProbe,
+  setDevtoolsSink,
+  type EmittedDevtoolsEvent,
+} from '@atolljs/core';
+import { DEVTOOLS_CHANNEL, type BroadcastMessage, type SessionInfo } from './protocol';
+import type { ConnectDevtoolsOptions, DevtoolsConnection } from './client';
+
+export function connectBroadcast(
+  opts: ConnectDevtoolsOptions,
+  session: SessionInfo,
+): DevtoolsConnection {
+  const bc = new BroadcastChannel(DEVTOOLS_CHANNEL);
+  const cap = opts.bufferCap ?? 50_000;
+  const tailCap = opts.replayBatches ?? 500;
+  const pending: EmittedDevtoolsEvent[] = [];
+  /** Batches kept for replay to late-joining dashboards. */
+  const tail: EmittedDevtoolsEvent[][] = [];
+  let closed = false;
+
+  const post = (msg: BroadcastMessage) => {
+    try {
+      bc.postMessage(msg);
+    } catch {
+      // channel torn down — close() races with postMessage on some engines
+    }
+  };
+
+  const hello = () => post({ type: 'hello', session });
+
+  const flush = () => {
+    if (closed || pending.length === 0) return;
+    const events = pending.splice(0, pending.length);
+    tail.push(events);
+    if (tail.length > tailCap) tail.shift();
+    post({ type: 'batch', session, events });
+  };
+
+  // A dashboard announcing itself — re-identify and replay so it doesn't
+  // start empty. The app listens on the same channel it publishes on.
+  bc.onmessage = (m: MessageEvent<BroadcastMessage>) => {
+    if (m.data?.type === 'view') {
+      hello();
+      for (const events of tail) post({ type: 'batch', session, events });
+    }
+  };
+
+  const timer = setInterval(flush, opts.flushMs ?? 100);
+  (timer as unknown as { unref?: () => void }).unref?.();
+
+  const bye = () => {
+    flush();
+    post({ type: 'bye', sessionId: session.id });
+  };
+  const onHide = () => bye();
+  if (typeof addEventListener === 'function') addEventListener('pagehide', onHide);
+
+  if (opts.network !== false) installFetchProbe(globalThis);
+  if (opts.memory !== false) installMemoryProbe(globalThis);
+
+  setDevtoolsSink((event) => {
+    if (closed) return;
+    pending.push(event);
+    if (pending.length > cap) pending.shift();
+    if (pending.length >= 1000) flush();
+  });
+
+  hello();
+
+  return {
+    session,
+    get open() {
+      return !closed;
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      bye();
+      setDevtoolsSink(null);
+      clearInterval(timer);
+      if (typeof removeEventListener === 'function') removeEventListener('pagehide', onHide);
+      bc.close();
+    },
+  };
+}