@stigmer/plugin-package 3.15.3-dev.20260916211208

package/src/__tests__/fixtures.test.ts

@@ -0,0 +1,198 @@
+/**
+ * The fixture suite: six real Cursor plugins, vendored from cursor/plugins
+ * at c1c0a32 (see fixtures/cursor-plugins/NOTICE), read exactly as a user's
+ * checkout would be. Every assertion names the field it pins; there are no
+ * snapshot files, so a change in what the reader produces is a change
+ * someone wrote down here.
+ *
+ * Between them the six cover: Cursor `variables` with `required` (github,
+ * xero, salesforce), a `${VAR}` inside a header (github), stdio `env` as
+ * `KEY: "${KEY}"` (xero), an entry with no `type` inferred to stdio
+ * (playwright), a `${VAR}` url plus the undocumented `auth` block
+ * (salesforce, the one refusal), two sub-agents and no server (thermos), a
+ * sub-agent with an unmappable model and a `readonly` field plus hooks that
+ * reference `${CURSOR_PLUGIN_ROOT}` and must never be read (advisor), skill
+ * frontmatter with vendor keys, `minClientVersions`, a `references/` file
+ * inside a skill, and image assets that are listed and never opened.
+ */
+
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { readPluginPackage } from "../read-plugin-package.js";
+import { directoryPluginFiles } from "../__test-utils__/directory-files.js";
+import { accepted, findingOf, kindsOf, refused } from "../__test-utils__/read.js";
+
+const FIXTURES = fileURLToPath(new URL("./fixtures/cursor-plugins/", import.meta.url));
+
+function readFixture(name: string) {
+  return readPluginPackage(directoryPluginFiles(`${FIXTURES}${name}`));
+}
+
+describe("thermos: skills and sub-agents, no server", () => {
+  const outcome = readFixture("thermos");
+
+  it("is accepted with no warnings", () => {
+    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: [] });
+  });
+
+  it("carries the manifest identity", () => {
+    const plugin = accepted(outcome);
+    expect(plugin).toMatchObject({
+      name: "thermos",
+      version: "1.0.0",
+      license: "MIT",
+      dialect: "cursor",
+      manifestsFound: [".cursor-plugin/plugin.json"],
+      author: { name: "Cursor", email: "plugins@cursor.com" },
+      homepage: "https://github.com/cursor/plugins",
+    });
+    expect(plugin.keywords).toContain("thermo-nuclear");
+  });
+
+  it("reads the three skills with their descriptions and files", () => {
+    const plugin = accepted(outcome);
+    expect(plugin.skills.map((s) => s.name)).toEqual(["thermo-nuclear-code-quality-review", "thermo-nuclear-review", "thermos"]);
+    expect(plugin.skills[2]?.description).toMatch(/^Launch both thermo-nuclear review subagents/);
+    expect(plugin.skills[2]?.files).toEqual(["skills/thermos/SKILL.md"]);
+  });
+
+  it("reads the two sub-agents with the file body as instructions and no model hint", () => {
+    const plugin = accepted(outcome);
+    expect(plugin.subAgents.map((a) => a.name)).toEqual(["thermo-nuclear-code-quality-review-subagent", "thermo-nuclear-review-subagent"]);
+    const review = plugin.subAgents[1];
+    expect(review?.description).toMatch(/^Thermo-nuclear branch audit/);
+    expect(review?.instructions.length).toBeGreaterThan(1000);
+    expect(review?.modelHint).toBeUndefined();
+    expect(review?.path).toBe("agents/thermo-nuclear-review-subagent.md");
+  });
+
+  it("has no servers and no variables, and records only the logo", () => {
+    const plugin = accepted(outcome);
+    expect(plugin.mcpServers).toEqual([]);
+    expect(plugin.variables).toEqual([]);
+    expect(plugin.ignored).toEqual([
+      { kind: "assets", path: "assets/" },
+      { kind: "logo", path: ".cursor-plugin/plugin.json#logo" },
+    ]);
+  });
+});
+
+describe("github: an HTTP server with a token in a header", () => {
+  const outcome = readFixture("github");
+
+  it("is accepted with no warnings", () => {
+    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: [] });
+  });
+
+  it("reads the server with the header reference on its env", () => {
+    expect(accepted(outcome).mcpServers).toEqual([
+      {
+        name: "github",
+        transport: "http",
+        url: "https://api.githubcopilot.com/mcp/",
+        headers: { Authorization: "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}" },
+        env: ["GITHUB_PERSONAL_ACCESS_TOKEN"],
+      },
+    ]);
+  });
+
+  it("declares the required variable as a secret with the joined title and description", () => {
+    expect(accepted(outcome).variables).toEqual([
+      {
+        name: "GITHUB_PERSONAL_ACCESS_TOKEN",
+        description:
+          "GitHub personal access token: Fine-grained or classic PAT from https://github.com/settings/tokens with the repo scopes you want the agent to use.",
+        isSecret: true,
+        optional: false,
+        declaredBy: "cursor",
+      },
+    ]);
+  });
+
+  it("records minClientVersions and the logo as ignored", () => {
+    expect(accepted(outcome).ignored.map((c) => c.kind).sort()).toEqual(["assets", "logo", "min-client-versions"]);
+  });
+});
+
+describe("xero: a stdio server passing two secrets by name", () => {
+  const outcome = readFixture("xero");
+
+  it("is accepted with no warnings", () => {
+    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: [] });
+  });
+
+  it("reads the npx command with its args and both env references", () => {
+    expect(accepted(outcome).mcpServers).toEqual([
+      {
+        name: "xero",
+        transport: "stdio",
+        command: "npx",
+        args: ["-y", "@xeroapi/xero-mcp-server@latest"],
+        env: ["XERO_CLIENT_ID", "XERO_CLIENT_SECRET"],
+      },
+    ]);
+  });
+
+  it("declares both variables as required secrets", () => {
+    expect(accepted(outcome).variables.map((v) => [v.name, v.isSecret, v.optional])).toEqual([
+      ["XERO_CLIENT_ID", true, false],
+      ["XERO_CLIENT_SECRET", true, false],
+    ]);
+  });
+});
+
+describe("playwright: a server with no type and no variables", () => {
+  const outcome = readFixture("playwright");
+
+  it("is accepted with no warnings and infers stdio from command", () => {
+    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: [] });
+    expect(accepted(outcome).mcpServers).toEqual([
+      { name: "playwright", transport: "stdio", command: "npx", args: ["-y", "@playwright/mcp@latest"], env: [] },
+    ]);
+    expect(accepted(outcome).variables).toEqual([]);
+  });
+});
+
+describe("salesforce: a variable in the url is refused", () => {
+  const outcome = readFixture("salesforce");
+
+  it("is refused for the url alone, with the auth block warned", () => {
+    expect(kindsOf(outcome)).toEqual({ errors: ["mcp-server-url-variable"], warnings: ["mcp-server-auth-ignored"] });
+    expect(findingOf(refused(outcome), "mcp-server-url-variable").message).toBe(
+      "MCP server 'salesforce' in 'mcp.json' has a variable in its 'url'; Stigmer sends the URL as written, so write the URL out and put variables in 'headers'",
+    );
+  });
+});
+
+describe("advisor: a sub-agent with an unmappable model, and hooks that are never read", () => {
+  const outcome = readFixture("advisor");
+
+  it("is accepted with the model and the readonly field warned", () => {
+    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: ["sub-agent-field-ignored", "sub-agent-model-unknown"] });
+    expect(findingOf(outcome.warnings, "sub-agent-model-unknown")).toMatchObject({ subject: "advisor-subagent", detail: "grok-4.6[effort=xhigh]" });
+    expect(findingOf(outcome.warnings, "sub-agent-field-ignored")).toMatchObject({ subject: "advisor-subagent", detail: "readonly" });
+  });
+
+  it("keeps the raw model text in the hint", () => {
+    expect(accepted(outcome).subAgents[0]?.modelHint).toEqual({ raw: "grok-4.6[effort=xhigh]", alias: "unknown" });
+  });
+
+  it("reads the skill with its references file and vendor frontmatter keys", () => {
+    const skill = accepted(outcome).skills[0];
+    expect(skill?.name).toBe("advisor");
+    expect(skill?.files).toEqual(["skills/advisor/SKILL.md", "skills/advisor/references/briefing-template.md"]);
+  });
+
+  it("records hooks as ignored without reading the ${CURSOR_PLUGIN_ROOT} inside them", () => {
+    const plugin = accepted(outcome);
+    expect(plugin.ignored).toEqual([
+      { kind: "assets", path: "assets/" },
+      { kind: "hooks", path: "hooks/" },
+      { kind: "logo", path: ".cursor-plugin/plugin.json#logo" },
+      { kind: "hooks", path: ".cursor-plugin/plugin.json#hooks" },
+    ]);
+    expect(plugin.mcpServers).toEqual([]);
+  });
+});

