@stigmer/cli 3.18.1-dev.20260919070736 → 3.19.0

package/src/marketplace/__fixtures__/cursor-marketplace.ts

@@ -4,7 +4,11 @@
 // is missing, so every suite sees an offered list and a dropped entry. It
 // names itself `acme-plugins`: the vendors' own names are built into every
 // client, so a fixture under one of them would meet the reserved-name
-// refusal instead of being added.
+// refusal instead of being added. Its plugins carry names no real catalogue
+// offers (`warmer`, `codeforge`): a bare-name install searches the official
+// catalogue too, which in a checkout is the live `plugins/` tree, and a
+// fixture named after a real plugin would collide with it as the catalogue
+// grows.
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -24,41 +28,41 @@ export function writeCursorMarketplace(root: string): void {
       metadata: { description: "A test catalogue" },
       plugins: [
         {
-          name: "thermos",
-          source: "thermos",
+          name: "warmer",
+          source: "warmer",
           description: "Keeps things warm.",
         },
-        { name: "github", source: "third_party/github" },
+        { name: "codeforge", source: "third_party/codeforge" },
         { name: "ghost", source: "ghost", description: "Listed, not present." },
       ],
     }),
   );
   write(
-    "thermos/.cursor-plugin/plugin.json",
+    "warmer/.cursor-plugin/plugin.json",
     JSON.stringify({
-      name: "thermos",
+      name: "warmer",
       version: "1.0.0",
-      description: "The thermos plugin.",
+      description: "The warmer plugin.",
       skills: "./skills/",
     }),
   );
   write(
-    "thermos/skills/warm/SKILL.md",
+    "warmer/skills/warm/SKILL.md",
     "---\nname: warm\ndescription: Warms.\n---\nKeep it warm.\n",
   );
   write(
-    "third_party/github/.cursor-plugin/plugin.json",
+    "third_party/codeforge/.cursor-plugin/plugin.json",
     JSON.stringify({
-      name: "github",
+      name: "codeforge",
       version: "2.1.0",
       mcpServers: "./mcp.json",
     }),
   );
   write(
-    "third_party/github/mcp.json",
+    "third_party/codeforge/mcp.json",
     JSON.stringify({
       mcpServers: {
-        github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
+        codeforge: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
       },
     }),
   );

package/src/marketplace/config.test.ts

@@ -48,26 +48,18 @@ function writeConfig(yaml: string): void {
   writeFileSync(configPath(), yaml);
 }
 
