gina 0.5.24 → 0.5.25

package/CHANGELOG.md

@@ -6,6 +6,25 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.25 - 2026-07-25
+### Added
+* controller:add scaffolds a NAMESPACE controller inside a bundle and prints the paste-ready routing.json rules to wire it. It generates controllers/controller.<name>.js with one JSDoc'd action stub per --controls entry (or a single default action when --controls is omitted), auto-detecting the bundle flavor: a view bundle gets self.render() stubs plus one template per action at templates/html/<name>/<action>.html, while an API-only bundle gets self.renderJSON() stubs and no templates. --api / --views force the flavor. The routing rules are PRINTED for you to paste — routing.json is never edited — so restart the bundle after wiring them. Controller and action names are validated (a lowercase letter followed by letters, digits or underscores; `controller` is reserved), and an existing controller is refused rather than overwritten. Offline CLI command — no bundle rebuild.
+* controller:remove (and its controller:rm alias) removes a namespace controller from a bundle, but only after a reference-aware safety scan. Because a routing rule that names a namespace with no matching controller file silently falls back to the default controller.js rather than erroring, a bare delete is unsafe: controller:remove scans routing.json (both the rule-level namespace and param.namespace) plus requireController() calls across the bundle, and REFUSES the removal if any still point at the controller, listing each one so you can repoint it first. It never edits routing.json. When clean, it confirms interactively, then deletes the controller file and its templates/html/<name>/ tree. --dry-run previews the plan and any blockers, --force deletes the file even with blockers (leaving the references for you to clean up by hand), and --format=json emits a machine-readable envelope. Offline CLI command — no bundle rebuild.
+* controller:rename renames a namespace controller in place, rewriting the structured references to the old namespace so nothing dangles. It moves controllers/controller.<old>.js to controller.<new>.js, moves the templates/html/<old>/ tree, and rewrites the old namespace at the two sites it can do safely: the routing.json namespace values (both the rule-level namespace and param.namespace, via anchored comment-preserving string edits — comments and ordering survive) and every requireController() call. Unlike controller:remove, rename DOES edit routing.json, but only those values. A full plan is shown first, then it confirms interactively before applying all-or-nothing (snapshot-guarded rollback on failure). Anything a static rewrite cannot resolve — a variable namespace, a non-literal requireController() argument, or the cosmetic controller class name — is REPORTED for you to fix by hand, never rewritten. --dry-run previews, --force applies without the prompt, and --format=json emits a machine-readable envelope. Offline CLI command — no bundle rebuild.
+* Added `settings.swig.autoescape` (boolean, default false) to opt in to HTML-escaping of Swig `{{ variable }}` output as an XSS defense, mirroring the existing `settings.nunjucks.autoescape` (default true). Swig's escaping default is unchanged in this release — set the flag to true per bundle to enable it. A non-boolean value now refuses bundle startup, so the security toggle can never be silently mis-typed.
+* Added `server.proxy.requireForwardedHeaders` (settings.json, opt-in, declared in the published schema): when true, a request is classified as reverse-proxied ONLY when it carries an X-Forwarded-Host header — the port-less-Host heuristic is disabled, so internal service-DNS calls can never rewrite the worker's proxy-host context. This is the deterministic option for deployments whose front proxy always sends X-Forwarded-Host, and the only mechanism that also protects renders with no request of their own (worker/cron-driven rendering). Defaults to false (historical heuristic unchanged).
+* Added GET /_gina/health/check on the default (express) engine, mirroring the isaac engine's existing liveness endpoint. It returns 200 with {"status":"healthy","timestamp":<ISO>}, is deliberately ungated (no admin allowlist, no dev gate) so container liveness probes reach it off-loopback, and stays in sync with the isaac fast-path per the /_gina/* built-in endpoint rule. Previously only the isaac engine served it, so bundles on the express engine had no ungated liveness target and had to run the isaac engine just to satisfy a Docker or Kubernetes healthcheck. Server-side only — no bundle rebuild; restart to apply.
+* Added cross-service request-id propagation. The always-on request id (req._ginaReqId, resolved from a sanitised inbound X-Request-Id or a fresh UUID) is now forwarded as x-request-id on every outbound self.query() call — the file-download proxy path plus both the HTTP/1 and HTTP/2 inter-bundle client paths — so one logical request stays correlatable as it fans out across bundles. A caller that sets x-request-id explicitly is never overwritten, and only the sanitised resolved id is forwarded (never a raw inbound header). The server also echoes X-Request-Id back on every response (both engines), so a caller, load balancer, or APM can read the id off the wire; the echo is independent of log format and guarded against an already-sent response. Server-side only — no bundle rebuild; restart to apply.
+* Machine-caller authentication for app routes (MS3): a request presenting `Authorization: Bearer <key>` matching a caller named in `settings.json > auth.machine.callers` now passes the authorization gate without a session — it satisfies `requireAuth`, its configured roles match route `roles` exactly like a session user's, and route policies receive it as `{ name, roles, machine: true }`. Session wins when both are present. Strictly opt-in and fail-closed (`auth.machine.enabled` defaults false; the boot lint refuses malformed shapes); keys support `${secret:KEY}` placeholders and are compared in constant time against boot-computed sha256 hashes — raw keys are not retained after boot. A presented-but-invalid key gets a clean 401 with `WWW-Authenticate: Bearer` (never the login bounce); audit records carry the caller name as the actor key plus `machine: true`, and `self.hasRole()` answers the caller's configured roles.
+* The staged upload progress indicator (`data-gina-form-upload-progress`) gains a `processing` lifecycle state, stamped on `data-gina-upload-progress-state` the moment the browser finishes sending the bytes (`xhr.upload.onloadend`) — the window during which the server post-processes the upload (rendering a preview, transcoding, scanning) before it responds. On a fast link the bytes finish in milliseconds while the server window can run for seconds, during which the bar would otherwise sit frozen at a full `uploading` state; the new state advances the state attribute ONLY, leaving the bar full (value/max/the percent attribute untouched) so a styled bar can show a distinct processing affordance via CSS instead of appearing stuck, and a native indeterminate bar keeps its animation running. Purely additive and i18n-neutral (no wording is hardcoded): a consumer that does not style the new state sees the bar stay full, exactly as before. Browser-bundled — re-bake bundles to pick it up.
+* Authorization contract in `bundle:openapi` — gated routes (`param.requireAuth` / `param.roles` / `param.policy`) now emit a `401` response entry (plus a `403` when roles or a policy add authorization beyond authentication), and when machine-caller auth (`settings.json > auth.machine`) is configured the spec gains `components.securitySchemes.bearerAuth` (`http`/`bearer`) plus a per-operation `security` requirement on gated routes. Role and policy names are never emitted into the spec; an un-gated, un-configured bundle's spec is unchanged.
+* Datastore query errors now carry a transient-vs-permanent classification, so an application can tell a self-healing failure from a real one without string-matching vendor error text. When a connector query fails, the error reaching your controller is stamped with `err.isTransient` (true when a retry after backoff can succeed — a datastore timeout, a dropped connection, a node warming up after a restart, rebalance or failover) and `err.transientReason`, a normalized token naming the condition (`socket:econnrefused`, `postgres:serialization-failure`, `mongo:transient-transaction`, `couchbase:timeout`, …). A controller can branch on it to render an honest "temporarily unavailable, please retry" instead of a generic 500 for a condition that clears itself in seconds. The classifier normalizes signals every driver already carries — socket errno, driver error codes and class names, ANSI SQLSTATE classes, MongoDB error labels, Couchbase N1QL cause codes — across all six datastore connectors (Couchbase, MongoDB, MySQL, PostgreSQL, ScyllaDB, SQLite), and is deliberately conservative: an unrecognized error, or one that is genuinely permanent such as a DNS misconfiguration (ENOTFOUND) or a duplicate key, classifies as permanent. Purely additive — it sets only those two fields, never alters existing ones, and never throws, so nothing changes for code that ignores them. Server-side; restart to pick it up.
+### Fixed
+* A file input that declares only its staging upload action (`data-gina-form-upload-action`) and relies on route defaults for the rest no longer emits a spurious warning-and-error pair — nor writes a visible error into the form's error container — on every bind (and re-bind). The delete action (`data-gina-form-upload-delete-action`, which removes an already-saved file) deliberately has no framework default because its endpoint is app-specific, so its absence is now a quiet debug at bind time; the requirement is still enforced when a delete is actually triggered. Declaring the delete action explicitly — the previous workaround — is no longer needed. Browser-bundled: rebuild your bundles to pick it up.
+* When a staged-upload reset or delete click matches none of the rendered previews, the framework now logs a diagnostic warning instead of silently doing nothing. Previously a zero-match removal skipped its whole cleanup path — the server-side temp-file delete request, the upload-progress-indicator reset, and the removal callback — with no signal, so orphaned temp files could go unnoticed. A normal removal (at least one preview matched) is unchanged. Browser-bundled: rebuild your bundles to pick it up.
+* Fixed absolute URLs poisoned by port-less internal calls (#B152): a request whose Host carries no port — a container health probe on an app route, a service-mesh hop, a sibling-bundle call addressed by service/DNS name — was classified as reverse-proxied and rewrote the worker's proxy-host context, so later renders' `getUrl`/`url` filter output and cross-bundle redirect / error-fallback targets could emit the internal host. The template filters (swig + nunjucks) and both redirect/error-fallback URL builders now prefer the emitting request's own per-request classification on both engines (Express included — the per-request slots are now filled engine-agnostically); the worker-global remains the fallback for renders without a request.
+* The Couchbase connector no longer hangs the request when an N1QL query fails at the socket level — connection refused or reset, or a node still warming up after a restart or rebalance — with no query-error envelope. The three query error handlers read the vendor `cause` unconditionally, so on such a failure a swallowed TypeError left the query callback un-fired and the request never settled (no response, no error page). Each handler now forwards a usable error on both paths — building from the query-error envelope when present, otherwise the raw driver error with its code/errno preserved — and always settles the query. Server-side; restart to pick it up.
+
 ## 0.5.24 - 2026-07-22
 ### Added
 * A per-upload-group `simulateWriteError` flag (honoured outside production scope only) deterministically triggers the multipart write-error path, so you can confirm the guarded-500 crash-guard on your own upload surface after an upgrade — with no filesystem or global-config change that affects real uploads. A group carrying the flag makes every upload tagging it answer HTTP 500 (the same guarded response a real mid-stream write error produces), and a boot warning surfaces the flag if it is ever shipped to production, where it stays inert. Server-side only — restart your bundles to pick it up.

package/README.md

@@ -59,16 +59,21 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.5.24
-
-- **Added — upload progress for the staged upload client layer (#R8, slice 1).** The staging POST of a `data-gina-form-upload-*` file input now reports real client-to-server wire progress. A new registered form event `uploadProgress.<uploadFormId>` carries `{ status, progress, loaded, total, lengthComputable, files }` (per-request aggregate — one staging request carries every file of a selection). Opt-in consumer surfaces: `data-gina-form-upload-on-progress="<windowCallback>"` and a declarative indicator resolved from `data-gina-form-upload-progress="<elementId>"` or the default `<fieldId>-progress` — a native `<progress>` element tracks uploaded/total bytes, any other element gets percent text plus `data-gina-upload-progress` / `data-gina-upload-progress-state` styling hooks. No wording is hardcoded. Browser-bundled — re-bake your bundles. (#R8)
-- **Added — drag-and-drop for the staged upload client layer (#R8, slice 2).** A file input carrying `data-gina-form-upload-dropzone="<elementId>"` binds the named element as a dropzone; files dropped there route through the exact same staging pipeline as a native picker selection (group tagging, staging POST, previews, hidden metadata fields, reset/delete, and upload progress). Opt-in and explicit-id-only, first-wins per zone, only file drags react (text/link drags fall through untouched), and a multi-file drop on a non-`multiple` input keeps the first file with a console warning. The zone exposes `data-gina-upload-dropzone` (owner input id) and `data-gina-upload-dropzone-state` (`idle`/`over`/`dropped`) as pure CSS styling hooks. Browser-bundled — re-bake your bundles. (#R8)
-- **Added — incident ref on error responses (#ERRREF).** Every `throwError` JSON error body now carries a top-level `ref` field — a short voice-relayable correlation code (6 uppercase hex, or a relay-safe caller-supplied value), present in all scopes — and one server-side error-level log line pairs that ref with the full error detail (message, stack, cause) and the request correlation id before the stack-egress gate strips the wire copy, so support can resolve a user-relayed ref to the exact server-side failure even in production. The HTML error surfaces carry the same ref. Also closes two logging gaps: a production API error thrown through the controller previously lost its stack server-side entirely, and message-only server errors logged method/code/url without the message. Always-on, additive and backward-compatible. Server-side — restart your bundles. (#ERRREF)
-- **Added — a per-upload-group `simulateWriteError` flag (honoured outside production only) to verify the upload write-error crash-guard.** Setting it on an upload group makes every upload tagging that group deterministically answer the same guarded HTTP 500 a real mid-stream write error produces — so you can confirm the crash-guard on your own upload surface after an upgrade, with no filesystem or global-config change affecting real uploads. A boot warning surfaces the flag if it ever reaches production, where it stays inert. Server-side — restart your bundles. (#B144)
-- **Fixed — the staged upload client layer no longer corrupts binary file uploads.** The multipart body was hand-assembled as a JS string and transmitted as a DOMString, which UTF-8-inflated every file byte ≥ 0x80 on the wire — a real image/PDF/archive was stored inflated and unreadable (measured ×1.49 on a cycling-byte fixture; a PNG lost its signature). The body is now assembled as a Blob (raw file bytes, transmitted verbatim) with the multipart framing and the `group=` disposition parameter byte-identical to before — no server or wire-contract change; disposition parameter values additionally percent-encode CR/LF/double-quote per RFC 7578. Files corrupted by this defect are losslessly recoverable (the stored bytes are the UTF-8 encoding of the original: decode utf8, re-encode latin1). NOTE the corruption only surfaced on gina ≥ 0.5.22 — the pre-0.5.22 server's since-removed string-decode layers coincidentally reversed the client inflation. Browser-bundled — re-bake your bundles, paired with a server ≥ 0.5.22. (#B148)
-- **Fixed — a misconfigured upload group whose destination directory cannot be created now answers HTTP 500 for that one request instead of crashing the bundle.** Previously the synchronous directory-creation error inside the multipart parser propagated as an uncaught exception and terminated the process on the next upload tagging that group. Server-side — restart your bundles. (#B145)
-- **Fixed — a staged file input declaring only its upload action is no longer silently repointed at the reset/delete route.** When a reset- or delete-action attribute was absent and a default route resolved, the fallback wrote the resolved URL onto the staging action attribute regardless of which attribute it was checking, so the staging POST went to the delete route; it now writes the attribute it was actually checking. Browser-bundled — re-bake your bundles. (#B146)
-- **Fixed — an upload no longer throws in its success handler when no preview element is present.** The preview-container lookup treated a `getElementById` miss (null) as a real element, stored it, and later dereferenced it; it now requires a resolved element, so an upload configured without a preview target completes cleanly. Browser-bundled — re-bake your bundles. (#B147)
+## What's in 0.5.25
+
+- **Added — machine-caller authentication for app routes.** A request presenting `Authorization: Bearer <key>` matching a caller named in `settings.json > auth.machine.callers` now passes the route authorization gate without a session: it satisfies `param.requireAuth`, its configured roles match route `roles` exactly like a session user's, and route policies receive it as `{ name, roles, machine: true }`. A session still wins when both are present. Strictly opt-in and fail-closed — `auth.machine.enabled` defaults false and the boot lint refuses every malformed shape rather than silently running open. Keys accept `${secret:KEY}` placeholders and are compared in constant time against sha256 hashes computed at boot, so raw keys are not retained; a presented-but-invalid key gets a clean `401` with `WWW-Authenticate: Bearer` and never the login redirect. Audit records carry the caller name as the actor plus `machine: true`, and `self.hasRole()` answers the caller's roles. An optional `auth.machine.authenticator` hook verifies any other sync-checkable credential (a JWT signature, an HMAC header, an `x-api-key` scheme). Server-side — restart your bundles. (MS3)
+- **Added — cross-service request-id propagation.** The always-on request id is now forwarded as `x-request-id` on every outbound `self.query()` call — the file-download proxy path and both the HTTP/1 and HTTP/2 inter-bundle client paths — so one logical request stays correlatable as it fans out across bundles. A caller that sets `x-request-id` explicitly is never overwritten, and only the sanitised resolved id is forwarded (never a raw inbound header). The server also echoes `X-Request-Id` back on every response on both engines, so a caller, load balancer or APM can read the id off the wire. Server-side — restart your bundles. (MS1)
+- **Added — `GET /_gina/health/check` on the default (express) engine**, mirroring the isaac engine's existing liveness endpoint. It returns `200` with `{"status":"healthy","timestamp":<ISO>}` and is deliberately ungated — no admin allowlist, no dev gate — so container liveness probes reach it off-loopback. Previously only isaac served it, so express bundles had no ungated liveness target and had to switch engines just to satisfy a Docker or Kubernetes healthcheck. Server-side — restart your bundles. (MS2)
+- **Added — the authorization contract in `bundle:openapi`.** Gated routes (`param.requireAuth` / `param.roles` / `param.policy`) now emit a `401` response entry, plus a `403` when roles or a policy add authorization beyond authentication, and a bundle with machine-caller auth configured gains `components.securitySchemes.bearerAuth` (`http`/`bearer`) with a per-operation `security` requirement on gated routes. Role and policy names are never emitted into the spec, and an un-gated, un-configured bundle's spec is byte-unchanged. (MS4)
+- **Added — the `controller:` CLI group.** `controller:add` scaffolds a namespace controller with one JSDoc'd action stub per `--controls` entry, auto-detecting the bundle flavor (a view bundle gets `self.render()` stubs plus a template per action; an API bundle gets `self.renderJSON()` stubs), and prints the paste-ready `routing.json` rules rather than editing your routing. `controller:remove` (alias `controller:rm`) deletes one only after a reference-aware scan of `routing.json` and every `requireController()` call — because a routing rule naming a namespace with no controller file silently falls back to the default controller instead of erroring, a bare delete is unsafe, so it refuses and lists the blockers. `controller:rename` renames in place and rewrites the references it can do safely, reporting anything a static rewrite cannot resolve rather than guessing. All three support `--dry-run` and `--format=json`; remove and rename confirm interactively and support `--force`. Offline CLI — no bundle rebuild. (#R9)
+- **Added — transient-vs-permanent classification for datastore connector errors.** When a connector query fails, the error reaching your controller now carries `err.isTransient` (true when a retry after backoff can succeed — a datastore timeout, a dropped connection, a node warming up after a restart, rebalance or failover) and `err.transientReason`, a normalized token naming the condition (`socket:econnrefused`, `postgres:serialization-failure`, `mongo:transient-transaction`, `couchbase:timeout`, …). A controller can branch on it to render an honest "temporarily unavailable, please retry" instead of a generic 500 for a condition that clears itself in seconds — without hand-rolling a vendor-error classifier. It normalizes signals every driver already carries (socket errno, driver codes and class names, ANSI SQLSTATE classes, MongoDB error labels, Couchbase N1QL cause codes) across all six datastore connectors, and is deliberately conservative: an unrecognized error, or a genuinely permanent one such as a DNS misconfiguration or a duplicate key, classifies as permanent. Purely additive — it sets only those two fields and never throws. Server-side — restart your bundles. (#CE1)
+- **Added — `settings.swig.autoescape`** (boolean, default false) to opt in to HTML-escaping of Swig `{{ variable }}` output as an XSS defense, mirroring the existing `settings.nunjucks.autoescape`. Swig's escaping default is unchanged in this release — set the flag per bundle to enable it. A non-boolean value now refuses bundle startup, so the security toggle can never be silently mis-typed.
+- **Added — `server.proxy.requireForwardedHeaders`** (opt-in, declared in the published schema): when true, a request is classified as reverse-proxied only when it carries an `X-Forwarded-Host` header, disabling the port-less-Host heuristic so internal service-DNS calls can never rewrite the worker's proxy-host context. This is the deterministic option for deployments whose front proxy always sends `X-Forwarded-Host`, and the only mechanism that also protects renders with no request of their own (worker- or cron-driven rendering). Defaults to false — the historical heuristic is unchanged.
+- **Added — a `processing` state on the staged upload progress indicator.** `data-gina-upload-progress-state` is stamped `processing` the moment the browser finishes sending the bytes — the window during which the server post-processes the upload (rendering a preview, transcoding, scanning) before it responds. On a fast link the bytes finish in milliseconds while that window can run for seconds, during which the bar would otherwise sit frozen at a full `uploading` state; the new state advances the state attribute only, leaving the bar full so a styled bar can show a distinct processing affordance via CSS, and a native indeterminate bar keeps animating. Purely additive and i18n-neutral. Browser-bundled — re-bake your bundles. (#R8)
+- **Fixed — absolute URLs poisoned by port-less internal calls.** A request whose `Host` carries no port — a container health probe on an app route, a service-mesh hop, a sibling-bundle call addressed by service or DNS name — was classified as reverse-proxied and rewrote the worker's proxy-host context, so later renders' `getUrl` / `url` filter output and cross-bundle redirect and error-fallback targets could emit the internal host. The template filters (swig and nunjucks) and both URL builders now prefer the emitting request's own per-request classification on both engines, Express included; the worker-global remains the fallback for renders without a request. Server-side — restart your bundles. (#B152)
+- **Fixed — the Couchbase connector no longer hangs the request when an N1QL query fails at the socket level** — connection refused or reset, or a node still warming up after a restart or rebalance — with no query-error envelope. The three query error handlers read the vendor `cause` unconditionally, so on such a failure a swallowed `TypeError` left the query callback un-fired and the request never settled: no response, no error page. Each handler now forwards a usable error on both paths and always settles the query. Server-side — restart your bundles. (#B153)
+- **Fixed — a file input declaring only its staging upload action no longer emits a spurious warning-and-error pair** — nor writes a visible error into the form's error container — on every bind and re-bind. The delete action deliberately has no framework default because its endpoint is app-specific, so its absence is now a quiet debug at bind time; the requirement is still enforced when a delete is actually triggered. Declaring the delete action explicitly, the previous workaround, is no longer needed. Browser-bundled — re-bake your bundles.
+- **Fixed — a staged-upload reset or delete click that matches none of the rendered previews now logs a diagnostic warning instead of silently doing nothing.** Previously a zero-match removal skipped its whole cleanup path — the server-side temp-file delete request, the progress-indicator reset, and the removal callback — with no signal, so orphaned temp files could go unnoticed. A normal removal is unchanged. Browser-bundled — re-bake your bundles. (#B150)
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -49,6 +49,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.5.22` ✅ | **Fixed**: multipart binary uploads arrive byte-identical — file payloads are no longer string-decoded on their way to disk, so images, PDFs and archives stop arriving mangled and mis-sized (pure-ASCII payloads were unaffected, which is what hid it), and `req.files[].size` reports the real on-disk byte count (#B103) · link HTML callbacks work and no longer break the link — `data-gina-link-event-on-success` / `-on-error` used to make every click throw before the request was opened, leaving a dead link; both attributes now fire a `window`-level function with `(event, result)`, the programmatic `gina.link.on()` channel unchanged (#B141) · reopening an AJAX popin renders current content instead of the previous open's — the content cache now dies with the open it warmed, and `data-gina-dialog-preload="false"` becomes a hard always-refetch guarantee (#B139) · FormValidator — numbered `is<N>` rules keep their distinct error keys on re-validation instead of collapsing onto a doubled bare `is` (#B138), a `query` rule failure can no longer hang the submit pass (#B87), and the #49 checkbox migration warnings name the payload-only remedy and can be silenced per form (#B125) · `page.view.locale` carries the real country record instead of an empty object (#B101) · `npm install -g gina` no longer dies when the effective npm prefix contains a path segment npm's redactor masks (#B126) · **Added**: the `settings.i18n.cultures` allowlist is honoured — a non-empty array constrains which cultures the user-signal negotiation steps may match, so a shipped-but-unlaunched catalog stays unreachable until listed; the whole `i18n` block is now in the published schema · **Changed**: runtime pins moved to the standard `engines` manifest key, so unsupported runtimes finally get npm's `EBADENGINE` warning |
 | **Q3 2026** | `0.5.23` ✅ | **Fixed**: multipart `req.files[].size` now reports the exact stored byte count — the value was snapshotted before the write pipeline finished counting, coming up a varying whole-chunk short (file bytes on disk were always intact); it is finalized before the request resumes, so `self.store()` and any persister see the real size (#B142) · a multi-file multipart upload no longer hangs when an early small file finishes while a later large part is still streaming — the per-stream completion listeners now arm at creation (an already-finished stream's event never replays), and a mid-stream write error answers a guarded 500 instead of crashing the bundle; single-file uploads were unaffected (#B143) · the stale-release banner (`server.releaseWatch`) is now injected by the async template-loader render delegates too — a bundle on a custom async loader got the `/_gina/release/*` endpoints and SSE but no in-page banner; both async delegates (swig / nunjucks) now splice it onto the finalized HTML like the sync paths, CSP-nonce-aware, byte-inert outside the gate (#RWATCH) |
 | **Q3 2026** | `0.5.24` ✅ | **Added**: upload progress for the staged upload client layer — the staging POST reports real client-to-server wire progress via a new `uploadProgress.<id>` form event and an opt-in declarative `<progress>` / percent indicator (#R8, slice 1) · drag-and-drop — a file input binds a named element as a dropzone that routes dropped files through the exact same staging pipeline as the native picker, opt-in and explicit-id-only with `idle`/`over`/`dropped` CSS state hooks (#R8, slice 2) · an incident `ref` on every error response — a short voice-relayable correlation code (present in all scopes) that a server-side log line pairs with the full error detail before the wire copy is stripped, so support can resolve a user-relayed ref to the exact failure even in production (#ERRREF) · a per-upload-group `simulateWriteError` flag (non-production only) to verify the upload write-error crash-guard on your own surface after an upgrade (#B144) · **Fixed**: the staged upload client layer no longer corrupts binary uploads — the multipart body is now a Blob of raw file bytes instead of a UTF-8-inflating DOMString, so images / PDFs / archives are stored byte-identical (the defect only surfaced on gina ≥ 0.5.22; corrupted files are losslessly recoverable) (#B148) · a misconfigured upload group whose destination directory cannot be created answers a guarded 500 instead of crashing the bundle (#B145) · a file input declaring only its upload action is no longer silently repointed at the reset/delete route (#B146) · an upload no longer throws in its success handler when no preview element is present (#B147) |
+| **Q3 2026** | `0.5.25` ✅ | **Added**: microservices readiness — machine-caller authentication (an `Authorization: Bearer` key named in `settings.json > auth.machine.callers` satisfies route authorization without a session, opt-in and fail-closed, constant-time compared against boot-computed hashes, with an optional custom authenticator hook for JWT/HMAC/api-key schemes), cross-service request-id propagation (the always-on request id forwarded as `x-request-id` on every `self.query()` and echoed back on every response, so one logical request stays correlatable across bundles), an ungated `GET /_gina/health/check` on the express engine so container liveness probes no longer require the isaac engine, and the authorization contract in `bundle:openapi` (gated routes emit `401`/`403` entries and a `bearerAuth` security scheme, never role or policy names) · the `controller:` CLI group — `controller:add` scaffolds a namespace controller with per-action stubs and prints paste-ready routing rules, `controller:remove`/`rm` deletes only after a reference-aware scan that refuses while any routing rule or `requireController()` still points at it, and `controller:rename` rewrites the references it can resolve safely and reports the rest (#R9) · transient-vs-permanent classification for datastore connector errors — `err.isTransient` + a normalized `err.transientReason` on every connector query failure across all six datastore connectors, so an application can render an honest retry response without string-matching vendor error text; conservative by design, an unrecognized or genuinely permanent error classifies as permanent (#CE1) · `settings.swig.autoescape` to opt in to Swig output escaping (default unchanged; a non-boolean now refuses boot) · `server.proxy.requireForwardedHeaders` to require `X-Forwarded-Host` for proxy classification, the deterministic alternative to the port-less-Host heuristic · a `processing` state on the staged upload progress indicator, covering the server post-processing window so a full bar reads as working rather than stuck (#R8) · **Fixed**: absolute URLs poisoned by port-less internal calls — a health probe, service-mesh hop or service-DNS sibling call could rewrite the worker's proxy-host context and leak the internal host into later renders' `getUrl`/`url` output and cross-bundle redirect targets; emitting requests now prefer their own classification on both engines (#B152) · the Couchbase connector no longer hangs a request when an N1QL query fails at the socket level with no query-error envelope — the callback went un-fired and the request never settled (#B153) · a file input declaring only its staging upload action no longer emits a spurious warning-and-error pair on every bind · a staged-upload removal matching no preview now logs a diagnostic instead of silently skipping its whole cleanup path, including the temp-file delete (#B150) |
 | **Q4 2026** | `0.6.0` | Security & compliance controls (technical safeguards mapping to PCI-DSS / SOC2 / HIPAA) |
 | **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
@@ -127,6 +128,9 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | ✅ | **`image:build` — first-class OCI packaging** — Packages a project bundle as a standard OCI image: synthesizes a Containerfile + build context from the project's registered state (bundles, entry, ports, env model, node floor) and executes the build with buildah — natively on Linux, or on a container host reached over ssh (`GINA_CONTAINER_HOST=ssh://[user@]host[:port]` env override → native buildah → `container.host` settings fallback). The selected `--env` bakes dev/prod parity: a non-dev env ships the release tree built in-image by `gina bundle:build` (never dev-mode hot-reload); the image boots via `gina-init` + `gina-container` (SIGTERM drain) and `EXPOSE` is computed deterministically from the `gina-init` port allocator. `${secret:KEY}` config placeholders ride byte-verbatim and resolve from the container environment at runtime — never baked. `--emit` prints the Containerfile + context manifest without building; `--format=json` emits a one-shot `{ project, bundle, image, tag, imageId?, durationMs, host, exposedPort }`; `--stream` emits NDJSON progress frames (`start` → `step` → `log` → `done` \| `error`); failures exit 1 with the reason on stdout. | `0.5.11-alpha.2` | 2026-07-05 |
 | ✅ | **`image:list` / `image:rm`** — Host-level image management on the container host `image:build` targets, resolved with the same precedence (`GINA_CONTAINER_HOST=ssh://[user@]host[:port]` env override → native buildah → `container.host` settings fallback); no `@<project>` argument. `image:list` prints every image on the host — an aligned table or `--format=json` (`{ host, images: [{ ref, id, size, created }] }`); the listing is deliberately unfiltered (a synthesized image carries no distinguishing label to filter on). `image:rm <ref>` removes one explicitly-named image — no bulk delete; `--force` maps to `buildah rmi -f`. | `0.5.19-alpha.2` | 2026-07-17 |
 | ✅ | **`image:run` / `container:ps` / `container:stop` — running images on the container host** — Runs a built OCI image as a container on the same host every `image:*` verb resolves (`GINA_CONTAINER_HOST=ssh://[user@]host[:port]` env override → native → `container.host` settings), driving `podman` — buildah builds images but cannot run them, and a build-only host (buildah present, podman absent) is reported honestly (`run unavailable on this host … needs podman + conmon`) rather than as an opaque exec failure. `image:run <image>` is detached by default and prints the container id alone on stdout (`--format=json` → `{ host, id, name, image, ports }`); with no `--publish` the image’s own baked `EXPOSE` is published same:same, `--publish=<host:ctr>[,…]` overrides, `--publish=none` disables; `--env-var=K=V` (repeatable) and `--env-file=<path>` hand environment values to the container without ever placing them in a process argv or baking them into the image; `--rm`; `--stream` runs it in the foreground and mirrors the container as NDJSON frames (`start` → `log` → `done` \| `error`, carrying the container’s own exit code). `container:ps [--all]` lists the host’s containers (aligned table or `--format=json` with normalized port maps); `container:stop <name|id> [--time=<s>] [--force]` stops one and reports the rung it came down on — `graceful` (the container handled the signal), `killed` (force-killed after the grace period) or `forced` (`--force`) — read from a post-stop inspect, since podman exits 0 either way. | `0.5.19-alpha.2` | 2026-07-17 |
+| ✅ | **`controller:add`** — Scaffold a namespace controller into a bundle and print the paste-ready `routing.json` rules to wire it. `controller:add <name> <bundle> @<project> [--controls=a,b,c]` writes `controllers/controller.<name>.js` with one JSDoc'd action stub per `--controls` entry (a single `default` action when omitted) — `render()` stubs plus per-action templates (`templates/html/<name>/<action>.html`) in a view bundle, `renderJSON()` stubs in an API-only bundle (auto-detected, `--views` / `--api` to override) — and prints the routing rules with an explanation. The hand-maintained, comment-bearing routing file is **never** edited (an opt-in `--with-route` writer is deferred on-demand); refuses to overwrite an existing controller. | `0.5.25-alpha.2` | 2026-07-23 |
+| ✅ | **`controller:remove` / `controller:rm`** — Remove a namespace controller from a bundle, reference-aware and refuse-unless-clean: scans the bundle's `routing.json` `namespace` keys (rule-level and `param.namespace`), `requireController('<name>')` call sites, and the namespace template tree, lists every blocking reference, and deletes the controller file + `templates/html/<name>/` tree only after interactive confirmation. `--dry-run` previews, `--force` deletes the file only (never editing `routing.json`, listing what remains to clean), `--format=json` emits a machine-readable envelope; the default `controller.js` is never removable. | `0.5.25-alpha.2` | 2026-07-23 |
+| ✅ | **`controller:rename`** — Rename a namespace controller and rewrite the references that point at it: moves the controller file, moves its `templates/html/<old>/` tree, and rewrites the `routing.json` `namespace` values + `requireController('<old>')` literals with comment-preserving string ops. Reports (does not rewrite) anything a static rewrite cannot resolve — a `param.namespace` `:variable`, a non-literal `requireController()` argument, the cosmetic class name. Shows the full plan then confirms interactively; `--dry-run` previews, `--force` applies non-interactively, `--format=json` emits the plan envelope. | `0.5.25-alpha.2` | 2026-07-23 |
 
 ---
 
@@ -266,6 +270,9 @@ Technical-safeguard primitives that map to the **PCI-DSS**, **SOC2**, and **HIPA
 | 📋 | **Application-level rate limiting** — Per-endpoint / per-client throttling at the route layer (today only an HTTP/2 rapid-reset limiter exists). Maps to PCI-DSS anti-automation and SOC2 availability. | `0.6.x` | Q4 2026 |
 | 📋 | **Data-at-rest / field-level encryption helpers** — Field-level encryption + key-management utilities. Maps to PCI-DSS req 3 and HIPAA §164.312(a)(2)(iv). | `0.6.x` | Q4 2026 |
 | 📋 | **Compliance control-mapping guide** — A reference mapping each Gina control to the PCI-DSS / SOC2 / HIPAA requirement it supports, plus an explicit "what the framework does not cover" section (to follow). | `0.6.x` | Q4 2026 |
+| 📋 | **Transport-security posture** — A production-scope HTTPS enforcement option (refuse or warn when a bundle serves plain HTTP outside local/dev scope), with a "TLS terminates upstream" escape hatch for the common mesh/ingress pattern, plus documented guidance for terminating mTLS at the mesh or ingress. Maps to the "encrypt everywhere / no implicit network trust" principle of NIST SP 800-207 (Zero Trust). | `0.6.x` | Q4 2026 |
+| 📋 | **Deny-by-default authorization mode** — An opt-in posture where every route requires authentication unless explicitly marked public, inverting today's per-route opt-in (a route that declares nothing is currently untouched). Complements the shipped Authorization / RBAC control. Maps to NIST SP 800-207 least-privilege / deny-by-default. | `0.6.x` | Q4 2026 |
+| 📋 | **Zero-Trust deployment guide** — A guide to running Gina inside a zero-trust architecture (NIST SP 800-207): terminating mTLS at the mesh/ingress, enforcing HTTPS, applying network default-deny between services, and shipping the built-in audit/metrics telemetry to a SOC. An honest-boundary companion to the compliance control-mapping guide — the framework supplies the enforcement point, identity, and telemetry; the deployment supplies transport identity and segmentation. | `0.6.x` | Q4 2026 |
 
 ---
 

package/bin/cli

@@ -342,6 +342,7 @@ async function onExec() {
         'cache:',
         'connector:',
         'container:',
+        'controller:',
         'dev:',
         'env:',
         'i18n:',

package/framework/v0.5.25/VERSION

@@ -0,0 +1 @@
+0.5.25

package/framework/{v0.5.24 → v0.5.25}/core/asset/plugin/dist/vendor/gina/js/gina.js

@@ -12003,6 +12003,23 @@ function ValidatorPlugin(rules, data, formId, culture) {
                     if (uploadProgressHFormIsRequired)
                         triggerEvent(gina, $target, 'uploadProgress.' + id + '.hform', result);
                 };
+
+                // #R8 — bytes-done → server post-processing window. onloadend is the
+                // final upload-phase event (fires on success AND on abort/error/timeout),
+                // so it robustly marks "sending finished" even when a browser omits the
+                // final onprogress at loaded==total. Advance the indicator STATE only —
+                // updateUploadProgressIndicator's `processing` branch leaves value/max/the
+                // percent attribute exactly as the last onprogress left them, so a styled
+                // (appearance:none) determinate bar stays visually full instead of
+                // regressing to an empty track. onUpload later flips complete/error at the
+                // response chokepoint, cleanly overwriting `processing`.
+                xhr.upload.onloadend = function() {
+                    if (!isUploadXhr) return;
+                    updateUploadProgressIndicator(
+                        ($target.uploadProperties) ? $target.uploadProperties.progressContainer : null,
+                        'processing'
+                    );
+                };
             }
 
             // catching timeout
@@ -12199,12 +12216,17 @@ function ValidatorPlugin(rules, data, formId, culture) {
      * Every target also carries two data attributes as styling hooks:
      * `data-gina-upload-progress` (integer percent, absent while indeterminate)
      * and `data-gina-upload-progress-state`
-     * (`preparing|uploading|indeterminate|complete|error`). No copy/labels are
-     * hardcoded — wording is the consumer's concern (CSS on the state attribute).
+     * (`preparing|uploading|indeterminate|processing|complete|error`). No copy/labels
+     * are hardcoded — wording is the consumer's concern (CSS on the state attribute).
+     * The `processing` state marks bytes-sent → awaiting-response (server-side
+     * post-processing): it advances the state attribute ONLY, leaving value/max/the
+     * percent attribute exactly as the last `uploading` update left them, so a styled
+     * determinate bar stays visually full (an indeterminate one keeps animating)
+     * through the window rather than regressing to an empty track.
      * The `reset` state strips everything this layer ever set on the element.
      *
      * @param {string|null} containerId - resolved indicator element id
-     * @param {string} state - `preparing` | `uploading` | `indeterminate` | `complete` | `error` | `reset`
+     * @param {string} state - `preparing` | `uploading` | `indeterminate` | `processing` | `complete` | `error` | `reset`
      * @param {object} [result] - `uploadProgress` payload (`progress`, `loaded`, `total`) — read for `uploading` only
      *
      * @returns {undefined}
@@ -12230,6 +12252,16 @@ function ValidatorPlugin(rules, data, formId, culture) {
 
         $indicator.setAttribute('data-gina-upload-progress-state', state);
 
+        if (state == 'processing') {
+            // #R8 — byte-complete, server still post-processing. Advance the STATE only:
+            // leave value/max and the `data-gina-upload-progress` percent exactly as the
+            // last `uploading` update left them (a determinate bar stays full; an
+            // indeterminate one keeps its native animation). Falling through to the guard
+            // below would strip `value` + the percent attribute — the regression this
+            // early return prevents (the state attribute is already stamped above).
+            return;
+        }
+
         if (state == 'complete') {
             if (isNativeProgress) {
                 if ( !$indicator.getAttribute('max') ) {
@@ -12875,6 +12907,20 @@ function ValidatorPlugin(rules, data, formId, culture) {
             }
         }
 
+        // #B150 — the removal loop matched zero previews against the input's
+        // customFiles, so NOTHING was removed: the tmp-delete XHR, the #R8
+        // indicator strip, and the removal callback below are all `removedCount>0`
+        // -gated and are about to be skipped, silently, leaving any staged tmp
+        // files on the server. That is expected when there was nothing to remove
+        // (an empty preview set), but a NON-EMPTY preview set that matched nothing
+        // is a state desync (e.g. a runtime-injected bind whose customFiles names
+        // do not line up with the rendered `data-upload-original-filename`s) —
+        // signal it so the otherwise-invisible skip is diagnosable. Signal-only:
+        // the `removedCount>0` gates STAY (no removal => no removal callback, #B94).
+        if (removedCount === 0 && childNodes.length > 0) {
+            console.warn('[FormValidator][upload]['+ ($uploadTrigger.id || '?') +'] '+ bindingType +': '+ childNodes.length +' preview(s) present but none matched the staged input files — nothing removed, cleanup skipped. Ensure each preview\'s `data-upload-original-filename` matches a current input file name.');
+        }
+
         // #R8 — at least one staged file the indicator reported is gone:
         // strip the upload-progress indicator entirely
         if (removedCount > 0) {
@@ -14839,12 +14885,22 @@ function ValidatorPlugin(rules, data, formId, culture) {
             }
             var uploadActionUrl = $el.getAttribute(action);
             if (!uploadActionUrl || uploadActionUrl == '' ) {
-                if (!defaultRoute)
-                    console.warn('`'+ action +'` definition not found for `'+ $el.id + '`. Trying to get default route.');
+                // #B149 — an action with NO framework default route is legitimately
+                // optional at bind time. `data-gina-form-upload-delete-action` removes
+                // an ALREADY-SAVED file, so its endpoint is app-specific — the injected
+                // tmp routes cannot serve it and there is deliberately no default (see
+                // the public file-uploads guide). Its real enforcement is lazy, at the
+                // delete USE site (onUploadResetOrDelete throws when a delete actually
+                // fires with no URL). So a missing no-default action is a single debug,
+                // never the warn + error + $errorContainer write that used to paint a
+                // spurious error on every (re)bind of a working upload-only input.
+                if (!defaultRoute) {
+                    console.debug('`'+ action +'` not declared for `'+ $el.id +'` (no framework default; optional until a delete is triggered).');
+                    return;
+                }
                 var additionalErrorDetails = null;
                 try {
-                    if (defaultRoute)
-                        uploadActionUrl = routing.getRoute(defaultRoute);
+                    uploadActionUrl = routing.getRoute(defaultRoute);
                 } catch (err) {
                     additionalErrorDetails = err;
                 }