@simplysm/sd-claude 14.0.42 → 14.0.44

package/claude/references/sd-simplysm14/core-node/docs/logging.md

@@ -0,0 +1,180 @@
+# Logging (consola)
+
+## `setupConsola`
+
+환경에 따라 consola의 reporter를 자동으로 구성한다.
+
+```typescript
+export function setupConsola(opts?: SetupConsolaOptions): void
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opts` | SetupConsolaOptions (optional) | 옵션 객체 |
+
+### SetupConsolaOptions
+
+```typescript
+export interface SetupConsolaOptions {
+  cli?: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cli` | boolean (optional) | CLI 모드 여부. true이면 프로덕션에서도 PrettyReporter 사용 (기본값: false) |
+
+### Behavior by Environment
+
+| Condition | Reporters | Debug Level |
+|-----------|-----------|------------|
+| Production (not DEV, not cli) | FileReporter | debug 레벨 포함 |
+| Development or cli + SD_DEBUG | PrettyReporter | debug 레벨 포함 |
+| Development or cli (일반) | FileReporter + PrettyReporter (info 이하) | debug는 파일에만 기록 |
+
+**Note**: 
+- `DEV` 환경변수 또는 `SD_DEBUG` 환경변수의 값을 `parseBoolEnv()`로 파싱한다.
+- `env("...")`는 @simplysm/core-common의 함수를 사용한다.
+
+**Example**:
+```typescript
+// 환경별 자동 구성
+setupConsola();
+
+// CLI 모드
+setupConsola({ cli: true });
+```
+
+---
+
+## `withMaxLevel`
+
+Consola reporter를 지정된 로그 레벨 이하로 제한하는 래퍼.
+
+```typescript
+export function withMaxLevel(reporter: ConsolaReporter, maxLevel: number): ConsolaReporter
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `reporter` | ConsolaReporter | 원본 reporter |
+| `maxLevel` | number | 최대 로그 레벨 (LogLevels 상수 참고) |
+
+**Return**: 제한된 reporter
+
+**Consola LogLevels**:
+```
+0: fatal
+1: error
+2: warn
+3: info
+4: success
+5: log
+6: debug
+7: trace
+```
+
+**Example**:
+```typescript
+import { withMaxLevel, PrettyReporter, LogLevels } from "@simplysm/core-node";
+
+// info 레벨 이하만 출력
+const limitedReporter = withMaxLevel(new PrettyReporter(), LogLevels.info);
+```
+
+---
+
+## `PrettyReporter`
+
+터미널 출력용 consola reporter.
+
+아이콘, 색상, 에러 스택 포맷팅을 지원한다.
+
+```typescript
+export class PrettyReporter implements ConsolaReporter {
+  log(logObj: LogObject, ctx: { options: ConsolaOptions }): void
+}
+```
+
+**Features**:
+- 로그 레벨별 아이콘 표시
+- 컬러 출력
+- 에러 객체의 스택 포맷팅
+- 타임스탐프 표시 (선택적)
+
+**Example**:
+```typescript
+import { PrettyReporter } from "@simplysm/core-node";
+import consola from "consola";
+
+consola.options.reporters = [new PrettyReporter()];
+```
+
+---
+
+## `createFileReporter`
+
+파일 기반 consola reporter를 생성한다.
+
+JSON 라인 형식으로 로그를 기록하며, 날짜별 로테이션과 크기 제한을 지원한다.
+
+```typescript
+export function createFileReporter(options?: FileReporterOptions): ConsolaReporter
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | FileReporterOptions (optional) | 옵션 객체 |
+
+### FileReporterOptions
+
+```typescript
+export interface FileReporterOptions {
+  maxSize?: number;    // 로그 파일 최대 크기 (바이트, 기본값: 20MB)
+  maxDays?: number;    // 로그 보관 기간 (일, 기본값: 14일)
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `maxSize` | number (optional) | 단일 로그 파일의 최대 크기 (바이트). 초과 시 롤오버됨 (기본값: 20MB = 20 * 1024 * 1024) |
+| `maxDays` | number (optional) | 로그 파일 보관 기간 (일). 이 기간이 지난 로그는 자동 삭제됨 (기본값: 14) |
+
+### Log File Format
+
+- 디렉토리: `.logs/`
+- 파일명 형식: `app.YYYY-MM-DD.log`
+- 내용: JSON 라인 (각 로그는 하나의 JSON 객체)
+
+**Example**:
+```typescript
+import { createFileReporter } from "@simplysm/core-node";
+import consola from "consola";
+
+const fileReporter = createFileReporter({
+  maxSize: 10 * 1024 * 1024,  // 10MB
+  maxDays: 7,                  // 7일 보관
+});
+
+consola.options.reporters = [fileReporter];
+```
+
+---
+
+## Integration with setupConsola
+
+setupConsola()는 내부적으로 PrettyReporter와 createFileReporter()를 사용하여 환경에 맞게 reporters를 구성한다.
+
+```typescript
+import { setupConsola } from "@simplysm/core-node";
+import consola from "consola";
+
+// 자동 구성
+setupConsola();
+
+// 이후 consola를 정상적으로 사용 가능
+consola.info("Application started");
+consola.debug("Debug information");
+```
+
+**주의**: consola는 프로젝트 루트의 `console.*` 금지 규칙을 대체하는 표준 로깅 수단이다.

package/claude/references/sd-simplysm14/core-node/docs/path.md

@@ -0,0 +1,176 @@
+# Path (pathx)
+
+## `PosixPath`
+
+POSIX 스타일(슬래시) 경로임을 타입 수준에서 보장하는 브랜드 타입.
+
+posix() 또는 posixResolve()를 통해서만 생성할 수 있다.
+
+```typescript
+export type PosixPath = string & {
+  [POSIX]: never;
+}
+```
+
+**Note**: 일반 문자열을 강제로 PosixPath로 캐스팅할 수 없다. posix() 또는 posixResolve()를 반드시 사용해야 한다.
+
+---
+
+## `posix`
+
+경로를 POSIX 스타일(슬래시)로 변환한다.
+
+경로 결합이나 resolve는 수행하지 않으며, 단순히 백슬래시를 슬래시로 바꾼다.
+
+```typescript
+export function posix(p: string): PosixPath
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `p` | string | 변환할 경로 |
+
+**Return**: PosixPath (슬래시로 정규화된 경로)
+
+**Example**:
+```typescript
+posix("C:\\Users\\test"); // "C:/Users/test"
+posix("./relative/path"); // "./relative/path"
+```
+
+---
+
+## `posixResolve`
+
+절대 경로로 resolve한 뒤 POSIX 스타일로 변환한다.
+
+```typescript
+export function posixResolve(...args: string[]): PosixPath
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `...args` | string[] | resolve할 경로 세그먼트 (node:path.resolve와 동일) |
+
+**Return**: PosixPath (절대 경로, 슬래시로 정규화)
+
+**Example**:
+```typescript
+posixResolve("/base", "sub", "file.txt"); // "/base/sub/file.txt" (Unix 환경)
+posixResolve("relative/path"); // "/home/user/relative/path" (절대 경로로 resolve됨)
+```
+
+---
+
+## `changeFileDirectory`
+
+파일 경로의 디렉토리를 변경한다.
+
+```typescript
+export function changeFileDirectory(
+  filePath: string,
+  fromDirectory: string,
+  toDirectory: string,
+): string
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 파일 경로 |
+| `fromDirectory` | string | 현재 디렉토리 |
+| `toDirectory` | string | 새 디렉토리 |
+
+**Return**: 새 디렉토리로 변경된 파일 경로
+
+**Throws**: filePath가 fromDirectory 내부에 없는 경우 ArgumentError 발생
+
+**Example**:
+```typescript
+changeFileDirectory("/a/b/c.txt", "/a/b", "/x");
+// → "/x/c.txt"
+
+changeFileDirectory("/a/b/sub/c.txt", "/a/b", "/x");
+// → "/x/sub/c.txt"
+```
+
+---
+
+## `basenameWithoutExt`
+
+확장자를 제외한 파일명(basename)을 반환한다.
+
+```typescript
+export function basenameWithoutExt(filePath: string): string
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 파일 경로 |
+
+**Return**: 확장자를 제외한 파일명
+
+**Example**:
+```typescript
+basenameWithoutExt("file.txt"); // "file"
+basenameWithoutExt("/path/to/file.spec.ts"); // "file.spec"
+basenameWithoutExt("/path/to/file"); // "file"
+```
+
+---
+
+## `isChildPath`
+
+childPath가 parentPath의 하위 경로인지 확인한다.
+
+동일한 경로이면 false를 반환한다.
+
+경로는 내부적으로 posixResolve()를 사용하여 정규화되며, POSIX 슬래시(/)를 구분자로 사용하여 비교한다.
+
+```typescript
+export function isChildPath(childPath: string, parentPath: string): boolean
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `childPath` | string | 자식으로 확인할 경로 |
+| `parentPath` | string | 부모로 확인할 경로 |
+
+**Return**: childPath가 parentPath의 하위 경로이면 true, 동일하거나 상위 경로이면 false
+
+**Example**:
+```typescript
+isChildPath("/a/b/c", "/a/b"); // true
+isChildPath("/a/b", "/a/b/c"); // false
+isChildPath("/a/b", "/a/b"); // false (동일 경로)
+isChildPath("/a/bc", "/a/b"); // false (접두사 매칭이 아님)
+```
+
+---
+
+## `filterByTargets`
+
+대상 경로 목록을 기반으로 파일을 필터링한다.
+
+대상 경로와 일치하거나 하위에 있는 파일을 포함한다.
+
+```typescript
+export function filterByTargets(files: string[], targets: string[], cwd: string): string[]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `files` | string[] | 필터링할 파일 경로 배열. 주의: cwd 하위의 절대 경로여야 한다. cwd 외부의 경로는 상대 경로(../)로 변환되어 처리된다. |
+| `targets` | string[] | 대상 경로 (cwd 기준 상대 경로, POSIX 스타일 권장) |
+| `cwd` | string | 현재 작업 디렉토리 (절대 경로) |
+
+**Return**: targets가 비어있으면 files를 그대로 반환; 그렇지 않으면 대상 경로 하위의 파일만 반환
+
+**Example**:
+```typescript
+const files = ["/proj/src/a.ts", "/proj/src/b.ts", "/proj/tests/c.ts"];
+filterByTargets(files, ["src"], "/proj");
+// → ["/proj/src/a.ts", "/proj/src/b.ts"]
+
+filterByTargets(files, [], "/proj");
+// → ["/proj/src/a.ts", "/proj/src/b.ts", "/proj/tests/c.ts"] (targets가 비어있음)
+```

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

@@ -0,0 +1,334 @@
+# Worker Threads
+
+## `Worker`
+
+Worker thread 프록시를 생성하는 팩토리 객체.
+
+```typescript
+export const Worker: {
+  create<TModule extends WorkerModule>(
+    workerPath: string,
+    options?: Omit<WorkerRawOptions, "stdout" | "stderr">,
+  ): WorkerProxy<TModule>
+}
+```
+
+### Static Method
+
+#### `create`
+
+워커 파일을 로드하고 타입 안전한 프록시를 생성한다.
+
+```typescript
+static create<TModule extends WorkerModule>(
+  workerPath: string,
+  options?: Omit<WorkerRawOptions, "stdout" | "stderr">,
+): WorkerProxy<TModule>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `workerPath` | string | 워커 파일 경로 (.ts 또는 .js). 개발 환경에서는 .ts를 권장하며, 내부적으로 tsx를 통해 실행된다. |
+| `options` | WorkerRawOptions (optional) | Worker thread 옵션. stdout/stderr는 자동으로 메인 프로세스로 파이프된다. |
+
+**Return**: WorkerProxy<TModule> - 타입 안전한 워커 프록시
+
+**Development vs Production**:
+- **.ts 파일**: `lib/worker-dev-proxy.js`를 통해 tsx로 실행됨
+- **.js 파일**: 직접 Worker로 로드됨
+
+**Example**:
+```typescript
+import { Worker } from "@simplysm/core-node";
+import type * as MyWorker from "./worker";
+
+const worker = Worker.create<typeof MyWorker>("./worker.ts");
+
+// 메서드 호출 (타입 안전)
+const result = await worker.add(10, 20);
+
+// 이벤트 수신 (타입 안전)
+worker.on("progress", (value) => {
+  console.log(`Progress: ${value}%`);
+});
+
+await worker.terminate();
+```
+
+---
+
+## `createWorker`
+
+워커 측에서 호출하여 메서드와 이벤트를 등록하는 팩토리 함수.
+
+```typescript
+export function createWorker<
+  TMethods extends Record<string, (...args: any[]) => unknown>,
+  TEvents extends Record<string, unknown> = Record<string, never>,
+>(
+  methods: TMethods,
+): {
+  send<TEventName extends keyof TEvents & string>(event: TEventName, data?: TEvents[TEventName]): void;
+  __methods: TMethods;
+  __events: TEvents;
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `methods` | Record<string, function> | 워커가 제공할 메서드 객체 |
+
+**Type Parameters**:
+- `TMethods`: 메서드 타입
+- `TEvents`: 이벤트 타입 (기본값: 빈 객체)
+
+**Return**: sender 객체. `send()` 메서드로 이벤트를 발송하고, export default로 내보낸다.
+
+**Example**:
+```typescript
+// worker.ts
+import { createWorker } from "@simplysm/core-node";
+
+interface MyEvents {
+  progress: number;
+}
+
+const methods = {
+  add: (a: number, b: number) => a + b,
+  multiply: (a: number, b: number) => a * b,
+};
+
+const sender = createWorker<typeof methods, MyEvents>(methods);
+
+export default sender;
+```
+
+---
+
+## `WorkerProxy`
+
+Worker.create()가 반환하는 프록시 타입.
+
+Promise화된 메서드 + 이벤트 리스너 + 종료 메서드를 제공한다.
+
+```typescript
+export type WorkerProxy<TModule extends WorkerModule> = PromisifyMethods<
+  TModule["default"]["__methods"]
+> & {
+  on<TEventName extends keyof TModule["default"]["__events"] & string>(
+    event: TEventName,
+    listener: (data: TModule["default"]["__events"][TEventName]) => void,
+  ): void;
+
+  off<TEventName extends keyof TModule["default"]["__events"] & string>(
+    event: TEventName,
+    listener: (data: TModule["default"]["__events"][TEventName]) => void,
+  ): void;
+
+  terminate(): Promise<void>;
+}
+```
+
+### Methods
+
+| Name | Signature | Description |
+|------|-----------|-------------|
+| `[메서드명]` | `(...args): Promise<R>` | 워커의 메서드. 비동기로 Promise를 반환한다. |
+| `on` | `<E extends EventName>(event, listener): void` | 워커 이벤트 리스너를 등록한다. |
+| `off` | `<E extends EventName>(event, listener): void` | 워커 이벤트 리스너를 해제한다. |
+| `terminate` | `(): Promise<void>` | 워커를 종료한다. |
+
+**Example**:
+```typescript
+const worker = Worker.create<typeof MyWorker>("./worker.ts");
+
+// 메서드 호출
+const sum = await worker.add(10, 20); // 30
+const product = await worker.multiply(5, 6); // 30
+
+// 이벤트 리스너 등록
+worker.on("progress", (value) => {
+  console.log(`Progress: ${value}%`);
+});
+
+// 이벤트 리스너 제거
+worker.off("progress", handler);
+
+// 워커 종료
+await worker.terminate();
+```
+
+---
+
+## `PromisifyMethods`
+
+메서드의 반환값을 Promise로 감싸는 매핑 타입.
+
+```typescript
+export type PromisifyMethods<TMethods> = {
+  [K in keyof TMethods]: TMethods[K] extends (...args: infer P) => infer R
+    ? (...args: P) => Promise<Awaited<R>>
+    : never;
+}
+```
+
+**Note**: 워커 메서드는 postMessage 기반으로 동작하여 항상 비동기이므로, 동기 메서드 타입도 `Promise<Awaited<R>>`로 변환된다.
+
+**Example**:
+```typescript
+// 원본
+interface Methods {
+  add: (a: number, b: number) => number;
+  process: (data: string) => Promise<Result>;
+}
+
+// PromisifyMethods 적용 후
+type ProxiedMethods = {
+  add: (a: number, b: number) => Promise<number>;
+  process: (data: string) => Promise<Result>;
+}
+```
+
+---
+
+## `WorkerModule`
+
+createWorker()가 반환하는 워커 모듈의 타입 구조.
+
+```typescript
+export interface WorkerModule {
+  default: {
+    __methods: Record<string, (...args: any[]) => unknown>;
+    __events: Record<string, unknown>;
+  };
+}
+```
+
+**Usage**:
+```typescript
+import type * as MyWorker from "./worker";
+
+const worker = Worker.create<typeof MyWorker>("./worker.ts");
+```
+
+---
+
+## `WorkerRequest`
+
+메인 프로세스에서 워커로 보내는 요청 메시지.
+
+```typescript
+export interface WorkerRequest {
+  id: string;
+  method: string;
+  params: unknown[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | 요청의 고유 ID (응답과 매칭하는 데 사용) |
+| `method` | string | 호출할 메서드명 |
+| `params` | unknown[] | 메서드 인자 배열 |
+
+---
+
+## `WorkerResponse`
+
+워커에서 메인 프로세스로 보내는 응답 메시지.
+
+Discriminated union 타입으로, 다음 중 하나의 형태를 가진다:
+
+```typescript
+export type WorkerResponse =
+  | {
+      request: WorkerRequest;
+      type: "return";
+      body?: unknown;
+    }
+  | {
+      request: WorkerRequest;
+      type: "error";
+      body: Error;
+    }
+  | {
+      type: "event";
+      event: string;
+      body?: unknown;
+    }
+  | {
+      type: "log";
+      body: string;
+    }
+```
+
+| Variant | Description |
+|---------|-------------|
+| `return` | 메서드 실행 성공 결과 |
+| `error` | 메서드 실행 중 에러 발생 |
+| `event` | 워커에서 발송한 이벤트 (request 없음, event 이름과 body 포함) |
+| `log` | 워커의 stdout.write 출력 (string body) |
+
+---
+
+## Complete Example
+
+### worker.ts (워커 파일)
+
+```typescript
+import { createWorker } from "@simplysm/core-node";
+
+interface MyEvents {
+  progress: number;
+  done: { result: number };
+}
+
+const methods = {
+  compute: async (n: number) => {
+    const sender = createWorker<typeof methods, MyEvents>(methods);
+    
+    let result = 0;
+    for (let i = 0; i <= n; i++) {
+      result += i;
+      // 진행률 보고
+      sender.send("progress", (i / n) * 100);
+    }
+    
+    sender.send("done", { result });
+    return result;
+  },
+};
+
+const sender = createWorker<typeof methods, MyEvents>(methods);
+export default sender;
+```
+
+### main.ts (메인 파일)
+
+```typescript
+import { Worker } from "@simplysm/core-node";
+import type * as MyWorker from "./worker";
+
+async function main() {
+  const worker = Worker.create<typeof MyWorker>("./worker.ts");
+
+  // 진행률 수신
+  worker.on("progress", (value) => {
+    console.log(`Progress: ${value.toFixed(1)}%`);
+  });
+
+  // 완료 신호 수신
+  worker.on("done", ({ result }) => {
+    console.log(`Done! Result: ${result}`);
+  });
+
+  // 메서드 호출
+  const result = await worker.compute(100);
+  console.log(`Final result: ${result}`);
+
+  // 워커 종료
+  await worker.terminate();
+}
+
+main().catch(console.error);
+```