@gesslar/muddy 0.0.1

package/src/Type.js

@@ -0,0 +1,113 @@
+import {URL} from "node:url"
+import {Collection, Util} from "@gesslar/toolkit"
+
+// Aliases
+const {capitalize} = Util
+const {allocateObject} = Collection
+const {freeze} = Object
+
+/**
+ * Type constants and mappings for Mudlet module types.
+ *
+ * Provides mappings between singular/plural forms, class constructors,
+ * file names, URLs, and XML package tag names for all module types.
+ */
+const Type = {}
+
+// Base
+const single = () => freeze(new Array("alias", "key", "script", "timer", "trigger"))
+const plural = () => freeze(new Array("aliases", "keys", "scripts", "timers", "triggers"))
+
+/**
+ * Array of singular module type names.
+ *
+ * @type {Array<string>}
+ */
+Type.SINGLE = single()
+
+/**
+ * Array of plural module type names.
+ *
+ * @type {Array<string>}
+ */
+Type.PLURAL = plural()
+
+/**
+ * Mapping from singular to plural module type names.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+Type.TO_PLURAL = freeze(await allocateObject(single(), plural()))
+
+/**
+ * Mapping from plural to singular module type names.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+Type.TO_SINGLE = freeze(await allocateObject(plural(), single()))
+
+const classify = async e => (await import(`./modules/${capitalize(e)}.js`)).default
+
+/**
+ * Mapping from plural module type names to their class constructors.
+ *
+ * @type {Readonly<Record<string, Function>>}
+ */
+Type.CLASS = Object.freeze(await allocateObject(
+  plural(),
+  await Promise.all(single().map(classify))
+))
+
+const upper = e => e.toUpperCase()
+
+/**
+ * Mapping from uppercase type names to plural module type names.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+Type.TYPES = Object.freeze(await allocateObject(
+  single().map(upper),
+  plural()
+))
+
+const file = e => `${e}.json`
+
+/**
+ * Mapping from plural module type names to their JSON file names.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+Type.FILES = Object.freeze(await allocateObject(
+  plural(),
+  plural().map(file)
+))
+
+const baseUrl = "https://schema.gesslar.dev/muddler/v1/"
+const url = e => new URL(`${e}.json`, baseUrl)
+
+/**
+ * Mapping from type names to their schema URLs.
+ *
+ * @type {Readonly<Record<string, URL>>}
+ */
+Type.URL = Object.freeze(await allocateObject(
+  ["mfile", "common", ...plural()],
+  ["mfile", "common", ...plural()].map(url)
+))
+
+const pack = e => `${capitalize(e)}Package`
+
+/**
+ * Mapping from plural module type names to their XML package tag names.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+Type.PACKAGES = Object.freeze(await allocateObject(
+  plural(),
+  single().map(pack)
+))
+
+/**
+ * Sealed Type object containing all module type constants and mappings.
+ */
+export default Object.seal(Type)

package/src/Watch.js

