democut 0.4.0 → 0.5.0

package/README.md

@@ -7,11 +7,15 @@ DemoCut(democut) 에이전트 인증 CLI — OAuth2 **Device Flow**(RFC 8628). H
 ## 설치
 
 ```bash
-npm install -g democut      # 또는: npx democut auth login
+npm install -g democut               # 전역 설치 (선택)
+npx -y democut@latest auth login     # 설치 없이 바로 (@latest 필수 — 아래 MCP 절 참고)
 ```
 
 ## 사용
 
+아래 예시는 **전역 설치한 경우**다. npx 로 쓰고 있다면 `democut` 을
+`npx -y democut@latest` 로 바꿔 읽으면 된다.
+
 ```bash
 democut auth login      # device flow 로 로그인 → 토큰 저장
 democut auth status     # 현재 정체/워크스페이스/티어
@@ -123,23 +127,36 @@ npm run build      # dist/cli.js (bin: democut) 번들
 에이전트가 도구로 직접 영상을 만든다.
 
 ```bash
-claude mcp add democut -- npx -y democut mcp
+claude mcp add democut -- npx -y democut@latest mcp
 ```
 
-`npx -y` 를 붙이는 이유는 전역 설치가 **연결의 선행 조건이 되지 않게** 하기 위해서다.
+`npx` 를 쓰는 이유는 전역 설치가 **연결의 선행 조건이 되지 않게** 하기 위해서다.
 설치가 빠지면 등록은 성립하는데(등록은 바이너리 존재를 검사하지 않는다) 연결만 실패하고,
 그 실패는 클라이언트의 `Failed to reconnect …` 한 줄로만 드러난다 — 서버가 뜨지 못하므로
 진단을 낼 주체가 없다. 자격증명은 패키지가 아니라 `~/.democut/credentials.json` 에 있어
 실행 방식을 바꿔도 로그인 상태는 그대로다. 전역 설치는 선택이다.
 
-노출 도구 4개:
+★ **`@latest` 를 빼지 마라.** `-y` 는 설치 확인 프롬프트를 자동 승인할 뿐 **버전을 다시
+해석하지 않는다** — 태그를 빼면 `~/.npm/_npx` 캐시에 남은 옛 버전이 그대로 뜬다
+(2026-08-31 실측: 게시본이 0.4.0 인데 캐시는 0.3.0). 그 스큐가 실제로 사고를 냈다. 서버가
+`project_slug` 를 필수화한 뒤 게시본이 갱신되기까지 **2시간 45분** 동안 stdio 사용자의 영상
+생성이 전부 422 였고, 원격 HTTP 사용자는 아무 영향이 없었다. 대가로 실행할 때마다
+레지스트리를 한 번 보므로 npm 에 닿지 못하면 서버가 아예 뜨지 않는데, **조용히 옛 도구를
+쓰는 것보다 큰 소리로 안 뜨는 편이 낫다**(레지스트리가 막힌 사내망이면 아래 원격 HTTP 나
+전역 설치를 쓴다).
+
+노출 도구 8개 — 쓰기는 둘뿐이고 과금은 하나뿐이다:
 
 | 도구 | 부작용 |
 |---|---|
 | `democut_auth_status` | 없음 — 로그인·워크스페이스·티어 확인 |
-| `democut_estimate_video_cost` | **없음** — 비용만 계산 |
-| `democut_generate_video` | **과금** — `confirmed_cost_usd` 필수 |
+| `democut_estimate_video_cost` | 없음 — 비용만 계산 |
+| `democut_credit_balance` | 없음 — 크레딧 잔액 |
+| `democut_credit_ledger` | 없음 — 크레딧 사용 내역 |
+| `democut_list_projects` | 없음 — 프로젝트 목록(최근 수정순) |
 | `democut_get_video_status` | 없음 — 상태 조회 + 선택적 저장 |
+| `democut_create_project` | **쓰기**(과금 없음) — 같은 제목이면 기존 것을 돌려준다 |
+| `democut_generate_video` | **과금** — `confirmed_cost_usd` 필수 |
 
 ### 비용 승인이 프로토콜에 맞게 바뀐다
 
@@ -151,23 +168,47 @@ CLI 는 TTY 에 `y/N` 을 물어 사람을 막지만 MCP 에는 물어볼 화면
    보내야 하고, 서버가 방금 계산한 값과 대조해 어긋나면 거부한다. 모델이 추정을 건너뛰고
    바로 생성하는 것을 막고, 사람에게 보여준 금액과 실제 청구액이 갈라지지 않게 한다.
 
-### stdio 와 원격 HTTP — 대체가 아니라 병존
+### stdio 와 원격 HTTP — 어느 쪽을 언제 쓰나
 
-**stdio(이 CLI)가 기본이다.** 이 프로세스가 `~/.democut/credentials.json` 을 읽고 만료 시
-refresh 로 회전하므로 **클라이언트 설정 파일에 토큰이 남지 않는다.** 그 장점은 원격이
-생겨도 사라지지 않는다.
+둘은 **대체가 아니라 병존**이고, 도구 이름·인자도 같다. 고르는 기준은 취향이 아니라
+**클라이언트가 도는 자리**다.
 
-**원격 HTTP 도 이미 있다** — `https://democut.ai/mcp` (2026-08-25 배포). 로컬 바이너리를 못
-띄우는 클라이언트용이다:
+| | 사람이 쓰는 클라이언트<br>(노트북의 Claude Code·Cursor…) | 헤드리스·자동화 호스트<br>(게이트웨이·CI·서버 박스) |
+|---|---|---|
+| **권장** | **원격 HTTP** | **stdio (이 CLI)** |
+| 로그인 | 붙는 순간 브라우저가 열려 끝난다 | `democut auth login --no-browser` 1회 (device flow, RFC 8628) |
+| 브라우저 없는 자리 | **불가** — 비대화형에서는 OAuth 흐름이 안 돈다 | **가능** — 코드를 다른 기기에서 승인 |
+| 사전 준비 | 아래 두 옵션을 그대로 복사 | 없음 — redirect URI 등록도 브라우저도 불필요 |
+| 버전 스큐 | **없다** — 띄울 로컬 바이너리가 없다 | `@latest` 로 막는다(위 참고) |
+| 산출물 | 만료되는 링크로만 받는다 | `--output` 으로 디스크에 저장된다 |
+
+헤드리스에서 갈리는 것은 편의가 아니라 **가능/불가능**이다. 원격 HTTP 의 OAuth 는 호스트가
+브라우저를 띄워야 시작되는데, Claude Code 문서가 비대화형에서는 그 흐름을 돌릴 수 없다고
+명시한다 — *"In non-interactive mode there's no `/mcp` panel, so Claude Code can't run the
+OAuth flow for you."* 사람이 대화형 세션에서 **미리** 인증해 두는 것(`claude mcp login`)이
+유일한 우회다. 거기에 Clerk 이 loopback redirect 의 포트를 정확 일치로 요구하므로 그 호스트가
+쓸 포트의 redirect URI 도 OAuth 애플리케이션에 미리 등록해야 한다.
+
+stdio 는 device flow(RFC 8628)라 redirect URI 자체가 없고, `--no-browser` 가 코드와 URL 을
+출력하면 사람이 **다른 기기에서** 승인한다 — 그래서 브라우저가 없는 자리에서도 성립한다.
 
 ```bash
-claude mcp add --transport http --client-id <client_id> --callback-port <포트> \
+claude mcp add --transport http --client-id 7ovjLP6E85qLNAyq --callback-port 33418 \
     democut https://democut.ai/mcp
 ```
 
-`--client-id` 와 `--callback-port` 가 필요한 이유는 서버 쪽 설계에서 온다 — 동적 클라이언트
-등록(DCR)을 **일부러 꺼 두고**, Clerk 이 loopback redirect 의 포트를 정확 일치로 요구하기
-때문이다. 근거는 `apps/api/app/mcp/auth.py` docstring 이 SSOT.
+두 옵션은 **생략할 수 없고 임의로 바꿀 수도 없다.** `--client-id` 는 이 서버가 아무
+클라이언트나 받지 않기 때문이고(동적 클라이언트 등록(DCR)을 **일부러 꺼 두었다** —
+켜면 아무나 등록해 통과하는 confused-deputy 표면이 열린다), `--callback-port` 는 그 포트의
+redirect URI 가 사전 등록돼 있어야 하기 때문이다. 미등록이면 Clerk 이 400
+`redirect_uri … does not match … pre-registered redirect urls` 로 거부한다. 위 두 값은
+공개값이고 웹 문서(<https://democut.ai/docs/agents>)가 같은 쌍을 안내한다. 설계 근거의
+SSOT 는 `apps/api/app/mcp/auth.py` docstring.
+
+> ⚠️ **"클라이언트 설정 파일에 토큰이 남지 않는다" 는 stdio 의 고유 장점이 아니다.**
+> 이 문서가 한동안 그렇게 적고 있었는데 **사실이 아니다** — 원격 HTTP 등록도 설정에는
+> 공개값 둘(`clientId`·`callbackPort`)만 남고 액세스 토큰은 호스트의 자격증명 저장소에
+> 있다(2026-08-31 실측). 두 전송이 같으므로 선택 근거가 되지 못한다. 위 표의 기준으로 골라라.
 
 > ⚠️ 이 문단은 원래 "원격은 동적 클라이언트 등록을 요구해서 체인을 새로 쌓아야 한다" 고
 > 적혀 있었는데 **틀렸다.** DCR 은 MCP 명세에서 MUST 가 아니라 SHOULD 이고, 무엇보다 우리

package/dist/cli.js

@@ -16313,7 +16313,7 @@ var StdioServerTransport = class {
 };
 
 // src/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 
 // src/mcp/tools.ts
 import { existsSync as existsSync2 } from "fs";
@@ -16347,6 +16347,22 @@ var PROJECTS_MAX_LIMIT = 100;
 function list(baseUrl, deps = {}) {
   return apiRequest(baseUrl, "/api/projects", {}, deps);
 }
+function create(baseUrl, body, deps = {}) {
+  return apiRequest(baseUrl, "/api/projects", { method: "POST", body }, deps);
+}
+async function defaultVoiceId(baseUrl, deps = {}) {
+  const out3 = await apiRequest(
+    baseUrl,
+    "/api/projects/voices",
+    {},
+    deps
+  );
+  const id = out3.default_voice_id;
+  if (!id) {
+    throw new Error("\uC11C\uBC84\uAC00 \uAE30\uBCF8 \uC74C\uC131\uC744 \uC54C\uB824\uC8FC\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4 (default_voice_id \uC5C6\uC74C).");
+  }
+  return id;
+}
 
 // src/mcp/tools.ts
 var COST_TOLERANCE_USD = 5e-3;
@@ -16683,6 +16699,33 @@ function listProjects(a = {}, deps = {}) {
     return { text: lines.join("\n") };
   });
 }
+function createProject(a = {}, deps = {}) {
+  return guarded2(READ_ONLY, async () => {
+    const title = (a.title ?? "").trim();
+    if (!title) {
+      return {
+        isError: true,
+        text: "title \uC774 \uD544\uC694\uD569\uB2C8\uB2E4. \uC0AC\uC6A9\uC790\uAC00 \uC54C\uC544\uBCFC \uC218 \uC788\uB294 \uD504\uB85C\uC81D\uD2B8 \uC774\uB984\uC744 \uB123\uC5B4 \uB2E4\uC2DC \uD638\uCD9C\uD558\uC138\uC694."
+      };
+    }
+    const base = resolveBaseUrl(deps.baseUrl);
+    const voiceId = await defaultVoiceId(base, deps);
+    const p = await create(
+      base,
+      { title, voice_id: voiceId, external_ref: `mcp:project:${title}` },
+      deps
+    );
+    return {
+      text: [
+        `\uD504\uB85C\uC81D\uD2B8 \uC900\uBE44\uB428 \u2014 slug: ${p.slug}`,
+        `\uC81C\uBAA9: ${p.title}`,
+        "",
+        "democut_generate_video \uC758 project_slug \uC5D0 \uC704 slug \uB97C \uADF8\uB300\uB85C \uB123\uC73C\uC138\uC694.",
+        "\uAC19\uC740 \uC81C\uBAA9\uC73C\uB85C \uC774 \uB3C4\uAD6C\uB97C \uB2E4\uC2DC \uBD88\uB7EC\uB3C4 \uC0C8\uB85C \uB9CC\uB4E4\uC9C0 \uC54A\uACE0 \uC774 \uD504\uB85C\uC81D\uD2B8\uAC00 \uB098\uC635\uB2C8\uB2E4."
+      ].join("\n")
+    };
+  });
+}
 
 // src/mcp/server.ts
 var RESOLUTIONS = ["480p", "720p", "1080p", "4k"];
@@ -16779,7 +16822,7 @@ var TOOLS = [
   },
   {
     name: "democut_list_projects",
-    description: "\uC774 \uC6CC\uD06C\uC2A4\uD398\uC774\uC2A4\uC758 \uD504\uB85C\uC81D\uD2B8 \uBAA9\uB85D\uC744 \uCD5C\uADFC \uC218\uC815\uC21C\uC73C\uB85C \uD655\uC778\uD55C\uB2E4. \uBD80\uC791\uC6A9\uB3C4 \uACFC\uAE08\uB3C4 \uC5C6\uB2E4. democut_generate_video \uC758 project_slug \uB294 **\uC2E4\uC7AC\uD558\uB294 \uBCF8\uC778 \uD504\uB85C\uC81D\uD2B8\uC5EC\uC57C** \uD558\uACE0 \uD2C0\uB9AC\uBA74 404 \uB2E4 \u2014 \uC2AC\uB7EC\uADF8\uB97C \uBAA8\uB974\uBA74 \uCD94\uCE21\uD558\uC9C0 \uB9D0\uACE0 \uC774\uAC78\uB85C \uBA3C\uC800 \uD655\uC778\uD558\uB77C. \uBAA9\uB85D\uC774 \uBE44\uC5B4 \uC788\uC73C\uBA74 \uC544\uC9C1 \uD504\uB85C\uC81D\uD2B8\uAC00 \uC5C6\uB2E4\uB294 \uB73B\uC774\uB2C8, \uC0AC\uC6A9\uC790\uC5D0\uAC8C democut.ai \uC5D0\uC11C \uD558\uB098 \uB9CC\uB4E0 \uB4A4 \uB2E4\uC2DC \uC694\uCCAD\uD574 \uB2EC\uB77C\uACE0 \uC54C\uB824\uB77C(\uB124\uAC00 \uC9C1\uC811 \uB9CC\uB4E4 \uC218\uB294 \uC5C6\uB2E4).",
+    description: "\uC774 \uC6CC\uD06C\uC2A4\uD398\uC774\uC2A4\uC758 \uD504\uB85C\uC81D\uD2B8 \uBAA9\uB85D\uC744 \uCD5C\uADFC \uC218\uC815\uC21C\uC73C\uB85C \uD655\uC778\uD55C\uB2E4. \uBD80\uC791\uC6A9\uB3C4 \uACFC\uAE08\uB3C4 \uC5C6\uB2E4. democut_generate_video \uC758 project_slug \uB294 **\uC2E4\uC7AC\uD558\uB294 \uBCF8\uC778 \uD504\uB85C\uC81D\uD2B8\uC5EC\uC57C** \uD558\uACE0 \uD2C0\uB9AC\uBA74 404 \uB2E4 \u2014 \uC2AC\uB7EC\uADF8\uB97C \uBAA8\uB974\uBA74 \uCD94\uCE21\uD558\uC9C0 \uB9D0\uACE0 \uC774\uAC78\uB85C \uBA3C\uC800 \uD655\uC778\uD558\uB77C. \uBAA9\uB85D\uC774 \uBE44\uC5B4 \uC788\uAC70\uB098 \uB9C8\uB545\uD55C \uAC83\uC774 \uC5C6\uC73C\uBA74 democut_create_project \uB85C \uB9CC\uB4E4 \uC218 \uC788\uB2E4 \u2014 \uB2E8 \uBA3C\uC800 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uC5B4\uB290 \uAC83\uC5D0 \uB123\uC744\uC9C0, \uC0C8\uB85C \uB9CC\uB4E0\uB2E4\uBA74 \uC5B4\uB5A4 \uC774\uB984\uC73C\uB85C \uD560\uC9C0 \uBB3C\uC5B4\uB77C.",
     inputSchema: {
       type: "object",
       properties: {
@@ -16791,6 +16834,21 @@ var TOOLS = [
       },
       additionalProperties: false
     }
+  },
+  {
+    name: "democut_create_project",
+    description: "\uD504\uB85C\uC81D\uD2B8\uB97C \uC0C8\uB85C \uB9CC\uB4E0\uB2E4. **\uACFC\uAE08\uC740 \uC5C6\uC9C0\uB9CC \uACC4\uC815\uC5D0 \uB0A8\uB294 \uC4F0\uAE30 \uC791\uC5C5\uC774\uB2E4.** \uC601\uC0C1 \uC0DD\uC131\uC740 \uBE44\uC6A9\uC744 \uADC0\uC18D\uC2DC\uD0AC \uD504\uB85C\uC81D\uD2B8\uAC00 \uC788\uC5B4\uC57C \uD558\uBBC0\uB85C, democut_list_projects \uAC00 \uBE44\uC5B4 \uC788\uAC70\uB098 \uB9C8\uB545\uD55C \uAC83\uC774 \uC5C6\uC744 \uB54C \uC4F4\uB2E4. \u2605 \uBA3C\uC800 democut_list_projects \uB85C **\uC4F8 \uB9CC\uD55C \uAC83\uC774 \uC774\uBBF8 \uC788\uB294\uC9C0 \uBCF4\uACE0**, \uC0AC\uC6A9\uC790\uC5D0\uAC8C \uC5B4\uB290 \uAC83\uC5D0 \uB123\uC744\uC9C0 \uBB3C\uC5B4\uB77C \u2014 \uBB3C\uC5B4\uBCF4\uC9C0 \uC54A\uACE0 \uC0C8\uB85C \uB9CC\uB4E4\uBA74 \uBE44\uC2B7\uD55C \uD504\uB85C\uC81D\uD2B8\uAC00 \uC313\uC778\uB2E4. \uAC19\uC740 \uC81C\uBAA9\uC73C\uB85C \uB2E4\uC2DC \uBD80\uB974\uBA74 \uC0C8\uB85C \uB9CC\uB4E4\uC9C0 \uC54A\uACE0 **\uAE30\uC874 \uAC83\uC744 \uB3CC\uB824\uC900\uB2E4**(\uC7AC\uC2DC\uB3C4 \uC548\uC804).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "\uD504\uB85C\uC81D\uD2B8 \uC774\uB984 1~100\uC790. \uC0AC\uC6A9\uC790\uAC00 \uC54C\uC544\uBCFC \uC218 \uC788\uAC8C \uC9D3\uACE0, \uAC00\uB2A5\uD558\uBA74 \uC0AC\uC6A9\uC790\uAC00 \uBD80\uB978 \uC774\uB984\uC744 \uADF8\uB300\uB85C \uC4F0\uB77C."
+        }
+      },
+      required: ["title"],
+      additionalProperties: false
+    }
   }
 ];
 function dispatch(name, args, deps = {}) {
@@ -16809,6 +16867,8 @@ function dispatch(name, args, deps = {}) {
       return creditLedger(args, deps);
     case "democut_list_projects":
       return listProjects(args, deps);
+    case "democut_create_project":
+      return createProject(args, deps);
     default:
       return Promise.resolve({ isError: true, text: `\uC54C \uC218 \uC5C6\uB294 \uB3C4\uAD6C: ${name}` });
   }
@@ -16848,7 +16908,8 @@ var HELP = `democut \u2014 DemoCut \uC5D0\uC774\uC804\uD2B8 CLI (OAuth2 device f
   democut video status <job_id> [--wait] [--output <\uACBD\uB85C>]
 
   democut mcp                                  MCP \uC11C\uBC84(stdio) \u2014 \uC5D0\uC774\uC804\uD2B8\uC5D0 \uB3C4\uAD6C\uB85C \uBD99\uC778\uB2E4
-                                               \uB4F1\uB85D: claude mcp add democut -- npx -y democut mcp
+                                               \uB4F1\uB85D: claude mcp add democut -- npx -y democut@latest mcp
+                                               (@latest \uD544\uC218 \u2014 -y \uB294 npx \uCE90\uC2DC\uC758 \uC61B \uBC84\uC804\uC744 \uADF8\uB300\uB85C \uB744\uC6B4\uB2E4)
 
 \uC0DD\uC131 \uC635\uC158:
   --duration <\uCD08>     \uAE30\uBCF8 5 (\uBAA8\uB378\uBCC4 \uD5C8\uC6A9 \uBC94\uC704 \uB2E4\uB984: 2.0=4~15, 2.5=4~30)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "democut",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "DemoCut 에이전트 CLI — device flow 로그인(RFC 8628) + 영상 생성",
   "license": "MIT",
   "author": "InfoGrab",