@matchkit.io/cli 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,154 @@
+# @matchkit.io/cli
+
+Command-line interface for MatchKit design system skills. Sync your design system, add components, and integrate with CI/CD pipelines.
+
+## Features
+
+- 🔐 **Browser-based authentication** - Secure OAuth flow via matchkit.io
+- 📦 **Component management** - Add individual components with automatic dependency resolution
+- 🔄 **Sync & update** - Pull latest design system updates from your MatchKit configuration
+- 🤖 **CI/CD ready** - Use API keys for automated deployments
+- 📊 **Status tracking** - See what's installed, what's available, and what's changed
+
+## Installation
+
+```bash
+npm install -g @matchkit.io/cli
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate (opens browser)
+matchkit login
+
+# 2. Initialize your project
+matchkit init
+
+# 3. Pull your design system
+matchkit pull
+```
+
+Your design system files are installed to `.claude/skills/[theme]-ui/` and work automatically with Claude Code, Cursor, VS Code, and Windsurf.
+
+## Commands
+
+### `matchkit login`
+
+Authenticate with MatchKit. Opens your browser to sign in, then saves your API key locally.
+
+```bash
+matchkit login
+```
+
+### `matchkit init`
+
+Initialize a MatchKit design system in your project. Links to your configuration on matchkit.io.
+
+```bash
+matchkit init
+```
+
+### `matchkit pull`
+
+Download your latest resolved design system from MatchKit.
+
+```bash
+matchkit pull
+```
+
+### `matchkit add <component>`
+
+Install a single component with its dependencies.
+
+```bash
+matchkit add button
+matchkit add data-table
+```
+
+### `matchkit list`
+
+Show all 27 components with their installation status.
+
+```bash
+matchkit list
+```
+
+### `matchkit status`
+
+Show current configuration, theme, version, and sync status.
+
+```bash
+matchkit status
+```
+
+### `matchkit diff`
+
+Show what changed since your last pull.
+
+```bash
+matchkit diff
+```
+
+## Configuration
+
+The CLI stores:
+- **Project config**: `.matchkit/config.json` (in your project)
+- **API key**: `~/.matchkit/credentials` (global, never committed)
+
+### .matchkit/config.json
+
+```json
+{
+  "$schema": "https://matchkit.io/schemas/config.json",
+  "configId": "cfg_a1b2c3d4e5f6",
+  "version": 3,
+  "theme": "soft",
+  "accent": "#14B8A6",
+  "overrides": { "radius": "xl", "button-style": "ghost" },
+  "componentsDir": "src/components/ui",
+  "skillDir": ".claude/skills/soft-ui",
+  "registryUrl": "https://matchkit.io/api/registry"
+}
+```
+
+## CI/CD Usage
+
+For automated deployments, set the `MATCHKIT_API_KEY` environment variable:
+
+```yaml
+# GitHub Actions
+- name: Pull MatchKit design system
+  env:
+    MATCHKIT_API_KEY: ${{ secrets.MATCHKIT_API_KEY }}
+  run: |
+    npm install -g @matchkit.io/cli
+    matchkit pull
+```
+
+Get your API key from https://matchkit.io/app/keys
+
+## How It Works
+
+1. **Authentication**: Browser OAuth flow creates an API key
+2. **Configuration**: Links your project to your MatchKit design system
+3. **Resolution**: Server-side resolution generates your personalized skill
+4. **Download**: ZIP download with all components, tokens, and documentation
+5. **Extraction**: Files land in `.claude/skills/[theme]-ui/`
+
+## Requirements
+
+- Node.js 18 or later
+- A MatchKit account (free tier available at https://matchkit.io)
+
+## Links
+
+- **Website**: https://matchkit.io
+- **Documentation**: https://matchkit.io/docs
+- **Dashboard**: https://matchkit.io/app
+- **Repository**: https://github.com/Maes9/matchkit
+- **Issues**: https://github.com/Maes9/matchkit/issues
+
+## License
+
+MIT

package/dist/commands/login.js

@@ -33,17 +33,7 @@ async function verifyKey(apiKey) {
 }
 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
+    // --key flag or non-interactive: skip all interactive prompts
     if (options?.key || !process.stdin.isTTY) {
         const apiKey = options?.key ?? process.env.MATCHKIT_API_KEY;
         if (!apiKey) {
@@ -64,6 +54,17 @@ export async function loginCommand(options) {
         p.outro("Key stored in " + pc.dim("~/.matchkit/credentials"));
         return;
     }
+    // Interactive flow below: requires TTY
+    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;
+        }
+    }
     // Browser-based auth flow
     const s = p.spinner();
     const callbackPromise = new Promise((resolve, reject) => {

package/dist/commands/pull.d.ts

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

package/dist/commands/pull.js

@@ -1,33 +1,164 @@
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { readConfig, configExists, writeConfig } from "../utils/config.js";
+import { readConfig, configExists, writeConfig, createDefaultConfig } from "../utils/config.js";
 import { getApiKey, authFetch, API_BASE_URL } from "../utils/auth.js";
-export async function pullCommand() {
+// Marker used to detect MatchKit-managed AI rules files
+const MATCHKIT_MARKER = "<!-- managed:matchkit -->";
+/**
+ * Build the content for AI rules files.
+ * This is the mandatory instruction set that tells AI tools to use the design system.
+ */
+function buildAiRulesContent(skillDir, theme) {
+    return `${MATCHKIT_MARKER}
+# MatchKit Design System — ${theme}-ui
+
+> Auto-generated by \`matchkit pull\`. Do not edit the marker line above.
+
+## MANDATORY — This project uses a complete design system
+
+A full design system is installed at \`${skillDir}/\`. You MUST use it for ALL UI work.
+
+### Before writing ANY UI code:
+
+1. **Read \`${skillDir}/SKILL.md\`** — contains design rules, component specs, and setup instructions
+2. **Read \`${skillDir}/registry.json\`** — lists all 27 available components with their dependencies
+3. **Copy \`${skillDir}/globals.css\`** to \`src/styles/globals.css\` if it doesn't exist yet
+4. **Create \`src/lib/utils.ts\`** with the \`cn()\` helper if it doesn't exist yet:
+   \`\`\`ts
+   import { clsx, type ClassValue } from "clsx";
+   import { twMerge } from "tailwind-merge";
+   export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }
+   \`\`\`
+5. **Copy component files** from \`${skillDir}/components/\` to \`src/components/ui/\` as needed
+
+### Rules — follow these at ALL times:
+
+- **ALWAYS** check \`${skillDir}/registry.json\` before creating any component — if it exists there, use it
+- **NEVER** create your own \`globals.css\`, Tailwind theme, or color tokens — use the provided \`globals.css\`
+- **NEVER** hardcode hex colors, pixel spacing, or font sizes — use CSS variables from \`globals.css\`
+- **NEVER** improvise a component if one already exists in the registry
+- **NEVER** modify files inside \`${skillDir}/\` — it is the upstream source of truth
+- **ALWAYS** use \`@/components/ui/{name}\` import paths for design system components
+- **ALWAYS** use \`@/lib/utils\` for the \`cn()\` helper
+
+### Available resources in \`${skillDir}/\`:
+
+| Path | Contents |
+|------|----------|
+| \`SKILL.md\` | Design rules, philosophy, component specs |
+| \`registry.json\` | Component registry with types, layers, dependencies |
+| \`components/*.tsx\` | 27 production-ready components |
+| \`layouts/*.tsx\` | 6 page layout references |
+| \`globals.css\` | Complete Tailwind v4 CSS with all tokens |
+| \`tokens/*.json\` | Design token values |
+| \`patterns/*.md\` | Responsive, dark mode, a11y, composition patterns |
+`;
+}
+/**
+ * Build Cursor .mdc format content (has YAML frontmatter with alwaysApply).
+ */
+function buildCursorMdcContent(skillDir, theme) {
+    return `---
+description: MatchKit ${theme}-ui design system — mandatory rules for all UI work
+alwaysApply: true
+---
+${buildAiRulesContent(skillDir, theme)}`;
+}
+/**
+ * Write AI rules files to the project root.
+ * Only writes if the file doesn't exist or is MatchKit-managed (has the marker).
+ * Returns the list of files that were written.
+ */
+function writeAiRulesFiles(cwd, skillDir, theme) {
+    const content = buildAiRulesContent(skillDir, theme);
+    const cursorMdcContent = buildCursorMdcContent(skillDir, theme);
+    const written = [];
+    const targets = [
+        { path: "CLAUDE.md", label: "CLAUDE.md", content },
+        { path: ".cursorrules", label: ".cursorrules", content },
+        { path: ".cursor/rules/matchkit.mdc", label: ".cursor/rules/matchkit.mdc", content: cursorMdcContent },
+        { path: ".github/copilot-instructions.md", label: ".github/copilot-instructions.md", content },
+        { path: ".windsurfrules", label: ".windsurfrules", content },
+    ];
+    for (const target of targets) {
+        const fullPath = join(cwd, target.path);
+        let shouldWrite = false;
+        if (!existsSync(fullPath)) {
+            shouldWrite = true;
+        }
+        else {
+            // File exists — only overwrite if it's MatchKit-managed
+            const existing = readFileSync(fullPath, "utf-8");
+            if (existing.includes(MATCHKIT_MARKER)) {
+                shouldWrite = true;
+            }
+        }
+        if (shouldWrite) {
+            const dir = dirname(fullPath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            writeFileSync(fullPath, target.content);
+            written.push(target.label);
+        }
+    }
+    return written;
+}
+export async function pullCommand(options) {
     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.");
+        p.log.error("Not logged in. Run " + pc.bold("matchkit login --key <key>") + " first.");
         process.exit(1);
     }
+    // Auto-create config.json if --config-id provided and no config exists
+    if (options?.configId) {
+        if (!configExists()) {
+            const cs = p.spinner();
+            cs.start("Fetching project details...");
+            try {
+                const res = await authFetch(`${API_BASE_URL}/api/v1/configs/${options.configId}`);
+                if (!res.ok) {
+                    cs.stop("Failed");
+                    p.log.error(`Project ${pc.dim(options.configId)} not found (${res.status})`);
+                    process.exit(1);
+                }
+                const data = (await res.json());
+                cs.stop("Project found");
+                const newConfig = createDefaultConfig(data.theme, data.accent ?? "#4F46E5", (data.overrides ?? {}));
+                writeConfig({ ...newConfig, configId: options.configId });
+                p.log.success(`Created .matchkit/config.json for ${pc.bold(data.theme + "-ui")}`);
+            }
+            catch {
+                cs.stop("Failed");
+                p.log.error("Could not fetch project details. Check your connection and API key.");
+                process.exit(1);
+            }
+        }
+        else {
+            // Config exists — update configId
+            const existing = readConfig();
+            writeConfig({ ...existing, configId: options.configId });
+        }
+    }
     // Check config
     if (!configExists()) {
-        p.log.error("No .matchkit/config.json found. Run " +
+        p.log.error("No .matchkit/config.json found. Use " +
+            pc.bold("--config-id <id>") +
+            " or 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.");
+        p.log.error("No configId in .matchkit/config.json. Use " +
+            pc.bold("matchkit pull --config-id <id>") +
+            " to link a project.");
         process.exit(1);
     }
     const s = p.spinner();
@@ -102,6 +233,11 @@ export async function pullCommand() {
         s.stop(`Extracted ${fileCount} files`);
         p.log.success(`${pc.bold(theme + "-ui")} v${version} → ${pc.dim(skillDir)}`);
         p.log.info(`Build: ${pc.dim(buildId)}`);
+        // Generate AI rules files so every AI tool uses the design system
+        const writtenRules = writeAiRulesFiles(process.cwd(), skillDir, theme);
+        if (writtenRules.length > 0) {
+            p.log.success(`AI rules → ${writtenRules.map((f) => pc.dim(f)).join(", ")}`);
+        }
         p.outro("Design system is up to date.");
     }
     catch (err) {

package/dist/index.js

@@ -11,7 +11,7 @@ const program = new Command();
 program
     .name("matchkit")
     .description("MatchKit — style-agnostic design system CLI")
-    .version("0.1.0");
+    .version("0.1.2");
 program
     .command("init")
     .description("Initialize a MatchKit design system in your project")
@@ -37,6 +37,7 @@ program
 program
     .command("pull")
     .description("Pull your latest resolved design system from the server")
+    .option("--config-id <id>", "Server config ID (skips matchkit init)")
     .action(pullCommand);
 program
     .command("status")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matchkit.io/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI for MatchKit design system skills. Init projects, add components, manage your design system.",
   "type": "module",
   "main": "dist/index.js",