@rse/ase 0.0.31 → 0.0.32

package/plugin/node_modules/@rse/stx/src/stx-logo.svg

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 882.64 329.75">
+  <!-- Generator: Adobe Illustrator 29.6.0, SVG Export Plug-In . SVG Version: 2.1.1 Build 207)  -->
+  <defs>
+    <style>
+      .st0 {
+        fill: #ccc;
+      }
+
+      .st1 {
+        fill: #666;
+      }
+
+      .st2 {
+        fill: #369;
+      }
+
+      .st3 {
+        fill: #999;
+      }
+    </style>
+  </defs>
+  <g>
+    <path class="st2" d="M606.01,12.15l-12.18,65.6,22.09,1.45,29.47,60.57-63.27-1.57-13.12,63.72c-1.41,7.5-3.28,19.68-3.28,26.24,0,9.84,4.22,17.81,18.74,17.81,5.62,0,32.27-2.6,38.83-3.07l-54.02,66.32c-9.84,3.75-4.95,4.22-20.42,4.22-43.58,0-65.13-20.62-65.13-51.54,0-12.65,1.41-24.83,4.69-42.64l18.66-93.4h-20.46l1.34-48.1h28.11l8.9-46.86,81.06-18.74Z"/>
+    <path class="st2" d="M309.1,239.86c14.06,6.56,40.77,16.87,64.66,16.4,15.93,0,22.49-6.09,22.49-13.59,0-8.43-7.03-14.99-27.18-23.9-26.24-12.65-51.54-31.86-51.54-62.32,0-51.07,44.98-82.94,108.71-82.94,29.52,0,70.19-.24,91.46.76l-5.73,57.29c-32.74-2.46-66.3-3.27-89.01-.42-14.88,1.87-24.83,4.69-24.83,14.06,0,6.56,8.43,13.59,26.24,21.55,24.83,11.71,55.29,29.05,55.29,63.72,0,54.82-47.32,83.4-113.39,83.4-30.92,0-60.91-7.97-75.91-18.74l18.74-55.29Z"/>
+    <path class="st2" d="M709.34,77.86l9.84,27.65c7.97,20.15,11.71,31.86,14.53,39.83h1.41c8.43-12.18,14.99-23.9,24.37-37.95l18.27-29.52h91.37l-96.99,111.99,52.95,118.55h-87.62l-10.78-30.46c-6.09-16.4-10.31-29.05-14.06-42.17h-1.41c-6.09,10.78-12.65,22.96-22.96,40.3l-19.68,32.33h-91.84l99.34-119.48-54.35-111.05h87.62Z"/>
+  </g>
+  <path class="st1" d="M147.29,186.89c1.5,5.13,3.57,10.07,6.19,14.71l-7.48,9.43c-2.44,3.08-2.17,7.48.58,10.25l12.88,12.88c2.78,2.78,7.17,3.02,10.25.58l9.37-7.42c4.82,2.78,9.95,4.94,15.29,6.47l1.4,12.05c.46,3.91,3.75,6.84,7.66,6.84h18.22c3.91,0,7.2-2.93,7.66-6.84l1.34-11.63c5.74-1.5,11.23-3.72,16.39-6.62l9.06,7.17c3.08,2.44,7.48,2.17,10.25-.58l12.88-12.88c2.78-2.78,3.02-7.17.58-10.25l-7.05-8.94c2.93-5.07,5.22-10.47,6.74-16.11l10.86-1.25c3.91-.46,6.84-3.75,6.84-7.66v-18.22c0-3.91-2.93-7.2-6.84-7.66l-10.71-1.25c-1.47-5.58-3.66-10.92-6.47-15.93l6.59-8.33c2.44-3.08,2.17-7.48-.58-10.25l-12.85-12.85c-2.78-2.78-7.17-3.02-10.25-.58l-8.09,6.41c-5.25-3.08-10.86-5.43-16.75-7.02l-1.22-10.47c-.46-3.91-3.75-6.84-7.66-6.84h-18.22c-3.91,0-7.2,2.93-7.66,6.84l-1.22,10.47c-6.04,1.62-11.81,4.06-17.18,7.26l-8.39-6.65c-3.08-2.44-7.48-2.17-10.25.58l-12.88,12.88c-2.78,2.78-3.02,7.17-.58,10.25l7.02,8.88c-2.81,5.07-4.94,10.47-6.35,16.08l-11.23,1.28c-3.91.46-6.84,3.75-6.84,7.66v18.22c0,3.91,2.93,7.2,6.84,7.66l11.84,1.37ZM213.29,137.61c16.6,0,30.12,13.52,30.12,30.12s-13.52,30.12-30.12,30.12-30.12-13.52-30.12-30.12,13.52-30.12,30.12-30.12Z"/>
+  <path class="st3" d="M139.37,199.72l-9.26-8.52c-2.85-2.63-7.22-2.69-10.13-.15l-5.52,4.75c-4.39-2.35-9.08-4.08-13.95-5.17l-1.18-7.38c-.6-3.81-4-6.58-7.85-6.44l-12.58.54c-3.86.17-7.01,3.19-7.29,7.05l-.56,7.43c-4.89,1.53-9.53,3.72-13.81,6.53l-6.16-4.48c-3.14-2.27-7.47-1.84-10.09,1.01l-8.52,9.32c-2.63,2.85-2.69,7.22-.15,10.13l5.3,6.15c-2.1,4.25-3.67,8.73-4.66,13.36l-8,1.28c-3.81.6-6.58,4-6.44,7.85l.54,12.58c.17,3.86,3.19,7.01,7.05,7.29l8.56.64c1.38,4.15,3.26,8.11,5.58,11.84l-5.09,7.02c-2.27,3.14-1.84,7.47,1.01,10.09l9.26,8.52c2.85,2.63,7.22,2.69,10.13.15l6.53-5.62c4.03,2.1,8.3,3.71,12.72,4.75l1.37,8.67c.6,3.81,4,6.58,7.85,6.44l12.58-.54c3.86-.17,7.01-3.19,7.29-7.05l.63-8.4c4.64-1.42,9.06-3.43,13.17-5.98l6.73,4.87c3.14,2.27,7.47,1.84,10.09-1.01l8.52-9.26c2.62-2.85,2.69-7.22.15-10.13l-5.33-6.15c2.23-4.24,3.91-8.75,4.97-13.41l7.69-1.23c3.81-.6,6.58-4,6.44-7.85l-.54-12.58c-.17-3.86-3.19-7.01-7.05-7.29l-7.64-.57c-1.4-4.52-3.35-8.82-5.84-12.83l4.44-6.1c2.33-3.14,1.91-7.49-.95-10.12ZM89.08,270.17c-13.59.59-25.11-10.01-25.67-23.6-.59-13.59,10.01-25.11,23.6-25.67,13.59-.59,25.11,10.01,25.67,23.6.59,13.59-10.01,25.11-23.6,25.67Z"/>
+  <path class="st0" d="M37.38,130.53c-3.32,1.97-4.65,6.15-3.05,9.68l3.16,7.05c1.57,3.54,5.56,5.33,9.25,4.16l5.46-1.72c2.31,2.73,4.91,5.16,7.8,7.25l-1.43,5.64c-.95,3.77,1.04,7.62,4.67,9l7.22,2.74c3.63,1.38,7.69-.16,9.49-3.62l2.65-5.09c3.7.37,7.41.31,11.05-.24l3.01,5.06c1.97,3.32,6.15,4.65,9.68,3.05l7.05-3.16c3.54-1.57,5.33-5.56,4.16-9.25l-1.7-5.34c3.09-2.47,5.81-5.31,8.18-8.49l5.33,1.34c3.77.95,7.62-1.04,9-4.67l2.74-7.22c1.38-3.63-.16-7.69-3.62-9.49l-4.75-2.48c.42-3.89.33-7.79-.28-11.64l4.38-2.6c3.32-1.97,4.65-6.15,3.05-9.68l-3.16-7.05c-1.57-3.54-5.56-5.33-9.25-4.16l-4.76,1.49c-2.42-2.98-5.21-5.66-8.28-7.94l1.21-4.73c.95-3.77-1.04-7.62-4.67-9l-7.22-2.74c-3.63-1.38-7.69.16-9.49,3.62l-2.16,4.13c-4.04-.45-8.1-.35-12.11.29l-2.46-4.14c-1.98-3.32-6.15-4.65-9.68-3.05l-7.05,3.16c-3.54,1.57-5.33,5.56-4.16,9.25l1.45,4.58c-3.22,2.63-6.07,5.7-8.47,9.1l-4.77-1.22c-3.77-.95-7.62,1.04-9,4.67l-2.76,7.26c-1.38,3.63.16,7.69,3.62,9.49l4.73,2.45c-.31,3.84-.16,7.71.53,11.53l-4.62,2.74ZM78.94,101.67c10.1-4.54,22,0,26.54,10.11,4.54,10.1,0,22-10.11,26.54-10.1,4.54-22,0-26.54-10.11-4.54-10.1,0-22,10.11-26.54Z"/>
+</svg>

