@stigmer/plugin-package 3.15.3-dev.20260916211208

package/src/__tests__/variables.test.ts

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

package/src/detect.ts

@@ -0,0 +1,189 @@
+/**
+ * Which manifests a package carries, which one gives it its identity, and
+ * what they agree on.
+ *
+ * A root `plugin.json` (the open format) is the identity when present, and
+ * any vendor manifests beside it contribute only their dialect data
+ * (declared paths, variables, inline servers). Without a root manifest the
+ * precedence is Claude, Cursor, Codex: the first present names the plugin.
+ * Every present manifest is read, so a plugin that ships two dialects has
+ * both honoured; a `name` present in two manifests with different values is
+ * refused, because a plugin that is two plugins depending on who reads it
+ * is exactly the drift Stigmer will not carry.
+ *
+ * The plugin name obeys the open format's rule in every dialect (1 to 64
+ * characters of `a-z 0-9 - .`, alphanumeric at both ends, no `--` or `..`);
+ * Cursor's published pattern is the same rule minus the repetition clause.
+ * Slugging is the installer's, not the reader's.
+ *
+ * MCP configuration sources are resolved here too, because a default
+ * location is a cross-manifest fact: `mcp.json` is read under the open
+ * rules when a root manifest exists; a Claude or Codex manifest that
+ * declares no `mcpServers` reads `.mcp.json` when present; Cursor reads
+ * only what it declares. Sub-agent files (`agents/*.md`) are a vendor
+ * component: they are read when any vendor manifest is present and recorded
+ * as ignored otherwise, since the open format defines no such component.
+ */
+
+import { readClaudeManifest, CLAUDE_DEFAULT_MCP_CONFIG } from "./dialects/claude.js";
+import { readCodexManifest } from "./dialects/codex.js";
+import { readCursorManifest } from "./dialects/cursor.js";
+import type { DialectManifest, McpConfigSource } from "./dialects/manifest.js";
+import { readOpenManifest } from "./dialects/open.js";
+import { type JsonObject, parseJsonObject, readText } from "./documents.js";
+import type { PluginFileIndex } from "./files.js";
+import { type Findings, MANIFEST_LOCATIONS } from "./messages.js";
+import type { PluginDialect } from "./types.js";
+
+/** The open format's `mcp.json`, a fixed location. */
+export const OPEN_MCP_CONFIG = "mcp.json";
+
+/** The vendor precedence when no root manifest exists. */
+const VENDOR_PRECEDENCE: readonly Exclude<PluginDialect, "agent-plugins">[] = ["claude", "cursor", "codex"];
+
+const NAME_MAX_LENGTH = 64;
+const NAME_PATTERN = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/;
+
+export interface ManifestSet {
+  /** The dialect that gave the plugin its identity. */
+  readonly dialect: PluginDialect;
+  /** Identity first, then the others in location order. */
+  readonly manifests: readonly DialectManifest[];
+  /** The validated plugin name; `undefined` after a name finding. */
+  readonly name: string | undefined;
+  /** True when a vendor manifest is present, so `agents/*.md` is a component. */
+  readonly readsAgents: boolean;
+  readonly mcpSources: readonly McpConfigSource[];
+}
+
+/** True when the directory holds any of the four manifests; the CLI's routing test. */
+export function hasPluginManifest(paths: Iterable<string>): boolean {
+  const locations = new Set<string>(Object.values(MANIFEST_LOCATIONS));
+  for (const path of paths) if (locations.has(path)) return true;
+  return false;
+}
+
+/** Read every present manifest; `undefined` (after `no-manifest`) when there is none. */
+export function detectManifests(index: PluginFileIndex, findings: Findings): ManifestSet | undefined {
+  const manifests: DialectManifest[] = [];
+  const present = (dialect: PluginDialect): DialectManifest | undefined => {
+    const path = MANIFEST_LOCATIONS[dialect];
+    if (!index.has(path)) return undefined;
+    const object = readManifestObject(index, path, findings);
+    // An unreadable manifest still counts as present: the finding already
+    // says why, and an empty contribution keeps the read going.
+    const manifest = object === undefined ? emptyManifest(dialect, path) : readDialect(dialect, object, path, findings);
+    manifests.push(manifest);
+    return manifest;
+  };
+
+  const root = present("agent-plugins");
+  const vendors = VENDOR_PRECEDENCE.map(present).filter((m): m is DialectManifest => m !== undefined);
+  if (manifests.length === 0) {
+    findings.error("no-manifest");
+    return undefined;
+  }
+
+  const identity = root ?? vendors[0];
+  if (identity === undefined) {
+    // Unreachable: manifests is non-empty, so root or vendors[0] exists.
+    throw new Error("manifest set without an identity manifest");
+  }
+  const ordered = [identity, ...manifests.filter((m) => m !== identity)];
+  const name = resolveName(identity, ordered, findings);
+
+  return {
+    dialect: identity.dialect,
+    manifests: ordered,
+    name,
+    readsAgents: vendors.length > 0,
+    mcpSources: resolveMcpSources(index, root, vendors),
+  };
+}
+
+function readManifestObject(index: PluginFileIndex, path: string, findings: Findings): JsonObject | undefined {
+  const text = readText(index, path, "manifest", findings);
+  return text === undefined ? undefined : parseJsonObject(text, path, "manifest-unreadable", findings);
+}
+
+function readDialect(dialect: PluginDialect, object: JsonObject, path: string, findings: Findings): DialectManifest {
+  switch (dialect) {
+    case "agent-plugins":
+      return readOpenManifest(object, path, findings);
+    case "claude":
+      return readClaudeManifest(object, path, findings);
+    case "cursor":
+      return readCursorManifest(object, path, findings);
+    case "codex":
+      return readCodexManifest(object, path, findings);
+    default: {
+      const exhaustive: never = dialect;
+      throw new Error(`unknown dialect ${String(exhaustive)}`);
+    }
+  }
+}
+
+function emptyManifest(dialect: PluginDialect, path: string): DialectManifest {
+  return { dialect, path, identity: {}, skillPaths: [], mcpConfigs: [], ignored: [] };
+}
+
+function resolveName(identity: DialectManifest, all: readonly DialectManifest[], findings: Findings): string | undefined {
+  const name = identity.identity.name;
+  if (name === undefined) {
+    // An unreadable identity manifest already reported itself; a second
+    // finding about its missing name would blame the author twice.
+    if (findings.errors.some((f) => f.kind === "manifest-unreadable" && f.path === identity.path)) return undefined;
+    findings.error("manifest-name-missing", { path: identity.path });
+    return undefined;
+  }
+  let valid = true;
+  if (!isValidPluginName(name)) {
+    findings.error("manifest-name-invalid", { path: identity.path, subject: name });
+    valid = false;
+  }
+  for (const other of all) {
+    if (other === identity) continue;
+    const otherName = other.identity.name;
+    if (otherName !== undefined && otherName !== name) {
+      findings.error("manifest-name-conflict", {
+        path: identity.path,
+        subject: name,
+        detail: `'${otherName}' in '${other.path}'`,
+      });
+      valid = false;
+    }
+  }
+  return valid ? name : undefined;
+}
+
+/** The open format's name rule, applied in every dialect. */
+export function isValidPluginName(name: string): boolean {
+  return name.length <= NAME_MAX_LENGTH && NAME_PATTERN.test(name) && !name.includes("--") && !name.includes("..");
+}
+
+function resolveMcpSources(
+  index: PluginFileIndex,
+  root: DialectManifest | undefined,
+  vendors: readonly DialectManifest[],
+): readonly McpConfigSource[] {
+  const sources: McpConfigSource[] = [];
+  if (root !== undefined && index.has(OPEN_MCP_CONFIG)) {
+    sources.push({ kind: "file", path: OPEN_MCP_CONFIG, dialect: "agent-plugins", manifest: root.path });
+  }
+  for (const vendor of vendors) {
+    if (vendor.mcpConfigs.length > 0) {
+      sources.push(...vendor.mcpConfigs);
+    } else if (vendor.dialect !== "cursor" && index.has(CLAUDE_DEFAULT_MCP_CONFIG)) {
+      sources.push({ kind: "file", path: CLAUDE_DEFAULT_MCP_CONFIG, dialect: vendor.dialect, manifest: vendor.path });
+    }
+  }
+  // Two manifests may name the same file (Claude and Codex both defaulting
+  // to `.mcp.json`); reading it twice would report every server twice.
+  const seen = new Set<string>();
+  return sources.filter((source) => {
+    if (source.kind === "inline") return true;
+    if (seen.has(source.path)) return false;
+    seen.add(source.path);
+    return true;
+  });
+}

