gina 0.4.5-alpha.1 → 0.4.5

package/CHANGELOG.md

@@ -6,6 +6,16 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.4.5 - 2026-06-06
+
+_Additive release — opt-in structured (JSON) logging with per-request `requestId` / `durationMs` correlation, plus public SDK-handle accessors (`getCluster()` on Couchbase, `getClient()` on MongoDB) for driver-level features such as multi-document transactions. No breaking changes, no settings reset._
+
+### Added
+* Opt-in structured (JSON) log output. Set `GINA_LOG_FORMAT=json` to emit one machine-parseable JSON object per log line (`{ts, level, bundle, message}`, with `group`/`msg` kept as back-compat aliases) for log collectors such as Loki, Datadog, Fluentd or CloudWatch. The default stays the coloured, human-readable format, so interactive `docker logs` output is unchanged. The existing `GINA_LOG_STDOUT` container flag continues to enable JSON output.
+* Added a public `getCluster()` accessor on Couchbase entities that returns the underlying SDK Cluster handle, so applications can use SDK-level features the entity layer does not wrap — notably multi-document transactions via `cluster.transactions().run(...)` — without reaching into private connection internals. Transaction support depends on the Couchbase driver your project installs (SDK 3.2+ / 4.x).
+* Added a public `getClient()` accessor on MongoDB entities that returns the underlying driver `MongoClient`, so applications can reach driver-level features the entity layer does not wrap — notably multi-document transactions via `client.startSession()` / `session.withTransaction(...)` — without reaching into private connection internals. Multi-document transactions additionally require a replica-set or sharded deployment and depend on the `mongodb` driver your project installs.
+* Opt-in per-request `requestId` and `durationMs` fields in structured (JSON) logs. When `GINA_LOG_FORMAT=json` is active, every log line emitted during a request is tagged with a request id (an inbound `X-Request-Id` is honoured when well-formed, otherwise one is generated) and the elapsed milliseconds since the request began, so lines from a single request can be correlated in a collector such as Loki, Datadog, Fluentd or CloudWatch. Default text logging is unchanged and pays no overhead.
+
 ## 0.4.4 - 2026-06-05
 
 _Additive release — `templates.json` gains comma-separated section keys (share one stylesheet/script block across several routes at once) and an optional `_common.config` block for page-level defaults. No breaking changes, no settings reset._

package/README.md

@@ -39,10 +39,12 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
-## What's in 0.4.4
+## What's in 0.4.5
 
-- **`templates.json` multi-section keys.** A section key may now be comma-separated — e.g. `"products, productDetail"` — to share a stylesheet or `<script>` block across several routes at once. The block is replicated under each named section and deep-merged into any section you also declare on its own, so a section's own keys win on collision. Single-section keys behave exactly as before.
-- **`templates.json` `_common.config` block.** An optional `_common.config` block holds page-level defaults (such as `routeNameAsFilenameEnabled` or `javascriptsDeferEnabled`). It is flattened back into `_common` at load time, so existing bundles are unaffected and any direct `_common` key still overrides the config block.
+- **Opt-in structured (JSON) logging.** Set `GINA_LOG_FORMAT=json` to emit one machine-parseable JSON object per log line (`{ts, level, bundle, message}`) for collectors such as Loki, Datadog, Fluentd or CloudWatch. The default stays the coloured, human-readable format, so interactive `docker logs` output is unchanged unless you opt in.
+- **Per-request `requestId` / `durationMs` in JSON logs.** When JSON logging is on, every log line emitted during a request carries a request id (an inbound `X-Request-Id` is honoured when well-formed, otherwise one is generated) and the elapsed milliseconds since the request began, so a single request's lines can be correlated in your collector. Default text logging is unchanged and pays no overhead.
+- **Public SDK Cluster accessor on Couchbase entities.** `getCluster()` returns the underlying SDK `Cluster` handle, so you can use SDK-level features the entity layer does not wrap — notably multi-document transactions via `cluster.transactions().run(...)` — without reaching into private connection internals.
+- **Public MongoClient accessor on MongoDB entities.** `getClient()` returns the underlying driver `MongoClient`, so you can reach driver-level features the entity layer does not wrap — notably multi-document transactions via `client.startSession()` / `session.withTransaction(...)` (which additionally require a replica-set or sharded deployment).
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -119,7 +119,7 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | --- | --- | --- | --- |
 | 📋 | **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, 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 |