package/src/__tests__/mcp-servers.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Pins the MCP server normalisation on its accepting paths: the two
+ * transports in both the open and the vendor dialects, transport inference,
+ * `sse` mapped with its warning, the `${user_config.KEY}` rewrite, header
+ * and argument references collected onto `env`, the Cursor `auth` block
+ * warned and scanned, inline and multiple sources, and the URL rule's
+ * loopback exception. Refusals are pinned kind by kind in the adversarial
+ * suite.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { claudePlugin, cursorPlugin, openPlugin } from "../testing.js";
+import { accepted, findingOf, kindsOf, read } from "../__test-utils__/read.js";
+
+describe("open dialect", () => {
+  it("reads a stdio and a streamable-http server into the two spec shapes", () => {
+    const plugin = accepted(
+      read(
+        openPlugin({
+          mcpServers: {
+            files: { type: "stdio", command: "npx", args: ["-y", "@acme/files", "--token", "${TOKEN}"], env: { TOKEN: "${TOKEN}" } },
+            api: { type: "streamable-http", url: "https://api.example.com/mcp", headers: { Authorization: "Bearer ${API_KEY}", "X-Org": "acme" } },
+          },
+        }),
+      ),
+    );
+    expect(plugin.mcpServers).toEqual([
+      { name: "files", transport: "stdio", command: "npx", args: ["-y", "@acme/files", "--token", "${TOKEN}"], env: ["TOKEN"] },
+      { name: "api", transport: "http", url: "https://api.example.com/mcp", headers: { Authorization: "Bearer ${API_KEY}", "X-Org": "acme" }, env: ["API_KEY"] },
+    ]);
+  });
+
+  it("maps the legacy sse transport to http with the fallback warning", () => {
+    const outcome = read(openPlugin({ mcpServers: { legacy: { type: "sse", url: "https://legacy.example.com/sse" } } }));
+    expect(kindsOf(outcome).warnings).toEqual(["mcp-server-sse-mapped"]);
+    expect(accepted(outcome).mcpServers[0]).toMatchObject({ transport: "http", url: "https://legacy.example.com/sse" });
+    expect(findingOf(outcome.warnings, "mcp-server-sse-mapped").message).toContain("falls back to SSE only when the server rejects it");
+  });
+
+  it("allows plain http for loopback hosts only", () => {
+    const outcome = read(openPlugin({ mcpServers: { local: { type: "streamable-http", url: "http://localhost:8080/mcp" }, ip: { type: "streamable-http", url: "http://127.0.0.1/mcp" } } }));
+    expect(accepted(outcome).mcpServers).toHaveLength(2);
+  });
+});
+
+describe("vendor dialects", () => {
+  it("infers the transport from command or url when type is absent", () => {
+    const plugin = accepted(
+      read(
+        cursorPlugin({
+          mcpServers: {
+            play: { command: "npx", args: ["-y", "@playwright/mcp@latest"] },
+            web: { url: "https://mcp.example.com/" },
+            explicit: { type: "http", url: "https://mcp.example.com/two" },
+          },
+        }),
+      ),
+    );
+    expect(plugin.mcpServers.map((s) => [s.name, s.transport])).toEqual([
+      ["play", "stdio"],
+      ["web", "http"],
+      ["explicit", "http"],
+    ]);
+  });
+
+  it("rewrites Claude's ${user_config.KEY} to ${KEY} in headers, args and env", () => {
+    const plugin = accepted(
+      read(
+        claudePlugin({
+          userConfig: { API_KEY: { type: "string", sensitive: true, required: true }, DB: { type: "string" } },
+          mcpServers: {
+            api: { url: "https://api.example.com/mcp", headers: { Authorization: "Bearer ${user_config.API_KEY}" } },
+            db: { command: "uvx", args: ["db-mcp", "--name", "${user_config.DB}"], env: { DB: "${user_config.DB}" } },
+          },
+        }),
+      ),
+    );
+    expect(plugin.mcpServers[0]).toMatchObject({ headers: { Authorization: "Bearer ${API_KEY}" }, env: ["API_KEY"] });
+    expect(plugin.mcpServers[1]).toMatchObject({ args: ["db-mcp", "--name", "${DB}"], env: ["DB"] });
+  });
+
+  it("warns on Cursor's auth block and still counts the variables inside it as references", () => {
+    const outcome = read(
+      cursorPlugin({
+        variables: { CLIENT_ID: { type: "string" } },
+        required: ["CLIENT_ID"],
+        mcpServers: { crm: { type: "http", url: "https://crm.example.com/mcp", auth: { CLIENT_ID: "${CLIENT_ID}", scopes: ["a"] } } },
+      }),
+    );
+    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: ["mcp-server-auth-ignored"] });
+    expect(accepted(outcome).mcpServers[0]?.env).toEqual(["CLIENT_ID"]);
+    expect(findingOf(outcome.warnings, "mcp-server-auth-ignored").message).toContain("ai.stigmer/mcp-servers/crm.yaml");
+  });
+
+  it("warns on a field Stigmer does not read instead of refusing", () => {
+    const outcome = read(cursorPlugin({ mcpServers: { s: { type: "http", url: "https://x.example.com/mcp", timeout: 30 } } }));
+    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: ["mcp-server-field-ignored"] });
+  });
+
+  it("reads an inline mcpServers object and a declared file together", () => {
+    const files = cursorPlugin({ mcpServers: { fromFile: { type: "http", url: "https://a.example.com/mcp" } } });
+    const manifest = JSON.parse(files.get(".cursor-plugin/plugin.json") as string) as Record<string, unknown>;
+    manifest["mcpServers"] = ["./mcp.json", { mcpServers: { inline: { type: "http", url: "https://b.example.com/mcp" } } }];
+    files.set(".cursor-plugin/plugin.json", JSON.stringify(manifest));
+    const plugin = accepted(read(files));
+    expect(plugin.mcpServers.map((s) => s.name)).toEqual(["fromFile", "inline"]);
+  });
+
+  it("reads Claude's default .mcp.json when the manifest declares no mcpServers", () => {
+    const plugin = accepted(read(claudePlugin({ mcpServers: { s: { command: "npx", args: ["x"] } } })));
+    expect(plugin.mcpServers.map((s) => s.name)).toEqual(["s"]);
+  });
+
+  it("warns on a top-level .mcp.json field it does not read, where the open format would refuse", () => {
+    const files = claudePlugin({ mcpServers: { s: { command: "npx" } } });
+    files.set(".mcp.json", JSON.stringify({ mcpServers: { s: { command: "npx" } }, comment: "x" }));
+    expect(kindsOf(read(files))).toEqual({ errors: [], warnings: ["mcp-config-field-ignored"] });
+  });
+});

