@mcpeak/cli 0.9.0

package/dist/replay-command-V0ZSJPiD.d.cts

@@ -0,0 +1,186 @@
+import { McpStdioConnection, ToolDef } from "@mcpeak/core";
+import { AuthoringExecutionSnapshot, AuthoringSessionView, BaselineGenerationResult, PreFillProvider } from "@mcpeak/generate";
+import { Cassette } from "@mcpeak/record";
+import { FinalizeRunnerExecutionOptions, RunSuiteOptions, RunnerExecution, RunnerReport, SuiteValidationIssue, SuiteValidationResult, TestSuiteSpec } from "@mcpeak/runner";
+//#region src/generate-command.d.ts
+interface GenerateCommandInput {
+  readonly suiteId: string;
+  readonly name: string;
+  readonly outPath: string;
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly baselineOnly: boolean;
+  readonly provider?: "codex" | "claude";
+  readonly model?: string;
+  /** 승인 전 시험 실행 여부. 기본은 실행이고 `--no-dry-run` 이 끈다. 설계 문서 §4.3. */
+  readonly dryRun: boolean;
+  /** `--cassette` 경로. 없으면 서버를 직접 부른다. */
+  readonly cassettePath?: string;
+  /** `--record`. 카세트 파일이 있어도 새로 녹화한다. */
+  readonly forceRecord: boolean;
+  /** `--force`. `--out` 에 파일이 있으면 지우고 새로 쓴다. 설계 문서 §5. */
+  readonly force: boolean;
+  /** `--reset-cmd`. 시험 실행 직전 1회 실행한다. */
+  readonly resetCmd?: string;
+  /** 입력값 교정 단계를 돌릴지 여부. 기본은 실행이고 `--no-repair` 가 끈다. 설계 문서 §7. */
+  readonly repair: boolean;
+}
+interface GenerateCommandDependencies {
+  connect(options: {
+    command: string;
+    args: readonly string[];
+  }): Promise<McpStdioConnection>;
+  createBaselineSuite(tools: readonly ToolDef[], options: {
+    suiteId: string;
+    suiteName: string;
+  }): BaselineGenerationResult;
+  createAuthoringSession(baseline: BaselineGenerationResult, options?: {
+    readonly preFilledCaseIds?: readonly string[];
+  }): AuthoringSessionView;
+  finalizeAuthoringDraft(options: {
+    session: AuthoringSessionView;
+    approval: {
+      approved: boolean;
+      fingerprint: string;
+    };
+  }): {
+    finalized: true;
+    snapshot: AuthoringExecutionSnapshot;
+  } | {
+    finalized: false;
+  };
+  getAuthoringExecutionSuite(snapshot: AuthoringExecutionSnapshot): TestSuiteSpec;
+  validateSuite(value: unknown): SuiteValidationResult;
+  exists(path: string): Promise<boolean>;
+  openTemp(path: string): Promise<{
+    writeFile(data: string, encoding: "utf8"): Promise<void>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+  }>;
+  readFile(path: string): Promise<Uint8Array>;
+  /**
+   * 임시 파일을 최종 경로에 커밋한다. `rename`이 아니라 `link`인 것이 요점이다.
+   * `rename`은 대상이 있으면 말없이 덮어쓴다. `link`는 EEXIST로 실패하므로
+   * 원자성과 no-clobber를 동시에 얻는다. 덮어쓸 수 있는 primitive를 아예 두지 않는다.
+   */
+  link(from: string, to: string): Promise<void>;
+  unlink(path: string): Promise<void>;
+  writeStdout(text: string): void;
+  writeStderr(text: string): void;
+  reviewIO?: ReviewIO;
+  providers?: Partial<Record<"codex" | "claude", (model: string) => TestAuthoringProvider | undefined>>;
+  /**
+   * 거절 근거 진단 통로 (#89 · 설계 문서 §6). `providers` 와 **따로 둔다.** 그쪽은
+   * `TestAuthoringProvider`(`author`)이고 이쪽은 `diagnoseRejection` 이라 다른 계약이다.
+   * `preFillProviders` 와 같은 선례다. 없으면 진단을 아예 묻지 않는다.
+   */
+  rejectionProviders?: Partial<Record<"codex" | "claude", (model: string) => import("@mcpeak/generate").RejectionDiagnosisProvider | undefined>>;
+  prepareRejectionDiagnosisRequests?: typeof import("@mcpeak/generate").prepareRejectionDiagnosisRequests;
+  dispatchRejectionDiagnosis?: typeof import("@mcpeak/generate").dispatchRejectionDiagnosis;
+  prepareAuthoringRequest?: typeof import("@mcpeak/generate").prepareAuthoringRequest;
+  dispatchAuthoringRequest?: typeof import("@mcpeak/generate").dispatchAuthoringRequest;
+  createAuthoringDiff?: typeof import("@mcpeak/generate").createAuthoringDiff;
+  applyAuthoringChanges?: typeof import("@mcpeak/generate").applyAuthoringChanges;
+  reviewLocalAuthoringCandidate?: typeof import("@mcpeak/generate").reviewLocalAuthoringCandidate;
+  computeCoverage?: typeof import("@mcpeak/generate").computeCoverage;
+  /**
+   * AI 사전보완 통로. 넷 다 주입돼야 사전보완이 돈다. 하나라도 없으면 건너뛴다.
+   * 위 authoring 통로와 같은 이유로 값 import 가 아니라 주입이다.
+   */
+  preparePreFillRequest?: typeof import("@mcpeak/generate").preparePreFillRequest;
+  previewPreFillRequest?: typeof import("@mcpeak/generate").previewPreFillRequest;
+  dispatchPreFillRequest?: typeof import("@mcpeak/generate").dispatchPreFillRequest;
+  preFillProviders?: Partial<Record<"codex" | "claude", (model: string) => PreFillProvider | undefined>>;
+  /**
+   * `instanceof` 용 클래스. 값 import 가 아니라 주입인 것이 요점이다.
+   *
+   * 이 파일은 `@mcpeak/generate` 에서 타입만 가져온다(위 `import type`). 클래스를 값으로
+   * 가져오면 `index.ts` 가 정적으로 끌어와 `test` 경로까지 `generate` 를 로드한다.
+   * `typeof import(...)` 는 타입 위치라 런타임 import 가 생기지 않고, 주입하면 클래스
+   * 동일성도 보장된다. 위 6개 필드가 같은 방식이다.
+   */
+  GenerateTestsError?: typeof import("@mcpeak/generate").GenerateTestsError;
+  /**
+   * 카세트 파일 입출력. 주입점을 여기 하나만 두는 이유는 시험 실행 경로에서 파일시스템을
+   * 만지는 곳이 이것뿐이기 때문이다. 나머지(`runDryRun`·`reviewDryRun`)는 주입한 client 와
+   * io 만 쓰므로 테스트가 실제 구현을 그대로 돌린다.
+   */
+  cassetteIo?: {
+    load(path: string): Promise<Cassette | null>;
+    save(path: string, cassette: Cassette): Promise<void>;
+  };
+}
+interface ReviewIO {
+  input(message: string): Promise<string>;
+  choose(message: string, choices: readonly string[]): Promise<string>;
+  confirm(message: string): Promise<boolean>;
+  write(text: string): void;
+  readonly interactive: boolean;
+  close?(): void;
+}
+type TestAuthoringProvider = import("@mcpeak/generate").TestAuthoringProvider;
+declare function runGenerateCommand(argv: readonly string[], deps: GenerateCommandDependencies): Promise<number>;
+declare const nodeGenerateDependencies: () => Omit<GenerateCommandDependencies, "connect" | "createBaselineSuite" | "createAuthoringSession" | "finalizeAuthoringDraft" | "getAuthoringExecutionSuite" | "validateSuite">;
+declare function nodeReviewIO(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): ReviewIO;
+//#endregion
+//#region src/repair-command.d.ts
+interface RepairCommandInput {
+  readonly bundlePath: string;
+  readonly providerId: "codex" | "claude";
+  readonly model: string;
+  readonly yes: boolean;
+  readonly includeStderr: boolean;
+  readonly maxCases: number;
+}
+interface RepairCommandDependencies {
+  readFile(path: string): Promise<string>;
+  writeStdout(text: string): void;
+  writeStderr(text: string): void;
+  /** 전송 확인 화면. 없으면 비대화형으로 본다. `generate` 가 쓰는 그 인터페이스다. */
+  readonly reviewIO?: ReviewIO;
+  /**
+   * 진단 통로. `@mcpeak/generate` 를 값으로 import 하지 않고 주입받는다. 정적으로 import 하면
+   * `test` 경로가 `generate` 를 함께 로드한다. 계획서 §8 위험표 첫 줄이다.
+   */
+  readonly diagnosis?: {
+    readonly prepare: typeof import("@mcpeak/generate").prepareDiagnosisRequest;
+    readonly dispatch: typeof import("@mcpeak/generate").dispatchDiagnosisRequest;
+    readonly providers: {
+      readonly codex: (model: string) => import("@mcpeak/generate").ServerDiagnosisProvider;
+      readonly claude: (model: string) => import("@mcpeak/generate").ServerDiagnosisProvider;
+    };
+  };
+}
+declare function parseRepairCommand(argv: readonly string[]): RepairCommandInput;
+/**
+ * `repair` 명령. 번들을 읽고, 전송 내용을 확인받고, provider 에게 진단을 물어 화면에 찍는다.
+ * 파일도 명세도 고치지 않는다. 종료 코드는 운영 실패에만 1 이다(설계서 §7.1).
+ */
+declare function runRepairCommand(argv: readonly string[], deps: RepairCommandDependencies): Promise<number>;
+//#endregion
+//#region src/replay-command.d.ts
+interface ReplayCommandInput {
+  readonly suitePath: string;
+  readonly cassettePath: string;
+}
+/**
+ * `connect` 가 없다. replay 가 서버를 띄우지 않는다는 것이 주석이 아니라 타입에 드러난다.
+ * ADR-0028.
+ */
+interface ReplayCommandDependencies {
+  readFile(path: string): Promise<Uint8Array>;
+  validateSuite(input: unknown): SuiteValidationResult;
+  loadCassette(path: string): Promise<Cassette | null>;
+  startRunner(options: RunSuiteOptions): RunnerExecution;
+  finalize(options: FinalizeRunnerExecutionOptions): Promise<RunnerReport>;
+  renderReport(report: RunnerReport, options?: {
+    color?: boolean;
+  }): string;
+  colorEnabled: boolean;
+  writeStdout(text: string): void;
+  writeStderr(text: string): void;
+}
+declare function parseReplayCommand(argv: readonly string[]): ReplayCommandInput;
+declare function runReplayCommand(argv: readonly string[], dependencies: ReplayCommandDependencies): Promise<number>;
+//#endregion
+export { RepairCommandDependencies as a, runRepairCommand as c, ReviewIO as d, nodeGenerateDependencies as f, runReplayCommand as i, GenerateCommandDependencies as l, runGenerateCommand as m, ReplayCommandInput as n, RepairCommandInput as o, nodeReviewIO as p, parseReplayCommand as r, parseRepairCommand as s, ReplayCommandDependencies as t, GenerateCommandInput as u };

