@dhruvwill/skills-cli 1.0.0

package/src/cli.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env bun
+
+import chalk from "chalk";
+import { sourceAdd, sourceRemove, sourceList } from "./commands/source.ts";
+import { targetAdd, targetRemove, targetList } from "./commands/target.ts";
+import { sync } from "./commands/sync.ts";
+import { update } from "./commands/update.ts";
+import { doctor } from "./commands/doctor.ts";
+import { status } from "./commands/status.ts";
+
+const VERSION = "1.0.0";
+
+function printHelp() {
+  console.log(`
+${chalk.bold("skills")} - Sync AI skills across all your agent tools
+
+${chalk.bold("USAGE")}
+  ${chalk.cyan("skills")} <command> [options]
+
+${chalk.bold("COMMANDS")}
+  ${chalk.cyan("status")}                        Show overview of sources, targets & sync state
+  ${chalk.cyan("doctor")}                        Diagnose configuration issues
+
+  ${chalk.bold("Source Management")}
+  ${chalk.cyan("source list")}                   List all registered sources
+  ${chalk.cyan("source add")} <url> ${chalk.dim("--remote")}     Add a remote Git repository
+  ${chalk.cyan("source add")} <path> ${chalk.dim("--local")}     Add a local folder
+  ${chalk.cyan("source remove")} <namespace>     Remove a source
+
+  ${chalk.bold("Target Management")}
+  ${chalk.cyan("target list")}                   List all targets with sync status
+  ${chalk.cyan("target add")} <name> <path>      Add a target directory
+  ${chalk.cyan("target remove")} <name>          Remove a target
+
+  ${chalk.bold("Synchronization")}
+  ${chalk.cyan("sync")}                          Push skills from store to all targets
+  ${chalk.cyan("update")}                        Refresh all sources from origin
+
+${chalk.bold("OPTIONS")}
+  ${chalk.cyan("--help, -h")}                    Show this help message
+  ${chalk.cyan("--version, -v")}                 Show version
+
+${chalk.bold("EXAMPLES")}
+  ${chalk.dim("# Add skills from GitHub (supports subdirectories)")}
+  ${chalk.cyan("skills source add")} https://github.com/vercel/ai-skills --remote
+  ${chalk.cyan("skills source add")} https://github.com/user/repo/tree/main/skills/my-skill --remote
+
+  ${chalk.dim("# Add skills from GitLab or Bitbucket")}
+  ${chalk.cyan("skills source add")} https://gitlab.com/user/repo --remote
+  ${chalk.cyan("skills source add")} https://bitbucket.org/user/repo --remote
+
+  ${chalk.dim("# Add local skills folder")}
+  ${chalk.cyan("skills source add")} ./my-local-skills --local
+
+  ${chalk.dim("# Add targets and sync")}
+  ${chalk.cyan("skills target add")} cursor ~/.cursor/skills
+  ${chalk.cyan("skills target add")} claude ~/.claude/settings/skills
+  ${chalk.cyan("skills sync")}
+
+${chalk.bold("DOCUMENTATION")}
+  ${chalk.dim("https://github.com/yourusername/skills")}
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log(`skills v${VERSION}`);
+    process.exit(0);
+  }
+
+  const command = args[0];
+  const subcommand = args[1];
+
+  try {
+    switch (command) {
+      case "source":
+        await handleSourceCommand(subcommand, args.slice(2));
+        break;
+
+      case "target":
+        await handleTargetCommand(subcommand, args.slice(2));
+        break;
+
+      case "sync":
+        await sync();
+        break;
+
+      case "update":
+        await update();
+        break;
+
+      case "doctor":
+        await doctor();
+        break;
+
+      case "status":
+        await status();
+        break;
+
+      case "help":
+        printHelp();
+        break;
+
+      default:
+        console.error(chalk.red(`Unknown command: ${command}`));
+        console.log(`Run ${chalk.cyan("skills --help")} for usage.`);
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error instanceof Error ? error.message : error}`));
+    process.exit(1);
+  }
+}
+
+async function handleSourceCommand(subcommand: string, args: string[]) {
+  switch (subcommand) {
+    case "add": {
+      const pathOrUrl = args[0];
+      const isRemote = args.includes("--remote");
+      const isLocal = args.includes("--local");
+
+      if (!pathOrUrl) {
+        console.error("Missing path or URL for source add");
+        process.exit(1);
+      }
+
+      if (!isRemote && !isLocal) {
+        console.error("Please specify --remote or --local");
+        process.exit(1);
+      }
+
+      if (isRemote && isLocal) {
+        console.error("Cannot specify both --remote and --local");
+        process.exit(1);
+      }
+
+      await sourceAdd(pathOrUrl, isRemote ? "remote" : "local");
+      break;
+    }
+
+    case "remove": {
+      const namespace = args[0];
+      if (!namespace) {
+        console.error("Missing namespace for source remove");
+        process.exit(1);
+      }
+      await sourceRemove(namespace);
+      break;
+    }
+
+    case "list":
+      await sourceList();
+      break;
+
+    default:
+      console.error(`Unknown source subcommand: ${subcommand}`);
+      console.log("Available: add, remove, list");
+      process.exit(1);
+  }
+}
+
+async function handleTargetCommand(subcommand: string, args: string[]) {
+  switch (subcommand) {
+    case "add": {
+      const name = args[0];
+      const path = args[1];
+
+      if (!name || !path) {
+        console.error("Usage: skills target add <name> <path>");
+        process.exit(1);
+      }
+
+      await targetAdd(name, path);
+      break;
+    }
+
+    case "remove": {
+      const name = args[0];
+      if (!name) {
+        console.error("Missing name for target remove");
+        process.exit(1);
+      }
+      await targetRemove(name);
+      break;
+    }
+
+    case "list":
+      await targetList();
+      break;
+
+    default:
+      console.error(`Unknown target subcommand: ${subcommand}`);
+      console.log("Available: add, remove, list");
+      process.exit(1);
+  }
+}
+
+main();

