@weborigami/origami 0.6.13 → 0.6.15

package/main.js

@@ -1,5 +1,6 @@
 export { default as documentObject } from "./src/common/documentObject.js";
 export * from "./src/common/serialize.js";
+export { default as debugParent } from "./src/dev/debug2/debugParent.js";
 export * as Dev from "./src/dev/dev.js";
 export * as Origami from "./src/origami/origami.js";
 export { default as origamiHighlightDefinition } from "./src/origami/origamiHighlightDefinition.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "Web Origami language, CLI, framework, and server",
   "type": "module",
   "repository": {
@@ -18,9 +18,9 @@
   },
   "dependencies": {
     "@hpcc-js/wasm-graphviz": "^1.21.0",
-    "@weborigami/async-tree": "0.6.13",
+    "@weborigami/async-tree": "0.6.15",
     "@weborigami/json-feed-to-rss": "1.0.1",
-    "@weborigami/language": "0.6.13",
+    "@weborigami/language": "0.6.15",
     "css-tree": "3.1.0",
     "highlight.js": "11.11.1",
     "jsdom": "28.1.0",

package/src/dev/debug2/debug2.js

@@ -1,38 +1,33 @@
-import { OrigamiFileMap } from "@weborigami/language";
-import { fork } from "node:child_process";
-import http from "node:http";
-import path from "node:path";
-
-const PUBLIC_HOST = "127.0.0.1";
-const PUBLIC_PORT = 5000;
-
-// Module that loads the server in the child process
-const childModuleUrl = new URL("./debugChild.js", import.meta.url);
-
-// The active child process and port
-/** @typedef {import("node:child_process").ChildProcess} ChildProcess */
-/** @typedef {{ process: ChildProcess, port: number | null }} ChildInfo */
-/** @type {ChildInfo | null} */
-let activeChild = null;
-
-// The most recently started child (may not be ready yet)
-/** @type {ChildInfo | null} */
-let pendingChild = null;
+import { execute } from "@weborigami/language";
+import debugParent from "./debugParent.js";
 
 /**
- * Given an Origami function, determine the runtime state's parent container,
- * then start a new debug server with that parent as the root of the resource
- * tree.
+ * Given an Origami expression, start a new debug server with that parent as the
+ * root of the resource tree.
+ *
+ * This function expects unevaluated arguments. This is what it allows it to
+ * extract the source code of the expression to be debugged. (If it were
+ * evaluated, the function will be called with the result of the expression.)
  *
- * This function expects an unevaluated expression. It will obtain the original
- * source of the expression and pass that to the child for evaluation. This
- * arrangement ensures the expression is evaluated in a clean Node context (not
- * polluted by previous evaluations).
+ * The `options` argument can include:
+ * - `enableUnsafeEval`: if true, enables the `!eval` debug command in the child
+ *   process; default is false
+ * - `debugFilesPath`: path to resources that will be added to the served tree
  *
- * @param {import("@weborigami/language").AnnotatedCode} code
- * @param {import("@weborigami/language").RuntimeState} state
+ * @typedef {import("@weborigami/language").RuntimeState} RuntimeState
+ * @typedef {import("@weborigami/language").AnnotatedCode} AnnotatedCode
+ *
+ * @param {AnnotatedCode} code
+ * @param {any | RuntimeState} options
+ * @param {RuntimeState} state
  */
-export default async function debug2(code, state) {
+export default async function debug2(code, options, state) {
+  if (state === undefined) {
+    // Options were omitted; shift arguments
+    state = options;
+    options = [];
+  }
+
   if (
     !(code instanceof Array) ||
     code.source === undefined ||
@@ -42,6 +37,9 @@ export default async function debug2(code, state) {
       "Dev.debug2 expects an Origami expression to evaluate: `debug2 <expression>`",
     );
   }
+
+  const expression = code.source;
+
   const { parent } = state;
   // @ts-ignore
   const parentPath = parent?.path;
@@ -49,253 +47,23 @@ export default async function debug2(code, state) {
     throw new Error("Dev.debug2 couldn't work out the parent path.");
   }
 
-  const serverOptions = {
-    expression: code.source,
-    parent: parentPath,
-  };
-
-  const tree = new OrigamiFileMap(parentPath);
-  tree.watch();
-  tree.addEventListener?.("change", (event) => {
-    // @ts-ignore
-    const { filePath } = event.options;
-    if (isJavaScriptFile(filePath)) {
-      // Need to restart the child process
-      console.log("JavaScript file changed, restarting server…");
-      startChild(serverOptions);
-    } else if (isPackageJsonFile(filePath)) {
-      // Need to restart the child process
-      console.log("package.json changed, restarting server…");
-      startChild(serverOptions);
-    } else {
-      // Just have the child reevaluate the expression
-      console.log("File changed, reloading site…");
-      activeChild?.process.send({ type: "REEVALUATE" });
-    }
-  });
+  // Need to evaluate options object
+  if (options.length > 0) {
+    options = await execute(options, state);
+  } else {
+    options = {};
+  }
 
-  // ---- Public server
-  const publicServer = http.createServer(proxyRequest);
-  publicServer.listen(PUBLIC_PORT, PUBLIC_HOST, () => {
-    startChild(serverOptions);
-    console.log(
-      `Server running at http://localhost:${PUBLIC_PORT}. Press Ctrl+C to stop.`,
-    );
+  // @ts-ignore
+  const enableUnsafeEval = options.enableUnsafeEval ?? false;
+  const debugFilesPath = options.debugFilesPath ?? "";
+
+  await debugParent({
+    debugFilesPath,
+    enableUnsafeEval,
+    expression,
+    parentPath,
   });
 }
 debug2.needsState = true;
 debug2.unevaluatedArgs = true;
-
-/**
- * Give a child process a chance to finish any in-flight requests before we kill
- * it.
- *
- * @param {ChildProcess} childProcess
- */
-async function drainAndStopChild(childProcess) {
-  if (childProcess.killed) {
-    return;
-  }
-
-  // Ask it to drain first.
-  try {
-    childProcess.send({ type: "DRAIN" });
-  } catch {
-    // ignore
-  }
-
-  const drained = new Promise((resolve) => {
-    const onMessage = (msg) => {
-      if (msg && typeof msg === "object" && msg.type === "DRAINED") {
-        cleanup(resolve);
-      }
-    };
-    const onExit = () => cleanup(resolve);
-
-    function cleanup(done) {
-      childProcess.off("message", onMessage);
-      childProcess.off("exit", onExit);
-      done();
-    }
-
-    childProcess.on("message", onMessage);
-    childProcess.on("exit", onExit);
-  });
-
-  // Give it a short grace window to finish in-flight work.
-  const GRACE_MS = 1500;
-  await Promise.race([
-    drained,
-    new Promise((r) => setTimeout(r, GRACE_MS).unref()),
-  ]);
-
-  if (!childProcess.killed) {
-    childProcess.kill("SIGTERM");
-  }
-
-  // Final escalation.
-  setTimeout(() => {
-    // Child should have exited by now, but if not kill it
-    if (!childProcess.killed) {
-      childProcess.kill("SIGKILL");
-    }
-  }, GRACE_MS).unref();
-}
-
-function isJavaScriptFile(filePath) {
-  const extname = path.extname(filePath).toLowerCase();
-  const jsExtensions = [".cjs", ".js", ".mjs", ".ts"];
-  return jsExtensions.includes(extname);
-}
-
-function isPackageJsonFile(filePath) {
-  return path.basename(filePath).toLowerCase() === "package.json";
-}
-
-/**
- * Proxy incoming requests to the active child server, or return a 503 if not
- * ready.
- *
- * @param {import("node:http").IncomingMessage} request
- * @param {import("node:http").ServerResponse} response
- */
-function proxyRequest(request, response) {
-  if (!activeChild) {
-    response.statusCode = 503;
-    response.setHeader("content-type", "text/plain; charset=utf-8");
-    response.end("Dev server is starting…\n");
-    return;
-  }
-
-  const { port } = activeChild;
-
-  // Minimal hop-by-hop header stripping
-  const headers = { ...request.headers };
-  delete headers.connection;
-  delete headers["proxy-connection"];
-  delete headers["keep-alive"];
-  delete headers.te;
-  delete headers.trailer;
-  delete headers["transfer-encoding"];
-  delete headers.upgrade;
-
-  const upstreamRequest = http.request(
-    {
-      host: PUBLIC_HOST,
-      port,
-      method: request.method,
-      path: request.url,
-      headers,
-    },
-    (upstreamResponse) => {
-      response.writeHead(
-        upstreamResponse.statusCode ?? 502,
-        upstreamResponse.statusMessage,
-        upstreamResponse.headers,
-      );
-      upstreamResponse.pipe(response);
-    },
-  );
-
-  upstreamRequest.on("error", (err) => {
-    // Stop piping the request body
-    request.unpipe(upstreamRequest);
-    upstreamRequest.destroy();
-
-    // Only send error response if headers haven't been sent yet
-    if (!response.headersSent) {
-      response.statusCode = 502;
-      response.setHeader("content-type", "text/plain; charset=utf-8");
-      response.end(`Upstream error: ${err.message}\n`);
-    } else {
-      // Headers already sent, can't send error message - just close
-      response.destroy();
-    }
-  });
-
-  // Also handle errors on the incoming request
-  request.on("error", () => {
-    upstreamRequest.destroy();
-  });
-
-  request.pipe(upstreamRequest);
-}
-
-/**
- * Start a new child process.
- *
- * This will be a pending process until it sends a READY message, at which point
- * it becomes active and any previous active child is drained and stopped.
- */
-function startChild(serverOptions) {
-  const { expression, parent } = serverOptions;
-
-  // Start the child process, passing parent path via an environment variable.
-  /** @type {ChildProcess} */
-  let childProcess;
-  try {
-    childProcess = fork(childModuleUrl, [], {
-      stdio: ["inherit", "inherit", "inherit", "ipc"],
-      env: {
-        ...process.env,
-        ORIGAMI_EXPRESSION: expression,
-        ORIGAMI_PARENT: parent,
-      },
-    });
-  } catch (error) {
-    throw new Error("Dev.debug2: failed to start child server:", {
-      cause: error,
-    });
-  }
-
-  // This becomes the pending child immediately
-  pendingChild = { process: childProcess, port: null };
-
-  // Listen for messages from the child about its status
-  childProcess.on("message", (/** @type {any} */ message) => {
-    if (!message || typeof message !== "object") {
-      return;
-    }
-
-    if (message.type === "READY" && typeof message.port === "number") {
-      // Only promote to active if this is still the pending child
-      if (pendingChild?.process === childProcess) {
-        const previousChild = activeChild;
-
-        activeChild = pendingChild;
-        pendingChild.port = message.port;
-        pendingChild = null;
-
-        // Drain previous child in background (don't wait)
-        if (previousChild?.process && previousChild.process !== childProcess) {
-          drainAndStopChild(previousChild.process).catch((err) =>
-            console.error("[drain]", err),
-          );
-        }
-      } else {
-        // This child was superseded by a newer one, kill it
-        // console.log("Child process superseded by newer one, killing it...");
-        childProcess.kill("SIGTERM");
-      }
-    }
-
-    if (message.type === "FATAL") {
-      // Child couldn't start (import error, etc.)
-      // Keep previous active child if any; otherwise we'll serve 500/503.
-      console.error("[child fatal]", message.error ?? message);
-      if (pendingChild?.process === childProcess) {
-        pendingChild = null;
-      }
-    }
-  });
-
-  childProcess.on("exit", (code, signal) => {
-    if (activeChild?.process === childProcess) {
-      // Active child died unexpectedly.
-      activeChild = null;
-    }
-    if (pendingChild?.process === childProcess) {
-      pendingChild = null;
-    }
-  });
-}

package/src/dev/debug2/debugChild.js

@@ -3,7 +3,7 @@ import { requestListener } from "../../server/server.js";
 import expressionTree from "./expressionTree.js";
 
 /**
- * The debug2 command runs this module in a child process, passing in a parent
+ * The debug parent runs this module in a child process, passing in a parent
  * path in an environment variable.
  *
  * This module starts an HTTP server that will serve resources from that tree.
@@ -22,6 +22,13 @@ function fail(message) {
   process.exit(1);
 }
 
+/** @type {string} */
+const debugFilesPath = process.env.ORIGAMI_DEBUG_FILES_PATH ?? "";
+
+/** @type {boolean} */
+// @ts-ignore
+const enableUnsafeEval = process.env.ORIGAMI_ENABLE_UNSAFE_EVAL === "1";
+
 /** @type {string} */
 // @ts-ignore
 const expression = process.env.ORIGAMI_EXPRESSION;
@@ -31,7 +38,7 @@ if (expression === undefined) {
 
 /** @type {string} */
 // @ts-ignore
-const parentPath = process.env.ORIGAMI_PARENT;
+const parentPath = process.env.ORIGAMI_PARENT_PATH;
 if (parentPath === undefined) {
   fail("Missing Origami parent");
 }
@@ -88,7 +95,12 @@ function beginDrain() {
 }
 
 async function evaluateExpression() {
-  const tree = await expressionTree(expression, parentPath);
+  const tree = await expressionTree({
+    debugFilesPath,
+    expression,
+    parentPath,
+    enableUnsafeEval,
+  });
   if (!tree) {
     fail("Dev.debug2: expression did not evaluate to a maplike resource tree");
   }

package/src/dev/debug2/debugCommands.js

@@ -0,0 +1,29 @@
+// Subset of commands made available via debugTransform
+
+import { Tree } from "@weborigami/async-tree";
+
+import index from "../../origami/indexPage.js";
+import yaml from "../../origami/yaml.js";
+import explore from "../explore.js";
+import svg from "../svg.js";
+import version from "../version.js";
+import oriEval from "./oriEval.js";
+
+export default function debugCommands(enableUnsafeEval = false) {
+  return Object.assign(
+    {
+      keys: Tree.keys,
+      json: Tree.json,
+      index,
+      yaml,
+      explore,
+      svg,
+      version,
+    },
+    enableUnsafeEval
+      ? {
+          eval: oriEval,
+        }
+      : {},
+  );
+}

package/src/dev/debug2/debugParent.js

@@ -0,0 +1,414 @@
+import { OrigamiFileMap } from "@weborigami/language";
+import { fork } from "node:child_process";
+import { EventEmitter } from "node:events";
+import http from "node:http";
+import net from "node:net";
+import path from "node:path";
+
+const PUBLIC_HOST = "127.0.0.1";
+const DEFAULT_PORT = 5000;
+
+// Module that loads the server in the child process
+const childModuleUrl = new URL("./debugChild.js", import.meta.url);
+
+// The public-facing server that proxies to the child process
+let publicServer;
+let publicOrigin;
+
+// The tree of files in the parent path, which we watch for changes
+let tree;
+
+// The active child process and port
+/** @typedef {import("node:child_process").ChildProcess} ChildProcess */
+/** @typedef {{ process: ChildProcess, port: number | null }} ChildInfo */
+/** @type {ChildInfo | null} */
+let activeChild = null;
+
+// The most recently started child (may not be ready yet)
+/** @type {ChildInfo | null} */
+let pendingChild = null;
+
+// Used to communicate errors to caller
+let emitter = null;
+
+/**
+ * Start a new debug parent server for the given Origami expression and runtime
+ * state.
+ *
+ * This function will start a child server that evaluates the given expression
+ * with the given parent path. This arrangement ensures the expression is
+ * evaluated in a clean Node context (not polluted by previous evaluations). The
+ * parent server proxies requests to the child server.
+ *
+ * The debug parent monitors the parent tree for changes, and restarts the child
+ * whenever files in the parent tree change.
+ *
+ * Supported `options`:
+ * - `debugFilesPath`: path to resources that will be added to the served tree
+ * - `enableUnsafeEval`: if true, enables the `!eval` debug command in the child
+ *   process; default is false
+ * - `expression` (required): the Origami expression to evaluate in the child
+ *   process
+ * - `parentPath` (required): the path to the parent tree used for evaluation
+ *
+ * The returned `emitter` is an EventEmitter that emits "error" events when the
+ * child server encounters an Origami error while handling a request.
+ *
+ * @param {Object} options
+ * @param {string} options.debugFilesPath
+ * @param {boolean} options.enableUnsafeEval
+ * @param {string} options.expression
+ * @param {string} options.parentPath
+ */
+export default async function debugParent(options) {
+  const { parentPath } = options;
+
+  tree = new OrigamiFileMap(parentPath);
+  tree.watch();
+  tree.addEventListener?.("change", (event) => {
+    // @ts-ignore
+    const { filePath } = event.options;
+    if (isJavaScriptFile(filePath)) {
+      // Need to restart the child process
+      console.log("JavaScript file changed, restarting server…");
+      startChild(options);
+    } else if (isPackageJsonFile(filePath)) {
+      // Need to restart the child process
+      console.log("package.json changed, restarting server…");
+      startChild(options);
+    } else {
+      // Just have the child reevaluate the expression
+      console.log("File changed, reloading site…");
+      activeChild?.process.send({ type: "REEVALUATE" });
+    }
+  });
+
+  const port = await findOpenPort();
+  publicOrigin = `http://${PUBLIC_HOST}:${port}`;
+
+  publicServer = http.createServer(proxyRequest);
+  publicServer.listen(port, PUBLIC_HOST, () => {
+    startChild(options);
+    console.log(`Server running at ${publicOrigin}. Press Ctrl+C to stop.`);
+  });
+
+  emitter = Object.assign(new EventEmitter(), {
+    close,
+  });
+
+  return emitter;
+}
+
+/**
+ * Gracefully stop the parent server and any active child server, giving the
+ * child a chance to finish any in-flight requests before exiting.
+ */
+async function close() {
+  // Stop accepting new connections and force-close any keep-alive connections
+  // so the close callback fires promptly.
+  const closed = new Promise((resolve) => publicServer.close(resolve));
+  publicServer.closeAllConnections();
+  await closed;
+  publicServer = null;
+  emitter = null;
+
+  // Drain and stop any children concurrently
+  const children = [pendingChild?.process, activeChild?.process].filter(
+    /** @returns {child is ChildProcess} */
+    (child) => child !== undefined,
+  );
+  pendingChild = null;
+  activeChild = null;
+  await Promise.all(children.map(drainAndStopChild));
+
+  // Stop watching for file changes
+  tree.unwatch();
+  tree = null;
+}
+
+/**
+ * Give a child process a chance to finish any in-flight requests before we kill
+ * it.
+ *
+ * @param {ChildProcess} childProcess
+ */
+async function drainAndStopChild(childProcess) {
+  if (childProcess.killed) {
+    return;
+  }
+
+  // Ask it to drain first.
+  try {
+    childProcess.send({ type: "DRAIN" });
+  } catch {
+    // ignore
+  }
+
+  const drained = new Promise((resolve) => {
+    const onMessage = (msg) => {
+      if (msg && typeof msg === "object" && msg.type === "DRAINED") {
+        cleanup(resolve);
+      }
+    };
+    const onExit = () => cleanup(resolve);
+
+    function cleanup(done) {
+      childProcess.off("message", onMessage);
+      childProcess.off("exit", onExit);
+      done();
+    }
+
+    childProcess.on("message", onMessage);
+    childProcess.on("exit", onExit);
+  });
+
+  // Give it a short grace window to finish in-flight work.
+  const GRACE_MS = 1500;
+  await Promise.race([
+    drained,
+    new Promise((r) => setTimeout(r, GRACE_MS).unref()),
+  ]);
+
+  if (!childProcess.killed) {
+    childProcess.kill("SIGTERM");
+  }
+
+  // Final escalation.
+  setTimeout(() => {
+    // Child should have exited by now, but if not kill it
+    if (!childProcess.killed) {
+      childProcess.kill("SIGKILL");
+    }
+  }, GRACE_MS).unref();
+}
+
+// Return the first open port number on or after the given port number.
+async function findOpenPort(startPort = DEFAULT_PORT) {
+  for (let port = startPort; port <= 65535; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+
+  throw new Error(`No open port found on or after ${startPort}`);
+}
+
+function isJavaScriptFile(filePath) {
+  const extname = path.extname(filePath).toLowerCase();
+  const jsExtensions = [".cjs", ".js", ".mjs", ".ts"];
+  return jsExtensions.includes(extname);
+}
+
+function isPackageJsonFile(filePath) {
+  return path.basename(filePath).toLowerCase() === "package.json";
+}
+
+/**
+ * Check whether a port is available on both IPv4 and IPv6 loopback addresses
+ * by attempting TCP connections. On macOS, IPv4 and IPv6 port spaces are
+ * independent (IPV6_V6ONLY=1 by default), so a server bound to [::]:PORT is
+ * invisible to a 127.0.0.1 bind check. Using connect probes on both loopbacks
+ * catches servers regardless of which protocol family they listen on. Any
+ * connection error (ECONNREFUSED, EADDRNOTAVAIL, etc.) means nothing is
+ * listening there, so the function is safe on systems without IPv6.
+ *
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+async function isPortAvailable(port) {
+  const [v4, v6] = await Promise.all([
+    isPortListening("127.0.0.1", port),
+    isPortListening("::1", port),
+  ]);
+  return !v4 && !v6;
+}
+
+/**
+ * @param {string} host
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+function isPortListening(host, port) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection(port, host);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Proxy incoming requests to the active child server, or return a 503 if not
+ * ready.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ */
+function proxyRequest(request, response) {
+  if (!activeChild) {
+    response.statusCode = 503;
+    response.setHeader("content-type", "text/plain; charset=utf-8");
+    response.end("Dev server is starting…\n");
+    return;
+  }
+
+  const { port } = activeChild;
+
+  // Minimal hop-by-hop header stripping
+  const headers = { ...request.headers };
+  delete headers.connection;
+  delete headers["proxy-connection"];
+  delete headers["keep-alive"];
+  delete headers.te;
+  delete headers.trailer;
+  delete headers["transfer-encoding"];
+  delete headers.upgrade;
+
+  const upstreamRequest = http.request(
+    {
+      host: PUBLIC_HOST,
+      port,
+      method: request.method,
+      path: request.url,
+      headers,
+    },
+    (upstreamResponse) => {
+      const { statusCode } = upstreamResponse;
+      response.writeHead(
+        statusCode ?? 502,
+        upstreamResponse.statusMessage,
+        upstreamResponse.headers,
+      );
+      upstreamResponse.pipe(response);
+
+      // Let caller know about the Origami error messages
+      if (statusCode !== undefined && statusCode >= 500 && emitter) {
+        const rawHeader = upstreamResponse.headers["x-error-details"];
+        const raw = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+        const message = raw ? decodeURIComponent(raw) : undefined;
+        if (message) {
+          emitter.emit("origami-error", message);
+        }
+      }
+    },
+  );
+
+  upstreamRequest.on("error", (err) => {
+    // Stop piping the request body
+    request.unpipe(upstreamRequest);
+    upstreamRequest.destroy();
+
+    // Only send error response if headers haven't been sent yet
+    if (!response.headersSent) {
+      response.statusCode = 502;
+      response.setHeader("content-type", "text/plain; charset=utf-8");
+      response.end(`Upstream error: ${err.message}\n`);
+    } else {
+      // Headers already sent, can't send error message - just close
+      response.destroy();
+    }
+  });
+
+  // Also handle errors on the incoming request
+  request.on("error", () => {
+    upstreamRequest.destroy();
+  });
+
+  request.pipe(upstreamRequest);
+}
+
+/**
+ * Start a new child process.
+ *
+ * This will be a pending process until it sends a READY message, at which point
+ * it becomes active and any previous active child is drained and stopped.
+ */
+function startChild(options) {
+  const { debugFilesPath, enableUnsafeEval, expression, parentPath } = options;
+
+  // Start the child process, passing parent path via an environment variable.
+  /** @type {ChildProcess} */
+  let childProcess;
+  try {
+    childProcess = fork(childModuleUrl, [], {
+      stdio: ["inherit", "inherit", "inherit", "ipc"],
+      env: {
+        ...process.env,
+        ORIGAMI_DEBUG_FILES_PATH: debugFilesPath,
+        ORIGAMI_ENABLE_UNSAFE_EVAL: enableUnsafeEval ? "1" : "0",
+        ORIGAMI_EXPRESSION: expression,
+        ORIGAMI_PARENT_PATH: parentPath,
+      },
+    });
+  } catch (error) {
+    throw new Error("Dev.debug2: failed to start child server:", {
+      cause: error,
+    });
+  }
+
+  // This becomes the pending child immediately
+  pendingChild = { process: childProcess, port: null };
+
+  // Listen for messages from the child about its status
+  childProcess.on("message", (/** @type {any} */ message) => {
+    if (!message || typeof message !== "object") {
+      return;
+    }
+
+    if (message.type === "READY" && typeof message.port === "number") {
+      // Only promote to active if this is still the pending child
+      if (pendingChild?.process === childProcess) {
+        const previousChild = activeChild;
+
+        activeChild = pendingChild;
+        pendingChild.port = message.port;
+        pendingChild = null;
+
+        // Drain previous child in background (don't wait)
+        if (previousChild?.process && previousChild.process !== childProcess) {
+          drainAndStopChild(previousChild.process).catch((err) =>
+            console.error("[drain]", err),
+          );
+        }
+
+        if (!emitter) {
+          console.warn(
+            "Dev.debug2: child server is ready but parent emitter is gone, cannot emit ready event",
+          );
+          return;
+        }
+        emitter.emit("ready", {
+          origin: publicOrigin,
+        });
+      } else {
+        // This child was superseded by a newer one, kill it
+        // console.log("Child process superseded by newer one, killing it...");
+        childProcess.kill("SIGTERM");
+      }
+    }
+
+    if (message.type === "FATAL") {
+      // Child couldn't start (import error, etc.)
+      // Keep previous active child if any; otherwise we'll serve 500/503.
+      console.error("[child fatal]", message.error ?? message);
+      if (pendingChild?.process === childProcess) {
+        pendingChild = null;
+      }
+    }
+  });
+
+  childProcess.on("exit", (code, signal) => {
+    if (activeChild?.process === childProcess) {
+      // Active child died unexpectedly.
+      activeChild = null;
+    }
+    if (pendingChild?.process === childProcess) {
+      pendingChild = null;
+    }
+  });
+}

package/src/dev/debug2/debugTransform.js

@@ -9,9 +9,10 @@ import {
   scope,
   trailingSlash,
 } from "@weborigami/async-tree";
-import { projectGlobals } from "@weborigami/language";
+import { OrigamiFileMap } from "@weborigami/language";
 import indexPage from "../../origami/indexPage.js";
 import yaml from "../../origami/yaml.js";
+import debugCommands from "./debugCommands.js";
 
 /**
  * Transform the given map-based tree to add debugging resources:
@@ -23,9 +24,19 @@ import yaml from "../../origami/yaml.js";
  * Also transform a simple object result to YAML for viewing.
  *
  * @param {import("@weborigami/async-tree").Maplike} maplike
+ * @param {string} debugFilesPath
+ * @param {boolean} enableUnsafeEval
  */
-export default function debugTransform(maplike) {
+export default function debugTransform(
+  maplike,
+  debugFilesPath = "",
+  enableUnsafeEval = false,
+) {
   const source = Tree.from(maplike, { deep: true });
+  const commands = debugCommands(enableUnsafeEval);
+
+  const debugFiles = debugFilesPath ? new OrigamiFileMap(debugFilesPath) : null;
+
   return Object.assign(new AsyncMap(), {
     description: "debug resources",
 
@@ -33,15 +44,22 @@ export default function debugTransform(maplike) {
       // Ask the tree if it has the key.
       let value = await source.get(key);
 
+      if (value === undefined && debugFiles) {
+        // Try the debug files
+        value = await debugFiles.get(key);
+      }
+
       if (value === undefined) {
-        // The tree doesn't have the key; try the defaults.
-        if (key === "index.html") {
+        // Try the defaults and commands
+        if (key === "_debugger/") {
+          return debugFiles;
+        } else if (key === "index.html") {
           // Generate an index page for this site
           value = await indexPage(source);
         } else if (key === ".keys.json") {
           value = await jsonKeys.stringify(source);
         } else if (typeof key === "string" && key.startsWith("!")) {
-          value = await invokeOrigamiCommand(source, key);
+          value = await invokeOrigamiCommand(commands, source, key);
         }
       }
 
@@ -60,8 +78,9 @@ export default function debugTransform(maplike) {
       }
 
       if (Tree.isMap(value)) {
-        // Ensure this transform is applied to any map result
-        value = debugTransform(value);
+        // Ensure this transform is applied to any map result.
+        // Note: debugFilesPath only needed at top level.
+        value = debugTransform(value, "", enableUnsafeEval);
       } else if (value?.unpack) {
         // If the value isn't a tree, but has a tree attached via an `unpack`
         // method, wrap the unpack method to add this transform.
@@ -95,13 +114,12 @@ export default function debugTransform(maplike) {
   });
 }
 
-async function invokeOrigamiCommand(tree, key) {
+async function invokeOrigamiCommand(commands, tree, key) {
   // Key is an Origami command; invoke it.
-  const globals = await projectGlobals(tree);
   const commandName = trailingSlash.remove(key.slice(1).trim());
 
-  // Look for command as a global or Dev command
-  const command = globals[commandName] ?? globals.Dev?.[commandName];
+  // Look for the indicated command
+  const command = commands[commandName];
   let value;
   if (command) {
     value = await command(tree);

package/src/dev/debug2/expressionTree.js

@@ -14,10 +14,15 @@ let version = 0;
  * Evaluate the given expression using the indicated parent path to produce a
  * resource tree, then transform that tree with debug resources and return it.
  *
- * @param {string} expression
- * @param {string} parentPath
+ * @param {Object} options
+ * @param {string} options.debugFilesPath
+ * @param {boolean} options.enableUnsafeEval
+ * @param {string} options.expression
+ * @param {string} options.parentPath
  */
-export default async function expressionTree(expression, parentPath) {
+export default async function expressionTree(options) {
+  const { debugFilesPath, expression, parentPath, enableUnsafeEval } = options;
+
   const parent = new OrigamiFileMap(parentPath);
   const globals = await projectGlobals(parent);
 
@@ -42,7 +47,7 @@ export default async function expressionTree(expression, parentPath) {
   setParent(maplike, parent);
 
   // Add debugging resources
-  const tree = debugTransform(maplike);
+  const tree = debugTransform(maplike, debugFilesPath, enableUnsafeEval);
 
   /** @type {any} */ (tree).version = version++;
 

package/src/dev/debug2/oriEval.js

@@ -0,0 +1,17 @@
+import ori from "../../origami/ori.js";
+
+let lastExpression;
+let lastResult;
+
+export default async function oriEval(parent) {
+  return async (encodedExpression) => {
+    console.log(encodedExpression);
+    const expression = decodeURIComponent(encodedExpression);
+    if (expression === lastExpression) {
+      return lastResult;
+    }
+    lastExpression = expression;
+    lastResult = await ori(expression, { parent });
+    return lastResult;
+  };
+}

package/src/dev/dev.js

@@ -12,6 +12,7 @@ export { default as audit } from "./crawler/audit.js";
 export { default as crawl } from "./crawler/crawl.js";
 export { default as debug } from "./debug.js";
 export { default as debug2 } from "./debug2/debug2.js";
+export { default as eval } from "./debug2/oriEval.js";
 export { default as explore } from "./explore.js";
 export { default as help } from "./help.js";
 export { default as log } from "./log.js";

package/src/dev/help.yaml

@@ -211,6 +211,9 @@ Tree:
     deepValues:
       args: (tree)
       description: The in-order leaf values of the tree
+    deflatePaths:
+      args: (tree)
+      description: Convert a tree to a mapping of paths to values
     delete:
       args: (map, key)
       description: Delete the value for the key from map
@@ -244,6 +247,9 @@ Tree:
     indent:
       args: "`…`"
       description: Tagged template literal for normalizing indentation
+    inflatePaths:
+      args: (map)
+      description: Convert mapping of paths to values into a tree
     inners:
       args: (tree)
       description: The tree's interior nodes

package/src/server/server.js

@@ -1,4 +1,9 @@
-import { Tree, keysFromPath, trailingSlash } from "@weborigami/async-tree";
+import {
+  TraverseError,
+  Tree,
+  keysFromPath,
+  trailingSlash,
+} from "@weborigami/async-tree";
 import { formatError } from "@weborigami/language";
 import { ServerResponse } from "node:http";
 import constructResponse from "./constructResponse.js";
@@ -138,9 +143,16 @@ ${message}
 </body>
 </html>
 `;
-  response.writeHead(500, { "Content-Type": "text/html" });
+  response.writeHead(500, {
+    "Content-Type": "text/html",
+    "x-error-details": encodeURIComponent(message),
+  });
   response.end(html, "utf-8");
-  console.error(message);
+
+  // Don't log traverse errors for requests like favicon.ico, com.chrome.devtools.json, etc.
+  if (!(error instanceof TraverseError)) {
+    console.error(message);
+  }
 }
 
 // Asynchronous tree router as Express middleware.