gina 0.1.6 → 0.1.8-alpha.1

package/CHANGELOG.md

@@ -6,6 +6,66 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.1.8-alpha.1 - 2026-03-26
+### Added
+* Config variable interpolation now accepts \${variable} syntax in addition to {variable}. Both forms work in all config files (routing.json, app.json, settings.json, etc.). The {variable} syntax continues to work unchanged — migration to \${variable} is optional and will be documented in a future release.
+* GINA_LOG_STDOUT=true — stdout-only mode for containerised deployments: logs emit as JSON lines (ts, level, group, msg), MQ transport disabled; compatible with kubectl logs, Fluentd, Datadog
+* gina-init: stateless ~/.gina/ bootstrap for Docker/K8s containers — generates projects.json, ports.json, ports.reverse.json, and settings.json from env vars or a mounted JSON config file, with no gina CLI ceremony required
+* critical: false option on this.query(): fire-and-forget HTTP/2 calls can now pass { critical: false } to swallow errors silently (log-only) instead of propagating to throwError and terminating the user-facing response (#H3)
+* critical: false option on this.query(): fire-and-forget HTTP/2 calls can now pass { critical: false } to swallow errors silently (log-only) instead of propagating to throwError and terminating the user-facing response (#H3)
+* HTTP/2 startup warmup: bundles can now declare server.warmup: ['https://upstream:port'] in their server config to pre-establish HTTP/2 sessions at startup. Warmup fires after bundle start, sends an initial PING to verify connectivity, then starts the 5s keepalive cycle — so the first real request reuses a live session instead of cold-connecting (#H5)
+* Couchbase connector: _scope property on entities (mirrors _collection), $scope placeholder substitution in N1QL queries, _scope stored in bulkInsert records. scope read from connectors.json config, falls back to NODE_SCOPE env var
+* Mockable service locator (#R2): getConfig() and getModel() now check for a __mock__ context override before hitting the real implementation. Test setup calls setContext('__mock__', { config: fn, model: fn }) — zero breaking changes, zero business logic changes. Lifts testability from E2E-only to unit-testable models and helpers
+* EntitySuper now accepts optional `injected` 3rd constructor param — `{connector, config}` — for unit testing entities without a running database or framework server (#R3). getConnection() returns injected.connector when set. New this.getConfig() instance method routes through injected.config, falling back to the global getConfig()/__mock__ chain (#R2).
+* SuperController.createTestInstance(deps) — static factory for controller unit testing (#R4). Creates a fresh instance with isolated local closure, wires mock req/res/next/options via setOptions(), marks it with _isTestInstance=true. Production singleton is never modified. Normalises missing conf structure so setOptions doesn't crash on minimal test deps.
+* Auto-migrate main.json and settings.json on first startup of a new short version (e.g. 0.1 → 0.2, 0.5 → 1.0): copies all namespaced keys from the previous release, seeds port/hostname from the previous settings.json. Downgrade is free — old keys are never removed.
+### Changed
+* whisper() now requires \${variable} syntax — bare {variable} placeholders are no longer replaced (migration: update config files and templates to use \${variable})
+* bundle:add now auto-detects system locale and timezone when scaffolding settings.json (LANG/LC_ALL → Intl → en_CM / UTC fallbacks)
+* conf/settings.json locale fallback now auto-detected from GINA_CULTURE at bundle config load (preferedLanguages, region, dateFormat.short, 24HourTimeFormat)
+* conf/settings.json locale defaults now resolved from built-in locale database: currency.code (ISO 4217) and preferedLanguages pulled from core/locales/dist/region/ by country code
+* conf/settings.json locale defaults fully auto-detected: measurementUnits (imperial for US/LR/MM), temperature (fahrenheit for US/BS/KY/PW), firstDayOfWeek from Intl.Locale.getWeekInfo()
+### Fixed
+* Fixed dev-mode resource churn (#B3): DNS resolver and cache wrapper were recreated on every HTTP request because controller.js is re-required each time by the hot-reload mechanism. Both are now persisted on process.gina and reused across re-requires. Eliminates silent abandonment of in-flight DNS lookups and loss of cache-invalidation listeners between requests.
+* Fixed W2 migration regression: resource template placeholders were written as \${} (empty variable) instead of \${variableName}, causing gina CLI to crash with RangeError on container startup. Also added mq_port validation in MQSpeaker to guard against malformed settings values.
+* Fixed W2 migration regression: {variable} → ${variable} in bin/cli, bin/gina-container, core/config.js, entityFactory.js, framework/init.js, bundle/add.js, and resources/locals.json (#B4)
+* Fixed remaining W2 regression: {gina}/{version} in templates test, {Model} in entityFactory boilerplate, {projectPath} in merge test; updated stale framework version import in merge.test.js (#B4)
+* Fixed HTTPS bundle abort on startup: verifyCertificate failure during dev startup (e.g. DNS failure or self-signed cert in containers) was logged at emerg severity, triggering start.js abort detection even though the server was already listening. Downgraded to warn.
+* Fixed rootDomain placeholder detection in config.js to match both `{rootDomain}` (old format) and `${rootDomain}` (new format) after the W2 interpolation migration.
+* getConfig() no-arg now exposes conf.settings — settings.json content is accessible as conf.settings on the bundle conf object, consistent with conf.security
+* Fixed Couchbase connector path resolution in model loader: conf.connectorsPath was never set, causing a MODULE_NOT_FOUND crash on first Couchbase connect.
+* Fixed entity loader in Couchbase connector crashing with TypeError when an entities directory contains helper modules that export plain objects instead of constructor functions.
+* HTTP/2 timeout messages now display in seconds when the value exceeds 1000ms (e.g. 30s instead of 30000ms)
+* HTTP/2 client now retries on GOAWAY mid-stream premature close and on 502 upstream responses. Previously both failures surfaced immediately to callers with no retry, requiring application-level degraded-mode fallbacks. The 502 retry also adds a req.on('response') handler that captures the :status pseudo-header — previously unread, making nginx-level errors indistinguishable from JSON parse failures.
+* renderJSON no longer throws ERR_HTTP2_INVALID_STREAM when the client disconnects (nginx timeout, browser navigation) before an async callback (Couchbase, HTTP/2 upstream) completes. The ServerHttp2Stream destroyed/closed state is now checked before stream.respond() and the request is silently dropped with a warning log.
+* entity.js: guard _resolver before .then() callbacks — prevents uncaught TypeError when a Promise-returning method has no registered trigger in _triggers, which corrupted the event loop
+* Fixed iso_short derivation in framework init — was using country code (cm) instead of language code (en) from culture en_CM
+* Fixed ReferenceError crash on startup: defIsoShort and defDate were referenced outside their declaring function in init.js
+
+## 0.1.7 - 2026-03-20
+### Added
+* Cache: sliding-window expiration and absolute ceiling (maxAge) for HTML and JSON response caches
+* Added gina cache:stats <bundle> @<project> CLI command. Fetches and prints a grouped table of in-memory cache entries from a running bundle. Requires the bundle to be running.
+* Cached routes now emit `Cache-Control` headers synchronised with the server-side TTL. A new optional `visibility` field (`"public" | "private"`, default `"private"`) in the per-route cache config controls the directive sent to browsers and CDNs. The hit path uses the remaining TTL so downstream caches do not over-serve stale content.
+* Per-route outgoing query timeout: add "queryTimeout": <ms> to any routing.json rule and self.query() will use it as the request timeout budget when options.requestTimeout is not explicitly set. The hardcoded 10 s default still applies when neither is set.
+### Changed
+* Cache FS writes in the JSON renderer are now asynchronous (fs.promises.writeFile), avoiding event-loop blocking on cache misses.
+* routing.json queryTimeout field now accepts human-readable strings ("30s", "500ms", "2m", "1h") in addition to integer milliseconds (30000). The value is normalised to ms at parse time so req.routing.queryTimeout is always a number.
+* app.json proxy target field "timeout" renamed to "requestTimeout" — unambiguous name for the per-request outgoing timeout. Update any app.json proxy target that declares a "timeout" to use "requestTimeout" instead. self.query() call sites that passed options.timeout must also be updated to options.requestTimeout.
+* self.query() options field "timeout" renamed to "requestTimeout" — consistent with app.json::proxy.<service>.requestTimeout. The internal pipeline (both HTTP/1 and HTTP/2 handlers) and the defaultOptions fallback now use requestTimeout throughout
+* Entity methods and Couchbase N1QL methods now return a native Promise (Option B). await entity.method(args) works directly without util.promisify. .onComplete(cb) remains fully backward-compatible. Removes the _isRegisteredFromProto guard that was silently dropping queries when a callback-path call preceded a Promise-path call on the same entity.
+### Fixed
+* Sub-second TTL and maxAge values (e.g. ttl: 0.5) now work correctly in the cache. Previously, fractional seconds were truncated to zero, causing immediate eviction.
+* Completed sub-second maxAge fix (#C1): both renderers were pre-truncating maxAge with ~~ before passing it to lib/cache, bypassing the Math.round fix. Removed ~~ from render-swig.js and render-json.js. Also fixed Cache-Status header calculation in server.isaac.js.
+* Cache keys now include the bundle name ("static:{bundle}:{url}" and "data:{bundle}:{url}") to prevent silent cache collisions when two bundles serve the same URL path on the same server instance.
+* Cache entries are now capped via LRU eviction. Cache(options) accepts a `maxEntries` option (default 0 = unlimited); when reached, the least-recently-accessed entry is evicted before each insert. The shared server cache defaults to 1000 entries, configurable via `server.cache.maxEntries` in env.json. The routing cache is capped at 5000 entries (FIFO).
+* Fixed handler files returning 404 when a catch-all root statics mapping (empty key) was defined: staticResources is now sorted by descending path length so specific prefixes like /handlers/ are matched before / in the prefix-regex loop
+* CORS preflight (OPTIONS) requests are now handled before routing: the server responds with HTTP 204 and the correct Access-Control-Allow-Origin header immediately, instead of forwarding to the controller action which returned an error without CORS headers. CORS response headers are now also included on all HTTP/2 JSON responses.
+* self.query() queryTimeout fallback now fires correctly: moved the req.routing.queryTimeout check to before the merge with defaultOptions, which was silently overwriting timeout with the "10s" framework default before the check could run
+* controller.render-swig.js: isRenderingCustomError now detected from both userData and localOptions (set by renderCustomError() in controller.js). Adds null-guard on userData. localOptions is now resolved before the flag check.
+### Security
+* Removed dead framework version v0.1.1-alpha.1 from the repository. Its package.json declared sanitize-html ^2.5.0 (CVE-2021-26539, CVE-2021-26540 — XSS, high severity) and busboy ^0.2.14 (dicer ReDoS). Neither version nor its dependencies were in use.
+
 ## 0.1.6 - 2026-03-08
 ### Added
 * Added JSDoc across core/controller/, core/model/, and helpers/: constructor @class/@constructor/@extends, @inner on private helpers, complete @param/@returns on all public methods, @global on the _ path helper, @module on controller/index.js

package/README.md

@@ -2,6 +2,8 @@
 
 [![GitHub version](https://badge.fury.io/gh/Rhinostone%2Fgina.svg)](https://badge.fury.io/gh/Rhinostone%2Fgina) [![npm version](https://badge.fury.io/js/gina.svg)](https://badge.fury.io/js/gina)
 
+> **Documentation:** [https://gina.io/docs/](https://gina.io/docs/)
+
 <strong>Gina I/O</strong> - Node.js MVC and Event Driven framework
 
 > We are looking for people to help us test and improve `Windows` support.
@@ -169,7 +171,7 @@ __NB.:__ If you are launching the command from the project directory, you don't
 We have just created a frontend application that will host our homepage.
 You will find all bundle sources under `myproject/src`.
 
-__Important:__ Since you are not running a local DNS Server, you have to change the host informations. Go to `myproject/env.json` & replace `dev` hostname from `frontend-{env}-{scope}-v{projectVersionMajor}.{rootDomain}` to `localhost`.
+__Important:__ Since you are not running a local DNS Server, you have to change the host informations. Go to `myproject/env.json` & replace `dev` hostname from `frontend-${env}-${scope}-v${projectVersionMajor}.${rootDomain}` to `localhost`.
 This is a temporary hack and gina will soon be provided with its own local DNS Server.
 
 You can start the bundle with the following command:
@@ -537,7 +539,7 @@ We just need to override Gina default certificate paths
 
 ```json
 {
-    "ca": "{GINA_HOMEDIR}/certificates/scopes/{scope}/{host}/certificate.combined.pem"
+    "ca": "${GINA_HOMEDIR}/certificates/scopes/${scope}/${host}/certificate.combined.pem"
 }
 ```
 
@@ -613,6 +615,10 @@ After this, try again to start, it should run better.
 
 More documentation and tutorials are coming soon !
 
+---
+
+For the full documentation, visit [https://gina.io/docs/](https://gina.io/docs/)
+
 ## License (MIT)
 
 Copyright © 2009-2026 [Rhinostone](http://www.rhinostone.com/)

package/ROADMAP.md

@@ -0,0 +1,124 @@
+# Gina — Roadmap
+
+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)
+
+---
+
+## Timeline
+
+| Period | Version | Focus |
+| --- | --- | --- |
+| **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 |
+| **Q3 2026** | `0.3.0` | Async/await · Dev hot-reload · MySQL & PostgreSQL connectors · AI Phase 2 |
+| **Q4 2026** | `0.4.0` | TypeScript declarations · AI agents (OpenAPI, MCP) · ScyllaDB connector |
+| **Q1 2027** | `0.5.0` | ESM support · Template engine migration · Structured logging |
+
+---
+
+## Features
+
+| 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 |
+
+---
+
+## Modernisation
+
+### Phase 1 — Stability
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **Per-request controller instances** — Each request gets its own controller instance, eliminating shared mutable state under concurrency. | `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 |
+| 📋 | **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
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **Promise adapter for entity calls** — `entityCall(emitter)` wraps the EventEmitter `.onComplete(cb)` pattern in a Promise. Controllers can switch to `async/await` immediately without rewriting entities. | `0.3.0` | Q3 2026 |
+| 📋 | **Async controller actions** — Controller actions become `async function`. Single `try/catch` per action replaces ad-hoc error guards. | `0.3.0` | Q3 2026 |
+
+### Phase 3 — Dev Tooling
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **File-watcher hot-reload** — Replace `delete require.cache` per-request with a `WatcherService` that evicts modules only on actual file change. Controllers and SQL files reload on save with zero per-request overhead. | `0.3.0` | Q3 2026 |
+| 📋 | **SQL annotation parser** — Replace the single-pass regex for N1QL file parsing with a state-machine parser. Handles nested block comments and `--` in string literals correctly. | `0.3.0` | Q3 2026 |
+
+### Phase 4 — DX
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **Explicit exports for global helpers** — `getContext`, `setContext`, `_`, `requireJSON` etc. available as explicit `require('gina/gna').getContext` imports alongside the existing global injection. Enables IDE navigation and static analysis. | `0.4.0` | Q4 2026 |
+| 📋 | **TypeScript declaration files** — `.d.ts` declarations for the public surface: `SuperController`, `EntitySuper`, connector config shapes, `routing.json` schema. No TS migration of internals — just declarations for consumer projects. | `0.4.0` | Q4 2026 |
+
+### Phase 5 — Future
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **ESM compatibility layer** — Dual CJS/ESM entry points via `"exports"` in `package.json`. Framework internals stay CJS; public API gets ESM re-exports. | `0.5.0` | Q1 2027 |
+| 📋 | **Template engine migration** — Replace the abandoned Swig 1.4.2 with a maintained engine. Leading candidate: Nunjucks (identical Jinja2-style syntax — existing templates require no changes). | `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 |
+
+---
+
+## Connectors
+
+New database connectors follow the same interface as the existing Couchbase connector: declared in `connectors.json`, acquired via `getConnection()`.
+
+| Status | Connector | Version | Target | Notes |
+| --- | --- | --- | --- | --- |
+| 📋 | **Redis** | `0.2.0` | Q2 2026 | Session store and general-purpose cache. Client: `ioredis`. Required for K8s horizontal scaling. |
+| 📋 | **SQLite** | `0.2.0` | Q2 2026 | Three use cases: framework state storage (replaces JSON files under `~/.gina/`), session store for single-pod/dev deployments, and embedded ORM connector. Uses `node:sqlite` (Node.js built-in since v22.5.0 — zero npm deps). |
+| 📋 | **MySQL / MariaDB** | `0.3.0` | Q3 2026 | ORM connector. Client: `mysql2`. |
+| 📋 | **PostgreSQL** | `0.3.0` | Q3 2026 | ORM connector. Client: `pg` (node-postgres). |
+| 📋 | **ScyllaDB** | `0.4.0` | Q4 2026 | Cassandra-compatible wide-column store. Client: `@scylladb/scylla-driver`. |
+| 📋 | **MongoDB** | `0.4.0` | Q4 2026 | Document store connector. Client: `mongodb` (official driver). Interface approach TBD — MongoDB's document model differs from the N1QL/SQL pattern used by existing connectors. |
+
+---
+
+## K8s & Docker
+
+| Status | Feature | Version | Date |
+| --- | --- | --- | --- |
+| ✅ | **Graceful shutdown on SIGTERM** — `server.close()` drains in-flight requests with configurable hard timeout (`GINA_SHUTDOWN_TIMEOUT`). | `0.1.8` | 2026-03-06 |
+| ✅ | **`gina-container` foreground launcher** — Drop-in entrypoint for Docker/K8s. Spawns the bundle non-detached, forwards SIGTERM, exits with the child's code. No framework socket server required. | `0.1.8` | 2026-03-06 |
+| ✅ | **Stdout/stderr structured logging** — `GINA_LOG_STDOUT=true` emits JSON lines compatible with `kubectl logs`, Fluentd, and Datadog. | `0.1.8` | 2026-03-21 |
+| ✅ | **`gina-init` — stateless container bootstrap** — Generates all required `~/.gina/` config from env vars or a mounted JSON file. Idempotent. Makes the framework init-container friendly. | `0.1.8` | 2026-03-22 |
+| 📋 | **Session storage for horizontal scaling** — Plug-in session store backed by Redis (#CN1) for multi-pod deployments. Default in-memory store remains available for single-pod and development. | `0.2.0` | Q2 2026 |
+
+---
+
+## AI
+
+### Phase 1 — AI can write Gina code correctly
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **JSON Schemas for config files** — Machine-readable schemas for `routing.json`, `connectors.json`, `app.json`, `settings.json`, `app.crons.json`. Adds `"$schema"` references to generated scaffold files. Gives editors free validation and autocomplete; gives AI assistants authoritative field names so generated config is correct on the first attempt. | `0.2.0` | Q2 2026 |
+| 📋 | **TypeScript declaration files** — Cross-listed with Modernisation Phase 4. Essential for AI code generation accuracy. | `0.4.0` | Q4 2026 |
+
+### Phase 2 — Gina apps can use AI
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **AI connector** — Declare an AI provider in `connectors.json` and acquire a client via `getConnection()`. Supported protocols: `anthropic://`, `openai://`. Follows the same pattern as database connectors. | `0.3.0` | Q3 2026 |
+| 📋 | **`renderStream` — streaming responses** — `self.renderStream(asyncIterable, contentType)` streams SSE or chunked JSON without buffering. Required for LLM token streaming without bypassing the render pipeline. | `0.3.0` | Q3 2026 |
+| 📋 | **Async job pattern for slow AI calls** — First-class "start job → return jobId → poll or webhook on completion" pattern integrated with the cron/queue infrastructure. Prevents LLM latency (1–30s) from blocking the response pipeline. | `0.4.0` | Q4 2026 |
+
+### Phase 3 — AI agents can consume Gina apps
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **OpenAPI spec generation** — `gina bundle:openapi @myproject` emits `openapi.json` from `routing.json`. Zero manual spec writing — route annotations become `description` fields. Makes any Gina app consumable by AI agents, API gateways, and testing tools. | `0.4.0` | Q4 2026 |
+| 📋 | **MCP server wrapper** — `gina bundle:mcp @myproject` exposes `routing.json` routes as MCP (Model Context Protocol) tools. Makes any Gina app a native MCP server discoverable by AI agents. | `0.4.0` | Q4 2026 |
+
+---
+
+*Last updated: 2026-03-26 · To suggest a feature, [open an issue](https://github.com/Rhinostone/gina/issues).*

package/bin/cli

@@ -133,6 +133,21 @@ async function onExec() {
             settings = requireJSON(settingsPath);// jshint ignore:line
         }
 
+        // Guard: settings.json may contain unresolved ${} template placeholders
+        // if it was written by a broken W2 migration. Null out any such values
+        // so env helpers fall back to safe OS defaults and init.js can regenerate
+        // the file correctly on the next framework start.
+        var _hasUnresolved = function(v) { return typeof(v) === 'string' && v.indexOf('${') >= 0; };// jshint ignore:line
+        if (_hasUnresolved(settings['log_level'])) { settings['log_level'] = 'info'; }
+        if (_hasUnresolved(settings['rundir']))     { settings['rundir']    = undefined; }
+        if (_hasUnresolved(settings['logdir']))     { settings['logdir']    = undefined; }
+        if (_hasUnresolved(settings['tmpdir']))     { settings['tmpdir']    = undefined; }
+        if (_hasUnresolved(settings['env']))        { settings['env']       = undefined; }
+        if (_hasUnresolved(settings['scope']))      { settings['scope']     = undefined; }
+        if (_hasUnresolved(settings['mq_port']))    { settings['mq_port']   = 8125; }
+        if (_hasUnresolved(settings['port']))       { settings['port']      = 8124; }
+        if (_hasUnresolved(settings['host_v4']))    { settings['host_v4']   = '127.0.0.1'; }
+        if (_hasUnresolved(settings['hostname']))   { settings['hostname']  = undefined; }
 
         setEnvVar('GINA_LOG_LEVEL', settings['log_level']);// jshint ignore:line
         setEnvVar('GINA_VERSION', version);// jshint ignore:line

package/bin/gina-container

@@ -59,6 +59,21 @@ if (fs.existsSync(settingsPath)) {
     settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
 }
 
+// Guard: settings.json may contain unresolved ${} template placeholders
+// if it was written by a broken W2 migration. Null out any such values
+// so env helpers fall back to safe OS defaults.
+var _hasUnresolved = function(v) { return typeof(v) === 'string' && v.indexOf('${') >= 0; };// jshint ignore:line
+if (_hasUnresolved(settings['log_level'])) { settings['log_level'] = 'info'; }
+if (_hasUnresolved(settings['rundir']))    { settings['rundir']    = undefined; }
+if (_hasUnresolved(settings['logdir']))    { settings['logdir']    = undefined; }
+if (_hasUnresolved(settings['tmpdir']))    { settings['tmpdir']    = undefined; }
+if (_hasUnresolved(settings['env']))       { settings['env']       = undefined; }
+if (_hasUnresolved(settings['scope']))     { settings['scope']     = undefined; }
+if (_hasUnresolved(settings['mq_port']))   { settings['mq_port']   = 8125; }
+if (_hasUnresolved(settings['port']))      { settings['port']      = 8124; }
+if (_hasUnresolved(settings['host_v4']))   { settings['host_v4']   = '127.0.0.1'; }
+if (_hasUnresolved(settings['hostname']))  { settings['hostname']  = undefined; }
+
 // ── 3. Set all GINA_* env vars (mirrors bin/cli bootstrap) ───────────────────
 var arch = process.arch;
 switch (process.arch) {