@pulsemcp/air-adapter-cursor 0.8.0

package/README.md

@@ -0,0 +1,84 @@
+# @pulsemcp/air-adapter-cursor
+
+AIR adapter extension for the [Cursor CLI](https://cursor.com/docs/cli) (`cursor-agent`). Translates AIR artifacts into Cursor's native formats and prepares working directories for agent sessions.
+
+## Installation
+
+```bash
+npm install @pulsemcp/air-adapter-cursor
+```
+
+## Usage
+
+### With the AIR CLI
+
+```bash
+# Install the adapter globally alongside the CLI
+npm install -g @pulsemcp/air-cli @pulsemcp/air-adapter-cursor
+
+# Start a Cursor session
+air start cursor --root web-app
+```
+
+### Programmatic
+
+```typescript
+import { resolveArtifacts } from "@pulsemcp/air-core";
+import { CursorAdapter } from "@pulsemcp/air-adapter-cursor";
+
+const artifacts = await resolveArtifacts("./air.json");
+const adapter = new CursorAdapter();
+
+// Prepare a working directory for a Cursor session
+const session = await adapter.prepareSession(artifacts, "./my-project", {
+  root: artifacts.roots["web-app"],
+});
+
+// session.configFiles  — [] (secrets are Cursor-native ${env:VAR}, see "Secrets" below)
+// session.skillPaths   — skill dirs created in .cursor/skills/
+// session.hookPaths    — hook dirs created in .cursor/hooks/
+// session.startCommand — { command: "cursor-agent", args: [], cwd: "..." }
+```
+
+## What `prepareSession()` does
+
+1. **Writes `.cursor/mcp.json`** — translates AIR MCP server configs into a top-level `mcpServers` map. User-authored servers and top-level keys are preserved; only AIR-owned keys are replaced.
+2. **Writes `.cursor/hooks.json`** — registers path-based hooks under `hooks.<event>` with a required `version: 1`. AIR-owned entries are tagged with `_air_hook_id`; user-authored hooks are preserved.
+3. **Injects skills** — copies `SKILL.md` files and associated content into `.cursor/skills/{name}/`, where Cursor discovers them.
+4. **Injects hooks** — copies hook directories into `.cursor/hooks/{name}/` and registers their command in `hooks.json`, anchored to the repo root.
+5. **Copies references** — attaches referenced documents into `{artifact}/references/`.
+6. **Respects local priority** — if a skill or hook directory already exists in the target, it is not overwritten.
+
+## Translation Details
+
+| AIR Format | Cursor Format |
+|------------|---------------|
+| `mcp.json` (flat map with `type`, `title`, `description`) | `mcpServers.<name>` entries in `.cursor/mcp.json` (metadata stripped) |
+| `stdio` servers | `{ command, args, env }` |
+| `sse` / `streamable-http` servers | `{ url, headers }` (Cursor auto-detects transport from the URL) |
+| Any `${VAR}` ref in `command` / `args` / `env` / `url` / `headers` | rewritten to Cursor-native `${env:VAR}` (anywhere in the string) |
+| Skills (`SKILL.md` + content) | `.cursor/skills/{name}/` |
+| Hooks (`HOOK.json` + scripts) | `.cursor/hooks/{name}/` + `hooks.<event>` registration in `.cursor/hooks.json` |
+| Hook events `session_start`, `session_end`, `pre_tool_call`, `post_tool_call`, `user_prompt_submit`, `stop`, `subagent_stop`, `pre_compact` | Cursor `sessionStart`, `sessionEnd`, `preToolUse`, `postToolUse`, `beforeSubmitPrompt`, `stop`, `subagentStop`, `preCompact` |
+| References | `{artifact}/references/` |
+
+## Secrets
+
+Cursor natively expands `${env:VAR}` references in `mcp.json` values. Instead of writing AIR `${VAR}` placeholders, the adapter rewrites every AIR `${VAR}` reference to Cursor's **`${env:VAR}`** form at translation time:
+
+- `env: { GITHUB_TOKEN: "${GITHUB_TOKEN}" }` → `env: { GITHUB_TOKEN: "${env:GITHUB_TOKEN}" }`
+- `headers: { Authorization: "Bearer ${API_TOKEN}" }` → `headers: { Authorization: "Bearer ${env:API_TOKEN}" }`
+- `env: { KEY: "${OTHER}" }` (renamed) → `env: { KEY: "${env:OTHER}" }`
+
+Cursor expands these from the host environment at launch. As a result, `prepareSession()` returns an **empty `configFiles` array** — there is no AIR `${VAR}` left for secret transforms to post-process.
+
+**No unforwardable shapes.** Because Cursor's `${env:VAR}` interpolation works *anywhere in a string*, every secret reference forwards cleanly — whole-value, partial, and renamed alike. The adapter therefore never warns about secrets. Cursor's own built-in interpolation tokens (`${userHome}`, `${workspaceFolder}`, `${workspaceFolderBasename}`, `${pathSeparator}`) and already-`${env:…}` references are left untouched so they are not double-wrapped.
+
+## Known gaps
+
+These AIR features have no static Cursor equivalent and are handled out of band:
+
+- **OAuth MCP servers** — AIR's detailed OAuth config (`clientId`/`scopes`/`redirectUri`/…) has no static `mcp.json` form. Cursor performs interactive OAuth via `cursor-agent mcp login <name>`.
+- **Plugins** — Cursor has no local plugin package an adapter can materialize. AIR 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.
+- **Subagent context** — Cursor has no `--append-system-prompt` flag, so subagent-root context is returned to the caller via `PreparedSession.subagentContext` rather than passed to the CLI.
+- **`notification` hook event** — AIR's `notification` event has no Cursor equivalent; hooks targeting it are skipped with a `console.warn`.

package/dist/cursor-adapter.d.ts

@@ -0,0 +1,225 @@
+import type { AgentAdapter, AgentSessionConfig, StartCommand, ResolvedArtifacts, RootEntry, McpServerEntry, PluginEntry, PrepareSessionOptions, PreparedSession, CleanSessionOptions, CleanSessionResult, LocalArtifacts } from "@pulsemcp/air-core";
+export declare class CursorAdapter implements AgentAdapter {
+    name: string;
+    displayName: string;
+    /**
+     * 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.
+     */
+    private static readonly AIR_TO_CURSOR_EVENT;
+    /** Canonical AIR snake_case event names with a Cursor mapping. */
+    private static readonly AIR_EVENT_NAMES;
+    isAvailable(): Promise<boolean>;
+    generateConfig(artifacts: ResolvedArtifacts, root?: RootEntry, _workDir?: string): AgentSessionConfig;
+    buildStartCommand(config: AgentSessionConfig): StartCommand;
+    /**
+     * 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.
+     */
+    prepareSession(artifacts: ResolvedArtifacts, targetDir: string, options?: PrepareSessionOptions): Promise<PreparedSession>;
+    /**
+     * 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.
+     */
+    listLocalArtifacts(targetDir: string): Promise<LocalArtifacts>;
+    /**
+     * 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.
+     */
+    cleanSession(targetDir: string, options?: CleanSessionOptions): Promise<CleanSessionResult>;
+    /**
+     * 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.
+     */
+    private mcpServerIdsPresent;
+    /**
+     * 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.
+     */
+    private hookEntriesPresent;
+    /**
+     * Resolve subagent roots from the root's default_subagent_roots.
+     * IDs are already qualified after composition-time canonicalization.
+     */
+    private resolveSubagentRoots;
+    /**
+     * Merge subagent roots' default_mcp_servers and default_skills into the
+     * parent's activated sets (union, preserving order with parent first).
+     */
+    private mergeSubagentArtifacts;
+    /**
+     * Build a system prompt section describing the subagent root dependencies.
+     */
+    private buildSubagentContext;
+    /**
+     * 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: Record<string, McpServerEntry>): Record<string, Record<string, unknown>>;
+    private translateMcpServer;
+    /**
+     * 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.
+     */
+    private toCursorVars;
+    /**
+     * 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: string, plugin: PluginEntry): Record<string, unknown>;
+    /**
+     * 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)
+     */
+    private resolveActivations;
+    /**
+     * 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.
+     */
+    private missingSourceDirMessage;
+    private formatPoolKeys;
+    /**
+     * Copy referenced documents into a references/ subdirectory of the target.
+     * `refIds` are qualified IDs (post-canonicalization).
+     */
+    private copyReferences;
+    /** Parse an existing JSON config, returning `{}` when absent/unparseable. */
+    private readJson;
+    private writeJson;
+    /**
+     * 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.
+     */
+    private writeCursorMcpConfig;
+    /**
+     * 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.
+     */
+    private writeCursorHooksConfig;
+    private isManagedHookEntry;
+    /**
+     * 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.
+     */
+    private pruneCursorMcpConfig;
+    /**
+     * 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.
+     */
+    private pruneCursorHooksConfig;
+    /**
+     * 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.
+     */
+    private buildHookCommand;
+    /**
+     * 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.
+     */
+    private anchorHookPath;
+    /**
+     * 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`.
+     */
+    private rewriteHookArgPath;
+    /** Human-readable list of the supported AIR hook event names (snake_case only). */
+    private supportedEventList;
+    private copyDirRecursive;
+}
+//# sourceMappingURL=cursor-adapter.d.ts.map

package/dist/cursor-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-adapter.d.ts","sourceRoot":"","sources":["../src/cursor-adapter.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EAEf,MAAM,oBAAoB,CAAC;AAsC5B,qBAAa,aAAc,YAAW,YAAY;IAChD,IAAI,SAAY;IAChB,WAAW,SAAY;IAEvB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAgCzC;IAEF,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CASrC;IAEI,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IASrC,cAAc,CACZ,SAAS,EAAE,iBAAiB,EAC5B,IAAI,CAAC,EAAE,SAAS,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,kBAAkB;IAmDrB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY;IAa3D;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,cAAc,CAClB,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAqM3B;;;;;OAKG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAIpE;;;;;;;;;;;;OAYG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA6G9B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAwB9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;;;;;;;;;;;OAaG;IACH,0BAA0B,CACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAQ1C,OAAO,CAAC,kBAAkB;IAgC1B;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;;OAQG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQ9E;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAgD1B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,cAAc;IAStB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAyBtB,6EAA6E;IAC7E,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,SAAS;IAKjB;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IA0B5B;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IA8F9B,OAAO,CAAC,kBAAkB;IAO1B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAkC9B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAKtB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAoB1B,mFAAmF;IACnF,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;CAYzB"}