gina 0.4.0 → 0.4.1

package/llms.txt

@@ -567,6 +567,9 @@ gina bundle:remove <bundle> @<project>  # Remove a bundle
 gina bundle:list @<project>             # List bundles (status, port summary, running state)
 gina bundle:list --all                  # List bundles for every registered project
 gina bundle:list @<project> --format=json  # JSON payload with ports, running, pid per bundle
+gina bundle:status <bundle> @<project>   # Status of one bundle (running/stopped, pid, port, env)
+gina project:status @<project>           # Status of every bundle in a project (all projects if omitted)
+gina project:status --format=json        # JSON payload: per-project array of bundle status objects
 gina service:list                       # List framework-internal services (@gina-only)
 gina service:list --format=json         # JSON payload with ports, running, pid per service
 gina connector:list                     # List connectors across every registered project (read-only)
@@ -605,10 +608,7 @@ gina-init                               # Bootstrap ~/.gina/ from env vars (cont
 
 **CLI stubs — commands that appear in docs or help.txt but are NOT implemented (handler files are empty or missing):**
 
-- `bundle:status` / `bundle:rename` / `bundle:copy` — comments-only handler files
-- `project:status` / `project:move` / `project:backup` / `project:restore` — empty or missing
-- `protocol:remove` — no handler file (also has a typo "remouve" in help.txt)
-- `minion:kill` / `minion:list` — no handler files
+- `project:move` / `project:backup` / `project:restore` — empty or missing
 - `framework:update` — empty handler
 - `gina --status` / `gina -t` — not in aliases.json, no handler
 
