@simplysm/sd-claude 14.0.65 → 14.0.68

package/claude/references/sd-simplysm14/apis/orm-common/db-context.md

@@ -0,0 +1,77 @@
+# @simplysm/orm-common — DbContext
+
+DB 1개에 대응하는 추상 클래스. 서브클래싱하여 테이블/뷰/프로시저를 인스턴스 프로퍼티로 등록하고, connect/transaction/DDL/initialize 진입점을 제공한다. 실제 SQL 실행은 생성자에 주입된 `DbContextExecutor` 가 담당.
+
+## 생성·등록
+
+```ts
+class MainDb extends DbContext {
+  user = this.queryable(User);            // → () => Queryable<User.$inferSelect, typeof User>
+  vUser = this.queryable(UserSummary);    // View 도 동일
+  getUserById = this.executable(GetUserById); // → () => Executable<TParams, TReturns>
+
+  migrations = [
+    { name: "001-init", up: async (db) => { await db.createTable(User); } },
+  ];
+}
+
+const db = new MainDb(executor, { database: "mydb", schema: "dbo" });
+```
+
+- `protected queryable(builder)`: `TableBuilder | ViewBuilder` 를 받아 호출시마다 새 alias 가 할당된 `Queryable` 을 만드는 팩토리 함수를 반환. 반환 함수에는 `SD_BUILDER` 심볼로 원본 builder 가 부착됨 (initialize 가 회수).
+- `protected executable(builder)`: `ProcedureBuilder` → `Executable` 팩토리. 동일하게 `SD_BUILDER` 부착.
+- `_migration` 프로퍼티: 시스템 마이그레이션 테이블(`_migration(code PK varchar(255))`) 이 자동 등록됨.
+
+## 연결 / 트랜잭션
+
+```ts
+await db.connect(async () => { ... });                        // connect + tx (auto commit/rollback)
+await db.connect(async () => { ... }, "REPEATABLE_READ");     // isolation level
+await db.connectWithoutTransaction(async () => { ... });      // connect only
+await db.transaction(async () => { ... });                    // 이미 connect 인 상태에서 tx 만
+```
+
+- `status: "ready" | "connect" | "transact"`. 잘못된 진입(중복 connect, 중복 tx)은 throw.
+- `connect()` 진입시 1회 `validateRelationsImpl` 호출 (relation 무결성 검사 — 잘못된 FK 정의는 여기서 throw).
+- 본문 throw 시 자동 rollback → `_executor.close()` 후 status `ready` 복귀. rollback 중 `DbTransactionError(NO_ACTIVE_TRANSACTION)` 는 무시.
+- `transaction()` 단독은 `status==="connect"` 일 때만. 이미 transact 면 throw.
+- `executeDefs(defs, resultMetas?)`: `_executor.executeDefs` 위임. `status==="transact"` 중 DDL 포함 시 throw.
+
+## DDL 실행
+
+`createTable`, `dropTable`, `renameTable`, `createView`, `dropView`, `createProc`, `dropProc`, `addColumn`, `dropColumn`, `modifyColumn`, `renameColumn`, `addPrimaryKey`, `dropPrimaryKey`, `addForeignKey`, `addIndex`, `dropForeignKey`, `dropIndex`, `clearSchema({database, schema?})`, `schemaExists(database, schema?): Promise<boolean>`, `truncate(table)`, `switchFk(table, enabled)`.
+
+각각 `executeDefs([...QueryDef])` 로 1건씩 실행. 트랜잭션 내에서는 `switchFk` 외 모두 차단(`executeDefs` 에서 검사).
+
+대응 `getXxxQueryDef(...)` 형태의 *생성기* 메서드도 동일 시그니처로 제공 (실행 없이 `QueryDef` 만 반환). `initialize()` 가 배치 DDL 을 모을 때 사용.
+
+`getCreateObjectQueryDef(builder)` — Table/View/Procedure 중 무엇이든 받아 알맞은 create DDL 반환.
+
+## initialize
+
+```ts
+await db.initialize();                      // 미적용 migration 만 실행
+await db.initialize({ dbs: ["a", "b"] });   // 다중 DB
+await db.initialize({ force: true });       // 스키마 clear + 전체 재생성 + 모든 migration 을 "적용됨" 등록
+```
+
+반환값: 실행된 migration 이 있으면 `true`, 아니면 `false`.
+
+동작:
+- `force=true`: `clearSchema` → DbContext 의 모든 등록 객체(`queryable`/`executable` 프로퍼티에서 `SD_BUILDER` 로 회수) create → `_Migration` 에 모든 migration name 등록 → `false`.
+- `force=false`:
+  - `_Migration` 테이블 없음 = 신규 DB → 전체 create + 모든 migration 등록 → `false`.
+  - 있음 → 미적용 migration 만 순차 실행 → 실행분 있으면 `true`.
+
+서브클래스가 `migrations: Migration[]` 를 오버라이드해 `{ name, up(db) }` 목록 제공.
+
+## 헬퍼
+
+- `database`/`schema` getter — 생성자 옵션 노출.
+- `getNextAlias(): string` — `T1`, `T2`, ... alias 카운터. `connect`/`connectWithoutTransaction` 진입시 reset.
+- `resetAliasCounter()`.
+- `getQueryDefObjectName(tableOrView)` — Table/View 메타에서 `{database, schema, name}` 산출 (없으면 DbContext 옵션 fallback).
+
+## 인터페이스
+
+외부에서 DbContext 를 의존성으로 다룰 때는 `DbContextBase`(코어) + `DbContextDdlMethods`(DDL) 인터페이스 사용 (`./types/db-context-def`). `DbContext` 가 둘 다 구현.

