@weborigami/origami 0.0.35

package/src/builtins/@tree/sortBy.js

@@ -0,0 +1,40 @@
+import { Tree, sortBy } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import addValueKeyToScope from "../../common/addValueKeyToScope.js";
+import { toFunction } from "../../common/utilities.js";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a new tree with the original's keys sorted using the given function to
+ * obtain a sort key for each value in the tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param {Invocable} sortKeyFn
+ */
+export default async function sortByBuiltin(treelike, sortKeyFn) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  const tree = Tree.from(treelike);
+
+  const fn = toFunction(sortKeyFn);
+  const baseScope = Scope.getScope(this);
+  async function extendedSortKeyFn(key, tree) {
+    const value = await tree.get(key);
+    const scope = addValueKeyToScope(baseScope, value, key);
+    const sortKey = await fn.call(scope, value, key);
+    return sortKey;
+  }
+
+  const sorted = sortBy(extendedSortKeyFn)(tree);
+  const scoped = Scope.treeWithScope(sorted, this);
+  return scoped;
+}
+
+sortByBuiltin.usage = `sortBy <tree>, [sortKeyFn]\tReturn a new tree with the original's keys sorted`;
+sortByBuiltin.documentation =
+  "https://graphorigami.org/cli/builtins.html#@sort";

package/src/builtins/@tree/static.js

@@ -0,0 +1,51 @@
+import { Tree, keysJson } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import { transformObject } from "../../common/utilities.js";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+import index from "../@index.js";
+
+/**
+ * Expose common static keys (index.html, .keys.json) for a tree.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ */
+export default async function staticTree(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  let result = transformObject(StaticTransform, tree);
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+
+function StaticTransform(Base) {
+  return class Static extends Base {
+    async get(key) {
+      let value = await super.get(key);
+      if (value === undefined && key === "index.html") {
+        value = index.call(this, this);
+      } else if (value === undefined && key === ".keys.json") {
+        value = keysJson.stringify(this);
+      } else if (Tree.isAsyncTree(value)) {
+        value = transformObject(StaticTransform, value);
+      }
+      return value;
+    }
+
+    async keys() {
+      const keys = new Set(await super.keys());
+      keys.add("index.html");
+      keys.add(".keys.json");
+      return keys;
+    }
+  };
+}
+
+staticTree.usage = `static <tree>\tAdd keys for generating common static files`;
+staticTree.documentation = "https://graphorigami.org/cli/builtins.html#static";

package/src/builtins/@tree/table.js

@@ -0,0 +1,74 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ */
+export default async function table(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  const firstValue = await valueForFirstKey(tree);
+  if (Tree.isAsyncTree(firstValue)) {
+    return fullTable(tree, firstValue);
+  } else {
+    return simpleTable(tree);
+  }
+}
+
+// Tree's values are subtrees.
+//
+// Return an R x C table, where R is the number of top-level keys in the tree
+// (plus a header row), and C is the number of 2nd-level keys (plus a labeling
+// column).
+//
+// The 2nd-level keys are obtain by inspecting the given model object, which is
+// taken to represent top-level objects in the tree.
+async function fullTable(tree, model) {
+  // Construct the header.
+  const modelKeys = Array.from(await model.keys());
+  const header = " \t" + modelKeys.join("\t");
+  const rows = [header];
+
+  // Add a row for each top-level object.
+  for (const key of await tree.keys()) {
+    let row = key;
+    const value = await tree.get(key);
+    for (const modelKey of await model.keys()) {
+      const value2 = await value.get(modelKey);
+      row += `\t${value2}`;
+    }
+    rows.push(row);
+  }
+
+  return rows.join("\n");
+}
+
+// Tree's values are not subtrees.
+// Return the (key, value) pairs as a simple two-column table.
+async function simpleTable(tree) {
+  const header = `Key\tValue`;
+  const rows = [header];
+  for (const key of await tree.keys()) {
+    const value = await tree.get(key);
+    rows.push(`${key}\t${value}`);
+  }
+  const text = rows.join("\n");
+  return text;
+}
+
+// Return the value for the tree's first key.
+async function valueForFirstKey(tree) {
+  const [value] = await tree.keys();
+  return value;
+}
+
+table.usage =
+  "table <tree>\tFormat the tree's top level as a tab-delimited table";
+table.documentation = "https://graphorigami.org/cli/builtins.html#table";

package/src/builtins/@tree/take.js

@@ -0,0 +1,40 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Given a tree, take the first n items from it.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param {number} n
+ */
+export default async function take(treelike, n) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+
+  /** @type {AsyncTree} */
+  let takeTree = {
+    async keys() {
+      const keys = Array.from(await tree.keys());
+      return keys.slice(0, n);
+    },
+
+    async get(key) {
+      return tree.get(key);
+    },
+  };
+
+  takeTree = Scope.treeWithScope(takeTree, this);
+
+  return takeTree;
+}
+
+take.usage = `take tree, n\tReturn the first n items from tree`;
+take.documentation = "https://graphorigami.org/cli/builtins.html#take";