@@ -859,7 +859,9 @@ Dev-mode query instrumentation captures every database query tied to the current
 123. **Framework-attribution leak sweeps must cover Mermaid `participant` declarations as a separate surface from prose blocks and inline code examples.** When correcting the standalone-Express idiom across a docs family (per llms.txt #118), the prose-sweep grep targets `require('express')` / `var app = express();` in JS code blocks. That grep does NOT match Mermaid `participant App as express()` lines — diagram syntax is structurally different from prose patterns. The canonical sibling cross-check (csrf.md, the gate prescribed by #118) also fails to reveal the gap because csrf.md's own diagram doesn't have an "App" participant at all (it uses middleware-component participants — `Browser`, `Csrf middleware`, `Controller action` — directly). So a prose-only sweep can leave Mermaid diagrams carrying the wrong adoption-shape indefinitely. Mitigation: when running the #118 sweep, add a SECOND grep over the docs tree: `grep -rn 'participant.*express\|App as express' docs/`. Fix shape: drop the `App` participant entirely and route arrows Client → Plugin → Ctrl directly, matching csrf.md's convention (one less intermediate participant; the `next()` call doesn't bounce through a separate App layer at the diagram level). For diagrams that carry a `Note over App,Plugin: ...` caption, reattach to `Note over Plugin: ...` since App is removed. Precedent: 2026-05-17 — `docs/guides/security-headers.md:24` + `docs/guides/csp.md:32` both had `participant App as express()` (carried forward from helmet's docs since HDR1 + HDR5 first shipped). Fixed in `gina-io/docs` commit `b4095ec` (2 files, 7 ins / 13 del). User-caught via "Why are we still talking about express in the diagrams" mid-session — the #118 sweep had landed earlier the same day and missed both. Generalises: any future framework-attribution correction (rename, vocabulary shift, adoption-convention update) should sweep BOTH prose patterns AND Mermaid `participant` declarations, since they're separate grep surfaces with separate idioms. Cost of the extra Mermaid sweep: 1 grep call. Cost of skipping: visible bug carries forward into the next docs reader's view. Established 2026-05-17.
 
 125. **CLI handler authoring & operations — 12 lessons consolidated** (replaces individual entries #17, #23, #24, #55, #56, #58, #59, #60, #62, #63, #102, #112):
-- **CLI stubs** — `bundle:status/rename/copy`, `project:status/move/backup/restore`, `protocol:remove`, `minion:kill/list`, `framework:update`, `gina --status/-t` appear in help.txt or docs but have empty/missing handler files; tracked in `ROADMAP.md § CLI` with target versions; never suggest to users without checking the handler file first.
+- **CLI stubs** — `project:move/backup/restore`, `framework:update`, `gina --status/-t` appear in help.txt or docs but have empty/missing handler files; tracked in `ROADMAP.md § CLI` with target versions; never suggest to users without checking the handler file first. `bundle:status` / `project:status` / `minion:list` / `minion:kill` / `protocol:remove` / `bundle:copy` (+ `cp` alias) / `bundle:rename` shipped 0.4.1-alpha.2. Both minion commands are run-dir-driven process-truth (the "minion" abstraction is half-wired — nothing sets `process.isMinion` or writes `*minion*.pid`, so a minion == any running bundle child-process): `minion:list` lists every live `<bundle>@<project>.pid` grouped by project via `lib.cmdStatusFormat`; `minion:kill @<project>` reaps them (hybrid kill-set = run-dir pidfiles + a `ps -ef | grep 'gina: ...@<project>'` sweep for pidfile-less orphans bundle:stop misses), SIGTERM→grace→SIGKILL escalation, `--dry-run` preview, unlinks stale/killed pidfiles, never touches mount symlinks or its own PID. `protocol:remove <bundle> @<project>` reverts a bundle to the project default protocol by deleting ONLY its `server.protocol/scheme/allowHTTP1` override from the bundle's `settings.json` (config.js `:1003-1011` auto-defaults an absent protocol to `def_protocol`/`def_scheme`); it deliberately does NOT mutate the shared `ports*.json` — `project:add` pre-allocates the full protocol×scheme×env matrix, so the default-protocol port already exists and pruning the set's port would be wrong; a per-env port-presence guard refuses (unless `--force`) when the default-protocol port is missing; `--dry-run` preview, header-preserving JSON rewrite (connector:rm pattern). `bundle:copy <source> <new> @<project>` (+ `cp`) duplicates a bundle under a new name in the SAME project: copies the `src/<source>` tree, then word-boundary-rewrites the name footprint (PascalCase `<Src>`→`<Dst>` for controller class names + lowercase whole-word `<src>`→`<new>` for the gina require-var / `app.json` name / webroot path, `.js`/`.json` files only — embedded tokens like `apiClient` are untouched; a first-bundle webroot `/` is repointed to `/<new>`), allocates a fresh FULL protocol×scheme×env port matrix via the shared `setPorts` (a single-port insert would later emerg in `config.js`, which expects the complete matrix), and clones+repoints the source's manifest entry (`src`/`link`/`releases` target paths). `--dry-run` previews every rewrite site before writing; `--force` overwrites an existing target (its `removeDest` mirrors `bundle:remove`'s deletions). TWO positionals leave `self.name` null (CmdHelper sets it only for a single positional), so the handler reads `self.bundles[0]`/`[1]` directly — which also slips past the `cmd.name`-gated existence guard so the not-yet-registered new name isn't rejected. `bundle:rename <old> <new> @<project>` is the move-sibling — it renames a bundle IN PLACE in the same project (`fs.renameSync` move, NOT a copy) reusing the same `inc/name-rewrite.js` engine but with `fixWebroot:false` (rename moves the only bundle, so there's no first-bundle/collision case; a name-derived `/<old>` webroot is still rewritten by the lowercase pass). Its ports are REKEYED, not reallocated — port NUMBERS are preserved: `ports.json` rewrites the `<old>@<project>/` owner prefix back into the SAME `[protocol][scheme][portKey]` slot (avoiding the two `project/rename.js` bugs: the wrong `[protocol][portKey]` slot, and a project-wide owner replace), then `ports.reverse.json` is rekeyed (`pr[new]=pr[old]; delete pr[old]`) and flipped LAST as the canonical existence record. It REFUSES a running bundle with NO `--force` bypass (`--force` only overwrites an existing dest); the whole multi-surface mutation (symlink → renameSync dir → rewrite tree → env → manifest → ports → ports.reverse) is snapshot-guarded (the `bundle:add` rollback model) so any post-move failure reverses the dir move and restores env/manifest/ports/ports.reverse from in-memory snapshots. NOTE: the ROADMAP's "fix the help.txt remouve typo" item was stale — no such typo existed.
+- **Two-guard `@<project>` requirement asymmetry in `lib/cmd/helper.js`** — a `project:*` command that should run without `@<project>` must be exempted in BOTH guards: the early task-shape guard (`!/^project\:(list|help|status)/`) AND the later projectName-resolution guard (`!/\:list$/.test(cmd.task)` → widened to also allow `^project:status$`). Exempting only the first leaves the second falling through to cwd-project-inference and a "No project name found" error before the handler runs. `project:list` is the working precedent that null `projectName` survives `loadAssets()`.
+- **Single-bundle CLI handlers read `cmd.name` / `self.name`, NOT `self.bundle`** — CmdHelper sets `cmd.name = cmd.bundles[0]` only when exactly one bundle positional is present (`lib/cmd/helper.js`, the `cmd.bundles.length == 1` branch); `cmd.bundles` is the array for bulk operations. There is no `self.bundle` property. Precedent: `bundle:stop` / `bundle:start` / `bundle:status` all read `self.name`. (Worked example: a sub-agent investigation reported the slot as `self.bundle`; a single read of `helper.js` refuted it before the handler shipped — verify agent-relayed property names against source.)
 - **`gina start` does not need sudo with a user-prefix install** — `npm install -g --prefix ~/.npm-global` (standard Gina setup) runs as the current user and doesn't touch `/var/run/`. The "Needs to be launched as [sudo]" comment in `lib/cmd/framework/start.js` only applies to system-wide installs.
 - **`gina start` exits with code 1 even on success** — the startup script detaches the daemon; the shell child exits 1 as part of detachment. Always use `gina status` to confirm rather than the exit code. Sibling: a `gina start` framework server left running can hang the full test suite AND bundle boot via stale `~/.gina/procs.json` forcing the server onto a non-canonical port (see `cli-handlers.md § 11`).
 - **CLI reserved flags — `--port` and `--version` must be renamed in subcommands** — both consumed by the framework's global CLI parser (`utils/helper.js::filterArgs` + `bin/cli:74-119`) before the subcommand sees argv. Use domain-prefixed forms: `--connector-port=`, `--driver-version=`. Un-prefixed forms are silently swallowed.
