superacli 1.1.0 → 1.1.2

package/cli/plugins-manager.js

@@ -2,9 +2,9 @@ const fs = require("fs")
 const path = require("path")
 const os = require("os")
 const { spawnSync } = require("child_process")
-const { installAgencyAgentsSkillProvider } = require("./plugin-agency-agents")
 const { SUPPORTED_ADAPTERS } = require("./adapter-schema")
 const { getRegistryPlugin } = require("./plugins-registry")
+const { getPluginInstallGuidance } = require("./plugin-install-guidance")
 const {
   readPluginsLock,
   writePluginsLock,
@@ -15,70 +15,42 @@ const BUNDLED_PLUGINS = {
   beads: path.resolve(__dirname, "..", "plugins", "beads", "plugin.json"),
   gwc: path.resolve(__dirname, "..", "plugins", "gwc", "plugin.json"),
   docker: path.resolve(__dirname, "..", "plugins", "docker", "plugin.json"),
-  "agency-agents": path.resolve(__dirname, "..", "plugins", "agency-agents", "plugin.json")
+  "agency-agents": path.resolve(__dirname, "..", "plugins", "agency-agents", "plugin.json"),
+  "visual-explainer": path.resolve(__dirname, "..", "plugins", "visual-explainer", "plugin.json")
 }
 
-const PLUGIN_INSTALL_GUIDANCE = {
-  beads: {
-    plugin: "beads",
-    binary: "br",
-    check: "br --version",
-    install_steps: [
-      "curl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)\" | bash",
-      "br --version"
-    ],
-    note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
-  },
-  gwc: {
-    plugin: "gwc",
-    binary: "gws",
-    check: "gws --version",
-    install_steps: [
-      "npm install -g @googleworkspace/cli",
-      "gws --version"
-    ],
-    note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
-  },
-  commiat: {
-    plugin: "commiat",
-    binary: "commiat",
-    check: "commiat --version",
-    install_steps: [
-      "npm install -g commiat",
-      "commiat --version"
-    ],
-    note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
-  },
-  docker: {
-    plugin: "docker",
-    binary: "docker",
-    check: "docker --version",
-    install_steps: [
-      "docker --version"
-    ],
-    note: "Install Docker Engine/Desktop using your OS package manager, then verify with docker --version."
-  },
-  stripe: {
-    plugin: "stripe",
-    binary: "stripe",
-    check: "stripe --version",
-    install_steps: [
-      "brew install stripe/stripe-cli/stripe",
-      "stripe --version",
-      "stripe login"
-    ],
-    note: "Install Stripe CLI and authenticate with stripe login before running API commands."
-  },
-  "agency-agents": {
-    plugin: "agency-agents",
-    binary: "curl",
-    check: "curl --version",
-    install_steps: [
-      "supercli plugins install agency-agents",
-      "supercli skills list --catalog --provider agency-agents --json",
-      "supercli skills get agency-agents:engineering.engineering-frontend-developer"
-    ],
-    note: "Install indexes remote markdown skills from https://github.com/msitarzewski/agency-agents (best effort, upstream paths may change)."
+function validateNodeHook(hook, kind) {
+  if (!hook) return null
+  if (!hook.script || typeof hook.script !== "string") {
+    throw Object.assign(new Error(`Invalid plugin manifest: ${kind}.script must be a string`), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false
+    })
+  }
+
+  const runtime = hook.runtime || "node"
+  if (runtime !== "node") {
+    throw Object.assign(new Error(`Invalid plugin manifest: ${kind}.runtime must be 'node'`), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false
+    })
+  }
+
+  const timeoutMs = hook.timeout_ms === undefined ? 15000 : Number(hook.timeout_ms)
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 15000) {
+    throw Object.assign(new Error(`Invalid plugin manifest: ${kind}.timeout_ms must be a positive number <= 15000`), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false
+    })
+  }
+
+  return {
+    script: hook.script,
+    runtime,
+    timeout_ms: timeoutMs
   }
 }
 
@@ -129,6 +101,10 @@ function resolveRepoManifestPath(baseDir, manifestPath) {
   return candidate
 }
 
