jest-runner-cli 0.2.0 → 0.2.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 nojaja
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 nojaja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,349 +1,353 @@
-# jest-runner-cli
-
-> A custom Jest runner with an imperative CLI process helper for testing CLI applications.
-
-**jest-runner-cli** is a lightweight, ESM-native Jest runner package that provides:
-- A custom Jest runner built with `create-jest-runner` for seamless integration
-- A `CliRunner` helper class to spawn and interact with child processes in tests
-- Full support for stdout/stderr monitoring, JSON parsing, and process management
-
-Perfect for testing CLI tools, scripts, and command-line applications in your Jest test suite.
-
-## Features
-
-✅ **Custom Jest Runner** — Drop-in replacement for running tests with a custom runner  
-✅ **CliRunner Helper** — Easy-to-use imperative API for spawning and controlling CLI processes  
-✅ **Flexible Output Reading** — Read stdout as lines, raw text, or parse JSON  
-✅ **Auto-Exit Protection** — Automatically detect and terminate hung processes  
-✅ **Cross-Platform** — Works on Windows, macOS, and Linux  
-✅ **ESM Native** — Built with modern ESM module support  
-✅ **TypeScript Ready** — Full type definitions included  
-
-⚠️ **Limitations** — Advanced retry strategies and custom signal handling not yet implemented
-
-## Installation
-
-```bash
-npm install --save-dev jest-runner-cli
-```
-
-**Peer Dependency:** Jest ^29.6.1
-
-## Quick Start
-
-### 1. Configure Jest
-
-Update `jest.config.js`:
-
-```js
-// jest.config.js (ESM)
-export default {
-  runner: 'jest-runner-cli',
-  testMatch: ['<rootDir>/test/**/*.test.ts']
-};
-```
-
-### 2. Use in Tests
-
-```ts
-import { CliRunner } from 'jest-runner-cli';
-
-describe('CLI testing', () => {
-  it('runs node -v and captures output', async () => {
-    const cli = new CliRunner();
-    cli.start({ command: process.execPath, args: ['-v'] });
-    
-    const lines = await cli.readStdout().toLines(2000);
-    expect(lines[0]).toMatch(/^v\d+\.\d+\.\d+/);
-    
-    await cli.sendCtrlC();
-    cli.dispose();
-  });
-});
-```
-
-## Usage Guide
-
-### Jest Runner Configuration
-
-The package acts as a Jest custom runner. Once configured in `jest.config.js`, Jest will automatically use it to execute your test files.
-
-### CliRunner API
-
-#### Basic Usage
-
-```ts
-import { CliRunner } from 'jest-runner-cli';
-
-const runner = new CliRunner();
-
-// Start a process
-runner.start({
-  command: 'node',
-  args: ['./my-script.js'],
-  cwd: process.cwd(),
-  env: process.env
-});
-
-// Write to stdin
-runner.writeln('input data');
-
-// Read output
-const output = await runner.readStdout().toLines();
-
-// Gracefully stop
-await runner.sendCtrlC();
-runner.dispose();
-```
-
-#### Reading Output
-
-```ts
-// Read as array of lines
-const lines = await runner.readStdout().toLines(2000); // timeout in ms
-
-// Read as raw string
-const text = await runner.readStdout(2000);
-
-// Extract JSON
-const json = await runner.readStdout().toJson(2000);
-
-// Get stderr
-const errors = runner.readStderr();
-
-// Clear buffer
-runner.readStdout().clear();
-```
-
-#### Handling Process Events
-
-```ts
-// Listen for process exit
-runner.on('exit', ({ code, signal }) => {
-  console.log(`Process exited with code ${code}`);
-});
-
-// Auto-exit on timeout (e.g., hung process)
-runner.start({ command: 'node', args: ['long-running.js'] }, 5000); // 5s timeout
-
-// Listen for auto-exit error
-runner.once('error', (err) => {
-  if (err.message === 'auto-exit timeout reached') {
-    console.log('Process was auto-terminated');
-  }
-});
-```
-
-### Complete Example
-
-```ts
-import { CliRunner } from 'jest-runner-cli';
-
-describe('My CLI App', () => {
-  let cli: CliRunner;
-
-  beforeEach(() => {
-    cli = new CliRunner();
-  });
-
-  afterEach(async () => {
-    await cli.sendCtrlC().catch(() => {});
-    cli.dispose();
-  });
-
-  it('displays help text', async () => {
-    cli.start({ command: 'node', args: ['./bin/cli.js', '--help'] });
-    const output = await cli.readStdout().toLines(2000);
-    
-    expect(output.join('\n')).toContain('Usage:');
-  });
-
-  it('handles JSON output', async () => {
-    cli.start({ command: 'node', args: ['./bin/cli.js', '--json'] });
-    const data = await cli.readStdout().toJson(2000);
-    
-    expect(data).toHaveProperty('version');
-  });
-
-  it('detects hung process', async () => {
-    const error = await new Promise((resolve) => {
-      cli.once('error', resolve);
-      cli.start(
-        { command: 'node', args: ['-e', 'setTimeout(() => {}, 60000)'] },
-        3000 // 3s timeout
-      );
-    });
-
-    expect(error.message).toBe('auto-exit timeout reached');
-  });
-});
-```
-
-## API Reference
-
-### CliRunner
-
-#### Methods
-
-| Method | Parameters | Returns | Description |
-|--------|-----------|---------|-------------|
-| `start()` | `SpawnOptions`, `exitWaitTimeout?` | `this` | Spawn a child process. If `exitWaitTimeout` is set (ms), the process will auto-terminate if it doesn't exit within that time. |
-| `write()` | `data: string` | `void` | Write to stdin without a newline. |
-| `writeln()` | `data: string` | `void` | Write to stdin with a newline appended. |
-| `readStdout()` | `timeout?: number` | `Promise<string>` \| `OutputHelper` | Read stdout buffer. With timeout arg, returns raw string. Without arg, returns helper with `.toLines()`, `.toJson()`, `.clear()` methods. |
-| `readStderr()` | — | `string` | Get stderr buffer (non-blocking). |
-| `sendCtrlC()` | `timeout?: number` | `Promise<void>` | Send SIGINT and wait for process exit. Falls back to SIGKILL on timeout. |
-| `dispose()` | — | `void` | Force-kill process and release resources. |
-
-#### Events
-
-| Event | Callback Arguments | Description |
-|-------|-------------------|-------------|
-| `exit` | `{ code, signal }` | Process exited. |
-| `stdout` | `chunk: string` | Data received on stdout. |
-| `stderr` | `chunk: string` | Data received on stderr. |
-| `error` | `err: Error` | Error occurred (e.g., auto-exit timeout). |
-
-#### Types
-
-```ts
-type SpawnOptions = {
-  command?: string;        // Required: command to execute
-  args?: string[];         // Command arguments
-  cwd?: string;            // Working directory
-  env?: NodeJS.ProcessEnv; // Environment variables
-};
-```
-
-## Project Structure
-
-```
-jest-runner-cli/
-├── src/
-│   ├── index.ts          # Main entry point, Jest runner export
-│   ├── run.ts            # Jest runner implementation
-│   └── CliRunner.ts      # CliRunner class
-├── test/unit/
-│   └── cliRunner.test.ts # Unit tests
-├── dist/                 # Compiled output (generated)
-├── jest.config.js        # Jest configuration
-├── tsconfig.json         # TypeScript base config
-├── tsconfig.build.json   # TypeScript build config
-└── package.json          # Package metadata
-```
-
-## Development
-
-### Setup
-
-```bash
-git clone https://github.com/yourusername/jest-runner-cli.git
-cd jest-runner-cli
-npm install
-```
-
-### Common Commands
-
-```bash
-npm run build      # Compile TypeScript
-npm run test       # Run tests
-npm run lint       # Check code quality
-npm run type-check # Check TypeScript types
-npm run docs       # Generate TypeDoc documentation
-npm run depcruise  # Analyze dependencies
-```
-
-### Testing
-
-```bash
-# Run all tests
-npm test
-
-# Run specific test file
-npm test -- cliRunner.test.ts
-
-# Run with coverage
-npm run test:ci
-```
-
-## Technical Details
-
-- **Runtime:** Node.js 18+, TypeScript 5.3+
-- **Module Format:** ESM (ECMAScript Modules)
-- **Jest Version:** 29.6.1+
-- **Build:** TypeScript compiled to `dist/` folder
-- **No Bundler:** Raw JS output, no webpack or similar
-
-### Implementation Notes
-
-- The Jest runner is built using `create-jest-runner` and delegates to Jest's core `runTest` function
-- TypeScript is compiled with separate configs:
-  - `tsconfig.json` — development (no emit)
-  - `tsconfig.build.json` — build (emits to `dist/`)
-- `CliRunner` is based on Node.js `child_process.spawn()` with event-driven stdout/stderr handling
-- Auto-exit timeout uses `setTimeout` to detect hung processes and escalates from `SIGINT` to `SIGKILL`
-
-## Troubleshooting
-
-### Process Not Starting
-
-**Error:** `No command provided`
-
-```ts
-// ❌ Wrong
-runner.start({});
-
-// ✅ Correct
-runner.start({ command: 'node', args: ['script.js'] });
-```
-
-### Timeout Reading Output
-
-**Error:** `stdout timeout`
-
-Increase the timeout value:
-
-```ts
-// Default 2000ms, increase if needed
-const output = await runner.readStdout().toLines(5000);
-```
-
-### Process Still Running After sendCtrlC
-
-On Windows, the process may not respond to SIGINT. The runner will auto-escalate to force-kill after timeout:
-
-```ts
-// Will escalate to taskkill after 2000ms
-await runner.sendCtrlC();
-
-// Or specify custom timeout
-await runner.sendCtrlC(5000);
-```
-
-## Changelog
-
-### v0.2.0 (Current)
-
-- ✅ Refactored to ESM with `type: module`
-- ✅ Integrated with `create-jest-runner` for Jest runner functionality
-- ✅ Added comprehensive TypeScript type definitions
-- ✅ Added auto-exit timeout feature for hung process detection
-- ✅ Updated test suite with async/await patterns
-
-### v0.1.0
-
-- Initial release with basic `CliRunner` functionality
-
-## License
-
-MIT © 2026
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit issues or pull requests.
-
-For development, ensure:
-- TypeScript strict mode is enabled
-- All tests pass (`npm test`)
-- Linting passes (`npm run lint`)
-- New features include unit tests in `test/unit/`
+# jest-runner-cli
+
+[![日本語ドキュメント](https://img.shields.io/badge/docs-日本語-blue.svg)](https://github.com/nojaja/jest-runner-cli/blob/main/README_ja.md)
+
+**[English](./README.md)** | **[日本語](./README_ja.md)**
+
+> A custom Jest runner with an imperative CLI process helper for testing CLI applications.
+
+**jest-runner-cli** is a lightweight, ESM-native Jest runner package that provides:
+- A custom Jest runner built with `create-jest-runner` for seamless integration
+- A `CliRunner` helper class to spawn and interact with child processes in tests
+- Full support for stdout/stderr monitoring, JSON parsing, and process management
+
+Perfect for testing CLI tools, scripts, and command-line applications in your Jest test suite.
+
+## Features
+
+✅ **Custom Jest Runner** — Drop-in replacement for running tests with a custom runner  
+✅ **CliRunner Helper** — Easy-to-use imperative API for spawning and controlling CLI processes  
+✅ **Flexible Output Reading** — Read stdout as lines, raw text, or parse JSON  
+✅ **Auto-Exit Protection** — Automatically detect and terminate hung processes  
+✅ **Cross-Platform** — Works on Windows, macOS, and Linux  
+✅ **ESM Native** — Built with modern ESM module support  
+✅ **TypeScript Ready** — Full type definitions included  
+
+⚠️ **Limitations** — Advanced retry strategies and custom signal handling not yet implemented
+
+## Installation
+
+```bash
+npm install --save-dev jest-runner-cli
+```
+
+**Peer Dependency:** Jest ^29.6.1
+
+## Quick Start
+
+### 1. Configure Jest
+
+Update `jest.config.js`:
+
+```js
+// jest.config.js (ESM)
+export default {
+  runner: 'jest-runner-cli',
+  testMatch: ['<rootDir>/test/**/*.test.ts']
+};
+```
+
+### 2. Use in Tests
+
+```ts
+import { CliRunner } from 'jest-runner-cli';
+
+describe('CLI testing', () => {
+  it('runs node -v and captures output', async () => {
+    const cli = new CliRunner();
+    cli.start({ command: process.execPath, args: ['-v'] });
+    
+    const lines = await cli.readStdout().toLines(2000);
+    expect(lines[0]).toMatch(/^v\d+\.\d+\.\d+/);
+    
+    await cli.sendCtrlC();
+    cli.dispose();
+  });
+});
+```
+
+## Usage Guide
+
+### Jest Runner Configuration
+
+The package acts as a Jest custom runner. Once configured in `jest.config.js`, Jest will automatically use it to execute your test files.
+
+### CliRunner API
+
+#### Basic Usage
+
+```ts
+import { CliRunner } from 'jest-runner-cli';
+
+const runner = new CliRunner();
+
+// Start a process
+runner.start({
+  command: 'node',
+  args: ['./my-script.js'],
+  cwd: process.cwd(),
+  env: process.env
+});
+
+// Write to stdin
+runner.writeln('input data');
+
+// Read output
+const output = await runner.readStdout().toLines();
+
+// Gracefully stop
+await runner.sendCtrlC();
+runner.dispose();
+```
+
+#### Reading Output
+
+```ts
+// Read as array of lines
+const lines = await runner.readStdout().toLines(2000); // timeout in ms
+
+// Read as raw string
+const text = await runner.readStdout(2000);
+
+// Extract JSON
+const json = await runner.readStdout().toJson(2000);
+
+// Get stderr
+const errors = runner.readStderr();
+
+// Clear buffer
+runner.readStdout().clear();
+```
+
+#### Handling Process Events
+
+```ts
+// Listen for process exit
+runner.on('exit', ({ code, signal }) => {
+  console.log(`Process exited with code ${code}`);
+});
+
+// Auto-exit on timeout (e.g., hung process)
+runner.start({ command: 'node', args: ['long-running.js'] }, 5000); // 5s timeout
+
+// Listen for auto-exit error
+runner.once('error', (err) => {
+  if (err.message === 'auto-exit timeout reached') {
+    console.log('Process was auto-terminated');
+  }
+});
+```
+
+### Complete Example
+
+```ts
+import { CliRunner } from 'jest-runner-cli';
+
+describe('My CLI App', () => {
+  let cli: CliRunner;
+
+  beforeEach(() => {
+    cli = new CliRunner();
+  });
+
+  afterEach(async () => {
+    await cli.sendCtrlC().catch(() => {});
+    cli.dispose();
+  });
+
+  it('displays help text', async () => {
+    cli.start({ command: 'node', args: ['./bin/cli.js', '--help'] });
+    const output = await cli.readStdout().toLines(2000);
+    
+    expect(output.join('\n')).toContain('Usage:');
+  });
+
+  it('handles JSON output', async () => {
+    cli.start({ command: 'node', args: ['./bin/cli.js', '--json'] });
+    const data = await cli.readStdout().toJson(2000);
+    
+    expect(data).toHaveProperty('version');
+  });
+
+  it('detects hung process', async () => {
+    const error = await new Promise((resolve) => {
+      cli.once('error', resolve);
+      cli.start(
+        { command: 'node', args: ['-e', 'setTimeout(() => {}, 60000)'] },
+        3000 // 3s timeout
+      );
+    });
+
+    expect(error.message).toBe('auto-exit timeout reached');
+  });
+});
+```
+
+## API Reference
+
+### CliRunner
+
+#### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `start()` | `SpawnOptions`, `exitWaitTimeout?` | `this` | Spawn a child process. If `exitWaitTimeout` is set (ms), the process will auto-terminate if it doesn't exit within that time. |
+| `write()` | `data: string` | `void` | Write to stdin without a newline. |
+| `writeln()` | `data: string` | `void` | Write to stdin with a newline appended. |
+| `readStdout()` | `timeout?: number` | `Promise<string>` \| `OutputHelper` | Read stdout buffer. With timeout arg, returns raw string. Without arg, returns helper with `.toLines()`, `.toJson()`, `.clear()` methods. |
+| `readStderr()` | — | `string` | Get stderr buffer (non-blocking). |
+| `sendCtrlC()` | `timeout?: number` | `Promise<void>` | Send SIGINT and wait for process exit. Falls back to SIGKILL on timeout. |
+| `dispose()` | — | `void` | Force-kill process and release resources. |
+
+#### Events
+
+| Event | Callback Arguments | Description |
+|-------|-------------------|-------------|
+| `exit` | `{ code, signal }` | Process exited. |
+| `stdout` | `chunk: string` | Data received on stdout. |
+| `stderr` | `chunk: string` | Data received on stderr. |
+| `error` | `err: Error` | Error occurred (e.g., auto-exit timeout). |
+
+#### Types
+
+```ts
+type SpawnOptions = {
+  command?: string;        // Required: command to execute
+  args?: string[];         // Command arguments
+  cwd?: string;            // Working directory
+  env?: NodeJS.ProcessEnv; // Environment variables
+};
+```
+
+## Project Structure
+
+```
+jest-runner-cli/
+├── src/
+│   ├── index.ts          # Main entry point, Jest runner export
+│   ├── run.ts            # Jest runner implementation
+│   └── CliRunner.ts      # CliRunner class
+├── test/unit/
+│   └── cliRunner.test.ts # Unit tests
+├── dist/                 # Compiled output (generated)
+├── jest.config.js        # Jest configuration
+├── tsconfig.json         # TypeScript base config
+├── tsconfig.build.json   # TypeScript build config
+└── package.json          # Package metadata
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/yourusername/jest-runner-cli.git
+cd jest-runner-cli
+npm install
+```
+
+### Common Commands
+
+```bash
+npm run build      # Compile TypeScript
+npm run test       # Run tests
+npm run lint       # Check code quality
+npm run type-check # Check TypeScript types
+npm run docs       # Generate TypeDoc documentation
+npm run depcruise  # Analyze dependencies
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npm test -- cliRunner.test.ts
+
+# Run with coverage
+npm run test:ci
+```
+
+## Technical Details
+
+- **Runtime:** Node.js 18+, TypeScript 5.3+
+- **Module Format:** ESM (ECMAScript Modules)
+- **Jest Version:** 29.6.1+
+- **Build:** TypeScript compiled to `dist/` folder
+- **No Bundler:** Raw JS output, no webpack or similar
+
+### Implementation Notes
+
+- The Jest runner is built using `create-jest-runner` and delegates to Jest's core `runTest` function
+- TypeScript is compiled with separate configs:
+  - `tsconfig.json` — development (no emit)
+  - `tsconfig.build.json` — build (emits to `dist/`)
+- `CliRunner` is based on Node.js `child_process.spawn()` with event-driven stdout/stderr handling
+- Auto-exit timeout uses `setTimeout` to detect hung processes and escalates from `SIGINT` to `SIGKILL`
+
+## Troubleshooting
+
+### Process Not Starting
+
+**Error:** `No command provided`
+
+```ts
+// ❌ Wrong
+runner.start({});
+
+// ✅ Correct
+runner.start({ command: 'node', args: ['script.js'] });
+```
+
+### Timeout Reading Output
+
+**Error:** `stdout timeout`
+
+Increase the timeout value:
+
+```ts
+// Default 2000ms, increase if needed
+const output = await runner.readStdout().toLines(5000);
+```
+
+### Process Still Running After sendCtrlC
+
+On Windows, the process may not respond to SIGINT. The runner will auto-escalate to force-kill after timeout:
+
+```ts
+// Will escalate to taskkill after 2000ms
+await runner.sendCtrlC();
+
+// Or specify custom timeout
+await runner.sendCtrlC(5000);
+```
+
+## Changelog
+
+### v0.2.0 (Current)
+
+- ✅ Refactored to ESM with `type: module`
+- ✅ Integrated with `create-jest-runner` for Jest runner functionality
+- ✅ Added comprehensive TypeScript type definitions
+- ✅ Added auto-exit timeout feature for hung process detection
+- ✅ Updated test suite with async/await patterns
+
+### v0.1.0
+
+- Initial release with basic `CliRunner` functionality
+
+## License
+
+MIT © 2026
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+For development, ensure:
+- TypeScript strict mode is enabled
+- All tests pass (`npm test`)
+- Linting passes (`npm run lint`)
+- New features include unit tests in `test/unit/`

package/README_ja.md

@@ -0,0 +1,352 @@
+# jest-runner-cli
+
+**[English](./README.md)** | **[日本語](./README_ja.md)**
+
+> CLI アプリケーションをテストするためのカスタム Jest ランナーと命令型プロセスヘルパー
+
+**jest-runner-cli** は、軽量でESM対応のJestランナーパッケージです。以下の機能を提供します：
+
+- `create-jest-runner` で構築したカスタム Jest ランナーのシームレスな統合
+- テストから子プロセスを直接制御できる `CliRunner` ヘルパークラス
+- stdout/stderr 監視、JSON 解析、プロセス管理の完全サポート
+
+CLI ツール、スクリプト、コマンドラインアプリケーションを Jest テストスイートでテストするのに最適です。
+
+## 主な機能
+
+✅ **カスタム Jest ランナー** — テスト実行用のカスタムランナーとして使用可能  
+✅ **CliRunner ヘルパー** — 子プロセスのスポーン・制御が簡単な命令型API  
+✅ **柔軟な出力読み取り** — stdout を行単位・テキスト・JSON として読み取り可能  
+✅ **自動終了保護** — ハングしたプロセスを自動検知・終了  
+✅ **クロスプラットフォーム** — Windows、macOS、Linux で動作  
+✅ **ESM ネイティブ** — モダンな ESM モジュールサポート  
+✅ **TypeScript 対応** — 完全な型定義を付属  
+
+⚠️ **制限事項** — 高度なリトライ戦略やカスタムシグナル処理は未実装
+
+## インストール
+
+```bash
+npm install --save-dev jest-runner-cli
+```
+
+**ピア依存関係：** Jest ^29.6.1
+
+## クイックスタート
+
+### 1. Jest を設定
+
+`jest.config.js` を更新します：
+
+```js
+// jest.config.js (ESM)
+export default {
+  runner: 'jest-runner-cli',
+  testMatch: ['<rootDir>/test/**/*.test.ts']
+};
+```
+
+### 2. テストで使用
+
+```ts
+import { CliRunner } from 'jest-runner-cli';
+
+describe('CLI テスト', () => {
+  it('node -v を実行して出力をキャプチャ', async () => {
+    const cli = new CliRunner();
+    cli.start({ command: process.execPath, args: ['-v'] });
+    
+    const lines = await cli.readStdout().toLines(2000);
+    expect(lines[0]).toMatch(/^v\d+\.\d+\.\d+/);
+    
+    await cli.sendCtrlC();
+    cli.dispose();
+  });
+});
+```
+
+## 使用ガイド
+
+### Jest ランナーの設定
+
+このパッケージは Jest のカスタムランナーとして機能します。`jest.config.js` に設定されると、Jest がテストファイルを実行する際に自動的に使用されます。
+
+### CliRunner API
+
+#### 基本的な使い方
+
+```ts
+import { CliRunner } from 'jest-runner-cli';
+
+const runner = new CliRunner();
+
+// プロセスを開始
+runner.start({
+  command: 'node',
+  args: ['./my-script.js'],
+  cwd: process.cwd(),
+  env: process.env
+});
+
+// stdin に書き込み
+runner.writeln('入力データ');
+
+// 出力を読み取り
+const output = await runner.readStdout().toLines();
+
+// 正常に停止
+await runner.sendCtrlC();
+runner.dispose();
+```
+
+#### 出力の読み取り
+
+```ts
+// 行配列として読み取り
+const lines = await runner.readStdout().toLines(2000); // タイムアウト (ms)
+
+// 生のテキスト文字列として読み取り
+const text = await runner.readStdout(2000);
+
+// JSON を抽出
+const json = await runner.readStdout().toJson(2000);
+
+// stderr を取得
+const errors = runner.readStderr();
+
+// バッファをクリア
+runner.readStdout().clear();
+```
+
+#### プロセスイベントの処理
+
+```ts
+// プロセス終了を監視
+runner.on('exit', ({ code, signal }) => {
+  console.log(`プロセスが終了コード ${code} で終了`);
+});
+
+// タイムアウト時に自動終了（ハングしたプロセス等）
+runner.start({ command: 'node', args: ['long-running.js'] }, 5000); // 5秒タイムアウト
+
+// 自動終了エラーを監視
+runner.once('error', (err) => {
+  if (err.message === 'auto-exit timeout reached') {
+    console.log('プロセスが自動停止されました');
+  }
+});
+```
+
+### 完全な例
+
+```ts
+import { CliRunner } from 'jest-runner-cli';
+
+describe('My CLI App', () => {
+  let cli: CliRunner;
+
+  beforeEach(() => {
+    cli = new CliRunner();
+  });
+
+  afterEach(async () => {
+    await cli.sendCtrlC().catch(() => {});
+    cli.dispose();
+  });
+
+  it('ヘルプテキストを表示', async () => {
+    cli.start({ command: 'node', args: ['./bin/cli.js', '--help'] });
+    const output = await cli.readStdout().toLines(2000);
+    
+    expect(output.join('\n')).toContain('Usage:');
+  });
+
+  it('JSON 出力を処理', async () => {
+    cli.start({ command: 'node', args: ['./bin/cli.js', '--json'] });
+    const data = await cli.readStdout().toJson(2000);
+    
+    expect(data).toHaveProperty('version');
+  });
+
+  it('ハングしたプロセスを検知', async () => {
+    const error = await new Promise((resolve) => {
+      cli.once('error', resolve);
+      cli.start(
+        { command: 'node', args: ['-e', 'setTimeout(() => {}, 60000)'] },
+        3000 // 3秒タイムアウト
+      );
+    });
+
+    expect(error.message).toBe('auto-exit timeout reached');
+  });
+});
+```
+
+## API リファレンス
+
+### CliRunner
+
+#### メソッド
+
+| メソッド | パラメータ | 戻り値 | 説明 |
+|---------|-----------|--------|------|
+| `start()` | `SpawnOptions`, `exitWaitTimeout?` | `this` | 子プロセスをスポーンします。`exitWaitTimeout` を設定（ミリ秒）すると、その時間内にプロセスが終了しない場合は自動停止します。 |
+| `write()` | `data: string` | `void` | 改行なしで stdin に書き込み。 |
+| `writeln()` | `data: string` | `void` | 改行付きで stdin に書き込み。 |
+| `readStdout()` | `timeout?: number` | `Promise<string>` \| `OutputHelper` | stdout バッファを読み取り。タイムアウト引数あり：生テキスト返却。なし：`.toLines()`、`.toJson()`、`.clear()` メソッドを持つヘルパー返却。 |
+| `readStderr()` | — | `string` | stderr バッファを取得（ノンブロッキング）。 |
+| `sendCtrlC()` | `timeout?: number` | `Promise<void>` | SIGINT を送信してプロセス終了を待機。タイムアウト時は SIGKILL へエスカレート。 |
+| `dispose()` | — | `void` | プロセスを強制終了し、リソースを解放。 |
+
+#### イベント
+
+| イベント | コールバック引数 | 説明 |
+|---------|-----------------|------|
+| `exit` | `{ code, signal }` | プロセスが終了。 |
+| `stdout` | `chunk: string` | stdout でデータを受信。 |
+| `stderr` | `chunk: string` | stderr でデータを受信。 |
+| `error` | `err: Error` | エラー発生（例：自動終了タイムアウト）。 |
+
+#### 型
+
+```ts
+type SpawnOptions = {
+  command?: string;        // 必須：実行するコマンド
+  args?: string[];         // コマンド引数
+  cwd?: string;            // 作業ディレクトリ
+  env?: NodeJS.ProcessEnv; // 環境変数
+};
+```
+
+## プロジェクト構造
+
+```
+jest-runner-cli/
+├── src/
+│   ├── index.ts          # メインエントリーポイント、Jest ランナーのエクスポート
+│   ├── run.ts            # Jest ランナーの実装
+│   └── CliRunner.ts      # CliRunner クラス
+├── test/unit/
+│   └── cliRunner.test.ts # ユニットテスト
+├── dist/                 # コンパイル済み出力（自動生成）
+├── jest.config.js        # Jest 設定
+├── tsconfig.json         # TypeScript ベース設定
+├── tsconfig.build.json   # TypeScript ビルド設定
+└── package.json          # パッケージメタデータ
+```
+
+## 開発
+
+### セットアップ
+
+```bash
+git clone https://github.com/yourusername/jest-runner-cli.git
+cd jest-runner-cli
+npm install
+```
+
+### 一般的なコマンド
+
+```bash
+npm run build      # TypeScript をコンパイル
+npm run test       # テストを実行
+npm run lint       # コード品質をチェック
+npm run type-check # TypeScript の型をチェック
+npm run docs       # TypeDoc ドキュメントを生成
+npm run depcruise  # 依存関係を分析
+```
+
+### テスト実行
+
+```bash
+# すべてのテストを実行
+npm test
+
+# 特定のテストファイルを実行
+npm test -- cliRunner.test.ts
+
+# カバレッジ付きで実行
+npm run test:ci
+```
+
+## 技術的詳細
+
+- **ランタイム：** Node.js 18+、TypeScript 5.3+
+- **モジュール形式：** ESM（ECMAScript Modules）
+- **Jest バージョン：** 29.6.1+
+- **ビルド：** TypeScript を `dist/` フォルダにコンパイル
+- **バンドラなし：** webpack 等を使わない生の JavaScript 出力
+
+### 実装に関する注
+
+- Jest ランナーは `create-jest-runner` を使用して構築され、Jest のコア `runTest` 関数に委譲します
+- TypeScript は個別の設定でコンパイルされます：
+  - `tsconfig.json` — 開発用（エミットなし）
+  - `tsconfig.build.json` — ビルド用（`dist/` にエミット）
+- `CliRunner` は Node.js の `child_process.spawn()` をベースに、イベント駆動の stdout/stderr 処理で実装されています
+- 自動終了タイムアウトは `setTimeout` を使用してハングしたプロセスを検知し、`SIGINT` から `SIGKILL` へエスカレートします
+
+## トラブルシューティング
+
+### プロセスが開始されない
+
+**エラー：** `No command provided`
+
+```ts
+// ❌ 間違い
+runner.start({});
+
+// ✅ 正しい
+runner.start({ command: 'node', args: ['script.js'] });
+```
+
+### 出力読み取りのタイムアウト
+
+**エラー：** `stdout timeout`
+
+タイムアウト値を増やしてください：
+
+```ts
+// デフォルト 2000ms、必要に応じて増加
+const output = await runner.readStdout().toLines(5000);
+```
+
+### sendCtrlC 後もプロセスが実行中
+
+Windows ではプロセスが SIGINT に応答しない場合があります。ランナーはタイムアウト後に自動的に強制終了にエスカレートします：
+
+```ts
+// 2000ms 後に taskkill へエスカレート
+await runner.sendCtrlC();
+
+// またはカスタムタイムアウトを指定
+await runner.sendCtrlC(5000);
+```
+
+## 変更履歴
+
+### v0.2.0（現在）
+
+- ✅ `type: module` を使用した ESM への再構築
+- ✅ `create-jest-runner` を使用した Jest ランナー機能の統合
+- ✅ 包括的な TypeScript 型定義の追加
+- ✅ ハングしたプロセス検知のための自動終了タイムアウト機能を追加
+- ✅ async/await パターンでのテストスイートの更新
+
+### v0.1.0
+
+- `CliRunner` の基本機能での初回リリース
+
+## ライセンス
+
+MIT © 2026
+
+## コントリビューション
+
+問題報告やプルリクエストを大歓迎します！
+
+開発時は以下の項目を確認してください：
+- TypeScript 厳密モードが有効になっていること
+- すべてのテストが成功すること（`npm test`）
+- リント・チェックが成功すること（`npm run lint`）
+- 新機能には `test/unit/` にユニットテストを含めること

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { CliRunner } from './CliRunner.js';
 export { CliRunner };
 export type { SpawnOptions } from './CliRunner.js';
-declare const JestRunnerCli: unknown;
+declare const JestRunnerCli: any;
 export default JestRunnerCli;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAInD,QAAA,MAAM,aAAa,SAA4B,CAAC;AAEhD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAOnD,QAAA,MAAM,aAAa,KAA4B,CAAC;AAEhD,eAAe,aAAa,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
-import createJestRunner from 'create-jest-runner';
+import { createRequire } from 'module';
 import { CliRunner } from './CliRunner.js';
 export { CliRunner };
+const require = createRequire(import.meta.url);
+const { createJestRunner } = require('create-jest-runner');
 const runPath = new URL('./run.js', import.meta.url).pathname;
 const JestRunnerCli = createJestRunner(runPath);
 export default JestRunnerCli;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,gBAAgB,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,CAAC;AAGrB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;AAE9D,MAAM,aAAa,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAEhD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,CAAC;AAGrB,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAE3D,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;AAE9D,MAAM,aAAa,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAEhD,eAAe,aAAa,CAAC"}

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AAGxC;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,GAAG,CACzB,YAAY,EAAE,MAAM,CAAC,YAAY,EACjC,aAAa,EAAE,MAAM,CAAC,aAAa,EACnC,WAAW,EAAE,eAAe,EAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,oBAGjB"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AAKxC;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,GAAG,CACzB,YAAY,EAAE,MAAM,CAAC,YAAY,EACjC,aAAa,EAAE,MAAM,CAAC,aAAa,EACnC,WAAW,EAAE,eAAe,EAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,oBAGjB"}

package/dist/run.js

@@ -1,3 +1,4 @@
+// jest-runner �� runTest �֐��𒼐ڎ擾
 import runTest from 'jest-runner/build/runTest.js';
 /**
  * Jest runner entry point that delegates to the core runTest helper.

package/dist/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAGA,OAAO,OAAO,MAAM,8BAA8B,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,GAAG,CACzB,YAAiC,EACjC,aAAmC,EACnC,WAA4B,EAC5B,OAAgB,EAChB,QAAgB;IAEhB,OAAO,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAIA,kCAAkC;AAClC,OAAO,OAAO,MAAM,8BAA8B,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,GAAG,CACzB,YAAiC,EACjC,aAAmC,EACnC,WAA4B,EAC5B,OAAgB,EAChB,QAAgB;IAEhB,OAAO,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;AAC9E,CAAC"}

package/package.json

@@ -1,59 +1,63 @@
-{
-  "name": "jest-runner-cli",
-  "version": "0.2.0",
-  "description": "Jest custom runner for CLI workflows with a minimal CliRunner helper",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": "./dist/index.js",
-    "./run": "./dist/run.js",
-    "./CliRunner": "./dist/CliRunner.js"
-  },
-  "files": [
-    "dist",
-    "package.json",
-    "README.md",
-    "LICENSE"
-  ],
-  "type": "module",
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "type-check": "tsc --noEmit",
-    "test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js",
-    "test:ci": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --coverage",
-    "lint": "eslint . --ext .ts",
-    "depcruise": "depcruise --config .dependency-cruiser.cjs src",
-    "docs": "typedoc --options typedoc.json"
-  },
-  "keywords": ["cli", "runner", "test", "jest"],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/gutyoh/jest-runner-cli.git"
-  },
-  "bugs": {
-    "url": "https://github.com/gutyoh/jest-runner-cli/issues"
-  },
-  "homepage": "https://github.com/gutyoh/jest-runner-cli#readme",
-  "license": "MIT",
-  "peerDependencies": {
-    "jest": "^29.6.1"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.2",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "dependency-cruiser": "^17.3.5",
-    "eslint": "^8.45.0",
-    "eslint-plugin-jsdoc": "^46.0.0",
-    "eslint-plugin-sonarjs": "^0.19.0",
-    "jest": "^29.6.1",
-    "ts-jest": "^29.1.0",
-    "typedoc": "^0.28.0",
-    "typedoc-plugin-markdown": "^4.8.0",
-    "typescript": "5.3.3"
-  },
-  "dependencies": {
-    "create-jest-runner": "^1.0.0",
-    "jest-runner": "^29.6.1"
-  }
-}
+{
+  "name": "jest-runner-cli",
+  "version": "0.2.2",
+  "description": "Jest custom runner for CLI workflows with a minimal CliRunner helper",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./run": "./dist/run.js",
+    "./CliRunner": "./dist/CliRunner.js"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "README_ja.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js",
+    "test:ci": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --coverage",
+    "test:integration": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config jest.integration.config.cjs",
+    "test:all": "npm run build && npm run test && npm run test:integration",
+    "lint": "eslint . --ext .ts",
+    "depcruise": "depcruise --config .dependency-cruiser.cjs src",
+    "docs": "typedoc --options typedoc.json"
+  },
+  "keywords": ["cli", "runner", "test", "jest"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nojaja/jest-runner-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nojaja/jest-runner-cli/issues"
+  },
+  "homepage": "https://github.com/nojaja/jest-runner-cli#readme",
+  "author": "nojaja <free.riccia@gmail.com> (https://github.com/nojaja)",
+  "license": "MIT",
+  "peerDependencies": {
+    "jest": "^29.6.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.2",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "dependency-cruiser": "^17.3.5",
+    "eslint": "^8.45.0",
+    "eslint-plugin-jsdoc": "^46.0.0",
+    "eslint-plugin-sonarjs": "^0.19.0",
+    "jest": "^29.6.1",
+    "ts-jest": "^29.1.0",
+    "typedoc": "^0.28.0",
+    "typedoc-plugin-markdown": "^4.8.0",
+    "typescript": "5.3.3"
+  },
+  "dependencies": {
+    "create-jest-runner": "^1.0.0",
+    "jest-runner": "^29.6.1"
+  }
+}