@simplysm/sd-claude 14.0.75 → 14.0.77

package/claude/references/sd-simplysm14/apis/core-common/utils.md

@@ -1,158 +1,189 @@
 # @simplysm/core-common — utils
 
-네임스페이스 import: `import { obj, str, num, bytes, path, json, xml, wait, transfer, err, dt, primitive } from "@simplysm/core-common";`
-
-## obj — 객체 조작
-
-### 복사·비교·병합
-
-```typescript
-obj.clone(src)                                        // 깊은 복사. 순환 참조·DateTime/DateOnly/Time/Uuid/
-                                                      //   Uint8Array/Date/RegExp/Error(cause)/Map/Set 지원.
-                                                      //   함수/Symbol 은 참조 유지, WeakMap/WeakSet 미지원.
-obj.equal(a, b, opt?)                                 // 깊은 동등. opt: { topLevelIncludes?, topLevelExcludes?,
-                                                      //   ignoreArrayIndex?, shallow? }
-                                                      //   include/exclude 는 최상위 객체 키에만 적용. shallow=true 면 1단계 참조 비교.
-obj.merge(source, target, opt?)                       // 깊은 병합 (불변, 새 객체). opt:
-                                                      //   { arrayProcess?: "replace"|"concat", useDelTargetNull? }
-obj.merge3(source, origin, target, optionsObj?)       // 3-way merge. { conflict, result }
-                                                      //   optionsObj 는 key별 { keys?, excludes?, ignoreArrayIndex? }
-```
+`utils/` 네임스페이스 일괄 export. import는 `import { obj, str, ..., js, ZipArchive } from "@simplysm/core-common"`.
 
