ai-cli-mcp 2.19.0 → 2.20.1

package/dist/__tests__/version-print.test.js

@@ -1,65 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { createTestClient } from './utils/mcp-client.js';
-import { getSharedMock } from './utils/persistent-mock.js';
-describe('Version Print on First Use', () => {
-    let client;
-    let testDir;
-    let consoleErrorSpy;
-    beforeEach(async () => {
-        // Ensure mock exists
-        await getSharedMock();
-        // Create a temporary directory for test files
-        testDir = mkdtempSync(join(tmpdir(), 'claude-code-test-'));
-        // Spy on console.error
-        consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
-        client = createTestClient({ debug: false });
-        await client.connect();
-    });
-    afterEach(async () => {
-        // Disconnect client
-        await client.disconnect();
-        // Clean up test directory
-        rmSync(testDir, { recursive: true, force: true });
-        // Restore console.error spy
-        consoleErrorSpy.mockRestore();
-    });
-    it('should print version and startup time only on first use', async () => {
-        // First tool call
-        await client.callTool('run', {
-            prompt: 'echo "test 1"',
-            workFolder: testDir,
-        });
-        // Find the version print in the console.error calls
-        const findVersionCall = (calls) => {
-            return calls.find(call => {
-                const str = call[1] || call[0]; // message might be first or second param
-                return typeof str === 'string' && str.includes('ai_cli_mcp v') && str.includes('started at');
-            });
-        };
-        // Check that version was printed on first use
-        const versionCall = findVersionCall(consoleErrorSpy.mock.calls);
-        expect(versionCall).toBeDefined();
-        expect(versionCall[1]).toMatch(/ai_cli_mcp v[0-9]+\.[0-9]+\.[0-9]+ started at \d{4}-\d{2}-\d{2}T/);
-        // Clear the spy but keep the spy active
-        consoleErrorSpy.mockClear();
-        // Second tool call
-        await client.callTool('run', {
-            prompt: 'echo "test 2"',
-            workFolder: testDir,
-        });
-        // Check that version was NOT printed on second use
-        const secondVersionCall = findVersionCall(consoleErrorSpy.mock.calls);
-        expect(secondVersionCall).toBeUndefined();
-        // Third tool call
-        await client.callTool('run', {
-            prompt: 'echo "test 3"',
-            workFolder: testDir,
-        });
-        // Should still not have been called with version print
-        const thirdVersionCall = findVersionCall(consoleErrorSpy.mock.calls);
-        expect(thirdVersionCall).toBeUndefined();
-    });
-});

package/dist/__tests__/wait.test.js

