@davidsouther/jiffies 2026.24.0 → 2026.24.2

package/src/safe.ts

@@ -1,12 +0,0 @@
-import { error } from "./log.ts";
-
-export const safe =
-  <A extends unknown[], R>(fn: (...args: A) => R, r: R): ((...args: A) => R) =>
-  (...args: A) => {
-    try {
-      return fn(...args);
-    } catch (e: unknown) {
-      error(`${e}`);
-      return r;
-    }
-  };

package/src/server/http/apps.ts

@@ -1,26 +0,0 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import type { MiddlewareFactory } from "./index.ts";
-import { fileResponse } from "./response.ts";
-
-/**
- * Searches up the request path until the first index is found.
- */
-export const findIndex: MiddlewareFactory =
-  async ({ root }) =>
-  async (req) => {
-    let filename = path.join(root, req.url ?? "");
-    if (path.basename(filename).match(/\.[a-z]{1,3}$/)) {
-      return undefined;
-    }
-    while (filename.startsWith(root)) {
-      const index = path.join(filename, "index.html");
-      try {
-        const stat = await fs.stat(index);
-        return fileResponse(index, stat);
-      } catch (_e) {
-        filename = path.dirname(filename);
-      }
-    }
-    return undefined;
-  };

package/src/server/http/css.ts

@@ -1,49 +0,0 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import type { MiddlewareFactory } from "./index.ts";
-import { contentResponse } from "./response.ts";
-
-function render(source: string) {
-  // Replace `from "@scope` with `from "/@scope`, for browsers
-  // source = source
-  //   .replaceAll(`from "@`, 'from "/@')
-  //   .replaceAll(`import("@`, 'import("/@');
-  return contentResponse(source, "text/css");
-}
-
-/**
- * Serves .css files statically. Finds .sass files and transpiles them to css.
- */
-export const cssFileServer: MiddlewareFactory =
-  async ({ root, scopes = {} }) =>
-  async (req) => {
-    const Url = new URL(req.url ?? "/", `http://${req.headers.host}`);
-    if (Url.pathname.endsWith(".css")) {
-      const scope = Object.entries(scopes).find(([s]) =>
-        Url.pathname.startsWith(`/${s}`),
-      );
-      // Expand url with found scope
-      Url.protocol = "file";
-      const url = scope
-        ? Url.pathname.replace(scope[0], scope[1])
-        : Url.pathname;
-      let filename = path.join(root, url);
-      try {
-        const stat = await fs.stat(filename);
-        if (stat.isFile()) {
-          const css = (await fs.readFile(filename)).toString("utf-8");
-          return render(css);
-        }
-      } catch {}
-
-      filename = filename.replace(/\.css$/, ".scss");
-      try {
-        const stat = await fs.stat(filename);
-        if (stat.isFile()) {
-          const css = (await fs.readFile(filename)).toString();
-          return render(css);
-        }
-      } catch {}
-    }
-    return undefined;
-  };

package/src/server/http/index.ts

