@simplysm/sd-claude 14.0.82 → 14.0.83

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

@@ -1,58 +0,0 @@
-# @simplysm/orm-common
-
-Dialect 독립 ORM 코어. `DbContext` 상속으로 테이블/뷰/프로시저를 등록하고, fluent builder + Expr AST 로 쿼리를 구성하면, 각 DBMS(MySQL/MSSQL/PostgreSQL) QueryBuilder 가 SQL 로 렌더한다. 실제 connect/execute 는 외부 executor 가 구현 (서버=`@simplysm/orm-node`, 클라이언트=`@simplysm/service-client` 의 OrmServiceClient).
-
-## 사용 트리거 인덱스
-
-- **`DbContext` (abstract class)** — DB 1개에 매핑되는 서브클래스를 만들 때. `protected queryable(Builder)` / `executable(Builder)` 로 테이블·뷰·프로시저를 인스턴스 프로퍼티로 등록, `connect()`/`transaction()` 로 실행 경계 잡고, DDL/`initialize()` 로 스키마 만들 때. 자세히: [db-context.md](./db-context.md)
-- **Schema Builders** — `Table(name)`, `View(name)`, `Procedure(name)` 로 스키마 객체 정의할 때. Column / Index / Relation factory 포함. 자세히: [schema-builders.md](./schema-builders.md)
-- **`Queryable` / `queryable()`** — `DbContext` 에 등록된 테이블/뷰에서 SELECT/INSERT/UPDATE/DELETE/UPSERT 빌더 체이닝, JOIN/include/recursive CTE/UNION/search 할 때. 자세히: [queryable.md](./queryable.md)
-- **`Executable` / `executable()`** — 등록된 프로시저 호출 결과 받을 때. 자세히: [executable.md](./executable.md)
-- **`expr` namespace + `ExprUnit`/`WhereExprUnit`** — `where`/`select`/`groupBy`/`having`/`update` 콜백 안에서 비교·논리·문자열·날짜·집계·윈도우·CASE·subquery 등 SQL 표현식 만들 때. dialect 독립 AST. 자세히: [expr.md](./expr.md)
-- **`parseSearchQuery(text)`** — `Queryable.search()` 내부에서 쓰는 OR/`+`AND/`-`NOT/`"…"`/`*` 구문 파서. 직접 LIKE 패턴이 필요할 때만 외부 사용. (`ParsedSearchQuery` = `{ or, must, not }`)
-- **`createQueryBuilder(dialect)`** — `Dialect` 문자열로 dialect 별 QueryBuilder 인스턴스 받을 때 (executor 진입점).
-- **`QueryBuilderBase` / `ExprRendererBase`** — 커스텀 dialect 구현을 위해 상속 베이스 필요할 때.
-- **`MysqlQueryBuilder` / `MssqlQueryBuilder` / `PostgresqlQueryBuilder`** (와 대응 `*ExprRenderer`) — 특정 dialect 인스턴스를 직접 new 하거나 `instanceof` 분기할 때. 일반은 `createQueryBuilder` 사용.
-- **`QueryDef` (union) + `QueryDefObjectName` (`./types/query-def`)** — executor 가 받는 query AST 의 union 타입 / 모든 DDL/DML 이 공통으로 쓰는 `{database?, schema?, name}` 형태의 DB 객체 식별자.
-- **`SelectQueryDef`, `InsertQueryDef`, `InsertIfNotExistsQueryDef`, `InsertIntoQueryDef`, `UpdateQueryDef`, `DeleteQueryDef`, `UpsertQueryDef`, `SelectQueryDefJoin`, `CudOutputDef`** — DML AST 노드를 직접 만들거나 검사할 때 (executor·테스트).
-- **DDL QueryDef (`Create*` / `Drop*` / `Rename*` / `Add*` / `Modify*` / `Truncate*` / `Clear*` / `Schema*` / `ExecProc*` 등)** — 스키마 변경/프로시저 호출 AST 를 직접 다룰 때 (`getXxxQueryDef()` 반환 타입과 일치).
-- **`DDL_TYPES` (배열) / `DdlType` (union)** — query 가 DDL 인지 런타임/타입 레벨에서 검사할 때. 트랜잭션 내 DDL 차단 가드에서 사용.
-- **`Expr` (union) / `WhereExpr` (union)** — SELECT·ORDER BY·SET 콜백이 모두 받는 일반 표현식 AST 와, WHERE·HAVING 전용 boolean 표현식 AST. ExprRenderer 가 dispatch 하는 대상.
-- **개별 Expr 노드 (`ExprColumn`, `ExprValue`, `ExprRaw`, `ExprEq`, `ExprLike`, `ExprConcat`, `ExprDateDiff`, `ExprSwitch`, `ExprCount`, `ExprWindow`, `ExprSubquery` …)** — Expr renderer 구현, AST 검사, 디버깅 시 개별 노드 타입 필요할 때. 응용 코드는 `expr.*` 헬퍼만 사용.
-- **`WinFn` (union) / `WinSpec` / `WinFn*` 개별 노드** — Window 함수 AST 분기 (`rowNumber`, `rank`, `lag`, `sumOver` 등) 를 직접 처리할 때.
-- **`DateUnit`** — `dateDiff`/`dateAdd` 의 단위 union (`"year" | "month" | "day" | "hour" | "minute" | "second"`). 동적으로 단위 선택할 때.
-- **`DataType` (`./types/column`)** — SQL 타입 union (`{type:"int"}` / `{type:"varchar",length}` / `{type:"decimal",precision,scale?}` ...). DDL/cast 의 타입 인자.
-- **`ColumnPrimitive` / `ColumnPrimitiveStr` / `ColumnPrimitiveMap`** — Column 값으로 허용되는 TS 타입 union (`string|number|boolean|DateTime|DateOnly|Time|Uuid|Bytes|undefined`), 그 키 이름 union, 키→타입 매핑. ExprUnit/ResultMeta 가 사용.
-- **`ColumnMeta`** — `ColumnBuilder.meta` 의 형태 (`{type, dataType, autoIncrement?, nullable?, default?, description?}`). 외부에서 column 정의를 읽어 DDL 만들 때.
-- **`dataTypeStrToColumnPrimitiveStr`** — `DataType.type` → `ColumnPrimitiveStr` 상수 매핑. cast 결과 dataType 추론에 사용.
-- **`InferColumnPrimitiveFromDataType<T>`** — `DataType` 타입에서 TS 값 타입 추론 (제네릭 타입 유틸).
-- **`inferColumnPrimitiveStr(value)`** — 런타임 값에서 `ColumnPrimitiveStr` 추론. NULL/unknown 이면 throw.
-- **`Dialect`** — `"mysql" | "mssql" | "postgresql"` union. dialect 분기/`createQueryBuilder` 인자.
-- **`dialects`** — `Dialect[]` 상수 배열. 테스트의 `it.each(dialects)` 또는 모든 dialect 순회용.
-- **`DataRecord`** — query 결과 row 의 재귀 타입 (`{ [key]: ColumnPrimitive | DataRecord | DataRecord[] }`). Queryable/Executable 의 결과 제약.
-- **`DbContextExecutor`** — 외부에서 DbContext 에 주입할 executor 인터페이스 (`connect`/`close`/`beginTransaction`/`commitTransaction`/`rollbackTransaction`/`executeDefs`). 신규 dialect/원격 executor 구현 시.
-- **`ResultMeta`** — `executeDefs` 가 받는 `{columns: Record<string,ColumnPrimitiveStr>, joins: Record<string,{isSingle}>}`. raw row → 타입 변환·JOIN 그룹핑에 필요.
-- **`IsolationLevel`** — `"READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE"`. `connect`/`transaction` 인자.
-- **`Migration`** — `{name, up(db)}`. DbContext 서브클래스의 `migrations` 프로퍼티 타입. `initialize()` 가 적용.
-- **`QueryBuildResult`** — `QueryBuilder.build()` 반환 (`{sql, resultSetIndex?, resultSetStride?}`). executor 가 `pickResultSets` 로 좁힐 때 필요.
-- **`DbContextBase` (`./types/db-context-def`)** — DbContext 의 코어 인터페이스 (`status`/`database`/`schema`/`executeDefs`/`getNextAlias` 등). Queryable·Executable·ViewBuilder 가 의존하므로 mock/대체 구현 시 사용.
-- **`DbContextStatus`** — `"ready" | "connect" | "transact"`. status 분기 시.
-- **`DbContextDdlMethods`** — `createTable`/`addColumn`/`addForeignKey` 등 DDL 메서드 집합 인터페이스. `Migration.up` 의 db 인자 타입.
-- **`DbTransactionError`** — executor 가 트랜잭션 에러를 표준화해 throw 하는 클래스. 호출측은 `instanceof DbTransactionError` 로 분기.
-- **`DbErrorCode`** — `NO_ACTIVE_TRANSACTION` / `TRANSACTION_ALREADY_STARTED` / `DEADLOCK` / `LOCK_TIMEOUT` enum. `err.code === DbErrorCode.DEADLOCK` 같은 분기에 사용.
-- **`parseQueryResult(rows, meta)` (`./utils/result-parser`)** — flat row 배열 + `ResultMeta` → 타입 변환 + JOIN 그룹핑된 중첩 객체 배열. async. 빈 결과면 undefined. executor 가 SELECT/OUTPUT 결과를 사용자 객체로 가공할 때.
-- **`pickResultSets(rawResults, buildResult)` (`./utils/pick-result-sets`)** — `QueryBuildResult` 의 `resultSetIndex`/`resultSetStride` 따라 여러 결과 셋 중 필요한 셋만 추출/concat. MySQL 배치 INSERT 의 OUTPUT SELECT 만 모을 때.
-- **`_Migration`** — `_migration(code PK varchar(255))` 시스템 테이블의 TableBuilder. DbContext 가 자동 등록, 사용자 직접 import 불필요.
-- **`SD_BUILDER`** — `queryable()`/`executable()` 팩토리 함수에 builder 를 부착하는 심볼. `initialize()` 가 DbContext 의 프로퍼티에서 builder 를 회수할 때 사용. 사용자 코드 직접 사용 X.
-
-## QueryBuilder (인라인)
-
-```ts
-import { createQueryBuilder } from "@simplysm/orm-common";
-const qb = createQueryBuilder("mysql"); // | "mssql" | "postgresql"
-const { sql, resultSetIndex, resultSetStride } = qb.build(queryDef);
-```
-
-`QueryBuilderBase.build(def)` 가 `def.type` 으로 동적 dispatch 하여 dialect 별 메서드 호출. 결과는 `QueryBuildResult { sql; resultSetIndex?; resultSetStride? }` — 여러 result set 이 돌아오는 dialect 별 패턴(MySQL OUTPUT INSERT 등)을 위해 추출 인덱스/스트라이드 동봉. executor 는 받은 raw set 배열을 `pickResultSets(raw, buildResult)` 로 좁힌다.
-
-`createQueryBuilder(dialect)` 외에 dialect 클래스(`MysqlQueryBuilder`/`MssqlQueryBuilder`/`PostgresqlQueryBuilder` 와 대응 `*ExprRenderer`)도 export. 일반적으로 `createQueryBuilder` 만 쓰면 충분, 커스텀 확장 시 `QueryBuilderBase`/`ExprRendererBase` 상속.

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

