gina 0.1.7 → 0.1.8

package/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    ignore:
+      # Vendored dependencies under framework/v*/ are managed manually.
+      # They are not installed via npm — do not auto-update them.
+      - dependency-name: "*"
+        update-types: ["version-update:semver-patch"]
+    open-pull-requests-limit: 5

package/CHANGELOG.md

@@ -6,6 +6,53 @@ 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 - 2026-03-27
+### Added
+* Added .github/dependabot.yml — weekly npm dependency updates for root package.json; vendored framework deps excluded
+* Added _debugLog / _isDebugLog to server.isaac.js (LOG_LEVEL=debug|trace outputs gray-coded timestamps with [gina:isaac] group tag, matching gna.js and server.js)
+### Changed
+* package.json description updated to: Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency
+### Fixed
+* Removed swig devDependency declarations (package.json.dist) from git — eliminated 6 Dependabot false-positive alerts (lodash, express, phantomjs are swig test-only deps, never installed or reachable at runtime)
+* Popin overlay stuck active after form submit: data-gina-popin-loading attribute was set on XHR readyState 1/3 but never removed on readyState 4 (response complete), leaving the overlay blocking subsequent interactions. Cleared in xhr.onreadystatechange readyState==4, popinClose, and popinReset.
+* Couchbase connector: @include directives sent raw to Couchbase in dev mode — the dev-mode SQL re-read refreshed the query body without re-expanding @include tokens, causing N1QL syntax errors. Dev-mode re-read now applies the same @include expansion as the startup parser.
+
+## 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

package/CONTRIBUTING.md

