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

package/dist/mcp-mount-discovery.js

@@ -0,0 +1,226 @@
+/**
+ * MCP mount discovery — turns a loaded `ggui.json#mcpMounts` list into
+ * a resolved, imported, factory-invoked set of mount payloads the
+ * OSS `ggui serve` path threads into
+ * `createGguiServer({ mcpMounts: ... })`.
+ *
+ * The flow per spec:
+ *
+ *   string (spec)
+ *     → resolve to absolute file path (relative → project root;
+ *       bare → Node module resolver)
+ *     → dynamic-import
+ *     → pick `createGguiMcpMount` or default export
+ *     → invoke (zero-arg; awaits Promise)
+ *     → structural validate `{ name: string; handlers: array }`
+ *
+ * This module is **type-thin**: it does NOT import `McpServerMount`
+ * from `@ggui-ai/mcp-server`, keeping `@ggui-ai/project-config`'s dep
+ * graph honest (no reverse dep from config → server). The CLI
+ * (`@ggui-ai/cli`), which already pulls `@ggui-ai/mcp-server`,
+ * narrows the returned `handlers: unknown[]` to the concrete
+ * `SharedHandler[]` at the adapter boundary. Down-layer collision
+ * checks + per-handler validation happen inside
+ * `composeHandlersWithMounts` when `createGguiServer` runs.
+ *
+ * ## Error model
+ *
+ * Non-throwing per source — one malformed mount does not black-hole
+ * the rest of the list. Every failure mode surfaces as an entry in
+ * `issues`, with the declared spec on `.path` so renderers can group
+ * issues by source. Callers that need fail-fast (`ggui serve` boot)
+ * inspect `result.issues` themselves and escalate to a fatal exit.
+ * Mirrors the blueprint / primitive discovery split.
+ *
+ * ## Factory contract lock
+ *
+ * The resolved module must export either:
+ *
+ *   - a named `createGguiMcpMount` function, OR
+ *   - a default export that is a function.
+ *
+ * Named export wins if both are present. The function receives zero
+ * arguments today; passing options is a future additive (widening the
+ * `ggui.json#mcpMounts` entry from `string` to `string | { module,
+ * options? }` and threading `options` through here).
+ *
+ * Mount factories are responsible for their own backing state —
+ * instantiating stores, seeding fixtures, wiring adapters — so the
+ * operator's config stays data-only. The factory may be `async`.
+ */
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * The export name callers should use on their mount module. A default
+ * export is also accepted when this named export is absent; the named
+ * form is preferred because it gives readers a visible symbol at the
+ * declaration site (`export function createGguiMcpMount() { ... }`).
+ */
+export const GGUI_MCP_MOUNT_FACTORY_EXPORT = 'createGguiMcpMount';
+/**
+ * Walk `ggui.json#mcpMounts` and produce resolved + invoked mount
+ * payloads. Non-throwing per source; each failure lands on `issues`.
+ *
+ * Ordering: `mounts` preserves declaration order (so collision errors
+ * inside `composeHandlersWithMounts` deterministically blame the
+ * later-declared duplicate). `issues` likewise preserves declaration
+ * order so CLI renderers can print "issue #1 first" if they want.
+ */
+export async function discoverMcpMounts(options) {
+    const { projectRoot, manifest } = options;
+    if (!isAbsolute(projectRoot)) {
+        throw new Error(`discoverMcpMounts: projectRoot must be absolute, got ${projectRoot}`);
+    }
+    const specs = manifest.mcpMounts;
+    const mounts = [];
+    const issues = [];
+    if (specs.length === 0)
+        return { mounts, issues };
+    const resolveModule = options.resolveModule ?? makeDefaultResolver(projectRoot);
+    const importModule = options.importModule ?? ((url) => import(url));
+    for (const spec of specs) {
+        let modulePath;
+        try {
+            modulePath = resolveModule(spec, projectRoot);
+        }
+        catch (cause) {
+            issues.push({
+                path: spec,
+                message: `Could not resolve mcpMounts entry "${spec}" — is the file present or the package installed? ` +
+                    `(${errorMessage(cause)})`,
+                cause,
+            });
+            continue;
+        }
+        let mod;
+        try {
+            mod = await importModule(pathToFileURL(modulePath).href);
+        }
+        catch (cause) {
+            issues.push({
+                path: spec,
+                message: `Failed to import mcpMounts entry "${spec}" (${modulePath}): ${errorMessage(cause)}`,
+                cause,
+            });
+            continue;
+        }
+        const factory = pickFactory(mod);
+        if (factory === null) {
+            issues.push({
+                path: spec,
+                message: `mcpMounts entry "${spec}" must export a \`${GGUI_MCP_MOUNT_FACTORY_EXPORT}\` function ` +
+                    `(or a default export that is a function) returning { name, handlers }. Got: ${describeModule(mod)}.`,
+            });
+            continue;
+        }
+        let payload;
+        try {
+            payload = await factory();
+        }
+        catch (cause) {
+            issues.push({
+                path: spec,
+                message: `mcpMounts entry "${spec}" factory threw during invocation: ${errorMessage(cause)}`,
+                cause,
+            });
+            continue;
+        }
+        const validated = validateMountShape(payload);
+        if (!validated.ok) {
+            issues.push({
+                path: spec,
+                message: `mcpMounts entry "${spec}" factory returned an unexpected shape: ${validated.message}`,
+            });
+            continue;
+        }
+        mounts.push({
+            spec,
+            modulePath,
+            mount: validated.mount,
+        });
+    }
+    return { mounts, issues };
+}
+// ─────────────────────────────────────────────────────────────────────
+// Internals
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Default resolver: relative paths resolve filesystem-wise against
+ * the project root (with an `existsSync` gate so a missing file
+ * produces a sharp error message, not a noisy `createRequire` trace);
+ * bare specifiers resolve through `createRequire` anchored at the
+ * project root.
+ */
+function makeDefaultResolver(projectRoot) {
+    // Anchor at `<projectRoot>/package.json` — same convention the
+    // primitive resolver uses. `createRequire` doesn't require the
+    // anchor file to exist; Node uses the path only to establish the
+    // ancestor `node_modules/` resolution chain.
+    const originUrl = pathToFileURL(join(projectRoot, 'package.json')).href;
+    const req = createRequire(originUrl);
+    return (spec) => {
+        if (spec.startsWith('./') || spec.startsWith('../') || isAbsolute(spec)) {
+            const resolved = resolve(projectRoot, spec);
+            if (!existsSync(resolved)) {
+                throw new Error(`relative mcpMounts path "${spec}" resolved to ${resolved}, which does not exist`);
+            }
+            return resolved;
+        }
+        return req.resolve(spec);
+    };
+}
+function pickFactory(mod) {
+    if (mod === null || typeof mod !== 'object')
+        return null;
+    const record = mod;
+    const named = record[GGUI_MCP_MOUNT_FACTORY_EXPORT];
+    if (typeof named === 'function') {
+        return named;
+    }
+    const dflt = record['default'];
+    if (typeof dflt === 'function') {
+        return dflt;
+    }
+    return null;
+}
+function validateMountShape(payload) {
+    if (payload === null || typeof payload !== 'object') {
+        return {
+            ok: false,
+            message: `expected an object shaped { name: string; handlers: [] }, got ${typeof payload}`,
+        };
+    }
+    const obj = payload;
+    const name = obj['name'];
+    if (typeof name !== 'string' || name.length === 0) {
+        return {
+            ok: false,
+            message: `\`name\` must be a non-empty string (used in collision-error messages + composition telemetry)`,
+        };
+    }
+    const handlers = obj['handlers'];
+    if (!Array.isArray(handlers)) {
+        return {
+            ok: false,
+            message: `\`handlers\` must be an array (received: ${typeof handlers})`,
+        };
+    }
+    return {
+        ok: true,
+        mount: {
+            name,
+            handlers: handlers,
+        },
+    };
+}
+function describeModule(mod) {
+    if (mod === null || typeof mod !== 'object')
+        return typeof mod;
+    const keys = Object.keys(mod);
+    return keys.length === 0 ? '(no exports)' : `exports: ${keys.join(', ')}`;
+}
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/node.d.ts

