@phnx-labs/agents-cli 1.20.3 → 1.20.5

package/dist/lib/plugin-marketplace.js

@@ -1,70 +1,222 @@
 /**
- * Native plugin marketplace install path for Claude / OpenClaw.
+ * Native plugin marketplaces for Claude / OpenClaw — one per DotAgents repo.
  *
- * Plugins managed by agents-cli are exposed as a synthetic local marketplace
- * named "agents-cli" under each version's plugin directory:
+ * Every DotAgents repo that holds plugins synthesizes its OWN synthetic local
+ * marketplace under each version's plugin directory, named after the repo:
  *
  *   <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
+ *     known_marketplaces.json                    # registers each repo's marketplace
+ *     marketplaces/agents-cli/                    # ~/.agents/plugins/*        (user repo)
+ *     marketplaces/agents-<alias>/                # ~/.agents-<alias>/plugins/* (extra repo)
+ *     marketplaces/agents-project/                # <cwd>/.agents/plugins/*    (project repo)
+ *       .claude-plugin/marketplace.json           # synthesized catalog
+ *       plugins/<plugin>/                         # copied plugin source
  *
- * Plus the version's settings.json gets `enabledPlugins["<plugin>@agents-cli"] = true`.
+ * Plus the version's settings.json gets
+ *   `enabledPlugins["<plugin>@<marketplace>"] = 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.
+ * This produces native `/plugin:skill` slash namespacing, visibility in
+ * `/plugins`, `/plugin enable|disable` support, AND honest attribution (the
+ * user can see which repo each plugin came from) — matching the Claude Code
+ * spec at https://code.claude.com/docs/en/plugins and /plugin-marketplaces.
+ *
+ * The naming policy lives in one place — marketplaceNameFor(). Source-side
+ * discovery (discoverMarketplaces) and per-version synthesis (syncMarketplaceManifest
+ * / registerMarketplace / syncAllMarketplaces) all key off a MarketplaceSpec so
+ * the catalog name and on-disk layout are derived, never hard-coded per call.
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { getPluginsDir, getEnabledExtraRepos, getProjectPluginsDir } from './state.js';
+import { agentConfigDirName } from './agents.js';
+/**
+ * Canonical name for the user-repo marketplace (~/.agents/plugins/). Kept as an
+ * exported constant for callers that operate on the user repo directly and for
+ * the `marketplaces/agents-cli/` on-disk path that existing installs already have.
+ */
 export const MARKETPLACE_NAME = 'agents-cli';
