@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/cli/plugins-cli.js

@@ -1,17 +1,48 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { loadConfig, writeConfigFile } from "../config/config.js";
+import { resolveStateDir } from "../config/paths.js";
 import { resolveArchiveKind } from "../infra/archive.js";
 import { installPluginFromNpmSpec, installPluginFromPath } from "../plugins/install.js";
 import { recordPluginInstall } from "../plugins/installs.js";
+import { clearPluginManifestRegistryCache } from "../plugins/manifest-registry.js";
 import { applyExclusiveSlotSelection } from "../plugins/slots.js";
+import { resolvePluginSourceRoots, formatPluginSourceForTable } from "../plugins/source-display.js";
 import { buildPluginStatusReport } from "../plugins/status.js";
+import { resolveUninstallDirectoryTarget, uninstallPlugin } from "../plugins/uninstall.js";
 import { updateNpmInstalledPlugins } from "../plugins/update.js";
 import { defaultRuntime } from "../runtime.js";
 import { formatDocsLink } from "../terminal/links.js";
 import { renderTable } from "../terminal/table.js";
 import { theme } from "../terminal/theme.js";
 import { resolveUserPath, shortenHomeInString, shortenHomePath } from "../utils.js";
+import { promptYesNo } from "./prompt.js";
+function resolveFileNpmSpecToLocalPath(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.toLowerCase().startsWith("file:")) {
+        return null;
+    }
+    const rest = trimmed.slice("file:".length);
+    if (!rest) {
+        return { ok: false, error: "unsupported file: spec: missing path" };
+    }
+    if (rest.startsWith("///")) {
+        // file:///abs/path -> /abs/path
+        return { ok: true, path: rest.slice(2) };
+    }
+    if (rest.startsWith("//localhost/")) {
+        // file://localhost/abs/path -> /abs/path
+        return { ok: true, path: rest.slice("//localhost".length) };
+    }
+    if (rest.startsWith("//")) {
+        return {
+            ok: false,
+            error: 'unsupported file: URL host (expected "file:<path>" or "file:///abs/path")',
+        };
+    }
+    return { ok: true, path: rest };
+}
 function formatPluginLine(plugin, verbose = false) {
     const status = plugin.status === "loaded"
         ? theme.success("loaded")
@@ -33,13 +64,15 @@ function formatPluginLine(plugin, verbose = false) {
         `  source: ${theme.muted(shortenHomeInString(plugin.source))}`,
         `  origin: ${plugin.origin}`,
     ];
-    if (plugin.version)
+    if (plugin.version) {
         parts.push(`  version: ${plugin.version}`);
+    }
     if (plugin.providerIds.length > 0) {
         parts.push(`  providers: ${plugin.providerIds.join(", ")}`);
     }
-    if (plugin.error)
+    if (plugin.error) {
         parts.push(theme.error(`  error: ${plugin.error}`));
+    }
     return parts.join("\n");
 }
 function applySlotSelectionForPlugin(config, pluginId) {
@@ -56,9 +89,31 @@ function applySlotSelectionForPlugin(config, pluginId) {
     });
     return { config: result.config, warnings: result.warnings };
 }
