@rse/nunjucks-cli 1.6.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,131 @@
+
+ChangeLog
+=========
+
+2.0.0 (2025-12-21)
+------------------
+
+- REFACTORING: switched to ESLint 9
+- REFACTORING: switched to TypeScript
+- REFACTORING: converted to STX and added packaging
+- MAINTENANCE: upgraded dependencies
+
+1.6.0 (2025-06-02)
+------------------
+
+- REFACTORING: upgraded to ESM land
+- MAINTENANCE: upgraded dependencies
+- MAINTENANCE: bumped year in all copyright messages
+
+1.5.2 (2024-03-11)
+------------------
+
+- MAINTENANCE: updated copyright messages
+- MAINTENANCE: upgraded dependencies
+- MAINTENANCE: updated Dockerfile
+
+1.5.1 (2023-12-25)
+------------------
+
+- MAINTENANCE: upgraded dependencies
+
+1.5.0 (2023-10-02)
+------------------
+
+- FEATURE: support that option -d can occur multiple times (mixes structures deeply)
+- MAINTENANCE: made ESLint happy with newer language features
+- MAINTENANCE: upgraded dependencies
+- MAINTENANCE: added Docker scripts
+- MAINTENANCE: fixed stdver
+
+1.4.5 (2023-08-28)
+------------------
+
+- BUGFIX: fixed once again the repo URL
+
+1.4.4 (2023-08-28)
+------------------
+
+- BUGFIX: fixed repo URL
+- FEATURE: added manpage
+
+1.4.3 (2023-08-27)
+------------------
+
+- MAINTENANCE: linked manpage
+- MAINTENANCE: added stdver
+- MAINTENANCE: improved badges
+
+1.4.2 (2023-08-26)
+------------------
+
+- FEATURE: added Unix manual page
+
+1.4.1 (2023-08-21)
+------------------
+
+- REFACTORING: switched option parser from yargs to commander in order to support -Dx=y and not just -D x=y (with space)
+
+1.4.0 (2023-08-20)
+------------------
+
+- FEATURE: added CLI option -C
+- MAINTENANCE: upgraded dependencies
+
+1.3.1 (2023-08-18)
+------------------
+
+- FEATURE: support local paths, too
+
+1.3.0 (2023-08-18)
+------------------
+
+- FEATURE: added better installation and usage hints
+- REFACTORING: removed addons as they are now in their own package
+
+1.2.1 (2023-08-17)
+------------------
+
+- FEATURE: added uuid global function
+- FEATURE: provided sprintf global function
+- FEATURE: added sprintf filter
+- FEATURE: added pad filter
+
+1.2.0 (2023-08-15)
+------------------
+
+- FEATURE: added jsonpath extension
+- REFACTORING: made jsYAML usage more modern and added support for jsonpath extension
+
+1.1.1 (2023-08-15)
+------------------
+
+- MAINTENANCE: used copyright symbol
+
+1.1.0 (2023-08-15)
+------------------
+
+- FEATURE: allowed NPM modules to be used as extensions
+
+1.0.1 (2023-08-15)
+------------------
+
+- BUGFIX: remembered extensions
+
+1.0.0 (2023-08-15)
+------------------
+
+- FEATURE: added hint to npx usage
+
+0.9.6 (2023-08-15)
+------------------
+
+- MAINTENANCE: final cleanup
+- MAINTENANCE: fixed npm publishing
+- MAINTENANCE: switched to private namespace
+
+0.9.5 (2023-08-15)
+------------------
+
+(first version)
+

package/Dockerfile

@@ -5,12 +5,12 @@
 #   build arguments (early)
 ARG         IMAGE_PREFIX=docker.io/engelschall/
 ARG         IMAGE_NAME=nunjucks-cli
-ARG         IMAGE_VERSION=1.5.2
-ARG         IMAGE_RELEASE=20240311
+ARG         IMAGE_VERSION=2.0.0
+ARG         IMAGE_RELEASE=20251221
 ARG         IMAGE_ALIAS=latest
 
 #   derive image from a certain base image
