@yoonion/mimi-seed-mcp 0.11.1 → 0.12.0

package/README.md

@@ -74,7 +74,7 @@ export ANTHROPIC_API_KEY=sk-ant-...
 
 ---
 
-## 제공 도구 (150+ 개 · 18개 영역)
+## 제공 도구 (150+ 개 · 19개 영역)
 
 | 영역 | 도구 수 | 주요 도구 |
 |------|---------|-----------|
@@ -96,6 +96,7 @@ export ANTHROPIC_API_KEY=sk-ant-...
 | Android 서명 | 3 | `android_signing_setup` / `android_generate_keystore` / `jenkins_upload_playstore_sa` |
 | 인증 | 4 | `mimi_seed_status` / `mimi_seed_auth_start` / `mimi_seed_auth_status` / `mimi_seed_remote_sync_credentials` |
 | AI (Claude) | 2 | `generate_release_notes_from_commits` / `generate_review_reply` |
+| 영상 제작 | 11 | `video_plan_from_story` / `video_research_youtube` / `video_synthesize_research` / `video_generate_image` / `video_render` |
 
 > 인앱 결제(IAP·구독) 도구는 위 Play Store·App Store 카운트에 포함됩니다 — `appstore_create_inapp_purchase` · `appstore_update_product_review_note` · `appstore_upload_product_review_screenshot` 등.
 > 전체 카탈로그(항상 최신): [`docs/domain/tool-catalog.md`](../../docs/domain/tool-catalog.md)
@@ -225,6 +226,10 @@ Claude가 연쇄 호출:
 | 변수 | 설명 |
 |------|------|
 | `ANTHROPIC_API_KEY` | AI 릴리즈 노트 생성 / 리뷰 답변 활성화 (선택) |
+| `YOUTUBE_API_KEY` | 참고 영상 메타데이터 조사 (선택) |
+| `PEXELS_API_KEY` | Pexels 스톡 영상 검색 (선택) |
+| `OPENAI_API_KEY` | 장면 이미지 생성 (선택) |
+| `MIMI_SEED_FFMPEG_PATH` / `MIMI_SEED_FFPROBE_PATH` | FFmpeg/ffprobe가 PATH에 없을 때 실행 파일 경로 (선택) |
 
 ---
 

package/assets/agent-guide.md

@@ -16,7 +16,7 @@ and which actions are irreversible.
 
 ## 0. The one thing that trips every agent: deferred tools
 
-Mimi Seed exposes **150+ MCP tools** across 18 domains (full inventory:
+Mimi Seed exposes **150+ MCP tools** across 19 domains (full inventory:
 [`docs/domain/tool-catalog.md`](domain/tool-catalog.md)). Harnesses that lazy-load large tool catalogs —
 **Claude Code most notably** — register these tools as **deferred**: the tool *names*
 are visible (in a system reminder), but the **input schemas are not loaded**. If you
@@ -56,6 +56,7 @@ tools directly — but the *call order* and *safety rules* below still apply.
 | Jenkins credentials + jobs | `select:jenkins_status,jenkins_save_config,jenkins_list_credentials,jenkins_create_credential,jenkins_upload_keystore,jenkins_upload_playstore_sa,jenkins_list_jobs,jenkins_get_job_config,jenkins_create_job,jenkins_update_job` |
 | CI (GitHub/GitLab) | `select:ci_save_config,ci_list_workflows,ci_trigger_build,ci_get_build_status,ci_list_recent_builds` |
 | Service account end-to-end | `select:iam_create_service_account,iam_create_key,iam_add_iam_policy_binding,playstore_register_service_account,playstore_verify_service_account` |
+| Story → researched video | `select:video_plan_from_story,video_research_youtube,video_search_stock_assets,video_synthesize_research,video_download_stock_assets,video_generate_image,video_add_local_asset,video_build_timeline,video_render,video_job_status,video_validate` |
 
 ---
 
@@ -79,13 +80,13 @@ every credential, which also tells them where to obtain each token
 
 | Service | Fix |
 |---------|-----|
-| Google (Firebase/AdMob/Play/Ads/GSC/GA4/IAM/BigQuery) | tool `mimi_seed_auth_start` → give the user the OAuth URL, **or** `mimi-seed auth login` |
+| Google (Firebase/AdMob/Play/Ads/GSC/GA4/IAM/BigQuery) | tool `mimi_seed_auth_start` → give the user the OAuth URL, **or** `mimi-seed auth login`. Both accept a **domain subset** (`domains=["ga4","googleads"]` / `--domains ga4,googleads`) — request only what the task needs; re-auth keeps prior grants (incremental). Omit for all domains |
 | App Store Connect | `mimi-seed auth appstore` → verify with `appstore_verify_credentials` |
 | Play service account | `mimi-seed auth playstore`, or register per-package with `playstore_register_service_account`. **Optional** — the OAuth token carries `androidpublisher`, so this is only needed for headless/CI |
 | BigQuery | `mimi-seed auth bigquery` (optional — OAuth works too) |
 | Jenkins | `mimi-seed auth jenkins` (probes the server before saving) |
 | GitHub / GitLab CI | `mimi-seed auth ci` |
-| Google Ads | `mimi-seed auth googleads` — needs the `adwords` OAuth scope; an old token may need `mimi-seed auth login --force` |
+| Google Ads | `mimi-seed auth googleads` — needs the `adwords` OAuth scope; an old token may need `mimi-seed auth login --domains googleads` (adds the grant, keeps the rest) |
 | Facebook / Instagram / Threads | `mimi-seed auth facebook` / `mimi-seed auth instagram` / `mimi-seed auth threads` |
 
 `mimi-seed auth meta` opens the combined social setup entry point when the user wants to review or reconnect
@@ -126,6 +127,10 @@ Notes that matter in practice:
   `playstore_*` call returns `403`.
 - AI features (`generate_release_notes_from_commits`, `generate_review_reply`) need
   `ANTHROPIC_API_KEY` in the environment.
+- Video production uses capability-specific environment keys: `ANTHROPIC_API_KEY` (storyboard),
+  `YOUTUBE_API_KEY` (reference research), `PEXELS_API_KEY` (licensed stock search), and
+  `OPENAI_API_KEY` (generated images). Rendering needs FFmpeg on `PATH` or
+  `MIMI_SEED_FFMPEG_PATH`.
 
 ---
 
@@ -148,6 +153,7 @@ per-domain inventory is [`docs/domain/tool-catalog.md`](domain/tool-catalog.md).
 | **Facebook / Instagram / Threads** | `facebook_post_photo` · `instagram_post_carousel` · `threads_post` · `threads_refresh_token` |
 | **Checks** | `playstore_check_submission_risks` · `appstore_check_submission_risks` · `screenshot_validate` · `release_status` |
 | **AI / Auth** | `generate_release_notes_from_commits` · `generate_review_reply` · `mimi_seed_status` · `mimi_seed_auth_start` · `mimi_seed_auth_status` · `mimi_seed_remote_sync_credentials` |
+| **Video production** | `video_plan_from_story` · `video_research_youtube` · `video_search_stock_assets` · `video_synthesize_research` · `video_generate_image` · `video_build_timeline` · `video_render` · `video_job_status` · `video_validate` |
 
 ---
 
@@ -169,6 +175,18 @@ per-domain inventory is [`docs/domain/tool-catalog.md`](domain/tool-catalog.md).
 `generate_release_notes_from_commits` (pass commit array + locales) → review with user →
 `playstore_update_release_notes` / `appstore_update_whats_new`.
 
+### Story → researched video
+1. `video_plan_from_story` — create the project and scene plan.
+2. `video_research_youtube` — collect reference-only metadata; never treat a result as a render asset.
+3. `video_search_stock_assets` — find licensed Pexels candidates.
+4. `video_synthesize_research` — combine metadata with any direct human/agent observations. Treat its output as
+   metadata-bounded guidance, not proof that the source videos were watched.
+5. Preview then confirm `video_download_stock_assets`; use `video_generate_image(confirm=false)` before any paid
+   generation and call it again with `confirm=true` only after approval. User-owned media goes through
+   `video_add_local_asset` with its ownership/license basis.
+6. `video_build_timeline` — provenance-gated scene assignment.
+7. Preview then confirm `video_render`; poll `video_job_status`, then run `video_validate` on the completed MP4.
+
 > **Mimi Seed does not compile app binaries.** It manages metadata, store releases, and
 > CI/Jenkins *credentials and job definitions* — not Xcode/Gradle builds. To produce an
 > `.ipa`/`.aab`, use EAS, Xcode, or a CI/Jenkins job. There is **no `jenkins_trigger_build`

package/dist/auth/cli.js

@@ -4,6 +4,7 @@ import open from 'open';
 import { startAuth, getStoredTokens, ensureFreshAccessToken, } from './google-auth.js';
 import { AuthError, classifyError } from './errors.js';
 import { getMcpOAuthClient } from './constants.js';
+import { AUTH_DOMAINS, DOMAIN_IDS, parseDomainList, summarizeGrantedDomains, } from './scopes.js';
 import { resolveLang } from '../lib/lang.js';
 // ko 가 원본이고 en 은 `typeof ko` 를 만족해야 한다 — 키를 빠뜨리면 컴파일이 깨진다.
 // 여기 있는 건 전부 **터미널에 찍히는 사람용 문자열**이다. errors.ts 가 만드는
@@ -14,11 +15,14 @@ const ko = {
 
   사용법:
     mimi-seed-auth                  # 로그인 (이미 있으면 자동 refresh 시도)
+    mimi-seed-auth --domains ga4,googleads   # 필요한 권한 도메인만 요청 (기존 권한 유지)
     mimi-seed-auth --refresh        # refresh_token으로 갱신만 시도 (브라우저 X)
-    mimi-seed-auth --status         # 현재 토큰 상태 출력
+    mimi-seed-auth --status         # 현재 토큰 상태 + 부여 도메인 출력
     mimi-seed-auth --logout         # 토큰 삭제
 
   옵션:
+    --domains <ids>  요청할 권한 도메인 (쉼표 구분, 미지정 시 전체).
+                     가능한 값: ${DOMAIN_IDS.join(', ')}
     --no-browser     URL 자동 오픈 안 함 (직접 복붙)
     --timeout <초>   콜백 대기 시간 (기본 600)
     --force          기존 토큰 무시하고 강제 재로그인
@@ -34,6 +38,11 @@ const ko = {
     statusRefreshed: (left) => `  ✅ 연결됨 — refresh_token으로 갱신 (${left})`,
     statusExpired: '  ⚠️  토큰 만료 + 자동 갱신 실패',
     statusNone: '  ❌ 연결된 계정 없음.',
+    grantedDomains: (list) => `     권한 도메인: ${list}`,
+    missingDomains: (list) => `     미부여: ${list} — mimi-seed-auth --domains <id> 로 추가 (기존 권한 유지)`,
+    domainsUnknown: '     권한 도메인: (구 토큰 — scope 기록 없음. 재로그인하면 기록됨)',
+    invalidDomains: (bad, valid) => `  ❌ 알 수 없는 도메인: ${bad}\n     가능한 값: ${valid}`,
+    domainsRequested: (list) => `  🎯 요청 도메인: ${list} (기존 부여 권한은 유지)`,
     refreshTrying: '  🔄 refresh_token으로 갱신 시도 중...',
     refreshNotNeeded: (left) => `  ✅ 토큰 유효 — 갱신 불필요 (${left})`,
     refreshDone: (left) => `  ✅ 갱신 완료 (${left})`,
@@ -70,11 +79,14 @@ const en = {
 
   Usage:
     mimi-seed-auth                  # log in (tries a silent refresh if a token exists)
+    mimi-seed-auth --domains ga4,googleads   # request only the domains you need (keeps prior grants)
     mimi-seed-auth --refresh        # only refresh with refresh_token (no browser)
-    mimi-seed-auth --status         # print the current token status
+    mimi-seed-auth --status         # print the current token status + granted domains
     mimi-seed-auth --logout         # delete the token
 
   Options:
+    --domains <ids>  Permission domains to request (comma-separated; all when omitted).
+                     Available: ${DOMAIN_IDS.join(', ')}
     --no-browser     Do not open the URL automatically (copy-paste it yourself)
     --timeout <sec>  How long to wait for the callback (default 600)
     --force          Ignore the existing token and force a re-login
@@ -90,6 +102,11 @@ const en = {
     statusRefreshed: (left) => `  ✅ Connected — refreshed with refresh_token (${left})`,
     statusExpired: '  ⚠️  Token expired + automatic refresh failed',
     statusNone: '  ❌ No connected account.',
+    grantedDomains: (list) => `     Granted domains: ${list}`,
+    missingDomains: (list) => `     Not granted: ${list} — add with mimi-seed-auth --domains <id> (prior grants are kept)`,
+    domainsUnknown: '     Granted domains: (legacy token — no scope record; re-login records it)',
+    invalidDomains: (bad, valid) => `  ❌ Unknown domain(s): ${bad}\n     Available: ${valid}`,
+    domainsRequested: (list) => `  🎯 Requesting domains: ${list} (prior grants are kept)`,
     refreshTrying: '  🔄 Trying to refresh with refresh_token...',
     refreshNotNeeded: (left) => `  ✅ Token still valid — no refresh needed (${left})`,
     refreshDone: (left) => `  ✅ Refreshed (${left})`,
@@ -155,6 +172,17 @@ function printAuthError(p) {
     if (p.cause && process.env.DEBUG)
         err(`     (cause: ${p.cause})`);
 }
+/** 도메인 선택형 로그인 이후 토큰은 전체 권한이 아닐 수 있다 — 부여 현황을 함께 출력. */
+function printGrantedDomains() {
+    const summary = summarizeGrantedDomains(getStoredTokens()?.scope);
+    if (!summary.known) {
+        err(M.domainsUnknown);
+        return;
+    }
+    err(M.grantedDomains(summary.granted.join(', ') || '-'));
+    if (summary.missing.length > 0)
+        err(M.missingDomains(summary.missing.join(', ')));
+}
 async function cmdStatus() {
     err('');
     err(M.statusTitle);
@@ -163,10 +191,12 @@ async function cmdStatus() {
     switch (r.status) {
         case 'fresh':
             err(M.statusFresh(fmtRemaining(r.msUntilExpiry)));
+            printGrantedDomains();
             err('');
             return 0;
         case 'refreshed':
             err(M.statusRefreshed(fmtRemaining(r.msUntilExpiry)));
+            printGrantedDomains();
             err('');
             return 0;
         case 'expired_refresh_failed':
@@ -227,11 +257,29 @@ async function cmdLogin() {
     const noBrowser = hasFlag('no-browser');
     const force = hasFlag('force');
     const timeoutSec = parseInt(flagValue('timeout') ?? '600', 10);
+    // --domains 파싱. 공백형(--domains ga4)과 equals형(--domains=ga4) 모두 지원하고,
+    // 플래그는 있는데 값이 없거나(--domains, --domains --force) 잘못된 id 면 조용히 전체
+    // 스코프로 폴백하지 않고 에러로 안내한다 — least-privilege 의도가 훼손되지 않도록.
+    const domainsEq = args.find((a) => a.startsWith('--domains='));
+    const domainsRaw = domainsEq ? domainsEq.slice('--domains='.length) : flagValue('domains');
+    const domainsFlagPresent = hasFlag('domains') || domainsEq !== undefined;
+    let domains;
+    if (domainsFlagPresent) {
+        const parsed = domainsRaw ? parseDomainList(domainsRaw) : { domains: [], invalid: [] };
+        if (parsed.invalid.length > 0 || parsed.domains.length === 0) {
+            err('');
+            err(M.invalidDomains(parsed.invalid.join(', ') || domainsRaw || '(값 없음)', DOMAIN_IDS.join(', ')));
+            err('');
+            return 1;
+        }
+        domains = parsed.domains;
+    }
     err('');
     err(M.loginTitle);
     err('');
-    // 1) 기존 토큰이 있으면 silent refresh 먼저 시도
-    if (!force) {
+    // 1) 기존 토큰이 있으면 silent refresh 먼저 시도.
+    //    --domains 는 "권한을 추가로 부여하겠다"는 명시적 의도라 이 단축 경로를 건너뛴다.
+    if (!force && !domains) {
         const existing = getStoredTokens();
         if (existing) {
             err(M.loginChecking);
@@ -264,6 +312,7 @@ async function cmdLogin() {
         const { clientId, clientSecret } = await getMcpOAuthClient();
         const r = startAuth(clientId, clientSecret, {
             timeoutMs: timeoutSec * 1000,
+            domains,
         });
         url = r.url;
         wait = r.wait;
@@ -274,6 +323,9 @@ async function cmdLogin() {
         err('');
         return 1;
     }
+    if (domains) {
+        err(M.domainsRequested(domains.map((d) => `${d} (${AUTH_DOMAINS[d].label})`).join(', ')));
+    }
     // 3) 브라우저 열기 (or URL 출력)
     if (noBrowser) {
         err('');
@@ -318,6 +370,7 @@ async function cmdLogin() {
     err('');
     err('');
     err(M.done);
+    printGrantedDomains();
     err('');
     err(M.nextTitle);
     err(M.nextExample1);

package/dist/auth/google-auth.d.ts

@@ -1,4 +1,6 @@
 import { type AuthErrorPayload } from './errors.js';
+import { type AuthDomainId } from './scopes.js';
+export type { AuthDomainId } from './scopes.js';
 export interface StoredTokens {
     access_token: string;
     refresh_token: string;
@@ -32,9 +34,14 @@ export declare function getAuthenticatedClient(): ReturnType<typeof createOAuth2
  * 호출자가 URL을 사용자에게 전달하거나 `open()`을 직접 호출.
  * `wait` Promise: 토큰 저장 시 resolve, 타임아웃/에러 시 reject.
  * 재호출 시 기존 세션 자동 정리.
+ *
+ * `domains` 로 권한 도메인 서브셋만 요청할 수 있다 (미지정 시 전체 — 기존 동작).
+ * include_granted_scopes 덕에 재로그인은 기존 부여 스코프를 유지한 채 새 스코프만
+ * 얹는다(incremental authorization) — 토큰 응답의 scope 필드에도 누적 전체가 온다.
  */
 export declare function startAuth(clientId: string, clientSecret: string, options?: {
     timeoutMs?: number;
+    domains?: readonly AuthDomainId[];
 }): {
     url: string;
     wait: Promise<StoredTokens>;
@@ -43,7 +50,9 @@ export declare function startAuth(clientId: string, clientSecret: string, option
  * Interactive login — opens browser, waits for callback.
  * startAuth() 래퍼 — CLI에서 사용.
  */
-export declare function login(clientId: string, clientSecret: string): Promise<StoredTokens>;
+export declare function login(clientId: string, clientSecret: string, options?: {
+    domains?: readonly AuthDomainId[];
+}): Promise<StoredTokens>;
 export type RefreshStatus = {
     status: 'fresh';
     tokens: StoredTokens;

package/dist/auth/google-auth.js

@@ -6,20 +6,8 @@ import path from 'node:path';
 import os from 'node:os';
 import { getMcpOAuthClient } from './constants.js';
 import { AuthError, classifyError } from './errors.js';
-const SCOPES = [
-    'https://www.googleapis.com/auth/firebase',
-    'https://www.googleapis.com/auth/cloud-platform',
-    'https://www.googleapis.com/auth/admob.readonly',
-    'https://www.googleapis.com/auth/admob.monetization',
-    'https://www.googleapis.com/auth/androidpublisher',
-    'https://www.googleapis.com/auth/adwords', // Google Ads API (googleads_* tools)
-    'https://www.googleapis.com/auth/webmasters', // Search Console API (gsc_* tools, 사이트맵 제출 포함)
-    'https://www.googleapis.com/auth/analytics.edit', // GA4 Analytics Admin API (ga4_* tools — property/data stream 생성·조회)
-    // GA4 **Data API**(analyticsdata — ga4_run_report)는 analytics.edit 을 받지 않는다.
-    // Admin API 전용 스코프이기 때문. 이게 빠져 있으면 property 목록은 보이는데 리포트만
-    // 403 으로 막혀서, "API 가 꺼졌나" 로 오진하기 쉽다. (2026-07 실사고)
-    'https://www.googleapis.com/auth/analytics.readonly',
-];
+// 스코프 목록의 SSOT 는 scopes.ts (도메인 → 스코프 매핑). 여기서는 로그인 요청 조립만 한다.
+import { scopesForDomains, mergeScopeStrings } from './scopes.js';
 // Primary config dir. Legacy `~/.preseed` is read as a fallback during the
 // rebrand so existing auth sessions don't force a re-login; new writes go to
 // the new dir.
@@ -131,6 +119,10 @@ let activeAuthServer = null;
  * 호출자가 URL을 사용자에게 전달하거나 `open()`을 직접 호출.
  * `wait` Promise: 토큰 저장 시 resolve, 타임아웃/에러 시 reject.
  * 재호출 시 기존 세션 자동 정리.
+ *
+ * `domains` 로 권한 도메인 서브셋만 요청할 수 있다 (미지정 시 전체 — 기존 동작).
+ * include_granted_scopes 덕에 재로그인은 기존 부여 스코프를 유지한 채 새 스코프만
+ * 얹는다(incremental authorization) — 토큰 응답의 scope 필드에도 누적 전체가 온다.
  */
 export function startAuth(clientId, clientSecret, options = {}) {
     if (activeAuthServer) {
@@ -142,10 +134,12 @@ export function startAuth(clientId, clientSecret, options = {}) {
     }
     saveCredentials(clientId, clientSecret);
     const oauth2Client = createOAuth2Client(clientId, clientSecret);
+    const requestedScopes = scopesForDomains(options.domains);
     const authUrl = oauth2Client.generateAuthUrl({
         access_type: 'offline',
-        scope: SCOPES,
+        scope: requestedScopes,
         prompt: 'consent',
+        include_granted_scopes: true,
     });
     const wait = new Promise((resolve, reject) => {
         const rejectAuth = (e) => reject(new AuthError(classifyError(e, { phase: 'login' })));
@@ -210,12 +204,20 @@ export function startAuth(clientId, clientSecret, options = {}) {
                     }));
                     return;
                 }
+                // scope 는 항상 기록한다 — 그리고 누적(monotonic)으로 저장한다.
+                //   1) include_granted_scopes 로 Google 측 grant 는 (기존 부여분 ∪ 이번 요청분)이다.
+                //   2) 응답의 tokens.scope 는 그 합집합이어야 하지만, 만약 Google 이 좁혀서 주거나
+                //      생략하면(빈 값) 여기서 기존 기록 + 이번 요청 스코프로 보정한다.
+                // 이렇게 해야 "scope 미기록 = 추적 이전 legacy 토큰" 불변식이 유지된다 — 도메인
+                // 선택형 로그인이 이를 깨서, 좁은 로그인이 legacy 로 오인돼 pre-flight 를 우회하는
+                // 것을 막는다. (기존엔 응답 scope 로 통째 덮어써서 이 두 위험에 모두 노출됐다.)
+                const priorScope = getStoredTokens()?.scope;
                 const stored = {
                     access_token: tokens.access_token,
                     refresh_token: tokens.refresh_token,
                     token_type: tokens.token_type ?? 'Bearer',
                     expiry_date: tokens.expiry_date ?? Date.now() + 3600_000,
-                    ...(tokens.scope && { scope: tokens.scope }),
+                    scope: mergeScopeStrings(priorScope, tokens.scope ?? requestedScopes.join(' ')),
                 };
                 saveTokens(stored);
                 res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
@@ -269,8 +271,8 @@ export function startAuth(clientId, clientSecret, options = {}) {
  * Interactive login — opens browser, waits for callback.
  * startAuth() 래퍼 — CLI에서 사용.
  */
-export async function login(clientId, clientSecret) {
-    const { url, wait } = startAuth(clientId, clientSecret);
+export async function login(clientId, clientSecret, options = {}) {
+    const { url, wait } = startAuth(clientId, clientSecret, options);
     console.log('🔐 브라우저에서 Google 로그인 중...');
     open(url);
     return wait;

package/dist/auth/scopes.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Google OAuth "권한 도메인" → 스코프 매핑의 SSOT.
+ *
+ * mimi-seed 는 통합 플랫폼이라 여러 구글 서비스 스코프를 다루는데, 예전엔 로그인 한 번에
+ * 전부(full-scope)를 강제로 요청했다. OAuth 앱 심사(verification)의 "Requesting Minimum
+ * Scopes" 요건과 least-privilege 원칙에 맞추기 위해, 사용자가 쓸 도메인만 골라 동의하는
+ * 선택형(incremental) 인증으로 바꿨다:
+ *
+ *   - 로그인 시 도메인 서브셋만 요청 가능 (`mimi-seed-auth --domains ga4,googleads`,
+ *     MCP `mimi_seed_auth_start` 의 `domains` 파라미터). 미지정 시 기존과 동일한 전체 요청.
+ *   - `include_granted_scopes=true` 로 요청하므로, 나중에 도메인을 추가해도 기존 부여
+ *     권한은 유지된 채 새 권한만 얹힌다 (Google incremental authorization).
+ *   - 도구 쪽은 `requireAuth(<scope>)` pre-flight 가 미부여 도메인을 결정적으로 안내한다.
+ *
+ * 도메인 경계는 "어느 도구 군이 어느 스코프를 실제 소비하는가" 기준이다. 특히
+ * cloud-platform 은 IAM API(서비스 계정 생성·키 발급)가 더 좁은 대안 스코프를 제공하지
+ * 않아서 유지하되, `gcp` 도메인으로 격리해 그 도구를 쓰는 사용자만 요청하게 한다.
+ */
+export interface AuthDomainDef {
+    /** 사람이 읽을 라벨 (동의 화면 아님 — CLI/도구 안내용) */
+    label: string;
+    scopes: readonly string[];
+    /** 이 도메인이 여는 도구/작업 요약 — CLI·MCP 안내 문자열에 사용 */
+    summary: string;
+}
+export declare const AUTH_DOMAINS: {
+    readonly firebase: {
+        readonly label: "Firebase";
+        readonly scopes: readonly ["https://www.googleapis.com/auth/firebase"];
+        readonly summary: "firebase_* — 프로젝트/앱/설정 조회·생성 (프로젝트 신규 생성·서비스 활성화는 gcp 도 필요)";
+    };
+    readonly gcp: {
+        readonly label: "Google Cloud (cloud-platform)";
+        readonly scopes: readonly ["https://www.googleapis.com/auth/cloud-platform"];
+        readonly summary: "iam_* (서비스 계정·키·IAM 바인딩 — IAM API 는 이 스코프의 좁은 대안이 없음), firebase 프로젝트 생성·서비스 활성화, BigQuery OAuth fallback";
+    };
+    readonly admob: {
+        readonly label: "AdMob";
+        readonly scopes: readonly ["https://www.googleapis.com/auth/admob.readonly", "https://www.googleapis.com/auth/admob.monetization"];
+        readonly summary: "admob_* — 수익 리포트, 앱·광고 단위 생성";
+    };
+    readonly playstore: {
+        readonly label: "Play Store";
+        readonly scopes: readonly ["https://www.googleapis.com/auth/androidpublisher"];
+        readonly summary: "playstore_* — 서비스 계정 없이 OAuth 로 하는 Play Console 작업";
+    };
+    readonly googleads: {
+        readonly label: "Google Ads";
+        readonly scopes: readonly ["https://www.googleapis.com/auth/adwords"];
+        readonly summary: "googleads_* — 캠페인·UAC 리포트";
+    };
+    readonly gsc: {
+        readonly label: "Search Console";
+        readonly scopes: readonly ["https://www.googleapis.com/auth/webmasters"];
+        readonly summary: "gsc_* — 사이트·사이트맵·검색 성과 (사이트맵 제출 포함)";
+    };
+    readonly ga4: {
+        readonly label: "Google Analytics (GA4)";
+        readonly scopes: readonly ["https://www.googleapis.com/auth/analytics.edit", "https://www.googleapis.com/auth/analytics.readonly"];
+        readonly summary: "ga4_* — property/data stream 생성·조회 + 리포트";
+    };
+};
+export type AuthDomainId = keyof typeof AUTH_DOMAINS;
+/** z.enum 등 튜플이 필요한 자리에 쓰는 도메인 id 목록 (선언 순서 유지). */
+export declare const DOMAIN_IDS: [AuthDomainId, ...AuthDomainId[]];
+export declare const CLOUD_PLATFORM_SCOPE: "https://www.googleapis.com/auth/cloud-platform";
+/**
+ * 공백 구분 scope 문자열들의 합집합. tokens.json 의 scope 는 누적(monotonic)이어야 하므로
+ * 로그인/갱신 시 기존 기록 + 새 응답을 합쳐 저장하는 데 쓴다. undefined/빈 문자열은 무시.
+ */
+export declare function mergeScopeStrings(...parts: Array<string | undefined>): string;
+/**
+ * 전체 스코프 (도메인 선언 순서대로 평탄화).
+ * 도메인 미지정 로그인의 기본값이자, 선택형 도입 전 full-scope 목록과 동일해야 한다
+ * (auth-scopes.test.ts 가 고정한다 — 스코프가 소리 없이 빠지면 기존 사용자 도구가 죽는다).
+ */
+export declare const ALL_SCOPES: readonly string[];
+/** 도메인 서브셋 → 요청할 스코프 목록. 미지정/빈 배열이면 전체(기존 동작). */
+export declare function scopesForDomains(domains?: readonly AuthDomainId[]): string[];
+/** 스코프 하나를 요구하는 도메인들 (INSUFFICIENT_SCOPE 안내에서 "--domains X" 를 채울 때 사용). */
+export declare function domainsForScope(scope: string): AuthDomainId[];
+/** CLI `--domains a,b,c` 파싱. 잘못된 id 는 invalid 로 분리해 호출자가 안내한다. */
+export declare function parseDomainList(raw: string): {
+    domains: AuthDomainId[];
+    invalid: string[];
+};
+export interface GrantedDomainSummary {
+    /** tokens.json 에 scope 기록이 있는지. false 면 스코프 추적 도입 전 구 토큰. */
+    known: boolean;
+    /** 도메인의 스코프가 전부 부여된 도메인들 */
+    granted: AuthDomainId[];
+    /** 하나라도 미부여인 도메인들 */
+    missing: AuthDomainId[];
+}
+/** tokens.json 의 공백 구분 scope 문자열 → 도메인 단위 부여 현황. */
+export declare function summarizeGrantedDomains(scopeStr: string | undefined): GrantedDomainSummary;
+/** 구 토큰(scope 미기록)이 이 스코프를 보유했다고 간주해도 되는가. */
+export declare function isPreTrackingScope(scope: string): boolean;

package/dist/auth/scopes.js

@@ -0,0 +1,159 @@
+/**
+ * Google OAuth "권한 도메인" → 스코프 매핑의 SSOT.
+ *
+ * mimi-seed 는 통합 플랫폼이라 여러 구글 서비스 스코프를 다루는데, 예전엔 로그인 한 번에
+ * 전부(full-scope)를 강제로 요청했다. OAuth 앱 심사(verification)의 "Requesting Minimum
+ * Scopes" 요건과 least-privilege 원칙에 맞추기 위해, 사용자가 쓸 도메인만 골라 동의하는
+ * 선택형(incremental) 인증으로 바꿨다:
+ *
+ *   - 로그인 시 도메인 서브셋만 요청 가능 (`mimi-seed-auth --domains ga4,googleads`,
+ *     MCP `mimi_seed_auth_start` 의 `domains` 파라미터). 미지정 시 기존과 동일한 전체 요청.
+ *   - `include_granted_scopes=true` 로 요청하므로, 나중에 도메인을 추가해도 기존 부여
+ *     권한은 유지된 채 새 권한만 얹힌다 (Google incremental authorization).
+ *   - 도구 쪽은 `requireAuth(<scope>)` pre-flight 가 미부여 도메인을 결정적으로 안내한다.
+ *
+ * 도메인 경계는 "어느 도구 군이 어느 스코프를 실제 소비하는가" 기준이다. 특히
+ * cloud-platform 은 IAM API(서비스 계정 생성·키 발급)가 더 좁은 대안 스코프를 제공하지
+ * 않아서 유지하되, `gcp` 도메인으로 격리해 그 도구를 쓰는 사용자만 요청하게 한다.
+ */
+export const AUTH_DOMAINS = {
+    firebase: {
+        label: 'Firebase',
+        scopes: ['https://www.googleapis.com/auth/firebase'],
+        summary: 'firebase_* — 프로젝트/앱/설정 조회·생성 (프로젝트 신규 생성·서비스 활성화는 gcp 도 필요)',
+    },
+    gcp: {
+        label: 'Google Cloud (cloud-platform)',
+        scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+        summary: 'iam_* (서비스 계정·키·IAM 바인딩 — IAM API 는 이 스코프의 좁은 대안이 없음), firebase 프로젝트 생성·서비스 활성화, BigQuery OAuth fallback',
+    },
+    admob: {
+        label: 'AdMob',
+        scopes: [
+            'https://www.googleapis.com/auth/admob.readonly',
+            'https://www.googleapis.com/auth/admob.monetization',
+        ],
+        summary: 'admob_* — 수익 리포트, 앱·광고 단위 생성',
+    },
+    playstore: {
+        label: 'Play Store',
+        scopes: ['https://www.googleapis.com/auth/androidpublisher'],
+        summary: 'playstore_* — 서비스 계정 없이 OAuth 로 하는 Play Console 작업',
+    },
+    googleads: {
+        label: 'Google Ads',
+        scopes: ['https://www.googleapis.com/auth/adwords'],
+        summary: 'googleads_* — 캠페인·UAC 리포트',
+    },
+    gsc: {
+        label: 'Search Console',
+        scopes: ['https://www.googleapis.com/auth/webmasters'],
+        summary: 'gsc_* — 사이트·사이트맵·검색 성과 (사이트맵 제출 포함)',
+    },
+    ga4: {
+        label: 'Google Analytics (GA4)',
+        scopes: [
+            // Admin API(property/data stream 생성·조회) 전용.
+            'https://www.googleapis.com/auth/analytics.edit',
+            // Data API(runReport)는 analytics.edit 을 받지 않는다 — 같은 도메인이지만 별도 스코프.
+            // (ga4/tools.ts 의 GA4_DATA_SCOPE 주석, 2026-07 실사고 참고.)
+            'https://www.googleapis.com/auth/analytics.readonly',
+        ],
+        summary: 'ga4_* — property/data stream 생성·조회 + 리포트',
+    },
+};
+/** z.enum 등 튜플이 필요한 자리에 쓰는 도메인 id 목록 (선언 순서 유지). */
+export const DOMAIN_IDS = Object.keys(AUTH_DOMAINS);
+export const CLOUD_PLATFORM_SCOPE = AUTH_DOMAINS.gcp.scopes[0];
+function dedupe(scopes) {
+    return [...new Set(scopes)];
+}
+/**
+ * 공백 구분 scope 문자열들의 합집합. tokens.json 의 scope 는 누적(monotonic)이어야 하므로
+ * 로그인/갱신 시 기존 기록 + 새 응답을 합쳐 저장하는 데 쓴다. undefined/빈 문자열은 무시.
+ */
+export function mergeScopeStrings(...parts) {
+    const set = new Set();
+    for (const part of parts) {
+        if (!part)
+            continue;
+        for (const s of part.split(' '))
+            if (s)
+                set.add(s);
+    }
+    return [...set].join(' ');
+}
+/**
+ * 전체 스코프 (도메인 선언 순서대로 평탄화).
+ * 도메인 미지정 로그인의 기본값이자, 선택형 도입 전 full-scope 목록과 동일해야 한다
+ * (auth-scopes.test.ts 가 고정한다 — 스코프가 소리 없이 빠지면 기존 사용자 도구가 죽는다).
+ */
+export const ALL_SCOPES = dedupe(DOMAIN_IDS.flatMap((id) => AUTH_DOMAINS[id].scopes));
+/** 도메인 서브셋 → 요청할 스코프 목록. 미지정/빈 배열이면 전체(기존 동작). */
+export function scopesForDomains(domains) {
+    if (!domains || domains.length === 0)
+        return [...ALL_SCOPES];
+    return dedupe(domains.flatMap((id) => AUTH_DOMAINS[id].scopes));
+}
+/** 스코프 하나를 요구하는 도메인들 (INSUFFICIENT_SCOPE 안내에서 "--domains X" 를 채울 때 사용). */
+export function domainsForScope(scope) {
+    return DOMAIN_IDS.filter((id) => AUTH_DOMAINS[id].scopes.includes(scope));
+}
+/** CLI `--domains a,b,c` 파싱. 잘못된 id 는 invalid 로 분리해 호출자가 안내한다. */
+export function parseDomainList(raw) {
+    const domains = [];
+    const invalid = [];
+    for (const part of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
+        if (DOMAIN_IDS.includes(part)) {
+            const id = part;
+            if (!domains.includes(id))
+                domains.push(id);
+        }
+        else {
+            invalid.push(part);
+        }
+    }
+    return { domains, invalid };
+}
+/** tokens.json 의 공백 구분 scope 문자열 → 도메인 단위 부여 현황. */
+export function summarizeGrantedDomains(scopeStr) {
+    if (scopeStr === undefined)
+        return { known: false, granted: [], missing: [] };
+    const grantedScopes = new Set(scopeStr.split(' ').filter(Boolean));
+    const granted = [];
+    const missing = [];
+    for (const id of DOMAIN_IDS) {
+        if (AUTH_DOMAINS[id].scopes.every((s) => grantedScopes.has(s)))
+            granted.push(id);
+        else
+            missing.push(id);
+    }
+    return { known: true, granted, missing };
+}
+/**
+ * scope 추적 도입 시점에 **이미 존재하던** 스코프들의 **동결(frozen) 스냅샷**.
+ *
+ * 구 토큰(scope === undefined)은 추적 도입 이전의 full-scope 로그인이므로, 이 시점에
+ * 존재하던 스코프는 보유로 간주해야 한다 — 안 그러면 pre-flight 를 새로 다는 순간
+ * 멀쩡히 동작하던 기존 사용자에게 불필요한 재로그인을 강제한다.
+ *
+ * 왜 "이후 추가된 것"이 아니라 "이전에 있던 것"을 나열하는가(안전한 쪽 동결):
+ * 추적 도입 이후 추가되는 스코프(GA4 analytics.* 를 포함해 앞으로의 모든 신규 스코프)는
+ * 이 집합에 없으므로 자동으로 '추적 이후'로 분류돼, 구 토큰에서 '미보유'로 안전하게
+ * 취급된다. 반대 방향(추가된 것을 나열)으로 두면 신규 스코프를 넣는 사람이 목록 갱신을
+ * 잊는 순간 구 토큰이 그 스코프를 '보유'로 오인해 pre-flight 가 무력화된다. 이 집합은
+ * 동결이라 **새 스코프를 여기 추가할 일은 없다**(auth-scopes.test.ts 가 고정).
+ */
+const PRE_TRACKING_SCOPES = new Set([
+    'https://www.googleapis.com/auth/firebase',
+    'https://www.googleapis.com/auth/cloud-platform',
+    'https://www.googleapis.com/auth/admob.readonly',
+    'https://www.googleapis.com/auth/admob.monetization',
+    'https://www.googleapis.com/auth/androidpublisher',
+    'https://www.googleapis.com/auth/adwords',
+    'https://www.googleapis.com/auth/webmasters',
+]);
+/** 구 토큰(scope 미기록)이 이 스코프를 보유했다고 간주해도 되는가. */
+export function isPreTrackingScope(scope) {
+    return PRE_TRACKING_SCOPES.has(scope);
+}