js-dev-tool 1.2.19 → 1.2.21

package/README.md

@@ -30,10 +30,11 @@ This section reflects the current `package.json#exports` and `package.json#files
 | --- | --- |
 | `js-dev-tool` | Root namespace object with `{ progress, common, utils }` |
 | `js-dev-tool/utils` | File, JSON, CLI, TSV/CSV, and small utility helpers |
-| `js-dev-tool/common` | File-system and terminal rendering primitives |
+| `js-dev-tool/common` | File-system helpers, terminal rendering primitives, and `isMain` |
 | `js-dev-tool/progress` | Progress renderer, spinner helpers, webpack / browserify progress hooks |
 | `js-dev-tool/progress/progress-extras` | Environment and webpack-version helpers |
 | `js-dev-tool/extras/algorithms` | Binary-search helper |
+| `js-dev-tool/extras/gzip-tool` | Deterministic gzip + Base64 source-literal helpers |
 | `js-dev-tool/extras/jsonl` | JSONL readers, JSONL-to-array/map helpers, and `jsonMinify` |
 | `js-dev-tool/extras/json-minify` | `jsonMinify` |
 | `js-dev-tool/extras/progress-light` | Small fixed-frame spinner |
@@ -93,6 +94,20 @@ console.log(map["1"], deps.slice(0, 5));
 - `createLogStreamAndResolvePath(logPath)`
 - `renderLine(msg?, row?)`
 - `cursor(enabled, output?)`
+- `isMain(moduleOrPathOrMeta)`
+
+`isMain(...)` is the cross-module-system entry-point check. It accepts:
+
+- CommonJS: `module` or `__filename`
+- ESM: `import.meta` or `fileURLToPath(import.meta.url)`
+
+```js
+const { isMain } = require("js-dev-tool/common");
+
+if (isMain(module)) {
+  console.log("run only when executed directly");
+}
+```
 
 ## `progress`
 
@@ -190,6 +205,34 @@ async function main() {
 main().catch(console.error);
 ```
 
