ai-cli-mcp 2.14.1 → 2.15.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ai-cli-mcp",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "mcpName": "io.github.mkXultra/ai-cli-mcp",
-  "description": "MCP server for AI CLI tools (Claude, Codex, Gemini, and Forge) with background process management",
+  "description": "MCP server for AI CLI tools (Claude, Codex, Gemini, Forge, and OpenCode) with background process management",
   "author": "mkXultra",
   "license": "MIT",
   "main": "dist/server.js",
@@ -25,21 +25,24 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.24.4"
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
   "type": "module",
   "devDependencies": {
     "@eslint/js": "^9.26.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^22.15.17",
-    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/coverage-v8": "^4.1.3",
     "husky": "^9.1.7",
-    "semantic-release": "^25.0.2",
+    "semantic-release": "^25.0.3",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.3"
   },
   "repository": {
     "type": "git",

package/src/__tests__/app-cli.test.ts

@@ -236,12 +236,22 @@ describe('ai-cli app', () => {
     const stderr = vi.fn();
 
     const exitCode = await runCli(['models'], { stdout, stderr });
+    const payload = JSON.parse(stdout.mock.calls[0][0]);
 
     expect(exitCode).toBe(0);
-    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"aliases"'));
-    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"claude-ultra"'));
-    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"gpt-5.4"'));
-    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"forge"'));
+    expect(payload.aliases).toEqual(expect.any(Array));
+    expect(payload.claude).toContain('sonnet');
+    expect(payload.codex).toContain('gpt-5.4');
+    expect(payload.forge).toEqual(['forge']);
+    expect(payload.opencode).toEqual(['opencode']);
+    expect(payload.dynamicModelBackends).toEqual({
+      opencode: {
+        explicitPrefix: 'oc-',
+        explicitPattern: 'oc-<provider/model>',
+        discoveryCommand: 'opencode models',
+        modelsAreDynamic: true,
+      },
+    });
     expect(stderr).not.toHaveBeenCalled();
   });
 
@@ -273,6 +283,12 @@ describe('ai-cli app', () => {
         available: true,
         lookup: 'path',
       },
+      opencode: {
+        configuredCommand: 'opencode',
+        resolvedPath: '/tmp/bin/opencode',
+        available: true,
+        lookup: 'path',
+      },
     });
 
     const exitCode = await runCli(['doctor'], { stdout, stderr, getDoctorStatus });
@@ -307,6 +323,8 @@ describe('ai-cli app', () => {
     expect(stdout).toHaveBeenCalledWith(expect.stringContaining('gpt-5.2-codex'));
     expect(stdout).toHaveBeenCalledWith(expect.stringContaining('gemini-2.5-pro'));
     expect(stdout).toHaveBeenCalledWith(expect.stringContaining('forge'));
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('opencode'));
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('oc-openai/gpt-5.4'));
     expect(stderr).not.toHaveBeenCalled();
   });
 
@@ -355,6 +373,7 @@ describe('ai-cli app', () => {
 
     expect(exitCode).toBe(0);
     expect(stdout).toHaveBeenCalledWith(DOCTOR_HELP_TEXT);
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('OpenCode'));
     expect(stderr).not.toHaveBeenCalled();
   });
 
@@ -366,6 +385,7 @@ describe('ai-cli app', () => {
 
     expect(exitCode).toBe(0);
     expect(stdout).toHaveBeenCalledWith(DOCTOR_HELP_TEXT);
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('OpenCode'));
     expect(stderr).not.toHaveBeenCalled();
   });
 

package/src/__tests__/cli-bin-smoke.test.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { delimiter, join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
@@ -24,6 +24,62 @@ afterEach(() => {
   }
 });
 