@@ -1,127 +0,0 @@
-#!/usr/bin/env node
-
-import {
-  createServer,
-  type IncomingMessage,
-  type RequestListener,
-  type ServerResponse,
-} from "node:http";
-import type { AddressInfo } from "node:net";
-import * as path from "node:path";
-import { info } from "../../log.ts";
-import { findIndex } from "./apps.ts";
-import { cssFileServer } from "./css.ts";
-import { fileResponse } from "./response.ts";
-import { sitemap } from "./sitemap.ts";
-import { staticFileServer } from "./static.ts";
-import { tsFileServer } from "./typescript.ts";
-
-export interface StaticResponse {
-  status: 200 | 404 | 500;
-  content: Buffer;
-  contentType: string;
-  contentLength?: number;
-  headers?: Map<string, string>;
-}
-
-export interface ServerConfig {
-  root: string;
-  scopes?: Record<`@${string}`, string>;
-}
-
-export type MiddlewareFactory = (
-  config: ServerConfig,
-) => Promise<StaticMiddleware>;
-
-export type StaticMiddleware = (
-  req: IncomingMessage,
-) => Promise<undefined | (() => Promise<StaticResponse>)>;
-
-const notFound: MiddlewareFactory =
-  async ({ root }) =>
-  async () =>
-    fileResponse(
-      // path.join(path.dirname(FLAGS.argv0), "404.html"),
-      path.join(root, "404.html"),
-      undefined,
-      404,
-    );
-
-const BASE_MIDDLEWARES: MiddlewareFactory[] = [
-  sitemap,
-  tsFileServer,
-  cssFileServer,
-  staticFileServer,
-  findIndex,
-  notFound,
-];
-
-const error = (res: ServerResponse, message: string) => {
-  console.error(message);
-  res.statusCode = 500;
-  res.write(message);
-  res.end();
-  return true;
-};
-
-const sendContent = async (
-  res: ServerResponse,
-  { content, contentType, contentLength, headers }: StaticResponse,
-) => {
-  res.setHeader("Content-Length", `${contentLength}`);
-  res.setHeader("Content-Type", contentType);
-  if (headers) {
-    for (const [header, value] of headers.entries()) {
-      res.setHeader(header.toLowerCase(), value);
-    }
-  }
-  await res.write(content);
-  res.end();
-  return true;
-};
-
-const log = (req: IncomingMessage) => {
-  const when = new Date().toISOString();
-  const who = req.socket.remoteAddress;
-  const what = req.url;
-  const how = `${req.method} ${what}`;
-  info("Request", { when, who, how });
-};
-
-export const makeServer = async (
-  config: ServerConfig,
-  middlewares: MiddlewareFactory[] = [],
-) => {
-  const handlers = await Promise.all(
-    [...middlewares, ...BASE_MIDDLEWARES].map(async (m) => m(config)),
-  );
-  const middlewareHandler: RequestListener = async (req, res) => {
-    log(req);
-    let handler: undefined | (() => Promise<StaticResponse>);
-    try {
-      for (const middleware of handlers) {
-        handler = await middleware(req);
-        if (handler !== undefined) {
-          break;
-        }
-      }
-      if (handler) {
-        sendContent(res, await handler());
-      } else {
-        res.end();
-      }
-    } catch (e) {
-      error(res, `${(e as Error).message}\n${(e as Error).stack}`);
-    }
-  };
-
-  // TODO(https)
-  const server = createServer(middlewareHandler);
-
-  server.on("listening", () => {
-    const { address, port } = server.address() as AddressInfo;
-    info("Server listening", { address: `http://${address}:${port}` });
-  });
-
-  return server;
-};

package/src/server/http/response.ts

@@ -1,60 +0,0 @@
-import type { Stats } from "node:fs";
-import * as fs from "node:fs/promises";
-import type { StaticResponse } from ".";
-
-const MIME_TYPES = {
-  js: "text/javascript",
-  ts: "text/javascript",
-  json: "text/javascript",
-  css: "text/css",
-  html: "text/html",
-  png: "image/png",
-  jpg: "image/jpeg",
-  jpeg: "image/jpeg",
-  svg: "image/svg+xml",
-  eot: "application/vnd.ms-fontobject",
-  ttf: "application/font-ttf",
-  woff: "application/font-woff",
-  woff2: "application/font-woff2",
-} as const;
-
-const mime = (basename: string) => {
-  const extension = basename
-    .substring(basename.lastIndexOf(".") + 1)
-    .toLowerCase();
-  return (
-    MIME_TYPES[extension as keyof typeof MIME_TYPES] ??
-    "application/octet-stream"
-  );
-};
-
-export const fileResponse =
-  (filename: string, stat?: Stats, status: 200 | 404 | 500 = 200) =>
-  async (): Promise<StaticResponse> => {
-    if (!stat) {
-      stat = await fs.stat(filename);
-    }
-    const content = await fs.readFile(filename);
-    const contentType = mime(filename);
-    const contentLength = stat.size;
-    return { status, contentType, contentLength, content };
-  };
-
-const CHARSET = "utf-8";
-export const contentResponse =
-  (
-    content: string,
-    contentType: string,
-    status: 200 | 404 | 500 = 200,
-    headers: Map<string, string> = new Map(),
-  ) =>
-  async (): Promise<StaticResponse> => {
-    const contentBuffer = Buffer.from(content, CHARSET);
-    return {
-      content: contentBuffer,
-      contentType: `${contentType.split(";")[0]}; charset=${CHARSET}`,
-      status,
-      contentLength: contentBuffer.length,
-      headers,
-    };
-  };

