@stigmer/cli 3.15.3-dev.20260916211208 → 3.16.1-dev.20260917224426

package/src/commands/install.test.ts

@@ -0,0 +1,289 @@
+// Command-level contract for `stigmer install`: a ref resolves through the
+// configured marketplaces to one entry, whose folder is pushed exactly as
+// `push plugin` would push it (the archive the backend receives is the one
+// 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.
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import {
+  createServer as createHttp2Server,
+  type Http2Server,
+  type ServerHttp2Session,
+} from "node:http2";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import type { ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { PluginSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb";
+import { PluginCommandController } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/command_pb";
+import {
+  ListPluginMembersResponseSchema,
+  type PushPluginRequest,
+} from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/io_pb";
+import { PluginQueryController } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/query_pb";
+import { PluginState } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { classify, ExitCode } from "../errors/index.js";
+import { writeCursorMarketplace } from "../marketplace/__fixtures__/cursor-marketplace.js";
+import { preparePluginPush } from "../resources/plugin.js";
+import { buildProgram } from "../program.js";
+
+let backend: Http2Server;
+let port: number;
+const openSessions = new Set<ServerHttp2Session>();
+let pushes: PushPluginRequest[] = [];
+
+let home: string;
+let fixture: string;
+let originalHome: string | undefined;
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(PluginCommandController, {
+      push: (req) => {
+        pushes.push(req);
+        return create(PluginSchema, {
+          metadata: { id: "plg_1", slug: "thermos", org: "acme" },
+          spec: { name: "thermos", version: "1.0.0" },
+          status: {
+            digest: "a".repeat(64),
+            state: PluginState.READY,
+            materialized: { skills: 1, agents: 1 },
+          },
+        });
+      },
+    });
+    router.service(PluginQueryController, {
+      listMembers: () =>
+        create(ListPluginMembersResponseSchema, {
+          members: [
+            {
+              kind: ApiResourceKind.skill,
+              id: "skl_1",
+              slug: "warm",
+              name: "warm",
+            },
+            {
+              kind: ApiResourceKind.agent,
+              id: "agt_1",
+              slug: "thermos",
+              name: "thermos",
+            },
+          ],
+        }),
+    });
+  };
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  port = (backend.address() as AddressInfo).port;
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+beforeEach(() => {
+  pushes = [];
+  originalHome = process.env.HOME;
+  home = mkdtempSync(join(tmpdir(), "stigmer-install-cmd-"));
+  fixture = mkdtempSync(join(tmpdir(), "stigmer-install-cmd-fixture-"));
+  writeCursorMarketplace(fixture);
+  process.env.HOME = home;
+  mkdirSync(join(home, ".stigmer"), { recursive: true });
+  writeFileSync(
+    join(home, ".stigmer", "config.yaml"),
+    [
+      "backend:",
+      "  type: cloud",
+      "backends:",
+      "  test:",
+      "    type: selfhost",
+      `    endpoint: 127.0.0.1:${port}`,
+      "current_backend: test",
+      "context:",
+      "  organization: acme",
+      "marketplaces:",
+      "  cursor-plugins:",
+      "    type: local",
+      `    path: ${fixture}`,
+      "",
+    ].join("\n"),
+  );
+});
+
+afterEach(() => {
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  rmSync(home, { recursive: true, force: true });
+  rmSync(fixture, { recursive: true, force: true });
+});
+
+interface RunOutcome {
+  readonly exitCode: number;
+  readonly message: string;
+  readonly stdout: string;
+}
+
+/** `stigmer [globals] install <args>`: the program's own flags (`--org`) go before the verb. */
+async function run(
+  args: string[] | string,
+  ...rest: string[]
+): Promise<RunOutcome> {
+  const [globals, local] = Array.isArray(args)
+    ? [args, rest]
+    : [[], [args, ...rest]];
+  const program = buildProgram();
+  program.exitOverride();
+  let stdout = "";
+  const outSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const errSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+  try {
+    await program.parseAsync([
+      "node",
+      "stigmer",
+      ...globals,
+      "install",
+      ...local,
+    ]);
+    return { exitCode: ExitCode.Success, message: "", stdout };
+  } catch (err) {
+    return {
+      exitCode: classify(err)?.exitCode ?? -1,
+      message: err instanceof Error ? err.message : String(err),
+      stdout,
+    };
+  } finally {
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+  }
+}
+
+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");
+    expect(outcome.exitCode).toBe(ExitCode.Success);
+    expect(pushes).toHaveLength(1);
+    const expected = await preparePluginPush(join(fixture, "thermos"));
+    expect(pushes[0]?.org).toBe("acme");
+    expect(
+      Buffer.from(pushes[0]?.artifact ?? []).equals(
+        Buffer.from(expected.archive),
+      ),
+    ).toBe(true);
+    expect(pushes[0]?.message).toBe(
+      "installed from marketplace 'cursor-plugins'",
+    );
+
+    const payload = JSON.parse(outcome.stdout);
+    expect(payload.message).toMatch(
+      /^Installed plugin 'thermos' \(1 skill, 0 MCP servers, 1 agent\)/,
+    );
+    const about = payload.sections.find(
+      (s: { title: string }) => s.title === "Plugin",
+    );
+    expect(about.fields).toContainEqual({
+      key: "Marketplace",
+      value: `cursor-plugins (${fixture})`,
+    });
+    expect(payload.data.members).toHaveLength(2);
+  });
+
+  it("finds a bare name across the configured marketplaces and honours --org, --visibility and --message", async () => {
+    const outcome = await run(
+      ["--org", "other"],
+      "github",
+      "--visibility",
+      "org",
+      "-m",
+      "hello",
+    );
+    expect(outcome.exitCode).toBe(ExitCode.Success);
+    expect(pushes[0]?.org).toBe("other");
+    expect(pushes[0]?.message).toBe("hello");
+    expect(pushes[0]?.visibility).toBeGreaterThan(0);
+  });
+
+  it("--dry-run reads the marketplace and describes the plugin without pushing", async () => {
+    const outcome = await run(
+      "cursor-plugins/thermos@1.0.0",
+      "--dry-run",
+      "--json",
+    );
+    expect(outcome.exitCode).toBe(ExitCode.Success);
+    expect(pushes).toHaveLength(0);
+    const payload = JSON.parse(outcome.stdout);
+    expect(payload.message).toBe(
+      "Dry run: 'cursor-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");
+    expect(outcome.exitCode).toBe(ExitCode.Usage);
+    expect(outcome.message).toMatch(
+      /pins version 9\.9\.9, but the marketplace offers 'thermos' at 1\.0\.0/,
+    );
+    expect(pushes).toHaveLength(0);
+  });
+
+  it("refuses a path toward push plugin, an unknown name, and an unknown marketplace", async () => {
+    expect((await run("./thermos")).message).toMatch(
+      /is a path.*stigmer push plugin \.\/thermos/s,
+    );
+    expect((await run("nope")).message).toMatch(
+      /no configured marketplace offers a plugin named 'nope'/,
+    );
+    expect((await run("nowhere/thermos")).message).toMatch(
+      /no marketplace named 'nowhere' is configured/,
+    );
+    expect(pushes).toHaveLength(0);
+  });
+
+  it("refuses a bare name two marketplaces offer, naming each qualified ref", async () => {
+    const second = mkdtempSync(join(tmpdir(), "stigmer-install-cmd-second-"));
+    try {
+      writeCursorMarketplace(second);
+      const { load, save } = await import("../config/index.js");
+      const config = load();
+      save({
+        ...config,
+        marketplaces: {
+          ...config.marketplaces,
+          second: { type: "local", path: second },
+        },
+      });
+      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/,
+      );
+    } finally {
+      rmSync(second, { recursive: true, force: true });
+    }
+  });
+});

