@rfdtech/components 1.22.0 → 2.0.1

package/dist/mcp/indexer.js

@@ -0,0 +1,370 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { GENERATED_DIR, SOURCE, hasRepoSource } from "./paths.js";
+function quoted(key, block) {
+    return block.match(new RegExp(`${key}:\\s*["']([^"']*)["']`))?.[1];
+}
+function quotedArray(key, block) {
+    const m = block.match(new RegExp(`${key}:\\s*\\[([\\s\\S]*?)\\]`));
+    if (!m)
+        return [];
+    return [...m[1].matchAll(/["']([^"']*)["']/g)].map((x) => x[1]);
+}
+function parseMeta(source) {
+    const block = source.match(/export const meta\s*=\s*{([\s\S]*?)};/)?.[1] ?? "";
+    return {
+        title: quoted("title", block) ?? "",
+        description: quoted("description", block),
+        category: quoted("category", block),
+        keywords: quotedArray("keywords", block),
+        since: quoted("since", block),
+        status: quoted("status", block),
+        related: quotedArray("related", block),
+        import: quoted("import", block),
+    };
+}
+/** Everything from the first top-level heading onward — drops the meta block and import statements. */
+function stripMetaAndImports(source) {
+    const heading = source.match(/^#\s+.+$/m);
+    if (!heading || heading.index === undefined)
+        return source.trim();
+    return source.slice(heading.index).trim();
+}
+function extractHeadings(body) {
+    return [...body.matchAll(/^#{1,3}\s+(.+)$/gm)].map((m) => m[1].trim());
+}
+// ───────────────────────── examples ─────────────────────────
+const RAW_IMPORT_RE = /import\s+(\w+)\s+from\s+["']\.\.\/previews\/examples\/([^"']+)\?raw["'];?/g;
+function extractRawImports(source) {
+    return [...source.matchAll(RAW_IMPORT_RE)].map((m) => ({
+        importName: m[1],
+        file: m[2],
+    }));
+}
+function extractUsedComponents(source) {
+    const used = new Set();
+    const re = /import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+["']@rfdtech\/components["'];?/g;
+    for (const m of source.matchAll(re)) {
+        for (const raw of m[1].split(",")) {
+            const name = raw.trim().split(/\s+as\s+/)[0].trim();
+            if (name)
+                used.add(name);
+        }
+    }
+    return [...used].sort();
+}
+function titleFromExampleFile(file) {
+    const base = file.replace(/\.example\.tsx$/, "");
+    return base
+        .split("-")
+        .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+        .join(" ");
+}
+async function buildRules() {
+    const rulesByCategory = {};
+    const componentToRuleIds = {};
+    if (!existsSync(SOURCE.rules))
+        return { rulesByCategory, componentToRuleIds };
+    const files = (await readdir(SOURCE.rules)).filter((f) => f.endsWith(".md")).sort();
+    for (const file of files) {
+        const category = file.replace(/\.md$/, "");
+        const raw = await readFile(path.join(SOURCE.rules, file), "utf8");
+        const blocks = raw.split("===RULE===").slice(1); // [0] is the "# Title" preamble
+        const rules = [];
+        for (const rawBlock of blocks) {
+            const block = rawBlock.replace(/^\n/, "");
+            const headerEnd = block.indexOf("\n\n");
+            const headerPart = headerEnd === -1 ? block : block.slice(0, headerEnd);
+            const body = headerEnd === -1 ? "" : block.slice(headerEnd + 2).trim();
+            const fields = {};
+            for (const line of headerPart.split("\n")) {
+                const idx = line.indexOf(":");
+                if (idx === -1)
+                    continue;
+                fields[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+            }
+            if (!fields.id)
+                continue;
+            const components = (fields.components ?? "")
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+            const rule = {
+                id: fields.id,
+                title: fields.title ?? "",
+                severity: fields.severity ?? "info",
+                components,
+                body,
+            };
+            rules.push(rule);
+            for (const c of components) {
+                (componentToRuleIds[c] ??= []).push(rule.id);
+            }
+        }
+        rulesByCategory[category] = rules;
+    }
+    return { rulesByCategory, componentToRuleIds };
+}
+// ───────────────────────── tokens ─────────────────────────
+// Mirrors scripts/generate-theme-tokens.mjs's `classify()` so tokens.json's
+// "group" field lines up with the same value-type buckets cletTheme() enforces
+// at the type level (color/length/shadow/zIndex/opacity/duration/misc).
+function classifyToken(cssVar) {
+    const local = cssVar.replace(/^--clet-/, "");
+    if (/radius/.test(local))
+        return "length";
+    if (/shadow/.test(local))
+        return "shadow";
+    if (/^z(-|$)/.test(local))
+        return "zIndex";
+    if (/font/.test(local))
+        return "font";
+    if (/opacity/.test(local))
+        return "opacity";
+    if (/(size|gap|width|height|padding|margin|px$|py$|-px-|-py-)/.test(local))
+        return "length";
+    if (/(duration|transition|delay|stagger)/.test(local))
+        return "duration";
+    if (/(color|^bg$|-bg$|bg-|background|border|accent|track|success|warning|error|primary|secondary|surface|hover|overlay|text|focus|current|highlight|shimmer)/.test(local))
+        return "color";
+    return "misc";
+}
+/**
+ * Parses src/generated/components.theme.ts — the file cletTheme() itself is
+ * typed against — for the authoritative list of every overridable token.
+ * This is what makes tokens.json/get_tokens() match the real runtime API
+ * surface (including ~70+ component-scoped tokens like --clet-card-padding
+ * that never appear in the 3 global theme CSS files).
+ */
+async function readTokenRegistry() {
+    if (!existsSync(SOURCE.generatedTheme))
+        return [];
+    const source = await readFile(SOURCE.generatedTheme, "utf8");
+    const entries = [];
+    const globalBlock = source.match(/export const CLET_GLOBAL_TOKEN_VARS[^{]*\{([\s\S]*?)\n\};/)?.[1] ?? "";
+    for (const m of globalBlock.matchAll(/^\s{2}\w+:\s*"(--clet-[\w-]+)",\s*$/gm)) {
+        entries.push({ cssVar: m[1] });
+    }
+    const componentSection = source.match(/export const CLET_COMPONENT_TOKEN_VARS[\s\S]*?=\s*\{([\s\S]*)\n\};\s*$/)?.[1] ?? "";
+    for (const compMatch of componentSection.matchAll(/^\s{2}(\w+):\s*\{([\s\S]*?)\n\s{2}\},\s*$/gm)) {
+        const [, component, body] = compMatch;
+        for (const m of body.matchAll(/^\s{4}\w+:\s*"(--clet-[\w-]+)",\s*$/gm)) {
+            entries.push({ component, cssVar: m[1] });
+        }
+    }
+    return entries;
+}
+/** "AppHeader" -> "app-header" — inverse of generate-theme-tokens.mjs's toPascalCase(). */
+function pascalToKebab(pascal) {
+    return pascal.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/** Component-scoped values, keyed by bare local name (no "--clet-" prefix). */
+async function readComponentCssValues(slug) {
+    const values = new Map();
+    const stylesDir = path.join(SOURCE.componentsDir, slug, "styles");
+    if (!existsSync(stylesDir))
+        return values;
+    for (const file of await readdir(stylesDir)) {
+        if (!file.endsWith(".css"))
+            continue;
+        const css = await readFile(path.join(stylesDir, file), "utf8");
+        for (const m of css.matchAll(/--clet-([\w-]+)\s*:\s*([^;]+);/g)) {
+            if (!values.has(m[1]))
+                values.set(m[1], m[2].trim()); // first declaration = base value
+        }
+    }
+    return values;
+}
+async function buildTokens() {
+    const tokens = {};
+    // Global token VALUES, keyed by bare local name, per theme.
+    const globalValues = {};
+    const files = { base: "base.css", light: "light.css", dark: "dark.css" };
+    for (const [theme, file] of Object.entries(files)) {
+        const p = path.join(SOURCE.themeDir, file);
+        if (!existsSync(p))
+            continue;
+        const css = await readFile(p, "utf8");
+        for (const m of css.matchAll(/--clet-([\w-]+)\s*:\s*([^;]+);/g)) {
+            (globalValues[m[1]] ??= {})[theme] = m[2].trim();
+        }
+    }
+    const registry = await readTokenRegistry();
+    const byComponent = new Map();
+    for (const entry of registry) {
+        if (!entry.component) {
+            const localName = entry.cssVar.replace(/^--clet-/, "");
+            tokens[entry.cssVar] = {
+                group: classifyToken(entry.cssVar),
+                scope: "global",
+                ...globalValues[localName],
+            };
+            continue;
+        }
+        const list = byComponent.get(entry.component) ?? [];
+        list.push(entry.cssVar);
+        byComponent.set(entry.component, list);
+    }
+    // Component-scoped VALUES: each component's own styles/*.css (fallback
+    // registry when a token isn't declared where expected — best-effort, first
+    // declaration wins; a component may set the same token again in a media
+    // query for a responsive override, which this doesn't capture separately).
+    for (const [component, cssVars] of byComponent) {
+        const slug = pascalToKebab(component);
+        const cssValues = await readComponentCssValues(slug);
+        for (const cssVar of cssVars) {
+            const localName = cssVar.replace(/^--clet-/, "");
+            const base = cssValues.get(localName);
+            tokens[cssVar] = {
+                group: classifyToken(cssVar),
+                scope: "component",
+                component: slug,
+                ...(base ? { base } : {}),
+            };
+        }
+    }
+    return tokens;
+}
+export async function buildIndex(outDir = GENERATED_DIR) {
+    if (!hasRepoSource) {
+        throw new Error("buildIndex() requires live repo source (demo/docs, src/types) which isn't present — " +
+            "this looks like a published install; it should only ever read the bundled generated/ snapshot.");
+    }
+    await mkdir(outDir, { recursive: true });
+    const pageFiles = (await readdir(SOURCE.pages)).filter((f) => f.endsWith(".mdx")).sort();
+    const exampleFiles = (await readdir(SOURCE.examples)).filter((f) => f.endsWith(".example.tsx"));
+    const pageSources = new Map();
+    for (const file of pageFiles) {
+        pageSources.set(file.replace(/\.mdx$/, ""), await readFile(path.join(SOURCE.pages, file), "utf8"));
+    }
+    const pageImports = new Map();
+    const globalImported = new Set();
+    for (const [slug, src] of pageSources) {
+        const imports = extractRawImports(src);
+        pageImports.set(slug, imports);
+        imports.forEach((i) => globalImported.add(i.file));
+    }
+    const exampleSourceCache = new Map();
+    async function getExampleSource(file) {
+        if (!exampleSourceCache.has(file)) {
+            try {
+                exampleSourceCache.set(file, await readFile(path.join(SOURCE.examples, file), "utf8"));
+            }
+            catch {
+                exampleSourceCache.set(file, `// Could not read ${file}`);
+            }
+        }
+        return exampleSourceCache.get(file);
+    }
+    const { rulesByCategory, componentToRuleIds } = await buildRules();
+    const tokens = await buildTokens();
+    const components = {};
+    const examplesOut = {};
+    const searchEntries = [];
+    let exampleCount = 0;
+    for (const [slug, src] of pageSources) {
+        const meta = parseMeta(src);
+        const docsBody = stripMetaAndImports(src);
+        const headings = extractHeadings(docsBody);
+        // Hybrid example ownership: explicit `?raw` imports are authoritative;
+        // a `<slug>*` glob only fills in files no page has claimed (avoids the
+        // form/form-field inversion and similar cross-page naming collisions).
+        const importsForSlug = pageImports.get(slug) ?? [];
+        const importNameByFile = new Map(importsForSlug.map((i) => [i.file, i.importName]));
+        const owned = new Set(importsForSlug.map((i) => i.file));
+        for (const file of exampleFiles) {
+            if (file.startsWith(slug) && !globalImported.has(file))
+                owned.add(file);
+        }
+        const exampleList = await Promise.all([...owned].sort().map(async (file) => {
+            const source = await getExampleSource(file);
+            return {
+                file,
+                importName: importNameByFile.get(file),
+                title: titleFromExampleFile(file),
+                components: extractUsedComponents(source),
+                source,
+            };
+        }));
+        examplesOut[slug] = exampleList;
+        exampleCount += exampleList.length;
+        const typesPath = path.join(SOURCE.types, `${slug}.ts`);
+        const types = existsSync(typesPath) ? await readFile(typesPath, "utf8") : null;
+        const ruleIds = componentToRuleIds[slug] ?? [];
+        components[slug] = {
+            meta: { slug, ...meta },
+            docs: docsBody,
+            headings,
+            types,
+            examples: exampleList,
+            ruleIds,
+        };
+        searchEntries.push({
+            slug,
+            name: meta.title || slug,
+            category: meta.category,
+            keywords: meta.keywords,
+            description: meta.description,
+            headings,
+        });
+    }
+    await writeFile(path.join(outDir, "components.json"), JSON.stringify(components, null, 2));
+    await writeFile(path.join(outDir, "examples.json"), JSON.stringify(examplesOut, null, 2));
+    await writeFile(path.join(outDir, "search.json"), JSON.stringify(searchEntries, null, 2));
+    await writeFile(path.join(outDir, "rules.json"), JSON.stringify(rulesByCategory, null, 2));
+    await writeFile(path.join(outDir, "tokens.json"), JSON.stringify(tokens, null, 2));
+    const builtFrom = {};
+    for (const dir of [SOURCE.pages, SOURCE.examples, SOURCE.types, SOURCE.rules, SOURCE.themeDir]) {
+        if (!existsSync(dir))
+            continue;
+        for (const file of await readdir(dir)) {
+            const filePath = path.join(dir, file);
+            const info = await stat(filePath);
+            if (info.isFile())
+                builtFrom[filePath] = info.mtimeMs;
+        }
+    }
+    // The generated token registry drives buildTokens() identity/grouping —
+    // track it so editing component CSS + regenerating it (or forgetting to)
+    // is visible to the staleness check, not just the 3 global theme files.
+    if (existsSync(SOURCE.generatedTheme)) {
+        builtFrom[SOURCE.generatedTheme] = (await stat(SOURCE.generatedTheme)).mtimeMs;
+    }
+    // Component-scoped token VALUES come from each component's own styles/*.css
+    // — track those too, so a value-only CSS edit (no registry change) still
+    // triggers a rebuild.
+    if (existsSync(SOURCE.componentsDir)) {
+        for (const entry of await readdir(SOURCE.componentsDir)) {
+            const stylesDir = path.join(SOURCE.componentsDir, entry, "styles");
+            if (!existsSync(stylesDir))
+                continue;
+            for (const file of await readdir(stylesDir)) {
+                if (!file.endsWith(".css"))
+                    continue;
+                const filePath = path.join(stylesDir, file);
+                builtFrom[filePath] = (await stat(filePath)).mtimeMs;
+            }
+        }
+    }
+    const ruleCount = Object.values(rulesByCategory).reduce((n, rs) => n + rs.length, 0);
+    const result = {
+        componentCount: Object.keys(components).length,
+        exampleCount,
+        ruleCount,
+        tokenCount: Object.keys(tokens).length,
+    };
+    await writeFile(path.join(outDir, "index.meta.json"), JSON.stringify({ builtAt: Date.now(), builtFrom, ...result }, null, 2));
+    return result;
+}
+// Runnable directly: `tsx src/indexer.ts` (dev) or `node dist/indexer.js` (build).
+if (import.meta.url === `file://${process.argv[1]}`) {
+    buildIndex()
+        .then((result) => {
+        console.log(`Index built: ${JSON.stringify(result)}`);
+    })
+        .catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/mcp/installers/claude.js

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { appendPointerOnce, mergeMcpServers, readJsonIfExists, writeJson, } from "./util.js";
+export function detect(cwd) {
+    return existsSync(path.join(cwd, ".claude")) || existsSync(path.join(cwd, ".mcp.json"));
+}
+async function installSkill(cwd, slug, skillSourcePath) {
+    const skillDir = path.join(cwd, ".claude", "skills", slug);
+    await mkdir(skillDir, { recursive: true });
+    const skillDest = path.join(skillDir, "SKILL.md");
+    const skillSource = await readFile(skillSourcePath, "utf8");
+    const skillChanged = !existsSync(skillDest) || (await readFile(skillDest, "utf8")) !== skillSource;
+    await copyFile(skillSourcePath, skillDest);
+    return skillChanged;
+}
+export async function install(cwd, skillSourcePath, skillImageSourcePath) {
+    const mcpJsonPath = path.join(cwd, ".mcp.json");
+    const existing = await readJsonIfExists(mcpJsonPath);
+    const { data, changed: mcpChanged } = mergeMcpServers(existing);
+    await writeJson(mcpJsonPath, data);
+    const skillChanged = await installSkill(cwd, "rfdtech-ui", skillSourcePath);
+    const imageSkillChanged = await installSkill(cwd, "image-to-components", skillImageSourcePath);
+    const claudeMdChanged = await appendPointerOnce(path.join(cwd, "CLAUDE.md"), "rfdtech-ui", "<!-- rfdtech-ui -->\nBefore writing UI code, see `.claude/skills/rfdtech-ui/SKILL.md` for " +
+        "`@rfdtech/components` conventions (search components, use authoritative types, follow the rules). " +
+        "Given a screenshot, image, mockup, or description of a screen to build, see " +
+        "`.claude/skills/image-to-components/SKILL.md` first.\n", "Project notes");
+    const changed = mcpChanged || skillChanged || imageSkillChanged || claudeMdChanged;
+    return {
+        name: "Claude Code",
+        changed,
+        detail: `.mcp.json${mcpChanged ? " (updated)" : " (already set)"}, ` +
+            `.claude/skills/rfdtech-ui/SKILL.md${skillChanged ? " (updated)" : " (already set)"}, ` +
+            `.claude/skills/image-to-components/SKILL.md${imageSkillChanged ? " (updated)" : " (already set)"}, ` +
+            `CLAUDE.md${claudeMdChanged ? " (updated)" : " (already set)"}`,
+    };
+}

package/dist/mcp/installers/codex.js

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const CODEX_DIR = path.join(os.homedir(), ".codex");
+const CONFIG_PATH = path.join(CODEX_DIR, "config.toml");
+const MARKER = "[mcp_servers.rfdtech-ui]";
+export function detect() {
+    return existsSync(CODEX_DIR);
+}
+// Codex config is TOML. Rather than pull in a TOML parser/writer for one
+// block, we do a text-level idempotent append — safe because we only ever
+// check for and add our own uniquely-named `[mcp_servers.rfdtech-ui]` table
+// and never touch any other section.
+export async function install() {
+    await mkdir(CODEX_DIR, { recursive: true });
+    const existing = existsSync(CONFIG_PATH) ? await readFile(CONFIG_PATH, "utf8") : "";
+    if (existing.includes(MARKER)) {
+        return { name: "Codex", changed: false, detail: "~/.codex/config.toml (already set)" };
+    }
+    const block = `\n${MARKER}\ncommand = "npx"\nargs = ["-y", "@rfdtech/components-mcp"]\n`;
+    await writeFile(CONFIG_PATH, existing.replace(/\s*$/, "") + "\n" + block, "utf8");
+    return { name: "Codex", changed: true, detail: "~/.codex/config.toml (updated)" };
+}

package/dist/mcp/installers/cursor.js

@@ -0,0 +1,33 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { mergeMcpServers, readJsonIfExists, writeJson } from "./util.js";
+export function detect(cwd) {
+    return existsSync(path.join(cwd, ".cursor"));
+}
+async function installRule(cwd, slug, description, skillSourcePath) {
+    const rulesDir = path.join(cwd, ".cursor", "rules");
+    await mkdir(rulesDir, { recursive: true });
+    const rulesPath = path.join(rulesDir, `${slug}.mdc`);
+    const skill = await readFile(skillSourcePath, "utf8");
+    const mdc = `---\ndescription: ${description}\nglobs: ["**/*.tsx", "**/*.ts"]\nalwaysApply: false\n---\n\n${skill}`;
+    const rulesChanged = !existsSync(rulesPath) || (await readFile(rulesPath, "utf8")) !== mdc;
+    await writeFile(rulesPath, mdc, "utf8");
+    return rulesChanged;
+}
+export async function install(cwd, skillSourcePath, skillImageSourcePath) {
+    const mcpJsonPath = path.join(cwd, ".cursor", "mcp.json");
+    const existing = await readJsonIfExists(mcpJsonPath);
+    const { data, changed: mcpChanged } = mergeMcpServers(existing);
+    await writeJson(mcpJsonPath, data);
+    const rulesChanged = await installRule(cwd, "rfdtech-ui", "GSL (@rfdtech/components) usage rules", skillSourcePath);
+    const imageRulesChanged = await installRule(cwd, "image-to-components", "Translate screenshots/mockups into GSL (@rfdtech/components) components", skillImageSourcePath);
+    const changed = mcpChanged || rulesChanged || imageRulesChanged;
+    return {
+        name: "Cursor",
+        changed,
+        detail: `.cursor/mcp.json${mcpChanged ? " (updated)" : " (already set)"}, ` +
+            `.cursor/rules/rfdtech-ui.mdc${rulesChanged ? " (updated)" : " (already set)"}, ` +
+            `.cursor/rules/image-to-components.mdc${imageRulesChanged ? " (updated)" : " (already set)"}`,
+    };
+}

package/dist/mcp/installers/doctor.js

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { GENERATED_DIR, hasRepoSource } from "../paths.js";
+import * as claude from "./claude.js";
+import * as cursor from "./cursor.js";
+import * as codex from "./codex.js";
+import * as opencode from "./opencode.js";
+export async function runDoctor(cwd = process.cwd()) {
+    console.log("Checking AI setup...\n");
+    const metaPath = path.join(GENERATED_DIR, "index.meta.json");
+    if (existsSync(metaPath)) {
+        const meta = JSON.parse(await readFile(metaPath, "utf8"));
+        console.log(`✓ Index found — ${meta.componentCount} components, ${meta.exampleCount} examples, ` +
+            `${meta.ruleCount} rules, ${meta.tokenCount} tokens`);
+    }
+    else if (hasRepoSource) {
+        console.log("✗ Index missing — run `rfdui index` (or just start the MCP server, which builds it automatically)");
+    }
+    else {
+        console.log("✗ No bundled index found in this install — the package may be corrupt; try reinstalling");
+    }
+    const tools = [
+        { name: "Claude Code", ok: claude.detect(cwd) },
+        { name: "Cursor", ok: cursor.detect(cwd) },
+        { name: "Codex", ok: codex.detect() },
+        { name: "OpenCode", ok: opencode.detect(cwd) },
+    ];
+    for (const t of tools) {
+        console.log(`${t.ok ? "✓" : "•"} ${t.name}${t.ok ? " detected" : " not detected"}`);
+    }
+    console.log(hasRepoSource
+        ? "\n✓ Running inside the gsl-components repo — index rebuilds automatically when source changes."
+        : "\n• Running as an installed package — serving the bundled index snapshot (no live rebuild).");
+    console.log("\nRun `rfdui setup` to (re)configure detected tools.");
+}

package/dist/mcp/installers/opencode.js

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { appendPointerOnce, readJsonIfExists, writeJson } from "./util.js";
+export function detect(cwd) {
+    return (existsSync(path.join(cwd, "opencode.json")) ||
+        existsSync(path.join(os.homedir(), ".config", "opencode")));
+}
+// Verified against https://opencode.ai/docs/mcp-servers/ and
+// https://opencode.ai/docs/config/: top-level `mcp` key in a project-root
+// `opencode.json`, each entry `{ type: "local", command: [...], enabled }`.
+export async function install(cwd) {
+    const configPath = path.join(cwd, "opencode.json");
+    const existing = await readJsonIfExists(configPath);
+    const isNewFile = !existing;
+    const data = existing && typeof existing === "object" ? { ...existing } : {};
+    if (isNewFile)
+        data.$schema ??= "https://opencode.ai/config.json";
+    const mcp = { ...data.mcp };
+    const desired = { type: "local", command: ["npx", "-y", "@rfdtech/components-mcp"], enabled: true };
+    const already = JSON.stringify(mcp["rfdtech-ui"]) === JSON.stringify(desired);
+    mcp["rfdtech-ui"] = desired;
+    data.mcp = mcp;
+    await writeJson(configPath, data);
+    const agentsChanged = await appendPointerOnce(path.join(cwd, "AGENTS.md"), "rfdtech-ui", "<!-- rfdtech-ui -->\nUse the `rfdtech-ui` MCP server (`search_components`, `get_component`, " +
+        "`get_rules`) before building UI with `@rfdtech/components`. Given a screenshot, image, " +
+        "mockup, or description of a screen to build, decompose it and map every element to an " +
+        "existing `@rfdtech/components` component/variant via the MCP before writing markup — " +
+        "only build custom UI if the user explicitly asks for it.\n", "Agent notes");
+    const changed = !already || agentsChanged;
+    return {
+        name: "OpenCode",
+        changed,
+        detail: `opencode.json${already ? " (already set)" : " (updated)"}, AGENTS.md${agentsChanged ? " (updated)" : " (already set)"}`,
+    };
+}

package/dist/mcp/installers/setup.js

@@ -0,0 +1,34 @@
+import { mkdir, copyFile } from "node:fs/promises";
+import path from "node:path";
+import { SKILL_SOURCE_PATH, SKILL_IMAGE_SOURCE_PATH } from "../paths.js";
+import * as claude from "./claude.js";
+import * as cursor from "./cursor.js";
+import * as codex from "./codex.js";
+import * as opencode from "./opencode.js";
+export async function runSetup(cwd = process.cwd()) {
+    console.log("rfdui setup — detecting AI tools...\n");
+    // Always drop the cross-tool skills, regardless of which specific tool (if any) is detected.
+    const aiDir = path.join(cwd, ".ai");
+    await mkdir(aiDir, { recursive: true });
+    await copyFile(SKILL_SOURCE_PATH, path.join(aiDir, "SKILL.md"));
+    await copyFile(SKILL_IMAGE_SOURCE_PATH, path.join(aiDir, "image-to-components.md"));
+    console.log("✓ .ai/SKILL.md, .ai/image-to-components.md written\n");
+    const results = [];
+    if (claude.detect(cwd))
+        results.push(await claude.install(cwd, SKILL_SOURCE_PATH, SKILL_IMAGE_SOURCE_PATH));
+    if (cursor.detect(cwd))
+        results.push(await cursor.install(cwd, SKILL_SOURCE_PATH, SKILL_IMAGE_SOURCE_PATH));
+    if (codex.detect())
+        results.push(await codex.install());
+    if (opencode.detect(cwd))
+        results.push(await opencode.install(cwd));
+    if (results.length === 0) {
+        console.log("No supported AI tool detected (looked for .claude/, .mcp.json, .cursor/, ~/.codex/, " +
+            "opencode.json, ~/.config/opencode).\n" +
+            "The MCP server is still available directly: `npx @rfdtech/components-mcp` or `rfdui mcp`.");
+        return;
+    }
+    for (const r of results) {
+        console.log(`${r.changed ? "✓" : "•"} ${r.name}: ${r.detail}`);
+    }
+}

package/dist/mcp/installers/util.js

@@ -0,0 +1,41 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export async function readJsonIfExists(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeJson(filePath, data) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+/** The MCP server identity every installer wires up, consistently named across tools. */
+export const MCP_SERVER_NAME = "rfdtech-ui";
+export const MCP_SERVER_COMMAND = { command: "npx", args: ["-y", "@rfdtech/components-mcp"] };
+/** Merge `{ mcpServers: { "rfdtech-ui": {...} } }` into an existing config object without touching anything else. */
+export function mergeMcpServers(existing) {
+    const data = existing && typeof existing === "object" ? { ...existing } : {};
+    const servers = { ...data.mcpServers };
+    const already = JSON.stringify(servers[MCP_SERVER_NAME]) === JSON.stringify(MCP_SERVER_COMMAND);
+    servers[MCP_SERVER_NAME] = MCP_SERVER_COMMAND;
+    data.mcpServers = servers;
+    return { data, changed: !already };
+}
+/** Append `marker`-tagged content to a markdown file once; no-op if already present. */
+export async function appendPointerOnce(filePath, marker, block, fallbackHeading) {
+    if (existsSync(filePath)) {
+        const content = await readFile(filePath, "utf8");
+        if (content.includes(marker))
+            return false;
+        await writeFile(filePath, content.replace(/\s*$/, "") + "\n\n" + block, "utf8");
+        return true;
+    }
+    await writeFile(filePath, `# ${fallbackHeading}\n\n${block}`, "utf8");
+    return true;
+}