@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/core-common/utils/num.md

@@ -0,0 +1,56 @@
+# num
+
+숫자 유틸리티 네임스페이스.
+
+```typescript
+import { num } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `parseInt` | `(text: unknown) => number \| undefined` | 문자열을 정수로 파싱. 비숫자 문자 제거 후 파싱. 소수점 이하 버림 |
+| `parseFloat` | `(text: unknown) => number \| undefined` | 문자열을 float로 파싱. 비숫자 문자 제거 후 파싱 |
+| `parseRoundedInt` | `(text: unknown) => number \| undefined` | 문자열을 float로 파싱한 후 반올림하여 정수 반환 |
+| `isNullOrEmpty` | `(val: number \| undefined) => val is 0 \| undefined` | 타입 가드: undefined, null, 0이면 true |
+| `format` | `(val: number, digit?) => string` | 천 단위 구분자 포함 문자열로 포맷 |
+| `format` | `(val: number \| undefined, digit?) => string \| undefined` | undefined이면 undefined 반환 |
+
+## `parseInt` / `parseFloat` 동작
+
+- 숫자, `-`, `.` 이외의 문자 제거 후 파싱
+- 선행 `-`만 음수 부호로 유지 (중간 `-`는 제거)
+- 파싱 실패 시 `undefined` 반환
+
+## `format` — `digit` 옵션
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `max` | `number` | 최대 소수점 자릿수 |
+| `min` | `number` | 최소 소수점 자릿수 (부족하면 0으로 채움) |
+
+## Usage
+
+```typescript
+import { num } from "@simplysm/core-common";
+
+num.parseInt("1,234.56");   // 1234
+num.parseInt("-123");       // -123
+num.parseInt("010-1234-5678"); // 1012345678 (중간 - 제거)
+num.parseInt("abc");        // undefined
+
+num.parseFloat("1,234.56"); // 1234.56
+num.parseRoundedInt("1.7"); // 2
+
+// null/zero 검사 (타입 가드)
+const count: number | undefined = getValue();
+if (num.isNullOrEmpty(count)) {
+  // count: 0 | undefined
+} else {
+  // count: number (non-zero)
+}
+
+num.format(1234567.89, { max: 2 }); // "1,234,567.89"
+num.format(1234, { min: 2 });       // "1,234.00"
+```

package/claude/references/sd-simplysm-v14/core-common/utils/obj.md

@@ -0,0 +1,107 @@
+# obj
+
+객체 유틸리티 네임스페이스. 깊은 복사, 비교, 병합, key 조작 등을 제공한다.
+
+```typescript
+import { obj } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `clone` | `<T>(source: T) => T` | 깊은 복사. 순환 참조, 커스텀 타입(`DateTime`, `DateOnly`, `Time`, `Uuid`, `Uint8Array`) 지원 |
+| `equal` | `(source, target, options?) => boolean` | 깊은 동등성 비교 |
+| `merge` | `<S, T>(source: S, target: T, opt?) => S & T` | 깊은 병합. source를 기반으로 target을 병합하여 새 객체 반환 |
+| `merge3` | `(source, origin, target, optionsObj?) => { conflict, result }` | 3-way 병합 |
+| `omit` | `<T, K>(item: T, omitKeys: K[]) => Omit<T, K>` | 특정 key 제외 |
+| `omitByFilter` | `<T>(item: T, omitKeyFn) => T` | 조건에 맞는 key 제외 |
+| `pick` | `<T, K>(item: T, pickKeys: K[]) => Pick<T, K>` | 특정 key만 선택 |
+| `getChainValue` | `(obj, chain, optional?) => unknown` | 체인 경로로 값 조회 (예: `"a.b[0].c"`) |
+| `getChainValueByDepth` | `(obj, key, depth, optional?) => TObject[TKey]` | 같은 key로 지정된 깊이만큼 하강 |
+| `setChainValue` | `(obj, chain, value) => void` | 체인 경로로 값 설정 |
+| `deleteChainValue` | `(obj, chain) => void` | 체인 경로로 값 삭제 |
+| `clearUndefined` | `<T>(obj: T) => T` | 객체에서 undefined/null 값을 가진 key 삭제 (원본 수정) |
+| `clear` | `<T>(obj: T) => Record<string, never>` | 객체의 모든 key 삭제 (원본 수정) |
+| `nullToUndefined` | `<T>(obj: T) => T \| undefined` | null을 undefined로 변환 (재귀, 원본 수정) |
+| `unflatten` | `(flatObj) => Record<string, unknown>` | 평탄화된 객체를 중첩 객체로 변환 (`"a.b.c": 1` → `{ a: { b: { c: 1 } } }`) |
+| `keys` | `<T>(obj: T) => (keyof T)[]` | 타입 안전한 `Object.keys` |
+| `entries` | `<T>(obj: T) => Entries<T>` | 타입 안전한 `Object.entries` |
+| `fromEntries` | `<T>(entryPairs: T[]) => { [K in T[0]]: T[1] }` | 타입 안전한 `Object.fromEntries` |
+| `map` | `(obj, fn) => Record<string, TNewValue>` | 각 엔트리를 변환하여 새 객체 반환 |
+
+## Related Types
+
+### `EqualOptions`
+
+`equal()` 옵션:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `topLevelIncludes` | `string[]` | 비교할 key 목록 (최상위 레벨에만 적용) |
+| `topLevelExcludes` | `string[]` | 비교에서 제외할 key 목록 (최상위 레벨에만 적용) |
+| `ignoreArrayIndex` | `boolean` | 배열 순서를 무시할지 여부. `true`면 O(n²) 복잡도 |
+| `shallow` | `boolean` | 얕은 비교 여부. `true`면 1단계만 비교 (참조 비교) |
+
+### `MergeOptions`
+
+`merge()` 옵션:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `arrayProcess` | `"replace" \| "concat"` | 배열 처리 방식. `"replace"`: target으로 교체 (기본값), `"concat"`: 병합 (중복 제거) |
+| `useDelTargetNull` | `boolean` | target이 null일 때 해당 key를 삭제할지 여부 |
+
+### `Merge3KeyOptions`
+
+`merge3()` key별 옵션:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `keys` | `string[]` | 비교할 하위 key 목록 |
+| `excludes` | `string[]` | 비교에서 제외할 하위 key 목록 |
+| `ignoreArrayIndex` | `boolean` | 배열 순서를 무시할지 여부 |
+
+### `UndefToOptional<T>`
+
+`undefined` 타입을 가진 속성을 optional로 변환:
+
+```typescript
+// { a: string; b: string | undefined } → { a: string; b?: string | undefined }
+export type UndefToOptional<TObject> = ...
+```
+
+### `OptionalToUndef<T>`
+
+optional 속성을 필수 + `undefined` 유니온으로 변환:
+
+```typescript
+// { a: string; b?: string } → { a: string; b: string | undefined }
+export type OptionalToUndef<TObject> = ...
+```
+
+## Usage
+
+```typescript
+import { obj } from "@simplysm/core-common";
+
+// 깊은 복사
+const copied = obj.clone({ nested: { data: [1, 2, 3] } });
+
+// 깊은 비교
+const isEqual = obj.equal(a, b, { topLevelExcludes: ["updatedAt"] });
+
+// 깊은 병합
+const merged = obj.merge(defaults, overrides);
+
+// omit / pick
+const noId = obj.omit(user, ["id"]);
+const onlyName = obj.pick(user, ["name", "email"]);
+
+// 체인 경로
+const val = obj.getChainValue(data, "user.address[0].city");
+obj.setChainValue(data, "user.name", "Alice");
+
+// 객체 변환
+const mapped = obj.map(colors, (key, rgb) => [null, `rgb(${rgb})`]);
+```

