gina 0.3.13 → 0.3.14

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

@@ -638,31 +638,46 @@ function CmdHelper(cmd, client, debug) {
             }
 
             if ( ! new _(cmd.projectManifestPath).existsSync() ) {
-                if ( !/^project\:(add|import)/.test(cmd.task) ) {
-                    console.warn('Project manifest.json not found. Trying to fix it ...');
-                    // return process.exit(1);
-                }
+                // #B16 — project:remove --force tolerates a missing manifest:
+                // registry-only removal (`~/.gina/projects.json` + state-store)
+                // is sufficient to unregister a partially-broken project. The
+                // recreate-from-template branch may itself fail when the
+                // project directory is gone, and the downstream read would
+                // error out. Stub `cmd.projectData` to a minimal shape and
+                // skip both recreate and read. The rest of `loadAssets`
+                // (homedir / bundles / releases / ports) reads `projectData`
+                // only via guarded `typeof != 'undefined'` checks, so a stub
+                // satisfies every downstream consumer for the removal path.
+                if ( /\:remove$/.test(cmd.task) && cmd.params['force'] ) {
+                    console.warn('Project manifest.json not found at '+ cmd.projectManifestPath +' — proceeding with registry-only removal (--force).');
+                    cmd.projectData = { project: cmd.projectName, version: '0.0.0', bundles: {} };
+                } else {
+                    if ( !/^project\:(add|import)/.test(cmd.task) ) {
+                        console.warn('Project manifest.json not found. Trying to fix it ...');
+                        // return process.exit(1);
+                    }
 
-                // Creating default manifest
-                var conf        = _(getPath('gina').core +'/template/conf/manifest.json', true);
-                var contentFile = require(conf);
-                var dic = {
-                    "project"   : cmd.projectName,
-                    "version"   : "1.0.0",
-                    "scope"     : cmd.mainConfig['def_scope'][ GINA_SHORT_VERSION ],
-                    "rootDomain": os.hostname()
-                };
+                    // Creating default manifest
+                    var conf        = _(getPath('gina').core +'/template/conf/manifest.json', true);
+                    var contentFile = require(conf);
+                    var dic = {
+                        "project"   : cmd.projectName,
+                        "version"   : "1.0.0",
+                        "scope"     : cmd.mainConfig['def_scope'][ GINA_SHORT_VERSION ],
+                        "rootDomain": os.hostname()
+                    };
 
-                contentFile = whisper(dic, contentFile); //data
-                lib.generator.createFileFromDataSync(
-                    contentFile,
-                    _(cmd.projectManifestPath, true)
-                )
+                    contentFile = whisper(dic, contentFile); //data
+                    lib.generator.createFileFromDataSync(
+                        contentFile,
+                        _(cmd.projectManifestPath, true)
+                    );
+                    cmd.projectData = requireJSON(cmd.projectManifestPath);
+                }
+            } else {
+                cmd.projectData = requireJSON(cmd.projectManifestPath);
             }
 
