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

package/dist/mcp-backend.js

@@ -10,8 +10,8 @@
  * What gets wired by default — see OSS-split §2 (the five server
  * responsibilities):
  *
- *   - `sessionChannel: true` — live-channel `/ws` endpoint. Required for
- *     MCP Apps iframes AND the console session viewer.
+ *   - `renderChannel: true` — live-channel `/ws` endpoint. Required for
+ *     MCP Apps iframes AND the console render viewer.
  *   - `pairing: true` — `POST /pair` + `POST /admin/pair/init` so
  *     remote clients (Portal, third-party) can pair with this server.
  *     The default `InMemoryAuthAdapter` registers pairing tokens
@@ -19,8 +19,8 @@
  *   - `console: { sessionCookie: true }` — landing page at `/` +
  *     `/s/<shortCode>` viewer + same-origin HTTP-only cookie flow.
  *   - `shortCodeIndex: new InMemoryShortCodeIndex()` — required by
- *     the `sessionCookie` flow so `POST /ggui/console/render-cookie`
- *     can resolve a posted shortCode to the bound `{renderId, appId}`.
+ *     the `sessionCookie` flow so `POST /ggui/console/session-cookie`
+ *     can resolve a posted shortCode to the bound `{sessionId, appId}`.
  *     In-memory is correct for the OSS first-run: render state lives
  *     in memory unless the operator opts into sqlite, so a matching
  *     index lifetime is what operators expect.
@@ -40,12 +40,11 @@ import { listThemes } from "@ggui-ai/design/themes";
 import { compileUiOnDemand } from "@ggui-ai/dev-stack";
 import { createLocalEmbeddingProvider } from "@ggui-ai/embedding-local";
 import { RUNTIME_BUNDLE_URL_PATH } from "@ggui-ai/iframe-runtime/server";
-import { composeWiredActionRouterFromMounts, createGguiServer, DEFAULT_BUILDER_APP_ID, FileSystemCodeStore, FixedWindowRateLimiter, InMemoryAuthAdapter, InMemoryQuotaStore, InMemoryShortCodeIndex, selectEmailSenderFromEnv, } from "@ggui-ai/mcp-server";
-import { InMemoryAppMetadataStore, InMemoryVectorStore } from "@ggui-ai/mcp-server-core/in-memory";
+import { createGguiServer, FileSystemCodeStore, FixedWindowRateLimiter, InMemoryAuthAdapter, InMemoryQuotaStore, InMemoryShortCodeIndex, selectEmailSenderFromEnv, } from "@ggui-ai/mcp-server";
+import { InMemoryAppMetadataStore, InMemoryBlueprintIndex, InMemoryVectorStore, } from "@ggui-ai/mcp-server-core/in-memory";
 import { PlaintextFileProviderKeyStore } from "@ggui-ai/mcp-server-core/plaintext";
-import { createInstalledBlueprintsProvider, } from "@ggui-ai/mcp-server-handlers/renders";
+import { createInstalledBlueprintsProvider, createStderrCacheTraceSink, setCacheTraceSink, } from "@ggui-ai/mcp-server-handlers/renders";
 import { createDeterministicPreviewEmitter } from "@ggui-ai/preview-a2ui/emitters";
-import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createServer as createNetServer } from "node:net";
 import { join } from "node:path";
