@vbarbarosh/node-helpers 3.72.3 → 3.72.5

package/README.md

@@ -20,7 +20,7 @@ npm install @vbarbarosh/node-helpers
 A subset of `@vbarbarosh/node-helpers` is available for browser:
 
 ```html
-<script src="https://unpkg.com/@vbarbarosh/node-helpers@3.72.3/dist/browser.js"></script>
+<script src="https://unpkg.com/@vbarbarosh/node-helpers@3.72.5/dist/browser.js"></script>
 ```
 
 ⚠️ All browser functions are exposed globally.

package/dist/browser.js

@@ -72,10 +72,10 @@ function serializer(replacer, cycleReplacer) {
 
 /***/ }),
 
-/***/ "./src sync recursive \\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$":
-/*!*******************************************************************************************************************************************************************************************************************************************************************************************************************************************************!*\
-  !*** ./src/ sync \b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\.test)\.js$ ***!
-  \*******************************************************************************************************************************************************************************************************************************************************************************************************************************************************/
+/***/ "./src sync recursive ^(?%21.*(cli-apps%7Cbrowser%7C\\.d)\\/).*\\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$":
+/*!**********************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************!*\
+  !*** ./src/ sync ^(?%21.*(cli-apps%7Cbrowser%7C\.d)\/).*\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\.test)\.js$ ***!
+  \**********************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************/
 /***/ ((module, __unused_webpack_exports, __webpack_require__) => {
 
 var map = {
@@ -94,8 +94,6 @@ var map = {
 	"./array_sum.js": "./src/array_sum.js",
 	"./array_unique.js": "./src/array_unique.js",
 	"./array_unique_last.js": "./src/array_unique_last.js",
-	"./cli-apps/watchdog.d/ignore_sigterm.js": "./src/cli-apps/watchdog.d/ignore_sigterm.js",
-	"./cli-apps/watchdog.d/my-ignore-sigterm.js": "./src/cli-apps/watchdog.d/my-ignore-sigterm.js",
 	"./date_add_hours.js": "./src/date_add_hours.js",
 	"./date_add_milliseconds.js": "./src/date_add_milliseconds.js",
 	"./date_add_minutes.js": "./src/date_add_minutes.js",
@@ -146,8 +144,6 @@ var map = {
 	"./http_put_utf8.js": "./src/http_put_utf8.js",
 	"./identity.js": "./src/identity.js",
 	"./ignore.js": "./src/ignore.js",
-	"./pid_kill_grace.d/ignore-sigterm-for-10ms.js": "./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js",
-	"./pid_kill_grace.d/ignore-sigterm.js": "./src/pid_kill_grace.d/ignore-sigterm.js",
 	"./plural.js": "./src/plural.js",
 	"./random_int.js": "./src/random_int.js",
 	"./urlmod.js": "./src/urlmod.js",
@@ -172,7 +168,7 @@ webpackContext.keys = function webpackContextKeys() {
 };
 webpackContext.resolve = webpackContextResolve;
 module.exports = webpackContext;
-webpackContext.id = "./src sync recursive \\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$";
+webpackContext.id = "./src sync recursive ^(?%21.*(cli-apps%7Cbrowser%7C\\.d)\\/).*\\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$";
 
 /***/ }),
 
@@ -648,116 +644,6 @@ function array_unique_last(array, fn = identity)
 module.exports = array_unique_last;
 
 
-/***/ }),
-
-/***/ "./src/cli-apps/watchdog.d/ignore_sigterm.js":
-/*!***************************************************!*\
-  !*** ./src/cli-apps/watchdog.d/ignore_sigterm.js ***!
-  \***************************************************/
-/***/ (() => {
-
-//#!/usr/bin/env node
-
-// 1️⃣ Client that ignores SIGTERM
-// Goal: process stays alive after SIGTERM and only dies on SIGKILL (exactly what pid_kill_grace should handle).
-//
-// What this tests for watchdog:
-//   - watchdog sends SIGTERM → process prints “ignored” and keeps running.
-//   - pid_kill_grace waits grace_timeout_ms, sees PID still alive, sends SIGKILL.
-//   - Process must die after SIGKILL.
-//   - Watchdog should log the whole sequence correctly.
-// This is a realistic scenario.
-
-console.log('PID:', process.pid);
-
-// Ignore SIGTERM
-process.on('SIGTERM', function () {
-    console.log('SIGTERM received, but intentionally ignored');
-});
-
-// Still react to SIGINT (Ctrl+C) so you can stop it manually if needed
-process.on('SIGINT', function () {
-    console.log('SIGINT received, exiting');
-    process.exit(130);
-});
-
-// Keep process alive
-setInterval(() => {
-    // simulate work
-}, 1000);
-
-
-/***/ }),
-
-/***/ "./src/cli-apps/watchdog.d/my-ignore-sigterm.js":
-/*!******************************************************!*\
-  !*** ./src/cli-apps/watchdog.d/my-ignore-sigterm.js ***!
-  \******************************************************/
-/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
-
-//#!/usr/bin/env node
-
-const Promise = __webpack_require__(/*! bluebird */ "bluebird");
-const cli = __webpack_require__(/*! @vbarbarosh/node-helpers/src/cli */ "./src/cli.js");
-const now_human = __webpack_require__(/*! @vbarbarosh/node-helpers/src/now_human */ "./src/now_human.js");
-
-cli(main);
-
-async function main()
-{
-    process.on('SIGTERM', function () {
-        console.log(`[${now_human()}][ignore-sigterm] SIGTERM, ignoring...`);
-    });
-    process.on('SIGINT', function () {
-        console.log(`[${now_human()}][ignore-sigterm] SIGINT, ignoring...`);
-    });
-
-    for (let iter = 1, last = 100; iter <= last; ++iter) {
-        console.log(`[${now_human()}][ignore-sigterm] ${iter} of ${last}`);
-        await Promise.delay(100);
-    }
-}
-
-
-/***/ }),
-
-/***/ "./src/cli.js":
-/*!********************!*\
-  !*** ./src/cli.js ***!
-  \********************/
-/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
-
-const ExitCodeError = __webpack_require__(/*! ./errors/ExitCodeError */ "./src/errors/ExitCodeError.js");
-const Promise = __webpack_require__(/*! bluebird */ "bluebird");
-
-/**
- * Entry point for Node CLI apps
- */
-function cli(main, report = error => console.error(error))
-{
-    // https://stackoverflow.com/a/46916601/1478566
-    const timer = setInterval(v => v, 1E9);
-
-    Promise.resolve(main()).then(resolve, reject);
-
-    function resolve() {
-        clearInterval(timer);
-    }
-    function reject(error) {
-        clearInterval(timer);
-        report(error);
-        if (error instanceof ExitCodeError) {
-            process.exit(error.exit_code);
-        }
-        else {
-            process.exit(1);
-        }
-    }
-}
-
-module.exports = cli;
-
-
 /***/ }),
 
 /***/ "./src/date_add_hours.js":