@@ -875,7 +877,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 126. **Release pipeline failure modes & recovery — 9 lessons consolidated** (replaces individual entries #15, #16, #43, #45, #46, #66, #84, #100, #113):
 - **Post-merge state check required after every `git merge --ff-only`** — `post_install.js` does NOT run on a git pull/merge. When the version changes (especially a `shortVersion` bump like `0.2 → 0.3`), three state stores go stale: `~/.gina/main.json` (`def_framework`, `frameworks["${shortVersion}"]`, all metadata keys), `~/.gina/${shortVersion}/settings.json` (missing entirely), `gina.db kv_store` (`main` + `settings/${shortVersion}` keys). Running `npm install` from inside the repo also fails (symlink error); patch the state files directly.
 - **Merge frequency / sync cadence** — merge `dev/wip` → `develop` after every feature/fix. Exception: hold at version boundaries (`0.3.x → 0.4.x`, `0.x → 1.x`) until the full release is prepared, because `git mv framework/v*/` during merge is a live deployment of the globally-installed CLI. Mid-version, the two branches must remain fast-forwardable to each other — never let both branches gain independent commits.
-- **Release pipeline (`script/post_publish.js` chain) — failure modes** — `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); `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`; `framework/v*/package.json` gitignored-but-CI-needed (heredoc-derive); 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; release-session tooling traps (`git filter-repo --replace-text` rewrites blob content only — pair with `--replace-message`; GitHub branch protection `allow_force_pushes: false` blocks ALL force-pushes including admin; full-payload PUT required to toggle; web UI toggle has been observed to silently no-op).
+- **Release pipeline (`script/post_publish.js` chain) — failure modes** — `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 (first defense: `script/retry_lockfile_sync.js` `retryWithBackoff`, ~80s ceiling, schedule `[5,15,30,30]`s; when the retry is exhausted — registry lag past ~80s, e.g. the v0.4.0 cut, 3rd recurrence after 0.3.9/0.3.11 — FAILS CLOSED via `script/sync_docs_deps.js` `readLockedGina`+`resolveDocsDepState`: reverts the docs `devDependencies.gina` to the version still pinned in the unregenerated `package-lock.json` so the committed pair stays consistent and docs CONTENT still deploys (only the badge lags), or skips the develop→main merge via a `docsMergeSafe` gate if the locked version is unreadable — never ships a mismatched pair, so `develop`↔`main` stay ff-only; established 2026-05-30); README freshness code-gate (touch-since-tag check); `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`; `framework/v*/package.json` gitignored-but-CI-needed (heredoc-derive); 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; release-session tooling traps (`git filter-repo --replace-text` rewrites blob content only — pair with `--replace-message`; GitHub branch protection `allow_force_pushes: false` blocks ALL force-pushes including admin; full-payload PUT required to toggle; web UI toggle has been observed to silently no-op).
 - **README.md is NOT auto-updated by any release script** — "What's in X.Y.Z" heading and Features-table Swig version reference are hand-maintained. Before `npm publish`: `grep -nE "What's in|Swig [0-9]" README.md`. README freshness is now a code-level gate in `prepare_version.js` (touch-since-tag check, established 2026-05-05 after three skipped manual-checklist steps in a row).
 - **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, with significant in-flight work 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).
 - **changie body strings — single-quote by default and escape `'` as `''`** — unquoted body containing ` #` (space + hash) → YAML treats it as a comment marker, silently truncating the body; unquoted body containing `:` breaks as a mapping; quoted body with unescaped literal `'` closes the scalar early. Author rule: every new changie entry uses `body: '...'` (single-quoted), every literal `'` inside becomes `''`. Verified by `.githooks/pre-commit` running `script/check_changie_entries.js` against staged `.yaml` files. `changie new -k <Kind> -b <body>` doesn't consistently auto-quote — `head -3 .changes/unreleased/<file>.yaml` after every `changie new` to confirm.
