@simplysm/sd-claude 14.0.88 → 14.0.90

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

@@ -1,52 +1,67 @@
-# @simplysm/orm-common — QueryDef / Expr / Column 타입
-
-executor·QueryBuilder 를 직접 구현하거나 AST·결과 메타를 다룰 때 참조하는 저수준 타입군. 일반 쿼리 작성에선 직접 쓸 일이 적다.
-
-## Column / DataType 타입
-
-- `type DataType` — SQL 데이터 타입 union: `{type:"int"}`/`{type:"bigint"}`/`{type:"float"}`/`{type:"double"}`/`{type:"decimal";precision;scale?}`/`{type:"varchar";length}`/`{type:"char";length}`/`{type:"text"}`/`{type:"binary"}`/`{type:"boolean"}`/`{type:"datetime"}`/`{type:"date"}`/`{type:"time"}`/`{type:"uuid"}`.
-- `type ColumnPrimitiveMap` — TS 타입 이름 → 실제 타입: `string`/`number`/`boolean`/`DateTime`/`DateOnly`/`Time`/`Uuid`/`Bytes`.
-- `type ColumnPrimitiveStr` — 위 키(`"string"|"number"|...`).
-- `type ColumnPrimitive` — 모든 원시 값 union + `undefined`(NULL 표현).
-- `const dataTypeStrToColumnPrimitiveStr` — SQL 타입명 → TS 타입명 매핑 객체(`int`→`"number"`, `datetime`→`"DateTime"` 등).
-- `type InferColumnPrimitiveFromDataType<T>` — `DataType` → TS 타입 추론(`cast` 결과 타입).
-- `inferColumnPrimitiveStr(value): ColumnPrimitiveStr` — 런타임 값에서 타입명 추론. NULL 이면 throw(추론 불가).
-- `interface ColumnMeta` — column 메타: `type: ColumnPrimitiveStr`/`dataType: DataType`/`autoIncrement?`/`nullable?`/`default?`/`description?`.
-
-## Database / Executor / 결과 타입
-
-- `type Dialect = "mysql" | "mssql" | "postgresql"` — 지원 dialect.
-- `const dialects: Dialect[]` — 전체 dialect 목록(dialect별 테스트 루프용).
-- `type IsolationLevel` — 격리 수준: `"READ_UNCOMMITTED"`(dirty read 허용)/`"READ_COMMITTED"`(기본, 커밋된 것만)/`"REPEATABLE_READ"`(반복 읽기 일관)/`"SERIALIZABLE"`(완전 직렬화·가장 엄격).
-- `type DataRecord` — 재귀 결과 레코드(`ColumnPrimitive | DataRecord | DataRecord[]`). include 중첩 표현.
-- `interface DbContextExecutor` — DB I/O 주입 인터페이스: `connect()`/`close()`/`beginTransaction(isolationLevel?)`/`commitTransaction()`/`rollbackTransaction()`/`executeDefs(defs, resultMetas?)`.
-- `interface ResultMeta` — 결과 변환 메타: `columns: Record<string, ColumnPrimitiveStr>`(키→타입)/`joins: Record<string, {isSingle}>`(조인 alias→단일/배열). `parseQueryResult` 입력.
-- `interface QueryBuildResult` — `QueryBuilder.build()` 반환: `sql: string`/`resultSetIndex?`(가져올 결과셋, 기본 0)/`resultSetStride?`(N번째마다 추출, MySQL 배치 INSERT 용).
-- `interface Migration` — `name: string`/`up: (db) => Promise<void>`.
-
-## Expr AST 타입
-
-`type Expr` — 전체 표현식 union. `type WhereExpr` — WHERE 전용 union(비교+논리). 각 멤버는 `type` 판별자 + 인자 필드를 가진 인터페이스. 모두 `type` 리터럴로 구분되며, 사용자는 `expr.*` 빌더로 생성하므로 직접 만들 일은 거의 없음.
-
-- 값: `ExprColumn`(`path: string[]`) / `ExprValue`(`value`) / `ExprRaw`(`sql`/`params`).
-- 비교(WhereExpr): `ExprEq`/`ExprGt`/`ExprLt`/`ExprGte`/`ExprLte`(각 `source`/`target`), `ExprBetween`(`source`/`from?`/`to?`), `ExprIsNull`(`arg`), `ExprLike`/`ExprRegexp`(`source`/`pattern`), `ExprIn`(`source`/`values`), `ExprInQuery`(`source`/`query`), `ExprExists`(`query`).
-- 논리(WhereExpr): `ExprNot`(`arg`), `ExprAnd`/`ExprOr`(`conditions`).
-- 문자열: `ExprConcat`/`ExprLeft`/`ExprRight`/`ExprTrim`/`ExprPadStart`/`ExprReplace`/`ExprUpper`/`ExprLower`/`ExprLength`/`ExprByteLength`/`ExprSubstring`/`ExprIndexOf`.
-- 숫자: `ExprAbs`/`ExprRound`(`digits`)/`ExprCeil`/`ExprFloor`.
-- 날짜: `ExprYear`/`ExprMonth`/`ExprDay`/`ExprHour`/`ExprMinute`/`ExprSecond`/`ExprIsoWeek`/`ExprIsoWeekStartDate`/`ExprIsoYearMonth`/`ExprDateDiff`(`unit`/`from`/`to`)/`ExprDateAdd`(`unit`/`source`/`value`)/`ExprFormatDate`(`format`).
-- 조건: `ExprCoalesce`/`ExprNullIf`/`ExprIs`/`ExprSwitch`(`cases`/`else`)/`ExprIf`(`condition`/`then`/`else?`).
-- 집계: `ExprCount`(`arg?`/`distinct?`)/`ExprSum`/`ExprAvg`/`ExprMax`/`ExprMin`.
-- 기타: `ExprGreatest`/`ExprLeast`/`ExprRowNum`/`ExprRandom`/`ExprCast`(`source`/`targetType`).
-- Window: `ExprWindow`(`fn: WinFn`/`spec: WinSpec`). `WinFn` union = `WinFnRowNumber`/`WinFnRank`/`WinFnDenseRank`/`WinFnNtile`(`n`)/`WinFnLag`/`WinFnLead`(`column`/`offset?`/`default?`)/`WinFnFirstValue`/`WinFnLastValue`/`WinFnSum`/`WinFnAvg`/`WinFnCount`/`WinFnMin`/`WinFnMax`. `WinSpec` = `{ partitionBy?: Expr[]; orderBy?: [Expr, ("ASC"|"DESC")?][] }`.
-- 시스템: `ExprSubquery`(`queryDef`).
-- `type DateUnit = "year"|"month"|"day"|"hour"|"minute"|"second"`.
-
-## QueryDef AST 타입
-
-`type QueryDef` — 전체 쿼리 정의 union(DML+DDL+Utils+Meta). `executeDefs`/`build` 입력.
-
-- DML: `SelectQueryDef`(`from`/`as`/`select?`/`distinct?`/`top?`/`lock?`/`where?`/`joins?`/`orderBy?`/`limit?`/`groupBy?`/`having?`/`with?`), `SelectQueryDefJoin`(+`isSingle?`), `InsertQueryDef`(`records`/`overrideIdentity?`/`output?`), `InsertIfNotExistsQueryDef`(`record`/`existsSelectQuery`), `InsertIntoQueryDef`(`recordsSelectQuery`), `UpdateQueryDef`(`record`/`where?`/`joins?`...), `DeleteQueryDef`, `UpsertQueryDef`(`existsSelectQuery`/`insertRecord`/`updateRecord`).
-- DDL: `ClearSchemaQueryDef`, `CreateTableQueryDef`(`columns`/`primaryKey?`)/`DropTableQueryDef`/`RenameTableQueryDef`/`TruncateQueryDef`, `AddColumnQueryDef`/`DropColumnQueryDef`/`ModifyColumnQueryDef`/`RenameColumnQueryDef`, `AddPrimaryKeyQueryDef`/`DropPrimaryKeyQueryDef`, `AddForeignKeyQueryDef`(`foreignKey: {name/fkColumns/targetTable/targetPkColumns}`)/`DropForeignKeyQueryDef`, `AddIndexQueryDef`(`index: {name/columns/unique?}`)/`DropIndexQueryDef`, `CreateViewQueryDef`/`DropViewQueryDef`, `CreateProcQueryDef`(`params?`/`returns?`/`query`)/`DropProcQueryDef`/`ExecProcQueryDef`(`params`).
-- Utils/Meta: `SwitchFkQueryDef`(`enabled`), `SchemaExistsQueryDef`.
-- 공통: `QueryDefObjectName`(`database?`/`schema?`/`name`) — DB 객체 이름(MySQL=`db.name`, MSSQL=`db.schema.name`, PG=`schema.name`). `CudOutputDef`(`columns`/`pkColNames`/`aiColName?`) — CUD OUTPUT 절.
-- `const DDL_TYPES` — DDL 타입명 배열(트랜잭션 내 DDL 차단 검사용. `switchFk` 는 제외 — 트랜잭션 내 허용). `type DdlType` — 그 union.
+# @simplysm/orm-common — 하위 타입 / QueryDef AST / QueryBuilder / 결과 파싱
+
+executor·QueryBuilder 를 직접 구현하거나, `QueryDef`/`Expr` AST·column 타입을 다루거나, 원시 결과를 TS 객체로 환원할 때 참조하는 묶음. 일반 쿼리 작성에서는 expr/Queryable 가 이 타입들을 가려주므로 직접 쓸 일이 적다.
+
+## column 타입
+
+- `DataType` — SQL 데이터 타입 union: `{type:"int"}`, `{type:"bigint"}`, `{type:"float"}`, `{type:"double"}`, `{type:"decimal", precision, scale?}`, `{type:"varchar", length}`, `{type:"char", length}`, `{type:"text"}`, `{type:"binary"}`, `{type:"boolean"}`, `{type:"datetime"}`, `{type:"date"}`, `{type:"time"}`, `{type:"uuid"}`. `expr.cast` 의 targetType·DDL column 정의에 사용.
+- `ColumnPrimitiveMap` — TS 타입 이름 → 실제 타입 매핑: `string→string`, `number→number`, `boolean→boolean`, `DateTime→DateTime`, `DateOnly→DateOnly`, `Time→Time`, `Uuid→Uuid`, `Bytes→Bytes`.
+- `ColumnPrimitiveStr` — `keyof ColumnPrimitiveMap`(타입 이름 문자열). `ExprUnit.dataType`·`val` 의 dataType.
+- `ColumnPrimitive` — 저장 가능한 모든 원시 값 union + `undefined`(=NULL).
+- `dataTypeStrToColumnPrimitiveStr` (const) — SQL DataType 이름 → TS 타입 이름 매핑 객체(`int→"number"`, `varchar→"string"`, `datetime→"DateTime"` 등). `cast` 가 결과 타입 결정에 사용.
+- `InferColumnPrimitiveFromDataType<T>` — `DataType` 에서 TS 값 타입 추론.
+- `inferColumnPrimitiveStr(value)` — 런타임 값에서 `ColumnPrimitiveStr` 추론. NULL 이면 추론 불가 throw.
+- `ColumnMeta` — column 메타: `{ type: ColumnPrimitiveStr; dataType: DataType; autoIncrement?; nullable?; default?; description? }`. `ColumnBuilder.meta` 타입.
+
+## db 타입
+
+- `Dialect` — `"mysql" | "mssql" | "postgresql"`. 지원 DBMS(MySQL 8.0.14+, MSSQL 2012+, PostgreSQL 9.0+).
+- `dialects` (const) — `Dialect[]`(전체 목록). dialect별 테스트 매트릭스에 사용.
+- `DataRecord` — 재귀 결과 레코드 타입: `{ [key: string]: ColumnPrimitive | DataRecord | DataRecord[] }`. include 중첩(단일 객체/배열)을 표현.
+- `QueryBuildResult` — `build()` 반환: `{ sql: string; resultSetIndex?: number; resultSetStride?: number }`. `resultSetIndex`=결과를 가져올 셋 index(기본 0, 예 MySQL INSERT+OUTPUT 는 1). `resultSetStride`=다중 결과에서 N번째마다 추출(MySQL 배치 INSERT 의 `INSERT;SELECT;...` 에서 SELECT 만 모을 때).
+- `IsolationLevel` — 트랜잭션 격리 수준(자세히는 [db-context.md](./db-context.md)).
+- `DbContextExecutor` / `ResultMeta` / `Migration` — executor·결과 메타·마이그레이션 정의. [db-context.md](./db-context.md) 참조.
+
+## QueryDef AST (query-def.ts)
+
+`executeDefs`/`build` 가 다루는 쿼리 정의 AST. `Queryable.getXQueryDef()`·`DbContext.getXQueryDef()` 가 생성.
+
+- `QueryDefObjectName` — `{ database?; schema?; name }`. DB 객체 네임스페이스(MySQL `database.name`, MSSQL `database.schema.name`, PostgreSQL `schema.name`).
+- DML: `SelectQueryDef`(from/as/select/distinct/top/lock/where/joins/orderBy/limit/groupBy/having/with), `SelectQueryDefJoin`(SelectQueryDef + `isSingle?`), `InsertQueryDef`(records/overrideIdentity?/output?), `InsertIfNotExistsQueryDef`, `InsertIntoQueryDef`, `UpdateQueryDef`, `DeleteQueryDef`, `UpsertQueryDef`.
+- `CudOutputDef` — CUD OUTPUT 절: `{ columns: string[]; pkColNames: string[]; aiColName? }`. 삽입/갱신/삭제 행 회수 정의.
+- DDL: `ClearSchemaQueryDef`, `CreateTableQueryDef`/`DropTableQueryDef`/`RenameTableQueryDef`/`TruncateQueryDef`, `AddColumnQueryDef`/`DropColumnQueryDef`/`ModifyColumnQueryDef`/`RenameColumnQueryDef`, `AddPrimaryKeyQueryDef`/`DropPrimaryKeyQueryDef`/`AddForeignKeyQueryDef`/`DropForeignKeyQueryDef`/`AddIndexQueryDef`/`DropIndexQueryDef`, `CreateViewQueryDef`/`DropViewQueryDef`/`CreateProcQueryDef`/`DropProcQueryDef`/`ExecProcQueryDef`.
+- Utils/Meta: `SwitchFkQueryDef`(`{ table; enabled }`, DDL 아님 — 트랜잭션 가능), `SchemaExistsQueryDef`.
+- `DDL_TYPES` (const) — DDL QueryDef type 문자열 배열. 트랜잭션 중 DDL 차단 판정(`switchFk` 는 제외)에 사용.
+- `DdlType` — `(typeof DDL_TYPES)[number]`.
+- `QueryDef` — 전체 union(DML + DDL + SwitchFk + SchemaExists). `executeDefs(defs: QueryDef[])` 의 원소 타입.
+
+## Expr AST (expr.ts)
+
+`ExprUnit.expr`/`WhereExprUnit.expr` 가 담는 JSON AST. QueryBuilder 의 ExprRenderer 가 SQL 로 변환.
+
+- `Expr` — 전체 표현식 union(값 `ExprColumn`/`ExprValue`/`ExprRaw`, 문자열/숫자/날짜/조건/집계/기타/window `ExprWindow`/시스템 `ExprSubquery`). select/orderBy 등.
+- `WhereExpr` — WHERE 전용 union(비교 `ExprEq`/`ExprGt`/.../`ExprIn`/`ExprInQuery`/`ExprExists` + 논리 `ExprNot`/`ExprAnd`/`ExprOr`). where/having.
+- 개별 인터페이스(`ExprEq`, `ExprConcat`, `ExprCount`, `ExprCast`, `ExprWindow` 등) — 각 `expr.*` 함수가 만드는 노드. `type` discriminant + 피연산자 필드.
+- `DateUnit` — `"year"|"month"|"day"|"hour"|"minute"|"second"`. dateDiff/dateAdd.
+- `WinFn` — window 함수 노드 union(`WinFnRowNumber`/`WinFnRank`/`WinFnLag`/`WinFnSum`/...). `WinSpec` — `{ partitionBy?: Expr[]; orderBy?: [Expr,("ASC"|"DESC")?][] }`(OVER 절).
+
+## QueryBuilder (QueryDef → SQL)
+
+직접 SQL 문자열이 필요하거나 dialect 동작을 검증할 때.
+
+- `createQueryBuilder(dialect: Dialect): QueryBuilderBase` — dialect 에 맞는 QueryBuilder 생성(`mysql`→Mysql, `mssql`→Mssql, `postgresql`→Postgresql).
+- `QueryBuilderBase` (abstract) — `build(def: QueryDef): QueryBuildResult` 가 공개 진입점. `def.type` 으로 동적 dispatch. 나머지는 protected/abstract(dialect 구현).
+- `MysqlQueryBuilder` / `MssqlQueryBuilder` / `PostgresqlQueryBuilder` — dialect별 구현. 보통 `createQueryBuilder` 로 얻음.
+- `ExprRendererBase` (abstract) — Expr→SQL 렌더러. `render(expr): string`, `renderWhere(exprs): string` 공개. `wrap(name)`/`escapeString`/`escapeValue` 는 dialect abstract.
+- `MysqlExprRenderer` / `MssqlExprRenderer` / `PostgresqlExprRenderer` — dialect별 렌더러.
+
+```typescript
+const sql = createQueryBuilder("mysql").build(queryable.getSelectQueryDef()).sql;
+```
+
+## 결과 파싱
+
+executor 가 원시 행을 받은 뒤 `ResultMeta` 로 TS 객체로 환원할 때.
+
+- `parseQueryResult<T>(rawResults, meta): Promise<T[] | undefined>` — 원시 결과 배열 + `ResultMeta` 로 타입 변환·JOIN 중첩. JOIN 없으면 단순 파싱, 있으면 그룹키 기준 재귀 그룹핑(O(n) Map). 입력 비었거나 파싱 후 전부 빈 객체면 `undefined`. 100건마다 이벤트 루프 양보(async 전용). isSingle 관계에 서로 다른 결과가 섞이면 throw.
+- `pickResultSets<T>(rawResults, buildResult): T[]` — 다중 결과셋에서 `QueryBuildResult` 의 `resultSetIndex`/`resultSetStride` 에 따라 필요한 셋만 추출. index 없으면 첫 셋, stride 없으면 index 셋 단일, stride 있으면 index 부터 stride 간격으로 concat(MySQL 배치 INSERT 의 SELECT 만 모을 때).

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

