speechflow 1.3.1 → 1.4.0

package/{src → speechflow-cli/src}/speechflow.ts

@@ -11,6 +11,7 @@ import Stream            from "node:stream"
 import { EventEmitter }  from "node:events"
 import http              from "node:http"
 import * as HAPI         from "@hapi/hapi"
+import Inert             from "@hapi/inert"
 import WebSocket         from "ws"
 import HAPIWebSocket     from "hapi-plugin-websocket"
 import HAPIHeader        from "hapi-plugin-header"
@@ -32,7 +33,7 @@ import chalk             from "chalk"
 
 /*  internal dependencies  */
 import SpeechFlowNode    from "./speechflow-node"
-import pkg               from "../package.json"
+import pkg               from "../../package.json"
 
 /*  central CLI context  */
 let cli: CLIio | null = null
@@ -67,6 +68,7 @@ type wsPeerInfo = {
             "[-a|--address <ip-address>] " +
             "[-p|--port <tcp-port>] " +
             "[-C|--cache <directory>] " +
+            "[-d|--dashboard <type>:<id>:<name>[,...]] " +
             "[-e|--expression <expression>] " +
             "[-f|--file <file>] " +
             "[-c|--config <id>@<yaml-config-file>] " +
@@ -125,6 +127,15 @@ type wsPeerInfo = {
             default:  path.join(dataDir, "cache"),
             describe: "directory for cached files (primarily AI model files)"
         })
