simba-skills 0.1.2

package/src/core/snapshot.ts

@@ -0,0 +1,123 @@
+import { mkdir, cp, readdir, writeFile, readFile, rm } from "node:fs/promises"
+import { join, basename, dirname } from "node:path"
+
+export interface SnapshotManifest {
+  id: string
+  reason: string
+  created: string
+  skills: string[]
+}
+
+export class SnapshotManager {
+  constructor(
+    private snapshotsDir: string,
+    private maxCount: number
+  ) {}
+
+  async createSnapshot(skillPaths: string[], reason: string): Promise<string> {
+    const id = this.generateId()
+    const snapshotDir = join(this.snapshotsDir, id)
+    const skillsBackupDir = join(snapshotDir, "skills")
+
+    await mkdir(skillsBackupDir, { recursive: true })
+
+    const skillNames: string[] = []
+
+    for (const skillPath of skillPaths) {
+      const skillName = basename(skillPath)
+      skillNames.push(skillName)
+      await cp(skillPath, join(skillsBackupDir, skillName), { recursive: true })
+    }
+
+    const manifest: SnapshotManifest = {
+      id,
+      reason,
+      created: new Date().toISOString(),
+      skills: skillNames,
+    }
+
+    await writeFile(
+      join(snapshotDir, "manifest.json"),
+      JSON.stringify(manifest, null, 2)
+    )
+
+    await this.pruneOldSnapshots()
+
+    return id
+  }
+
+  async listSnapshots(): Promise<SnapshotManifest[]> {
+    try {
+      const entries = await readdir(this.snapshotsDir, { withFileTypes: true })
+      const manifests: SnapshotManifest[] = []
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+
+        try {
+          const manifestPath = join(this.snapshotsDir, entry.name, "manifest.json")
+          const content = await readFile(manifestPath, "utf-8")
+          manifests.push(JSON.parse(content))
+        } catch {
+          continue
+        }
+      }
+
+      return manifests.sort(
+        (a, b) => new Date(b.created).getTime() - new Date(a.created).getTime()
+      )
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return []
+      }
+      throw err
+    }
+  }
+
+  async restore(snapshotId: string, targetDir: string): Promise<void> {
+    const snapshotDir = join(this.snapshotsDir, snapshotId)
+    const skillsBackupDir = join(snapshotDir, "skills")
+    const manifestPath = join(snapshotDir, "manifest.json")
+
+    const manifest: SnapshotManifest = JSON.parse(
+      await readFile(manifestPath, "utf-8")
+    )
+
+    for (const skillName of manifest.skills) {
+      const sourcePath = join(skillsBackupDir, skillName)
+      const targetPath = join(targetDir, skillName)
+
+      // Ensure parent exists, remove old version if present
+      await mkdir(dirname(targetPath), { recursive: true })
+      try {
+        await rm(targetPath, { recursive: true })
+      } catch {
+        // Ignore if doesn't exist
+      }
+
+      await cp(sourcePath, targetPath, { recursive: true })
+    }
+  }
+
+  async getLatestSnapshot(): Promise<SnapshotManifest | null> {
+    const list = await this.listSnapshots()
+    return list[0] ?? null
+  }
+
+  private generateId(): string {
+    const now = new Date()
+    // Include milliseconds for uniqueness when creating multiple snapshots quickly
+    return now.toISOString().replace(/[:.]/g, "-").slice(0, 23)
+  }
+
+  private async pruneOldSnapshots(): Promise<void> {
+    const list = await this.listSnapshots()
+
+    if (list.length <= this.maxCount) return
+
+    const toDelete = list.slice(this.maxCount)
+    for (const snapshot of toDelete) {
+      await rm(join(this.snapshotsDir, snapshot.id), { recursive: true })
+    }
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,75 @@
+// Core types for simba
+
+export interface Agent {
+  id: string
+  name: string
+  shortName: string // Short display name for matrix views (max 8 chars)
+  globalPath: string
+  projectPath: string
+  detected: boolean
+}
+
+export interface SkillFile {
+  path: string
+  hash: string
+}
+
+export interface SkillInfo {
+  name: string
+  treeHash: string
+  files: SkillFile[]
+  origin: string
+  lastSeen: Date
+  agents: string[]
+}
+
+export interface SyncConfig {
+  strategy: "union" | "source"
+  sourceAgent: string
+}
+
+export interface SnapshotConfig {
+  maxCount: number
+  autoSnapshot: boolean
+}
+
+export interface Config {
+  agents: Record<string, Agent>
+  sync: SyncConfig
+  snapshots: SnapshotConfig
+  skills: Record<string, SkillInfo>
+}
+
+export type SkillStatus = "synced" | "conflict" | "unique" | "missing"
+
+export interface SkillMatrix {
+  skillName: string
+  agents: Record<string, { present: boolean; hash: string | null }>
+  status: SkillStatus
+}
+
+// Registry types for skill management
+
+export interface SkillAssignment {
+  type: "directory" | "file"
+  target?: string // For file type, which file to symlink (e.g., "rule.mdc")
+}
+
+export interface InstallSource {
+  repo: string // GitHub shorthand "user/repo", full URL, or absolute local path
+  protocol: "https" | "ssh" | "local"
+  skillPath?: string // Path within repo, e.g., "./better-auth/create-auth"
+}
+
+export interface ManagedSkill {
+  name: string
+  source: string // "adopted:claude", "installed:vercel-labs/agent-skills", etc.
+  installedAt: string // ISO date
+  assignments: Record<string, SkillAssignment> // agentId -> assignment
+  installSource?: InstallSource // Present for installed skills, powers updates
+}
+
+export interface Registry {
+  version: 1
+  skills: Record<string, ManagedSkill>
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+
+import { defineCommand, runMain } from "citty"
+
+const main = defineCommand({
+  meta: {
+    name: "simba",
+    version: "0.2.0",
+    description: "AI skills manager",
+  },
+  subCommands: {
+    adopt: () => import("./commands/adopt").then((m) => m.default),
+    assign: () => import("./commands/assign").then((m) => m.default),
+    backup: () => import("./commands/backup").then((m) => m.default),
+    detect: () => import("./commands/detect").then((m) => m.default),
+    doctor: () => import("./commands/doctor").then((m) => m.default),
+    import: () => import("./commands/import").then((m) => m.default),
+    install: () => import("./commands/install").then((m) => m.default),
+    list: () => import("./commands/list").then((m) => m.default),
+    manage: () => import("./commands/manage").then((m) => m.default),
+    migrate: () => import("./commands/migrate").then((m) => m.default),
+    restore: () => import("./commands/restore").then((m) => m.default),
+    snapshots: () => import("./commands/snapshots").then((m) => m.default),
+    status: () => import("./commands/status").then((m) => m.default),
+    sync: () => import("./commands/sync").then((m) => m.default),
+    unassign: () => import("./commands/unassign").then((m) => m.default),
+    uninstall: () => import("./commands/uninstall").then((m) => m.default),
+    undo: () => import("./commands/undo").then((m) => m.default),
+    update: () => import("./commands/update").then((m) => m.default),
+  },
+})
+
+runMain(main)

package/src/tui/matrix.ts

@@ -0,0 +1,189 @@
+import termkit from "terminal-kit"
+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 { getRegistryPath, getSkillsDir, getConfigPath, expandPath } from "../utils/paths"
+import type { Agent, Registry } from "../core/types"
+
+// Cast to any to access showCursor (missing from @types/terminal-kit)
+const term = termkit.terminal as typeof termkit.terminal & { showCursor: () => void }
+
+interface MatrixState {
+  skills: string[]
+  agents: Agent[]
+  registry: Registry
+  cursorRow: number
+  cursorCol: number
+}
+
+export async function runMatrixTUI(): Promise<void> {
+  const registryStore = new RegistryStore(getRegistryPath())
+  const registry = await registryStore.load()
+
+  const configStore = new ConfigStore(getConfigPath())
+  const config = await configStore.load()
+
+  const skillsStore = new SkillsStore(getSkillsDir(), getRegistryPath())
+
+  // Run fresh detection instead of relying on stale config
+  const agentRegistry = new AgentRegistry(config.agents)
+  const detected = await agentRegistry.detectAgents()
+  const detectedAgents = Object.values(detected).filter(a => a.detected)
+  const skills = Object.keys(registry.skills)
+
+  if (skills.length === 0) {
+    term.yellow("\nNo skills managed yet. Run 'simba adopt' first.\n")
+    process.exit(0)
+  }
+
+  const state: MatrixState = {
+    skills,
+    agents: detectedAgents,
+    registry,
+    cursorRow: 0,
+    cursorCol: 0,
+  }
+
+  term.clear()
+  term.hideCursor()
+
+  const render = () => {
+    term.moveTo(1, 1)
+    term.eraseLine()
+    term.bold.cyan("Simba - Skills Manager")
+    term("                              ")
+    term.dim("[?] Help\n\n")
+
+    // Header row
+    term("                     ")
+    for (let i = 0; i < state.agents.length; i++) {
+      const agent = state.agents[i]
+      const name = agent.name.slice(0, 8).padEnd(10)
+      if (i === state.cursorCol && state.cursorRow === -1) {
+        term.bgWhite.black(name)
+      } else {
+        term.bold(name)
+      }
+    }
+    term("\n")
+    term("─".repeat(21 + state.agents.length * 10) + "\n")
+
+    // Skill rows
+    for (let row = 0; row < state.skills.length; row++) {
+      const skillName = state.skills[row]
+      const skill = state.registry.skills[skillName]
+      const displayName = skillName.slice(0, 18).padEnd(20)
+
+      if (row === state.cursorRow) {
+        term.bgWhite.black(displayName)
+      } else {
+        term(displayName)
+      }
+      term(" ")
+
+      for (let col = 0; col < state.agents.length; col++) {
+        const agent = state.agents[col]
+        const isAssigned = !!skill.assignments[agent.id]
+        const symbol = isAssigned ? "●" : "○"
+
+        const isCursor = row === state.cursorRow && col === state.cursorCol
+
+        if (isCursor) {
+          term.bgYellow.black(` ${symbol} `.padEnd(10))
+        } else if (isAssigned) {
+          term.green(` ${symbol} `.padEnd(10))
+        } else {
+          term.dim(` ${symbol} `.padEnd(10))
+        }
+      }
+      term("\n")
+    }
+
+    term("\n")
+    term("─".repeat(21 + state.agents.length * 10) + "\n")
+    term.dim("[Space] Toggle  [a] Assign all  [n] None  [q] Quit\n")
+  }
+
+  const toggle = async () => {
+    const skillName = state.skills[state.cursorRow]
+    const agent = state.agents[state.cursorCol]
+    const skill = state.registry.skills[skillName]
+
+    if (skill.assignments[agent.id]) {
+      await skillsStore.unassignSkill(skillName, expandPath(agent.globalPath))
+      delete skill.assignments[agent.id]
+    } else {
+      await skillsStore.assignSkill(skillName, expandPath(agent.globalPath), { type: "directory" })
+      skill.assignments[agent.id] = { type: "directory" }
+    }
+
+    await registryStore.save(state.registry)
+  }
+
+  const assignAll = async () => {
+    const skillName = state.skills[state.cursorRow]
+    const skill = state.registry.skills[skillName]
+
+    for (const agent of state.agents) {
+      if (!skill.assignments[agent.id]) {
+        await skillsStore.assignSkill(skillName, expandPath(agent.globalPath), { type: "directory" })
+        skill.assignments[agent.id] = { type: "directory" }
+      }
+    }
+
+    await registryStore.save(state.registry)
+  }
+
+  const unassignAll = async () => {
+    const skillName = state.skills[state.cursorRow]
+    const skill = state.registry.skills[skillName]
+
+    for (const agent of state.agents) {
+      if (skill.assignments[agent.id]) {
+        await skillsStore.unassignSkill(skillName, expandPath(agent.globalPath))
+        delete skill.assignments[agent.id]
+      }
+    }
+
+    await registryStore.save(state.registry)
+  }
+
+  render()
+
+  term.grabInput(true)
+
+  term.on("key", async (key: string) => {
+    switch (key) {
+      case "UP":
+        state.cursorRow = Math.max(0, state.cursorRow - 1)
+        break
+      case "DOWN":
+        state.cursorRow = Math.min(state.skills.length - 1, state.cursorRow + 1)
+        break
+      case "LEFT":
+        state.cursorCol = Math.max(0, state.cursorCol - 1)
+        break
+      case "RIGHT":
+        state.cursorCol = Math.min(state.agents.length - 1, state.cursorCol + 1)
+        break
+      case " ":
+        await toggle()
+        break
+      case "a":
+        await assignAll()
+        break
+      case "n":
+        await unassignAll()
+        break
+      case "q":
+      case "CTRL_C":
+        term.clear()
+        term.showCursor()
+        term.grabInput(false)
+        process.exit(0)
+    }
+
+    render()
+  })
+}

package/src/utils/diff.ts

@@ -0,0 +1,53 @@
+import { parseDiffFromFile, type FileDiffMetadata } from "@pierre/diffs"
+import terminalKit from "terminal-kit"
+
+const term = terminalKit.terminal
+
+export interface DiffResult {
+  identical: boolean
+  diff?: FileDiffMetadata
+}
+
+export function compareFiles(oldContent: string, newContent: string, filename: string = "file"): DiffResult {
+  if (oldContent === newContent) {
+    return { identical: true }
+  }
+
+  const diff = parseDiffFromFile(
+    { name: filename, contents: oldContent },
+    { name: filename, contents: newContent }
+  )
+
+  return { identical: false, diff }
+}
+
+export function renderDiff(diff: FileDiffMetadata, leftLabel: string, rightLabel: string): void {
+  term.bold(`\n  Comparing: `).defaultColor(`${leftLabel} vs ${rightLabel}\n\n`)
+
+  for (const hunk of diff.hunks) {
+    // Show hunk header
+    term.gray(`  @@ -${hunk.deletionStart},${hunk.deletionLines} +${hunk.additionStart},${hunk.additionLines} @@\n`)
+
+    for (const content of hunk.hunkContent) {
+      if (content.type === "context") {
+        for (const line of content.lines) {
+          term.gray(`    ${line.trimEnd()}\n`)
+        }
+      } else if (content.type === "change") {
+        for (const line of content.deletions) {
+          term.red(`  - ${line.trimEnd()}\n`)
+        }
+        for (const line of content.additions) {
+          term.green(`  + ${line.trimEnd()}\n`)
+        }
+      }
+    }
+  }
+
+  term("\n")
+}
+
+export function renderIdenticalMessage(skillName: string): void {
+  term.yellow(`\n  "${skillName}" has identical content in all agents.\n`)
+  term.gray("  Choosing the first agent as source.\n\n")
+}

package/src/utils/hash.ts

@@ -0,0 +1,47 @@
+import { readFile, readdir, stat } from "node:fs/promises"
+import { join, relative } from "node:path"
+import { createHash } from "node:crypto"
+import type { SkillFile } from "../core/types"
+
+export async function hashFile(filePath: string): Promise<string> {
+  const content = await readFile(filePath)
+  return createHash("sha256").update(content).digest("hex")
+}
+
+export async function hashTree(
+  dirPath: string
+): Promise<{ treeHash: string; files: SkillFile[] }> {
+  const files: SkillFile[] = []
+  await collectFiles(dirPath, dirPath, files)
+
+  // Sort for deterministic ordering
+  files.sort((a, b) => a.path.localeCompare(b.path))
+
+  // Git-style: hash of "path:hash\n" entries
+  const treeContent = files.map((f) => `${f.path}:${f.hash}`).join("\n")
+  const treeHash = createHash("sha256").update(treeContent).digest("hex")
+
+  return { treeHash, files }
+}
+
+async function collectFiles(
+  basePath: string,
+  currentPath: string,
+  files: SkillFile[]
+): Promise<void> {
+  const entries = await readdir(currentPath, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = join(currentPath, entry.name)
+
+    if (entry.isDirectory()) {
+      await collectFiles(basePath, fullPath, files)
+    } else if (entry.isFile()) {
+      const hash = await hashFile(fullPath)
+      files.push({
+        path: relative(basePath, fullPath),
+        hash,
+      })
+    }
+  }
+}

package/src/utils/paths.ts

@@ -0,0 +1,30 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export function expandPath(path: string): string {
+  if (path.startsWith("~/")) {
+    return join(homedir(), path.slice(2))
+  }
+  return path
+}
+
+export function getConfigDir(): string {
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), ".config")
+  return join(xdgConfig, "simba")
+}
+
+export function getConfigPath(): string {
+  return join(getConfigDir(), "config.toml")
+}
+
+export function getSnapshotsDir(): string {
+  return join(getConfigDir(), "snapshots")
+}
+
+export function getSkillsDir(): string {
+  return join(getConfigDir(), "skills")
+}
+
+export function getRegistryPath(): string {
+  return join(getConfigDir(), "registry.json")
+}

