gina 0.5.8-alpha.1 → 0.5.8

package/CHANGELOG.md

@@ -6,6 +6,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.8 - 2026-07-04
+### Added
+* `gina help <group>` now prints help for that command group (e.g. `gina help bundle` shows the bundle command reference), falling back to the top-level help for an unknown group.
+* Added `gina connector:models <connector> @<project> [<bundle>]` — lists the models a configured AI connector's provider can serve (its live catalogue), the read sibling of `connector:test --connect` (which makes the same `models.list()` call but keeps only the count). Text mode prints one model id per line; `--format=json` emits `{ project, connector, provider, count, models }` with each entry passed through verbatim from the provider. Resolves config only and never prints credentials; offline providers such as `ollama://` work with no internet. Exits non-zero on connector-not-found, a non-AI connector, a credential or transport error, or a provider client that cannot enumerate models (reported as unsupported, never a fabricated empty list).
+### Fixed
+* `gina --help`, `gina -h` and `gina help` now print the CLI command reference (usage + command list) instead of exiting with `gina: shortcut not indexed [undefined]`.
+* `gina <group>:help` (e.g. `gina bundle:help`) no longer prints a stray `file <path>` debug line before the help text.
+* CLI help text now shows the correct `--` flag prefix (previously rendered with an em-dash) for `gina --version` and the `project:add` / `project:import` `--path` argument.
+* Running `gina <group>:<action>` with an unrecognised action in a valid command group — e.g. `gina connector` / `gina framework:connector` (connector is its own command group), or `gina -V` — now prints a clear "not a valid command" message that points to `gina help` (and suggests the matching command group when the action names one), instead of crashing with a raw Node "Cannot find module" stack trace.
+* Fixed reverse-proxy host context freezing at the first proxied request. The `PROXY_HOST` / `PROXY_HOSTNAME` worker-globals (derived from a port-less `Host` header or `X-Forwarded-Host`) were captured once behind a one-shot `isProxyHost` gate, so they froze at the first proxied request's value and every later request — plus internal `Controller::query()` forwards that read them — inherited a stale host. The proxy host/scheme is now request-scoped: each request's proxied classification and host are stashed per-request (mirroring the existing `X-Forwarded-Prefix` handling), the worker-global is refreshed on every proxied request so it can never freeze (and, being written only from proxied requests, can never freeze to a raw `host:port`), and the internal-call `X-Forwarded-Host` forward carries the triggering request's proxied host. A raw `host:port` request (no reverse proxy) is never classified as proxied, so its URL builders keep resolving the configured host; single-hop and multi-hop (`X-Forwarded-Host` wins) reverse-proxy topologies are both handled. Server-side only.
+
 ## 0.5.7 - 2026-07-03
 ### Added
 * Added a connector-backed job store to the async-job primitive: point `jobs.store` (app.json) at a `connectors.json` entry and job records persist in SQLite (`node:sqlite` built-in, zero new dependencies) — they survive bundle restarts and are readable cross-process, while the deferred function still runs in the creating process. A configured store that cannot be built fails the boot instead of silently degrading to the in-memory store, and the create/worker race on async stores was hardened away for future backends.

package/README.md

