gina 0.2.1-alpha.1 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,80 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.3.0 - 2026-04-06
+### Added
+* HTTP/2 client resilience: retry with backoff (up to 2 retries with 500ms delay), pre-flight PING validation on cached sessions, and session freshness tracking via _lastPongAt. Protects against OrbStack silent TCP drops and stale HTTP/2 sessions.
+* Inspector UX: drag-to-select log rows, copy badge fade-out, left accent selection styling, logo watermark on content panes, window geometry and env panel height persistence
+* Inspector View tab performance anomaly alerts: pulsing dot indicator on tab label, badge border override, and tooltip for metrics exceeding thresholds (load time, transfer size, FCP, query duration, query count)
+* Inspector Query tab: index badges per query card showing which database indexes are used (green for secondary, amber for primary scan, red for no index, grey N/A for unsupported connectors)
+* Inspector Query tab: per-card result size color-coding using the same weight thresholds as the total badge
+* Inspector Query tab: search input debounce (200ms), filter persistence in localStorage, and pagination (20 cards default with Show all button)
+* Couchbase connector: extractIndexes() helper and profile timings query option in dev mode for index reporting in the Inspector
+* Inspector: manual connect form on the 'No source' overlay — type a bundle URL to connect without editing the address bar
+* Inspector: tab layout presets (Balanced / Backend / Frontend / Custom) in settings panel — reorder tabs for different developer audiences, or drag to create a custom order
+* Docker Compose starter: `docker compose up` in gina-starter sets up a Gina app container + Couchbase Community 7.6.4 with pre-seeded cluster, bucket, application user, and sample documents — zero local install required
+### Changed
+* Renamed legacy Inspector parameter and marker names across the render pipeline: `displayToolbar` → `displayInspector` (server.js, controller.js, render-swig.js, render-v1.js), `{# Gina Toolbar #}` → `{# Gina Inspector #}` comment markers and guard regexes, "Beemaster" → "Inspector" in server.isaac.js and scan.js comments. `render-v1.js` now includes `statusbar.html` instead of `toolbar.html`, completing the migration of all render paths to the modern Inspector statusbar.
+### Fixed
+* Fixed error page displaying `[object Object]` when upstream returned an error object instead of a string — render-swig now normalises error and message fields to strings before building the error response (#Q2)
+* Couchbase session store v3/v4: touch() and destroy() passed MutationResult as error to express-session callback, causing defer(next, MutationResult) and a 500 response with the Couchbase CAS token as body on every authenticated read-only request (#CB-BUG-4)
+* Static file server now sends ETag and Last-Modified headers in production, enabling conditional GET (304 Not Modified) responses for all static types on both HTTP/1.x and HTTP/2 paths
+* Fixed method-based routing on shared URLs — the router now continues scanning after a URL match with a wrong method instead of immediately throwing 405. GET /notes and POST /notes can coexist as separate routing rules; a 405 is only emitted after the full scan finds no method match.
+* Fixed crash in fitsWithRequirements when a URL param route has no requirements block — router now accepts any non-empty segment value and correctly binds it to req.params / req[method] instead of throwing TypeError.
+* Fixed throwError(res, code, stringMsg) silently overriding an explicit 3-digit HTTP status code with res.status || 500 — throwError(res, 404, "Not found") now correctly sends 404 instead of 500.
+* Removed dead buffer consumption code from entity.js Option B path (_arguments[trigger] was unreachable for both connector-generated and custom entity methods). Added defensive unconditional clear at Option B entry point to prevent stale buffer leakage across calls (#M5).
+* Inspector Query tab: durationClass variable shadowing in renderQueryContent
+
+## 0.3.0-alpha.1 - 2026-04-02
+### Added
+* `project:start` / `project:stop` / `project:restart` — start, stop, or restart all bundles in a project with one command. Delegates to `bundle:start/stop/restart @<project>` (bulk mode). Flags forwarded.
+* Inspector Phase 2 — Inspector dev SPA embedded at `/_gina/inspector/` (engine-agnostic — works with both Isaac and Express). See CHANGELOG.md for the complete breakdown.
+* Thin in-page status bar — `statusbar.html` (new file in `dist/vendor/gina/html/`) is included instead of `toolbar.html`. A 36-line vanilla JS IIFE creates a Shadow DOM host (`#__gina-statusbar`) fixed at bottom-right: status dot (green = ok, red = `data.error` set), `bundle@env` label, and an "Inspector" link to `/_gina/inspector/`. No RequireJS, no jQuery, no SASS. Shadow DOM isolates styles from the app. `gina.js` toolbar module silently skips init when `#gina-toolbar` is absent (`!$toolbar.length` guard at line 17752).
+* Gina infrastructure port range 4100–4199 — reserved exclusively for Gina infrastructure; never assigned to bundle HTTP servers by `gina port:scan` (range skipped automatically). Layout: `4100` = socket server (future migration from 8124), `4101` = reserved, `4102` = engine.io internal transport, `4103–4199` = reserved for future Gina infrastructure. `settings.json` `engine.io.port` corrected from `8888` (conflicts with Jupyter Notebook) to `4102`. Port range documented in `framework/v0.3.0-alpha.1/lib/cmd/port/help.txt`.
+* `window.__ginaData` — replaces the two `<pre id="gina-toolbar-*-json">` DOM nodes with a single `<script>window.__ginaData = { gina: {...}, user: {...} };</script>` tag injected before `</body>` in dev mode. Data is built in Node.js (`controller.render-swig.js`) with the same field masking as before (`view.assets = {}`, `view.scripts/stylesheets = "ignored-by-toolbar"`); `</script>` and `<!--` sequences are escaped before serialization. Toolbar JS (`gina.js` dist + `main.js` src) updated to read from `window.__ginaData` directly instead of scraping DOM text nodes; mock file-upload writes back to `window.__ginaData.user`/`.gina`. The Inspector will access this object via `window.opener` or `postMessage` when it opens as a separate tab. No change to the data structure or toolbar panel rendering logic.
+* PATCH method support — `req.patch` is now populated with the parsed request body (JSON or form-encoded). Body parsing mirrors POST. `req.body` aliases `req.patch` for method-agnostic actions. URI params are merged into `req.patch` the same way as PUT. Use PATCH for partial updates (only the sent fields change); use PUT for full resource replacement. `case 'patch':` added to `getParams()` and `getParam()` in `controller.js`. `"method": "PATCH"` is now valid in `routing.json`.
+* HEAD method support — `req.head` is populated with query-string and URI params (same semantics as GET). The framework runs the full controller action so all response headers are set correctly, then suppresses the body before writing to the wire. Both `render()` (Swig) and `renderJSON()` honour HEAD. Routes declared as `GET` automatically accept HEAD requests — no separate routing rule needed. Useful for cache validation, existence checks, and CDN probing without downloading a response body.
+* Async controller actions — controller actions can be declared `async`. The router captures the return value of `controller[action]()` at both dispatch sites (with and without middleware) and attaches `.catch()` if the value is thenable. Rejections are routed to `throwError(response, 500, err.stack || err.message || String(err))`. Existing sync actions are unaffected.
+* `onCompleteCall(emitter)` global helper — wraps any EventEmitter that exposes `.onComplete(cb)` into a native Promise. Enables `await onCompleteCall(_(path).mkdir())` and similar patterns for PathObject file operations (`mkdir`, `cp`, `mv`, `rm`) and `Shell` commands from async controller actions.
+* Fixed empty `unhandledRejection` handler in `gna.js` — now logs `[ FRAMEWORK ] Unhandled promise rejection:` with the full stack so stray rejections are visible in framework logs instead of being silently swallowed.
+* 13 new unit tests covering the async dispatch guard source structure and pure `dispatchAction` logic (test/core/router.test.js suites 06–07).
+* `renderStream(asyncIterable, contentType)` on SuperController — streams any `AsyncIterable` as a chunked HTTP response without buffering. `contentType` defaults to `text/event-stream` (SSE); each yielded string/Buffer becomes `data: {chunk}\n\n`. For other content types, chunks are written raw. HTTP/2: `stream.respond()` + `stream.write()` + `stream.end()`. HTTP/1.1: automatic chunked transfer-encoding via `response.write()`. `x-accel-buffering: no` set automatically for SSE. Upstream response headers (CORS etc.) merged into the initial headers frame. Required for LLM token streaming with `ai.client` + `stream: true`. 32 unit tests (test/core/render-stream.test.js).
+* Route radix trie (#R1) — `lib/routing/src/radix.js` builds a segment-level radix trie from `routing.json` once at startup. `Routing.buildTrie(routing, bundle)` is called in `onRoutesLoaded()`; `Routing.lookupTrie(pathname, bundle)` returns candidate route names in O(m) time (m = path segment count). On a cache miss, `handle()` builds a `Set` from the trie candidates and uses `Set.has()` to skip non-matching routes in the `for…in` loop — turning the worst-case O(n×m) scan into O(m) candidate selection + O(k×m) validation (k = candidates). Falls back transparently to the full scan when the trie is unavailable. Internal change — no user-facing API change. 46 unit tests (test/lib/radix.test.js).
+* HTTP/2 configurable settings (#H3) — `maxConcurrentStreams` and `initialWindowSize` are now read from `settings.json` `http2Options` instead of being hardcoded. Defaults: `maxConcurrentStreams: 256`, `initialWindowSize: 655350` (10× TCP default). Security-critical settings (`maxHeaderListSize: 65536`, `enablePush: false`, `maxSessionRejectedStreams: 100`, `maxSessionInvalidFrames: 1000`) remain hardcoded and are not user-overridable. 16 unit tests in test/core/server.isaac.test.js (suites 03–03b).
+* HTTP/2 session metrics (#H3) — `server._h2Metrics` counter object (`activeSessions`, `totalStreams`, `goawayCount`, `rstCount`) is instrumented via `server.on('session', …)` event handlers and exposed under the `"http2"` key in the `/_gina/info` JSON response. 18 unit tests in test/core/server.isaac.test.js (suites 04–04b).
+* Security & CVE compliance docs page — `docs/security.md` lists all known HTTP/2 CVEs addressed by Gina: CVE-2023-44487 (Rapid Reset), CVE-2024-27316 / CVE-2024-27983 (CONTINUATION flood), CVE-2019-9514 (RST flood), HPACK bomb, and server push abuse. Each section includes attack description, Gina mitigation code snippet, and the Node.js version required. Docs only — no code changes.
+* AI connector — declare any LLM provider in `connectors.json` via a named protocol (`anthropic://`, `openai://`, `deepseek://`, `qwen://`, `groq://`, `mistral://`, `gemini://`, `xai://`, `perplexity://`, `ollama://`). All OpenAI-compatible providers share the `openai` npm package; `baseURL` overrides let any endpoint work including Ollama (MiMo, Llama, Phi…) and self-hosted vLLM. Unified `.infer(messages, options)` normaliser returns `{ content, model, usage, raw }` across providers; raw SDK client exposed on `.client` for streaming and function-calling. No tokens spent at startup. 70 unit tests (test/core/ai-connector.test.js).
+* `peerDependencies` for AI SDK clients — `openai` (>=4.0.0) and `@anthropic-ai/sdk` (>=0.27.0) added as optional peer dependencies alongside the existing database connector peers (`ioredis`, `mysql2`, `pg`, `mongodb`, `@scylladb/scylla-driver`, `couchbase`). npm/yarn will surface a compatibility warning when a user pins an untested client version. All clients remain loaded from the project's `node_modules` — zero framework runtime dependency.
+* MySQL ORM connector — entity wiring + SQL method generation from `sql/` files, `?` positional placeholders, `mysql2` pool (loaded from project `node_modules` — zero framework dependency), native Promise + `.onComplete()` shim, `@param`/`@return` annotation support. Install `mysql2` in your project to activate. 68 unit tests (test/core/mysql-connector.test.js).
+* PostgreSQL ORM connector — same entity/SQL architecture as MySQL; uses `$1`, `$2`, … placeholders, `pg.Pool` with idle-client error guard, `pool.query()` execution. Install `pg` in your project to activate. 72 unit tests (test/core/postgresql-connector.test.js).
+* Per-bundle framework version pinning — declare `"gina_version": "<version>"` on any bundle entry in `manifest.json` to run that bundle under a specific installed gina version. The socket server keeps running its own version; only the spawned bundle process uses the declared version. Validated against the tracked version registry in `~/.gina/main.json` before start.
+* `--gina-version=<version>` flag for `bundle:start` — CLI override that takes priority over `manifest.json`. Passes the version down to the spawned process via an isolated context clone so concurrent bundle starts do not interfere.
+* `bundle:add` now writes `"gina_version"` to the new bundle entry in `manifest.json` — records the current framework version at scaffold time so the pin is explicit from day one.
+* 33 new unit tests covering the resolution logic, validation, context isolation, and source structure (test/lib/bundle-gina-version.test.js).
+* Auto-sync `def_framework` in `~/.gina/main.json` on `bundle|project start|restart` (`bin/cli`) and on `gina-container` startup — keeps the active framework version aligned with `package.json` automatically after a version bump or worktree branch switch, with no manual `main.json` edit required.
+* Added `def_framework` sync in `post_install.js` — `main.json` is updated at install time so the CLI, cmd handlers, and `framework:init` all agree on the active version immediately after install.
+* New unit tests for `def_framework` sync logic in `test/bin/cli.test.js` (9 tests) and `test/bin/gina-container.test.js` section 05 (10 tests).
+* Hot-reload (#M6) — in dev mode `WatcherService` now starts automatically and registers watchers for `controller.js`, `controller.render-swig.js`, and the bundle's `controllers/` directory. `require.cache` is evicted only when a watched file has actually changed, eliminating per-request eviction overhead. Falls back transparently to per-request eviction when the watcher is not available (production, non-dev env). 15 new unit tests covering source-structure guards and pure dirty-flag logic (test/core/router.test.js suites 08–09).
+* GOAWAY logging (#H5) ��� `client.on('goaway')` handler in `controller.js` now logs `errorCode`, `lastStreamID`, and session key via `console.warn`. Distinguishes clean server restarts (errorCode 0) from protocol errors. 2 tests in `http2-client.test.js` section 09.
+* HTTP/2 session-level guards now configurable (#H7) — `maxSessionRejectedStreams` and `maxSessionInvalidFrames` are now read from `settings.json` `http2Options` (defaults 100 and 1000). Previously hardcoded. Bundle boilerplate `settings.server.json` documents all four `http2Options` keys. 4 new tests in `server.isaac.test.js`.
+* `onCompleteCall` formalized as `lib/async` module (#M4) — the Promise adapter previously lived only as an implicit global in `helpers/path.js`. Now a proper library at `lib/async/src/main.js`, registered in `lib/index.js` as `lib.async`. Input validation throws `TypeError` for missing/invalid emitters. Global injection delegates to the lib module. 16 tests in `test/lib/async.test.js`.
+### Fixed
+* Fixed method-based routing on shared URLs — the router now continues scanning after a URL match with a wrong method instead of immediately throwing 405. GET `/notes` and POST `/notes` can coexist as separate routing rules; a 405 is only emitted after the full scan finds no method match. (`core/server.js`)
+* Fixed crash in `fitsWithRequirements` when a URL param route has no `requirements` block — router now accepts any non-empty segment value and correctly binds it to `req.params` / `req[method]` instead of throwing `TypeError`. (`lib/routing/src/main.js`)
+* Fixed `throwError(res, code, stringMsg)` silently overriding an explicit 3-digit HTTP status code with `res.status || 500` — `throwError(res, 404, 'Not found')` now correctly sends 404 instead of 500. (`core/controller/controller.js`)
+* Fixed port scanner `opt.end` hardcoded window — `scan.js` previously used a fixed `start + 899` ceiling regardless of `limit`, so a `port:reset` scan requesting many ports could exhaust the window before finding them all. Window is now `Math.min(start + Math.max(899, limit + 99), maxEnd)`, giving at least 899 ports of headroom for small limits and scaling proportionally for large ones (e.g. `protocol:set` passes `protocols × schemes × envs × bundles`). Unit tests added in `test/unit/port-scan.test.js`.
+* Fixed `query()` forwarding errors directly to `throwError()` on non-2xx upstream responses — the callback now receives the error object so controllers can implement graceful degradation instead of always surfacing a hard error. (#Q1)
+* Fixed `throwError()` logging empty for plain-object errors from `query()` — `err.stack || err.message` was undefined; now serializes `errorObject.error` and captures the callsite stack when no stack is present. (#Q1)
+* Fixed `controller.render-swig.js` error field priority — `statusCodes[status]` was evaluated first, burying the actual upstream error reason; `data.page.data.error` and `data.page.data.message` now take priority, `statusCodes[status]` is the fallback. Added `console.error` log before `throwError` so the upstream reason appears in bundle logs. (#Q1)
+* Fixed `whisper()` error log showing `{key}` instead of `${key}` for missing dictionary keys.
+* Fixed `bundle:start` (socket-server path) not initialising `ctx.envVars` — `gna.js defineDefault()` could not create GINA_* globals when the key was absent.
+* Fixed `env.json` placeholder substitution — `${bundlesPath}`, `${homedir}`, `${cachePath}`, `${projectName}`, `${projectVersion}`, `${projectVersionMajor}` were missing from the `reps` dict in `CmdHelper`; whisper left them unresolved.
+* Fixed `package.json` `"main"` field still pointing to `framework/v0.2.1-alpha.3/core/gna` after version bump — now `framework/v0.3.0-alpha.1/core/gna`.
+* Fixed error page displaying `[object Object]` when upstream returned an error object instead of a string — `render-swig` now normalises `error` and `message` fields to strings before building the error response. (#Q2)
+
+## 0.2.1-alpha.3 - 2026-03-29
+Internal version bump — no user-facing changes. Repository URLs updated from Rhinostone to gina-io.
+
 ## 0.2.0 - 2026-03-29
 ### Added
 * NODE_COMPILE_CACHE (#P1): set at startup in gna.js to ~/.gina/cache/v8 — Node.js >= 22.8 caches V8 bytecode to disk, reducing cold-start time by 30–60% on subsequent runs. No-op on older Node versions.

package/CONTRIBUTING.md

@@ -11,6 +11,7 @@ Gina follows a BDFL governance model — see [GOVERNANCE.md](./GOVERNANCE.md) fo
 - [Running the tests](#running-the-tests)
 - [Development environment](#development-environment)
 - [Debugging](#debugging)
+- [Coding conventions](#coding-conventions)
 - [Branch model](#branch-model)
 - [Commit style](#commit-style)
 - [Changelog](#changelog)
@@ -47,7 +48,7 @@ The default is `/usr/local` (system) or `~/.npm-global` (user). The target direc
 
 ```bash
 cd $(npm config get prefix)/lib/node_modules
-git clone https://github.com/Rhinostone/gina.git gina
+git clone https://github.com/gina-io/gina.git gina
 cd gina && git checkout develop
 ```
 
@@ -124,6 +125,14 @@ gina bundle:restart <bundle_name> @<project_name> --inspect=<port_number>
 
 ---
 
+## Coding conventions
+
+All coding conventions — variable declarations, function style, constructor patterns, error handling, async patterns, naming, JSDoc, EventEmitter usage, path handling, logging, and test conventions — are documented in [CONVENTIONS.md](./CONVENTIONS.md).
+
+Please read it before submitting your first pull request.
+
+---
+
 ## Branch model
 
 | Branch | Purpose |
@@ -176,7 +185,7 @@ Before opening a PR against `develop`:
 
 ## Reporting bugs
 
-Open a [GitHub issue](https://github.com/Rhinostone/gina/issues) and include:
+Open a [GitHub issue](https://github.com/gina-io/gina/issues) and include:
 
 - Node.js version (`node --version`)
 - Gina version (`gina --version`)