@cursor/july 0.1.101 → 0.1.103

package/src/internal/discovery/cursor-plugin.ts

@@ -0,0 +1,705 @@
+/**
+ * A Cursor plugin directory read as an extension tree: skills, commands, agents, and MCP servers under the plugin's own names.
+ */
+
+import { readFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join } from "node:path";
+import { z } from "zod";
+import type {
+  ConnectionTransport,
+  DiscoveredConnection,
+  DiscoveredSkill,
+} from "../../types.js";
+import { parseYamlFrontmatter } from "../frontmatter.js";
+import { isRecord } from "../is-record.js";
+import {
+  type DiscoveryContext,
+  displayPath,
+  errorMessage,
+  isBlank,
+} from "./context.js";
+import { isDirectory, isFile, sortedEntries, walkFiles } from "./fs.js";
+import { skillDescription, skillFiles } from "./skills.js";
+
+/** One `agents/*.md` file: a subagent the plugin ships. */
+export interface CursorPluginAgent {
+  name: string;
+  description?: string;
+  /** Model id; absent inherits the parent agent's model. */
+  model?: string;
+  prompt: string;
+}
+
+/** What a plugin contributes, under its own (unprefixed) names. */
+export interface CursorPluginTree {
+  description?: string;
+  /** `skills/` and `commands/`; a command is a user-invoked skill. */
+  skills: DiscoveredSkill[];
+  connections: DiscoveredConnection[];
+  /** Servers the plugin declares that the mount overlays; left uncompiled. */
+  overlaidServers: string[];
+  agents: CursorPluginAgent[];
+}
+
+/** The plugin directory being read. */
+interface PluginDir {
+  ctx: DiscoveryContext;
+  root: string;
+  manifestPath: string;
+  variables: Record<string, string>;
+}
+
+type JsonRecord = Record<string, unknown>;
+
+/** First match wins, as in Cursor. */
+const MANIFEST_PATHS = [
+  ".cursor-plugin/plugin.json",
+  ".claude-plugin/plugin.json",
+  "plugin.json",
+];
+/** Probed in order; the first file to name a server defines it. */
+const MCP_CONFIG_FILES = [".mcp.json", "mcp.json"];
+const MARKDOWN_EXTENSIONS = new Set([".md", ".mdc", ".markdown"]);
+const COMMAND_EXTENSIONS = new Set([...MARKDOWN_EXTENSIONS, ".txt"]);
+/** `${NAME}`, `${NAME:-default}`, and the user-mcp.json spelling `${env:NAME}`. */
+const PLACEHOLDER =
+  /\$\{(?:env:([A-Za-z_][A-Za-z0-9_]*)|([^:}]+)(?::-([^}]*))?)\}/g;
+const PLUGIN_ROOT_VARIABLES = new Set([
+  "CURSOR_PLUGIN_ROOT",
+  "CLAUDE_PLUGIN_ROOT",
+]);
+
+/** A component slot's declaration: one directory or a list of paths. */
+const pathsSchema = z
+  .union([z.string(), z.array(z.string())])
+  .transform((value) => (typeof value === "string" ? [value] : value));
+
+/** A blank or null value reads as absent, as a missing key would. */
+const text = z
+  .string()
+  .nullish()
+  .transform((value) =>
+    value === undefined || value === null || value.trim() === ""
+      ? undefined
+      : value
+  );
+
+const manifestSchema = z.object({
+  description: text.optional(),
+  skills: pathsSchema.optional(),
+  commands: pathsSchema.optional(),
+  agents: pathsSchema.optional(),
+  rules: z.unknown().optional(),
+  hooks: z.unknown().optional(),
+  mcpServers: z
+    .union([
+      z.string(),
+      z.record(z.unknown()),
+      z.array(z.union([z.string(), z.record(z.unknown())])),
+    ])
+    .optional()
+    .transform((value) => {
+      const items =
+        value === undefined || Array.isArray(value) ? (value ?? []) : [value];
+      return {
+        paths: items.filter((item) => typeof item === "string"),
+        inline: items.filter((item) => typeof item !== "string"),
+      };
+    }),
+});
+
+type Manifest = z.infer<typeof manifestSchema>;
+type McpServers = Manifest["mcpServers"];
+
+const frontmatterSchema = z.object({
+  name: text.optional(),
+  description: text.optional(),
+  model: text.optional(),
+});
+
+type Frontmatter = z.infer<typeof frontmatterSchema>;
+
+/** One `mcpServers` entry after placeholder expansion. */
+const mcpServerSchema = z.object({
+  type: z.string().optional(),
+  url: z.string().optional(),
+  headers: z.record(z.string()).optional(),
+  command: z.string().optional(),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string()).optional(),
+  cwd: z.string().optional(),
+  envFile: z.string().optional(),
+  /** Cursor's static OAuth client hint. */
+  auth: z.record(z.unknown()).optional(),
+  /** Claude's spelling of the same hint. */
+  oauth: z.record(z.unknown()).optional(),
+  /** Cursor disables unlisted tools; an empty list would disable them all. */
+  enabledTools: z.array(z.string()).nonempty().optional(),
+});
+
+type McpServer = z.infer<typeof mcpServerSchema>;
+
+export async function readCursorPlugin(
+  ctx: DiscoveryContext,
+  root: string,
+  mountPath: string,
+  variables: Record<string, string>,
+  overlaid: ReadonlySet<string>
+): Promise<CursorPluginTree | undefined> {
+  const manifest = await readManifest(ctx, root, mountPath);
+  if (manifest === undefined) {
+    return undefined;
+  }
+  const plugin: PluginDir = {
+    ctx,
+    root,
+    manifestPath: manifest.path,
+    variables,
+  };
+  const skills = await loadPluginSkills(plugin, manifest.data.skills);
+  for (const command of await loadPluginCommands(
+    plugin,
+    manifest.data.commands
+  )) {
+    if (skills.some((skill) => skill.name === command.name)) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, root),
+        message: `Plugin command "${command.name}" has the same name as a skill; the skill wins. Ignoring the command.`,
+      });
+      continue;
+    }
+    skills.push(command);
+  }
+  await warnUnmountedSlots(plugin, manifest.data);
+  return {
+    description: manifest.data.description,
+    skills,
+    ...(await loadPluginConnections(
+      plugin,
+      manifest.data.mcpServers,
+      overlaid
+    )),
+    agents: await loadPluginAgents(plugin, manifest.data.agents),
+  };
+}
+
+async function readManifest(
+  ctx: DiscoveryContext,
+  root: string,
+  mountPath: string
+): Promise<{ data: Manifest; path: string } | undefined> {
+  for (const rel of MANIFEST_PATHS) {
+    const path = join(root, rel);
+    if (!(await isFile(path))) {
+      continue;
+    }
+    const data = await readJson(ctx, path);
+    if (data === undefined) {
+      return undefined;
+    }
+    const parsed = manifestSchema.safeParse(data);
+    if (parsed.success) {
+      return { data: parsed.data, path };
+    }
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message: `The plugin manifest is malformed: ${firstIssue(parsed.error)}.`,
+    });
+    return undefined;
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, mountPath),
+    message: `${displayPath(ctx, root)} is not a Cursor plugin: it has no ${MANIFEST_PATHS.join(", ")}.`,
+  });
+  return undefined;
+}
+
+/** Slots Cursor applies through the IDE that have no agent-sdk mapping yet. */
+async function warnUnmountedSlots(
+  plugin: PluginDir,
+  manifest: Manifest
+): Promise<void> {
+  const unmounted: string[] = [];
+  if (
+    manifest.rules !== undefined ||
+    (await isDirectory(join(plugin.root, "rules")))
+  ) {
+    unmounted.push("rules");
+  }
+  if (
+    manifest.hooks !== undefined ||
+    (await isFile(join(plugin.root, "hooks", "hooks.json")))
+  ) {
+    unmounted.push("hooks");
+  }
+  if (unmounted.length === 0) {
+    return;
+  }
+  plugin.ctx.diagnostics.push({
+    severity: "warning",
+    path: displayPath(plugin.ctx, plugin.root),
+    message: `Cursor plugin ${unmounted.join(" and ")} are not mounted yet; skills, commands, agents, and MCP servers are. Ignoring.`,
+  });
+}
+
+async function loadPluginSkills(
+  plugin: PluginDir,
+  declared: string[] | undefined
+): Promise<DiscoveredSkill[]> {
+  const dirs: string[] = [];
+  if (declared === undefined) {
+    if (await isFile(join(plugin.root, "SKILL.md"))) {
+      dirs.push(plugin.root);
+    }
+    dirs.push(...(await skillDirsIn(join(plugin.root, "skills"))));
+  }
+  for (const path of declaredPaths(plugin, declared ?? [])) {
+    if (basename(path) === "SKILL.md" && (await isFile(path))) {
+      dirs.push(dirname(path));
+    } else if (await isFile(join(path, "SKILL.md"))) {
+      dirs.push(path);
+    } else {
+      dirs.push(...(await skillDirsIn(path)));
+    }
+  }
+  const skills: DiscoveredSkill[] = [];
+  for (const dir of dirs) {
+    const skill = await readSkillDir(plugin, dir);
+    if (skill !== undefined && !skills.some((s) => s.name === skill.name)) {
+      skills.push(skill);
+    }
+  }
+  return skills;
+}
+
+/** Immediate subdirectories holding a SKILL.md. */
+async function skillDirsIn(dir: string): Promise<string[]> {
+  if (!(await isDirectory(dir))) {
+    return [];
+  }
+  const dirs: string[] = [];
+  for (const entry of await sortedEntries(dir)) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory() && (await isFile(join(path, "SKILL.md")))) {
+      dirs.push(path);
+    }
+  }
+  return dirs;
+}
+
+async function readSkillDir(
+  plugin: PluginDir,
+  dir: string
+): Promise<DiscoveredSkill | undefined> {
+  const skillMdPath = join(dir, "SKILL.md");
+  const { data, body } = await readMarkdown(plugin, skillMdPath);
+  const name = componentName(plugin, data.name ?? basename(dir), skillMdPath);
+  if (name === undefined) {
+    return undefined;
+  }
+  return {
+    name,
+    description: skillDescription(name, data.description, body),
+    markdown: body.trim(),
+    files: await skillFiles(dir),
+  };
+}
+
+async function loadPluginCommands(
+  plugin: PluginDir,
+  declared: string[] | undefined
+): Promise<DiscoveredSkill[]> {
+  const skills: DiscoveredSkill[] = [];
+  for (const path of await componentFiles(
+    plugin,
+    declared,
+    "commands",
+    COMMAND_EXTENSIONS
+  )) {
+    const { data, body } = await readMarkdown(plugin, path);
+    const name = componentName(plugin, data.name ?? fileStem(path), path);
+    if (name === undefined) {
+      continue;
+    }
+    skills.push({
+      name,
+      description: skillDescription(name, data.description, body),
+      markdown: body.trim(),
+      files: {},
+    });
+  }
+  return skills;
+}
+
+async function loadPluginAgents(
+  plugin: PluginDir,
+  declared: string[] | undefined
+): Promise<CursorPluginAgent[]> {
+  const agents: CursorPluginAgent[] = [];
+  for (const path of await componentFiles(
+    plugin,
+    declared,
+    "agents",
+    MARKDOWN_EXTENSIONS
+  )) {
+    const { data, body } = await readMarkdown(plugin, path);
+    const name = componentName(plugin, data.name ?? fileStem(path), path);
+    if (name === undefined || agents.some((agent) => agent.name === name)) {
+      continue;
+    }
+    if (isBlank(body)) {
+      plugin.ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(plugin.ctx, path),
+        message: "Plugin agent has no prompt body; ignoring.",
+      });
+      continue;
+    }
+    agents.push({
+      name,
+      description: data.description,
+      model: data.model === "inherit" ? undefined : data.model,
+      prompt: body.trim(),
+    });
+  }
+  return agents;
+}
+
+/**
+ * The plugin's MCP servers as connections. A server the mount overlays is
+ * reported by name and never compiled, so its placeholders need no values.
+ */
+async function loadPluginConnections(
+  plugin: PluginDir,
+  declared: McpServers,
+  overlaid: ReadonlySet<string>
+): Promise<Pick<CursorPluginTree, "connections" | "overlaidServers">> {
+  const servers = new Map<string, { raw: unknown; path: string }>();
+  for (const file of MCP_CONFIG_FILES) {
+    const path = join(plugin.root, file);
+    if (!(await isFile(path))) {
+      continue;
+    }
+    for (const [name, raw] of Object.entries(await readMcpFile(plugin, path))) {
+      if (!servers.has(name)) {
+        servers.set(name, { raw, path });
+      }
+    }
+  }
+  // The manifest's own `mcpServers` wins on a name both declare.
+  for (const path of declaredPaths(plugin, declared.paths)) {
+    for (const [name, raw] of Object.entries(await readMcpFile(plugin, path))) {
+      servers.set(name, { raw, path });
+    }
+  }
+  for (const inline of declared.inline) {
+    for (const [name, raw] of Object.entries(mcpServersOf(inline))) {
+      servers.set(name, { raw, path: plugin.manifestPath });
+    }
+  }
+  const connections: DiscoveredConnection[] = [];
+  const overlaidServers: string[] = [];
+  for (const [rawName, { raw, path }] of servers) {
+    const name = componentName(plugin, rawName, path);
+    if (name === undefined) {
+      continue;
+    }
+    if (overlaid.has(name)) {
+      overlaidServers.push(name);
+      continue;
+    }
+    const connection = serverConnection(plugin, name, raw, path);
+    if (connection !== undefined) {
+      connections.push(connection);
+    }
+  }
+  return { connections, overlaidServers };
+}
+
+async function readMcpFile(
+  plugin: PluginDir,
+  path: string
+): Promise<Record<string, unknown>> {
+  const data = await readJson(plugin.ctx, path);
+  return isRecord(data) ? mcpServersOf(data) : {};
+}
+
+/** `{ mcpServers: { ... } }`, or a bare map of server-like entries. */
+function mcpServersOf(data: JsonRecord): Record<string, unknown> {
+  if (isRecord(data.mcpServers)) {
+    return data.mcpServers;
+  }
+  const servers: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(data)) {
+    if (isRecord(value) && ("command" in value || "url" in value)) {
+      servers[name] = value;
+    }
+  }
+  return servers;
+}
+
+function serverConnection(
+  plugin: PluginDir,
+  name: string,
+  raw: unknown,
+  path: string
+): DiscoveredConnection | undefined {
+  const unresolved = new Set<string>();
+  const expanded = expandPlaceholders(
+    raw,
+    (key) => {
+      if (PLUGIN_ROOT_VARIABLES.has(key)) {
+        return plugin.root;
+      }
+      return lookupVariable(plugin.variables, key) ?? process.env[key];
+    },
+    unresolved
+  );
+  if (unresolved.size > 0) {
+    plugin.ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(plugin.ctx, path),
+      message: `MCP server "${name}" needs ${[...unresolved].map((v) => `\${${v}}`).join(", ")}. Pass it in cursorPlugin({ variables }) or set it in the environment.`,
+    });
+    return undefined;
+  }
+  const parsed = mcpServerSchema.safeParse(expanded);
+  if (!parsed.success) {
+    plugin.ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(plugin.ctx, path),
+      message: `MCP server "${name}" is malformed: ${firstIssue(parsed.error)}.`,
+    });
+    return undefined;
+  }
+  const transport = serverTransport(plugin, name, parsed.data, path);
+  if (transport === undefined) {
+    return undefined;
+  }
+  const enabledTools = parsed.data.enabledTools;
+  return {
+    name,
+    transport,
+    // Cursor scopes the model to `enabledTools`; here that is an advertised allowlist.
+    advertiseTools: enabledTools === undefined ? undefined : true,
+    tools: enabledTools,
+  };
+}
+
+function serverTransport(
+  plugin: PluginDir,
+  name: string,
+  server: McpServer,
+  path: string
+): ConnectionTransport | undefined {
+  if (server.url !== undefined) {
+    const type =
+      server.type === "sse"
+        ? "sse"
+        : server.type === "http"
+          ? "http"
+          : undefined;
+    return {
+      type,
+      url: server.url,
+      headers: server.headers,
+      // Either client hint means the server speaks OAuth; the host PKCE flow
+      // (`mcp oauth`) owns it here.
+      oauth:
+        server.auth !== undefined || server.oauth !== undefined
+          ? true
+          : undefined,
+    };
+  }
+  if (server.command !== undefined) {
+    if (server.envFile !== undefined) {
+      plugin.ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(plugin.ctx, path),
+        message: `MCP server "${name}" sets envFile, which is not supported; pass its variables in cursorPlugin({ variables }).`,
+      });
+    }
+    return {
+      type: server.type === "stdio" ? "stdio" : undefined,
+      command: server.command,
+      args: server.args,
+      env: server.env,
+      cwd: server.cwd,
+    };
+  }
+  plugin.ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(plugin.ctx, path),
+    message: `MCP server "${name}" declares neither url nor command.`,
+  });
+  return undefined;
+}
+
+function expandPlaceholders(
+  value: unknown,
+  lookup: (key: string) => string | undefined,
+  unresolved: Set<string>
+): unknown {
+  if (typeof value === "string") {
+    return value.replace(
+      PLACEHOLDER,
+      (match, envKey?: string, key?: string, fallback?: string) => {
+        const name = envKey ?? key ?? "";
+        const resolved = lookup(name) ?? fallback;
+        if (resolved === undefined) {
+          unresolved.add(name);
+          return match;
+        }
+        return resolved;
+      }
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => expandPlaceholders(item, lookup, unresolved));
+  }
+  if (isRecord(value)) {
+    const out: JsonRecord = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = expandPlaceholders(item, lookup, unresolved);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Exact name first, then case-insensitive, as the Cursor loader resolves
+ * install variables: the Datadog plugin templates `${dd_site}` while its
+ * declared variable is `DD_SITE`.
+ */
+function lookupVariable(
+  variables: Record<string, string>,
+  key: string
+): string | undefined {
+  if (variables[key] !== undefined) {
+    return variables[key];
+  }
+  const lower = key.toLowerCase();
+  return Object.entries(variables).find(
+    ([name]) => name.toLowerCase() === lower
+  )?.[1];
+}
+
+/**
+ * Files a component slot resolves to: the manifest's declaration (files and
+ * directories, walked) or the conventional folder.
+ */
+async function componentFiles(
+  plugin: PluginDir,
+  declared: string[] | undefined,
+  folder: string,
+  extensions: Set<string>
+): Promise<string[]> {
+  const roots =
+    declared === undefined
+      ? [join(plugin.root, folder)]
+      : declaredPaths(plugin, declared);
+  const files: string[] = [];
+  for (const path of roots) {
+    if (await isDirectory(path)) {
+      files.push(...(await walkFiles(path)));
+    } else if (await isFile(path)) {
+      files.push(path);
+    }
+  }
+  return files.filter((file) => extensions.has(extname(file)));
+}
+
+/** Manifest paths resolve against the plugin root; escaping ones are refused, as in Cursor. */
+function declaredPaths(plugin: PluginDir, declared: string[]): string[] {
+  const paths: string[] = [];
+  for (const item of declared) {
+    const rel = item.replace(/^\.\//, "");
+    if (rel.includes("..") || isAbsolute(rel) || rel.includes("://")) {
+      plugin.ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(plugin.ctx, plugin.manifestPath),
+        message: `Plugin manifest path "${item}" leaves the plugin directory; ignoring.`,
+      });
+      continue;
+    }
+    paths.push(join(plugin.root, rel));
+  }
+  return paths;
+}
+
+async function readJson(ctx: DiscoveryContext, path: string): Promise<unknown> {
+  try {
+    return JSON.parse(await readFile(path, "utf8")) as unknown;
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message: `Failed to parse ${basename(path)}: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+}
+
+/** Frontmatter the reader understands; a malformed block warns and reads as empty. */
+async function readMarkdown(
+  plugin: PluginDir,
+  path: string
+): Promise<{ data: Frontmatter; body: string }> {
+  const { data, body, error } = parseYamlFrontmatter(
+    await readFile(path, "utf8")
+  );
+  const parsed = frontmatterSchema.safeParse(data);
+  const problem =
+    error ?? (parsed.success ? undefined : firstIssue(parsed.error));
+  if (problem !== undefined) {
+    plugin.ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(plugin.ctx, path),
+      message: `Frontmatter is malformed (${problem}); using the file name and body.`,
+    });
+  }
+  return { data: parsed.success ? parsed.data : {}, body };
+}
+
+/**
+ * Cursor lowercases and hyphenates component names; `_` and `.` fold to `-`
+ * as well so the name fits the tool-name rule and can never carry `__`.
+ */
+function componentName(
+  plugin: PluginDir,
+  raw: string,
+  path: string
+): string | undefined {
+  const name = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (name !== "") {
+    return name;
+  }
+  plugin.ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(plugin.ctx, path),
+    message: `Plugin component name "${raw}" has no usable characters; ignoring.`,
+  });
+  return undefined;
+}
+
+/** `headers: Expected object, received array`; the path names the field. */
+function firstIssue(error: z.ZodError): string {
+  const issue = error.issues[0];
+  if (issue === undefined) {
+    return "invalid";
+  }
+  const path = issue.path.join(".");
+  return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+
+function fileStem(path: string): string {
+  return basename(path, extname(path));
+}