gina 0.3.9-alpha.1 → 0.3.9

package/CHANGELOG.md

@@ -6,6 +6,22 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.3.9 - 2026-05-04
+### Added
+* Add a `process.gina._bundleFilterWraps[bundleName]` hook so bundles can wrap nunjucks filters at render time. Bundle-level monkey-patches on `lib.nunjucksFilters` do not survive `refreshCore()` (which creates a fresh lib singleton ~per-request in dev mode); the framework now applies registered wraps inside `registerGinaFilters` after the per-request filter factory runs.
+### Changed
+* Drop the redundant `<namespace>-` prefix from `resolveTemplatePath()` effective name in nunjucks rendering. Routes whose name already carries the namespace (e.g. `project-get`, `client-list`) previously resolved to `project/project-get.njk` and `client/client-list.njk`; they now resolve to the cleaner `<namespace>/<action>.njk` path (e.g. `project/get.njk`, `client/list.njk`).
+### Fixed
+* Guard `length` filter against null/undefined input in nunjucks-filters and swig-filters. Templates piping a missing variable through `| length` (e.g. `{{ breadcrumb | length }}`) now return 0 instead of crashing with a `TypeError`, matching upstream nunjucks `runtime.length` and Jinja2.
+* Handle Couchbase Node.js SDK 4.x `JsonTranscoder` pre-decoded session values in the v4 session-store. Previous code called `.toString()` on the already-parsed object (producing `"[object Object]"`) and then `JSON.parse`d it, surfacing as a 500 on every authenticated request that touched session retrieval.
+* Mirror `ctxObj.envVars` into `process.env` during `gna.js` bootstrap so third-party plugins (CSRF middleware, future env-readers) see env vars that `bin/cli`'s `filterArgs()` stripped before spawn. `setEnvVar` populates Gina's own context but did not touch `process.env`, leaving plugins reading the raw `process.env` with `undefined` values.
+* Preserve inner Swig string-literal quotes in mid-URL `{{ }}` expressions in `getAssets()`. The decorative-quote-strip guard was anchored (`/^\{\{/`), so an asset URL with `{{ }}` embedded mid-string had its inner Swig quotes stripped, the mangled URL landed in the cached layout `__ginaData.gina.view.assets`, and the runtime Swig pass then threw `Unexpected colon on line N` at parse time. The compile guard keeps its anchor — only fully-Swig URLs are pre-compiled at scan time; embedded `{{ }}` is left for the cached layout runtime Swig pass.
+* Isolate per-request middleware dispatch state in `nextMiddleware` via a new `createNextMiddleware()` factory. The previous shape held dispatch state on the function own properties (`._index`, `._count`, `._request`, `._response`, `._next`, `._nextAction`); under concurrent requests, request B setup at the entry point overwrote request A state, so A awaited middleware callbacks resumed against B `req` object — visible as sporadic `[csrf] no req.session.id` 500s when express-session correctly populated `req.session` for A but CSRF then ran with B `req`. Each call to `createNextMiddleware()` now returns a fresh closure with isolated state.
+* Add a `require.cache` fallback to the `lib` registry import in `controller.render-nunjucks.js`, mirroring `render-swig.js`. `server.isaac.js` `refreshCore()` overwrites the lib cache entry with the exports value (not a Module object); a plain `require("../../lib")` returns `undefined` after a refresh and crashes the module-level read of `Collection`, `Cache`, `nunjucksFilters`, and `nunjucksResolver`. Route every per-request lookup through a module-scope `libRef` variable that uses `|| require.cache[require.resolve("../../lib")]` as the fallback.
+* Promote `userData` keys to the top-level template context in `controller.render-nunjucks.js` for ergonomic parity with swig. The previous code only wrote each key to `data.page.data[k]`, contradicting the existing comment that promised top-level promotion (`{{ foo }}`); each key is now also mirrored to `data[k]` when not already defined.
+* Alias `data.data` to `data.page.data` before `env.render()` in nunjucks rendering. Page-shells under nunjucks layout inheritance (e.g. `{% set document = data.document %}`) evaluated to `undefined` because `data` was not a key in the env.render context object. Swig layouts already have this aliasing implicit via `{% set data = page.data %}` at `_layouts/layout.html:1`; nunjucks layouts now get the same lookup path framework-side.
+* Substitute `{{ page.X }}`, `{{ page.environment.X }}`, and `{{ page.data.session.X }}` placeholders inside the `ginaLoader` HTML string after `injectAssets()`. `gina.onload.min.js` is inserted as a literal HTML string and so cannot rely on nunjucks to resolve its tokens; without substitution, `window.onGinaLoaded` threw a `JSON.parse` SyntaxError on every page, leaving `gina.popin`, `gina.session`, `gina.forms`, and `window.onGenericXhrResponse` undefined and breaking every legacy popin and form-submit. Mirrors `render-swig.js` flatten-then-`whisper()` approach.
+
 ## 0.3.8 - 2026-04-26
 ### Fixed
 * Fixed `npm install -g gina` failing with `Cannot find module 'psl'` on fresh and upgrade installs (regression from 0.3.7). The pre/post-install scripts no longer load the framework `lib` registry — `psl` and `@rhinostone/swig` are now declared as top-level npm dependencies so the runtime resolves them via the standard module resolution chain, and a helpers pre-load in the install scripts ensures `lib/logger`'s circular load completes correctly so internal helpers' module-local `console` references bind to the full Logger singleton.