package/src/dialects/claude.ts

@@ -0,0 +1,90 @@
+/**
+ * The Claude Code manifest (`.claude-plugin/plugin.json`), and the shape the
+ * Codex compatibility manifest shares with it.
+ *
+ * Claude's manifest is optional in its own tool (without one, the directory
+ * name is the plugin name) and `name` is its only required field. Path
+ * fields are a string or an array of strings, `./`-prefixed: `skills` ADDS
+ * to the default `skills/` scan and may name a directory that is itself a
+ * skill; `agents` REPLACES the default `agents/` and its entries are files
+ * or directories. `mcpServers` is a path, an inline object, or an array of
+ * either, defaulting to `.mcp.json` at the plugin root. `userConfig`
+ * declares the variables a user is prompted for. Hooks, LSP servers,
+ * channels, output styles, workflows and the experimental components are
+ * recorded as ignored.
+ *
+ * The reader is exported with its known-field set so the Codex dialect,
+ * whose legacy manifest is this shape plus `apps` and `interface`, reuses it
+ * rather than restating it.
+ */
+
+import type { JsonObject } from "../documents.js";
+import type { Findings } from "../messages.js";
+import type { PluginDialect } from "../types.js";
+import {
+  type DialectManifest,
+  ignoredFieldComponents,
+  readDeclaredPaths,
+  readIdentity,
+  readMcpSources,
+  warnUnknownFields,
+} from "./manifest.js";
+
+export const CLAUDE_KNOWN_FIELDS: ReadonlySet<string> = new Set([
+  "name",
+  "version",
+  "description",
+  "author",
+  "homepage",
+  "repository",
+  "license",
+  "keywords",
+  "skills",
+  "commands",
+  "agents",
+  "workflows",
+  "hooks",
+  "mcpServers",
+  "outputStyles",
+  "lspServers",
+  "experimental",
+  "userConfig",
+  "channels",
+  "dependencies",
+  "defaultEnabled",
+]);
+
+/** The default MCP configuration file when the manifest declares none. */
+export const CLAUDE_DEFAULT_MCP_CONFIG = ".mcp.json";
+
+export function readClaudeManifest(object: JsonObject, path: string, findings: Findings): DialectManifest {
+  return readClaudeShapedManifest(object, path, "claude", CLAUDE_KNOWN_FIELDS, findings);
+}
+
+/** The Claude shape under a given dialect and known-field set (Codex reuses it). */
+export function readClaudeShapedManifest(
+  object: JsonObject,
+  path: string,
+  dialect: PluginDialect,
+  known: ReadonlySet<string>,
+  findings: Findings,
+): DialectManifest {
+  warnUnknownFields(object, known, path, findings);
+  const identity = readIdentity(object, path, findings);
+  const skillPaths = readDeclaredPaths(object, "skills", path, findings) ?? [];
+  const agentPaths = readDeclaredPaths(object, "agents", path, findings);
+  const declaredMcp = readMcpSources(object, "mcpServers", path, dialect, findings);
+  const manifest: { -readonly [K in keyof DialectManifest]: DialectManifest[K] } = {
+    dialect,
+    path,
+    identity,
+    skillPaths,
+    mcpConfigs: declaredMcp,
+    ignored: ignoredFieldComponents(object, path),
+  };
+  if (agentPaths !== undefined) manifest.agentPaths = agentPaths;
+  if (object["userConfig"] !== undefined) {
+    manifest.variables = { dialect: "claude", value: object["userConfig"], manifest: path };
+  }
+  return manifest;
+}