+describe('cli helper entrypoint smoke', () => {
+  it('prints help for cli.run with OpenCode examples', () => {
+    const output = execFileSync(
+      'node',
+      ['--import', 'tsx', 'src/cli.ts', '--help'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: process.env,
+      }
+    );
+
+    expect(output).toContain('Usage: npm run -s cli.run -- --model <model> --workFolder <path> --prompt "..." [options]');
+    expect(output).toContain('opencode');
+    expect(output).toContain('oc-openai/gpt-5.4');
+    expect(output).toContain('OpenCode');
+    expect(output).toContain('npm run -s cli.run.parse -- --agent opencode < raw.txt');
+  });
+
+  it('prints help for cli.run.parse with OpenCode agent support', () => {
+    const output = execFileSync(
+      'node',
+      ['--import', 'tsx', 'src/cli-parse.ts', '--help'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: process.env,
+      }
+    );
+
+    expect(output).toContain('Usage: npm run -s cli.run.parse -- --agent <claude|codex|gemini|forge|opencode>');
+    expect(output).toContain('Agent type: claude, codex, gemini, forge, or opencode');
+    expect(output).toContain('npm run -s cli.run.parse -- --agent opencode < raw.txt');
+  });
+
+  it('parses OpenCode NDJSON through cli.run.parse', () => {
+    const output = execFileSync(
+      'node',
+      ['--import', 'tsx', 'src/cli-parse.ts', '--agent', 'opencode'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        env: process.env,
+        input: '{"type":"step_start","sessionID":"ses_cli_parse"}\n{"type":"text","sessionID":"ses_cli_parse","part":{"type":"text","text":"Hello from cli.parse"}}\n{"type":"step_finish","sessionID":"ses_cli_parse","part":{"type":"step-finish","tokens":{"total":9},"cost":1}}\n',
+      }
+    );
+
+    expect(JSON.parse(output)).toEqual({
+      message: 'Hello from cli.parse',
+      session_id: 'ses_cli_parse',
+      tokens: { total: 9 },
+      cost: 1,
+    });
+  });
+});
+
 describe('ai-cli entrypoint smoke', () => {
   it('prints doctor output for the ai-cli entrypoint', () => {
     const fakeBinDir = makeTempDir('ai-cli-bin-');
@@ -31,6 +87,7 @@ describe('ai-cli entrypoint smoke', () => {
     writeExecutable(fakeBinDir, 'codex');
     writeExecutable(fakeBinDir, 'gemini');
     writeExecutable(fakeBinDir, 'forge');
+    writeExecutable(fakeBinDir, 'opencode');
 
     const output = execFileSync(
       'node',
@@ -45,6 +102,7 @@ describe('ai-cli entrypoint smoke', () => {
           CODEX_CLI_NAME: 'codex',
           GEMINI_CLI_NAME: 'gemini',
           FORGE_CLI_NAME: 'forge',
+          OPENCODE_CLI_NAME: 'opencode',
         },
       }
     );
@@ -53,6 +111,7 @@ describe('ai-cli entrypoint smoke', () => {
     expect(output).toContain('"codex"');
     expect(output).toContain('"gemini"');
     expect(output).toContain('"forge"');
+    expect(output).toContain('"opencode"');
     expect(output).toContain('"available": true');
   });
 
@@ -71,5 +130,7 @@ describe('ai-cli entrypoint smoke', () => {
     expect(output).toContain('--model <model>');
     expect(output).toContain('claude-ultra');
     expect(output).toContain('forge');
+    expect(output).toContain('opencode');
+    expect(output).toContain('oc-openai/gpt-5.4');
   });
 });

package/src/__tests__/cli-builder.test.ts

@@ -23,6 +23,7 @@ const DEFAULT_CLI_PATHS = {
   codex: '/usr/bin/codex',
   gemini: '/usr/bin/gemini',
   forge: '/usr/bin/forge',
+  opencode: '/usr/bin/opencode',
 };
 
 describe('cli-builder', () => {
@@ -104,6 +105,15 @@ describe('cli-builder', () => {
         'reasoning_effort is not supported for forge.'
       );
     });
+
+    it('should reject reasoning_effort for opencode explicitly', () => {
+      expect(() => getReasoningEffort('opencode', 'high')).toThrow(
+        'reasoning_effort is not supported for opencode.'
+      );
+      expect(() => getReasoningEffort('oc-openai/gpt-5.4', 'high')).toThrow(
+        'reasoning_effort is not supported for opencode.'
+      );
+    });
   });
 
   describe('buildCliCommand', () => {
@@ -409,43 +419,129 @@ describe('cli-builder', () => {
       });
     });
 
-    describe('forge agent', () => {
-      it('should build forge command without model flags', () => {
+    describe('opencode agent', () => {
+      it('should build default opencode command without --model', () => {
         const cmd = buildCliCommand({
           prompt: 'test',
           workFolder: '/tmp',
-          model: 'forge',
+          model: 'opencode',
           cliPaths: DEFAULT_CLI_PATHS,
         });
 
-        expect(cmd.agent).toBe('forge');
-        expect(cmd.cliPath).toBe('/usr/bin/forge');
-        expect(cmd.resolvedModel).toBe('forge');
-        expect(cmd.args).toEqual(['-C', '/tmp', '-p', 'test']);
+        expect(cmd.agent).toBe('opencode');
+        expect(cmd.cliPath).toBe('/usr/bin/opencode');
+        expect(cmd.cwd).toBe('/tmp');
+        expect(cmd.args).toEqual(['run', '--format', 'json', '--dir', '/tmp', 'test']);
+        expect(cmd.args).not.toContain('--model');
       });
 
-      it('should map session_id to --conversation-id for forge', () => {
+      it('should route valid explicit OpenCode model syntax', () => {
         const cmd = buildCliCommand({
           prompt: 'test',
           workFolder: '/tmp',
-          model: 'forge',
-          session_id: 'forge-conv-123',
+          model: 'oc-openai/gpt-5.4',
           cliPaths: DEFAULT_CLI_PATHS,
         });
 
-        expect(cmd.args).toEqual(['-C', '/tmp', '--conversation-id', 'forge-conv-123', '-p', 'test']);
+        expect(cmd.agent).toBe('opencode');
+        expect(cmd.resolvedModel).toBe('oc-openai/gpt-5.4');
+        expect(cmd.args).toEqual([
+          'run',
+          '--format',
+          'json',
+          '--dir',
+          '/tmp',
+          '--model',
+          'openai/gpt-5.4',
+          'test',
+        ]);
+      });
+
+      it.each([
+        'oc-',
+        'oc-openai',
+        'oc-/gpt-5.4',
+        'oc-openai/',
+      ])('should reject invalid explicit OpenCode syntax: %s', (model) => {
+        expect(() =>
+          buildCliCommand({
+            prompt: 'test',
+            workFolder: '/tmp',
+            model,
+            cliPaths: DEFAULT_CLI_PATHS,
+          })
+        ).toThrow('Invalid OpenCode model. Expected exact syntax oc-<provider/model>.');
       });
 
-      it('should reject reasoning_effort for forge in command building', () => {
+      it.each([' oc-openai/gpt-5.4', 'oc-openai/gpt-5.4 '])(
+        'should reject explicit OpenCode models with surrounding whitespace: %s',
+        (model) => {
+          expect(() =>
+            buildCliCommand({
+              prompt: 'test',
+              workFolder: '/tmp',
+              model,
+              cliPaths: DEFAULT_CLI_PATHS,
+            })
+          ).toThrow('Invalid OpenCode model. Expected exact syntax oc-<provider/model>.');
+        }
+      );
+
+      it('should reject reasoning_effort for OpenCode in command building', () => {
         expect(() =>
           buildCliCommand({
             prompt: 'test',
             workFolder: '/tmp',
-            model: 'forge',
+            model: 'opencode',
             reasoning_effort: 'high',
             cliPaths: DEFAULT_CLI_PATHS,
           })
-        ).toThrow('reasoning_effort is not supported for forge.');
+        ).toThrow('reasoning_effort is not supported for opencode.');
+      });
+
+      it('should build resumed default OpenCode command', () => {
+        const cmd = buildCliCommand({
+          prompt: 'resume prompt',
+          workFolder: '/tmp',
+          model: 'opencode',
+          session_id: 'ses-123',
+          cliPaths: DEFAULT_CLI_PATHS,
+        });
+
+        expect(cmd.args).toEqual([
+          'run',
+          '--format',
+          'json',
+          '--dir',
+          '/tmp',
+          '--session',
+          'ses-123',
+          'resume prompt',
+        ]);
+        expect(cmd.args).not.toContain('--model');
+      });
+
+      it('should build resumed explicit OpenCode command', () => {
+        const cmd = buildCliCommand({
+          prompt: 'resume prompt',
+          workFolder: '/tmp',
+          model: 'oc-openai/gpt-5.4',
+          session_id: 'ses-456',
+          cliPaths: DEFAULT_CLI_PATHS,
+        });
+
+        expect(cmd.args).toEqual([
+          'run',
+          '--format',
+          'json',
+          '--dir',
+          '/tmp',
+          '--session',
+          'ses-456',
+          '--model',
+          'openai/gpt-5.4',
+          'resume prompt',
+        ]);
       });
     });
   });

package/src/__tests__/cli-process-service.test.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { CliProcessService } from '../cli-process-service.js';
+import { createOpenCodeMock } from './utils/opencode-mock.js';
 
 function createMockCliScript(dir: string, name: string, options: { ignoreSigterm?: boolean } = {}): string {
   const scriptPath = join(dir, name);
@@ -66,6 +67,7 @@ describe('CliProcessService', () => {
         codex: scriptPath,
         gemini: scriptPath,
         forge: scriptPath,
+        opencode: scriptPath,
       },
     });
 
@@ -145,6 +147,7 @@ printf '%s\n' '{"type":"system","session_id":"session-cli-1"}'
         codex: scriptPath,
         gemini: scriptPath,
         forge: scriptPath,
+        opencode: scriptPath,
       },
     });
 
@@ -255,6 +258,7 @@ printf '%s\n' '{"type":"system","session_id":"session-cli-1"}'
         codex: scriptPath,
         gemini: scriptPath,
         forge: scriptPath,
+        opencode: scriptPath,
       },
     });
 
@@ -294,6 +298,7 @@ printf '%s\n' '{"type":"system","session_id":"session-cli-1"}'
         codex: '/bin/sh',
         gemini: '/bin/sh',
         forge: '/bin/sh',
+        opencode: '/bin/sh',
       },
     });
 
