@simplysm/sd-claude 14.0.65 → 14.0.68

package/claude/references/sd-simplysm14/apis/core-node/consola.md

@@ -0,0 +1,64 @@
+## @simplysm/core-node — consola
+
+`consola` 전역 인스턴스 셋업 + 컬러 콘솔 리포터 + JSON 파일 회전 리포터. Node 앱(서버·CLI) 진입점에서 `setupConsola()` 1회 호출하면 환경에 맞게 reporter 가 구성됨.
+
+### setupConsola
+
+```ts
+interface SetupConsolaOptions { cli?: boolean; }
+setupConsola(opts?: SetupConsolaOptions): void;
+```
+
+- `cli: true` 또는 `env.DEV` 가 truthy → dev 모드.
+  - `SD_DEBUG` truthy: `PrettyReporter` 하나만, debug 까지.
+  - 아니면: `createFileReporter()` + `withMaxLevel(new PrettyReporter(), LogLevels.info)` — 파일에는 debug 까지, 콘솔에는 info 이상만.
+- 그 외 (prod): `createFileReporter()` 하나만, debug 까지.
+
+모든 경로에서 `consola.level = LogLevels.debug`.
+
+### PrettyReporter
+
+```ts
+class PrettyReporter implements ConsolaReporter {}
+```
+
+- 색상 자동 감지: `NO_COLOR` 있으면 off, `FORCE_COLOR` 있으면 on, TTY 면 on, win32 면 on.
+- 타입별 아이콘/색 (info=cyan, success/ready=green, warn=yellow, error/fatal/fail=red, start=magenta, debug=gear, trace=arrow).
+- `logObj.type === "box"` 면 `> tag`, `> title`, `> 각 줄` 형태로 박스 렌더.
+- `logObj.tag !== ""` 면 `[tag]` 가 회색으로 prefix.
+- level < 2 (error/fatal/warn) 는 `stderr`, 그 외 `stdout` 으로 출력. 추가로 badge 처리(앞뒤 빈 줄).
+- args 중 `Error.stack` 가진 객체는 재귀적으로 cause 체인까지 풀어서 stack 정리 (cwd 제거, `file://` 제거, 들여쓰기).
+- `type === "trace"` 면 즉시 stack 첨부.
+
+### createFileReporter
+
+```ts
+interface FileReporterOptions {
+  maxSize?: number;   // default 20MB
+  maxDays?: number;   // default 14
+}
+createFileReporter(options?: FileReporterOptions): ConsolaReporter;
+```
+
+- 출력 디렉토리: `<cwd>/.logs` (자동 mkdir).
+- 파일명: `app.<YYYY-MM-DD>.log` → 크기 초과 시 `app.<YYYY-MM-DD>.<n>.log` 로 순번.
+- 로그 1줄 = JSON: `{ time(ISO), level, tag?, err?: {message,stack}, msg? }`. `Error` arg 는 `err` 필드로, 그 외는 모두 `String` 화 후 공백 조인되어 `msg`.
+- 날짜 바뀌면 회전 + 그날 첫 write 에서 `maxDays` 이전 `app.YYYY-MM-DD.*.log` 정리.
+
+### withMaxLevel
+
+```ts
+withMaxLevel(reporter: ConsolaReporter, maxLevel: number): ConsolaReporter;
+```
+
+`logObj.level > maxLevel` 인 항목을 drop. `setupConsola` 가 dev 콘솔 리포터에 `LogLevels.info` 로 적용.
+
+### 사용 예
+
+```ts
+import { setupConsola } from "@simplysm/core-node";
+
+setupConsola({ cli: true });   // 진입점 1회
+consola.info("server started");
+consola.withTag("db").debug({ sql, params });
+```

package/claude/references/sd-simplysm14/apis/core-node/cpx.md