@@ -104,13 +103,6 @@ export function buildMcpServerBackend(opts) {
     // derive the live-channel URL.
     const baseUrl = opts.publicBaseUrl ?? `http://${opts.host}:${opts.port}`;
     const wsBaseUrl = baseUrl.replace(/^http(s?):\/\//, "ws$1://");
-    // Router over the mount handler bundle. Computed once; absent
-    // (`null`) when no mounts are declared so the server falls through
-    // to agent-routed behavior.
-    const wiredActionRouter = composeWiredActionRouterFromMounts(opts.mcpMounts, () => ({
-        appId: DEFAULT_BUILDER_APP_ID,
-        requestId: randomUUID(),
-    }));
     // Strict-auth OSS default (`devAllowAll: false`). `createGguiServer`
     // would otherwise fall back to `InMemoryAuthAdapter({ devAllowAll:
     // true })`, which authenticates any non-empty bearer as builder — a
@@ -161,8 +153,23 @@ export function buildMcpServerBackend(opts) {
     // get `MockEmbeddingProvider` if they don't bind an embedder — that
     // keeps the 60MB `@huggingface/transformers` install surface off
     // the unit-test path.
+    const embeddingCacheDir = getEmbeddingCacheDir();
     const embedding = createLocalEmbeddingProvider({
-        cacheDir: getEmbeddingCacheDir(),
+        cacheDir: embeddingCacheDir,
+    });
+    // One-line boot log of which embedding provider is live, so a captured
+    // serve log makes real-model-vs-mock unambiguous. The local provider
+    // loads `bge-small-en-v1.5` lazily; we then fire a best-effort warmup
+    // probe (one `embed`) so the model is downloaded/loaded before the
+    // first real lookup AND a load failure (e.g. missing
+    // `@huggingface/transformers` peer dep) is surfaced as a clear
+    // fallback warning rather than a silent first-lookup degradation.
+    // eslint-disable-next-line no-console -- one-shot boot signal, mirrors banner output
+    console.warn(`[ggui:embedding] local ${embedding.id} (cache: ${embeddingCacheDir})`);
+    embedding.embed("warmup").catch((err) => {
+        const reason = err instanceof Error ? err.message : String(err);
+        // eslint-disable-next-line no-console -- one-shot boot signal; local model unavailable
+        console.warn(`[ggui:embedding] MockEmbeddingProvider fallback — local model unavailable: ${reason}`);
     });
     // BYOK provider-key store — same `~/.ggui/credentials.json` that
     // `byok-resolver.ts` reads on every `resolve()`. Threading the store
@@ -240,7 +247,7 @@ export function buildMcpServerBackend(opts) {
     // themes don't have a registry id to surface here — agents pick from
     // `listThemes()` either way; the file-mode override only affects the
     // server's bound `theme` (rendered CSS variables), not the
-    // session/handler-side `themeId` chain.
+    // render/handler-side `themeId` chain.
     const manifestThemePreset = opts.theme?.source === "preset" ? opts.theme.preset : undefined;
     const appMetadataStore = new InMemoryAppMetadataStore({
         ...(manifestThemePreset !== undefined ? { defaultThemeId: manifestThemePreset } : {}),
@@ -253,13 +260,13 @@ export function buildMcpServerBackend(opts) {
             ? { defaultGadgets: opts.gadgets }
             : {}),
         // `ggui.json#app.publicEnv` operator-stamped values for wrapper
-        // hooks to read via `getPublicEnv()`. The push gate
+        // hooks to read via `getPublicEnv()`. The render gate
         // (`assertPublicEnvSatisfied`) verifies every declared wrapper's
         // `requires` keys are present in this map BEFORE the iframe boots.
         ...(opts.publicEnv !== undefined && Object.keys(opts.publicEnv).length > 0
             ? { defaultPublicEnv: opts.publicEnv }
             : {}),
-        // `ggui.json#app.defaultDisplayMode`. Stamped per-push as
+        // `ggui.json#app.defaultDisplayMode`. Stamped per-render as
         // `_meta.ui.displayMode`; controls only host-side presentation.
         ...(opts.defaultDisplayMode !== undefined
             ? { defaultDisplayMode: opts.defaultDisplayMode }
@@ -274,6 +281,14 @@ export function buildMcpServerBackend(opts) {
     // here on the absent-storage path; threaded back as `vectors` to
     // `createGguiServer` so server + provider share state.
     const vectorStore = storage.vectors ?? new InMemoryVectorStore();
+    // Blueprint identity index — minted here so the install bridge's
+    // provider deps and the server share ONE instance (the server's
+    // ref-equality guard enforces this, same as `vectorStore`). The index
+    // is rebuildable from vector-store metadata and self-heals at the read
+    // site, so an in-memory index is safe even alongside a persistent
+    // `storage.vectors`; a persistent index can be threaded later via the
+    // same seam.
+    const blueprintIndex = new InMemoryBlueprintIndex();
     // Construct the marketplace-install bridge BEFORE `createGguiServer`
     // so we can fold it into `opts.generation.installedBlueprints` below.
     // Per design lock (project_slices_5_6_7_plan.md), the provider
@@ -319,14 +334,14 @@ export function buildMcpServerBackend(opts) {
                     errors: result.errors.map((m) => m.text),
                 };
             },
-            deps: { embedding, vectorStore },
+            deps: { embedding, vectorStore, index: blueprintIndex },
             onIssue: (issue) => {
                 process.stderr.write(`[ggui serve] installed-blueprint ${issue.id}: ${issue.kind}: ${issue.message}\n`);
             },
         };
         installedBlueprintsProvider = createInstalledBlueprintsProvider(providerOptions);
     }
-    // Fold the bridge into the generation deps so the push handler +
+    // Fold the bridge into the generation deps so the render handler +
     // handshake negotiator both consume it via `MatchBlueprintDeps.
     // installedBlueprints`. Two-step pattern keeps the createGguiServer
     // call below unchanged when no provider is wired.
@@ -338,6 +353,17 @@ export function buildMcpServerBackend(opts) {
             }
             : opts.generation
         : undefined;
+    // Env-gated blueprint-cache trace sink. When `GGUI_CACHE_TRACE_STDERR`
+    // is truthy, every `matchBlueprint` decision (and the reason it landed
+    // there) is written as a single JSON line to stderr prefixed
+    // `[ggui:cache-trace] ` — a diagnostic for seeing WHY a semantic match
+    // missed (RAG retrieved nothing / cosine below floor / judge declined)
+    // in a captured server log. Registered BEFORE `createGguiServer` so the
+    // first lookup already routes through it. Absent env = no sink (the
+    // matcher emits nothing and spends no CPU on the top-K probe).
+    if (process.env["GGUI_CACHE_TRACE_STDERR"]) {
+        setCacheTraceSink(createStderrCacheTraceSink());
+    }
     const server = createGguiServer({
         auth,
         embedding,
@@ -355,7 +381,7 @@ export function buildMcpServerBackend(opts) {
         // Cross-restart HMAC secrets. Present iff the caller declared a
         // persistent dir. Both threaded so the next restart can verify
         // tokens minted by the previous run instead of regenerating per
-        // process. Render-signer.secret rides on the `renderSigning`
+        // process. render-signer.secret rides on the `renderSigning`
         // discriminated union (the `false` shape disables the layer
         // entirely; we always want it on here, so build the object form).
         ...(persistedWsTokenSecret !== undefined ? { wsTokenSecret: persistedWsTokenSecret } : {}),
@@ -381,6 +407,10 @@ export function buildMcpServerBackend(opts) {
         // declaration, leave the server to mint its own internal
         // InMemoryVectorStore that the bridge couldn't see.
         vectors: vectorStore,
+        // Share the one minted index instance with the server so the install
+        // bridge + matcher resolve identity through the SAME index (the
+        // server's ref-equality guard enforces this).
+        index: blueprintIndex,
         // `threads:` is an opt-in on createGguiServer (no zero-config
         // fallback — threads without an explicit store wouldn't mount
         // routes at all). We only pass it when the manifest declares a
@@ -397,7 +427,7 @@ export function buildMcpServerBackend(opts) {
                 },
             }
             : {}),
-        sessionChannel: true,
+        renderChannel: true,
         pairing: opts.keysFile ? { persistencePath: opts.keysFile } : true,
         // Email magic-link login. OSS first-run default mirrors
         // `provisionalPreview` — wire a sender so magic links can be
@@ -472,7 +502,7 @@ export function buildMcpServerBackend(opts) {
         // `GGUI_CODE_CACHE_DIR`). Survives `ggui serve` restart so
         // claude.ai's iframe cache still resolves URLs minted before the
         // restart. Operators can `rm -rf` the cache at any time —
-        // immutable URLs guarantee a fresh push repopulates as needed.
+        // immutable URLs guarantee a fresh render repopulates as needed.
         codeStore: new FileSystemCodeStore({ root: getCodeCacheDir() }),
         // Manifest-declared blueprints. Only present when `ggui serve`
         // found UIs in `blueprints.include`; absent = the server's
@@ -499,7 +529,7 @@ export function buildMcpServerBackend(opts) {
         ...(opts.themeWriter ? { themeWriter: opts.themeWriter } : {}),
         // Live-theme wiring — `themeProvider` reads from a shared cell
         // that `onThemeConfigChange` writes to on every console save,
-        // so the picker's "Save to ggui.json" reaches the next push's
+        // so the picker's "Save to ggui.json" reaches the next render's
         // bootstrap envelope without a restart. Both threaded through
         // when present; absent = boot-baked behaviour (legacy).
         ...(opts.themeProvider ? { themeProvider: opts.themeProvider } : {}),
@@ -508,8 +538,8 @@ export function buildMcpServerBackend(opts) {
         // is the live-channel URL published on `_meta["ai.ggui/render"]`
         // so iframes opened by an MCP Apps host (Claude Desktop, Claude
         // Code, claude.ai) can subscribe back to this same process.
-        // First-party hosts (Studio, Portal, console) consume
-        // `_meta.ui.resourceUri` instead and never hit the URL directly.
+        // First-party hosted UIs consume `_meta.ui.resourceUri`
+        // instead and never hit the URL directly.
         mcpApps: {
             wsUrl: `${wsBaseUrl}/ws`,
         },
@@ -543,31 +573,27 @@ export function buildMcpServerBackend(opts) {
         },
         // Generation wiring. Threaded through to
         // `defaultHandlers.render.generation` → `createGguiRenderHandler`.
-        // Absent = placeholder mode: render mints renderIds + shortCodes
+        // Absent = placeholder mode: render mints sessionIds + shortCodes
         // + preview but does NOT produce componentCode. The CLI's
         // `runServeCommand` probes BYOK (env → credentials file) at
         // boot and only supplies this opt on a hit. See
         // `./generation-probe.ts`.
         ...(generationWithInstalled ? { generation: generationWithInstalled } : {}),
+        // Seed pools from `--seed-pool` artifacts. Threaded into the
+        // handshake negotiator so cross-deployment blueprints are
+        // accessible without being in the local cache.
+        ...(opts.seedPools && opts.seedPools.length > 0 ? { seedPools: opts.seedPools } : {}),
         // Mount aggregation. External SharedHandler bundles appended onto
         // `/mcp` alongside ggui-native tools. No CLI config loader yet —
         // programmatic hosts + integration tests compose mounts through
         // this opt directly.
         ...(opts.mcpMounts && opts.mcpMounts.length > 0 ? { mcpMounts: opts.mcpMounts } : {}),
-        // wiredActionRouter composed from the same mount handlers. With
-        // mounts present, every mounted tool becomes wire-dispatchable
-        // from a generated UI's `actionSpec[name].dispatch.tool` (when
-        // `dispatch.kind === 'tool'`) — the "zero agent code" path.
-        // Without mounts, no router is wired and inbound actions stay on
-        // the agent-routed path.
-        ...(wiredActionRouter ? { wiredActionRouter } : {}),
         // Schema-compat mode. Defaults to `'reject'` inside
         // `createGguiServer`; the env override is the operator's escape
         // hatch for scenarios that intentionally ship a blueprint with a
-        // schema mismatch (e.g. contract-probe fixtures that test runtime
-        // TOOL_THREW / SCHEMA_VIOLATION error paths — `'reject'` would
-        // otherwise block the stack item at push/try-live time before
-        // runtime gets to emit the envelope under test).
+        // schema mismatch (e.g. contract-probe fixtures that exercise
+        // mismatch handling downstream — `'reject'` would otherwise block
+        // the render at render/try-live time before the scenario starts).
         //
         // Accepted values match `SchemaCompatMode`: `'reject' | 'warn' |
         // 'off'`. Unrecognized values fall through to the server's
@@ -580,28 +606,6 @@ export function buildMcpServerBackend(opts) {
                 schemaCompatCheck: process.env["GGUI_SCHEMA_COMPAT_MODE"],
             }
             : {}),
-        // Wired-tool per-call timeout override (default 30 s in
-        // `session-channel.ts::DEFAULT_WIRED_TOOL_TIMEOUT_MS`). Mirrors the
-        // `GGUI_SCHEMA_COMPAT_MODE` escape-hatch shape: env-only; absent or
-        // unparseable falls through to the server's default. Test harnesses
-        // exercising TOOL_TIMEOUT envelopes lower this to keep per-test
-        // budgets small (the conformance fixture
-        // `wired-action-tool-timeout.json` deliberately wires a hanging
-        // tool; the default 30 s wait would dominate a Lane-1 spec budget).
-        //
-        // Parse uses `Number()` + finite + positive-integer checks; a typo
-        // (`"abc"`, `"-100"`, `"NaN"`) falls through silently to default.
-        // Operators that need a different production timeout SHOULD compose
-        // `createGguiServer` directly rather than rely on env coupling.
-        ...(() => {
-            const raw = process.env["GGUI_WIRED_TIMEOUT_MS"];
-            if (raw === undefined || raw === "")
-                return {};
-            const parsed = Number(raw);
-            if (!Number.isFinite(parsed) || parsed <= 0)
-                return {};
-            return { wiredActionTimeoutMs: Math.floor(parsed) };
-        })(),
     });
     return {
         listen: async (port, host) => {

package/dist/paths.d.ts

@@ -51,7 +51,7 @@ export declare function getEmbeddingCacheDir(): string;
  * safe to return even when nothing has been written yet. Operators
  * who want to reset the cache can `rm -rf` this directory at any
  * time — every entry is content-addressable + immutable, so a
- * re-fetch repopulates from upstream code on next push.
+ * re-fetch repopulates from upstream code on next render.
  */
 export declare function getCodeCacheDir(): string;
 /**
@@ -59,14 +59,14 @@ export declare function getCodeCacheDir(): string;
  * short-codes.sqlite, bootstrap-secret.hex, render-signer-secret.hex,
  * keys.json …). Survives `ggui serve` restarts so claude.ai chat-history
  * revisits can rehydrate the iframe instead of seeing four cascading
- * failures (HMAC + shortCode + session + pairing).
+ * failures (HMAC + shortCode + render + pairing).
  *
  * Resolution order:
  *   1. `GGUI_PERSISTENT_DIR` env — operator override (tests, clean-room,
  *      shared mount).
  *   2. `<projectRoot>/.ggui/persistent` — when the CLI resolved a
  *      ggui.json. Per-project isolation; different projects get
- *      separate sessions even on the same machine.
+ *      separate renders even on the same machine.
  *   3. `~/.ggui/persistent` — fallback when there's no manifest
  *      (`ggui serve` from a bare directory).
  *

package/dist/paths.js

@@ -81,7 +81,7 @@ export function getEmbeddingCacheDir() {
  * safe to return even when nothing has been written yet. Operators
  * who want to reset the cache can `rm -rf` this directory at any
  * time — every entry is content-addressable + immutable, so a
- * re-fetch repopulates from upstream code on next push.
+ * re-fetch repopulates from upstream code on next render.
  */
 export function getCodeCacheDir() {
     const override = process.env['GGUI_CODE_CACHE_DIR'];
@@ -94,14 +94,14 @@ export function getCodeCacheDir() {
  * short-codes.sqlite, bootstrap-secret.hex, render-signer-secret.hex,
  * keys.json …). Survives `ggui serve` restarts so claude.ai chat-history
  * revisits can rehydrate the iframe instead of seeing four cascading
- * failures (HMAC + shortCode + session + pairing).
+ * failures (HMAC + shortCode + render + pairing).
  *
  * Resolution order:
  *   1. `GGUI_PERSISTENT_DIR` env — operator override (tests, clean-room,
  *      shared mount).
  *   2. `<projectRoot>/.ggui/persistent` — when the CLI resolved a
  *      ggui.json. Per-project isolation; different projects get
- *      separate sessions even on the same machine.
+ *      separate renders even on the same machine.
  *   3. `~/.ggui/persistent` — fallback when there's no manifest
  *      (`ggui serve` from a bare directory).
  *

package/dist/persistent-secrets.js

@@ -20,7 +20,7 @@
  * Security posture: these secrets are a render-token signing key, NOT
  * a long-lived credential like an OAuth client secret. Losing them
  * means an attacker can mint MCP Apps bootstrap tokens for arbitrary
- * `(renderId, appId)` pairs — same blast radius as before, just
+ * `(sessionId, appId)` pairs — same blast radius as before, just
  * surviving restart. Mode 0600 on the file matches `~/.ggui/credentials
  * .json` (BYOK keys) which has the same threat model.
  *

package/dist/persistent-stores.d.ts

@@ -1,5 +1,5 @@
-import type { RenderStore, VectorStore } from '@ggui-ai/mcp-server-core';
-export declare function createPersistentRenderStore(persistentDir: string): Promise<RenderStore>;
+import type { GguiSessionStore, VectorStore } from '@ggui-ai/mcp-server-core';
+export declare function createPersistentGguiSessionStore(persistentDir: string): Promise<GguiSessionStore>;
 export declare function createPersistentVectorStore(persistentDir: string): Promise<VectorStore>;
 /**
  * Compute the auto-default `keysFile` path. Returns `undefined` when

package/dist/persistent-stores.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistent-stores.d.ts","sourceRoot":"","sources":["../src/persistent-stores.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,wBAAsB,2BAA2B,CAC/C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED,wBAAsB,2BAA2B,CAC/C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7D"}
+{"version":3,"file":"persistent-stores.d.ts","sourceRoot":"","sources":["../src/persistent-stores.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAElC,wBAAsB,gCAAgC,CACpD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAQ3B;AAED,wBAAsB,2BAA2B,CAC/C,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7D"}

package/dist/persistent-stores.js

@@ -1,7 +1,7 @@
 /**
  * Default-on persistent stores under `<persistentDir>/`. Used when the
  * operator hasn't declared `storage.renders` / `storage.vectors` in
- * `ggui.json` AND hasn't passed `--ephemeral`. Closes the RenderStore
+ * `ggui.json` AND hasn't passed `--ephemeral`. Closes the GguiSessionStore
  * leg of the rehydrate problem: without this, a restart drops every
  * render row even though the HMAC secret + ShortCodeIndex now persist.
  *
@@ -16,11 +16,11 @@
  */
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-export async function createPersistentRenderStore(persistentDir) {
+export async function createPersistentGguiSessionStore(persistentDir) {
     mkdirSync(persistentDir, { recursive: true });
-    const { SqliteRenderStore } = await import('@ggui-ai/mcp-server-core/sqlite');
-    return new SqliteRenderStore({
-        filename: join(persistentDir, 'renders.sqlite'),
+    const { SqliteGguiSessionStore } = await import('@ggui-ai/mcp-server-core/sqlite');
+    return new SqliteGguiSessionStore({
+        filename: join(persistentDir, 'sessions.sqlite'),
     });
 }
 export async function createPersistentVectorStore(persistentDir) {

package/dist/pool-artifact.d.ts

@@ -0,0 +1,19 @@
+import type { PortableBlueprint } from '@ggui-ai/protocol';
+/** Write records to a directory: manifest.json + codes/<hash>.tsx. */
+export declare function writePoolArtifact(dir: string, records: readonly PortableBlueprint[]): Promise<void>;
+export interface ReadPoolResult {
+    /**
+     * Raw, UNVALIDATED records (manifest entry + reassembled
+     * componentCode). The artifact bytes are an untrusted input; the
+     * trust boundary is `fromPortableBlueprint` at the loader
+     * (`buildSeedPool`), which validates each record and skips
+     * rejections with a log line. This reader only owns the directory
+     * IO; the layout/format is the shared codec's.
+     */
+    readonly records: readonly unknown[];
+    /** Per-record problems (malformed entry, bad ref, missing/unreadable code body); never throws on these. */
+    readonly issues: readonly string[];
+}
+/** Read + reassemble records. Throws on a missing/invalid manifest or unsupported schemaVersion (v1 included — re-export, no migration shim). */
+export declare function readPoolArtifact(dir: string): Promise<ReadPoolResult>;
+//# sourceMappingURL=pool-artifact.d.ts.map

package/dist/pool-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-artifact.d.ts","sourceRoot":"","sources":["../src/pool-artifact.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAK3D,sEAAsE;AACtE,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACpC,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,2GAA2G;IAC3G,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,iJAAiJ;AACjJ,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA6B3E"}

package/dist/pool-artifact.js

@@ -0,0 +1,59 @@
+/**
+ * Filesystem IO for the seed-pool wrapper artifact. The byte FORMAT
+ * (schema version, layout names, codeRef shape, rejection/issue
+ * messages) is owned by `@ggui-ai/artifact-manifest`'s pool-artifact
+ * codec — this module owns only the directory IO: writing/reading the
+ * manifest + code bodies and splicing `componentCode` back in.
+ */
+import { mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { POOL_ARTIFACT_CODES_DIR, POOL_ARTIFACT_MANIFEST_FILENAME, buildPoolArtifactManifest, parsePoolArtifactManifest, poolArtifactCodeRef, serializePoolArtifactManifest, } from '@ggui-ai/artifact-manifest';
+const codeHash = (code) => createHash('sha256').update(code, 'utf-8').digest('hex');
+/** Write records to a directory: manifest.json + codes/<hash>.tsx. */
+export async function writePoolArtifact(dir, records) {
+    // Clear ONLY the files this codec owns, never the whole dir — the caller's
+    // path (e.g. `--out .`) is passed through verbatim, so a recursive wipe of
+    // `dir` would delete unrelated files. Removing `codes/` + the manifest still
+    // guarantees no stale code bodies survive a rewrite.
+    await mkdir(dir, { recursive: true });
+    await rm(join(dir, POOL_ARTIFACT_CODES_DIR), { recursive: true, force: true });
+    await rm(join(dir, POOL_ARTIFACT_MANIFEST_FILENAME), { force: true });
+    await mkdir(join(dir, POOL_ARTIFACT_CODES_DIR), { recursive: true });
+    const entries = [];
+    for (const r of records) {
+        const codeRef = poolArtifactCodeRef(codeHash(r.componentCode));
+        await writeFile(join(dir, POOL_ARTIFACT_CODES_DIR, codeRef), r.componentCode, 'utf-8');
+        const { componentCode: _omit, ...rest } = r;
+        entries.push({ record: rest, codeRef });
+    }
+    await writeFile(join(dir, POOL_ARTIFACT_MANIFEST_FILENAME), serializePoolArtifactManifest(buildPoolArtifactManifest(entries)), 'utf-8');
+}
+/** Read + reassemble records. Throws on a missing/invalid manifest or unsupported schemaVersion (v1 included — re-export, no migration shim). */
+export async function readPoolArtifact(dir) {
+    let raw;
+    try {
+        raw = await readFile(join(dir, POOL_ARTIFACT_MANIFEST_FILENAME), 'utf-8');
+    }
+    catch (cause) {
+        throw new Error(`seed pool: cannot read ${join(dir, POOL_ARTIFACT_MANIFEST_FILENAME)}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const parsed = parsePoolArtifactManifest(raw);
+    if (!parsed.ok) {
+        throw new Error(`seed pool: ${parsed.reason}`);
+    }
+    const records = [];
+    const issues = parsed.issues.map((issue) => `seed pool: ${issue}`);
+    for (const entry of parsed.manifest.blueprints) {
+        let componentCode;
+        try {
+            componentCode = await readFile(join(dir, POOL_ARTIFACT_CODES_DIR, entry.codeRef), 'utf-8');
+        }
+        catch {
+            issues.push(`seed pool: missing code body ${entry.codeRef}; skipping blueprint`);
+            continue;
+        }
+        records.push({ ...entry.record, componentCode });
+    }
+    return { records, issues };
+}

package/dist/provider-key-command.d.ts

@@ -0,0 +1,51 @@
+/** Providers that accept a user-supplied plaintext API key. */
+export declare const BYOK_PROVIDERS: readonly ["anthropic", "openai", "google", "openrouter"];
+/** Provider name subset that supports BYOK. */
+export type ByokProvider = (typeof BYOK_PROVIDERS)[number];
+/**
+ * Resolve which LLM provider to push a key for.
+ *
+ * Priority:
+ *   1. `flagProvider` (explicit `--provider` flag) — validated against BYOK set.
+ *      Bedrock → descriptive error. Unknown provider → error.
+ *   2. `ggui.json#generation.model` — parsed via `parseAnyLlmRoute` from
+ *      `@ggui-ai/protocol`. Bedrock → error. Unparseable / absent → error.
+ *
+ * **Does NOT hand-roll a provider parser.** All model-string parsing goes
+ * through `parseAnyLlmRoute` (covers both canonical `provider:model` and
+ * LiteLLM `provider/model` forms).
+ */
+export declare function inferProvider(gguiJson: unknown, flagProvider: string | undefined): ByokProvider | {
+    error: string;
+};
+/**
+ * Return the primary env-var name for a BYOK provider.
+ * For google the primary is `GOOGLE_API_KEY` (with `GEMINI_API_KEY` as
+ * fallback checked in `readKeyFromEnv`). Order matches `byok-resolver.ts`
+ * so that the local-dev key and the pushed key always agree.
+ */
+export declare function envVarForProvider(provider: ByokProvider): string;
+/**
+ * Read the API key for a BYOK provider from the given env.
+ *
+ * - `anthropic`   → `ANTHROPIC_API_KEY`
+ * - `openai`      → `OPENAI_API_KEY`
+ * - `google`      → `GOOGLE_API_KEY` (primary), then `GEMINI_API_KEY` (fallback)
+ * - `openrouter`  → `OPENROUTER_API_KEY`
+ *
+ * Order matches `byok-resolver.ts` so that the key the cloud receives is
+ * always the same one local generation uses.
+ *
+ * Returns `undefined` when no non-empty value is found.
+ */
+export declare function readKeyFromEnv(provider: ByokProvider, env?: Readonly<Record<string, string | undefined>>): string | undefined;
+export declare const PROVIDER_KEY_HELP = "ggui provider-key \u2014 manage cloud provider API keys for a ggui app\n\nUsage:\n  ggui provider-key set --app <appId> [--provider <name>]\n\nSubcommands:\n  set   Push a provider API key from the appropriate env var to the cloud app.\n        The provider is derived from ggui.json#generation.model unless\n        --provider is given explicitly.\n\n        Supported providers: anthropic, openai, google, openrouter.\n        (bedrock is IAM-only \u2014 no plaintext key to push.)\n\n        Reads the key from env:\n          ANTHROPIC_API_KEY  (anthropic)\n          OPENAI_API_KEY     (openai)\n          GOOGLE_API_KEY     (google, primary); GEMINI_API_KEY (fallback)\n          OPENROUTER_API_KEY (openrouter)\n\nOptions:\n  --app <appId>       Target app ID (required).\n  --provider <name>   Override provider (default: derived from ggui.json).\n  --help, -h          Show this help.\n";
+/**
+ * Entry point for `ggui provider-key <subcommand> [options]`.
+ *
+ * @param args - argv slice after `provider-key` (e.g. `['set', '--app', 'app123']`)
+ * @param startDir - optional cwd override (primarily for tests)
+ * @returns exit code (0 = success, 1 = error)
+ */
+export declare function runProviderKeyCommand(args: readonly string[], startDir?: string): Promise<number>;
+//# sourceMappingURL=provider-key-command.d.ts.map

package/dist/provider-key-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-key-command.d.ts","sourceRoot":"","sources":["../src/provider-key-command.ts"],"names":[],"mappings":"AAqBA,+DAA+D;AAC/D,eAAO,MAAM,cAAc,0DAA2D,CAAC;AAEvF,+CAA+C;AAC/C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAU3D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,OAAO,EACjB,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA8ClC;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAWhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,YAAY,EACtB,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,MAAM,GAAG,SAAS,CAWpB;AAMD,eAAO,MAAM,iBAAiB,o4BAuB7B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,GAAE,MAAsB,GAC/B,OAAO,CAAC,MAAM,CAAC,CA+EjB"}