claude-playbook 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# claude-playbook CLI
+
+Discover and install Claude Code skills, agents, and MCPs from your terminal.
+
+## Installation
+
+```bash
+npx claude-playbook <command>
+
+# Or install globally
+npm install -g claude-playbook
+```
+
+## Commands
+
+### Search
+
+Search for skills, agents, or MCPs:
+
+```bash
+# Search everything
+claude-playbook search git
+
+# Search specific type
+claude-playbook search database --type mcp
+```
+
+### List
+
+List all available items:
+
+```bash
+# List everything
+claude-playbook list
+
+# List specific type
+claude-playbook list skills
+claude-playbook list agents
+claude-playbook list mcps
+
+# Filter by category
+claude-playbook list --category "code-review"
+```
+
+### Install
+
+Install an MCP to your Claude Code configuration:
+
+```bash
+# Install an MCP
+claude-playbook install github
+claude-playbook install stripe
+
+# Preview changes without installing
+claude-playbook install firebase --dry-run
+
+# Check skill usage (skills are built-in)
+claude-playbook install commit --type skill
+```
+
+### Sync
+
+Sync your Playbook between web and local Claude Code:
+
+```bash
+# Full bidirectional sync (pull items, push installation status)
+claude-playbook sync
+
+# Pull only (don't update web badges)
+claude-playbook sync --no-push
+
+# Preview changes without making them
+claude-playbook sync --dry-run
+
+# Skip all confirmations
+claude-playbook sync --force
+```
+
+**Authentication Options:**
+
+1. **Session Token** (short-lived): Get from `/auth/cli` page on web app
+2. **Personal Access Token** (recommended): Create in Settings > Access Tokens
+
+```bash
+# Using PAT (recommended for automation)
+claude-playbook sync --token pat_abc12345_abcdef1234567890...
+
+# Using environment variable
+export PLAYBOOK_SUPABASE_URL=https://your-project.supabase.co
+claude-playbook sync
+```
+
+### Config
+
+View or manage your configuration:
+
+```bash
+# Show current config
+claude-playbook config --show
+
+# Show config file path
+claude-playbook config --path
+
+# Reset configuration
+claude-playbook config --reset
+```
+
+## Development
+
+```bash
+cd packages/cli
+npm install
+npm run build
+node dist/index.js search git
+```
+
+## License
+
+MIT

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const configCommand: Command;

package/dist/commands/config.js

@@ -0,0 +1,64 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+const CLAUDE_CONFIG_DIR = path.join(os.homedir(), ".claude");
+const SETTINGS_FILE = path.join(CLAUDE_CONFIG_DIR, "settings.json");
+function readSettings() {
+    if (!fs.existsSync(SETTINGS_FILE)) {
+        return {};
+    }
+    const content = fs.readFileSync(SETTINGS_FILE, "utf-8");
+    return JSON.parse(content);
+}
+export const configCommand = new Command("config")
+    .description("View or modify Claude Code configuration")
+    .option("--show", "Show current configuration")
+    .option("--path", "Show config file path")
+    .option("--reset", "Reset configuration to defaults")
+    .action((options) => {
+    if (options.path) {
+        console.log(SETTINGS_FILE);
+        return;
+    }
+    if (options.reset) {
+        if (fs.existsSync(SETTINGS_FILE)) {
+            const backupPath = SETTINGS_FILE + ".backup";
+            fs.copyFileSync(SETTINGS_FILE, backupPath);
+            fs.writeFileSync(SETTINGS_FILE, JSON.stringify({}, null, 2));
+            console.log(chalk.green("Configuration reset"));
+            console.log(chalk.gray(`Backup saved to: ${backupPath}`));
+        }
+        else {
+            console.log(chalk.yellow("No configuration file exists yet"));
+        }
+        return;
+    }
+    // Default: show config
+    const settings = readSettings();
+    if (Object.keys(settings).length === 0) {
+        console.log(chalk.yellow("No configuration found"));
+        console.log(chalk.gray(`\nConfig path: ${SETTINGS_FILE}`));
+        console.log(chalk.gray("Use 'claude-playbook install <mcp>' to add MCP servers"));
+        return;
+    }
+    console.log(chalk.bold("\nClaude Code Configuration:\n"));
+    if (settings.mcpServers) {
+        console.log(chalk.cyan("MCP Servers:"));
+        for (const [name, config] of Object.entries(settings.mcpServers)) {
+            console.log(`  ${chalk.green("●")} ${name}`);
+            if (Object.keys(config).length > 0) {
+                console.log(chalk.gray(`    ${JSON.stringify(config)}`));
+            }
+        }
+        console.log();
+    }
+    for (const [key, value] of Object.entries(settings)) {
+        if (key !== "mcpServers") {
+            console.log(chalk.cyan(`${key}:`));
+            console.log(chalk.gray(`  ${JSON.stringify(value)}`));
+        }
+    }
+    console.log(chalk.gray(`\nConfig path: ${SETTINGS_FILE}`));
+});

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const installCommand: Command;

