@cleocode/adapters 2.0.0

package/src/providers/cursor/install.ts

@@ -0,0 +1,271 @@
+/**
+ * Cursor Install Provider
+ *
+ * Handles CLEO installation into Cursor environments:
+ * - Registers CLEO MCP server in .cursor/mcp.json
+ * - 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';
+import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+
+/** Lines that should appear in instruction files to reference CLEO. */
+const INSTRUCTION_REFERENCES = [
+  '@~/.cleo/templates/CLEO-INJECTION.md',
+  '@.cleo/memory-bridge.md',
+];
+
+/** MCP server registration key used in Cursor config. */
+const MCP_SERVER_KEY = 'cleo';
+
+/**
+ * Install provider for Cursor.
+ *
+ * Manages CLEO's integration with Cursor by:
+ * 1. Registering the CLEO MCP server in .cursor/mcp.json
+ * 2. Creating/updating .cursorrules with @-references (legacy)
+ * 3. Creating .cursor/rules/cleo.mdc with @-references (modern)
+ */
+export class CursorInstallProvider implements AdapterInstallProvider {
+  private installedProjectDir: string | null = null;
+
+  /**
+   * Install CLEO into a Cursor project.
+   *
+   * @param options - Installation options including project directory and MCP server path
+   * @returns Result describing what was installed
+   */
+  async install(options: InstallOptions): Promise<InstallResult> {
+    const { projectDir, mcpServerPath } = options;
+    const installedAt = new Date().toISOString();
+    let instructionFileUpdated = false;
+    let mcpRegistered = false;
+    const details: Record<string, unknown> = {};
+
+    // Step 1: Register MCP server in .cursor/mcp.json
+    if (mcpServerPath) {
+      mcpRegistered = this.registerMcpServer(projectDir, mcpServerPath);
+      if (mcpRegistered) {
+        details.mcpConfigPath = join(projectDir, '.cursor', 'mcp.json');
+      }
+    }
+
+    // Step 2: Ensure instruction files have @-references
+    instructionFileUpdated = this.updateInstructionFiles(projectDir);
+    if (instructionFileUpdated) {
+      details.instructionFiles = this.getUpdatedFileList(projectDir);
+    }
+
+    this.installedProjectDir = projectDir;
+
+    return {
+      success: true,
+      installedAt,
+      instructionFileUpdated,
+      mcpRegistered,
+      details,
+    };
+  }
+
+  /**
+   * Uninstall CLEO from the current Cursor project.
+   *
+   * Removes the MCP server registration from .cursor/mcp.json.
+   * Does not remove instruction file references (they are harmless if CLEO is not present).
+   */
+  async uninstall(): Promise<void> {
+    if (!this.installedProjectDir) return;
+
+    const mcpPath = join(this.installedProjectDir, '.cursor', 'mcp.json');
+    if (existsSync(mcpPath)) {
+      try {
+        const raw = readFileSync(mcpPath, 'utf-8');
+        const config = JSON.parse(raw) as Record<string, unknown>;
+        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
+        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
+          delete mcpServers[MCP_SERVER_KEY];
+          writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        }
+      } catch {
+        // Ignore errors during uninstall
+      }
+    }
+
+    this.installedProjectDir = null;
+  }
+
+  /**
+   * Check whether CLEO is installed in the current environment.
+   *
+   * Checks for MCP server registered in .cursor/mcp.json.
+   */
+  async isInstalled(): Promise<boolean> {
+    const mcpPath = join(process.cwd(), '.cursor', 'mcp.json');
+    if (existsSync(mcpPath)) {
+      try {
+        const config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
+        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
+        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
+          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: string): Promise<void> {
+    this.updateInstructionFiles(projectDir);
+  }
+
+  /**
+   * Register the CLEO MCP server in .cursor/mcp.json.
+   *
+   * Cursor stores MCP server configuration in .cursor/mcp.json
+   * under the mcpServers key.
+   *
+   * @returns true if registration was performed or updated
+   */
+  private registerMcpServer(projectDir: string, mcpServerPath: string): boolean {
+    const cursorDir = join(projectDir, '.cursor');
+    const mcpPath = join(cursorDir, 'mcp.json');
+    let config: Record<string, unknown> = {};
+
+    mkdirSync(cursorDir, { recursive: true });
+
+    if (existsSync(mcpPath)) {
+      try {
+        config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
+      } catch {
+        // Start fresh on parse error
+      }
+    }
+
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+      config.mcpServers = {};
+    }
+
+    const mcpServers = config.mcpServers as Record<string, unknown>;
+    mcpServers[MCP_SERVER_KEY] = {
+      command: 'node',
+      args: [mcpServerPath],
+    };
+
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    return true;
+  }
+
+  /**
+   * 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
+   */
+  private updateInstructionFiles(projectDir: string): boolean {
+    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
+   */
+  private updateLegacyRules(projectDir: string): boolean {
+    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
+   */
+  private updateModernRules(projectDir: string): boolean {
+    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.
+   */
+  private getUpdatedFileList(projectDir: string): string[] {
+    const files: string[] = [];
+    if (existsSync(join(projectDir, '.cursorrules'))) {
+      files.push(join(projectDir, '.cursorrules'));
+    }
+    files.push(join(projectDir, '.cursor', 'rules', 'cleo.mdc'));
+    return files;
+  }
+}

package/src/providers/cursor/manifest.json

@@ -0,0 +1,26 @@
+{
+  "id": "cursor",
+  "name": "Cursor Adapter",
+  "version": "1.0.0",
+  "description": "CLEO adapter for Cursor AI code editor",
+  "provider": "cursor",
+  "entryPoint": "src/index.ts",
+  "capabilities": {
+    "supportsHooks": false,
+    "supportedHookEvents": [],
+    "supportsSpawn": false,
+    "supportsInstall": true,
+    "supportsMcp": true,
+    "supportsInstructionFiles": true,
+    "instructionFilePattern": ".cursor/rules/*.mdc",
+    "supportsContextMonitor": false,
+    "supportsStatusline": false,
+    "supportsProviderPaths": true,
+    "supportsTransport": false
+  },
+  "detectionPatterns": [
+    { "type": "env", "pattern": "CURSOR_EDITOR", "description": "Cursor sets this env var" },
+    { "type": "file", "pattern": ".cursor", "description": "Cursor config directory" },
+    { "type": "file", "pattern": ".cursorrules", "description": "Legacy Cursor rules file" }
+  ]
+}

package/src/providers/cursor/spawn.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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
+ */
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+/**
+ * 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 declare class CursorSpawnProvider implements AdapterSpawnProvider {
+    /**
+     * Check if Cursor supports spawning subagents.
+     *
+     * @returns false (Cursor does not support CLI spawning)
+     */
+    canSpawn(): Promise<boolean>;
+    /**
+     * 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
+     */
+    spawn(_context: SpawnContext): Promise<SpawnResult>;
+    /**
+     * List running Cursor subagent processes.
+     *
+     * @returns Empty array (no processes can be spawned)
+     */
+    listRunning(): Promise<SpawnResult[]>;
+    /**
+     * Terminate a Cursor subagent process.
+     *
+     * No-op because Cursor cannot spawn processes.
+     *
+     * @param _instanceId - Unused; no processes to terminate
+     */
+    terminate(_instanceId: string): Promise<void>;
+}
+//# sourceMappingURL=spawn.d.ts.map

package/src/providers/cursor/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE3F;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAIlC;;;;;;;;OAQG;IACG,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAQzD;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAI3C;;;;;;OAMG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGpD"}

package/src/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/src/providers/cursor/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["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;YAC7C,kEAAkE;YAClE,wEAAwE,CACzE,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"}

package/src/providers/cursor/spawn.ts

@@ -0,0 +1,66 @@
+/**
+ * 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
+ */
+
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+
+/**
+ * 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 implements AdapterSpawnProvider {
+  /**
+   * Check if Cursor supports spawning subagents.
+   *
+   * @returns false (Cursor does not support CLI spawning)
+   */
+  async canSpawn(): Promise<boolean> {
+    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: SpawnContext): Promise<SpawnResult> {
+    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(): Promise<SpawnResult[]> {
+    return [];
+  }
+
+  /**
+   * Terminate a Cursor subagent process.
+   *
+   * No-op because Cursor cannot spawn processes.
+   *
+   * @param _instanceId - Unused; no processes to terminate
+   */
+  async terminate(_instanceId: string): Promise<void> {
+    // No-op: Cursor does not spawn processes.
+  }
+}

package/src/providers/opencode/__tests__/adapter.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for the OpenCode adapter package.
+ *
+ * @task T5240
+ */
+export {};
+//# sourceMappingURL=adapter.test.d.ts.map

package/src/providers/opencode/__tests__/adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.test.d.ts","sourceRoot":"","sources":["adapter.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}