@stigmer/plugin-package 3.34.0 → 3.36.0

package/src/__tests__/presentation.test.ts

@@ -1,186 +0,0 @@
-/**
- * The presentation read, the one a storefront card runs.
- *
- * Pins: the vendored Cursor fixtures yield their `displayName`, `logo`,
- * `category` and author (thermos, a PNG; playwright, an SVG); a Codex
- * manifest yields the same fields from `interface`, with the `./` spelling
- * stripped; a Claude manifest yields identity only, and so does an open
- * manifest until it carries `extensions["ai.stigmer"]`, which speaks the
- * same three fields under the same logo rules; a
- * root manifest names the plugin ahead of a vendor manifest beside it,
- * while the vendor manifest still lends its appearance; a logo that is
- * absent from the listing, over the cap, not an image, a URL or an escape
- * is dropped without a finding; an unparseable manifest contributes nothing
- * and the read still answers. The lazy twin reads exactly the manifests
- * listed and no other file, and treats a fetch that rejects as a manifest
- * that is not there.
- */
-
-import { fileURLToPath } from "node:url";
-
-import { describe, expect, it } from "vitest";
-
-import { type LazyCandidate } from "../client/prepare.js";
-import { readPluginPresentationFromTree } from "../client/presentation.js";
-import { inMemoryPluginFiles, PLUGIN_DOCUMENT_LIMITS } from "../files.js";
-import { MANIFEST_LOCATIONS } from "../messages.js";
-import { readPluginPresentation } from "../presentation.js";
-import { claudePlugin, codexPlugin, cursorPlugin, openPlugin, withFile, type PluginFixture } from "../testing.js";
-import { directoryPluginFiles } from "../__test-utils__/directory-files.js";
-
-const FIXTURES = fileURLToPath(new URL("./fixtures/cursor-plugins/", import.meta.url));
-const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
-
-function present(files: PluginFixture) {
-  return readPluginPresentation(inMemoryPluginFiles(files));
-}
-
-describe("readPluginPresentation over the vendored Cursor fixtures", () => {
-  it("thermos: display name, PNG logo, category, author", () => {
-    const presentation = readPluginPresentation(directoryPluginFiles(`${FIXTURES}thermos`));
-    expect(presentation).toEqual({
-      displayName: "Thermos",
-      logo: "assets/logo.png",
-      category: "developer-tools",
-      version: "1.0.0",
-      description: expect.stringContaining("Thermo-nuclear branch review"),
-      author: { name: "Cursor", email: "plugins@cursor.com" },
-    });
-  });
-
-  it("playwright: an SVG logo is an image too", () => {
-    const presentation = readPluginPresentation(directoryPluginFiles(`${FIXTURES}playwright`));
-    expect(presentation.displayName).toBe("Playwright");
-    expect(presentation.logo).toBe("assets/logo.svg");
-  });
-});
-
-describe("the dialects that carry appearance", () => {
-  it("a Cursor manifest speaks at its top level", () => {
-    const files = withFile(
-      cursorPlugin({ manifest: { displayName: "GitHub", logo: "assets/logo.png", category: "integrations", author: { name: "Cursor" } } }),
-      "assets/logo.png",
-      PNG_BYTES,
-    );
-    expect(present(files)).toMatchObject({ displayName: "GitHub", logo: "assets/logo.png", category: "integrations", author: { name: "Cursor" } });
-  });
-
-  it("a legacy Codex manifest speaks through `interface`, and `./` is stripped from its logo", () => {
-    const files = withFile(
-      codexPlugin({
-        version: "6.0.1",
-        manifest: { interface: { displayName: "Airtable", logo: "./assets/logo.png", category: "Productivity", developerName: "Airtable" } },
-      }),
-      "assets/logo.png",
-      PNG_BYTES,
-    );
-    expect(present(files)).toEqual({ displayName: "Airtable", logo: "assets/logo.png", category: "Productivity", version: "6.0.1" });
-  });
-
-  it("a Claude manifest and an open manifest without the extension yield identity only", () => {
-    expect(present(claudePlugin({ version: "1.0.0", description: "Reviews pull requests.", manifest: { author: { name: "Anthropic" } } }))).toEqual({
-      version: "1.0.0",
-      description: "Reviews pull requests.",
-      author: { name: "Anthropic" },
-    });
-    const open = present(openPlugin({ version: "2.0.0", description: "The assistant." }));
-    expect(open.displayName).toBeUndefined();
-    expect(open.logo).toBeUndefined();
-    expect(open.version).toBe("2.0.0");
-  });
-
-  it("an open manifest speaks through extensions[\"ai.stigmer\"], under the same logo rules as a vendor manifest", () => {
-    const files = withFile(
-      openPlugin({
-        version: "1.0.0",
-        description: "Linear's hosted MCP server.",
-        manifest: { author: { name: "Stigmer" }, extensions: { "ai.stigmer": { displayName: "Linear", logo: "assets/logo.png", category: "integrations" } } },
-      }),
-      "assets/logo.png",
-      PNG_BYTES,
-    );
-    expect(present(files)).toEqual({
-      displayName: "Linear",
-      logo: "assets/logo.png",
-      category: "integrations",
-      version: "1.0.0",
-      description: "Linear's hosted MCP server.",
-      author: { name: "Stigmer" },
-    });
-    const unlisted = present(openPlugin({ manifest: { extensions: { "ai.stigmer": { displayName: "Linear", logo: "assets/missing.png" } } } }));
-    expect(unlisted).toEqual({ displayName: "Linear" });
-    expect(present(openPlugin({ manifest: { extensions: { "ai.stigmer": "nope" } } }))).toEqual({});
-  });
-
-  it("a root manifest names the plugin first; a vendor manifest beside it still lends its appearance", () => {
-    let files = openPlugin({ version: "3.0.0", description: "From the root manifest." });
-    files = withFile(
-      files,
-      MANIFEST_LOCATIONS.cursor,
-      JSON.stringify({ name: "plugin", version: "1.0.0", description: "From the Cursor manifest.", displayName: "Plugin", logo: "assets/logo.png" }),
-    );
-    files = withFile(files, "assets/logo.png", PNG_BYTES);
-    expect(present(files)).toMatchObject({ version: "3.0.0", description: "From the root manifest.", displayName: "Plugin", logo: "assets/logo.png" });
-  });
-});
-
-describe("a logo that cannot be shown is no logo, never a finding", () => {
-  const cases: readonly [string, string, PluginFixture | undefined][] = [
-    ["not listed", "assets/missing.png", undefined],
-    ["a URL", "https://example.com/logo.png", undefined],
-    ["an escape", "../logo.png", undefined],
-    ["not an image", "assets/logo.txt", withFile(cursorPlugin(), "assets/logo.txt", "text")],
-    ["over the cap", "assets/huge.png", withFile(cursorPlugin(), "assets/huge.png", new Uint8Array(PLUGIN_DOCUMENT_LIMITS.logo + 1))],
-  ];
-  for (const [label, logo, base] of cases) {
-    it(label, () => {
-      const files = withFile(base ?? cursorPlugin(), MANIFEST_LOCATIONS.cursor, JSON.stringify({ name: "plugin", displayName: "Plugin", logo }));
-      const presentation = present(files);
-      expect(presentation.displayName).toBe("Plugin");
-      expect(presentation.logo).toBeUndefined();
-    });
-  }
-
-  it("a wrong type is absent", () => {
-    const files = withFile(cursorPlugin(), MANIFEST_LOCATIONS.cursor, JSON.stringify({ name: "plugin", displayName: 7, logo: ["assets/logo.png"], author: "Cursor" }));
-    expect(present(files)).toEqual({});
-  });
-
-  it("an unparseable manifest contributes nothing and the read answers", () => {
-    const files = withFile(cursorPlugin({ version: "1.0.0" }), MANIFEST_LOCATIONS.cursor, "{ not json");
-    expect(present(files)).toEqual({});
-  });
-});
-
-describe("readPluginPresentationFromTree", () => {
-  function lazy(files: PluginFixture, reads: string[], failing: ReadonlySet<string> = new Set()): LazyCandidate[] {
-    const encoder = new TextEncoder();
-    return [...files.entries()].map(([path, content]) => {
-      const bytes = typeof content === "string" ? encoder.encode(content) : content;
-      return {
-        path,
-        size: bytes.length,
-        read: async () => {
-          reads.push(path);
-          if (failing.has(path)) throw new Error(`cannot read ${path}`);
-          return bytes;
-        },
-      };
-    });
-  }
-
-  it("reads exactly the manifests listed and no other file", async () => {
-    const reads: string[] = [];
-    const files = withFile(cursorPlugin({ manifest: { displayName: "Thermos", logo: "assets/logo.png" }, skills: [{ name: "review" }] }), "assets/logo.png", PNG_BYTES);
-    const presentation = await readPluginPresentationFromTree(lazy(files, reads));
-    expect(presentation).toMatchObject({ displayName: "Thermos", logo: "assets/logo.png" });
-    expect(reads).toEqual([MANIFEST_LOCATIONS.cursor]);
-  });
-
-  it("a manifest whose fetch rejects is a manifest that is not there", async () => {
-    const reads: string[] = [];
-    const files = cursorPlugin({ manifest: { displayName: "Thermos" } });
-    const presentation = await readPluginPresentationFromTree(lazy(files, reads, new Set([MANIFEST_LOCATIONS.cursor])));
-    expect(presentation).toEqual({});
-  });
-});

