@simplysm/sd-claude 14.0.88 → 14.0.89

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

@@ -1,14 +1,14 @@
 # @simplysm/storage
 
-FTP/FTPS/SFTP 원격 스토리지에 연결해 파일·디렉토리를 업로드·다운로드·조회·삭제하는 Node 전용 클라이언트. 프로토콜별 구현을 동일 인터페이스(`StorageClient`)로 통일하고, 팩토리(`StorageFactory.connect`)로 연결/종료를 자동 관리.
+FTP / FTPS / SFTP 원격 스토리지에 연결해 파일·디렉토리를 업로드·다운로드·조회·삭제하는 Node 전용 클라이언트. 프로토콜별 구현을 동일 인터페이스(`StorageClient`)로 통일하고, 팩토리(`StorageFactory.connect`)로 연결/종료를 자동 관리.
 
 ## 사용 트리거 인덱스
 
-- **StorageFactory.connect** — 원격 스토리지에 접속해 파일 작업을 한 뒤 자동으로 연결을 닫고 싶을 때. 권장 진입점.
+- **StorageFactory** — 원격 스토리지에 접속해 파일 작업을 한 뒤 자동으로 연결을 닫고 싶을 때. 권장 진입점.
 - **StorageClient** — `connect` 콜백 안에서 받는 파일 조작 인터페이스. mkdir/list/readFile/put/remove 등 호출 시 참조.
-- **FileInfo** — `list()` 가 돌려주는 항목 구조(이름·파일여부)를 확인할 때.
 - **StorageConnConfig** — 접속 호스트/계정/비밀번호를 구성할 때.
 - **StorageProtocol** — 프로토콜 종류(`ftp`/`ftps`/`sftp`)를 지정할 때.
+- **FileInfo** — `list()` 가 돌려주는 항목 구조(이름·파일여부)를 확인할 때.
 - **FtpStorageClient / SftpStorageClient** — 팩토리 없이 클라이언트를 직접 인스턴스화·재연결 제어해야 할 때(비권장).
 
 ## StorageProtocol
