gina 0.3.13-alpha.2 → 0.3.13

package/framework/v0.3.13/lib/secrets/src/main.js

@@ -0,0 +1,200 @@
+'use strict';
+/*
+ * This file is part of the gina package.
+ * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * @module lib/secrets
+ * @description Substitutes `${secret:KEY}` placeholders in a merged bundle
+ * config tree at config-load time. The default backend resolves keys from
+ * `process.env`; a future iteration may add pluggable backends.
+ *
+ * **Syntax.** `${secret:KEY}` where `KEY` matches `^[A-Z_][A-Z0-9_]*$`.
+ * The placeholder must be the entire JSON string value — mixed-content
+ * strings like `'prefix-${secret:K}-suffix'` are passed through unchanged
+ * (no substitution attempted).
+ *
+ * **Timing.** Runs once per bundle slice during `loadBundleConfig`,
+ * mutating the merged config object in place. Subsequent reads see the
+ * resolved values; no dynamic re-resolution.
+ *
+ * **Fail-closed.** Unset / empty backend values cause the backend to
+ * throw `Error('Secret resolution failed')`. The error message does NOT
+ * include the key name.
+ *
+ * **Path tracking.** The dotted paths that were substituted are recorded
+ * in an internal `WeakMap`; callers can retrieve them via
+ * `getResolvedPaths(config)` to support future log-redaction wrappers.
+ *
+ * @example
+ * var secrets = lib.secrets;
+ * process.env.DB_PASSWORD = 's3cret';
+ * var conf = { db: { password: '${secret:DB_PASSWORD}' }, db_host: 'localhost' };
+ * secrets.resolve(conf);
+ * conf.db.password;                  // → 's3cret'
+ * secrets.getResolvedPaths(conf);    // → ['db.password']
+ *
+ * @example
+ * // Fail-closed when env var is missing:
+ * delete process.env.MISSING;
+ * try {
+ *     secrets.resolve({ a: '${secret:MISSING}' });
+ * } catch (e) {
+ *     e.message;   // 'Secret resolution failed'
+ * }
+ */
+
+var defaultBackend = require('./backends/env');
+
+/**
+ * Regex matching an entire `${secret:KEY}` placeholder. The capture group
+ * is the key name. Anchored on both ends — embedded placeholders inside
+ * longer strings do not match.
+ *
+ * @constant {RegExp} SECRET_RE
+ * @memberof module:lib/secrets
+ */
+var SECRET_RE = /^\${secret:([A-Z_][A-Z0-9_]*)\}$/;
+
+/**
+ * Internal map of resolved-config object → array of dotted paths that
+ * were substituted during the walk. `WeakMap` so entries are GC'd with
+ * their config object.
+ *
+ * @inner
+ * @private
+ * @type {WeakMap<object, string[]>}
+ */
+var _resolvedPathsByConfig = new WeakMap();
+
+/**
+ * Walk `node` recursively, substituting any string value that matches
+ * `SECRET_RE` in place. Records substituted dotted paths into `paths`.
+ * Mixed-content strings pass through unchanged.
+ *
+ * @inner
+ * @private
+ * @param {*}        node        - Current subtree (object, array, or scalar)
+ * @param {string[]} paths       - Mutable array of substituted dotted paths
+ * @param {string}   currentPath - Dotted path of `node` from the walk root
+ * @param {object}   backend     - Backend with `resolve(key) → string`
+ * @returns {void}
+ * @throws {Error} Propagates backend resolution errors
+ */
+function walkAndResolve(node, paths, currentPath, backend) {
+    if (node === null || typeof node !== 'object') {
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (var i = 0; i < node.length; i++) {
+            var elementPath = currentPath + '[' + i + ']';
+            if (typeof node[i] === 'string') {
+                var match = node[i].match(SECRET_RE);
+                if (match) {
+                    node[i] = backend.resolve(match[1]);
+                    paths.push(elementPath);
+                }
+            } else if (node[i] !== null && typeof node[i] === 'object') {
+                walkAndResolve(node[i], paths, elementPath, backend);
+            }
+        }
+        return;
+    }
+    for (var key in node) {
+        if (!Object.prototype.hasOwnProperty.call(node, key)) {
+            continue;
+        }
+        var keyPath = currentPath ? (currentPath + '.' + key) : key;
+        if (typeof node[key] === 'string') {
+            var keyMatch = node[key].match(SECRET_RE);
+            if (keyMatch) {
+                node[key] = backend.resolve(keyMatch[1]);
+                paths.push(keyPath);
+            }
+        } else if (node[key] !== null && typeof node[key] === 'object') {
+            walkAndResolve(node[key], paths, keyPath, backend);
+        }
+    }
+}
+
+/**
+ * Resolve all `${secret:KEY}` placeholders in `config` in place. Returns
+ * the same `config` reference (for chaining).
+ *
+ * Walks every object key and array element; replaces any string value
+ * matching `^\${secret:KEY\}$` with the value returned by `backend.resolve(KEY)`.
+ * Substitution is one-pass — placeholders inside already-resolved values
+ * are NOT re-walked. Mixed-content strings (`'prefix-${secret:K}-suffix'`)
+ * return unchanged.
+ *
+ * @memberof module:lib/secrets
+ * @function resolve
+ * @param {object|Array} config    - The merged bundle config object to walk in place
+ * @param {object}       [backend] - Optional backend override. Defaults to the env-var backend.
+ * @param {function}     backend.resolve - `function(key) ⇒ string`. Throws on failure.
+ * @returns {object|Array|*} The same `config` reference (mutated in place). Non-object inputs return unchanged.
+ * @throws {Error} `'Secret resolution failed'` if any placeholder cannot be resolved
+ *
+ * @example
+ * var secrets = lib.secrets;
+ * process.env.API_KEY = 'abc';
+ * secrets.resolve({ api: { key: '${secret:API_KEY}' } });
+ * // → { api: { key: 'abc' } }
+ *
+ * @example
+ * // Custom backend (test fixture or future plug-in shape):
+ * secrets.resolve(conf, {
+ *     resolve: function(key) {
+ *         if (key === 'TEST') return 'value';
+ *         throw new Error('Secret resolution failed');
+ *     }
+ * });
+ */
+function resolve(config, backend) {
+    if (config === null || typeof config !== 'object') {
+        return config;
+    }
+    var paths = [];
+    walkAndResolve(config, paths, '', backend || defaultBackend);
+    if (paths.length > 0) {
+        _resolvedPathsByConfig.set(config, paths);
+    }
+    return config;
+}
+
+/**
+ * Return the dotted paths that were substituted in `config` during the
+ * most recent `resolve(config)` call. Used by future log-redaction
+ * wrappers to know which fields originated as secrets.
+ *
+ * Paths use dotted notation for object keys (`'db.password'`) and
+ * bracketed indices for array elements (`'items[0]'`).
+ *
+ * @memberof module:lib/secrets
+ * @function getResolvedPaths
+ * @param {object|Array} config - The resolved config object
+ * @returns {string[]} Array of substituted dotted paths. Empty if none.
+ *
+ * @example
+ * var conf = { db: { password: '${secret:DB_PASSWORD}' }, items: ['${secret:A}', 'literal'] };
+ * process.env.DB_PASSWORD = 'pw';
+ * process.env.A = 'va';
+ * secrets.resolve(conf);
+ * secrets.getResolvedPaths(conf); // → ['db.password', 'items[0]']
+ */
+function getResolvedPaths(config) {
+    if (config === null || typeof config !== 'object') {
+        return [];
+    }
+    return _resolvedPathsByConfig.get(config) || [];
+}
+
+module.exports = {
+    resolve: resolve,
+    getResolvedPaths: getResolvedPaths,
+    SECRET_RE: SECRET_RE
+};

