ai-cli-mcp 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# [2.12.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.11.0...v2.12.0) (2026-03-12)
+
+
+### Features
+
+* ai-cliコマンドを追加しアーキテクチャをリファクタリング ([10a1209](https://github.com/mkXultra/ai-cli-mcp/commit/10a120933d5893d47e47001a165f0abc5e4557aa))
+* CliProcessServiceとCLIサブコマンドを追加 ([0043ee4](https://github.com/mkXultra/ai-cli-mcp/commit/0043ee4a73bbf2d48f57b0b0ded8f12e29e8ebf2))
+* CLIサブコマンドhelpとcleanupを追加し状態保存先を再設計 ([63dc1a2](https://github.com/mkXultra/ai-cli-mcp/commit/63dc1a238e9883cab04e818413576ad265b600ab))
+* doctorとmodelsサブコマンドを追加しモデルカタログをモジュール化 ([15222e3](https://github.com/mkXultra/ai-cli-mcp/commit/15222e3c29c18bc16fa0bc7d6c4f3bdc621f6ff6))
+
 # [2.11.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.10.0...v2.11.0) (2026-03-08)
 
 

package/README.ja.md

@@ -9,6 +9,10 @@ AI CLIツール（Claude, Codex, Gemini）をバックグラウンドプロセ
 
 Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦戦していることに気づいたことはありませんか？このサーバーは、強力な統合 `run` ツールを提供し、複数のAIエージェントを活用してコーディングタスクをより効果的に処理できるようにします。
 
+## デモ
+
+[![デモ](docs/assets/demo-jp.gif)](https://github.com/mkXultra/ai-cli-mcp/releases/download/v2.11.0/demo-jp.mp4)
+
 ## 概要
 
 このMCPサーバーは、LLMがAI CLIツールと対話するためのツールを提供します。MCPクライアントと統合することで、LLMは以下のことが可能になります：
@@ -45,6 +49,8 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 >    - `gpt-5.2-codex` で `README.md` にアーキテクチャの解説を追記
 > 4. 最後に再び `wait` して、両方の結果をまとめてください。
 
+[![セッション再開デモ](docs/assets/demo-resume-jp.gif)](https://github.com/mkXultra/ai-cli-mcp/releases/download/v2.11.0/demo-resume-jp.mp4)
+
 ## メリット
 
 - **真の非同期マルチタスク**: エージェントの実行はバックグラウンドで行われ、即座に制御が戻ります。呼び出し元のAIは実行完了を待つことなく、並行して次のタスクの実行や別のエージェントの呼び出しを行うことができます。
@@ -61,9 +67,16 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 
 ## インストールと使い方
 
-推奨される使用方法は、`npx` を使用してインストールすることです。
+現在の主な使い方は 2 つあります。
+
+- `ai-cli-mcp`: MCP サーバーの起動
+- `ai-cli`: 人間向け CLI
+
+### MCP 利用 (`npx`)
 
-### MCP設定ファイルでnpxを使用する場合:
+MCP サーバーとして使う場合は、`npx` 経由が推奨です。
+
+#### MCP設定ファイルでnpxを使用する場合:
 
 ```json
     "ai-cli-mcp": {
@@ -75,12 +88,47 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
     },
 ```
 
-### Claude CLI mcp add コマンドを使用する場合:
+#### Claude CLI mcp add コマンドを使用する場合:
 
 ```bash
 claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'
 ```
 
+### 人間向け CLI 利用 (グローバルインストール)
+
+シェルから `ai-cli` を直接使いたい場合は、グローバルインストールしてください。
+
+```bash
+npm install -g ai-cli-mcp
+```
+
+これで以下の 2 つのコマンドが使えるようになります。
+
+- `ai-cli`
+- `ai-cli-mcp`
+
+例:
+
+```bash
+ai-cli doctor
+ai-cli models
+ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
+ai-cli ps
+ai-cli result 12345
+ai-cli wait 12345 --timeout 300
+ai-cli kill 12345
+ai-cli cleanup
+ai-cli-mcp
+```
+
+### 人間向け CLI 利用 (`npx`)
+
+公開パッケージ名はまだ `ai-cli-mcp` のままなので、`npx` で `ai-cli` を使う場合は次の形になります。
+
+```bash
+npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
+```
+
 ## 重要な初回セットアップ
 
 ### Claude CLIの場合:
@@ -112,6 +160,56 @@ gemini auth login
 
 macOSでは、これらのツールを初めて実行する際にフォルダへのアクセス許可を求められる場合があります。最初の実行が失敗しても、2回目以降は動作するはずです。
 
+## CLI コマンド
+
+`ai-cli` は現在以下をサポートしています。
+
+- `run`
+- `ps`
+- `result`
+- `wait`
+- `kill`
+- `cleanup`
+- `doctor`
+- `models`
+- `mcp`
+
+基本的な流れ:
+
+```bash
+ai-cli doctor
+ai-cli models
+ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
+ai-cli ps
+ai-cli wait 12345
+ai-cli result 12345
+ai-cli cleanup
+```
+
+`run` の作業ディレクトリ指定は `--cwd` が基本です。互換性のために `--workFolder` / `--work-folder` も受け付けます。
+
+`doctor` は CLI バイナリの存在確認と path 解決だけを行います。ログイン状態や利用規約同意までは確認しません。
+
+## CLI の状態保存先
+
+バックグラウンド実行した `ai-cli` の状態は、次のディレクトリに保存されます。
+
+```text
+~/.local/state/ai-cli/cwds/<normalized-cwd>/<pid>/
+```
+
+各 PID ディレクトリには以下が入ります。
+
+- `meta.json`
+- `stdout.log`
+- `stderr.log`
+
+完了済み・失敗済みの実行は `ai-cli cleanup` で削除できます。`running` のものは保持されます。
+
+## 既知の制約
+
+detached 実行された `ai-cli` の自然終了 exit code は、まだ永続化していません。そのため、CLI は出力と running/completed 状態は返せますが、自然終了したバックグラウンド実行の `exitCode` は現時点では保証しません。
+
 ## MCPクライアントへの接続
 
 サーバーのセットアップ後、MCPクライアント（CursorやWindsurfなど）の設定ファイル（`mcp.json` や `mcp_config.json`）に設定を追加してください。
@@ -167,6 +265,7 @@ PIDを指定して、実行中のAIエージェントプロセスを終了しま
 ## トラブルシューティング
 
 - **"Command not found" (claude-code-mcp):** グローバルにインストールした場合、npmのグローバルbinディレクトリがシステムのPATHに含まれているか確認してください。`npx` を使用している場合、`npx` 自体が機能しているか確認してください。
+- **"Command not found" (`ai-cli`):** グローバルインストール時は npm のグローバル bin ディレクトリが `PATH` に入っているか確認してください。`npx` の場合は `npx -y --package ai-cli-mcp@latest ai-cli ...` を使ってください。
 - **"Command not found" (claude または ~/.claude/local/claude):** Claude CLIが正しくインストールされていることを確認してください。`claude/doctor` を実行するか、公式ドキュメントを確認してください。
 - **権限の問題:** 「重要な初回セットアップ」の手順を実行したか確認してください。
 - **サーバーからのJSONエラー:** `MCP_CLAUDE_DEBUG` が `true` の場合、エラーメッセージやログがMCPのJSON解析を妨げる可能性があります。通常動作時は `false` に設定してください。

package/README.md

@@ -11,6 +11,10 @@ An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude,
 
 Did you notice that Cursor sometimes struggles with complex, multi-step edits or operations? This server, with its powerful unified `run` tool, enables multiple AI agents to handle your coding tasks more effectively.
 
+## Demo
+
+[![Demo](docs/assets/demo.gif)](https://github.com/mkXultra/ai-cli-mcp/releases/download/v2.11.0/demo.mp4)
+
 ## Overview
 
 This MCP server provides tools that can be used by LLMs to interact with AI CLI tools. When integrated with MCP clients, it allows LLMs to:
@@ -44,6 +48,8 @@ You can reuse heavy context (like large codebases) using session IDs to save cos
 >    - Add architecture documentation to `README.md` using `gpt-5.2-codex`
 > 4. Finally, `wait` again to combine both results.
 
+[![Session Resume Demo](docs/assets/demo-resume.gif)](https://github.com/mkXultra/ai-cli-mcp/releases/download/v2.11.0/demo-resume.mp4)
+
 ## Benefits
 
 - **True Async Multitasking**: Agent execution happens in the background, returning control immediately. The calling AI can proceed with the next task or invoke another agent without waiting for completion.
@@ -60,9 +66,16 @@ The only prerequisite is that the AI CLI tools you want to use are locally insta
 
 ## Installation & Usage
 
-The recommended way to use this server is by installing it by using `npx`.
+There are now two primary ways to use this package:
+
+- `ai-cli-mcp`: MCP server entrypoint
+- `ai-cli`: human-facing CLI for background AI runs
+
+### MCP usage with `npx`
 
-### Using npx in your MCP configuration:
+The recommended way to use the MCP server is via `npx`.
+
+#### Using npx in your MCP configuration:
 
 ```json
     "ai-cli-mcp": {
@@ -74,12 +87,47 @@ The recommended way to use this server is by installing it by using `npx`.
     },
 ```
 
-### Using Claude CLI mcp add command:
+#### Using Claude CLI mcp add command:
 
 ```bash
 claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'
 ```
 
+### Human CLI usage with global install
+
+If you want to use the production CLI directly from your shell, install the package globally:
+
+```bash
+npm install -g ai-cli-mcp
+```
+
+This exposes both commands:
+
+- `ai-cli`
+- `ai-cli-mcp`
+
+Examples:
+
+```bash
+ai-cli doctor
+ai-cli models
+ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
+ai-cli ps
+ai-cli result 12345
+ai-cli wait 12345 --timeout 300
+ai-cli kill 12345
+ai-cli cleanup
+ai-cli-mcp
+```
+
+### Human CLI usage with `npx`
+
+Because the published package name is still `ai-cli-mcp`, the shortest `npx` form for the CLI is:
+
+```bash
+npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
+```
+
 ## Important First-Time Setup
 
 ### For Claude CLI:
@@ -111,6 +159,56 @@ gemini auth login
 
 macOS might ask for folder permissions the first time any of these tools run. If the first run fails, subsequent runs should work.
 
+## CLI Commands
+
+`ai-cli` currently supports:
+
+- `run`
+- `ps`
+- `result`
+- `wait`
+- `kill`
+- `cleanup`
+- `doctor`
+- `models`
+- `mcp`
+
+Example flow:
+
+```bash
+ai-cli doctor
+ai-cli models
+ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
+ai-cli ps
+ai-cli wait 12345
+ai-cli result 12345
+ai-cli cleanup
+```
+
+`run` accepts `--cwd` as the primary working-directory flag and also accepts the older aliases `--workFolder` / `--work-folder` for compatibility.
+
+`doctor` checks only binary existence and path resolution. It does not verify login state or terms acceptance.
+
+## CLI State Storage
+
+Background CLI runs are stored under:
+
+```text
+~/.local/state/ai-cli/cwds/<normalized-cwd>/<pid>/
+```
+
+Each PID directory contains:
+
+- `meta.json`
+- `stdout.log`
+- `stderr.log`
+
+Use `ai-cli cleanup` to remove completed and failed runs. Running processes are preserved.
+
+## Known Limitation
+
+Detached `ai-cli` runs do not currently persist natural process exit codes. As a result, the CLI can report process output and running/completed state, but it does not yet guarantee `exitCode` for naturally finished background runs.
+
 ## Connecting to Your MCP Client
 
 After setting up the server, add the configuration to your MCP client's settings file (e.g., `mcp.json` for Cursor, `mcp_config.json` for Windsurf).
@@ -166,6 +264,7 @@ Terminates a running AI agent process by PID.
 ## Troubleshooting
 
 - **"Command not found" (claude-code-mcp):** If installed globally, ensure the npm global bin directory is in your system's PATH. If using `npx`, ensure `npx` itself is working.
+- **"Command not found" (`ai-cli`):** If installed globally, ensure your npm global bin directory is in `PATH`. If using `npx`, use `npx -y --package ai-cli-mcp@latest ai-cli ...`.
 - **"Command not found" (claude or ~/.claude/local/claude):** Ensure the Claude CLI is installed correctly. Run `claude/doctor` or check its documentation.
 - **Permissions Issues:** Make sure you've run the "Important First-Time Setup" step.
 - **JSON Errors from Server:** If `MCP_CLAUDE_DEBUG` is `true`, error messages or logs might interfere with MCP's JSON parsing. Set to `false` for normal operation.

package/dist/__tests__/app-cli.test.js

@@ -0,0 +1,285 @@
+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(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',
+            },
+        });
+        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(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();
+    });
+});

package/dist/__tests__/cli-bin-smoke.test.js

@@ -0,0 +1,54 @@
+import { execFileSync } from 'node:child_process';
+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';
+const tempDirs = [];
+function makeTempDir(prefix) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function writeExecutable(dir, name) {
+    const filePath = join(dir, name);
+    writeFileSync(filePath, '#!/bin/sh\nexit 0\n', 'utf8');
+    chmodSync(filePath, 0o755);
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe('ai-cli entrypoint smoke', () => {
+    it('prints doctor output for the ai-cli entrypoint', () => {
+        const fakeBinDir = makeTempDir('ai-cli-bin-');
+        writeExecutable(fakeBinDir, 'claude');
+        writeExecutable(fakeBinDir, 'codex');
+        writeExecutable(fakeBinDir, 'gemini');
+        const output = execFileSync('node', ['--import', 'tsx', 'src/bin/ai-cli.ts', 'doctor'], {
+            cwd: process.cwd(),
+            encoding: 'utf8',
+            env: {
+                ...process.env,
+                PATH: `${fakeBinDir}${delimiter}${process.env.PATH || ''}`,
+                CLAUDE_CLI_NAME: 'claude',
+                CODEX_CLI_NAME: 'codex',
+                GEMINI_CLI_NAME: 'gemini',
+            },
+        });
+        expect(output).toContain('"claude"');
+        expect(output).toContain('"codex"');
+        expect(output).toContain('"gemini"');
+        expect(output).toContain('"available": true');
+    });
+    it('prints run help for the ai-cli entrypoint', () => {
+        const output = execFileSync('node', ['--import', 'tsx', 'src/bin/ai-cli.ts', 'run', '--help'], {
+            cwd: process.cwd(),
+            encoding: 'utf8',
+            env: process.env,
+        });
+        expect(output).toContain('Usage: ai-cli run --cwd <path> [options]');
+        expect(output).toContain('--model <model>');
+        expect(output).toContain('claude-ultra');
+    });
+});