@matchkit.io/cli 0.1.0

package/dist/commands/add.d.ts

@@ -0,0 +1 @@
+export declare function addCommand(componentName: string): Promise<void>;

package/dist/commands/add.js

@@ -0,0 +1,84 @@
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { readConfig } from "../utils/config.js";
+import { fetchComponent, fetchRegistry, isComponentInstalled, } from "../utils/registry.js";
+export async function addCommand(componentName) {
+    const s = p.spinner();
+    try {
+        const config = readConfig();
+        // 1. Fetch the registry to find the component
+        s.start(`Resolving ${pc.cyan(componentName)}...`);
+        const registry = await fetchRegistry(config);
+        const component = registry.components.find((c) => c.name === componentName);
+        if (!component) {
+            s.stop(`Component ${pc.red(componentName)} not found`);
+            const available = registry.components.map((c) => c.name).join(", ");
+            p.log.error(`Component "${componentName}" not found in the ${config.theme} registry.\n\nAvailable: ${pc.dim(available)}`);
+            process.exit(1);
+        }
+        // 2. Check if already installed
+        if (isComponentInstalled(config.skillDir, component.file)) {
+            s.stop(`${pc.yellow(componentName)} already installed`);
+            const overwrite = await p.confirm({
+                message: `${componentName} is already installed. Overwrite?`,
+            });
+            if (p.isCancel(overwrite) || !overwrite) {
+                p.cancel("Cancelled.");
+                process.exit(0);
+            }
+            s.start(`Fetching ${pc.cyan(componentName)}...`);
+        }
+        // 3. Resolve registry dependencies (install those first)
+        const toInstall = [];
+        if (component.registryDependencies.length > 0) {
+            for (const dep of component.registryDependencies) {
+                if (!isComponentInstalled(config.skillDir, `components/${dep}.tsx`)) {
+                    toInstall.push(dep);
+                }
+            }
+        }
+        // 4. Fetch and write the component (and deps)
+        const allComponents = [componentName, ...toInstall];
+        const installed = [];
+        const npmDeps = [...component.dependencies];
+        for (const name of allComponents) {
+            const data = await fetchComponent(config, name);
+            const targetPath = join(process.cwd(), config.skillDir, `components/${name}.tsx`);
+            // Ensure directory exists
+            const dir = dirname(targetPath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            writeFileSync(targetPath, data.source);
+            installed.push(name);
+            // Collect npm dependencies
+            for (const d of data.dependencies) {
+                if (!npmDeps.includes(d)) {
+                    npmDeps.push(d);
+                }
+            }
+        }
+        s.stop(`Installed ${pc.green(installed.length.toString())} component(s)`);
+        // 5. Summary
+        const lines = [
+            `${pc.cyan("Component:")}  ${componentName} (Layer ${component.layer})`,
+            `${pc.cyan("Path:")}       ${config.skillDir}/components/${componentName}.tsx`,
+        ];
+        if (toInstall.length > 0) {
+            lines.push(`${pc.cyan("Dependencies:")} ${toInstall.map((d) => pc.dim(d)).join(", ")}`);
+        }
+        if (npmDeps.length > 0) {
+            lines.push("");
+            lines.push(`${pc.yellow("npm dependencies needed:")}`);
+            lines.push(`  npm install ${npmDeps.join(" ")}`);
+        }
+        p.note(lines.join("\n"), "Added");
+    }
+    catch (err) {
+        s.stop("Failed");
+        p.log.error(err instanceof Error ? err.message : "An unknown error occurred");
+        process.exit(1);
+    }
+}

package/dist/commands/diff.d.ts

@@ -0,0 +1 @@
+export declare function diffCommand(): Promise<void>;

package/dist/commands/diff.js

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { readConfig, configExists } from "../utils/config.js";
+import { fetchRegistry } from "../utils/registry.js";
+export async function diffCommand() {
+    if (!configExists()) {
+        p.log.error("No .matchkit/config.json found. Run `matchkit init` first.");
+        process.exit(1);
+    }
+    const config = readConfig();
+    const s = p.spinner();
+    s.start("Comparing local vs registry...");
+    try {
+        const registry = await fetchRegistry(config);
+        s.stop("Registry fetched");
+        const results = {
+            missing: [],
+            installed: [],
+        };
+        for (const component of registry.components) {
+            const localPath = join(process.cwd(), config.skillDir, component.file);
+            if (existsSync(localPath)) {
+                results.installed.push(component);
+            }
+            else {
+                results.missing.push(component);
+            }
+        }
+        console.log("");
+        console.log(`  ${pc.cyan(config.theme + "-ui")} · ${results.installed.length} installed, ${results.missing.length} missing`);
+        console.log("");
+        if (results.missing.length > 0) {
+            console.log(`  ${pc.yellow("Missing components:")}`);
+            for (const c of results.missing) {
+                console.log(`    ${pc.dim("○")} ${c.name}`);
+            }
+            console.log("");
+            console.log(`  Run ${pc.cyan("matchkit add <name>")} to install missing components.`);
+        }
+        else {
+            console.log(`  ${pc.green("All components are installed.")} Your skill is complete.`);
+        }
+        console.log("");
+    }
+    catch (err) {
+        s.stop("Failed");
+        p.log.error(err instanceof Error ? err.message : "Unknown error");
+        process.exit(1);
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,211 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { configExists, writeConfig, createDefaultConfig } from "../utils/config.js";
+import { isAuthenticated, authFetch, API_BASE_URL } from "../utils/auth.js";
+const THEMES = [
+    { value: "clarity", label: "Clarity UI", hint: "Free — Sharp, structured B2B SaaS" },
+    { value: "soft", label: "Soft UI", hint: "Pro — Warm-minimal for AI tools" },
+    { value: "brutal", label: "Brutal UI", hint: "Pro — Neobrutalism — bold, graphic" },
+    { value: "glass", label: "Glass UI", hint: "Pro — Technical, translucent" },
+];
+const ACCENT_PRESETS = [
+    { value: "#4F46E5", label: "Indigo" },
+    { value: "#0EA5E9", label: "Sky Blue" },
+    { value: "#10B981", label: "Emerald" },
+    { value: "#F59E0B", label: "Amber" },
+    { value: "#EF4444", label: "Red" },
+    { value: "#8B5CF6", label: "Violet" },
+    { value: "#EC4899", label: "Pink" },
+    { value: "custom", label: "Custom hex" },
+];
+export async function initCommand() {
+    p.intro(pc.bgCyan(pc.black(" matchkit init ")));
+    if (configExists()) {
+        const shouldOverwrite = await p.confirm({
+            message: "A .matchkit/config.json already exists. Overwrite it?",
+        });
+        if (p.isCancel(shouldOverwrite) || !shouldOverwrite) {
+            p.cancel("Init cancelled.");
+            process.exit(0);
+        }
+    }
+    // Step 1: Pick theme
+    const theme = await p.select({
+        message: "Pick a theme:",
+        options: THEMES,
+    });
+    if (p.isCancel(theme)) {
+        p.cancel("Init cancelled.");
+        process.exit(0);
+    }
+    // Premium themes require authentication
+    if (theme !== "clarity" && !isAuthenticated()) {
+        p.log.warn(`${pc.bold(String(theme))} is a premium theme. Run ${pc.bold("matchkit login")} first.`);
+        p.log.info(`Get your API key at ${pc.cyan("matchkit.io/app/keys")}`);
+        p.outro(`Or use ${pc.bold("clarity")} (free) — all 27 components, no account needed.`);
+        process.exit(0);
+    }
+    // Step 2: Pick accent color
+    const accentChoice = await p.select({
+        message: "Pick an accent color:",
+        options: ACCENT_PRESETS,
+    });
+    if (p.isCancel(accentChoice)) {
+        p.cancel("Init cancelled.");
+        process.exit(0);
+    }
+    let accent = accentChoice;
+    if (accent === "custom") {
+        const customHex = await p.text({
+            message: "Enter a hex color (e.g. #FF6B35):",
+            validate: (val) => {
+                if (!/^#[0-9A-Fa-f]{6}$/.test(val)) {
+                    return "Please enter a valid hex color (e.g. #FF6B35)";
+                }
+            },
+        });
+        if (p.isCancel(customHex)) {
+            p.cancel("Init cancelled.");
+            process.exit(0);
+        }
+        accent = customHex;
+    }
+    // Step 3: Use default axes or customize
+    const useDefaults = await p.confirm({
+        message: "Use default axis settings for this theme?",
+        initialValue: true,
+    });
+    if (p.isCancel(useDefaults)) {
+        p.cancel("Init cancelled.");
+        process.exit(0);
+    }
+    let overrides = {};
+    if (!useDefaults) {
+        const radius = await p.select({
+            message: "Corner style (radius):",
+            options: [
+                { value: "sm", label: "Sharp", hint: "2-4px" },
+                { value: "md", label: "Moderate", hint: "4-8px" },
+                { value: "lg", label: "Rounded", hint: "8-12px" },
+                { value: "xl", label: "Pill", hint: "12-16px" },
+            ],
+        });
+        if (p.isCancel(radius)) {
+            p.cancel("Init cancelled.");
+            process.exit(0);
+        }
+        const buttonStyle = await p.select({
+            message: "Button style:",
+            options: [
+                { value: "filled", label: "Filled", hint: "Solid background" },
+                { value: "outline", label: "Outline", hint: "Border only" },
+                { value: "ghost", label: "Ghost", hint: "No background or border" },
+                { value: "soft-fill", label: "Soft fill", hint: "Muted background" },
+            ],
+        });
+        if (p.isCancel(buttonStyle)) {
+            p.cancel("Init cancelled.");
+            process.exit(0);
+        }
+        const density = await p.select({
+            message: "Spacing density:",
+            options: [
+                { value: "compact", label: "Compact", hint: "Tight spacing" },
+                { value: "default", label: "Default", hint: "Standard spacing" },
+                { value: "spacious", label: "Spacious", hint: "Generous spacing" },
+            ],
+        });
+        if (p.isCancel(density)) {
+            p.cancel("Init cancelled.");
+            process.exit(0);
+        }
+        overrides = {
+            radius: radius,
+            "button-style": buttonStyle,
+            "spacing-density": density,
+        };
+    }
+    // Write local config first
+    const config = createDefaultConfig(theme, accent, overrides);
+    writeConfig(config);
+    // Step 4: Link to a server-side project (premium + authenticated only)
+    let linkedConfigId;
+    if (theme !== "clarity" && isAuthenticated()) {
+        const s = p.spinner();
+        s.start("Checking your projects...");
+        try {
+            const res = await authFetch(`${API_BASE_URL}/api/v1/configs`);
+            if (res.ok) {
+                const userConfigs = (await res.json());
+                // Filter to configs matching the selected theme
+                const matching = userConfigs.filter((c) => c.theme === theme);
+                s.stop(matching.length > 0
+                    ? `Found ${matching.length} ${theme} project${matching.length > 1 ? "s" : ""}`
+                    : "No projects found");
+                if (matching.length > 0) {
+                    const choice = await p.select({
+                        message: "Link to an existing project?",
+                        options: [
+                            ...matching.map((c) => ({
+                                value: c.id,
+                                label: c.name,
+                                hint: `${c.id} · v${c.version}`,
+                            })),
+                            {
+                                value: "__skip__",
+                                label: "Skip — just use local config",
+                                hint: "You can link later",
+                            },
+                        ],
+                    });
+                    if (!p.isCancel(choice) && choice !== "__skip__") {
+                        linkedConfigId = choice;
+                    }
+                }
+                else {
+                    p.log.info(`No ${pc.bold(String(theme))} projects found. Create one at ${pc.cyan("matchkit.io/app")}`);
+                }
+            }
+            else {
+                s.stop("Could not fetch projects");
+            }
+        }
+        catch {
+            s.stop("Offline — skipping project linking");
+        }
+        // Update config with configId if linked
+        if (linkedConfigId) {
+            const updatedConfig = { ...config, configId: linkedConfigId };
+            writeConfig(updatedConfig);
+            p.log.success(`Linked to ${pc.dim(linkedConfigId)}`);
+        }
+    }
+    // Summary
+    const summaryLines = [
+        `${pc.cyan("Theme:")}        ${theme}`,
+        `${pc.cyan("Accent:")}       ${accent}`,
+        `${pc.cyan("Overrides:")}    ${Object.keys(overrides).length === 0 ? "defaults" : Object.entries(overrides).map(([k, v]) => `${k}=${v}`).join(", ")}`,
+        `${pc.cyan("Config:")}       .matchkit/config.json`,
+        `${pc.cyan("Skill dir:")}    ${config.skillDir}`,
+    ];
+    if (linkedConfigId) {
+        summaryLines.push(`${pc.cyan("Project ID:")}   ${linkedConfigId}`);
+        summaryLines.push("");
+        summaryLines.push(`Next steps:`);
+        summaryLines.push(`  ${pc.green("matchkit pull")}          Sync your design system`);
+        summaryLines.push(`  ${pc.green("matchkit list")}          See all available components`);
+    }
+    else {
+        summaryLines.push("");
+        summaryLines.push(`Next steps:`);
+        summaryLines.push(`  ${pc.green("matchkit add button")}    Add your first component`);
+        summaryLines.push(`  ${pc.green("matchkit list")}          See all available components`);
+    }
+    p.note(summaryLines.join("\n"), "Configuration saved");
+    // Gentle upsell for free users
+    if (theme === "clarity" && !isAuthenticated()) {
+        p.log.info(pc.dim("Unlock 3 more themes + custom axes → ") +
+            pc.cyan("matchkit.io/configure"));
+    }
+    p.outro(pc.green("MatchKit initialized!"));
+}

package/dist/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function listCommand(): Promise<void>;

package/dist/commands/list.js

@@ -0,0 +1,58 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { readConfig, configExists } from "../utils/config.js";
+import { loadLocalRegistry, isComponentInstalled, fetchRegistry, } from "../utils/registry.js";
+export async function listCommand() {
+    if (!configExists()) {
+        p.log.error("No .matchkit/config.json found. Run `matchkit init` first.");
+        process.exit(1);
+    }
+    const config = readConfig();
+    const s = p.spinner();
+    // Try local registry first, fall back to remote
+    let components;
+    const localRegistry = loadLocalRegistry(config.skillDir);
+    if (localRegistry) {
+        components = localRegistry.components;
+    }
+    else {
+        s.start("Fetching component registry...");
+        try {
+            const registry = await fetchRegistry(config);
+            components = registry.components;
+            s.stop("Registry loaded");
+        }
+        catch (err) {
+            s.stop("Failed to fetch registry");
+            p.log.error(err instanceof Error ? err.message : "Unknown error");
+            process.exit(1);
+        }
+    }
+    // Group by layer
+    const layer1 = components.filter((c) => c.layer === 1);
+    const layer2 = components.filter((c) => c.layer === 2);
+    const formatComponent = (c) => {
+        const installed = isComponentInstalled(config.skillDir, c.file);
+        const status = installed
+            ? pc.green("●")
+            : pc.dim("○");
+        const name = installed ? pc.white(c.name) : pc.dim(c.name);
+        return `  ${status} ${name.padEnd(24)} ${pc.dim(c.description)}`;
+    };
+    const installedCount = components.filter((c) => isComponentInstalled(config.skillDir, c.file)).length;
+    console.log("");
+    console.log(`  ${pc.cyan(config.theme + "-ui")} · ${pc.dim(`${installedCount}/${components.length} installed`)}`);
+    console.log("");
+    console.log(`  ${pc.bold("Layer 1 — Primitives")} (${layer1.length})`);
+    for (const c of layer1) {
+        console.log(formatComponent(c));
+    }
+    console.log("");
+    console.log(`  ${pc.bold("Layer 2 — Composites")} (${layer2.length})`);
+    for (const c of layer2) {
+        console.log(formatComponent(c));
+    }
+    console.log("");
+    console.log(`  ${pc.green("●")} installed  ${pc.dim("○")} available — use ${pc.cyan("matchkit add <name>")} to install`);
+    console.log("");
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,3 @@
+export declare function loginCommand(options?: {
+    key?: string;
+}): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,140 @@
+import * as http from "node:http";
+import { exec } from "node:child_process";
+import { platform } from "node:os";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { saveApiKey, getApiKey, API_BASE_URL } from "../utils/auth.js";
+/**
+ * Open a URL in the user's default browser.
+ */
+function openBrowser(url) {
+    const cmd = platform() === "darwin"
+        ? "open"
+        : platform() === "win32"
+            ? "start"
+            : "xdg-open";
+    exec(`${cmd} "${url}"`);
+}
+/**
+ * Verify an API key by hitting the user endpoint.
+ */
+async function verifyKey(apiKey) {
+    try {
+        const res = await fetch(`${API_BASE_URL}/api/v1/user`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+export async function loginCommand(options) {
+    p.intro(pc.bold("matchkit login"));
+    const existing = getApiKey();
+    if (existing) {
+        const overwrite = await p.confirm({
+            message: "You already have an API key stored. Replace it?",
+        });
+        if (p.isCancel(overwrite) || !overwrite) {
+            p.outro("Keeping existing key.");
+            return;
+        }
+    }
+    // --key flag or non-interactive: fall back to manual key entry
+    if (options?.key || !process.stdin.isTTY) {
+        const apiKey = options?.key ?? process.env.MATCHKIT_API_KEY;
+        if (!apiKey) {
+            p.log.error("No API key provided. Use --key <key> or set MATCHKIT_API_KEY.");
+            process.exit(1);
+        }
+        const s = p.spinner();
+        s.start("Verifying key...");
+        const user = await verifyKey(apiKey);
+        if (!user) {
+            s.stop("Invalid API key");
+            p.log.error("This API key is not valid. Check it and try again.");
+            process.exit(1);
+        }
+        s.stop("Key verified");
+        saveApiKey(apiKey);
+        p.log.success(`Logged in as ${pc.bold(user.email ?? "unknown")}`);
+        p.outro("Key stored in " + pc.dim("~/.matchkit/credentials"));
+        return;
+    }
+    // Browser-based auth flow
+    const s = p.spinner();
+    const callbackPromise = new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://127.0.0.1`);
+            if (url.pathname === "/callback") {
+                const key = url.searchParams.get("key");
+                res.writeHead(200, {
+                    "Content-Type": "text/html",
+                    "Connection": "close",
+                });
+                res.end(`
+          <html>
+            <body style="font-family: -apple-system, sans-serif; display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0; background: #FAF7F2;">
+              <div style="text-align: center;">
+                <div style="font-size: 48px; margin-bottom: 12px;">&#10003;</div>
+                <h2 style="color: #1A1916; margin-bottom: 8px;">Authenticated</h2>
+                <p style="color: #8A8579;">You can close this tab and return to your terminal.</p>
+              </div>
+            </body>
+          </html>
+        `);
+                server.close();
+                clearTimeout(timer);
+                if (key) {
+                    resolve(key);
+                }
+                else {
+                    reject(new Error("No API key received in callback"));
+                }
+            }
+            else {
+                res.writeHead(404);
+                res.end("Not found");
+            }
+        });
+        const timer = setTimeout(() => {
+            server.close();
+            reject(new Error("Login timed out after 2 minutes. Try again."));
+        }, 120_000);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const loginUrl = `${API_BASE_URL}/cli-auth?port=${addr.port}`;
+            p.log.info(`Opening browser to ${pc.cyan(loginUrl)}`);
+            openBrowser(loginUrl);
+            s.start("Waiting for browser authentication...");
+        });
+    });
+    try {
+        const key = await callbackPromise;
+        s.stop("Key received");
+        const vs = p.spinner();
+        vs.start("Verifying key...");
+        const user = await verifyKey(key);
+        if (!user) {
+            vs.stop("Verification failed");
+            p.log.error("The received key could not be verified. Try again.");
+            process.exit(1);
+        }
+        vs.stop("Key verified");
+        saveApiKey(key);
+        p.log.success(`Logged in as ${pc.bold(user.email ?? "unknown")}`);
+        p.log.info(`Tier: ${pc.cyan(user.tier ?? "free")}`);
+        p.log.info(`Key stored in ${pc.dim("~/.matchkit/credentials")}`);
+        p.outro("Run " +
+            pc.bold("matchkit init") +
+            " to link a project.");
+    }
+    catch (err) {
+        s.stop("Login failed");
+        p.log.error(err instanceof Error ? err.message : "Could not complete login.");
+        process.exit(1);
+    }
+}

package/dist/commands/pull.d.ts

@@ -0,0 +1 @@
+export declare function pullCommand(): Promise<void>;

package/dist/commands/pull.js

@@ -0,0 +1,112 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { readConfig, configExists, writeConfig } from "../utils/config.js";
+import { getApiKey, authFetch, API_BASE_URL } from "../utils/auth.js";
+export async function pullCommand() {
+    p.intro(pc.bold("matchkit pull"));
+    // Check auth
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        p.log.error("Not logged in. Run " + pc.bold("matchkit login") + " first.");
+        process.exit(1);
+    }
+    // Check config
+    if (!configExists()) {
+        p.log.error("No .matchkit/config.json found. Run " +
+            pc.bold("matchkit init") +
+            " first.");
+        process.exit(1);
+    }
+    const config = readConfig();
+    const configId = config.configId;
+    if (!configId) {
+        p.log.error("No configId in .matchkit/config.json. This project was set up before the hosted resolution model.");
+        p.log.info("Create a config at " +
+            pc.cyan("matchkit.io/app") +
+            " and run " +
+            pc.bold("matchkit init") +
+            " again.");
+        process.exit(1);
+    }
+    const s = p.spinner();
+    s.start("Pulling latest design system...");
+    try {
+        // Get the download from the server — may return JSON with downloadUrl
+        // or stream the ZIP directly (when R2 is unavailable)
+        const pullRes = await authFetch(`${API_BASE_URL}/api/v1/configs/${configId}/pull`);
+        if (!pullRes.ok) {
+            const err = await pullRes.json().catch(() => ({}));
+            s.stop("Pull failed");
+            p.log.error(err.error ?? `Server returned ${pullRes.status}`);
+            process.exit(1);
+        }
+        let zipBuffer;
+        let buildId;
+        let version;
+        let theme;
+        const contentType = pullRes.headers.get("content-type") ?? "";
+        if (contentType.includes("application/zip")) {
+            // Server streamed the ZIP directly (R2 unavailable)
+            zipBuffer = await pullRes.arrayBuffer();
+            buildId = pullRes.headers.get("x-build-id") ?? "unknown";
+            version = parseInt(pullRes.headers.get("x-version") ?? "0", 10);
+            theme = pullRes.headers.get("x-theme") ?? config.theme;
+        }
+        else {
+            // Server returned JSON with R2 download URL
+            const pullData = await pullRes.json();
+            buildId = pullData.buildId;
+            version = pullData.version;
+            theme = pullData.theme;
+            s.message("Downloading package...");
+            // Download the ZIP from R2
+            const zipRes = await fetch(pullData.downloadUrl);
+            if (!zipRes.ok) {
+                s.stop("Download failed");
+                p.log.error(`Failed to download package: ${zipRes.status}`);
+                process.exit(1);
+            }
+            zipBuffer = await zipRes.arrayBuffer();
+        }
+        s.message("Extracting components...");
+        // Extract ZIP using JSZip (dynamic import to keep CLI startup fast)
+        const JSZip = (await import("jszip")).default;
+        const zip = await JSZip.loadAsync(zipBuffer);
+        const skillDir = config.skillDir;
+        const fullSkillDir = join(process.cwd(), skillDir);
+        // Ensure skill directory exists
+        if (!existsSync(fullSkillDir)) {
+            mkdirSync(fullSkillDir, { recursive: true });
+        }
+        let fileCount = 0;
+        for (const [path, entry] of Object.entries(zip.files)) {
+            if (entry.dir)
+                continue;
+            const content = await entry.async("string");
+            const fullPath = join(fullSkillDir, path);
+            const dir = dirname(fullPath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            writeFileSync(fullPath, content);
+            fileCount++;
+        }
+        // Update local config version
+        const updatedConfig = {
+            ...config,
+            configId,
+        };
+        writeConfig(updatedConfig);
+        s.stop(`Extracted ${fileCount} files`);
+        p.log.success(`${pc.bold(theme + "-ui")} v${version} → ${pc.dim(skillDir)}`);
+        p.log.info(`Build: ${pc.dim(buildId)}`);
+        p.outro("Design system is up to date.");
+    }
+    catch (err) {
+        s.stop("Pull failed");
+        p.log.error(err instanceof Error ? err.message : "An unexpected error occurred");
+        process.exit(1);
+    }
+}

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function statusCommand(): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,53 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { readConfig, configExists } from "../utils/config.js";
+import { getApiKey, authFetch, API_BASE_URL } from "../utils/auth.js";
+export async function statusCommand() {
+    p.intro(pc.bold("matchkit status"));
+    // Check config
+    if (!configExists()) {
+        p.log.error("No .matchkit/config.json found. Run " +
+            pc.bold("matchkit init") +
+            " first.");
+        process.exit(1);
+    }
+    const config = readConfig();
+    const configId = config.configId;
+    p.log.info(`Theme:  ${pc.bold(config.theme)}`);
+    p.log.info(`Accent: ${pc.bold(config.accent)}`);
+    p.log.info(`Dir:    ${pc.dim(config.skillDir)}`);
+    if (!configId) {
+        p.log.warn("No configId — this is a local-only config (free tier).");
+        p.outro("Upgrade at " + pc.cyan("matchkit.io/configure") + " for premium themes + CLI sync.");
+        return;
+    }
+    p.log.info(`Config: ${pc.dim(configId)}`);
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        p.log.warn("Not logged in — run " + pc.bold("matchkit login") + " to sync.");
+        p.outro("");
+        return;
+    }
+    const s = p.spinner();
+    s.start("Checking server...");
+    try {
+        const res = await authFetch(`${API_BASE_URL}/api/v1/configs/${configId}`);
+        if (!res.ok) {
+            s.stop("Could not reach server");
+            p.log.warn("Config not found on server or access denied.");
+            p.outro("");
+            return;
+        }
+        const serverConfig = await res.json();
+        s.stop("Synced");
+        p.log.info(`Version:  ${pc.bold(String(serverConfig.version))}`);
+        p.log.info(`Build:    ${pc.dim(serverConfig.buildId ?? "not built")}`);
+        p.log.info(`Updated:  ${pc.dim(new Date(serverConfig.updatedAt).toLocaleDateString())}`);
+        p.outro("Use " + pc.bold("matchkit pull") + " to update your local files.");
+    }
+    catch {
+        s.stop("Connection failed");
+        p.log.warn("Could not connect to matchkit.io.");
+        p.outro("");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { initCommand } from "./commands/init.js";
+import { addCommand } from "./commands/add.js";
+import { listCommand } from "./commands/list.js";
+import { diffCommand } from "./commands/diff.js";
+import { loginCommand } from "./commands/login.js";
+import { pullCommand } from "./commands/pull.js";
+import { statusCommand } from "./commands/status.js";
+const program = new Command();
+program
+    .name("matchkit")
+    .description("MatchKit — style-agnostic design system CLI")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Initialize a MatchKit design system in your project")
+    .action(initCommand);
+program
+    .command("add")
+    .description("Add a component to your project")
+    .argument("<component>", "Component name (e.g. button, data-table)")
+    .action(addCommand);
+program
+    .command("list")
+    .description("List all available components and their install status")
+    .action(listCommand);
+program
+    .command("diff")
+    .description("Show changes between local components and the registry")
+    .action(diffCommand);
+program
+    .command("login")
+    .description("Authenticate with MatchKit (opens browser)")
+    .option("--key <key>", "API key for non-interactive login (CI/CD)")
+    .action(loginCommand);
+program
+    .command("pull")
+    .description("Pull your latest resolved design system from the server")
+    .action(pullCommand);
+program
+    .command("status")
+    .description("Show current config, version, and sync status")
+    .action(statusCommand);
+program.parse();

package/dist/utils/auth.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI authentication utilities.
+ *
+ * API key stored globally in ~/.matchkit/credentials (not per-project).
+ * Also supports MATCHKIT_API_KEY env var for CI/CD.
+ */
+/** Base URL for the MatchKit API. Override via MATCHKIT_API_URL for dev. */
+export declare const API_BASE_URL: string;
+export interface Credentials {
+    apiKey: string;
+}
+/**
+ * Read the stored API key.
+ * Priority: MATCHKIT_API_KEY env var > ~/.matchkit/credentials file.
+ */
+export declare function getApiKey(): string | null;
+/**
+ * Store an API key in ~/.matchkit/credentials.
+ */
+export declare function saveApiKey(apiKey: string): void;
+/**
+ * Check if the user is authenticated (has an API key).
+ */
+export declare function isAuthenticated(): boolean;
+/**
+ * Get auth headers for API requests.
+ */
+export declare function getAuthHeaders(): Record<string, string>;
+/**
+ * Make an authenticated fetch request to the MatchKit API.
+ */
+export declare function authFetch(url: string, options?: RequestInit): Promise<Response>;

package/dist/utils/auth.js

@@ -0,0 +1,71 @@
+/**
+ * CLI authentication utilities.
+ *
+ * API key stored globally in ~/.matchkit/credentials (not per-project).
+ * Also supports MATCHKIT_API_KEY env var for CI/CD.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/** Base URL for the MatchKit API. Override via MATCHKIT_API_URL for dev. */
+export const API_BASE_URL = process.env.MATCHKIT_API_URL ?? "https://www.matchkit.io";
+const CREDENTIALS_DIR = join(homedir(), ".matchkit");
+const CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials");
+/**
+ * Read the stored API key.
+ * Priority: MATCHKIT_API_KEY env var > ~/.matchkit/credentials file.
+ */
+export function getApiKey() {
+    // 1. Check environment variable (for CI/CD)
+    const envKey = process.env.MATCHKIT_API_KEY;
+    if (envKey)
+        return envKey;
+    // 2. Check credentials file
+    if (!existsSync(CREDENTIALS_FILE))
+        return null;
+    try {
+        const content = readFileSync(CREDENTIALS_FILE, "utf-8");
+        const creds = JSON.parse(content);
+        return creds.apiKey || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Store an API key in ~/.matchkit/credentials.
+ */
+export function saveApiKey(apiKey) {
+    if (!existsSync(CREDENTIALS_DIR)) {
+        mkdirSync(CREDENTIALS_DIR, { recursive: true });
+    }
+    const creds = { apiKey };
+    writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2) + "\n", {
+        mode: 0o600, // read/write only for owner
+    });
+}
+/**
+ * Check if the user is authenticated (has an API key).
+ */
+export function isAuthenticated() {
+    return getApiKey() !== null;
+}
+/**
+ * Get auth headers for API requests.
+ */
+export function getAuthHeaders() {
+    const apiKey = getApiKey();
+    if (!apiKey)
+        return {};
+    return { Authorization: `Bearer ${apiKey}` };
+}
+/**
+ * Make an authenticated fetch request to the MatchKit API.
+ */
+export async function authFetch(url, options = {}) {
+    const headers = {
+        ...getAuthHeaders(),
+        ...(options.headers ?? {}),
+    };
+    return fetch(url, { ...options, headers });
+}

package/dist/utils/config.d.ts

@@ -0,0 +1,17 @@
+export interface MatchKitConfig {
+    $schema?: string;
+    version: string;
+    theme: string;
+    accent: string;
+    overrides: Record<string, string>;
+    componentsDir: string;
+    skillDir: string;
+    registryUrl: string;
+    /** Server config ID for authenticated pull (premium themes) */
+    configId?: string;
+}
+export declare function getConfigPath(cwd?: string): string;
+export declare function configExists(cwd?: string): boolean;
+export declare function readConfig(cwd?: string): MatchKitConfig;
+export declare function writeConfig(config: MatchKitConfig, cwd?: string): void;
+export declare function createDefaultConfig(theme: string, accent: string, overrides?: Record<string, string>): MatchKitConfig;

package/dist/utils/config.js

@@ -0,0 +1,36 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+const CONFIG_FILE = ".matchkit/config.json";
+export function getConfigPath(cwd = process.cwd()) {
+    return join(cwd, CONFIG_FILE);
+}
+export function configExists(cwd = process.cwd()) {
+    return existsSync(getConfigPath(cwd));
+}
+export function readConfig(cwd = process.cwd()) {
+    const path = getConfigPath(cwd);
+    if (!existsSync(path)) {
+        throw new Error("No .matchkit/config.json found. Run `matchkit init` first.");
+    }
+    return JSON.parse(readFileSync(path, "utf-8"));
+}
+export function writeConfig(config, cwd = process.cwd()) {
+    const path = getConfigPath(cwd);
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+}
+export function createDefaultConfig(theme, accent, overrides = {}) {
+    return {
+        $schema: "https://matchkit.io/schemas/config.json",
+        version: "1.0.0",
+        theme,
+        accent,
+        overrides,
+        componentsDir: "src/components/ui",
+        skillDir: `.claude/skills/${theme}-ui`,
+        registryUrl: "https://www.matchkit.io/api/registry",
+    };
+}

package/dist/utils/registry.d.ts

@@ -0,0 +1,37 @@
+import type { MatchKitConfig } from "./config.js";
+export interface RegistryComponent {
+    name: string;
+    type: string;
+    layer: number;
+    description: string;
+    tags: string[];
+    category: string;
+    file: string;
+    dependencies: string[];
+    registryDependencies: string[];
+}
+export interface RegistryData {
+    $schema: string;
+    basePath: string;
+    components: RegistryComponent[];
+}
+/**
+ * Fetch the full registry for a theme from the registry API.
+ */
+export declare function fetchRegistry(config: MatchKitConfig): Promise<RegistryData>;
+/**
+ * Fetch a single component's source code from the registry API.
+ */
+export declare function fetchComponent(config: MatchKitConfig, name: string): Promise<{
+    source: string;
+    dependencies: string[];
+    registryDependencies: string[];
+}>;
+/**
+ * Load a local registry.json from the skill directory.
+ */
+export declare function loadLocalRegistry(skillDir: string): RegistryData | null;
+/**
+ * Check if a component is installed locally.
+ */
+export declare function isComponentInstalled(skillDir: string, componentFile: string): boolean;

package/dist/utils/registry.js

@@ -0,0 +1,50 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAuthHeaders } from "./auth.js";
+/**
+ * Fetch the full registry for a theme from the registry API.
+ */
+export async function fetchRegistry(config) {
+    const url = `${config.registryUrl}?theme=${encodeURIComponent(config.theme)}`;
+    // Include auth headers for premium themes (clarity is free, no auth needed)
+    const headers = config.theme !== "clarity" ? getAuthHeaders() : {};
+    const res = await fetch(url, { headers });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch registry: ${res.status} ${res.statusText}`);
+    }
+    return res.json();
+}
+/**
+ * Fetch a single component's source code from the registry API.
+ */
+export async function fetchComponent(config, name) {
+    const url = `${config.registryUrl}/component?theme=${encodeURIComponent(config.theme)}&name=${encodeURIComponent(name)}`;
+    const headers = config.theme !== "clarity" ? getAuthHeaders() : {};
+    const res = await fetch(url, { headers });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch component "${name}": ${res.status} ${res.statusText}`);
+    }
+    return res.json();
+}
+/**
+ * Load a local registry.json from the skill directory.
+ */
+export function loadLocalRegistry(skillDir) {
+    const registryPath = join(process.cwd(), skillDir, "registry.json");
+    if (!existsSync(registryPath))
+        return null;
+    try {
+        const content = readFileSync(registryPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a component is installed locally.
+ */
+export function isComponentInstalled(skillDir, componentFile) {
+    const filePath = join(process.cwd(), skillDir, componentFile);
+    return existsSync(filePath);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@matchkit.io/cli",
+  "version": "0.1.0",
+  "description": "CLI for MatchKit design system skills. Init projects, add components, manage your design system.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "matchkit": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0",
+    "commander": "^13.0.0",
+    "jszip": "^3.10.1",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.4.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Maes9/matchkit"
+  },
+  "homepage": "https://matchkit.io",
+  "license": "MIT"
+}