stx
===

Simple Task Execution




Abstract
--------

stx, Simple Task Execution, is a small Node.js-based 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 is inspired by and somewhat
resembles good-old Unix make, but it is not intended as a direct
replacement for it.

Its main design criterias and features are:

- Support for plain text configurations of just one or more tasks.
- Support for filtering tasks based on constraints, based on
machine architecture, operating system plaform, or hostname of
underlying device.
- Support for task sources as dependencies and recursive
resolution of all transitive task sources for pre-execution.
- Support for file and named based task targets and sources.
- Support for optional task sources to skip tasks with
still older sources or ignoring the failing of dependent scripts.
- Support for arbitrary task script languages, especially
JavaScript/TypeScript in addition to regular shells,
for maximum flexibility.
- Support for a special task script language "shell" which
allows somewhat portable shell scripting.
- Support for showing verbose script information during
execution for good traceability of the execution.
- Support for fuzzy-matching top-level tasks for better
Developer Experience (DX).

Installation
------------

When you want to use stx as a globally available command:

``
$ npm install -g @rse/stx
`

When you want to use stx as a locally available build tool from within NPM's package.json
by being able to just execute npm start instead of npx stx -v4 -c etc/stx.conf :

`
{
[...]
"devDependencies": {
[...]
"stx": "*"
},
"scripts": {
"start": "stx -v4 -c etc/stx.conf",
[...]
}
}
`

Usage
-----

See the Unix manual page for the documentation of the stx command.

Example
-------

See the stx's own build procedure for an example of a stx configuration:

`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:

`txt
$ 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
``

License
-------

Copyright © 2025 Dr. Ralf S. Engelschall (http://engelschall.com/)

Licensed under MIT