-### 키 조작
+## `obj` — 객체 조작
+
+```ts
+obj.clone<T>(source): T
+  // 깊은 복사. 순환 참조 지원. Date/DateTime/DateOnly/Time/Uuid/RegExp/Error/Uint8Array/Array/Map/Set 모두 별도 처리.
+  // 프로토타입 체인 유지(Object.setPrototypeOf). 함수·Symbol은 참조 유지. WeakMap/WeakSet 미지원. getter/setter는 현재 값으로 평가.
+
+obj.equal(source, target, options?: EqualOptions): boolean
+interface EqualOptions {
+  topLevelIncludes?: string[]   // 지정한 key만 비교 (최상위만, 객체 속성에만 적용)
+  topLevelExcludes?: string[]   // 지정한 key 제외 (최상위만)
+  ignoreArrayIndex?: boolean    // array 순서 무시. true면 O(n²) (permutation 매칭)
+  shallow?: boolean             // 1단계 참조 비교
+}
+  // null != null 분기, custom 타입은 tick/toString 기반 비교.
 
-```typescript
-obj.omit(o, ["k1","k2"])
-obj.omitByFilter(o, (k) => k.startsWith("_"))
-obj.pick(o, ["k1","k2"])
-obj.keys(o) / obj.entries(o) / obj.fromEntries(pairs)  // 타입 안전 Object.* 래퍼
-obj.map(o, (k, v) => [newK | null, newV])              // entry 변환 (newK=null 이면 원래 키 유지)
-```
+obj.merge<S, T>(source, target, opt?: MergeOptions): S & T
+interface MergeOptions {
+  arrayProcess?: "replace" | "concat"   // 기본 "replace"(target으로 교체). "concat"=합집합(Set 중복 제거)
+  useDelTargetNull?: boolean            // target이 null이면 결과 key 삭제
+}
+  // 불변 (새 객체 반환). 타입 다르면 target으로 덮어씀. Map은 재귀 머지.
 
-### 체인 경로 (`"a.b[0].c"` 형식)
+obj.merge3(source, origin, target, optionsObj?: Record<key, Merge3KeyOptions>):
+  { conflict: boolean; result: O & S & T }
+  // 3-way merge. source==origin → target 채택, target==origin → source 채택,
+  // source==target → 채택, 셋 다 다름 → conflict=true + origin 유지
+interface Merge3KeyOptions { keys?; excludes?; ignoreArrayIndex? }   // equal과 동일
 
-```typescript
-obj.getChainValue(o, "a.b[0].c")
-obj.getChainValue(o, "a.b[0].c", true)   // optional: 중간 null 만나면 undefined
-obj.setChainValue(o, "a.b.c", v)         // 중간 객체 자동 생성
-obj.deleteChainValue(o, "a.b.c")
-obj.getChainValueByDepth(o, key, depth, optional?)  // 같은 key 로 N단계 하강
-```
+obj.omit(item, omitKeys[]): Omit<T, K>
+obj.omitByFilter(item, (key) => boolean): T          // @internal
+obj.pick(item, keys[]): Pick<T, K>
 
-### 변환 (원본 변형 — `@mutates`)
+obj.getChainValue(o, "a.b[0].c", optional?: true): unknown
+obj.getChainValueByDepth(o, key, depth, optional?): T[K]   // 같은 key로 depth회 하강
+obj.setChainValue(o, chain, value): void
+obj.deleteChainValue(o, chain): void
 
-```typescript
-obj.clearUndefined(o)     // null/undefined 값 키 제거
-obj.clear(o)              // 모든 키 제거
-obj.nullToUndefined(o)    // 재귀, null → undefined
-obj.unflatten({ "a.b.c": 1 })  // → { a: { b: { c: 1 } } }
-```
+obj.clearUndefined(o): T                              // @mutates null/undefined key 삭제
+obj.clear(o): {}                                      // @mutates 전체 비우기
+obj.nullToUndefined(o): T                             // @mutates null→undefined (재귀, 순환 안전)
+obj.unflatten({ "a.b.c": 1 }): { a: { b: { c: 1 } } }   // @internal
 
-### 타입 유틸
+obj.keys(o): (keyof T)[]                              // 타입 안전 Object.keys
+obj.entries(o): [K, V][]                              // 타입 안전 Object.entries
+obj.fromEntries(pairs): Record
+obj.map(o, (key, value) => [newKey | null, newValue]): Record
+  // null newKey → 기존 key 유지. key/value 동시 변환
 
-```typescript
-obj.UndefToOptional<T>    // { a: string|undefined } → { a?: string|undefined }
-obj.OptionalToUndef<T>    // { a?: string } → { a: string|undefined }
+type UndefToOptional<T>                               // { a, b: T|undefined } → { a, b?: T }
+type OptionalToUndef<T>                               // { a, b? } → { a, b: T|undefined }
 ```
 
-## str — 문자열
+## `str` — 문자열
 
-```typescript
-str.getKoreanSuffix(text, "을"|"은"|"이"|"와"|"랑"|"로"|"라")
-                                  // 받침 유무로 조사 결정. "로" 는 ㄹ 받침이면 "로".
-str.replaceFullWidth(s)           // 전각 영숫자/공백/괄호 → 반각
-str.toPascalCase(s) / toCamelCase(s) / toKebabCase(s) / toSnakeCase(s)
-                                  // case 함수는 기존 -/_ 구분자 보존, 연속 대문자 개별 분리 ("XMLParser" → "x-m-l-parser")
-str.isNullOrEmpty(s)              // null|undefined|"" 타입 가드
-str.insert(s, idx, insertStr)
+```ts
+str.getKoreanSuffix(text, type: "을"|"은"|"이"|"와"|"랑"|"로"|"라"): string
+  // 받침 유무로 조사 자동. "로"는 ㄹ 받침 예외(받침 있어도 "로"). 한글 외 문자→무받침 취급.
+str.replaceFullWidth(str): string                    // 전각 영숫자/공백/괄호 → 반각
+str.toPascalCase(s) / toCamelCase / toKebabCase / toSnakeCase
+  // PascalCase: 하이픈/언더/점 + 소문자 → 대문자. 첫글자 대문자화.
+  // kebab/snake: 대문자/대문자그룹 분리. 기존 구분자는 유지 (혼합 시 "hello-_world").
+str.isNullOrEmpty(s): s is "" | undefined            // 타입 가드
+str.insert(s, index, insertString): string
 ```
 
-## num — 숫자
+## `num` — 숫자
 
-```typescript
-num.parseInt(text)        // 비숫자 제거 후 정수 파싱. 선행 - 만 음수 부호, 중간 - 제거. 소수점은 trunc.
-num.parseFloat(text)
-num.parseRoundedInt(text) // float 후 반올림
-num.isNullOrEmpty(v)      // null|undefined|0 타입 가드
-num.format(v, { max?, min? })  // 천 단위 + 소수점 자릿수. toLocaleString 기반
+```ts
+num.parseInt(text): number | undefined               // 숫자 외 문자 제거. 선행 - 만 음수, 중간 - 제거. "010-1234-5678"→1012345678
+num.parseFloat(text): number | undefined
+num.parseRoundedInt(text): number | undefined        // parseFloat 후 Math.round
+num.isNullOrEmpty(n): n is 0 | undefined             // 타입 가드 (0/null/undefined)
+num.format(val, digit?: { max?, min? }): string      // toLocaleString. min 부족분은 0 패딩
 ```
 
-## bytes — Uint8Array
+## `bytes` — Uint8Array
 
-```typescript
-bytes.concat([a, b, ...])
-bytes.toHex(u8) / bytes.fromHex(hex)            // 소문자 hex. 홀수 길이/잘못된 문자 시 ArgumentError
-bytes.toBase64(u8) / bytes.fromBase64(b64)      // 표준 base64 (+/, = 패딩). 공백 자동 제거
+```ts
+bytes.concat(arrs: Bytes[]): Bytes
+bytes.toHex(b): string                               // 소문자
+bytes.fromHex(hex): Bytes                            // 홀수 길이/무효 문자 → ArgumentError
+bytes.toBase64(b): string
+bytes.fromBase64(s): Bytes                           // 공백·패딩 정규화. 무효 문자/길이 → ArgumentError
 ```
 
