@simplysm/sd-claude 14.0.88 → 14.0.89

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

@@ -1,86 +1,72 @@
 # @simplysm/core-node — fsx
 
-`import { fsx } from "@simplysm/core-node"`. Node `fs` 래퍼 네임스페이스. 대부분 함수는 동기(`...Sync`)와 비동기(Promise) 쌍으로 제공된다. IO 실패 시 `SdError(err, targetPath)` 로 경로를 포함해 throw 하고, 쓰기 계열은 상위 디렉토리를 자동 생성한다.
+`export * as fsx` 네임스페이스 (`packages/core-node/src/utils/fs.ts`). Node `fs` 를 감싼 파일시스템 IO. 대부분 동기(`...Sync`)/비동기 쌍을 제공하며, 실패 시 모두 `SdError(err, targetPath)` 로 원인+경로를 붙여 throw 한다. 항상 `fsx.<fn>(...)` 형태로 호출.
 
 ## 존재 확인
 
-- `existsSync(targetPath: string): boolean` / `exists(targetPath: string): Promise<boolean>` — 파일/디렉토리 존재 여부. 비동기는 `fs.access` 실패를 throw 하지 않고 false 로 반환. 파일·디렉토리 구분은 없음.
+- `existsSync(targetPath: string): boolean` / `exists(targetPath: string): Promise<boolean>` — 파일/디렉토리 존재 여부. 비동기 버전은 `fs.access` 실패를 catch 해 false 반환(throw 안 함).
 
 ## 디렉토리 생성
 
-- `mkdirSync(targetPath: string): void` / `mkdir(targetPath: string): Promise<void>` — `recursive: true` 재귀 생성. 이미 존재하면 무시.
-
-```ts
-await fsx.mkdir("dist/sub");
-```
+- `mkdirSync(targetPath: string): void` / `mkdir(targetPath: string): Promise<void>` — 재귀 생성(`recursive: true`). 중간 경로가 없어도 전부 만든다.
 
 ## 삭제
 
-- `rmSync(targetPath: string): void` — 재귀·force 삭제, **재시도 없이 즉시 실패**. 파일 잠금 우려가 있으면 비동기 `rm` 사용.
-- `rm(targetPath: string): Promise<void>` — 재귀·force 삭제, 일시 오류 시 500ms 간격 최대 6회 재시도(Windows 잠금 대응).
+- `rmSync(targetPath: string): void` — 재귀+force 삭제. **재시도 없이 즉시 실패**. 파일 잠금 등 일시 오류가 예상되면 비동기 `rm` 을 쓸 것.
+- `rm(targetPath: string): Promise<void>` — 재귀+force 삭제. 일시 오류에 대해 **500ms 간격 최대 6회 재시도**(`retryDelay: 500, maxRetries: 6`).
 
 ## 복사
 
-- `copySync(sourcePath: string, targetPath: string, filter?): void` / `copy(...): Promise<void>` — 파일·디렉토리 재귀 복사. **source 미존재 시 아무 작업 없이 반환**. 파일 복사는 실패 시 500ms 간격 최대 7회(0~6) 재시도. 비동기는 디렉토리 하위를 `parallelAsync` 병렬 복사.
-  - `filter?: (absolutePath: string) => boolean` — 하위 항목마다 **절대 경로**로 호출, true 만 복사. 최상위 source 자신은 필터 대상 아님. 디렉토리에 false 면 그 디렉토리와 모든 하위를 건너뜀. 특정 확장자·폴더만 복사할 때 사용.
+- `copySync(sourcePath, targetPath, filter?): void` / `copy(sourcePath, targetPath, filter?): Promise<void>` — 파일/디렉토리 복사. async 는 하위 항목을 `parallelAsync` 로 병렬 복사.
+  - `sourcePath: string` — 원본. **존재하지 않으면 아무 것도 안 하고 반환**(throw 안 함).
+  - `targetPath: string` — 대상. 디렉토리면 대상 디렉토리를 만들고 하위를 재귀 복사, 파일이면 상위 디렉토리 생성 후 복사.
+  - `filter?: (absolutePath: string) => boolean` — 복사 여부 결정. 각 하위 항목의 **절대 경로**가 전달되며 true=복사, false=제외. **최상위 sourcePath 자신은 필터 대상 아님**. 디렉토리에 false 면 그 디렉토리와 모든 내용을 건너뜀. 빌드 산출물 중 특정 파일만 복사할 때 사용.
+  - 파일 복사 실패 시 500ms busy-wait(sync)/setTimeout(async) 으로 최대 7회 시도 후 실패하면 `SdError` throw.
 
-```ts
-await fsx.copy("src", "dist", (p) => !p.endsWith(".map"));
-```
-
-## 파일 읽기
-
-- `readSync(targetPath: string): string` / `read(...): Promise<string>` — UTF-8 문자열로 읽기.
-- `readBytesSync(targetPath: string): Uint8Array` / `readBytes(...): Promise<Uint8Array>` — 바이너리로 읽기.
-- `readJsonSync<TData = unknown>(targetPath: string): TData` / `readJson<TData = unknown>(...): Promise<TData>` — `@simplysm/core-common` 의 `json.parse` 로 파싱(표준 `JSON` 아님 — Date 등 확장 타입 복원). 파싱 실패 시 경로 + 내용 500자 프리뷰를 포함해 throw.
-
-```ts
-const cfg = await fsx.readJson<{ version: string }>("package.json");
-```
+## 읽기
 
-## 파일 쓰기
+- `readSync(targetPath: string): string` / `read(...): Promise<string>` — UTF-8 문자열로 읽음.
+- `readBytesSync(targetPath: string): Uint8Array` / `readBytes(...): Promise<Uint8Array>` — 바이너리로 읽음.
+- `readJsonSync<TData = unknown>(targetPath): TData` / `readJson<TData = unknown>(...): Promise<TData>` — 읽어 `json.parse`(`@simplysm/core-common`, Date 등 특수타입 복원) 로 파싱. 파싱 실패 시 SdError 메시지에 내용 앞 500자 프리뷰를 첨부.
 
-- `writeSync(targetPath: string, data: string | Uint8Array): void` / `write(...): Promise<void>` — 상위 디렉토리 자동 생성 후 `flush: true` 로 기록(데이터 손실 방지 강제 플러시).
-- `writeJsonSync(targetPath: string, data: unknown, options?): void` / `writeJson(...): Promise<void>` — `json.stringify` 로 직렬화 후 기록.
-  - `options.replacer?: (this, key: string | undefined, value: unknown) => unknown` — 직렬화 시 값 변환 replacer.
-  - `options.space?: string | number` — 들여쓰기(가독 출력용).
+## 쓰기
 