+export const SYSTEM_MARKETPLACE_NAME = 'agents-system';
+/** Marketplace name for <cwd>/.agents/plugins/*. */
+export const PROJECT_MARKETPLACE_NAME = 'agents-project';
+// ─── Naming policy (single source of truth) ──────────────────────────────────
+/**
+ * Map a MarketplaceSpec to its catalog name. This is the ONLY place that
+ * encodes the repo → name policy; every other function derives the name here.
+ */
+export function marketplaceNameFor(spec) {
+    switch (spec.kind) {
+        case 'user': return MARKETPLACE_NAME; // "agents-cli"
+        case 'extra': return `agents-${spec.alias}`; // e.g. "agents-extras"
+        case 'project': return PROJECT_MARKETPLACE_NAME; // "agents-project"
+        case 'system': return SYSTEM_MARKETPLACE_NAME; // "agents-system"
+    }
+}
+/** Resolve a spec-or-name argument to the bare marketplace name string. */
+function nameOf(specOrName) {
+    return typeof specOrName === 'string' ? specOrName : marketplaceNameFor(specOrName);
+}
+function descriptionFor(spec) {
+    switch (spec.kind) {
+        case 'user': return 'Plugins from the user repo (~/.agents/plugins/)';
+        case 'extra': return `Plugins from extra repo "${spec.alias}" (~/.agents-${spec.alias}/plugins/)`;
+        case 'project': return 'Project-scoped plugins from <cwd>/.agents/plugins/';
+        case 'system': return 'Plugins from the system repo (~/.agents/.system/plugins/)';
+    }
+}
+// ─── Source-side discovery ────────────────────────────────────────────────────
+/**
+ * Discover every DotAgents repo that contributes plugins, in precedence order
+ * (user, then each enabled extra repo, then the project repo when cwd has one).
+ * No agent / version is involved — this walks source-side plugin roots only.
+ *
+ * A repo is included when its plugins/ directory exists on disk. The user repo
+ * is always probed; extras come from getEnabledExtraRepos() (already filtered to
+ * enabled + on-disk repos); the project repo is included only when
+ * <cwd>/.agents/plugins/ exists.
+ */
+export function discoverMarketplaces(opts = {}) {
+    const out = [];
+    // User repo — always the canonical "agents-cli" marketplace.
+    const userRoot = getPluginsDir();
+    if (dirExists(userRoot)) {
+        const spec = { kind: 'user' };
+        out.push({ spec, name: marketplaceNameFor(spec), pluginsRoot: userRoot, description: descriptionFor(spec) });
+    }
+    // Extra repos — peer ~/.agents-<alias>/ clones (and user-owned path:-repos).
+    for (const extra of getEnabledExtraRepos()) {
+        const pluginsRoot = path.join(extra.dir, 'plugins');
+        if (!dirExists(pluginsRoot))
+            continue;
+        const spec = { kind: 'extra', alias: extra.alias, root: pluginsRoot };
+        out.push({ spec, name: marketplaceNameFor(spec), pluginsRoot, description: descriptionFor(spec) });
+    }
+    // Project repo — <cwd>/.agents/plugins/.
+    const projectRoot = getProjectPluginsDir(opts.cwd ?? process.cwd());
+    if (projectRoot && dirExists(projectRoot)) {
+        const spec = { kind: 'project', root: projectRoot };
+        out.push({ spec, name: marketplaceNameFor(spec), pluginsRoot: projectRoot, description: descriptionFor(spec) });
+    }
+    return out;
+}
+function dirExists(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Per-version paths ────────────────────────────────────────────────────────
 function pluginsRootForVersion(agent, versionHome) {
-    return path.join(versionHome, `.${agent}`, 'plugins');
+    return path.join(versionHome, agentConfigDirName(agent), 'plugins');
 }
-export function marketplaceRoot(agent, versionHome) {
-    return path.join(pluginsRootForVersion(agent, versionHome), 'marketplaces', MARKETPLACE_NAME);
+export function marketplaceRoot(specOrName, agent, versionHome) {
+    return path.join(pluginsRootForVersion(agent, versionHome), 'marketplaces', nameOf(specOrName));
 }
-export function marketplaceManifestPath(agent, versionHome) {
-    return path.join(marketplaceRoot(agent, versionHome), '.claude-plugin', 'marketplace.json');
+export function marketplaceManifestPath(specOrName, agent, versionHome) {
+    return path.join(marketplaceRoot(specOrName, agent, versionHome), '.claude-plugin', 'marketplace.json');
 }
-export function pluginInstallDir(plugin, agent, versionHome) {
-    return path.join(marketplaceRoot(agent, versionHome), 'plugins', plugin.name);
+export function pluginInstallDir(plugin, specOrName, agent, versionHome) {
+    return path.join(marketplaceRoot(specOrName, 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');
+    return path.join(versionHome, agentConfigDirName(agent), 'settings.json');
 }
+// ─── Copy plugin source into a marketplace ────────────────────────────────────
 /**
- * Copy plugin source into marketplace install dir.
- * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ * Copy plugin source into the marketplace install dir for the given spec.
+ * Source of truth remains the plugin's source dir — this is a per-version snapshot.
+ *
+ * Symlinks pointing OUTSIDE the plugin source root are dropped. They show up
+ * when plugin authors (legitimately) link prompt-side references to sibling
+ * codebases — e.g. the rush plugin's `app -> ../../../rush/app` for @app/...
+ * autocomplete in user prompts. Faithfully copying those symlinks pollutes
+ * the marketplace with gigabytes of node_modules / .next / brand-asset video
+ * that the consumer (Claude Code, OpenClaw) then walks during plugin
+ * discovery — which is the documented cause of multi-minute startup hangs.
+ *
+ * Internal symlinks (target stays inside the plugin root) are preserved.
  */
-export function copyPluginToMarketplace(plugin, agent, versionHome) {
-    const dest = pluginInstallDir(plugin, agent, versionHome);
+export function copyPluginToMarketplace(plugin, spec, agent, versionHome) {
+    const dest = pluginInstallDir(plugin, spec, 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 });
+    const sourceRealRoot = (() => {
+        try {
+            return fs.realpathSync(plugin.root);
+        }
+        catch {
+            return plugin.root;
+        }
+    })();
+    const skipped = [];
+    fs.cpSync(plugin.root, dest, {
+        recursive: true,
+        dereference: false,
+        filter: (src) => {
+            try {
+                const stat = fs.lstatSync(src);
+                if (!stat.isSymbolicLink())
+                    return true;
+                const target = fs.realpathSync(src);
+                if (target === sourceRealRoot || target.startsWith(sourceRealRoot + path.sep)) {
+                    return true;
+                }
+                skipped.push(path.relative(plugin.root, src) || path.basename(src));
+                return false;
+            }
+            catch {
+                // Dangling symlink or stat failure — drop it; it can't be useful in
+                // the marketplace and would error the consumer's walk anyway.
+                skipped.push(path.relative(plugin.root, src) || path.basename(src));
+                return false;
+            }
+        },
+    });
+    if (skipped.length > 0) {
+        process.stderr.write(`agents-cli: plugin '${plugin.name}' has ${skipped.length} symlink(s) ` +
+            `pointing outside its source root; not copied to marketplace ` +
+            `(would bloat consumer startup): ${skipped.join(', ')}\n`);
+    }
     return dest;
 }
+// ─── Catalog synthesis ──────────────────────────────────────────────────────
 /**
- * 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.
+ * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the plugins
+ * already installed under <marketplace>/plugins/. Always run after add or remove
+ * so the manifest stays in lockstep with on-disk contents. Returns the manifest
+ * it wrote, or null when the marketplace has no plugins dir yet.
  */
-export function syncMarketplaceManifest(agent, versionHome) {
-    const root = marketplaceRoot(agent, versionHome);
+export function syncMarketplaceManifest(spec, agent, versionHome) {
+    const name = marketplaceNameFor(spec);
+    const root = marketplaceRoot(spec, 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('.'))
+        if (entry.name.startsWith('.'))
             continue;
-        const manifestFile = path.join(pluginsDir, entry.name, '.claude-plugin', 'plugin.json');
+        // Follow symlinks: Dirent.isDirectory() is false for a symlink even when the
+        // target is a directory. statSync follows the link.
+        const entryPath = path.join(pluginsDir, entry.name);
+        let isDir = entry.isDirectory();
+        if (!isDir && entry.isSymbolicLink()) {
+            try {
+                isDir = fs.statSync(entryPath).isDirectory();
+            }
+            catch {
+                isDir = false;
+            }
+        }
+        if (!isDir)
+            continue;
+        const manifestFile = path.join(entryPath, '.claude-plugin', 'plugin.json');
         if (!fs.existsSync(manifestFile))
             continue;
         let manifest;
@@ -84,22 +236,25 @@ export function syncMarketplaceManifest(agent, versionHome) {
     }
     const manifest = {
         $schema: 'https://anthropic.com/claude-code/marketplace.schema.json',
-        name: MARKETPLACE_NAME,
-        description: 'Plugins managed by agents-cli',
+        name,
+        description: descriptionFor(spec),
         owner: { name: 'agents-cli' },
         plugins: entries.sort((a, b) => a.name.localeCompare(b.name)),
     };
-    const manifestPath = marketplaceManifestPath(agent, versionHome);
+    const manifestPath = marketplaceManifestPath(spec, agent, versionHome);
     fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
     return manifest;
 }
+// ─── Registration in known_marketplaces.json ──────────────────────────────────
 /**
- * Register the agents-cli marketplace in known_marketplaces.json so Claude Code
- * discovers it on startup. Idempotent: re-running just refreshes lastUpdated.
+ * Register a marketplace in known_marketplaces.json so Claude Code discovers
+ * it on startup. Idempotent: re-running just refreshes lastUpdated. Other
+ * marketplaces' entries are preserved untouched.
  */
-export function registerMarketplace(agent, versionHome) {
-    const root = marketplaceRoot(agent, versionHome);
+export function registerMarketplace(spec, agent, versionHome) {
+    const name = marketplaceNameFor(spec);
+    const root = marketplaceRoot(spec, agent, versionHome);
     const knownPath = knownMarketplacesPath(agent, versionHome);
     let known = {};
     if (fs.existsSync(knownPath)) {
@@ -110,7 +265,7 @@ export function registerMarketplace(agent, versionHome) {
             known = {};
         }
     }
-    known[MARKETPLACE_NAME] = {
+    known[name] = {
         source: { source: 'directory', path: root },
         installLocation: root,
         lastUpdated: new Date().toISOString(),
@@ -119,10 +274,12 @@ export function registerMarketplace(agent, versionHome) {
     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.
+ * Drop a marketplace entry from known_marketplaces.json. Called when the last
+ * plugin under it is removed. Removes only its own entry; deletes the file only
+ * when no entries remain.
  */
-export function unregisterMarketplace(agent, versionHome) {
+export function unregisterMarketplace(specOrName, agent, versionHome) {
+    const name = nameOf(specOrName);
     const knownPath = knownMarketplacesPath(agent, versionHome);
     if (!fs.existsSync(knownPath))
         return;
@@ -133,9 +290,9 @@ export function unregisterMarketplace(agent, versionHome) {
     catch {
         return;
     }
-    if (!(MARKETPLACE_NAME in known))
+    if (!(name in known))
         return;
-    delete known[MARKETPLACE_NAME];
+    delete known[name];
     if (Object.keys(known).length === 0) {
         try {
             fs.unlinkSync(knownPath);
@@ -146,15 +303,38 @@ export function unregisterMarketplace(agent, versionHome) {
         fs.writeFileSync(knownPath, JSON.stringify(known, null, 2) + '\n', 'utf-8');
     }
 }
+// ─── Top-level orchestration ──────────────────────────────────────────────────
 /**
- * Mark a plugin as enabled in <versionHome>/.{agent}/settings.json under
- * enabledPlugins["<plugin>@agents-cli"]: true. Reads, mutates, writes —
- * preserving every other key.
+ * Discover every source-side marketplace, then for each one re-synthesize its
+ * catalog from the plugins already copied under the version home and register
+ * it in known_marketplaces.json. Returns one result per marketplace that has at
+ * least one plugin installed.
+ *
+ * Copying plugin source into a marketplace is the caller's responsibility
+ * (copyPluginToMarketplace / syncPluginToVersion) — this reconciles catalogs +
+ * registrations across all repos once the copies are in place. Marketplaces
+ * whose version-home plugins dir is empty or absent are skipped, so we never
+ * register a known_marketplace pointing at a directory with no catalog.
  */
-export function enablePluginInSettings(pluginName, agent, versionHome, options = {}) {
-    if (!options.allowExecSurfaces && marketplacePluginHasExecSurfaces(pluginName, agent, versionHome)) {
-        return;
+export function syncAllMarketplaces(agent, versionHome, opts = {}) {
+    const results = [];
+    for (const dm of discoverMarketplaces(opts)) {
+        const manifest = syncMarketplaceManifest(dm.spec, agent, versionHome);
+        if (!manifest || manifest.plugins.length === 0)
+            continue;
+        registerMarketplace(dm.spec, agent, versionHome);
+        results.push({ spec: dm.spec, name: dm.name, plugins: manifest.plugins.length });
     }
+    return results;
+}
+// ─── Per-plugin settings ops ──────────────────────────────────────────────────
+/**
+ * Mark a plugin as enabled in <versionHome>/.{agent}/settings.json under
+ * enabledPlugins["<plugin>@<marketplace>"]: true. Reads, mutates, writes —
+ * preserving every other key. Trust/exec-surface gating is the caller's
+ * responsibility (plugins.ts owns plugin capability inspection).
+ */
+export function addPluginToSettings(pluginName, marketplaceName, agent, versionHome) {
     const sPath = settingsPath(agent, versionHome);
     let settings = {};
     if (fs.existsSync(sPath)) {
@@ -169,49 +349,17 @@ export function enablePluginInSettings(pluginName, agent, versionHome, options =
         settings.enabledPlugins = {};
     }
     const enabled = settings.enabledPlugins;
-    const key = `${pluginName}@${MARKETPLACE_NAME}`;
+    const key = `${pluginName}@${marketplaceName}`;
     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');
 }
-function marketplacePluginHasExecSurfaces(pluginName, agent, versionHome) {
-    const root = path.join(marketplaceRoot(agent, versionHome), 'plugins', pluginName);
-    if (fs.existsSync(path.join(root, '.mcp.json')))
-        return true;
-    for (const dir of ['bin', 'scripts', 'permissions']) {
-        if (fs.existsSync(path.join(root, dir)))
-            return true;
-    }
-    const hooksFile = path.join(root, 'hooks', 'hooks.json');
-    if (fs.existsSync(hooksFile))
-        return true;
-    const hooksDir = path.join(root, 'hooks');
-    if (fs.existsSync(hooksDir)) {
-        try {
-            if (fs.readdirSync(hooksDir).some((entry) => !entry.startsWith('.')))
-                return true;
-        }
-        catch {
-            return true;
-        }
-    }
-    const settingsFile = path.join(root, 'settings.json');
-    if (!fs.existsSync(settingsFile))
-        return false;
-    try {
-        const settings = JSON.parse(fs.readFileSync(settingsFile, 'utf-8'));
-        return Object.keys(settings).some((key) => key !== 'permissions') || 'permissions' in settings;
-    }
-    catch {
-        return true;
-    }
-}
 /**
- * Remove the enabledPlugins key for this plugin. Inverse of enablePluginInSettings.
+ * Remove the enabledPlugins key for this plugin. Inverse of addPluginToSettings.
  */
-export function disablePluginInSettings(pluginName, agent, versionHome) {
+export function removePluginFromSettings(pluginName, marketplaceName, agent, versionHome) {
     const sPath = settingsPath(agent, versionHome);
     if (!fs.existsSync(sPath))
         return;
@@ -225,7 +373,7 @@ export function disablePluginInSettings(pluginName, agent, versionHome) {
     const enabled = settings.enabledPlugins;
     if (!enabled)
         return;
-    const key = `${pluginName}@${MARKETPLACE_NAME}`;
+    const key = `${pluginName}@${marketplaceName}`;
     if (!(key in enabled))
         return;
     delete enabled[key];
@@ -234,12 +382,13 @@ export function disablePluginInSettings(pluginName, agent, versionHome) {
     }
     fs.writeFileSync(sPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
 }
+// ─── Marketplace teardown helpers ─────────────────────────────────────────────
 /**
  * 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);
+export function removePluginFromMarketplace(pluginName, specOrName, agent, versionHome) {
+    const installed = path.join(marketplaceRoot(specOrName, agent, versionHome), 'plugins', pluginName);
     if (!fs.existsSync(installed))
         return false;
     fs.rmSync(installed, { recursive: true, force: true });
@@ -248,8 +397,8 @@ export function removePluginFromMarketplace(pluginName, agent, versionHome) {
 /**
  * Return true if the marketplace has no plugins left under it.
  */
-export function marketplaceIsEmpty(agent, versionHome) {
-    const pluginsDir = path.join(marketplaceRoot(agent, versionHome), 'plugins');
+export function marketplaceIsEmpty(specOrName, agent, versionHome) {
+    const pluginsDir = path.join(marketplaceRoot(specOrName, agent, versionHome), 'plugins');
     if (!fs.existsSync(pluginsDir))
         return true;
     const remaining = fs.readdirSync(pluginsDir, { withFileTypes: true })
@@ -259,8 +408,8 @@ export function marketplaceIsEmpty(agent, versionHome) {
 /**
  * Drop the entire marketplace directory. Called after the last plugin removal.
  */
-export function removeEmptyMarketplaceDir(agent, versionHome) {
-    const root = marketplaceRoot(agent, versionHome);
+export function removeEmptyMarketplaceDir(specOrName, agent, versionHome) {
+    const root = marketplaceRoot(specOrName, agent, versionHome);
     if (!fs.existsSync(root))
         return;
     fs.rmSync(root, { recursive: true, force: true });
@@ -268,7 +417,7 @@ export function removeEmptyMarketplaceDir(agent, versionHome) {
 /**
  * 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);
+export function isInstalledInMarketplace(pluginName, specOrName, agent, versionHome) {
+    const installed = path.join(marketplaceRoot(specOrName, agent, versionHome), 'plugins', pluginName);
     return fs.existsSync(path.join(installed, '.claude-plugin', 'plugin.json'));
 }

package/dist/lib/plugins.d.ts

@@ -8,7 +8,7 @@
  * module discovers plugins, validates their manifests, and syncs their
  * contents into agent version homes.
  */
-import type { AgentId, DiscoveredPlugin, PluginManifest } from './types.js';
+import type { AgentId, DiscoveredPlugin, PluginManifest, MarketplaceSpec } from './types.js';
 export interface PluginCapabilities {
     hasHooks: boolean;
     hasMcp: boolean;
@@ -19,11 +19,28 @@ export interface PluginCapabilities {
 }
 export declare const PLUGIN_EXEC_SURFACE_LABELS: Record<keyof PluginCapabilities, string>;
 /**
- * Discover all plugins in ~/.agents/plugins/.
+ * 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 declare function discoverPlugins(): DiscoveredPlugin[];
-export declare function buildDiscoveredPlugin(pluginRoot: string, manifest: PluginManifest): DiscoveredPlugin;
+export declare function discoverPluginsInDir(pluginsDir: string, spec?: MarketplaceSpec): DiscoveredPlugin[];
+/**
+ * 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 declare function discoverPlugins(opts?: {
+    cwd?: string;
+}): DiscoveredPlugin[];
+export declare function buildDiscoveredPlugin(pluginRoot: string, manifest: PluginManifest, spec?: MarketplaceSpec): DiscoveredPlugin;
 export declare function inspectPluginCapabilities(pluginRoot: string): PluginCapabilities;
 export declare function hasPluginExecSurfaces(capabilities: PluginCapabilities): boolean;
 export declare function pluginCapabilityLabels(capabilities: PluginCapabilities): string[];