package/src/server/http/sitemap.ts

@@ -1,24 +0,0 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { info } from "../../log.ts";
-import type { MiddlewareFactory } from "./index.ts";
-import { contentResponse } from "./response.ts";
-
-export const sitemap: MiddlewareFactory = async ({ root }) => {
-  const apps: string[] = [];
-  for await (const file of fs.glob("**/index.html", {
-    cwd: root,
-    withFileTypes: false,
-    exclude: (name) => name === "node_modules",
-  })) {
-    const index = `/${file.replaceAll(path.sep, "/")}`;
-    info("Adding to sitemap", { index });
-    apps.push(index);
-  }
-  return async (req) => {
-    if ((req.url ?? "").endsWith("sitemap.json")) {
-      return contentResponse(JSON.stringify(apps), "application/json");
-    }
-    return undefined;
-  };
-};

package/src/server/http/static.ts

@@ -1,28 +0,0 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import type { MiddlewareFactory } from "./index.ts";
-import { fileResponse } from "./response.ts";
-
-export const staticFileServer: MiddlewareFactory =
-  async ({ root, scopes = {} }) =>
-  async (req) => {
-    const scope = Object.entries(scopes).find(([s]) =>
-      req.url?.startsWith(`/${s}`),
-    );
-    const url = new URL(req.url ?? "", "http://localhost");
-    const pathname = scope
-      ? url.pathname.replace(scope[0], scope[1])
-      : url.pathname;
-    const filename = path.join(root, pathname);
-
-    try {
-      const stat = await fs.stat(filename);
-      return stat.isDirectory() ? undefined : fileResponse(filename, stat);
-    } catch (e) {
-      if ((e as { code?: string }).code === "ENOENT") {
-        return fileResponse(filename, undefined, 404);
-      }
-      console.error(e);
-      return undefined;
-    }
-  };

package/src/server/http/typescript.ts

@@ -1,46 +0,0 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { transpile } from "../../transpile.mjs";
-import type { MiddlewareFactory } from "./index.ts";
-import { contentResponse } from "./response.ts";
-
-function render(source: string, headers: Map<string, string>) {
-  // Replace `from "@scope` with `from "/@scope`, for browsers
-  source = source
-    .replaceAll(`from "@`, 'from "/@')
-    .replaceAll(`import("@`, 'import("/@');
-  return contentResponse(source, "application/javascript", 200, headers);
-}
-
-/**
- * Serves .js files statically. Finds .ts files and transpiles them to JS.
- */
-export const tsFileServer: MiddlewareFactory =
-  async ({ root, scopes = {} }) =>
-  async (req) => {
-    if (req.url?.endsWith(".js") || req.url?.endsWith(".ts")) {
-      const scope = Object.entries(scopes).find(([s]) =>
-        req.url?.startsWith(`/${s}`),
-      );
-      // Expand url with found scope
-      const url = scope ? req.url.replace(scope[0], scope[1]) : req.url;
-      let filename = path.join(root, url);
-      const stat = await fs.stat(filename);
-      if (stat.isFile()) {
-        let js: string;
-        const headers: Map<string, string> = new Map();
-        if (filename.endsWith(".ts")) {
-          js = await transpile(filename, () => fs.readFile(filename));
-          headers.set("SourceMap", `${url}.map`);
-          js += `\n//# sourceURL=${url}`;
-        } else {
-          if (url.endsWith(".ts.map")) {
-            filename = filename.replace(/\.map$/, "");
-          }
-          js = (await fs.readFile(filename)).toString("utf-8");
-        }
-        return render(js, headers);
-      }
-    }
-    return undefined;
-  };