@@ -1,260 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { EventEmitter } from 'node:events';
-import { spawn } from 'node:child_process';
-import { homedir } from 'node:os';
-import { existsSync } from 'node:fs';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-// Mock dependencies
-vi.mock('node:child_process');
-vi.mock('node:fs');
-vi.mock('node:os');
-vi.mock('node:path', () => ({
-    resolve: vi.fn((path) => path),
-    join: vi.fn((...args) => args.join('/')),
-    isAbsolute: vi.fn((path) => path.startsWith('/')),
-    dirname: vi.fn((path) => '/tmp')
-}));
-vi.mock('@modelcontextprotocol/sdk/server/stdio.js');
-vi.mock('@modelcontextprotocol/sdk/types.js', () => ({
-    ListToolsRequestSchema: { name: 'listTools' },
-    CallToolRequestSchema: { name: 'callTool' },
-    ErrorCode: {
-        InternalError: 'InternalError',
-        MethodNotFound: 'MethodNotFound',
-        InvalidParams: 'InvalidParams'
-    },
-    McpError: class extends Error {
-        code;
-        constructor(code, message) {
-            super(message);
-            this.code = code;
-        }
-    }
-}));
-vi.mock('@modelcontextprotocol/sdk/server/index.js', () => ({
-    Server: vi.fn().mockImplementation(function () {
-        this.setRequestHandler = vi.fn();
-        this.connect = vi.fn();
-        this.close = vi.fn();
-        this.onerror = undefined;
-        return this;
-    }),
-}));
-// Mock package.json
-vi.mock('../../package.json', () => ({
-    default: { version: '1.0.0-test' }
-}));
-// Re-import after mocks
-const mockSpawn = vi.mocked(spawn);
-const mockHomedir = vi.mocked(homedir);
-const mockExistsSync = vi.mocked(existsSync);
-describe('Wait Tool Tests', () => {
-    let handlers;
-    let mockServerInstance;
-    let server;
-    // Setup function to initialize server with mocks
-    const setupServer = async () => {
-        vi.resetModules();
-        handlers = new Map();
-        // Mock Server implementation to capture handlers
-        vi.mocked(Server).mockImplementation(function () {
-            this.setRequestHandler = vi.fn((schema, handler) => {
-                handlers.set(schema.name, handler);
-            });
-            this.connect = vi.fn();
-            this.close = vi.fn();
-            return this;
-        });
-        const module = await import('../server.js');
-        // @ts-ignore
-        const { ClaudeCodeServer } = module;
-        server = new ClaudeCodeServer();
-        mockServerInstance = vi.mocked(Server).mock.results[0].value;
-    };
-    beforeEach(async () => {
-        mockHomedir.mockReturnValue('/home/user');
-        mockExistsSync.mockReturnValue(true);
-        await setupServer();
-    });
-    afterEach(() => {
-        vi.clearAllMocks();
-        vi.useRealTimers();
-    });
-    const createMockProcess = (pid) => {
-        const mockProcess = new EventEmitter();
-        mockProcess.pid = pid;
-        mockProcess.stdout = new EventEmitter();
-        mockProcess.stderr = new EventEmitter();
-        mockProcess.stdout.on = vi.fn();
-        mockProcess.stderr.on = vi.fn();
-        mockProcess.kill = vi.fn();
-        return mockProcess;
-    };
-    it('should wait for a single running process', async () => {
-        const callToolHandler = handlers.get('callTool');
-        const mockProcess = createMockProcess(12345);
-        mockSpawn.mockReturnValue(mockProcess);
-        // Start a process first
-        await callToolHandler({
-            params: {
-                name: 'run',
-                arguments: {
-                    prompt: 'test prompt',
-                    workFolder: '/tmp'
-                }
-            }
-        });
-        // Mock process output accumulation (simulated internally by server)
-        // We need to access the process manager or simulate events
-        // Call wait
-        const waitPromise = callToolHandler({
-            params: {
-                name: 'wait',
-                arguments: {
-                    pids: [12345]
-                }
-            }
-        });
-        // Simulate process completion after a delay
-        setTimeout(() => {
-            mockProcess.stdout.emit('data', 'Process output');
-            mockProcess.emit('close', 0);
-        }, 10);
-        const result = await waitPromise;
-        const response = JSON.parse(result.content[0].text);
-        expect(response).toHaveLength(1);
-        expect(response[0].pid).toBe(12345);
-        expect(response[0].status).toBe('completed');
-        // expect(response[0].stdout).toBe('Process output'); // Flaky test
-    });
-    it('should return immediately if process is already completed', async () => {
-        const callToolHandler = handlers.get('callTool');
-        const mockProcess = createMockProcess(12346);
-        mockSpawn.mockReturnValue(mockProcess);
-        // Start process
-        await callToolHandler({
-            params: {
-                name: 'run',
-                arguments: {
-                    prompt: 'test',
-                    workFolder: '/tmp'
-                }
-            }
-        });
-        // Complete immediately
-        mockProcess.emit('close', 0);
-        // Call wait
-        const result = await callToolHandler({
-            params: {
-                name: 'wait',
-                arguments: {
-                    pids: [12346]
-                }
-            }
-        });
-        const response = JSON.parse(result.content[0].text);
-        expect(response[0].status).toBe('completed');
-    });
-    it('should wait for multiple processes', async () => {
-        const callToolHandler = handlers.get('callTool');
-        // Process 1
-        const p1 = createMockProcess(101);
-        mockSpawn.mockReturnValueOnce(p1);
-        await callToolHandler({
-            params: { name: 'run', arguments: { prompt: 'p1', workFolder: '/tmp' } }
-        });
-        // Process 2
-        const p2 = createMockProcess(102);
-        mockSpawn.mockReturnValueOnce(p2);
-        await callToolHandler({
-            params: { name: 'run', arguments: { prompt: 'p2', workFolder: '/tmp' } }
-        });
-        // Wait for both
-        const waitPromise = callToolHandler({
-            params: {
-                name: 'wait',
-                arguments: { pids: [101, 102] }
-            }
-        });
-        // Finish p1
-        setTimeout(() => { p1.emit('close', 0); }, 10);
-        // Finish p2 later
-        setTimeout(() => { p2.emit('close', 0); }, 30);
-        const result = await waitPromise;
-        const response = JSON.parse(result.content[0].text);
-        expect(response).toHaveLength(2);
-        expect(response.find((r) => r.pid === 101).status).toBe('completed');
-        expect(response.find((r) => r.pid === 102).status).toBe('completed');
-    });
-    it('should clear timeout timers after wait resolves', async () => {
-        vi.useFakeTimers();
-        const callToolHandler = handlers.get('callTool');
-        const mockProcess = createMockProcess(12348);
-        mockSpawn.mockReturnValue(mockProcess);
-        await callToolHandler({
-            params: {
-                name: 'run',
-                arguments: {
-                    prompt: 'test prompt',
-                    workFolder: '/tmp'
-                }
-            }
-        });
-        const waitPromise = callToolHandler({
-            params: {
-                name: 'wait',
-                arguments: {
-                    pids: [12348],
-                    timeout: 180
-                }
-            }
-        });
-        mockProcess.emit('close', 0);
-        await vi.runAllTicks();
-        const result = await waitPromise;
-        const response = JSON.parse(result.content[0].text);
-        expect(response[0].status).toBe('completed');
-        expect(vi.getTimerCount()).toBe(0);
-    });
-    it('should throw error for non-existent PID', async () => {
-        const callToolHandler = handlers.get('callTool');
-        try {
-            await callToolHandler({
-                params: {
-                    name: 'wait',
-                    arguments: { pids: [99999] }
-                }
-            });
-            expect.fail('Should have thrown');
-        }
-        catch (error) {
-            expect(error.message).toContain('Process with PID 99999 not found');
-        }
-    });
-    it('should handle timeout', async () => {
-        const callToolHandler = handlers.get('callTool');
-        const mockProcess = createMockProcess(12347);
-        mockSpawn.mockReturnValue(mockProcess);
-        await callToolHandler({
-            params: { name: 'run', arguments: { prompt: 'test', workFolder: '/tmp' } }
-        });
-        // Call wait with short timeout
-        const waitPromise = callToolHandler({
-            params: {
-                name: 'wait',
-                arguments: {
-                    pids: [12347],
-                    timeout: 0.1 // 100ms
-                }
-            }
-        });
-        // Don't emit close event
-        try {
-            await waitPromise;
-            expect.fail('Should have thrown');
-        }
-        catch (error) {
-            expect(error.message).toContain('Timed out');
-        }
-    });
-});

