npm - @davidsouther/jiffies - Versions diffs - 2026.4.1 → 2026.24.0 - Mend

@davidsouther/jiffies 2026.4.1 → 2026.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

package/README.md +0 -3
package/package.json +11 -6
package/src/404.html +1 -1
package/src/components/accordion.ts +25 -0
package/src/components/alert.ts +47 -0
package/src/components/card.ts +54 -0
package/src/components/children.ts +11 -0
package/src/components/form.ts +25 -0
package/src/components/index.ts +22 -0
package/src/components/link.ts +22 -0
package/src/components/modal.ts +15 -0
package/src/components/nav.ts +42 -0
package/src/components/property.ts +32 -0
package/src/components/tabs.ts +82 -0
package/src/components/virtual_scroll.ts +1 -1
package/src/dom/README.md +7 -2
package/src/dom/SKILL.md +201 -0
package/src/dom/dom.ts +185 -41
package/src/dom/fc.ts +3 -2
package/src/dom/form/form.app.ts +35 -41
package/src/dom/form/form.ts +79 -10
package/src/dom/form/index.html +2 -2
package/src/dom/hydrate.ts +206 -0
package/src/dom/navigation/index.ts +349 -0
package/src/dom/render.ts +41 -0
package/src/dom/svg.ts +6 -2
package/src/fs_node.ts +2 -2
package/src/log.ts +154 -2
package/src/server/http/response.ts +6 -3
package/src/server/http/sitemap.ts +10 -34
package/src/server/http/static.ts +0 -2
package/src/server/live-reload.ts +208 -0
package/src/server/main.ts +14 -7
package/src/server/ws/frame.ts +36 -0
package/src/server/ws/handshake.ts +42 -0
package/src/server/ws/index.ts +100 -0
package/src/ssg/bundle.ts +85 -0
package/src/ssg/copy-public.ts +44 -0
package/src/ssg/discover.ts +143 -0
package/src/ssg/main.ts +168 -0
package/src/ssg/rewrite.ts +18 -0
package/src/ssg/ssg.ts +134 -0
package/src/components/test.ts +0 -5
package/src/components/virtual_scroll.test.ts +0 -30
package/src/context.test.ts +0 -58
package/src/context.ts +0 -67
package/src/diff.test.ts +0 -48
package/src/dom/fc.test.ts +0 -43
package/src/dom/form/form.test.ts +0 -0
package/src/dom/html.test.ts +0 -74
package/src/dom/observable.test.ts +0 -43
package/src/dom/test.ts +0 -11
package/src/equal.test.ts +0 -23
package/src/flags.test.ts +0 -43
package/src/flags.ts +0 -53
package/src/fs.test.ts +0 -106
package/src/fs_win.test.ts +0 -11
package/src/generator.test.ts +0 -27
package/src/index.html +0 -82
package/src/is_browser.js +0 -1
package/src/lock.test.ts +0 -17
package/src/observable/observable.test.ts +0 -73
package/src/pico/_variables.scss +0 -66
package/src/pico/components/_accordion.scss +0 -112
package/src/pico/components/_button-group.scss +0 -51
package/src/pico/components/_card.scss +0 -47
package/src/pico/components/_dropdown.scss +0 -203
package/src/pico/components/_modal.scss +0 -181
package/src/pico/components/_nav.scss +0 -79
package/src/pico/components/_progress.scss +0 -70
package/src/pico/components/_property.scss +0 -34
package/src/pico/content/_button.scss +0 -152
package/src/pico/content/_code.scss +0 -63
package/src/pico/content/_embedded.scss +0 -0
package/src/pico/content/_form-alt.scss +0 -276
package/src/pico/content/_form.scss +0 -259
package/src/pico/content/_misc.scss +0 -0
package/src/pico/content/_table.scss +0 -28
package/src/pico/content/_toggle.scss +0 -132
package/src/pico/content/_typography.scss +0 -232
package/src/pico/layout/_container.scss +0 -40
package/src/pico/layout/_document.scss +0 -0
package/src/pico/layout/_flex.scss +0 -46
package/src/pico/layout/_grid.scss +0 -24
package/src/pico/layout/_scroller.scss +0 -16
package/src/pico/layout/_section.scss +0 -8
package/src/pico/layout/_sectioning.scss +0 -55
package/src/pico/pico.scss +0 -60
package/src/pico/reset/_accessibility.scss +0 -34
package/src/pico/reset/_button.scss +0 -17
package/src/pico/reset/_code.scss +0 -15
package/src/pico/reset/_document.scss +0 -48
package/src/pico/reset/_embedded.scss +0 -39
package/src/pico/reset/_form.scss +0 -97
package/src/pico/reset/_misc.scss +0 -23
package/src/pico/reset/_nav.scss +0 -5
package/src/pico/reset/_progress.scss +0 -4
package/src/pico/reset/_table.scss +0 -8
package/src/pico/reset/_typography.scss +0 -25
package/src/pico/themes/default/_colors.scss +0 -65
package/src/pico/themes/default/_dark.scss +0 -148
package/src/pico/themes/default/_light.scss +0 -149
package/src/pico/themes/default/_styles.scss +0 -272
package/src/pico/themes/default.scss +0 -34
package/src/pico/utilities/_accessibility.scss +0 -3
package/src/pico/utilities/_loading.scss +0 -52
package/src/pico/utilities/_reduce-motion.scss +0 -27
package/src/pico/utilities/_tooltip.scss +0 -101
package/src/result.test.ts +0 -101
package/src/scope/describe.ts +0 -81
package/src/scope/display/console.ts +0 -26
package/src/scope/display/dom.ts +0 -36
package/src/scope/display/junit.ts +0 -64
package/src/scope/execute.ts +0 -110
package/src/scope/expect.ts +0 -169
package/src/scope/fix.ts +0 -30
package/src/scope/index.ts +0 -11
package/src/scope/scope.ts +0 -21
package/src/scope/state.ts +0 -13
package/src/test.mjs +0 -33
package/src/test_all.ts +0 -35