package/src/commands/doctor.ts

@@ -0,0 +1,248 @@
+import chalk from "chalk";
+import { $ } from "bun";
+import { getSources, getTargets } from "../lib/config.ts";
+import { getNamespacePath, SKILLS_ROOT, SKILLS_STORE, CONFIG_PATH } from "../lib/paths.ts";
+import { directoryExists } from "../lib/hash.ts";
+
+interface DiagnosticResult {
+  name: string;
+  status: "ok" | "warn" | "error";
+  message: string;
+}
+
+/**
+ * Run diagnostics on the skills CLI configuration
+ */
+export async function doctor(): Promise<void> {
+  console.log();
+  console.log(chalk.bold("Skills Doctor"));
+  console.log(chalk.dim("─".repeat(50)));
+  console.log();
+
+  const results: DiagnosticResult[] = [];
+
+  // Check 1: Git installation
+  results.push(await checkGit());
+
+  // Check 2: Skills directory
+  results.push(await checkSkillsDirectory());
+
+  // Check 3: Config file
+  results.push(await checkConfigFile());
+
+  // Check 4: Store directory
+  results.push(await checkStoreDirectory());
+
+  // Check 5: Sources
+  results.push(...await checkSources());
+
+  // Check 6: Targets
+  results.push(...await checkTargets());
+
+  // Print results
+  for (const result of results) {
+    const icon = result.status === "ok" 
+      ? chalk.green("✓") 
+      : result.status === "warn" 
+        ? chalk.yellow("!") 
+        : chalk.red("✗");
+    
+    const statusColor = result.status === "ok"
+      ? chalk.green
+      : result.status === "warn"
+        ? chalk.yellow
+        : chalk.red;
+
+    console.log(`  ${icon} ${chalk.bold(result.name)}`);
+    console.log(`    ${statusColor(result.message)}`);
+    console.log();
+  }
+
+  // Summary
+  const errors = results.filter(r => r.status === "error").length;
+  const warnings = results.filter(r => r.status === "warn").length;
+  const ok = results.filter(r => r.status === "ok").length;
+
+  console.log(chalk.dim("─".repeat(50)));
+  
+  if (errors > 0) {
+    console.log(chalk.red(`${errors} error(s), ${warnings} warning(s), ${ok} passed`));
+  } else if (warnings > 0) {
+    console.log(chalk.yellow(`${warnings} warning(s), ${ok} passed`));
+  } else {
+    console.log(chalk.green(`All ${ok} checks passed!`));
+  }
+  
+  console.log();
+}
+
+async function checkGit(): Promise<DiagnosticResult> {
+  try {
+    const result = await $`git --version`.quiet();
+    const version = result.text().trim();
+    return {
+      name: "Git",
+      status: "ok",
+      message: version,
+    };
+  } catch {
+    return {
+      name: "Git",
+      status: "error",
+      message: "Git is not installed. Required for remote sources.",
+    };
+  }
+}
+
+async function checkSkillsDirectory(): Promise<DiagnosticResult> {
+  if (await directoryExists(SKILLS_ROOT)) {
+    return {
+      name: "Skills Directory",
+      status: "ok",
+      message: SKILLS_ROOT,
+    };
+  }
+  return {
+    name: "Skills Directory",
+    status: "warn",
+    message: `Not found: ${SKILLS_ROOT}. Will be created on first use.`,
+  };
+}
+
+async function checkConfigFile(): Promise<DiagnosticResult> {
+  const file = Bun.file(CONFIG_PATH);
+  if (await file.exists()) {
+    try {
+      await file.json();
+      return {
+        name: "Config File",
+        status: "ok",
+        message: CONFIG_PATH,
+      };
+    } catch {
+      return {
+        name: "Config File",
+        status: "error",
+        message: `Invalid JSON: ${CONFIG_PATH}`,
+      };
+    }
+  }
+  return {
+    name: "Config File",
+    status: "warn",
+    message: `Not found: ${CONFIG_PATH}. Will be created on first use.`,
+  };
+}
+
+async function checkStoreDirectory(): Promise<DiagnosticResult> {
+  if (await directoryExists(SKILLS_STORE)) {
+    const { readdir } = await import("fs/promises");
+    try {
+      const entries = await readdir(SKILLS_STORE);
+      const count = entries.length;
+      return {
+        name: "Store Directory",
+        status: "ok",
+        message: `${SKILLS_STORE} (${count} item${count !== 1 ? "s" : ""})`,
+      };
+    } catch {
+      return {
+        name: "Store Directory",
+        status: "ok",
+        message: SKILLS_STORE,
+      };
+    }
+  }
+  return {
+    name: "Store Directory",
+    status: "warn",
+    message: `Not found: ${SKILLS_STORE}. Will be created on first use.`,
+  };
+}
+
+async function checkSources(): Promise<DiagnosticResult[]> {
+  const results: DiagnosticResult[] = [];
+  
+  try {
+    const sources = await getSources();
+    
+    if (sources.length === 0) {
+      results.push({
+        name: "Sources",
+        status: "warn",
+        message: "No sources registered. Add one with: skills source add <url> --remote",
+      });
+      return results;
+    }
+
+    for (const source of sources) {
+      const path = getNamespacePath(source.namespace);
+      const exists = await directoryExists(path);
+      
+      if (exists) {
+        results.push({
+          name: `Source: ${source.namespace}`,
+          status: "ok",
+          message: `${source.type} → ${path}`,
+        });
+      } else {
+        results.push({
+          name: `Source: ${source.namespace}`,
+          status: "error",
+          message: `Missing directory: ${path}. Run: skills update`,
+        });
+      }
+    }
+  } catch (error) {
+    results.push({
+      name: "Sources",
+      status: "error",
+      message: `Failed to read sources: ${error}`,
+    });
+  }
+
+  return results;
+}
+
+async function checkTargets(): Promise<DiagnosticResult[]> {
+  const results: DiagnosticResult[] = [];
+  
+  try {
+    const targets = await getTargets();
+    
+    if (targets.length === 0) {
+      results.push({
+        name: "Targets",
+        status: "warn",
+        message: "No targets registered. Add one with: skills target add <name> <path>",
+      });
+      return results;
+    }
+
+    for (const target of targets) {
+      const exists = await directoryExists(target.path);
+      
+      if (exists) {
+        results.push({
+          name: `Target: ${target.name}`,
+          status: "ok",
+          message: target.path,
+        });
+      } else {
+        results.push({
+          name: `Target: ${target.name}`,
+          status: "warn",
+          message: `Directory missing: ${target.path}. Will be created on sync.`,
+        });
+      }
+    }
+  } catch (error) {
+    results.push({
+      name: "Targets",
+      status: "error",
+      message: `Failed to read targets: ${error}`,
+    });
+  }
+
+  return results;
+}