-const BUILT_IN_NAMES = [
-  OFFICIAL_MARKETPLACE_NAME,
-  "cursor-plugins",
-  "claude-code-plugins",
-  "codex-plugins",
-];
+const BUILT_IN_NAMES = [OFFICIAL_MARKETPLACE_NAME];
 
 describe("listMarketplaces", () => {
-  it("is the built-in sources alone on a fresh machine, the official one first", () => {
+  it("is the built-in source alone on a fresh machine, the official catalogue", () => {
     const listing = listMarketplaces();
     expect(listing.known.map((m) => m.name)).toEqual(BUILT_IN_NAMES);
     expect(listing.known[0]?.source).toEqual({ type: "official" });
-    expect(listing.known[1]?.source).toEqual({
-      type: "github",
-      repo: "cursor/plugins",
-    });
+    expect(listing.known).toHaveLength(1);
     expect(listing.unreadable).toEqual([]);
   });
 
-  it("lists configured entries after the built-ins, in file order, names the unreadable ones, and lets a built-in win over a same-named entry", () => {
+  it("lists configured entries after the built-in, in file order, names the unreadable ones, and lets the built-in win over a same-named entry", () => {
     writeConfig(
       [
         "backend:",
@@ -76,8 +68,8 @@ describe("listMarketplaces", () => {
         "  acme:",
         "    type: github",
         "    repo: acme/plugins",
-        // Written before the vendors were built in: the built-in wins, the entry stays in the file.
-        "  cursor-plugins:",
+        // A hand edit under the built-in's name: the built-in wins, the entry stays in the file.
+        "  stigmer:",
         "    type: github",
         "    repo: someone/fork",
         "  pinned:",
@@ -102,23 +94,20 @@ describe("listMarketplaces", () => {
       "pinned",
       "team",
     ]);
-    expect(listing.known[4]?.source).toEqual({
+    expect(listing.known[0]?.source).toEqual({ type: "official" });
+    expect(listing.known[1]?.source).toEqual({
       type: "github",
       repo: "acme/plugins",
     });
-    expect(listing.known[5]?.source).toEqual({
+    expect(listing.known[2]?.source).toEqual({
       type: "github",
       repo: "anthropics/claude-code",
       ref: "v1.2.3",
     });
-    expect(listing.known[6]?.source).toEqual({
+    expect(listing.known[3]?.source).toEqual({
       type: "local",
       path: "/srv/plugins",
     });
-    expect(listing.known[1]?.source).toEqual({
-      type: "github",
-      repo: "cursor/plugins",
-    });
     expect(listing.unreadable).toEqual([
       {
         name: "broken",
@@ -173,13 +162,11 @@ describe("addMarketplace and removeMarketplace", () => {
     });
   });
 
-  it("refuses every built-in name, a duplicate, an unknown removal, and a built-in removal", () => {
+  it("refuses the built-in name, a duplicate, an unknown removal, and the built-in's removal; a vendor's name is free", () => {
     expect(() =>
       addMarketplace("stigmer", { type: "local", path: "/x" }),
     ).toThrow(/'stigmer' is a built-in source and cannot be added or replaced/);
-    expect(() =>
-      addMarketplace("cursor-plugins", { type: "local", path: "/x" }),
-    ).toThrow(/'cursor-plugins' is a built-in source/);
+    addMarketplace("cursor-plugins", { type: "github", repo: "cursor/plugins" });
     addMarketplace("team", { type: "local", path: "/srv/plugins" });
     expect(() =>
       addMarketplace("team", { type: "local", path: "/other" }),
@@ -190,9 +177,6 @@ describe("addMarketplace and removeMarketplace", () => {
     expect(() => removeMarketplace("stigmer")).toThrow(
       /'stigmer' is a built-in source and cannot be removed/,
     );
-    expect(() => removeMarketplace("codex-plugins")).toThrow(
-      /'codex-plugins' is a built-in source and cannot be removed/,
-    );
   });
 
   it("refuses under --standalone instead of writing a default file over the user's", () => {

package/src/marketplace/config.ts

@@ -1,14 +1,17 @@
-// The sources a CLI knows: the built-in ones (the official catalogue and the
-// three vendors' public ones, the same list the console ships), and the ones
-// a user added under the `marketplaces` key of ~/.stigmer/config.yaml.
+// The sources a CLI knows: the built-in one (the official catalogue, the same
+// list the console ships) and the ones a user added under the `marketplaces`
+// key of ~/.stigmer/config.yaml.
 //
 // A source is client-side configuration, never a server resource: the
 // server only ever sees the plugin archive a client pushes. That is why the
 // list lives beside the named backends and the context, and why `stigmer
-// marketplace` is a noun group like `config` and `auth`. The built-ins are
-// code, not config: they cannot be added over or removed, so `stigmer
-// install cursor-plugins/thermos` works on a fresh machine and the CLI's
-// list never drifts from the console's.
+// marketplace` is a noun group like `config` and `auth`. The built-in is
+// code, not config: it cannot be added over or removed, so `stigmer install
+// assistant` works on a fresh machine and the CLI's list never drifts from
+// the console's. A vendor's public repository is a source the user adds by
+// name (`stigmer marketplace add cursor/plugins`), never one on offer by
+// default: the official catalogue already carries what Stigmer can offer of
+// it, curated (`plugins/README.md`).
 //
 // The config module keeps the on-disk entry loose (`MarketplaceEntryConfig`,
 // every field optional) so a hand-edited entry this CLI cannot read survives
@@ -82,8 +85,9 @@ export function listMarketplaces(
   const known: KnownMarketplace[] = [...BUILT_IN_SOURCES];
   const unreadable: UnreadableMarketplace[] = [];
   for (const [name, entry] of Object.entries(config.marketplaces ?? {})) {
-    // A config written before the vendors were built in may name one; the
-    // built-in wins and the entry is left in the file untouched.
+    // A config may name the built-in (a hand edit, or a file written by a
+    // CLI whose built-ins differed); the built-in wins and the entry is left
+    // in the file untouched.
     if (isBuiltInMarketplaceName(name)) continue;
     const narrowed = narrowEntry(entry);
     if (narrowed.ok) known.push({ name, source: narrowed.source });

package/src/marketplace/install.test.ts

@@ -33,9 +33,9 @@ afterAll(() => {
 describe("prepareEntry", () => {
   it("prepares an offered entry exactly as push plugin would prepare its directory", async () => {
     const tree = readMarketplaceTree(root);
-    const viaMarketplace = await prepareEntry(tree, "github");
-    const viaFolder = await preparePluginPush(join(root, "third_party", "github"));
-    expect(viaMarketplace.plugin.name).toBe("github");
+    const viaMarketplace = await prepareEntry(tree, "codeforge");
+    const viaFolder = await preparePluginPush(join(root, "third_party", "codeforge"));
+    expect(viaMarketplace.plugin.name).toBe("codeforge");
     expect(viaMarketplace.digest).toBe(viaFolder.digest);
     expect(
       Buffer.from(viaMarketplace.archive).equals(
@@ -57,15 +57,15 @@ describe("prepareEntry", () => {
 
 describe("assertVersion", () => {
   it("passes without a pin or with the offered version, refuses another naming the offered one", async () => {
-    const prepared = await prepareEntry(readMarketplaceTree(root), "thermos");
-    expect(() => assertVersion(prepared, undefined, "thermos")).not.toThrow();
+    const prepared = await prepareEntry(readMarketplaceTree(root), "warmer");
+    expect(() => assertVersion(prepared, undefined, "warmer")).not.toThrow();
     expect(() =>
-      assertVersion(prepared, "1.0.0", "thermos@1.0.0"),
+      assertVersion(prepared, "1.0.0", "warmer@1.0.0"),
     ).not.toThrow();
     expect(() =>
-      assertVersion(prepared, "9.9.9", "acme-plugins/thermos@9.9.9"),
+      assertVersion(prepared, "9.9.9", "acme-plugins/warmer@9.9.9"),
     ).toThrow(
-      /pins version 9\.9\.9, but the marketplace offers 'thermos' at 1\.0\.0\n\nInstall it as 'acme-plugins\/thermos@1\.0\.0'/,
+      /pins version 9\.9\.9, but the marketplace offers 'warmer' at 1\.0\.0\n\nInstall it as 'acme-plugins\/warmer@1\.0\.0'/,
     );
   });
 });
@@ -104,10 +104,10 @@ describe("locateEntry", () => {
   const remoteFiles = {
     "marketplace.json": JSON.stringify({
       name: "remote",
-      plugins: [{ name: "thermos", source: "./thermos" }],
+      plugins: [{ name: "warmer", source: "./warmer" }],
     }),
-    "thermos/plugin.json": JSON.stringify({
-      name: "thermos",
+    "warmer/plugin.json": JSON.stringify({
+      name: "warmer",
       version: "3.0.0",
     }),
   };
@@ -122,7 +122,7 @@ describe("locateEntry", () => {
       source: { type: "local", path: root } as const,
     };
     const located = await locateEntry(
-      parseInstallRef("acme-plugins/thermos"),
+      parseInstallRef("acme-plugins/warmer"),
       listing(local),
     );
     try {
@@ -132,7 +132,7 @@ describe("locateEntry", () => {
       located.open.dispose();
     }
     await expect(
-      locateEntry(parseInstallRef("nowhere/thermos"), listing(local)),
+      locateEntry(parseInstallRef("nowhere/warmer"), listing(local)),
     ).rejects.toThrow(/no marketplace named 'nowhere' is configured/);
   });
 
@@ -142,7 +142,7 @@ describe("locateEntry", () => {
       source: { type: "local", path: root } as const,
     };
     const located = await locateEntry(
-      parseInstallRef("github"),
+      parseInstallRef("codeforge"),
       listing(local),
     );
     try {
@@ -178,11 +178,11 @@ describe("locateEntry", () => {
     };
     const before = countTempTrees();
     await expect(
-      locateEntry(parseInstallRef("thermos"), listing(local, remote), {
+      locateEntry(parseInstallRef("warmer"), listing(local, remote), {
         fetchImpl: servingZipOf(remoteFiles),
       }),
     ).rejects.toThrow(
-      /offered by more than one marketplace: acme-plugins, remote\n\nName the one you mean: acme-plugins\/thermos or remote\/thermos/,
+      /offered by more than one marketplace: acme-plugins, remote\n\nName the one you mean: acme-plugins\/warmer or remote\/warmer/,
     );
     expect(countTempTrees()).toBe(before);
   });
@@ -197,8 +197,8 @@ describe("locateEntry", () => {
       source: { type: "github", repo: "a/b" } as const,
     };
     const requests: string[] = [];
-    // `github` is offered by the local fixture alone: the remote is peeked, not downloaded.
-    const located = await locateEntry(parseInstallRef("github"), listing(local, remote), {
+    // `codeforge` is offered by the local fixture alone: the remote is peeked, not downloaded.
+    const located = await locateEntry(parseInstallRef("codeforge"), listing(local, remote), {
       fetchImpl: servingZipOf(remoteFiles, "r-HEAD", requests),
     });
     located.open.dispose();
@@ -241,7 +241,7 @@ describe("locateEntry", () => {
       source: { type: "github", repo: "a/b" } as const,
     };
     const located = await locateEntry(
-      parseInstallRef("remote/thermos"),
+      parseInstallRef("remote/warmer"),
       listing(remote),
       {
         fetchImpl: servingZipOf(remoteFiles),

package/src/marketplace/read.test.ts

@@ -27,8 +27,8 @@ describe("readMarketplaceTree", () => {
     expect(tree.marketplace.name).toBe("acme-plugins");
     expect(tree.marketplace.dialect).toBe("cursor");
     expect(tree.marketplace.plugins.map((entry) => entry.name)).toEqual([
-      "thermos",
-      "github",
+      "warmer",
+      "codeforge",
     ]);
     expect(tree.warnings).toHaveLength(1);
     expect(tree.warnings[0]?.kind).toBe("entry-directory-missing");
@@ -71,10 +71,10 @@ describe("readMarketplaceTree", () => {
 describe("findEntry and entryDirectory", () => {
   it("resolves an offered entry to its absolute directory and an unknown name to undefined", () => {
     const tree = readMarketplaceTree(root);
-    const github = findEntry(tree.marketplace, "github");
-    expect(github?.dir).toBe("third_party/github");
-    expect(entryDirectory(tree, github!)).toBe(
-      join(root, "third_party", "github"),
+    const codeforge = findEntry(tree.marketplace, "codeforge");
+    expect(codeforge?.dir).toBe("third_party/codeforge");
+    expect(entryDirectory(tree, codeforge!)).toBe(
+      join(root, "third_party", "codeforge"),
     );
     expect(findEntry(tree.marketplace, "ghost")).toBeUndefined();
   });

package/src/marketplace/render.ts

@@ -5,7 +5,6 @@
 // same kind of thing: client-side configuration, not a server collection.
 
 import { readPluginPackage } from "@stigmer/plugin-package";
-import { isBuiltInMarketplaceName } from "@stigmer/plugin-package/client";
 import { CommandResult } from "../output/index.js";
 import { count, readPluginDirectory } from "../resources/plugin.js";
 import {
@@ -27,15 +26,7 @@ export function renderMarketplaceList(
         );
   const section = result.addSection("Sources");
   for (const marketplace of listing.known) {
-    // A built-in reads "built in" beside where it comes from, so the user
-    // knows which names `remove` will refuse.
-    section.field(
-      marketplace.name,
-      isBuiltInMarketplaceName(marketplace.name) &&
-        marketplace.source.type !== "official"
-        ? `${describeSource(marketplace.source)} (built in)`
-        : describeSource(marketplace.source),
-    );
+    section.field(marketplace.name, describeSource(marketplace.source));
   }
   for (const marketplace of listing.unreadable) {
     section.field(marketplace.name, `cannot be read: ${marketplace.reason}`);

package/src/resources/connect/oauth.test.ts

@@ -112,7 +112,7 @@ describe("runOAuthFlow", () => {
       log: () => {},
     });
     expect(openBrowser).toHaveBeenCalledWith(
-      "https://app.stigmer.ai/acme/mcp-servers/github",
+      "https://app.stigmer.ai/library/mcp-servers/acme/github",
     );
   });
 
@@ -152,7 +152,7 @@ describe("runOAuthFlow", () => {
       log: () => {},
     });
     expect(openBrowser).toHaveBeenCalledWith(
-      "http://localhost:7234/acme/mcp-servers/github",
+      "http://localhost:7234/library/mcp-servers/acme/github",
     );
   });
 });

package/src/resources/connect/oauth.ts

@@ -60,7 +60,10 @@ export async function runOAuthFlow(deps: OAuthFlowDeps): Promise<void> {
 
   const slug = deps.server.metadata?.slug ?? "";
   const name = deps.server.metadata?.name ?? slug;
-  const pageURL = `${consoleURL}/${deps.org}/mcp-servers/${slug}`;
+  // The route both consoles serve (`/library/mcp-servers/<org>/<slug>`);
+  // the Go-era `/<org>/mcp-servers/<slug>` answered 404 in the TypeScript
+  // console and sent the user to a dead page.
+  const pageURL = `${consoleURL}/library/mcp-servers/${deps.org}/${slug}`;
 
   log(`OAuth authentication required for '${name}'.`);
   log("Opening web console to complete authentication...");

package/src/resources/plugin.test.ts

@@ -2,8 +2,13 @@
 // sorted sized entries, the ignore matcher applied (defaults, .gitignore,
 // .stigmerignore), symlinks never followed, and the JSON projection that
 // reduces overlay documents to their paths; then the prepared push (the
-// deterministic archive and its SHA-256, the server's own digest) and the
-// install summary renderer.
+// deterministic archive and its SHA-256, the server's own digest), the
+// install summary renderer (only the kinds installed are counted; the Next
+// section says what each server still needs), and `readNextSteps` against an
+// in-memory backend: a sign-in for an OAuth server without a grant, "signed
+// in" with one, the variables an API-key server wants and where they are
+// asked, the agent an MCP-only plugin still needs, and no line for a server
+// the CLI cannot read.
 
 import {
   mkdirSync,
@@ -260,3 +265,115 @@ describe("renderPushOutcome", () => {
     expect(text).toContain("runs on the session's model");
   });
 });
+
+describe("readNextSteps", () => {
+  it("reads what each server still needs, best-effort, and names the agent an MCP-only plugin lacks", async () => {
+    const { readNextSteps, renderPushOutcome } = await import("./plugin.js");
+    const { create } = await import("@bufbuild/protobuf");
+    const { Code, ConnectError, createRouterTransport } =
+      await import("@connectrpc/connect");
+    const { Stigmer } = await import("@stigmer/sdk");
+    const { McpServerQueryController } =
+      await import("@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb");
+    const { McpServerSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb");
+    const { GetOAuthGrantStatusOutputSchema, OAuthConnectionHealth } =
+      await import("@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb");
+    const { McpServerAuthSchema, McpServerSpecSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb");
+    const { EnvVarDeclarationSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb");
+    const { PluginSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb");
+    const { PluginMemberSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/plugin/v1/io_pb");
+    const { ApiResourceKind } =
+      await import("@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb");
+    const { renderResult } = await import("../output/command-result.js");
+
+    const shapes: Record<string, "oauth" | "oauth-granted" | "api-key" | "open" | "missing"> = {
+      linear: "oauth",
+      notion: "oauth-granted",
+      warmth: "api-key",
+      weather: "open",
+      ghost: "missing",
+    };
+    const transport = createRouterTransport(({ service }) => {
+      service(McpServerQueryController, {
+        getByReference: (ref) => {
+          const shape = shapes[ref.slug];
+          if (shape === undefined || shape === "missing")
+            throw new ConnectError("no server", Code.NotFound);
+          const spec = create(McpServerSpecSchema);
+          if (shape === "oauth" || shape === "oauth-granted") {
+            spec.auth = create(McpServerAuthSchema, { targetEnvVar: "TOKEN", oauthOnly: true });
+            spec.env = { TOKEN: create(EnvVarDeclarationSchema, { isSecret: true }) };
+          }
+          if (shape === "api-key") spec.env = { API_TOKEN: create(EnvVarDeclarationSchema, { isSecret: true }) };
+          return create(McpServerSchema, { metadata: { id: `mcp_${ref.slug}`, org: "acme", slug: ref.slug }, spec });
+        },
+        getOAuthGrantStatus: (input) => {
+          const granted = input.resourceId === "mcp_notion";
+          return create(GetOAuthGrantStatusOutputSchema, {
+            connected: granted,
+            connectionHealth: granted
+              ? OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_HEALTHY
+              : OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_NO_GRANT,
+          });
+        },
+      });
+    });
+    const client = new Stigmer({ baseUrl: "/", getAccessToken: () => "t", customTransport: transport });
+    const member = (slug: string) =>
+      create(PluginMemberSchema, { kind: ApiResourceKind.mcp_server, id: `mcp_${slug}`, slug, name: slug });
+
+    const next = await readNextSteps(client, "acme", Object.keys(shapes).map(member));
+    expect(next).toEqual([
+      { kind: "sign-in", server: "linear", command: "stigmer connect mcp-server linear" },
+      { kind: "signed-in", server: "notion" },
+      {
+        kind: "api-key",
+        server: "warmth",
+        variables: ["API_TOKEN"],
+        askedAt: "connect",
+        command: "stigmer connect mcp-server warmth --env API_TOKEN=...",
+      },
+      { kind: "add-to-agent", servers: ["linear", "notion", "warmth", "weather", "ghost"] },
+    ]);
+
+    // With an agent, the variables are the agent's to ask and no agent is missing.
+    const withAgent = await readNextSteps(client, "acme", [
+      member("warmth"),
+      create(PluginMemberSchema, { kind: ApiResourceKind.agent, id: "agt_1", slug: "thermos", name: "thermos" }),
+    ]);
+    expect(withAgent).toEqual([
+      { kind: "api-key", server: "warmth", variables: ["API_TOKEN"], askedAt: "agent" },
+    ]);
+
+    // The renderer names only the kinds installed and prints the Next section.
+    const plugin = create(PluginSchema, {
+      metadata: { id: "plg_1", slug: "linear" },
+      status: { materialized: { skills: 0, mcpServers: 1, agents: 0, workflows: 0 } },
+    });
+    const result = renderPushOutcome(
+      { plugin, members: [member("linear")], archiveBytes: 10 },
+      { next: next.slice(0, 1) },
+    );
+    const lines: string[] = [];
+    const original = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      lines.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+    try {
+      renderResult(result, "human");
+    } finally {
+      process.stderr.write = original;
+    }
+    const text = lines.join("");
+    expect(text).toContain("Installed plugin 'linear' (1 MCP server)");
+    expect(text).not.toContain("0 skills");
+    expect(text).toContain("Next");
+    expect(text).toContain("Sign in to linear:  stigmer connect mcp-server linear");
+  });
+});