@@ -1,53 +1,90 @@
 # @simplysm/orm-node
 
-Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실 DB(MSSQL/MySQL/PostgreSQL)에 연결해 구동하는 ORM 실행 계층. 고수준 `createOrm` 팩토리와 저수준 연결(`DbConn`) 계층을 함께 제공.
+Node.js 환경에서 `@simplysm/orm-common` 의 `DbContext` 를 실제 DB(MySQL/MSSQL/PostgreSQL)에 연결·실행하는 ORM 런타임. 고수준 진입점(`createOrm`)과 저수준 연결(`createDbConn`/`DbConn`)을 함께 노출.
 
 ## 사용 트리거 인덱스
 
-- **createOrm / Orm / OrmOptions** — `DbContext` 서브클래스 + 연결설정으로 ORM 인스턴스를 만들고 `connect`/`connectWithoutTransaction` 콜백 안에서 쿼리 실행할 때. 앱에서 ORM 을 쓰는 일반 진입점. (아래 인라인 군)
-- **저수준 DB 연결 계층** (`createDbConn`, `DbConn`, `DbConnConfig`+dialect별 Config, `NodeDbContextExecutor`, `getDialectFromConfig`, `DB_CONN_*` 상수) — ORM 추상화 없이 직접 SQL·파라미터 쿼리·bulk insert·수동 트랜잭션을 다루거나 `DbContext` 의 executor 를 직접 구성할 때. 자세히: [db-conn.md](./db-conn.md)
+- **createOrm / Orm / OrmOptions** — `DbContext` 서브클래스로 ORM 인스턴스를 만들고 `connect`/`connectWithoutTransaction` 으로 트랜잭션 경계를 잡아 query 를 돌릴 때. (아래 "ORM 진입" 군)
+- **NodeDbContextExecutor** — `DbContext` 에 직접 주입할 executor 를 손수 만들 때(`createOrm` 이 내부에서 자동 생성하므로 직접 쓸 일은 드묾). (아래 "ORM 진입" 군 및 db-conn.md)
+- **createDbConn / DbConn / DbConnConfig 계열 / getDialectFromConfig / DB_CONN_\* 상수** — ORM 없이 raw SQL·파라미터 쿼리·bulk insert·수동 트랜잭션을 직접 다루거나 dialect별 접속 설정을 작성할 때. 자세히: [db-conn.md](./db-conn.md)
 