-## path — POSIX 경로 (브라우저용)
+## `path` — POSIX 경로 (브라우저용, `/` 만 지원)
 
-```typescript
-path.join(...segs)            // 슬래시만 지원, 백슬래시 X
-path.basename(p, ext?)
-path.extname(p)               // 숨김 파일(".gitignore")은 빈 문자열
+```ts
+path.join(...segments): string                       // 슬래시 정규화
+path.basename(filePath, ext?): string                // ext 제거 옵션
+path.extname(filePath): string                       // 숨김파일(.gitignore)은 "" (Node 동일)
 ```
 
-## json — 커스텀 타입 지원 JSON
+## `json` — 커스텀 타입 지원 JSON
 
-```typescript
-json.stringify(obj, { space?, replacer?, redactBytes? })
-                              // Date/DateTime/DateOnly/Time/Uuid/Set/Map/Error/Uint8Array 를 { __type__, data } 로.
-                              //   redactBytes=true 면 Uint8Array 내용을 "__hidden__"로 (parse 복원 불가).
-                              //   순환 참조 시 TypeError. 전역 prototype 미수정 (Worker 안전).
-json.parse<T>(str)            // __type__ 마커 복원. 모든 null → undefined (simplysm null-free 규칙).
-                              //   에러 시 SdError. DEV 환경에서만 메시지에 전체 JSON 포함.
+```ts
+json.stringify(obj, options?: {
+  space?: number | string,
+  replacer?: (key, value) => unknown,
+  redactBytes?: boolean,                             // Uint8Array → "__hidden__" (로깅용, parse 시 throw)
+}): string
+json.parse<T>(str): T
 ```
+- 사전 변환으로 `{ __type__, data }` 태그 객체 생성: Date/DateTime/DateOnly/Time/Uuid/Set/Map/Error(cause·code·detail 포함)/Uint8Array(hex). `Date.prototype.toJSON` 미수정 → Worker 안전.
+- 순환 참조 → `TypeError`.
+- `parse`는 `nullToUndefined` 적용 (모든 JSON `null` → `undefined`, simplysm null-free 규칙).
+- 파싱 실패 시 `__DEV__` 환경에서는 메시지에 전체 JSON 포함, 아니면 길이만.
 
-## xml — fast-xml-parser 래퍼
+## `xml` — XML (fast-xml-parser 래퍼)
 
-```typescript
-xml.parse(str, { stripTagPrefix? })
-   // 결과: 속성은 `$` 객체, 텍스트는 `_` 키, 자식 요소는 배열 (루트 제외).
-   //   stripTagPrefix=true 면 "ns:tag" → "tag" (속성은 유지).
-xml.stringify(obj, options?)  // fast-xml-parser XmlBuilderOptions
+```ts
+xml.parse(str, options?: { stripTagPrefix?: boolean }): unknown
+xml.stringify(obj, options?: XmlBuilderOptions): string
 ```
+- 속성은 `$` 그룹, 텍스트 노드는 `_` key. 1단계 깊이 미만은 단일 객체, 이상은 array.
+- `stripTagPrefix`: `"ns:tag"`에서 접두사 제거 (속성은 유지).
 
-## wait — 대기
+## `wait` — 타이밍
 
-```typescript
-await wait.time(ms)
-await wait.until(() => cond, intervalMs=100, maxCount?)   // maxCount 초과 시 TimeoutError
+```ts
+wait.time(ms): Promise<void>                         // setTimeout Promise화
+wait.until(forwarder, ms = 100, maxCount?): Promise<void>
+  // forwarder가 true 반환할 때까지 ms 간격 폴링. maxCount 초과 시 TimeoutError(count)
 ```
 
