@cursor/bdk 0.2.3 → 0.2.4

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

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