-## ORM 팩토리 (createOrm)
+## ORM 진입
 
-`DbContext` 서브클래스와 연결설정을 받아, 호출마다 새 `DbContext` 인스턴스를 만들고 트랜잭션 단위 실행을 관리하는 가장 일반적인 진입점.
+`DbContext` 서브클래스와 접속 설정을 받아 연결·트랜잭션 경계를 관리하는 고수준 진입. query DSL 자체는 `@simplysm/orm-common` 의 `DbContext` 가 제공하고, 이 군은 그 컨텍스트를 실제 DB 연결에 묶는 역할.
 
 ### createOrm
 
 ```typescript
-createOrm<T extends DbContext>(
+function createOrm<T extends DbContext>(
   DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T,
   config: DbConnConfig,
   options?: OrmOptions,
 ): Orm<T>
 ```
 
-- `DbClass` — `@simplysm/orm-common` 의 `DbContext` 를 상속한 사용자 클래스 생성자. 내부에서 `NodeDbContextExecutor(config)` 와 `{ database, schema }` 를 주입해 인스턴스화함.
-- `config: DbConnConfig` — DB 접속 정보. `dialect` 로 DBMS 분기. 상세 필드는 db-conn.md.
-- `options?: OrmOptions` — `config` 의 `database`/`schema` 보다 **우선** 적용(값이 있을 때만 덮어씀). 같은 `config` 로 DB/스키마만 바꿔 붙일 때 사용.
-- 반환 `Orm<T>` — 아래 필드·메서드를 가진 객체.
+`DbContext` 서브클래스를 받아 `Orm<T>` 를 반환. DB 인스턴스는 `connect`/`connectWithoutTransaction` 호출마다 새로 생성되므로 반환된 `Orm` 객체 자체는 재사용 가능.
 