@@ -1,77 +0,0 @@
-# @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

@@ -1,20 +0,0 @@
-# @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

@@ -1,92 +0,0 @@
-# @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

@@ -1,98 +0,0 @@
-# @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

@@ -1,128 +0,0 @@
-# @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

@@ -1,69 +0,0 @@
-# @simplysm/orm-node
-
-Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실제 DB(MSSQL/MySQL/PostgreSQL)에 붙여 실행하기 위한 어댑터. 드라이버 모듈(`tedious`/`mysql2`/`pg`/`pg-copy-streams`)은 dialect 선택 시점에 지연 import.
-
-## 사용 트리거 인덱스
-
-- **`createOrm`** — `DbContext` 서브클래스 + `DbConnConfig` 로 ORM 인스턴스 생성. 일반 ORM 사용의 진입점.
-- **`Orm<T>`** — `createOrm` 반환 타입. 함수 시그니처·DI 토큰에서 참조하거나 `connect` / `connectWithoutTransaction` 호출 시.
-- **`OrmOptions`** — `createOrm` 3번째 인자. `DbConnConfig` 의 `database` / `schema` 를 런타임에 덮어쓸 때.
-- **`createDbConn`** — `DbConnConfig` 만으로 저수준 `DbConn` 인스턴스 직접 생성. `DbContext` 없이 raw SQL/bulk insert 가 필요할 때.
-- **`NodeDbContextExecutor`** — `DbContext` 의 executor 직접 주입이 필요할 때. 일반적으로는 `createOrm` 이 내부적으로 사용.
-- **`MysqlDbConn`** — MySQL 용 `DbConn` 구현 클래스. 직접 `new` 하지 말고 `createDbConn` 사용. 타입 참조용 import.
-- **`MssqlDbConn`** — MSSQL/Azure SQL 용 `DbConn` 구현 클래스. 직접 `new` 하지 말고 `createDbConn` 사용. 타입 참조용 import.
-- **`PostgresqlDbConn`** — PostgreSQL 용 `DbConn` 구현 클래스. 직접 `new` 하지 말고 `createDbConn` 사용. 타입 참조용 import.
-- **`DbConn`** — 저수준 연결 인터페이스. 모든 dialect 공통 메서드(`connect`/`close`/트랜잭션/`execute`/`executeParametrized`/`bulkInsert`) 와 `close` 이벤트.
-- **`DbConnConfig`** — dialect 분기 union 타입. `createOrm`/`createDbConn` 입력.
-- **`MysqlDbConnConfig`** — `dialect: "mysql"` 한정 설정 타입.
-- **`MssqlDbConnConfig`** — `dialect: "mssql" | "mssql-azure"` 설정 타입. `schema?` 포함.
-- **`PostgresqlDbConnConfig`** — `dialect: "postgresql"` 설정 타입. `schema?` 포함.
-- **`getDialectFromConfig`** — `DbConnConfig` → `Dialect` 변환(`mssql-azure` → `mssql`). 쿼리 빌더 선택 시.
-- **`DB_CONN_CONNECT_TIMEOUT`** — DB 연결 수립 타임아웃 상수 (10초).
-- **`DB_CONN_DEFAULT_TIMEOUT`** — 쿼리/유휴 기본 타임아웃 상수 (10분).
-- **`DB_CONN_ERRORS`** — `NOT_CONNECTED` / `ALREADY_CONNECTED` 에러 메시지 리터럴.
-
-## 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회로 묶어 실행하고 `defs.length` 개의 빈 배열 반환(결과 불필요 케이스 최적화). 미연결 상태에서 메서드 호출 시 `DB_CONN_ERRORS.NOT_CONNECTED` SdError throw.

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

