gina 0.3.13-alpha.2 → 0.3.13

package/.playwright-mcp/page-2026-05-14T02-29-01-333Z.yml

@@ -0,0 +1,404 @@
+- generic [ref=e2]:
+  - region "Skip to main content":
+    - link "Skip to main content" [ref=e3] [cursor=pointer]:
+      - /url: "#__docusaurus_skipToContent_fallback"
+  - navigation "Main" [ref=e4]:
+    - generic [ref=e5]:
+      - generic [ref=e6]:
+        - link "Gina logo Gina" [ref=e7] [cursor=pointer]:
+          - /url: /docs/
+          - img "Gina logo" [ref=e9]
+          - generic [ref=e10]: Gina
+        - link "Docs" [ref=e11] [cursor=pointer]:
+          - /url: /docs/intro
+        - link "Tutorials" [ref=e12] [cursor=pointer]:
+          - /url: /docs/tutorials
+        - link "Templating" [ref=e13] [cursor=pointer]:
+          - /url: /docs/templating/
+        - link "Roadmap" [ref=e14] [cursor=pointer]:
+          - /url: /docs/roadmap
+      - generic [ref=e15]:
+        - generic [ref=e17]:
+          - link "Changelog" [ref=e18] [cursor=pointer]:
+            - /url: https://github.com/gina-io/gina/releases
+            - text: v0.3.12
+          - link "GitHub repository" [ref=e19] [cursor=pointer]:
+            - /url: https://github.com/gina-io/gina
+            - img [ref=e20]
+          - link "npm package (stable)" [ref=e22] [cursor=pointer]:
+            - /url: https://www.npmjs.com/package/gina/v/0.3.12
+            - img [ref=e23]
+        - generic "light mode" [ref=e26] [cursor=pointer]:
+          - checkbox "Switch between dark and light mode (currently light mode)" [disabled]
+          - generic [ref=e27]:
+            - generic [ref=e28]: ☾
+            - generic [ref=e29]: ☀
+        - textbox "Search" [ref=e32]
+  - generic [ref=e35]:
+    - complementary [ref=e36]:
+      - navigation "Docs sidebar" [ref=e39]:
+        - list [ref=e40]:
+          - listitem [ref=e41]:
+            - link "What is Gina?" [ref=e42] [cursor=pointer]:
+              - /url: /docs/intro
+              - img [ref=e44]
+              - generic "What is Gina?" [ref=e46]
+          - listitem [ref=e47]:
+            - generic [ref=e48]:
+              - link "Getting Started" [ref=e49] [cursor=pointer]:
+                - /url: /docs/getting-started
+                - img [ref=e51]
+                - generic "Getting Started" [ref=e56]
+              - button "Expand sidebar category 'Getting Started'" [ref=e57] [cursor=pointer]
+          - listitem [ref=e58]:
+            - generic [ref=e59]:
+              - link "Concepts" [ref=e60] [cursor=pointer]:
+                - /url: /docs/concepts
+                - img [ref=e62]
+                - generic "Concepts" [ref=e64]
+              - button "Expand sidebar category 'Concepts'" [ref=e65] [cursor=pointer]
+          - listitem [ref=e66]:
+            - generic [ref=e67]:
+              - link "Guides" [ref=e68] [cursor=pointer]:
+                - /url: /docs/guides
+                - img [ref=e70]
+                - generic "Guides" [ref=e73]
+              - button "Expand sidebar category 'Guides'" [ref=e74] [cursor=pointer]
+          - listitem [ref=e75]:
+            - generic [ref=e76]:
+              - link "CLI Reference" [ref=e77] [cursor=pointer]:
+                - /url: /docs/cli
+                - img [ref=e79]
+                - generic "CLI Reference" [ref=e81]
+              - button "Collapse sidebar category 'CLI Reference'" [expanded] [ref=e82] [cursor=pointer]
+            - list [ref=e83]:
+              - listitem [ref=e84]:
+                - link "bundle" [ref=e85] [cursor=pointer]:
+                  - /url: /docs/cli/cli-bundle
+                  - generic "bundle" [ref=e86]
+              - listitem [ref=e87]:
+                - link "project" [ref=e88] [cursor=pointer]:
+                  - /url: /docs/cli/cli-project
+                  - generic "project" [ref=e89]
+              - listitem [ref=e90]:
+                - link "framework" [ref=e91] [cursor=pointer]:
+                  - /url: /docs/cli/cli-framework
+                  - generic "framework" [ref=e92]
+              - listitem [ref=e93]:
+                - link "env" [ref=e94] [cursor=pointer]:
+                  - /url: /docs/cli/cli-env
+                  - generic "env" [ref=e95]
+              - listitem [ref=e96]:
+                - link "port" [ref=e97] [cursor=pointer]:
+                  - /url: /docs/cli/cli-port
+                  - generic "port" [ref=e98]
+              - listitem [ref=e99]:
+                - link "scope" [ref=e100] [cursor=pointer]:
+                  - /url: /docs/cli/cli-scope
+                  - generic "scope" [ref=e101]
+              - listitem [ref=e102]:
+                - link "view" [ref=e103] [cursor=pointer]:
+                  - /url: /docs/cli/cli-view
+                  - generic "view" [ref=e104]
+              - listitem [ref=e105]:
+                - link "cache" [ref=e106] [cursor=pointer]:
+                  - /url: /docs/cli/cli-cache
+                  - generic "cache" [ref=e107]
+              - listitem [ref=e108]:
+                - link "protocol" [ref=e109] [cursor=pointer]:
+                  - /url: /docs/cli/cli-protocol
+                  - generic "protocol" [ref=e110]
+              - listitem [ref=e111]:
+                - link "service" [ref=e112] [cursor=pointer]:
+                  - /url: /docs/cli/cli-service
+                  - generic "service" [ref=e113]
+              - listitem [ref=e114]:
+                - link "connector" [ref=e115] [cursor=pointer]:
+                  - /url: /docs/cli/cli-connector
+                  - generic "connector" [ref=e116]
+          - listitem [ref=e117]:
+            - generic [ref=e118]:
+              - link "Configuration Reference" [ref=e119] [cursor=pointer]:
+                - /url: /docs/reference/
+                - img [ref=e121]
+                - generic "Configuration Reference" [ref=e122]
+              - button "Expand sidebar category 'Configuration Reference'" [ref=e123] [cursor=pointer]
+          - listitem [ref=e124]:
+            - generic [ref=e125]:
+              - link "API Reference" [ref=e126] [cursor=pointer]:
+                - /url: /docs/api
+                - img [ref=e128]
+                - generic "API Reference" [ref=e131]
+              - button "Expand sidebar category 'API Reference'" [ref=e132] [cursor=pointer]
+          - listitem [ref=e133]:
+            - generic [ref=e134]:
+              - link "Globals" [ref=e135] [cursor=pointer]:
+                - /url: /docs/globals
+                - img [ref=e137]
+                - generic "Globals" [ref=e140]
+              - button "Expand sidebar category 'Globals'" [ref=e141] [cursor=pointer]
+          - listitem [ref=e142]:
+            - link "Security" [ref=e143] [cursor=pointer]:
+              - /url: /docs/security
+              - img [ref=e145]
+              - generic "Security" [ref=e147]
+          - listitem [ref=e148]:
+            - link "Migration Guide" [ref=e149] [cursor=pointer]:
+              - /url: /docs/migration
+              - img [ref=e151]
+              - generic "Migration Guide" [ref=e153]
+    - main [ref=e154]:
+      - generic [ref=e156]:
+        - generic [ref=e158]:
+          - article [ref=e159]:
+            - navigation "Breadcrumbs" [ref=e160]:
+              - list [ref=e161]:
+                - listitem [ref=e162]:
+                  - link "Home page" [ref=e163] [cursor=pointer]:
+                    - /url: /docs/
+                    - img [ref=e164]
+                - listitem [ref=e166]:
+                  - link "CLI Reference" [ref=e167] [cursor=pointer]:
+                    - /url: /docs/cli
+                - listitem [ref=e168]:
+                  - generic [ref=e169]: service
+            - generic [ref=e170]:
+              - heading "service" [level=1] [ref=e172]
+              - generic [ref=e173]:
+                - generic [ref=e174]:
+                  - generic [ref=e175]:
+                    - img [ref=e176]
+                    - text: 1 min read
+                  - generic [ref=e179]: Intermediate
+                - generic [ref=e180]:
+                  - generic [ref=e181]: Prerequisites
+                  - list [ref=e182]:
+                    - listitem [ref=e183]:
+                      - link "Gina installed globally" [ref=e184] [cursor=pointer]:
+                        - /url: /docs/getting-started/installation
+                    - listitem [ref=e185]:
+                      - link "CLI bundle reference" [ref=e186] [cursor=pointer]:
+                        - /url: /docs/cli/cli-bundle
+              - paragraph [ref=e187]:
+                - text: The
+                - code [ref=e188]: service
+                - text: command group lists
+                - strong [ref=e189]: framework-internal services
+                - text: — bundles that ship alongside gina and run as companion processes (currently
+                - code [ref=e190]: proxy
+                - text: and
+                - code [ref=e191]: inspector
+                - text: ). These services are registered under the reserved
+                - code [ref=e192]: "@gina"
+                - text: project.
+              - generic [ref=e193]:
+                - generic [ref=e194]:
+                  - img [ref=e196]
+                  - text: Gina-internal surface
+                - paragraph [ref=e199]:
+                  - code [ref=e200]: service:list
+                  - text: currently rejects any project other than
+                  - code [ref=e201]: "@gina"
+                  - text: . User-defined services are not a surface yet — use
+                  - link "bundle:list" [ref=e202] [cursor=pointer]:
+                    - /url: /docs/cli/cli-bundle#bundlelist
+                    - code [ref=e203]: bundle:list
+                  - text: for bundles in user projects.
+              - separator [ref=e204]
+              - heading "service:listDirect link to servicelist" [level=2] [ref=e205]:
+                - code [ref=e206]: service:list
+                - link "Direct link to servicelist" [ref=e207] [cursor=pointer]:
+                  - /url: "#servicelist"
+                  - text: "#"
+              - paragraph [ref=e208]:
+                - emphasis [ref=e209]: New in 0.3.7-alpha.2
+              - paragraph [ref=e210]: List framework-internal services with src-existence, preferred-port summary, and host-side running state.
+              - code [ref=e214]:
+                - generic [ref=e215]: gina service:list
+              - code [ref=e219]:
+                - generic [ref=e220]: gina service:list @gina
+              - paragraph [ref=e221]:
+                - strong [ref=e222]: Flags
+              - table [ref=e223]:
+                - rowgroup [ref=e224]:
+                  - row "Flag Description" [ref=e225]:
+                    - columnheader "Flag" [ref=e226]
+                    - columnheader "Description" [ref=e227]
+                - rowgroup [ref=e228]:
+                  - row "--format=json Emit a JSON payload instead of the human-readable text table" [ref=e229]:
+                    - cell "--format=json" [ref=e230]:
+                      - code [ref=e231]: "--format=json"
+                    - cell "Emit a JSON payload instead of the human-readable text table" [ref=e232]
+              - heading "OutputDirect link to Output" [level=3] [ref=e233]:
+                - text: Output
+                - link "Direct link to Output" [ref=e234] [cursor=pointer]:
+                  - /url: "#output"
+                  - text: "#"
+              - code [ref=e238]:
+                - generic [ref=e239]: "[ running ] inspector http/2.0 dev https 4208 pid 27007"
+                - generic [ref=e240]: "[ running ] proxy http/2.0 dev https 4210 pid 15346"
+              - list [ref=e241]:
+                - listitem [ref=e242]:
+                  - strong [ref=e243]:
+                    - code [ref=e244]: "[ running ]"
+                    - text: /
+                    - code [ref=e245]: "[ stopped ]"
+                    - text: /
+                    - code [ref=e246]: "[ ?! ]"
+                  - text: — running state (probed from
+                  - code [ref=e247]: ~/.gina/run/<service>@gina.pid
+                  - text: with
+                  - code [ref=e248]: process.kill(pid, 0)
+                  - text: ) or src-existence when the source directory is missing.
+                - listitem [ref=e249]:
+                  - strong [ref=e250]:
+                    - code [ref=e251]: http/2.0 dev https 4208
+                  - text: — preferred port. Read from
+                  - code [ref=e252]: ~/.gina/ports.reverse.json
+                  - text: ". Precedence:"
+                  - code [ref=e253]: http/2.0 https
+                  - text: →
+                  - code [ref=e254]: http/1.1 https
+                  - text: →
+                  - code [ref=e255]: http/1.1 http
+                  - text: ;
+                  - code [ref=e256]: dev
+                  - text: env is preferred when present, otherwise the first environment in the record. Services with no allocated port render as
+                  - code [ref=e257]: (no port)
+                  - text: .
+                - listitem [ref=e258]:
+                  - strong [ref=e259]:
+                    - code [ref=e260]: pid 27007
+                  - text: — process id when running.
+              - paragraph [ref=e261]:
+                - text: With
+                - code [ref=e262]: "--format=json"
+                - text: ", each service object carries:"
+              - code [ref=e266]:
+                - generic [ref=e267]: "{"
+                - generic [ref=e268]: "\"service\": \"inspector\","
+                - generic [ref=e269]: "\"path\": \"src/inspector\","
+                - generic [ref=e270]: "\"status\": \"ok\","
+                - generic [ref=e271]: "\"ports\": {"
+                - generic [ref=e272]: "\"dev\": { \"http/1.1\": { \"http\": 4200, \"https\": 4204 }, \"http/2.0\": { \"https\": 4208 } },"
+                - generic [ref=e273]: "\"prod\": { \"http/1.1\": { \"http\": 4201, \"https\": 4205 }, \"http/2.0\": { \"https\": 4209 } }"
+                - generic [ref=e274]: "},"
+                - generic [ref=e275]: "\"running\": true,"
+                - generic [ref=e276]: "\"pid\": 27007"
+                - generic [ref=e277]: "}"
+              - paragraph [ref=e278]:
+                - text: A missing or malformed
+                - code [ref=e279]: ports.reverse.json
+                - text: is tolerated — the command still renders with every service showing
+                - code [ref=e280]: (no port)
+                - text: /
+                - code [ref=e281]: "ports: null"
+                - text: . A stale pidfile (process exited) reports
+                - code [ref=e282]: (stopped)
+                - text: without being deleted; pidfile clean-up stays with
+                - link "bundle:stop" [ref=e283] [cursor=pointer]:
+                  - /url: /docs/cli/cli-bundle#bundlestop
+                  - code [ref=e284]: bundle:stop
+                - text: .
+              - generic [ref=e285]:
+                - generic [ref=e286]:
+                  - img [ref=e288]
+                  - text: Docker bundles
+                - paragraph [ref=e291]:
+                  - text: Services running inside a Docker container write their pidfile inside the container, not on the host
+                  - code [ref=e292]: ~/.gina/run/
+                  - text: directory. Running
+                  - code [ref=e293]: service:list
+                  - text: from a host shell will report them as
+                  - code [ref=e294]: (stopped)
+                  - text: even when the container is up — use
+                  - code [ref=e295]: docker ps
+                  - text: or
+                  - code [ref=e296]: docker exec <container> gina service:list
+                  - text: for the container-side view.
+              - separator [ref=e297]
+              - heading "service:helpDirect link to servicehelp" [level=2] [ref=e298]:
+                - code [ref=e299]: service:help
+                - link "Direct link to servicehelp" [ref=e300] [cursor=pointer]:
+                  - /url: "#servicehelp"
+                  - text: "#"
+              - paragraph [ref=e301]:
+                - text: Print the usage summary for the
+                - code [ref=e302]: service
+                - text: command group.
+              - code [ref=e306]:
+                - generic [ref=e307]: gina service:help
+              - code [ref=e311]:
+                - generic [ref=e312]: gina service
+            - generic [ref=e313]:
+              - generic [ref=e314]:
+                - generic [ref=e315]: Was this page helpful?
+                - generic [ref=e316]:
+                  - button "Yes, this was helpful" [ref=e317] [cursor=pointer]:
+                    - generic [ref=e318]: 👍
+                    - generic [ref=e319]: –
+                  - button "No, this was not helpful" [ref=e320] [cursor=pointer]:
+                    - generic [ref=e321]: 👎
+                    - generic [ref=e322]: –
+              - link "Edit this page" [ref=e326] [cursor=pointer]:
+                - /url: https://github.com/gina-io/docs/tree/main/docs/cli/service.md
+                - img [ref=e327]
+                - text: Edit this page
+          - navigation "Docs pages" [ref=e331]:
+            - link "Previous « protocol" [ref=e332] [cursor=pointer]:
+              - /url: /docs/cli/cli-protocol
+              - generic [ref=e333]: Previous
+              - generic [ref=e334]: « protocol
+            - link "Next connector »" [ref=e335] [cursor=pointer]:
+              - /url: /docs/cli/cli-connector
+              - generic [ref=e336]: Next
+              - generic [ref=e337]: connector »
+        - list [ref=e341]:
+          - listitem [ref=e342]:
+            - link "service:list" [ref=e343] [cursor=pointer]:
+              - /url: "#servicelist"
+              - code [ref=e344]: service:list
+            - list [ref=e345]:
+              - listitem [ref=e346]:
+                - link "Output" [ref=e347] [cursor=pointer]:
+                  - /url: "#output"
+          - listitem [ref=e348]:
+            - link "service:help" [ref=e349] [cursor=pointer]:
+              - /url: "#servicehelp"
+              - code [ref=e350]: service:help
+  - contentinfo [ref=e351]:
+    - generic [ref=e352]:
+      - generic [ref=e353]:
+        - generic [ref=e354]:
+          - generic [ref=e355]: Docs
+          - list [ref=e356]:
+            - listitem [ref=e357]:
+              - link "Getting Started" [ref=e358] [cursor=pointer]:
+                - /url: /docs/intro
+        - generic [ref=e359]:
+          - generic [ref=e360]: Community
+          - list [ref=e361]:
+            - listitem [ref=e362]:
+              - link "GitHub Issues(opens in new tab)" [ref=e363] [cursor=pointer]:
+                - /url: https://github.com/gina-io/gina/issues
+                - text: GitHub Issues
+                - img "(opens in new tab)" [ref=e364]
+            - listitem [ref=e366]:
+              - link "GitHub Discussions(opens in new tab)" [ref=e367] [cursor=pointer]:
+                - /url: https://github.com/gina-io/gina/discussions
+                - text: GitHub Discussions
+                - img "(opens in new tab)" [ref=e368]
+            - listitem [ref=e370]:
+              - link "Support Gina" [ref=e371] [cursor=pointer]:
+                - /url: /docs/support
+        - generic [ref=e372]:
+          - generic [ref=e373]: More
+          - list [ref=e374]:
+            - listitem [ref=e375]:
+              - link "npm(opens in new tab)" [ref=e376] [cursor=pointer]:
+                - /url: https://www.npmjs.com/package/gina
+                - text: npm
+                - img "(opens in new tab)" [ref=e377]
+      - generic [ref=e380]: Copyright © 2009-2026 Gina I/O.
+  - button "Collapse sidebar" [ref=e382] [cursor=pointer]:
+    - img [ref=e383]

