@spacebar_ai/moldclaw-core 2026.3.14 → 2026.3.16

package/docs/pipeline-sdk/CLI_SPEC.md

@@ -0,0 +1,609 @@
+# moldClaw Pipeline CLI 명령어 스펙
+
+> **Version**: 1.0.0-draft  
+> **Date**: 2026-03-20
+
+---
+
+## 개요
+
+`moldclaw pipeline` CLI는 파이프라인 개발, 테스트, 배포를 위한 통합 도구이다.
+
+```
+moldclaw pipeline <command> [options]
+```
+
+---
+
+## 명령어 상세
+
+### 1. `moldclaw pipeline init`
+
+새 파이프라인 프로젝트를 생성한다.
+
+#### 사용법
+
+```bash
+moldclaw pipeline init [name] [options]
+```
+
+#### 옵션
+
+| 옵션                     | 단축   | 설명                        | 기본값     |
+| ------------------------ | ------ | --------------------------- | ---------- |
+| `--template <name>`      | `-t`   | 템플릿 선택                 | `blank`    |
+| `--directory <dir>`      | `-d`   | 생성 디렉토리               | `./<name>` |
+| `--typescript`           |        | TypeScript 사용             | `true`     |
+| `--javascript`           | `-js`  | JavaScript 사용             | `false`    |
+| `--package-manager <pm>` | `--pm` | 패키지 매니저               | `npm`      |
+| `--git`                  |        | Git 초기화                  | `true`     |
+| `--no-git`               |        | Git 초기화 안 함            |            |
+| `--yes`                  | `-y`   | 모든 프롬프트에 기본값 사용 | `false`    |
+
+#### 템플릿 목록
+
+| 템플릿            | 설명                          |
+| ----------------- | ----------------------------- |
+| `blank`           | 빈 템플릿 (최소 구조)         |
+| `simple`          | 단순 선형 파이프라인          |
+| `parallel`        | 병렬 처리 예제                |
+| `interactive`     | UI 상호작용 (하드 파이프라인) |
+| `api-integration` | 외부 API 연동 예제            |
+| `data-processor`  | 데이터 처리 스타터            |
+| `chatbot`         | 대화형 AI 스타터              |
+| `video-editor`    | 비디오 편집 스타터            |
+
+#### 예시
+
+```bash
+# 대화형 모드
+moldclaw pipeline init
+
+# 이름 지정
+moldclaw pipeline init my-pipeline
+
+# 템플릿 사용
+moldclaw pipeline init my-pipeline --template video-editor
+
+# JavaScript + pnpm
+moldclaw pipeline init my-pipeline -js --pm pnpm
+
+# 비대화형 모드
+moldclaw pipeline init my-pipeline -y -t simple
+```
+
+#### 대화형 프롬프트
+
+```
+? 파이프라인 이름: my-awesome-pipeline
+? 설명: An awesome pipeline for doing awesome things
+? 카테고리: productivity
+? 템플릿: blank
+? TypeScript 사용? Yes
+? Git 초기화? Yes
+? 패키지 매니저: npm
+
+📁 Creating pipeline project...
+  ✔ Created package.json
+  ✔ Created moldclaw.pipeline.json
+  ✔ Created src/index.ts
+  ✔ Created tsconfig.json
+  ✔ Initialized git repository
+
+✅ Pipeline project created!
+
+Next steps:
+  cd my-awesome-pipeline
+  npm install
+  moldclaw pipeline dev
+```
+
+---
+
+### 2. `moldclaw pipeline dev`
+
+개발 모드로 파이프라인을 실행한다. 파일 변경 시 자동 재시작.
+
+#### 사용법
+
+```bash
+moldclaw pipeline dev [options]
+```
+
+#### 옵션
+
+| 옵션              | 단축 | 설명                 | 기본값  |
+| ----------------- | ---- | -------------------- | ------- |
+| `--port <port>`   | `-p` | 개발 서버 포트       | `4321`  |
+| `--no-hot-reload` |      | 핫 리로드 비활성화   |         |
+| `--mock-apis`     | `-m` | API 목업 모드        | `false` |
+| `--input <file>`  | `-i` | 입력 파일/JSON       |         |
+| `--config <file>` | `-c` | 설정 오버라이드 파일 |         |
+| `--debug`         |      | 디버그 모드          | `false` |
+| `--open`          | `-o` | 브라우저 자동 열기   | `false` |
+
+#### 예시
+
+```bash
+# 기본 실행
+moldclaw pipeline dev
+
+# 입력 데이터와 함께
+moldclaw pipeline dev --input ./test-data.json
+
+# 목업 API 모드
+moldclaw pipeline dev --mock-apis
+
+# 디버그 모드
+moldclaw pipeline dev --debug
+```
+
+#### 개발 서버 기능
+
+1. **핫 리로드**: 소스 파일 변경 시 자동 재시작
+2. **API 목업**: `--mock-apis` 플래그로 외부 API 대신 목업 사용
+3. **디버그 UI**: `http://localhost:4321` 에서 파이프라인 상태 확인
+4. **스텝별 실행**: 개별 스텝만 테스트 가능
+5. **상태 검사**: 각 스텝의 입/출력 데이터 확인
+
+---
+
+### 3. `moldclaw pipeline test`
+
+파이프라인 테스트를 실행한다.
+
+#### 사용법
+
+```bash
+moldclaw pipeline test [options]
+```
+
+#### 옵션
+
+| 옵션                 | 단축 | 설명                       | 기본값  |
+| -------------------- | ---- | -------------------------- | ------- |
+| `--watch`            | `-w` | 파일 변경 감지 모드        | `false` |
+| `--coverage`         |      | 커버리지 리포트            | `false` |
+| `--filter <pattern>` | `-f` | 테스트 필터                |         |
+| `--timeout <ms>`     | `-t` | 타임아웃                   | `30000` |
+| `--parallel`         |      | 병렬 실행                  | `true`  |
+| `--snapshot`         | `-s` | 스냅샷 테스트              | `false` |
+| `--update-snapshots` | `-u` | 스냅샷 업데이트            | `false` |
+| `--ci`               |      | CI 모드 (컬러 비활성화 등) | `false` |
+
+#### 예시
+
+```bash
+# 모든 테스트 실행
+moldclaw pipeline test
+
+# 워치 모드
+moldclaw pipeline test --watch
+
+# 특정 테스트만
+moldclaw pipeline test --filter "analyze step"
+
+# 커버리지 포함
+moldclaw pipeline test --coverage
+
+# CI 환경
+moldclaw pipeline test --ci --coverage
+```
+
+#### 테스트 파일 구조
+
+```
+tests/
+├── pipeline.test.ts          # 전체 파이프라인 테스트
+├── steps/
+│   ├── analyze.test.ts       # 개별 스텝 테스트
+│   └── process.test.ts
+├── fixtures/
+│   ├── input.json            # 테스트 입력 데이터
+│   └── expected-output.json  # 기대 출력
+└── __snapshots__/            # 스냅샷 파일
+```
+
+#### 테스트 유틸리티
+
+```typescript
+import { createMockContext, createMockTools } from "@moldclaw/pipeline-sdk";
+
+describe("analyze step", () => {
+  it("should process input correctly", async () => {
+    const ctx = createMockContext({
+      input: { data: "test" },
+      config: { format: "json" },
+    });
+
+    const result = await analyzeStep.handler(ctx);
+
+    expect(result).toMatchSnapshot();
+  });
+});
+```
+
+---
+
+### 4. `moldclaw pipeline build`
+
+프로덕션 빌드를 생성한다.
+
+#### 사용법
+
+```bash
+moldclaw pipeline build [options]
+```
+
+#### 옵션
+
+| 옵션             | 단축 | 설명                       | 기본값   |
+| ---------------- | ---- | -------------------------- | -------- |
+| `--output <dir>` | `-o` | 출력 디렉토리              | `./dist` |
+| `--minify`       |      | 코드 압축                  | `true`   |
+| `--sourcemap`    |      | 소스맵 생성                | `true`   |
+| `--analyze`      | `-a` | 번들 분석                  | `false`  |
+| `--target <env>` |      | 타겟 환경                  | `node`   |
+| `--clean`        |      | 빌드 전 출력 디렉토리 정리 | `true`   |
+
+#### 타겟 환경
+
+- `node`: Node.js 환경 (기본값)
+- `browser`: 브라우저 환경 (UI 컴포넌트 포함 시)
+- `universal`: 양쪽 지원
+
+#### 예시
+
+```bash
+# 기본 빌드
+moldclaw pipeline build
+
+# 번들 분석 포함
+moldclaw pipeline build --analyze
+
+# 소스맵 없이
+moldclaw pipeline build --no-sourcemap
+
+# 특정 출력 디렉토리
+moldclaw pipeline build -o ./build
+```
+
+#### 빌드 출력
+
+```
+dist/
+├── index.js              # 메인 번들
+├── index.js.map          # 소스맵
+├── index.d.ts            # 타입 정의
+├── ui/                   # UI 컴포넌트 (있는 경우)
+│   └── EditorCanvas.js
+└── manifest.json         # 파이프라인 메타데이터
+```
+
+---
+
+### 5. `moldclaw pipeline publish`
+
+마켓플레이스에 파이프라인을 배포한다.
+
+#### 사용법
+
+```bash
+moldclaw pipeline publish [options]
+```
+
+#### 옵션
+
+| 옵션                 | 단축 | 설명                      | 기본값   |
+| -------------------- | ---- | ------------------------- | -------- |
+| `--tag <tag>`        |      | 버전 태그                 | `latest` |
+| `--dry-run`          |      | 실제 퍼블리시 없이 검증만 | `false`  |
+| `--access <level>`   |      | 접근 수준                 | `public` |
+| `--changelog <file>` |      | 변경 로그 파일            |          |
+| `--skip-build`       |      | 빌드 건너뛰기             | `false`  |
+| `--otp <code>`       |      | 2FA 코드                  |          |
+
+#### 접근 수준
+
+- `public`: 모든 사용자에게 공개
+- `unlisted`: 링크로만 접근 가능
+- `private`: 초대된 사용자만 접근
+
+#### 태그
+
+- `latest`: 안정 버전 (기본값)
+- `beta`: 베타 버전
+- `alpha`: 알파 버전
+- `canary`: 최신 개발 버전
+
+#### 예시
+
+```bash
+# 기본 퍼블리시
+moldclaw pipeline publish
+
+# 드라이런
+moldclaw pipeline publish --dry-run
+
+# 베타 릴리스
+moldclaw pipeline publish --tag beta
+
+# 비공개 퍼블리시
+moldclaw pipeline publish --access private
+
+# 변경 로그 포함
+moldclaw pipeline publish --changelog CHANGELOG.md
+```
+
+#### 퍼블리시 프로세스
+
+```
+$ moldclaw pipeline publish
+
+🔐 Authenticating...
+  ✔ Logged in as developer@example.com
+
+📦 Building pipeline...
+  ✔ TypeScript compilation
+  ✔ Bundle optimization
+  ✔ Asset processing
+
+🔍 Validating...
+  ✔ Package structure
+  ✔ Dependencies resolved
+  ✔ Security scan passed
+  ✔ API compatibility check
+  ✔ Metadata complete
+
+📋 Pipeline Summary:
+  ┌─────────────────────────────────────┐
+  │ Name: Video Auto Editor             │
+  │ Version: 1.0.0                      │
+  │ Category: media-production          │
+  │ Size: 245 KB                        │
+  │ Pricing: One-time ($29.99 USD)      │
+  │ Access: Public                      │
+  └─────────────────────────────────────┘
+
+? Confirm publish to moldClaw Marketplace? (Y/n) Y
+
+🚀 Publishing...
+  ⠋ Uploading package...
+  ✔ Package uploaded (245 KB)
+  ⠋ Processing...
+  ✔ Processing complete
+  ⠋ Generating preview...
+  ✔ Preview generated
+  ⠋ Indexing...
+  ✔ Indexed
+
+✅ Published successfully!
+   https://marketplace.moldclaw.com/pipelines/video-auto-editor
+
+📊 You can track downloads and reviews at:
+   https://marketplace.moldclaw.com/developer/pipelines/video-auto-editor
+```
+
+---
+
+### 6. `moldclaw pipeline run`
+
+파이프라인을 실행한다.
+
+#### 사용법
+
+```bash
+moldclaw pipeline run <pipeline-id> [options]
+```
+
+#### 옵션
+
+| 옵션              | 단축 | 설명                              | 기본값     |
+| ----------------- | ---- | --------------------------------- | ---------- |
+| `--input <data>`  | `-i` | 입력 데이터 (파일 경로 또는 JSON) |            |
+| `--config <file>` | `-c` | 설정 파일                         |            |
+| `--output <dir>`  | `-o` | 출력 디렉토리                     | `./output` |
+| `--dry-run`       |      | 시뮬레이션 모드                   | `false`    |
+| `--resume <id>`   |      | 체크포인트에서 재개               |            |
+| `--async`         | `-a` | 백그라운드 실행                   | `false`    |
+| `--notify`        | `-n` | 완료 시 알림                      | `false`    |
+| `--step <id>`     | `-s` | 특정 스텝부터 시작                |            |
+| `--until <id>`    |      | 특정 스텝까지만 실행              |            |
+
+#### 예시
+
+```bash
+# 기본 실행
+moldclaw pipeline run video-auto-editor --input ./video.mp4
+
+# JSON 입력
+moldclaw pipeline run data-processor --input '{"files": ["a.csv", "b.csv"]}'
+
+# 설정과 함께
+moldclaw pipeline run my-pipeline -i data.json -c config.json
+
+# 백그라운드 실행
+moldclaw pipeline run heavy-pipeline -i data.json --async --notify
+
+# 특정 스텝만
+moldclaw pipeline run my-pipeline --step process --until render
+
+# 체크포인트에서 재개
+moldclaw pipeline run my-pipeline --resume run_abc123
+```
+
+---
+
+### 7. `moldclaw pipeline list`
+
+설치된 파이프라인 목록을 표시한다.
+
+#### 사용법
+
+```bash
+moldclaw pipeline list [options]
+```
+
+#### 옵션
+
+| 옵션               | 단축 | 설명                 | 기본값  |
+| ------------------ | ---- | -------------------- | ------- |
+| `--json`           | `-j` | JSON 형식 출력       | `false` |
+| `--category <cat>` | `-c` | 카테고리 필터        |         |
+| `--outdated`       |      | 업데이트 가능한 것만 | `false` |
+
+#### 예시
+
+```bash
+# 전체 목록
+moldclaw pipeline list
+
+# JSON 출력
+moldclaw pipeline list --json
+
+# 특정 카테고리
+moldclaw pipeline list --category media-production
+
+# 업데이트 가능한 것만
+moldclaw pipeline list --outdated
+```
+
+---
+
+### 8. `moldclaw pipeline install`
+
+마켓플레이스에서 파이프라인을 설치한다.
+
+#### 사용법
+
+```bash
+moldclaw pipeline install <pipeline-id> [options]
+```
+
+#### 옵션
+
+| 옵션              | 단축 | 설명           | 기본값   |
+| ----------------- | ---- | -------------- | -------- |
+| `--version <ver>` | `-v` | 특정 버전 설치 | `latest` |
+| `--global`        | `-g` | 전역 설치      | `true`   |
+| `--local`         | `-l` | 로컬 설치      | `false`  |
+
+#### 예시
+
+```bash
+# 최신 버전 설치
+moldclaw pipeline install video-auto-editor
+
+# 특정 버전
+moldclaw pipeline install video-auto-editor@1.0.0
+
+# 로컬 설치
+moldclaw pipeline install video-auto-editor --local
+```
+
+---
+
+### 9. `moldclaw pipeline uninstall`
+
+설치된 파이프라인을 제거한다.
+
+```bash
+moldclaw pipeline uninstall <pipeline-id>
+```
+
+---
+
+### 10. `moldclaw pipeline update`
+
+파이프라인을 업데이트한다.
+
+#### 사용법
+
+```bash
+moldclaw pipeline update [pipeline-id] [options]
+```
+
+#### 옵션
+
+| 옵션        | 단축 | 설명                     | 기본값  |
+| ----------- | ---- | ------------------------ | ------- |
+| `--all`     | `-a` | 모든 파이프라인 업데이트 | `false` |
+| `--dry-run` |      | 변경 사항 미리보기       | `false` |
+
+---
+
+### 11. `moldclaw pipeline info`
+
+파이프라인 상세 정보를 표시한다.
+
+```bash
+moldclaw pipeline info <pipeline-id>
+```
+
+#### 출력 예시
+
+```
+📦 video-auto-editor
+   Version: 1.2.0
+   Author: moldClaw Team
+   Category: media-production
+   License: MIT
+
+📝 Description:
+   Automatically edit videos with AI-powered scene detection,
+   transcription, and smart cutting.
+
+📊 Stats:
+   Downloads: 1,234
+   Rating: 4.8 ★ (52 reviews)
+   Size: 245 KB
+
+📋 Dependencies:
+   APIs: meshy-ai, openai-whisper
+   Tools: ffmpeg, ffprobe
+
+💰 Pricing:
+   One-time purchase: $29.99 USD
+
+🔗 Links:
+   Marketplace: https://marketplace.moldclaw.com/pipelines/video-auto-editor
+   Repository: https://github.com/moldclaw/video-auto-editor
+```
+
+---
+
+## 글로벌 옵션
+
+모든 명령에서 사용 가능한 옵션:
+
+| 옵션         | 단축 | 설명          |
+| ------------ | ---- | ------------- |
+| `--help`     | `-h` | 도움말 표시   |
+| `--version`  | `-v` | 버전 표시     |
+| `--verbose`  |      | 상세 출력     |
+| `--quiet`    | `-q` | 최소 출력     |
+| `--no-color` |      | 컬러 비활성화 |
+
+---
+
+## 환경 변수
+
+| 변수                          | 설명                     |
+| ----------------------------- | ------------------------ |
+| `MOLDCLAW_PIPELINE_DIR`       | 파이프라인 설치 디렉토리 |
+| `MOLDCLAW_MARKETPLACE_TOKEN`  | 마켓플레이스 인증 토큰   |
+| `MOLDCLAW_PIPELINE_CACHE_DIR` | 캐시 디렉토리            |
+
+---
+
+## 종료 코드
+
+| 코드 | 의미                      |
+| ---- | ------------------------- |
+| `0`  | 성공                      |
+| `1`  | 일반 오류                 |
+| `2`  | 사용법 오류 (잘못된 인자) |
+| `3`  | 의존성 오류               |
+| `4`  | 인증 오류                 |
+| `5`  | 네트워크 오류             |
+| `6`  | 파이프라인 실행 오류      |