package/src/__tests__/overlay-and-ignored.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Pins the `ai.stigmer/` overlay (the three document shapes located and
+ * handed over as bytes with the server check) and the ignored-component
+ * record (directories and files on disk, manifest fields, deduplicated,
+ * never per file, with hook scripts never read).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { cursorPlugin, openPlugin } from "../testing.js";
+import { accepted, kindsOf, read } from "../__test-utils__/read.js";
+
+describe("the ai.stigmer/ overlay", () => {
+  it("locates the agent, workflow and server documents and hands them over as bytes", () => {
+    const files = openPlugin({
+      mcpServers: { gh: { type: "streamable-http", url: "https://gh.example.com/mcp" } },
+      files: {
+        "ai.stigmer/agent.yaml": "kind: Agent\n",
+        "ai.stigmer/workflows/triage.yaml": "kind: Workflow\n",
+        "ai.stigmer/mcp-servers/gh.yaml": "spec:\n  auth: {}\n",
+      },
+    });
+    const overlay = accepted(read(files)).overlay;
+    expect(overlay.agent?.path).toBe("ai.stigmer/agent.yaml");
+    expect(new TextDecoder().decode(overlay.agent?.bytes)).toBe("kind: Agent\n");
+    expect(overlay.workflows.map((w) => [w.name, w.path])).toEqual([["triage", "ai.stigmer/workflows/triage.yaml"]]);
+    expect(overlay.mcpServers.map((s) => [s.server, s.path])).toEqual([["gh", "ai.stigmer/mcp-servers/gh.yaml"]]);
+  });
+
+  it("is empty when the folder is absent", () => {
+    expect(accepted(read(openPlugin())).overlay).toEqual({ workflows: [], mcpServers: [] });
+  });
+});
+
+describe("ignored components", () => {
+  it("records each component directory and file once, and never reads inside them", () => {
+    const files = cursorPlugin({
+      manifest: { hooks: "./hooks/hooks.json", rules: "./rules/", logo: "assets/logo.png", minClientVersions: { cursor: "3.13.0" } },
+      files: {
+        "hooks/hooks.json": '{"hooks":{"stop":[{"command":"bash \\"${CURSOR_PLUGIN_ROOT}/hooks/stop.sh\\""}]}}',
+        "hooks/stop.sh": "exit 0",
+        "rules/one.mdc": "rule",
+        "rules/two.mdc": "rule",
+        "assets/logo.png": new Uint8Array([0x89, 0x50]),
+        ".lsp.json": "{}",
+        "settings.json": "{}",
+        "README.md": "readme",
+        "LICENSE": "MIT",
+      },
+    });
+    const outcome = read(files);
+    expect(kindsOf(outcome)).toEqual({ errors: [], warnings: [] });
+    expect(accepted(outcome).ignored).toEqual([
+      { kind: "assets", path: "assets/" },
+      { kind: "hooks", path: "hooks/" },
+      { kind: "rules", path: "rules/" },
+      { kind: "lsp-servers", path: ".lsp.json" },
+      { kind: "settings", path: "settings.json" },
+      { kind: "hooks", path: ".cursor-plugin/plugin.json#hooks" },
+      { kind: "rules", path: ".cursor-plugin/plugin.json#rules" },
+      { kind: "logo", path: ".cursor-plugin/plugin.json#logo" },
+      { kind: "min-client-versions", path: ".cursor-plugin/plugin.json#minClientVersions" },
+    ]);
+  });
+});

package/src/__tests__/skills.test.ts

@@ -0,0 +1,89 @@
+/**
+ * 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

@@ -0,0 +1,111 @@
+/**
+ * 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");
+  });
+});