-```ts
-await fsx.writeJson("out.json", data, { space: 2 });
-```
+- `writeSync(targetPath, data): void` / `write(targetPath, data): Promise<void>` — **상위 디렉토리 자동 생성** 후 기록(`flush: true`).
+  - `data: string | Uint8Array` — 텍스트 또는 바이너리.
+- `writeJsonSync(targetPath, data, options?): void` / `writeJson(targetPath, data, options?): Promise<void>` — `json.stringify` 로 직렬화 후 write.
+  - `data: unknown` — 직렬화 대상.
+  - `options?.replacer?: (this, key, value) => unknown` — JSON.stringify 의 replacer 와 동일 역할. 특정 키 값을 변환·제외할 때.
+  - `options?.space?: string | number` — 들여쓰기. 사람이 읽을 파일이면 `2` 같은 값 지정.
 
 ## 디렉토리 읽기
 
-- `readdirSync(targetPath: string): string[]` / `readdir(...): Promise<string[]>` — 직속 항목 이름(상대 이름) 배열. 절대 경로 아님.
+- `readdirSync(targetPath: string): string[]` / `readdir(...): Promise<string[]>` — 디렉토리 직계 항목명(경로 아님) 배열.
 
 ## 파일 정보
 
-- `statSync(targetPath: string): fs.Stats` / `stat(...): Promise<fs.Stats>` — 심볼릭 링크를 따라간 stat.
-- `lstatSync(targetPath: string): fs.Stats` / `lstat(...): Promise<fs.Stats>` — 링크 자체의 stat(링크 비추적). 링크 여부 판별·복사 분기에 사용.
+- `statSync(targetPath): fs.Stats` / `stat(...): Promise<fs.Stats>` — 정보 조회. **심볼릭 링크를 따라감**(링크 대상의 정보).
+- `lstatSync(targetPath): fs.Stats` / `lstat(...): Promise<fs.Stats>` — 정보 조회. **심볼릭 링크를 따라가지 않음**(링크 자체 정보). 링크/실파일을 구분해야 하면 lstat.
 
 ## Glob
 
-- `globSync(pattern: string, options?: GlobOptions): string[]` / `glob(...): Promise<string[]>` — glob 매칭. 입력 패턴의 `\` 를 `/` 로 치환하고, 결과는 `path.resolve` 한 **절대 경로** 배열.
-  - `options?: GlobOptions` — `glob` 라이브러리 옵션(`dot`, `ignore`, `nodir` 등).
-
-```ts
-const files = await fsx.glob("src/**/*.ts", { ignore: ["**/*.d.ts"] });
-```
+- `globSync(pattern: string, options?: GlobOptions): string[]` / `glob(...): Promise<string[]>` — glob 검색. 입력 패턴의 `\` 를 `/` 로 치환해 매칭하고, 결과는 모두 `path.resolve` 로 **절대 경로**화해 반환.
+  - `pattern: string` — glob 패턴(예: `"src/**/*.ts"`).
+  - `options?: GlobOptions` — `glob` 패키지 옵션 그대로(`dot`, `cwd`, `ignore` 등). 숨김 파일 포함하려면 `{ dot: true }`.
 
 ## 유틸리티
 
-- `clearEmptyDirectory(dirPath: string): Promise<void>` — 하위를 재귀 순회해 파일이 하나도 없는 빈 디렉토리를 삭제(하위 삭제로 비게 된 상위도 삭제). 미존재 시 무시.
-- `findAllParentChildPathsSync(childGlob: string, fromPath: string, rootPath?: string): string[]` / `findAllParentChildPaths(...): Promise<string[]>` — fromPath 에서 루트 방향으로 부모 디렉토리를 순회하며 각 디렉토리에서 `childGlob` 매칭 파일을 수집(절대 경로). `tsconfig.json` 등 설정 파일 상향 탐색에 사용.
-  - `childGlob` — 각 디렉토리에서 검색할 glob 패턴.
-  - `fromPath` — 탐색 시작 경로.
-  - `rootPath?` — 탐색 중단 경로. 미지정이거나 fromPath 가 rootPath 하위가 아니면 파일시스템 루트까지 올라감.
+- `clearEmptyDirectory(dirPath: string): Promise<void>` — `dirPath` 하위를 재귀 순회하며 **빈 디렉토리만** 삭제. 하위가 모두 비어 상위도 비게 되면 상위도 삭제. 파일이 하나라도 있으면 그 디렉토리는 보존. 존재하지 않으면 즉시 반환.
+- `findAllParentChildPathsSync(childGlob, fromPath, rootPath?): string[]` / `findAllParentChildPaths(...): Promise<string[]>` — `fromPath` 에서 루트 방향으로 부모 디렉토리를 거슬러 올라가며 각 디렉토리에서 `childGlob` 매칭 파일을 모아 평탄화 반환. 상위 디렉토리의 설정 파일(예: 각 단계 `package.json`) 수집에 사용.
+  - `childGlob: string` — 각 디렉토리에서 검색할 glob.
+  - `fromPath: string` — 탐색 시작 경로.
+  - `rootPath?: string` — 탐색 중단 경로. 생략 시 파일시스템 루트까지. **주의: fromPath 는 rootPath 의 하위여야 함**, 아니면 루트까지 올라간다.
+
+## 사용 예
 
 ```ts