package/ROADMAP.md

@@ -15,7 +15,13 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.3.0` ✅ | Async/await · Dev hot-reload · MySQL & PostgreSQL connectors · AI Phase 2 · Tutorials · Mobile backend guide · Route radix tree · Connector peerDependencies · 103 Early Hints · HTTP/2 observability · Security & CVE page · Couchbase connector hardening · Inspector Phase 1 + Phase 2 · CLI Tier 1 (project lifecycle, port:set, framework:get) |
 | **Q3 2026** | `0.3.1` ✅ | Release workflow fixes · SQL index reporting Phase A · HTTP/2 direct stream for HTML · Dependency reduction (`ssl-checker`, `colors`, `uuid` removed — engine.io sole runtime dep) |
 | **Q3 2026** | `0.3.2` ✅ | JSON Schema for config files · Entity short-name aliases · Model loading fix · getConfig() proxy fix · Inspector tab presets & QI propagation |
-| **Q3 2026** | `0.3.3` | OpenAPI spec generation · CLI port:set & framework:get · TypeScript declarations · Explicit exports |
+| **Q3 2026** | `0.3.3` ✅ | OpenAPI spec generation · CLI port:set & framework:get · TypeScript declarations · Explicit exports · Swig npm migration · Live index introspection · Popin perf · Docker fixes |
+| **Q3 2026** | `0.3.4` ✅ | Patch: `gna.js` stale framework path fix · Release lifecycle `gna.js` sync |
+| **Q3 2026** | `0.3.5` ✅ | Security: `@rhinostone/swig` 1.5.0 (CVE-2023-25345 extended guards) · Browser-side swig parity |
+| **Q4 2026** | `0.3.6` ✅ | Inspector payload redaction (#R7) · Pre-commit & CI local-tool path guards · Private-token leak gate · Whisper Error fix (#B12) · `framework:init` hardening (#B13) · CORS preflight fix · `syncDocs` lockfile regen |
+| **Q4 2026** | `0.3.7` ✅ | Web Security CSRF trilogy (#CSRF1/2/3) · Nunjucks template engine opt-in (#NJ1–#NJ4) · Eval-safety hardening (#SCS1) · MCP server (#AI8 stdio + HTTP transports) · `connector:*` CLI (#CN10) · vendored-dep CVE-visibility lock · psl/optimist removal · Session.name drop-in identity |
+| **Q4 2026** | `0.3.8` ✅ | Patch: `npm install -g gina@latest` regression fix — `psl` + `@rhinostone/swig` promoted to top-level deps · install scripts decoupled from framework `lib` registry · helpers preload guarding `lib/logger` ↔ `framework/v*/helpers` circular dep |
+| **Q2 2026** | `0.3.9` ✅ | Consumer-feedback batch (11 framework patches): per-request middleware dispatch isolation · Couchbase 4.x JsonTranscoder · `length` filter null safety · `process.env` mirroring · 6 nunjucks render-pipeline patches (libRef fallback · namespace prefix drop · bundle filter wraps · top-level userData · `data.data` alias · ginaLoader placeholders) · `getAssets` mid-URL `{{ }}` strip-guard anchor |
 | **Q4 2026** | `0.4.0` | AI agents (MCP) · ScyllaDB connector · PWA scaffold · Prometheus metrics · Advanced tutorial · Website redesign · Docs offline ZIP · Bun investigation · Couchbase v2 removal · HTTP/2 hardening · Trailer support · CLI Tier 2 (bundle/project status, rename, copy, protocol:remove, minions) |
 | **Q1 2027** | `0.5.0` | ESM support · Template engine migration · Structured logging · Alt-Svc · HTTP/2 priorities · WebSocket over HTTP/2 · Inspector Production · CLI Tier 3 (project:move, framework:update, backup/restore, man pages) |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
@@ -119,10 +125,10 @@ Four focused follow-up sessions to close the deferred gap left by the `0.3.7-alp
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
-| 🔨 | **Port `lib/swig-filters` → `lib/nunjucks-filters`** — Mechanically port the 7 filters (`getUrl`, `getWebroot`, `length`, `nl2br`, `addHours`, `addDays`, `addYears`) into a sister library registered via `env.addFilter()` in `controller.render-nunjucks.js`. Closes the most user-visible gap — template authors get `{{ '/home' \| getUrl() }}` and the date helpers immediately. | `0.3.7` | Q4 2026 |
-| 🔨 | **`setResources` / `<gina>` layout placeholders** — Port the asset-cataloguing pipeline so build-time `<link>` / `<script>` tags are auto-injected into nunjucks layouts the same way they are into swig layouts. `data.page.view.stylesheets` / `.scripts` now populated before render; post-render `injectAssets` helper auto-injects stylesheets before `</head>`, scripts before `</body>` (or before `</head>` when `javascriptsDeferEnabled`), plus `externalPlugins` and the `ginaLoader` before `</head>`. Templates may opt in explicitly with `{{ page.view.stylesheets \| safe }}` — exact-substring detection skips the auto-inject when they do. | `0.3.7` | Q4 2026 |
-| 📋 | **Static HTML cache parity** — Port the swig disk-write/serve cache path so `cache:` keys in `routing.json` actually produce cached HTML for nunjucks routes. | `0.3.7` | Q4 2026 |
-| 📋 | **Early Hints 103 auto-send for CSS/JS preloads** — Move the 103 path in `controller.js this.render()` to be engine-agnostic. Pure perf optimisation; manual `self.setEarlyHints(linkHeader)` already works. | `0.3.7` | Q4 2026 |
+| ✅ | **Port `lib/swig-filters` → `lib/nunjucks-filters`** — Mechanically port the 7 filters (`getUrl`, `getWebroot`, `length`, `nl2br`, `addHours`, `addDays`, `addYears`) into a sister library registered via `env.addFilter()` in `controller.render-nunjucks.js`. Closes the most user-visible gap — template authors get `{{ '/home' \| getUrl() }}` and the date helpers immediately. | `0.3.7-alpha.3` | 2026-04-23 |
+| ✅ | **`setResources` / `<gina>` layout placeholders** — Port the asset-cataloguing pipeline so build-time `<link>` / `<script>` tags are auto-injected into nunjucks layouts the same way they are into swig layouts. `data.page.view.stylesheets` / `.scripts` now populated before render; post-render `injectAssets` helper auto-injects stylesheets before `</head>`, scripts before `</body>` (or before `</head>` when `javascriptsDeferEnabled`), plus `externalPlugins` and the `ginaLoader` before `</head>`. Templates may opt in explicitly with `{{ page.view.stylesheets \| safe }}` — exact-substring detection skips the auto-inject when they do. | `0.3.7-alpha.3` | 2026-04-23 |
+| ✅ | **Static HTML cache parity** — Port the swig disk-write/serve cache path so `cache:` keys in `routing.json` actually produce cached HTML for nunjucks routes. | `0.3.7-alpha.4` | 2026-04-23 |
+| ✅ | **Early Hints 103 auto-send for CSS/JS preloads** — Move the 103 path in `controller.js this.render()` to be engine-agnostic. Pure perf optimisation; manual `self.setEarlyHints(linkHeader)` already works. | `0.3.7-alpha.4` | 2026-04-23 |
 
 ### Eval safety
 