package/src/commands/source.ts

@@ -0,0 +1,191 @@
+import { $ } from "bun";
+import { resolve } from "path";
+import { rm, cp, mkdir } from "fs/promises";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { addSource, removeSource, getSources } from "../lib/config.ts";
+import { parseGitUrl, getRemoteNamespace, getLocalNamespace, getNamespacePath, SKILLS_STORE } from "../lib/paths.ts";
+import { directoryExists } from "../lib/hash.ts";
+
+/**
+ * Add a source (remote or local)
+ */
+export async function sourceAdd(pathOrUrl: string, type: "remote" | "local"): Promise<void> {
+  if (type === "remote") {
+    await addRemoteSource(pathOrUrl);
+  } else {
+    await addLocalSource(pathOrUrl);
+  }
+}
+
+/**
+ * Add a remote Git repository as a source
+ */
+async function addRemoteSource(url: string): Promise<void> {
+  const parsed = parseGitUrl(url);
+  
+  if (!parsed) {
+    throw new Error(`Invalid Git URL: ${url}. Expected formats:\n  - https://github.com/owner/repo\n  - https://gitlab.com/owner/repo\n  - https://bitbucket.org/owner/repo\n  - https://any-host.com/owner/repo.git`);
+  }
+
+  const namespace = getRemoteNamespace(parsed);
+  const targetPath = getNamespacePath(namespace);
+  const cloneUrl = parsed.cloneUrl;
+  const branch = parsed.branch || "main";
+
+  console.log(`Adding remote source: ${url}`);
+  console.log(`Namespace: ${namespace}`);
+  if (parsed.subdir) {
+    console.log(`Subdirectory: ${parsed.subdir}`);
+  }
+
+  // Check if directory already exists
+  if (await directoryExists(targetPath)) {
+    throw new Error(`Source already exists at ${namespace}. Remove it first with 'skills source remove ${namespace}'`);
+  }
+
+  // Create parent directory if needed
+  await mkdir(getNamespacePath(parsed.owner), { recursive: true });
+
+  // Clone the repository
+  console.log("Cloning repository...");
+  
+  try {
+    if (parsed.subdir) {
+      // Use sparse checkout to only get the specific subdirectory
+      const tempPath = `${targetPath}_temp`;
+      
+      // Initialize sparse checkout
+      await $`git clone --filter=blob:none --no-checkout --depth 1 --branch ${branch} ${cloneUrl} ${tempPath}`.quiet();
+      
+      // Configure sparse checkout
+      await $`git -C ${tempPath} sparse-checkout init --cone`.quiet();
+      await $`git -C ${tempPath} sparse-checkout set ${parsed.subdir}`.quiet();
+      await $`git -C ${tempPath} checkout`.quiet();
+      
+      // Move the subdirectory to the target path
+      const subdirFullPath = `${tempPath}/${parsed.subdir}`;
+      await cp(subdirFullPath, targetPath, { recursive: true });
+      
+      // Clean up temp directory
+      await rm(tempPath, { recursive: true, force: true });
+    } else {
+      // Clone the entire repository
+      await $`git clone --depth 1 --branch ${branch} ${cloneUrl} ${targetPath}`.quiet();
+      
+      // Remove .git directory to avoid nested git repos
+      await rm(`${targetPath}/.git`, { recursive: true, force: true });
+    }
+  } catch (error) {
+    // Clean up on failure
+    await rm(targetPath, { recursive: true, force: true });
+    await rm(`${targetPath}_temp`, { recursive: true, force: true });
+    throw new Error(`Failed to clone repository: ${error}`);
+  }
+
+  // Add to config
+  await addSource({
+    type: "remote",
+    url,
+    namespace,
+  });
+
+  console.log(`Successfully added remote source: ${namespace}`);
+}
+
+/**
+ * Add a local folder as a source
+ */
+async function addLocalSource(folderPath: string): Promise<void> {
+  const absolutePath = resolve(folderPath);
+  
+  if (!(await directoryExists(absolutePath))) {
+    throw new Error(`Local folder does not exist: ${absolutePath}`);
+  }
+
+  const namespace = getLocalNamespace(absolutePath);
+  const targetPath = getNamespacePath(namespace);
+
+  console.log(`Adding local source: ${absolutePath}`);
+  console.log(`Namespace: ${namespace}`);
+
+  // Check if namespace already exists
+  if (await directoryExists(targetPath)) {
+    throw new Error(`Source already exists at ${namespace}. Remove it first with 'skills source remove ${namespace}'`);
+  }
+
+  // Create local directory
+  await mkdir(getNamespacePath("local"), { recursive: true });
+
+  // Copy files
+  console.log("Copying files...");
+  await cp(absolutePath, targetPath, { recursive: true });
+
+  // Add to config
+  await addSource({
+    type: "local",
+    path: absolutePath,
+    namespace,
+  });
+
+  console.log(`Successfully added local source: ${namespace}`);
+}
+
+/**
+ * Remove a source by namespace
+ */
+export async function sourceRemove(namespace: string): Promise<void> {
+  const removed = await removeSource(namespace);
+  
+  if (!removed) {
+    throw new Error(`Source not found: ${namespace}`);
+  }
+
+  // Remove the files from store
+  const targetPath = getNamespacePath(namespace);
+  await rm(targetPath, { recursive: true, force: true });
+
+  console.log(`Removed source: ${namespace}`);
+}
+
+/**
+ * List all sources in a table format
+ */
+export async function sourceList(): Promise<void> {
+  const sources = await getSources();
+
+  if (sources.length === 0) {
+    console.log("No sources registered.");
+    console.log(`Add a source with: ${chalk.cyan("skills source add <url> --remote")}`);
+    return;
+  }
+
+  const table = new Table({
+    head: [
+      chalk.bold("Namespace"),
+      chalk.bold("Type"),
+      chalk.bold("Location"),
+      chalk.bold("Status"),
+    ],
+    style: {
+      head: [],
+      border: [],
+    },
+  });
+
+  for (const source of sources) {
+    const exists = await directoryExists(getNamespacePath(source.namespace));
+    const status = exists ? chalk.green("OK") : chalk.red("MISSING");
+    
+    table.push([
+      source.namespace,
+      source.type,
+      source.url || source.path || "",
+      status,
+    ]);
+  }
+
+  console.log();
+  console.log(table.toString());
+  console.log();
+}