@weborigami/origami 0.0.73 → 0.1.0

package/src/{builtins/@debug.js → dev/debug.js}

@@ -1,8 +1,8 @@
 import { Tree } from "@weborigami/async-tree";
-import ExplorableSiteTransform from "../common/ExplorableSiteTransform.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 import { isTransformApplied, transformObject } from "../common/utilities.js";
-import OriCommandTransform from "../misc/OriCommandTransform.js";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import ExplorableSiteTransform from "./ExplorableSiteTransform.js";
+import OriCommandTransform from "./OriCommandTransform.js";
 
 /**
  * Add debugging features to the indicated tree.
@@ -16,7 +16,7 @@ import getTreeArgument from "../misc/getTreeArgument.js";
 export default async function debug(treelike) {
   // The debug command leaves the tree's existing scope intact; it does not
   // apply its own scope to the tree.
-  let tree = await getTreeArgument(this, arguments, treelike, "@debug");
+  let tree = await getTreeArgument(this, arguments, treelike, "dev:debug");
 
   if (!isTransformApplied(DebugTransform, tree)) {
     tree = transformObject(DebugTransform, tree);
@@ -69,6 +69,3 @@ function DebugTransform(Base) {
     }
   };
 }
-
-debug.usage = `@debug <tree>\tAdd debug features to a tree`;
-debug.documentation = "https://weborigami.org/language/@debug.html";

package/src/dev/dev.js

@@ -0,0 +1,9 @@
+export { default as breakpoint } from "./breakpoint.js";
+export { default as changes } from "./changes.js";
+export { default as code } from "./code.js";
+export { default as debug } from "./debug.js";
+export { default as explore } from "./explore.js";
+export { default as log } from "./log.js";
+export { default as serve } from "./serve.js";
+export { default as svg } from "./svg.js";
+export { default as watch } from "./watch.js";

package/src/{builtins/@explore.js → dev/explore.js}

@@ -1,29 +1,31 @@
 /** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
 import { Tree, scope } from "@weborigami/async-tree";
 import { OrigamiFiles } from "@weborigami/language";
-import builtins from "../builtins/@builtins.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import { keySymbol } from "../common/utilities.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
-import debug from "./@debug.js";
+import { builtinsTree } from "../internal.js";
+import debug from "./debug.js";
 
-const miscUrl = new URL("../misc", import.meta.url);
-const miscFiles = new OrigamiFiles(miscUrl);
-miscFiles.parent = builtins;
+let templatePromise;
 
 /**
  * @this {AsyncTree|null}
  */
 export default async function explore(...keys) {
-  assertTreeIsDefined(this, "explore");
+  assertTreeIsDefined(this, "origami:explore");
   if (!this) {
     return undefined;
   }
 
+  const tree = Tree.from(this);
+
   /** @type {any} */
   let result;
   if (keys.length > 0) {
     // Traverse the scope using the given keys.
-    const debugTree = await debug.call(this, this);
+    const debugTree = await debug.call(tree, this);
     if (!debugTree) {
       return undefined;
     }
@@ -39,37 +41,23 @@ export default async function explore(...keys) {
     result = await Tree.traverse(debugScope, ...keys);
   } else {
     // Return the Explore page for the current scope.
-    const templateFile = await miscFiles.get("explore.ori");
-    const template = await templateFile.unpack();
-
-    const data = await getScopeData(scope(this));
+    const data = await getScopeData(scope(tree));
+    templatePromise ??= loadTemplate();
+    const template = await templatePromise;
     const text = await template(data);
 
     result = new String(text);
-    const tree = this;
     result.unpack = () => debug.call(tree, tree);
   }
 
   return result;
 }
 
-// To test if a given tree represents the builtins, we walk up the chain to see
-// if any of its prototypes are the builtins tree.
-function isBuiltins(tree) {
-  while (tree) {
-    if (tree === builtins) {
-      return true;
-    }
-    tree = Object.getPrototypeOf(tree);
-  }
-  return false;
-}
-
 async function getScopeData(scope) {
   const trees = scope.trees ?? [scope];
   const data = [];
   for (const tree of trees) {
-    if (isBuiltins(tree)) {
+    if (tree.parent === undefined) {
       // Skip builtins.
       continue;
     }
@@ -82,5 +70,11 @@ async function getScopeData(scope) {
   return data;
 }
 
-explore.usage = "@explore\tExplore the current scope in the browser";
-explore.documentation = "https://weborigami.org/language/@explore.html";
+async function loadTemplate() {
+  const folderPath = path.resolve(fileURLToPath(import.meta.url), "..");
+  const folder = new OrigamiFiles(folderPath);
+  folder.parent = builtinsTree;
+  const templateFile = await folder.get("explore.ori");
+  const template = await templateFile.unpack();
+  return template;
+}

package/src/{misc → dev}/explore.js.inline

@@ -3,9 +3,9 @@ let frame;
 
 const modes = {
   Content: "",
-  Index: "!@index",
-  YAML: "!@yaml",
-  SVG: "!@svg",
+  Index: "!index",
+  YAML: "!yaml",
+  SVG: "!svg",
 };
 
 // Extract the path from the URL hash.
@@ -15,7 +15,7 @@ function getPathFromHash() {
 
 function getModeFromLocation() {
   const href = document.location.href;
-  const match = /[\/](?<command>\!(?:@index|@yaml|@svg))$/.exec(href);
+  const match = /[\/](?<command>\!(?:index|yaml|svg))$/.exec(href);
   const command = match?.groups?.command ?? "";
   const mode =
     Object.keys(modes).find((key) => modes[key] === command) ?? "Content";

package/src/{misc → dev}/explore.ori

@@ -16,12 +16,12 @@
       <button id="buttonSVG">SVG</button>
       <button id="buttonYAML">YAML</button>
     </div>
-    ${ @map(scope, (scopeTree) => `
+    ${ map(scope, (scopeTree) => `
       <ul>
         <h2>${ scopeTree/name }</h2>
-        ${ @map(scopeTree/keys, (key) => `
+        ${ map(scopeTree/keys, (key) => `
         <li>
-          <a href="./!@explore/${ key }" target="frame">${ key }</a>
+          <a href="./!explore/${ key }" target="frame">${ key }</a>
         </li>
         `) }
       </ul>

package/src/{builtins/@log.js → dev/log.js}

@@ -1,4 +1,4 @@
-import yaml from "./@yaml.js";
+import yaml from "../origami/yaml.js";
 
 /**
  * Log the first argument to the console as a side effect and return the second

package/src/{builtins/@serve.js → dev/serve.js}

@@ -2,12 +2,12 @@ import { Tree } from "@weborigami/async-tree";
 import http from "node:http";
 import { createServer } from "node:net";
 import process from "node:process";
-import ExplorableSiteTransform from "../common/ExplorableSiteTransform.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import { isTransformApplied, transformObject } from "../common/utilities.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
 import { requestListener } from "../server/server.js";
-import debug from "./@debug.js";
-import watch from "./@watch.js";
+import debug from "./debug.js";
+import ExplorableSiteTransform from "./ExplorableSiteTransform.js";
+import watch from "./watch.js";
 
 const defaultPort = 5000;
 
@@ -22,7 +22,7 @@ const defaultPort = 5000;
  * @this {AsyncTree|null}
  */
 export default async function serve(treelike, port) {
-  assertTreeIsDefined(this, "serve");
+  assertTreeIsDefined(this, "dev:serve");
   let tree;
   if (treelike) {
     tree = Tree.from(treelike, { parent: this });
@@ -66,6 +66,3 @@ function findOpenPort(port) {
       .listen(port)
   );
 }
-
-serve.usage = `@serve <tree>, [port]\tStart a web server for the tree`;
-serve.documentation = "https://weborigami.org/language/@serve.html";

package/src/{builtins/@svg.js → dev/svg.js}

@@ -1,6 +1,6 @@
 import graphviz from "graphviz-wasm";
-import getTreeArgument from "../misc/getTreeArgument.js";
-import dot from "../misc/treeDot.js";
+import getTreeArgument from "../common/getTreeArgument.js";
+import dot from "./treeDot.js";
 
 let graphvizLoaded = false;
 
@@ -20,7 +20,13 @@ export default async function svg(treelike, options = {}) {
     await graphviz.loadWASM();
     graphvizLoaded = true;
   }
-  const tree = await getTreeArgument(this, arguments, treelike, "@svg", true);
+  const tree = await getTreeArgument(
+    this,
+    arguments,
+    treelike,
+    "dev:svg",
+    true
+  );
   const dotText = await dot.call(this, tree, options);
   if (dotText === undefined) {
     return undefined;
@@ -32,6 +38,3 @@ export default async function svg(treelike, options = {}) {
   result.unpack = () => tree;
   return result;
 }
-
-svg.usage = `@svg <tree>\tRender a tree visually as in SVG format`;
-svg.documentation = "https://weborigami.org/language/@svg.html";

package/src/{misc → dev}/treeDot.js

@@ -191,6 +191,3 @@ function stringDiff(first, second) {
   }
   return second.slice(i);
 }
-
-dot.usage = `dot <tree>\tRender a tree visually in dot language`;
-dot.documentation = "https://weborigami.org/cli/builtins.html#dot";

package/src/{builtins/@watch.js → dev/watch.js}

@@ -1,7 +1,7 @@
 import { Tree } from "@weborigami/async-tree";
 import { formatError } from "@weborigami/language";
 import ConstantTree from "../common/ConstantTree.js";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Let a tree (e.g., of files) respond to changes.
@@ -16,7 +16,12 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  */
 export default async function watch(treelike, fn) {
   /** @type {any} */
-  const container = await getTreeArgument(this, arguments, treelike, "@watch");
+  const container = await getTreeArgument(
+    this,
+    arguments,
+    treelike,
+    "dev:watch"
+  );
 
   // Watch the indicated tree.
   await /** @type {any} */ (container).watch?.();
@@ -48,7 +53,7 @@ async function evaluateTree(parent, fn) {
   let message;
   let result;
   try {
-    result = await fn.call(parent);
+    result = await fn();
   } catch (/** @type {any} */ error) {
     message = formatError(error);
   }
@@ -82,6 +87,3 @@ function updateIndirectPointer(indirect, target) {
 
   Object.setPrototypeOf(indirect, target);
 }
-
-watch.usage = `@watch <folder>, [expr]\tLet a folder tree respond to changes`;
-watch.documentation = "https://weborigami.org/language/@watch.html";

package/src/handlers/handlerExports.js

@@ -0,0 +1,16 @@
+export { default as cssHandler } from "./css.handler.js";
+export { default as htmHandler } from "./htm.handler.js";
+export { default as htmlHandler } from "./html.handler.js";
+export { default as jpegHandler } from "./jpeg.handler.js";
+export { default as jpgHandler } from "./jpg.handler.js";
+export { default as jsHandler } from "./js.handler.js";
+export { default as jsonHandler } from "./json.handler.js";
+export { default as mdHandler } from "./md.handler.js";
+export { default as mjsHandler } from "./mjs.handler.js";
+export { default as oriHandler } from "./ori.handler.js";
+export { default as oridocumentHandler } from "./oridocument.handler.js";
+export { default as txtHandler } from "./txt.handler.js";
+export { default as wasmHandler } from "./wasm.handler.js";
+export { default as xhtmlHandler } from "./xhtml.handler.js";
+export { default as yamlHandler } from "./yaml.handler.js";
+export { default as ymlHandler } from "./yml.handler.js";

package/src/handlers/handlers.js

@@ -0,0 +1,37 @@
+import {
+  jsHandler,
+  oriHandler,
+  oridocumentHandler,
+  wasmHandler,
+  yamlHandler,
+} from "../internal.js";
+import cssHandler from "./css.handler.js";
+import htmHandler from "./htm.handler.js";
+import htmlHandler from "./html.handler.js";
+import jpegHandler from "./jpeg.handler.js";
+import jpgHandler from "./jpg.handler.js";
+import jsonHandler from "./json.handler.js";
+import mdHandler from "./md.handler.js";
+import mjsHandler from "./mjs.handler.js";
+import txtHandler from "./txt.handler.js";
+import xhtmlHandler from "./xhtml.handler.js";
+import ymlHandler from "./yml.handler.js";
+
+export default {
+  "css.handler": cssHandler,
+  "htm.handler": htmHandler,
+  "html.handler": htmlHandler,
+  "jpeg.handler": jpegHandler,
+  "jpg.handler": jpgHandler,
+  "js.handler": jsHandler,
+  "json.handler": jsonHandler,
+  "md.handler": mdHandler,
+  "mjs.handler": mjsHandler,
+  "ori.handler": oriHandler,
+  "oridocument.handler": oridocumentHandler,
+  "txt.handler": txtHandler,
+  "wasm.handler": wasmHandler,
+  "xhtml.handler": xhtmlHandler,
+  "yaml.handler": yamlHandler,
+  "yml.handler": ymlHandler,
+};

package/src/{builtins → handlers}/js.handler.js

@@ -1,4 +1,4 @@
-import processUnpackedContent from "../common/processUnpackedContent.js";
+import { processUnpackedContent } from "../internal.js";
 
 /**
  * A JavaScript file

package/src/{builtins → handlers}/json.handler.js

@@ -1,3 +1,4 @@
+import { symbols } from "@weborigami/async-tree";
 import * as utilities from "../common/utilities.js";
 
 /**
@@ -14,6 +15,13 @@ export default {
     if (!json) {
       throw new Error("Tried to parse something as JSON but it wasn't text.");
     }
-    return JSON.parse(json);
+    const data = JSON.parse(json);
+    if (data && typeof data === "object" && Object.isExtensible(data)) {
+      Object.defineProperty(data, symbols.deep, {
+        enumerable: false,
+        value: true,
+      });
+    }
+    return data;
   },
 };

package/src/handlers/mjs.handler.js

@@ -0,0 +1,2 @@
+// .mjs is a synonynm for .js
+export { jsHandler as default } from "../internal.js";

package/src/{builtins → handlers}/ori.handler.js

@@ -1,8 +1,7 @@
 import { symbols } from "@weborigami/async-tree";
 import { compile } from "@weborigami/language";
-import processUnpackedContent from "../common/processUnpackedContent.js";
 import * as utilities from "../common/utilities.js";
-import builtins from "./@builtins.js";
+import { builtinsTree, processUnpackedContent } from "../internal.js";
 
 /**
  * An Origami expression file
@@ -14,7 +13,6 @@ export default {
 
   /** @type {import("@weborigami/language").UnpackFunction} */
   async unpack(packed, options = {}) {
-    const attachedData = options.attachedData;
     const parent =
       options.parent ??
       /** @type {any} */ (packed).parent ??
@@ -37,12 +35,12 @@ export default {
       url,
     };
 
-    // Compile the source code as an Origami expression and evaluate it.
-    const compiler = options.compiler ?? compile.expression;
+    // Compile the source code as an Origami program and evaluate it.
+    const compiler = options.compiler ?? compile.program;
     const fn = compiler(source);
-    const target = parent ?? builtins;
+    const target = parent ?? builtinsTree;
     let content = await fn.call(target);
 
-    return processUnpackedContent(content, parent, attachedData);
+    return processUnpackedContent(content, parent);
   },
 };

package/src/{builtins → handlers}/oridocument.handler.js

@@ -1,7 +1,7 @@
 import { symbols } from "@weborigami/async-tree";
 import { compile } from "@weborigami/language";
-import processUnpackedContent from "../common/processUnpackedContent.js";
 import * as utilities from "../common/utilities.js";
+import { processUnpackedContent } from "../internal.js";
 
 /**
  * An Origami template document: a plain text file that contains Origami

package/src/{builtins → handlers}/wasm.handler.js

@@ -1,4 +1,4 @@
-import processUnpackedContent from "../common/processUnpackedContent.js";
+import { processUnpackedContent } from "../internal.js";
 
 /**
  * A WebAssembly module

package/src/{builtins → handlers}/yaml.handler.js

@@ -1,7 +1,8 @@
+import { symbols } from "@weborigami/async-tree";
 import * as YAMLModule from "yaml";
-import processUnpackedContent from "../common/processUnpackedContent.js";
 import { parseYaml } from "../common/serialize.js";
 import * as utilities from "../common/utilities.js";
+import { processUnpackedContent } from "../internal.js";
 
 // See notes at serialize.js
 // @ts-ignore
@@ -24,6 +25,12 @@ export default {
       throw new Error("Tried to parse something as YAML but it wasn't text.");
     }
     const data = parseYaml(yaml);
+    if (data && typeof data === "object" && Object.isExtensible(data)) {
+      Object.defineProperty(data, symbols.deep, {
+        enumerable: false,
+        value: true,
+      });
+    }
     return processUnpackedContent(data, parent);
   },
 };

package/src/handlers/yml.handler.js

@@ -0,0 +1,2 @@
+// .yml is a synonym for .yaml
+export { yamlHandler as default } from "../internal.js";

package/src/help/help.js

@@ -0,0 +1,103 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "url";
+import YAML from "yaml";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
+import version from "../origami/version.js";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {string} [key]
+ */
+export default async function help(key) {
+  assertTreeIsDefined(this, "help:");
+
+  const helpFilename = path.resolve(
+    fileURLToPath(import.meta.url),
+    "../help.yaml"
+  );
+  const helpYaml = await fs.readFile(helpFilename);
+  const helpData = YAML.parse(String(helpYaml));
+
+  if (key === undefined) {
+    // Show all namespace descriptions
+    return namespaceDescriptions(helpData);
+  }
+
+  // Try treating key as a namespace.
+  const namespace = helpData[key];
+  if (namespace) {
+    return namespaceCommands(namespace, key);
+  }
+
+  // Try treating key as a builtin command.
+  for (const [namespace, { commands }] of Object.entries(helpData)) {
+    if (commands && Object.hasOwn(commands, key)) {
+      return commandDescription(commands[key], namespace, key);
+    }
+  }
+
+  return `help: "${key}" not found`;
+}
+
+async function commandDescription(commandHelp, namespace, command) {
+  const url = commandHelp.collection
+    ? `${namespace}.html`
+    : `${namespace}/${command}.html`;
+  const text = [
+    "",
+    formatCommandDescription(commandHelp, namespace, command),
+    "",
+    `For more information: https://weborigami.org/builtins/${url}`,
+  ];
+  return text.join("\n");
+}
+
+function formatCommandDescription(commandHelp, namespace, command) {
+  const { args, description } = commandHelp;
+  return `  ${namespace}:${command}${args ?? ""} - ${description}`;
+}
+
+async function namespaceCommands(namespaceHelp, namespace) {
+  const text = [];
+
+  const commands = namespaceHelp.commands;
+  if (commands === undefined) {
+    text.push(`"${namespace}" works like a protocol at the start of a path.`);
+  } else {
+    if (namespaceHelp.description) {
+      const description = namespaceHelp.description;
+      const lowercase = description[0].toLowerCase() + description.slice(1);
+      text.push(
+        `The "${namespace}" namespace contains commands to ${lowercase}.`
+      );
+    }
+    text.push("");
+    for (const [command, commandHelp] of Object.entries(commands)) {
+      text.push(formatCommandDescription(commandHelp, namespace, command));
+    }
+    text.push("");
+  }
+
+  const url = namespaceHelp.collection ? `${namespace}.html` : `${namespace}/`;
+  text.push(`For more information: https://weborigami.org/builtins/${url}`);
+  return text.join("\n");
+}
+
+async function namespaceDescriptions(helpData) {
+  const text = [
+    `Origami ${version} has commands grouped into the following namespaces:\n`,
+  ];
+  for (const [key, value] of Object.entries(helpData)) {
+    const description = value.description;
+    if (description) {
+      text.push(`  ${key}: ${description}`);
+    }
+  }
+  text.push(
+    `\nType "ori help:<namespace>" for more or visit https://weborigami.org/builtins`
+  );
+  return text.join("\n");
+}