@cursor/july 0.1.100 → 0.1.102

package/dist/internal/discovery/cursor-plugin.js

@@ -0,0 +1,570 @@
+/**
+ * A Cursor plugin directory read as an extension tree: skills, commands, agents, and MCP servers under the plugin's own names.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { readFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join } from "node:path";
+import { z } from "zod";
+import { parseYamlFrontmatter } from "../frontmatter.js";
+import { displayPath, errorMessage, isBlank, } from "./context.js";
+import { isDirectory, isFile, sortedEntries, walkFiles } from "./fs.js";
+import { skillDescription, skillFiles } from "./skills.js";
+/** 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 !== null && value !== void 0 ? value : []) : [value];
+        return {
+            paths: items.filter((item) => typeof item === "string"),
+            inline: items.filter((item) => typeof item !== "string"),
+        };
+    }),
+});
+const frontmatterSchema = z.object({
+    name: text.optional(),
+    description: text.optional(),
+    model: text.optional(),
+});
+/** 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(),
+});
+export function readCursorPlugin(ctx, root, mountPath, variables, overlaid) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const manifest = yield readManifest(ctx, root, mountPath);
+        if (manifest === undefined) {
+            return undefined;
+        }
+        const plugin = {
+            ctx,
+            root,
+            manifestPath: manifest.path,
+            variables,
+        };
+        const skills = yield loadPluginSkills(plugin, manifest.data.skills);
+        for (const command of yield 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);
+        }
+        yield warnUnmountedSlots(plugin, manifest.data);
+        return Object.assign(Object.assign({ description: manifest.data.description, skills }, (yield loadPluginConnections(plugin, manifest.data.mcpServers, overlaid))), { agents: yield loadPluginAgents(plugin, manifest.data.agents) });
+    });
+}
+function readManifest(ctx, root, mountPath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const rel of MANIFEST_PATHS) {
+            const path = join(root, rel);
+            if (!(yield isFile(path))) {
+                continue;
+            }
+            const data = yield 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. */
+function warnUnmountedSlots(plugin, manifest) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const unmounted = [];
+        if (manifest.rules !== undefined ||
+            (yield isDirectory(join(plugin.root, "rules")))) {
+            unmounted.push("rules");
+        }
+        if (manifest.hooks !== undefined ||
+            (yield 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.`,
+        });
+    });
+}
+function loadPluginSkills(plugin, declared) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const dirs = [];
+        if (declared === undefined) {
+            if (yield isFile(join(plugin.root, "SKILL.md"))) {
+                dirs.push(plugin.root);
+            }
+            dirs.push(...(yield skillDirsIn(join(plugin.root, "skills"))));
+        }
+        for (const path of declaredPaths(plugin, declared !== null && declared !== void 0 ? declared : [])) {
+            if (basename(path) === "SKILL.md" && (yield isFile(path))) {
+                dirs.push(dirname(path));
+            }
+            else if (yield isFile(join(path, "SKILL.md"))) {
+                dirs.push(path);
+            }
+            else {
+                dirs.push(...(yield skillDirsIn(path)));
+            }
+        }
+        const skills = [];
+        for (const dir of dirs) {
+            const skill = yield readSkillDir(plugin, dir);
+            if (skill !== undefined && !skills.some((s) => s.name === skill.name)) {
+                skills.push(skill);
+            }
+        }
+        return skills;
+    });
+}
+/** Immediate subdirectories holding a SKILL.md. */
+function skillDirsIn(dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(yield isDirectory(dir))) {
+            return [];
+        }
+        const dirs = [];
+        for (const entry of yield sortedEntries(dir)) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory() && (yield isFile(join(path, "SKILL.md")))) {
+                dirs.push(path);
+            }
+        }
+        return dirs;
+    });
+}
+function readSkillDir(plugin, dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const skillMdPath = join(dir, "SKILL.md");
+        const { data, body } = yield readMarkdown(plugin, skillMdPath);
+        const name = componentName(plugin, (_a = data.name) !== null && _a !== void 0 ? _a : basename(dir), skillMdPath);
+        if (name === undefined) {
+            return undefined;
+        }
+        return {
+            name,
+            description: skillDescription(name, data.description, body),
+            markdown: body.trim(),
+            files: yield skillFiles(dir),
+        };
+    });
+}
+function loadPluginCommands(plugin, declared) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const skills = [];
+        for (const path of yield componentFiles(plugin, declared, "commands", COMMAND_EXTENSIONS)) {
+            const { data, body } = yield readMarkdown(plugin, path);
+            const name = componentName(plugin, (_a = data.name) !== null && _a !== void 0 ? _a : fileStem(path), path);
+            if (name === undefined) {
+                continue;
+            }
+            skills.push({
+                name,
+                description: skillDescription(name, data.description, body),
+                markdown: body.trim(),
+                files: {},
+            });
+        }
+        return skills;
+    });
+}
+function loadPluginAgents(plugin, declared) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const agents = [];
+        for (const path of yield componentFiles(plugin, declared, "agents", MARKDOWN_EXTENSIONS)) {
+            const { data, body } = yield readMarkdown(plugin, path);
+            const name = componentName(plugin, (_a = data.name) !== null && _a !== void 0 ? _a : 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.
+ */
+function loadPluginConnections(plugin, declared, overlaid) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const servers = new Map();
+        for (const file of MCP_CONFIG_FILES) {
+            const path = join(plugin.root, file);
+            if (!(yield isFile(path))) {
+                continue;
+            }
+            for (const [name, raw] of Object.entries(yield 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(yield 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 = [];
+        const overlaidServers = [];
+        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 };
+    });
+}
+function readMcpFile(plugin, path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const data = yield readJson(plugin.ctx, path);
+        return isRecord(data) ? mcpServersOf(data) : {};
+    });
+}
+/** `{ mcpServers: { ... } }`, or a bare map of server-like entries. */
+function mcpServersOf(data) {
+    if (isRecord(data.mcpServers)) {
+        return data.mcpServers;
+    }
+    const servers = {};
+    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, name, raw, path) {
+    const unresolved = new Set();
+    const expanded = expandPlaceholders(raw, (key) => {
+        var _a;
+        if (PLUGIN_ROOT_VARIABLES.has(key)) {
+            return plugin.root;
+        }
+        return (_a = lookupVariable(plugin.variables, key)) !== null && _a !== void 0 ? _a : 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, name, server, path) {
+    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, lookup, unresolved) {
+    if (typeof value === "string") {
+        return value.replace(PLACEHOLDER, (match, envKey, key, fallback) => {
+            var _a, _b;
+            const name = (_a = envKey !== null && envKey !== void 0 ? envKey : key) !== null && _a !== void 0 ? _a : "";
+            const resolved = (_b = lookup(name)) !== null && _b !== void 0 ? _b : 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 = {};
+        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, key) {
+    var _a;
+    if (variables[key] !== undefined) {
+        return variables[key];
+    }
+    const lower = key.toLowerCase();
+    return (_a = Object.entries(variables).find(([name]) => name.toLowerCase() === lower)) === null || _a === void 0 ? void 0 : _a[1];
+}
+/**
+ * Files a component slot resolves to: the manifest's declaration (files and
+ * directories, walked) or the conventional folder.
+ */
+function componentFiles(plugin, declared, folder, extensions) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const roots = declared === undefined
+            ? [join(plugin.root, folder)]
+            : declaredPaths(plugin, declared);
+        const files = [];
+        for (const path of roots) {
+            if (yield isDirectory(path)) {
+                files.push(...(yield walkFiles(path)));
+            }
+            else if (yield 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, declared) {
+    const paths = [];
+    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;
+}
+function readJson(ctx, path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return JSON.parse(yield readFile(path, "utf8"));
+        }
+        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. */
+function readMarkdown(plugin, path) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { data, body, error } = parseYamlFrontmatter(yield readFile(path, "utf8"));
+        const parsed = frontmatterSchema.safeParse(data);
+        const problem = error !== null && error !== void 0 ? 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, raw, path) {
+    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) {
+    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) {
+    return basename(path, extname(path));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/internal/discovery/extensions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `agent/extensions/<ns>.ts` | `agent/extensions/<ns>/extension.ts`: agent-shaped trees and Cursor plugins mounted under a namespace.
+ */
+import type { DiscoveredConnection, DiscoveredExtension, DiscoveredSkill, DiscoveredTool, ResolvedAgent } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+/** The agent's authored slot lists that mounted extensions append to. */
+export interface ExtensionContributions {
+    tools: DiscoveredTool[];
+    skills: DiscoveredSkill[];
+    connections: DiscoveredConnection[];
+    subagents: ResolvedAgent[];
+}
+/**
+ * Mount every extension under `agent/extensions/` and append what it
+ * contributes to the authored lists as `<ns>__<name>`, stamped with
+ * `extension`. The namespace is the mount's filename stem or directory name.
+ */
+export declare function appendExtensions(ctx: DiscoveryContext, extensionsDir: string, into: ExtensionContributions): Promise<DiscoveredExtension[]>;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/internal/discovery/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/extensions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAEV,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,cAAc,EAEd,aAAa,EAEd,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,cAAc,CAAC;AAgBlE,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CA4BhC"}