@@ -42,14 +42,11 @@ 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.7
-
-- **Durable async-job stores.** The async-job primitive (`self.startJob` / `lib.job`) can now persist job records in a real backend: point `jobs.store` (app.json) at a `connectors.json` entry and records survive bundle restarts and are readable cross-process — **SQLite** (`node:sqlite` built-in, zero new dependencies), **MongoDB** (shared mongod — durable and visible across processes and pods), or **Redis** (`ioredis`; per-state and expiry indexes maintained atomically so list and sweep never scan the keyspace; Redis Cluster supported via a hash-tagged key prefix). A configured store that cannot be built fails the boot instead of silently degrading to the in-memory store.
-- **Failed-job retry (opt-in).** Pass `maxAttempts` to `self.startJob` / `lib.job.create` and a failed attempt is retried on the creating process with exponential backoff (`jobs.retryBackoffMs` in app.json, default 1000 ms, doubling per attempt). Between attempts the record returns to `pending` with the last error and a `nextRetryAt` timestamp visible; `failed` and `completed` remain strictly terminal, and the completion webhook fires exactly once. The default stays a single attempt — behavior is unchanged unless you opt in.
-- **npm 12 readiness.** The install and release tooling accept npm 12's changed `npm pack --json` output shape, and installing under npm 12's script-blocking default is documented (`npm install -g gina@latest --allow-scripts=gina` — not needed on npm ≤ 11).
-- **Concurrency fixes in the render delegates.** A family of cross-request defects under production concurrency: the swig render cache writer crashed with an HTTP 500 on every cached route in production (#B60); a swig render suspended at its template-read await could resume with a concurrent request's closures and merge that request's page data into its own response (#B61); a finishing stream released a concurrent request's `req`/`res` refs instead of its own and reported stream errors through the wrong controller (#B62); the JSON delegate's cache writer reported cache-configuration errors through a concurrent request's controller (#B63). All per-request state in the delegates is now function-scoped.
-- **Robustness fixes.** A `connectors.json` entry with `"connector": "redis"` no longer aborts the bundle boot — the Redis connector now ships a no-op boot connector, unblocking the documented Redis session-store configuration.
-- **Security — static-asset path traversal fixed.** A request URL with `../` (or its `%2F` / `%2e%2e` percent-encoded forms) could escape a `statics.json` mapping's target directory and read any sibling file under the shared root (config, credentials, server-side source). Both static resolvers now confine the resolved path to its mapping target (or `publicPath`) and return 404 on any escape (#B64); legitimate assets are unaffected and no configuration change is required.
+## What's in 0.5.8
+
+- **New — `gina connector:models`.** List the model catalogue a configured AI connector's provider can serve: `gina connector:models <connector> @<project> [<bundle>]`. It is the read sibling of `connector:test --connect` — the same credentialed `models.list()` call, but it returns the model list instead of only a count. Text mode prints one model id per line; `--format=json` emits `{ project, connector, provider, count, models }` with each entry passed through verbatim from the provider (only `id` is guaranteed across providers). Resolves config only and never prints credentials; offline providers such as `ollama://` work with no internet.
+- **New — per-group `gina help [<group>]`.** `gina help <group>` (e.g. `gina help framework`) prints just that group's commands, and an unknown action now prints a clean message instead of a raw stack trace.
+- **Fixed — reverse-proxy host context no longer freezes (#B65).** For a bundle behind a reverse proxy, the host context derived from a port-less `Host` header or `X-Forwarded-Host` was captured once at the first proxied request and reused for the life of the worker, so later requests — and internal cross-bundle calls — could build URLs against a stale host. It is now re-derived per request: single-hop and multi-hop (`X-Forwarded-Host`) deployments resolve the correct host, and a bundle accessed directly on `host:port` (no proxy) is unaffected. No configuration change required.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -32,6 +32,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **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 |
 | **Q3 2026** | `0.5.7` ✅ | Durable async-job stores — `jobs.store` (app.json) → `connectors.json` entry: SQLite (`node:sqlite`, zero new dependencies) · MongoDB (shared mongod, multi-pod) · Redis (`ioredis`, atomic per-state + expiry indexes, Redis Cluster via hash-tagged prefix); restart-durable, cross-process, fail-fast on an unbuildable store · opt-in failed-job retry (`maxAttempts` + exponential backoff; completion webhook fires exactly once) · npm 12 readiness (install + release tooling, `--allow-scripts=gina` guidance) · render-delegate concurrency fixes (production cross-request data bleed / wrong-controller error routing / cached-route 500) · `"connector": "redis"` entry no longer aborts boot · **Security**: static-asset path-traversal fix — resolver paths canonicalised and confined to their `statics.json` mapping target (404 on any escape, `%2F` / `%2e%2e` forms included) |
+| **Q3 2026** | `0.5.8` ✅ | `connector:models` — list a configured AI connector's provider models (the read sibling of `connector:test --connect`) · per-group `gina help [<group>]` · **Fixed**: reverse-proxy host context request-scoped — `PROXY_HOST` / `PROXY_HOSTNAME` no longer freeze at the first proxied request (single-hop and multi-hop `X-Forwarded-Host` both handled; raw `host:port` unchanged) · CLI help polish (per-group help output, clean message for an unknown action, em-dash flag typos) |
 | **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 |
 
@@ -232,6 +233,7 @@ New database connectors follow the same interface as the existing Couchbase conn
 | ✅ | **`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. |
+| ✅ | **`connector:models` — list an AI connector's provider models** | `0.5.8` | Q2 2026 | Lists the model catalogue a configured `ai` connector's provider can serve — the read sibling of `connector:test --connect` (which makes the same `models.list()` call but keeps only the count). `gina connector:models <connector> @<project> [<bundle>]` prints one model id per line (a count footer on stderr), or `--format=json` emits `{ project, connector, provider, count, models }` with each entry passed through verbatim from the provider (only `id` is guaranteed across providers — Anthropic and OpenAI-family return different fields). Reuses the direct-`AIConnector` bootstrap of `connector:infer` / `connector:test` (no bundle boot, no framework socket); resolves config only and never prints credentials; offline providers such as `ollama://` work with no internet. `isAIConnector`-gated (a non-AI connector is rejected cleanly), and a provider client without `models.list` reports `supported:false` with a non-zero exit rather than a fabricated empty list. Implemented 2026-07-03. |
 
 ---
 

package/framework/v0.5.8/VERSION

@@ -0,0 +1 @@
+0.5.8

package/framework/{v0.5.8-alpha.1 → v0.5.8}/core/controller/controller.js

@@ -3133,7 +3133,10 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         var ctx             = getContext()
             , protocol      = null
             , scheme        = null
-            , isProxyHost   = getContext('isProxyHost')
+            // #B65 — prefer THIS request's proxy classification (per-request slot) over
+            // the sticky worker-global latch, so the internal-call forward reflects the
+            // triggering request; fall back to the global for req-less callers.
+            , isProxyHost   = ( local.req && typeof(local.req._ginaIsProxyHost) != 'undefined' ) ? local.req._ginaIsProxyHost : ( getContext('isProxyHost') || false )
             , bundle        = null
             , webroot       = options.webroot || ctx.gina.config.envConf[ctx.bundle][ctx.env].server.webroot;// bundle servers's webroot by default
         ;
@@ -3197,8 +3200,10 @@ if ( /^local$/i.test(process.env.NODE_SCOPE) ) {
         }
 
         if (isProxyHost) {
+            // #B65 — forward THIS request's proxied host (per-request slot), falling back
+            // to the worker-global for req-less callers (released-response / ws-query).
             // X-Forwarded-Host
-            options.headers['x-forwarded-host'] = process.gina.PROXY_HOST;
+            options.headers['x-forwarded-host'] = ( local.req && local.req._ginaProxyHost ) ? local.req._ginaProxyHost : process.gina.PROXY_HOST;
             // X-Forwarded-Proto
             options.headers['x-forwarded-proto'] = process.gina.PROXY_SCHEME;
         }

package/framework/{v0.5.8-alpha.1 → v0.5.8}/core/server.isaac.js

@@ -1617,23 +1617,42 @@ function ServerEngineClass(options) {
             isProxyHost = getContext('isProxyHost') || false;
             requestHost = request.headers.host || request.headers[':authority'];
             // console.debug('[PROXY_HOST][isProxyHost='+ isProxyHost +'] request.headers.host -> ' + request.headers.host + '  VS request.headers[":authority"] '+ request.headers[':authority'] +' | '+ request.url);
-            if (
-                !isProxyHost
-                && !/\:[0-9]+$/.test(requestHost)
-                ||
-                !isProxyHost
-                && request.headers['x-forwarded-host']
-            ) {
-                // Enable proxied mode
-                process.gina.PROXY_HOSTNAME = process.gina.PROXY_SCHEME +'://'+ requestHost;
-                process.gina.PROXY_HOST     = requestHost;
-                // For internal services communications - Eg.: Controller::query()
-                if (request.headers['x-forwarded-host']) {
-                    process.gina.PROXY_HOSTNAME = request.headers['x-forwarded-proto'] +'://'+ request.headers['x-forwarded-host'];
-                    process.gina.PROXY_HOST     = request.headers['x-forwarded-host'];
-                    // console.debug('[PROXY_HOST][X-FORWARDED-PROTO] override request.headers["x-forwarded-host"] -> ' + request.headers['x-forwarded-host']);
+            // #B65 — request-scope the reverse-proxy host context. Classify THIS
+            // request as proxied when its inbound Host is port-less (a reverse proxy
+            // rewrote it) OR it carries an X-Forwarded-Host; a raw `host:port` access
+            // (no proxy) is never classified proxied, so its URL builders keep
+            // resolving the static config host. The per-request result is stashed on
+            // the request (request._ginaIsProxyHost / _ginaProxyHost / _ginaProxyHostname
+            // — mirrors request._ginaProxyPrefix below) so concurrent requests can't
+            // contaminate each other. The worker-global PROXY_* is refreshed on EVERY
+            // proxied request (NOT gated on the sticky `isProxyHost` latch) so it can
+            // never FREEZE at the first proxied request's value — the same one-shot-gate
+            // defect the x-forwarded-prefix block below calls out. Because the globals
+            // are only ever written from a proxied request, they can never freeze to a
+            // `host:port` (raw) value.
+            var _thisReqProxied = (
+                ( requestHost && !/\:[0-9]+$/.test(requestHost) )
+                || request.headers['x-forwarded-host']
+            ) ? true : false;
+            request._ginaIsProxyHost = _thisReqProxied;
+            if ( _thisReqProxied ) {
+                // this request's proxied host/hostname — X-Forwarded-Host wins (multi-hop:
+                // TLS-terminating ingress -> inner proxy -> bundle), else the port-less
+                // Host (single-hop: reverse proxy -> bundle).
+                if ( request.headers['x-forwarded-host'] ) {
+                    request._ginaProxyHostname = request.headers['x-forwarded-proto'] +'://'+ request.headers['x-forwarded-host'];
+                    request._ginaProxyHost     = request.headers['x-forwarded-host'];
+                } else {
+                    request._ginaProxyHostname = process.gina.PROXY_SCHEME +'://'+ requestHost;
+                    request._ginaProxyHost     = requestHost;
                 }
-                // Forcing context - also available for workers
+                // Refresh the worker-global on EVERY proxied request (freeze fix) — the
+                // value is always this request's proxied host, so a later internal
+                // direct-host call inherits a correct (never direct-frozen) global.
+                // For internal services communications - Eg.: Controller::query()
+                process.gina.PROXY_HOSTNAME = request._ginaProxyHostname;
+                process.gina.PROXY_HOST     = request._ginaProxyHost;
+                // Forcing context - also available for workers (monotonic: only ever true)
                 setContext('isProxyHost', true);
             }
 

package/framework/{v0.5.8-alpha.1 → v0.5.8}/lib/cmd/connector/help.txt

@@ -30,6 +30,12 @@
     infer <connector> <bundle> @<project>
                                  Same, against the bundle's merged
                                  shared+bundle connector view.
+    models <connector> @<project>
+                                 List the models a configured AI connector's
+                                 provider can serve (its live catalogue).
+    models <connector> <bundle> @<project>
+                                 Same, against the bundle's merged
+                                 shared+bundle connector view.
     test                         Probe every connector in every registered
                                  project for readiness (config, driver,
                                  secrets). Exit non-zero on any failure.
@@ -147,6 +153,19 @@
                                  or null for OpenAI-family streams (which expose
                                  no single final object). No effect in text mode.
 
+  Options (models):
+
+    --format=json                Emit `{ project, connector, provider, count,
+                                 models }` (plus `bundle` when a bundle is
+                                 named) instead of one model id per line. Each
+                                 `models[]` entry is passed through verbatim
+                                 from the provider (SDK shapes differ; only
+                                 `id` is guaranteed present).
+    --api-key=<value>            Override the connector's apiKey with a
+                                 literal (bypasses ${secret:...} resolution).
+    --base-url=<url>             Override the provider base URL.
+    --protocol=<uri>             Override the connector protocol scheme.
+
   Options (test):
 
     --connect                    Add a live connectivity probe on top of the
@@ -246,6 +265,20 @@
     NDJSON token frames (one JSON object per line — start / delta / done /
     error) on stdout regardless of `--format`.
 
+    `connector:models` lists the models a configured AI connector's provider
+    can serve — it makes the same `models.list()` call `connector:test
+    --connect` uses, but surfaces the model ids instead of just a count (for
+    populating a model picker, scripting a "offers model X?" check, or
+    auditing reach). It only works with `ai` connectors, resolves the config
+    and instantiates the connector exactly like `connector:infer` (no bundle
+    boot; the provider SDK must be installed in the project), and never prints
+    credentials. Offline providers (`ollama://`) work with no internet. Text
+    mode prints one model id per line to stdout (count footer to stderr);
+    `--format=json` emits `{ project, connector, provider, count, models }`
+    with each entry passed through from the provider. A provider client that
+    exposes no `models.list` is reported UNSUPPORTED with a non-zero exit —
+    never a fabricated empty list.
+
     `connector:test` probes configured connectors for readiness and exits
     non-zero on any failure (so it can gate CI). The default is validate-only
     and offline: for each connector it checks that the type / `ai` protocol is
@@ -324,6 +357,10 @@
     echo '[{"role":"user","content":"hi"}]' | gina connector:infer claude @myproject
                                                                        Multi-turn messages piped as JSON on stdin
 
+    gina connector:models claude @myproject                            List the models the connector's provider can serve (one id per line)
+    gina connector:models claude api @myproject                        Same, as the api bundle sees it (merged shared+bundle)
+    gina connector:models claude @myproject --format=json              Machine-readable { project, connector, provider, count, models }
+
     gina connector:test @myproject                                     Validate every connector in a project (config + driver + secrets)
     gina connector:test claude @myproject                              Validate one connector (shared / merged view)
     gina connector:test claude api @myproject                          Validate one connector as the api bundle sees it