sonamu 0.10.11 → 0.10.13

package/src/ui/async-route.ts

@@ -0,0 +1,4 @@
+/** Fastify가 비동기 실패를 오류 처리기로 전달할 수 있도록 Promise를 반환합니다. */
+export function forwardAsyncErrors<Result>(handler: () => Promise<Result>): Promise<Result> {
+  return Promise.resolve().then(handler);
+}

package/src/ui/cdd-service.ts

@@ -4,6 +4,7 @@ import os from "os";
 import path from "path";
 
 import { Sonamu } from "../api/sonamu";
+import { isStringValue } from "../utils/runtime-value";
 import {
   type CddAcEntry,
   type CddAcFile,
@@ -17,6 +18,22 @@ import {
   type CddTreeNode,
 } from "./cdd-types";
 
+interface CddTreeResult {
+  exists: boolean;
+  tree: CddTreeNode[];
+}
+interface EditorCliConfig {
+  cli: string;
+  waitFlag: string;
+}
+interface EditorCliResolution {
+  bin: string;
+  args: string[];
+}
+interface CddRulesResult {
+  rules: CddRuleSummary[];
+}
+
 export type {
   CddAcEntry,
   CddAcFile,
@@ -93,7 +110,7 @@ function scanDirectory(dirPath: string, relativeTo: string): CddTreeNode[] {
 }
 
 /** contract/ 디렉터리의 트리 구조를 반환 */
-export function getCddTree(): { exists: boolean; tree: CddTreeNode[] } {
+export function getCddTree(): CddTreeResult {
   const contractDir = getContractDir();
   if (!fs.existsSync(contractDir)) {
     return { exists: false, tree: [] };
@@ -142,17 +159,17 @@ export async function editContent(
 }
 
 /** 에디터별 앱 번들 내 CLI 경로 + --wait 플래그 매핑 */
-const EDITOR_CLI_MAP: Record<string, { cli: string; waitFlag: string }> = {
+const EDITOR_CLI_MAP = {
   "Visual Studio Code": { cli: "Contents/Resources/app/bin/code", waitFlag: "--wait" },
   Zed: { cli: "Contents/MacOS/cli", waitFlag: "--wait" },
   Cursor: { cli: "Contents/Resources/app/bin/cursor", waitFlag: "--wait" },
-};
+} satisfies Record<string, EditorCliConfig>;
 
 /** 앱 번들 CLI 경로를 resolve. wait=false이면 --wait 플래그를 생략 */
-function resolveEditorCli(options?: { wait?: boolean }): { bin: string; args: string[] } {
+function resolveEditorCli(options?: { wait?: boolean }): EditorCliResolution {
   const wait = options?.wait ?? true;
   const appName = Sonamu.config.externalEditor ?? "Visual Studio Code";
-  const mapping = EDITOR_CLI_MAP[appName];
+  const mapping = Object.entries(EDITOR_CLI_MAP).find(([name]) => name === appName)?.[1];
   if (!mapping) {
     throw new Error(
       `지원되지 않는 에디터입니다: ${appName} (지원: ${Object.keys(EDITOR_CLI_MAP).join(", ")})`,
@@ -218,7 +235,7 @@ export function openSourceFile(filePath: string): void {
  * ======================================================================== */
 
 /** contract/rules/ 디렉터리 내 .rules.json 파일 목록 반환 */
-export function listRules(): { rules: CddRuleSummary[] } {
+export function listRules(): CddRulesResult {
   const contractDir = getContractDir();
   const rulesDir = path.join(contractDir, "rules");
   if (!fs.existsSync(rulesDir)) return { rules: [] };
@@ -235,11 +252,13 @@ export function listRules(): { rules: CddRuleSummary[] } {
 
     try {
       const raw = fs.readFileSync(absPath, "utf-8");
-      const doc = JSON.parse(raw) as { description?: string; rules?: unknown[] };
+      const doc = /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ JSON.parse(
+        raw,
+      ) as { description?: string; rules?: unknown[] };
       rules.push({
         key,
         path: relPath,
-        description: typeof doc.description === "string" ? doc.description : "",
+        description: isStringValue(doc.description) ? doc.description : "",
         ruleCount: Array.isArray(doc.rules) ? doc.rules.length : 0,
       });
     } catch (err) {
@@ -266,12 +285,14 @@ export function readRule(ruleKey: string): CddRuleDetail {
   }
 
   const raw = fs.readFileSync(absPath, "utf-8");
-  const doc = JSON.parse(raw) as { description?: string; rules?: CddRuleEntry[] };
+  const doc = /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ JSON.parse(
+    raw,
+  ) as { description?: string; rules?: CddRuleEntry[] };
 
   return {
     key: ruleKey,
     path: `rules/${ruleKey}.rules.json`,
-    description: typeof doc.description === "string" ? doc.description : "",
+    description: isStringValue(doc.description) ? doc.description : "",
     rules: Array.isArray(doc.rules) ? doc.rules : [],
   };
 }
@@ -287,7 +308,9 @@ export function addRule(req: CddAddRuleRequest): CddRuleDetail {
   }
 
   const raw = fs.readFileSync(absPath, "utf-8");
-  const doc = JSON.parse(raw) as { description?: string; rules?: CddRuleEntry[] };
+  const doc = /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ JSON.parse(
+    raw,
+  ) as { description?: string; rules?: CddRuleEntry[] };
   const rules: CddRuleEntry[] = Array.isArray(doc.rules) ? doc.rules : [];
 
   const nextId = generateNextRuleId(rules);
@@ -308,7 +331,7 @@ export function addRule(req: CddAddRuleRequest): CddRuleDetail {
   return {
     key: req.ruleKey,
     path: `rules/${req.ruleKey}.rules.json`,
-    description: typeof doc.description === "string" ? doc.description : "",
+    description: isStringValue(doc.description) ? doc.description : "",
     rules,
   };
 }

package/src/ui/migrations-api.ts

@@ -0,0 +1,381 @@
+import { readFile } from "fs/promises";
+import { PassThrough } from "stream";
+
+import { type FastifyInstance, type FastifyReply } from "fastify";
+
+import { Sonamu } from "../api/sonamu";
+import { type SonamuDBConfig } from "../database/db";
+import { SD } from "../dict/sd";
+import { BadRequestException } from "../exceptions/so-exceptions";
+import {
+  Migrator,
+  MigrationTargetExecutionError,
+  type MigrationResult,
+} from "../migration/migrator";
+import { SlackConfirm, type SlackConfirmPendingResult } from "../migration/slack-confirm";
+import {
+  type MigrationAction,
+  type MigrationConnectionStatus,
+  type MigrationProgressEvent,
+  type MigrationStreamEvent,
+  type MigrationTarget,
+} from "../migration/types";
+import { forwardAsyncErrors } from "./async-route";
+
+type ApprovalReady = { type: "ready" };
+type ApprovalResult = ApprovalReady | SlackConfirmPendingResult;
+type ApplyBody = { targets: MigrationTarget[]; requestor?: string };
+type LegacyApplyBody = ApplyBody & { force?: boolean; forceReason?: string };
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1"]);
+
+function assertTargets(migrator: Migrator, targets: MigrationTarget[]): void {
+  const allowed = new Set(migrator.getConnections().map(({ connKey }) => connKey));
+  const invalid = targets.filter((target) => !allowed.has(target));
+  if (targets.length === 0 || invalid.length > 0) {
+    throw new BadRequestException(SD("error.badRequest"), {
+      message: `Invalid migration targets: ${invalid.length === 0 ? "(empty)" : invalid.join(", ")}`,
+    });
+  }
+}
+
+function targetRequiresApproval(slack: SlackConfirm, target: MigrationTarget): boolean {
+  const connection = /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ Sonamu
+    .dbConfig[target]?.connection as { host?: string } | undefined;
+  const remote = !LOCAL_HOSTS.has((connection?.host ?? "localhost").toLowerCase());
+  return remote && slack.isTargetRequiresApproval(target);
+}
+
+async function getAvailableTargetStatuses(
+  migrator: Migrator,
+  targets: MigrationTarget[],
+): Promise<MigrationConnectionStatus[]> {
+  const statuses = await Promise.all(targets.map((target) => migrator.getConnectionStatus(target)));
+  const failed = statuses.filter(({ status, error }) => status === "error" || error !== undefined);
+  if (failed.length > 0) {
+    throw new BadRequestException(SD("error.badRequest"), {
+      message: `Migration status could not be verified: ${failed.map(({ connKey }) => connKey).join(", ")}`,
+    });
+  }
+  return statuses;
+}
+
+function getPendingMigrations(statuses: MigrationConnectionStatus[]) {
+  return [...new Set(statuses.flatMap(({ pending }) => pending))];
+}
+
+async function requestApproval(
+  migrator: Migrator,
+  targets: MigrationTarget[],
+  requestor?: string,
+): Promise<ApprovalResult> {
+  assertTargets(migrator, targets);
+  const statuses = await getAvailableTargetStatuses(migrator, targets);
+  const slack = new SlackConfirm();
+  const requiresApproval = targets.some((target) => targetRequiresApproval(slack, target));
+  if (!requiresApproval || !slack.isConfigured()) {
+    return { type: "ready" };
+  }
+
+  const pending = getPendingMigrations(statuses);
+  if (pending.length === 0) {
+    return { type: "ready" };
+  }
+
+  const existing = await slack.getExistingRequest(pending);
+  if (existing !== null) {
+    const approval = await slack.checkApproval(existing.channel, existing.ts);
+    if (approval.approved) {
+      return { type: "ready" };
+    }
+    if (approval.rejected) {
+      throw new BadRequestException(SD("sonamu.error.migrationRejected"));
+    }
+    return { type: "pending", ...existing };
+  }
+
+  const created = await slack.postApprovalRequest(pending, targets, requestor);
+  await slack.saveRequest(pending, created.channel, created.ts);
+  return { type: "pending", ...created };
+}
+
+async function requireApprovedApply(
+  body: ApplyBody,
+  statuses: MigrationConnectionStatus[],
+): Promise<{ channel: string; ts: string } | null> {
+  const slack = new SlackConfirm();
+  const requiresApproval = body.targets.some((target) => targetRequiresApproval(slack, target));
+  if (!requiresApproval || !slack.isConfigured()) {
+    return null;
+  }
+
+  const pending = getPendingMigrations(statuses);
+  if (pending.length === 0) {
+    return null;
+  }
+
+  const existing = await slack.getExistingRequest(pending);
+  if (existing === null) {
+    throw new BadRequestException(SD("error.badRequest"), {
+      message: "Slack approval has not been requested",
+    });
+  }
+  const approval = await slack.checkApproval(existing.channel, existing.ts);
+  if (approval.rejected) {
+    throw new BadRequestException(SD("sonamu.error.migrationRejected"));
+  }
+  if (!approval.approved) {
+    throw new BadRequestException(SD("error.badRequest"), {
+      message: "Slack approval is still pending",
+    });
+  }
+  return existing;
+}
+
+async function runLegacyApply(
+  migrator: Migrator,
+  body: LegacyApplyBody,
+): Promise<MigrationResult | SlackConfirmPendingResult> {
+  assertTargets(migrator, body.targets);
+  const statuses = await getAvailableTargetStatuses(migrator, body.targets);
+  const slack = new SlackConfirm();
+  const requiresApproval = body.targets.some((target) => targetRequiresApproval(slack, target));
+  if (!requiresApproval || !slack.isConfigured()) {
+    return migrator.apply(body.targets);
+  }
+
+  const pending = getPendingMigrations(statuses);
+  if (pending.length === 0) {
+    return migrator.apply(body.targets);
+  }
+
+  const existing = await slack.getExistingRequest(pending);
+  if (existing === null) {
+    const created = await slack.postApprovalRequest(pending, body.targets, body.requestor);
+    await slack.saveRequest(pending, created.channel, created.ts);
+    return { type: "pending", ...created };
+  }
+
+  const approval = await slack.checkApproval(existing.channel, existing.ts);
+  if (approval.rejected) {
+    throw new BadRequestException(SD("sonamu.error.migrationRejected"));
+  }
+  if (!approval.approved && !body.force) {
+    return { type: "pending", ...existing };
+  }
+  if (!approval.approved) {
+    await slack.forceApproval(
+      existing.channel,
+      existing.ts,
+      body.forceReason ?? "사유 없음",
+      body.requestor,
+    );
+  }
+
+  const result = await migrator.apply(body.targets);
+  if (result.length > 0) {
+    await slack.logExecution(existing.channel, existing.ts, result, body.requestor);
+  }
+  return result;
+}
+
+function sendMigrationStream(
+  reply: FastifyReply,
+  action: MigrationAction,
+  targets: MigrationTarget[],
+  run: (onProgress: (event: MigrationProgressEvent) => void) => Promise<MigrationResult>,
+  afterComplete?: (result: MigrationResult) => Promise<void>,
+) {
+  const stream = new PassThrough();
+  let canWrite = true;
+  let current: MigrationProgressEvent | undefined;
+  const completedTargets: MigrationTarget[] = [];
+  const write = (event: MigrationStreamEvent) => {
+    if (canWrite && !stream.destroyed) {
+      stream.write(`${JSON.stringify(event)}\n`);
+    }
+  };
+
+  stream.on("close", () => {
+    canWrite = false;
+  });
+  reply
+    .header("content-type", "application/x-ndjson; charset=utf-8")
+    .header("cache-control", "no-cache, no-transform")
+    .header("content-encoding", "identity")
+    .header("x-no-compression", "1");
+
+  void (async () => {
+    try {
+      const result = await run((event) => {
+        if (event.type === "target-complete") {
+          if (event.connKey !== "shadow") completedTargets.push(event.connKey);
+          write(event);
+          // 다음 target의 lifecycle이 시작되기 전 오류를 직전 target에 잘못 귀속하지 않습니다.
+          current = undefined;
+          return;
+        }
+        current = event;
+        write(event);
+      });
+      await afterComplete?.(result);
+      write({ type: "complete", result });
+    } catch (caught) {
+      const message = caught instanceof Error ? caught.message : String(caught);
+      const failedTarget =
+        caught instanceof MigrationTargetExecutionError ? caught.connKey : current?.connKey;
+      write({
+        type: "error",
+        action,
+        message,
+        connKey: failedTarget,
+        file:
+          current?.type === "file-start" || current?.type === "file-executed"
+            ? current.file
+            : undefined,
+        completedTargets,
+        pendingTargets: targets.filter((target) => !completedTargets.includes(target)),
+      });
+    } finally {
+      if (!stream.destroyed) {
+        stream.end();
+      }
+    }
+  })();
+
+  return reply.send(stream);
+}
+
+export async function registerMigrationsApi(server: FastifyInstance) {
+  const migrator = new Migrator();
+
+  server.get("/api/migrations/connections", async () => ({
+    connections: migrator.getConnections(),
+  }));
+  server.get("/api/migrations/codes", async () => ({ codes: await migrator.getMigrationCodes() }));
+  server.get<{ Querystring: { codeName: string } }>("/api/migrations/code", (request) =>
+    forwardAsyncErrors(async () => {
+      const migrationCode = (await migrator.getMigrationCodes()).find(
+        ({ name }) => name === request.query.codeName,
+      );
+      if (migrationCode === undefined) {
+        throw new BadRequestException(SD("error.badRequest"));
+      }
+      return { code: await readFile(migrationCode.path, "utf8") };
+    }),
+  );
+  server.get<{ Querystring: { connKey?: MigrationTarget } }>("/api/migrations/status", (request) =>
+    forwardAsyncErrors(async () => {
+      if (request.query.connKey === undefined) {
+        return { status: await migrator.getStatus() };
+      }
+      return { status: await migrator.getConnectionStatus(request.query.connKey) };
+    }),
+  );
+  server.get<{ Querystring: { compareConnKey: MigrationTarget } }>(
+    "/api/migrations/prepared-codes",
+    (request) =>
+      forwardAsyncErrors(async () => ({
+        preparedCodes: await migrator.getPreparedCodes(request.query.compareConnKey),
+      })),
+  );
+
+  server.post<{ Body: ApplyBody }>("/api/migrations/request-approval", (request) =>
+    forwardAsyncErrors(async () => {
+      return requestApproval(migrator, request.body.targets, request.body.requestor);
+    }),
+  );
+  server.post<{ Body: { channel: string; ts: string } }>(
+    "/api/migrations/checkApproval",
+    (request) =>
+      forwardAsyncErrors(async () => {
+        const slack = new SlackConfirm();
+        return slack.isConfigured()
+          ? slack.checkApproval(request.body.channel, request.body.ts)
+          : { approved: true, rejected: false };
+      }),
+  );
+  server.post<{
+    Body: { channel: string; ts: string; reason: string; requestor?: string };
+  }>("/api/migrations/forceApproval", (request) =>
+    forwardAsyncErrors(async () => {
+      const slack = new SlackConfirm();
+      if (!slack.isConfigured()) {
+        throw new BadRequestException(SD("sonamu.error.slackConfirmNotConfigured"));
+      }
+      await slack.forceApproval(
+        request.body.channel,
+        request.body.ts,
+        request.body.reason,
+        request.body.requestor,
+      );
+      return { success: true };
+    }),
+  );
+
+  server.post("/api/migrations/shadow", async (_request, reply) => {
+    return sendMigrationStream(reply, "shadow", [], (onProgress) => {
+      return migrator.runShadowTest({ onProgress });
+    });
+  });
+  server.post<{ Body: ApplyBody }>("/api/migrations/apply", async (request, reply) => {
+    assertTargets(migrator, request.body.targets);
+    const statuses = await getAvailableTargetStatuses(migrator, request.body.targets);
+    const approval = await requireApprovedApply(request.body, statuses);
+    return sendMigrationStream(
+      reply,
+      "apply",
+      request.body.targets,
+      (onProgress) => migrator.apply(request.body.targets, { onProgress }),
+      approval === null
+        ? undefined
+        : async (result) => {
+            await new SlackConfirm().logExecution(
+              approval.channel,
+              approval.ts,
+              result,
+              request.body.requestor,
+            );
+          },
+    );
+  });
+  server.post<{ Body: { targets: MigrationTarget[] } }>(
+    "/api/migrations/rollback",
+    async (request, reply) => {
+      assertTargets(migrator, request.body.targets);
+      await getAvailableTargetStatuses(migrator, request.body.targets);
+      return sendMigrationStream(reply, "rollback", request.body.targets, (onProgress) => {
+        return migrator.rollback(request.body.targets, { onProgress });
+      });
+    },
+  );
+
+  server.post<{ Body: { compareConnKey?: MigrationTarget } }>(
+    "/api/migrations/generatePreparedCodes",
+    (request) =>
+      forwardAsyncErrors(async () => migrator.generatePreparedCodes(request.body.compareConnKey)),
+  );
+
+  // 이전 UI 번들과 외부 스크립트가 새 서버에서도 한 릴리스 동안 동작하도록 유지합니다.
+  server.post<{
+    Body: {
+      action: "apply" | "rollback" | "shadow";
+      targets: (keyof SonamuDBConfig)[];
+      force?: boolean;
+      forceReason?: string;
+      requestor?: string;
+    };
+  }>("/api/migrations/runAction", (request) =>
+    forwardAsyncErrors(async () => {
+      if (request.body.action === "shadow") {
+        return migrator.runShadowTest();
+      }
+      if (request.body.action === "apply") {
+        return runLegacyApply(migrator, request.body);
+      }
+      assertTargets(migrator, request.body.targets);
+      await getAvailableTargetStatuses(migrator, request.body.targets);
+      return migrator.rollback(request.body.targets);
+    }),
+  );
+}

package/src/utils/formatter.ts

@@ -10,8 +10,9 @@ import { format, type FormatConfig } from "oxfmt";
 import { cached } from "./async-utils";
 import { isTest } from "./controller";
 import { execute } from "./process-utils";
+import { isNumberValue } from "./runtime-value";
 
-const _require = createRequire(import.meta.url);
+const requireFromHere = createRequire(import.meta.url);
 
 /**
  * 코드를 프로젝트의 oxfmt + oxlint 설정에 맞춰 포매팅한 문자열을 반환합니다.
@@ -75,9 +76,11 @@ async function loadOxfmtConfig(): Promise<FormatConfig> {
   while (true) {
     const candidate = join(dir, ".oxfmtrc.json");
     try {
+      // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
       cachedOxfmtConfig = JSON.parse(await readFile(candidate, "utf-8")) as FormatConfig;
       return cachedOxfmtConfig;
     } catch (e) {
+      // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
       if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
         !isTest() && console.error(`Failed to load ${candidate}:`, e);
         break;
@@ -121,7 +124,8 @@ async function runOxlint(code: string): Promise<string> {
       });
     } catch (e) {
       // lint 위반 시 exit code != 0이지만 --fix는 적용됨. exec 자체 실패만 throw.
-      if (typeof (e as Error & { code?: number }).code !== "number") {
+      // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
+      if (!isNumberValue((e as Error & { code?: number }).code)) {
         throw e;
       }
     }
@@ -138,7 +142,7 @@ async function runOxlint(code: string): Promise<string> {
 
 function resolveOxlintBin(): string {
   try {
-    return _require.resolve("oxlint/bin/oxlint");
+    return requireFromHere.resolve("oxlint/bin/oxlint");
   } catch {
     return "oxlint";
   }

package/src/utils/fs-utils.ts

@@ -8,12 +8,12 @@ import { formatCode } from "./formatter";
 /**
  * fs/promises에는 exists가 없어요. 대신 access가 있습니다.
  * 근데 얘는 인터페이스가 쓰기 불편해요. 그래서 감싸주었습니다.
- * @param path
+ * @param targetPath
  * @returns
  */
-export async function exists(path: PathLike): Promise<boolean> {
+export async function exists(targetPath: PathLike): Promise<boolean> {
   try {
-    await access(path, constants.F_OK);
+    await access(targetPath, constants.F_OK);
     return true;
   } catch {
     return false;
@@ -21,9 +21,9 @@ export async function exists(path: PathLike): Promise<boolean> {
 }
 
 // 디렉토리가 아니라 파일만 존재하는지 확인합니다.
-export async function fileExists(path: PathLike): Promise<boolean> {
+export async function fileExists(targetPath: PathLike): Promise<boolean> {
   try {
-    const stats = await stat(path);
+    const stats = await stat(targetPath);
     return stats.isFile();
   } catch {
     return false;

package/src/utils/model.ts

@@ -1,9 +1,7 @@
-import { type SonamuQueryMode } from "../types/types";
+import { type SonamuQueryMode, type SonamuSemanticParams } from "../types/types";
 
 // semanticQuery가 있으면 similarity를 추가하는 조건부 타입
-type WithSimilarity<LP, T> = LP extends { semanticQuery: Record<string, unknown> }
-  ? T & { similarity: number }
-  : T;
+type WithSimilarity<LP, T> = "semanticQuery" extends keyof LP ? T & { similarity: number } : T;
 
 export type ListResult<
   LP extends { queryMode?: SonamuQueryMode },
@@ -20,6 +18,7 @@ export function asArray<T>(param: T | T[]): T[] {
   if (Array.isArray(param)) {
     return param;
   } else {
+    // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
     return [param] as T[];
   }
 }
@@ -39,5 +38,5 @@ export interface BaseListParams {
   page?: number;
   keyword?: string;
   queryMode?: "list" | "count" | "both";
-  semanticQuery?: Record<string, unknown>;
+  semanticQuery?: SonamuSemanticParams["semanticQuery"];
 }