npm - gina - Versions diffs - 0.3.7-alpha.2 → 0.3.7-alpha.3 - Mend

gina 0.3.7-alpha.2 → 0.3.7-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (392) hide show

package/.playwright-mcp/console-2026-04-22T21-42-03-731Z.log ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ [ 112ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ http://127.0.0.1:41724/_gina/assets/routing.json:0
2	+ [ 114ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ http://127.0.0.1:41724/favicon.ico:0

package/.playwright-mcp/page-2026-04-22T21-42-03-861Z.yml ADDED Viewed

@@ -0,0 +1,3 @@
+- generic [active] [ref=e1]:
+  - heading "gina PSL browser smoke" [level=1] [ref=e2]
+  - generic [ref=e3]: waiting…

package/.playwright-mcp/page-2026-04-22T21-44-40-373Z.yml ADDED Viewed

@@ -0,0 +1,3 @@
+- generic [active] [ref=e1]:
+  - heading "gina PSL browser smoke" [level=1] [ref=e2]
+  - generic [ref=e3]: Domain ready; psl loaded via RequireJS OK | input="example.com" expected="example.com" actual="example.com" OK | input="sub.example.com" expected="example.com" actual="example.com" OK | input="https://www.google.co.uk/blah" expected="google.co.uk" actual="google.co.uk" OK | input="https://my-bucket.s3.af-south-1.amazon.co.za/puppy.png" expected="amazon.co.za" actual="amazon.co.za" OK | input="Mac-mini.local" expected="Mac-mini.local" actual="Mac-mini.local" OK | input="frontend.myproject.beta.Mac-mini.local" expected="Mac-mini.local" actual="Mac-mini.local" OK | input="api.default.svc.cluster.local" expected="cluster.local" actual="cluster.local" OK | input="192.168.1.5" expected="192.168.1.5" actual="192.168.1.5" OK | input="localhost" expected="localhost" actual="localhost" OK | input="" expected="" actual="" OK | input="россия.xn--p1ai" expected="xn--h1alffa9f.xn--p1ai" actual="xn--h1alffa9f.xn--p1ai" ALL PASS

package/CHANGELOG.md CHANGED Viewed

@@ -6,6 +6,64 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
+## 0.3.7-alpha.3 - 2026-04-23 (npm only — no git tag)
+### Added
+* The nunjucks render path now registers Gina's built-in filter registry automatically. Bundles with `render.engine: "nunjucks"` get the same 7 filters as the swig path — `getUrl`, `getWebroot`, `length`, `nl2br`, `addHours`, `addDays`, `addYears` — with no manual `env.addFilter()` calls needed. Templates can use `{{ 'home' | getUrl }}`, `{{ body | nl2br | safe }}`, or date helpers out of the box. User-registered filters on top (`env.addFilter('upper', fn)`) coexist with the built-in registry. Closes the most user-visible gap left by the 0.3.7-alpha.2 nunjucks MVP.
+* Bundles with `render.engine: "nunjucks"` now get automatic asset injection — the same way swig bundles do. Stylesheets, scripts, external plugins, and the Gina loader script are placed into the rendered HTML without any manual `<link>` or `<script>` wiring in layouts. Templates can still opt in explicitly via `{{ page.view.stylesheets | safe }}` and `{{ page.view.scripts | safe }}` — when either is used, auto-injection is skipped for that slot so tags never appear twice. `javascriptsDeferEnabled` moves scripts to `<head>` instead of before `</body>`, and `javascriptsExcluded: "**"` suppresses the loader. XHR / popin responses (`isWithoutLayout`) ship only the common-gina assets, matching swig-side behaviour. Closes the biggest semantic gap left by the 0.3.7-alpha.2 nunjucks MVP.
+### Changed
+* Swapped lib/domain from a vendored MPL-2.0 Public Suffix List (`framework/v*/lib/domain/dist/*.dat`) to the MIT-licensed `psl@^1.15.0` npm package. The public API is preserved — `new Domain()` / `new Domain(cb)` + `getRootDomain(host).value` / `.isSLD` / `.isRegisteredTldOrSld` all behave the same on recognised domains. Under the hood, the wrapper delegates to `psl.parse()` and falls back to the hostname's last two labels for unknown suffixes (matches today's behaviour on `.local`, `.localdomain`, cluster-internal pseudo-TLDs). IPv4 literals (`192.168.1.5`), IPv6 literals (`[::1]`), and `undefined`/`null` inputs are now handled defensively rather than producing broken values or throwing. Browser-side, the psl UMD is vendored and exposed via RequireJS as `vendor/gina/psl`. Shrinks the published tarball by ~780 KB and removes the only copyleft-flagged content from Socket's scan.
+### Removed
+* Removed orphaned core/deps/optimist-0.6.1/ vendored dependency. optimist (X11 license, flagged by Socket) was vendored but never actually used by any framework code — bin/cli parses CLI arguments directly via process.argv. Its declared transitives (wordwrap, minimist) were never installed, so any attempt to require it would have thrown MODULE_NOT_FOUND. Removal shrinks the published tarball by ~140KB and ticks up Socket's License score.
+## 0.3.7-alpha.2 - 2026-04-22 (npm only — no git tag)
+### Added
+* Inspector reveal toggle — dev-mode `/_gina/reveal` JSON endpoint returns the unredacted `__ginaData` snapshot when the bundle scope is `local`; bundles running in beta/production/testing return 403 and never store a raw snapshot. The Inspector Data tab has a matching red-tinted Reveal toggle that calls the endpoint and replaces the redacted payload client-side. Persisted in `localStorage.__gina_inspector_reveal`; automatically disabled and cleared when the bundle scope flips away from local.
+* Explicit exports for `gna.js` globals (#M8 / #AI3) — every framework-injected helper is now also surfaced as a named property on `require('gina')` / `require('gina/gna')`. Context helpers (`setContext`, `getContext`, `joinContext`, `resetContext`, `getLib`, `whisper`, `define`, `getDefined`, `isWin32`), path helpers (`_`, `setPath`, `getPath`, `setPaths`, `getPaths`, `onCompleteCall`), model helpers (`getModel`, `getModelEntity`), JSON/Data/Text/Console/Task helpers (`requireJSON`, `encodeRFC5987ValueChars`, `formatDataFromString`, `__`, `log`, `run`) and env helpers (`getUserHome`, `getEnvVar`, `getEnvVars`, `setEnvVar`, `getProtected`, `filterArgs`, `getLogDir`, `getRunDir`, `getTmpDir`, `getBundleStartingArgv`, `getVendorsConfig`, `setVendorsConfig`, `defineDefault`, `parseTimeout`, `merge`) plus `ApiError` are now statically discoverable, with JSDoc on each entry so IDEs, static analysers and the upcoming `.d.ts` generator (#M9) can navigate to definitions. Runtime globals are unchanged — this is an additive export surface only.
+* Auto-generated `types/gna.d.ts` from JSDoc (#M9) — new `script/generate_gna_types.js` reads the `GLOBAL_EXPORTS` inventory from `framework/v*/test/unit/gna-exports.test.js` (locked in by #M8) and per-export JSDoc blocks on `framework/v*/core/gna.js`, then emits `types/gna.d.ts`. For each global it prefers `typeof globalThis.<name>` when declared in `types/globals.d.ts`, otherwise synthesizes a TypeScript function signature from `@param`/`@returns`. Zero non-core dependencies. Wired into two new npm scripts — `npm run types:gen` (regenerate) and `npm run types:check` (CI-style drift detection, exit code 1 on mismatch). A new unit test `framework/v*/test/unit/gna-types-drift.test.js` re-runs the generator in-memory and asserts the output matches the checked-in file, so `.d.ts` drift is caught on every test run. Side effect — the regenerated file now covers the 12 exports that the hand-written `gna.d.ts` was missing (`joinContext`, `encodeRFC5987ValueChars`, `formatDataFromString`, `__`, `log`, `getProtected`, `filterArgs`, `getBundleStartingArgv`, `getVendorsConfig`, `setVendorsConfig`, `defineDefault`, `merge`), closing the #M8 → #M9 loop.
+* `gina bundle:mcp <bundle> @<project>` — generates a Model Context Protocol (MCP) tool manifest from `routing.json` at `<bundle>/config/mcp.json` (override with `--output=<path>`). Targets MCP specification revision 2025-06-18: emits one Tool per (route × URL variant × HTTP method) combination with `name`, `title`, `description`, `inputSchema` (Draft-07, `type: "object"`, URL path params as required strings with `pattern`/`enum` from `requirements`), `annotations` (`readOnlyHint` for GET, `destructiveHint` for POST/PUT/DELETE), and `_meta` (`io.gina.*` prefix preserving `routeName`, `url`, `method`, `namespace`, `control`, `middleware`, `scopes`, `cache`, `bundle`, `hostname`, `requirements`, `_sample` for downstream dispatch). Framework-internal routes (`/_gina/*`), HEAD, and OPTIONS are skipped. Cross-bundle proxy routes outside the current emission are warned and skipped. Source-of-truth is `routing.json` directly — independent of `bundle:openapi`. No alias. No runtime MCP server is started (deferred to #AI8b). Ships alongside a new `lib/routing-introspect/` module that extracts the shared URL/method/requirement parsing used by both `bundle:openapi` and `bundle:mcp`, covered by 45 unit tests in `test/lib/routing-introspect.test.js`. #AI8
+* `gina bundle:mcp-start <bundle> @<project>` — runs a live Model Context Protocol server for a single bundle over stdio (MCP specification revision 2025-06-18, JSON-RPC 2.0 framing, newline-delimited UTF-8). Reads the static manifest written by `gina bundle:mcp` from `<bundle>/config/mcp.json` and dispatches incoming `tools/call` requests as real HTTP requests against the running bundle's configured port on localhost. Implements `initialize`, `ping`, `tools/list`, `tools/call`, `notifications/initialized`, and `notifications/cancelled`; unknown methods return `-32601` (METHOD_NOT_FOUND); argument validation failures return `-32602` (INVALID_PARAMS); tool execution failures (upstream 4xx/5xx, ECONNREFUSED, timeout) are returned as `{content, isError: true}` per MCP — never as JSON-RPC errors. Tool path parameters are substituted into the URL (`/invoice/:id` → `/invoice/42`); remaining arguments become the query string for GET/DELETE/HEAD or the JSON body for POST/PUT/PATCH. `application/json` and `application/problem+json` responses become `structuredContent` + a text block; non-JSON responses fall back to a text block. Default dispatch timeout is 30 seconds. Stdio discipline is enforced by an early intercept in `bin/cli`: when `bundle:mcp-start` is detected in argv, `process.stdout.write` is redirected to stderr and the real write is stashed on `process.__ginaMcpStdout` before any framework module is loaded — the MCP wire stays clean; framework logs, bootstrap noise, and `console.log` output go to stderr where MCP clients ignore them. The server warns on stderr if `routing.json` has been modified after `mcp.json` (stale manifest) and flags tools whose middleware list looks session-scoped (`auth`/`session`/`login`). Prerequisites — the bundle MUST be started (`gina bundle:start`) and a manifest generated (`gina bundle:mcp`) first. Ships with two new framework libraries — `lib/mcp-server/` (transport-agnostic JSON-RPC + lifecycle state machine) and `lib/mcp-dispatch/` (HTTP loopback dispatcher), covered by 80 unit tests across `test/lib/mcp-server.test.js`, `test/lib/mcp-dispatch.test.js`, and `test/bin/bundle-mcp-start.test.js`. #AI8 Phase 2a — Streamable HTTP transport deferred to a later phase.
+* `lib/mcp-dispatch` — concurrency cap on the HTTP loopback dispatcher. `createDispatcher({ maxInFlight })` rejects the (N+1)th concurrent `dispatch()` call with `{content, isError: true}` (never a JSON-RPC error) once the in-flight count reaches the cap; defaults to `DEFAULT_MAX_IN_FLIGHT = 16`. Early-exit paths (missing `_meta["io.gina.url"]`, unresolved path parameter, over-limit) do not consume a slot — only calls that actually issue an upstream HTTP request count against the budget. A new `getInFlightCount()` method is exposed on the dispatcher for ops instrumentation. Latent today in `bundle:mcp-start` because stdio is single-client; prevents pile-up behind a slow upstream once multiple MCP clients share one dispatcher via the Streamable HTTP transport (#AI8 Phase 2b).
+* `gina bundle:mcp-start --timeout-ms=<n>` — overrides the HTTP dispatch timeout for a single MCP server process. Also reads `mcp.json > server > timeoutMs` when the CLI flag is absent. Precedence: `--timeout-ms` > manifest > 30 000 ms default. Non-numeric / non-positive values at any layer fall through to the next layer with a stderr warning, so a malformed override cannot silently disable the timeout. The resolved value is surfaced in the startup info line (`Dispatch target: <url> (timeout: <n> ms)`) for operator visibility. The previous hardcoded 30 s default still applies when neither override is set.
+* Dual-mode Inspector statusbar link — the dev-mode statusbar now prefers the standalone Inspector SPA when `config/settings.json > inspector.url` is set on a bundle (e.g. `"inspector": {"url": "http://localhost:4200/inspector/"}`), opening it in a new tab with `?target=<this-origin+webroot>` pre-filled. When unset, the link falls back to the legacy embedded popup at `{webroot}/_gina/inspector/` with its persisted geometry — existing behaviour is unchanged. The resolved URL is exposed to the client shim via `window.__ginaData.gina.inspectorUrl`, injected by both `controller.render-swig.js` and `controller.render-json.js` so HTML and XHR-driven pages agree on the target. Cross-origin support for the standalone SPA is rounded out by adding `access-control-allow-origin: *` to the two remaining `/_gina/*` handlers that still lacked it — the Inspector SPA asset route (`/_gina/inspector/*`) and the log stream (`/_gina/logs`) — in both `server.isaac.js` and `server.js` so the SPA can pull CSS/JS/fonts and subscribe to the SSE logs from a different origin than the target bundle.
+* Dual-mode resolution for `gina inspector:open` — the command now picks the Inspector URL the same way the dev-mode statusbar does since `0.3.7-alpha.2`. Resolution order: (1) `--url=<url>` CLI override, (2) the bundle's `config/settings.json > inspector.url` (e.g. `"inspector": {"url": "http://localhost:4200/inspector/"}`), (3) the embedded popup at `<target>/_gina/inspector/` (legacy fallback, unchanged). In every case the target bundle origin is passed as `?target=<origin>` so the standalone SPA knows which bundle to drive. The `--url` flag is the escape hatch when the Inspector is reachable at an address not declared in the bundle config. When `--port` is used alone (no project/bundle context) and `--url` is not passed, the embedded path is kept — there is no config to read.
+* `gina inspector:open` now accepts a full `http(s)://` URL as the positional target — useful when bundles run on Docker or a remote environment while the Inspector SPA runs on the host (e.g. `gina inspector:open https://v3-local.example.com/api/`). The URL is used as the target origin directly; project and bundle resolution are skipped, mirroring the `--port` short-circuit. A new per-user fallback was also added to the Inspector URL resolution chain: `~/.gina/<shortVersion>/settings.json > inspector.url`. Set it once and every invocation without `--url=` uses the same standalone SPA origin. Full resolution order: (1) `--url=<url>`, (2) bundle `config/settings.json > inspector.url`, (3) global `~/.gina/<shortVersion>/settings.json > inspector.url`, (4) embedded popup at `<target>/_gina/inspector/`.
+* `gina service:list` — lists framework-internal services (bundles registered under `@gina`) with their name, preferred dev port, src-existence status, and current running state. Running state is probed from `~/.gina/run/<service>@gina.pid` combined with `process.kill(pid, 0)`; stale pidfiles report the service as stopped without being auto-deleted (clean-up stays with `bundle:stop`). Ports are read from `~/.gina/ports.reverse.json` and the preferred one picked by the `http/2.0 https` → `http/1.1 https` → `http/1.1 http` precedence (dev env first, then the first env present). Supports `--format=json` for scripting, and tolerates a missing or malformed `ports.reverse.json` without erroring. `@gina` is the only project accepted for now — `gina service:list @freelancer` is rejected with a clear message; user-defined services are not a surface yet. Ships with a new cmd group at `framework/v*/lib/cmd/service/` (`list.js`, `help.js`, `help.txt`) registered in the `bin/cli` offline allowlist, and 37 source-inspection unit tests in `test/lib/service-list.test.js`.
+* `gina connector:list` — lists connectors declared across a project's `shared/config/connectors.json` and every bundle's `config/connectors.json`, with driver install status, range and version-pin info. Three invocation modes: `gina connector:list` (every registered project), `gina connector:list @<project>` (one project, shared + all bundles), `gina connector:list <bundle> @<project>` (merged shared+bundle view that the bundle sees at runtime). Each row shows a status flag (`[ ok ]` installed or Node-builtin, `[ ?! ]` driver declared but not found in `<project>/node_modules/<driver>`, `[ ?? ]` unknown connector type or unrecognised `ai` protocol), the logical name, the resolved connector type, a source label (`[shared]`, `[<bundle>]`, `[<bundle> override]`), and driver details (`<npm>@<range>` + pin + installed version, or `run npm install <npm>` when missing, or `(built-in)` for `node:sqlite`). Driver resolution follows the framework's `peerDependencies`: `couchbase` → `couchbase`, `redis` → `ioredis`, `mysql` → `mysql2`, `postgresql` → `pg`, `mongodb` → `mongodb`, `scylladb` → `@scylladb/scylla-driver`, `sqlite` → built-in `node:sqlite`, `ai` → `@anthropic-ai/sdk` (for `anthropic://`) or `openai` (for `openai://`, `deepseek://`, `qwen://`, `groq://`, `mistral://`, `together://`, `ollama://`, `gemini://`, `xai://`, `perplexity://`). Shared and bundle-level overlay is key-level with bundle winning on conflicting keys, mirroring the runtime merge in `core/config.js`. When two bundles pin the same driver at different `version` values the command emits a trailing `[ !! ] driver \`<name>\` has conflicting \`version\` pins` line — npm resolves `node_modules/<driver>/` to a single version per project, so the first install wins. Supports `--format=json` for scripting with a stable `{project, bundle?, status, connectors: [{project, bundle, name, connector, source, driver, builtin, range, version, installed, installedVersion, note, unresolved}]}` shape. `connectors.json` and `manifest.json` files are parsed with `//` and `/* */` comment tolerance via `requireJSON`. Registered as an offline command — no framework socket required. Ships with a new cmd group at `framework/v*/lib/cmd/connector/` (`list.js`, `help.js`, `help.txt`, `arguments.json`) and 89 source-inspection unit tests in `test/lib/connector-list.test.js`. First of the #CN10 multi-session plan — subsequent sessions add `connector:add`, `connector:rm`, and `connector:migrate`.
+* `gina connector:add` — writes a connector entry to a project's `shared/config/connectors.json` or a bundle's `<bundle-src>/config/connectors.json`. Two invocation modes: `gina connector:add <name> @<project>` (writes to shared) and `gina connector:add <name> <bundle> @<project>` (writes to the bundle, resolved via `manifest.bundles[bundle].src`). Connector type is inferred from `<name>` when it matches one of the six allowed types (`couchbase`, `mysql`, `postgresql`, `sqlite`, `redis`, `ai`), or set explicitly via `--connector=<type>` (or the `--driver=<type>` synonym). Flags cover the common keys: `--host=`, `--connector-port=`, `--database=`, `--username=`, `--password=`, `--scope=` (one of `local`, `beta`, `production`, `testing`), and the AI-specific `--protocol=`, `--model=`, `--api-key=`, `--base-url=`. Driver version pinning via `--driver-version=<range>` writes a `version` field on the entry (new in the `schema/connectors.json`); when set, the printed install hint uses the pin (`npm install ioredis@"^5.0.0"`) instead of the framework's `peerDependencies` range. Preserves any `//` or `/* */` comment header above the first `{`; serialises the body with 4-space indentation; pins `$schema` at the top of the output with the canonical `https://gina.io/schema/connectors.json` URL; preserves existing key order and replaces an overwrite in place (not moved to the bottom). After writing, prints a one-line install hint — `Next: run `npm install <pkg>@"<range>"` inside your project root.` — using `@anthropic-ai/sdk` for `anthropic://` or `openai` for any other OpenAI-compatible AI protocol (`openai://`, `deepseek://`, `qwen://`, `groq://`, `mistral://`, `together://`, `ollama://`, `gemini://`, `xai://`, `perplexity://`). `sqlite` short-circuits to a `No install needed (Node >= 22.5.0 built-in node:sqlite)` note. Refuses to overwrite an existing entry without `--force`. Note on reserved flag names: the CLI uses `--connector-port=` (not `--port=`) because the framework reserves `--port=` for its own socket port, and `--driver-version=` (not `--version=`) because `--version=<value>` would be auto-mapped to `GINA_VERSION` and trigger a framework migration; the written JSON shape still uses `port` and `version` property names. Registered as an offline command — no framework socket required. Ships with 94 source-inspection unit tests in `test/lib/connector-add.test.js`. Second of the #CN10 multi-session plan — follow-ups are `connector:rm` and `connector:migrate` + framework-side auto-migrate hook.
+* `gina connector:rm` — removes a connector entry from a project's `shared/config/connectors.json` or a bundle's `<bundle-src>/config/connectors.json`. Two invocation modes mirror `connector:add`: `gina connector:rm <name> @<project>` (removes from shared) and `gina connector:rm <name> <bundle> @<project>` (removes from the bundle, resolved via `manifest.bundles[bundle].src`). `connector:remove` is accepted as an alias. Flags: `--dry-run` prints what would be removed without touching any file (always exits `0` — includes the sibling-usage warning and driver-retention hint); `--force` skips the project-level usage guard that otherwise refuses to remove a shared connector while any bundle still references it. Bundle-level removals always proceed and leave shared untouched. After removal, prints a driver-retention hint listing any sibling bundles (or shared) that still reference the same driver and a reminder that `gina does not uninstall npm packages`; sqlite is exempt (built-in `node:sqlite`). Attempting to remove from a bundle when the entry lives only in shared prints an "inherited from shared" hint pointing at the right scope. Preserves any `//` or `/* */` comment header above the first `{`; mid-body comments are lost on rewrite (same as `connector:add`). Registered as an offline command — no framework socket required. Ships with 81 source-inspection unit tests in `test/lib/connector-rm.test.js`. Third of the #CN10 multi-session plan — follow-up is `connector:migrate` + framework-side auto-migrate hook.
+* `gina connector:migrate` — lints every `connectors.json` in a project (or a single bundle's file) and, when `--fix` is passed, applies auto-fixable issues in place. Default mode is a read-only dry run — nothing is written without `--fix`. Two detection types today: `missing-schema` (top-level `$schema` key absent — auto-fixable, injects `"$schema": "https://gina.io/schema/connectors.json"` pinned at the top of the object while preserving the leading comment header and existing key order) and `bare-key-no-connector` (entry has no `connector` field and its key is not in the built-in enum `couchbase, mysql, postgresql, sqlite, redis, ai` — warn-only since the correct driver cannot be inferred; suggests the manual remediation via `gina connector:add <name> @<project> --connector=<type> --force`). Two invocation modes: `gina connector:migrate @<project>` scans shared + every bundle listed in `manifest.json`; `gina connector:migrate <bundle> @<project>` scans just the bundle's file. Flags: `--fix` applies auto-fixable issues; `--format=json` emits a machine-readable report with `{project, scope, bundle, fixApplied, files[]}` for CI / scripting. Registered as an offline command — no framework socket required. Idempotent — re-running after `--fix` is a clean no-op. Never modifies `core/config.js` and never runs at bundle boot: `connector:migrate` is explicit and opt-in, so a stale connectors.json cannot silently mutate in production. The real framework-side auto-migrate hook is deferred until `0.4.0` alongside `#CN8` (Couchbase SDK v2 removal) when a concrete old-shape → new-shape delta will justify touching the boot path. Ships with 87 source-inspection unit tests in `test/lib/connector-migrate.test.js`, a full write-path smoke test on a disposable sandbox (shared + two bundles, before/after assertions on `$schema` injection and key-order preservation), and a no-false-positive smoke on a real 7-bundle project. Fourth and final CLI session of the `#CN10` multi-session plan — `list`, `add`, `rm`, `migrate` now form a complete `connector:*` group.
+* `gina connector:add --install` — opt-in flag that runs the detected package manager's install command immediately after writing the connector entry. The package manager is detected by probing the project root for lockfiles in order: `bun.lockb` → `pnpm-lock.yaml` → `yarn.lock` → `package-lock.json`. npm is the fallback when none matches. The install range is resolved in three tiers, first match wins: (1) `--driver-version=` pin set on the call (also persisted under `entry.version`); (2) the project's `package.json` (`dependencies` preferred over `devDependencies`) — reusing an already-declared range keeps the lockfile stable across repeated installs; (3) the framework's `peerDependencies` declaration. The resolved tier is labelled in the pre-install log (`(source: entry | project | framework)`) so the decision is visible in the terminal. `sqlite` short-circuits to exit 0 with a "built-in, no install needed" note. AI connectors with missing or unknown `protocol` exit 1 (the entry is still persisted to disk so the user can fix the protocol and re-run `--install` separately, or install by hand). Spawn uses `child_process.spawnSync` with `stdio: 'inherit'` so the PM's native output streams through to the user's terminal; `ENOENT` (PM binary missing from PATH) returns exit code 127. By design there is no `--no-install` / `--yes` counterpart and no configuration that silently flips the default — `--install` is opt-in and locked by a negative-invariant source-inspection test. No changes to `core/config.js` or any framework boot path. Ships with 40 new source-inspection unit tests in `test/lib/connector-add.test.js` (135/135 pass; full connector suite 392/392) and a live smoke covering sqlite short-circuit, AI unknown-protocol exit 1, real `ioredis` install via npm fallback, subsequent install via lockfile-detected npm with a project-pinned range, and `--driver-version=^5.3.0` taking priority. Fifth and final CLI session of the `#CN10` multi-session plan — `list`, `add` (with `--install`), `rm`, `migrate` now form the complete `connector:*` group.
+* `lib/mcp-http` — Streamable HTTP transport primitives for the MCP server (spec revision 2025-06-18). New framework library that wraps an `mcp-server` instance with `createHttpTransport({ mcpServer, host, port, maxBodyBytes, onError })` — binds an `http.createServer` on the configured host / port (defaults to `127.0.0.1:0`, OS-assigned) and exposes `.start() / .stop() / .address()` for lifecycle control. POST accepts either a single JSON-RPC 2.0 frame or a batch (array); the `Accept` header picks the response shape — `application/json` returns a JSON frame (or JSON array for batch), `text/event-stream` returns one `event: message` per non-notification frame and closes the stream. Notifications-only POSTs return 202 Accepted with an empty body. Body size is capped at `DEFAULT_MAX_BODY_BYTES = 1 MiB` (override via `maxBodyBytes`); overflow replies 413 + JSON-RPC error frame. GET and DELETE return 405 + `Allow: POST` — v1 has no server-initiated streams (`tools/list_changed: false`, no sampling, no roots) so the spec-compliant answer is to refuse the method. OPTIONS returns a minimal preflight (full CORS Origin echo and `--auth-token` enforcement land in #AI8 Phase 2b Session 2). `Mcp-Session-Id` is generated via `crypto.randomUUID()` on the `initialize` response when the client did not provide one; client-supplied ids are echoed on every response including 202. `.stop()` sets `keepAliveTimeout = 1` and calls `closeIdleConnections()` so SIGTERM-driven shutdowns don't stall on idle keep-alive sockets. 34 unit tests in `test/lib/mcp-http.test.js`. Registered in the lib registry as `lib.mcpHttp` — not yet wired to `bundle:mcp-start`; the `--transport=http` CLI surface lands in #AI8 Phase 2b Session 3.
+* `lib/mcp-http` — security layer on the MCP Streamable HTTP transport. Two new options on `createHttpTransport`: `authToken` (enables static bearer authentication — requests must carry `Authorization: Bearer <token>` on every non-OPTIONS request) and `allowedOrigins` (extends the built-in loopback `Origin` allowlist; pass `["*"]` to disable the check entirely). The built-in allowlist accepts `http(s)://localhost`, `http(s)://127.0.0.1`, and `http(s)://[::1]` on any port so MCP Inspector and browser dev tools on random dev ports work without extra configuration. Ordering is OPTIONS → Origin gate → bearer gate → method routing: preflight bypasses auth (browsers cannot carry `Authorization` on a preflight), a disallowed `Origin` returns 403 without CORS echo (self-defeating otherwise), and a missing / invalid bearer returns 401 + `WWW-Authenticate: Bearer realm="MCP"` with CORS headers preserved so browser clients can read the error body. Bearer validation uses `crypto.timingSafeEqual` with a length-mismatch short-circuit (timingSafeEqual throws on unequal lengths), and the scheme prefix is parsed case-insensitively per RFC 6750 with trailing-whitespace tolerance on the presented token. Response CORS headers (`access-control-allow-origin` + `vary: Origin`, or `*` with no `vary` under wildcard) are now echoed on every POST / 202 / 405 / 413 / 500 path when the request carried an allowed Origin. OPTIONS preflight now lists `authorization` in `access-control-allow-headers` and honours the same Origin allowlist (allowed origin → echoed; disallowed → 204 with no `access-control-allow-origin`, so the browser blocks the actual request). 36 new unit tests cover the Origin allowlist (default loopback, IPv6 `[::1]`, extra origins, `*` wildcard, non-http schemes, malformed URLs), the bearer flow (missing / wrong scheme / wrong value / length-mismatch / trailing whitespace / case-insensitive scheme), CORS echo on every response path, OPTIONS preflight behaviour under each Origin policy, and input validation (empty / non-string `authToken` → no auth; non-array `allowedOrigins` → loopback-only default). Still not wired to `bundle:mcp-start` — CLI surface lands in #AI8 Phase 2b Session 3.
+* `gina bundle:mcp-start --transport=http` — Streamable HTTP transport for the live MCP server (MCP spec revision 2025-06-18). The existing stdio behaviour is preserved as the default; passing `--transport=http` wires the same dispatcher + mcp-server instance to `lib/mcp-http.createHttpTransport()` instead of `attachStdio()`. Six new CLI flags are whitelisted in `lib/cmd/bundle/arguments.json`: `--transport=stdio|http`, `--http-host=<host>`, `--http-port=<n>`, `--max-in-flight=<n>`, `--auth-token=<token>`, `--cors-origin=<comma-list>`. Every flag has a matching `mcp.json > server > <field>` manifest fallback (`transport`, `httpHost`, `httpPort`, `maxInFlight`, `authToken`, `allowedOrigins`) and, where sensible, an env-var layer (`GINA_HOST_V4` for the bind host, `GINA_MCP_AUTH_TOKEN` for the bearer token). Precedence at every resolver: CLI → manifest → env → default, with invalid values (non-numeric port, negative max-in-flight, out-of-range integer, unknown transport name) warning on stderr and falling through to the next tier. Bind host defaults to the framework-wide `host_v4` loopback convention (`127.0.0.1` by default, same mechanism as the MQ listener and CLI daemon socket) — opt into `0.0.0.0` is deliberate. HTTP port defaults to `0` (OS-assigned); the resolved port is logged to stderr on startup so wrappers can discover it. The startup info line now reads "MCP server listening on http://<host>:<port> (bearer auth: enabled)?. Dispatch target: <baseUrl> (timeout: <n> ms, maxInFlight: <n>). <N> tools exposed." On SIGTERM / SIGINT, `gracefulExit()` awaits `httpTransport.stop()` before `process.exit()` so in-flight responses drain cleanly. The `bin/cli` stdout intercept from Phase 2a is a no-op under HTTP mode (nothing writes to stdout in that path) and is therefore preserved unchanged. 27 new source-inspection tests in `test/bin/bundle-mcp-start.test.js` cover the whitelist additions, each resolver's precedence chain, the stdio|http branch in `startServer`, the HTTP transport wire-up shape, the bearer-auth log annotation, and the SIGTERM / `httpTransport.stop()` drain. `bundle:mcp-start` help.txt extended with the new flag table and default-security-posture notes. #AI8 Phase 2b Session 3.
+* `swig.useProject` — opt-in `config/settings.json` key that loads a project-pinned `@rhinostone/swig` (or `@rhinostone/swig-twig`) from the project's `node_modules/` in place of the framework's bundled copy. The override is honoured only when the project pin shares the same major as the framework floor and is at or above it (currently `^1.6.0`); a rejected override falls back to the framework copy and logs a one-line `[swig-resolver]` warning at bundle startup naming the reason (`version-mismatch`, `not-installed`, `malformed-package-json`, `missing-version`). Default is `false` — existing bundles see no behaviour change. A second key `swig.package` (enum `@rhinostone/swig` | `@rhinostone/swig-twig`, default `@rhinostone/swig`) selects which frontend package to resolve; the abandoned upstream `swig` name is never accepted. The resolved module is cached on `process.gina._swig` for the life of the bundle process, so `core/server.js` and `core/controller/controller.js` both see the same instance — including after dev-mode `refreshCoreDependencies()` evictions. Ships with `lib/swig-resolver/` (`resolve`, `load`, `get`, `getDecision`, `reset`) and 51 unit tests in `test/lib/swig-resolver.test.js`. Schema updated in `schema/settings.json`. Standalone-mode note: when multiple bundles share a process, the first one to call `load()` wins; a subsequent bundle requesting a different package is warned and keeps the already-loaded copy.
+* `lib/nunjucks-resolver` — primitive (N1) for project-installed nunjucks detection. Mirrors the `lib/swig-resolver` shape (resolve / load / get / getDecision / reset + dev-mode mtime hot-swap via `process.gina._nunjucks*`) with two deliberate differences: (1) no framework-bundled fallback — nunjucks is never declared in `framework/v*/package.json`, so `load()` throws an `Error` with `code: NUNJUCKS_NOT_INSTALLED` when the project has not installed the package, instead of silently returning a framework copy (bundles fail loud at startup rather than mid-render); (2) no version floor — the framework itself never calls any nunjucks API (rendering will live in `controller.render-nunjucks.js`, Gina code), so any version the user installs is accepted. Same dev-mode hot-swap mechanism: when `NODE_ENV_IS_DEV=true`, each `get()` call `fs.statSync`-probes `<projectPath>/node_modules/nunjucks/package.json` and, on mtime drift, evicts the cached module from `require.cache` and re-runs `load()` with the stashed options — `npm install nunjucks@<newer>` in a dev project takes effect on the next request without a bundle restart. Production short-circuits the probe. Ships with 38 unit tests in `test/lib/nunjucks-resolver.test.js` — resolve paths (installed / not-installed / malformed / missing-version / package-override), load success + cache + idempotency, load rejection with structured error + decision attached, get() throw-before-load contract, reset() fields, dev-mode mtime hot-swap including the uninstall-between-loads case that surfaces the error on refresh. Registered in `lib/index.js` as `lib.nunjucksResolver`. No wiring into `server.js` / `controller.js` yet — that lands in N2 alongside `controller.render-nunjucks.js` and the `render.engine` settings key.
+* `settings.json > render.engine = "nunjucks"` — opt-in nunjucks rendering for a bundle (N2 MVP). New `core/controller/controller.render-nunjucks.js` delegate file, mirroring `render-swig.js`'s module signature (`async function(userData, displayInspector, errOptions, deps)`). `controller.js` `self.render()` now reads `settings.render.engine` from the bundle config and dispatches to either `controller.render-swig` (default) or `controller.render-nunjucks`. The dev-mode cacheless branch evicts the nunjucks delegate from `require.cache` alongside the existing swig / v1 entries, wrapped in try/catch so older framework dirs without the nunjucks delegate still load. `server.js` gains a new `initNunjucksEngine(conf)` helper called alongside `initSwigEngine` when `hasViews(bundle)` is true — for bundles with `render.engine === "nunjucks"`, it calls `lib.nunjucksResolver.load(self.executionPath, settings.nunjucks)`, which throws `NUNJUCKS_NOT_INSTALLED` when the project has not `npm install`ed the package (bundle startup fails loud rather than deferring the error to the first render). `render-nunjucks.js` caches a `nunjucks.Environment` per template root on `process.gina._nunjucksEnvs` (invalidated when the underlying nunjucks module itself was hot-swapped via `process.gina._nunjucksEnvsOwner`), disables nunjucks's own template cache in dev mode (`noCache: process.env.NODE_ENV_IS_DEV === "true"`) so template edits take effect without restart, and wires the namespace-aware template path resolution from `render-swig.js:271-335` (the CVE-2023-25345 path-traversal guard is swig-specific legacy and remains in `render-swig.js` only). HEAD requests send headers only; HTTP/1.1 uses `res.writeHead() + res.end()`. Schema updates in `schema/settings.json`: new top-level `render` block (`engine` enum `["swig","nunjucks"]`, default `"swig"`) and `nunjucks` block (`package`, `autoescape`). **Explicitly deferred to follow-up sessions** — documented in `render-nunjucks.js`'s header comment so nothing is hidden: (1) Inspector `__gdPayload` injection, (2) HTTP/2 `stream.respond()` direct path and Early Hints 103, (3) static HTML cache writes, (4) `setResources` asset injection and `<gina>` layout placeholder resolution, (5) Gina `SwigFilters` equivalents — users register their own filters via `nunjucks.Environment.addFilter()`, (6) error-page template routing (the framework error template is currently swig-only, so thrown errors from nunjucks pages still render via the swig path). 36 source-inspection unit tests in `test/lib/render-engine-dispatch.test.js` — schema shape, controller.js dispatch logic, cacheless eviction try/catch, render-nunjucks module shape, Environment cache invalidation, HEAD handling, deferred-features comment presence, server.js init wiring, and negative invariants (framework `package.json` must never declare nunjucks; `render-nunjucks.js` must never `require("nunjucks")` directly; dispatch default must stay `"swig"`). Full suite 3273/3273.
+* `script/check_changie_entries.js` + pre-commit hook — self-enforces `llms.txt` lesson #66 (changie YAML body shapes). The script validates every staged `.changes/unreleased/*.yaml` entry: `kind:` must match the Added/Changed/Deprecated/Removed/Fixed/Security enum, `body:` must be single-quoted (`body: '...'`), double-quoted, or a block scalar (`>-` / `|-` / `>` / `|`), `time:` must be an ISO-8601 shape. Unquoted bodies are rejected unconditionally — even when today's content happens to be safe — because a later edit could introduce the ` #` silent-truncation or `:` mapping-values hazards. Single-quoted bodies are walked character-by-character to ensure every literal `'` is escaped as `''` and the scalar terminates before the `time:` key. Double-quoted bodies are checked for a closing unescaped `"`. Wired into `.githooks/pre-commit` alongside the existing local-tool-path leak guard (#S5) — runs only against staged changes files (`git diff --cached --diff-filter=AM`), so pre-existing unquoted entries on disk are grandfathered until someone edits them. The script is also callable standalone (`node script/check_changie_entries.js .changes/unreleased/*.yaml`) for CI use or on-demand audits. 25 unit tests in `test/lib/check-changie-entries.test.js` cover every safe body shape (single-quoted with escapes, double-quoted with escapes, folded `>-` and literal `|-` block scalars), all rejection patterns (unquoted with `:`, unquoted with ` #`, unquoted plain, unescaped `'` inside single-quoted, unterminated single-quoted, unterminated double-quoted), missing / empty / wrong-kind / wrong-field-order fields, and batch behaviour (every failing file reported in one pass; no-args → exit 0; missing-file-path → reported). Exits 1 with a per-file reason on any failure, exit 0 when clean. Full suite 3298/3298.
+### Changed
+* Inspector refresh button now performs a full soft refresh instead of only invalidating the data-diff cache. One click re-polls data, force-refetches the live index introspection (`/_gina/indexes`), refetches the unredacted `/_gina/reveal` snapshot when reveal mode is active, and reopens the passive `/_gina/agent` SSE stream when it has closed. Shift+click additionally reloads the inspected page via `window.opener.location.reload()`. The button's tooltip advertises the Shift+click modifier.
+* `gina bundle:list` — each bundle line now shows a preferred-port summary and host-side running state alongside the existing `[ ok ]` / `[ ?! ]` src-existence indicator. Preferred port is read from `~/.gina/ports.reverse.json` by the `http/2.0 https` → `http/1.1 https` → `http/1.1 http` precedence (dev env first, then the first env present); bundles with no allocated port render as `(no port)`. Running state is derived from `~/.gina/run/<bundle>@<project>.pid` + `process.kill(pid, 0)`; a stale pidfile (process gone) reports the bundle as stopped without deleting the file (clean-up stays with `bundle:stop`). Text output gains a padded bundle-name column, the port summary, and a `(running, pid N)` or `(stopped)` suffix per bundle; `--format=json` output gains `ports: object|null`, `running: boolean`, and `pid: number|null` fields on each bundle object. A missing or malformed `ports.reverse.json` is tolerated — the command still renders with all bundles showing `(no port)`. Caveat: bundles running inside a Docker container do not write a pidfile to the host `~/.gina/run/` directory, so they will report as stopped from a host shell even when the container is up — use `docker ps` for the container-side view.
+* `swig.useProject` — dev-mode hot-swap via mtime check. When `NODE_ENV_IS_DEV=true` and a bundle has opted in to `swig.useProject: true`, every call to `lib.swigResolver.get()` (which runs on every HTTP request via `controller.js` re-require under `refreshCoreDependencies()`) `fs.statSync`-probes the project's `<projectPath>/node_modules/<pkg>/package.json` and compares the `mtimeMs` against the value cached at the last `load()`. Identical → return the cached swig instance (near-zero cost: one `fs.stat`). Different (or the file appeared / disappeared) → evict the old project copy from `require.cache`, clear the in-process cache (`process.gina._swig` / `_swigDecision` / `_swigPackage`), and re-run `load()` with the original options so the next access picks up the new version. Use case: `npm install @rhinostone/swig@<newer>` in a project while a dev bundle is running now takes effect on the next request without a bundle restart. Production bundles (`NODE_ENV_IS_DEV` not `true`) short-circuit the mtime probe and keep the load-once semantics. Downgrades below the framework floor or wrong-major upgrades re-enter the same safety gates as the initial `load()` — the refreshed decision falls back to the framework copy with the usual `[swig-resolver]` warning. `reset()` now clears the full cache (adds `_swigOptions`, `_swigProjectPath`, `_swigMtime` to the fields wiped). 7 new unit tests in `test/lib/swig-resolver.test.js` (58 total) cover the production no-op, unchanged-mtime short-circuit, mtime-triggered reload, toggle-off and missing-projectPath short-circuits, fresh-get without prior `load()`, and version-drift-below-floor fallback. Test fixtures use a helper-local monotonic mtime counter (`Math.max(prev, Date.now(), lastMtime) + 1000`) to guarantee strict mtime progression across successive calls — `Date.now()` millisecond granularity would otherwise collide when two calls fire within the same wall-clock millisecond. `ROOT` is realpath-normalised inside `before()` because macOS `os.tmpdir()` returns `/var/folders/...` while Node's `require.cache` keys use the realpath `/private/var/folders/...`.
+* `controller.render-nunjucks.js` — Inspector `__gdPayload` injection shipped (closes N2 deferred item #1). `injectInspectorScripts(html, data, self, local, displayInspector)` builds the same redacted payload shape as `render-swig.js:1041-1128` (two `JSON.parse(JSON.stringify(data.page))` clones into `__gdGina` / `__gdUser`, `view.scripts`/`view.stylesheets` scrubbed on both, `inspectorRedact.getConfig(local.options.conf)` for pattern config, `environment.scope` + `inspectorUrl` attached to the gina clone, `JSON.parse(JSON.stringify(...))` snapshot gated on `process.env.NODE_SCOPE === 'local'` before the redact pass, then `inspectorRedact.redact({compiledPatterns, replacement})`), serialises to `<script>window.__ginaData = ...</script>` with `</script>` → `<\/script>` and `<!--` → `<\!--` escapes matching swig at lines 1096-1097, and injects alongside a `<script>window.__ginaLogs</script>` console-hook script before the first `</body>` via case-insensitive regex replace. Gated on `displayInspector === false` → never; `displayInspector === true` → always; otherwise `self.isCacheless()` (dev-mode default, same as swig). Side effects: stashes redacted payload on `self.serverInstance._lastGinaData` (consumed by engine.io push + `/_gina/agent` SSE), stashes unredacted on `serverInstance._lastGinaDataUnredacted` when scope is local (null otherwise so `/_gina/reveal` has nothing to leak outside dev), and emits `process.emit('inspector#data', __gdPayload)`. The injection call is wrapped in try/catch in the render function body so an Inspector-side bug can never break the actual page render — it falls through to sending the un-injected HTML with a `[render-nunjucks] inspector injection skipped: ...` console warning. **Still deferred within the Inspector port:** (a) `statusbar.html` inclusion (the swig template uses `{% include %}` with swig-specific syntax; nunjucks-compatible version needed), (b) `data.page.flow` pipeline from `local._timeline` (render-swig.js:986-1040 shape; belongs in a shared helper before porting), (c) `data.page.queries` pipeline from `local._queryLog`. 18 new source-inspection tests in `test/lib/render-engine-dispatch.test.js` §05b — imports, helper declaration, both gates (`displayInspector` + `isCacheless`), `</body>` guard, payload construction, redact pipeline, unredacted-scope gate, `</script>`/`<!--` escapes, script tag text, console-hook script, serverInstance stashes, event emit, regex replace injection site, try/catch wrapping in the main render body, plus two "documentation" tests that lock in the within-Inspector deferred-features comment. Full suite 3316/3316. render-nunjucks.js header block updated to strike through the shipped deferred item and expand the remaining within-port deferred list.
+* `controller.render-nunjucks.js` — HTTP/2 `stream.respond()` direct path shipped (closes N2 deferred item #2). `sendHtmlResponse` now implements the four-way branch documented in `the internal architecture docs §7b` and used by `render-swig.js:877-927`: (1) HEAD + HTTP/2 stream → `stream.respond({content-type, content-length, :status, ...merged})` + `stream.end()` with no body; (2) HEAD + HTTP/1.1 → `res.setHeader(content-length)` + `res.writeHead()` + `res.end()`; (3) body + HTTP/2 stream → `stream.respond({content-type, :status, ...merged})` + `stream.end(html)`; (4) body + HTTP/1.1 → `res.writeHead()` + `res.end(html)`. Both HTTP/2 branches guard against `stream.destroyed || stream.closed` (client disconnected before the async render callback completed — without the guard, `stream.respond()` throws `ERR_HTTP2_INVALID_STREAM`). Both HTTP/2 branches merge pipeline-set headers via `local.res.getHeaders()` because `stream.respond()` on the raw HTTP/2 stream does NOT include headers set via `response.setHeader()` — CORS, cache-control, cookies set earlier in the pipeline would otherwise be silently dropped on HTTP/2 responses. `local.res.headersSent = true` is flagged after successful `stream.respond()` to signal the HTTP/1.1 compat layer that the response was sent directly. Still deferred within the HTTP/2 track: Early Hints 103 auto-send from accumulated `h2Links` — that fires in `controller.js this.render()` before the delegate is called, so it's a controller-level change rather than a render-nunjucks change. 10 new source-inspection tests in `test/lib/render-engine-dispatch.test.js` §05a covering each of the four branches, the stream-destroyed guard (asserted to appear at least twice for both HEAD and body paths), the pipeline-header merge (getHeaders() called at least twice), the headersSent flag (set at least twice), and the HTTP/1.1 fallback patterns. Full suite 3326/3326.
+* `controller.render-nunjucks.js` — error-page template routing shipped (closes the remaining "framework error template is swig-only" gap for nunjucks bundles). When a bundle has opted into `render.engine = "nunjucks"` and defines custom error templates under `templates/html/errors/<code>.html`, `controller.js renderCustomError()` sets `errOptions.file` to the absolute path of the matching error file from `bundleConf.content.templates._common.errorFiles[code]`. The render-nunjucks delegate now detects `localOptions.isRenderingCustomError === true` and branches: instead of going through `resolveTemplatePath` + `FileSystemLoader.render()` (the loader rejects absolute paths and cannot reach shared-path error templates that live outside the bundle template root), it reads the file with `fs.readFileSync(localOptions.file, 'utf8')` and renders the contents with `env.renderString(source, data)`. Every failure mode in the branch — absent path, missing file, read error, renderString error — falls back to a minimal inline HTML body served through `sendHtmlResponse`, never recursing via `self.throwError`. Recursion would re-enter the same branch and could loop infinitely; the inline fallback guarantees the client always gets a well-formed response. Defensive `localOptions.isRenderingCustomError = false` reset after render mirrors `render-swig.js` lines 804 and 1434 — prevents a downstream render that reuses the same `localOptions` reference from re-entering the branch. The shared `getEnvironment(nunjucks, templateRoot, ...)` call is now hoisted above the branch so both the custom-error path (uses `env.renderString`) and the normal path (uses `env.render`) reuse the same cached `nunjucks.Environment`. 14 new source-inspection tests in `test/lib/render-engine-dispatch.test.js` §05c — branch presence and ordering relative to `resolveTemplatePath`, `fs.readFileSync` on `localOptions.file`, `env.renderString(_errSource, data)` usage, missing-file fallback, read-error fallback, renderString-error fallback, the no-recursion negative invariant (`self.throwError` must never appear inside the branch body), flag reset after render, inline-HTML status-code derivation, `getEnvironment` ordering, normal-path regression guard (`env.render(templateRel, data)` still present), template-existence pre-flight guard, and the top-of-file header "shipped" lock. Full suite 3326 → 3340. Deferred-feature list in the render-nunjucks.js header block, `the internal architecture docs` §5 + §8, and `llms.txt` #67 all updated to mark the item as shipped.
+### Removed
+* Removed the unused vendored swig-client browser bundle (core/deps/swig-client/). The client-side Swig bundle is produced at build time from @rhinostone/swig (Phase 7) — the vendored copy had zero runtime or build-time references.
+### Fixed
+* Inspector payload redactor no longer false-positively redacts non-secret identifiers that happen to contain secret substrings (e.g. `companyName`, `lastCompanyUsedId`, `passportRequired`). The key matcher now tokenizes on camelCase and punctuation boundaries and compares anchored tokens, so only genuine secret-named fields are redacted.
+* Inspector Reveal toggle now reliably shows the full HTML page payload instead of tiny session data from background JSON polls. The unredacted snapshot is only written by HTML renders — JSON polling endpoints no longer clobber the slot between page load and click.
+* Inspector Reveal toggle now routes to the correct bundle in proxy-routed multi-bundle setups. `toggleReveal()` derives the `/_gina/reveal` URL from the opener window's pathname (or the standalone `?target=` param) so the request hits the bundle that rendered the current page, not the front proxy's default bundle.
+* Bundle startup no longer crashes with `EINVAL: invalid argument, readlink` when loading config files in dev mode. The `require.cache` eviction calls in `config.js` `loadWithTemplate` are now wrapped in try/catch — `requireJSON` reads config via `fs.readFileSync` and evicts its own cache, so filesystem races (observed on OrbStack/Docker bind mounts after the bundles symlink is re-created) are non-fatal.
+* Bundle no longer crashes with an uncaught `ECONNREFUSED` when an HTTP/2 client session fails to connect. The `client.on('error', ...)` listener in `handleHTTP2ClientRequest` had a property-access chain (`getContext('gina').ports[options.protocol][options.scheme.replace(...)][options.port]`) that threw `TypeError` when the caller passed a bare hostname (undefined `options.protocol`/`options.scheme`). A throw from inside an `'error'` listener becomes an `uncaughtException` and terminates the process. The whole listener body is now wrapped in try/catch, the port-enhancement lookup safe-navigates every key, and `proc.js` `uncaughtException` handler now filters `ECONNREFUSED` originating from TCP connect frames (matching the existing `ECONNRESET` behaviour).
+* Inspector tab content now refreshes automatically when the opener page navigates. The client-side log poller (`pollLogs` in `inspector.js`) tracked `logsOff` against the opener's `__ginaLogs` array but never detected that the array itself is replaced on navigation — the new page's `statusbar.html` inline script re-runs and installs a fresh empty array, so the old `logsOff` offset would be larger than the new array length and the guard `src.length <= logsOff` returned early forever. New `_lastLogsRef` holds the last-polled array reference; when it changes (or the array length shrinks below the offset), `logsOff` is reset to 0 so the new page's entries are picked up on the next poll cycle.
+* Detached daemon processes no longer spin at 100% CPU when their launching CLI exits and leaves an orphaned stdio pipe. Writing to the dead pipe triggered `EPIPE`, which escalated to `uncaughtException`; the existing handler then wrote the error back to the same dead stdout, producing another `EPIPE` — an infinite loop. `proc.js` now installs silent `error` listeners on `proc.stdout`/`proc.stderr` at init, guards the uncaughtException EPIPE branch with a re-entry flag, and wraps the diagnostic `stdout.write()` calls in `try/catch` so a subsequent write failure is swallowed instead of re-thrown.
+* `gina framework:init` now re-heals project fields that have been saved as `null` in `projects.json`. The integrity loop in `checkIfProjects` used `typeof(project[prop]) != 'undefined'` to decide whether a field needed refreshing from `main.json`; because `typeof null === 'object'`, a field that had been written as `null` in a previous run (for example because its per-release entry was not yet defined) was permanently skipped. The guard now also requires `project[prop] !== null`, so `def_scope`, `local_scope`, `production_scope`, `dev_env` and similar namespaced fields recover on the next framework start.
+* `gina bundle:start` no longer hangs indefinitely when the resolved bundle entry point does not exist on disk. The `isRealApp` callback in `lib/cmd/bundle/start.js` used to log the error via `terminal.error()` and then return without closing the CLI socket or calling `end()` — the connected `gina` CLI would wait forever for output that could not arrive. The error branch now mirrors the sibling `nodeModulesErr` path: `opt.msg` is set to the error message and `end(opt, cmd, isBulkStart, bundleIndex, true)` is called, so the CLI receives the error and the process exits cleanly.
+* Inspector popup now stays in sync during SPA (pushState/XHR) navigation inside the inspected page. Opener polling alone could not pick up SPA renders because those paths do not rewrite `window.__ginaData`. The Inspector now opens a parallel `/_gina/agent` SSE subscription alongside the existing opener source and receives pushed `data`/`log` frames from `render-json.js` whenever `process.gina._inspectorActive` is true. Multi-bundle proxy setups are handled by deriving the stream URL from the opener pathname. Manual refresh after each page change is no longer required.
+* `gina bundle:openapi` no longer crashes on `routing.json` files that contain `//` or `/* */` comments. The command used plain `require(routingPath)` which hands the file to Node's JSON loader, and that loader throws `SyntaxError` on any comment — including the `// bundle needs to be restarted on changes !!` header that real `routing.json` files routinely carry. Swapped to `requireJSON`, which strips comments before parsing. The new `bundle:mcp` command already used `requireJSON`; this aligns `bundle:openapi` with it.
+* `gina project:add @<name> --path=<dir>` no longer hangs indefinitely when the target directory already contains a `package.json`. The existing-file branch now merges the existing package with the framework template and exits cleanly.
+* CLI argument parsing no longer silently truncates `--<key>=<value>` flags whose value contains a literal `=` character. Both entry points in the argv pipeline — `utils/helper.js::filterArgs` (populates `process.gina.GINA_*`) and `lib/cmd/helper.js::getParams` (populates `cmd.params[<key>]`) — previously used `.split(/=/)` with no limit, chopping the value at every `=`. Real-world values affected: `--driver-version=">=5.3.0 <6.0.0"` (truncated to `>`), `--password=foo=bar` (truncated to `foo`), `--api-key=sk-=abc=` (truncated to `sk-`). Fix is an `indexOf('=')`-based substring that splits on the first `=` only; everything after is kept verbatim. Discovered during the `connector:add --install` smoke test (CN10 Session 5) when a semver range with a leading `>=` was silently chopped. Covered by 13 unit tests in `test/lib/cli-arg-parsing.test.js` (source-inspection on both sites + behavioural checks against `>=X.Y.Z`, caret ranges, multi-`=` passwords, base64-ish api keys, empty values, and flag-only tokens). Full suite 3044/3044.
 ## 0.3.6 - 2026-04-16
 ### Changed
 * syncDocs now regenerates the docs-site package-lock.json after bumping devDependencies.gina — prevents CI / Vercel / Worker deploy failures on every stable release.

package/ROADMAP.md CHANGED Viewed

@@ -108,10 +108,21 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | 📋 | **ESM compatibility layer** — Dual CJS/ESM entry points via `"exports"` in `package.json`. Framework internals stay CJS; public API gets ESM re-exports. | `0.5.0` | Q1 2027 |
-| 🚧 | **Pluggable template engine** — **Partially shipped in `0.3.7`**: opt-in `render.engine = "nunjucks"` dispatch per bundle. The project installs `nunjucks` itself (no framework dep); Gina loads it via `lib/nunjucks-resolver` and routes through `controller.render-nunjucks.js`. Swig remains the default, runs unchanged. Inspector dev payload and HTTP/2 `stream.respond()` direct path both shipped in `0.3.7` follow-ups. **Remaining `0.5.0` scope**: feature parity with render-swig (Early Hints 103 auto-send, static HTML cache, `setResources` / asset cataloguing, error-page template routing, within-Inspector `statusbar.html` include + flow/queries pipelines); per-template-extension dispatch so a single bundle can mix engines (`.swig` / `.njk`); optional auto-detect on `.njk` presence. Breaking syntax differences (`{% parent %}` → `{{ super() }}`, filter renames, `autoescape` default, `date` format strings, no `{% spaceless %}`) are nunjucks's own — Gina doesn't paper over them. | `0.5.0` | Q1 2027 |
+| 🚧 | **Pluggable template engine** — **Partially shipped in `0.3.7`**: opt-in `render.engine = "nunjucks"` dispatch per bundle. The project installs `nunjucks` itself (no framework dep); Gina loads it via `lib/nunjucks-resolver` and routes through `controller.render-nunjucks.js`. Swig remains the default, runs unchanged. Inspector dev payload, HTTP/2 `stream.respond()` direct path, and error-page template routing all shipped in `0.3.7-alpha.2`. **Closing the parity gap on the `0.3.7` ASAP track** (see Nunjucks Parity below): filter registry port, `setResources` / `<gina>` layout placeholders, static HTML cache parity, Early Hints 103 auto-send. **Remaining `0.5.0` scope**: within-Inspector sub-items (`statusbar.html` include + flow/queries pipelines); per-template-extension dispatch so a single bundle can mix engines (`.swig` / `.njk`); optional auto-detect on `.njk` presence. Breaking syntax differences (`{% parent %}` → `{{ super() }}`, filter renames, `autoescape` default, `date` format strings, no `{% spaceless %}`) are nunjucks's own — Gina doesn't paper over them. | `0.5.0` | Q1 2027 |
 | 📋 | **Structured logging** — JSON log output (`{ level, message, bundle, requestId, durationMs }`). Additive — existing consumers are unaffected. Enables log aggregation (Loki, Datadog, CloudWatch). | `0.5.0` | Q1 2027 |
 | 📋 | **Research `AsyncLocalStorage` for request context** — Evaluate `node:async_hooks` `AsyncLocalStorage` as a replacement for the `local` closure pattern, giving true async isolation across `setTimeout`, Promises, and `async/await` chains without any closure threading. Output: decision doc + proof-of-concept branch. | `0.5.0` | Q1 2027 |
+### Nunjucks Parity (`0.3.7` ASAP track)
+Four focused follow-up sessions to close the deferred gap left by the `0.3.7-alpha.2` nunjucks MVP. Ordered by user impact.
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 🔨 | **Port `lib/swig-filters` → `lib/nunjucks-filters`** — Mechanically port the 7 filters (`getUrl`, `getWebroot`, `length`, `nl2br`, `addHours`, `addDays`, `addYears`) into a sister library registered via `env.addFilter()` in `controller.render-nunjucks.js`. Closes the most user-visible gap — template authors get `{{ '/home' \| getUrl() }}` and the date helpers immediately. | `0.3.7` | Q4 2026 |
+| 🔨 | **`setResources` / `<gina>` layout placeholders** — Port the asset-cataloguing pipeline so build-time `<link>` / `<script>` tags are auto-injected into nunjucks layouts the same way they are into swig layouts. `data.page.view.stylesheets` / `.scripts` now populated before render; post-render `injectAssets` helper auto-injects stylesheets before `</head>`, scripts before `</body>` (or before `</head>` when `javascriptsDeferEnabled`), plus `externalPlugins` and the `ginaLoader` before `</head>`. Templates may opt in explicitly with `{{ page.view.stylesheets \| safe }}` — exact-substring detection skips the auto-inject when they do. | `0.3.7` | Q4 2026 |
+| 📋 | **Static HTML cache parity** — Port the swig disk-write/serve cache path so `cache:` keys in `routing.json` actually produce cached HTML for nunjucks routes. | `0.3.7` | Q4 2026 |
+| 📋 | **Early Hints 103 auto-send for CSS/JS preloads** — Move the 103 path in `controller.js this.render()` to be engine-agnostic. Pure perf optimisation; manual `self.setEarlyHints(linkHeader)` already works. | `0.3.7` | Q4 2026 |
 ---
 ## Connectors

package/framework/v0.3.7-alpha.3/VERSION ADDED Viewed

	@@ -0,0 +1 @@
1	+ 0.3.7-alpha.3