package/src/__tests__/skills.test.ts

@@ -1,89 +0,0 @@
-/**
- * Pins skill discovery across the dialects (the fixed `skills/` children,
- * declared paths that are a skill or a directory of skills, Claude's root
- * single skill) and the frontmatter check's relaxations (name defaulted to
- * the directory, name differing from the directory, description missing),
- * plus the per-skill file listing the installer builds archives from.
- */
-
-import { describe, expect, it } from "vitest";
-
-import { claudePlugin, cursorPlugin, openPlugin, withFile } from "../testing.js";
-import { accepted, kindsOf, read } from "../__test-utils__/read.js";
-
-describe("discovery", () => {
-  it("reads the immediate children of skills/ that hold SKILL.md, and lists each skill's files", () => {
-    const files = openPlugin({
-      skills: [
-        { name: "alpha", description: "A", files: { "scripts/run.sh": "echo", "references/REF.md": "ref" } },
-        { name: "beta", description: "B" },
-      ],
-    });
-    files.set("skills/not-a-skill/README.md", "no SKILL.md here");
-    files.set("skills/alpha/nested/deeper/SKILL.md", "---\nname: deeper\ndescription: d\n---\nbody");
-    const plugin = accepted(read(files));
-    expect(plugin.skills.map((s) => s.name)).toEqual(["alpha", "beta"]);
-    expect(plugin.skills[0]).toMatchObject({
-      dir: "skills/alpha",
-      files: ["skills/alpha/SKILL.md", "skills/alpha/nested/deeper/SKILL.md", "skills/alpha/references/REF.md", "skills/alpha/scripts/run.sh"],
-    });
-  });
-
-  it("reads a declared directory of skills and a declared path that is itself a skill", () => {
-    const files = claudePlugin({ manifest: { skills: ["./extra/", "./solo"] } });
-    files.set("extra/one/SKILL.md", "---\nname: one\ndescription: d\n---\nbody");
-    files.set("solo/SKILL.md", "---\nname: solo\ndescription: d\n---\nbody");
-    files.set("skills/base/SKILL.md", "---\nname: base\ndescription: d\n---\nbody");
-    const plugin = accepted(read(files));
-    expect(plugin.skills.map((s) => s.dir)).toEqual(["extra/one", "skills/base", "solo"]);
-  });
-
-  it("reads a root SKILL.md as a single skill when nothing else declares skills", () => {
-    const files = claudePlugin({ name: "solo-skill" });
-    files.set("SKILL.md", "---\nname: solo-skill\ndescription: d\n---\nbody");
-    files.set("README.md", "readme");
-    const plugin = accepted(read(files));
-    expect(plugin.skills).toHaveLength(1);
-    expect(plugin.skills[0]).toMatchObject({ name: "solo-skill", dir: "" });
-    expect(plugin.skills[0]?.files).toContain("README.md");
-  });
-
-  it("does not read a root SKILL.md when skills/ exists", () => {
-    const files = openPlugin({ skills: [{ name: "a", description: "d" }] });
-    files.set("SKILL.md", "---\nname: root\ndescription: d\n---\nbody");
-    expect(accepted(read(files)).skills.map((s) => s.name)).toEqual(["a"]);
-  });
-
-  it("warns on a declared skills path that names nothing", () => {
-    const outcome = read(cursorPlugin({ manifest: { skills: "./missing/" } }));
-    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: ["path-missing"] });
-  });
-});
-
-describe("frontmatter", () => {
-  it("accepts optional and vendor frontmatter keys silently", () => {
-    const files = openPlugin({
-      skills: [{ name: "a", description: "d", frontmatter: { license: "MIT", metadata: { author: "x" }, "allowed-tools": "Bash", "disable-model-invocation": true, icon: "bulb" } }],
-    });
-    expect(kindsOf(read(files))).toEqual({ errors: [], warnings: [] });
-  });
-
-  it("names a skill after its directory when the frontmatter has no name, with a warning", () => {
-    const files = withFile(openPlugin(), "skills/from-dir/SKILL.md", "---\ndescription: d\n---\nbody");
-    const outcome = read(files);
-    expect(kindsOf(outcome).warnings).toEqual(["skill-name-defaulted"]);
-    expect(accepted(outcome).skills[0]?.name).toBe("from-dir");
-  });
-
-  it("warns when the name differs from the directory and when the description is missing", () => {
-    const files = openPlugin({ skills: [{ name: "real-name", dir: "other-dir" }] });
-    const outcome = read(files);
-    expect(kindsOf(outcome).warnings).toEqual(["skill-description-missing", "skill-name-differs-from-directory"]);
-    expect(accepted(outcome).skills[0]).toMatchObject({ name: "real-name", dir: "skills/other-dir" });
-  });
-
-  it("accepts Stigmer's dot-scoped names, a superset of the Agent Skills rule", () => {
-    const plugin = accepted(read(openPlugin({ skills: [{ name: "platform.my-skill", description: "d" }] })));
-    expect(plugin.skills[0]?.name).toBe("platform.my-skill");
-  });
-});

