sonamu 0.8.13 → 0.8.14

package/src/types/types.ts

@@ -17,6 +17,29 @@ export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K
   Model-Definition
 */
 
+/**
+ * 부모 Entity fixture 생성 시 함께 생성할 companion Entity 설정
+ *
+ * 예: User fixture 생성 시 credentials Account를 함께 생성
+ */
+export type FixtureCompanion = {
+  /** 함께 생성할 Entity 이름 */
+  entity: string;
+
+  /**
+   * 고정 오버라이드 값.
+   * "{{fieldName}}" 형식으로 부모 fixture의 필드 값을 참조할 수 있다.
+   * 예: { "account_id": "{{email}}" } → 부모 User의 email 값 사용
+   */
+  overrides?: Record<string, unknown>;
+
+  /**
+   * 부모 1개당 생성할 companion 개수. 기본값 1.
+   * 예: count: 2 → User 1개당 companion 2개 생성
+   */
+  count?: number;
+};
+
 /**
  * cone: 범용 메타데이터 시스템
  *
@@ -31,6 +54,7 @@ export type Cone = {
   fixtureGenerator?: string; // Faker.js 코드 또는 커스텀 함수
   fixtureDefault?: unknown; // 기본값
   fixtureStrategy?: "sequence"; // string 타입이지만 DB sequence로 관리되는 PK (better-auth 등)
+  fixtureCompanions?: FixtureCompanion[]; // 부모 fixture 생성 시 함께 생성할 companion Entity 목록
 
   // 참조 데이터 관련
   dataSource?: {
@@ -179,6 +203,14 @@ export type JsonProp = CommonProp & {
   type: "json";
   id: string;
 }; // PG: json / TS: any(id) / JSON: any
+export type SearchTextSourceColumn = {
+  name: string;
+  caseInsensitive?: boolean;
+};
+export type SearchTextProp = CommonProp & {
+  type: "searchText";
+  sourceColumns: SearchTextSourceColumn[];
+}; // PG: text (generated) / TS: string / JSON: string
 export type UuidProp = CommonProp & {
   type: "uuid";
 }; // PG: uuid / TS: string / JSON: string
@@ -271,6 +303,7 @@ export type EntityProp =
   | UuidProp
   | UuidArrayProp
   | JsonProp
+  | SearchTextProp
   | VirtualProp
   | VectorProp
   | VectorArrayProp
@@ -333,12 +366,26 @@ export type BuiltInTypeId = (typeof BUILT_IN_TYPE_IDS)[number];
  */
 export type VectorOps = "vector_cosine_ops" | "vector_ip_ops" | "vector_l2_ops";
 