-## transfer — Worker 전송
+## `transfer` — Worker 직렬화
 
-`structuredClone` 미지원 타입 처리. Date/DateTime/DateOnly/Time/Uuid/RegExp/Error(cause/code/detail)/Uint8Array/Map/Set/Array/Object.
+```ts
+transfer.encode(obj): { result: unknown; transferList: ArrayBuffer[] }
+transfer.decode(obj): unknown
+```
+- `worker.postMessage(result, transferList)` 패턴. Uint8Array는 zero-copy 전송, SharedArrayBuffer는 transferList 제외.
+- 지원: Date/DateTime/DateOnly/Time/Uuid/RegExp, Error(cause·code·detail), Array/Map/Set/일반 객체. 그 외 TypedArray는 일반 객체로 처리됨.
+- 순환 참조 → `TypeError("순환 참조 감지됨: <path>")`. 같은 객체 다중 참조는 캐시 재사용.
+
+## `err` — 에러 메시지
 
-```typescript
-const { result, transferList } = transfer.encode(data);
-worker.postMessage(result, transferList);          // Uint8Array.buffer 가 transferList 에 zero-copy
-const decoded = transfer.decode(event.data);
+```ts
+err.message(err: unknown): string                    // Error.message 또는 String(err)
 ```
 
-순환 참조 시 `TypeError("순환 참조 감지됨: <path>")`. 같은 객체 다중 참조는 인코딩 결과 캐싱.
+## `dt` — 날짜·시간 포맷 내부 헬퍼
+
+```ts
+dt.format(formatStr, args: { year?, month?, day?, hour?, minute?, second?, millisecond?, timezoneOffsetMinutes? }): string
+dt.normalizeMonth(year, month, day): { year, month, day }   // 월 오버플로 + 일수 보정
+dt.convert12To24(rawHour, isPM): number                     // 12 AM=0, 12 PM=12
+```
+- format 토큰: `yyyy yy`, `MM M`, `ddd`(요일 한글), `dd d`, `tt`(AM/PM), `hh h`(12시간), `HH H`(24시간), `mm m`, `ss s`, `fff ff f`(밀리초), `zzz zz z`(타임존 ±HH:mm/±HH/±H). 긴 토큰 우선.
 
-## err — 에러 메시지
+## `primitive` — PrimitiveType 런타임
 
-```typescript
-err.message(unknownErr)   // Error 면 .message, 아니면 String(err)
+```ts
+primitive.typeStr(value): PrimitiveTypeStr           // 값 → "string"|"number"|"boolean"|"DateTime"|"DateOnly"|"Time"|"Uuid"|"Bytes"
 ```
+- 미지원 타입 → `ArgumentError`.
 
-## dt — date-format 저수준
+## 직접 export — 템플릿 태그
 
-`DateTime/DateOnly/Time#toFormatString` 내부에서 사용. 직접 사용 드묾.
+`js`, `ts`, `html`, `tsql`, `mysql`, `pgsql` — 모두 같은 동작 (IDE 코드 하이라이팅용). 들여쓰기 정규화: 앞뒤 빈 줄 제거 + 모든 줄에서 공통 최소 들여쓰기만큼 dedent.
 
-```typescript
-dt.format(formatStr, { year?, month?, day?, hour?, minute?, second?, millisecond?, timezoneOffsetMinutes? })
-   // 토큰은 types.md 의 "date-format 토큰" 참조
-dt.normalizeMonth(year, month, day)    // 월 1-12 정규화 + 일 클램프
-dt.convert12To24(rawHour, isPM)        // 12시간 → 24시간
+```ts
+const sql = mysql`
+  SELECT * FROM users
+  LIMIT 10
+`;
 ```
 
-## primitive — 런타임 타입 추론
+## 직접 export — `ZipArchive` (`@zip.js/zip.js` 래퍼)
 
-```typescript
-primitive.typeStr(value)
-// string/number/boolean/DateTime/DateOnly/Time/Uuid/Bytes 중 하나 반환.
-// 미지원 타입은 ArgumentError.
+```ts
+class ZipArchive {
+  constructor(data?: Blob | Bytes)                   // 없으면 새 아카이브
+  extractAll(progressCb?: (p: { fileName, totalSize, extractedSize }) => void): Promise<Map<string, Bytes>>
+  get(fileName): Promise<Bytes | undefined>          // 캐싱됨
+  exists(fileName): Promise<boolean>
+  write(fileName, bytes): void                       // 캐시에만 저장
+  compress(): Promise<Bytes>                         // 캐시된 모든 파일을 ZIP으로 (extractAll 호출 → 전체 메모리 적재)
+  close(): Promise<void>                             // reader 닫고 캐시 비움
+}
+interface ZipArchiveProgress { fileName, totalSize, extractedSize }
 ```