package/src/__tests__/sub-agents.test.ts

@@ -1,111 +0,0 @@
-/**
- * Pins sub-agent normalisation: `agents/*.md` read under vendor manifests
- * and recorded as ignored under a root-only manifest; the body as
- * instructions; name from frontmatter or file stem; Claude `skills:`
- * matched to the plugin's skills; `model` classified into an alias (never
- * an id); every other frontmatter field warned once; declared agent paths
- * that are files or directories.
- */
-
-import { describe, expect, it } from "vitest";
-
-import { classifyModel } from "../normalise/sub-agents.js";
-import { claudePlugin, cursorPlugin, openPlugin } from "../testing.js";
-import { accepted, kindsOf, read } from "../__test-utils__/read.js";
-
-describe("discovery", () => {
-  it("reads agents/*.md under a Cursor manifest into SubAgent shapes", () => {
-    const plugin = accepted(
-      read(
-        cursorPlugin({
-          agents: [{ file: "reviewer", frontmatter: { name: "code-reviewer", description: "Reviews code." }, body: "Review the diff carefully and report findings.\n" }],
-        }),
-      ),
-    );
-    expect(plugin.subAgents).toEqual([
-      {
-        name: "code-reviewer",
-        description: "Reviews code.",
-        instructions: "Review the diff carefully and report findings.",
-        skillNames: [],
-        path: "agents/reviewer.md",
-      },
-    ]);
-  });
-
-  it("records agents/ as ignored, unread, under a root-only manifest", () => {
-    const files = openPlugin();
-    files.set("agents/x.md", "---\nname: x\n---\nthis frontmatter would be fine");
-    const plugin = accepted(read(files));
-    expect(plugin.subAgents).toEqual([]);
-    expect(plugin.ignored).toEqual([{ kind: "agents", path: "agents/" }]);
-  });
-
-  it("reads declared agent files and directories, replacing the default directory", () => {
-    const files = claudePlugin({ manifest: { agents: ["./custom/one.md", "./more/"] } });
-    files.set("custom/one.md", "---\nname: one\n---\nDo the first thing well.");
-    files.set("more/two.md", "---\nname: two\n---\nDo the second thing well.");
-    files.set("agents/ignored.md", "---\nname: three\n---\nNot read: the manifest replaced agents/.");
-    const plugin = accepted(read(files));
-    expect(plugin.subAgents.map((a) => a.name)).toEqual(["one", "two"]);
-  });
-
-  it("names a bare prompt after its file with a warning", () => {
-    const outcome = read(claudePlugin({ agents: [{ file: "helper", frontmatter: null, body: "You help with everything, patiently." }] }));
-    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: ["sub-agent-name-defaulted"] });
-    expect(accepted(outcome).subAgents[0]).toMatchObject({ name: "helper", instructions: "You help with everything, patiently." });
-  });
-});
-
-describe("frontmatter fields", () => {
-  it("matches Claude skills: to the plugin's skills and warns on the rest", () => {
-    const outcome = read(
-      claudePlugin({
-        skills: [{ name: "known", description: "d" }],
-        agents: [{ file: "a", frontmatter: { skills: ["known", "unknown"] } }],
-      }),
-    );
-    expect(kindsOf(outcome).warnings).toEqual(["sub-agent-skill-unknown"]);
-    expect(accepted(outcome).subAgents[0]?.skillNames).toEqual(["known"]);
-  });
-
-  it("classifies model into an alias and warns on one it cannot map", () => {
-    const outcome = read(
-      cursorPlugin({
-        agents: [
-          { file: "fast", frontmatter: { model: "fast" } },
-          { file: "sonnet", frontmatter: { model: "claude-sonnet-4-5" } },
-          { file: "inherit", frontmatter: { model: "inherit" } },
-          { file: "grok", frontmatter: { model: "grok-4.6[effort=xhigh]" } },
-          { file: "none", frontmatter: {} },
-        ],
-      }),
-    );
-    expect(kindsOf(outcome).warnings).toEqual(["sub-agent-model-unknown"]);
-    const hints = accepted(outcome).subAgents.map((a) => [a.name, a.modelHint?.alias]);
-    expect(hints).toEqual([
-      ["fast", "fast"],
-      ["grok", "unknown"],
-      ["inherit", "inherit"],
-      ["none", undefined],
-      ["sonnet", "sonnet"],
-    ]);
-  });
-
-  it("warns once per field Stigmer does not read", () => {
-    const outcome = read(cursorPlugin({ agents: [{ file: "a", frontmatter: { readonly: true, is_background: false, effort: "high" } }] }));
-    expect(kindsOf(outcome).warnings).toEqual(["sub-agent-field-ignored", "sub-agent-field-ignored", "sub-agent-field-ignored"]);
-  });
-});
-
-describe("classifyModel", () => {
-  it("maps the dialects' spellings onto the alias set", () => {
-    expect(classifyModel("fast").alias).toBe("fast");
-    expect(classifyModel("Sonnet").alias).toBe("sonnet");
-    expect(classifyModel("claude-opus-4-1").alias).toBe("opus");
-    expect(classifyModel("claude-haiku-4.5").alias).toBe("haiku");
-    expect(classifyModel("inherit").alias).toBe("inherit");
-    expect(classifyModel("gpt-5").alias).toBe("unknown");
-    expect(classifyModel("gpt-5").raw).toBe("gpt-5");
-  });
-});

