ai-cli-mcp 2.11.0 → 2.13.0

package/docs/cli-architecture.md

@@ -0,0 +1,275 @@
+# AI CLI Architecture Plan
+
+## Goal
+
+`ai-cli-mcp` package will expose two global commands:
+
+- `ai-cli`: human-facing production CLI
+- `ai-cli-mcp`: MCP server entrypoint for backward compatibility
+
+The package name stays `ai-cli-mcp` for now. We do not introduce a daemon. We keep the product as a thin wrapper over Claude Code, Codex CLI, and Gemini CLI.
+
+## Non-Goals
+
+- Renaming the npm package in this phase
+- Introducing a long-running background daemon
+- Introducing a new public job identifier such as `run_id`
+- Making the CLI responsible for deep process orchestration beyond launching and observing AI CLI processes
+- Capturing exit codes in the first production CLI iteration
+
+## Product Shape
+
+### `ai-cli`
+
+`ai-cli` is the primary CLI for humans.
+
+Supported commands:
+
+- `ai-cli run`
+- `ai-cli wait`
+- `ai-cli ps`
+- `ai-cli result`
+- `ai-cli kill`
+- `ai-cli cleanup`
+- `ai-cli models`
+- `ai-cli doctor`
+- `ai-cli mcp`
+
+Behavior:
+
+- Running `ai-cli` with no subcommand prints help
+- Public process identity is `pid`
+- `--cwd` is the working directory flag
+- Output format should stay close to MCP responses
+
+### `ai-cli-mcp`
+
+`ai-cli-mcp` remains the MCP-focused command.
+
+Behavior:
+
+- Running `ai-cli-mcp` with no arguments starts the MCP server
+- This command exists for compatibility with existing users and MCP configurations
+
+## Public Command Semantics
+
+### `ai-cli run`
+
+Starts the target AI CLI in the background and returns immediately.
+
+Properties:
+
+- Returns MCP-like JSON including `pid`, `status`, `agent`, and `message`
+- Uses `pid` as the public identifier
+- Spawns the actual Claude/Codex/Gemini process directly
+- Redirects `stdout` and `stderr` to files
+- Does not guarantee `exitCode` in the initial design
+
+### `ai-cli wait`
+
+Waits until all given PIDs are no longer running.
+
+Properties:
+
+- Input is one or more `pid` values
+- Timeout is supported
+- Response format follows MCP `wait` as closely as possible
+- Returns a result array, same direction as MCP
+
+### `ai-cli ps`
+
+Lists tracked runs with minimal information.
+
+Properties:
+
+- Output includes `pid`, `agent`, and `status`
+- Initial scope is intentionally minimal
+
+### `ai-cli result`
+
+Reads saved output and returns parsed results.
+
+Properties:
+
+- Behavior should stay close to MCP `get_result`
+- Parsed output is preferred
+- Falls back to raw output when parsing fails or output is incomplete
+
+### `ai-cli kill`
+
+Sends `SIGTERM` to the given PID.
+
+Properties:
+
+- Public API is intentionally PID-based
+- Users may also kill processes manually outside the tool
+
+### `ai-cli cleanup`
+
+Removes tracked process state for runs that are no longer running.
+
+Properties:
+
+- Removes completed and failed PID directories
+- Keeps running processes intact
+- Removes empty per-cwd directories after cleanup
+
+### `ai-cli doctor`
+
+Checks whether supported AI CLI binaries are available.
+
+Properties:
+
+- Scope is binary existence/path resolution only
+- It does not verify login or acceptance state
+
+### `ai-cli models`
+
+Returns the supported model list and aliases.
+
+Properties:
+
+- Behavior should stay close to MCP-supported model documentation
+- Static model definitions are acceptable in this phase
+
+### `ai-cli mcp`
+
+Starts the MCP server from the `ai-cli` command.
+
+Properties:
+
+- Allows one package to support both direct CLI usage and MCP usage
+
+## Entrypoints
+
+Planned package bin layout:
+
+```json
+{
+  "bin": {
+    "ai-cli": "dist/bin/ai-cli.js",
+    "ai-cli-mcp": "dist/bin/ai-cli-mcp.js"
+  }
+}
+```
+
+Planned source layout:
+
+```text
+src/
+  bin/
+    ai-cli.ts
+    ai-cli-mcp.ts
+  app/
+    cli.ts
+    mcp.ts
+```
+
+Responsibilities:
+
+- `src/bin/ai-cli.ts`: thin CLI entrypoint
+- `src/bin/ai-cli-mcp.ts`: thin MCP entrypoint
+- `src/app/cli.ts`: subcommand parsing and dispatch for `ai-cli`
+- `src/app/mcp.ts`: MCP server bootstrap
+
+## Backend Architecture
+
+The core implementation should be shared between CLI and MCP.
+
+Suggested internal boundaries:
+
+- `cli-builder`
+  - resolves model aliases
+  - validates input
+  - builds the real Claude/Codex/Gemini command
+- `runner`
+  - spawns the actual AI CLI process
+  - redirects `stdout` and `stderr` to files
+- `process-store`
+  - stores tracked process metadata
+  - exact path and file format are intentionally deferred
+- `process-service`
+  - shared use cases for `run`, `wait`, `ps`, `result`, and `kill`
+- `parsers`
+  - parses saved output into structured results
+
+## PID-Based Design Decision
+
+The public interface stays PID-based on purpose.
+
+Rationale:
+
+- This CLI is a thin wrapper over existing AI CLI tools
+- PID is already the native OS process identifier
+- Users can inspect or terminate processes with normal Unix tooling
+- We do not want to introduce a synthetic public job ID in this phase
+
+Implication:
+
+- Public commands use `pid`
+- Internal storage may store additional metadata if needed
+- PID remains the only required identifier at the product surface
+
+## Background Execution Strategy
+
+The first production CLI implementation uses direct process spawning with file redirection.
+
+Approach:
+
+- Spawn the actual AI CLI process directly
+- Redirect `stdout` to a file
+- Redirect `stderr` to a file
+- Persist enough metadata to support `wait`, `ps`, `result`, and `kill`
+
+Why this approach:
+
+- Lighter than introducing a worker process
+- Keeps the CLI close to Unix process semantics
+- Avoids worker-child termination complexity
+- Keeps migration from the current MCP server relatively simple
+
+Tradeoff accepted in phase one:
+
+- `exitCode` is not guaranteed to be captured
+
+If this becomes a practical problem, a thin per-run wrapper/worker can be introduced later without changing the public CLI model.
+
+## MCP Compatibility Plan
+
+MCP functionality stays in the project and should be preserved.
+
+Compatibility goals:
+
+- Keep current MCP tool names
+- Keep current response shape as much as practical
+- Reuse the same backend logic as the new CLI where possible
+
+Target mapping:
+
+- MCP `run` -> shared process service `run`
+- MCP `wait` -> shared process service `wait`
+- MCP `list_processes` -> shared process service `ps`
+- MCP `get_result` -> shared process service `result`
+- MCP `kill_process` -> shared process service `kill`
+
+## Implementation Order
+
+1. Split the current `src/server.ts` responsibilities into MCP surface and shared process logic
+2. Introduce new bin entrypoints for `ai-cli` and `ai-cli-mcp`
+3. Add `ai-cli` subcommand parsing and help output
+4. Implement direct background spawning with stdout/stderr file redirection
+5. Implement CLI commands: `run`, `wait`, `ps`, `result`, `kill`
+6. Add `models`, `doctor`, and `mcp`
+7. Rewire MCP handlers to the same shared backend
+
+## Open Items Deferred
+
+The following items are intentionally deferred:
+
+- state directory path
+- file naming scheme
+- metadata file schema
+- exit code capture for detached CLI runs
+- retention and cleanup policy
+- exact raw output access patterns
+- Windows-specific process handling details

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "ai-cli-mcp",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "mcpName": "io.github.mkXultra/ai-cli-mcp",
-  "description": "MCP server for AI CLI tools (Claude, Codex, and Gemini) with background process management",
+  "description": "MCP server for AI CLI tools (Claude, Codex, Gemini, and Forge) with background process management",
   "author": "mkXultra",
   "license": "MIT",
   "main": "dist/server.js",
   "bin": {
-    "ai-cli-mcp": "dist/server.js"
+    "ai-cli": "dist/bin/ai-cli.js",
+    "ai-cli-mcp": "dist/bin/ai-cli-mcp.js"
   },
   "scripts": {
     "build": "tsc",

package/server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.mkXultra/ai-cli-mcp",
-  "description": "MCP server for AI CLI tools (Claude, Codex, and Gemini) with background process management",
+  "description": "MCP server for AI CLI tools (Claude, Codex, Gemini, and Forge) with background process management",
   "repository": {
     "url": "https://github.com/mkXultra/ai-cli-mcp",
     "source": "github"

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

@@ -0,0 +1,370 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  CLI_HELP_TEXT,
+  DOCTOR_HELP_TEXT,
+  MODELS_HELP_TEXT,
+  RUN_HELP_TEXT,
+  WAIT_HELP_TEXT,
+  runCli,
+} from '../app/cli.js';
+
+describe('ai-cli app', () => {
+  it('prints help and exits successfully when no subcommand is provided', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const startMcpServer = vi.fn();
+
+    const exitCode = await runCli([], {
+      stdout,
+      stderr,
+      startMcpServer,
+    });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toHaveBeenCalledWith(CLI_HELP_TEXT);
+    expect(stderr).not.toHaveBeenCalled();
+    expect(startMcpServer).not.toHaveBeenCalled();
+  });
+
+  it('starts MCP mode when the mcp subcommand is provided', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const startMcpServer = vi.fn().mockResolvedValue(undefined);
+
+    const exitCode = await runCli(['mcp'], {
+      stdout,
+      stderr,
+      startMcpServer,
+    });
+
+    expect(exitCode).toBe(0);
+    expect(startMcpServer).toHaveBeenCalledTimes(1);
+    expect(stdout).not.toHaveBeenCalled();
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('dispatches run with parsed CLI options', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const startMcpServer = vi.fn();
+    const runProcess = vi.fn().mockResolvedValue({
+      pid: 123,
+      status: 'started',
+      agent: 'claude',
+      message: 'claude process started successfully',
+    });
+
+    const exitCode = await runCli(
+      ['run', '--cwd', '/tmp/project', '--prompt', 'hello', '--model', 'sonnet'],
+      {
+        stdout,
+        stderr,
+        startMcpServer,
+        runProcess,
+      }
+    );
+
+    expect(exitCode).toBe(0);
+    expect(runProcess).toHaveBeenCalledWith({
+      cwd: '/tmp/project',
+      prompt: 'hello',
+      model: 'sonnet',
+    });
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"pid": 123'));
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('accepts legacy run option aliases', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const runProcess = vi.fn().mockResolvedValue({
+      pid: 123,
+      status: 'started',
+      agent: 'claude',
+      message: 'claude process started successfully',
+    });
+
+    const exitCode = await runCli(
+      [
+        'run',
+        '--workFolder',
+        '/tmp/project',
+        '--prompt_file',
+        '/tmp/prompt.txt',
+        '--session_id',
+        'session-123',
+        '--reasoning_effort',
+        'high',
+      ],
+      {
+        stdout,
+        stderr,
+        runProcess,
+      }
+    );
+
+    expect(exitCode).toBe(0);
+    expect(runProcess).toHaveBeenCalledWith({
+      cwd: '/tmp/project',
+      prompt_file: '/tmp/prompt.txt',
+      session_id: 'session-123',
+      reasoning_effort: 'high',
+    });
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('requires a prompt or prompt file for run', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+
+    const exitCode = await runCli(['run', '--cwd', '/tmp/project'], {
+      stdout,
+      stderr,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toHaveBeenCalledWith('Missing required option: --prompt or --prompt-file\n');
+    expect(stdout).toHaveBeenCalledWith(CLI_HELP_TEXT);
+  });
+
+  it('dispatches wait with pid arguments and timeout', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const waitForProcesses = vi.fn().mockResolvedValue([{ pid: 123, status: 'completed' }]);
+
+    const exitCode = await runCli(
+      ['wait', '123', '456', '--timeout', '5'],
+      {
+        stdout,
+        stderr,
+        waitForProcesses,
+      }
+    );
+
+    expect(exitCode).toBe(0);
+    expect(waitForProcesses).toHaveBeenCalledWith([123, 456], 5);
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"status": "completed"'));
+  });
+
+  it('rejects invalid wait timeout values', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const waitForProcesses = vi.fn();
+
+    const exitCode = await runCli(['wait', '123', '--timeout', 'abc'], {
+      stdout,
+      stderr,
+      waitForProcesses,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toHaveBeenCalledWith('Invalid --timeout value\n');
+    expect(stdout).toHaveBeenCalledWith(CLI_HELP_TEXT);
+    expect(waitForProcesses).not.toHaveBeenCalled();
+  });
+
+  it('rejects non-integer pid arguments for wait', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const waitForProcesses = vi.fn();
+
+    const exitCode = await runCli(['wait', '123', 'abc'], {
+      stdout,
+      stderr,
+      waitForProcesses,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toHaveBeenCalledWith('All pid arguments must be positive integers\n');
+    expect(stdout).toHaveBeenCalledWith(CLI_HELP_TEXT);
+    expect(waitForProcesses).not.toHaveBeenCalled();
+  });
+
+  it('dispatches ps, result, and kill', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const listProcesses = vi.fn().mockResolvedValue([{ pid: 123, agent: 'claude', status: 'running' }]);
+    const getProcessResult = vi.fn().mockResolvedValue({ pid: 123, status: 'completed' });
+    const killProcess = vi.fn().mockResolvedValue({ pid: 123, status: 'terminated' });
+
+    const psExitCode = await runCli(['ps'], { stdout, stderr, listProcesses });
+    expect(psExitCode).toBe(0);
+    expect(listProcesses).toHaveBeenCalledTimes(1);
+
+    const resultExitCode = await runCli(['result', '123'], { stdout, stderr, getProcessResult });
+    expect(resultExitCode).toBe(0);
+    expect(getProcessResult).toHaveBeenCalledWith(123, false);
+
+    const killExitCode = await runCli(['kill', '123'], { stdout, stderr, killProcess });
+    expect(killExitCode).toBe(0);
+    expect(killProcess).toHaveBeenCalledWith(123);
+  });
+
+  it('dispatches cleanup', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const cleanupProcesses = vi.fn().mockResolvedValue({ removed: 2, message: 'Removed 2 processes' });
+
+    const exitCode = await runCli(['cleanup'], { stdout, stderr, cleanupProcesses });
+
+    expect(exitCode).toBe(0);
+    expect(cleanupProcesses).toHaveBeenCalledTimes(1);
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"removed": 2'));
+  });
+
+  it('prints models as structured json', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+
+    const exitCode = await runCli(['models'], { stdout, stderr });
+
+    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(stderr).not.toHaveBeenCalled();
+  });
+
+  it('prints doctor status as structured json', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const getDoctorStatus = vi.fn().mockReturnValue({
+      claude: {
+        configuredCommand: 'claude',
+        resolvedPath: '/tmp/bin/claude',
+        available: true,
+        lookup: 'path',
+      },
+      codex: {
+        configuredCommand: 'codex',
+        resolvedPath: null,
+        available: false,
+        lookup: 'path',
+      },
+      gemini: {
+        configuredCommand: 'gemini',
+        resolvedPath: '/tmp/bin/gemini',
+        available: true,
+        lookup: 'path',
+      },
+      forge: {
+        configuredCommand: 'forge',
+        resolvedPath: '/tmp/bin/forge',
+        available: true,
+        lookup: 'path',
+      },
+    });
+
+    const exitCode = await runCli(['doctor'], { stdout, stderr, getDoctorStatus });
+
+    expect(exitCode).toBe(0);
+    expect(getDoctorStatus).toHaveBeenCalledTimes(1);
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"configuredCommand": "claude"'));
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"available": false'));
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('passes verbose through to result', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const getProcessResult = vi.fn().mockResolvedValue({ pid: 123, status: 'completed' });
+
+    const exitCode = await runCli(['result', '123', '--verbose'], { stdout, stderr, getProcessResult });
+
+    expect(exitCode).toBe(0);
+    expect(getProcessResult).toHaveBeenCalledWith(123, true);
+  });
+
+  it('prints detailed help for run --help', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+
+    const exitCode = await runCli(['run', '--help'], { stdout, stderr });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toHaveBeenCalledWith(RUN_HELP_TEXT);
+    expect(stdout).toHaveBeenCalledWith(expect.stringContaining('claude-ultra'));
+    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(stderr).not.toHaveBeenCalled();
+  });
+
+  it('prints detailed help for wait --help', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+
+    const exitCode = await runCli(['wait', '--help'], { stdout, stderr });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toHaveBeenCalledWith(WAIT_HELP_TEXT);
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('prints detailed help for models --help', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+
+    const exitCode = await runCli(['models', '--help'], { stdout, stderr });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toHaveBeenCalledWith(MODELS_HELP_TEXT);
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('prints detailed help for doctor --help', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+
+    const exitCode = await runCli(['doctor', '--help'], { stdout, stderr });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toHaveBeenCalledWith(DOCTOR_HELP_TEXT);
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('prints detailed help for doctor -h', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+
+    const exitCode = await runCli(['doctor', '-h'], { stdout, stderr });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toHaveBeenCalledWith(DOCTOR_HELP_TEXT);
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('prints help for --help', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const startMcpServer = vi.fn();
+
+    const exitCode = await runCli(['--help'], {
+      stdout,
+      stderr,
+      startMcpServer,
+    });
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toHaveBeenCalledWith(CLI_HELP_TEXT);
+    expect(stderr).not.toHaveBeenCalled();
+  });
+
+  it('returns a non-zero exit code for unknown subcommands', async () => {
+    const stdout = vi.fn();
+    const stderr = vi.fn();
+    const startMcpServer = vi.fn();
+
+    const exitCode = await runCli(['unknown'], {
+      stdout,
+      stderr,
+      startMcpServer,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toHaveBeenCalledWith(expect.stringContaining('Unknown subcommand: unknown'));
+    expect(stdout).toHaveBeenCalledWith(CLI_HELP_TEXT);
+    expect(startMcpServer).not.toHaveBeenCalled();
+  });
+});