@weborigami/origami 0.6.15 → 0.6.16

package/main.js

@@ -1,7 +1,9 @@
 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 { default as debugTransform } from "./src/dev/debug2/debugTransform.js";
 export * as Dev from "./src/dev/dev.js";
+export * from "./src/handlers/origamiHandlers.js";
 export * as Origami from "./src/origami/origami.js";
 export { default as origamiHighlightDefinition } from "./src/origami/origamiHighlightDefinition.js";
 export { default as constructResponse } from "./src/server/constructResponse.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.6.15",
+  "version": "0.6.16",
   "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.15",
+    "@weborigami/async-tree": "0.6.16",
     "@weborigami/json-feed-to-rss": "1.0.1",
-    "@weborigami/language": "0.6.15",
+    "@weborigami/language": "0.6.16",
     "css-tree": "3.1.0",
     "highlight.js": "11.11.1",
     "jsdom": "28.1.0",
@@ -29,6 +29,7 @@
     "marked-highlight": "2.2.3",
     "marked-smartypants": "1.1.11",
     "sharp": "0.34.5",
+    "whatwg-mimetype": "5.0.0",
     "yaml": "2.8.2"
   },
   "scripts": {

package/src/common/findOpenPort.js

@@ -0,0 +1,58 @@
+import net from "node:net";
+
+const DEFAULT_PORT = 5000;
+
+/**
+ * Return the first open port number on or after the given port number.
+ *
+ * @param {number} startPort
+ * @returns {Promise<number>}
+ */
+export 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}`);
+}
+
+/**
+ * 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);
+    });
+  });
+}

package/src/dev/debug2/debug2.js

@@ -1,4 +1,5 @@
-import { execute } from "@weborigami/language";
+import { OrigamiFileMap } from "@weborigami/language";
+import path from "node:path";
 import debugParent from "./debugParent.js";
 
 /**
@@ -9,25 +10,13 @@ import debugParent from "./debugParent.js";
  * 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.)
  *
- * 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
- *
  * @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, options, state) {
-  if (state === undefined) {
-    // Options were omitted; shift arguments
-    state = options;
-    options = [];
-  }
-
+export default async function debug2(code, state) {
   if (
     !(code instanceof Array) ||
     code.source === undefined ||
@@ -47,23 +36,45 @@ export default async function debug2(code, options, state) {
     throw new Error("Dev.debug2 couldn't work out the parent path.");
   }
 
-  // Need to evaluate options object
-  if (options.length > 0) {
-    options = await execute(options, state);
-  } else {
-    options = {};
-  }
-
-  // @ts-ignore
-  const enableUnsafeEval = options.enableUnsafeEval ?? false;
-  const debugFilesPath = options.debugFilesPath ?? "";
-
-  await debugParent({
-    debugFilesPath,
-    enableUnsafeEval,
+  // Start the debug server
+  const server = await debugParent({
     expression,
     parentPath,
   });
+
+  // Watch the parent files for changes
+  const tree = new OrigamiFileMap(parentPath);
+  tree.watch();
+  tree.addEventListener?.("change", async (event) => {
+    // @ts-ignore
+    const { filePath } = event.options;
+    if (isJavaScriptFile(filePath)) {
+      // Need to restart the child process
+      console.log("JavaScript file changed, restarting server…");
+      await server.restart();
+    } else if (path.basename(filePath) === "package.json") {
+      // Need to restart the child process
+      console.log("package.json changed, restarting server…");
+      await server.restart();
+    } else {
+      // Just have the child reevaluate the expression
+      console.log("File changed, reloading site…");
+      await server.reevaluate();
+    }
+  });
+
+  // When server closes, stop watching for file changes
+  server.on("close", () => {
+    tree.unwatch();
+  });
+
+  console.log(`Server running at ${server.origin}. Press Ctrl+C to stop.`);
 }
 debug2.needsState = true;
 debug2.unevaluatedArgs = true;
+
+function isJavaScriptFile(filePath) {
+  const extname = path.extname(filePath).toLowerCase();
+  const jsExtensions = [".cjs", ".js", ".mjs", ".ts"];
+  return jsExtensions.includes(extname);
+}

package/src/dev/debug2/debugChild.js

@@ -22,13 +22,6 @@ 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;
@@ -43,6 +36,8 @@ if (parentPath === undefined) {
   fail("Missing Origami parent");
 }
 
+const quiet = process.env.ORIGAMI_QUIET === "1";
+
 // An indirect pointer to the tree of resources;
 let treeHandle = {};
 
@@ -50,7 +45,7 @@ let treeHandle = {};
 await evaluateExpression();
 
 // Serve the tree of resources
-const listener = requestListener(treeHandle);
+const listener = requestListener(treeHandle, { quiet });
 const server = http.createServer(listener);
 
 // Track live connections so we can drain/close cleanly.
@@ -96,10 +91,8 @@ function beginDrain() {
 
 async function evaluateExpression() {
   const tree = await expressionTree({
-    debugFilesPath,
     expression,
     parentPath,
-    enableUnsafeEval,
   });
   if (!tree) {
     fail("Dev.debug2: expression did not evaluate to a maplike resource tree");
@@ -118,6 +111,8 @@ async function evaluateExpression() {
   } catch {
     // Ignore errors.
   }
+
+  process.send?.({ type: "EVALUATED" });
 }
 
 function maybeFinishDrain() {

package/src/dev/debug2/debugCommands.js

@@ -1,29 +1,11 @@
 // Subset of commands made available via debugTransform
 
 import { Tree } from "@weborigami/async-tree";
+export const keys = Tree.keys;
+export const json = Tree.json;
 
-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,
-        }
-      : {},
-  );
-}
+export { default as index } from "../../origami/indexPage.js";
+export { default as yaml } from "../../origami/yaml.js";
+export { default as explore } from "../explore.js";
+export { default as svg } from "../svg.js";
+export { default as version } from "../version.js";

package/src/dev/debug2/debugParent.js

@@ -1,12 +1,9 @@
-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";
+import { findOpenPort } from "../../common/findOpenPort.js";
 
 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);
@@ -15,9 +12,6 @@ const childModuleUrl = new URL("./debugChild.js", import.meta.url);
 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 */
@@ -44,9 +38,6 @@ let emitter = null;
  * 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
@@ -55,47 +46,32 @@ let emitter = null;
  * 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
+ * @param {number} [options.port]
+ * @param {boolean} [options.quiet]
  */
 export default async function debugParent(options) {
   const { parentPath } = options;
+  if (parentPath === undefined) {
+    throw new Error("Debugger couldn't work out the parent path.");
+  }
 
-  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();
+  const port = options.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.`);
-  });
+  await new Promise((resolve) =>
+    publicServer.listen(port, PUBLIC_HOST, resolve),
+  );
+  await startChild(options);
 
   emitter = Object.assign(new EventEmitter(), {
     close,
+    origin: publicOrigin,
+    reevaluate,
+    restart: () => startChild(options),
   });