package/claude/references/sd-simplysm14/apis/orm-common/executable.md

@@ -0,0 +1,20 @@
+# @simplysm/orm-common — Executable
+
+저장 프로시저 호출 래퍼. `DbContext.executable(builder)` 가 만든 팩토리 호출(`db.getUserById()`)마다 새 인스턴스 반환.
+
+```ts
+class Executable<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord> {
+  getExecProcQueryDef(params?: InferColumnExprs<TParams>): ExecProcQueryDef
+  async execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>
+}
+```
+
+- `params` 의 각 값은 `ExprInput<T>` (= `ExprUnit<T> | T`). 리터럴이면 `expr.val(meta.type, value)` 로 자동 래핑.
+- 프로시저에 `params` 가 정의되지 않은 builder 에 인자를 넘기면 throw.
+- 반환은 결과 셋의 배열 (프로시저가 여러 SELECT 를 반환할 수 있음).
+
+```ts
+const [users] = await db.getUserById().execute({ userId: 1 });
+```
+
+`executable(db, builder)` — 팩토리. `DbContext.executable` 의 내부 구현이며, `SD_BUILDER` 심볼로 builder 를 부착해야 `initialize()` 가 회수할 수 있다 (직접 쓰지 말고 `DbContext.executable` 사용 권장).

package/claude/references/sd-simplysm14/apis/orm-common/expr.md

