@ggui-ai/cli 0.2.0-alpha.3 → 0.3.0-rc.0

package/README.md

@@ -1,6 +1,6 @@
 # @ggui-ai/cli
 
-> Open `ggui` CLI — the local dev + serve + pair + bench binary for the `ggui` protocol. OSS and self-hosted workflows end-to-end. **No account required.**
+> Open `ggui` CLI — the local dev + serve + authoring binary for the `ggui` protocol. OSS and self-hosted workflows end-to-end. **No account required.**
 
 [![npm version](https://img.shields.io/npm/v/@ggui-ai/cli.svg)](https://www.npmjs.com/package/@ggui-ai/cli)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
@@ -32,7 +32,7 @@ To declare a project (blueprints, primitives, theme, agent entry), drop a `ggui.
 
 ### `ggui serve`
 
-Run the OSS self-hosted personal-mode server: MCP at `/mcp`, session viewer at `/s/<shortCode>`, pairing endpoints, and a live-channel WebSocket. Supervises the agent declared in `ggui.json#agent.entry`.
+Run the OSS self-hosted personal-mode server: MCP at `/mcp`, render viewer at `/s/<shortCode>`, pairing endpoints, and a live-channel WebSocket. Supervises the agent declared in `ggui.json#agent.entry`.
 
 ```bash
 ggui serve                          # default: http://127.0.0.1:6781
@@ -45,12 +45,41 @@ ggui serve --mcp-only               # skip agent supervision
 
 - ✅ Local server, viewer, cookie-authenticated WebSocket subscribe/ack all work end-to-end.
 - ✅ `ggui_render` mints shortCodes and lands on the same-origin viewer.
-- ✅ Component-code generation is wired on the OSS path via `createUiGenerator()` from `@ggui-ai/ui-gen` — the same harness the hosted runtime uses. `ggui_render` returns `codeReady: false` only when no BYOK credentials resolve (no `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / etc.); supply a key to get full generation locally.
-- 🔒 Default auth is dev-mode (any bearer → `builder`). Swap in a real `AuthAdapter` via `createGguiServer({ auth })` before exposing beyond `127.0.0.1`.
+- ✅ Component-code generation is wired on the OSS path via `createUiGenerator()` from `@ggui-ai/ui-gen` — the same harness the hosted runtime uses. When no LLM credentials resolve (no `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / etc.), `ggui_render` still lands a real render — a connect-your-key onboarding card with `codeReady: true` that walks the operator through supplying a key. `codeReady: false` is reserved for failures (generation errors, malformed credentials at boot).
+- 🔒 Default auth is strict pairing — only pair-minted bearer tokens authenticate `/mcp` (pair via the landing page or `POST /pair`). `--dev-allow-all` (local dev / tunnel smoke) and `--public-demo` (rate-limited, operator-paid public demo) relax `/mcp` to any-bearer; `--multi-tenant` keeps strict auth with per-user provider-key scoping; `--oauth` mounts the OAuth 2.1 + DCR routes MCP custom-connector hosts (claude.ai, ChatGPT) need. Custom adapters via `createGguiServer({ auth })`.
 
 ### `ggui dev`
 
-Start the local UI registry + compile-on-demand dev hub, optionally supervising a local agent runtime. See `ggui dev --help` for the full flag list (agent adapter, tunnel provider, browser auto-open).
+Start the local UI registry + compile-on-demand dev hub, optionally supervising a local agent runtime. Run `ggui --help` for the flag list (agent adapter, tunnel provider, browser auto-open).
+
+#### Tunnel-provider plugins
+
+`ggui dev` exposes the local stack through a `TunnelProvider` seam. Real providers (cloudflared bindings, ngrok, hosted tunnels) plug in without changing the CLI:
+
+1. Set `GGUI_TUNNEL_PROVIDER=<module specifier>` (a package name or path resolvable from your project).
+2. The module exports a `createTunnelProvider()` factory (preferred) or a default export returning a `TunnelProvider`.
+3. Type the module against the published contract: `import type { TunnelProvider, TunnelProviderModule } from '@ggui-ai/cli/tunnel-provider'`.
+
+When the variable is unset, or the module fails shape validation, the CLI falls back to the null provider (`status: 'unavailable'` with a reason) instead of crashing the dev loop.
+
+### Everything else
+
+| Command             | What it does                                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `ggui login`        | Sign into ggui.ai (device flow); tokens stored in `~/.ggui/auth.json`.                                                         |
+| `ggui logout`       | Discard the local ggui.ai session.                                                                                             |
+| `ggui whoami`       | Print the authenticated user.                                                                                                  |
+| `ggui keys`         | Manage `ggui_user_*` connector keys (list / create / revoke).                                                                  |
+| `ggui create`       | Create cloud resources tied to this project (`create app` writes `appId` into `ggui.json`).                                    |
+| `ggui gadget`       | Author gadgets for the ggui marketplace (`gadget create <scope/name>` scaffolds a repo).                                       |
+| `ggui blueprint`    | Author UI blueprints for the ggui marketplace (`blueprint create <scope/name>` scaffolds a repo).                              |
+| `ggui theme`        | Validate + inspect operator-authored DTCG themes (`theme validate <path>`).                                                    |
+| `ggui export-pool`  | Export this deployment's reusable blueprints as a shareable pool directory; load elsewhere via `ggui serve --seed-pool <dir>`. |
+| `ggui push`         | Compile + bulk-push blueprints to a ggui.ai cloud app (requires `ggui login`).                                                 |
+| `ggui deploy`       | Provision + wire a ggui.ai cloud app for this project (idempotent).                                                            |
+| `ggui provider-key` | Manage provider API keys for a cloud ggui app (`provider-key set --app <appId>`).                                              |
+
+Run `ggui --help` for per-command flags.
 
 ## Configuration
 
@@ -67,7 +96,7 @@ Start the local UI registry + compile-on-demand dev hub, optionally supervising
 
 Set `protocol` to the value of `PROTOCOL_VERSION` exported by `@ggui-ai/protocol` in the version you install (or omit the field — the CLI will fall back to the installed protocol version).
 
-Optional blocks include `storage` (sessions / vectors / threads via `memory` or `sqlite`), `primitives`, `theme`, `adapters`, and `blueprints`. See [`@ggui-ai/project-config`](../project-config) for the full schema.
+Optional blocks include `storage` (renders / vectors / threads via `memory` or `sqlite`), `primitives`, `theme`, `blueprints`, `generation`, and `mcpMounts`. See [`@ggui-ai/project-config`](../project-config) for the full schema.
 
 ## MCP config for your agent runtime
 
@@ -78,12 +107,14 @@ Point any MCP-compatible agent at the local endpoint `ggui serve` exposes:
   "mcpServers": {
     "ggui": {
       "url": "http://127.0.0.1:6781/mcp",
-      "headers": { "Authorization": "Bearer dev" }
+      "headers": { "Authorization": "Bearer <paired-bearer>" }
     }
   }
 }
 ```
 
+Mint the bearer by pairing (landing page or `POST /pair`). Under `ggui serve --dev-allow-all`, any non-empty bearer (e.g. `dev`) authenticates.
+
 ## Links
 
 - [Repo](https://github.com/ggui-ai/ggui) — source, examples, issue tracker

package/dist/api-client.d.ts

@@ -1,3 +1,5 @@
+import type { PushRecord } from './push-command.js';
+import type { GadgetDescriptor, AppTheme } from '@ggui-ai/protocol';
 export interface DeviceCodeResponse {
     device_code: string;
     user_code: string;
@@ -48,12 +50,51 @@ export declare class ApiError extends Error {
 }
 export declare function postAuthDevice(endpoint: string, clientName: string): Promise<DeviceCodeResponse>;
 export declare function postAuthPoll(endpoint: string, deviceCode: string): Promise<TokenResponse>;
-export declare function postAuthRefresh(endpoint: string, refreshToken: string): Promise<TokenResponse>;
+export declare function postAuthRefresh(endpoint: string, refreshToken: string, fetchImpl?: typeof fetch): Promise<TokenResponse>;
 export declare function getMe(): Promise<MeResponse>;
 export declare function listKeys(): Promise<KeysListResponse>;
 export declare function createKey(args: {
     name?: string;
     expiresAt?: string;
 }): Promise<KeysCreateResponse>;
+export interface AppsCreateResponse {
+    appId: string;
+    /**
+     * The app's MCP endpoint, used VERBATIM as `GGUI_MCP_URL` — `<base>/apps/<appId>`,
+     * with NO `/mcp` suffix. The per-app cloud pod serves the MCP transport at this
+     * bare path; appending `/mcp` (a local `ggui serve` convention) 404s. Carries
+     * the deployment-correct host (prod `mcp.ggui.ai`, sandbox `<env>.mcp.sandbox…`),
+     * so prefer it over any reconstructed/hardcoded URL. See `resolveDeployMcpUrl`.
+     */
+    connectUrl: string;
+    isDefault: boolean;
+    createdAt: string;
+}
+export declare function createApp(args: {
+    displayName?: string;
+}): Promise<AppsCreateResponse>;
 export declare function revokeKey(id: string): Promise<void>;
+export interface PushResponse {
+    pushed: number;
+    appId: string;
+}
+export declare function pushAppBlueprints(appId: string, blueprints: PushRecord[]): Promise<PushResponse>;
+export interface SetProviderKeyResponse {
+    provider: string;
+    lastFour: string;
+    appId: string;
+}
+export declare function setAppProviderKey(appId: string, provider: string, plaintextKey: string, label?: string): Promise<SetProviderKeyResponse>;
+export interface PatchAppConfigResponse {
+    updated: string[];
+}
+export declare function patchAppConfig(appId: string, patch: {
+    gadgets?: GadgetDescriptor[];
+    publicEnv?: Record<string, string>;
+    generation?: {
+        model: string;
+        keySource: 'own' | 'managed';
+    };
+    theme?: AppTheme;
+}): Promise<PatchAppConfigResponse>;
 //# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,yBAAyB,EAAE,MAAM,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,QAAQ,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM1D;AAqBD,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAQ7B;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,aAAa,CAAC,CAQxB;AA0ED,wBAAsB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAKjD;AAED,wBAAsB,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAK1D;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAa9B;AAED,wBAAsB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASzD"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/api-client.js

@@ -59,8 +59,8 @@ export async function postAuthPoll(endpoint, deviceCode) {
         throw await parseError(res);
     return (await res.json());
 }
-export async function postAuthRefresh(endpoint, refreshToken) {
-    const res = await fetch(`${endpoint}/v1/auth/refresh`, {
+export async function postAuthRefresh(endpoint, refreshToken, fetchImpl = globalThis.fetch.bind(globalThis)) {
+    const res = await fetchImpl(`${endpoint}/v1/auth/refresh`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ refresh_token: refreshToken }),
@@ -137,9 +137,37 @@ export async function createKey(args) {
         },
     }), (r) => r.json());
 }
+export async function createApp(args) {
+    return withAuthRetry((s) => authedFetch(s, {
+        method: 'POST',
+        path: '/v1/apps',
+        body: { displayName: args.displayName },
+    }), (r) => r.json());
+}
 export async function revokeKey(id) {
     await withAuthRetry((s) => authedFetch(s, {
         method: 'DELETE',
         path: `/v1/keys/${encodeURIComponent(id)}`,
     }), async () => undefined);
 }
+export async function pushAppBlueprints(appId, blueprints) {
+    return withAuthRetry((s) => authedFetch(s, {
+        method: 'POST',
+        path: `/v1/apps/${encodeURIComponent(appId)}/blueprints`,
+        body: { blueprints },
+    }), (res) => res.json());
+}
+export async function setAppProviderKey(appId, provider, plaintextKey, label) {
+    return withAuthRetry((s) => authedFetch(s, {
+        method: 'POST',
+        path: `/v1/apps/${encodeURIComponent(appId)}/provider-keys`,
+        body: { provider, plaintextKey, ...(label ? { label } : {}) },
+    }), (r) => r.json());
+}
+export async function patchAppConfig(appId, patch) {
+    return withAuthRetry((s) => authedFetch(s, {
+        method: 'PATCH',
+        path: `/v1/apps/${encodeURIComponent(appId)}`,
+        body: patch,
+    }), (r) => r.json());
+}

package/dist/auth-keys.d.ts

@@ -1,4 +1,4 @@
-export declare const KEYS_HELP = "ggui keys \u2014 manage CLI keys\n\nUsage:\n  ggui keys list                          [--keys-file <path>]\n  ggui keys create  [--name <label>] [--expires-at <iso8601>] [--keys-file <path>]\n  ggui keys revoke  <id>                  [--keys-file <path>]\n  ggui keys register --scope <@scope>    [--registry <url>]\n\nlist      Print the caller's keys (id, prefix, name, status, dates).\ncreate    Mint a new connector key. The full secret is printed ONCE \u2014 copy it.\nrevoke    Soft-revoke a connector key by id (the row stays for audit).\nregister  Register a per-scope Ed25519 PUBLISHER key with the marketplace\n          registry so future `ggui gadget publish` / `ggui blueprint publish`\n          signed by the matching private key validate. The keypair is\n          auto-generated on first publish under\n          ~/.ggui/keys/<scope>/{private,public}.key \u2014 this verb ships\n          the public half to the registry's POST /author-keys.\n\nPass --keys-file <path> to operate on the LOCAL JSON file instead of\nthe cloud (api.ggui.ai). The file format is the one written by\n`ggui serve --keys-file` \u2014 the two commands share the same store, so\nyou can mint a bearer here and have `ggui serve` accept it on next\nboot. Use this for self-host / personal-mode workflows. --keys-file\napplies to list/create/revoke only; `register` always talks to the\nmarketplace registry.\n";
+export declare const KEYS_HELP = "ggui keys \u2014 manage CLI keys\n\nUsage:\n  ggui keys list                          [--keys-file <path>]\n  ggui keys create  [--name <label>] [--expires-at <iso8601>] [--keys-file <path>]\n  ggui keys revoke  <id>                  [--keys-file <path>]\n  ggui keys register --scope <@scope>    [--registry <url>] [--auth=bearer [--token <token>]]\n\nlist      Print the caller's keys (id, prefix, name, status, dates).\ncreate    Mint a new connector key. The full secret is printed ONCE \u2014 copy it.\nrevoke    Soft-revoke a connector key by id (the row stays for audit).\nregister  Register a per-scope Ed25519 PUBLISHER key with the marketplace\n          registry so future `ggui gadget publish` / `ggui blueprint publish`\n          signed by the matching private key validate. The keypair is\n          auto-generated on first publish under\n          ~/.ggui/keys/<scope>/{private,public}.key \u2014 this verb ships\n          the public half to the registry's POST /author-keys.\n\nregister-only Auth:\n  --auth=bearer        Use a bearer token (for self-hosted or local\n                       registries). Pair with --token <token> or set\n                       GGUI_REGISTRY_TOKEN in the environment.\n  --token <token>      Bearer token (paired with --auth=bearer).\n  (default)            Your `ggui login` session \u2014 the CLI reads\n                       ~/.ggui/auth.json and refreshes the token\n                       automatically when it has expired. Run\n                       `ggui login` first.\n\n\nPass --keys-file <path> to operate on the LOCAL JSON file instead of\nthe cloud (api.ggui.ai). The file format is the one written by\n`ggui serve --keys-file` \u2014 the two commands share the same store, so\nyou can mint a bearer here and have `ggui serve` accept it on next\nboot. Use this for self-host / personal-mode workflows. --keys-file\napplies to list/create/revoke only; `register` always talks to the\nmarketplace registry.\n";
 export declare function runKeysCommand(args: readonly string[]): Promise<number>;
 export interface RegisterFlags {
     readonly scope?: string;

package/dist/auth-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-keys.d.ts","sourceRoot":"","sources":["../src/auth-keys.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,SAAS,43CAyBrB,CAAC;AAEF,wBAAsB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB7E;AA6PD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CA2CzE"}
+{"version":3,"file":"auth-keys.d.ts","sourceRoot":"","sources":["../src/auth-keys.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,SAAS,w7DA2BrB,CAAC;AAEF,wBAAsB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB7E;AA6PD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CA2CzE"}

package/dist/auth-keys.js

@@ -13,6 +13,7 @@
 import process from 'node:process';
 import { ApiError, createKey, listKeys, revokeKey } from './api-client.js';
 import { formatLocalKeyTable, loadLocalKeys, mintLocalKey, revokeLocalKey, saveLocalKeys, } from './local-keys.js';
+import { AUTH_HELP_FRAGMENT, parseAuthFlags } from './internal/auth-strategy.js';
 import { runRegisterAuthorKey } from './internal/register-author-key.js';
 export const KEYS_HELP = `ggui keys — manage CLI keys
 
@@ -20,7 +21,7 @@ Usage:
   ggui keys list                          [--keys-file <path>]
   ggui keys create  [--name <label>] [--expires-at <iso8601>] [--keys-file <path>]
   ggui keys revoke  <id>                  [--keys-file <path>]
-  ggui keys register --scope <@scope>    [--registry <url>]
+  ggui keys register --scope <@scope>    [--registry <url>] [--auth=bearer [--token <token>]]
 
 list      Print the caller's keys (id, prefix, name, status, dates).
 create    Mint a new connector key. The full secret is printed ONCE — copy it.
@@ -32,6 +33,8 @@ register  Register a per-scope Ed25519 PUBLISHER key with the marketplace
           ~/.ggui/keys/<scope>/{private,public}.key — this verb ships
           the public half to the registry's POST /author-keys.
 
+register-only ${AUTH_HELP_FRAGMENT}
+
 Pass --keys-file <path> to operate on the LOCAL JSON file instead of
 the cloud (api.ggui.ai). The file format is the one written by
 \`ggui serve --keys-file\` — the two commands share the same store, so
@@ -329,7 +332,15 @@ export function parseRegisterFlags(args) {
     };
 }
 async function runKeysRegister(args) {
-    const flags = parseRegisterFlags(args);
+    // Peel the shared `--auth=bearer` / `--token` flags first (same
+    // router the publish verbs use), then parse the register-specific
+    // flags from the residue.
+    const authParsed = parseAuthFlags(args);
+    if ('error' in authParsed) {
+        process.stderr.write(`ggui keys register: ${authParsed.error}\n`);
+        return 2;
+    }
+    const flags = parseRegisterFlags(authParsed.rest);
     if (flags.help) {
         process.stdout.write(KEYS_HELP);
         return 0;
@@ -346,18 +357,22 @@ async function runKeysRegister(args) {
         process.stderr.write(`ggui keys register: --scope must start with \`@\` (got "${flags.scope}")\n`);
         return 2;
     }
+    const authFlags = authParsed.flags;
     const outcome = await runRegisterAuthorKey({
         scope: flags.scope,
         ...(flags.registry !== undefined ? { registry: flags.registry } : {}),
+        ...(authFlags.auth !== undefined || authFlags.token !== undefined
+            ? { auth: authFlags }
+            : {}),
     }, {
         cwd: process.cwd(),
         env: process.env,
         fetch,
-        // Unix-epoch SECONDS (matches the convention publish.ts uses for
-        // `expiresAt` in the registry-token cache — see auth-cache.ts:31).
-        // `Date.now()` returns milliseconds; passing it raw caused
-        // `isTokenFresh` to always return false against a real Cognito
-        // exp claim (also in seconds), forcing a re-auth on every run.
+        // Unix-epoch SECONDS — the login-session expiry fields
+        // (`accessExpiresAt` / `refreshExpiresAt` in auth-store.ts) are
+        // in seconds. `Date.now()` returns milliseconds; passing it raw
+        // would make every freshness check fail and force a refresh (or
+        // a spurious "session expired") on every run.
         now: () => Math.floor(Date.now() / 1000),
     });
     if (outcome.ok) {

package/dist/auth-store.d.ts

@@ -7,7 +7,7 @@ export interface AuthSessionDocument {
     readonly version: 1;
     /** API endpoint these tokens are bound to (origin only, no path). */
     readonly endpoint: string;
-    /** Cognito sub of the authenticated user. */
+    /** Server-side id of the authenticated user the tokens are bound to. */
     readonly userId: string;
     /** Stable session id grouping access + refresh on the server. */
     readonly sessionId: string;

package/dist/auth-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAoCA;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,WAAW,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAUlD;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,mBAAmB,GAAG,IAAI,CAiB/D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,CAQrD;AAmBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CA2B9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAKxD"}
+{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAoCA;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,WAAW,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAUlD;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,mBAAmB,GAAG,IAAI,CAiB/D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,CAQrD;AAmBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CA2B9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAKxD"}

package/dist/cli.js

@@ -12,18 +12,20 @@ import { fileURLToPath } from 'node:url';
 import { GguiDevError, LocalUiRegistry, runDev } from '@ggui-ai/dev-stack';
 import { discoverLocalUis, discoverMcpMounts, discoverPrimitives, GguiJsonLoadError, loadTheme, } from '@ggui-ai/project-config/node';
 import { resolveAgentPlan } from './serve-fallback.js';
-import { buildAgentRuntime, describeTunnelSession, launchBrowser, openTunnel, parseDevFlags, resolveAgentCommand, resolveHubUrl, shouldAutoOpen, } from './dev-command.js';
+import { buildAgentRuntime, describeTunnelSession, DEV_HELP, launchBrowser, openTunnel, parseDevFlags, resolveAgentCommand, resolveHubUrl, shouldAutoOpen, } from './dev-command.js';
 import { createNullTunnelProvider, discoverTunnelProvider, } from './tunnel-provider.js';
-import { ManifestBlueprintProvider, resolveStorageFromConfig, buildNoCredentialsRender, } from '@ggui-ai/mcp-server';
+import { ManifestBlueprintProvider, resolveStorageFromConfig, buildNoCredentialsGguiSession, } from '@ggui-ai/mcp-server';
 import { InMemoryBlueprintProvider } from '@ggui-ai/mcp-server-core/in-memory';
 import { createByokResolver } from './byok-resolver.js';
 import { isInstalledBlueprintPath } from './internal/artifact-install.js';
-import { DEFAULT_ROUTE_BY_PROVIDER, describeGenerationBinding, probeGenerationBinding, } from './generation-probe.js';
+import { DEFAULT_ROUTE_BY_PROVIDER, GENERATION_MODEL_ENV, describeGenerationBinding, probeGenerationBinding, resolveConfiguredRoute, } from './generation-probe.js';
 import { buildMcpServerBackend, pickFreePort } from './mcp-backend.js';
+import { FileSystemSeedPoolSource } from './filesystem-seed-pool-source.js';
+import { buildSeedPool } from '@ggui-ai/mcp-server-handlers';
 import { createThemeWriter } from './theme-writer.js';
 import { createThemeFileUploader } from './theme-file-uploader.js';
 import { getPersistentDir } from './paths.js';
-import { createPersistentRenderStore, createPersistentVectorStore, } from './persistent-stores.js';
+import { createPersistentGguiSessionStore, createPersistentVectorStore, } from './persistent-stores.js';
 import { parseServeFlags, runServe, SERVE_HELP, } from './serve-command.js';
 import { runLoginCommand } from './auth-login.js';
 import { runLogoutCommand } from './auth-logout.js';
@@ -32,6 +34,11 @@ import { runKeysCommand } from './auth-keys.js';
 import { runGadgetCommand } from './gadget-command.js';
 import { runBlueprintCommand } from './blueprint-command.js';
 import { runThemeCommand } from './theme-command.js';
+import { runExportPoolCommand } from './export-pool-command.js';
+import { runCreateCommand } from './create-app-command.js';
+import { runPushCommand } from './push-command.js';
+import { runDeployCommand } from './deploy-command.js';
+import { runProviderKeyCommand } from './provider-key-command.js';
 const HELP = `ggui — open CLI for the ggui protocol
 
 Usage:
@@ -71,6 +78,11 @@ Commands:
   logout       Discard the local ggui.ai session.
   whoami       Print the authenticated user.
   keys         Manage ggui_user_* connector keys (list/create/revoke).
+  create       Create cloud resources tied to this project.
+
+                 create app [--name <displayName>]  Create a new ggui.ai app
+                                                    and write appId into ggui.json.
+
   gadget       Author gadgets for the ggui marketplace.
 
                  gadget create <scope/name>  Scaffold a new gadget repo.
@@ -84,6 +96,29 @@ Commands:
                  theme validate <path>  Validate a JSON theme file against
                                         the ThemeDocumentV1 schema.
 
+  export-pool  Export this deployment's reusable blueprints as a shareable
+               pool directory (manifest.json + codes/). The pool can be
+               loaded by another deployment via \`ggui serve --seed-pool <dir>\`.
+
+                 --out <dir>  Output directory (default: ./ggui-pool).
+
+  deploy       Provision + wire a ggui.ai cloud app for this project
+               (idempotent: safe to re-run after a partial failure).
+               Requires a ggui.json in the current directory tree.
+
+                 --push-keys  Also push provider API key from env to the app.
+
+  provider-key Manage provider API keys for a cloud ggui app.
+
+                 provider-key set --app <appId> [--provider <name>]
+                   Push a provider API key from env to the cloud app.
+
+  push         Compile + bulk-push blueprints to a ggui.ai cloud app.
+               Requires \`ggui login\`.
+
+                 --app <appId>  Target app ID (default: ggui.json#appId).
+                 --from <dir>   Read from an existing pool artifact directory.
+
 Global options:
   --help, -h   Show this help.
   --version    Show installed version.
@@ -122,6 +157,16 @@ async function main(argv) {
             return runBlueprintCommand(rest);
         case 'theme':
             return runThemeCommand(rest);
+        case 'export-pool':
+            return runExportPoolCommand(rest);
+        case 'push':
+            return runPushCommand(rest);
+        case 'create':
+            return runCreateCommand(rest);
+        case 'deploy':
+            return runDeployCommand(rest);
+        case 'provider-key':
+            return runProviderKeyCommand(rest);
         default:
             process.stderr.write(`ggui: unknown command "${command}"\n\n`);
             process.stderr.write(HELP);
@@ -129,7 +174,7 @@ async function main(argv) {
     }
 }
 // `buildMcpServerBackend` moved to `./mcp-backend.ts` so tests can
-// exercise the full opt-in bundle ({sessionChannel, pairing,
+// exercise the full opt-in bundle ({renderChannel, pairing,
 // console.sessionCookie, shortCodeIndex}) without triggering
 // `main()` at import. See module-level doc there for the bundle
 // rationale.
@@ -211,7 +256,7 @@ async function runServeCommand(args) {
     // Resolve `ggui.json#storage` → concrete adapters BEFORE binding.
     // Absent storage block → empty bundle → server keeps in-memory
     // defaults. Sqlite paths resolve relative to the manifest directory
-    // (not CWD) so `"path": "./ggui-renders.sqlite"` lands next to
+    // (not CWD) so `"path": "./ggui-sessions.sqlite"` lands next to
     // `ggui.json` regardless of where the operator invoked `ggui serve`
     // from. Failure to instantiate (e.g. better-sqlite3 peer dep
     // missing, permission denied) propagates to the exit-1 path below.
@@ -223,7 +268,7 @@ async function runServeCommand(args) {
         process.stderr.write(`ggui serve: storage: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }
-    // Persistent default for RenderStore + VectorStore — layered AFTER
+    // Persistent default for GguiSessionStore + VectorStore — layered AFTER
     // the manifest resolver so explicit `ggui.json#storage` declarations
     // always win, and BEFORE the banner so `describeStorageStatus`
     // reflects the actual wired state. Without this layer, ggui-default
@@ -235,10 +280,10 @@ async function runServeCommand(args) {
         // `--ephemeral` skips the whole persistent layering. Operators who
         // pass the flag get pure in-memory defaults across the board (HMAC
         // secrets mint fresh per process). Without the flag, the
-        // sqlite-backed VectorStore + RenderStore persist across restarts
+        // sqlite-backed VectorStore + GguiSessionStore persist across restarts
         // — note this means the install-to-cache bridge can serve stale
-        // install-provenance rows after a boot if the source TSX behind a
-        // cached row has been edited or uninstalled in the meantime.
+        // installed rows after a boot if the source TSX behind a cached
+        // row has been edited or uninstalled in the meantime.
         if (!parsed.ephemeral) {
             const persistentDir = getPersistentDir(plan.projectRoot);
             const manifestDeclaresRenders = plan.manifest?.storage?.renders !== undefined;
@@ -253,7 +298,7 @@ async function runServeCommand(args) {
             // resolved above) — the operator asked for it by name.
             if (!manifestDeclaresRenders && storage.renderStore === undefined) {
                 try {
-                    const renderStore = await createPersistentRenderStore(persistentDir);
+                    const renderStore = await createPersistentGguiSessionStore(persistentDir);
                     storage = { ...storage, renderStore };
                 }
                 catch (err) {
@@ -376,16 +421,16 @@ async function runServeCommand(args) {
     }
     // Live-theme state cell. Shared between the console-theme route's
     // POST handler (mountDevtoolThemeRoutes' `onConfigChange` callback)
-    // and the push handler's `themeProvider` getter so a "Save to
-    // ggui.json" in the picker reaches the next push's bootstrap
-    // envelope without a server restart. Without the cell the push
+    // and the render handler's `themeProvider` getter so a "Save to
+    // ggui.json" in the picker reaches the next render's bootstrap
+    // envelope without a server restart. Without the cell the render
     // handler would capture `themeId` once at boot, and any subsequent
     // edit would be silently ignored until restart.
     //
     // Initial value derives from the boot-time LoadedTheme so the
-    // first push (before any save happens) embeds the manifest's
+    // first render (before any save happens) embeds the manifest's
     // declared theme. POST writes mutate `themeStateCell.current`;
-    // the closure below reads it on every push.
+    // the closure below reads it on every render.
     const themeStateCell = {
         current: theme !== undefined && theme.source === 'preset'
             ? { id: theme.preset, mode: theme.mode }
@@ -458,15 +503,33 @@ async function runServeCommand(args) {
     const settingsUrl = `${baseUrlForCard}/settings`;
     // No-credentials cards live for an hour from mint — long enough for
     // the operator to follow the Connect-Claude link, paste a key, and
-    // re-prompt before the persisted render is GC'd.
+    // re-prompt before the persisted GguiSession is GC'd.
     const NO_CREDENTIALS_CARD_TTL_MS = 60 * 60 * 1000;
-    // Resolve the operator's explicit `generation.model` route, if any.
-    // The schema-side `parseAnyLlmRoute` transform yields a typed
-    // `LlmRoute` directly — no string parsing here. Bedrock is
-    // hosted-only on the OSS path (no IAM resolver chain wired); reject
-    // explicitly with a clear error rather than silently failing at
-    // dispatch time.
-    const configuredRoute = plan.manifest?.generation?.model;
+    // Resolve the operator's explicit generation route, applying the
+    // precedence rule `GGUI_GENERATION_MODEL` env > `ggui.json#
+    // generation.model`. The env override is the ops escape hatch: it
+    // repoints a `ggui serve` instance at a different model without
+    // editing the manifest (and lets the e2e provider matrix boot the
+    // SAME sample under different providers). The manifest leg is
+    // already a typed `LlmRoute` from the schema transform; the env leg
+    // is parsed via `parseAnyLlmRoute` inside `resolveConfiguredRoute`.
+    const routeResolution = resolveConfiguredRoute({
+        envModel: process.env[GENERATION_MODEL_ENV],
+        manifestRoute: plan.manifest?.generation?.model,
+    });
+    if (routeResolution.kind === 'invalid-env') {
+        process.stderr.write(`ggui serve: ${GENERATION_MODEL_ENV}="${routeResolution.raw}" is not a ` +
+            `valid model route. Accepted forms:\n` +
+            `  - canonical: "openai:gpt-5.4-mini"\n` +
+            `  - LiteLLM:   "gemini/gemini-3.1-flash-lite"\n` +
+            `See docs/principles/model-string-convention.md.\n`);
+        return 1;
+    }
+    const configuredRoute = routeResolution.kind === 'route' ? routeResolution.route : undefined;
+    // Bedrock is hosted-only on the OSS path (no IAM resolver chain
+    // wired); reject explicitly with a clear error rather than silently
+    // failing at dispatch time. Covers both env + manifest sources since
+    // the check runs on the resolved route.
     if (configuredRoute?.provider === 'bedrock') {
         process.stderr.write(`ggui serve: ggui.json#generation.model declared a bedrock route ` +
             `("${configuredRoute.model}"), but the OSS BYOK resolver chain ` +
@@ -486,8 +549,8 @@ async function runServeCommand(args) {
             ...(configuredRoute ? { configuredRoute } : {}),
             onNoCredentials: (ctx, story) => {
                 const nowEpochMs = Date.parse(story.nowIso);
-                return buildNoCredentialsRender({
-                    renderId: story.renderId,
+                return buildNoCredentialsGguiSession({
+                    sessionId: story.sessionId,
                     appId: ctx.appId,
                     intent: story.intent,
                     nowEpochMs,
@@ -538,6 +601,20 @@ async function runServeCommand(args) {
         return 1;
     }
     process.stdout.write(`${describeGenerationBinding(generationBinding)}\n`);
+    // Build seed pools from --seed-pool flags BEFORE composing the backend
+    // factory. `buildSeedPool` is async (reads + indexes the directory
+    // artifact) so it must run here in the async outer scope rather than
+    // inside the synchronous `backendFactory` closure below.
+    const seedPools = [];
+    for (const dir of parsed.seedPools) {
+        try {
+            seedPools.push(await buildSeedPool(new FileSystemSeedPoolSource(dir), { scope: 'shared' }));
+        }
+        catch (err) {
+            process.stderr.write(`ggui serve: --seed-pool "${dir}": ${err instanceof Error ? err.message : String(err)}\n`);
+            return 1;
+        }
+    }
     try {
         return await runServe({
             flags: {
@@ -590,9 +667,9 @@ async function runServeCommand(args) {
                         themeWriter: createThemeWriter(join(plan.projectRoot, 'ggui.json')),
                         themeFileUploader: createThemeFileUploader(join(plan.projectRoot, 'ggui.json')),
                         // Live-theme: closure reads `themeStateCell` on every
-                        // push. `onThemeConfigChange` mutates the cell from
+                        // render. `onThemeConfigChange` mutates the cell from
                         // the console-theme route's POST handler. Together:
-                        // console save → cell update → next push's bootstrap
+                        // console save → cell update → next render's bootstrap
                         // carries the new themeId. No restart required.
                         themeProvider,
                         onThemeConfigChange: (next) => {
@@ -605,7 +682,7 @@ async function runServeCommand(args) {
                             //  - { preset, mode?, overrides? }: explicit preset.
                             //  - { file, mode? }: custom DTCG document.
                             // For preset shapes, propagate id+mode to the live
-                            // cell so the next push's bootstrap envelope picks
+                            // cell so the next render's bootstrap envelope picks
                             // them up. For the file branch the bootstrap's
                             // `themeId` field has no useful value (the runtime
                             // bundles only registered presets), so we clear
@@ -657,7 +734,7 @@ async function runServeCommand(args) {
                     : {}),
                 // Pass through `app.publicEnv`. The server projects only keys
                 // that some registered wrapper's `requires` lists onto
-                // `App.publicEnv` for the push-gate validator + the iframe
+                // `App.publicEnv` for the render-gate validator + the iframe
                 // runtime's `getPublicEnv()`.
                 ...(plan.manifest?.app?.publicEnv &&
                     Object.keys(plan.manifest.app.publicEnv).length > 0
@@ -668,6 +745,7 @@ async function runServeCommand(args) {
                     : {}),
                 generation: generationBinding.generation,
                 ...(mcpMounts.length > 0 ? { mcpMounts } : {}),
+                ...(seedPools.length > 0 ? { seedPools } : {}),
                 // Marketplace-install bridge. Pass the projectRoot +
                 // filtered installed-blueprint subset so `buildMcpServerBackend`
                 // can construct an `InstalledBlueprintsProvider` rooted on the
@@ -899,6 +977,10 @@ function narrowMcpMounts(discovered) {
 }
 async function runDevCommand(args) {
     const parsed = parseDevFlags(args);
+    if (parsed.error === '__help__') {
+        process.stdout.write(DEV_HELP);
+        return 0;
+    }
     if (parsed.error) {
         process.stderr.write(`ggui dev: ${parsed.error}\n`);
         return 1;