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

package/dist/primitive-discovery.js

@@ -0,0 +1,281 @@
+/**
+ * Primitive manifest discovery — turns a loaded `ggui.json` into the
+ * set of primitive catalogs the project declares via
+ * `primitives.packages` (npm specifiers) and `primitives.local`
+ * (globs).
+ *
+ * The flow:
+ *
+ *   ggui.json.primitives.packages (npm specifiers)
+ *     → resolve each spec through Node's module resolution
+ *     → walk up to the enclosing `package.json`
+ *     → read `ggui.primitives.json` alongside it
+ *     → parse via {@link parsePrimitivesManifest}
+ *
+ *   ggui.json.primitives.local (globs relative to project root)
+ *     → filesystem match (tinyglobby, same options as blueprint
+ *       discovery)
+ *     → filter to basename === `ggui.primitives.json`
+ *     → parse via {@link parsePrimitivesManifest}
+ *
+ * For npm specifiers, the resolver walks UP from the resolved subpath
+ * file to find the enclosing `package.json` — this avoids requiring
+ * packages to add `ggui.primitives.json` to their `exports` block and
+ * matches the intuition that "the manifest lives at the package root".
+ *
+ * ## Error model
+ *
+ * Discovery never throws on a per-source failure. One malformed
+ * manifest should not black-hole the rest of the project — the
+ * `ggui dev` hub renders the valid catalogs + flags the bad ones in
+ * the UI. Each issue carries a path + message so callers can render
+ * a useful list.
+ *
+ * Callers that need fail-fast semantics (e.g. `ggui serve` boot,
+ * where continuing with a partial set is a silent deploy-time
+ * regression) inspect `result.issues` themselves and escalate to a
+ * thrown error when non-empty. This helper stays policy-neutral —
+ * mirrors the blueprint-discovery split.
+ *
+ * ## Why `@ggui-ai/project-config/node`, not a sibling package
+ *
+ * Discovery is filesystem + parse + identity check. It is NOT HTTP,
+ * agent runtime, or generator state. Consumers today:
+ *
+ *   - `@ggui-ai/mcp-server` at `ggui serve` boot time — builds the
+ *     primitive index so future generator consumers can enumerate
+ *     every declared source.
+ *   - `@ggui-ai/dev-stack` may consume it later for a unified
+ *     `ggui dev` hub view (symmetric with blueprint discovery).
+ *
+ * Housing it here keeps one source of truth and avoids an inbound
+ * dep on either consumer.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { glob } from 'tinyglobby';
+import { GGUI_PRIMITIVES_JSON_FILENAME, parsePrimitivesManifest, } from './primitives-manifest.js';
+/**
+ * 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 async function discoverPrimitives(options) {
+    const { projectRoot, manifest } = options;
+    if (!isAbsolute(projectRoot)) {
+        throw new Error(`discoverPrimitives: projectRoot must be absolute, got ${projectRoot}`);
+    }
+    const catalogs = [];
+    const issues = [];
+    const seenImports = new Map(); // import → manifestPath
+    const resolveModule = options.resolveModule ?? makeDefaultModuleResolver(projectRoot);
+    // ── packages: npm specifiers ────────────────────────────────────
+    for (const spec of manifest.primitives.packages) {
+        let entryPath;
+        try {
+            entryPath = resolveModule(spec, projectRoot);
+        }
+        catch (cause) {
+            issues.push({
+                path: spec,
+                message: `Could not resolve primitive package "${spec}" — is it installed in the project? ` +
+                    `(${errorMessage(cause)})`,
+                cause,
+            });
+            continue;
+        }
+        const pkgRoot = findEnclosingPackageRoot(entryPath);
+        if (!pkgRoot) {
+            issues.push({
+                path: spec,
+                message: `Primitive package "${spec}" resolved to ${entryPath}, but no enclosing package.json was found.`,
+            });
+            continue;
+        }
+        const manifestPath = join(pkgRoot, GGUI_PRIMITIVES_JSON_FILENAME);
+        if (!existsSync(manifestPath)) {
+            issues.push({
+                path: spec,
+                message: `Primitive package "${spec}" is missing ${GGUI_PRIMITIVES_JSON_FILENAME} at its root (${pkgRoot}). ` +
+                    `Expected convention: one ggui.primitives.json alongside package.json.`,
+            });
+            continue;
+        }
+        const parsed = loadManifestAt(manifestPath, spec);
+        if (!parsed.ok) {
+            issues.push(parsed.issue);
+            continue;
+        }
+        // The declared `ggui.json` spec MUST match the manifest's own
+        // `import` field. A mismatch means the operator declared the
+        // wrong package name OR the package is advertising a different
+        // specifier — either way, the generator's import-line would be
+        // wrong. Surface it here rather than hand the agent a broken
+        // catalog.
+        if (parsed.manifest.import !== spec) {
+            issues.push({
+                path: spec,
+                message: `Primitive package "${spec}" declares import="${parsed.manifest.import}" in its ` +
+                    `ggui.primitives.json, but ggui.json lists it under primitives.packages as "${spec}". ` +
+                    `These must match — either update ggui.json's entry or the package's manifest.`,
+            });
+            continue;
+        }
+        recordCatalog(catalogs, issues, seenImports, {
+            source: 'package',
+            import: parsed.manifest.import,
+            manifestPath,
+            manifest: parsed.manifest,
+        });
+    }
+    // ── local: globs ────────────────────────────────────────────────
+    const localPatterns = manifest.primitives.local;
+    if (localPatterns.length > 0) {
+        const matches = await glob(localPatterns, {
+            cwd: projectRoot,
+            absolute: true,
+            onlyFiles: true,
+            followSymbolicLinks: false,
+            dot: false,
+        });
+        for (const absolutePath of matches) {
+            const rel = relative(projectRoot, absolutePath);
+            const displayPath = rel === '' ? absolutePath : rel;
+            // Mirror blueprint discovery's wide-`**` safety — skip matches
+            // whose basename isn't the canonical filename. Users sometimes
+            // write `ui/**/*.json` patterns and pick up arbitrary JSON.
+            if (!absolutePath.endsWith(sep + GGUI_PRIMITIVES_JSON_FILENAME)) {
+                continue;
+            }
+            const parsed = loadManifestAt(absolutePath, displayPath);
+            if (!parsed.ok) {
+                issues.push(parsed.issue);
+                continue;
+            }
+            recordCatalog(catalogs, issues, seenImports, {
+                source: 'local',
+                import: parsed.manifest.import,
+                manifestPath: absolutePath,
+                manifest: parsed.manifest,
+            });
+        }
+    }
+    return { catalogs, issues };
+}
+/**
+ * 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 async function discoverPrimitivesFromGguiJsonPath(manifestPath, manifest, extra = {}) {
+    const projectRoot = dirname(resolve(manifestPath));
+    return discoverPrimitives({ projectRoot, manifest, ...extra });
+}
+// ─────────────────────────────────────────────────────────────────────
+// Internals
+// ─────────────────────────────────────────────────────────────────────
+function makeDefaultModuleResolver(projectRoot) {
+    // Anchor at `<projectRoot>/package.json` — the file doesn't have
+    // to exist for resolution to produce a working answer; Node uses
+    // the path only to establish the ancestor `node_modules/` chain.
+    //
+    // We use `import.meta.resolve` rather than `createRequire().resolve`
+    // because primitive packages (`@ggui-ai/design`, sibling catalogs
+    // operators may author) are ESM-only — their `package.json#exports`
+    // declare only the `"import"` condition per the open-source
+    // subtree's `"type": "module"` convention. CommonJS `require.resolve`
+    // cannot satisfy a subpath whose `exports` entry has no `"require"`
+    // condition, even though the subpath IS defined for ESM consumers —
+    // the resolver throws `ERR_PACKAGE_PATH_NOT_EXPORTED` with a
+    // misleading "not defined by exports" message.
+    //
+    // Crucially, discovery never actually `require()`s the resolved
+    // entry; it only walks UP from the entry path to find the enclosing
+    // `package.json` (see `findEnclosingPackageRoot` above). So using
+    // an ESM-native resolver is both honest (matches the package's
+    // actual condition set) and safe (no downstream CJS load).
+    //
+    // `import.meta.resolve(spec, parent)` is stable + synchronous in
+    // Node 20+. The returned URL is converted back to a filesystem path
+    // with `fileURLToPath` so the rest of the pipeline stays
+    // path-based.
+    const originUrl = pathToFileURL(join(projectRoot, 'package.json')).href;
+    return (specifier) => fileURLToPath(import.meta.resolve(specifier, originUrl));
+}
+function findEnclosingPackageRoot(startFile) {
+    let dir = dirname(resolve(startFile));
+    for (;;) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function loadManifestAt(absolutePath, displayPath) {
+    let raw;
+    try {
+        raw = readFileSync(absolutePath, 'utf-8');
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            issue: {
+                path: displayPath,
+                message: `Could not read ${GGUI_PRIMITIVES_JSON_FILENAME}: ${errorMessage(cause)}`,
+                cause,
+            },
+        };
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            issue: {
+                path: displayPath,
+                message: `${GGUI_PRIMITIVES_JSON_FILENAME} is not valid JSON: ${errorMessage(cause)}`,
+                cause,
+            },
+        };
+    }
+    try {
+        const manifest = parsePrimitivesManifest(decoded);
+        return { ok: true, manifest };
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            issue: {
+                path: displayPath,
+                message: `${GGUI_PRIMITIVES_JSON_FILENAME} failed schema validation: ${errorMessage(cause)}`,
+                cause,
+            },
+        };
+    }
+}
+function recordCatalog(catalogs, issues, seenImports, candidate) {
+    const prior = seenImports.get(candidate.import);
+    if (prior !== undefined) {
+        issues.push({
+            path: candidate.manifestPath,
+            message: `Duplicate primitive import specifier "${candidate.import}" — already declared by ${prior}. ` +
+                `Two sources cannot claim the same specifier (the generator would emit duplicate import lines).`,
+        });
+        return;
+    }
+    seenImports.set(candidate.import, candidate.manifestPath);
+    catalogs.push(candidate);
+}
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/primitives-manifest.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `ggui.primitives.json` v1 — primitive package manifest.
+ *
+ * Fourth open file-format surface in the ggui manifest model, after
+ * `ggui.json` (root) and `ggui.ui.json` (per-UI). One file at the
+ * root of each primitive source:
+ *
+ * ```
+ * packages/design/
+ * ├── ggui.primitives.json   ← this file
+ * ├── package.json
+ * └── src/primitives/
+ * ```
+ *
+ * The root `ggui.json#primitives.packages` (npm specifiers) +
+ * `primitives.local` (globs) declare *which* primitive sources the
+ * app uses; this file declares *what each source exports* + the
+ * `import` specifier consumers use + an optional pre-generated LLM
+ * docs pointer.
+ *
+ * Both `primitives.packages` (npm specifiers) and `primitives.local`
+ * (globs) follow the same discovery convention: the resolver walks up
+ * from the resolved source to the enclosing `package.json` and reads
+ * `ggui.primitives.json` next to it.
+ *
+ * **Ownership boundary:**
+ *
+ *   - *Which* packages / local paths declare primitives → `ggui.json`.
+ *   - *Which* primitives a source exports + import specifier + docs
+ *     pointer → this file.
+ *   - *What* each primitive renders / its prop interface / its
+ *     JSDoc description → TSX source in the declaring package. NOT a
+ *     ggui concern.
+ *
+ * **Extending rules:**
+ *
+ *   1. Additive only within `schema: '1'`. Optional fields default to
+ *      no-op behaviour so older tooling ignores them.
+ *   2. Framework-neutral. Nothing Claude-SDK / Vercel-AI-SDK /
+ *      LangGraph / framework-specific belongs here.
+ *   3. Root and per-primitive objects are strict — unknown keys fail
+ *      parse. Same discipline as `ggui.json` + `ggui.ui.json`.
+ */
+import { z } from 'zod';
+/**
+ * Root manifest. `import` MUST be a non-empty string — either an npm
+ * specifier (for `primitives.packages` sources) or a relative path
+ * (for `primitives.local` sources). The discovery layer validates
+ * that `import` matches the declared `packages` entry when the
+ * source was resolved through an npm specifier.
+ */
+export declare const PrimitivesManifestV1: z.ZodObject<{
+    /** File-format version — always `"1"` for v1. */
+    schema: z.ZodLiteral<"1">;
+    /**
+     * The specifier consumers import from. For npm-distributed
+     * primitive packages this is the same string the app lists in
+     * `ggui.json#primitives.packages` (e.g.
+     * `@ggui-ai/design/primitives`). For in-project local primitives
+     * it is the path consumers import from (e.g.
+     * `./src/ui/primitives/index.js`).
+     */
+    import: z.ZodString;
+    /**
+     * List of primitive components this source exports. At least one
+     * entry — a manifest that declares zero primitives is always a
+     * mistake.
+     */
+    primitives: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    /**
+     * Optional path to a pre-generated LLM docs blob the generator
+     * can inject into the system prompt. Resolved relative to this
+     * manifest's directory at load time (not parse time).
+     *
+     * Absent → the server falls back to a names-only doc block and
+     * emits a boot warning (not fatal). The package's own build
+     * pipeline is responsible for emitting the file; ggui tooling
+     * never writes it.
+     */
+    docs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Static TypeScript type derived from the v1 schema. */
+export type PrimitivesManifestV1 = z.infer<typeof PrimitivesManifestV1>;
+/**
+ * Canonical type alias — `PrimitivesManifest` is the term used
+ * everywhere else (discovery, docs, mcp-server wiring).
+ * `PrimitivesManifestV1` is the version-pinned name.
+ */
+export type PrimitivesManifest = PrimitivesManifestV1;
+/**
+ * Canonical filename — always `ggui.primitives.json`, always at the
+ * root of the declaring package / local primitive directory.
+ */
+export declare const GGUI_PRIMITIVES_JSON_FILENAME = "ggui.primitives.json";
+/**
+ * Parse a raw JSON value into a validated {@link PrimitivesManifest}.
+ * Throws a `ZodError` with human-readable issues on invalid input.
+ */
+export declare function parsePrimitivesManifest(raw: unknown): PrimitivesManifest;
+/**
+ * Safe-parse variant — returns a discriminated `z.safeParse` result.
+ */
+export declare function safeParsePrimitivesManifest(raw: unknown): ReturnType<typeof PrimitivesManifestV1.safeParse>;
+//# sourceMappingURL=primitives-manifest.d.ts.map

package/dist/primitives-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives-manifest.d.ts","sourceRoot":"","sources":["../src/primitives-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiCxB;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;IAE7B,iDAAiD;;IAGjD;;;;;;;OAOG;;IAGH;;;;OAIG;;;;IASH;;;;;;;;;OASG;;kBAEH,CAAC;AAEL,yDAAyD;AACzD,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,yBAAyB,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAExE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,oBAAoB,CAAC,SAAS,CAAC,CAEnD"}

package/dist/primitives-manifest.js

@@ -0,0 +1,131 @@
+/**
+ * `ggui.primitives.json` v1 — primitive package manifest.
+ *
+ * Fourth open file-format surface in the ggui manifest model, after
+ * `ggui.json` (root) and `ggui.ui.json` (per-UI). One file at the
+ * root of each primitive source:
+ *
+ * ```
+ * packages/design/
+ * ├── ggui.primitives.json   ← this file
+ * ├── package.json
+ * └── src/primitives/
+ * ```
+ *
+ * The root `ggui.json#primitives.packages` (npm specifiers) +
+ * `primitives.local` (globs) declare *which* primitive sources the
+ * app uses; this file declares *what each source exports* + the
+ * `import` specifier consumers use + an optional pre-generated LLM
+ * docs pointer.
+ *
+ * Both `primitives.packages` (npm specifiers) and `primitives.local`
+ * (globs) follow the same discovery convention: the resolver walks up
+ * from the resolved source to the enclosing `package.json` and reads
+ * `ggui.primitives.json` next to it.
+ *
+ * **Ownership boundary:**
+ *
+ *   - *Which* packages / local paths declare primitives → `ggui.json`.
+ *   - *Which* primitives a source exports + import specifier + docs
+ *     pointer → this file.
+ *   - *What* each primitive renders / its prop interface / its
+ *     JSDoc description → TSX source in the declaring package. NOT a
+ *     ggui concern.
+ *
+ * **Extending rules:**
+ *
+ *   1. Additive only within `schema: '1'`. Optional fields default to
+ *      no-op behaviour so older tooling ignores them.
+ *   2. Framework-neutral. Nothing Claude-SDK / Vercel-AI-SDK /
+ *      LangGraph / framework-specific belongs here.
+ *   3. Root and per-primitive objects are strict — unknown keys fail
+ *      parse. Same discipline as `ggui.json` + `ggui.ui.json`.
+ */
+import { z } from 'zod';
+/**
+ * Primitive component name — must be a valid JavaScript identifier.
+ * Stricter than a freeform string because the generator emits literal
+ * `import { <name> } from '<import>'` lines, and anything that isn't
+ * a valid identifier would break the TSX output.
+ *
+ * Also rejects reserved words implicitly via the "leading letter"
+ * rule — JS identifiers can't start with a digit. A downstream
+ * allowlist of reserved words is avoided here on purpose: the list
+ * is long, version-dependent, and would add maintenance burden
+ * without meaningfully changing what authors actually write.
+ */
+const PrimitiveNameSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/, {
+    message: 'primitive name must be a valid JavaScript identifier (letters, digits, _, $; not starting with a digit).',
+});
+/**
+ * Per-primitive entry. v1 only requires `name`; the TSX source +
+ * JSDoc is the authoritative prop-surface. Additive fields
+ * (description override, deprecation marker, variant hint) land
+ * later under `schema: "1"`.
+ */
+const PrimitiveEntrySchema = z.strictObject({
+    name: PrimitiveNameSchema,
+});
+/**
+ * Root manifest. `import` MUST be a non-empty string — either an npm
+ * specifier (for `primitives.packages` sources) or a relative path
+ * (for `primitives.local` sources). The discovery layer validates
+ * that `import` matches the declared `packages` entry when the
+ * source was resolved through an npm specifier.
+ */
+export const PrimitivesManifestV1 = z
+    .strictObject({
+    /** File-format version — always `"1"` for v1. */
+    schema: z.literal('1'),
+    /**
+     * The specifier consumers import from. For npm-distributed
+     * primitive packages this is the same string the app lists in
+     * `ggui.json#primitives.packages` (e.g.
+     * `@ggui-ai/design/primitives`). For in-project local primitives
+     * it is the path consumers import from (e.g.
+     * `./src/ui/primitives/index.js`).
+     */
+    import: z.string().min(1, 'import must not be empty'),
+    /**
+     * List of primitive components this source exports. At least one
+     * entry — a manifest that declares zero primitives is always a
+     * mistake.
+     */
+    primitives: z
+        .array(PrimitiveEntrySchema)
+        .min(1, 'primitives must declare at least one entry')
+        .refine((arr) => new Set(arr.map((p) => p.name)).size === arr.length, { message: 'primitive names must be unique within a manifest' }),
+    /**
+     * Optional path to a pre-generated LLM docs blob the generator
+     * can inject into the system prompt. Resolved relative to this
+     * manifest's directory at load time (not parse time).
+     *
+     * Absent → the server falls back to a names-only doc block and
+     * emits a boot warning (not fatal). The package's own build
+     * pipeline is responsible for emitting the file; ggui tooling
+     * never writes it.
+     */
+    docs: z.string().min(1).optional(),
+});
+/**
+ * Canonical filename — always `ggui.primitives.json`, always at the
+ * root of the declaring package / local primitive directory.
+ */
+export const GGUI_PRIMITIVES_JSON_FILENAME = 'ggui.primitives.json';
+/**
+ * Parse a raw JSON value into a validated {@link PrimitivesManifest}.
+ * Throws a `ZodError` with human-readable issues on invalid input.
+ */
+export function parsePrimitivesManifest(raw) {
+    return PrimitivesManifestV1.parse(raw);
+}
+/**
+ * Safe-parse variant — returns a discriminated `z.safeParse` result.
+ */
+export function safeParsePrimitivesManifest(raw) {
+    return PrimitivesManifestV1.safeParse(raw);
+}