+        .option("d", {
+            alias:    "dashboard",
+            type:     "string",
+            array:    false,
+            coerce,
+            nargs:    1,
+            default:  "",
+            describe: "list of dashboard block types and names"
+        })
         .option("e", {
             alias:    "expression",
             type:     "string",
@@ -176,6 +187,21 @@ type wsPeerInfo = {
         logPrefix: pkg.name
     })
 
+    /*  catch uncaught exceptions  */
+    process.on("uncaughtException", (err) => {
+        cli!.log("error", `uncaught exception: ${err.message}`)
+        process.exit(1)
+    })
+
+    /*  catch unhandled promise rejections  */
+    process.on("unhandledRejection", (reason) => {
+        if (reason instanceof Error)
+            cli!.log("error", `unhandled rejection: ${reason.message}`)
+        else
+            cli!.log("error", `unhandled rejection: ${reason}`)
+        process.exit(1)
+    })
+
     /*  provide startup information  */
     cli.log("info", `starting SpeechFlow ${pkg["x-stdver"]} (${pkg["x-release"]})`)
 
@@ -185,21 +211,6 @@ type wsPeerInfo = {
         for (const key of Object.keys(result.parsed))
             cli.log("info", `loaded environment variable "${key}" from ".env" files`)
 
-    /*  handle uncaught exceptions  */
-    process.on("uncaughtException", async (err: Error) => {
-        cli!.log("warning", `process crashed with a fatal error: ${err} ${err.stack}`)
-        process.exit(1)
-    })
-
-    /*  handle unhandled promise rejections  */
-    process.on("unhandledRejection", async (reason, promise) => {
-        if (reason instanceof Error)
-            cli!.log("error", `promise rejection not handled: ${reason.message}: ${reason.stack}`)
-        else
-            cli!.log("error", `promise rejection not handled: ${reason}`)
-        process.exit(1)
-    })
-
     /*  sanity check usage  */
     let n = 0
     if (typeof args.e === "string" && args.e !== "") n++
@@ -220,7 +231,16 @@ type wsPeerInfo = {
             throw new Error("invalid configuration file specification (expected \"<id>@<yaml-config-file>\")")
         const [ , id, file ] = m
         const yaml = await cli.input(file, { encoding: "utf8" })
-        const obj: any = jsYAML.load(yaml)
+        let obj: any
+        try {
+            obj = jsYAML.load(yaml)
+        }
+        catch (err) {
+            if (err instanceof Error)
+                throw new Error(`failed to parse YAML configuration: ${err.message}`)
+            else
+                throw new Error(`failed to parse YAML configuration: ${err}`)
+        }
         if (obj[id] === undefined)
             throw new Error(`no such id "${id}" found in configuration file`)
         config = obj[id] as string
@@ -308,7 +328,14 @@ type wsPeerInfo = {
         for (const name of Object.keys(nodes)) {
             cli!.log("info", `gathering status of node <${name}>`)
             const node = new nodes[name](name, cfg, {}, [])
-            const status = await node.status()
+            const status = await Promise.race<{ [ key: string ]: string | number }>([
+                node.status(),
+                new Promise<never>((resolve, reject) => setTimeout(() =>
+                    reject(new Error("timeout")), 10 * 1000))
+            ]).catch((err: Error) => {
+                cli!.log("warning", `[${node.id}]: failed to gather status of node <${node.id}>: ${err.message}`)
+                return {} as { [ key: string ]: string | number }
+            })
             if (Object.keys(status).length > 0) {
                 let first = true
                 for (const key of Object.keys(status)) {
@@ -336,12 +363,9 @@ type wsPeerInfo = {
         ast = flowlink.compile(config)
     }
     catch (err) {
-        if (err instanceof Error && err.name === "FlowLinkError")
-            cli!.log("error", `failed to parse SpeechFlow configuration: ${err.toString()}"`)
-        else if (err instanceof Error)
-            cli!.log("error", `failed to parse SpeechFlow configuration: ${err.message}"`)
-        else
-            cli!.log("error", "failed to parse SpeechFlow configuration: internal error")
+        const errorMsg = err instanceof Error && err.name === "FlowLinkError"
+            ? err.toString() : (err instanceof Error ? err.message : "internal error")
+        cli!.log("error", `failed to parse SpeechFlow configuration: ${errorMsg}`)
         process.exit(1)
     }
     try {
@@ -358,10 +382,11 @@ type wsPeerInfo = {
                     throw new Error(`unknown node <${id}>`)
                 let node: SpeechFlowNode
                 try {
-                    let num = nodeNums.get(nodes[id]) ?? 0
-                    nodeNums.set(nodes[id], ++num)
+                    const NodeClass = nodes[id]
+                    let num = nodeNums.get(NodeClass) ?? 0
+                    nodeNums.set(NodeClass, ++num)
                     const name = num === 1 ? id : `${id}:${num}`
-                    node = new nodes[id](name, cfg, opts, args)
+                    node = new NodeClass(name, cfg, opts, args)
                 }
                 catch (err) {
                     /*  fatal error  */
@@ -384,12 +409,9 @@ type wsPeerInfo = {
         })
     }
     catch (err) {
-        if (err instanceof Error && err.name === "FlowLinkError")
-            cli!.log("error", `failed to materialize SpeechFlow configuration: ${err.toString()}`)
-        else if (err instanceof Error)
-            cli!.log("error", `failed to materialize SpeechFlow configuration: ${err.message}`)
-        else
-            cli!.log("error", "failed to materialize SpeechFlow configuration: internal error")
+        const errorMsg = err instanceof Error && err.name === "FlowLinkError"
+            ? err.toString() : (err instanceof Error ? err.message : "internal error")
+        cli!.log("error", `failed to materialize SpeechFlow configuration: ${errorMsg}`)
         process.exit(1)
     }
 
@@ -438,9 +460,13 @@ type wsPeerInfo = {
         /*  open node  */
         cli!.log("info", `open node <${node.id}>`)
         node.setTimeZero(timeZero)
-        await node.open().catch((err: Error) => {
-            cli!.log("error", `[${node.id}]: ${err.message}`)
-            throw new Error(`failed to open node <${node.id}>`)
+        await Promise.race<void>([
+            node.open(),
+            new Promise<never>((resolve, reject) => setTimeout(() =>
+                reject(new Error("timeout")), 10 * 1000))
+        ]).catch((err: Error) => {
+            cli!.log("error", `[${node.id}]: failed to open node <${node.id}>: ${err.message}`)
+            throw new Error(`failed to open node <${node.id}>: ${err.message}`)
         })
     }
 
@@ -462,9 +488,10 @@ type wsPeerInfo = {
         }
     }
 
-    /*  graph processing: PASS 6: track stream finishing  */
+    /*  graph processing: PASS 5: track stream finishing  */
     const activeNodes  = new Set<SpeechFlowNode>()
     const finishEvents = new EventEmitter()
+    finishEvents.setMaxListeners(graphNodes.size + 10)
     for (const node of graphNodes) {
         if (node.stream === null)
             throw new Error(`stream of node <${node.id}> still not initialized`)
@@ -512,9 +539,12 @@ type wsPeerInfo = {
             throw new Error(`external request failed: no such node <${name}>`)
         }
         else {
-            await foundNode.receiveRequest(args).catch((err: Error) => {
-                cli!.log("warning", `external request to node <${name}> failed: ${err}`)
-                throw new Error(`external request to node <${name}> failed: ${err}`)
+            await Promise.race<void>([
+                foundNode.receiveRequest(args),
+                new Promise<never>((resolve, reject) => setTimeout(() =>
+                    reject(new Error("timeout")), 10 * 1000))
+            ]).catch((err: Error) => {
+                cli!.log("warning", `external request to node <${name}> failed: ${err.message}`)
             })
         }
     }
@@ -525,6 +555,7 @@ type wsPeerInfo = {
         address: args.a,
         port:    args.p
     })
+    await hapi.register({ plugin: Inert })
     await hapi.register({ plugin: HAPIHeader, options: { Server: `${pkg.name}/${pkg.version}` } })
     await hapi.register({ plugin: HAPIWebSocket })
     hapi.events.on("response", (request: HAPI.Request) => {
@@ -558,6 +589,29 @@ type wsPeerInfo = {
                 cli!.log("error", `HAPI: log: ${err}`)
         }
     })
+    hapi.route({
+        method: "GET",
+        path: "/{param*}",
+        handler: {
+            directory: {
+                path: path.join(__dirname, "../../speechflow-ui-db/dst"),
+                redirectToSlash: true,
+                index: true
+            }
+        }
+    })
+    hapi.route({
+        method: "GET",
+        path:   "/api/dashboard",
+        handler: (request: HAPI.Request, h: HAPI.ResponseToolkit) => {
+            const config = []
+            for (const block of args.d.split(",")) {
+                const [ type, id, name ] = block.split(":")
+                config.push({ type, id, name })
+            }
+            return h.response(config).code(200)
+        }
+    })
     hapi.route({
         method: "GET",
         path:   "/api/{req}/{node}/{params*}",
@@ -565,10 +619,13 @@ type wsPeerInfo = {
         },
         handler: (request: HAPI.Request, h: HAPI.ResponseToolkit) => {
             const peer = request.info.remoteAddress
+            const params = request.params.params as string ?? ""
+            if (params.length > 1000)
+                return h.response({ response: "ERROR", data: "parameters too long" }).code(400)
             const req = {
                 request: request.params.req,
                 node:    request.params.node,
-                args:    (request.params.params as string ?? "").split("/").filter((seg) => seg !== "")
+                args:    params.split("/").filter((seg) => seg !== "")
             }
             cli!.log("info", `HAPI: peer ${peer}: GET: ${JSON.stringify(req)}`)
             return consumeExternalRequest(req).then(() => {
@@ -583,9 +640,10 @@ type wsPeerInfo = {
         path:   "/api",
         options: {
             payload: {
-                output: "data",
-                parse:  true,
-                allow:  "application/json"
+                output:   "data",
+                parse:    true,
+                allow:    "application/json",
+                maxBytes: 1 * 1024 * 1024
             },
             plugins: {
                 websocket: {
@@ -601,8 +659,10 @@ type wsPeerInfo = {
                     },
                     disconnect: (args: any) => {
                         const ctx: wsPeerCtx = args.ctx
+                        const ws: WebSocket = args.ws
                         const peer = ctx.peer
                         wsPeers.delete(peer)
+                        ws.removeAllListeners()
                         cli!.log("info", `HAPI: WebSocket: disconnect: peer ${peer}`)
                     }
                 }
@@ -623,14 +683,35 @@ type wsPeerInfo = {
         }
     })
     await hapi.start()
-    cli!.log("info", `HAPI: started REST/WebSocket network service: http://${args.address}:${args.port}`)
+    cli!.log("info", `HAPI: started REST/WebSocket network service: http://${args.a}:${args.p}`)
 
     /*  hook for sendResponse method of nodes  */
     for (const node of graphNodes) {
         node.on("send-response", (args: any[]) => {
             const data = JSON.stringify({ response: "NOTIFY", node: node.id, args })
             for (const [ peer, info ] of wsPeers.entries()) {
-                cli!.log("info", `HAPI: peer ${peer}: ${data}`)
+                cli!.log("debug", `HAPI: remote peer ${peer}: sending ${data}`)
+                if (info.ws.readyState === WebSocket.OPEN)
+                    info.ws.send(data)
+            }
+        })
+    }
+
+    /*  hook for dashboardInfo method of nodes  */
+    for (const node of graphNodes) {
+        node.on("dashboard-info", (info: {
+            type: string,
+            id:   string,
+            kind: "final" | "intermediate",
+            value: string | number
+        }) => {
+            const data = JSON.stringify({
+                response: "DASHBOARD",
+                node:     "",
+                args:     [ info.type, info.id, info.kind, info.value ]
+            })
+            for (const [ peer, info ] of wsPeers.entries()) {
+                cli!.log("debug", `HAPI: dashboard peer ${peer}: send ${data}`)
                 info.ws.send(data)
             }
         })
@@ -653,9 +734,39 @@ type wsPeerInfo = {
             cli!.log("warning", `**** received signal ${signal} -- shutting down service ****`)
 
         /*  shutdown HAPI service  */
-        cli!.log("info", `HAPI: stopping REST/WebSocket network service: http://${args.address}:${args.port}`)
+        cli!.log("info", `HAPI: stopping REST/WebSocket network service: http://${args.a}:${args.p}`)
         await hapi.stop({ timeout: 2000 })
 
+        /*  clear WebSocket connections  */
+        if (wsPeers.size > 0) {
+            cli!.log("info", "HAPI: closing WebSocket connections")
+            const closePromises: Promise<void>[] = []
+            for (const [ peer, info ] of wsPeers.entries()) {
+                closePromises.push(new Promise<void>((resolve, reject) => {
+                    if (info.ws.readyState !== WebSocket.OPEN)
+                        resolve()
+                    else {
+                        const timeout = setTimeout(() => {
+                            reject(new Error(`timeout for peer ${peer}`))
+                        }, 2 * 1000)
+                        info.ws.once("close", () => {
+                            clearTimeout(timeout)
+                            resolve()
+                        })
+                        info.ws.close()
+                    }
+                }))
+            }
+            await Promise.race([
+                Promise.all(closePromises),
+                new Promise((resolve, reject) =>
+                    setTimeout(() => reject(new Error("timeout for all peers")), 5 * 1000))
+            ]).catch((err) => {
+                cli!.log("warning", `HAPI: WebSockets failed to close: ${err}`)
+            })
+            wsPeers.clear()
+        }
+
         /*  graph processing: PASS 1: disconnect node streams  */
         for (const node of graphNodes) {
             if (node.stream === null) {
@@ -685,8 +796,12 @@ type wsPeerInfo = {
         /*  graph processing: PASS 2: close nodes  */
         for (const node of graphNodes) {
             cli!.log("info", `close node <${node.id}>`)
-            await node.close().catch((err) => {
-                cli!.log("warning", `node <${node.id}> failed to close: ${err}`)
+            await Promise.race<void>([
+                node.close(),
+                new Promise<never>((resolve, reject) => setTimeout(() =>
+                    reject(new Error("timeout")), 10 * 1000))
+            ]).catch((err: Error) => {
+                cli!.log("warning", `node <${node.id}> failed to close: ${err.message}`)
             })
         }
 
@@ -705,6 +820,12 @@ type wsPeerInfo = {
             graphNodes.delete(node)
         }
 
+        /*  clear event emitters  */
+        finishEvents.removeAllListeners()
+
+        /*  clear active nodes  */
+        activeNodes.clear()
+
         /*  terminate process  */
         if (signal === "finished") {
             cli!.log("info", "terminate process (exit code 0)")
@@ -715,24 +836,38 @@ type wsPeerInfo = {
             process.exit(1)
         }
     }
+
+    /*  hook into regular finish  */
     finishEvents.on("finished", () => { shutdown("finished") })
+
+    /*  hook into process signals  */
     process.on("SIGINT",        () => { shutdown("SIGINT")   })
     process.on("SIGUSR1",       () => { shutdown("SIGUSR1")  })
     process.on("SIGUSR2",       () => { shutdown("SIGUSR2")  })
     process.on("SIGTERM",       () => { shutdown("SIGTERM")  })
+
+    /*  re-hook into uncaught exception handler  */
+    process.removeAllListeners("uncaughtException")
     process.on("uncaughtException", (err) => {
-        cli!.log("error", `uncaught exception: ${err}`)
+        cli!.log("error", `uncaught exception: ${err.message}`)
         shutdown("exception")
     })
+
+    /*  re-hook into unhandled promise rejection handler  */
+    process.removeAllListeners("unhandledRejection")
     process.on("unhandledRejection", (reason) => {
-        cli!.log("error", `unhandled rejection: ${reason}`)
+        if (reason instanceof Error)
+            cli!.log("error", `unhandled rejection: ${reason.message}`)
+        else
+            cli!.log("error", `unhandled rejection: ${reason}`)
         shutdown("exception")
     })
 })().catch((err: Error) => {
+    /*  top-level exception handling  */
     if (cli !== null)
-        cli.log("error", err.message)
+        cli.log("error", `${err.message}:\n${err.stack}`)
     else
-        process.stderr.write(`${pkg.name}: ${chalk.red("ERROR")}: ${err.message} ${err.stack}\n`)
+        process.stderr.write(`${pkg.name}: ${chalk.red("ERROR")}: ${err.message}\n${err.stack}\n`)
     process.exit(1)
 })
 

package/speechflow-ui-db/etc/eslint.mjs

@@ -0,0 +1,106 @@
+/*
+**  SpeechFlow - Speech Processing Flow Graph
+**  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+
+import pluginJs      from "@eslint/js"
+import pluginStd     from "neostandard"
+import pluginN       from "eslint-plugin-n"
+import pluginImport  from "eslint-plugin-import"
+import pluginPromise from "eslint-plugin-promise"
+import pluginVue     from "eslint-plugin-vue"
+import pluginTS      from "typescript-eslint"
+import globals       from "globals"
+import parserTS      from "@typescript-eslint/parser"
+import parserVue     from "vue-eslint-parser"
+
+export default [
+    pluginJs.configs.recommended,
+    ...pluginTS.configs.strict,
+    ...pluginTS.configs.stylistic,
+    ...pluginStd({
+        ignores: pluginStd.resolveIgnoresFromGitignore()
+    }),
+    ...pluginVue.configs["flat/recommended"],
+    {
+        plugins: {
+            "n":       pluginN,
+            "import":  pluginImport,
+            "promise": pluginPromise
+        },
+        files:   [ "**/*.{vue,ts}" ],
+        ignores: [ "dst/" ],
+        languageOptions: {
+            ecmaVersion: 2022,
+            sourceType:  "module",
+            parser: parserVue,
+            parserOptions: {
+                parser: parserTS,
+                extraFileExtensions: [ ".vue" ],
+                ecmaFeatures: {
+                    jsx: false
+                }
+            },
+            globals: {
+                ...globals.browser,
+                ...globals.node,
+                ...globals.commonjs
+            }
+        },
+        rules: {
+            "curly":                                              "off",
+            "require-atomic-updates":                             "off",
+            "dot-notation":                                       "off",
+            "no-labels":                                          "off",
+            "no-useless-constructor":                             "off",
+
+            "@stylistic/indent":                                  [ "error", 4, { SwitchCase: 1 } ],
+            "@stylistic/linebreak-style":                         [ "error", "unix" ],
+            "@stylistic/semi":                                    [ "error", "never" ],
+            "@stylistic/operator-linebreak":                      [ "error", "after", { overrides: { "&&": "before", "||": "before", ":": "after" } } ],
+            "@stylistic/brace-style":                             [ "error", "stroustrup", { allowSingleLine: true } ],
+            "@stylistic/quotes":                                  [ "error", "double" ],
+
+            "@stylistic/no-multi-spaces":                         "off",
+            "@stylistic/no-multi-spaces":                         "off",
+            "@stylistic/no-multiple-empty-lines":                 "off",
+            "@stylistic/key-spacing":                             "off",
+            "@stylistic/object-property-newline":                 "off",
+            "@stylistic/space-in-parens":                         "off",
+            "@stylistic/array-bracket-spacing":                   "off",
+            "@stylistic/lines-between-class-members":             "off",
+            "@stylistic/multiline-ternary":                       "off",
+            "@stylistic/quote-props":                             "off",
+
+            "vue/html-indent":                                    "off",
+            "vue/v-bind-style":                                   [ "error", "longform" ],
+            "vue/max-attributes-per-line":                        "off",
+            "vue/html-self-closing":                              "off",
+            "vue/no-multi-spaces":                                "off",
+            "vue/html-closing-bracket-newline":                   "off",
+            "vue/html-closing-bracket-spacing":                   "off",
+            "vue/singleline-html-element-content-newline":        "off",
+            "vue/no-v-html":                                      "off",
+            "vue/v-on-style":                                     "off",
+            "vue/component-tags-order":                           "off",
+            "vue/first-attribute-linebreak":                      "off",
+            "vue/attributes-order":                               "off",
+            "vue/component-definition-name-casing":               "off",
+            "vue/block-order":                                    "off",
+
+            "@typescript-eslint/no-empty-function":               "off",
+            "@typescript-eslint/no-explicit-any":                 "off",
+            "@typescript-eslint/no-unused-vars":                  "off",
+            "@typescript-eslint/ban-ts-comment":                  "off",
+            "@typescript-eslint/no-this-alias":                   "off",
+            "@typescript-eslint/no-non-null-assertion":           "off",
+            "@typescript-eslint/consistent-type-definitions":     "off",
+            "@typescript-eslint/array-type":                      "off",
+            "@typescript-eslint/no-extraneous-class":             "off",
+            "@typescript-eslint/consistent-indexed-object-style": "off",
+            "@typescript-eslint/adjacent-overload-signatures":    "off"
+        }
+    }
+]
+

package/speechflow-ui-db/etc/htmllint.json

@@ -0,0 +1,55 @@
+{
+    "plugins": [],
+    "maxerr": false,
+    "raw-ignore-regex": false,
+    "attr-bans": [ "align", "background", "bgcolor", "border", "frameborder", "longdesc", "marginwidth", "marginheight", "scrolling", "style", "width" ],
+    "indent-delta": false,
+    "indent-style": "nonmixed",
+    "indent-width": 4,
+    "indent-width-cont": false,
+    "spec-char-escape": true,
+    "text-ignore-regex": false,
+    "tag-bans": [ "b", "i" ],
+    "tag-close": true,
+    "tag-name-lowercase": true,
+    "tag-name-match": true,
+    "tag-self-close": false,
+    "doctype-first": false,
+    "doctype-html5": false,
+    "attr-name-style": "dash",
+    "attr-name-ignore-regex": false,
+    "attr-no-dup": true,
+    "attr-no-unsafe-char": true,
+    "attr-order": false,
+    "attr-quote-style": "double",
+    "attr-req-value": true,
+    "attr-new-line": false,
+    "attr-validate": true,
+    "id-no-dup": true,
+    "id-class-no-ad": true,
+    "id-class-style": "underscore",
+    "class-no-dup": true,
+    "class-style": false,
+    "id-class-ignore-regex": false,
+    "img-req-alt": true,
+    "img-req-src": true,
+    "html-valid-content-model": true,
+    "head-valid-content-model": true,
+    "href-style": false,
+    "label-req-for": true,
+    "line-end-style": "lf",
+    "line-no-trailing-whitespace": false,
+    "line-max-len": false,
+    "line-max-len-ignore-regex": false,
+    "head-req-title": true,
+    "title-no-dup": true,
+    "title-max-len": 60,
+    "html-req-lang": false,
+    "lang-style": "case",
+    "fig-req-figcaption": false,
+    "focusable-tabindex-style": false,
+    "input-radio-req-name": true,
+    "input-req-label": false,
+    "table-req-caption": false,
+    "table-req-header": false
+}

package/speechflow-ui-db/etc/stx.conf

@@ -0,0 +1,79 @@
+##
+##  SpeechFlow - Speech Processing Flow Graph
+##  Copyright (c) 2024-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+##  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+##
+
+#   (internal): create patch set for NPM dependencies
+patch-make
+    npm shrinkwrap && \
+    patch-package --patch-dir package.d \
+        "@typescript-eslint/typescript-estree" \
+        htmllint-cli && \
+    shx rm -f npm-shrinkwrap.json
+
+#   (internal): apply patch set for NPM dependencies
+patch-apply
+    patch-package --patch-dir package.d
+
+#   static code analysis (continuous file watching)
+lint-watch
+    nodemon --exec "npm start lint" --watch src --ext html,styl,js,ts,vue
+
+#   static code analysis
+lint : lint-vue-tsc lint-eslint lint-stylelint lint-htmllint
+
+#   static code analysis (Vue language)
+lint-vue-tsc
+    vue-tsc --project etc/tsc-client.json --noEmit
+
+#   static code analysis (TypeScript language)
+lint-eslint
+    eslint --config etc/eslint.mjs src/**/*.vue src/**/*.ts
+
+#   static code analysis (CSS/Stylus languages)
+lint-stylelint
+    stylelint --config etc/stylelint.yaml src/**/*.styl src/**/*.vue
+
+#   static code analysis (HTML language)
+lint-htmllint
+    htmllint --rc etc/htmllint.json src/**/*.html
+
+#   build components for production
+build
+    npm start build-client
+
+#   build components for development
+build-dev
+    npm start build-client-dev
+
+#   build client components for production
+build-client
+    vite --config etc/vite-client.mts build --mode production
+
+#   build client components for development
+build-client-dev
+    vite --config etc/vite-client.mts build --mode development
+
+#   build client components for development (continuous file watching)
+build-client-dev-watch
+    cross-env NODE_OPTIONS="--max-old-space-size=4096" \
+        vite --config etc/vite-client.mts build --mode development --watch
+
+#   run server
+server
+    serve -d --listen 12345 --single dst
+
+#   remove all development-only NPM dependencies
+prune
+    npm prune --omit=dev
+
+#   remove all generated artifacts (reverse of "npm start build")
+clean
+    shx rm -rf dst-stage1 dst-stage2
+
+#   remove all generated artifacts (reverse of "npm install" and "npm start build")
+clean:dist : clean
+    shx rm -f package-lock.json && \
+    shx rm -rf node_modules
+