gina 0.4.4 → 0.4.5

package/llms.txt

@@ -949,3 +949,11 @@ Dev-mode query instrumentation captures every database query tied to the current
 150. **#A11Y1 — `FormValidator` reflects each managed field's validity into `aria-invalid`, so `aria-errormessage` associations actually reach assistive technology; done at the rule-agnostic error-display chokepoint `handleErrorsDisplay` (`core/plugins/lib/validator/src/main.js`).** Per WAI-ARIA an `aria-errormessage` (or error `aria-describedby`) association is inert unless the field also carries `aria-invalid="true"`, which the validator never set. Now the chokepoint sets `aria-invalid="true"` on a committed error (error-set + refresh branches, gated `!isWarning` so soft live-check warnings while typing are NOT asserted) and `"false"` on clear — but on clear it MIRRORS the native `ValidityState` (`$el.willValidate && $el.validity && !$el.validity.valid` ⇒ keep `"true"`) so it never disagrees with the `:user-invalid` styling already shown for natively-constrained fields. Hidden fields (`$el.type=='hidden'`) are skipped. **No-duplicate-message + auto-wire:** a `_hasConsumerErrMsg` probe hoisted before the branch chain suppresses the injected `form-item-error-message` div when the field already references its own error element via `aria-errormessage`; legacy forms with no association keep the injected div and gain an `aria-errormessage` wire to it — a deterministic `gina-errormessage-<form>-<field>` id (sanitised), marked `data-gina-aria-errormessage` so a gina-owned wire is distinguished from a consumer's, removed on clear, and the refresh branch preserves the owned id. **Submit + blur announcement:** on a failed submit (`onValidate`) focus moves to the first DOM-order invalid field (hidden / unfocusable / zero-count skipped) so AT announces it; blur-time committed errors are announced through a lazily-created per-form visually-hidden `aria-live="polite"` region (`announceA11yError`), gated on the per-field path (`fieldName` set) once focus has LEFT the field — a CSS `:user-invalid` toggle is not reliably announced and on blur the field's own aria state isn't re-read; submit-time errors use focus, not the region. **Scope nuance:** the per-field blur/`input` passes fire only when the form opts into `data-gina-form-live-check-enabled` (the warning branch is gated on it); the always-on submit pass covers `aria-invalid` + focus regardless, so a non-live form still gets submit-time exposure. Rule-agnostic (the chokepoint operates on `errors[name]`, not per rule — `isRequired` / `isEmail` / `isInList` / every rule covered). No public API change; existing `form-item-error` / `form-item-warning` / `form-item-error-message` / `data-gina-form-errors` classes + submit-button toggling unchanged. Real-AT smoke (VoiceOver / NVDA announcing the field + message) is the manual acceptance step — the automated coverage exercises the DOM attributes that drive AT. Shipped as four atomic commits. Tests: `test/core/validator-aria-invalid.test.js` (42 — jsdom DOM-behaviour replicas + source pins). Established 2026-06-03.
 
 151. **`templates.json` pre-process pass in `core/config.js` (right after the `hasViews` line, BEFORE the routing↔template GET auto-vivify) expands two additive section-key shapes once per bundle — gina-io/gina#8 comma-separated keys + #10 `_common.config`.** #8: a comma-separated section key (`"a, b": {…}`) is split on `/\s*,\s*/` (each name `.trim()`med, empty segments skipped) and the block is replicated under each named section, MERGING into any section that already exists so a section's own keys win — `merge(existing, JSON.clone(block))`, and `lib/merge` keeps its FIRST argument on a leaf collision (`override=false` default). #10: an optional `_common.config` block is `merge(_common, _common.config)`-flattened back into `_common` then deleted, so the existing `_common.*` read sites are unchanged and a direct `_common.X` overrides `_common.config.X`. **Placement is load-bearing:** the pass must run before the GET auto-vivify `files['templates'][rule.toLowerCase()] = {}` (which keys off CLEAN route names from routing.json) — otherwise a comma key leaves the real route names "missing" → empty `{}` sections get minted AND the comma key survives to produce a dead `"a, b@bundle"` route. **Both are no-ops when absent** (no comma → single-element split → identical; no `_common.config` → untouched), so existing bundles are byte-identical — verified zero comma keys across known consumer + gina fixture `templates.json` before shipping. **#7 (a Swig-like `{ "inherit": … }` directive) was closed un-shipped**, so #8 is NOT redundant: `_common` shares to ALL routes, #8 shares a chosen SUBSET — a gap nothing else fills. Collect-then-mutate (gather comma keys first) avoids changing the object mid-`for…in`. Tests: `test/core/config-templates-preprocess.test.js` (source pins incl. placement-before-auto-vivify + a real-`merge` pure-logic replica: split / union-merge / own-keys-win / trim / empty-segment / flatten / no-op). Established 2026-06-05.