-
-            cmd.projectData         = requireJSON(cmd.projectManifestPath);
-
             cmd.projectHomedir      = (
                                         typeof(cmd.projects[cmd.projectName].homedir) != 'undefined'
                                         && cmd.projects[cmd.projectName].homedir != ''

package/framework/{v0.3.13 → v0.3.14}/lib/cmd/project/remove.js

@@ -50,7 +50,18 @@ function Remove(opt, cmd) {
             , force     = ( typeof(self.params['force']) != 'undefined' ) ? self.params['force'] : false;
 
 
+        // #B16 — --force tolerates a missing project directory. The whole
+        // point of --force on a rm command is to honour partial breakage
+        // (dir deleted by hand, failed scaffold, etc.). Without --force,
+        // a missing dir is still a hard error so the user notices the
+        // typo / wrong-machine case.
         if ( !folder.existsSync() ) {
+            if ( force ) {
+                console.warn('project [ '+ self.projectName +' ] not found at '+ folder.toString() +' — proceeding with registry-only removal (--force).');
+                // Skip the prompt and folder rmSync; jump straight to
+                // ports cleanup + projects.json delete via end().
+                return end(true);
+            }
             console.error('project [ '+ self.projectName+' ] was not found at this location: ' + folder.toString() );
             process.exit(1)
         }

package/framework/{v0.3.13 → v0.3.14}/package.json

@@ -1,8 +1,8 @@
 {
   "name": "gina-framework",
-  "version": "0.3.13-alpha.4",
+  "version": "0.3.14-alpha.2",
   "dependencies": {
-    "@rhinostone/swig": "^2.3.0",
+    "@rhinostone/swig": "^2.4.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/core/gna');
+var _gna = require('./framework/v0.3.14/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.3.13/core/controller');
-var EntitySuper     = require('./framework/v0.3.13/core/model/entity');
+var SuperController = require('./framework/v0.3.14/core/controller');
+var EntitySuper     = require('./framework/v0.3.14/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.3.13/lib/uuid');
+var uuid = require('./framework/v0.3.14/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.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).
+Maintained fork of the abandoned swig 1.4.2 template engine. Published to npm as `@rhinostone/swig@2.4.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.
 
@@ -283,7 +283,7 @@ Declare any LLM provider in `connectors.json` via `"connector": "ai"`. Named pro
 
 ```json
 {
-  "claude":   { "connector": "ai", "protocol": "anthropic://", "apiKey": "${ANTHROPIC_API_KEY}", "model": "claude-opus-4-6" },
+  "claude":   { "connector": "ai", "protocol": "anthropic://", "apiKey": "${ANTHROPIC_API_KEY}", "model": "claude-opus-4-7" },
   "deepseek": { "connector": "ai", "protocol": "deepseek://",  "apiKey": "${DEEPSEEK_API_KEY}",  "model": "deepseek-chat" },
   "local":    { "connector": "ai", "protocol": "ollama://",    "model": "mimo" }
 }
@@ -757,9 +757,9 @@ Dev-mode query instrumentation captures every database query tied to the current
 28. **Connector code is NOT hot-reloaded** — `core/connectors/*/index.js` modules are loaded once at bundle startup via entity registration, not via `lib/index.js`. `refreshCore()` does not evict them. Any change (new QI fields, `extractIndexes()`, `profile: "timings"`) requires `gina bundle:stop` + `gina bundle:start` or `docker restart <container>`.
 29. **Couchbase SDK v4 `meta.profile` is always undefined** — the C++ binding (`couchbase-cxx-client`) does not forward the `profile` field from the N1QL server response. `meta.profile` is `undefined` even with `profile: 'timings'` in the request. The EXPLAIN fallback (`explainForIndexes()`) runs `EXPLAIN <statement>` asynchronously and caches results per unique statement. First request for a new statement may show N/A; subsequent requests hit the cache. `USE KEYS` queries use `ExpressionScan`/`KeyScan` operators (no `index` field) — detected separately by `extractIndexes()`.
 30. **Test lookback constants are fragile** — `inspector.test.js` section 08 scans backward from `_devLog.push(_queryEntry)` by byte distance looking for `envIsDev`. Adding helper functions or fields between the guard and the push increases the distance. Current constant: 1800 chars. Always check after adding code near the connector QI guard.
-28. **`req.routing.param.<key>` ≠ URL value — use `req.params.<key>`** — `req.routing.param` holds the raw routing config object from `routing.json`. For URL parameter bindings like `"id": ":id"`, the value stored there is the literal placeholder string `":id"`, not the actual URL segment. The actual captured value is in `req.params.id` (always available) and `req.get.id` / `req.delete.id` etc. (method-specific). Static values declared in `param` (e.g. `"code": 302`) ARE correctly available on `req.routing.param.code`. Rule of thumb: use `req.routing.param` only for static metadata, never for captured URL params.
-29. **`fitsWithRequirements` requires `"slug": ":slug"` in `param` even when `requirements` is set** — the router only increments the route-match score (and populates `req.params`) for a URL parameter if that parameter key exists in the `param` block (e.g. `"slug": ":slug"`). Having `requirements: { "slug": "..." }` alone is not enough — the route will 404 without the binding. The `requirements` block adds regex validation on top of the binding; it does not imply the binding.
-30. **Controller files must NOT contain `require` or `inherits`** — the router (`router.js:557-560`) calls `inherits(Controller, SuperController)` automatically before every dispatch. Writing `var SuperController = require('../../../core/controller/controller')` or `Controller = inherits(Controller, SuperController)` inside a controller file is wrong and will break on path changes. The correct pattern is a plain constructor function with `this.action = function(req, res) {}` closure-style methods — matching the boilerplate in `core/template/boilerplate/bundle/controllers/controller.content.js`. Never use `Controller.prototype.method` either; actions are defined as properties on `this` inside the constructor.
+105. **`req.routing.param.<key>` ≠ URL value — use `req.params.<key>`** — `req.routing.param` holds the raw routing config object from `routing.json`. For URL parameter bindings like `"id": ":id"`, the value stored there is the literal placeholder string `":id"`, not the actual URL segment. The actual captured value is in `req.params.id` (always available) and `req.get.id` / `req.delete.id` etc. (method-specific). Static values declared in `param` (e.g. `"code": 302`) ARE correctly available on `req.routing.param.code`. Rule of thumb: use `req.routing.param` only for static metadata, never for captured URL params.
+106. **`fitsWithRequirements` requires `"slug": ":slug"` in `param` even when `requirements` is set** — the router only increments the route-match score (and populates `req.params`) for a URL parameter if that parameter key exists in the `param` block (e.g. `"slug": ":slug"`). Having `requirements: { "slug": "..." }` alone is not enough — the route will 404 without the binding. The `requirements` block adds regex validation on top of the binding; it does not imply the binding.
+107. **Controller files must NOT contain `require` or `inherits`** — the router (`router.js:557-560`) calls `inherits(Controller, SuperController)` automatically before every dispatch. Writing `var SuperController = require('../../../core/controller/controller')` or `Controller = inherits(Controller, SuperController)` inside a controller file is wrong and will break on path changes. The correct pattern is a plain constructor function with `this.action = function(req, res) {}` closure-style methods — matching the boilerplate in `core/template/boilerplate/bundle/controllers/controller.content.js`. Never use `Controller.prototype.method` either; actions are defined as properties on `this` inside the constructor.
 31. **Inspector (formerly Beemaster) is a built-in dev inspector, not a service or separate bundle** — served at `/_gina/inspector/` by `server.js` `onRequest()` in dev mode (engine-agnostic — works with both Isaac and Express). Runs inside the bundle's own process — no project registration, no separate port, no auto-start spawn. The SPA files live in `core/asset/plugin/dist/vendor/gina/inspector/` (framework tree). Same origin as the monitored bundle — `window.opener.__ginaData` always works. Only served when `isDev` is true; production bundles never expose the Inspector.
 32. **`/_gina/*` are built-in endpoints, not services** — all `/_gina/*` handlers (healthcheck, assets, cache/stats, info, inspector, logs) run inside the bundle's own HTTP server process. No separate process or port. Isaac is the source of truth, but every handler must also work with Express. New `/_gina/*` endpoints go in `server.js` `onRequest()`. Isaac-specific fast-paths (e.g. `readSync`, `server._cached`) can stay in `server.isaac.js` but the base functionality must exist in `server.js`. Existing Isaac-only handlers (healthcheck, assets/routing.json, cache/stats, info) are a known gap being ported incrementally.
 33. **`query()` callback — `false` is the success sentinel** — `self.query()` calls `callback(false, data)` on success, not `callback(null, data)`. Use `if (err)` as the error guard — it works because `false` is falsy. Never check `err === null` (always false on success). Never use `err = merge(err, {...})` on a real Error object — `merge()` destroys `message` and `stack`. Assign extra properties directly: `err.session = userSession`.
@@ -772,7 +772,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 40. **`queryParams` vs `queryOptions` at `conn._cluster.query()`** — the Couchbase connector's `conn._cluster.query()` must receive the full `queryOptions` object (which includes `parameters: queryParams`, `profile`, `scanConsistency`, `adhoc`), NOT the raw `queryParams` array. Passing `queryParams` silently drops all non-parameter options because the SDK only reads named properties from the options object. This bug existed at lines 892 and 934 for years, invisibly disabling `profile: 'timings'`, `scanConsistency`, and `adhoc: false` on every SDK v3+ query.
 41. **Option B is the active dispatch path in the Couchbase connector** — `register()` in `readSource()` has two paths: Option A (`self._isRegisteredFromProto === true`) and Option B (`!self._isRegisteredFromProto`). Option B is always active for all connector-generated entity methods. When adding debug logging or QI instrumentation to the query execution path, place it in Option B — Option A is dead code.
 42. **Validator touched-field-only error display** — the validator runs a global validation pass on every field blur to determine submit button state (`isFormValid`). The global pass must NOT display errors for untouched fields — only for `event.target.name` (the field the user actually touched). Two call sites in `validator/src/main.js`: ~line 3337 (within the `isFormValid && gResult.error` block) and ~line 4865 (same pattern in the second validation path). The global pass still correctly disables/enables the submit button.
-42. **Docker `node_modules` isolation** — Docker containers using `node_modules` anonymous volumes have their own copy of all npm packages. Edits to `node_modules/` on the host are invisible inside the container. To debug SDK-level behaviour, either `docker exec` and edit inside the container, or add logging to the framework connector code (which IS bind-mounted) rather than the SDK itself.
+108. **Docker `node_modules` isolation** — Docker containers using `node_modules` anonymous volumes have their own copy of all npm packages. Edits to `node_modules/` on the host are invisible inside the container. To debug SDK-level behaviour, either `docker exec` and edit inside the container, or add logging to the framework connector code (which IS bind-mounted) rather than the SDK itself.
 43. **Release pipeline (`script/post_publish.js` chain) — failure modes & gotchas** — covers `self.*` chain ordering (gates prepend; non-fatal wrap for polish steps), syncDocs alpha-misclass + nested-lifecycle red herring (`publishAlpha`'s `npm publish --tag alpha` triggers a NESTED full lifecycle that legitimately logs `[syncDocs] Alpha release — skipping docs sync`), docs-repo lockfile-mismatch race after stable publish (RESOLVED 2026-05-05 via `script/retry_lockfile_sync.js` `retryWithBackoff` — ~80s ceiling, schedule `[5,15,30,30]`s), README freshness code-gate (touch-since-tag check, established 2026-05-05 after three skipped manual-checklist steps in a row), `bumpVersion` `git mv framework/v<old>/ v<new>/` requires state-store pre-sync across `~/.gina/main.json` + `~/.gina/<short>/settings.json` + `gina.db kv_store` (canonical since #CN2v3), `framework/v*/package.json` gitignored-but-CI-needed (heredoc-derive in `.github/workflows/test.yml`; `bumpVersion` writes the local copy after the dir rename, commit `6c287c62`), lockfile-regen primitive `npm install --package-lock-only --ignore-scripts`, single try/catch around sequential git silently skips downstream work, early-return footgun on multi-side-effect functions (commit `c0a20c0c`), todo/spec text drifts from code so verify before implementing, release-session tooling traps (`git filter-repo --replace-text` rewrites blob content only — pair with `--replace-message` for commit-message leaks; GitHub branch protection `allow_force_pushes: false` blocks ALL force-pushes including admin and the per-subfield REST endpoint returns 404, full-payload PUT required, web UI toggle has been observed to silently no-op).
 45. **README.md is NOT auto-updated by any release script** — the "What's in X.Y.Z" heading and Features-table Swig version reference are hand-maintained. Before every `npm publish`: run `grep -nE "What's in|Swig [0-9]" README.md` to catch stale sections. Stable checklist step 5 covers this for `package.json`/`llms.txt`/etc. but does not enforce README explicitly. Add to pre-flight mental model: README needs manual bump.
 46. **Docs-repo WIP during release merge: stash, don't file-overwrite** — when merging `develop → main` in `~/Sites/gina/docs/repo` to recover from a `syncDocs` miss, the file-overwrite dance (cp to /tmp, git-show HEAD, edit, restore) only scales to 1–2 files. With significant in-flight work (e.g. Swig migration at 40+ files), use `git stash push -u -m "<purpose>"` → `git checkout main` → `git merge --ff-only develop` → `git push origin main` → `git checkout develop` → `git stash pop`. The `-u` is required for untracked files (e.g. new `.mdx` files).
@@ -815,9 +815,9 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 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). **Constraint to know before extending the sidecar**: the regex requires a literal `v` prefix on the version. Bare version mentions — `0.3.7`, `## What's in 0.3.7`, third-party version strings like `@rhinostone/swig 1.5.0` — are invisible to the mechanism and will not be auto-rewritten. Adding such a file to the sidecar no-ops on those refs; they need a separate maintenance approach. Auto-rewriting bare version mentions would also be strictly worse than no-op — silently relabelling old content as new masks the staleness — so a freshness gate that asserts the file was touched at all in the release window (see `script/check_readme_freshness.js` + the `self.checkReadmeFreshness` step in `prepare_version.js`, established 2026-05-05) is the right primary mechanism for this class of drift. **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.
 
-90. **Socket's "Obfuscated code" alert on `gina.min.js` is a verified false positive (Mozilla Public Suffix List data table from `psl@^1.15.0`, byte-identical-data-shape to the standalone `psl@1.15.0` package which Socket scores 100/100) — dismiss per-version on Socket UI with the standing justification text in the local-tool playbook's Socket section. DO NOT attempt the build-pipeline lazy-load (r.js `exclude` of `vendor/gina/psl` + standalone PSL chunk + runtime AMD path config in `core.js`) — it breaks the consumer sync-require contract: gina-consuming bundles routinely call `require('gina/link')` synchronously inside their `onGinaReady` callback, and that contract cannot be satisfied once `lib/domain → vendor/gina/psl` becomes an async XHR (`lib/domain` never resolves → `gina/link` never resolves → consumer hits `Module name "gina/link" has not been loaded yet for context: _`). Verified failure during browser smoke against a representative consumer bundle on 2026-05-05.** A source-level lazy-load (modify `lib/domain/src/main.js` to drop `vendor/gina/psl` as an AMD dep and defer `require(['vendor/gina/psl'])` into the `Domain(cb)` constructor's already-async callback path) would work but the engineering cost (4-8 hrs + cross-route smoke across each of the consumer's nginx static docroots + ongoing standalone-chunk deploy sync) doesn't pay back the per-version dismiss friction (~5-25 min/year). The standing decision is to dismiss per-version. The post-publish dismissal step is wired into both Alpha and Stable Release Checklists in the local-tool playbook.
-
 89. **Lead-side hedging via "open follow-up questions" in design recommendations is a distinct failure mode of the measure-first / no-static-analogy rule — even AFTER doing the measurement, the output shape can still punt the synthesis the recommender owes.** Pattern: investigation done (gap analysis, regex inspection, git-log windows, code-path verification), recommendation written, but it ends with "(i) do you want strict X or relaxed Y? (ii) for the secondary check, signal A or signal B?" — two-options framing that looks measured but is actually pushing the synthesis back to the user. **Detection**: open follow-up questions of the form "X vs Y — which do you want?" at the end of a recommendation are almost always hedging. The recommender has the data; if the data does not discriminate, the answer is "not enough data, would need observation Z to resolve" — not "you pick". **The fix shape**: pick the loosest-but-sufficient assertion the data supports, name explicitly what would change your mind (a falsifying observation, a constraint shift), and commit. If a tradeoff genuinely needs user input (a policy choice between strict-and-friction vs lenient-and-flexible), frame it as "I recommend X for these reasons; the only reason to pick Y is if [explicit constraint] applies — does it?" — that is still committed reasoning, with the user's input narrowed to the one variable that actually moves the answer. **Generalises to any agent or lead recommendation in any project.** This trap operates one layer up from the lead-side static-analogy reasoning rule (already documented as a session rule): static-analogy is "I skipped measurement and reasoned by analogy"; this is "I did measure, but my output shape still hedges". The user's reflex "what's your measured take?" catches both. Rule of thumb: a measured recommendation that ends with two open questions about which design knob to turn has not finished the work. Precedent: 2026-05-05 README freshness gate session — first recommendation flagged for static-analogy reasoning (proposed extending the existing `.local-sync-targets.json` mechanism to README.md, by analogy from the local-doc auto-bump pattern, without measuring whether the regex actually applied to README's bare-version mentions). After the user's "is this measured?" prompt, the second recommendation did the measurement (read README.md, ran git log against the tag pairs, inspected the regex, reviewed the existing checklist) but ended with "(i) strict heading-match vs lag-one-minor — which? (ii) compare swig against npm-resolved or against framework dep — which?". The user's "what's your measured take?" prompted a corrected version that dropped both questions: primary gate is touch-since-tag (catches every form of forgetfulness), secondary heading/swig assertions skipped as redundant. Both layers of the same trap surfaced in one session — useful worked example for the next one.
+
+90. **Socket's "Obfuscated code" alert on `gina.min.js` is a verified false positive (Mozilla Public Suffix List data table from `psl@^1.15.0`, byte-identical-data-shape to the standalone `psl@1.15.0` package which Socket scores 100/100) — dismiss per-version on Socket UI with the standing justification text in the local-tool playbook's Socket section. DO NOT attempt the build-pipeline lazy-load (r.js `exclude` of `vendor/gina/psl` + standalone PSL chunk + runtime AMD path config in `core.js`) — it breaks the consumer sync-require contract: gina-consuming bundles routinely call `require('gina/link')` synchronously inside their `onGinaReady` callback, and that contract cannot be satisfied once `lib/domain → vendor/gina/psl` becomes an async XHR (`lib/domain` never resolves → `gina/link` never resolves → consumer hits `Module name "gina/link" has not been loaded yet for context: _`). Verified failure during browser smoke against a representative consumer bundle on 2026-05-05.** A source-level lazy-load (modify `lib/domain/src/main.js` to drop `vendor/gina/psl` as an AMD dep and defer `require(['vendor/gina/psl'])` into the `Domain(cb)` constructor's already-async callback path) would work but the engineering cost (4-8 hrs + cross-route smoke across each of the consumer's nginx static docroots + ongoing standalone-chunk deploy sync) doesn't pay back the per-version dismiss friction (~5-25 min/year). The standing decision is to dismiss per-version. The post-publish dismissal step is wired into both Alpha and Stable Release Checklists in the local-tool playbook.
 93. **Reverse-proxy path-prefix awareness via `X-Forwarded-Prefix` — the bundle's internal `server.webroot` stays `/`, but the value templated into `gina.config.webroot` carries the proxy's mount path so client-side root-relative URLs (`/_gina/assets/routing.json`, the `gina.min.css` link injection, etc.) target the correct upstream through the proxy instead of routing to whichever bundle answered bare `/`.** Standard header used by Spring Boot, Traefik, FastAPI, ASP.NET Core, NestJS, Quarkus. Capture site: `core/server.isaac.js` proxy-detection block (sibling to the `X-Forwarded-Host` / `X-Forwarded-Proto` reads); normalisation rules — leading slash added if missing, trailing slashes stripped, empty / `"/"` dropped; stored on `process.gina.PROXY_PREFIX`. Composition site: `core/controller/controller.js` at the `set('page.environment.webroot', ...)` call (~line 513) — when `PROXY_PREFIX` is set, public webroot becomes `prefix + bundle.server.webroot` (slash-normalised), then templated into `gina.onload.min.js`. Internal disk-path resolution and asset-rewrite call sites (e.g. `controller.js:927,956`) still use the bundle's native `server.webroot` — only the browser-facing `gina.config.webroot` carries the prefix; the proxy strips the prefix when forwarding upstream so the bundle's static handlers receive native paths. Symptom shape that surfaces this gap: browser fetches `/_gina/*` URLs that nginx routes to the wrong upstream (the bundle that owns bare `/`, not the bundle that rendered the page); inspector indicator names one bundle but `routing.json` contents come from another. Server-side asset URL rewriting at `controller.js:927,956` and the `linkTo` family also write URLs intended for browser consumption — same prefix-awareness gap, deferred follow-up. The bare `/_gina/assets/routing.json` handler exists only in `server.isaac.js` with no engine-agnostic equivalent in `server.js`; bundles using the Express engine don't have this endpoint at all — independent of this slice but worth noting on the next `/_gina/*` parity sweep. Established 2026-05-06 after the symptom surfaced from a multi-bundle nginx deployment where a sub-path bundle's pages were fetching the root bundle's `routing.json`.
 
 94. **ScyllaDB / Cassandra connector — `cassandra-driver` wrapper + fictitious `@scylladb/scylla-driver` registry placeholder + CQL ergonomics + `USING TTL` session store** — The Node.js ecosystem has no first-party shard-aware ScyllaDB driver (Python / Java / Go / Rust drivers are first-party shard-aware; Node.js is not), so the framework `scylladb` connector wraps `cassandra-driver` (Apache Software Foundation, `>=4.0.0` requires Node >=20, eval-safe per #SCS1 posture). Pre-#CN5 `lib/connector-registry/src/main.js` pinned `@scylladb/scylla-driver@>=1.0.0` as a placeholder — that npm package does not exist (404), which would have failed at install time the moment `connector:add primary --connector=scylladb --driver-version=...` printed its install hint. **Always `npm view <pkg>` to confirm the package exists** when populating registry-style mappings — same shape as the #I18N2 `intl-messageformat@9.13.0` non-existent-version trap. **CQL ORM** mirrors the SQL connector shape: entity files at `models/<keyspace>/cql/<Entity>/*.sql` (distinct dir like Couchbase's `n1ql/`, uniform `.sql` extension), `?` positional placeholders, `client.execute(query, args, { prepare: true })` returning Promise + `.onComplete()` shim, `@param` casting for CQL types (text/int/bigint/uuid/timeuuid/timestamp/boolean/blob/list/set/map/decimal/double/inet), `@return` coercion handling SELECT rows / LWT `[applied]` / write defaults. **CQL session store** has no Redis-EXPIRE equivalent — `set()` issues `INSERT … USING TTL <ttl>` (atomic write + expiry); `touch()` issues `UPDATE … USING TTL <ttl> SET sess = ? WHERE sid = ?` (rewrites data with fresh TTL); `clear()` uses CQL `TRUNCATE` (heavy cluster op — the only full-table delete CQL allows). Required schema: `CREATE TABLE sessions (sid TEXT PRIMARY KEY, sess TEXT) WITH default_time_to_live = 86400`. Promise → callback safety mirrors post-#CB-BUG-4: write methods MUST call `fn(null)` explicitly inside `.then()`, never `.then(fn)` directly. Established 2026-05-09 (#CN5).
@@ -840,5 +840,13 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 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.
+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. **`router.js` had the same antipattern at two sites** (`refreshCoreDependencies()` ~L116-127 and the controller-require path ~L617-627) — latent because router.js was the slot's only consumer and read it back self-consistently. Fixed 2026-05-16 (#B18) by dropping the `require.cache[path] = require(path)` line at both sites and reading `SuperController = require(path)` directly; the preceding `delete require.cache[require.resolve(path)]` already evicts the slot so the next `require()` builds a fresh `Module`. Test coverage in `test/core/router.test.js § 10` (8 tests: source pins enforcing the antipattern is gone, both fix sites preserve the delete-before-require shape, plus a pure-logic replica showing why poisoning breaks plain `require()`). Established 2026-05-14; fix closed 2026-05-16.
+
+105. **`Controller::throwError` JSON wire — fail-closed `stack` strip outside local scope.** `core/controller/controller.js` (~L5138, after the L5129-5137 fallback initializer and before the L5139 serialization) carries `if (!_isLocalScope && errorObject && errorObject.stack) delete errorObject.stack;` so server-side internals (file paths, library versions, internal stack frames) don't leak to API clients in beta, testing, production, or any unset scope. Local scope (`NODE_SCOPE_IS_LOCAL=true`) preserves the stack on the wire because the dev toolbar's `data-xhr` panel reads `XHRData.stack` from the parsed JSON body (`events.js:394` `JSON.parse(xhr.responseText)` → `ginaToolbar.update('data-xhr', XHRData)` at `events.js:463/498/590`). **Fail-closed shape, not fail-open**: the gate is `!_isLocalScope` (strip unless local) rather than `_isProdScope` (strip only if production explicitly set) — a missing or unset `NODE_SCOPE_IS_LOCAL` still strips, so env-var slip on a fresh prod deployment can't reintroduce the leak. The single intervention sits after both construction paths converge (the L5006-5050 if/else-if chain AND the L5129-5137 fallback initializer) so one delete covers both the L5141 catch-all `JSON.stringify(errorObject)` path and the L5143-5149 explicit-whitelist `stack: errorObject.stack || null` path. Same scope-gating shape as the `#R7` Inspector reveal endpoint (local-scope-only) and consistent with the `#P19` module-load env-cache pattern (`_isLocalScope` is read once from `process.env.NODE_SCOPE_IS_LOCAL` at controller.js:69, which `gna.js:304` sets at bootstrap from the configured scope). The L5029-5031 explicit-extract comment ("reach the client error dialog") remains accurate for the local-scope path only. **Out of scope, separate slices**: (a) HTML error-page branch at L5292-5333 `<pre class="stack">` still leaks in non-local scopes when no custom error template is configured; (b) consumer-side leaks where `err.stack` is passed directly as the `msg` argument and surfaces in the `error` string instead of the gated `stack` field — needs per-call-site sanitization on the consumer side. Server-side log line at L5153 (`console.error(errOutput)`) intentionally mirrors the wire — what is sent is what is logged. Established 2026-05-16. (Note: this number collides with the pre-existing entry #105 at L760 — known duplicate, awaiting comprehensive numbering pass.)
+
+110. **`Controller::throwError` HTML branch — fail-closed `<pre class="stack">` strip outside local scope.** Symmetric companion to the JSON wire entry above (at L845 in this file). The fallback HTML error page constructed inside `controller.js` (~L5294+, when no custom error template is configured) now gates both render sites on `_isLocalScope`: the msg-shape `if (msg.stack && _isLocalScope)` (~L5311) and the generic-shape `if (stack && _isLocalScope)` (~L5349) — so the `<pre class="...stack">` block never reaches non-local viewers. Title / error / message `<pre>` blocks continue to render unconditionally. Custom error templates dispatched via `renderCustomError` at L5266-5281 stay consumer-owned — what a consumer view renders from `req.params.errorObject` (e.g. `{% if data.stack %}{{ data.stack }}{% endif %}`) is the consumer's call. With both the JSON wire gate and this HTML branch gate in place, the framework's two error-response wire shapes are scope-gated atomically; only the consumer-side leak shape remains (callsites that pass `err.stack` as the msg argument and surface it in the `error` STRING — needs per-callsite sanitization, the framework can't reach it). Test coverage in `test/core/controller.test.js § 13` mirrors § 12's shape: source pins on both gates + position-relative-to-msgString-anchor + pure-logic replicas (msg-shape + generic-shape × local/non-local × stack/no-stack). Number jumps from #105 → #110 to avoid the existing duplicate cluster at L760-775 (#105/106/107/108) — comprehensive numbering pass deferred. Established 2026-05-16.
+
+111. **#S7 — `/_gina/info` and `/_gina/cache/stats` IP-allowlist gate (admin axis, mirrors #OBS1 `/_gina/metrics`).** Both endpoints expose process state (`process.memoryUsage` / `uptime` / `version` / HTTP/2 session counters at `/_gina/info`, full cache contents at `/_gina/cache/stats`) — admin-grade information that should not reach public callers. The gate lives at `server.isaac.js` module scope as `isAdminClientAllowed(req)` and is invoked at the top of each handler (~L664 for `/_gina/info`, ~L707 for `/_gina/cache/stats`) returning a 403 JSON `{error:'forbidden',message:'...client IP not in app.json admin.allowFrom'}` with cache-control headers on deny. Allowlist is configured via the new `admin.allowFrom` block in `app.json` (schema/app.json declares it as a sibling of `metrics`); defaults to `['127.0.0.1', '::1']` (loopback) when omitted; empty array `[]` is explicit deny-everyone. `core/gna.js` reads the block in the existing `server.on('started')` callback (right after the metrics init block) and caches it on `process.gina._adminAllowList` so `server.isaac.js` can read it without a per-request `gna.getConfig` call. Five invariants mirror the `lib.metrics.isClientAllowed` pattern: (1) IP is read from `req.socket.remoteAddress` only — `X-Forwarded-For` is NEVER trusted because reverse proxies could spoof it; (2) `::ffff:IPv4` is normalised to `IPv4` so listing `127.0.0.1` matches both forms; (3) `req.connection.remoteAddress` is a fallback for older Node versions; (4) empty allowlist denies everyone (explicit lockdown); (5) missing `process.gina._adminAllowList` falls back to loopback (defensive against init order). `/_gina/health/check` is intentionally NOT gated (k8s liveness probes need it open). `/_gina/metrics` keeps its own separate `metrics.allowFrom` gate — separate axis from `admin.allowFrom`, so bundles that disable metrics still get the admin lockdown. Test coverage in `test/core/server.isaac.test.js § 08` (source structure pins on the helper + both handler invocations + gna.js init + schema declaration) + `§ 08b` (10-case pure-logic replica covering loopback/non-loopback × IPv4/IPv6/IPv6-mapped × empty-allowlist × `req.connection` fallback × missing-socket × X-Forwarded-For spoof). The shape is reusable for any future admin-grade `/_gina/*` endpoint — copy the gate check + add to the handler. Established 2026-05-16.
+
+112. **#B16 — `--force` semantics on `gina project:rm` honoured for partial-breakage states (missing manifest, missing project dir).** The whole point of `--force` on a rm command is to tolerate broken state — disk-full mid-scaffold, manually-deleted directory, stuck `~/.gina/projects.json` row with no on-disk artefacts. Pre-fix, the framework's shared `CmdHelper.loadAssets()` (`lib/cmd/helper.js`, ~L640) read `manifest.json` unconditionally before `project:remove`'s handler started; the recreate-from-template fallback itself failed when the project DIR was gone; the downstream `requireJSON` then bubbled an `ENOENT: no such file or directory, open '<projectPath>/manifest.json'`. Two coordinated fixes: (a) `loadAssets()` recognises `/\:remove$/.test(cmd.task) && cmd.params['force']` and stubs `cmd.projectData = { project: cmd.projectName, version: '0.0.0', bundles: {} }` instead of reading from disk — downstream consumers (homedir / bundles / releases / per-bundle `gina_version` resolution at L967-970) read `projectData` only via guarded `typeof != 'undefined'` checks, so the stub satisfies every site; (b) `lib/cmd/project/remove.js` `init()` (~L53) now warns and `return end(true)` when the project folder is missing AND `--force` is set, bypassing the prompt + folder rmSync and going straight to ports cleanup + `~/.gina/projects.json` delete. Without `--force`, both sites preserve the original `console.error` + `process.exit(1)` so typos and wrong-machine invocations still surface immediately. The registry-missing check (`projects[projectName] not found in ~/.gina/projects.json`) is unchanged — `--force` can't help when there's no record to remove. **By-design overshoot:** the helper.js task regex `/\:remove$/` matches ANY `:remove` task, not just `project:remove` — `bundle:remove --force` would ALSO get the manifest-tolerance treatment (test §03 documents this). That's fine because (i) no other `:remove` task exists today, (ii) if one is added, the same tolerance is probably what it wants, and (iii) the bundle:remove handler has its own checks downstream so the wrong-target case still surfaces. Test coverage at `test/lib/project-remove.test.js` §01 (helper.js source pins) + §02 (remove.js source pins + negative invariants) + §03-04 (pure-logic replicas covering force × missing-manifest, force × missing-folder, no-force preserved-behaviour, stub-satisfies-downstream). Established 2026-05-16.
 

package/package.json

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

package/schema/app.json

@@ -67,6 +67,19 @@
           "default": true
         }
       }
+    },
+    "admin": {
+      "type": "object",
+      "description": "Admin-grade /_gina/* endpoint access control. Gates /_gina/info and /_gina/cache/stats on a per-bundle IP allowlist. Same shape as `metrics.allowFrom` but a separate axis — admin endpoints expose process state (memory, uptime, HTTP/2 session counters, cache contents) and are scope-separately from Prometheus scrapes.",
+      "additionalProperties": false,
+      "properties": {
+        "allowFrom": {
+          "type": "array",
+          "description": "IP allowlist for admin /_gina/* endpoints (/_gina/info, /_gina/cache/stats). Requests from any other source receive 403. Defaults to localhost only (127.0.0.1, ::1). Empty array `[]` denies everyone — explicit lockdown choice. Reads from req.socket.remoteAddress only — X-Forwarded-For is NOT trusted because reverse proxies could spoof it.",
+          "items": { "type": "string" },
+          "default": ["127.0.0.1", "::1"]
+        }
+      }
     }
   },
   "definitions": {

package/framework/v0.3.13/VERSION

@@ -1 +0,0 @@
-0.3.13