@stigmer/cli 3.17.0 → 3.18.0

package/src/commands/bootstrap.ts

@@ -0,0 +1,91 @@
+// `stigmer bootstrap` — make the configured backend a ready Stigmer: the
+// system organization exists and the official marketplace's default plugins
+// are installed into it, public. `stigmer up` does this for the local stack
+// on its own; this verb is for every other shape (a raw self-hosted server
+// behind docker-compose or Helm, the hosted platform's scheduled lane), and
+// runs the very same two phases (local/bootstrap.ts), so "ready" has one
+// meaning everywhere.
+//
+// Flagless on purpose. The org is the system org in every edition, and the
+// defaults are idempotent by the server's digest, so there is nothing to
+// force: a second run over a converged backend changes nothing and says so.
+// The verb never deletes anything; a scheduled lane must be able to run it
+// without that power.
+//
+// Exit is non-zero when any default failed to land, after the outcomes are
+// rendered, so a lane's run is red for the right reason and a human reads
+// what did and did not install. Heavy modules load lazily inside the action
+// so `--help` stays fast.
+
+import type { Command } from "commander";
+import { ensureAuthenticated } from "../config/index.js";
+import { CliExitError } from "../errors/cli-exit-error.js";
+import { ExitCode } from "../errors/exit-codes.js";
+import { CommandResult, type OutputFlags, renderResult } from "../output/index.js";
+import { addResultFlags, resultFormat } from "./shared.js";
+
+export function registerBootstrap(program: Command): void {
+  const bootstrap = program
+    .command("bootstrap")
+    .description(
+      "make the configured backend ready: ensure the system organization and install the default plugins",
+    )
+    .action((options: OutputFlags) => runBootstrapCommand(options));
+  addResultFlags(bootstrap);
+}
+
+async function runBootstrapCommand(flags: OutputFlags): Promise<void> {
+  const [{ connectBackend }, { bootstrapBackend }, { SYSTEM_ORG }] =
+    await Promise.all([
+      import("../backend.js"),
+      import("../local/bootstrap.js"),
+      import("../local/system-org.js"),
+    ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  const say = (line: string): void => {
+    process.stderr.write(`${line}\n`);
+  };
+  const result = await bootstrapBackend(client.stigmer, say);
+
+  const failed = result.plugins.failed;
+  const out =
+    failed.length === 0
+      ? CommandResult.success("Backend is ready")
+      : CommandResult.warning(
+          `Backend bootstrapped with ${failed.length} default plugin${failed.length === 1 ? "" : "s"} not installed`,
+        );
+  out
+    .addSection("System organization")
+    .field("Slug", SYSTEM_ORG)
+    .field("State", result.org);
+  const plugins = out.addSection("Default plugins");
+  for (const outcome of result.plugins.outcomes) {
+    switch (outcome.action) {
+      case "installed":
+      case "up-to-date":
+        plugins.field(outcome.name, outcome.action);
+        break;
+      case "failed":
+        plugins.field(outcome.name, `failed: ${outcome.error}`);
+        break;
+      default: {
+        const exhaustive: never = outcome;
+        throw new Error(`unhandled outcome ${String(exhaustive)}`);
+      }
+    }
+  }
+  if (failed.length > 0) {
+    out.hint("Fix the cause named above and run 'stigmer bootstrap' again.");
+  }
+  renderResult(out, resultFormat(flags));
+
+  if (failed.length > 0) {
+    throw new CliExitError(
+      `default plugin${failed.length === 1 ? "" : "s"} not installed: ${failed.join(", ")}`,
+      ExitCode.General,
+    );
+  }
+}

package/src/commands/install.test.ts

@@ -4,7 +4,10 @@
 // the folder prepares to); --dry-run pushes nothing; a version pin, a path,
 // an unknown name and an ambiguous name refuse with their sentences. A real
 // Connect backend over h2c serves the plugin controllers; the config file
-// (HOME redirected) points a selfhost backend at it.
+// (HOME redirected) points a selfhost backend at it. The global fetch is
+// stubbed: the built-in vendor sources are asked through their marketplace
+// files (answered 404, so they declare nothing) and any download would fail
+// loudly, which pins that a bare install never fetches a vendor's zipball.
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import {
@@ -101,8 +104,20 @@ afterAll(async () => {
   await new Promise<void>((resolve) => backend.close(() => resolve()));
 });
 
+/** Every URL the stubbed fetch was asked; raw files answer 404, anything else refuses. */
+let fetched: string[] = [];
+
 beforeEach(() => {
   pushes = [];
+  fetched = [];
+  vi.stubGlobal("fetch", async (input: RequestInfo | URL) => {
+    const url = String(input);
+    fetched.push(url);
+    if (url.startsWith("https://raw.githubusercontent.com/")) {
+      return new Response("Not Found", { status: 404 });
+    }
+    throw new Error(`unexpected network request in test: ${url}`);
+  });
   originalHome = process.env.HOME;
   home = mkdtempSync(join(tmpdir(), "stigmer-install-cmd-"));
   fixture = mkdtempSync(join(tmpdir(), "stigmer-install-cmd-fixture-"));
@@ -122,7 +137,7 @@ beforeEach(() => {
       "context:",
       "  organization: acme",
       "marketplaces:",
-      "  cursor-plugins:",
+      "  acme-plugins:",
       "    type: local",
       `    path: ${fixture}`,
       "",
@@ -131,6 +146,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  vi.unstubAllGlobals();
   if (originalHome === undefined) delete process.env.HOME;
   else process.env.HOME = originalHome;
   rmSync(home, { recursive: true, force: true });
@@ -184,7 +200,7 @@ async function run(
 
 describe("install", () => {
   it("pushes the entry's folder as push plugin would, into the context org, and renders the install", async () => {
-    const outcome = await run("cursor-plugins/thermos", "--json");
+    const outcome = await run("acme-plugins/thermos", "--json");
     expect(outcome.exitCode).toBe(ExitCode.Success);
     expect(pushes).toHaveLength(1);
     const expected = await preparePluginPush(join(fixture, "thermos"));
@@ -195,7 +211,7 @@ describe("install", () => {
       ),
     ).toBe(true);
     expect(pushes[0]?.message).toBe(
-      "installed from marketplace 'cursor-plugins'",
+      "installed from marketplace 'acme-plugins'",
     );
 
     const payload = JSON.parse(outcome.stdout);
@@ -207,7 +223,7 @@ describe("install", () => {
     );
     expect(about.fields).toContainEqual({
       key: "Marketplace",
-      value: `cursor-plugins (${fixture})`,
+      value: `acme-plugins (${fixture})`,
     });
     expect(payload.data.members).toHaveLength(2);
   });
@@ -229,7 +245,7 @@ describe("install", () => {
 
   it("--dry-run reads the marketplace and describes the plugin without pushing", async () => {
     const outcome = await run(
-      "cursor-plugins/thermos@1.0.0",
+      "acme-plugins/thermos@1.0.0",
       "--dry-run",
       "--json",
     );
@@ -237,13 +253,13 @@ describe("install", () => {
     expect(pushes).toHaveLength(0);
     const payload = JSON.parse(outcome.stdout);
     expect(payload.message).toBe(
-      "Dry run: 'cursor-plugins/thermos' would install plugin 'thermos'",
+      "Dry run: 'acme-plugins/thermos' would install plugin 'thermos'",
     );
     expect(payload.data.plugin.name).toBe("thermos");
   });
 
   it("refuses a version the marketplace does not offer, naming the one it does", async () => {
-    const outcome = await run("cursor-plugins/thermos@9.9.9");
+    const outcome = await run("acme-plugins/thermos@9.9.9");
     expect(outcome.exitCode).toBe(ExitCode.Usage);
     expect(outcome.message).toMatch(
       /pins version 9\.9\.9, but the marketplace offers 'thermos' at 1\.0\.0/,
@@ -280,8 +296,11 @@ describe("install", () => {
       const outcome = await run("thermos");
       expect(outcome.exitCode).toBe(ExitCode.Usage);
       expect(outcome.message).toMatch(
-        /offered by more than one marketplace: cursor-plugins, second\n\nName the one you mean: cursor-plugins\/thermos or second\/thermos/,
+        /offered by more than one marketplace: acme-plugins, second\n\nName the one you mean: acme-plugins\/thermos or second\/thermos/,
       );
+      // The three built-in vendor sources were asked through their files and nothing was downloaded.
+      expect(fetched.filter((url) => url.startsWith("https://raw.githubusercontent.com/cursor/plugins/")).length).toBeGreaterThan(0);
+      expect(fetched.some((url) => url.startsWith("https://codeload.github.com/"))).toBe(false);
     } finally {
       rmSync(second, { recursive: true, force: true });
     }

package/src/commands/marketplace.test.ts

@@ -78,14 +78,14 @@ describe("marketplace add", () => {
     expect(outcome.exitCode).toBe(ExitCode.Success);
     const payload = JSON.parse(outcome.stdout);
     expect(payload.message).toBe(
-      `Added marketplace 'cursor-plugins' (${fixture}), offering 2 plugins`,
+      `Added source 'acme-plugins' (${fixture}), offering 2 plugins`,
     );
     expect(payload.data).toEqual({
-      name: "cursor-plugins",
+      name: "acme-plugins",
       source: { type: "local", path: fixture },
       plugins: 2,
     });
-    expect(load().marketplaces?.["cursor-plugins"]).toEqual({
+    expect(load().marketplaces?.["acme-plugins"]).toEqual({
       type: "local",
       path: fixture,
     });
@@ -108,9 +108,14 @@ describe("marketplace add", () => {
     expect(load().marketplaces).toBeUndefined();
   });
 
-  it("refuses the reserved name and a duplicate", async () => {
+  it("refuses every built-in name toward --name, and a duplicate", async () => {
     expect((await run("add", fixture, "--name", "stigmer")).message).toMatch(
-      /built-in marketplace/,
+      /'stigmer' is a built-in source and cannot be added or replaced[\s\S]*--name/,
+    );
+    // A local clone of a vendor's catalogue names itself after the vendor; the
+    // built-in wins the name and the user is told how to add the clone anyway.
+    expect((await run("add", fixture, "--name", "cursor-plugins")).message).toMatch(
+      /'cursor-plugins' is a built-in source/,
     );
     await run("add", fixture);
     expect((await run("add", fixture)).message).toMatch(/already configured/);
@@ -118,7 +123,7 @@ describe("marketplace add", () => {
 });
 
 describe("marketplace list", () => {
-  it("is offline, official first, and names an entry it cannot read", async () => {
+  it("is offline, the built-ins first, and names an entry it cannot read", async () => {
     await run("add", fixture);
     const { save } = await import("../config/index.js");
     const config = load();
@@ -133,7 +138,13 @@ describe("marketplace list", () => {
     expect(payload.status).toBe("warning");
     expect(payload.data.marketplaces).toEqual([
       { name: "stigmer", source: { type: "official" } },
-      { name: "cursor-plugins", source: { type: "local", path: fixture } },
+      { name: "cursor-plugins", source: { type: "github", repo: "cursor/plugins" } },
+      {
+        name: "claude-code-plugins",
+        source: { type: "github", repo: "anthropics/claude-code" },
+      },
+      { name: "codex-plugins", source: { type: "github", repo: "openai/plugins" } },
+      { name: "acme-plugins", source: { type: "local", path: fixture } },
       {
         name: "broken",
         unreadable: "unknown type 'gitlab' (expected 'github' or 'local')",
@@ -145,11 +156,11 @@ describe("marketplace list", () => {
 describe("marketplace show", () => {
   it("lists the offered plugins with their manifest versions and the entries it could not offer", async () => {
     await run("add", fixture);
-    const outcome = await run("show", "cursor-plugins", "--json");
+    const outcome = await run("show", "acme-plugins", "--json");
     expect(outcome.exitCode).toBe(ExitCode.Success);
     const payload = JSON.parse(outcome.stdout);
     expect(payload.message).toBe(
-      "Marketplace 'cursor-plugins' offers 2 plugins, with 1 warning",
+      "Marketplace 'acme-plugins' offers 2 plugins, with 1 warning",
     );
     expect(payload.data.plugins).toEqual([
       {
@@ -184,17 +195,20 @@ describe("marketplace show", () => {
 });
 
 describe("marketplace remove", () => {
-  it("removes a configured marketplace and refuses the built-in and an unknown one", async () => {
+  it("removes an added source and refuses a built-in and an unknown one", async () => {
     await run("add", fixture);
-    expect((await run("remove", "cursor-plugins")).exitCode).toBe(
+    expect((await run("remove", "acme-plugins")).exitCode).toBe(
       ExitCode.Success,
     );
     expect(load().marketplaces).toBeUndefined();
     expect((await run("remove", "stigmer")).message).toMatch(
-      /cannot be removed/,
+      /'stigmer' is a built-in source and cannot be removed/,
+    );
+    expect((await run("remove", "codex-plugins")).message).toMatch(
+      /'codex-plugins' is a built-in source and cannot be removed/,
     );
-    expect((await run("remove", "cursor-plugins")).message).toMatch(
-      /no marketplace named 'cursor-plugins'/,
+    expect((await run("remove", "acme-plugins")).message).toMatch(
+      /no marketplace named 'acme-plugins'/,
     );
   });
 });

package/src/commands/marketplace.ts

@@ -22,12 +22,14 @@ interface AddFlags extends OutputFlags {
 export function registerMarketplace(program: Command): void {
   const marketplace = program
     .command("marketplace")
-    .description("manage the plugin marketplaces you install from");
+    .description(
+      "manage the sources the Marketplace installs from: the built-in catalogues and the ones you add",
+    );
 
   const add = marketplace
     .command("add <source>")
     .description(
-      "add a marketplace: a directory, a GitHub 'owner/repo[@ref]', or that repository's URL",
+      "add a source: a directory, a GitHub 'owner/repo[@ref]', or that repository's URL",
     )
     .option(
       "--name <name>",
@@ -38,19 +40,19 @@ export function registerMarketplace(program: Command): void {
 
   const list = marketplace
     .command("list")
-    .description("list the configured marketplaces (offline)")
+    .description("list the known sources, built in and added (offline)")
     .action((options: OutputFlags) => runList(options));
   addResultFlags(list);
 
   const show = marketplace
     .command("show <name>")
-    .description("show the plugins a marketplace offers (reads its source)")
+    .description("show the plugins a source offers (reads it)")
     .action((name: string, options: OutputFlags) => runShow(name, options));
   addResultFlags(show);
 
   const remove = marketplace
     .command("remove <name>")
-    .description("remove a configured marketplace (installed plugins stay)")
+    .description("remove an added source (installed plugins stay; a built-in cannot be removed)")
     .action((name: string, options: OutputFlags) => runRemove(name, options));
   addResultFlags(remove);
 }
@@ -81,7 +83,7 @@ async function runAdd(source: string, flags: AddFlags): Promise<void> {
   m.addMarketplace(name, parsed);
 
   const result = CommandResult.success(
-    `Added marketplace '${name}' (${m.describeSource(parsed)}), offering ${offered} plugin${offered === 1 ? "" : "s"}`,
+    `Added source '${name}' (${m.describeSource(parsed)}), offering ${offered} plugin${offered === 1 ? "" : "s"}`,
   );
   result.hint(`See what it offers with: stigmer marketplace show ${name}`);
   result.hint(`Install from it with:     stigmer install ${name}/<plugin>`);
@@ -123,7 +125,7 @@ async function runRemove(name: string, flags: OutputFlags): Promise<void> {
   const m = await import("../marketplace/index.js");
   const { CommandResult } = await import("../output/index.js");
   m.removeMarketplace(name);
-  const result = CommandResult.success(`Removed marketplace '${name}'`);
+  const result = CommandResult.success(`Removed source '${name}'`);
   result.hint(
     "Plugins installed from it stay installed; remove one with: stigmer delete plugin <name>",
   );

package/src/config/resolve.test.ts

@@ -150,11 +150,11 @@ describe("resolveOrganization", () => {
     );
   });
 
-  it("defaults to the seedpack org in local mode when nothing is configured", () => {
+  it("defaults to the system org in local mode when nothing is configured", () => {
     expect(resolveOrganization(localConfig())).toBe("stigmer");
   });
 
-  it("defaults to the seedpack org on a selfhost backend (it IS the OSS server)", () => {
+  it("defaults to the system org on a selfhost backend (it IS the OSS server)", () => {
     expect(resolveOrganization(selfhostConfig())).toBe("stigmer");
   });
 

package/src/config/resolve.ts

@@ -8,6 +8,7 @@
 
 import { CliExitError, ExitCode } from "../errors/index.js";
 import { SERVER_PORT } from "../local/constants.js";
+import { SYSTEM_ORG } from "../local/system-org.js";
 import { type Config, activeBackend, isCloudMode } from "./config.js";
 
 const DEFAULT_CLOUD_ENDPOINT = "api.stigmer.ai:443";
@@ -16,13 +17,13 @@ const DEFAULT_LOCAL_ENDPOINT = "localhost:7234";
 /** Well-known URL for the Stigmer Cloud web console. */
 export const DEFAULT_CLOUD_CONSOLE_URL = "https://app.stigmer.ai";
 
-// Local mode is single-tenant: the seedpack bootstraps resources into the
-// "stigmer" org (see client-apps/cli/src/local/seedpack/apply.ts DEFAULT_ORG).
-// Org-scoped getByReference now requires an org, so bare-slug `get`/`run`/`apply`
-// in local mode fall back to this default when nothing else is configured. The
-// same holds for selfhost backends — they ARE the OSS server. Cloud mode has no
-// implicit org — the caller must select one (flag/env/context/login).
-const DEFAULT_LOCAL_ORG = "stigmer";
+// Local mode is single-tenant: the bootstrap `stigmer up` runs creates the
+// system org and installs the default plugins into it, so bare-slug
+// `get`/`run`/`apply` in local mode fall back to that org when nothing else
+// is configured. The same holds for selfhost backends — they ARE the OSS
+// server. Cloud mode has no implicit org — the caller must select one
+// (flag/env/context/login).
+const DEFAULT_LOCAL_ORG = SYSTEM_ORG;
 
 /**
  * Resolve the server endpoint.

package/src/local/bootstrap.test.ts

@@ -1,71 +1,143 @@
-// Pins the bootstrap's shape: the seedpack step then the default-plugins step,
-// over one client; a seedpack failure is contained by its own step and the
-// plugins step still runs; a plugins failure is a warning that names the
-// retry command, never a throw past the bootstrap.
+// Pins the local bootstrap's shape: prepare, then run, then retire, over one
+// client; a preparation failure skips the run and the retire together, and a
+// run that cannot start skips the retire (nothing is deleted before its
+// replacement is in place); a default that failed to land is one warning
+// naming `stigmer bootstrap` and holds the retire back with a line saying so;
+// a retire failure is contained by its own warning; nothing throws past the
+// bootstrap.
 
 import { describe, expect, it } from "vitest";
+import type { Stigmer } from "@stigmer/sdk";
 import type { BackendClient } from "../client/index.js";
 import {
+  type BootstrapResult,
+  type PreparedBootstrap,
   bootstrapLocalBackend,
-  installDefaultPluginsBestEffort,
 } from "./bootstrap.js";
 
-const client = { stigmer: {} } as unknown as BackendClient;
+const stigmer = {} as unknown as Stigmer;
+const client = { stigmer } as unknown as BackendClient;
+const prepared: PreparedBootstrap = { defaults: [] };
+
+function converged(): BootstrapResult {
+  return { org: "present", plugins: { outcomes: [], failed: [] } };
+}
 
 describe("bootstrapLocalBackend", () => {
-  it("runs the seedpack step then the plugins step, over the same client and home", async () => {
+  it("prepares, runs, then retires, over the same client and home", async () => {
     const order: string[] = [];
     await bootstrapLocalBackend("/home/x", {
       client,
       say: () => {},
-      seedpack: async (c, home) => {
-        expect(c).toBe(client);
-        expect(home).toBe("/home/x");
-        order.push("seedpack");
+      prepare: async () => {
+        order.push("prepare");
+        return prepared;
       },
-      plugins: async (c, home) => {
-        expect(c).toBe(client);
+      run: async (s, p) => {
+        expect(s).toBe(stigmer);
+        expect(p).toBe(prepared);
+        order.push("run");
+        return converged();
+      },
+      retire: async (s, home) => {
+        expect(s).toBe(stigmer);
         expect(home).toBe("/home/x");
-        order.push("plugins");
+        order.push("retire");
       },
     });
-    expect(order).toEqual(["seedpack", "plugins"]);
+    expect(order).toEqual(["prepare", "run", "retire"]);
   });
 
-  it("still runs the plugins step when the seedpack step has warned", async () => {
+  it("skips the run and the retire when preparation fails, with one warning", async () => {
     const said: string[] = [];
-    let plugins = 0;
+    let retired = 0;
+    let ran = 0;
     await bootstrapLocalBackend("/home/x", {
       client,
       say: (line) => said.push(line),
-      seedpack: async (_c, _h, say) => say("Warning: seedpack failed"),
-      plugins: async () => {
-        plugins += 1;
+      prepare: async () => {
+        throw new Error("offline");
+      },
+      run: async () => {
+        ran += 1;
+        return converged();
+      },
+      retire: async () => {
+        retired += 1;
       },
     });
-    expect(plugins).toBe(1);
-    expect(said).toEqual(["Warning: seedpack failed"]);
+    expect(ran).toBe(0);
+    expect(retired).toBe(0);
+    expect(said).toEqual([
+      "Warning: could not prepare the default plugins, so the local backend was not bootstrapped and nothing was retired. Run 'stigmer up' again to retry.",
+    ]);
   });
-});
 
-describe("installDefaultPluginsBestEffort", () => {
-  it("turns a step that cannot even start into one warning naming the retry commands", async () => {
+  it("skips the retire when the run cannot even start, with one warning naming the retry", async () => {
     const said: string[] = [];
-    // A client whose plugin lookups throw: the step's own failure path, not a default's.
-    const broken = {
-      stigmer: {
-        plugin: {
-          getByReference: async () => {
-            throw new Error("backend unreachable");
-          },
+    let retired = 0;
+    await bootstrapLocalBackend("/home/x", {
+      client,
+      say: (line) => said.push(line),
+      prepare: async () => prepared,
+      run: async () => {
+        throw new Error("backend unreachable");
+      },
+      retire: async () => {
+        retired += 1;
+      },
+    });
+    expect(retired).toBe(0);
+    expect(said).toEqual([
+      "Warning: failed to bootstrap the local backend, so nothing was retired. Run 'stigmer up' again to retry.",
+    ]);
+  });
+
+  it("holds the retire back when a default did not land, naming the default and saying why", async () => {
+    const said: string[] = [];
+    let retired = 0;
+    await bootstrapLocalBackend("/home/x", {
+      client,
+      say: (line) => said.push(line),
+      prepare: async () => prepared,
+      run: async () => ({
+        org: "created",
+        plugins: {
+          outcomes: [
+            { name: "assistant", action: "failed", error: "refused" },
+          ],
+          failed: ["assistant"],
         },
+      }),
+      retire: async () => {
+        retired += 1;
       },
-    } as unknown as BackendClient;
-    await installDefaultPluginsBestEffort(broken, "/home/x", (line) =>
-      said.push(line),
-    );
-    expect(said.filter((line) => line.startsWith("Warning:"))).toEqual([
-      "Warning: failed to install default plugin 'assistant'. Run 'stigmer install assistant' to retry.",
+    });
+    expect(retired).toBe(0);
+    expect(said).toEqual([
+      "Warning: failed to install default plugin 'assistant'. Run 'stigmer bootstrap' to retry.",
+      "Nothing was retired: the resources an older release installed stay until every default plugin is in place.",
+    ]);
+  });
+
+  it("contains a retire that threw in one warning, after the run succeeded", async () => {
+    const said: string[] = [];
+    let ran = 0;
+    await bootstrapLocalBackend("/home/x", {
+      client,
+      say: (line) => said.push(line),
+      prepare: async () => prepared,
+      run: async () => {
+        ran += 1;
+        return converged();
+      },
+      retire: async () => {
+        throw new Error("project read failed");
+      },
+    });
+    expect(ran).toBe(1);
+    expect(said).toEqual([
+      "Warning: failed to retire the resources an older release installed. Run 'stigmer up' again to retry.",
     ]);
   });
 });