-FROM        node:24-alpine3.21
+FROM        node:24-alpine3.23
 
 #   add additional build tools
 RUN         apk update && \

package/eslint.mjs

@@ -9,10 +9,12 @@ import pluginStd     from "neostandard"
 import pluginN       from "eslint-plugin-n"
 import pluginImport  from "eslint-plugin-import"
 import pluginPromise from "eslint-plugin-promise"
+import pluginTS      from "typescript-eslint"
 import globals       from "globals"
 
 export default [
     pluginJs.configs.recommended,
+    ...pluginTS.configs.recommended,
     ...pluginStd({
         ignores: pluginStd.resolveIgnoresFromGitignore()
     }),
@@ -22,7 +24,7 @@ export default [
             "import":  pluginImport,
             "promise": pluginPromise
         },
-        files:   [ "**/*.js" ],
+        files:   [ "**/*.js", "**/*.ts" ],
         ignores: [ "dst/" ],
         languageOptions: {
             ecmaVersion: 2022,
@@ -58,7 +60,10 @@ export default [
             "@stylistic/array-bracket-spacing":                   "off",
             "@stylistic/lines-between-class-members":             "off",
             "@stylistic/multiline-ternary":                       "off",
-            "@stylistic/quote-props":                             "off"
+            "@stylistic/quote-props":                             "off",
+
+            "@typescript-eslint/no-explicit-any":                 "off",
+            "@typescript-eslint/no-unused-vars":                  [ "error", { "argsIgnorePattern": "^_", "caughtErrorsIgnorePattern": "^_" } ]
         }
     }
 ]

package/{nunjucks.js → nunjucks.ts}

@@ -5,36 +5,71 @@
 **  Licensed under MIT <http://spdx.org/licenses/MIT.html>
 */
 
-/*  internal requirements  */
-import fs          from "node:fs"
-import path        from "node:path"
+/*  built-in requirements  */
+import fs                from "node:fs"
+import path              from "node:path"
+import { createRequire } from "node:module"
 
 /*  external requirements  */
-import { Command } from "commander"
-import chalk       from "chalk"
-import jsYAML      from "js-yaml"
-import nunjucks    from "nunjucks"
-import deepmerge   from "deepmerge"
+import { Command }       from "commander"
+import chalk             from "chalk"
+import jsYAML            from "js-yaml"
+import nunjucks          from "nunjucks"
+import deepmerge         from "deepmerge"
+
+/*  type definitions  */
+type PackageInfo = {
+    name:         string
+    version:      string
+    description:  string
+    author:       { name: string; email: string; url: string }
+    license:      string
+    dependencies: { nunjucks: string }
+}
+type ContextType = Record<string, any>
+type OptionsType = {
+    autoescape?:       boolean
+    throwOnUndefined?: boolean
+    trimBlocks?:       boolean
+    lstripBlocks?:     boolean
+    watch?:            boolean
+    noCache?:          boolean
+}
+type CLIOptions = {
+    help:      boolean
+    version:   boolean
+    config:    string
+    option:    string[]
+    defines:   string[]
+    define:    string[]
+    extension: string[]
+    output:    string
+    _:         string[]
+}
 
 /*  load my own information  */
-const my = JSON.parse(await fs.promises.readFile(new URL("./package.json", import.meta.url)))
+const my: PackageInfo = JSON.parse(await fs.promises.readFile(new URL("./package.json", import.meta.url), "utf-8"))
 
 /*  parse command-line arguments  */
 const program = new Command()
+const reduceArray = (v: string, l: string[]) => l.concat([ v ])
 program.name("nunjucks")
     .description("Nunjucks Template Rendering Command-Line Interface")
     .showHelpAfterError("hint: use option --help for usage information")