+function noCleanup() {
+  return undefined
+}
+
 function loadManifestFromGit(repo, options = {}) {
   if (!repo || typeof repo !== "string") {
     throw Object.assign(new Error("Missing git repo URL/path for plugin install"), {
@@ -139,53 +115,50 @@ function loadManifestFromGit(repo, options = {}) {
   }
 
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "dcli-plugin-"))
-  try {
-    const args = ["clone", "--depth", "1"]
-    if (options.ref) {
-      args.push("--branch", String(options.ref), "--single-branch")
-    }
-    args.push(repo, tmpDir)
-    const clone = spawnSync("git", args, { encoding: "utf-8", timeout: 15000 })
-
-    if (clone.error) {
-      const suggestion = clone.error.code === "ENOENT"
-        ? ["Install git and retry"]
-        : []
-      throw Object.assign(new Error(`Failed to clone plugin repo '${repo}': ${clone.error.message}`), {
-        code: 105,
-        type: "integration_error",
-        recoverable: true,
-        suggestions: suggestion
-      })
-    }
-    if (clone.status !== 0) {
-      throw Object.assign(new Error(`Failed to clone plugin repo '${repo}': ${(clone.stderr || "").trim() || `exit ${clone.status}`}`), {
-        code: 105,
-        type: "integration_error",
-        recoverable: true
-      })
-    }
+  const args = ["clone", "--depth", "1"]
+  if (options.ref) args.push("--branch", String(options.ref), "--single-branch")
+  args.push(repo, tmpDir)
+  const clone = spawnSync("git", args, { encoding: "utf-8", timeout: 15000 })
 
-    const manifestPath = resolveRepoManifestPath(tmpDir, options.manifestPath)
-    if (!fs.existsSync(manifestPath)) {
-      throw Object.assign(new Error(`Plugin manifest not found in repo: ${options.manifestPath || "plugin.json"}`), {
-        code: 92,
-        type: "resource_not_found",
-        recoverable: false
-      })
-    }
+  if (clone.error) {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+    const suggestion = clone.error.code === "ENOENT" ? ["Install git and retry"] : []
+    throw Object.assign(new Error(`Failed to clone plugin repo '${repo}': ${clone.error.message}`), {
+      code: 105,
+      type: "integration_error",
+      recoverable: true,
+      suggestions: suggestion
+    })
+  }
+  if (clone.status !== 0) {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+    throw Object.assign(new Error(`Failed to clone plugin repo '${repo}': ${(clone.stderr || "").trim() || `exit ${clone.status}`}`), {
+      code: 105,
+      type: "integration_error",
+      recoverable: true
+    })
+  }
 
-    return {
-      manifest: parseManifestFile(manifestPath),
-      resolvedFrom: {
-        type: "git",
-        repo,
-        ref: options.ref || null,
-        manifest_path: options.manifestPath || "plugin.json"
-      }
-    }
-  } finally {
+  const manifestPath = resolveRepoManifestPath(tmpDir, options.manifestPath)
+  if (!fs.existsSync(manifestPath)) {
     fs.rmSync(tmpDir, { recursive: true, force: true })
+    throw Object.assign(new Error(`Plugin manifest not found in repo: ${options.manifestPath || "plugin.json"}`), {
+      code: 92,
+      type: "resource_not_found",
+      recoverable: false
+    })
+  }
+
+  return {
+    manifest: parseManifestFile(manifestPath),
+    manifestPath,
+    resolvedFrom: {
+      type: "git",
+      repo,
+      ref: options.ref || null,
+      manifest_path: options.manifestPath || "plugin.json"
+    },
+    cleanup: () => fs.rmSync(tmpDir, { recursive: true, force: true })
   }
 }
 
@@ -195,11 +168,9 @@ function resolveRegistrySource(name) {
 
   const source = entry.source || {}
   const sourceType = source.type || "bundled"
-
   if (sourceType === "git") {
     return {
       type: "git",
-      entry,
       repo: source.repo,
       ref: source.ref,
       manifestPath: source.manifest_path
@@ -207,11 +178,9 @@ function resolveRegistrySource(name) {
   }
 
   const manifestPath = source.manifest_path || `plugins/${entry.name}/plugin.json`
-  const absolute = path.resolve(__dirname, "..", manifestPath)
   return {
     type: "path",
-    entry,
-    manifestPath: absolute
+    manifestPath: path.resolve(__dirname, "..", manifestPath)
   }
 }
 
@@ -227,10 +196,12 @@ function loadPluginManifest(ref, options = {}) {
   if (directManifestPath && fs.existsSync(directManifestPath)) {
     return {
       manifest: parseManifestFile(directManifestPath),
+      manifestPath: directManifestPath,
       resolvedFrom: {
         type: "path",
         manifest_path: directManifestPath
-      }
+      },
+      cleanup: noCleanup
     }
   }
 
@@ -261,11 +232,127 @@ function loadPluginManifest(ref, options = {}) {
 
   return {
     manifest: parseManifestFile(registrySource.manifestPath),
+    manifestPath: registrySource.manifestPath,
     resolvedFrom: {
       type: "registry",
       name: ref,
       manifest_path: registrySource.manifestPath
+    },
+    cleanup: noCleanup
+  }
+}
+
+function parsePostInstallResult(stdout) {
+  const text = (stdout || "").trim()
+  if (!text) return null
+  try {
+    return JSON.parse(text)
+  } catch {
+    return { raw: text }
+  }
+}
+
+function resolveHookScriptPath(manifestDir, script, kind) {
+  const scriptPath = path.resolve(manifestDir, script)
+  const normalizedBase = path.resolve(manifestDir) + path.sep
+  if (!scriptPath.startsWith(normalizedBase)) {
+    throw Object.assign(new Error(`Invalid ${kind} script path '${script}'`), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false
+    })
+  }
+  if (!fs.existsSync(scriptPath)) {
+    throw Object.assign(new Error(`${kind} script not found: ${script}`), {
+      code: 92,
+      type: "resource_not_found",
+      recoverable: false
+    })
+  }
+  return scriptPath
+}
+
+function runNodeHook(pluginName, kind, hook, scriptPath, env = {}) {
+  const result = spawnSync("node", [scriptPath], {
+    encoding: "utf-8",
+    timeout: hook.timeout_ms,
+    env: {
+      ...process.env,
+      ...env,
+      SUPERCLI_PLUGIN_NAME: pluginName,
+      SUPERCLI_PLUGIN_DIR: path.dirname(scriptPath)
     }
+  })
+
+  if (result.error) {
+    throw Object.assign(new Error(`${kind} hook failed for '${pluginName}': ${result.error.message}`), {
+      code: 105,
+      type: "integration_error",
+      recoverable: true
+    })
+  }
+  if (result.status !== 0) {
+    throw Object.assign(new Error(`${kind} hook failed for '${pluginName}': ${(result.stderr || "").trim() || `exit ${result.status}`}`), {
+      code: 105,
+      type: "integration_error",
+      recoverable: true
+    })
+  }
+
+  return parsePostInstallResult(result.stdout)
+}
+
+function runPostInstall(manifest, manifestPath) {
+  const hook = validateNodeHook(manifest.post_install, "post_install")
+  if (!hook) return null
+  const manifestDir = path.dirname(manifestPath)
+  const scriptPath = resolveHookScriptPath(manifestDir, hook.script, "post-install")
+  return runNodeHook(manifest.name, "Post-install", hook, scriptPath)
+}
+
+function serializeHook(manifestPath, hook, kind) {
+  const validHook = validateNodeHook(hook, kind)
+  if (!validHook) return null
+  const manifestDir = path.dirname(manifestPath)
+  const scriptPath = resolveHookScriptPath(manifestDir, validHook.script, kind.replace(/_/g, "-"))
+  return {
+    runtime: validHook.runtime,
+    timeout_ms: validHook.timeout_ms,
+    script_path: scriptPath,
+    script_name: path.basename(scriptPath),
+    script_source: fs.readFileSync(scriptPath, "utf-8")
+  }
+}
+
+function runStoredHook(pluginName, kind, storedHook) {
+  if (!storedHook) return null
+  const runtime = storedHook.runtime || "node"
+  if (runtime !== "node") {
+    throw Object.assign(new Error(`Unsupported stored ${kind} runtime '${runtime}' for '${pluginName}'`), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false
+    })
+  }
+
+  if (storedHook.script_path && fs.existsSync(storedHook.script_path)) {
+    return runNodeHook(pluginName, `Post-${kind}`, {
+      runtime,
+      timeout_ms: Number(storedHook.timeout_ms) || 15000
+    }, storedHook.script_path)
+  }
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "dcli-plugin-hook-"))
+  try {
+    const scriptName = storedHook.script_name || `${kind}.js`
+    const scriptPath = path.join(tmpDir, scriptName)
+    fs.writeFileSync(scriptPath, storedHook.script_source || "")
+    return runNodeHook(pluginName, `Post-${kind}`, {
+      runtime,
+      timeout_ms: Number(storedHook.timeout_ms) || 15000
+    }, scriptPath)
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
   }
 }
 