@@ -928,3 +930,8 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 141. **CSP per-response nonce — `gina.plugins.Csp({ useNonce: true })` (opt-in, default off) lets a bundle drop `'unsafe-inline'` from `script-src` without breaking the framework's injected inline scripts.** When `useNonce` is true the `ginaCsp` middleware generates a fresh `crypto.randomBytes(16).toString('base64')` nonce PER RESPONSE (128-bit W3C CSP3 floor), stamps it on the per-request carrier `req._ginaCspNonce`, and rebuilds the header per response appending `'nonce-<value>'` to `script-src` (fallback `default-src`; the factory THROWS at call time if neither directive is present, since the nonce has nowhere to attach). **`req._ginaCspNonce` is the carrier — NOT `res.locals`** (gina has no such slot in EITHER engine — verified: zero hits across server.js / server.isaac.js / server.express.js / controller.js; the issue's `res.locals.cspNonce` assumption does not hold) **and NOT `process.gina.*`** (process-global → would leak across concurrent requests, the PROXY_PREFIX bug class; `req._ginaCspNonce` mirrors the `req._ginaProxyPrefix` precedent, written by a middleware + read by the renderer on the same `req` that flows middleware→routing→controller→render in both engines). The static path (`useNonce:false`) precomputes the header once at factory time and writes no `req` slot — **zero behaviour change + zero per-request allocation** for bundles that don't opt in. The swig + nunjucks render delegates capture `_cspNonce = req._ginaCspNonce` alongside the #M1 req/res capture and stamp `nonce="<value>"` on the `onGinaLoaded` bootstrap `<script>`: swig via a function-local `_nonceLoader()` applied at all 3 ginaLoader injection sites; nunjucks by threading the nonce into `injectAssets()`. The bootstrap `<script type="text/javascript">` tag is built ONCE out-of-band in `config.js` and cached, so the nonce is injected at render time via a `.replace()` into a fresh string (never mutating the shared cache). The nonce is generated ONLY when gina is the header writer (the idempotent first-writer-wins `res.getHeader` guard): if a proxy/ingress already set CSP, no nonce is generated and none lands on the tags, keeping header and tags consistent. **Scope:** the always-on `onGinaLoaded` bootstrap (the production blocker — the only inline script emitted in prod) PLUS the dev-only Inspector (`__ginaData` + console-capture) and metrics-patch inline blocks in BOTH engines, all via the same `_cspNonce` capture + a `_cspNonceAttr` fragment (`nonce ? ' nonce="'+nonce+'"' : ''`) spliced into each `'<script' + _cspNonceAttr + '>'` opening. **nunjucks `injectInspectorScripts` reads the STABLE `local._cspNonce` slot** (stamped from the captured req in the main render scope), NOT volatile `local.req` — `render-nunjucks.test.js` §01 enforces "only one `local.req` read (the capture line)" per the #M1 race-discipline, so a `local.req._ginaCspNonce` read inside the helper trips it; the stable-`local._cspNonce` channel mirrors how that helper already reads `local._timeline`/`local._queryLog`. **Follow-up (shipped) — statusbar + application-template nonce helper.** The render delegates also expose the per-request nonce to templates: swig sets `data.page.cspNonce = _cspNonce` before BOTH `compiledTemplate(data)` sites (cache-hit + cache-miss — the swig var re-evaluates per execute, and the app-template helper must resolve on the cache-hit path too); nunjucks sets top-level `data.cspNonce` in the `env.render`/`env.renderString` context (its native top-level-promotion idiom). Both guard `if (_cspNonce)` so the key is ABSENT when no nonce (`{{ page.cspNonce }}` / `{{ cspNonce }}` then render empty + the `{% if %}` wrapper is falsy → no attribute → byte-for-byte back-compat). The Inspector `statusbar.html` (swig-only, dev-only, `{%- include -%}`d from the layout at the **dist** path) opens with `<script{% if page.cspNonce %} nonce="{{ page.cspNonce }}"{% endif %}>` — src + dist kept BYTE-IDENTICAL (dist is the runtime include artifact, not built from src via build.json; its JS body has zero swig delimiters so the line-1 conditional is the only template construct). This doubles as the **application-template nonce helper**: a bundle marks its OWN inline `<script>`s the same way (swig `{{ page.cspNonce }}`, nunjucks `{{ cspNonce }}`). Verified end-to-end with real execution at both ends — `csp-plugin.test.js §13` (middleware emits the header + stamps `req._ginaCspNonce`) and a real-`@rhinostone/swig` harness that `{%- include -%}`s the actual dist statusbar inside a parent template and confirms `page` inherits into the include (nonce attribute carries the exact value; bare tag without). Tests: `csp-plugin.test.js` §10-13, `render-swig.test.js` §14-16, `render-nunjucks.test.js` §04-06. Established 2026-05-27.
 
