@cleocode/adapters 2026.3.72 → 2026.3.73

package/src/providers/gemini-cli/install.ts

@@ -0,0 +1,203 @@
+/**
+ * Gemini CLI Install Provider
+ *
+ * Handles CLEO installation into Gemini CLI environments:
+ * - Registers CLEO MCP server in ~/.gemini/settings.json
+ * - Ensures AGENTS.md has CLEO @-references
+ *
+ * @task T161
+ * @epic T134
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+
+/** Lines that should appear in AGENTS.md to reference CLEO. */
+const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+
+/** MCP server registration key used in Gemini CLI settings. */
+const MCP_SERVER_KEY = 'cleo';
+
+/**
+ * Install provider for Gemini CLI.
+ *
+ * Manages CLEO's integration with Gemini CLI by:
+ * 1. Registering the CLEO MCP server in ~/.gemini/settings.json
+ * 2. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ *
+ * @task T161
+ * @epic T134
+ */
+export class GeminiCliInstallProvider implements AdapterInstallProvider {
+  /**
+   * Install CLEO into a Gemini CLI environment.
+   *
+   * @param options - Installation options including project directory and MCP server path
+   * @returns Result describing what was installed
+   * @task T161
+   */
+  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 ~/.gemini/settings.json
+    if (mcpServerPath) {
+      mcpRegistered = this.registerMcpServer(mcpServerPath);
+      if (mcpRegistered) {
+        details.mcpConfigPath = join(homedir(), '.gemini', 'settings.json');
+      }
+    }
+
+    // Step 2: Ensure AGENTS.md has @-references
+    instructionFileUpdated = this.updateInstructionFile(projectDir);
+    if (instructionFileUpdated) {
+      details.instructionFile = join(projectDir, 'AGENTS.md');
+    }
+
+    return {
+      success: true,
+      installedAt,
+      instructionFileUpdated,
+      mcpRegistered,
+      details,
+    };
+  }
+
+  /**
+   * Uninstall CLEO from the Gemini CLI environment.
+   *
+   * Removes the MCP server registration from ~/.gemini/settings.json.
+   * Does not remove AGENTS.md references (they are harmless if CLEO is not present).
+   * @task T161
+   */
+  async uninstall(): Promise<void> {
+    const settingsPath = join(homedir(), '.gemini', 'settings.json');
+    if (existsSync(settingsPath)) {
+      try {
+        const raw = readFileSync(settingsPath, '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(settingsPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        }
+      } catch {
+        // Ignore errors during uninstall
+      }
+    }
+  }
+
+  /**
+   * Check whether CLEO is installed in the Gemini CLI environment.
+   *
+   * Checks for MCP server registered in ~/.gemini/settings.json.
+   * Returns true if the CLEO MCP server entry is found.
+   * @task T161
+   */
+  async isInstalled(): Promise<boolean> {
+    const settingsPath = join(homedir(), '.gemini', 'settings.json');
+    if (existsSync(settingsPath)) {
+      try {
+        const config = JSON.parse(readFileSync(settingsPath, '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 AGENTS.md contains @-references to CLEO instruction files.
+   *
+   * Creates AGENTS.md if it does not exist. Appends any missing references.
+   *
+   * @param projectDir - Project root directory
+   * @task T161
+   */
+  async ensureInstructionReferences(projectDir: string): Promise<void> {
+    this.updateInstructionFile(projectDir);
+  }
+
+  /**
+   * Register the CLEO MCP server in ~/.gemini/settings.json.
+   *
+   * Gemini CLI stores its MCP server configuration in ~/.gemini/settings.json
+   * under the mcpServers key.
+   *
+   * @param mcpServerPath - Absolute path to the MCP server entry point
+   * @returns true if registration was performed or updated
+   */
+  private registerMcpServer(mcpServerPath: string): boolean {
+    const geminiDir = join(homedir(), '.gemini');
+    const settingsPath = join(geminiDir, 'settings.json');
+    let config: Record<string, unknown> = {};
+
+    mkdirSync(geminiDir, { recursive: true });
+
+    if (existsSync(settingsPath)) {
+      try {
+        config = JSON.parse(readFileSync(settingsPath, '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(settingsPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    return true;
+  }
+
+  /**
+   * Update AGENTS.md with CLEO @-references.
+   *
+   * @param projectDir - Project root directory
+   * @returns true if the file was created or modified
+   */
+  private updateInstructionFile(projectDir: string): boolean {
+    const agentsMdPath = join(projectDir, 'AGENTS.md');
+    let content = '';
+    let existed = false;
+
+    if (existsSync(agentsMdPath)) {
+      content = readFileSync(agentsMdPath, 'utf-8');
+      existed = true;
+    }
+
+    const missingRefs = INSTRUCTION_REFERENCES.filter((ref) => !content.includes(ref));
+
+    if (missingRefs.length === 0) {
+      return false;
+    }
+
+    const refsBlock = missingRefs.join('\n');
+
+    if (existed) {
+      const separator = content.endsWith('\n') ? '' : '\n';
+      content = content + separator + refsBlock + '\n';
+    } else {
+      content = refsBlock + '\n';
+    }
+
+    writeFileSync(agentsMdPath, content, 'utf-8');
+    return true;
+  }
+}

package/src/providers/gemini-cli/manifest.json

@@ -0,0 +1,35 @@
+{
+  "id": "gemini-cli",
+  "name": "Gemini CLI Adapter",
+  "version": "1.0.0",
+  "description": "CLEO adapter for Google Gemini CLI",
+  "provider": "gemini-cli",
+  "entryPoint": "src/index.ts",
+  "capabilities": {
+    "supportsHooks": true,
+    "supportedHookEvents": [
+      "SessionStart",
+      "SessionEnd",
+      "BeforeAgent",
+      "AfterAgent",
+      "BeforeTool",
+      "AfterTool",
+      "BeforeModel",
+      "AfterModel",
+      "PreCompress",
+      "Notification"
+    ],
+    "supportsSpawn": false,
+    "supportsInstall": true,
+    "supportsMcp": true,
+    "supportsInstructionFiles": false,
+    "supportsContextMonitor": false,
+    "supportsStatusline": false,
+    "supportsProviderPaths": false,
+    "supportsTransport": false
+  },
+  "detectionPatterns": [
+    { "type": "cli", "pattern": "gemini", "description": "Gemini CLI binary available in PATH" },
+    { "type": "directory", "pattern": "~/.gemini", "description": "Gemini CLI config directory" }
+  ]
+}

package/src/providers/kimi/adapter.ts

@@ -0,0 +1,153 @@
+/**
+ * Kimi Adapter
+ *
+ * Main CLEOProviderAdapter implementation for Moonshot AI Kimi.
+ * Provides install-only capabilities for CLEO integration.
+ * Kimi has no native hook system, so integration is via MCP only.
+ *
+ * @task T163
+ * @epic T134
+ */
+
+import { exec } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import type {
+  AdapterCapabilities,
+  AdapterHealthStatus,
+  CLEOProviderAdapter,
+} from '@cleocode/contracts';
+import { KimiHookProvider } from './hooks.js';
+import { KimiInstallProvider } from './install.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * CLEO provider adapter for Moonshot AI Kimi.
+ *
+ * Bridges CLEO's adapter system with Kimi's integration surface:
+ * - Hooks: No-op (Kimi has no native hook system)
+ * - Install: Registers MCP server in ~/.kimi/mcp.json and ensures AGENTS.md references
+ *
+ * @task T163
+ * @epic T134
+ */
+export class KimiAdapter implements CLEOProviderAdapter {
+  readonly id = 'kimi';
+  readonly name = 'Kimi';
+  readonly version = '1.0.0';
+
+  capabilities: AdapterCapabilities = {
+    supportsHooks: false,
+    supportedHookEvents: [],
+    supportsSpawn: false,
+    supportsInstall: true,
+    supportsMcp: true,
+    supportsInstructionFiles: false,
+    supportsContextMonitor: false,
+    supportsStatusline: false,
+    supportsProviderPaths: false,
+    supportsTransport: false,
+    supportsTaskSync: false,
+  };
+
+  hooks: KimiHookProvider;
+  install: KimiInstallProvider;
+
+  private projectDir: string | null = null;
+  private initialized = false;
+
+  constructor() {
+    this.hooks = new KimiHookProvider();
+    this.install = new KimiInstallProvider();
+  }
+
+  /**
+   * Initialize the adapter for a given project directory.
+   *
+   * @param projectDir - Root directory of the project
+   * @task T163
+   */
+  async initialize(projectDir: string): Promise<void> {
+    this.projectDir = projectDir;
+    this.initialized = true;
+  }
+
+  /**
+   * Dispose the adapter and clean up resources.
+   *
+   * Releases tracked state. No hooks to unregister since Kimi
+   * has no native hook system.
+   * @task T163
+   */
+  async dispose(): Promise<void> {
+    this.initialized = false;
+    this.projectDir = null;
+  }
+
+  /**
+   * Run a health check to verify Kimi is accessible.
+   *
+   * Checks:
+   * 1. Adapter has been initialized
+   * 2. Kimi CLI binary is available in PATH
+   * 3. ~/.kimi/ configuration directory exists
+   *
+   * @returns Health status with details about each check
+   * @task T163
+   */
+  async healthCheck(): Promise<AdapterHealthStatus> {
+    const details: Record<string, unknown> = {};
+
+    if (!this.initialized) {
+      return {
+        healthy: false,
+        provider: this.id,
+        details: { error: 'Adapter not initialized' },
+      };
+    }
+
+    // Check Kimi CLI availability
+    let cliAvailable = false;
+    try {
+      const { stdout } = await execAsync('which kimi');
+      cliAvailable = stdout.trim().length > 0;
+      details.cliPath = stdout.trim();
+    } catch {
+      details.cliAvailable = false;
+    }
+
+    // Check for Kimi config directory
+    const kimiConfigDir = join(homedir(), '.kimi');
+    const configExists = existsSync(kimiConfigDir);
+    details.configDirExists = configExists;
+
+    // Healthy if CLI is available (primary requirement)
+    const healthy = cliAvailable;
+    details.cliAvailable = cliAvailable;
+
+    return {
+      healthy,
+      provider: this.id,
+      details,
+    };
+  }
+
+  /**
+   * Check whether the adapter has been initialized.
+   * @task T163
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Get the project directory this adapter was initialized with.
+   * @task T163
+   */
+  getProjectDir(): string | null {
+    return this.projectDir;
+  }
+}

package/src/providers/kimi/hooks.ts

@@ -0,0 +1,80 @@
+/**
+ * Kimi Hook Provider
+ *
+ * Kimi has no native hook system (hookSystem is "none").
+ * This provider implements the minimal AdapterHookProvider interface
+ * with a no-op mapProviderEvent that always returns null.
+ *
+ * @task T163
+ * @epic T134
+ */
+
+import type { AdapterHookProvider } from '@cleocode/contracts';
+
+/**
+ * Hook provider for Kimi.
+ *
+ * Kimi does not expose a native hook or event system.
+ * All hook-related methods are no-ops; mapProviderEvent always
+ * returns null since there are no events to map.
+ *
+ * @task T163
+ * @epic T134
+ */
+export class KimiHookProvider implements AdapterHookProvider {
+  private registered = false;
+
+  /**
+   * Map a Kimi native event name to a CAAMP hook event name.
+   *
+   * Kimi has no hook system, so this always returns null.
+   *
+   * @param _providerEvent - Unused; Kimi emits no hookable events
+   * @returns Always null
+   * @task T163
+   */
+  mapProviderEvent(_providerEvent: string): string | null {
+    return null;
+  }
+
+  /**
+   * Register native hooks for a project.
+   *
+   * Kimi has no hook system. This method is a no-op and only
+   * tracks registration state for interface compliance.
+   *
+   * @param _projectDir - Project directory (unused)
+   * @task T163
+   */
+  async registerNativeHooks(_projectDir: string): Promise<void> {
+    this.registered = true;
+  }
+
+  /**
+   * Unregister native hooks.
+   *
+   * Kimi has no hook system. This method is a no-op.
+   * @task T163
+   */
+  async unregisterNativeHooks(): Promise<void> {
+    this.registered = false;
+  }
+
+  /**
+   * Check whether hooks have been registered via registerNativeHooks.
+   * @task T163
+   */
+  isRegistered(): boolean {
+    return this.registered;
+  }
+
+  /**
+   * Get the full event mapping for introspection/debugging.
+   *
+   * Returns an empty map since Kimi has no hookable events.
+   * @task T163
+   */
+  getEventMap(): Readonly<Record<string, string>> {
+    return {};
+  }
+}

package/src/providers/kimi/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Kimi provider adapter.
+ *
+ * CLEO provider adapter for Moonshot AI Kimi.
+ * Default export is the adapter class for dynamic loading by AdapterManager.
+ *
+ * @task T163
+ * @epic T134
+ */
+
+import { KimiAdapter } from './adapter.js';
+
+export { KimiAdapter } from './adapter.js';
+export { KimiHookProvider } from './hooks.js';
+export { KimiInstallProvider } from './install.js';
+
+export default KimiAdapter;
+
+/**
+ * Factory function for creating adapter instances.
+ * Used by AdapterManager's dynamic import fallback.
+ *
+ * @task T163
+ */
+export function createAdapter(): KimiAdapter {
+  return new KimiAdapter();
+}

package/src/providers/kimi/install.ts

@@ -0,0 +1,209 @@
+/**
+ * Kimi Install Provider
+ *
+ * Handles CLEO installation into Kimi environments:
+ * - Registers CLEO MCP server in ~/.kimi/mcp.json
+ * - Ensures AGENTS.md has CLEO @-references
+ *
+ * Kimi has no native hook system, so this is the primary integration
+ * mechanism: registering the MCP server so CLEO can be accessed as a tool.
+ *
+ * @task T163
+ * @epic T134
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+
+/** Lines that should appear in AGENTS.md to reference CLEO. */
+const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+
+/** MCP server registration key used in Kimi MCP config. */
+const MCP_SERVER_KEY = 'cleo';
+
+/**
+ * Install provider for Kimi.
+ *
+ * Manages CLEO's integration with Kimi by:
+ * 1. Registering the CLEO MCP server in ~/.kimi/mcp.json
+ * 2. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ *
+ * Since Kimi has no native hook system, MCP registration is the only
+ * mechanism for surfacing CLEO capabilities inside a Kimi session.
+ *
+ * @task T163
+ * @epic T134
+ */
+export class KimiInstallProvider implements AdapterInstallProvider {
+  /**
+   * Install CLEO into a Kimi environment.
+   *
+   * @param options - Installation options including project directory and MCP server path
+   * @returns Result describing what was installed
+   * @task T163
+   */
+  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 ~/.kimi/mcp.json
+    if (mcpServerPath) {
+      mcpRegistered = this.registerMcpServer(mcpServerPath);
+      if (mcpRegistered) {
+        details.mcpConfigPath = join(homedir(), '.kimi', 'mcp.json');
+      }
+    }
+
+    // Step 2: Ensure AGENTS.md has @-references
+    instructionFileUpdated = this.updateInstructionFile(projectDir);
+    if (instructionFileUpdated) {
+      details.instructionFile = join(projectDir, 'AGENTS.md');
+    }
+
+    return {
+      success: true,
+      installedAt,
+      instructionFileUpdated,
+      mcpRegistered,
+      details,
+    };
+  }
+
+  /**
+   * Uninstall CLEO from the Kimi environment.
+   *
+   * Removes the MCP server registration from ~/.kimi/mcp.json.
+   * Does not remove AGENTS.md references (they are harmless if CLEO is not present).
+   * @task T163
+   */
+  async uninstall(): Promise<void> {
+    const mcpPath = join(homedir(), '.kimi', '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
+      }
+    }
+  }
+
+  /**
+   * Check whether CLEO is installed in the Kimi environment.
+   *
+   * Checks for MCP server registered in ~/.kimi/mcp.json.
+   * Returns true if the CLEO MCP server entry is found.
+   * @task T163
+   */
+  async isInstalled(): Promise<boolean> {
+    const mcpPath = join(homedir(), '.kimi', '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 AGENTS.md contains @-references to CLEO instruction files.
+   *
+   * Creates AGENTS.md if it does not exist. Appends any missing references.
+   *
+   * @param projectDir - Project root directory
+   * @task T163
+   */
+  async ensureInstructionReferences(projectDir: string): Promise<void> {
+    this.updateInstructionFile(projectDir);
+  }
+
+  /**
+   * Register the CLEO MCP server in ~/.kimi/mcp.json.
+   *
+   * Kimi stores its MCP server configuration in ~/.kimi/mcp.json
+   * under the mcpServers key.
+   *
+   * @param mcpServerPath - Absolute path to the MCP server entry point
+   * @returns true if registration was performed or updated
+   */
+  private registerMcpServer(mcpServerPath: string): boolean {
+    const kimiDir = join(homedir(), '.kimi');
+    const mcpPath = join(kimiDir, 'mcp.json');
+    let config: Record<string, unknown> = {};
+
+    mkdirSync(kimiDir, { 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 AGENTS.md with CLEO @-references.
+   *
+   * @param projectDir - Project root directory
+   * @returns true if the file was created or modified
+   */
+  private updateInstructionFile(projectDir: string): boolean {
+    const agentsMdPath = join(projectDir, 'AGENTS.md');
+    let content = '';
+    let existed = false;
+
+    if (existsSync(agentsMdPath)) {
+      content = readFileSync(agentsMdPath, 'utf-8');
+      existed = true;
+    }
+
+    const missingRefs = INSTRUCTION_REFERENCES.filter((ref) => !content.includes(ref));
+
+    if (missingRefs.length === 0) {
+      return false;
+    }
+
+    const refsBlock = missingRefs.join('\n');
+
+    if (existed) {
+      const separator = content.endsWith('\n') ? '' : '\n';
+      content = content + separator + refsBlock + '\n';
+    } else {
+      content = refsBlock + '\n';
+    }
+
+    writeFileSync(agentsMdPath, content, 'utf-8');
+    return true;
+  }
+}