-`database` 가 `options` 와 `config` 양쪽 모두에서 없거나 빈 문자열이면 연결 시 `"database는 필수입니다"` throw.
+- DbClass — `DbContext` 를 상속한 생성자. `(executor, { database, schema? })` 시그니처 고정. query 진입점(`this.queryable(Entity)`)을 정의한 사용자 DB 클래스를 넘김. 어떤 엔티티 집합을 다룰지 결정하는 자리.
+- config — `DbConnConfig`(dialect별 분기 유니온, [db-conn.md](./db-conn.md) 참조). 접속 대상·인증 정보. DBMS 종류·호스트·계정이 여기서 정해짐.
+- options? — `OrmOptions`. config 의 `database`/`schema` 를 덮어쓰는 우선 옵션. 같은 접속 정보로 DB·스키마만 바꿔 쓸 때(다중 테넌트 등) 지정.
 
-### OrmOptions
+database 해석: `options.database` → `config.database` 순으로 찾고, 둘 다 없거나 빈 문자열이면 `"database는 필수입니다"` throw. schema 해석도 `options.schema` → `config.schema` 순(없으면 `undefined` 유지).
+
+```typescript
+class TestDb extends DbContext {
+  user = this.queryable(User);
+}
+const orm = createOrm(TestDb, mysqlConfig, { database: "TestDb" });
+await orm.connect(async (db) => {
+  await db.user().insert([{ id: 100, name: "orm-test" }]);
+  return db.user().execute();
+}); // 트랜잭션 안에서 실행 후 자동 커밋
+```
 
-- `database?: string` — DB 이름. 지정 시 `config.database` 대신 사용(우선).
-- `schema?: string` — 스키마 이름(MSSQL `dbo`, PostgreSQL `public` 등). 지정 시 `config.schema` 대신 사용(우선). MySQL 은 스키마 개념이 없어 보통 생략.
+### Orm
 
-### Orm<T>
+```typescript
+interface Orm<T extends DbContext> {
+  readonly DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T;
+  readonly config: DbConnConfig;
+  readonly options?: OrmOptions;
+  connect<R>(callback: (conn: T) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>;
+  connectWithoutTransaction<R>(callback: (conn: T) => Promise<R>): Promise<R>;
+}
+```
 
-- `DbClass` (readonly) — 생성에 쓰인 `DbContext` 생성자 그대로 노출.
-- `config` (readonly) — 생성에 쓰인 `DbConnConfig` 그대로 노출.
-- `options?` (readonly) — 생성에 쓰인 `OrmOptions` 그대로 노출.
-- `connect<R>(callback: (conn: T) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>` — 새 `DbContext` 를 만들어 **트랜잭션 안에서** 콜백 실행하고 콜백 반환값을 그대로 반환. `isolationLevel` 로 격리수준 지정(미지정 시 연결설정의 기본 격리수준). 커밋·롤백·연결 종료는 `DbContext.connect` 가 관리.
-- `connectWithoutTransaction<R>(callback: (conn: T) => Promise<R>): Promise<R>` — **트랜잭션 없이** 연결만 열고 콜백 실행. DDL 처럼 트랜잭션 밖에서 돌려야 하거나 콜백 내부에서 `db.transaction(...)` 을 직접 제어할 때 사용.
+`createOrm` 반환 타입. 각 메서드 호출마다 DB 인스턴스를 새로 만들어 연결→콜백→정리.
 
-사용 예:
+- DbClass / config / options — `createOrm` 에 넘긴 값을 그대로 읽기 전용으로 보관. 같은 설정으로 재연결·진단할 때 참조.
+- connect — 콜백을 **트랜잭션 안에서** 실행. 콜백이 정상 종료하면 커밋, throw 하면 롤백 후 그 오류를 다시 throw. 여러 쓰기를 원자적으로 묶어야 할 때.
+- isolationLevel? — `"READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE"`(`@simplysm/orm-common`). 트랜잭션 격리 수준. 미지정 시 연결의 `defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED`. 더티 리드를 막아야 하면 `READ_COMMITTED` 이상으로 올림.
+- connectWithoutTransaction — 콜백을 **트랜잭션 없이** 실행. 읽기 전용이거나, 콜백 내부에서 `db.transaction(...)` 으로 부분 트랜잭션을 직접 열어 일부 구간만 원자화할 때.
+- callback — 연결된 DbContext 인스턴스(`T`)를 받아 query 를 수행하고 임의 값 `R` 을 반환. 그 반환값이 `connect`/`connectWithoutTransaction` 의 결과가 됨.
 
 ```typescript
-class MyDb extends DbContext {
-  user = this.queryable(User);
+// 읽기는 트랜잭션 없이, 그 안에서 일부 쓰기만 부분 트랜잭션으로
+await orm.connectWithoutTransaction(async (db) => {
+  await db.transaction(async () => {
+    await db.user().insert([{ id: 300, name: "partial-tx" }]);
+  });
+  return db.user().execute();
+});
+```
+
+### OrmOptions
+
+```typescript
+interface OrmOptions {
+  database?: string;
+  schema?: string;
 }
-const orm = createOrm(MyDb, { dialect: "mysql", host: "localhost", username: "root", password: "pw", database: "mydb" });
-const users = await orm.connect(async (db) => db.user().execute(), "READ_COMMITTED");
-await orm.connectWithoutTransaction(async (db) => db.transaction(async () => { /* ... */ }));
 ```