-const tsconfigs = await fsx.findAllParentChildPaths("tsconfig.json", srcDir, projectRoot);
+import { fsx } from "@simplysm/core-node";
+await fsx.writeJson("dist/meta.json", { builtAt: new Date() }, { space: 2 });
+await fsx.copy("src", "dist", (p) => !p.endsWith(".ts")); // .ts 제외 복사
+const pkgs = await fsx.findAllParentChildPaths("package.json", process.cwd());
 ```
-
-## 주의사항
-
-- 동기 `rmSync`/`copySync` 는 재시도 동작이 비동기와 다름(rmSync 는 무재시도). Windows EPERM/잠금이 우려되면 비동기 버전 사용.
-- glob 결과는 항상 절대 경로 — 상대 경로가 필요하면 호출 측에서 `path.relative` 처리.
-- JSON IO 는 표준 `JSON` 이 아닌 `@simplysm/core-common` 의 `json` 사용 — Date 등 확장 타입 복원이 다름.
+</content>

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

@@ -1,42 +1,39 @@
 # @simplysm/core-node — pathx
 
-`import { pathx } from "@simplysm/core-node"`. 경로 정규화·판정·치환 유틸 네임스페이스. 내부 비교는 항상 POSIX 슬래시 기준이다.
+`export * as pathx` 네임스페이스 (`packages/core-node/src/utils/path.ts`). 경로 문자열 가공·판정 유틸. OS 무관 비교를 위해 POSIX 슬래시(`/`)로 정규화하는 것이 핵심. `pathx.<fn>(...)` 형태로 호출.
 
-## PosixPath 생성
+## PosixPath (브랜드 타입)
 
-- `posix(p: string): PosixPath` — `\` → `/` 치환만 수행(resolve·결합 안 함). 반환은 브랜드 타입 `PosixPath`.
-- `posixResolve(...args: string[]): PosixPath` — `path.resolve` 로 절대 경로화한 뒤 슬래시 치환. 상대 입력은 cwd 기준으로 절대화.
-- `PosixPath` — `string & { [POSIX]: never }` 브랜드 타입. `posix`/`posixResolve` 로만 생성 가능. POSIX 슬래시 경로임을 타입으로 보장할 때 쓰임(예: `FsWatcherChangeInfo.path`).
+- `type PosixPath = string & { [POSIX]: never }` — POSIX 슬래시 경로임을 나타내는 브랜드 타입. `posix()`/`posixResolve()` 로만 생성 가능. 일반 `string` 을 PosixPath 자리에 직접 넣을 수 없어, 정규화를 강제하는 타입 가드 역할.
 
-```ts
-pathx.posix("C:\\a\\b");        // "C:/a/b"
-pathx.posixResolve("a", "b");   // "<cwd>/a/b"
-```
+## 정규화
 
-## 판정·치환
+- `posix(p: string): PosixPath` — 백슬래시 → 슬래시 치환만 수행. **결합·resolve 안 함**. 예: `posix("C:\\Users\\test")` → `"C:/Users/test"`. 이미 절대 경로인 문자열을 POSIX 표기로만 바꿀 때.
+- `posixResolve(...args: string[]): PosixPath` — 인자들을 `path.resolve` 로 절대 경로 결합 후 슬래시로 변환. 예: `posixResolve("/base", "sub", "f.txt")` → `"/base/sub/f.txt"`, 상대경로 단독이면 cwd 기준 절대화. 경로 결합+정규화를 동시에 할 때.
 
-- `isChildPath(childPath: string, parentPath: string): boolean` — child 가 parent 의 하위인지. **동일 경로는 false**. 내부적으로 양쪽을 `posixResolve` 정규화 후 `parent + "/"` 접두 비교.
-- `changeFileDirectory(filePath: string, fromDirectory: string, toDirectory: string): string` — filePath 의 소속 디렉토리를 from→to 로 교체. `filePath === fromDirectory` 면 toDirectory 반환. from 하위가 아니면 `ArgumentError` throw. 빌드 출력 경로 산출에 사용.
-- `basenameWithoutExt(filePath: string): string` — 마지막 확장자만 제거한 basename. `file.spec.ts` → `file.spec`.
+## 경로 가공
 
-```ts
-pathx.isChildPath("/a/b/c", "/a/b");                     // true
-pathx.changeFileDirectory("/src/x.ts", "/src", "/dist"); // "/dist/x.ts"
-```
+- `changeFileDirectory(filePath, fromDirectory, toDirectory): string` — `filePath` 의 디렉토리 prefix 를 `fromDirectory` → `toDirectory` 로 치환(상대 위치 유지). 예: `("/a/b/c.txt", "/a", "/x")` → `"/x/b/c.txt"`. `filePath === fromDirectory` 면 `toDirectory` 반환. **filePath 가 fromDirectory 내부가 아니면 `ArgumentError` throw**. src→dist 같은 출력 경로 산출에 사용.
 
-## 타겟 필터링
+## 판정·필터링
 
-- `filterByTargets(files: string[], targets: string[], cwd: string): string[]` — files 중 targets 경로와 일치하거나 그 하위인 것만 반환.
-  - `files` — 필터링할 파일 경로. cwd 하위 절대 경로 권장(cwd 외부 경로는 `../` 상대로 변환되어 매칭이 어려움).
-  - `targets` — cwd 기준 상대 경로(POSIX 슬래시 권장). **빈 배열이면 files 를 그대로 반환**("필터 없음" 의미).
-  - `cwd` — 절대 기준 디렉토리. files 의 cwd 상대 경로를 만들어 target 과 비교.
+- `isChildPath(childPath, parentPath): boolean` — `childPath` 가 `parentPath` 의 하위인지. 양쪽을 `posixResolve` 로 정규화 후 비교. **동일 경로면 false**(자기 자신은 하위 아님). 경계 오탐 방지를 위해 parent 끝에 `/` 를 붙여 비교.
+- `filterByTargets(files, targets, cwd): string[]` — 파일 목록을 타겟 경로 하위만 남김.
+  - `files: string[]` — 필터링할 파일. **cwd 하위 절대 경로여야 함**(외부 경로는 `../` 상대경로로 변환되어 매칭 실패 가능).
+  - `targets: string[]` — 대상 경로(cwd 기준 상대, POSIX 권장). 각 파일의 cwd-상대경로가 target 과 같거나 `target + "/"` 로 시작하면 통과.
+  - `cwd: string` — 기준 작업 디렉토리(절대 경로).
+  - **`targets` 가 비면 `files` 를 그대로 반환**(필터 미적용). CLI 의 `-t <패키지>` 같은 부분 빌드 대상 한정에 사용.
 
-```ts
-pathx.filterByTargets(["/p/src/a.ts", "/p/tests/c.ts"], ["src"], "/p");
-// → ["/p/src/a.ts"]
-```
+## 파일명
+
+- `basenameWithoutExt(filePath: string): string` — 확장자 1단계만 제거한 basename. 예: `"file.txt"` → `"file"`, `"a/file.spec.ts"` → `"file.spec"`(마지막 확장자만 제거).
 
-## 주의사항
+## 사용 예
 
-- `filterByTargets` 의 `targets` 가 비면 전체 통과 — 빈 결과를 기대하지 말 것.
-- `changeFileDirectory` 는 범위 밖 입력을 silent 처리하지 않고 throw 하므로, 호출 전 `isChildPath` 로 보장하거나 throw 를 처리.
+```ts
+import { pathx } from "@simplysm/core-node";
+const out = pathx.changeFileDirectory(srcFile, "/proj/src", "/proj/dist");
+if (pathx.isChildPath(out, "/proj")) { /* ... */ }
+const targeted = pathx.filterByTargets(allFiles, ["src", "tests"], process.cwd());
+```
+</content>

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

@@ -1,54 +1,52 @@
-# @simplysm/core-node — Worker
+# @simplysm/core-node — worker
 
-worker_threads 를 타입 안전 RPC + 이벤트로 감싼다. 워커 파일은 `createWorker` 로 메서드 묶음을 `export default` 하고, 메인은 `Worker.create<typeof import("...")>()` 로 프록시를 만들어 메서드를 직접 호출한다. 인자/반환은 `@simplysm/core-common` 의 `transfer`(structured clone + transferList)로 직렬화된다.
+`worker_threads` 를 타입 안전하게 쓰기 위한 래퍼. 워커 파일에서 `createWorker(methods)` 로 메서드 묶음을 export 하고, 메인에서 `Worker.create<typeof import("./worker")>(path)` 로 프록시를 만들어 `await worker.method(...)` 처럼 호출. 메시지 직렬화는 `@simplysm/core-common` 의 `transfer`(Date/특수타입·transferList 지원)를 사용한다. 개발(.ts)·프로덕션(.js) 양쪽을 자동 분기한다.
 
-## createWorker (워커 측)
+## createWorker (워커 스레드 측)
 
-- `createWorker<TMethods, TEvents>(methods: TMethods): { send; __methods; __events }` — 워커 스레드 내에서 메서드 핸들러를 등록. 반환값을 `export default` 한다. `parentPort` 가 없으면(메인에서 직접 실행) `SdError` throw.
-  - `methods: Record<string, (...args: any[]) => unknown>` — RPC 로 노출할 메서드. 반환은 동기/Promise 무관(메인에선 항상 Promise). 핸들러 throw 는 메인 호출에서 reject 로 전파.
-  - `TEvents extends Record<string, unknown>` — 워커→메인 이벤트 페이로드 타입 맵(선택, 기본은 이벤트 없음).
-  - `send<TEventName extends keyof TEvents & string>(event, data?): void` — 워커→메인 이벤트 전송.
-  - `__methods` / `__events` — 타입 추론 전용 필드(런타임 의미 없음). 메인의 `Worker.create` 가 시그니처를 끌어올 때 사용.
-- 워커의 `process.stdout.write` 는 내부에서 가로채져 메시지 프로토콜로 메인의 stdout 에 전달됨(워커 로그가 메인 콘솔에 보임).
+- `createWorker<TMethods, TEvents>(methods): { send; __methods; __events }` — 워커 스레드 진입 파일에서 호출하고 그 반환을 `export default`. `parentPort` 가 없으면(워커 컨텍스트 아님) `SdError` throw. 메서드 호출 메시지를 수신해 실행 후 결과/에러를 응답하고, 워커의 `process.stdout.write` 를 가로채 메인으로 로그를 전달한다.
+  - `methods: TMethods` (`Record<string, (...args) => unknown>`) — 워커가 제공할 메서드 맵. 동기/비동기 모두 가능(await 됨). 알 수 없는 메서드 호출 시 `SdError("알 수 없는 메서드: ...")` 응답.
+  - 제네릭 `TEvents extends Record<string, unknown>` — 워커가 보낼 이벤트명→데이터 타입 맵(메인의 `on` 타입 추론에 사용).
+  - 반환 `send<K extends keyof TEvents & string>(event, data?)` — 워커→메인 이벤트 전송. 진행률 등 메서드 반환과 별개 통지에 사용.
+  - 반환 `__methods`/`__events` — 타입 추론용 마커(런타임에 `Worker.create` 가 직접 쓰진 않음, 타입에서만 참조).
 
 ```ts
 // worker.ts
