superacli 1.1.7 → 1.1.9

package/cli/plugins-manager.js

@@ -357,8 +357,8 @@ function runStoredHook(pluginName, kind, storedHook) {
   }
 }
 
-function checkBinary(binary) {
-  const r = spawnSync(binary, ["--version"], { encoding: "utf-8", timeout: 5000 })
+function checkBinary(binary, args) {
+  const r = spawnSync(binary, args || ["--version"], { encoding: "utf-8", timeout: 5000 })
   if (r.error) {
     return {
       binary,
@@ -394,7 +394,7 @@ function doctorPlugin(name) {
   const checks = []
   for (const check of (plugin.checks || [])) {
     if (check && check.type === "binary" && check.name) {
-      checks.push({ type: "binary", ...checkBinary(check.name) })
+      checks.push({ type: "binary", ...checkBinary(check.name, check.args) })
     }
   }
 

package/cli/skills-catalog.js

@@ -7,17 +7,27 @@ function dcliDir() {
   return process.env.SUPERCLI_HOME || path.join(os.homedir(), ".dcli")
 }
 
+function supercliDir() {
+  return process.env.SUPERCLI_HOME || path.join(os.homedir(), ".supercli")
+}
+
 function providersFile() {
-  return path.join(dcliDir(), "skills-providers.json")
+  const supercliPath = path.join(supercliDir(), "skills-providers.json")
+  const dcliPath = path.join(dcliDir(), "skills-providers.json")
+  return fs.existsSync(supercliPath) ? supercliPath : dcliPath
 }
 
 function indexFile() {
-  return path.join(dcliDir(), "skills-index.json")
+  const supercliPath = path.join(supercliDir(), "skills-index.json")
+  const dcliPath = path.join(dcliDir(), "skills-index.json")
+  return fs.existsSync(supercliPath) ? supercliPath : dcliPath
 }
 
 function ensureDir() {
   const dir = dcliDir()
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+  const supercliDirPath = supercliDir()
+  if (!fs.existsSync(supercliDirPath)) fs.mkdirSync(supercliDirPath, { recursive: true })
 }
 
 function defaultProviders() {
@@ -135,7 +145,7 @@ function syncCatalog() {
       for (const entry of entries) {
         if (!entry || !entry.id || !entry.source_url) continue
         skills.push({
-          id: `${provider.name}:${entry.id}`,
+          id: provider.name + ":" + entry.id,
           provider: provider.name,
           name: entry.name || entry.id,
           description: entry.description || "",
@@ -147,6 +157,34 @@ function syncCatalog() {
       continue
     }
 
+    if (provider.type === "plugin_fs") {
+      const pluginDir = provider.plugin_dir
+      if (!pluginDir || !fs.existsSync(pluginDir)) continue
+      const skillsDir = path.join(pluginDir, "skills")
+      if (fs.existsSync(skillsDir)) {
+        const files = walkDir(skillsDir)
+        for (const filePath of files) {
+          const markdown = fs.readFileSync(filePath, "utf-8")
+          const { frontmatter, body } = parseFrontmatter(markdown)
+          const baseId = baseSkillId(filePath, frontmatter, skillsDir)
+          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()
+          })
+        }
+      }
+      continue
+    }
+
     const roots = Array.isArray(provider.roots) ? provider.roots : []
     for (const root of roots) {
       const files = walkDir(root)
@@ -158,9 +196,8 @@ function syncCatalog() {
         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}`,
+          id: provider.name + ":" + baseId,
           provider: provider.name,
           name,
           description,
@@ -206,7 +243,6 @@ function getCatalogSkill(providerId) {
   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")
@@ -215,15 +251,136 @@ function getCatalogSkill(providerId) {
     if (res.error || res.status !== 0) return null
     markdown = (res.stdout || "").trim()
   }
-
   if (!markdown) return null
+  return { ...hit, markdown }
+}
 
+
+
+/**
+ * Get catalog information with provider breakdown
+ */
+function getCatalogInfo() {
+  const idx = readIndex()
+  const providers = listProviders()
+  
+  const providerStats = providers.map(provider => {
+    if (!provider.enabled) {
+      return { name: provider.name, type: provider.type, enabled: false, status: 'disabled' }
+    }
+    
+    let skillsCount = 0
+    let status = 'active'
+    let details = {}
+    
+    if (provider.type === 'plugin_fs') {
+      const pluginDir = provider.plugin_dir
+      if (!pluginDir || !fs.existsSync(pluginDir)) {
+        status = 'missing'
+        details.error = 'Plugin directory not found'
+      } else {
+        const skillsDir = path.join(pluginDir, 'skills')
+        if (fs.existsSync(skillsDir)) {
+          const files = walkDir(skillsDir)
+          skillsCount = files.length
+          details.plugin_dir = pluginDir
+          details.skills_dir = skillsDir
+        } else {
+          status = 'no_skills_dir'
+          details.skills_dir = skillsDir
+        }
+      }
+    } else if (provider.type === 'local_fs' || provider.type === 'repo_fs') {
+      const roots = Array.isArray(provider.roots) ? provider.roots : []
+      for (const root of roots) {
+        if (fs.existsSync(root)) {
+          const files = walkDir(root)
+          skillsCount += files.length
+        }
+      }
+      details.roots = roots
+    } else if (provider.type === 'remote_static') {
+      skillsCount = Array.isArray(provider.entries) ? provider.entries.length : 0
+      details.entries_count = skillsCount
+      details.source_repo = provider.source_repo
+    }
+    
+    return {
+      name: provider.name,
+      type: provider.type,
+      enabled: provider.enabled,
+      status,
+      skills_count: skillsCount,
+      ...details
+    }
+  })
+  
   return {
-    ...hit,
-    markdown
+    index: {
+      version: idx.version,
+      updated_at: idx.updated_at,
+      total_skills: idx.skills.length
+    },
+    providers: providerStats,
+    recent_skills: idx.skills.slice(-5).map(s => ({
+      id: s.id,
+      name: s.name,
+      provider: s.provider,
+      added_at: s.updated_at
+    }))
   }
 }
 
+/**
+ * Describe all provider types with examples
+ */
+function describeProviderTypes() {
+  return {
+    provider_types: [
+      {
+        name: 'local_fs',
+        description: 'Scans local directories for SKILL.md files',
+        example: {
+          name: 'my-skills',
+          type: 'local_fs',
+          roots: ['~/.config/opencode/skills'],
+          enabled: true
+        }
+      },
+      {
+        name: 'repo_fs',
+        description: 'Scans repository directories for SKILL.md files',
+        example: {
+          name: 'repo',
+          type: 'repo_fs',
+          roots: ['.agents/skills', 'docs/skills'],
+          enabled: true
+        }
+      },
+      {
+        name: 'remote_static',
+        description: 'Pre-indexed skills from remote repositories (GitHub)',
+        example: {
+          name: 'visual-explainer',
+          type: 'remote_static',
+          source_repo: 'https://github.com/user/repo',
+          entries: [{ id: 'skill-1', source_url: 'https://raw.githubusercontent.com/...' }]
+        }
+      },
+      {
+        name: 'plugin_fs',
+        description: 'Auto-discovers SKILL.md files from installed plugin skills/ directory',
+        example: {
+          name: 'superbackend',
+          type: 'plugin_fs',
+          plugin_dir: '/path/to/plugins/superbackend'
+        }
+      }
+    ]
+  }
+}
+
+
 module.exports = {
   listProviders,
   addProvider,
@@ -233,5 +390,7 @@ module.exports = {
   syncCatalog,
   listCatalogSkills,
   searchCatalog,
-  getCatalogSkill
+  getCatalogSkill,
+  getCatalogInfo,
+  describeProviderTypes
 }

package/cli/skills.js

@@ -13,7 +13,9 @@ const {
   syncCatalog,
   listCatalogSkills,
   searchCatalog,
-  getCatalogSkill
+  getCatalogSkill,
+  getCatalogInfo,
+  describeProviderTypes
 } = require("./skills-catalog")
 
 function normalizeSkillId(input) {
@@ -179,7 +181,7 @@ function buildTeachSkillMarkdown(options = {}) {
     ]
   }
 
-  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nThis skill teaches LLMs how to discover and use SuperCLI capabilities and skill documents:\n\n1. List available capability docs and catalog skills:\n\n\`\`\`bash\nsupercli skills list --json\n\`\`\`\n\n2. Fetch documentation for a specific capability:\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 capability 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 skill documents 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 skill documents\nsupercli skills sync\n\n# Search skill documents 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\`\`\``
+  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nThis skill teaches LLMs how to discover and use SuperCLI capabilities and skill documents:\n\n1. List available capability docs and catalog skills:\n\n\`\`\`bash\nsupercli skills list --json\n\`\`\`\n\n2. Fetch documentation for a specific capability:\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 capability 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 skill documents 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 skill documents\nsupercli skills sync\n\n# Search skill documents 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\n7. **Using Positional Arguments** (for commands that require positional values):\n\n\`\`\`bash\n# Some commands require positional arguments instead of named flags\nsupercli <namespace> <resource> <action> <positional1> <positional2> --json\n\n# Example: Delete by ID (positional argument)\nsupercli superbackend waiting-list delete --id <objectId> --quiet\n\n# Example: Passthrough to plugin CLI\nsupercli superbackend _ _ <resource> <command> <args...> --quiet\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\nsupercli superbackend waiting-list delete --id <id> --quiet\nsupercli superbackend _ _ users list --value 10 --quiet\n\`\`\``
 }
 
 function buildPluginsUsageSkillMarkdown(options = {}) {
@@ -339,7 +341,48 @@ function handleSkillsCommand(options) {
       return true
     }
 
-    outputError({ code: 85, type: "invalid_argument", message: "Unknown providers subcommand. Use: list, add, remove, show", recoverable: false })
+    if (action === "describe") {
+      const types = describeProviderTypes()
+      if (humanMode && !flags.json) {
+        console.log("\n  ⚡ Skill Provider Types\n")
+        for (const t of types.provider_types) {
+          console.log("  " + t.name + ":")
+          console.log("    " + t.description)
+          console.log("    Example:")
+          console.log("      " + JSON.stringify(t.example, null, 6))
+          console.log("")
+        }
+      } else {
+        output(types)
+      }
+      return true
+    }
+
+    outputError({ code: 85, type: "invalid_argument", message: "Unknown providers subcommand. Use: list, add, remove, show, describe", recoverable: false })
+    return true
+  }
+
+  if (subcommand === "catalog") {
+    const action = positional[2]
+    if (action === "info") {
+      const info = getCatalogInfo()
+      if (humanMode && !flags.json) {
+        console.log("\n  ⚡ Skills Catalog Info\n")
+        console.log("  Index:")
+        console.log("    Version:", info.index.version)
+        console.log("    Updated:", info.index.updated_at)
+        console.log("    Total Skills:", info.index.total_skills)
+        console.log("\n  Providers:")
+        for (const p of info.providers) {
+          console.log("    - " + p.name + " (" + p.type + "): " + p.skills_count + " skills [" + p.status + "]")
+        }
+        console.log("")
+      } else {
+        output({ catalog: info })
+      }
+      return true
+    }
+    outputError({ code: 85, type: "invalid_argument", message: "Usage: supercli skills catalog info [--json]", recoverable: false })
     return true
   }