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

package/src/local/plugins/defaults.test.ts

@@ -0,0 +1,238 @@
+// Pins the default-set step over a real Connect backend: a default absent
+// from the org is pushed public with the CLI's message; one present at the
+// same digest, READY and public is skipped without a push; a changed digest,
+// a non-READY state or a non-public visibility pushes again; the defaults go
+// in the marketplace's order; one failure does not stop the next; and a
+// second run over a converged backend pushes nothing.
+
+import { createHash } from "node:crypto";
+import { 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 { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import {
+  type Plugin,
+  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 { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
+import type { Stigmer } from "@stigmer/sdk";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { writeCursorMarketplace } from "../../marketplace/__fixtures__/cursor-marketplace.js";
+import { preparePluginPush } from "../../resources/plugin.js";
+import { installDefaultPlugins } from "./defaults.js";
+
+let backend: Http2Server;
+let stigmer: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+/** The backend's plugins by slug; tests seed it and pushes converge it. */
+let held: Map<string, Plugin>;
+let pushes: PushPluginRequest[];
+/** Slugs whose push the backend refuses, to prove one failure does not stop the next. */
+let refusing: Set<string>;
+
+let official: string;
+let thermosDigest: string;
+let githubDigest: string;
+
+function pluginRow(
+  slug: string,
+  digest: string,
+  state = PluginState.READY,
+  visibility = ApiResourceVisibility.visibility_public,
+): Plugin {
+  return create(PluginSchema, {
+    metadata: { id: `plg_${slug}`, slug, org: "stigmer", visibility },
+    spec: { name: slug },
+    status: { digest, state },
+  });
+}
+
+beforeAll(async () => {
+  official = mkdtempSync(join(tmpdir(), "stigmer-defaults-official-"));
+  writeCursorMarketplace(official);
+  // The fixture is Cursor-dialect (no `defaults`); the official tree is Stigmer's, so write that file over it.
+  rmSync(join(official, ".cursor-plugin"), { recursive: true, force: true });
+  writeFileSync(
+    join(official, "marketplace.json"),
+    JSON.stringify({
+      name: "stigmer",
+      plugins: [
+        { name: "thermos", source: "./thermos" },
+        { name: "github", source: "./third_party/github" },
+      ],
+      defaults: ["thermos", "github"],
+    }),
+  );
+  thermosDigest = (await preparePluginPush(join(official, "thermos"))).digest;
+  githubDigest = (
+    await preparePluginPush(join(official, "third_party", "github"))
+  ).digest;
+
+  const routes = (router: ConnectRouter) => {
+    router.service(PluginCommandController, {
+      push: (req) => {
+        pushes.push(req);
+        // The archive names the plugin: the backend knows the two trees by their digests.
+        const slug =
+          digestOf(req.artifact) === thermosDigest ? "thermos" : "github";
+        if (refusing.has(slug))
+          throw new ConnectError(`refused ${slug}`, Code.FailedPrecondition);
+        const row = pluginRow(
+          slug,
+          digestOf(req.artifact),
+          PluginState.READY,
+          req.visibility,
+        );
+        held.set(slug, row);
+        return row;
+      },
+    });
+    router.service(PluginQueryController, {
+      getByReference: (ref) => {
+        const row = held.get(ref.slug);
+        if (row === undefined)
+          throw new ConnectError(`plugin ${ref.slug} not found`, Code.NotFound);
+        return row;
+      },
+      listMembers: () =>
+        create(ListPluginMembersResponseSchema, { members: [] }),
+    });
+  };
+  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));
+  const port = (backend.address() as AddressInfo).port;
+  stigmer = createNodeClient({
+    baseUrl: normalizeEndpoint(`127.0.0.1:${port}`),
+  });
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+  rmSync(official, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  held = new Map();
+  pushes = [];
+  refusing = new Set();
+});
+
+function digestOf(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+const say = (): void => {};
+
+function run() {
+  return installDefaultPlugins(
+    { stigmer, info: say },
+    { org: "stigmer", official: { repoDir: () => official } },
+  );
+}
+
+describe("installDefaultPlugins", () => {
+  it("installs every default in order, public, with the CLI's message, on a fresh backend", async () => {
+    const result = await run();
+    expect(result.outcomes.map((o) => [o.name, o.action])).toEqual([
+      ["thermos", "installed"],
+      ["github", "installed"],
+    ]);
+    expect(result.failed).toEqual([]);
+    expect(pushes.map((p) => p.org)).toEqual(["stigmer", "stigmer"]);
+    expect(
+      pushes.every(
+        (p) => p.visibility === ApiResourceVisibility.visibility_public,
+      ),
+    ).toBe(true);
+    expect(pushes[0]?.message).toMatch(
+      /^default plugin, installed by stigmer up \(/,
+    );
+    expect(digestOf(pushes[0]!.artifact)).toBe(thermosDigest);
+    expect(digestOf(pushes[1]!.artifact)).toBe(githubDigest);
+  });
+
+  it("pushes nothing when every default is already held at the same digest, READY and public", async () => {
+    held.set("thermos", pluginRow("thermos", thermosDigest));
+    held.set("github", pluginRow("github", githubDigest));
+    const result = await run();
+    expect(result.outcomes.map((o) => o.action)).toEqual([
+      "up-to-date",
+      "up-to-date",
+    ]);
+    expect(pushes).toHaveLength(0);
+  });
+
+  it("pushes again on a changed digest, a non-READY state, or a non-public visibility", async () => {
+    held.set("thermos", pluginRow("thermos", "f".repeat(64)));
+    held.set("github", pluginRow("github", githubDigest, PluginState.FAILED));
+    expect((await run()).outcomes.map((o) => o.action)).toEqual([
+      "installed",
+      "installed",
+    ]);
+    expect(pushes).toHaveLength(2);
+
+    pushes = [];
+    held.set(
+      "thermos",
+      pluginRow(
+        "thermos",
+        thermosDigest,
+        PluginState.READY,
+        ApiResourceVisibility.visibility_private,
+      ),
+    );
+    held.set("github", pluginRow("github", githubDigest));
+    expect((await run()).outcomes.map((o) => o.action)).toEqual([
+      "installed",
+      "up-to-date",
+    ]);
+    expect(pushes).toHaveLength(1);
+  });
+
+  it("a second run over a backend the first converged pushes nothing", async () => {
+    await run();
+    pushes = [];
+    const result = await run();
+    expect(result.outcomes.map((o) => o.action)).toEqual([
+      "up-to-date",
+      "up-to-date",
+    ]);
+    expect(pushes).toHaveLength(0);
+  });
+
+  it("one default failing does not stop the next, and the failure is named", async () => {
+    refusing.add("thermos");
+    const result = await run();
+    expect(result.outcomes.map((o) => [o.name, o.action])).toEqual([
+      ["thermos", "failed"],
+      ["github", "installed"],
+    ]);
+    expect(result.failed).toEqual(["thermos"]);
+    const failed = result.outcomes[0];
+    expect(failed?.action === "failed" && failed.error).toMatch(
+      /refused thermos/,
+    );
+  });
+});

package/src/local/plugins/defaults.ts

@@ -0,0 +1,135 @@
+// The default plugins a fresh local backend is bootstrapped with: the
+// `defaults` list of the official marketplace, installed in order into the
+// system org as public, so the global default-agent lookup and cross-org
+// references find them exactly where the seedpack used to put them.
+//
+// Idempotent by the server's own identity, not a marker file: before each
+// push the entry is prepared (walked, zipped, hashed) and the org's plugin
+// of that name is read back; when its digest equals the prepared archive's,
+// it is READY and it is public, there is nothing to do and nothing is sent.
+// A second `stigmer up` therefore pushes nothing, and a `stigmer up` after
+// an upgrade pushes exactly the entries whose content changed. The record is
+// the server, so any machine that reaches the same backend sees the same
+// answer (the seedpack's cloud-mode rule, made the only rule).
+//
+// Best-effort per entry: one default failing to install does not stop the
+// next, and the caller decides how to surface the failures (the daemon
+// launcher warns and names `stigmer install <name>`).
+
+import { type Stigmer, isNotFound } from "@stigmer/sdk";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { PluginState } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import { log } from "../../logger.js";
+import { VERSION } from "../../version.js";
+import {
+  type ResolveOfficialOptions,
+  resolveOfficialMarketplace,
+} from "../../marketplace/official.js";
+import { readMarketplaceTree } from "../../marketplace/read.js";
+import { prepareEntry } from "../../marketplace/install.js";
+import {
+  type PreparedPluginPush,
+  pushPrepared,
+} from "../../resources/plugin.js";
+
+export interface DefaultPluginsDeps {
+  /** The client bound to the backend being bootstrapped. */
+  readonly stigmer: Stigmer;
+  /** Human progress lines (stderr). */
+  readonly info: (line: string) => void;
+}
+
+export interface DefaultPluginsOptions {
+  /** The org the defaults are installed into: the seedpack's org, until the seedpack is gone. */
+  readonly org: string;
+  /** How the official tree is found (injectable for tests). */
+  readonly official?: ResolveOfficialOptions;
+}
+
+export type DefaultPluginOutcome =
+  | {
+      readonly name: string;
+      readonly action: "installed";
+      readonly digest: string;
+    }
+  | {
+      readonly name: string;
+      readonly action: "up-to-date";
+      readonly digest: string;
+    }
+  | {
+      readonly name: string;
+      readonly action: "failed";
+      readonly error: string;
+    };
+
+export interface DefaultPluginsResult {
+  readonly outcomes: readonly DefaultPluginOutcome[];
+  /** The names that did not land, for the caller's warning. */
+  readonly failed: readonly string[];
+}
+
+/** Install every default the official marketplace names, in order, skipping what the backend already holds. */
+export async function installDefaultPlugins(
+  deps: DefaultPluginsDeps,
+  options: DefaultPluginsOptions,
+): Promise<DefaultPluginsResult> {
+  const official = resolveOfficialMarketplace(options.official);
+  const tree = readMarketplaceTree(official.dir, "the official marketplace");
+
+  const outcomes: DefaultPluginOutcome[] = [];
+  for (const name of tree.marketplace.defaults) {
+    try {
+      const prepared = await prepareEntry(tree, name);
+      if (await isAlreadyInstalled(deps.stigmer, options.org, prepared)) {
+        outcomes.push({ name, action: "up-to-date", digest: prepared.digest });
+        continue;
+      }
+      deps.info(`Installing default plugin '${name}'…`);
+      await pushPrepared(deps.stigmer, prepared, {
+        org: options.org,
+        visibility: ApiResourceVisibility.visibility_public,
+        message: `default plugin, installed by stigmer up (${VERSION})`,
+      });
+      outcomes.push({ name, action: "installed", digest: prepared.digest });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log.warn("default plugin install failed", { name, error: message });
+      outcomes.push({ name, action: "failed", error: message });
+    }
+  }
+  return {
+    outcomes,
+    failed: outcomes
+      .filter((outcome) => outcome.action === "failed")
+      .map((outcome) => outcome.name),
+  };
+}
+
+/**
+ * True when the org already holds this exact archive, materialised and
+ * public. A plugin that is absent (NOT_FOUND) installs; one that is present
+ * with another digest, still installing, failed, or not public is pushed
+ * again, which the server treats as an upgrade or a convergence.
+ */
+async function isAlreadyInstalled(
+  stigmer: Stigmer,
+  org: string,
+  prepared: PreparedPluginPush,
+): Promise<boolean> {
+  let existing;
+  try {
+    existing = await stigmer.plugin.getByReference({
+      org,
+      slug: prepared.plugin.name,
+    });
+  } catch (error) {
+    if (isNotFound(error)) return false;
+    throw error;
+  }
+  return (
+    existing.status?.digest === prepared.digest &&
+    existing.status.state === PluginState.READY &&
+    existing.metadata?.visibility === ApiResourceVisibility.visibility_public
+  );
+}

package/src/local/seedpack/content.ts

@@ -17,7 +17,6 @@
 // package in the lean install (where the package is not a dependency, only an
 // on-demand artifact). `seedpack/src/index.ts` is the one definition both follow.
 
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   cpSync,
@@ -36,7 +35,12 @@ import { ExitCode } from "../../errors/exit-codes.js";
 import { log } from "../../logger.js";
 import { VERSION } from "../../version.js";
 import { runtimesDir } from "../paths.js";
-import { isAcquirableRelease } from "../runtime/runtimes-install.js";
+import {
+  ensureRuntimesRoot,
+  isAcquirableRelease,
+  npmInstallIntoRuntimes,
+  type NpmInstall,
+} from "../runtime/runtimes-install.js";
 
 const SEEDPACK_PACKAGE = "@stigmer/seedpack";
 
@@ -71,7 +75,7 @@ export interface ResolveSeedpackOptions {
   /** Release version of @stigmer/seedpack to acquire (defaults to the CLI version). */
   version?: string;
   /** npm install implementation (injectable for tests). */
-  install?: (installDir: string, spec: string) => void;
+  install?: NpmInstall;
 }
 
 /**
@@ -117,17 +121,10 @@ export function acquireSeedpack(opts: ResolveSeedpackOptions = {}): string {
       );
     }
     log.info(`acquiring ${SEEDPACK_PACKAGE}`, { version, dir: installDir });
-    mkdirSync(installDir, { recursive: true });
-    // A stable package.json root keeps the install deterministic. npm install is
-    // additive and non-pruning, so this prefix is safely shared with the runner.
-    const rootPkg = join(installDir, "package.json");
-    if (!existsSync(rootPkg)) {
-      writeFileSync(
-        rootPkg,
-        `${JSON.stringify({ name: "stigmer-runtime", private: true, version: "0.0.0" }, null, 2)}\n`,
-      );
-    }
-    const install = opts.install ?? installSeedpack;
+    // The same per-version root the server and runner packages install into;
+    // npm install is additive and non-pruning, so the prefix is safely shared.
+    ensureRuntimesRoot(installDir);
+    const install = opts.install ?? npmInstallIntoRuntimes;
     install(installDir, `${SEEDPACK_PACKAGE}@${version}`);
   }
 
@@ -141,34 +138,6 @@ export function acquireSeedpack(opts: ResolveSeedpackOptions = {}): string {
   return pkgDir;
 }
 
-// Install the seedpack package into an isolated prefix. Output is inherited so
-// the user sees the one-time download progress.
-function installSeedpack(installDir: string, spec: string): void {
-  try {
-    execFileSync(
-      "npm",
-      [
-        "install",
-        spec,
-        "--prefix",
-        installDir,
-        "--omit=dev",
-        "--no-audit",
-        "--no-fund",
-      ],
-      {
-        stdio: "inherit",
-      },
-    );
-  } catch (err) {
-    throw new CliExitError(`failed to install ${spec}`, ExitCode.General, [
-      `Command: npm install ${spec} --prefix ${installDir}`,
-      "Ensure npm is on PATH and the network is reachable.",
-      String(err),
-    ]);
-  }
-}
-
 /**
  * Deterministic SHA-256 over the canonical content, identical to
  * `@stigmer/seedpack`'s `contentHash` (and the Go algorithm): files walked in

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

@@ -0,0 +1,62 @@
+// A small Cursor-dialect marketplace written to a directory for the
+// marketplace suites: two plugins offered (one with a skill, one MCP-only,
+// the second under a nested source directory) and one entry whose directory
+// is missing, so every suite sees an offered list and a dropped entry.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export const CURSOR_MARKETPLACE_NAME = "cursor-plugins";
+
+export function writeCursorMarketplace(root: string): void {
+  const write = (rel: string, content: string): void => {
+    const full = join(root, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  };
+  write(
+    ".cursor-plugin/marketplace.json",
+    JSON.stringify({
+      name: CURSOR_MARKETPLACE_NAME,
+      metadata: { description: "A test catalogue" },
+      plugins: [
+        {
+          name: "thermos",
+          source: "thermos",
+          description: "Keeps things warm.",
+        },
+        { name: "github", source: "third_party/github" },
+        { name: "ghost", source: "ghost", description: "Listed, not present." },
+      ],
+    }),
+  );
+  write(
+    "thermos/.cursor-plugin/plugin.json",
+    JSON.stringify({
+      name: "thermos",
+      version: "1.0.0",
+      description: "The thermos plugin.",
+      skills: "./skills/",
+    }),
+  );
+  write(
+    "thermos/skills/warm/SKILL.md",
+    "---\nname: warm\ndescription: Warms.\n---\nKeep it warm.\n",
+  );
+  write(
+    "third_party/github/.cursor-plugin/plugin.json",
+    JSON.stringify({
+      name: "github",
+      version: "2.1.0",
+      mcpServers: "./mcp.json",
+    }),
+  );
+  write(
+    "third_party/github/mcp.json",
+    JSON.stringify({
+      mcpServers: {
+        github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
+      },
+    }),
+  );
+}