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

package/dist/deploy-command.js

@@ -0,0 +1,386 @@
+/**
+ * `ggui deploy` — idempotent orchestrator that provisions and wires a
+ * ggui.ai cloud app for the current project.
+ *
+ * Sequencing (ggui-side only):
+ *   1. login        — device-flow auth (if not already signed in)
+ *   2. create-app   — POST /v1/apps, persist appId into ggui.json
+ *   3. mint-key     — POST /v1/keys, write GGUI_MCP_BEARER into .env.local
+ *   4. push         — export local blueprint pool + upload to the app
+ *   5. push-config  — PATCH /v1/apps/{appId}: gadgets + publicEnv from ggui.json
+ *   6. wire-env     — write GGUI_MCP_URL into .env.local
+ *
+ * Each step is skipped when its gate is already satisfied, making the
+ * command idempotent — run it again after a partial failure and it
+ * resumes from the first unsatisfied step.
+ *
+ * Agent / MCP HOSTING (guuey.com) is out of scope for `ggui deploy`.
+ * This command wires only the ggui UI layer.
+ */
+/* eslint-disable no-console */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tryLoadAuthSession } from './auth-store.js';
+import { runLoginCommand } from './auth-login.js';
+import { createApp, createKey } from './api-client.js';
+import { findGguiJson, readGguiJson, writeGguiJson } from './internal/ggui-json.js';
+import { runPushCommand } from './push-command.js';
+import { runConfigPushStep } from './config-push.js';
+import { runProviderKeyCommand } from './provider-key-command.js';
+/**
+ * Derive the ordered list of steps to execute given the current state.
+ * Pure function — no I/O.
+ *
+ * Step order:
+ *   login? → create-app? → mint-key? → push → push-config → push-keys? → wire-env
+ */
+export function planDeploySteps(input) {
+    const { state: s, pushKeys } = input;
+    const steps = [];
+    if (!s.authed)
+        steps.push({ kind: 'login' });
+    if (!s.appId)
+        steps.push({ kind: 'create-app' });
+    if (!s.hasKey)
+        steps.push({ kind: 'mint-key' });
+    steps.push({ kind: 'push' }, { kind: 'push-config' });
+    if (pushKeys)
+        steps.push({ kind: 'push-keys' });
+    steps.push({ kind: 'wire-env' });
+    return steps;
+}
+/**
+ * Resolve the `GGUI_MCP_URL` value `ggui deploy` wires into `.env.local`.
+ *
+ * The per-app cloud pod serves the MCP transport at the BARE per-app endpoint
+ * `<base>/apps/<appId>` (the `connectUrl` the backend advertises) — NOT a
+ * `/mcp` sub-path. The `/mcp` suffix is the LOCAL `ggui serve` convention;
+ * appending it here produced a URL the per-app pod 404s, so the agent (which
+ * reads GGUI_MCP_URL verbatim) could never connect to a deployed app.
+ *
+ *   - `connectUrl` present (a create-app ran this session) → use it VERBATIM —
+ *     the deployment-correct base (prod `mcp.ggui.ai`, sandbox
+ *     `<env>.mcp.sandbox.ggui.ai`, derived from whichever backend `GGUI_API_URL`
+ *     pointed at).
+ *   - absent → the PRODUCTION default `https://mcp.ggui.ai/apps/<appId>`.
+ *
+ * The caller leaves any pre-existing `GGUI_MCP_URL` untouched (env override).
+ */
+export function resolveDeployMcpUrl(connectUrl, appId) {
+    return connectUrl ?? `https://mcp.ggui.ai/apps/${appId}`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// .env.local upsert helper
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Read-modify-write `.env.local` at `envLocalPath`, upserting `key=value`.
+ *
+ * - If the file doesn't exist, creates it with only this line.
+ * - If the key already exists, replaces its value in-place.
+ * - Other keys/comments are preserved unchanged.
+ * - No trailing newline is added beyond the final `\n`.
+ */
+export function upsertEnvLocal(envLocalPath, key, value) {
+    const line = `${key}=${value}`;
+    if (!existsSync(envLocalPath)) {
+        writeFileSync(envLocalPath, `${line}\n`, 'utf-8');
+        return;
+    }
+    const raw = readFileSync(envLocalPath, 'utf-8');
+    const lines = raw.split('\n');
+    let found = false;
+    const updated = lines.map((l) => {
+        // Match `KEY=...` or `export KEY=...` (no leading spaces per convention).
+        const trimmed = l.startsWith('export ') ? l.slice(7) : l;
+        const eq = trimmed.indexOf('=');
+        if (eq !== -1 && trimmed.slice(0, eq).trim() === key) {
+            found = true;
+            return line;
+        }
+        return l;
+    });
+    if (!found) {
+        // Append: ensure one blank line before the new entry if the file is
+        // non-empty and doesn't already end with a blank line.
+        const last = updated[updated.length - 1];
+        if (last !== undefined && last.trim() !== '') {
+            updated.push('');
+        }
+        updated.push(line);
+    }
+    // Rejoin preserving the original trailing-newline behaviour.
+    const result = updated.join('\n');
+    writeFileSync(envLocalPath, result.endsWith('\n') ? result : `${result}\n`, 'utf-8');
+}
+/**
+ * Read the non-empty value of `key` from `.env.local`, or `undefined` if
+ * the file doesn't exist, the key is absent, or its value is empty.
+ * Strips surrounding quotes + `export ` prefix the same way `upsertEnvLocal`
+ * recognises them.
+ */
+export function readEnvLocalValue(envLocalPath, key) {
+    if (!existsSync(envLocalPath))
+        return undefined;
+    const raw = readFileSync(envLocalPath, 'utf-8');
+    for (const rawLine of raw.split('\n')) {
+        const l = rawLine.trim().startsWith('export ')
+            ? rawLine.trim().slice(7)
+            : rawLine.trim();
+        const eq = l.indexOf('=');
+        if (eq !== -1 && l.slice(0, eq).trim() === key) {
+            const val = l
+                .slice(eq + 1)
+                .replace(/^["']|["']$/g, '')
+                .trim();
+            if (val.length > 0)
+                return val;
+        }
+    }
+    return undefined;
+}
+/**
+ * Read the current deploy state from disk:
+ *   - authed  : ~/.ggui/auth.json is present + valid
+ *   - appId   : ggui.json#appId if found
+ *   - hasKey  : GGUI_MCP_BEARER present in .env.local (not empty)
+ */
+function readDeployContext(cwd) {
+    const gguiJsonPath = findGguiJson(cwd);
+    // .env.local lives next to ggui.json when one is found, else at cwd.
+    const projectRoot = gguiJsonPath ? dirname(gguiJsonPath) : cwd;
+    const envLocalPath = join(projectRoot, '.env.local');
+    const authed = tryLoadAuthSession() !== null;
+    let appId;
+    if (gguiJsonPath) {
+        const result = readGguiJson(gguiJsonPath);
+        if ('value' in result) {
+            const v = result.value['appId'];
+            if (typeof v === 'string' && v.length > 0)
+                appId = v;
+        }
+    }
+    const hasKey = readEnvLocalValue(envLocalPath, 'GGUI_MCP_BEARER') !== undefined;
+    return {
+        gguiJsonPath,
+        envLocalPath,
+        state: { authed, appId, hasKey },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Orchestrator
+// ─────────────────────────────────────────────────────────────────────────────
+export const DEPLOY_HELP = `ggui deploy — provision + wire a ggui.ai cloud app for this project
+
+Idempotent: run it again after a partial failure to resume.
+
+Steps (ggui-side only):
+  1. login        Sign in (skipped if already authed)
+  2. create-app   Create a cloud app + write appId into ggui.json
+  3. mint-key     Create a connector key + write GGUI_MCP_BEARER into .env.local
+  4. push         Export + upload blueprints to the app
+  5. push-config  Push declared gadgets + publicEnv to the app
+  6. push-keys    Push provider API key from env to the app (only with --push-keys)
+  7. wire-env     Write GGUI_MCP_URL into .env.local
+
+Agent / MCP HOSTING (guuey.com) is handled separately.
+
+Usage:
+  ggui deploy [--push-keys]
+
+Options:
+  --push-keys  Read the provider API key from the appropriate env var
+               (e.g. ANTHROPIC_API_KEY) and push it to the cloud app so
+               keySource=own renders work. Derives the provider from
+               ggui.json#generation.model (or pass --provider to
+               \`ggui provider-key set\` directly).
+`;
+/**
+ * Orchestrate a full ggui-side deploy. Returns a process exit code.
+ */
+export async function runDeployCommand(_args) {
+    if (_args.includes('--help') || _args.includes('-h')) {
+        process.stdout.write(DEPLOY_HELP);
+        return 0;
+    }
+    const pushKeys = _args.includes('--push-keys');
+    const cwd = process.cwd();
+    // Read current state.
+    const ctx = readDeployContext(cwd);
+    const { gguiJsonPath, envLocalPath, state } = ctx;
+    if (!gguiJsonPath) {
+        process.stderr.write('ggui deploy: no ggui.json found in this directory or its parents.\n' +
+            '  Run from a scaffolded project directory (one created by `npx @ggui-ai/create-agentic-app`).\n');
+        return 1;
+    }
+    const steps = planDeploySteps({ state, pushKeys });
+    // Mutable state for values discovered mid-run that subsequent steps need.
+    let appId = state.appId;
+    let connectUrl;
+    for (const step of steps) {
+        switch (step.kind) {
+            case 'login': {
+                process.stdout.write('\n[ggui deploy] Step: login\n');
+                const code = await runLoginCommand([]);
+                if (code !== 0) {
+                    process.stderr.write('ggui deploy: login failed. Aborting.\n');
+                    return code;
+                }
+                // runLoginCommand persisted the session to ~/.ggui/auth.json;
+                // createApp / createKey load it internally, so nothing to thread
+                // forward here.
+                break;
+            }
+            case 'create-app': {
+                process.stdout.write('\n[ggui deploy] Step: create-app\n');
+                let app;
+                try {
+                    app = await createApp({});
+                }
+                catch (err) {
+                    process.stderr.write(`ggui deploy: create-app failed — ${err instanceof Error ? err.message : String(err)}\n`);
+                    return 1;
+                }
+                appId = app.appId;
+                connectUrl = app.connectUrl;
+                // Persist appId into ggui.json. The app already exists server-side
+                // now, so a persist failure is LOUD: without the appId on disk a
+                // re-run would call create-app again and create a DUPLICATE app.
+                const read = readGguiJson(gguiJsonPath);
+                if ('error' in read) {
+                    process.stderr.write(`ggui deploy: create-app: app ${app.appId} was created, but ggui.json ` +
+                        `could not be read to persist appId — ${read.error}\n` +
+                        `  Add "appId": "${app.appId}" to ggui.json manually before re-running, ` +
+                        `or a re-run will create a DUPLICATE app.\n`);
+                    return 1;
+                }
+                writeGguiJson(gguiJsonPath, { ...read.value, appId });
+                process.stdout.write(`  appId:      ${app.appId}\n`);
+                process.stdout.write(`  connectUrl: ${app.connectUrl}\n`);
+                break;
+            }
+            case 'mint-key': {
+                process.stdout.write('\n[ggui deploy] Step: mint-key\n');
+                let key;
+                try {
+                    key = await createKey({ name: 'ggui deploy' });
+                }
+                catch (err) {
+                    process.stderr.write(`ggui deploy: mint-key failed — ${err instanceof Error ? err.message : String(err)}\n`);
+                    return 1;
+                }
+                // Write the one-time-reveal secret into .env.local.
+                upsertEnvLocal(envLocalPath, 'GGUI_MCP_BEARER', key.apiKey);
+                process.stdout.write(`  Key created (prefix: ${key.prefix}). Written to .env.local.\n`);
+                break;
+            }
+            case 'push': {
+                process.stdout.write('\n[ggui deploy] Step: push\n');
+                if (!appId) {
+                    process.stderr.write('ggui deploy: push: no appId resolved. This is a bug.\n');
+                    return 1;
+                }
+                const code = await runPushCommand(['--app', appId]);
+                if (code !== 0) {
+                    process.stderr.write('ggui deploy: push failed. Aborting.\n');
+                    return code;
+                }
+                break;
+            }
+            case 'push-config': {
+                process.stdout.write('\n[ggui deploy] Step: push-config\n');
+                if (!appId) {
+                    process.stderr.write('ggui deploy: push-config: no appId resolved. This is a bug.\n');
+                    return 1;
+                }
+                const code = await runConfigPushStep(appId);
+                if (code !== 0) {
+                    process.stderr.write('ggui deploy: push-config failed. Aborting.\n');
+                    return code;
+                }
+                break;
+            }
+            case 'push-keys': {
+                process.stdout.write('\n[ggui deploy] Step: push-keys\n');
+                if (!appId) {
+                    process.stderr.write('ggui deploy: push-keys: no appId resolved. This is a bug.\n');
+                    return 1;
+                }
+                const code = await runProviderKeyCommand(['set', '--app', appId]);
+                if (code !== 0) {
+                    process.stderr.write('ggui deploy: push-keys failed. Aborting.\n');
+                    return code;
+                }
+                break;
+            }
+            case 'wire-env': {
+                process.stdout.write('\n[ggui deploy] Step: wire-env\n');
+                if (!appId) {
+                    process.stderr.write('ggui deploy: wire-env: no appId resolved. This is a bug.\n');
+                    return 1;
+                }
+                // NEVER clobber an existing GGUI_MCP_URL. The FIRST deploy writes
+                // the deployment-correct base derived from create-app's connectUrl
+                // (e.g. sandbox `<env>.mcp.sandbox.ggui.ai`, prod `mcp.ggui.ai`).
+                // On REDEPLOY we have only the appId — reconstructing a hardcoded
+                // prod URL here would silently break a sandbox/non-prod deployment.
+                // So: leave any existing value alone; only write when absent.
+                const existing = readEnvLocalValue(envLocalPath, 'GGUI_MCP_URL');
+                if (existing) {
+                    process.stdout.write(`  GGUI_MCP_URL already set (${existing}) — leaving it unchanged.\n`);
+                    break;
+                }
+                // No prior value → resolve the deployment-correct BARE per-app URL
+                // (see resolveDeployMcpUrl: the per-app pod serves MCP at the bare
+                // endpoint, never `/mcp`). The fallback to the production default only
+                // fires when create-app didn't run this session — a first deploy always
+                // has connectUrl, so it never reaches the fallback in practice.
+                const mcpUrl = resolveDeployMcpUrl(connectUrl, appId);
+                upsertEnvLocal(envLocalPath, 'GGUI_MCP_URL', mcpUrl);
+                process.stdout.write(`  GGUI_MCP_URL=${mcpUrl}\n`);
+                break;
+            }
+            default: {
+                // Exhaustiveness check — DeployStepKind is a union; this branch
+                // is unreachable in correct code.
+                const _exhaustive = step.kind;
+                process.stderr.write(`ggui deploy: unknown step "${_exhaustive}"\n`);
+                return 1;
+            }
+        }
+    }
+    // keySource=own WARN — if the project declared keySource='own' but the
+    // user didn't pass --push-keys this deploy, remind them that cloud renders
+    // will reject until a key is set.
+    if (!pushKeys && appId) {
+        const gguiReadResult = readGguiJson(gguiJsonPath);
+        if ('value' in gguiReadResult) {
+            const { z } = await import('zod');
+            const schema = z.object({
+                generation: z.object({ keySource: z.string().optional() }).optional(),
+            });
+            const parsed = schema.safeParse(gguiReadResult.value);
+            if (parsed.success && parsed.data.generation?.keySource === 'own') {
+                process.stderr.write(`\n  WARN: keySource=own but no provider key pushed — run\n` +
+                    `    ggui deploy --push-keys\n` +
+                    `  or\n` +
+                    `    ggui provider-key set --app ${appId}\n` +
+                    `  else cloud renders will reject.\n`);
+            }
+        }
+    }
+    // Report the URL actually in .env.local — after wire-env that file is
+    // authoritative (a preserved sandbox/non-prod value is reflected
+    // accurately rather than re-derived as the prod default).
+    const finalMcpUrl = readEnvLocalValue(envLocalPath, 'GGUI_MCP_URL') ?? '(unknown)';
+    process.stdout.write('\n');
+    process.stdout.write('  ggui deploy complete.\n');
+    process.stdout.write(`\n`);
+    process.stdout.write(`  App MCP endpoint:  ${finalMcpUrl}\n`);
+    process.stdout.write(`  Bearer key:        in .env.local (GGUI_MCP_BEARER)\n`);
+    process.stdout.write('\n');
+    process.stdout.write('  The agent will use the cloud ggui endpoint on next `pnpm dev`.\n' +
+        '  Local ggui service is skipped automatically when GGUI_MCP_URL is remote.\n' +
+        '\n' +
+        '  Agent / MCP hosting (guuey.com) is handled separately.\n');
+    return 0;
+}

package/dist/dev-command.d.ts

@@ -28,14 +28,18 @@ export interface ParsedDevFlags {
      */
     tunnel: boolean;
     agent?: string;
+    /** `'__help__'` for `--help` / `-h`; other strings = usage error. */
     error?: string;
 }
 /**
  * Parse the raw `ggui dev` argv tail. Returns a discriminated
  * shape — `error` field is non-undefined when the input was
- * malformed; callers render it and bail with exit code 1.
+ * malformed (`'__help__'` is the help sentinel, mirroring
+ * `parseServeFlags`); callers render it and bail with exit code 1.
  */
 export declare function parseDevFlags(args: readonly string[]): ParsedDevFlags;
+/** Help text for `ggui dev` — printed on `--help` / `-h`. */
+export declare const DEV_HELP = "ggui dev \u2014 run the local development stack\n\nBoots the local dev hub (UI registry + dev server) and, when\n`--agent` is supplied, supervises your agent entry alongside it.\nSets GGUI_MODE=dev (unless already set) so the server mounts the\n/devtools/* namespace and the SPA shows the link. In an interactive\nterminal the hub URL auto-opens in your browser (skipped in CI, when\nstdout is piped, with BROWSER=none, or with --no-open).\n\nUsage:\n  ggui dev [options]\n\nOptions:\n  --port <n>        Bind port (default: 6780, 0 = OS-assigned).\n  --host <addr>     Bind host (default: 127.0.0.1).\n  --agent <entry>   Agent entry file to supervise (e.g. src/agent.ts).\n                    Resolved before the socket binds \u2014 bad paths fail fast.\n  --no-serve        Do not bind the HTTP dev hub; run registry-only.\n  --no-open         Skip the browser auto-open.\n  --tunnel          Opt into managed-mode: after the local stack is\n                    listening, the configured tunnel provider exposes it\n                    remotely. The local loop runs unchanged either way.\n  --help, -h        Show this help.\n";
 export { resolveAgentCommand, buildAgentRuntime };
 export type { AgentCommandResolution };
 /**

package/dist/dev-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-command.d.ts","sourceRoot":"","sources":["../src/dev-command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dev-command.d.ts","sourceRoot":"","sources":["../src/dev-command.ts"],"names":[],"mappings":"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"}

package/dist/dev-command.js

@@ -13,11 +13,13 @@
  * tunnel, a test harness) pick their own launch policy.
  */
 import { spawn as nodeSpawn, } from 'node:child_process';
+import { DEFAULT_DEV_HOST, DEFAULT_DEV_PORT } from '@ggui-ai/dev-stack';
 import { buildAgentRuntime, resolveAgentCommand, } from './agent-resolution.js';
 /**
  * Parse the raw `ggui dev` argv tail. Returns a discriminated
  * shape — `error` field is non-undefined when the input was
- * malformed; callers render it and bail with exit code 1.
+ * malformed (`'__help__'` is the help sentinel, mirroring
+ * `parseServeFlags`); callers render it and bail with exit code 1.
  */
 export function parseDevFlags(args) {
     const out = { noServe: false, noOpen: false, tunnel: false };
@@ -61,10 +63,38 @@ export function parseDevFlags(args) {
             out.agent = v;
             continue;
         }
+        if (arg === '--help' || arg === '-h') {
+            return { ...out, error: '__help__' };
+        }
         return { ...out, error: `unknown flag "${arg ?? ''}"` };
     }
     return out;
 }
+/** Help text for `ggui dev` — printed on `--help` / `-h`. */
+export const DEV_HELP = `ggui dev — run the local development stack
+
+Boots the local dev hub (UI registry + dev server) and, when
+\`--agent\` is supplied, supervises your agent entry alongside it.
+Sets GGUI_MODE=dev (unless already set) so the server mounts the
+/devtools/* namespace and the SPA shows the link. In an interactive
+terminal the hub URL auto-opens in your browser (skipped in CI, when
+stdout is piped, with BROWSER=none, or with --no-open).
+
+Usage:
+  ggui dev [options]
+
+Options:
+  --port <n>        Bind port (default: ${DEFAULT_DEV_PORT}, 0 = OS-assigned).
+  --host <addr>     Bind host (default: ${DEFAULT_DEV_HOST}).
+  --agent <entry>   Agent entry file to supervise (e.g. src/agent.ts).
+                    Resolved before the socket binds — bad paths fail fast.
+  --no-serve        Do not bind the HTTP dev hub; run registry-only.
+  --no-open         Skip the browser auto-open.
+  --tunnel          Opt into managed-mode: after the local stack is
+                    listening, the configured tunnel provider exposes it
+                    remotely. The local loop runs unchanged either way.
+  --help, -h        Show this help.
+`;
 // Agent-entry resolution + adapter construction live in
 // `./agent-resolution.ts`. They are re-exported here so call sites
 // that reach for these from `dev-command.js` keep working — and

package/dist/export-pool-command.d.ts

@@ -0,0 +1,25 @@
+export declare const EXPORT_POOL_HELP = "ggui export-pool \u2014 export this app's reusable blueprints as a shared pool\n\nWrites a directory artifact (manifest.json + codes/) that another ggui\ndeployment can load with `ggui serve --seed-pool <dir>`.\n\nUsage:\n  ggui export-pool [--out <dir>]\n\nOptions:\n  --out <dir>   Output directory (default: ./ggui-pool).\n\nRequires a persistent vectors store (ggui.json: storage.vectors.driver = \"sqlite\").\n";
+/** Result of {@link exportLocalPool}: the artifact directory + how many records it holds. */
+export interface ExportLocalPoolResult {
+    /** Absolute path of the written artifact directory. */
+    readonly dir: string;
+    /** Number of blueprint records written (may be 0 — the artifact dir is still written). */
+    readonly count: number;
+}
+/**
+ * Resolve the storage stack → list blueprints → write a pool artifact to disk.
+ *
+ * When `outDir` is omitted a fresh temp directory is created (suitable for
+ * a subsequent `ggui push` that immediately reads the artifact). When provided,
+ * the artifact is written to `resolve(process.cwd(), outDir)`.
+ *
+ * Throws on hard errors (no vectors store, list failure). An empty pool is
+ * NOT an error here — the artifact directory is written regardless (possibly
+ * holding zero records) so callers can decide whether "nothing to export /
+ * push" is graceful (push) or an error (explicit `export-pool`).
+ *
+ * Returns the artifact directory + record count.
+ */
+export declare function exportLocalPool(outDir?: string): Promise<ExportLocalPoolResult>;
+export declare function runExportPoolCommand(args: readonly string[]): Promise<number>;
+//# sourceMappingURL=export-pool-command.d.ts.map

package/dist/export-pool-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-pool-command.d.ts","sourceRoot":"","sources":["../src/export-pool-command.ts"],"names":[],"mappings":"AAkCA,eAAO,MAAM,gBAAgB,oaAY5B,CAAC;AAEF,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA0CrF;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBnF"}

package/dist/export-pool-command.js

@@ -0,0 +1,116 @@
+import { dirname, resolve } from 'node:path';
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { listRegistryBlueprintsForExport, } from '@ggui-ai/mcp-server-handlers';
+import { toPortableBlueprint } from '@ggui-ai/protocol/blueprint-key';
+import { resolveStorageFromConfig, DEFAULT_BUILDER_APP_ID } from '@ggui-ai/mcp-server';
+import { findGguiJson, safeLoadGguiJson, } from '@ggui-ai/project-config/node';
+import { writePoolArtifact } from './pool-artifact.js';
+function parseExportPoolFlags(args) {
+    let out = './ggui-pool';
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--out' || a === '-o') {
+            const v = args[++i];
+            if (v === undefined)
+                return { out, error: '--out requires a path' };
+            out = v;
+        }
+        else if (a === '--help' || a === '-h') {
+            return { out, error: '__help__' };
+        }
+    }
+    return { out };
+}
+export const EXPORT_POOL_HELP = `ggui export-pool — export this app's reusable blueprints as a shared pool
+
+Writes a directory artifact (manifest.json + codes/) that another ggui
+deployment can load with \`ggui serve --seed-pool <dir>\`.
+
+Usage:
+  ggui export-pool [--out <dir>]
+
+Options:
+  --out <dir>   Output directory (default: ./ggui-pool).
+
+Requires a persistent vectors store (ggui.json: storage.vectors.driver = "sqlite").
+`;
+/**
+ * Resolve the storage stack → list blueprints → write a pool artifact to disk.
+ *
+ * When `outDir` is omitted a fresh temp directory is created (suitable for
+ * a subsequent `ggui push` that immediately reads the artifact). When provided,
+ * the artifact is written to `resolve(process.cwd(), outDir)`.
+ *
+ * Throws on hard errors (no vectors store, list failure). An empty pool is
+ * NOT an error here — the artifact directory is written regardless (possibly
+ * holding zero records) so callers can decide whether "nothing to export /
+ * push" is graceful (push) or an error (explicit `export-pool`).
+ *
+ * Returns the artifact directory + record count.
+ */
+export async function exportLocalPool(outDir) {
+    // Resolve the SAME storage stack `ggui serve` uses, from ggui.json in cwd.
+    // A missing manifest is fine (MCP-only / default storage); a manifest that
+    // exists but fails schema validation is a hard error — surface it rather
+    // than silently falling through to the generic "no vectors store" message.
+    const gguiJsonPath = findGguiJson(process.cwd());
+    let manifest;
+    if (gguiJsonPath) {
+        const loaded = safeLoadGguiJson(gguiJsonPath);
+        if (!loaded.success) {
+            throw new Error(loaded.error.message);
+        }
+        manifest = loaded.data;
+    }
+    const projectRoot = gguiJsonPath ? dirname(gguiJsonPath) : process.cwd();
+    const storage = await resolveStorageFromConfig(manifest?.storage, { baseDir: projectRoot });
+    if (!storage.vectors) {
+        throw new Error('no persistent vectors store. Set storage.vectors.driver="sqlite" in ggui.json (nothing to export from an in-memory store).');
+    }
+    const rows = await listRegistryBlueprintsForExport(storage.vectors, DEFAULT_BUILDER_APP_ID);
+    // Tool-identity catalog is NOT available here: `export-pool` is a
+    // batch offline export with no live MCP connections. The catalog is
+    // a runtime artifact built from active `initialize` + `tools/list`
+    // handshakes during `ggui serve`. Passing it here would require
+    // either persisting it to disk or starting the server just for export
+    // — both are the wrong trade-off for an offline command. The
+    // `generatorProtocolVersion` stamp (always set by toPortableBlueprint)
+    // is sufficient for era-compatibility gating; the `toolIdentityCatalogHash`
+    // remains absent, triggering an "unstamped → warn" policy on importers.
+    const records = rows.map((r) => toPortableBlueprint(r));
+    const resolvedDir = outDir !== undefined
+        ? resolve(process.cwd(), outDir)
+        : await mkdtemp(join(tmpdir(), 'ggui-pool-'));
+    await writePoolArtifact(resolvedDir, records);
+    return { dir: resolvedDir, count: records.length };
+}
+export async function runExportPoolCommand(args) {
+    const flags = parseExportPoolFlags(args);
+    if (flags.error === '__help__') {
+        process.stdout.write(EXPORT_POOL_HELP);
+        return 0;
+    }
+    if (flags.error) {
+        process.stderr.write(`ggui export-pool: ${flags.error}\n`);
+        return 1;
+    }
+    let result;
+    try {
+        result = await exportLocalPool(flags.out);
+    }
+    catch (err) {
+        process.stderr.write(`ggui export-pool: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    // Explicit `export-pool` of an empty pool is an error: the operator asked
+    // to export something and there is nothing. (The on-the-fly export path
+    // used by `ggui push` treats 0 as a graceful "nothing to push" instead.)
+    if (result.count === 0) {
+        process.stderr.write('ggui export-pool: 0 blueprints found for this app; nothing written.\n');
+        return 1;
+    }
+    process.stdout.write(`ggui export-pool: wrote ${result.count} blueprint(s) to ${result.dir}\n`);
+    return 0;
+}

package/dist/filesystem-seed-pool-source.d.ts

@@ -0,0 +1,13 @@
+import type { SeedPoolSource } from '@ggui-ai/mcp-server-handlers';
+/**
+ * Reads a seed-pool directory artifact (B2 OSS adapter). Records come
+ * back raw/unvalidated — `buildSeedPool` runs each one through the
+ * `fromPortableBlueprint` trust boundary.
+ */
+export declare class FileSystemSeedPoolSource implements SeedPoolSource {
+    private readonly dir;
+    readonly label: string;
+    constructor(dir: string);
+    loadAll(): Promise<readonly unknown[]>;
+}
+//# sourceMappingURL=filesystem-seed-pool-source.d.ts.map

package/dist/filesystem-seed-pool-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-seed-pool-source.d.ts","sourceRoot":"","sources":["../src/filesystem-seed-pool-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAGnE;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,cAAc;IAEjD,OAAO,CAAC,QAAQ,CAAC,GAAG;IADhC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBACM,GAAG,EAAE,MAAM;IAGlC,OAAO,IAAI,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC;CAQ7C"}

package/dist/filesystem-seed-pool-source.js

@@ -0,0 +1,22 @@
+import { readPoolArtifact } from './pool-artifact.js';
+/**
+ * Reads a seed-pool directory artifact (B2 OSS adapter). Records come
+ * back raw/unvalidated — `buildSeedPool` runs each one through the
+ * `fromPortableBlueprint` trust boundary.
+ */
+export class FileSystemSeedPoolSource {
+    dir;
+    label;
+    constructor(dir) {
+        this.dir = dir;
+        this.label = `seed:${dir}`;
+    }
+    async loadAll() {
+        const { records, issues } = await readPoolArtifact(this.dir);
+        for (const issue of issues) {
+            // eslint-disable-next-line no-console -- operator-visible load warning
+            console.warn(`[ggui] ${issue}`);
+        }
+        return records;
+    }
+}