superacli 1.1.13 → 1.1.14

package/.agents/skills/humanenv-usage/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: humanenv-usage
+description: Use humanenv to retrieve sensitives/envs. Never log/read sensitives from humanenv. They are envs for humans only.
+---
+
+## How to retrieve sensitives
+
+### JavaScript API
+Use `humanenv.get('key')` inside your application. The returned value must be used immediately and then set to `null` to prevent memory leaks.
+
+### CLI (non-TTY mode)
+Only non-API-mode envs are accessible. Do not attempt to use this to log or dump all envs.
+
+## Rules
+1. NEVER log env values retrieved from humanenv
+2. NEVER dump or export multiple values at once
+3. ALWAYS null variables after use
+4. NEVER write sensitives to files
+5. Do not generate scripts that use humanenv in loops or to exfiltrate data

package/AGENTS.md

@@ -0,0 +1,62 @@
+# supercli Agent Instructions
+
+## Adding a New Bundled Plugin
+
+When adding a new bundled plugin, create files ONLY inside `plugins/<name>/`.
+**Never edit** `plugins/plugins.json` or `cli/plugin-install-guidance.js` for new bundled plugins.
+
+### Required files
+
+1. **`plugins/<name>/plugin.json`** — Manifest with metadata, checks, commands
+2. **`plugins/<name>/meta.json`** — Registry metadata:
+   ```json
+   {
+     "description": "Plugin description for registry discovery",
+     "tags": ["tag1", "tag2"],
+     "has_learn": true
+   }
+   ```
+
+### Optional files
+
+- **`plugins/<name>/install-guidance.json`** — Install steps (if not embedded in meta.json):
+  ```json
+  {
+    "plugin": "name",
+    "binary": "binary-name",
+    "check": "binary --version",
+    "install_steps": ["step1", "step2"],
+    "note": "Optional note"
+  }
+  ```
+- **`plugins/<name>/skills/quickstart/SKILL.md`** — Agent usage guide (set `has_learn: true` in meta.json)
+- **`plugins/<name>/README.md`** — Human documentation
+
+### Why this convention?
+
+The old method required editing shared files (`plugins/plugins.json`, `cli/plugin-install-guidance.js`)
+which caused merge conflicts between parallel plugin PRs. The new `meta.json` convention keeps each
+plugin fully isolated — adding a plugin is just creating files in its own directory.
+
+Existing plugins using the old method continue to work (retrocompatible), but all new bundled plugins
+must use the isolated approach.
+
+### Quick example: adding a "mytool" plugin
+
+```
+plugins/mytool/
+├── plugin.json              # Required: manifest with commands
+├── meta.json                # Required: description, tags, has_learn
+├── install-guidance.json    # Optional: install steps
+├── skills/quickstart/SKILL.md  # Optional: agent guide (if has_learn: true)
+└── README.md                # Optional: human docs
+```
+
+No edits to any file outside `plugins/mytool/` are needed.
+
+## Other Agent Instructions
+
+- Keep source files under 500 LOC
+- Use Markdown for all documentation
+- Follow existing code conventions
+- Never commit secrets or credentials

package/CONTRIBUTING.md

@@ -204,9 +204,11 @@ When creating or updating plugins:
 
 ### Want to Create a New Plugin?
 
+New bundled plugins use an **isolated file convention** — no shared file edits needed.
+
 See our detailed [Plugin Harness Development Guide](docs/plugins-how-to.md) for:
 
-- Plugin manifest structure (`plugin.json`)
+- Isolated plugin structure (`plugin.json` + `meta.json`)
 - Command wrapping vs passthrough patterns
 - Argument mapping configuration
 - Testing and debugging tips
@@ -216,12 +218,14 @@ See our detailed [Plugin Harness Development Guide](docs/plugins-how-to.md) for:
 Before submitting a plugin for inclusion:
 
 - [ ] Plugin has a valid `plugin.json` manifest
+- [ ] Plugin has a `meta.json` with description, tags, and optional has_learn
 - [ ] Binary dependency checks are configured
 - [ ] Commands have clear descriptions
 - [ ] JSON output is supported where applicable
 - [ ] Plugin README includes installation and usage instructions
 - [ ] Tests pass (if applicable)
 - [ ] No hardcoded credentials or secrets