package/claude/references/sd-simplysm-v14/core-common/utils/path.md

@@ -0,0 +1,30 @@
+# path
+
+경로 유틸리티 네임스페이스. Node.js `path` 모듈 대체 (브라우저 환경 지원). POSIX 스타일 경로(슬래시 `/`)만 지원한다. Windows 백슬래시(`\`)는 지원하지 않는다.
+
+```typescript
+import { path } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `join` | `(...segments: string[]) => string` | 경로 결합 (`path.join` 대체) |
+| `basename` | `(filePath: string, ext?: string) => string` | 파일명 추출 (`path.basename` 대체). ext 지정 시 해당 확장자 제거 |
+| `extname` | `(filePath: string) => string` | 파일 확장자 추출 (`path.extname` 대체). 숨김 파일(`.gitignore`)은 빈 문자열 반환 |
+
+## Usage
+
+```typescript
+import { path } from "@simplysm/core-common";
+
+path.join("/foo", "bar", "baz");  // "/foo/bar/baz"
+path.join("/foo/", "/bar/");      // "/foo/bar"
+
+path.basename("/foo/bar/file.txt");         // "file.txt"
+path.basename("/foo/bar/file.txt", ".txt"); // "file"
+
+path.extname("/foo/bar/file.txt");  // ".txt"
+path.extname("/foo/.gitignore");    // ""
+```

package/claude/references/sd-simplysm-v14/core-common/utils/primitive.md

@@ -0,0 +1,28 @@
+# primitive
+
+원시 타입 변환 유틸리티 네임스페이스.
+
+```typescript
+import { primitive } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `typeStr` | `(value: PrimitiveTypeMap[PrimitiveTypeStr]) => PrimitiveTypeStr` | 값으로부터 `PrimitiveTypeStr` 추론. 지원하지 않는 타입이면 `ArgumentError` 발생 |
+
+## Usage
+
+```typescript
+import { primitive } from "@simplysm/core-common";
+
+primitive.typeStr("hello");          // "string"
+primitive.typeStr(123);              // "number"
+primitive.typeStr(true);             // "boolean"
+primitive.typeStr(new DateTime());   // "DateTime"
+primitive.typeStr(new DateOnly());   // "DateOnly"
+primitive.typeStr(new Time());       // "Time"
+primitive.typeStr(Uuid.generate()); // "Uuid"
+primitive.typeStr(new Uint8Array()); // "Bytes"
+```

package/claude/references/sd-simplysm-v14/core-common/utils/str.md

@@ -0,0 +1,63 @@
+# str
+
+문자열 유틸리티 네임스페이스.
+
+```typescript
+import { str } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `getKoreanSuffix` | `(text, type) => string` | 받침 유무에 따라 적절한 한국어 조사 반환 |
+| `replaceFullWidth` | `(str) => string` | 전각 문자(Ａ-Ｚ, ａ-ｚ, ０-９, 전각 공백, 전각 괄호)를 반각 문자로 변환 |
+| `toPascalCase` | `(str) => string` | PascalCase로 변환 (`-`, `_`, `.` 구분자 지원) |
+| `toCamelCase` | `(str) => string` | camelCase로 변환 |
+| `toKebabCase` | `(str) => string` | kebab-case로 변환 |
+| `toSnakeCase` | `(str) => string` | snake_case로 변환 |
+| `isNullOrEmpty` | `(str: string \| undefined) => str is "" \| undefined` | 타입 가드: undefined, null, 빈 문자열이면 true |
+| `insert` | `(str, index, insertString) => string` | 특정 위치에 문자열 삽입 |
+
+## `getKoreanSuffix` — 조사 타입
+
+| `type` | 받침 있음 | 받침 없음 | 설명 |
+|--------|----------|----------|------|
+| `"을"` | 을 | 를 | 목적격 조사 |
+| `"은"` | 은 | 는 | 주격 보조사 |
+| `"이"` | 이 | 가 | 주격 조사 |
+| `"와"` | 과 | 와 | 접속 조사 |
+| `"랑"` | 이랑 | 랑 | 접속 조사 |
+| `"로"` | 으로 (ㄹ 받침은 "로") | 로 | 도구격 조사 |
+| `"라"` | 이라 | 라 | 서술격 조사 |
+
+## Usage
+
+```typescript
+import { str } from "@simplysm/core-common";
+
+// 한국어 조사
+str.getKoreanSuffix("Apple", "을"); // "를"
+str.getKoreanSuffix("책", "이");    // "이"
+str.getKoreanSuffix("파일", "을");  // "을"
+
+// 전각 → 반각
+str.replaceFullWidth("Ａ１２３"); // "A123"
+
+// 케이스 변환
+str.toPascalCase("hello-world"); // "HelloWorld"
+str.toCamelCase("HelloWorld");   // "helloWorld"
+str.toKebabCase("HelloWorld");   // "hello-world"
+str.toSnakeCase("HelloWorld");   // "hello_world"
+
+// null/empty 검사 (타입 가드)
+const name: string | undefined = getValue();
+if (str.isNullOrEmpty(name)) {
+  // name: "" | undefined
+} else {
+  // name: string (non-empty)
+}
+
+// 문자열 삽입
+str.insert("Hello World", 5, ","); // "Hello, World"
+```

package/claude/references/sd-simplysm-v14/core-common/utils/template-strings.md

@@ -0,0 +1,49 @@
+# Template Strings
+
+IDE 코드 하이라이팅 지원용 태그드 템플릿 리터럴 함수. 실제 동작은 문자열 결합 + 들여쓰기 정규화(앞뒤 빈 줄 제거, 공통 들여쓰기 제거)이다.
+
+```typescript
+export function js(strings: TemplateStringsArray, ...values: unknown[]): string;
+export function ts(strings: TemplateStringsArray, ...values: unknown[]): string;
+export function html(strings: TemplateStringsArray, ...values: unknown[]): string;
+export function tsql(strings: TemplateStringsArray, ...values: unknown[]): string;
+export function mysql(strings: TemplateStringsArray, ...values: unknown[]): string;
+export function pgsql(strings: TemplateStringsArray, ...values: unknown[]): string;
+```
+
+직접 named import로 사용한다 (네임스페이스 아님):
+
+```typescript
+import { js, ts, html, tsql, mysql, pgsql } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Description |
+|----------|-------------|
+| `js` | JavaScript 코드 하이라이팅용 |
+| `ts` | TypeScript 코드 하이라이팅용 |
+| `html` | HTML 마크업 하이라이팅용 |
+| `tsql` | MSSQL T-SQL 하이라이팅용 |
+| `mysql` | MySQL SQL 하이라이팅용 |
+| `pgsql` | PostgreSQL SQL 하이라이팅용 |
+
+## Usage
+
+```typescript
+import { ts, tsql } from "@simplysm/core-common";
+
+const code = ts`
+  interface User {
+    name: string;
+    age: number;
+  }
+`;
+// "interface User {\n  name: string;\n  age: number;\n}"
+
+const query = tsql`
+  SELECT TOP 10 *
+  FROM Users
+  WHERE Name = ${keyword}
+`;
+```

package/claude/references/sd-simplysm-v14/core-common/utils/transfer.md

@@ -0,0 +1,35 @@
+# transfer
+
+Worker 간 전송 가능한 객체 변환 유틸리티 네임스페이스. `structuredClone`이 지원하지 않는 커스텀 타입을 처리한다.
+
+```typescript
+import { transfer } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `encode` | `(obj) => { result: unknown; transferList: ArrayBuffer[] }` | Simplysm 타입을 포함한 객체를 Worker 전송 가능한 형태로 변환. 순환 참조 시 `TypeError` 발생 |
+| `decode` | `(obj) => unknown` | `encode()`로 변환된 객체를 원래 Simplysm 타입으로 복원 |
+
+## 지원 타입
+
+`Date`, `DateTime`, `DateOnly`, `Time`, `Uuid`, `RegExp`, `Error` (cause, code, detail 포함), `Uint8Array`, `Array`, `Map`, `Set`, 일반 객체
+
+`Uint8Array`는 zero-copy 전송을 위해 `ArrayBuffer`를 `transferList`에 추가한다. `SharedArrayBuffer`는 이미 공유 메모리이므로 `transferList`에 추가하지 않는다.
+
+## Usage
+
+```typescript
+import { transfer } from "@simplysm/core-common";
+
+// Worker로 데이터 전송
+const { result, transferList } = transfer.encode(data);
+worker.postMessage(result, transferList);
+
+// Worker에서 데이터 수신
+self.onmessage = (event) => {
+  const decoded = transfer.decode(event.data);
+};
+```

package/claude/references/sd-simplysm-v14/core-common/utils/wait.md

@@ -0,0 +1,35 @@
+# wait
+
+비동기 대기 유틸리티 네임스페이스.
+
+```typescript
+import { wait } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `until` | `(forwarder, milliseconds?, maxCount?) => Promise<void>` | 조건이 true가 될 때까지 대기 |
+| `time` | `(millisecond: number) => Promise<void>` | 지정된 시간만큼 대기 |
+
+## `until` — Parameters
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `forwarder` | `() => boolean \| Promise<boolean>` | - | 조건 함수. 첫 번째 호출에서 true이면 즉시 반환 |
+| `milliseconds` | `number` | `100` | 확인 간격 (ms) |
+| `maxCount` | `number` | `undefined` | 최대 시도 횟수. 초과 시 `TimeoutError` 발생. 미지정 시 무제한 |
+
+## Usage
+
+```typescript
+import { wait } from "@simplysm/core-common";
+
+// 조건 대기
+await wait.until(() => isReady);
+await wait.until(() => isReady, 100, 50); // 100ms 간격, 최대 50회
+
+// 시간 대기
+await wait.time(1000); // 1초 대기
+```

package/claude/references/sd-simplysm-v14/core-common/utils/xml.md

@@ -0,0 +1,49 @@
+# xml
+
+XML 변환 유틸리티 네임스페이스. `fast-xml-parser` 기반.
+
+```typescript
+import { xml } from "@simplysm/core-common";
+```
+
+## Functions
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `parse` | `(str, options?) => unknown` | XML 문자열을 객체로 파싱 |
+| `stringify` | `(obj, options?) => string` | 객체를 XML 문자열로 직렬화 |
+
+## `parse` — 파싱 규칙
+
+- 속성: `$` 객체에 그룹화
+- 텍스트 노드: `_` key에 저장
+- 자식 요소: 배열로 변환 (루트 요소 제외)
+
+## `parse` — options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stripTagPrefix` | `boolean` | 태그 접두사(네임스페이스) 제거 여부. 속성은 접두사 유지 |
+
+## Usage
+
+```typescript
+import { xml } from "@simplysm/core-common";
+
+// 파싱
+const result = xml.parse('<root id="1"><item>hello</item></root>');
+// { root: { $: { id: "1" }, item: [{ _: "hello" }] } }
+
+// 네임스페이스 제거
+const clean = xml.parse('<ns:root><ns:item>hello</ns:item></ns:root>', { stripTagPrefix: true });
+// { root: { item: [{ _: "hello" }] } }
+
+// 직렬화
+const str = xml.stringify({
+  root: {
+    $: { id: "1" },
+    item: [{ _: "hello" }, { _: "world" }],
+  },
+});
+// '<root id="1"><item>hello</item><item>world</item></root>'
+```

package/claude/references/sd-simplysm-v14/core-common/utils/zip-archive.md

@@ -0,0 +1,77 @@
+# ZipArchive
+
+ZIP 파일 처리 클래스. ZIP 파일의 읽기, 쓰기, 압축, 해제를 처리한다. 동일 파일의 중복 해제를 방지하기 위해 내부 캐싱을 사용한다. `@zip.js/zip.js` 기반.
+
+```typescript
+import { ZipArchive } from "@simplysm/core-common";
+
+export class ZipArchive {
+  constructor(data?: Blob | Bytes);
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `extractAll` | method | `(progressCallback?) => Promise<Map<string, Bytes \| undefined>>` | 모든 파일 추출 |
+| `get` | method | `(fileName: string) => Promise<Bytes \| undefined>` | 특정 파일 추출. 내부 캐시 활용 |
+| `exists` | method | `(fileName: string) => Promise<boolean>` | 파일 존재 여부 확인 |
+| `write` | method | `(fileName: string, bytes: Bytes) => void` | 파일 쓰기 (캐시에 저장) |
+| `compress` | method | `() => Promise<Bytes>` | 캐시된 파일을 ZIP으로 압축 |
+| `close` | method | `() => Promise<void>` | 리더 닫기 및 캐시 비우기 |
+
+## Related Types
+
+### `ZipArchiveProgress`
+
+`extractAll()` 진행률 콜백의 파라미터 타입:
+
+```typescript
+export interface ZipArchiveProgress {
+  fileName: string;
+  totalSize: number;
+  extractedSize: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `fileName` | `string` | 현재 처리 중인 파일명 |
+| `totalSize` | `number` | 전체 파일 크기 (바이트) |
+| `extractedSize` | `number` | 현재까지 추출된 크기 (바이트) |
+
+## Usage
+
+```typescript
+import { ZipArchive } from "@simplysm/core-common";
+
+// ZIP 파일 읽기
+const archive = new ZipArchive(zipBytes);
+try {
+  const content = await archive.get("file.txt");
+} finally {
+  await archive.close();
+}
+
+// ZIP 파일 생성
+const newArchive = new ZipArchive();
+try {
+  newArchive.write("file.txt", textBytes);
+  newArchive.write("data.json", jsonBytes);
+  const zipBytes = await newArchive.compress();
+} finally {
+  await newArchive.close();
+}
+
+// 모든 파일 추출 (진행률 보고 포함)
+const archive2 = new ZipArchive(zipBytes);
+try {
+  const files = await archive2.extractAll((progress) => {
+    const pct = (progress.extractedSize / progress.totalSize * 100).toFixed(1);
+    console.log(`${progress.fileName}: ${pct}%`);
+  });
+} finally {
+  await archive2.close();
+}
+```

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

@@ -0,0 +1,59 @@
+# @simplysm/core-node
+
+> Node.js 전용 코어 유틸리티 패키지. 파일 시스템 조작, 자식 프로세스 실행, 경로 처리, 파일 감시, Worker thread 래퍼, consola 로깅 설정을 제공한다.
+> `@simplysm/core-common`에 의존하며, Node.js 런타임에서만 동작한다.
+
+## Installation
+
+```bash
+npm install @simplysm/core-node
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 파일 읽기/쓰기/복사/삭제 | [fsx](./utils/fsx.md) |
+| 자식 프로세스 실행 | [cpx](./utils/cpx.md) |
+| 경로 변환/비교 | [pathx](./utils/pathx.md) |
+| 파일 변경 감시 | [FsWatcher](./features/fs-watcher.md) |
+| 로깅 설정 | [setupConsola](./logging/setup-consola.md) |
+| 커스텀 터미널 로깅 | [PrettyReporter](./logging/pretty-reporter.md) |
+| 커스텀 파일 로깅 | [createFileReporter](./logging/create-file-reporter.md) |
+| 워커 스레드로 작업 분리 | [Worker](./worker/worker.md) + [createWorker](./worker/create-worker.md) |
+
+## API Overview
+
+### Utils
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`fsx`](./utils/fsx.md) | namespace | 파일 시스템 작업(존재 확인, 읽기/쓰기, 복사, 삭제, glob)이 필요할 때 |
+| [`cpx`](./utils/cpx.md) | namespace | 외부 명령어나 자식 프로세스를 실행할 때 |
+| [`pathx`](./utils/pathx.md) | namespace | 경로를 POSIX 스타일로 변환하거나, 경로 간 관계(하위 경로 여부)를 확인할 때 |
+
+### Features
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`FsWatcher`](./features/fs-watcher.md) | class | 파일/디렉토리 변경을 지속적으로 감시하고 이벤트를 받아야 할 때 |
+
+### Logging
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`setupConsola`](./logging/setup-consola.md) | function | 서버/CLI 시작 시 consola 로깅을 환경에 맞게 자동 구성할 때 |
+| [`PrettyReporter`](./logging/pretty-reporter.md) | class | 터미널에 아이콘/색상이 포함된 포맷으로 로그를 출력할 때 |
+| [`createFileReporter`](./logging/create-file-reporter.md) | function | 로그를 JSON 라인 파일로 기록하고 날짜별 로테이션이 필요할 때 |
+
+### Worker
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`Worker`](./worker/worker.md) | const | 메인 스레드에서 타입 안전하게 워커 메서드를 호출할 때 |
+| [`createWorker`](./worker/create-worker.md) | function | 워커 파일에서 메서드/이벤트를 등록할 때 (`Worker`와 쌍으로 사용) |
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 브라우저 환경 → `@simplysm/core-browser`
+- 플랫폼 중립 유틸리티(DateTime, UUID, EventEmitter 등) → `@simplysm/core-common`