-interface Events { progress: number }
+interface MyEvents { progress: number; }
 const methods = {
   calc: (x: number) => { sender.send("progress", 50); return x * 2; },
 };
-const sender = createWorker<typeof methods, Events>(methods);
+const sender = createWorker<typeof methods, MyEvents>(methods);
 export default sender;
 ```
 
 ## Worker.create (메인 측)
 
-- `Worker.create<TModule extends WorkerModule>(filePath: string, opt?): WorkerProxy<TModule>` — 워커를 띄우고 프록시 반환. `.ts` 경로면 `lib/worker-dev-proxy.js`(tsx) 경유 로드, `.js` 면 직접 로드. `file://` URL / 절대 경로 모두 허용.
-  - `filePath` — 워커 파일 경로.
-  - `opt?: Omit<WorkerRawOptions, "stdout" | "stderr">` — `worker_threads` `WorkerOptions`(단 `stdout`/`stderr` 제외 — 내부에서 항상 캡처해 파이프). `opt.env` 는 `process.env` 위에 머지, `opt.argv` 는 워커 인자.
-- `WorkerProxy<TModule>` — 프록시 형태:
-  - 각 메서드 — `(...args) => Promise<Awaited<R>>`. 호출하면 RPC. 워커 핸들러 에러는 reject.
-  - `on(event, listener)` / `off(event, listener)` — 워커 `send` 이벤트 구독/해제.
-  - `terminate(): Promise<void>` — 워커 종료. 대기 중 요청은 reject.
+- `Worker.create<TModule extends WorkerModule>(filePath, opt?): WorkerProxy<TModule>` — 워커 스레드를 띄우고 메서드 프록시를 반환. 메서드 호출은 메시지로 전달되어 결과가 Promise 로 resolve/reject 된다. 워커 stdout/stderr 는 메인 프로세스로 파이프되며, 워커 비정상 종료(exit code≠0)·error 시 대기 중인 모든 호출이 reject 된다. 로거 태그 `sd-worker`.
+  - `filePath: string` — 워커 파일 경로. `file://` URL 또는 절대 경로. 확장자가 `.ts` 면 dev 모드로 `lib/worker-dev-proxy.js`(tsx 로 TS 동적 로드)를 통해 실행, `.js` 면 직접 실행.
+  - `opt?: Omit<WorkerRawOptions, "stdout" | "stderr">` — worker_threads 옵션(stdout/stderr 는 내부 고정이라 제외). `env` 는 `process.env` 와 병합 전달, `argv` 는 dev 모드에서 워커 경로 뒤에 이어 붙음.
+  - 반환 `WorkerProxy<TModule>` — 아래.
 
 ```ts
 // main.ts
 const worker = Worker.create<typeof import("./worker")>("./worker.ts");
 worker.on("progress", (p) => console.log(p));
-const r = await worker.calc(21); // 42
+const result = await worker.calc(10); // 20
 await worker.terminate();
 ```
 
-## 타입
+## WorkerProxy
+
+`Worker.create` 반환 프록시. 워커 메서드 + 예약 메서드 3종을 제공.
 
