simba-skills 0.1.2

package/README.md

@@ -0,0 +1,181 @@
+# Simba
+
+[![npm version](https://img.shields.io/npm/v/simba-skills)](https://www.npmjs.com/package/simba-skills)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+AI skills manager with a central store and symlink-based distribution across 14+ coding agents.
+
+## Why Simba?
+
+Most skill installers are one-shot: they clone a repo and copy files. Simba is a **skill lifecycle manager**:
+
+- **Central store** → One source of truth at `~/.config/simba/skills/`
+- **Registry tracking** → Records install sources, enabling one-command updates
+- **Symlink distribution** → No file duplication; changes propagate instantly
+- **Multi-agent sync** → Keep Claude, Cursor, Copilot, and others in sync
+- **Rollback support** → Automatic snapshots before destructive operations
+
+## Installation
+
+```bash
+# Requires Bun runtime
+bunx simba-skills detect
+```
+
+Or install globally:
+
+```bash
+bun install -g simba-skills
+```
+
+## Quick Start
+
+```bash
+# Detect installed agents
+simba detect
+
+# Adopt existing skills into the central store
+simba adopt
+
+# Install skills from GitHub
+simba install vercel-labs/agent-skills
+
+# Assign skills to specific agents
+simba assign my-skill claude,cursor
+
+# Check for updates (uses tracked install sources)
+simba update
+
+# View skill matrix across all agents
+simba status
+```
+
+## Key Features
+
+### Install & Update
+
+```bash
+# Install from GitHub (HTTPS)
+simba install user/repo
+
+# Install from private repos (SSH)
+simba install user/repo --ssh
+
+# Install from local path (creates symlinks, auto-syncs)
+simba install ~/my-skills
+
+# Update all installed skills from their sources
+simba update
+```
+
+Simba records the source repository and path during installation, enabling `simba update` to fetch and compare changes with diffs.
+
+### Assign & Manage
+
+```bash
+# Assign skill to multiple agents
+simba assign my-skill claude,cursor,copilot
+
+# Interactive TUI for bulk management
+simba manage
+
+# Remove skill from agents
+simba unassign my-skill claude
+```
+
+### Health & Recovery
+
+```bash
+# Check symlink integrity
+simba doctor
+
+# Auto-repair broken symlinks
+simba doctor --fix
+
+# Backup all skills
+simba backup ./skills.tar.gz --includeConfig
+
+# Restore from backup
+simba restore ./skills.tar.gz
+
+# Undo last operation
+simba undo
+```
+
+## Supported Agents
+
+| Agent | Global Path | Project Path |
+|-------|-------------|--------------|
+| Claude Code | `~/.claude/skills` | `.claude/skills` |
+| Cursor | `~/.cursor/skills` | `.cursor/skills` |
+| Codex | `~/.codex/skills` | `.codex/skills` |
+| GitHub Copilot | `~/.copilot/skills` | `.github/skills` |
+| Gemini CLI | `~/.gemini/skills` | `.gemini/skills` |
+| Windsurf | `~/.codeium/windsurf/skills` | `.windsurf/skills` |
+| Amp | `~/.config/agents/skills` | `.agents/skills` |
+| Goose | `~/.config/goose/skills` | `.goose/skills` |
+| OpenCode | `~/.config/opencode/skill` | `.opencode/skill` |
+| Kilo Code | `~/.kilocode/skills` | `.kilocode/skills` |
+| Roo Code | `~/.roo/skills` | `.roo/skills` |
+| Antigravity | `~/.gemini/antigravity/skills` | `.agent/skills` |
+| Clawdbot | `~/.clawdbot/skills` | `skills` |
+| Droid | `~/.factory/skills` | `.factory/skills` |
+
+## Architecture
+
+```
+~/.config/simba/
+├── config.toml           # Settings
+├── registry.json         # Skill metadata, sources & assignments
+├── skills/               # Central store
+│   └── my-skill/
+│       └── SKILL.md
+└── snapshots/            # Automatic rollback points
+
+~/.claude/skills/
+└── my-skill → ~/.config/simba/skills/my-skill  (symlink)
+
+~/.cursor/skills/
+└── my-skill → ~/.config/simba/skills/my-skill  (symlink)
+```
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `detect` | Scan for installed agents |
+| `adopt` | Move existing skills into central store |
+| `install` | Install from GitHub or local path |
+| `uninstall` | Remove skill from store and agents |
+| `update` | Check and apply updates from sources |
+| `list` | List managed skills |
+| `status` | Skill matrix across agents |
+| `assign` | Symlink skill to agents |
+| `unassign` | Remove skill from agents |
+| `manage` | Interactive TUI |
+| `sync` | Union merge across agents |
+| `migrate` | Copy all skills from one agent to another |
+| `doctor` | Verify and repair symlinks |
+| `backup` | Export skills to archive |
+| `restore` | Restore from backup |
+| `snapshots` | List rollback points |
+| `undo` | Restore from last snapshot |
+| `import` | Copy global skill to project for customization |
+
+## Configuration
+
+Config at `~/.config/simba/config.toml`:
+
+```toml
+[snapshots]
+maxCount = 10
+autoSnapshot = true
+
+[sync]
+strategy = "union"  # or "source"
+sourceAgent = ""    # for source strategy
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "simba-skills",
+  "version": "0.1.2",
+  "description": "AI skills manager - central store with symlink-based distribution across 14+ coding agents",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "license": "MIT",
+  "author": "Ethan Fann",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ethanfann/simba"
+  },
+  "keywords": [
+    "ai",
+    "skills",
+    "claude",
+    "cursor",
+    "copilot",
+    "codex",
+    "amp",
+    "gemini",
+    "windsurf",
+    "agent",
+    "cli"
+  ],
+  "bin": {
+    "simba": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "test": "bun test",
+    "lint": "bunx tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/tar": "^6.1.13",
+    "@types/terminal-kit": "^2.5.7",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@pierre/diffs": "^1.0.6",
+    "citty": "^0.1.6",
+    "gray-matter": "^4.0.3",
+    "simple-git": "^3.30.0",
+    "smol-toml": "^1.3.0",
+    "tar": "^7.5.3",
+    "terminal-kit": "^3.1.2"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/commands/adopt.ts

@@ -0,0 +1,232 @@
+import { defineCommand } from "citty"
+import { readdir, rm, access, readFile, stat } from "node:fs/promises"
+import { join } from "node:path"
+import * as p from "@clack/prompts"
+import matter from "gray-matter"
+import { ConfigStore } from "../core/config-store"
+import { RegistryStore } from "../core/registry-store"
+import { SkillsStore } from "../core/skills-store"
+import { AgentRegistry } from "../core/agent-registry"
+import { getConfigPath, getSkillsDir, getRegistryPath, expandPath } from "../utils/paths"
+import { isSymlink, createSymlink } from "../utils/symlinks"
+import { compareFiles, renderDiff, renderIdenticalMessage } from "../utils/diff"
+import type { Agent, ManagedSkill } from "../core/types"
+
+export interface ConflictingSkill {
+  agentId: string
+  path: string
+}
+
+export interface AdoptOptions {
+  skillsDir: string
+  registryPath: string
+  configPath: string
+  agents: Record<string, Agent>
+  dryRun: boolean
+  onConflict: (skillName: string, skills: ConflictingSkill[]) => Promise<string>
+}
+
+interface DiscoveredSkill {
+  name: string
+  agentId: string
+  path: string
+}
+
+export async function runAdopt(options: AdoptOptions): Promise<void> {
+  const skillsStore = new SkillsStore(options.skillsDir, options.registryPath)
+  const registryStore = new RegistryStore(options.registryPath)
+  const registry = await registryStore.load()
+
+  const discovered: DiscoveredSkill[] = []
+  for (const [agentId, agent] of Object.entries(options.agents)) {
+    if (!agent.detected) continue
+
+    const agentPath = expandPath(agent.globalPath)
+    try {
+      const entries = await readdir(agentPath, { withFileTypes: true })
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+
+        const skillPath = join(agentPath, entry.name)
+        if (await isSymlink(skillPath)) continue
+
+        try {
+          await access(join(skillPath, "SKILL.md"))
+        } catch {
+          continue
+        }
+
+        discovered.push({ name: entry.name, agentId, path: skillPath })
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err
+    }
+  }
+
+  const byName = new Map<string, DiscoveredSkill[]>()
+  for (const skill of discovered) {
+    if (!byName.has(skill.name)) byName.set(skill.name, [])
+    byName.get(skill.name)!.push(skill)
+  }
+
+  const toAdopt: Array<{ name: string; skill: DiscoveredSkill }> = []
+  for (const [name, skills] of byName) {
+    if (await skillsStore.hasSkill(name)) {
+      console.log(`  Skipping ${name} (already in store)`)
+      continue
+    }
+
+    if (skills.length === 1) {
+      toAdopt.push({ name, skill: skills[0] })
+    } else {
+      const conflictingSkills = skills.map(s => ({ agentId: s.agentId, path: s.path }))
+      const chosenAgent = await options.onConflict(name, conflictingSkills)
+      const chosen = skills.find(s => s.agentId === chosenAgent)!
+      toAdopt.push({ name, skill: chosen })
+    }
+  }
+
+  if (toAdopt.length === 0) {
+    console.log("\nNo new skills to adopt.")
+    return
+  }
+
+  console.log(`\nAdopting ${toAdopt.length} skills...`)
+
+  if (options.dryRun) {
+    for (const { name, skill } of toAdopt) {
+      console.log(`  Would adopt: ${name} (from ${skill.agentId})`)
+    }
+    console.log("\n(dry run - no changes made)")
+    return
+  }
+
+  for (const { name, skill } of toAdopt) {
+    await skillsStore.addSkill(name, skill.path)
+    await rm(skill.path, { recursive: true })
+    await createSymlink(join(options.skillsDir, name), skill.path)
+
+    const managedSkill: ManagedSkill = {
+      name,
+      source: `adopted:${skill.agentId}`,
+      installedAt: new Date().toISOString(),
+      assignments: { [skill.agentId]: { type: "directory" } }
+    }
+    registry.skills[name] = managedSkill
+
+    console.log(`  Adopted: ${name} (from ${skill.agentId})`)
+  }
+
+  await registryStore.save(registry)
+  console.log("\nAdoption complete!")
+}
+
+export default defineCommand({
+  meta: { name: "adopt", description: "Adopt skills from agents into Simba's store" },
+  args: {
+    dryRun: { type: "boolean", alias: "n", description: "Preview changes without applying", default: false },
+  },
+  async run({ args }) {
+    const configStore = new ConfigStore(getConfigPath())
+    const config = await configStore.load()
+
+    const agentRegistry = new AgentRegistry(config.agents)
+    const detected = await agentRegistry.detectAgents()
+
+    const detectedAgents = Object.fromEntries(
+      Object.entries(detected).filter(([, a]) => a.detected)
+    )
+
+    if (Object.keys(detectedAgents).length === 0) {
+      console.log("No agents detected. Run 'simba detect' first.")
+      return
+    }
+
+    console.log("\nScanning agents for skills...")
+    for (const [id, agent] of Object.entries(detectedAgents)) {
+      console.log(`  ${agent.name}`)
+    }
+
+    await runAdopt({
+      skillsDir: getSkillsDir(),
+      registryPath: getRegistryPath(),
+      configPath: getConfigPath(),
+      agents: detectedAgents,
+      dryRun: args.dryRun,
+      onConflict: async (skillName, skills) => {
+        // Read SKILL.md content and metadata from each conflicting skill
+        const contents = await Promise.all(
+          skills.map(async (s) => {
+            const skillPath = join(s.path, "SKILL.md")
+            const [content, stats] = await Promise.all([
+              readFile(skillPath, "utf-8"),
+              stat(skillPath),
+            ])
+            const parsed = matter(content)
+            return {
+              agentId: s.agentId,
+              content,
+              mtime: stats.mtime,
+              version: parsed.data.version as string | undefined,
+            }
+          })
+        )
+
+        // Check if all versions are identical
+        const firstContent = contents[0].content
+        const allIdentical = contents.every((c) => c.content === firstContent)
+
+        if (allIdentical) {
+          renderIdenticalMessage(skillName)
+          return contents[0].agentId
+        }
+
+        // Compare semver strings (basic: split by dots, compare numerically)
+        const compareSemver = (a: string, b: string): number => {
+          const pa = a.split(".").map((n) => parseInt(n, 10) || 0)
+          const pb = b.split(".").map((n) => parseInt(n, 10) || 0)
+          for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+            const diff = (pa[i] || 0) - (pb[i] || 0)
+            if (diff !== 0) return diff
+          }
+          return 0
+        }
+
+        // Find newest: prefer version comparison if all have versions
+        const allHaveVersions = contents.every((c) => c.version)
+        const newest = allHaveVersions
+          ? contents.reduce((a, b) => (compareSemver(a.version!, b.version!) >= 0 ? a : b))
+          : contents.reduce((a, b) => (a.mtime > b.mtime ? a : b))
+
+        // Show diff between first two versions (most common case)
+        const comparison = compareFiles(
+          contents[0].content,
+          contents[1].content,
+          "SKILL.md"
+        )
+
+        if (comparison.diff) {
+          renderDiff(comparison.diff, contents[0].agentId, contents[1].agentId)
+        }
+
+        // Format options with version or date
+        const formatDate = (d: Date) =>
+          d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" })
+
+        const result = await p.select({
+          message: `Conflict: "${skillName}" exists in multiple agents. Which version?`,
+          options: contents.map((c) => {
+            const info = c.version ? `v${c.version}` : formatDate(c.mtime)
+            const isNewest = c.agentId === newest.agentId
+            return {
+              value: c.agentId,
+              label: `${c.agentId} (${info})${isNewest ? " ← newest" : ""}`,
+            }
+          }),
+        })
+        if (p.isCancel(result)) process.exit(0)
+        return result as string
+      },
+    })
+  },
+})

package/src/commands/assign.ts

@@ -0,0 +1,110 @@
+import { defineCommand } from "citty"
+import * as p from "@clack/prompts"
+import { RegistryStore } from "../core/registry-store"
+import { SkillsStore } from "../core/skills-store"
+import { ConfigStore } from "../core/config-store"
+import { AgentRegistry } from "../core/agent-registry"
+import { getSkillsDir, getRegistryPath, getConfigPath, expandPath } from "../utils/paths"
+
+export interface AssignOptions {
+  skill: string
+  agents: string[]
+  skillsDir: string
+  registryPath: string
+  agentPaths: Record<string, string>
+}
+
+export async function runAssign(options: AssignOptions): Promise<void> {
+  const skillsStore = new SkillsStore(options.skillsDir, options.registryPath)
+  const registryStore = new RegistryStore(options.registryPath)
+  const registry = await registryStore.load()
+
+  const skill = registry.skills[options.skill]
+  if (!skill) {
+    console.error(`Skill not found: ${options.skill}`)
+    process.exit(1)
+  }
+
+  for (const agentId of options.agents) {
+    const agentPath = options.agentPaths[agentId]
+    if (!agentPath) {
+      console.error(`Unknown agent: ${agentId}`)
+      continue
+    }
+
+    await skillsStore.assignSkill(options.skill, agentPath, { type: "directory" })
+    skill.assignments[agentId] = { type: "directory" }
+    console.log(`Assigned ${options.skill} to ${agentId}`)
+  }
+
+  await registryStore.save(registry)
+}
+
+export default defineCommand({
+  meta: { name: "assign", description: "Assign a skill to agents" },
+  args: {
+    skill: { type: "positional", description: "Skill name", required: false },
+    agents: { type: "positional", description: "Agent IDs (comma-separated)", required: false },
+  },
+  async run({ args }) {
+    const configStore = new ConfigStore(getConfigPath())
+    const config = await configStore.load()
+
+    const registryStore = new RegistryStore(getRegistryPath())
+    const registry = await registryStore.load()
+
+    // Get detected agents
+    const agentRegistry = new AgentRegistry(config.agents)
+    const detected = await agentRegistry.detectAgents()
+    const detectedAgents = Object.entries(detected).filter(([, a]) => a.detected)
+
+    const agentPaths: Record<string, string> = {}
+    for (const [id, agent] of detectedAgents) {
+      agentPaths[id] = expandPath(agent.globalPath)
+    }
+
+    // Interactive mode if args missing
+    let skill = args.skill as string | undefined
+    let agents: string[]
+
+    if (!skill) {
+      const skills = Object.keys(registry.skills)
+      if (skills.length === 0) {
+        console.log("No skills managed. Run 'simba adopt' first.")
+        return
+      }
+
+      const result = await p.select({
+        message: "Select a skill to assign",
+        options: skills.map((s) => ({ value: s, label: s })),
+      })
+      if (p.isCancel(result)) process.exit(0)
+      skill = result as string
+    }
+
+    if (!args.agents) {
+      if (detectedAgents.length === 0) {
+        console.log("No agents detected.")
+        return
+      }
+
+      const result = await p.multiselect({
+        message: "Select agents to assign to",
+        options: detectedAgents.map(([id, a]) => ({ value: id, label: a.name })),
+        required: true,
+      })
+      if (p.isCancel(result)) process.exit(0)
+      agents = result as string[]
+    } else {
+      agents = (args.agents as string).split(",").map((a) => a.trim())
+    }
+
+    await runAssign({
+      skill,
+      agents,
+      skillsDir: getSkillsDir(),
+      registryPath: getRegistryPath(),
+      agentPaths,
+    })
+  },
+})

package/src/commands/backup.ts

@@ -0,0 +1,121 @@
+import { defineCommand } from "citty"
+import { ConfigStore } from "../core/config-store"
+import { AgentRegistry } from "../core/agent-registry"
+import { getConfigPath, expandPath } from "../utils/paths"
+import { inputText } from "../utils/prompts"
+import { mkdir, writeFile, readFile } from "node:fs/promises"
+import { join, dirname } from "node:path"
+import * as tar from "tar"
+
+export default defineCommand({
+  meta: {
+    name: "backup",
+    description: "Export all skills to archive",
+  },
+  args: {
+    path: {
+      type: "positional",
+      description: "Output path (.tar.gz)",
+    },
+    includeConfig: {
+      type: "boolean",
+      description: "Include simba config in backup",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const configStore = new ConfigStore(getConfigPath())
+    const config = await configStore.load()
+    const registry = new AgentRegistry(config.agents)
+
+    // Prompt for path if not provided
+    const defaultPath = `./simba-backup-${new Date().toISOString().slice(0, 10)}.tar.gz`
+    let outputPath = args.path
+    if (!outputPath) {
+      outputPath = await inputText("Output path:", {
+        placeholder: defaultPath,
+        defaultValue: defaultPath,
+      })
+    }
+
+    // Collect all unique skills
+    const allSkills = new Map<string, { path: string; origin: string }>()
+
+    for (const [agentId, agent] of Object.entries(config.agents)) {
+      if (!agent.detected) continue
+
+      const skills = await registry.listSkills(agentId)
+      for (const skill of skills) {
+        if (!allSkills.has(skill.name)) {
+          allSkills.set(skill.name, {
+            path: registry.getSkillPath(skill.name, agentId),
+            origin: agentId,
+          })
+        }
+      }
+    }
+
+    if (allSkills.size === 0) {
+      console.log("No skills to backup.")
+      return
+    }
+
+    // Create temp directory for backup structure
+    const tempDir = join(dirname(outputPath), `.simba-backup-${Date.now()}`)
+    const skillsDir = join(tempDir, "skills")
+    await mkdir(skillsDir, { recursive: true })
+
+    // Copy skills to temp structure
+    const manifest = {
+      version: "1",
+      created: new Date().toISOString(),
+      simba_version: "0.1.0",
+      source_agents: [...new Set(Array.from(allSkills.values()).map((s) => s.origin))],
+      skills: {} as Record<string, { hash: string; origin: string; files: string[] }>,
+      includes_config: args.includeConfig,
+    }
+
+    for (const [name, { path, origin }] of allSkills) {
+      const destPath = join(skillsDir, name)
+      await Bun.$`cp -r ${path} ${destPath}`
+
+      const skill = (await registry.listSkills(origin)).find((s) => s.name === name)
+      if (skill) {
+        manifest.skills[name] = {
+          hash: skill.treeHash,
+          origin,
+          files: skill.files.map((f) => f.path),
+        }
+      }
+    }
+
+    // Write manifest
+    await writeFile(
+      join(tempDir, "manifest.json"),
+      JSON.stringify(manifest, null, 2)
+    )
+
+    // Include config if requested
+    if (args.includeConfig) {
+      const configContent = await readFile(getConfigPath(), "utf-8")
+      await writeFile(join(tempDir, "config.toml"), configContent)
+    }
+
+    // Create tar.gz
+    await tar.create(
+      {
+        gzip: true,
+        file: outputPath,
+        cwd: tempDir,
+      },
+      ["manifest.json", "skills", ...(args.includeConfig ? ["config.toml"] : [])]
+    )
+
+    // Cleanup temp
+    await Bun.$`rm -rf ${tempDir}`
+
+    console.log(`\nBackup created: ${outputPath}`)
+    console.log(`Skills: ${allSkills.size}`)
+    console.log(`Config included: ${args.includeConfig}`)
+  },
+})