package/src/commands/install.ts

@@ -0,0 +1,108 @@
+// `stigmer install [marketplace/]name[@version]` — install a plugin by name
+// from a marketplace. The verb takes a ref, not a kind: a plugin is the one
+// thing a marketplace offers, so there is nothing to disambiguate. A folder
+// on disk is installed with `stigmer push plugin <dir>`; a path given here is
+// refused toward it.
+//
+// Install is: open the marketplace's tree, find the entry, read its directory
+// through the same walker `push plugin` uses, push the archive. The server
+// does the rest (materialising skills, servers, the agent), exactly as for a
+// push, so an install from a marketplace and a push of the same checked-out
+// folder are one digest and one plugin. There is no `uninstall`:
+// `stigmer delete plugin <name>` is the one delete verb across kinds.
+//
+// Heavy modules load lazily inside the action so `--help` stays fast.
+
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { type OutputFlags, renderResult } from "../output/index.js";
+import { addResultFlags, globalOrg, resultFormat } from "./shared.js";
+
+interface InstallFlags extends OutputFlags {
+  visibility?: string;
+  message?: string;
+  dryRun?: boolean;
+}
+
+export function registerInstall(program: Command): void {
+  const install = program
+    .command("install <ref>")
+    .description(
+      "install a plugin from a marketplace by name: [marketplace/]name[@version]",
+    )
+    .option(
+      "--visibility <level>",
+      "visibility for the plugin and everything it installs (private, org, public, platform)",
+    )
+    .option(
+      "-m, --message <message>",
+      "version message describing what changed",
+    )
+    .option(
+      "--dry-run",
+      "read the marketplace and show what would install, without pushing",
+    )
+    .action((ref: string, options: InstallFlags, command: Command) =>
+      runInstall(ref, options, command),
+    );
+  addResultFlags(install);
+}
+
+async function runInstall(
+  refText: string,
+  options: InstallFlags,
+  command: Command,
+): Promise<void> {
+  const format = resultFormat(options);
+  const m = await import("../marketplace/index.js");
+  const plugin = await import("../resources/plugin.js");
+  const { parseVisibility } = await import("../resources/skill.js");
+  const { CommandResult } = await import("../output/index.js");
+
+  const ref = m.parseInstallRef(refText);
+  const visibility = parseVisibility(options.visibility, "--visibility");
+
+  const located = await m.locateEntry(ref, m.listMarketplaces());
+  try {
+    const prepared = await m.prepareEntry(located.tree, ref.name);
+    m.assertVersion(prepared, ref.version, refText);
+    const qualified = m.formatInstallRef({
+      marketplace: located.marketplace.name,
+      name: ref.name,
+    });
+
+    if (options.dryRun === true) {
+      const result = plugin.describePackageOn(
+        CommandResult.success(
+          `Dry run: '${qualified}' would install plugin '${prepared.plugin.name}'`,
+        ),
+        prepared.plugin,
+        prepared.warnings,
+        prepared.stats,
+      );
+      result.hint("Run without --dry-run to install it.");
+      renderResult(result, format);
+      return;
+    }
+
+    const { connectBackend } = await import("../backend.js");
+    const client = connectBackend();
+    ensureAuthenticated(client.config);
+    const org = resolveOrganization(client.config, globalOrg(command));
+    const outcome = await plugin.pushPrepared(client.stigmer, prepared, {
+      org,
+      visibility,
+      message:
+        options.message ??
+        `installed from marketplace '${located.marketplace.name}'`,
+    });
+    renderResult(
+      plugin.renderPushOutcome(outcome, {
+        installedFrom: `${located.marketplace.name} (${m.describeSource(located.marketplace.source)})`,
+      }),
+      format,
+    );
+  } finally {
+    located.open.dispose();
+  }
+}