package/src/dialects/codex.ts

@@ -0,0 +1,24 @@
+/**
+ * The Codex compatibility manifest (`.codex-plugin/plugin.json`).
+ *
+ * New Codex packages are the open form: a root `plugin.json` with
+ * OpenAI-specific presentation, app mappings and hooks under
+ * `extensions["com.openai"]`, which the open reader records as an ignored
+ * extension. The legacy `.codex-plugin/plugin.json` that Codex still
+ * accepts is the Claude shape (`skills`, `mcpServers`, hooks) plus two
+ * fields of its own: `apps` (registered ChatGPT app mappings, `.app.json`)
+ * and `interface` (marketplace presentation). Nothing Codex-specific maps
+ * to a Stigmer resource, so the reader is the Claude reader under the
+ * `codex` dialect with the two extra fields known and `apps` ignored.
+ */
+
+import type { JsonObject } from "../documents.js";
+import type { Findings } from "../messages.js";
+import { CLAUDE_KNOWN_FIELDS, readClaudeShapedManifest } from "./claude.js";
+import type { DialectManifest } from "./manifest.js";
+
+const KNOWN_FIELDS: ReadonlySet<string> = new Set([...CLAUDE_KNOWN_FIELDS, "apps", "interface"]);
+
+export function readCodexManifest(object: JsonObject, path: string, findings: Findings): DialectManifest {
+  return readClaudeShapedManifest(object, path, "codex", KNOWN_FIELDS, findings);
+}