+142. **`bin/cli` resolves the framework dir from `GINA_VERSION` (env/persisted) falling back to `package.json` version, then `require()`s `framework/v<version>/lib/generator` — now guarded by `fs.existsSync(frameworkPath)` BEFORE that require.** A `GINA_VERSION` pointing at a non-installed version (a stale pin, or a bind-mounted dev tree at a different version) otherwise throws `MODULE_NOT_FOUND` that the surrounding `try/catch` mislabels as `gina: could not load [ package.json ]` (package.json actually loaded fine), and the legitimate `existsSync` guard sits AFTER the require so it never fires — every CLI command then fails opaquely (in a container, `project:import` silently fails, so bundles report "not registered" on start). The guard now fails fast with a clear `gina framework:install <version>` message via `process.stderr.write` (`console` is not reassigned to the framework logger until later, so `console.alert` is undefined there). Diagnostic tell: `could not load package.json` followed by `Cannot find module '…/framework/v<X>/lib/generator'` means framework version `<X>` is not installed, not that package.json is broken. (`8fa9c278`, 2026-05-30)
+
+143. **`lib/cmd-status-format` — shared run-state/port display primitive for the status/list CLI handlers (`pad` / `pickPreferredPort` / `readPidfile`).** `bundle:list`, `service:list`, `bundle:status`, and `project:status` each carried byte-identical inline copies of three helpers; they now consume `lib.cmdStatusFormat` (`var fmt = lib.cmdStatusFormat;` — the ambient registry global; the bare `require('lib/cmd-status-format')` form does NOT resolve in `bin/cli`/`bin/cmd` daemon scope, the same constraint as `routing-introspect`/`connector-registry`, because the `NODE_PATH` shim runs at bundle runtime). The module is **pure** — requires only node `fs`/`path`, reads no framework globals — so it is unit-testable by a direct require. The load-bearing design move: `readPidfile` was generalised from the inline `readPidfile(bundleName, projectName)` (which read the `GINA_HOMEDIR` + `_` globals) to `readPidfile(runDir, bundleName, projectName)` built with `path.join`; callers pass `GINA_HOMEDIR + '/run'`, and `service:list`'s hardwired `@gina` case becomes `fmt.readPidfile(GINA_HOMEDIR + '/run', name, 'gina')`. `pad` / `pickPreferredPort` were already pure and moved verbatim. **Test-extraction pattern**: the four handler test files were source-inspection suites pinning the inline *definitions*; extraction invalidates those pins, so they were rewritten to consume-the-primitive assertions (`/fmt\.readPidfile\(/` + `doesNotMatch /var readPidfile = function/`) and the behavioural coverage moved to `test/lib/cmd-status-format.test.js` (require-by-path, 15 tests) — the handlers' tests stay thin, the primitive is the behavioural surface. `lib/cmd/connector/list.js`'s byte-identical inline `pad(s, width)` was given the same treatment in `79d71abf` (call site routed through `fmt.pad`, test source-pin re-aimed — the new `var fmt` pin tolerates the column-aligned declaration via `/var fmt\s+= /`); `lib/cmd/cache/stats.js`'s `pad(str, len)` is a different signature and stays inline. Commits `fa0e0c1d`..`45459fa9` (+ `79d71abf` connector:list). Established 2026-05-31.
+
+144. **`self.setTemplate(file, ext)` — runtime template override (controller action API, shipped `0.4.1-alpha.2`).** A controller action resolving its template dynamically (e.g. a catch-all dispatcher) calls `self.setTemplate(file, ext)` AFTER `setOptions()` to override the rule's default; it stashes `local.options._templateOverride = {file, ext}` (ext leading-dot-normalised; non-string args ignored; bails if `local.options` unset). BOTH render delegates read it and resolve the override **verbatim under the templates root with NO namespace prefixing**: render-swig in the path-resolution block ahead of the `namespace` branch, gated `!isRenderingCustomError` (swig's block is shared with custom-error rendering, so a leftover override must not hijack the framework error template); render-nunjucks via an early `return ovFile` in `resolveTemplatePath()` (its custom-error path uses `errOptions`, which carries no override, so no gate needed). **Inert-API gotcha — the writer alone is a no-op:** #27 shipped the writer with ZERO readers (it set `_templateOverride` but no delegate consumed it; source-inspection tests on the writer passed while the feature did nothing). When adding any 'the delegates read X' API, grep the delegates for the reader first and back it with a BEHAVIOURAL test that the rendered output changes. Commits `9f2471f0` (#27 writer + swig reader) + `61211bfb` (#29 nunjucks reader). Established 2026-06-01.

