@simplysm/sd-claude 14.0.50 → 14.0.52

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

@@ -0,0 +1,55 @@
+# `StorageClient`
+
+스토리지 클라이언트 공통 인터페이스. [`FtpStorageClient`](../clients/ftp-storage-client.md)와 [`SftpStorageClient`](../clients/sftp-storage-client.md)가 구현한다.
+
+## When to use
+
+- ✅ 프로토콜에 무관한 스토리지 작업 함수를 작성할 때 (파라미터/반환 타입으로 사용)
+- ❌ 직접 인스턴스화할 수 없다 — 구현체인 `FtpStorageClient`/`SftpStorageClient`를 사용하거나, [`StorageFactory.connect()`](../factory/storage-factory.md) 콜백에서 제공받는다
+
+## Signature
+
+```typescript
+interface StorageClient {
+  connect(config: StorageConnConfig): Promise<void>;
+  mkdir(dirPath: string): Promise<void>;
+  rename(fromPath: string, toPath: string): Promise<void>;
+  list(dirPath: string): Promise<FileInfo[]>;
+  readFile(filePath: string): Promise<Bytes>;
+  exists(filePath: string): Promise<boolean>;
+  put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
+  uploadDir(fromPath: string, toPath: string): Promise<void>;
+  remove(filePath: string): Promise<void>;
+  close(): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connect` | method | `(config: StorageConnConfig) => Promise<void>` | 스토리지 서버에 연결. 이미 연결된 상태에서 호출하면 `SdError` 발생 |
+| `mkdir` | method | `(dirPath: string) => Promise<void>` | 디렉토리 생성. 부모 디렉토리가 없으면 함께 생성 |
+| `rename` | method | `(fromPath: string, toPath: string) => Promise<void>` | 파일/디렉토리 이름 변경 또는 이동 |
+| `list` | method | `(dirPath: string) => Promise<FileInfo[]>` | 디렉토리 내 파일/디렉토리 목록 조회 |
+| `readFile` | method | `(filePath: string) => Promise<Bytes>` | 파일 내용을 `Bytes`(`Uint8Array`)로 읽기 |
+| `exists` | method | `(filePath: string) => Promise<boolean>` | 파일/디렉토리 존재 여부 확인. 모든 예외는 `false` 반환 |
+| `put` | method | `(localPathOrBuffer: string \| Bytes, storageFilePath: string) => Promise<void>` | 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드 |
+| `uploadDir` | method | `(fromPath: string, toPath: string) => Promise<void>` | 로컬 디렉토리 전체를 원격 경로에 업로드 |
+| `remove` | method | `(filePath: string) => Promise<void>` | 파일 삭제 |
+| `close` | method | `() => Promise<void>` | 연결 종료. 이미 종료된 상태에서 호출해도 안전 |
+
+## Usage
+
+```typescript
+import type { StorageClient } from "@simplysm/storage";
+import { StorageFactory } from "@simplysm/storage";
+
+// StorageClient 타입을 직접 사용하는 경우 (예: 함수 파라미터 타입)
+async function doWork(storage: StorageClient): Promise<void> {
+  await storage.mkdir("/remote/dir");
+  await storage.put("/local/file.txt", "/remote/dir/file.txt");
+}
+
+await StorageFactory.connect("sftp", { host: "sftp.example.com", user: "user", password: "pass" }, doWork);
+```

package/claude/references/sd-simplysm-v14/storage/types/storage-conn-config.md