package/docs/RELEASE_CHECKLIST.md

@@ -1,65 +0,0 @@
-# Release Process
-
-This project uses [semantic-release](https://semantic-release.gitbook.io/) for automated versioning and publishing.
-
-## How It Works
-
-1. **Commit with Conventional Commits format** to `develop` branch
-2. **CI automatically determines version** based on commit messages
-3. **Automatic release**: version bump, CHANGELOG update, npm publish, GitHub Release
-
-## Commit Message Format
-
-Use [Conventional Commits](https://www.conventionalcommits.org/) format:
-
-| Type | Description | Version Bump |
-|------|-------------|--------------|
-| `fix:` | Bug fixes | Patch (1.0.0 → 1.0.1) |
-| `feat:` | New features | Minor (1.0.0 → 1.1.0) |
-| `feat!:` or `BREAKING CHANGE:` | Breaking changes | Major (1.0.0 → 2.0.0) |
-| `docs:`, `chore:`, `style:`, `refactor:`, `test:` | Other changes | No release |
-
-### Examples
-
-```bash
-# Patch release
-git commit -m "fix: resolve session_id not working for Codex"
-
-# Minor release
-git commit -m "feat: add support for new model"
-
-# Major release
-git commit -m "feat!: change API response format"
-# or
-git commit -m "feat: change API response format
-
-BREAKING CHANGE: response structure has changed"
-```
-
-## Pre-Merge Checklist
-
-Before merging to `develop`:
-
-- [ ] Tests pass locally (`npm test`)
-- [ ] Build succeeds (`npm run build`)
-- [ ] Commit messages follow Conventional Commits format
-- [ ] PR has been reviewed (if applicable)
-
-## Important: Git Tags
-
-semantic-release uses git tags to determine the current version. **Tags must exist on the `develop` branch.**
-
-If releases fail with version errors:
-
-1. Check existing tags: `git tag -l 'v*'`
-2. Ensure the latest version tag exists on `develop`
-3. If missing, create it: `git tag vX.X.X && git push origin vX.X.X`
-
-## npm Trusted Publishing Setup
-
-This project uses OIDC trusted publishing (no npm token required).
-
-Configuration on npmjs.com:
-- Organization/user: `mkXultra`
-- Repository: `ai-cli-mcp`
-- Workflow filename: `publish.yml`

package/docs/cli-architecture.md

@@ -1,275 +0,0 @@
-# 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