package/package.json

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

package/script/sync_docs_deps.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/*
+ * 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.
+ */
+
+/**
+ * @file script/sync_docs_deps.js
+ *
+ * Fail-closed decision helper for `script/post_publish.js → syncDocs`.
+ *
+ * After a stable publish, `syncDocs` bumps the docs repo's
+ * `devDependencies.gina` to the just-published version and regenerates
+ * `package-lock.json`. When the npm registry's eventual-consistency window
+ * leaves the new version unresolvable past the retry budget (see
+ * `retry_lockfile_sync.js`), the regen fails and `package-lock.json` is left
+ * pinning the PREVIOUS version while `package.json` has already been bumped to
+ * the new one. Committing + merging that mismatched pair to docs `main` breaks
+ * the next Vercel `npm ci` deploy (the recurring failure on
+ * `gina@0.3.7` / `gina@0.3.9` / `gina@0.3.11` / `gina@0.4.0`).
+ *
+ * This helper makes that path FAIL CLOSED: on a regen failure it reads the
+ * version still pinned in the unregenerated `package-lock.json` and reverts
+ * `devDependencies.gina` to match it, so the committed pair stays internally
+ * consistent and the docs CONTENT still deploys — only the cosmetic version
+ * badge lags until a follow-up bump. If the locked version cannot be read, the
+ * merge is skipped entirely rather than ship a mismatch.
+ *
+ * Both functions are pure (no I/O) so the decision is unit-testable without a
+ * real docs repo or registry — the caller passes in the lockfile content and
+ * the retry result.
+ */
+
+'use strict';
+
+
+/**
+ * Extract the `gina` version pinned in a docs-repo `package-lock.json`.
+ *
+ * Handles all three lockfile shapes: `lockfileVersion` 2/3 store packages in a
+ * path-keyed `packages` map; `lockfileVersion` 1 (and the legacy half of a
+ * `lockfileVersion` 2 file) uses a flat `dependencies` map. The `packages` map
+ * is preferred when present.
+ *
+ * @param {string|null} lockfileContent  raw `package-lock.json` text
+ * @returns {string|null} the pinned gina version (e.g. `'0.3.15'`), or `null`
+ *   when the lockfile is absent, unparseable, or carries no gina entry.
+ *
+ * @example
+ *   readLockedGina(fs.readFileSync('package-lock.json', 'utf8')); // '0.3.15'
+ *   readLockedGina(null);          // null
+ *   readLockedGina('{ not json');  // null
+ */
+function readLockedGina(lockfileContent) {
+    if (!lockfileContent) {
+        return null;
+    }
+    var parsed;
+    try {
+        parsed = JSON.parse(lockfileContent);
+    } catch (e) {
+        return null;
+    }
+    // lockfileVersion 2/3 — path-keyed packages map.
+    if (
+        parsed.packages
+        && parsed.packages['node_modules/gina']
+        && parsed.packages['node_modules/gina'].version
+    ) {
+        return parsed.packages['node_modules/gina'].version;
+    }
+    // lockfileVersion 1 (and the legacy half of a v2 file) — flat dependencies map.
+    if (
+        parsed.dependencies
+        && parsed.dependencies.gina
+        && parsed.dependencies.gina.version
+    ) {
+        return parsed.dependencies.gina.version;
+    }
+    return null;
+}
+
+
+/**
+ * Decide what `devDependencies.gina` should be set to, and whether the
+ * docs `develop → main` merge is safe, given the outcome of the lockfile regen.
+ *
+ * @param {object}        opts
+ * @param {object}        opts.lockResult       result from `retryWithBackoff` — `{ ok, attempts, lastErr }`
+ * @param {string|null}   [opts.lockfileContent] raw `package-lock.json` text (read only on the failure path)
+ * @param {string}        opts.newVersion       the just-published gina version (no `^`)
+ * @returns {{ devDep: (string|null), mergeToMain: boolean, reason: string }}
+ *   `devDep` is the spec to set (`'^x.y.z'`), or `null` when no consistent
+ *   spec can be guaranteed; `mergeToMain` is `false` only when shipping the
+ *   merge would risk a mismatched pair; `reason` is a stable diagnostic tag.
+ *
+ * @example
+ *   // regen succeeded — lockfile pins the new version, merge is safe
+ *   resolveDocsDepState({ lockResult: { ok: true }, newVersion: '0.4.0' });
+ *   // → { devDep: '^0.4.0', mergeToMain: true, reason: 'lockfile-fresh' }
+ *
+ *   // regen failed (registry lag), lockfile still pins the old version —
+ *   // revert the devDep to match so the committed pair stays consistent
+ *   resolveDocsDepState({
+ *       lockResult: { ok: false },
+ *       lockfileContent: oldLockfileText, // pins gina@0.3.15
+ *       newVersion: '0.4.0'
+ *   });
+ *   // → { devDep: '^0.3.15', mergeToMain: true, reason: 'registry-lag-reverted' }
+ *
+ *   // regen failed AND the locked version is unreadable — fail closed
+ *   resolveDocsDepState({ lockResult: { ok: false }, lockfileContent: null, newVersion: '0.4.0' });
+ *   // → { devDep: null, mergeToMain: false, reason: 'manual-recovery' }
+ */
+function resolveDocsDepState(opts) {
+    opts = opts || {};
+    var lockResult = opts.lockResult || {};
+    var newVersion = opts.newVersion;
+
+    // Regen succeeded → package-lock.json now pins the new version; the devDep
+    // already set to ^new is consistent and the merge is safe.
+    if (lockResult.ok) {
+        return { devDep: '^' + newVersion, mergeToMain: true, reason: 'lockfile-fresh' };
+    }
+
+    // Regen failed (registry lag). package-lock.json was NOT regenerated and
+    // still pins the previously-locked version. Revert the devDep to match it
+    // so the committed pair is internally consistent and content still deploys.
+    var locked = readLockedGina(opts.lockfileContent);
+    if (locked) {
+        return { devDep: '^' + locked, mergeToMain: true, reason: 'registry-lag-reverted' };
+    }
+
+    // Cannot determine the locked version → cannot guarantee a consistent pair.
+    // Fail closed: skip the merge so no mismatch reaches docs main.
+    return { devDep: null, mergeToMain: false, reason: 'manual-recovery' };
+}
+
+
+module.exports = {
+    readLockedGina: readLockedGina,
+    resolveDocsDepState: resolveDocsDepState
+};