@@ -0,0 +1,52 @@
+## @simplysm/core-node — cpx
+
+`import { cpx } from "@simplysm/core-node"` — 자식 프로세스 spawn + 시스템 인코딩 감지. Windows `chcp` 코드 페이지 또는 POSIX `LANG/LC_ALL` 의 charset 부분을 보고 stdout/stderr 를 적절히 디코딩.
+
+### 인코딩 감지
+
+```ts
+cpx.getSystemEncoding(): string                   // 최초 1회 감지 후 모듈 캐시
+cpx.resetEncodingCache(): void
+cpx.codePageToEncoding(codePage: number): string  // 65001→utf-8, 949→euc-kr, 932→shift-jis, 936→gbk, 950→big5, 1252/1251/1250/874→windows-* / 그 외 utf-8
+```
+
+감지 실패 시 `utf-8` fallback.
+
+### 디코딩
+
+```ts
+cpx.decodeBytes(raw: Uint8Array, systemEncoding?: string): string
+// utf-8 이면 바로 디코딩.
+// 그 외 인코딩이면 먼저 utf-8 strict 시도 → 실패 시 systemEncoding 으로 fallback.
+```
+
+### spawn / spawnSync
+
+```ts
+interface SpawnResult { stdout: string; stderr: string; exitCode: number; }
+
+cpx.spawn(cmd, args, opts?: SpawnOptions & { reject?: boolean }): SpawnProcess
+cpx.spawnSync(cmd, args, opts?: SpawnSyncOptions & { reject?: boolean }): SpawnResult
+```
+
+- 기본 `stdio: "pipe"`. `process.env` 와 `opts.env` 머지해 자식에 전달.
+- stdout/stderr 가 pipe 면 모아서 `decodeBytes` 로 문자열화.
+- `exitCode !== 0` 이고 `reject !== false` 면 throw (`Command failed: <cmd> <args>`).
+- `cpx.spawn` 은 `SpawnProcess` 반환 (PromiseLike + `pid` + `kill(signal?)`).
+
+```ts
+const r = await cpx.spawn("git", ["status", "--porcelain"]);
+console.log(r.stdout);
+
+const proc = cpx.spawn("pnpm", ["watch"], { reject: false });
+process.on("SIGINT", () => proc.kill());
+const { exitCode } = await proc;
+```
+
+### resolveStdioPipe
+
+```ts
+cpx.resolveStdioPipe(stdio): { stdout: boolean; stderr: boolean }
+```
+
+stdio 값(`"pipe"`, `"inherit"`, 배열, `undefined`)에서 stdout/stderr 각각 pipe 여부 판정. spawn 자체가 내부 사용하므로 사용자 호출 거의 없음.

package/claude/references/sd-simplysm14/apis/core-node/fs-watcher.md

@@ -0,0 +1,53 @@
+## @simplysm/core-node — FsWatcher
+
+chokidar 래퍼. 짧은 시간 내 이벤트를 병합해서 콜백 1회만 호출하고, Windows 의 EPERM (감시 디렉토리 사라짐 등) 발생 시 watcher 자동 재시작. 모듈 로드 시 `fs.FSWatcher.prototype.emit` 을 한 번 패치해서, listener 없는 인스턴스의 orphan `error` 이벤트로 인한 uncaughtException 도 swallow.
+
+### 시그니처
+
+```ts
+type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir";
+
+interface FsWatcherChangeInfo {
+  event: FsWatcherEvent;
+  path: PosixPath;          // 항상 슬래시 경로
+}
+
+class FsWatcher {
+  static watch(paths: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher>;
+
+  onChange(
+    opt: { delay?: number },
+    cb: (changes: FsWatcherChangeInfo[]) => void | Promise<void>,
+  ): this;
+
+  close(): Promise<void>;
+}
+```
+
+### 동작 디테일
+
+- `paths` 의 각 원소에서 glob 메타문자(`* ? { [ ]`) 이전 부분을 `chokidar.watch` 대상 디렉토리로 추출하고, 실제 변경 알림은 원래 패턴에 대해 `minimatch(path, p, { dot: true })` 또는 `minimatch(path, p + "/**")` 매칭만 통과.
+- 항상 `ignoreInitial: true` 로 chokidar 호출. 사용자가 `options.ignoreInitial: false` 를 주면 첫 콜백을 빈 배열로 1회 호출 (실제 파일 목록은 포함하지 않음 — 이벤트 병합 모델과의 충돌 방지).
+- `onChange` 의 `delay` 로 `DebounceQueue` 생성. 윈도우 내 같은 파일의 이벤트는 lookup 테이블로 병합:
+  - `add+change` → `add`
+  - `add+unlink` → 제거 (생성 직후 삭제 상쇄)
+  - `addDir+unlinkDir` → 제거
+  - `unlink+add` → `add`
+  - `unlink+change` → `change`
+  - `unlinkDir+addDir` → `addDir`
+  - 미정의 조합은 뒤 이벤트로 덮어쓰기.
+- `error` 의 code 가 `EPERM` 이면 watcher 종료 → 1초 대기 → 재생성 → 등록된 모든 핸들러 재부착 → ready 대기. 최대 3회 시도 후 포기 (에러 로그만).
+
+### 사용 예
+
+```ts
+const watcher = await FsWatcher.watch(["src/**/*.ts", "tests/**/*.ts"]);
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { event, path } of changes) {
+    consola.info(`${event}: ${path}`);
+  }
+});
+
+// 종료
+await watcher.close();
+```

package/claude/references/sd-simplysm14/apis/core-node/fsx.md

