gina 0.5.16 → 0.5.17

package/CHANGELOG.md

@@ -6,6 +6,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.17 - 2026-07-13
+### Fixed
+* Cleaning up a stale project registration is now reliable. `gina project:rm @<project> --force` (the `:rm` alias) removes the entry instead of erroring — the alias had failed an internal `--force` guard that only the full `project:remove` form passed. And `gina project:remove` / `project:rm @<project> --force` no longer crashes with an `ENOENT` error when the stale project's path can no longer be created (a top-level path such as `/app`, or any path under a read-only parent): it skips the now-pointless project-directory re-creation and goes straight to registry-only removal, cleaning both `~/.gina/projects.json` and its state-store mirror plus the project's port assignments — without resurrecting an empty skeleton directory.
+* Installing gina with the npm 12 `--allow-scripts=gina` remedy (or `npm config set allow-scripts=gina --location=user`) no longer fails with `EALLOWSCRIPTS`. npm exports the allowance to install-script children as `npm_config_allow_scripts`, and npm rejects it in project-scoped installs — which killed the nested framework-dependency install inside post-install, and with it the whole `npm install -g gina`. The nested install now drops the inherited allowance for its duration (the framework dependencies carry no install scripts, so nothing is lost). This unblocks the npm 12 install path, where install scripts are blocked by default and the flag is required.
+* `gina bundle:start` now honours a bundle's configured default scope. A typo in the scope-resolution expression returned an undefined property, so a bundle that declared a default scope in its manifest started with an undefined scope instead of the configured one (bundles with no configured default scope were unaffected — they already fell back to the framework default scope). The command now reads the correct property.
+
 ## 0.5.16 - 2026-07-12
 ### Added
 * Multipart text fields are now captured into the request body: `request.body` (and `request.post`/`request.put`/`request.patch`) carries the non-file fields of a `multipart/form-data` request — bracket-notation names arrive nested and values verbatim (no url-decode, no boolean/null coercion), capped by the new `upload.maxTextFields` (default 1000) and `upload.maxTextFieldSize` (default 1MB) settings with a 400 on breach. Previously every text field of a multipart request was silently dropped.

package/README.md

@@ -42,13 +42,11 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.5.16
+## What's in 0.5.17
 