@@ -0,0 +1,92 @@
+# @simplysm/orm-common — expr
+
+Dialect 독립 SQL 표현식 빌더. SQL 문자열 대신 JSON AST(`Expr`/`WhereExpr`) 를 만들어 `Queryable` 메타에 누적되고, QueryBuilder 가 DBMS 별로 렌더.
+
+## 래퍼
+
+- `ExprUnit<T extends ColumnPrimitive>` — `{ dataType: ColumnPrimitiveStr, expr: Expr }`. `.n` 게터로 `NonNullable<T>` 로 cast.
+- `WhereExprUnit` — boolean 컨텍스트 (`where`/`having`/논리 연산자) 전용.
+- `ExprInput<T> = ExprUnit<T> | T` — 리터럴도 받는 입력 타입.
+- `expr.toExpr(value)` / `toExpr(value)` 헬퍼 — `ExprUnit` 이면 풀고, 아니면 `{type:"value", value}` 로 감쌈.
+
+## 카테고리별 API
+
+### 값 / 컬럼 / Raw
+- `expr.val(dataType, value)` — 리터럴 → `ExprUnit`. `dataType ∈ "string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes"`.
+- `expr.col(dataType, ...path)` — 컬럼 참조(주로 내부).
+- `expr.raw(dataType)\`SQL ${interp}\`` — 태그드 템플릿. 보간값은 파라미터화. dialect 의존 함수 사용 시 escape hatch.
+
+### 비교 / NULL (→ `WhereExprUnit`)
+- `eq`, `gt`, `lt`, `gte`, `lte`(source, target)
+- `between(source, from?, to?)`
+- `null(source)` — IS NULL
+- `like(source, pattern)`, `regexp(source, pattern)`
+- `in(source, values[])`, `inQuery(source, queryable)` — `queryable` 은 1-컬럼 select 여야 함. `exists(queryable)`.
+
+### 논리
+- `not(WhereExprUnit)`, `and(WhereExprUnit[])`, `or(WhereExprUnit[])` — 빈 배열은 throw.
+
+### 문자열 (→ `ExprUnit<string ...>`)
+- `concat(...args)`, `left(s, n)`, `right(s, n)`, `trim(s)`
+- `padStart(s, length, fillString)`, `replace(s, from, to)`
+- `upper(s)`, `lower(s)`
+- `length(s)` → number, `byteLength(s)` → number
+- `substring(s, start, length?)`, `indexOf(s, search)` → number
+
+### 숫자
+- `abs`, `round(s, digits)`, `ceil`, `floor`.
+
+### 날짜 (`DateUnit = "year"|"month"|"day"|"hour"|"minute"|"second"`)
+- `year/month/day/hour/minute/second(source)`
+- `isoWeek(d)`, `isoWeekStartDate(d)`, `isoYearMonth(d)`
+- `dateDiff(unit, from, to)` → number
+- `dateAdd(unit, source, value)`
+- `formatDate(source, format: string)` — format 문자열은 dialect 변환.
+
+### NULL 처리 / 조건
+- `coalesce(...args)` — 첫 non-null. 마지막 인자가 NonNullable 이면 반환 타입도 NonNullable.
+- `nullIf(source, value)`
+- `is(WhereExprUnit)` → `ExprUnit<boolean>` (boolean 변환)
+- `if(condition, then, else_)` → `ExprUnit<T>` — 결과 dataType 은 ExprUnit/non-null 리터럴에서 추론.
+- `switch<T>()` → `SwitchExprBuilder<T>` — `.case(cond, then).case(...).default(value)` 체이닝.
+
+### 집계 (GROUP BY 컨텍스트)
+- `count(arg?, distinct?)` → number
+- `sum(arg)`, `avg(arg)` → `number | undefined`
+- `max(arg)`, `min(arg)` → `T | undefined`
+- `greatest(...args)`, `least(...args)` — 행 내 최대/최소.
+
+### 기타 스칼라
+- `rowNum()` → number — MSSQL `ROW_NUMBER() OVER(...)` 가 아니라 dialect 별 row 식별 함수 (간단 시퀀스).
+- `random()` → number, 0~1.
+- `cast(source, targetType: DataType)` — 결과 dataType 은 `dataTypeStrToColumnPrimitiveStr` 매핑.
+- `subquery(dataType, queryable)` — 1-컬럼 select 의 스칼라 서브쿼리.
+
+### 윈도우 함수 (`WinSpecInput = { partitionBy?: ExprInput[], orderBy?: [ExprInput, "ASC"|"DESC"?][] }`)
+- 순위: `rowNumber(spec)`, `rank(spec)`, `denseRank(spec)`, `ntile(n, spec)`
+- 시퀀스 비교: `lag(column, spec, { offset?, default? })`, `lead(column, spec, { offset?, default? })`
+- 첫/끝: `firstValue(column, spec)`, `lastValue(column, spec)`
+- 집계 윈도우: `sumOver(column, spec)`, `avgOver(column, spec)`, `countOver(spec, column?)`, `minOver(column, spec)`, `maxOver(column, spec)`
+
+## 예시
+
+```ts
+db.user()
+  .where(u => [
+    expr.eq(u.status, "active"),
+    expr.between(u.age, 18, 65),
+    expr.or([expr.like(u.name, "%kim%"), expr.like(u.email, "%kim%")]),
+  ])
+  .select(u => ({
+    name: expr.concat(u.firstName, " ", u.lastName),
+    rank: expr.rowNumber({ partitionBy: [u.deptId], orderBy: [[u.score, "DESC"]] }),
+    label: expr.switch<string>()
+      .case(expr.gte(u.score, 90), "A")
+      .case(expr.gte(u.score, 80), "B")
+      .default("C"),
+  }))
+```
+
+## Expr AST 타입
+
+세부 노드 타입은 `./types/expr` 의 union (`ExprColumn`/`ExprValue`/`ExprRaw`/...`ExprWindow`/`ExprSubquery`). 일반 사용자는 직접 다룰 필요 없음 — ExprRenderer 구현이나 디버깅·검증 시만.

package/claude/references/sd-simplysm14/apis/orm-common/queryable.md