@@ -0,0 +1,81 @@
+## @simplysm/core-node — fsx
+
+`import { fsx } from "@simplysm/core-node"` — 파일/디렉토리 IO 헬퍼. 동기·비동기 쌍으로 제공. 모든 함수는 오류를 `SdError(원본, targetPath)` 로 wrap 해서 throw.
+
+### 존재/생성/삭제
+
+```ts
+fsx.existsSync(p): boolean
+fsx.exists(p): Promise<boolean>
+fsx.mkdirSync(p): void                 // recursive
+fsx.mkdir(p): Promise<void>            // recursive
+fsx.rmSync(p): void                    // recursive, force, 재시도 없음
+fsx.rm(p): Promise<void>               // recursive, force, 6회/500ms 재시도 (파일 잠금 대응)
+```
+
+동기 rm 은 재시도 없음 — Windows 잠금 가능성 있으면 비동기 `rm` 사용.
+
+### 복사
+
+```ts
+fsx.copySync(src, dst, filter?): void
+fsx.copy(src, dst, filter?): Promise<void>
+```
+
+- `src` 없으면 no-op.
+- `filter(absolutePath): boolean` — 각 하위 항목 절대 경로로 호출. 최상위 `src` 자체는 필터 대상 아님. 디렉토리에 false 반환 시 그 하위 전체 스킵.
+- 파일 복사 6회/500ms 재시도 (sync 는 busy-wait).
+
+### 읽기/쓰기
+
+```ts
+fsx.readSync(p): string                          // utf-8
+fsx.read(p): Promise<string>
+fsx.readBytesSync(p): Uint8Array
+fsx.readBytes(p): Promise<Uint8Array>
+fsx.readJsonSync<T>(p): T                        // @simplysm/core-common json.parse
+fsx.readJson<T>(p): Promise<T>
+
+fsx.writeSync(p, data: string|Uint8Array): void  // 상위 디렉토리 자동 생성, flush:true
+fsx.write(p, data): Promise<void>
+fsx.writeJsonSync(p, data, { replacer?, space? }?): void
+fsx.writeJson(p, data, { replacer?, space? }?): Promise<void>
+```
+
+JSON 파싱 실패 시 `SdError` 메시지에 파일 경로 + 본문 500자 미리보기 포함.
+
+### 디렉토리/정보
+
+```ts
+fsx.readdirSync(p): string[]
+fsx.readdir(p): Promise<string[]>
+fsx.statSync(p): fs.Stats                        // 심볼릭 링크 따라감
+fsx.stat(p): Promise<fs.Stats>
+fsx.lstatSync(p): fs.Stats                       // 심볼릭 링크 따라가지 않음
+fsx.lstat(p): Promise<fs.Stats>
+```
+
+### Glob / 트리 유틸
+
+```ts
+fsx.globSync(pattern, options?: GlobOptions): string[]      // 항상 절대 경로, 백슬래시 → 슬래시
+fsx.glob(pattern, options?): Promise<string[]>
+
+fsx.clearEmptyDirectory(dirPath): Promise<void>             // 빈 디렉토리 재귀 삭제
+
+fsx.findAllParentChildPathsSync(childGlob, fromPath, rootPath?): string[]
+fsx.findAllParentChildPaths(childGlob, fromPath, rootPath?): Promise<string[]>
+```
+
+`findAllParentChildPaths*`: `fromPath` 에서 루트 방향으로 부모를 순회하며 각 디렉토리에 `childGlob` 적용. `rootPath` 미지정 또는 `fromPath` 가 `rootPath` 하위가 아니면 파일 시스템 루트까지 진행. `pnpm-workspace.yaml` 같은 ancestor 설정 파일 탐색에 사용.
+
+사용 예:
+
+```ts
+import { fsx } from "@simplysm/core-node";
+
+await fsx.mkdir(path.resolve(out, "dist"));
+const tsFiles = await fsx.glob("src/**/*.ts");
+const cfg = await fsx.readJson<MyConfig>("sd.config.json");
+await fsx.copy(src, dst, (p) => !p.includes(`${path.sep}node_modules${path.sep}`));
+```

package/claude/references/sd-simplysm14/apis/core-node/pathx.md

