sonamu 0.10.13 → 0.11.0

package/src/tooling/__tests__/cli-tooling-stub-practice.contract.test.ts

@@ -0,0 +1,147 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { tooling } from "../cli-tooling";
+import { attachSonamuTestRoot, detachSonamuTestRoot } from "./helpers/sonamu-test-root";
+
+let apiRoot = "";
+let practiceDir = "";
+
+// 구 CLI가 만들던 practice 스텁 본문을 그대로 재현합니다.
+function expectedCode(fileName: string): string {
+  return [
+    `import { Sonamu } from "sonamu";`,
+    "",
+    `console.clear();`,
+    `console.log("${fileName}");`,
+    "",
+    `Sonamu.runScript(async () => {`,
+    ` // TODO`,
+    `});`,
+    "",
+  ].join("\n");
+}
+
+async function runPractice(name: string) {
+  expect(tooling.stub).toBeDefined();
+  expect(tooling.stub.practice).toBeTypeOf("function");
+  return tooling.stub.practice({ name });
+}
+
+async function seedPracticeFiles(fileNames: string[]): Promise<void> {
+  await mkdir(practiceDir, { recursive: true });
+  await Promise.all(
+    fileNames.map((fileName) => writeFile(path.join(practiceDir, fileName), "", "utf8")),
+  );
+}
+
+beforeEach(async () => {
+  const apiRootPath = await attachSonamuTestRoot();
+  apiRoot = apiRootPath;
+  practiceDir = path.join(apiRootPath, "src", "practices");
+});
+
+afterEach(async () => {
+  await detachSonamuTestRoot();
+});
+
+describe("stub.practice tooling 연산", () => {
+  it("practices 디렉터리가 없으면 만들고 첫 번째 파일을 생성한다", async () => {
+    await expect(runPractice("hello")).resolves.toMatchObject({
+      fileName: "p1-hello.ts",
+      path: path.join(practiceDir, "p1-hello.ts"),
+    });
+
+    await expect(readFile(path.join(practiceDir, "p1-hello.ts"), "utf8")).resolves.toBe(
+      expectedCode("p1-hello.ts"),
+    );
+  });
+
+  it("기존 practice 파일의 최대 시퀀스 다음 번호를 사용한다", async () => {
+    await seedPracticeFiles(["p1-first.ts", "p3-third.ts"]);
+
+    await expect(runPractice("fourth")).resolves.toMatchObject({ fileName: "p4-fourth.ts" });
+
+    await expect(readFile(path.join(practiceDir, "p4-fourth.ts"), "utf8")).resolves.toBe(
+      expectedCode("p4-fourth.ts"),
+    );
+  });
+
+  it("시퀀스 규칙에 맞지 않는 파일은 번호 계산에서 제외한다", async () => {
+    await seedPracticeFiles(["p2-second.ts", "p9-ninth.js", "readme.md", "practice.ts"]);
+
+    await expect(runPractice("third")).resolves.toMatchObject({ fileName: "p3-third.ts" });
+  });
+
+  it("허용 문자로만 이루어진 이름은 파일명과 경로를 그대로 돌려준다", async () => {
+    await expect(runPractice("my.practice-01_v2")).resolves.toEqual({
+      fileName: "p1-my.practice-01_v2.ts",
+      path: path.join(practiceDir, "p1-my.practice-01_v2.ts"),
+    });
+
+    await expect(readFile(path.join(practiceDir, "p1-my.practice-01_v2.ts"), "utf8")).resolves.toBe(
+      expectedCode("p1-my.practice-01_v2.ts"),
+    );
+  });
+
+  // 시퀀스가 double 정밀도 한계까지 커지면 다음 번호가 현재 최댓값과 같아져
+  // 계산된 파일명이 이미 존재하는 파일과 충돌합니다. 이때 덮어쓰면 안 됩니다.
+  it("계산한 파일명이 이미 있으면 덮어쓰지 않고 PRACTICE_FILE_EXISTS로 거절한다", async () => {
+    const collidingFileName = "p10000000000000000000-collide.ts";
+    await seedPracticeFiles([]);
+    await writeFile(path.join(practiceDir, collidingFileName), "기존 내용", "utf8");
+
+    await expect(runPractice("collide")).rejects.toMatchObject({
+      code: "PRACTICE_FILE_EXISTS",
+      exitCode: 2,
+    });
+
+    await expect(readFile(path.join(practiceDir, collidingFileName), "utf8")).resolves.toBe(
+      "기존 내용",
+    );
+    await expect(readdir(practiceDir)).resolves.toEqual([collidingFileName]);
+  });
+
+  it("상위 경로를 노리는 이름은 거절하고 루트 밖 파일을 건드리지 않는다", async () => {
+    const victimPath = path.join(apiRoot, "src", "victim.ts");
+    await writeFile(victimPath, "피해자 원본", "utf8");
+    // p1-../../../victim.ts는 practices 밖(api/src/victim.ts)으로 정규화되는 이름입니다.
+    const escapingName = "../../../victim";
+    expect(path.resolve(practiceDir, `p1-${escapingName}.ts`)).toBe(victimPath);
+
+    await expect(runPractice(escapingName)).rejects.toMatchObject({
+      code: "INVALID_PRACTICE_NAME",
+      exitCode: 2,
+    });
+
+    await expect(readFile(victimPath, "utf8")).resolves.toBe("피해자 원본");
+    // 이름 검증이 파일 시스템 접근보다 먼저이므로 practices 디렉터리도 만들지 않습니다.
+    await expect(readdir(practiceDir)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it.each([
+    ["큰따옴표가 섞인 이름", 'evil");console.log("'],
+    ["경로 구분자가 섞인 이름", "nested/practice"],
+    ["역슬래시가 섞인 이름", "escape\\practice"],
+    ["점으로 시작하는 이름", "..hidden"],
+    ["빈 문자열이 아닌 공백 포함 이름", "two words"],
+  ])("%s은 INVALID_PRACTICE_NAME으로 거절하고 아무 파일도 쓰지 않는다", async (_label, name) => {
+    await expect(runPractice(name)).rejects.toMatchObject({
+      code: "INVALID_PRACTICE_NAME",
+      exitCode: 2,
+    });
+
+    await expect(readdir(practiceDir)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("name이 없으면 인자 오류로 실패한다", async () => {
+    expect(tooling.stub).toBeDefined();
+
+    await expect(tooling.stub.practice({})).rejects.toMatchObject({
+      code: "MISSING_ARGUMENT",
+      exitCode: 2,
+    });
+  });
+});

package/src/tooling/__tests__/default-cdd-adapter.contract.test.ts

@@ -0,0 +1,73 @@
+import * as fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { createDefaultCddToolingAdapter } from "../cdd-service";
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })),
+  );
+});
+
+async function createFixture() {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "sonamu-default-cdd-"));
+  temporaryDirectories.push(workspace);
+  const contractRoot = path.join(workspace, "contract");
+  const outsideRoot = path.join(workspace, "outside");
+  await Promise.all([fs.mkdir(contractRoot), fs.mkdir(outsideRoot)]);
+  return { contractRoot, outsideRoot };
+}
+
+describe("기본 CDD tooling adapter", () => {
+  it("주입한 root와 fs로 내부 일반 파일을 읽고 수정한다", async () => {
+    const { contractRoot } = await createFixture();
+    const document = path.join(contractRoot, "order.contract.md");
+    await fs.writeFile(document, "# 주문\n", "utf8");
+    const adapter = createDefaultCddToolingAdapter({ contractRoot, fs });
+
+    await expect(adapter.read({ path: "order.contract.md" })).resolves.toEqual({
+      content: "# 주문\n",
+      fileType: "contract",
+    });
+    await adapter.addAcceptanceCriterion({
+      document: "order.contract.md",
+      text: "승인된 주문만 처리한다",
+      dryRun: false,
+    });
+    await expect(fs.readFile(document, "utf8")).resolves.toContain("승인된 주문만 처리한다");
+  });
+
+  it("외부 파일 symlink 읽기를 기본 adapter 경로에서도 거절한다", async () => {
+    const { contractRoot, outsideRoot } = await createFixture();
+    const outside = path.join(outsideRoot, "secret.contract.md");
+    await fs.writeFile(outside, "외부 비밀", "utf8");
+    await fs.symlink(outside, path.join(contractRoot, "linked.contract.md"));
+    const adapter = createDefaultCddToolingAdapter({ contractRoot, fs });
+
+    await expect(adapter.read({ path: "linked.contract.md" })).rejects.toMatchObject({
+      code: "INVALID_CDD_PATH",
+    });
+  });
+
+  it("외부 파일 symlink 쓰기를 거절하고 원본을 보존한다", async () => {
+    const { contractRoot, outsideRoot } = await createFixture();
+    const outside = path.join(outsideRoot, "protected.contract.md");
+    await fs.writeFile(outside, "보존할 내용\n", "utf8");
+    await fs.symlink(outside, path.join(contractRoot, "linked.contract.md"));
+    const adapter = createDefaultCddToolingAdapter({ contractRoot, fs });
+
+    await expect(
+      adapter.addAcceptanceCriterion({
+        document: "linked.contract.md",
+        text: "변조",
+        dryRun: false,
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_CDD_PATH" });
+    await expect(fs.readFile(outside, "utf8")).resolves.toBe("보존할 내용\n");
+  });
+});

package/src/tooling/__tests__/helpers/sonamu-test-root.ts

@@ -0,0 +1,42 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { Sonamu, type SonamuTestingSnapshot } from "../../../api/sonamu";
+import { type AbsolutePath } from "../../../utils/path-utils";
+
+const createdWorkspaces: string[] = [];
+let capturedSnapshot: SonamuTestingSnapshot | null = null;
+let capturedInitialized = false;
+
+/**
+ * 임시 api root를 만들어 Sonamu singleton의 공개 setter로 주입합니다.
+ *
+ * tooling 연산은 `Sonamu.isInitialized`가 참이면 초기화를 건너뛰므로,
+ * 실제 DB/설정 없이 파일 경로 기반 동작만 검증할 수 있습니다.
+ */
+export async function attachSonamuTestRoot(): Promise<string> {
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "sonamu-tooling-"));
+  createdWorkspaces.push(workspace);
+  const apiRootPath = path.join(workspace, "api");
+  await mkdir(path.join(apiRootPath, "src", "application"), { recursive: true });
+
+  capturedSnapshot ??= Sonamu.captureTestingSnapshot();
+  capturedInitialized = Sonamu.isInitialized;
+  // SAFETY: mkdtemp가 반환한 절대 경로만 주입합니다.
+  Sonamu.apiRootPath = apiRootPath as AbsolutePath;
+  Sonamu.isInitialized = true;
+  return apiRootPath;
+}
+
+/** 주입한 Sonamu 상태를 되돌리고 임시 디렉터리를 정리합니다. */
+export async function detachSonamuTestRoot(): Promise<void> {
+  if (capturedSnapshot !== null) {
+    Sonamu.restoreTestingSnapshot(capturedSnapshot);
+    capturedSnapshot = null;
+  }
+  Sonamu.isInitialized = capturedInitialized;
+  await Promise.all(
+    createdWorkspaces.splice(0).map((workspace) => rm(workspace, { recursive: true, force: true })),
+  );
+}

package/src/tooling/__tests__/test-run-client-config.contract.test.ts

@@ -0,0 +1,154 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { type AddressInfo } from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { createDefaultTestRunClient } from "../test-run-client";
+
+const STATUS_PAYLOAD = { running: false };
+const RUN_RESULT = {
+  ok: true,
+  summary: { total: 1, passed: 1, failed: 0, skipped: 0, durationMs: 12 },
+  results: [],
+};
+
+const originalVitest = process.env.VITEST;
+const originalHot = process.env.HOT;
+const temporaryRoots: string[] = [];
+const startedServers: Server[] = [];
+
+/** DevRunner 응답을 대신하는 실제 로컬 HTTP 서버를 띄웁니다. */
+async function startDevRunnerServer(): Promise<number> {
+  const server = createServer((request, response) => {
+    response.setHeader("content-type", "application/json");
+    if (request.url === "/__test__/status") {
+      response.end(JSON.stringify(STATUS_PAYLOAD));
+      return;
+    }
+    if (request.url === "/__test__/run") {
+      response.end(JSON.stringify(RUN_RESULT));
+      return;
+    }
+    response.statusCode = 404;
+    response.end("{}");
+  });
+  startedServers.push(server);
+  await new Promise<void>((resolve) => {
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  // SAFETY: TCP listen 이후의 주소는 항상 AddressInfo 입니다.
+  const address = server.address() as AddressInfo;
+  return address.port;
+}
+
+/** dist 빌드 없이 src/sonamu.config.ts만 가진 일반 개발 프로젝트를 만듭니다. */
+async function createSourceOnlyProject(port: number | null): Promise<string> {
+  const projectRoot = await mkdtemp(path.join(os.tmpdir(), "sonamu-test-run-client-"));
+  temporaryRoots.push(projectRoot);
+  await mkdir(path.join(projectRoot, "src"), { recursive: true });
+  await writeFile(path.join(projectRoot, ".env"), "SONAMU_TEST_RUN_CLIENT=1\n");
+  if (port === null) return projectRoot;
+
+  await writeFile(
+    path.join(projectRoot, "src", "sonamu.config.ts"),
+    `
+export default {
+  server: { listen: { host: "127.0.0.1", port: ${port} } },
+  test: { devRunner: { enabled: true, routePrefix: "/__test__" } },
+};
+`,
+  );
+  return projectRoot;
+}
+
+function enterPlainDevShell(): void {
+  // dist 설정을 고르는 환경변수가 없는 일반 개발 셸을 재현합니다.
+  delete process.env.VITEST;
+  delete process.env.HOT;
+}
+
+afterEach(async () => {
+  if (originalVitest === undefined) delete process.env.VITEST;
+  else process.env.VITEST = originalVitest;
+  if (originalHot === undefined) delete process.env.HOT;
+  else process.env.HOT = originalHot;
+
+  await Promise.all(
+    startedServers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.close(() => resolve());
+        }),
+    ),
+  );
+  await Promise.all(
+    temporaryRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+  );
+});
+
+describe("test-run-client의 sonamu.config 로딩", () => {
+  it("dist 빌드가 없어도 status가 src/sonamu.config.ts를 읽는다", async () => {
+    const port = await startDevRunnerServer();
+    const projectRoot = await createSourceOnlyProject(port);
+    enterPlainDevShell();
+
+    await expect(createDefaultTestRunClient(projectRoot).status()).resolves.toEqual(STATUS_PAYLOAD);
+    expect(process.env.VITEST).toBeUndefined();
+  });
+
+  it("dist 빌드가 없어도 run이 src/sonamu.config.ts를 읽는다", async () => {
+    const port = await startDevRunnerServer();
+    const projectRoot = await createSourceOnlyProject(port);
+    enterPlainDevShell();
+
+    await expect(
+      createDefaultTestRunClient(projectRoot).run({ files: ["a.test.ts"] }),
+    ).resolves.toMatchObject({ ok: true });
+    expect(process.env.VITEST).toBeUndefined();
+  });
+
+  it("기존 VITEST 값은 설정 로딩 후 원래 값으로 되돌린다", async () => {
+    const port = await startDevRunnerServer();
+    const projectRoot = await createSourceOnlyProject(port);
+    enterPlainDevShell();
+    process.env.VITEST = "false";
+
+    await expect(createDefaultTestRunClient(projectRoot).status()).resolves.toEqual(STATUS_PAYLOAD);
+    expect(process.env.VITEST).toBe("false");
+  });
+
+  it("설정 파일이 없으면 TEST_RUN_CONFIG_ERROR로 실패하고 환경변수를 복원한다", async () => {
+    const projectRoot = await createSourceOnlyProject(null);
+    enterPlainDevShell();
+
+    await expect(createDefaultTestRunClient(projectRoot).status()).rejects.toMatchObject({
+      code: "TEST_RUN_CONFIG_ERROR",
+    });
+    expect(process.env.VITEST).toBeUndefined();
+  });
+
+  it("devRunner가 비활성화되어 있으면 설정 오류로 실패한다", async () => {
+    const projectRoot = await mkdtemp(path.join(os.tmpdir(), "sonamu-test-run-client-off-"));
+    temporaryRoots.push(projectRoot);
+    await mkdir(path.join(projectRoot, "src"), { recursive: true });
+    await writeFile(path.join(projectRoot, ".env"), "SONAMU_TEST_RUN_CLIENT=1\n");
+    await writeFile(
+      path.join(projectRoot, "src", "sonamu.config.ts"),
+      `
+export default {
+  server: { listen: { host: "127.0.0.1", port: 3000 } },
+  test: { devRunner: { enabled: false } },
+};
+`,
+    );
+    enterPlainDevShell();
+
+    await expect(createDefaultTestRunClient(projectRoot).status()).rejects.toMatchObject({
+      code: "TEST_RUN_CONFIG_ERROR",
+    });
+    expect(process.env.VITEST).toBeUndefined();
+  });
+});

