@stigmer/server 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/domain/plugin/__tests__/materialize.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Pins the pure half of a push — what the plan says a package becomes,
+ * before any write: the composed agent's instructions (the versioned
+ * template, snapshot-pinned), a sub-agent's mcp_access naming server
+ * SLUGS while `model_override` stays empty and the hint becomes a warning,
+ * a built-in name becoming a warning, an MCP-only package planning no
+ * agent, the `mcpServers` key-to-slug rule, a skill archive rooted at its
+ * SKILL.md with the plugin's labels on the request, a version the tag
+ * pattern rejects becoming a warning, an overlay that redefines the
+ * transport refused, and the convergence and drop rules over members.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  inMemoryPluginFiles,
+  readPluginPackage,
+} from "@stigmer/plugin-package";
+import type { PluginPackage } from "@stigmer/plugin-package";
+import { cursorPlugin, openPlugin } from "@stigmer/plugin-package/testing";
+import type { PluginFixture } from "@stigmer/plugin-package/testing";
+import { create } from "@bufbuild/protobuf";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import {
+  McpServerSpecSchema,
+  StdioServerConfigSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import { inflateEntry } from "../../../archive/inflate.js";
+import { openArchive } from "../../../archive/open.js";
+import {
+  PLUGIN_LABEL,
+  PLUGIN_VERSION_LABEL,
+} from "../../../pipeline/apiresource-labels.js";
+import {
+  DEFAULT_AGENT_INSTRUCTIONS_VERSION,
+  renderDefaultAgentInstructions,
+} from "../materialize/default-agent-instructions.js";
+import type { PluginIdentity } from "../materialize/identity.js";
+import { McpServerOverlayError } from "../materialize/mcp-servers.js";
+import { planMaterialization } from "../materialize/plan.js";
+import { droppedMembers, membersConverge } from "../members.js";
+import type { Member } from "../members.js";
+
+const IDENTITY: PluginIdentity = {
+  org: "acme",
+  id: "plg_1",
+  slug: "thermos",
+  name: "thermos",
+  digest: "d".repeat(64),
+  visibility: ApiResourceVisibility.visibility_org,
+};
+
+function read(fixture: PluginFixture): PluginPackage {
+  const outcome = readPluginPackage(inMemoryPluginFiles(fixture));
+  if (!outcome.ok) {
+    throw new Error(outcome.errors.map((e) => e.message).join("\n"));
+  }
+  return outcome.plugin;
+}
+
+const thermos = cursorPlugin({
+  name: "thermos",
+  version: "1.2.0",
+  description: "Code review with a thermonuclear standard",
+  skills: [
+    {
+      name: "thermo-review",
+      description: "Review code thoroughly",
+      body: "# Review",
+      files: { "references/checklist.md": "- read it all" },
+    },
+  ],
+  agents: [
+    {
+      file: "reviewer",
+      frontmatter: {
+        name: "reviewer",
+        description: "Reviews",
+        model: "sonnet",
+      },
+      body: "You review pull requests with care.",
+    },
+    {
+      file: "explore",
+      frontmatter: { name: "explore", description: "Shadows a built-in" },
+      body: "You explore the repository far and wide.",
+    },
+  ],
+  mcpServers: {
+    my_github: {
+      type: "http",
+      url: "https://api.githubcopilot.com/mcp/",
+      headers: { Authorization: "Bearer ${GITHUB_TOKEN}" },
+    },
+  },
+  variables: { GITHUB_TOKEN: { type: "string", title: "Token" } },
+  required: ["GITHUB_TOKEN"],
+});
+
+describe("renderDefaultAgentInstructions", () => {
+  it("renders the versioned template for the package", () => {
+    expect(DEFAULT_AGENT_INSTRUCTIONS_VERSION).toBe(1);
+    expect(renderDefaultAgentInstructions(read(thermos))).toBe(
+      [
+        "You are thermos: Code review with a thermonuclear standard",
+        "",
+        "Your skills:",
+        "- thermo-review: Review code thoroughly",
+        "",
+        "Your tools come from these MCP servers:",
+        "- my_github",
+        "",
+        "Before acting on a task a skill covers, read that skill and follow it. " +
+          "Use the tools your servers provide rather than guessing at their results. " +
+          "When you finish, state what you did and what you could not do.",
+      ].join("\n"),
+    );
+  });
+});
+
+describe("planMaterialization", () => {
+  const pkg = read(thermos);
+  const plan = planMaterialization(
+    pkg,
+    inMemoryPluginFiles(thermos),
+    { workflows: [], mcpServers: [] },
+    IDENTITY,
+    "first",
+  );
+
+  it("plans one skill, one server and one agent, in materialisation order", () => {
+    expect(
+      plan.members.map((m) => `${ApiResourceKind[m.kind]}:${m.slug}`),
+    ).toEqual(["skill:thermo-review", "mcp_server:mygithub", "agent:thermos"]);
+    expect(plan.tag).toBe("1.2.0");
+  });
+
+  it("writes the skill's archive rooted at SKILL.md and stamps the plugin's labels on the request", () => {
+    const skill = plan.skills[0]!;
+    expect(skill.request.labels).toEqual({
+      [PLUGIN_LABEL]: "plg_1",
+      [PLUGIN_VERSION_LABEL]: "d".repeat(64),
+    });
+    expect(skill.request.tag).toBe("1.2.0");
+    expect(skill.request.message).toBe("first");
+    const { entries } = openArchive(skill.request.artifact);
+    expect(entries.map((e) => e.name)).toEqual([
+      "SKILL.md",
+      "references/checklist.md",
+    ]);
+    expect(
+      new TextDecoder().decode(inflateEntry(entries[0]!.entry, 1 << 20)),
+    ).toContain("name: thermo-review");
+  });
+
+  it("names servers by slug everywhere a sub-agent or usage refers to them", () => {
+    expect(plan.mcpServers[0]).toMatchObject({
+      name: "my_github",
+      slug: "mygithub",
+    });
+    expect(
+      plan.mcpServers[0]!.resource.spec?.env["GITHUB_TOKEN"],
+    ).toMatchObject({ isSecret: true, optional: false });
+    const agent = plan.agent!.resource;
+    expect(
+      agent.spec?.mcpServerUsages.map((u) => u.mcpServerRef?.slug),
+    ).toEqual(["mygithub"]);
+    expect(
+      agent.spec?.subAgents.map((s) => s.mcpAccess.map((a) => a.mcpServer)),
+    ).toEqual([["mygithub"], ["mygithub"]]);
+  });
+
+  it("records a model hint and a built-in name as warnings and never sets model_override", () => {
+    expect(
+      plan.agent!.resource.spec?.subAgents.map((s) => s.modelOverride),
+    ).toEqual(["", ""]);
+    expect(plan.warnings.map((w) => `${w.kind}:${w.path}`)).toEqual(
+      expect.arrayContaining([
+        "model-hint-unresolved:agents/reviewer.md",
+        "sub-agent-name-builtin:agents/explore.md",
+      ]),
+    );
+  });
+
+  it("plans no agent for an MCP-only package", () => {
+    const mcpOnly = openPlugin({
+      name: "github",
+      mcpServers: {
+        github: { type: "streamable-http", url: "https://example.com/mcp" },
+      },
+    });
+    const onlyPlan = planMaterialization(
+      read(mcpOnly),
+      inMemoryPluginFiles(mcpOnly),
+      { workflows: [], mcpServers: [] },
+      IDENTITY,
+      "",
+    );
+    expect(onlyPlan.agent).toBeUndefined();
+    expect(onlyPlan.members.map((m) => ApiResourceKind[m.kind])).toEqual([
+      "mcp_server",
+    ]);
+  });
+
+  it("warns and leaves the tag empty when the manifest version does not fit the tag pattern", () => {
+    const built = cursorPlugin({
+      name: "b",
+      version: "1.0.0+build.7",
+      skills: [{ name: "s" }],
+    });
+    const builtPlan = planMaterialization(
+      read(built),
+      inMemoryPluginFiles(built),
+      { workflows: [], mcpServers: [] },
+      IDENTITY,
+      "",
+    );
+    expect(builtPlan.tag).toBe("");
+    expect(builtPlan.warnings.map((w) => w.kind)).toContain(
+      "version-not-taggable",
+    );
+    expect(builtPlan.skills[0]!.request.tag).toBe("");
+  });
+
+  it("refuses a server overlay that redefines the transport", () => {
+    const overlay = create(McpServerSchema, {
+      spec: create(McpServerSpecSchema, {
+        serverType: {
+          case: "stdio",
+          value: create(StdioServerConfigSchema, { command: "npx" }),
+        },
+      }),
+    });
+    expect(() =>
+      planMaterialization(
+        pkg,
+        inMemoryPluginFiles(thermos),
+        {
+          workflows: [],
+          mcpServers: [
+            {
+              path: "ai.stigmer/mcp-servers/my_github.yaml",
+              server: "my_github",
+              resource: overlay,
+            },
+          ],
+        },
+        IDENTITY,
+        "",
+      ),
+    ).toThrow(McpServerOverlayError);
+  });
+});
+
+describe("members: convergence and drops", () => {
+  const digest = "d".repeat(64);
+  const stored: Member[] = [
+    {
+      kind: ApiResourceKind.skill,
+      id: "skl_1",
+      slug: "thermo-review",
+      name: "thermo-review",
+      version: digest,
+    },
+    {
+      kind: ApiResourceKind.agent,
+      id: "agt_1",
+      slug: "thermos",
+      name: "thermos",
+      version: digest,
+    },
+  ];
+  const planned = [
+    {
+      kind: ApiResourceKind.skill,
+      slug: "thermo-review",
+      name: "thermo-review",
+    },
+    { kind: ApiResourceKind.agent, slug: "thermos", name: "thermos" },
+  ];
+
+  it("converges only when every planned member is present and stamped with the digest", () => {
+    expect(membersConverge(stored, planned, digest)).toBe(true);
+    expect(membersConverge(stored, planned, "e".repeat(64))).toBe(false);
+    expect(membersConverge(stored.slice(1), planned, digest)).toBe(false);
+    expect(
+      membersConverge(
+        [...stored, { ...stored[0]!, slug: "extra", id: "skl_2" }],
+        planned,
+        digest,
+      ),
+    ).toBe(false);
+  });
+
+  it("drops the members the plan no longer names", () => {
+    expect(droppedMembers(stored, planned.slice(1)).map((m) => m.slug)).toEqual(
+      ["thermo-review"],
+    );
+    expect(droppedMembers(stored, planned)).toEqual([]);
+  });
+});

package/src/domain/plugin/__tests__/overlay-parse.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Pins the overlay parser as the server twin of the SDK's strict manifest
+ * parse: a document the CLI accepts parses (camelCase and proto field
+ * names both), an unknown field refuses naming the path, a wrong `kind`
+ * refuses, a missing `kind` refuses, an empty or non-mapping document
+ * refuses, a foreign `metadata.org` refuses while an empty or matching
+ * one passes, and malformed YAML refuses with the parser's message.
+ */
+import { describe, expect, it } from "vitest";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+
+import { OverlayParseError, parseOverlayDocument } from "../overlay/parse.js";
+
+const encoder = new TextEncoder();
+const AGENT = { schema: AgentSchema, yamlKind: "Agent", org: "acme" };
+
+function parse(text: string) {
+  return parseOverlayDocument(
+    "ai.stigmer/agent.yaml",
+    encoder.encode(text),
+    AGENT,
+  );
+}
+
+function refusal(text: string): string {
+  try {
+    parse(text);
+  } catch (error) {
+    expect(error).toBeInstanceOf(OverlayParseError);
+    return (error as OverlayParseError).message;
+  }
+  throw new Error("expected a refusal");
+}
+
+describe("parseOverlayDocument", () => {
+  it("parses a document the CLI accepts, in either field casing", () => {
+    const agent = parse(
+      "apiVersion: agentic.stigmer.ai/v1\nkind: Agent\nmetadata:\n  name: thermos\nspec:\n  instructions: Long enough instructions here.\n  skill_refs:\n    - slug: a\n  skillRefs:\n    - slug: b\n",
+    );
+    expect(agent.metadata?.name).toBe("thermos");
+    expect(agent.spec?.skillRefs.map((r) => r.slug)).toContain("b");
+  });
+
+  it("refuses an unknown field, naming the document", () => {
+    expect(
+      refusal("kind: Agent\nmetadata:\n  name: t\nspec:\n  colour: blue\n"),
+    ).toContain("overlay document 'ai.stigmer/agent.yaml': invalid Agent:");
+  });
+
+  it("refuses a kind other than the one its location holds", () => {
+    expect(refusal("kind: Workflow\nmetadata:\n  name: t\n")).toBe(
+      "overlay document 'ai.stigmer/agent.yaml': kind 'Workflow' is not the Agent this location holds",
+    );
+  });
+
+  it("refuses a missing kind", () => {
+    expect(refusal("metadata:\n  name: t\n")).toContain(
+      "missing the required 'kind' field (expected kind: Agent)",
+    );
+  });
+
+  it("refuses an empty or non-mapping document", () => {
+    expect(refusal("   \n")).toContain("the document is empty");
+    expect(refusal("- a\n- b\n")).toContain("expected a mapping document");
+  });
+
+  it("refuses a foreign org and accepts an empty or matching one", () => {
+    expect(
+      refusal("kind: Agent\nmetadata:\n  name: t\n  org: other\n"),
+    ).toContain(
+      "metadata.org 'other' is not the organization the plugin is installed into ('acme')",
+    );
+    expect(
+      parse("kind: Agent\nmetadata:\n  name: t\n  org: acme\n").metadata?.org,
+    ).toBe("acme");
+    expect(parse("kind: Agent\nmetadata:\n  name: t\n").metadata?.org).toBe("");
+  });
+
+  it("refuses malformed YAML with the parser's message", () => {
+    expect(refusal("kind: Agent\nmetadata: [unclosed\n")).toContain(
+      "invalid YAML:",
+    );
+  });
+});