gina 0.5.6-alpha.2 → 0.5.6

package/CHANGELOG.md

@@ -6,6 +6,38 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.6 - 2026-07-01
+### Added
+* Added a streaming variant to the AI connector: getModel('<name>').stream(messages, options) returns an EventEmitter emitting start/delta/done/error events for token-by-token inference, plus an .onComplete(cb) shim mirroring infer(). Works across Anthropic and every OpenAI-compatible provider; the buffered infer() is unchanged.
+* The dev Inspector now has an "AI stream" tab that shows AI token streams per request. Streams started with getModel('<name>').stream(...) surface live as they arrive — token frames carrying model, role, running token counts and latency — plus an end-of-request snapshot of every stream the request made. Stream metadata is always captured in dev mode; the prompt and generated text ride the wire only when the new inspector.ai.captureText setting is enabled (default off).
+* The dev Inspector can bridge selected framework entity events onto its live Event tab via a new settings.inspector.events.topics allow-list (default empty, so nothing is bridged by default). Whitelisted entity trigger names, matched exactly or by a single leading or trailing wildcard, surface as framework-sourced events alongside events emitted explicitly via self.emitEvent, carrying a safe ok/error summary rather than raw record data.
+* Observable application events in the Inspector: emit a named runtime event with self.emitEvent(name, metadata) — or lib/inspector-events from model or background-job code — and see it live in a new Inspector "Events" tab. Events emitted within a request also appear in the end-of-request snapshot; events emitted outside a request (a background job or detached timer) still stream live. Capture is gated to dev mode or an open instrumentation window; the event name always rides the wire, while metadata values are opt-in via settings.inspector.events.captureArgs (default off).
+* The dev Inspector can now surface framework connector-lifecycle events on its live Event tab: when a database connector re-establishes its connection (a "ready" lifecycle event, e.g. on reconnect), it appears as a framework-sourced <connector>#ready event carrying a safe ok/error summary. Bridging is opt-in through the same settings.inspector.events.topics allow-list as entity events (default empty, so nothing is bridged) and matched by exact name or a single leading or trailing wildcard; these lifecycle events stream live only, with no per-request snapshot.
+* Added a `connector:infer` CLI command that runs a one-off inference against a configured AI connector outside a request: `gina connector:infer <connector> @<project> --message="..."` (or a messages JSON array piped on stdin). It resolves the project's shared + bundle connector config and credentials (`${secret:KEY}` from the environment, never echoed), instantiates the connector directly without booting the bundle, and prints the normalised result — `--format=json` for machine output. Useful for smoke-testing connectivity and credentials from CI/automation, or scripting a one-off inference from the shell. Errors cleanly on a non-AI connector.
+* Added a `--stream` mode to `connector:infer` that streams the inference as newline-delimited JSON (NDJSON) — one frame per line on stdout: a `start` frame, a `delta` frame per token, then a terminal `done` frame (content, model, usage, latency) or an `error` frame. Token counters are passed through verbatim and never fabricated — they are `null` when the provider does not report them (some providers report token usage only in a final chunk, or omit it entirely). `--stream` always emits NDJSON regardless of `--format`, for token-by-token consumption from CI or a shell.
+* `gina connector:test` — probe configured connectors for readiness and exit non-zero on any failure (CI-friendly). Validate-only by default and offline: for each connector it checks the type / `ai` protocol is recognised, the npm driver is installed, and every `${secret:KEY}` placeholder resolves from the environment. `--connect` adds a live probe — for `ai` connectors it calls the provider models.list (zero generation tokens; `ollama://` confirms the local server is up). `gina connector:test [<connector> [<bundle>]] @<project>` tests one connector or every connector in a project; `--format=json` emits a machine-readable readiness report.
+* gina connector:infer gains a --raw flag that opts the heavy provider response back into the output (omitted by default for CLI use). With --format=json it adds a raw field carrying the full provider response; with --stream it adds raw to the final done frame (the final provider message object, or null for OpenAI-compatible streams, which expose no single final object). It has no effect in text mode.
+### Changed
+* `gina stop` (alias of `framework:stop`) now lists any bundles still running when it exits and points to `gina bundle:stop` / `gina project:stop` — it stops the framework socket server only, not the detached bundle processes, which keep running. The framework CLI `--help` and man page now document `start`/`stop`/`restart` and make the daemon-only scope of `stop` explicit.
+### Fixed
+* gina project:import is now additive across release targets. Previously, importing a project for one scope and env rebuilt the per-bundle manifest.json release map from scratch, dropping any targets registered under other scopes or envs (and resetting custom target paths and versions). Import now preserves the existing release map and only seeds a default target for the scope/env cells that have none, so registering a brand-new scope no longer wipes the release targets already in use.
+* The development Inspector /_gina/agent SSE endpoint now streams live AI token-stream and application-event frames over the HTTP/1 server, matching the HTTP/2 (isaac) engine SSE and the WebSocket transport. Previously these two live frame types only reached Inspector clients connected over the isaac SSE or the WebSocket.
+* The Couchbase connector now substitutes a positional placeholder used as a dynamic field-path key (a `<field>.$N` component, e.g. `SET doc.flags.$2 = $3`) at every occurrence in a prepared statement. Previously, when the same `$N` was used as a field-path component in more than one clause (for example once in SET and once in WHERE), only the last occurrence was interpolated and the earlier one was left as a literal `$N`, producing malformed N1QL; a lower-numbered placeholder could also bleed into a higher-numbered one (`$3` into `$30`). Value placeholders (`= $N`, `LIMIT $N`) are unaffected and still bind positionally.
+* AI connectors now expose their inference API through getModel(): getModel(name).infer(...) and getModel(name).stream(...) work as documented. Previously the model loader treated an AI connector factory like an entity manager, so getModel() returned only a bare connection wrapper without infer/stream — and self.inferAsync plus AI token-stream capture, which build on it, were unreachable.
+* The model loader no longer crashes with a ReferenceError when a connectors.json entry has no resolvable connector module. The "No connector found" error path referenced an undefined variable while constructing its own error, masking the real diagnostic; it now reports the missing connector cleanly.
+* Model-initialization failures at boot on a bundle without an onInitialize handler are no longer silently swallowed. Previously such a bundle started in a degraded state (its model layer dead) and failed later with a cryptic call-time error; it now aborts the boot with a clear message, matching the fail-fast behavior of every other model-init failure path.
+* A native `<dialog>` popin closed by the user agent — pressing Escape, or submitting a `<form method="dialog">` inside it — now runs the same cleanup as the close button. Previously only the framework's own close paths cleaned up, so a user-agent close left a reused AJAX popin with stale content and its open state stuck, making the next open of a shared-name popin show the previous fragment.
+* The AI connector core now loads the framework's `lib` registry directly instead of going through the full framework bootstrap, so a configured AI connector can be instantiated outside a running bundle — e.g. by `gina connector:infer` in an offline/CLI context. Previously the bootstrap's bundle-boot path (which resolves a started bundle's listening port) made the connector core un-loadable anywhere but inside a live bundle.
+* Multipart upload filenames carrying non-ASCII UTF-8 characters in the plain Content-Disposition `filename=` parameter are now decoded as UTF-8 instead of busboy's latin1 default. A filename such as "Accusé de réception.pdf" previously reached the upload handler mojibaked ("Accusé de réception.pdf") and was persisted under that mangled name. The RFC 5987 `filename*` form (self-describing) and ASCII field names are unaffected.
+* gina connector:infer now writes its buffered result with synchronous I/O, so the full output is no longer truncated when stdout is a pipe (for example | jq, command substitution, or CI) — previously the process could exit before the OS pipe buffer was flushed, cutting off large responses. --message now takes precedence over a piped stdin messages array (an accidentally non-TTY stdin such as a heredoc or redirected file no longer overrides an explicit --message), and --format is matched strictly so only --format=json emits JSON while jsonl and json5 fall back to the text output.
+* DELETE route matching no longer crashes with a 500 ("Invalid regular expression ... Unterminated group") when a route requirements pattern ends in a group-close immediately before the regex flag (for example /(^null$|^[0-9A-Za-z]{6}$)/i). An off-by-one in the DELETE-only requirement un-delimiting over-stripped the final pattern character, so the first such route reached while scanning broke the entire DELETE dispatch — even a DELETE to an unrelated route. A requirement ending )$/i previously lost its $ end anchor silently; it is now kept.
+* DELETE route matching now honours the regex flags on a route requirements pattern (for example /^foo$/i), matching the GET path. Previously the DELETE-only matcher dropped the trailing flags when un-delimiting the pattern, so a requirement written to be case-insensitive matched case-sensitively on DELETE while the same pattern matched case-insensitively on GET.
+* The connector:add --help output and the AI connector JSDoc examples now show the working ${secret:KEY} placeholder for injecting an API key or password into a connector entry, instead of a bare ${ENV_VAR} form. A bare ${ENV_VAR} placeholder is never substituted at config-load time — only ${secret:KEY} placeholders are resolved from the environment — so the previous examples would have produced a connector that used the literal placeholder string as its credential.
+* gina connector:test now fails a connector whose config carries a bare ${ENV_VAR} placeholder (for example an apiKey of ${ANTHROPIC_API_KEY}). Such a placeholder is never substituted at config-load time — only ${secret:KEY} placeholders are resolved from the environment — so the connector would otherwise use the literal placeholder string as its value; the default validate-only run previously reported it as passing. A new `envvar` check surfaces the offending field and the fix (use ${secret:KEY}), and a registered project whose directory is missing is now reported as a failure in the all-projects report.
+* connector:infer now recognises an AI connector declared as just "ai": { ... } with no explicit "connector" field (the shape connector:add writes when the name equals the type). It previously rejected such an entry with a self-contradictory "is a `ai` connector, not `ai`" error, because it required the "connector" field while connector:list and connector:test already accept the entry key as a fallback. Separately, the lib/connector-config resolver now returns a DEEP copy of the selected entry, so resolving a nested ${secret:KEY} placeholder in place can never mutate the shared parsed-JSON (requireJSON) cache.
+* `gina connector:test` now resolves every connector entry through the shared connector-config resolver — the same deep-copying path `connector:infer` uses — instead of an inline shallow merge. When testing a whole project or every registered project, each entry is now a fresh deep copy, so an in-place ${secret:KEY} resolution during a --connect live probe can no longer mutate the shared parsed-config cache through a nested placeholder.
+* A corrupt project registration in `~/.gina/projects.json` — an empty or missing path, or a path pointing at a deleted directory — no longer aborts EVERY gina command with a stack-trace dump. A registry entry with an empty/invalid path is now skipped with a clear warning (re-add it with `gina project:add`), and running a command against a project whose directory has been deleted prints an actionable message (re-add it, or remove the stale entry with `gina project:remove --force`) instead of crashing.
+
 ## 0.5.5 - 2026-06-22
 ### Added
 * Added gina project:move to relocate a project source tree to a new filesystem path. The project name, its home directory, the port matrix, and its bundles are preserved (only the registry path is updated). It refuses while any bundle in the project is running, refuses a cross-filesystem target (pointing you to project:import), and reverses the move on failure.