package/src/tooling/cdd-service.ts

@@ -0,0 +1,256 @@
+import { constants } from "node:fs";
+import * as defaultFs from "node:fs/promises";
+import path from "node:path";
+
+type CddFileSystem = Pick<typeof defaultFs, "lstat" | "mkdir" | "open" | "opendir" | "realpath">;
+
+function invalidCddPath(relativePath: string, cause?: unknown): Error {
+  return Object.assign(new Error(`CDD 경로가 contract 밖을 참조합니다: ${relativePath}`), {
+    code: "INVALID_CDD_PATH",
+    cause,
+  });
+}
+
+function isWithin(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+}
+
+async function nearestExistingPath(fs: CddFileSystem, target: string): Promise<string> {
+  let candidate = target;
+  while (true) {
+    try {
+      await fs.lstat(candidate);
+      return candidate;
+    } catch (error) {
+      // SAFETY: node:fs lstat 실패의 code만 읽어 경로 부재를 구분합니다.
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      const parent = path.dirname(candidate);
+      if (parent === candidate) throw error;
+      candidate = parent;
+    }
+  }
+}
+
+function createCddFileOperation({
+  contractRoot,
+  fs = defaultFs,
+}: {
+  contractRoot: string;
+  fs?: CddFileSystem;
+}) {
+  async function resolveBoundary(relativePath: string) {
+    const [canonicalRoot, configuredRoot] = await Promise.all([
+      fs.realpath(contractRoot),
+      Promise.resolve(path.resolve(contractRoot)),
+    ]);
+    const target = path.resolve(configuredRoot, relativePath);
+    if (!isWithin(configuredRoot, target)) throw invalidCddPath(relativePath);
+    return { canonicalRoot, target };
+  }
+
+  async function assertCanonicalPath(
+    canonicalRoot: string,
+    target: string,
+    relativePath: string,
+  ): Promise<string> {
+    const canonicalTarget = await fs.realpath(target);
+    if (!isWithin(canonicalRoot, canonicalTarget)) throw invalidCddPath(relativePath);
+    return canonicalTarget;
+  }
+
+  return {
+    async readDirectory(relativePath: string) {
+      const { canonicalRoot, target } = await resolveBoundary(relativePath);
+      const canonicalTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+      let directory;
+      try {
+        directory = await fs.opendir(target);
+        const recheckedTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+        if (recheckedTarget !== canonicalTarget) throw invalidCddPath(relativePath);
+        const entries = [];
+        while (true) {
+          const entry = await directory.read();
+          if (entry === null) return entries;
+          entries.push(entry);
+        }
+      } finally {
+        await directory?.close();
+      }
+    },
+    async read(relativePath: string): Promise<string> {
+      const { canonicalRoot, target } = await resolveBoundary(relativePath);
+      const canonicalTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+      let handle;
+      try {
+        // 최종 symlink를 따라가지 않은 descriptor를 연 뒤 실제 경로를 다시 확인합니다.
+        handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const recheckedTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+        if (recheckedTarget !== canonicalTarget) throw invalidCddPath(relativePath);
+        return await handle.readFile("utf8");
+      } catch (error) {
+        // SAFETY: node:fs open 실패의 code만 읽어 symlink 거부를 정규화합니다.
+        if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+          throw invalidCddPath(relativePath, error);
+        }
+        throw error;
+      } finally {
+        await handle?.close();
+      }
+    },
+
+    async write(relativePath: string, contents: string): Promise<void> {
+      const { canonicalRoot, target } = await resolveBoundary(relativePath);
+      const existing = await nearestExistingPath(fs, target);
+      const canonicalExisting = await assertCanonicalPath(canonicalRoot, existing, relativePath);
+      const targetExists = existing === target;
+
+      if (!targetExists) {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await assertCanonicalPath(canonicalRoot, path.dirname(target), relativePath);
+      }
+
+      let handle;
+      try {
+        // 검증 전 truncate를 피하고 새 파일은 배타적으로 생성합니다.
+        const flags = targetExists
+          ? constants.O_WRONLY | constants.O_NOFOLLOW
+          : constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+        handle = await fs.open(target, flags, 0o666);
+        const canonicalTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+        if (
+          !isWithin(canonicalRoot, canonicalTarget) ||
+          (targetExists && canonicalTarget !== canonicalExisting)
+        ) {
+          throw invalidCddPath(relativePath);
+        }
+        await handle.truncate(0);
+        await handle.writeFile(contents, "utf8");
+      } catch (error) {
+        // SAFETY: node:fs open 실패의 code만 읽어 symlink 거부를 정규화합니다.
+        if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+          throw invalidCddPath(relativePath, error);
+        }
+        throw error;
+      } finally {
+        await handle?.close();
+      }
+    },
+  };
+}
+
+type CddRuleDocument = {
+  description?: string;
+  rules?: Array<{ id: string; when: string; instruction: string; examples?: string[] }>;
+};
+
+function parseCddRules(contents: string): CddRuleDocument {
+  try {
+    // SAFETY: CDD 규칙 소비 지점은 선택 필드만 읽고 배열 부재를 기본값으로 처리합니다.
+    return JSON.parse(contents) as CddRuleDocument;
+  } catch (cause) {
+    throw Object.assign(new Error("CDD rules JSON is malformed"), {
+      code: "INVALID_CDD_RULES",
+      exitCode: 2,
+      cause,
+    });
+  }
+}
+
+/**
+ * 규칙 문서를 읽되, 아직 파일이 없으면 빈 문서로 취급합니다.
+ *
+ * 첫 규칙 등록 시 rules 디렉터리와 파일이 없는 상태를 부트스트랩하기 위한 처리이며,
+ * 깨진 JSON은 그대로 INVALID_CDD_RULES로 실패시켜 덮어쓰기를 막습니다.
+ */
+async function readCddRuleDocument(
+  files: { read(relativePath: string): Promise<string> },
+  relativePath: string,
+): Promise<CddRuleDocument> {
+  try {
+    return parseCddRules(await files.read(relativePath));
+  } catch (error) {
+    // SAFETY: node:fs 읽기 실패의 code만 읽어 규칙 문서 부재를 구분합니다.
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+export function createDefaultCddToolingAdapter({
+  contractRoot,
+  fs = defaultFs,
+}: {
+  contractRoot: string;
+  fs?: CddFileSystem;
+}) {
+  const files = createCddFileOperation({ contractRoot, fs });
+
+  return {
+    async read(input: { path: string }) {
+      return { content: await files.read(input.path), fileType: "contract" as const };
+    },
+    async rules() {
+      let entries;
+      try {
+        entries = await files.readDirectory("rules");
+      } catch (error) {
+        // SAFETY: node:fs 디렉터리 조회 실패의 code만 읽어 규칙 디렉터리 부재를 구분합니다.
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return { rules: [] };
+        throw error;
+      }
+
+      const rules = [];
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".rules.json")) continue;
+        const key = entry.name.replace(/\.rules\.json$/, "");
+        const relativePath = `rules/${entry.name}`;
+        const document = parseCddRules(await files.read(relativePath));
+        rules.push({
+          key,
+          path: relativePath,
+          description: document.description ?? "",
+          ruleCount: document.rules?.length ?? 0,
+        });
+      }
+      return { rules };
+    },
+    async showRule(input: { ruleId: string }) {
+      const relativePath = `rules/${input.ruleId}.rules.json`;
+      return {
+        key: input.ruleId,
+        path: relativePath,
+        ...parseCddRules(await files.read(relativePath)),
+      };
+    },
+    async addRule(input: {
+      ruleKey: string;
+      id: string;
+      when: string;
+      text: string;
+      examples?: string[];
+      dryRun: boolean;
+    }) {
+      const rule = { ruleKey: input.ruleKey, id: input.id, when: input.when, text: input.text };
+      if (input.dryRun) return { dryRun: true as const, rule };
+
+      const relativePath = `rules/${input.ruleKey}.rules.json`;
+      const document = await readCddRuleDocument(files, relativePath);
+      document.rules ??= [];
+      document.rules.push({
+        id: input.id,
+        when: input.when,
+        instruction: input.text,
+        examples: input.examples ?? [],
+      });
+      await files.write(relativePath, `${JSON.stringify(document, null, 2)}\n`);
+      return { key: input.ruleKey, path: relativePath, ...document };
+    },
+    async addAcceptanceCriterion(input: { document: string; text: string; dryRun: boolean }) {
+      if (input.dryRun)
+        return { operation: "addAcceptanceCriterion" as const, input, dryRun: true };
+      const contents = await files.read(input.document);
+      await files.write(input.document, `${contents}\n- ${input.text}\n`);
+      return { document: input.document, text: input.text, applied: true as const };
+    },
+  };
+}