@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/plugins/plugins.js

@@ -1,14 +1,3 @@
-/**
- * Plugin discovery, validation, and syncing.
- *
- * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks,
- * commands, agents, workflows, bin scripts, MCP servers, and settings under a
- * single manifest (plugin.json). They are user-authored resources, sitting
- * alongside skills/, commands/, hooks/, etc. — git-tracked as source of truth.
- * This module discovers plugins, validates their manifests, and syncs their
- * contents into agent version homes. Workflows under a plugin’s workflows/
- * are resolved at run time by resolveWorkflowRef (Phase 5 packaging).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -48,15 +37,6 @@ function isPluginRootEntry(pluginsDir, entry) {
         return false;
     }
 }
-/**
- * Discover all plugins in a given plugins directory (e.g. ~/.agents/plugins/,
- * ~/.agents/.system/plugins/, <cwd>/.agents/plugins/, ~/.agents-<alias>/plugins/).
- * A valid plugin has a .claude-plugin/plugin.json manifest.
- *
- * `spec` stamps marketplace provenance onto each discovered plugin. Callers that
- * scan a single source dir without a marketplace identity (e.g. project-launch)
- * may omit it; those plugins default to the user marketplace.
- */
 export function discoverPluginsInDir(pluginsDir, spec = { kind: 'user' }) {
     if (!fs.existsSync(pluginsDir)) {
         return [];
@@ -69,14 +49,6 @@ export function discoverPluginsInDir(pluginsDir, spec = { kind: 'user' }) {
         const pluginRoot = path.join(pluginsDir, entry.name);
         const manifest = loadPluginManifest(pluginRoot);
         if (!manifest) {
-            // A directory that looks like a plugin root but has no valid manifest is
-            // silently invisible to every downstream command (list/info/sync, and the
-            // materialize-into-version-homes copy) with no other diagnostic anywhere
-            // in the chain — it can sit here indefinitely, on the correct git commit,
-            // and never surface as broken (RUSH-2270: the `work` plugin shipped
-            // without .claude-plugin/plugin.json and nothing noticed for a full merge
-            // cycle). Warn once here, at the one place that decides discoverability,
-            // so the gap is visible the moment `agents sync` runs.
             const manifestPath = path.join(entry.name, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
             process.stderr.write(`agents-cli: '${entry.name}' in ${pluginsDir} has no valid ${manifestPath} ` +
                 `(missing, malformed JSON, or missing name/version) — skipped, not discovered as a plugin.\n`);
@@ -86,15 +58,6 @@ export function discoverPluginsInDir(pluginsDir, spec = { kind: 'user' }) {
     }
     return plugins;
 }
-/**
- * Discover every plugin across ALL marketplaces — the user repo (~/.agents/),
- * each enabled extra repo (~/.agents-<alias>/), and the project repo
- * (<cwd>/.agents/) — stamping marketplace provenance onto each.
- *
- * Plugin names are NOT deduplicated across marketplaces: a `code` plugin in both
- * the user repo and an extra repo yields two entries (`code@agents-cli` and
- * `code@agents-<alias>`), each installing into its own marketplace directory.
- */
 export function discoverPlugins(opts = {}) {
     const out = [];
     for (const dm of discoverMarketplaces(opts)) {
@@ -103,12 +66,6 @@ export function discoverPlugins(opts = {}) {
     return out;
 }
 export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user' }) {
-    // Every marketplace kind lays plugins out as `<repo>/plugins/<name>`, so the
-    // repo root is always the grandparent of pluginRoot — true for user
-    // (~/.agents), system (~/.agents/.system), each extra repo, and the project
-    // repo (<cwd>/.agents) alike. Deriving it here means every caller of
-    // buildDiscoveredPlugin (discoverPluginsInDir, inspectPluginCapabilities, …)
-    // gets provenance for free with no signature change.
     const repoRoot = path.dirname(path.dirname(pluginRoot));
     return {
         name: manifest.name,
@@ -134,12 +91,6 @@ export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user
         },
     };
 }
-/**
- * Ordered, non-empty resource groups a plugin packages. Single source of truth
- * for the breakdown shown by the plugin picker, `agents inspect --plugins`, and
- * its detail view. Empty categories are omitted; `settings` appears only when
- * the plugin merges non-permission settings.
- */
 export function pluginResourceGroups(plugin) {
     const groups = [
         { label: 'skills', items: plugin.skills.map((s) => `/${plugin.name}:${s}`) },
@@ -159,13 +110,6 @@ export function pluginResourceGroups(plugin) {
         out.push({ label: 'settings', items: ['settings.json'] });
     return out;
 }
-/**
- * True when a manifest field declares an inline execution surface — a non-empty
- * path string, a non-empty array, or an object with at least one key. The
- * official plugin format lets `hooks`/`mcpServers` live inline in the manifest
- * (a path or an inline map) instead of as a `hooks/` dir or `.mcp.json` file, so
- * filesystem-only detection would miss them and auto-enable a hostile plugin.
- */
 function manifestDeclaresExecSurface(value) {
     if (typeof value === 'string')
         return value.trim().length > 0;
@@ -179,9 +123,6 @@ export function inspectPluginCapabilities(pluginRoot) {
     const manifest = loadPluginManifest(pluginRoot);
     const plugin = manifest ? buildDiscoveredPlugin(pluginRoot, manifest) : null;
     return {
-        // Inline manifest `hooks`/`mcpServers` are execution surfaces too — a cloned
-        // repo's project plugin must not be auto-enabled just because it ships the
-        // exec config inline in plugin.json rather than as a hooks/ dir or .mcp.json.
         hasHooks: (plugin?.hooks.length || 0) > 0 ||
             pluginHasDirectoryEntries(pluginRoot, 'hooks') ||
             manifestDeclaresExecSurface(manifest?.hooks),
@@ -201,9 +142,6 @@ export function pluginCapabilityLabels(capabilities) {
         .filter((key) => capabilities[key])
         .map((key) => PLUGIN_EXEC_SURFACE_LABELS[key]);
 }
-/**
- * Load a plugin manifest from a plugin directory.
- */
 export function loadPluginManifest(pluginRoot) {
     const manifestPath = path.join(pluginRoot, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
     if (!fs.existsSync(manifestPath)) {
@@ -247,14 +185,6 @@ export function assertPluginTargetContained(targetRoot, pluginsDir) {
         throw new Error(`Plugin install target escapes plugins directory: ${targetRoot}`);
     }
 }
-/**
- * Get a specific plugin by name. On a cross-marketplace name collision the
- * highest-precedence scope wins (project > extra > user > system) — the same
- * resolution the sync writer's Map(last-wins) dedupe and collectPluginScopes()
- * use. discoverPlugins() yields low→high precedence order, so the LAST match is
- * the winner; returning the first match would resolve to the lowest scope (e.g.
- * a system plugin over the user's same-named one), which is exactly backwards.
- */
 export function getPlugin(name) {
     const plugins = discoverPlugins();
     for (let i = plugins.length - 1; i >= 0; i--) {
@@ -263,11 +193,6 @@ export function getPlugin(name) {
     }
     return null;
 }
-/**
- * Check if an agent supports a specific plugin.
- * If the plugin specifies agents, only those are supported.
- * Otherwise defaults to all plugin-capable agents.
- */
 export function pluginSupportsAgent(plugin, agent) {
     if (!isCapable(agent, 'plugins'))
         return false;
@@ -276,8 +201,6 @@ export function pluginSupportsAgent(plugin, agent) {
     }
     return true;
 }
-// ─── Discovery helpers ────────────────────────────────────────────────────────
-/** Fact basenames (no .md) from a plugin's memory/ directory. */
 export function discoverPluginMemory(pluginRoot) {
     const dir = path.join(pluginRoot, 'memory');
     if (!fs.existsSync(dir))
@@ -301,15 +224,6 @@ function discoverPluginSkills(pluginRoot) {
         .filter(d => d.isDirectory() && !d.name.startsWith('.'))
         .map(d => d.name);
 }
-/**
- * The lifecycle events a plugin hooks into, read from hooks/hooks.json.
- *
- * The official plugin format wraps the event map under a `hooks` key
- * (`{ description, hooks: { SessionStart: [...], PreToolUse: [...] } }`), so the
- * meaningful keys are the events — NOT the top-level keys (`description`,
- * `hooks`). Older/flat files put the event names at the top level directly; we
- * read whichever object actually holds the event map.
- */
 export function discoverPluginHooks(pluginRoot) {
     const hooksFile = path.join(pluginRoot, 'hooks', 'hooks.json');
     if (!fs.existsSync(hooksFile))
@@ -331,7 +245,6 @@ function discoverPluginScripts(pluginRoot) {
         return [];
     return fs.readdirSync(scriptsDir).filter(f => !f.startsWith('.'));
 }
-/** Discover command .md files inside a plugin's commands/ directory. */
 export function discoverPluginCommands(pluginRoot) {
     const commandsDir = path.join(pluginRoot, 'commands');
     if (!fs.existsSync(commandsDir))
@@ -340,7 +253,6 @@ export function discoverPluginCommands(pluginRoot) {
         .filter(f => f.endsWith('.md') && !f.startsWith('.'))
         .map(f => f.slice(0, -3));
 }
-/** Discover agent definition .md files inside a plugin's agents/ directory. */
 export function discoverPluginAgentDefs(pluginRoot) {
     const agentsDir = path.join(pluginRoot, 'agents');
     if (!fs.existsSync(agentsDir))
@@ -349,13 +261,6 @@ export function discoverPluginAgentDefs(pluginRoot) {
         .filter(f => f.endsWith('.md') && !f.startsWith('.'))
         .map(f => f.slice(0, -3));
 }
-/**
- * Discover workflow directories inside a plugin's `workflows/` folder.
- * A valid workflow is a directory containing WORKFLOW.md (same contract as
- * project/user/system workflows). Phase 5: plugins package workflows as
- * entrypoints so `agents run <name>` can resolve them without a separate
- * install into ~/.agents/workflows/.
- */
 export function discoverPluginWorkflows(pluginRoot) {
     const workflowsDir = path.join(pluginRoot, 'workflows');
     if (!fs.existsSync(workflowsDir))
@@ -370,14 +275,12 @@ export function discoverPluginWorkflows(pluginRoot) {
         return [];
     }
 }
-/** Discover executable files in a plugin's bin/ directory. */
 export function discoverPluginBin(pluginRoot) {
     const binDir = path.join(pluginRoot, 'bin');
     if (!fs.existsSync(binDir))
         return [];
     return fs.readdirSync(binDir).filter(f => !f.startsWith('.'));
 }
-/** Discover MCP server names from .mcp.json at the plugin root. */
 export function discoverPluginMcpServers(pluginRoot) {
     const mcpFile = path.join(pluginRoot, '.mcp.json');
     if (!fs.existsSync(mcpFile))
@@ -390,7 +293,6 @@ export function discoverPluginMcpServers(pluginRoot) {
         return [];
     }
 }
-/** Discover LSP server keys from .lsp.json at the plugin root. */
 export function discoverPluginLspServers(pluginRoot) {
     const lspFile = path.join(pluginRoot, '.lsp.json');
     if (!fs.existsSync(lspFile))
@@ -403,7 +305,6 @@ export function discoverPluginLspServers(pluginRoot) {
         return [];
     }
 }
-/** Discover monitor names from monitors/monitors.json. */
 export function discoverPluginMonitors(pluginRoot) {
     const monitorsFile = path.join(pluginRoot, 'monitors', 'monitors.json');
     if (!fs.existsSync(monitorsFile))
@@ -418,7 +319,6 @@ export function discoverPluginMonitors(pluginRoot) {
         return [];
     }
 }
-/** Return true if settings.json contains non-permission keys worth merging. */
 function pluginHasNonPermissionSettings(pluginRoot) {
     const settingsPath = path.join(pluginRoot, 'settings.json');
     if (!fs.existsSync(settingsPath))
@@ -431,15 +331,6 @@ function pluginHasNonPermissionSettings(pluginRoot) {
         return false;
     }
 }
-// ─── Variable expansion ───────────────────────────────────────────────────────
-/**
- * Expand plugin variables in a string.
- *
- * Variables:
- *   ${CLAUDE_PLUGIN_ROOT}      -> absolute path to plugin directory
- *   ${CLAUDE_PLUGIN_DATA}      -> per-version data directory for this plugin
- *   ${user_config.<key>}       -> value from plugin's .user-config.json
- */
 export function expandPluginVars(str, pluginRoot, pluginName, agentId, versionHome, userConfig) {
     const dataDir = path.join(versionHome, agentConfigDirName(agentId), 'plugin-data', pluginName);
     let result = str
@@ -452,10 +343,6 @@ export function expandPluginVars(str, pluginRoot, pluginName, agentId, versionHo
     }
     return result;
 }
-// ─── userConfig storage ───────────────────────────────────────────────────────
-/**
- * Load persisted user config for a plugin from .user-config.json.
- */
 export function loadUserConfig(pluginName) {
     const configPath = path.join(getPluginsDir(), pluginName, USER_CONFIG_FILE);
     if (!fs.existsSync(configPath))
@@ -467,35 +354,17 @@ export function loadUserConfig(pluginName) {
         return {};
     }
 }
-/**
- * Persist user config for a plugin to .user-config.json.
- */
 export function saveUserConfig(pluginName, config) {
     const configPath = path.join(getPluginsDir(), pluginName, USER_CONFIG_FILE);
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
-// ─── Dependency checking ──────────────────────────────────────────────────────
-/**
- * Check plugin dependencies against installed plugins.
- * Returns names of missing dependencies (warning only — not a hard error).
- */
 export function checkPluginDependencies(manifest) {
     if (!manifest.dependencies || manifest.dependencies.length === 0)
         return [];
     const installed = new Set(discoverPlugins().map(p => p.name));
     return manifest.dependencies.filter(dep => !installed.has(dep));
 }
-// ─── Marketplace routing ──────────────────────────────────────────────────────
-/**
- * Reconstruct a MarketplaceSpec from a marketplace name. The inverse of
- * marketplaceNameFor(): "agents-cli" → user, "agents-project" → project,
- * "agents-system" → system, "agents-<alias>" → extra. The per-version
- * marketplace operations only key off the name (never spec.root), but we
- * resolve the real source root anyway so the spec is honest for any caller that
- * inspects it (e.g. descriptionFor, which would otherwise label the system
- * marketplace as an extra repo named "system").
- */
 export function marketplaceSpecForName(name, cwd = process.cwd()) {
     if (!name || name === MARKETPLACE_NAME)
         return { kind: 'user' };
@@ -508,12 +377,6 @@ export function marketplaceSpecForName(name, cwd = process.cwd()) {
     const alias = name.slice('agents-'.length);
     return { kind: 'extra', alias, root: getExtraPluginsDir(alias) };
 }
-/**
- * List the marketplace names that have been synthesized under a version home
- * (i.e. the directories beneath .{agent}/plugins/marketplaces/). Used by
- * removal/orphan/diff passes that must touch every marketplace a version
- * carries, not just the user one.
- */
 function listVersionMarketplaceNames(agent, versionHome) {
     const dir = path.join(versionHome, agentConfigDirName(agent), 'plugins', 'marketplaces');
     if (!fs.existsSync(dir))
@@ -527,28 +390,6 @@ function listVersionMarketplaceNames(agent, versionHome) {
         return [];
     }
 }
-// ─── Main sync entry point ────────────────────────────────────────────────────
-/**
- * Sync a plugin to a specific agent version's home directory.
- *
- * For plugins-capable agents (claude, openclaw):
- *   1. Copy plugin source into <versionHome>/.<agent>/plugins/marketplaces/agents-cli/plugins/<name>/
- *   2. Pre-expand ${user_config.*} variables in copied text files (Claude doesn't know this var).
- *   3. (Re-)synthesize the marketplace.json catalog from the installed plugins.
- *   4. Register the synthetic marketplace in known_marketplaces.json.
- *   5. Mark <plugin>@agents-cli enabled in settings.json#enabledPlugins.
- *   6. Migrate (remove) legacy dual-dash skills/commands/agents/bin/hooks/mcp entries.
- *
- * Claude/OpenClaw natively handle the plugin's skills, commands, agents, hooks,
- * MCP servers, bin/, settings.json, and permissions once the plugin lives at the
- * native install path and is marked enabled — see
- * https://code.claude.com/docs/en/plugins.
- *
- * Droid (Factory CLI) reuses this same marketplace layout but additionally
- * requires an installed_plugins.json registry entry and a "local"-source
- * known_marketplaces.json entry before `droid plugin list` will see the plugin
- * (steps handled by registerMarketplace's droid branch + step 5c below).
- */
 export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     const result = {
         success: false,
@@ -567,13 +408,7 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     if (!isCapable(agent, 'plugins')) {
         return result;
     }
-    // OpenCode uses TS/JS modules under ~/.config/opencode/plugins/, not the
-    // Claude marketplace layout. Install those modules and return early.
     if (agent === 'opencode') {
-        // Trust gate (RUSH-1756): OpenCode plugins are raw executable TS/JS modules,
-        // so they must clear the same consent check as every other exec surface
-        // before install — this branch used to return early, bypassing the gate the
-        // Hermes/marketplace branches all apply.
         const enablePlugin = options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root));
         if (!enablePlugin) {
             return result;
@@ -584,8 +419,6 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
             result.skills.push(plugin.name);
         return result;
     }
-    // Goose loads Open Plugins from $HOME/.agents/plugins/<name>/ (same layout as
-    // agents-cli's source tree). Under the shim HOME is the version home.
     if (agent === 'goose') {
         const ok = installGoosePlugin(plugin, versionHome);
         result.success = ok;
@@ -593,8 +426,6 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
             result.skills.push(plugin.name);
         return result;
     }
-    // Hermes loads plugins from a flat $HOME/.hermes/plugins/<name>/ dir with a
-    // plugin.yaml manifest, gated by a plugins.enabled allowlist in config.yaml.
     if (agent === 'hermes') {
         const enablePlugin = options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root));
         const ok = installHermesPlugin(plugin, versionHome, enablePlugin);
@@ -604,20 +435,12 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
         return result;
     }
     const userConfig = loadUserConfig(plugin.name);
-    // Route every marketplace op through the plugin's own marketplace, so a plugin
-    // discovered in an extra/project repo installs under its own
-    // marketplaces/<name>/ tree — never the user marketplace.
     const spec = marketplaceSpecForName(plugin.marketplace);
     const marketplaceName = marketplaceNameFor(spec);
-    // 1. Copy plugin to native marketplace install dir.
     const installDir = copyPluginToMarketplace(plugin, spec, agent, versionHome);
-    // 2. Pre-expand ${user_config.*} in the copy. Leave ${CLAUDE_PLUGIN_ROOT} /
-    //    ${CLAUDE_PLUGIN_DATA} alone — Claude expands those natively at runtime.
     if (Object.keys(userConfig).length > 0) {
         expandUserConfigInDir(installDir, userConfig);
     }
-    // 2b. Write agent-native manifest dir alongside .claude-plugin/ when the agent
-    //     expects a different directory name (e.g. Codex uses .codex-plugin/).
     const agentManifestDir = AGENTS[agent].pluginManifestDir;
     if (agentManifestDir && agentManifestDir !== PLUGIN_MANIFEST_DIR) {
         const srcManifest = path.join(installDir, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
@@ -627,35 +450,18 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
             fs.copyFileSync(srcManifest, path.join(destManifestDir, PLUGIN_MANIFEST_FILE));
         }
     }
-    // 3-5. Synthesize manifest, register marketplace, enable plugin.
     syncMarketplaceManifest(spec, agent, versionHome);
     registerMarketplace(spec, agent, versionHome);
-    // Trust gate: plugins with executable surfaces (hooks/, bin/, scripts/,
-    // .mcp.json, settings.json, permissions/) are only auto-enabled when the
-    // caller explicitly opts in. addPluginToSettings does no gating — that moved
-    // here, where plugin capabilities are inspected.
     const enablePlugin = options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root));
     if (enablePlugin) {
         addPluginToSettings(plugin.name, marketplaceName, agent, versionHome);
     }
-    // 5c. Droid diverges from Claude's marketplace+enabledPlugins model: it only
-    //     "sees" a plugin that also has an entry in installed_plugins.json (with
-    //     the marketplace registered as source "local"). Register the install so
-    //     `droid plugin list` shows it — Active when enabled, Inactive otherwise.
     if (agent === 'droid') {
         registerDroidInstalledPlugin(plugin.name, marketplaceName, installDir, plugin.manifest.version, agent, versionHome);
     }
-    // 5d. Copilot, like Droid, only "sees" a plugin that also has an entry in its
-    //     auto-managed config.json#installedPlugins (registerMarketplace already
-    //     wrote settings.json#extraKnownMarketplaces, and addPluginToSettings the
-    //     enabledPlugins flag). cache_path points at the marketplace copy; the
-    //     `enabled` flag mirrors the exec-surface trust gate above.
     if (agent === 'copilot') {
         registerCopilotInstalledPlugin(plugin.name, marketplaceName, installDir, plugin.manifest.version, enablePlugin, agent, versionHome);
     }
-    // 5b. Convert plugin commands/ to skills for agents that dropped command support
-    //     (Codex >= 0.117.0). Skill name is prefixed with plugin name to avoid
-    //     collision with standalone command skills.
     if (options.version && shouldInstallCommandAsSkill(agent, options.version) && plugin.commands.length > 0) {
         const agentDir = path.join(versionHome, agentConfigDirName(agent));
         const skillSourceDirs = [path.join(agentDir, 'skills')];
@@ -666,9 +472,7 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
             }
         }
     }
-    // 6. Migrate legacy dual-dash flat layout from previous versions of agents-cli.
     migrateLegacyFlatLayout(plugin, agent, versionHome);
-    // Populate the result shape for backward-compatible callers/reporting.
     result.skills = plugin.skills.map(s => `${plugin.name}:${s}`);
     result.commands = plugin.commands.map(c => `${plugin.name}:${c}`);
     result.agentDefs = plugin.agentDefs.map(a => `${plugin.name}:${a}`);
@@ -709,10 +513,6 @@ function pluginHasDirectoryEntries(pluginRoot, dirName) {
         return false;
     }
 }
-/**
- * Walk a directory and replace ${user_config.*} placeholders in text files.
- * Leaves all other variables (${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}) alone.
- */
 function expandUserConfigInDir(dir, userConfig) {
     const textExtensions = new Set(['.md', '.json', '.sh', '.py', '.js', '.ts', '.yaml', '.yml', '.toml', '.txt']);
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -732,18 +532,12 @@ function expandUserConfigInDir(dir, userConfig) {
                 fs.writeFileSync(full, expanded, 'utf-8');
             }
         }
-        catch { /* skip unreadable */ }
+        catch { }
     }
 }
-/**
- * Remove legacy <plugin>--* entries from a version home, left by the previous
- * flatten-based sync. Safe to call repeatedly — only deletes paths matching the
- * plugin's prefix.
- */
 function migrateLegacyFlatLayout(plugin, agent, versionHome) {
     const prefix = `${plugin.name}--`;
     const agentRoot = path.join(versionHome, agentConfigDirName(agent));
-    // 1. skills
     const skillsDir = path.join(agentRoot, 'skills');
     if (fs.existsSync(skillsDir)) {
         for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
@@ -751,11 +545,10 @@ function migrateLegacyFlatLayout(plugin, agent, versionHome) {
                 try {
                     fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
                 }
-                catch { /* skip */ }
+                catch { }
             }
         }
     }
-    // 2. commands
     if (agent === 'claude' || agent === 'openclaw') {
         const cmdsDir = path.join(agentRoot, AGENTS[agent]?.commandsSubdir ?? 'commands');
         if (fs.existsSync(cmdsDir)) {
@@ -764,12 +557,11 @@ function migrateLegacyFlatLayout(plugin, agent, versionHome) {
                     try {
                         fs.unlinkSync(path.join(cmdsDir, entry.name));
                     }
-                    catch { /* skip */ }
+                    catch { }
                 }
             }
         }
     }
-    // 3. agent definitions
     const agentsDir = path.join(agentRoot, 'agents');
     if (fs.existsSync(agentsDir)) {
         for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
@@ -777,20 +569,17 @@ function migrateLegacyFlatLayout(plugin, agent, versionHome) {
                 try {
                     fs.unlinkSync(path.join(agentsDir, entry.name));
                 }
-                catch { /* skip */ }
+                catch { }
             }
         }
     }
-    // 4. plugin-bin
     const binDir = path.join(agentRoot, 'plugin-bin', plugin.name);
     if (fs.existsSync(binDir)) {
         try {
             fs.rmSync(binDir, { recursive: true, force: true });
         }
-        catch { /* skip */ }
+        catch { }
     }
-    // 5. settings.json — strip namespaced mcpServers, hooks referencing plugin
-    //    root, permissions referencing plugin root, and pluginBinPaths entries.
     const settingsPath = path.join(agentRoot, 'settings.json');
     if (!fs.existsSync(settingsPath))
         return;
@@ -865,41 +654,21 @@ function migrateLegacyFlatLayout(plugin, agent, versionHome) {
         try {
             fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
         }
-        catch { /* ignore */ }
-    }
-}
-// ─── OpenCode plugins (TS/JS modules) ─────────────────────────────────────────
-/**
- * OpenCode loads JS/TS modules from `$HOME/.config/opencode/plugins/` (global)
- * and `<project>/.opencode/plugins/` (project). Under agents-cli version
- * isolation HOME is the version home, so we write:
- *   {versionHome}/.config/opencode/plugins/
- *
- * Claude-style marketplace plugins are NOT auto-converted; we install modules
- * from (in order):
- *   1. pluginRoot/opencode/*.{ts,js,mjs,cjs}
- *   2. pluginRoot/plugins/*.{ts,js,mjs,cjs}
- *   3. pluginRoot/*.{ts,js,mjs,cjs} (excluding *.test.* / *.spec.*)
- * If none exist, install still succeeds by writing a marker + copying any
- * package.json so empty plugins don't break sync; opencode simply has nothing
- * to load until a real module appears.
- */
+        catch { }
+    }
+}
 export function openCodePluginsDir(versionHome) {
     return path.join(versionHome, '.config', 'opencode', 'plugins');
 }
-// OpenCode's local-plugin loader only auto-loads direct *.ts / *.js files under
-// plugins/ — not nested dirs and not .mjs/.cjs (see opencode.ai/docs/plugins).
 const OPENCODE_MODULE_RE = /\.(ts|js)$/i;
 const OPENCODE_TEST_RE = /\.(test|spec)\./i;
 function listOpenCodeModules(dir) {
     if (!fs.existsSync(dir))
         return [];
-    // readdir without recursion — only loader-visible direct children.
     return fs.readdirSync(dir, { withFileTypes: true })
         .filter((e) => e.isFile() && OPENCODE_MODULE_RE.test(e.name) && !OPENCODE_TEST_RE.test(e.name) && !e.name.startsWith('.'))
         .map((e) => e.name);
 }
-/** Resolve source module files for an agents-cli plugin to install into OpenCode. */
 export function resolveOpenCodePluginSources(pluginRoot) {
     for (const sub of ['opencode', 'plugins']) {
         const dir = path.join(pluginRoot, sub);
@@ -914,7 +683,6 @@ export function installOpenCodePlugin(plugin, versionHome) {
     fs.mkdirSync(destDir, { recursive: true });
     const sources = resolveOpenCodePluginSources(plugin.root);
     const destPluginDir = path.join(destDir, plugin.name);
-    // Clean previous install of this plugin name (file or dir)
     const bareTs = path.join(destDir, `${plugin.name}.ts`);
     const bareJs = path.join(destDir, `${plugin.name}.js`);
     for (const p of [bareTs, bareJs, destPluginDir]) {
@@ -922,18 +690,13 @@ export function installOpenCodePlugin(plugin, versionHome) {
             if (fs.existsSync(p))
                 fs.rmSync(p, { recursive: true, force: true });
         }
-        catch { /* best effort */ }
+        catch { }
     }
     if (sources.length === 0) {
-        // No TS/JS modules — still create a managed marker so isPluginSynced can
-        // track that we processed the plugin (and so re-sync is idempotent).
         fs.mkdirSync(destPluginDir, { recursive: true });
         fs.writeFileSync(path.join(destPluginDir, '.agents-cli-managed'), `plugin=${plugin.name}\n# no opencode modules found under ${plugin.root}\n`, 'utf-8');
         return true;
     }
-    // Install each module as a direct file under plugins/ so the loader sees it.
-    // Multi-module plugins get `<name>` or `<name>-<stem>` basenames (never a
-    // nested directory — OpenCode does not scan nested plugin dirs).
     for (let i = 0; i < sources.length; i++) {
         const src = sources[i];
         const ext = path.extname(src);
@@ -945,7 +708,6 @@ export function installOpenCodePlugin(plugin, versionHome) {
                 : `${plugin.name}-${stem}${ext}`);
         fs.copyFileSync(src, path.join(destDir, destName));
     }
-    // Marker file so isOpenCodePluginInstalled / remove can track multi-file installs.
     fs.mkdirSync(destPluginDir, { recursive: true });
     fs.writeFileSync(path.join(destPluginDir, '.agents-cli-managed'), `plugin=${plugin.name}\nfiles=${sources.map((s) => path.basename(s)).join(',')}\n`, 'utf-8');
     return true;
@@ -979,7 +741,6 @@ export function removeOpenCodePlugin(pluginName, versionHome) {
             removed = true;
         }
     }
-    // Flat multi-module installs: <name>-<stem>.ts/js next to the marker dir.
     if (fs.existsSync(destDir)) {
         for (const entry of fs.readdirSync(destDir)) {
             if (entry.startsWith(`${pluginName}-`) && /\.(ts|js)$/i.test(entry)) {
@@ -987,29 +748,12 @@ export function removeOpenCodePlugin(pluginName, versionHome) {
                     fs.rmSync(path.join(destDir, entry), { force: true });
                     removed = true;
                 }
-                catch { /* ignore */ }
+                catch { }
             }
         }
     }
     return removed;
 }
-/**
- * Security (RUSH-1755): `fs.cpSync(..., { recursive: true })` copies symlinks
- * verbatim (dereference defaults to false), so a malicious plugin can ship a
- * symlink whose target escapes the install root — e.g.
- * `.agents-cli-managed -> ~/.bashrc`. The managed-marker / manifest writes that
- * follow the copy would then write THROUGH the link, clobbering an
- * attacker-chosen path outside the install root.
- *
- * Walk destRoot after the recursive copy, lstat each entry, and remove any
- * symlink whose resolved target escapes BOTH destRoot and sourceRoot. Both roots
- * matter because Node's cpSync rewrites a *relative* internal symlink
- * (`./x`) into an *absolute* link back into the source tree, so a legitimate
- * internal symlink resolves under sourceRoot (not destRoot) after the copy.
- * Keeping targets within sourceRoot preserves those internal symlinks — matching
- * copyPluginToMarketplace's policy — while genuinely external escapes are
- * dropped, neutralizing the write-through.
- */
 function stripEscapingSymlinks(destRoot, sourceRoot) {
     const realRoots = [destRoot, sourceRoot].map((r) => {
         try {
@@ -1037,7 +781,6 @@ function stripEscapingSymlinks(destRoot, sourceRoot) {
                     escapes = !within(fs.realpathSync(full));
                 }
                 catch {
-                    // Dangling / unresolvable symlink — treat as escaping and drop it.
                     escapes = true;
                 }
                 if (escapes) {
@@ -1045,13 +788,10 @@ function stripEscapingSymlinks(destRoot, sourceRoot) {
                         fs.rmSync(full, { force: true });
                         removed.push(path.relative(destRoot, full) || entry.name);
                     }
-                    catch { /* best effort */ }
+                    catch { }
                 }
             }
             else if (entry.isDirectory()) {
-                // Do not descend into symlinked dirs — isDirectory() is false for a
-                // symlink even when it points at a directory, so this only recurses
-                // into real subdirectories, keeping the walk inside destRoot.
                 walk(full);
             }
         }
@@ -1059,15 +799,6 @@ function stripEscapingSymlinks(destRoot, sourceRoot) {
     walk(destRoot);
     return removed;
 }
-// ─── Goose plugins (Open Plugins under .agents/plugins/) ─────────────────────
-/**
- * Goose auto-discovers Open Plugins at `$HOME/.agents/plugins/<name>/`.
- * Under agents-cli version isolation HOME is the version home, so we install to:
- *   {versionHome}/.agents/plugins/<name>/
- *
- * Full plugin directory copy (not marketplace) — same layout goose and
- * agents-cli share for source plugins.
- */
 export function goosePluginsDir(versionHome) {
     return path.join(versionHome, '.agents', 'plugins');
 }
@@ -1096,17 +827,6 @@ export function removeGoosePlugin(pluginName, versionHome) {
     fs.rmSync(destRoot, { recursive: true, force: true });
     return true;
 }
-// ─── Hermes plugins (flat ~/.hermes/plugins/ + config.yaml enable toggle) ─────
-/**
- * Hermes (Nous Research) loads plugins from a flat `$HOME/.hermes/plugins/<name>/`
- * directory holding a `plugin.yaml` manifest — NOT the Claude marketplace layout.
- * Under agents-cli version isolation HOME is the version home, so we install to:
- *   {versionHome}/.hermes/plugins/<name>/
- * A plugin does not load until its name is added to `plugins.enabled` (a YAML
- * array) in `{versionHome}/.hermes/config.yaml`; a deny-list `plugins.disabled`
- * wins on conflict, so agents-cli only manages the `enabled` allowlist and never
- * touches `disabled` (user-owned).
- */
 export function hermesPluginsDir(versionHome) {
     return path.join(versionHome, '.hermes', 'plugins');
 }
@@ -1121,11 +841,6 @@ function writeHermesPluginManifest(plugin, destRoot) {
     };
     fs.writeFileSync(path.join(destRoot, HERMES_PLUGIN_MANIFEST_FILE), yaml.stringify(manifest), 'utf-8');
 }
-/**
- * Add or remove a plugin name in `plugins.enabled` within ~/.hermes/config.yaml,
- * preserving every other key (read → mutate → write). Never touches
- * `plugins.disabled`. No-op (no rewrite) when the desired state already holds.
- */
 export function setHermesPluginEnabled(pluginName, versionHome, enabled) {
     const configPath = hermesConfigPath(versionHome);
     let config = {};
@@ -1148,7 +863,7 @@ export function setHermesPluginEnabled(pluginName, versionHome, enabled) {
         plugins.enabled = current.filter((n) => n !== pluginName);
     }
     else {
-        return; // desired state already holds — no rewrite
+        return;
     }
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, yaml.stringify(config), 'utf-8');
@@ -1167,11 +882,6 @@ export function installHermesPlugin(plugin, versionHome, enable) {
         }
         writeHermesPluginManifest(plugin, destRoot);
         fs.writeFileSync(path.join(destRoot, '.agents-cli-managed'), `plugin=${plugin.name}\n`, 'utf-8');
-        // Enable only when trusted — never DOWN-toggle here. An un-flagged background
-        // re-sync of an exec-surface plugin passes enable=false; forcing the allowlist
-        // to false then would clobber a plugin the user deliberately enabled with
-        // --allow-exec-surfaces. Mirror addPluginToSettings: add-if-trusted, else leave
-        // the existing enabled state untouched. (Removal still unregisters explicitly.)
         if (enable) {
             setHermesPluginEnabled(plugin.name, versionHome, true);
         }
@@ -1189,16 +899,9 @@ export function removeHermesPlugin(pluginName, versionHome) {
     const existed = fs.existsSync(destRoot);
     if (existed)
         fs.rmSync(destRoot, { recursive: true, force: true });
-    // Always drop it from the enabled allowlist, even if the dir was already gone.
     setHermesPluginEnabled(pluginName, versionHome, false);
     return existed;
 }
-// ─── Sync status ──────────────────────────────────────────────────────────────
-/**
- * Check if a plugin is synced to a version. True when the plugin lives at the
- * native marketplace install path. Legacy dual-dash entries are not counted —
- * they're treated as stale and migrated away on the next sync.
- */
 export function isPluginSynced(plugin, agent, versionHome) {
     if (!isCapable(agent, 'plugins'))
         return false;
@@ -1214,20 +917,11 @@ export function isPluginSynced(plugin, agent, versionHome) {
     const spec = marketplaceSpecForName(plugin.marketplace);
     if (!isInstalledInMarketplace(plugin.name, spec, agent, versionHome))
         return false;
-    // Droid additionally requires its installed_plugins.json registry entry —
-    // without it the marketplace copy is invisible to `droid plugin list`.
     if (agent === 'droid') {
         return isDroidPluginInstalled(plugin.name, marketplaceNameFor(spec), agent, versionHome);
     }
     return true;
 }
-// ─── Removal ─────────────────────────────────────────────────────────────────
-/**
- * Remove a plugin from a specific agent version's home directory.
- * Inverse of syncPluginToVersion.
- *
- * Works whether or not the plugin source still exists on disk.
- */
 export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHome) {
     const result = {
         skills: [],
@@ -1238,29 +932,24 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
         permissions: 0,
         mcp: 0,
     };
-    // OpenCode: remove TS/JS modules from ~/.config/opencode/plugins/.
     if (agent === 'opencode') {
         if (removeOpenCodePlugin(pluginName, versionHome)) {
             result.skills.push(pluginName);
         }
         return result;
     }
-    // Goose: remove Open Plugin directory from versionHome/.agents/plugins/.
     if (agent === 'goose') {
         if (removeGoosePlugin(pluginName, versionHome)) {
             result.skills.push(pluginName);
         }
         return result;
     }
-    // Hermes: remove the flat plugin dir and drop it from config.yaml plugins.enabled.
     if (agent === 'hermes') {
         if (removeHermesPlugin(pluginName, versionHome)) {
             result.skills.push(pluginName);
         }
         return result;
     }
-    // 1. Remove the plugin from every marketplace it's installed under. A name can
-    //    appear in more than one (collision across repos), so we sweep them all.
     let removedAny = false;
     for (const name of listVersionMarketplaceNames(agent, versionHome)) {
         const spec = marketplaceSpecForName(name);
@@ -1274,10 +963,7 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
         if (agent === 'copilot') {
             unregisterCopilotInstalledPlugin(pluginName, name, agent, versionHome);
         }
-        // Refresh marketplace.json so it reflects what's left under plugins/.
         syncMarketplaceManifest(spec, agent, versionHome);
-        // If we just removed the last plugin, drop the marketplace dir and the
-        // known_marketplaces.json entry too.
         if (marketplaceIsEmpty(name, agent, versionHome)) {
             removeEmptyMarketplaceDir(name, agent, versionHome);
             unregisterMarketplace(name, agent, versionHome);
@@ -1286,14 +972,9 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
     if (removedAny) {
         result.skills.push(pluginName);
     }
-    // 4. Strip any legacy dual-dash entries from prior agents-cli versions.
     cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, result);
     return result;
 }
-/**
- * Strip dual-dash flat-layout entries left behind by older agents-cli sync runs.
- * Mutates `result` to record what was removed.
- */
 function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, result) {
     const prefix = `${pluginName}--`;
     const agentRoot = path.join(versionHome, agentConfigDirName(agent));
@@ -1306,7 +987,7 @@ function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, resul
                 fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
                 result.skills.push(entry.name);
             }
-            catch { /* skip */ }
+            catch { }
         }
     }
     if (agent === 'claude' || agent === 'openclaw') {
@@ -1319,7 +1000,7 @@ function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, resul
                     fs.unlinkSync(path.join(commandsDir, entry.name));
                     result.commands.push(entry.name);
                 }
-                catch { /* skip */ }
+                catch { }
             }
         }
     }
@@ -1332,7 +1013,7 @@ function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, resul
                 fs.unlinkSync(path.join(agentsDir, entry.name));
                 result.agentDefs.push(entry.name);
             }