-- **Added — multipart text fields are captured into the request body.** A `multipart/form-data` request's non-file fields now populate `request.body` (and `request.post`/`request.put`/`request.patch`) — bracket-notation names arrive nested and values verbatim (no url-decode, no boolean/null coercion), capped by the new `upload.maxTextFields` (default 1000) and `upload.maxTextFieldSize` (default 1MB) settings with a 400 on breach. Previously every text field of a multipart request was silently dropped.
-- **Fixed — `$form.send(FormData)` keeps its non-file fields.** When the payload also carries files, the non-file fields now ride the multipart body as standard text parts and reach the server nested exactly as on the JSON (fileless) path, instead of being dropped.
-- **Fixed — a routing rule's `param.title` reaches the browser-tab title.** The routing-param title promotion had been silently inert since its introduction, so the tab title always showed the route name; a rule's `param.title` now sets `page.view.title` (the stripped route name remains the fallback for title-less rules, and a controller-set title still wins). The `view:add` layout boilerplate now reads `page.view.title` / `page.view.lang`, so freshly scaffolded pages get a real tab title and lang attribute.
-- **Fixed — `settings.i18n.cookieName` is now honoured.** The per-request locale negotiation reads the cookie named by the setting (default `gina_culture`), and an explicit `null` disables cookie-based negotiation. Previously the shipped key was silently ignored — the cookie name was hardcoded.
-- **Fixed — the locale-DB fallback no longer 500s or falls back by accident.** When a request's language is missing from the region data, the fallback now resolves deterministically (`region.isoShort` → legacy `region.shortCode` → `en`) with every step guarded. Previously a bundle without a `region` settings block could answer 500, and schema-valid bundles silently received the first region record while the warn printed `undefined`.
+- **Fixed — `npm install -g gina` works under the npm 12 `--allow-scripts=gina` remedy.** With the npm 12 install-script allowance set (the `--allow-scripts=gina` flag, or `npm config set allow-scripts=gina --location=user`), the global install no longer fails with `EALLOWSCRIPTS`: the nested framework-dependency install inside post-install now drops the inherited `npm_config_allow_scripts` for its duration (those dependencies carry no install scripts, so nothing is lost). This makes `0.5.17` the first Gina version installable on npm 12, where install scripts are blocked by default and the allowance is required. (#B106)
+- **Fixed — stale project cleanup is reliable.** `gina project:rm @<project> --force` (the `:rm` alias) now removes the registration instead of erroring, and neither `project:remove` nor `project:rm --force` crashes with `ENOENT` when a stale project's path can no longer be created (a top-level path, or one under a read-only parent) — it goes straight to registry-only removal, cleaning `~/.gina/projects.json`, its state-store mirror, and the project's port assignments without resurrecting an empty skeleton directory. (#B104 / #B105)
+- **Fixed — `gina bundle:start` honours a bundle's configured default scope.** A typo in the scope-resolution expression returned an undefined property, so a bundle that declared a default scope in its manifest started with an undefined scope; the command now reads the correct property. (Bundles with no configured default scope were unaffected — they already fell back to the framework default scope.)
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -41,6 +41,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.5.14` ✅ | Validator + error-handling robustness — a non-string validator error label now degrades to the rule's English default instead of throwing (the throw had aborted validation and left every later form on the page unbound), across all four label sources · a per-field `ApiError` message no longer leaks a raw server stack trace to the browser outside local scope · a changing validator message on a still-invalid field re-announces through the ARIA live region · release: stable publishes assert a single, correctly-named README "What's in" section |
 | **Q3 2026** | `0.5.15` ✅ | Client-side components (Web Components) — standards-based, zero-dependency conventions for stateful client widgets: `gina view:add` scaffolds a reference custom element (server-rendered light-DOM partial + behavior-only class), components upgrade automatically in popin/XHR-injected content with no rebinding, form-associated custom elements participate in `FormValidator`, live-data components ride the connect/disconnect lifecycle over `method:"ws"` routes or SSE, and the dev Inspector gains a component census + client component-event capture · a popin/dialog trigger can opt out of the hover/focus preload (`data-gina-dialog-preload="false"`) · **Fixed**: `gina.popin` sees every popin so a form can redirect into a different one (#B90), a redirect into a popin opens content-first (#B79), server-side validation of a data object against a rules object works (#B85), `$form.send(FormData)` nests bracket-notation field names (#B92), a fields-only multipart POST no longer hangs (#B93) and a malformed multipart body no longer crashes the bundle (#B97), `X-Powered-By` suppression reaches static and error responses (#B96), and upload reset/delete removes the preview, restores class-hidden inputs, and gains removal callbacks (#B94/#B95) |
 | **Q3 2026** | `0.5.16` ✅ | **Added**: a `multipart/form-data` request's non-file text fields are now captured into `request.body` (bracket-notation nested, values verbatim, capped by `upload.maxTextFields` / `upload.maxTextFieldSize` with a 400 on breach) — previously silently dropped · **Fixed**: `$form.send(FormData)` keeps its non-file fields when the payload also carries files (#B92), and a routing rule's `param.title` now reaches the browser-tab title (`page.view.title`) instead of always showing the route name, with the route name as the fallback (#B98) |
+| **Q3 2026** | `0.5.17` ✅ | **Fixed**: `npm install -g gina` no longer fails with `EALLOWSCRIPTS` under the npm 12 `--allow-scripts=gina` remedy — the nested framework-dependency install drops the inherited allowance, making `0.5.17` the first version installable on npm 12 (#B106) · stale project cleanup is reliable — `project:rm @<project> --force` (the alias) removes the entry, and `project:remove` / `:rm --force` no longer `ENOENT`-crashes on an uncreatable stale path, going straight to registry-only removal (#B104/#B105) · `bundle:start` honours a bundle's configured default scope (a typo had returned an undefined property) |
 | **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
 

package/framework/v0.5.17/VERSION

@@ -0,0 +1 @@
+0.5.17

package/framework/{v0.5.16 → v0.5.17}/lib/cmd/bundle/start.js

@@ -297,7 +297,7 @@ function Start(opt, cmd) {
         }
 
         var env = ( typeof(self.bundlesByProject[self.projectName][bundle].def_env) != 'undefined') ? self.bundlesByProject[self.projectName][bundle].def_env : self.defaultEnv;
-        var scope = ( typeof(self.bundlesByProject[self.projectName][bundle].def_scope) != 'undefined') ? self.bundlesByProject[self.projectName][bundle].def_scpoe : self.defaultScope;
+        var scope = ( typeof(self.bundlesByProject[self.projectName][bundle].def_scope) != 'undefined') ? self.bundlesByProject[self.projectName][bundle].def_scope : self.defaultScope;
         // terminal.debug('env -> ', env);
         var protocol = self.bundlesByProject[self.projectName][bundle].def_protocol;
         // terminal.debug('protocol -> ', protocol);

package/framework/{v0.5.16 → v0.5.17}/lib/cmd/helper.js

@@ -541,7 +541,9 @@ function CmdHelper(cmd, client, debug) {
                 // valid name but not in projects and task != :add, :remove, :import or :restore
                 // (project:restore registers a brand-new on-disk tree from an archive,
                 //  so its @<name> is legitimately not-yet-registered — like :add/:import)
-                if ( typeof(cmd.projects[cmd.projectName]) == 'undefined' && !/\:(add|import|remove|restore)$/.test(cmd.task) ) {
+                // #B104 — `rm` co-listed with `remove` so the `project:rm` alias follows the
+                // same not-yet-registered exemption as `project:remove` (consistent alias).
+                if ( typeof(cmd.projects[cmd.projectName]) == 'undefined' && !/\:(add|import|remove|rm|restore)$/.test(cmd.task) ) {
                     errMsg = 'Project ['+ cmd.projectName +'] not found in your projects list';
                     console.error(errMsg);
                     exit(errMsg);
@@ -690,9 +692,40 @@ function CmdHelper(cmd, client, debug) {
                 // (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'] ) {
+                if ( /\:(remove|rm)$/.test(cmd.task) && cmd.params['force'] ) {
+                    // #B104 — accept BOTH `project:remove` and the `project:rm` alias:
+                    // `cmd.task` is the raw argv token (`:292`), and `:rm` resolves to
+                    // `remove.js` purely via the `rm.js` file redirect, leaving the token
+                    // literal. The bare `/\:remove$/` failed the alias, so `project:rm
+                    // @<stale> --force` fell through to the #B59 gone-dir error below and
+                    // removed nothing. (`:544`'s sibling exemption set is broadened to match.)
                     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: {} };
+                    // #B105 — for a stale-entry removal, SKIP every asset-recreation block
+                    // below (the homedir / bundles / releases / logs / tmp / cache mkdirSync
+                    // blocks + the env.json write): there is nothing to (re)build for a project
+                    // being deleted, and for an UNCREATABLE path (a top-level `/app`, or any
+                    // path under a non-writable parent) the env.json write ENOENT-throws — the
+                    // outer catch turns it into an emerg + exit(1) BEFORE `remove.js` runs.
+                    // Skipping also drops the wasteful resurrect-then-delete for a merely-gone
+                    // (creatable) path. Populate exactly what `remove.js` reads — projectLocation
+                    // (its init) + the port maps (its end()'s cleanup) — then return.
+                    // The ports load is LOAD-BEARING here: the gone-path early-return further
+                    // down sits BEFORE the canonical ports load, and `remove.js` end() rewrites
+                    // ports.json / ports.reverse.json unconditionally — so without loading them
+                    // the maps would be the empty `{}` defaults and EVERY project's ports would
+                    // be wiped. Mirror the canonical load (see the `cmd.portsData = requireJSON`
+                    // site later in this function); the port paths are already set at `:563-564`.
+                    cmd.projectLocation = _(cmd.projects[cmd.projectName].path, true);
+                    if ( typeof(require.cache[cmd.portsPath]) != 'undefined') {
+                        delete require.cache[require.resolve(cmd.portsPath)]
+                    }
+                    cmd.portsData          = requireJSON(cmd.portsPath) || {};
+                    if ( typeof(require.cache[cmd.portsReversePath]) != 'undefined') {
+                        delete require.cache[require.resolve(cmd.portsReversePath)]
+                    }
+                    cmd.portsReverseData   = requireJSON(cmd.portsReversePath) || {};
+                    return;
                 } else if ( ! fs.existsSync(cmd.projects[cmd.projectName].path) ) {
                     // #B59 — the project DIRECTORY itself is gone (a valid-length path pointing
                     // at a deleted dir, or an empty/invalid `.path`). The recreate `else` below

package/framework/{v0.5.16 → v0.5.17}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "dependencies": {
     "@rhinostone/swig": "^2.7.2",
     "intl-messageformat": "^11.2.4",

package/gna.js

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

package/llms.txt

@@ -845,7 +845,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 - **Lockfile-probe package manager detection — ordered table, first match wins, no heuristics** — for an install-a-package CLI step (e.g. `connector:add --install`), detect PM by walking a fixed lockfile list: `bun.lockb` → `pnpm-lock.yaml` → `yarn.lock` → `package-lock.json` (fall back to npm). Never infer from `package.json.packageManager`, `process.env.npm_execpath`, or `which <pm>`. Pair with 3-tier install-range resolution (explicit user pin → project deps → framework peerDeps).
 - **Argv `--<key>=<value>` parsing — split on the first `=` only, never on every `=`** — both `utils/helper.js::filterArgs` and `framework/v*/lib/cmd/helper.js::getParams` parse `--key=value` tokens; both used to call `.split(/=/)` with no limit, silently truncating any value containing `=` (signed tokens, version ranges like `">=5.3.0 <6.0.0"`). Correct: `var _eq = raw.indexOf('='); arr = (_eq > -1) ? [raw.substring(0, _eq), raw.substring(_eq + 1)] : [raw]`. `split(/=/, 2)` is NOT a valid replacement (drops everything after second `=`). Locked by negative-invariant tests in `test/lib/cli-arg-parsing.test.js`.
 - **PWA scaffold delivery path — `view:add`, not `bundle:add`, carries `bundle_public/` + `bundle_templates/`** — `bundle:add` copies just `boilerplate/bundle/` (JSON-API bundle, 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. Files under `bundle_public/` are NOT token-substituted — only `add.js` does `${bundle}` substitution. Filename is `manifest.webmanifest`, not `manifest.json`.
-- **`--force` on rm commands tolerates partial-breakage states** — `CmdHelper.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; `project/remove.js init()` warns and proceeds to ports cleanup + `~/.gina/projects.json` delete when the project folder is missing AND `--force` is set. Without `--force`, both sites preserve `console.error` + `process.exit(1)` so typos still surface. By-design overshoot: the `/\:remove$/` regex matches ANY `:remove` task — `bundle:remove --force` would inherit the same tolerance. **Sibling robustness (#B59, 2026-07-01, `helper.js`):** a corrupt `projects.json` registration no longer emerg-crashes EVERY command. Three degrade-not-throw points, all inside `isCmdConfigured`'s try (whose catch does `console.emerg(stack)` + `exit(1)`): the `:262` registry loop pre-checks each `.path` against `_()`'s reject set (undefined / `''` / length≤2) and `console.warn`+`continue`s a corrupt entry (mirrors #B24's degrade-and-continue) instead of letting `new _('')` throw; the targeted deref (the `else if` ~`:366`) now requires a truthy length>2 `.path`, so an empty targeted path falls to the cwd fallback exactly like an already-handled undefined one and reaches the clean guard; and a THIRD `else if ( ! fs.existsSync(cmd.projects[name].path) )` — a SIBLING of the `/\:remove$/ && force` branch above, NOT a guard atop the recreate `else` (so that branch stays byte-identical and its source-inspection test passes unchanged) — clean-exits with `path no longer exists — re-add / remove --force` instead of the auto-manifest `createFileFromDataSync` ENOENT (the generator does no `mkdir -p`; use `fs.existsSync`, not `_()`, so an empty path is tested without throwing). Verified via an isolated-home A/B smoke (PRE-FIX all 3 cases stack-dump; FIXED clean); tests `helper.test.js §20`. **Sibling loud-reject (#B69, 2026-07-05, same file):** an `@` token whose first char falls outside `[a-z0-9_.]` (e.g. `@Myproject`, a bare `@`) was silently dropped by the argv detection loop — the command then ran against the cwd project / all projects with exit 0 (a mutating task like `bundle:add` could write to the wrong project while reporting success). Such tokens now reject loudly (`is not a valid project name`, exit 1) via a catch-all `else if (/^\@/)` after the detection branch; the detection regex and `isValidName` both test only the FIRST char, so the pre-existing `!isValidName` reject inside the detection branch is unreachable dead code. The family's `@<project>`-not-registered path was separately measured to already exit 1 (pipe + PTY, Node + Bun) — when checking CLI exit codes, read `$?` directly, never through a pipeline.
+- **`--force` on rm commands tolerates partial-breakage states** — `CmdHelper.loadAssets()` recognises `/\:(remove|rm)$/.test(cmd.task) && cmd.params['force']` (broadened from a bare `/\:remove$/` — #B104, so the `project:rm` alias reaches it, not just `project:remove`) and stubs `cmd.projectData = { project: cmd.projectName, version: '0.0.0', bundles: {} }` instead of reading from disk; `project/remove.js init()` warns and proceeds to ports cleanup + `~/.gina/projects.json` delete when the project folder is missing AND `--force` is set. Without `--force`, both sites preserve `console.error` + `process.exit(1)` so typos still surface. By-design overshoot: the `/\:(remove|rm)$/` regex matches ANY `:remove`/`:rm` task — `bundle:remove --force` would inherit the same tolerance. **Sibling robustness (#B59, 2026-07-01, `helper.js`):** a corrupt `projects.json` registration no longer emerg-crashes EVERY command. Three degrade-not-throw points, all inside `isCmdConfigured`'s try (whose catch does `console.emerg(stack)` + `exit(1)`): the `:262` registry loop pre-checks each `.path` against `_()`'s reject set (undefined / `''` / length≤2) and `console.warn`+`continue`s a corrupt entry (mirrors #B24's degrade-and-continue) instead of letting `new _('')` throw; the targeted deref (the `else if` ~`:366`) now requires a truthy length>2 `.path`, so an empty targeted path falls to the cwd fallback exactly like an already-handled undefined one and reaches the clean guard; and a THIRD `else if ( ! fs.existsSync(cmd.projects[name].path) )` — a SIBLING of the `/\:remove$/ && force` branch above, NOT a guard atop the recreate `else` (so that branch stays byte-identical and its source-inspection test passes unchanged) — clean-exits with `path no longer exists — re-add / remove --force` instead of the auto-manifest `createFileFromDataSync` ENOENT (the generator does no `mkdir -p`; use `fs.existsSync`, not `_()`, so an empty path is tested without throwing). Verified via an isolated-home A/B smoke (PRE-FIX all 3 cases stack-dump; FIXED clean); tests `helper.test.js §20`. **Sibling loud-reject (#B69, 2026-07-05, same file):** an `@` token whose first char falls outside `[a-z0-9_.]` (e.g. `@Myproject`, a bare `@`) was silently dropped by the argv detection loop — the command then ran against the cwd project / all projects with exit 0 (a mutating task like `bundle:add` could write to the wrong project while reporting success). Such tokens now reject loudly (`is not a valid project name`, exit 1) via a catch-all `else if (/^\@/)` after the detection branch; the detection regex and `isValidName` both test only the FIRST char, so the pre-existing `!isValidName` reject inside the detection branch is unreachable dead code. The family's `@<project>`-not-registered path was separately measured to already exit 1 (pipe + PTY, Node + Bun) — when checking CLI exit codes, read `$?` directly, never through a pipeline. **Sibling completion (#B104/#B105, 2026-07-13, same file):** stale-entry `--force` removal now works for the `project:rm` alias AND an uncreatable path. #B104: the guard tests the raw `cmd.task` (=`argv[2]`); `:rm` resolves to `remove.js` by file-redirect only (there is NO canonical name in helper scope), so `project:rm @<stale> --force` failed the bare `/\:remove$/` and fell through to the #B59 gone-dir error, removing nothing — broadened to `/\:(remove|rm)$/` at the `--force` guard AND the `:544` not-registered exemption set (`/\:(add|import|remove|rm|restore)$/`). #B105 (a #B59 residual): the `--force` branch used to stub `projectData` then CONTINUE into loadAssets' recreation blocks — the project-path `mkdirSync`s (which swallow their Error return) + the `env.json` `createFileFromDataSync`, which ENOENT-THROWS for an uncreatable path (a top-level `/app`, or one under a non-writable parent — the generator writes a sibling temp then renames, no `mkdir -p`) → emerg BEFORE `remove.js` runs; a merely-gone-but-creatable path was wastefully resurrected-then-deleted. It now SKIPS all recreation: sets `cmd.projectLocation` + loads the port maps, then RETURNS. The ports load is LOAD-BEARING — the gone-path early-return (`fs.existsSync(projectLocation)` false → `return`) sits BEFORE the canonical ports load, and `remove.js` end() rewrites `ports.json`/`ports.reverse.json` unconditionally, so skipping it would blank EVERY project's ports. Verified isolated-home A/B (RED: alias `_err59` + entry stays / `/app` ENOENT emerg; GREEN 11/11 — both surfaces incl. the `gina.db` mirror drop the entry, ports intact, no `/app` skeleton); tests `project-remove.test.js §01/§03/§05` + `project-restore.test.js §10`. Server/CLI-side — no dist rebuild.
 - **CLI Tier 3 — project-tree relocate / archive / restore (`project:move` slice 1 `1c492241`, `project:backup` slice 2 `4fed7de8`, `project:restore` + `lib/archiver.decompress()` slice 3 `68563976`; shipped 0.5.x)** — `project:move @<p> --to=/new/path` atomically `renameSync`-moves the source tree and rewrites ONLY the registry `path` (inverse of `project:rename`); refuses while any bundle runs (no `--force` bypass), refuses cross-filesystem (`EXDEV` → use `project:import`). **THE load-bearing gotcha — `--path` is unusable as a "must-not-exist target" for ANY `project:` command:** the shared `CmdHelper` bootstrap ("Creating project location if not existing") pre-`mkdirSync`s `cmd.params.path` for every `project:` command AND points `projectLocation` at it, so a move/restore target passed via `--path` is auto-created and the handler's "target must not exist" check then refuses on the bootstrap's own dir — take the target via a flag the bootstrap never reads (`--to`), whitelisted in `project/arguments.json` (this DIRECTLY bites `project:restore`, whose help advertised `--path`). Three facts make a path-only move minimal: `ports.json` is NAME-keyed (`"<port>": "<bundle>@<project>/<env>"`), so a name-unchanged move never touches `ports*.json` (a negative `self.ports`-absence pin locks this); the `projects.json` path-derived fields (`bundles_path`/`releases_path`/…) live under `~/.<project>` (homedir, name-keyed), so only the `path` field is rewritten; use `renameSync` (atomic, symlink-preserving, throws `EXDEV` cross-fs), NOT `folder.mv` (cp+rm, dereferences symlinks). `project:backup @<p> [--out=/dump]` archives the SOURCE to `<out>/<p>-<YYYYMMDD-HHMMSS>.zip`, read-only on the registry. **THE archiver gotcha** (`lib/archiver` was COMPLETELY UNUSED before this — "compress() works" was an unverified inherited claim): the directory form `compress(dir, target)` is BROKEN for a project tree — `browse()` walks with `fs.statSync`, which FOLLOWS symlinks, so it recurses the project's absolute `node_modules/gina` symlink into the entire framework install AND leaks absolute host paths; use the ARRAY form `compress([{input,output},…], target, {name,method:'gzip',level:9})` (deterministic `<target>/<name>.zip`, entries at the `output` relative paths, no wrapper folder) with a self-walk that EXCLUDES `node_modules` by name and SKIPS symlinks via `dirent.isSymbolicLink()`. `--with-password` is REJECTED fail-closed — every encryption hook is an empty stub and JSZip can't make encrypted zips, so returning a plaintext archive for an encryption request is a false-security footgun. `project:restore @<name> <archive.zip> --to=/path [--force]` extracts then RE-REGISTERS so the project is immediately startable: `lib/archiver.decompress()` (was an empty stub; now JSZip-3.x — `JSZip.loadAsync` → per-entry `entry.async('nodebuffer')`, skip `entry.dir`, **zip-slip guard** rejecting any entry whose resolved dest escapes the target) → self-invoke `project:add @name --path=<to>` (self-resolved `bin/cli` via `process.execPath`, NEVER a PATH-resolved `gina`) → loop `bundle:add <b> @name --import` over `manifest.bundles` (the only path that allocates a bundle's ports — bare `project:add` allocates 0; `project:import` REFUSES an unregistered name). Uses the explicit `@<name>` CLI shape (cheaper than the no-`@` form help advertised — only the not-found guard needs a `restore` exemption vs 3 guard exemptions otherwise — and `@name` IS the rename-on-restore target). **Sync-emit-before-listener bug (probe-caught, generalizable):** a synchronous early-return emit (missing src / sync throw) fires BEFORE the caller's `.onComplete` attaches its listener, so the listener misses it (hang) — defer synchronous emits via `process.nextTick` (`compress()` has the same latent shape). `lib/archiver` is server-only (fs/zlib) → no plugin rebuild. **Positive-evidence lesson:** all 26 of `project:move`'s source-pin/pure-logic tests PASSED while it was functionally BROKEN by the `--path` collision — only a live `add→move→verify` HTTP-200 smoke caught it, so a new CLI command needs a live happy-path smoke before "done".
 - **CLI Tier 3 — `framework:update` state reconcile (slice 4 `93e1798a`) + `<group>:man` inline man pages (slice 5 `ae34b7ec`); shipped 0.5.x, completes CLI Tier 3** — `framework:update [--to-version=<v>] [--fix|--apply] [--dry-run] [--format=json]` is a **state-migration** command, NOT the "npm self-update" the ROADMAP once advertised (that was declined — can't update the running process, PATH/sudo hazards; deferred behind a future `--self-update`). It reconciles `~/.gina/main.json` (`def_framework` + `frameworks[<short>]`) and `<short>/settings.json` (`version` + `def_framework`) to `GINA_VERSION` (or `--to-version`), automating the manual Post-merge state check; dry-run by default, `--fix`/`--apply` writes. **Writes MUST go through `lib.generator.createFileFromDataSync(obj, path)`** — that routes a `StateStore.isStatePath` match to `StateStore.write` → SQLite key + atomic JSON sidecar IN LOCKSTEP (so reading the sidecar via `requireJSON` while writing via `createFileFromDataSync` repairs BOTH a stale `def_framework` AND a prior `gina.db`-vs-sidecar drift in one shot); a raw `fs.writeFileSync` is the `post_install.js` bug that drifts `gina.db` behind the sidecar. No-CmdHelper handler (models `framework/set.js`/`version.js`, reads bare `GINA_HOMEDIR`/`GINA_VERSION` globals) — the right shape for a no-project framework command, and it sidesteps the `--path` bootstrap-mkdir gotcha entirely (no project arg). Never-regress guard reuses `script/version_compare.isStrictlyOlder` via `require('../../../../../script/version_compare')` (the relative depth is invariant across framework-dir renames, and `version_compare.js` ships to npm). **Is `def_framework` runtime-load-bearing? — outcome (c), runtime-read but NARROW:** `helper.js` keys `mainConfig.protocols[short]`/`schemes[short]` off it to default protocols/schemes for projects that pin no `framework` AND declare none of their own, but scopes/envs/cultures default off `GINA_SHORT_VERSION` not `def_framework`, and the drift only bites at shortVersion (0.4→0.5) not patch granularity; per-shortVersion metadata-map seeding stays `framework:init`'s job (the command WARNS when absent, locked by a negative-invariant test). `gina framework:man` / `project:man` / `bundle:man` / `service:man` **runtime-render** the group's ronn `.1.md` page to the terminal (design fork over a build-time roff generator + `package.json "man"` field — no new markdown/man dependency, none is installed), falling back to that group's `help.txt` with a one-line notice when the `.1.md` is absent (only `gina-framework.1.md` exists today, so `project`/`bundle`/`service` fall back). The cross-group engine lives at `lib/cmd/man-render.js` (sibling to `helper.js`, required as `require('../man-render')` — NOT a per-group `inc/`, because it serves 4 groups; the group comes from `opt.task.topic`, so a future `<group>:man` falls back automatically), and each `lib/cmd/<group>/man.js` is a one-line `module.exports = require('../man-render')`. **Lazy `console` keeps the module require-testable** — `man-render.js` reads `getPath`/`GINA_VERSION`/`lib.logger` lazily INSIDE the handler body, never at module top, so a unit test can `require()` it to exercise the pure helpers (`substitute`/`stripRonn`/`renderMan`) without throwing `lib is not defined` (a top-level `var console = lib.logger` would).
 - **`gina version` reports the framework DEFAULT template engine only** — `version` is a context-free global command (no bundle/project config loads), so its `Template engine:` banner line (a `%engine%` msg-token read from the framework-dir engine package, try/catch-omitted when the package is absent) always names the default engine; a bundle's per-bundle opt-in engine is not visible to it. `--short` is unaffected.
@@ -994,3 +994,5 @@ Dev-mode query instrumentation captures every database query tied to the current
 231. **A routing rule's `param.title` now reaches `page.view.title` — the routing-param promotion loop in `setOptions()` was dead code since its introduction, and the route-name title is now the fallback it was always meant to be (#B98, `0.5.16-alpha.2`).** The historical generic `param.<key>` → `page.<key>` promotion loop in `core/controller/controller.js` `setOptions()` never executed its dispatch: it sat inside the inner `for..in` AFTER a `continue` that fires for every own enumerable property (a string enumerates its char indices), so `set()` was unreachable for any plain value — verified structurally identical in the pre-#P26 blob, so never a regression; the root of years of "`param.title`/`param.template`/`:param` promotions don't work" reports. The fix REPLACES the loop with a guarded title-only promotion (`typeof(p.title) == 'string' && p.title !== ''`) rather than reviving the generic dispatch, because measurement showed every other param key ALREADY reaches templates through live paths: `:bindings` + static keys land bulk-merged at `page.view.params.<key>` (with resolved URL values; `file`/`control`/`title` deliberately excluded from that merge), `section` at `page.section` (bespoke setter), `file` at `page.view.file` — `title` was the ONE promotion with no live equivalent, and a full revival would have created ~20 top-level `page.<key>` writes with zero framework readers plus collision landmines (a param named `data`/`view`/`environment`/`forms` would shadow a framework namespace before its setters run — worst case breaks the render-swig session block). Deliberately NO edit at the route-name write: `set()` merges TARGET-WINS (2-arg `merge` — an earlier write survives later fills), so the promotion simply running earlier in setOptions IS the fallback semantics (pinned by an ordering test); controller-set `data.page.view.title` still beats both via the render two-step merge. Rider: the `view:add` boilerplate layout read the never-populated `page.title`/`page.lang` — now `page.view.title`/`page.view.lang`, so scaffolded apps finally render a real tab title and lang attribute. Server-side only (controller.js is not browser-bundled — no dist rebuild); consumer pickup = version bump + bundle restart. Tests: `test/core/controller.test.js` §01–§03 (real-lib/merge replica + getter-instrument behavioral smoke + ordering pins + the dead-loop subtract control).
 
 232. **The controller locale-DB fallback no longer crashes or falls back by accident — `region.isoShort` (the schema key) → legacy `region.shortCode` → `'en'`, every step guarded (#B100, 0.5.16).** Both catch sites — the `setOptions` locale bridge and the public-but-uncalled `getLocales()` — read `settings.region.shortCode` BLIND (a key the published settings schema forbids: `region` is `additionalProperties: false` with exactly `culture`/`isoShort`/`date`/`timeZone`, and nothing ever seeds it) and fed it unguarded into `findOne({lang: …}).content`. Three measured behaviours: (1) SCHEMA-VALID bundles (region present, no shortCode) did NOT throw — `Collection.find` round-trips its filter through `JSON.stringify`, which DROPS undefined-valued keys, so `findOne({lang: undefined})` collapses to a match-ALL and returns the FIRST record (`en`) while the warn printed ``replacing by default: `undefined` `` — a fallback by accident, not decision; (2) a bundle with NO `region` block threw at the warn's own deref (`reading 'shortCode'`); (3) a legacy `shortCode` naming an unloaded language threw on `.content` (the loaded set is the `core/locales/dist/region` files: `en` + `fr`). The throws escape `setOptions` synchronously and land in `router.route()`'s try/catch → a graceful per-request 500 via `throwError` — never a bundle kill. Fixed with a shared closure helper `getLocaleFallbackLang(conf)` (isoShort → shortCode → `'en'`, existence-guarded; `isoShort` is ISO 639-1, seeded by `bundle:add` as the culture's language part — this is its FIRST framework read) plus a guarded fallback lookup (`findOne(fallback) || findOne('en')`, `.content` gated, `[]` last resort) and the warn now printing the RESOLVED value. **Reusable gotcha: a `Collection` filter with an `undefined` value does not filter — JSON.stringify strips the key and the empty filter matches EVERY record; never pass a possibly-undefined criterion to `find`/`findOne` expecting a no-match.** Server-side only (controller.js not browser-bundled — no dist rebuild). Tests: `test/core/controller-locale-fallback.test.js` (source pins + a real-Collection/real-region-data replica + subtracts reproducing all three pre-fix behaviours); live-verified in an isolated daemonless boot (region-less bundle + unhandled lang → HTTP 200 + honest `en` warn, cold and warm).
+
+233. **The global install died with EALLOWSCRIPTS when the npm 12 allow-scripts remedy was set — the nested framework install must not inherit the allowance (#B106, `0.5.17-alpha.2`).** npm exports every explicitly-set config value to lifecycle children as `npm_config_*` env vars, and npm rejects `allow-scripts` in PROJECT-scoped installs (`EALLOWSCRIPTS` — fires on npm 12.0.1 AND late npm 11.x, measured on 11.16/11.18, absent on 11.6): `script/post_install.js` `npmInstall()` chdirs into the framework dir and runs exactly such an install, so a user following the documented remedy (`--allow-scripts=gina`, or `npm config set allow-scripts=gina --location=user`) had the nested child die and the whole `npm install -g gina` fail — and on npm 12, where install scripts are BLOCKED by default and the flag is required, gina ≤ 0.5.16 had NO working install path at all (default → the bootstrap silently never runs: no `~/.gina`, no framework node_modules, no SUCCESS marker; remedy → the crash). Fixed with a save → delete → run-child → restore-if-defined guard on `npm_config_allow_scripts`, sibling to the pre-existing `npm_config_global` override at the same call site; the `typeof` gate on the restore is load-bearing (assigning `undefined` to a `process.env` key coerces it to the string `"undefined"`). Verified end-to-end in a node:26 container: the fixed package, published to a throwaway local registry and installed REGISTRY-SPEC with the remedy set, succeeds on npm 12.0.1 (SUCCESS + framework node_modules present, nested deps resolved) where `gina@0.5.16` fails on the same path. Three adjacent measurements worth keeping: (a) an `allowScripts` manifest field or a project `.npmrc` does NOT prevent the rejection — the inherited env var is refused regardless, so dropping the env var is the only working fix class; (b) npm 12 does NOT honor the name-keyed allowance for `file:`-tarball installs (scripts stay blocked with the user config AND the inline flag) — verify install-script fixes registry-spec (throwaway Verdaccio; `npm publish --tag` for prereleases), never from a packed tarball; (c) on npm ≤ 11 the allow-scripts warning is ADVISORY — scripts run with no flag, so the config is never needed there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -73,12 +73,12 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.5.16/core/gna",
+  "main": "./framework/v0.5.17/core/gna",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "import": "./index.mjs",
-      "require": "./framework/v0.5.16/core/gna.js"
+      "require": "./framework/v0.5.17/core/gna.js"
     },
     "./gna": {
       "types": "./types/gna.d.ts",

package/script/post_install.js

@@ -499,6 +499,23 @@ function PostInstall() {
     }
 
 
+    /**
+     * Installs the framework directory's own nested dependencies — a
+     * project-scoped `npm install` (`bun install` under Bun) run from
+     * `self.versionPath`.
+     *
+     * Sanitizes inherited `npm_config_*` lifecycle exports around the child:
+     * `npm_config_global` is forced to `false` (this is a project install even
+     * when gina itself is installed globally), and the allow-scripts export is
+     * dropped for the child's duration (#B106) — npm rejects `allow-scripts`
+     * in project-scoped installs (EALLOWSCRIPTS), so an inherited value from
+     * the documented `--allow-scripts=gina` remedy would kill the nested
+     * install and with it the whole global install.
+     *
+     * @inner
+     * @param {function} done - continuation callback
+     * @returns {void}
+     */
     var npmInstall = function(done) {
 
         console.info('Now installing modules. Please, wait ...');
@@ -519,11 +536,21 @@ function PostInstall() {
         console.info('Running: `'+ cmd +'` from '+ process.cwd() );
         console.info('Running using TMPDIR: '+  _(getTmpDir(), true) );
         var oldConfigGlobal = process.env.npm_config_global;
+        var oldAllowScripts = process.env.npm_config_allow_scripts;
         process.env.npm_config_global = false;
+        // #B106 — npm exports explicitly-set config to lifecycle children as
+        // `npm_config_*`, and `allow-scripts` is rejected in project-scoped
+        // installs (EALLOWSCRIPTS): an inherited `--allow-scripts=gina` (or the
+        // user-level config) would kill this nested install. Drop it — the
+        // framework deps carry no install scripts.
+        delete process.env.npm_config_allow_scripts;
         console.info('Running using TMPDIR: '+ cmd);
         console.info(execSync(cmd).toString());
         process.chdir(initialDir);
         process.env.npm_config_global = oldConfigGlobal;
+        if ( typeof(oldAllowScripts) != 'undefined' ) {
+            process.env.npm_config_allow_scripts = oldAllowScripts;
+        }
 
         done()
     }

package/framework/v0.5.16/VERSION

@@ -1 +0,0 @@
-0.5.16