@@ -0,0 +1,139 @@
+import {Disposer, Notify, Sass, Term, Time} from "@gesslar/toolkit"
+import {watch} from "node:fs/promises"
+import process from "node:process"
+
+import Muddy from "./Muddy.js"
+
+/**
+ * @import {DirectoryObject} from "@gesslar/toolkit"
+ * @import {DisposerClass} from "@gesslar/toolkit"
+ * @import {FileObject} from "@gesslar/toolkit"
+ * @import {Glog} from "@gesslar/toolkit"
+ * @import {NotifyClass} from "@gesslar/toolkit"
+ */
+
+export default class Watch {
+  /** @type {DirectoryObject} */
+  #projectDirectory
+  /** @type {DirectoryObject} */
+  #srcDirectory
+  /** @type {FileObject} */
+  #mfile
+  /** @type {Glog} */
+  #glog
+  /** @type {NotifyClass} */
+  #notify
+  /** @type {DisposerClass} */
+  #disposer
+  // eslint-disable-next-line jsdoc/no-undefined-types
+  /** @type {Array<AsyncIterator>} */
+  #watchers = new Array()
+  /** @type {AbortController} */
+  #ac
+  /** @type {boolean} */
+  #pending = false
+  /** @type {boolean} */
+  #busy = false
+
+  /**
+   * Main execution point.
+   *
+   * @param {DirectoryObject} projectDirectory - The directory of project.
+   * @param {Glog} log - The Glog instance object.
+   */
+  async run(projectDirectory, log) {
+    this.#projectDirectory = projectDirectory
+    this.#srcDirectory = projectDirectory.getDirectory("src")
+    this.#mfile = this.#projectDirectory.getFile("mfile")
+    this.#glog = log
+    this.#notify = Notify
+    this.#disposer = Disposer
+
+    await new Muddy().run(this.#projectDirectory, this.#glog)
+
+    this.#initialiseInputHandler()
+    this.#startWatch()
+  }
+
+  async #startWatch() {
+    this.#ac = new AbortController()
+
+    const toWatch = [this.#srcDirectory, this.#mfile]
+
+    try {
+      for(const w of toWatch) {
+        const watcher = watch(w.url, {
+          recursive: w.isDirectory ?? false,
+          persistent: true,
+          signal: this.#ac.signal,
+          overflow: "error"
+        })
+
+        this.#watchers.push(watcher)
+
+        ;(async() => {
+          try {
+            for await(const _ of watcher) {
+              if(this.#busy) {
+                this.#pending = true
+                continue
+              }
+
+              this.#pending = false
+              this.#busy = true
+
+              while(true) {
+                await Time.after(50)
+                await new Muddy().run(this.#projectDirectory, this.#glog)
+
+                if(this.#pending) {
+                  this.#pending = false
+                  continue
+                }
+
+                break
+              }
+
+              this.#busy = false
+            }
+          } catch(err) {
+            if(err.name === "AbortError")
+              return
+
+            throw err
+          }
+        })()
+      }
+    } catch {}
+  }
+
+  /**
+   * Initialises the input handler for watch mode.
+   * Sets up raw mode input handling for interactive commands.
+   *
+   * @returns {void}
+   */
+  async #initialiseInputHandler() {
+    Term
+      .setCharMode()
+      .resume()
+      .utf8()
+      .hideCursor()
+
+    process.stdin.on("data", async key => {
+      try {
+        if(key === "q" || key === "\u0003" || key === "\u0004") {   // Ctrl+C
+          Term
+            .setLineMode()
+            .showCursor()
+            .pause()
+            .write("\nExiting.\n")
+
+          process.exit(0)
+        }
+      } catch(error) {
+        Sass.new("Processing input.", error).report(true)
+      }
+    })
+  }
+}

package/src/cli.js

@@ -0,0 +1,88 @@
+#! /usr/bin/env node
+
+import c from "@gesslar/colours"
+import {Collection, DirectoryObject, Glog, Sass, Term} from "@gesslar/toolkit"
+import {Command} from "commander"
+import process from "node:process"
+
+import Muddy from "./Muddy.js"
+import Watch from "./Watch.js"
+
+const aliasNames  = ["OK", "INFO", "WARN", "ERR"]
+const aliasCodes  = ["{<I}{F064}", "{<I}{F023}", "{<I}{F178}", "{<I}{F166}"]
+const kindNames   = ["aliases", "keys", "scripts", "timers", "triggers", "other"]
+const kindCodes   = ["{<I}{F167}", "{<I}{F135}", "{<I}{F026}", "{<I}{F223}", "{<I}{F204}", "{<I}{F136}"]
+
+const glogColourNames   = ["success", "info", "warn", "error"]
+const glogColourCodes   = ["{F035}", "{F033}", "{F208}", "{F032}"]
+
+void (async() => {
+  const opts = {}, args = []
+
+  try {
+    // Initialize colours aliases
+    aliasNames.forEach((e, i) => c.alias.set(e, aliasCodes[i]))
+    kindNames.forEach((e, i) => c.alias.set(e, kindCodes[i]))
+
+    // Initialize logging
+    const glog = new Glog()
+      .withName("MUDDY")
+      .withStackTrace()
+      .noDisplayName()
+      .withColours(await Collection.allocateObject(
+        glogColourNames,
+        glogColourCodes
+      ))
+      .withSymbols(await Collection.allocateObject(
+        glogColourNames,
+        [`•`, `•`, `•`, `•`]
+      ))
+
+    const program = new Command("muddy")
+      .argument("[directory]", "The project directory containing an 'mfile' file and 'src/' directory.")
+      .option("-w, --watch", "Enable watch mode.", false)
+      .option("-n, --nerd", "Nerd mode. Advanced error reporting.", false)
+      .parse()
+
+    Object.assign(opts, program.opts())
+    args.push(...program.args)
+
+    const dirArg = args.join(" ").trim()
+    const cwd = new DirectoryObject(dirArg || ".")
+
+    if(!await cwd.exists) {
+      glog.error(`No such directory '${dirArg}'.`)
+      process.exit(1)
+    }
+
+    if(!(await cwd.hasDirectory("src") && await cwd.hasFile("mfile"))) {
+      glog.error(`'${cwd.path}' is not a valid muddy project directory.`)
+      process.exit(1)
+    }
+
+    if(opts.watch) {
+      setupAbortHandlers()
+      await new Watch().run(cwd, glog)
+    } else {
+      await new Muddy().run(cwd, glog)
+    }
+  } catch(error) {
+    Sass.from(error, "Starting muddy.").report(opts.nerd ?? false)
+  }
+
+  /**
+   * Creates handlers for various reasons that the application may crash.
+   */
+  function setupAbortHandlers() {
+    void["SIGINT", "SIGTERM", "SIGHUP"].forEach(signal => {
+      process.on(signal, () => {
+        Term
+          .setLineMode()
+          .showCursor()
+          .pause()
+
+        process.exit(0)
+      })
+    })
+  }
+})()

package/src/modules/Action.js

@@ -0,0 +1,158 @@
+import {Valid} from "@gesslar/toolkit"
+
+import Module from "./MudletModule.js"
+
+export default class Action extends Module {
+  #meta = new Map()
+
+  constructor(object={}) {
+    super(object)
+
+    const {
+      css="",
+      commandButtonUp="",
+      commandButtonDown="",
+      icon="",
+      orientation=0,
+      location=0,
+      posX=0,
+      posY=0,
+      mButtonState=1,
+      sizeX=0,
+      sizeY=0,
+      buttonColumn=0,
+      buttonRotation=0
+    } = object
+
+    // Validate string fields
+    Valid.type(css, "String")
+    Valid.type(commandButtonUp, "String")
+    Valid.type(commandButtonDown, "String")
+    Valid.type(icon, "String")
+
+    // Validate orientation (0=horizontal, 1=vertical)
+    Valid.type(orientation, "Number")
+    Valid.assert(orientation === 0 || orientation === 1, "orientation must be 0 or 1")
+
+    // Validate location (0, 2, 3, or 4)
+    Valid.type(location, "Number")
+    Valid.assert([0, 2, 3, 4].includes(location), "location must be 0, 2, 3, or 4")
+
+    // Validate non-negative integers
+    Valid.type(posX, "Number")
+    Valid.assert(posX >= 0, "posX must be non-negative")
+    Valid.type(posY, "Number")
+    Valid.assert(posY >= 0, "posY must be non-negative")
+    Valid.type(sizeX, "Number")
+    Valid.assert(sizeX >= 0, "sizeX must be non-negative")
+    Valid.type(sizeY, "Number")
+    Valid.assert(sizeY >= 0, "sizeY must be non-negative")
+    Valid.type(buttonColumn, "Number")
+    Valid.assert(buttonColumn >= 0, "buttonColumn must be non-negative")
+
+    // Validate button state (1=unchecked/up, 2=checked/down)
+    Valid.type(mButtonState, "Number")
+    Valid.assert(mButtonState === 1 || mButtonState === 2, "mButtonState must be 1 or 2")
+
+    // Validate button rotation (0, 90, 180, or 270)
+    Valid.type(buttonRotation, "Number")
+    Valid.assert([0, 90, 180, 270].includes(buttonRotation), "buttonRotation must be 0, 90, 180, or 270")
+
+    // Store metadata
+    this.#meta.set("css", css)
+    this.#meta.set("commandButtonUp", commandButtonUp)
+    this.#meta.set("commandButtonDown", commandButtonDown)
+    this.#meta.set("icon", icon)
+    this.#meta.set("orientation", orientation)
+    this.#meta.set("location", location)
+    this.#meta.set("posX", posX)
+    this.#meta.set("posY", posY)
+    this.#meta.set("mButtonState", mButtonState)
+    this.#meta.set("sizeX", sizeX)
+    this.#meta.set("sizeY", sizeY)
+    this.#meta.set("buttonColumn", buttonColumn)
+    this.#meta.set("buttonRotation", buttonRotation)
+  }
+
+  get css() {
+    return this.#meta.get("css")
+  }
+
+  get commandButtonUp() {
+    return this.#meta.get("commandButtonUp")
+  }
+
+  get commandButtonDown() {
+    return this.#meta.get("commandButtonDown")
+  }
+
+  get icon() {
+    return this.#meta.get("icon")
+  }
+
+  get orientation() {
+    return this.#meta.get("orientation")
+  }
+
+  get location() {
+    return this.#meta.get("location")
+  }
+
+  get posX() {
+    return this.#meta.get("posX")
+  }
+
+  get posY() {
+    return this.#meta.get("posY")
+  }
+
+  get mButtonState() {
+    return this.#meta.get("mButtonState")
+  }
+
+  get sizeX() {
+    return this.#meta.get("sizeX")
+  }
+
+  get sizeY() {
+    return this.#meta.get("sizeY")
+  }
+
+  get buttonColumn() {
+    return this.#meta.get("buttonColumn")
+  }
+
+  get buttonRotation() {
+    return this.#meta.get("buttonRotation")
+  }
+
+  toJSON() {
+    return Object.assign(
+      super.toJSON(),
+      {...Object.fromEntries(this.#meta)}
+    )
+  }
+
+  toXMLFragment() {
+    const frag = super.toXMLFragment()
+
+    // Add elements in schema order (after name, packageName, script from Module)
+    frag
+      .last()
+      .ele({css: this.css}).up()
+      .ele({commandButtonUp: this.commandButtonUp}).up()
+      .ele({commandButtonDown: this.commandButtonDown}).up()
+      .ele({icon: this.icon}).up()
+      .ele({orientation: this.orientation}).up()
+      .ele({location: this.location}).up()
+      .ele({posX: this.posX}).up()
+      .ele({posY: this.posY}).up()
+      .ele({mButtonState: this.mButtonState}).up()
+      .ele({sizeX: this.sizeX}).up()
+      .ele({sizeY: this.sizeY}).up()
+      .ele({buttonColumn: this.buttonColumn}).up()
+      .ele({buttonRotation: this.buttonRotation}).up()
+
+    return frag
+  }
+}

package/src/modules/Alias.js

@@ -0,0 +1,45 @@
+import {Valid} from "@gesslar/toolkit"
+
+import MudletModule from "./MudletModule.js"
+
+export default class Alias extends MudletModule {
+  #meta = new Map()
+
+  constructor(object={regex: "", command: ""}) {
+    super(object)
+
+    const {regex="", command=""} = object
+    Valid.type(regex, "String")
+    Valid.type(command, "String")
+
+    this.#meta.set("regex", regex)
+    this.#meta.set("command", command)
+  }
+
+  get regex() {
+    return this.#meta.get("regex")
+  }
+
+  get command() {
+    return this.#meta.get("command")
+  }
+
+  toJSON() {
+    return Object.assign(
+      super.toJSON(),
+      {...Object.fromEntries(this.#meta)}
+    )
+  }
+
+  toXMLFragment() {
+    const frag = super.toXMLFragment()
+
+    // Add elements in schema order (after name, script, packageName from Module)
+    frag
+      .last()
+      .ele({command: this.command}).up()
+      .ele({regex: this.regex}).up()
+
+    return frag
+  }
+}

package/src/modules/Key.js

@@ -0,0 +1,61 @@
+import {Valid} from "@gesslar/toolkit"
+
+import MudletModule from "./MudletModule.js"
+
+export default class Key extends MudletModule {
+  #meta = new Map()
+
+  constructor(object={}) {
+    super(object)
+
+    const {
+      command="",
+      keyCode=0,
+      keyModifier=0
+    } = object
+
+    // Validate string fields
+    Valid.type(command, "String")
+
+    // Validate integer fields
+    Valid.type(keyCode, "Number")
+    Valid.type(keyModifier, "Number")
+
+    // Store metadata
+    this.#meta.set("command", command)
+    this.#meta.set("keyCode", keyCode)
+    this.#meta.set("keyModifier", keyModifier)
+  }
+
+  get command() {
+    return this.#meta.get("command")
+  }
+
+  get keyCode() {
+    return this.#meta.get("keyCode")
+  }
+
+  get keyModifier() {
+    return this.#meta.get("keyModifier")
+  }
+
+  toJSON() {
+    return Object.assign(
+      super.toJSON(),
+      {...Object.fromEntries(this.#meta)}
+    )
+  }
+
+  toXMLFragment() {
+    const frag = super.toXMLFragment()
+
+    // Add elements in schema order (after name, packageName, script from Module)
+    frag
+      .last()
+      .ele({command: this.command}).up()
+      .ele({keyCode: this.keyCode}).up()
+      .ele({keyModifier: this.keyModifier}).up()
+
+    return frag
+  }
+}

package/src/modules/Mfile.js

@@ -0,0 +1,16 @@
+const Mfile = new Object()
+
+Mfile.FIELDS = Object.freeze([
+  "package", "title", "description", "version", "author", "icon",
+  "dependencies", "outputFile",
+])
+
+Mfile.MFILE_TO_CONFIG = Object.freeze(new Map([
+  ["package", "mpackage"],
+  ["author", "author"],
+  ["icon", "icon"],
+  ["description", "description"],
+  ["version", "version"],
+]))
+
+export default Mfile