@hajimism/dek 0.1.0

package/src/server/hub.ts

@@ -0,0 +1,104 @@
+import type { LiveEvent } from "../core/live-protocol.ts";
+
+/** A live event and the deck it happened in; a page hears only its own deck's. */
+export type DeckEvent = LiveEvent & { deck: string };
+
+type Listener = (event: DeckEvent) => void;
+
+/** What the server's own readers see of the hub: subscribe, and later unsubscribe. */
+export type EventFeed = { listen(fn: Listener): () => void };
+
+export type EventHub = EventFeed & {
+  emit(event: DeckEvent): void;
+  /** An SSE stream of every event `accept` lets through, all of them when it is left out. */
+  sse(accept?: (event: DeckEvent) => boolean): ReadableStream<Uint8Array>;
+  /** Drop every listener and end every stream; later events go nowhere. */
+  close(): void;
+};
+
+/** Bun closes a request that is idle for 10s; an SSE comment keeps `/events` open. */
+export const SSE_HEARTBEAT_MS = 5_000;
+
+/**
+ * Fan-out: each event goes to whoever listens at the time, and to no one else. Nothing is kept
+ * for a listener that comes later, so a reader that stops reading cannot make the hub grow.
+ */
+export function createEventHub(options: { heartbeatMs?: number } = {}): EventHub {
+  const listeners = new Set<Listener>();
+  const streams = new Set<() => void>();
+  const encoder = new TextEncoder();
+  let closed = false;
+
+  const listen = (fn: Listener): (() => void) => {
+    if (closed) {
+      return () => undefined;
+    }
+    listeners.add(fn);
+    return () => {
+      listeners.delete(fn);
+    };
+  };
+
+  return {
+    listen,
+    emit(event) {
+      for (const fn of [...listeners]) {
+        try {
+          fn(event);
+        } catch {
+          // One reader's failure is its own; the rest still hear the event.
+        }
+      }
+    },
+    sse(accept = () => true) {
+      let end = (): void => undefined;
+      return new ReadableStream<Uint8Array>({
+        start(controller) {
+          const send = (bytes: Uint8Array): void => {
+            try {
+              controller.enqueue(bytes);
+            } catch {
+              end();
+            }
+          };
+          const heartbeat = setInterval(
+            () => send(encoder.encode(": ping\n\n")),
+            options.heartbeatMs ?? SSE_HEARTBEAT_MS,
+          );
+          // The page's stream is its deck's already, so the deck stays off the wire.
+          const unlisten = listen((event) => {
+            if (accept(event)) {
+              const { deck: _deck, ...wire } = event;
+              send(encoder.encode(`data: ${JSON.stringify(wire)}\n\n`));
+            }
+          });
+          end = () => {
+            clearInterval(heartbeat);
+            unlisten();
+            streams.delete(end);
+            try {
+              controller.close();
+            } catch {
+              /* already closed */
+            }
+          };
+          streams.add(end);
+          send(encoder.encode(": connected\n\n"));
+          if (closed) {
+            end();
+          }
+        },
+        cancel() {
+          end();
+        },
+      });
+    },
+    close() {
+      closed = true;
+      listeners.clear();
+      for (const end of [...streams]) {
+        end();
+      }
+    },
+  };
+}

package/src/server/lan.ts

