@mcpeak/cli 0.9.0 → 0.11.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 OhMyMCP contributors
+Copyright (c) 2026 MCPeak contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -22,7 +22,7 @@ mcpeak test packages/cli/tests/fixtures/weather-suite.json \
   --arg examples/weather-server/server.mjs
 ```
 
-문법은 `mcpeak test <suite.json> --command <executable> [--arg <value> ...] [--json] [--junit <path>] [--stderr-lines <N>]`입니다. 위 예시의 command와 arg는 `node examples/weather-server/server.mjs`로 실행됩니다. `--arg`는 반복할 수 있고, 하이픈으로 시작하는 값은 `--arg=-m`, 빈 값은 `--arg=`로 전달합니다.
+문법은 `mcpeak test <suite.json> --command <executable> [--arg <value> ...] [--json] [--junit <path>] [--stderr-lines <N>] [--record-session <path> | --session <path>]`입니다. 위 예시의 command와 arg는 `node examples/weather-server/server.mjs`로 실행됩니다. `--arg`는 반복할 수 있고, 하이픈으로 시작하는 값은 `--arg=-m`, 빈 값은 `--arg=`로 전달합니다.
 
 stdout에는 보고서만 나갑니다. 기본은 사람이 읽는 보고서이고, `--json`을 주면 `RunnerReport` JSON이 나갑니다. CLI 오류와 서버 프로세스 진단은 stderr로만 나가므로 `--json > report.json`이 깨지지 않습니다. 모든 테스트가 통과하면 종료 코드 0을, failed 또는 aborted report와 입력, 연결, 종료 오류에는 1을 반환합니다.
 
@@ -40,6 +40,11 @@ XML을 만드는 단계에서 실패하면 `CLI_INTERNAL_ERROR`와 함께 종료
 
 `RunnerReport`에는 시간 정보가 없어 모든 `time` 속성은 `0`입니다. "0초 걸렸다"가 아니라 "시간 정보를 갖고 있지 않다"는 뜻입니다. 근거는 [ADR-0016](../../docs/adr/0016-junit-time-속성-고정.md), 플래그 설계는 [ADR-0019](../../docs/adr/0019-junit-리포터-cli-노출-방식.md)에 있습니다.
 
+`--record-session <path>`는 서버가 `globalThis.fetch`로 호출한 외부 HTTP 응답을 녹화하고,
+`--session <path>`는 그 녹화본을 재생합니다. 서버는 재생 때도 실제로 실행됩니다. `node:http`와
+`node:https` 계층 호출은 범위 밖이라 실제 네트워크로 나갈 수 있으며, CLI는 녹화 0건이나 재생
+0건처럼 범위 밖 호출이 의심되는 실행을 stderr 알림으로 드러냅니다.
+
 `--stderr-lines <N>`은 실패했거나 서버가 비정상 종료·중단했을 때, 진단 내용이 있으면 stderr에 붙는 서버 프로세스 진단 블록의 stderr 표시 줄 수입니다. 기본값은 20이고, `0`을 주면 블록을 완전히 끕니다(그때 출력 바이트는 이 기능이 없던 때와 같습니다). 블록에는 종료 코드와 시그널, 서버가 남긴 stderr의 마지막 N줄이 담기며 잘린 사실은 헤더에 적힙니다. 서버가 정상 종료했고 stderr도 비어 있으면 보여줄 근거가 없으므로 블록을 쓰지 않습니다.
 
 ### 승인 지문 대조
@@ -56,11 +61,16 @@ XML을 만드는 단계에서 실패하면 `CLI_INTERNAL_ERROR`와 함께 종료
 
 전부 통과인데 불일치일 때만 예외를 두는 이유는 승인받지 않은 명세로 초록불이 뜬 상태이기 때문입니다. 그 사실은 실패보다 오히려 조용히 지나가기 쉽습니다.
 
+현재 명세에서 계산한 지문과 저장된 `approval.fingerprint`가 불일치하면 전부 통과했는지 실패가
+있는지에 맞춰 상황을 구분해 알립니다. 지문 두 개만으로는 구체적인 변경 내용을 복원할 수 없으므로
+버전 관리에서 명세를 비교하도록 안내하고, 의도한 변경이면 같은 설정의 `mcpeak generate`에
+`--force`를 붙여 다시 생성·승인하도록 안내합니다.
+
 명세 줄은 보고서 본문 뒤에 빈 줄 하나를 두고 stdout으로 나갑니다. `--json`에는 위 억제 규칙을 적용하지 않고 `spec` 키를 항상 넣습니다(`approval`은 `matched` · `mismatched` · `absent` 중 하나, `fingerprint`는 실행 시점 계산값, `approvedFingerprint`는 파일에 적힌 값이며 `absent`면 키가 없습니다). 기계가 읽는 출력에서 키가 조건부로 사라지면 소비자가 분기를 하나 더 써야 합니다. 기존 보고서 키는 그대로이므로 기존 소비자는 깨지지 않습니다.
 
 지문이 없는 명세도 정상입니다. 손으로 쓴 명세와 이 기능 이전에 만든 명세가 여기에 해당하며 실패로 취급하지 않습니다.
 
-현재는 UTF-8 JSON 단일 명세와 stdio 서버만 지원합니다. shell 문법, 여러 명세, TypeScript 모듈 명세는 지원하지 않습니다. `record`, `replay`, `mock` 명령은 아직 구현되지 않았습니다.
+현재는 UTF-8 JSON 단일 명세와 stdio 서버만 지원합니다. shell 문법, 여러 명세, TypeScript 모듈 명세는 지원하지 않습니다. `record`, `mock` 명령은 아직 구현되지 않았습니다.
 
 ## generate
 

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 //#region src/cli.ts
-require("./src-Df8147pD.cjs").run(process.argv.slice(2)).then((code) => {
+require("./index.cjs").run(process.argv.slice(2)).then((code) => {
 	process.exitCode = code;
 });
 //#endregion

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as run } from "./src-D1NW6ckv.mjs";
+import { run } from "./index.mjs";
 //#region src/cli.ts
 run(process.argv.slice(2)).then((code) => {
 	process.exitCode = code;

package/dist/commands.cjs

@@ -1,11 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_test_command = require("./test-command-BZ_94UmI.cjs");
+const require_test_command = require("./test-command-B_faNSfA.cjs");
 exports.nodeGenerateDependencies = require_test_command.nodeGenerateDependencies;
 exports.nodeReviewIO = require_test_command.nodeReviewIO;
 exports.parseRepairCommand = require_test_command.parseRepairCommand;
-exports.parseReplayCommand = require_test_command.parseReplayCommand;
 exports.parseTestCommand = require_test_command.parseTestCommand;
 exports.runCli = require_test_command.runCli;
 exports.runGenerateCommand = require_test_command.runGenerateCommand;
 exports.runRepairCommand = require_test_command.runRepairCommand;
-exports.runReplayCommand = require_test_command.runReplayCommand;

package/dist/commands.d.cts

@@ -1,11 +1,18 @@
-import { a as RepairCommandDependencies, c as runRepairCommand, d as ReviewIO, f as nodeGenerateDependencies, i as runReplayCommand, l as GenerateCommandDependencies, m as runGenerateCommand, n as ReplayCommandInput, o as RepairCommandInput, p as nodeReviewIO, r as parseReplayCommand, s as parseRepairCommand, t as ReplayCommandDependencies, u as GenerateCommandInput } from "./replay-command-V0ZSJPiD.cjs";
-import { McpStdioConnection } from "@mcpeak/core";
+import { a as GenerateCommandDependencies, c as nodeGenerateDependencies, d as ConnectTarget, i as runRepairCommand, l as nodeReviewIO, n as RepairCommandInput, o as GenerateCommandInput, r as parseRepairCommand, s as ReviewIO, t as RepairCommandDependencies, u as runGenerateCommand } from "./repair-command-D3zL3G5W.cjs";
+import { McpHttpConnection, McpStdioConnection } from "@mcpeak/core";
 import { CheckDeterminismOptions, DeterminismResult, FinalizeRunnerExecutionOptions, InputContractOptions, RunSuiteOptions, RunnerExecution, RunnerReport, SpecFindingsResult, SuiteValidationIssue, SuiteValidationResult, TestSuiteSpec } from "@mcpeak/runner";
+import "@mcpeak/record/external";
 //#region src/test-command.d.ts
 interface TestCommandInput {
   readonly suitePath: string;
-  readonly command: string;
-  readonly args: readonly string[];
+  /**
+   * 붙을 대상. `--command`/`--arg` 면 stdio, `--url` 이면 Streamable HTTP 다(#137).
+   *
+   * `command` · `args` 두 필드를 이 하나로 바꿨다. 두 transport 를 나란히 두면 "url 이
+   * 있으면 command 는 무시" 같은 규칙이 읽는 자리마다 되풀이되고, 그 규칙이 한 군데서만
+   * 어긋나도 사용자가 지정하지 않은 곳에 붙는다.
+   */
+  readonly target: ConnectTarget;
   readonly json: boolean;
   /** `--junit` 로 받은 XML 출력 경로. 지정하지 않으면 undefined 이고 XML 을 만들지 않는다. */
   readonly junitPath: string | undefined;
@@ -15,9 +22,13 @@ interface TestCommandInput {
   readonly determinism: boolean;
   /** `--reset-cmd` 로 받은 초기화 명령. 각 회차 전에 1번씩 실행한다. */
   readonly resetCmd: string | undefined;
+  /** `--session`. External 세션을 재생한다. */
+  readonly sessionPath: string | undefined;
+  /** `--record-session`. External 세션을 녹화한다. */
+  readonly recordSessionPath: string | undefined;
   readonly stderrLines: number;
 }
-type CliErrorCode = "CLI_USAGE" | "COMMAND_NOT_IMPLEMENTED" | "SUITE_FORMAT_UNSUPPORTED" | "SUITE_READ_FAILED" | "SUITE_ENCODING_INVALID" | "SUITE_JSON_INVALID" | "SUITE_VALIDATION_FAILED" | "MCP_CONNECTION_FAILED" | "RUNNER_EXECUTION_FAILED" | "RUNNER_FINALIZATION_FAILED" | "JUNIT_WRITE_FAILED" | "REPAIR_BUNDLE_WRITE_FAILED" | "RESET_COMMAND_FAILED" | "CLI_INTERNAL_ERROR";
+type CliErrorCode = "CLI_USAGE" | "COMMAND_NOT_IMPLEMENTED" | "SUITE_FORMAT_UNSUPPORTED" | "SUITE_READ_FAILED" | "SUITE_ENCODING_INVALID" | "SUITE_JSON_INVALID" | "SUITE_VALIDATION_FAILED" | "MCP_CONNECTION_FAILED" | "RUNNER_EXECUTION_FAILED" | "RUNNER_FINALIZATION_FAILED" | "RUNNER_PAYLOAD_LIMIT_EXCEEDED" | "JUNIT_WRITE_FAILED" | "REPAIR_BUNDLE_WRITE_FAILED" | "RESET_COMMAND_FAILED" | "EXTERNAL_SESSION_FAILED" | "CLI_INTERNAL_ERROR";
 interface CliFailure {
   readonly code: CliErrorCode;
   readonly message: string;
@@ -31,7 +42,25 @@ interface TestCommandDependencies {
   connect(options: {
     command: string;
     args: readonly string[];
+    /** External 배선이 만든 자식 환경 변수. Bootstrap 주입이 여기 실린다. */
+    env?: Readonly<Record<string, string>>;
   }): Promise<McpStdioConnection>;
+  /**
+   * 원격(Streamable HTTP) 대상용 연결. `core.connectHttp` 다.
+   *
+   * **선택 사항으로 둔다.** 위 `checkInputContract` 와 같은 이유다 — 진입점의 "런타임 의존성
+   * 없음" 경로와 대시보드처럼 stdio 만 배선한 호출자가 이 필드를 채울 수 없다. 없으면
+   * `--url` 이 조용히 stdio 로 떨어지지 않고 무엇이 없는지 말하고 멈춘다(#137).
+   */
+  connectHttp?(options: {
+    url: string;
+    headers?: Readonly<Record<string, string>>;
+  }): Promise<McpHttpConnection>;
+  /**
+   * `--header-env` 가 가리키는 환경변수를 읽는다. 이것이 없으면 `--header-env` 를 쓸 수 없다.
+   * CLI 코드가 `process` 를 직접 읽지 않기 위한 주입점이다(ADR-0013).
+   */
+  readEnv?(name: string): string | undefined;
   startRunner(options: RunSuiteOptions): RunnerExecution;
   finalize(options: FinalizeRunnerExecutionOptions): Promise<RunnerReport>;
   renderReport(report: RunnerReport, options?: {
@@ -62,6 +91,15 @@ interface TestCommandDependencies {
   writeStderr(text: string): void;
 }
 declare function parseTestCommand(argv: readonly string[]): TestCommandInput;
+/**
+ * `test` 실행에 External Record/Replay 수명주기를 씌운다.
+ *
+ * Coordinator 를 **먼저 열고 마지막에 닫는다**(ADR-0052). 그 사이에 들어가는 것이 기존 실행
+ * 전부라, 성공·실패·예외 어느 경로로 빠져나가도 `finish` 가 불려야 한다. 안 불리면 SQLite
+ * 파일 핸들이 남고 Record 세션이 `running` 인 채로 남아 다음 실행이 이어 쓸 수 없다.
+ *
+ * 세션 옵션이 없으면 배선을 아예 만들지 않는다 — 기존 실행 경로가 한 글자도 달라지지 않는다.
+ */
 declare function runCli(argv: readonly string[], dependencies: TestCommandDependencies): Promise<number>;
 //#endregion
-export { type CliErrorCode, type CliFailure, type GenerateCommandDependencies, type GenerateCommandInput, type RepairCommandDependencies, type RepairCommandInput, type ReplayCommandDependencies, type ReplayCommandInput, type ReviewIO, type TestCommandDependencies, type TestCommandInput, nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseReplayCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand, runReplayCommand };
+export { type CliErrorCode, type CliFailure, type GenerateCommandDependencies, type GenerateCommandInput, type RepairCommandDependencies, type RepairCommandInput, type ReviewIO, type TestCommandDependencies, type TestCommandInput, nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand };

package/dist/commands.d.mts

@@ -1,11 +1,18 @@
-import { a as RepairCommandDependencies, c as runRepairCommand, d as ReviewIO, f as nodeGenerateDependencies, i as runReplayCommand, l as GenerateCommandDependencies, m as runGenerateCommand, n as ReplayCommandInput, o as RepairCommandInput, p as nodeReviewIO, r as parseReplayCommand, s as parseRepairCommand, t as ReplayCommandDependencies, u as GenerateCommandInput } from "./replay-command-BAtSzf8R.mjs";
+import { a as GenerateCommandDependencies, c as nodeGenerateDependencies, d as ConnectTarget, i as runRepairCommand, l as nodeReviewIO, n as RepairCommandInput, o as GenerateCommandInput, r as parseRepairCommand, s as ReviewIO, t as RepairCommandDependencies, u as runGenerateCommand } from "./repair-command-DQh2h4tQ.mjs";
 import { CheckDeterminismOptions, DeterminismResult, FinalizeRunnerExecutionOptions, InputContractOptions, RunSuiteOptions, RunnerExecution, RunnerReport, SpecFindingsResult, SuiteValidationIssue, SuiteValidationResult, TestSuiteSpec } from "@mcpeak/runner";
-import { McpStdioConnection } from "@mcpeak/core";
+import { McpHttpConnection, McpStdioConnection } from "@mcpeak/core";
+import "@mcpeak/record/external";
 //#region src/test-command.d.ts
 interface TestCommandInput {
   readonly suitePath: string;
-  readonly command: string;
-  readonly args: readonly string[];
+  /**
+   * 붙을 대상. `--command`/`--arg` 면 stdio, `--url` 이면 Streamable HTTP 다(#137).
+   *
+   * `command` · `args` 두 필드를 이 하나로 바꿨다. 두 transport 를 나란히 두면 "url 이
+   * 있으면 command 는 무시" 같은 규칙이 읽는 자리마다 되풀이되고, 그 규칙이 한 군데서만
+   * 어긋나도 사용자가 지정하지 않은 곳에 붙는다.
+   */
+  readonly target: ConnectTarget;
   readonly json: boolean;
   /** `--junit` 로 받은 XML 출력 경로. 지정하지 않으면 undefined 이고 XML 을 만들지 않는다. */
   readonly junitPath: string | undefined;
@@ -15,9 +22,13 @@ interface TestCommandInput {
   readonly determinism: boolean;
   /** `--reset-cmd` 로 받은 초기화 명령. 각 회차 전에 1번씩 실행한다. */
   readonly resetCmd: string | undefined;
+  /** `--session`. External 세션을 재생한다. */
+  readonly sessionPath: string | undefined;
+  /** `--record-session`. External 세션을 녹화한다. */
+  readonly recordSessionPath: string | undefined;
   readonly stderrLines: number;
 }
-type CliErrorCode = "CLI_USAGE" | "COMMAND_NOT_IMPLEMENTED" | "SUITE_FORMAT_UNSUPPORTED" | "SUITE_READ_FAILED" | "SUITE_ENCODING_INVALID" | "SUITE_JSON_INVALID" | "SUITE_VALIDATION_FAILED" | "MCP_CONNECTION_FAILED" | "RUNNER_EXECUTION_FAILED" | "RUNNER_FINALIZATION_FAILED" | "JUNIT_WRITE_FAILED" | "REPAIR_BUNDLE_WRITE_FAILED" | "RESET_COMMAND_FAILED" | "CLI_INTERNAL_ERROR";
+type CliErrorCode = "CLI_USAGE" | "COMMAND_NOT_IMPLEMENTED" | "SUITE_FORMAT_UNSUPPORTED" | "SUITE_READ_FAILED" | "SUITE_ENCODING_INVALID" | "SUITE_JSON_INVALID" | "SUITE_VALIDATION_FAILED" | "MCP_CONNECTION_FAILED" | "RUNNER_EXECUTION_FAILED" | "RUNNER_FINALIZATION_FAILED" | "RUNNER_PAYLOAD_LIMIT_EXCEEDED" | "JUNIT_WRITE_FAILED" | "REPAIR_BUNDLE_WRITE_FAILED" | "RESET_COMMAND_FAILED" | "EXTERNAL_SESSION_FAILED" | "CLI_INTERNAL_ERROR";
 interface CliFailure {
   readonly code: CliErrorCode;
   readonly message: string;
@@ -31,7 +42,25 @@ interface TestCommandDependencies {
   connect(options: {
     command: string;
     args: readonly string[];
+    /** External 배선이 만든 자식 환경 변수. Bootstrap 주입이 여기 실린다. */
+    env?: Readonly<Record<string, string>>;
   }): Promise<McpStdioConnection>;
+  /**
+   * 원격(Streamable HTTP) 대상용 연결. `core.connectHttp` 다.
+   *
+   * **선택 사항으로 둔다.** 위 `checkInputContract` 와 같은 이유다 — 진입점의 "런타임 의존성
+   * 없음" 경로와 대시보드처럼 stdio 만 배선한 호출자가 이 필드를 채울 수 없다. 없으면
+   * `--url` 이 조용히 stdio 로 떨어지지 않고 무엇이 없는지 말하고 멈춘다(#137).
+   */
+  connectHttp?(options: {
+    url: string;
+    headers?: Readonly<Record<string, string>>;
+  }): Promise<McpHttpConnection>;
+  /**
+   * `--header-env` 가 가리키는 환경변수를 읽는다. 이것이 없으면 `--header-env` 를 쓸 수 없다.
+   * CLI 코드가 `process` 를 직접 읽지 않기 위한 주입점이다(ADR-0013).
+   */
+  readEnv?(name: string): string | undefined;
   startRunner(options: RunSuiteOptions): RunnerExecution;
   finalize(options: FinalizeRunnerExecutionOptions): Promise<RunnerReport>;
   renderReport(report: RunnerReport, options?: {
@@ -62,6 +91,15 @@ interface TestCommandDependencies {
   writeStderr(text: string): void;
 }
 declare function parseTestCommand(argv: readonly string[]): TestCommandInput;
+/**
+ * `test` 실행에 External Record/Replay 수명주기를 씌운다.
+ *
+ * Coordinator 를 **먼저 열고 마지막에 닫는다**(ADR-0052). 그 사이에 들어가는 것이 기존 실행
+ * 전부라, 성공·실패·예외 어느 경로로 빠져나가도 `finish` 가 불려야 한다. 안 불리면 SQLite
+ * 파일 핸들이 남고 Record 세션이 `running` 인 채로 남아 다음 실행이 이어 쓸 수 없다.
+ *
+ * 세션 옵션이 없으면 배선을 아예 만들지 않는다 — 기존 실행 경로가 한 글자도 달라지지 않는다.
+ */
 declare function runCli(argv: readonly string[], dependencies: TestCommandDependencies): Promise<number>;
 //#endregion
-export { type CliErrorCode, type CliFailure, type GenerateCommandDependencies, type GenerateCommandInput, type RepairCommandDependencies, type RepairCommandInput, type ReplayCommandDependencies, type ReplayCommandInput, type ReviewIO, type TestCommandDependencies, type TestCommandInput, nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseReplayCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand, runReplayCommand };
+export { type CliErrorCode, type CliFailure, type GenerateCommandDependencies, type GenerateCommandInput, type RepairCommandDependencies, type RepairCommandInput, type ReviewIO, type TestCommandDependencies, type TestCommandInput, nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand };

package/dist/commands.mjs

@@ -1,2 +1,2 @@
-import { a as runReplayCommand, c as nodeGenerateDependencies, i as parseReplayCommand, l as nodeReviewIO, n as runCli, o as parseRepairCommand, s as runRepairCommand, t as parseTestCommand, u as runGenerateCommand } from "./test-command-CsJfojut.mjs";
-export { nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseReplayCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand, runReplayCommand };
+import { a as nodeGenerateDependencies, i as runRepairCommand, n as runCli, o as nodeReviewIO, r as parseRepairCommand, s as runGenerateCommand, t as parseTestCommand } from "./test-command-DEp9hrfH.mjs";
+export { nodeGenerateDependencies, nodeReviewIO, parseRepairCommand, parseTestCommand, runCli, runGenerateCommand, runRepairCommand };

package/dist/index.cjs

@@ -1,6 +1,220 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-Df8147pD.cjs");
-exports.COMMANDS = require_src.COMMANDS;
-exports.nodeRepairDependencies = require_src.nodeRepairDependencies;
-exports.run = require_src.run;
-exports.unavailableReplayDependencies = require_src.unavailableReplayDependencies;
+const require_test_command = require("./test-command-B_faNSfA.cjs");
+let node_fs_promises = require("node:fs/promises");
+//#region src/index.ts
+const COMMANDS = [
+	"test",
+	"generate",
+	"repair",
+	"record",
+	"mock"
+];
+const unavailableDependencies = {
+	readFile: async () => {
+		throw new Error("runtime dependencies unavailable");
+	},
+	validateSuite: () => {
+		throw new Error("runtime dependencies unavailable");
+	},
+	connect: async () => {
+		throw new Error("runtime dependencies unavailable");
+	},
+	startRunner: () => {
+		throw new Error("runtime dependencies unavailable");
+	},
+	finalize: async () => {
+		throw new Error("runtime dependencies unavailable");
+	},
+	renderReport: () => {
+		throw new Error("runtime dependencies unavailable");
+	},
+	renderJUnit: () => {
+		throw new Error("runtime dependencies unavailable");
+	},
+	writeFile: async () => {
+		throw new Error("runtime dependencies unavailable");
+	},
+	colorEnabled: false,
+	writeStdout: (text) => process.stdout.write(text),
+	writeStderr: (text) => process.stderr.write(text)
+};
+const unavailableRuntimeDependencies = {
+	...unavailableDependencies,
+	readFile: node_fs_promises.readFile
+};
+/**
+* `repair` 실행 의존성. 함수로 빼 둔 이유는 **주입 자체를 테스트가 단언할 수 있게** 하기
+* 위해서다. 분기 안에 리터럴로 두면 `reviewIO` 를 빠뜨려도 아무 테스트도 안 깨진다.
+* 실제로 그렇게 한 번 빠뜨렸다(T10 보고서).
+*
+* 대화형 판정은 `generate` 와 같은 기준이다. 같은 `nodeReviewIO()` 를 쓰고, 그 구현이
+* stdin·stdout 이 둘 다 TTY 일 때만 `interactive` 를 참으로 만든다.
+*/
+function nodeRepairDependencies(generate) {
+	return {
+		readFile: (path) => (0, node_fs_promises.readFile)(path, "utf8"),
+		writeStdout: (text) => void process.stdout.write(text),
+		writeStderr: (text) => void process.stderr.write(text),
+		reviewIO: require_test_command.nodeReviewIO(),
+		diagnosis: {
+			prepare: generate.prepareDiagnosisRequest,
+			dispatch: generate.dispatchDiagnosisRequest,
+			providers: {
+				codex: (model) => generate.createCodexProvider({ model }),
+				claude: (model) => generate.createClaudeProvider({ model })
+			}
+		}
+	};
+}
+/** `mcpeak help <이름>` 으로 볼 수 있는 명령. 위 두 갈래가 같은 목록을 봐야 한다. */
+const HELP_TOPICS = [
+	"test",
+	"generate",
+	"repair"
+];
+const isHelpTopic = (value) => HELP_TOPICS.includes(value);
+async function run(argv) {
+	if (argv.length === 0 || argv.length === 1 && [
+		"--help",
+		"-h",
+		"help"
+	].includes(argv[0] ?? "")) {
+		process.stdout.write(require_test_command.GLOBAL_HELP);
+		return 0;
+	}
+	if (argv.length === 2) {
+		const command = argv[0] === "help" ? argv[1] : argv[1] === "--help" ? argv[0] : void 0;
+		if (command === "replay" || command === "verify") return require_test_command.runCli([command], unavailableDependencies);
+		if (isHelpTopic(command)) {
+			process.stdout.write(require_test_command.commandHelp(command));
+			return 0;
+		}
+	}
+	/**
+	* `help` 로 시작했는데 위에서 안 걸렸다면 **뒤에 붙은 인자가 틀린 것**이다.
+	*
+	* 여기서 안 막고 아래로 흘려보내면 `runCli` 가 `argv[0]` 인 `help` 를 명령으로 읽어
+	* "알 수 없는 CLI 명령 'help'입니다" 라고 한다. 사용자가 정확히 친 토큰을 틀렸다고
+	* 지목하는 셈이라, 무엇을 고쳐야 하는지가 화면에서 사라진다.
+	*/
+	if (argv[0] === "help") {
+		const target = argv[1] ?? "";
+		const extra = argv[2];
+		const message = isHelpTopic(target) && extra !== void 0 ? `\`help ${require_test_command.escapeTerminalText(target)}\` 뒤의 '${require_test_command.escapeTerminalText(extra)}' 는 받지 않습니다.` : `도움말이 없는 명령 '${require_test_command.escapeTerminalText(target)}'입니다.`;
+		process.stderr.write(`오류 [CLI_USAGE]: ${message}\n해결: ${require_test_command.commandDiscovery}\n`);
+		return 1;
+	}
+	if (argv.length === 1 && argv[0] === "--version") {
+		process.stdout.write(`mcpeak ${require_test_command.version}\n`);
+		return 0;
+	}
+	if (argv[0] === "generate") {
+		let core;
+		let runner;
+		let generate;
+		try {
+			[core, runner, generate] = await Promise.all([
+				import("@mcpeak/core"),
+				import("@mcpeak/runner"),
+				import("@mcpeak/generate")
+			]);
+		} catch {
+			return require_test_command.runGenerateCommand(argv, {
+				...require_test_command.nodeGenerateDependencies(),
+				connect: unavailableDependencies.connect,
+				createBaselineSuite: unavailableDependencies.validateSuite,
+				createAuthoringSession: unavailableDependencies.validateSuite,
+				finalizeAuthoringDraft: unavailableDependencies.validateSuite,
+				getAuthoringExecutionSuite: unavailableDependencies.validateSuite,
+				validateSuite: unavailableDependencies.validateSuite
+			});
+		}
+		return require_test_command.runGenerateCommand(argv, {
+			...require_test_command.nodeGenerateDependencies(),
+			connect: core.connectStdio,
+			connectHttp: core.connectHttp,
+			readEnv: (name) => process.env[name],
+			createBaselineSuite: generate.createBaselineSuite,
+			createAuthoringSession: generate.createAuthoringSession,
+			finalizeAuthoringDraft: generate.finalizeAuthoringDraft,
+			getAuthoringExecutionSuite: generate.getAuthoringExecutionSuite,
+			validateSuite: runner.validateMcpSuite,
+			reviewIO: require_test_command.nodeReviewIO(),
+			providers: {
+				codex: (model) => generate.createCodexAuthoringProvider({ model }),
+				claude: (model) => generate.createClaudeAuthoringProvider({ model })
+			},
+			prepareAuthoringRequest: generate.prepareAuthoringRequest,
+			dispatchAuthoringRequest: generate.dispatchAuthoringRequest,
+			createAuthoringDiff: generate.createAuthoringDiff,
+			applyAuthoringChanges: generate.applyAuthoringChanges,
+			reviewLocalAuthoringCandidate: generate.reviewLocalAuthoringCandidate,
+			computeCoverage: generate.computeCoverage,
+			preparePreFillRequest: generate.preparePreFillRequest,
+			previewPreFillRequest: generate.previewPreFillRequest,
+			dispatchPreFillRequest: generate.dispatchPreFillRequest,
+			preFillProviders: {
+				codex: (model) => generate.createCodexProvider({ model }),
+				claude: (model) => generate.createClaudeProvider({ model })
+			},
+			prepareRejectionDiagnosisRequests: generate.prepareRejectionDiagnosisRequests,
+			dispatchRejectionDiagnosis: generate.dispatchRejectionDiagnosis,
+			rejectionProviders: {
+				codex: (model) => generate.createCodexProvider({ model }),
+				claude: (model) => generate.createClaudeProvider({ model })
+			},
+			GenerateTestsError: generate.GenerateTestsError
+		});
+	}
+	if (argv[0] === "repair") {
+		/**
+		* `generate` 분기와 같은 모양으로 동적 import 한다. `test` 경로는 이 분기를 지나지 않으므로
+		* 여전히 `core` 와 `runner` 만 로드한다. 계획서 §8 위험표 첫 줄.
+		*/
+		let generate;
+		try {
+			generate = await import("@mcpeak/generate");
+		} catch {
+			process.stderr.write("오류 [REPAIR_RUNTIME_UNAVAILABLE]: 진단에 필요한 @mcpeak/generate 를 로드하지 못했습니다.\n해결: 의존성을 설치한 뒤 다시 실행하세요.\n");
+			return 1;
+		}
+		const dependencies = nodeRepairDependencies(generate);
+		try {
+			return await require_test_command.runRepairCommand(argv, dependencies);
+		} finally {
+			dependencies.reviewIO?.close?.();
+		}
+	}
+	if (argv[0] !== "test") return require_test_command.runCli(argv, unavailableDependencies);
+	try {
+		if (!require_test_command.parseTestCommand(argv.slice(1)).suitePath.toLowerCase().endsWith(".json")) return require_test_command.runCli(argv, unavailableDependencies);
+	} catch {
+		return require_test_command.runCli(argv, unavailableDependencies);
+	}
+	let core;
+	let runner;
+	try {
+		[core, runner] = await Promise.all([import("@mcpeak/core"), import("@mcpeak/runner")]);
+	} catch {
+		return require_test_command.runCli(argv, unavailableRuntimeDependencies);
+	}
+	return require_test_command.runCli(argv, {
+		readFile: node_fs_promises.readFile,
+		validateSuite: runner.validateMcpSuite,
+		connect: core.connectStdio,
+		connectHttp: core.connectHttp,
+		readEnv: (name) => process.env[name],
+		startRunner: runner.runSuite,
+		finalize: runner.finalizeRunnerExecution,
+		renderReport: runner.renderReport,
+		renderJUnit: runner.renderJUnit,
+		writeFile: (path, text) => (0, node_fs_promises.writeFile)(path, text, "utf8"),
+		colorEnabled: process.stdout.isTTY === true && process.env.NO_COLOR === void 0,
+		writeStdout: (text) => process.stdout.write(text),
+		writeStderr: (text) => process.stderr.write(text)
+	});
+}
+//#endregion
+exports.COMMANDS = COMMANDS;
+exports.nodeRepairDependencies = nodeRepairDependencies;
+exports.run = run;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { a as RepairCommandDependencies, t as ReplayCommandDependencies } from "./replay-command-V0ZSJPiD.cjs";
+import { t as RepairCommandDependencies } from "./repair-command-D3zL3G5W.cjs";
 //#region src/index.d.ts
 type Command = (argv: string[]) => Promise<number>;