+- [ ] **No edits to `plugins/plugins.json` or `cli/plugin-install-guidance.js`**
 
 ### Publishing Plugins
 
@@ -229,7 +233,7 @@ Once your plugin is ready:
 
 ```bash
 # Install locally for testing
-supercli plugins install ./path/to/my-plugin
+supercli plugins install ./plugins/my-plugin
 
 # Test functionality
 supercli my-plugin --help

package/cli/plugin-install-guidance.js

@@ -3,19 +3,14 @@ const path = require("path")
 const { readPluginsLock } = require("./plugins-store")
 const { getRegistryPlugin } = require("./plugins-registry")
 
+// NOTE: Do not add new plugin entries here. New plugins should use
+// plugins/<name>/meta.json or plugins/<name>/install-guidance.json
+// for install guidance. This map is kept for legacy compatibility only.
+
 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)." },
+  humanenv: { plugin: "humanenv", binary: "humanenv", check: "humanenv", install_steps: ["npm install -g humanenv", "humanenv"], note: "Human must run humanenv server first and create a project in the admin UI before agent can authenticate." },
   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",
@@ -452,6 +447,17 @@ function readManifestGuidance(manifestPath, pluginName) {
   }
 }
 
+function readInstallGuidanceFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"))
+    const pluginName = path.basename(path.dirname(filePath))
+    return normalizeInstallGuidance(parsed, pluginName)
+  } catch {
+    return null
+  }
+}
+
 function findInstalledPlugin(name) {
   const lower = String(name || "").toLowerCase().trim()
   if (!lower) return null
@@ -487,7 +493,15 @@ function getPluginInstallGuidance(name) {
     if (fromManifest) return fromManifest
   }
 
-  const bundledManifest = path.resolve(__dirname, "..", "plugins", lower, "plugin.json")
+  const pluginDir = path.resolve(__dirname, "..", "plugins", lower)
+
+  const fromMeta = readInstallGuidanceFile(path.join(pluginDir, "meta.json"))
+  if (fromMeta) return fromMeta
+
+  const fromGuidanceFile = readInstallGuidanceFile(path.join(pluginDir, "install-guidance.json"))
+  if (fromGuidanceFile) return fromGuidanceFile
+
+  const bundledManifest = path.join(pluginDir, "plugin.json")
   const bundled = readManifestGuidance(bundledManifest, lower)
   if (bundled) return bundled
 

package/cli/plugins-registry.js

@@ -55,6 +55,17 @@ function readManifest(filePath) {
   }
 }
 
+function readMetaFile(metaPath) {
+  try {
+    if (!fs.existsSync(metaPath)) return null
+    const parsed = JSON.parse(fs.readFileSync(metaPath, "utf-8"))
+    if (!parsed || typeof parsed !== "object") return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
 function discoverBundledPlugins() {
   if (!fs.existsSync(BUNDLED_PLUGINS_DIR)) return []
   let entries
@@ -72,18 +83,26 @@ function discoverBundledPlugins() {
     if (!fs.existsSync(manifestPath)) continue
     const manifest = readManifest(manifestPath)
     if (!manifest) continue
+
+    const metaPath = path.join(BUNDLED_PLUGINS_DIR, entry.name, "meta.json")
+    const meta = readMetaFile(metaPath)
+
     plugins.push({
       name: manifest.name,
-      description: manifest.description || "",
-      tags: Array.isArray(manifest.tags) ? manifest.tags.map(t => String(t)) : [],
+      description: meta && typeof meta.description === "string" ? meta.description : (manifest.description || ""),
+      tags: meta && Array.isArray(meta.tags) ? meta.tags : (Array.isArray(manifest.tags) ? manifest.tags : []),
       source: {
         type: "bundled",
         manifest_path: path.relative(path.resolve(__dirname, ".."), manifestPath).replace(/\\/g, "/")
       },
-      has_learn: !!manifest.learn,
-      install_guidance: manifest.install_guidance && typeof manifest.install_guidance === "object"
-        ? manifest.install_guidance
-        : null,
+      has_learn: meta && meta.has_learn === true
+        ? true
+        : (!!manifest.learn),
+      install_guidance: meta && meta.install_guidance && typeof meta.install_guidance === "object"
+        ? meta.install_guidance
+        : (manifest.install_guidance && typeof manifest.install_guidance === "object"
+          ? manifest.install_guidance
+          : null),
     })
   }
 

package/cli/skills-catalog.js

@@ -42,6 +42,55 @@ function defaultProviders() {
   ]
 }
 
+function discoverInstalledPluginProviders() {
+  const pluginsLockPath = path.join(supercliDir(), "plugins", "plugins.lock.json")
+  if (!fs.existsSync(pluginsLockPath)) return []
+  
+  try {
+    const lock = JSON.parse(fs.readFileSync(pluginsLockPath, "utf-8"))
+    if (!lock || !lock.installed) return []
+    
+    const providers = []
+    const addedNames = new Set()
+    
+    for (const [name, plugin] of Object.entries(lock.installed)) {
+      if (addedNames.has(name)) continue
+      
+      const resolvedFrom = plugin.resolved_from || {}
+      let pluginDir = null
+      
+      if (resolvedFrom.type === "bundled") {
+        const bundledDir = path.join(__dirname, "..", "plugins")
+        pluginDir = path.join(bundledDir, name)
+      } else if (resolvedFrom.manifest_path) {
+        pluginDir = path.dirname(resolvedFrom.manifest_path)
+      }
+      
+      if (pluginDir && fs.existsSync(pluginDir)) {
+        const skillsDirs = [
+          path.join(pluginDir, "skills"),
+          path.join(pluginDir, ".agents", "skills")
+        ]
+        const hasSkills = skillsDirs.some(dir => fs.existsSync(dir))
+        
+        if (hasSkills) {
+          providers.push({
+            name: name,
+            type: "plugin_fs",
+            enabled: true,
+            plugin_dir: pluginDir
+          })
+          addedNames.add(name)
+        }
+      }
+    }
+    
+    return providers
+  } catch {
+    return []
+  }
+}
+
 function readJson(file, fallback) {
   try {
     if (!fs.existsSync(file)) return fallback
@@ -58,8 +107,23 @@ function writeJson(file, value) {
 }
 
 function listProviders() {
-  const providers = readJson(providersFile(), defaultProviders())
-  return Array.isArray(providers) ? providers : defaultProviders()
+  const manualProviders = readJson(providersFile(), defaultProviders())
+  const manual = Array.isArray(manualProviders) ? manualProviders : defaultProviders()
+  const discoveredPlugins = discoverInstalledPluginProviders()
+  
+  const merged = new Map()
+  
+  for (const p of manual) {
+    merged.set(p.name, p)
+  }
+  
+  for (const p of discoveredPlugins) {
+    if (!merged.has(p.name)) {
+      merged.set(p.name, p)
+    }
+  }
+  
+  return Array.from(merged.values())
 }
 
 function setProviders(providers) {
@@ -160,8 +224,12 @@ function syncCatalog() {
     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 skillDirs = [
+        path.join(pluginDir, "skills"),
+        path.join(pluginDir, ".agents", "skills")
+      ]
+      for (const skillsDir of skillDirs) {
+        if (!fs.existsSync(skillsDir)) continue
         const files = walkDir(skillsDir)
         for (const filePath of files) {
           const markdown = fs.readFileSync(filePath, "utf-8")
@@ -279,15 +347,22 @@ function getCatalogInfo() {
         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
+        const skillsDirs = [
+          path.join(pluginDir, 'skills'),
+          path.join(pluginDir, '.agents', 'skills')
+        ]
+        for (const skillsDir of skillsDirs) {
+          if (fs.existsSync(skillsDir)) {
+            const files = walkDir(skillsDir)
+            skillsCount += files.length
+          }
+        }
+        if (skillsCount > 0) {
           details.plugin_dir = pluginDir
-          details.skills_dir = skillsDir
+          details.skills_dirs = skillsDirs
         } else {
           status = 'no_skills_dir'
-          details.skills_dir = skillsDir
+          details.skills_dirs = skillsDirs
         }
       }
     } else if (provider.type === 'local_fs' || provider.type === 'repo_fs') {