package/README.md

@@ -1,6 +1,6 @@
 # Gina
 
-[![npm version](https://img.shields.io/npm/v/gina)](https://www.npmjs.com/package/gina) [![npm downloads](https://img.shields.io/npm/dm/gina)](https://www.npmjs.com/package/gina) [![GitHub stars](https://img.shields.io/github/stars/gina-io/gina)](https://github.com/gina-io/gina/stargazers) [![Tests](https://github.com/gina-io/gina/actions/workflows/test.yml/badge.svg)](https://github.com/gina-io/gina/actions/workflows/test.yml) [![Socket Badge](https://socket.dev/api/badge/npm/package/gina)](https://socket.dev/npm/package/gina) [![Node.js >= 22](https://img.shields.io/badge/node-%3E%3D%2022-brightgreen)](https://nodejs.org) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/gina)](https://www.npmjs.com/package/gina) [![npm downloads](https://img.shields.io/npm/dm/gina)](https://www.npmjs.com/package/gina) [![GitHub stars](https://img.shields.io/github/stars/gina-io/gina)](https://github.com/gina-io/gina/stargazers) [![Tests](https://github.com/gina-io/gina/actions/workflows/test.yml/badge.svg)](https://github.com/gina-io/gina/actions/workflows/test.yml) [![Socket Badge](https://socket.dev/api/badge/npm/package/gina)](https://socket.dev/npm/package/gina) [![Node.js >= 22](https://img.shields.io/badge/node-%3E%3D%2022-brightgreen)](https://nodejs.org) [![Bun >= 1.2](https://img.shields.io/badge/Bun-%3E%3D%201.2-brightgreen)](https://bun.sh) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 > **Documentation:** [gina.io/docs](https://gina.io/docs/) · **Issues:** [GitHub](https://github.com/gina-io/gina/issues) · **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
 
@@ -40,16 +40,13 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
-## What's in 0.5.5
+## What's in 0.5.6
 
-- **WebSocket routes in `routing.json`.** Declare a WebSocket-over-HTTP/2 endpoint with `"method": "ws"` and a `param.wsHandler` pointing at a `channels/<name>.js` handler — auto-registered at bundle start, no `app.onWebSocket()` call needed. Routes support `:param` path segments and per-route `param.wsOptions` (`maxPayload` / `protocol` / `closeTimeout`).
-- **Cross-bundle calls from a channel handler.** A WebSocket handler can now call another bundle over HTTP with `session.query()` — the same warm-HTTP/2-session call a controller makes with `self.query()`.
-- **Framework versions side-by-side.** `gina framework:add <version>` installs a published framework version alongside the active one so a bundle can pin it via `--gina-version`; `framework:list` / `framework:remove` / `framework:update` / `framework:reset` round out the set.
-- **Project lifecycle CLI.** `gina project:move --to=<path>` relocates a project's source tree (and its registry entry); `project:backup` / `project:restore` archive a project to a `.zip` and rebuild it.
-- **Inline CLI man pages.** `gina framework:man` (and `project:man` / `bundle:man` / `service:man`) renders a command group's manual page in the terminal.
-- **Bun is now a supported runtime.** Install with `bun add -g gina`; the install + boot path is validated end-to-end by a CI Bun smoke.
-- **Idempotent HTTP/2 client retries.** Inter-bundle `self.query()` now auto-retries only HTTP safe methods on a transient transport failure, so a `POST` / `PUT` / `PATCH` / `DELETE` the upstream already executed is no longer silently replayed; opt a non-safe call back in with `retryUnsafe: true`.
-- **Security.** A WebSocket denial-of-service fix via an `ws` dependency override (reached through `engine.io`), plus log-tail restart hardening.
+- **AI-connector CLI suite.** `gina connector:infer <connector> @<project> --message="…"` runs a one-off inference against a configured AI connector **outside a running bundle** — resolves the merged connector config + `${secret:KEY}` credentials (never echoed), instantiates the connector directly, and prints the normalised result. `--stream` emits token frames as NDJSON, `--raw` adds the full provider response, `--format=json` for machine output. `gina connector:test [<connector>] @<project>` probes connectors for readiness (driver installed, `${secret:KEY}` resolvable), exits non-zero on any failure (CI-friendly); `--connect` adds a zero-generation-token live provider check.
+- **Streaming AI inference.** `getModel('<name>').stream(messages, options)` returns an EventEmitter emitting `start` / `delta` / `done` / `error` for token-by-token inference across Anthropic and every OpenAI-compatible provider (plus an `.onComplete(cb)` shim); the buffered `infer()` is unchanged.
+- **AI stream + application events in the Inspector.** A new dev-Inspector **"AI stream"** tab shows token streams per request; a new **"Events"** tab surfaces named application events emitted with `self.emitEvent(name, metadata)`, with opt-in bridges (`settings.inspector.events.topics`) that surface whitelisted entity events and database connector-lifecycle (`<connector>#ready`) events.
+- **`getModel()` exposes the AI inference API.** `getModel(name).infer(…)` and `getModel(name).stream(…)` now work as documented — previously an AI connector returned only a bare connection wrapper.
+- **Robustness fixes.** Boot aborts with a clear message on a model-init failure instead of starting degraded (#B57); a corrupt `~/.gina/projects.json` registration is skipped with a warning instead of crashing every command (#B59); DELETE-route requirement regexes honour their flags and no longer crash on a group-close-before-flag pattern; multipart upload filenames with non-ASCII UTF-8 characters are decoded correctly; a native `<dialog>` popin closed by the user agent (Escape / dialog-method form) runs the same cleanup as the close button; the Couchbase connector substitutes a positional placeholder used as a dynamic field-path key at every occurrence; `gina project:import` is now additive across release targets; `gina stop` reports any bundles still running.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -30,6 +30,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q2 2026** | `0.5.3` ✅ | Patch: released-response crash family finished — late `throwError(status, error)` (2- and 3-argument forms) and the HTML render delegates (swig / nunjucks + async variants) no longer crash or emit unhandled rejections when invoked on an already-released response · atomic `~/.gina` state-file writes (concurrent multi-bundle / multi-container boot can't read a torn file) · framework command-socket hardened against malformed / fragmented payloads · framework socket port no longer corrupted by a bundle's `--port` · synchronous boot-failure diagnostics under piped stdout/stderr · storage `_id` collision hardening · `gina port:set --force` |
 | **Q2 2026** | `0.5.4` ✅ | Node.js 26 support (engine `>= 22 <27`, CI matrix) · FormValidator fixes (`isFloat` accepts string floats · `isDate` non-ISO masks + rule chaining) · quieter live form validation (error message revealed on blur) · file-upload fixes (honour `tmpPath` / per-group `path` · enforce `maxFields` + `maxFieldsSize` unit suffix · **Security**: reject uploads to an unconfigured group, closing an `allowedExtensions` / `isMultipleAllowed` bypass) · two dev-mode heap fixes (hot-reload lib-eviction leak · HTTP/2 `self.query()` settled-stream retention) · tighter per-request config isolation (narrowed router clone · `getRouteByUrl` shared-config mutation) · dev Inspector reliability (per-tab channel under COOP · Swig render-race isolation · multi-bundle proxy log/index routing · SPA hardening) · Express-engine `/_gina/info` + `/_gina/cache/stats` parity · `bundle:add --ignore-ports` |
 | **Q2 2026** | `0.5.5` ✅ | WebSocket routes in `routing.json` (`method: "ws"` + `param.wsHandler` → `channels/<name>.js`, `:param` paths, per-route `param.wsOptions`) · cross-bundle `session.query()` from WebSocket channel handlers · framework version side-by-side CLI (`framework:add` / `framework:list` / `framework:remove` / `framework:update` / `framework:reset`) · `project:move` / `project:backup` / `project:restore` · inline CLI man pages (`framework:man` / `project:man` / `bundle:man` / `service:man`) · Bun promoted to a supported, CI-gated runtime · idempotent HTTP/2 client retries (safe-method gating + per-call `retryUnsafe` opt-in) · **Security**: WebSocket-DoS dependency hardening (`ws` override) · `tail` restart hardening |
+| **Q3 2026** | `0.5.6` ✅ | AI-connector CLI suite — `connector:infer` (one-off inference · `--stream` NDJSON · `--raw`) + `connector:test` (CI readiness probe · `--connect` zero-token live check) · AI connector `stream()` + Inspector "AI stream" tab · application events in the Inspector — `self.emitEvent()` + a new "Events" tab, opt-in entity-event & connector-lifecycle bridges · `getModel()` exposes the AI `infer`/`stream` API · fixes: model-init fail-fast · corrupt `projects.json` registration skipped cleanly · DELETE-route regex flags + off-by-one crash · UTF-8 multipart upload filenames · native `<dialog>` popin close cleanup · Couchbase dynamic field-path placeholder · `project:import` additive across release targets · `gina stop` bundles-still-running notice |
 | **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 |
 
@@ -228,6 +229,8 @@ New database connectors follow the same interface as the existing Couchbase conn
 | ✅ | **Couchbase SDK v2 removal** | `0.4.0` | 2026-05-22 | `connector.v2.js` and `session-store.v2.js` removed, along with every `sdkVersion`-based v2 branch in `index.js` (consistency setup, prepared-statement builder, FTS substitution, query dispatch, and the `bulkInsert` path). The connector and session-store resolvers default to SDK v3 and fail fast with an explicit upgrade message when a project still pins `couchbase@2`. Migration is a driver bump (`npm install couchbase@^4`), not a `connectors.json` edit — `sdk.version` is derived from the installed `couchbase` npm major, never a config key. |
 | ✅ | **`peerDependencies` for connector clients** | `0.3.0` | 2026-04-01 | All connector client libraries (`ioredis`, `mysql2`, `pg`, `mongodb`, `@scylladb/scylla-driver`, `couchbase`, `openai`, `@anthropic-ai/sdk`) are declared as optional `peerDependencies`. Signals the tested version range to npm/yarn and surfaces a compatibility warning when a user pins an untested version. Zero framework runtime dependency — clients are always loaded from the project's `node_modules`. |
 | ✅ | **`connector:*` CLI group + lint/fix migration** | `0.3.8` | Q2 2026 | New CLI for managing `connectors.json` at project (shared) or bundle scope: `connector:list`, `connector:add`, `connector:rm`, `connector:migrate`. Positional-absence signals scope — omit `<bundle>` to operate on `shared/config/connectors.json`, include it to operate on the bundle's own. `list` cross-references declared connectors against the project's `node_modules` and prints install status per driver. `add` writes the JSON entry and prints the exact `npm install <driver>@<range>` command (no auto-install in v1). `rm` supports `--dry-run` / `--force` and scans sibling bundles for usage before removing at project scope. `migrate` lints every `connectors.json` (or a single bundle's file) and, with `--fix`, injects missing `$schema` entries while preserving comment headers and key order — dry-run by default. Framework-side auto-migrate hook deferred to `0.4.0` alongside the Couchbase SDK v2 removal where a concrete old-shape → new-shape delta will justify touching the boot path. Adds a `version` property to the `connectors.json` schema for install-version resolution. Optional follow-up: `--install` flag with lockfile-based package manager detection. **Session 1 (`connector:list`) shipped 2026-04-21, `0.3.7-alpha.3`** — read-only lister with overlay/override detection, driver install probing, version-pin disagreement warnings, JSON output, 89 source-inspection unit tests. **Session 2 (`connector:add` + schema `version`) shipped 2026-04-21, `0.3.7-alpha.3`** — writes shared or bundle-scoped connector entries, infers type from `<name>`, preserves comment headers and key order, pins `$schema` at the top, rejects overwrites without `--force`, prints `npm install <pkg>@"<range>"` install hint (AI resolves per protocol scheme, sqlite short-circuits to built-in note), adds `version` property to `schema/connectors.json`. 94 source-inspection unit tests; 7 live smoke tests. CLI flag rename (`--connector-port=`/`--driver-version=`) avoids framework-reserved `--port`/`--version`. **Session 3 (`connector:rm`) shipped 2026-04-21, `0.3.7-alpha.3`** — removes shared or bundle-scoped entries via positional-absence scoping (`remove` alias accepted); `--dry-run` previews without writing; `--force` skips the project-level usage guard that otherwise refuses when any bundle still references the same logical name; driver-retention hint prints after every removal naming sibling bundles that still use the same driver (sqlite exempt — built-in); inherited-from-shared hint fires when rm from a bundle targets an entry declared only in shared. Never runs `npm uninstall`. 81 source-inspection unit tests. **Session 4 (`connector:migrate`) shipped 2026-04-21, `0.3.7-alpha.3`** — CLI-only linter: dry-run by default, `--fix` applies auto-fixable issues in place. Two detection types: `missing-schema` (auto-fixable, injects `"$schema": "https://gina.io/schema/connectors.json"` pinned at top while preserving comment header and key order) and `bare-key-no-connector` (entry key not in `couchbase, mysql, postgresql, sqlite, redis, ai` enum with no `connector` field — warn-only since driver cannot be inferred). Two invocation modes via positional-absence: `@<project>` scans shared + every bundle; `<bundle> @<project>` scans just that bundle. `--format=json` emits `{project, scope, bundle, fixApplied, files[]}` envelope for CI. Registered as offline — no framework socket required. Idempotent. Never modifies `core/config.js` and never runs at bundle boot — explicit and opt-in. Real framework-side hook deferred to `0.4.0` alongside Couchbase SDK v2 removal. 87 source-inspection unit tests; full write-path smoke test on a disposable sandbox (shared + two bundles), plus a no-false-positive smoke on a real 7-bundle project. |
+| ✅ | **`connector:infer` — one-off AI inference CLI** | `0.5.6-alpha.3` | Q2 2026 | Runs a single inference against a configured `ai` connector **outside a request** — the runtime sibling of the config-only `connector:list`/`add`/`rm`/`migrate` tooling. Resolves the project's shared (or shared+bundle merged) `connectors.json`, resolves `${secret:KEY}` credentials from the CLI's own environment (the resolved value is never echoed), instantiates the connector directly (no bundle boot, no framework socket), and prints the normalised result. `gina connector:infer <connector> [<bundle>] @<project> --message="..."`, with `--system` / `--model` / `--max-tokens` / `--temperature` per-call overrides; `--message` takes precedence over a messages JSON array piped on stdin. `--format=json` (matched strictly — `jsonl`/`json5` fall back to the text output) emits `{ content, model, usage }`, with `--raw` adding the full provider response as a `raw` field (omitted by default for CLI use); text mode writes the content to stdout and a model/usage footer to stderr. `--stream` streams the inference as newline-delimited JSON (NDJSON) — one frame per line on stdout: a `start` frame, a `delta` frame per token, then a terminal `done` (content, model, usage, latency; plus the provider `raw` object under `--raw` — `null` for OpenAI-family streams) or `error` frame; token counters are passed through verbatim and are `null` (never fabricated) when a provider does not report them. Errors cleanly on a non-`ai` connector, and surfaces missing-SDK / credential / transport failures with a non-zero exit and the reason on stderr. Useful for smoke-testing connectivity + credentials from CI/automation, or scripting a one-off inference from a shell; offline providers such as `ollama://` work with no paid-API key. Implemented 2026-06-30 (`connector:infer` + the `--stream` NDJSON mode; a later output-hardening pass added `--raw`, pipe-safe synchronous writes, and `--message`-over-stdin precedence). |
+| ✅ | **`connector:test` — connector readiness probe CLI** | `0.5.6-alpha.3` | Q2 2026 | Probes a project's configured connectors for readiness **outside a request** — the CI-friendly sibling of `connector:list` (driver-install status only) and `secrets:check` (env presence only), answering "is this connector ready to use?". Default is validate-only and offline: per connector it checks the `connector` type / `ai` protocol is recognised, the npm driver is installed at `<project>/node_modules`, and every `${secret:KEY}` placeholder resolves from the environment — no network, no connector instantiated — exiting non-zero when any connector fails so it can gate a deploy. `gina connector:test [<connector> [<bundle>]] @<project>` tests one connector or every connector in a project (bare → every registered project), mirroring `connector:infer`'s positional grammar and `secrets:check`'s all-mode; `--format=json` emits a machine-readable readiness report. The `--connect` opt-in adds a live connectivity probe: for `ai` connectors it calls the provider's `models.list` (a credentialed request that authenticates with **zero generation tokens**; `ollama://` confirms the local server is up), resolving `${secret:KEY}` the way `connector:infer` does (the value is never printed). For DB/cache connectors the live `--connect` probe is reported as **skipped** for now (config / driver / secrets are still validated) — the live DB/cache probe is a follow-up, since those connector classes load `core/gna` (which exits the process outside a booted bundle) and cannot be instantiated the way the AI connector is. Implemented 2026-06-30. |
 
 ---
 
@@ -318,6 +321,7 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | ✅ | **AI connector** — Declare any LLM provider in `connectors.json` via named protocol (`anthropic://`, `openai://`, `deepseek://`, `qwen://`, `groq://`, `mistral://`, `gemini://`, `xai://`, `perplexity://`, `ollama://`). Unified `.infer(messages, options)` normaliser + raw `.client` for advanced use. | `0.3.0` | Q1 2026 |
 | ✅ | **`renderStream` — streaming responses** — `self.renderStream(asyncIterable, contentType)` streams SSE or chunked JSON without buffering. Required for LLM token streaming without bypassing the render pipeline. | `0.3.0` | 2026-03-31 |
 | ✅ | **Async job pattern for slow AI calls** — First-class "start job → return jobId → poll or webhook on completion" pattern, backed by the `lib/job` primitive (`self.startJob` / `self.inferAsync`, always-on `/_gina/jobs/:id` polling, opt-in completion webhook). Prevents LLM latency (1–30s) from blocking the response pipeline. | `0.4.0` | 2026-05-22 |
+| ✅ | **AI connector streaming + Inspector AI-stream tab** — `getModel('<name>').stream(messages, options)` returns an EventEmitter emitting `start`/`delta`/`done`/`error` for token-by-token inference (plus an `.onComplete(cb)` shim mirroring `infer()`), across Anthropic and every OpenAI-compatible provider; the buffered `.infer()` is unchanged. The dev Inspector gains an "AI stream" tab — live token frames (model, role, running token counts, latency) plus an end-of-request snapshot; stream metadata is always captured in dev mode, while the prompt and generated text ride the wire only when the opt-in `inspector.ai.captureText` setting is enabled (default off). | `0.5.6-alpha.2` | 2026-06-24 |
 
 ### Phase 3 — AI agents can consume Gina apps
 
@@ -374,6 +378,7 @@ Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/
 | ✅ | **Query tab** — Per-request query instrumentation via AsyncLocalStorage in the Couchbase connector. Cross-bundle propagation via `__ginaQueries` JSON sidecar. Split trigger badge (entity\|method), SQL syntax highlighting, params table, free-text search. Tagged with `origin` (bundle) and `connector`. | `0.3.0-alpha.1` | 2026-04-03 |
 | ✅ | **Remove legacy toolbar from `gina.min.js`** — Toolbar AMD module removed from RequireJS bundle. The `statusbar.html` shim is now the sole provider of `window.ginaToolbar` in dev mode. Guard fixes in `events.js` (unguarded call, `typeof == 'object'` null bug). Source directory retained for reference. | `0.3.0-alpha.1` | 2026-04-03 |
 | ✅ | **Reorganize Inspector source to match plugin conventions** — Source moved into `html/`, `css/`, `js/`, `sass/` subdirectories. CSS converted to SCSS with nesting. Build script Phase 2 skips Inspector; Phase 3 compiles SCSS and copies to flat dist. Inspector CSS served separately, not concatenated into `gina.min.css`. | `0.3.0-alpha.1` | 2026-04-04 |
+| ✅ | **Events tab — application & framework events** — `self.emitEvent(name, metadata)` emits a named runtime event that streams live to a new Inspector "Events" tab (and appears in the end-of-request snapshot); events emitted outside a request still stream live. Opt-in bridges surface whitelisted **entity** trigger events and database **connector-lifecycle** (`<connector>#ready`) events as framework-sourced events via `settings.inspector.events.topics` (exact name or a single leading/trailing wildcard). Capture is gated to dev mode or an open instrumentation window; the event name always rides the wire, while metadata values are opt-in via `settings.inspector.events.captureArgs` (default off). | `0.5.6` | 2026-06-30 |
 
 ### Phase 3 — Production
 

package/framework/v0.5.6/VERSION

@@ -0,0 +1 @@
+0.5.6

package/framework/{v0.5.6-alpha.2 → v0.5.6}/core/asset/plugin/dist/vendor/gina/inspector/index.html

@@ -37,6 +37,9 @@
       <button class="bm-tab" data-tab="stream">
         <svg class="bm-tab-icon" viewBox="0 0 16 16"><path d="M3 8a1.5 1.5 0 11-3 0 1.5 1.5 0 013 0zM9.5 8a1.5 1.5 0 11-3 0 1.5 1.5 0 013 0zM16 8a1.5 1.5 0 11-3 0 1.5 1.5 0 013 0z" fill="currentColor"/></svg>
         Stream</button>
+      <button class="bm-tab" data-tab="events">
+        <svg class="bm-tab-icon" viewBox="0 0 16 16"><path d="M1 8h3l2-5 3 11 2.5-6H15" fill="none" stroke="currentColor" stroke-width="1.3" stroke-linejoin="round" stroke-linecap="round"/></svg>
+        Events</button>
     </nav>
     <div class="bm-header-spacer"></div>
     <button class="bm-refresh-btn" id="bm-refresh" title="Refresh now (Shift+click: reload page)" aria-label="Refresh data">
@@ -187,6 +190,13 @@
     </div>
   </section>
 
+  <!-- Application events tab -->
+  <section id="tab-events" class="bm-panel" aria-label="Application events">
+    <div class="bm-scroll-area" data-tab="events">
+      <pre class="bm-raw-view" id="tree-events"></pre>
+    </div>
+  </section>
+
   <!-- ── Logs tab ── -->
   <section id="tab-logs" class="bm-panel" aria-label="Logs">
     <div class="bm-logs-controls">

package/framework/{v0.5.6-alpha.2 → v0.5.6}/core/asset/plugin/dist/vendor/gina/inspector/inspector.js

@@ -106,17 +106,17 @@
     /**
      * Tab order definitions for each layout preset.
      *
-     * - **balanced** (default) — Data, View, Logs, Forms, Query, Flow, Stream
-     * - **backend** — Data, Query, Flow, Logs, View, Forms, Stream
-     * - **frontend** — View, Data, Forms, Logs, Query, Flow, Stream
+     * - **balanced** (default) — Data, View, Logs, Forms, Query, Flow, Stream, Events
+     * - **backend** — Data, Query, Flow, Logs, View, Forms, Stream, Events
+     * - **frontend** — View, Data, Forms, Logs, Query, Flow, Stream, Events
      *
      * Each array contains `data-tab` attribute values in display order.
      * @constant {Object.<string, string[]>}
      */
     var TAB_LAYOUTS = {
-        balanced: ['data', 'view', 'logs', 'forms', 'query', 'flow', 'stream'],
-        backend:  ['data', 'query', 'flow', 'logs', 'view', 'forms', 'stream'],
-        frontend: ['view', 'data', 'forms', 'logs', 'query', 'flow', 'stream']
+        balanced: ['data', 'view', 'logs', 'forms', 'query', 'flow', 'stream', 'events'],
+        backend:  ['data', 'query', 'flow', 'logs', 'view', 'forms', 'stream', 'events'],
+        frontend: ['view', 'data', 'forms', 'logs', 'query', 'flow', 'stream', 'events']
     };
 
     /**
@@ -171,6 +171,16 @@
      * @type {{id: ?string, frames: Object[]}}
      */
     var _aiStreamBuf = { id: null, frames: [] };
+    /**
+     * Live application-event buffer (#EVTBUS). Unlike the single-slot token buffer,
+     * this ACCUMULATES discrete events (capped at EVENT_BUF_MAX) so the Event tab
+     * shows the rolling sequence as they fire; the end-of-request snapshot
+     * (user.events) carries the events of one request.
+     * @type {Object[]}
+     */
+    var _eventBuf     = [];
+    /** @constant {number} Cap on the rolling live event buffer. */
+    var EVENT_BUF_MAX = 500;
     /** @type {LogEntry[]} In-memory log buffer (capped at {@link MAX_LOG_ENTRIES}) */
     var logs    = [];
     /** @type {number} Read offset into `source.__ginaLogs` for client-side polling */
@@ -1784,6 +1794,8 @@
             // #AISTREAM \u2014 the Stream tab renders its live token buffer even before
             // a snapshot exists, so don't blank it with the "Waiting\u2026" hint.
             if (name === 'stream') { renderAiStream(treeEl, null); return; }
+            // #EVTBUS — same for the Event tab's rolling live buffer.
+            if (name === 'events') { renderAppEvents(treeEl, null); return; }
             treeEl.innerHTML = '<span class="bm-hint">Waiting for source data\u2026</span>';
             return;
         }
@@ -1851,6 +1863,12 @@
                 // and return before the innerHTML/fold path; token text is untrusted.
                 renderAiStream(treeEl, u.aiStream);
                 return;
+            case 'events':
+                // #EVTBUS — render the rolling live buffer (or the request snapshot)
+                // via textContent; return before the innerHTML/fold path. Event
+                // names + metadata are app-controlled but treated as untrusted.
+                renderAppEvents(treeEl, u.events);
+                return;
         }
 
         treeEl.innerHTML = content || '<span class="bm-empty">No data</span>';
@@ -1963,6 +1981,72 @@
         }
     }
 