package/framework/{v0.3.13-alpha.2 → v0.3.13}/package.json

@@ -1,8 +1,8 @@
 {
   "name": "gina-framework",
-  "version": "0.3.13-alpha.2",
+  "version": "0.3.13-alpha.4",
   "dependencies": {
-    "@rhinostone/swig": "^2.2.0",
+    "@rhinostone/swig": "^2.3.0",
     "intl-messageformat": "^11.2.4",
     "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.13-alpha.2/core/gna');
+var _gna = require('./framework/v0.3.13/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.3.13-alpha.2/core/controller');
-var EntitySuper     = require('./framework/v0.3.13-alpha.2/core/model/entity');
+var SuperController = require('./framework/v0.3.13/core/controller');
+var EntitySuper     = require('./framework/v0.3.13/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.3.13-alpha.2/lib/uuid');
+var uuid = require('./framework/v0.3.13/lib/uuid');
 
 module.exports = {
 

package/llms.txt

@@ -51,7 +51,7 @@ framework/v${version}/
 
 ### Swig — `@rhinostone/swig` (npm dependency)
 
-Maintained fork of the abandoned swig 1.4.2 template engine. Published to npm as `@rhinostone/swig@2.2.0` (npm org: `rhinostone`, maintainer: `beemaster`). Repo: `https://github.com/gina-io/swig`. Declared in `framework/v*/package.json` — installed via `npm install` inside the framework directory. Requires `npm install` after clone, merge, or worktree switch (the framework `node_modules/` is gitignored).
+Maintained fork of the abandoned swig 1.4.2 template engine. Published to npm as `@rhinostone/swig@2.3.0` (npm org: `rhinostone`, maintainer: `beemaster`). Repo: `https://github.com/gina-io/swig`. Declared in `framework/v*/package.json` — installed via `npm install` inside the framework directory. Requires `npm install` after clone, merge, or worktree switch (the framework `node_modules/` is gitignored).
 
 Previously vendored at `core/deps/swig-1.4.2/` — removed in the migration to the npm dep. CVE-2023-25345 parse-time blocklist (`__proto__`/`constructor`/`prototype`) is patched in the fork's `parser.js` and `tags/set.js`. The path traversal boundary check in `controller.render-swig.js` is Gina's own code and is unaffected by this migration.
 
@@ -826,3 +826,19 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 96. **Layout cache concurrent-render ENOENT race — atomic temp+rename closes the gap window between `rmSync` and the post-priming read.** `controller.render-swig.js` primes a per-template layout cache file at `<cachePath>/<bundle>/swig/<subFolder>/layout.html` from the `{% extends "..." %}` directive, then reads it back ~340 sync-code lines below to inline assets. In dev mode (`_cacheIsEnabled !== 'true'`) the priming block USED to delete-then-rewrite (`fs.rmSync(newLayoutFilename)` followed by `await fs.promises.writeFile(newLayoutFilename, buffer)`), which opened a gap window: a concurrent render of the same URL could `rmSync` the file AFTER the first render's `writeFile` completed but BEFORE its later `readFile` syscall opened the file, leaving the first render with `Error: ENOENT: no such file or directory, open '<cache>/<bundle>/swig/.../layout.html'`. Symptom shape: intermittent 500s on parallel POST/GET bursts to the same URL in dev mode (production unaffected — cached mode skips the rmSync entirely). **Fix** — collapse `rmSync + writeFile(target)` into `writeFile(temp) + rename(temp → target)` at BOTH cache-write sites (the priming block AT THE TOP and the post-asset-injection rewrite ~640 lines below). POSIX `rename(2)` is atomic on the same filesystem, so concurrent readers always observe either the prior content or the new content, never an absent file. Per-process unique temp names (`<target>.tmp.<pid>.<Date.now()>.<random>`) avoid TOCTOU on the temp itself. The CVE-2023-25345 `{% extends %}` path-traversal boundary check at the priming block is preserved verbatim. **Reproduction** — a tight in-process Promise.all(50) misses the race because all attempts march in lockstep through awaits; the natural staggering needed for the race to fire comes from the pre-block request-lifecycle awaits in a real HTTP server (routing/middleware/controller setup). A unit-level harness can amplify the race by adding `for (k=0; k<5; k++) await Promise.resolve()` BEFORE the racy block plus a ~10ms sync CPU sink between writeFile and readFile and 0-50ms setTimeout stagger across attempts — that recipe surfaced 205/1000 ENOENT failures pre-fix, 0/1000 post-fix. **Test surface** — `test/core/render-swig.test.js` § 11: four source pins (rmSync removed, writeFile+rename pair at both cache-write sites, temp name embeds pid/time/random) + CVE-2023-25345 preservation pin + a behavior test that exercises 200 concurrent atomic writes and asserts 0 ENOENT. Generalises to any "delete then rewrite a shared file under concurrent renders" pattern — atomic temp+rename is the canonical resolution wherever the read window can outlive the rewrite cycle. Established 2026-05-11.
 
+97. **`String.prototype.match` + `indexOf(match)` is unsafe positional anchoring when match strings can be substrings of each other** — short regex matches (e.g. a bare `//` separator) collide on `indexOf` with longer matches earlier in the haystack (a `//` inside a URL string on a prior line that already passed the guard). Manifested at `helpers/json/src/main.js:63-78` where the comment-stripping loop did `commentsWithSlashes = jsonStr.match(/\/\/(.*)?/g)` + per-match `jsonStr.indexOf(m)` + `charAt(pos-1)` URL-guard: the bare `//` separator's `indexOf` re-found the URL's `//`, the guard re-fired against the URL's `:`, and the real separator was never stripped — `JSON.parse` then threw `Expected double-quoted property name` on every bundle config combining a URL string with a bare `//` line. **Use `matchAll` (returns `match.index` per occurrence) when positional iteration is needed, or restructure to per-line scanning.** Related secondary trap: greedy regex-and-loop has implicit per-line scope (`(.*)?` consumed rest of line so only the FIRST `//` per line was guarded); naively replacing it with a non-greedy single-pass lookbehind `(?<![:"\\])\/\/[^\n]*/g` flattens this to per-position and would strip from mid-string `//`-bearing URLs like `"http://host//:rest"` — 8 fixtures under `lib/collection/test/data/` (Couchbase travel-sample data) carry exactly this pattern, caught by `test/lib/collection.test.js` § 05's `assert.deepStrictEqual(result, mocks)` where `mocks` is `requireJSON(...)`. **Final fix shape**: `split('\n')` + per-line leftmost `//` + `:` / `"` / `\` char-before guard — mirrors the original greedy heuristic without the substring-collision class of bug. Established 2026-05-13 (commit `2210ab17`); full incident narrative in the project's post-mortem store.
+
+98. **Secrets resolver — `${secret:KEY}` placeholder substitution in bundle JSON configs at config-load time** — `lib/secrets` walks the merged per-bundle config and substitutes `${secret:KEY}` placeholders from `process.env[KEY]` before `self.envConf[bundle][env]` is finalised in `core/config.js::loadBundleConfig`. Anchored regex `^\${secret:([A-Z_][A-Z0-9_]*)\}$` matches ONLY when the entire string value is the placeholder — mixed strings (`"prefix-${secret:K}-suffix"`) pass through unchanged (deliberate scope choice: removes the "is `{` substitution or literal?" ambiguity). Non-string scalars are walked but never mutated; nested objects and arrays descend recursively. **Fail-closed**: unset / empty env var throws `Error('Secret resolution failed')` (no key name in the message — the key is attached as a non-enumerable `_ginaSecretKey` property for debug-only logging; consumer surfaces never see the key name). Resolution happens once per config-load cycle (in-place mutation; second pass finds nothing). Cache invalidation: `config.refresh()` re-runs the resolver, but secret rotation needs a process restart (the supervisor inherits its env from container init, not from the running framework). **Pluggable backend interface** — `secrets.resolve(config, backend?)` accepts a `{resolve(key) → string|throw}` object; only the `process.env` backend ships in this iteration, but the API is stable for future plug-ins (Vault, SOPS, K8s Secrets). **Path tracking via `WeakMap`** — `secrets.getResolvedPaths(config)` returns the dotted paths (`'db.password'`, `'items[0]'`) the resolver substituted; storage is GC'd when the config is collected and never serialised. Groundwork for a future log-redaction wrapper at any merged-conf print site (`Inspector` payload, debug-export tools); no such print site exists in `core/config.js` today (existing `console.debug` calls interpolate scalar identifiers, not the merged object). **Consumers** — `gina.plugins.Csrf()` reads `settings.csrf.secret` (placeholder-resolved) with precedence `opts.secret` > `settings.csrf.secret` > `process.env.GINA_CSRF_SECRET` (back-compat); `gina bundle:mcp-start` re-runs the resolver on the parsed `mcp.json` immediately after `requireJSON()` so `server.authToken` etc. resolve before downstream readers; bundle scaffolding (`project:add` / `bundle:add`) recommends the placeholder shape in `core/template/conf/settings.json` and `core/template/boilerplate/bundle/index.js`. Established 2026-05-13 (#SECRETS1, commits `8aa2ec82` resolver + wiring, `c1b09ed5` syntax rename `{secret:KEY}` → `${secret:KEY}`, `7a8b0f36` csrf.secret slot, `7d513638` mcp.json route, `33f34b23` scaffolding).
+
+99. **Probe-first protocol for removing load-bearing fallback code** — when a defensive fallback (eval fallback, try/catch shim, recovery branch) has documented history of being load-bearing despite "looking like dead code", apply the structural fix at the cause-side FIRST, then instrument the fallback with a stderr probe BEFORE removing it, then run the full test suite to observe whether the probe fires. Only remove the fallback (and the probe) AFTER observing zero probe fires across all sites. This turns "I reasoned the structural fix breaks the trigger condition" into "the test suite empirically confirms the fallback never executes after the structural fix". **Worked example** — #M22 logger circular-require (2026-05-14). The 3 eval fallbacks at `lib/logger/src/main.js:69` + `containers/file/index.js:16` + `containers/mq/index.js:10` had bitten a prior session (#SCS1c, commit `ae932a5e`, 2026-04-23) — the evals were removed WITHOUT the structural fix and every logger-consuming test crashed with `TypeError: merge is not a function at init`. The 2026-05-14 protocol: (1) apply ONLY the structural fix in `lib/merge/src/main.js` (`require('../../../helpers')` → direct `require(__dirname + '/../../../../../utils/prototypes.json_clone')`, same `JSON.clone` population without going through the for-loop helper loader). (2) Add `process.stderr.write('[m22-probe] eval fallback fired at <file>:<line>\n')` at each fallback site, KEEPING the eval intact. (3) Run full local suite, capture stderr, `grep -c '\[m22-probe\]'`. **Zero fires** = empirical evidence the structural fix worked. (4) Only THEN remove the probes + evals. (5) Re-run suite to verify clean. ~10 minutes of work; the equivalent "reason about it and hope" approach was the failure mode of #SCS1c. **Detection signal that the protocol is warranted**: any session prompt or proposal phrased as "X is load-bearing because the prior attempt failed when X was removed". When you see that shape, surface the probe-first protocol BEFORE any code deletion. **Reflex check**: if your proposed protocol is "apply X subset first, then the rest" without a measurement justification for the subset choice, you're hedging, not measuring. The user's "is this your measured recommendation?" reflex catches this — answer is to surface positive evidence (probe never fires) rather than just smaller-blast-radius framing. Sister rule: the global "No fix without measurement" + the "Verification has THREE outcomes" expansion. Established 2026-05-14 (#M22, commit `2247e22e`).
+
+100. **`gh run list --commit <sha>` returns empty intermittently — branch-scoped query is more reliable when commit-filter doesn't match.** Observed 2026-05-14 during the #S9 ship CI verification: `gh run list --repo gina-io/gina --commit 64222df8 --limit 6` returned empty output even after all 4 workflows had completed green; `gh run list --repo gina-io/gina --branch develop --limit 10` showed them immediately for the same commit. Possible causes: gh CLI's commit-filter parsing edge case, GitHub Actions runs-API indexing delay between push and commit-SHA indexing, or commit-SHA being matched against a different ref. **Detection signal**: an `until` poll loop based on `gh run list --commit <sha> | grep -qE "completed[[:space:]]+(success|failure)"` will hang indefinitely because the empty input never matches the success regex — wasted background work. **Workaround**: poll `gh run list --branch <branch> --limit <N>` and either eyeball the commit-message line or grep the output for the SHA / commit-subject. Cheaper still: skip the poll entirely and accept that CI runs ~15-60s after push (per recent push timing observations on the gina repo); a single `gh run list --branch <branch>` after a reasonable interval is usually enough. Established 2026-05-14 during the #S9 plugin dormancy ship (commit `64222df8`, CI 4/4 green: Tests 32s · Security 17s · Vendored CVE Scan 15s · Bundle Freshness 50s).
+
+101. **Docs-site `.md` JSX-leak + `plugin-client-redirects` vs `onBrokenLinks` non-composition** — Docusaurus' `markdown.format: 'detect'` does NOT reliably promote a `.md` file to MDX from JSX usage alone, so manual `import` / `<JSX>` blocks in `.md` source leak as visible body text on the rendered page (e.g. `import DocMeta from '@site/src/components/DocMeta';` literally rendered as a `<p>` paragraph above body content). Convention: doc authors put metadata in frontmatter, the `readingTimePlugin` remark plugin auto-injects `<DocMeta>` into every `/docs/` page at build time; never write `import` / JSX in `.md` source (rename to `.mdx` if you need genuine JSX). Separately, `@docusaurus/plugin-client-redirects` does NOT satisfy `onBrokenLinks: 'throw'` at build time — redirect pages generate at build-OUTPUT stage, AFTER the broken-link checker runs against the source-derived doc tree, so internal links must use the canonical URL form (e.g. `/cli/cli-bundle` for CLI pages with `id: cli-<file>` frontmatter) not redirect aliases (`/cli/bundle`). Audit methodology lesson: body-link sweep extends prereq-frontmatter sweep — body links use the same anti-patterns and break the build identically. Detection greps: `grep -rln "^import " ~/Sites/gina/docs/repo/docs --include="*.md"` (JSX-in-md leaks) and `grep -rnE "\]\(/cli/(bundle|cache|connector|env|framework|port|project|protocol|scope|service|view)([#)/]|$)" ~/Sites/gina/docs/repo/docs/` (filename-form CLI body-link anti-pattern). Established 2026-05-14 (#D9 audit, commits `e3e21b6` secrets.md broken-link fix + `57a19d3` connector.md/service.md DocMeta cleanup).
+
+102. **PWA scaffold delivery path — `view:add`, not `bundle:add`, carries `bundle_public/` + `bundle_templates/`** — The #R6 PWA scaffold (`manifest.webmanifest` + `sw.js` under `core/template/boilerplate/bundle_public/`, plus the manifest `<link>` / `theme-color` `<meta>` / apple-touch-icon `<link>` / inline service-worker registration `<script>` injected into `bundle_templates/html/layouts/main.html`) reaches a scaffolded bundle ONLY through `gina view:add` — `bundle:add` copies just `boilerplate/bundle/` (config/controllers/index.js/locales: a JSON-API bundle with no HTML layout). `view:add`'s `copyFolder()` (`lib/cmd/view/add.js:297-314`) copies `bundle_public/` → `<bundle>/public/` AND `bundle_templates/` → `<bundle>/templates/` together in one command, so the PWA files and the modified layout always land as a set or not at all. `view:add` is the documented standard step for HTML bundles (getting-started "Add a bundle and go live" → "Add HTML views"), not a corner case. Files under `bundle_public/` are NOT token-substituted — only `add.js` does `${bundle}` substitution, and only on `.js`/`.json` under `boilerplate/bundle/` — so they land byte-identical. **`getAssets()` (`core/server.js`) handling for the injected layout tags**: `<link rel="manifest">` catalogs cleanly as `type='manifest', as=null` with the already-registered `application/manifest+json` MIME (no TypeError, no console noise); `<link rel="apple-touch-icon">` is skipped via the `/icon/` `continue` branch (a missing `apple-touch-icon.png` produces no 404 noise); the inline SW-registration `<script>` is skipped via the no-`src` `continue`. Trace any new `<link>` / `<script>` added to the default layout through `getAssets()` the same way before shipping it. Decisions: `favicon.ico` is the baseline manifest icon — no fake PNG binaries ship; the dev drops in `icon-192/512.png` + `apple-touch-icon.png` per `bundle_public/readme.md`. Filename is `manifest.webmanifest`, not `manifest.json`. Established 2026-05-14 (#R6).
+
+103. **A `gina start` framework server left running during a session can hang the full test suite AND bundle boot — shared root is `~/.gina/procs.json` staleness forcing the server onto a non-canonical port.** Two symptoms observed 2026-05-14 (0.3.13 #R6/#H9 session): (1) the full `node --test` suite hung ~40 minutes on `test/core/entity-arguments.test.js` — that test connects to the MQSpeaker on `:8125`, and a *degraded* framework server (alive but not on the canonical `:8124`) leaves the connect pending forever because the host's node flags carry `--test-timeout=0` (no per-test timeout → infinite hang, the run never completes, no green/red verdict). Killing the framework server makes the same test pass in ~67ms — a fast `ECONNREFUSED` on `:8125` instead of a hang, the test logs a warn and proceeds. (2) `gina bundle:start` AND `bin/gina-container` both hang during bundle boot right after the MQSpeaker connect, before binding the HTTP port. **Root cause for both:** `~/.gina/procs.json` accumulates stale entries from long-dead gina versions (pids that no longer exist still claiming `:8124`); `gina start` for the current version then binds a *different* port (observed `:3199`), and anything expecting the framework server at the canonical `:8124` hangs or misbehaves. **Practical rules:** before running the full local suite, ensure no `gina start` server is alive (`lsof -nP -iTCP:8124 -sTCP:LISTEN`) and add `--test-timeout=120000` to the `node --test` invocation as a safety net so a single hung test fails fast instead of stalling the whole run (healthy full-suite runtime is ~6s). If bundles will not boot on a dev host, suspect stale `procs.json` first — and before assuming a code change is at fault, run a zero-content subtract test: scaffold a bundle with `bundle:add` only (no `view:add`) and confirm it hangs identically. Established 2026-05-14 during the gina 0.3.13 #R6/#H9 value-add session.
+
+104. **`require.cache[path]` must hold a `Module` instance — `require.cache[path] = require(path)` poisons the slot.** Node reads `.exports` off each `require.cache` entry on every subsequent `require()`; assigning the bare exports object into the slot (no `.exports` key) makes the next plain `require()` return `undefined`, surfacing downstream as `Cannot read properties of undefined (reading '<X>')`. Correct hot-reload shapes: `delete require.cache[require.resolve(path)]` then use the `require()` return value directly, **or** `require.cache[c].exports = require(path)` (keeps the `Module`, swaps only `.exports`) — never `require.cache[path] = require(path)`. Fixed in `refreshCore()` (`core/server.isaac.js`, `add6655e`); the 13 `|| require.cache[require.resolve(...)]` workaround sites across the controller layer + connectors are now redundant dead code. Identical antipattern still latent in `router.js` (the `controller/index.js` slot — `router.js` is its only consumer and reads it back self-consistently), tracked as #B18. Established 2026-05-14.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.3.13-alpha.2",
+  "version": "0.3.13",
   "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.13-alpha.2/core/gna",
+  "main": "./framework/v0.3.13/core/gna",
   "types": "./types/index.d.ts",
   "typesVersions": {
     "*": {
@@ -78,7 +78,7 @@
   "license": "MIT",
   "readmeFilename": "README.md",
   "dependencies": {
-    "@rhinostone/swig": "^1.6.0",
+    "@rhinostone/swig": "^2.3.0",
     "engine.io": "^6.0.0",
     "psl": "^1.15.0"
   },

package/framework/v0.3.13-alpha.2/VERSION

@@ -1 +0,0 @@
-0.3.13-alpha.2

package/framework/v0.3.13-alpha.2/core/plugins/lib/file/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "gina-core-plugin-file",
-  "version": "1.0.0",
-  "description": "File manager plugin",
-  "authors": [
-    {
-      "name": "Maritn-Luther ETOUMAN",
-      "email": "contact@gina.io"
-    },
-    {
-      "name": "Fabrice DELANEAU",
-      "email": "contact@gina.io"
-    }
-  ],
-  "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
-  "engines": {
-    "node": ">=0.10.22"
-  },
-  "main": "src/main",
-  "scripts": {
-    "test": "nodeunit test"
-  },
-  "license": "MIT",
-  "readmeFilename": "README.md"
-}

package/framework/v0.3.13-alpha.2/core/plugins/lib/intl/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "gina-core-plugin-intl",
-  "version": "1.0.0",
-  "description": "International Language & Country Codes plugin based on ISO 3166",
-  "authors": [
-    {
-      "name": "Maritn-Luther ETOUMAN",
-      "email": "contact@gina.io"
-    },
-    {
-      "name": "Fabrice DELANEAU",
-      "email": "contact@gina.io"
-    }
-  ],
-  "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
-  "engines": {
-    "node": ">=0.10.22"
-  },
-  "main": "src/main",
-  "scripts": {
-    "test": "nodeunit test"
-  },
-  "license": "MIT",
-  "readmeFilename": "README.md"
-}

package/framework/v0.3.13-alpha.2/core/plugins/lib/intl/src/main.js

@@ -1,35 +0,0 @@
-
-function IntlPlugin() {
-
-    var merge       = merge || require('lib/merge');
-    var Collection  = Collection || require('lib/collection');
-
-    var self = {
-        options : {
-            isCaseSensitive: true,
-            locale: 'en' // by default
-        }
-    };
-
-    // load phrases
-    var phrases = {
-        'amendment' : {
-            _data : null,
-            en : 'amendment',
-            fr : 'avenant'
-        }
-    };
-
-};
-
-if ( ( typeof(module) !== 'undefined' ) && module.exports ) {
-    // Publish as node.js module
-    var merge       = require('lib/merge');
-    var Collection  = require('lib/collection');
-
-    module.exports  = IntlPlugin
-
-} else if ( typeof(define) === 'function' && define.amd) {
-    // Publish as AMD module
-    define('gina/intl', function(){ return IntlPlugin })
-}

package/framework/v0.3.13-alpha.2/core/template/boilerplate/bundle_public/readme.md

@@ -1 +0,0 @@
-`public` is the public directory.