gina 0.6.33 → 0.7.0

package/framework/v0.7.0/core/server.route-candidates.js

@@ -0,0 +1,326 @@
+'use strict';
+/**
+ * Route-candidate index for the cold routing path of `server.js` (#P46).
+ *
+ * `_handleDispatch` matches a request by walking the bundle's routing table in
+ * declaration order and running `lib/routing`'s `compareUrls` on each rule: a cold
+ * match costs about 1.1 µs per rule scanned, and a request no rule matches pays for
+ * the whole table (≈ 440 µs at 380 rules, measured 2026-09-25). This module answers,
+ * for one request, the SET of rule names that could match it; the loop skips every
+ * other rule. The loop, its order and every per-rule check are unchanged, so the
+ * first match in declaration order still wins.
+ *
+ * The set is a SUPERSET of the rules the loop can accept, never a subset:
+ *
+ * - a URL variant is split on `,` exactly as `compareUrls` splits it (untrimmed);
+ * - a segment holding a `:` ANYWHERE is a parameter (`hasParams` in lib/routing
+ *   tests `/\:/`), so an inline parameter such as `page:number` is one;
+ * - a static segment must equal the request's segment exactly, as `parseRouting`
+ *   compares it;
+ * - the loop's own equality clause (`pathname == routing[name].url`) compares the
+ *   RAW pathname with the WHOLE raw url string, so every rule is also indexed under
+ *   its raw url and looked up with the raw pathname;
+ * - a rule the path index cannot model is evaluated for every request (`always`):
+ *   one declaring two or more requirements that are not bound as a whole `:key`
+ *   segment (for GET and DELETE, `parseRouting` writes each such request key over
+ *   the compared segments from index 0, so two or more replace real path segments),
+ *   one variant with a requirement of that kind that does not start with `/` (its
+ *   index 0 is a real segment), a variant with surrounding whitespace, `?` or `#`,
+ *   and a url that is not a string (the loop still evaluates it; `compareUrls`
+ *   throws on it and the loop answers 500, which stays so).
+ *
+ * `lookup()` returns `null` — "no filter, scan every rule", today's behaviour — for
+ * a path the index does not model: one that does not start with `/`, holds `?` or
+ * `#` (express keeps the query in the pathname), or has an empty segment after the
+ * leading `/` (`/`, a trailing `/`, `//`: a parameter whose requirement accepts `''`
+ * can match an empty segment, and these paths are few and meet the warm route cache
+ * after their first request).
+ *
+ * A rule skipped by the index no longer runs `compareUrls`, so two things it used to
+ * do stop: its `validator::` requirements no longer run for that request (a throwing
+ * validator on a rule that cannot match the URL no longer answers 500), and it no
+ * longer leaves captured values in `req.params` / the method bag when no rule matches
+ * (visible only to a custom error page).
+ *
+ * The index is built once per routing table object and bundle (a `WeakMap`), from the
+ * table `config.getRouting()` returns. Nothing adds or removes a rule in that table
+ * after boot: the per-request writes go to copies (`router.js` per-rule copy,
+ * ws-query's `JSON.clone`), and a table object replaced by a reload is indexed anew.
+ *
+ * Server-only: not part of the browser bundle. It lives under `core/` on purpose — the
+ * pre-commit gate treats `lib/routing/src/` as bundled source.
+ *
+ * @module gina/core/server.route-candidates
+ */
+
+/**
+ * The result of classifying one URL variant of a rule.
+ *
+ * @constant
+ * @type {{TRIE: number, SKIP: number, ALWAYS: number}}
+ */
+var CLASS = { TRIE: 1, SKIP: 2, ALWAYS: 3 };
+
+/**
+ * One node of the path index.
+ *
+ * @typedef {object} RouteIndexNode
+ * @property {Object<string, RouteIndexNode>} s - static children, keyed by the exact segment (a null-prototype map, so `toString` or `__proto__` is an ordinary key)
+ * @property {RouteIndexNode|null} p - the parameter child: any segment holding a `:`
+ * @property {string[]} n - the rule names whose url variant ends at this node
+ */
+
+/**
+ * The candidate index of one bundle's rules in one routing table.
+ *
+ * @typedef {object} RouteIndex
+ * @property {RouteIndexNode} root - the path index; the leading empty segment is not stored
+ * @property {Object<string, string[]>} literal - raw url string → rule names (null-prototype map)
+ * @property {string[]} always - rule names evaluated for every request the index models
+ * @property {number} size - the number of rules indexed (all three parts together)
+ */
+
+/**
+ * Indexes built so far: routing table object → Map(bundle → RouteIndex).
+ *
+ * @type {WeakMap<object, Map<string, RouteIndex>>}
+ */
+var _indexes = new WeakMap();
+
+/**
+ * A new, empty path-index node.
+ *
+ * @inner
+ * @returns {RouteIndexNode}
+ */
+function createNode() {
+    return { s: Object.create(null), p: null, n: [] };
+}
+
+/**
+ * Counts a rule's own requirements that are NOT bound as a whole `:key` segment of
+ * one url variant — the keys `parseRouting` may write over the compared segments for
+ * a GET or DELETE request carrying them (#B650 limited them to the rule's OWN keys).
+ * A requirement used only inside a segment (`page:number`) counts, as it does there.
+ * Exported for the unit tests.
+ *
+ * @private
+ * @param {*} requirements - the rule's `requirements`
+ * @param {string[]} segments - the variant split on `/`
+ * @returns {number} the count, or `Infinity` when `requirements` is not an object
+ */
+function countUnboundRequirements(requirements, segments) {
+    if (typeof requirements === 'undefined' || requirements === null) {
+        return 0;
+    }
+    if (typeof requirements !== 'object') {
+        // lib/routing tests these with hasOwnProperty.call: a string or a function has
+        // own properties (`length`, `name`) that would count — never model it
+        return Infinity;
+    }
+    var keys = Object.getOwnPropertyNames(requirements), count = 0;
+    for (var i = 0; i < keys.length; i++) {
+        if (typeof requirements[keys[i]] === 'undefined') continue;
+        if (segments.indexOf(':' + keys[i]) < 0) ++count;
+    }
+    return count;
+}
+
+/**
+ * Decides how one url variant of a rule is indexed. Exported for the unit tests.
+ *
+ * @private
+ * @param {*} requirements - the rule's `requirements`
+ * @param {string} variant - one comma-separated part of the rule's url, untrimmed
+ * @returns {number} `CLASS.TRIE` (insert it), `CLASS.SKIP` (it cannot match a path the index models) or `CLASS.ALWAYS` (evaluate the rule for every request)
+ */
+function classifyVariant(requirements, variant) {
+    if (variant !== variant.trim() || /[?#]/.test(variant)) {
+        return CLASS.ALWAYS;
+    }
+    var segments = variant.split('/');
+    var unbound  = countUnboundRequirements(requirements, segments);
+    if (unbound >= 2) {
+        return CLASS.ALWAYS;
+    }
+    if (variant.charAt(0) !== '/') {
+        // index 0 is a real segment here, and one unbound key replaces it; without
+        // one, the variant has one segment fewer than any path starting with `/`
+        return (unbound >= 1) ? CLASS.ALWAYS : CLASS.SKIP;
+    }
+    for (var i = 1; i < segments.length; i++) {
+        // an empty segment can only equal an empty request segment, and lookup()
+        // returns null for every path holding one
+        if (segments[i] === '') return CLASS.SKIP;
+    }
+    return CLASS.TRIE;
+}
+
+/**
+ * Inserts one url variant (starting with `/`, no empty segment after it).
+ *
+ * @inner
+ * @param {RouteIndexNode} root
+ * @param {string} variant
+ * @param {string} name - the rule name
+ * @returns {void}
+ */
+function insert(root, variant, name) {
+    var segments = variant.split('/'), node = root;
+    for (var i = 1; i < segments.length; i++) {
+        var s = segments[i];
+        if (s.indexOf(':') > -1) {
+            if (node.p === null) node.p = createNode();
+            node = node.p;
+        } else {
+            if (typeof node.s[s] === 'undefined') node.s[s] = createNode();
+            node = node.s[s];
+        }
+    }
+    if (node.n.indexOf(name) < 0) node.n.push(name);
+}
+
+/**
+ * Builds the candidate index of one bundle's rules. Walks the table the way the
+ * routing loop does (`for…in`, non-object entries skipped, `bundle` compared with
+ * `!=`), so a rule the loop would skip for another bundle is left out.
+ *
+ * @param {object} routing - the table `config.getRouting(bundle, env)` returns
+ * @param {string} bundle - the bundle being routed
+ * @returns {RouteIndex}
+ *
+ * @example
+ * var index = build({
+ *     'item@api': { bundle: 'api', url: '/items/:id', method: 'GET', param: { control: 'get', id: ':id' } }
+ * }, 'api');
+ * lookup(index, '/items/7', '/items/7'); // Set { 'item@api' }
+ */
+function build(routing, bundle) {
+    var index = { root: createNode(), literal: Object.create(null), always: [], size: 0 };
+    for (var name in routing) {
+        var rule = routing[name];
+        if (typeof rule !== 'object' || rule === null) continue;
+        if (rule.bundle != bundle) continue;
+        ++index.size;
+
+        var url = rule.url;
+        if (typeof url !== 'string') {
+            index.always.push(name);
+            continue;
+        }
+
+        if (typeof index.literal[url] === 'undefined') index.literal[url] = [];
+        index.literal[url].push(name);
+
+        var variants = url.split(/\,/g), toInsert = [], always = false;
+        for (var v = 0; v < variants.length; v++) {
+            var c = classifyVariant(rule.requirements, variants[v]);
+            if (c === CLASS.ALWAYS) { always = true; break; }
+            if (c === CLASS.TRIE) toInsert.push(variants[v]);
+        }
+        if (always) {
+            index.always.push(name);
+            continue;
+        }
+        for (var i = 0; i < toInsert.length; i++) {
+            insert(index.root, toInsert[i], name);
+        }
+    }
+    return index;
+}
+
+/**
+ * Collects the rule names whose variant structurally matches `segments[i…]`.
+ *
+ * @inner
+ * @param {RouteIndexNode} node
+ * @param {string[]} segments - the decoded request path split on `/`
+ * @param {number} i - the next segment to match
+ * @param {Set<string>} out
+ * @returns {void}
+ */
+function collect(node, segments, i, out) {
+    if (i === segments.length) {
+        for (var k = 0; k < node.n.length; k++) out.add(node.n[k]);
+        return;
+    }
+    var child = node.s[segments[i]];
+    if (typeof child !== 'undefined') collect(child, segments, i + 1, out);
+    if (node.p !== null) collect(node.p, segments, i + 1, out);
+}
+
+/**
+ * The candidate rule names for one request.
+ *
+ * @param {RouteIndex} index
+ * @param {string} rawPathname - the request path as the routing loop compares it (`pathname`)
+ * @param {string} decodedPathname - the same path through `safeDecodeURI`, as `compareUrls` receives it
+ * @returns {Set<string>|null} the candidates (possibly empty: no rule can match), or `null` when the path is one the index does not model — scan every rule
+ *
+ * @example
+ * lookup(index, '/items/7', '/items/7');   // Set { 'item@api' }
+ * lookup(index, '/nothing', '/nothing');   // Set {} — a 404 without scanning
+ * lookup(index, '/items/', '/items/');     // null — full scan
+ */
+function lookup(index, rawPathname, decodedPathname) {
+    if (typeof decodedPathname !== 'string' || decodedPathname.charAt(0) !== '/' || /[?#]/.test(decodedPathname)) {
+        return null;
+    }
+    var segments = decodedPathname.split('/');
+    for (var i = 1; i < segments.length; i++) {
+        if (segments[i] === '') return null;
+    }
+
+    var out = new Set();
+    collect(index.root, segments, 1, out);
+
+    var literal = index.literal[rawPathname];
+    if (typeof literal !== 'undefined') {
+        for (var l = 0; l < literal.length; l++) out.add(literal[l]);
+    }
+    for (var a = 0; a < index.always.length; a++) out.add(index.always[a]);
+    return out;
+}
+
+/**
+ * The candidate rule names for one request against a routing table, building and
+ * caching the table's index on first use. Any unexpected error yields `null` (scan
+ * every rule, as before): the caller awaits nothing here and has no `try` around it.
+ *
+ * @param {object} routing - the table `config.getRouting(bundle, env)` returns
+ * @param {string} bundle - the bundle being routed
+ * @param {string} rawPathname - the request path as the routing loop compares it
+ * @param {string} decodedPathname - `safeDecodeURI(rawPathname)`
+ * @returns {Set<string>|null}
+ *
+ * @example
+ * var candidates = candidatesFor(routing, bundle, pathname, safeDecodeURI(pathname));
+ * // in the loop: if ( candidates !== null && !candidates.has(name) ) continue;
+ */
+function candidatesFor(routing, bundle, rawPathname, decodedPathname) {
+    try {
+        if (routing === null || typeof routing !== 'object') return null;
+        var byBundle = _indexes.get(routing);
+        if (typeof byBundle === 'undefined') {
+            byBundle = new Map();
+            _indexes.set(routing, byBundle);
+        }
+        var index = byBundle.get(bundle);
+        if (typeof index === 'undefined') {
+            index = build(routing, bundle);
+            byBundle.set(bundle, index);
+        }
+        return lookup(index, rawPathname, decodedPathname);
+    } catch (err) {
+        return null;
+    }
+}
+
+module.exports = {
+    CLASS                    : CLASS,
+    build                    : build,
+    lookup                   : lookup,
+    candidatesFor            : candidatesFor,
+    classifyVariant          : classifyVariant,
+    countUnboundRequirements : countUnboundRequirements
+};

package/framework/{v0.6.33 → v0.7.0}/core/template/boilerplate/bundle/config/connectors.json

@@ -9,7 +9,7 @@
 //   "database" : "${bundle}",
 //   "username" : "appuser",
 //   "password" : "secret",
-//   "ping"     : "2m"
+//   "pingInterval" : "2m"
 // }
 //
 // For local overrides without touching this file:

package/framework/{v0.6.33 → v0.7.0}/core/template/boilerplate/bundle/config/settings.json

@@ -10,5 +10,11 @@
         "date": "${dateFormat}",
         // https://en.wikipedia.org/wiki/List_of_tz_database_time_zones — e.g. Africa/Douala, America/New_York, Europe/Paris
         "timeZone": "${timeZone}"
+    },
+    // Swig output auto-escaping, an XSS defence: `true` HTML-escapes every {{ x }}.
+    // Mark a variable that carries HTML on purpose with `| safe`, e.g. {{ gina.csrfInput | safe }}.
+    // A bundle that leaves it unset renders unescaped until 0.8.0, which makes `true` the default.
+    "swig": {
+        "autoescape": true
     }
 }