@@ -0,0 +1,55 @@
+## @simplysm/core-node — pathx
+
+`import { pathx } from "@simplysm/core-node"` — 경로 변환·비교 유틸. POSIX 스타일 통일과 cwd 기준 target 필터링용.
+
+### PosixPath 브랜드 타입
+
+```ts
+type PosixPath = string & { [POSIX]: never };
+```
+
+`posix()` 또는 `posixResolve()` 결과에만 부여. 슬래시 경로임을 타입으로 보장.
+
+### 변환
+
+```ts
+pathx.posix(p: string): PosixPath
+// 백슬래시 → 슬래시 만. resolve 안 함.
+// posix("C:\\Users\\test") === "C:/Users/test"
+
+pathx.posixResolve(...args: string[]): PosixPath
+// path.resolve 후 슬래시화. 항상 절대 경로.
+```
+
+### 비교/판정
+
+```ts
+pathx.isChildPath(child, parent): boolean
+// posixResolve 정규화 후 비교. 동일 경로면 false.
+
+pathx.changeFileDirectory(filePath, fromDir, toDir): string
+// filePath 의 fromDir 부분을 toDir 로 치환.
+// filePath === fromDir 이면 toDir 반환.
+// filePath 가 fromDir 하위가 아니면 ArgumentError throw.
+
+pathx.basenameWithoutExt(filePath): string
+// path.basename(p, path.extname(p)). "a/b/c.spec.ts" → "c.spec"
+```
+
+### target 필터링
+
+```ts
+pathx.filterByTargets(files: string[], targets: string[], cwd: string): string[]
+```
+
+- `targets` 가 비면 `files` 그대로 반환.
+- 각 `target` 은 cwd 기준 상대 경로 (POSIX 권장).
+- `files` 각 원소를 cwd 기준 상대 POSIX 로 변환 후 `relative === target || relative.startsWith(target + "/")` 매칭.
+- `files` 는 cwd 하위 절대 경로 가정 — 외부 경로는 `../` 로 변환되어 매칭에서 빠짐.
+
+CLI 의 `-t <project>` 처럼 사용자 지정 부분 경로로 후보를 좁힐 때 사용.
+
+```ts
+const files = ["/proj/src/a.ts", "/proj/tests/c.ts"];
+pathx.filterByTargets(files, ["src"], "/proj"); // ["/proj/src/a.ts"]
+```

package/claude/references/sd-simplysm14/apis/core-node/worker.md

@@ -0,0 +1,111 @@
+## @simplysm/core-node — Worker
+
+`worker_threads` 위의 타입 안전 RPC. 워커 측에서 `createWorker(methods)` 로 default export 하면, 메인 측에서 `Worker.create<typeof import("./worker")>(path)` 로 메서드 직접 호출 + 이벤트 수신 가능한 Proxy 를 얻는다. 메시지 인코딩은 `@simplysm/core-common` 의 `transfer.encode/decode` 사용 (Uint8Array 등 transferable 자동 처리).
+
+### 타입
+
+```ts
+interface WorkerModule {
+  default: {
+    __methods: Record<string, (...args: any[]) => unknown>;
+    __events: Record<string, unknown>;
+  };
+}
+
+type PromisifyMethods<T> = {
+  [K in keyof T]: T[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+};
+
+type WorkerProxy<TModule extends WorkerModule> =
+  PromisifyMethods<TModule["default"]["__methods"]> & {
+    on<E extends keyof TModule["default"]["__events"] & string>(
+      event: E, listener: (data: TModule["default"]["__events"][E]) => void,
+    ): void;
+    off<E extends keyof TModule["default"]["__events"] & string>(event: E, listener): void;
+    terminate(): Promise<void>;
+  };
+```
+
+메서드는 항상 `Promise<Awaited<R>>` 로 노출. `on`/`off`/`terminate` 는 예약어 — 워커 메서드명으로 사용 금지.
+
+### Worker.create (메인 측)
+
+```ts
+Worker.create<TModule extends WorkerModule>(
+  filePath: string,
+  opt?: Omit<WorkerOptions, "stdout" | "stderr">,
+): WorkerProxy<TModule>;
+```
+
+- `filePath`: `file://` URL 또는 절대 경로.
+- 실행 모드는 `import.meta.filename` 확장자로 결정:
+  - `.ts` (개발/tsx) → 내부 `lib/worker-dev-proxy.js` 를 띄우고 워커 파일을 argv 로 전달, tsx 로 동적 로드.
+  - `.js` (프로덕션) → 워커 파일을 그대로 `new Worker(workerPath, ...)`.
+- 항상 `stdout: true, stderr: true` 로 워커 띄우고 메인의 stdout/stderr 로 pipe. 워커 내부의 `process.stdout.write` 도 메시지 프로토콜(`type: "log"`)로 메인에 전달되어 그대로 stdout 에 출력 — 워커의 `console.log` 가 메인 터미널에 보임.
+- `opt.env` 는 `process.env` 와 머지되어 워커에 전달.
+- 워커 비정상 종료(`exit code !== 0`) 또는 `error` 발생 시 대기 중 모든 호출이 reject. `terminate()` 호출 시에도 in-flight 요청은 모두 reject.
+
+### createWorker (워커 측)
+
+```ts
+function createWorker<
+  TMethods extends Record<string, (...args: any[]) => unknown>,
+  TEvents extends Record<string, unknown> = Record<string, never>,
+>(methods: TMethods): {
+  send<E extends keyof TEvents & string>(event: E, data?: TEvents[E]): void;
+  __methods: TMethods;
+  __events: TEvents;
+};
+```
+
+- 워커 스레드에서만 호출 (`parentPort == null` 이면 `SdError` throw).
+- `methods` 의 각 함수는 메인에서 `worker.<name>(...args)` 로 호출되어 결과/throw 가 그대로 전달됨. async 함수도 await 처리됨.
+- 알 수 없는 메서드/잘못된 메시지 형식 호출 시 `SdError` 로 응답.
+- 반환값 객체에 `send(event, data?)` 가 있어 워커 → 메인 단방향 이벤트 가능. `TEvents` 제네릭으로 이벤트 이름·페이로드 타입 보장. 반환값은 반드시 `export default` 해야 메인의 `typeof import(...)` 추론이 동작.
+
+### WorkerRequest / WorkerResponse
+
+내부 메시지 프로토콜 (사용자가 직접 다룰 일 없음).
+
+```ts
+interface WorkerRequest { id: string; method: string; params: unknown[]; }
+
+type WorkerResponse =
+  | { request: WorkerRequest; type: "return"; body?: unknown }
+  | { request: WorkerRequest; type: "error";  body: Error }
+  | { type: "event"; event: string; body?: unknown }
+  | { type: "log";   body: string };
+```
+
+### 사용 예
+
+```ts
+// worker.ts
+import { createWorker } from "@simplysm/core-node";
+
+interface Events { progress: number; }
+
+const methods = {
+  async heavy(x: number) {
+    sender.send("progress", 50);
+    return x * 2;
+  },
+};
+
+const sender = createWorker<typeof methods, Events>(methods);
+export default sender;
+```
+
+```ts
+// main.ts
+import { Worker } from "@simplysm/core-node";
+
+const worker = Worker.create<typeof import("./worker")>(
+  new URL("./worker.ts", import.meta.url).href,
+);
+worker.on("progress", (p) => consola.info(`${p}%`));
+const result = await worker.heavy(21);   // 42
+await worker.terminate();
+```

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