@@ -0,0 +1,98 @@
+# @simplysm/orm-common — Queryable
+
+체이닝 SELECT/INSERT/UPDATE/DELETE/UPSERT 빌더. `DbContext.queryable(builder)` 가 만든 팩토리 호출(`db.user()`)마다 새 alias 가 할당된 새 `Queryable` 이 반환된다. 모든 체이닝 메서드는 새 인스턴스를 반환(immutable).
+
+```ts
+class Queryable<TData extends DataRecord, TFrom extends TableBuilder | never>
+```
+- `TData` — 결과 row 타입 (관계 include 포함).
+- `TFrom` — CUD(INSERT/UPDATE/DELETE/UPSERT) 시 필요한 원본 TableBuilder. `select`/`join`/`union`/`wrap`/`groupBy`/`recursive`/`distinct` 한 후엔 `never` 가 되어 CUD 불가.
+
+## 옵션 체이닝
+
+- `.select(fn: cols => mapped)` — SELECT 컬럼/표현식 재구성. 원시 리터럴은 자동 `ExprUnit` 으로 래핑. → `Queryable<UnwrapQueryableRecord<R>, never>`.
+- `.distinct()` — DISTINCT.
+- `.lock()` — FOR UPDATE.
+- `.top(n)` — TOP N (ORDER BY 무관).
+- `.limit(skip, take)` — `orderBy` 필수, 없으면 throw.
+- `.orderBy(fn | "key.path", "ASC" | "DESC"?)` — 누적. 문자열 overload 는 `obj.getChainValue` 로 컬럼 검색 (동적 정렬용).
+- `.where(predicate: cols => WhereExprUnit[])` — 누적, AND 결합.
+- `.search(cols => ExprUnit<string|undefined>[], text)` — `parseSearchQuery` 의 OR/AND(`+`)/NOT(`-`)/`"…"`/`*` 구문을 컬럼들에 LIKE 로 적용 (소문자 비교).
+- `.groupBy(cols => ExprUnit[])` — `TFrom` → never.
+- `.having(predicate)` — GROUP BY 후 필터, 누적 AND.
+
+## JOIN / INCLUDE
+
+```ts
+.join(as, (qr, cols) => Queryable)        // 1:N — { ..., [as]?: R[] }
+.joinSingle(as, (qr, cols) => Queryable)  // N:1 또는 1:1 — { ..., [as]?: R }
+.include(item => item.user.company)       // PathProxy 기반 자동 JOIN (TableBuilder 기반만)
+```
+
+- 콜백의 `qr: JoinQueryable` 은 `.from(table)` / `.select(customCols)` / `.union(...queries)` 제공.
+- `.include` 는 `TableBuilder.relations` 정의를 따라 FK/RelationKey(=joinSingle) 또는 FKT/RelationKeyTarget(=join, `single:true` 면 joinSingle) 으로 풀림. 동일 경로 중복 호출은 무시. 다단계(`a.b.c`)는 부모 객체 안으로 nested 됨.
+- PathProxy 는 ColumnPrimitive 필드 접근을 컴파일 에러로 막아 관계 키만 허용.
+
+## Subquery / UNION / Recursive CTE
+
+- `.wrap()` — 현재 Queryable 을 서브쿼리로 감싼 새 Queryable. `distinct()`/`groupBy()` 후 `count()` 직전에 필요.
+- `Queryable.union(q1, q2, ...)` (static) — UNION (중복 제거). 2개 미만 throw. 첫 query 의 컬럼 구조 사용.
+- `.recursive(fn: (cte: RecursiveQueryable<TData>) => Queryable<TData>)` — WITH RECURSIVE 생성. 콜백 안에서 `cte.from(table)` 한 결과에 `self` 프로퍼티(현재 CTE 자기 참조)가 부여됨. `.union(...)` 도 가능.
+
+## 실행 (SELECT)
+
+- `await qr.execute(): Promise<TData[]>`
+- `await qr.single(): Promise<TData | undefined>` — 2개 이상이면 throw.
+- `await qr.first(): Promise<TData | undefined>` — 내부 `top(1)`.
+- `await qr.count(fn?): Promise<number>` — `distinct`/`groupBy` 후 직접 호출시 throw → `wrap()` 필요.
+- `await qr.exists(): Promise<boolean>` — `top(1)` 으로 행 존재 확인.
+
+## CUD (TFrom = TableBuilder 필요)
+
+```ts
+await q.insert(records);
+const [{ id }] = await q.insert([{...}], ["id"]);             // OUTPUT
+
+await q.insertIfNotExists(record);                            // WHERE 조건과 결합
+await q.insertIfNotExists(record, ["id"]);                    // 단건 반환
+
+await q2.insertInto(TargetTable);                             // INSERT INTO ... SELECT
+await q2.insertInto(TargetTable, ["id"]);
+
+await q.update(cols => ({ name: expr.val("string", "x") }));
+await q.update(cols => ({...}), ["id"]);
+
+await q.delete();
+await q.delete(["id", "name"]);
+
+await q.upsert(updateFn);                                     // UPDATE 또는 INSERT (existsSelectQuery=현재 where)
+await q.upsert(updateFn, ["id"]);
+await q.upsert(updateFn, insertFn);
+await q.upsert(updateFn, insertFn, ["id"]);
+```
+
+- `insert(records)` 는 records 0건이면 noop. MSSQL 1000행 제한을 위해 청크 분할(`CHUNK_SIZE=1000`) — 각 청크는 별도 `executeDefs` 호출, OUTPUT 도 누적.
+- `insert` 의 records 에 autoIncrement 컬럼 값이 명시되면 자동으로 `overrideIdentity` 켜짐.
+- CUD 는 `TFrom` 이 `TableBuilder` 일 때만 — 아니면 `_getCudOutputDef` 에서 throw. ViewBuilder/Queryable 합성/Union 후엔 사용 불가.
+- `await q.switchFk(enabled)` — TableBuilder/ViewBuilder 기반에서 FK on/off (트랜잭션 내 사용 가능).
+
+## QueryDef 생성기 (실행 없이 def 만)
+
+`getSelectQueryDef()`, `getInsertQueryDef(records, output?)`, `getInsertIfNotExistsQueryDef(record, output?)`, `getInsertIntoQueryDef(target, output?)`, `getUpdateQueryDef(recordFwd, output?)`, `getDeleteQueryDef(output?)`, `getUpsertQueryDef(updateFn, insertFn, output?)`, `getResultMeta(outputColumns?)`.
+
+## 타입
+
+`QueryableRecord<TData>` — `TData` 의 원시 필드를 `ExprUnit<T>`, 중첩 객체/배열은 재귀로 감싼 형태. `where`/`select` 콜백 인자 타입.
+
+`QueryableWriteRecord<TData>` — `ExprInput<T>` (= `ExprUnit<T> | T`) 으로, `update`/`upsert` 의 record 값 입력 타입.
+
+`UnwrapQueryableRecord<R>` — `.select` 결과를 다시 DataRecord 로 역추론.
+
+`PathProxy<T>` — `.include` 인자 타입. 비-ColumnPrimitive 필드만 노출.
+
+## 보조 함수
+
+```ts
+queryable(db, tableOrView, as?)   // Queryable factory 생성. DbContext.queryable 의 내부 구현
+getMatchedPrimaryKeys(fkCols, targetTable)  // include 가 FK 컬럼과 대상 PK 매칭
+```

