@phnx-labs/agents-cli 1.18.2 → 1.18.4

package/dist/lib/plugin-marketplace.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Native plugin marketplace install path for Claude / OpenClaw.
+ *
+ * Plugins managed by agents-cli are exposed as a synthetic local marketplace
+ * named "agents-cli" under each version's plugin directory:
+ *
+ *   <versionHome>/.{claude,openclaw}/plugins/
+ *     known_marketplaces.json            # registers the "agents-cli" marketplace
+ *     marketplaces/agents-cli/
+ *       .claude-plugin/marketplace.json  # synthesized catalog
+ *       plugins/<plugin>/                # copied plugin source
+ *
+ * Plus the version's settings.json gets `enabledPlugins["<plugin>@agents-cli"] = true`.
+ *
+ * This produces native `/plugin:skill` slash namespacing, visibility in `/plugins`,
+ * and `/plugin enable|disable` support — matching the Claude Code spec at
+ * https://code.claude.com/docs/en/plugins and /plugin-marketplaces.
+ */
+import type { AgentId, DiscoveredPlugin } from './types.js';
+export declare const MARKETPLACE_NAME = "agents-cli";
+interface MarketplacePluginEntry {
+    name: string;
+    source: string;
+    description?: string;
+    version?: string;
+    author?: {
+        name: string;
+        email?: string;
+    };
+}
+interface MarketplaceManifest {
+    $schema?: string;
+    name: string;
+    description?: string;
+    owner: {
+        name: string;
+        email?: string;
+    };
+    plugins: MarketplacePluginEntry[];
+}
+export declare function marketplaceRoot(agent: AgentId, versionHome: string): string;
+export declare function marketplaceManifestPath(agent: AgentId, versionHome: string): string;
+export declare function pluginInstallDir(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): string;
+export declare function knownMarketplacesPath(agent: AgentId, versionHome: string): string;
+/**
+ * Copy plugin source into marketplace install dir.
+ * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ */
+export declare function copyPluginToMarketplace(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): string;
+/**
+ * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the list of
+ * plugins installed under <marketplace>/plugins/. Always run after add or remove
+ * so the manifest stays in lockstep with on-disk contents.
+ */
+export declare function syncMarketplaceManifest(agent: AgentId, versionHome: string): MarketplaceManifest | null;
+/**
+ * Register the agents-cli marketplace in known_marketplaces.json so Claude Code
+ * discovers it on startup. Idempotent: re-running just refreshes lastUpdated.
+ */
+export declare function registerMarketplace(agent: AgentId, versionHome: string): void;
+/**
+ * Drop the agents-cli marketplace entry from known_marketplaces.json.
+ * Called when the last plugin under it is removed.
+ */
+export declare function unregisterMarketplace(agent: AgentId, versionHome: string): void;
+/**
+ * Mark a plugin as enabled in <versionHome>/.{agent}/settings.json under
+ * enabledPlugins["<plugin>@agents-cli"]: true. Reads, mutates, writes —
+ * preserving every other key.
+ */
+export declare function enablePluginInSettings(pluginName: string, agent: AgentId, versionHome: string): void;
+/**
+ * Remove the enabledPlugins key for this plugin. Inverse of enablePluginInSettings.
+ */
+export declare function disablePluginInSettings(pluginName: string, agent: AgentId, versionHome: string): void;
+/**
+ * Remove a plugin's installed marketplace directory. Returns true if the dir
+ * existed and was removed.
+ */
+export declare function removePluginFromMarketplace(pluginName: string, agent: AgentId, versionHome: string): boolean;
+/**
+ * Return true if the marketplace has no plugins left under it.
+ */
+export declare function marketplaceIsEmpty(agent: AgentId, versionHome: string): boolean;
+/**
+ * Drop the entire marketplace directory. Called after the last plugin removal.
+ */
+export declare function removeEmptyMarketplaceDir(agent: AgentId, versionHome: string): void;
+/**
+ * Detect whether a plugin is installed via the native marketplace path.
+ */
+export declare function isInstalledInMarketplace(pluginName: string, agent: AgentId, versionHome: string): boolean;
+export {};