@@ -0,0 +1,81 @@
+# @simplysm/excel
+
+OOXML(xlsx) 워크북을 lazy-load 로 읽고 쓰는 클래스 묶음. ZIP 내부 XML 을 접근 시점에만 파싱한다.
+
+## 사용 트리거 인덱스
+- **`ExcelWorkbook`** — xlsx 바이트/Blob 을 열거나 새 워크북을 만들 때. 사용 후 `close()` 필수.
+- **`ExcelWorksheet`** — 시트 단위로 셀/행/열 접근, 데이터테이블 입출력, 틀 고정/줌, 조건부 서식, 이미지 삽입.
+- **`ExcelCell` / `ExcelRow` / `ExcelCol`** — 단일 셀 값·수식·스타일·병합, 행/열 전체 셀 일괄 접근, 열 너비.
+- **`ExcelWrapper`** — Zod 스키마로 헤더·타입을 정의해 레코드 배열로 read/write.
+- **`ExcelUtils`** — `"A1"`↔좌표, 범위 주소, Excel 직렬 날짜 ↔ 타임스탬프, numFmt 변환.
+- **타입 (`ExcelValueType`, `ExcelStyleOptions`, `ExcelFont`, `ExcelConditionalRule` 등)** — 입력 옵션·반환값 정의.
+
+## ExcelWorkbook
+```typescript
+new ExcelWorkbook(arg?: Blob | Bytes)
+getWorksheetNames(): Promise<string[]>
+addWorksheet(name): Promise<ExcelWorksheet>
+getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet>  // 인덱스 0 기반
+setDefaultStyle(opts: ExcelStyleOptions): Promise<void>              // cellXfs[0] 덮어쓰기
+toBytes(): Promise<Bytes>
+toBlob(): Promise<Blob>                                              // xlsx MIME
+close(): Promise<void>                                               // 멱등, 이후 모든 메서드는 throw
+```
+패턴: `const wb = new ExcelWorkbook(bytes); try { ... } finally { await wb.close(); }`. 인자 생략 시 빈 워크북.
+
+## ExcelWorksheet
+```typescript
+getName() / setName(newName)
+row(r) / col(c) / cell(r, c)                                         // 모두 0 기반, 동기 반환
+getRange(): Promise<ExcelAddressRangePoint>
+getCells(): Promise<ExcelCell[][]>                                   // 전체 2D
+getDataTable(opt?: { headerRowIndex?; checkEndColIndex?; usableHeaderNameFn? })
+                                                                     // 레코드 배열. 중복 헤더면 throw
+setDataMatrix(matrix: ExcelValueType[][])                            // 0,0 부터
+setRecords(records: Record<string, ExcelValueType>[])                // 첫 행 헤더 자동
+copyCell / copyRow / copyCellStyle / copyRowStyle / insertCopyRow
+setZoom(percent) / freezeAt({ r?, c? })
+addConditionalFormat({ ref, rules: ExcelConditionalRule[] })         // 호출마다 priority 누적
+addImage({ bytes, ext, from, to? })                                  // ext 는 mime lookup. to 생략 시 from+1,+1
+```
+
+## ExcelCell / ExcelRow / ExcelCol
+```typescript
+// ExcelCell
+cell.addr                                                            // { r, c }
+getValue() / setValue(val: ExcelValueType)                           // string/number/boolean/DateOnly/DateTime/Time/undefined
+getFormula() / setFormula(val)                                       // 셀 타입 "str" 로 설정
+merge(endR, endC)                                                    // 현재 셀부터 (endR,endC) 까지
+getStyleId() / setStyleId(id)
+setStyle(opts: ExcelStyleOptions)                                    // 기존 스타일에 clone-merge
+
+// ExcelRow / ExcelCol
+row.cell(c) / col.cell(r)
+row.getCells() / col.getCells()
+col.setWidth(size)
+```
+값 setter 에 `undefined` → 셀 삭제. Date/Time 계열은 numFmt 자동 설정.
+
+## ExcelWrapper
+```typescript
+new ExcelWrapper(schema: z.ZodObject)                                // .describe() 가 Excel 헤더명
+read(file, wsNameOrIndex = 0, { excludes? }?): Promise<z.infer<S>[]> // 내부에서 워크북 close
+write(wsName, records, { excludes? }?): Promise<ExcelWorkbook>       // 호출자가 close 필수
+```
+write: 모든 셀 테두리, 필수(non-optional/nullable/default) 비-boolean 필드 헤더는 노란 배경, 첫 행 freeze, 줌 85%.
+
+## ExcelUtils
+```typescript
+stringifyAddr({r,c}) / parseCellAddr("B3")        // {r:2,c:1}
+stringifyColAddr(0)  // "A"     parseColAddr("AA")  // 26
+stringifyRangeAddr / parseRangeAddr("A1:C3")
+convertTimeTickToNumber(tick) / convertNumberToTimeTick(serial)      // Excel 1899-12-30 기준
+convertNumFmtIdToName / convertNumFmtCodeToName / convertNumFmtNameToId
+```
+
+## 타입 요약
+- `ExcelValueType` = `number | string | DateOnly | DateTime | Time | boolean | undefined`.
+- `ExcelStyleOptions`: `background`(ARGB 8자리), `border: ExcelBorderPosition[]`, `horizontalAlign`, `verticalAlign`, `numberFormat` (`"number"|"string"|"DateOnly"|"DateTime"|"Time"`), `numberFormatCode` (커스텀, 우선), `font: ExcelFont`.
+- `ExcelFont`: `size, family, bold, italic, underline, color(ARGB), strike`. 미지정 속성은 OOXML 에 emit 안 됨 → Excel 기본값.
+- `ExcelConditionalRule`: `{type:"cellIs", op, value, style}` | `{type:"text", op:"contains"|"notContains"|"beginsWith"|"endsWith", value, style}` | `{type:"expression", formula, style}`. `style` = `ExcelConditionalRuleStyle` (`background`, `fontColor`, `fontWeight`).
+- `ExcelAddressPoint = {r,c}` / `ExcelAddressRangePoint = {s,e}` 모두 0 기반.

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