package/framework/v0.3.9/VERSION

@@ -0,0 +1 @@
+0.3.9

package/framework/{v0.3.9-alpha.1 → v0.3.9}/core/connectors/couchbase/lib/session-store.v4.js

@@ -198,6 +198,16 @@ module.exports = function(session, bundle){
         }
         if (err) return fn(err);
         if (!data || !data.value) return fn();
+        // FRAMEWORK PATCH (freelancer/v3): handle the case where data.value is
+        // already a parsed object (Couchbase Node.js SDK 4.x JsonTranscoder
+        // returns the decoded value, not the raw bytes). Without this, calling
+        // .toString() on an object produces "[object Object]" which JSON.parse
+        // can't handle and every authenticated request 500s on session-retrieval.
+        // Push upstream to gina-io/gina.
+        if (typeof data.value === 'object' && !Buffer.isBuffer(data.value)) {
+            console.debug('[SessionStore v4] (1) GOT data (already-parsed object)');
+            return fn(null, data.value);
+        }
         data = data.value.toString();
         console.debug('[SessionStore v4] (1) GOT data');
         // console.debug('[SessionStore v4] (2) GOT ' + data);

package/framework/{v0.3.9-alpha.1 → v0.3.9}/core/controller/controller.render-nunjucks.js

@@ -127,7 +127,13 @@ var inspectorRedact = require('lib/inspector-redact');
 // rendering without a layout (mirrors render-swig.js:494-498). Fetched via
 // the lib registry so the dev-mode hot-reload evictions of `lib/index.js`
 // don't poison the reference across requests.
