agentsys 5.1.0 → 5.2.1

package/bin/cli.js

@@ -8,10 +8,12 @@
  * Remove:   npm uninstall -g agentsys && agentsys --remove
  */
 
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const https = require('https');
+const { createGunzip } = require('zlib');
 
 const VERSION = require('../package.json').version;
 // Use the installed npm package directory as source (no git clone needed)
@@ -20,7 +22,7 @@ const discovery = require('../lib/discovery');
 const transforms = require('../lib/adapter-transforms');
 
 // Valid tool names
-const VALID_TOOLS = ['claude', 'opencode', 'codex'];
+const VALID_TOOLS = ['claude', 'opencode', 'codex', 'cursor'];
 
 function getInstallDir() {
   const home = process.env.HOME || process.env.USERPROFILE;
@@ -54,7 +56,7 @@ function getConfigPath(platform) {
 
 function commandExists(cmd) {
   try {
-    execSync(`${process.platform === 'win32' ? 'where' : 'which'} ${cmd}`, { stdio: 'pipe' });
+    execFileSync(process.platform === 'win32' ? 'where.exe' : 'which', [cmd], { stdio: 'pipe' });
     return true;
   } catch {
     return false;
@@ -84,6 +86,9 @@ function parseArgs(args) {
     stripModels: true, // Default: strip models
     tool: null,        // Single tool
     tools: [],         // Multiple tools
+    only: [],          // --only flag: selective plugin install
+    subcommand: null,  // 'update', 'list', 'install', 'remove', 'search'
+    subcommandArg: null, // argument for subcommand (e.g. plugin name)
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -102,6 +107,10 @@ function parseArgs(args) {
     } else if (arg === '--strip-models') {
       // Legacy flag, now default behavior
       result.stripModels = true;
+    } else if (arg === '--only' && args[i + 1]) {
+      const pluginList = args[i + 1].split(',').map(p => p.trim()).filter(Boolean);
+      result.only.push(...pluginList);
+      i++;
     } else if (arg === '--tool' && args[i + 1]) {
       const tool = args[i + 1].toLowerCase();
       if (VALID_TOOLS.includes(tool)) {
@@ -121,6 +130,20 @@ function parseArgs(args) {
         result.tools.push(tool);
       }
       i++;
+    } else if (['update', 'list', 'install', 'remove', 'search'].includes(arg)) {
+      result.subcommand = arg;
+      // Check for subcommand --help
+      if (args[i + 1] && (args[i + 1] === '--help' || args[i + 1] === '-h')) {
+        result.subcommandArg = '--help';
+        i++;
+      // For 'list': accept --all, --agents, --skills, --commands, --hooks, --plugins
+      } else if (arg === 'list' && args[i + 1] && ['--all', '--agents', '--skills', '--commands', '--hooks', '--plugins'].includes(args[i + 1])) {
+        result.subcommandArg = args[i + 1];
+        i++;
+      } else if (args[i + 1] && !args[i + 1].startsWith('-')) {
+        result.subcommandArg = args[i + 1];
+        i++;
+      }
     }
   }
 
@@ -191,6 +214,1007 @@ function installDependencies(installDir) {
   execSync('npm install --production', { cwd: installDir, stdio: 'inherit' });
 }
 
+// --- External Plugin Fetching ---
+
+function getPluginCacheDir() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  return path.join(home, '.agentsys', 'plugins');
+}
+
+function loadMarketplace() {
+  const marketplacePath = path.join(PACKAGE_DIR, '.claude-plugin', 'marketplace.json');
+  if (!fs.existsSync(marketplacePath)) {
+    console.error('[ERROR] marketplace.json not found at ' + marketplacePath);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(marketplacePath, 'utf8'));
+}
+
+/**
+ * Normalize marketplace plugin source entries.
+ *
+ * Supported formats:
+ * - string URL/path (legacy)
+ * - object: { source: "url", url: "..." } (current)
+ * - object: { source: "path", path: "..." } (local/bundled)
+ *
+ * @param {string|Object} source
+ * @returns {{type: 'remote'|'local', value: string}|null}
+ */
+function resolvePluginSource(source) {
+  if (typeof source === 'string') {
+    const value = source.trim();
+    if (!value) return null;
+    if (value.startsWith('./') || value.startsWith('../')) {
+      return { type: 'local', value };
+    }
+    return { type: 'remote', value };
+  }
+
+  if (!source || typeof source !== 'object') return null;
+
+  const sourceType = typeof source.source === 'string' ? source.source.toLowerCase() : null;
+
+  if ((sourceType === 'path' || sourceType === 'local') && typeof source.path === 'string') {
+    return { type: 'local', value: source.path };
+  }
+
+  if (sourceType === 'url' && typeof source.url === 'string') {
+    return { type: 'remote', value: source.url };
+  }
+
+  // Backward/forward-compatible fallbacks
+  if (typeof source.path === 'string') {
+    return { type: 'local', value: source.path };
+  }
+  if (typeof source.url === 'string') {
+    return { type: 'remote', value: source.url };
+  }
+
+  return null;
+}
+
+/**
+ * Backward-compatible helper returning only the source URL/path value.
+ *
+ * @param {string|Object} source
+ * @returns {string|null}
+ */
+function resolveSourceUrl(source) {
+  const normalized = resolvePluginSource(source);
+  return normalized ? normalized.value : null;
+}
+
+/**
+ * Resolve plugin dependencies transitively.
+ *
+ * Circular dependencies are expected and handled: the `visiting` Set tracks
+ * the current DFS path and short-circuits any back-edge (e.g. next-task ->
+ * ship -> next-task), adding the already-visited node to `resolved` and
+ * returning immediately so the traversal terminates without infinite recursion.
+ *
+ * @param {string[]} names - Plugin names to resolve
+ * @param {Object} marketplace - Parsed marketplace.json
+ * @returns {string[]} All required plugin names (deduplicated, topologically ordered)
+ */
+function resolvePluginDeps(names, marketplace) {
+  const pluginMap = {};
+  for (const p of marketplace.plugins) {
+    pluginMap[p.name] = p;
+  }
+
+  // Validate requested names exist
+  for (const name of names) {
+    if (!pluginMap[name]) {
+      console.error(`[ERROR] Unknown plugin: ${name}. Available: ${marketplace.plugins.map(p => p.name).join(', ')}`);
+      process.exit(1);
+    }
+  }
+
+  const resolved = new Set();
+  const visiting = new Set();
+
+  function visit(name) {
+    if (resolved.has(name)) return;
+    if (visiting.has(name)) {
+      // Circular dep - just add it and stop recursing
+      resolved.add(name);
+      return;
+    }
+    visiting.add(name);
+
+    visiting.delete(name);
+    resolved.add(name);
+  }
+
+  for (const name of names) {
+    visit(name);
+  }
+
+  return [...resolved];
+}
+
+/**
+ * Download a GitHub repo tarball and extract to cache directory.
+ *
+ * @param {string} name - Plugin name
+ * @param {string} source - GitHub source URL (e.g. "github:agent-sh/agentsys-plugin-next-task")
+ * @param {string} version - Expected version string
+ * @returns {Promise<string>} Path to extracted plugin directory
+ */
+async function fetchPlugin(name, source, version) {
+  const cacheDir = getPluginCacheDir();
+  const pluginDir = path.join(cacheDir, name);
+  const versionFile = path.join(pluginDir, '.version');
+
+  // Check cache
+  if (fs.existsSync(versionFile)) {
+    const cached = fs.readFileSync(versionFile, 'utf8').trim();
+    if (cached === version) {
+      return pluginDir;
+    }
+  }
+
+  const parsedSource = parseGitHubSource(source, version, name);
+  const owner = parsedSource.owner;
+  const repo = parsedSource.repo;
+
+  const refCandidates = parsedSource.explicitRef
+    ? [parsedSource.ref]
+    : [parsedSource.ref, version, 'main', 'master'];
+
+  let lastError = null;
+  for (const ref of [...new Set(refCandidates.filter(Boolean))]) {
+    const tarballUrl = `https://api.github.com/repos/${owner}/${repo}/tarball/${ref}`;
+
+    try {
+      console.log(`  Fetching ${name}@${version} from ${owner}/${repo} (${ref})...`);
+
+      // Clean and recreate
+      if (fs.existsSync(pluginDir)) {
+        fs.rmSync(pluginDir, { recursive: true, force: true });
+      }
+      fs.mkdirSync(pluginDir, { recursive: true });
+
+      // Download and extract tarball
+      await downloadAndExtractTarball(tarballUrl, pluginDir);
+
+      // Write version marker
+      fs.writeFileSync(versionFile, version);
+      return pluginDir;
+    } catch (err) {
+      lastError = err;
+      const isNotFound = /HTTP 404/.test(err.message);
+      if (isNotFound && !parsedSource.explicitRef) {
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  throw new Error(
+    `Unable to fetch ${name} from ${owner}/${repo}. Tried refs: ${[...new Set(refCandidates.filter(Boolean))].join(', ')}. Last error: ${lastError ? lastError.message : 'unknown error'}`
+  );
+}
+
+/**
+ * Parse GitHub source URL formats and normalize repo name.
+ *
+ * @param {string} source
+ * @param {string} version
+ * @param {string} [name]
+ * @returns {{owner: string, repo: string, ref: string, explicitRef: boolean}}
+ */
+function parseGitHubSource(source, version, name = 'plugin') {
+  // Parse source formats:
+  //   "https://github.com/owner/repo" or "https://github.com/owner/repo#ref"
+  //   "github:owner/repo" or "github:owner/repo#ref"
+  const urlMatch = source.match(/github\.com\/([^/]+)\/([^/#]+)(?:#(.+))?/);
+  const shortMatch = !urlMatch && source.match(/^github:([^/]+)\/([^#]+)(?:#(.+))?$/);
+  const match = urlMatch || shortMatch;
+  if (!match) {
+    throw new Error(`Unsupported source format for ${name}: ${source}`);
+  }
+
+  const owner = match[1];
+  const repo = match[2].replace(/\.git$/, '');
+  const explicitRef = Boolean(match[3]);
+  const ref = match[3] || `v${version}`;
+  return { owner, repo, ref, explicitRef };
+}
+
+/**
+ * Download a tarball from URL and extract to dest directory.
+ * Strips the top-level directory from the tarball (GitHub tarballs have owner-repo-sha/).
+ */
+function downloadAndExtractTarball(url, dest) {
+  return new Promise((resolve, reject) => {
+    const ghToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    const request = (reqUrl, redirectCount = 0) => {
+      if (redirectCount > 5) {
+        reject(new Error(`Too many redirects fetching tarball from ${url}`));
+        return;
+      }
+      const headers = {
+        'User-Agent': `agentsys/${VERSION}`,
+        'Accept': 'application/vnd.github+json'
+      };
+      if (ghToken) headers['Authorization'] = `Bearer ${ghToken}`;
+      https.get(reqUrl, { headers }, (res) => {
+        // Follow redirects (GitHub API returns 302 to S3)
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          res.resume();
+          request(res.headers.location, redirectCount + 1);
+          return;
+        }
+
+        if (res.statusCode !== 200) {
+          res.resume();
+          const hint = res.statusCode === 403 ? ' (rate limited — set GITHUB_TOKEN env var)' : '';
+          reject(new Error(`HTTP ${res.statusCode}${hint} fetching tarball from ${reqUrl}`));
+          return;
+        }
+
+        // Use tar command to extract (available on all supported platforms)
+        // On Windows/MSYS2, convert backslash paths to forward slashes for tar
+        const tarDest = process.platform === 'win32' ? dest.replace(/\\/g, '/') : dest;
+        const tar = require('child_process').spawn('tar', [
+          'xz', '--strip-components=1', '-C', tarDest
+        ], { stdio: ['pipe', 'inherit', 'pipe'] });
+
+        let stderr = '';
+        tar.stderr.on('data', (d) => { stderr += d; });
+
+        res.pipe(tar.stdin);
+
+        tar.on('close', (code) => {
+          if (code !== 0) {
+            reject(new Error(`tar extraction failed (code ${code}): ${stderr}`));
+          } else {
+            resolve();
+          }
+        });
+
+        tar.on('error', reject);
+      }).on('error', reject);
+    };
+
+    request(url);
+  });
+}
+
+/**
+ * Discover plugins from the external cache directory (~/.agentsys/plugins/).
+ * Falls back to PACKAGE_DIR/plugins/ if cache doesn't exist (bundled install).
+ *
+ * @param {string[]} [onlyPlugins] - If provided, only return these plugins
+ * @returns {string} The root directory to use for plugin discovery
+ */
+function resolvePluginRoot(onlyPlugins) {
+  const cacheDir = getPluginCacheDir();
+  // If we have cached external plugins, use the cache dir
+  if (fs.existsSync(cacheDir)) {
+    const entries = fs.readdirSync(cacheDir).filter(e => {
+      const pluginJson = path.join(cacheDir, e, '.claude-plugin', 'plugin.json');
+      return fs.existsSync(pluginJson);
+    });
+    if (entries.length > 0) {
+      // Return a synthetic root where plugins/ is the cache dir
+      // We need to restructure: cache has ~/.agentsys/plugins/<name>/
+      // but discovery expects <root>/plugins/<name>/
+      // The cache dir IS the plugins dir, so root is its parent
+      return path.join(cacheDir, '..');
+    }
+  }
+  // Fallback to bundled
+  return PACKAGE_DIR;
+}
+
+/**
+ * Fetch all requested plugins (with dependency resolution) to the cache.
+ *
+ * @param {string[]} pluginNames - Plugins to fetch (empty = all)
+ * @param {Object} marketplace - Parsed marketplace.json
+ * @returns {Promise<string[]>} Names of fetched plugins
+ */
+async function fetchExternalPlugins(pluginNames, marketplace) {
+  const pluginMap = {};
+  for (const p of marketplace.plugins) {
+    pluginMap[p.name] = p;
+  }
+
+  // Determine which plugins to fetch
+  let toFetch;
+  if (pluginNames.length > 0) {
+    toFetch = resolvePluginDeps(pluginNames, marketplace);
+  } else {
+    toFetch = marketplace.plugins.map(p => p.name);
+  }
+
+  console.log(`\nFetching ${toFetch.length} plugin(s): ${toFetch.join(', ')}\n`);
+
+  const fetched = [];
+  const failed = [];
+  for (const name of toFetch) {
+    const plugin = pluginMap[name];
+    if (!plugin) continue;
+
+    const source = resolvePluginSource(plugin.source);
+
+    // Local/bundled plugin, no external fetch needed
+    if (!source || source.type === 'local') {
+      // Bundled plugin, no fetch needed
+      fetched.push(name);
+      continue;
+    }
+
+    try {
+      await fetchPlugin(name, source.value, plugin.version);
+      fetched.push(name);
+    } catch (err) {
+      failed.push(name);
+      console.error(`  [ERROR] Failed to fetch ${name}: ${err.message}`);
+    }
+  }
+
+  if (failed.length > 0) {
+    const missingDeps = failed.filter(f => toFetch.includes(f) && !pluginNames.includes(f));
+    if (missingDeps.length > 0) {
+      console.error(`\n  [WARN] Missing dependencies: ${missingDeps.join(', ')}`);
+      console.error(`  Some plugins may not work correctly without their dependencies.`);
+    }
+
+    throw new Error(`Failed to fetch ${failed.length} plugin(s): ${failed.join(', ')}`);
+  }
+
+  return fetched;
+}
+
+/**
+ * List installed plugins and their components.
+ * @param {string} [filter] - 'all', 'plugins', 'agents', 'skills', 'commands', 'hooks', or null (default: plugins summary)
+ */
+function listInstalledPlugins(filter) {
+  const cacheDir = getPluginCacheDir();
+  const installed = loadInstalledJson();
+  const showAll = filter === 'all' || filter === '--all';
+  const showPlugins = !filter || filter === 'plugins' || filter === '--plugins' || showAll;
+  const showAgents = filter === 'agents' || filter === '--agents' || showAll;
+  const showSkills = filter === 'skills' || filter === '--skills' || showAll;
+  const showCommands = filter === 'commands' || filter === '--commands' || showAll;
+  const showHooks = filter === 'hooks' || filter === '--hooks' || showAll;
+
+  console.log(`\nagentsys v${VERSION}\n`);
+
+  // Gather all cached plugins
+  const plugins = [];
+  if (fs.existsSync(cacheDir)) {
+    const entries = fs.readdirSync(cacheDir).filter(e => {
+      return fs.statSync(path.join(cacheDir, e)).isDirectory();
+    }).sort();
+    for (const name of entries) {
+      const pluginDir = path.join(cacheDir, name);
+      const versionFile = path.join(pluginDir, '.version');
+      const ver = fs.existsSync(versionFile) ? fs.readFileSync(versionFile, 'utf8').trim() : 'unknown';
+      const components = loadComponents(pluginDir);
+      const entry = installed.plugins[name] || {};
+      const hooksFile = path.join(pluginDir, 'hooks', 'hooks.json');
+      const hasHooks = fs.existsSync(hooksFile);
+      plugins.push({ name, version: ver, components, entry, hasHooks, dir: pluginDir });
+    }
+  }
+
+  if (plugins.length === 0) {
+    console.log('No plugins installed. Run: agentsys install <plugin>\n');
+    return;
+  }
+
+  if (showPlugins && !showAll) {
+    // Default view: plugin summary
+    console.log('PLUGINS');
+    for (const p of plugins) {
+      const scope = p.entry.scope || 'full';
+      const scopeTag = scope === 'partial' ? '[partial]' : '[full]';
+      const platforms = p.entry.platforms ? p.entry.platforms.join(', ') : '';
+      const counts = [];
+      if (p.components.agents.length) counts.push(`${p.components.agents.length} agents`);
+      if (p.components.skills.length) counts.push(`${p.components.skills.length} skills`);
+      if (p.components.commands.length) counts.push(`${p.components.commands.length} cmds`);
+      if (p.hasHooks) counts.push('hooks');
+      console.log(`  ${p.name.padEnd(18)} ${p.version.padEnd(10)} ${scopeTag.padEnd(10)} ${counts.join(', ')}  ${platforms}`);
+    }
+    console.log();
+    console.log(`  ${plugins.length} plugins. Use --all, --agents, --skills, --commands, --hooks for details.`);
+    console.log();
+    return;
+  }
+
+  if (showAll || showPlugins) {
+    console.log('PLUGINS');
+    for (const p of plugins) {
+      const scope = p.entry.scope || 'full';
+      const scopeTag = scope === 'partial' ? '[partial]' : '[full]';
+      console.log(`  ${p.name}@${p.version}  ${scopeTag}`);
+    }
+    console.log();
+  }
+
+  if (showAgents) {
+    console.log('AGENTS');
+    let total = 0;
+    for (const p of plugins) {
+      for (const a of p.components.agents) {
+        console.log(`  ${p.name}:${a.name.padEnd(28)} ${(a.model || '').padEnd(8)} ${a.description || ''}`);
+        total++;
+      }
+    }
+    if (total === 0) console.log('  (none)');
+    console.log();
+  }
+
+  if (showSkills) {
+    console.log('SKILLS');
+    let total = 0;
+    for (const p of plugins) {
+      for (const s of p.components.skills) {
+        console.log(`  ${p.name}:${s.name.padEnd(28)} ${s.description || ''}`);
+        total++;
+      }
+    }
+    if (total === 0) console.log('  (none)');
+    console.log();
+  }
+
+  if (showCommands) {
+    console.log('COMMANDS');
+    let total = 0;
+    for (const p of plugins) {
+      for (const c of p.components.commands) {
+        console.log(`  /${c.name.padEnd(29)} ${c.description || ''}`);
+        total++;
+      }
+    }
+    if (total === 0) console.log('  (none)');
+    console.log();
+  }
+
+  if (showHooks) {
+    console.log('HOOKS');
+    let total = 0;
+    for (const p of plugins) {
+      if (p.hasHooks) {
+        try {
+          const hooks = JSON.parse(fs.readFileSync(path.join(p.dir, 'hooks', 'hooks.json'), 'utf8'));
+          const hookList = Array.isArray(hooks) ? hooks : (hooks.hooks || []);
+          for (const h of hookList) {
+            const event = h.event || h.matcher || 'unknown';
+            console.log(`  ${p.name}:${String(event).padEnd(28)} ${h.description || ''}`);
+            total++;
+          }
+        } catch { /* skip malformed hooks */ }
+      }
+    }
+    if (total === 0) console.log('  (none)');
+    console.log();
+  }
+}
+
+/**
+ * Re-fetch all installed external plugins (update to latest versions).
+ */
+async function updatePlugins() {
+  console.log(`\nagentsys v${VERSION} - Updating plugins\n`);
+
+  const marketplace = loadMarketplace();
+  const cacheDir = getPluginCacheDir();
+
+  if (!fs.existsSync(cacheDir)) {
+    console.log('No cached plugins found. Run agentsys to install first.');
+    return;
+  }
+
+  // Get currently installed external plugins
+  const installed = fs.readdirSync(cacheDir).filter(e => {
+    return fs.statSync(path.join(cacheDir, e)).isDirectory();
+  });
+
+  if (installed.length === 0) {
+    console.log('No external plugins installed.');
+    return;
+  }
+
+  // Force re-fetch by removing version files
+  for (const name of installed) {
+    const versionFile = path.join(cacheDir, name, '.version');
+    if (fs.existsSync(versionFile)) {
+      fs.unlinkSync(versionFile);
+    }
+  }
+
+  await fetchExternalPlugins(installed, marketplace);
+  console.log('\n[OK] Plugins updated.');
+}
+
+// --- installed.json manifest ---
+
+function getInstalledJsonPath() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  return path.join(home, '.agentsys', 'installed.json');
+}
+
+function loadInstalledJson() {
+  const p = getInstalledJsonPath();
+  if (fs.existsSync(p)) {
+    try {
+      return JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch {
+      return { plugins: {} };
+    }
+  }
+  return { plugins: {} };
+}
+
+function saveInstalledJson(data) {
+  const p = getInstalledJsonPath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + '\n');
+}
+
+function recordInstall(name, version, platforms, granular) {
+  const data = loadInstalledJson();
+  const entry = {
+    version,
+    installedAt: new Date().toISOString(),
+    platforms,
+    scope: 'full'
+  };
+  if (granular && granular.scope === 'partial') {
+    entry.scope = 'partial';
+    entry.agents = granular.agents || [];
+    entry.skills = granular.skills || [];
+    entry.commands = granular.commands || [];
+  }
+  data.plugins[name] = entry;
+  saveInstalledJson(data);
+}
+
+function recordRemove(name) {
+  const data = loadInstalledJson();
+  delete data.plugins[name];
+  saveInstalledJson(data);
+}
+
+// --- Core version compatibility check ---
+
+/**
+ * Simple semver range check. Supports ">=X.Y.Z" format.
+ * Returns true if ver satisfies the range.
+ */
+function satisfiesRange(ver, range) {
+  if (!range) return true;
+  const parseVer = (s) => {
+    const m = s.match(/^(\d+)\.(\d+)\.(\d+)/);
+    return m ? [parseInt(m[1]), parseInt(m[2]), parseInt(m[3])] : null;
+  };
+
+  const greaterEq = range.match(/^>=(.+)$/);
+  if (greaterEq) {
+    const required = parseVer(greaterEq[1]);
+    const actual = parseVer(ver);
+    if (!required || !actual) return true;
+    for (let i = 0; i < 3; i++) {
+      if (actual[i] > required[i]) return true;
+      if (actual[i] < required[i]) return false;
+    }
+    return true; // equal
+  }
+  return true; // unknown range format, don't block
+}
+
+function checkCoreCompat(pluginEntry) {
+  // Core version compat check removed - field deprecated in schema
+}
+
+// --- Granular install helpers ---
+
+/**
+ * Parse "plugin:component" install target format.
+ * @param {string} arg - e.g. "next-task:ci-fixer" or "next-task" or "next-task@1.0.0"
+ * @returns {{ plugin: string, component: string|null, version: string|null }}
+ */
+function parseInstallTarget(arg) {
+  if (!arg || typeof arg !== 'string') {
+    return { plugin: null, component: null, version: null };
+  }
+
+  let plugin = arg;
+  let component = null;
+  let version = null;
+
+  // Check for colon (component separator) before @ (version separator)
+  const colonIdx = plugin.indexOf(':');
+  if (colonIdx > 0) {
+    component = plugin.slice(colonIdx + 1) || null;
+    plugin = plugin.slice(0, colonIdx);
+  }
+
+  // Check for @version on the plugin part
+  const atIdx = plugin.indexOf('@');
+  if (atIdx > 0) {
+    version = plugin.slice(atIdx + 1) || null;
+    plugin = plugin.slice(0, atIdx);
+  }
+
+  return { plugin: plugin || null, component, version };
+}
+
+/**
+ * Load components.json from a cached plugin directory.
+ * @param {string} pluginDir - Path to the cached plugin directory
+ * @returns {{ agents: Array, skills: Array, commands: Array }}
+ */
+function loadComponents(pluginDir) {
+  const componentsPath = path.join(pluginDir, 'components.json');
+  if (fs.existsSync(componentsPath)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(componentsPath, 'utf8'));
+      const normalize = (arr) => (arr || []).map(item =>
+        typeof item === 'string' ? { name: item } : item
+      );
+      return {
+        agents: normalize(data.agents),
+        skills: normalize(data.skills),
+        commands: normalize(data.commands)
+      };
+    } catch {
+      // Fall through to filesystem scan
+    }
+  }
+
+  // Fallback: scan filesystem
+  const components = { agents: [], skills: [], commands: [] };
+
+  const agentsDir = path.join(pluginDir, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    const files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+    for (const f of files) {
+      components.agents.push({ name: f.replace(/\.md$/, ''), file: `agents/${f}` });
+    }
+  }
+
+  const skillsDir = path.join(pluginDir, 'skills');
+  if (fs.existsSync(skillsDir)) {
+    const dirs = fs.readdirSync(skillsDir, { withFileTypes: true }).filter(d => d.isDirectory());
+    for (const d of dirs) {
+      if (fs.existsSync(path.join(skillsDir, d.name, 'SKILL.md'))) {
+        components.skills.push({ name: d.name, dir: `skills/${d.name}` });
+      }
+    }
+  }
+
+  const commandsDir = path.join(pluginDir, 'commands');
+  if (fs.existsSync(commandsDir)) {
+    const files = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+    for (const f of files) {
+      components.commands.push({ name: f.replace(/\.md$/, ''), file: `commands/${f}` });
+    }
+  }
+
+  return components;
+}
+
+/**
+ * Resolve which type a component belongs to.
+ * @param {{ agents: Array, skills: Array, commands: Array }} components
+ * @param {string} name - Component name to find
+ * @returns {{ type: string, name: string, file?: string, dir?: string }|null}
+ */
+function resolveComponent(components, name) {
+  if (!name || !components) return null;
+
+  for (const agent of components.agents) {
+    if (agent.name === name) return { type: 'agent', name: agent.name, file: agent.file };
+  }
+  for (const skill of components.skills) {
+    if (skill.name === name) return { type: 'skill', name: skill.name, dir: skill.dir };
+  }
+  for (const cmd of components.commands) {
+    if (cmd.name === name) return { type: 'command', name: cmd.name, file: cmd.file };
+  }
+  return null;
+}
+
+/**
+ * Build a filter object from a resolved component.
+ * @param {{ type: string, name: string }} resolved
+ * @returns {{ agents: string[], skills: string[], commands: string[] }}
+ */
+function buildFilterFromComponent(resolved) {
+  const filter = { agents: [], skills: [], commands: [] };
+  if (resolved.type === 'agent') filter.agents.push(resolved.name);
+  else if (resolved.type === 'skill') filter.skills.push(resolved.name);
+  else if (resolved.type === 'command') filter.commands.push(resolved.name);
+  return filter;
+}
+
+// --- Detect which platforms are installed ---
+
+function detectInstalledPlatforms() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  const platforms = [];
+  if (fs.existsSync(path.join(home, '.claude'))) platforms.push('claude');
+  const opencodeDir = getOpenCodeConfigDir();
+  if (fs.existsSync(opencodeDir)) platforms.push('opencode');
+  if (fs.existsSync(path.join(home, '.codex'))) platforms.push('codex');
+  // Cursor rules are project-scoped; detect only if Cursor rules/commands/skills exist in CWD
+  const cursorDir = path.join(process.cwd(), '.cursor');
+  if (fs.existsSync(path.join(cursorDir, 'rules')) || fs.existsSync(path.join(cursorDir, 'commands')) || fs.existsSync(path.join(cursorDir, 'skills'))) platforms.push('cursor');
+  return platforms;
+}
+
+// --- install subcommand ---
+
+async function installPlugin(nameWithVersion, args) {
+  // Parse plugin:component and name[@version]
+  const target = parseInstallTarget(nameWithVersion);
+  let name = target.plugin;
+  let requestedVersion = target.version;
+  const componentName = target.component;
+
+  // Legacy fallback: handle plain name@version (parseInstallTarget already handles this)
+  if (!name) {
+    console.error('[ERROR] Usage: agentsys install <plugin[:component][@version]>');
+    process.exit(1);
+  }
+
+  const marketplace = loadMarketplace();
+  const pluginMap = {};
+  for (const p of marketplace.plugins) {
+    pluginMap[p.name] = p;
+  }
+
+  if (!pluginMap[name]) {
+    console.error(`[ERROR] Unknown plugin: ${name}`);
+    console.error(`Available: ${marketplace.plugins.map(p => p.name).join(', ')}`);
+    process.exit(1);
+  }
+
+  const plugin = pluginMap[name];
+  checkCoreCompat(plugin);
+
+  // Resolve deps
+  const toFetch = resolvePluginDeps([name], marketplace);
+  console.log(`\nInstalling ${name} (+ deps: ${toFetch.filter(n => n !== name).join(', ') || 'none'})\n`);
+
+  // Fetch all
+  for (const depName of toFetch) {
+    const dep = pluginMap[depName];
+    if (!dep) continue;
+
+    const source = resolvePluginSource(dep.source);
+    if (!source || source.type === 'local') continue;
+
+    checkCoreCompat(dep);
+    const ver = depName === name && requestedVersion ? requestedVersion : dep.version;
+    try {
+      await fetchPlugin(depName, source.value, ver);
+    } catch (err) {
+      console.error(`  [ERROR] Failed to fetch ${depName}: ${err.message}`);
+    }
+  }
+
+  // Determine platforms
+  let platforms;
+  if (args.tool) {
+    platforms = [args.tool];
+  } else if (args.tools.length > 0) {
+    platforms = args.tools;
+  } else {
+    platforms = detectInstalledPlatforms();
+    if (platforms.length === 0) platforms = ['claude']; // default
+  }
+
+  console.log(`Installing for platforms: ${platforms.join(', ')}`);
+
+  // Resolve component filter if a specific component was requested
+  let filter = null;
+  if (componentName) {
+    const cacheDir = getPluginCacheDir();
+    const pluginDir = path.join(cacheDir, name);
+    if (!fs.existsSync(pluginDir)) {
+      console.error(`[ERROR] Plugin ${name} not found in cache after fetch.`);
+      process.exit(1);
+    }
+    const components = loadComponents(pluginDir);
+    const resolved = resolveComponent(components, componentName);
+    if (!resolved) {
+      const allNames = [
+        ...components.agents.map(a => a.name),
+        ...components.skills.map(s => s.name),
+        ...components.commands.map(c => c.name)
+      ];
+      console.error(`[ERROR] Component "${componentName}" not found in plugin ${name}.`);
+      if (allNames.length > 0) {
+        console.error(`Available components: ${allNames.join(', ')}`);
+      }
+      process.exit(1);
+    }
+    filter = buildFilterFromComponent(resolved);
+    console.log(`  Installing ${resolved.type}: ${resolved.name}`);
+  }
+
+  // Use cache as install source
+  const installDir = getInstallDir();
+  const needsLocal = platforms.includes('opencode') || platforms.includes('codex') || platforms.includes('cursor');
+  if (needsLocal && !fs.existsSync(path.join(installDir, 'lib'))) {
+    // Need local install for transforms
+    cleanOldInstallation(installDir);
+    copyFromPackage(installDir);
+  }
+
+  for (const platform of platforms) {
+    if (platform === 'claude') {
+      if (filter) {
+        console.log('  [NOTE] Claude Code installs whole plugins (granular not supported). Installing full plugin.');
+      }
+      // Claude uses marketplace install
+      if (commandExists('claude')) {
+        try { execSync('claude plugin marketplace add agent-sh/agentsys', { stdio: 'pipe' }); } catch {}
+        for (const depName of toFetch) {
+          if (!/^[a-z0-9][a-z0-9-]*$/.test(depName)) continue;
+          try {
+            execSync(`claude plugin install ${depName}@agentsys`, { stdio: 'pipe' });
+          } catch {
+            try { execSync(`claude plugin update ${depName}@agentsys`, { stdio: 'pipe' }); } catch {}
+          }
+        }
+      }
+    }
+    // OpenCode and Codex get handled through normal install flow with cached plugins
+  }
+
+  if (platforms.includes('opencode') && installDir) {
+    installForOpenCode(installDir, { stripModels: args.stripModels, filter });
+  }
+  if (platforms.includes('codex') && installDir) {
+    installForCodex(installDir, { filter });
+  }
+  if (platforms.includes('cursor') && installDir) {
+    installForCursor(installDir, { filter });
+  }
+
+  // Record in installed.json
+  for (const depName of toFetch) {
+    const dep = pluginMap[depName];
+    const ver = depName === name && requestedVersion ? requestedVersion : (dep ? dep.version : 'unknown');
+    if (depName === name && filter) {
+      recordInstall(depName, ver, platforms, {
+        scope: 'partial',
+        agents: filter.agents,
+        skills: filter.skills,
+        commands: filter.commands
+      });
+    } else {
+      recordInstall(depName, ver, platforms);
+    }
+  }
+
+  console.log(`\n[OK] Installed ${name} successfully.`);
+}
+
+// --- remove subcommand ---
+
+function removePlugin(name) {
+  const installed = loadInstalledJson();
+
+  if (!installed.plugins[name]) {
+    console.error(`[ERROR] Plugin ${name} is not installed.`);
+    process.exit(1);
+  }
+
+  const platforms = installed.plugins[name].platforms || [];
+
+  // Remove from cache
+  const cacheDir = getPluginCacheDir();
+  const pluginCacheDir = path.join(cacheDir, name);
+  if (fs.existsSync(pluginCacheDir)) {
+    fs.rmSync(pluginCacheDir, { recursive: true, force: true });
+    console.log(`  Removed from cache: ${name}`);
+  }
+
+  // Remove from platforms
+  if (platforms.includes('claude') && commandExists('claude')) {
+    try {
+      execSync(`claude plugin uninstall ${name}@agentsys`, { stdio: 'pipe' });
+      console.log(`  Removed from Claude Code: ${name}`);
+    } catch {}
+  }
+
+  if (platforms.includes('opencode')) {
+    const opencodeDir = getOpenCodeConfigDir();
+    console.log(`  [NOTE] OpenCode files may need manual cleanup in ${opencodeDir}`);
+  }
+
+  if (platforms.includes('codex')) {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    const skillsDir = path.join(home, '.codex', 'skills');
+    console.log(`  [NOTE] Codex skill files may need manual cleanup in ${skillsDir}`);
+  }
+
+  // Update installed.json
+  recordRemove(name);
+  console.log(`\n[OK] Removed ${name}.`);
+}
+
+// --- search subcommand ---
+
+function searchPlugins(term) {
+  const marketplace = loadMarketplace();
+
+  // Handle "plugin:" prefix to list components of a specific plugin
+  if (term && term.endsWith(':')) {
+    const pluginName = term.slice(0, -1);
+    const cacheDir = getPluginCacheDir();
+    const pluginDir = path.join(cacheDir, pluginName);
+    if (!fs.existsSync(pluginDir)) {
+      console.log(`Plugin "${pluginName}" is not cached. Install it first: agentsys install ${pluginName}`);
+      return;
+    }
+    const components = loadComponents(pluginDir);
+    console.log(`\nComponents of ${pluginName}:\n`);
+    if (components.agents.length > 0) {
+      console.log('  Agents:');
+      for (const a of components.agents) {
+        const desc = a.description ? ` - ${a.description}` : '';
+        console.log(`    ${a.name}${desc}`);
+      }
+    }
+    if (components.skills.length > 0) {
+      console.log('  Skills:');
+      for (const s of components.skills) {
+        const desc = s.description ? ` - ${s.description}` : '';
+        console.log(`    ${s.name}${desc}`);
+      }
+    }
+    if (components.commands.length > 0) {
+      console.log('  Commands:');
+      for (const c of components.commands) {
+        const desc = c.description ? ` - ${c.description}` : '';
+        console.log(`    ${c.name}${desc}`);
+      }
+    }
+    const total = components.agents.length + components.skills.length + components.commands.length;
+    console.log(`\n${total} component(s) found.`);
+    return;
+  }
+
+  let plugins = marketplace.plugins;
+
+  if (term) {
+    const lower = term.toLowerCase();
+    plugins = plugins.filter(p =>
+      p.name.toLowerCase().includes(lower) ||
+      (p.description && p.description.toLowerCase().includes(lower))
+    );
+  }
+
+  if (plugins.length === 0) {
+    console.log(`No plugins found${term ? ` matching "${term}"` : ''}.`);
+    return;
+  }
+
+  // Print table
+  const nameWidth = Math.max(14, ...plugins.map(p => p.name.length)) + 2;
+  const verWidth = 10;
+  console.log(`\n${'NAME'.padEnd(nameWidth)}${'VERSION'.padEnd(verWidth)}DESCRIPTION`);
+  console.log(`${'─'.repeat(nameWidth)}${'─'.repeat(verWidth)}${'─'.repeat(40)}`);
+  for (const p of plugins) {
+    const desc = p.description ? (p.description.length > 60 ? p.description.slice(0, 57) + '...' : p.description) : '';
+    console.log(`${p.name.padEnd(nameWidth)}${(p.version || '').padEnd(verWidth)}${desc}`);
+  }
+  console.log(`\n${plugins.length} plugin(s) found.`);
+}
+
 function installForClaude() {
   console.log('\n[INSTALL] Installing for Claude Code...\n');
 
@@ -198,7 +1222,7 @@ function installForClaude() {
     console.log('[WARN]  Claude Code CLI not detected.');
     console.log('   Install it first: https://claude.ai/code\n');
     console.log('   Then run in Claude Code:');
-    console.log('   /plugin marketplace add avifenesh/agentsys');
+    console.log('   /plugin marketplace add agent-sh/agentsys');
     console.log('   /plugin install next-task@agentsys\n');
     return false;
   }
@@ -207,7 +1231,7 @@ function installForClaude() {
     // Add GitHub marketplace
     console.log('Adding marketplace...');
     try {
-      execSync('claude plugin marketplace add avifenesh/agentsys', { stdio: 'pipe' });
+      execSync('claude plugin marketplace add agent-sh/agentsys', { stdio: 'pipe' });
     } catch {
       // May already exist
     }
@@ -249,7 +1273,7 @@ function installForClaude() {
     return true;
   } catch (err) {
     console.log('[ERROR] Auto-install failed. Manual installation:');
-    console.log('   /plugin marketplace add avifenesh/agentsys');
+    console.log('   /plugin marketplace add agent-sh/agentsys');
     console.log('   /plugin install next-task@agentsys');
     return false;
   }
@@ -270,7 +1294,7 @@ function installForClaudeDevelopment() {
   // Remove marketplace plugins first
   console.log('Removing marketplace plugins...');
   try {
-    execSync('claude plugin marketplace remove avifenesh/agentsys', { stdio: 'pipe' });
+    execSync('claude plugin marketplace remove agent-sh/agentsys', { stdio: 'pipe' });
     console.log('  [OK] Removed marketplace');
   } catch {
     // May not exist
@@ -328,7 +1352,7 @@ function installForClaudeDevelopment() {
 
 function installForOpenCode(installDir, options = {}) {
   console.log('\n[INSTALL] Installing for OpenCode...\n');
-  const { stripModels = true } = options;
+  const { stripModels = true, filter = null } = options;
 
   if (stripModels) {
     console.log('  [INFO] Model specifications stripped (default). Use --no-strip to include.');
@@ -389,6 +1413,11 @@ function installForOpenCode(installDir, options = {}) {
 
   // Transform and copy command files
   for (const [target, plugin, source] of commandMappings) {
+    // Apply filter: skip commands not in the filter list
+    if (filter && filter.commands.length > 0) {
+      const cmdName = target.replace(/\.md$/, '');
+      if (!filter.commands.includes(cmdName)) continue;
+    }
     const srcPath = path.join(installDir, 'plugins', plugin, 'commands', source);
     const destPath = path.join(commandsDir, target);
     if (fs.existsSync(srcPath)) {
@@ -420,6 +1449,11 @@ function installForOpenCode(installDir, options = {}) {
     if (fs.existsSync(srcAgentsDir)) {
       const agentFiles = fs.readdirSync(srcAgentsDir).filter(f => f.endsWith('.md'));
       for (const agentFile of agentFiles) {
+        // Apply filter: skip agents not in the filter list
+        if (filter && filter.agents.length > 0) {
+          const agentName = agentFile.replace(/\.md$/, '');
+          if (!filter.agents.includes(agentName)) continue;
+        }
         const srcPath = path.join(srcAgentsDir, agentFile);
         const destPath = path.join(agentsDir, agentFile);
         let content = fs.readFileSync(srcPath, 'utf8');
@@ -457,6 +1491,10 @@ function installForOpenCode(installDir, options = {}) {
         .filter(d => d.isDirectory());
       for (const skillDir of skillDirs) {
         const skillName = skillDir.name;
+        // Apply filter: skip skills not in the filter list
+        if (filter && filter.skills.length > 0) {
+          if (!filter.skills.includes(skillName)) continue;
+        }
         const srcSkillPath = path.join(srcSkillsDir, skillName, 'SKILL.md');
         if (fs.existsSync(srcSkillPath)) {
           const destSkillDir = path.join(skillsDestDir, skillName);
@@ -480,8 +1518,9 @@ function installForOpenCode(installDir, options = {}) {
   return true;
 }
 
-function installForCodex(installDir) {
+function installForCodex(installDir, options = {}) {
   console.log('\n[INSTALL] Installing for Codex CLI...\n');
+  const { filter = null } = options;
 
   const home = process.env.HOME || process.env.USERPROFILE;
   const configDir = path.join(home, '.codex');
@@ -519,6 +1558,10 @@ function installForCodex(installDir) {
   const skillMappings = discovery.getCodexSkillMappings(installDir);
 
   for (const [skillName, plugin, sourceFile, description] of skillMappings) {
+    // Apply filter: skip commands/skills not in the filter list
+    if (filter && filter.commands.length > 0) {
+      if (!filter.commands.includes(skillName)) continue;
+    }
     if (!description) {
       console.log(`  [WARN] Skipping skill ${skillName}: missing description`);
       continue;
@@ -555,6 +1598,101 @@ function installForCodex(installDir) {
   return true;
 }
 
+function installForCursor(installDir, options = {}) {
+  console.log('\n[INSTALL] Installing for Cursor...\n');
+  const { filter = null } = options;
+  const cwd = process.cwd();
+
+  // Create target directories (all project-scoped)
+  const skillsDir = path.join(cwd, '.cursor', 'skills');
+  const commandsDir = path.join(cwd, '.cursor', 'commands');
+  const rulesDir = path.join(cwd, '.cursor', 'rules');
+  fs.mkdirSync(skillsDir, { recursive: true });
+  fs.mkdirSync(commandsDir, { recursive: true });
+  fs.mkdirSync(rulesDir, { recursive: true });
+
+  // Cleanup old agentsys files from rules dir
+  for (const f of fs.readdirSync(rulesDir).filter(f => f.startsWith('agentsys-') && f.endsWith('.mdc'))) {
+    fs.unlinkSync(path.join(rulesDir, f));
+  }
+
+  // Cleanup old agentsys files from commands dir (only those matching known commands)
+  const commandMappingsForCleanup = discovery.getCommandMappings(installDir);
+  const knownCommandFiles = new Set(commandMappingsForCleanup.map(([target]) => target));
+  for (const f of fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'))) {
+    if (knownCommandFiles.has(f)) {
+      fs.unlinkSync(path.join(commandsDir, f));
+    }
+  }
+
+  // Collect known skill names from discovery before cleanup
+  const pluginDirs = discovery.discoverPlugins(installDir);
+  const knownSkillNames = new Set();
+  for (const pluginName of pluginDirs) {
+    const srcSkillsDir = path.join(installDir, 'plugins', pluginName, 'skills');
+    if (!fs.existsSync(srcSkillsDir)) continue;
+    for (const d of fs.readdirSync(srcSkillsDir, { withFileTypes: true })) {
+      if (d.isDirectory() && /^[a-zA-Z0-9_-]+$/.test(d.name)) knownSkillNames.add(d.name);
+    }
+  }
+
+  // Cleanup old agentsys skill dirs (only known names, preserve user-created skills)
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (entry.isDirectory() && knownSkillNames.has(entry.name)) {
+      fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
+    }
+  }
+
+  // Install skills
+  let skillCount = 0;
+  for (const pluginName of pluginDirs) {
+    const srcSkillsDir = path.join(installDir, 'plugins', pluginName, 'skills');
+    if (!fs.existsSync(srcSkillsDir)) continue;
+    const entries = fs.readdirSync(srcSkillsDir, { withFileTypes: true }).filter(d => d.isDirectory());
+    for (const entry of entries) {
+      if (!/^[a-zA-Z0-9_-]+$/.test(entry.name)) continue;
+      if (filter && filter.skills && filter.skills.length > 0 && !filter.skills.includes(entry.name)) continue;
+      const srcPath = path.join(srcSkillsDir, entry.name, 'SKILL.md');
+      if (!fs.existsSync(srcPath)) continue;
+      const destDir = path.join(skillsDir, entry.name);
+      fs.mkdirSync(destDir, { recursive: true });
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = transforms.transformSkillForCursor(content, {
+        pluginInstallPath: path.join(installDir, 'plugins', pluginName)
+      });
+      fs.writeFileSync(path.join(destDir, 'SKILL.md'), content);
+      skillCount++;
+    }
+  }
+
+  // Install commands
+  const commandMappings = discovery.getCommandMappings(installDir);
+  let cmdCount = 0;
+  for (const [target, plugin, source] of commandMappings) {
+    if (filter && filter.commands && filter.commands.length > 0) {
+      const cmdName = target.replace(/\.md$/, '');
+      if (!filter.commands.includes(cmdName)) continue;
+    }
+    const srcPath = path.join(installDir, 'plugins', plugin, 'commands', source);
+    if (!fs.existsSync(srcPath)) {
+      console.log(`  [WARN] Source file not found: ${srcPath}`);
+      continue;
+    }
+    let content = fs.readFileSync(srcPath, 'utf8');
+    content = transforms.transformCommandForCursor(content, {
+      pluginInstallPath: path.join(installDir, 'plugins', plugin)
+    });
+    fs.writeFileSync(path.join(commandsDir, target), content);
+    cmdCount++;
+  }
+
+  console.log(`\n[OK] Cursor installation complete!`);
+  console.log(`   Skills: ${skillCount} installed to ${skillsDir}`);
+  console.log(`   Commands: ${cmdCount} installed to ${commandsDir}`);
+  console.log('   All content is project-scoped and auto-loaded by Cursor.\n');
+  return true;
+}
+
 function removeInstallation() {
   const installDir = getInstallDir();
 
@@ -571,6 +1709,113 @@ function removeInstallation() {
   console.log('  - Claude: /plugin marketplace remove agentsys');
   console.log('  - OpenCode: Remove files under ~/.config/opencode/ (commands/*.md, agents/*.md, skills/*/SKILL.md) and ~/.config/opencode/plugins/agentsys.ts');
   console.log('  - Codex: Remove ~/.codex/skills/*/');
+  console.log('  - Cursor: Remove .cursor/skills/, .cursor/commands/, and .cursor/rules/agentsys-*.mdc from your project');
+}
+
+function printSubcommandHelp(subcommand) {
+  const helps = {
+    install: `
+agentsys install — Install plugins and components
+
+Usage:
+  agentsys install <plugin>              Install a full plugin (all agents, skills, commands)
+  agentsys install <plugin>:<component>  Install a single agent, skill, or command
+  agentsys install <plugin>@<version>    Install a specific version
+
+Examples:
+  agentsys install next-task             Install next-task + dependencies (deslop, ship, sync-docs)
+  agentsys install next-task:ci-fixer    Install just the ci-fixer agent
+  agentsys install deslop:deslop         Install just the deslop skill
+  agentsys install enhance:enhance-docs  Install just the enhance-docs skill
+  agentsys install perf@1.2.0            Install perf at version 1.2.0
+
+Options:
+  --tool <name>     Install for a specific platform (claude, opencode, codex, cursor)
+  --tools <list>    Install for multiple platforms (comma-separated)
+
+Notes:
+  - Dependencies are resolved automatically (e.g., deslop requires next-task)
+  - The full plugin is cached locally; granular install only affects what gets
+    copied to platform directories (OpenCode, Codex)
+  - Claude Code always installs whole plugins (platform limitation)
+  - Use "agentsys search <plugin>:" to list available components
+`,
+    list: `
+agentsys list — List installed plugins and components
+
+Usage:
+  agentsys list               Plugin summary (name, version, scope, counts)
+  agentsys list --all         Show everything (plugins, agents, skills, commands, hooks)
+  agentsys list --plugins     Show plugins with version and scope
+  agentsys list --agents      Show all agents across all installed plugins
+  agentsys list --skills      Show all skills across all installed plugins
+  agentsys list --commands    Show all commands (slash commands)
+  agentsys list --hooks       Show all hooks
+
+Output format:
+  AGENTS
+    plugin:agent-name          model    description
+  SKILLS
+    plugin:skill-name          description
+  COMMANDS
+    /command-name              description
+  HOOKS
+    plugin:event               description
+
+Scope tags:
+  [full]     All components of the plugin are installed
+  [partial]  Only selected components are installed
+`,
+    search: `
+agentsys search — Search available plugins and components
+
+Usage:
+  agentsys search              List all available plugins
+  agentsys search <term>       Filter plugins by name or description
+  agentsys search <plugin>:    List all components (agents, skills, commands) of a plugin
+
+Examples:
+  agentsys search              Show all 13 plugins
+  agentsys search perf         Find plugins matching "perf"
+  agentsys search next-task:   Show next-task's 10 agents, 3 skills, 2 commands
+  agentsys search :ci-fixer    Search all plugins for "ci-fixer"
+
+Output:
+  NAME          VERSION  DESCRIPTION
+  next-task     1.0.0    Master workflow orchestrator
+  deslop        1.0.0    Clean AI slop from code
+`,
+    remove: `
+agentsys remove — Remove an installed plugin
+
+Usage:
+  agentsys remove <plugin>     Remove plugin from cache and platform directories
+
+Notes:
+  - Warns if another installed plugin depends on the one being removed
+  - Claude Code: runs "claude plugin uninstall <plugin>@agentsys"
+  - OpenCode/Codex: notes manual cleanup may be needed
+  - Updates installed.json manifest
+`,
+    update: `
+agentsys update — Update installed plugins to latest versions
+
+Usage:
+  agentsys update              Re-fetch all installed plugins from GitHub
+
+Notes:
+  - Clears cached versions and re-downloads latest from each plugin's GitHub repo
+  - Only updates plugins already in the cache (~/.agentsys/plugins/)
+  - Does not change platform installations — run "agentsys" again to re-install
+`
+  };
+
+  const text = helps[subcommand];
+  if (text) {
+    console.log(text);
+  } else {
+    console.log(`No help available for "${subcommand}". Run: agentsys --help`);
+  }
 }
 
 function printHelp() {
@@ -579,19 +1824,36 @@ agentsys v${VERSION} - Workflow automation for AI coding assistants
 
 Usage:
   agentsys                    Interactive installer (select platforms)
-  agentsys --tool <name>      Install for single tool (claude, opencode, codex)
+  agentsys --tool <name>      Install for single tool (claude, opencode, codex, cursor)
   agentsys --tools <list>     Install for multiple tools (comma-separated)
+  agentsys --only <plugins>   Install only specified plugins (comma-separated, resolves deps)
   agentsys --development      Development mode: install to ~/.claude/plugins
   agentsys --no-strip, -ns    Include model specifications (stripped by default)
   agentsys --remove           Remove local installation
   agentsys --version, -v      Show version
   agentsys --help, -h         Show this help
+  agentsys install <plugin>    Install a specific plugin (resolves deps)
+  agentsys install <p>:<comp>  Install a single agent, skill, or command
+  agentsys install <p>@<ver>  Install a specific version
+  agentsys remove <plugin>    Remove an installed plugin
+  agentsys search [term]      Search available plugins
+  agentsys search <plugin>:   List components of a plugin
+  agentsys list               List installed plugins (summary)
+  agentsys list --all         List everything (plugins, agents, skills, commands, hooks)
+  agentsys list --plugins     List plugins only
+  agentsys list --agents      List all agents across plugins
+  agentsys list --skills      List all skills across plugins
+  agentsys list --commands    List all commands across plugins
+  agentsys list --hooks       List all hooks across plugins
+  agentsys update             Re-fetch latest versions of installed plugins
 
 Non-Interactive Examples:
   agentsys --tool claude              # Install for Claude Code only
   agentsys --tool opencode            # Install for OpenCode only
   agentsys --tools "claude,opencode"  # Install for both
-  agentsys --tools claude,opencode,codex  # Install for all three
+  agentsys --tools claude,opencode,codex,cursor  # Install for all
+  agentsys --only next-task           # Install next-task + its dependencies
+  agentsys --only "next-task,perf"    # Install specific plugins + deps
 
 Development Mode:
   agentsys --development      # Install plugins directly to ~/.claude/plugins
@@ -609,12 +1871,13 @@ Supported Platforms:
   claude   - Claude Code (marketplace install or development mode)
   opencode - OpenCode (local commands + native plugin)
   codex    - Codex CLI (local skills)
+  cursor   - Cursor (project-scoped .mdc rules)
 
 Install:  npm install -g agentsys && agentsys
 Update:   npm update -g agentsys && agentsys
 Remove:   npm uninstall -g agentsys && agentsys --remove
 
-Docs: https://github.com/avifenesh/agentsys
+Docs: https://github.com/agent-sh/agentsys
 `);
 }
 
@@ -639,6 +1902,46 @@ async function main() {
     return;
   }
 
+  // Handle subcommand help
+  if (args.subcommandArg === '--help') {
+    printSubcommandHelp(args.subcommand);
+    return;
+  }
+
+  // Handle subcommands
+  if (args.subcommand === 'list') {
+    listInstalledPlugins(args.subcommandArg);
+    return;
+  }
+
+  if (args.subcommand === 'update') {
+    await updatePlugins();
+    return;
+  }
+
+  if (args.subcommand === 'search') {
+    searchPlugins(args.subcommandArg);
+    return;
+  }
+
+  if (args.subcommand === 'install') {
+    if (!args.subcommandArg) {
+      console.error('[ERROR] Usage: agentsys install <plugin[@version]>');
+      process.exit(1);
+    }
+    await installPlugin(args.subcommandArg, args);
+    return;
+  }
+
+  if (args.subcommand === 'remove') {
+    if (!args.subcommandArg) {
+      console.error('[ERROR] Usage: agentsys remove <plugin>');
+      process.exit(1);
+    }
+    removePlugin(args.subcommandArg);
+    return;
+  }
+
   // Determine which tools to install
   let selected = [];
 
@@ -673,7 +1976,8 @@ async function main() {
     const options = [
       { value: 'claude', label: 'Claude Code' },
       { value: 'opencode', label: 'OpenCode' },
-      { value: 'codex', label: 'Codex CLI' }
+      { value: 'codex', label: 'Codex CLI' },
+      { value: 'cursor', label: 'Cursor' }
     ];
 
     selected = await multiSelect(
@@ -684,15 +1988,26 @@ async function main() {
     if (selected.length === 0) {
       console.log('\nNo platforms selected. Exiting.');
       console.log('\nFor Claude Code, you can also install directly:');
-      console.log('  /plugin marketplace add avifenesh/agentsys');
+      console.log('  /plugin marketplace add agent-sh/agentsys');
       process.exit(0);
     }
   }
 
   console.log(`\nInstalling for: ${selected.join(', ')}\n`);
 
-  // Only copy to ~/.agentsys if OpenCode or Codex selected (they need local files)
-  const needsLocalInstall = selected.includes('opencode') || selected.includes('codex');
+  // Fetch external plugins to cache
+  const marketplace = loadMarketplace();
+  const onlyPlugins = args.only;
+  const pluginNames = onlyPlugins.length > 0 ? onlyPlugins : marketplace.plugins.map(p => p.name);
+
+  // Check core version compatibility
+  for (const pName of pluginNames) {
+    const entry = marketplace.plugins.find(p => p.name === pName);
+    if (entry) checkCoreCompat(entry);
+  }
+
+  // Only copy to ~/.agentsys if OpenCode, Codex, or Cursor selected (they need local files)
+  const needsLocalInstall = selected.includes('opencode') || selected.includes('codex') || selected.includes('cursor');
   let installDir = null;
 
   if (needsLocalInstall) {
@@ -702,6 +2017,8 @@ async function main() {
     installDependencies(installDir);
   }
 
+  await fetchExternalPlugins(pluginNames, marketplace);
+
   // Install for each platform
   const failedPlatforms = [];
   for (const platform of selected) {
@@ -725,6 +2042,11 @@ async function main() {
           failedPlatforms.push('codex');
         }
         break;
+      case 'cursor':
+        if (!installForCursor(installDir)) {
+          failedPlatforms.push('cursor');
+        }
+        break;
     }
   }
 
@@ -739,7 +2061,7 @@ async function main() {
   }
   console.log('\nTo update:  npm update -g agentsys');
   console.log('To remove:  npm uninstall -g agentsys && agentsys --remove');
-  console.log('\nDocs: https://github.com/avifenesh/agentsys');
+  console.log('\nDocs: https://github.com/agent-sh/agentsys');
 }
 
 // Export for testing when required as module
@@ -750,4 +2072,33 @@ if (require.main === module) {
   });
 }
 
-module.exports = { parseArgs, VALID_TOOLS };
+module.exports = {
+  parseArgs,
+  VALID_TOOLS,
+  resolvePluginDeps,
+  fetchPlugin,
+  fetchExternalPlugins,
+  resolvePluginRoot,
+  loadMarketplace,
+  getPluginCacheDir,
+  listInstalledPlugins,
+  updatePlugins,
+  installPlugin,
+  removePlugin,
+  searchPlugins,
+  loadInstalledJson,
+  saveInstalledJson,
+  recordInstall,
+  recordRemove,
+  satisfiesRange,
+  checkCoreCompat,
+  detectInstalledPlatforms,
+  getInstalledJsonPath,
+  parseInstallTarget,
+  loadComponents,
+  resolveComponent,
+  buildFilterFromComponent,
+  resolvePluginSource,
+  parseGitHubSource,
+  installForCursor
+};