package/src/commands/marketplace.test.ts

@@ -0,0 +1,200 @@
+// Command-level contract for `stigmer marketplace`: add reads the source once
+// and records it under the file's own name (or --name), list is offline and
+// names an unreadable entry, show lists what a marketplace offers with each
+// entry's version, remove refuses the built-in name. Over the real config
+// file (HOME redirected) and a local marketplace fixture; no network.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { load } from "../config/index.js";
+import { classify, ExitCode } from "../errors/index.js";
+import { writeCursorMarketplace } from "../marketplace/__fixtures__/cursor-marketplace.js";
+import { buildProgram } from "../program.js";
+
+let home: string;
+let fixture: string;
+let originalHome: string | undefined;
+
+beforeEach(() => {
+  originalHome = process.env.HOME;
+  home = mkdtempSync(join(tmpdir(), "stigmer-marketplace-cmd-"));
+  fixture = mkdtempSync(join(tmpdir(), "stigmer-marketplace-cmd-fixture-"));
+  writeCursorMarketplace(fixture);
+  process.env.HOME = home;
+});
+
+afterEach(() => {
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  rmSync(home, { recursive: true, force: true });
+  rmSync(fixture, { recursive: true, force: true });
+});
+
+interface RunOutcome {
+  readonly exitCode: number;
+  readonly message: string;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+async function run(...args: string[]): Promise<RunOutcome> {
+  const program = buildProgram();
+  program.exitOverride();
+  let stdout = "";
+  let stderr = "";
+  const outSpy = vi
+    .spyOn(process.stdout, "write")
+    .mockImplementation((chunk) => {
+      stdout += String(chunk);
+      return true;
+    });
+  const errSpy = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((chunk) => {
+      stderr += String(chunk);
+      return true;
+    });
+  try {
+    await program.parseAsync(["node", "stigmer", "marketplace", ...args]);
+    return { exitCode: ExitCode.Success, message: "", stdout, stderr };
+  } catch (err) {
+    return {
+      exitCode: classify(err)?.exitCode ?? -1,
+      message: err instanceof Error ? err.message : String(err),
+      stdout,
+      stderr,
+    };
+  } finally {
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+  }
+}
+
+describe("marketplace add", () => {
+  it("reads the source, records it under the file's own name, and says what it offers", async () => {
+    const outcome = await run("add", fixture, "--json");
+    expect(outcome.exitCode).toBe(ExitCode.Success);
+    const payload = JSON.parse(outcome.stdout);
+    expect(payload.message).toBe(
+      `Added marketplace 'cursor-plugins' (${fixture}), offering 2 plugins`,
+    );
+    expect(payload.data).toEqual({
+      name: "cursor-plugins",
+      source: { type: "local", path: fixture },
+      plugins: 2,
+    });
+    expect(load().marketplaces?.["cursor-plugins"]).toEqual({
+      type: "local",
+      path: fixture,
+    });
+  });
+
+  it("records it under --name instead, and refuses a name outside the grammar", async () => {
+    expect((await run("add", fixture, "--name", "cursor")).exitCode).toBe(
+      ExitCode.Success,
+    );
+    expect(Object.keys(load().marketplaces ?? {})).toEqual(["cursor"]);
+    const bad = await run("add", fixture, "--name", "Not Valid");
+    expect(bad.exitCode).toBe(ExitCode.Usage);
+    expect(bad.message).toMatch(/'Not Valid' is not a marketplace name/);
+  });
+
+  it("refuses a directory that is not a marketplace before recording anything", async () => {
+    const outcome = await run("add", home);
+    expect(outcome.exitCode).toBe(ExitCode.Usage);
+    expect(outcome.message).toMatch(/not a marketplace this CLI can read/);
+    expect(load().marketplaces).toBeUndefined();
+  });
+
+  it("refuses the reserved name and a duplicate", async () => {
+    expect((await run("add", fixture, "--name", "stigmer")).message).toMatch(
+      /built-in marketplace/,
+    );
+    await run("add", fixture);
+    expect((await run("add", fixture)).message).toMatch(/already configured/);
+  });
+});
+
+describe("marketplace list", () => {
+  it("is offline, official first, and names an entry it cannot read", async () => {
+    await run("add", fixture);
+    const { save } = await import("../config/index.js");
+    const config = load();
+    save({
+      ...config,
+      marketplaces: { ...config.marketplaces, broken: { type: "gitlab" } },
+    });
+
+    const outcome = await run("list", "--json");
+    expect(outcome.exitCode).toBe(ExitCode.Success);
+    const payload = JSON.parse(outcome.stdout);
+    expect(payload.status).toBe("warning");
+    expect(payload.data.marketplaces).toEqual([
+      { name: "stigmer", source: { type: "official" } },
+      { name: "cursor-plugins", source: { type: "local", path: fixture } },
+      {
+        name: "broken",
+        unreadable: "unknown type 'gitlab' (expected 'github' or 'local')",
+      },
+    ]);
+  });
+});
+
+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");
+    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",
+    );
+    expect(payload.data.plugins).toEqual([
+      {
+        name: "thermos",
+        dir: "thermos",
+        version: "1.0.0",
+        description: "The thermos plugin.",
+      },
+      { name: "github", dir: "third_party/github", version: "2.1.0" },
+    ]);
+    expect(payload.data.warnings).toHaveLength(1);
+    expect(payload.data.warnings[0].subject).toBe("ghost");
+  });
+
+  it("shows the built-in marketplace with assistant as its default", async () => {
+    const outcome = await run("show", "stigmer", "--json");
+    expect(outcome.exitCode).toBe(ExitCode.Success);
+    const payload = JSON.parse(outcome.stdout);
+    expect(payload.data.marketplace.defaults).toEqual(["assistant"]);
+    expect(payload.data.plugins.map((p: { name: string }) => p.name)).toContain(
+      "assistant",
+    );
+  });
+
+  it("refuses an unknown name toward list", async () => {
+    const outcome = await run("show", "nope");
+    expect(outcome.exitCode).toBe(ExitCode.Usage);
+    expect(outcome.message).toMatch(
+      /no marketplace named 'nope'.*stigmer marketplace list/s,
+    );
+  });
+});
+
+describe("marketplace remove", () => {
+  it("removes a configured marketplace and refuses the built-in and an unknown one", async () => {
+    await run("add", fixture);
+    expect((await run("remove", "cursor-plugins")).exitCode).toBe(
+      ExitCode.Success,
+    );
+    expect(load().marketplaces).toBeUndefined();
+    expect((await run("remove", "stigmer")).message).toMatch(
+      /cannot be removed/,
+    );
+    expect((await run("remove", "cursor-plugins")).message).toMatch(
+      /no marketplace named 'cursor-plugins'/,
+    );
+  });
+});