package/src/server/live-reload.ts

@@ -1,208 +0,0 @@
-import { type FSWatcher, watch } from "node:fs";
-import * as fs from "node:fs/promises";
-import type { AddressInfo } from "node:net";
-import * as path from "node:path";
-import { type MiddlewareFactory, makeServer } from "./http/index.ts";
-import { contentResponse } from "./http/response.ts";
-import { attachWebSocketServer, type WebSocketHub } from "./ws/index.ts";
-
-// Live-reload feature for a (optionally watched) jiffies static dev server.
-// Shaped as stock jiffies middlewares + a generic watcher composed with the
-// ws/ transport, so a downstream server adds `--port`/`--host`/`--watch` via
-// jiffiesArgs and injects only its own build command and watched paths.
-// See .agents/developer/2026-06-10-A-upstream-livereload-client/design.md.
-
-// The injected client snippet opens a WebSocket to `path` and reloads the page
-// on any pushed message. On close it reconnects with a short fixed backoff,
-// which recovers from a server restart or a socket dropped during a rebuild.
-// Errors are swallowed; the close handler drives the reconnect. `path` is a
-// parameter so the caller owns the reload route.
-export function webSocketReloadClient(path: string): string {
-  return `<script>(function(){function connect(){var ws=new WebSocket((location.protocol==="https:"?"wss://":"ws://")+location.host+${JSON.stringify(
-    path,
-  )});ws.onmessage=function(){location.reload();};ws.onerror=function(){};ws.onclose=function(){setTimeout(connect,1000);};}connect();})();</script>`;
-}
-
-// Injects the reload snippet into HTML navigations. Mirrors jiffies findIndex
-// (walk up for index.html) for extensionless paths; serves .html directly.
-// Asset/CSS/TS requests fall through to the base middlewares.
-export const htmlInjector =
-  (snippet: string): MiddlewareFactory =>
-  async ({ root }) =>
-  async (req) => {
-    const { pathname } = new URL(req.url ?? "/", "http://localhost");
-    const decoded = decodeURIComponent(pathname);
-    const ext = path.extname(decoded);
-    let target: string | undefined;
-    if (ext === ".html") {
-      target = path.join(root, decoded);
-    } else if (ext === "") {
-      let dir = path.join(root, decoded);
-      while (dir.startsWith(root)) {
-        const idx = path.join(dir, "index.html");
-        try {
-          if ((await fs.stat(idx)).isFile()) {
-            target = idx;
-            break;
-          }
-        } catch {}
-        dir = path.dirname(dir);
-      }
-    }
-    if (!target) return undefined;
-    try {
-      if (!(await fs.stat(target)).isFile()) return undefined;
-      const html = await fs.readFile(target, "utf-8");
-      const injected = html.includes("</body>")
-        ? html.replace("</body>", `${snippet}</body>`)
-        : html + snippet;
-      return contentResponse(injected, "text/html");
-    } catch {
-      return undefined;
-    }
-  };
-
-// Ignores dotfiles and node_modules. The argument is the full resolved path, so
-// callers can compose this with project-specific generated-output paths.
-export const ignoreDefault = (file: string): boolean =>
-  /(^|[\\/])\./.test(file) || file.includes("node_modules");
-
-// Watches dirs recursively, coalescing bursts into a single trailing call. The
-// ignore predicate receives the resolved absolute path of each changed file, so
-// it can exclude build outputs written back into a watched dir (which would
-// otherwise retrigger the build endlessly).
-export function watchTree(
-  dirs: string[],
-  onChange: () => void,
-  {
-    debounceMs = 150,
-    ignore = ignoreDefault,
-  }: { debounceMs?: number; ignore?: (file: string) => boolean } = {},
-): { close: () => void } {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const watchers: FSWatcher[] = [];
-  for (const dir of dirs) {
-    try {
-      watchers.push(
-        watch(dir, { recursive: true }, (_event, filename) => {
-          if (!filename) return;
-          if (ignore(path.join(dir, filename.toString()))) return;
-          if (timer) clearTimeout(timer);
-          timer = setTimeout(onChange, debounceMs);
-        }),
-      );
-    } catch {
-      // Directory may not exist; skip it.
-    }
-  }
-  return {
-    close: () => {
-      if (timer) clearTimeout(timer);
-      for (const w of watchers) w.close();
-    },
-  };
-}
-
-// Serializes rebuilds: a change during a build sets a dirty flag that triggers
-// exactly one more rebuild afterward. `onBuilt` runs once per successful rebuild
-// (each time the inner rebuild resolves true), letting the caller broadcast a
-// reload without the client needing a queryable build id.
-export function createRebuilder(
-  rebuild: () => Promise<boolean>,
-  onBuilt?: () => void,
-): {
-  run: () => Promise<void>;
-  trigger: () => void;
-} {
-  let building = false;
-  let dirty = false;
-  const run = async (): Promise<void> => {
-    if (building) {
-      dirty = true;
-      return;
-    }
-    building = true;
-    try {
-      do {
-        dirty = false;
-        if (await rebuild()) onBuilt?.();
-      } while (dirty);
-    } finally {
-      building = false;
-    }
-  };
-  return { run, trigger: () => void run() };
-}
-
-export interface WatchServerOptions {
-  root: string;
-  watchDirs: string[];
-  rebuild: () => Promise<boolean>;
-  debounceMs?: number;
-  // Resolved paths to exclude from watching (e.g. build outputs written back
-  // into a watched dir). Defaults to ignoreDefault when omitted.
-  ignore?: (file: string) => boolean;
-  port?: number;
-  host?: string;
-  // The reload route. Defaults to "/__livereload". The injected snippet and the
-  // ws hub are both bound to this path.
-  reloadPath?: string;
-}
-
-// Initial build, then serve `root` with the injector middleware, attach a
-// WebSocket hub at reloadPath, and watch `watchDirs`. Each successful rebuild
-// broadcasts "reload" to connected clients. Returns the bound port and a
-// close() for clean shutdown. The hub is late-bound: the initial build runs
-// before it exists, so its onBuilt broadcast is a no-op (no clients yet).
-export async function startWatchServer(
-  opts: WatchServerOptions,
-): Promise<{ port: number; close: () => Promise<void> }> {
-  const reloadPath = opts.reloadPath ?? "/__livereload";
-  let hub: WebSocketHub | undefined;
-  const rebuilder = createRebuilder(opts.rebuild, () =>
-    hub?.broadcast("reload"),
-  );
-  await rebuilder.run();
-  const snippet = webSocketReloadClient(reloadPath);
-  const server = await makeServer({ root: opts.root }, [htmlInjector(snippet)]);
-  const watchOpts: { debounceMs?: number; ignore?: (file: string) => boolean } =
-    {};
-  if (opts.debounceMs !== undefined) watchOpts.debounceMs = opts.debounceMs;
-  if (opts.ignore !== undefined) watchOpts.ignore = opts.ignore;
-  const watcher = watchTree(opts.watchDirs, rebuilder.trigger, watchOpts);
-  await new Promise<void>((resolve) =>
-    server.listen(opts.port ?? 8080, opts.host ?? "127.0.0.1", resolve),
-  );
-  hub = attachWebSocketServer(server, { path: reloadPath });
-  const address = server.address() as AddressInfo;
-  return {
-    port: address.port,
-    close: () =>
-      new Promise<void>((resolve) => {
-        hub?.close();
-        watcher.close();
-        server.close(() => resolve());
-      }),
-  };
-}
-
-export interface JiffiesArgsParams {
-  port?: string; // default for --port  (default "8080")
-  host?: string; // default for --host  (default "0.0.0.0")
-}
-
-// A parseArgs `options` fragment for launching a (optionally watched) jiffies
-// static server. Spread into a downstream's parseArgs options so it owns the
-// entrypoint and the `values.watch` branch. `params` overrides the port/host
-// defaults; `watch` defaults to false.
-export function jiffiesArgs(params?: JiffiesArgsParams): {
-  port: { type: "string"; default: string };
-  host: { type: "string"; default: string };
-  watch: { type: "boolean"; default: false };
-} {
-  return {
-    port: { type: "string", default: params?.port ?? "8080" },
-    host: { type: "string", default: params?.host ?? "0.0.0.0" },
-    watch: { type: "boolean", default: false },
-  };
-}