package/src/builtins/@tree/values.js

@@ -0,0 +1,23 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return the interior nodes of the tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function values(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  return Tree.values(tree);
+}
+
+values.usage = `values <tree>\tThe top-level values in the tree`;
+values.documentation = "https://graphorigami.org/cli/builtins.html#values";

package/src/builtins/@tree/valuesDeep.js

@@ -0,0 +1,23 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return the in-order exterior values of a tree as a flat array.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function valuesDeep(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  return Tree.mapReduce(treelike, null, async (values) => values.flat());
+}
+
+valuesDeep.usage = `valuesDeep <tree>\tThe in-order tree values as a flat array`;
+valuesDeep.documentation =
+  "https://graphorigami.org/cli/builtins.html#valuesDeep";

package/src/builtins/@treeHttp.js

@@ -0,0 +1,19 @@
+import { ops } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {string} host
+ * @param  {...string|Symbol} keys
+ */
+export default function treeHttp(host, ...keys) {
+  assertScopeIsDefined(this);
+  return ops.treeHttp.call(this, host, ...keys);
+}
+
+treeHttp.usage = `@treeHttp <domain>, <...keys>\tA web site tree via HTTP`;
+treeHttp.documentation = "https://graphorigami.org/language/@treeHttp.html";

package/src/builtins/@treeHttps.js

@@ -0,0 +1,19 @@
+import { ops } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {string} host
+ * @param  {...string|Symbol} keys
+ */
+export default function treeHttps(host, ...keys) {
+  assertScopeIsDefined(this);
+  return ops.treeHttps.call(this, host, ...keys);
+}
+
+treeHttps.usage = `@treeHttps <domain>, <...keys>\tA web site tree via HTTPS`;
+treeHttps.documentation = "https://graphorigami.org/language/@treeHttps.html";

package/src/builtins/@true.js

@@ -0,0 +1 @@
+export default true;

package/src/builtins/@unpack.js

@@ -0,0 +1,13 @@
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {any} obj
+ * @returns
+ */
+export default function unpack(obj) {
+  assertScopeIsDefined(this);
+  return obj?.unpack?.();
+}

package/src/builtins/@watch.js

@@ -0,0 +1,108 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import ConstantTree from "../common/ConstantTree.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Let a tree (e.g., of files) respond to changes.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ * @param {Invocable} [fn]
+ */
+export default async function watch(treelike, fn) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+
+  // Watch the indicated tree.
+  /** @type {any} */
+  const container = Tree.from(treelike);
+  await /** @type {any} */ (container).watch?.();
+
+  // // Watch trees in scope.
+  // const scope = /** @type {any} */ (container).scope;
+  // await scope?.watch?.();
+
+  if (fn === undefined) {
+    return container;
+  }
+
+  // The caller supplied a function to reevaluate whenever the tree changes.
+  let tree = await evaluateTree(container.scope, fn);
+
+  // We want to return a stable reference to the tree, so we'll use a prototype
+  // chain that will always point to the latest tree. We'll extend the tree's
+  // prototype chain with an empty object, and use that as a handle (pointer to
+  // a pointer) to the tree. This is what we'll return to the caller.
+  const handle = Object.create(tree);
+
+  // Reevaluate the function whenever the tree changes.
+  container.addEventListener?.("change", async () => {
+    const tree = await evaluateTree(container.scope, fn);
+    updateIndirectPointer(handle, tree);
+  });
+
+  return handle;
+}
+
+async function evaluateTree(scope, fn) {
+  let tree;
+  let message;
+  let result;
+  try {
+    result = await fn.call(scope);
+  } catch (error) {
+    message = messageForError(error);
+  }
+  tree = result ? Tree.from(result) : undefined;
+  if (tree) {
+    return tree;
+  }
+  if (!message) {
+    message = `warning: watch expression did not return a tree`;
+  }
+  console.warn(message);
+  tree = new ConstantTree(message);
+  if (scope) {
+    tree = Scope.treeWithScope(tree, scope);
+  }
+  return tree;
+}
+
+function messageForError(error) {
+  let message = "";
+  // Work up to the root cause, displaying intermediate messages as we go up.
+  while (error.cause) {
+    message += error.message + `\n`;
+    error = error.cause;
+  }
+  if (error.name) {
+    message += `${error.name}: `;
+  }
+  message += error.message;
+  return message;
+}
+
+// Update an indirect pointer to a target.
+function updateIndirectPointer(indirect, target) {
+  // Clean the pointer of any named properties or symbols that have been set
+  // directly on it.
+  for (const key of Object.getOwnPropertyNames(indirect)) {
+    delete indirect[key];
+  }
+  for (const key of Object.getOwnPropertySymbols(indirect)) {
+    delete indirect[key];
+  }
+
+  Object.setPrototypeOf(indirect, target);
+}
+
+watch.usage = `@watch <folder>, [expr]\tLet a folder tree respond to changes`;
+watch.documentation = "https://graphorigami.org/language/@watch.html";

