@ggui-ai/cli 0.1.0-rc.1

package/dist/serve-command.d.ts

@@ -0,0 +1,500 @@
+/**
+ * `ggui serve` argument parsing, banner rendering, and lifecycle
+ * driver.
+ *
+ * Runs the open self-hosted personal-mode path from `@ggui-ai/mcp-server`
+ * + an optional supervised agent. Default (no flags, with a valid
+ * `ggui.json` + `agent.entry`) is MCP + agent side by side. Opt-down
+ * is `--mcp-only`. Missing-or-incomplete config falls back to
+ * MCP-only with a warning; broken config is a `cli.ts`-level error
+ * surfaced separately.
+ *
+ * Deliberately distinct from `ggui dev`:
+ *
+ *   - `ggui dev`   — local dev loop: registry + hub + runtime supervision
+ *                   + preview + (optional) tunnel. Developer-facing.
+ *   - `ggui serve` — personal-mode self-hosted runtime: MCP server +
+ *                    optional supervised agent. Operator-facing.
+ *
+ * Keep these separate. The only shared code between them is pure
+ * agent-entry resolution (`./agent-resolution.ts`) — no dev-loop
+ * concerns leak into serve.
+ *
+ * This module stays pure / testable — no `node:http` binds, no
+ * `createGguiServer()` import, no logger dep. `cli.ts` composes this
+ * logic with the real server package, agent adapter, and logger.
+ */
+import type { AgentRuntimeAdapter, AgentRuntimeEvent, AgentRuntimeStartInput } from '@ggui-ai/agent-runtime';
+import type { PairingService } from '@ggui-ai/mcp-server';
+/**
+ * Default bind port. Distinct from `ggui dev`'s 6780 so both can run
+ * simultaneously without colliding. Not a registered port; chosen for
+ * memorability + non-collision with the dev hub.
+ */
+export declare const DEFAULT_SERVE_PORT = 6781;
+/** Default bind host. Loopback only — matches `ggui dev`. */
+export declare const DEFAULT_SERVE_HOST = "127.0.0.1";
+export interface ParsedServeFlags {
+    /** Port to bind. Defaults to {@link DEFAULT_SERVE_PORT}. `0` = OS-assigned. */
+    port: number;
+    /** Host to bind. Defaults to {@link DEFAULT_SERVE_HOST}. */
+    host: string;
+    /**
+     * When true, boot MCP server only — skip agent supervision even
+     * if `ggui.json` has `agent.entry`. Operator opt-down per the
+     * §10.2a lock.
+     */
+    mcpOnly: boolean;
+    /**
+     * When true, switch the in-memory auth adapter to `devAllowAll: true`
+     * — every non-empty bearer (including the no-bearer probe MCP custom
+     * connectors send) authenticates as builder. Strictly a local-dev /
+     * tunnel-smoke escape hatch; production uses pairing or a custom
+     * `AuthAdapter`.
+     *
+     * NEVER expose a `--dev-allow-all` server to the open internet
+     * outside an ephemeral tunnel — the banner prints an unmissable
+     * warning when this flag is set.
+     */
+    devAllowAll: boolean;
+    /**
+     * Override the public base URL used to compose `mcpApps.renderBaseUrl`,
+     * `mcpApps.wsUrl`, and `runtime.url`. Without this, the URLs derive
+     * from `--host:--port`, which only resolves from the same machine.
+     * Set to a tunnel URL (`https://<random>.trycloudflare.com`) when
+     * testing against a remote MCP host so iframe-runtime + `/r/<code>`
+     * links resolve from the host's perspective.
+     *
+     * Trailing slash is stripped on parse. Must include scheme
+     * (`http://` or `https://`); the `wsUrl` is derived by replacing the
+     * scheme with `ws`/`wss`.
+     */
+    publicBaseUrl?: string;
+    /**
+     * When true, auto-spawn a cloudflared quick-tunnel pointed at the
+     * local listen port and treat the assigned URL as
+     * {@link publicBaseUrl}. Mutually exclusive with `--public-base-url`
+     * (operator gets EITHER explicit URL OR auto-tunnel).
+     *
+     * `--public + --dev-allow-all` combination is rejected at parse
+     * time unless `--i-know-its-public` is also set — exposing
+     * any-bearer auth to the open internet via cloudflared takes a
+     * deliberate flag.
+     */
+    publicAutoTunnel?: boolean;
+    /** Acknowledgement flag — see {@link publicAutoTunnel}. */
+    iKnowItsPublic?: boolean;
+    /**
+     * Mount the OAuth 2.1 + PKCE + Dynamic Client Registration routes
+     * required by MCP custom-connector hosts (claude.ai, ChatGPT) whose
+     * "Add connector" form has no field for a pre-shared bearer token.
+     *
+     * Flow when on:
+     *   1. Host hits `/mcp` without auth → 401 + WWW-Authenticate
+     *      pointing at `/.well-known/oauth-protected-resource`.
+     *   2. Host fetches discovery → finds `/oauth/authorize` +
+     *      `/oauth/token` + `/oauth/register`.
+     *   3. Host registers a client via DCR (no pre-shared secrets) +
+     *      redirects user-agent to `/oauth/authorize`.
+     *   4. Server renders a paste-key page; operator pastes the
+     *      paired bearer (from the landing page or `POST /pair`).
+     *   5. Server validates against the active `AuthAdapter`, mints
+     *      an authorization code, redirects back with `?code=...`.
+     *   6. Host exchanges code → access_token (= the paired bearer).
+     *   7. Subsequent `/mcp` calls authenticate normally.
+     *
+     * Without `--oauth`, OAuth-discovery clients bail with "couldn't
+     * reach MCP server" because the .well-known endpoints 404. Pure-
+     * bearer clients (Claude Desktop with bearer in config, console,
+     * etc.) keep working without it.
+     */
+    oauth: boolean;
+    /**
+     * When true, run a public-facing demo: every non-empty bearer
+     * authenticates as builder (same auth shape as {@link devAllowAll})
+     * but with three differences:
+     *
+     *   1. Banner copy is "PUBLIC DEMO" with a "operator pays for the
+     *      LLM" cost note, instead of the "DEV ALLOW-ALL" warning.
+     *   2. A per-remote-IP `FixedWindowRateLimiter` is bound to the
+     *      `ggui_push` handler so a single visitor can't burn the
+     *      operator's budget. Default: 30 push calls per 10 minutes per IP.
+     *   3. The pair-code beacon is suppressed (same as devAllowAll —
+     *      pair codes are meaningless under any-bearer-auth).
+     *
+     * Mutually exclusive with {@link devAllowAll}: both relax /mcp auth
+     * the same way, but they describe different operator intents and
+     * surface different banner copy. Using both at once is rejected at
+     * parse time so the banner stays truthful.
+     *
+     * Use case: a developer hosting a small ggui demo for an audience
+     * (Show HN, blog post, classroom) where unauthenticated end-users
+     * should be able to interact, paid for by the operator's single
+     * shared LLM key in `~/.ggui/credentials.json`.
+     */
+    publicDemo: boolean;
+    /**
+     * Multi-tenant posture. Switches the `/ggui/console/llm-keys` gate
+     * from admin-token to auth-adapter — each authenticated end-user
+     * manages their OWN provider keys (scope = `userId` for `kind:'user'`
+     * identities, `appId` for `kind:'app'`). `kind:'builder'` identities
+     * are rejected at the gate.
+     *
+     * Strict-auth shape — every bearer must clear the `AuthAdapter`.
+     * Mutually exclusive with {@link devAllowAll} and {@link publicDemo};
+     * those modes collapse every identity to `kind:'builder'` which the
+     * multi-tenant gate rejects, so the combination would produce a
+     * server that's wired multi-tenant but can't authenticate anyone.
+     *
+     * Use case: a single `ggui serve` instance fronting many users (a
+     * shared dev box, a small team server) where each user pastes their
+     * own LLM key via /settings using their paired bearer.
+     */
+    multiTenant: boolean;
+    /**
+     * Server-level MCP instructions preset (the string injected into
+     * the LLM's system prompt above the tool catalog). Operator-tunable
+     * advisory level for tool-use posture:
+     *
+     *   - `default`    — gentle "ggui first when UI fits, prose otherwise"
+     *   - `aggressive` — render anything with structure (no-preset default)
+     *   - `always`     — every response renders via ggui_push
+     *   - `minimal`    — server identity only, no behavioral nudge
+     *   - `off`        — omit the field entirely
+     *
+     * Surface = `--mcp-instructions <preset>` or
+     * `GGUI_MCP_INSTRUCTIONS=<preset>` env var (CLI flag wins).
+     * Custom strings can only be passed via programmatic embed
+     * (`createGguiServer({mcpInstructions: '...'})`).
+     */
+    mcpInstructions?: 'default' | 'aggressive' | 'always' | 'minimal' | 'off';
+    /**
+     * Skip auto-opening the operator's browser at the base URL after
+     * boot. Without this flag, `ggui serve` opens the local HTTP URL
+     * after the banner — server-side redirect routes first-run
+     * operators (no LLM creds) to the admin onboarding flow. Auto-open
+     * is also skipped for `--mcp-only` (no UI surface) and non-TTY
+     * sessions (CI, supervised, piped output).
+     *
+     * Surface = `--no-open` flag.
+     */
+    noOpen?: boolean;
+    /**
+     * Path to a JSON file backing the pairing service. When set, paired
+     * bearers survive a server restart — claude.ai stays connected
+     * across `ggui serve` runs.
+     *
+     * Stored in plaintext at the path with `0600` perms; assume the
+     * file lives on operator-controlled disk (e.g. `~/.ggui/keys.json`).
+     *
+     * Surface = `--keys-file <path>`.
+     */
+    keysFile?: string;
+    /**
+     * Disable the cross-restart persistence bundle. Without this flag,
+     * `ggui serve` reads or mints the HMAC secrets (and, in later
+     * slices, SessionStore + ShortCodeIndex + VectorStore + paired
+     * bearers) under `getPersistentDir(projectRoot)` so a server
+     * restart doesn't invalidate cached `_meta.ggui.bootstrap.token` +
+     * `/r/<code>?sig=&exp=` URLs — claude.ai chat-history revisits
+     * keep working.
+     *
+     * With `--ephemeral`, every restart mints fresh HMAC secrets (the
+     * legacy behavior). Use for tests / CI loops that don't want files
+     * written under `~/.ggui/` or the project root, and for incident-
+     * response nuclear-revoke scenarios.
+     *
+     * Surface = `--ephemeral`.
+     */
+    ephemeral?: boolean;
+    /**
+     * Operator-pinned admin bearer for the console `/keys` gate. Absent
+     * = the server mints a fresh `ggui_admin_*` per boot. Pin a value
+     * here when the operator wants the bearer to survive restarts (e.g.
+     * the same value lives in a password manager + an MCP-host config).
+     *
+     * Surface = `--admin-token <token>`.
+     */
+    adminToken?: string;
+    /** Populated when parsing failed; caller renders + bails with exit code 1. */
+    error?: string;
+}
+/**
+ * Parse the raw `ggui serve` argv tail. Returns a discriminated
+ * shape — `error` field is non-undefined on malformed input.
+ *
+ * Flag surface per the §10.2a lock:
+ *   - `--port <n>` / `--host <addr>`: bind target.
+ *   - `--mcp-only`: opt-down to MCP-only.
+ *   - `--all`: REJECTED with a pointer to the real default. See doc lock.
+ *   - `--help` / `-h`: help sentinel.
+ */
+export declare function parseServeFlags(args: readonly string[]): ParsedServeFlags;
+/**
+ * Resolved agent-component status for the banner + lifecycle. The
+ * CLI layer computes this from (flags, ggui.json state, resolution
+ * result) before calling {@link runServe}.
+ */
+export type AgentStatus = {
+    readonly kind: 'running';
+    /** Display-friendly entry path (relative to cwd is fine). */
+    readonly entry: string;
+    /** `js` → plain node; `ts` → node --import=tsx. */
+    readonly language: 'js' | 'ts';
+} | {
+    readonly kind: 'disabled';
+    readonly reason: AgentDisabledReason;
+};
+export type AgentDisabledReason = '--mcp-only' | 'no ggui.json' | 'ggui.json has no agent.entry';
+/**
+ * Shape the banner a `ggui serve` run prints AFTER the server is
+ * listening. Pure so tests can pin the exact copy.
+ *
+ * Honest about scope — the CLI now wires strict auth (any bearer that
+ * isn't pair-minted is rejected) and pre-mints an initial pair code
+ * via the `pairCode` field so the operator's first-run flow has a
+ * concrete starting point. The blueprint-read handler family is still
+ * what ships today; `pairCode` is optional for backward-compat with
+ * embedding hosts that opt out of pairing.
+ */
+export interface ServeBannerInputs {
+    /** The actual bound port. May differ from requested when `--port 0`. */
+    readonly port: number;
+    /** The actual bound host. */
+    readonly host: string;
+    /** Number of registered MCP tools. */
+    readonly toolCount: number;
+    /** Server name echoed in `info`. */
+    readonly serverName: string;
+    /** Server version echoed in `info`. */
+    readonly serverVersion: string;
+    /** Agent component status at banner time. */
+    readonly agent: AgentStatus;
+    /**
+     * Pre-minted initial pairing code, when the backend has pairing
+     * wired. `undefined` when pairing is disabled (future embedding
+     * hosts). Always present for `ggui serve` runs today.
+     */
+    readonly pairCode?: string;
+    /**
+     * Unix-millis expiry of {@link pairCode}. Present iff `pairCode`
+     * is present.
+     */
+    readonly pairCodeExpiresAt?: number;
+    /**
+     * When true, the auth section becomes a "DEV ALLOW-ALL" warning
+     * instead of the strict-auth blurb. Set by `--dev-allow-all`.
+     */
+    readonly devAllowAll?: boolean;
+    /**
+     * When true, the auth section becomes a "PUBLIC DEMO" warning with
+     * a cost-attribution + rate-limit note instead of the strict-auth
+     * blurb. Set by `--public-demo`. Mutually exclusive with
+     * `devAllowAll` at parse time; the banner asserts the same shape.
+     */
+    readonly publicDemo?: boolean;
+    /**
+     * When true, the auth section adds a "MULTI-TENANT" line below the
+     * strict-auth blurb explaining that each user manages their own LLM
+     * keys via /settings under their paired bearer. Set by
+     * `--multi-tenant`. Mutually exclusive with `devAllowAll` and
+     * `publicDemo` at parse time.
+     */
+    readonly multiTenant?: boolean;
+    /**
+     * Public base URL displayed under the local URLs when set via
+     * `--public-base-url`. Reminds the operator which URL their tunnel
+     * is forwarding to without grepping the agent-emitted shortCode
+     * URLs.
+     */
+    readonly publicBaseUrl?: string;
+    /**
+     * When true, the auth section advertises OAuth discovery so the
+     * operator can see at a glance that custom-connector hosts will
+     * be able to complete the auth dance. Absent → no extra line.
+     */
+    readonly oauth?: boolean;
+    /**
+     * Admin token printed prominently in the banner so operators can
+     * paste it into the console `/admin-login` page. Absent → no line
+     * (e.g. an embedded host with no console wired).
+     */
+    readonly adminToken?: string;
+    /**
+     * When true, the banner adds an action line pointing the operator at
+     * the console `/settings` page so they can paste an LLM key without
+     * touching env vars or restarting. Set when `describeGenerationBinding`
+     * returned null (no env var + no credentials-file entry).
+     */
+    readonly noLlmKey?: boolean;
+    /**
+     * Embedding model id surfaced for the local RAG layer. When set,
+     * the banner shows a `rag` line so operators see which model is
+     * wired (and that bge-small downloads lazily on first push). Absent
+     * when no embedding is wired (e.g. tests, programmatic embeds that
+     * fall back to MockEmbeddingProvider).
+     */
+    readonly embeddingModel?: string;
+}
+export declare function describeServeBanner(input: ServeBannerInputs): string[];
+/**
+ * Banner cell for the `agent` line. Pure — tests pin the copy.
+ */
+export declare function describeAgentStatus(status: AgentStatus): string;
+/**
+ * Minimal shape the CLI runner needs back from `@ggui-ai/mcp-server`.
+ * The real factory returns more (the Express app, plus lifecycle
+ * plumbing); we narrow here so tests can substitute without
+ * conjuring an `Express` instance or pulling node:http types into
+ * the pure module.
+ */
+export interface ServeBackend {
+    /** Bind and accept connections. Resolves to the bound port. */
+    listen(port: number, host: string): Promise<number>;
+    /** Close all connections. Idempotent. */
+    close(): Promise<void>;
+    /** Number of MCP tools registered on this server. */
+    readonly toolCount: number;
+    /** Server name echoed in `info`. */
+    readonly serverName: string;
+    /** Server version echoed in `info`. */
+    readonly serverVersion: string;
+    /**
+     * Count of primitive catalogs the backend composed from
+     * `ggui.json#primitives.{packages,local}`. Surfaced narrow (count
+     * only, not the catalog shape) so the test narrowing stays tight
+     * — integration tests that need the full shape compose
+     * `createGguiServer` directly.
+     */
+    readonly primitiveCatalogCount: number;
+    /**
+     * Which theme source backs `server.theme` — `'default'` when the
+     * CLI passed nothing (server fell back to the shipped
+     * `@ggui-ai/design` lightTheme), `'file'` when the operator's
+     * `ggui.json#theme = { file: ... }` resolved cleanly, `'preset'`
+     * when the operator selected one of the registered DTCG presets
+     * (`ggui.json#theme = "claudic"` shorthand or
+     * `{ preset: 'claudic', mode: 'dark', overrides: {...} }`). Tests
+     * use this to prove the thread-through without reaching into the
+     * `GguiServer` shape.
+     */
+    readonly themeSource: 'default' | 'file' | 'preset';
+    /**
+     * Composed pairing service, or `null` when the backend was built
+     * without pairing. `ggui serve`'s default bundle always wires
+     * pairing on; this field is nullable to keep the `ServeBackend`
+     * contract truthful for future embedding hosts that opt out.
+     *
+     * `runServe` uses this to pre-mint an initial pair code after bind
+     * (so a fresh operator's first-run flow doesn't need a pre-existing
+     * bearer to trigger `/admin/pair/init`). Tests substitute `null` to
+     * exercise the "no pre-mint" branch.
+     */
+    readonly pairingService: PairingService | null;
+    /**
+     * Admin bearer that gates the console `/keys` plane (mint / list /
+     * revoke + admin-login). Either the operator-supplied value (via
+     * `--admin-token`) or a fresh `ggui_admin_*` minted on boot when
+     * that flag is absent. `null` when the backend has no console wired
+     * — the CLI bundle always does, so this is non-null in practice.
+     *
+     * Surfaced narrow on the `ServeBackend` contract so `runServe` can
+     * banner-print it next to PAIR_CODE without reaching into the
+     * `GguiServer` shape.
+     */
+    readonly adminToken: string | null;
+    /**
+     * Embedding model id for the local RAG layer. Set when the backend
+     * wired `createLocalEmbeddingProvider` (CLI default — bge-small-en-
+     * v1.5). Absent when the backend fell back to `MockEmbeddingProvider`
+     * (programmatic embeds / test paths). Used by `describeServeBanner`
+     * to surface the RAG model in the boot banner so operators see
+     * what's wired.
+     */
+    readonly embeddingModel?: string;
+}
+/**
+ * Factory that constructs the backend. Injectable so tests can
+ * provide a deterministic fake without booting a real HTTP server.
+ * Production wiring in `cli.ts` passes a factory that composes
+ * `@ggui-ai/mcp-server`'s `createGguiServer` + the package's `info`.
+ */
+export type ServeBackendFactory = () => ServeBackend;
+/**
+ * Supervised-agent plumbing. Only populated when `runServe` has been
+ * asked to run the agent (i.e. `status.kind === 'running'`). `cli.ts`
+ * assembles this from `./agent-resolution.ts` + the loaded `ggui.json`.
+ */
+export interface ServeAgentSupervision {
+    readonly adapter: AgentRuntimeAdapter;
+    readonly startInput: AgentRuntimeStartInput;
+    /**
+     * Event sink — called for every `AgentRuntimeEvent` emitted by the
+     * adapter between start and stop. Production wires a logger;
+     * tests use a collector. Optional: omitting it silently discards
+     * the event stream (still valid for tests that only care about
+     * lifecycle, not logs).
+     */
+    readonly onEvent?: (event: AgentRuntimeEvent) => void;
+}
+/**
+ * Shape of the "await until shutdown" signal. Production uses an
+ * in-process SIGINT/SIGTERM listener; tests pass a manual AbortSignal
+ * to trigger a graceful close without raising real signals.
+ */
+export interface ServeShutdownSignal {
+    readonly aborted: boolean;
+    addEventListener(event: 'abort', handler: () => void, opts?: {
+        once?: boolean;
+    }): void;
+}
+export interface RunServeOptions {
+    /** Parsed flags. The `error` field must already be handled upstream. */
+    readonly flags: Readonly<Omit<ParsedServeFlags, 'error'>>;
+    /** Build the backend. Called once, after flag parsing. */
+    readonly backendFactory: ServeBackendFactory;
+    /**
+     * Agent supervision plumbing. Populated iff `agentStatus.kind ===
+     * 'running'`. When undefined, `runServe` skips supervision entirely.
+     */
+    readonly agent?: ServeAgentSupervision;
+    /** Pre-resolved banner status — `cli.ts` picks this per the fallback matrix. */
+    readonly agentStatus: AgentStatus;
+    /**
+     * When true, the boot banner emits a "/settings to set your LLM key"
+     * action line so first-run operators know how to recover from
+     * `ggui_push` returning codeReady:false. Set by `cli.ts` when the
+     * generation probe returned null (no env + no credentials-file).
+     */
+    readonly noLlmKey?: boolean;
+    /** Where to write the banner. */
+    readonly stdout: {
+        write(chunk: string): void;
+    };
+    /**
+     * Signal that resolves the serve loop. Production composes this
+     * from SIGINT + SIGTERM; tests abort it manually.
+     */
+    readonly shutdownSignal: ServeShutdownSignal;
+}
+/**
+ * Boot the backend, start the agent (if any), print the banner, then
+ * block until the shutdown signal fires. On signal, stops both
+ * components gracefully and resolves.
+ *
+ * Agent-crash policy (§10.2a lock): a crash AFTER boot surfaces as
+ * an `onEvent({type:'status', status:'crashed'})` delivery — the
+ * serve loop keeps MCP running and waits for shutdown. No auto-
+ * restart in v1. Operators compose restart policies via their own
+ * supervisor.
+ *
+ * MCP failure surfaces as a thrown error from `backendFactory()` /
+ * `backend.listen()` and propagates to `cli.ts` (exit 1).
+ *
+ * Pure enough to unit-test: the HTTP binding, signal wiring, and
+ * banner render are all either injected or pinned by
+ * {@link describeServeBanner} / {@link describeAgentStatus}.
+ */
+export declare function runServe(opts: RunServeOptions): Promise<number>;
+export declare const SERVE_HELP = "ggui serve \u2014 run the open self-hosted personal-mode app\n\nBoots the @ggui-ai/mcp-server binding with persistent defaults AND\n(by default) supervises your agent alongside it. The current MCP\nhandler surface is the blueprint-read family (search / list_featured\n/ render); more tools come online as @ggui-ai/mcp-server-handlers\ngrows.\n\nFirst-run bundle (all on by default):\n  - Landing page at /          \u2014 operator opens a browser and sees\n                                  server identity + pair-code card.\n  - Session viewer at /r/<code> \u2014 same-origin viewer for sessions\n                                  minted by ggui_push; same-origin\n                                  HTTP-only cookie authenticates the\n                                  live-channel /ws upgrade.\n  - POST /pair + POST /admin/pair/init \u2014 pairing endpoint for MCP\n                                  hosts and third-party clients.\n  - Live-channel /ws            \u2014 live session plane for MCP Apps\n                                  iframes and the console.\n\nEmbedding hosts that want a different shape (no landing page, no\npairing, programmatic control) should compose createGguiServer()\ndirectly in code rather than invoking `ggui serve`.\n\nUsage:\n  ggui serve [options]\n\nOptions:\n  --port <n>             Bind port (default: 6781, 0 = OS-assigned).\n  --host <addr>          Bind host (default: 127.0.0.1).\n  --mcp-only             Run just the MCP server; do not supervise an agent.\n  --dev-allow-all        Accept any non-empty bearer (incl. no bearer) as\n                         builder. Local-dev / tunnel smoke ONLY \u2014 never\n                         expose to the open internet.\n  --public-demo          Public-facing demo posture: same any-bearer auth\n                         as --dev-allow-all, plus per-IP rate limit on\n                         ggui_push (30 generations / 10 min) and a\n                         \"PUBLIC DEMO \u2014 operator pays\" banner. Mutually\n                         exclusive with --dev-allow-all.\n  --multi-tenant         Multi-tenant posture: switches the /settings LLM-\n                         keys gate from admin-token to auth-adapter so\n                         each authenticated end-user manages their OWN\n                         key plane (scope = userId/appId). kind:'builder'\n                         identities are rejected at the gate. Strict-auth\n                         only; mutually exclusive with --dev-allow-all\n                         and --public-demo. (Generation-time BYOK still\n                         resolves at the operator 'global' scope \u2014 a\n                         follow-up will thread per-user BYOK through\n                         ggui_push.)\n  --public-base-url <u>  Override the public base URL used to compose\n                         iframe-runtime + shortCode URLs. Set this to a\n                         tunnel URL (https://<random>.trycloudflare.com)\n                         when testing against a remote MCP host so URLs\n                         resolve from the host's perspective. Without\n                         this, URLs derive from --host:--port and only\n                         work from the same machine.\n  --oauth                Mount OAuth 2.1 + PKCE + Dynamic Client\n                         Registration routes (.well-known/oauth-* +\n                         /oauth/{authorize,token,register}). Required\n                         for MCP custom-connector hosts (claude.ai,\n                         ChatGPT) whose Add Connector form has no field\n                         for a pre-shared bearer; OAuth lets them do\n                         a discovery \u2192 DCR \u2192 consent dance ending in\n                         the same paired bearer the strict-auth flow\n                         already mints. Pure-bearer clients (Claude\n                         Desktop with bearer in config) work without it.\n  --admin-token <t>      Pin the admin bearer that gates the console\n                         /keys plane (list / mint / revoke pairings +\n                         /admin-login route). Without this, the server\n                         mints a fresh ggui_admin_* token per boot and\n                         prints it on the banner. Pin a stable value\n                         when you want the bearer to survive restarts\n                         (e.g. paste once into a password manager).\n  --ephemeral            Disable cross-restart persistence. Without\n                         this flag, the HMAC secrets that sign MCP\n                         Apps bootstrap tokens and signed render URLs\n                         are read or minted under .ggui/persistent/\n                         (project-local if a ggui.json was resolved,\n                         else ~/.ggui/persistent/) so cached tokens\n                         survive a server restart. Pass this flag to\n                         keep restarts ephemeral (tests / CI / nuclear-\n                         revoke). Override the dir via GGUI_PERSISTENT_DIR.\n  --help, -h             Show this help.\n\nAgent runtime:\n  The default boots your agent alongside MCP. The agent's entry file\n  comes from ggui.json:\n\n    { \"agent\": { \"entry\": \"./agent.ts\" } }\n\n  Supported extensions: .js / .mjs / .cjs (node), .ts / .tsx / .mts\n  (node --import=tsx). No ggui.json, or no agent.entry, falls back\n  to MCP-only with a warning. Malformed ggui.json or a bad entry\n  is a hard error.\n\n  Agent crashes after startup are logged; the MCP server keeps\n  running. No auto-restart \u2014 compose that with your own supervisor.\n\nPersistent storage (default-on; opt-out via --ephemeral):\n  By default `ggui serve` writes a small bundle under .ggui/persistent/\n  (project-local if a ggui.json was resolved, else ~/.ggui/persistent/)\n  so cached MCP Apps tokens, signed render URLs, shortCodes, sessions,\n  vectors, and paired bearers survive a restart \u2014 claude.ai chat-history\n  revisits keep working.\n\n  Bundle layout:\n\n    .ggui/persistent/\n      \u251C\u2500\u2500 bootstrap-secret.hex      (HMAC, 0600)\n      \u251C\u2500\u2500 render-signer-secret.hex  (HMAC, 0600)\n      \u251C\u2500\u2500 short-codes.sqlite        (/r/<code> + /api/bootstrap/<code> resolution)\n      \u251C\u2500\u2500 sessions.sqlite           (SessionStore \u2014 stack items + event history)\n      \u251C\u2500\u2500 vectors.sqlite            (RAG corpus)\n      \u2514\u2500\u2500 keys.json                 (paired bearers)\n\n  Override the dir with `GGUI_PERSISTENT_DIR`. Pass `--ephemeral` to\n  skip the bundle entirely (tests, CI loops, nuclear-revoke).\n\n  Explicit ggui.json#storage declarations always win \u2014 declare\n  `{ \"sessions\": { \"driver\": \"memory\" } }` to opt sessions back to\n  in-memory while keeping other surfaces persistent. Custom sqlite\n  paths via ggui.json#storage are honored verbatim:\n\n    {\n      \"storage\": {\n        \"sessions\": { \"driver\": \"sqlite\", \"path\": \"./ggui-sessions.sqlite\" },\n        \"vectors\":  { \"driver\": \"sqlite\", \"path\": \"./ggui-vectors.sqlite\" },\n        \"threads\":  { \"driver\": \"sqlite\", \"path\": \"./ggui-threads.sqlite\" }\n      }\n    }\n\n  Threads: the persistent-chat route family (/threads) is opt-in.\n  Absent `storage.threads` leaves the routes unmounted \u2014 pairs\n  with Portal's self-hosted origins only when declared. Driver\n  semantics:\n    - `driver: \"sqlite\"` \u2014 durable. Threads survive restart.\n      /ggui/health reports `threads.durability: \"durable\"`;\n      Portal hides its non-durable caveat.\n    - `driver: \"memory\"` \u2014 routes mount but data is lost on\n      restart. /ggui/health reports `threads.durability:\n      \"ephemeral\"`; Portal shows its caveat.\n\n  Paths resolve relative to the ggui.json directory. The sqlite\n  driver needs `better-sqlite3` installed in your project.\n\nRecommended setups:\n\n  Local-only smoke (no tunnel, no remote MCP host):\n    ggui serve\n\n  claude.ai custom connector (over a public tunnel):\n    1. Tunnel: cloudflared tunnel --url http://localhost:6781\n    2. ggui serve --oauth \\\n                  --public-base-url https://<tunnel>.trycloudflare.com\n    3. Note PAIR_CODE from boot. Visit the landing page (the public URL\n       above), complete pairing, save the bearer.\n    4. claude.ai \u2192 Settings \u2192 Connectors \u2192 Add custom connector.\n       URL: https://<tunnel>.trycloudflare.com/mcp\n       Client ID / Secret: leave empty (server uses Dynamic Client\n       Registration; no pre-shared secret needed).\n    5. Click Connect \u2192 claude.ai redirects you to a paste-key page.\n       Paste the bearer from step 3. Done.\n\n  Quick local-dev WITHOUT auth (NEVER over a public tunnel):\n    ggui serve --dev-allow-all\n\nCurrent limits:\n  - Strict-auth only: /mcp rejects any bearer that isn't pair-minted.\n    The CLI pre-mints one pairing code on boot (printed as\n    `PAIR_CODE <code>` and shown in the banner + on the landing\n    page). Complete `POST /pair {code, deviceName}` to receive a\n    bearer you can use with MCP. Embed @ggui-ai/mcp-server in your\n    own entrypoint to inject a different AuthAdapter (OIDC, Cognito,\n    etc.) for production.\n  - Single-tenant: every request scopes to one `builder` app id.\n";
+//# sourceMappingURL=serve-command.d.ts.map

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

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