-    .option("-h, --help", "show usage help", false)
-    .option("-V, --version", "show program version information", false)
-    .option("-c, --config <config-file>", "load Nunjucks configuration YAML file", "")
-    .option("-C, --option <key>=<value>", "set Nunjucks configuration option", (v, l) => l.concat([ v ]), [])
-    .option("-d, --defines <context-file>", "load context definition YAML file", (v, l) => l.concat([ v ]), [])
-    .option("-D, --define <key>=<value>", "set context definition key/value", (v, l) => l.concat([ v ]), [])
-    .option("-e, --extension <module-name>", "load Nunjucks JavaScript extension module", (v, l) => l.concat([ v ]), [])
-    .option("-o, --output <output-file>", "save output file", "-")
+    .option("-h, --help",                    "show usage help",                                        false)
+    .option("-V, --version",                 "show program version information",                       false)
+    .option("-c, --config <config-file>",    "load Nunjucks configuration YAML file",                  "")
+    .option("-C, --option <key>=<value>",    "set Nunjucks configuration option",         reduceArray, [])
+    .option("-d, --defines <context-file>",  "load context definition YAML file",         reduceArray, [])
+    .option("-D, --define <key>=<value>",    "set context definition key/value",          reduceArray, [])
+    .option("-e, --extension <module-name>", "load Nunjucks JavaScript extension module", reduceArray, [])
+    .option("-o, --output <output-file>",    "save output file",                                       "-")
     .argument("[<input-file>]", "input file")
 program.parse(process.argv)
