superacli 1.0.1 → 1.1.2

package/cli/skills-catalog.js

@@ -0,0 +1,237 @@
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+const { spawnSync } = require("child_process")
+
+function dcliDir() {
+  return process.env.SUPERCLI_HOME || path.join(os.homedir(), ".dcli")
+}
+
+function providersFile() {
+  return path.join(dcliDir(), "skills-providers.json")
+}
+
+function indexFile() {
+  return path.join(dcliDir(), "skills-index.json")
+}
+
+function ensureDir() {
+  const dir = dcliDir()
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+}
+
+function defaultProviders() {
+  const home = os.homedir()
+  const cwd = process.cwd()
+  return [
+    { name: "opencode", type: "local_fs", roots: [path.join(home, ".config", "opencode", "skills")], enabled: true },
+    { name: "codex", type: "local_fs", roots: [path.join(home, ".config", "codex", "skills")], enabled: true },
+    { name: "windsurf", type: "local_fs", roots: [path.join(home, ".config", "windsurf", "skills")], enabled: true },
+    { name: "cursor", type: "local_fs", roots: [path.join(home, ".config", "cursor", "skills")], enabled: true },
+    { name: "repo", type: "repo_fs", roots: [path.join(cwd, ".agents", "skills"), path.join(cwd, "docs", "skills")], enabled: true }
+  ]
+}
+
+function readJson(file, fallback) {
+  try {
+    if (!fs.existsSync(file)) return fallback
+    return JSON.parse(fs.readFileSync(file, "utf-8"))
+  } catch {
+    return fallback
+  }
+}
+
+function writeJson(file, value) {
+  ensureDir()
+  fs.writeFileSync(file, JSON.stringify(value, null, 2))
+  return value
+}
+
+function listProviders() {
+  const providers = readJson(providersFile(), defaultProviders())
+  return Array.isArray(providers) ? providers : defaultProviders()
+}
+
+function setProviders(providers) {
+  return writeJson(providersFile(), providers)
+}
+
+function addProvider(entry) {
+  const providers = listProviders()
+  const idx = providers.findIndex(p => p.name === entry.name)
+  if (idx >= 0) providers[idx] = entry
+  else providers.push(entry)
+  setProviders(providers)
+  return entry
+}
+
+function removeProvider(name) {
+  const providers = listProviders()
+  const next = providers.filter(p => p.name !== name)
+  const removed = next.length !== providers.length
+  setProviders(next)
+  return removed
+}
+
+function getProvider(name) {
+  return listProviders().find(p => p.name === name) || null
+}
+
+function readIndex() {
+  const empty = { version: 1, updated_at: null, skills: [] }
+  const idx = readJson(indexFile(), empty)
+  if (!idx || typeof idx !== "object") return empty
+  if (!Array.isArray(idx.skills)) idx.skills = []
+  return idx
+}
+
+function walkDir(dir) {
+  const files = []
+  if (!fs.existsSync(dir)) return files
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...walkDir(full))
+      continue
+    }
+    if (entry.isFile() && entry.name === "SKILL.md") files.push(full)
+  }
+  return files
+}
+
+function parseFrontmatter(markdown) {
+  if (!markdown.startsWith("---\n")) return { frontmatter: {}, body: markdown }
+  const end = markdown.indexOf("\n---\n", 4)
+  if (end < 0) return { frontmatter: {}, body: markdown }
+  const raw = markdown.slice(4, end)
+  const body = markdown.slice(end + 5)
+  const frontmatter = {}
+  for (const line of raw.split("\n")) {
+    const idx = line.indexOf(":")
+    if (idx < 0) continue
+    const key = line.slice(0, idx).trim()
+    const value = line.slice(idx + 1).trim().replace(/^"|"$/g, "")
+    if (key) frontmatter[key] = value
+  }
+  return { frontmatter, body }
+}
+
+function baseSkillId(filePath, frontmatter, root) {
+  if (frontmatter.skill_name) return frontmatter.skill_name
+  const rel = path.relative(root, filePath)
+  return rel.replace(/\\/g, "/").replace(/\/SKILL\.md$/, "").replace(/\//g, ".")
+}
+
+function syncCatalog() {
+  const providers = listProviders()
+  const skills = []
+
+  for (const provider of providers) {
+    if (!provider.enabled) continue
+
+    if (provider.type === "remote_static") {
+      const entries = Array.isArray(provider.entries) ? provider.entries : []
+      for (const entry of entries) {
+        if (!entry || !entry.id || !entry.source_url) continue
+        skills.push({
+          id: `${provider.name}:${entry.id}`,
+          provider: provider.name,
+          name: entry.name || entry.id,
+          description: entry.description || "",
+          source_url: entry.source_url,
+          tags: Array.isArray(entry.tags) ? entry.tags : [],
+          updated_at: new Date().toISOString()
+        })
+      }
+      continue
+    }
+
+    const roots = Array.isArray(provider.roots) ? provider.roots : []
+    for (const root of roots) {
+      const files = walkDir(root)
+      for (const filePath of files) {
+        const markdown = fs.readFileSync(filePath, "utf-8")
+        const { frontmatter, body } = parseFrontmatter(markdown)
+        const baseId = baseSkillId(filePath, frontmatter, root)
+        const heading = body.split("\n").find(l => l.startsWith("# "))
+        const name = frontmatter.skill_name || (heading ? heading.slice(2).trim() : baseId)
+        const description = frontmatter.description || ""
+        const tags = typeof frontmatter.tags === "string" ? frontmatter.tags.split(",").map(t => t.trim()).filter(Boolean) : []
+
+        skills.push({
+          id: `${provider.name}:${baseId}`,
+          provider: provider.name,
+          name,
+          description,
+          source_path: filePath,
+          tags,
+          updated_at: new Date().toISOString()
+        })
+      }
+    }
+  }
+
+  skills.sort((a, b) => a.id.localeCompare(b.id))
+  const next = {
+    version: 1,
+    updated_at: new Date().toISOString(),
+    providers: providers.map(p => p.name),
+    skills
+  }
+  writeJson(indexFile(), next)
+  return next
+}
+
+function listCatalogSkills(options = {}) {
+  const idx = readIndex()
+  let items = idx.skills || []
+  if (options.provider) items = items.filter(s => s.provider === options.provider)
+  return items.map(s => ({ id: s.id, name: s.name, description: s.description, provider: s.provider }))
+}
+
+function searchCatalog(query, options = {}) {
+  const q = String(query || "").trim().toLowerCase()
+  if (!q) return []
+  const items = listCatalogSkills(options)
+  return items.filter(s =>
+    s.id.toLowerCase().includes(q) ||
+    s.name.toLowerCase().includes(q) ||
+    String(s.description || "").toLowerCase().includes(q)
+  )
+}
+
+function getCatalogSkill(providerId) {
+  const idx = readIndex()
+  const hit = (idx.skills || []).find(s => s.id === providerId)
+  if (!hit) return null
+  let markdown = null
+
+  if (hit.source_path) {
+    if (!fs.existsSync(hit.source_path)) return null
+    markdown = fs.readFileSync(hit.source_path, "utf-8")
+  } else if (hit.source_url) {
+    const res = spawnSync("curl", ["-fsSL", hit.source_url], { encoding: "utf-8", timeout: 15000 })
+    if (res.error || res.status !== 0) return null
+    markdown = (res.stdout || "").trim()
+  }
+
+  if (!markdown) return null
+
+  return {
+    ...hit,
+    markdown
+  }
+}
+
+module.exports = {
+  listProviders,
+  addProvider,
+  removeProvider,
+  getProvider,
+  readIndex,
+  syncCatalog,
+  listCatalogSkills,
+  searchCatalog,
+  getCatalogSkill
+}

package/cli/skills.js

@@ -1,5 +1,18 @@
 const { createPlan } = require("./planner")
 
+const PLUGINS_USAGE_SKILL_ID = "plugins.registry.usage"
+const {
+  listProviders,
+  addProvider,
+  removeProvider,
+  getProvider,
+  readIndex,
+  syncCatalog,
+  listCatalogSkills,
+  searchCatalog,
+  getCatalogSkill
+} = require("./skills-catalog")
+
 function normalizeSkillId(input) {
   if (!input || typeof input !== "string") return null
   const parts = input.trim().split(".")
@@ -163,14 +176,61 @@ function buildTeachSkillMarkdown(options = {}) {
     ]
   }
 
-  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nThis skill teaches LLMs how to discover and use SuperCLI skills:\n\n1. List available skills:\n\n\`\`\`bash\nsupercli skills list --json\n\`\`\`\n\n2. Fetch a specific skill:\n\n\`\`\`bash\nsupercli skills get <namespace.resource.action> --format skill.md\n\`\`\`\n\n3. Parse YAML frontmatter to understand command, arguments, output schema, and metadata.\n\n4. Execute the command with validated arguments:\n\n\`\`\`bash\nsupercli <namespace> <resource> <action> --arg value --json\n\`\`\`\n\n# Examples\n\n\`\`\`bash\nsupercli skills teach --format skill.md\nsupercli skills teach --format skill.md --show-dag\n\`\`\``
+  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nThis skill teaches LLMs how to discover and use SuperCLI skills:\n\n1. List available skills:\n\n\`\`\`bash\nsupercli skills list --json\n\`\`\`\n\n2. Fetch a specific skill:\n\n\`\`\`bash\nsupercli skills get <namespace.resource.action> --format skill.md\n\`\`\`\n\n3. Parse YAML frontmatter to understand command, arguments, output schema, and metadata.\n\n4. Execute the command with validated arguments:\n\n\`\`\`bash\nsupercli <namespace> <resource> <action> --arg value --json\n\`\`\`\n\n5. For plugin discovery and remote plugin installs, use:\n\n\`\`\`bash\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md\n\`\`\`\n\n6. To index skills from a local directory (e.g., a project with docs/skills):\n\n\`\`\`bash\n# List current providers\nsupercli skills providers list --json\n\n# Add a local provider for a project\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\n\n# Sync the catalog to index new skills\nsupercli skills sync\n\n# Search skills from the new provider\nsupercli skills search <query> --provider myproject\n\n# Remove a provider if needed\nsupercli skills providers remove --name myproject\n\`\`\`\n\n# Examples\n\n\`\`\`bash\nsupercli skills teach --format skill.md\nsupercli skills teach --format skill.md --show-dag\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\nsupercli skills sync\nsupercli skills search btc --provider myproject\n\`\`\``
+}
+
+function buildPluginsUsageSkillMarkdown(options = {}) {
+  const includeDag = !!options.showDag
+  const frontmatter = {
+    skill_name: "plugins_registry_usage",
+    description: "Explains plugin discovery from plugins/plugins.json and local/remote plugin installation flows.",
+    command: `skills get ${PLUGINS_USAGE_SKILL_ID}`,
+    arguments: [
+      {
+        name: "format",
+        type: "string",
+        required: false,
+        description: "Output format, default skill.md"
+      },
+      {
+        name: "show-dag",
+        type: "boolean",
+        required: false,
+        description: "Include internal DAG for agent reasoning"
+      }
+    ],
+    output_schema: {
+      instruction: "string",
+      examples: "array"
+    },
+    metadata: {
+      side_effects: false,
+      risk_level: "safe",
+      dag_supported: true
+    }
+  }
+
+  if (includeDag) {
+    frontmatter.dag = [
+      { id: 1, type: "load_plugin_registry" },
+      { id: 2, type: "resolve_install_method", depends_on: [1] },
+      { id: 3, type: "emit_plugin_usage_instructions", depends_on: [2] }
+    ]
+  }
+
+  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nUse this workflow for plugin discovery and installation:\n\n1. Explore registry metadata (name/description/tags):\n\n\`\`\`bash\nsupercli plugins explore --json\nsupercli plugins explore --name commiat --json\nsupercli plugins explore --tags git,ai --json\n\`\`\`\n\n2. Install by registry name:\n\n\`\`\`bash\nsupercli plugins install commiat --json\n\`\`\`\n\n3. Install directly from a remote git repository:\n\n\`\`\`bash\nsupercli plugins install --git https://github.com/org/repo.git --manifest-path plugins/supercli/plugin.json --ref main --json\n\`\`\`\n\n4. Validate installed plugin health and guidance:\n\n\`\`\`bash\nsupercli plugins doctor commiat --json\nsupercli plugins show commiat --json\n\`\`\`\n\n5. Use the namespace command exposed by the plugin.\n\n# Examples\n\n\`\`\`bash\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md --show-dag\n\`\`\``
 }
 
 function listSkillsMetadata(config) {
-  return (config.commands || []).map(cmd => ({
+  const commandSkills = (config.commands || []).map(cmd => ({
     name: `${cmd.namespace}.${cmd.resource}.${cmd.action}`,
     description: cmd.description || ""
   }))
+  commandSkills.push({
+    name: PLUGINS_USAGE_SKILL_ID,
+    description: "Discover and install plugins from the registry or remote git repos"
+  })
+  return commandSkills
 }
 
 function handleSkillsCommand(options) {
@@ -178,8 +238,102 @@ function handleSkillsCommand(options) {
   const subcommand = positional[1]
   const format = flags.format || "skill.md"
 
+  if (subcommand === "providers") {
+    const action = positional[2]
+    if (action === "list") {
+      const providers = listProviders()
+      if (humanMode && !flags.json) {
+        console.log("\n  ⚡ Skill Providers\n")
+        outputHumanTable(providers, [
+          { key: "name", label: "Name" },
+          { key: "type", label: "Type" },
+          { key: "enabled", label: "Enabled" }
+        ])
+        console.log("")
+      } else {
+        output({ providers })
+      }
+      return true
+    }
+
+    if (action === "add") {
+      const name = flags.name || positional[3]
+      const type = flags.type || "local_fs"
+      const rootsRaw = flags.roots || flags.root
+      if (!name || !rootsRaw) {
+        outputError({ code: 85, type: "invalid_argument", message: "Usage: supercli skills providers add --name <provider> --roots <path1,path2> [--type local_fs|repo_fs]", recoverable: false })
+        return true
+      }
+      const roots = String(rootsRaw).split(",").map(r => r.trim()).filter(Boolean)
+      const provider = addProvider({ name, type, roots, enabled: flags.enabled !== "false" })
+      output({ ok: true, provider })
+      return true
+    }
+
+    if (action === "remove") {
+      const name = flags.name || positional[3]
+      if (!name) {
+        outputError({ code: 85, type: "invalid_argument", message: "Usage: supercli skills providers remove --name <provider>", recoverable: false })
+        return true
+      }
+      output({ ok: true, removed: removeProvider(name) })
+      return true
+    }
+
+    if (action === "show") {
+      const name = flags.name || positional[3]
+      if (!name) {
+        outputError({ code: 85, type: "invalid_argument", message: "Usage: supercli skills providers show --name <provider>", recoverable: false })
+        return true
+      }
+      const provider = getProvider(name)
+      if (!provider) {
+        outputError({ code: 92, type: "resource_not_found", message: `Provider '${name}' not found`, suggestions: ["Run: supercli skills providers list"] })
+        return true
+      }
+      output({ provider })
+      return true
+    }
+
+    outputError({ code: 85, type: "invalid_argument", message: "Unknown providers subcommand. Use: list, add, remove, show", recoverable: false })
+    return true
+  }
+
+  if (subcommand === "sync") {
+    const index = syncCatalog()
+    output({ ok: true, updated_at: index.updated_at, providers: index.providers, skills: index.skills.length })
+    return true
+  }
+
+  if (subcommand === "search") {
+    const query = flags.query || positional.slice(2).join(" ")
+    if (!query) {
+      outputError({ code: 85, type: "invalid_argument", message: "Usage: supercli skills search --query <text> [--provider <provider>]", recoverable: false })
+      return true
+    }
+    const skills = searchCatalog(query, { provider: flags.provider })
+    output({ skills })
+    return true
+  }
+
   if (subcommand === "list") {
-    const skills = listSkillsMetadata(config)
+    const useCatalog = flags.catalog === true || flags.catalog === "true" || !!flags.provider
+    if (flags["no-catalog"] || flags.catalog === false || flags.catalog === "false" || !useCatalog) {
+      const skills = listSkillsMetadata(config)
+      if (humanMode && !flags.json) {
+        console.log("\n  ⚡ Skills (command-level only)\n")
+        outputHumanTable(skills, [
+          { key: "name", label: "Name" },
+          { key: "description", label: "Description" }
+        ])
+        console.log("")
+      } else {
+        output({ skills })
+      }
+      return true
+    }
+
+    const skills = listCatalogSkills({ provider: flags.provider })
     if (humanMode && !flags.json) {
       console.log("\n  ⚡ Skills\n")
       outputHumanTable(skills, [
@@ -188,7 +342,8 @@ function handleSkillsCommand(options) {
       ])
       console.log("")
     } else {
-      output({ skills })
+      const index = readIndex() || {}
+      output({ skills, index: { updated_at: index.updated_at || null } })
     }
     return true
   }
@@ -208,6 +363,17 @@ function handleSkillsCommand(options) {
       return true
     }
 
+    const skillId = positional[2] || ""
+    if (skillId.includes(":")) {
+      const skill = getCatalogSkill(skillId)
+      if (!skill) {
+        outputError({ code: 92, type: "resource_not_found", message: `Skill ${skillId} not found in local catalog`, suggestions: ["Run: supercli skills sync", "Run: supercli skills list --catalog --json"] })
+        return true
+      }
+      console.log(skill.markdown)
+      return true
+    }
+
     const dottedId = positional[2] || (positional[3] && positional[4] ? `${positional[2]}.${positional[3]}.${positional[4]}` : "")
     const parsed = normalizeSkillId(dottedId)
     if (!parsed) {
@@ -215,6 +381,11 @@ function handleSkillsCommand(options) {
       return true
     }
 
+    if (parsed.id === PLUGINS_USAGE_SKILL_ID) {
+      console.log(buildPluginsUsageSkillMarkdown({ showDag: !!flags["show-dag"] }))
+      return true
+    }
+
     const cmd = config.commands.find(c =>
       c.namespace === parsed.namespace && c.resource === parsed.resource && c.action === parsed.action
     )
@@ -227,14 +398,17 @@ function handleSkillsCommand(options) {
     return true
   }
 
-  outputError({ code: 85, type: "invalid_argument", message: "Unknown skills subcommand. Use: list, get, teach", recoverable: false })
+  outputError({ code: 85, type: "invalid_argument", message: "Unknown skills subcommand. Use: list, get, teach, sync, search, providers", recoverable: false })
   return true
 }
 
 module.exports = {
+  PLUGINS_USAGE_SKILL_ID,
   normalizeSkillId,
   buildCommandSkillMarkdown,
   buildTeachSkillMarkdown,
+  buildPluginsUsageSkillMarkdown,
   listSkillsMetadata,
-  handleSkillsCommand
+  handleSkillsCommand,
+  renderYamlObject // Export for testing coverage
 }