package/src/__tests__/variables.test.ts

@@ -1,94 +0,0 @@
-/**
- * Pins variable normalisation: Cursor variables are secrets with `required`
- * deciding `optional`, Claude `userConfig` carries `sensitive` and
- * `required`, titles and descriptions are joined, the unsupported Claude
- * attributes warn once each, an undeclared reference is declared as a
- * required secret with a warning naming the server, and a declared
- * variable no server uses is warned.
- */
-
-import { describe, expect, it } from "vitest";
-
-import { claudePlugin, cursorPlugin } from "../testing.js";
-import { accepted, findingOf, kindsOf, read } from "../__test-utils__/read.js";
-
-describe("Cursor variables", () => {
-  it("declares every property as a secret, optional unless required", () => {
-    const plugin = accepted(
-      read(
-        cursorPlugin({
-          variables: {
-            TOKEN: { type: "string", title: "Token", description: "A personal access token." },
-            REGION: { type: "string", title: "Region" },
-          },
-          required: ["TOKEN"],
-          mcpServers: { s: { type: "http", url: "https://x.example.com/mcp", headers: { A: "${TOKEN}", B: "${REGION}" } } },
-        }),
-      ),
-    );
-    expect(plugin.variables).toEqual([
-      { name: "TOKEN", description: "Token: A personal access token.", isSecret: true, optional: false, declaredBy: "cursor" },
-      { name: "REGION", description: "Region", isSecret: true, optional: true, declaredBy: "cursor" },
-    ]);
-  });
-});
-
-describe("Claude userConfig", () => {
-  it("carries sensitive and required, and warns once per unsupported attribute", () => {
-    const outcome = read(
-      claudePlugin({
-        userConfig: {
-          API_KEY: { type: "string", title: "API key", sensitive: true, required: true },
-          MODE: { type: "string", default: "fast", options: ["fast", "slow"] },
-          DIR: { type: "directory", description: "Where to write" },
-          COUNT: { type: "number", min: 1, max: 5, multiple: true },
-        },
-        mcpServers: {
-          s: { command: "npx", args: ["x", "${MODE}", "${DIR}", "${COUNT}"], env: { API_KEY: "${API_KEY}" } },
-        },
-      }),
-    );
-    expect(kindsOf(outcome).warnings).toEqual([
-      "variable-default-dropped",
-      "variable-option-dropped",
-      "variable-option-dropped",
-      "variable-option-dropped",
-      "variable-option-dropped",
-      "variable-type-narrowed",
-      "variable-type-narrowed",
-    ]);
-    expect(accepted(outcome).variables).toEqual([
-      { name: "API_KEY", description: "API key", isSecret: true, optional: false, declaredBy: "claude" },
-      { name: "MODE", isSecret: false, optional: true, declaredBy: "claude" },
-      { name: "DIR", description: "Where to write", isSecret: false, optional: true, declaredBy: "claude" },
-      { name: "COUNT", isSecret: false, optional: true, declaredBy: "claude" },
-    ]);
-  });
-});
-
-describe("reconciliation with references", () => {
-  it("declares an undeclared reference as a required secret and names the server", () => {
-    const outcome = read(cursorPlugin({ mcpServers: { gh: { type: "http", url: "https://api.example.com/mcp", headers: { Authorization: "Bearer ${GITHUB_TOKEN}" } } } }));
-    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: ["variable-inferred"] });
-    expect(findingOf(outcome.warnings, "variable-inferred")).toMatchObject({ subject: "GITHUB_TOKEN", detail: "gh" });
-    expect(accepted(outcome).variables).toEqual([{ name: "GITHUB_TOKEN", isSecret: true, optional: false, declaredBy: "inferred" }]);
-  });
-
-  it("warns on a declared variable no server references", () => {
-    const outcome = read(cursorPlugin({ variables: { UNUSED: { type: "string" } } }));
-    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: ["variable-unreferenced"] });
-    expect(accepted(outcome).variables[0]?.name).toBe("UNUSED");
-  });
-
-  it("lists declared variables first in declaration order, then inferred ones sorted", () => {
-    const plugin = accepted(
-      read(
-        cursorPlugin({
-          variables: { Z: { type: "string" }, A: { type: "string" } },
-          mcpServers: { s: { type: "http", url: "https://x.example.com/mcp", headers: { h: "${Z} ${A} ${M} ${B}" } } },
-        }),
-      ),
-    );
-    expect(plugin.variables.map((v) => v.name)).toEqual(["Z", "A", "B", "M"]);
-  });
-});