CLI: support versioned plugin updates (#49998)

Merged via squash.

Prepared head SHA: 545ea60fa2
Co-authored-by: huntharo <5617868+huntharo@users.noreply.github.com>
Reviewed-by: @huntharo

src/cli/plugins-cli.test.ts

@@ -379,6 +379,140 @@ describe("plugins cli", () => {
     expect(runtimeLogs.at(-1)).toBe("No tracked plugins to update.");
   });
 
+  it("maps an explicit unscoped npm dist-tag update to the tracked plugin id", async () => {
+    const config = {
+      plugins: {
+        installs: {
+          "openclaw-codex-app-server": {
+            source: "npm",
+            spec: "openclaw-codex-app-server",
+            installPath: "/tmp/openclaw-codex-app-server",
+            resolvedName: "openclaw-codex-app-server",
+          },
+        },
+      },
+    } as OpenClawConfig;
+    loadConfig.mockReturnValue(config);
+    updateNpmInstalledPlugins.mockResolvedValue({
+      config,
+      changed: false,
+      outcomes: [],
+    });
+
+    await runCommand(["plugins", "update", "openclaw-codex-app-server@beta"]);
+
+    expect(updateNpmInstalledPlugins).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config,
+        pluginIds: ["openclaw-codex-app-server"],
+        specOverrides: {
+          "openclaw-codex-app-server": "openclaw-codex-app-server@beta",
+        },
+      }),
+    );
+  });
+
+  it("maps an explicit scoped npm dist-tag update to the tracked plugin id", async () => {
+    const config = {
+      plugins: {
+        installs: {
+          "voice-call": {
+            source: "npm",
+            spec: "@openclaw/voice-call",
+            installPath: "/tmp/voice-call",
+            resolvedName: "@openclaw/voice-call",
+          },
+        },
+      },
+    } as OpenClawConfig;
+    loadConfig.mockReturnValue(config);
+    updateNpmInstalledPlugins.mockResolvedValue({
+      config,
+      changed: false,
+      outcomes: [],
+    });
+
+    await runCommand(["plugins", "update", "@openclaw/voice-call@beta"]);
+
+    expect(updateNpmInstalledPlugins).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config,
+        pluginIds: ["voice-call"],
+        specOverrides: {
+          "voice-call": "@openclaw/voice-call@beta",
+        },
+      }),
+    );
+  });
+
+  it("maps an explicit npm version update to the tracked plugin id", async () => {
+    const config = {
+      plugins: {
+        installs: {
+          "openclaw-codex-app-server": {
+            source: "npm",
+            spec: "openclaw-codex-app-server",
+            installPath: "/tmp/openclaw-codex-app-server",
+            resolvedName: "openclaw-codex-app-server",
+          },
+        },
+      },
+    } as OpenClawConfig;
+    loadConfig.mockReturnValue(config);
+    updateNpmInstalledPlugins.mockResolvedValue({
+      config,
+      changed: false,
+      outcomes: [],
+    });
+
+    await runCommand(["plugins", "update", "openclaw-codex-app-server@0.2.0-beta.4"]);
+
+    expect(updateNpmInstalledPlugins).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config,
+        pluginIds: ["openclaw-codex-app-server"],
+        specOverrides: {
+          "openclaw-codex-app-server": "openclaw-codex-app-server@0.2.0-beta.4",
+        },
+      }),
+    );
+  });
+
+  it("keeps using the recorded npm tag when update is invoked by plugin id", async () => {
+    const config = {
+      plugins: {
+        installs: {
+          "openclaw-codex-app-server": {
+            source: "npm",
+            spec: "openclaw-codex-app-server@beta",
+            installPath: "/tmp/openclaw-codex-app-server",
+            resolvedName: "openclaw-codex-app-server",
+          },
+        },
+      },
+    } as OpenClawConfig;
+    loadConfig.mockReturnValue(config);
+    updateNpmInstalledPlugins.mockResolvedValue({
+      config,
+      changed: false,
+      outcomes: [],
+    });
+
+    await runCommand(["plugins", "update", "openclaw-codex-app-server"]);
+
+    expect(updateNpmInstalledPlugins).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config,
+        pluginIds: ["openclaw-codex-app-server"],
+      }),
+    );
+    expect(updateNpmInstalledPlugins).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        specOverrides: expect.anything(),
+      }),
+    );
+  });
+
   it("writes updated config when updater reports changes", async () => {
     const cfg = {
       plugins: {

src/cli/plugins-cli.ts

@@ -7,6 +7,7 @@ import { loadConfig, writeConfigFile } from "../config/config.js";
 import { resolveStateDir } from "../config/paths.js";
 import type { PluginInstallRecord } from "../config/types.plugins.js";
 import { resolveArchiveKind } from "../infra/archive.js";
+import { parseRegistryNpmSpec } from "../infra/npm-registry-spec.js";
 import { type BundledPluginSource, findBundledPluginSource } from "../plugins/bundled-sources.js";
 import { enablePluginInConfig } from "../plugins/enable.js";
 import { installPluginFromNpmSpec, installPluginFromPath } from "../plugins/install.js";
@@ -227,6 +228,56 @@ function createPluginInstallLogger(): { info: (msg: string) => void; warn: (msg:
   };
 }
 
+function extractInstalledNpmPackageName(install: PluginInstallRecord): string | undefined {
+  if (install.source !== "npm") {
+    return undefined;
+  }
+  const resolvedName = install.resolvedName?.trim();
+  if (resolvedName) {
+    return resolvedName;
+  }
+  return (
+    (install.spec ? parseRegistryNpmSpec(install.spec)?.name : undefined) ??
+    (install.resolvedSpec ? parseRegistryNpmSpec(install.resolvedSpec)?.name : undefined)
+  );
+}
+
+function resolvePluginUpdateSelection(params: {
+  installs: Record<string, PluginInstallRecord>;
+  rawId?: string;
+  all?: boolean;
+}): { pluginIds: string[]; specOverrides?: Record<string, string> } {
+  if (params.all) {
+    return { pluginIds: Object.keys(params.installs) };
+  }
+  if (!params.rawId) {
+    return { pluginIds: [] };
+  }
+
+  const parsedSpec = parseRegistryNpmSpec(params.rawId);
+  if (!parsedSpec || parsedSpec.selectorKind === "none") {
+    return { pluginIds: [params.rawId] };
+  }
+
+  const matches = Object.entries(params.installs).filter(([, install]) => {
+    return extractInstalledNpmPackageName(install) === parsedSpec.name;
+  });
+  if (matches.length !== 1) {
+    return { pluginIds: [params.rawId] };
+  }
+
+  const [pluginId] = matches[0];
+  if (!pluginId) {
+    return { pluginIds: [params.rawId] };
+  }
+  return {
+    pluginIds: [pluginId],
+    specOverrides: {
+      [pluginId]: parsedSpec.raw,
+    },
+  };
+}
+
 function logSlotWarnings(warnings: string[]) {
   if (warnings.length === 0) {
     return;
@@ -1032,7 +1083,12 @@ export function registerPluginsCli(program: Command) {
     .action(async (id: string | undefined, opts: PluginUpdateOptions) => {
       const cfg = loadConfig();
       const installs = cfg.plugins?.installs ?? {};
-      const targets = opts.all ? Object.keys(installs) : id ? [id] : [];
+      const selection = resolvePluginUpdateSelection({
+        installs,
+        rawId: id,
+        all: opts.all,
+      });
+      const targets = selection.pluginIds;
 
       if (targets.length === 0) {
         if (opts.all) {
@@ -1046,6 +1102,7 @@ export function registerPluginsCli(program: Command) {
       const result = await updateNpmInstalledPlugins({
         config: cfg,
         pluginIds: targets,
+        specOverrides: selection.specOverrides,
         dryRun: opts.dryRun,
         logger: {
           info: (msg) => defaultRuntime.log(msg),