@@ -0,0 +1,80 @@
+# @simplysm/lint
+
+Simplysm 컨벤션용 ESLint 플러그인 패키지. 커스텀 규칙 묶음(`./eslint-plugin`)과 typescript-eslint·angular-eslint 통합 flat config 프리셋(`./eslint-recommended`)을 제공한다.
+
+## 사용 트리거 인덱스
+
+- **`./eslint-recommended` (default export)** — 프로젝트 `eslint.config.{js,mjs,cjs}` 에서 그대로 spread 해 simplysm 표준 lint 규칙을 적용할 때.
+- **`./eslint-plugin` (default export)** — recommended 를 사용하지 않고 개별 규칙만 골라 쓰거나, 다른 flat config 에서 `@simplysm/<rule>` 로 참조할 때.
+
+## `./eslint-recommended`
+
+```ts
+// eslint.config.mjs
+import recommended from "@simplysm/lint/eslint-recommended";
+export default recommended;
+// 또는 추가 config 와 함께
+export default [...recommended, { /* overrides */ }];
+```
+
+`typescript-eslint.config(...)` 결과(flat config 배열). 다음을 합쳐 export 한다:
+
+- `ignores`: `**/node_modules/**`, `**/dist/**`, `**/.*/**` (디렉터리 단위 스킵).
+- `**/*.{js,mjs,cjs}` 블록: globals=node, 플러그인 `import`/`@simplysm`/`unused-imports`, `import/no-extraneous-dependencies` 예외 경로 = `**/lib/**`, `**/eslint.config.{js,cjs,mjs}`, `**/simplysm.{js,cjs,mjs}`, `**/vitest.config.{js,cjs,mjs}`.
+- `angular.configs.tsRecommended` + `**/*.ts` 블록: `tseslint.parser` + `parserOptions.project: true`, `angular.processInlineTemplates` processor, `eslint-import-resolver-typescript` resolver(`alwaysTryTypes: true`).
+- `**/*.html` 블록: `angular.configs.templateRecommended` + `templateAccessibility` extends, `@angular-eslint/template/eqeqeq` 는 `allowNullOrUndefined: true`, `label-has-associated-control` off, `template/no-any` error.
+- `**/tests/**/*.ts` override: `no-console`, `import/no-extraneous-dependencies`, `@simplysm/ts-no-throw-not-implemented-error` off.
+- `**/vitest.config.ts` override: `no-restricted-properties` off (vitest 가 `process` 접근 필요).
+
+공통으로 강제되는 simplysm 컨벤션:
+
+- `Buffer`/`buffer`/`events`/`eventemitter3` 금지 → `Uint8Array`/`@simplysm/core-common` 사용 유도.
+- `process.env`/`import.meta.env` 직접 접근 금지 → `env("...")` 호출 강제. `env("NODE_ENV")` 자체 금지.
+- `=== undefined` / `!== undefined` 금지 → `== null` / `!= null` 통일.
+- TS 블록 전용: `naming-convention` 으로 `private` 멤버에 leading underscore(`_foo`) 강제, `strict-boolean-expressions` (nullable boolean/object 허용), `ban-ts-comment` (`ts-expect-error` 는 3자 이상 설명 필수), `only-throw-error`, `no-floating-promises` 등.
+
+## `./eslint-plugin`
+
+```ts
+// eslint.config.mjs
+import simplysm from "@simplysm/lint/eslint-plugin";
+export default [{
+  plugins: { "@simplysm": simplysm },
+  rules: { "@simplysm/no-hard-private": "error" },
+}];
+```
+
+`{ rules: { ... } }` 형태의 ESLint 플러그인 객체. 노출 규칙(전부 `@simplysm/<name>` 으로 참조):
+
+### `ng-no-async-effect` (problem)
+`@angular/core`에서 import 한 `effect()` 1번째 인자가 async 함수면 보고. named/aliased/namespace import 모두 추적. `await` 이후 signal read 가 의존성 추적 밖으로 빠지는 문제 방지. 안내: 비동기 작업은 `void untracked(async () => { ... })` 로 감쌀 것.
+
+### `ng-template-no-strict-null-check` (problem)
+HTML 템플릿 바인딩에서 `=== null|undefined`, `!== null|undefined` 사용 시 보고. `== null`/`!= null` 로 통일 유도. autofix 없음(인라인 템플릿 offset 매핑 문제).
+
+### `ng-template-no-todo-comments` (problem, recommended=warn)
+HTML 주석 `<!-- TODO: ... -->` 를 정규식으로 탐지해 본문을 메시지로 보고. AST 방문자 없이 raw text 스캔.
+
+### `ng-template-sd-require-binding-attrs` (problem, fixable)
+`sd-*` 접두사 컴포넌트의 plain attribute 사용을 제한하고 property binding 으로 변환.
+- 옵션: `selectorPrefixes`(기본 `["sd-"]`), `allowAttributes`(기본 `["id","class","style","title","tabindex","role"]`), `allowAttributePrefixes`(기본 `["aria-","data-","sd-"]`).
+- Autofix: `foo="bar"` → `[foo]="'bar'"`, 값 없으면 `[foo]="true"`.
+
+### `no-hard-private` (problem, fixable)
+ES private 필드(`#field`, `#method()`, `accessor #field`, `this.#field`) 금지. TypeScript `private _field` 스타일 강제. Autofix 로 `#x` → `_x` 치환 + 선언부에 `private` 키워드 삽입(데코레이터/`static`/`async`/`readonly` 순서 보존). 동일 클래스에 `_x` 멤버가 이미 있으면 `nameConflict` 로 보고만(자동 수정 안 함).
+
+### `no-subpath-imports-from-simplysm` (problem, fixable)
+`@simplysm/<pkg>/src/...` 형태 import 금지. 정적 `import`, 동적 `import()`, `export ... from`, `export * from` 모두 검사. Autofix: `@simplysm/<pkg>` 로 단축.
+
+### `ts-no-throw-not-implemented-error` (suggestion, recommended=warn)
+`@simplysm/core-common` 에서 import 한 `NotImplementedError` 의 `new` 호출 보고. named/aliased/namespace import 추적. 인자가 비어있지 않은 문자열 리터럴이면 메시지에 그대로 노출(없으면 `"미구현"`). 동적 import 는 미지원. `**/tests/**/*.ts` 에서는 off.
+
+### `ts-no-unused-injects` (problem, fixable)
+클래스 내 `inject()` 로 초기화된 PropertyDefinition 중 같은 클래스 본문에서 식별자로 단 한 번도 참조되지 않는 필드 보고. Autofix 로 해당 필드 라인 제거.
+
+### `ts-no-unused-protected-readonly` (problem, fixable)
+`@Component({ template: "..." })` 클래스의 `protected readonly` 인스턴스 필드(=static 제외) 중 인라인 템플릿과 클래스 본문 모두에서 미참조면 보고·자동 제거. `templateUrl` 만 있는 경우(=`template` 프로퍼티 없음) 검사 스킵. 템플릿은 `@angular/compiler` 의 `parseTemplate` 로 파싱하며 `*ngFor` 로컬 변수, `@let`, `@if as alias`, `@for item/context`, `@switch`/`@defer` 트리거까지 스코프 처리.
+
+## 규칙 작성용 유틸 (내부)
+
+`createRule` 은 패키지 내부 규칙 정의 전용 헬퍼(`ESLintUtils.RuleCreator` 래퍼)로, 외부 export 표면(`exports` 필드) 에 노출되지 않는다. 소비자 코드에서 직접 사용하지 않음.

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