-var Collection      = require('../../lib').Collection;
+//
+// FRAMEWORK PATCH (freelancer/v3): mirror render-swig.js's `|| require.cache[...]`
+// fallback. server.isaac.js refreshCore() overwrites the lib cache entry with the
+// exports value (not a Module object), so a plain `require()` here returns
+// undefined and crashes the module-level read. Push upstream to gina-io/gina.
+var libRef          = require('../../lib') || require.cache[require.resolve('../../lib')];
+var Collection      = libRef.Collection;
 // #NJ3 — static HTML cache writes. Module-scoped `cache` instance mirrors
 // `render-swig.js:6` and `render-json.js:5`. Per-request, the main render
 // function re-points it at the server's shared in-memory store (key:
@@ -135,7 +141,7 @@ var Collection      = require('../../lib').Collection;
 // (`server.isaac.js:1012-1067`) is engine-agnostic, so writes from this
 // delegate are served back on subsequent hits without going through the
 // controller at all.
-var cache           = new (require('../../lib').Cache)();
+var cache           = new (libRef.Cache)();
 
 /**
  * Caches a `nunjucks.Environment` per bundle template root so we don't
@@ -210,6 +216,16 @@ function resolveTemplatePath(data, localOptions) {
         if (effective === localOptions.namespace) {
             effective = 'index';
         }
+        // FRAMEWORK PATCH (freelancer/v3): drop redundant `<namespace>-` prefix
+        // from the file segment when present, so `project/project-get.njk`
+        // resolves to `project/get.njk` (and `client/client-list.njk` to
+        // `client/list.njk`). Lets route names that already carry the
+        // namespace (e.g. `project-get`, `client-list`) live at the cleaner
+        // `<namespace>/<action>.njk` path. Push upstream to gina-io/gina.
+        var nsPrefix = localOptions.namespace + '-';
+        if (effective.length > nsPrefix.length && effective.indexOf(nsPrefix) === 0) {
+            effective = effective.substring(nsPrefix.length);
+        }
         var rel = localOptions.namespace + '/' + effective;
         if (ext && !rel.endsWith(ext)) { rel += ext; }
         return rel;
@@ -465,7 +481,9 @@ function sendHtmlResponse(local, html) {
  * @returns {void}
  */
 function registerGinaFilters(env, self, local, localOptions) {
-    var nunjucksFilters = require('../../lib').nunjucksFilters
+    // FRAMEWORK PATCH (freelancer/v3): use module-scope libRef fallback so
+    // refreshCore's malformed cache entry doesn't return undefined here.
+    var nunjucksFilters = (libRef && libRef.nunjucksFilters)
         || require('../../lib/nunjucks-filters');
 
     // Same isProxyHost detection as render-swig.js:606-625. Duplicated here
@@ -502,6 +520,26 @@ function registerGinaFilters(env, self, local, localOptions) {
         res:         local.res
     });
 