@@ -0,0 +1,34 @@
+# StorageConnConfig
+
+스토리지 서버 연결 설정 인터페이스.
+
+```typescript
+interface StorageConnConfig {
+  host: string;
+  port?: number;
+  user?: string;
+  password?: string;
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `host` | `string` | 서버 호스트 주소 |
+| `port` | `number \| undefined` | 포트 번호. 생략 시 프로토콜 기본값 사용 (FTP/FTPS: 21, SFTP: 22) |
+| `user` | `string \| undefined` | 사용자 이름 |
+| `password` | `string \| undefined` | 비밀번호. SFTP에서 생략하면 SSH agent + `~/.ssh/id_ed25519` 키 파일 인증을 순서대로 시도 |
+
+## Usage
+
+```typescript
+import type { StorageConnConfig } from "@simplysm/storage";
+
+const config: StorageConnConfig = {
+  host: "sftp.example.com",
+  port: 22,
+  user: "user",
+  password: "pass",
+};
+```

package/claude/rules/sd-claude-rules.md

@@ -4,32 +4,31 @@
 - `cd` 명령을 통한 타 폴더로의 이동 금지.
 - `npx tsc` 사용 금지. 반드시 `pnpm typecheck [targets..]`등의 스크립트 사용
 - `npx eslint` 사용 금지. 반드시 `pnpm lint [targets..]`등의 스크립트 사용
+- `sed` 사용 금지. 너무 위험함.
 
 # 대화 규칙
 
 - 응답 전 항상 thinking 할 것.
 - 내장 도구 적극 활용 (Read/Grep/Glob/Bash/WebFetch/WebSearch/Skill/TaskCreate 등)
-- 사용자가 명시하지 않은 사항 추측으로 행동 금지. 추측한것이 맞는지 `AskUserQuestion` tool로 물어볼 것.
 - 사용자 요청의 의도가 불명확할 때는 `/sd-inner-clarify` 스킬을 호출하여 명확화.
 - 맥락에 맞는 용어 사용
   - 업무 기능·요구사항 논의 → 업무 용어 (사용자가 화면에서 뭘 하는지)
   - DB 스키마 설계 → 테이블·컬럼명
   - 코드 구현 → 함수·클래스명
 - 한국 개발 현장 통용 용어 사용
+- 사용자가 명시하지 않은 사항 추측으로 행동 금지. 추측한것이 맞는지 `AskUserQuestion` tool로 물어볼 것.
+  - 명시적 요청없이 다음 단계를 추측하여 바로 작업 하지 말것
+  - 명시적 요청없이 코드/문서등을 바로 수정하지 말것
+- 사용자가 직접 확인해야할 사항이 있으면, 계속 진행하지 말고 멈추고 사용자에게 직접 확인 결과를 요청할 것.
 
 # Playwright
 
 - 사용자가 접속주소를 알려주지 않았다면, 반드시 사용자에게 접속주소를 요청할것. (서버 강제 실행 금지)
 - /playwright-cli 스킬을 사용할 것
 
-# 사용법 참조
-
-- 프론트엔드: `.claude/references/sd-frontend-design.md`
-- `@angular/*`: `angular-cli` mcp를 활용
-- `@simplysm/*`: 해당 패키지의 `README.md`
-
 # 코딩 룰
 
+- 프론트엔드: `.claude/references/sd-frontend-design.md`
 - barrel export 금지: `src/` 루트의 `index.ts`외, 하위 폴더 re-export `index.ts` 금지
 - 다른 패키지에 대한 re-export 금지
 - 정적 import가 불가능한 경우를 제외하고 `import()` 사용 금지
@@ -41,4 +40,5 @@
 
 ## 주의사항
 
-- 프로젝트 루트 외부 파일 생성/수정/삭제 금지
+- 세션내 작업 수행중 사용자가 특정 부분 코드를 수정했을 수 있음. 임의로 롤백하지 말것
+  - 알고있던 정보와 상이한 코드 정보가 있다면, 사용자에게 보고후 확인을 받을 것.

package/claude/rules/sd-simplysm-v14.md

@@ -0,0 +1,33 @@
+# @simplysm/* 라이브러리 문서 인덱스
+
+## 필수 규칙
+
+`@simplysm/*`를 import하는 파일을 신규 작성하거나 수정할 때,
+작업 전 해당 패키지의 README.md를 반드시 Read 도구로 읽어야 한다.
+문서에 API 시그니처, 사용 예시, anti-pattern, 제약사항이 포함되어 있다.
+
+- "간단한 수정"이라도 예외 없음
+- 읽지 않고 수정하면 규칙 위반
+
+## 패키지 목록
+
+| 패키지 | 문서 경로 | 설명 |
+|--------|-----------|------|
+| `@simplysm/angular` | `.claude/references/sd-simplysm-v14/angular/README.md` | Angular 21 UI 컴포넌트, 디렉티브, 프로바이더, 레시피 |
+| `@simplysm/core-common` | `.claude/references/sd-simplysm-v14/core-common/README.md` | 플랫폼 중립 유틸리티 (DateTime, UUID, EventEmitter 등) |
+| `@simplysm/core-browser` | `.claude/references/sd-simplysm-v14/core-browser/README.md` | 브라우저 전용 유틸리티 |
+| `@simplysm/core-node` | `.claude/references/sd-simplysm-v14/core-node/README.md` | Node.js 유틸리티 (Fsx, Cpx, FsWatcher 등) |
+| `@simplysm/service-server` | `.claude/references/sd-simplysm-v14/service-server/README.md` | Fastify 기반 서비스 서버 |
+| `@simplysm/service-client` | `.claude/references/sd-simplysm-v14/service-client/README.md` | 서비스 클라이언트 (WebSocket/HTTP) |
+| `@simplysm/service-common` | `.claude/references/sd-simplysm-v14/service-common/README.md` | 서버-클라이언트 공유 프로토콜, 타입 |
+| `@simplysm/orm-node` | `.claude/references/sd-simplysm-v14/orm-node/README.md` | Node.js ORM (MSSQL, MySQL, PostgreSQL) |
+| `@simplysm/orm-common` | `.claude/references/sd-simplysm-v14/orm-common/README.md` | ORM 공통 쿼리빌더, 스키마, 타입 |
+| `@simplysm/excel` | `.claude/references/sd-simplysm-v14/excel/README.md` | 엑셀 파일 읽기/쓰기 |
+| `@simplysm/storage` | `.claude/references/sd-simplysm-v14/storage/README.md` | FTP/SFTP 스토리지 클라이언트 |
+| `@simplysm/sd-cli` | `.claude/references/sd-simplysm-v14/sd-cli/README.md` | 빌드/체크 CLI 도구 |
+| `@simplysm/sd-claude` | `.claude/references/sd-simplysm-v14/sd-claude/README.md` | Claude Code 에셋 동기화 |
+| `@simplysm/lint` | `.claude/references/sd-simplysm-v14/lint/README.md` | ESLint 공유 설정 |
+| `@simplysm/capacitor-plugin-auto-update` | `.claude/references/sd-simplysm-v14/capacitor-plugin-auto-update/README.md` | Capacitor 자동 업데이트 플러그인 |
+| `@simplysm/capacitor-plugin-file-system` | `.claude/references/sd-simplysm-v14/capacitor-plugin-file-system/README.md` | Capacitor 파일 시스템 플러그인 |
+| `@simplysm/capacitor-plugin-intent` | `.claude/references/sd-simplysm-v14/capacitor-plugin-intent/README.md` | Capacitor Intent 플러그인 |
+| `@simplysm/capacitor-plugin-usb-storage` | `.claude/references/sd-simplysm-v14/capacitor-plugin-usb-storage/README.md` | Capacitor USB 스토리지 플러그인 |

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

@@ -6,12 +6,17 @@ effort: low
 
 # sd-claude-docs: CLAUDE.md + README.md/docs 통합 생성
 
-프로젝트를 분석하여 **CLAUDE.md**(모노레포 내부 개발자용 컨텍스트)와 **README.md + docs/**(패키지 소비자용 API 문서)를 한 번에 생성·갱신한다. 설정 파일·스크립트·소스 코드에서 검증 가능한 사실만 추출하며, 기존 문서는 섹션 단위로 병합한다.
+프로젝트를 분석하여 **CLAUDE.md**(모노레포 내부 개발자용 컨텍스트)와 **소비자 문서(README.md + _api-index.md + Entry 파일)**를 한 번에 생성·갱신한다. 설정 파일·스크립트·소스 코드에서 검증 가능한 사실만 추출하며, 기존 문서는 섹션 단위로 병합한다.
 
-- **라이브러리 프로젝트** (`private: true`가 아닌 패키지 1개 이상 존재): CLAUDE.md + 각 패키지 `README.md` (+ 분량 조건에 해당 시 `docs/{category}/{entry}.md` 트리)
+- **라이브러리 프로젝트** (`private: true`가 아닌 패키지 1개 이상 존재): CLAUDE.md + 각 패키지 소비자 문서
 - **소비앱** (모든 패키지가 `private: true`): CLAUDE.md만 생성
 
-**두 문서의 독립성.** CLAUDE.md는 **모노레포 내부 개발자(LLM 포함)**용, README.md + docs/는 **패키지 소비자**용이다. 대상·관점이 달라 중복되지 않는다. README.md + docs/는 **wiki 스타일**로 구성한다 — 각 export된 class/component(Entry)는 자체 md 파일로 분리되어, 소비자(특히 LLM)가 필요한 Entry 하나만 조회할 수 있게 한다. README.md는 인덱스, 상세는 각 Entry 파일에 둔다.
+**두 문서의 독립성.** CLAUDE.md는 **모노레포 내부 개발자(LLM 포함)**용, 소비자 문서는 **패키지 소비자**용이다. 대상·관점이 달라 중복되지 않는다.
+
+**작업 기반 발견성.** 소비자 문서는 **작업 라우터 구조**로 구성한다:
+- **README.md** = 작업 라우터 ("하려는 작업 → 읽을 파일" 매핑에 전념. API 목록은 두지 않는다)
+- **_api-index.md** = API 참조 인덱스 (API 이름을 이미 알 때 문서를 찾는 보조 파일)
+- **{category}/{entry}.md** = Entry 상세 (각 Entry 상단에 "읽어야 하는 상황" 필수)
 
 ## 사용법
 
@@ -36,15 +41,23 @@ effort: low
 
 ### 출력 경로 규칙
 
-라이브러리 프로젝트에서 패키지 소비자용 문서는 **해당 패키지 루트**에 위치한다.
+| 구분 | CLAUDE.md | README.md | _api-index.md | Entry 파일 |
+|------|-----------|-----------|---------------|------------|
+| 모노레포 (각 패키지) | `{패키지 경로}/CLAUDE.md` | `{문서 루트}/{패키지명}/README.md` | `{문서 루트}/{패키지명}/_api-index.md` | `{문서 루트}/{패키지명}/{category}/{entry}.md` |
+| 모노레포 루트 | `./CLAUDE.md` | — | — | — |
+| 단일 패키지 (루트=패키지) | `./CLAUDE.md` | `./README.md` | `./_api-index.md` | `./{category}/{entry}.md` |
+
+`private: true` 패키지는 README.md / Entry 파일을 생성하지 않는다 (CLAUDE.md만).
+
+#### `{문서 루트}` 결정
 
-| 구분 | CLAUDE.md | README.md | docs/ |
-|------|-----------|-----------|-------|
-| 모노레포 (각 패키지) | `{패키지 경로}/CLAUDE.md` | `{패키지 경로}/README.md` | `{패키지 경로}/docs/{category}/{entry}.md` |
-| 모노레포 루트 | `./CLAUDE.md` | — | — |
-| 단일 패키지 (루트=패키지) | `./CLAUDE.md` | `./README.md` | `./docs/{category}/{entry}.md` |
+루트 `package.json`의 `version` 필드에서 메이저 버전을 추출하여 `{문서 루트}`를 결정한다.
+
+```
+version: "14.0.51" → 메이저 버전: 14 → {문서 루트}: .claude/references/sd-simplysm-v14
+```
 
-`private: true` 패키지는 README.md / docs/를 생성하지 않는다 (CLAUDE.md만).
+모노레포에서 `{패키지명}`은 패키지 디렉토리명이다 (예: `packages/angular` → `angular`). README.md 내부의 Entry 파일 링크는 상대 경로를 사용한다 (예: `[SdThemeProvider](./providers/sd-theme-provider.md)`).
 
 ## Step 1: 사전 분석
 
@@ -107,10 +120,11 @@ effort: low
 
 subagent가 개별 파일을 하나씩 Read하는 대신 병합 파일 1회 Read로 전체 소스를 파악할 수 있게 한다. 컨텍스트 소비를 대폭 줄이는 핵심 단계이다.
 
-각 패키지에 대해 Bash로 실행 (여러 패키지면 병렬):
+타임스탬프 변수를 생성한 뒤, 각 패키지에 대해 Bash로 실행 (여러 패키지면 병렬):
 
 ```bash
-bash .claude/skills/sd-claude-docs/merge-source.sh {패키지경로} ./tmp/{패키지명}-source.txt
+TS=$(date +%y%m%d%H%M%S)
+bash .claude/skills/sd-claude-docs/merge-source.sh {패키지경로} ./.tmp/docs/$TS/{패키지명}-source.txt
 ```
 
 ### 3-2. subagent 병렬 실행
@@ -120,26 +134,29 @@ bash .claude/skills/sd-claude-docs/merge-source.sh {패키지경로} ./tmp/{패
 #### subagent 프롬프트
 
 ```
-{패키지 경로}의 CLAUDE.md와 README.md/docs를 생성·갱신한다.
+{패키지 경로}의 CLAUDE.md와 소비자 문서를 생성·갱신한다.
 
 `.claude/skills/sd-claude-docs/references/package-docs.md`를 읽고 그 지침을 따른다.
 
 전달 사항:
 - 패키지 경로: {패키지 경로}
-- 소스 병합 파일: {./tmp/{패키지명}-source.txt의 절대 경로}
+- 패키지명: {패키지 디렉토리명}
+- 문서 루트: {문서 루트}
+- 소비자 문서 출력 경로: `{문서 루트}/{패키지명}/`
+- 소스 병합 파일: {./.tmp/docs/$TS/{패키지명}-source.txt의 절대 경로}
 - 루트 수준 설정 (이 내용과 중복되는 정보는 패키지 CLAUDE.md에 반복하지 않는다):
   {Step 1에서 추출한 코딩 규칙·컴파일러 설정 목록}
 ```
 
-각 subagent는 소스 병합 파일을 한 번 Read하여 CLAUDE.md(Key Patterns)와 README.md/docs(API 문서) 모두에 활용한다.
+각 subagent는 소스 병합 파일을 한 번 Read하여 CLAUDE.md(Key Patterns)와 소비자 문서(API 문서) 모두에 활용한다.
 
 ### subagent 반환 정보
 
 - 패키지 경로
 - CLAUDE.md 생성/갱신/건너뜀 여부
-- README.md 생성/갱신/건너뜀 여부 + 구조 (README 단독 / README + docs 트리)
+- 소비자 문서 생성/갱신/건너뜀 여부 + 구조 (README 단독 / README + _api-index + Entry 트리)
 - Entry 수 / 총 API 항목 수
-- 생성된 파일 목록
+- 생성된 파일 목록 (_api-index.md 포함)
 
 ## Step 4: 루트 CLAUDE.md 생성
 
@@ -210,20 +227,20 @@ UI:       angular (Angular)
 ```markdown
 ## sd-claude-docs 결과
 
-| 패키지 | CLAUDE.md | README.md | 구조 | Entry / API |
-|--------|-----------|-----------|------|-------------|
+| 패키지 | CLAUDE.md | 소비자 문서 | 구조 | Entry / API |
+|--------|-----------|-------------|------|-------------|
 | root | 생성 | — | — | — |
 | @simplysm/core-common | 갱신 | 갱신 | README 단독 | 8 / 35 |
-| @simplysm/angular | 갱신 | 갱신 | README + docs 트리 | 72 / 126 |
+| @simplysm/angular | 갱신 | 갱신 | README + _api-index + Entry 트리 | 72 / 126 |
 | @simplysm/internal | 생성 | — (private) | — | — |
 
 ### 생성된 파일 목록
 - CLAUDE.md (root)
 - packages/core-common/CLAUDE.md
-- packages/core-common/README.md
-- packages/core-common/docs/utils/string-utils.md
+- {문서 루트}/core-common/README.md
 - packages/angular/CLAUDE.md
-- packages/angular/README.md
-- packages/angular/docs/{category}/{entry}.md …
+- {문서 루트}/angular/README.md
+- {문서 루트}/angular/_api-index.md
+- {문서 루트}/angular/{category}/{entry}.md …
 - ...
 ```