-            catch { /* skip */ }
+            catch { }
         }
     }
     const binDir = path.join(agentRoot, 'plugin-bin', pluginName);
@@ -1341,7 +1022,7 @@ function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, resul
             fs.rmSync(binDir, { recursive: true, force: true });
             result.bin.push(binDir);
         }
-        catch { /* skip */ }
+        catch { }
     }
     const settingsPath = path.join(agentRoot, 'settings.json');
     if (!fs.existsSync(settingsPath))
@@ -1427,7 +1108,7 @@ function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, resul
         try {
             fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
         }
-        catch { /* ignore */ }
+        catch { }
     }
 }
 function pairKey(marketplace, name) {
@@ -1440,25 +1121,10 @@ function indexActivePlugins(input) {
     const pairs = new Set();
     for (const p of input) {
         names.add(p.name);
-        // A discovered plugin always carries provenance; the type allows undefined,
-        // so mirror discovery's own default (a marketplace-less plugin is the user
-        // "agents-cli" marketplace — see discoverPlugins / buildDiscoveredPlugin).
         pairs.add(pairKey(p.marketplace ?? MARKETPLACE_NAME, p.name));
     }
     return { names, pairs };
 }
-/**
- * Does the SOURCE repo backing a synthesized marketplace exist on disk? A
- * marketplace's version-home install is only authoritative-cleanable when its
- * source repo is present: a present repo missing a plugin means that plugin was
- * genuinely removed, while an absent repo (a project we're not in, a removed
- * extra repo) is merely unreachable and must not be mistaken for deletion.
- *
- * We check the REPO root, not the plugins/ subdir: the user repo (~/.agents/)
- * always exists but its plugins/ dir may not, and "user repo present, no `code`
- * plugin in it" is exactly what makes an `agents-cli` `code` shadow a real
- * orphan (PHNX-2618).
- */
 function marketplaceSourceRepoExists(marketplaceName, cwd) {
     const spec = marketplaceSpecForName(marketplaceName, cwd);
     switch (spec.kind) {
@@ -1471,25 +1137,6 @@ function marketplaceSourceRepoExists(marketplaceName, cwd) {
         }
     }
 }
-/**
- * Is a version-home marketplace-plugin install an orphan (safe to trash)?
- *
- * A version-home plugin is keyed by (marketplace, name), not name alone — the
- * bug PHNX-2618 exposed. When the same plugin name lives in two marketplaces
- * (e.g. a legacy `code` under `agents-cli` and the current `code` under
- * `agents-system`), a name-only test keeps BOTH alive because the name is active
- * somewhere, so the stale copy never gets cleaned and serves deleted skills.
- *
- *   - Pair still active → keep.
- *   - Pair gone, but the marketplace's source repo is present (authoritative) →
- *     orphan. Trash it even though another marketplace still ships that name.
- *   - Pair gone AND the source repo is absent (unreachable) → fall back to the
- *     original name-only test so an unrelated sync can't trash a plugin whose
- *     source simply isn't on this box / in this cwd right now.
- *
- * When `pairs` is null (a legacy bare-name caller), this reduces to the original
- * name-only behavior unchanged.
- */
 function isOrphanMarketplacePlugin(marketplaceName, pluginName, active, cwd) {
     if (active.pairs === null)
         return !active.names.has(pluginName);
@@ -1499,21 +1146,10 @@ function isOrphanMarketplacePlugin(marketplaceName, pluginName, active, cwd) {
         return true;
     return !active.names.has(pluginName);
 }
-/**
- * Remove orphaned plugin entries from a version home. A marketplace-plugin
- * install is "orphan" when no active source plugin matches its (marketplace,
- * name) pair (see isOrphanMarketplacePlugin). Soft-deletes the affected
- * marketplace plugin dir to ~/.agents/.trash/plugins/. Also cleans up any
- * legacy dual-dash skills/ directories from older agents-cli versions.
- *
- * Pass the discovered plugins (`discoverPlugins()`) for marketplace-aware
- * detection; a bare `Set<string>` of names keeps the original name-only behavior.
- */
 export function cleanOrphanedPluginSkills(agent, versionHome, activePlugins, version) {
     const active = indexActivePlugins(activePlugins);
     const cwd = process.cwd();
     const removed = [];
-    // 1. Walk every marketplace's install dir and trash entries no longer active.
     for (const name of listVersionMarketplaceNames(agent, versionHome)) {
         const spec = marketplaceSpecForName(name);
         const mktPluginsDir = path.join(marketplaceRoot(name, agent, versionHome), 'plugins');
@@ -1541,9 +1177,8 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePlugins, ver
                 removed.push(entry.name);
                 trashedHere = true;
             }
-            catch { /* skip on error */ }
+            catch { }
         }
-        // Keep manifest in sync with on-disk state and drop the marketplace if empty.
         if (trashedHere) {
             syncMarketplaceManifest(spec, agent, versionHome);
             if (marketplaceIsEmpty(name, agent, versionHome)) {
@@ -1552,7 +1187,6 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePlugins, ver
             }
         }
     }
-    // 2. Sweep legacy dual-dash skills directories from older agents-cli versions.
     const skillsDir = path.join(versionHome, agentConfigDirName(agent), 'skills');
     if (fs.existsSync(skillsDir)) {
         for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
@@ -1572,7 +1206,7 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePlugins, ver
                 fs.renameSync(path.join(skillsDir, entry.name), trashDest);
                 removed.push(entry.name);
             }
-            catch { /* skip on error */ }
+            catch { }
         }
     }
     return removed;
