@weborigami/origami 0.6.15 → 0.6.17

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

@@ -6,13 +6,13 @@ export { default as indexPage } from "../origami/indexPage.js";
 export { default as yaml } from "../origami/yaml.js";
 export { default as breakpoint } from "./breakpoint.js";
 export { default as changes } from "./changes.js";
+export { default as changes2 } from "./changes2.js";
 export { default as code } from "./code.js";
 export { default as copy } from "./copy.js";
 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

@@ -68,9 +68,15 @@ Origami:
     fetch:
       args: (url, options)
       description: Fetch a resource from a URL with support for extensions
+    hash:
+      args: (data)
+      description: A hex string hash of the data
     htmlEscape:
       args: (text)
       description: Escape HTML entities in the text
+    htmlParse:
+      args: (html)
+      description: Parse HTML into a plain JavaScript object
     image:
       description: Collection of functions for working with images
     indexPage:
@@ -107,6 +113,12 @@ Origami:
       description: POST the given data to the URL
     projectRoot:
       description: The root folder for the current Origami project
+    randomFrom:
+      args: (data)
+      description: Returns a random value based on the data
+    randomsFrom:
+      args: (data)
+      description: Returns a function to produce random values based on the data
     redirect:
       args: (url, options)
       description: Redirect to the given URL
@@ -139,6 +151,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
@@ -187,6 +202,9 @@ Tree:
     clear:
       args: (map)
       description: Remove all values from the map
+    combine:
+      args: (tree1, tree2, combineFn)
+      description: Pairwise application of combineFn to the trees' values
     concat:
       args: (...trees)
       description: Merge trees, renumbering numeric keys

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;
+  },
+};