+function createPluginInstallLogger() {
+    return {
+        info: (msg) => defaultRuntime.log(msg),
+        warn: (msg) => defaultRuntime.log(theme.warn(msg)),
+    };
+}
+function enablePluginInConfig(config, pluginId) {
+    return {
+        ...config,
+        plugins: {
+            ...config.plugins,
+            entries: {
+                ...config.plugins?.entries,
+                [pluginId]: {
+                    ...config.plugins?.entries?.[pluginId],
+                    enabled: true,
+                },
+            },
+        },
+    };
+}
 function logSlotWarnings(warnings) {
-    if (warnings.length === 0)
+    if (warnings.length === 0) {
         return;
+    }
     for (const warning of warnings) {
         defaultRuntime.log(theme.warn(warning));
     }
@@ -66,8 +121,8 @@ function logSlotWarnings(warnings) {
 export function registerPluginsCli(program) {
     const plugins = program
         .command("plugins")
-        .description("Manage Poolbot plugins/extensions")
-        .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/plugins", "docs.molt.bot/cli/plugins")}\n`);
+        .description("Manage Pool Bot plugins and extensions")
+        .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/plugins", "docs.poolbot.ai/cli/plugins")}\n`);
     plugins
         .command("list")
         .description("List discovered plugins")
@@ -96,9 +151,17 @@ export function registerPluginsCli(program) {
         defaultRuntime.log(`${theme.heading("Plugins")} ${theme.muted(`(${loaded}/${list.length} loaded)`)}`);
         if (!opts.verbose) {
             const tableWidth = Math.max(60, (process.stdout.columns ?? 120) - 1);
+            const sourceRoots = resolvePluginSourceRoots({
+                workspaceDir: report.workspaceDir,
+            });
+            const usedRoots = new Set();
             const rows = list.map((plugin) => {
                 const desc = plugin.description ? theme.muted(plugin.description) : "";
-                const sourceLine = desc ? `${plugin.source}\n${desc}` : plugin.source;
+                const formattedSource = formatPluginSourceForTable(plugin, sourceRoots);
+                if (formattedSource.rootKey) {
+                    usedRoots.add(formattedSource.rootKey);
+                }
+                const sourceLine = desc ? `${formattedSource.value}\n${desc}` : formattedSource.value;
                 return {
                     Name: plugin.name || plugin.id,
                     ID: plugin.name && plugin.name !== plugin.id ? plugin.id : "",
@@ -111,6 +174,20 @@ export function registerPluginsCli(program) {
                     Version: plugin.version ?? "",
                 };
             });
+            if (usedRoots.size > 0) {
+                defaultRuntime.log(theme.muted("Source roots:"));
+                for (const key of ["stock", "workspace", "global"]) {
+                    if (!usedRoots.has(key)) {
+                        continue;
+                    }
+                    const dir = sourceRoots[key];
+                    if (!dir) {
+                        continue;
+                    }
+                    defaultRuntime.log(`  ${theme.command(`${key}:`)} ${theme.muted(dir)}`);
+                }
+                defaultRuntime.log("");
+            }
             defaultRuntime.log(renderTable({
                 width: tableWidth,
                 columns: [
@@ -154,14 +231,16 @@ export function registerPluginsCli(program) {
         if (plugin.name && plugin.name !== plugin.id) {
             lines.push(theme.muted(`id: ${plugin.id}`));
         }
-        if (plugin.description)
+        if (plugin.description) {
             lines.push(plugin.description);
+        }
         lines.push("");
         lines.push(`${theme.muted("Status:")} ${plugin.status}`);
         lines.push(`${theme.muted("Source:")} ${shortenHomeInString(plugin.source)}`);
         lines.push(`${theme.muted("Origin:")} ${plugin.origin}`);
-        if (plugin.version)
+        if (plugin.version) {
             lines.push(`${theme.muted("Version:")} ${plugin.version}`);
+        }
         if (plugin.toolNames.length > 0) {
             lines.push(`${theme.muted("Tools:")} ${plugin.toolNames.join(", ")}`);
         }
@@ -180,21 +259,27 @@ export function registerPluginsCli(program) {
         if (plugin.services.length > 0) {
             lines.push(`${theme.muted("Services:")} ${plugin.services.join(", ")}`);
         }
-        if (plugin.error)
+        if (plugin.error) {
             lines.push(`${theme.error("Error:")} ${plugin.error}`);
+        }
         if (install) {
             lines.push("");
             lines.push(`${theme.muted("Install:")} ${install.source}`);
-            if (install.spec)
+            if (install.spec) {
                 lines.push(`${theme.muted("Spec:")} ${install.spec}`);
-            if (install.sourcePath)
+            }
+            if (install.sourcePath) {
                 lines.push(`${theme.muted("Source path:")} ${shortenHomePath(install.sourcePath)}`);
-            if (install.installPath)
+            }
+            if (install.installPath) {
                 lines.push(`${theme.muted("Install path:")} ${shortenHomePath(install.installPath)}`);
-            if (install.version)
+            }
+            if (install.version) {
                 lines.push(`${theme.muted("Recorded version:")} ${install.version}`);
-            if (install.installedAt)
+            }
+            if (install.installedAt) {
                 lines.push(`${theme.muted("Installed at:")} ${install.installedAt}`);
+            }
         }
         defaultRuntime.log(lines.join("\n"));
     });
@@ -245,13 +330,133 @@ export function registerPluginsCli(program) {
         await writeConfigFile(next);
         defaultRuntime.log(`Disabled plugin "${id}". Restart the gateway to apply.`);
     });
+    plugins
+        .command("uninstall")
+        .description("Uninstall a plugin")
+        .argument("<id>", "Plugin id")
+        .option("--keep-files", "Keep installed files on disk", false)
+        .option("--keep-config", "Deprecated alias for --keep-files", false)
+        .option("--force", "Skip confirmation prompt", false)
+        .option("--dry-run", "Show what would be removed without making changes", false)
+        .action(async (id, opts) => {
+        const cfg = loadConfig();
+        const report = buildPluginStatusReport({ config: cfg });
+        const extensionsDir = path.join(resolveStateDir(process.env, os.homedir), "extensions");
+        const keepFiles = Boolean(opts.keepFiles || opts.keepConfig);
+        if (opts.keepConfig) {
+            defaultRuntime.log(theme.warn("`--keep-config` is deprecated, use `--keep-files`."));
+        }
+        // Find plugin by id or name
+        const plugin = report.plugins.find((p) => p.id === id || p.name === id);
+        const pluginId = plugin?.id ?? id;
+        // Check if plugin exists in config
+        const hasEntry = pluginId in (cfg.plugins?.entries ?? {});
+        const hasInstall = pluginId in (cfg.plugins?.installs ?? {});
+        if (!hasEntry && !hasInstall) {
+            if (plugin) {
+                defaultRuntime.error(`Plugin "${pluginId}" is not managed by plugins config/install records and cannot be uninstalled.`);
+            }
+            else {
+                defaultRuntime.error(`Plugin not found: ${id}`);
+            }
+            process.exit(1);
+        }
+        const install = cfg.plugins?.installs?.[pluginId];
+        const isLinked = install?.source === "path";
+        // Build preview of what will be removed
+        const preview = [];
+        if (hasEntry) {
+            preview.push("config entry");
+        }
+        if (hasInstall) {
+            preview.push("install record");
+        }
+        if (cfg.plugins?.allow?.includes(pluginId)) {
+            preview.push("allowlist entry");
+        }
+        if (isLinked &&
+            install?.sourcePath &&
+            cfg.plugins?.load?.paths?.includes(install.sourcePath)) {
+            preview.push("load path");
+        }
+        if (cfg.plugins?.slots?.memory === pluginId) {
+            preview.push(`memory slot (will reset to "memory-core")`);
+        }
+        const deleteTarget = !keepFiles
+            ? resolveUninstallDirectoryTarget({
+                pluginId,
+                hasInstall,
+                installRecord: install,
+                extensionsDir,
+            })
+            : null;
+        if (deleteTarget) {
+            preview.push(`directory: ${shortenHomePath(deleteTarget)}`);
+        }
+        const pluginName = plugin?.name || pluginId;
+        defaultRuntime.log(`Plugin: ${theme.command(pluginName)}${pluginName !== pluginId ? theme.muted(` (${pluginId})`) : ""}`);
+        defaultRuntime.log(`Will remove: ${preview.length > 0 ? preview.join(", ") : "(nothing)"}`);
+        if (opts.dryRun) {
+            defaultRuntime.log(theme.muted("Dry run, no changes made."));
+            return;
+        }
+        if (!opts.force) {
+            const confirmed = await promptYesNo(`Uninstall plugin "${pluginId}"?`);
+            if (!confirmed) {
+                defaultRuntime.log("Cancelled.");
+                return;
+            }
+        }
+        const result = await uninstallPlugin({
+            config: cfg,
+            pluginId,
+            deleteFiles: !keepFiles,
+            extensionsDir,
+        });
+        if (!result.ok) {
+            defaultRuntime.error(result.error);
+            process.exit(1);
+        }
+        for (const warning of result.warnings) {
+            defaultRuntime.log(theme.warn(warning));
+        }
+        await writeConfigFile(result.config);
+        const removed = [];
+        if (result.actions.entry) {
+            removed.push("config entry");
+        }
+        if (result.actions.install) {
+            removed.push("install record");
+        }
+        if (result.actions.allowlist) {
+            removed.push("allowlist");
+        }
+        if (result.actions.loadPath) {
+            removed.push("load path");
+        }
+        if (result.actions.memorySlot) {
+            removed.push("memory slot");
+        }
+        if (result.actions.directory) {
+            removed.push("directory");
+        }
+        defaultRuntime.log(`Uninstalled plugin "${pluginId}". Removed: ${removed.length > 0 ? removed.join(", ") : "nothing"}.`);
+        defaultRuntime.log("Restart the gateway to apply changes.");
+    });
     plugins
         .command("install")
         .description("Install a plugin (path, archive, or npm spec)")
         .argument("<path-or-spec>", "Path (.ts/.js/.zip/.tgz/.tar.gz) or an npm package spec")
         .option("-l, --link", "Link a local path instead of copying", false)
+        .option("--pin", "Record npm installs as exact resolved <name>@<version>", false)
         .action(async (raw, opts) => {
-        const resolved = resolveUserPath(raw);
+        const fileSpec = resolveFileNpmSpecToLocalPath(raw);
+        if (fileSpec && !fileSpec.ok) {
+            defaultRuntime.error(fileSpec.error);
+            process.exit(1);
+        }
+        const normalized = fileSpec && fileSpec.ok ? fileSpec.path : raw;
+        const resolved = resolveUserPath(normalized);
         const cfg = loadConfig();
         if (fs.existsSync(resolved)) {
             if (opts.link) {
@@ -262,7 +467,7 @@ export function registerPluginsCli(program) {
                     defaultRuntime.error(probe.error);
                     process.exit(1);
                 }
-                let next = {
+                let next = enablePluginInConfig({
                     ...cfg,
                     plugins: {
                         ...cfg.plugins,
@@ -270,15 +475,8 @@ export function registerPluginsCli(program) {
                             ...cfg.plugins?.load,
                             paths: merged,
                         },
-                        entries: {
-                            ...cfg.plugins?.entries,
-                            [probe.pluginId]: {
-                                ...cfg.plugins?.entries?.[probe.pluginId],
-                                enabled: true,
-                            },
-                        },
                     },
-                };
+                }, probe.pluginId);
                 next = recordPluginInstall(next, {
                     pluginId: probe.pluginId,
                     source: "path",
@@ -296,28 +494,16 @@ export function registerPluginsCli(program) {
             }
             const result = await installPluginFromPath({
                 path: resolved,
-                logger: {
-                    info: (msg) => defaultRuntime.log(msg),
-                    warn: (msg) => defaultRuntime.log(theme.warn(msg)),
-                },
+                logger: createPluginInstallLogger(),
             });
             if (!result.ok) {
                 defaultRuntime.error(result.error);
                 process.exit(1);
             }
-            let next = {
-                ...cfg,
-                plugins: {
-                    ...cfg.plugins,
-                    entries: {
-                        ...cfg.plugins?.entries,
-                        [result.pluginId]: {
-                            ...cfg.plugins?.entries?.[result.pluginId],
-                            enabled: true,
-                        },
-                    },
-                },
-            };
+            // Plugin CLI registrars may have warmed the manifest registry cache before install;
+            // force a rescan so config validation sees the freshly installed plugin.
+            clearPluginManifestRegistryCache();
+            let next = enablePluginInConfig(cfg, result.pluginId);
             const source = resolveArchiveKind(resolved) ? "archive" : "path";
             next = recordPluginInstall(next, {
                 pluginId: result.pluginId,
@@ -355,32 +541,28 @@ export function registerPluginsCli(program) {
         }
         const result = await installPluginFromNpmSpec({
             spec: raw,
-            logger: {
-                info: (msg) => defaultRuntime.log(msg),
-                warn: (msg) => defaultRuntime.log(theme.warn(msg)),
-            },
+            logger: createPluginInstallLogger(),
         });
         if (!result.ok) {
             defaultRuntime.error(result.error);
             process.exit(1);
         }
-        let next = {
-            ...cfg,
-            plugins: {
-                ...cfg.plugins,
-                entries: {
-                    ...cfg.plugins?.entries,
-                    [result.pluginId]: {
-                        ...cfg.plugins?.entries?.[result.pluginId],
-                        enabled: true,
-                    },
-                },
-            },
-        };
+        // Ensure config validation sees newly installed plugin(s) even if the cache was warmed at startup.
+        clearPluginManifestRegistryCache();
+        let next = enablePluginInConfig(cfg, result.pluginId);
+        // PB's installPluginFromNpmSpec does not return npmResolution metadata yet;
+        // record what we can (version from manifest) and store the raw spec.
+        const recordSpec = opts.pin && result.version ? `${result.pluginId}@${result.version}` : raw;
+        if (opts.pin && !result.version) {
+            defaultRuntime.log(theme.warn("Could not resolve exact npm version for --pin; storing original npm spec."));
+        }
+        if (opts.pin && result.version) {
+            defaultRuntime.log(`Pinned npm install record to ${result.pluginId}@${result.version}.`);
+        }
         next = recordPluginInstall(next, {
             pluginId: result.pluginId,
             source: "npm",
-            spec: raw,
+            spec: recordSpec,
             installPath: result.targetDir,
             version: result.version,
         });
@@ -417,6 +599,7 @@ export function registerPluginsCli(program) {
                 info: (msg) => defaultRuntime.log(msg),
                 warn: (msg) => defaultRuntime.log(theme.warn(msg)),
             },
+            // NOTE: onIntegrityDrift is available in OC but not yet ported to PB's update module.
         });
         for (const outcome of result.outcomes) {
             if (outcome.status === "error") {
@@ -453,15 +636,16 @@ export function registerPluginsCli(program) {
             }
         }
         if (diags.length > 0) {
-            if (lines.length > 0)
+            if (lines.length > 0) {
                 lines.push("");
+            }
             lines.push(theme.warn("Diagnostics:"));
             for (const diag of diags) {
                 const target = diag.pluginId ? `${diag.pluginId}: ` : "";
                 lines.push(`- ${target}${diag.message}`);
             }
         }
-        const docs = formatDocsLink("/plugin", "docs.molt.bot/plugin");
+        const docs = formatDocsLink("/plugin", "docs.poolbot.ai/plugin");
         lines.push("");
         lines.push(`${theme.muted("Docs:")} ${docs}`);
         defaultRuntime.log(lines.join("\n"));

package/dist/cli/program/build-program.js

@@ -1,12 +1,14 @@
 import { Command } from "commander";
-import { createProgramContext } from "./context.js";
 import { registerProgramCommands } from "./command-registry.js";
+import { createProgramContext } from "./context.js";
 import { configureProgramHelp } from "./help.js";
 import { registerPreActionHooks } from "./preaction.js";
+import { setProgramContext } from "./program-context.js";
 export function buildProgram() {
     const program = new Command();
     const ctx = createProgramContext();
     const argv = process.argv;
+    setProgramContext(program, ctx);
     configureProgramHelp(program, ctx);
     registerPreActionHooks(program, ctx.programVersion);
     registerProgramCommands(program, ctx, argv);