@@ -0,0 +1,190 @@
+# Contributing to Gina
+
+Gina follows a BDFL governance model — see [GOVERNANCE.md](./GOVERNANCE.md) for how decisions are made. Contributions of all experience levels are welcome.
+
+---
+
+## Table of contents
+
+- [Requirements](#requirements)
+- [Getting started locally](#getting-started-locally)
+- [Running the tests](#running-the-tests)
+- [Development environment](#development-environment)
+- [Debugging](#debugging)
+- [Branch model](#branch-model)
+- [Commit style](#commit-style)
+- [Changelog](#changelog)
+- [Pull request checklist](#pull-request-checklist)
+- [Reporting bugs](#reporting-bugs)
+- [Proposing features](#proposing-features)
+
+---
+
+## Requirements
+
+| Requirement | Version |
+| --- | --- |
+| OS | macOS or Linux (Windows: Docker only) |
+| Node.js | >= 18 |
+| npm | >= 8 |
+| Changie | >= 1.24 |
+
+---
+
+## Getting started locally
+
+Gina must be installed globally — the CLI and framework bootstrapper expect to run from the npm global prefix. Contributors clone directly into that location instead of using `npm install -g .`.
+
+#### 1. Find your global prefix
+
+```bash
+npm config get prefix --quiet
+```
+
+The default is `/usr/local` (system) or `~/.npm-global` (user). The target directory is `${prefix}/lib/node_modules/gina`.
+
+#### 2. Clone into the prefix
+
+```bash
+cd $(npm config get prefix)/lib/node_modules
+git clone https://github.com/Rhinostone/gina.git gina
+cd gina && git checkout develop
+```
+
+#### 3. Run the install scripts
+
+```bash
+node ./script/pre_install.js
+node ./script/post_install.js
+```
+
+#### 4. Verify
+
+```bash
+gina version
+```
+
+---
+
+## Running the tests
+
+The test suite uses Node's built-in `node:test` runner — no additional test dependencies needed.
+
+```bash
+# Run all tests
+node --test test/**/*.test.js
+
+# Run a single file
+node --test test/core/controller.test.js
+```
+
+---
+
+## Development environment
+
+When contributing to the framework, use the `dev` environment. It enables hot-reload, the debug toolbar, and verbose logging that makes it easier to follow what the framework is doing internally.
+
+```bash
+gina framework:set --env=dev
+```
+
+This sets the default environment so you can omit `--env=dev` from subsequent commands. To start the framework:
+
+```bash
+gina start
+```
+
+To follow logs in real time:
+
+```bash
+gina tail --follow
+```
+
+To revert to production defaults:
+
+```bash
+gina framework:set --env=prod
+```
+
+---
+
+## Debugging
+
+### Framework
+
+```bash
+gina start --inspect-gina
+```
+
+### Bundle
+
+```bash
+gina bundle:restart <bundle_name> @<project_name> --inspect=<port_number>
+```
+
+---
+
+## Branch model
+
+| Branch | Purpose |
+| --- | --- |
+| `master` | Stable — merged from `develop` via PR at release time |
+| `develop` | Working branch — all PRs target this branch |
+
+Always branch from `develop` and open your PR against `develop`.
+
+---
+
+## Commit style
+
+Use imperative or gerund sentences, matching the existing log:
+
+```text
+Fixed GlobalContext::whisper() memory leak
+Added _debugLog to server.isaac.js
+Allowing bundle:build to build for dev env
+```
+
+- One logical change per commit
+- No references to AI tools in commit messages, comments, or files
+
+---
+
+## Changelog
+
+Gina uses [changie](https://changie.dev) for changelog management. After any user-facing change, run:
+
+```bash
+changie new
+```
+
+Pick the kind (`Added`, `Changed`, `Fixed`, `Removed`, `Security`) and write the body from the user's perspective. Do **not** edit `CHANGELOG.md` directly — changie generates it at release time from entries in `.changes/unreleased/`.
+
+---
+
+## Pull request checklist
+
+Before opening a PR against `develop`:
+
+- [ ] Tests pass — `node --test test/**/*.test.js`
+- [ ] New behaviour is covered by a test (or an explanation is provided for why it cannot be)
+- [ ] A `changie new` entry exists for any user-facing change
+- [ ] Commit messages follow the style above
+- [ ] Docs updated if public API, CLI, or config schema changed
+
+---
+
+## Reporting bugs
+
+Open a [GitHub issue](https://github.com/Rhinostone/gina/issues) and include:
+
+- Node.js version (`node --version`)
+- Gina version (`gina --version`)
+- Minimal reproduction steps
+- Expected vs actual behaviour
+
+---
+
+## Proposing features
+
+Open a GitHub issue describing the use case **before** writing code. Features that align with the [roadmap](./ROADMAP.md) and architecture are most likely to be accepted. Significant API changes go through a public discussion period before being finalised.

package/GOVERNANCE.md

@@ -0,0 +1,20 @@
+# Governance
+
+Gina follows the **BDFL** (Benevolent Dictator For Life) model with a commitment to transparency.
+
+Gina is developed and maintained by **Martin Luther** ([Rhinostone](https://www.rhinostone.com/)). Final decisions on direction, API design, and releases rest with the maintainer. Community contributions and RFCs are welcome and taken seriously.
+
+## How decisions are made
+
+- **Patches and bug fixes** — reviewed and merged by the maintainer. Open a pull request against `develop`.
+- **New features** — open a GitHub issue describing the use case before writing code. Features that align with the roadmap and architecture are most likely to be accepted.
+- **Breaking changes and API design** — decided by the maintainer after considering community input. Significant changes go through a public discussion period on GitHub before being finalised.
+- **Releases** — scheduled and cut by the maintainer following the [roadmap](./ROADMAP.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to set up the project locally, the commit style, and the PR checklist.
+
+## Code of Conduct
+
+Be respectful. Contributions of all experience levels are welcome.

package/README.md

@@ -171,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:
@@ -229,7 +229,7 @@ Gina is shipped with [Swig](https://node-swig.github.io/swig-templates/) as the
 
 Please, note that you have 2 types of environments : one for the framework, and one for your project & your bundles.
 
-> By default, Gina (the framework) comes with 2 environments : `dev` and `prod`. The default is `prod`. If you are [contributing](./README-4Contributors.md) to the framework or prototyping your application or service, we advise using the `dev` environment.
+> By default, Gina (the framework) comes with 2 environments : `dev` and `prod`. The default is `prod`. If you are [contributing](./CONTRIBUTING.md) to the framework or prototyping your application or service, we advise using the `dev` environment.
 >
 > ```tty
 > gina framework:set --env=dev
@@ -539,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"
 }
 ```
 
@@ -619,6 +619,10 @@ More documentation and tutorials are coming soon !
 
 For the full documentation, visit [https://gina.io/docs/](https://gina.io/docs/)
 
+## Governance
+
+Gina is led by Martin Luther (Rhinostone). Final decisions on direction, API design, and releases rest with the maintainer. Community contributions and RFCs are welcome and taken seriously. See [GOVERNANCE.md](./GOVERNANCE.md) for details.
+
 ## License (MIT)
 
 Copyright © 2009-2026 [Rhinostone](http://www.rhinostone.com/)

package/ROADMAP.md

@@ -0,0 +1,165 @@
+# 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 · Startup cache |
+| **Q3 2026** | `0.3.0` | Async/await · Dev hot-reload · MySQL & PostgreSQL connectors · AI Phase 2 · Tutorials · Mobile backend guide · Route radix tree |
+| **Q4 2026** | `0.4.0` | TypeScript declarations · AI agents (OpenAPI, MCP) · ScyllaDB connector · PWA scaffold · Advanced tutorial · Website redesign · Bun investigation |
+| **Q1 2027** | `0.5.0` | ESM support · Template engine migration · Structured logging |
+| **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
+
+---
+
+## 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 |
+| 📋 | **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 |
+
+---
+
+## 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 |
+| 📋 | **Pluggable template engine** — Swig 1.4.2 stays fully integrated and remains the default. Nunjucks added as a supported alternative (opt-in per project via config). The render layer is abstracted behind a common interface so both engines co-exist. Switching to Nunjucks requires a per-project migration guide (breaking differences: `{% parent %}` → `{{ super() }}`, filter renames, autoescape default, `date` format strings, no `{% spaceless %}` — see docs). | `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 |
+
+---
+
+## Performance
+
+| Status | Feature | Version | Target | Notes |
+| --- | --- | --- | --- | --- |
+| 📋 | **`NODE_COMPILE_CACHE` — V8 bytecode startup cache** | `0.2.0` | Q2 2026 | Node.js 22.8+ caches compiled V8 bytecode to disk. Set once at startup — 30–60% faster cold start on subsequent runs with zero code changes to user bundles. No-op on Node < 22.8, so safe to ship unconditionally. |
+| 📋 | **Route radix tree — compile `routing.json` at startup** | `0.3.0` | Q3 2026 | Current router does linear matching against `routing.json` on every request. Pre-compile routes into a radix tree at bundle startup for O(log n) matching. 2–3x faster routing layer. Internal change — no user-facing API change. |
+| 📋 | **Bun runtime compatibility investigation** | `0.4.0` | Q4 2026 | Prototype Gina under Bun. Two blockers to verify: `require.cache` deletion (dev hot-reload) and `node:http2` completeness. If both pass, Bun gives 3–10x faster startup and meaningful throughput gains. Deliverable: a compatibility report. |
+
+---
+
+## Windows
+
+Windows compatibility is a hard requirement for `1.0.0`. The alpha scope covers all core features: install, scaffold, bundle start/stop, routing, rendering, and basic CLI. Full production-grade parity is post-1.0.0.
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **Windows alpha compatibility** — Install scripts, path handling, symlinks, and bundle lifecycle (start/stop/restart) work correctly on Windows. `bin/gina.bat` kept in sync with `bin/gina`. CI Windows runner required before this can be marked done. Out of scope for alpha: full build system (bash-based), Windows service integration, production-grade process management. | `1.0.0` | Q3 2027 |
+
+---
+
+## Tutorials
+
+| Status | Tutorial | Duration | Version | Target |
+| --- | --- | --- | --- | --- |
+| 📋 | **Using Gina as a mobile backend** — REST API patterns, JSON-only bundles, token auth, CORS, HTTP/2, and the path to OpenAPI/MCP for SDK generation. Docs only — no code changes. | — | `0.3.0` | Q3 2026 |
+| 📋 | **Beginner** — Your first Gina app: install, scaffold, one route, one controller, browser response. Starts from `gina new` — no prior project needed. | 5 min | `0.3.0` | Q3 2026 |
+| 📋 | **Intermediate** — Multi-bundle setup, routing with URL params, entity + connector wiring, template rendering, form handling. Starts from scratch. | ~30 min | `0.3.0` | Q3 2026 |
+| 📋 | **Advanced** — Full production project: authentication, scoped data isolation, async/await, HTTP/2, structured logging, Docker/K8s deployment. Starts from the intermediate tutorial's finished state. | ~60 min | `0.4.0` | Q4 2026 |
+
+---
+
+## Website
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **Official website redesign + docs integration** — Refactor gina.io as a proper project homepage (landing page, feature highlights, showcase) with the documentation fully integrated. Single coherent web presence. Prerequisite: tutorials complete. | `0.4.0` | Q4 2026 |
+
+---
+
+*Last updated: 2026-03-27 · 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) {