@@ -901,25 +787,6 @@ function date_is_leap_year(d)
 module.exports = date_is_leap_year;
 
 
-/***/ }),
-
-/***/ "./src/errors/ExitCodeError.js":
-/*!*************************************!*\
-  !*** ./src/errors/ExitCodeError.js ***!
-  \*************************************/
-/***/ ((module) => {
-
-class ExitCodeError extends Error
-{
-    constructor(exit_code, message = '') {
-        super(message);
-        this.exit_code = exit_code;
-    }
-}
-
-module.exports = ExitCodeError;
-
-
 /***/ }),
 
 /***/ "./src/factorize_ms.js":
@@ -1725,7 +1592,7 @@ const factorize_ms = __webpack_require__(/*! ./factorize_ms */ "./src/factorize_
 /**
  * Format milliseconds
  */
-function format_ms3(ms)
+function format_ms3(ms, include_zero_hours = false)
 {
     if (!ms) {
         ms = 0;
@@ -1733,7 +1600,7 @@ function format_ms3(ms)
 
     // 00:05.445
     const [h, m, s, xx] = factorize_ms(ms);
-    if (h) {
+    if (h || include_zero_hours) {
         return `0${h}:0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '');
     }
     return `0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '')
@@ -2219,99 +2086,6 @@ function math_lcm(a, b)
 module.exports = math_lcm;
 
 
-/***/ }),
-
-/***/ "./src/now_human.js":
-/*!**************************!*\
-  !*** ./src/now_human.js ***!
-  \**************************/
-/***/ ((module, __unused_webpack_exports, __webpack_require__) => {
-
-const format_date_human = __webpack_require__(/*! ./format_date_human */ "./src/format_date_human.js");
-
-function now_human()
-{
-    return format_date_human(new Date());
-}
-
-module.exports = now_human;
-
-
-/***/ }),
-
-/***/ "./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js":
-/*!*********************************************************!*\
-  !*** ./src/pid_kill_grace.d/ignore-sigterm-for-10ms.js ***!
-  \*********************************************************/
-/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
-
-//#!/usr/bin/env node
-
-const Promise = __webpack_require__(/*! bluebird */ "bluebird");
-const cli = __webpack_require__(/*! ../cli */ "./src/cli.js");
-const now_human = __webpack_require__(/*! ../now_human */ "./src/now_human.js");
-
-// Child ignores SIGTERM for 10 ms, but dies naturally before the grace loop ends
-
-cli(main);
-
-async function main()
-{
-    let timer;
-
-    process.on('SIGTERM', function () {
-        console.log(`[${now_human()}][ignore-sigterm-for-10ms] SIGTERM_ignoring...`);
-        timer ??= setTimeout(terminate, 10);
-    });
-    process.on('SIGINT', function () {
-        console.log(`[${now_human()}][ignore-sigterm-for-10ms] SIGINT_ignoring...`);
-    });
-
-    for (let iter = 1, last = 100; iter <= last; ++iter) {
-        console.log(`[${now_human()}][ignore-sigterm-for-10ms] ${iter} of ${last}`);
-        await Promise.delay(10);
-    }
-}
-
-function terminate()
-{
-    console.log(`[${now_human()}][ignore-sigterm-for-10ms] TERMINATE_AFTER_10MS`);
-    process.exit(0);
-}
-
-
-/***/ }),
-
-/***/ "./src/pid_kill_grace.d/ignore-sigterm.js":
-/*!************************************************!*\
-  !*** ./src/pid_kill_grace.d/ignore-sigterm.js ***!
-  \************************************************/
-/***/ ((__unused_webpack_module, __unused_webpack_exports, __webpack_require__) => {
-
-//#!/usr/bin/env node
-
-const Promise = __webpack_require__(/*! bluebird */ "bluebird");
-const cli = __webpack_require__(/*! ../cli */ "./src/cli.js");
-const now_human = __webpack_require__(/*! ../now_human */ "./src/now_human.js");
-
-cli(main);
-
-async function main()
-{
-    process.on('SIGTERM', function () {
-        console.log(`[${now_human()}][ignore-sigterm] SIGTERM_ignoring...`);
-    });
-    process.on('SIGINT', function () {
-        console.log(`[${now_human()}][ignore-sigterm] SIGINT_ignoring...`);
-    });
-
-    for (let iter = 1, last = 100; iter <= last; ++iter) {
-        console.log(`[${now_human()}][ignore-sigterm] ${iter} of ${last}`);
-        await Promise.delay(10);
-    }
-}
-
-
 /***/ }),
 
 /***/ "./src/plural.js":