@@ -1,32 +0,0 @@
-# @simplysm/sd-claude
-
-Claude Code 셋업 자산(`.claude/` 의 sd-* 스킬·룰·훅) 배포 및 `sd-claude` CLI 제공 패키지. 코드 API 없음 — 외부 import 가능한 라이브러리 심볼 미노출.
-
-## 사용 트리거 인덱스
-
-- 현재 로그인된 Claude 계정을 프로필로 저장 → [auth save](#cli-sd-claude)
-- 저장된 다른 Claude 계정으로 전환 → [auth switch](#cli-sd-claude)
-- 소비 프로젝트 설치 시 `.claude/` 자산 자동 배치 → [postinstall](#패키지-훅)
-- 워크스페이스 `.claude/` 변경분을 패키지 `claude/` 로 동기화(배포 직전) → [prepack / sync](#패키지-훅)
-
-## CLI `sd-claude`
-
-`bin: sd-claude` → `scripts/cli.mjs`. 사용법: `sd-claude <subcommand> <action>`.
-
-- `auth save`: 현재 `claude auth status` 의 `orgName` 을 프로필 키로, `~/.claude/.credentials.json` 의 `claudeAiOauth.refreshToken` 과 `~/.claude/statusline-cache.json` 의 사용량 스냅샷을 `~/.claude/profiles.json` 에 저장하고 `current` 를 해당 프로필로 설정. orgName 또는 refreshToken 미획득 시 stderr 출력 후 exit 1.
-- `auth switch`: `profiles.json` 의 계정 목록을 번호 + 현재 마커(`*`) + 사용량(현재 계정은 live, 그 외는 저장 시점) 으로 출력. 번호 입력으로 대상 선택 → 현재 계정의 최신 refreshToken·사용량을 백업 저장 → `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`/`CLAUDE_CODE_OAUTH_SCOPES` 환경변수로 `claude auth login` 을 spawn → 갱신된 refreshToken 저장 + `current` 업데이트. TTY 아니면 exit 1.
-- 그 외 인자: 사용법 출력 후 exit 1.
-
-저장 위치 식별자 풀이:
-- `~/.claude/profiles.json`: `{ current: string, accounts: { [orgName]: { refreshToken, usage } } }` 구조. 패키지가 관리.
-- `~/.claude/.credentials.json`: Claude Code 본체가 관리. `claudeAiOauth.refreshToken` 만 읽음.
-- `~/.claude/statusline-cache.json`: Claude Code 본체가 관리. `rate_limits.five_hour` / `seven_day` 의 `used_percentage` + `resets_at` 만 읽음.
-
-## 패키지 훅
-
-- `postinstall` (`scripts/postinstall.mjs`): 소비 프로젝트의 `node_modules` 설치 시 자동 실행. `INIT_CWD` 또는 `node_modules` 경로 역추적으로 프로젝트 루트 결정 → `<projectRoot>/.claude/` 의 기존 sd-* 항목(root 1단계 + 하위 디렉토리 1단계의 `^sd[-_]` 매칭) 정리 후 패키지 `claude/` 의 동일 항목 + `settings.json` + `simplysm.json` 을 복사. 소비 프로젝트가 `name: "simplysm"` 이고 메이저 버전이 같으면 skip(모노레포 자기 자신 보호). 실패해도 throw 하지 않음(install 차단 방지).
-- `prepack` (`scripts/sync.mjs`): `pnpm pub`/`npm pack` 직전 실행. 워크스페이스 루트(`../../`)의 `.claude/` 에서 sd-* 항목(+ `settings.json`/`simplysm.json`) 을 패키지 `claude/` 로 증분 복사. 동일 파일은 mtime+size 비교로 skip, 변경분은 unlink 후 copy + src mtime 보존, src 에 없는 dest 항목은 prune. 제외: `evals/` 하위, 파일명 `SKILL.eval.md`, `eval_*` 접두 파일. (Windows EPERM 회피 위해 일괄 rmSync 미사용.)
-
-식별자 풀이:
-- sd-* 항목 스캔 범위: 디렉토리 root + 1단계 하위. 정규식 `^sd[-_]`. 즉 `.claude/skills/sd-foo/`, `.claude/rules/sd-bar.md`, `.claude/sd-baz/` 등 매칭.
-- watch 훅 연동: 모노레포에서는 `sd.config.ts` 의 `scripts` 타겟이 `.claude/sd-*` 변경 감지 시 본 `sync.mjs` 를 호출(패키지 외부 설정).