-- `WorkerModule` — `{ default: { __methods; __events } }`. `Worker.create` 의 `TModule` 제약. `typeof import("./worker")` 로 충족.
-- `PromisifyMethods<TMethods>` — 각 메서드 반환을 `Promise<Awaited<R>>` 로 매핑(워커 호출은 항상 비동기).
-- `WorkerProxy<TModule>` — 위 프록시 타입(promise화 메서드 + on/off + terminate).
-- `WorkerRequest` — `{ id; method; params }` 내부 요청 메시지.
-- `WorkerResponse` — 내부 응답 유니온: `return`(반환값) / `error`(Error) / `event`(send 이벤트) / `log`(stdout 전달).
+- 메서드 프록시: `TModule["default"]["__methods"]` 의 각 메서드가 `(...args) => Promise<Awaited<R>>` 로 노출(`PromisifyMethods`). 동기 메서드도 항상 Promise(postMessage 기반).
+- `on<TEventName>(event, listener): void` — 워커 `send` 이벤트 구독. `event`/`listener` 타입은 `TEvents` 에서 추론.
+- `off<TEventName>(event, listener): void` — 이벤트 구독 해제.
+- `terminate(): Promise<void>` — 워커 종료. 대기 중 호출은 "워커가 종료되었습니다" 로 reject 후 스레드 종료.
 
-## 주의사항
+## 타입
 
-- 비정상 종료(exit code≠0)·워커 error 시 대기 중 모든 요청이 reject 되고 error 로깅됨 — silent 무시 아님.
-- 워커 메서드는 항상 Promise 반환 — 동기 시그니처여도 메인에선 `await` 필요.
-- 인자/반환은 transfer 직렬화 가능한 값이어야 함(함수·일부 클래스 인스턴스 제약).
+- `interface WorkerModule { default: { __methods: Record<string, (...args) => unknown>; __events: Record<string, unknown> } }` — `Worker.create` 의 제네릭 제약. `typeof import("./worker")` 가 이 구조를 만족(=`createWorker` 반환을 default export).
+- `type PromisifyMethods<TMethods>` — 각 메서드 반환을 `Promise<Awaited<R>>` 로 바꾸는 매핑 타입.
+- `type WorkerProxy<TModule>` — 위 프록시 타입.
+- `interface WorkerRequest { id; method; params }` / `type WorkerResponse` — 내부 메시지 프로토콜 타입(`return`/`error`/`event`/`log`). 직접 다룰 일은 거의 없음.

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

@@ -1,35 +1,35 @@
 # @simplysm/excel
 
-OOXML(.xlsx) 워크북을 ZIP 단위 lazy-load 로 읽고 쓰는 라이브러리. 대용량 파일에서도 접근한 셀에 필요한 XML 파트만 로드한다(모든 셀 메서드가 `async` 인 이유). 워크북 생성·시트 추가·셀 값/스타일·조건부 서식·이미지 삽입·Zod 스키마 기반 레코드 매핑을 제공한다.
+OOXML(.xlsx) 워크북을 ZIP 단위 lazy-load 로 읽고 쓰는 라이브러리. 대용량 파일에서도 접근한 셀에 필요한 XML 파트(SharedStrings/Styles 등)만 그때그때 로드한다(모든 셀 메서드가 `async` 인 이유). `ExcelWorkbook` 진입점에서 시트 추가·셀 값/수식·스타일·조건부 서식·이미지·행 복사를 다루며, Zod 스키마 기반 `ExcelWrapper` 로 레코드 배열 ↔ 엑셀 변환도 지원한다.
 
 ## 사용 트리거 인덱스
 
-- **ExcelWorkbook / ExcelWorksheet** — .xlsx 파일을 열거나 새로 만들고 시트를 다루며 바이트로 내보낼 때. 시트 단위 데이터 테이블·매트릭스·이미지·뷰(zoom/freeze) 처리 포함. 자세히: [workbook-worksheet.md](./workbook-worksheet.md)
-- **ExcelCell / ExcelRow / ExcelCol** — 개별 셀의 값·수식·병합·스타일을 읽고 쓰거나 행/열 단위로 셀을 순회할 때. 자세히: [cell.md](./cell.md)
-- **셀 스타일 (ExcelStyleOptions / ExcelFont)** — 셀 또는 워크북 default 의 배경·테두리·정렬·숫자형식·폰트를 지정할 때. 자세히: [style.md](./style.md)
+- **ExcelWorkbook / ExcelWorksheet** — .xlsx 파일을 열거나 새로 만들고 시트를 다루며 바이트/Blob 로 내보낼 때. 시트 단위 데이터 테이블·매트릭스·행 복사·이미지·뷰(zoom/freeze/탭색) 처리 포함. 자세히: [workbook-worksheet.md](./workbook-worksheet.md)
+- **ExcelCell / ExcelRow / ExcelCol** — 개별 셀의 값·수식·병합·스타일을 읽고 쓰거나 행/열 단위로 셀을 순회하고 열 너비를 줄 때. 자세히: [cell.md](./cell.md)
+- **셀 스타일 (ExcelStyleOptions / ExcelFont)** — 셀(`cell.setStyle`) 또는 워크북 default(`wb.setDefaultStyle`)의 배경·테두리·정렬·숫자형식·폰트를 지정할 때. 자세히: [style.md](./style.md)
 - **조건부 서식 (ExcelConditionalRule / ExcelConditionalRuleStyle)** — 셀/범위에 값 비교·텍스트 매칭·수식 기반 native CF 규칙을 추가할 때. 자세히: [conditional-format.md](./conditional-format.md)
-- **ExcelWrapper** — Zod 스키마로 헤더 매핑·타입 변환·유효성 검사를 자동화해 레코드 배열 ↔ Excel 을 변환할 때. 자세히: [wrapper.md](./wrapper.md)
-- **ExcelUtils** — 셀 주소(A1 ↔ 좌표) 변환, Excel 날짜 시리얼 ↔ 타임스탬프 변환, 숫자형식 코드/ID/이름 상호 변환이 필요할 때. 자세히: [utils.md](./utils.md)
-- **값/주소/형식 타입** — 셀 값 유니온·숫자형식 프리셋·셀 타입·주소 좌표 타입을 시그니처에서 참조할 때. 아래 인라인 섹션 참조.
+- **ExcelWrapper** — Zod 스키마로 헤더 매핑·타입 변환·유효성 검사를 자동화해 레코드 배열 ↔ 엑셀을 변환할 때. 자세히: [wrapper.md](./wrapper.md)
+- **ExcelUtils** — 셀 주소(A1 ↔ 좌표) 변환, 엑셀 날짜 시리얼 ↔ 타임스탬프 변환, 숫자형식 코드/ID/이름 상호 변환이 필요할 때. 자세히: [utils.md](./utils.md)
+- **값/주소/형식 타입** — 셀 값 유니온·숫자형식 프리셋·셀 타입·주소 좌표·정렬/테두리 enum 을 시그니처에서 참조할 때. 아래 인라인 섹션 참조.
 - **OOXML XML-shape 타입** — `ExcelXml*` / `Excel*Data` 류. 라이브러리 내부 XML 파서/직렬화기가 쓰는 OOXML 노드 구조 타입. 아래 인라인 섹션 참조.
 
 ## 값/주소/형식 타입
 
 `./types` 가 노출하는 사용자 대면 타입. 셀 값을 다루거나 메서드 시그니처를 해석할 때 참조.
 