@@ -0,0 +1,51 @@
+import { type NetworkInterfaceInfo, networkInterfaces } from "node:os";
+
+const PASSWORD_ALPHABET = "abcdefghijkmnpqrstuvwxyz23456789";
+
+export function lanUrls(
+  port: number,
+  ifaces: NodeJS.Dict<NetworkInterfaceInfo[]> = networkInterfaces(),
+): string[] {
+  const urls: string[] = [];
+  for (const entries of Object.values(ifaces)) {
+    for (const info of entries ?? []) {
+      const family = String(info.family);
+      if (info.internal || (family !== "IPv4" && family !== "4")) {
+        continue;
+      }
+      urls.push(`http://${info.address}:${port}/`);
+    }
+  }
+  return urls;
+}
+
+/** Ten letters from an alphabet without look-alikes: 50 bits, still easy to read out to a room. */
+export function generateRemotePassword(length = 10): string {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return [...bytes].map((byte) => PASSWORD_ALPHABET[byte % PASSWORD_ALPHABET.length]).join("");
+}
+
+export function remoteBanner(
+  loopback: string,
+  remoteUrls: string[],
+  options: { password?: string; presenterPaths?: string[] } = {},
+): string {
+  const password = options.password;
+  if (!password) {
+    return loopback;
+  }
+  const lines = [loopback];
+  for (const url of remoteUrls) {
+    if (url !== loopback) {
+      lines.push(url);
+    }
+  }
+  const presenterHost = remoteUrls.find((url) => !url.includes("127.0.0.1")) ?? loopback;
+  for (const path of options.presenterPaths ?? []) {
+    lines.push(`presenter: ${new URL(path, presenterHost).href}`);
+  }
+  // The browser asks for a user name too; the password alone unlocks the presenter.
+  lines.push(`password: ${password} (any user name)`);
+  return lines.join("\n");
+}