package/dist/lib/plugin-marketplace.js

@@ -0,0 +1,239 @@
+/**
+ * Native plugin marketplace install path for Claude / OpenClaw.
+ *
+ * Plugins managed by agents-cli are exposed as a synthetic local marketplace
+ * named "agents-cli" under each version's plugin directory:
+ *
+ *   <versionHome>/.{claude,openclaw}/plugins/
+ *     known_marketplaces.json            # registers the "agents-cli" marketplace
+ *     marketplaces/agents-cli/
+ *       .claude-plugin/marketplace.json  # synthesized catalog
+ *       plugins/<plugin>/                # copied plugin source
+ *
+ * Plus the version's settings.json gets `enabledPlugins["<plugin>@agents-cli"] = true`.
+ *
+ * This produces native `/plugin:skill` slash namespacing, visibility in `/plugins`,
+ * and `/plugin enable|disable` support — matching the Claude Code spec at
+ * https://code.claude.com/docs/en/plugins and /plugin-marketplaces.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const MARKETPLACE_NAME = 'agents-cli';
+function pluginsRootForVersion(agent, versionHome) {
+    return path.join(versionHome, `.${agent}`, 'plugins');
+}
+export function marketplaceRoot(agent, versionHome) {
+    return path.join(pluginsRootForVersion(agent, versionHome), 'marketplaces', MARKETPLACE_NAME);
+}
+export function marketplaceManifestPath(agent, versionHome) {
+    return path.join(marketplaceRoot(agent, versionHome), '.claude-plugin', 'marketplace.json');
+}
+export function pluginInstallDir(plugin, agent, versionHome) {
+    return path.join(marketplaceRoot(agent, versionHome), 'plugins', plugin.name);
+}
+export function knownMarketplacesPath(agent, versionHome) {
+    return path.join(pluginsRootForVersion(agent, versionHome), 'known_marketplaces.json');
+}
+function settingsPath(agent, versionHome) {
+    return path.join(versionHome, `.${agent}`, 'settings.json');
+}
+/**
+ * Copy plugin source into marketplace install dir.
+ * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ */
+export function copyPluginToMarketplace(plugin, agent, versionHome) {
+    const dest = pluginInstallDir(plugin, agent, versionHome);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest)) {
+        fs.rmSync(dest, { recursive: true, force: true });
+    }
+    fs.cpSync(plugin.root, dest, { recursive: true, dereference: false });
+    return dest;
+}
+/**
+ * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the list of
+ * plugins installed under <marketplace>/plugins/. Always run after add or remove
+ * so the manifest stays in lockstep with on-disk contents.
+ */
+export function syncMarketplaceManifest(agent, versionHome) {
+    const root = marketplaceRoot(agent, versionHome);
+    const pluginsDir = path.join(root, 'plugins');
+    if (!fs.existsSync(pluginsDir))
+        return null;
+    const entries = [];
+    for (const entry of fs.readdirSync(pluginsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const manifestFile = path.join(pluginsDir, entry.name, '.claude-plugin', 'plugin.json');
+        if (!fs.existsSync(manifestFile))
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        entries.push({
+            name: manifest.name,
+            source: `./plugins/${manifest.name}`,
+            description: manifest.description,
+            version: manifest.version,
+            ...(manifest.author ? { author: manifest.author } : {}),
+        });
+    }
+    const manifest = {
+        $schema: 'https://anthropic.com/claude-code/marketplace.schema.json',
+        name: MARKETPLACE_NAME,
+        description: 'Plugins managed by agents-cli',
+        owner: { name: 'agents-cli' },
+        plugins: entries.sort((a, b) => a.name.localeCompare(b.name)),
+    };
+    const manifestPath = marketplaceManifestPath(agent, versionHome);
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    return manifest;
+}
+/**
+ * Register the agents-cli marketplace in known_marketplaces.json so Claude Code
+ * discovers it on startup. Idempotent: re-running just refreshes lastUpdated.
+ */
+export function registerMarketplace(agent, versionHome) {
+    const root = marketplaceRoot(agent, versionHome);
+    const knownPath = knownMarketplacesPath(agent, versionHome);
+    let known = {};
+    if (fs.existsSync(knownPath)) {
+        try {
+            known = JSON.parse(fs.readFileSync(knownPath, 'utf-8'));
+        }
+        catch {
+            known = {};
+        }
+    }
+    known[MARKETPLACE_NAME] = {
+        source: { source: 'local', path: root },
+        installLocation: root,
+        lastUpdated: new Date().toISOString(),
+    };
+    fs.mkdirSync(path.dirname(knownPath), { recursive: true });
+    fs.writeFileSync(knownPath, JSON.stringify(known, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Drop the agents-cli marketplace entry from known_marketplaces.json.
+ * Called when the last plugin under it is removed.
+ */
+export function unregisterMarketplace(agent, versionHome) {
+    const knownPath = knownMarketplacesPath(agent, versionHome);
+    if (!fs.existsSync(knownPath))
+        return;
+    let known;
+    try {
+        known = JSON.parse(fs.readFileSync(knownPath, 'utf-8'));
+    }
+    catch {
+        return;
+    }
+    if (!(MARKETPLACE_NAME in known))
+        return;
+    delete known[MARKETPLACE_NAME];
+    if (Object.keys(known).length === 0) {
+        try {
+            fs.unlinkSync(knownPath);
+        }
+        catch { /* ignore */ }
+    }
+    else {
+        fs.writeFileSync(knownPath, JSON.stringify(known, null, 2) + '\n', 'utf-8');
+    }
+}
+/**
+ * Mark a plugin as enabled in <versionHome>/.{agent}/settings.json under
+ * enabledPlugins["<plugin>@agents-cli"]: true. Reads, mutates, writes —
+ * preserving every other key.
+ */
+export function enablePluginInSettings(pluginName, agent, versionHome) {
+    const sPath = settingsPath(agent, versionHome);
+    let settings = {};
+    if (fs.existsSync(sPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(sPath, 'utf-8'));
+        }
+        catch {
+            settings = {};
+        }
+    }
+    if (!settings.enabledPlugins || typeof settings.enabledPlugins !== 'object') {
+        settings.enabledPlugins = {};
+    }
+    const enabled = settings.enabledPlugins;
+    const key = `${pluginName}@${MARKETPLACE_NAME}`;
+    if (enabled[key] === true)
+        return;
+    enabled[key] = true;
+    fs.mkdirSync(path.dirname(sPath), { recursive: true });
+    fs.writeFileSync(sPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Remove the enabledPlugins key for this plugin. Inverse of enablePluginInSettings.
+ */
+export function disablePluginInSettings(pluginName, agent, versionHome) {
+    const sPath = settingsPath(agent, versionHome);
+    if (!fs.existsSync(sPath))
+        return;
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(sPath, 'utf-8'));
+    }
+    catch {
+        return;
+    }
+    const enabled = settings.enabledPlugins;
+    if (!enabled)
+        return;
+    const key = `${pluginName}@${MARKETPLACE_NAME}`;
+    if (!(key in enabled))
+        return;
+    delete enabled[key];
+    if (Object.keys(enabled).length === 0) {
+        delete settings.enabledPlugins;
+    }
+    fs.writeFileSync(sPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Remove a plugin's installed marketplace directory. Returns true if the dir
+ * existed and was removed.
+ */
+export function removePluginFromMarketplace(pluginName, agent, versionHome) {
+    const installed = path.join(marketplaceRoot(agent, versionHome), 'plugins', pluginName);
+    if (!fs.existsSync(installed))
+        return false;
+    fs.rmSync(installed, { recursive: true, force: true });
+    return true;
+}
+/**
+ * Return true if the marketplace has no plugins left under it.
+ */
+export function marketplaceIsEmpty(agent, versionHome) {
+    const pluginsDir = path.join(marketplaceRoot(agent, versionHome), 'plugins');
+    if (!fs.existsSync(pluginsDir))
+        return true;
+    const remaining = fs.readdirSync(pluginsDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && !d.name.startsWith('.'));
+    return remaining.length === 0;
+}
+/**
+ * Drop the entire marketplace directory. Called after the last plugin removal.
+ */
+export function removeEmptyMarketplaceDir(agent, versionHome) {
+    const root = marketplaceRoot(agent, versionHome);
+    if (!fs.existsSync(root))
+        return;
+    fs.rmSync(root, { recursive: true, force: true });
+}
+/**
+ * Detect whether a plugin is installed via the native marketplace path.
+ */
+export function isInstalledInMarketplace(pluginName, agent, versionHome) {
+    const installed = path.join(marketplaceRoot(agent, versionHome), 'plugins', pluginName);
+    return fs.existsSync(path.join(installed, '.claude-plugin', 'plugin.json'));
+}

package/dist/lib/plugins.d.ts

@@ -35,6 +35,12 @@ export declare function discoverPluginCommands(pluginRoot: string): string[];
 export declare function discoverPluginAgentDefs(pluginRoot: string): string[];
 /** Discover executable files in a plugin's bin/ directory. */
 export declare function discoverPluginBin(pluginRoot: string): string[];
+/** Discover MCP server names from .mcp.json at the plugin root. */
+export declare function discoverPluginMcpServers(pluginRoot: string): string[];
+/** Discover LSP server keys from .lsp.json at the plugin root. */
+export declare function discoverPluginLspServers(pluginRoot: string): string[];
+/** Discover monitor names from monitors/monitors.json. */
+export declare function discoverPluginMonitors(pluginRoot: string): string[];
 /**
  * Expand plugin variables in a string.
  *
@@ -60,15 +66,18 @@ export declare function checkPluginDependencies(manifest: PluginManifest): strin
 /**
  * Sync a plugin to a specific agent version's home directory.
  *
- * For Claude:
- *   1. Copy plugin skills into version's skills dir (prefixed: pluginName--skillName)
- *   2. Copy plugin commands into version's commands dir (prefixed: pluginName--cmdName.md)
- *   3. Copy plugin agent defs into version's agents dir (prefixed: pluginName--agentName.md)
- *   4. Copy plugin bin/ into version home plugin-bin/<pluginName>/, note path in settings
- *   5. Read hooks/hooks.json, expand vars, merge into settings.json hooks
- *   6. Read .mcp.json, expand vars, merge mcpServers into settings.json
- *   7. Read settings.json, merge non-permission keys non-destructively into settings.json
- *   8. Read settings.json permissions, expand vars, merge into settings.json
+ * 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.
  */
 export declare function syncPluginToVersion(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): {
     success: boolean;
@@ -82,8 +91,9 @@ export declare function syncPluginToVersion(plugin: DiscoveredPlugin, agent: Age
     settings: boolean;
 };
 /**
- * Check if a plugin is synced to a version by inspecting the version home.
- * Checks skills, commands, agent defs, bin, hook commands, and permissions.
+ * 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 declare function isPluginSynced(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): boolean;
 /**
@@ -102,8 +112,10 @@ export declare function removePluginFromVersion(pluginName: string, pluginRoot:
     mcp: number;
 };
 /**
- * Remove orphaned plugin skill directories from a version home.
- * Soft-deletes to ~/.agents/.trash/plugins/.
+ * Remove orphaned plugin entries from a version home. An entry is "orphan" if
+ * its plugin name is not in the active plugin set. 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.
  */
 export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>, version?: string): string[];
 export interface VersionPluginDiff {