package/src/builtins/@with.js

@@ -0,0 +1,22 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import { toFunction } from "../common/utilities.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param  {Invocable} invocable
+ */
+export default function withTree(treelike, invocable) {
+  assertScopeIsDefined(this);
+  const tree = Tree.from(treelike);
+  const fn = toFunction(invocable);
+  const scope = new Scope(tree, this);
+  return fn.call(scope);
+}

package/src/builtins/@yaml.js

@@ -0,0 +1,23 @@
+/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+import YAML from "yaml";
+import * as serialize from "../common/serialize.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Render the object as text in YAML format.
+ *
+ * @this {AsyncTree|null}
+ * @param {any} [obj]
+ */
+export default async function toYaml(obj) {
+  assertScopeIsDefined(this);
+  obj = obj ?? (await this?.get("@current"));
+  if (obj === undefined) {
+    return undefined;
+  }
+  const value = await serialize.toJsonValue(obj);
+  return YAML.stringify(value);
+}
+
+toYaml.usage = `@yaml <obj>\tRender the object as text in YAML format`;
+toYaml.documentation = "https://graphorigami.org/language/@yaml.html";

package/src/builtins/~.js

@@ -0,0 +1,9 @@
+import { OrigamiFiles, Scope } from "@weborigami/language";
+import os from "node:os";
+import builtins from "./@builtins.js";
+
+/** @type {import("@weborigami/types").AsyncTree} */
+let tree = new OrigamiFiles(os.homedir());
+tree = Scope.treeWithScope(tree, builtins);
+
+export default tree;