+
+152. **#M12a — opt-in structured (JSON) logging resolved once into `opt.format` (env `GINA_LOG_FORMAT=json`; `text` default).** `lib/logger/src/main.js` init resolves the render format with precedence `GINA_LOG_FORMAT=json|text` > `GINA_LOG_STDOUT` truthy ⇒ json (back-compat alias for the #K8s3 flag) > `text`, BEFORE `loadContainers()` `JSON.clone()`s `opt` into each container — so `containers/default/index.js` reads `opt.format` (falling back to the `GINA_LOG_STDOUT` env when `opt.format` is absent) instead of re-testing env. JSON line = `{ts, level, bundle, message, group, msg}`: `bundle`/`message` are the canonical #M12 keys; `group`/`msg` are retained as back-compat aliases for the shipped #K8s3 `{ts,level,group,msg}` shape — ADDITIVE, non-breaking (a rename would have failed the existing `logger-log-integrity.test.js §17.07` subprocess test, which asserts `typeof entry.{group,msg}==='string'`; the additive choice kept it green). The raw `console.log` path (`self.log`, `main.js` ~L814) bypasses the container dispatch, so it ALSO honours `opt.format==='json'` (wraps as `{ts, level:'info', bundle:opt.name, message, group, msg}`) — without this, JSON mode would interleave JSON + plain lines and break a collector. Default `text` keeps `docker`/OrbStack `docker logs` output byte-identical (the chokepoint for levelled output is the default container; `self.log` is the only other stdout writer — both covered). **M12b deferred** — automatic per-request `requestId`/`durationMs` stamping needs an always-on per-request `AsyncLocalStorage` context = #M14 (the Inspector `_queryALS` store at `controller.js:282-283` is dev/window-gated and carries no id; `durationMs` is computable from the metrics `response.on('finish')` hook but only when metrics is enabled). Tests: `test/lib/logger-render.test.js` (9, behavioural + source-pin). Established 2026-06-05.
+
+153. **Couchbase entities expose a public `getCluster()` accessor (wired onto both the model-entity and N1QL-entity prototypes in `core/connectors/couchbase/index.js`) returning the underlying SDK Cluster handle, so applications can use SDK-level features the entity layer does not wrap — notably multi-document ACID transactions via `cluster.transactions().run(...)` — without reaching into private `_*` connection internals.** The dual connection-shape lookup (`conn._cluster` for the entity-query path vs `conn._scope._bucket._cluster` for the bulk-insert/scope-collection path) is now centralised in ONE internal `resolveCluster(conn)` helper shared by `explainForIndexes`, `bulkInsert` and `getCluster()` — previously each path re-implemented it; it throws a clearly-coded `GINA_COUCHBASE_CLUSTER_UNRESOLVED` error (not a cryptic `undefined.query()` TypeError) when neither shape resolves. `getCluster()` calls `this.getConnection()` then `resolveCluster()`; it is Couchbase-specific so it lives on the connector's entity decoration (reachable wherever `bulkInsert` is), NOT on the generic `EntitySuper`/`getModel()` surface (a SQL/Redis/Mongo entity has no cluster). `explainForIndexes` consumes the helper in a try/catch to stay fire-and-forget non-fatal (warn + skip — it must never break the live query). gina does not pin the `couchbase` driver (resolved from the project's `node_modules`), so `.transactions()` availability depends on the project's installed SDK (3.2+/4.x); `getCluster()` guarantees only the handle. Tests: `test/core/couchbase-connector.test.js` (source pins + pure-logic replicas, neutral fixtures); the pre-existing `inspector.test.js` block-49 cluster-resolution pins were re-pointed from `explainForIndexes` to the extracted `resolveCluster()`. Established 2026-06-05.
+
+154. **MongoDB entities expose a public `getClient()` accessor (wired onto the entity prototype in `core/connectors/mongodb/index.js`) returning the underlying driver `MongoClient`, so applications can use driver-level features the entity layer does not wrap — notably multi-document transactions via `client.startSession()` → `session.withTransaction(...)`, change streams and `bulkWrite` — without reaching into private connection internals.** Unlike Couchbase's `getCluster()` (which derives the handle from the connection the entity already holds), Mongo's accessor needs a one-line connector plumbing step first: the entity is handed the `Db` (what `getConnection()` returns), but the `MongoClient` lives one level up and was previously closure-private — reachable through NO supported path — so `MongodbConnector.onReady` now decorates the yielded `Db` with a `_client` back-reference (mirroring the existing `_db._name` decoration) before `fn(null, _db)`. A private `resolveClient(conn)` helper reads `conn._client`, guards that it exposes a `startSession()` method, and throws a clearly-coded `GINA_MONGODB_CLIENT_UNRESOLVED` error (not a cryptic `undefined.startSession()` TypeError) when it cannot resolve; `getClient()` calls `this.getConnection()` then `resolveClient()`. It is Mongo-specific so it lives on the connector's own entity decoration, NOT on the generic `EntitySuper` surface — and on a SINGLE entity surface (Mongo pipelines attach only to existing entity classes, so there is no second N1QL-style prototype to mirror onto, unlike Couchbase). gina does not pin the `mongodb` driver (resolved from the project's `node_modules`); multi-document transactions additionally require a replica-set or sharded deployment, so `getClient()` guarantees only the handle. Tests: `test/core/mongodb-connector.test.js` (source pins + pure-logic replicas, neutral fixtures). Established 2026-06-06.
+
+155. **#M12b — opt-in per-request `requestId` + `durationMs` in JSON logs, built on a narrow `AsyncLocalStorage` (`process.gina._reqALS`, parked like `_queryALS` so it survives dev `require.cache` busting).** Gated on JSON logging ONLY: `_reqCtxLogging` in `core/server.js` mirrors the logger's `opt.format` env precedence (`GINA_LOG_FORMAT=json` > `GINA_LOG_STDOUT`). Text mode renders no id field, so running the ALS there would be pure overhead with no reader — gating on JSON ties the cost to the operator's existing structured-logging opt-in and keeps the default text path byte-identical/zero-cost (this also sidesteps the unmeasured always-on throughput question). `onInstance` (`server.js`) stamps `request._ginaReqStartMs` + `request._ginaReqId` at request entry; the id resolver honours a SANITISED inbound `X-Request-Id` (charset `/^[\w.\-]{1,128}$/`, regenerate-on-violation to kill log-forging/injection) else `crypto.randomUUID()`. The `.run({requestId,startMs})` wrap is at `handle()` — NOT `onInstance` — because the `request.on('end')` boundary between them loses async context whereas `handle()`'s awaits preserve it (original body renamed `_handleDispatch`; `handle` became a thin wrapper; call sites untouched). HTTP/2 gets per-stream scoping for free: streams flow through the same `handle()` via Node's per-stream compat `'request'` event, NOT `session.on('stream')`. The logger's two JSON-assembly sites (default container + the raw `self.log`/`console.log` path) optionally read `process.gina._reqALS.getStore()` and add `requestId` + `durationMs = Date.now() - startMs` (per-line elapsed) when a store is active; absent for CLI/boot/off-request logs (graceful guard). `.run()` NOT `enterWith()` (enterWith bleeds sideways across siblings). The always-on-regardless-of-format throughput PoC (#M14's go/no-go for un-gating) stays deferred — needs a bootable env. Tests: `test/lib/logger-render.test.js §06` (behavioural store→fields + source pins) + `test/core/server.test.js #M12b` (resolver sanitisation, env precedence, ALS-propagation-through-await + concurrent isolation, source pins). Established 2026-06-06.