package/dist/src-D1NW6ckv.mjs

@@ -0,0 +1,459 @@
+import { a as runReplayCommand, c as nodeGenerateDependencies, d as GLOBAL_HELP, f as VERIFY_USAGE_HINT, l as nodeReviewIO, m as version, n as runCli, p as commandHelp, r as ReplayRuntimeUnavailableError, s as runRepairCommand, t as parseTestCommand, u as runGenerateCommand } from "./test-command-CsJfojut.mjs";
+import { readFile, writeFile } from "node:fs/promises";
+//#region src/verify-command.ts
+/**
+* 런타임 모듈을 못 불러 fallback 의존성이 쓰일 때 던진다.
+*
+* 타입을 따로 두는 이유는 이 실패가 **카세트 손상과 구분돼야** 하기 때문이다. 그냥 던지면
+* `CASSETTE_READ_FAILED` 로 잡혀 "카세트 파일이 손상되지 않았는지 확인하세요" 가 나가고,
+* 사용자는 멀쩡한 파일을 들여다보게 된다. 고칠 곳은 설치다.
+*/
+var VerifyRuntimeUnavailableError = class extends Error {
+	constructor() {
+		super("verify 실행에 필요한 모듈을 로드하지 못했습니다.");
+		this.name = "VerifyRuntimeUnavailableError";
+	}
+};
+const dictionary = {
+	VERIFY_RUNTIME_UNAVAILABLE: {
+		message: "verify 에 필요한 @mcpeak/record 를 로드하지 못했습니다.",
+		hint: "의존성을 설치한 뒤 다시 실행하세요. 카세트 파일의 문제가 아닙니다."
+	},
+	CASSETTE_NOT_FOUND: {
+		message: "카세트 파일이 없습니다.",
+		hint: "`mcpeak generate --cassette <path> --record` 로 먼저 녹화하세요."
+	},
+	CASSETTE_READ_FAILED: {
+		message: "카세트를 읽지 못했습니다.",
+		hint: "카세트 파일이 손상되지 않았는지 확인하세요."
+	},
+	SERVER_CONNECT_FAILED: {
+		message: "MCP 서버에 연결하지 못했습니다.",
+		hint: "--command 와 --arg 가 카세트를 녹화할 때 쓴 서버와 같은지 확인하세요."
+	},
+	CASSETTE_DRIFTED: {
+		message: "카세트가 실서버 응답과 다릅니다.",
+		hint: "서버가 바뀐 것이라면 `--record` 로 카세트를 다시 만드세요."
+	}
+};
+var VerifyCommandError = class extends Error {
+	failure;
+	constructor(failure) {
+		super(failure.message);
+		this.failure = failure;
+	}
+};
+const usage = (message) => {
+	throw new VerifyCommandError({
+		code: "CLI_USAGE",
+		message,
+		hint: VERIFY_USAGE_HINT
+	});
+};
+/**
+* 값을 하나 읽는다. `--opt value` 와 `--opt=value` 를 모두 받는다.
+*
+* `--arg` 만 값의 모양을 검사하지 않는다. 서버 인자는 대부분 플래그 모양이고(`-y`, `--with`,
+* `--db-path`) 빈 문자열도 정상적인 인자다. `generate` 와 `test` 가 이미 `--arg` 를 그렇게
+* 받으므로, 여기서 거절하면 **`generate --record` 로 녹화한 바로 그 서버를 `verify` 로는
+* 부를 수 없다.** 같은 명령줄을 못 받는 verify 는 그 카세트를 확인할 방법이 아예 없다.
+*
+* `--command` 는 그대로 검사한다. 실행 파일 자리에 들어온 플래그는 값을 빠뜨린 오타다.
+*/
+function optionValue(argv, index, name) {
+	const anyShape = name === "--arg";
+	const token = argv[index] ?? "";
+	if (token.startsWith(`${name}=`)) {
+		const value = token.slice(name.length + 1);
+		if (value === "" && !anyShape) usage(`${name} 옵션 값이 필요합니다.`);
+		return [value, index];
+	}
+	const next = argv[index + 1];
+	if (next === void 0 || !anyShape && (next === "" || next.startsWith("--"))) usage(`${name} 옵션 값이 필요합니다.`);
+	return [next, index + 1];
+}
+function parseVerifyCommand(argv) {
+	let cassettePath;
+	let command;
+	const args = [];
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index] ?? "";
+		const [name] = token.startsWith("--") ? token.split("=", 1) : [token];
+		if (name === "--command") {
+			if (command !== void 0) usage("--command 는 한 번만 사용할 수 있습니다.");
+			[command, index] = optionValue(argv, index, "--command");
+			continue;
+		}
+		if (name === "--arg") {
+			let value;
+			[value, index] = optionValue(argv, index, "--arg");
+			args.push(value);
+			continue;
+		}
+		if (name === "--record") usage("verify 는 카세트를 고치지 않습니다. 다시 녹화하려면 generate --record 를 쓰세요.");
+		if (token.startsWith("--")) usage(`알 수 없는 옵션입니다: ${token}`);
+		if (cassettePath !== void 0) usage(`카세트는 하나만 받습니다: ${token}`);
+		cassettePath = token;
+	}
+	if (cassettePath === void 0 || cassettePath === "") usage("카세트 JSON 경로가 필요합니다.");
+	if (command === void 0) usage("--command 에 MCP 서버 실행 명령이 필요합니다.");
+	return Object.freeze({
+		cassettePath,
+		command,
+		args: Object.freeze([...args])
+	});
+}
+const format = (failure) => `오류 [${failure.code}]: ${failure.message}\n해결: ${failure.hint}\n`;
+const writeFailure = (dependencies, failure) => {
+	dependencies.writeStderr(format(failure));
+	return 1;
+};
+/**
+* 결과 요약. 숫자만 찍고 끝내지 않는다 — 무엇이 어떻게 다른지가 이 명령의 산출물이다.
+* `record` 가 만든 문장을 그대로 싣는다. 여기서 다시 쓰면 두 곳이 갈린다.
+*/
+function formatVerifyResult(result, cassettePath) {
+	const lines = [];
+	const total = result.matched + result.mismatched.length + result.failed.length + result.skipped.length;
+	for (const item of [
+		...result.mismatched,
+		...result.failed,
+		...result.skipped
+	]) lines.push(item.message, "");
+	lines.push(`카세트: ${cassettePath}`);
+	lines.push(`  일치 ${result.matched} · 불일치 ${result.mismatched.length} · 실패 ${result.failed.length} · 확인불가 ${result.skipped.length} (총 ${total})`);
+	if (result.skipped.length > 0) lines.push("  확인불가는 args 에 마스킹된 비밀값이 있어 실서버에 그대로 보낼 수 없는 요청입니다.");
+	if (result.mismatched.length === 0 && result.failed.length === 0) lines.push(result.skipped.length === 0 ? "  카세트가 실서버와 일치합니다." : `  확인한 ${result.matched}개는 실서버와 일치합니다. ${result.skipped.length}개는 확인하지 못했습니다.`);
+	return `${lines.join("\n")}\n`;
+}
+async function runVerifyCommand(argv, dependencies) {
+	let input;
+	try {
+		input = parseVerifyCommand(argv);
+	} catch (error) {
+		if (error instanceof VerifyCommandError) return writeFailure(dependencies, error.failure);
+		throw error;
+	}
+	let cassette;
+	try {
+		cassette = await dependencies.loadCassette(input.cassettePath);
+	} catch (error) {
+		const code = error instanceof VerifyRuntimeUnavailableError ? "VERIFY_RUNTIME_UNAVAILABLE" : "CASSETTE_READ_FAILED";
+		return writeFailure(dependencies, {
+			code,
+			...dictionary[code]
+		});
+	}
+	if (cassette === null) return writeFailure(dependencies, {
+		code: "CASSETTE_NOT_FOUND",
+		...dictionary.CASSETTE_NOT_FOUND
+	});
+	let client;
+	try {
+		client = await dependencies.connect({
+			command: input.command,
+			args: input.args
+		});
+	} catch {
+		return writeFailure(dependencies, {
+			code: "SERVER_CONNECT_FAILED",
+			...dictionary.SERVER_CONNECT_FAILED
+		});
+	}
+	let result;
+	try {
+		result = await dependencies.verifyCassette(client, cassette, { cassettePath: input.cassettePath });
+	} finally {
+		await client.close().catch(() => {});
+	}
+	dependencies.writeStdout(formatVerifyResult(result, input.cassettePath));
+	if (result.mismatched.length === 0 && result.failed.length === 0) return 0;
+	dependencies.writeStderr(format({
+		code: "CASSETTE_DRIFTED",
+		...dictionary.CASSETTE_DRIFTED
+	}));
+	return 1;
+}
+//#endregion
+//#region src/index.ts
+const COMMANDS = [
+	"test",
+	"generate",
+	"repair",
+	"record",
+	"replay",
+	"verify",
+	"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
+};
+/**
+* `repair` 실행 의존성. 함수로 빼 둔 이유는 **주입 자체를 테스트가 단언할 수 있게** 하기
+* 위해서다. 분기 안에 리터럴로 두면 `reviewIO` 를 빠뜨려도 아무 테스트도 안 깨진다.
+* 실제로 그렇게 한 번 빠뜨렸다(T10 보고서).
+*
+* 대화형 판정은 `generate` 와 같은 기준이다. 같은 `nodeReviewIO()` 를 쓰고, 그 구현이
+* stdin·stdout 이 둘 다 TTY 일 때만 `interactive` 를 참으로 만든다.
+*/
+function nodeRepairDependencies(generate) {
+	return {
+		readFile: (path) => readFile(path, "utf8"),
+		writeStdout: (text) => void process.stdout.write(text),
+		writeStderr: (text) => void process.stderr.write(text),
+		reviewIO: nodeReviewIO(),
+		diagnosis: {
+			prepare: generate.prepareDiagnosisRequest,
+			dispatch: generate.dispatchDiagnosisRequest,
+			providers: {
+				codex: (model) => generate.createCodexProvider({ model }),
+				claude: (model) => generate.createClaudeProvider({ model })
+			}
+		}
+	};
+}
+/**
+* replay 는 `connect` 를 쓰지 않는다. 대신 카세트 로더가 필요하다. 런타임 의존성을 못 불러도
+* 사용 오류는 정상적으로 내야 하므로, 실제로 쓰이기 전에 끝나는 경로를 위해 자리만 채운다.
+*
+* **테스트가 배선을 직접 단언할 수 있도록 내보낸다.** 여기서 평범한 Error 로 되돌아가면
+* 사용자는 "이슈를 보고하세요" 를 보게 되는데, 모듈 모킹으로는 이 경로를 재현할 수 없다 —
+* `record` 와 `runner` 가 `generate-command` 를 통해 정적 import 체인에 있어서, 그것을
+* 모킹하면 `index.ts` 로드 자체가 깨진다. `nodeRepairDependencies` 를 함수로 뺀 것과 같은
+* 이유다(주입을 빠뜨려도 아무 테스트가 안 깨지는 상황을 막는다).
+*/
+const unavailableReplayDependencies = {
+	...unavailableRuntimeDependencies,
+	/**
+	* 런타임에서 오는 의존성은 전용 오류 타입을 던진다. 평범한 Error 로 두면 `validateSuite`
+	* 자리에서 `CLI_INTERNAL_ERROR` 로 잡혀 "이슈를 보고하세요" 가 나가고, 사용자는 자기
+	* 설치 문제로 버그 리포트를 쓰게 된다. 실제로 가장 먼저 걸리는 것이 `validateSuite` 다.
+	*
+	* `unavailableRuntimeDependencies` 자체는 `test` 경로와 공유하므로 여기서만 덮는다.
+	*/
+	validateSuite: () => {
+		throw new ReplayRuntimeUnavailableError();
+	},
+	loadCassette: async () => {
+		throw new ReplayRuntimeUnavailableError();
+	},
+	startRunner: () => {
+		throw new ReplayRuntimeUnavailableError();
+	},
+	finalize: async () => {
+		throw new ReplayRuntimeUnavailableError();
+	},
+	renderReport: () => {
+		throw new ReplayRuntimeUnavailableError();
+	}
+};
+/**
+* verify 도 런타임을 못 불러도 사용 오류는 정상적으로 내야 한다. 파싱은 의존성 없이 끝나므로
+* `--command` 누락 같은 오류는 여기까지 오지 않는다.
+*/
+const unavailableVerifyDependencies = {
+	loadCassette: async () => {
+		throw new VerifyRuntimeUnavailableError();
+	},
+	connect: async () => {
+		throw new VerifyRuntimeUnavailableError();
+	},
+	verifyCassette: async () => {
+		throw new VerifyRuntimeUnavailableError();
+	},
+	writeStdout: (text) => void process.stdout.write(text),
+	writeStderr: (text) => void process.stderr.write(text)
+};
+async function run(argv) {
+	if (argv.length === 0 || argv.length === 1 && [
+		"--help",
+		"-h",
+		"help"
+	].includes(argv[0] ?? "")) {
+		process.stdout.write(GLOBAL_HELP);
+		return 0;
+	}
+	if (argv.length === 2) {
+		const command = argv[0] === "help" ? argv[1] : argv[1] === "--help" ? argv[0] : void 0;
+		if (command === "test" || command === "generate" || command === "repair" || command === "replay" || command === "verify") {
+			process.stdout.write(commandHelp(command));
+			return 0;
+		}
+	}
+	if (argv.length === 1 && argv[0] === "--version") {
+		process.stdout.write(`mcpeak ${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 runGenerateCommand(argv, {
+				...nodeGenerateDependencies(),
+				connect: unavailableDependencies.connect,
+				createBaselineSuite: unavailableDependencies.validateSuite,
+				createAuthoringSession: unavailableDependencies.validateSuite,
+				finalizeAuthoringDraft: unavailableDependencies.validateSuite,
+				getAuthoringExecutionSuite: unavailableDependencies.validateSuite,
+				validateSuite: unavailableDependencies.validateSuite
+			});
+		}
+		return runGenerateCommand(argv, {
+			...nodeGenerateDependencies(),
+			connect: core.connectStdio,
+			createBaselineSuite: generate.createBaselineSuite,
+			createAuthoringSession: generate.createAuthoringSession,
+			finalizeAuthoringDraft: generate.finalizeAuthoringDraft,
+			getAuthoringExecutionSuite: generate.getAuthoringExecutionSuite,
+			validateSuite: runner.validateMcpSuite,
+			reviewIO: 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 runRepairCommand(argv, dependencies);
+		} finally {
+			dependencies.reviewIO?.close?.();
+		}
+	}
+	if (argv[0] === "replay") {
+		let runner;
+		let record;
+		try {
+			[runner, record] = await Promise.all([import("@mcpeak/runner"), import("@mcpeak/record")]);
+		} catch {
+			return runReplayCommand(argv.slice(1), unavailableReplayDependencies);
+		}
+		return runReplayCommand(argv.slice(1), {
+			readFile,
+			validateSuite: runner.validateMcpSuite,
+			loadCassette: record.loadCassette,
+			startRunner: runner.runSuite,
+			finalize: runner.finalizeRunnerExecution,
+			renderReport: runner.renderReport,
+			colorEnabled: process.stdout.isTTY === true && process.env.NO_COLOR === void 0,
+			writeStdout: (text) => process.stdout.write(text),
+			writeStderr: (text) => process.stderr.write(text)
+		});
+	}
+	if (argv[0] === "verify") {
+		let core;
+		let record;
+		try {
+			[core, record] = await Promise.all([import("@mcpeak/core"), import("@mcpeak/record")]);
+		} catch {
+			return runVerifyCommand(argv.slice(1), unavailableVerifyDependencies);
+		}
+		return runVerifyCommand(argv.slice(1), {
+			loadCassette: record.loadCassette,
+			connect: (options) => core.connect({
+				command: options.command,
+				args: options.args
+			}),
+			verifyCassette: record.verifyCassette,
+			writeStdout: (text) => void process.stdout.write(text),
+			writeStderr: (text) => void process.stderr.write(text)
+		});
+	}
+	if (argv[0] !== "test") return runCli(argv, unavailableDependencies);
+	try {
+		if (!parseTestCommand(argv.slice(1)).suitePath.toLowerCase().endsWith(".json")) return runCli(argv, unavailableDependencies);
+	} catch {
+		return runCli(argv, unavailableDependencies);
+	}
+	let core;
+	let runner;
+	try {
+		[core, runner] = await Promise.all([import("@mcpeak/core"), import("@mcpeak/runner")]);
+	} catch {
+		return runCli(argv, unavailableRuntimeDependencies);
+	}
+	return runCli(argv, {
+		readFile,
+		validateSuite: runner.validateMcpSuite,
+		connect: core.connectStdio,
+		startRunner: runner.runSuite,
+		finalize: runner.finalizeRunnerExecution,
+		renderReport: runner.renderReport,
+		renderJUnit: runner.renderJUnit,
+		writeFile: (path, text) => 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
+export { unavailableReplayDependencies as i, nodeRepairDependencies as n, run as r, COMMANDS as t };