-- `ExcelValueType` = `number | string | DateOnly | DateTime | Time | boolean | undefined` — 셀이 가질 수 있는 값 유니온. `getValue()` 반환·`setValue()` 인자 타입. `undefined` = 빈 셀(읽기 시 값 없음, 쓰기 시 셀 삭제).
-- `ExcelNumberFormat` = `"number" | "string" | "DateOnly" | "DateTime" | "Time"` — 숫자형식 프리셋 이름. 셀의 numFmt 를 의미 단위로 분류한 값. `"number"` = 일반 수치, `"string"` = 텍스트 형식, 나머지는 날짜/시간 시리얼 해석에 사용.
-- `ExcelCellType` = `"s" | "b" | "str" | "n" | "inlineStr" | "e"` — OOXML 셀 `t` 속성. `"s"` = SharedString 인덱스 참조, `"b"` = boolean, `"str"` = 수식 결과 문자열, `"n"` = 숫자, `"inlineStr"` = 인라인 서식 텍스트, `"e"` = 에러(읽기 시 throw). 보통 직접 다루지 않고 `getValue`/`setValue` 가 자동 처리.
+- `ExcelValueType` = `number | string | DateOnly | DateTime | Time | boolean | undefined` — 셀이 가질 수 있는 값 유니온. `getValue()` 반환·`setValue()` 인자 타입. `undefined` = "값 없음"(읽기 시 빈 셀, 쓰기 시 셀 삭제)이므로 결측을 끝까지 보존. `DateOnly`/`DateTime`/`Time` 은 `@simplysm/core-common` 타입.
+- `ExcelNumberFormat` = `"number" | "string" | "DateOnly" | "DateTime" | "Time"` — 숫자형식 프리셋 이름. `"number"` = 일반 수치, `"string"` = 텍스트 형식, 나머지는 날짜/시간 시리얼 해석/표시에 사용. `ExcelStyleOptions.numberFormat` 와 `ExcelUtils` 변환의 공용 단위.
+- `ExcelCellType` = `"s" | "b" | "str" | "n" | "inlineStr" | "e"` — OOXML 셀 `t` 속성. `"s"` = SharedString 인덱스 참조, `"b"` = boolean(`"1"`/`"0"`), `"str"` = 수식 결과 문자열, `"n"` = 숫자, `"inlineStr"` = 인라인 서식 텍스트, `"e"` = 에러(읽기 시 throw). 보통 직접 다루지 않고 `getValue`/`setValue` 가 자동 매핑.
 - `ExcelAddressPoint` = `{ r: number; c: number }` — 0 기반 행(`r`)·열(`c`) 좌표. 셀 단일 위치 단위.
 - `ExcelAddressRangePoint` = `{ s: ExcelAddressPoint; e: ExcelAddressPoint }` — 범위 좌표. `s` = 시작(좌상단), `e` = 끝(우하단). `getRange()` 반환 타입.
 - `ExcelBorderPosition` = `"left" | "right" | "top" | "bottom"` — 테두리 적용 변. `ExcelStyleOptions.border` 배열 원소.
-- `ExcelHorizontalAlign` = `"center" | "left" | "right"` — 가로 정렬.
-- `ExcelVerticalAlign` = `"center" | "top" | "bottom"` — 세로 정렬.
+- `ExcelHorizontalAlign` = `"center" | "left" | "right"` — 가로 정렬 값.
+- `ExcelVerticalAlign` = `"center" | "top" | "bottom"` — 세로 정렬 값.
 - `ExcelFontUnderline` = `"single" | "double" | "singleAccounting" | "doubleAccounting"` — 밑줄 종류. OOXML `<u val="...">` 의 val 에 그대로 매핑.
 
 ## OOXML XML-shape 타입
 
-`./types` 가 함께 export 하는 다음 인터페이스·타입은 라이브러리 내부 XML 파서/직렬화기가 OOXML 파트의 파싱 결과(`xml2js` 스타일의 `$`=속성, 배열 래핑) 구조를 표현하는 데이터 모델이다. 일반 사용 흐름(값/스타일/시트 API)에서는 직접 다루지 않으며, OOXML 노드를 직접 조작·검증할 때만 참조한다.
+`./types` 가 함께 export 하는 다음 인터페이스·타입은 라이브러리 내부 XML 파서/직렬화기가 OOXML 파트의 파싱 결과(`xml2js` 스타일의 `$`=속성, 자식 배열 래핑)를 표현하는 데이터 모델이다. 일반 사용 흐름(값/스타일/시트 API)에서는 직접 다루지 않으며, OOXML 노드를 직접 조작·검증할 때만 참조한다.
 
 - `ExcelXmlContentTypeData` — `[Content_Types].xml` 의 `Types`(Default/Override 파트 등록) 구조.
 - `ExcelXmlRelationshipData` / `ExcelRelationshipData` — `*.rels` 의 `Relationships` 및 개별 `Relationship`(Id/Target/Type) 구조.
@@ -40,4 +40,4 @@ OOXML(.xlsx) 워크북을 ZIP 단위 lazy-load 로 읽고 쓰는 라이브러리
 - `ExcelXmlDrawingData` — `xl/drawings/drawingN.xml` 의 `wsDr`(twoCellAnchor/pic/blipFill/spPr 등 이미지 앵커) 구조.
 - `ExcelXmlSharedStringData` / `ExcelXmlSharedStringDataSi` / `ExcelXmlSharedStringDataText` — `xl/sharedStrings.xml` 의 `sst` 와 `si` 항목(단순 `t` 또는 서식 run `r[]`), 텍스트 노드(`space="preserve"` 보존) 구조.
 - `ExcelXmlStyleData` 및 하위(`...Font` / `...Fill` / `...Border` / `...Xf` / `...Dxf`) — `xl/styles.xml` 의 `styleSheet`(numFmts/fonts/fills/borders/cellXfs/dxfs) 와 각 자원 노드 구조.
-- `ExcelXml` = `{ readonly data: unknown; cleanup(): void }` — 모든 XML 파트 래퍼가 따르는 공통 인터페이스. `data` = 파싱된 노드 트리, `cleanup()` = 직렬화 전 마무리 정리.
+- `ExcelXml` = `{ readonly data: unknown; cleanup(): void }` — 모든 XML 파트 래퍼가 따르는 공통 인터페이스. `data` = 파싱된 노드 트리, `cleanup()` = 직렬화 전 마무리 정리. 외부에서 구현할 일은 거의 없다.

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