+- 같은 파일 재추출 방지를 위해 내부 `_cache: Map<filename, Bytes>` 사용.
+- 대용량 ZIP 의 `compress()` 는 메모리 주의 (스트리밍 X).

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

@@ -1,21 +1,12 @@
 ## @simplysm/core-node
 
-Node.js 전용 유틸·기능 묶음. 파일 IO/glob, 경로 변환, 자식 프로세스 spawn, 파일 시스템 감시, consola 리포터 셋업, worker_threads 타입 안전 래퍼.
+Node.js 환경 전용 파일시스템·자식 프로세스·경로·파일감시·로깅·Worker 유틸 묶음.
 
 ## 사용 트리거 인덱스
 
-- **`fsx` 네임스페이스** — 파일/디렉토리 존재 확인·생성·복사·삭제·읽기·쓰기·JSON·glob·재귀 유틸. 자세히: [fsx.md](./fsx.md)
-- **`pathx` 네임스페이스** — POSIX 경로 변환, 하위 경로 판정, 디렉토리 치환, target 필터링. 자세히: [pathx.md](./pathx.md)
-- **`cpx` 네임스페이스** — 시스템 인코딩 감지 + 자식 프로세스 spawn/spawnSync (인코딩 자동 디코딩, exitCode 기반 reject). 자세히: [cpx.md](./cpx.md)
-- **`FsWatcher`** — chokidar 기반 디바운스/이벤트 병합 + Windows EPERM 자동 복구 파일 감시. 자세히: [fs-watcher.md](./fs-watcher.md)
-- **consola 셋업** — Node 앱 진입점에서 로깅 환경(콘솔/파일) 구성. 자세히: [consola.md](./consola.md)
-  - **`setupConsola`** — 진입점 1회 호출. dev/prod·`SD_DEBUG`·`cli` 조합으로 리포터 자동 구성.
-  - **`PrettyReporter`** — 색상·아이콘·tag·stack/cause 정리 포함 콘솔 출력 리포터.
-  - **`createFileReporter`** — `<cwd>/.logs/app.<날짜>.log` JSON 회전 + 보존 기간 정리.
-  - **`withMaxLevel`** — 기존 리포터에 level 상한 필터 씌우기 (dev 콘솔에서 debug 가리기 등).
-- **Worker 래퍼** — worker_threads 위 타입 안전 RPC (메서드 호출 + 이벤트 + 워커 stdout 메인 전달). 자세히: [worker.md](./worker.md)
-  - **`Worker.create`** — 메인 측. 워커 파일을 띄우고 메서드 직접 호출 가능한 Proxy 반환.
-  - **`createWorker`** — 워커 측. `methods` 등록 + `send(event, data)` 로 이벤트 발행. `export default` 필수.
-  - **`WorkerProxy<TModule>`** — `Worker.create` 반환 타입. 워커 모듈 타입 추론에 사용.
-  - **`WorkerModule`** — 워커 default export 의 구조 인터페이스 (`__methods`/`__events`). 직접 구현 불필요.
-  - **`PromisifyMethods<T>`** — 메서드 반환을 `Promise<Awaited<R>>` 로 감싸는 매핑 타입. `WorkerProxy` 내부 사용.
+- **`fsx`** — 파일/디렉토리 존재확인·생성·복사·삭제·읽기/쓰기(텍스트/바이너리/JSON)·glob·부모 디렉토리 탐색이 필요할 때. 자세히: [fsx.md](./fsx.md)
+- **`pathx`** — POSIX 슬래시 경로 변환, 부모-자식 경로 판정, cwd 기준 타겟 필터링이 필요할 때. 자세히: [pathx.md](./pathx.md)
+- **`cpx`** — 자식 프로세스 spawn(비동기/동기), 시스템 인코딩 자동 디코딩, 실패 시 reject 옵션. 자세히: [cpx.md](./cpx.md)
+- **`FsWatcher`** — 디렉토리/glob 변경 감시 + 디바운싱 + 이벤트 병합 + EPERM 자동 재시작. 자세히: [fs-watcher.md](./fs-watcher.md)
+- **`setupConsola` / `PrettyReporter` / `createFileReporter`** — CLI/서버 로깅 일괄 설정, 컬러 콘솔 + JSONL 파일 회전. 자세히: [consola.md](./consola.md)
+- **`Worker` / `createWorker`** — 타입 안전 worker_threads 래퍼. 메인에서 `Worker.create()`, 워커에서 `createWorker()`. 자세히: [worker.md](./worker.md)

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