package/src/server/ws/frame.ts

@@ -1,36 +0,0 @@
-// Encodes `text` as a single unmasked server->client WebSocket text frame:
-// FIN set + opcode 0x1 => first byte 0x81; mask bit clear; 7-bit / 16-bit /
-// 64-bit extended payload-length selection by utf8 byte count. Server-to-client
-// frames are never masked (RFC 6455).
-export function encodeTextFrame(text: string): Buffer {
-  const payload = Buffer.from(text, "utf-8");
-  const length = payload.length;
-  const fin = 0x81; // FIN set, opcode 0x1 (text).
-
-  let header: Buffer;
-  if (length < 126) {
-    header = Buffer.from([fin, length]);
-  } else if (length <= 0xffff) {
-    header = Buffer.alloc(4);
-    header[0] = fin;
-    header[1] = 0x7e;
-    header.writeUInt16BE(length, 2);
-  } else {
-    header = Buffer.alloc(10);
-    header[0] = fin;
-    header[1] = 0x7f;
-    header.writeBigUInt64BE(BigInt(length), 2);
-  }
-
-  return Buffer.concat([header, payload]);
-}
-
-// Reads the opcode nibble of an inbound (client, masked) frame for control-frame
-// handling: 0x1 text, 0x8 close, 0x9 ping, 0xA pong, etc. Returns undefined for a
-// partial/unreadable buffer. Does NOT decode the masked payload.
-export function readOpcode(buffer: Buffer): number | undefined {
-  if (buffer.length === 0) {
-    return undefined;
-  }
-  return buffer[0] & 0x0f;
-}