package/src/server/lock.ts

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { DekError } from "../core/error.ts";
+import { writeInside } from "../core/safe-fs.ts";
+
+export type DevServerLock = {
+  url: string;
+  pid: number;
+  password?: string;
+  /** The one deck a server scoped to a deck serves; absent when it serves the project. */
+  deck?: string;
+};
+
+function serverLockPath(root: string): string {
+  return join(root, ".dek", "server.json");
+}
+
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readDevServerLock(root: string): DevServerLock | undefined {
+  const path = serverLockPath(root);
+  if (!existsSync(path)) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as DevServerLock;
+    if (typeof parsed.url === "string" && typeof parsed.pid === "number") {
+      return {
+        url: parsed.url,
+        pid: parsed.pid,
+        ...(typeof parsed.password === "string" ? { password: parsed.password } : {}),
+        ...(typeof parsed.deck === "string" ? { deck: parsed.deck } : {}),
+      };
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+/** The URL of each root a server in this process holds, which two racing servers both see. */
+const claimedRoots = new Map<string, string>();
+
+/** Throw when a live server, in this process or another, already holds `root`. */
+export function assertNoDevServer(root: string): void {
+  const existing = readDevServerLock(root);
+  const running =
+    claimedRoots.get(root) ?? (existing && isPidAlive(existing.pid) ? existing.url : undefined);
+  if (running !== undefined) {
+    throw new DekError(`dev server already running at ${running}`, {
+      path: serverLockPath(root),
+      hint: `open ${running}`,
+    });
+  }
+}
+
+export function writeDevServerLock(
+  root: string,
+  url: string,
+  password?: string,
+  deck?: string,
+): void {
+  assertNoDevServer(root);
+  claimedRoots.set(root, url);
+  try {
+    // A fresh file renamed into place, so it may hold the --remote password: its owner's only.
+    writeInside(
+      serverLockPath(root),
+      `${JSON.stringify({ url, pid: process.pid, ...(password ? { password } : {}), ...(deck ? { deck } : {}) })}\n`,
+      root,
+      { mode: 0o600 },
+    );
+  } catch (error) {
+    claimedRoots.delete(root);
+    throw error;
+  }
+}
+
+export function removeDevServerLock(root: string): void {
+  claimedRoots.delete(root);
+  const current = readDevServerLock(root);
+  if (current && current.pid !== process.pid) {
+    return;
+  }
+  try {
+    unlinkSync(serverLockPath(root));
+  } catch {
+    /* already gone */
+  }
+}

package/src/server/pages.ts

@@ -0,0 +1,71 @@
+import { renderDeckHtml } from "../core/document.ts";
+import type { Project } from "../core/resolve.ts";
+import { errorPage, htmlResponse, renderIndexHtml } from "./routes.ts";
+
+export type DevPages = {
+  /** A deck's live page; a deck that fails to render answers with its error. */
+  deckPage(dir: string, mode: "player" | "presenter"): Response;
+  /** The project's list of decks. */
+  indexPage(): Response;
+  /** Forget every rendered page, after an edit that may change what they show. */
+  clear(): void;
+};
+
+/** The pages a dev server renders, each kept until `clear`. */
+export function createDevPages(options: {
+  embed: { playerScript: string; liveReloadScript: string };
+  remote: boolean;
+  /** Embedded on the presenter page, so its stream and moves are let through. */
+  password: string | undefined;
+  project: () => Project;
+}): DevPages {
+  const { embed, remote, password } = options;
+  const pages = new Map<string, string>();
+
+  const cached = (key: string, render: () => string): string => {
+    const hit = pages.get(key);
+    if (hit !== undefined) {
+      return hit;
+    }
+    const html = render();
+    pages.set(key, html);
+    return html;
+  };
+
+  return {
+    deckPage(dir, mode) {
+      try {
+        return htmlResponse(
+          cached(`${dir}:${mode}`, () =>
+            renderDeckHtml(dir, {
+              playerScript: embed.playerScript,
+              target: {
+                kind: "dev",
+                mode,
+                includeNotes: mode === "presenter" || !remote,
+                liveReloadScript: embed.liveReloadScript,
+                ...(mode === "presenter" && password ? { liveToken: password } : {}),
+              },
+            }),
+          ),
+        );
+      } catch (error) {
+        return htmlResponse(errorPage(error), 500);
+      }
+    },
+    indexPage() {
+      return htmlResponse(
+        cached("index", () => {
+          const { decks, failed } = options.project();
+          return renderIndexHtml(
+            decks.map((deck) => ({ name: deck.name, title: deck.deck.title })),
+            failed.map((entry) => ({ name: entry.name })),
+          );
+        }),
+      );
+    },
+    clear() {
+      pages.clear();
+    },
+  };
+}

package/src/server/pairing.ts

@@ -0,0 +1,40 @@
+import { generateRemotePassword } from "./lan.ts";
+
+/** How long a pairing code shown as a QR code stays good, used or not. */
+export const PAIRING_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * One-use codes that let a phone in as the presenter by scanning a QR code, without typing the
+ * password. A code works once and for a few minutes, so a photo of a projected terminal is worth
+ * nothing by the time anyone could use it; the password stays for any other device.
+ */
+export type Pairings = {
+  /** A fresh code; the ones before it stay good until used or expired. */
+  issue(): string;
+  /** True, once, for a code that was issued and has not expired. */
+  redeem(code: string): boolean;
+};
+
+export function createPairings(options: { ttlMs?: number; now?: () => number } = {}): Pairings {
+  const ttlMs = options.ttlMs ?? PAIRING_TTL_MS;
+  const now = options.now ?? Date.now;
+  const open = new Map<string, number>();
+  return {
+    issue() {
+      // 16 letters of the password alphabet: 80 bits, for a code that lives five minutes.
+      const code = generateRemotePassword(16);
+      open.set(code, now() + ttlMs);
+      return code;
+    },
+    redeem(code) {
+      const expires = open.get(code);
+      open.delete(code);
+      for (const [other, at] of open) {
+        if (at <= now()) {
+          open.delete(other);
+        }
+      }
+      return expires !== undefined && expires > now();
+    },
+  };
+}

package/src/server/project-watch.ts

@@ -0,0 +1,142 @@
+import { watch } from "node:fs";
+import { join } from "node:path";
+import type { LiveEvent } from "../core/live-protocol.ts";
+import type { PlaywrightRunner } from "../core/playwright.ts";
+import { type Project, resolveProject } from "../core/resolve.ts";
+import { createEventHub, type DeckEvent, type EventHub } from "./hub.ts";
+import { type Stoppable, watchDeck } from "./watch.ts";
+
+export type ProjectWatch = {
+  /** The project as last read: re-read after a sync, so decks that come and go show. */
+  project(): Project;
+  /** Every event the decks' watchers emit, each with its deck. */
+  hub: EventHub;
+  /** Stop every watcher, then end the event stream. */
+  close(): void;
+};
+
+/**
+ * Watch the decks a server serves: the one it is scoped to, or every deck of the project and
+ * the decks directory for decks that come and go. `onChange` runs whenever what a page shows
+ * may have changed: after each event but diagnostics and the timeline, and when the deck set does.
+ */
+export function createProjectWatch(options: {
+  root: string;
+  project: Project;
+  scopedDeckName?: string;
+  visual: boolean;
+  visualRunner?: PlaywrightRunner;
+  pollIntervalMs: number;
+  onChange: () => void;
+}): ProjectWatch {
+  const { root, scopedDeckName } = options;
+  let project = options.project;
+  let stopped = false;
+  const hub = createEventHub();
+  const watchers = new Map<string, Stoppable>();
+  const watchOptions = {
+    visual: options.visual,
+    visualRunner: options.visualRunner,
+    pollIntervalMs: options.pollIntervalMs,
+  };
+
+  /** Bring the server up to date before any page hears the event and asks for what changed. */
+  const emit = (event: DeckEvent): void => {
+    if (event.type === "sync") {
+      refreshProject();
+    }
+    if (event.type !== "diagnostics" && event.type !== "timeline") {
+      options.onChange();
+    }
+    hub.emit(event);
+  };
+
+  const reconcileWatchers = (): void => {
+    const targets = scopedDeckName
+      ? new Map([[join(project.root, "decks", scopedDeckName), scopedDeckName]])
+      : watchTargets(project);
+    for (const [dir, deck] of targets) {
+      if (!watchers.has(dir)) {
+        const emitFor = (event: LiveEvent) => emit({ ...event, deck });
+        watchers.set(dir, watchDeck(dir, emitFor, watchOptions));
+      }
+    }
+    for (const [dir, watcher] of watchers) {
+      if (!targets.has(dir)) {
+        watcher.close();
+        watchers.delete(dir);
+      }
+    }
+  };
+
+  /** Re-read the project after decks come and go; the index lists the deck set. */
+  const refreshProject = (): void => {
+    // fs.watch can deliver an event after close; a watcher made then would outlive the server.
+    if (stopped) {
+      return;
+    }
+    try {
+      const fresh = resolveProject(root);
+      const changed = deckNames(fresh) !== deckNames(project);
+      project = fresh;
+      if (changed) {
+        options.onChange();
+      }
+      reconcileWatchers();
+    } catch {
+      // dek.toml may disappear mid-write; keep the last known project.
+    }
+  };
+
+  reconcileWatchers();
+  let decksDirWatcher: Stoppable | undefined;
+  if (!scopedDeckName) {
+    try {
+      const dirWatcher = watch(join(project.root, "decks"), { recursive: true }, refreshProject);
+      const timer = setInterval(refreshProject, options.pollIntervalMs);
+      decksDirWatcher = {
+        close() {
+          dirWatcher.close();
+          clearInterval(timer);
+        },
+      };
+    } catch {
+      decksDirWatcher = undefined;
+    }
+  }
+
+  return {
+    project: () => project,
+    hub,
+    close() {
+      stopped = true;
+      for (const watcher of watchers.values()) {
+        watcher.close();
+      }
+      decksDirWatcher?.close();
+      hub.close();
+    },
+  };
+}
+
+/** The decks to watch, parsed or not: each deck's name by its directory. */
+export function watchTargets(project: {
+  decks: Array<{ name: string; dir: string }>;
+  failed: Array<{ name: string; dir: string }>;
+}): Map<string, string> {
+  const targets = new Map<string, string>();
+  for (const { name, dir } of [...project.decks, ...project.failed]) {
+    if (!targets.has(dir)) {
+      targets.set(dir, name);
+    }
+  }
+  return targets;
+}
+
+/** Every deck name the index lists, parsed or not, as one comparable key. */
+function deckNames(project: Project): string {
+  return [...project.decks, ...project.failed]
+    .map((entry) => entry.name)
+    .sort()
+    .join("\n");
+}

package/src/server/rooms.ts

@@ -0,0 +1,133 @@
+import {
+  decodePointer,
+  decodePosition,
+  encodePointer,
+  encodePosition,
+} from "../core/live-protocol.ts";
+import { clampPosition, deckStops } from "../core/position.ts";
+import type { ProjectDeck } from "../core/resolve.ts";
+import type { Position } from "../core/step.ts";
+
+/** A socket in a room, as far as a room needs one. */
+export type RoomClient = { send(payload: string): unknown };
+
+/**
+ * Where a deck stands, as `dekc current` and `dekc goto` print it, and how many pages show it. With
+ * none, the position is where the next page opened lands.
+ */
+type RoomPosition = { slug: string; slideIndex: number; beatIndex: number; viewers: number };
+
+export type Rooms<C extends RoomClient> = {
+  /** A socket joins its deck's room, and is told where the talk stands. */
+  join(room: string, client: C): void;
+  leave(room: string, client: C): void;
+  /**
+   * What a presenter sends, relayed to everyone else in the room: a move, kept within the deck and
+   * as where the room stands; or where the laser points, kept nowhere, since a page that joins
+   * later must not see a laser that pointed before it came.
+   */
+  relay(room: string, from: C, payload: string): void;
+  /** Send the room to a slide; the reason when the deck or slide is not there. */
+  goto(room: string, slug: string): { ok: true; at: RoomPosition } | { ok: false; message: string };
+  current(room: string): RoomPosition;
+  /** After the script changed: a kept position past a slide or beat now gone is pulled back. */
+  reclamp(): void;
+};
+
+/**
+ * The presenter rooms, one per deck: who is connected, and the position each deck is at.
+ * `decks` is read on each call, so a room follows the script as it is now.
+ */
+export function createRooms<C extends RoomClient>(decks: () => ProjectDeck[]): Rooms<C> {
+  const rooms = new Map<string, Set<C>>();
+  const positions = new Map<string, Position>();
+
+  const deckFor = (room: string): ProjectDeck | undefined =>
+    decks().find((entry) => entry.name === room);
+
+  /** `pos` within the room's deck; kept as sent while the deck fails to parse. */
+  const within = (room: string, pos: Position): Position | undefined => {
+    const deck = deckFor(room);
+    return deck ? clampPosition(pos, deckStops(deck.deck.sections)) : pos;
+  };
+
+  const broadcast = (room: string, payload: string, except?: C): void => {
+    for (const client of rooms.get(room) ?? []) {
+      if (client !== except) {
+        client.send(payload);
+      }
+    }
+  };
+
+  const current = (room: string): RoomPosition => {
+    const deck = deckFor(room);
+    const viewers = rooms.get(room)?.size ?? 0;
+    const pos = positions.get(room) ?? { slideIndex: 0, beatIndex: 0 };
+    const slug = deck?.deck.sections[pos.slideIndex]?.slug;
+    if (!slug) {
+      return { slug: deck?.deck.sections[0]?.slug ?? room, slideIndex: 0, beatIndex: 0, viewers };
+    }
+    return { slug, slideIndex: pos.slideIndex, beatIndex: pos.beatIndex, viewers };
+  };
+
+  return {
+    join(room, client) {
+      const clients = rooms.get(room) ?? new Set();
+      clients.add(client);
+      rooms.set(room, clients);
+      const pos = positions.get(room);
+      if (pos) {
+        client.send(encodePosition(pos));
+      }
+    },
+    leave(room, client) {
+      const clients = rooms.get(room);
+      if (!clients) {
+        return;
+      }
+      clients.delete(client);
+      if (clients.size === 0) {
+        rooms.delete(room);
+      }
+    },
+    relay(room, from, payload) {
+      const laser = decodePointer(payload);
+      if (laser) {
+        broadcast(room, encodePointer(laser.pointer), from);
+        return;
+      }
+      const sent = decodePosition(payload);
+      const pos = sent && within(room, sent);
+      if (!pos) {
+        return;
+      }
+      positions.set(room, pos);
+      broadcast(room, encodePosition(pos), from);
+    },
+    goto(room, slug) {
+      const deck = deckFor(room);
+      if (!deck) {
+        return { ok: false, message: `deck "${room}" not found` };
+      }
+      const slideIndex = deck.deck.sections.findIndex((section) => section.slug === slug);
+      if (slideIndex < 0) {
+        return { ok: false, message: `section "${slug}" not found` };
+      }
+      const pos = { slideIndex, beatIndex: 0 };
+      positions.set(room, pos);
+      broadcast(room, encodePosition(pos));
+      return { ok: true, at: current(room) };
+    },
+    current,
+    reclamp() {
+      for (const [room, pos] of positions) {
+        const kept = within(room, pos);
+        if (kept) {
+          positions.set(room, kept);
+        } else {
+          positions.delete(room);
+        }
+      }
+    },
+  };
+}