+### `js-dev-tool/extras/gzip-tool`
+
+Exports:
+
+- `gzip(data, useZeroTimestamp?)`
+- `toBase64SourceLiteral(rawData, wrapSize?)`
+
+Use this module when you want deterministic gzip output and a clean way to embed the compressed bytes into JavaScript source.
+
+Key behaviors:
+
+- `gzip(...)` compresses with gzip level `9`
+- `gzip(..., true)` zeroes the gzip `mtime` header so repeated builds with the same input stay byte-stable
+- `toBase64SourceLiteral(...)` wraps Base64 output with trailing `\` line continuations so the result can be pasted into a multi-line JavaScript string literal
+- `wrapSize` must be a finite integer between `1` and `2048`
+
+Example:
+
+```js
+const { gzip, toBase64SourceLiteral } = require("js-dev-tool/extras/gzip-tool");
+
+const compressed = gzip("console.log(\"hello\");");
+const sourceLiteral = toBase64SourceLiteral(compressed, 76);
+
+console.log(compressed.length);
+console.log(sourceLiteral);
+```
+
 ### `js-dev-tool/extras/progress-light`
 
 Exports:

package/common/index.d.ts

@@ -43,17 +43,29 @@ export function renderLine(msg?: string, row?: number): void;
  */
 export function cursor(enabled: boolean, output?: NodeJS.WriteStream): void;
 /**
- * Returns `true` if the given module is the entry point of the current process.
+ * Minimal `import.meta`-compatible shape accepted by `isMain`.
  *
- * Accepts either a `module` object (CommonJS) or a file path string,
- * making it usable from both CommonJS and ESM contexts.
+ * Only `url` is required. `resolve` stays optional so the same shape works
+ * across older and newer Node.js ESM runtimes.
+ */
+declare type TImportMeta = {
+  url: string;
+  resolve?: (filePath: string) => string;
+ };
+/**
+ * Returns `true` when the provided CommonJS module, absolute file path, or
+ * ESM `import.meta` object represents the current process entry point.
+ *
+ * This gives one API that works across both module systems:
+ * - CommonJS: `module` or `__filename`
+ * - ESM: `import.meta` or `fileURLToPath(import.meta.url)`
  *
  * Equivalent to `import.meta.main` in Deno / Bun,
  * or `process.argv[1] === fileURLToPath(import.meta.url)` in ESM.
  *
- * @param {Partial<NodeJS.Module> | string} modOrFilePath
- *   Pass `module` or `__filename` (CommonJS),
- *   or `fileURLToPath(import.meta.url)` (ESM).
+ * @param {Partial<NodeJS.Module> | TImportMeta | string} modOrPathOrMeta
+ *   Pass `module` or `__filename` from CommonJS,
+ *   or `import.meta` / `fileURLToPath(import.meta.url)` from ESM.
  * @returns {boolean} `true` if the calling module is the entry point.
  *
  * @example
@@ -67,7 +79,12 @@ export function cursor(enabled: boolean, output?: NodeJS.WriteStream): void;
  * if (isMain(__filename)) { main(); }
  *
  * @example
- * // ESM — via fileURLToPath:
+ * // ESM — via import.meta object:
+ * import { isMain } from "js-dev-tool/common";
+ * if (isMain(import.meta)) { main(); }
+ *
+ * @example
+ * // ESM — via fileURLToPath(import.meta.url):
  * import { isMain } from "js-dev-tool/common";
  * import { fileURLToPath } from "node:url";
  * if (isMain(fileURLToPath(import.meta.url))) { main(); }
@@ -76,4 +93,4 @@ export function cursor(enabled: boolean, output?: NodeJS.WriteStream): void;
  * @verified CJS: Confirmed working on Node.js v11.15.0 — v26.3.0.
  * @verified ESM: Confirmed working on Node.js v12.22.11 — v26.3.0.
  */
-export function isMain(modOrFilePath: Partial<NodeJS.Module> | string): boolean;
+export function isMain(modOrPathOrMeta: Partial<NodeJS.Module> | TImportMeta | string): boolean;

package/common/index.js

@@ -13,6 +13,7 @@
 const fs = require("fs");
 const path = require("path");
 const rl = require("readline");
+const { fileURLToPath } = require("url");
 /**
  * @param {string} dest
  */
@@ -56,17 +57,30 @@ const cursor = (enabled, output = process.stderr) => {
   }
 };
 /**
- * Returns `true` if the given module is the entry point of the current process.
+ * Minimal `import.meta`-compatible shape accepted by {@link isMain}.
  *
- * Accepts either a `module` object (CommonJS) or a file path string,
- * making it usable from both CommonJS and ESM contexts.
+ * Only `url` is required. `resolve` stays optional so the same shape works
+ * across older and newer Node.js ESM runtimes.
+ *
+ * @typedef {{
+ *   url: string;
+ *   resolve?: (filePath: string) => string;
+ * }} TImportMeta
+ */
+/**
+ * Returns `true` when the provided CommonJS module, absolute file path, or
+ * ESM `import.meta` object represents the current process entry point.
+ *
+ * This gives one API that works across both module systems:
+ * - CommonJS: `module` or `__filename`
+ * - ESM: `import.meta` or `fileURLToPath(import.meta.url)`
  *
  * Equivalent to `import.meta.main` in Deno / Bun,
  * or `process.argv[1] === fileURLToPath(import.meta.url)` in ESM.
  *
- * @param {Partial<NodeJS.Module> | string} modOrFilePath
- *   Pass `module` or `__filename` (CommonJS),
- *   or `fileURLToPath(import.meta.url)` (ESM).
+ * @param {Partial<NodeJS.Module> | TImportMeta | string} modOrPathOrMeta
+ *   Pass `module` or `__filename` from CommonJS,
+ *   or `import.meta` / `fileURLToPath(import.meta.url)` from ESM.
  * @returns {boolean} `true` if the calling module is the entry point.
  *
  * @example
@@ -80,7 +94,12 @@ const cursor = (enabled, output = process.stderr) => {
  * if (isMain(__filename)) { main(); }
  *
  * @example
- * // ESM — via fileURLToPath:
+ * // ESM — via import.meta object:
+ * import { isMain } from "js-dev-tool/common";
+ * if (isMain(import.meta)) { main(); }
+ *
+ * @example
+ * // ESM — via fileURLToPath(import.meta.url):
  * import { isMain } from "js-dev-tool/common";
  * import { fileURLToPath } from "node:url";
  * if (isMain(fileURLToPath(import.meta.url))) { main(); }
@@ -89,11 +108,18 @@ const cursor = (enabled, output = process.stderr) => {
  * @verified CJS: Confirmed working on Node.js v11.15.0 — v26.3.0.
  * @verified ESM: Confirmed working on Node.js v12.22.11 — v26.3.0.
  */
-function isMain(modOrFilePath) {
-  if (typeof modOrFilePath === "string") {
-    return process.argv[1] === modOrFilePath;
+function isMain(modOrPathOrMeta) {
+  /** @type {string=} */
+  let pathString;
+  if (typeof modOrPathOrMeta === "string") {
+    pathString = modOrPathOrMeta;
+  } else if ("url" in modOrPathOrMeta /* && "resolve" in modOrPathOrMeta */) {
+    pathString = fileURLToPath(modOrPathOrMeta.url);
+  }
+  if (pathString) {
+    return process.argv[1] === pathString;
   }
-  return require.main === modOrFilePath;
+  return require.main === modOrPathOrMeta;
 }
 module.exports = {
   checkParentDirectory,

package/extras/gzip-tool.js

@@ -49,11 +49,16 @@ function toBase64SourceLiteral(rawData, wrapSize = 100) {
   if (wrapSize > 2048) throw new Error(`"wrapSize" is expected to be 2048 or less - ${wrapSize}`);
   if (wrapSize < 1) throw new Error(`A wrapSize of 0 or less will result in an infinite loop, so please make it 1 or greater. - ${wrapSize}`);
   const base64 = Buffer.from(rawData).toString("base64");
-  let wrapped = "";
-  for (let offset = 0, L = base64.length; offset < L;) {
-    wrapped += `${base64.slice(offset, offset += wrapSize)}\\\n`;
+  const L = base64.length;
+  if (!L) return "";
+  let wrapped = "", lineSuffix = "\\\n";
+  for (let offset = 0; offset < L;) {
+    if (
+      (offset + wrapSize) >= L
+    ) lineSuffix = "";
+    wrapped += (base64.slice(offset, offset += wrapSize) + lineSuffix);
   }
-  return wrapped.slice(0, -2);
+  return wrapped;
 }
 module.exports = {
   gzip, toBase64SourceLiteral

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-dev-tool",
-  "version": "1.2.19",
+  "version": "1.2.21",
   "type": "commonjs",
   "bin": {
     "jstool": "tools.js",
@@ -84,7 +84,7 @@
     "!tool.sh"
   ],
   "peerDependencies": {
-    "archiver": "^4.0.1",
+    "archiver": "^7.0.1",
     "webpack": "*"
   },
   "dependencies": {
@@ -95,7 +95,7 @@
     "replace": "^1.2.2",
     "rm-cstyle-cmts": "^3.4.4",
     "terser": "^5.48.0",
-    "tin-args": "^0.1.6",
+    "tin-args": "^0.1.7",
     "ts-cc-map": "^1.1.0"
   }
 }

package/progress/index.js

@@ -14,6 +14,7 @@ const {
   wppHandlerV4,
   isWebpackV5later,
 } = require("./progress-extras");
+const _log = console.log;
 /**
  *
  * @param {string[]} frames progress frame.
@@ -106,7 +107,7 @@ const createProgressObject = (frames, formatOpt, messageEmitter) => {
      * adjust to next line
      */
     newLine() {
-      console.log();
+      _log();
     },
     /**
      * change the fps rate
@@ -204,7 +205,7 @@ function createWebpackProgressPluginHandler(
   {
     const shortenProgress = (/** @type {number} */ pct) => {
       renderer(formatPercentage(pct));
-      pct === 1 && (console.log(), (dotted = 0));
+      pct === 1 && (_log(), (dotted = 0));
     };
     if (logFilePath !== void 0) {
       const wppLogger = lib.createLogStreamAndResolvePath(logFilePath);

package/progress/progress-extras.js

@@ -8,6 +8,7 @@
 /// <reference path="./index.d.ts"/>
 "use strict";
 const lib = require("../common");
+const _log = console.log;
 const checkENV = () => {
   const env = process.env;
   if (env.CI) return "ci";
@@ -32,7 +33,7 @@ const wppHandlerV4 = ((renderer, cwd) => {
         message +
         ` [${modules}, ${actives}] ${path}`,
     );
-    percentage === 1 && console.log();
+    percentage === 1 && _log();
   };
 })(lib.renderLine, process.cwd());
 /** @type {TWebpackProgressHandler} */
@@ -46,7 +47,7 @@ const wppHandlerV5 = ((renderer/*, cwd*/) => {
     renderer(
       `pct: ${(percentage * 100).toFixed(4)}%, process: [${message}]${pathOrPluginName ? `, info: [${pathOrPluginName}]` : ""}${args.length ? " - " : ""}${args[0]?.slice(args[0].length - maxLen) || ""}`,
     );
-    percentage === 1 && console.log();
+    percentage === 1 && _log();
   };
 })(lib.renderLine/*, process.cwd()*/);
 /** @type {boolean} */

package/tool-lib/cjbm.js

@@ -109,8 +109,9 @@ function getReplacer(ext) {
 }
 /**
  * @param {string} ext
+ * @param {NsJsTool.TDevConsole} logger
  */
-const emitProcessCallback = (ext) => {
+const emitProcessCallback = (ext, logger) => {
   /**
    * @param {string[]} sourceFiles
    */
@@ -126,7 +127,7 @@ const emitProcessCallback = (ext) => {
           fs.rename(sourceFile, afterPath, err => {
             if (err) console.error(err);
             else {
-              console.log(`renamed: ${sourceFile} => ${afterPath}`);
+              logger.log(`renamed: ${sourceFile} => ${afterPath}`);
             }
           });
         }
@@ -143,7 +144,7 @@ module.exports = () => {
     /**
      * about regex: see [[tools.js] regex - (C)onvert (J)S to (B)rowser (M)odule](https://regex101.com/r/EpuQLT/37)
      */
-    fn() {
+    fn(logger) {
       const bases = getBasePaths();
       const ext = params.ext || "js";
       /**
@@ -157,22 +158,25 @@ module.exports = () => {
           return data.replace(reImportExportDetection, getReplacer(ext));
         }, {
           bases,
-          cb: emitProcessCallback(ext)
+          cb: emitProcessCallback(ext, logger)
         },
       );
     },
     get help() {
-      return `${this.taskName}
-  ex - jstool -cmd cjbm [-root ./build | -basePath "./dist/esm,extra-tests/mini-semaphore"] [-ext js] [-test /\\.js$/] [-targets "['core.js', 'object.js']"]
-  note:
-    root     - Recursively searches for files.
-               This option is useful, but if there are directories that need to be avoided, use the 'basePath' option
-    basePath - can be "<path>,<path>,..." (array type arg)
-    ext      - specifies the module extension for import/export clauses. default is "js"
-    test     - Any file extension can be specified. (The default is /\\.js$/)
-    targets  - specify this if you want to apply it only to a specific file.
-               the file specified here should be directly under \`basePath\`!
-               value must be array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."
+      const level = 16;
+      return `jstool -cmd cjbm [-root "./build" | -basePath "./dist/esm,extra-tests/mini-semaphore"] [-ext "js"] [-test "/\\.js$/"] [-targets "['core.js', 'object.js']"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"cjbm".cyan} ${"-basePath".green} ${"dist/esm,extra-tests/mini-semaphore".gray(level)} ${"-targets".green} ${"core.js,object.js".gray(level)}
+
+${"  Options:".red}
+  ${"  root".cyan}      ${`: Recursively scan a single root directory.`.gray(level)}
+  ${"  basePath".cyan}  ${`: Source directory path(s). Use this when you want tighter scan control.`.gray(level)}
+  ${"  ext".cyan}       ${`: Module extension used in import/export clauses. default is "js".`.gray(level)}
+  ${"  test".cyan}      ${`: Target file matcher. default is /\\.js$/.`.gray(level)}
+  ${"  targets".cyan}   ${`: Limit processing to specific files directly under basePath.`.gray(level)}
+
+${"  Note:".magenta} ${`targets accepts comma-separated values or array type arg such as "['core.js','object.js']".`.gray(level)}
 `;
     },
   };

package/tool-lib/cmt-trick.js

@@ -12,10 +12,10 @@
  * @file comment trick toggle
  */
 /**
- *
  * @param {string} code
+ * @param {NsJsTool.TDevConsole} logger
  */
-function cleanup(code) {
+function cleanup(code, logger) {
   const reCleanUp = new RegExp(
     "\s*\/(?:\s*\/+\*\s+(?:ctt|comment-toggle-trick|https:\/\/coderwall)([\s\S]+?)(?:\s+)\/\*\/[\s\S]+|\s*\*\s+(?:ctt|comment-toggle-trick|https:\/\/coderwall)[\s\S]+\/\*\/([\s\S]+?))\s*\/{2,}\*\/", "g"
   );
@@ -25,12 +25,13 @@ function cleanup(code) {
 }
 /**
  * @param {string} code
+ * @param {NsJsTool.TDevConsole} logger
  */
-function doIt(code) {
+function doIt(code, logger) {
   return code.replace(
     /\/+(?=\*\s?(ctt|comment-toggle-trick|https:\/\/coderwall))/g, ($0) => {
       const slashes = $0.length === 2 ? "/" : "//";
-      console.log(
+      logger.log(
         "the-comment-toggle-trick: %s",
         /*enableBefore*/ slashes.length === 2
           ? "-->enable before<--, mute after"
@@ -47,24 +48,28 @@ function doIt(code) {
 module.exports = () => {
   return {
     taskName: "comment trick toggle",
-    fn(mode) {
+    fn(logger, mode) {
       processSources(
         /** @type {string} */ (this.taskName), (code) => {
-          return mode === "clean" ? cleanup(code) : doIt(code);
+          return mode === "clean" ? cleanup(code, logger) : doIt(code, logger);
         }, {
           ...params,
         },
       );
     },
     get help() {
-      return `Do comment trick toggle
-  It recognizes three markers: \`ctt | comment-toggle-trick | https://coderwall\`
-  jstool -cmd cmtTrick[:clean] (-base <source dir> | -bases "<source dir>,<source dir>,...") [-test re/\\\\.js$/]
-  note:
-    :clean - remove comment token etc leaving the currently enabled code
-    base (or root) - scan single source folder
-    bases          - must be array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."
-    test           - terget extension, default is /\\\\.js$/
+      const level = 16;
+      return `jstool -cmd cmtTrick[:clean] (-basePath "<source dir>" | -basePath "<source dir>,<source dir>,...") [-test "re/\\\\.js$/"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"cmtTrick:clean".cyan} ${"-basePath".green} ${"src,examples".gray(level)} ${"-test".green} ${"re/\\\\.js$/".gray(level)}
+
+${"  Options:".red}
+  ${"  :clean".cyan}     ${`: Remove comment tokens and leave the currently enabled code.`.gray(level)}
+  ${"  basePath".cyan}   ${`: Source directory path(s). Comma-separated or array type arg is accepted.`.gray(level)}
+  ${"  test".cyan}       ${`: Target file matcher. default is /\\\\.js$/.`.gray(level)}
+
+${"  Note:".magenta} ${`Recognized markers: ctt | comment-toggle-trick | https://coderwall`.gray(level)}
 `;
     },
   };

package/tool-lib/ps.js

@@ -21,8 +21,9 @@ module.exports = {
   /**
    * @param {import("fs")} fs
    * @param {import("../utils")} utils
+   * @param {NsJsTool.TDevConsole} logger
    */
-  globalize: (fs, utils) => {
+  globalize: (fs, utils, logger) => {
     /**
      * @param {string} dir
      * @param {string[]} sourceFiles
@@ -32,12 +33,12 @@ module.exports = {
     const visitDirectory = (dir, sourceFiles, testRe, recurse) => {
       if (dir.length) {
         if (!fs.existsSync(dir)) {
-          console.info(`directory: [${dir}] is not found`);
+          console.warn(`directory: [${dir}] is not found`);
         } else {
           utils.walkDirSync(dir, (dirent) => {
             const currentPath = `${dir}/${dirent.name}`;
             if (dirent.isFile() && testRe.test(dirent.name)) {
-              DEBUG && console.log("processSources::", dirent.name);
+              DEBUG && logger.log("processSources::", dirent.name);
               sourceFiles.push(currentPath);
             } else if (recurse && dirent.isDirectory()) {
               visitDirectory(currentPath, sourceFiles, testRe, true);
@@ -72,8 +73,8 @@ module.exports = {
         sourceFiles = [];
         const reFile = params.test || test;
         const actualBases = isArray(bases) ? bases : [base];
-        DEBUG && console.log("processSources::", actualBases, reFile);
-        DEBUG && console.log("processSources::re", reFile, reFile.constructor);
+        DEBUG && logger.log("processSources::", actualBases, reFile);
+        DEBUG && logger.log("processSources::re", reFile, reFile.constructor);
         if (root) {
           visitDirectory(root.trim(), sourceFiles, reFile, true);
         } else {
@@ -88,7 +89,7 @@ module.exports = {
         }
       }
       sourceFiles = sourceFiles.filter(Boolean);
-      DEBUG && console.log("processSources::processSources:", sourceFiles);
+      DEBUG && logger.log("processSources::processSources:", sourceFiles);
       let count = sourceFiles.length;
       let written = 0;
       /** @type {() => void} */

package/tool-lib/rws.js

@@ -49,18 +49,29 @@ const decrementVersion = (nversionArray) => {
  * + Too many record entries can be hard to see,  
  *   so if there are more than 10 entries, they will be truncated.
  * @param {TVersionRecords} record
+ * @param {number=} [max=5]
  */
-const shortenRecord = (record) => {
+const shortenRecord = (record, max = 5) => {
   let keys = /** @type {TVersionString[]} */ (Object.keys(record));
-  if (keys.length > 10) {
-    keys = keys.slice(keys.length - 10);
+  if (typeof max !== "number") {
+    console.warn(`rws::shortenRecord - "max" parameter is invalid, force set 5. (max: ${max})`);
+    max = 5;
+  } else {
+    if (!Number.isFinite(max)) max = 5;
+    else {
+      if (max < 1) max = 1;
+      else if (max > keys.length) max = keys.length;
+    }
+  }
+  if (keys.length > max) {
+    keys = keys.slice(keys.length - max);
     /** @type {TVersionRecords} */
-    const newRecord = {};
+    const shortRecord = {};
     for (let i = 0; i < keys.length; ) {
       const key = keys[i++];
-      newRecord[key] = record[key];
+      shortRecord[key] = record[key];
     }
-    return newRecord;
+    return shortRecord;
   }
   return record;
 };
@@ -72,7 +83,7 @@ const shortenRecord = (record) => {
 module.exports = (fs, utils) => {
   return {
     taskName: "(R)ecord(W)ebpack(S)ize",
-    fn() {
+    fn(logger) {
       const versionSourcePath = params.versionSource || "./package.json";
       /** @type {{ version: TVersionString }} */
       const thisPackage = utils.readJson(versionSourcePath);
@@ -139,7 +150,7 @@ module.exports = (fs, utils) => {
         if (prevEntry) {
           if (isDiff(prevEntry, entry)) {
             sizeRecord[versionStr] = entry;
-            utils.log(shortenRecord(sizeRecord));
+            utils.log(shortenRecord(sizeRecord, params.printMax));
             msg = "[%s] is updated";
           } else {
             needWrite = false;
@@ -163,15 +174,21 @@ module.exports = (fs, utils) => {
       }
     },
     get help() {
-      return `${this.taskName}
-  ex - jstool -cmd rws [-versionSource "<version source path>"] [-webpack lib/webpack.js -umd umd/webpack.js -dest "./dev-extras/webpack-size.json"] [-rws-tags "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"]
-  note:
-    versionSource - JSON file path used to read the "version" field. if not specified then apply "./package.json"
-    webpack  - if not specified then apply "./dist/webpack/index.js"
-    umd      - if not specified then apply "./dist/umd/index.js"
-    bin      - if not specified then apply "./dist/bin/index.js"
-    rws-tags - It is treated as parameter array separated by ":", e.g - "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"
-    dest     - if not specified then apply "./logs/webpack-size.json"
+      const level = 16;
+      return `jstool -cmd rws [-versionSource "./package.json"] [-webpack "./dist/webpack/index.js" -umd "./dist/umd/index.js" -bin "./dist/bin/index.js"]\\
+  [-dest "./logs/webpack-size.json"] [-printMax 5] [-rws-tags "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"rws".cyan} ${"-versionSource".green} ${"packages/web/package.json".gray(level)} ${"-dest".green} ${"./dev-extras/webpack-size.json".gray(level)}
+
+${"  Options:".red}
+  ${"  versionSource".cyan}  ${`: JSON file path used to read the "version" field. default is "./package.json"`.gray(level)}
+  ${"  webpack".cyan}        ${`: Source path for the webpack bundle. default is "./dist/webpack/index.js"`.gray(level)}
+  ${"  umd".cyan}            ${`: Source path for the UMD bundle. default is "./dist/umd/index.js"`.gray(level)}
+  ${"  bin".cyan}            ${`: Source path for the bin bundle. default is "./dist/bin/index.js"`.gray(level)}
+  ${"  dest".cyan}           ${`: Output path of the size record JSON. default is "./logs/webpack-size.json"`.gray(level)}
+  ${"  printMax".cyan}       ${`: Max number of record entries shown in the preview log. default is 5`.gray(level)}
+  ${"  rws-tags".cyan}       ${`: Extra tag:path pairs separated by ",". e.g. "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"`.gray(level)}
 `;
     },
   };