package/package.json

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

package/framework/v0.4.4/VERSION

@@ -1 +0,0 @@
-0.4.4

package/framework/v0.4.4/lib/logger/README.md

@@ -1,7 +0,0 @@
-# Logger documentation
-
-## Debuging your test with nodeunit
-
-```tty
- node --inspect-brk=6959 `which nodeunit` ./test/01-find.js
-```

package/framework/v0.4.4/lib/logger/src/containers/default/index.js

@@ -1,75 +0,0 @@
-'use strict';
-// Imports
-
-function DefaultContainer(opt, loggers) {
-    var self = {
-        // flow or container name/id
-        name: 'default'
-    };
-    var loggerHelper    = require(__dirname +'/../../helper.js')(opt, loggers);
-    var format          = loggerHelper.format;
-
-    function init() {
-
-        // process.on('gina#bundle-started', function onBundleStarted(mqPort, hostV4, group) {
-        //     onPayload(true);
-        // });
-        // process.on('gina#container-writting', function onBundleStarted(mqPort, hostV4, group) {
-        //     console.debug('[MQDefault] resuming ...');
-        //     if (group) {
-        //         console.info('[MQTail] Group `'+group+'` connected `'+ hostV4 +'` on port `'+ mqPort +'` :)');
-        //     }
-        //     onPayload(true);
-        // });
-
-        onPayload();
-        // ----------------------------Debug---------------------------------------
-        var level = 'debug';
-        // Init debugging - Logs not in hierarchy will just be ignored
-        if (opt.hierarchies[opt.hierarchy].indexOf( opt.levels[level].code) > -1) {
-            process.emit('logger#'+self.name, JSON.stringify({
-                group       : opt.name,
-                level       : level,
-                // Raw content !
-                content     : '`'+ self.name +'` logger container loaded !'
-            }));
-        }
-        level = null;
-        // ------------------------------------------------------------------------
-    }
-
-    function onPayload() {
-
-        // #K8s3 — write JSON lines when GINA_LOG_STDOUT=true so that log collectors
-        // (kubectl logs, Fluentd, Datadog, etc.) can parse structured output.
-        // Otherwise write the standard formatted, coloured output for interactive terminals.
-        var isContainerMode = /^true$/i.test(process.env.GINA_LOG_STDOUT);
-
-        process.on('logger#'+self.name, function onPayload(payload) {
-
-            try {
-                var payloadObj = JSON.parse(payload);
-
-                if (isContainerMode) {
-                    process.stdout.write(JSON.stringify({
-                        ts   : new Date().toISOString(),
-                        level: payloadObj.level,
-                        group: payloadObj.group,
-                        msg  : payloadObj.content
-                    }) + '\n');
-                } else {
-                    process.stdout.write( format(payloadObj.group, payloadObj.level, payloadObj.content, payloadObj.skipFormating) );
-                }
-            } catch (e) {
-                process.stdout.write( format('', '', payload, true) );
-            }
-
-            payloadObj = null;
-        });
-    }
-
-
-
-    init();
-}
-module.exports = DefaultContainer;