@simplysm/sd-claude 14.0.76 → 14.0.77

package/claude/references/sd-simplysm14/apis/orm-node/README.md

@@ -66,4 +66,4 @@ dialect 분기 union. 공통 필드: `host`, `port?`, `username`, `password`, `d
 new NodeDbContextExecutor(config: DbConnConfig)
 ```
 
-`DbContextExecutor` 구현. `connect` 시 내부에서 `createDbConn` + `conn.connect()` 수행. `executeDefs(defs, resultMetas?)` 는 `@simplysm/orm-common` 의 `createQueryBuilder` + `parseQueryResult` 를 사용해 `QueryDef[]` → SQL → 파싱 결과. `resultMetas` 가 전부 `null` 인 경우 단일 결합 SQL 1회로 묶어 실행. 미연결 상태에서 메서드 호출 시 `DB_CONN_ERRORS.NOT_CONNECTED` SdError throw.
+`DbContextExecutor` 구현. `connect` 시 내부에서 `createDbConn` + `conn.connect()` 수행. `executeDefs(defs, resultMetas?)` 는 `@simplysm/orm-common` 의 `createQueryBuilder` + `parseQueryResult` 를 사용해 `QueryDef[]` → SQL → 파싱 결과. `resultMetas` 가 전부 `null` 인 경우 단일 결합 SQL 1회로 묶어 실행하고 `defs.length` 개의 빈 배열 반환(결과 불필요 케이스 최적화). 미연결 상태에서 메서드 호출 시 `DB_CONN_ERRORS.NOT_CONNECTED` SdError throw.

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

@@ -1,9 +1,32 @@
 # @simplysm/sd-claude
 
-Claude Code 셋업 자산(`.claude/` 의 sd-* 스킬·룰·훅) 배포 및 `sd-claude` CLI 제공 패키지.
+Claude Code 셋업 자산(`.claude/` 의 sd-* 스킬·룰·훅) 배포 및 `sd-claude` CLI 제공 패키지. 코드 API 없음 — 외부 import 가능한 라이브러리 심볼 미노출.
 
-코드 API 없음 (npm 배포용). 외부에서 import 할 수 있는 라이브러리 심볼은 노출하지 않는다.
+## 사용 트리거 인덱스
 