@@ -1594,7 +1228,6 @@ export function diffVersionPlugins(agent, version) {
             }
         }
     }
-    // Also surface legacy dual-dash skill dirs as orphans during migration period.
     const skillsDir = path.join(versionHome, agentConfigDirName(agent), 'skills');
     if (fs.existsSync(skillsDir)) {
         for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
@@ -1644,13 +1277,7 @@ export function removePluginSkillFromVersion(agent, version, skillName) {
     }
     return { success: true };
 }
-// ─── Install / Update ─────────────────────────────────────────────────────────
-/**
- * Parse an install spec of the form `name@source` or just `source`.
- * Source can be a git URL or an absolute/relative local path.
- */
 export function parseInstallSpec(spec) {
-    // Check for name@source form
     const atIdx = spec.indexOf('@');
     if (atIdx > 0) {
         const name = spec.slice(0, atIdx);
@@ -1659,14 +1286,8 @@ export function parseInstallSpec(spec) {
     }
     return { name: null, source: spec };
 }
-/**
- * Install a plugin from a git URL or local path.
- * Clones/copies to ~/.agents/plugins/<name>/.
- * Returns the installed plugin name and root path.
- */
 export async function installPlugin(spec) {
     const { name: specName, source } = parseInstallSpec(spec);
-    // Resolve local path (handle ~)
     const isLocalPath = source.startsWith('/') || source.startsWith('./') || source.startsWith('../') || source.startsWith('~')
         || (IS_WINDOWS && isWindowsAbsolutePath(source));
     const resolvedSource = isLocalPath
@@ -1674,7 +1295,6 @@ export async function installPlugin(spec) {
         : source;
     const pluginsDir = getPluginsDir();
     fs.mkdirSync(pluginsDir, { recursive: true });
-    // If local path, load manifest to get the name
     let targetName = specName;
     if (!targetName) {
         if (isLocalPath) {
@@ -1684,7 +1304,6 @@ export async function installPlugin(spec) {
             targetName = manifest.name;
         }
         else {
-            // Derive from git URL: last path segment without .git
             targetName = path.basename(resolvedSource).replace(/\.git$/, '');
         }
     }
@@ -1695,15 +1314,12 @@ export async function installPlugin(spec) {
     assertPluginTargetContained(targetRoot, pluginsDir);
     const isNew = !fs.existsSync(targetRoot);
     if (isLocalPath) {
-        // Copy local directory
         if (fs.existsSync(targetRoot)) {
             fs.rmSync(targetRoot, { recursive: true, force: true });
         }
         fs.cpSync(resolvedSource, targetRoot, { recursive: true });
     }
     else {
-        // Git clone. Validate the transport (blocks ext::/file:///http:///leading-"-")
-        // and pass "--" so the source can never be parsed as a git option.
         assertSafeGitTransport(resolvedSource);
         if (fs.existsSync(targetRoot)) {
             fs.rmSync(targetRoot, { recursive: true, force: true });
@@ -1712,21 +1328,15 @@ export async function installPlugin(spec) {
             stdio: 'pipe',
         });
     }
-    // Validate manifest
     const manifest = loadPluginManifest(targetRoot);
     if (!manifest) {
         fs.rmSync(targetRoot, { recursive: true, force: true });
         throw new Error(`Installed source has no valid .claude-plugin/plugin.json`);
     }
     const capabilities = inspectPluginCapabilities(targetRoot);
-    // Persist source for future updates. `version` records the manifest version
-    // at pull time — a baseline that lets the heal path tell "central is an
-    // untouched copy of upstream" (safe to fast-forward) from "the user edited
-    // it" (leave alone) without hashing the whole tree.
     fs.writeFileSync(path.join(targetRoot, SOURCE_FILE), JSON.stringify({ source, isGit: !isLocalPath, version: manifest.version }), 'utf-8');
     return { name: manifest.name, root: targetRoot, isNew, capabilities };
 }
-/** Read a plugin's `.source` provenance, or null when absent/unreadable. */
 export function readPluginSourceInfo(root) {
     const f = path.join(root, SOURCE_FILE);
     if (!fs.existsSync(f))
@@ -1738,12 +1348,6 @@ export function readPluginSourceInfo(root) {
         return null;
     }
 }
-/**
- * Resolve the CURRENT upstream manifest version for a local-sourced plugin
- * (the `.system`/local-path case). Returns null for git sources — reading their
- * upstream version would need a network fetch, so git plugins are refreshed only
- * via the explicit `agents plugins update`.
- */
 export function getUpstreamManifestVersion(info) {
     if (info.isGit)
         return null;
@@ -1751,36 +1355,11 @@ export function getUpstreamManifestVersion(info) {
     const m = loadPluginManifest(resolved);
     return m?.version ?? null;
 }
-/**
- * Update an installed plugin by re-pulling from its original source.
- * Returns true if the update succeeded.
- */
-/**
- * Labels of exec surfaces present in `after` that were NOT present in `before`.
- * Used by updatePlugin to distinguish a newly-appearing execution surface
- * (upstream compromise → renewed consent required) from one the user already
- * trusted (leave enablement alone).
- */
 export function newExecSurfaceLabels(before, after) {
     return Object.keys(PLUGIN_EXEC_SURFACE_LABELS)
         .filter((key) => after[key] && !before[key])
         .map((key) => PLUGIN_EXEC_SURFACE_LABELS[key]);
 }
-/**
- * Re-fetch a plugin from its recorded source and apply the update to disk.
- *
- * Security (RUSH-1757): a plugin's upstream is mutable. `updatePlugin` never
- * mutates the live plugin tree before it has inspected the incoming content —
- * the new revision is fetched into a **quarantine** dir first, its capabilities
- * are diffed against the current on-disk baseline, and the update is applied to
- * `plugin.root` only after the trust decision. If the update introduces a NEW
- * executable surface (hooks/, .mcp.json, bin/, scripts/, settings.json,
- * permissions/) that the current revision did not carry, the update is refused
- * unless `options.allowExecSurfaces` is set — the last-good content is kept in
- * place, so a benign-then-compromised upstream can never execute on the next
- * update without renewed consent. A surface the user already trusted is not a
- * "new" surface and does not re-trigger the gate.
- */
 export async function updatePlugin(name, options = {}) {
     const plugin = getPlugin(name);
     if (!plugin) {
@@ -1797,23 +1376,17 @@ export async function updatePlugin(name, options = {}) {
     catch {
         return { success: false, error: `Could not read source info for '${name}'` };
     }
-    // Baseline: what the live (already-trusted) revision ships today.
     const before = inspectPluginCapabilities(plugin.root);
-    // Quarantine dir lives beside plugin.root (same filesystem) so the final
-    // apply can be a rename. The dot-prefix keeps it out of plugin discovery.
     const quarantine = path.join(path.dirname(plugin.root), `.${path.basename(plugin.root)}.update-quarantine`);
     const cleanupQuarantine = () => {
         try {
             fs.rmSync(quarantine, { recursive: true, force: true });
         }
-        catch { /* best effort */ }
+        catch { }
     };
     cleanupQuarantine();
     try {
-        // 1. Fetch the incoming revision into quarantine — never touch plugin.root yet.
         if (sourceInfo.isGit) {
-            // Copy the working checkout (with its .git) and fast-forward the copy, so a
-            // hostile upstream diff lands in the quarantine, not the live tree.
             fs.cpSync(plugin.root, quarantine, { recursive: true });
             execFileSync('git', ['-C', quarantine, 'pull', '--ff-only'], { stdio: 'pipe' });
         }
@@ -1825,11 +1398,8 @@ export async function updatePlugin(name, options = {}) {
             }
             fs.cpSync(resolvedSource, quarantine, { recursive: true });
         }
-        // 2. Diff capabilities of the incoming revision against the baseline.
         const after = inspectPluginCapabilities(quarantine);
         const newSurfaces = newExecSurfaceLabels(before, after);
-        // 3. Refuse a surface-introducing update without renewed consent. The
-        //    last-good content stays in place untouched.
         if (newSurfaces.length > 0 && options.allowExecSurfaces !== true) {
             cleanupQuarantine();
             return {
@@ -1840,8 +1410,6 @@ export async function updatePlugin(name, options = {}) {
                     `Re-run with --allow-exec-surfaces if you trust the source.`,
             };
         }
-        // 4. Apply: swap the quarantined revision into plugin.root, preserving the
-        //    user config and re-stamping .source.
         const userConfigPath = path.join(plugin.root, USER_CONFIG_FILE);
         const userConfigBackup = fs.existsSync(userConfigPath)
             ? fs.readFileSync(userConfigPath, 'utf-8')
@@ -1851,8 +1419,6 @@ export async function updatePlugin(name, options = {}) {
         if (userConfigBackup !== null) {
             fs.writeFileSync(userConfigPath, userConfigBackup, 'utf-8');
         }
-        // Re-stamp .source with the freshly pulled manifest version so the baseline
-        // tracks what's now on disk (keeps the heal "unmodified?" check honest).
         const freshVersion = loadPluginManifest(plugin.root)?.version;
         fs.writeFileSync(path.join(plugin.root, SOURCE_FILE), JSON.stringify({ ...sourceInfo, version: freshVersion }), 'utf-8');
         return { success: true, newExecSurfaces: newSurfaces, hasExecSurfaces: hasPluginExecSurfaces(after) };