@@ -0,0 +1,69 @@
+import { GguiJsonV1 } from './schema.js';
+/** How many parent directories `findGguiJson` will walk by default. */
+export declare const DEFAULT_FIND_MAX_DEPTH = 8;
+/**
+ * Walk up from `startDir` (default: `process.cwd()`) looking for a
+ * `ggui.json`. Returns the absolute path to the first match, or
+ * `null` if no file is found within `maxDepth` levels.
+ *
+ * Stops when the filesystem root is reached, regardless of `maxDepth`.
+ * Never throws — a missing file is a valid result ("not in a ggui
+ * project"), not an error.
+ */
+export declare function findGguiJson(startDir?: string, maxDepth?: number): string | null;
+/**
+ * Error thrown when a `ggui.json` fails to load — missing file,
+ * malformed JSON, or schema validation failure. Wraps the underlying
+ * cause (`SyntaxError` / `ZodError`) on `.cause` so callers can
+ * inspect issue lists when they need to.
+ */
+export declare class GguiJsonLoadError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Read `ggui.json` at `path`, parse JSON, validate against the v1
+ * schema. Returns the fully-defaulted document.
+ *
+ * Throws {@link GguiJsonLoadError} if:
+ *   - the file does not exist,
+ *   - the file is not valid JSON,
+ *   - the document fails schema validation (cause set to `ZodError`).
+ */
+export declare function loadGguiJson(path: string): GguiJsonV1;
+/**
+ * Result of {@link safeLoadGguiJson} — mirrors `z.safeParse` so
+ * consumers can branch without try/catch.
+ */
+export type SafeLoadResult = {
+    success: true;
+    data: GguiJsonV1;
+} | {
+    success: false;
+    error: GguiJsonLoadError;
+};
+/**
+ * Non-throwing variant of {@link loadGguiJson}. Returns a
+ * discriminated result. Use this in CLI surfaces that render issue
+ * lists directly.
+ */
+export declare function safeLoadGguiJson(path: string): SafeLoadResult;
+/**
+ * Serialize and write a `ggui.json` document to `path`. The input is
+ * re-validated against the v1 schema before writing so a caller
+ * cannot accidentally persist a document that wouldn't round-trip
+ * through {@link loadGguiJson}.
+ *
+ * Output format: 2-space indent, trailing newline.
+ */
+export declare function saveGguiJson(path: string, doc: GguiJsonV1): void;
+export { GGUI_JSON_FILENAME, GguiJsonV1, parseGguiJson, safeParseGguiJson, } from './schema.js';
+export { discoverLocalUis, discoverFromGguiJsonPath, type DiscoveredUi, type DiscoveryIssue, type DiscoveryResult, type DiscoverOptions, } from './discovery.js';
+export { discoverPrimitives, discoverPrimitivesFromGguiJsonPath, type DiscoveredPrimitiveCatalog, type PrimitiveDiscoveryIssue, type PrimitiveDiscoveryResult, type DiscoverPrimitivesOptions, } from './primitive-discovery.js';
+export { discoverMcpMounts, GGUI_MCP_MOUNT_FACTORY_EXPORT, type DiscoveredMcpMount, type McpMountDiscoveryIssue, type McpMountDiscoveryResult, type DiscoverMcpMountsOptions, } from './mcp-mount-discovery.js';
+export { GGUI_PRIMITIVES_JSON_FILENAME, PrimitivesManifestV1, parsePrimitivesManifest, safeParsePrimitivesManifest, type PrimitivesManifest, } from './primitives-manifest.js';
+export { ThemeDocumentV1, parseThemeDocument, safeParseThemeDocument, type ThemeDocument, } from './theme.js';
+export { loadTheme, loadThemeFromGguiJsonPath, type LoadedTheme, type LoadThemeOptions, type LoadThemeResult, type ThemeLoadIssue, } from './theme-loader.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAqBA,OAAO,EAEL,UAAU,EAEX,MAAM,aAAa,CAAC;AAErB,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,GAAE,MAAsB,EAChC,QAAQ,GAAE,MAA+B,GACxC,MAAM,GAAG,IAAI,CAUf;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAoCrD;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACnC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAS7D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAGhE;AAMD,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAMrB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EACL,kBAAkB,EAClB,kCAAkC,EAClC,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EACL,iBAAiB,EACjB,6BAA6B,EAC7B,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,EACvB,2BAA2B,EAC3B,KAAK,kBAAkB,GACxB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACL,SAAS,EACT,yBAAyB,EACzB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAC"}