package/src/utils/prompts.ts

@@ -0,0 +1,85 @@
+import * as p from "@clack/prompts"
+import type { Agent } from "../core/types"
+
+export function isCancel(value: unknown): value is symbol {
+  return p.isCancel(value)
+}
+
+export function cancel(message = "Operation cancelled."): never {
+  p.cancel(message)
+  process.exit(0)
+}
+
+export async function selectAgent(
+  agents: Record<string, Agent>,
+  message: string,
+  filter?: (agent: Agent) => boolean
+): Promise<string> {
+  const options = Object.entries(agents)
+    .filter(([_, a]) => a.detected && (!filter || filter(a)))
+    .map(([id, a]) => ({ value: id, label: a.name }))
+
+  if (options.length === 0) {
+    p.log.error("No agents available.")
+    process.exit(1)
+  }
+
+  const result = await p.select({ message, options })
+  if (isCancel(result)) cancel()
+  return result as string
+}
+
+export async function selectMultipleAgents(
+  agents: Record<string, Agent>,
+  message: string,
+  exclude?: string[]
+): Promise<string[]> {
+  const options = Object.entries(agents)
+    .filter(([id, a]) => a.detected && !exclude?.includes(id))
+    .map(([id, a]) => ({ value: id, label: a.name }))
+
+  if (options.length === 0) {
+    p.log.error("No agents available.")
+    process.exit(1)
+  }
+
+  const result = await p.multiselect({ message, options, required: true })
+  if (isCancel(result)) cancel()
+  return result as string[]
+}
+
+export async function selectFromList<T extends string>(
+  message: string,
+  options: { value: T; label: string; hint?: string }[]
+): Promise<T> {
+  if (options.length === 0) {
+    p.log.error("No options available.")
+    process.exit(1)
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result = await p.select({ message, options: options as any })
+  if (isCancel(result)) cancel()
+  return result as T
+}
+
+export async function inputText(
+  message: string,
+  options?: { placeholder?: string; defaultValue?: string }
+): Promise<string> {
+  const result = await p.text({
+    message,
+    placeholder: options?.placeholder,
+    defaultValue: options?.defaultValue,
+  })
+  if (isCancel(result)) cancel()
+  return result as string
+}
+
+export async function confirm(message: string, initial = false): Promise<boolean> {
+  const result = await p.confirm({ message, initialValue: initial })
+  if (isCancel(result)) cancel()
+  return result as boolean
+}
+
+export { p }

package/src/utils/symlinks.ts

@@ -0,0 +1,34 @@
+import { symlink, unlink, readlink, lstat, mkdir } from "node:fs/promises"
+import { dirname } from "node:path"
+
+export async function createSymlink(source: string, target: string): Promise<void> {
+  await mkdir(dirname(target), { recursive: true })
+  await symlink(source, target)
+}
+
+export async function isSymlink(path: string): Promise<boolean> {
+  try {
+    const stat = await lstat(path)
+    return stat.isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+export async function removeSymlink(path: string): Promise<void> {
+  try {
+    await unlink(path)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw err
+    }
+  }
+}
+
+export async function getSymlinkTarget(path: string): Promise<string | null> {
+  try {
+    return await readlink(path)
+  } catch {
+    return null
+  }
+}