+
+`createOrm` 3번째 인자. config 보다 우선 적용.
+
+- database? — 사용할 DB 이름. config 의 `database` 대신 쓸 때. 접속 정보는 같고 DB 만 다른 다중 테넌트 상황에서 인스턴스별로 지정.
+- schema? — 스키마 이름(예: MSSQL `dbo`, PostgreSQL `public`). MySQL 은 스키마 개념이 없어 보통 미지정.
+
+### NodeDbContextExecutor
+
+`@simplysm/orm-common` 의 `DbContextExecutor` 를 Node 환경에서 구현한 클래스. `createOrm` 이 내부에서 생성·주입하므로 직접 다룰 일은 드묾. `DbContext` 를 `createOrm` 없이 손수 조립할 때만 사용. 생성자·메서드 전체 시그니처와 동작은 [db-conn.md](./db-conn.md) 의 동명 섹션 참조.

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

@@ -1,14 +1,14 @@
 # @simplysm/orm-node — 저수준 DB 연결
 
-`createOrm` 추상화 없이 직접 SQL/파라미터 쿼리/bulk insert/수동 트랜잭션을 다루거나, `DbContext` 의 executor 를 직접 구성할 때 사용하는 계층. 연결 인스턴스 생성·연결 인터페이스·접속설정·executor·dialect 헬퍼·상수로 구성.
+`createOrm` 추상화를 거치지 않고 raw SQL·파라미터 쿼리·bulk insert·수동 트랜잭션을 직접 다루거나, dialect별 접속 설정 타입을 작성하거나, `DbContext` 의 executor 를 손수 구성할 때 함께 읽히는 묶음. 연결 인스턴스 생성·연결 인터페이스·접속 설정·executor·dialect 헬퍼·상수로 구성.
 
 ## createDbConn
 
 ```typescript
-createDbConn(config: DbConnConfig): Promise<DbConn>
+function createDbConn(config: DbConnConfig): Promise<DbConn>
 ```
 
-`config.dialect` 에 맞는 드라이버를 **지연 import** 해 연결 인스턴스를 만든다(mysql → `mysql2/promise`, postgresql → `pg` + `pg-copy-streams`, mssql/mssql-azure → `tedious`). 한 번 로드한 드라이버는 모듈 캐시에 보관. 반환된 객체는 아직 **미연결** 상태이므로 `connect()` 를 별도 호출해야 함.
+`config.dialect` 에 맞는 드라이버를 **지연 import** 해 연결 인스턴스를 만든다(mysql → `mysql2/promise`, postgresql → `pg` + `pg-copy-streams`, mssql/mssql-azure → `tedious`). 한 번 로드한 드라이버는 모듈 캐시에 보관해 재사용. 반환 객체는 아직 **미연결** 상태이므로 `connect()` 를 별도 호출해야 함.
 
 ```typescript
 const conn = await createDbConn({ dialect: "postgresql", host: "localhost", username: "u", password: "p", database: "db" });
@@ -17,22 +17,28 @@ await conn.connect();
 
 ## DbConn
 
-저수준 연결 인터페이스. `EventEmitter<{ close: void }>` 를 상속하며 연결 종료 시 `close` 이벤트를 발생시킨다. 구현체 `MysqlDbConn`/`MssqlDbConn`/`PostgresqlDbConn` 는 직접 export 되지 않고 `createDbConn` 으로만 획득.
+저수준 연결 인터페이스. `EventEmitter<{ close: void }>` 를 상속하며 연결 종료 시 `close` 이벤트를 발생시킨다. 구현체 `MssqlDbConn`/`MysqlDbConn`/`PostgresqlDbConn` 은 직접 export 되지 않고 `createDbConn` 으로만 획득(타입 `DbConn` 만 import 가능).
 
-- `config: DbConnConfig` — 이 연결의 접속설정(읽기전용).
-- `isConnected: boolean` — 현재 연결 여부. `connect` 성공 시 `true`, `close`/종료 이벤트 시 `false`.
-- `isInTransaction: boolean` — 트랜잭션 진행 여부. `beginTransaction` 후 `true`, 커밋/롤백 후 `false`.
-- `connect(): Promise<void>` — 연결 수립. 이미 연결돼 있으면 `DB_CONN_ERRORS.ALREADY_CONNECTED` throw.
-- `close(): Promise<void>` — 연결 종료. 미연결 상태면 아무 동작 없이 반환.
-- `beginTransaction(isolationLevel?: IsolationLevel): Promise<void>` — 트랜잭션 시작. `isolationLevel` 미지정 시 `config.defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED`.
-- `commitTransaction(): Promise<void>` — 커밋.
-- `rollbackTransaction(): Promise<void>` — 롤백.
-- `execute(queries: string[]): Promise<Record<string, unknown>[][]>` — 원시 SQL 문자열 배열을 순차 실행. 빈 문자열은 건너뛰며, 각 쿼리의 결과셋을 평탄화해 묶은 배열 반환.
-- `executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>` — 파라미터 바인딩 쿼리 실행. SQL 인젝션 회피·값 재바인딩 시. 반환은 결과셋 배열(MySQL 멀티스테이트먼트는 statement별로 분리, INSERT/UPDATE/DELETE 자리는 빈 배열).
-- `bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>` — 네이티브 bulk API 로 대량 삽입. `tableName` 은 `database.table` 또는 `database.schema.table`. `columnMetas` 는 컬럼명 → `ColumnMeta`(타입·nullable) 매핑이며 키 순서가 컬럼 순서를 결정. `records` 가 빈 배열이면 아무 동작 없이 반환. dialect별 경로: MSSQL tedious BulkLoad, MySQL `LOAD DATA LOCAL INFILE`(임시 CSV 파일 생성·삭제, UUID/binary 는 `UNHEX`), PostgreSQL `COPY FROM STDIN`(CSV 스트림).
+- config: DbConnConfig — 이 연결의 접속 설정(읽기 전용). 어떤 dialect·DB 로 연결됐는지 확인용.
+- isConnected: boolean — 현재 연결 여부. `connect` 성공 시 `true`, `close`/종료(`end`) 이벤트 시 `false`. 재연결 판단·정리 분기에 사용.
+- isInTransaction: boolean — 트랜잭션 진행 여부. `beginTransaction` 후 `true`, 커밋·롤백 후 `false`. 중첩 방지·상태 확인에 사용.
+- connect(): Promise\<void\> — 연결 수립. 이미 연결돼 있으면 `DB_CONN_ERRORS.ALREADY_CONNECTED` throw.
+- close(): Promise\<void\> — 연결 종료. 미연결 상태면 아무 동작 없이 반환(throw 안 함). 재호출 안전.
+- beginTransaction(isolationLevel?: IsolationLevel): Promise\<void\> — 트랜잭션 시작. `isolationLevel` 미지정 시 `config.defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED` 로 시작. 테스트로 확인된 값: `"READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE"`. 더티 리드 차단이 필요하면 `READ_COMMITTED` 이상.
+- commitTransaction(): Promise\<void\> — 진행 중 트랜잭션 커밋, `isInTransaction` 을 `false` 로.
+- rollbackTransaction(): Promise\<void\> — 진행 중 트랜잭션 롤백, `isInTransaction` 을 `false` 로.
+- execute(queries: string[]): Promise\<Record\<string, unknown\>[][]\> — 원시 SQL 문자열 배열을 순차 실행. 빈/공백 문자열은 건너뜀. 각 쿼리의 결과셋들을 평탄화해 하나의 배열로 묶어 반환. DDL·다건 SQL 일괄 실행에 사용.
+- executeParametrized(query: string, params?: unknown[]): Promise\<Record\<string, unknown\>[][]\> — 파라미터 바인딩 쿼리 1건 실행. SQL 인젝션 회피·값 재바인딩 시. 반환은 결과셋 배열(MySQL 멀티스테이트먼트는 statement별로 분리되며 INSERT/UPDATE/DELETE 자리는 빈 배열, PostgreSQL 은 단일 결과셋). `params` 미지정 시 MSSQL 은 배치(`execSqlBatch`) 경로, 지정 시 `execSql` 파라미터 경로로 실행.
+- bulkInsert(tableName: string, columnMetas: Record\<string, ColumnMeta\>, records: Record\<string, unknown\>[]): Promise\<void\> — 네이티브 bulk API 로 대량 삽입. `tableName` 은 `database.table` 또는 `database.schema.table`(dialect별 인용 부호 포함된 완전 수식명). `columnMetas` 는 컬럼명 → `ColumnMeta`(`dataType`·`nullable`) 매핑이며 **키 순서가 컬럼 순서를 결정**, `records` 의 각 객체는 이 키들로 값 추출. `records` 가 빈 배열이면 아무 동작 없이 반환. `DateTime`/`DateOnly`/`Time`/`Uuid`/`Uint8Array`/`null` 값은 dialect별로 적절히 변환됨.
+
+dialect별 bulk insert 경로(서버 측 권한·설정에 의존):
+
+- MSSQL — tedious `BulkLoad`. `ColumnMeta.dataType` 을 tedious 타입으로 매핑.
+- MySQL — `LOAD DATA LOCAL INFILE`. 임시 CSV 파일을 생성·실행 후 삭제하며, UUID/binary 컬럼은 `UNHEX()` 로 복원.
+- PostgreSQL — `COPY FROM STDIN`(CSV 스트림). binary 는 bytea hex 형식으로 인코딩.
 
 ```typescript
