@cleocode/adapters 2026.4.30 → 2026.4.35

package/dist/providers/cursor/adapter.js

@@ -0,0 +1,151 @@
+/**
+ * Cursor Adapter
+ *
+ * Main CLEOProviderAdapter implementation for Cursor AI code editor.
+ * Provides install capabilities for CLEO integration. Hooks and spawn
+ * are not supported since Cursor lacks CLI-based lifecycle events
+ * and subagent spawning.
+ *
+ * @task T5240
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CursorHookProvider } from './hooks.js';
+import { CursorInstallProvider } from './install.js';
+/**
+ * CLEO provider adapter for Cursor AI code editor.
+ *
+ * Bridges CLEO's adapter system with Cursor's capabilities:
+ * - Install: Manages .cursorrules and .cursor/rules/cleo.mdc rule files
+ * - Hooks: Stub provider (Cursor has no lifecycle event system)
+ * - Spawn: Not supported (Cursor has no CLI for subagent spawning)
+ *
+ * @remarks
+ * Cursor is a GUI-based editor, so many CLI-oriented capabilities
+ * (spawn, transport, task sync, context monitor) are unsupported.
+ * Integration is primarily through instruction rule files placed in
+ * `.cursor/rules/` (modern MDC format) and `.cursorrules` (legacy).
+ */
+export class CursorAdapter {
+    /** Unique provider identifier. */
+    id = 'cursor';
+    /** Human-readable provider name. */
+    name = 'Cursor';
+    /** Adapter version string. */
+    version = '1.0.0';
+    /** Declared capabilities for this provider. */
+    capabilities = {
+        supportsHooks: true,
+        // 10/16 canonical events — derived from getProviderHookProfile('cursor') in CAAMP 1.9.1.
+        // PermissionRequest, PreModel, PostModel, PostCompact, Notification, ConfigChange are
+        // not supported by Cursor's hook system.
+        supportedHookEvents: [
+            'SessionStart',
+            'SessionEnd',
+            'PromptSubmit',
+            'ResponseComplete',
+            'PreToolUse',
+            'PostToolUse',
+            'PostToolUseFailure',
+            'SubagentStart',
+            'SubagentStop',
+            'PreCompact',
+        ],
+        supportsSpawn: false,
+        supportsInstall: true,
+        supportsInstructionFiles: true,
+        instructionFilePattern: '.cursor/rules/*.mdc',
+        supportsContextMonitor: false,
+        supportsStatusline: false,
+        supportsProviderPaths: true,
+        supportsTransport: false,
+        supportsTaskSync: false,
+    };
+    /** Hook provider for CAAMP event mapping. */
+    hooks;
+    /** Install provider for managing rule files. */
+    install;
+    /** Project directory this adapter was initialized with, or null. */
+    projectDir = null;
+    /** Whether {@link initialize} has been called. */
+    initialized = false;
+    constructor() {
+        this.hooks = new CursorHookProvider();
+        this.install = new CursorInstallProvider();
+    }
+    /**
+     * Initialize the adapter for a given project directory.
+     *
+     * @param projectDir - Root directory of the project
+     */
+    async initialize(projectDir) {
+        this.projectDir = projectDir;
+        this.initialized = true;
+    }
+    /**
+     * Dispose the adapter and clean up resources.
+     */
+    async dispose() {
+        if (this.hooks.isRegistered()) {
+            await this.hooks.unregisterNativeHooks();
+        }
+        this.initialized = false;
+        this.projectDir = null;
+    }
+    /**
+     * Run a health check to verify Cursor is accessible.
+     *
+     * Checks:
+     * 1. Adapter has been initialized
+     * 2. .cursor/ configuration directory exists in the project
+     * 3. CURSOR_EDITOR env var is set
+     *
+     * @returns Health status with details about each check
+     */
+    async healthCheck() {
+        const details = {};
+        if (!this.initialized) {
+            return {
+                healthy: false,
+                provider: this.id,
+                details: { error: 'Adapter not initialized' },
+            };
+        }
+        // Check for Cursor config directory in the project
+        let configExists = false;
+        if (this.projectDir) {
+            const cursorConfigDir = join(this.projectDir, '.cursor');
+            configExists = existsSync(cursorConfigDir);
+            details.configDirExists = configExists;
+        }
+        // Check for CURSOR_EDITOR env var
+        const editorEnvSet = process.env.CURSOR_EDITOR !== undefined;
+        details.editorEnvSet = editorEnvSet;
+        // Check for legacy .cursorrules file
+        if (this.projectDir) {
+            const legacyRulesExist = existsSync(join(this.projectDir, '.cursorrules'));
+            details.legacyRulesExist = legacyRulesExist;
+        }
+        // Healthy if we detect Cursor presence (config dir or env var)
+        const healthy = configExists || editorEnvSet;
+        details.detected = healthy;
+        return {
+            healthy,
+            provider: this.id,
+            details,
+        };
+    }
+    /**
+     * Check whether the adapter has been initialized.
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get the project directory this adapter was initialized with.
+     */
+    getProjectDir() {
+        return this.projectDir;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/providers/cursor/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/providers/cursor/adapter.ts"],"names":[],"mappings":"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"}

package/dist/providers/cursor/hooks.js

@@ -0,0 +1,208 @@
+/**
+ * Cursor Hook Provider
+ *
+ * Maps Cursor's native hook events to CAAMP canonical hook events.
+ * Cursor supports 10 of 16 canonical events through its config-based hook system.
+ *
+ * Event translation uses CAAMP normalizer APIs:
+ * - `toCanonical(nativeName, 'cursor')` for runtime event name resolution
+ * - `getSupportedEvents('cursor')` to enumerate supported canonical events
+ * - `getProviderHookProfile('cursor')` for the full provider profile
+ *
+ * Cursor uses camelCase native event names (e.g. `sessionStart`, `preToolUse`).
+ * Hooks are configured via `.cursor/hooks.json`. Supported handler types:
+ * command, prompt.
+ *
+ * Unsupported events: PermissionRequest, PreModel, PostModel, PostCompact,
+ * Notification, ConfigChange.
+ *
+ * @task T165
+ * @epic T134
+ */
+/** CAAMP provider identifier for Cursor. */
+const PROVIDER_ID = 'cursor';
+/**
+ * Fallback map from Cursor native event names to CAAMP canonical names.
+ *
+ * Derived from `getProviderHookProfile('cursor').mappings` in CAAMP 1.9.1.
+ * Covers all 10 supported events. PermissionRequest, PreModel, PostModel,
+ * PostCompact, Notification, and ConfigChange are not supported by Cursor.
+ *
+ * Cursor uses camelCase names while CAAMP canonical names are PascalCase.
+ */
+const CURSOR_EVENT_MAP = {
+    // CAAMP: toNative('SessionStart',       'cursor') = 'sessionStart'
+    sessionStart: 'SessionStart',
+    // CAAMP: toNative('SessionEnd',         'cursor') = 'sessionEnd'
+    sessionEnd: 'SessionEnd',
+    // CAAMP: toNative('PromptSubmit',       'cursor') = 'beforeSubmitPrompt'
+    beforeSubmitPrompt: 'PromptSubmit',
+    // CAAMP: toNative('ResponseComplete',   'cursor') = 'stop'
+    stop: 'ResponseComplete',
+    // CAAMP: toNative('PreToolUse',         'cursor') = 'preToolUse'
+    preToolUse: 'PreToolUse',
+    // CAAMP: toNative('PostToolUse',        'cursor') = 'postToolUse'
+    postToolUse: 'PostToolUse',
+    // CAAMP: toNative('PostToolUseFailure', 'cursor') = 'postToolUseFailure'
+    postToolUseFailure: 'PostToolUseFailure',
+    // CAAMP: toNative('SubagentStart',      'cursor') = 'subagentStart'
+    subagentStart: 'SubagentStart',
+    // CAAMP: toNative('SubagentStop',       'cursor') = 'subagentStop'
+    subagentStop: 'SubagentStop',
+    // CAAMP: toNative('PreCompact',         'cursor') = 'preCompact'
+    preCompact: 'PreCompact',
+};
+/**
+ * Hook provider for Cursor.
+ *
+ * Cursor registers hooks via its config system at `.cursor/hooks.json`.
+ * Supported handler types: command, prompt.
+ *
+ * CAAMP 1.9.1 reveals Cursor supports 10 of 16 canonical events. Previously
+ * this provider was a no-op stub. It now provides full event mapping and CAAMP
+ * normalizer integration.
+ *
+ * Event mapping is based on `getProviderHookProfile('cursor')` from CAAMP 1.9.1.
+ * Async accessors (`getSupportedCanonicalEvents`, `getProviderProfile`) call
+ * CAAMP directly when available.
+ *
+ * Since hooks are registered through the config system (managed by the install
+ * provider), `registerNativeHooks` and `unregisterNativeHooks` track registration
+ * state without performing filesystem operations.
+ *
+ * @remarks
+ * This provider was originally a no-op stub. It now provides full event
+ * mapping for all 10 canonical events supported by Cursor, plus CAAMP
+ * normalizer integration via async accessors. Registration state is
+ * tracked in-memory because Cursor manages hooks through its own config.
+ *
+ * @task T165
+ * @epic T134
+ */
+export class CursorHookProvider {
+    /** Whether hooks have been registered for the current session. */
+    registered = false;
+    /**
+     * Map a Cursor native event name to a CAAMP canonical hook event name.
+     *
+     * Looks up the native event name in the map derived from
+     * `getProviderHookProfile('cursor').mappings` (CAAMP 1.9.1). Cursor uses
+     * camelCase names (e.g. "preToolUse", "sessionStart").
+     *
+     * Returns null for unsupported events (PermissionRequest, PreModel,
+     * PostModel, PostCompact, Notification, ConfigChange).
+     *
+     * @param providerEvent - Cursor native event name (e.g. "preToolUse", "sessionStart")
+     * @returns CAAMP canonical event name, or null if unmapped
+     * @task T165
+     */
+    mapProviderEvent(providerEvent) {
+        return CURSOR_EVENT_MAP[providerEvent] ?? null;
+    }
+    /**
+     * Register native hooks for a project.
+     *
+     * For Cursor, hooks are registered via the config system
+     * (`.cursor/hooks.json`), managed by the install provider.
+     * This method marks hooks as registered without performing filesystem operations.
+     *
+     * Iterating supported events is handled at install time using
+     * `getSupportedCanonicalEvents()` to enumerate all 10 supported hooks.
+     *
+     * @param _projectDir - Project directory (unused; Cursor config manages registration)
+     * @task T165
+     */
+    async registerNativeHooks(_projectDir) {
+        this.registered = true;
+    }
+    /**
+     * Unregister native hooks.
+     *
+     * For Cursor, this is a no-op since hooks are managed through the config
+     * system. Unregistration happens via the install provider's uninstall method.
+     *
+     * @task T165
+     */
+    async unregisterNativeHooks() {
+        this.registered = false;
+    }
+    /**
+     * Check whether hooks have been registered via `registerNativeHooks`.
+     */
+    isRegistered() {
+        return this.registered;
+    }
+    /**
+     * Get the native→canonical event mapping for introspection and debugging.
+     *
+     * Returns the map derived from `getProviderHookProfile('cursor').mappings`
+     * (CAAMP 1.9.1). Use `getSupportedCanonicalEvents()` to enumerate canonical
+     * names via live CAAMP APIs.
+     *
+     * @returns Immutable record of native event name → canonical event name
+     */
+    getEventMap() {
+        return { ...CURSOR_EVENT_MAP };
+    }
+    /**
+     * Enumerate supported canonical events via CAAMP's `getSupportedEvents()`.
+     *
+     * Calls `getSupportedEvents('cursor')` from the CAAMP normalizer to get the
+     * authoritative list. Cursor supports 10 of 16 canonical events. Falls back
+     * to the values of the static event map when CAAMP is unavailable at runtime.
+     *
+     * @returns Array of CAAMP canonical event names supported by Cursor
+     * @task T165
+     */
+    async getSupportedCanonicalEvents() {
+        try {
+            const { getSupportedEvents } = await import('@cleocode/caamp');
+            return getSupportedEvents(PROVIDER_ID);
+        }
+        catch {
+            return [...new Set(Object.values(CURSOR_EVENT_MAP))];
+        }
+    }
+    /**
+     * Retrieve the full provider hook profile from CAAMP.
+     *
+     * Calls `getProviderHookProfile('cursor')` from the CAAMP normalizer to
+     * get the complete profile: hook system type (`config`), config path
+     * (`.cursor/hooks.json`), handler types (command, prompt), and all event
+     * mappings. Returns null when CAAMP is unavailable at runtime.
+     *
+     * @returns Provider hook profile or null if CAAMP is unavailable
+     * @task T165
+     */
+    async getProviderProfile() {
+        try {
+            const { getProviderHookProfile } = await import('@cleocode/caamp');
+            return getProviderHookProfile(PROVIDER_ID) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Translate a CAAMP canonical event to its Cursor native name via CAAMP.
+     *
+     * Calls `toNative(canonical, 'cursor')` from the CAAMP normalizer.
+     * Returns null for unsupported events or when CAAMP is unavailable.
+     *
+     * @param canonical - CAAMP canonical event name (e.g. "PreToolUse")
+     * @returns Cursor native event name (e.g. "preToolUse") or null
+     * @task T165
+     */
+    async toNativeEvent(canonical) {
+        try {
+            const { toNative } = await import('@cleocode/caamp');
+            return toNative(canonical, PROVIDER_ID);
+        }
+        catch {
+            // Invert the static map as fallback
+            const entry = Object.entries(CURSOR_EVENT_MAP).find(([, v]) => v === canonical);
+            return entry?.[0] ?? null;
+        }
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/providers/cursor/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/providers/cursor/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,4CAA4C;AAC5C,MAAM,WAAW,GAAG,QAAiB,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,gBAAgB,GAA2B;IAC/C,mEAAmE;IACnE,YAAY,EAAE,cAAc;IAC5B,iEAAiE;IACjE,UAAU,EAAE,YAAY;IACxB,yEAAyE;IACzE,kBAAkB,EAAE,cAAc;IAClC,2DAA2D;IAC3D,IAAI,EAAE,kBAAkB;IACxB,iEAAiE;IACjE,UAAU,EAAE,YAAY;IACxB,kEAAkE;IAClE,WAAW,EAAE,aAAa;IAC1B,yEAAyE;IACzE,kBAAkB,EAAE,oBAAoB;IACxC,oEAAoE;IACpE,aAAa,EAAE,eAAe;IAC9B,mEAAmE;IACnE,YAAY,EAAE,cAAc;IAC5B,iEAAiE;IACjE,UAAU,EAAE,YAAY;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,kBAAkB;IAC7B,kEAAkE;IAC1D,UAAU,GAAG,KAAK,CAAC;IAE3B;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,aAAqB;QACpC,OAAO,gBAAgB,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC;IACjD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,mBAAmB,CAAC,WAAmB;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,qBAAqB;QACzB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW;QACT,OAAO,EAAE,GAAG,gBAAgB,EAAE,CAAC;IACjC,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,2BAA2B;QAC/B,IAAI,CAAC;YACH,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;YAC/D,OAAO,kBAAkB,CAAC,WAAW,CAAa,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,kBAAkB;QACtB,IAAI,CAAC;YACH,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;YACnE,OAAO,sBAAsB,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,aAAa,CAAC,SAAiB;QACnC,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;YACrD,OAAO,QAAQ,CAAC,SAA2C,EAAE,WAAW,CAAC,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;YACpC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;YAChF,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAC5B,CAAC;IACH,CAAC;CACF"}

package/dist/providers/cursor/index.js

@@ -0,0 +1,36 @@
+/**
+ * @packageDocumentation
+ *
+ * CLEO provider adapter for Cursor AI code editor.
+ * Default export is the adapter class for dynamic loading by AdapterManager.
+ *
+ * @task T5240
+ */
+import { CursorAdapter } from './adapter.js';
+export { CursorAdapter } from './adapter.js';
+export { CursorHookProvider } from './hooks.js';
+export { CursorInstallProvider } from './install.js';
+export default CursorAdapter;
+/**
+ * Factory function for creating adapter instances.
+ * Used by AdapterManager's dynamic import fallback.
+ *
+ * @remarks
+ * This is the primary entry point for dynamic adapter loading.
+ * AdapterManager calls this function when it resolves the cursor
+ * provider via its import-based discovery mechanism.
+ *
+ * @returns A new {@link CursorAdapter} instance ready for initialization
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@cleocode/adapters/providers/cursor';
+ *
+ * const adapter = createAdapter();
+ * await adapter.initialize('/path/to/project');
+ * ```
+ */
+export function createAdapter() {
+    return new CursorAdapter();
+}
+//# sourceMappingURL=index.js.map

package/dist/providers/cursor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/cursor/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,eAAe,aAAa,CAAC;AAE7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,aAAa,EAAE,CAAC;AAC7B,CAAC"}

package/dist/providers/cursor/install.js

@@ -0,0 +1,180 @@
+/**
+ * Cursor Install Provider
+ *
+ * Handles CLEO installation into Cursor environments:
+ * - Ensures .cursorrules has CLEO @-references (legacy format)
+ * - Creates .cursor/rules/cleo.mdc with CLEO references (modern format)
+ *
+ * Cursor supports two instruction file formats:
+ * 1. Legacy: .cursorrules (flat file, project root)
+ * 2. Modern: .cursor/rules/*.mdc (MDC format, per-rule files)
+ *
+ * This provider writes to both for maximum compatibility.
+ *
+ * @task T5240
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Lines that should appear in instruction files to reference CLEO. */
+const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+/**
+ * Install provider for Cursor.
+ *
+ * Manages CLEO's integration with Cursor by:
+ * 1. Creating/updating .cursorrules with @-references (legacy)
+ * 2. Creating .cursor/rules/cleo.mdc with @-references (modern)
+ *
+ * @remarks
+ * Installation is idempotent and writes to both instruction file formats
+ * for maximum compatibility. The legacy `.cursorrules` file is only modified
+ * if it already exists (never created from scratch). The modern MDC file
+ * is always created or updated to ensure Cursor's rule engine picks it up.
+ */
+export class CursorInstallProvider {
+    /**
+     * Install CLEO into a Cursor project.
+     *
+     * @param options - Installation options including project directory
+     * @returns Result describing what was installed
+     */
+    async install(options) {
+        const { projectDir } = options;
+        const installedAt = new Date().toISOString();
+        let instructionFileUpdated = false;
+        const details = {};
+        // Step 1: Ensure instruction files have @-references
+        instructionFileUpdated = this.updateInstructionFiles(projectDir);
+        if (instructionFileUpdated) {
+            details.instructionFiles = this.getUpdatedFileList(projectDir);
+        }
+        return {
+            success: true,
+            installedAt,
+            instructionFileUpdated,
+            details,
+        };
+    }
+    /**
+     * Uninstall CLEO from the current Cursor project.
+     *
+     * Does not remove instruction file references (they are harmless if CLEO is not present).
+     */
+    async uninstall() { }
+    /**
+     * Check whether CLEO is installed in the current environment.
+     *
+     * Checks for .cursor/rules/cleo.mdc or .cursorrules with CLEO references.
+     */
+    async isInstalled() {
+        const mdcPath = join(process.cwd(), '.cursor', 'rules', 'cleo.mdc');
+        if (existsSync(mdcPath)) {
+            return true;
+        }
+        const rulesPath = join(process.cwd(), '.cursorrules');
+        if (existsSync(rulesPath)) {
+            try {
+                const content = readFileSync(rulesPath, 'utf-8');
+                if (INSTRUCTION_REFERENCES.some((ref) => content.includes(ref))) {
+                    return true;
+                }
+            }
+            catch {
+                // Fall through
+            }
+        }
+        return false;
+    }
+    /**
+     * Ensure instruction files contain @-references to CLEO.
+     *
+     * Updates .cursorrules (legacy) and creates .cursor/rules/cleo.mdc (modern).
+     *
+     * @param projectDir - Project root directory
+     */
+    async ensureInstructionReferences(projectDir) {
+        this.updateInstructionFiles(projectDir);
+    }
+    /**
+     * Update instruction files with CLEO @-references.
+     *
+     * Handles both legacy (.cursorrules) and modern (.cursor/rules/cleo.mdc) formats.
+     *
+     * @returns true if any file was created or modified
+     */
+    updateInstructionFiles(projectDir) {
+        let updated = false;
+        // Update legacy .cursorrules if it exists
+        if (this.updateLegacyRules(projectDir)) {
+            updated = true;
+        }
+        // Create/update modern .cursor/rules/cleo.mdc
+        if (this.updateModernRules(projectDir)) {
+            updated = true;
+        }
+        return updated;
+    }
+    /**
+     * Update legacy .cursorrules file with @-references.
+     * Only modifies the file if it already exists (does not create it).
+     *
+     * @returns true if the file was modified
+     */
+    updateLegacyRules(projectDir) {
+        const rulesPath = join(projectDir, '.cursorrules');
+        if (!existsSync(rulesPath)) {
+            return false;
+        }
+        let content = readFileSync(rulesPath, 'utf-8');
+        const missingRefs = INSTRUCTION_REFERENCES.filter((ref) => !content.includes(ref));
+        if (missingRefs.length === 0) {
+            return false;
+        }
+        const separator = content.endsWith('\n') ? '' : '\n';
+        content = content + separator + missingRefs.join('\n') + '\n';
+        writeFileSync(rulesPath, content, 'utf-8');
+        return true;
+    }
+    /**
+     * Create or update .cursor/rules/cleo.mdc with CLEO references.
+     *
+     * MDC (Markdown Component) format is Cursor's modern rule file format.
+     * Each .mdc file in .cursor/rules/ is loaded as a rule set.
+     *
+     * @returns true if the file was created or modified
+     */
+    updateModernRules(projectDir) {
+        const rulesDir = join(projectDir, '.cursor', 'rules');
+        const mdcPath = join(rulesDir, 'cleo.mdc');
+        const expectedContent = [
+            '---',
+            'description: CLEO task management protocol references',
+            'globs: "**/*"',
+            'alwaysApply: true',
+            '---',
+            '',
+            ...INSTRUCTION_REFERENCES,
+            '',
+        ].join('\n');
+        if (existsSync(mdcPath)) {
+            const existing = readFileSync(mdcPath, 'utf-8');
+            if (existing === expectedContent) {
+                return false;
+            }
+        }
+        mkdirSync(rulesDir, { recursive: true });
+        writeFileSync(mdcPath, expectedContent, 'utf-8');
+        return true;
+    }
+    /**
+     * Get list of instruction files that were updated.
+     */
+    getUpdatedFileList(projectDir) {
+        const files = [];
+        if (existsSync(join(projectDir, '.cursorrules'))) {
+            files.push(join(projectDir, '.cursorrules'));
+        }
+        files.push(join(projectDir, '.cursor', 'rules', 'cleo.mdc'));
+        return files;
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/providers/cursor/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../../src/providers/cursor/install.ts"],"names":[],"mappings":"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"}

package/dist/providers/cursor/spawn.js

@@ -0,0 +1,59 @@
+/**
+ * Cursor Spawn Provider
+ *
+ * Cursor is a GUI-based AI code editor and does not support
+ * CLI-based subagent spawning. This provider implements
+ * the AdapterSpawnProvider interface with appropriate rejections.
+ *
+ * @task T5240
+ */
+/**
+ * Spawn provider for Cursor.
+ *
+ * Cursor does not support subagent spawning via CLI. The adapter
+ * declares supportsSpawn: false in its capabilities. All methods
+ * either reject or return empty results.
+ */
+export class CursorSpawnProvider {
+    /**
+     * Check if Cursor supports spawning subagents.
+     *
+     * @returns false (Cursor does not support CLI spawning)
+     */
+    async canSpawn() {
+        return false;
+    }
+    /**
+     * Attempt to spawn a subagent via Cursor.
+     *
+     * Always throws because Cursor does not support subagent spawning.
+     * Callers should check canSpawn() before calling this method.
+     *
+     * @param _context - Unused; spawning is not supported
+     * @throws Error explaining that Cursor does not support subagent spawning
+     */
+    async spawn(_context) {
+        throw new Error('Cursor does not support subagent spawning. ' +
+            'Cursor is a GUI-based editor without CLI subagent capabilities. ' +
+            'Use a provider that supports spawning (e.g., Claude Code or OpenCode).');
+    }
+    /**
+     * List running Cursor subagent processes.
+     *
+     * @returns Empty array (no processes can be spawned)
+     */
+    async listRunning() {
+        return [];
+    }
+    /**
+     * Terminate a Cursor subagent process.
+     *
+     * No-op because Cursor cannot spawn processes.
+     *
+     * @param _instanceId - Unused; no processes to terminate
+     */
+    async terminate(_instanceId) {
+        // No-op: Cursor does not spawn processes.
+    }
+}
+//# sourceMappingURL=spawn.js.map

package/dist/providers/cursor/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../../src/providers/cursor/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACZ,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,CAAC,QAAsB;QAChC,MAAM,IAAI,KAAK,CACb,6CAA6C;YAC3C,kEAAkE;YAClE,wEAAwE,CAC3E,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CAAC,WAAmB;QACjC,0CAA0C;IAC5C,CAAC;CACF"}