@rhost/testkit 1.5.1 → 1.5.3

package/node_modules/@ursamu/mushcode/src/eval/engine.js

@@ -0,0 +1,238 @@
+import { parse } from "../../parser/mod.js";
+// ── EvalEngine ────────────────────────────────────────────────────────────────
+/**
+ * AST-based softcode evaluator.
+ *
+ * Register functions and commands, then call `evalString()` to evaluate a
+ * raw softcode string or `eval()` to evaluate an already-parsed node.
+ *
+ * @example
+ * const engine = new EvalEngine(myAccessor);
+ * registerStdlib(engine);
+ * engine.registerFunction("u", { eval: "lazy", minArgs: 1, maxArgs: Infinity, exec: uImpl });
+ * const result = await engine.evalString("[add(1,2)]", ctx);
+ * // → "3"
+ */ export class EvalEngine {
+  accessor;
+  functions;
+  commands;
+  subHandlers;
+  fallbackCommand;
+  constructor(/** The host-provided database accessor (passed to DB stdlib functions). */ accessor){
+    this.accessor = accessor;
+    this.functions = new Map();
+    this.commands = new Map();
+    this.subHandlers = [];
+  }
+  /** Register a softcode function by name (case-insensitive). Returns `this` for chaining. */ registerFunction(name, impl) {
+    this.functions.set(name.toLowerCase(), impl);
+    return this;
+  }
+  /** Register a `@command` handler by name (case-insensitive). Returns `this` for chaining. */ registerCommand(name, impl) {
+    this.commands.set(name.toLowerCase(), impl);
+    return this;
+  }
+  /**
+   * Register a custom `%<code>` substitution handler.
+   *
+   * Custom handlers are checked **before** built-in substitutions, so you can
+   * override any built-in code. `match` is either an exact code string (e.g.
+   * `"s"` for `%s`) or a predicate (e.g. `code => code.startsWith("V")` for
+   * `%Va`–`%Vz`).
+   *
+   * @returns `this` for chaining.
+   */ registerSub(match, fn) {
+    this.subHandlers.push({
+      match,
+      fn
+    });
+    return this;
+  }
+  /**
+   * Register a fallback handler for `@commands` that have no specific handler registered.
+   *
+   * @returns `this` for chaining.
+   */ registerCommandFallback(fn) {
+    this.fallbackCommand = fn;
+    return this;
+  }
+  /** Parse and evaluate a raw softcode string. */ async evalString(source, ctx) {
+    const ast = parse(source, "Start");
+    return await this.eval(ast, ctx);
+  }
+  // ── Core evaluator ──────────────────────────────────────────────────────────
+  /** Evaluate a node to a string. */ async eval(node, ctx) {
+    if (ctx.signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    if (ctx.depth > ctx.maxDepth) return "#-1 EVALUATION DEPTH EXCEEDED";
+    // deno-lint-ignore no-explicit-any
+    const n = node;
+    switch(node.type){
+      // ── Leaves ──────────────────────────────────────────────────────────────
+      case "Literal":
+        return n.value;
+      case "Escape":
+        return n.char;
+      case "TagRef":
+        return "#" + n.name;
+      case "Substitution":
+        return await this.evalSub(n.code, ctx);
+      case "SpecialVar":
+        return this.evalSpecialVar(n.code, ctx);
+      // ── Containers that just concatenate their parts ─────────────────────
+      case "EvalBlock":
+      case "Arg":
+      case "Text":
+      case "Pattern":
+      case "BracedString":
+      case "UserCommand":
+        return this.evalParts(n.parts, ctx);
+      // ── Function call ────────────────────────────────────────────────────
+      case "FunctionCall":
+        return this.evalFunction(node, ctx);
+      // ── Command nodes — side effects only, return empty string ──────────
+      case "CommandList":
+      case "AtCommand":
+      case "AttributeSet":
+        await this.exec(node, ctx);
+        return "";
+      // ── Patterns — produce their printed form; registration is host work ─
+      case "DollarPattern":
+      case "ListenPattern":
+        return "";
+      default:
+        return "";
+    }
+  }
+  /** Execute a node for its side effects (commands). */ async exec(node, ctx) {
+    // deno-lint-ignore no-explicit-any
+    const n = node;
+    switch(node.type){
+      case "CommandList":
+        for (const cmd of n.commands){
+          await this.exec(cmd, ctx);
+        }
+        break;
+      case "AtCommand":
+        {
+          const name = n.name.toLowerCase();
+          const impl = this.commands.get(name);
+          const obj = n.object ? await this.eval(n.object, ctx) : null;
+          const val = n.value ? await this.eval(n.value, ctx) : null;
+          if (impl) {
+            await impl.exec(n.switches, obj, val, ctx, this);
+          } else if (this.fallbackCommand) {
+            await this.fallbackCommand(n.name, n.switches, obj, val, ctx, this);
+          }
+          break;
+        }
+      case "AttributeSet":
+        {
+          const impl = this.commands.get("&");
+          if (!impl) break;
+          const obj = await this.eval(n.object, ctx);
+          const val = n.value ? await this.eval(n.value, ctx) : null;
+          await impl.exec([], obj, val != null ? `${n.attribute}=${val}` : n.attribute, ctx, this);
+          break;
+        }
+      default:
+        // Non-command in exec position — evaluate for side effects (e.g. a UserCommand
+        // that contains embedded [pemit(...)] blocks).
+        await this.eval(node, ctx);
+    }
+  }
+  // ── Helpers ─────────────────────────────────────────────────────────────────
+  async evalParts(parts, ctx) {
+    const chunks = [];
+    let total = 0;
+    for (const p of parts){
+      const chunk = await this.eval(p, ctx);
+      total += chunk.length;
+      if (total > ctx.maxOutputLen) return "#-1 OUTPUT LIMIT EXCEEDED";
+      chunks.push(chunk);
+    }
+    return chunks.join("");
+  }
+  async evalFunction(node, ctx) {
+    // deno-lint-ignore no-explicit-any
+    const n = node;
+    const name = n.name.toLowerCase();
+    const impl = this.functions.get(name);
+    if (!impl) return `#-1 FUNCTION (${n.name}) NOT FOUND`;
+    const args = n.args;
+    if (args.length < impl.minArgs) return `#-1 FUNCTION (${n.name}) REQUIRES AT LEAST ${impl.minArgs} ARGUMENT(S)`;
+    if (args.length > impl.maxArgs) return `#-1 FUNCTION (${n.name}) TAKES AT MOST ${impl.maxArgs} ARGUMENT(S)`;
+    try {
+      if (impl.eval === "lazy") {
+        const thunks = args.map((arg)=>(override)=>this.eval(arg, override ? {
+              ...ctx,
+              ...override
+            } : ctx));
+        return await impl.exec(thunks, ctx, this) ?? "";
+      }
+      const vals = [];
+      for (const arg of args)vals.push(await this.eval(arg, ctx));
+      return await impl.exec(vals, ctx, this) ?? "";
+    } catch (e) {
+      return `#-1 ${e instanceof Error ? e.message.toUpperCase() : "ERROR"}`;
+    }
+  }
+  async evalSub(code, ctx) {
+    // Custom substitution handlers — checked before built-ins
+    for (const { match, fn } of this.subHandlers){
+      if (typeof match === "string" ? match === code : match(code)) {
+        return fn(code, ctx);
+      }
+    }
+    // Positional arguments
+    if (/^[0-9]$/.test(code)) return ctx.args[parseInt(code)] ?? "";
+    // Registers
+    if (code.startsWith("q")) return ctx.registers.get(code.slice(1)) ?? "";
+    // Context objects
+    if (code === "#") return ctx.enactor;
+    if (code === ":") return ctx.enactor; // objid — same as enactor in flat-UUID systems
+    if (code === "!") return ctx.executor;
+    if (code === "@") return ctx.caller ?? "";
+    if (code === "+") return String(ctx.args.length);
+    // Formatting characters
+    if (code === "r" || code === "R") return "\r\n";
+    if (code === "t" || code === "T") return "\t";
+    if (code === "b" || code === "B") return " ";
+    if (code === "%") return "%";
+    if (code === "[") return "[";
+    if (code === "]") return "]";
+    if (code === ",") return ",";
+    if (code === ";") return ";";
+    if (code === "\\") return "\\";
+    // Name — needs DB
+    if (code === "N") return this.accessor.getName(ctx.enactor);
+    if (code === "n") return (await this.accessor.getName(ctx.enactor)).toLowerCase();
+    // Location — needs DB
+    if (code === "L") return await this.resolveLocation(ctx);
+    // Iter variables via %i0–%i9
+    if (/^i[0-9]$/.test(code)) {
+      const depth = parseInt(code[1]);
+      return ctx.iterStack[depth]?.item ?? "";
+    }
+    // Attribute shorthand %=ATTRNAME — read from enactor
+    if (code.startsWith("=")) return await this.accessor.getAttr(ctx.enactor, code.slice(1)) ?? "";
+    // ANSI codes — pass through as-is for the host to render
+    if (/^[xXcC]/.test(code)) return `%${code}`;
+    return "";
+  }
+  evalSpecialVar(code, ctx) {
+    const frame = ctx.iterStack[0];
+    if (code === "##") return frame?.item ?? "";
+    if (code === "#@") return frame ? String(frame.index) : "";
+    if (code === "#$") return ""; // last name-lookup dbref — host concern
+    return "";
+  }
+  async resolveLocation(ctx) {
+    try {
+      const target = await this.accessor.resolveTarget(ctx.enactor, "loc(me)");
+      return target ?? "";
+    } catch  {
+      return "";
+    }
+  }
+}
+//# sourceMappingURL=engine.js.map

package/node_modules/@ursamu/mushcode/src/eval/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sources":["./engine.ts"],"names":[],"mappings":"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"}

package/node_modules/@ursamu/mushcode/src/eval/engine.ts

@@ -0,0 +1,276 @@
+import type { ASTNode }     from "../../parser/mod.js";
+import { parse }              from "../../parser/mod.js";
+import type {
+  EvalContext, EvalThunk,
+  FunctionImpl, CommandImpl,
+  ObjectAccessor, IEvalEngine,
+  IterFrame, SubHandlerFn, CommandFallbackFn,
+} from "./context.ts";
+
+// ── EvalEngine ────────────────────────────────────────────────────────────────
+
+/**
+ * AST-based softcode evaluator.
+ *
+ * Register functions and commands, then call `evalString()` to evaluate a
+ * raw softcode string or `eval()` to evaluate an already-parsed node.
+ *
+ * @example
+ * const engine = new EvalEngine(myAccessor);
+ * registerStdlib(engine);
+ * engine.registerFunction("u", { eval: "lazy", minArgs: 1, maxArgs: Infinity, exec: uImpl });
+ * const result = await engine.evalString("[add(1,2)]", ctx);
+ * // → "3"
+ */
+export class EvalEngine implements IEvalEngine {
+  private readonly functions   = new Map<string, FunctionImpl>();
+  private readonly commands    = new Map<string, CommandImpl>();
+  private readonly subHandlers: Array<{ match: string | ((code: string) => boolean); fn: SubHandlerFn }> = [];
+  private fallbackCommand?: CommandFallbackFn;
+
+  constructor(
+    /** The host-provided database accessor (passed to DB stdlib functions). */
+    readonly accessor: ObjectAccessor,
+  ) {}
+
+  /** Register a softcode function by name (case-insensitive). Returns `this` for chaining. */
+  registerFunction(name: string, impl: FunctionImpl): this {
+    this.functions.set(name.toLowerCase(), impl);
+    return this;
+  }
+
+  /** Register a `@command` handler by name (case-insensitive). Returns `this` for chaining. */
+  registerCommand(name: string, impl: CommandImpl): this {
+    this.commands.set(name.toLowerCase(), impl);
+    return this;
+  }
+
+  /**
+   * Register a custom `%<code>` substitution handler.
+   *
+   * Custom handlers are checked **before** built-in substitutions, so you can
+   * override any built-in code. `match` is either an exact code string (e.g.
+   * `"s"` for `%s`) or a predicate (e.g. `code => code.startsWith("V")` for
+   * `%Va`–`%Vz`).
+   *
+   * @returns `this` for chaining.
+   */
+  registerSub(
+    match: string | ((code: string) => boolean),
+    fn: SubHandlerFn,
+  ): this {
+    this.subHandlers.push({ match, fn });
+    return this;
+  }
+
+  /**
+   * Register a fallback handler for `@commands` that have no specific handler registered.
+   *
+   * @returns `this` for chaining.
+   */
+  registerCommandFallback(fn: CommandFallbackFn): this {
+    this.fallbackCommand = fn;
+    return this;
+  }
+
+  /** Parse and evaluate a raw softcode string. */
+  async evalString(source: string, ctx: EvalContext): Promise<string> {
+    const ast = parse(source, "Start");
+    return await this.eval(ast, ctx);
+  }
+
+  // ── Core evaluator ──────────────────────────────────────────────────────────
+
+  /** Evaluate a node to a string. */
+  async eval(node: ASTNode, ctx: EvalContext): Promise<string> {
+    if (ctx.signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    if (ctx.depth > ctx.maxDepth) return "#-1 EVALUATION DEPTH EXCEEDED";
+
+    // deno-lint-ignore no-explicit-any
+    const n = node as any;
+
+    switch (node.type) {
+      // ── Leaves ──────────────────────────────────────────────────────────────
+      case "Literal":      return n.value as string;
+      case "Escape":       return n.char  as string;
+      case "TagRef":       return "#" + (n.name as string);
+
+      case "Substitution": return await this.evalSub(n.code as string, ctx);
+      case "SpecialVar":   return this.evalSpecialVar(n.code as string, ctx);
+
+      // ── Containers that just concatenate their parts ─────────────────────
+      case "EvalBlock":
+      case "Arg":
+      case "Text":
+      case "Pattern":
+      case "BracedString":
+      case "UserCommand":
+        return this.evalParts(n.parts as ASTNode[], ctx);
+
+      // ── Function call ────────────────────────────────────────────────────
+      case "FunctionCall":
+        return this.evalFunction(node, ctx);
+
+      // ── Command nodes — side effects only, return empty string ──────────
+      case "CommandList":
+      case "AtCommand":
+      case "AttributeSet":
+        await this.exec(node, ctx);
+        return "";
+
+      // ── Patterns — produce their printed form; registration is host work ─
+      case "DollarPattern":
+      case "ListenPattern":
+        return "";
+
+      default:
+        return "";
+    }
+  }
+
+  /** Execute a node for its side effects (commands). */
+  async exec(node: ASTNode, ctx: EvalContext): Promise<void> {
+    // deno-lint-ignore no-explicit-any
+    const n = node as any;
+
+    switch (node.type) {
+      case "CommandList":
+        for (const cmd of n.commands as ASTNode[]) {
+          await this.exec(cmd, ctx);
+        }
+        break;
+
+      case "AtCommand": {
+        const name = (n.name as string).toLowerCase();
+        const impl = this.commands.get(name);
+        const obj = n.object ? await this.eval(n.object as ASTNode, ctx) : null;
+        const val = n.value  ? await this.eval(n.value  as ASTNode, ctx) : null;
+        if (impl) {
+          await impl.exec(n.switches as string[], obj, val, ctx, this);
+        } else if (this.fallbackCommand) {
+          await this.fallbackCommand(n.name as string, n.switches as string[], obj, val, ctx, this);
+        }
+        break;
+      }
+
+      case "AttributeSet": {
+        const impl = this.commands.get("&");
+        if (!impl) break;
+        const obj = await this.eval(n.object as ASTNode, ctx);
+        const val = n.value ? await this.eval(n.value as ASTNode, ctx) : null;
+        await impl.exec([], obj, val != null ? `${n.attribute}=${val}` : n.attribute, ctx, this);
+        break;
+      }
+
+      default:
+        // Non-command in exec position — evaluate for side effects (e.g. a UserCommand
+        // that contains embedded [pemit(...)] blocks).
+        await this.eval(node, ctx);
+    }
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────────
+
+  private async evalParts(parts: ASTNode[], ctx: EvalContext): Promise<string> {
+    const chunks: string[] = [];
+    let total = 0;
+    for (const p of parts) {
+      const chunk = await this.eval(p, ctx);
+      total += chunk.length;
+      if (total > ctx.maxOutputLen) return "#-1 OUTPUT LIMIT EXCEEDED";
+      chunks.push(chunk);
+    }
+    return chunks.join("");
+  }
+
+  private async evalFunction(node: ASTNode, ctx: EvalContext): Promise<string> {
+    // deno-lint-ignore no-explicit-any
+    const n    = node as any;
+    const name = (n.name as string).toLowerCase();
+    const impl = this.functions.get(name);
+
+    if (!impl) return `#-1 FUNCTION (${n.name}) NOT FOUND`;
+
+    const args = n.args as ASTNode[];
+    if (args.length < impl.minArgs)
+      return `#-1 FUNCTION (${n.name}) REQUIRES AT LEAST ${impl.minArgs} ARGUMENT(S)`;
+    if (args.length > impl.maxArgs)
+      return `#-1 FUNCTION (${n.name}) TAKES AT MOST ${impl.maxArgs} ARGUMENT(S)`;
+
+    try {
+      if (impl.eval === "lazy") {
+        const thunks: EvalThunk[] = args.map(arg =>
+          (override?: Partial<EvalContext>) =>
+            this.eval(arg, override ? { ...ctx, ...override } : ctx)
+        );
+        return (await impl.exec(thunks, ctx, this)) ?? "";
+      }
+      const vals: string[] = [];
+      for (const arg of args) vals.push(await this.eval(arg, ctx));
+      return (await impl.exec(vals, ctx, this)) ?? "";
+    } catch (e: unknown) {
+      return `#-1 ${e instanceof Error ? e.message.toUpperCase() : "ERROR"}`;
+    }
+  }
+
+  private async evalSub(code: string, ctx: EvalContext): Promise<string> {
+    // Custom substitution handlers — checked before built-ins
+    for (const { match, fn } of this.subHandlers) {
+      if (typeof match === "string" ? match === code : match(code)) {
+        return fn(code, ctx);
+      }
+    }
+    // Positional arguments
+    if (/^[0-9]$/.test(code))          return ctx.args[parseInt(code)] ?? "";
+    // Registers
+    if (code.startsWith("q"))           return ctx.registers.get(code.slice(1)) ?? "";
+    // Context objects
+    if (code === "#")                   return ctx.enactor;
+    if (code === ":")                   return ctx.enactor;  // objid — same as enactor in flat-UUID systems
+    if (code === "!")                   return ctx.executor;
+    if (code === "@")                   return ctx.caller ?? "";
+    if (code === "+")                   return String(ctx.args.length);
+    // Formatting characters
+    if (code === "r" || code === "R")   return "\r\n";
+    if (code === "t" || code === "T")   return "\t";
+    if (code === "b" || code === "B")   return " ";
+    if (code === "%")                   return "%";
+    if (code === "[")                   return "[";
+    if (code === "]")                   return "]";
+    if (code === ",")                   return ",";
+    if (code === ";")                   return ";";
+    if (code === "\\")                  return "\\";
+    // Name — needs DB
+    if (code === "N")                   return this.accessor.getName(ctx.enactor);
+    if (code === "n")                   return (await this.accessor.getName(ctx.enactor)).toLowerCase();
+    // Location — needs DB
+    if (code === "L")                   return await this.resolveLocation(ctx);
+    // Iter variables via %i0–%i9
+    if (/^i[0-9]$/.test(code)) {
+      const depth = parseInt(code[1]);
+      return ctx.iterStack[depth]?.item ?? "";
+    }
+    // Attribute shorthand %=ATTRNAME — read from enactor
+    if (code.startsWith("="))           return (await this.accessor.getAttr(ctx.enactor, code.slice(1))) ?? "";
+    // ANSI codes — pass through as-is for the host to render
+    if (/^[xXcC]/.test(code))          return `%${code}`;
+    return "";
+  }
+
+  private evalSpecialVar(code: string, ctx: EvalContext): string {
+    const frame: IterFrame | undefined = ctx.iterStack[0];
+    if (code === "##") return frame?.item  ?? "";
+    if (code === "#@") return frame ? String(frame.index) : "";
+    if (code === "#$") return "";  // last name-lookup dbref — host concern
+    return "";
+  }
+
+  private async resolveLocation(ctx: EvalContext): Promise<string> {
+    try {
+      const target = await this.accessor.resolveTarget(ctx.enactor, "loc(me)");
+      return target ?? "";
+    } catch {
+      return "";
+    }
+  }
+}

package/node_modules/@ursamu/mushcode/src/eval/mod.js

@@ -0,0 +1,25 @@
+/**
+ * @module
+ * AST-based softcode evaluator: `EvalEngine`, `makeContext()`, `registerStdlib()`,
+ * and the full type vocabulary for contexts, accessors, and function registrations.
+ *
+ * @example
+ * ```ts
+ * import { EvalEngine, makeContext, registerStdlib } from "@ursamu/mushcode/eval";
+ *
+ * const engine = new EvalEngine({
+ *   getAttr: async (_id, _attr) => null,
+ *   resolveTarget: async (_from, expr) => expr === "me" ? "player-uuid" : null,
+ *   getName: async (_id) => "Tester",
+ *   hasFlag: async (_id, _flag) => false,
+ * });
+ * registerStdlib(engine);
+ *
+ * const ctx    = makeContext({ enactor: "player-uuid", executor: "player-uuid" });
+ * const result = await engine.evalString("[add(1,2)] [capstr(hello)]", ctx);
+ * console.log(result); // "3 Hello"
+ * ```
+ */ export { EvalEngine } from "./engine.js";
+export { makeContext } from "./context.js";
+export { registerStdlib } from "./stdlib/mod.js";
+//# sourceMappingURL=mod.js.map

package/node_modules/@ursamu/mushcode/src/eval/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sources":["./mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,SAAS,UAAU,sBAA+B;AAClD,SAAS,WAAW,uBAA+B;AACnD,SAAS,cAAc,0BAA+B"}

package/node_modules/@ursamu/mushcode/src/eval/mod.ts

@@ -0,0 +1,31 @@
+/**
+ * @module
+ * AST-based softcode evaluator: `EvalEngine`, `makeContext()`, `registerStdlib()`,
+ * and the full type vocabulary for contexts, accessors, and function registrations.
+ *
+ * @example
+ * ```ts
+ * import { EvalEngine, makeContext, registerStdlib } from "@ursamu/mushcode/eval";
+ *
+ * const engine = new EvalEngine({
+ *   getAttr: async (_id, _attr) => null,
+ *   resolveTarget: async (_from, expr) => expr === "me" ? "player-uuid" : null,
+ *   getName: async (_id) => "Tester",
+ *   hasFlag: async (_id, _flag) => false,
+ * });
+ * registerStdlib(engine);
+ *
+ * const ctx    = makeContext({ enactor: "player-uuid", executor: "player-uuid" });
+ * const result = await engine.evalString("[add(1,2)] [capstr(hello)]", ctx);
+ * console.log(result); // "3 Hello"
+ * ```
+ */
+export { EvalEngine }          from "./engine.js";
+export { makeContext }         from "./context.js";
+export { registerStdlib }      from "./stdlib/mod.js";
+export type {
+  EvalContext, EvalThunk,
+  ObjectAccessor, IEvalEngine,
+  FunctionImpl, CommandImpl,
+  IterFrame, SubHandlerFn, CommandFallbackFn,
+}                              from "./context.js";

package/node_modules/@ursamu/mushcode/src/eval/stdlib/compare.js

@@ -0,0 +1,56 @@
+function toNum(s) {
+  const n = Number(s);
+  if (!isFinite(n)) throw new Error(`ARGUMENT (${s}) IS NOT A NUMBER`);
+  return n;
+}
+export const compareFunctions = {
+  eq: {
+    minArgs: 2,
+    maxArgs: 2,
+    exec (args) {
+      const [a, b] = args;
+      return toNum(a) === toNum(b) ? "1" : "0";
+    }
+  },
+  neq: {
+    minArgs: 2,
+    maxArgs: 2,
+    exec (args) {
+      const [a, b] = args;
+      return toNum(a) !== toNum(b) ? "1" : "0";
+    }
+  },
+  gt: {
+    minArgs: 2,
+    maxArgs: 2,
+    exec (args) {
+      const [a, b] = args;
+      return toNum(a) > toNum(b) ? "1" : "0";
+    }
+  },
+  gte: {
+    minArgs: 2,
+    maxArgs: 2,
+    exec (args) {
+      const [a, b] = args;
+      return toNum(a) >= toNum(b) ? "1" : "0";
+    }
+  },
+  lt: {
+    minArgs: 2,
+    maxArgs: 2,
+    exec (args) {
+      const [a, b] = args;
+      return toNum(a) < toNum(b) ? "1" : "0";
+    }
+  },
+  lte: {
+    minArgs: 2,
+    maxArgs: 2,
+    exec (args) {
+      const [a, b] = args;
+      return toNum(a) <= toNum(b) ? "1" : "0";
+    }
+  }
+};
+//# sourceMappingURL=compare.js.map

package/node_modules/@ursamu/mushcode/src/eval/stdlib/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sources":["./compare.ts"],"names":[],"mappings":"AAEA,SAAS,MAAM,CAAS;EACtB,MAAM,IAAI,OAAO;EACjB,IAAI,CAAC,SAAS,IAAI,MAAM,IAAI,MAAM,CAAC,UAAU,EAAE,EAAE,iBAAiB,CAAC;EACnE,OAAO;AACT;AAEA,OAAO,MAAM,mBAAiD;EAC5D,IAAK;IAAE,SAAS;IAAG,SAAS;IAAG,MAAK,IAAI;MAAI,MAAM,CAAC,GAAE,EAAE,GAAG;MAAkB,OAAO,MAAM,OAAO,MAAM,KAAK,MAAM;IAAK;EAAE;EACxH,KAAK;IAAE,SAAS;IAAG,SAAS;IAAG,MAAK,IAAI;MAAI,MAAM,CAAC,GAAE,EAAE,GAAG;MAAkB,OAAO,MAAM,OAAO,MAAM,KAAK,MAAM;IAAK;EAAE;EACxH,IAAK;IAAE,SAAS;IAAG,SAAS;IAAG,MAAK,IAAI;MAAI,MAAM,CAAC,GAAE,EAAE,GAAG;MAAkB,OAAO,MAAM,KAAO,MAAM,KAAK,MAAM;IAAK;EAAE;EACxH,KAAK;IAAE,SAAS;IAAG,SAAS;IAAG,MAAK,IAAI;MAAI,MAAM,CAAC,GAAE,EAAE,GAAG;MAAkB,OAAO,MAAM,MAAO,MAAM,KAAK,MAAM;IAAK;EAAE;EACxH,IAAK;IAAE,SAAS;IAAG,SAAS;IAAG,MAAK,IAAI;MAAI,MAAM,CAAC,GAAE,EAAE,GAAG;MAAkB,OAAO,MAAM,KAAO,MAAM,KAAK,MAAM;IAAK;EAAE;EACxH,KAAK;IAAE,SAAS;IAAG,SAAS;IAAG,MAAK,IAAI;MAAI,MAAM,CAAC,GAAE,EAAE,GAAG;MAAkB,OAAO,MAAM,MAAO,MAAM,KAAK,MAAM;IAAK;EAAE;AAC1H,EAAE"}

package/node_modules/@ursamu/mushcode/src/eval/stdlib/compare.ts

@@ -0,0 +1,16 @@
+import type { FunctionImpl } from "../context.ts";
+
+function toNum(s: string): number {
+  const n = Number(s);
+  if (!isFinite(n)) throw new Error(`ARGUMENT (${s}) IS NOT A NUMBER`);
+  return n;
+}
+
+export const compareFunctions: Record<string, FunctionImpl> = {
+  eq:  { minArgs: 2, maxArgs: 2, exec(args) { const [a,b] = args as string[]; return toNum(a) === toNum(b) ? "1" : "0"; } },
+  neq: { minArgs: 2, maxArgs: 2, exec(args) { const [a,b] = args as string[]; return toNum(a) !== toNum(b) ? "1" : "0"; } },
+  gt:  { minArgs: 2, maxArgs: 2, exec(args) { const [a,b] = args as string[]; return toNum(a) >   toNum(b) ? "1" : "0"; } },
+  gte: { minArgs: 2, maxArgs: 2, exec(args) { const [a,b] = args as string[]; return toNum(a) >=  toNum(b) ? "1" : "0"; } },
+  lt:  { minArgs: 2, maxArgs: 2, exec(args) { const [a,b] = args as string[]; return toNum(a) <   toNum(b) ? "1" : "0"; } },
+  lte: { minArgs: 2, maxArgs: 2, exec(args) { const [a,b] = args as string[]; return toNum(a) <=  toNum(b) ? "1" : "0"; } },
+};