@@ -368,6 +373,7 @@ printf '%s\n' '{"type":"system","session_id":"session-cli-1"}'
         codex: '/bin/sh',
         gemini: '/bin/sh',
         forge: '/bin/sh',
+        opencode: '/bin/sh',
       },
     });
 
@@ -426,6 +432,7 @@ printf '%s\n' '{"type":"system","session_id":"session-cli-1"}'
         codex: '/bin/sh',
         gemini: '/bin/sh',
         forge: '/bin/sh',
+        opencode: '/bin/sh',
       },
     });
 
@@ -502,6 +509,7 @@ printf '%s\n' '{"type":"system","session_id":"session-cli-1"}'
         codex: '/bin/sh',
         gemini: '/bin/sh',
         forge: '/bin/sh',
+        opencode: '/bin/sh',
       },
     });
 
@@ -564,6 +572,7 @@ Forge assistant reply
         codex: '/bin/sh',
         gemini: '/bin/sh',
         forge: '/bin/sh',
+        opencode: '/bin/sh',
       },
     });
 
@@ -575,4 +584,107 @@ Forge assistant reply
       session_id: 'forge-conv-1',
     });
   });
+
+  it('parses successful OpenCode detached runs from stdout only', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'ai-cli-cli-service-'));
+    tempDirs.push(root);
+    const stateDir = join(root, 'state');
+    const workFolder = join(root, 'opencode-project');
+    mkdirSync(workFolder, { recursive: true });
+    const argsLogPath = join(root, 'opencode-args.log');
+    const { scriptPath } = createOpenCodeMock(root, { argsLogPath });
+
+    const service = new CliProcessService({
+      stateDir,
+      cliPaths: {
+        claude: '/bin/sh',
+        codex: '/bin/sh',
+        gemini: '/bin/sh',
+        forge: '/bin/sh',
+        opencode: scriptPath,
+      },
+    });
+
+    const runResult = await service.startProcess({
+      prompt: 'hello opencode',
+      cwd: workFolder,
+      model: 'opencode',
+    });
+
+    const waited = await service.waitForProcesses([runResult.pid], 5);
+    expect(waited).toHaveLength(1);
+    expect(waited[0]).toMatchObject({
+      pid: runResult.pid,
+      agent: 'opencode',
+      status: 'completed',
+      exitCode: 0,
+      model: 'opencode',
+      session_id: 'ses-opencode-default',
+      agentOutput: {
+        message: 'Initial: hello opencode',
+        session_id: 'ses-opencode-default',
+        tokens: { total: 11833 },
+        cost: 0,
+      },
+    });
+    expect(waited[0]).not.toHaveProperty('stdout');
+    expect(waited[0]).not.toHaveProperty('stderr');
+    expect(readFileSync(argsLogPath, 'utf8')).toContain(`--dir ${workFolder}`);
+  });
+
+  it('preserves raw stdout and stderr for failed detached OpenCode runs', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'ai-cli-cli-service-'));
+    tempDirs.push(root);
+    const stateDir = join(root, 'state');
+    const workFolder = join(root, 'opencode-fail-project');
+    mkdirSync(workFolder, { recursive: true });
+    const { scriptPath } = createOpenCodeMock(root);
+
+    const service = new CliProcessService({
+      stateDir,
+      cliPaths: {
+        claude: '/bin/sh',
+        codex: '/bin/sh',
+        gemini: '/bin/sh',
+        forge: '/bin/sh',
+        opencode: scriptPath,
+      },
+    });
+
+    const runResult = await service.startProcess({
+      prompt: 'please fail',
+      cwd: workFolder,
+      model: 'oc-openai/gpt-5.4',
+    });
+
+    const [compactResult] = await service.waitForProcesses([runResult.pid], 5);
+    expect(compactResult).toMatchObject({
+      pid: runResult.pid,
+      agent: 'opencode',
+      status: 'failed',
+      exitCode: 7,
+      model: 'oc-openai/gpt-5.4',
+      session_id: 'ses-opencode-default',
+      stdout: expect.stringContaining('Partial failure output'),
+      stderr: expect.stringContaining('OpenCode failed for openai/gpt-5.4'),
+    });
+    expect(compactResult).not.toHaveProperty('agentOutput');
+
+    const verboseResult = await service.getProcessResult(runResult.pid, true);
+    expect(verboseResult).toMatchObject({
+      pid: runResult.pid,
+      agent: 'opencode',
+      status: 'failed',
+      exitCode: 7,
+      session_id: 'ses-opencode-default',
+      stdout: expect.stringContaining('Partial failure output'),
+      stderr: expect.stringContaining('OpenCode failed for openai/gpt-5.4'),
+      agentOutput: {
+        message: 'Partial failure output',
+        session_id: 'ses-opencode-default',
+        tokens: { total: 42 },
+        cost: 0,
+      },
+    });
+  });
 });