-await conn.beginTransaction();
+await conn.beginTransaction("READ_COMMITTED");
 const [rows] = await conn.executeParametrized('SELECT * FROM "User" WHERE id = $1', [1]);
 await conn.commitTransaction();
 ```
@@ -43,27 +49,31 @@ await conn.commitTransaction();
 
 공통 필드:
 
-- `dialect` — `"mysql"` | `"mssql"` | `"mssql-azure"` | `"postgresql"`. DBMS 선택. `"mssql-azure"` 는 Azure SQL 용으로 드라이버는 mssql 과 동일하되 연결 시 `encrypt` 활성화. 쿼리 빌더용으로는 `getDialectFromConfig` 가 `"mssql"` 로 정규화.
-- `host: string` — 접속 호스트.
-- `port?: number` — 포트. 미지정 시 드라이버 기본값(PostgreSQL 은 5432 로 보정).
-- `username: string` — 인증 사용자.
-- `password: string` — 인증 비밀번호.
-- `database?: string` — 기본 DB 이름.
-- `defaultIsolationLevel?: IsolationLevel` — `beginTransaction` 의 `isolationLevel` 미지정 시 적용할 기본 격리수준.
+- dialect — `"mysql" | "mssql" | "mssql-azure" | "postgresql"`. DBMS 선택. `"mssql-azure"` 는 Azure SQL 용으로 드라이버는 mssql 과 동일하되 연결 시 `encrypt` 가 활성화됨. 쿼리 빌더용 dialect 로는 `getDialectFromConfig` 가 `"mssql"` 로 정규화.
+- host: string — 접속 호스트.
+- port?: number — 포트. 미지정 시 드라이버 기본값(PostgreSQL 은 미지정 시 5432 로 보정).
+- username: string — 인증 사용자.
+- password: string — 인증 비밀번호.
+- database?: string — 접속 기본 DB 이름.
+- defaultIsolationLevel?: IsolationLevel — `beginTransaction` 의 `isolationLevel` 미지정 시 적용할 기본 격리 수준. 연결 단위로 기본 격리를 고정하고 싶을 때.
 
 dialect별 추가 필드:
 
-- `MysqlDbConnConfig` — `dialect: "mysql"`. 공통 필드만(스키마 개념 없음).
-- `MssqlDbConnConfig` — `dialect: "mssql" | "mssql-azure"`. `schema?: string`(예 `dbo`) 추가.
-- `PostgresqlDbConnConfig` — `dialect: "postgresql"`. `schema?: string`(예 `public`) 추가.
+- MysqlDbConnConfig — `dialect: "mysql"`. 공통 필드만(스키마 개념 없음).
+- MssqlDbConnConfig — `dialect: "mssql" | "mssql-azure"`. `schema?: string`(예 `dbo`) 추가.
+- PostgresqlDbConnConfig — `dialect: "postgresql"`. `schema?: string`(예 `public`) 추가.
+
+```typescript
+const cfg: MssqlDbConnConfig = { dialect: "mssql", host: "localhost", port: 21433, username: "sa", password: "...", database: "TestDb", schema: "dbo" };
+```
 
 ## getDialectFromConfig
 
 ```typescript