@@ -30,20 +30,26 @@ interface StorageConnConfig { host: string; port?: number; user?: string; passwo
 - `host: string` — 접속 대상 서버 호스트명 또는 IP. 필수.
 - `port?: number` — 접속 포트. 미지정 시 각 라이브러리 기본값(FTP 21, SFTP 22) 사용.
 - `user?: string` — 로그인 사용자명. 미지정 시 익명/기본 사용자.
-- `password?: string` — 로그인 비밀번호. **SFTP 에서 이 값이 `null`/미지정이면** password 인증 대신 `~/.ssh/id_ed25519` 개인키와 SSH agent(`SSH_AUTH_SOCK`) 로 인증 시도하고, 키 파싱 실패(암호화 키 등) 시 agent 단독으로 재시도.
+- `password?: string` — 로그인 비밀번호. **SFTP 에서 이 값이 `null`/미지정이면** password 인증 대신 `~/.ssh/id_ed25519` 개인키와 SSH agent(`SSH_AUTH_SOCK` 환경변수가 설정된 경우 `agent` 옵션) 로 인증 시도하고, 키 파싱 실패(암호화 키 등) 시 agent 단독으로 재시도. FTP/FTPS 에서는 미지정 시 라이브러리 기본(익명) 처리.
 
 ## StorageFactory
 
-스토리지 접속 진입점. 연결 생성 → 콜백 실행 → 자동 종료를 묶어 처리한다.
+스토리지 접속 진입점. 연결 생성 → 콜백 실행 → 자동 종료를 묶어 처리한다. 인스턴스를 직접 만들 필요 없이 정적 `connect` 만 사용.
 
 ```ts
-static connect<R>(type: StorageProtocol, config: StorageConnConfig, fn: (storage: StorageClient) => R | Promise<R>): Promise<R>
+class StorageFactory {
+  static connect<R>(
+    type: StorageProtocol,
+    config: StorageConnConfig,
+    fn: (storage: StorageClient) => R | Promise<R>,
+  ): Promise<R>;
+}
 ```
 
 - `type: StorageProtocol` — 사용할 프로토콜. `"sftp"` → `SftpStorageClient`, `"ftps"` → `FtpStorageClient(secure=true)`, `"ftp"` → `FtpStorageClient(secure=false)` 를 내부 생성.
 - `config: StorageConnConfig` — 접속 설정.
-- `fn` — 연결된 `StorageClient` 를 받아 파일 작업을 수행하는 콜백. 반환값이 그대로 `connect` 의 결과(`Promise<R>`) 가 됨.
-- 동작: `client.connect()` 후 `fn` 실행, `finally` 에서 `client.close()` 호출하며 종료 오류는 무시. 콜백에서 예외가 나도 연결은 반드시 닫히고 예외는 그대로 전파됨. 직접 클라이언트를 다루는 것보다 권장.
+- `fn: (storage: StorageClient) => R | Promise<R>` — 연결된 `StorageClient` 를 받아 파일 작업을 수행하는 콜백. 반환값이 그대로 `connect` 의 결과(`Promise<R>`) 가 됨.
+- 동작: `client.connect()` 후 `fn` 실행, `finally` 에서 `client.close()` 호출하며 종료 오류는 무시(이미 종료된 경우 대비). 콜백에서 예외가 나도 연결은 반드시 닫히고 예외는 그대로 전파됨. 직접 클라이언트를 다루는 것보다 권장.
 
 ```ts
 const names = await StorageFactory.connect("sftp", { host: "10.0.0.1", user: "u", password: "p" }, async (s) => {
@@ -72,16 +78,16 @@ interface StorageClient {
 }
 ```
 
-- `connect(config)` — 서버에 연결. 이미 연결된 인스턴스에서 재호출하면 `SdError` throw(먼저 `close()` 필요). `StorageFactory.connect` 사용 시 직접 호출 불필요.
+- `connect(config)` — 서버에 연결. 이미 연결된 인스턴스에서 재호출하면 `SdError` throw(먼저 `close()` 필요). `StorageFactory.connect` 사용 시 직접 호출 불필요. 연결 도중 실패하면 내부 라이브러리 연결을 닫고 예외를 다시 throw.
 - `mkdir(dirPath)` — 디렉토리 생성. 부모 디렉토리가 없으면 함께 생성(FTP `ensureDir`, SFTP 재귀 `mkdir`).
 - `rename(fromPath, toPath)` — 파일/디렉토리 경로 이동·이름 변경.
 - `list(dirPath)` — 디렉토리 내 항목을 `FileInfo[]` 로 반환.
-- `readFile(filePath)` — 원격 파일 전체를 `Bytes`(Uint8Array) 로 다운로드. SFTP 는 응답이 예상 타입(Buffer/string) 이 아니면 `SdError` throw.
-- `exists(filePath)` — 파일/디렉토리 존재 여부. **모든 예외(부모 없음·권한·네트워크 오류 포함) 에 대해 `false` 반환** — true/false 외 throw 없음. FTP 는 `size()` 로 파일을 O(1) 확인 후 실패 시 부모 디렉토리 목록으로 디렉토리 확인(슬래시 없는 경로는 루트 `/` 기준).
-- `put(localPathOrBuffer, storageFilePath)` — 업로드. 첫 인자가 `string` 이면 로컬 파일 경로, `Bytes` 면 메모리 바이트를 업로드 대상으로 사용.
-- `uploadDir(fromPath, toPath)` — 로컬 디렉토리 전체를 원격 디렉토리로 업로드.
+- `readFile(filePath)` — 원격 파일 전체를 `Bytes`(Uint8Array) 로 메모리에 다운로드(스트리밍 아님 — 큰 파일은 메모리 부담). 텍스트가 필요하면 호출 측에서 디코딩. SFTP 는 응답이 예상 타입(Buffer/string) 이 아니면 `SdError` throw.
+- `exists(filePath)` — 파일/디렉토리 존재 여부. **모든 예외(부모 없음·권한·네트워크 오류 포함) 에 대해 `false` 반환** — true/false 외 throw 없음. 따라서 `true` 만 "확실히 존재"로 신뢰한다. FTP 는 `size()` 로 파일을 O(1) 확인 후 실패 시 부모 디렉토리 목록으로 디렉토리 확인(슬래시 없는 경로는 루트 `/` 기준이라 항목 많은 디렉토리에서는 느려질 수 있음). SFTP 는 `exists()` 결과가 문자열(`'d'`/`'-'`/`'l'`)이면 존재로 판정.
+- `put(localPathOrBuffer, storageFilePath)` — 단일 파일 업로드. 첫 인자가 `string` 이면 로컬 파일 경로, `Bytes` 면 메모리 바이트를 업로드 대상으로 사용.
+- `uploadDir(fromPath, toPath)` — 로컬 디렉토리 전체를 원격 디렉토리로 재귀 업로드.
 - `remove(filePath)` — 원격 파일 삭제.
-- `close()` — 연결 종료. 이미 종료된 상태에서 호출해도 오류 없음. 종료 후 같은 인스턴스에서 `connect()` 로 재연결 가능.
+- `close()` — 연결 종료. 이미 종료/미연결 상태에서 호출해도 오류 없음. 종료 후 같은 인스턴스에서 `connect()` 로 재연결 가능. `StorageFactory.connect` 사용 시 직접 호출 불필요.
 
 미연결 상태에서 작업 메서드를 호출하면 모든 구현체가 `SdError`("연결되어 있지 않습니다") throw.
 
@@ -91,12 +97,12 @@ interface StorageClient {
 interface FileInfo { name: string; isFile: boolean; }
 ```
 
-- `name: string` — 항목 이름(파일명 또는 디렉토리명).
-- `isFile: boolean` — 파일이면 `true`, 디렉토리면 `false`. SFTP 는 항목 type 이 `"-"` 인 경우만 `true`(디렉토리·심볼릭 링크는 `false`).
+- `name: string` — 항목 이름(파일명 또는 디렉토리명, 경로 아님).
+- `isFile: boolean` — 파일이면 `true`, 디렉토리면 `false`. 디렉토리 재귀 탐색 시 파일만 골라 처리하는 분기 기준으로 사용. SFTP 는 항목 type 이 `"-"` 인 경우만 `true`(디렉토리·심볼릭 링크는 `false`).
 
 ## FtpStorageClient / SftpStorageClient (직접 사용, 비권장)
 
-`StorageClient` 직접 구현체. 보통은 `StorageFactory.connect` 로 충분하며, 연결 수명을 수동으로 다뤄야 할 때만 직접 생성한다.
+`StorageClient` 직접 구현체. 보통은 `StorageFactory.connect` 로 충분하며, 연결 수명을 콜백 밖에서 수동으로 다뤄야 할 때만 직접 생성한다.
 
 ```ts
 new FtpStorageClient(secure?: boolean)  // secure=true → FTPS, 생략/false → 평문 FTP
@@ -105,7 +111,7 @@ new SftpStorageClient()
 
 - `FtpStorageClient` 의 `secure` 생성자 인자 — `true` 면 TLS(FTPS), 생략/`false` 면 평문 FTP. (팩토리는 `ftps`→`true`, `ftp`→`false` 로 매핑.)
 - `SftpStorageClient` 는 생성자 인자 없음. password 미지정 시 키/agent 인증 경로를 탄다(StorageConnConfig 의 `password` 풀이 참조).
-- 직접 사용 시 `connect()` → 작업 → `close()` 순으로 호출하고 호출 측이 종료를 책임져야 함(연결 누수 주의).
+- 직접 사용 시 `connect()` → 작업 → `close()` 순으로 호출하고, 예외 발생 시에도 `close()` 가 호출되도록 `try/finally` 로 감쌀 것. 동일 인스턴스에서 `close()` 없이 `connect()` 를 재호출하면 연결 누수로 throw.
 
 ```ts
 const client = new SftpStorageClient();

package/claude/skills/sd-demo/SKILL.md

@@ -30,6 +30,12 @@ spec.md 의 화면 1개를 클라이언트 패키지의 화면 컴포넌트 자
 
 **충돌 확인**: 대상 화면(또는 동반 모달 화면) 의 파일이 이미 존재하면 묻기 — ① 덮어쓰기 / ② spec 변경분만 보강 / ③ 취소. 호출자 발화에 명시된 분기가 있으면 묻지 않고 그 분기로 진행.
 
+**마커 점검**: 대상 화면(또는 동반 모달 화면) 의 헤더 마커 확인.
+
+- 헤더 미확정(마커 없음) / `[확정: 날짜]` → 본문에 와이어프레임·항목 초안이 있으면 그대로 진행 (미확정은 미검토 초안이지만 데모가 그 검토를 돕는 시각화이므로 정상).
+- 단 미확정 섹션의 본문이 와이어프레임·항목 없이 분석 방법뿐이면 → 시각화할 내용 없음. 사용자에게 보고하고 중단 (sd-spec 으로 해당 화면을 먼저 채우도록 안내).
+- 본문 인라인 `[OPEN]` 항목 → 4단계의 더미 마커로 placeholder 처리.
+
 ### 2단계: 대상 화면 항목 분석
 
 spec.md 의 대상 화면 항목에서 다음을 추출:

package/claude/skills/sd-impl/SKILL.md

@@ -33,20 +33,17 @@ spec.md 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 공통·기반 기능)
 
 작업 대상 §4.x/§5.x/§6.x 와 작업 대상이 참조하는 §5/§6/§7/§8/§9 항목을 점검:
 
-- **헤더 `[OPEN: 날짜]` 섹션**: 본문이 재분석 포인터일 뿐 초안 부재 → "spec 수정 절차" 적용.
+- **헤더 미확정(마커 없음) 섹션**: 사용자 미검토 상태 → 그대로 구현하지 않음. 해당 § 을 사용자에게 제시·검토 요청 → 확정/수정 후 `[확정]` 으로 승격 → 진행. 단 본문이 초안 없이 재분석 방법뿐이면 "spec 수정 절차" 적용.
 - **본문 인라인 `[OPEN]`**: 결정 근거가 있으면 결정. 없으면 1건씩 질문 → 답변 후 "spec 수정 절차" 적용.
 - **사용자 제공 예정 자료**: spec 본문에 사용자 회신 대기로 적힌 자료. 사용자 회신 후 진행.
 - **묵시적 모호**: 명시 마커는 없지만 spec 본문이 분기·정의·정의식·경계 케이스를 다루지 않는 부분. 4단계 분해 중 발견 가능성 높음. 발견 시 본 단계로 회귀.
 
 #### spec 수정 절차
 
-spec 본문 수정이 필요한 경우(인라인 `[OPEN]` 해소·헤더 `[OPEN]` 해소·구조 변경·6단계 (b)(d) 분류 처리 등) 메인 LLM 이 직접 처리:
+spec 본문 수정이 필요한 경우(인라인 `[OPEN]` 해소·미확정 섹션 확정·구조 변경·6단계 (b)(d) 분류 처리 등) 메인 LLM 이 직접 처리:
 
-1. **sd-spec SKILL.md Read** — 룰 인지 (초안 작성 사이클·헤더 마커 형식·관련 섹션·의존 식별 룰).
-2. **초안 → "맞나요?" → 확정 → spec.md Edit** (sd-spec 사이클 적용).
-3. **의존 식별** — 수정된 § 항목을 의존으로 가진 §4.x/§5.x/§6.x 탐색 (sd-spec "의존 식별" 룰). 본 작업 단위 자신은 제외 (작업 중).
-4. **마커 제거** — 의존 §4.x/§5.x/§6.x 헤더의 `, 구현: YYYY-MM-DD` 부분만 제거 (이전 구현 무효화).
-   - 영향 단위에 번호를 매겨 사용자에게 모아서 "맞나요?" 질문 — 전체 동의 → 일괄 제거 / 일부 유지 지목 → 지목 항목 마커 유지.
+1. **sd-spec SKILL.md Read** — 룰 인지.
+2. **재분석/검토 → 확정 → spec.md Edit** — sd-spec 의 "확정 섹션 수정·구현 무효화" 룰 적용. `[확정]` 산출이므로 합의(행동 규칙) 후 헤더 `[확정: 날짜]` 부착. 수정으로 무효화되는 구현 §4.x/§5.x/§6.x (본 작업 단위 자신은 제외 — 작업 중) 의 `, 구현: …` 마커 제거를 합의 내용에 함께 올림.
 
 본 작업 단위(§4.x/§5.x/§6.x 자신)의 헤더 `[확정]` 은 9단계에서 `[확정, 구현]` 으로 확장.