package/src/server/ws/handshake.ts

@@ -1,42 +0,0 @@
-import { createHash } from "node:crypto";
-import type { IncomingMessage } from "node:http";
-import type { Duplex } from "node:stream";
-
-// The fixed GUID concatenated to the client key before hashing, per RFC 6455.
-const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
-
-// base64( SHA-1( key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" ) ), per RFC 6455.
-// Pure function of the client's Sec-WebSocket-Key.
-export function acceptKey(secWebSocketKey: string): string {
-  return createHash("sha1")
-    .update(secWebSocketKey + WS_GUID)
-    .digest("base64");
-}
-
-// Validates the upgrade request, writes the "101 Switching Protocols" response
-// (Upgrade: websocket, Connection: Upgrade, Sec-WebSocket-Accept: acceptKey(...))
-// to the raw socket, and returns true. Returns false WITHOUT writing on a
-// malformed upgrade (missing/non-"websocket" Upgrade header or missing
-// Sec-WebSocket-Key), leaving the socket for the caller to destroy.
-export function completeHandshake(
-  req: IncomingMessage,
-  socket: Duplex,
-): boolean {
-  const key = req.headers["sec-websocket-key"];
-  const upgrade = req.headers.upgrade;
-  if (typeof key !== "string" || key.length === 0) {
-    return false;
-  }
-  if (typeof upgrade !== "string" || upgrade.toLowerCase() !== "websocket") {
-    return false;
-  }
-
-  const response =
-    "HTTP/1.1 101 Switching Protocols\r\n" +
-    "Upgrade: websocket\r\n" +
-    "Connection: Upgrade\r\n" +
-    `Sec-WebSocket-Accept: ${acceptKey(key)}\r\n` +
-    "\r\n";
-  socket.write(response);
-  return true;
-}