@simplysm/sd-claude 14.0.47 → 14.0.49

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

@@ -1,180 +0,0 @@
-# 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

@@ -1,176 +0,0 @@
-# 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/utilities-cpx.md

@@ -1,194 +0,0 @@
-# Utilities — cpx
-
-`cpx`는 `@simplysm/core-node`에서 네임스페이스로 re-export되는 자식 프로세스 실행 유틸리티 모음이다.
-
-```typescript
-import { cpx } from "@simplysm/core-node";
-```
-
----
-
-## `SpawnResult`
-
-프로세스 실행 결과.
-
-```typescript
-export interface SpawnResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `stdout` | `string` | 표준 출력 문자열. stdio가 "inherit"이면 빈 문자열 |
-| `stderr` | `string` | 표준 에러 문자열. stdio가 "inherit"이면 빈 문자열 |
-| `exitCode` | `number` | 프로세스 종료 코드 |
-
----
-
-## `SpawnProcess`
-
-`spawn()`의 반환 타입. `PromiseLike<SpawnResult>`를 구현하여 `await`로 결과를 기다리거나, `kill()`로 프로세스를 종료할 수 있다.
-
-```typescript
-export class SpawnProcess implements PromiseLike<SpawnResult> {
-  get pid(): number | undefined;
-  then(onfulfilled?, onrejected?): Promise<...>;
-  catch(onrejected?): Promise<...>;
-  kill(signal?: NodeJS.Signals | number): boolean;
-}
-```
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `pid` | `number \| undefined` | 프로세스 ID |
-| `then` | method | PromiseLike 구현 |
-| `catch` | method | PromiseLike 구현 |
-| `kill` | method | 프로세스에 시그널 전송. 성공 여부 반환 |
-
----
-
-## `spawn`
-
-비동기 자식 프로세스를 실행한다. `SpawnProcess`를 반환하므로 `await`로 결과를 기다리거나 `kill()`로 종료할 수 있다.
-
-기본적으로 `exitCode !== 0`이면 reject된다. `options.reject: false`를 지정하면 항상 resolve된다.
-
-```typescript
-export function spawn(
-  cmd: string,
-  args: string[],
-  options?: SpawnOptions & { reject?: boolean },
-): SpawnProcess
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `cmd` | `string` | 실행할 명령어 |
-| `args` | `string[]` | 명령어 인수 |
-| `options` | `SpawnOptions & { reject?: boolean }` | Node.js `child_process.spawn` 옵션 + `reject` 플래그 |
-| `options.reject` | `boolean` | false이면 exitCode != 0이어도 resolve. 기본값 true |
-
-```typescript
-// 기본 사용
-const result = await cpx.spawn("git", ["status"], { cwd: "/project" });
-
-// 종료 가능한 프로세스
-const proc = cpx.spawn("long-running-cmd", []);
-proc.kill();
-
-// 출력 직접 표시, 오류 무시
-await cpx.spawn("make", ["build"], { stdio: "inherit", reject: false });
-```
-
----
-
-## `spawnSync`
-
-동기 자식 프로세스를 실행한다. `SpawnResult`를 직접 반환한다.
-
-기본적으로 `exitCode !== 0`이면 throw된다. `options.reject: false`를 지정하면 항상 반환된다.
-
-```typescript
-export function spawnSync(
-  cmd: string,
-  args: string[],
-  options?: SpawnSyncOptions & { reject?: boolean },
-): SpawnResult
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `cmd` | `string` | 실행할 명령어 |
-| `args` | `string[]` | 명령어 인수 |
-| `options` | `SpawnSyncOptions & { reject?: boolean }` | Node.js `child_process.spawnSync` 옵션 + `reject` 플래그 |
-| `options.reject` | `boolean` | false이면 exitCode != 0이어도 반환. 기본값 true |
-
----
-
-## `getSystemEncoding`
-
-시스템 인코딩을 감지한다. 결과는 캐시된다.
-
-- Windows: `chcp` 명령으로 코드 페이지 번호를 읽어 인코딩 이름으로 변환
-- Linux/macOS: `LANG` 또는 `LC_ALL` 환경변수에서 추출
-- 감지 실패 시 `"utf-8"` 반환
-
-```typescript
-export function getSystemEncoding(): string
-```
-
----
-
-## `codePageToEncoding`
-
-Windows 코드 페이지 번호를 인코딩 이름으로 변환한다.
-
-```typescript
-export function codePageToEncoding(codePage: number): string
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `codePage` | `number` | Windows 코드 페이지 번호 (예: 65001, 949) |
-
-**반환**: 인코딩 이름 (예: `"utf-8"`, `"euc-kr"`). 알 수 없는 코드 페이지는 `"utf-8"` 반환.
-
-지원하는 코드 페이지:
-
-| Code Page | Encoding |
-|-----------|----------|
-| 65001 | utf-8 |
-| 949 | euc-kr |
-| 932 | shift-jis |
-| 936 | gbk |
-| 950 | big5 |
-| 1252 | windows-1252 |
-| 1251 | windows-1251 |
-| 1250 | windows-1250 |
-| 874 | windows-874 |
-
----
-
-## `resetEncodingCache`
-
-`getSystemEncoding()`이 캐시한 인코딩 값을 초기화한다. 다음 호출 시 재감지한다.
-
-```typescript
-export function resetEncodingCache(): void
-```
-
----
-
-## `decodeBytes`
-
-`Uint8Array`를 시스템 인코딩으로 문자열로 디코딩한다. UTF-8로 먼저 시도하고 실패 시 시스템 인코딩을 사용한다.
-
-```typescript
-export function decodeBytes(raw: Uint8Array, systemEncoding?: string): string
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `raw` | `Uint8Array` | 디코딩할 바이트 배열 |
-| `systemEncoding` | `string` | 사용할 인코딩. 생략 시 `getSystemEncoding()` 결과 사용 |
-
----
-
-## `resolveStdioPipe`
-
-Node.js `stdio` 옵션에서 stdout/stderr가 pipe인지 여부를 추출한다.
-
-```typescript
-export function resolveStdioPipe(
-  stdio: SpawnOptions["stdio"],
-): { stdout: boolean; stderr: boolean }
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `stdio` | `SpawnOptions["stdio"]` | Node.js spawn의 stdio 옵션 |
-
-**반환**: `{ stdout: boolean, stderr: boolean }`. `stdio`가 `"pipe"` 또는 `null`/`undefined`이면 둘 다 `true`.