package/tool-lib/tools.d.ts

@@ -6,6 +6,7 @@
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
 /// <reference types="literate-regex/global"/>
+/// <reference types="tin-args" preserve="true"/>
 /**
  * @date 2023-10-25
  */
@@ -19,7 +20,7 @@ declare global {
     declare type TStringReplacer = (matchs: string, ...args: any[]) => string;
     /** use `(R)ecord(W)ebpack(S)ize` */
     declare type TRwsTags = "webpack" | "umd" | "bin";
-    declare var params: ReturnType<typeof import("tin-args")<TToolArgs>>;
+    declare var params: NsTinArgs.TTinArgsReturnType<TToolArgs>;
     declare var isArray: typeof Array.isArray;
     /**
      * @date 2025/2/18 0:46:03
@@ -65,6 +66,8 @@ declare global {
         minor?: true;
         patch?: true;
         extras: string[];
+        /** rws */
+        printMax?: number;
         /** rws, backup */
         dest: string;
         /** backup */
@@ -135,7 +138,7 @@ declare global {
         cb?: (sourceFiles: string[]) => void
     }
     declare type TJSToolEntry = {
-        fn: (mode?: string) => void;
+        fn: (logger: NsJsTool.TDevConsole, mode?: string) => void;
         help: string;
         taskName: string;
     }
@@ -145,5 +148,13 @@ declare global {
     declare type TVersionString = `${number}.${number}.${number}${string}`;
     declare type TVersionRecords = Record<TVersionString, Partial<Record<TRwsTags, number>>>;
     declare type TSizeRecordEntry = TVersionRecords["0.0.0"];
+    declare namespace NsJsTool {
+      type TDevConsole = {
+        log: Console["log"];
+        warn: Console["warn"];
+        error: Console["error"];
+        info: Console["info"];
+      };
+    }
 }
-export = {};
+export {};

package/tool-lib/zip-task.js

@@ -19,7 +19,7 @@ module.exports =
   (utils) => {
     return {
       taskName: "zip",
-      fn() {
+      fn(logger) {
         const comment = params.comment;
         const paths = params.args;
         if (Array.isArray(paths)) {
@@ -29,8 +29,18 @@ module.exports =
           }
         }
       },
-      help: `jstool -cmd zip [-comment "the comment"] lib/webpack.js lib/type-ids.js
-  It is possible to create zip files with comments
-`,
+      get help() {
+        const level = 16;
+        return `jstool -cmd zip [-comment "the comment"] lib/webpack.js lib/type-ids.js
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"zip".cyan} ${"-comment".green} ${"release artifact".gray(level)} ${"lib/webpack.js lib/type-ids.js".gray(level)}
+
+${"  Options:".red}
+  ${"  comment".cyan}  ${`: ZIP comment string embedded into the output archive.`.gray(level)}
+
+${"  Note:".magenta} ${`Pass target file paths as args after the options.`.gray(level)}
+`;
+      },
     };
   };

package/tools.js

@@ -18,8 +18,25 @@ const utils = require("./utils");
 global.params = require("tin-args")();
 global.verbose = params.verb;
 global.isArray = Array.isArray;
-require("./tool-lib/ps").globalize(fs, utils);
-utils.log(params);
+/**
+ * @date 2026/06/27 15:59:10
+ * @since v1.5.23-dev
+ * @type {NsJsTool.TDevConsole}
+ */
+const devLogger = (() => {
+  const emptyLogger = /** @type {NsJsTool.TDevConsole} */({
+    log() {},
+    info() {},
+    warn() {},
+    error() {},
+  });
+  if (process.env.CI) return emptyLogger;
+  return params.verb ? console : emptyLogger;
+})();
+/** shorthand of __`console.log`__ */
+const _log = console.log;
+if (verbose) utils.log(params);
+require("./tool-lib/ps").globalize(fs, utils, devLogger);
 /**
  * how to config terser, see {@link https://github.com/terser/terser#minify-options-structure Minify options structure}
  *
@@ -78,7 +95,7 @@ const ToolFunctions = {
    */
   replace: {
     taskName: "replace",
-    fn() {
+    fn(logger) {
       const re = params.regex;
       const after = params.after || "";
       let targets = params.args || params.targets
@@ -91,26 +108,27 @@ const ToolFunctions = {
       }
     },
     get help() {
+      const level = 16;
       return `jstool -cmd replace [-after <replacement>] -regex \"/^\\s+<!--[\\s\\S]+?-->(?:\\r?\\n)?/gm\" [-targets "<path>,<path>,..." | <args: file, file file...>]
 
 ${"  Options:".red}
-  ${"  after".cyan}  ${`: If omitted, "" (empty string) is used, meaning that the matched string is deleted.`.gray(16)}
-  ${"  targets".cyan}${`: Single path string or Array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."`.gray(16)}
+  ${"  after".cyan}  ${`: If omitted, "" (empty string) is used, meaning that the matched string is deleted.`.gray(level)}
+  ${"  targets".cyan}${`: Single path string or Array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."`.gray(level)}
 
-${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${`
+${"  remarks".magenta}${": targets - can use args parameter instead".gray(level)}${`
     It is better to use the <args: file, file file...>
-    e.g - ${"jstool".yellow} ${"-cmd".green} ${"replace".cyan} ${"-after".green} ${`".."`.red} ${"-regex".green} ${String.raw`'re/(?<=reference path=")(\.)(?=\/index.d.ts")/'`.magenta} ${"build/**/*.js".gray(16)}
+    e.g - ${"jstool".yellow} ${"-cmd".green} ${"replace".cyan} ${"-after".green} ${`".."`.red} ${"-regex".green}=${String.raw`'r/(?<=reference path=")(\.)(?=\/index.d.ts")/'`.magenta} ${"build/**/*.js".gray(level)}
                                                                                                   ^^^^^^^^^^^^^
-`.gray(16)}`;
+`.gray(level)}`;
     },
   },
   version: {
     taskName: "version",
-    fn() {
+    fn(logger) {
       let { major, minor /*, patch*/, pkgJsons = ["./package.json"] } = params;
       /** @type {string} */
       let currentVersion;
-      /** @type {string} */
+      /** @type {string=} */
       let nextVersion;
       !isArray(pkgJsons) && (pkgJsons = [pkgJsons]);
       utils.fireReplace(
@@ -156,18 +174,28 @@ ${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${
           paths,
         );
       }
-      // @ts-ignore
       console.log("version updated: %s", nextVersion);
     },
-    help: `jstool -cmd version [-major | -minor] [-pkgJsons "./package.json,../package.json"] [-extras "test/web/index.html"]
-  bump top level package.json version(can specify "package.json" paths by \`pkgJsons\` option if need), specify patch version is unnecessary.
-  note:
-    extras - can be "<path>,<path>,..." (array type arg)
-`,
+    get help() {
+      const level = 16;
+      return `jstool -cmd version [-major | -minor] [-pkgJsons "./package.json,../package.json"] [-extras "test/web/index.html"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"version".cyan} ${"-minor".green} ${"-extras".green} ${"README.md,test/web/index.html".gray(level)}
+
+${"  Options:".red}
+  ${"  major".cyan}     ${`: Bump major version and reset minor/patch to 0.`.gray(level)}
+  ${"  minor".cyan}     ${`: Bump minor version and reset patch to 0.`.gray(level)}
+  ${"  pkgJsons".cyan}  ${`: Target package.json path(s). Comma-separated or array type arg is accepted.`.gray(level)}
+  ${"  extras".cyan}    ${`: Additional files whose version strings should be replaced too.`.gray(level)}
+
+${"  Note:".magenta} ${`If neither -major nor -minor is specified, patch version is bumped.`.gray(level)}
+`;
+    },
   },
   minify: {
     taskName: "minify",
-    fn() {
+    fn(logger) {
       const Terser = require("terser");
       const sx = params.suffix;
       let suffix = ".mini";
@@ -195,12 +223,19 @@ ${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${
         opt,
       );
     },
-    help: `jstool -cmd minify -basePath extra-tests/web/mini-semaphore [-test "re/\\.js$/"] [-suffix ".mini"]
-  note:
-    basePath - can be "<path>,<path>,..." (array type arg)
-    test     - can be omit, default is \`/\\.js$/\`
-    suffix   - can be omit, default is ".mini"
-`,
+    get help() {
+      const level = 16;
+      return `jstool -cmd minify -basePath "extra-tests/web/mini-semaphore" [-test "re/\\.js$/"] [-suffix ".mini"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"minify".cyan} ${"-basePath".green} ${"dist/esm,dist/cjs".gray(level)} ${"-suffix".green} ${".min".gray(level)}
+
+${"  Options:".red}
+  ${"  basePath".cyan}  ${`: Source directory path(s). Comma-separated or array type arg is accepted.`.gray(level)}
+  ${"  test".cyan}      ${`: Target file matcher. default is /\\.js$/.`.gray(level)}
+  ${"  suffix".cyan}    ${`: Output suffix inserted before ".js". default is ".mini".`.gray(level)}
+`;
+    },
   },
   /**
    * NOTE: keep comment that start with "/&#42;" when "&#42;/" end mark appears in same line.
@@ -209,12 +244,12 @@ ${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${
    */
   rmc: {
     taskName: "rm-cstyle-cmts",
-    fn() {
+    fn(logger) {
       rmc.reset();
       if (params.rmc4ts) {
         const keepBangLine = params.rmc4ts === "keepBangLine";
         const reMultiLineChcker = /^\/\*(\*|!)\s|^\/\*(?!-).+\*\/$/;
-        const reSingleLineChecer = /^\/\/+!/;
+        const reSingleLineChecer = /^(?:\/\/+!)/;
         rmc.setListener(({ event, fragment }) => {
           if (event === /*EScannerEvent.MultiLineComment*/ 1) {
             return reMultiLineChcker.test(fragment);
@@ -240,16 +275,23 @@ ${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${
         },
       );
     },
-    help: `$ jstool -cmd rmc [-rmc4ts[:keepBangLine]] -basePath "./dist/cjs,./dist/cjs/gulp" -test "/\\.(js|d\\.ts)$/"
-  note: basePath - can be "<path>,<path>,..." (array type arg)
-    test  - can be omit, defulat \`/\.js$/\`
-    rmc4ts- for typescript source.
-      keep comment that start with "/*" when "*/" end mark appears in same line.
-      if start with "/*-" remove it
-      keep leading "/// <reference ...>" directives above a top-level "use strict" line in CJS emit.(2026/02/03)
-    rmc4ts=keepBangLine (2025/12/24)
-          - In addition to the "rmc4ts" processing, it also preserves line comments that start with "//!".
-`,
+    get help() {
+      const level = 16;
+      return `jstool -cmd rmc [-rmc4ts[:keepBangLine]] -basePath "./dist/cjs,./dist/cjs/gulp" [-test "/\\.(js|d\\.ts)$/"] [-suffix ".clean"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"rmc".cyan} ${"-rmc4ts:keepBangLine".green} ${"-basePath".green} ${"dist/cjs,dist/cjs/gulp".gray(level)} ${"-test".green} ${"/\\.(js|d\\.ts)$/".gray(level)}
+
+${"  Options:".red}
+  ${"  basePath".cyan}  ${`: Source directory path(s). Comma-separated or array type arg is accepted.`.gray(level)}
+  ${"  test".cyan}      ${`: Target file matcher. default is /\\.js$/.`.gray(level)}
+  ${"  suffix".cyan}    ${`: Output suffix inserted before ".js" when needed.`.gray(level)}
+  ${"  rmc4ts".cyan}    ${`: TypeScript-oriented mode. Preserves single-line /* */ comments except ones that start with "/*-".`.gray(level)}
+
+${"  Extra:".magenta} ${`rmc4ts:keepBangLine also preserves line comments that start with "//!".`.gray(level)}
+${"  Extra:".magenta} ${`Leading /// <reference ...> directives are kept above a top-level "use strict" line in CJS output.`.gray(level)}
+`;
+    },
   },
   zip: require("./tool-lib/zip-task")(utils),
 };
@@ -298,25 +340,25 @@ function isJSToolEntry(entry) {
  */
 function printHelp(cmd) {
   const entry = ToolFunctions[cmd];
-  console.log(`${cmd.yellow + " help:".green} ${entry.help.gray(8)}`);
+  _log(`${cmd.yellow + " help:".green} ${entry.help.gray(8)}`);
 }
 if (params.cmd) {
   const [task, mode] = params.cmd.split(":");
   const entry = ToolFunctions[task];
-  isJSToolEntry(entry) && entry.fn(mode);
+  isJSToolEntry(entry) && entry.fn(devLogger, mode);
 } else if (params.shell) {
   const SCRIPT_DIR = path.dirname(process.argv[1]);
   const arg = `${params.major ? "-major" : params.minor ? "-minor" : ""}`;
   utils.execWithOutputResult(
     `bash ${SCRIPT_DIR}/scripts/tool.sh ${params.shell} ${arg}`,
     (result) => {
-      console.log(result);
+      _log(result);
     },
     process.cwd(),
   );
 } else if (params.v) {
   const thisVersion = require("./package.json").version;
-  console.log(
+  _log(
     `${"jstool".magenta} in "js-dev-scripts", version: ${thisVersion.green}
 more details see ${"https://github.com/jeffy-g/js-dev-scripts".blue}`,
   );
@@ -327,7 +369,7 @@ more details see ${"https://github.com/jeffy-g/js-dev-scripts".blue}`,
       printHelp(cmdName);
     } else {
       const commands = Object.keys(ToolFunctions);
-      console.log(`
+      _log(`
 Usage: node jstool -cmd <command name>
     - - - - available commands:`);
       for (const cmd of commands) {

package/utils.js

@@ -27,6 +27,7 @@ const lib = require("./common");
 const tinArgs = require("tin-args");
 const { listDependenciesOf } = require("./extras/list-deps-of");
 const CI = !!process.env.CI;
+const _log = console.log;
 /**
  * Nothing is logged in a CI environment.
  */
@@ -53,7 +54,6 @@ function extractVersion(versionString = process.version) {
   const [major = 0, minor = 0, patch = 0] = pv ? pv.map((value, i) => {
     return (i > 0 && +value) || void 0;
   }).slice(1) : [];
-  console.log("result:", major, minor, patch);
   return { major, minor, patch };
 }
 /**
@@ -257,16 +257,16 @@ function compressScript(scriptPath, comment = "") {
     compressionMethod: zlibZip.CompressionMethod.DEFLATE,
     os: zlibZip.OperatingSystem.MSDOS,
   });
-  console.log(`added ${scriptPath} to zip`);
-  console.log("start compress...");
+  _log(`added ${scriptPath} to zip`);
+  _log("start compress...");
   console.time("zip:compress");
   const compressed = zip.compress();
   console.timeEnd("zip:compress");
-  console.log("compress done.\n");
+  _log("compress done.\n");
   const pp = path.parse(scriptPath);
   const output = `${pp.dir ? pp.dir + "/" : ""}${pp.name}.zip`;
   fs.writeFile(output, compressed, (err) => {
-    console.log(`\nzip file created, error: ${err}\n => ${output}`);
+    _log(`\nzip file created, error: ${err}\n => ${output}`);
   });
 }
 /**
@@ -283,16 +283,16 @@ function compressScript2(scriptPath, comment = "") {
   const pp = path.parse(scriptPath);
   const output = fs.createWriteStream(`${pp.dir}/${pp.name}.zip`);
   output.on("close", function () {
-    console.log(archive.pointer() + " total bytes");
-    console.log(
+    _log(archive.pointer() + " total bytes");
+    _log(
       "archiver has been finalized and the output file descriptor has closed.",
     );
   });
   output.on("end", function () {
-    console.log("Data has been drained");
+    _log("Data has been drained");
   });
   archive.on("progress", (progress) => {
-    console.log(progress.entries.processed);
+    _log(progress.entries.processed);
   });
   archive.pipe(output);
   archive.file(scriptPath, {
@@ -313,7 +313,7 @@ function compressScript2(scriptPath, comment = "") {
  * @param {(result: string) => void} doneCallbackWithArgs gulp callback function.
  */
 function execWithOutputResult(command, doneCallbackWithArgs, cwd) {
-  console.log();
+  _log();
   const { exec } = require("child_process");
   return exec(command, { cwd }, (err, stdout /* , stderr */) => {
     if (err) {
@@ -423,7 +423,7 @@ function copyText(content, message = "text copied!", chcp65001 = true) {
       if (err) {
         console.error(err);
       } else {
-        console.log(message, stdout);
+        _log(message, stdout);
       }
     });
     // @ts-ignore