-declare const COMMANDS: readonly ["test", "generate", "repair", "record", "replay", "verify", "mock"];
+declare const COMMANDS: readonly ["test", "generate", "repair", "record", "mock"];
 /**
  * `repair` 실행 의존성. 함수로 빼 둔 이유는 **주입 자체를 테스트가 단언할 수 있게** 하기
  * 위해서다. 분기 안에 리터럴로 두면 `reviewIO` 를 빠뜨려도 아무 테스트도 안 깨진다.
@@ -11,17 +11,6 @@ declare const COMMANDS: readonly ["test", "generate", "repair", "record", "repla
  * stdin·stdout 이 둘 다 TTY 일 때만 `interactive` 를 참으로 만든다.
  */
 declare function nodeRepairDependencies(generate: typeof import("@mcpeak/generate")): RepairCommandDependencies;
-/**
- * replay 는 `connect` 를 쓰지 않는다. 대신 카세트 로더가 필요하다. 런타임 의존성을 못 불러도
- * 사용 오류는 정상적으로 내야 하므로, 실제로 쓰이기 전에 끝나는 경로를 위해 자리만 채운다.
- *
- * **테스트가 배선을 직접 단언할 수 있도록 내보낸다.** 여기서 평범한 Error 로 되돌아가면
- * 사용자는 "이슈를 보고하세요" 를 보게 되는데, 모듈 모킹으로는 이 경로를 재현할 수 없다 —
- * `record` 와 `runner` 가 `generate-command` 를 통해 정적 import 체인에 있어서, 그것을
- * 모킹하면 `index.ts` 로드 자체가 깨진다. `nodeRepairDependencies` 를 함수로 뺀 것과 같은
- * 이유다(주입을 빠뜨려도 아무 테스트가 안 깨지는 상황을 막는다).
- */
-declare const unavailableReplayDependencies: ReplayCommandDependencies;
 declare function run(argv: string[]): Promise<number>;
 //#endregion