package/src/dialects/cursor.ts

@@ -0,0 +1,73 @@
+/**
+ * The Cursor manifest (`.cursor-plugin/plugin.json`).
+ *
+ * Cursor publishes a draft-07 schema for this file (`additionalProperties:
+ * false`, only `name` required); the known-field set below is that schema's
+ * key list, and `author` there carries `name` and `email` only. Component
+ * fields `skills`, `agents`, `rules`, `commands` are a path or an array of
+ * paths (the schema says "glob pattern(s) or path(s)"; every published
+ * plugin uses a `./`-prefixed directory, and a glob is refused rather than
+ * expanded). `mcpServers` is a path, an inline object, or an array of
+ * either. `variables` is a JSON Schema object whose `properties` are the
+ * variables a user is prompted for and whose `required` list marks the
+ * mandatory ones; Cursor has no sensitivity flag, so Stigmer treats every
+ * Cursor variable as a secret. `rules`, `commands`, `hooks`, `logo` and
+ * `minClientVersions` are recorded as ignored; `displayName`, `publisher`,
+ * `category` and `tags` are marketplace metadata Stigmer neither carries
+ * nor warns about.
+ */
+
+import type { JsonObject } from "../documents.js";
+import type { Findings } from "../messages.js";
+import {
+  type DialectManifest,
+  ignoredFieldComponents,
+  readDeclaredPaths,
+  readIdentity,
+  readMcpSources,
+  warnUnknownFields,
+} from "./manifest.js";
+
+const KNOWN_FIELDS: ReadonlySet<string> = new Set([
+  "name",
+  "displayName",
+  "description",
+  "version",
+  "minClientVersions",
+  "author",
+  "publisher",
+  "homepage",
+  "repository",
+  "license",
+  "logo",
+  "keywords",
+  "category",
+  "tags",
+  "commands",
+  "agents",
+  "skills",
+  "rules",
+  "hooks",
+  "variables",
+  "mcpServers",
+]);
+
+export function readCursorManifest(object: JsonObject, path: string, findings: Findings): DialectManifest {
+  warnUnknownFields(object, KNOWN_FIELDS, path, findings);
+  const identity = readIdentity(object, path, findings);
+  const skillPaths = readDeclaredPaths(object, "skills", path, findings) ?? [];
+  const agentPaths = readDeclaredPaths(object, "agents", path, findings);
+  const manifest: { -readonly [K in keyof DialectManifest]: DialectManifest[K] } = {
+    dialect: "cursor",
+    path,
+    identity,
+    skillPaths,
+    mcpConfigs: readMcpSources(object, "mcpServers", path, "cursor", findings),
+    ignored: ignoredFieldComponents(object, path),
+  };
+  if (agentPaths !== undefined) manifest.agentPaths = agentPaths;
+  if (object["variables"] !== undefined) {
+    manifest.variables = { dialect: "cursor", value: object["variables"], manifest: path };
+  }
+  return manifest;
+}