-
   return emitter;
 }
 
@@ -110,7 +86,6 @@ async function close() {
   publicServer.closeAllConnections();
   await closed;
   publicServer = null;
-  emitter = null;
 
   // Drain and stop any children concurrently
   const children = [pendingChild?.process, activeChild?.process].filter(
@@ -121,9 +96,9 @@ async function close() {
   activeChild = null;
   await Promise.all(children.map(drainAndStopChild));
 
-  // Stop watching for file changes
-  tree.unwatch();
-  tree = null;
+  emitter.emit("close");
+  emitter.removeAllListeners();
+  emitter = null;
 }
 
 /**
@@ -182,66 +157,6 @@ async function drainAndStopChild(childProcess) {
   }, 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.
@@ -322,6 +237,30 @@ function proxyRequest(request, response) {
   request.pipe(upstreamRequest);
 }
 
+async function reevaluate() {
+  if (!activeChild) {
+    return;
+  }
+
+  const child = activeChild;
+
+  // Wait for the next EVALUATED message from the child
+  const evaluated = /** @type {Promise<void>} */ (
+    new Promise((resolve) => {
+      const onMessage = (/** @type {any} */ msg) => {
+        if (msg && typeof msg === "object" && msg.type === "EVALUATED") {
+          child.process.off("message", onMessage);
+          resolve();
+        }
+      };
+      child.process.on("message", onMessage);
+    })
+  );
+
+  child.process.send({ type: "REEVALUATE" });
+  await evaluated;
+}
+
 /**
  * Start a new child process.
  *
@@ -329,7 +268,8 @@ function proxyRequest(request, response) {
  * it becomes active and any previous active child is drained and stopped.
  */
 function startChild(options) {
-  const { debugFilesPath, enableUnsafeEval, expression, parentPath } = options;
+  const { expression, parentPath } = options;
+  const quiet = options.quiet ?? false;
 
   // Start the child process, passing parent path via an environment variable.
   /** @type {ChildProcess} */
@@ -339,10 +279,9 @@ function startChild(options) {
       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,
+        ORIGAMI_QUIET: quiet ? "1" : "0",
       },
     });
   } catch (error) {
@@ -354,61 +293,77 @@ function startChild(options) {
   // 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),
-          );
+  // Returns a Promise that resolves when the child signals READY, or rejects
+  // on FATAL or unexpected exit before ready.
+  return /** @type {Promise<void>} */ (
+    new Promise((resolve, reject) => {
+      // Listen for messages from the child about its status
+      childProcess.on("message", (/** @type {any} */ message) => {
+        if (!message || typeof message !== "object") {
+          return;
+        } else 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) {
+              emitter.emit("ready", { origin: publicOrigin });
+            }
+            resolve();
+          } else {
+            // This child was superseded by a newer one, kill it
+            // console.log("Child process superseded by newer one, killing it...");
+            childProcess.kill("SIGTERM");
+          }
+        } else if (message.type === "EVALUATED") {
+          // Let caller know child has reevaluated the expression (after a file change)
+          if (emitter) {
+            emitter.emit("evaluated");
+          }
+        } else 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;
+          }
+          reject(new Error(message.error ?? "Child server failed to start"));
         }
+      });
 