package/src/dom/render.ts ADDED Viewed

@@ -0,0 +1,41 @@
+import { XHTML_NAMESPACE_URI } from "./dom.ts";
+export interface DocumentOptions {
+  body: Node | Node[];
+  head?: Node | Node[];
+  lang?: string;
+  doctype?: string;
+}
+export function renderToString(node: Node | Node[]): string {
+  if (Array.isArray(node)) return node.map(renderToString).join("");
+  if (node.nodeType === 1) {
+    const el = node as Element;
+    const html = el.outerHTML;
+    const ns = el.namespaceURI;
+    if (ns && ns !== XHTML_NAMESPACE_URI && !html.includes("xmlns=")) {
+      return html.replace(/^<([^\s>]+)/, `<$1 xmlns="${ns}"`);
+    }
+    return html;
+  }
+  if (node.nodeType === 11)
+    return Array.from(node.childNodes).map(renderToString).join("");
+  if (node.nodeType === 3) {
+    return (node.textContent ?? "")
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;");
+  }
+  return "";
+}
+export function renderDocument({
+  body,
+  head,
+  lang = "en",
+  doctype = "<!doctype html>",
+}: DocumentOptions): string {
+  const headStr = head != null ? renderToString(head) : "";
+  const bodyStr = renderToString(body);
+  return `${doctype}<html lang="${lang}"><head>${headStr}</head><body>${bodyStr}</body></html>`;
+}

package/src/dom/svg.ts CHANGED Viewed

@@ -3,7 +3,7 @@ import {
   type DenormChildren,
   SVG_NAMESPACE_URI,
   up,
-} from "./dom.js";
+} from "./dom.ts";
 const makeSVGElement =
   <K extends keyof SVGElementTagNameMap>(name: K) =>
@@ -11,7 +11,11 @@ const makeSVGElement =
     attrs?: DenormAttrs<SVGElementTagNameMap[K]>,
     ...children: DenormChildren[]
   ) =>
-    up(document.createElementNS(SVG_NAMESPACE_URI, name), attrs, ...children);
+    up(
+      window.document.createElementNS(SVG_NAMESPACE_URI, name),
+      attrs,
+      ...children,
+    );
 export const a = makeSVGElement("a");
 export const animate = makeSVGElement("animate");

package/src/fs_node.ts CHANGED Viewed

