@matchkit.io/cli 0.1.0 → 0.1.1

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

@@ -2,32 +2,61 @@ 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 { readConfig, configExists, writeConfig, createDefaultConfig } from "../utils/config.js";
 import { getApiKey, authFetch, API_BASE_URL } from "../utils/auth.js";
-export async function pullCommand() {
+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();

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.1");
 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.1",
   "description": "CLI for MatchKit design system skills. Init projects, add components, manage your design system.",
   "type": "module",
   "main": "dist/index.js",