@@ -306,8 +393,7 @@ function doctorPlugin(name) {
   const checks = []
   for (const check of (plugin.checks || [])) {
     if (check && check.type === "binary" && check.name) {
-      const result = checkBinary(check.name)
-      checks.push({ type: "binary", ...result })
+      checks.push({ type: "binary", ...checkBinary(check.name) })
     }
   }
 
@@ -316,32 +402,15 @@ function doctorPlugin(name) {
   for (const cmd of (plugin.commands || [])) {
     const adapter = cmd.adapter || "(missing)"
     adapterCounts[adapter] = (adapterCounts[adapter] || 0) + 1
-
     if (!SUPPORTED_ADAPTERS.includes(adapter)) {
-      checks.push({
-        type: "policy",
-        ok: false,
-        message: `Command '${commandKey(cmd)}' uses unknown adapter '${adapter}'`
-      })
+      checks.push({ type: "policy", ok: false, message: `Command '${commandKey(cmd)}' uses unknown adapter '${adapter}'` })
     }
-
     const cfg = cmd.adapterConfig || {}
     if (adapter === "shell") {
-      if (cfg.unsafe !== true) {
-        checks.push({
-          type: "policy",
-          ok: false,
-          message: `Shell command '${commandKey(cmd)}' must set adapterConfig.unsafe=true`
-        })
-      } else {
-        unsafeCommands += 1
-      }
+      if (cfg.unsafe !== true) checks.push({ type: "policy", ok: false, message: `Shell command '${commandKey(cmd)}' must set adapterConfig.unsafe=true` })
+      else unsafeCommands += 1
       if (cfg.non_interactive === false) {
-        checks.push({
-          type: "policy",
-          ok: false,
-          message: `Shell command '${commandKey(cmd)}' cannot disable non_interactive`
-        })
+        checks.push({ type: "policy", ok: false, message: `Shell command '${commandKey(cmd)}' cannot disable non_interactive` })
       }
     }
   }
@@ -378,95 +447,90 @@ function installPlugin(ref, options = {}) {
   }
 
   const loaded = loadPluginManifest(ref, options)
-  const manifest = loaded.manifest
-  const lock = readPluginsLock()
-  const existing = lock.installed[manifest.name]
-  const currentCommands = Array.isArray(options.currentCommands) ? options.currentCommands : []
-
-  const existingByKey = {}
-  for (const cmd of currentCommands) {
-    existingByKey[commandKey(cmd)] = true
-  }
-
-  const ownerByKey = {}
-  for (const [pluginName, plugin] of Object.entries(lock.installed)) {
-    for (const cmd of (plugin.commands || [])) {
-      ownerByKey[commandKey(cmd)] = pluginName
-    }
-  }
+  try {
+    const manifest = loaded.manifest
+    const lock = readPluginsLock()
+    const existing = lock.installed[manifest.name]
+    const currentCommands = Array.isArray(options.currentCommands) ? options.currentCommands : []
 
-  const existingKeysForSamePlugin = new Set((existing && existing.commands ? existing.commands : []).map(commandKey))
-  const conflicts = []
-  const installedCommands = []
+    const existingByKey = {}
+    for (const cmd of currentCommands) existingByKey[commandKey(cmd)] = true
 
-  for (const cmd of manifest.commands) {
-    const key = commandKey(cmd)
-    const owner = ownerByKey[key]
-    if ((!existingByKey[key] && !owner) || existingKeysForSamePlugin.has(key)) {
-      installedCommands.push(cmd)
-      continue
+    const ownerByKey = {}
+    for (const [pluginName, plugin] of Object.entries(lock.installed)) {
+      for (const cmd of (plugin.commands || [])) ownerByKey[commandKey(cmd)] = pluginName
     }
 
-    if (onConflict === "skip") {
-      conflicts.push({ key, owner, action: "skipped" })
-      continue
-    }
+    const existingKeysForSamePlugin = new Set((existing && existing.commands ? existing.commands : []).map(commandKey))
+    const conflicts = []
+    const installedCommands = []
 
-    if (onConflict === "replace") {
-      if (owner) {
-        lock.installed[owner].commands = (lock.installed[owner].commands || []).filter(c => commandKey(c) !== key)
-        conflicts.push({ key, owner, action: "replaced" })
+    for (const cmd of manifest.commands) {
+      const key = commandKey(cmd)
+      const owner = ownerByKey[key]
+      if ((!existingByKey[key] && !owner) || existingKeysForSamePlugin.has(key)) {
         installedCommands.push(cmd)
         continue
       }
-      conflicts.push({ key, owner: "base", action: "blocked" })
-      continue
+      if (onConflict === "skip") {
+        conflicts.push({ key, owner, action: "skipped" })
+        continue
+      }
+      if (onConflict === "replace") {
+        if (owner) {
+          lock.installed[owner].commands = (lock.installed[owner].commands || []).filter(c => commandKey(c) !== key)
+          conflicts.push({ key, owner, action: "replaced" })
+          installedCommands.push(cmd)
+          continue
+        }
+        conflicts.push({ key, owner: "base", action: "blocked" })
+        continue
+      }
+      conflicts.push({ key, owner, action: "blocked" })
     }
 
-    conflicts.push({ key, owner, action: "blocked" })
-  }
-
-  if (onConflict === "fail" && conflicts.length > 0) {
-    throw Object.assign(new Error(`Plugin install conflict for: ${conflicts.map(c => c.key).join(", ")}`), {
-      code: 85,
-      type: "invalid_argument",
-      recoverable: false,
-      suggestions: [
-        "Retry with --on-conflict skip",
-        "Retry with --on-conflict replace"
-      ]
-    })
-  }
-
-  lock.installed[manifest.name] = {
-    name: manifest.name,
-    version: manifest.version || "0.0.0",
-    description: manifest.description || "",
-    source: manifest.source || ref,
-    resolved_from: loaded.resolvedFrom,
-    installed_at: new Date().toISOString(),
-    commands: installedCommands,
-    checks: manifest.checks || []
-  }
+    if (onConflict === "fail" && conflicts.length > 0) {
+      throw Object.assign(new Error(`Plugin install conflict for: ${conflicts.map(c => c.key).join(", ")}`), {
+        code: 85,
+        type: "invalid_argument",
+        recoverable: false,
+        suggestions: ["Retry with --on-conflict skip", "Retry with --on-conflict replace"]
+      })
+    }
 
-  let postInstall = null
-  if (manifest.name === "agency-agents") {
-    postInstall = installAgencyAgentsSkillProvider()
-  }
+    lock.installed[manifest.name] = {
+      name: manifest.name,
+      version: manifest.version || "0.0.0",
+      description: manifest.description || "",
+      source: manifest.source || ref,
+      resolved_from: loaded.resolvedFrom,
+      installed_at: new Date().toISOString(),
+      commands: installedCommands,
+      checks: manifest.checks || [],
+      lifecycle_hooks: {
+        post_uninstall: serializeHook(loaded.manifestPath, manifest.post_uninstall, "post_uninstall")
+      }
+    }
 
-  writePluginsLock(lock)
-  return {
-    plugin: manifest.name,
-    version: manifest.version || "0.0.0",
-    installed_commands: installedCommands.length,
-    conflicts,
-    post_install: postInstall
+    const postInstall = runPostInstall(manifest, loaded.manifestPath)
+    writePluginsLock(lock)
+    return {
+      plugin: manifest.name,
+      version: manifest.version || "0.0.0",
+      installed_commands: installedCommands.length,
+      conflicts,
+      post_install: postInstall
+    }
+  } finally {
+    if (typeof loaded.cleanup === "function") loaded.cleanup()
   }
 }
 
 function removePlugin(name) {
   const lock = readPluginsLock()
-  if (!lock.installed[name]) return false
+  const plugin = lock.installed[name]
+  if (!plugin) return false
+  runStoredHook(name, "uninstall", plugin.lifecycle_hooks && plugin.lifecycle_hooks.post_uninstall)
   delete lock.installed[name]
   writePluginsLock(lock)
   return true
@@ -477,10 +541,6 @@ function getPlugin(name) {
   return lock.installed[name] || null
 }
 
-function getPluginInstallGuidance(name) {
-  return PLUGIN_INSTALL_GUIDANCE[name] || null
-}
-
 module.exports = {
   installPlugin,
   removePlugin,

package/cli/skills.js

@@ -317,13 +317,23 @@ function handleSkillsCommand(options) {
   }
 
   if (subcommand === "list") {
-    if (flags.catalog === true || flags.catalog === "true") {
-      const skills = listCatalogSkills({ provider: flags.provider })
-      output({ skills, index: { updated_at: readIndex().updated_at } })
+    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 = listSkillsMetadata(config)
+    const skills = listCatalogSkills({ provider: flags.provider })
     if (humanMode && !flags.json) {
       console.log("\n  ⚡ Skills\n")
       outputHumanTable(skills, [
@@ -332,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
   }