@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/core-node/features/fs-watcher.md

@@ -0,0 +1,110 @@
+# FsWatcher
+
+Chokidar 기반 파일 시스템 감시 래퍼. 짧은 시간 내에 발생하는 이벤트를 병합하여 콜백을 한 번만 호출한다.
+EPERM 에러 발생 시 최대 3회까지 watcher를 자동 재시작한다.
+
+## When to use
+
+- ✅ 파일/디렉토리 변경을 지속적으로 감시하고, 짧은 시간 내 연속 이벤트를 하나로 병합해야 할 때
+- ✅ glob 패턴으로 특정 파일만 감시하면서 이벤트 디바운싱이 필요할 때
+- ❌ 단발성 파일 변경 확인 → `fsx.stat`으로 mtime 비교
+
+```typescript
+export class FsWatcher {
+  static async watch(paths: string[], options?: chokidar.ChokidarOptions): Promise<FsWatcher>
+  onChange(opt: { delay?: number }, cb: (changeInfos: FsWatcherChangeInfo[]) => void | Promise<void>): this
+  async close(): Promise<void>
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `watch` | static method | `(paths: string[], options?: ChokidarOptions) => Promise<FsWatcher>` | 파일 감시 시작. `ready` 이벤트까지 대기 후 반환 |
+| `onChange` | method | `(opt: { delay?: number }, cb: ...) => this` | 파일 변경 이벤트 핸들러 등록 |
+| `close` | method | `() => Promise<void>` | 파일 감시자 종료 |
+
+## `ignoreInitial` 주의
+
+chokidar의 `ignoreInitial` 옵션은 내부적으로 항상 `true`로 설정된다.
+`options.ignoreInitial: false`를 전달하면 첫 번째 `onChange` 호출 시 빈 배열로 콜백이 호출되지만, 실제 초기 파일 목록은 포함되지 않는다. 이는 이벤트 병합 로직과의 충돌을 방지하기 위한 의도적인 동작이다.
+
+## Related Types
+
+### `FsWatcherEvent`
+
+```typescript
+export type FsWatcherEvent = "add" | "addDir" | "change" | "unlink" | "unlinkDir";
+```
+
+지원되는 파일 변경 이벤트 타입.
+
+### `FsWatcherChangeInfo`
+
+```typescript
+export interface FsWatcherChangeInfo {
+  event: FsWatcherEvent;
+  path: PosixPath;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `event` | `FsWatcherEvent` | 변경 이벤트 타입 |
+| `path` | [`PosixPath`](../utils/pathx.md#posixpath) | 변경된 파일/디렉토리 경로 (정규화됨) |
+
+## 이벤트 병합 전략
+
+같은 파일에 대해 `delay` 시간 내에 여러 이벤트가 발생하면 최종 상태만 전달된다:
+
+| 이전 이벤트 | 신규 이벤트 | 결과 |
+|------------|------------|------|
+| `add` | `change` | `add` (생성 직후 수정 → 생성) |
+| `add` | `unlink` | 제거 (생성 직후 삭제 → 변경 없음) |
+| `addDir` | `unlinkDir` | 제거 (생성 직후 삭제 → 변경 없음) |
+| `unlink` | `add` | `add` (삭제 후 재생성 → 생성) |
+| `unlink` | `change` | `change` |
+| `unlinkDir` | `addDir` | `addDir` (디렉토리 재생성) |
+| 그 외 | — | 최신 이벤트로 덮어쓰기 |
+
+## Glob 패턴 처리
+
+glob 패턴이 포함된 경로(`*`, `?`, `{`, `[`, `]`)는 glob base 디렉토리를 감시하고, Minimatch로 이벤트를 필터링한다.
+
+## Usage
+
+```typescript
+import { FsWatcher } from "@simplysm/core-node";
+
+const watcher = await FsWatcher.watch(["src/**/*.ts"]);
+
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { event, path } of changes) {
+    // event: "add" | "addDir" | "change" | "unlink" | "unlinkDir"
+    // path: PosixPath
+  }
+});
+
+// 종료
+await watcher.close();
+```
+
+## 🚫 Anti-patterns
+
+### close() 누락
+
+```typescript
+// ❌ close하지 않으면 프로세스가 종료되지 않음
+const watcher = await FsWatcher.watch(["src/**/*.ts"]);
+watcher.onChange({ delay: 300 }, handler);
+// 프로세스 행
+
+// ✅ 작업 완료 후 반드시 close
+const watcher = await FsWatcher.watch(["src/**/*.ts"]);
+watcher.onChange({ delay: 300 }, handler);
+// ... 작업 완료 후
+await watcher.close();
+```
+
+**근거**: chokidar watcher는 persistent 모드로 동작하여 close하지 않으면 프로세스가 종료되지 않는다.

package/claude/references/sd-simplysm-v14/core-node/logging/create-file-reporter.md

@@ -0,0 +1,78 @@
+# createFileReporter
+
+파일 기반 consola reporter를 생성한다. `.logs/` 디렉토리에 `app.YYYY-MM-DD.log` 형식으로 JSON 라인을 기록하며, 날짜별 로테이션과 크기 제한을 지원한다.
+
+## When to use
+
+- ✅ 로그를 파일로 영구 보관하고, 날짜별 로테이션/크기 제한이 필요할 때
+- ❌ 터미널 출력용 → [`PrettyReporter`](./pretty-reporter.md) 사용
+- ❌ 환경별 자동 구성 → [`setupConsola`](./setup-consola.md) 사용
+
+```typescript
+export function createFileReporter(options?: FileReporterOptions): ConsolaReporter
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `options` | `FileReporterOptions` (optional) | 파일 reporter 옵션 |
+
+## Returns
+
+`ConsolaReporter` — consola reporter 인터페이스 구현체
+
+## Related Types
+
+### `FileReporterOptions`
+
+```typescript
+export interface FileReporterOptions {
+  /** @default 20MB */
+  maxSize?: number;
+  /** @default 14 */
+  maxDays?: number;
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `maxSize` | `number` (optional) | `20 * 1024 * 1024` (20MB) | 파일 1개의 최대 크기(bytes). 초과 시 `app.YYYY-MM-DD.N.log`로 순번 파일 생성 |
+| `maxDays` | `number` (optional) | `14` | 보관할 최대 일수. 날짜가 바뀔 때 이전 파일을 정리 |
+
+## 로그 파일 형식
+
+각 라인은 JSON 객체:
+
+```json
+{"time":"2024-01-15T10:30:00.000Z","level":"INFO","msg":"서버 시작"}
+{"time":"2024-01-15T10:30:01.000Z","level":"ERROR","tag":"db","err":{"message":"연결 실패","stack":"Error: ..."}}
+```
+
+| 필드 | 설명 |
+|------|------|
+| `time` | ISO 8601 타임스탬프 |
+| `level` | 로그 타입 대문자 (INFO, ERROR, DEBUG 등) |
+| `tag` | consola 태그 (있을 때만 포함) |
+| `msg` | 문자열 인자를 공백으로 합친 메시지 (있을 때만 포함) |
+| `err` | Error 객체 (있을 때만 포함): `{ message, stack }` |
+
+## 파일 명명 규칙
+
+- 기본: `.logs/app.YYYY-MM-DD.log`
+- 크기 초과 시: `.logs/app.YYYY-MM-DD.1.log`, `.logs/app.YYYY-MM-DD.2.log`, ...
+- `process.cwd()` 기준 `.logs/` 디렉토리에 저장
+
+## Usage
+
+```typescript
+import { createFileReporter } from "@simplysm/core-node";
+import consola from "consola";
+
+// 기본 옵션
+consola.options.reporters = [createFileReporter()];
+
+// 크기/기간 커스텀
+const reporter = createFileReporter({ maxSize: 10 * 1024 * 1024, maxDays: 7 });
+consola.options.reporters = [reporter];
+```

package/claude/references/sd-simplysm-v14/core-node/logging/pretty-reporter.md

@@ -0,0 +1,38 @@
+# PrettyReporter
+
+터미널 출력용 consola reporter. 로그 타입별 아이콘과 색상을 지원하며, 에러 스택 트레이스를 포맷팅한다.
+
+## When to use
+
+- ✅ 터미널에 아이콘/색상이 포함된 가독성 좋은 로그를 출력할 때
+- ✅ `setupConsola()`의 기본 동작 대신 reporter를 직접 조합할 때
+- ❌ 로그를 파일로 저장 → [`createFileReporter`](./create-file-reporter.md) 사용
+
+```typescript
+export class PrettyReporter implements ConsolaReporter {
+  log(logObj: LogObject, ctx: { options: ConsolaOptions }): void
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `log` | method | `(logObj: LogObject, ctx: { options: ConsolaOptions }) => void` | 로그 항목을 터미널에 출력 |
+
+## 동작 방식
+
+- `logObj.level < 2` (error/fatal)이면 `stderr`, 그 외이면 `stdout`에 출력
+- 컬러 지원 자동 감지: `NO_COLOR` 환경 변수 → `FORCE_COLOR` 환경 변수 → `process.stdout.isTTY` → Windows 여부 순으로 판단
+- 로그 타입별 아이콘: `error`/`fatal`/`fail` = `✖`, `ready`/`success` = `✔`, `warn` = `⚠`, `info` = `ℹ`, `debug` = `⚙`, `trace` = `→`
+- `Error` 객체는 메시지 + 스택 트레이스로 포맷팅되며, `cause` 체인도 재귀적으로 표시됨
+- `badge` 옵션이나 error/fatal 레벨이면 로그 앞뒤에 빈 줄을 추가 (시각적 강조)
+
+## Usage
+
+```typescript
+import { PrettyReporter } from "@simplysm/core-node";
+import consola from "consola";
+
+consola.options.reporters = [new PrettyReporter()];
+```

package/claude/references/sd-simplysm-v14/core-node/logging/setup-consola.md

@@ -0,0 +1,77 @@
+# setupConsola
+
+환경에 따라 consola reporter를 자동 구성한다. 이 패키지의 `console.*` 사용 금지 규칙을 대체하는 표준 로깅 진입점이다.
+
+## When to use
+
+- ✅ 서버/CLI 애플리케이션 시작 시 환경별(개발/프로덕션) 로깅을 한 번에 구성할 때
+- ❌ reporter를 세밀하게 커스텀 조합할 때 → `createFileReporter`/`PrettyReporter`를 직접 사용
+
+```typescript
+export function setupConsola(opts?: SetupConsolaOptions): void
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `opts` | `SetupConsolaOptions` (optional) | 구성 옵션 |
+
+## Related Types
+
+### `SetupConsolaOptions`
+
+```typescript
+export interface SetupConsolaOptions {
+  cli?: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cli` | `boolean` (optional) | CLI 모드 여부. `true`이면 프로덕션에서도 개발 경로(FileReporter + PrettyReporter)를 사용 |
+
+## 환경별 동작
+
+| 조건 | Reporter | 레벨 |
+|------|----------|------|
+| 프로덕션 (`DEV` 아님, `cli` 아님) | `FileReporter`만 | debug까지 파일 기록 |
+| 개발 또는 `cli: true` + `SD_DEBUG=true` | `PrettyReporter`만 | debug까지 터미널 출력 |
+| 개발 또는 `cli: true` (일반) | `FileReporter` + `PrettyReporter` (info 이하만) | debug는 파일에만 기록, info 이하는 터미널 출력 |
+
+`DEV` 환경 변수 감지에는 `@simplysm/core-common`의 `parseBoolEnv(env("DEV"))`를 사용한다.
+
+## `withMaxLevel`
+
+reporter에 로그 레벨 상한선을 설정한 래퍼를 반환한다. `setupConsola()` 내부에서 PrettyReporter를 info 레벨로 제한할 때 사용된다.
+
+```typescript
+export function withMaxLevel(reporter: ConsolaReporter, maxLevel: number): ConsolaReporter
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `reporter` | `ConsolaReporter` | 감쌀 reporter |
+| `maxLevel` | `number` | 이 레벨보다 높은 로그는 무시 (consola의 `LogLevels` 상수 사용 권장) |
+
+## Usage
+
+```typescript
+import { setupConsola, withMaxLevel, PrettyReporter } from "@simplysm/core-node";
+import { LogLevels } from "consola";
+
+// 환경별 자동 구성 (일반 서버)
+setupConsola();
+
+// CLI 모드 (프로덕션에서도 터미널 출력)
+setupConsola({ cli: true });
+
+// 개별 reporter 직접 조합
+import consola from "consola";
+import { createFileReporter } from "@simplysm/core-node";
+
+consola.options.reporters = [
+  createFileReporter(),
+  withMaxLevel(new PrettyReporter(), LogLevels.info),
+];
+```

package/claude/references/sd-simplysm-v14/core-node/utils/cpx.md

@@ -0,0 +1,128 @@
+# cpx
+
+자식 프로세스 실행 및 인코딩 감지 유틸리티 네임스페이스.
+
+```typescript
+import { cpx } from "@simplysm/core-node";
+```
+
+## When to use
+
+- ✅ 외부 명령어(git, npm, 빌드 도구 등)를 실행하고 결과를 받아야 할 때
+- ✅ 자식 프로세스의 stdout/stderr를 Uint8Array로 수집하고 시스템 인코딩에 맞게 디코딩해야 할 때
+- ❌ Worker thread로 CPU 작업 분리 → [`Worker`](../worker/worker.md) 사용
+
+## Members
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `spawn` | function | `(cmd: string, args: string[], options?: SpawnOptions & { reject?: boolean }) => SpawnProcess` | 자식 프로세스 실행 (비동기). `SpawnProcess`를 반환한다 |
+| `spawnSync` | function | `(cmd: string, args: string[], options?: SpawnSyncOptions & { reject?: boolean }) => SpawnResult` | 자식 프로세스 동기 실행 |
+| `getSystemEncoding` | function | `() => string` | 시스템 기본 인코딩 감지. 결과는 캐시됨 |
+| `codePageToEncoding` | function | `(codePage: number) => string` | Windows 코드 페이지 번호를 인코딩 이름으로 변환 |
+| `resetEncodingCache` | function | `() => void` | 캐시된 시스템 인코딩 초기화 |
+| `decodeBytes` | function | `(raw: Uint8Array, systemEncoding?: string) => string` | Uint8Array를 문자열로 디코딩 |
+| `resolveStdioPipe` | function | `(stdio: SpawnOptions["stdio"]) => { stdout: boolean; stderr: boolean }` | stdio 옵션에서 pipe 여부 추출 |
+| `SpawnProcess` | class | — | `spawn()` 반환 타입. PromiseLike 구현, kill() 지원 |
+| `SpawnResult` | interface | — | `spawn`/`spawnSync` 결과 타입 |
+
+## `SpawnProcess`
+
+`spawn()`이 반환하는 클래스. `PromiseLike<SpawnResult>`를 구현하여 `await`로 사용 가능하다.
+
+```typescript
+export class SpawnProcess implements PromiseLike<SpawnResult> {
+  get pid(): number | undefined
+  then<TResult1 = SpawnResult, TResult2 = never>(
+    onfulfilled?: ((value: SpawnResult) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult1 | TResult2>
+  catch<TResult = never>(
+    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<SpawnResult | TResult>
+  kill(signal?: NodeJS.Signals | number): boolean
+}
+```
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `pid` | getter | `number \| undefined` | 자식 프로세스의 PID |
+| `then` | method | `PromiseLike.then` | Promise then 메서드 |
+| `catch` | method | `PromiseLike.catch` | Promise catch 메서드 |
+| `kill` | method | `(signal?: NodeJS.Signals \| number) => boolean` | 프로세스에 신호를 보냄 (기본값: SIGTERM) |
+
+## `SpawnResult`
+
+```typescript
+export interface SpawnResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stdout` | `string` | 표준 출력 내용. stdio가 "pipe"가 아니면 빈 문자열 |
+| `stderr` | `string` | 표준 에러 내용. stdio가 "pipe"가 아니면 빈 문자열 |
+| `exitCode` | `number` | 프로세스 종료 코드 |
+
+## reject 옵션
+
+`spawn`/`spawnSync` 모두 기본적으로 `exitCode !== 0`이면 오류를 발생시킨다. `options.reject: false`를 지정하면 항상 정상 반환된다.
+
+## getSystemEncoding 인코딩 감지 로직
+
+- **Windows**: `chcp` 명령으로 코드 페이지를 얻어 `codePageToEncoding()`으로 변환
+- **Linux/macOS**: `LANG` 또는 `LC_ALL` 환경 변수의 `.` 이후 부분 사용
+- 감지 실패 시 `"utf-8"` 반환
+
+## decodeBytes 디코딩 로직
+
+- `systemEncoding`이 `"utf-8"`이면 UTF-8로 바로 디코딩
+- 그렇지 않으면 먼저 UTF-8 strict 디코딩을 시도하고, 실패하면 `systemEncoding`으로 디코딩
+
+## Usage
+
+```typescript
+import { cpx } from "@simplysm/core-node";
+
+// 기본 실행 (결과 대기)
+const result = await cpx.spawn("git", ["status"], { cwd: "/project" });
+console.log(result.stdout);
+
+// 실시간 출력 표시
+await cpx.spawn("npm", ["run", "build"], { stdio: "inherit" });
+
+// 오류 무시
+const result2 = await cpx.spawn("cmd", ["nonexistent"], { reject: false });
+// result2.exitCode가 0이 아니어도 throw되지 않음
+
+// 프로세스 제어
+const proc = cpx.spawn("long-running", []);
+setTimeout(() => proc.kill(), 5000);
+const r = await proc;
+
+// 동기 실행
+const syncResult = cpx.spawnSync("node", ["--version"]);
+
+// 인코딩 감지
+const encoding = cpx.getSystemEncoding(); // e.g. "utf-8", "euc-kr"
+```
+
+## 🚫 Anti-patterns
+
+### reject: false 없이 실패 허용 프로세스 실행
+
+```typescript
+// ❌ exitCode !== 0이면 throw — 의도적으로 실패를 허용할 때 문제
+const result = await cpx.spawn("grep", ["pattern", "file.txt"]);
+
+// ✅ reject: false로 종료 코드를 직접 확인
+const result = await cpx.spawn("grep", ["pattern", "file.txt"], { reject: false });
+if (result.exitCode === 0) {
+  // 매칭 있음
+}
+```
+
+**근거**: `spawn`/`spawnSync`는 기본적으로 `exitCode !== 0`이면 오류를 발생시킨다. 실패가 정상 흐름인 경우 `reject: false` 필수.

package/claude/references/sd-simplysm-v14/core-node/utils/fsx.md

@@ -0,0 +1,168 @@
+# fsx
+
+파일 시스템 작업을 위한 유틸리티 네임스페이스. 모든 연산은 동기(`*Sync`)와 비동기 쌍으로 제공된다.
+비동기 버전을 기본으로 사용하고, CLI 초기화 등 동기가 반드시 필요한 경우에만 동기 버전을 사용한다.
+
+```typescript
+import { fsx } from "@simplysm/core-node";
+```
+
+## When to use
+
+- ✅ Node.js에서 파일/디렉토리 CRUD, glob 검색, JSON 파일 처리가 필요할 때
+- ✅ 상위 디렉토리 자동 생성, 복사 시 필터링, 삭제 시 자동 재시도 등 편의 기능이 필요할 때
+- ❌ 브라우저 환경 → `@simplysm/core-browser` 또는 Web API 사용
+- ❌ 스트림 기반 대용량 파일 처리 → Node.js `fs.createReadStream` 직접 사용
+
+## Members
+
+### 존재 여부 확인
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `exists` | function | `(targetPath: string) => Promise<boolean>` | 파일 또는 디렉토리가 존재하는지 확인 (비동기) |
+| `existsSync` | function | `(targetPath: string) => boolean` | 파일 또는 디렉토리가 존재하는지 확인 (동기) |
+
+### 디렉토리 생성
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `mkdir` | function | `(targetPath: string) => Promise<void>` | 디렉토리를 재귀적으로 생성 (비동기) |
+| `mkdirSync` | function | `(targetPath: string) => void` | 디렉토리를 재귀적으로 생성 (동기) |
+
+### 삭제
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `rm` | function | `(targetPath: string) => Promise<void>` | 파일/디렉토리 삭제. 파일 잠금 오류 시 최대 6회(500ms 간격) 재시도 (비동기) |
+| `rmSync` | function | `(targetPath: string) => void` | 파일/디렉토리 삭제. 재시도 없이 즉시 실패 (동기) |
+
+### 복사
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `copy` | function | `(sourcePath: string, targetPath: string, filter?: (absolutePath: string) => boolean) => Promise<void>` | 파일/디렉토리 복사. sourcePath가 없으면 아무것도 하지 않음 (비동기) |
+| `copySync` | function | `(sourcePath: string, targetPath: string, filter?: (absolutePath: string) => boolean) => void` | 파일/디렉토리 복사 (동기) |
+
+### 파일 읽기
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `read` | function | `(targetPath: string) => Promise<string>` | 파일을 UTF-8 문자열로 읽음 (비동기) |
+| `readSync` | function | `(targetPath: string) => string` | 파일을 UTF-8 문자열로 읽음 (동기) |
+| `readBytes` | function | `(targetPath: string) => Promise<Uint8Array>` | 파일을 Uint8Array로 읽음 (비동기) |
+| `readBytesSync` | function | `(targetPath: string) => Uint8Array` | 파일을 Uint8Array로 읽음 (동기) |
+| `readJson` | function | `<TData = unknown>(targetPath: string) => Promise<TData>` | JSON 파일 읽기, `@simplysm/core-common`의 `json.parse` 사용 (비동기) |
+| `readJsonSync` | function | `<TData = unknown>(targetPath: string) => TData` | JSON 파일 읽기 (동기) |
+
+### 파일 쓰기
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `write` | function | `(targetPath: string, data: string \| Uint8Array) => Promise<void>` | 파일에 데이터 쓰기. 상위 디렉토리 자동 생성 (비동기) |
+| `writeSync` | function | `(targetPath: string, data: string \| Uint8Array) => void` | 파일에 데이터 쓰기. 상위 디렉토리 자동 생성 (동기) |
+| `writeJson` | function | `(targetPath: string, data: unknown, options?: { replacer?: ...; space?: string \| number }) => Promise<void>` | JSON 파일 쓰기, `@simplysm/core-common`의 `json.stringify` 사용 (비동기) |
+| `writeJsonSync` | function | `(targetPath: string, data: unknown, options?: { replacer?: ...; space?: string \| number }) => void` | JSON 파일 쓰기 (동기) |
+
+### 디렉토리 읽기
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `readdir` | function | `(targetPath: string) => Promise<string[]>` | 디렉토리 내용 읽기 (비동기) |
+| `readdirSync` | function | `(targetPath: string) => string[]` | 디렉토리 내용 읽기 (동기) |
+
+### 파일 정보
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `stat` | function | `(targetPath: string) => Promise<fs.Stats>` | 파일/디렉토리 정보 조회. 심볼릭 링크를 따라감 (비동기) |
+| `statSync` | function | `(targetPath: string) => fs.Stats` | 파일/디렉토리 정보 조회. 심볼릭 링크를 따라감 (동기) |
+| `lstat` | function | `(targetPath: string) => Promise<fs.Stats>` | 파일/디렉토리 정보 조회. 심볼릭 링크를 따라가지 않음 (비동기) |
+| `lstatSync` | function | `(targetPath: string) => fs.Stats` | 파일/디렉토리 정보 조회. 심볼릭 링크를 따라가지 않음 (동기) |
+
+### Glob
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `glob` | function | `(pattern: string, options?: GlobOptions) => Promise<string[]>` | Glob 패턴으로 파일 검색. 절대 경로 배열 반환 (비동기) |
+| `globSync` | function | `(pattern: string, options?: GlobOptions) => string[]` | Glob 패턴으로 파일 검색 (동기) |
+
+### 유틸리티
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `clearEmptyDirectory` | function | `(dirPath: string) => Promise<void>` | 지정 디렉토리 하위의 빈 디렉토리를 재귀적으로 삭제 |
+| `findAllParentChildPaths` | function | `(childGlob: string, fromPath: string, rootPath?: string) => Promise<string[]>` | 시작 경로에서 루트 방향으로 부모 디렉토리를 순회하며 glob 패턴에 매칭되는 파일 검색 (비동기) |
+| `findAllParentChildPathsSync` | function | `(childGlob: string, fromPath: string, rootPath?: string) => string[]` | 시작 경로에서 루트 방향으로 부모 디렉토리를 순회하며 glob 패턴에 매칭되는 파일 검색 (동기) |
+
+## `copy` / `copySync` — filter 파라미터
+
+- 각 파일/디렉토리의 **절대 경로**가 전달된다
+- `true` 반환 시 복사, `false` 반환 시 제외
+- 최상위 `sourcePath`는 필터링 대상이 아니다. 필터는 모든 하위 항목(직접 및 간접)에 재귀적으로 적용된다
+- 디렉토리에 대해 `false`를 반환하면 해당 디렉토리와 모든 내용을 건너뛴다
+
+## `findAllParentChildPaths` / `findAllParentChildPathsSync` — rootPath 주의
+
+- `fromPath`는 `rootPath`의 하위 경로여야 한다. 그렇지 않으면 파일 시스템 루트까지 검색한다
+
+## Usage
+
+```typescript
+import { fsx } from "@simplysm/core-node";
+
+// 파일 존재 확인
+const exists = await fsx.exists("/path/to/file.txt");
+
+// 읽기/쓰기
+const content = await fsx.read("/path/to/file.txt");
+await fsx.write("/path/to/new-file.txt", "Hello, World!");
+
+// JSON 읽기/쓰기
+const data = await fsx.readJson<{ name: string }>("/config.json");
+await fsx.writeJson("/config.json", { name: "test" });
+
+// 복사 (필터 적용)
+await fsx.copy("/src/dir", "/dst/dir", (filePath) => !filePath.includes("node_modules"));
+
+// Glob 검색
+const tsFiles = await fsx.glob("src/**/*.ts");
+
+// 빈 디렉토리 정리
+await fsx.clearEmptyDirectory("/output");
+
+// 부모 디렉토리에서 파일 검색
+const configs = await fsx.findAllParentChildPaths("package.json", "/project/src/components");
+```
+
+## 🚫 Anti-patterns
+
+### 동기 버전을 기본으로 사용
+
+```typescript
+// ❌ 비동기 컨텍스트에서 동기 함수 사용
+async function process() {
+  const content = fsx.readSync("/path/to/file.txt");
+  fsx.writeSync("/path/to/output.txt", content);
+}
+
+// ✅ 비동기 버전 사용
+async function process() {
+  const content = await fsx.read("/path/to/file.txt");
+  await fsx.write("/path/to/output.txt", content);
+}
+```
+
+**근거**: 동기 버전은 이벤트 루프를 차단한다. CLI 초기화 등 반드시 동기가 필요한 경우에만 `*Sync` 사용.
+
+### rmSync로 일시적 파일 잠금 오류 처리
+
+```typescript
+// ❌ rmSync는 재시도 없이 즉시 실패
+fsx.rmSync("/path/to/locked-file");
+
+// ✅ rm은 파일 잠금 시 최대 6회(500ms 간격) 재시도
+await fsx.rm("/path/to/locked-file");
+```
+
+**근거**: Windows에서 파일 잠금은 흔한 일시적 오류. 비동기 `rm`을 사용하면 자동 재시도된다.

package/claude/references/sd-simplysm-v14/core-node/utils/pathx.md

@@ -0,0 +1,73 @@
+# pathx
+
+경로 처리 및 `PosixPath` 브랜드 타입 유틸리티 네임스페이스.
+
+```typescript
+import { pathx } from "@simplysm/core-node";
+```
+
+## When to use
+
+- ✅ Windows 경로를 POSIX 슬래시로 정규화해야 할 때
+- ✅ 경로 간 하위 관계를 확인하거나, 파일 경로의 디렉토리를 바꿔야 할 때
+- ❌ 단순 `path.join`/`path.resolve`만 필요한 경우 → Node.js `path` 모듈 직접 사용
+
+## Members
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `PosixPath` | type | `string & { [POSIX]: never }` | POSIX 스타일(슬래시) 경로 브랜드 타입 |
+| `posix` | function | `(p: string) => PosixPath` | 백슬래시를 슬래시로 변환. resolve는 수행하지 않음 |
+| `posixResolve` | function | `(...args: string[]) => PosixPath` | 절대 경로로 resolve한 뒤 POSIX 스타일로 변환 |
+| `changeFileDirectory` | function | `(filePath: string, fromDirectory: string, toDirectory: string) => string` | 파일 경로의 디렉토리를 변경 |
+| `basenameWithoutExt` | function | `(filePath: string) => string` | 확장자를 제외한 파일명(basename) 반환 |
+| `isChildPath` | function | `(childPath: string, parentPath: string) => boolean` | childPath가 parentPath의 하위 경로인지 확인 |
+| `filterByTargets` | function | `(files: string[], targets: string[], cwd: string) => string[]` | 대상 경로 목록에 기반한 파일 필터링 |
+
+## `PosixPath`
+
+슬래시(`/`) 구분자임을 타입 수준에서 보장하는 브랜드 타입. `posix()` 또는 `posixResolve()`를 통해서만 생성할 수 있다. `FsWatcher`가 반환하는 경로는 항상 `PosixPath`다.
+
+```typescript
+export type PosixPath = string & {
+  [POSIX]: never;
+};
+```
+
+## `changeFileDirectory` — 예외 조건
+
+`filePath`가 `fromDirectory` 내부에 없으면 `ArgumentError`를 throw한다.
+
+## `isChildPath` — 동일 경로 처리
+
+동일한 경로이면 `false`를 반환한다. 내부적으로 `posixResolve()`로 정규화하여 비교한다.
+
+## `filterByTargets` — files 파라미터 주의
+
+`files`는 `cwd` 하위의 절대 경로여야 한다. `cwd` 외부 경로는 상대 경로(`../`)로 변환되어 처리되며 의도치 않은 결과가 생길 수 있다. `targets`가 비어있으면 `files`를 그대로 반환한다.
+
+## Usage
+
+```typescript
+import { pathx } from "@simplysm/core-node";
+
+// POSIX 경로 변환
+const p = pathx.posix("C:\\Users\\test"); // "C:/Users/test"
+
+// 절대 경로 resolve + POSIX
+const abs = pathx.posixResolve("./relative", "path"); // e.g. "D:/cwd/relative/path"
+
+// 파일 디렉토리 변경
+const newPath = pathx.changeFileDirectory("/a/b/c.txt", "/a", "/x"); // "/x/b/c.txt"
+
+// 확장자 없는 basename
+pathx.basenameWithoutExt("file.spec.ts"); // "file.spec"
+
+// 자식 경로 확인
+pathx.isChildPath("/a/b/c", "/a/b"); // true
+pathx.isChildPath("/a/b", "/a/b"); // false (동일 경로)
+
+// 파일 필터링
+const files = ["/proj/src/a.ts", "/proj/tests/b.ts"];
+pathx.filterByTargets(files, ["src"], "/proj"); // ["/proj/src/a.ts"]
+```