-- `bin`: `sd-claude` — `auth save` (현재 Claude 계정 저장) / `auth switch` (저장된 계정 목록에서 선택해 전환).
-- `postinstall`: 패키지 설치 시 `claude/` 의 sd-\* 에셋을 소비 프로젝트 루트의 `.claude/` 로 복사 (기존 sd-\* 항목은 정리 후 재복사, `settings.json`·`simplysm.json` 포함).
-- `prepack`: 배포 전 워크스페이스의 `.claude/` → `packages/sd-claude/claude/` 증분 복사 (mtime+size 비교, `evals/`·`SKILL.eval.md`·`eval_*` 제외).
+- 현재 로그인된 Claude 계정을 프로필로 저장 → [auth save](#cli-sd-claude)
+- 저장된 다른 Claude 계정으로 전환 → [auth switch](#cli-sd-claude)
+- 소비 프로젝트 설치 시 `.claude/` 자산 자동 배치 → [postinstall](#패키지-훅)
+- 워크스페이스 `.claude/` 변경분을 패키지 `claude/` 로 동기화(배포 직전) → [prepack / sync](#패키지-훅)
+
+## CLI `sd-claude`
+
+`bin: sd-claude` → `scripts/cli.mjs`. 사용법: `sd-claude <subcommand> <action>`.
+
+- `auth save`: 현재 `claude auth status` 의 `orgName` 을 프로필 키로, `~/.claude/.credentials.json` 의 `claudeAiOauth.refreshToken` 과 `~/.claude/statusline-cache.json` 의 사용량 스냅샷을 `~/.claude/profiles.json` 에 저장하고 `current` 를 해당 프로필로 설정. orgName 또는 refreshToken 미획득 시 stderr 출력 후 exit 1.
+- `auth switch`: `profiles.json` 의 계정 목록을 번호 + 현재 마커(`*`) + 사용량(현재 계정은 live, 그 외는 저장 시점) 으로 출력. 번호 입력으로 대상 선택 → 현재 계정의 최신 refreshToken·사용량을 백업 저장 → `CLAUDE_CODE_OAUTH_REFRESH_TOKEN`/`CLAUDE_CODE_OAUTH_SCOPES` 환경변수로 `claude auth login` 을 spawn → 갱신된 refreshToken 저장 + `current` 업데이트. TTY 아니면 exit 1.
+- 그 외 인자: 사용법 출력 후 exit 1.
+
+저장 위치 식별자 풀이:
+- `~/.claude/profiles.json`: `{ current: string, accounts: { [orgName]: { refreshToken, usage } } }` 구조. 패키지가 관리.
+- `~/.claude/.credentials.json`: Claude Code 본체가 관리. `claudeAiOauth.refreshToken` 만 읽음.
+- `~/.claude/statusline-cache.json`: Claude Code 본체가 관리. `rate_limits.five_hour` / `seven_day` 의 `used_percentage` + `resets_at` 만 읽음.
+
+## 패키지 훅
+
+- `postinstall` (`scripts/postinstall.mjs`): 소비 프로젝트의 `node_modules` 설치 시 자동 실행. `INIT_CWD` 또는 `node_modules` 경로 역추적으로 프로젝트 루트 결정 → `<projectRoot>/.claude/` 의 기존 sd-* 항목(root 1단계 + 하위 디렉토리 1단계의 `^sd[-_]` 매칭) 정리 후 패키지 `claude/` 의 동일 항목 + `settings.json` + `simplysm.json` 을 복사. 소비 프로젝트가 `name: "simplysm"` 이고 메이저 버전이 같으면 skip(모노레포 자기 자신 보호). 실패해도 throw 하지 않음(install 차단 방지).
+- `prepack` (`scripts/sync.mjs`): `pnpm pub`/`npm pack` 직전 실행. 워크스페이스 루트(`../../`)의 `.claude/` 에서 sd-* 항목(+ `settings.json`/`simplysm.json`) 을 패키지 `claude/` 로 증분 복사. 동일 파일은 mtime+size 비교로 skip, 변경분은 unlink 후 copy + src mtime 보존, src 에 없는 dest 항목은 prune. 제외: `evals/` 하위, 파일명 `SKILL.eval.md`, `eval_*` 접두 파일. (Windows EPERM 회피 위해 일괄 rmSync 미사용.)
+
+식별자 풀이:
+- sd-* 항목 스캔 범위: 디렉토리 root + 1단계 하위. 정규식 `^sd[-_]`. 즉 `.claude/skills/sd-foo/`, `.claude/rules/sd-bar.md`, `.claude/sd-baz/` 등 매칭.
+- watch 훅 연동: 모노레포에서는 `sd.config.ts` 의 `scripts` 타겟이 `.claude/sd-*` 변경 감지 시 본 `sync.mjs` 를 호출(패키지 외부 설정).

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

@@ -16,7 +16,7 @@
 - **`init`** — 인터랙티브 프롬프트로 SI 워크스페이스 골격 생성.
 
 공통 옵션:
-- `-t / --target <pkg>` (반복 가능) — 대상 패키지. `sd.config.ts.packages` 키 (= `@simplysm/` 접두사 **제외**한 짧은 이름). 미지정 시 전체.
+- `-t / --target <pkg>` (반복 가능) — 대상 패키지. `sd.config.ts.packages` 키 (= `@simplysm/` 접두사 **제외**한 짧은 이름). 미지정 시 전체. `check`/`watch`/`dev`/`build`/`publish` 에서 지원. `device` 는 단수(`-t <pkg>` 1회). `replace-deps`/`init` 미지원.
 - `-o / --opt <val>` (반복 가능) — `sd.config.ts` 함수의 `params.opt[]` 로 전달. `check` 와 `init` 제외 전 커맨드에서 지원.
 - `--debug` — 디버그 로그 출력 (모든 커맨드).
 - `--help / -h` — 단독 호출 시 모든 서브커맨드 종합 도움말.

package/claude/references/sd-simplysm14/apis/service-client/README.md

@@ -1,49 +1,52 @@
 # @simplysm/service-client
 
-`@simplysm/service-server` 와 WebSocket 으로 통신하는 클라이언트. RPC 호출·이벤트 구독·파일 업/다운로드·원격 ORM 실행을 단일 `ServiceClient` 에서 제공한다 (Node/브라우저 공용).
+`@simplysm/service-server` 와 WebSocket(`/ws`) 으로 통신하는 클라이언트. RPC 호출·서버 push 이벤트 구독·파일 업/다운로드·원격 ORM 트랜잭션 실행을 단일 `ServiceClient` 에서 제공한다 (Node/브라우저 공용).
 
 ## 사용 트리거 인덱스
 
-- **createServiceClient / ServiceConnectionOptions** — 서버 접속용 `ServiceClient` 를 만들고 `connect()`/`close()` 로 연결을 열고 닫을 때.
-- **getService / send / ServiceProxy** — 서버에 등록된 서비스의 메서드를 타입 안전 RPC 로 호출할 때 (Proxy 기반 메서드 호출 또는 저수준 `send`).
-- **auth** — 서버 인증 토큰을 등록하고 재연결 시 자동 재인증되도록 토큰을 내부에 보관할 때.
-- **getEvent / addListener / removeListener / emitEvent** — 서버 push 이벤트를 구독·해지하거나, 다른 클라이언트에게 이벤트를 발행할 때.
+- **createServiceClient / ServiceClient / ServiceConnectionOptions** — 서버 접속 클라이언트를 생성하고 `connect()` / `close()` 로 연결 수명을 관리할 때.
+- **getService / send / ServiceProxy** — 서버 등록 서비스의 메서드를 타입 안전 RPC 로 호출할 때 (Proxy 호출 또는 저수준 `send`).
+- **auth** — 서버 인증 토큰을 등록하고 재연결 시 자동 재인증 + 파일 업로드 인증을 활성화할 때.
+- **getEvent / addListener / removeListener / emitEvent / ClientEventProxy** — 서버 push 이벤트를 구독·해지하거나 다른 클라이언트에게 발행할 때.
 - **uploadFile / downloadFileBuffer** — 서버에 multipart 파일을 올리거나 정적 경로에서 바이트(`Uint8Array`)로 받을 때.
-- **createOrmClientConnector / OrmConnectOptions** — 서버 측 `"Orm"` 서비스를 통해 `DbContext` 트랜잭션을 원격 실행할 때.
-- **ServiceClient 이벤트 (`state` / `request-progress` / `response-progress` / `server-progress`)** — 연결 상태 변화와 전송/응답/서버 진행률을 인스턴스 레벨에서 구독할 때.
-- **BlobInput / FileCollection / isWorkerSupported 외** — Node/브라우저 양쪽 환경에서 동일한 코드를 쓰기 위해 DOM 의존 타입을 대체하거나 Worker 지원 여부를 미리 확인할 때.
+- **createOrmClientConnector / OrmClientConnector / OrmConnectOptions** — 서버 `"Orm"` 서비스를 통해 `DbContext` 트랜잭션을 원격 실행할 때.
+- **OrmClientDbContextExecutor** — `DbContext` 를 직접 구성해야 할 때만. 보통 `OrmClientConnector` 가 내부에서 사용함.
+- **ServiceClient 인스턴스 이벤트 (`state` / `request-progress` / `response-progress` / `server-progress`)** — 연결 상태 변화와 전송/응답/서버 진행률을 인스턴스 레벨에서 구독할 때.
+- **BlobInput / FileCollection / BrowserWorker / isBrowserWorkerSupported / isNodeWorkerSupported / isWorkerSupported** — Node/브라우저 공용 코드에서 DOM 의존 타입을 대체하거나 Worker 오프로딩 가용성을 확인할 때.
 
-## 연결/생성
+## 연결 / 생성
 
 ```ts
 createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient
 interface ServiceConnectionOptions { port: number; host: string; ssl?: boolean; maxReconnectCount?: number; }
 client.connect(): Promise<void>
-client.close(): Promise<void>     // protocol wrapper 의 worker 자원도 dispose
+client.close(): Promise<void>   // protocol wrapper 의 worker·resolver 자원도 dispose
 client.connected: boolean
-client.hostUrl: string            // `${ssl?https:http}://host:port`
+client.hostUrl: string          // `${ssl?https:http}://host:port`
 ```
 
-- WebSocket URL 은 `${ws|wss}://host:port/ws?ver=2&clientId=<uuid>&clientName=<name>` 으로 접속한다.
-- `maxReconnectCount` 기본 10, `0` 이면 재연결 비활성.
-- 5s 마다 ping, 30s 무응답 시 강제 재연결. 재연결 성공 시 인증 토큰(`auth()`)과 이벤트 리스너(`addListener`)가 자동 복구된다.
+- WebSocket URL: `${ws|wss}://host:port/ws?ver=2&clientId=<uuid>&clientName=<name>`.
+- `maxReconnectCount` 기본 10. `0` 이면 재연결 비활성.
+- 5s 마다 ping(`0x01`), 30s 무응답 시 강제 재연결. 재연결 성공 시 인증 토큰과 이벤트 리스너가 자동 복구된다.
+- Node 환경에서 글로벌 `WebSocket` 이 없으면 `ws` 패키지로 polyfill (모듈 로드 시 1회).
 
 ## RPC 호출
 
 ```ts
-client.getService<TService>(serviceName): ServiceProxy<TService>
-client.send(serviceName, methodName, params, progress?): Promise<unknown>
-type ServiceProxy<T> = { [K in keyof T]: T[K] extends (...a:infer P)=>infer R ? (...a:P)=>Promise<Awaited<R>> : never }
-interface ServiceProgress { request?(s); response?(s); server?(s); }
-interface ServiceProgressState { uuid: string; totalSize: number; completedSize: number; }
+client.getService<TService>(serviceName: string): ServiceProxy<TService>
+client.send(serviceName, methodName, params: unknown[], progress?: ServiceProgress): Promise<unknown>
+type ServiceProxy<T> = { [K in keyof T]: T[K] extends (...a: infer P) => infer R ? (...a: P) => Promise<Awaited<R>> : never }
+interface ServiceProgress { request?(s: ServiceProgressState): void; response?(s): void; server?(s): void }
+interface ServiceProgressState { uuid: string; totalSize: number; completedSize: number }
 ```
 
-- `getService` 는 Proxy 라 임의 메서드명 호출 가능. 타입은 `TService` 로만 보장된다.
+- `getService` 는 Proxy. 임의 메서드명 호출 가능하며 타입 보장은 `TService` 로만.
 - 와이어 메시지 이름은 `"<serviceName>.<methodName>"`.
-- 인코딩/디코딩의 Worker 오프로딩 임계값:
-  - **인코드**: body 가 `Uint8Array`, 30KB 초과 문자열, 길이 100 초과 배열, 또는 첫 요소가 `Uint8Array` 인 배열일 때 Worker 사용.
-  - **디코드**: 수신 바이트가 30KB 초과일 때 Worker 사용.
-  - Worker 미지원 환경(또는 초기화 실패)에선 메인 스레드 fallback.
+- 인코드/디코드의 Worker 오프로딩 임계값:
+  - **인코드**: body 가 `Uint8Array`, 30KB 초과 문자열, 길이 100 초과 배열, 또는 첫 원소가 `Uint8Array` 인 배열일 때 Worker.
+  - **디코드**: 수신 바이트 30KB 초과 시 Worker.
+  - Worker 미지원/초기화 실패 환경은 메인 스레드 fallback.
+- 소켓 끊김·재연결 시 대기 중인 모든 요청은 `"요청 취소됨: 소켓 연결이 끊어졌습니다"` 로 reject.
 
 ## 인증
 
@@ -51,22 +54,23 @@ interface ServiceProgressState { uuid: string; totalSize: number; completedSize:
 client.auth(token: string): Promise<void>
 ```
 
-- 서버에 `auth` 메시지를 보내고 토큰을 내부 저장. 재연결 시 자동으로 같은 토큰으로 재인증.
-- `uploadFile` 은 인증 토큰이 없으면 에러를 던진다.
+- 서버에 `auth` 메시지를 보내고 토큰을 내부 저장. 재연결 시 동일 토큰으로 자동 재인증.
+- `uploadFile` 은 토큰이 없으면 즉시 throw.
 
 ## 이벤트 (서버 push)
 
 ```ts
-client.getEvent<TEventDef>(eventName): ClientEventProxy<TEventDef>
-client.addListener<TEventDef>(eventName, info, cb): Promise<string>   // key 반환
-client.removeListener(key): Promise<void>
-client.emitEvent<TEventDef>(eventName, infoSelector, data): Promise<void>
-interface ClientEventProxy<T> { addListener(info, cb): Promise<string>; removeListener(key): Promise<void>; emit(infoSelector, data): Promise<void>; }
+client.getEvent<TEventDef>(eventName: string): ClientEventProxy<TEventDef>
+client.addListener<TEventDef>(eventName, info: TEventDef["$info"], cb): Promise<string>   // listener key
+client.removeListener(key: string): Promise<void>
+client.emitEvent<TEventDef>(eventName, infoSelector: (info) => boolean, data): Promise<void>
+interface ClientEventProxy<T> { addListener(info, cb): Promise<string>; removeListener(key): Promise<void>; emit(infoSelector, data): Promise<void> }
 ```
 
-- `addListener` 는 연결 상태에서만 호출 가능 (`!connected` 시 throw). 로컬 맵에도 보관해 재연결 시 자동 재구독.
-- `emitEvent` 는 서버에 `evt:gets` 로 후보를 받아 `infoSelector` 통과분에만 `evt:emit` 호출. 대상이 0건이면 emit 생략.
-- 핸들러 내부 에러는 로깅만 되고 다른 핸들러 호출은 계속 진행.
+- `addListener` 는 `connected` 상태에서만 호출 가능 (그 외 throw). 로컬 맵에 보관해 재연결 시 자동 재구독.
+- `emitEvent` 는 서버에 `evt:gets` 로 후보 목록을 받아 `infoSelector` 통과분에만 `evt:emit` 호출. 대상 0건이면 emit 생략.
+- 핸들러 내부 에러는 로깅만, 다른 핸들러 호출은 계속.
+- `removeListener` 는 서버 전송 실패를 무시함 (서버가 연결 끊김 시 자동 정리하므로).
 
 ## 파일 업/다운로드
 
@@ -74,11 +78,11 @@ interface ClientEventProxy<T> { addListener(info, cb): Promise<string>; removeLi
 client.uploadFile(files: File[] | FileCollection | { name: string; data: BlobInput }[]): Promise<ServiceUploadResult[]>
 client.downloadFileBuffer(relPath: string): Promise<Uint8Array>
 type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string
-interface FileCollection { length; item(i); [i]; [Symbol.iterator]() }  // 브라우저 FileList 호환
+interface FileCollection { readonly length; item(i); [i]; [Symbol.iterator]() }  // 브라우저 FileList 와 구조적 호환
 ```
 
 - 업로드: `POST {hostUrl}/upload` (multipart). 헤더 `x-sd-client-name`, `Authorization: Bearer <token>`. 인증 필수.
-- 다운로드: `GET {hostUrl}/{relPath}` 의 응답 본문을 `Uint8Array` 로 반환. `relPath` 가 `/` 로 시작하지 않으면 자동으로 붙임.
+- 다운로드: `GET {hostUrl}/{relPath}` 응답 본문을 `Uint8Array` 로 반환. `relPath` 가 `/` 로 시작하지 않으면 자동 prepend.
 - 브라우저 전용 `File`/`FileList` 대신 `BlobInput`/`FileCollection` 으로 Node 환경도 지원.
 
 ## ORM 클라이언트
@@ -86,30 +90,31 @@ interface FileCollection { length; item(i); [i]; [Symbol.iterator]() }  // 브
 ```ts
 createOrmClientConnector(client: ServiceClient): OrmClientConnector
 interface OrmConnectOptions<T extends DbContext> {
-  DbClass: new (executor, { database, schema? }) => T;
+  DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T;
   connOpt: DbConnOptions & { configName: string };
-  dbContextOpt?: { database: string; schema: string };
+  dbContextOpt?: { database: string; schema: string };   // 지정 시 둘 다 필수
 }
 connector.connect(config, async db => ...)               // 트랜잭션 래핑
 connector.connectWithoutTransaction(config, async db => ...)
 ```
 
-- 서버의 `"Orm"` 서비스에 RPC 를 걸어 `getInfo` → `connect` → `executeDefs`/`executeParametrized`/`bulkInsert` 등을 실행.
-- `dbContextOpt` 생략 시 서버가 알려준 `database`/`schema` 사용. 최종 `database` 가 빈 값이면 에러.
-- 외래키 참조 위반 에러(`a parent row: a foreign key constraint` / `conflicted with the REFERENCE`)는 "경고! 연관된 작업으로 인해 작업이 거부되었습니다..." 사용자 메시지로 변환되어 throw (원본은 `cause`).
+- 서버 `"Orm"` 서비스에 RPC 를 걸어 `getInfo` → `connect` → `executeDefs` / `executeParametrized` / `bulkInsert` / `begin·commit·rollbackTransaction` / `close` 를 위임.
+- `dbContextOpt` 생략 시 서버가 알려준 `database` / `schema` 사용. 최종 `database` 가 빈 값이면 throw.
+- 외래키 참조 위반 메시지(`a parent row: a foreign key constraint` / `conflicted with the REFERENCE`)는 "경고! 연관된 작업으로 인해 작업이 거부되었습니다. 후속 작업을 확인해 주세요." 로 변환되어 throw (원본은 `cause`).
+- `OrmClientDbContextExecutor` 는 `DbContextExecutor` 구현체. 보통 connector 가 내부 생성하며 직접 인스턴스화는 커스텀 `DbContext` 구성 시에만.
 
-## 상태/진행률 이벤트
+## 인스턴스 이벤트 (상태/진행률)
 
 ```ts
 client.on("state", (s: "connected" | "closed" | "reconnecting") => ...)
-client.on("request-progress",  (s: ServiceProgressState) => ...)  // 클라이언트 → 서버 전송 청크 진행
-client.on("response-progress", (s: ServiceProgressState) => ...)  // 서버 → 클라이언트 응답 청크 진행
+client.on("request-progress",  (s: ServiceProgressState) => ...)  // 클라 → 서버 전송 청크 진행
+client.on("response-progress", (s: ServiceProgressState) => ...)  // 서버 → 클라 응답 청크 진행
 client.on("server-progress",   (s: ServiceProgressState) => ...)  // 서버가 명시적으로 보내는 진행률
 ```
 
-- `request-progress` 는 인코드 결과 chunk 가 2개 이상일 때만 초기 0% 가 발행됨. 단일 청크는 progress 없음.
-- `response-progress` 는 분할 수신 중에는 서버 progress 메시지로, 응답 완료 시 100% 보정값으로 발행됨.
-- `send` 호출 시 전달한 `progress?: ServiceProgress` 콜백은 인스턴스 이벤트와 함께 호출된다.
+- `request-progress` 는 인코드 결과 chunk 가 2개 이상일 때만 0% 초기값 발행. 단일 청크면 발행 없음.
+- `response-progress` 는 분할 수신 중에는 서버 progress 메시지, 응답 완료 시 100% 보정값으로 발행.
+- `send` 호출에 전달한 `progress` 콜백은 인스턴스 이벤트와 함께 호출됨.
 
 ## 환경 호환 유틸
 
@@ -119,6 +124,8 @@ import { BlobInput, FileCollection, BrowserWorker,
   from "@simplysm/service-client";
 ```
 
-- `BrowserWorker` — DOM `Worker` 의 구조적 호환 인터페이스. Node 환경 typecheck 통과용.
-- `isBrowserWorkerSupported()` / `isNodeWorkerSupported()` / `isWorkerSupported()` — 현재 런타임에서 Worker 오프로딩이 가능한지 사전 확인.
-- 보통 직접 호출할 필요 없음. `ServiceClient` 가 내부에서 분기하므로, 환경별 분기 로직을 사용자 코드에서 직접 짤 때만 사용.
+- `BrowserWorker` — DOM `Worker` 의 최소 구조 호환 인터페이스. Node 환경 typecheck 통과용.
+- `isBrowserWorkerSupported()` — `"Worker" in globalThis`.
+- `isNodeWorkerSupported()` — `process.versions.node` 존재 여부.
+- `isWorkerSupported()` — 위 둘 중 하나.
+- 보통 직접 호출할 필요 없음 (`ServiceClient` 내부에서 분기). 환경 분기 로직을 사용자 코드에서 직접 짤 때만 사용.

package/claude/references/sd-simplysm14/apis/service-server/README.md

@@ -1,20 +1,13 @@
 # @simplysm/service-server
 
-Fastify 기반 서비스 서버. HTTP/WebSocket 양 전송 위에서 "서비스(`이름`+`메서드 맵`)" 단위로 RPC, JWT 인증, 정적 파일, 업로드, 이벤트 브로드캐스트, V1 레거시 호환을 제공한다.
+Fastify + WebSocket 기반 서비스 서버. 클라이언트(`@simplysm/service-client`)와 짝으로 RPC·이벤트 푸시·파일 업로드·정적 서빙·JWT 인증을 단일 포트로 제공한다.
 
 ## 사용 트리거 인덱스
 
-- **`ServiceServer` / `createServiceServer` / `ServiceServerOptions`** — 서버 인스턴스 생성·기동·종료·이벤트 브로드캐스트·JWT 발급. 자세히: [server.md](./server.md)
-- **`defineService` / `auth` / `ServiceContext` / `ServiceMethods`** — 서비스 정의 및 메서드/팩토리 인증 래퍼, 컨텍스트 헬퍼. 자세히: [define-service.md](./define-service.md)
-- **`AuthTokenPayload` / `signJwt` / `verifyJwt` / `decodeJwt`** — JWT 토큰 페이로드 타입 및 직접 서명/검증 유틸. 자세히: [auth.md](./auth.md)
-- **빌트인 서비스 (`OrmService` / `AutoUpdateService` / `AppStructureService`)** — `services` 옵션에 그대로 등록해 ORM 프록시·자동 업데이트·앱 메뉴 트리 제공. 자세히: [builtin-services.md](./builtin-services.md)
-- **전송/프로토콜/레거시 내부** (`handleHttpRequest`, `handleUpload`, `handleStaticFile`, `createWebSocketHandler`, `createServiceSocket`, `createServerProtocolWrapper`, `handleV1Connection` 등) — `ServiceServer.listen()` 이 자동 사용. 커스텀 Fastify 라우트 직조 시에만 직접 호출. 자세히: [internals.md](./internals.md)
-
-## `getConfig`
-
-```ts
-import { getConfig } from "@simplysm/service-server";
-const conf = await getConfig<{ orm: { default: DbConnConfig } }>(filePath);
-```
-
-`<rootPath>/.config.json` 같은 JSON 설정 파일을 읽고 LazyGcMap 캐시 + `FsWatcher` 로 핫리로드한다. 보통은 `ctx.getConfig(section)` 으로 충분하며, 이 함수를 직접 호출할 일은 root/client 경로 외 설정 파일을 읽을 때만 있다.
+| 트리거 | 자료 |
+| --- | --- |
+| 서버 인스턴스 생성·기동·종료, 이벤트 emit, JWT 토큰 발급/검증, `ServiceServerOptions`(`rootPath`/`port`/`ssl`/`auth`/`services`/`legacyV1Handlers`) | [server.md](./server.md) |
+| 사용자 서비스 정의(`defineService`), `ServiceContext`, `ServiceMethods` 타입 추출, `createServiceContext`, `getServiceAuthPermissions` | [define-service.md](./define-service.md) |
+| 인증 래퍼 `auth()` (서비스/메서드 레벨, 역할 제한), `AuthTokenPayload`, `signJwt`/`verifyJwt`/`decodeJwt` | [auth.md](./auth.md) |
+| 빌트인 서비스: `OrmService`, `AutoUpdateService`, `AppStructureService`, V1 레거시 자동 업데이트 핸들러 | [builtin-services.md](./builtin-services.md) |
+| 내부 전송 계층(`/api/:service/:method`·`/upload`·정적 서빙, WebSocket 핸들러, 프로토콜 래퍼/워커, `ServiceSocket`, `getConfig`) — 직접 사용 시 | [internals.md](./internals.md) |

package/claude/references/sd-simplysm14/apis/service-server/auth.md

@@ -1,29 +1,37 @@
-# @simplysm/service-server — auth
+# @simplysm/service-server — 인증
 
-JWT 페이로드 타입 및 서명/검증 유틸. 일반 시나리오에서는 `server.signAuthToken` / `server.verifyAuthToken` 이 동일 알고리즘으로 감싸므로 그쪽을 쓴다. 이 모듈을 직접 import 하는 경우는 토큰 발급/검증을 서버 인스턴스 없이 수행해야 할 때 (테스트, 별도 인증 서비스, 디코드 등).
+## `auth(fn)` / `auth(permissions, fn)`
 
-## `AuthTokenPayload<TAuthInfo>`
+서비스 factory 또는 개별 메서드를 래핑해 인증 요구사항을 부착. 래핑 함수는 호출 동작을 그대로 유지하며 내부 심볼에 `permissions: string[]` 저장.
 
-```ts
-interface AuthTokenPayload<TAuthInfo = unknown> extends jose.JWTPayload {
-  roles: string[];                 // auth(["role"], fn) 검사 대상
-  data: TAuthInfo;                 // ctx.authInfo 로 노출
-}
-```
+- 서비스 수준: `defineService("X", auth((ctx) => ({ ... })))` — 모든 메서드 로그인 필요.
+- 서비스 수준 + 역할: `defineService("X", auth(["admin"], (ctx) => ({ ... })))`.
+- 메서드 수준: factory 내부에서 `someMethod: auth(() => result)`.
+- 메서드 수준 + 역할: `someMethod: auth(["admin", "owner"], () => result)` — 배열 중 하나라도 매칭하면 통과(OR).
 
-## `signJwt(jwtSecret, payload) → Promise<string>`
+실행 시(`executeServiceMethod`) 동작:
+
+- 메서드 권한이 있으면 서비스 권한을 **덮어쓴다**. 메서드 권한 미부착 시 서비스 권한 사용.
+- 권한 요구 + `options.auth == null` → "auth 설정이 필요합니다" throw(서버 설정 오류).
+- 권한 요구 + `options.auth === false` → 인증 스킵.
+- 권한 요구 + `options.auth = { jwtSecret }` → payload 없으면 "로그인이 필요합니다" throw. `permissions.length > 0` 이면 `payload.roles` 중 하나라도 일치해야 통과, 아니면 "권한이 부족합니다" throw. `permissions.length === 0` (= `auth(fn)`) 이면 토큰만 있으면 통과.
+
+## `AuthTokenPayload<TAuthInfo>`
 
-HS256, `iat` 자동, 만료 `12h` 고정. 토큰 수명을 바꿔야 하면 이 함수 대신 직접 `jose.SignJWT` 를 쓴다.
+`jose.JWTPayload` 확장.
 
-## `verifyJwt<TAuthInfo>(jwtSecret, token) → Promise<AuthTokenPayload<TAuthInfo>>`
+- `roles: string[]` — `auth(["role"], fn)` 검사 대상.
+- `data: TAuthInfo` — 임의 사용자 데이터. `ctx.authInfo` 로 노출.
 
-검증 실패 시 `토큰이 만료되었습니다.` 또는 `유효하지 않은 토큰입니다.` 를 throw.
+## JWT 헬퍼
 
-## `decodeJwt<TAuthInfo>(token) → AuthTokenPayload<TAuthInfo>`
+`server.signAuthToken`/`verifyAuthToken` 이 동일 알고리즘으로 감싸므로 일반 시나리오에선 그쪽을 쓴다. 직접 import 는 서버 인스턴스 없이 토큰을 다루는 경우(테스트, 별도 인증 서버, 디코드 등)만.
 
-서명 검증 없이 페이로드만 디코드. 클라이언트 측 만료 표시 등 비보안 용도에만.
+- `signJwt<T>(jwtSecret, payload): Promise<string>` — HS256, `iat` 자동, `exp = 12h` 고정. 수명 변경 필요 시 `jose.SignJWT` 직접 사용.
+- `verifyJwt<T>(jwtSecret, token): Promise<AuthTokenPayload<T>>` — 만료: "토큰이 만료되었습니다", 그 외 위조: "유효하지 않은 토큰입니다" throw.
+- `decodeJwt<T>(token): AuthTokenPayload<T>` — 서명 검증 없이 페이로드만 디코드. 클라이언트 측 만료 표시 등 비보안 용도에만.
 
-## 예제
+## 예
 
 ```ts
 const token = await signJwt(secret, { roles: ["admin"], data: { userId: "U1" } });

package/claude/references/sd-simplysm14/apis/service-server/builtin-services.md

@@ -1,47 +1,71 @@
-# @simplysm/service-server — builtin-services
+# @simplysm/service-server — 빌트인 서비스
 
-`ServiceServerOptions.services` 에 그대로 푸시해서 쓰는 사전 정의 서비스. 각각의 `*ServiceType` 은 클라이언트 측에서 `client.getService<*ServiceType>("<이름>")` 로 타입 공유한다.
+`options.services` 에 추가해 사용. 각 `*ServiceType` 은 클라이언트의 `client.getService<*ServiceType>("<이름>")` 에 그대로 사용.
 
-## `OrmService` / `OrmServiceType`
+## `OrmService`
 
-이름 alias: `["Orm", "SdOrmService"]`. **WebSocket 전용** (HTTP 호출 시 throw — 트랜잭션을 소켓 라이프타임에 묶기 위함). `auth()` 로 감싸져 있어 로그인 필요.
+DB 연결을 WebSocket 세션과 묶어 원격 ORM 사용.
 
-설정: `ctx.getConfig("orm")` 으로 `Record<string, DbConnConfig>` 를 읽고 `opt.configName` 으로 선택. 클라이언트가 `opt.config` 로 일부 필드 override 가능.
+- 별칭: `["Orm", "SdOrmService"]`.
+- **WebSocket 전용**. HTTP 호출 시 "WebSocket 연결이 필요합니다…" throw(트랜잭션을 소켓 라이프타임에 묶기 위함).
+- `auth()` 래핑이라 로그인 필수. 역할 제한은 없음.
+- 설정 소스: `ctx.getConfig<Record<string, DbConnConfig>>("orm")` → `opt.configName` 키 조회. 호출 시 `opt.config` 가 base 설정을 부분 override.
+- 연결 ID 는 소켓별 카운터(1부터, 가장 큰 값+1). 소켓 close 시 해당 소켓의 모든 열린 DB 연결 자동 정리(에러는 warn 후 무시).
+- `dialect === "mssql-azure"` 는 외부 노출 시 `"mssql"` 로 정규화.
 
-메서드: `getInfo`, `connect → connId`, `close(connId)`, `beginTransaction(connId, isolation?)`, `commitTransaction`, `rollbackTransaction`, `executeParametrized(connId, sql, params?)`, `executeDefs(connId, defs, optionsMeta?)`, `bulkInsert(connId, table, colDefs, records)`. 소켓 close 시 그 소켓의 모든 연결을 자동 정리.
+메서드:
 
-## `AutoUpdateService` / `AutoUpdateServiceType`
+- `getInfo(opt)` → `{ dialect, database?, schema? }` (연결 안 만들고 설정 조회만).
+- `connect(opt): Promise<number>` — connId 반환.
+- `close(connId)`.
+- `beginTransaction(connId, isolationLevel?)`, `commitTransaction(connId)`, `rollbackTransaction(connId)`.
+- `executeParametrized(connId, query, params?)` — `unknown[][]` (멀티 결과셋).
+- `executeDefs(connId, defs: QueryDef[], options?: (ResultMeta | undefined)[])` — `options` 가 전부 null/undefined 면 단일 multi-SQL 실행 후 빈 배열들, 아니면 def 별로 build → execute → `pickResultSets` → opt 있으면 `parseQueryResult`, 없으면 raw.
+- `bulkInsert(connId, tableName, columnDefs, records)`.
 
-이름 alias: `["AutoUpdate", "SdAutoUpdateService"]`. 인증 없음.
+`opt: DbConnOptions & { configName: string }`. 타입 export: `OrmServiceType`.
 
-`getLastVersion(platform)` — `<clientPath>/<platform>/updates/` 디렉토리에서 `android` 는 `.apk`, 그 외는 `.exe` 중 `semver.maxSatisfying("*")` 으로 최신을 골라 `{ version, downloadPath }` 반환. 없으면 `undefined`.
+## `AutoUpdateService`
 
-## `AppStructureService(itemsMap) → ServiceDefinition` / `AppStructureServiceType`
+- 별칭: `["AutoUpdate", "SdAutoUpdateService"]`. 인증 없음.
+- `getLastVersion(platform: string): Promise<{ version, downloadPath } | undefined>` — `<clientPath>/<platform>/updates/` 에서 `platform === "android"` → `.apk`, 그 외 → `.exe` 중 파일명이 `^[0-9.]*$` 인 것만 후보. `semver.maxSatisfying(versions, "*")` 로 최신 선정. clientName 미설정 시 throw, 디렉터리/매칭 파일 없으면 undefined.
+- `downloadPath` = `/<clientName>/<platform>/updates/<fileName>` (POSIX 정규화).
+- 타입 export: `AutoUpdateServiceType`.
 
-다른 두 서비스와 달리 **팩토리 호출 결과**를 등록한다. 이름 `"AppStructure"`, 인증 없음.
+## `AppStructureService(itemsMap)`
 
-```ts
-import { AppStructureService } from "@simplysm/service-server";
-import type { AppStructureItem } from "@simplysm/service-common";
-
-const itemsMap: Record<string, AppStructureItem[]> = { admin: [...], shop: [...] };
-services: [AppStructureService(itemsMap)];
-```
+다른 두 서비스와 달리 **팩토리 함수**(서비스 정의가 아님). 호출 결과를 `services` 에 등록.
 
-`getItems()` 한 메서드만 노출. 클라이언트 메뉴/라우트 트리 공급용.
+- 시그니처: `AppStructureService(itemsMap: Record<string, AppStructureItem[]>): ServiceDefinition`
+- 서비스 이름: `"AppStructure"`. 인증 없음.
+- 메서드: `getItems(): Record<string, AppStructureItem[]>` — 주입된 map 그대로 반환.
+- 타입 export: `AppStructureServiceType`.
 
-## 등록 예제
+`AppStructureItem` 은 `@simplysm/service-common` 정의(메뉴/라우트 트리 항목).
 
 ```ts
-import { createServiceServer, OrmService, AutoUpdateService, AppStructureService } from "@simplysm/service-server";
-
-createServiceServer({
-  rootPath, port: 50080, auth: { jwtSecret },
-  services: [
-    OrmService,
-    AutoUpdateService,
-    AppStructureService(appItemsMap),
-    MyAppService,
-  ],
-});
+services: [AppStructureService({ admin: [...], user: [...] })];
 ```
+
+## V1 레거시 자동 업데이트
+
+ver≠"2" 로 접속한 구버전 클라이언트 호환. JSON 라인 프로토콜.
+
+### `handleV1Connection(socket, autoUpdateMethods, clientNameSetter?)` / `handleV1Connection(socket, options)`
+
+`ServiceServer` 가 자동 호출. `services` 에 `AutoUpdate` 가 있으면 그 factory 의 `getLastVersion` 을 V1 메서드로 자동 매핑. `legacyV1Handlers` 도 그대로 전달. 둘 다 없으면 1008 거부.
+
+`V1ConnectionOptions`:
+
+- `serviceContext?` 또는 `serviceContextFactory?: (req: V1Request) => ServiceContext` — 핸들러용 컨텍스트(둘 중 하나).
+- `handlers?: V1RequestHandler[]` — 우선 실행. 각 핸들러는 `{ handled: true, state?: "success"|"error", body } | { handled: false }` 반환. handled=true 면 즉시 응답.
+- `autoUpdateMethods?` 또는 `autoUpdateMethodsFactory?: (ctx) => V1AutoUpdateMethods` — 모든 사용자 핸들러가 미처리 + `command === "SdAutoUpdateService.getLastVersion"` 일 때 fallback.
+- `clientNameSetter?: (clientName: string | undefined) => void` — 매 요청의 `clientName` 알림 콜백.
+- 어디서도 처리 안 되면 `{ code: "UPGRADE_REQUIRED", message: "앱 업그레이드가 필요합니다." }` 응답.
+
+타입:
+
+- `V1Request = { uuid, command, params: unknown[], clientName? }`
+- `V1Response = { name: "response", reqUuid, state: "success" | "error", body }`
+- `V1AutoUpdateMethods = { getLastVersion(platform): Promise<unknown> | unknown }`
+- `V1RequestHandler`, `V1RequestHandlerContext`, `V1RequestHandlerResult`.

package/claude/references/sd-simplysm14/apis/service-server/define-service.md

@@ -1,70 +1,54 @@
-# @simplysm/service-server — define-service
+# @simplysm/service-server — 서비스 정의
 
-서비스 정의 + 인증 래퍼 + 컨텍스트. `ServiceServerOptions.services` 에 들어갈 단위를 만든다.
+## `defineService(name, factory): ServiceDefinition<TMethods>`
 
-## `defineService(name, factory) → ServiceDefinition<TMethods>`
+- `name: string | string[]` — 단일 또는 별칭 목록. 첫 요소가 primary(`def.name`), 전체가 `def.names`. RPC 라우팅은 `names.includes(요청서비스명)` 매칭. 빈 배열이면 throw.
+- `factory: (ctx: ServiceContext) => TMethods` — 매 요청마다 호출되어 메서드 객체 생성(컨텍스트 캡처). factory 자체가 `auth(...)` 래핑이면 `authPermissions` 가 자동 추출돼 서비스 수준 인증으로 승격.
 
-```ts
-defineService<TMethods extends Record<string, (...args: any[]) => any>>(
-  name: string | string[],          // 다중 이름 = alias (예: ["Orm", "SdOrmService"])
-  factory: (ctx: ServiceContext) => TMethods,
-): ServiceDefinition<TMethods>;
-```
-
-`factory` 는 호출마다 실행돼 메서드 객체를 생성한다 (요청별 컨텍스트 캡처). `factory` 가 `auth(...)` 로 감싸져 있으면 서비스 수준 인증으로 승격된다.
+반환 `ServiceDefinition<TMethods>`:
 
-## `auth(...)` — 인증 래퍼
-
-```ts
-auth(fn)                           // 로그인 필요
-auth(["admin", "owner"], fn)       // 해당 역할 중 하나 필요 (OR)
-```
-
-- 서비스 수준: `defineService("X", auth((ctx) => ({ ... })))`
-- 메서드 수준: 팩토리 안에서 메서드를 `auth(["admin"], () => result)` 로 감싼다. 메서드 권한이 있으면 서비스 권한을 **덮어쓴다**.
-- `auth: false` 옵션 시 검증 스킵, `auth: undefined` 인데 auth 필요 서비스 등록 시 `listen()` throw, auth 설정됐는데 토큰 없거나 권한 부족 시 메서드 호출에서 throw (`로그인이 필요합니다.` / `권한이 부족합니다.`).
+- `name: string`
+- `names: string[]`
+- `factory`
+- `authPermissions?: string[]`
 
 ## `ServiceContext<TAuthInfo>`
 
-서비스 메서드가 받는 요청별 컨텍스트.
+서비스 factory 가 받는 요청별 컨텍스트.
 
-```ts
-interface ServiceContext<TAuthInfo = unknown> {
-  server: ServiceServer<TAuthInfo>;
-  socket?: ServiceSocket;                            // WS 경로일 때만
-  http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> };
-  legacy?: { clientName?: string };                  // V1 레거시 경로
+- `server: ServiceServer<TAuthInfo>`
+- `socket?: ServiceSocket` — WebSocket 경로일 때만.
+- `http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> }` — HTTP 경로.
+- `legacy?: { clientName?: string }` — V1 경로.
+- `get authInfo(): TAuthInfo | undefined` — socket 의 payload.data 우선, 없으면 http.
+- `get clientName(): string | undefined` — socket → http → legacy 순. 빈 문자/`..`/`/`/`\\` 포함 시 throw.
+- `get clientPath(): string | undefined` — `<rootPath>/www/<clientName>`. clientName 없으면 undefined.
+- `getConfig<T>(section: string): Promise<T>` — `<rootPath>/.config.json` + `<clientPath>/.config.json` 을 `obj.merge` 한 뒤 `section` 키 반환. 섹션 없으면 throw. 설정 파일은 `FsWatcher` 로 변경 감시되어 자동 리로드.
 
-  get authInfo(): TAuthInfo | undefined;             // payload.data
-  get clientName(): string | undefined;              // socket → http → legacy 순. 위험문자(.. / \) throw
-  get clientPath(): string | undefined;              // <rootPath>/www/<clientName>
-  getConfig<T>(section: string): Promise<T>;         // root + clientPath 의 .config.json merge, 누락 시 throw
-}
-```
+## `ServiceMethods<TDefinition>` 타입
 
-## `ServiceMethods<TDefinition>`
-
-클라이언트에서 메서드 시그니처만 공유하기 위한 추출 타입.
+`ServiceDefinition<M>` 에서 `M` 추출. 클라이언트의 `client.getService<MyServiceType>("MyService")` 에 사용.
 
 ```ts
-export const UserService = defineService("User", (ctx) => ({ ... }));
+export const UserService = defineService("User", (ctx) => ({
+  getProfile: () => ({ name: "kim" }),
+}));
 export type UserServiceType = ServiceMethods<typeof UserService>;
-// 클라이언트: client.getService<UserServiceType>("User")
 ```
 
-## 보조
+## 보조 export
 
-- `createServiceContext(server, socket?, http?, legacy?)` — 컨텍스트 직조 (커스텀 라우트용).
-- `getServiceAuthPermissions(fn)` — `auth()` 가 함수에 심볼로 심어둔 권한 배열을 읽는다 (내부 executor 가 사용).
+- `createServiceContext(server, socket?, http?, legacy?): ServiceContext` — 컨텍스트 직조. 커스텀 라우트/테스트용.
+- `getServiceAuthPermissions(fn): string[] | undefined` — `auth()` 가 함수에 심어둔 권한 배열 추출. 래핑 안 됐으면 undefined. 내부 executor 가 사용.
 
-## 예제
+## 예
 
 ```ts
 const HealthService = defineService("Health", () => ({
   check: () => ({ status: "ok" }),
 }));
 
-const UserService = defineService("User", auth((ctx) => ({
+const UserService = defineService(["User", "MyUser"], auth((ctx) => ({
   me: () => ctx.authInfo,
   adminOnly: auth(["admin"], () => "ok"),
 })));