package/dist/commands/install.js

@@ -0,0 +1,82 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { fetchMCPs, fetchSkills } from "../registry.js";
+const CLAUDE_CONFIG_DIR = path.join(os.homedir(), ".claude");
+const SETTINGS_FILE = path.join(CLAUDE_CONFIG_DIR, "settings.json");
+function readSettings() {
+    if (!fs.existsSync(SETTINGS_FILE)) {
+        return {};
+    }
+    const content = fs.readFileSync(SETTINGS_FILE, "utf-8");
+    return JSON.parse(content);
+}
+function writeSettings(settings) {
+    if (!fs.existsSync(CLAUDE_CONFIG_DIR)) {
+        fs.mkdirSync(CLAUDE_CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2));
+}
+export const installCommand = new Command("install")
+    .description("Install a skill or MCP to your Claude Code configuration")
+    .argument("<name>", "Name of the skill or MCP to install")
+    .option("-t, --type <type>", "Type to install (skill, mcp)", "mcp")
+    .option("--dry-run", "Show what would be installed without making changes")
+    .action(async (name, options) => {
+    const spinner = ora(`Looking for ${name}...`).start();
+    try {
+        if (options.type === "mcp") {
+            const mcps = await fetchMCPs();
+            const mcp = mcps.find((m) => m.id.toLowerCase() === name.toLowerCase() || m.name.toLowerCase() === name.toLowerCase());
+            if (!mcp) {
+                spinner.fail(`MCP "${name}" not found`);
+                console.log(chalk.gray("\nUse 'claude-playbook search <query>' to find available MCPs"));
+                process.exit(1);
+            }
+            spinner.text = `Installing ${mcp.name}...`;
+            const config = { [mcp.id]: {} };
+            if (options.dryRun) {
+                spinner.info("Dry run - would add to settings.json:");
+                console.log(chalk.cyan(JSON.stringify({ mcpServers: config }, null, 2)));
+                return;
+            }
+            const settings = readSettings();
+            settings.mcpServers = {
+                ...settings.mcpServers,
+                ...config,
+            };
+            writeSettings(settings);
+            spinner.succeed(`Installed ${chalk.bold(mcp.name)}`);
+            console.log(chalk.gray(`\n  Added to ${SETTINGS_FILE}`));
+            console.log(chalk.gray(`  Tools: ${mcp.tools.join(", ")}`));
+            if (mcp.documentationUrl) {
+                console.log(chalk.gray(`  Docs: ${mcp.documentationUrl}`));
+            }
+        }
+        else if (options.type === "skill") {
+            const skills = await fetchSkills();
+            const skill = skills.find((s) => s.id.toLowerCase() === name.toLowerCase() || s.name.toLowerCase() === name.toLowerCase());
+            if (!skill) {
+                spinner.fail(`Skill "${name}" not found`);
+                process.exit(1);
+            }
+            spinner.succeed(`Found skill: ${chalk.bold(skill.name)}`);
+            console.log(chalk.gray(`\n  Invocation: ${skill.invocation}`));
+            console.log(chalk.gray(`  ${skill.description}`));
+            console.log(chalk.yellow("\n  Note: Skills are built-in and don't require installation."));
+            console.log(chalk.yellow(`  Just use: ${skill.invocation}`));
+        }
+        else {
+            spinner.fail(`Unknown type: ${options.type}`);
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        spinner.fail("Installation failed");
+        console.error(chalk.red(error.message));
+        process.exit(1);
+    }
+});

package/dist/commands/list.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const listCommand: Command;

package/dist/commands/list.js

@@ -0,0 +1,72 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { fetchSkills, fetchAgents, fetchMCPs } from "../registry.js";
+export const listCommand = new Command("list")
+    .description("List all available skills, agents, or MCPs")
+    .argument("[type]", "Type to list (skill, agent, mcp, or all)", "all")
+    .option("-c, --category <category>", "Filter by category")
+    .action(async (type, options) => {
+    const spinner = ora("Fetching from registry...").start();
+    try {
+        const showType = (t) => type === "all" || type === t || type === t + "s";
+        if (showType("skill")) {
+            try {
+                const skills = await fetchSkills();
+                spinner.stop();
+                const filtered = options.category
+                    ? skills.filter((s) => s.category?.toLowerCase() === options.category?.toLowerCase())
+                    : skills;
+                console.log(chalk.bold.magenta(`\nSkills (${filtered.length}):\n`));
+                for (const skill of filtered) {
+                    console.log(`  ${chalk.magenta("/")}${skill.name}`);
+                    console.log(chalk.gray(`    ${skill.description}`));
+                }
+            }
+            catch {
+                console.log(chalk.yellow("\nNo skills found in registry"));
+            }
+        }
+        if (showType("agent")) {
+            try {
+                const agents = await fetchAgents();
+                spinner.stop();
+                const filtered = options.category
+                    ? agents.filter((a) => a.category?.toLowerCase() === options.category?.toLowerCase())
+                    : agents;
+                console.log(chalk.bold.blue(`\nAgents (${filtered.length}):\n`));
+                for (const agent of filtered) {
+                    console.log(`  ${chalk.blue("●")} ${agent.name}`);
+                    console.log(chalk.gray(`    ${agent.description}`));
+                }
+            }
+            catch {
+                console.log(chalk.yellow("\nNo agents found in registry"));
+            }
+        }
+        if (showType("mcp")) {
+            try {
+                const mcps = await fetchMCPs();
+                spinner.stop();
+                const filtered = options.category
+                    ? mcps.filter((m) => m.category?.toLowerCase() === options.category?.toLowerCase())
+                    : mcps;
+                console.log(chalk.bold.green(`\nMCP Servers (${filtered.length}):\n`));
+                for (const mcp of filtered) {
+                    console.log(`  ${chalk.green("⚡")} ${mcp.name} (${mcp.toolCount} tools)`);
+                    console.log(chalk.gray(`    ${mcp.description}`));
+                }
+            }
+            catch {
+                console.log(chalk.yellow("\nNo MCPs found in registry"));
+            }
+        }
+        spinner.stop();
+        console.log();
+    }
+    catch (error) {
+        spinner.fail("Failed to fetch registry");
+        console.error(chalk.red(error.message));
+        process.exit(1);
+    }
+});

package/dist/commands/search.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const searchCommand: Command;

package/dist/commands/search.js

@@ -0,0 +1,34 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { searchRegistry } from "../registry.js";
+export const searchCommand = new Command("search")
+    .description("Search for skills, agents, or MCPs")
+    .argument("<query>", "Search query")
+    .option("-t, --type <type>", "Filter by type (skill, agent, mcp)")
+    .action(async (query, options) => {
+    const spinner = ora("Searching registry...").start();
+    try {
+        const results = await searchRegistry(query, options.type);
+        spinner.stop();
+        if (results.length === 0) {
+            console.log(chalk.yellow(`No results found for "${query}"`));
+            return;
+        }
+        console.log(chalk.bold(`\nFound ${results.length} result(s):\n`));
+        for (const { type, item } of results) {
+            const typeColor = type === "skill" ? chalk.magenta : type === "agent" ? chalk.blue : chalk.green;
+            console.log(typeColor(`[${type.toUpperCase()}]`) + " " + chalk.bold(item.name));
+            console.log(chalk.gray(`  ${item.description}`));
+            if (item.category) {
+                console.log(chalk.gray(`  Category: ${item.category}`));
+            }
+            console.log();
+        }
+    }
+    catch (error) {
+        spinner.fail("Failed to search registry");
+        console.error(chalk.red(error.message));
+        process.exit(1);
+    }
+});

package/dist/commands/sync.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const syncCommand: Command;

package/dist/commands/sync.js

@@ -0,0 +1,568 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import * as readline from "readline";
+import { spawnSync } from "child_process";
+import lockfile from "proper-lockfile";
+import { getSafeInstalledItems } from "../config-reader.js";
+const CLAUDE_CONFIG_DIR = path.join(os.homedir(), ".claude");
+const SETTINGS_FILE = path.join(CLAUDE_CONFIG_DIR, "settings.json");
+const SYNC_META_FILE = path.join(CLAUDE_CONFIG_DIR, ".playbook-sync.json");
+const BACKUP_DIR = path.join(CLAUDE_CONFIG_DIR, ".playbook-backups");
+const LOCK_OPTIONS = {
+    stale: 30000, // Consider lock stale after 30 seconds
+    retries: {
+        retries: 3,
+        minTimeout: 1000,
+        maxTimeout: 3000,
+    },
+};
+// Acquire exclusive lock for sync operations
+async function acquireLock() {
+    // Ensure the lock target exists
+    if (!fs.existsSync(CLAUDE_CONFIG_DIR)) {
+        fs.mkdirSync(CLAUDE_CONFIG_DIR, { recursive: true });
+    }
+    // Create a marker file for the lock if it doesn't exist
+    const lockTarget = path.join(CLAUDE_CONFIG_DIR, ".playbook-lock-target");
+    if (!fs.existsSync(lockTarget)) {
+        fs.writeFileSync(lockTarget, "");
+    }
+    try {
+        const release = await lockfile.lock(lockTarget, LOCK_OPTIONS);
+        return release;
+    }
+    catch (err) {
+        if (err.code === "ELOCKED") {
+            throw new Error("Another sync operation is in progress. Please wait and try again.");
+        }
+        throw err;
+    }
+}
+// Token validation - supports both JWT and PAT
+function isValidToken(token) {
+    // Check for PAT format: pat_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY (77 chars)
+    if (token.startsWith("pat_") && token.length === 77) {
+        // Validate format: pat_ + 8 hex chars + _ + 64 hex chars
+        const patRegex = /^pat_[a-f0-9]{8}_[a-f0-9]{64}$/i;
+        if (patRegex.test(token)) {
+            return { valid: true, type: "pat" };
+        }
+    }
+    // Check for JWT format
+    const parts = token.split(".");
+    if (parts.length === 3) {
+        try {
+            // Check header and payload are valid base64
+            for (let i = 0; i < 2; i++) {
+                const decoded = Buffer.from(parts[i], "base64url").toString();
+                JSON.parse(decoded);
+            }
+            return { valid: true, type: "jwt" };
+        }
+        catch {
+            // Fall through
+        }
+    }
+    return { valid: false, type: null };
+}
+// Decode JWT to check expiration
+function decodeJWT(token) {
+    try {
+        const parts = token.split(".");
+        const payload = Buffer.from(parts[1], "base64url").toString();
+        return JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+}
+// Check if Claude Code is running (platform-specific, using safe spawnSync)
+function isClaudeCodeRunning() {
+    try {
+        const platform = os.platform();
+        if (platform === "darwin" || platform === "linux") {
+            // Use pgrep with fixed arguments (no shell injection possible)
+            const result = spawnSync("pgrep", ["-f", "claude"], {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            return result.status === 0 && result.stdout.trim().length > 0;
+        }
+        else if (platform === "win32") {
+            // Use tasklist with fixed arguments
+            const result = spawnSync("tasklist", ["/FI", "IMAGENAME eq claude*"], {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            return result.stdout?.toLowerCase().includes("claude") ?? false;
+        }
+        return false;
+    }
+    catch {
+        // If check fails, assume not running
+        return false;
+    }
+}
+// Create backup of settings file
+function backupSettings() {
+    if (!fs.existsSync(SETTINGS_FILE)) {
+        return null;
+    }
+    try {
+        if (!fs.existsSync(BACKUP_DIR)) {
+            fs.mkdirSync(BACKUP_DIR, { recursive: true });
+        }
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const backupFile = path.join(BACKUP_DIR, `settings.${timestamp}.json`);
+        fs.copyFileSync(SETTINGS_FILE, backupFile);
+        // Clean up old backups (keep last 5)
+        const backups = fs.readdirSync(BACKUP_DIR)
+            .filter((f) => f.startsWith("settings.") && f.endsWith(".json"))
+            .sort()
+            .reverse();
+        for (const old of backups.slice(5)) {
+            fs.unlinkSync(path.join(BACKUP_DIR, old));
+        }
+        return backupFile;
+    }
+    catch {
+        return null;
+    }
+}
+// Read settings with error handling
+function readSettings() {
+    if (!fs.existsSync(SETTINGS_FILE)) {
+        return {};
+    }
+    try {
+        const content = fs.readFileSync(SETTINGS_FILE, "utf-8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse settings.json: ${error.message}`);
+    }
+}
+// Write settings atomically with safety checks
+function writeSettings(settings) {
+    if (!fs.existsSync(CLAUDE_CONFIG_DIR)) {
+        fs.mkdirSync(CLAUDE_CONFIG_DIR, { recursive: true });
+    }
+    // Security check: refuse to write if settings file is a symlink
+    if (fs.existsSync(SETTINGS_FILE)) {
+        const stats = fs.lstatSync(SETTINGS_FILE);
+        if (stats.isSymbolicLink()) {
+            throw new Error("Security: settings.json is a symlink, refusing to write");
+        }
+    }
+    // Write atomically via temp file
+    const tempFile = `${SETTINGS_FILE}.tmp`;
+    fs.writeFileSync(tempFile, JSON.stringify(settings, null, 2));
+    fs.renameSync(tempFile, SETTINGS_FILE);
+}
+// Validate item ID format to prevent path traversal
+function isValidItemId(id) {
+    return /^[a-zA-Z0-9_-]+$/.test(id) && id.length <= 100;
+}
+// Sanitize string for safe storage
+function sanitizeString(str, maxLength = 500) {
+    return str
+        .slice(0, maxLength)
+        .replace(/[\x00-\x1F\x7F]/g, "") // Remove control characters
+        .trim();
+}
+// Prompt for user confirmation
+async function confirm(message) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question(`${message} (y/N) `, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+        });
+    });
+}
+// Prompt for token input with hidden characters
+async function promptForToken() {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        process.stdout.write(chalk.cyan("Paste your Playbook token: "));
+        let token = "";
+        process.stdin.setRawMode?.(true);
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+        const onData = (char) => {
+            if (char === "\n" || char === "\r") {
+                process.stdin.setRawMode?.(false);
+                process.stdin.removeListener("data", onData);
+                console.log(); // New line
+                rl.close();
+                resolve(token);
+            }
+            else if (char === "\x7F" || char === "\b") {
+                // Backspace
+                if (token.length > 0) {
+                    token = token.slice(0, -1);
+                    process.stdout.write("\b \b");
+                }
+            }
+            else if (char === "\x03") {
+                // Ctrl+C
+                process.exit(0);
+            }
+            else {
+                token += char;
+                process.stdout.write("*");
+            }
+        };
+        process.stdin.on("data", onData);
+    });
+}
+// Fetch playbook from cloud
+async function fetchPlaybook(token, supabaseUrl) {
+    const functionsUrl = supabaseUrl.replace(".supabase.co", ".functions.supabase.co");
+    const response = await fetch(`${functionsUrl}/playbook`, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Token expired or invalid. Please generate a new token from the Playbook web app.");
+        }
+        const error = await response.json().catch(() => ({}));
+        throw new Error(error.error || `API error: ${response.statusText}`);
+    }
+    return response.json();
+}
+// Save sync metadata
+function saveSyncMeta(userId, itemCount) {
+    const meta = {
+        lastSyncedAt: new Date().toISOString(),
+        userId,
+        itemCount,
+    };
+    fs.writeFileSync(SYNC_META_FILE, JSON.stringify(meta, null, 2));
+}
+// Push installation status to cloud
+async function pushInstalledStatus(token, supabaseUrl, mcpServerIds) {
+    const items = getSafeInstalledItems(mcpServerIds);
+    if (items.length === 0) {
+        return { pushed: 0 };
+    }
+    const functionsUrl = supabaseUrl.replace(".supabase.co", ".functions.supabase.co");
+    try {
+        const response = await fetch(`${functionsUrl}/playbook/installed`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                items: items.map((item) => ({
+                    type: item.type,
+                    id: item.id,
+                    name: item.name,
+                })),
+                syncedAt: new Date().toISOString(),
+            }),
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            return {
+                pushed: 0,
+                error: errorData.error || `HTTP ${response.status}`,
+            };
+        }
+        const data = await response.json();
+        return { pushed: data.synced || items.length };
+    }
+    catch (err) {
+        return {
+            pushed: 0,
+            error: err instanceof Error ? err.message : "Unknown error",
+        };
+    }
+}
+// Main sync logic
+async function syncPlaybook(token, supabaseUrl, options) {
+    const spinner = ora("Fetching your Playbook...").start();
+    try {
+        // Fetch playbook from cloud
+        const playbook = await fetchPlaybook(token, supabaseUrl);
+        spinner.text = `Found ${playbook.items.length} items for ${playbook.user.email}`;
+        if (playbook.items.length === 0) {
+            spinner.info("Your Playbook is empty. Add items on the web app first.");
+            return;
+        }
+        // Group items by type
+        const mcps = playbook.items.filter((i) => i.item_type === "mcp");
+        const skills = playbook.items.filter((i) => i.item_type === "skill");
+        const others = playbook.items.filter((i) => !["mcp", "skill"].includes(i.item_type));
+        spinner.succeed(`Fetched ${playbook.items.length} items`);
+        console.log(chalk.gray(`\n  MCPs: ${mcps.length}`));
+        console.log(chalk.gray(`  Skills: ${skills.length}`));
+        console.log(chalk.gray(`  Other: ${others.length}\n`));
+        if (options.dryRun) {
+            console.log(chalk.yellow("Dry run mode - no changes will be made\n"));
+        }
+        // Safety check: warn if Claude Code is running
+        if (!options.dryRun && isClaudeCodeRunning()) {
+            console.log(chalk.yellow("\nWarning: Claude Code appears to be running."));
+            console.log(chalk.gray("  Modifying settings while Claude Code is running may require a restart."));
+            if (!options.force) {
+                const proceed = await confirm(chalk.yellow("  Continue anyway?"));
+                if (!proceed) {
+                    console.log(chalk.gray("\nSync cancelled. Close Claude Code and try again."));
+                    return;
+                }
+            }
+            console.log();
+        }
+        // Process MCPs
+        if (mcps.length > 0) {
+            const mcpSpinner = ora("Installing MCPs to settings.json...").start();
+            // Read current settings
+            let settings;
+            try {
+                settings = readSettings();
+            }
+            catch (error) {
+                mcpSpinner.fail("Failed to read settings");
+                throw error;
+            }
+            settings.mcpServers = settings.mcpServers || {};
+            // Count new MCPs
+            let toInstall = 0;
+            let skipped = 0;
+            for (const mcp of mcps) {
+                if (!isValidItemId(mcp.item_id)) {
+                    skipped++;
+                    continue;
+                }
+                if (settings.mcpServers[mcp.item_id]) {
+                    skipped++;
+                    continue;
+                }
+                toInstall++;
+            }
+            if (toInstall === 0) {
+                mcpSpinner.info(`All ${mcps.length} MCPs already installed`);
+            }
+            else {
+                mcpSpinner.stop();
+                // Show what will be installed
+                console.log(chalk.cyan(`\n  MCPs to install (${toInstall}):`));
+                for (const mcp of mcps) {
+                    if (!isValidItemId(mcp.item_id)) {
+                        console.log(chalk.yellow(`  ! ${mcp.item_id} (invalid ID, skipping)`));
+                        continue;
+                    }
+                    if (settings.mcpServers[mcp.item_id]) {
+                        continue; // Already installed
+                    }
+                    console.log(chalk.gray(`  + ${sanitizeString(mcp.item_name, 50)}`));
+                }
+                console.log();
+                // Confirm installation
+                if (!options.dryRun && !options.force) {
+                    const proceed = await confirm(chalk.cyan(`  Install ${toInstall} MCP(s) to settings.json?`));
+                    if (!proceed) {
+                        console.log(chalk.gray("\nInstallation cancelled."));
+                        return;
+                    }
+                }
+                if (!options.dryRun) {
+                    // Create backup before modifying
+                    if (!options.noBackup) {
+                        const backupPath = backupSettings();
+                        if (backupPath) {
+                            console.log(chalk.gray(`\n  Backup created: ${backupPath}`));
+                        }
+                    }
+                    // Install MCPs
+                    let installed = 0;
+                    for (const mcp of mcps) {
+                        if (!isValidItemId(mcp.item_id))
+                            continue;
+                        if (settings.mcpServers[mcp.item_id])
+                            continue;
+                        settings.mcpServers[mcp.item_id] = {
+                        // Note: Command and args need to be configured by user
+                        // We create a placeholder entry
+                        };
+                        installed++;
+                    }
+                    writeSettings(settings);
+                    console.log(chalk.green(`\n  Installed ${installed} MCP(s)`));
+                }
+                else {
+                    console.log(chalk.yellow(`  Would install ${toInstall} MCP(s) (dry run)`));
+                }
+            }
+        }
+        // Process Skills
+        if (skills.length > 0) {
+            console.log(chalk.cyan(`\n  Skills in your Playbook (${skills.length}):`));
+            console.log(chalk.gray("  (Skills are built-in and don't need installation)"));
+            for (const skill of skills) {
+                console.log(chalk.gray(`  - ${sanitizeString(skill.item_name, 50)}`));
+            }
+        }
+        // Process other items
+        if (others.length > 0) {
+            console.log(chalk.cyan(`\n  Other items (${others.length}):`));
+            console.log(chalk.gray("  (Reference items - no local installation needed)"));
+            for (const item of others) {
+                console.log(chalk.gray(`  - [${item.item_type}] ${sanitizeString(item.item_name, 50)}`));
+            }
+        }
+        // Save sync metadata
+        if (!options.dryRun) {
+            saveSyncMeta(playbook.user.id, playbook.items.length);
+        }
+        console.log(chalk.green("\nSync complete!"));
+        if (mcps.length > 0) {
+            console.log(chalk.yellow("\nNote: Newly added MCPs may need configuration."));
+            console.log(chalk.gray(`  Edit ${SETTINGS_FILE} to add command and args.`));
+            console.log(chalk.gray("  Documentation: https://claude.ai/claude-code/mcps"));
+        }
+    }
+    catch (error) {
+        spinner.fail("Sync failed");
+        throw error;
+    }
+}
+export const syncCommand = new Command("sync")
+    .description("Sync your Playbook bidirectionally: pull items from web, push installation status back")
+    .option("--token <token>", "Playbook auth token (or paste when prompted)")
+    .option("--supabase-url <url>", "Supabase project URL", process.env.PLAYBOOK_SUPABASE_URL)
+    .option("--dry-run", "Show what would be synced without making changes")
+    .option("-f, --force", "Skip confirmation prompts")
+    .option("--no-backup", "Skip creating backup of settings.json")
+    .option("--no-push", "Skip pushing installation status to cloud")
+    .addHelpText("after", `
+Examples:
+  $ npx claude-playbook sync                    # Full bidirectional sync
+  $ npx claude-playbook sync --no-push          # Pull only (don't update web badges)
+  $ npx claude-playbook sync --dry-run          # Preview what would happen
+  $ npx claude-playbook sync --force            # Skip all confirmations
+
+Authentication:
+  Supports two token types:
+  - JWT: Short-lived session token from /auth/cli (expires in ~1 hour)
+  - PAT: Personal Access Token from Settings > Access Tokens (long-lived)
+
+Environment:
+  PLAYBOOK_SUPABASE_URL    Supabase project URL (avoids prompting)
+`)
+    .action(async (options) => {
+    // Check for Supabase URL
+    const supabaseUrl = options.supabaseUrl || process.env.PLAYBOOK_SUPABASE_URL;
+    if (!supabaseUrl) {
+        console.error(chalk.red("Error: Supabase URL not configured"));
+        console.log(chalk.gray("\nSet PLAYBOOK_SUPABASE_URL environment variable or use --supabase-url"));
+        console.log(chalk.gray("Example: export PLAYBOOK_SUPABASE_URL=https://your-project.supabase.co"));
+        process.exit(1);
+    }
+    console.log(chalk.bold("\nPlaybook Sync"));
+    console.log(chalk.gray("Syncing your Playbook items to local Claude Code config\n"));
+    // Get token
+    let token = options.token;
+    if (!token) {
+        console.log(chalk.gray("Authentication options:"));
+        console.log(chalk.gray("  1. Session token: https://claude-code-playbook.vercel.app/auth/cli"));
+        console.log(chalk.gray("  2. Personal Access Token: Settings > Access Tokens (recommended)\n"));
+        token = await promptForToken();
+    }
+    // Validate token format (JWT or PAT)
+    const tokenValidation = isValidToken(token);
+    if (!tokenValidation.valid) {
+        console.error(chalk.red("\nError: Invalid token format"));
+        console.log(chalk.gray("Supported formats:"));
+        console.log(chalk.gray("  - JWT: Session token from web app (short-lived)"));
+        console.log(chalk.gray("  - PAT: Personal Access Token from Settings > Access Tokens (long-lived)"));
+        console.log(chalk.gray("\nMake sure you copied the complete token."));
+        process.exit(1);
+    }
+    // Token type-specific handling
+    if (tokenValidation.type === "pat") {
+        console.log(chalk.gray("Using Personal Access Token"));
+        // PATs don't have client-side expiration check - server validates
+    }
+    else {
+        // JWT: Check token expiration
+        const decoded = decodeJWT(token);
+        if (decoded?.exp) {
+            const expiresAt = new Date(decoded.exp * 1000);
+            const now = new Date();
+            if (expiresAt < now) {
+                console.error(chalk.red("\nError: Token has expired"));
+                console.log(chalk.gray(`Expired at: ${expiresAt.toLocaleString()}`));
+                console.log(chalk.gray("Please generate a new token from the web app."));
+                console.log(chalk.gray("\nTip: Create a Personal Access Token for long-lived authentication:"));
+                console.log(chalk.gray("     Settings > Access Tokens > New Token"));
+                process.exit(1);
+            }
+            const minutesRemaining = Math.round((expiresAt.getTime() - now.getTime()) / 60000);
+            if (minutesRemaining < 5) {
+                console.log(chalk.yellow(`\nWarning: Token expires in ${minutesRemaining} minutes`));
+                console.log(chalk.gray("Tip: Use a Personal Access Token for long-lived authentication"));
+            }
+        }
+    }
+    let releaseLock = null;
+    try {
+        // Acquire exclusive lock
+        const lockSpinner = ora("Acquiring sync lock...").start();
+        try {
+            releaseLock = await acquireLock();
+            lockSpinner.succeed("Lock acquired");
+        }
+        catch (lockErr) {
+            lockSpinner.fail("Could not acquire lock");
+            throw lockErr;
+        }
+        await syncPlaybook(token, supabaseUrl, {
+            dryRun: options.dryRun || false,
+            force: options.force || false,
+            noBackup: options.backup === false,
+        });
+        // Push installation status to cloud (unless --no-push)
+        if (!options.dryRun && options.push !== false) {
+            const pushSpinner = ora("Syncing installation status to cloud...").start();
+            const settings = readSettings();
+            const mcpIds = Object.keys(settings.mcpServers || {});
+            const pushResult = await pushInstalledStatus(token, supabaseUrl, mcpIds);
+            if (pushResult.error) {
+                pushSpinner.warn(`Could not sync status to cloud: ${pushResult.error} (non-fatal)`);
+            }
+            else if (pushResult.pushed > 0) {
+                pushSpinner.succeed(`Synced ${pushResult.pushed} item(s) as "installed" on web`);
+            }
+            else {
+                pushSpinner.info("No items to sync to cloud");
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(`\n${error.message}`));
+        process.exit(1);
+    }
+    finally {
+        // Always release lock
+        if (releaseLock) {
+            await releaseLock();
+        }
+    }
+});

package/dist/config-reader.d.ts

@@ -0,0 +1,14 @@
+export interface SafeInstalledItem {
+    type: "mcp" | "skill";
+    id: string;
+    name: string;
+    installed: true;
+}
+/**
+ * Get installed items in a format safe for web sync.
+ * IMPORTANT: This strips all sensitive data:
+ * - No env variables (API keys, tokens)
+ * - No command paths (local system info)
+ * - No args (may contain tokens)
+ */
+export declare function getSafeInstalledItems(mcpServerIds: string[]): SafeInstalledItem[];

package/dist/config-reader.js

@@ -0,0 +1,55 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+const CLAUDE_DIR = path.join(os.homedir(), ".claude");
+/**
+ * Get installed items in a format safe for web sync.
+ * IMPORTANT: This strips all sensitive data:
+ * - No env variables (API keys, tokens)
+ * - No command paths (local system info)
+ * - No args (may contain tokens)
+ */
+export function getSafeInstalledItems(mcpServerIds) {
+    const items = [];
+    // MCPs - only use IDs passed in (already validated)
+    for (const id of mcpServerIds) {
+        // Validate ID format for safety
+        if (/^[a-zA-Z0-9_-]+$/.test(id) && id.length <= 100) {
+            items.push({
+                type: "mcp",
+                id,
+                name: id,
+                installed: true,
+            });
+        }
+    }
+    // Skills - read from ~/.claude/skills/
+    const skillsDir = path.join(CLAUDE_DIR, "skills");
+    if (fs.existsSync(skillsDir)) {
+        try {
+            const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const skillFile = path.join(skillsDir, entry.name, "skill.md");
+                    const indexFile = path.join(skillsDir, entry.name, "index.md");
+                    if (fs.existsSync(skillFile) || fs.existsSync(indexFile)) {
+                        // Validate name format
+                        if (/^[a-zA-Z0-9_-]+$/.test(entry.name) &&
+                            entry.name.length <= 100) {
+                            items.push({
+                                type: "skill",
+                                id: entry.name,
+                                name: entry.name,
+                                installed: true,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore read errors
+        }
+    }
+    return items;
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { searchCommand } from "./commands/search.js";
+import { installCommand } from "./commands/install.js";
+import { configCommand } from "./commands/config.js";
+import { listCommand } from "./commands/list.js";
+import { syncCommand } from "./commands/sync.js";
+const program = new Command();
+program
+    .name("claude-playbook")
+    .description("Discover and install Claude Code skills, agents, and MCPs")
+    .version("0.1.0");
+program.addCommand(searchCommand);
+program.addCommand(installCommand);
+program.addCommand(configCommand);
+program.addCommand(listCommand);
+program.addCommand(syncCommand);
+program.parse();

package/dist/registry.d.ts

@@ -0,0 +1,29 @@
+export interface RegistryItem {
+    id: string;
+    name: string;
+    description: string;
+    category?: string;
+}
+export interface Skill extends RegistryItem {
+    invocation: string;
+    source: string;
+}
+export interface Agent extends RegistryItem {
+    invocation: string;
+    capabilities?: string[];
+}
+export interface MCP extends RegistryItem {
+    provider?: string;
+    toolCount: number;
+    tools: string[];
+    installUrl?: string;
+    documentationUrl?: string;
+}
+export type ItemType = "skill" | "agent" | "mcp";
+export declare function fetchSkills(): Promise<Skill[]>;
+export declare function fetchAgents(): Promise<Agent[]>;
+export declare function fetchMCPs(): Promise<MCP[]>;
+export declare function searchRegistry(query: string, type?: ItemType): Promise<{
+    type: ItemType;
+    item: RegistryItem;
+}[]>;

package/dist/registry.js

@@ -0,0 +1,68 @@
+// Registry fetching utilities
+const REGISTRY_BASE = "https://raw.githubusercontent.com/AnobleSCM/claude-code-registry/main";
+async function fetchJson(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+    }
+    return response.json();
+}
+export async function fetchSkills() {
+    return fetchJson(`${REGISTRY_BASE}/skills/index.json`);
+}
+export async function fetchAgents() {
+    return fetchJson(`${REGISTRY_BASE}/agents/index.json`);
+}
+export async function fetchMCPs() {
+    return fetchJson(`${REGISTRY_BASE}/mcps/index.json`);
+}
+export async function searchRegistry(query, type) {
+    const results = [];
+    const queryLower = query.toLowerCase();
+    const matchesQuery = (item) => {
+        return (item.name.toLowerCase().includes(queryLower) ||
+            item.description.toLowerCase().includes(queryLower) ||
+            item.category?.toLowerCase().includes(queryLower) ||
+            false);
+    };
+    if (!type || type === "skill") {
+        try {
+            const skills = await fetchSkills();
+            for (const skill of skills) {
+                if (matchesQuery(skill)) {
+                    results.push({ type: "skill", item: skill });
+                }
+            }
+        }
+        catch {
+            // Registry might not exist yet
+        }
+    }
+    if (!type || type === "agent") {
+        try {
+            const agents = await fetchAgents();
+            for (const agent of agents) {
+                if (matchesQuery(agent)) {
+                    results.push({ type: "agent", item: agent });
+                }
+            }
+        }
+        catch {
+            // Registry might not exist yet
+        }
+    }
+    if (!type || type === "mcp") {
+        try {
+            const mcps = await fetchMCPs();
+            for (const mcp of mcps) {
+                if (matchesQuery(mcp)) {
+                    results.push({ type: "mcp", item: mcp });
+                }
+            }
+        }
+        catch {
+            // Registry might not exist yet
+        }
+    }
+    return results;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "claude-playbook",
+  "version": "0.1.0",
+  "description": "CLI for discovering and installing Claude Code skills, agents, and MCPs",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "claude-playbook": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnobleSCM/claude-code-playbook.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/AnobleSCM/claude-code-playbook/issues"
+  },
+  "homepage": "https://github.com/AnobleSCM/claude-code-playbook/tree/main/packages/cli#readme",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "cli",
+    "mcp",
+    "skills",
+    "anthropic"
+  ],
+  "author": "AnobleSCM",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ora": "^8.0.1",
+    "proper-lockfile": "^4.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}