@dhruvwill/skills-cli 1.0.0

package/src/lib/paths.ts

@@ -0,0 +1,236 @@
+import { homedir } from "os";
+import { join } from "path";
+
+/** Root directory for skills CLI */
+export const SKILLS_ROOT = join(homedir(), ".skills");
+
+/** Central store for all ingested skills */
+export const SKILLS_STORE = join(SKILLS_ROOT, "store");
+
+/** Configuration file path */
+export const CONFIG_PATH = join(SKILLS_ROOT, "config.json");
+
+/**
+ * Get the store path for a given namespace
+ */
+export function getNamespacePath(namespace: string): string {
+  return join(SKILLS_STORE, namespace);
+}
+
+export interface ParsedGitUrl {
+  host: string;
+  owner: string;
+  repo: string;
+  branch?: string;
+  subdir?: string;
+  cloneUrl: string;
+}
+
+/**
+ * Parse a Git URL from various hosts (GitHub, GitLab, Bitbucket, self-hosted)
+ * 
+ * Supports formats:
+ * - https://github.com/owner/repo
+ * - https://github.com/owner/repo/tree/branch/path
+ * - https://gitlab.com/owner/repo
+ * - https://gitlab.com/owner/repo/-/tree/branch/path
+ * - https://bitbucket.org/owner/repo
+ * - https://bitbucket.org/owner/repo/src/branch/path
+ * - https://any-host.com/owner/repo.git
+ * - git@host:owner/repo.git
+ */
+export function parseGitUrl(url: string): ParsedGitUrl | null {
+  // Try each parser in order
+  return parseGitHubUrl(url) 
+    || parseGitLabUrl(url) 
+    || parseBitbucketUrl(url) 
+    || parseGenericGitUrl(url);
+}
+
+/**
+ * Parse GitHub URLs
+ */
+function parseGitHubUrl(url: string): ParsedGitUrl | null {
+  // GitHub with subdirectory (tree or blob)
+  const subdirMatch = url.match(/github\.com\/([^\/]+)\/([^\/]+)\/(?:tree|blob)\/([^\/]+)\/(.+)/);
+  if (subdirMatch) {
+    const [, owner, repo, branch, subdir] = subdirMatch;
+    return {
+      host: "github.com",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      branch,
+      subdir: subdir.replace(/\/$/, ""),
+      cloneUrl: `https://github.com/${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  // GitHub basic HTTPS
+  const httpsMatch = url.match(/github\.com\/([^\/]+)\/([^\/\.\s]+)/);
+  if (httpsMatch) {
+    const [, owner, repo] = httpsMatch;
+    return {
+      host: "github.com",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      cloneUrl: `https://github.com/${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  // GitHub SSH
+  const sshMatch = url.match(/git@github\.com:([^\/]+)\/(.+?)(?:\.git)?$/);
+  if (sshMatch) {
+    const [, owner, repo] = sshMatch;
+    return {
+      host: "github.com",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      cloneUrl: `git@github.com:${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Parse GitLab URLs
+ */
+function parseGitLabUrl(url: string): ParsedGitUrl | null {
+  // GitLab with subdirectory (uses /-/tree/ pattern)
+  const subdirMatch = url.match(/gitlab\.com\/([^\/]+)\/([^\/]+)\/-\/tree\/([^\/]+)\/(.+)/);
+  if (subdirMatch) {
+    const [, owner, repo, branch, subdir] = subdirMatch;
+    return {
+      host: "gitlab.com",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      branch,
+      subdir: subdir.replace(/\/$/, ""),
+      cloneUrl: `https://gitlab.com/${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  // GitLab basic HTTPS
+  const httpsMatch = url.match(/gitlab\.com\/([^\/]+)\/([^\/\.\s]+)/);
+  if (httpsMatch) {
+    const [, owner, repo] = httpsMatch;
+    return {
+      host: "gitlab.com",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      cloneUrl: `https://gitlab.com/${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  // GitLab SSH
+  const sshMatch = url.match(/git@gitlab\.com:([^\/]+)\/(.+?)(?:\.git)?$/);
+  if (sshMatch) {
+    const [, owner, repo] = sshMatch;
+    return {
+      host: "gitlab.com",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      cloneUrl: `git@gitlab.com:${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Parse Bitbucket URLs
+ */
+function parseBitbucketUrl(url: string): ParsedGitUrl | null {
+  // Bitbucket with subdirectory (uses /src/branch/path pattern)
+  const subdirMatch = url.match(/bitbucket\.org\/([^\/]+)\/([^\/]+)\/src\/([^\/]+)\/(.+)/);
+  if (subdirMatch) {
+    const [, owner, repo, branch, subdir] = subdirMatch;
+    return {
+      host: "bitbucket.org",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      branch,
+      subdir: subdir.replace(/\/$/, ""),
+      cloneUrl: `https://bitbucket.org/${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  // Bitbucket basic HTTPS
+  const httpsMatch = url.match(/bitbucket\.org\/([^\/]+)\/([^\/\.\s]+)/);
+  if (httpsMatch) {
+    const [, owner, repo] = httpsMatch;
+    return {
+      host: "bitbucket.org",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      cloneUrl: `https://bitbucket.org/${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  // Bitbucket SSH
+  const sshMatch = url.match(/git@bitbucket\.org:([^\/]+)\/(.+?)(?:\.git)?$/);
+  if (sshMatch) {
+    const [, owner, repo] = sshMatch;
+    return {
+      host: "bitbucket.org",
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      cloneUrl: `git@bitbucket.org:${owner}/${repo.replace(/\.git$/, "")}.git`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Parse generic Git URLs (self-hosted, other providers)
+ */
+function parseGenericGitUrl(url: string): ParsedGitUrl | null {
+  // SSH format: git@host:owner/repo.git
+  const sshMatch = url.match(/git@([^:]+):([^\/]+)\/(.+?)(?:\.git)?$/);
+  if (sshMatch) {
+    const [, host, owner, repo] = sshMatch;
+    return {
+      host,
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      cloneUrl: url.endsWith(".git") ? url : `${url}.git`,
+    };
+  }
+
+  // HTTPS format: https://host/owner/repo.git or https://host/owner/repo
+  const httpsMatch = url.match(/https?:\/\/([^\/]+)\/([^\/]+)\/([^\/\.\s]+)/);
+  if (httpsMatch) {
+    const [, host, owner, repo] = httpsMatch;
+    return {
+      host,
+      owner,
+      repo: repo.replace(/\.git$/, ""),
+      cloneUrl: url.endsWith(".git") ? url : `${url}.git`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Get the namespace for a parsed Git URL
+ * For subdirectories, uses owner/skill-name
+ * For full repos, uses owner/repo
+ */
+export function getRemoteNamespace(parsed: ParsedGitUrl): string {
+  if (parsed.subdir) {
+    // Use the last part of the subdir path as the skill name
+    const subdirName = parsed.subdir.split("/").pop() || parsed.subdir;
+    return `${parsed.owner}/${subdirName}`;
+  }
+  return `${parsed.owner}/${parsed.repo}`;
+}
+
+/**
+ * Get the local namespace for a folder path
+ */
+export function getLocalNamespace(folderPath: string): string {
+  const folderName = folderPath.split(/[\/\\]/).filter(Boolean).pop() || "unnamed";
+  return `local/${folderName}`;
+}

package/src/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Source configuration - where skills originate from
+ */
+export interface Source {
+  /** Type of source */
+  type: "remote" | "local";
+  /** Git URL for remote sources */
+  url?: string;
+  /** Absolute path for local sources */
+  path?: string;
+  /** Store subdirectory (e.g., "anthropic/skills" or "local/my-folder") */
+  namespace: string;
+}
+
+/**
+ * Target configuration - where skills are synced to
+ */
+export interface Target {
+  /** User-friendly name (e.g., "cursor") */
+  name: string;
+  /** Absolute path to target directory */
+  path: string;
+}
+
+/**
+ * Main configuration file structure
+ */
+export interface Config {
+  sources: Source[];
+  targets: Target[];
+}
+
+/**
+ * Sync status for targets
+ */
+export type SyncStatus = "synced" | "not synced" | "target missing";

package/tests/cli.test.ts

@@ -0,0 +1,252 @@
+import { describe, test, expect, beforeEach, afterEach, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile, readdir } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import { $ } from "bun";
+
+/**
+ * Integration tests for CLI commands
+ * 
+ * These tests create temporary directories and clean up after themselves.
+ * They test the full CLI workflow including source and target management.
+ */
+
+describe("CLI Integration Tests", () => {
+  let testDir: string;
+  let testSourceDir: string;
+  let testTargetDir: string;
+
+  beforeAll(async () => {
+    // Create a master test directory
+    testDir = join(tmpdir(), `skills-integration-${Date.now()}`);
+    await mkdir(testDir, { recursive: true });
+
+    // Create test subdirectories
+    testSourceDir = join(testDir, "test-source");
+    testTargetDir = join(testDir, "test-target");
+
+    await mkdir(testSourceDir, { recursive: true });
+    await mkdir(testTargetDir, { recursive: true });
+
+    // Create a test skill in source directory
+    await writeFile(join(testSourceDir, "SKILL.md"), "# Test Skill\n\nThis is a test skill.");
+    await writeFile(join(testSourceDir, "rules.md"), "# Rules\n\n- Rule 1\n- Rule 2");
+  });
+
+  afterAll(async () => {
+    // Clean up test directory
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  describe("Local Source Management", () => {
+    test("can add a local source", async () => {
+      const result = await $`bun run src/cli.ts source add ${testSourceDir} --local`.text();
+      
+      expect(result).toContain("Adding local source");
+      expect(result).toContain("Successfully added local source");
+    });
+
+    test("lists the added source", async () => {
+      const result = await $`bun run src/cli.ts source list`.text();
+      
+      expect(result).toContain("local/test-source");
+      expect(result).toContain("local");
+      expect(result).toContain("OK");
+    });
+
+    test("can remove the source", async () => {
+      const result = await $`bun run src/cli.ts source remove local/test-source`.text();
+      
+      expect(result).toContain("Removed source");
+    });
+
+    test("source is no longer listed", async () => {
+      const result = await $`bun run src/cli.ts source list`.text();
+      
+      // The specific test source should be removed (may have other sources)
+      expect(result).not.toContain("local/test-source");
+    });
+  });
+
+  describe("Target Management", () => {
+    beforeEach(async () => {
+      // Add a source first
+      await $`bun run src/cli.ts source add ${testSourceDir} --local`.quiet();
+    });
+
+    afterEach(async () => {
+      // Clean up
+      try {
+        await $`bun run src/cli.ts target remove test-target`.quiet();
+      } catch {}
+      try {
+        await $`bun run src/cli.ts source remove local/test-source`.quiet();
+      } catch {}
+    });
+
+    test("can add a target", async () => {
+      const result = await $`bun run src/cli.ts target add test-target ${testTargetDir}`.text();
+      
+      expect(result).toContain("Adding target: test-target");
+      expect(result).toContain("Successfully registered target");
+      expect(result).toContain("Performing initial sync");
+    });
+
+    test("lists the added target with sync status", async () => {
+      await $`bun run src/cli.ts target add test-target ${testTargetDir}`.quiet();
+      
+      const result = await $`bun run src/cli.ts target list`.text();
+      
+      expect(result).toContain("test-target");
+      expect(result).toContain("synced");
+    });
+
+    test("can remove the target", async () => {
+      await $`bun run src/cli.ts target add test-target ${testTargetDir}`.quiet();
+      
+      const result = await $`bun run src/cli.ts target remove test-target`.text();
+      
+      expect(result).toContain("Removed target");
+    });
+  });
+
+  describe("Sync Operations", () => {
+    beforeEach(async () => {
+      // Add source and target
+      await $`bun run src/cli.ts source add ${testSourceDir} --local`.quiet();
+      await $`bun run src/cli.ts target add test-target ${testTargetDir}`.quiet();
+    });
+
+    afterEach(async () => {
+      try {
+        await $`bun run src/cli.ts target remove test-target`.quiet();
+      } catch {}
+      try {
+        await $`bun run src/cli.ts source remove local/test-source`.quiet();
+      } catch {}
+    });
+
+    test("sync copies files to target", async () => {
+      const result = await $`bun run src/cli.ts sync`.text();
+      
+      expect(result).toContain("Syncing skills to all targets");
+      expect(result).toContain("Synced");
+      expect(result).toContain("Sync complete");
+
+      // Verify files exist in target
+      const files = await readdir(testTargetDir, { recursive: true });
+      expect(files.length).toBeGreaterThan(0);
+    });
+
+    test("update refreshes sources", async () => {
+      const result = await $`bun run src/cli.ts update`.text();
+      
+      expect(result).toContain("Updating all sources");
+      expect(result).toContain("Updated");
+      expect(result).toContain("Update complete");
+    });
+  });
+
+  describe("Status and Doctor", () => {
+    test("status shows overview", async () => {
+      const result = await $`bun run src/cli.ts status`.text();
+      
+      expect(result).toContain("Skills Status");
+      expect(result).toContain("Paths");
+      expect(result).toContain("Sources");
+      expect(result).toContain("Targets");
+    });
+
+    test("doctor runs diagnostics", async () => {
+      const result = await $`bun run src/cli.ts doctor`.text();
+      
+      expect(result).toContain("Skills Doctor");
+      expect(result).toContain("Git");
+      expect(result).toContain("passed");
+    });
+  });
+
+  describe("Help and Version", () => {
+    test("--help shows usage", async () => {
+      const result = await $`bun run src/cli.ts --help`.text();
+      
+      expect(result).toContain("skills");
+      expect(result).toContain("USAGE");
+      expect(result).toContain("COMMANDS");
+      expect(result).toContain("source");
+      expect(result).toContain("target");
+      expect(result).toContain("sync");
+    });
+
+    test("-h shows usage", async () => {
+      const result = await $`bun run src/cli.ts -h`.text();
+      
+      expect(result).toContain("USAGE");
+    });
+
+    test("--version shows version", async () => {
+      const result = await $`bun run src/cli.ts --version`.text();
+      
+      expect(result).toMatch(/skills v\d+\.\d+\.\d+/);
+    });
+
+    test("-v shows version", async () => {
+      const result = await $`bun run src/cli.ts -v`.text();
+      
+      expect(result).toMatch(/skills v\d+\.\d+\.\d+/);
+    });
+
+    test("help command shows usage", async () => {
+      const result = await $`bun run src/cli.ts help`.text();
+      
+      expect(result).toContain("USAGE");
+    });
+  });
+
+  describe("Error Handling", () => {
+    test("unknown command shows error", async () => {
+      try {
+        await $`bun run src/cli.ts unknown-command`.text();
+        expect(true).toBe(false); // Should not reach
+      } catch (error: any) {
+        expect(error.stderr.toString()).toContain("Unknown command");
+      }
+    });
+
+    test("source add without flags shows error", async () => {
+      try {
+        await $`bun run src/cli.ts source add /some/path`.text();
+        expect(true).toBe(false); // Should not reach
+      } catch (error: any) {
+        expect(error.stderr.toString()).toContain("--remote or --local");
+      }
+    });
+
+    test("target add without path shows error", async () => {
+      try {
+        await $`bun run src/cli.ts target add myname`.text();
+        expect(true).toBe(false); // Should not reach
+      } catch (error: any) {
+        expect(error.stderr.toString()).toContain("Usage:");
+      }
+    });
+
+    test("removing non-existent source shows error", async () => {
+      try {
+        await $`bun run src/cli.ts source remove nonexistent/source`.text();
+        expect(true).toBe(false); // Should not reach
+      } catch (error: any) {
+        expect(error.stderr.toString()).toContain("not found");
+      }
+    });
+
+    test("removing non-existent target shows error", async () => {
+      try {
+        await $`bun run src/cli.ts target remove nonexistent`.text();
+        expect(true).toBe(false); // Should not reach
+      } catch (error: any) {
+        expect(error.stderr.toString()).toContain("not found");
+      }
+    });
+  });
+});

package/tests/config.test.ts

@@ -0,0 +1,135 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdir, rm } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+
+describe("Config Management", () => {
+  let testDir: string;
+  let testConfigPath: string;
+  let testStorePath: string;
+
+  beforeEach(async () => {
+    // Create a unique temp directory for each test
+    testDir = join(tmpdir(), `skills-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    testConfigPath = join(testDir, "config.json");
+    testStorePath = join(testDir, "store");
+    await mkdir(testDir, { recursive: true });
+    await mkdir(testStorePath, { recursive: true });
+  });
+
+  afterEach(async () => {
+    // Clean up test directory
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("creates default config when none exists", async () => {
+    expect(await Bun.file(testConfigPath).exists()).toBe(false);
+
+    // Write default config
+    const defaultConfig = { sources: [], targets: [] };
+    await Bun.write(testConfigPath, JSON.stringify(defaultConfig, null, 2));
+
+    // Re-check with fresh file reference
+    const configFile = Bun.file(testConfigPath);
+    expect(await configFile.exists()).toBe(true);
+    const content = await configFile.json();
+    expect(content).toEqual({ sources: [], targets: [] });
+  });
+
+  test("reads existing config", async () => {
+    const config = {
+      sources: [{ type: "remote", url: "https://github.com/test/repo", namespace: "test/repo" }],
+      targets: [{ name: "cursor", path: "/home/user/.cursor/skills" }],
+    };
+    await Bun.write(testConfigPath, JSON.stringify(config, null, 2));
+
+    const content = await Bun.file(testConfigPath).json();
+    expect(content.sources).toHaveLength(1);
+    expect(content.targets).toHaveLength(1);
+    expect(content.sources[0].namespace).toBe("test/repo");
+  });
+
+  test("adds source to config", async () => {
+    const config = { sources: [], targets: [] };
+    await Bun.write(testConfigPath, JSON.stringify(config, null, 2));
+
+    // Read, modify, write
+    const content = await Bun.file(testConfigPath).json();
+    content.sources.push({
+      type: "remote",
+      url: "https://github.com/new/repo",
+      namespace: "new/repo",
+    });
+    await Bun.write(testConfigPath, JSON.stringify(content, null, 2));
+
+    const updated = await Bun.file(testConfigPath).json();
+    expect(updated.sources).toHaveLength(1);
+    expect(updated.sources[0].namespace).toBe("new/repo");
+  });
+
+  test("removes source from config", async () => {
+    const config = {
+      sources: [
+        { type: "remote", url: "https://github.com/test/repo1", namespace: "test/repo1" },
+        { type: "remote", url: "https://github.com/test/repo2", namespace: "test/repo2" },
+      ],
+      targets: [],
+    };
+    await Bun.write(testConfigPath, JSON.stringify(config, null, 2));
+
+    // Read, modify, write
+    const content = await Bun.file(testConfigPath).json();
+    content.sources = content.sources.filter((s: any) => s.namespace !== "test/repo1");
+    await Bun.write(testConfigPath, JSON.stringify(content, null, 2));
+
+    const updated = await Bun.file(testConfigPath).json();
+    expect(updated.sources).toHaveLength(1);
+    expect(updated.sources[0].namespace).toBe("test/repo2");
+  });
+
+  test("adds target to config", async () => {
+    const config = { sources: [], targets: [] };
+    await Bun.write(testConfigPath, JSON.stringify(config, null, 2));
+
+    const content = await Bun.file(testConfigPath).json();
+    content.targets.push({
+      name: "cursor",
+      path: "/home/user/.cursor/skills",
+    });
+    await Bun.write(testConfigPath, JSON.stringify(content, null, 2));
+
+    const updated = await Bun.file(testConfigPath).json();
+    expect(updated.targets).toHaveLength(1);
+    expect(updated.targets[0].name).toBe("cursor");
+  });
+
+  test("removes target from config", async () => {
+    const config = {
+      sources: [],
+      targets: [
+        { name: "cursor", path: "/home/user/.cursor/skills" },
+        { name: "claude", path: "/home/user/.claude/skills" },
+      ],
+    };
+    await Bun.write(testConfigPath, JSON.stringify(config, null, 2));
+
+    const content = await Bun.file(testConfigPath).json();
+    content.targets = content.targets.filter((t: any) => t.name !== "cursor");
+    await Bun.write(testConfigPath, JSON.stringify(content, null, 2));
+
+    const updated = await Bun.file(testConfigPath).json();
+    expect(updated.targets).toHaveLength(1);
+    expect(updated.targets[0].name).toBe("claude");
+  });
+
+  test("handles corrupted config gracefully", async () => {
+    await Bun.write(testConfigPath, "not valid json {{{");
+
+    try {
+      await Bun.file(testConfigPath).json();
+      expect(true).toBe(false); // Should not reach here
+    } catch (error) {
+      expect(error).toBeDefined();
+    }
+  });
+});