package/src/cli/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import { ObjectTree, Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import path from "node:path";
+import process, { stdout } from "node:process";
+import ori from "../builtins/@ori.js";
+import project from "../builtins/@project.js";
+import { keySymbol } from "../common/utilities.js";
+import showUsage from "./showUsage.js";
+
+async function main(...args) {
+  const expression = args.join(" ");
+
+  // Find the project root.
+  const projectTree = await project.call(null);
+
+  // HACK: get the configuration via the project.
+  const config = new Scope(...projectTree.scope.trees.slice(1));
+
+  // If no arguments were passed, show usage.
+  if (!expression) {
+    await showUsage(config);
+    return;
+  }
+
+  // Splice ambients tree into project tree scope.
+  const ambients = new ObjectTree({});
+  ambients[keySymbol] = "Origami CLI";
+  let tree = Scope.treeWithScope(projectTree, new Scope(ambients, config));
+
+  // Traverse from the project root to the current directory.
+  const currentDirectory = process.cwd();
+  const relative = path.relative(projectTree.path, currentDirectory);
+  if (relative !== "") {
+    tree = await Tree.traversePath(tree, relative);
+  }
+
+  // Add ambient property for the current tree.
+  await ambients.set("@current", tree);
+
+  const scope = Scope.getScope(tree);
+  const result = await ori.call(scope, expression);
+  if (result !== undefined) {
+    const output = result instanceof Buffer ? result : String(result);
+    await stdout.write(output);
+
+    // If stdout points to the console, and the result didn't end in a newline,
+    // then output a newline.
+    if (stdout.isTTY) {
+      const lastChar = output[output.length - 1];
+      const isNewLine = lastChar === "\n" || lastChar === 10;
+      if (!isNewLine) {
+        await stdout.write("\n");
+      }
+    }
+  }
+}
+
+// Process command line arguments
+const args = process.argv;
+args.shift(); // "node"
+args.shift(); // name of this script file
+// Not sure why we end up with blank arguments; skip them.
+while (args[0] === "") {
+  args.shift();
+}
+try {
+  await main(...args);
+} catch (/** @type {any} */ error) {
+  // Work up to the root cause, displaying intermediate messages as we go up.
+  if (!error.cause && !error.stack) {
+    console.error(error.message);
+  } else {
+    while (error.cause) {
+      console.error(error.message);
+      error = error.cause;
+    }
+  }
+  if (error.stack) {
+    // Display stack trace for root cause, under the theory that that's the most
+    // useful place to look for the problem.
+    console.error(error.stack);
+  }
+  process.exitCode = 1;
+}

package/src/cli/defaultModuleExport.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+export default async function defaultModuleExport(...keys) {
+  // On Windows, absolute paths must be valid file:// URLs.
+  const modulePath = path.resolve(process.cwd(), ...keys);
+  const url = pathToFileURL(modulePath);
+  const module = await import(url.href);
+  const result = module.default;
+  if (!result) {
+    console.error(`${modulePath} does not define a default export.`);
+    return;
+  }
+  return result;
+}

package/src/cli/showUsage.js

@@ -0,0 +1,86 @@
+const groupDescriptions = {
+  "@cache": "Functions for caching data",
+  "@tree": "Functions for working with trees",
+  "@image": "Functions for working with images",
+  "@parse": "Parsing functions",
+  "@scope": "Functions for working with tree scopes",
+};
+
+export default async function showUsage(scope) {
+  console.log(`Usage: ori <expression>, which could be:
+- a string in single quotes, or a number
+- a file or folder name
+- an https: or http: URL
+- a name like "foo" that refers to an object/function exported by a project file foo.js
+- the name of a function below:
+`);
+
+  // Gather usages.
+  const usages = [];
+  for (const key of await scope.keys()) {
+    let command;
+    // We get the command associated with the key in a try/catch because
+    // we want to ignore any syntax errors.
+    try {
+      command = await scope.get(key);
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        continue;
+      }
+    }
+    if (groupDescriptions[key]) {
+      usages.push(`${key}\t${groupDescriptions[key]}`);
+    } else if (typeof command === "function") {
+      let usage = command?.usage;
+      if (!usage) {
+        usage = defaultUsage(key, command);
+      }
+      usages.push(usage);
+    }
+  }
+
+  // Case-insensitive sort
+  usages.sort(function (a, b) {
+    return a.toLowerCase().localeCompare(b.toLowerCase());
+  });
+
+  // Split into signatures and descriptions.
+  const signatures = [];
+  const descriptions = [];
+  usages.forEach((usage) => {
+    const [signature, description] = usage.split("\t");
+    signatures.push(signature);
+    descriptions.push(description || "");
+  });
+
+  // Calculate length of longest signature.
+  const lengths = signatures.map((signature) => signature.length);
+  const maxLength = Math.max(...lengths);
+
+  // Format lines, padding the descriptions to that length + gap.
+  const gap = 4;
+  const length = maxLength + gap;
+  const formatted = signatures.map(
+    (signature, index) => `${signature.padEnd(length)}${descriptions[index]}`
+  );
+
+  console.log(formatted.join("\n"));
+  console.log(
+    `\nMore details: "ori @help"; or get help on a function like @serve with "ori @help/@serve"`
+  );
+}
+
+function defaultUsage(name, fn) {
+  const arity = fn.length;
+  if (arity === 0) {
+    return `${name}()`;
+  } else if (arity === 1) {
+    return `${name}(arg)`;
+  } else {
+    let args = [];
+    for (let i = 0; i < arity; i++) {
+      args.push(`arg${i + 1}`);
+    }
+    return `${name}(${args.join(", ")})`;
+  }
+}

package/src/common/CommandModulesTransform.d.ts

@@ -0,0 +1,5 @@
+import { Mixin } from "@weborigami/language";
+
+declare const CommandModulesTransform: Mixin<{}>;
+
+export default CommandModulesTransform;