package/framework/v0.4.0/VERSION

@@ -1 +0,0 @@
-0.4.0

package/framework/v0.4.0/lib/cmd/bundle/copy.js

@@ -1,18 +0,0 @@
-/**
- * @module gina/lib/cmd/bundle/copy
- */
-/**
- * Copy and insall the source bundle into another existing project
- *
- * - throw error if project does not exist
- * - setup:
- *      * ~/.gina/ports.json
- *      * ~/.gina/portsReverse.json
- *      * update ports on /new/path/to/project/env.json
- *      * update infos on /new/path/to/project/manifest.json
- *      * No cleanup needed since it's only a copy !
- *
- * The main advantage you are gaining over a simple copy/paste is that gina is going to
- * write configuration/settings for you.
- *
- * */

package/framework/v0.4.0/lib/cmd/bundle/rename.js

@@ -1,7 +0,0 @@
-/**
- * @module gina/lib/cmd/bundle/rename
- */
-/**
- * Rename a given bundle
- * ! config, source & target project must be identical
- */

package/framework/v0.4.0/lib/cmd/bundle/status.js

@@ -1,6 +0,0 @@
-/**
- * @module gina/lib/cmd/bundle/status
- */
-/**
- * Created by martinlutheretouman on 2/5/15.
- */

package/framework/v0.4.0/lib/cmd/project/status.js

@@ -1,3 +0,0 @@
-/**
- * Created by martinlutheretouman on 2/5/15.
- */