@@ -34,8 +34,8 @@ export class NodeFileSystemAdapter implements FileSystemAdapter {
   readdir(path: string): Promise<string[]> {
     return readdir(path);
   }
-  mkdir(path: string): Promise<void> {
-    return mkdir(path);
+  async mkdir(path: string): Promise<void> {
+    await mkdir(path, { recursive: true });
   }
   async scandir(path: string): Promise<Stats[]> {
     return Promise.all(

package/src/log.ts CHANGED Viewed

@@ -72,7 +72,7 @@ function findSource() {
   return atLines[2]?.trim().slice("at ".length) ?? "(unknown)";
 }
-type LoggerFormatFn = <
+export type LoggerFormatFn = <
   D extends {
     name: string;
     prefix: string;
@@ -84,6 +84,156 @@ type LoggerFormatFn = <
   data: D,
 ) => string;
+// ── prettyLogFormatter ──────────────────────────────────────────────────────
+// A TTY-aware formatter: compact, color-and-glyph-coded human lines on a
+// terminal, byte-identical JSON.stringify when piped/redirected so machine
+// tooling is unchanged. See docs/developer/2026-06-09-A-log-formatter/design.md.
+// Raw ANSI escapes; no color/log runtime dependency in this library.
+const ANSI = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+} as const;
+type AnsiCode = keyof typeof ANSI;
+// HH:MM:SS.mmm sliced from a UTC ISO 8601 string. Timezone-stable by
+// construction: it never reads local-time accessors, so output depends only on
+// the ISO input, not the runner's TZ.
+function shortClock(iso: string): string {
+  return iso.slice(11, 23);
+}
+// Glyph + color per severity, keyed on the numeric level (DEBUG 1, INFO 2,
+// WARN 3, ERROR 4). Fixed single-column glyph so messages align vertically.
+function levelGlyph(level: number): { glyph: string; color: AnsiCode } {
+  if (level <= LEVEL.DEBUG) return { glyph: "·", color: "dim" };
+  if (level === LEVEL.INFO) return { glyph: "ℹ", color: "green" };
+  if (level === LEVEL.WARN) return { glyph: "⚠", color: "yellow" };
+  return { glyph: "✖", color: "red" };
+}
+function methodColor(method: string): AnsiCode {
+  switch (method) {
+    case "GET":
+      return "cyan";
+    case "POST":
+      return "green";
+    case "PUT":
+    case "PATCH":
+      return "yellow";
+    case "DELETE":
+      return "red";
+    default:
+      return "white";
+  }
+}
+function statusColor(status: number): AnsiCode {
+  if (status >= 500) return "red";
+  if (status >= 400) return "yellow";
+  if (status >= 300) return "cyan";
+  return "green";
+}
+// Fields that are pure metadata noise on a human terminal: `name`/`level` are
+// constant or duplicate `prefix`, and `source` resolves to the info() wrapper.
+// `message` is rendered on its own, never echoed into the trailing tail.
+const HUMAN_DROP = new Set(["name", "prefix", "level", "source", "message"]);
+export interface PrettyLogOptions {
+  /** Render colored, human-shaped lines. Default: !!process.stdout.isTTY. */
+  tty?: boolean;
+  /** Emit ANSI color escapes. Default: same as `tty`. */
+  color?: boolean;
+  /** Injectable clock for deterministic timestamps in tests. Default: new Date. */
+  now?: () => Date;
+}
+/**
+ * Factory returning a {@link LoggerFormatFn} that is pretty + colored on a TTY
+ * and falls back to `JSON.stringify` when not. Options resolve once at
+ * construction (`tty` reads `process.stdout.isTTY`), so production piped output
+ * stays JSON; tests inject `tty`/`color`/`now` for a deterministic colorless
+ * layout assertable without a real terminal.
+ */
+export function prettyLogFormatter(
+  options: PrettyLogOptions = {},
+): LoggerFormatFn {
+  const tty = options.tty ?? !!process.stdout.isTTY;
+  const color = options.color ?? tty;
+  const now = options.now ?? (() => new Date());
+  const paint = (code: AnsiCode, s: string): string =>
+    color ? `${ANSI[code]}${s}${ANSI.reset}` : s;
+  return <
+    D extends {
+      name: string;
+      prefix: string;
+      level: number;
+      message: string;
+      source: string;
+    },
+  >(
+    data: D,
+  ): string => {
+    if (!tty) return JSON.stringify(data);
+    const record = data as unknown as Record<string, unknown>;
+    const { glyph, color: glyphColor } = levelGlyph(data.level);
+    const mark = paint(glyphColor, glyph);
+    // Access-log shape: `<glyph> <clock> <METHOD> <path> <client> [status] [ms]`.
+    // Clock comes from the request's `when` ISO (UTC slice), not now().
+    if (data.message === "Request") {
+      const when = typeof record.when === "string" ? record.when : "";
+      const how = typeof record.how === "string" ? record.how : "";
+      const space = how.indexOf(" ");
+      const method = space === -1 ? how : how.slice(0, space);
+      const path = space === -1 ? "" : how.slice(space + 1);
+      const segments = [
+        mark,
+        paint("dim", shortClock(when || now().toISOString())),
+        paint(methodColor(method), method),
+        paint("bold", path),
+      ];
+      if (record.who !== undefined) {
+        segments.push(paint("dim", String(record.who)));
+      }
+      if (record.status !== undefined) {
+        segments.push(
+          paint(statusColor(Number(record.status)), String(record.status)),
+        );
+      }
+      if (record.ms !== undefined) {
+        segments.push(paint("dim", `${record.ms}ms`));
+      }
+      return segments.filter((s) => s !== "").join(" ");
+    }
+    // Generic shape: `<glyph> <clock> <message> <dim key=value …>`.
+    const tail = Object.entries(record)
+      .filter(([key]) => !HUMAN_DROP.has(key))
+      .map(([key, value]) =>
+        paint(
+          "dim",
+          `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`,
+        ),
+      );
+    return [
+      mark,
+      paint("dim", shortClock(now().toISOString())),
+      paint("bold", data.message),
+      ...tail,
+    ].join(" ");
+  };
+}
 export function getLogger(
   name: string,
   args: LoggerFormatFn | { format?: LoggerFormatFn; console?: Console } = {
@@ -132,7 +282,9 @@ export function getLogger(
   return logger as Logger;
 }
-export const DEFAULT_LOGGER = getLogger("default");
+export const DEFAULT_LOGGER = getLogger("default", {
+  format: prettyLogFormatter(),
+});
 export function debug(message: Display, data?: object) {
   if (data) DEFAULT_LOGGER.debug(message, data);

package/src/server/http/response.ts CHANGED Viewed

@@ -2,7 +2,7 @@ import type { Stats } from "node:fs";
 import * as fs from "node:fs/promises";
 import type { StaticResponse } from ".";
-const MIME_TYPES: Record<string, string> = {
+const MIME_TYPES = {
   js: "text/javascript",
   ts: "text/javascript",
   json: "text/javascript",
@@ -16,13 +16,16 @@ const MIME_TYPES: Record<string, string> = {
   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] ?? "application/octet-stream";
+  return (
+    MIME_TYPES[extension as keyof typeof MIME_TYPES] ??
+    "application/octet-stream"
+  );
 };
 export const fileResponse =

package/src/server/http/sitemap.ts CHANGED Viewed

@@ -4,41 +4,17 @@ import { info } from "../../log.ts";
 import type { MiddlewareFactory } from "./index.ts";
 import { contentResponse } from "./response.ts";
-const findSiteMap = async (root: string, prefix = root) => {
-  if (root.startsWith("node_modules")) {
-    return [];
-  }
-  const children = (await fs.readdir(root, { withFileTypes: true })).map(
-    async (entry): Promise<string[]> => {
-      const next = path
-        .join(root, entry.name)
-        // Normalize separators for web
-        .replaceAll(path.sep, "/");
-      if (entry.isFile()) {
-        if (entry.name === "index.html") {
-          const index = next.replace(prefix, "");
-          info("Adding to sitemap", { index });
-          return [index];
-        }
-      } else if (entry.isDirectory()) {
-        if (entry.name.startsWith(".")) {
-          return [];
-        }
-        const flattened = (
-          await Promise.all(await findSiteMap(next, prefix))
-        ).flat();
-        return flattened;
-      }
-      return [];
-    },
-  );
-  return children;
-};
 export const sitemap: MiddlewareFactory = async ({ root }) => {
-  const apps = await (await Promise.all(await findSiteMap(root)))
-    .flat()
-    .filter((a) => a !== undefined);
+  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");

package/src/server/http/static.ts CHANGED Viewed

@@ -14,8 +14,6 @@ export const staticFileServer: MiddlewareFactory =
       ? url.pathname.replace(scope[0], scope[1])
       : url.pathname;
     const filename = path.join(root, pathname);
-    // Expand url with found scope
-    console.log(scope, req.url, filename);
     try {
       const stat = await fs.stat(filename);

package/src/server/live-reload.ts ADDED Viewed

@@ -0,0 +1,208 @@
+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/main.ts CHANGED Viewed

@@ -1,23 +1,30 @@
-#!/usr/bin/env node --experimental-loader ../loader.mjs
+#!/usr/bin/env node
 import * as process from "node:process";
 import { info } from "../log.ts";
 info("Starting server", { cwd: process.cwd() });
-import { parse } from "../flags.ts";
+import { parseArgs } from "node:util";
-const FLAGS = parse(process.argv);
+// Declared up front so an unknown flag fails fast: parseArgs defaults to
+// strict: true, which throws on undeclared options. The throw happens at module
+// top level (before main() listens), so a malformed invocation exits non-zero
+// and never reaches the listening state. With no flags the defaults reproduce
+// the prior bind target (0.0.0.0:8080).
+const { values } = parseArgs({
+  options: {
+    port: { type: "string", default: "8080" },
+    host: { type: "string", default: "0.0.0.0" },
+  },
+});
 import * as path from "node:path";
 import { makeServer } from "./http/index.ts";
 async function main() {
   const server = await makeServer({ root: path.join(process.cwd(), "src") });
-  server.listen(
-    FLAGS.asNumber("port", 8080),
-    FLAGS.asString("host", "0.0.0.0"),
-  );
+  server.listen(Number.parseInt(values.port, 10), values.host);
 }
 main();

package/src/server/ws/frame.ts ADDED Viewed

@@ -0,0 +1,36 @@
+// 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 ADDED Viewed

@@ -0,0 +1,42 @@
+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;
+}