-getDialectFromConfig(config: DbConnConfig): Dialect
+function getDialectFromConfig(config: DbConnConfig): Dialect
 ```
 
-`config.dialect` 를 `@simplysm/orm-common` 의 `Dialect` 로 변환. `"mssql-azure"` → `"mssql"` 로 정규화하고 나머지는 그대로 반환. 쿼리 빌더의 dialect 결정에 사용.
+`config.dialect` 를 `@simplysm/orm-common` 의 `Dialect` 로 변환. `"mssql-azure"` → `"mssql"` 로 정규화하고 나머지는 그대로 반환. 쿼리 빌더의 dialect 결정에 사용 — Azure 여부와 무관하게 같은 SQL 방언을 써야 할 때.
 
 ## NodeDbContextExecutor
 
@@ -71,24 +81,25 @@ getDialectFromConfig(config: DbConnConfig): Dialect
 new NodeDbContextExecutor(config: DbConnConfig)
 ```
 
-`@simplysm/orm-common` 의 `DbContextExecutor` 를 Node 환경에서 구현한 클래스. `createOrm` 이 내부에서 자동 주입하므로 보통 직접 쓸 일은 없고, `DbContext` 를 `createOrm` 없이 수동 인스턴스화할 때만 사용. 생성자에는 `DbConnConfig` 만 받고, 실제 연결은 `connect()` 시점에 `createDbConn` 으로 지연 생성한다.
+`@simplysm/orm-common` 의 `DbContextExecutor` 를 Node 환경에서 구현한 클래스. `createOrm` 이 내부에서 자동 주입하므로 보통 직접 쓸 일은 없고, `DbContext` 를 `createOrm` 없이 수동 인스턴스화할 때만 사용. 생성자는 `DbConnConfig` 만 받고, 실제 연결은 `connect()` 시점에 `createDbConn` 으로 지연 생성한다.
 
-- `connect(): Promise<void>` — `createDbConn(config)` 로 연결 생성 후 수립.
-- `close(): Promise<void>` — 연결 종료 후 내부 참조 해제.
-- `beginTransaction(isolationLevel?: IsolationLevel)` / `commitTransaction()` / `rollbackTransaction()` — 트랜잭션 위임.
-- `executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>` — 파라미터 쿼리 위임.
-- `bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: DataRecord[]): Promise<void>` — bulk insert 위임.
-- `executeDefs<T>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>` — `QueryDef` 배열을 dialect 쿼리 빌더로 SQL 변환해 실행. `resultMetas` 가 전부 `null`/미지정이면(결과 불필요) 모든 def 를 하나의 SQL 로 합쳐 단일 요청으로 보내고 def 수만큼 빈 배열 반환(쓰기 전용 최적화). 그 외엔 def 마다 개별 실행 후, 해당 위치에 `resultMeta` 가 있으면 `parseQueryResult` 로 타입 변환해 반환.
+- constructor(config: DbConnConfig) — `getDialectFromConfig` 로 dialect 를 결정해 보관. 이 시점엔 연결을 열지 않음.
+- connect(): Promise\<void\> — `createDbConn(config)` 로 연결 생성 후 수립.
+- close(): Promise\<void\> — 연결 종료 후 내부 참조 해제.
+- beginTransaction(isolationLevel?: IsolationLevel) / commitTransaction() / rollbackTransaction() — 내부 `DbConn` 에 트랜잭션 제어 위임. `isolationLevel?` 의미는 위 `DbConn.beginTransaction` 과 동일.
+- executeParametrized(query: string, params?: unknown[]): Promise\<Record\<string, unknown\>[][]\> — 파라미터 쿼리 위임.
+- bulkInsert(tableName: string, columnMetas: Record\<string, ColumnMeta\>, records: DataRecord[]): Promise\<void\> — bulk insert 위임.
+- executeDefs\<T\>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise\<T[][]\> — `QueryDef` 배열을 dialect 쿼리 빌더로 SQL 변환해 실행. `resultMetas` 가 전부 `null`/미지정이면(결과 불필요) 모든 def 를 하나의 SQL 로 합쳐 단일 요청으로 보내고 def 수만큼 빈 배열 반환(쓰기 전용 최적화, 인터페이스 계약 유지). 그 외엔 def 마다 개별 실행 후, 해당 위치에 `resultMeta` 가 있으면 `parseQueryResult` 로 타입 변환해 반환, 없으면 raw 결과셋 그대로 반환.
 - 모든 실행 메서드는 미연결 상태에서 호출 시 `SdError(DB_CONN_ERRORS.NOT_CONNECTED)` throw.
 
 ## 상수
 
-- `DB_CONN_CONNECT_TIMEOUT` — 연결 수립 타임아웃. `10 * 1000`(10초).
-- `DB_CONN_DEFAULT_TIMEOUT` — 쿼리 기본 타임아웃. `10 * 60 * 1000`(10분). 마지막 활동 후 이 값의 2배가 지나면 연결을 자동 종료(idle 타임아웃).
-- `DB_CONN_ERRORS` — 오류 메시지 상수 객체. `NOT_CONNECTED`(미연결 상태 실행 시), `ALREADY_CONNECTED`(이미 연결된 상태에서 재연결 시). `expect(...).rejects.toThrow(DB_CONN_ERRORS.NOT_CONNECTED)` 처럼 throw 비교·메시지 매칭에 사용.
+- DB_CONN_CONNECT_TIMEOUT — 연결 수립 타임아웃 `10 * 1000`(10초). 드라이버의 connect 타임아웃으로 전달.
+- DB_CONN_DEFAULT_TIMEOUT — 쿼리 기본 타임아웃 `10 * 60 * 1000`(10분). 마지막 활동 후 이 값의 2배가 지나면 연결을 자동 종료(idle 타임아웃)하는 데도 사용.
+- DB_CONN_ERRORS — 오류 메시지 상수 객체(`as const`). `NOT_CONNECTED`(미연결 상태에서 실행 시), `ALREADY_CONNECTED`(이미 연결된 상태에서 재연결 시). `expect(...).rejects.toThrow(DB_CONN_ERRORS.NOT_CONNECTED)` 처럼 throw 비교·메시지 매칭에 사용.
 
 ## 주의사항
 
 - `createDbConn` 반환 객체는 미연결 상태 — 반드시 `connect()` 호출 후 사용.
-- bulk insert 는 dialect별 네이티브 경로가 달라(MySQL 은 임시파일 + `LOCAL INFILE`, PostgreSQL 은 `COPY`) 서버 측 권한·설정에 의존할 수 있음.
-- 대부분의 작업은 `createOrm`(README)으로 충분. 이 계층은 원시 SQL·executor 커스터마이징이 필요한 경우에만.
+- bulk insert 는 dialect별 네이티브 경로가 달라(MySQL 임시파일 + `LOCAL INFILE`, PostgreSQL `COPY`, MSSQL `BulkLoad`) 서버 측 권한·설정에 의존할 수 있음.
+- 대부분의 작업은 `createOrm`(README)으로 충분. 이 계층은 raw SQL·executor 커스터마이징이 필요한 경우에만.

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