package/claude/references/sd-simplysm14/apis/orm-common/schema-builders.md

@@ -0,0 +1,128 @@
+# @simplysm/orm-common — Schema Builders
+
+테이블/뷰/프로시저를 fluent 로 정의하는 immutable 빌더. `DbContext` 의 `queryable()`/`executable()` 에 전달하여 등록한다. 모든 메서드는 `new Xxx({...this.meta, ...})` 형태로 새 인스턴스 반환.
+
+## Table / TableBuilder
+
+```ts
+import { Table } from "@simplysm/orm-common";
+
+const User = Table("User")            // Table<TName>(name)
+  .database("mydb")
+  .schema("dbo")                      // MSSQL/PostgreSQL only
+  .description("사용자")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    name: c.varchar(100),
+    email: c.varchar(200).nullable(),
+    status: c.varchar(20).default("active"),
+  }))
+  .primaryKey("id")                   // 복합: .primaryKey("a","b")
+  .indexes((i) => [i.index("email").unique()])
+  .relations((r) => ({
+    posts: r.foreignKeyTarget(() => Post, "author"),
+  }));
+```
+
+타입 추론 프로퍼티 (`readonly $xxx!` — 런타임 값 X, 타입 추출용):
+- `$inferSelect` — 컬럼 + (deep) 관계 (관계는 optional)
+- `$inferColumns` — 컬럼만
+- `$inferInsert` — `autoIncrement`/`nullable`/`default` 컬럼은 optional
+- `$inferUpdate` — 모든 필드 optional
+- `$columns`, `$relations` — 정의 자체
+
+`meta`: `{ name; description?; database?; schema?; columns?; primaryKey?; relations?; indexes? }`.
+
+## View / ViewBuilder
+
+```ts
+import { View } from "@simplysm/orm-common";
+
+const ActiveUsers = View("ActiveUsers")
+  .database("mydb")
+  .query((db: MainDb) =>
+    db.user().where(u => [expr.eq(u.status, "active")])
+       .select(u => ({ id: u.id, name: u.name })))
+  .relations(r => ({ posts: r.relationKeyTarget(() => Post, "author") }));
+```
+
+- `.query<TData>(viewFn: (db) => Queryable<TData>)` 의 viewFn 은 `queryable()` 호출시(=`createView` DDL 만들 때, `db.queryable(ViewBuilder)` 팩토리에서) 실행된다.
+- View 의 관계는 `relationKey`/`relationKeyTarget` 만 사용 (DB FK 미생성).
+- `$inferSelect: TData`.
+
+## Procedure / ProcedureBuilder
+
+```ts
+import { Procedure } from "@simplysm/orm-common";
+
+const GetUserById = Procedure("GetUserById")
+  .database("mydb")
+  .params(c => ({ userId: c.bigint() }))
+  .returns(c => ({ id: c.bigint(), name: c.varchar(100) }))
+  .body("SELECT id, name FROM User WHERE id = userId");
+// MSSQL 본문은 @userId 사용. PostgreSQL 은 RETURN QUERY 필요.
+```
+
+`$params`, `$returns` 타입 추론. `meta`: `{ name; description?; database?; schema?; params?; returns?; query? }`.
+
+## Column Factory (`columns((c) => ...)` 안에서 사용)
+
+`createColumnFactory()` 반환 객체의 메서드 — 모두 `ColumnBuilder<TValue, TMeta>` 반환:
+
+| 메서드 | TS 타입 | SQL 매핑 |
+|---|---|---|
+| `int()` | number | INT |
+| `bigint()` | number | BIGINT |
+| `float()` | number | FLOAT/REAL |
+| `double()` | number | DOUBLE |
+| `decimal(precision, scale?)` | number | DECIMAL(p,s) |
+| `varchar(length)` | string | VARCHAR(n) |
+| `char(length)` | string | CHAR(n) |
+| `text()` | string | TEXT/LONGTEXT |
+| `binary()` | Bytes | LONGBLOB/VARBINARY(MAX)/BYTEA |
+| `boolean()` | boolean | TINYINT(1)/BIT/BOOLEAN |
+| `datetime()` | DateTime | DATETIME |
+| `date()` | DateOnly | DATE |
+| `time()` | Time | TIME |
+| `uuid()` | Uuid | BINARY(16)/UNIQUEIDENTIFIER/UUID |
+
+`ColumnBuilder` 체이닝:
+- `.autoIncrement()` — INSERT 시 자동 증가, `$inferInsert` 에서 optional.
+- `.nullable()` — TS 타입에 `| undefined` 추가.
+- `.default(value)` — 기본값. `$inferInsert` 에서 optional.
+- `.description(text)` — DDL Comment.
+
+타입 유틸: `ColumnBuilderRecord`, `InferColumns<T>`, `InferColumnExprs<T>` (Executable params), `RequiredInsertKeys<T>`, `OptionalInsertKeys<T>`, `InferInsertColumns<T>`, `InferUpdateColumns<T>`, `DataToColumnBuilderRecord<TData>`.
+
+## Index Factory (`indexes((i) => ...)` 안에서)
+
+```ts
+i.index("email").unique()
+i.index("name", "createdAt").orderBy("ASC", "DESC")
+i.index("createdAt").name("IX_Foo")
+i.index("a").description("...")
+```
+
+`IndexBuilder<TKeys>` 의 `meta`: `{ columns; name?; unique?; orderBy?; description? }`.
+
+## Relation Factory (`relations((r) => ...)` 안에서)
+
+Table 은 4개 모두, View 는 `relationKey`/`relationKeyTarget` 만 노출.
+
+```ts
+// N:1
+r.foreignKey(["authorId"], () => User, { description?: string })       // DB FK 생성
+r.relationKey(["companyId"], () => Company, { description?: string })   // 논리 관계 (FK X) — View 가능
+
+// 1:N (기본) 또는 1:1 (single: true)
+r.foreignKeyTarget(() => Post, "author")
+r.foreignKeyTarget(() => Profile, "user", { single: true })
+r.relationKeyTarget(() => UserSummary, "company", { single?, description? })
+```
+
+- `foreignKey` 의 두 번째 인자는 *대상 테이블 factory* `() => TableBuilder` (순환 참조 회피).
+- `foreignKeyTarget` 의 두 번째 인자 `relationName` 은 대상 테이블에 정의된 자기방향 FK 의 키 이름.
+- 메서드 체이닝(`.description()`/`.single()`)은 TS 순환 참조 (TS7022) 회피용으로 *제거됨* — 옵션은 마지막 `opts` 객체로만 전달.
+- 빌더 클래스: `ForeignKeyBuilder`, `ForeignKeyTargetBuilder`, `RelationKeyBuilder`, `RelationKeyTargetBuilder`.
+
+타입 유틸: `RelationBuilderRecord`, `ExtractRelationTarget<T>`, `ExtractRelationTargetResult<T>`, `InferDeepRelations<TRelations>` — 모두 관계를 optional 로 추론, 같은 테이블 재방문 시 더 깊이 들어가지 않음 (순환 끊김).