@@ -1,64 +1,59 @@
-## @simplysm/core-node — consola
+## @simplysm/core-node — consola 설정
 
-`consola` 전역 인스턴스 셋업 + 컬러 콘솔 리포터 + JSON 파일 회전 리포터. Node 앱(서버·CLI) 진입점에서 `setupConsola()` 1회 호출하면 환경에 맞게 reporter 가 구성됨.
+전역 `consola` 인스턴스에 reporter 를 일괄 부착하는 헬퍼와 reporter 구현체.
 
 ### setupConsola
 
 ```ts
-interface SetupConsolaOptions { cli?: boolean; }
-setupConsola(opts?: SetupConsolaOptions): void;
+setupConsola(opts?: { cli?: boolean }): 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` 로 설정 후 환경에 따라 reporter 구성:
 
-모든 경로에서 `consola.level = LogLevels.debug`.
+- `opts.cli !== true` && `env("DEV")` falsy → **프로덕션**: `createFileReporter()` 만 (JSONL 파일, 콘솔 X).
+- 그 외 → **개발**:
+  - `env("SD_DEBUG")` truthy → `PrettyReporter()` 만 (debug 포함 콘솔).
+  - 그 외 → `createFileReporter()`(debug 포함 파일) + `PrettyReporter()`(info 이상만 콘솔, `withMaxLevel` 적용).
 
-### PrettyReporter
+`opts.cli`: CLI 프로세스(`sd-cli` 등) 여부. true 면 파일 출력 없이 콘솔만 사용하도록 분기.
+
+### withMaxLevel
 
 ```ts
-class PrettyReporter implements ConsolaReporter {}
+withMaxLevel(reporter: ConsolaReporter, maxLevel: number): 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 첨부.
+기존 reporter 를 감싸 `logObj.level > maxLevel` 인 항목을 버린다. consola `LogLevels` 는 낮을수록 심각(0=fatal/error, 1=warn, 2=log, 3=info, 4=debug, 5=trace).
 
-### createFileReporter
+### PrettyReporter
 
-```ts
-interface FileReporterOptions {
-  maxSize?: number;   // default 20MB
-  maxDays?: number;   // default 14
-}
-createFileReporter(options?: FileReporterOptions): ConsolaReporter;
-```
+`class PrettyReporter implements ConsolaReporter` — ANSI 컬러 콘솔 출력.
 
-- 출력 디렉토리: `<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` 정리.
+- 색상 활성화: `env("NO_COLOR")` 있으면 비활성, `env("FORCE_COLOR")` 있으면 강제, TTY 또는 win32 면 활성.
+- level<2 (fatal/error/warn) → `stderr`, 그 외 → `stdout`.
+- `type === "box"` → 박스 포맷, `type === "trace"` → 스택 첨부, level<2 또는 `badge: true` → 위아래 빈 줄.
+- `Error` args → message + cwd prefix 제거된 스택 + `cause` 재귀 indent.
+- `ctx.options.formatOptions.date: true` → 시각 `HH:mm:ss.SSS` 부착.
 
-### withMaxLevel
+### createFileReporter
 
 ```ts
-withMaxLevel(reporter: ConsolaReporter, maxLevel: number): ConsolaReporter;
+createFileReporter(options?: { maxSize?: number; maxDays?: number }): ConsolaReporter
 ```
 
-`logObj.level > maxLevel` 인 항목을 drop. `setupConsola` 가 dev 콘솔 리포터에 `LogLevels.info` 로 적용.
+- `maxSize` (기본 20MB): 파일 1개 최대 크기. 초과 시 `app.<YYYY-MM-DD>.<seq>.log` 시퀀스로 회전.
+- `maxDays` (기본 14): cutoff 일자 이전 로그 파일 자동 삭제. 매일 첫 로그 시 1회 실행.
+- 출력 위치: `${process.cwd()}/.logs/app.<YYYY-MM-DD>.log` (필요시 `.<seq>` 부착).
+- 라인 형식: `{ time, level, tag?, err?: {message,stack}, msg? }` JSONL. `Error` arg 는 `err` 필드로 분리, 나머지는 `msg` 로 공백 연결.
+- 날짜 바뀌면 자동 로테이트. `.logs` 디렉토리는 첫 쓰기 시 생성.
 
-### 사용 예
+### 예
 
 ```ts