+export const KnownOpclassValues = [
+  "gin_trgm_ops",
+  "gist_trgm_ops",
+  "gin_bigm_ops",
+  "vector_cosine_ops",
+  "vector_ip_ops",
+  "vector_l2_ops",
+  "pgroonga_varchar_full_text_search_ops_v2",
+  "pgroonga_jsonb_full_text_search_ops_v2",
+] as const;
+export type KnownOpclass = (typeof KnownOpclassValues)[number];
+
 type EntityIndexColumn = {
   name: string;
   nullsFirst?: boolean;
   sortOrder?: "ASC" | "DESC";
   /** pgvector 인덱스에서 사용할 거리 연산자 (vector 컬럼에만 적용) */
   vectorOps?: VectorOps;
+  /** generic 인덱스 opclass (vectorOps는 하위호환 목적으로 유지) */
+  opclass?: KnownOpclass | string;
 };
 export type EntityIndex = {
   type: "index" | "unique" | "hnsw" | "ivfflat";
@@ -598,6 +645,9 @@ export function isUuidProp(p: unknown): p is UuidProp | UuidArrayProp {
 export function isJsonProp(p: unknown): p is JsonProp {
   return (p as JsonProp)?.type === "json";
 }
+export function isSearchTextProp(p: unknown): p is SearchTextProp {
+  return (p as SearchTextProp)?.type === "searchText";
+}
 export function isVirtualProp(p: unknown): p is VirtualProp {
   return (p as VirtualProp)?.type === "virtual";
 }
@@ -1041,6 +1091,12 @@ const GeneratedColumnSchema = z.object({
   expression: z.string(),
 });
 
+const FixtureCompanionSchema = z.object({
+  entity: z.string(),
+  overrides: z.record(z.string(), z.unknown()).optional(),
+  count: z.number().int().positive().optional(),
+});
+
 /**
  * Cone 스키마 검증
  *
@@ -1053,6 +1109,7 @@ const ConeSchema = z
     fixtureGenerator: z.string().optional(),
     fixtureDefault: z.unknown().optional(),
     fixtureStrategy: z.literal("sequence").optional(),
+    fixtureCompanions: z.array(FixtureCompanionSchema).optional(),
     dataSource: z
       .object({
         strategy: z.enum(["sample", "ids", "query", "file", "recent", "random"]),
@@ -1186,6 +1243,21 @@ const JsonPropSchema = z
   })
   .strict();
 
+const SearchTextSourceColumnSchema = z
+  .object({
+    name: z.string(),
+    caseInsensitive: z.boolean().optional(),
+  })
+  .strict();
+
+const SearchTextPropSchema = z
+  .object({
+    ...BasePropFields,
+    type: z.literal("searchText"),
+    sourceColumns: z.array(SearchTextSourceColumnSchema).min(1),
+  })
+  .strict();
+
 const VirtualPropSchema = z
   .object({
     ...BasePropFields,
@@ -1297,6 +1369,7 @@ const NormalPropTypes = [
   "uuid",
   "uuid[]",
   "json",
+  "searchText",
   "virtual",
   "vector",
   "vector[]",
@@ -1335,6 +1408,7 @@ export const NormalPropSchema = z
       NumericPropSchema,
       NumericArrayPropSchema,
       JsonPropSchema,
+      SearchTextPropSchema,
       VirtualPropSchema,
       VectorPropSchema,
       VectorArrayPropSchema,
@@ -1391,6 +1465,7 @@ const EntityIndexColumnSchema = z.object({
   nullsFirst: z.boolean().optional(),
   sortOrder: z.enum(["ASC", "DESC"]).optional(),
   vectorOps: z.enum(["vector_cosine_ops", "vector_ip_ops", "vector_l2_ops"]).optional(),
+  opclass: z.union([z.enum(KnownOpclassValues), z.string().min(1)]).optional(),
 });
 
 // EntityIndex 스키마 정의
@@ -1439,7 +1514,75 @@ const EnumDefSchema = z.union([
   }),
 ]);
 
-export const EntityJsonSchema = z
+function unwrapSearchTextJsonSourceType(zodType: z.ZodTypeAny): z.ZodTypeAny {
+  let current = zodType;
+
+  while (current instanceof z.ZodOptional || current instanceof z.ZodNullable) {
+    current = current.unwrap() as z.ZodTypeAny;
+  }
+
+  return current;
+}
+
+export function isSearchTextJsonSourceZodType(zodType: z.ZodTypeAny): boolean {
+  const baseType = unwrapSearchTextJsonSourceType(zodType);
+  if (!(baseType instanceof z.ZodArray)) {
+    return false;
+  }
+
+  const elementType = baseType.def.element;
+  return elementType instanceof z.ZodString;
+}
+
+function validateSearchTextSources(
+  props: readonly z.infer<typeof EntityPropSchema>[],
+  ctx: z.RefinementCtx,
+  propsPath: (string | number)[] = ["props"],
+): void {
+  const propsByName = new Map(
+    props.map((prop) => {
+      return [prop.name, prop];
+    }),
+  );
+
+  props.forEach((prop, propIndex) => {
+    if (prop.type !== "searchText") {
+      return;
+    }
+
+    prop.sourceColumns.forEach((source, sourceIndex) => {
+      const sourceProp = propsByName.get(source.name);
+      const sourcePath = [...propsPath, propIndex, "sourceColumns", sourceIndex, "name"];
+
+      if (!sourceProp) {
+        ctx.addIssue({
+          code: "custom",
+          message: `searchText source column "${source.name}"을(를) 찾을 수 없습니다.`,
+          path: sourcePath,
+        });
+        return;
+      }
+
+      if (sourceProp.type === "string" || sourceProp.type === "string[]") {
+        return;
+      }
+
+      if (sourceProp.type === "json") {
+        // json source의 최종 타입 유효성은 EntityManager.register() 단계에서
+        // 실제 Zod 타입을 해석하여 구조적으로 검증합니다.
+        return;
+      }
+
+      ctx.addIssue({
+        code: "custom",
+        message: `searchText source column "${source.name}"의 타입 "${sourceProp.type}"은(는) 지원되지 않습니다.`,
+        path: sourcePath,
+      });
+    });
+  });
+}
+
+const EntityJsonBaseSchema = z
   .object({
     id: z.string().describe("PascalCase로 된 Entity ID"),
     title: z.string().describe("Entity 이름"),
@@ -1453,18 +1596,31 @@ export const EntityJsonSchema = z
   })
   .strict();
 
+export const EntityJsonSchema = EntityJsonBaseSchema.superRefine((entity, ctx) => {
+  validateSearchTextSources(entity.props, ctx);
+});
+
+const TemplateEntitySchema = EntityJsonBaseSchema.omit({ id: true })
+  .extend({
+    entityId: z.string(),
+  })
+  .partial({
+    table: true,
+    props: true,
+    indexes: true,
+    subsets: true,
+    enums: true,
+  })
+  .superRefine((entity, ctx) => {
+    if (!entity.props) {
+      return;
+    }
+
+    validateSearchTextSources(entity.props, ctx);
+  });
+
 export const TemplateOptions = z.object({
-  entity: EntityJsonSchema.omit({ id: true })
-    .extend({
-      entityId: z.string(),
-    })
-    .partial({
-      table: true,
-      props: true,
-      indexes: true,
-      subsets: true,
-      enums: true,
-    }),
+  entity: TemplateEntitySchema,
   init_types: z.object({
     entityId: z.string(),
   }),

package/src/ui/api.ts

@@ -37,7 +37,15 @@ import {
 } from "../types/types";
 import { nonNullable } from "../utils/utils";
 import { setAiApi } from "./ai-api";
-import { editContent, getCddTree, openSourceFile, readContent } from "./cdd-service";
+import {
+  editContent,
+  editSchema,
+  getCddTree,
+  listSchemas,
+  openSourceFile,
+  readContent,
+  readSchema,
+} from "./cdd-service";
 
 export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
   fastify.register(
@@ -1415,6 +1423,21 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
         return { success: true };
       });
 
+      // CDD Schema API
+      server.get("/api/cdd/schemas", async () => {
+        return listSchemas();
+      });
+
+      server.post<{ Body: { schemaKey: string } }>("/api/cdd/readSchema", async (request) => {
+        const { schemaKey } = request.body;
+        return readSchema(schemaKey);
+      });
+
+      server.post<{ Body: { schemaKey: string } }>("/api/cdd/editSchema", async (request) => {
+        const { schemaKey } = request.body;
+        return editSchema(schemaKey);
+      });
+
       // ui-web 빌드 파일 서빙
       const uiDistPath = path.resolve(import.meta.dirname, "../ui-web");
 

package/src/ui/cdd-service.ts

@@ -1,26 +1,33 @@
 import { spawn } from "child_process";
-import crypto from "crypto";
 import fs from "fs";
 import os from "os";
 import path from "path";
 import { Sonamu } from "../api/sonamu";
-
-export type CddFileType = "contract" | "spec";
-
-export type CddTreeNode = {
-  name: string;
-  /** contract/ 기준 상대 경로 */
-  path: string;
-  type: "file" | "directory";
-  /** file인 경우만 존재 */
-  fileType?: CddFileType;
-  /** directory인 경우만 존재 */
-  children?: CddTreeNode[];
-};
+import type {
+  CddContentEnvelope,
+  CddFileType,
+  CddSchema,
+  CddSchemaDetailEnvelope,
+  CddSchemaReference,
+  CddSchemaSummary,
+  CddTreeNode,
+} from "./cdd-types";
+
+export type {
+  CddContentEnvelope,
+  CddFileType,
+  CddSchema,
+  CddSchemaDetailEnvelope,
+  CddSchemaField,
+  CddSchemaFieldType,
+  CddSchemaReference,
+  CddSchemaSummary,
+  CddTreeNode,
+} from "./cdd-types";
 
 /** contract/ 디렉터리 절대 경로 반환 (apiRootPath 기준) */
 function getContractDir(): string {
-  return path.join(Sonamu.apiRootPath, "contract");
+  return path.join(Sonamu.apiRootPath, "..", "..", "contract");
 }
 
 /** 경로가 contract/ 디렉터리 내부인지 검증 */
@@ -82,15 +89,17 @@ export function getCddTree(): { exists: boolean; tree: CddTreeNode[] } {
   return { exists: true, tree };
 }
 
-/** content 필드를 string으로 변환 (string[] 및 string 모두 지원) */
-function contentToString(content: unknown): string {
-  if (Array.isArray(content)) return content.join("\n");
-  if (typeof content === "string") return content;
-  return "";
+/** schema ID로 schema 파일을 찾아 반환 */
+function resolveSchema(schemaId: string): CddSchema | null {
+  const contractDir = getContractDir();
+  const schemaPath = path.join(contractDir, "schemas", `${schemaId}.schema.json`);
+  if (!fs.existsSync(schemaPath)) return null;
+  const raw = fs.readFileSync(schemaPath, "utf-8");
+  return JSON.parse(raw) as CddSchema;
 }
 
-/** JSON 파일의 전체 내용을 읽어 반환 (content는 string으로 변환) */
-export function readContent(filePath: string): Record<string, unknown> {
+/** JSON 파일의 전체 내용을 읽어 schema와 함께 envelope로 반환 */
+export function readContent(filePath: string): CddContentEnvelope {
   assertInsideContractDir(filePath);
 
   const contractDir = getContractDir();
@@ -101,11 +110,19 @@ export function readContent(filePath: string): Record<string, unknown> {
   }
 
   const raw = fs.readFileSync(absPath, "utf-8");
-  const json = JSON.parse(raw) as Record<string, unknown>;
-  return { ...json, content: contentToString(json.content) };
+  const document = JSON.parse(raw) as Record<string, unknown>;
+  const fileType = detectFileType(path.basename(filePath));
+  const schemaId = typeof document.schema === "string" ? document.schema : null;
+  const schema = schemaId ? resolveSchema(schemaId) : null;
+
+  return {
+    document,
+    schema,
+    fileType: fileType ?? "contract",
+  };
 }
 
-/** JSON 파일의 content 필드를 외부 에디터로 편집 */
+/** JSON 파일을 외부 에디터로 직접 편집 */
 export async function editContent(
   filePath: string,
 ): Promise<{ success: boolean; filePath: string }> {
@@ -119,37 +136,9 @@ export async function editContent(
   }
 
   const editor = resolveEditorCli();
+  await runEditor(editor, absPath);
 
-  const raw = fs.readFileSync(absPath, "utf-8");
-  const json: Record<string, unknown> = JSON.parse(raw);
-
-  const content = contentToString(json.content);
-
-  const tmpFileName = `cdd-edit-${crypto.randomUUID()}.md`;
-  const tmpFilePath = path.join(os.tmpdir(), tmpFileName);
-
-  fs.writeFileSync(tmpFilePath, content, "utf-8");
-
-  try {
-    await runEditor(editor, tmpFilePath);
-
-    const edited = fs.readFileSync(tmpFilePath, "utf-8");
-    json.content = edited.split("\n");
-
-    const today = new Date();
-    const yyyy = today.getFullYear();
-    const mm = String(today.getMonth() + 1).padStart(2, "0");
-    const dd = String(today.getDate()).padStart(2, "0");
-    json.lastModified = `${yyyy}-${mm}-${dd}`;
-
-    fs.writeFileSync(absPath, `${JSON.stringify(json, null, 2)}\n`, "utf-8");
-
-    return { success: true, filePath };
-  } finally {
-    if (fs.existsSync(tmpFilePath)) {
-      fs.unlinkSync(tmpFilePath);
-    }
-  }
+  return { success: true, filePath };
 }
 
 /** 에디터별 앱 번들 내 CLI 경로 + --wait 플래그 매핑 */
@@ -208,6 +197,157 @@ function runEditor(editor: { bin: string; args: string[] }, filePath: string): P
   });
 }
 