@@ -1,43 +1,49 @@
 # @simplysm/lint
 
-심플리즘 워크스페이스 전용 ESLint 플러그인. 커스텀 규칙 9종 묶음(`eslint-plugin`)과, 그 규칙들을 포함해 JS/TS/HTML 파일별로 완성된 flat config 배열(`eslint-recommended`)을 서브패스 export 로 제공. `src/index.ts` 없음 — `package.json` 의 `exports`(`./eslint-plugin`, `./eslint-recommended`)가 진입점.
+simplysm 전용 ESLint 9 flat-config 프리셋과 커스텀 규칙 9종을 제공하는 ESLint 플러그인 패키지. `src/index.ts` 없음 — `package.json` 의 `exports`(`./eslint-plugin`, `./eslint-recommended`) 두 subpath 가 진입점. 패키지 루트 import 는 없음.
 
 ## 사용 트리거 인덱스
 
-- **eslint-recommended** — 프로젝트 `eslint.config.{js,mjs,cjs}` 에서 simplysm 표준 lint 규칙 전체(JS/TS/HTML 파일별 + tseslint/angular-eslint 통합)를 한 번에 적용할 때 import 하는 default export(완성된 flat config 배열).
-- **eslint-plugin** — `@simplysm/<rule>` 커스텀 규칙 9종을 직접 켜거나, 개별 규칙의 감지 범위·메시지·autofix·옵션을 파악할 때. 자세히: [rules.md](./rules.md)
+- **eslint-recommended** (`@simplysm/lint/eslint-recommended`) — 프로젝트 `eslint.config.ts` 에서 통째로 spread 해 쓰는 완성형 flat-config 배열. JS/TS/HTML 파일별 규칙·ignore·플러그인·Angular 통합이 모두 포함됨. 새 프로젝트 lint 설정을 잡을 때.
+- **eslint-plugin** (`@simplysm/lint/eslint-plugin`) — 커스텀 규칙만 담은 ESLint Plugin 객체(`{ rules }`). recommended 를 쓰지 않고 규칙을 직접 골라 등록할 때, 또는 규칙 동작을 개별 검토할 때. 자세히: [rules.md](./rules.md)
 
 ## eslint-recommended
 
-`@simplysm/lint/eslint-recommended` 의 default export. `tseslint.config(...)` 결과(`FlatConfig` 배열)이므로 호출형이 아니라 완성된 상수. 그대로 export 하거나 spread 후 항목을 덧붙여 사용.
+`@simplysm/lint/eslint-recommended` 의 default export. `typescript-eslint` 의 `tseslint.config(...)` 결과 = flat-config 객체 배열. 그대로 spread 해서 사용함.
 
-```js
-// eslint.config.js
+```typescript
+// eslint.config.ts
 import recommended from "@simplysm/lint/eslint-recommended";