package/src/__tests__/cli-utils.test.ts

@@ -20,6 +20,7 @@ describe('cli-utils doctor status', () => {
     delete process.env.CODEX_CLI_NAME;
     delete process.env.GEMINI_CLI_NAME;
     delete process.env.FORGE_CLI_NAME;
+    delete process.env.OPENCODE_CLI_NAME;
     process.env.PATH = '/mock/bin:/usr/bin';
   });
 
@@ -51,6 +52,12 @@ describe('cli-utils doctor status', () => {
       available: false,
       lookup: 'path',
     });
+    expect(status.opencode).toEqual({
+      configuredCommand: 'opencode',
+      resolvedPath: null,
+      available: false,
+      lookup: 'path',
+    });
   });
 
   it('does not mark non-executable PATH entries as available', async () => {
@@ -73,6 +80,12 @@ describe('cli-utils doctor status', () => {
       available: false,
       lookup: 'path',
     });
+    expect(status.opencode).toEqual({
+      configuredCommand: 'opencode',
+      resolvedPath: null,
+      available: false,
+      lookup: 'path',
+    });
   });
 
   it('reports invalid relative env paths as doctor errors', async () => {
@@ -163,4 +176,25 @@ describe('cli-utils doctor status', () => {
     });
     expect(findForgeCli()).toBe('forge-custom');
   });
+
+  it('supports OpenCode lookup via OPENCODE_CLI_NAME', async () => {
+    process.env.OPENCODE_CLI_NAME = 'opencode-custom';
+    mockAccessSync.mockImplementation((filePath) => {
+      if (filePath === '/mock/bin/opencode-custom') {
+        return undefined;
+      }
+      throw new Error('not executable');
+    });
+
+    const { getCliDoctorStatus, findOpencodeCli } = await import('../cli-utils.js');
+    const status = getCliDoctorStatus();
+
+    expect(status.opencode).toEqual({
+      configuredCommand: 'opencode-custom',
+      resolvedPath: '/mock/bin/opencode-custom',
+      available: true,
+      lookup: 'env',
+    });
+    expect(findOpencodeCli()).toBe('opencode-custom');
+  });
 });