-export { COMMANDS, Command, nodeRepairDependencies, run, unavailableReplayDependencies };
+export { COMMANDS, Command, nodeRepairDependencies, run };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { a as RepairCommandDependencies, t as ReplayCommandDependencies } from "./replay-command-BAtSzf8R.mjs";
+import { t as RepairCommandDependencies } from "./repair-command-DQh2h4tQ.mjs";
 //#region src/index.d.ts
 type Command = (argv: string[]) => Promise<number>;
-declare const COMMANDS: readonly ["test", "generate", "repair", "record", "replay", "verify", "mock"];
+declare const COMMANDS: readonly ["test", "generate", "repair", "record", "mock"];
 /**
  * `repair` 실행 의존성. 함수로 빼 둔 이유는 **주입 자체를 테스트가 단언할 수 있게** 하기
  * 위해서다. 분기 안에 리터럴로 두면 `reviewIO` 를 빠뜨려도 아무 테스트도 안 깨진다.
@@ -11,17 +11,6 @@ declare const COMMANDS: readonly ["test", "generate", "repair", "record", "repla
  * stdin·stdout 이 둘 다 TTY 일 때만 `interactive` 를 참으로 만든다.
  */
 declare function nodeRepairDependencies(generate: typeof import("@mcpeak/generate")): RepairCommandDependencies;
-/**
- * replay 는 `connect` 를 쓰지 않는다. 대신 카세트 로더가 필요하다. 런타임 의존성을 못 불러도
- * 사용 오류는 정상적으로 내야 하므로, 실제로 쓰이기 전에 끝나는 경로를 위해 자리만 채운다.
- *
- * **테스트가 배선을 직접 단언할 수 있도록 내보낸다.** 여기서 평범한 Error 로 되돌아가면
- * 사용자는 "이슈를 보고하세요" 를 보게 되는데, 모듈 모킹으로는 이 경로를 재현할 수 없다 —
- * `record` 와 `runner` 가 `generate-command` 를 통해 정적 import 체인에 있어서, 그것을
- * 모킹하면 `index.ts` 로드 자체가 깨진다. `nodeRepairDependencies` 를 함수로 뺀 것과 같은
- * 이유다(주입을 빠뜨려도 아무 테스트가 안 깨지는 상황을 막는다).
- */
-declare const unavailableReplayDependencies: ReplayCommandDependencies;
 declare function run(argv: string[]): Promise<number>;
 //#endregion
-export { COMMANDS, Command, nodeRepairDependencies, run, unavailableReplayDependencies };
+export { COMMANDS, Command, nodeRepairDependencies, run };