-import { setupConsola } from "@simplysm/core-node";
+import { setupConsola, PrettyReporter, createFileReporter } from "@simplysm/core-node";
+import consola from "consola";
+setupConsola({ cli: true });
 
-setupConsola({ cli: true });   // 진입점 1회
-consola.info("server started");
-consola.withTag("db").debug({ sql, params });
+// 커스텀
+consola.options.reporters = [new PrettyReporter(), createFileReporter({ maxDays: 30 })];
 ```

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

@@ -1,52 +1,44 @@
 ## @simplysm/core-node — cpx
 
-`import { cpx } from "@simplysm/core-node"` — 자식 프로세스 spawn + 시스템 인코딩 감지. Windows `chcp` 코드 페이지 또는 POSIX `LANG/LC_ALL` 의 charset 부분을 보고 stdout/stderr 를 적절히 디코딩.
+`import { cpx } from "@simplysm/core-node"`. 자식 프로세스 spawn 래퍼. stdout/stderr 를 시스템 인코딩으로 자동 디코딩, 실패 시 stderr 포함 에러 throw.
 
 ### 인코딩 감지
 
-```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.
+- `getSystemEncoding(): string` — Windows 는 `chcp` 결과 코드 페이지를, POSIX 는 `LANG`/`LC_ALL` 의 `.<enc>` 부분을 파싱. 실패 시 `"utf-8"`. **결과는 모듈 캐시**.
+- `resetEncodingCache(): void` — 캐시 초기화. 환경 변경 후 강제 재감지 시.
+- `codePageToEncoding(codePage): string` — Windows 코드 페이지 번호→IANA 인코딩명(65001/949/932/936/950/1252/1251/1250/874 지원, 그 외 `"utf-8"`).
+- `decodeBytes(raw: Uint8Array, systemEncoding?: string): string` — UTF-8 fatal decode 시도 → 실패 시 지정 인코딩으로 fallback.
 
-### 디코딩
+### spawn
 
 ```ts
-cpx.decodeBytes(raw: Uint8Array, systemEncoding?: string): string
-// utf-8 이면 바로 디코딩.
-// 그 외 인코딩이면 먼저 utf-8 strict 시도 → 실패 시 systemEncoding 으로 fallback.
+spawn(cmd, args, options?): SpawnProcess
+spawnSync(cmd, args, options?): SpawnResult
 ```
 
-### spawn / spawnSync
+- `options`: Node `SpawnOptions`/`SpawnSyncOptions` + `reject?: boolean`.
+  - `stdio` 기본 `"pipe"`. pipe 인 스트림만 캡처되며 비-pipe 스트림은 결과 문자열이 빈 문자열.
+  - `env`: `process.env` 와 병합되어 자식에 전달.
+  - `reject` (기본 `true`): exitCode≠0 일 때 `false` 면 결과 객체 반환, `true` 면 throw. 에러 메시지는 `Command failed (exit N): <cmd> <args>` + stderr/stdout 마지막 4000자.
+- `SpawnResult`: `{ stdout: string; stderr: string; exitCode: number }`. 종료 코드가 없고 시그널만 있으면 exitCode=1.
 
-```ts
-interface SpawnResult { stdout: string; stderr: string; exitCode: number; }
+### SpawnProcess
 
-cpx.spawn(cmd, args, opts?: SpawnOptions & { reject?: boolean }): SpawnProcess
-cpx.spawnSync(cmd, args, opts?: SpawnSyncOptions & { reject?: boolean }): SpawnResult
-```
+`spawn()` 반환값. `PromiseLike<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?)`).
+- `pid: number | undefined` — 자식 PID.
+- `then / catch` — `SpawnResult` resolve 또는 에러 reject.
+- `kill(signal?): boolean` — 자식 프로세스에 시그널 전송.
 
-```ts
-const r = await cpx.spawn("git", ["status", "--porcelain"]);
-console.log(r.stdout);
+### resolveStdioPipe
 
-const proc = cpx.spawn("pnpm", ["watch"], { reject: false });
-process.on("SIGINT", () => proc.kill());
-const { exitCode } = await proc;
-```
+- `resolveStdioPipe(stdio): { stdout: boolean; stderr: boolean }` — `SpawnOptions["stdio"]` 가 각 스트림에 대해 pipe 인지 판정. 배열·`"pipe"`·`undefined` 모두 처리.
 