@@ -2499,14 +2273,14 @@ var __webpack_exports__ = {};
   \******************************/
 const ns = new URL(document.currentScript.src).searchParams.get('var') ?? 'h';
 if (typeof window[ns] !== 'undefined') {
-    console.log(`❌ @vbarbarosh/node-helpers@${"3.72.3"} was not injected — window.${ns} is already in use`);
+    console.log(`❌ @vbarbarosh/node-helpers@${"3.72.5"} was not injected — window.${ns} is already in use`);
 }
 else {
-    console.log(`🎉 @vbarbarosh/node-helpers@${"3.72.3"} successfully exposed as window.${ns}`);
+    console.log(`🎉 @vbarbarosh/node-helpers@${"3.72.5"} successfully exposed as window.${ns}`);
     window[ns] = {};
     // https://github.com/webpack/webpack/issues/625
     // https://webpack.js.org/guides/dependency-management/#require-context
-    const require_tmp = __webpack_require__("./src sync recursive \\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$");
+    const require_tmp = __webpack_require__("./src sync recursive ^(?%21.*(cli-apps%7Cbrowser%7C\\.d)\\/).*\\b(array%7Cdate%7Chttp_delete%7Chttp_get_blob%7Chttp_get_buffer%7Chttp_get_json%7Chttp_get_utf8%7Chttp_head%7Chttp_patch_json%7Chttp_post_json%7Chttp_post_multipart%7Chttp_put_buffer%7Chttp_put_json%7Chttp_put_utf8%7Cidentity%7Cignore%7Cfcmp%7Cfilter%7Cformat%7Cplural%7Crandom_int%7Curlmod%7Cwaitcb)[^/]*(?<%21\\.test)\\.js$");
     require_tmp.keys().forEach(function (key) {
         const [, basename] = key.match(/([^/]+)\.js$/);
         window[ns][basename] = require_tmp(key);

package/package.json

@@ -2,7 +2,7 @@
     "author": "Vladimir Barbarosh <vladimir.barbarosh@gmail.com>",
     "license": "MIT",
     "name": "@vbarbarosh/node-helpers",
-    "version": "3.72.3",
+    "version": "3.72.5",
     "description": "A set of helpers for JavaScript/Node.js",
     "unpkg": "dist/browser.js",
     "jsdelivr": "dist/browser.js",

package/src/browser/index.js

@@ -7,7 +7,7 @@ else {
     window[ns] = {};
     // https://github.com/webpack/webpack/issues/625
     // https://webpack.js.org/guides/dependency-management/#require-context
-    const require_tmp = require.context('..', true, /\b(array|date|http_delete|http_get_blob|http_get_buffer|http_get_json|http_get_utf8|http_head|http_patch_json|http_post_json|http_post_multipart|http_put_buffer|http_put_json|http_put_utf8|identity|ignore|fcmp|filter|format|plural|random_int|urlmod|waitcb)[^/]*(?<!\.test)\.js$/);
+    const require_tmp = require.context('..', true, /^(?!.*(cli-apps|browser|\.d)\/).*\b(array|date|http_delete|http_get_blob|http_get_buffer|http_get_json|http_get_utf8|http_head|http_patch_json|http_post_json|http_post_multipart|http_put_buffer|http_put_json|http_put_utf8|identity|ignore|fcmp|filter|format|plural|random_int|urlmod|waitcb)[^/]*(?<!\.test)\.js$/);
     require_tmp.keys().forEach(function (key) {
         const [, basename] = key.match(/([^/]+)\.js$/);
         window[ns][basename] = require_tmp(key);

package/src/clamp.js

@@ -0,0 +1,6 @@
+function clamp(min, max, value)
+{
+    return Math.max(min, Math.min(max, value));
+}
+
+module.exports = clamp;

package/src/cli-apps/watchdog.d/quick-exit-after-2-pings.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+const Promise = require('bluebird');
+const cli = require('../../cli');
+const ping_socket = require('../../ping_socket');
+
+cli(main);
+
+async function main()
+{
+    for (let iter = 1, last = 2; iter <= last; ++iter) {
+        await ping_socket(process.env.WATCHDOG_SOCKET);
+        await Promise.delay(10);
+    }
+}

package/src/cli-apps/watchdog.d/quick-hang-after-1-ping.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+const Promise = require('bluebird');
+const cli = require('../../cli');
+const ping_socket = require('../../ping_socket');
+
+cli(main);
+
+async function main()
+{
+    await ping_socket(process.env.WATCHDOG_SOCKET);
+    while (true) {
+        await Promise.delay(1000);
+    }
+}

package/src/cli-apps/watchdog.js

@@ -5,14 +5,19 @@ const HeartbeatServer = require('../HeartbeatServer');
 const Promise = require('bluebird');
 const cli = require('../cli');
 const cuid = require('@paralleldrive/cuid2');
+const format_ms3 = require('../format_ms3');
+const format_thousands = require('../format_thousands');
 const make = require('@vbarbarosh/type-helpers/src/make');
-const now_human = require('../now_human');
 const pgid_exists = require('../pgid_exists');
 const pgid_kill_grace = require('../pgid_kill_grace');
 const pkg = require('../../package.json');
 const shell_spawn = require('../shell_spawn');
 
+const STARTED_AT = Date.now();
 const LOGS_ROOT_UID = cuid.createId();
+const ARGS = process.argv.slice(2);
+
+let PING_COUNTER = 0;
 
 // 💎 Only the lack of a valid PING within WATCHDOG_INTERVAL is fatal
 
@@ -31,18 +36,17 @@ cli(main, report);
 
 function report(error)
 {
-    log(`[watchdog_end_error] ${error.message}`);
+    log(`[watchdog_end_error] ${render_stats()} | ${error.message} | ${ARGS.join(' ')}`);
 }
 
 async function main()
 {
-    const args = process.argv.slice(2);
-    if (!args.length) {
+    if (!ARGS.length) {
         usage();
         process.exit(1);
     }
 
-    switch (args[0]) {
+    switch (ARGS[0]) {
     case '-v':
     case '--version':
         version();
@@ -52,18 +56,20 @@ async function main()
 
     log(`[watchdog_begin] v${pkg.version}`);
 
-    const WATCHDOG_INTERVAL = make(process.env.WATCHDOG_INTERVAL, {type: 'int', min: 1000, default: 5000});
+    const WATCHDOG_INTERVAL = process.env.__TESTING__
+        ? make(process.env.WATCHDOG_INTERVAL, {type: 'int', min: 1, default: 5000})
+        : make(process.env.WATCHDOG_INTERVAL, {type: 'int', min: 1000, default: 5000});
     const heartbeat_server = new HeartbeatServer(WATCHDOG_INTERVAL);
     const WATCHDOG_SOCKET = heartbeat_server.socket_path;
-    heartbeat_server.on('heartbeat', () => log('[watchdog_ping] ❤️'))
+    heartbeat_server.on('heartbeat', () => log(`[watchdog_ping] ❤️ ${render_stats(++PING_COUNTER)}`))
     heartbeat_server.on('warning', error => log(`[watchdog_warn] ⚠️ ${error}`))
 
     try {
-        log(`[watchdog_args] ${args.join(' ')}`);
+        log(`[watchdog_args] ${ARGS.join(' ')}`);
         log(`[watchdog_interval] ${WATCHDOG_INTERVAL}`);
         log(`[watchdog_socket_path] ${heartbeat_server.socket_path}`);
         const env = {...process.env, WATCHDOG_INTERVAL, WATCHDOG_SOCKET};
-        const proc = await shell_spawn(args, {stdio: 'inherit', env, detached: true}).init();
+        const proc = await shell_spawn(ARGS, {stdio: 'inherit', env, detached: true}).init();
         const pgid = proc.pid; // group id == leader pid
 
         const signal = new Promise(function (resolve, reject) {
@@ -94,7 +100,7 @@ async function main()
         await Promise.resolve(heartbeat_server.dispose()).timeout(1000);
     }
 
-    log('[watchdog_end_ok]');
+    log(`[watchdog_end_ok] ${render_stats()} | ${ARGS.join(' ')}`);
     process.exit(0);
 }
 
@@ -102,13 +108,18 @@ function log(s)
 {
     const ss = JSON.stringify(s).slice(1, -1).replaceAll('\\"', '"');
     if (ss[0] === '[') {
-        console.log(`[${LOGS_ROOT_UID}][${now_human()}]${ss}`);
+        console.log(`[${LOGS_ROOT_UID}][${format_ms3(Date.now() - STARTED_AT, true)}]${ss}`);
     }
     else {
-        console.log(`[${LOGS_ROOT_UID}][${now_human()}] ${ss}`);
+        console.log(`[${LOGS_ROOT_UID}][${format_ms3(Date.now() - STARTED_AT, true)}] ${ss}`);
     }
 }
 
+function render_stats()
+{
+    return `pings=${format_thousands(PING_COUNTER)}`;
+}
+
 function usage()
 {
     process.stdout.write(`

package/src/cli-apps/watchdog.test.js

@@ -1,7 +1,48 @@
 const assert = require('assert');
+const pid_exists = require('../pid_exists');
+const shell_spawn = require('../shell_spawn');
+const stream = require('stream');
+const stream_each = require('../stream_each');
+const stream_lines = require('../stream_lines');
 
 // watchdog true -> race condition; true exists too quickly; bug in shell_spawn
 
-describe.skip('watchdog', function () {
-
+describe('watchdog', function () {
+    this.timeout(1000);
+    it('Happy Path', async function () {
+        const env = {...process.env, WATCHDOG_INTERVAL: 100, __TESTING__: 1};
+        const proc = shell_spawn([`${__dirname}/watchdog.js`, `${__dirname}/watchdog.d/quick-exit-after-2-pings.js`], {env});
+        try {
+            const stdout = [];
+            await Promise.all([
+                stream.promises.pipeline(proc.stdout, stream_lines(), stream_each(v => stdout.push(v))),
+                proc.promise(),
+            ]);
+            assert.strictEqual(stdout.filter(v => v.includes('[watchdog_ping]')).length, 2);
+            assert.strictEqual(stdout.filter(v => v.includes('[watchdog_end_ok] pings=2')).length, 1);
+        }
+        finally {
+            if (pid_exists(proc.pid)) {
+                process.kill(proc.pid, 'SIGTERM');
+            }
+        }
+    });
+    it('Hang after 1 ping', async function () {
+        const env = {...process.env, WATCHDOG_INTERVAL: 100, __TESTING__: 1};
+        const proc = shell_spawn([`${__dirname}/watchdog.js`, `${__dirname}/watchdog.d/quick-hang-after-1-ping.js`], {env});
+        const stdout = [];
+        try {
+            await Promise.all([
+                stream.promises.pipeline(proc.stdout, stream_lines(), stream_each(v => stdout.push(v))),
+                assert.rejects(proc.promise().timeout(500), {message: 'Process terminated with code 124 and signal null'}),
+            ]);
+            assert.strictEqual(stdout.filter(v => v.includes('[watchdog_ping]')).length, 1);
+            assert.strictEqual(stdout.filter(v => v.includes('[watchdog_end_error] pings=1 | No heartbeat for the last 100ms')).length, 1);
+        }
+        finally {
+            if (pid_exists(proc.pid)) {
+                process.kill(proc.pid, 'SIGTERM');
+            }
+        }
+    });
 });

package/src/format_ms3.js

@@ -3,7 +3,7 @@ const factorize_ms = require('./factorize_ms');
 /**
  * Format milliseconds
  */
-function format_ms3(ms)
+function format_ms3(ms, include_zero_hours = false)
 {
     if (!ms) {
         ms = 0;
@@ -11,7 +11,7 @@ function format_ms3(ms)
 
     // 00:05.445
     const [h, m, s, xx] = factorize_ms(ms);
-    if (h) {
+    if (h || include_zero_hours) {
         return `0${h}:0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '');
     }
     return `0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '')

package/src/round.js

@@ -0,0 +1,24 @@
+// // round(34.037531, 0.001) -> 34.038000000000004
+// function round(value, precision = 1)
+// {
+//     return Math.round(value / precision) * precision;
+// }
+
+// // round(1.005, 0.01) -> 1
+// function round(value, precision = 1)
+// {
+//     const p = 1 / precision;
+//     return Math.round(value * p) / p;
+// }
+
+function round(value, precision = 1)
+{
+    if (precision === 0) {
+        return value;
+    }
+    const factor = 1 / precision;
+    const epsilon = 1e-12 * Math.sign(value);
+    return Math.round((value * factor) + epsilon) / factor;
+}
+
+module.exports = round;

package/src/round.test.js

@@ -0,0 +1,38 @@
+const assert = require('assert');
+const round = require('./round');
+
+const items = [
+    [34, 25, 25],
+    [37.5, 25, 50],
+    [34.037531, 0.001, 34.038],
+    [1.005, 0.01, 1.01],
+
+    // Synthetic cases generated by DeepSeek
+    [1.005, 0.001, 1.005],        // More precise rounding
+    [1.005, 0.1, 1.0],            // Less precise rounding
+    [1.015, 0.01, 1.02],          // Another edge case with 5
+    [1.025, 0.01, 1.03],          // Yet another edge case
+    [0.5, 1, 1],                  // Round to nearest integer
+    [0.4, 1, 0],                  // Round down to integer
+    [123.456, 0.01, 123.46],      // Standard decimal rounding
+    [123.456, 0.1, 123.5],        // Different precision
+    [123.456, 1, 123],            // Round to whole number
+    [123.456, 10, 120],           // Round to tens
+    [123.456, 100, 100],          // Round to hundreds
+    [0, 0.01, 0],                 // Zero value
+    [-1.005, 0.01, -1.01],        // Negative numbers
+    [-1.015, 0.01, -1.02],        // Negative edge case
+    [-37.5, 25, -50],             // Negative with integer precision
+    [1.2345e-5, 1e-6, 0.000012],  // Very small numbers
+    [999.999, 0.001, 999.999],    // Rounding that causes carry-over
+    [0.0000000000001, 0.01, 0],   // Extremely small number
+    [Number.MAX_SAFE_INTEGER, 1000, 9007199254741000], // Large numbers
+];
+
+describe('round', function () {
+    items.forEach(function ([value, precision, expected],) {
+        it(`${value} [${precision}] → ${expected}`, function () {
+            assert.deepStrictEqual(round(value, precision), expected);
+        });
+    });
+});

package/src/shell.md

@@ -0,0 +1,16 @@
+Basic helper for running external commands via `execFile`.
+
+- Fails if the command exits with non-zero code.
+- Fails if anything is printed to `stderr`.
+- Resolves with `stdout` (string), exactly as produced.
+
+## Signature
+
+```
+shell(args, options) → Promise<string>
+```
+
+## Notes
+
+- `args[0]` is the executable; `args[1..]` are arguments.
+- Suitable for commands that produce clean stdout and no warnings.

package/src/shell_json.md

@@ -0,0 +1,12 @@
+Basic helper for running external commands via `execFile`, and parse result by JSON.parse.
+
+- Fails if the command exits with non-zero code.
+- Fails if anything is printed to `stderr`.
+- Fails if stdout is not valid JSON.
+- Resolves with parsed JSON value.
+
+## Signature
+
+```
+shell_json(args, options) → Promise<any>
+```

package/src/shell_lines.md

@@ -0,0 +1,12 @@
+Basic helper for running external commands via `execFile`, and splits stdout into lines.
+
+- Fails if the command exits with non-zero code.
+- Fails if anything is printed to `stderr`.
+- Strips trailing newline(s).
+- Returns array of lines.
+
+## Signature
+
+```
+shell_lines(args, options) → Promise<string[]>
+```

package/src/shell_spawn.js

@@ -1,6 +1,7 @@
 const ExitCodeError = require('./errors/ExitCodeError');
 const Promise = require('bluebird');
 const child_process = require('child_process');
+const ignore = require('./ignore');
 
 // 📕 Notes by ChatGPT:
 // If the child is killed by a signal (e.g. SIGKILL from outside),
@@ -20,45 +21,44 @@ const child_process = require('child_process');
 // >     }
 // > }
 
-// ⚠️ Both .init and .promise are targets for race conditions!
 function shell_spawn(args, options)
 {
-    let init, promise;
+    const init = {};
+    const run = {};
+
+    init.promise = new Promise(function (resolve, reject) {
+        init.resolve = resolve;
+        init.reject = reject;
+    });
+    run.promise = new Promise(function (resolve, reject) {
+        run.resolve = resolve;
+        run.reject = reject;
+    });
+
     const out = child_process.spawn(args[0], args.slice(1), options);
-    out.init = function () {
-        return init = init || new Promise(function (resolve, reject) {
-            out.once('error', init_error);
-            out.once('spawn', init_spawn);
-            function init_error(error) {
-                out.off('spawn', init_spawn);
-                reject(error);
-            }
-            function init_spawn() {
-                out.off('error', init_error);
-                resolve(out);
-            }
-        });
-    };
-    out.promise = function () {
-        return promise = promise || new Promise(function (resolve, reject) {
-            out.once('error', promise_error);
-            out.once('exit', promise_exit);
-            function promise_error(error) {
-                out.off('exit', promise_exit);
-                reject(error);
-            }
-            function promise_exit(code, signal) {
-                out.off('error', promise_error);
-                if (code === 0) {
-                    resolve();
-                }
-                else {
-                    reject(new ExitCodeError(code || 128, `Process terminated with code ${code} and signal ${signal}`));
-                }
-            }
-        });
-    };
+    out.once('error', onerror);
+    out.once('spawn', onspawn);
+    out.once('exit', onexit);
+    out.init = () => init.promise;
+    out.promise = () => run.promise;
     return out;
+
+    function onerror(error) {
+        init.reject(error);
+        run.reject(error);
+    }
+    function onexit(code, signal) {
+        if (code === 0) {
+            run.resolve();
+        }
+        else {
+            run.reject(new ExitCodeError(code || 128, `Process terminated with code ${code} and signal ${signal}`));
+        }
+    }
+    function onspawn() {
+        init.resolve(out);
+        init.reject = ignore;
+    }
 }
 
 module.exports = shell_spawn;

package/src/shell_spawn.md

@@ -0,0 +1,25 @@
+Spawn-based helper for long-running or streaming commands.
+
+Provides two promises:
+
+- `proc.init()` — resolves when the child emits `spawn`.
+- `proc.promise()` — resolves when the child exits with code 0.
+
+## Failure semantics
+
+- Rejects if `error` event occurs.
+- Rejects if exit code is non-zero.
+- If child dies by signal, treated as non-zero exit (uses exitCode = 128).
+
+## Signature
+
+```
+const proc = shell_spawn(args, options)
+proc.init() → Promise<ChildProcess>
+proc.promise() → Promise<void>
+```
+
+## Notes
+
+- Output is streamed (not buffered).
+- Use when you need live stdout/stderr or long-running jobs.

package/src/shell_spawn.test.js

@@ -3,7 +3,7 @@ const assert = require('assert');
 const pid_exists = require('./pid_exists');
 const shell_spawn = require('./shell_spawn');
 
-describe.skip('shell_spawn', function () {
+describe('shell_spawn', function () {
     describe('Happy Path', function () {
         it('basic', async function () {
             await shell_spawn(['true']).promise().timeout(100);
@@ -20,4 +20,11 @@ describe.skip('shell_spawn', function () {
         assert(!pid_exists(proc.pid));
         await proc.promise().timeout(100);
     });
+    it('should throw when init fails', async function () {
+        await assert.rejects(shell_spawn(['ggg111']).init(), /^Error: spawn ggg111 ENOENT$/);
+    });
+    it('should throw when process exists with non zero code', async function () {
+        const proc = await shell_spawn(['false']).init();
+        await assert.rejects(proc.promise().timeout(100), /^Error: Process terminated with code 1 and signal null$/);
+    });
 });

package/src/shell_stdall.md

@@ -0,0 +1,11 @@
+Runs a command via `execFile` and returns both stdout and stderr.
+
+- Rejects only on exec error.
+- Resolves with `{stdout, stderr}`.
+- Does NOT treat stderr output as failure.
+
+## Signature
+
+```
+shell_stdall(args, options) → Promise<{stdout: string, stderr: string}>
+```

package/src/shell_thru.md

@@ -0,0 +1,10 @@
+Convenience wrapper over `shell_spawn` with `stdio: 'inherit'`.
+
+- Child stdout/stderr are streamed directly to parent terminal.
+- Supports `proc.init()` and `proc.promise()` like `shell_spawn`.
+
+## Signature
+
+```
+shell_thru(args, options) → ChildProcess
+```