package/framework/{v0.6.33 → v0.7.0}/core/template/boilerplate/bundle/controllers/setup.js

@@ -47,6 +47,12 @@ function SetupClass(req, res, next){
      * Will replace all `\n` by `<br/>`
      *  e.g.:
      *      {{ contact.address | nl2br }}
+     *  With `settings.swig.autoescape: true` (this scaffold's setting) nl2br escapes the text
+     *  and keeps the `<br/>` as markup: no `| safe` needed.
+     *
+     * [ | safe ]
+     * With `settings.swig.autoescape: true`, mark a variable that carries HTML on purpose:
+     *      {{ gina.csrfInput | safe }}
      */
 
 
@@ -75,8 +81,9 @@ function SetupClass(req, res, next){
 
     //     /*
     //     * markdown filter
-    //     * Usage:
-    //     *      <p>{{ 'once **upon** a time\nthere was a princess' | markdown('strong','em') }}"</p>
+    //     * Usage (`| safe` keeps the HTML as markup when autoescape is on — only for markdown you trust,
+    //     * the converter does not sanitize it):
+    //     *      <p>{{ 'once **upon** a time\nthere was a princess' | markdownToHtml | safe }}</p>
     //     *
     //     * @param {string} text - markdown text string
     //     *

package/framework/{v0.6.33 → v0.7.0}/helpers/path.js

@@ -1187,8 +1187,9 @@ function PathHelper() {
      * @param {Array} [excluded] - Filenames (strings) or RegExps to skip
      *
      * @callback callback
-     * @param {boolean|Error} err - `false` on success, an `Error` on failure
-     *                              (was a plain string pre-#B227)
+     * @param {boolean|Error} err - `false` on success, an `Error` with a string
+     *                              `stack` on failure (was a plain string
+     *                              pre-#B227; could lack `stack` on Bun, #B654)
      * @param {string} source
      * @param {number} i
      * */
@@ -1280,38 +1281,67 @@ function PathHelper() {
      * never observe a truncated destination and a failed copy never destroys
      * the previous content.
      *
+     * On failure the temp file is removed once its stream has closed, and only
+     * then does the callback run (#B649): its open runs on a worker thread and
+     * can create the file after the failure is reported.
+     *
      * @inner
      * @param {string} source
      * @param {string} destination
      * @param {number} i - Caller's iteration cursor, passed back untouched
      *
      * @callback callback
-     * @param {boolean|Error} err - `false` on success, an `Error` on failure
-     *                              (was a plain string pre-#B227)
+     * @param {boolean|Error} err - `false` on success, an `Error` with a string
+     *                              `stack` on failure (was a plain string
+     *                              pre-#B227; could lack `stack` on Bun, #B654)
      * @param {number} i
      * */
     var copyFile = function(source, destination, i, callback) {
 
         var _tmpTarget  = destination + '.' + process.pid + '.' + Math.random().toString(36).slice(2, 8) + '.tmp';
         var _settled    = false;
+        // #B649 — true once the temp stream has closed: only then is its open (an
+        // O_CREAT on a worker thread) known to be over, so only then does a reap
+        // find the file that open may have created
+        var _tmpClosed  = false;
 
         var sourceStream = fs.createReadStream(source);
         // #B227 — no direct write to the final name
         // was: var destinationStream = fs.createWriteStream(destination);
         var destinationStream = fs.createWriteStream(_tmpTarget);
+        // #B649 — registered before the pipe's 'close' handler below, so the flag
+        // is already set when that handler runs
+        destinationStream.once('close', function() { _tmpClosed = true });
 
         var onCopyError = function(err) {
             if (_settled) return;
             _settled = true;
             try { destinationStream.destroy() } catch (_e) {}
-            try { if ( fs.existsSync(_tmpTarget) ) fs.unlinkSync(_tmpTarget) } catch (_e) {}
             // #B227 — propagate a real Error (was a plain string, so callers
             // printing `err.stack` logged `undefined`); keep the historical
             // message prefix for log continuity
             if ( !(err instanceof Error) ) {
                 err = new Error('Error on Path.cp(...): could not copy `'+ source +'` to `'+ destination +'`');
             }
-            callback(err, i)
+            // #B654 — Bun (1.3, 1.4) reports stream errors as an Error with no
+            // `stack` at all, and callers print `err.stack`: give it one, keeping
+            // the error itself (its `code` and message)
+            else if ( typeof(err.stack) != 'string' ) {
+                try { Error.captureStackTrace(err) } catch (_e) {}
+            }
+            // #B649 — reap and settle only once the temp stream has closed. A source
+            // that fails at open can be reported before the temp file's own open has
+            // run, so checking for the file here could find nothing and leave the
+            // file that open created a moment later on disk (destroy() only closes
+            // the descriptor).
+            // was: try { if ( fs.existsSync(_tmpTarget) ) fs.unlinkSync(_tmpTarget) } catch (_e) {}
+            //      callback(err, i)
+            var reapAndSettle = function() {
+                try { fs.unlinkSync(_tmpTarget) } catch (_e) {} // ENOENT when the open never created it
+                callback(err, i)
+            };
+            if (_tmpClosed) return reapAndSettle();
+            destinationStream.once('close', reapAndSettle);
         };
 
         // #B227 — the source stream previously had NO error listener: an

package/framework/{v0.6.33 → v0.7.0}/lib/cmd/bundle/restart.js

@@ -1,6 +1,8 @@
 var fs          = require('fs');
 const { runMain } = require('module');
-var exec        = require('child_process').exec;
+// #B663 (2026-09-25) — execFile: bundle:stop and bundle:start run from argument vectors, without a shell.
+// var exec        = require('child_process').exec;
+var execFile    = require('child_process').execFile;
 
 var CmdHelper   = require('./../helper');
 var console     = lib.logger;
@@ -33,10 +35,16 @@ function Restart(opt, cmd) {
     /**
      * Validates configuration and triggers single-bundle or bulk restart.
      *
+     * Takes the runtime and CLI script paths off `process.argv` as an argument pair
+     * (`self.cliArgv`), and keeps the `--` flags it was given as a list
+     * (`self.inheritedArgv`), for the stop and start children, which run without
+     * a shell (#B663).
+     *
      * @inner
      * @private
      * @param {object} opt - Parsed command-line options
      * @param {object} cmd - The cmd dispatcher object
+     * @returns {(boolean|void)} false when the CLI is not configured
      */
     var init = function(opt, cmd) {
         // import CMD helpers
@@ -45,7 +53,10 @@ function Restart(opt, cmd) {
         // check CMD configuration
         if (!isCmdConfigured()) return false;
 
-        self.cmdStr = process.argv.splice(0, 2).join(' ');
+        // #B663 (2026-09-25) — the runtime and CLI script paths stay an argument pair: the
+        // children run without a shell (the pair was joined into a command line).
+        // self.cmdStr = process.argv.splice(0, 2).join(' ');
+        self.cliArgv = process.argv.splice(0, 2);
 
         self.inheritedArgv = [];
         for (let i = 0, len = process.argv.length; i < len; i++) {
@@ -54,7 +65,8 @@ function Restart(opt, cmd) {
             }
         }
 
-        self.inheritedArgv =  self.inheritedArgv.join(' ');
+        // #B663 (2026-09-25) — kept as a list: each flag reaches bundle:start as one argument.
+        // self.inheritedArgv =  self.inheritedArgv.join(' ');
 
         // start all bundles
         opt.onlineCount = 0;
@@ -76,11 +88,17 @@ function Restart(opt, cmd) {
     /**
      * Executes a stop-then-start sequence for one bundle, optionally in bulk.
      *
+     * `bundle:stop` and `bundle:start` run as two `execFile` children of the same
+     * runtime and CLI script, each from an argument vector, without a shell (#B663).
+     * The start runs only once the stop has succeeded, and only the start gets the
+     * inherited `--` flags and the debug flag.
+     *
      * @inner
      * @private
      * @param {object} opt - Parsed command-line options (includes client, debugPort)
-     * @param {object} cmd - Overwritten internally with the shell command string
+     * @param {object} cmd - Overwritten internally with a display string of the two commands (the debug line; nothing runs it)
      * @param {number} [bundleIndex] - When provided, performs a bulk restart at this index
+     * @returns {void}
      */
     var restart = function(opt, cmd, bundleIndex) {
 
@@ -120,44 +138,95 @@ function Restart(opt, cmd) {
                 //console.debug(' OPTIONS => ', opt.debugPort, opt.debugBrkEnabled);
                 //console.info('running: gina bundle:restart '+ bundle + '@' + self.projectName);
                 msg = 'Restarting, please wait ...';
-                cmd = '$gina bundle:stop ' + bundle + ' @' + self.projectName + ' && $gina bundle:start ' + bundle + ' @' + self.projectName;
-                if (self.inheritedArgv != '') {
-                    cmd += ' '+ self.inheritedArgv;
-                }
+                // #B663 (2026-09-25) — two argument vectors run without a shell: bundle:stop, then
+                // bundle:start only once the stop has succeeded (what the shell's `&&` did). The
+                // command line spliced the CLI path, the bundle and project names and every
+                // inherited `--` flag in unquoted, so a path containing a space broke the restart
+                // and shell syntax in a flag ran.
+                // cmd = '$gina bundle:stop ' + bundle + ' @' + self.projectName + ' && $gina bundle:start ' + bundle + ' @' + self.projectName;
+                // if (self.inheritedArgv != '') {
+                //     cmd += ' '+ self.inheritedArgv;
+                // }
+                // if (opt.debugPort) {
+                //     cmd += ' --inspect';
+                //     if (opt.debugBrkEnabled) {
+                //         cmd += '-brk'
+                //     }
+                //     cmd += '='+ opt.debugPort;
+                //     msg = 'You should now start your debug session on port #'+opt.debugPort;
+                // }
+                // cmd = cmd.replace(/\$(gina)/g, self.cmdStr);
+                var stopArgv  = [self.cliArgv[1], 'bundle:stop', bundle, '@' + self.projectName];
+                var startArgv = [self.cliArgv[1], 'bundle:start', bundle, '@' + self.projectName].concat(self.inheritedArgv);
                 if (opt.debugPort) {
-                    cmd += ' --inspect';
-                    if (opt.debugBrkEnabled) {
-                        cmd += '-brk'
-                    }
-                    cmd += '='+ opt.debugPort;
+                    startArgv.push('--inspect' + (opt.debugBrkEnabled ? '-brk' : '') + '=' + opt.debugPort);
                     msg = 'You should now start your debug session on port #'+opt.debugPort;
                 }
-                cmd = cmd.replace(/\$(gina)/g, self.cmdStr);
+                // for the debug line only: nothing runs this string
+                cmd = [self.cliArgv[0]].concat(stopArgv).join(' ') + ' && ' + [self.cliArgv[0]].concat(startArgv).join(' ');
 
                 console.debug('Executing: '+cmd);
 
                 opt.client.write('\n\r'+msg +'\n');
 
-                // If it is stuck, the problem is not here ... cmd.start should be a good start
-                exec(cmd, function(err, stdout, stderr) {
+                /**
+                 * Ends this bundle's restart on a failed step: logs the error, then moves on
+                 * to the next bundle (bulk restart) or exits 1.
+                 *
+                 * @inner
+                 * @private
+                 * @param {Error} err - The failed child's error
+                 * @returns {object} The pending timer
+                 */
+                var onFailed = function(err) {
+                    error = err.toString();
+                    console.error(error);
+                    //opt.notStopped.push(bundle + '@' + self.projectName);
+                    return setTimeout(() => {
+                        end(opt, cmd, isBulkRestart, bundleIndex, true)
+                    }, 250); // 500
+                };
 
+                // If it is stuck, the problem is not here ... cmd.start should be a good start
+                // #B663 (2026-09-25) — replaced by the two execFile calls below.
+                // exec(cmd, function(err, stdout, stderr) {
+                //
+                //     if (err) {
+                //         error = err.toString();
+                //         console.error(error);
+                //         //opt.notStopped.push(bundle + '@' + self.projectName);
+                //         return setTimeout(() => {
+                //             end(opt, cmd, isBulkRestart, bundleIndex, true)
+                //         }, 250); // 500
+                //     }
+                //
+                //     // retrieve messages from the parent stdout
+                //     if (stdout) {
+                //         console.log(stdout.replace(/\n\rTrying to.*/gm, ''));
+                //     }
+                //     setTimeout(() => {
+                //         //opt.client.write('  => bundle [ ' + bundle + '@' + self.projectName + ' ] restarted on port #'+ bundlePort+' :D\n');
+                //         end(opt, cmd, isBulkRestart, bundleIndex)
+                //     }, 250); // 500
+                // })
+                execFile(self.cliArgv[0], stopArgv, function onStopped(err, stopStdout) {
                     if (err) {
-                        error = err.toString();
-                        console.error(error);
-                        //opt.notStopped.push(bundle + '@' + self.projectName);
-                        return setTimeout(() => {
-                            end(opt, cmd, isBulkRestart, bundleIndex, true)
-                        }, 250); // 500
-                    }
-
-                    // retrieve messages from the parent stdout
-                    if (stdout) {
-                        console.log(stdout.replace(/\n\rTrying to.*/gm, ''));
+                        return onFailed(err);
                     }
-                    setTimeout(() => {
-                        //opt.client.write('  => bundle [ ' + bundle + '@' + self.projectName + ' ] restarted on port #'+ bundlePort+' :D\n');
-                        end(opt, cmd, isBulkRestart, bundleIndex)
-                    }, 250); // 500
+                    execFile(self.cliArgv[0], startArgv, function onStarted(err, startStdout) {
+                        if (err) {
+                            return onFailed(err);
+                        }
+                        // retrieve messages from the parent stdout
+                        var stdout = (stopStdout || '') + (startStdout || '');
+                        if (stdout) {
+                            console.log(stdout.replace(/\n\rTrying to.*/gm, ''));
+                        }
+                        setTimeout(() => {
+                            //opt.client.write('  => bundle [ ' + bundle + '@' + self.projectName + ' ] restarted on port #'+ bundlePort+' :D\n');
+                            end(opt, cmd, isBulkRestart, bundleIndex)
+                        }, 250); // 500
+                    })
                 })
             })//EO isRealApp
         }