gina 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -6,6 +6,10 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 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.
+
 ## 0.3.7 - 2026-04-26
 ### Added
 * Released `0.3.7` — cumulative stable of the `0.3.7-alpha.1` through `0.3.7-alpha.10` cycle. Headline tracks: **Web Security CSRF trilogy** (`gina.plugins.Session()` cookie hardening + `gina.plugins.Csrf()` signed double-submit token middleware + Origin/Referer pre-filter; OWASP ASVS 4.0 V4.2.1 aligned; opt-in plugin shape; per-route `csrfExempt: true` for webhook receivers). **Nunjucks template engine opt-in** (`render.engine = "nunjucks"` per bundle; filter parity #NJ1, setResources/asset injection #NJ2, render cache #NJ3, Early Hints 103 auto-send #NJ4). **MCP server** (`bundle:mcp` static manifest emit + `bundle:mcp-start` stdio and HTTP transports; #AI8 Phases 1/2a/2b). **Connector CLI** (`connector:list/add/rm/migrate`; #CN10). **Eval-safety hardening** (#SCS1 family — collection safe-evaluator + validator-plugin grammar-locked walker replacements; vendored-dep CVE-visibility invariant locked in via OSV scan workflow). Supply-chain trim (`psl` swap for vendored MPL-2.0 PSL data, `optimist` removal). Release-pipeline hardening (`gna.js` stable-version sync at framework-dir rename, StateStore + gina.db sync across renames, asset-plugin build honours `--gzip-bin`/`--brotli-bin` overrides). Plus `Session.name` drop-in identity restoration in alpha.10. See per-alpha sections for per-feature detail and test counts; full suite 3822/3822 at the stable cut.

package/framework/v0.3.8/VERSION

@@ -0,0 +1 @@
+0.3.8

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.7/core/gna');
+var _gna = require('./framework/v0.3.8/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.3.7/core/controller');
-var EntitySuper     = require('./framework/v0.3.7/core/model/entity');
+var SuperController = require('./framework/v0.3.8/core/controller');
+var EntitySuper     = require('./framework/v0.3.8/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.3.7/lib/uuid');
+var uuid = require('./framework/v0.3.8/lib/uuid');
 
 module.exports = {
 

package/llms.txt

@@ -861,8 +861,12 @@ YAML indent trap: the heredoc body and the `EOF` terminator must land at column
 
 78. **`git filter-repo` operational gotchas — second-run prompts, origin removal, committer-date SHA churn, and the local-only-tag false positive that makes a previously-cleaned repo *look* like it still has leaks.** Four traps in order: (1) **prior-run safety prompt** — if `.git/filter-repo/already_ran` exists from an earlier rewrite, the next run prints "Treat this run as a continuation of filtering in the previous run (Y/N)?" and reads stdin. `--force` does not bypass it. Pipe `echo Y |` for non-interactive runs. (2) **origin removed** — filter-repo deletes the `origin` remote at the end of every run by design ("so you don't accidentally push the rewritten history"). After the rewrite, `git remote add origin https://github.com/<owner>/<repo>.git` before any push. (3) **committer-date SHA churn** — filter-repo updates committer dates to "now" on every commit it walks, even when message and tree are unchanged. Every reachable commit gets a new SHA. Net effect: a no-op rewrite of an already-clean branch still produces a force-push divergence between local and origin. (4) **local-only-tag false positive** — `git log --all` reaches every ref, including local-only safety-net tags created by prior rewrites (`pre-rewrite-*-DATE`, `pre-history-scrub-*-DATE`). Those tags preserve un-substituted commits as personal backups. They are NOT on origin (verify with `git ls-remote origin 'refs/tags/pre-*'`) and therefore not violating the public-surface rule. Before re-running filter-repo on a previously-cleaned repo, check leak counts per branch with `git log <ref> --format='%s%n%b' | grep -iE '<patterns>' | wc -l` for each live branch individually — if all are zero, the live branches are clean and the only "leaks" left are in personal local-only tags that don't need rewriting. Precedent: 2026-04-25 second-pass leak scrub on gina-io/gina — comprehensive `git log --all` audit found 4 commit subjects + 3 commit bodies with descriptive feature mentions, but per-branch checks showed origin develop/master/dev/wip all already at 0 leaks. The remaining matches lived only in `pre-rewrite-*-20260421T233346Z` tags from a 2026-04-21 prior filter-repo. Today's filter-repo did push develop and dev/wip with cosmetically-different SHAs (force-pushed for nothing) before the per-branch verification surfaced that master was already clean. The reflex "saw leaks via `git log --all`, run filter-repo" needs the per-branch refinement step to avoid unnecessary force-push churn on tracking clones.
 
-79. **GitHub branch protection — `allow_force_pushes: false` blocks ALL force-pushes including admin (independent of `enforce_admins`); the dedicated subfield REST endpoint for this flag does not exist.** Two non-obvious behaviors: (1) **flag interaction** — `enforce_admins: false` does NOT mean admins can force-push when `allow_force_pushes: false`. The two flags work on different rule categories: `enforce_admins` controls whether review-style protections (required reviews, status checks) apply to admin actors; `allow_force_pushes` is a flat protocol-level block on history rewriting that GitHub's git backend rejects regardless of admin status. So `enforce_admins: false` + `allow_force_pushes: false` means: admins can merge without review, but cannot force-push. To force-push to a protected branch as admin, `allow_force_pushes` must be flipped to `true` (temporarily) before the push, then back to `false` after. (2) **subfield endpoint absence** — GitHub's REST API documents per-subfield endpoints for some protection flags (`POST/DELETE /repos/.../protection/required_signatures`, `enforce_admins`), but `POST /repos/.../protection/allow_force_pushes` and `DELETE /repos/.../protection/allow_force_pushes` both return `404 Not Found`. The subfield API is partial. To toggle `allow_force_pushes`, use either the full `PUT /repos/.../protection` payload (with all required fields including `required_status_checks`, `enforce_admins`, `required_pull_request_reviews`, `restrictions` — null for those without rules), or `DELETE /repos/.../protection` to drop protection entirely then re-`PUT` to recreate. The web UI Settings → Branches → "Allow force pushes" toggle is also a clean path when an admin is at the keyboard. **Best non-destructive workflow** when force-push is needed for a one-off operation: have an admin lift via web UI → push → admin re-enables. The API path is brittle (the full-PUT payload must be reconstructed exactly to avoid losing other rule settings). Precedent: 2026-04-25 leak scrub — attempted `gh api -X POST repos/gina-io/gina/branches/master/protection/allow_force_pushes` to allow a force-push of master, got 404 (subfield endpoint absent), the push correctly failed, no protection state was modified (verified after via `gh api .../protection --jq`). The 404 was harmless — neither flip happened — but the master push didn't go through either. master turned out to already be clean from the prior rewrite, so no push was actually needed.
+79. **GitHub branch protection — `allow_force_pushes: false` blocks ALL force-pushes including admin (independent of `enforce_admins`); the dedicated subfield REST endpoint for this flag does not exist.** Two non-obvious behaviors: (1) **flag interaction** — `enforce_admins: false` does NOT mean admins can force-push when `allow_force_pushes: false`. The two flags work on different rule categories: `enforce_admins` controls whether review-style protections (required reviews, status checks) apply to admin actors; `allow_force_pushes` is a flat protocol-level block on history rewriting that GitHub's git backend rejects regardless of admin status. So `enforce_admins: false` + `allow_force_pushes: false` means: admins can merge without review, but cannot force-push. To force-push to a protected branch as admin, `allow_force_pushes` must be flipped to `true` (temporarily) before the push, then back to `false` after. (2) **subfield endpoint absence** — GitHub's REST API documents per-subfield endpoints for some protection flags (`POST/DELETE /repos/.../protection/required_signatures`, `enforce_admins`), but `POST /repos/.../protection/allow_force_pushes` and `DELETE /repos/.../protection/allow_force_pushes` both return `404 Not Found`. The subfield API is partial. To toggle `allow_force_pushes`, use either the full `PUT /repos/.../protection` payload (with all required fields including `required_status_checks`, `enforce_admins`, `required_pull_request_reviews`, `restrictions` — null for those without rules), or `DELETE /repos/.../protection` to drop protection entirely then re-`PUT` to recreate. The web UI Settings → Branches → "Allow force pushes" toggle is also a clean path when an admin is at the keyboard. **Best non-destructive workflow** when force-push is needed for a one-off operation: have an admin lift via web UI → push → admin re-enables. The API path is brittle (the full-PUT payload must be reconstructed exactly to avoid losing other rule settings). Precedent: 2026-04-25 leak scrub — attempted `gh api -X POST repos/gina-io/gina/branches/master/protection/allow_force_pushes` to allow a force-push of master, got 404 (subfield endpoint absent), the push correctly failed, no protection state was modified (verified after via `gh api .../protection --jq`). The 404 was harmless — neither flip happened — but the master push didn't go through either. master turned out to already be clean from the prior rewrite, so no push was actually needed. **2026-04-26 update (gina@0.3.7 stable cut, master-reset session)** — UI toggle did NOT take effect. Two attempts via Settings → Branches → "Allow force pushes" → Save left the underlying state unchanged (force-push still rejected with `GH006: Protected branch update failed`). Classic protection settings looked normal; rulesets API was empty (no competing rule). API-fallback PUT (full payload, `allow_force_pushes: true`) worked first try; flipped back after the push. Possible causes: stale browser session, Org-level enforcement, UI bug. **Refined pattern**: if the UI doesn't take effect after one attempt (verify immediately with `gh api repos/<owner>/<repo>/branches/<branch>/protection --jq .allow_force_pushes.enabled`), fall back to API-PUT — don't retry the UI. Saves a round-trip on a class of failure that's hard to diagnose at the UI layer.
 
 80. **Plan-vs-shipped attribute drift — when a multi-commit feature plan declares an interface attribute name, the shipped implementation may diverge, and downstream commits silently propagate the wrong name unless every fresh session re-grounds against the source.** The trap: a planning document or upstream commit prompt declares an interface attribute (e.g. "the plugin attaches the token to `req._csrfToken`"). The actual implementation, once written, names it differently (`req.csrfToken` — no underscore). Downstream commits that depend on the attribute (controller exposing it to template context, validator AJAX reading it off `req`, tests asserting on the name) all reference the original planned name unless their author re-verifies. The plan looks coherent; the code drifts. **Detection pattern**: every fresh agent session implementing a downstream commit must `grep -n '<attribute>' <upstream-source-file>` before referencing the attribute. If the plan and the source disagree, the source wins — re-read the plan, fix the references, flag the upstream-plan inconsistency in the session report so the planner can correct future-downstream prompts. **The source of truth for an in-flight feature is the shipped code on `develop`, not the upstream plan or prompt.** Plans rot the moment implementation deviates; planning hygiene means re-grounding every multi-commit feature against the latest develop tip before downstream work. Precedent: 2026-04-25 #CSRF2 implementation — the plan-of-record (commit-3 prompt) said `req._csrfToken`; commit-1's plugin attached `req.csrfToken` (verified at `core/plugins/lib/csrf/src/main.js:377,407`). The fresh agent for commit 3 caught it via the grep pattern and used the correct name, preventing silent wrong-attribute propagation into controller.js + 25 new tests + the planned docs guide.
 
 81. **CI flake-vs-regression triage — when a CI run fails on a commit, look for a same-message-different-SHA pair before assuming the code is buggy.** Rebases or amends produce two commits with identical messages but different SHAs. If `gh run list --repo <owner>/<repo> --branch <branch> --limit 10 --json databaseId,conclusion,headSha,name,displayTitle` shows the earlier SHA passed Tests and the later SHA failed, run `git diff --stat A..B` between them — empty output proves byte-identical content. Same content + different CI outcome = environmental flake, not regression, and the test should not be touched (per the "Don't change existing tests unless asked" rule). **Reproduce shape matters**: a single-file local run (`node --test test/lib/<file>.test.js`) is necessary but not sufficient — CI invokes all four directories in one process (`node --test test/core/*.test.js test/lib/*.test.js test/bin/*.test.js test/integration/helper.test.js`), and module / parallelism state shape differs between the two. Reproduce with the **exact CI invocation** before falling back to a rerun. **Cheapest discriminator order**: (1) `git diff --stat` between same-message SHAs (proves content-identical, ~1 second); (2) full-suite local invocation with the exact CI command (proves logic-deterministic at scale, ~30s); (3) `gh run rerun <id> --repo <owner>/<repo>` if (1)+(2) survive — green retry confirms environmental flake, red retry escalates to CI-environment investigation (Node version drift, runner timing, fixture pollution across the parallel file dispatch). **Watchlist hygiene**: log single-occurrence flakes to a local post-mortem journal under "CI flake watchlist" — `gh run list` retention defaults to 90 days, so without a local note a recurrence in 6 months looks like a first occurrence. Two occurrences of the same flake on a deterministic in-memory test = pattern, not coincidence. Precedent: 2026-04-26 — `test/lib/collection.test.js > 05 - delete > delete: Hotel without ids WHERE country = France` flaked once on run #24938620953 (`d1ea0a72`, 2026-04-25, Node 24.14.1, Ubuntu); same-content earlier SHA `623e4232` had passed; full-suite local run was 3766/3766 clean; rerun went green. Watchlist entry filed in the local post-mortem journal.
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "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.7/core/gna",
+  "main": "./framework/v0.3.8/core/gna",
   "types": "./types/index.d.ts",
   "typesVersions": {
     "*": {
@@ -78,7 +78,9 @@
   "license": "MIT",
   "readmeFilename": "README.md",
   "dependencies": {
-    "engine.io": "^6.0.0"
+    "@rhinostone/swig": "^1.6.0",
+    "engine.io": "^6.0.0",
+    "psl": "^1.15.0"
   },
   "devDependencies": {
     "csso-cli": "4.0.2",

package/script/post_install.js

@@ -61,14 +61,44 @@ var getUserHome = function() {
 // `colors` dependency removed in 0.3.1 — ANSI codes are now built into the logger.
 // No temporary install needed.
 
-var lib         = require('./lib');
-var console     = lib.logger;
+// Framework lib registry is intentionally not loaded here. At install time the
+// framework's nested deps (psl, @rhinostone/swig) may not yet be resolvable, and
+// `lib/domain` would crash on `require('psl')`. Node's built-in `console` is
+// sufficient for the install scripts; `console.setLevel` (a `lib.logger`-only
+// method) is gated below.
 
 var scriptPath = __dirname;
 var ginaPath = (scriptPath.replace(/\\/g, '/')).replace('/script', '');
-var help        = require(ginaPath + '/utils/helper.js');
 var pack        = ginaPath + '/package.json';
 pack =  (isWin32()) ? pack.replace(/\//g, '\\') : pack;
+
+// Pre-load framework helpers BEFORE utils/helper. utils/helper.js's init()
+// calls `require('framework/v*/lib/logger')`, which itself requires
+// `framework/v*/helpers` (lib/logger:64). When utils/helper is the outer
+// caller of lib/logger, lib/logger blocks at its helpers require and the
+// iteration's `_require` reloads path.js / task.js while lib/logger is still
+// mid-load — their module-local `var console = require('../lib/logger')`
+// then binds to a partial module.exports (= {}), so a later `console.debug`
+// in `task.js#run()` throws TypeError. Pre-loading helpers here makes
+// helpers/index.js the outer caller, so lib/logger completes inside
+// context.js's trigger and the subsequent `_require` reloads of path.js/
+// task.js see the full Logger singleton from cache.
+// Filesystem-driven version discovery so this stays correct across version
+// bumps that may temporarily skew package.json `version` and the framework
+// directory name (e.g. during a patch release window).
+try {
+    var _frameworkDir = fs.readdirSync(ginaPath + '/framework')
+        .filter(function(d) { return /^v/.test(d); })
+        .sort()
+        .pop();
+    if (_frameworkDir) {
+        require(ginaPath + '/framework/' + _frameworkDir + '/helpers');
+    }
+} catch (_e) {
+    // best-effort preload; the actual install steps will surface any real failure
+}
+
+var help        = require(ginaPath + '/utils/helper.js');
 var helpers = null;
 
 
@@ -135,7 +165,10 @@ function PostInstall() {
 
             if ( /^\-\-log-level\=/.test(args[i]) ) {
                 var logLevel = args[i].split(/\=/)[1];
-                console.setLevel(logLevel, 'gina');
+                // setLevel is a lib.logger method; Node's built-in console doesn't expose it.
+                if ( typeof(console.setLevel) === 'function' ) {
+                    console.setLevel(logLevel, 'gina');
+                }
                 process.env.LOG_LEVEL=logLevel;
             }
         }
@@ -168,7 +201,8 @@ function PostInstall() {
                     ]
                 };
                 console.warn('No `package.json` found for your project, creating one to avoid install exceptions');
-                lib.generator.createFileFromDataSync(defaultPackageJsonContent, projectPackageJsonObj.toString());
+                // Inlined to avoid loading the framework lib registry at install time.
+                fs.writeFileSync(projectPackageJsonObj.toString(), JSON.stringify(defaultPackageJsonContent, null, 4));
             }
         }
 
@@ -301,7 +335,7 @@ function PostInstall() {
                 try {
                     await promisify(funct)();
                 } catch (e) {
-                    console.error(e.toString());
+                    console.error(e && e.stack ? e.stack : e.toString());
                     process.exit(1);
                     return;
                 }

package/script/pre_install.js

@@ -14,11 +14,39 @@ var util        = require('util');
 var promisify   = util.promisify;
 var { execSync } = require('child_process');
 
-//var lib         = require('./lib');
-// var console     = lib.logger;
-var lib     = null;
+// Framework lib registry is intentionally not loaded here — see checkIfGinaIsAlreadyInstalled.
 var helpers = null;
 
+// Pre-load framework helpers BEFORE utils/helper. utils/helper.js's init()
+// calls `require('framework/v*/lib/logger')`, which itself requires
+// `framework/v*/helpers` (lib/logger:64). When utils/helper is the outer
+// caller of lib/logger, lib/logger blocks at its helpers require and the
+// iteration's `_require` reloads path.js / task.js while lib/logger is still
+// mid-load — their module-local `var console = require('../lib/logger')`
+// then binds to a partial module.exports (= {}). path.js guards
+// `console.debug`/`info` with `typeof`, but `console.warn` (line 220) and
+// `console.error` (lines 575/872/902) are unguarded — disk-error code paths
+// in cp/rm during checkIfGinaIsAlreadyInstalled's archive backup would crash.
+// Pre-loading helpers here makes helpers/index.js the outer caller, so
+// lib/logger completes inside context.js's trigger and the subsequent
+// `_require` reloads see the full Logger singleton from cache.
+// Filesystem-driven version discovery so this stays correct across version
+// bumps that may temporarily skew package.json `version` and the framework
+// directory name.
+try {
+    var _scriptPath = __dirname;
+    var _ginaPath = (_scriptPath.replace(/\\/g, '/')).replace('/script', '');
+    var _frameworkDir = fs.readdirSync(_ginaPath + '/framework')
+        .filter(function(d) { return /^v/.test(d); })
+        .sort()
+        .pop();
+    if (_frameworkDir) {
+        require(_ginaPath + '/framework/' + _frameworkDir + '/helpers');
+    }
+} catch (_e) {
+    // best-effort preload; the actual install steps will surface any real failure
+}
+
 /**
  * Pre install constructor
  *
@@ -426,9 +454,12 @@ function PreInstall() {
 
         var frameworkPath   = self.versionPath;
         try {
+            // utils/helper sets up the global `_()` path helper. We deliberately do NOT
+            // load the framework's full `lib` registry here — at preinstall time the
+            // framework's nested npm deps (psl, @rhinostone/swig) may not be resolvable
+            // yet, and `lib/domain` would crash on `require('psl')`. Node's built-in
+            // `console` is sufficient for the install scripts.
             helpers = require(self.gina+ '/utils/helper');
-            lib     = require('./lib');
-            console = lib.logger;
         } catch (err) {
             return done(err)
         }

package/framework/v0.3.7/VERSION

@@ -1 +0,0 @@
-0.3.7