@xpack/xpm-lib 3.0.0

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@xpack/xpm-lib",
+  "version": "3.0.0",
+  "description": "A Node.js ES6 module with the xpm library utilities",
+  "type": "module",
+  "main": "./dist/index.js",
+  "typings": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "scripts": {
+    "compile-watch": "tsc --build --verbose --watch src",
+    "prettier": "prettier src --write",
+    "fix": "eslint --fix src",
+    "compile": "tsc --build --verbose src",
+    "fix-compile": "npm run prettier && npm run fix && npm run compile",
+    "npm-install": "npm install",
+    "npm-link": "npm link",
+    "npm-link-deps": "npm link @xpack/logger",
+    "npm-outdated": "npm outdated",
+    "npm-update": "npm update",
+    "npm-version-patch": "npm version patch",
+    "npm-version-minor": "npm version minor",
+    "postversion": "git push origin --all && git push origin --tags",
+    "npm-pack": "npm pack",
+    "git-log": "git log --pretty='%cd * %h %s' --date=short",
+    "lint": "eslint src",
+    "prepare": "npm run compile && npm run lint",
+    "pretest": "npm run lint",
+    "test": "npm run test-tap-run",
+    "test-ci": "npm run test-tap-run",
+    "test-tap-run": "tap run",
+    "test-tap-config-list": "tap config list",
+    "dev-cycle": "npm run fix && npm run compile && npm run test-100-c8",
+    "clean": "del-cli dist 'tests/**/cjs' 'src/**/*.d.ts' 'src/**/*.d.ts.map' 'src/**/*.js' 'src/**/*.js.map' 'tests/**/*.d.ts' 'tests/**/*.d.ts.map' 'tests/**/*.js' 'tests/**/*.js.map' '**/tsconfig.tsbuildinfo' .nyc_output coverage",
+    "deep-clean": "npm run clean && rm -rf node_modules package-lock.json",
+    "npm-version": "echo $(which node) $(node --version) && echo $(which npm) $(npm --version)"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xpack/xpm-lib-ts.git"
+  },
+  "keywords": [
+    "xpm",
+    "liquid",
+    "liquidjs"
+  ],
+  "author": {
+    "name": "Liviu Ionescu",
+    "email": "ilg@livius.net",
+    "url": "https://github.com/ilg-ul"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/xpack/xpm-lib-ts/issues"
+  },
+  "homepage": "https://xpack.github.io/xpm-lib-ts/",
+  "dependencies": {
+    "@npmcli/arborist": "^9.1.9",
+    "@xpack/logger": "^6.0.0",
+    "cacache": "^18.0.2",
+    "cp-file": "^10.0.0",
+    "decompress": "^4.2.1",
+    "del": "^8.0.1",
+    "https-proxy-agent": "^7.0.6",
+    "liquidjs": "^10.24.0",
+    "make-dir": "^5.1.0",
+    "node-fetch": "^3.3.2",
+    "pacote": "^17.0.6",
+    "proxy-from-env": "^1.1.0",
+    "semver": "^7.7.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.31.0",
+    "@tsconfig/node20": "^20.1.6",
+    "@types/decompress": "^4.2.7",
+    "@types/node": "^25.0.3",
+    "@types/npmcli__arborist": "^6.3.1",
+    "@types/pacote": "^11.1.8",
+    "@types/proxy-from-env": "^1.0.4",
+    "@types/semver": "^7.7.1",
+    "@types/tap": "^15.0.11",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.31.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.7.4",
+    "tap": "^21.5.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.38.0"
+  },
+  "engines": {
+    "node": " >=20.0"
+  }
+}

package/src/README.md

@@ -0,0 +1,10 @@
+# src
+
+This folder includes the main TypeScript source files, that provide
+the project functionality.
+
+They are compiled by `tsc` into the top `dist` folder as ES6 code.
+
+## CommonJS backward compatibility
+
+Starting with version 3.x, compatibility with CommonJS was removed.

package/src/index.ts

@@ -0,0 +1,35 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/license/mit.
+ */
+
+/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+
+// ----------------------------------------------------------------------------
+
+// Re-export all library definitions.
+export * from './lib/functions/chmod-recursive.js'
+export * from './lib/functions/perform-substitutions.js'
+export * from './lib/functions/utils.js'
+
+export * from './lib/errors.js'
+export * from './lib/init-template-base.js'
+export * from './lib/liquid-actions.js'
+export * from './lib/liquid-build-configurations.js'
+export * from './lib/liquid-drop.js'
+export * from './lib/liquid-engine.js'
+export * from './lib/liquid-package.js'
+export * from './lib/package.js'
+export * from './lib/policies.js'
+export * from './lib/substitutions-variables.js'
+export * from './lib/types.js'
+
+export * from 'liquidjs'
+
+// ----------------------------------------------------------------------------