+    // ── Application-event tab (#EVTBUS) ──────────────────────────────────────
+
+    /**
+     * Append one live application-event frame to the rolling buffer (capped at
+     * EVENT_BUF_MAX) and, when the Event tab is active, re-render it directly.
+     * Unlike appendTokenDelta (single-slot, reset per stream id), events ACCUMULATE
+     * — each frame is one discrete event. Rendered via textContent (event names +
+     * optional metadata are app-controlled but treated as untrusted).
+     * @inner
+     * @param {Object} frame - The inspector#event frame `{ name, id, t, meta? }`.
+     */
+    function appendAppEvent(frame) {
+        if (!frame || typeof frame !== 'object' || !frame.name) { return; }
+        _eventBuf.push(frame);
+        if (_eventBuf.length > EVENT_BUF_MAX) { _eventBuf.shift(); }
+        // Live-tail directly when the tab is open — NOT via renderTab (which a data
+        // snapshot would re-render). Mirrors appendTokenDelta's direct-render.
+        if (activeTab() === 'events') {
+            var el = qs('#tree-events');
+            if (el) { el.textContent = formatEventBuffer(_eventBuf); }
+        }
+    }
+
+    /**
+     * Format an array of event frames/entries as a plain-text transcript — one line
+     * per event (time · name · compact metadata, present only when captureArgs is
+     * enabled server-side). Rendered via textContent by the caller; never innerHTML.
+     * @inner
+     * @param {Object[]} arr
+     * @returns {string}
+     */
+    function formatEventBuffer(arr) {
+        if (!arr || !arr.length) { return 'No events captured.'; }
+        return arr.map(function (e) {
+            var ts = '';
+            try { ts = new Date(e.t).toISOString().substr(11, 12); } catch (x) { ts = ''; }
+            var line = (ts ? ts + '  ' : '') + (e.name || '?');
+            if (e.meta && typeof e.meta === 'object') {
+                var s;
+                try { s = JSON.stringify(e.meta); } catch (x) { s = '[unserialisable]'; }
+                line += '  ' + s;
+            }
+            return line;
+        }).join('\n');
+    }
+
+    /**
+     * Render the Event tab pane. Prefers the rolling live buffer (events accumulate
+     * across the session); falls back to the request snapshot (`user.events`) when
+     * no live frames have arrived (e.g. opener-only mode without an agent stream).
+     * Always textContent — event names + metadata are treated as untrusted.
+     * @inner
+     * @param {Element} el - The `#tree-events` pane.
+     * @param {?Object[]} snapshot - `user.events`, or null.
+     */
+    function renderAppEvents(el, snapshot) {
+        if (!el) { return; }
+        if (_eventBuf.length) {
+            el.textContent = formatEventBuffer(_eventBuf);
+        } else if (snapshot && snapshot.length) {
+            el.textContent = formatEventBuffer(snapshot);
+        } else {
+            el.textContent = 'No events captured.';
+        }
+    }
+
     /**
      * Render the Data tab in raw JSON mode (pretty-printed `<pre>` block).
      * @inner
@@ -4105,6 +4189,11 @@
                 try { appendTokenDelta(JSON.parse(ev.data)); } catch (e) {}
             });
 
+            es.addEventListener('event', function (ev) {
+                // #EVTBUS — live application-event frame (textContent-rendered).
+                try { appendAppEvent(JSON.parse(ev.data)); } catch (e) {}
+            });
+
             es.addEventListener('open', function () {
                 qs('#bm-dot').className = 'bm-dot ok';
                 // Label stays as "Connecting…" until the first data event updates it
@@ -4221,6 +4310,9 @@
                     } else if (frame.event === 'token') {
                         // #AISTREAM — live AI token-stream frame (textContent-rendered).
                         appendTokenDelta(frame.data);
+                    } else if (frame.event === 'event') {
+                        // #EVTBUS — live application-event frame (textContent-rendered).
+                        appendAppEvent(frame.data);
                     }
                 } catch (e) {}
             };
@@ -4351,6 +4443,11 @@
                 try { appendTokenDelta(JSON.parse(ev.data)); } catch (e) {}
             });
 
+            es.addEventListener('event', function (ev) {
+                // #EVTBUS — live application-event frame (textContent-rendered).
+                try { appendAppEvent(JSON.parse(ev.data)); } catch (e) {}
+            });
+
             es.onerror = function () {
                 // EventSource reconnects automatically. Opener polling is the
                 // primary source here, so no UI state change is needed.

package/framework/{v0.5.6-alpha.2 → v0.5.6}/core/asset/plugin/dist/vendor/gina/js/gina.js

@@ -5405,8 +5405,21 @@ function Routing() {
                         continue;
                     }
                     let condition = params.requirements[_key];
+                    let conditionFlags = '';
                     if ( /^\//.test(condition) ) {
-                        condition = condition.substring(1, condition.lastIndexOf('/')-1);
+                        // Strip the surrounding `/…/<flags>` delimiters to the bare pattern body.
+                        // End index is lastIndexOf('/') (exclusive), NOT -1: the `-1` over-stripped
+                        // the final body char, so a requirement ending `…)/i` (group-close right
+                        // before the flag) lost its closing `)` → `new RegExp(condition)` threw
+                        // "Invalid regular expression: Unterminated group", 500ing every DELETE
+                        // dispatch that scanned it (a `…)$/i` requirement merely lost its `$` anchor).
+                        // Preserve the trailing `/<flags>` too (the segment after the closing `/`)
+                        // and pass it to new RegExp, mirroring the GET path (fitsWithRequirements):
+                        // a requirement written `/.../i` now matches case-insensitively on DELETE as
+                        // well. Previously the flags were dropped here, so DELETE matched
+                        // case-sensitively while GET honoured them — a silent DELETE/GET mismatch.
+                        conditionFlags = condition.substring(condition.lastIndexOf('/') + 1);
+                        condition = condition.substring(1, condition.lastIndexOf('/'));
                     } else if ( /^validator\:\:/.test(condition) && await fitsWithRequirements(uRo[p], uRe[p], params, request, response, next) ) {
                         ++score;
                         continue;
@@ -5414,7 +5427,7 @@ function Routing() {
                     if (
                         /^:/.test(uRo[p])
                         && typeof(condition) != 'undefined'
-                        && new RegExp(condition).test(uRe[p])
+                        && new RegExp(condition, conditionFlags).test(uRe[p])
                     ) {
                         ++score;
                         request[method][uRo[p].substring(1)] = uRe[p];
@@ -19784,6 +19797,30 @@ define('gina/popin', [ 'require', 'lib/domain', 'lib/merge', 'utils/events' ], f
                 }
             }
 
+            // A native <dialog> can be closed by the user agent — pressing Escape, or
+            // submitting a `<form method="dialog">` inside it — which fires the element's
+            // native `close` event WITHOUT going through popinClose(). popinClose() is the
+            // only path that resets `isOpen`, runs popinUnbind() (clearing an AJAX popin's
+            // innerHTML + removing its `loaded.<id>` listener) and restores the toolbar, so
+            // a UA close otherwise leaves the reused element stale and `isOpen` stuck true.
+            // Bind a one-time native `close` listener that runs the same cleanup. We listen
+            // to `close` (not `cancel`): `close` fires for BOTH Escape and method="dialog";
+            // `cancel` is Escape-only. De-dup: on the plugin's own close, popinClose() sets
+            // isOpen=false synchronously before the queued `close` event fires, so the guard
+            // below sees isOpen===false and no-ops (popinClose() also re-guards on !isOpen),
+            // and popinClose()'s $el.close() on an already-closed dialog is a spec no-op so
+            // there is no recursion. `_ginaCloseSyncBound` keeps it to one listener across
+            // element reuse; gated on useDialogMode (non-dialog mode is a <div>, no `close`
+            // event). Native addEventListener — NOT gina's addListener (the custom event bus).
+            if ( self.options.useDialogMode && $el && !$el._ginaCloseSyncBound ) {
+                $el._ginaCloseSyncBound = true;
+                $el.addEventListener('close', function () {
+                    if ( $popin.isOpen ) {
+                        popinClose($popin.name);
+                    }
+                });
+            }
+
             $popin.isOpen = true;
             // so it can be forwarded to the handler who is listening
             $popin.target = $el;