@yagni-app/code 1.0.6 → 1.0.8

package/dist/pluginCommand.js

@@ -0,0 +1,499 @@
+/**
+ * `yagni plugin …` — install, remove, and update Claude Code plugins from
+ * marketplaces without leaving YAGNI Code, mirroring Claude Code's own
+ * `claude plugin` surface (marketplace add/list/update/remove, install,
+ * uninstall, enable, disable, update, list).
+ *
+ * State lives in YAGNI's own ledger (pluginStore.ts). Plugins Claude Code
+ * installed are still mirrored read-only (claudePlugins.ts) and show up in
+ * `list` labelled as such, so a developer sees one honest inventory: what
+ * loads, where it came from, and which components (hooks) are not bridged.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join, sep } from "node:path";
+import { pluginInventory, readTrustDecision } from "./claudeCompat.js";
+import { discoverClaudePlugins } from "./claudePlugins.js";
+import { agentDir } from "./credentials.js";
+import { DISTRIBUTION } from "./distribution.js";
+import { PluginStoreError, addMarketplace, catalog, describeSource, installPlugin, parseMarketplaceSource, pluginsHome, pruneCache, readKnownMarketplaces, readLedger, removeMarketplace, setPluginEnabled, uninstallPlugin, updateMarketplace, updatePlugins, } from "./pluginStore.js";
+import { getActiveProfileName } from "./profiles.js";
+const cmd = DISTRIBUTION.commandName;
+const USAGE = `Usage:
+  ${cmd} plugin marketplace add <owner/repo | git-url | path>
+  ${cmd} plugin marketplace list
+  ${cmd} plugin marketplace update [name]
+  ${cmd} plugin marketplace remove <name>
+  ${cmd} plugin install <plugin>[@marketplace] [-s user|project]
+  ${cmd} plugin uninstall <plugin>[@marketplace] [-s user|project]
+  ${cmd} plugin enable <plugin>[@marketplace]
+  ${cmd} plugin disable <plugin>[@marketplace]
+  ${cmd} plugin update [<plugin>[@marketplace]]
+  ${cmd} plugin list [--available]
+  ${cmd} plugin inventory --json      (machine-readable; backs the in-session /plugin panel)
+
+In a session: /plugin opens the same panel; /reload-plugins applies changes
+without restarting.
+
+Scopes (install/uninstall):
+  user     available in all your projects (default)
+  project  only inside this repo
+
+What loads from a plugin: skills, commands, agents, and MCP servers
+(.mcp.json at the plugin root). Hooks and LSP servers are not bridged;
+\`plugin list\` says so per plugin. State: ~/.yagni-code/plugins.
+Plugins installed with Claude Code itself are picked up too (read-only).
+
+Examples:
+  ${cmd} plugin marketplace add acme/claude-plugins
+  ${cmd} plugin install code-review@acme-plugins
+  ${cmd} plugin update
+`;
+export function parsePluginArgs(args) {
+    const out = {
+        subcommand: undefined,
+        positionals: [],
+        scope: "user",
+        scopeExplicit: false,
+        available: false,
+        json: false,
+    };
+    const scopeFrom = (value) => {
+        if (value === "user" || value === "project")
+            return value;
+        throw new Error(`Invalid scope "${value ?? ""}" — expected user or project.`);
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "-s" || arg === "--scope") {
+            out.scope = scopeFrom(args[++i]);
+            out.scopeExplicit = true;
+            continue;
+        }
+        if (arg.startsWith("--scope=")) {
+            out.scope = scopeFrom(arg.slice("--scope=".length));
+            out.scopeExplicit = true;
+            continue;
+        }
+        if (arg === "--available" || arg === "-a") {
+            out.available = true;
+            continue;
+        }
+        if (arg === "--json") {
+            out.json = true;
+            continue;
+        }
+        if (arg === "-h" || arg === "--help") {
+            out.subcommand = "help";
+            continue;
+        }
+        if (arg.startsWith("-"))
+            throw new Error(`Unknown option "${arg}".`);
+        if (out.subcommand === undefined)
+            out.subcommand = arg;
+        else
+            out.positionals.push(arg);
+    }
+    return out;
+}
+/** The repo root a project-scope install applies to: nearest `.git` ancestor, else cwd. */
+export function resolveRepoRoot(cwd) {
+    let current = cwd;
+    for (;;) {
+        if (existsSync(join(current, ".git")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return cwd;
+        current = parent;
+    }
+}
+export async function pluginCommand(args, deps = {}) {
+    const stdout = deps.stdout ?? ((t) => process.stdout.write(t));
+    const stderr = deps.stderr ?? ((t) => process.stderr.write(t));
+    const cwd = deps.cwd ?? process.cwd();
+    const home = deps.home ?? homedir();
+    const env = deps.env ?? process.env;
+    const io = {
+        cwd,
+        home,
+        env,
+        store: { home: pluginsHome(env, home), ...(deps.git ? { git: deps.git } : {}), ...(deps.now ? { now: deps.now } : {}) },
+        stdout,
+        stderr,
+        agentDir: deps.agentDir ?? (async () => agentDir(await getActiveProfileName())),
+    };
+    let parsed;
+    try {
+        parsed = parsePluginArgs(args);
+    }
+    catch (err) {
+        stderr(`${err instanceof Error ? err.message : String(err)}\n${USAGE}`);
+        return 1;
+    }
+    try {
+        switch (parsed.subcommand) {
+            case undefined:
+            case "help":
+                stdout(USAGE);
+                return 0;
+            case "marketplace":
+                return await marketplaceCommand(parsed, io);
+            case "install":
+            case "add":
+                return await install(parsed, io);
+            case "uninstall":
+            case "remove":
+                return uninstall(parsed, io);
+            case "enable":
+                return toggle(parsed, true, io);
+            case "disable":
+                return toggle(parsed, false, io);
+            case "update":
+                return await update(parsed, io);
+            case "list":
+                return parsed.available ? listAvailable(io) : await list(io);
+            case "inventory":
+                return await inventory(io);
+            default:
+                stderr(`Unknown plugin subcommand "${parsed.subcommand}".\n${USAGE}`);
+                return 1;
+        }
+    }
+    catch (err) {
+        if (err instanceof PluginStoreError) {
+            stderr(`Error: ${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+}
+// ── marketplace ─────────────────────────────────────────────────────────────
+async function marketplaceCommand(parsed, io) {
+    const [action, target] = parsed.positionals;
+    switch (action) {
+        case "add": {
+            if (!target) {
+                io.stderr(`Error: a marketplace source is required.\nUsage: ${cmd} plugin marketplace add <owner/repo | git-url | path>\n`);
+                return 1;
+            }
+            const source = parseMarketplaceSource(target, io.cwd);
+            if (!source) {
+                io.stderr(`Error: "${target}" is not a GitHub owner/repo, a git URL, or an existing directory.\n`);
+                return 1;
+            }
+            if (source.source !== "directory")
+                io.stdout(`Cloning ${describeSource(source)}…\n`);
+            const added = await addMarketplace(source, io.store);
+            const names = added.marketplace.plugins.map((p) => p.name);
+            io.stdout(`Added marketplace "${added.name}" (${describeSource(source)}) with ${names.length} plugin(s)${names.length ? `: ${names.join(", ")}` : ""}.\n`);
+            if (names[0])
+                io.stdout(`Install one with: ${cmd} plugin install ${names[0]}@${added.name}\n`);
+            return 0;
+        }
+        case "list":
+        case undefined: {
+            const known = readKnownMarketplaces(io.store.home);
+            const entries = Object.entries(known);
+            if (entries.length === 0) {
+                io.stdout(`No marketplaces added. Add one with: ${cmd} plugin marketplace add <owner/repo | git-url | path>\n`);
+                return 0;
+            }
+            for (const [name, mp] of entries) {
+                io.stdout(`${name}\n  Source: ${describeSource(mp.source)}\n  Location: ${mp.installLocation}\n`);
+            }
+            return 0;
+        }
+        case "update": {
+            const known = readKnownMarketplaces(io.store.home);
+            const names = target ? [target] : Object.keys(known);
+            if (names.length === 0) {
+                io.stdout("No marketplaces to update.\n");
+                return 0;
+            }
+            let failed = false;
+            for (const name of names) {
+                try {
+                    const { changed } = await updateMarketplace(name, io.store);
+                    io.stdout(`${name}: ${changed ? "updated" : "already up to date"}\n`);
+                }
+                catch (err) {
+                    failed = true;
+                    io.stderr(`${name}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            if (!failed)
+                io.stdout(`Installed plugins are re-synced by: ${cmd} plugin update\n`);
+            return failed ? 1 : 0;
+        }
+        case "remove": {
+            if (!target) {
+                io.stderr(`Error: a marketplace name is required.\nUsage: ${cmd} plugin marketplace remove <name>\n`);
+                return 1;
+            }
+            const { removedPlugins } = removeMarketplace(target, io.store);
+            pruneCache(io.store.home);
+            io.stdout(`Removed marketplace "${target}"${removedPlugins.length ? ` and its installed plugin(s): ${removedPlugins.join(", ")}` : ""}.\n`);
+            return 0;
+        }
+        default:
+            io.stderr(`Unknown marketplace action "${action}".\n${USAGE}`);
+            return 1;
+    }
+}
+// ── install / uninstall / enable / disable / update ─────────────────────────
+async function install(parsed, io) {
+    const spec = parsed.positionals[0];
+    if (!spec) {
+        io.stderr(`Error: a plugin is required.\nUsage: ${cmd} plugin install <plugin>[@marketplace] [-s user|project]\n`);
+        return 1;
+    }
+    const projectPath = parsed.scope === "project" ? resolveRepoRoot(io.cwd) : undefined;
+    const { resolved, installPath, replaced } = await installPlugin(spec, { scope: parsed.scope, projectPath }, io.store);
+    const assets = discoverClaudePlugins({ cwd: io.cwd, homeDir: io.home, yagniLedger: readLedger(io.store.home) }).user.find((p) => p.key === resolved.key);
+    const where = parsed.scope === "project" ? `project scope, ${projectPath}` : "user scope";
+    io.stdout(`${replaced ? "Reinstalled" : "Installed"} ${resolved.key} v${resolved.version} (${where}).\n`);
+    if (assets) {
+        io.stdout(`  Loads: ${componentSummary(assets)}\n`);
+        for (const line of mcpNotes(assets, io.env))
+            io.stdout(`  ${line}\n`);
+        if (assets.unsupported.length > 0)
+            io.stdout(`  Not bridged: ${assets.unsupported.join(", ")}\n`);
+    }
+    else {
+        io.stdout(`  Warning: nothing loadable found in ${installPath} (no skills, commands, agents, or MCP servers).\n`);
+    }
+    io.stdout(`Takes effect on the next ${cmd} launch.\n`);
+    return 0;
+}
+function uninstall(parsed, io) {
+    const spec = parsed.positionals[0];
+    if (!spec) {
+        io.stderr(`Error: a plugin is required.\nUsage: ${cmd} plugin uninstall <plugin>[@marketplace] [-s user|project]\n`);
+        return 1;
+    }
+    const { key, removed } = uninstallPlugin(spec, { ...(parsed.scopeExplicit ? { scope: parsed.scope } : {}), projectPath: resolveRepoRoot(io.cwd) }, io.store);
+    pruneCache(io.store.home);
+    io.stdout(`Uninstalled ${key} (${removed.map((r) => r.scope).join(", ")} scope).\n`);
+    return 0;
+}
+function toggle(parsed, enabled, io) {
+    const spec = parsed.positionals[0];
+    if (!spec) {
+        io.stderr(`Error: a plugin is required.\nUsage: ${cmd} plugin ${enabled ? "enable" : "disable"} <plugin>[@marketplace]\n`);
+        return 1;
+    }
+    const { key } = setPluginEnabled(spec, enabled, io.store);
+    io.stdout(`${enabled ? "Enabled" : "Disabled"} ${key}. Takes effect on the next ${cmd} launch.\n`);
+    return 0;
+}
+async function update(parsed, io) {
+    const spec = parsed.positionals[0];
+    if (!spec && Object.keys(readLedger(io.store.home).plugins).length === 0) {
+        io.stdout(`No plugins installed via ${cmd}. Install one with: ${cmd} plugin install <plugin>[@marketplace]\n`);
+        return 0;
+    }
+    const report = await updatePlugins(spec, io.store);
+    for (const mp of report.marketplaces)
+        io.stdout(`Marketplace ${mp.name}: ${mp.changed ? "updated" : "already up to date"}\n`);
+    for (const p of report.plugins) {
+        io.stdout(`${p.key}: ${p.from === p.to ? `v${p.to} re-synced` : `v${p.from} → v${p.to}`}\n`);
+    }
+    for (const e of report.errors)
+        io.stderr(`Error: ${e}\n`);
+    pruneCache(io.store.home);
+    if (report.plugins.length > 0)
+        io.stdout(`Takes effect on the next ${cmd} launch.\n`);
+    return report.errors.length > 0 ? 1 : 0;
+}
+// ── inventory (machine-readable, for the in-session panel) ─────────────────
+async function inventory(io) {
+    const result = pluginInventory({ cwd: io.cwd, agentDir: await io.agentDir(), homeDir: io.home, env: io.env });
+    io.stdout(`${JSON.stringify(result)}\n`);
+    return 0;
+}
+// ── list ────────────────────────────────────────────────────────────────────
+async function list(io) {
+    const discovered = discoverClaudePlugins({ cwd: io.cwd, homeDir: io.home, yagniLedger: readLedger(io.store.home) });
+    const ledger = readLedger(io.store.home);
+    const repoRoot = resolveRepoRoot(io.cwd);
+    const all = [...discovered.user, ...discovered.project];
+    const disabled = Object.entries(ledger.plugins).filter(([, entries]) => entries.every((e) => !e.enabled));
+    const disabledLine = disabled.length > 0
+        ? `Disabled: ${disabled.map(([key]) => key).join(", ")} (re-enable with \`${cmd} plugin enable <plugin>\`)\n`
+        : "";
+    if (all.length === 0) {
+        io.stdout("No plugins load here.\n");
+        if (disabledLine)
+            io.stdout(disabledLine);
+        else
+            io.stdout(`Add a marketplace with \`${cmd} plugin marketplace add <owner/repo | git-url | path>\`, then \`${cmd} plugin install <plugin>\`.\n`);
+        return 0;
+    }
+    let trust = null;
+    try {
+        trust = readTrustDecision(await io.agentDir(), io.cwd);
+    }
+    catch {
+        trust = null;
+    }
+    const describeOrigin = (p) => {
+        if (p.origin === "yagni") {
+            const entries = ledger.plugins[p.key] ?? [];
+            const scopes = entries
+                .filter((e) => e.scope === "user" || e.projectPath === repoRoot || (e.projectPath && repoRoot.startsWith(e.projectPath + sep)))
+                .map((e) => e.scope);
+            return `installed via ${cmd} (${[...new Set(scopes)].join(", ") || "user"})`;
+        }
+        if (p.origin === "claude-code")
+            return "mirrored from Claude Code";
+        return "from this repo's marketplace";
+    };
+    const render = (p, gated) => {
+        io.stdout(`  ${p.key}${p.version ? `  v${p.version}` : ""}  ${describeOrigin(p)}${gated && trust !== true ? "  (loads once this folder is trusted)" : ""}\n`);
+        io.stdout(`    ${componentSummary(p)}\n`);
+        for (const line of mcpNotes(p, io.env))
+            io.stdout(`    ${line}\n`);
+        if (p.unsupported.length > 0)
+            io.stdout(`    not bridged: ${p.unsupported.join(", ")}\n`);
+    };
+    if (discovered.user.length > 0) {
+        io.stdout(`Plugins (${discovered.user.length}):\n`);
+        for (const p of discovered.user)
+            render(p, false);
+    }
+    if (discovered.project.length > 0) {
+        io.stdout(`Plugins from this repo's config (${discovered.project.length}):\n`);
+        for (const p of discovered.project)
+            render(p, true);
+    }
+    if (disabledLine)
+        io.stdout(disabledLine);
+    return 0;
+}
+function listAvailable(io) {
+    const cat = catalog(io.store);
+    if (cat.length === 0) {
+        io.stdout(`No marketplaces added. Add one with: ${cmd} plugin marketplace add <owner/repo | git-url | path>\n`);
+        return 0;
+    }
+    const installed = new Set(Object.keys(readLedger(io.store.home).plugins));
+    for (const mp of cat) {
+        io.stdout(`${mp.marketplace}:\n`);
+        if (mp.entries.length === 0)
+            io.stdout("  (no plugins listed)\n");
+        for (const e of mp.entries) {
+            const key = `${e.name}@${mp.marketplace}`;
+            const flags = [installed.has(key) ? "installed" : null, e.installable ? null : "not installable (remote source)"].filter(Boolean);
+            io.stdout(`  ${e.name}${e.version ? `  v${e.version}` : ""}${flags.length ? `  [${flags.join(", ")}]` : ""}\n`);
+            if (e.description)
+                io.stdout(`    ${e.description}\n`);
+        }
+    }
+    return 0;
+}
+// ── helpers ─────────────────────────────────────────────────────────────────
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function countSkills(paths) {
+    let n = 0;
+    for (const path of paths) {
+        if (!isDir(path)) {
+            n += 1;
+            continue;
+        }
+        if (existsSync(join(path, "SKILL.md"))) {
+            n += 1;
+            continue;
+        }
+        try {
+            for (const child of readdirSync(path)) {
+                if (existsSync(join(path, child, "SKILL.md")))
+                    n += 1;
+            }
+        }
+        catch {
+            // unreadable dir → 0
+        }
+    }
+    return n;
+}
+function countMarkdown(paths) {
+    let n = 0;
+    for (const path of paths) {
+        if (!isDir(path)) {
+            if (path.endsWith(".md"))
+                n += 1;
+            continue;
+        }
+        try {
+            n += readdirSync(path).filter((f) => f.endsWith(".md")).length;
+        }
+        catch {
+            // unreadable dir → 0
+        }
+    }
+    return n;
+}
+export function componentSummary(p) {
+    const parts = [];
+    const skills = countSkills(p.skillPaths);
+    const commands = countMarkdown(p.commandPaths);
+    const agents = countMarkdown(p.agentDirs);
+    const mcp = p.mcp ? Object.keys(p.mcp.servers).length : 0;
+    if (skills)
+        parts.push(`${skills} skill${skills === 1 ? "" : "s"}`);
+    if (commands)
+        parts.push(`${commands} command${commands === 1 ? "" : "s"}`);
+    if (agents)
+        parts.push(`${agents} agent${agents === 1 ? "" : "s"}`);
+    if (mcp)
+        parts.push(`${mcp} MCP server${mcp === 1 ? "" : "s"}`);
+    return parts.length ? parts.join(" · ") : "nothing loadable";
+}
+/** Whether a stdio `command` resolves on PATH (or is an existing path). Unknown when it has an unexpanded ${VAR}. */
+export function commandOnPath(command, env) {
+    if (command.includes("${"))
+        return null;
+    if (isAbsolute(command) || command.includes("/") || command.includes("\\"))
+        return existsSync(command);
+    const exts = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+    for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
+        for (const ext of exts) {
+            if (existsSync(join(dir, command + ext)))
+                return true;
+        }
+    }
+    return false;
+}
+/** Per-server notes for a plugin's MCP block: names, and a missing-binary warning for stdio servers. */
+export function mcpNotes(p, env) {
+    if (!p.mcp)
+        return [];
+    const lines = [];
+    const names = Object.keys(p.mcp.servers);
+    lines.push(`MCP: ${names.join(", ")} (check with \`${cmd} mcp list\`)`);
+    const missing = new Set();
+    for (const value of Object.values(p.mcp.servers)) {
+        if (!value || typeof value !== "object")
+            continue;
+        const config = value;
+        if (config.type !== undefined && config.type !== "stdio")
+            continue;
+        if (typeof config.command !== "string")
+            continue;
+        if (commandOnPath(config.command, env) === false)
+            missing.add(config.command);
+    }
+    for (const command of missing) {
+        lines.push(`Note: "${command}" is not on your PATH — install it before launching or its server will fail to start.`);
+    }
+    return lines;
+}
+//# sourceMappingURL=pluginCommand.js.map

package/dist/pluginStore.d.ts

@@ -0,0 +1,170 @@
+/**
+ * YAGNI Code's own plugin ledger — the state behind `yagni plugin …`.
+ *
+ * Layout under `~/.yagni-code/plugins/` (Claude Code's shape, our own files —
+ * we never write into `~/.claude`, whose ledger format is versioned and
+ * undocumented; we only read it, see claudePlugins.ts):
+ *
+ *   known_marketplaces.json    marketplace name → source + local checkout
+ *   installed_plugins.json     `name@marketplace` → installed entries
+ *   marketplaces/<name>/       git checkout of a marketplace repo
+ *   cache/<mp>/<plugin>/<ver>/ the installed copy of a plugin
+ *
+ * Marketplace sources: `owner/repo` (GitHub over HTTPS, the developer's own
+ * git credentials), any git URL (ssh or https), or a local directory (its
+ * catalog is read in place; installs still copy into the cache, so edits land
+ * on the next `plugin update`). Only marketplace entries with relative-path
+ * sources install;
+ * object sources (github/url/npm/archive) are network installs of a second
+ * repo and are reported as unsupported rather than fetched.
+ *
+ * All git calls go through an injectable runner so tests never touch the
+ * network. Writes are atomic (temp + rename).
+ */
+import { type Marketplace, type MarketplaceEntry } from "./claudePlugins.js";
+export type MarketplaceSource = {
+    source: "github";
+    repo: string;
+} | {
+    source: "git";
+    url: string;
+} | {
+    source: "directory";
+    path: string;
+};
+export interface KnownMarketplace {
+    source: MarketplaceSource;
+    /** Marketplace root: the checkout (git) or the directory itself. */
+    installLocation: string;
+    addedAt: string;
+}
+export type PluginInstallScope = "user" | "project";
+export interface InstalledPlugin {
+    scope: PluginInstallScope;
+    /** Absolute path of the installed copy (cache dir). */
+    installPath: string;
+    version: string;
+    /** Repo root the project-scope install applies to. */
+    projectPath?: string;
+    enabled: boolean;
+    installedAt: string;
+}
+export interface PluginLedger {
+    version: 1;
+    plugins: Record<string, InstalledPlugin[]>;
+}
+export interface GitResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+export type GitRunner = (args: string[], opts: {
+    cwd?: string;
+}) => Promise<GitResult>;
+export declare const defaultGit: GitRunner;
+export declare class PluginStoreError extends Error {
+}
+export declare function pluginsHome(env?: NodeJS.ProcessEnv, userHome?: string): string;
+export declare function readKnownMarketplaces(home: string): Record<string, KnownMarketplace>;
+export declare function writeKnownMarketplaces(home: string, value: Record<string, KnownMarketplace>): void;
+export declare function readLedger(home: string): PluginLedger;
+export declare function writeLedger(home: string, ledger: PluginLedger): void;
+/** Interpret the `marketplace add` argument. Null when it is none of the shapes. */
+export declare function parseMarketplaceSource(input: string, cwd: string): MarketplaceSource | null;
+export declare function cloneUrl(source: MarketplaceSource): string | null;
+export declare function describeSource(source: MarketplaceSource): string;
+export interface StoreDeps {
+    home: string;
+    git?: GitRunner;
+    now?: () => Date;
+}
+export declare function addMarketplace(source: MarketplaceSource, deps: StoreDeps): Promise<{
+    name: string;
+    marketplace: Marketplace;
+    installLocation: string;
+}>;
+export declare function knownMarketplaceOrThrow(name: string, deps: StoreDeps): KnownMarketplace;
+/** Pull a git marketplace; a directory marketplace is always current. Returns whether anything changed. */
+export declare function updateMarketplace(name: string, deps: StoreDeps): Promise<{
+    changed: boolean;
+    head: string | null;
+}>;
+export declare function removeMarketplace(name: string, deps: StoreDeps): {
+    removedPlugins: string[];
+};
+export declare function splitKey(key: string): {
+    plugin: string;
+    marketplace: string | null;
+};
+export interface ResolvedPlugin {
+    key: string;
+    plugin: string;
+    marketplace: string;
+    marketplaceRoot: string;
+    entry: MarketplaceEntry;
+    /** Plugin source dir inside the marketplace checkout. */
+    sourceRoot: string;
+    version: string;
+}
+/**
+ * Find `<plugin>[@marketplace]` across known marketplaces. Without an
+ * explicit marketplace the name must be unique across them.
+ */
+export declare function resolvePluginSpec(spec: string, deps: StoreDeps): Promise<ResolvedPlugin>;
+export interface InstallOptions {
+    scope: PluginInstallScope;
+    /** Required for scope "project": the repo root the install applies to. */
+    projectPath?: string;
+}
+export declare function installPlugin(spec: string, opts: InstallOptions, deps: StoreDeps): Promise<{
+    resolved: ResolvedPlugin;
+    installPath: string;
+    replaced: InstalledPlugin | null;
+}>;
+/** The ledger key an uninstall/enable/disable spec refers to; must be unambiguous. */
+export declare function resolveInstalledKey(spec: string, deps: StoreDeps): string;
+export interface UninstallOptions {
+    scope?: PluginInstallScope;
+    projectPath?: string;
+}
+export declare function uninstallPlugin(spec: string, opts: UninstallOptions, deps: StoreDeps): {
+    key: string;
+    removed: InstalledPlugin[];
+};
+export declare function setPluginEnabled(spec: string, enabled: boolean, deps: StoreDeps): {
+    key: string;
+    count: number;
+};
+export interface UpdateReport {
+    key: string;
+    from: string;
+    to: string;
+    /** Files re-synced from the marketplace even when the version string is unchanged. */
+    refreshed: boolean;
+}
+/**
+ * Refresh marketplaces and re-sync installed plugins from them. Every
+ * installed plugin is re-copied (a content change with no version bump still
+ * lands), and version changes are reported.
+ */
+export declare function updatePlugins(spec: string | undefined, deps: StoreDeps): Promise<{
+    marketplaces: {
+        name: string;
+        changed: boolean;
+    }[];
+    plugins: UpdateReport[];
+    errors: string[];
+}>;
+/** Marketplace catalog entries with their install status (for `plugin list --available`). */
+export declare function catalog(deps: StoreDeps): {
+    marketplace: string;
+    entries: {
+        name: string;
+        version: string | null;
+        description: string | null;
+        installable: boolean;
+    }[];
+}[];
+/** Remove empty cache parents left behind by uninstalls (best effort). */
+export declare function pruneCache(home: string): void;
+//# sourceMappingURL=pluginStore.d.ts.map