package/claude/references/sd-simplysm14/apis/orm-node/README.md

@@ -0,0 +1,59 @@
+# @simplysm/orm-node
+
+Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실제 DB(MSSQL/MySQL/PostgreSQL)에 붙여 실행하기 위한 어댑터. 드라이버 모듈(`tedious`/`mysql2`/`pg`/`pg-copy-streams`)은 dialect 선택 시점에 지연 import.
+
+## 사용 트리거 인덱스
+
+- **`createOrm` / `Orm` / `OrmOptions`** — `DbContext` 서브클래스 + `DbConnConfig` 로 ORM 인스턴스를 만들고, 트랜잭션 유/무 콜백을 실행한다. 일반 ORM 사용의 진입점.
+- **`createDbConn`** — `DbConnConfig` 만으로 저수준 `DbConn` 인스턴스를 직접 만든다. `DbContext` 없이 raw SQL/bulk insert 가 필요할 때.
+- **`NodeDbContextExecutor`** — `DbContext` 의 executor 직접 주입이 필요할 때. 일반적으로는 `createOrm` 이 내부적으로 사용.
+- **`MysqlDbConn` / `MssqlDbConn` / `PostgresqlDbConn`** — dialect별 `DbConn` 구현. 직접 `new` 하지 말고 `createDbConn` 사용. 타입 참조용으로만 import.
+- **`DbConn` / `DbConnConfig` (+ `MysqlDbConnConfig` / `MssqlDbConnConfig` / `PostgresqlDbConnConfig`)** — 설정/연결 타입. 함수 시그니처·DI 토큰 등에서 참조.
+- **`getDialectFromConfig`** — `DbConnConfig` → `Dialect` 변환(`mssql-azure` → `mssql`). 쿼리 빌더 선택 시.
+- **`DB_CONN_CONNECT_TIMEOUT` (10s) / `DB_CONN_DEFAULT_TIMEOUT` (10m) / `DB_CONN_ERRORS`** — 타임아웃·에러 메시지 상수.
+
+## createOrm
+
+```ts
+function createOrm<T extends DbContext>(
+  DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T,
+  config: DbConnConfig,
+  options?: OrmOptions, // { database?: string; schema?: string } — config 보다 우선
+): Orm<T>;
+
+interface Orm<T> {
+  connect<R>(cb: (db: T) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>; // 트랜잭션
+  connectWithoutTransaction<R>(cb: (db: T) => Promise<R>): Promise<R>;                 // 트랜잭션 없음
+}
+```
+
+`database` 가 `options` 와 `config` 양쪽 모두 없으면 throw. 매 `connect*` 호출마다 새 `DbContext` 인스턴스를 만들어 콜백 종료 시 연결을 닫는다.
+
+```ts
+const orm = createOrm(MyDb, { dialect: "mysql", host, port, username, password, database });
+await orm.connect(async (db) => db.user().execute());
+```
+
+## createDbConn
+
+```ts
+function createDbConn(config: DbConnConfig): Promise<DbConn>;
+```
+
+dialect 에 따라 드라이버 모듈을 lazy import 한 뒤 해당 `DbConn` 구현 반환. **반환된 객체는 미연결 상태** — 호출자가 `conn.connect()` → 사용 → `conn.close()` 까지 책임. `DbConn` 은 `EventEmitter<{ close: void }>` 이며 다음 메서드 제공: `connect`, `close`, `beginTransaction(isolationLevel?)`, `commitTransaction`, `rollbackTransaction`, `execute(queries: string[])`, `executeParametrized(query, params?)`, `bulkInsert(tableName, columnMetas, records)`. `bulkInsert` 는 dialect별 네이티브 경로 사용(MSSQL: tedious BulkLoad / MySQL: `LOAD DATA LOCAL INFILE` 임시파일 / PostgreSQL: `COPY FROM STDIN`).
+
+## DbConnConfig
+
+dialect 분기 union. 공통 필드: `host`, `port?`, `username`, `password`, `database?`, `defaultIsolationLevel?`.
+
+- `MysqlDbConnConfig` — `dialect: "mysql"`.
+- `MssqlDbConnConfig` — `dialect: "mssql" | "mssql-azure"`, `schema?`. `mssql-azure` 는 `encrypt: true` 로 연결.
+- `PostgresqlDbConnConfig` — `dialect: "postgresql"`, `schema?`.
+
+## NodeDbContextExecutor
+
+```ts
+new NodeDbContextExecutor(config: DbConnConfig)
+```
+
+`DbContextExecutor` 구현. `connect` 시 내부에서 `createDbConn` + `conn.connect()` 수행. `executeDefs(defs, resultMetas?)` 는 `@simplysm/orm-common` 의 `createQueryBuilder` + `parseQueryResult` 를 사용해 `QueryDef[]` → SQL → 파싱 결과. `resultMetas` 가 전부 `null` 인 경우 단일 결합 SQL 1회로 묶어 실행. 미연결 상태에서 메서드 호출 시 `DB_CONN_ERRORS.NOT_CONNECTED` SdError throw.