package/plugin/node_modules/@rse/stx/src/stx.md

@@ -0,0 +1,293 @@
+
+# stx(1) -- Simple Task Execution
+
+## SYNOPSIS
+
+`stx`
+\[`-h`|`--help`\]
+\[`-V`|`--version`\]
+\[`-l`|`--log` *log-level*\]
+\[`-v`|`--verbose` *verbosity-level*\]
+\[`-c`|`--config` *config-file*\]
+\[`-e`|`--env` *key*`=`*val*\]
+\[`-p`|`--prefix` *task-name-prefix*\]
+\[`-s`|`--single`\]
+\[*task-name* [*task-option* \[...\]\] \[...\]
+
+## DESCRIPTION
+
+`stx`(1), *Simple Task Execution*, is a small command-line tool to run
+small scripts to perform certain tasks. It is intended to be used inside
+a software build process, especially in one based on *Node Package
+Manager (NPM)* scripts. `stx`(1) is inspired by and somewhat resembles
+good-old Unix `make`(1), but it is not intended as a direct replacement for it.
+
+## OPTIONS
+
+The following command-line options and arguments exist:
+
+- \[`-h`|`--help`\]:
+  Show program usage information only.
+
+- \[`-V`|`--version`\]:
+  Show program version information only.
+
+- \[`-l`|`--log *logging-level*`\]:
+  Set logging level for tracing the execution processing:
+  `error`, `warning`, `info` or `debug`.
+  The default is `warning`.
+
+- \[`-v`|`--verbose *verbosity-level*`\]:
+  Set verbosity level for showing script information:
+  `4` (separator, comment, command, and script),
+  `3` (comment, command, and script).
+  `2` (command and script),
+  `1` (script only), or
+  `0` (none).
+  The default is `0`.
+
+- \[`-v`|`--version`\]:
+  Show executed scripts before execution.
+
+- \[`-c`|`--config` *config-file*\]:
+  Use *config-file* for the configuration. The default is the
+  relative path `etc/stx.conf` from the current working directory.
+
+- \[`-e`|`--env` *key*`=`*val*\]:
+  Extend the process environment with an additional variable of name
+  *key* and value *val*. This is for convenience reasons as passing
+  environment variables externally is platform and shell specific.
+
+- \[`-p`|`--prefix` *task-name-prefix*\]:
+  Prefix all passed *task-name* arguments with *task-name-prefix* before
+  trying to execute them. This is for convenience reasons to
+  not having to repeat common prefixes of related tasks.
+
+- \[`-s`|`--single`\]:
+  Treat all trailing command line arguments after the first *task-name*
+  as arguments to a single task. The default is to treat all arguments
+  which do not stark with `-` or `+` as separate task names.
+
+- \[*task-name* \[*task-option* \[...\]\] \[...\]
+  One or more requests to execute a task named *task-name*
+  with zero or more passed options *task-option*. The
+  *task-name* has to match the regular expression
+  `@?[a-zA-Z_.](?:[a-zA-Z0-9_:.-]+[a-zA-Z0-9_]|[a-zA-Z0-9_]+)`.
+  Hence, examples of *task-name* are `foo`, `foo-bar`, `Foo.Bar`,
+  `FOO:BAR:QUUX`, etc. The *task-option* has to start with a hyphen
+  (`-`). If a command line argument starts with a plus (`+`) this
+  prefix is stripped and the argument is NOT treated as a following
+  *task-name*, even if option `-s`|`--single` is not enabled.
+  The *task-name* arguments are split into segments (separated
+  by the regular expression `[_.:-]`) and then each segment is
+  matched with multiple strategies: exact match, case-insensite
+  match, fuzzy match and prefix match.
+
+## CONFIGURATION
+
+The configuration file of `stx`(1) has to match to the following PEG-style grammar:
+
+```txt
+<config>        ::= <empty-line> | <comment-block> | <config-block>
+
+<empty-lines>   ::= /(\s*\r?\n)+/
+<comment-block> ::= /(?:#.*?\r?\n)+/
+<config-block>  ::= <specification> <script>
+
+<specification> ::= <target>+ (":" <source>+)? <constraint>* <language>?
+<script>        ::= /(\s+\S.*?\r?\n)+/
+
+<target>        ::= <task> | <file>
+<source>        ::= (<task> | <file>) "?"?
+<constraint>    ::= "[" "!"? /.+?/ "]"
+<language>      ::= "{" /.+?/ "}"
+
+<task>          ::= <name>
+<file>          ::= "@" <name>
+
+<name>          ::= <quoted> | <bareword>
+
+<quoted>        ::= /"((?:\\"|[^\r\n])*)"/
+<bareword>      ::= <segment> (<sep> <segment>)*
+
+<segment>       ::= /[a-zA-Z][a-zA-Z0-9]*/
+<sep>           ::= /[_.:-]/
+```
+
+The configuration structure and semantics are:
+
+- Each configuration consists of one or more configuration blocks,
+  each starting with a single non-indented specification line,
+  followed by one or more indented script lines.
+
+- Specifications consist of one or more targets, zero
+  or more sources, zero or more platform constraints
+  and an optional language.
+
+- Targets and sources are either task name definitions and task
+  name references or (when prefixed with `@`) output file definitions
+  and inputs file references. A source postfix of `?` denotes
+  an optional source, which for a task reference means the task
+  execution is allowed to fail and for a file reference means
+  the file is allowed to not exist.
+
+- Constraints are key/value and allow glob-style matches of the value
+  (optionally negated by a `!` prefix) for the keys `machine` (CPU
+  architectures "arm", "arm64", "ia32", "loong64", "mips", "mipsel",
+  "ppc64", "riscv64", "s390x", and "x64" -- see Node.js `os.machine()`
+  for details), `platform` (operating system "aix", "darwin",
+  "freebsd", "linux", "openbsd", "sunos", and "win32" -- see Node.js
+  `os.platform()` for details) and `hostname` (hostname of system -- see
+  Node.js `os.hostname()` for details). Constraints act as filters for
+  the configuration blocks: if a constraint does not match the current
+  platform, the configuration block is silently ignored.
+
+## LANGUAGES
+
+`stx`(1) ships with direct support for the following two built-in programming languages:
+
+- `js`: *JavaScript*, by calling the `node`(1)
+  executable `stx`(1) is executed itself. The potential NPM peer
+  packages `concurrently`, `shelljs`, `zx`, and `dax-sh` can be
+  recommended in order to write platform-agnostic scripts. Use this
+  language for maximum scripting flexibility and portability.
+
+- `ts`: *TypeScript*, by calling the `node`(1)
+  executable `stx`(1) is executed itself. The potential NPM peer
+  packages `concurrently`, `shelljs`, `zx`, and `dax-sh` can be
+  recommended in order to write platform-agnostic scripts. Use this
+  language for maximum scripting flexibility and portability.
+
+`stx`(1) ships with direct support for the following typical shell languages:
+
+- `shell`: *Shell Abstraction*, by either
+  calling `sh`(1) under non-Windows platforms, or calling `cmd` under
+  Windows platforms. Additionally, for simple cross-plaform scripting,
+  under Windows platforms the following replacements are automatically
+  done on the script: line endings are converted to CR-LF,
+  line continuations `\\` are converted to `^` and variable references
+  like `$XXX` or `${XXX}` are converted to `%XXX%`. If you want
+  plain *Bourne-Shell* or *Batch Command*, use the languages
+  `sh` and `cmd` instead. Use this language for some scripting
+  portability.
+
+- `sh`: *Bourne-Shell*, by calling the `sh`(1) executable.
+  This is usually available under non-Windows platforms like
+  macOS, Linux, or FreeBSD only. Use this language for
+  Unix scripting without portability demands.
+
+- `cmd`: *Batch Command*, by calling the `cmd` executable.
+  This is available under Windows platform only. Use this
+  language for Windows scripting without portability demands.
+
+Additionally, you can use an arbitrary language as long as a particular
+script interpreting program is in `$PATH`. Popular Unix shell examples
+are `bash`, `zsh`, `fish`, `nushell`, `xonsh`, or `elvish`. Popular
+Windows shell example is `powershell`.
+
+## EXAMPLE
+
+An example configuration is (this is actually the build procedure of `stx`(1) itself):
+
+```txt
+#   static code analysis (linting)
+lint
+    eslint --config etc/eslint.mjs src/**/*.ts && \
+    markdownlint-cli2 --config etc/.markdownlint.yaml src/**/*.md
+
+#   static code analysis (linting) with file watching
+lint-watch
+    nodemon --exec "npm start lint" --watch src --ext ts
+
+#   code compilation/transpiling (building)
+build-watch
+    nodemon --exec "npm start build" --watch src --ext ts
+
+#   build entire project
+build : lint build-cmd build-man
+
+#   build command program
+build-cmd
+    vite --config etc/vite.mts build --mode production
+
+#   build manual page
+build-man
+    remark --quiet --use remark-man --output dst-stage2/stx.1 src/stx.md
+
+#   build packaging (self-contained executables) -- fallback
+build-pkg [hostname=!en4*]
+    echo "(packaging skipped)"
+
+#   build packaging (self-contained executables)
+build-pkg [hostname=en4*]
+    shx mkdir -p dst-stage2/@rse dst-stage3
+    cd dst-stage2
+    rm -f @rse/stx-*
+    targets="node24-linux-x64,node24-linux-arm64"
+    targets="$targets,node24-win-x64,node24-win-arm64"
+    targets="$targets,node24-macos-x64,node24-macos-arm64"
+    pkg --sea --public -c ../package.json -t "$targets" stx.js
+    shx mv @rse/stx-linux-x64     ../dst-stage3/stx-lnx-x64     && \
+    shx mv @rse/stx-linux-arm64   ../dst-stage3/stx-lnx-a64     && \
+    shx mv @rse/stx-win-x64.exe   ../dst-stage3/stx-win-x64.exe && \
+    shx mv @rse/stx-win-arm64.exe ../dst-stage3/stx-win-a64.exe && \
+    shx mv @rse/stx-macos-x64     ../dst-stage3/stx-mac-x64     && \
+    shx mv @rse/stx-macos-arm64   ../dst-stage3/stx-mac-a64
+
+#   remove regularly built files
+clean
+    shx rm -rf dst-stage1 dst-stage2 dst-stage3
+
+#   remove all built files
+clean-dist : clean
+    shx rm -f package-lock.json
+    shx rm -rf node_modules
+```
+
+Example execution calls are:
+
+```sh
+$ stx
+Available tasks:
+build                     build entire project
+build-cmd                 build command program
+build-man                 build manual page
+build-pkg                 build packaging (self-contained executables)
+build-watch               code compilation/transpiling (building)
+clean                     remove regularly built files
+clean-dist                remove all built files
+lint                      static code analysis (linting)
+lint-watch                static code analysis (linting) with file watching
+
+$ stx -v2 build
+$ sh [...]
+| eslint --config etc/eslint.mjs src/**/*.ts && \
+| markdownlint-cli2 --config etc/.markdownlint.yaml src/**/*.md
+markdownlint-cli2 v0.18.1 (markdownlint v0.38.0)
+Finding: src/**/*.md
+Linting: 1 file(s)
+Summary: 0 error(s)
+$ sh [...]
+| vite --config etc/vite.mts build --mode production
+vite v7.0.2 building for production...
+1:52:32 AM [tsc] building...
+1:52:32 AM [tsc] build completed in 447ms.
+✓ 1 modules transformed.
+dst-stage2/stx.js  10.75 kB
+✓ built in 484ms
+$ sh [...]
+| remark --quiet --use remark-man --output dst-stage2/stx.1 src/stx.md
+```
+
+## HISTORY
+
+`stx`(1) was developed in July 2025 as a replacement for the otherwise
+decent `nps`(1) command and to support more complex scripts from within
+`npm`(1), the *Node Package Manager (NPM)*. The main issue was that
+`nps`(1), when used with YAML and because of special parsing semantics
+of YAML, cannot support complex shell scripts with a combination of
+line-continuations and indentations.
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>