+/* ========================================================================
+ * Schema 관리 API
+ * ======================================================================== */
+
+/** contract/schemas/ 디렉터리 내 .schema.json 파일 경로 목록 반환 */
+function scanSchemaFiles(): { absPath: string; relPath: string; fileName: string }[] {
+  const schemasDir = path.join(getContractDir(), "schemas");
+  if (!fs.existsSync(schemasDir)) return [];
+
+  return fs
+    .readdirSync(schemasDir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".schema.json"))
+    .map((e) => ({
+      absPath: path.join(schemasDir, e.name),
+      relPath: `schemas/${e.name}`,
+      fileName: e.name,
+    }));
+}
+
+/** 특정 schemaId를 참조하는 contract/spec 문서들을 재귀 수집 */
+function collectSchemaReferences(
+  schemaId: string,
+  dirPath: string,
+  relativeTo: string,
+): CddSchemaReference[] {
+  if (!fs.existsSync(dirPath)) return [];
+  const refs: CddSchemaReference[] = [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "schemas") continue;
+      refs.push(...collectSchemaReferences(schemaId, fullPath, relativeTo));
+    } else if (entry.isFile()) {
+      const fileType = detectFileType(entry.name);
+      if (!fileType) continue;
+      try {
+        const raw = fs.readFileSync(fullPath, "utf-8");
+        const doc = JSON.parse(raw) as Record<string, unknown>;
+        if (doc.schema === schemaId) {
+          refs.push({
+            path: path.relative(relativeTo, fullPath),
+            fileType,
+            name: entry.name,
+          });
+        }
+      } catch {
+        // JSON 파싱 실패 시 무시
+      }
+    }
+  }
+  return refs;
+}
+
+/** schema 파일명에서 기대되는 id 추출 */
+function expectedSchemaId(fileName: string): string {
+  return fileName.replace(/\.schema\.json$/, "");
+}
+
+/** schemas/ 하위 경로가 contract/schemas/ 내부인지 검증 */
+function assertInsideSchemaDir(schemaKey: string): void {
+  const schemasDir = path.join(getContractDir(), "schemas");
+  const resolved = path.resolve(schemasDir, `${schemaKey}.schema.json`);
+  if (!resolved.startsWith(schemasDir + path.sep) && resolved !== schemasDir) {
+    throw new Error(`유효하지 않은 스키마 키입니다: ${schemaKey}`);
+  }
+}
+
+/** schema 목록 반환 */
+export function listSchemas(): { schemas: CddSchemaSummary[] } {
+  const contractDir = getContractDir();
+  const files = scanSchemaFiles();
+  const schemas: CddSchemaSummary[] = [];
+
+  for (const file of files) {
+    const key = expectedSchemaId(file.fileName);
+    try {
+      const raw = fs.readFileSync(file.absPath, "utf-8");
+      const schema = JSON.parse(raw) as CddSchema;
+      const refs = collectSchemaReferences(schema.id, contractDir, contractDir);
+      schemas.push({
+        key,
+        id: schema.id,
+        path: file.relPath,
+        type: schema.type,
+        fieldCount: schema.fields.length,
+        referenceCount: refs.length,
+        hasIdMismatch: schema.id !== key,
+      });
+    } catch (err) {
+      schemas.push({
+        key,
+        id: key,
+        path: file.relPath,
+        type: "contract",
+        fieldCount: 0,
+        referenceCount: 0,
+        hasIdMismatch: false,
+        parseError: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return { schemas };
+}
+
+/** schema 상세 반환 (파일명 기반 key로 조회) */
+export function readSchema(schemaKey: string): CddSchemaDetailEnvelope {
+  assertInsideSchemaDir(schemaKey);
+
+  const contractDir = getContractDir();
+  const absPath = path.join(contractDir, "schemas", `${schemaKey}.schema.json`);
+
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`스키마를 찾을 수 없습니다: ${schemaKey}`);
+  }
+
+  const raw = fs.readFileSync(absPath, "utf-8");
+  const schema = JSON.parse(raw) as CddSchema;
+  const relPath = path.relative(contractDir, absPath);
+  const references = collectSchemaReferences(schema.id, contractDir, contractDir);
+
+  return {
+    key: schemaKey,
+    path: relPath,
+    schema,
+    references,
+    hasIdMismatch: schema.id !== schemaKey,
+  };
+}
+
+/** schema 파일을 외부 에디터로 편집 (파일명 기반 key로 조회) */
+export async function editSchema(
+  schemaKey: string,
+): Promise<{ success: boolean; schemaKey: string }> {
+  assertInsideSchemaDir(schemaKey);
+
+  const contractDir = getContractDir();
+  const absPath = path.join(contractDir, "schemas", `${schemaKey}.schema.json`);
+
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`스키마를 찾을 수 없습니다: ${schemaKey}`);
+  }
+
+  const editor = resolveEditorCli();
+  await runEditor(editor, absPath);
+
+  return { success: true, schemaKey };
+}
+
 /** 소스 파일을 외부 에디터로 열기 (대기하지 않음) */
 export function openSourceFile(filePath: string): void {
   const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(Sonamu.apiRootPath, filePath);

package/src/ui/cdd-types.ts

@@ -0,0 +1,73 @@
+export type CddFileType = "contract" | "spec";
+
+export type CddSchemaFieldType =
+  | "string"
+  | "string[]"
+  | "Record<string, string>"
+  | "Record<string, object>";
+
+export type CddSchemaField = {
+  name: string;
+  label?: string;
+  type: CddSchemaFieldType;
+  renderer?: string;
+  required: boolean;
+};
+
+export type CddSchema = {
+  id: string;
+  type: "contract" | "spec";
+  fields: CddSchemaField[];
+};
+
+export type CddContentEnvelope = {
+  document: Record<string, unknown>;
+  schema: CddSchema | null;
+  fileType: CddFileType;
+};
+
+export type CddTreeNode = {
+  name: string;
+  path: string;
+  type: "file" | "directory";
+  fileType?: CddFileType;
+  children?: CddTreeNode[];
+};
+
+export type CddSchemaSummary = {
+  key: string;
+  id: string;
+  path: string;
+  type: "contract" | "spec";
+  fieldCount: number;
+  referenceCount: number;
+  hasIdMismatch: boolean;
+  parseError?: string;
+};
+
+export type CddSchemaReference = {
+  path: string;
+  fileType: CddFileType;
+  name: string;
+};
+
+export type CddSchemaDetailEnvelope = {
+  key: string;
+  path: string;
+  schema: CddSchema;
+  references: CddSchemaReference[];
+  hasIdMismatch: boolean;
+};
+
+/** Acceptance Criterion 테스트 참조 */
+export type AcceptanceCriterionTestRef = {
+  target: string;
+  pattern: string;
+};
+
+/** 구조화된 Acceptance Criterion */
+export type AcceptanceCriterion = {
+  id: string;
+  condition: string;
+  testRef: AcceptanceCriterionTestRef;
+};