-const argv = { ...program.opts(), _: program.args }
+const argv: CLIOptions = {
+    ...program.opts(),
+    _: program.args
+} as CLIOptions
 
 /*  handle special help request  */
 if (argv.help) {
@@ -58,7 +93,7 @@ if (argv._.length > 1) {
     console.error(chalk.red("nunjucks: ERROR: invalid number of arguments (zero or one input file expected)"))
     process.exit(1)
 }
-let inputFile = argv._[0] ?? "-"
+let inputFile: string = argv._[0] ?? "-"
 if (inputFile === "-") {
     inputFile = "<stdin>"
     process.stdin.setEncoding("utf-8")
@@ -67,9 +102,9 @@ if (inputFile === "-") {
     while (true) {
         let bytesRead = 0
         try {
-            bytesRead = fs.readSync(process.stdin.fd, buf, 0, BUFSIZE)
+            bytesRead = fs.readSync(process.stdin.fd, buf, 0, BUFSIZE, null)
         }
-        catch (ex) {
+        catch (ex: any) {
             if      (ex.code === "EAGAIN") continue
             else if (ex.code === "EOF")    break
             else                           throw ex
@@ -88,12 +123,12 @@ else {
 }
 
 /*  provide context variables for template  */
-let context = {}
+let context: ContextType = {}
 for (const define of argv.defines) {
     try {
-        context = deepmerge(context, jsYAML.load(fs.readFileSync(define, { encoding: "utf8" })))
+        context = deepmerge(context, jsYAML.load(fs.readFileSync(define, { encoding: "utf8" })) as ContextType)
     }
-    catch (ex) {
+    catch (ex: any) {
         console.error(chalk.red(`nunjucks: ERROR: failed to load context YAML file: ${ex.toString()}`))
         process.exit(1)
     }
@@ -103,46 +138,53 @@ for (const define of argv.defines) {
 context.env = process.env
 
 /*  add context defines  */
-argv.define.forEach((define) => {
-    let [ , key, val ] = define.match(/^([^=]+)(?:=(.*))?$/)
+argv.define.forEach((define: string) => {
+    const match = define.match(/^([^=]+)(?:=(.*))?$/)
+    if (!match)
+        return
+    let [ , key, val ]: (string | undefined)[] = match
+    if (!key)
+        return
     if (val === undefined)
-        val = true
+        val = "true"
     context[key] = val
 })
 
 /*  determine Nunjucks options  */
-let options = {}
+let options: OptionsType = {}
 if (argv.config) {
     try {
-        options = jsYAML.load(fs.readFileSync(argv.config, { encoding: "utf8" }))
+        options = jsYAML.load(fs.readFileSync(argv.config, { encoding: "utf8" })) as OptionsType
     }
-    catch (ex) {
+    catch (ex: any) {
         console.error(chalk.red(`nunjucks: ERROR: failed to load options YAML file: ${ex.toString()}`))
         process.exit(1)
     }
 }
 if (argv.option.length > 0)
     options = Object.assign(options, argv.option)
-options = Object.assign({}, {
+options = {
     autoescape:       false,
     throwOnUndefined: false,
     trimBlocks:       true,
     lstripBlocks:     true,
     watch:            false,
-    noCache:          true
-}, options)
+    noCache:          true,
+    ...options
+}
 
 /*  configure environment  */
 const env = nunjucks.configure(inputFile, options)
 
 /*  load external extension files  */
 for (const extension of argv.extension) {
-    let modpath = path.resolve(extension)
+    let modpath: string | null = path.resolve(extension)
     if (!fs.existsSync(modpath)) {
         try {
+            const require = createRequire(import.meta.url)
             modpath = require.resolve(extension)
         }
-        catch (ex) {
+        catch (_ex) {
             modpath = null
         }
     }
@@ -150,7 +192,19 @@ for (const extension of argv.extension) {
         console.error(chalk.red(`nunjucks: ERROR: failed to find extension module: ${extension}`))
         process.exit(1)
     }
-    const mod = require(modpath)
+
+    /*  dynamically import the module  */
+    let mod: any
+    try {
+        mod = await import(modpath)
+
+        /*  handle both default and named exports  */
+        mod = mod.default ?? mod
+    }
+    catch (ex: any) {
+        console.error(chalk.red(`nunjucks: ERROR: failed to load extension module: ${ex.toString()}`))
+        process.exit(1)
+    }
     if (!(mod !== null && typeof mod === "function")) {
         console.error(chalk.red(`nunjucks: ERROR: failed to call extension file: ${modpath}`))
         process.exit(1)
@@ -159,11 +213,11 @@ for (const extension of argv.extension) {
 }
 
 /*  render Nunjucks template  */
-let output
+let output: string
 try {
     output = env.renderString(input, context)
 }
-catch (ex) {
+catch (ex: any) {
     console.error(chalk.red(`nunjucks: ERROR: failed to render template: ${ex.toString()}`))
     process.exit(1)
 }

package/package.json

@@ -1,8 +1,8 @@
 {
     "name":                       "@rse/nunjucks-cli",
     "publishConfig":              { "access": "public" },
-    "version":                    "1.6.0",
-    "stdver":                     "1.6.0-GA",
+    "version":                    "2.0.0",
+    "stdver":                     "2.0.0-GA",
     "description":                "Nunjucks Template Rendering Command-Line Interface",
     "author": {
         "name":                   "Dr. Ralf S. Engelschall",
@@ -18,32 +18,43 @@
         "url":                    "http://github.com/rse/nunjucks-cli/issues"
     },
     "bin": {
-        "nunjucks":               "nunjucks.js"
+        "nunjucks":               "nunjucks.ts"
     },
     "man":                        "nunjucks.1",
     "type":                       "module",
+    "engines": {
+        "node":                   ">=22.18.0"
+    },
     "dependencies": {
         "nunjucks":               "3.2.4",
-        "chalk":                  "5.4.1",
-        "commander":              "14.0.0",
-        "js-yaml":                "4.1.0",
+        "chalk":                  "5.6.2",
+        "commander":              "14.0.2",
+        "js-yaml":                "4.1.1",
         "deepmerge":              "4.3.1"
     },
     "devDependencies": {
-        "eslint":                 "9.28.0",
-        "@eslint/js":             "9.28.0",
-        "neostandard":            "0.12.1",
+        "eslint":                 "9.39.2",
+        "@eslint/js":             "9.39.2",
+        "neostandard":            "0.12.2",
         "eslint-plugin-promise":  "7.2.1",
-        "eslint-plugin-import":   "2.31.0",
-        "eslint-plugin-n":        "17.19.0",
-        "globals":                "16.2.0",
+        "eslint-plugin-import":   "2.32.0",
+        "eslint-plugin-n":        "17.23.1",
+        "globals":                "16.5.0",
         "remark-cli":             "12.0.1",
         "remark":                 "15.0.1",
-        "remark-man":             "9.0.0"
+        "remark-man":             "9.0.0",
+        "typescript":             "5.9.3",
+        "typescript-eslint":      "8.50.0",
+        "@rse/stx":               "1.1.3",
+        "shx":                    "0.4.0",
+        "@yao-pkg/pkg":           "6.11.0",
+
+        "@types/node":            "25.0.3",
+        "@types/js-yaml":         "4.0.9",
+        "@types/nunjucks":        "3.2.6"
     },
     "scripts": {
-        "lint":                   "eslint --config eslint.mjs nunjucks.js",
-        "man":                    "remark --quiet --use remark-man --output nunjucks.1 nunjucks.md",
-        "test":                   "echo 'Hello, {{who}}!' | node nunjucks.js -D who=world -"
+        "start":                  "stx -v4 -c stx.conf",
+        "test":                   "npm start test"
     }
 }

package/stx.conf

@@ -0,0 +1,90 @@
+##
+##  nunjucks -- Nunjucks Template Rendering Command-Line Interface
+##  Copyright (c) 2019-2025 Dr. Ralf S. Engelschall <rse@engelschall.com>
+##  Licensed under MIT <https://spdx.org/licenses/MIT>
+##
+
+#   static code analysis
+lint
+    eslint --config eslint.mjs nunjucks.ts && \
+    tsc --project tsconfig.json
+
+#   build manual page
+man
+    remark --quiet --use remark-man --output nunjucks.1 nunjucks.md
+
+#   execute simple smole test
+test
+    echo 'Hello, {{who}}!' | node nunjucks.ts -D who=world -
+
+#   build all-in-one packages
+build:pkg [hostname=en4.*]
+
+#   package distribution archives
+package : build:pkg [hostname=en4.*]
+    VERSION=`sed -n '/"version":/ s/.*: *"\(.*\)".*/\1/p' package.json` && \
+    targets="node24-linux-x64,node24-linux-arm64" && \
+    targets="$targets,node24-win-x64,node24-win-arm64" && \
+    targets="$targets,node24-macos-x64,node24-macos-arm64" && \
+    sed -e 's;@rse/nunjucks-cli;nunjucks;' <package.json >nunjucks.json && \
+    pkg --sea --public -c nunjucks.json -t "$targets" nunjucks.ts && \
+    rm -f nunjucks.json && \
+    shx mv nunjucks-linux-x64     nunjucks-lnx-x64     && \
+    shx mv nunjucks-linux-arm64   nunjucks-lnx-a64     && \
+    shx mv nunjucks-win-x64.exe   nunjucks-win-x64.exe && \
+    shx mv nunjucks-win-arm64.exe nunjucks-win-a64.exe && \
+    shx mv nunjucks-macos-x64     nunjucks-mac-x64     && \
+    shx mv nunjucks-macos-arm64   nunjucks-mac-a64
+    mkdir -p nunjucks-$VERSION/ && \
+    mkdir -p nunjucks-$VERSION-win-x64/ && \
+    mkdir -p nunjucks-$VERSION-win-a64/ && \
+    mkdir -p nunjucks-$VERSION-mac-x64/ && \
+    mkdir -p nunjucks-$VERSION-mac-a64/ && \
+    mkdir -p nunjucks-$VERSION-lnx-x64/ && \
+    mkdir -p nunjucks-$VERSION-lnx-a64/ && \
+    cp -p nunjucks.ts             nunjucks-$VERSION/nunjucks.ts && \
+    cp -p nunjucks-win-x64.exe    nunjucks-$VERSION-win-x64/nunjucks.exe && \
+    cp -p nunjucks-win-a64.exe    nunjucks-$VERSION-win-a64/nunjucks.exe && \
+    cp -p nunjucks-mac-x64        nunjucks-$VERSION-mac-x64/nunjucks && \
+    cp -p nunjucks-mac-a64        nunjucks-$VERSION-mac-a64/nunjucks && \
+    cp -p nunjucks-lnx-x64        nunjucks-$VERSION-lnx-x64/nunjucks && \
+    cp -p nunjucks-lnx-a64        nunjucks-$VERSION-lnx-a64/nunjucks && \
+    cp -p nunjucks.1              nunjucks-$VERSION/nunjucks.man && \
+    cp -p nunjucks.1              nunjucks-$VERSION-win-x64/nunjucks.man && \
+    cp -p nunjucks.1              nunjucks-$VERSION-win-a64/nunjucks.man && \
+    cp -p nunjucks.1              nunjucks-$VERSION-mac-x64/nunjucks.man && \
+    cp -p nunjucks.1              nunjucks-$VERSION-mac-a64/nunjucks.man && \
+    cp -p nunjucks.1              nunjucks-$VERSION-lnx-x64/nunjucks.man && \
+    cp -p nunjucks.1              nunjucks-$VERSION-lnx-a64/nunjucks.man && \
+    zip -9 -r nunjucks-$VERSION.zip         nunjucks-$VERSION/         && \
+    zip -9 -r nunjucks-$VERSION-win-x64.zip nunjucks-$VERSION-win-x64/ && \
+    zip -9 -r nunjucks-$VERSION-win-a64.zip nunjucks-$VERSION-win-a64/ && \
+    zip -9 -r nunjucks-$VERSION-mac-x64.zip nunjucks-$VERSION-mac-x64/ && \
+    zip -9 -r nunjucks-$VERSION-mac-a64.zip nunjucks-$VERSION-mac-a64/ && \
+    zip -9 -r nunjucks-$VERSION-lnx-x64.zip nunjucks-$VERSION-lnx-x64/ && \
+    zip -9 -r nunjucks-$VERSION-lnx-a64.zip nunjucks-$VERSION-lnx-a64/
+
+#   publish distribution archives
+publish : package [hostname=en4.*]
+    VERSION=`sed -n '/"version":/ s/.*: *"\(.*\)".*/\1/p' package.json` && \
+    V=`echo "$VERSION" | sed -e 's;\.;\\.;g'` && \
+    sed -n -e "/^${V} /, /^[0-9]\\./ { /^${V} /p; /^[0-9]\\./!p; }" <CHANGELOG.md >.notes.md && \
+    gh release create --title "Nunjucks $VERSION" --notes-file .notes.md --verify-tag $VERSION \
+    nunjucks-$VERSION.zip \
+    nunjucks-$VERSION-win-x64.zip \
+    nunjucks-$VERSION-win-a64.zip \
+    nunjucks-$VERSION-mac-x64.zip \
+    nunjucks-$VERSION-mac-a64.zip \
+    nunjucks-$VERSION-lnx-x64.zip \
+    nunjucks-$VERSION-lnx-a64.zip && \
+    rm -f .notes.md
+
+#   remove all generated artifacts
+clean
+    shx rm -rf nunjucks-*.zip
+
+#   remove all generated artifacts
+distclean: clean
+    shx rm -f package-lock.json && \
+    shx rm -rf node_modules
+

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "target":                           "ES2024",
+        "module":                           "node20",
+        "lib":                              [ "ES2024" ],
+        "moduleResolution":                 "node16",
+        "resolveJsonModule":                true,
+        "allowImportingTsExtensions":       true,
+        "allowSyntheticDefaultImports":     true,
+        "esModuleInterop":                  true,
+        "forceConsistentCasingInFileNames": true,
+        "strict":                           true,
+        "skipLibCheck":                     true,
+        "noEmit":                           true,
+        "types":                            [ "node" ]
+    },
+    "include": [
+        "nunjucks.ts"
+    ],
+    "exclude": [
+        "node_modules"
+    ]
+}