package/claude/references/sd-simplysm14/apis/sd-claude/README.md

@@ -0,0 +1,9 @@
+# @simplysm/sd-claude
+
+Claude Code 셋업 자산(`.claude/` 의 sd-* 스킬·룰·훅) 배포 및 `sd-claude` CLI 제공 패키지.
+
+코드 API 없음 (npm 배포용). 외부에서 import 할 수 있는 라이브러리 심볼은 노출하지 않는다.
+
+- `bin`: `sd-claude` — `auth save` / `auth switch` (저장된 Claude 계정 전환).
+- `postinstall`: 설치 시 사용자 `~/.claude/` 로 자산 동기화.
+- `prepack`: 배포 전 `.claude/` → `packages/sd-claude/claude/` 증분 복사.

package/claude/references/sd-simplysm14/apis/sd-cli/README.md

@@ -0,0 +1,50 @@
+# @simplysm/sd-cli
+
+워크스페이스 빌드/배포 오케스트레이터. 라이브러리 export 는 `sd.config.ts` 작성용 타입과 Vitest Angular 플러그인, 그리고 외부 도구가 재사용할 `SdTsCompiler` 다. CLI 서브커맨드는 이 문서 대상 아님 (`pnpm sd-cli --help`).
+
+## 사용 트리거 인덱스
+- **`SdConfigFn` / `SdConfig` / `SdConfigParams`** — `sd.config.ts` 의 default export 타이핑. 자세히: [sd-config.md](./sd-config.md)
+- **패키지별 설정 타입 (`SdBuildPackageConfig`, `SdClientPackageConfig`, `SdServerPackageConfig`, `SdScriptsPackageConfig`)** — `SdConfig.packages` 값 타이핑. 자세히: [sd-config.md](./sd-config.md)
+- **`SdPublishConfig` / `SdPostPublishScriptConfig`** — `publish`·`postPublish` 항목 타이핑. 자세히: [sd-config.md](./sd-config.md)
+- **`SdCapacitorConfig` / `SdElectronConfig` / `SdPwaConfig` / `SdBrowserSupportConfig`** — 클라이언트 패키지의 모바일/데스크톱/PWA/브라우저 지원 옵션. 자세히: [sd-config.md](./sd-config.md)
+- **`sdAngularPlugin(options)`** — Vitest 의 `vite.config` (또는 `vitest.config`) 에서 Angular 패키지 AOT 컴파일이 필요할 때 plugin 으로 추가.
+- **`SdTsCompiler` (+ `ISdTsCompilerOptions`, `ISdTsCompilerResult`)** — 사용자 코드에서 직접 호출할 일은 거의 없음. Angular/Non-Angular TS 패키지를 증분 컴파일·진단·lint·SCSS 통합 처리하는 엔진. `sd-cli` 내부 엔진(`engines/`, `orchestrators/`) 및 `sdAngularPlugin` 에서 사용. 외부에서 동일한 엔진을 재사용해야 할 때만 직접 import.
+
+## sdAngularPlugin
+
+```typescript
+import { sdAngularPlugin, type SdAngularPluginOptions } from "@simplysm/sd-cli";
+
+// vitest.config.ts
+plugins: [sdAngularPlugin({ pkg: "angular" })]
+```
+
+`pkg` 는 `sd.config.ts.packages` 키 (= `packages/<pkg>/` 디렉토리명). 패키지의 `.ts` 를 AOT 컴파일해 `transform` 훅에서 JS 로 치환한다. `tsconfig.json` 의 `angularCompilerOptions` 유무로 Angular 모드를 자동 감지. Vitest watch 의 `watchChange` 를 받아 증분 재컴파일. 첫 `buildStart` 전에 `config()` 호출 필수 (Vitest 가 자동 호출).
+
+## SdTsCompiler
+
+```typescript
+import { SdTsCompiler } from "@simplysm/sd-cli";
+
+const compiler = new SdTsCompiler({
+  pkgDir: "/abs/path/to/packages/foo",
+  cwd: "/abs/path/to/workspace",
+  output: { js: true, dts: false },  // 출력 제어 — 둘 다 false 면 typecheck only
+  includeTests: false,                // true 면 tests/ 도 rootNames 에 포함
+  lint: false,
+  globalScss: false,
+});
+const result = await compiler.compileAsync(/* modifiedFiles? */);
+// result.diagnostics, result.errorCount, result.emitResults (Angular), ...
+```
+
+특징:
+- 인스턴스를 재사용해 호출 간 incremental 빌드 (`tsBuildInfoFile` 은 `<pkgDir>/.cache/` 하위).
+- `compileAsync(modifiedFiles)` 의 modifiedFiles 는 watch 모드의 변경 파일. 미전달 시 전체 affected 탐색.
+- Angular 패키지(`tsconfig.angularCompilerOptions`)는 자동으로 NgtscProgram 사용. 결과의 `emitResults: { filename, contents, sourceFileName }[]` 를 호출자가 디스크/번들러에 전달. Non-Angular 은 `host.writeFile` 로 디스크에 직접 emit (결과의 `emitResults` undefined).
+- `compilerOptionsTransformer` 로 target/module/outDir 등을 후처리 override 가능.
+- `transformStylesheet`, `externalStylesheets`, `sourceFileCache` 는 Angular 클라이언트 빌드 통합용 (esbuild 플러그인이 사용).
+- 단계별 try/catch 로 부분 복구 — 한 단계 실패해도 다른 진단/emit 결과는 유지.
+- 결과의 `affectedFiles` 가 `undefined` 면 전역 변경 (전체 리빌드 신호).
+
+전체 옵션·결과 필드 정의는 `packages/sd-cli/src/ts-compiler/sd-ts-compiler-options.ts`, `sd-ts-compiler-result.ts` 참조.