package/src/lib/errors.ts

@@ -0,0 +1,29 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/license/mit.
+ */
+
+/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+
+// ----------------------------------------------------------------------------
+
+// Application errors
+export class XpmError extends Error {}
+
+export class XpmPrerequisitesError extends Error {}
+
+export class XpmInputError extends Error {}
+
+export class XpmSyntaxError extends Error {}
+
+export class XpmOutputError extends Error {}
+
+// Other errors:  Child.
+
+// ----------------------------------------------------------------------------

package/src/lib/functions/chmod-recursive.ts

@@ -0,0 +1,103 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2017-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/license/mit.
+ */
+
+/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+
+// ----------------------------------------------------------------------------
+
+// https://nodejs.org/docs/latest/api/
+import assert from 'node:assert'
+import * as fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { Logger } from '@xpack/logger'
+
+// ----------------------------------------------------------------------------
+
+export async function chmodRecursive({
+  inputPath,
+  readOnly,
+  log,
+}: {
+  inputPath: string
+  readOnly: boolean
+  log: Logger
+}): Promise<void> {
+  assert(inputPath, 'mandatory inputPath')
+  assert(log, 'mandatory log')
+
+  const stat = await fs.lstat(inputPath)
+  // log.trace(util.inspect(stat))
+
+  if (stat.isSymbolicLink()) {
+    // Since it is not possible to change the modes of links (lchmod
+    // was deprecated and worked on macOS anyway), don't bother
+    // with them.
+    return
+  }
+
+  // The order is important, process the folder before
+  // changing it to RO.
+  if (readOnly && stat.isDirectory()) {
+    log.trace(inputPath)
+    const dirents = await fs.readdir(inputPath, {
+      withFileTypes: true,
+    })
+    for (const dirent of dirents) {
+      await chmodRecursive({
+        inputPath: path.resolve(inputPath, dirent.name),
+        readOnly,
+        log,
+      })
+    }
+  }
+
+  const mode = stat.mode
+  // For RO, remove all W bits, for RW add only user.
+  const newMode = readOnly
+    ? mode &
+      ~(fs.constants.S_IWUSR | fs.constants.S_IWGRP | fs.constants.S_IWOTH)
+    : mode | fs.constants.S_IWUSR
+
+  // log.trace(
+  //  `set ${inputPath} from ${mode.toString(8)} to ${newMode.toString(8)}`)
+  await fs.chmod(inputPath, newMode)
+
+  const actualStat = await fs.stat(inputPath)
+  // log.trace(`actual ${inputPath} is ${actualStat.mode.toString(8)}`)
+
+  if (readOnly) {
+    if ((actualStat.mode & fs.constants.S_IWUSR) !== 0) {
+      log.warn(`${inputPath} not set to RO`)
+    }
+  } else {
+    if ((actualStat.mode & fs.constants.S_IWUSR) === 0) {
+      log.warn(`${inputPath} not set to RW`)
+    }
+  }
+
+  // If RW, process the folder after changing it to RW.
+  if (!readOnly && stat.isDirectory()) {
+    log.trace(inputPath)
+    const dirents = await fs.readdir(inputPath, {
+      withFileTypes: true,
+    })
+    for (const dirent of dirents) {
+      await chmodRecursive({
+        inputPath: path.resolve(inputPath, dirent.name),
+        readOnly,
+        log,
+      })
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/lib/functions/perform-substitutions.ts

@@ -0,0 +1,116 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/license/mit.
+ */
+
+/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+
+// ----------------------------------------------------------------------------
+
+import assert from 'node:assert'
+
+import { Context } from 'liquidjs'
+
+import { Logger } from '@xpack/logger'
+
+import { XpmLiquidEngine } from '../liquid-engine.js'
+import { XpmLiquidPropertiesDrop } from '../liquid-drop.js'
+import { XpmLiquidSubstitutionsVariables } from '../substitutions-variables.js'
+
+// ----------------------------------------------------------------------------
+/**
+ * Perform substitution on the input string.
+ * Repeat until no more Liquid variables or tags are identified.
+ *
+ * @param input - The input string, possibly with substitutions.
+ * @param map - The substitution map.
+ * @returns The substituted string.
+ *
+ * @throws Liquid exceptions
+ */
+
+export async function performSubstitutions({
+  log,
+  engine,
+  input,
+  substitutionsVariables,
+}: {
+  log: Logger
+  engine: XpmLiquidEngine
+  input: string
+  substitutionsVariables: XpmLiquidSubstitutionsVariables
+}): Promise<string> {
+  assert(substitutionsVariables)
+
+  if (input.trim() === '') {
+    // Spare it the trouble for empty strings.
+    return input
+  }
+
+  let context
+  // Wrap properties into a liquid drop (a mechanism to process
+  // substitutions immediately).
+  if (Object.keys(substitutionsVariables.properties).length > 0) {
+    context = new Context({
+      ...substitutionsVariables,
+      properties: new XpmLiquidPropertiesDrop({
+        log,
+        engine,
+        properties: substitutionsVariables.properties,
+      }),
+    })
+  } else {
+    context = new Context(substitutionsVariables)
+  }
+
+  log.trace(`performSubstitutions('${input}')`)
+
+  let current: string = input
+  let substituted: string = current
+  let count = 0
+
+  // Iterate until all substitutions are done.
+  while (current.includes('{{') || current.includes('{%')) {
+    ++count
+    // May throw.
+    try {
+      substituted = (await engine.parseAndRender(current, context)) as string
+
+      /* c8 ignore start */ /* istanbul ignore next */
+      if (substituted === current) {
+        // If nothing changed, we're done.
+        // This test is just a safety net, normally should not get there.
+        log.warn(
+          `performSubstitutions() ${String(count)} => |`,
+          substituted,
+          '| did not change'
+        )
+
+        break
+      } /* c8 ignore stop */
+    } catch (ex) {
+      if (ex instanceof Error) {
+        // log.error(ex)
+        log.error(ex.message)
+      } else {
+        log.error(new Error(String(ex)))
+      }
+      // Return the current (unsubstituted) value.
+      substituted = current
+      break
+    }
+
+    log.trace(`performSubstitutions() ${String(count)} => |`, substituted, '|')
+    current = substituted
+  }
+
+  return substituted
+}
+
+// ----------------------------------------------------------------------------

package/src/lib/functions/utils.ts

@@ -0,0 +1,88 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/license/mit.
+ */
+
+/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+
+// ----------------------------------------------------------------------------
+
+import * as os from 'node:os'
+
+// ----------------------------------------------------------------------------
+
+export function isPrimitive(value: unknown): boolean {
+  return (
+    (typeof value !== 'object' && typeof value !== 'function') || value === null
+  )
+}
+
+export function isJsonObject(value: unknown): boolean {
+  return value !== undefined && !isPrimitive(value) && !Array.isArray(value)
+}
+
+export function isJsonArray(value: unknown): boolean {
+  return value !== undefined && Array.isArray(value)
+}
+
+export function isNonEmptyJsonObject(value: unknown): boolean {
+  return isJsonObject(value) && Object.keys(value as object).length > 0
+}
+
+export function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}
+
+/**
+ * Replace non alphanumeric chars with dashes to make the paths
+ * comply with filesystem names.
+ *
+ * @param {string} input A path candidate.
+ * @returns {string} A validated path.
+ */
+export function filterPath(input: string): string {
+  /* c8 ignore start */ /* istanbul ignore next */
+  const fixed =
+    os.platform() === 'win32'
+      ? input.replace(/[^a-zA-Z0-9\\:]+/g, '-')
+      : input.replace(/[^a-zA-Z0-9/]+/g, '-')
+  /* c8 ignore stop */
+
+  return fixed.replace(/--/g, '-')
+}
+
+/**
+ * Replace non alphanumeric chars with dashes to make the paths
+ * comply with Posix filesystem names.
+ *
+ * @param {string} input A path candidate.
+ * @returns {string} A validated path.
+ */
+export function filterPosixPath(input: string): string {
+  /* istanbul ignore next */
+  const fixed = input.replace(/[^a-zA-Z0-9/]+/g, '-')
+
+  return fixed.replace(/--/g, '-')
+}
+
+/**
+ * Replace non alphanumeric chars with dashes to make the paths
+ * comply with Windows filesystem names.
+ *
+ * @param {string} input A path candidate.
+ * @returns {string} A validated path.
+ */
+export function filterWin32Path(input: string): string {
+  /* istanbul ignore next */
+  const fixed = input.replace(/[^a-zA-Z0-9\\:]+/g, '-')
+
+  return fixed.replace(/--/g, '-')
+}
+
+// ----------------------------------------------------------------------------