@@ -1,29 +1,27 @@
 # @simplysm/sd-cli
 
-simplysm 모노레포의 빌드/배포 오케스트레이터 CLI. entry(`src/index.ts`)가 라이브러리로 재노출하는 것은 `sd.config.ts` 작성용 설정 타입 묶음, Vitest용 Angular AOT Vite 플러그인, 프로그래밍 방식 TS/Angular AOT 컴파일러 클래스 3종. (CLI 서브커맨드 구현 자체는 entry export 대상 아님.)
+simplysm 모노레포의 빌드/배포 오케스트레이터 CLI. entry(`src/index.ts`)가 외부로 노출하는 것은 CLI 실행 코드가 아니라 세 가지뿐: ① `sd.config.ts` 작성용 설정 타입군, ② 패키지 단위 TypeScript/Angular AOT 증분 컴파일러(`SdTsCompiler`)와 그 옵션·결과 타입, ③ Vitest 전용 Angular Vite 플러그인(`sdAngularPlugin`).
 
 ## 사용 트리거 인덱스
 
-- **sd.config.ts 설정 타입** (`SdConfig`, `SdConfigFn`, `SdConfigParams`, `SdPackageConfig` 계열, `SdPublishConfig` 계열, Capacitor/Electron/PWA 설정 등) — 프로젝트 루트 `sd.config.ts` 를 작성·수정해 패키지 빌드 타겟·배포·앱 패키징을 설정할 때. 자세히: [sd-config-types.md](./sd-config-types.md)
-- **SdTsCompiler** (`SdTsCompiler`, `ISdTsCompilerOptions`, `ISdTsCompilerResult`) — 패키지의 `.ts` 를 TS/Angular AOT 로 증분 컴파일하고 진단·emit·lint·SCSS 결과를 한 번에 얻을 때 (빌드 엔진·플러그인 내부에서 사용). 자세히: [SdTsCompiler.md](./SdTsCompiler.md)
-- **sdAngularPlugin** — Vitest 에서 Angular 패키지를 AOT 컴파일해 TestBed 로 돌리기 위한 Vite 플러그인을 `vitest.config.ts` 에 끼울 때. 아래 인라인 섹션 참조.
+- **sd.config.ts 설정 타입** — 프로젝트 루트 `sd.config.ts` 를 작성·수정하며 어떤 패키지를 어떤 타겟(`node`/`browser`/`neutral`/`client`/`server`/`scripts`)으로 빌드할지, 배포(npm/로컬/FTP)·Capacitor/Electron/PWA·서버 옵션을 지정할 때. `SdConfigFn` 으로 default export 함수 타입을 잡고 각 패키지를 타겟별 인터페이스로 채움. 자세히: [sd-config-types.md](./sd-config-types.md)
+- **SdTsCompiler / ISdTsCompilerOptions / ISdTsCompilerResult / ISdTsCompilerEmitOptions** — sd-cli 외부에서 패키지 단위 TS(또는 Angular AOT) 증분 컴파일을 직접 구동하거나 그 결과(emit·진단·lint·SCSS)를 다룰 때. 자세히: [SdTsCompiler.md](./SdTsCompiler.md)
+- **sdAngularPlugin / SdAngularPluginOptions** — Vitest 에서 Angular 패키지의 `.ts` 를 AOT 컴파일해 주입하는 Vite 플러그인을 설정할 때. 아래 인라인 섹션 참조.
 
 ## sdAngularPlugin
 
-Vitest 전용 Vite 플러그인. `SdTsCompiler` 로 대상 패키지의 `.ts` 를 AOT 컴파일하고, `transform` 훅에서 컴파일된 JS 를 반환한다.
-
 ```typescript
-function sdAngularPlugin(options: SdAngularPluginOptions): Plugin
+function sdAngularPlugin(options: SdAngularPluginOptions): Plugin; // vite Plugin 반환
+interface SdAngularPluginOptions { pkg: string; }
 ```
 
-`SdAngularPluginOptions`:
-
-- pkg: string — `sd.config.ts` 의 `packages` 키(패키지 디렉토리명, `@simplysm/` 접두사 제외). `config()` 훅에서 `packages/<pkg>` 를 컴파일 루트로 해석한다. 어느 Angular 패키지를 테스트 빌드할지 지정.
+Angular AOT 컴파일을 수행하는 **Vitest 전용** Vite 플러그인(`vitest.config.ts` 의 `angular` project plugins 에 등록). 내부에서 `SdTsCompiler` 로 대상 패키지의 `.ts`(tests 포함, `includeTests: true`, `output: { js: true, dts: false }`)를 AOT 컴파일하고, Vite `transform` 훅에서 컴파일된 JS 를 반환한다. `enforce: "pre"` 로 다른 transform 보다 먼저 동작하며, 컴파일러가 만든 인라인 base64 소스맵을 분리해 Vite 호환 형태(`{ code, map }`)로 넘긴다. `compilerOptionsTransformer` 로 `noEmit:false`·`declaration:false`·`inlineSourceMap:true`·`rootDir = cwd` 를 강제하고, `buildEnd` 마다 내부 컴파일러를 폐기해 다음 watch 재빌드 때 재생성하며, watch 변경 파일을 모아 `buildStart` 의 캐시 무효화에 쓴다.
 
-동작: `enforce: "pre"` 플러그인. `buildStart` 에서 내부 `SdTsCompiler`(`output: { js: true, dts: false }`, `includeTests: true`, `rootDir` = cwd)로 패키지 전체를 AOT 컴파일해 소스경로→JS 맵을 만들고, `transform` 훅이 매칭되는 `.ts` 요청에 컴파일된 JS(인라인 소스맵 분리)를 돌려준다. `watchChange` 로 모은 변경 파일을 다음 `buildStart` 의 증분 무효화에 넘기고, `buildEnd` 에서 컴파일러를 폐기해 다음 라운드에 재생성한다. 진단은 logger 로 보고, emit 디스크 출력은 하지 않음.
+- pkg: string — 컴파일 대상 패키지 디렉토리명. `sd.config.ts` 의 `packages` 키와 동일(`@simplysm/` 접두사 제외한 짧은 이름, 예: `"angular"`). 플러그인은 `process.cwd()/packages/<pkg>` 를 컴파일 루트로 잡으므로, 테스트하려는 Angular 패키지명을 그대로 넣는다.
 
 ```typescript
+// vitest.config.ts
 import { sdAngularPlugin } from "@simplysm/sd-cli";
-// vitest.config.ts project.plugins 에 추가
+
 plugins: [sdAngularPlugin({ pkg: "angular" })];
 ```