-### resolveStdioPipe
+### 예
 
 ```ts
-cpx.resolveStdioPipe(stdio): { stdout: boolean; stderr: boolean }
+import { cpx } from "@simplysm/core-node";
+const { stdout } = await cpx.spawn("git", ["rev-parse", "HEAD"]);
+const proc = cpx.spawn("node", ["server.js"], { reject: false });
+proc.kill("SIGTERM");
 ```
-
-stdio 값(`"pipe"`, `"inherit"`, 배열, `undefined`)에서 stdout/stderr 각각 pipe 여부 판정. spawn 자체가 내부 사용하므로 사용자 호출 거의 없음.

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

@@ -1,53 +1,42 @@
 ## @simplysm/core-node — FsWatcher
 
-chokidar 래퍼. 짧은 시간 내 이벤트를 병합해서 콜백 1회만 호출하고, Windows 의 EPERM (감시 디렉토리 사라짐 등) 발생 시 watcher 자동 재시작. 모듈 로드 시 `fs.FSWatcher.prototype.emit` 을 한 번 패치해서, listener 없는 인스턴스의 orphan `error` 이벤트로 인한 uncaughtException 도 swallow.
+Chokidar 기반 디렉토리/글로브 변경 감시. 짧은 시간 내 이벤트를 병합하여 콜백 1회로 묶고, Windows EPERM 시 자동 재시작.
 
-### 시그니처
+### 타입
 
-```ts
-type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir";
+- `FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir"` — chokidar 원본 이벤트 그대로. 디렉토리/파일 add·unlink 구분.
+- `FsWatcherChangeInfo = { event: FsWatcherEvent; path: PosixPath }` — 콜백 인자 1건. `path` 는 POSIX 슬래시 정규화.
+
+### 생성
 
-interface FsWatcherChangeInfo {
-  event: FsWatcherEvent;
-  path: PosixPath;          // 항상 슬래시 경로
-}
+```ts
+FsWatcher.watch(paths: string[], options?: ChokidarOptions): Promise<FsWatcher>
+```
 
-class FsWatcher {
-  static watch(paths: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher>;
+- `paths`: 감시 대상. 디렉토리 절대 경로 또는 glob 패턴 혼용 가능. glob 메타문자 이전까지를 실제 감시 base 로 추출 후 chokidar 에 전달.
+- `options`: chokidar `ChokidarOptions`. `ignoreInitial` 은 내부적으로 항상 `true` 로 override 되지만, 사용자가 `false` 로 명시한 경우 첫 `onChange` 콜백을 **빈 배열**로 1회 호출(초기 트리거 신호용, 실제 초기 목록은 X).
+- `ready` 대기 후 resolve. 초기화 에러 시 close 후 reject.
 
-  onChange(
-    opt: { delay?: number },
-    cb: (changes: FsWatcherChangeInfo[]) => void | Promise<void>,
-  ): this;
+### 메서드
 
-  close(): Promise<void>;
-}
-```
+- `onChange(opt: { delay?: number }, cb: (changes: FsWatcherChangeInfo[]) => void | Promise<void>): this`
+  - `opt.delay`: 디바운스 ms. 마지막 이벤트로부터 이 시간 후 콜백 1회.
+  - 같은 파일에 대한 연속 이벤트 자동 병합: `add+change=add`, `add+unlink`=상쇄(제외), `addDir+unlinkDir`=상쇄, `unlink+add=add`, `unlink+change=change`, `unlinkDir+addDir=addDir`. 룩업 미스는 현재 이벤트로 덮어쓰기.
+  - 콜백은 감시 base 가 아닌 **`paths` 원본 glob 에 매칭되는 경로만** 통과 (minimatch, dot 포함).
+  - 다중 호출 가능. 각 호출마다 독립 debounce 큐 + handler 등록.
+- `close(): Promise<void>` — debounce 큐 dispose + chokidar close.
 
-### 동작 디테일
+### 자동 복구
 
-- `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회 시도 후 포기 (에러 로그만).
+- 감시 디렉토리 소실로 EPERM 발생 시 최대 3회 / 1초 간격으로 watcher 재생성·핸들러 재등록. 성공 시 retry count 리셋, 초과 시 중단(error 로그).
+- native `fs.FSWatcher.prototype.emit` 를 모듈 로드 시 1회 패치: listener 0 + `error` 이벤트는 swallow (orphan error 로 인한 프로세스 종료 방지).
 
-### 사용 예
+### 예
 
 ```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}`);
-  }
+const w = await FsWatcher.watch(["src/**/*.ts"]);
+w.onChange({ delay: 300 }, async (changes) => {
+  for (const { path, event } of changes) console.log(event, path);
 });
-
-// 종료
-await watcher.close();
+// await w.close();
 ```