+| 🚧 | **Structured logging** — **Opt-in JSON output shipped**: set `GINA_LOG_FORMAT=json` for one machine-parseable object per log line (`{ ts, level, bundle, message }`); the coloured, human-readable format stays the default, so `docker logs` is unchanged. Additive — existing consumers are unaffected. Enables log aggregation (Loki, Datadog, CloudWatch). Per-request fields (`requestId`, `durationMs`) pending request-context research. | `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)

package/framework/v0.4.5/VERSION

@@ -0,0 +1 @@
+0.4.5

package/framework/{v0.4.5-alpha.1 → v0.4.5}/core/asset/plugin/dist/vendor/gina/inspector/inspector.css

@@ -3640,5 +3640,3 @@ details[open] > summary.bm-summary::before {
     text-align: left;
   }
 }
-
-/*# sourceMappingURL=inspector.css.map */

package/framework/{v0.4.5-alpha.1 → v0.4.5}/core/connectors/couchbase/index.js

@@ -93,6 +93,40 @@ function Couchbase(conn, infos) {
      */
     var _explainCache = new Map();
 
+    /**
+     * Resolve the underlying Couchbase SDK Cluster handle from a connection
+     * object, tolerating both shapes the connector produces:
+     *   - entity query path: the cluster sits directly at `conn._cluster`
+     *   - bulk-insert / scope-collection path: `conn` is scope-shaped and the
+     *     cluster is nested at `conn._scope._bucket._cluster`
+     *
+     * Single source of truth for cluster resolution — `explainForIndexes`,
+     * `bulkInsert` and the public `getCluster()` accessor all consume it, so the
+     * dual-shape lookup lives in exactly one place.
+     *
+     * @param {object} conn - A Couchbase connection object (bucket- or scope-shaped).
+     * @returns {object} The SDK Cluster (guaranteed to expose a `query()` method).
+     * @throws {Error} `GINA_COUCHBASE_CLUSTER_UNRESOLVED` when neither shape yields a usable cluster.
+     * @private
+     */
+    var resolveCluster = function(conn) {
+        var cluster = (conn && conn._cluster)
+            ? conn._cluster
+            : (conn && conn._scope && conn._scope._bucket && conn._scope._bucket._cluster)
+                ? conn._scope._bucket._cluster
+                : null;
+
+        if (!cluster || typeof(cluster.query) !== 'function') {
+            var _err = new Error('[ CONNECTOR ][ couchbase ] Unable to resolve the SDK Cluster from the connection — '
+                + 'neither `conn._cluster` nor `conn._scope._bucket._cluster` exposes a query() method. '
+                + 'The connection shape may have changed across an SDK or framework upgrade.');
+            _err.code = 'GINA_COUCHBASE_CLUSTER_UNRESOLVED';
+            throw _err;
+        }
+
+        return cluster;
+    };
+
     /**
      * Runs EXPLAIN on a N1QL statement asynchronously and caches the
      * extracted indexes. Patches `queryEntry.indexes` in-place once
@@ -106,16 +140,13 @@ function Couchbase(conn, infos) {
      * @private
      */
     var explainForIndexes = function(conn, statement, queryEntry, queryOptions) {
-        // Resolve cluster from whichever conn shape we received:
-        // - entity query path: conn._cluster exists directly
-        // - bulk insert path: conn is a scope object, cluster is at conn._scope._bucket._cluster
-        var cluster = (conn._cluster)
-            ? conn._cluster
-            : (conn._scope && conn._scope._bucket && conn._scope._bucket._cluster)
-                ? conn._scope._bucket._cluster
-                : null;
-
-        if (!cluster || typeof(cluster.query) !== 'function') {
+        // #QI is fire-and-forget instrumentation — resolve the cluster via the
+        // shared helper but keep this path non-fatal (warn + skip) so a
+        // resolution failure never breaks the actual query.
+        var cluster;
+        try {
+            cluster = resolveCluster(conn);
+        } catch (_clusterErr) {
             console.warn('[explainForIndexes] Cannot resolve cluster from conn — skipping EXPLAIN for: ' + statement.substring(0, 80));
             return;
         }
@@ -210,6 +241,10 @@ function Couchbase(conn, infos) {
 
                     // extra CRUD methods
                     Entity.prototype.bulkInsert     = bulkInsert;
+                    // public SDK Cluster accessor — supported entry point for
+                    // SDK-level features (e.g. transactions) the entity layer
+                    // does not wrap; see resolveCluster()/getCluster().
+                    Entity.prototype.getCluster     = getCluster;
 
 
                     entities[className] = Entity
@@ -441,6 +476,9 @@ function Couchbase(conn, infos) {
                     entities[entityName].prototype._collection    = entityName;
                     entities[entityName].prototype._scope         = infos.scope || process.env.NODE_SCOPE;
                     entities[entityName].prototype._filename      = _( __dirname + '/lib/n1ql.js', true );
+                    // public SDK Cluster accessor — parity with model entities so a
+                    // consumer never hits an asymmetric `undefined` (see getCluster()).
+                    entities[entityName].prototype.getCluster     = getCluster;
                 }
 
 
@@ -1208,7 +1246,9 @@ function Couchbase(conn, infos) {
             var self = this;
 
             var err = false;
-            conn._scope._bucket._cluster.query(query, queryOptions)
+            // cluster resolved via the shared dual-shape helper (was a bare
+            // conn._scope._bucket._cluster deref).
+            resolveCluster(conn).query(query, queryOptions)
                 .catch( function onError(err) {
                     try {
                         // #QI — finalize bulkInsert query entry on error
@@ -1321,6 +1361,38 @@ function Couchbase(conn, infos) {
         }
     }
 
+    /**
+     * getCluster
+     *
+     * Returns the underlying Couchbase SDK Cluster handle backing this entity's
+     * connection, resolved across the connection shapes the connector produces
+     * (see `resolveCluster`). This is the supported, non-underscore way to reach
+     * SDK-level features the entity layer does not wrap — most notably
+     * multi-document ACID transactions via `cluster.transactions().run(...)`.
+     *
+     * Note: gina does not bundle or pin the `couchbase` driver — it is resolved
+     * from your project's `node_modules`. Transaction support (`.transactions()`)
+     * therefore depends on the Couchbase SDK version your project installs
+     * (3.2+ / 4.x). gina guarantees only that this returns the resolved Cluster
+     * handle; it makes no promise about which SDK-level capabilities that handle
+     * exposes.
+     *
+     * @returns {object} The Couchbase SDK Cluster.
+     * @throws {Error} `GINA_COUCHBASE_CLUSTER_UNRESOLVED` when the cluster cannot be resolved.
+     *
+     * @example
+     * // Inside a controller action holding an entity instance:
+     * var cluster = myEntity.getCluster();
+     * await cluster.transactions().run(async function (ctx) {
+     *     var doc = await ctx.get(collection, 'doc-id');
+     *     await ctx.replace(doc, Object.assign({}, doc.content, { balance: 0 }));
+     * });
+     */
+    var getCluster = function() {
+        return resolveCluster(this.getConnection());
+    };
+
+
     return init(conn, infos)
 }
 

package/framework/{v0.4.5-alpha.1 → v0.4.5}/core/connectors/mongodb/index.js

@@ -88,6 +88,36 @@ function Mongodb(conn, infos) {
         ObjectId = null;
     }
 
+    /**
+     * Resolve the underlying MongoDB driver `MongoClient` from a connection
+     * object. The entity layer is handed the `Db` instance (what
+     * `getConnection()` returns); the connector decorates that Db with a
+     * `_client` back-reference to the owning `MongoClient` one level up (see
+     * `MongodbConnector.onReady`), because session and multi-document
+     * transaction APIs live on the `MongoClient`, not the `Db`.
+     *
+     * Single source of truth for client resolution, so the lookup — and its
+     * coded failure mode — live in exactly one place.
+     *
+     * @param {object} conn - A MongoDB connection object (the `Db` from getConnection()).
+     * @returns {object} The MongoDB driver MongoClient (guaranteed to expose a `startSession()` method).
+     * @throws {Error} `GINA_MONGODB_CLIENT_UNRESOLVED` when the client cannot be resolved.
+     * @private
+     */
+    var resolveClient = function(conn) {
+        var client = (conn && conn._client) ? conn._client : null;
+
+        if (!client || typeof(client.startSession) !== 'function') {
+            var _err = new Error('[ CONNECTOR ][ mongodb ] Unable to resolve the MongoClient from the connection — '
+                + '`conn._client` does not expose a startSession() method. '
+                + 'The connection shape may have changed across a driver or framework upgrade.');
+            _err.code = 'GINA_MONGODB_CLIENT_UNRESOLVED';
+            throw _err;
+        }
+
+        return client;
+    };
+
     var init = function(conn, infos) {
         var EntitySuperClass = null;
         var entitiesPath     = getPath('bundle') + '/models/' + infos.database + '/entities';
@@ -131,6 +161,10 @@ function Mongodb(conn, infos) {
             Entity.prototype._collection = entityName;
             Entity.prototype._scope      = infos.scope || process.env.NODE_SCOPE;
             Entity.prototype._filename   = _(entitiesPath + '/' + files[f], true);
+            // public MongoClient accessor — supported entry point for driver-level
+            // features (sessions, multi-document transactions, change streams) the
+            // entity layer does not wrap; see resolveClient()/getClient().
+            Entity.prototype.getClient   = getClient;
 
             entities[className] = Entity;
         }
@@ -458,6 +492,48 @@ function Mongodb(conn, infos) {
     };
 
 
+    /**
+     * getClient
+     *
+     * Returns the underlying MongoDB driver `MongoClient` backing this entity's
+     * connection. The entity layer is handed the `Db` (what `getConnection()`
+     * returns); the `MongoClient` lives one level up and is where session and
+     * multi-document transaction APIs are exposed — so this is the supported,
+     * non-underscore way to reach driver-level features the entity layer does
+     * not wrap, chiefly ACID transactions via
+     * `client.startSession()` → `session.withTransaction(...)`, plus change
+     * streams and `bulkWrite`.
+     *
+     * Note: gina does not bundle or pin the `mongodb` driver — it is resolved
+     * from your project's `node_modules`. Session/transaction support therefore
+     * depends on the driver your project installs, and multi-document
+     * transactions additionally require a replica-set or sharded deployment
+     * (not a standalone mongod). gina guarantees only that this returns the
+     * resolved client handle; it makes no promise about which driver-level
+     * capabilities that handle exposes.
+     *
+     * @returns {object} The MongoDB driver MongoClient.
+     * @throws {Error} `GINA_MONGODB_CLIENT_UNRESOLVED` when the client cannot be resolved.
+     *
+     * @example
+     * // Inside a controller action holding an entity instance:
+     * var client  = myEntity.getClient();
+     * var session = client.startSession();
+     * try {
+     *     await session.withTransaction(async function () {
+     *         var db = client.db();
+     *         await db.collection('accounts').updateOne({ _id: from }, { $inc: { balance: -100 } }, { session: session });
+     *         await db.collection('accounts').updateOne({ _id: to },   { $inc: { balance:  100 } }, { session: session });
+     *     });
+     * } finally {
+     *     await session.endSession();
+     * }
+     */
+    var getClient = function() {
+        return resolveClient(this.getConnection());
+    };
+
+
     return init(conn, infos);
 }
 

package/framework/{v0.4.5-alpha.1 → v0.4.5}/core/connectors/mongodb/lib/connector.js

@@ -136,6 +136,11 @@ function MongodbConnector(conf) {
      * Register a one-time ready callback. Async — calls `client.connect()`
      * which establishes the TCP connection and verifies authentication.
      *
+     * The yielded `Db` is decorated with `_name` (db name) and `_client` (a
+     * back-reference to the owning `MongoClient`), so entities — which are
+     * handed the `Db` — can reach client-level APIs (sessions, transactions)
+     * through the public `getClient()` accessor.
+     *
      * @param {function} fn - `fn(err, conn)` where `conn` is the mongodb Db instance.
      */
     this.onReady = function(fn) {
@@ -144,6 +149,7 @@ function MongodbConnector(conf) {
         _client.connect().then(function() {
             _db = _client.db(_dbName);
             _db._name = _dbName;
+            _db._client = _client; // back-reference to the MongoClient (one level up from the Db) so entities can reach sessions/transactions via getClient()
             console.debug('[MongodbConnector] connected to: ' + _dbName);
             fn(null, _db);
         }).catch(function(err) {

package/framework/{v0.4.5-alpha.1 → v0.4.5}/core/server.js

@@ -44,6 +44,31 @@ const crypto        = require('crypto');
 var https           = require('https');
 // ssl-checker dependency removed in 0.3.1 — replaced by inline verifyCertificate().
 
+// #M12b — per-request log context (requestId / durationMs in JSON logs).
+// Active ONLY when JSON logging is on: the text formatter ('[%d] [%s][%a] %m')
+// renders no id field, so running the AsyncLocalStorage in text mode would be pure
+// overhead with no reader. Mirrors lib/logger's opt.format precedence
+// (GINA_LOG_FORMAT > GINA_LOG_STDOUT), resolved once — the format is fixed for the
+// process lifetime.
+var _reqCtxLogging = (function() {
+    if ( /^json$/i.test(process.env.GINA_LOG_FORMAT) ) { return true; }
+    if ( /^text$/i.test(process.env.GINA_LOG_FORMAT) ) { return false; }
+    return /^true$/i.test(process.env.GINA_LOG_STDOUT);
+})();
+
+// #M12b — resolve the request id: honour a sanitised inbound `X-Request-Id` (so logs
+// correlate across an upstream proxy / sibling services), else generate a UUID. The
+// inbound value is client-supplied and untrusted — cap length and restrict the
+// charset to neutralise log-forging / injection; on any violation fall back to a
+// fresh UUID.
+var _resolveRequestId = function(request) {
+    var _inbound = request && request.headers && request.headers['x-request-id'];
+    if ( _inbound && /^[\w.\-]{1,128}$/.test(_inbound) ) {
+        return _inbound;
+    }
+    return crypto.randomUUID();
+};
+
 
 // Lightweight debug logger — gated on LOG_LEVEL so zero cost in production.
 // Format mirrors lib/logger template: [date] [debug  ][gina:server] message
@@ -2640,6 +2665,16 @@ function Server(options) {
         // catch all (request urls)
         self.instance.all('*', function onInstance(request, response, next) {
 
+            // #M12b — stamp request-entry time + id so the logger can attribute every
+            // line emitted during this request to it (requestId / durationMs in JSON
+            // logs). Active only in JSON mode; the per-request .run() happens at handle()
+            // (the request.on('end') boundary between here and handle() loses async
+            // context, so the store must be established where the dispatch runs).
+            if ( _reqCtxLogging ) {
+                request._ginaReqStartMs = Date.now();
+                request._ginaReqId      = _resolveRequestId(request);
+            }
+
             // #FI — dev-mode request timeline for Inspector Flow tab
             // Only initialized when the Inspector has been opened (process.gina._inspectorActive)
             // #INS10 — or during a prod instrumentation window (process.gina._inspectorWindowUntil).
@@ -4221,7 +4256,31 @@ function Server(options) {
         return request
     }
 
+    // #M12b — wrap the async dispatch in the per-request log context so requestId /
+    // durationMs propagate through the WHOLE await chain (router, controller, render,
+    // connectors). Established here — not at onInstance — because the request.on('end')
+    // boundary between them loses the async context, whereas handle()'s awaits preserve
+    // it. The store carries {requestId, startMs} stamped at onInstance entry. Gated on
+    // JSON logging; in text mode handle === the dispatch with zero ALS overhead.
     var handle = async function(req, res, next, bundle, pathname, config) {
+        if ( _reqCtxLogging ) {
+            if ( !process.gina ) { process.gina = {}; }
+            if ( !process.gina._reqALS ) {
+                var { AsyncLocalStorage } = require('async_hooks');
+                process.gina._reqALS = new AsyncLocalStorage();
+            }
+            var _reqStore = {
+                requestId : req._ginaReqId || _resolveRequestId(req),
+                startMs   : (typeof req._ginaReqStartMs === 'number') ? req._ginaReqStartMs : Date.now()
+            };
+            return process.gina._reqALS.run(_reqStore, function() {
+                return _handleDispatch(req, res, next, bundle, pathname, config);
+            });
+        }
+        return _handleDispatch(req, res, next, bundle, pathname, config);
+    };
+
+    var _handleDispatch = async function(req, res, next, bundle, pathname, config) {
 
         // #FI — request setup time (header parsing, CORS, Inspector endpoint checks)
         if (req._devTimeline) {

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

@@ -0,0 +1,44 @@
+# Logger
+
+Gina's multi-stream, multi-group structured logger (RFC 5424 severity levels). Bundle
+code binds it to `console` (`var console = require('gina').lib.logger`) and calls
+`console.info(...)`, `console.err(...)`, etc.; the logger filters by level and fans
+each line out to its transport "containers" — `default` → `process.stdout`,
+`mq` → port 8125 (`gina tail`), and an opt-in `file` container.
+
+## Output modes
+
+The `default` container has two render modes, resolved once at logger init. Select the
+mode with an environment variable on the bundle process (precedence
+`GINA_LOG_FORMAT` → `GINA_LOG_STDOUT` → `text`):
+
+- **text** (default) — a coloured, human-readable line (`[%d] [%s][%a] %m`), ideal for
+  a terminal or `docker logs`.
+- **json** — one machine-parseable JSON object per line, for log aggregation:
+
+  ```json
+  {"ts":"…","level":"info","bundle":"frontend@myproject","message":"…","group":"frontend@myproject","msg":"…"}
+  ```
+
+  `bundle`/`message` are canonical; `group`/`msg` are back-compat aliases.
+
+Two env vars select JSON:
+
+- `GINA_LOG_FORMAT=json` — emit JSON instead of the coloured text, in any environment.
+- `GINA_LOG_STDOUT=true` — container preset: implies JSON **and** skips the MQ
+  transport (no MQ listener runs inside a container).
+
+Both the level methods (`console.info`, `console.debug`, …) and plain `console.log`
+honour the mode, so the stream stays uniformly parseable.
+
+Full reference: the [Logging guide](https://gina.io/docs/guides/logging) and the
+[Logger API reference](https://gina.io/docs/api/logger).
+
+## Tests
+
+From the repository root:
+
+```bash
+node --test test/lib/logger-render.test.js
+node --test test/integration/logger-log-integrity.test.js
+```

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

@@ -0,0 +1,97 @@
+'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() {
+
+        // #M12 — structured (JSON) logging. The render format is resolved once at logger
+        // init (main.js -> opt.format) and cloned into this container's `opt`. We read
+        // opt.format here; if it is absent (a logger init path that predates #M12) we fall
+        // back to the #K8s3 GINA_LOG_STDOUT env flag, so behaviour is unchanged either way.
+        // JSON mode  -> one machine-parseable object per line (kubectl logs / Fluentd /
+        //               Datadog / Loki).
+        // text mode  -> the coloured, human-readable format() output (the default).
+        var isJsonMode = (opt && opt.format)
+            ? (opt.format === 'json')
+            : /^true$/i.test(process.env.GINA_LOG_STDOUT);
+
+        process.on('logger#'+self.name, function onPayload(payload) {
+
+            try {
+                var payloadObj = JSON.parse(payload);
+
+                if (isJsonMode) {
+                    // #M12 — `bundle` and `message` are the canonical keys; `group` and `msg`
+                    // are retained as back-compat aliases for pre-#M12 JSON consumers (the
+                    // shipped #K8s3 shape was {ts, level, group, msg}). Additive, non-breaking.
+                    var _jsonLine = {
+                        ts     : new Date().toISOString(),
+                        level  : payloadObj.level,
+                        bundle : payloadObj.group,
+                        message: payloadObj.content,
+                        group  : payloadObj.group,
+                        msg    : payloadObj.content
+                    };
+                    // #M12b — stamp the per-request id + elapsed-ms when a request context
+                    // is active (process.gina._reqALS, created by server.js in JSON mode).
+                    // Absent for CLI / boot / off-request logs — the fields are then omitted.
+                    if (process.gina && process.gina._reqALS) {
+                        var _reqStore = process.gina._reqALS.getStore();
+                        if (_reqStore) {
+                            _jsonLine.requestId  = _reqStore.requestId;
+                            _jsonLine.durationMs = Date.now() - _reqStore.startMs;
+                        }
+                    }
+                    process.stdout.write(JSON.stringify(_jsonLine) + '\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;

package/framework/{v0.4.5-alpha.1 → v0.4.5}/lib/logger/src/main.js

@@ -364,6 +364,24 @@ function Logger() {
             if (mqIdx > -1) opt.flows.splice(mqIdx, 1);
         }
 
+        // #M12 — structured (JSON) logging opt-in. The active render format is resolved
+        // ONCE here, before loadContainers() clones `opt` into each container, so a
+        // container reads `opt.format` instead of re-testing the environment. Precedence:
+        //   1. GINA_LOG_FORMAT = json|text  (explicit; works outside container mode)
+        //   2. GINA_LOG_STDOUT truthy => json (back-compat alias for the #K8s3 flag)
+        //   3. default 'text' — the coloured, human-readable output (unchanged).
+        // Keeping the default at 'text' means interactive consumers (docker / OrbStack
+        // `docker logs`, a dev terminal) see exactly the same output as before.
+        if ( /^json$/i.test(process.env.GINA_LOG_FORMAT) ) {
+            opt.format = 'json';
+        } else if ( /^text$/i.test(process.env.GINA_LOG_FORMAT) ) {
+            opt.format = 'text';
+        } else if ( /^true$/i.test(process.env.GINA_LOG_STDOUT) ) {
+            opt.format = 'json';
+        } else {
+            opt.format = 'text';
+        }
+
         // if ( new _(optionsPath).existsSync() ) {
         //     if (userOptions.flows.indexOf('mq') < 0) {
         //         userOptions.flows.splice(0, 0, 'mq')
@@ -811,7 +829,32 @@ function Logger() {
                 // }
             // }
 
-            process.stdout.write(content + '\n');
+            // #M12 — honour the structured (JSON) render mode for the raw console.log
+            // path, which writes straight to stdout and bypasses the container dispatch.
+            // Without this, JSON mode would emit a mix of JSON lines (levelled output) and
+            // plain lines (console.log), breaking a log collector. Text mode is unchanged.
+            if ( opt.format === 'json' ) {
+                var _jsonLine = {
+                    ts     : new Date().toISOString(),
+                    level  : 'info',
+                    bundle : opt.name,
+                    message: content,
+                    group  : opt.name,
+                    msg    : content
+                };
+                // #M12b — stamp the per-request id + elapsed-ms when a request context is
+                // active (process.gina._reqALS). Absent for CLI / boot / off-request logs.
+                if (process.gina && process.gina._reqALS) {
+                    var _reqStore = process.gina._reqALS.getStore();
+                    if (_reqStore) {
+                        _jsonLine.requestId  = _reqStore.requestId;
+                        _jsonLine.durationMs = Date.now() - _reqStore.startMs;
+                    }
+                }
+                process.stdout.write(JSON.stringify(_jsonLine) + '\n');
+            } else {
+                process.stdout.write(content + '\n');
+            }
         }
 
     };

package/framework/{v0.4.5-alpha.1 → v0.4.5}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.4.5-alpha.1",
+  "version": "0.4.5-alpha.2",
   "dependencies": {
     "@rhinostone/swig": "^2.6.0",
     "intl-messageformat": "^11.2.4",

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.4.5-alpha.1/core/gna');
+var _gna = require('./framework/v0.4.5/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.4.5-alpha.1/core/controller');
-var EntitySuper     = require('./framework/v0.4.5-alpha.1/core/model/entity');
+var SuperController = require('./framework/v0.4.5/core/controller');
+var EntitySuper     = require('./framework/v0.4.5/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.4.5-alpha.1/lib/uuid');
+var uuid = require('./framework/v0.4.5/lib/uuid');
 
 module.exports = {