-export default recommended;
-// 규칙 추가 시: export default [...recommended, { files: ["**/*.ts"], rules: { "no-debugger": "error" } }];
+
+export default [...recommended];
 ```
 
-config 가 강제하는 핵심 내용(파일 glob 블록별):
+배열을 구성하는 config 블록(순서대로):
 
-- **ignores** — `**/node_modules/**`, `**/dist/**`, `**/.*/**`(숨김 디렉터리 전체). 순회 자체를 건너뜀.
-- **`**/*.{js,mjs,cjs}`** — node globals 적용. 켜는 규칙: `require-await`(async 함수에 await 없으면 오류), `no-shadow`(상위 스코프 변수 가림 금지), `no-duplicate-imports`(같은 모듈 중복 import 금지), `no-unused-expressions`(부수효과 없는 표현식 금지), `no-undef`(선언 안 된 식별자 사용 금지), `unused-imports/no-unused-imports`(미사용 import 제거, autofix), `unused-imports/no-unused-vars`(미사용 변수·인자 경고, `^_` 접두는 무시), `import/no-extraneous-dependencies`(미선언 의존성 import 금지, 단 `lib/**`·`eslint.config.*`·`simplysm.*`·`vitest.config.*` 는 devDependencies 허용), `@simplysm/no-subpath-imports-from-simplysm`, `@simplysm/no-hard-private` + 아래 공통 규칙군.
-- **`**/*.ts`** — `angular.configs.tsRecommended` 를 펼친 뒤 추가. `processInlineTemplates` 로 인라인 템플릿 분리, `tseslint.parser`(`parserOptions.project: true`) 사용, `eslint-import-resolver-typescript` resolver 를 `import.meta.resolve` 로 자동 등록. 켜는 규칙: `no-console`(error), 그리고 타입 인식 `@typescript-eslint/*` 규칙 — `require-await`, `await-thenable`(thenable 만 await), `return-await`(`in-try-catch` = try/catch 안에서만 return await 요구), `no-floating-promises`(await/void 안 한 Promise 금지), `no-shadow`, `no-unnecessary-condition`(`allowConstantLoopConditions: true` = 상수 루프 조건 허용), `no-unnecessary-type-assertion`, `prefer-reduce-type-parameter`, `prefer-return-this-type`, `no-unused-expressions`, `strict-boolean-expressions`(`allowNullableBoolean`·`allowNullableObject` = nullable boolean/object 의 조건식 허용), `ban-ts-comment`(`ts-expect-error` 는 3자 이상 설명 필수), `prefer-readonly`, `naming-convention`(private 멤버는 `_` 접두 필수, 그 외 포맷 제약 없음), `no-misused-promises`(`checksVoidReturn.arguments:false`·`inheritedMethods:false` = 콜백 인자·상속 메서드의 void 반환 검사는 끔), `only-throw-error`(Error 외 throw 금지), `no-array-delete`(배열에 `delete` 금지). 커스텀 규칙 6종: `@simplysm/ng-no-async-effect`, `no-hard-private`, `no-subpath-imports-from-simplysm`, `ts-no-throw-not-implemented-error`(warn), `ts-no-unused-injects`, `ts-no-unused-protected-readonly`. + `@angular-eslint/no-output-native`(off).
-- **`**/*.html`** — `angular.configs.templateRecommended` + `templateAccessibility` 확장. 커스텀 템플릿 규칙: `@simplysm/ng-template-no-strict-null-check`, `ng-template-no-todo-comments`(warn), `ng-template-sd-require-binding-attrs` + `@angular-eslint/template/eqeqeq`(`allowNullOrUndefined: true` = null/undefined 비교는 느슨한 비교 허용), `label-has-associated-control`(off), `no-any`(error).
-- **`**/tests/**/*.ts`(override)** — 테스트 완화: `no-console`(off), `import/no-extraneous-dependencies`(off), `@simplysm/ts-no-throw-not-implemented-error`(off).
-- **`**/vitest.config.ts`(override)** — `no-restricted-properties`(off). 설정 파일에서 `process.env` 직접 접근 허용.
+- **globalIgnores** — `**/node_modules/**`, `**/dist/**`, `**/.*/**` 순회 자체를 건너뜀. 점(.)으로 시작하는 디렉토리 전체가 제외 대상.
+- **공통 languageOptions** — `ecmaVersion: "latest"`, `sourceType: "module"`.
+- **JS 블록** (`**/*.js`, `**/*.mjs`, `**/*.cjs`) — node 글로벌, `import`/`@simplysm`/`unused-imports` 플러그인 등록. 활성 규칙: `require-await`, `no-shadow`, `no-duplicate-imports`, `no-unused-expressions`, `no-undef`, unused-imports 2종, `import/no-extraneous-dependencies`(lib·`eslint.config`·`simplysm`·`vitest.config` 파일은 devDeps 허용), `@simplysm/no-subpath-imports-from-simplysm`, `@simplysm/no-hard-private`, node 빌트인 차단 규칙군, env 직접접근 차단 규칙군.
+- **angular tsRecommended** — `angular.configs.tsRecommended` spread.
+- **TS 블록** (`**/*.ts`) — `processor: angular.processInlineTemplates`(인라인 템플릿 추출 후 별도 lint), `parserOptions.project: true`(타입 정보 사용), `import/resolver` 로 typescript resolver(`alwaysTryTypes: true`) 지정. typescript-eslint 타입체크 규칙 다수 + `@simplysm` 커스텀 규칙 6종 활성. 커스텀 규칙 심각도: `ng-no-async-effect`/`no-hard-private`/`no-subpath-imports-from-simplysm`/`ts-no-unused-injects`/`ts-no-unused-protected-readonly` = `error`, `ts-no-throw-not-implemented-error` = `warn`. `@angular-eslint/no-output-native` 은 `off`.
+- **HTML 블록** (`**/*.html`) — `angular.configs.templateRecommended` + `templateAccessibility` extends. `@simplysm` 템플릿 규칙 3종 활성: `ng-template-no-strict-null-check`=`error`, `ng-template-no-todo-comments`=`warn`, `ng-template-sd-require-binding-attrs`=`error`. `@angular-eslint/template/eqeqeq` 는 `allowNullOrUndefined: true`, `label-has-associated-control`=`off`, `no-any`=`error`.
+- **테스트 오버라이드** (`**/tests/**/*.ts`) — 테스트 코드 완화: `no-console`=`off`, `import/no-extraneous-dependencies`=`off`, `@simplysm/ts-no-throw-not-implemented-error`=`off`.
+- **vitest.config 오버라이드** (`**/vitest.config.ts`) — `no-restricted-properties`=`off` (설정 파일에서 `process.env` 접근 허용).
 
-공통 규칙군(JS/TS 양쪽 적용): `no-warning-comments`(warn, TODO/FIXME 등 경고), `eqeqeq`(`always`, 단 `null` 비교는 `==`/`!=` 허용), `no-self-compare`, `array-callback-return`(map/filter 등 콜백에 return 강제). 추가 공통 금지: `no-restricted-globals`(`Buffer` 전역 금지 → `Uint8Array`/`BytesUtils`), `no-restricted-imports`(`buffer`·`events`·`eventemitter3` 모듈 금지), `no-restricted-properties`(`process.env` 직접 접근 금지 → `env("...")`), `no-restricted-syntax`(`import.meta.env` 직접 접근·`env("NODE_ENV")`·`=== undefined`/`!== undefined` 류 strict 비교 금지 → `== null`/`!= null`).
+주의:
 
-주의: 타입 인식 `@typescript-eslint` 규칙이 켜져 있어 TS 파일은 `parserOptions.project: true` 가 동작하는 환경(tsconfig 포함)이어야 함.
+- TS 블록은 타입 정보(`parserOptions.project: true`)를 요구하므로, 대상 프로젝트에 유효한 `tsconfig` 가 있어야 함.
+- node 빌트인 차단(`noNodeBuiltinsRules`): `Buffer` 글로벌 및 `buffer`/`events`/`eventemitter3` import 금지 — 각각 `Uint8Array`/`@simplysm/core-common`의 `BytesUtils`·`EventEmitter` 로 대체 유도. JS·TS 블록 모두에 적용.
+- env 직접접근 차단(`noDirectEnvAccessRules`): `process.env`·`import.meta.env` 직접 접근, `env("NODE_ENV")` 호출, `=== undefined`/`!== undefined`(엄격 비교) 를 `no-restricted-properties`/`no-restricted-syntax` 로 막음(엄격 비교는 `== null`/`!= null` 로 유도). JS·TS 블록 모두에 적용.
 
 ## eslint-plugin
 
-`@simplysm/lint/eslint-plugin` 의 default export 는 `{ rules: { ... } }` 형태의 ESLint 플러그인 객체. 9개 규칙을 규칙 ID → 규칙 정의로 매핑. 보통 `eslint-recommended` 가 내부에서 `@simplysm` 네임스페이스로 등록하므로, 직접 import 는 recommended 없이 커스텀 config 를 짜거나 특정 규칙만 개별 제어할 때만 필요. 규칙별 상세는 [rules.md](./rules.md).
+`@simplysm/lint/eslint-plugin` 의 default export. ESLint Plugin 형태 객체.
 
-```js
+```typescript
 import plugin from "@simplysm/lint/eslint-plugin";
-export default [{ plugins: { "@simplysm": plugin }, rules: { "@simplysm/no-hard-private": "error" } }];
+// plugin === { rules: { "ng-no-async-effect": ..., "no-hard-private": ..., ... } }
 ```
 
-규칙 ID 9종: `ng-no-async-effect`, `ng-template-no-strict-null-check`, `ng-template-no-todo-comments`, `ng-template-sd-require-binding-attrs`, `no-hard-private`, `no-subpath-imports-from-simplysm`, `ts-no-throw-not-implemented-error`, `ts-no-unused-injects`, `ts-no-unused-protected-readonly`.
+- `rules` — 규칙 id → 규칙 객체 맵. 등록된 9개 id: `ng-no-async-effect`, `ng-template-no-strict-null-check`, `ng-template-no-todo-comments`, `ng-template-sd-require-binding-attrs`, `no-hard-private`, `no-subpath-imports-from-simplysm`, `ts-no-throw-not-implemented-error`, `ts-no-unused-injects`, `ts-no-unused-protected-readonly`.
+
+flat-config 에서 직접 등록할 때는 `plugins: { "@simplysm": plugin }` 로 매핑 후 `"@simplysm/<id>"` 로 켬. 각 규칙의 검사 대상·옵션·autofix·메시지는 [rules.md](./rules.md) 참조.