@simplysm/sd-claude 14.0.82 → 14.0.83

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

@@ -1,39 +0,0 @@
-# @simplysm/service-server — 인증
-
-## `auth(fn)` / `auth(permissions, fn)`
-
-서비스 factory 또는 개별 메서드를 래핑해 인증 요구사항을 부착. 래핑 함수는 호출 동작을 그대로 유지하며 내부 심볼에 `permissions: string[]` 저장.
-
-- 서비스 수준: `defineService("X", auth((ctx) => ({ ... })))` — 모든 메서드 로그인 필요.
-- 서비스 수준 + 역할: `defineService("X", auth(["admin"], (ctx) => ({ ... })))`.
-- 메서드 수준: factory 내부에서 `someMethod: auth(() => result)`.
-- 메서드 수준 + 역할: `someMethod: auth(["admin", "owner"], () => result)` — 배열 중 하나라도 매칭하면 통과(OR).
-
-실행 시(`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>`
-
-`jose.JWTPayload` 확장.
-
-- `roles: string[]` — `auth(["role"], fn)` 검사 대상.
-- `data: TAuthInfo` — 임의 사용자 데이터. `ctx.authInfo` 로 노출.
-
-## JWT 헬퍼
-
-`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" } });
-const payload = await verifyJwt<{ userId: string }>(secret, token);
-```

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

@@ -1,71 +0,0 @@
-# @simplysm/service-server — 빌트인 서비스
-
-`options.services` 에 추가해 사용. 각 `*ServiceType` 은 클라이언트의 `client.getService<*ServiceType>("<이름>")` 에 그대로 사용.
-
-## `OrmService`
-
-DB 연결을 WebSocket 세션과 묶어 원격 ORM 사용.
-
-- 별칭: `["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(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)`.
-
-`opt: DbConnOptions & { configName: string }`. 타입 export: `OrmServiceType`.
-
-## `AutoUpdateService`
-
-- 별칭: `["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`.
-
-## `AppStructureService(itemsMap)`
-
-다른 두 서비스와 달리 **팩토리 함수**(서비스 정의가 아님). 호출 결과를 `services` 에 등록.
-
-- 시그니처: `AppStructureService(itemsMap: Record<string, AppStructureItem[]>): ServiceDefinition`
-- 서비스 이름: `"AppStructure"`. 인증 없음.
-- 메서드: `getItems(): Record<string, AppStructureItem[]>` — 주입된 map 그대로 반환.
-- 타입 export: `AppStructureServiceType`.
-
-`AppStructureItem` 은 `@simplysm/service-common` 정의(메뉴/라우트 트리 항목).
-
-```ts
-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,55 +0,0 @@
-# @simplysm/service-server — 서비스 정의
-
-## `defineService(name, factory): ServiceDefinition<TMethods>`
-
-- `name: string | string[]` — 단일 또는 별칭 목록. 첫 요소가 primary(`def.name`), 전체가 `def.names`. RPC 라우팅은 `names.includes(요청서비스명)` 매칭. 빈 배열이면 throw.
-- `factory: (ctx: ServiceContext) => TMethods` — 매 요청마다 호출되어 메서드 객체 생성(컨텍스트 캡처). factory 자체가 `auth(...)` 래핑이면 `authPermissions` 가 자동 추출돼 서비스 수준 인증으로 승격.
-
-반환 `ServiceDefinition<TMethods>`:
-
-- `name: string`
-- `names: string[]`
-- `factory`
-- `authPermissions?: string[]`
-
-## `ServiceContext<TAuthInfo>`
-
-서비스 factory 가 받는 요청별 컨텍스트.
-
-- `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` 로 변경 감시되어 자동 리로드.
-
-## `ServiceMethods<TDefinition>` 타입
-
-`ServiceDefinition<M>` 에서 `M` 추출. 클라이언트의 `client.getService<MyServiceType>("MyService")` 에 사용.
-
-```ts
-export const UserService = defineService("User", (ctx) => ({
-  getProfile: () => ({ name: "kim" }),
-}));
-export type UserServiceType = ServiceMethods<typeof UserService>;
-```
-
-## 보조 export
-
-- `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", "MyUser"], auth((ctx) => ({
-  me: () => ctx.authInfo,
-  adminOnly: auth(["admin"], () => "ok"),
-})));
-```

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

@@ -1,82 +0,0 @@
-# @simplysm/service-server — 내부 전송 계층
-
-`ServiceServer.listen()` 이 자동 결선하므로 일반 사용에선 불필요. 커스텀 Fastify 라우트·테스트·비표준 전송 시 참고.
-
-## HTTP
-
-### `handleHttpRequest(req, reply, jwtSecret, runMethod)`
-
-`/api/:service/:method` 라우트 핸들러.
-
-- `x-sd-client-name` 헤더 필수(없으면 throw).
-- `Authorization: Bearer <jwt>` 있고 `jwtSecret` 도 있으면 `verifyJwt`. 토큰만 있고 secret 없으면 throw. 검증 실패 시 401 응답.
-- GET: `?json=<JSON encoded array>` → `json.parse`.
-- POST: body 가 배열이어야 함(아니면 400).
-- 그 외 메서드: 405.
-- `runMethod({ serviceName, methodName, params, http: { clientName, authTokenPayload } })` 호출 후 결과를 `reply.send`.
-
-### `handleUpload(req, reply, rootPath, jwtSecret)`
-
-multipart 업로드. `Authorization` 헤더 필수(없으면 401, `jwtSecret` 미구성 시 401). 각 파일을 `<rootPath>/www/uploads/<uuid><ext>` 로 저장. 응답 `ServiceUploadResult[] = { path, filename, size }[]` (`path` = `uploads/<saveName>`). 도중 truncated 또는 에러 발생 시 진행 중 + 이미 저장된 모든 파일 삭제 후 500.
-
-### `handleStaticFile(req, reply, rootPath, urlPath)`
-
-`<rootPath>/www/<urlPath>` 정적 서빙.
-
-- 경로 탐색 차단: `pathx.isChildPath(targetFilePath, allowedRootPath)` 가드.
-- 디렉터리 + URL 미 trailing slash → `pathname + "/"` 리다이렉트. trailing slash 있으면 `<dir>/index.html` 사용.
-- 숨김 파일(basename 이 `.` 시작) → 403.
-- ENOENT 404, 기타 500. 에러는 HTML 응답.
-
-## WebSocket
-
-### `createWebSocketHandler(runMethod, jwtSecret): WebSocketHandler`
-
-여러 WS 연결 풀 관리. 처리 메시지:
-
-- `<service>.<method>` (body 가 배열) → RPC. `runMethod` 위임.
-- `evt:add { key, name, info }` — 이벤트 리스너 등록.
-- `evt:remove { key }` — 제거.
-- `evt:gets { name }` — 모든 소켓의 해당 이벤트 리스너 정보 조회.
-- `evt:emit { keys, data }` — 매칭 키 가진 소켓에게 `evt:on` 푸시.
-- `auth <token>` — JWT 검증 후 `socket.authTokenPayload` 설정.
-
-에러 코드: `BAD_MESSAGE`(알 수 없는 요청), `INTERNAL_ERROR`. `env("DEV")` truthy 시 `stack` 포함.
-
-`addSocket(socket, clientId, clientName, connReq)` 동일 clientId 이전 연결 자동 종료 후 교체. `emit(name, infoSelector, data)` 는 `ServiceServer.emitEvent` 의 백엔드.
-
-### `createServiceSocket(socket, clientId, clientName, connReq): ServiceSocket`
-
-단일 WS 관리.
-
-- 5초 ping/pong (`socket.ping()` → 응답 없으면 `terminate()`).
-- 1바이트 `0x01`(ping) 수신 → `0x02`(pong) 송신.
-- 메시지는 `createServerProtocolWrapper()` 통과. 진행률(`type === "progress"`) 디코드 결과는 자동으로 `progress` 메시지 회신.
-
-표면: `connectedAtDateTime: DateTime`, `clientName`, `connReq`, `authTokenPayload`(get/set), `close()`, `send(uuid, msg)`(전송 바이트), `addListener(key, eventName, info)`, `removeListener(key)`, `getEventListeners(eventName)`, `filterEventTargetKeys(targetKeys)`, `on("error"|"close"|"message", handler)`.
-
-## 프로토콜 래퍼
-
-### `createServerProtocolWrapper(): ServerProtocolWrapper`
-
-`@simplysm/service-common` 의 `createServiceProtocol()` 기반. 무거운 케이스만 워커 스레드로 위임:
-
-- encode: body 가 `Uint8Array` 이거나 `Uint8Array` 요소를 하나라도 가진 배열 → 워커.
-- decode: 입력 바이트 > 30KB → 워커.
-
-워커는 모듈 로드 시 1회 생성 lazy singleton(`maxOldGenerationSizeMb: 4096`). 워커 모듈: `workers/service-protocol.worker.ts`.
-
-표면: `encode(uuid, message)`, `decode(bytes)`, `dispose()`(메인 스레드 프로토콜만 정리, 워커는 공유).
-
-## 설정 캐시
-
-### `getConfig<T>(filePath: string): Promise<T | undefined>`
-
-JSON 설정 파일 로더.
-
-- `LazyGcMap` 캐시: 만료 1시간, GC 10분 간격. 캐시 히트 시 만료 시간 자동 갱신.
-- 파일 없으면 undefined.
-- `FsWatcher` 로 변경 감시 → 100ms 디바운스 후 리로드. 삭제 감지 시 캐시·워처 정리.
-- 만료 시 워처도 함께 해제.
-
-`ServiceContext.getConfig(section)` 이 root/client `.config.json` 두 경로를 이 함수로 읽어 `obj.merge`. 그 외 경로의 설정 파일을 읽을 때만 직접 호출.

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

@@ -1,57 +0,0 @@
-# @simplysm/service-server — 서버
-
-## `createServiceServer<TAuthInfo>(options): ServiceServer<TAuthInfo>`
-
-`new ServiceServer(options)` 단순 팩토리. `TAuthInfo` 는 JWT payload 의 `data` 필드 타입.
-
-## `ServiceServerOptions`
-
-- `rootPath: string` — 정적/업로드/설정 루트. 정적은 `<rootPath>/www/`, 업로드 저장은 `<rootPath>/www/uploads/`, 설정은 `<rootPath>/.config.json` 및 `<rootPath>/www/<clientName>/.config.json`.
-- `port: number` — listen 포트. host 는 항상 `0.0.0.0`.
-- `ssl?: { pfxBytes: Uint8Array; passphrase: string }` — 지정 시 HTTPS. 내부에서 `Buffer.from(pfxBytes)` 변환. 미지정 시 helmet 의 `upgrade-insecure-requests` 제거, `hsts`/`crossOriginOpenerPolicy` 비활성.
-- `auth?: { jwtSecret: string } | false`
-  - `undefined`(미지정): auth 미구성. 인증 요구 서비스가 하나라도 있으면 `listen()` 시 throw.
-  - `false`: 의도적 비활성화. `auth()` 래핑된 서비스/메서드도 인증 스킵.
-  - 객체: jwt 시크릿 등록.
-- `services: ServiceDefinition[]` — `defineService()` 결과 배열.
-- `legacyV1Handlers?: V1RequestHandler[]` — ver≠"2" 로 접속한 클라이언트의 커스텀 핸들러. 이 배열도 비고 `AutoUpdate` 서비스도 services 에 없으면 V1 연결을 1008 로 거부.
-
-## `ServiceServer<TAuthInfo>`
-
-`EventEmitter<{ ready: void; close: void }>` 상속.
-
-- `readonly options: ServiceServerOptions`
-- `readonly fastify: FastifyInstance` — 생성자에서 즉시 생성, 플러그인은 `listen()` 시 등록.
-- `isOpen: boolean`
-- `listen(): Promise<void>` — fastify 플러그인(`@fastify/websocket`, `@fastify/helmet`, `@fastify/multipart`, `@fastify/static`, `@fastify/cors`) 등록, JSON 파서/직렬화기를 `@simplysm/core-common` 의 `json` 으로 교체(Date/BigInt/Uint8Array 보존), 라우트 바인딩, `0.0.0.0:port` listen, SIGINT/SIGTERM 핸들러 등록(10초 후 `process.exit(1)` 강제), `ready` 이벤트 발생.
-- `close(): Promise<void>` — 모든 WebSocket 종료 → `fastify.close()` → `close` 이벤트.
-- `getEvent<TEventDef>(eventName): ServerEventProxy<TEventDef>` — `{ emit(infoSelector, data): Promise<void> }` 핸들 반환.
-- `emitEvent<TEventDef>(eventName, infoSelector, data): Promise<void>` — 클라이언트가 `evt:add` 로 등록한 리스너 중 `infoSelector(info) === true` 인 키에만 푸시.
-- `signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>` — HS256, `exp` 12h 고정. `jwtSecret` 미구성 시 throw.
-- `verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>` — 만료/위조 시 throw.
-
-`TEventDef` 는 `@simplysm/service-common` 의 `ServiceEventDef`(`{ $info; $data }` 형태). `infoSelector` 는 클라이언트가 listener 등록 시 보낸 `info` 객체를 받아 boolean 반환.
-
-## 자동 등록되는 라우트
-
-- `ALL /api/:service/:method` — RPC. `x-sd-client-name` 헤더 필수, `Authorization: Bearer <jwt>` 옵션. GET 은 `?json=<JSON encoded array>`, POST 는 body 가 params 배열. 그 외 HTTP 메서드 405.
-- `ALL /upload` — multipart 업로드. 인증 헤더 필수. 응답 `ServiceUploadResult[]`.
-- `GET /`, `GET /ws` — WebSocket. 쿼리 `ver=2&clientId=<id>&clientName=<name>` (clientId/clientName 누락 시 1008). ver≠"2" → V1 레거시.
-- `* /*` — 정적 서빙(`/api/...`·`/upload`·`/`·`/ws` 외).
-
-## 예
-
-```ts
-const server = createServiceServer<{ userId: string }>({
-  rootPath: process.cwd(),
-  port: 50080,
-  auth: { jwtSecret: process.env.JWT_SECRET! },
-  services: [UserService, OrmService],
-});
-server.on("ready", () => console.log("up"));
-await server.listen();
-
-const token = await server.signAuthToken({ roles: ["admin"], data: { userId: "u1" } });
-await server.getEvent<{ $info: { shopId: number }; $data: { id: number } }>("order-created")
-  .emit(info => info.shopId === 1, { id: 99 });
-```

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

@@ -1,71 +0,0 @@
-# @simplysm/storage
-
-FTP/FTPS/SFTP 원격 스토리지에 동일 인터페이스(`StorageClient`)로 파일을 읽고/쓰는 Node 라이브러리.
-
-## 사용 트리거 인덱스
-
-- **`StorageFactory.connect`** — FTP/FTPS/SFTP 어느 것이든 연결→작업→자동 종료를 한 번에 처리할 때 (권장 진입점).
-- **`StorageClient`** — 콜백 안에서 사용하는 공통 파일 작업 인터페이스(mkdir/list/readFile/put/uploadDir/remove/rename/exists).
-- **`FtpStorageClient` / `SftpStorageClient`** — 연결 생명주기를 직접 관리해야 할 때만 (장기 연결 풀 등). 그 외엔 `StorageFactory.connect` 사용.
-- **`StorageConnConfig`** — `connect`/`StorageFactory.connect` 에 넘기는 접속 정보(host/port/user/password) 타입.
-- **`StorageProtocol`** — `StorageFactory.connect` 의 `type` 인자로 쓰는 프로토콜 리터럴(`"ftp" | "ftps" | "sftp"`).
-- **`FileInfo`** — `list` 결과 항목 타입(`{ name, isFile }`).
-
-## StorageFactory.connect
-
-```ts
-class StorageFactory {
-  static connect<R>(
-    type: StorageProtocol,                                   // "ftp" | "ftps" | "sftp"
-    config: StorageConnConfig,
-    fn: (storage: StorageClient) => R | Promise<R>,
-  ): Promise<R>;
-}
-```
-
-- `type` 에 따라 `FtpStorageClient(secure=false)` / `FtpStorageClient(secure=true)` / `SftpStorageClient` 생성.
-- 콜백 실행 전 `connect`, 콜백 종료(예외 포함) 후 `close` 자동 호출. `close` 실패는 무시.
-
-```ts
-const list = await StorageFactory.connect("sftp", { host, user, password }, async (s) => {
-  await s.mkdir("/up/2026");
-  await s.put(Buffer.from("hi"), "/up/2026/a.txt");
-  return await s.list("/up/2026");
-});
-```
-
-## StorageClient
-
-```ts
-interface StorageClient {
-  connect(config: StorageConnConfig): Promise<void>;
-  mkdir(dirPath: string): Promise<void>;                              // 부모 디렉토리 자동 생성
-  rename(fromPath: string, toPath: string): Promise<void>;
-  list(dirPath: string): Promise<FileInfo[]>;                         // { name, isFile }
-  readFile(filePath: string): Promise<Bytes>;                         // Bytes = Uint8Array (@simplysm/core-common)
-  exists(filePath: string): Promise<boolean>;                         // 모든 예외 시 false
-  put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;  // string=로컬 경로, Bytes=메모리 버퍼
-  uploadDir(fromPath: string, toPath: string): Promise<void>;         // 디렉토리 통째로 업로드
-  remove(filePath: string): Promise<void>;
-  close(): Promise<void>;                                             // 이미 종료돼 있어도 안전
-}
-
-interface StorageConnConfig { host: string; port?: number; user?: string; password?: string; }
-interface FileInfo { name: string; isFile: boolean; }
-type StorageProtocol = "ftp" | "ftps" | "sftp";
-```
-
-## FtpStorageClient / SftpStorageClient
-
-`StorageClient` 구현체. 직접 사용 시 주의:
-
-- `connect` 후 반드시 `close`. 동일 인스턴스에서 `connect` 중복 호출 금지(연결 누수 → `SdError` throw). `close` 후 재연결은 가능.
-- `FtpStorageClient(secure: boolean)` — `secure=true` 가 FTPS.
-- `SftpStorageClient` — `config.password` 가 있으면 비밀번호 인증. 없으면 `~/.ssh/id_ed25519` 키 + (있으면) `SSH_AUTH_SOCK` agent 로 시도, 키 파싱 실패 시 agent 단독 재시도.
-- `FtpStorageClient.exists` — 파일은 `size()` 로 O(1), 디렉토리는 부모 `list()` 스캔. 슬래시 없는 경로는 `/` 기준.
-
-```ts
-const client = new SftpStorageClient();
-await client.connect({ host, user, password });
-try { /* ... */ } finally { await client.close(); }
-```