package/dist/node.js

@@ -0,0 +1,157 @@
+/**
+ * Node-only filesystem helpers for `ggui.json`.
+ *
+ * Lives on the `@ggui-ai/project-config/node` subpath (not the root
+ * barrel) because it imports `node:fs` / `node:path`. Pulling those
+ * builtins into the root barrel would break browser bundlers that
+ * resolve `@ggui-ai/project-config` directly (webpack refuses the
+ * `node:` scheme). The schema + parser in `./schema.ts` stay
+ * browser-safe and are re-exported both from here and from the root
+ * barrel.
+ *
+ * Intended callers:
+ *
+ * - Open `ggui` CLI (local dev / run / pair / serve / bench). Walks
+ *   upward from `process.cwd()` to find the project-root file.
+ * - Any hosting integration that reads the open manifest to
+ *   reconstitute an agent. Hosting layers treat `ggui.json` as
+ *   input-only; per-tenant overlay config lives outside this package.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { GGUI_JSON_FILENAME, parseGguiJson, } from './schema.js';
+/** How many parent directories `findGguiJson` will walk by default. */
+export const DEFAULT_FIND_MAX_DEPTH = 8;
+/**
+ * Walk up from `startDir` (default: `process.cwd()`) looking for a
+ * `ggui.json`. Returns the absolute path to the first match, or
+ * `null` if no file is found within `maxDepth` levels.
+ *
+ * Stops when the filesystem root is reached, regardless of `maxDepth`.
+ * Never throws — a missing file is a valid result ("not in a ggui
+ * project"), not an error.
+ */
+export function findGguiJson(startDir = process.cwd(), maxDepth = DEFAULT_FIND_MAX_DEPTH) {
+    let dir = resolve(startDir);
+    for (let i = 0; i <= maxDepth; i++) {
+        const candidate = join(dir, GGUI_JSON_FILENAME);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Error thrown when a `ggui.json` fails to load — missing file,
+ * malformed JSON, or schema validation failure. Wraps the underlying
+ * cause (`SyntaxError` / `ZodError`) on `.cause` so callers can
+ * inspect issue lists when they need to.
+ */
+export class GguiJsonLoadError extends Error {
+    path;
+    constructor(message, path, options) {
+        super(message, options);
+        this.name = 'GguiJsonLoadError';
+        this.path = path;
+    }
+}
+/**
+ * Read `ggui.json` at `path`, parse JSON, validate against the v1
+ * schema. Returns the fully-defaulted document.
+ *
+ * Throws {@link GguiJsonLoadError} if:
+ *   - the file does not exist,
+ *   - the file is not valid JSON,
+ *   - the document fails schema validation (cause set to `ZodError`).
+ */
+export function loadGguiJson(path) {
+    if (!existsSync(path)) {
+        throw new GguiJsonLoadError(`ggui.json not found at ${path}`, path);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch (cause) {
+        throw new GguiJsonLoadError(`Failed to read ggui.json at ${path}`, path, { cause });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new GguiJsonLoadError(`ggui.json at ${path} is not valid JSON`, path, { cause });
+    }
+    try {
+        return parseGguiJson(decoded);
+    }
+    catch (cause) {
+        throw new GguiJsonLoadError(`ggui.json at ${path} failed schema validation`, path, { cause });
+    }
+}
+/**
+ * Non-throwing variant of {@link loadGguiJson}. Returns a
+ * discriminated result. Use this in CLI surfaces that render issue
+ * lists directly.
+ */
+export function safeLoadGguiJson(path) {
+    try {
+        return { success: true, data: loadGguiJson(path) };
+    }
+    catch (error) {
+        if (error instanceof GguiJsonLoadError) {
+            return { success: false, error };
+        }
+        throw error;
+    }
+}
+/**
+ * Serialize and write a `ggui.json` document to `path`. The input is
+ * re-validated against the v1 schema before writing so a caller
+ * cannot accidentally persist a document that wouldn't round-trip
+ * through {@link loadGguiJson}.
+ *
+ * Output format: 2-space indent, trailing newline.
+ */
+export function saveGguiJson(path, doc) {
+    const validated = parseGguiJson(doc);
+    writeFileSync(path, JSON.stringify(validated, null, 2) + '\n', 'utf-8');
+}
+// Re-export schema + parser from the same subpath so Node callers
+// can do `import { parseGguiJson, loadGguiJson } from
+// '@ggui-ai/project-config/node'` without two imports. Browser callers
+// use the root barrel, which exports the browser-safe subset.
+export { GGUI_JSON_FILENAME, GguiJsonV1, parseGguiJson, safeParseGguiJson, } from './schema.js';
+// Filesystem-backed blueprint manifest discovery. Lives here (not the
+// browser-safe root barrel) because it imports `node:fs/promises` +
+// `tinyglobby`. Consumed by `@ggui-ai/dev-stack` (for the `ggui dev`
+// hub) and `@ggui-ai/mcp-server` (for `ggui serve` boot wiring).
+export { discoverLocalUis, discoverFromGguiJsonPath, } from './discovery.js';
+// Filesystem + Node-module-resolution backed primitive manifest
+// discovery. Symmetric with blueprint discovery above but resolves
+// npm specifiers through `createRequire` rather than glob-only.
+// Consumed by `@ggui-ai/mcp-server` at `ggui serve` boot to index
+// every primitive source declared in `ggui.json#primitives`.
+export { discoverPrimitives, discoverPrimitivesFromGguiJsonPath, } from './primitive-discovery.js';
+// Node-only resolution of `ggui.json#mcpMounts`. Dynamic-imports each
+// declared module, invokes its `createGguiMcpMount` factory, and
+// returns structurally-validated mount payloads. Consumed by
+// `@ggui-ai/cli` at `ggui serve` boot to thread operator-declared
+// tool bundles through `createGguiServer({ mcpMounts })`.
+export { discoverMcpMounts, GGUI_MCP_MOUNT_FACTORY_EXPORT, } from './mcp-mount-discovery.js';
+// Browser-safe primitive manifest schema + parsers re-exported here
+// too so Node callers get the full surface from one import path.
+export { GGUI_PRIMITIVES_JSON_FILENAME, PrimitivesManifestV1, parsePrimitivesManifest, safeParsePrimitivesManifest, } from './primitives-manifest.js';
+// Browser-safe theme document schema + parsers — re-exported on the
+// Node subpath so `ggui serve` / `ggui dev` get the full theme
+// surface from one import path. See `./theme.js` for the v1
+// plain-DTCG contract.
+export { ThemeDocumentV1, parseThemeDocument, safeParseThemeDocument, } from './theme.js';
+// Filesystem-backed theme loader — consumes `ggui.json#theme`,
+// resolves it against the project root, parses + validates, and
+// returns a `LoadedTheme` ready for the OSS `ggui serve` server.
+// Non-throwing per-file; the CLI escalates issues to fatal at boot.
+export { loadTheme, loadThemeFromGguiJsonPath, } from './theme-loader.js';

package/dist/primitive-discovery.d.ts

@@ -0,0 +1,95 @@
+import type { GguiJsonV1 } from './schema.js';
+import { type PrimitivesManifest } from './primitives-manifest.js';
+/**
+ * One discovered primitive catalog — the import specifier + absolute
+ * manifest path + the parsed manifest. Callers address by `import`;
+ * paths drive doc-file lookups and informational output.
+ */
+export interface DiscoveredPrimitiveCatalog {
+    /**
+     * Where the source came from. `'package'` = resolved through an
+     * npm specifier declared in `ggui.json#primitives.packages`;
+     * `'local'` = matched by a glob in `ggui.json#primitives.local`.
+     * Renderers may use this to annotate the catalog differently.
+     */
+    source: 'package' | 'local';
+    /**
+     * The specifier consumers import from (equal to `manifest.import`).
+     * Keyed separately from the manifest so callers don't have to
+     * reach into the nested shape for the common case.
+     */
+    import: string;
+    /** Absolute path to the discovered `ggui.primitives.json`. */
+    manifestPath: string;
+    /** Parsed manifest. */
+    manifest: PrimitivesManifest;
+}
+/**
+ * An error surfaced during discovery. Shape matches
+ * {@link DiscoveryIssue} from blueprint discovery so CLI renderers
+ * can treat both issue streams identically.
+ */
+export interface PrimitiveDiscoveryIssue {
+    /**
+     * Path or specifier of the offending source. For `packages`
+     * entries this is the declared npm specifier (not a filesystem
+     * path) since resolution may have failed before we could locate
+     * a file. For `local` entries this is a relative path under the
+     * project root.
+     */
+    path: string;
+    message: string;
+    /** Underlying cause (typically `ZodError`, `SyntaxError`, or the resolver error). */
+    cause?: unknown;
+}
+/** Result of a full primitive-discovery pass. */
+export interface PrimitiveDiscoveryResult {
+    /** Successfully parsed catalogs. Ordering: packages first (in declaration order),
+     *  then local (filesystem-walk order from tinyglobby). */
+    catalogs: DiscoveredPrimitiveCatalog[];
+    /** Issues that should be rendered to the user; discovery still returns. */
+    issues: PrimitiveDiscoveryIssue[];
+}
+/**
+ * Options for {@link discoverPrimitives}. `resolveModule` is exposed
+ * so tests can inject a fake resolver; real callers omit it and get
+ * the Node `createRequire` default anchored at `projectRoot`.
+ */
+export interface DiscoverPrimitivesOptions {
+    /**
+     * Absolute project root — the directory containing `ggui.json`.
+     * Globs in `primitives.local` resolve relative to this directory;
+     * npm specifiers in `primitives.packages` resolve through a
+     * `require` anchored here.
+     */
+    projectRoot: string;
+    /** The parsed `ggui.json`. Only `primitives.{packages,local}` is consumed. */
+    manifest: GguiJsonV1;
+    /**
+     * Hook for tests — given the declared specifier and the project
+     * root, return the absolute path to a representative file inside
+     * the package (any file that lets us walk UP to the enclosing
+     * `package.json`). Throw to signal "not resolvable". Production
+     * callers omit this; the default resolver uses `createRequire`
+     * against `<projectRoot>/package.json`.
+     */
+    resolveModule?: (specifier: string, projectRoot: string) => string;
+}
+/**
+ * Walk both `primitives.packages` and `primitives.local`, build the
+ * catalog, accumulate issues.
+ *
+ * Non-throwing per source. Duplicate-`import`-specifier across
+ * sources is an issue (first-seen wins, later ones accumulate as
+ * issues). A glob pattern that matches nothing is allowed — the
+ * manifest may exist ahead of primitives being authored; operators
+ * can still run `ggui dev` without the catalog being complete.
+ */
+export declare function discoverPrimitives(options: DiscoverPrimitivesOptions): Promise<PrimitiveDiscoveryResult>;
+/**
+ * Convenience wrapper for the common "I have a `ggui.json` path,
+ * give me the primitives" flow. Resolves the project root from the
+ * manifest path.
+ */
+export declare function discoverPrimitivesFromGguiJsonPath(manifestPath: string, manifest: GguiJsonV1, extra?: Omit<DiscoverPrimitivesOptions, 'projectRoot' | 'manifest'>): Promise<PrimitiveDiscoveryResult>;
+//# sourceMappingURL=primitive-discovery.d.ts.map

package/dist/primitive-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive-discovery.d.ts","sourceRoot":"","sources":["../src/primitive-discovery.ts"],"names":[],"mappings":"AAyDA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAElC;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,iDAAiD;AACjD,MAAM,WAAW,wBAAwB;IACvC;8DAC0D;IAC1D,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,2EAA2E;IAC3E,MAAM,EAAE,uBAAuB,EAAE,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,EAAE,UAAU,CAAC;IACrB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;CACpE;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA0HnC;AAED;;;;GAIG;AACH,wBAAsB,kCAAkC,CACtD,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,UAAU,EACpB,KAAK,GAAE,IAAI,CAAC,yBAAyB,EAAE,aAAa,GAAG,UAAU,CAAM,GACtE,OAAO,CAAC,wBAAwB,CAAC,CAGnC"}