@@ -0,0 +1,33 @@
+# @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 패턴이 필요할 때만 외부 사용.
+- **`QueryBuilder` (`createQueryBuilder(dialect)`, `QueryBuilderBase`, `ExprRendererBase`, `*QueryBuilder`, `*ExprRenderer`)** — executor 측에서 `QueryDef` 를 dialect SQL 로 렌더할 때. 응용 코드는 직접 호출 X.
+- **`QueryDef` 타입군 (`./types/query-def`)** — executor·테스트에서 빌더가 만든 AST 를 직접 다룰 때. `QueryDef`, `SelectQueryDef`, `InsertQueryDef`, ..., `QueryDefObjectName`, `DDL_TYPES`, `DdlType`.
+- **`Expr` 타입군 (`./types/expr`)** — Expr AST 노드 타입(`ExprColumn`/`ExprValue`/`ExprRaw`/`ExprEq`/...`ExprWindow`/`ExprSubquery`). `DateUnit`. ExprRenderer 구현·검사에서 사용.
+- **`DataType` / `ColumnPrimitive*` (`./types/column`)** — SQL DataType union(`int`/`bigint`/`varchar`/`datetime`/`uuid`/...) 과 TS 타입 매핑(`ColumnPrimitiveMap`/`ColumnPrimitiveStr`/`ColumnPrimitive`/`ColumnMeta`). `dataTypeStrToColumnPrimitiveStr` 상수, `InferColumnPrimitiveFromDataType<T>` / `inferColumnPrimitiveStr(value)` 런타임 추론.
+- **`Dialect` / `dialects` / `DataRecord` / `DbContextExecutor` / `ResultMeta` / `IsolationLevel` / `Migration` / `QueryBuildResult` (`./types/db`)** — executor 구현·DbContext 외부 인터페이스. `Migration[]` 은 DbContext 서브클래스의 `migrations` 프로퍼티로 오버라이드해 `initialize()` 에서 적용.
+- **`DbContextBase` / `DbContextStatus` / `DbContextDdlMethods` (`./types/db-context-def`)** — 외부에서 DbContext 를 인터페이스로 다룰 때 (Queryable/Executable/ViewBuilder 가 의존).
+- **`DbTransactionError` / `DbErrorCode`** — executor 가 트랜잭션 에러를 표준화해 throw, 호출측은 `instanceof` 로 분기. 코드: `NO_ACTIVE_TRANSACTION`, `TRANSACTION_ALREADY_STARTED`, `DEADLOCK`, `LOCK_TIMEOUT`.
+- **`parseResults(rows, meta)` / `pickResultSets(rawResults, buildResult)` (`./utils/*`)** — executor 측 raw 결과 가공. `parseResults` 는 flat row → 중첩 객체(JOIN 그룹핑 + 타입 파싱). `pickResultSets(raw, { resultSetIndex, resultSetStride })` 는 다중 결과 셋에서 필요한 셋만 추출 (예: MySQL 배치 INSERT 의 OUTPUT SELECT).
+- **`_Migration` / `SD_BUILDER`** — 내부용. `_Migration` 은 `_migration(code PK)` 시스템 테이블, `SD_BUILDER` 는 `queryable()`/`executable()` 팩토리 함수에 붙는 메타 심볼 (`initialize()` 가 DbContext 의 프로퍼티에서 builder 를 회수할 때 사용).
+
+## 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` 상속.