package/CHANGELOG.md

@@ -6,6 +6,35 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.3.13 - 2026-05-14
+### Added
+* Released `0.3.13` — cumulative stable of the `0.3.13-alpha` cycle. Alpha-cycle headline tracks (detailed under `0.3.13-alpha.3` in the changelog): **`${secret:KEY}` config-placeholder resolver** (#SECRETS1) — `lib/secrets` substitutes `${secret:KEY}` placeholders embedded in bundle JSON configs (`settings.json`, `app.json`, `connectors.json`, `mcp.json`) from `process.env[KEY]` at config-load time, fail-closed on an unset/empty var; ships with a `settings.csrf.secret` slot for `gina.plugins.Csrf()` and `mcp.json` placeholder support for `gina bundle:mcp-start`. **Eval-safety campaign completed** (#M20–#M22) — validator nested-key rule construction refactored off `eval` (#M20); the four HTML event-callback `eval` sites and the conditional-binding evaluator fallback dropped (#M21a, #M21b); the Pattern B user-defined-validator `eval` documented as load-bearing public API with an invariant test (#M21c); the logger ↔ merge circular-require restructured so the three `eval(fs.readFileSync(...))` fallbacks are removed (#M22) — Phase 3c complete, one load-bearing framework `eval` remains by design. Plus the #M1 async-race retrofit follow-up (render-nunjucks terminal-exit closure nulling) and a `requireJSON` line-comment / URL-collision fix. The entries below are the post-alpha-cycle changes that complete the release.
+* Bundle scaffolding now includes a starter Progressive Web App setup. Running view:add adds a manifest.webmanifest and a cache-first service-worker stub (sw.js) to the bundle public directory, and the default HTML layout links the manifest, declares a theme colour, and registers the service worker. Add your own icon PNGs and edit the manifest to describe the app.
+* The Isaac HTTP/2 server now rate-limits rapid-reset stream floods. When a single connection opens more than maxStreamsPerSecond new streams within a rolling one-second window (default 200), the server sends a GOAWAY and closes that session — a targeted, application-level defense against CVE-2023-44487-style attacks on top of the OS-level fix in modern Node.js. Configurable via settings.json http2Options.maxStreamsPerSecond. The /_gina/info endpoint exposes a new rapidResetBlocked counter.
+### Changed
+* Bumped the @rhinostone/swig dependency floor from ^2.2.0 to ^2.3.0 in framework/v*/package.json. Version 2.3.0 drops yargs and terser from the published package production dependencies — CLI argument parsing is now a built-in zero-dependency parser, and terser (used only by swig compile --minify) moved to devDependencies and loads lazily. A library install of @rhinostone/swig now pulls in only @rhinostone/swig-core, so installing gina has a smaller transitive dependency tree. No template-engine API or behavior change; swigResolver DEFAULT_MIN stays at 2.0.0 since the framework does not depend on any new 2.3.0 API.
+### Removed
+* Removed two dormant plugin directories (`core/plugins/lib/file/` and `core/plugins/lib/intl/`) that had no consumers in any known bundle. Slightly smaller npm tarball; no functional change.
+### Fixed
+* Fixed a dev-mode hot-reload crash: refreshCore() overwrote the lib and plugins require.cache entries with their exports objects instead of Module instances, so the controller render delegates threw "Cannot read properties of undefined" after a hot reload.
+
+## 0.3.13-alpha.3 - 2026-05-14 (npm only — no git tag)
+### Added
+* `${secret:KEY}` placeholder syntax in bundle JSON configs. Substituted at getConfig() time from process.env[KEY]. Fails closed if the env var is unset or empty. Resolution happens once per config-load cycle (cached). Pluggable-backend support is reserved for a future iteration; only the env-var backend ships in this alpha.
+* `settings.json > csrf.secret` config slot in `gina.plugins.Csrf()` — flows through the `lib/secrets` resolver, so `${secret:KEY}` placeholders work for the Csrf HMAC secret. Precedence is `opts.secret` (test override) > `settings.csrf.secret` > `process.env.GINA_CSRF_SECRET` (back-compat); existing bundles that set `GINA_CSRF_SECRET` keep working unchanged.
+* `${secret:KEY}` placeholder support in `mcp.json` for `gina bundle:mcp-start`. The cmd handler now calls `lib/secrets` on the parsed manifest immediately after `requireJSON()`, so `server.authToken` (and any other future placeholder field in mcp.json) gets filled from `process.env[KEY]` before downstream readers pick it up. Existing bundles that set `process.env.GINA_MCP_AUTH_TOKEN` directly keep working unchanged — that fallback is the last step of the precedence chain.
+### Changed
+* Added terminal-exit closure nulling to render-nunjucks for early per-request memory release, matching render-swig pattern (#M1 retrofit follow-up).
+* Bundle scaffolding (project add / bundle add) now shows the `${secret:KEY}` placeholder pattern as the recommended shape for session and CSRF secrets. `core/template/conf/settings.json` documents the new `settings.csrf.secret` slot (placeholder-compatible) alongside the existing GINA_CSRF_SECRET env-var fallback; `core/template/boilerplate/bundle/index.js` shows `self.getConfig('session').secret` (with bundle/config/session.json holding a `${secret:SESSION_SECRET}` placeholder) as the recommended session-secret wiring, keeping the direct `process.env.SESSION_SECRET` shape as a back-compat note.
+### Fixed
+* `requireJSON` line-comment stripping no longer fails when a bundle config combines a URL string with a bare `//` line-comment separator. The previous `indexOf`-into-greedy-match pass collided on the URL `://` and silently skipped the real separator, leaving `JSON.parse` to throw `Expected double-quoted property name`. The pass is now per-line on the leftmost `//`, matching the prior heuristic without the substring collision.
+### Security
+* Replaced eval() in validator nested-key rule construction (Socket #SCS campaign cluster M20).
+* Removing eval() from 4 HTML event-callback sites in the browser bundle (events.js + validator/main.js). The function-call shape `data-gina-...-event-on-*="fn(args)"` is no longer supported — register the handler on window and use the bare-identifier shape `="fn"`; a deprecation warning is logged at runtime if a function-call shape is encountered. Clears 4 of the 9 remaining Socket `Uses eval` flag sites (#M21a).
+* Removing eval() from the conditional binding evaluator fallback in form-validator.js. Form `condition` strings that previously hit the eval escape-hatch now throw with an explicit message listing the four supported shapes (binary comparison `a OP b`, RegExp instance, boolean, /regex/flags literal). Regex-literal strings still pass through. Clears 1 of the 5 remaining Socket `Uses eval` flag sites (#M21b).
+* Documenting the Pattern B eval surface at form-validator.js (user-defined validator function bodies registered on `gina.forms.validators` from disk-loaded `bundle/validators/<name>/main.js` files at framework boot). The eval is load-bearing public API and stays — no behavior change. Adds an in-source trust-model comment block and pins the invariant with `test/lib/validator-scs1i.test.js` (zero writes to `gina.forms.validators` in framework source; zero request-time identifiers around the userValidator source chain). Closes the M21 cluster (#M21c).
+* Restructuring the logger ↔ merge circular-require so the eval fallbacks at lib/logger/src/main.js + the two logger containers are no longer needed and have been removed. Root cause was merge.js requiring `helpers/index.js` (the for-loop helper loader) at module-load to populate `JSON.clone`, which transitively required `lib/logger` via several helpers and produced a partial-module return under circular load. Fix swaps that for a direct require of `utils/prototypes.json_clone` (a 100-line standalone primitive with zero top-level requires) — same JSON.clone population, no circular trigger. Clears the final 3 server-side Socket `Uses eval` sites (#M22). Phase 3c complete: 1 live framework eval site remains (the load-bearing Pattern B at form-validator.js:1886 / #M21c trust model).
+
 ## 0.3.12 - 2026-05-12
 ### Changed
 * Bumped @rhinostone/swig dependency floor from ^2.0.1 to ^2.1.0 in framework/v*/package.json. Version 2.1.0 introduces a multi-flavor architecture splitting the runtime into a shared @rhinostone/swig-core package plus per-flavor frontends (@rhinostone/swig native syntax, @rhinostone/swig-twig Twig-syntax frontend); the native @rhinostone/swig package remains drop-in compatible with the @rhinostone/swig@1.x and 2.0.x API surface gina depends on (swig.compile, swig.setFilter, swig.setTag, swig.renderFile). swigResolver DEFAULT_MIN stays at 2.0.0 since the framework does not depend on any new 2.1.0-only API. Resolves the version-currency drift surfaced by 'npm view @rhinostone/swig version' returning 2.1.0 against the current ^2.0.1 floor.

package/README.md

@@ -22,7 +22,7 @@ Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope
 | ORM / entities | EventEmitter-based entity system; SQL files auto-wired to entity methods |
 | Connectors | Couchbase, MongoDB, ScyllaDB / Cassandra, MySQL, PostgreSQL, Redis, SQLite, AI (LLM) — loaded from project `node_modules` |
 | AI connector | Any LLM provider via named protocol (`anthropic://`, `openai://`, `ollama://`, …) |
-| Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) 2.2.0 — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` |
+| Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) 2.3.0 — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` |
 | Internationalisation | Per-bundle JSON catalogs, `t()` helper, swig + nunjucks `t` filter, CLDR plurals, ICU MessageFormat opt-in via `t.icu()` |
 | Observability | Built-in `/_gina/metrics` Prometheus endpoint (opt-in, IP-allowlisted) — Node.js process metrics + HTTP counter / duration histogram with cardinality-safe route labels |
 | Hot reload | WatcherService evicts `require.cache` only on file change — zero per-request overhead in dev |
@@ -39,6 +39,16 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
+## What's in 0.3.13
+
+- **`${secret:KEY}` placeholder substitution** (#SECRETS1) — bundle JSON configs (`settings.json`, `app.json`, `connectors.json`, `mcp.json`, …) can embed `${secret:KEY}` placeholders that the framework resolves from `process.env[KEY]` at config-load time, before the merged config reaches `getConfig()` or any plugin factory. Anchored to whole-string values; fails closed on an unset/empty var. `gina.plugins.Csrf()` reads `settings.csrf.secret` through it, and `gina bundle:mcp-start` resolves `mcp.json` placeholders such as `server.authToken`. Pluggable-backend interface reserved for a future iteration; only the `process.env` backend ships now.
+- **Progressive Web App scaffold** (#R6) — `gina view:add` now drops a `manifest.webmanifest` and a cache-first service-worker stub (`sw.js`) into the bundle's `public/` directory, and wires the manifest `<link>`, a `theme-color` `<meta>`, an apple-touch-icon `<link>`, and an inline service-worker registration into the default layout. Zero runtime dependency — static files plus layout tags.
+- **HTTP/2 rapid-reset rate limiter** (#H9) — the Isaac engine now bounds new-stream creation per session in a rolling one-second window; over `maxStreamsPerSecond` (default 200) it sends a `GOAWAY` and closes the session. An application-level layer over the OS-level CVE-2023-44487 mitigation in modern Node.js, complementing `maxSessionRejectedStreams` (which counts refused, not created, streams). Configurable via `settings.json` `http2Options.maxStreamsPerSecond`; `/_gina/info` exposes a `rapidResetBlocked` counter.
+- **Eval-safety campaign completed** (#M20–#M22) — the multi-release effort to remove `eval` / `new Function` call sites from the published tarball is finished. The validator plugin's `makeObjectFromArgs` was refactored to a segments-array path build; the HTML-event-callback evals and the conditional-binding fallback were dropped; and the logger's circular-require `eval(fs.readFileSync(...))` fallbacks were eliminated by fixing the `merge → helpers → logger` cycle at its source. The one remaining eval is a load-bearing public-API site (user-defined form validators), kept by design with a documented trust model and an invariant test.
+- **`@rhinostone/swig` floor bumped to `^2.3.0`** — `2.3.0` drops `yargs` and `terser` from the published package's production dependencies (CLI parsing is now a built-in zero-dependency parser; `terser` moved to `devDependencies`, loaded lazily), so a library install pulls in only `@rhinostone/swig-core` — a smaller transitive tree. No template-engine API or behaviour change.
+- **`requireJSON` comment / URL fix** — `requireJSON` no longer mis-parses JSON config files that combine a `//` line comment with a URL string value (`"key": "https://…"`); the comment-stripping pass is now per-line on the leftmost `//`, so comment-bearing configs with URLs load cleanly.
+- **Dev-mode hot-reload fix** — `refreshCore()` was rebuilding the `lib` / `plugins` `require.cache` entries with their exports objects instead of `Module` instances, crashing the controller render delegates with `Cannot read properties of undefined` after a hot reload; it now lets `require()` rebuild a proper `Module`. Also removed two dormant internal plugin directories (`core/plugins/lib/file/`, `core/plugins/lib/intl/`) with no known consumers — a slightly smaller npm tarball, no functional change.
+
 ## What's in 0.3.12
 
 - **Spec-correct `+` decoding in URL query strings and urlencoded bodies** — fixes two complementary parsers that didn't decode `+` to space per RFC 1866 / WHATWG URL. The Isaac engine's URL query-string parser had no `+` substitution at all in either of its two branches (multi-value `&` loop + single-key `=` no-`&` path); the body parser's `application/x-www-form-urlencoded` content-type test was inverted, leaving `+` literal in `req.post` / `req.put` / `req.patch` values. Both now correctly produce space. Express engine was already spec-correct via `qs` defaults. Closes #B17.

package/ROADMAP.md

@@ -23,7 +23,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q4 2026** | `0.3.8` ✅ | Patch: `npm install -g gina@latest` regression fix — `psl` + `@rhinostone/swig` promoted to top-level deps · install scripts decoupled from framework `lib` registry · helpers preload guarding `lib/logger` ↔ `framework/v*/helpers` circular dep |
 | **Q2 2026** | `0.3.9` ✅ | Consumer-feedback batch (11 framework patches): per-request middleware dispatch isolation · Couchbase 4.x JsonTranscoder · `length` filter null safety · `process.env` mirroring · 6 nunjucks render-pipeline patches (libRef fallback · namespace prefix drop · bundle filter wraps · top-level userData · `data.data` alias · ginaLoader placeholders) · `getAssets` mid-URL `{{ }}` strip-guard anchor |
 | **Q2 2026** | `0.3.10` ✅ | FormValidator HTML5 form-reassociation hardening trilogy (`HTMLFormControlsCollection`-based `bindForm` + `unbindForm` symmetry · radio mutual-exclusion + IDL/attribute reconciliation · `defaultChecked` cache for reset) · `X-Forwarded-Prefix` reverse-proxy path-prefix awareness |
-| **Q4 2026** | `0.4.0` | AI agents (MCP) · ScyllaDB connector · PWA scaffold · Advanced tutorial · Website redesign · Docs offline ZIP · Bun investigation · Couchbase v2 removal · HTTP/2 hardening · Trailer support · CLI Tier 2 (bundle/project status, rename, copy, protocol:remove, minions) |
+| **Q4 2026** | `0.4.0` | AI agents (MCP) · ScyllaDB connector · Advanced tutorial · Website redesign · Docs offline ZIP · Bun investigation · Couchbase v2 removal · Trailer support · CLI Tier 2 (bundle/project status, rename, copy, protocol:remove, minions) |
 | **Q1 2027** | `0.5.0` | ESM support · Template engine migration · Structured logging · Alt-Svc · HTTP/2 priorities · WebSocket over HTTP/2 · Inspector Production · CLI Tier 3 (project:move, framework:update, backup/restore, man pages) |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
 
@@ -37,7 +37,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | ✅ | **`watchers.json`** — First-class bundle config for file watchers. Declare watchers on config files with event-based notification (no polling). Foundation for the dev-mode hot-reload system. | `0.2.0` | 2026-03-29 |
 | ✅ | **i18n core** — Per-bundle message catalogs under `bundle/locales/<culture>.json` with a fallback chain (specific culture → base language → default). Server-side `t(key, [params], [culture])` global helper with parameter interpolation and CLDR pluralisation. Swig and Nunjucks filters with the same surface (`{{ "key"\|t }}`, `{{ "key"\|t({ name: x }) }}`). Per-request locale negotiation from URL prefix / cookie / `Accept-Language` / settings default. CLI: `gina i18n:scan` for missing-key coverage per culture, `i18n:add <culture>` to seed a new catalog, `i18n:export` / `i18n:import` for `.po` / `.csv` / `.json` round-trip with translators. Headless by design — the visual translation editor lands later as the first content feature in Beemaster (admin Phase 3). Runtime + filters + `req.culture` negotiation + full CLI all shipped on the `0.3.11-alpha` track. | `0.3.11-alpha` | 2026-05-08 |
 | ✅ | **i18n ICU MessageFormat** — Opt-in `t.icu(key, params, culture)` variant powered by `intl-messageformat`. Adds gender / select / nested combinators (`{count, plural, one {# item} other {# items}}`, `{gender, select, female {…} male {…} other {…}}`) on top of the i18n core. Existing `t()` shape unchanged — v1 catalogs continue to work. Covers grammars (Romance, Slavic) and select expressions the v1 `{name}` + plural-forms shape can't express. Exposed as `gna.t.icu()` (global), `self.t.icu()` (controller helper), and `tIcu` template filter (swig + nunjucks). Library loaded via dynamic `import()` from a module-level loader kicked off at bundle boot — sync API after first-call resolves. | `0.3.11-alpha` | 2026-05-08 |
-| 📋 | **PWA scaffold** — `gina bundle:add` drops `manifest.json`, a service worker stub (`sw.js`), and the required `<meta>` / `<link>` tags into the bundle boilerplate. Zero runtime dependency. Enables Gina apps to be installed on mobile as PWAs without additional tooling. | `0.4.0` | Q4 2026 |
+| ✅ | **PWA scaffold** — `gina view:add` drops a `manifest.webmanifest` and a cache-first service worker stub (`sw.js`) into the bundle's `public/` directory, and adds the manifest `<link>`, a `theme-color` `<meta>`, an apple-touch-icon `<link>`, and an inline service-worker registration script to the default HTML layout. Zero runtime dependency — static files plus layout tags. Enables Gina apps to be installed on mobile as PWAs without additional tooling. | `0.3.13` | 2026-05-14 |
 | ✅ | **Per-bundle framework version** — Declare `"gina_version": "0.1.8"` on any bundle entry in `manifest.json` to pin that bundle to a specific installed framework version. The socket server continues running its own version; only the spawned bundle process uses the declared version. Validated against the tracked version list in `main.json` before start. `--gina-version=X.Y.Z` flag on `bundle:start` provides the same override without touching config files. | `0.3.0` | 2026-03-31 |
 | ✅ | **PATCH method** — `req.patch` populated with the parsed request body (JSON or form-encoded). `req.body` aliases `req.patch`. URI params merged. `"method": "PATCH"` valid in `routing.json`. Use PATCH for partial updates (only sent fields change) vs PUT which replaces the full resource. | `0.3.0` | 2026-03-31 |
 | ✅ | **HEAD method** — `req.head` populated with query-string and URI params. Full controller action runs so all response headers are set correctly; body is suppressed before writing to the wire. Both `render()` and `renderJSON()` honour HEAD. Routes declared as `GET` automatically accept HEAD — no extra routing rule needed. | `0.3.0` | 2026-03-31 |
@@ -134,13 +134,13 @@ Four focused follow-up sessions to close the deferred gap left by the `0.3.7-alp
 
 ### Eval safety
 
-Complete the removal of `eval` / `new Function` call sites from the published tarball. Four tranches shipped across `0.3.7-alpha.4` / `0.3.7-alpha.5` cleared 13 of 24 catalogued sites; 2 more were removed by deleting orphaned source during the toolbar cleanup (15 of 24 addressed). The validator structural refactor cleared 3 more on `0.3.13-alpha.2` (18 of 24). Two clusters remain, each needing a focused session.
+Complete the removal of `eval` / `new Function` call sites from the published tarball. Four tranches shipped across `0.3.7-alpha.4` / `0.3.7-alpha.5` cleared 13 of 24 catalogued sites; 2 more were removed by deleting orphaned source during the toolbar cleanup (15 of 24 addressed). The validator structural refactor cleared 3 more on `0.3.13-alpha.2` (18 of 24). The two remaining clusters — the feature-intrinsic eval design pass and the logger circular-require refactor — completed the campaign in `0.3.13`. The single remaining eval is a load-bearing public-API site (user-defined form validators), kept by design with a documented trust model.
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | ✅ | **Validator structural refactor** — Refactored `makeObjectFromArgs` in the validator plugin: the previous string-accumulator path-build + runtime evaluation is replaced by a segments-array threaded through the recursion plus a local safe setter. Cleared 3 eval sites. +27 parity tests in `test/lib/validator-scs1f.test.js`. Browser bundle rebuilt. | `0.3.13-alpha.2` | 2026-05-13 |
-| 📋 | **Feature-intrinsic eval design pass** — 6 sites eval user-supplied JS by design (user-defined form validators, HTML event callbacks on form data attributes). Decision pass: safe-eval sandbox via `vm.Script`, pre-parse to a restricted AST, or formalise "accept and document" with an explicit trust assumption. Outcome may include dropping unused placeholder features. | `0.3.8` | Q1 2027 |
-| 📋 | **Logger circular-require refactor** — 3 load-bearing `eval(fs.readFileSync(...))` fallbacks in the logger work around a circular `merge → helpers → logger` require chain. Restructure the chain so the fallback is no longer needed. Clears the final 3 sites of the campaign. Regression risk touches every logger-consuming test. | `0.3.8` | Q1 2027 |
+| ✅ | **Feature-intrinsic eval design pass** — 6 sites that eval user-supplied JS by design, across 3 patterns (HTML event callbacks, user-defined form validators, conditional binding fallback). The design pass formalised the trust model; the coding slices dropped the HTML-event-callback evals and the conditional-binding fallback, and documented the user-defined-validator site as a load-bearing public API with an invariant test. | `0.3.13-alpha.3` | 2026-05-14 |
+| ✅ | **Logger circular-require refactor** — 3 load-bearing `eval(fs.readFileSync(...))` fallbacks in the logger worked around a circular `merge → helpers → logger` require chain. Fixed at the source of the cycle: `merge.js` now requires the json-clone primitive directly instead of going through the helpers loader, so the circular chain never fires and the 3 eval fallbacks are unreachable and removed. | `0.3.13` | 2026-05-14 |
 
 ---
 
@@ -156,6 +156,16 @@ Cross-site request forgery protection. Three-phase defense-in-depth plan aligned
 
 ---
 
+## Secrets & Configuration
+
+Secrets handling for bundle JSON configs without baking plaintext values into source. Pluggable-backend design with `process.env` as the default; the reserved API surface allows future Vault / SOPS / K8s Secrets backends to slot in without changing call sites or the placeholder syntax.
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| ✅ | **`${secret:KEY}` placeholder substitution** — `lib/secrets` resolves `${secret:KEY}` placeholders embedded in bundle JSON configs (`settings.json`, `app.json`, `connectors.json`, `mcp.json`, etc.) at config-load time. Anchored regex matches the entire string value only — mixed strings (`"prefix-${secret:K}-suffix"`) pass through unchanged. Default backend reads `process.env[KEY]`; pluggable-backend interface reserved for a future iteration. Fails closed (throws `Error('Secret resolution failed')`) when an env var is unset or empty; the error message intentionally omits the key name. Resolution is once per config-load cycle (in-place mutation). `WeakMap`-backed path tracking enables a future log-redaction wrapper at merged-conf print sites. Hooked inside `core/config.js::loadBundleConfig`, so downstream readers (`getConfig()`, plugin factories) see resolved values transparently. **Consumers shipped**: `gina.plugins.Csrf()` reads `settings.csrf.secret` (precedence `opts.secret` > `settings.csrf.secret` > `process.env.GINA_CSRF_SECRET` for back-compat); `gina bundle:mcp-start` re-runs the resolver on the parsed `mcp.json` immediately after `requireJSON()` so `server.authToken` and any future placeholder field gets filled before downstream readers; bundle scaffolding (`project:add` / `bundle:add`) recommends the placeholder shape in `core/template/conf/settings.json` and `core/template/boilerplate/bundle/index.js`. 33 tests in `test/core/config-secrets-resolver.test.js`. | `0.3.13-alpha` | 2026-05-13 |
+
+---
+
 ## Connectors
 
 New database connectors follow the same interface as the existing Couchbase connector: declared in `connectors.json`, acquired via `getConnection()`.
@@ -237,7 +247,7 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | ✅ | **103 Early Hints** — send `Link` preload headers as informational response before the final response | `0.3.0-alpha.1` | 2026-03-31 | `self.setEarlyHints(links)` on SuperController. HTTP/2: `stream.additionalHeaders({ ':status': 103 })`; HTTP/1.1: `res.writeEarlyHints()` (Node.js 18.11+). Silent no-op on unsupported runtimes. |
 | ✅ | **HTTP/2 session metrics** — expose active session count, stream count, GOAWAY and RST_STREAM totals via `/_gina/info` | `0.3.0-alpha.1` | 2026-04-01 | `server._h2Metrics` counter object instrumented via session event handlers; exposed under `"http2"` key in `/_gina/info` JSON. |
 | ✅ | **Configurable `maxConcurrentStreams` and `initialWindowSize`** — move from hardcoded to `settings.json` `http2Options` | `0.3.0-alpha.1` | 2026-04-05 | All four HTTP/2 server settings configurable: `maxConcurrentStreams` (256), `initialWindowSize` (655350), `maxSessionRejectedStreams` (100), `maxSessionInvalidFrames` (1000). Security guards (`maxHeaderListSize`, `enablePush`) remain hardcoded. |
-| 📋 | **Application-level rapid reset rate limiter** (CVE-2023-44487) — per-session stream creation counter | `0.4.0` | Q4 2026 | Node.js ≥ 20.12.1 has the OS-level fix. Add an application-level counter: if a session creates more than N streams per second, close with GOAWAY. Important for public-facing deployments. |
+| ✅ | **Application-level rapid reset rate limiter** (CVE-2023-44487) — per-session stream creation counter | `0.3.13` | 2026-05-14 | The Isaac HTTP/2 session handler counts new streams in a rolling 1s window per session; over `maxStreamsPerSecond` (default 200) it sends a GOAWAY and closes the session. More targeted than `maxSessionRejectedStreams` (which counts refused streams, not created ones). Configurable via `settings.json` `http2Options.maxStreamsPerSecond`; `/_gina/info` exposes a `rapidResetBlocked` counter. |
 | 📋 | **Trailer support** — `stream.sendTrailers()` + `waitForTrailers: true` | `0.4.0` | Q4 2026 | No trailer support today. Required for gRPC-style streaming (grpc-status trailer) and content integrity use cases. Opt-in: activated only when a controller calls `self.sendTrailers(fields)`. |
 | 📋 | **Alt-Svc header** — advertise HTTP/3 availability | `0.5.0` | Q1 2027 | Set `Alt-Svc: h3=":443"; ma=86400` response header to advertise HTTP/3 (QUIC) availability via a QUIC-capable reverse proxy (nginx, Caddy, Cloudflare). Gina does not need to implement QUIC — just announce it. Opt-in via `settings.server.json`. Native HTTP/3 is out of scope: Node.js has no stable QUIC API, and the standard deployment topology (Gina → proxy → client) already delivers HTTP/3 at the edge. |
 | 📋 | **RFC 9218 Extensible Priorities** — read `Priority: u=N, i` request header | `0.5.0` | Q1 2027 | Use the RFC 9218 priority header to order response writes for multiplexed API clients. Low value for typical HTML page loads; high value for parallel API requests with declared urgency. |

package/framework/v0.3.13/VERSION

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