gina 0.3.13 → 0.3.14

package/CHANGELOG.md

@@ -6,6 +6,21 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.3.14 - 2026-05-16
+### Changed
+* Bumped the @rhinostone/swig dependency floor from ^2.3.0 to ^2.4.0 in framework/v*/package.json and root package.json. Version 2.4.0 adds ternary (a ? b : c) and Elvis (a ?: b) operator support in template expressions — usable in {{ }} output and in tag arguments such as {% if %}, {% set %}, {% for %} — plus two CLI/build fixes (mocha invocation in make coverage; EEXIST guard in swig compile -o). No template-engine API change at the surface gina calls; swigResolver DEFAULT_MIN stays at 2.0.0.
+### Fixed
+* FormValidator::validateFormById now fails loud with an actionable error when the resolved id is not an HTMLFormElement — for example when a sibling <p id="X"> or <div id="X"> shares the id with a later-loaded <form id="X"> from a popin or AJAX fragment — instead of crashing later inside bindForm with a cryptic TypeError on the undefined .elements.length access. The error names the offending tag (e.g. `parent` resolves to <P>, not a FORM) and suggests renaming so the underlying id collision is visible from the console message. The guard mirrors the existing instanceof HTMLFormElement discriminator already used in resetErrorsDisplay elsewhere in the same file.
+* FormValidator::getFormById now fails loud with the same actionable error as validateFormById when the resolved id is not an HTMLFormElement — for example when a sibling <p id="X"> or <div id="X"> shares the id with a later-loaded <form id="X"> from a popin or AJAX fragment — instead of letting initForm register the non-FORM element in instance.$forms (polluting subsequent lookups) and crashing later inside bindForm with a cryptic TypeError on the undefined .elements.length access. The error names the offending tag (e.g. `parent` resolves to <P>, not a FORM) and suggests renaming so the underlying id collision is visible from the console message. Sister guard to the validateFormById fix in the previous commit; same shape and same root cause, different code path.
+* gina bundle:list — two argv parsing bugs in lib/cmd/bundle/list.js. (Bug A) Bare `gina bundle:list` no longer emits the spurious red `[error][gina] [ null ] is not a valid project name` stderr line before falling through to listAll(); CmdHelper initialises projectName to null (per lib/cmd/helper.js:77) but the previous post-loop dispatch only handled the undefined case. (Bug B) `gina bundle:list --all --format=json` now correctly prints JSON instead of text — the previous in-loop short-circuit on `!self.projectName` returned to listAll() before the `--format=json` token at a later argv position could set self.format. Restructure separates parsing from dispatch: the argv walk now only sets self.format + an allFlag, and dispatch runs once after the full scan completes (`if (allFlag || self.projectName == null) listAll() else if (isDefined(...)) listProjectOnly()`). Loose `== null` matches both null and undefined cleanly. The `--all` regex was extended from `/^--all=/` to `/^--all(=|$)/` so bare `--all` is matched explicitly instead of falling through to the projectName short-circuit. No functional change for valid argv shapes (`gina bundle:list @<project>` and `gina bundle:list --format=json --all` both work identically before and after).
+* Framework VERSION file no longer drifts by 1 version after each post-publish bumpVersion cycle — post_publish.js now writes framework/v{new}/VERSION alongside the renamed framework directory's package.json, sibling to the existing gitignored-file rewrite. Without this, VERSION moved with the renameSync but kept the prior publish's content, so framework/v{new}/VERSION reported the previous version until the next npm publish fired prepare_version.js. No runtime impact today (no readers); fixes the visible drift for anyone inspecting the file directly.
+* #B18 — `core/router.js` no longer poisons `require.cache[controller/index.js]` after eviction. The two sites — `refreshCoreDependencies()` (~L116-127) and the controller-require path (~L617-627) — previously did `delete require.cache[path]` then `require.cache[path] = require(path)`, which assigns the exports OBJECT (not a `Module` instance) into the slot. Latent bug because router.js was the slot's only consumer and read it back self-consistently, but the antipattern would have surfaced as `undefined`-exports crashes the moment any other module did a plain `require(controller/index.js)`. Mirror of the `refreshCore()` fix already shipped in commit `add6655e` for `core/server.isaac.js`. Both sites now use the return value of `require(...)` directly; the preceding `delete require.cache[...]` already evicts the slot so the next `require()` builds a fresh `Module` correctly. No functional change observable today — closes a documented latent bug from llms.txt #104.
+* #B16 — `gina project:rm @<project> --force` no longer ENOENTs when the project state is partially broken (missing `manifest.json` and/or missing project directory). The whole point of `--force` on a rm command is to tolerate partial breakage, but the framework's shared `CmdHelper.loadAssets()` was reading `manifest.json` unconditionally before the handler even started, and the handler itself was erroring out when the project directory was gone. Two coordinated fixes: (a) `lib/cmd/helper.js` `loadAssets()` now stubs `cmd.projectData` with a minimal `{project, version, bundles}` shape when the task is `:remove` and `--force` is set, skipping both the recreate-from-template attempt (which itself fails when the dir is gone) and the downstream `requireJSON` read; (b) `lib/cmd/project/remove.js` `init()` now warns and dispatches directly to `end(true)` when the project folder is missing AND `--force` is set, bypassing the prompt and folder rmSync to land registry-only removal (ports cleanup + `~/.gina/projects.json` delete). Without `--force`, both sites preserve the original error + exit behaviour so typos and wrong-machine invocations still surface immediately. The registry-missing check (`projects[projectName] not found in ~/.gina/projects.json`) is unchanged — `--force` can't help when there's no record to remove.
+### Security
+* Controller::throwError now strips the `stack` field from JSON error responses outside the local scope (NODE_SCOPE_IS_LOCAL=true). Local scope keeps the stack on the wire so the dev toolbar's data-xhr panel can render server-side stack frames; beta, testing, production, and any unset scope always strip — preventing server-side internals (file paths, library versions, internal stack frames) from leaking to API clients. Fail-closed: when the scope flag is missing or false for any reason, the wire stays clean. The toolbar is the only verified consumer (events.js:394 `JSON.parse(xhr.responseText)` → `ginaToolbar.update("data-xhr", XHRData)`); it is already gated on its own load path and does not load outside local scope. Out of scope and tracked separately: the HTML error-page branch (generic `<pre class="stack">` element at controller.js:5292-5333, served only when no custom error template is configured) still leaks in non-local scopes; and consumer-side leaks where `err.stack` is passed directly as the msg argument and surfaces in the `error` field instead of the gated `stack` field — those require per-call-site sanitization on the consumer side.
+* Controller::throwError now also gates the fallback HTML error page on local scope — the `<pre class="stack">` block under the L5294+ msgString construction is rendered only when NODE_SCOPE_IS_LOCAL=true, so server-side stack frames (file paths, library versions, internal frames) don't leak via the generic HTML error page in non-local scopes. Same fail-closed shape as the JSON wire gate landed in the previous Security entry; covers both render sites in the fallback path (msg-shape and generic-shape branches). Title / error / message <pre> blocks continue to render in every scope. Custom error templates dispatched via renderCustomError stay consumer-owned — what the template chooses to render from req.params.errorObject (e.g. {% if data.stack %}{{ data.stack }}{% endif %} in a consumer view) is the consumer's call, not the framework's. Closes the cross-shape part of the throwError stack-leak story; consumer-side leaks where `err.stack` is passed as the msg argument and surfaces in the `error` string still need per-call-site sanitization on the consumer side.
+* Built-in /_gina/info and /_gina/cache/stats endpoints are now IP-allowlisted per bundle (#S7). They expose process state (memory, uptime, version, HTTP/2 session counters, cache contents) — admin-grade information that should not reach public callers. The new `admin.allowFrom` block in `app.json` defines the allowlist; defaults to loopback only (`["127.0.0.1", "::1"]`) when omitted. Empty array `[]` is explicit deny-everyone. The IP is read from `req.socket.remoteAddress` only — `X-Forwarded-For` is NOT trusted because reverse proxies could spoof it. `::ffff:IPv4` (IPv6-mapped IPv4) is normalised to `IPv4` so listing `127.0.0.1` matches both forms. Denied requests receive 403 with `{ error: "forbidden", message: "/_gina/<path>: client IP not in app.json admin.allowFrom" }`. Mirrors the /_gina/metrics gate convention (#OBS1) but is configured on a separate axis — bundles that disable metrics still get the admin lockdown by default. /_gina/health/check is unaffected (k8s liveness probes need it unrestricted). To allow scraping from an internal monitor on a sister host, add the monitor IP to `app.json admin.allowFrom`.
+
 ## 0.3.13 - 2026-05-14
 ### Added
 * Released `0.3.13` — cumulative stable of the `0.3.13-alpha` cycle. Alpha-cycle headline tracks (detailed under `0.3.13-alpha.3` in the changelog): **`${secret:KEY}` config-placeholder resolver** (#SECRETS1) — `lib/secrets` substitutes `${secret:KEY}` placeholders embedded in bundle JSON configs (`settings.json`, `app.json`, `connectors.json`, `mcp.json`) from `process.env[KEY]` at config-load time, fail-closed on an unset/empty var; ships with a `settings.csrf.secret` slot for `gina.plugins.Csrf()` and `mcp.json` placeholder support for `gina bundle:mcp-start`. **Eval-safety campaign completed** (#M20–#M22) — validator nested-key rule construction refactored off `eval` (#M20); the four HTML event-callback `eval` sites and the conditional-binding evaluator fallback dropped (#M21a, #M21b); the Pattern B user-defined-validator `eval` documented as load-bearing public API with an invariant test (#M21c); the logger ↔ merge circular-require restructured so the three `eval(fs.readFileSync(...))` fallbacks are removed (#M22) — Phase 3c complete, one load-bearing framework `eval` remains by design. Plus the #M1 async-race retrofit follow-up (render-nunjucks terminal-exit closure nulling) and a `requireJSON` line-comment / URL-collision fix. The entries below are the post-alpha-cycle changes that complete the release.

package/README.md

@@ -22,7 +22,7 @@ Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope
 | ORM / entities | EventEmitter-based entity system; SQL files auto-wired to entity methods |
 | Connectors | Couchbase, MongoDB, ScyllaDB / Cassandra, MySQL, PostgreSQL, Redis, SQLite, AI (LLM) — loaded from project `node_modules` |
 | AI connector | Any LLM provider via named protocol (`anthropic://`, `openai://`, `ollama://`, …) |
-| Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) 2.3.0 — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` |
+| Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) 2.4.0 — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` |
 | Internationalisation | Per-bundle JSON catalogs, `t()` helper, swig + nunjucks `t` filter, CLDR plurals, ICU MessageFormat opt-in via `t.icu()` |
 | Observability | Built-in `/_gina/metrics` Prometheus endpoint (opt-in, IP-allowlisted) — Node.js process metrics + HTTP counter / duration histogram with cardinality-safe route labels |
 | Hot reload | WatcherService evicts `require.cache` only on file change — zero per-request overhead in dev |
@@ -39,6 +39,16 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
+## What's in 0.3.14
+
+- **Server-side stack-frame leak prevention on both error wires** — `Controller::throwError` now gates the `stack` field in JSON error responses and the `<pre class="stack">` block in the fallback HTML error page on local scope. Beta, testing, production, and any unset scope strip — preventing file paths, library versions, and internal stack frames from reaching API clients and page viewers. Local scope (`NODE_SCOPE_IS_LOCAL=true`) preserves the stack on both wires so the dev toolbar's `data-xhr` panel and the fallback HTML page keep showing the trace inline. Fail-closed shape (gate is `!_isLocalScope`, not `_isProdScope`) so a missing scope var on a fresh deployment cannot reintroduce the leak. Custom error templates dispatched via `renderCustomError` stay consumer-owned — what a consumer view renders from `req.params.errorObject` is unchanged. Consumer-side leak where `err.stack` is passed as the `msg` argument and surfaces in the `error` STRING is NOT covered by the framework gate — those callsites need per-callsite sanitization (`new Error('...').message` instead of `.stack`).
+- **Admin-grade `/_gina/*` endpoints IP-allowlisted** (#S7) — `/_gina/info` (process memory / uptime / version / HTTP/2 session counters) and `/_gina/cache/stats` (full cache contents) now require an IP allowlist configured via a new `admin.allowFrom` block in `app.json`. Defaults to loopback only (`["127.0.0.1", "::1"]`); empty array `[]` is explicit deny-everyone. Client IP is read from `req.socket.remoteAddress` only — `X-Forwarded-For` is NOT trusted (reverse proxies could spoof it). `::ffff:IPv4` is normalised so listing `127.0.0.1` matches both forms. `/_gina/health/check` is intentionally unrestricted (k8s liveness probes need it open). Mirrors the `/_gina/metrics` (#OBS1) gate convention but on a separate axis — bundles that disable metrics still get the admin lockdown. **Action required:** bundles that scrape `/_gina/info` or `/_gina/cache/stats` from a non-loopback host (internal monitor, sister K8s pod, etc.) must add the source IP to `app.json admin.allowFrom`. Localhost-only access (typical dev workflow) needs no change.
+- **`gina project:rm --force` tolerates partial-breakage states** (#B16) — the whole point of `--force` on a rm command is to honour broken state (manually-deleted directory, failed scaffold mid-disk-full, stuck `projects.json` row with no on-disk artefacts). Pre-fix the framework errored on missing `manifest.json` and missing project directory even with `--force` set. Both now warn and fall back to registry-only removal (`~/.gina/projects.json` + state-store row). Without `--force` both still error so typos and wrong-machine invocations surface immediately. The registry-missing check is unchanged — `--force` cannot help when there is no record to remove.
+- **`bundle:list` argv parsing cleanup** (#B15) — two pre-existing surface bugs. Bare `gina bundle:list` no longer emits a spurious red `[error][gina] [ null ] is not a valid project name` stderr line before falling through to the all-projects view. `gina bundle:list --all --format=json` now correctly prints JSON instead of text — the previous in-loop short-circuit dispatched to `listAll()` before the `--format=json` token at a later argv position could set the format. No functional change for valid argv shapes.
+- **FormValidator HTMLFormElement guards** — `FormValidator::validateFormById` and `FormValidator::getFormById` now fail loud with an actionable error when the resolved id is not an `HTMLFormElement` (for example when a sibling `<p id="X">` or `<div id="X">` shares the id with a later-loaded `<form id="X">` from a popin or AJAX fragment), instead of crashing later inside `bindForm` with a cryptic `TypeError` on `.elements.length`. The error names the offending tag and suggests renaming so the id collision is visible from the console message.
+- **`@rhinostone/swig` floor bumped to `^2.4.0`** — `2.4.0` adds ternary (`a ? b : c`) and Elvis (`a ?: b`) operator support in template expressions, plus two CLI/build fixes (`mocha` invocation in `make coverage`; `EEXIST` guard in `swig compile -o`). No template-engine API change at the surface gina calls. `swigResolver DEFAULT_MIN` stays at `2.0.0`.
+- **Internal housekeeping** — `core/router.js` hot-reload no longer poisons the `require.cache` slot for `controller/index.js` (#B18, mirror of the `refreshCore()` fix shipped in `add6655e`). `script/post_publish.js bumpVersion` now refreshes the `framework/v*/VERSION` file content alongside the `renameSync` of the gitignored sibling, closing a drift family that previously needed manual repair after each alpha bump.
+
 ## What's in 0.3.13
 
 - **`${secret:KEY}` placeholder substitution** (#SECRETS1) — bundle JSON configs (`settings.json`, `app.json`, `connectors.json`, `mcp.json`, …) can embed `${secret:KEY}` placeholders that the framework resolves from `process.env[KEY]` at config-load time, before the merged config reaches `getConfig()` or any plugin factory. Anchored to whole-string values; fails closed on an unset/empty var. `gina.plugins.Csrf()` reads `settings.csrf.secret` through it, and `gina bundle:mcp-start` resolves `mcp.json` placeholders such as `server.authToken`. Pluggable-backend interface reserved for a future iteration; only the `process.env` backend ships now.

package/framework/v0.3.14/VERSION

@@ -0,0 +1 @@
+0.3.14

package/framework/{v0.3.13 → v0.3.14}/core/asset/plugin/dist/vendor/gina/js/gina.js

@@ -9823,6 +9823,18 @@ function ValidatorPlugin(rules, data, formId) {
     }
 
 
+    /**
+     * getFormById
+     *
+     * @param {string} formId
+     *
+     * @returns {object} $form
+     *
+     * @throws {Error} When `formId` resolves via document.getElementById to a non-FORM
+     *                 element. Same shape and root cause as validateFormById's @throws —
+     *                 a sibling <p id="X"> / <div id="X"> shares the id with a later-
+     *                 loaded <form id="X"> (popin / AJAX fragment).
+     * */
     var getFormById = function(formId) {
         var $form = null, _id = formId;
 
@@ -9836,8 +9848,25 @@ function ValidatorPlugin(rules, data, formId) {
         _id = _id.replace(/\#/, '');
 
         // in case form is created on the fly and is not yet registered
-        if (document.getElementById(_id) != null && typeof (instance['$forms'][_id]) == 'undefined') {
-            initForm( document.getElementById(_id) );
+        var $candidate = document.getElementById(_id);
+        if ($candidate != null && typeof (instance['$forms'][_id]) == 'undefined') {
+
+            // Same fail-loud guard as validateFormById's else branch —
+            // document.getElementById returns the first matching element regardless
+            // of tag, so a sibling <p id="X"> / <div id="X"> / etc. wins over a
+            // later-loaded <form id="X">. Surface the collision instead of letting
+            // initForm register the non-FORM element in instance.$forms (polluting
+            // subsequent lookups) and crash later inside bindForm with
+            // `Cannot read properties of undefined (reading 'length')`.
+            if ( !($candidate instanceof HTMLFormElement) ) {
+                throw new Error(
+                    '[ FormValidator::getFormById(formId) ] `' + _id + '` resolves to <'
+                    + $candidate.tagName + '>, not a FORM. A non-FORM element shares the same id as '
+                    + 'the target form — rename one of them so the id is unique.'
+                );
+            }
+
+            initForm( $candidate );
         }
 
         if ( typeof(instance.$forms[_id]) != 'undefined' ) {
@@ -9909,6 +9938,12 @@ function ValidatorPlugin(rules, data, formId) {
      * @param {object} [customRule]
      *
      * @returns {object} $form
+     *
+     * @throws {Error} When `formId` resolves via document.getElementById to a non-FORM
+     *                 element (e.g. a sibling <p id="X"> / <div id="X"> sharing the id
+     *                 with a later-loaded <form id="X">). Surfaces the collision instead
+     *                 of crashing later inside bindForm with a cryptic
+     *                 `Cannot read properties of undefined (reading 'length')`.
      * */
     var validateFormById = function(formId, customRule) {
         var $form = null
@@ -9952,6 +9987,21 @@ function ValidatorPlugin(rules, data, formId) {
             $form   = this.$forms[_id] = instance['$forms'][_id];
         } else { // binding a form out of context (outside of the main instance)
             $target             = document.getElementById(_id);
+
+            // validateFormById was designed for FORM elements. getElementById
+            // returns the first matching element regardless of tag, so a sibling
+            // <p id="X"> / <div id="X"> / etc. wins over a later-loaded
+            // <form id="X">. Surface the collision instead of crashing later
+            // inside bindForm with a cryptic
+            // `Cannot read properties of undefined (reading 'length')`.
+            if ( $target && !($target instanceof HTMLFormElement) ) {
+                throw new Error(
+                    '[ FormValidator::validateFormById(formId) ] `' + _id + '` resolves to <'
+                    + $target.tagName + '>, not a FORM. A non-FORM element shares the same id as '
+                    + 'the target form — rename one of them so the id is unique.'
+                );
+            }
+
             $validator.id           = _id;
             $validator.target       = $target;
 

package/framework/{v0.3.13 → v0.3.14}/core/asset/plugin/dist/vendor/gina/js/gina.min.js

@@ -277,13 +277,14 @@ delete require.cache[require.resolve('../../../../../helpers/data')];require('..
 document:null,errors:{},initialized:!1,isReady:!1,rules:{},$forms:{},getFormById:null,validateFormById:null,setOptions:null,resetErrorsDisplay:null,resetFields:null},S={id:null,plugin:this.plugin,on:C?on:null,eventData:{},target:C?document:null,cachedErrors:{},lastFocused:C?[]:null,binded:!1,unbinded:!1,withUserBindings:!1,rules:{},setOptions:null,send:null,isValidating:null,isSubmitting:null,submit:null,destroy:null,resetErrorsDisplay:null,resetFields:null},ka={},aa={},v=null,u={url:'',method:'GET',
 isSynchrone:!1,withCredentials:!1,withRateLimit:!0,headers:{'Content-Type':'application/x-www-form-urlencoded; charset=UTF-8','X-Requested-With':'XMLHttpRequest'}},V=function(){if(typeof document==='undefined'||!document||typeof document.cookie!=='string')return null;var a=document.cookie||'';if(!a)return null;a=a.split(';');for(var b=0,e=a.length;b<e;++b){for(var k=a[b];k.charAt(0)===' '||k.charAt(0)==='\t';)k=k.slice(1);var z=k.indexOf('=');if(!(z<0)&&k.slice(0,z)==='gina-csrf-token'){a=k.slice(z+
 1);try{return decodeURIComponent(a)}catch(y){return a}}}return null},h=function(a){if(typeof a!=='string'||!a)return!1;a=a.toUpperCase();return a!=='GET'&&a!=='HEAD'&&a!=='OPTIONS'},g=function(a,b,e){e=typeof e!='undefined'?{id:e}:null;var k={},z;for(z in b)k[z]=b[z];if(typeof a!='undefined'&&a.count()>0){try{wa(a,''),va(a)}catch(y){throw y;}return T(e,k,null,c.rules)}return new n(k)},q=function(a){u=a=D(a,u);return this},F=function(a){var b=null;if(!c.$forms)throw Error('`$forms` collection not found');
-if(typeof a=='undefined')throw Error('[ FormValidator::getFormById(formId) ] `formId` is missing');a=a.replace(/#/,'');if(document.getElementById(a)!=null&&typeof c.$forms[a]=='undefined'){var e=document.getElementById(a),k,z=typeof(ka.count()>0)?ka:c.rules;e.getAttribute?(id=e.getAttribute('id')||'form.'+U(),id!==e.getAttribute('id')&&e.setAttribute('id',id)):(id='form.'+U(),e.setAttribute('id',id));e.id=S.id=id;if(typeof e.id!='undefined'&&e.id!='null'&&e.id!=''){S.target=e;c.$forms[e.id]=D({},
-S);if(k=e.getAttribute('data-gina-form-rule')){k=k.replace(/\-|\//g,'.');if(typeof z[k]=='undefined')throw Error('['+e.id+'] no rule found with key: `null`');k=z[k]}typeof e.id=='string'&&typeof z[e.id.replace(/\-/g,'.')]!='undefined'?$target=c.$forms[e.id].target:typeof e.id=='object'?(delete c.$forms[e.id],z=e.attributes.getNamedItem('id').nodeValue||'form.'+U(),e.setAttribute('id',z),e.id=z,S.target=e,c.$forms[z]=D({},S),$target=c.$forms[z].target):$target=c.$forms[e.id].target;k?Ya($target,k):
-Ya($target)}}typeof c.$forms[a]!='undefined'&&(c.$forms[a].withUserBindings=!0,b=typeof this.$forms!='undefined'&&typeof this.$forms[a]=='undefined'?this.$forms[a]=c.$forms[a]:c.$forms[a]);if(!b)throw Error('Validator::getFormById(...) exception: could not retrieve form `'+a+'`');b.binded||(Ya(b.target),b=c.$forms[a]);A&&C&&typeof window.ginaToolbar!='undefined'&&window.ginaToolbar&&(gina.forms.errors||(gina.forms.errors={}),e={id:a,rules:c.$forms[a].rules},typeof c.$forms[a].errors!='undefined'&&
-(e.errors=c.$forms[a].errors),window.ginaToolbar.update('forms',e));return b},N=function(){var a=!1,b=null;gina.hasPopinHandler&&gina.popinIsBinded&&(b=gina.popin.getActivePopin());b&&b.isOpen&&(a=!0);return a},r=function(a,b){var e=typeof(ka.count()>0)?ka:c.rules;if(!c.$forms)throw Error('`$forms` collection not found');if(typeof a!='undefined'&&typeof c.$forms[a]!='undefined')return c.$forms[a];if(typeof a=='undefined')if(typeof this.id!='undefined'&&this.id!=''&&this.id!=null)a=this.id;else throw Error('[ FormValidator::validateFormById(formId, customRule) ] `formId` is missing');
-if(typeof a=='string')a=a.replace(/#/,'');else{if(typeof a!='object'||Array.isArray(a))throw Error('[ FormValidator::validateFormById(formId[, customRule]) ] `formId` should be a `string`');var k=a.form;a=k.getAttribute('id')||'form.'+U();k.setAttribute('id',a)}var z=document.getElementsByTagName('form');for(var y={},f=0,O=z.length;f<O;++f)k=z[f].getAttribute('id')||null,typeof y[k]=='undefined'?y[k]=!0:typeof c.$forms[k]=='undefined'||c.$forms[k].warned||(gina.popinIsBinded?console.warn('Popin/Validator::bindForm($target, customRule): `'+
-k+'` is a duplicate form ID. If not fixed, this could lead to an undesirable behaviour.\n Check inside your popin content'):console.warn('Validator::bindForm($target, customRule): `'+k+'` is a duplicate form ID. If not fixed, this could lead to an undesirable behaviour.'),c.$forms[k].warned=!0);if(typeof this.$forms!='undefined'&&typeof c.$forms[a]!='undefined')z=this.$forms[a]=c.$forms[a];else{k=document.getElementById(a);S.id=a;S.target=k;z=this.$forms[a]=c.$forms[a]=D({},S);if(typeof b=='undefined')if(y=
-a.replace(/\-/g,'.'),typeof e!='undefined')z.rule=Ja(y);else{if(typeof z.target!='undefined'&&z.target!==null&&z.target.getAttribute('data-gina-form-rule'))if(y=z.target.getAttribute('data-gina-form-rule').replace(/\-|\//g,'.'),typeof e!='undefined')z.rule=Ja(y);else throw Error('[ FormValidator::validateFormById(formId) ] using `data-gina-form-rule` on form `'+z.target+'`: no matching rule found');}else if(y=b.replace(/\-|\//g,'.'),typeof e!='undefined')z.rule=Ja(y);else throw Error('[ FormValidator::validateFormById(formId, customRule) ] `'+
+if(typeof a=='undefined')throw Error('[ FormValidator::getFormById(formId) ] `formId` is missing');a=a.replace(/#/,'');var e=document.getElementById(a);if(e!=null&&typeof c.$forms[a]=='undefined'){if(!(e instanceof HTMLFormElement))throw Error('[ FormValidator::getFormById(formId) ] `'+a+'` resolves to <'+e.tagName+'>, not a FORM. A non-FORM element shares the same id as the target form \u2014 rename one of them so the id is unique.');var k,z=typeof(ka.count()>0)?ka:c.rules;e.getAttribute?(id=e.getAttribute('id')||
+'form.'+U(),id!==e.getAttribute('id')&&e.setAttribute('id',id)):(id='form.'+U(),e.setAttribute('id',id));e.id=S.id=id;if(typeof e.id!='undefined'&&e.id!='null'&&e.id!=''){S.target=e;c.$forms[e.id]=D({},S);if(k=e.getAttribute('data-gina-form-rule')){k=k.replace(/\-|\//g,'.');if(typeof z[k]=='undefined')throw Error('['+e.id+'] no rule found with key: `null`');k=z[k]}typeof e.id=='string'&&typeof z[e.id.replace(/\-/g,'.')]!='undefined'?$target=c.$forms[e.id].target:typeof e.id=='object'?(delete c.$forms[e.id],
+z=e.attributes.getNamedItem('id').nodeValue||'form.'+U(),e.setAttribute('id',z),e.id=z,S.target=e,c.$forms[z]=D({},S),$target=c.$forms[z].target):$target=c.$forms[e.id].target;k?Ya($target,k):Ya($target)}}typeof c.$forms[a]!='undefined'&&(c.$forms[a].withUserBindings=!0,b=typeof this.$forms!='undefined'&&typeof this.$forms[a]=='undefined'?this.$forms[a]=c.$forms[a]:c.$forms[a]);if(!b)throw Error('Validator::getFormById(...) exception: could not retrieve form `'+a+'`');b.binded||(Ya(b.target),b=c.$forms[a]);
+A&&C&&typeof window.ginaToolbar!='undefined'&&window.ginaToolbar&&(gina.forms.errors||(gina.forms.errors={}),e={id:a,rules:c.$forms[a].rules},typeof c.$forms[a].errors!='undefined'&&(e.errors=c.$forms[a].errors),window.ginaToolbar.update('forms',e));return b},N=function(){var a=!1,b=null;gina.hasPopinHandler&&gina.popinIsBinded&&(b=gina.popin.getActivePopin());b&&b.isOpen&&(a=!0);return a},r=function(a,b){var e=typeof(ka.count()>0)?ka:c.rules;if(!c.$forms)throw Error('`$forms` collection not found');
+if(typeof a!='undefined'&&typeof c.$forms[a]!='undefined')return c.$forms[a];if(typeof a=='undefined')if(typeof this.id!='undefined'&&this.id!=''&&this.id!=null)a=this.id;else throw Error('[ FormValidator::validateFormById(formId, customRule) ] `formId` is missing');if(typeof a=='string')a=a.replace(/#/,'');else{if(typeof a!='object'||Array.isArray(a))throw Error('[ FormValidator::validateFormById(formId[, customRule]) ] `formId` should be a `string`');var k=a.form;a=k.getAttribute('id')||'form.'+
+U();k.setAttribute('id',a)}var z=document.getElementsByTagName('form');for(var y={},f=0,O=z.length;f<O;++f)k=z[f].getAttribute('id')||null,typeof y[k]=='undefined'?y[k]=!0:typeof c.$forms[k]=='undefined'||c.$forms[k].warned||(gina.popinIsBinded?console.warn('Popin/Validator::bindForm($target, customRule): `'+k+'` is a duplicate form ID. If not fixed, this could lead to an undesirable behaviour.\n Check inside your popin content'):console.warn('Validator::bindForm($target, customRule): `'+k+'` is a duplicate form ID. If not fixed, this could lead to an undesirable behaviour.'),
+c.$forms[k].warned=!0);if(typeof this.$forms!='undefined'&&typeof c.$forms[a]!='undefined')z=this.$forms[a]=c.$forms[a];else{if((k=document.getElementById(a))&&!(k instanceof HTMLFormElement))throw Error('[ FormValidator::validateFormById(formId) ] `'+a+'` resolves to <'+k.tagName+'>, not a FORM. A non-FORM element shares the same id as the target form \u2014 rename one of them so the id is unique.');S.id=a;S.target=k;z=this.$forms[a]=c.$forms[a]=D({},S);if(typeof b=='undefined')if(y=a.replace(/\-/g,
+'.'),typeof e!='undefined')z.rule=Ja(y);else{if(typeof z.target!='undefined'&&z.target!==null&&z.target.getAttribute('data-gina-form-rule'))if(y=z.target.getAttribute('data-gina-form-rule').replace(/\-|\//g,'.'),typeof e!='undefined')z.rule=Ja(y);else throw Error('[ FormValidator::validateFormById(formId) ] using `data-gina-form-rule` on form `'+z.target+'`: no matching rule found');}else if(y=b.replace(/\-|\//g,'.'),typeof e!='undefined')z.rule=Ja(y);else throw Error('[ FormValidator::validateFormById(formId, customRule) ] `'+
 b+'` is not a valid rule');k&&typeof this.isPopinContext!='undefined'&&/true/i.test(this.isPopinContext)&&(k.isPopinContext=this.isPopinContext);k&&!z.binded&&Ya(k,y)}if(!z)throw Error('[ FormValidator::validateFormById(formId, customRule) ] `'+a+'` not found');return z||null},x=function(a){var b=a.form.id||a.form.getAttribute('id'),e=a.name||a.form.getAttribute('name'),k=document.activeElement.name;if(!/^true$/i.test(c.$forms[b].isValidating)){var z=a.parentNode;a=!1;var y=z.getElementsByTagName('div');
 /form\-item\-warning/.test(z.className)&&k!=e?z.className=z.className.replace(/form\-item\-warning/,'form-item-error'):/form\-item\-error/.test(z.className)&&k==e&&(z.className=z.className.replace(/form\-item\-error/,'form-item-warning'),a=!0);if(!/^true$/i.test(c.$forms[b].isValidating)||a)for(b=0,e=y.length;b<e;++b)if(/form\-item\-error\-message/.test(y[b].className)){y[b].className=a?y[b].className+' hidden':y[b].className.replace(/(\s+hidden|hidden)/,'');break}}},J={},L=function(a,b,e,k){if(A)var z=
 null;var y=!1;if(typeof a.dataset.ginaFormIsResetting!='undefined'&&/^(true)$/i.test(a.dataset.ginaFormIsResetting))b={},J={},a.dataset.ginaFormIsResetting=!1;else if(/^(true)$/i.test(a.dataset.ginaFormLiveCheckEnabled)&&typeof k!='undefined'){var f=typeof a.id!='string'?a.getAttribute('id'):a.id;typeof J[f]=='undefined'&&(J[f]={});if(b&&b.count()>0){if(J[f][k]={},J[f][k]=D(b[k],J[f][k]),J[f][k].count()==0&&delete J[f][k],b=J[f],!c.$forms[f].sent||c.$forms[f].isValidating)if(y=!0,f=c.$forms[f].lastFocused,

package/framework/{v0.3.13 → v0.3.14}/core/controller/controller.js

@@ -4954,7 +4954,21 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
 
 
     /**
-     * Throw error
+     * Throw error — terminates the request with an error response.
+     *
+     * Response shape depends on the request type:
+     *   - XHR / non-templated routes → JSON body `{ status, error, stack? }`
+     *   - Templated routes → HTML error page or rendered error template
+     *
+     * The `stack` field (JSON) and the `<pre class="stack">` block (fallback
+     * HTML error page) are emitted only when the active scope is local
+     * (`NODE_SCOPE_IS_LOCAL=true`) so the dev toolbar can render server-side
+     * stack frames in its data-xhr panel and the fallback HTML page shows the
+     * trace inline. Beta, testing, production, and unset scopes strip both to
+     * prevent server-internals (file paths, library versions, internal frames)
+     * from leaking to API clients or page viewers. Custom error templates
+     * dispatched via `renderCustomError` are consumer-owned — what the
+     * template renders from `req.params.errorObject` is the consumer's call.
      *
      * @param {object} [ res ]
      * @param {number} code
@@ -5136,6 +5150,15 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                     }
                 }
 
+                // Fail-closed: strip server-side stack from the JSON wire outside
+                // local scope so file paths, library versions, and internal stack
+                // frames don't leak to API clients. Local scope keeps it so the
+                // dev toolbar's data-xhr panel can render it (events.js:394 →
+                // ginaToolbar.update('data-xhr', XHRData)).
+                if (!_isLocalScope && errorObject && errorObject.stack) {
+                    delete errorObject.stack;
+                }
+
                 var errOutput = null, output = errorObject.toString();
                 if ( output == '[object Object]' ) {
                     errOutput = JSON.stringify(errorObject);
@@ -5289,7 +5312,12 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                         msgString += '<pre class="'+ eCode +' message">'+ msg.message +'</pre>';
                     }
 
-                    if (msg.stack) {
+                    // Fail-closed: render the stack frame only in local scope
+                    // so file paths, library versions, and internal frames don't
+                    // leak via the fallback HTML error page. Symmetric to the
+                    // JSON wire gate (~L5147). Custom error templates dispatched
+                    // via renderCustomError at L5266-5281 are consumer-owned.
+                    if (msg.stack && _isLocalScope) {
 
                         if (msg.error) {
                             msg.stack = msg.stack.replace(msg.error, '')
@@ -5327,7 +5355,9 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
                     if (message) {
                         msgString += '<pre class="'+ eCode +' message">'+ message +'</pre>';
                     }
-                    if (stack) {
+                    // Fail-closed: local scope only — same gate shape as the
+                    // msg-shape site above.
+                    if (stack && _isLocalScope) {
                         msgString += '<pre class="'+ eCode +' stack">'+ stack +'</pre>';
                     }
                 }

package/framework/{v0.3.13 → v0.3.14}/core/gna.js

@@ -1162,6 +1162,25 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
                                     console.warn('[lib.metrics] init skipped: ' + (metricsErr.message || metricsErr));
                                 }
 
+                                // #S7 — admin /_gina/* allowlist init. Reads `admin.allowFrom`
+                                // from app.json; defaults to loopback (127.0.0.1, ::1). Stored
+                                // on process.gina so server.isaac.js's /_gina/info and
+                                // /_gina/cache/stats handlers can gate on it. Same shape as the
+                                // metrics allowlist but a separate axis — admin endpoints expose
+                                // process state and warrant their own access control.
+                                try {
+                                    var _adminAppConf = (typeof gna.getConfig === 'function') ? gna.getConfig('app') : null;
+                                    var _adminAllow   = (_adminAppConf && _adminAppConf.admin && Array.isArray(_adminAppConf.admin.allowFrom))
+                                        ? _adminAppConf.admin.allowFrom.slice()
+                                        : ['127.0.0.1', '::1'];
+                                    if (!process.gina) process.gina = {};
+                                    process.gina._adminAllowList = _adminAllow;
+                                } catch (adminAclErr) {
+                                    console.warn('[admin-acl] init skipped: ' + (adminAclErr.message || adminAclErr));
+                                    if (!process.gina) process.gina = {};
+                                    process.gina._adminAllowList = ['127.0.0.1', '::1'];
+                                }
+
                                 // setting default global middlewares
                                 if ( typeof(instance.use) == 'function' ) {
 

package/framework/{v0.3.13 → v0.3.14}/core/plugins/lib/validator/src/main.js

@@ -304,6 +304,18 @@ function ValidatorPlugin(rules, data, formId) {
     }
 
 
+    /**
+     * getFormById
+     *
+     * @param {string} formId
+     *
+     * @returns {object} $form
+     *
+     * @throws {Error} When `formId` resolves via document.getElementById to a non-FORM
+     *                 element. Same shape and root cause as validateFormById's @throws —
+     *                 a sibling <p id="X"> / <div id="X"> shares the id with a later-
+     *                 loaded <form id="X"> (popin / AJAX fragment).
+     * */
     var getFormById = function(formId) {
         var $form = null, _id = formId;
 
@@ -317,8 +329,25 @@ function ValidatorPlugin(rules, data, formId) {
         _id = _id.replace(/\#/, '');
 
         // in case form is created on the fly and is not yet registered
-        if (document.getElementById(_id) != null && typeof (instance['$forms'][_id]) == 'undefined') {
-            initForm( document.getElementById(_id) );
+        var $candidate = document.getElementById(_id);
+        if ($candidate != null && typeof (instance['$forms'][_id]) == 'undefined') {
+
+            // Same fail-loud guard as validateFormById's else branch —
+            // document.getElementById returns the first matching element regardless
+            // of tag, so a sibling <p id="X"> / <div id="X"> / etc. wins over a
+            // later-loaded <form id="X">. Surface the collision instead of letting
+            // initForm register the non-FORM element in instance.$forms (polluting
+            // subsequent lookups) and crash later inside bindForm with
+            // `Cannot read properties of undefined (reading 'length')`.
+            if ( !($candidate instanceof HTMLFormElement) ) {
+                throw new Error(
+                    '[ FormValidator::getFormById(formId) ] `' + _id + '` resolves to <'
+                    + $candidate.tagName + '>, not a FORM. A non-FORM element shares the same id as '
+                    + 'the target form — rename one of them so the id is unique.'
+                );
+            }
+
+            initForm( $candidate );
         }
 
         if ( typeof(instance.$forms[_id]) != 'undefined' ) {
@@ -390,6 +419,12 @@ function ValidatorPlugin(rules, data, formId) {
      * @param {object} [customRule]
      *
      * @returns {object} $form
+     *
+     * @throws {Error} When `formId` resolves via document.getElementById to a non-FORM
+     *                 element (e.g. a sibling <p id="X"> / <div id="X"> sharing the id
+     *                 with a later-loaded <form id="X">). Surfaces the collision instead
+     *                 of crashing later inside bindForm with a cryptic
+     *                 `Cannot read properties of undefined (reading 'length')`.
      * */
     var validateFormById = function(formId, customRule) {
         var $form = null
@@ -433,6 +468,21 @@ function ValidatorPlugin(rules, data, formId) {
             $form   = this.$forms[_id] = instance['$forms'][_id];
         } else { // binding a form out of context (outside of the main instance)
             $target             = document.getElementById(_id);
+
+            // validateFormById was designed for FORM elements. getElementById
+            // returns the first matching element regardless of tag, so a sibling
+            // <p id="X"> / <div id="X"> / etc. wins over a later-loaded
+            // <form id="X">. Surface the collision instead of crashing later
+            // inside bindForm with a cryptic
+            // `Cannot read properties of undefined (reading 'length')`.
+            if ( $target && !($target instanceof HTMLFormElement) ) {
+                throw new Error(
+                    '[ FormValidator::validateFormById(formId) ] `' + _id + '` resolves to <'
+                    + $target.tagName + '>, not a FORM. A non-FORM element shares the same id as '
+                    + 'the target form — rename one of them so the id is unique.'
+                );
+            }
+
             $validator.id           = _id;
             $validator.target       = $target;
 

package/framework/{v0.3.13 → v0.3.14}/core/router.js

@@ -118,9 +118,15 @@ function Router(env, scope) {
         // removed: direct pre-load of controller.js — index.js (in dev/cacheless mode) deletes and
         // re-requires controller.js internally, so pre-loading it here caused a double instantiation
         // (Domain constructor, swig init, etc.) on every request. Let index.js own the re-require.
-        require.cache[_(corePath +'/controller/index.js', true)] = require( _(corePath +'/controller/index.js', true) );
 
-        SuperController = require.cache[_(corePath +'/controller/index.js', true)];
+        // #B18 — Use the return value of require() directly instead of
+        // re-poisoning the cache slot with `require.cache[path] = require(path)`.
+        // The latter assigns the exports OBJECT (no `.exports` key) into the slot
+        // where Node expects a Module instance; downstream plain `require()`
+        // calls then read `.exports` off a bare exports object and get
+        // `undefined`. router.js was the last latent occurrence of this
+        // antipattern after the `refreshCore()` fix (`add6655e`).
+        SuperController = require(_(corePath +'/controller/index.js', true));
 
         if (_hotReload) _hotReload.core = false; // #M6 — clear flag after eviction
         corePath = null;
@@ -615,12 +621,13 @@ function Router(env, scope) {
                     //if (isCacheless) {
                         // Super controller
                         delete require.cache[require.resolve(_(corePath +'/controller/index.js', true))];
-                        require.cache[_(corePath +'/controller/index.js', true)] = require( _(corePath +'/controller/index.js', true) );
-
                         delete require.cache[require.resolve(filename)];
                     //}
 
-                    var SuperController     = require.cache[_(corePath +'/controller/index.js', true)];
+                    // #B18 — Same fix as the sibling at L116-127. require() returns
+                    // a freshly built Module instance; assigning the exports object
+                    // back into require.cache[path] poisons the slot.
+                    var SuperController     = require(_(corePath +'/controller/index.js', true));
 
 
                     var RequiredController  = require(filename);

package/framework/{v0.3.13 → v0.3.14}/core/server.isaac.js

@@ -41,6 +41,42 @@ const env               = process.env.NODE_ENV
     , isProductionScope = process.env.NODE_SCOPE_IS_PRODUCTION && process.env.NODE_SCOPE_IS_PRODUCTION.toLowerCase() === 'true'
 ;
 
+/**
+ * IP-allowlist check for admin-grade /_gina/* endpoints (/_gina/info,
+ * /_gina/cache/stats). #S7.
+ *
+ * Reads the allowlist from `process.gina._adminAllowList`, which `gna.js`
+ * populates at bundle init from `app.json` `admin.allowFrom` (defaults to
+ * loopback `['127.0.0.1', '::1']`). Same shape as `lib.metrics.isClientAllowed`
+ * but on a separate axis — admin endpoints expose process state (memory,
+ * uptime, HTTP/2 session counters, cache contents) and are gated separately
+ * from Prometheus scrapes.
+ *
+ * Reads the client IP from `req.socket.remoteAddress` only — never trusts
+ * `X-Forwarded-For` because reverse proxies could spoof it. Normalises
+ * `::ffff:IPv4` (IPv6-mapped IPv4) → `IPv4` so listing `127.0.0.1` matches
+ * both forms.
+ *
+ * Empty allowlist (`[]`) denies everyone — explicit lockdown choice.
+ * Missing `process.gina._adminAllowList` (init not yet fired) falls back
+ * to loopback-only, the safest default.
+ *
+ * @inner
+ * @param {http.IncomingMessage|http2.Http2ServerRequest} req
+ * @returns {boolean} true if client IP is allowed, false otherwise
+ */
+function isAdminClientAllowed(req) {
+    var list = (typeof process.gina === 'object' && process.gina && Array.isArray(process.gina._adminAllowList))
+        ? process.gina._adminAllowList
+        : ['127.0.0.1', '::1'];
+    if (list.length === 0) return false;
+    var ip = (req.socket && req.socket.remoteAddress)
+          || (req.connection && req.connection.remoteAddress)
+          || '';
+    if (ip.indexOf('::ffff:') === 0) ip = ip.slice(7);
+    return list.indexOf(ip) >= 0;
+}
+
 /**
  * Reloads all core and lib modules from disk by replacing their require.cache
  * entries with fresh exports. Excludes gna.js itself. Also refreshes the
@@ -663,6 +699,25 @@ function ServerEngineClass(options) {
 
             if ( request.method.toUpperCase() === 'GET' && /\_gina\/info$/i.test(request.url) ) {
 
+                // #S7 — IP allowlist gate. Mirrors the metrics endpoint
+                // gate at L605-621. 403 on deny.
+                if ( !isAdminClientAllowed(request) ) {
+                    var infoForbiddenBody    = JSON.stringify({ error: 'forbidden', message: '/_gina/info: client IP not in app.json admin.allowFrom' });
+                    var infoForbiddenHeaders = {
+                        'cache-control': 'no-cache, no-store, must-revalidate',
+                        'pragma':        'no-cache',
+                        'expires':       '0',
+                        'content-type':  'application/json; charset=utf8',
+                        'X-Powered-By':  'Gina/' + GINA_VERSION
+                    };
+                    if (response.stream) {
+                        response.stream.respond({ ':status': 403, ...infoForbiddenHeaders });
+                        return response.stream.end(infoForbiddenBody);
+                    }
+                    response.writeHead(403, infoForbiddenHeaders);
+                    return response.end(infoForbiddenBody);
+                }
+
                 var infoPayload = {
                     "cache-is-enabled": server._cacheIsEnabled,
                     "memory"  : process.memoryUsage(),
@@ -705,6 +760,25 @@ function ServerEngineClass(options) {
             }
 
             if ( request.method.toUpperCase() === 'GET' && /\/_gina\/cache\/stats$/i.test(request.url) ) {
+
+                // #S7 — IP allowlist gate. Same shape as the /_gina/info gate above.
+                if ( !isAdminClientAllowed(request) ) {
+                    var cacheStatsForbiddenBody    = JSON.stringify({ error: 'forbidden', message: '/_gina/cache/stats: client IP not in app.json admin.allowFrom' });
+                    var cacheStatsForbiddenHeaders = {
+                        'cache-control': 'no-cache, no-store, must-revalidate',
+                        'pragma':        'no-cache',
+                        'expires':       '0',
+                        'content-type':  'application/json; charset=utf8',
+                        'X-Powered-By':  'Gina/' + GINA_VERSION
+                    };
+                    if (response.stream) {
+                        response.stream.respond({ ':status': 403, ...cacheStatsForbiddenHeaders });
+                        return response.stream.end(cacheStatsForbiddenBody);
+                    }
+                    response.writeHead(403, cacheStatsForbiddenHeaders);
+                    return response.end(cacheStatsForbiddenBody);
+                }
+
                 cache.from(server._cached);
                 const cacheStatsData = JSON.stringify(cache.stats());
                 const cacheStatsHeaders = {

package/framework/{v0.3.13 → v0.3.14}/lib/cmd/bundle/list.js

@@ -48,12 +48,23 @@ function List(opt, cmd) {
                 // Tolerant — fall through with empty ports table.
             }
         }
+        // Full pre-scan of argv. No dispatch inside the loop — separating
+        // parsing from dispatch means flag ordering can't change behaviour
+        // (`--all --format=json` now produces the same JSON output as
+        // `--format=json --all`). The previous in-loop short-circuit on
+        // `!self.projectName` was also the root of the spurious
+        // `[ null ] is not a valid project name` error on the bare
+        // `gina bundle:list` no-arg call: CmdHelper initialises
+        // `cmd.projectName` to `null` (filterArgs only assigns from a
+        // `@<project>` argv token, per `lib/cmd/helper.js:77`), and the
+        // original post-loop dispatch only handled `undefined`.
+        var allFlag = false;
         for (let i=3, len=process.argv.length; i<len; i++) {
             if ( /^\-\-format\=/.test(process.argv[i]) ) {
-                self.format = process.argv[i].split(/\=/)[1]
+                self.format = process.argv[i].split(/\=/)[1];
             }
-            if ( /^\-\-all\=/.test(process.argv[i]) || !self.projectName ) {
-                return listAll()
+            if ( /^\-\-all(\=|$)/.test(process.argv[i]) ) {
+                allFlag = true;
             }
         }
 
@@ -73,16 +84,19 @@ function List(opt, cmd) {
         //     }
         // }
 
-        if ( typeof(self.projectName) == 'undefined' ) {
-            listAll()
-        } else if ( typeof(self.projectName) != 'undefined' && isDefined(self.projectName) ) {
-            listProjectOnly()
+        // Dispatch after the full scan. `self.projectName == null` matches
+        // both null (CmdHelper default) and undefined — either signals "no
+        // project specified", route to listAll().
+        if ( allFlag || self.projectName == null ) {
+            listAll();
+        } else if ( isDefined(self.projectName) ) {
+            listProjectOnly();
         } else {
             console.error('[ '+self.projectName+' ] is not a valid project name.');
-            process.exit(1)
+            process.exit(1);
         }
 
-        process.exit(0)
+        process.exit(0);
     }
 
     /**