-        if (!emitter) {
-          console.warn(
-            "Dev.debug2: child server is ready but parent emitter is gone, cannot emit ready event",
+      childProcess.on("exit", (code, signal) => {
+        if (activeChild?.process === childProcess) {
+          // Active child died unexpectedly.
+          activeChild = null;
+        }
+        if (pendingChild?.process === childProcess) {
+          pendingChild = null;
+          // Child died before it was ready. If child was ready and resolve()
+          // was called, when the child exits, then reject() is a no-op.
+          reject(
+            new Error(
+              `Child exited before ready (code=${code}, signal=${signal})`,
+            ),
           );
-          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,10 +9,9 @@ import {
   scope,
   trailingSlash,
 } from "@weborigami/async-tree";
-import { OrigamiFileMap } from "@weborigami/language";
 import indexPage from "../../origami/indexPage.js";
 import yaml from "../../origami/yaml.js";
-import debugCommands from "./debugCommands.js";
+import * as debugCommands from "./debugCommands.js";
 
 /**
  * Transform the given map-based tree to add debugging resources:
@@ -23,19 +22,29 @@ import debugCommands from "./debugCommands.js";
  *
  * Also transform a simple object result to YAML for viewing.
  *
- * @param {import("@weborigami/async-tree").Maplike} maplike
- * @param {string} debugFilesPath
- * @param {boolean} enableUnsafeEval
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
+ * @typedef {import("@weborigami/async-tree").Packed} Packed
+ *
+ * @param {Maplike|Packed} input
  */
-export default function debugTransform(
-  maplike,
-  debugFilesPath = "",
-  enableUnsafeEval = false,
-) {
-  const source = Tree.from(maplike, { deep: true });
-  const commands = debugCommands(enableUnsafeEval);
+export default function debugTransform(input) {
+  if (isUnpackable(input)) {
+    // If the value isn't a tree, but has a tree attached via an `unpack`
+    // method, destructively wrap the unpack method to add this transform.
+    const original = input.unpack.bind(input);
+    input.unpack = async () => {
+      const content = await original();
+      if (!Tree.isTraversable(content) || typeof content === "function") {
+        return content;
+      }
+      /** @type {any} */
+      let tree = Tree.from(content);
+      return debugTransform(tree);
+    };
+    return input;
+  }
 
-  const debugFiles = debugFilesPath ? new OrigamiFileMap(debugFilesPath) : null;
+  const source = Tree.from(input, { deep: true });
 
   return Object.assign(new AsyncMap(), {
     description: "debug resources",
@@ -44,22 +53,15 @@ export default function debugTransform(
       // 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) {
         // Try the defaults and commands
-        if (key === "_debugger/") {
-          return debugFiles;
-        } else if (key === "index.html") {
+        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(commands, source, key);
+          value = await invokeOrigamiCommand(source, key);
         }
       }
 
@@ -72,29 +74,21 @@ export default function debugTransform(
           Tree.merge(object, {
             "index.html": yamlText,
           });
-      } else if (Tree.isMaplike(value) && !Tree.isMap(value)) {
+      } else if (
+        Tree.isMaplike(value) &&
+        !Tree.isMap(value) &&
+        typeof value !== "function"
+      ) {
         // Make it a map so we can debug it
         value = Tree.from(value);
       }
 
-      if (Tree.isMap(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.
-        const original = value.unpack.bind(value);
-        value.unpack = async () => {
-          const content = await original();
-          if (!Tree.isTraversable(content) || typeof content === "function") {
-            return content;
-          }
-          /** @type {any} */
-          let tree = Tree.from(content);
-          return debugTransform(tree);
-        };
+      // Ensure this transform is applied to any map result, or any object with
+      // an unpack method that returns a map.
+      if (Tree.isMap(value) || value?.unpack) {
+        value = debugTransform(value);
       }
+
       return value;
     },
 
@@ -114,15 +108,15 @@ export default function debugTransform(
   });
 }
 
-async function invokeOrigamiCommand(commands, tree, key) {
+async function invokeOrigamiCommand(tree, key) {
   // Key is an Origami command; invoke it.
   const commandName = trailingSlash.remove(key.slice(1).trim());
 
   // Look for the indicated command
-  const command = commands[commandName];
+  const command = debugCommands[commandName];
   let value;
   if (command) {
-    value = await command(tree);
+    value = command instanceof Function ? await command(tree) : command;
   } else {
     // Look for command in scope
     const parentScope = await scope(tree);

package/src/dev/debug2/expressionTree.js

@@ -15,13 +15,11 @@ let version = 0;
  * resource tree, then transform that tree with debug resources and return it.
  *
  * @param {Object} options
- * @param {string} options.debugFilesPath
- * @param {boolean} options.enableUnsafeEval
  * @param {string} options.expression
  * @param {string} options.parentPath
  */
 export default async function expressionTree(options) {
-  const { debugFilesPath, expression, parentPath, enableUnsafeEval } = options;
+  const { expression, parentPath } = options;
 
   const parent = new OrigamiFileMap(parentPath);
   const globals = await projectGlobals(parent);
@@ -47,7 +45,7 @@ export default async function expressionTree(options) {
   setParent(maplike, parent);
 
   // Add debugging resources
-  const tree = debugTransform(maplike, debugFilesPath, enableUnsafeEval);
+  const tree = debugTransform(maplike);
 
   /** @type {any} */ (tree).version = version++;
 

package/src/dev/debug2/oriEval.js

@@ -1,17 +1,49 @@
-import ori from "../../origami/ori.js";
+import { trailingSlash, Tree } from "@weborigami/async-tree";
+import { evaluate, projectGlobals } from "@weborigami/language";
+import debugTransform from "./debugTransform.js";
 
-let lastExpression;
-let lastResult;
+const mapParentToResult = new WeakMap();
 
+/**
+ * Return a route that evaluates a key containing an expression.
+ *
+ * Because this route may be used multiple times to return the resources for a
+ * page, we cache the result for each parent and key.
+ *
+ * To allow multiple evaluations of the same expression, we expect the key to be
+ * of the form `<counter>,<expression>`, where the counter is a number that will
+ * be used for caching but ignored for evaluation. The debugger increments the
+ * counter to force reevaluation of the same expression.
+ */
 export default async function oriEval(parent) {
-  return async (encodedExpression) => {
-    console.log(encodedExpression);
-    const expression = decodeURIComponent(encodedExpression);
-    if (expression === lastExpression) {
-      return lastResult;
+  const globals = await projectGlobals(parent);
+  return async (key) => {
+    const normalizedKey = trailingSlash.remove(key);
+    let result = mapParentToResult.get(parent);
+    if (result?.key === normalizedKey) {
+      return result.value;
     }
-    lastExpression = expression;
-    lastResult = await ori(expression, { parent });
-    return lastResult;
+
+    const regex = /^\d+,(?<expression>.*)$/;
+    const match = normalizedKey.match(regex);
+    let value;
+    if (match) {
+      const expression = decodeURIComponent(match.groups.expression);
+      value = await evaluate(expression, {
+        globals,
+        mode: "shell",
+        parent,
+      });
+      if (
+        (Tree.isMaplike(value) && typeof value !== "function") ||
+        value?.unpack
+      ) {
+        value = debugTransform(value);
+      }
+    }
+
+    mapParentToResult.set(parent, { key: normalizedKey, value });
+
+    return value;
   };
 }

package/src/dev/dev.js

@@ -12,7 +12,6 @@ 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

@@ -79,6 +79,9 @@ Origami:
     inline:
       args: (text)
       description: Inline Origami expressions found in the text
+    htmlParse:
+      args: (html)
+      description: Parse HTML into a plain JavaScript object
     json:
       args: (obj)
       description: Render the object in JSON format
@@ -139,6 +142,9 @@ Origami:
     unpack:
       args: (buffer)
       description: Unpack the buffer into a usable form
+    xmlParse:
+      args: (xml)
+      description: Parse XML into a plain JavaScript object
     yaml:
       args: (obj)
       description: Render the object in YAML format

package/src/handlers/origamiHandlers.js

@@ -0,0 +1 @@
+export { default as xml_handler } from "./xml_handler.js";

package/src/handlers/xml_handler.js

@@ -0,0 +1,23 @@
+import { symbols, toString } from "@weborigami/async-tree";
+import xmlParse from "../origami/xmlParse.js";
+
+export default {
+  mediaType: "application/xml",
+
+  async unpack(packed, options = {}) {
+    const parent = options.parent ?? null;
+    const text = toString(packed);
+    if (text === null) {
+      throw new TypeError("XML handler can only unpack text.");
+    }
+    const data = await xmlParse(text);
+    // Define `parent` as non-enumerable property
+    Object.defineProperty(data, symbols.parent, {
+      configurable: true,
+      enumerable: false,
+      value: parent,
+      writable: true,
+    });
+    return data;
+  },
+};

package/src/origami/domNodeToObject.js

@@ -0,0 +1,93 @@
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const CDATA_SECTION_NODE = 4;
+const DOCUMENT_NODE = 9;
+const DOCUMENT_FRAGMENT_NODE = 11;
+
+export default function domNodeToObject(node) {
+  switch (node.nodeType) {
+    case DOCUMENT_NODE:
+      return {
+        name: "#document",
+        children: [...node.childNodes]
+          .filter((child) => !isWhitespaceOnly(child))
+          .map(domNodeToObject),
+      };
+
+    case DOCUMENT_FRAGMENT_NODE:
+      return {
+        name: "#document-fragment",
+        children: [...node.childNodes]
+          .filter((child) => !isWhitespaceOnly(child))
+          .map(domNodeToObject),
+      };
+
+    case ELEMENT_NODE: {
+      const attributes = Object.fromEntries(
+        [...node.attributes].map((attr) => [attr.name, attr.value]),
+      );
+
+      const relevantChildren = [...node.childNodes].filter(
+        (child) =>
+          (child.nodeType === ELEMENT_NODE ||
+            child.nodeType === TEXT_NODE ||
+            child.nodeType === CDATA_SECTION_NODE) &&
+          !isWhitespaceOnly(child),
+      );
+
+      const onlyText = relevantChildren.every(
+        (child) =>
+          child.nodeType === TEXT_NODE || child.nodeType === CDATA_SECTION_NODE,
+      );
+
+      const result = {
+        name: node.localName,
+      };
+      if (Object.keys(attributes).length > 0) {
+        result.attributes = attributes;
+      }
+      if (onlyText) {
+        const text = relevantChildren
+          .map((child) => collapseWhitespace(child.nodeValue ?? ""))
+          .join("")
+          .trim();
+        if (text.length > 0) {
+          result.text = text;
+        }
+      } else if (relevantChildren.length > 0) {
+        result.children = relevantChildren.map(domNodeToObject);
+      }
+
+      return result;
+    }
+
+    case TEXT_NODE:
+      return {
+        name: "#text",
+        text: collapseWhitespace(node.nodeValue ?? ""),
+      };
+
+    case CDATA_SECTION_NODE:
+      return {
+        name: "#cdata-section",
+        text: collapseWhitespace(node.nodeValue ?? ""),
+      };
+
+    default:
+      return {
+        name: `#node-${node.nodeType}`,
+      };
+  }
+}
+
+// Collapse leading or trailing whitespace characters to a single space
+function collapseWhitespace(str) {
+  return str.replace(/^\s+/, " ").replace(/\s+$/, " ");
+}
+
+function isWhitespaceOnly(node) {
+  return (
+    (node.nodeType === TEXT_NODE || node.nodeType === CDATA_SECTION_NODE) &&
+    node.nodeValue.trim() === ""
+  );
+}

package/src/origami/htmlParse.js

@@ -0,0 +1,22 @@
+import { args } from "@weborigami/async-tree";
+import loadJsDom from "../common/loadJsDom.js";
+import domNodeToObject from "./domNodeToObject.js";
+
+/**
+ * Return the DOM structure for the given HTML as a plain object.
+ *
+ * @param {import("@weborigami/async-tree").Stringlike} html
+ */
+export default async function htmlParse(html) {
+  html = args.stringlike(html, "Origami.htmlParse");
+  const { JSDOM } = await loadJsDom();
+  const dom = JSDOM.fragment(html);
+  let object = domNodeToObject(dom);
+  if (
+    (object.name === "#document" || object.name === "#document-fragment") &&
+    object.children.length === 1
+  ) {
+    object = object.children[0];
+  }
+  return object;
+}

package/src/origami/mdOutline.js

@@ -22,18 +22,29 @@ export default async function mdOutline(input) {
   const outline = {};
   const stack = [];
   let sectionText = "";
+  let sectionTextTrimmed = null;
   /** @type {any} */
   let current = outline;
   for (const token of tokens) {
     if (token.type === "heading") {
       // Current section text gets added as content for the current node.
-      if (sectionText) {
-        current._text = sectionText.trim();
+      sectionTextTrimmed = sectionText.trim();
+      if (sectionTextTrimmed) {
+        current._text = sectionTextTrimmed;
         sectionText = "";
       }
 
-      // Pop the stack to find the right level for this heading
       const { depth, text: headingText } = token;
+
+      // Did we skip a heading level? If so, create `_skip<n>` nodes
+      while (stack.length < depth - 1) {
+        const skipNode = {};
+        current[`_skip${stack.length + 1}`] = skipNode;
+        stack.push(current);
+        current = skipNode;
+      }
+
+      // Pop the stack to find the right level for this heading
       while (stack.length >= depth) {
         current = stack.pop();
         consolidateText(current);
@@ -51,8 +62,9 @@ export default async function mdOutline(input) {
   }
 
   // Any remaining section text gets added as content for the current node.
-  if (sectionText) {
-    current._text = sectionText.trim();
+  sectionTextTrimmed = sectionText.trim();
+  if (sectionTextTrimmed) {
+    current._text = sectionTextTrimmed;
     current = stack.pop();
     if (current) {
       consolidateText(current);

package/src/origami/origami.js

@@ -4,8 +4,8 @@ export { default as basename } from "./basename.js";
 export { default as csv } from "./csv.js";
 export { default as document } from "./document.js";
 export { default as fetch } from "./fetch.js";
-export { default as htmlDom } from "./htmlDom.js";
 export { default as htmlEscape } from "./htmlEscape.js";
+export { default as htmlParse } from "./htmlParse.js";
 export { default as format } from "./image/format.js";
 export * as image from "./image/image.js";
 export { default as resize } from "./image/resize.js";
@@ -34,5 +34,6 @@ export { default as static } from "./static.js";
 export { default as string } from "./string.js";
 export { default as tsv } from "./tsv.js";
 export { default as unpack } from "./unpack.js";
+export { default as xmlParse } from "./xmlParse.js";
 export { default as yaml } from "./yaml.js";
 export { default as yamlParse } from "./yamlParse.js";

package/src/origami/xmlParse.js

@@ -0,0 +1,33 @@
+import { args } from "@weborigami/async-tree";
+import loadJsDom from "../common/loadJsDom.js";
+import domNodeToObject from "./domNodeToObject.js";
+
+let parser;
+
+/**
+ * Return the DOM for the given XML as a plain object.
+ *
+ * @param {import("@weborigami/async-tree").Stringlike} xml
+ */
+export default async function xmlParse(xml) {
+  xml = args.stringlike(xml, "Origami.xmlParse");
+  const parser = await getParser();
+  const dom = parser.parseFromString(xml, "application/xml");
+  let object = domNodeToObject(dom);
+  if (
+    (object.name === "#document" || object.name === "#document-fragment") &&
+    object.children.length === 1
+  ) {
+    object = object.children[0];
+  }
+  return object;
+}
+
+async function getParser() {
+  if (!parser) {
+    const { JSDOM } = await loadJsDom();
+    const dom = new JSDOM();
+    parser = new dom.window.DOMParser();
+  }
+  return parser;
+}

package/src/server/server.js

@@ -88,7 +88,14 @@ export async function handleRequest(request, response, map) {
 
 export function keysFromUrl(url) {
   const encodedKeys = keysFromPath(url.pathname);
-  const keys = encodedKeys.map((key) => decodeURIComponent(key));
+  // Decode the keys, but stop decoding if we encounter an Origami debugger command
+  let foundCommand = false;
+  const keys = encodedKeys.map((key) => {
+    if (key.startsWith("!")) {
+      foundCommand = true;
+    }
+    return foundCommand ? key : decodeURIComponent(key);
+  });
 
   // If the keys array is empty (the path was just a trailing slash) or if the
   // path ended with a slash, add "index.html" to the end of the keys.
@@ -104,12 +111,17 @@ export function keysFromUrl(url) {
  * https.createServer calls, letting you serve an async tree as a set of pages.
  *
  * @typedef {import("@weborigami/async-tree").Maplike} Maplike
+ * @param {object} options
+ * @param {boolean} [options.quiet] If true, suppresses logging of incoming requests.
  * @param {Maplike} maplike
  */
-export function requestListener(maplike) {
+export function requestListener(maplike, options = {}) {
+  const quiet = options.quiet ?? false;
   const tree = Tree.from(maplike);
   return async function (request, response) {
-    console.log(decodeURI(request.url));
+    if (!quiet) {
+      console.log(decodeURI(request.url));
+    }
     const handled = await handleRequest(request, response, tree);
     if (!handled) {
       // Not found, return a 404.

package/src/origami/htmlDom.js

@@ -1,14 +0,0 @@
-import { args } from "@weborigami/async-tree";
-import loadJsDom from "../common/loadJsDom.js";
-
-/**
- * Return the DOM for the given HTML string.
- *
- * @param {import("@weborigami/async-tree").Stringlike} html
- */
-export default async function htmlDom(html) {
-  html = args.stringlike(html, "Origami.htmlDom");
-  const { JSDOM } = await loadJsDom();
-  const dom = JSDOM.fragment(html);
-  return dom;
-}