@ggui-ai/project-config 0.1.0-rc.1

package/dist/schema.d.ts

@@ -0,0 +1,520 @@
+/**
+ * `ggui.json` v1 — the OSS `ggui` server's runtime source of truth.
+ *
+ * When a developer runs `ggui serve`, the OSS server reads this file
+ * to discover everything it needs: app identity, protocol version,
+ * blueprint manifests, primitive packages, theme tokens, declared
+ * adapter intent. The schema is framework-neutral — it describes
+ * *the ggui app*, never the internal orchestration of any specific
+ * agent runtime. LLM choice, system prompt, framework-specific tool
+ * inventory belong in each framework's own config, not here.
+ *
+ * The manifest surface model:
+ *
+ * - `ggui.json`     — this file. Open. Root manifest.
+ * - `ggui.ui.json`  — one per authored UI, colocated with source.
+ *                     Indexed via `blueprints.include` globs.
+ *
+ * **Rules for extending:**
+ *
+ * 1. **Additive only within `schema: '1'`.** Optional fields with
+ *    defaults are safe. New top-level fields MUST default to
+ *    behavioural no-ops so older tooling can ignore them.
+ * 2. **Framework-neutral.** If a field is meaningful only to one
+ *    agent framework (Claude SDK, Vercel AI SDK, LangGraph, ADK,
+ *    CrewAI, Mastra, etc.), it does NOT belong here. Same manifest
+ *    describes the same ggui app across all frameworks.
+ * 3. **Host-neutral.** Build / runtime / deploy / sizing fields live
+ *    in a hosting-vendor overlay, never here.
+ * 4. **No vendor names in enum values.** `residency: 'acme-cloud'`
+ *    is the exact mistake a previous draft made. If an enum needs
+ *    to name a hosting provider, it belongs in that provider's
+ *    overlay.
+ *
+ * **Strictness (locked 2026-04-18):**
+ *
+ * Root object is strict — unknown top-level keys cause parse to
+ * fail. This catches typos (`"blueprint"` singular, `"component"`
+ * for `"primitives"`, etc.) and prevents silent drift toward the
+ * agent-runtime-centric shape we explicitly rejected. Nested
+ * objects are also strict for v1; additive fields are a coordinated
+ * schema change, not a drive-by.
+ */
+import { z } from 'zod';
+/**
+ * Operator identity — who's running this server. Surfaced on the
+ * public welcome page at `/` so visitors see "operated by X" instead
+ * of unbranded server chrome.
+ *
+ * **Privacy-first by default.** Every field is optional. Nothing is
+ * shown when nothing is set — no "anonymous" placeholder, no
+ * hostname-derived fallback. The visitor sees just server identity
+ * and public-surface affordances (login link, share-link hints).
+ *
+ * Distinct from `app` (which identifies the *server*) — `operator`
+ * identifies the *human/entity* running the server. A single
+ * operator can run multiple `app`s, but the welcome page always
+ * shows ONE operator block (one server = one ggui.json).
+ *
+ * **What this is NOT:**
+ *   - Not auth (the admin token is its own credential)
+ *   - Not telemetry (server doesn't phone home with operator info)
+ *   - Not user/builder identity (those are MCP-pairing concerns)
+ */
+declare const OperatorSchema: z.ZodObject<{
+    /** Display name shown on the welcome page. e.g. "Wanseob Lim" or
+     * "Loqu Inc.". Free-form — no slug constraint. */
+    name: z.ZodOptional<z.ZodString>;
+    /** Operator's homepage / brand URL. Linkified on the welcome page
+     * if set. Must be a valid http(s) URL. */
+    url: z.ZodOptional<z.ZodURL>;
+    /** One-line description shown under the operator name. e.g.
+     * "personal ggui server — tinkering only" or "Loqu's hosted ggui
+     * for friends + family". Plain text, no markup. */
+    tagline: z.ZodOptional<z.ZodString>;
+    /** mailto-eligible contact address. Linkified as `mailto:` on the
+     * welcome page if set. Operators uncomfortable putting this on a
+     * public page should leave it unset — `name` and `url` carry the
+     * "how to reach me" load just as well. */
+    contact: z.ZodOptional<z.ZodEmail>;
+}, z.core.$strict>;
+/** Public type alias for the operator block. */
+export type OperatorConfig = z.infer<typeof OperatorSchema>;
+/**
+ * Discriminated theme selection. Three accepted shapes:
+ *
+ *   1. `string` — preset id shorthand (`theme: 'claudic'` ≡
+ *      `theme: { preset: 'claudic' }`)
+ *   2. `{ preset, mode?, overrides? }` — registered preset with
+ *      optional mode + override layer
+ *   3. `{ file, mode? }` — DTCG JSON file
+ *
+ * Strict objects on shapes 2 and 3 reject unknown keys to catch
+ * typos at parse (`{ presset: 'claudic' }` fails, not silently
+ * loads default).
+ */
+export declare const ThemeConfigSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    preset: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+    }>>;
+    overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    file: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+    }>>;
+}, z.core.$strict>]>;
+/**
+ * Discriminated union over storage drivers. Add new drivers as
+ * additive siblings under the same discriminator — never widen an
+ * existing variant, since that would silently change what older
+ * manifests mean.
+ */
+declare const StorageSurfaceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    driver: z.ZodLiteral<"memory">;
+}, z.core.$strict>, z.ZodObject<{
+    driver: z.ZodLiteral<"sqlite">;
+    /** Filesystem path to the SQLite database file. Relative paths
+     * resolve from the ggui.json directory at adapter-instantiation
+     * time. Empty strings are rejected at parse. */
+    path: z.ZodString;
+}, z.core.$strict>], "driver">;
+declare const StorageSchema: z.ZodObject<{
+    /** Session persistence (events + stack + identity). Absent =
+     * in-memory (sessions reset on restart). */
+    sessions: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        driver: z.ZodLiteral<"memory">;
+    }, z.core.$strict>, z.ZodObject<{
+        driver: z.ZodLiteral<"sqlite">;
+        /** Filesystem path to the SQLite database file. Relative paths
+         * resolve from the ggui.json directory at adapter-instantiation
+         * time. Empty strings are rejected at parse. */
+        path: z.ZodString;
+    }, z.core.$strict>], "driver">>;
+    /** Vector index persistence (RAG, blueprint embeddings). Absent =
+     * in-memory (index rebuilds on restart). */
+    vectors: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        driver: z.ZodLiteral<"memory">;
+    }, z.core.$strict>, z.ZodObject<{
+        driver: z.ZodLiteral<"sqlite">;
+        /** Filesystem path to the SQLite database file. Relative paths
+         * resolve from the ggui.json directory at adapter-instantiation
+         * time. Empty strings are rejected at parse. */
+        path: z.ZodString;
+    }, z.core.$strict>], "driver">>;
+    /** Persistent-chat thread + message persistence. Absent = in-memory
+     * (threads vanish on restart — correct for dev, unsafe for any
+     * deployment Portal's self-hosted flow talks to). Pair with
+     * `driver: 'sqlite'` + a `path` for durable local storage; the
+     * `@ggui-ai/mcp-server-core/sqlite#SqliteThreadStore` reference
+     * impl consumes the same file-per-surface layout the sessions/
+     * vectors drivers already use. */
+    threads: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        driver: z.ZodLiteral<"memory">;
+    }, z.core.$strict>, z.ZodObject<{
+        driver: z.ZodLiteral<"sqlite">;
+        /** Filesystem path to the SQLite database file. Relative paths
+         * resolve from the ggui.json directory at adapter-instantiation
+         * time. Empty strings are rejected at parse. */
+        path: z.ZodString;
+    }, z.core.$strict>], "driver">>;
+}, z.core.$strict>;
+/**
+ * Public type alias for one storage surface's config (sessions or
+ * vectors). Callers instantiating adapters from a parsed manifest
+ * pattern-match on `driver`.
+ */
+export type StorageSurfaceConfig = z.infer<typeof StorageSurfaceSchema>;
+/** Public type alias for the full storage block. */
+export type StorageConfig = z.infer<typeof StorageSchema>;
+/**
+ * Public type alias for the resolved theme selection (post-parse).
+ *
+ * `theme` in `ggui.json` accepts a string shorthand, a preset
+ * config object, or a file config object. Consumers reading a
+ * parsed `GguiJsonV1` pattern-match on shape (`typeof === 'string'`,
+ * `'preset' in value`, `'file' in value`).
+ */
+export type ThemeConfig = z.infer<typeof ThemeConfigSchema>;
+/**
+ * The authoritative v1 schema. `z.infer<typeof GguiJsonV1>` yields
+ * the static TypeScript type. A valid document round-trips cleanly:
+ * parse → `JSON.stringify` → re-parse produces an equivalent value.
+ *
+ * **Required fields:** `schema`, `protocol`, `app`.
+ * **Optional fields with defaults:** `blueprints`, `primitives`,
+ * `adapters`. A zero-config `ggui.json` is just the three required
+ * fields — the OSS server boots with defaults for everything else.
+ * **Optional without default:** `theme` (absent = shipped default
+ * tokens), `agent` (absent = `ggui serve` runs MCP-only).
+ *
+ * **Strict root:** unknown top-level keys are rejected.
+ */
+export declare const GguiJsonV1: z.ZodObject<{
+    /** File-format version — always `"1"` for v1. Distinct from
+     * `protocol` (which versions the wire contract the app speaks). */
+    schema: z.ZodLiteral<"1">;
+    /** ggui wire protocol version the app speaks. */
+    protocol: z.ZodString;
+    /** App identity. */
+    app: z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+        /**
+         * Per-app gadget catalog. The CLI
+         * passes these through to `InMemoryAppMetadataStore` so the
+         * handshake / push / ops handlers can validate every
+         * `clientCapabilities.gadgets[*]` ref against the registered
+         * set's package identity + export names. Each entry is a gadget
+         * PACKAGE and MUST satisfy the strict
+         * `strictGadgetDescriptorSchema` from `@ggui-ai/protocol`
+         * (a non-empty `exports[]` array, each export carrying required
+         * description / usage / example).
+         *
+         * Omitting this field falls back to the protocol's
+         * `STDLIB_GADGETS` defaults (the 7 first-party hooks).
+         * Declared 3rd-party wrappers (Leaflet, Mapbox, Stripe, …) land
+         * here.
+         */
+        gadgets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            exports: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                description: z.ZodString;
+                usage: z.ZodString;
+                example: z.ZodType<import("@ggui-ai/protocol").JsonValue, unknown, z.core.$ZodTypeInternals<import("@ggui-ai/protocol").JsonValue, unknown>>;
+                permission: z.ZodOptional<z.ZodEnum<{
+                    camera: "camera";
+                    "clipboard-read": "clipboard-read";
+                    "clipboard-write": "clipboard-write";
+                    geolocation: "geolocation";
+                    microphone: "microphone";
+                    notifications: "notifications";
+                    "persistent-storage": "persistent-storage";
+                    midi: "midi";
+                    "speaker-selection": "speaker-selection";
+                    "storage-access": "storage-access";
+                    "background-sync": "background-sync";
+                    accelerometer: "accelerometer";
+                    gyroscope: "gyroscope";
+                    magnetometer: "magnetometer";
+                    "ambient-light-sensor": "ambient-light-sensor";
+                    "screen-wake-lock": "screen-wake-lock";
+                }>>;
+                gotchas: z.ZodOptional<z.ZodString>;
+                required: z.ZodOptional<z.ZodBoolean>;
+                hook: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                description: z.ZodString;
+                usage: z.ZodString;
+                example: z.ZodType<import("@ggui-ai/protocol").JsonValue, unknown, z.core.$ZodTypeInternals<import("@ggui-ai/protocol").JsonValue, unknown>>;
+                permission: z.ZodOptional<z.ZodEnum<{
+                    camera: "camera";
+                    "clipboard-read": "clipboard-read";
+                    "clipboard-write": "clipboard-write";
+                    geolocation: "geolocation";
+                    microphone: "microphone";
+                    notifications: "notifications";
+                    "persistent-storage": "persistent-storage";
+                    midi: "midi";
+                    "speaker-selection": "speaker-selection";
+                    "storage-access": "storage-access";
+                    "background-sync": "background-sync";
+                    accelerometer: "accelerometer";
+                    gyroscope: "gyroscope";
+                    magnetometer: "magnetometer";
+                    "ambient-light-sensor": "ambient-light-sensor";
+                    "screen-wake-lock": "screen-wake-lock";
+                }>>;
+                gotchas: z.ZodOptional<z.ZodString>;
+                required: z.ZodOptional<z.ZodBoolean>;
+                component: z.ZodString;
+            }, z.core.$strict>]>>;
+            version: z.ZodString;
+            package: z.ZodString;
+            bundleUrl: z.ZodOptional<z.ZodURL>;
+            bundleHost: z.ZodOptional<z.ZodString>;
+            bundleSri: z.ZodOptional<z.ZodString>;
+            styleUrl: z.ZodOptional<z.ZodURL>;
+            connect: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodURL>>>;
+            requires: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            typesUrl: z.ZodOptional<z.ZodURL>;
+            typesSri: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        /**
+         * Public env channel. Operator-stamped key→value map that
+         * the server projects (filtered to declared wrappers' `requires`)
+         * onto `globalThis.__ggui__.publicEnv` so wrapper hooks can read
+         * values via `getPublicEnv(key)`.
+         *
+         * Keys MUST match `GGUI_PUBLIC_APP_[A-Z0-9_]+` — the `GGUI_PUBLIC_USER_`
+         * namespace is reserved for a future per-user channel. Values are
+         * arbitrary strings; the server projects only keys whose values are
+         * declared in some registered wrapper's `requires`. Operators who
+         * declare a key without a value can use the empty string (the
+         * Mapbox SDK will surface "Invalid token" on first request rather
+         * than a missing-key error from the push gate).
+         *
+         * Omitting this field is equivalent to `{}` — wrappers without
+         * `requires` work unchanged; wrappers that declare `requires` will
+         * fail at push-gate validation if their required keys are missing.
+         */
+        publicEnv: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        /**
+         * MCP-Apps presentation mode (canvas slice). `'canvas'` makes
+         * `ggui_new_session` mint a session-scoped iframe
+         * (`ui://ggui/session/<sessionId>`) and route subsequent pushes
+         * through the session WebSocket channel instead of returning a
+         * per-push `ui://ggui/render/<shortCode>` resource. `'inline'`
+         * (default when omitted) preserves the per-push iframe behavior
+         * that flagship MCP-Apps hosts already expect.
+         */
+        defaultMcpAppsMode: z.ZodOptional<z.ZodEnum<{
+            inline: "inline";
+            canvas: "canvas";
+        }>>;
+    }, z.core.$strict>;
+    /** Operator identity — who's running this server. Optional;
+     * surfaced on the public welcome page at `/` when set. Privacy-
+     * first: nothing renders when nothing is set, no "anonymous"
+     * placeholder. See {@link OperatorConfig}. */
+    operator: z.ZodOptional<z.ZodObject<{
+        /** Display name shown on the welcome page. e.g. "Wanseob Lim" or
+         * "Loqu Inc.". Free-form — no slug constraint. */
+        name: z.ZodOptional<z.ZodString>;
+        /** Operator's homepage / brand URL. Linkified on the welcome page
+         * if set. Must be a valid http(s) URL. */
+        url: z.ZodOptional<z.ZodURL>;
+        /** One-line description shown under the operator name. e.g.
+         * "personal ggui server — tinkering only" or "Loqu's hosted ggui
+         * for friends + family". Plain text, no markup. */
+        tagline: z.ZodOptional<z.ZodString>;
+        /** mailto-eligible contact address. Linkified as `mailto:` on the
+         * welcome page if set. Operators uncomfortable putting this on a
+         * public page should leave it unset — `name` and `url` carry the
+         * "how to reach me" load just as well. */
+        contact: z.ZodOptional<z.ZodEmail>;
+    }, z.core.$strict>>;
+    /** Blueprint discovery. Defaults to no custom UIs declared. */
+    blueprints: z.ZodDefault<z.ZodObject<{
+        /** Glob patterns relative to the `ggui.json` directory. Each match
+         * should resolve to a `ggui.ui.json` file. */
+        include: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    /** Primitive discovery. Defaults to the shipped
+     * `@ggui-ai/design/primitives` package + no local primitives. */
+    primitives: z.ZodDefault<z.ZodObject<{
+        packages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        local: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    /**
+     * Theme selection. Three accepted shapes:
+     *
+     * - **Shorthand string** — `theme: "claudic"`. Picks a preset from
+     *   the `@ggui-ai/design` registry. Default mode is `'light'`.
+     * - **Preset object** — `theme: { preset: "claudic", mode: "dark",
+     *   overrides: { "color.primary.500": "#cc785c" } }`. Picks a
+     *   registered preset, optional explicit mode, optional flat
+     *   dot-path token overrides applied on top of the preset's
+     *   tokens before CSS emission.
+     * - **File object** — `theme: { file: "./theme.json", mode: "dark" }`.
+     *   Loads tokens from a project-relative DTCG JSON file. The
+     *   `mode` is metadata only — the file's tokens are the resolved
+     *   theme; mode propagates to consumers that vary based on it
+     *   (e.g. `color-scheme: dark` injection).
+     *
+     * Absent (`theme: undefined`) means use the shipped default tokens
+     * from `@ggui-ai/design` (currently `lightTheme`).
+     */
+    theme: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        preset: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+        }>>;
+        overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        file: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+        }>>;
+    }, z.core.$strict>]>>;
+    /** Agent-runtime config for `ggui serve`. Absent means the
+     * command boots MCP-only (no agent loop attached). */
+    agent: z.ZodOptional<z.ZodObject<{
+        /** Path to the agent's entry file, relative to the ggui.json
+         * directory. Supported extensions: .js, .mjs, .cjs, .ts, .tsx,
+         * .mts. Validation of extension happens at `ggui serve` time —
+         * the schema stays permissive so malformed entries surface with
+         * the CLI's error message (which can list supported extensions +
+         * remediation), not a zod issue trace. */
+        entry: z.ZodString;
+    }, z.core.$strict>>;
+    /** Explicit storage adapter declarations. Absent means every
+     * persistence surface stays in-memory (the zero-config OSS
+     * default). Present means the operator has opted in per surface
+     * — no surface silently creates a file on disk. See
+     * {@link StorageConfig}. */
+    storage: z.ZodOptional<z.ZodObject<{
+        /** Session persistence (events + stack + identity). Absent =
+         * in-memory (sessions reset on restart). */
+        sessions: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            driver: z.ZodLiteral<"memory">;
+        }, z.core.$strict>, z.ZodObject<{
+            driver: z.ZodLiteral<"sqlite">;
+            /** Filesystem path to the SQLite database file. Relative paths
+             * resolve from the ggui.json directory at adapter-instantiation
+             * time. Empty strings are rejected at parse. */
+            path: z.ZodString;
+        }, z.core.$strict>], "driver">>;
+        /** Vector index persistence (RAG, blueprint embeddings). Absent =
+         * in-memory (index rebuilds on restart). */
+        vectors: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            driver: z.ZodLiteral<"memory">;
+        }, z.core.$strict>, z.ZodObject<{
+            driver: z.ZodLiteral<"sqlite">;
+            /** Filesystem path to the SQLite database file. Relative paths
+             * resolve from the ggui.json directory at adapter-instantiation
+             * time. Empty strings are rejected at parse. */
+            path: z.ZodString;
+        }, z.core.$strict>], "driver">>;
+        /** Persistent-chat thread + message persistence. Absent = in-memory
+         * (threads vanish on restart — correct for dev, unsafe for any
+         * deployment Portal's self-hosted flow talks to). Pair with
+         * `driver: 'sqlite'` + a `path` for durable local storage; the
+         * `@ggui-ai/mcp-server-core/sqlite#SqliteThreadStore` reference
+         * impl consumes the same file-per-surface layout the sessions/
+         * vectors drivers already use. */
+        threads: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            driver: z.ZodLiteral<"memory">;
+        }, z.core.$strict>, z.ZodObject<{
+            driver: z.ZodLiteral<"sqlite">;
+            /** Filesystem path to the SQLite database file. Relative paths
+             * resolve from the ggui.json directory at adapter-instantiation
+             * time. Empty strings are rejected at parse. */
+            path: z.ZodString;
+        }, z.core.$strict>], "driver">>;
+    }, z.core.$strict>>;
+    /**
+     * Default plugin-registry URL for this app.
+     *
+     * When the user runs `ggui install <scope/name@version>` or `ggui
+     * publish` from this project, the CLI resolves the target registry
+     * via a three-layer chain (highest priority wins):
+     *
+     *   1. Explicit `--registry=<url>` flag passed to the CLI.
+     *   2. `GGUI_REGISTRY` environment variable.
+     *   3. This `registry` field in `ggui.json`.
+     *   4. (none → error) The CLI ships with NO hard-coded default;
+     *      operators MUST pick a registry per app.
+     *
+     * Mirrors the npm `--registry` / `npm_config_registry` / `.npmrc`
+     * resolution pattern but anchored on `ggui.json` for the project-
+     * local layer (instead of a dotfile) — the same file that holds
+     * `app.gadgets` is the natural place to declare which
+     * marketplace those libraries come from.
+     *
+     * Validated as a URL at schema-parse time; the CLI does not
+     * second-guess scheme / host beyond URL-shape (HTTPS recommendation
+     * is enforced at install-time, not here, so dev fixtures pointing
+     * at `http://localhost:<port>` parse cleanly).
+     *
+     * Absent = no project-local default; the CLI falls through to env
+     * var or flag, and errors if neither is set.
+     */
+    registry: z.ZodOptional<z.ZodURL>;
+    /**
+     * Local MCP tool mounts — the operator-facing seam for declaring
+     * additional tool surfaces that aggregate onto `/mcp` alongside
+     * ggui-native tools (`ggui_push`, etc.). Each entry is a module
+     * specifier:
+     *
+     *   - Relative paths (`./path/to/mount.js`, `../local/mcp.mjs`)
+     *     resolve against the directory containing `ggui.json`. Must
+     *     include the file extension — we do not guess `.js` vs
+     *     `.mjs`. File must exist.
+     *   - Bare npm specifiers (`@my-org/mcp-mount`, `some-pkg/entry`)
+     *     resolve through Node's module resolver anchored at the
+     *     project root.
+     *
+     * Each resolved module must export a `createGguiMcpMount` function
+     * (or a default export) returning `{ name: string; handlers:
+     * SharedHandler[] }` — i.e., an `McpServerMount` from
+     * `@ggui-ai/mcp-server`. The factory owns its own state (backing
+     * store, seed, etc.). Zero-argument today; arguments are a future
+     * additive (widen the entry to `string | { module, options? }`).
+     *
+     * Default: `[]` (no mounts). Collisions between mount tool names
+     * and ggui-native tool names (or between two mounts) are rejected
+     * at `createGguiServer` composition time, not silently — see
+     * `packages/mcp-server/src/mcp-mounts.ts::composeHandlersWithMounts`. */
+    mcpMounts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** Static TypeScript type derived from the v1 schema. */
+export type GguiJsonV1 = z.infer<typeof GguiJsonV1>;
+/**
+ * Canonical filename — always at the project root, always this
+ * name. Exported so tooling uses the constant instead of
+ * hard-coding the string.
+ */
+export declare const GGUI_JSON_FILENAME = "ggui.json";
+/**
+ * Parse a raw JSON value into a validated {@link GguiJsonV1}.
+ * Throws a `ZodError` with human-readable issues on invalid input.
+ *
+ * Accepts any `unknown` — callers are expected to have already
+ * decoded the JSON (`JSON.parse(source)`). Applies defaults for
+ * absent optional fields.
+ */
+export declare function parseGguiJson(raw: unknown): GguiJsonV1;
+/**
+ * Safe-parse variant — returns a discriminated `z.safeParse` result
+ * (`{ success: true, data }` vs `{ success: false, error }`). Prefer
+ * this inside CLI tooling where you want to render the issue list
+ * without try/catch.
+ */
+export declare function safeParseGguiJson(raw: unknown): ReturnType<typeof GguiJsonV1.safeParse>;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyGxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,QAAA,MAAM,cAAc;IAClB;sDACkD;;IAElD;8CAC0C;;IAI1C;;uDAEmD;;IAEnD;;;8CAG0C;;kBAI1C,CAAC;AAEH,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AA+H5D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;oBAI5B,CAAC;AAqEH;;;;;GAKG;AACH,QAAA,MAAM,oBAAoB;;;;IAZxB;;oDAEgD;;8BAahD,CAAC;AAEH,QAAA,MAAM,aAAa;IACjB;gDAC4C;;;;;QAnB5C;;wDAEgD;;;IAmBhD;gDAC4C;;;;;QAtB5C;;wDAEgD;;;IAsBhD;;;;;;sCAMkC;;;;;QA9BlC;;wDAEgD;;;kBA8BhD,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;IACrB;uEACmE;;IAOnE,iDAAiD;;IAKjD,oBAAoB;;;;QA9XpB;;;;;;;;;;;;;;;WAeG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAIH;;;;;;;;;;;;;;;;;WAiBG;;QAEH;;;;;;;;WAQG;;;;;;IAqVH;;;kDAG8C;;QA/T9C;0DACkD;;QAElD;kDAC0C;;QAI1C;;2DAEmD;;QAEnD;;;kDAG0C;;;IAqT1C,+DAA+D;;QAhS/D;sDAC8C;;;IAoS9C;qEACiE;;;;;IAQjE;;;;;;;;;;;;;;;;;;OAkBG;;;;;;;;;;;;;;;IAKH;0DACsD;;QAhRtD;;;;;kDAK0C;;;IAgR1C;;;;gCAI4B;;QA5H5B;oDAC4C;;;;;YAnB5C;;4DAEgD;;;QAmBhD;oDAC4C;;;;;YAtB5C;;4DAEgD;;;QAsBhD;;;;;;0CAMkC;;;;;YA9BlC;;4DAEgD;;;;IAiJhD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;IAQH;;;;;;;;;;;;;;;;;;;;;;;;6EAwByE;;kBASzE,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,UAAU,CAAC,SAAS,CAAC,CAEzC"}