gina 0.5.18 → 0.5.19

package/CHANGELOG.md

@@ -6,6 +6,27 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.19 - 2026-07-17
+### Added
+* The checkbox migration warning now also covers the un-tick direction: markup carrying the `checked` attribute plus a `value` (or `data-value`) reading false or empty — which used to render unticked and now stays ticked — is flagged once per field, with the same legacy opt-in pointer as the existing warning
+* Routes can now require an authenticated session. Declare `"requireAuth": true` in a routing.json rule's `param` block and the framework answers unauthenticated requests before the controller action ever runs: a 401 by default, or — for a browser navigation, when `settings.json > auth.loginRoute` names a rule or a path — a non-cacheable redirect to the login page, with the original request snapshotted first so the login action can replay it via `self.resumeRequest()`. A request counts as authenticated when `req.session.user` is set; populating it at login stays the application's job. XHR requests always get the 401, never a redirect. Routes that declare nothing behave exactly as before. Author mistakes now refuse to boot rather than silently leaving a route open: a non-boolean `requireAuth`, or an `auth.loginRoute` the bundle does not declare.
+* image:list and image:rm — inspect and remove OCI images on the container host image:build targets. Both resolve the host with image:build's own precedence (GINA_CONTAINER_HOST env override, then native buildah, then the container.host setting), so image:list always shows what image:build would build onto. image:list prints an aligned table or --format=json ({ host, images: [{ ref, id, size, created, sizeBytes, createdAt }] } — createdAt is the exact RFC3339 creation time and sizeBytes an approximate machine-sortable byte count derived from buildah's humanized size); an untagged image reports <none>:<none> and a multi-tagged image yields one entry per tag. image:rm takes an explicit image reference or id (--force removes one a container still references; removing one tag of a multi-tagged image untags it — the image survives under its other tags); there is no bulk delete, and the reference is charset-gated before it reaches the host
+* Role-based route authorization — a route can now require the session user to hold one of a set of roles: routing.json `param.roles: ["admin", "editor"]` (ANY-of match against `req.session.user.roles`; implies `requireAuth`, so unauthenticated callers still get the 401/login bounce). Authenticated callers holding none of the listed roles get a 403 whose body stays generic — the required roles are never echoed to the wire. Declared but invalid `roles` shapes (null, a bare string, an empty array, non-string members) refuse to boot instead of leaving the route silently ungated, and the client-served routing maps no longer ship the authorization keys (`requireAuth`/`roles`/`policy`).
+* A policy-function escape hatch for route authorization — a route can now delegate its access decision to a named per-bundle function for the record/attribute checks roles cannot express (ownership and the like): routing.json `param.policy: "ownsInvoice"` loads `<bundle>/policies/ownsInvoice.js` (`module.exports = function (user, req) { return boolean; }`), registered at boot and AND-composed after roles (implies `requireAuth`; evaluation order authN → roles → policy). A policy is allowed only when it returns a literal `true`; any other return denies, and a policy that throws denies with a 403 rather than erroring the response. The 403 stays generic — the policy name is never echoed to the wire. A missing, broken, non-function, non-string or `async function` policy refuses to boot instead of leaving the route silently ungated. Also adds the imperative `self.hasRole(role)` controller helper for actions that authorize mid-logic.
+* An audit trail — a user-attributed, append-only record of "who did what to which record when", distinct from application logging (it has its own store and never rides the logger sinks). Opt in with `settings.json > audit.enabled: true` and call `self.audit(action, data[, cb])` from an action: `self.audit("invoice.delete", { resource: id })` writes a v1 record `{ id, ts, requestId, actor: {key, roles}, action, resource?, meta?, ip, rule, method, bundle, env }`. The default backend is an append-only JSONL file at `<project>/logs/audit-<bundle>-<env>.jsonl` (per-bundle-per-env, resolved path logged at boot; override with `audit.file`, or point `audit.store` at a connectors.json entry — no connector ships an audit-store implementation yet, so that path currently refuses the boot rather than failing silently). Writes are serialized, so on-disk order matches emit order. The actor is a snapshot of `session.user[audit.actorKey]` (default `"id"`) plus a copy of `user.roles` — never the whole user object; `ip` is the socket address and `X-Forwarded-For` is never trusted. Route authorization denials are recorded automatically when the trail is on (`authz.denied` with `meta.outcome` covering `401` / `login-bounce` / `403-roles` / `403-policy`; opt out with `audit.events.authz: false`), and an audit failure can never change an authorization outcome. Every request now carries an always-on request id, so audit records and JSON log lines correlate by construction (that id honours a sanitized inbound `X-Request-Id`, so it is a correlation key, not attribution — attribution is the actor fields). Malformed `audit` settings — a non-boolean `enabled`, an empty `file`/`store`/`actorKey`, a non-boolean `events.authz`, or `store` and `file` together — refuse to boot instead of leaving a compliance control silently OFF.
+* `gina image:run <image>` runs an image on the same container host `image:build` targets, with podman. Detached by default (the container id is printed on stdout, alone, so it can be captured), publishing the port the image EXPOSEs mapped same:same — that EXPOSE is the port the gina-init allocator computed at build time, so it is the one the bundle actually binds. `--publish=<host>:<container>[,...]` overrides it, `--publish=none` publishes nothing. Also `--name`, `--rm`, `--stream` (foreground, mirroring the container output as NDJSON frames) and `--format=json`. Runtime environment comes from `--env-var=KEY=VALUE` (repeatable) and `--env-file=<path>`, and reaches the container without ever entering argv or a shell, so values stay out of the host process list — which is how a ${secret:KEY} placeholder baked verbatim into the image gets its value at start. buildah builds images but cannot run them, so a build-only host (buildah present, podman absent) says so honestly instead of failing opaquely. Host resolution is identical to image:build / image:list / image:rm, and no project is required.
+* A new `container:` command group — `gina container:ps [--all] [--format=json]` lists the containers on the container host `image:build` targets (running only by default; every container on the host is shown, as there is no gina-specific marker to filter on), and `gina container:stop <name|id> [--time=<s>] [--force] [--format=json]` stops one. The verbs live in their own group because they act on containers rather than images — the split podman and docker make — but they resolve the host through exactly the same precedence as the image group, so container:ps always lists the host image:build builds onto and image:run runs on. container:stop reports the rung the container came down on, which podman own exit code hides: podman exits 0 whether the container handled SIGTERM or had to be SIGKILLed after the grace period, so a post-stop inspect reads the container exit code — 137 is 128+SIGKILL (it did not handle the signal in time) and anything else means it came down on its own terms. Stopping an already-exited container is a success no-op, so the verb is safe to re-run. Both verbs drive podman and report a build-only host (buildah present, podman absent) honestly rather than as an opaque exec failure.
+### Changed
+* Request data crossing a redirect() now rides the session (the hidden inheritedData flash channel, one-shot — consumed by the next routed GET, gone on refresh) whenever a live session exists; the clear-text ?inheritedData= URL form and its 2000-char cap now apply only to session-less bundles. resumeRequest()'s plain-XHR and non-XHR GET replays no longer drop the halted request's extra data. For a session-ful bundle that halts a credential-bearing POST (a registration or login paused mid-flight), this removes a plaintext-secret-in-URL disclosure: the payload no longer lands in the address bar, browser history, or access logs.
+### Fixed
+* Calling `gina.emit('error', ...)` on the module object no longer throws — `emit` is now an inert stub that always returns `false` (the detached-copy assignment it replaces never dispatched to any listener; the module object is not an event surface — application events go through the controller's `self.emitEvent()`)
+* image:build: images for projects that declare gina among their own dependencies no longer fail at gina-init with EACCES — the synthesized Containerfile re-hands the runtime home back after the project-dependency install, whose framework postinstall was re-seeding $HOME/.gina root-owned after the earlier hand-back (dependency-free projects were unaffected)
+* image:build: the pinned framework now actually wins require('gina') inside images built for gina-dependent projects — the node_modules/gina link supersedes the project-extracted copy (ln -sfn against a real directory exits 0 but nests the symlink inside it, so the project's own gina was silently used at runtime while the CLI binaries ran from the global pin)
+* getRoute() no longer throws (surfacing as a 500 at the caller) when composing a URL for a GET route that declares no requirements block and receives extra params — the deep-link-before-login replay (resumeRequest()) failed on any halted requirements-less GET route carrying data, and the same crash was reachable from the url template filter / getUrl() family, in the browser bundle too. Extra params now land on the composed URL as query parameters.
+* The relative-path `self.redirect('/path')` form resolves its target again server-side: the route matcher is async and the historical un-awaited call could never match. `redirect()` is now async as a result — prefer `return self.redirect(...)` from controller actions so a resolution error reaches the framework's handler.
+* A redirect to an unresolvable target no longer crashes the process — the request now gets a clean 404, and the response-header composer tolerates a falsy routing state instead of throwing from inside the error path itself.
+* Prometheus metrics (app.json metrics.enabled) no longer double-count requests under the isaac engine: the request-lifecycle hook ran at both dispatch layers for any request reaching the router, so counters were double-incremented and the duration histogram double-observed. The hook now records exactly once on either engine, request durations are measured from engine entry, and the dev Inspector Flow timeline keeps its accurate request-start time.
+
 ## 0.5.18 - 2026-07-16
 ### Added
 * Bundle-wide `sliding` and `maxAge` cache defaults: `server.cache` now supplies `sliding` and `maxAge` fallbacks that a route inherits when it omits them, mirroring the existing `ttl` fallback — so sliding-window caching can be enabled for a whole bundle from one place. Per-route values still win (an explicit `sliding: false` overrides a bundle-wide `true`), and behaviour is unchanged for bundles that do not set these keys. Applies to cached HTML (swig, nunjucks) and JSON responses.
@@ -45,7 +66,7 @@ and is generated by [Changie](https://github.com/miniscruff/changie).
 ### Fixed
 * Cleaning up a stale project registration is now reliable. `gina project:rm @<project> --force` (the `:rm` alias) removes the entry instead of erroring — the alias had failed an internal `--force` guard that only the full `project:remove` form passed. And `gina project:remove` / `project:rm @<project> --force` no longer crashes with an `ENOENT` error when the stale project's path can no longer be created (a top-level path such as `/app`, or any path under a read-only parent): it skips the now-pointless project-directory re-creation and goes straight to registry-only removal, cleaning both `~/.gina/projects.json` and its state-store mirror plus the project's port assignments — without resurrecting an empty skeleton directory.
 * Installing gina with the npm 12 `--allow-scripts=gina` remedy (or `npm config set allow-scripts=gina --location=user`) no longer fails with `EALLOWSCRIPTS`. npm exports the allowance to install-script children as `npm_config_allow_scripts`, and npm rejects it in project-scoped installs — which killed the nested framework-dependency install inside post-install, and with it the whole `npm install -g gina`. The nested install now drops the inherited allowance for its duration (the framework dependencies carry no install scripts, so nothing is lost). This unblocks the npm 12 install path, where install scripts are blocked by default and the flag is required.
-* `gina bundle:start` now honours a bundle's configured default scope. A typo in the scope-resolution expression returned an undefined property, so a bundle that declared a default scope in its manifest started with an undefined scope instead of the configured one (bundles with no configured default scope were unaffected — they already fell back to the framework default scope). The command now reads the correct property.
+* Corrected a typo in `gina bundle:start`'s scope-resolution expression, which read a misspelled property name. **No behaviour change** — the local variable it assigns is never read, and no bundle manifest carries the per-bundle property (nothing writes it), so the misspelled branch was unreachable: no bundle was ever started with a wrong or undefined scope. A bundle's effective scope continues to resolve, unchanged, from `--scope=`, then `NODE_SCOPE`, then the project's default scope, then the framework default.
 
 ## 0.5.16 - 2026-07-12
 ### Added

package/README.md

@@ -42,21 +42,16 @@ 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.18
-
-- **Added — a shared redis L2 for the render cache, and pluggable cache backends.** `server.cache.type` now sets a bundle's default output-cache backend (`memory`, `fs`, or `redis`) and a route with `cache` set inherits it, alongside new bundle-wide `sliding` / `maxAge` fallbacks (per-route values still win). The `redis` tier caches rendered output in a shared store, so several replicas serve the same rendered page and a freshly-started replica serves what a peer already rendered (cross-replica cold-start): writes go to the in-process L1 synchronously and to redis fire-and-forget (the response never waits on redis), an L1 miss warms back from redis with the authoritative remaining TTL, invalidation propagates, and a down or failing redis degrades to per-replica caching (fail-open). The bundle validates its cache configuration at boot and refuses to start on an unsupported shape. New bundles default to `memory`; existing installs are unchanged.
-- **Added — type-safe DTOs and a default-on validation pipe.** `gina.dto` lets you author a data shape once and project it four ways: runtime validation, response shaping, JSON Schema (draft-07 or 2020-12), and TypeScript. A `routing.json` rule declaring `param.dto` has its payload validated before the controller action runs — a clean, localised 422 on failure, a type-coerced payload on success — and `param.responseDto` shapes the outgoing JSON so a field marked `.exclude()` never reaches the wire. `gina bundle:types <bundle> @<project>` emits declarations from those same DTOs, and `bundle:openapi` / `bundle:mcp` now emit real request/response schemas instead of `.*`. DTOs are resolved at bundle boot, so a missing one fails the boot instead of silently disabling validation; routes that declare no DTO are unaffected.
-- **Added — `releaseWatch`, a stale built-release watch for local production rehearsals.** A bundle serving a built release under `local` scope + a non-dev env has no hot-reload, so after you edit source it silently keeps serving the stale build. Opt in via `server.releaseWatch`: the bundle fingerprints its source tree against the manifest release stamp (now written by `bundle:build` / `project:build`), surfaces staleness on `GET /_gina/release/status` and a `GET /_gina/release/events` SSE stream, and rebuilds on `POST /_gina/release/rebuild` with an **idle-gated restart** that waits on in-flight requests and `gina.registerBusyProbe` application probes. Rendered pages carry a live shadow-DOM banner offering one-click rebuild-and-reload, and `restartMode: supervisor` suits a daemonless container launch (drain, then exit(0) for an orchestrator to respawn). Hard-gated on local scope + a non-dev env — byte-inert everywhere else.
-- **Added — flush or event-evict the render cache from outside the bundle.** `POST /_gina/cache/clear` (both engines, loopback-gated) and a new `gina cache:clear [<bundle>] @<project>` CLI flush the rendered-output cache — without ever touching compiled templates or HTTP/2 sessions — with `--dry-run` and `--format=json`. `?event=<name>` evicts by event: a controller's `self.cache.invalidateByEvent()` only reaches its own process, so this is how one bundle's write invalidates another bundle's cached pages. Note `?event=` previously went unread, so passing it flushed *every* bundle's output cache; it is now honoured.
-- **Added — two-tier render-cache observability.** Every cache hit's `Cache-Status` header now carries an RFC 9211 `detail` parameter naming the physical tier that served the bytes — `memory` for the in-process L1, `redis` for a shared-L2 warm (the cross-replica cold-start, visible per request), `fs` for a disk read-back after a restart — and `/_gina/cache/stats` gains an `l2` block reporting the redis store's connection health, with no network round-trip on the admin path.
-- **Changed — render-cache keys are release-namespaced, so an upgrade auto-invalidates.** The cache key *and* the `fs` cache path now carry a release namespace — `GINA_CACHE_NAMESPACE` (an id you set, such as a git SHA or build number) when present, otherwise the framework version — so a new build never serves a page cached by old code. `fs`-cached files from a superseded namespace are orphaned on disk until cleared. Dev mode is unaffected (it runs cacheless).
-- **Changed — the `Cache-Status` miss form follows RFC 9211.** It is now `gina-cache; fwd=uri-miss` (previously the bare `gina-cache; uri-miss`, which read as an unregistered parameter to RFC-aware tooling), and the engine-agnostic read path emits it on a genuine both-tier miss — giving Express bundles their first cache-miss signal on the wire.
-- **Fixed — event-driven cache invalidation now works, and a cache fault no longer discards a good page.** A route's `cache.invalidateOnEvents` was registered but nothing ever fired it — the documented `self.cache.invalidateByEvent()` did not exist, so configured routes served stale content until their TTL expired. `self.cache` now exists on the controller and reports the number of entries evicted. Three further defects in the same path are fixed: re-registering a key carrying a querystring **threw** (the registry ran cache keys through a condition evaluator, where `?`/`=` parse as operator tokens) and under the swig engine that throw unwound to the top-level error handler, which answered 500 and discarded a page that had already rendered; registrations were never reclaimed, so the registry grew a row per cache-miss re-render; and an `fs` entry read back after a restart carried no registration at all. Separately, a failed cache **write** now degrades exactly as the nunjucks and JSON renderers already did — the response is served, the failure logged, and the next miss retries.
-- **Fixed — the `fs` render cache survives a restart.** An `fs`-cached response written to disk was previously orphaned on the next boot (the in-process index starts empty), so it was never served again and its file was never cleaned up — `fs` behaved no better than `memory` across a restart. The read path now falls back to disk on an index miss, replaying the entry from a `.meta` sidecar and preserving the **original absolute expiry**, so a restart never extends a TTL. Entries expiring on their timer now run the same cleanup as a manual eviction, instead of stranding their body and sidecar on disk.
-- **Fixed — a checkbox's `value` attribute no longer decides its `checked` state.** The HTML `checked` attribute alone drives the initial rendering, and the posted boolean is derived from the live checked state rather than the value string — so a consent-style checkbox rendered with `value="true"` is no longer silently pre-ticked, `value="false"` no longer un-ticks a server-checked box, a checkbox unticked from your own script no longer posts `true` off its stale value, and a neutral-valued checkbox with an `isBoolean` rule posts real booleans instead of going dead. The forced rule injection now appends `isRequired` before `isBoolean`, so an unchecked box whose rule declared neither no longer fails with "Cannot be left empty". A transitional per-form opt-in — `data-gina-form-checkbox-value-as-state="true"` (deprecated) — preserves the old value-driven ticking while markup migrates to `checked`, and a once-per-field console warning flags the affected checkboxes. (#49)
-- **Fixed — the published TypeScript declarations now describe the runtime.** `import gina from "gina"; gina.lib` previously failed to typecheck for every consumer, because the main entry declared no value at all. The module surface now carries all 78 runtime members including `gina.dto`; `SuperController` gains its i18n / jobs / trailers / events / template-override methods plus `GinaRequest<TDto>` and `req.dto` typing for route DTOs; fictional declarations were removed; and a two-part gate (a consumer fixture compiled by `tsc` through the package exports map, plus a runtime-parity test) keeps the declarations and the runtime in sync.
-- **Fixed — errors surface instead of crashing, masking, or coming back as `0`.** A framework error raised from a detached context — a scheduled cron/timer, a worker, or a bootstrap-time `getLib()` — no longer crashes the process with `TypeError: next is not a function` while masking the original error. `getLib()` / `getConfig()` no longer crash with an opaque `Cannot read properties of undefined (reading 'conf')` when configuration is read while the config build is still partway (for example a fail-closed `${secret:KEY}` resolution), so the real boot error surfaces. A bitwise `|` at nine sites across the HTTP server, the browser client bundle, and three CLI commands coerced the Error to the number `0` — a rendered 500 page body and the `protocol:set` / `port:reset` / `project:add` output all reported `0` instead of the cause. And log messages containing a `$` are no longer mangled by the text formatter's `%`-token splice, across every level and sink. (#B108 / #B112)
-- **Fixed — two smaller corrections.** A server-side form-validator `query` rule no longer re-points the framework's process-wide cache onto a second Map, so concurrent renders keep reading their cached entries and pooled HTTP/2 sessions land in the real server's cache. And `bundle:openapi` / `bundle:mcp` no longer advertise `.exclude()`d DTO fields in response schemas — the 200 content schema and the MCP tool `outputSchema` now emit the response projection, while request-side schemas keep the declared shape. (#B110 / #B115)
+## What's in 0.5.19
+
+- **Added — route authorization.** A `routing.json` rule can now gate access declaratively, enforced before the controller action runs. `param.requireAuth: true` requires an authenticated session (`req.session.user` set — populating it at login stays the app's job): an unauthenticated XHR gets a 401, a browser navigation gets a non-cacheable redirect to `settings.json > auth.loginRoute` with the original request snapshotted for `self.resumeRequest()` to replay. `param.roles: ["admin", "editor"]` requires any one of a set of roles (implies `requireAuth`); `param.policy: "ownsInvoice"` delegates the decision to a per-bundle `policies/ownsInvoice.js` function for the ownership/record checks roles can't express (AND-composed after roles, allowed only on a literal `true`, a throwing policy denies). Denials stay generic — the required roles and policy name never reach the wire, and the client-served routing maps no longer ship the authorization keys. Author mistakes refuse to boot rather than leaving a route silently open (a non-boolean flag, an undeclared `loginRoute`, an invalid `roles` shape, a missing / broken / `async` policy). Also adds the imperative `self.hasRole(role)` controller helper. Routes that declare nothing behave exactly as before.
+- **Added — an audit trail.** A user-attributed, append-only record of "who did what to which record when", with its own store, never riding the logger sinks. Opt in with `settings.json > audit.enabled: true` and call `self.audit("invoice.delete", { resource: id })` from an action; the default backend is an append-only JSONL file at `<project>/logs/audit-<bundle>-<env>.jsonl` (override with `audit.file`, or point `audit.store` at a connectors.json entry). The actor is a snapshot of `session.user[audit.actorKey]` plus a copy of `user.roles` — never the whole user object — and `X-Forwarded-For` is never trusted. Route-authorization denials are recorded automatically (`authz.denied`, opt out with `audit.events.authz: false`), and an audit failure can never change an authorization outcome. Every request now carries an always-on request id, so audit records and JSON log lines correlate by construction. Malformed `audit` settings refuse to boot rather than leaving a compliance control silently off.
+- **Added — an OCI image and container CLI.** Building on `image:build` (0.5.11), five verbs now inspect and run images on the same container host: `gina image:list` (aligned table or `--format=json` with a machine-sortable `sizeBytes` and an RFC3339 `createdAt`), `image:rm <ref>` (untags a multi-tagged image; no bulk delete; the reference is charset-gated), and `image:run <image>` (runs with podman — detached by default, publishing the EXPOSEd port same:same, with `--publish` / `--rm` / `--stream` / `--env-var` / `--env-file`, so a `${secret:KEY}` baked into an image gets its value at start without ever entering argv or a shell). A new `container:` group lists and stops running containers — `container:ps [--all]` and `container:stop <name|id>`, which reports the rung the container came down on (137 = SIGKILL after the grace period, otherwise its own terms). Every verb resolves the host with `image:build`'s precedence and reports a build-only host (buildah without podman) honestly instead of failing opaquely.
+- **Changed — `redirect()` carries request data through the session by default.** When a redirect carried the request's params they used to travel in the URL as `?inheritedData=<encoded JSON>` — in clear, in the address bar, browser history, and access logs, capped at 2000 characters. On a bundle with a session they now ride the session instead (a one-shot flash, consumed by the next routed GET, gone on refresh); the URL form and its cap now apply only to session-less bundles. For a bundle that halts a credential-bearing POST mid-flight (a registration or login), this removes a plaintext-secret-in-URL disclosure. The target action still reads the data from `req.get` unchanged, and `resumeRequest()`'s plain-XHR and full-page replays no longer drop it.
+- **Fixed — metrics no longer double-count under the isaac engine.** With `app.json metrics.enabled` on, the request-lifecycle hook ran at both dispatch layers for any request reaching the router, so Prometheus counters were double-incremented and the duration histogram double-observed. The hook now records exactly once on either engine, durations are measured from engine entry, and the dev Inspector Flow timeline keeps its accurate request-start time. Metrics-enabled deployments will see counter rates roughly halve at pickup — that is the double-count disappearing, not traffic dropping. (#OBS1)
+- **Fixed — redirect resolution.** The relative-path `self.redirect('/path')` form resolves its target server-side again (the route matcher is async and the historical un-awaited call could never match; `redirect()` is now async — prefer `return self.redirect(...)` from actions), a redirect to an unresolvable target gets a clean 404 instead of crashing the process, and `getRoute()` no longer throws a 500 when composing a URL for a GET route that declares no `requirements` block and receives extra params (they now land as query parameters). (#B120 / #B121)
+- **Fixed — `image:build` for projects that depend on gina.** Images built for a project that lists gina among its own dependencies no longer fail at `gina-init` with `EACCES`, and the pinned framework now actually wins `require('gina')` inside the image — the `node_modules/gina` link supersedes the project-extracted copy. Dependency-free projects were unaffected. (#B118 / #B119)
+- **Fixed — two smaller corrections.** `gina.emit('error', ...)` on the module object no longer throws (`emit` is an inert stub; application events go through the controller's `self.emitEvent()`), and the checkbox migration warning added in 0.5.18 now also covers the un-tick direction — markup carrying `checked` plus a false / empty `value` that used to render unticked and now stays ticked is flagged once per field. (#B109 / #49)
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -43,6 +43,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.5.16` ✅ | **Added**: a `multipart/form-data` request's non-file text fields are now captured into `request.body` (bracket-notation nested, values verbatim, capped by `upload.maxTextFields` / `upload.maxTextFieldSize` with a 400 on breach) — previously silently dropped · **Fixed**: `$form.send(FormData)` keeps its non-file fields when the payload also carries files (#B92), and a routing rule's `param.title` now reaches the browser-tab title (`page.view.title`) instead of always showing the route name, with the route name as the fallback (#B98) |
 | **Q3 2026** | `0.5.17` ✅ | **Fixed**: `npm install -g gina` no longer fails with `EALLOWSCRIPTS` under the npm 12 `--allow-scripts=gina` remedy — the nested framework-dependency install drops the inherited allowance, making `0.5.17` the first version installable on npm 12 (#B106) · stale project cleanup is reliable — `project:rm @<project> --force` (the alias) removes the entry, and `project:remove` / `:rm --force` no longer `ENOENT`-crashes on an uncreatable stale path, going straight to registry-only removal (#B104/#B105) · `bundle:start` honours a bundle's configured default scope (a typo had returned an undefined property) |
 | **Q3 2026** | `0.5.18` ✅ | **Added**: a redis-backed L2 render cache — rendered output is cached in a shared store, so several replicas serve the same rendered page and a freshly-started replica serves what a peer already rendered (cross-replica cold-start), degrading to per-replica caching if redis is down · pluggable cache backends (`server.cache.type`: `memory` / `fs` / `redis`) with bundle-wide `sliding` / `maxAge` fallbacks a route inherits · type-safe DTOs and a default-on validation pipe (`gina.dto` — one shape projected to runtime validation, response shaping, JSON Schema and TypeScript; `param.dto` validates the payload before the action with a localised 422, `param.responseDto` shapes the wire, `gina bundle:types` emits declarations, and `bundle:openapi` / `bundle:mcp` emit real request/response schemas) · `releaseWatch` — an opt-in stale built-release watch for local production rehearsals (source-tree fingerprint against the manifest release stamp, `GET /_gina/release/status` + an SSE stream, idle-gated rebuild-and-restart honouring in-flight requests and busy probes, a live shadow-DOM banner, and `restartMode: supervisor` for daemonless container launches) · `POST /_gina/cache/clear` + a `gina cache:clear` CLI (flush the rendered-output cache, or evict by event across bundles) · two-tier cache observability (an RFC 9211 `Cache-Status` `detail` naming the serving tier, plus an `l2` redis-health block on `/_gina/cache/stats`) · **Changed**: render-cache keys are release-namespaced, so an upgrade auto-invalidates (`GINA_CACHE_NAMESPACE`, else the framework version) · the `Cache-Status` miss form is now the RFC 9211 `gina-cache; fwd=uri-miss`, and Express bundles get their first cache-miss signal · **Fixed**: event-driven cache invalidation works — `self.cache.invalidateByEvent()` now exists, and a key carrying a querystring no longer throws a 500 that discarded an already-rendered page · the `fs` cache survives a restart (disk read-back via a `.meta` sidecar, original absolute expiry preserved, no TTL extension) · a checkbox's `value` attribute no longer decides its `checked` state (#49) · the published TypeScript declarations describe the runtime · errors surface instead of crashing, masking, or coming back as `0` (detached-context `throwError`, partial-boot `getLib()` / `getConfig()`, a bitwise-or at nine sites, and `$` in log messages) |
+| **Q3 2026** | `0.5.19` ✅ | **Added**: route authorization — a `routing.json` rule gates access before the action runs via `param.requireAuth` (a 401 for XHR, a non-cacheable login redirect for a browser navigation, the original request snapshotted for `resumeRequest()`), `param.roles` (ANY-of, implies `requireAuth`), and `param.policy` (a per-bundle function for the ownership/record checks roles can't express, AND-composed after roles); denials stay generic — required roles and the policy name never reach the wire — author mistakes refuse to boot, and `self.hasRole()` authorizes mid-logic · an audit trail — opt-in `self.audit(action, data)` writes a user-attributed append-only JSONL record (its own store, never the logger sinks; an actor snapshot, `X-Forwarded-For` never trusted), route-authorization denials recorded automatically, and an always-on request id correlating audit records to JSON logs · an OCI image/container CLI on the `image:build` host — `image:list` / `image:rm` / `image:run` (podman; publishes the EXPOSEd port, `--env-var` / `--env-file` keep secrets out of argv) and a `container:` group (`container:ps` / `container:stop`, reporting the rung a container came down on) · **Changed**: `redirect()` carries request data through the session by default (a one-shot flash, gone on refresh), the clear-text `?inheritedData=` URL form and its 2000-char cap now session-less-only — removing a plaintext-secret-in-URL disclosure when a session-ful bundle halts a credential-bearing POST · **Fixed**: Prometheus metrics no longer double-count under the isaac engine (#OBS1) · the relative `self.redirect('/path')` form resolves again and an unresolvable target 404s instead of crashing (`redirect()` is now async), and `getRoute()` no longer 500s on a requirements-less GET route with extra params (#B120/#B121) · `image:build` for gina-dependent projects no longer fails at gina-init and the pinned framework wins `require('gina')` (#B118/#B119) · `gina.emit` is an inert stub (#B109) and the checkbox migration warning now covers the un-tick direction (#49) |
 | **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 |
@@ -117,6 +118,8 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | ✅ | **`project:backup` / `project:restore`** — Archive a project's source tree to a `.zip` (`backup`, symlinks skipped), and rebuild + re-register a project from a backup `.zip` so it is immediately startable (`restore`). | `0.5.5-alpha.2` | 2026-06-19 |
 | ✅ | **`framework:man` / `project:man` / `bundle:man` / `service:man`** — Inline CLI manual pages. Runtime-renders the group's ronn `.1.md` (substituting `{version}`/`{year}`) when it exists (`framework` today), else falls back to that group's `help.txt`. No build step or markdown/man dependency. | `0.5.5-alpha.2` | 2026-06-20 |
 | ✅ | **`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 |
 
 ---
 
@@ -248,8 +251,8 @@ Technical-safeguard primitives that map to the **PCI-DSS**, **SOC2**, and **HIPA
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
-| 📋 | **Authorization / RBAC** — A role/permission model, per-route authorization gate, and policy helpers (today Gina ships authentication status only, no authorization). Maps to PCI-DSS req 7, HIPAA §164.312(a)(1), SOC2 CC6 (least privilege). | `0.6.x` | Q4 2026 |
-| 📋 | **Tamper-evident audit trail** — A user-attributed, append-only, integrity-protected record of who did what to which record when, distinct from application logging. Maps to PCI-DSS req 10, HIPAA §164.312(b), SOC2 CC7. | `0.6.x` | Q4 2026 |
+| ✅ | **Authorization / RBAC** — Per-route authorization declared in `routing.json`: `param.requireAuth` requires an authenticated session, `param.roles: ["admin","editor"]` requires any one of a set of roles, and `param.policy: "ownsInvoice"` delegates to a per-bundle function for the record/attribute checks roles cannot express (evaluation order: authentication → roles → policy). Unauthenticated callers get a 401, or a non-cacheable login bounce when `settings.json > auth.loginRoute` is set (the paused request replays after sign-in); authorized-but-denied callers get a 403 whose body stays generic — the required roles and the policy name are never echoed to the wire. `self.hasRole(role)` covers actions that authorize mid-logic. A route that declares nothing is untouched, and any declaration that would leave a route silently ungated refuses to boot. Maps to PCI-DSS req 7, HIPAA §164.312(a)(1), SOC2 CC6 (least privilege). | `0.5.19-alpha.2` | shipped |
+| 📋 | **Tamper-evident audit trail** — A user-attributed, append-only, integrity-protected record of who did what to which record when, distinct from application logging. **The audit trail itself has already shipped** — `settings.json > audit.enabled` plus `self.audit(action, data)` writes an append-only JSONL trail (actor, action, resource, request id, ip, route, timestamp), and route-authorization denials are recorded automatically; see the changelog for the release that carries it. **What remains for this row is the tamper-evidence** — the HMAC hash chain that makes an edited, deleted, or reordered record detectable, plus `gina audit:verify`. Maps to PCI-DSS req 10, HIPAA §164.312(b), SOC2 CC7. | `0.6.x` | Q4 2026 |
 | 📋 | **Authentication hardening** — Password hashing/policy helpers, account lockout, and MFA/TOTP hooks. Maps to PCI-DSS req 8, HIPAA §164.312(d). | `0.6.x` | Q4 2026 |
 | 📋 | **Session lifecycle hardening** — Session-id rotation on privilege change and idle/absolute timeouts, on top of the existing Session plugin. Maps to PCI-DSS req 8.2. | `0.6.x` | Q4 2026 |
 | 📋 | **PII/PHI protection** — Production log-field redaction, data classification, and retention helpers (today's redaction is a dev-only inspector tool). Maps to HIPAA and SOC2 Privacy. | `0.6.x` | Q4 2026 |

package/bin/cli

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

package/framework/v0.5.19/VERSION

@@ -0,0 +1 @@
+0.5.19

package/framework/{v0.5.18 → v0.5.19}/core/asset/plugin/dist/vendor/gina/js/gina.js

@@ -6216,7 +6216,7 @@ function Routing() {
      * @function getRoute
      *
      * @param {string} rule e.g.: [ <scheme>:// ]<name>[ @<bundle> ][ /<environment> ]
-     * @param {object} params
+     * @param {object} params - substituted into the route's `:placeholders`; on a GET route, leftover keys that are neither reserved nor declared in the rule's `requirements` are appended to `route.url` as query parameters (a rule with no `requirements` block is safe — the block is optional)
      * @param {number} [urlIndex] in case you have more than one url registered for the current route, you can select the one you want to use. Default is 0.
      *
      * @returns {object} route
@@ -6349,7 +6349,10 @@ function Routing() {
             for (let p in params) {
                 if (
                     self.reservedParams.indexOf(p) > -1
-                    || typeof(route.requirements[p]) != 'undefined'
+                    // a rule that declares no `requirements` block composes with requirements: undefined —
+                    // guard the deref (the fitsWithRequirements discipline) so getRoute(rule, extraParams)
+                    // on such a GET route appends the query params instead of throwing
+                    || ( route.requirements && typeof(route.requirements[p]) != 'undefined' )
                     || extracted.indexOf(p) > -1
                 ) {
                     continue;
@@ -6547,9 +6550,15 @@ function Routing() {
     /**
      * Get route by url
      * N.B.: this will only work with rules declared with `GET` method property
-     * ATTENTION !!! Not fully working for frontend because of unresolved promises !!!!
+     *
+     * Async since #B121: the underlying `compareUrls` machinery is async (it can
+     * await `validator::` routing-requirement validation), and the historical
+     * un-awaited call meant no rule could ever match — callers received the
+     * `false` sentinel for every url. Await this method (or `.then()` it); the
+     * old "unresolved promises" caveat that used to sit here was this defect.
      *
      * @function getRouteByUrl
+     * @async
      *
      * @param {string} url e.g.: /webroot/some/url/path or http
      * @param {string} [bundle] targeted bundle
@@ -6557,10 +6566,15 @@ function Routing() {
      * @param {object} [request]
      * @param {boolean} [isOverridingMethod] // will replace request.method by the provided method - Used for redirections
      *
-     * @returns {object|boolean} route - when route is found; `false` when not found
+     * @returns {Promise<object|boolean>} route - when route is found; `false` when not found
+     *
+     * @example
+     *  // from an async context (e.g. a controller helper)
+     *  var route = await lib.routing.getRouteByUrl('/myapp/landing', 'myapp', 'GET', req);
+     *  if (route) { console.log(route.name, route.param); }
      * */
 
-    self.getRouteByUrl = function (url, bundle, method, request, isOverridingMethod) {
+    self.getRouteByUrl = async function (url, bundle, method, request, isOverridingMethod) {
 
         if (
             arguments.length == 2
@@ -6744,8 +6758,16 @@ function Routing() {
                 // normal case
                 //Parsing for the right url.
                 try {
-                    isRoute = self.compareUrls(params, routing[name].url, request);
-                    if (isRoute.past) {
+                    // #B121 root cause — `compareUrls` is async (it can await `validator::`
+                    // requirement validation), so the historical un-awaited call yielded a
+                    // Promise whose `.past` is always undefined: no rule could EVER match
+                    // server-side. Await it, and mirror the engine loop's exact-url
+                    // fast-path so this block stays identical to `server.js` (see the
+                    // N.B. above the loop).
+                    // was: isRoute = self.compareUrls(params, routing[name].url, request);
+                    // was: if (isRoute.past) {
+                    isRoute = await self.compareUrls(params, routing[name].url, request);
+                    if (pathname == routing[name].url || isRoute.past) {
                         route = JSON.clone(routing[name]);
                         route.name = name;
                         // #B52-residual finding-2: getRouteByUrl returns `route` (a fresh clone of the
@@ -6839,7 +6861,11 @@ function Routing() {
                 }
 
                 // forms
-                var altRoute = self.compareUrls(params, url, request) || null;
+                // #B121 root-cause sibling — un-awaited async `compareUrls`: `altRoute`
+                // was a Promise (truthy, `.past` undefined), so this not-found
+                // bookkeeping branch could never run.
+                // was: var altRoute = self.compareUrls(params, url, request) || null;
+                var altRoute = ( await self.compareUrls(params, url, request) ) || null;
                 if(altRoute.past && isMethodProvidedByDefault) {
                     notFound = method.toUpperCase() +'::'+ altRoute.request.routing.rule;
                     if ( typeof(self.notFound[notFound]) == 'undefined' ) {
@@ -14951,6 +14977,25 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         checkboxValueStateWarned[elId] = true;
                         console.warn('[ FormValidator ] checkbox `'+ elId +'`: `value` no longer implies the checked state; add the `checked` attribute if it must render ticked, or set `data-gina-form-checkbox-value-as-state="true"` on the form to restore the legacy behavior');
                     }
+
+                    // Migration aid (#49) — the mirror direction: this markup used to be
+                    // auto-UN-ticked by its `value` (the pre-fix init pass cleared a
+                    // parser-checked box whose resolved value read false/empty) and now
+                    // stays ticked. Membership mirrors the old resolution chain:
+                    // `data-value` attribute, else `value` attribute, else the DOM
+                    // `.value` — with the empty string mapping to false. Reads run
+                    // before the checkbox init pass, so `.value` is parser-fresh here.
+                    var legacyUntickValue = $inputs[f].getAttribute('data-value') || $inputs[f].getAttribute('value') || $inputs[f].value;
+                    if (
+                        /^(checkbox)$/i.test($inputs[f].type)
+                        && !isCheckboxValueAsState($form)
+                        && $inputs[f].hasAttribute('checked')
+                        && ( legacyUntickValue === '' || /^false$/i.test(legacyUntickValue) )
+                        && !checkboxValueStateWarned[elId]
+                    ) {
+                        checkboxValueStateWarned[elId] = true;
+                        console.warn('[ FormValidator ] checkbox `'+ elId +'`: `value` no longer un-ticks a checked box; remove the `checked` attribute if it must render unticked, or set `data-gina-form-checkbox-value-as-state="true"` on the form to restore the legacy behavior');
+                    }
                 }
             }