superacli 1.1.8 → 1.1.9

package/cli/adapters/process.js

@@ -171,16 +171,25 @@ async function execute(cmd, flags, context = {}) {
   }
 
   if (passthroughMode) {
+    // Passthrough mode: use __rawArgs from flags (collected from remaining positional args)
     const passthroughArgs = Array.isArray(flags.__rawArgs) ? flags.__rawArgs : []
     args.push(...passthroughArgs)
   } else {
+    // Normal mode: collect positional values from flags OR from __positionalArgs
     const positionalValues = []
+    
+    // First, try to get positional values from flags (defined args)
     for (const name of positionalNames) {
       if (remainingFlags[name] !== undefined) {
         positionalValues.push(String(remainingFlags[name]))
         delete remainingFlags[name]
       }
     }
+    
+    // Also support __positionalArgs array for commands that need raw positional values
+    if (Array.isArray(flags.__positionalArgs)) {
+      positionalValues.push(...flags.__positionalArgs)
+    }
 
     const flagArgs = []
     if (includeJsonFlag) flagArgs.push(includeJsonFlag)

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
   }
 

package/cli/supercli.js

@@ -226,7 +226,7 @@ function renderTopLevelHelp(config) {
       "  MCP: supercli mcp list | supercli mcp add <name> --url <url> | supercli mcp tools --mcp-server <name> | supercli mcp call --mcp-server <name> --tool <tool> | supercli mcp bind --mcp-server <name> --tool <tool> --as <ns.res.act> | supercli mcp doctor --mcp-server <name> | supercli mcp remove <name>",
     );
     console.log(
-      "  Skill Docs: supercli skills list | supercli skills get <id> | supercli skills search --query <q> | supercli skills sync",
+      "  Skill Docs: supercli skills list | supercli skills get <id> | supercli skills catalog info | supercli skills providers describe | supercli skills search --query <q> | supercli skills sync",
     );
     if (config.features?.ask || process.env.OPENAI_BASE_URL) {
       console.log('  AI: supercli ask "<your natural language query>"');
@@ -859,6 +859,26 @@ async function main() {
       return;
     }
 
+    // Handle passthrough positional arguments
+    const passthroughArgs = [];
+    if (cmd.adapterConfig && cmd.adapterConfig.passthrough === true) {
+      // For passthrough commands, collect remaining positional args after namespace.resource.action
+      const cmdPositionalIndex = positional.findIndex((p, i) => 
+        i >= 0 && 
+        positional[i] === namespace &&
+        positional[i + 1] === resource &&
+        positional[i + 2] === action
+      );
+      if (cmdPositionalIndex >= 0) {
+        // Collect all args after namespace resource action
+        for (let i = cmdPositionalIndex + 3; i < positional.length; i++) {
+          passthroughArgs.push(positional[i]);
+        }
+      }
+      // Pass to adapter via __rawArgs
+      uFlags.__rawArgs = passthroughArgs;
+    }
+
     const start = Date.now();
     const result = await execute(cmd, uFlags, {
       server: SERVER || "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superacli",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "Config-driven, AI-friendly dynamic CLI",
   "license": "MIT",
   "main": "server/app.js",

package/plugins/openhands/plugin.json

@@ -43,10 +43,10 @@
       "adapter": "process",
       "adapterConfig": {
         "command": "openhands",
-        "baseArgs": ["--headless", "-t"],
+        "baseArgs": ["--headless", "--always-approve", "--override-with-envs", "-t"],
         "positionalArgs": ["task"],
         "parseJson": false,
-        "timeout_ms": 15000,
+        "timeout_ms": 180000,
         "missingDependencyHelp": "Please install OpenHands CLI to use this command."
       },
       "args": [
@@ -64,10 +64,10 @@
       "adapter": "process",
       "adapterConfig": {
         "command": "openhands",
-        "baseArgs": ["--headless", "-f"],
+        "baseArgs": ["--headless", "--always-approve", "--override-with-envs", "-f"],
         "positionalArgs": ["file"],
         "parseJson": false,
-        "timeout_ms": 15000,
+        "timeout_ms": 180000,
         "missingDependencyHelp": "Please install OpenHands CLI to use this command."
       },
       "args": [
@@ -85,11 +85,11 @@
       "adapter": "process",
       "adapterConfig": {
         "command": "openhands",
-        "baseArgs": ["--headless", "--json", "-t"],
+        "baseArgs": ["--headless", "--always-approve", "--override-with-envs", "--json", "-t"],
         "positionalArgs": ["task"],
         "stream": "jsonl",
         "parseJson": false,
-        "timeout_ms": 15000,
+        "timeout_ms": 180000,
         "missingDependencyHelp": "Please install OpenHands CLI to use this command."
       },
       "args": [

package/plugins/openhands/skills/quickstart/SKILL.md

@@ -8,6 +8,16 @@ Use this plugin to run OpenHands in headless automation mode.
 - Verify CLI: `openhands --version`
 - Install plugin: `supercli plugins install openhands`
 
+## Environment Setup
+
+Set these environment variables before running headless tasks:
+
+```bash
+export LLM_API_KEY="your-api-key"
+export LLM_MODEL="openai/gpt-4o-mini"  # or another model
+export LLM_BASE_URL="https://openrouter.ai/api/v1"  # optional
+```
+
 ## Common Commands
 
 - Version: `supercli openhands self version`
@@ -15,6 +25,19 @@ Use this plugin to run OpenHands in headless automation mode.
 - Headless task from file: `supercli openhands task file --file ./task.txt`
 - JSONL stream mode: `supercli openhands task json --task "Add tests"`
 
+## Smoke Test Example
+
+```bash
+# Set environment variables
+export LLM_API_KEY="your-openrouter-api-key"
+export LLM_MODEL="openai/gpt-4o-mini"
+export LLM_BASE_URL="https://openrouter.ai/api/v1"
+export PATH="/path/to/venv/bin:$PATH"
+
+# Run a simple task
+supercli openhands task run --task "Create a file called test.txt with 'hello world'"
+```
+
 ## Passthrough
 
 For any unsupported subcommand, use passthrough: