democut 0.2.0 → 0.3.0

package/README.md

@@ -117,53 +117,82 @@ npm test
 npm run build      # dist/cli.js (bin: democut) 번들
 ```
 
+## MCP 서버 (에이전트에 도구로 붙이기)
+
+`democut mcp` 는 **stdio MCP 서버**다. Claude Code·Cursor 등 MCP 클라이언트에 붙이면
+에이전트가 도구로 직접 영상을 만든다.
+
+```bash
+claude mcp add democut -- democut mcp
+```
+
+노출 도구 4개:
+
+| 도구 | 부작용 |
+|---|---|
+| `democut_auth_status` | 없음 — 로그인·워크스페이스·티어 확인 |
+| `democut_estimate_video_cost` | **없음** — 비용만 계산 |
+| `democut_generate_video` | **과금** — `confirmed_cost_usd` 필수 |
+| `democut_get_video_status` | 없음 — 상태 조회 + 선택적 저장 |
+
+### 비용 승인이 프로토콜에 맞게 바뀐다
+
+CLI 는 TTY 에 `y/N` 을 물어 사람을 막지만 MCP 에는 물어볼 화면이 없다. 대신 두 겹이다:
+
+1. **호스트의 도구 승인** — Claude Code 등이 도구 호출 전에 사용자에게 확인을 받는다.
+   우리가 제어할 수 없으므로 이것만 믿지 않는다.
+2. **`confirmed_cost_usd` 재확인** — 생성 도구는 호출자가 *직접 본* 추정 금액을 다시 실어
+   보내야 하고, 서버가 방금 계산한 값과 대조해 어긋나면 거부한다. 모델이 추정을 건너뛰고
+   바로 생성하는 것을 막고, 사람에게 보여준 금액과 실제 청구액이 갈라지지 않게 한다.
+
+### 왜 원격 HTTP 가 아니라 stdio 인가
+
+원격 MCP 서버로 만들면 클라이언트가 OAuth 2.1 discovery(RFC 9728 + RFC 8414 + PKCE +
+동적 클라이언트 등록)를 요구한다. 우리가 가진 것은 device flow(RFC 8628)라 그 체인을 새로
+쌓아야 하고, 정적 Bearer 를 클라이언트 설정에 박는 우회는 **access token 이 1시간이면
+만료**돼 곧 깨진다.
+
+stdio 는 그 문제가 통째로 사라진다 — 이 프로세스가 이미 `~/.democut/credentials.json` 을
+읽고 만료 시 refresh 로 회전한다. **클라이언트 설정에 토큰이 남지 않고**, 서버에 새 인증
+표면을 만들지 않으며, CLI 가 이미 검증해 둔 경로를 그대로 쓴다.
+
+원격 HTTP 는 로컬 바이너리를 못 돌리는 클라이언트를 위해 나중에 별도로 얹는다.
+
 ## 게시 (npm publish)
 
-**아직 게시되지 않았다** — `npm install -g democut` 은 현재 404 다.
-게시는 사람이 한다(에이전트 범위 밖).
-
-> ⚠️ **게시가 문서 승격보다 먼저다.** `democut` 은 **무스코프**라 우리가 게시하기 전까지
-> **누구나 그 이름으로 올릴 수 있다**(스코프 패키지와 달리 네임스페이스 보호가 없다).
-> `/docs/agents` 의 복사 버튼과 `/updates` 공지가 먼저 나가면, 그 사이 제3자가 악성
-> `democut` 을 선점해 사용자가 그것을 설치하는 창이 열린다 —
-> `democut auth login` 이 워크스페이스 토큰을 다루므로 토큰 탈취로 이어질 수 있다
-> (CWE-829, faceta 리뷰 2026-08-21).
->
-> 따라서 **머지 → npm publish → 승격(promote)** 순서를 지킨다. 승격 전에 확인:
-> ```bash
-> curl -s -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/democut   # 200 이어야 한다
-> ```
-
-순서:
-
-1. **서버 라우터가 프로덕션에 있어야 한다.** `democut video` 는 `/api/videogen` 을 호출하고
-   기본 base URL 이 프로덕션(`https://democut.ai`)이다. 그 라우터가 없으면 게시해도 모든
-   video 커맨드가 404 다. 확인:
-   ```bash
-   curl -s -o /dev/null -w '%{http_code}\n' -X POST https://democut.ai/api/videogen/estimate
-   # 401 이면 배포됨(인증 필요) · 404 면 미승격
-   ```
-2. **org 는 필요 없다.** 이 패키지는 **무스코프**(`democut`)라 개인 계정으로 바로 게시되고,
-   무스코프는 기본이 public 이라 `--access public` 도 필요 없다.
+**CI 가 자동으로 한다.** 사람이 순서를 기억할 필요가 없다.
 
