gina 0.1.9-alpha.5 → 0.2.0

package/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: gina-automator

package/CHANGELOG.md

@@ -6,6 +6,54 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 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.
+* JSON Schemas for routing.json, app.json, connectors.json, settings.json, app.crons.json — machine-readable schemas at schema/ in the package root. Scaffold templates now include "$schema" references to https://gina.io/schema/ for free editor validation and autocomplete in VS Code and any JSON Schema-aware IDE (#AI1)
+* GitHub Discussions enabled — community Q&A and Show and Tell categories now available on the repo (#A10)
+* Added V8 pointer compression detection at startup: sets GINA_V8_POINTER_COMPRESSED=true and logs heap limit when Node.js is built with --experimental-enable-pointer-compression (#P4)
+* Added unit tests for #M2 entity._arguments buffer management — covers Promise path deletion and DISPATCH:BUFFER_CALLBACK deletion (3 tests, test/core/entity-arguments.test.js)
+* Redis session store connector (CN1): ioredis-backed store with standalone, Cluster, and TLS support; configured via connectors.json — no credentials in application code
+* SQLite session store connector (CN2 v1): node:sqlite-backed store (built-in since Node 22.5.0, zero npm deps) with WAL mode, prepared-statement caching, and background expiry cleanup; supports file-based and ':memory:' databases
+* Added GitHub Actions CI pipeline — runs the full test suite (494+ tests) on Node.js 18, 20, and 22 on every push and PR to `develop` and `master` (#A1)
+* Stable release now auto-tags, merges to master, and publishes the next alpha to npm
+* SQLite ORM connector v2: entity wiring + SQL method generation from .sql files, Option-B Promise/.onComplete() pattern, connector.js (WAL, FK, synchronous open), 56 unit tests
+* Added llms.txt — LLM-optimised framework reference for Cursor, Copilot, Claude.ai
+* Added peerDependencies (all optional) for connector client libraries: couchbase, ioredis, mysql2, pg, mongodb, @scylladb/scylla-driver
+* Added GitHub issue templates (bug_report, feature_request) and PR template
+* SQLite state storage for ~/.gina/ config files (CN2 v3): lib/state.js StateStore routes all state-file writes through node:sqlite (DatabaseSync) for atomic writes and concurrent access safety; JSON sidecars kept for backwards-compat read paths
+* Added WatcherService (lib/watcher): fs.watch-based file-change registry. Reads watchers.json bundle config and starts native file watchers on server startup. Exposes gna.watcher for framework-internal registration (#M6). 9 new tests in test/core/watcher.test.js.
+* bundle:add preserves existing bundle source when the src/ directory already exists and rewrite is false — cloned starter repos are no longer overwritten
+### Changed
+* README: added 3-bullet why-Gina summary, feature highlights table, and Quick start section at the top; added MIT license and Node.js >= 18 badges; updated npm keywords to be search-relevant (http2, multi-bundle, event-driven, rest, api, couchbase) (#A9, #V3)
+### Fixed
+* Removed dead singleton infrastructure from SuperController (SuperController.instance, SuperController.initialized, init()/getInstance() singleton path); removed 4 no-op freeMemory([], false) calls; fixed throwError() HTML error path missing local.req/res/next = null after res.end() (#M1)
+* Added deprecation warning to Couchbase SDK v2 connector: logs on every connection when sdk.version is 2 (EOL since 2021, removal planned for 0.4.0). Adds a separate fatal error when GINA_V8_POINTER_COMPRESSED=true, as v2 NAN bindings are incompatible with pointer-compressed Node.js builds.
+* Fixed DISPATCH:BUFFER_CALLBACK path (util.promisify path in entity method wrappers): entity._arguments[trigger] was consumed but not deleted after use, allowing a buffered result from one request to persist and resolve all subsequent callers with stale data. Now deletes the buffer after consuming, matching the Promise path behaviour (#M2).
+* Retired freeMemory() helper in controller pipeline — replaced all call sites with explicit local.req/res/next nulling so intent is visible at each response exit point (#M3)
+* Fixed `/_gina/info` HTTP/2 endpoint returning `[object Object]` — `stream.end(infoHeaders)` was passing the headers object instead of the JSON string `infoStatus` (#H1)
+* Added stream-closed guard (`stream.destroyed || stream.closed`) to `throwError()` HTML error response path — prevents unhandled error on HTTP/2 when a stream closes between error trigger and response write (#H2)
+* Fixed infinite recursion in connector ping() when keepAlive is false (CB-BUG-4): replaced unconditional self.ping() recursive call with return in v2/v3/v4
+* Removed redundant modelUtil.setConnection() call in connector v2/v3/v4 onConnect() (CB-PERF-3): first unconditional call before the existsSync guard was a no-op duplicate
+* Fixed gina.onError() handler accumulation on Couchbase reconnect (CB-BUG-1): guarded registration with _errorHandlerRegistered flag so only one handler is registered per connector instance across reconnections (v2/v3/v4)
+* Fixed session-store.v3 get() always returning session-not-found (CB-BUG-2): converted to async/await so Promise resolves before checks run — every session lookup was failing silently, forcing re-authentication on every request
+* Fixed session-store.v3 set() silently discarding writes (CB-BUG-3): converted to async/await so upsert is awaited before calling fn() — writes appeared to succeed but were never confirmed
+* Fixed CB-PERF-1 (300ms startup delay), CB-PERF-2 (ping reconnect drops callback), CB-QUAL-2 (eval() for @options parsing), CB-QUAL-3 (bulkInsert returns plain object instead of Promise) in Couchbase connector
+* Fixed CB-QUAL-4, CB-LOW-1–5, CB-LOW-7: sanitised bulkInsert key in N1QL, fixed uuid implicit global, re-enabled strict mode in index.js, removed dead os.version import, removed duplicate use-strict in session-store.v4, added exponential backoff for Couchbase reconnects, removed dead commented-out blocks in connector files
+* Fixed bundle:start hang: JSON.parse(process.argv[3]) in gna.start() threw SyntaxError in CLI mode where argv[3] is the project name (plain string), causing every bundle to crash silently and wait the full 60-second timeout. Added JSON format guard. Also added immediate crash detection in the start.js child watcher for non-zero exits during startup (#B9).
+* Made engine.io a lazy require in server.isaac.js — loaded only when options.ioServer is configured, so bundles without WebSocket support no longer crash at startup if engine.io is absent
+* Made ssl-checker a lazy require in server.js — loaded only inside verifyCertificate(), so bundles not using HTTPS cert verification no longer crash at startup if ssl-checker is absent
+* Fixed Couchbase entity methods called via util.promisify without .bind(): instead of crashing with a cryptic 'Cannot set properties of undefined (setting _isRegisteredFromProto)', the framework now transparently recovers the entity singleton so the call succeeds
+* Fixed EventEmitter listener leak on entity singleton when using util.promisify without .bind() (intermittent 500 errors under repeated requests on the same entity method)
+* Boilerplate templates installed by view:add now render correctly — doubled html/ prefix removed from extends and include paths
+* cache:stats now falls back through all assigned port/scheme combinations instead of trying only the first — fixes ECONNREFUSED on bundles that run HTTP/2 only
+* Fixed entity method concurrency: concurrent callers on the same method now each receive their own result (FIFO queue dispatch replaces single-slot _callbacks; DISPATCH:PREEMPTIVE_BUFFER and consume paths queue-aware)
+* All user-customisable settings (port, debug_port, mq_port, host_v4, hostname, logdir, tmpdir, rundir, log_level) now survive a shortVersion bump (e.g. 0.1 → 0.2) — previously they were silently reset to defaults because post_install pre-creates ~/.gina/<shortVersion>/settings.json from the template before init.js runs, making the migration block unreachable; fixed by detecting the unresolved template and triggering migration in that case too
+### Security
+* Added four missing HTTP/2 server security settings in `isaac.js`: `maxHeaderListSize: 65536` (HPACK bomb defense), `enablePush: false` (deprecated in browsers), `maxSessionRejectedStreams: 100` (RST/rapid reset flood defense — CVE-2019-9514, CVE-2023-44487), `maxSessionInvalidFrames: 1000` (CONTINUATION flood defense — CVE-2024-27316, CVE-2024-27983) (#H3)
+* Fixed Couchbase restQuery() credential exposure and shell injection (CB-SEC-1, CB-SEC-2): replaced exec(curl...) with http.request(), credentials now sent via Authorization header, no shell involved
+* Removed err.stack from HTTP 500 JSON response body in Couchbase connector (CB-QUAL-1): stack traces with filesystem paths now logged server-side only, never sent to clients
+
 ## 0.1.8 - 2026-03-27
 ### Added
 * Added .github/dependabot.yml — weekly npm dependency updates for root package.json; vendored framework deps excluded

package/README.md

@@ -1,8 +1,8 @@
 # Gina <img src="https://gina.io/favicon-16x16.png" alt="Gina icon" style="position: absolute; top:10px; margin-right: 10px;" />
 
-[![npm version](https://badge.fury.io/js/gina.svg)](https://badge.fury.io/js/gina) [![GitHub version](https://badge.fury.io/gh/Rhinostone%2Fgina.svg)](https://badge.fury.io/gh/Rhinostone%2Fgina) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D%2018-brightgreen)](https://nodejs.org) [![Tests](https://github.com/Rhinostone/gina/actions/workflows/test.yml/badge.svg)](https://github.com/Rhinostone/gina/actions/workflows/test.yml)
+[![npm version](https://badge.fury.io/js/gina.svg)](https://badge.fury.io/js/gina) [![GitHub version](https://badge.fury.io/gh/gina-io%2Fgina.svg)](https://badge.fury.io/gh/gina-io%2Fgina) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D%2018-brightgreen)](https://nodejs.org) [![Tests](https://github.com/gina-io/gina/actions/workflows/test.yml/badge.svg)](https://github.com/gina-io/gina/actions/workflows/test.yml)
 
-> **Documentation:** [https://gina.io/docs/](https://gina.io/docs/) · **Issues:** [GitHub](https://github.com/Rhinostone/gina/issues)
+> **Documentation:** [https://gina.io/docs/](https://gina.io/docs/) · **Issues:** [GitHub](https://github.com/gina-io/gina/issues)
 
 Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency.
 

package/ROADMAP.md

@@ -2,7 +2,7 @@
 
 This roadmap covers planned features, architectural improvements, new connectors, and AI integration. Items marked ✅ are shipped. All planned items are open to community contribution — see [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
 
-> **Docs:** [gina.io/docs](https://gina.io/docs/) · **Issues:** [github.com/Rhinostone/gina/issues](https://github.com/Rhinostone/gina/issues)
+> **Docs:** [gina.io/docs](https://gina.io/docs/) · **Issues:** [github.com/gina-io/gina/issues](https://github.com/gina-io/gina/issues)
 
 ---
 
@@ -12,7 +12,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | --- | --- | --- |
 | **Apr 2026** | `0.1.8` ✅ | Scaffold correctness · K8s support · Dependency injection · Automatic version migration |
 | **Q2 2026** | `0.2.0` | Stability · WatcherService · Redis & SQLite connectors · K8s session storage · Startup cache · Pointer compression · Couchbase v2 deprecation · Couchbase security & critical bug fixes · HTTP/2 security hardening |
-| **Q3 2026** | `0.3.0` | Async/await · Dev hot-reload · MySQL & PostgreSQL connectors · AI Phase 2 · Tutorials · Mobile backend guide · Route radix tree · Connector peerDependencies · 103 Early Hints · HTTP/2 observability · Security & CVE page · Couchbase connector hardening · Beemaster Phase 1 |
+| **Q3 2026** | `0.3.0` | Async/await · Dev hot-reload · MySQL & PostgreSQL connectors · AI Phase 2 · Tutorials · Mobile backend guide · Route radix tree · Connector peerDependencies · 103 Early Hints · HTTP/2 observability · Security & CVE page · Per-bundle framework version · Couchbase connector hardening · Beemaster Phase 1 |
 | **Q4 2026** | `0.4.0` | TypeScript declarations · AI agents (OpenAPI, MCP) · ScyllaDB connector · PWA scaffold · Advanced tutorial · Website redesign · Docs offline ZIP · Bun investigation · Couchbase v2 removal · HTTP/2 hardening · Trailer support · Beemaster core |
 | **Q1 2027** | `0.5.0` | ESM support · Template engine migration · Structured logging · Alt-Svc · HTTP/2 priorities · WebSocket over HTTP/2 · Beemaster admin |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
@@ -24,8 +24,9 @@ This roadmap covers planned features, architectural improvements, new connectors
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | ✅ | **Automatic version migration** — Upgrading or downgrading gina (e.g. `0.1.x → 0.2.0`, `0.5.x → 1.0.0`) automatically migrates `~/.gina/` config to the new version on first startup. Downgrade is free — old version data is never removed. | `0.1.8` | 2026-03-26 |
-| 📋 | **`watchers.json`** — First-class bundle config for file watchers. Declare watchers on config files with event-based notification (no polling). Foundation for the dev-mode hot-reload system. | `0.2.0` | Q2 2026 |
+| ✅ | **`watchers.json`** — First-class bundle config for file watchers. Declare watchers on config files with event-based notification (no polling). Foundation for the dev-mode hot-reload system. | `0.2.0` | 2026-03-29 |
 | 📋 | **PWA scaffold** — `gina bundle:add` drops `manifest.json`, a service worker stub (`sw.js`), and the required `<meta>` / `<link>` tags into the bundle boilerplate. Zero runtime dependency. Enables Gina apps to be installed on mobile as PWAs without additional tooling. | `0.4.0` | Q4 2026 |
+| 📋 | **Per-bundle framework version** — Declare `"gina_version": "0.1.8"` on any bundle entry in `manifest.json` to pin that bundle to a specific installed framework version. The socket server continues running its own version; only the spawned bundle process uses the declared version. Validated against the tracked version list in `main.json` before start. `--gina-version=X.Y.Z` flag on `bundle:start` provides the same override without touching config files. | `0.3.0` | Q3 2026 |
 
 ---
 
@@ -36,7 +37,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | ✅ | **Per-request controller instances** — Each HTTP request gets its own isolated controller instance with its own request state. Removes dead singleton infrastructure and fixes edge-case memory retention in error paths. | `0.2.0` | Q2 2026 |
-| 📋 | **Entity `_arguments` buffer scoped to call** — Move the event result buffer from the entity to the individual call, preventing concurrent callers from sharing state. | `0.2.0` | Q2 2026 |
+| ✅ | **Entity `_arguments` buffer scoped to call** — Move the event result buffer from the entity to the individual call, preventing concurrent callers from sharing state. | `0.2.0` | 2026-03-29 |
 | ✅ | **Retire `freeMemory`** — Once per-request instances land (#M1), there is no shared `local` closure to null. Replace `freeMemory` call sites with explicit `local.req = null; local.res = null; local.next = null` at response exit points. | `0.2.0` | Q2 2026 |
 
 ### Phase 2 — Async
@@ -261,4 +262,4 @@ Standalone gina dev and admin tool. A dedicated browser-tab app (`services/src/b
 
 ---
 
-*Last updated: 2026-03-28 (Beemaster added) · To suggest a feature, [open an issue](https://github.com/Rhinostone/gina/issues).*
+*Last updated: 2026-03-29 (Per-bundle framework version added) · To suggest a feature, [open an issue](https://github.com/gina-io/gina/issues).*

package/framework/v0.2.0/VERSION

@@ -0,0 +1 @@
+0.2.0

package/framework/{v0.1.9-alpha.5 → v0.2.0}/core/gna.js

@@ -805,7 +805,25 @@ isBundleMounted(projects, bundlesPath, getContext('bundle'), function onBundleMo
                 //     }
                 // }
 
-                // will start watchers from here
+                // #R1 — start user-defined watchers declared in watchers.json via WatcherService.
+                // conf.watchers is the parsed content of the bundle's watchers.json (auto-loaded
+                // by config.js). conf.bundlePath is the absolute bundle source directory.
+                // Framework internal watchers (#M6) will register against gna.watcher using
+                // WatcherService.register() before calling start().
+                var _watchersConf = (conf && conf.watchers && typeof conf.watchers === 'object')
+                    ? conf.watchers
+                    : null;
+                var _hasUserWatchers = _watchersConf && Object.keys(_watchersConf).some(function(k) {
+                    return k.charAt(0) !== '$';
+                });
+                if (_hasUserWatchers && lib.Watcher) {
+                    var _watcher    = new lib.Watcher();
+                    var _configDir  = conf.bundlePath + '/config';
+                    _watcher.load(_configDir, _watchersConf);
+                    _watcher.start();
+                    // expose so #M6 and user bundle code can register against the same service
+                    gna.watcher = _watcher;
+                }
                 callback()
             })
         }

package/framework/{v0.1.9-alpha.5 → v0.2.0}/core/model/entity.js

@@ -214,32 +214,31 @@ function EntitySuper(conn, caller, injected) {
                                 if (entity._triggers.indexOf(events[i].shortName) > -1) {
                                     console.debug('[ MODEL ][ ENTITY ] Setting promise listener for: [ ' + self.model + '/' + events[i].entityName + '::' + events[i].shortName + ' ]');
 
-                                    if (typeof(entity._arguments) == 'undefined' || typeof(entity._arguments) != 'undefined' && typeof(entity._arguments[events[i].shortName]) == 'undefined') {
-
-                                        if (entity.listenerCount(events[i].shortName) > 0) {
-                                            entity.removeAllListeners([events[i].shortName])
-                                        }
+                                    // #M2 — queue check: buffer is now an array; treat missing/empty as "no buffer".
+                                    if (!entity._arguments || !entity._arguments[events[i].shortName] || entity._arguments[events[i].shortName].length === 0) {
 
+                                        // #M2 — removeAllListeners removed: it was killing the queue
+                                        // dispatch listener registered by concurrent in-flight callers.
                                         entity.once(events[i].shortName, function () { // cannot be `entity.on` for prod/stage
                                             // check if not already fired
                                             if (entity._callbacks[events[i].shortName]) {
 
-                                                entity.removeAllListeners([events[i].shortName]);
                                                 console.log('\nDISPATCH:ONCE_LISTENER ' + events[i].shortName +'('+ events[i].index  +')');
                                                 cb.apply(this, arguments);
                                             }
                                         });
 
 
-                                        // backing up callback
+                                        // backing up callback (scalar — promisify fast-path bypasses queue)
                                         entity._callbacks[events[i].shortName] = cb;
                                     } else { // in case the event is not ready yet
                                         console.log('\nDISPATCH:BUFFER_CALLBACK ' + events[i].shortName);
-                                        // #M2 — consume and delete the buffer so the next caller
-                                        // gets a fresh listener instead of this stale result.
-                                        // Mirrors the delete in the Promise path (Option B, below).
-                                        var _firing2Args = entity._arguments[events[i].shortName];
-                                        delete entity._arguments[events[i].shortName];
+                                        // #M2 — queue consume: shift oldest buffered result so concurrent
+                                        // callers each receive their own result, not a shared stale one.
+                                        var _firing2Args = entity._arguments[events[i].shortName].shift();
+                                        if (entity._arguments[events[i].shortName].length === 0) {
+                                            delete entity._arguments[events[i].shortName];
+                                        }
                                         cb.apply(entity[m], _firing2Args);
                                     }
                                 }
@@ -270,9 +269,9 @@ function EntitySuper(conn, caller, injected) {
                         //   existing callers keep working unchanged:
                         //     entity.method(args).onComplete(function(err, data) {...})
                         //
-                        //   entity._callbacks[shortName] is now used as a boolean
-                        //   guard only (truthy = listener active, null = consumed).
-                        //   The same check as before, just no longer stores the cb.
+                        //   entity._callbacks[shortName] is a FIFO queue (array) of
+                        //   per-invocation resolvers (#M2).  A single persistent .on
+                        //   listener dequeues the oldest resolver on each emit.
                         //
                         // The util.promisify fast-path above (lines 192-229) is
                         //   untouched — it fires when this[m] is undefined (called
@@ -289,56 +288,57 @@ function EntitySuper(conn, caller, injected) {
 
                         if (entity._triggers.indexOf(events[i].shortName) > -1) {
 
-                            if (typeof(entity._arguments) == 'undefined' || typeof(entity._arguments) != 'undefined' && typeof(entity._arguments[events[i].shortName]) == 'undefined') {
+                            // #M2 — queue check: buffer is now an array; treat missing/empty as "no buffer".
+                            if (!entity._arguments || !entity._arguments[events[i].shortName] || entity._arguments[events[i].shortName].length === 0) {
 
-                                if (entity.listenerCount(events[i].shortName) > 0) {
-                                    entity.removeAllListeners([events[i].shortName]);
-                                }
-
-                                // Shared resolver — whichever fires first (DISPATCH:CALLBACK_FLUSH or the
-                                // once-listener) resolves/rejects the Promise. The second call
-                                // is a no-op (guard: _callbacks[shortName] is null after first).
+                                // #M2 — resolver: double-resolution guard replaces the old _callbacks
+                                // delete guard. The queue dispatch listener manages _callbacks —
+                                // _resolver no longer needs to touch it.
                                 //
-                                // Why store a function in _callbacks (not `true`):
-                                //   The entity's custom emit (entity.js:~494) has three conditions
-                                //   that call setListener(). Condition 3 fires when
-                                //   `typeof(_callbacks[type]) != 'undefined'` — which includes
-                                //   boolean `true`. setListener's DISPATCH:CALLBACK_FLUSH then calls
-                                //   `_callbacks[trigger].apply(this, args)` — `true.apply` throws.
-                                //   Storing a function makes DISPATCH:CALLBACK_FLUSH the primary resolution
-                                //   path (same as old code where _callbacks stored the cb).
+                                // _innerResult.then() (connector Promise path) and the queue dispatch
+                                // listener may both call _resolver; the _resolved flag ensures only
+                                // the first call wins.
+                                var _resolved = false;
                                 var _resolver = function(err, data) {
-                                    // Guard: delete after first call to prevent double-resolution.
-                                    // Using delete (not null) so that DISPATCH:CALLBACK_FLUSH's
-                                    // typeof(_callbacks[trigger]) != 'undefined' check correctly
-                                    // sees 'undefined' and skips the null.apply() call.
-                                    if (!entity._callbacks[events[i].shortName]) return;
-                                    delete entity._callbacks[events[i].shortName];
-                                    entity.removeAllListeners([events[i].shortName]);
+                                    if (_resolved) return;
+                                    _resolved = true;
                                     if (err) _reject(err);
                                     else     _resolve(data);
                                 };
 
-                                // once-listener as fallback in case DISPATCH:CALLBACK_FLUSH doesn't run
-                                // (e.g. custom emit conditions not met). cannot be `entity.on`
-                                // for prod/stage — must stay `once`.
-                                entity.once(events[i].shortName, function () {
-                                    _resolver.apply(null, arguments);
-                                });
-
-                                // Store resolver: satisfies condition 3, enables DISPATCH:CALLBACK_FLUSH
-                                entity._callbacks[events[i].shortName] = _resolver;
+                                // #M2 — FIFO queue: push this invocation's resolver instead of
+                                // overwriting the single _callbacks slot.  removeAllListeners is
+                                // removed — it was killing in-flight callers' queue dispatch listener.
+                                if (!entity._callbacks[e]) {
+                                    entity._callbacks[e] = [];
+                                }
+                                entity._callbacks[e].push(_resolver);
+
+                                // Register a single persistent dispatch listener only when none is
+                                // active.  It dequeues the oldest resolver on each emit so concurrent
+                                // callers each receive their own result in arrival order.
+                                if (entity.listenerCount(e) === 0) {
+                                    var _onQueueEmit = function onQueueEmit() {
+                                        var _q = entity._callbacks[e];
+                                        if (!_q || _q.length === 0) return;
+                                        var _fn = _q.shift();
+                                        _fn.apply(null, arguments);
+                                        if (!_q || _q.length === 0) {
+                                            delete entity._callbacks[e];
+                                            entity.removeListener(e, _onQueueEmit);
+                                        }
+                                    };
+                                    entity.on(e, _onQueueEmit);
+                                }
 
                             } else {
-                                // Event already fired — args were buffered in _arguments.
-                                // Resolve/reject immediately from the cached result, then
-                                // delete the buffer so the next call gets a fresh listener
-                                // instead of resolving again with the same stale result.
-                                // Without this delete, any concurrent call that fires before
-                                // the listener is registered (e.g. an alert cron) poisons
-                                // ALL subsequent requests for the entity's lifetime.
-                                var _args = entity._arguments[events[i].shortName];
-                                delete entity._arguments[events[i].shortName];
+                                // Event already fired — args were buffered in _arguments queue.
+                                // #M2 — shift oldest buffered result: concurrent callers each
+                                // consume their own result, not a shared stale scalar.
+                                var _args = entity._arguments[events[i].shortName].shift();
+                                if (entity._arguments[events[i].shortName].length === 0) {
+                                    delete entity._arguments[events[i].shortName];
+                                }
                                 if (_args[0]) _reject(_args[0]);
                                 else          _resolve(_args[1]);
                             }
@@ -356,9 +356,9 @@ function EntitySuper(conn, caller, injected) {
                         // via 'N1QL:entity#method' (different event), so entity.emit() is
                         // never called for them — _promise would hang forever.
                         //
-                        // _resolver already guards against double-resolution: its first call
-                        // deletes _callbacks[shortName], so any subsequent call (from
-                        // DISPATCH:CALLBACK_FLUSH or the once-listener) hits the !_callbacks guard and exits.
+                        // _resolver guards against double-resolution via the _resolved flag (#M2).
+                        // The queue dispatch listener and _innerResult.then() may both call it;
+                        // the flag ensures only the first call wins.
                         //
                         // Additional guard: _resolver is only defined when shortName is in
                         // entity._triggers (lines 268+). If the method returns a Promise
@@ -495,12 +495,14 @@ function EntitySuper(conn, caller, injected) {
                                 this._arguments = {}
                             }
 
-                            // retrieving local arguments, & binding it to the event callback
-                            if ( typeof(this._arguments[trigger]) == 'undefined' ) {
-                                console.log('\nDISPATCH:PREEMPTIVE_BUFFER ' + trigger);
-
-                                this._arguments[trigger] = arguments;
+                            // #M2 — queue mode: push to array so each concurrent caller consumes
+                            // its own buffered result instead of sharing a single scalar slot.
+                            // Before: scalar assignment silently dropped every emit after the first.
+                            if (!this._arguments[trigger]) {
+                                this._arguments[trigger] = [];
                             }
+                            console.log('\nDISPATCH:PREEMPTIVE_BUFFER ' + trigger);
+                            this._arguments[trigger].push(arguments);
 
                         })
                 }
@@ -567,7 +569,9 @@ function EntitySuper(conn, caller, injected) {
         if (
             self._triggers && self._triggers.indexOf(type) == -1 && self._triggers.indexOf(type.replace(/[0-9]/g, '')) > -1
             || self._triggers && self._triggers.indexOf(type) > -1 && typeof(self._callbacks[type]) == 'undefined' && typeof(self._events[type]) == 'undefined'
-            || self._triggers && self._triggers.indexOf(type) > -1 && typeof(self._callbacks[type]) != 'undefined'
+            // #M2 — skip DISPATCH:CALLBACK_FLUSH for queue mode (_callbacks is an array);
+            // the persistent .on dispatch listener handles routing in that case.
+            || self._triggers && self._triggers.indexOf(type) > -1 && typeof(self._callbacks[type]) != 'undefined' && !Array.isArray(self._callbacks[type])
         ) {
             setListener(arguments)
         }

package/framework/v0.2.0/core/template/boilerplate/bundle/config/watchers.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://gina.io/schema/watchers.json"
+}

package/framework/{v0.1.9-alpha.5 → v0.2.0}/core/template/conf/env.json

@@ -45,7 +45,7 @@
       "publicPath": "${bundlesPath}/${bundle}/public",
       "templatesPath": "${bundlesPath}/${bundle}/templates",
       "handlersPath": "${bundlesPath}/${bundle}/templates/handlers",
-      "watchers": "${bundlesPath}/${bundle}/watchers",
+      "watchersPath": "${bundlesPath}/${bundle}/watchers",
       "workersPath": "${bundlesPath}/${bundle}/workers",
       "template": false,
       "server": {

package/framework/{v0.1.9-alpha.5 → v0.2.0}/lib/cmd/bundle/add.js

@@ -312,6 +312,8 @@ function Add(opt, cmd) {
                         if (rewrite) {
                             delete content.bundles[local.bundle]
                         }
+                        // #A6 — pass rewrite flag so createBundle can detect pre-existing source
+                        local.rewrite = rewrite;
                         createBundle()
                     })
                 })
@@ -443,6 +445,15 @@ function Add(opt, cmd) {
             , target    = _( self.projects[self.projectName].path +'/'+ projectData.bundles[local.bundle].src, true )
             , sample    = new _( getPath('gina').core + '/template/boilerplate/bundle/' );
 
+        // #A6 — if source already exists and rewrite is false (new bundle, not replace),
+        // preserve the existing files (e.g. cloned starter repos) and skip the boilerplate copy.
+        if (!local.rewrite && fs.existsSync(target)) {
+            console.log('Bundle [ '+ local.bundle +' ] has been added to your project with success ;)');
+            rl.clearLine();
+            ++local.b;
+            addBundles(local.b);
+            return;
+        }
 
         sample.cp(target, function done(err, destination) {
 

package/framework/{v0.1.9-alpha.5 → v0.2.0}/lib/cmd/framework/init.js

@@ -552,10 +552,20 @@ function Initialize(opt) {
         var localUserSettings = null;
         if ( targetObj.existsSync() ) {
             localUserSettings = requireJSON(target);
-        } else {
-            // MIGRATION: seed networking values from the previous release's settings.json
-            // so port, hostname, etc. survive a short-version bump. All assignments are
-            // env-var-gated so CLI flags or a prior checkIfSettings run take precedence.
+            // post_install.js copies resources/home/settings.json (which has ${...} placeholders)
+            // into ~/.gina/<shortVersion>/settings.json before init.js runs. On a shortVersion
+            // bump the file therefore exists but is an unresolved template — detect this by
+            // checking whether the port field is still a placeholder string, and treat it the
+            // same as "file absent" so the migration block below runs.
+            if (typeof(localUserSettings['port']) === 'string' && localUserSettings['port'].indexOf('${') === 0) {
+                localUserSettings = null;
+            }
+        }
+        if (!localUserSettings) {
+            // MIGRATION: seed user-customisable values from the previous release's settings.json
+            // so port, hostname, logdir, tmpdir, rundir, and log_level survive a short-version
+            // bump. All assignments are env-var-gated so CLI flags or a prior checkIfSettings
+            // run take precedence. On a fresh install no previous version exists — defaults apply.
             var _prevShortForSettings = null;
             for (var _sfk in main['frameworks']) {
                 if (_sfk === '_comment' || _sfk === self.release) continue;
@@ -572,7 +582,11 @@ function Initialize(opt) {
                         'debug_port' : 'GINA_DEBUG_PORT',
                         'mq_port'    : 'GINA_MQ_PORT',
                         'host_v4'    : 'GINA_HOST_V4',
-                        'hostname'   : 'GINA_HOSTNAME'
+                        'hostname'   : 'GINA_HOSTNAME',
+                        'logdir'     : 'GINA_LOGDIR',
+                        'tmpdir'     : 'GINA_TMPDIR',
+                        'rundir'     : 'GINA_RUNDIR',
+                        'log_level'  : 'GINA_LOG_LEVEL'
                     };
                     for (var _smk in _settingsMigrationMap) {
                         if (!getEnvVar(_settingsMigrationMap[_smk]) && typeof(_prevSettings[_smk]) !== 'undefined') {

package/framework/{v0.1.9-alpha.5 → v0.2.0}/lib/index.js

@@ -69,6 +69,9 @@ function Lib() {
         SessionStore    : _require('./session-store'),
         SwigFilters     : _require('./swig-filters'),
         Cache           : _require('./cache'),
+        // #R1 — WatcherService: fs.watch-based file-change registry. Class is hot-reloadable;
+        // instantiated once per bundle in gna.js:onStarted and stored as gna.watcher.
+        Watcher         : _require('./watcher'),
         // replaced: _require('./state') — StateStore is a singleton backed by node:sqlite
         // (DatabaseSync). Hot-reloading it in dev mode would close and re-open the DB
         // connection on every HTTP request, racing with in-flight writes. Use plain

package/framework/v0.2.0/lib/watcher/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "gina-lib-watcher",
+  "version": "1.0.0",
+  "description": "WatcherService — shared fs.watch registry for user-defined and framework watchers",
+
+  "author": {
+    "name": "Maritn-Luther ETOUMAN",
+    "email": "contact@gina.io"
+  },
+  "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "main": "src/main",
+  "scripts": {
+    "test": "node --test test"
+  },
+  "license": "MIT",
+  "readmeFilename": "README.md"
+}