@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/service-server/transport-socket/service-socket.md

@@ -0,0 +1,64 @@
+# ServiceSocket
+
+프로토콜 인코딩/디코딩, ping/pong 연결 유지, 이벤트 리스너 추적이 포함된 단일 WebSocket 연결 인터페이스.
+
+```typescript
+interface ServiceSocket {
+  readonly connectedAtDateTime: DateTime;
+  readonly clientName: string;
+  readonly connReq: FastifyRequest;
+  authTokenPayload?: AuthTokenPayload;
+
+  close(): void;
+  send(uuid: string, msg: ServiceServerMessage): Promise<number>;
+  addListener(key: string, eventName: string, info: unknown): void;
+  removeListener(key: string): void;
+  getEventListeners(eventName: string): Array<{ key: string; info: unknown }>;
+  filterEventTargetKeys(targetKeys: string[]): string[];
+  on(event: "error", handler: (err: Error) => void): void;
+  on(event: "close", handler: (code: number) => void): void;
+  on(event: "message", handler: (data: { uuid: string; msg: ServiceClientMessage }) => void): void;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connectedAtDateTime` | property | `DateTime` | 연결 시점의 DateTime 객체 |
+| `clientName` | property | `string` | 클라이언트 앱 이름 |
+| `connReq` | property | `FastifyRequest` | 연결 시점의 Fastify 요청 객체 |
+| `authTokenPayload` | property | `AuthTokenPayload` (optional) | WebSocket `auth` 메시지로 검증된 토큰 페이로드 |
+| `close()` | method | `void` | WebSocket 연결을 종료한다 (`socket.terminate()`) |
+| `send(uuid, msg)` | method | `Promise<number>` | 메시지를 프로토콜 인코딩하여 전송한다. 전송된 바이트 수를 반환한다. 소켓이 닫혀있으면 0을 반환한다 |
+| `addListener(key, eventName, info)` | method | `void` | key/name/info로 이벤트 리스너를 등록한다 |
+| `removeListener(key)` | method | `void` | key로 이벤트 리스너를 제거한다 |
+| `getEventListeners(eventName)` | method | `Array<{ key: string; info: unknown }>` | 특정 이벤트 이름에 해당하는 모든 리스너의 배열을 반환한다 |
+| `filterEventTargetKeys(targetKeys)` | method | `string[]` | 이 소켓의 리스너에 존재하는 대상 키만 필터링하여 반환한다 |
+| `on(event, handler)` | method | `void` | `"error"`, `"close"`, `"message"` 이벤트 핸들러를 등록한다 |
+
+ping/pong: 5초 간격으로 ping을 전송하고, 클라이언트의 `0x01` 바이트(ping) 수신 시 `0x02` 바이트(pong)를 응답한다. pong 미수신 시 연결을 종료한다.
+
+프로토콜 메시지 처리: `createServerProtocolWrapper`를 사용하여 메시지를 인코딩/디코딩한다. 수신 메시지의 디코딩 결과가 `"progress"` 타입이면 진행률 메시지를 클라이언트에 전송한다.
+
+## Related Types
+
+### `createServiceSocket`
+
+`ServiceSocket` 인스턴스를 생성한다.
+
+```typescript
+function createServiceSocket(
+  socket: WebSocket,
+  clientId: string,
+  clientName: string,
+  connReq: FastifyRequest,
+): ServiceSocket;
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `socket` | `WebSocket` | 기저 WebSocket 인스턴스 (`ws` 라이브러리) |
+| `clientId` | `string` | 클라이언트 고유 식별자 |
+| `clientName` | `string` | 클라이언트 앱 이름 |
+| `connReq` | `FastifyRequest` | 연결 시점의 Fastify 요청 객체 |

package/claude/references/sd-simplysm-v14/service-server/transport-socket/websocket-handler.md

@@ -0,0 +1,57 @@
+# WebSocketHandler
+
+다중 WebSocket 연결을 관리하고, 메시지를 서비스로 라우팅하며, 이벤트 브로드캐스팅을 처리하는 인터페이스.
+
+```typescript
+interface WebSocketHandler {
+  addSocket(socket: WebSocket, clientId: string, clientName: string, connReq: FastifyRequest): void;
+  closeAll(): void;
+  emit<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `addSocket(socket, clientId, clientName, connReq)` | method | `void` | 새 WebSocket 연결을 추가한다. 동일 `clientId`의 이전 연결이 있으면 해제한다 |
+| `closeAll()` | method | `void` | 모든 활성 연결을 닫는다 |
+| `emit(eventName, infoSelector, data)` | method | `Promise<void>` | `infoSelector`에 매칭되는 클라이언트에 이벤트를 브로드캐스트한다 |
+
+메시지 라우팅 (`processRequest` 내부):
+
+| `message.name` | 처리 |
+|-----------------|------|
+| `"SvcName.methodName"` (`.` 포함) | `runMethod`로 서비스 메서드 실행 |
+| `"evt:add"` | 이벤트 리스너 등록 (`key`, `name`, `info`) |
+| `"evt:remove"` | 이벤트 리스너 제거 (`key`) |
+| `"evt:gets"` | 전체 소켓의 특정 이벤트 리스너 조회 |
+| `"evt:emit"` | 지정된 키 대상 이벤트 발송 |
+| `"auth"` | JWT 토큰 검증 후 소켓에 `authTokenPayload` 저장 |
+
+## Related Types
+
+### `createWebSocketHandler`
+
+`WebSocketHandler` 인스턴스를 생성한다.
+
+```typescript
+function createWebSocketHandler(
+  runMethod: (def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+  }) => Promise<unknown>,
+  jwtSecret: string | undefined,
+): WebSocketHandler;
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `runMethod` | `(def: { serviceName, methodName, params, socket? }) => Promise<unknown>` | 서비스 메서드 실행 콜백 |
+| `jwtSecret` | `string \| undefined` | JWT 시크릿. `undefined`이면 `auth` 메시지 처리 시 에러를 던진다 |

package/claude/references/sd-simplysm-v14/service-server/types/service-server-options.md

@@ -0,0 +1,36 @@
+# ServiceServerOptions
+
+서버 생성 시 전달하는 옵션 인터페이스.
+
+```typescript
+interface ServiceServerOptions {
+  rootPath: string;
+  port: number;
+  ssl?: {
+    pfxBytes: Uint8Array;
+    passphrase: string;
+  };
+  auth?: {
+    jwtSecret: string;
+  } | false;
+  services: ServiceDefinition[];
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rootPath` | `string` | 서버 루트 경로. 정적 파일은 `{rootPath}/www/`에서 서빙되고, 설정 파일은 `{rootPath}/.config.json`에서 읽는다 |
+| `port` | `number` | 리스닝 포트 번호 |
+| `ssl` | `{ pfxBytes: Uint8Array; passphrase: string }` (optional) | HTTPS 설정. PFX 인증서 바이트와 비밀번호. 설정하지 않으면 HTTP로 동작한다 |
+| `auth` | `{ jwtSecret: string } \| false` (optional) | JWT 인증 설정. 세 가지 상태가 있다 |
+| `services` | `ServiceDefinition[]` | 등록할 서비스 정의 배열 |
+
+`auth` 필드의 세 가지 상태:
+
+| 값 | 의미 |
+|----|------|
+| `{ jwtSecret: "..." }` | 인증 활성화. `auth()`로 래핑된 서비스/메서드는 토큰 검증을 수행한다 |
+| `false` | 인증 의도적 비활성화. `auth()`로 래핑된 서비스/메서드도 인증 검사를 스킵한다 |
+| `undefined` (미설정) | 인증 미사용. `auth()`로 래핑된 서비스가 있으면 `listen()` 시 에러를 던진다 |

package/claude/references/sd-simplysm-v14/service-server/utils/get-config.md

@@ -0,0 +1,29 @@
+# getConfig
+
+`.config.json` 파일을 읽고 캐싱한다. 파일 변경 시 자동 리로드되며, 캐시는 1시간 후 만료된다.
+
+## When to use
+
+- ✅ 서비스에서 `.config.json` 설정 파일을 캐싱/자동 리로드로 읽을 때
+- ❌ 일반적으로는 `ServiceContext.getConfig()`를 사용한다 — 이 함수는 내부적으로 `getConfig`를 호출하면서 루트/클라이언트별 설정 병합을 자동으로 처리한다
+
+```typescript
+async function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `filePath` | `string` | `.config.json` 파일의 절대 경로 |
+
+## Returns
+
+`Promise<TConfig | undefined>` — 파싱된 설정 객체. 파일이 존재하지 않으면 `undefined`.
+
+캐싱 동작:
+- `LazyGcMap`을 사용하여 캐시를 관리한다 (10분 간격 GC, 1시간 후 만료)
+- 캐시 히트 시 파일을 다시 읽지 않는다 (접근 시간이 자동 갱신됨)
+- `FsWatcher`로 파일 변경을 감시하고, 변경 시 100ms 지연 후 리로드한다
+- 파일이 삭제되면 캐시와 워처를 모두 해제한다
+- 캐시 만료 시 워처도 함께 해제한다

package/claude/references/sd-simplysm-v14/storage/README.md

@@ -0,0 +1,99 @@
+# @simplysm/storage
+
+> FTP/FTPS/SFTP 파일 저장소 클라이언트 라이브러리 (Node.js 전용). `StorageClient` 인터페이스로 프로토콜을 통일하고, `StorageFactory`로 연결 생명주기를 관리한다. 내부적으로 `basic-ftp`(FTP/FTPS)와 `ssh2-sftp-client`(SFTP)를 사용한다.
+
+## Installation
+
+```bash
+npm install @simplysm/storage
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| FTP/SFTP 서버에 파일 업로드/다운로드 | [`StorageFactory`](./factory/storage-factory.md) |
+| 프로토콜별 구현 차이 확인 (FTP/FTPS) | [`FtpStorageClient`](./clients/ftp-storage-client.md) |
+| SFTP 인증 방식 (패스워드/SSH 키) 확인 | [`SftpStorageClient`](./clients/sftp-storage-client.md) |
+| 스토리지 작업을 추상화하는 함수 작성 | [`StorageClient`](./types/storage-client.md) |
+| 연결 설정 타입 확인 | [`StorageConnConfig`](./types/storage-conn-config.md) |
+
+## API Overview
+
+### Factory
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`StorageFactory`](./factory/storage-factory.md) | class | 스토리지 서버에 연결하여 파일 작업을 수행할 때 (기본 진입점) |
+
+### Clients
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`FtpStorageClient`](./clients/ftp-storage-client.md) | class | FTP/FTPS 클라이언트를 직접 생명주기 관리해야 할 때 |
+| [`SftpStorageClient`](./clients/sftp-storage-client.md) | class | SFTP 클라이언트를 직접 생명주기 관리해야 할 때 |
+
+### Types
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`StorageClient`](./types/storage-client.md) | interface | 스토리지 작업을 프로토콜 무관하게 추상화하는 함수 시그니처에 사용할 때 |
+| [`StorageConnConfig`](./types/storage-conn-config.md) | interface | 연결 설정 객체를 타입으로 지정할 때 |
+| [`FileInfo`](./types/file-info.md) | interface | `list()` 반환값을 처리할 때 |
+
+## Usage Examples
+
+### SFTP로 파일 업로드 (StorageFactory 사용 권장)
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+await StorageFactory.connect(
+  "sftp",
+  { host: "sftp.example.com", user: "user", password: "pass" },
+  async (storage) => {
+    await storage.mkdir("/remote/dir");
+    await storage.put("/local/file.txt", "/remote/dir/file.txt");
+  },
+);
+```
+
+콜백이 완료되거나 예외가 발생하면 자동으로 연결이 종료된다.
+
+### FTP로 파일 목록 조회 및 다운로드
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+const files = await StorageFactory.connect(
+  "ftp",
+  { host: "ftp.example.com", port: 21, user: "user", password: "pass" },
+  async (storage) => {
+    const list = await storage.list("/data");
+    for (const file of list.filter((f) => f.isFile)) {
+      const content = await storage.readFile(`/data/${file.name}`);
+      // content는 Bytes (Uint8Array)
+    }
+    return list;
+  },
+);
+```
+
+### SSH 키 인증으로 SFTP 연결 (비밀번호 생략)
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+await StorageFactory.connect(
+  "sftp",
+  { host: "sftp.example.com", user: "user" }, // password 생략 → SSH agent/키 파일 인증
+  async (storage) => {
+    const list = await storage.list("/home/user");
+  },
+);
+```
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 브라우저 환경에서 파일 업로드/다운로드 → 이 패키지는 Node.js 전용이다
+- HTTP/S3 등 FTP/SFTP 이외의 프로토콜 → 이 패키지는 FTP/FTPS/SFTP만 지원한다

package/claude/references/sd-simplysm-v14/storage/clients/ftp-storage-client.md

@@ -0,0 +1,99 @@
+# `FtpStorageClient`
+
+FTP/FTPS 프로토콜을 사용하는 스토리지 클라이언트. `basic-ftp` 라이브러리 기반. [`StorageClient`](../types/storage-client.md) 인터페이스를 구현한다.
+
+## When to use
+
+- ✅ FTP/FTPS 연결을 직접 생명주기 관리해야 할 때 (장시간 연결 유지 등)
+- ❌ 단일 작업 단위로 연결/종료를 자동 관리하고 싶을 때 → [`StorageFactory.connect()`](../factory/storage-factory.md) 사용 권장
+
+## Signature
+
+```typescript
+class FtpStorageClient implements StorageClient {
+  constructor(private readonly _secure: boolean = false);
+}
+```
+
+## Constructor
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `_secure` | `boolean` | `false` | `true`이면 FTPS (TLS/SSL 암호화), `false`이면 FTP |
+
+## Members
+
+[`StorageClient`](../types/storage-client.md) 인터페이스의 모든 메서드를 구현한다. 구현 특이사항:
+
+| Member | Kind | Description |
+|--------|------|-------------|
+| `connect` | method | 이미 연결된 상태에서 호출하면 `SdError` 발생. 연결 실패 시 내부 `ftp.Client`를 즉시 닫고 예외를 전파 |
+| `mkdir` | method | `basic-ftp`의 `ensureDir()`을 사용하여 부모 디렉토리 포함 재귀 생성 |
+| `exists` | method | 먼저 `size()` 명령으로 파일을 O(1) 성능으로 확인. 실패 시 부모 디렉토리 `list()`로 디렉토리 존재 여부 확인. 슬래시 없는 경로(예: `file.txt`)는 루트(`/`)에서 검색. 모든 예외는 `false` 반환 |
+| `put` | method | `string`이면 파일 경로로, `Bytes`이면 `Readable` 스트림으로 변환하여 `uploadFrom()` 호출 |
+| `close` | method | 동기적으로 내부 클라이언트를 정리하고 `Promise.resolve()` 반환. 이미 종료된 상태에서 호출해도 안전 |
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { FtpStorageClient } from "@simplysm/storage";
+
+const client = new FtpStorageClient();
+try {
+  await client.connect({ host: "ftp.example.com", user: "user", password: "pass" });
+  await client.put("/local/file.txt", "/remote/file.txt");
+} finally {
+  await client.close();
+}
+```
+
+### 전형 예제
+
+```typescript
+import { FtpStorageClient } from "@simplysm/storage";
+
+// FTPS 사용
+const client = new FtpStorageClient(true); // true = FTPS
+try {
+  await client.connect({ host: "ftps.example.com", user: "user", password: "pass" });
+  const exists = await client.exists("/remote/file.txt");
+  if (exists) {
+    await client.rename("/remote/file.txt", "/remote/backup.txt");
+  }
+  await client.uploadDir("/local/dir", "/remote/dir");
+} finally {
+  await client.close(); // 예외 발생 여부와 무관하게 반드시 종료
+}
+```
+
+## 🚫 Anti-patterns
+
+### close() 없이 사용
+
+```typescript
+// ❌ finally 없이 사용하면 예외 시 연결 누수
+const client = new FtpStorageClient();
+await client.connect(config);
+await client.put("/local/file.txt", "/remote/file.txt");
+await client.close();
+
+// ✅ try/finally로 보장하거나 StorageFactory.connect() 사용
+```
+
+**근거**: 예외 발생 시 `close()`가 호출되지 않아 FTP 연결이 누수된다.
+
+### 동일 인스턴스에서 connect() 중복 호출
+
+```typescript
+// ❌ close() 없이 connect()를 다시 호출하면 SdError 발생
+await client.connect(config);
+await client.connect(config); // SdError: "FTP 서버에 이미 연결되어 있습니다"
+
+// ✅ close() 후 재연결
+await client.close();
+await client.connect(config);
+```
+
+**근거**: 내부 클라이언트가 이미 존재하면 `SdError`를 던진다.

package/claude/references/sd-simplysm-v14/storage/clients/sftp-storage-client.md

@@ -0,0 +1,108 @@
+# `SftpStorageClient`
+
+SFTP 프로토콜을 사용하는 스토리지 클라이언트. `ssh2-sftp-client` 라이브러리 기반. [`StorageClient`](../types/storage-client.md) 인터페이스를 구현한다.
+
+## When to use
+
+- ✅ SFTP 연결을 직접 생명주기 관리해야 할 때 (장시간 연결 유지 등)
+- ❌ 단일 작업 단위로 연결/종료를 자동 관리하고 싶을 때 → [`StorageFactory.connect()`](../factory/storage-factory.md) 사용 권장
+
+## Signature
+
+```typescript
+class SftpStorageClient implements StorageClient {
+  constructor();
+}
+```
+
+## Members
+
+[`StorageClient`](../types/storage-client.md) 인터페이스의 모든 메서드를 구현한다. 구현 특이사항:
+
+| Member | Kind | Description |
+|--------|------|-------------|
+| `connect` | method | 이미 연결된 상태에서 호출하면 `SdError` 발생. `password` 유무에 따라 인증 방식이 달라짐 (아래 인증 메커니즘 참조). 연결 실패 시 `client.end()`를 호출하고 예외를 전파 |
+| `mkdir` | method | `ssh2-sftp-client`의 `mkdir(path, true)`를 호출하여 부모 디렉토리 포함 재귀 생성 |
+| `list` | method | `item.type === "-"`이면 파일(`isFile: true`), 아니면 디렉토리(`isFile: false`)로 변환 |
+| `exists` | method | `ssh2-sftp-client`의 `exists()` 반환값(`false \| 'd' \| '-' \| 'l'`)을 검사. 문자열이면 존재. 모든 예외는 `false` 반환 |
+| `readFile` | method | `ssh2-sftp-client`의 `get()` 반환값(`Buffer` 또는 `string`)을 `Bytes`(`Uint8Array`)로 변환 |
+| `put` | method | `string`이면 `fastPut()`으로, `Bytes`이면 `Buffer.from()` 변환 후 `put()`으로 업로드 (`ssh2-sftp-client` 라이브러리 요구사항) |
+| `close` | method | `client.end()`를 호출하여 연결 종료. 이미 종료된 상태에서 호출해도 안전 |
+
+## Authentication
+
+`connect()` 호출 시 [`StorageConnConfig`](../types/storage-conn-config.md)의 `password` 유무에 따라 인증 방식이 결정된다:
+
+**`password`가 있는 경우**: 패스워드 인증
+
+**`password`가 없는 경우**: 다음 순서로 시도
+1. SSH agent (`SSH_AUTH_SOCK` 환경변수가 설정된 경우 `agent` 옵션 추가)
+2. `~/.ssh/id_ed25519` 개인키 파일 읽어 `privateKey` 옵션으로 인증 시도
+3. `privateKey` 파싱 실패 시 (암호화된 키 등) SSH agent만으로 재시도
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { SftpStorageClient } from "@simplysm/storage";
+
+const client = new SftpStorageClient();
+try {
+  await client.connect({ host: "sftp.example.com", user: "user", password: "pass" });
+  await client.put("/local/file.txt", "/remote/file.txt");
+} finally {
+  await client.close();
+}
+```
+
+### 전형 예제
+
+```typescript
+import { SftpStorageClient } from "@simplysm/storage";
+
+// SSH 키 인증 (password 생략)
+const client = new SftpStorageClient();
+try {
+  await client.connect({ host: "sftp.example.com", user: "user" });
+  await client.mkdir("/remote/dir");
+  await client.put("/local/file.txt", "/remote/dir/file.txt");
+  const list = await client.list("/remote/dir");
+  for (const item of list.filter((f) => f.isFile)) {
+    const content = await client.readFile(`/remote/dir/${item.name}`);
+    // content는 Bytes (Uint8Array)
+  }
+} finally {
+  await client.close(); // 예외 발생 여부와 무관하게 반드시 종료
+}
+```
+
+## 🚫 Anti-patterns
+
+### close() 없이 사용
+
+```typescript
+// ❌ finally 없이 사용하면 예외 시 연결 누수
+const client = new SftpStorageClient();
+await client.connect(config);
+await client.put("/local/file.txt", "/remote/file.txt");
+await client.close();
+
+// ✅ try/finally로 보장하거나 StorageFactory.connect() 사용
+```
+
+**근거**: 예외 발생 시 `close()`가 호출되지 않아 SFTP 연결이 누수된다.
+
+### 동일 인스턴스에서 connect() 중복 호출
+
+```typescript
+// ❌ close() 없이 connect()를 다시 호출하면 SdError 발생
+await client.connect(config);
+await client.connect(config); // SdError: "SFTP 서버에 이미 연결되어 있습니다"
+
+// ✅ close() 후 재연결
+await client.close();
+await client.connect(config);
+```
+
+**근거**: 내부 클라이언트가 이미 존재하면 `SdError`를 던진다.

package/claude/references/sd-simplysm-v14/storage/factory/storage-factory.md

@@ -0,0 +1,114 @@
+# `StorageFactory`
+
+스토리지 클라이언트 팩토리. 콜백 패턴으로 연결/종료를 자동 관리한다.
+
+## When to use
+
+- ✅ FTP/FTPS/SFTP 서버에 파일 업로드, 다운로드, 목록 조회 등 작업을 수행할 때 — 기본 진입점
+- ❌ 하나의 연결을 장시간 유지하면서 여러 작업 단위에 걸쳐 재사용해야 할 때 → [`FtpStorageClient`](../clients/ftp-storage-client.md) 또는 [`SftpStorageClient`](../clients/sftp-storage-client.md)를 직접 관리
+
+## Signature
+
+```typescript
+class StorageFactory {
+  static async connect<R>(
+    type: StorageProtocol,
+    config: StorageConnConfig,
+    fn: (storage: StorageClient) => R | Promise<R>,
+  ): Promise<R>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connect` | static method | `<R>(type: StorageProtocol, config: StorageConnConfig, fn: (storage: StorageClient) => R \| Promise<R>) => Promise<R>` | 프로토콜에 맞는 클라이언트를 생성하고, 연결 후 콜백을 실행하며, 완료/예외 시 자동으로 연결을 종료 |
+
+### `connect<R>()` 파라미터
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | `StorageProtocol` | 프로토콜 타입 |
+| `config` | [`StorageConnConfig`](../types/storage-conn-config.md) | 연결 설정 |
+| `fn` | `(storage: StorageClient) => R \| Promise<R>` | 연결된 클라이언트로 작업을 수행하는 콜백 |
+
+**반환**: `Promise<R>` — 콜백의 반환값
+
+**동작**:
+- `type`에 따라 [`FtpStorageClient`](../clients/ftp-storage-client.md) 또는 [`SftpStorageClient`](../clients/sftp-storage-client.md)를 생성
+- `client.connect(config)` 후 `fn(client)` 실행
+- `fn` 완료 또는 예외 발생 여부와 무관하게 `finally`에서 `client.close()` 호출
+- `fn`에서 발생한 예외는 그대로 전파
+
+## Related Types
+
+### `StorageProtocol`
+
+`StorageFactory.connect()`의 `type` 파라미터 타입.
+
+```typescript
+type StorageProtocol = "ftp" | "ftps" | "sftp";
+```
+
+| Variant | Description |
+|---------|-------------|
+| `"ftp"` | 일반 FTP. `FtpStorageClient(false)` 생성 |
+| `"ftps"` | TLS/SSL 암호화 FTP. `FtpStorageClient(true)` 생성 |
+| `"sftp"` | SSH 기반 SFTP. `SftpStorageClient()` 생성 |
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+// 파일 업로드
+await StorageFactory.connect(
+  "sftp",
+  { host: "sftp.example.com", user: "user", password: "pass" },
+  async (storage) => {
+    await storage.put("/local/file.txt", "/remote/file.txt");
+  },
+);
+```
+
+### 전형 예제
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+// 파일 목록 조회 후 반환값 활용
+const list = await StorageFactory.connect(
+  "ftp",
+  { host: "ftp.example.com", port: 21, user: "user", password: "pass" },
+  (storage) => storage.list("/data"),
+);
+
+// 바이트 데이터로 업로드
+const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
+await StorageFactory.connect(
+  "ftps",
+  { host: "ftps.example.com", user: "user", password: "pass" },
+  (storage) => storage.put(data, "/remote/file.bin"),
+);
+```
+
+## 🚫 Anti-patterns
+
+### 콜백 밖에서 클라이언트 참조 유지
+
+```typescript
+// ❌ 콜백이 끝나면 연결이 종료되므로 외부에서 클라이언트를 사용할 수 없다
+let savedClient: StorageClient;
+await StorageFactory.connect("sftp", config, (storage) => {
+  savedClient = storage;
+});
+await savedClient.list("/"); // 이미 close()된 상태
+
+// ✅ 필요한 작업을 모두 콜백 안에서 수행
+const list = await StorageFactory.connect("sftp", config, (storage) => storage.list("/"));
+```
+
+**근거**: `connect()`는 `finally`에서 `close()`를 호출하므로 콜백 종료 후 클라이언트는 사용 불가 상태다.

package/claude/references/sd-simplysm-v14/storage/types/file-info.md

@@ -0,0 +1,32 @@
+# FileInfo
+
+파일 또는 디렉토리 정보를 담는 인터페이스. [`StorageClient.list()`](./storage-client.md)의 반환 타입이다.
+
+```typescript
+interface FileInfo {
+  name: string;
+  isFile: boolean;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | 파일 또는 디렉토리의 이름 (경로 아님, 이름만) |
+| `isFile` | `boolean` | `true`이면 파일, `false`이면 디렉토리 |
+
+## Usage
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+const items = await StorageFactory.connect(
+  "sftp",
+  { host: "sftp.example.com", user: "user", password: "pass" },
+  async (storage) => storage.list("/remote/dir"),
+);
+
+const files = items.filter((item) => item.isFile);
+const dirs = items.filter((item) => !item.isFile);
+```