@pulsemcp/air-adapter-cursor 0.8.0

package/dist/cursor-adapter.js

@@ -0,0 +1,1018 @@
+import { execSync } from "child_process";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, copyFileSync, rmSync, statSync, } from "fs";
+import { join, dirname, relative } from "path";
+import { buildManifest, deleteManifest, diffManifest, getManifestPath, loadManifest, writeManifest, parseQualifiedId, resolveReference, } from "@pulsemcp/air-core";
+import { scanLocalSkills } from "./scan-local-skills.js";
+/** Matches a value that contains a `${VAR}` reference anywhere within it. */
+const CONTAINS_VAR_RE = /\$\{[^}]+\}/;
+/**
+ * Cursor's built-in `${...}` interpolation tokens. These are NOT environment
+ * variables and must be left untouched when rewriting AIR `${VAR}` refs into
+ * Cursor's `${env:VAR}` form — wrapping them would break Cursor's own
+ * expansion.
+ */
+const CURSOR_BUILTIN_VARS = new Set([
+    "userHome",
+    "workspaceFolder",
+    "workspaceFolderBasename",
+    "pathSeparator",
+]);
+export class CursorAdapter {
+    name = "cursor";
+    displayName = "Cursor";
+    /**
+     * Map AIR lifecycle event names to Cursor `hooks.json` event names.
+     *
+     * Accepts both snake_case AIR names and camelCase Cursor event names as
+     * identity mappings, so hook authors targeting the Cursor runtime can write
+     * Cursor-native event names directly without translating to snake_case.
+     *
+     * The only AIR event without a Cursor equivalent is `notification` — it is
+     * intentionally absent, so `reconcileHooks` warns and skips registration when
+     * it encounters it. Cursor-only events (beforeShellExecution, afterFileEdit,
+     * etc.) have no AIR analog and are therefore not generated by AIR, but
+     * user-authored hooks targeting them are preserved.
+     */
+    static AIR_TO_CURSOR_EVENT = {
+        // snake_case AIR names
+        session_start: "sessionStart",
+        session_end: "sessionEnd",
+        pre_tool_call: "preToolUse",
+        post_tool_call: "postToolUse",
+        user_prompt_submit: "beforeSubmitPrompt",
+        stop: "stop",
+        subagent_stop: "subagentStop",
+        pre_compact: "preCompact",
+        // camelCase Cursor event names (identity — hook authors targeting Cursor
+        // often write these directly).
+        sessionStart: "sessionStart",
+        sessionEnd: "sessionEnd",
+        preToolUse: "preToolUse",
+        postToolUse: "postToolUse",
+        postToolUseFailure: "postToolUseFailure",
+        subagentStart: "subagentStart",
+        subagentStop: "subagentStop",
+        beforeShellExecution: "beforeShellExecution",
+        afterShellExecution: "afterShellExecution",
+        beforeMCPExecution: "beforeMCPExecution",
+        afterMCPExecution: "afterMCPExecution",
+        beforeReadFile: "beforeReadFile",
+        afterFileEdit: "afterFileEdit",
+        beforeSubmitPrompt: "beforeSubmitPrompt",
+        preCompact: "preCompact",
+        afterAgentResponse: "afterAgentResponse",
+        afterAgentThought: "afterAgentThought",
+        beforeTabFileRead: "beforeTabFileRead",
+        afterTabFileEdit: "afterTabFileEdit",
+        workspaceOpen: "workspaceOpen",
+    };
+    /** Canonical AIR snake_case event names with a Cursor mapping. */
+    static AIR_EVENT_NAMES = [
+        "session_start",
+        "session_end",
+        "pre_tool_call",
+        "post_tool_call",
+        "user_prompt_submit",
+        "stop",
+        "subagent_stop",
+        "pre_compact",
+    ];
+    async isAvailable() {
+        try {
+            execSync("which cursor-agent", { stdio: "pipe" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    generateConfig(artifacts, root, _workDir) {
+        const pluginActivations = root?.default_plugins
+            ? this.resolveActivations(artifacts.plugins, root.default_plugins, "plugin")
+            : [];
+        const plugins = {};
+        for (const a of pluginActivations)
+            plugins[a.qualified] = artifacts.plugins[a.qualified];
+        // Merge plugin-declared MCP servers and skills into root defaults (additive).
+        // All incoming IDs are qualified (post-canonicalization at composition time),
+        // so we deduplicate on qualified IDs.
+        const mcpQualSet = new Set(root?.default_mcp_servers ?? []);
+        const skillQualSet = new Set(root?.default_skills ?? []);
+        for (const plugin of Object.values(plugins)) {
+            if (plugin.mcp_servers) {
+                for (const id of plugin.mcp_servers)
+                    mcpQualSet.add(id);
+            }
+            if (plugin.skills) {
+                for (const id of plugin.skills)
+                    skillQualSet.add(id);
+            }
+        }
+        const mcpActivations = this.resolveActivations(artifacts.mcp, [...mcpQualSet], "MCP server");
+        const skillActivations = this.resolveActivations(artifacts.skills, [...skillQualSet], "skill");
+        const mcpServers = {};
+        for (const a of mcpActivations)
+            mcpServers[a.short] = artifacts.mcp[a.qualified];
+        const mcpConfig = this.translateMcpServersByShort(mcpServers);
+        const pluginConfigs = pluginActivations.map((a) => this.translatePlugin(a.short, artifacts.plugins[a.qualified]));
+        const skillPaths = skillActivations.map((a) => artifacts.skills[a.qualified].path);
+        return {
+            agent: "cursor",
+            mcpConfig,
+            pluginConfigs,
+            skillPaths,
+            env: {},
+        };
+    }
+    buildStartCommand(config) {
+        // Cursor auto-discovers `.cursor/mcp.json`, `.cursor/hooks.json`, and
+        // `.cursor/skills/` relative to its working directory. Pointing the working
+        // directory at the prepared directory loads everything; no extra flags are
+        // required.
+        return {
+            command: "cursor-agent",
+            args: [],
+            env: config.env,
+            cwd: config.workDir,
+        };
+    }
+    /**
+     * Prepare a working directory for a Cursor CLI session.
+     *
+     * Writes `.cursor/mcp.json` (MCP servers under `mcpServers`) and
+     * `.cursor/hooks.json` (hook registrations under `hooks.<event>`), injects
+     * skills + references into `.cursor/skills/<name>/`, copies path-based hooks
+     * into `.cursor/hooks/<name>/`, and returns the start command.
+     *
+     * Inputs to activation lists (root defaults, overrides, plugin-declared
+     * primitives) are accepted as either qualified (`@scope/id`) or short form;
+     * ambiguous short forms are rejected. Filesystem materialization uses
+     * shortnames — Cursor's config files, `.cursor/skills/`, `.cursor/hooks/`,
+     * and the manifest are scope-naive. Two activated qualified IDs that share
+     * a shortname hard-fail with a clear "add one to exclude" message.
+     *
+     * NOTE: `configFiles` is intentionally returned empty. AIR `${VAR}`
+     * references in MCP env/headers are rewritten to Cursor's native
+     * `${env:VAR}` interpolation at translation time, so there is no resolvable
+     * `${VAR}` left for AIR's transform/validation pipeline. The `.cursor/mcp.json`
+     * we wrote above is deliberately not surfaced as a config file.
+     */
+    async prepareSession(artifacts, targetDir, options) {
+        const root = options?.root;
+        const skillPaths = [];
+        const hookPaths = [];
+        const prevManifest = loadManifest(targetDir);
+        // 1. Resolve which artifacts to activate (overrides take precedence over root defaults)
+        let mcpServerIds = options?.mcpServerOverrides ?? root?.default_mcp_servers ?? undefined;
+        let skillIds = options?.skillOverrides ?? root?.default_skills ?? [];
+        let hookIds = options?.hookOverrides ?? root?.default_hooks ?? [];
+        // 1b. Merge subagent roots' artifacts if applicable.
+        const subagentRoots = this.resolveSubagentRoots(root, artifacts, options);
+        if (subagentRoots.length > 0) {
+            const merged = this.mergeSubagentArtifacts(subagentRoots, mcpServerIds, skillIds);
+            if (!options?.mcpServerOverrides) {
+                mcpServerIds = merged.mcpServerIds;
+            }
+            if (!options?.skillOverrides) {
+                skillIds = merged.skillIds;
+            }
+        }
+        // 1c. Resolve plugins and merge their declared artifacts (additive)
+        const pluginIds = options?.pluginOverrides ?? root?.default_plugins ?? undefined;
+        const pluginActivations = pluginIds?.length
+            ? this.resolveActivations(artifacts.plugins, pluginIds, "plugin")
+            : [];
+        const plugins = {};
+        for (const a of pluginActivations)
+            plugins[a.qualified] = artifacts.plugins[a.qualified];
+        const mcpSet = new Set(mcpServerIds ?? []);
+        const skillSet = new Set(skillIds);
+        const hookSet = new Set(hookIds);
+        for (const plugin of Object.values(plugins)) {
+            if (plugin.mcp_servers)
+                for (const id of plugin.mcp_servers)
+                    mcpSet.add(id);
+            if (plugin.skills)
+                for (const id of plugin.skills)
+                    skillSet.add(id);
+            if (plugin.hooks)
+                for (const id of plugin.hooks)
+                    hookSet.add(id);
+        }
+        if (mcpSet.size > 0 || mcpServerIds !== undefined)
+            mcpServerIds = [...mcpSet];
+        skillIds = [...skillSet];
+        hookIds = [...hookSet];
+        // 2. Resolve activations: qualified ID + shortname per artifact.
+        //    Throws on unknown IDs, ambiguous shortnames, and shortname collisions.
+        const skillActs = this.resolveActivations(artifacts.skills, skillIds, "skill");
+        const mcpActs = mcpServerIds
+            ? this.resolveActivations(artifacts.mcp, mcpServerIds, "MCP server")
+            : [];
+        const hookActs = this.resolveActivations(artifacts.hooks, hookIds, "hook");
+        const skillShortIds = skillActs.map((a) => a.short);
+        const hookShortIds = hookActs.map((a) => a.short);
+        const mcpShortIds = mcpActs.map((a) => a.short);
+        // 3. Reconcile against prior manifest using shortnames — those are the keys
+        //    used for filesystem materialization and stored in the manifest.
+        const diff = diffManifest(prevManifest, {
+            skills: skillShortIds,
+            hooks: hookShortIds,
+            mcpServers: mcpShortIds,
+        });
+        for (const staleSkillId of diff.staleSkills) {
+            const staleDir = join(targetDir, ".cursor", "skills", staleSkillId);
+            if (existsSync(staleDir)) {
+                rmSync(staleDir, { recursive: true, force: true });
+            }
+        }
+        for (const staleHookId of diff.staleHooks) {
+            const staleDir = join(targetDir, ".cursor", "hooks", staleHookId);
+            if (existsSync(staleDir)) {
+                rmSync(staleDir, { recursive: true, force: true });
+            }
+        }
+        // 4. Inject skills + references into .cursor/skills/<short>/
+        const materializedSkillShortIds = [];
+        for (const a of skillActs) {
+            const skill = artifacts.skills[a.qualified];
+            const skillTargetDir = join(targetDir, ".cursor", "skills", a.short);
+            if (existsSync(skillTargetDir)) {
+                materializedSkillShortIds.push(a.short);
+                continue;
+            }
+            const skillSourceDir = skill.path;
+            if (!existsSync(skillSourceDir)) {
+                console.warn(this.missingSourceDirMessage("skill", a.qualified, skillSourceDir));
+                continue;
+            }
+            this.copyDirRecursive(skillSourceDir, skillTargetDir);
+            skillPaths.push(skillTargetDir);
+            materializedSkillShortIds.push(a.short);
+            if (skill.references && skill.references.length > 0) {
+                this.copyReferences(skill.references, skillTargetDir, artifacts);
+            }
+        }
+        // 5. Validate and inject path-based hooks into .cursor/hooks/<short>/.
+        const prevHookIds = new Set(prevManifest?.hooks ?? []);
+        const registeredHookShortIds = [];
+        const registeredHookActivations = [];
+        for (const a of hookActs) {
+            const hook = artifacts.hooks[a.qualified];
+            const hookTargetDir = join(targetDir, ".cursor", "hooks", a.short);
+            const alreadyExists = existsSync(hookTargetDir);
+            if (alreadyExists && !prevHookIds.has(a.short)) {
+                continue;
+            }
+            if (!alreadyExists) {
+                const hookSourceDir = hook.path;
+                if (!existsSync(hookSourceDir)) {
+                    console.warn(this.missingSourceDirMessage("hook", a.qualified, hookSourceDir));
+                    continue;
+                }
+                this.copyDirRecursive(hookSourceDir, hookTargetDir);
+                if (hook.references && hook.references.length > 0) {
+                    this.copyReferences(hook.references, hookTargetDir, artifacts);
+                }
+            }
+            hookPaths.push(hookTargetDir);
+            registeredHookShortIds.push(a.short);
+            registeredHookActivations.push({ short: a.short, qualified: a.qualified });
+        }
+        // 6. Write `.cursor/mcp.json`: AIR-managed MCP servers, merged into any
+        //    user-authored config (full replacement of AIR-owned keys; user keys
+        //    preserved; stale AIR keys removed).
+        const translatedServers = {};
+        for (const a of mcpActs)
+            translatedServers[a.short] = artifacts.mcp[a.qualified];
+        this.writeCursorMcpConfig(targetDir, this.translateMcpServersByShort(translatedServers), diff.staleMcpServers);
+        // 6b. Write `.cursor/hooks.json`: AIR-owned hook registrations (tagged with
+        //     `_air_hook_id`), merged into any user-authored hooks.
+        const managedHookIds = new Set([
+            ...diff.staleHooks,
+            ...registeredHookShortIds,
+        ]);
+        this.writeCursorHooksConfig(targetDir, hookPaths, managedHookIds);
+        // 7. Persist the updated manifest (shortnames — keyed by filesystem dir).
+        //    Only record skills/hooks that were actually materialized so the manifest
+        //    does not claim ownership of artifacts AIR skipped (e.g. a missing source dir).
+        writeManifest(buildManifest(targetDir, {
+            adapter: this.name,
+            skills: materializedSkillShortIds,
+            hooks: registeredHookShortIds,
+            mcpServers: mcpShortIds,
+        }));
+        // 8. Generate ephemeral subagent context for the session.
+        //    Cursor has no `--append-system-prompt` equivalent, so this is surfaced
+        //    to the caller via `subagentContext` rather than the start command.
+        let subagentContext;
+        if (subagentRoots.length > 0) {
+            subagentContext = this.buildSubagentContext(subagentRoots);
+        }
+        // 9. Build start command (working directory = prepared directory).
+        const config = this.generateConfig(artifacts, undefined, targetDir);
+        const startCommand = this.buildStartCommand({
+            ...config,
+            workDir: targetDir,
+        });
+        return {
+            // Empty by design — see method doc: AIR `${VAR}` references are rewritten
+            // to Cursor's native `${env:VAR}` interpolation at translation time, so
+            // there is nothing left for AIR's JSON transform/validation pipeline to
+            // resolve. The `.cursor/mcp.json` and `.cursor/hooks.json` we wrote above
+            // are deliberately not surfaced as config files.
+            configFiles: [],
+            skillPaths,
+            hookPaths,
+            hookActivations: registeredHookActivations,
+            startCommand,
+            subagentContext,
+        };
+    }
+    /**
+     * Enumerate skills checked into `<targetDir>/.cursor/skills/`. Cursor loads
+     * these directly from the filesystem regardless of AIR's involvement, so
+     * they're always active and must not be overwritten or removed. The TUI uses
+     * this list to surface them as read-only entries.
+     */
+    async listLocalArtifacts(targetDir) {
+        return { skills: scanLocalSkills(targetDir) };
+    }
+    /**
+     * Remove every artifact AIR has previously written into `targetDir`.
+     *
+     * Reads the per-target manifest, deletes each tracked skill / hook
+     * directory, removes tracked MCP server keys from `.cursor/mcp.json`, and
+     * removes AIR-managed hook entries from `.cursor/hooks.json`. When every
+     * category is cleaned, the manifest itself is deleted; partial cleans (any
+     * `keep*` flag set) update the manifest with the kept entries so future runs
+     * continue to track them.
+     *
+     * Items in the manifest that no longer exist on disk are silently skipped
+     * — the manifest can drift if a user removed files manually between runs.
+     */
+    async cleanSession(targetDir, options) {
+        const dryRun = options?.dryRun ?? false;
+        const cleanSkills = !(options?.keepSkills ?? false);
+        const cleanHooks = !(options?.keepHooks ?? false);
+        const cleanMcpServers = !(options?.keepMcpServers ?? false);
+        const fullClean = cleanSkills && cleanHooks && cleanMcpServers;
+        const manifestPath = getManifestPath(targetDir);
+        const manifestFileExists = existsSync(manifestPath);
+        const manifest = loadManifest(targetDir);
+        if (!manifest) {
+            let corruptManifestRemoved = false;
+            if (manifestFileExists && fullClean && !dryRun) {
+                corruptManifestRemoved = deleteManifest(targetDir);
+            }
+            return {
+                removedSkills: [],
+                removedHooks: [],
+                removedMcpServers: [],
+                mcpConfigPath: null,
+                settingsPath: null,
+                manifestPath,
+                manifestExisted: manifestFileExists,
+                manifestRemoved: corruptManifestRemoved,
+            };
+        }
+        const mcpPath = join(targetDir, ".cursor", "mcp.json");
+        const hooksPath = join(targetDir, ".cursor", "hooks.json");
+        const removedSkills = [];
+        if (cleanSkills) {
+            for (const id of manifest.skills) {
+                const dir = join(targetDir, ".cursor", "skills", id);
+                if (!existsSync(dir))
+                    continue;
+                if (!dryRun)
+                    rmSync(dir, { recursive: true, force: true });
+                removedSkills.push(id);
+            }
+        }
+        const removedHooks = [];
+        if (cleanHooks) {
+            for (const id of manifest.hooks) {
+                const dir = join(targetDir, ".cursor", "hooks", id);
+                if (!existsSync(dir))
+                    continue;
+                if (!dryRun)
+                    rmSync(dir, { recursive: true, force: true });
+                removedHooks.push(id);
+            }
+        }
+        // Prune AIR-owned MCP servers from `.cursor/mcp.json`.
+        const removedMcpServers = [];
+        let mcpConfigPath = null;
+        if (cleanMcpServers && manifest.mcpServers.length > 0 && existsSync(mcpPath)) {
+            const presentMcpIds = this.mcpServerIdsPresent(mcpPath, manifest.mcpServers);
+            if (presentMcpIds.length > 0) {
+                if (!dryRun) {
+                    mcpConfigPath = this.pruneCursorMcpConfig(mcpPath, presentMcpIds);
+                }
+                else {
+                    mcpConfigPath = mcpPath;
+                }
+                for (const id of presentMcpIds)
+                    removedMcpServers.push(id);
+            }
+        }
+        // Prune AIR-owned hook entries from `.cursor/hooks.json`.
+        let settingsPath = null;
+        if (cleanHooks && manifest.hooks.length > 0 && existsSync(hooksPath)) {
+            if (this.hookEntriesPresent(hooksPath, new Set(manifest.hooks))) {
+                if (!dryRun) {
+                    settingsPath = this.pruneCursorHooksConfig(hooksPath, new Set(manifest.hooks));
+                }
+                else {
+                    settingsPath = hooksPath;
+                }
+            }
+        }
+        let manifestRemoved = false;
+        if (fullClean) {
+            if (!dryRun) {
+                manifestRemoved = deleteManifest(targetDir);
+            }
+            else {
+                manifestRemoved = manifestFileExists;
+            }
+        }
+        else if (!dryRun) {
+            writeManifest(buildManifest(targetDir, {
+                adapter: manifest.adapter ?? this.name,
+                skills: cleanSkills ? [] : manifest.skills,
+                hooks: cleanHooks ? [] : manifest.hooks,
+                mcpServers: cleanMcpServers ? [] : manifest.mcpServers,
+            }));
+        }
+        return {
+            removedSkills,
+            removedHooks,
+            removedMcpServers,
+            // Cursor splits MCP servers (`.cursor/mcp.json`) and hooks
+            // (`.cursor/hooks.json`) across two files; report them separately.
+            mcpConfigPath,
+            settingsPath,
+            manifestPath,
+            manifestExisted: true,
+            manifestRemoved,
+        };
+    }
+    /**
+     * Read `.cursor/mcp.json` and return the subset of `ids` whose key is
+     * actually present under `mcpServers`. Returns an empty list if the file
+     * can't be parsed — we'd rather under-report than claim to have removed
+     * entries we never touched.
+     */
+    mcpServerIdsPresent(mcpPath, ids) {
+        const existing = this.readJson(mcpPath);
+        const servers = existing.mcpServers ?? {};
+        return ids.filter((id) => Object.prototype.hasOwnProperty.call(servers, id));
+    }
+    /**
+     * Return true if `.cursor/hooks.json` contains at least one AIR-owned hook
+     * entry (`_air_hook_id` ∈ `managedHookIds`). Used to avoid rewriting a file
+     * we wouldn't actually change.
+     */
+    hookEntriesPresent(hooksPath, managedHookIds) {
+        const config = this.readJson(hooksPath);
+        const hooks = config.hooks ?? {};
+        for (const entries of Object.values(hooks)) {
+            if (!Array.isArray(entries))
+                continue;
+            for (const e of entries) {
+                if (this.isManagedHookEntry(e, managedHookIds))
+                    return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Resolve subagent roots from the root's default_subagent_roots.
+     * IDs are already qualified after composition-time canonicalization.
+     */
+    resolveSubagentRoots(root, artifacts, options) {
+        if (options?.skipSubagentMerge)
+            return [];
+        if (!root?.default_subagent_roots?.length)
+            return [];
+        const resolved = [];
+        for (const id of root.default_subagent_roots) {
+            const res = resolveReference(artifacts.roots, id, undefined);
+            if (res.status === "ok") {
+                resolved.push(artifacts.roots[res.qualified]);
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Merge subagent roots' default_mcp_servers and default_skills into the
+     * parent's activated sets (union, preserving order with parent first).
+     */
+    mergeSubagentArtifacts(subagentRoots, parentMcpServerIds, parentSkillIds) {
+        const mcpSet = new Set(parentMcpServerIds ?? []);
+        const skillSet = new Set(parentSkillIds);
+        for (const sub of subagentRoots) {
+            if (sub.default_mcp_servers) {
+                for (const id of sub.default_mcp_servers)
+                    mcpSet.add(id);
+            }
+            if (sub.default_skills) {
+                for (const id of sub.default_skills)
+                    skillSet.add(id);
+            }
+        }
+        return {
+            mcpServerIds: parentMcpServerIds !== undefined || mcpSet.size > 0 ? [...mcpSet] : undefined,
+            skillIds: [...skillSet],
+        };
+    }
+    /**
+     * Build a system prompt section describing the subagent root dependencies.
+     */
+    buildSubagentContext(subagentRoots) {
+        const lines = [
+            "## Subagent Root Dependencies",
+            "",
+            "This session includes capabilities from the following subagent roots.",
+            "Their skills and MCP servers have been merged into your session.",
+            "",
+        ];
+        for (const sub of subagentRoots) {
+            lines.push(`### ${sub.display_name || "Subagent"}`);
+            lines.push("");
+            lines.push(`**Description**: ${sub.description}`);
+            if (sub.default_mcp_servers?.length) {
+                lines.push(`**MCP Servers**: ${sub.default_mcp_servers.join(", ")}`);
+            }
+            if (sub.default_skills?.length) {
+                lines.push(`**Skills**: ${sub.default_skills.join(", ")}`);
+            }
+            if (sub.subdirectory) {
+                lines.push(`**Subdirectory**: ${sub.subdirectory}`);
+            }
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Translate a shortname-keyed MCP server map into Cursor's `mcpServers`
+     * shape (a plain object ready for JSON serialization). Callers convert
+     * qualified IDs to shortnames before invoking this — Cursor's config is
+     * scope-naive.
+     *
+     * Secret handling is Cursor-native: AIR `${VAR}` references in any string
+     * value (command, args, env values, url, headers) are rewritten to Cursor's
+     * `${env:VAR}` interpolation, which Cursor expands from the host environment
+     * at launch (see `toCursorVars`). Because Cursor's interpolation works
+     * anywhere in a string, partial (`"Bearer ${TOKEN}"`) and renamed
+     * (`KEY = "${OTHER}"`) references all forward cleanly — there are no
+     * unforwardable shapes, so no warnings are emitted.
+     */
+    translateMcpServersByShort(servers) {
+        const out = {};
+        for (const [name, server] of Object.entries(servers)) {
+            out[name] = this.translateMcpServer(server);
+        }
+        return out;
+    }
+    translateMcpServer(server) {
+        if (server.type === "stdio") {
+            const out = { command: this.toCursorVars(server.command) };
+            if (server.args && server.args.length > 0) {
+                out.args = server.args.map((a) => this.toCursorVars(a));
+            }
+            if (server.env && Object.keys(server.env).length > 0) {
+                const env = {};
+                for (const [key, value] of Object.entries(server.env)) {
+                    env[key] = this.toCursorVars(value);
+                }
+                out.env = env;
+            }
+            return out;
+        }
+        // Remote server (sse or streamable-http). Cursor models both as a URL-based
+        // server and auto-detects the transport from the URL.
+        const out = { url: this.toCursorVars(server.url) };
+        if (server.headers && Object.keys(server.headers).length > 0) {
+            const headers = {};
+            for (const [key, value] of Object.entries(server.headers)) {
+                headers[key] = this.toCursorVars(value);
+            }
+            out.headers = headers;
+        }
+        // NOTE: AIR's detailed OAuth config (clientId/scopes/redirectUri/…) has no
+        // static Cursor equivalent — Cursor performs interactive OAuth via
+        // `cursor-agent mcp login <name>`. The gap is documented in the adapter README.
+        return out;
+    }
+    /**
+     * Rewrite AIR `${VAR}` references into Cursor's native `${env:VAR}`
+     * interpolation. Each `${...}` token is wrapped unless it is already a
+     * Cursor `${env:...}` reference or one of Cursor's built-in interpolation
+     * tokens (`${userHome}`, `${workspaceFolder}`, …), which must be left
+     * untouched. Strings without a `${...}` token are returned unchanged.
+     */
+    toCursorVars(value) {
+        if (typeof value !== "string")
+            return value;
+        if (!CONTAINS_VAR_RE.test(value))
+            return value;
+        return value.replace(/\$\{([^}]+)\}/g, (full, inner) => {
+            if (inner.startsWith("env:"))
+                return full; // already a Cursor env ref
+            if (CURSOR_BUILTIN_VARS.has(inner))
+                return full; // Cursor built-in token
+            return `\${env:${inner}}`;
+        });
+    }
+    /**
+     * Translate an AIR plugin to a Cursor-facing descriptor.
+     *
+     * Cursor's marketplace plugins are remote-installed and have no local package
+     * file an adapter can materialize. AIR therefore treats plugins as composition
+     * sugar: a plugin's declared MCP servers / skills / hooks are expanded into the
+     * activation set and materialized as their underlying Cursor-native artifacts.
+     * This descriptor is informational only.
+     */
+    translatePlugin(shortId, plugin) {
+        return {
+            name: shortId,
+            description: plugin.description,
+            ...(plugin.version && { version: plugin.version }),
+        };
+    }
+    /**
+     * Resolve a list of activation IDs (each qualified or short) into qualified
+     * IDs paired with shortnames suitable for filesystem materialization.
+     *
+     * Throws on:
+     *   - unknown IDs (after attempting both qualified and short-form lookup)
+     *   - ambiguous short references (multiple scopes contribute the shortname)
+     *   - shortname collisions in the activation set itself (two qualified IDs
+     *     with the same shortname can't share a single materialization dir)
+     */
+    resolveActivations(pool, ids, artifactType) {
+        const acts = [];
+        const errors = [];
+        const shortToQualified = new Map();
+        for (const id of ids) {
+            const res = resolveReference(pool, id, undefined);
+            if (res.status === "missing") {
+                errors.push(`Unknown ${artifactType} ID "${id}". Available: ${this.formatPoolKeys(pool)}.`);
+                continue;
+            }
+            if (res.status === "ambiguous") {
+                errors.push(`${artifactType} reference "${id}" is ambiguous — candidates: ` +
+                    `${res.candidates.join(", ")}. Use the qualified form to disambiguate.`);
+                continue;
+            }
+            const qualified = res.qualified;
+            const { id: short } = parseQualifiedId(qualified);
+            const prior = shortToQualified.get(short);
+            if (prior !== undefined && prior !== qualified) {
+                errors.push(`${artifactType} shortname collision: both "${prior}" and "${qualified}" ` +
+                    `are activated and would write to the same target name "${short}". ` +
+                    `Add one to air.json#exclude or activate only one of them.`);
+                continue;
+            }
+            if (prior === qualified)
+                continue; // dedup
+            shortToQualified.set(short, qualified);
+            acts.push({ qualified, short });
+        }
+        if (errors.length > 0) {
+            throw new Error(errors.length === 1 ? errors[0] : `Activation errors:\n  - ${errors.join("\n  - ")}`);
+        }
+        return acts;
+    }
+    /**
+     * Build the warning emitted when a registered artifact's `path` does not
+     * exist on disk at materialization time. The qualified ID encodes the
+     * declaring catalog's scope, so a reviewer can trace the offending entry
+     * back to its index file. Materialization is skipped for this artifact and
+     * the rest of the session proceeds.
+     */
+    missingSourceDirMessage(artifactType, qualified, resolvedPath) {
+        return (`warning: ${artifactType} "${qualified}" declares path "${resolvedPath}" but that directory does not exist — skipping. ` +
+            `The catalog that contributed "${qualified}" registered a path AIR cannot materialize. ` +
+            `Fix the \`path\` field in the catalog's index file (or exclude the artifact in air.json) to restore the ${artifactType}.`);
+    }
+    formatPoolKeys(pool) {
+        const keys = Object.keys(pool);
+        if (keys.length === 0)
+            return "(none)";
+        if (keys.length > 8) {
+            return `${keys.slice(0, 8).join(", ")}, … (${keys.length} total)`;
+        }
+        return keys.join(", ");
+    }
+    /**
+     * Copy referenced documents into a references/ subdirectory of the target.
+     * `refIds` are qualified IDs (post-canonicalization).
+     */
+    copyReferences(refIds, targetDir, artifacts) {
+        const refsTargetDir = join(targetDir, "references");
+        for (const refId of refIds) {
+            const ref = artifacts.references[refId];
+            if (!ref)
+                continue;
+            const refSourcePath = ref.path;
+            if (existsSync(refSourcePath)) {
+                const refTargetPath = join(refsTargetDir, ref.path.split("/").pop() || ref.path);
+                mkdirSync(dirname(refTargetPath), { recursive: true });
+                copyFileSync(refSourcePath, refTargetPath);
+            }
+        }
+    }
+    // ============================================================
+    // `.cursor/mcp.json` and `.cursor/hooks.json` read / merge / write
+    // ============================================================
+    /** Parse an existing JSON config, returning `{}` when absent/unparseable. */
+    readJson(path) {
+        if (!existsSync(path))
+            return {};
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed
+                : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    writeJson(path, value) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(value, null, 2) + "\n");
+    }
+    /**
+     * Merge AIR-managed MCP servers into `.cursor/mcp.json`, preserving any
+     * user-authored config. Keys in `staleMcpIds` are removed; keys in
+     * `translatedServers` are set/replaced; other servers and top-level keys pass
+     * through. A run that leaves the config empty deletes the file rather than
+     * leaving an empty stub. Returns the path written, or null if the file was
+     * deleted / not created.
+     */
+    writeCursorMcpConfig(targetDir, translatedServers, staleMcpIds) {
+        const mcpPath = join(targetDir, ".cursor", "mcp.json");
+        const config = this.readJson(mcpPath);
+        const servers = config.mcpServers ?? {};
+        for (const id of staleMcpIds)
+            delete servers[id];
+        for (const [id, cfg] of Object.entries(translatedServers))
+            servers[id] = cfg;
+        if (Object.keys(servers).length > 0) {
+            config.mcpServers = servers;
+        }
+        else {
+            delete config.mcpServers;
+        }
+        if (Object.keys(config).length === 0) {
+            if (existsSync(mcpPath))
+                rmSync(mcpPath, { force: true });
+            return null;
+        }
+        this.writeJson(mcpPath, config);
+        return mcpPath;
+    }
+    /**
+     * Merge AIR-owned hook registrations into `.cursor/hooks.json`, preserving
+     * any user-authored hooks. AIR-owned entries (tagged with `_air_hook_id`)
+     * whose ID is in `managedHookIds` are pruned, then the current selection is
+     * registered. A run that leaves no hooks deletes the file (an empty hooks
+     * config is a useless stub) unless the user kept other top-level keys.
+     * Returns the path written, or null if the file was deleted / not created.
+     */
+    writeCursorHooksConfig(targetDir, newHookPaths, managedHookIds) {
+        const hooksPath = join(targetDir, ".cursor", "hooks.json");
+        const config = this.readJson(hooksPath);
+        const hooks = config.hooks ?? {};
+        // Prune AIR-owned entries whose ID is managed by this run.
+        for (const event of Object.keys(hooks)) {
+            const entries = hooks[event];
+            if (!Array.isArray(entries))
+                continue;
+            const kept = entries.filter((e) => !this.isManagedHookEntry(e, managedHookIds));
+            if (kept.length === 0) {
+                delete hooks[event];
+            }
+            else {
+                hooks[event] = kept;
+            }
+        }
+        // Register the current hook selection.
+        for (const hookPath of newHookPaths) {
+            const hookJsonPath = join(hookPath, "HOOK.json");
+            if (!existsSync(hookJsonPath))
+                continue;
+            let hookJson;
+            try {
+                hookJson = JSON.parse(readFileSync(hookJsonPath, "utf-8"));
+            }
+            catch {
+                continue;
+            }
+            const hookId = hookPath.split(/[\\/]/).filter(Boolean).pop() || "";
+            const rawEvent = hookJson.event;
+            const cursorEvent = typeof rawEvent === "string"
+                ? CursorAdapter.AIR_TO_CURSOR_EVENT[rawEvent]
+                : undefined;
+            if (!cursorEvent) {
+                if (rawEvent !== undefined) {
+                    console.warn(`warning: hook "${hookId}" declares unrecognized event "${String(rawEvent)}" — skipping registration in .cursor/hooks.json. ` +
+                        `Supported events: ${this.supportedEventList()}.`);
+                }
+                continue;
+            }
+            if (!hookJson.command)
+                continue;
+            const hookRelDir = relative(targetDir, hookPath);
+            const command = this.buildHookCommand(hookRelDir, hookPath, hookJson.command, hookJson.args);
+            const hookEntry = { command };
+            if (typeof hookJson.matcher === "string" && hookJson.matcher.length > 0) {
+                hookEntry.matcher = hookJson.matcher;
+            }
+            if (hookJson.timeout_seconds != null) {
+                hookEntry.timeout = hookJson.timeout_seconds;
+            }
+            hookEntry._air_hook_id = hookId;
+            if (!hooks[cursorEvent]) {
+                hooks[cursorEvent] = [];
+            }
+            hooks[cursorEvent].push(hookEntry);
+        }
+        if (Object.keys(hooks).length > 0) {
+            config.hooks = hooks;
+            if (config.version === undefined)
+                config.version = 1;
+            this.writeJson(hooksPath, config);
+            return hooksPath;
+        }
+        // No hooks remain. Drop the now-empty `hooks` key; if nothing meaningful is
+        // left (only `version`, or the object is empty), delete the file instead of
+        // leaving a useless stub. Preserve any other user-authored top-level keys.
+        delete config.hooks;
+        const remaining = Object.keys(config).filter((k) => k !== "version");
+        if (remaining.length === 0) {
+            if (existsSync(hooksPath))
+                rmSync(hooksPath, { force: true });
+            return null;
+        }
+        this.writeJson(hooksPath, config);
+        return hooksPath;
+    }
+    isManagedHookEntry(entry, managedHookIds) {
+        if (!entry || typeof entry !== "object")
+            return false;
+        const id = entry._air_hook_id;
+        if (typeof id !== "string")
+            return false;
+        return managedHookIds.has(id);
+    }
+    /**
+     * Remove `mcpIds` from `mcpServers` in `.cursor/mcp.json`, preserving
+     * user-authored entries and other top-level fields. Returns the path of the
+     * file that was rewritten, or null if the file became empty and was deleted.
+     */
+    pruneCursorMcpConfig(mcpPath, mcpIds) {
+        const config = this.readJson(mcpPath);
+        const servers = config.mcpServers ?? {};
+        for (const id of mcpIds)
+            delete servers[id];
+        if (Object.keys(servers).length > 0) {
+            config.mcpServers = servers;
+        }
+        else {
+            delete config.mcpServers;
+        }
+        if (Object.keys(config).length === 0) {
+            rmSync(mcpPath, { force: true });
+            return null;
+        }
+        this.writeJson(mcpPath, config);
+        return mcpPath;
+    }
+    /**
+     * Remove AIR-managed hook entries (matched by `_air_hook_id` ∈
+     * `managedHookIds`) from `.cursor/hooks.json`, preserving user-authored
+     * entries and other top-level fields. Returns the path of the file that was
+     * rewritten, or null if no hooks remain and the file was deleted.
+     */
+    pruneCursorHooksConfig(hooksPath, managedHookIds) {
+        const config = this.readJson(hooksPath);
+        const hooks = config.hooks ?? {};
+        for (const event of Object.keys(hooks)) {
+            const entries = hooks[event];
+            if (!Array.isArray(entries))
+                continue;
+            const kept = entries.filter((e) => !this.isManagedHookEntry(e, managedHookIds));
+            if (kept.length === 0) {
+                delete hooks[event];
+            }
+            else {
+                hooks[event] = kept;
+            }
+        }
+        if (Object.keys(hooks).length > 0) {
+            config.hooks = hooks;
+            this.writeJson(hooksPath, config);
+            return hooksPath;
+        }
+        delete config.hooks;
+        const remaining = Object.keys(config).filter((k) => k !== "version");
+        if (remaining.length === 0) {
+            rmSync(hooksPath, { force: true });
+            return null;
+        }
+        this.writeJson(hooksPath, config);
+        return hooksPath;
+    }
+    /**
+     * Build a shell command string from HOOK.json's command and args fields.
+     *
+     * Hook authors write paths relative to their own hook directory. Cursor
+     * invokes hooks with a working directory that is not guaranteed to be the
+     * project root, so hook-relative paths are anchored to the repository root
+     * via `"$(git rev-parse --show-toplevel)/.cursor/hooks/<id>/<path>"`. The
+     * double quotes keep the path safe for project directories with spaces.
+     *
+     *   - `command` is anchored if it starts with `./` (explicit hook-relative).
+     *   - Each `args` entry is anchored if it looks like a path AND the file
+     *     exists under the hook's installed directory.
+     *
+     * Args that are not rewritten and contain shell metacharacters are
+     * single-quoted for safety.
+     */
+    buildHookCommand(hookRelDir, hookAbsDir, command, args) {
+        let cmd;
+        if (command.startsWith("./")) {
+            cmd = this.anchorHookPath(join(hookRelDir, command.slice(2)));
+        }
+        else {
+            cmd = command;
+        }
+        if (args && args.length > 0) {
+            const rewritten = args.map((a) => this.rewriteHookArgPath(a, hookRelDir, hookAbsDir));
+            const escaped = rewritten.map((r) => r.anchored
+                ? this.anchorHookPath(r.value)
+                : /[\s;&|`$"'\\]/.test(r.value)
+                    ? `'${r.value.replace(/'/g, "'\\''")}'`
+                    : r.value);
+            cmd += " " + escaped.join(" ");
+        }
+        return cmd;
+    }
+    /**
+     * Wrap a project-root-relative path in `"$(git rev-parse --show-toplevel)/..."`
+     * so the resolved path is independent of the cwd at hook invocation. Double
+     * quotes are required so the command substitution runs; characters that are
+     * special inside double quotes (`$`, `` ` ``, `"`, `\`) are escaped in the
+     * path component so an unusual hook ID or filename can't break out of the
+     * quoting.
+     */
+    anchorHookPath(projectRelPath) {
+        const safe = projectRelPath.replace(/[\\"$`]/g, "\\$&");
+        return `"$(git rev-parse --show-toplevel)/${safe}"`;
+    }
+    /**
+     * If `arg` is a hook-relative path that points at a real file under the
+     * hook's installed directory, return its project-root-relative form
+     * (`.cursor/hooks/<id>/<path>`) flagged as anchored so the caller can wrap it.
+     * Otherwise return `arg` unchanged with `anchored: false`.
+     */
+    rewriteHookArgPath(arg, hookRelDir, hookAbsDir) {
+        if (!arg)
+            return { value: arg, anchored: false };
+        if (arg.startsWith("-") || arg.startsWith("/") || arg.startsWith("~")) {
+            return { value: arg, anchored: false };
+        }
+        const hasExplicitPrefix = arg.startsWith("./");
+        const candidate = hasExplicitPrefix ? arg.slice(2) : arg;
+        if (!hasExplicitPrefix && !candidate.includes("/")) {
+            return { value: arg, anchored: false };
+        }
+        if (!existsSync(join(hookAbsDir, candidate))) {
+            return { value: arg, anchored: false };
+        }
+        return { value: join(hookRelDir, candidate), anchored: true };
+    }
+    /** Human-readable list of the supported AIR hook event names (snake_case only). */
+    supportedEventList() {
+        return CursorAdapter.AIR_EVENT_NAMES.join(", ");
+    }
+    copyDirRecursive(src, dest) {
+        mkdirSync(dest, { recursive: true });
+        for (const entry of readdirSync(src)) {
+            const srcPath = join(src, entry);
+            const destPath = join(dest, entry);
+            if (statSync(srcPath).isDirectory()) {
+                this.copyDirRecursive(srcPath, destPath);
+            }
+            else {
+                copyFileSync(srcPath, destPath);
+            }
+        }
+    }
+}
+//# sourceMappingURL=cursor-adapter.js.map