+    // FRAMEWORK PATCH (freelancer/v3): apply bundle-level filter wraps registered
+    // on process state. Bundle-level monkey-patches on `lib.nunjucksFilters`
+    // don't survive refreshCore() (which creates a fresh lib singleton ~per-
+    // request in dev mode), so bundles register their wrap on
+    // `process.gina._bundleFilterWraps[bundleName]` and the framework applies
+    // them here. Push upstream to gina-io/gina alongside Bugs A-D.
+    var bundleFilterWraps = (process.gina && process.gina._bundleFilterWraps) || {};
+    Object.keys(bundleFilterWraps).forEach(function (bundleName) {
+        var wrap = bundleFilterWraps[bundleName];
+        if (typeof wrap === 'function') {
+            try {
+                filters = wrap(filters) || filters;
+            } catch (wrapErr) {
+                try {
+                    console.warn('[render-nunjucks] bundle filter wrap failed for ' + bundleName + ': ' + (wrapErr.message || wrapErr));
+                } catch (e) {}
+            }
+        }
+    });
+
     for (var name in filters) {
         if (typeof filters[name] === 'function' && name !== 'getConfig') {
             env.addFilter(name, filters[name]);
@@ -717,10 +755,11 @@ module.exports = async function renderNunjucks(userData, displayInspector, errOp
     // Fetch the nunjucks module from the process-cache. `get()` throws if
     // the bundle-startup load did not succeed — we surface that cleanly
     // via throwError so the usual error page pipeline handles it.
+    // FRAMEWORK PATCH (freelancer/v3): use module-scope libRef fallback.
     var nunjucks;
     try {
-        nunjucks = require('../../lib').nunjucksResolver
-            ? require('../../lib').nunjucksResolver.get()
+        nunjucks = (libRef && libRef.nunjucksResolver)
+            ? libRef.nunjucksResolver.get()
             : require('../../lib/nunjucks-resolver').get();
     } catch (err) {
         return self.throwError(err);
@@ -781,13 +820,29 @@ module.exports = async function renderNunjucks(userData, displayInspector, errOp
 
     // Merge user data into page.data so templates can access via {{ page.data.foo }}
     // or {{ foo }} at top level (promoted for ergonomic parity with swig).
+    // FRAMEWORK PATCH (freelancer/v3): the comment promised top-level promotion but
+    // the original code only wrote to data.page.data. Mirror to top-level too.
     if (userData && typeof(userData) === 'object') {
         if (!data.page.data) { data.page.data = {}; }
         Object.keys(userData).forEach(function (k) {
             data.page.data[k] = userData[k];
+            if (typeof(data[k]) === 'undefined') {
+                data[k] = userData[k];
+            }
         });
     }
 
+    // FRAMEWORK PATCH (freelancer/v3): Bug J — alias `data.data` to `data.page.data`
+    // so page-shell `{% set X = data.Y %}` resolves under nunjucks layout
+    // inheritance. Mirrors swig's `_layouts/layout.html:1` `{% set data = page.data %}`.
+    // Without this, page-shells like `estimate/get.njk:11 {% set document = data.document %}`
+    // evaluate to undefined (no `data` key in the env.render context object) and
+    // the .overview section renders empty even though page.data.document is fully
+    // populated. Push upstream to gina-io/gina alongside Bugs A-I.
+    if (data && data.page && data.page.data) {
+        data.data = data.page.data;
+    }
+
     var env;
     try {
         env = getEnvironment(nunjucks, templateRoot, {
@@ -924,6 +979,38 @@ module.exports = async function renderNunjucks(userData, displayInspector, errOp
         try { console.warn('[render-nunjucks] asset injection skipped: ' + (assetErr.message || assetErr)); } catch (e) {}
     }
 
+    // FRAMEWORK PATCH (freelancer/v3): substitute {{ page.X }} / {{ page.environment.X }}
+    // placeholders inside ginaLoader (gina.onload.min.js), which is inserted as a literal
+    // HTML string by injectAssets() and therefore cannot rely on nunjucks to resolve its
+    // tokens. Mirrors render-swig.js:572-582 (flatten dict) + 1276 (whisper call). Without
+    // this, `window.onGinaLoaded` throws a JSON.parse SyntaxError on every page, leaving
+    // gina.popin / gina.session / gina.forms / window.onGenericXhrResponse undefined and
+    // breaking every legacy popin + form-submit. Push upstream to gina-io/gina alongside
+    // Bugs A-E.
+    try {
+        if (data && data.page && typeof data.page === 'object' && typeof whisper === 'function') {
+            var ginaLoaderDic = {};
+            for (var _d in data.page) {
+                ginaLoaderDic['page.' + _d] = data.page[_d];
+            }
+            if (typeof data.page.environment === 'object' && data.page.environment !== null) {
+                for (var _k in data.page.environment) {
+                    ginaLoaderDic['page.environment.' + _k] = data.page.environment[_k];
+                }
+            }
+            // gina.onload.min.js also references `{{ page.data.session.X }}` (depth 3)
+            // for session id/timeout/createdAt/lastModified — flatten that level too.
+            if (data.page.data && typeof data.page.data === 'object' && data.page.data.session && typeof data.page.data.session === 'object') {
+                for (var _s in data.page.data.session) {
+                    ginaLoaderDic['page.data.session.' + _s] = data.page.data.session[_s];
+                }
+            }
+            html = whisper(ginaLoaderDic, html, /\{{ ([a-zA-Z.]+) \}}/g);
+        }
+    } catch (whisperErr) {
+        try { console.warn('[render-nunjucks] ginaLoader whisper substitution skipped: ' + (whisperErr.message || whisperErr)); } catch (e) {}
+    }
+
     // Inspector dev-payload injection (dev mode only; no-op otherwise).
     try {
         html = injectInspectorScripts(html, data, self, local, displayInspector);

package/framework/{v0.3.9-alpha.1 → v0.3.9}/core/gna.js

@@ -221,6 +221,13 @@ if (process.argv.length >= 3 /**&& /gina$/.test(process.argv[1])*/ ) {
                         evar = false
                     }
 
+                    // FRAMEWORK PATCH (freelancer/v3): mirror ctxObj.envVars into process.env so
+                    // third-party plugins (Csrf, future env-readers) see what filterArgs() stripped
+                    // in the supervisor before spawn. Push upstream to gina-io/gina.
+                    if ( typeof(obj[a]) != 'undefined' && obj[a] !== null ) {
+                        process.env[a] = String(obj[a]);
+                    }
+
                     setEnvVar(a, evar, true)
 
                 }

package/framework/{v0.3.9-alpha.1 → v0.3.9}/core/server.js

@@ -1063,7 +1063,14 @@ function Server(options) {
             //         .replace(/((src|href|srcset)\=\"|(src|href|srcset)\=\')/g, '')
             //         .replace(/\"/g, '')
             // ;
-            if ( !/^\{\{/.test(url) ) {
+            // FRAMEWORK PATCH (freelancer/v3): drop the `^` anchor so the
+            // decorative-quote strip is also skipped when `{{ }}` is embedded
+            // mid-string (e.g. `css/main.css?cache={{ ''|formatDate('HH:MM:ss') }}`).
+            // Without this, inner Swig string-literal quotes get stripped, the
+            // expression becomes `{{ |formatDate(HH:MM:ss) }}`, and the cached
+            // layout's runtime Swig pass throws "Unexpected colon on line N".
+            // Reproduces in v0.3.9-alpha.2 (last touched 2026-04-26).
+            if ( !/\{\{/.test(url) ) {
                 url = url.replace(/(\"|\')/g, '');
             }
             if (swig && /^\{\{/.test(url) ) {
@@ -2756,6 +2763,8 @@ function Server(options) {
                     && self.instance._expressMiddlewares.length > 0
                 ) {
 
+                    // FRAMEWORK PATCH (freelancer/v3): Bug I — per-request dispatcher
+                    var nextMiddleware = createNextMiddleware();
                     nextMiddleware._index        = 0;
                     nextMiddleware._count        = self.instance._expressMiddlewares.length-1;
                     nextMiddleware._request      = request;
@@ -3628,6 +3637,17 @@ function Server(options) {
      * @private
      * @param {Error|boolean} err - Error from the previous middleware, or false
      */
+    // FRAMEWORK PATCH (freelancer/v3): Bug I — wrap nextMiddleware in a
+    // per-request factory. The original function held dispatch state on its
+    // own properties (._index, ._request, ._response, ._next, ._nextAction).
+    // Under concurrent requests, request B's setup at the entry point
+    // overwrote request A's state, so A's awaited middleware callbacks
+    // resumed against B's req object — visible as "[csrf] no req.session.id"
+    // sporadic 500s when express-session correctly populated req.session for
+    // A but CSRF then ran with B's req that never went through session.
+    // Each call to createNextMiddleware now returns a fresh function with
+    // closure-isolated state. Push upstream to gina-io/gina.
+    var createNextMiddleware = function() {
     var nextMiddleware = function(err) {
 
         var router              = local.router;
@@ -3681,6 +3701,8 @@ function Server(options) {
             }
         });
     };
+        return nextMiddleware;
+    };
 
     /**
      * Detects CORS preflight (OPTIONS) requests by inspecting the method,
@@ -4092,6 +4114,8 @@ function Server(options) {
 
         if (matched) {
             if ( /^isaac/.test(self.engine) && self.instance._expressMiddlewares.length > 0) {
+                // FRAMEWORK PATCH (freelancer/v3): Bug I — per-request dispatcher
+                var nextMiddleware = createNextMiddleware();
                 nextMiddleware._index        = 0;
                 nextMiddleware._count        = self.instance._expressMiddlewares.length-1;
                 nextMiddleware._request      = req;

package/framework/{v0.3.9-alpha.1 → v0.3.9}/lib/nunjucks-filters/src/main.js

@@ -338,6 +338,13 @@ function NunjucksFilters(conf) {
      *   {{ users | length }}
      */
     self.length = function (input, obj) {
+        // Match upstream nunjucks `runtime.length` / Jinja2: undefined or null → 0.
+        // Without this guard, `typeof(input.count)` dereferences `.count` first
+        // and throws on undefined — crashing any template that pipes a missing
+        // variable through `| length`.
+        if ( input == null ) {
+            return 0;
+        }
         if ( typeof(input.count) != 'undefined' ) {
             return input.count();
         } else {

package/framework/{v0.3.9-alpha.1 → v0.3.9}/lib/swig-filters/src/main.js

@@ -318,6 +318,13 @@ function SwigFilters(conf) {
     // Extends default `length` filter
     self.length = function (input, obj) {
 
+        // Match upstream nunjucks `runtime.length` / Jinja2: undefined or null → 0.
+        // Without this guard, `typeof(input.count)` dereferences `.count` first
+        // and throws on undefined — crashing any template that pipes a missing
+        // variable through `| length`.
+        if ( input == null ) {
+            return 0
+        }
         if ( typeof(input.count) != 'undefined' ) {
             return input.count()
         } else {

package/framework/{v0.3.9-alpha.1 → v0.3.9}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.3.9-alpha.1",
+  "version": "0.3.9-alpha.2",
   "dependencies": {
     "@rhinostone/swig": "^1.6.0",
     "psl": "^1.15.0"

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.3.9-alpha.1/core/gna');
+var _gna = require('./framework/v0.3.9/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.3.9-alpha.1/core/controller');
-var EntitySuper     = require('./framework/v0.3.9-alpha.1/core/model/entity');
+var SuperController = require('./framework/v0.3.9/core/controller');
+var EntitySuper     = require('./framework/v0.3.9/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.3.9-alpha.1/lib/uuid');
+var uuid = require('./framework/v0.3.9/lib/uuid');
 
 module.exports = {
 

package/llms.txt

@@ -870,3 +870,7 @@ YAML indent trap: the heredoc body and the `EOF` terminator must land at column
 82. **Source-inspection tests that assert source order — `src.indexOf('<funcName>(<args>)')` matches the function DEFINITION before the call site, not the call site.** When a test asserts "A must be called before B" via `indexOf` on a function-name-with-args fragment, the match lands on the `function <funcName>(<args>)` definition near the top of the file, not the call site lower in the body. If both names are defined in the same source-order as their call sites, the assertion accidentally passes for the wrong reason; if they're defined in a different order than they're called (helper defined first, used last), it fails for the wrong reason. **Discrimination test**: `grep -c '<pattern>' <file>` — if the count is > 1, the indexOf is ambiguous and the assertion is unreliable. **Fix**: search for a unique call-site fragment that doesn't appear in the function definition — typically the assignment LHS (`requestOrigin = parseRequestOrigin(req)`, `presented = readPresentedToken(req`). Definitions never contain the assignment target. Same trap applies to any pattern where definition and call share the same identifier syntax — method names, event listener attachments, even `console.error('[<feature>]'` template strings. Precedent: 2026-04-26 #CSRF3 implementation — section 14 source-inspection test "Origin pre-filter runs AFTER the csrfExempt short-circuit" failed at first because `indexOf('parseRequestOrigin(req)')` matched the `function parseRequestOrigin(req)` definition (line 152) before the call site (line 531); switched to `indexOf('requestOrigin = parseRequestOrigin(req)')` (assignment-form, unique to the call site). The sibling "BEFORE token verify" test passed only by coincidence — the `parseRequestOrigin` definition was already before the `readPresentedToken` definition in the file.
 
 83. **`Origin: "null"` is a real value browsers send — sandboxed iframes (`<iframe sandbox>`), `file://` pages, and some redirected requests carry the literal string `"null"` in the Origin header (and in `Sec-Fetch-Site: cross-site` flows).** Origin-checking code that does `if (origin) { /* allowlist match */ }` treats `"null"` as truthy and tries to match it. Without an explicit guard the result is wrong-for-the-right-outcome at best: the allowlist almost never contains `"null"`, so the request 403s — but for the wrong reason (it should fall through to the Referer fallback or a known-no-origin handler, not be rejected for "origin not in allowlist"). The same trap applies to CORS allowlists, CSRF Origin pre-filters, audit logging, and any code branching on `Origin`. **Fix**: add an explicit `s === 'null'` guard at the start of the Origin parser, treating `"null"` exactly like an absent header — empty result, fall through to the next signal (Referer, Sec-Fetch metadata, etc.). Document the guard with a brief comment so it isn't "cleaned up" by a future contributor who reads it as a no-op string check. Precedent: 2026-04-26 #CSRF3 implementation — `parseOriginString` at `core/plugins/lib/csrf/src/main.js:108` returns `null` (the JS literal) when input is the string `"null"`, so `parseRequestOrigin` falls back to parsing the host out of `Referer`. Two unit tests pin this behaviour: `Origin: "null"` + missing `Referer` → 403 with reason "missing origin/referer"; `Origin: "null"` + valid `Referer` → next() called. Without the guard, the missing-Referer case would have 403'd with reason "origin not allowed", masking the real problem from any operator reading the log.
+
+84. **Local-tool doc files at gitignored paths drift independently across worktree splits — git merges don't carry gitignored content, so each worktree's local docs must be maintained separately.** A primary repo (`develop`) and a linked worktree (`dev/wip` via `git worktree add`) hold independent gitignored doc copies; a version bump on the primary updates its local docs via tooling, but the linked worktree's copies stay at the previous version because gitignored files don't FF across `git merge --ff-only`. **Auto-update on the primary worktree**: version-bump scripts read `script/.local-sync-targets.json` (gitignored — lists relative paths to local doc files), iterate entries, regex-replace `v<old>` → `v<new>` with `(?![\\d.])` lookahead to avoid clobbering longer prefix-sharing versions. Tracked source code names only the generic config file, never the targets — no public-surface leak of local-tool path names. Same indirection already in `script/post_publish.js → bumpVersion`; replicated in `script/prepare_version.js` for non-publish bumps (added 2026-04-29). **Manual update on linked worktrees**: the project's gitignored git-workflow doc gets a post-merge state-check step instructing the maintainer to grep version refs after every fast-forward and update mismatches. **Generalises**: any worktree-split repo with gitignored doc files has the same pattern. Each worktree's local-doc version refs match its OWN `package.json` — versions can legitimately differ between branches at different cuts. Precedent: 2026-04-29 — discovered drift in two local-doc files (primary on `0.3.9-alpha.2` had docs saying `alpha.11`; linked on `0.3.7-alpha.10` had docs saying `alpha.8`); fixed manually, then automated via the existing `.local-sync-targets.json` indirection.
+
+85. **Tracked source code that reads/writes local-tool files must use a gitignored config-file indirection — naming the local-tool paths directly in tracked source CONTENT is a public-surface leak even when the operation is functional.** Extends entry #68's "local-tool path leaks have three surfaces" by adding a fourth: tracked-script body content (path string literals, code comments, variable names, log/console message strings). **Counterfactual check before writing**: would removing every mention of the local-tool name BREAK the feature, or just make the path configurable? If the latter, the mention is not load-bearing — extract to a gitignored sidecar config the script reads at runtime. Compare to the existing leak-filter regex in `script/prepare_version.js` (already quoted by entry #68) — THAT pattern IS product functionality (the filter literally needs to identify the path to filter it out), allowed exception. **Existing pattern to mirror**: `script/post_publish.js → bumpVersion` reads `script/.local-sync-targets.json` (gitignored — lists relative paths to operate on), iterates entries, applies generic regex-replace. Tracked source names only the generic config file, never the targets. The same shape was replicated in `script/prepare_version.js` (entry #84) after a first-attempt mistake. **The "Don't strip what you haven't surveyed" mirror — "Don't ADD a public-surface mention without surveying the rule first"**. Recovery cost is asymmetric: removal requires `git filter-repo` + force-push (and force-push to a public default branch is itself a high-friction operation per entry #79), addition is one keystroke. Always run the leak-scan regex (per entry #68's documented patterns) against the diff BEFORE staging — `git diff <file> | grep '^+' | grep -v '^+++' | grep -iE '<leak-patterns>'` — not after pushing. Precedent: 2026-04-29 — first attempt at extending `prepare_version.js` for the worktree-drift fix (entry #84) named the local-doc path directly in 6+ places (path literal, two comments, variable names, two log strings); user surfaced the violation before commit during a "are you sure there won't be side effects?" review pass; reverted to the `post_publish.js` indirection pattern in the same session, then committed clean.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.3.9-alpha.1",
+  "version": "0.3.9",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -56,7 +56,7 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.3.9-alpha.1/core/gna",
+  "main": "./framework/v0.3.9/core/gna",
   "types": "./types/index.d.ts",
   "typesVersions": {
     "*": {

package/framework/v0.3.9-alpha.1/VERSION

@@ -1 +0,0 @@
-0.3.9-alpha.1