-   > `@democut` **스코프**는 쓸 수 없다 — 그 이름은 이미 npm 계정 하나가 점유하고 있고
-   > (username 과 org 는 같은 네임스페이스다) 그래서 `democut` org 를 만들 수 없다.
-   > **패키지 이름은 그와 별개 네임스페이스**라 무스코프 `democut` 은 그대로 쓸 수 있다.
-   > 향후 `@democut/mcp` 같은 스코프 패키지가 필요해지면 그 계정을 되찾아야 한다
-   > (이메일을 못 받는 미인증 계정이면 로그인 후 계정 설정에서 이메일을 교체하거나,
-   > 비밀번호를 모르면 npm Support 로 문의).
+```
+promote(사람이 누르는 버튼)  →  npm-publish-cli  →  deploy-dgx
+```
 
-3. `npm login` 후:
-   ```bash
-   cd cli
-   npm run build          # prepublishOnly 가 자동으로도 돌지만 먼저 확인
-   npm publish            # 무스코프는 기본 public — --access 불필요
-   ```
+`deploy-dgx` 가 게시 성공을 `needs` 로 요구하므로, **게시가 실패하면 문서가 프로덕션에
+나가지 않는다.** `/docs/agents` 가 아직 없는 패키지를 안내하는 창이 구조적으로 열리지 않는다
+(무스코프 이름이라 그 창에서 제3자가 선점하면 토큰 탈취로 이어질 수 있다 — CWE-829).
+
+버전이 그대로면 잡은 "이미 게시됨" 으로 즉시 통과한다. 그러니 **게시하려면 `cli/package.json`
+의 version 을 올리기만 하면 된다** — `VERSION` ↔ `package.json` 정합은 테스트가 강제하므로
+`src/version.ts` 도 같이 올린다.
 
-> **토큰을 코드나 대화에 넣지 않는다.** `npm login` 은 브라우저 인증이고 토큰은 `~/.npmrc`
-> 에만 남는다. CI 에서 자동 게시가 필요해지면 npm **Automation token**(publish 전용,
-> 이 패키지로 스코프 제한)을 발급해 **GitLab CI/CD 변수**(masked + protected)에 두고
-> `NODE_AUTH_TOKEN` 으로 주입한다 — 이 레포가 배포 시크릿에 쓰는 방식과 같다.
+순서를 강제하는 것은 `.gitlab-ci.yml` 의 `deploy-dgx.needs` 하나뿐이고, 그것이 지워지면
+아무 신호 없이 보장이 사라진다 — `scripts/tests/promote.sh` 가 지킨다(`make test-scripts`).
+
+### 선행 설정 (1회)
+
+npm **Automation token** 을 발급해(2FA 를 우회하도록 설계된 종류다) GitLab CI/CD 변수
+`NPM_TOKEN` 에 **masked + protected** 로 넣는다. 토큰이 없으면 잡이 명확한 메시지로 실패한다.
+
+> **토큰을 코드나 대화에 넣지 않는다.** 값은 GitLab 변수에만 두고, 레포에도 로컬 파일에도
+> 남기지 않는다.
+
+### 수동 게시 (긴급시)
+
+```bash
+cd cli
+npm run build
+npm publish        # 무스코프는 기본 public — --access 불필요
+```
 
-게시되는 것은 `files` 에 적힌 **`dist/` 뿐**이다(소스·테스트는 포함되지 않는다).
+2FA 가 보안 키(WebAuthn)면 `npm publish` 가 브라우저 승인 URL 을 띄운다.
+게시되는 것은 `files` 에 적힌 **`dist/` 뿐**이다(소스·테스트 미포함).
 `npm pack --dry-run` 으로 목록을 먼저 확인할 수 있다.