@yoonion/mimi-seed-mcp 0.3.25 → 0.3.27

package/dist/appstore/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * App Store Connect API 에러 친절화.
+ *
+ * Apple은 표준 JSON 에러 응답을 내려준다:
+ *   { "errors": [{ "code": "...", "title": "...", "detail": "...",
+ *                  "source": { "pointer": "/data/attributes/whatsNew" } }] }
+ *
+ * 실제 거부 사례에서 자주 만나는 코드별 hint 를 첨가해
+ * "App Store API 409: { errors: [...] }" 같은 raw dump 대신
+ * 무엇을 고쳐야 하는지 즉시 보이게 한다.
+ *
+ * 비표준 body (HTML, plain text, 빈 응답 등) 는 폴백으로 원본 보존.
+ */
+/** Apple JSON Error response 구조 (단일 errors 배열). */
+interface AppleError {
+    id?: string;
+    code?: string;
+    status?: string;
+    title?: string;
+    detail?: string;
+    source?: {
+        pointer?: string;
+        parameter?: string;
+    };
+}
+/** Apple 표준 에러 응답 파싱 시도. 실패하면 null 반환. */
+declare function parseAppleErrorBody(body: string): AppleError[] | null;
+/** 단일 Apple error → 한 줄 사람용 표기. */
+declare function formatAppleError(e: AppleError): string;
+/**
+ * App Store API 응답 (status + raw body) 을 친절한 Error 로 변환.
+ *
+ * - 표준 Apple JSON: `App Store API {status}: [CODE] detail @ pointer 💡 hint` 형식.
+ *   여러 errors 가 있으면 줄바꿈으로 나열.
+ * - 비표준 body: 기존 형식(`App Store API {status}: {body}`) 그대로 보존.
+ *
+ * `Error.cause` 에 원본 `{ status, body, parsedErrors }` 첨부 — 호출자가 코드별 분기 필요 시 사용.
+ */
+export declare function friendlyAppStoreError(status: number, body: string): Error;
+export declare const __testing: {
+    CODE_HINTS: Record<string, string>;
+    parseAppleErrorBody: typeof parseAppleErrorBody;
+    formatAppleError: typeof formatAppleError;
+};
+export {};

package/dist/appstore/errors.js

@@ -0,0 +1,88 @@
+/**
+ * App Store Connect API 에러 친절화.
+ *
+ * Apple은 표준 JSON 에러 응답을 내려준다:
+ *   { "errors": [{ "code": "...", "title": "...", "detail": "...",
+ *                  "source": { "pointer": "/data/attributes/whatsNew" } }] }
+ *
+ * 실제 거부 사례에서 자주 만나는 코드별 hint 를 첨가해
+ * "App Store API 409: { errors: [...] }" 같은 raw dump 대신
+ * 무엇을 고쳐야 하는지 즉시 보이게 한다.
+ *
+ * 비표준 body (HTML, plain text, 빈 응답 등) 는 폴백으로 원본 보존.
+ */
+/** Apple 에러 코드 → 친절한 hint (실측 거부 사례 기반). */
+const CODE_HINTS = {
+    // What's New / localization 텍스트 검증 실패
+    INVALID_CHARACTERS: 'HTML 태그·금지 문자가 포함됐어요. 제출 전 lib/text-validators.ts 로 사전 검증 권장.',
+    // 버전 상태가 편집 불가 (READY_FOR_SALE / WAITING_FOR_REVIEW 등)
+    ENTITY_STATE_INVALID: '버전 상태가 편집 가능 단계가 아니에요 (이미 심사중/출시됨). 새 versionString 으로 appstore_create_version 필요할 수 있어요.',
+    // 필수 필드 누락
+    ENTITY_ERROR_ATTRIBUTE_REQUIRED: '필수 필드가 빠졌어요 — source.pointer 위치 확인.',
+    // 길이 / 형식 위반
+    ENTITY_ERROR_ATTRIBUTE_INVALID: '필드 값이 정책 위반(길이/형식). source.pointer 위치 확인.',
+    // 빌드 attach 시 빌드를 못 찾음
+    NOT_FOUND: '대상 리소스를 찾을 수 없어요 — id/versionId/buildId 가 유효한지, 동일 앱 소속인지 확인.',
+    // 권한 부족 (API Key role 문제)
+    FORBIDDEN_ERROR: 'API Key 권한 부족 — App Store Connect > Users and Access 에서 키 role 확인.',
+    // submit 직후 cancel 시도 (큐 진입 후)
+    STATE_ERROR: '현재 상태에서 허용되지 않는 작업. cancel_review 라면 큐 진입 후라서 불가 — 새 versionString 으로 우회.',
+};
+/** Apple 표준 에러 응답 파싱 시도. 실패하면 null 반환. */
+function parseAppleErrorBody(body) {
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        if (Array.isArray(parsed?.errors) && parsed.errors.length > 0) {
+            return parsed.errors;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 단일 Apple error → 한 줄 사람용 표기. */
+function formatAppleError(e) {
+    const code = e.code ?? 'UNKNOWN';
+    const detail = e.detail ?? e.title ?? '(no detail)';
+    const pointer = e.source?.pointer ?? e.source?.parameter;
+    const hint = e.code ? CODE_HINTS[e.code] : undefined;
+    const parts = [`[${code}] ${detail}`];
+    if (pointer)
+        parts.push(`@ ${pointer}`);
+    if (hint)
+        parts.push(`\n  💡 ${hint}`);
+    return parts.join(' ');
+}
+/**
+ * App Store API 응답 (status + raw body) 을 친절한 Error 로 변환.
+ *
+ * - 표준 Apple JSON: `App Store API {status}: [CODE] detail @ pointer 💡 hint` 형식.
+ *   여러 errors 가 있으면 줄바꿈으로 나열.
+ * - 비표준 body: 기존 형식(`App Store API {status}: {body}`) 그대로 보존.
+ *
+ * `Error.cause` 에 원본 `{ status, body, parsedErrors }` 첨부 — 호출자가 코드별 분기 필요 시 사용.
+ */
+export function friendlyAppStoreError(status, body) {
+    const errors = parseAppleErrorBody(body);
+    let message;
+    if (errors) {
+        const formatted = errors.map(formatAppleError).join('\n');
+        message = `App Store API ${status}:\n${formatted}`;
+    }
+    else {
+        message = `App Store API ${status}: ${body}`;
+    }
+    const err = new Error(message);
+    // 원본 보존 — 호출자 코드별 retry 분기용.
+    err.cause = { status, body, parsedErrors: errors ?? undefined };
+    return err;
+}
+// ── 테스트용 export ────────────────────────────────────────────
+export const __testing = {
+    CODE_HINTS,
+    parseAppleErrorBody,
+    formatAppleError,
+};

package/dist/appstore/tools.d.ts

@@ -26,6 +26,29 @@ export declare function attachBuildToVersion(versionId: string, buildId: string)
     buildId: string;
     ok: boolean;
 }>;
+/**
+ * 가장 최신 VALID 빌드를 자동으로 찾아 versionId 에 attach.
+ *
+ * 흐름:
+ *   1. versionId → appId 역추적 (`getVersionAppAndPlatform`).
+ *   2. `listBuilds(appId)` 로 최근 10개 빌드 조회 (sort: uploadedDate desc).
+ *   3. `processingState === 'VALID'` 필터.
+ *   4. `minBuildNumber` 옵션 있으면 buildNumber 숫자 기준 필터.
+ *   5. buildNumber 숫자 최대값으로 정렬 → 1개 선택.
+ *   6. attach.
+ *
+ * 사용처: 1.4.x 같은 매 배포마다 `appstore_list_builds` → 수동 탐색 → `appstore_attach_build` 의
+ * 3-step 을 한 번에 줄임. 실수로 PROCESSING 중인 빌드를 attach 해서 심사 제출 시점에 깨지는
+ * 케이스도 차단.
+ */
+export declare function attachLatestValidBuild(versionId: string, opts?: {
+    minBuildNumber?: number;
+}): Promise<{
+    versionId: string;
+    attachedBuildId: string;
+    buildNumber: string;
+    uploadedDate?: string;
+}>;
 export declare function getVersionLocalizations(versionId: string): Promise<any>;
 export interface LocalizationUpdateFields {
     whatsNew?: string;
@@ -80,6 +103,31 @@ export interface ListCustomerReviewsOptions {
 }
 export declare function listCustomerReviews(appId: string, opts?: ListCustomerReviewsOptions): Promise<any>;
 export declare function createReviewResponse(reviewId: string, responseBody: string): Promise<any>;
+/**
+ * submit_for_review dry-run 프리뷰 — 비가역 제출 직전 사용자 확인용.
+ *
+ * 1.4.x 배포 사고 누적: submit 직후 cancel_review 가 큐 진입으로 막혀 새 versionString
+ * bump 으로 우회해야 하는 케이스가 반복됨 (reference_appstore_cancel_review_window).
+ * 호출자가 의도한 그 버전·빌드인지 미리 보여줘서 잘못된 versionId 제출 차단.
+ */
+export declare function buildSubmitForReviewPreview(versionId: string): Promise<{
+    versionId: string;
+    versionString?: string;
+    state?: string;
+    appId: string;
+    platform: string;
+    attachedBuild?: {
+        id: string;
+        buildNumber?: string;
+        uploadedDate?: string;
+        processingState?: string;
+    };
+    whatsNewByLocale: Array<{
+        locale: string;
+        excerpt: string;
+        length: number;
+    }>;
+}>;
 export declare function submitVersionForReview(versionId: string): Promise<{
     submissionId: string;
     appId: string;

package/dist/appstore/tools.js

@@ -1,4 +1,5 @@
 import { getAuthHeaders } from './auth.js';
+import { friendlyAppStoreError } from './errors.js';
 /**
  * App Store Connect API v1 래퍼
  * https://developer.apple.com/documentation/appstoreconnectapi
@@ -24,7 +25,7 @@ export async function apiGet(path, params) {
     const res = await fetch(url.toString(), { headers });
     if (!res.ok) {
         const body = await res.text();
-        throw new Error(`App Store API ${res.status}: ${body}`);
+        throw friendlyAppStoreError(res.status, body);
     }
     return res.json();
 }
@@ -44,7 +45,7 @@ async function apiPatch(path, body) {
     });
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`App Store API ${res.status}: ${text}`);
+        throw friendlyAppStoreError(res.status, text);
     }
     // 204 No Content 가능
     const text = await res.text();
@@ -66,7 +67,7 @@ async function apiPost(path, body) {
     });
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`App Store API ${res.status}: ${text}`);
+        throw friendlyAppStoreError(res.status, text);
     }
     // 201 Created — 본문에 created entity. 일부 엔드포인트는 204
     const text = await res.text();
@@ -147,6 +148,51 @@ export async function attachBuildToVersion(versionId, buildId) {
     });
     return { versionId, buildId, ok: true };
 }
+/**
+ * 가장 최신 VALID 빌드를 자동으로 찾아 versionId 에 attach.
+ *
+ * 흐름:
+ *   1. versionId → appId 역추적 (`getVersionAppAndPlatform`).
+ *   2. `listBuilds(appId)` 로 최근 10개 빌드 조회 (sort: uploadedDate desc).
+ *   3. `processingState === 'VALID'` 필터.
+ *   4. `minBuildNumber` 옵션 있으면 buildNumber 숫자 기준 필터.
+ *   5. buildNumber 숫자 최대값으로 정렬 → 1개 선택.
+ *   6. attach.
+ *
+ * 사용처: 1.4.x 같은 매 배포마다 `appstore_list_builds` → 수동 탐색 → `appstore_attach_build` 의
+ * 3-step 을 한 번에 줄임. 실수로 PROCESSING 중인 빌드를 attach 해서 심사 제출 시점에 깨지는
+ * 케이스도 차단.
+ */
+export async function attachLatestValidBuild(versionId, opts) {
+    const { appId } = await getVersionAppAndPlatform(versionId);
+    const builds = (await listBuilds(appId));
+    const valid = builds.filter((b) => b.processingState === 'VALID');
+    if (valid.length === 0) {
+        throw new Error(`appId=${appId} 에 VALID 빌드가 없어요 (최근 ${builds.length}개 확인). 빌드 PROCESSING 완료 대기 필요.`);
+    }
+    let candidates = valid;
+    if (opts?.minBuildNumber !== undefined) {
+        const min = opts.minBuildNumber;
+        candidates = valid.filter((b) => Number(b.version) >= min);
+        if (candidates.length === 0) {
+            throw new Error(`minBuildNumber=${min} 이상 VALID 빌드가 없어요. VALID 빌드: ${valid.map((b) => b.version).join(', ')}`);
+        }
+    }
+    // buildNumber 가 숫자 문자열이라는 가정 (TestFlight 표준). NaN 은 -Infinity 처리해 뒤로.
+    candidates.sort((a, b) => {
+        const an = Number(a.version);
+        const bn = Number(b.version);
+        return (isNaN(bn) ? -Infinity : bn) - (isNaN(an) ? -Infinity : an);
+    });
+    const target = candidates[0];
+    await attachBuildToVersion(versionId, target.id);
+    return {
+        versionId,
+        attachedBuildId: target.id,
+        buildNumber: target.version,
+        uploadedDate: target.uploadedDate,
+    };
+}
 // ─── 로컬라이제이션 (메타데이터) ───
 export async function getVersionLocalizations(versionId) {
     const data = await apiGet(`/appStoreVersions/${versionId}/appStoreVersionLocalizations`, {
@@ -426,6 +472,52 @@ async function isVersionAttached(submissionId, versionId) {
     const items = (data?.data ?? []);
     return items.some((it) => it?.relationships?.appStoreVersion?.data?.id === versionId);
 }
+/**
+ * submit_for_review dry-run 프리뷰 — 비가역 제출 직전 사용자 확인용.
+ *
+ * 1.4.x 배포 사고 누적: submit 직후 cancel_review 가 큐 진입으로 막혀 새 versionString
+ * bump 으로 우회해야 하는 케이스가 반복됨 (reference_appstore_cancel_review_window).
+ * 호출자가 의도한 그 버전·빌드인지 미리 보여줘서 잘못된 versionId 제출 차단.
+ */
+export async function buildSubmitForReviewPreview(versionId) {
+    const { appId, platform } = await getVersionAppAndPlatform(versionId);
+    // 버전 메타: versionString + state
+    const versionData = await apiGet(`/appStoreVersions/${versionId}`, {
+        'fields[appStoreVersions]': 'versionString,appStoreState',
+    }).catch(() => null);
+    const versionString = versionData?.data?.attributes?.versionString;
+    const state = versionData?.data?.attributes?.appStoreState;
+    // attached build
+    let attachedBuild;
+    const build = await apiGet(`/appStoreVersions/${versionId}/build`, {
+        'fields[builds]': 'version,uploadedDate,processingState',
+    }).catch(() => null);
+    if (build?.data?.id) {
+        attachedBuild = {
+            id: build.data.id,
+            buildNumber: build.data.attributes?.version,
+            uploadedDate: build.data.attributes?.uploadedDate,
+            processingState: build.data.attributes?.processingState,
+        };
+    }
+    const localizations = (await getVersionLocalizations(versionId).catch(() => []));
+    const whatsNewByLocale = localizations
+        .filter((l) => typeof l.whatsNew === 'string' && l.whatsNew.length > 0)
+        .map((l) => ({
+        locale: l.locale,
+        length: l.whatsNew.length,
+        excerpt: l.whatsNew.length > 200 ? `${l.whatsNew.slice(0, 200)}…` : l.whatsNew,
+    }));
+    return {
+        versionId,
+        versionString,
+        state,
+        appId,
+        platform,
+        attachedBuild,
+        whatsNewByLocale,
+    };
+}
 export async function submitVersionForReview(versionId) {
     const { appId, platform } = await getVersionAppAndPlatform(versionId);
     // 1. CREATED 상태의 reviewSubmission이 있으면 재사용, 없으면 새로 생성

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

@@ -0,0 +1,32 @@
+import { JWT } from 'google-auth-library';
+import type { OAuth2Client } from 'google-auth-library';
+export interface ServiceAccountKey {
+    type?: string;
+    client_email?: string;
+    private_key?: string;
+    project_id?: string;
+}
+/** 서비스 계정 키 JSON 문자열을 검증 후 저장. 형식이 아니면 throw. */
+export declare function saveBigQueryServiceAccountJson(json: string): ServiceAccountKey;
+/** 저장된 BigQuery 서비스 계정 키. 없거나 형식 오류면 null. */
+export declare function getBigQueryServiceAccountKey(): ServiceAccountKey | null;
+/** 저장된 BigQuery 서비스 계정 키 삭제. 없으면 false. */
+export declare function deleteBigQueryServiceAccountJson(): boolean;
+export type BigQueryAuthSource = 'service-account' | 'user-oauth';
+export interface BigQueryAuth {
+    client: OAuth2Client | JWT;
+    source: BigQueryAuthSource;
+    /** 서비스 계정이면 client_email, 사용자 OAuth면 null. */
+    clientEmail: string | null;
+    /** 서비스 계정 키의 project_id (있으면). */
+    projectId: string | null;
+}
+/**
+ * BigQuery 인증 클라이언트 해석. 우선순위:
+ *  1. BigQuery 서비스 계정 (~/.mimi-seed/bigquery-service-account.json)
+ *  2. 사용자 OAuth (~/.mimi-seed/tokens.json)
+ * 둘 다 없으면 null.
+ */
+export declare function resolveBigQueryAuth(): BigQueryAuth | null;
+/** BigQuery 인증을 강제. 없으면 안내 메시지와 함께 throw. */
+export declare function requireBigQueryAuth(): BigQueryAuth;

package/dist/auth/bigquery-auth.js

@@ -0,0 +1,100 @@
+import { JWT } from 'google-auth-library';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { getAuthenticatedClient } from './google-auth.js';
+// BigQuery 전용 서비스 계정 키 저장 위치.
+// 서비스 계정 인증은 Google Workspace 의 재인증(reauth) 정책에서 면제되므로,
+// 사용자 OAuth 가 `invalid_rapt` 로 갱신 거부되는 환경에서도 안정적으로 동작한다.
+const CONFIG_DIR = path.join(os.homedir(), '.mimi-seed');
+const BQ_SA_PATH = path.join(CONFIG_DIR, 'bigquery-service-account.json');
+// jobs.create(쿼리 작업 생성) + 데이터셋 읽기에 필요한 최소 스코프.
+const BQ_SCOPES = [
+    'https://www.googleapis.com/auth/bigquery.readonly',
+    'https://www.googleapis.com/auth/cloud-platform',
+];
+function safeReadSa(p) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (parsed.type === 'service_account' && parsed.client_email && parsed.private_key) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 서비스 계정 키 JSON 문자열을 검증 후 저장. 형식이 아니면 throw. */
+export function saveBigQueryServiceAccountJson(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new Error('JSON 파싱 실패 — 올바른 서비스 계정 키 파일이 아닙니다.');
+    }
+    if (parsed.type !== 'service_account' || !parsed.client_email || !parsed.private_key) {
+        throw new Error('서비스 계정 키 형식이 아닙니다 (type="service_account", client_email, private_key 필요).');
+    }
+    if (!fs.existsSync(CONFIG_DIR))
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(BQ_SA_PATH, json, { mode: 0o600 });
+    return parsed;
+}
+/** 저장된 BigQuery 서비스 계정 키. 없거나 형식 오류면 null. */
+export function getBigQueryServiceAccountKey() {
+    if (!fs.existsSync(BQ_SA_PATH))
+        return null;
+    return safeReadSa(BQ_SA_PATH);
+}
+/** 저장된 BigQuery 서비스 계정 키 삭제. 없으면 false. */
+export function deleteBigQueryServiceAccountJson() {
+    if (!fs.existsSync(BQ_SA_PATH))
+        return false;
+    fs.unlinkSync(BQ_SA_PATH);
+    return true;
+}
+function makeJwt(sa) {
+    return new JWT({ email: sa.client_email, key: sa.private_key, scopes: BQ_SCOPES });
+}
+/**
+ * BigQuery 인증 클라이언트 해석. 우선순위:
+ *  1. BigQuery 서비스 계정 (~/.mimi-seed/bigquery-service-account.json)
+ *  2. 사용자 OAuth (~/.mimi-seed/tokens.json)
+ * 둘 다 없으면 null.
+ */
+export function resolveBigQueryAuth() {
+    const sa = getBigQueryServiceAccountKey();
+    if (sa) {
+        return {
+            client: makeJwt(sa),
+            source: 'service-account',
+            clientEmail: sa.client_email ?? null,
+            projectId: sa.project_id ?? null,
+        };
+    }
+    const oauth = getAuthenticatedClient();
+    if (oauth) {
+        return { client: oauth, source: 'user-oauth', clientEmail: null, projectId: null };
+    }
+    return null;
+}
+const BQ_AUTH_HINT = [
+    '❌ BigQuery 인증이 설정되지 않았어.',
+    '',
+    '방법 1 — 서비스 계정 (권장: Google Workspace 재인증 정책의 영향을 받지 않음):',
+    '  npx -y @yoonion/mimi-seed-mcp mimi-seed-bigquery-auth',
+    '',
+    '방법 2 — Google 계정 OAuth:',
+    '  npx -y @yoonion/mimi-seed-mcp mimi-seed-auth',
+    '',
+    '그 다음에 다시 물어봐줘.',
+].join('\n');
+/** BigQuery 인증을 강제. 없으면 안내 메시지와 함께 throw. */
+export function requireBigQueryAuth() {
+    const auth = resolveBigQueryAuth();
+    if (!auth)
+        throw new Error(BQ_AUTH_HINT);
+    return auth;
+}

package/dist/auth/bigquery-setup-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/auth/bigquery-setup-cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import readline from 'node:readline';
+import fs from 'node:fs';
+import { saveBigQueryServiceAccountJson, getBigQueryServiceAccountKey, } from './bigquery-auth.js';
+import * as bigquery from '../bigquery/tools.js';
+import { JWT } from 'google-auth-library';
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+const ask = (q) => new Promise((r) => rl.question(q, r));
+async function main() {
+    console.log('');
+    console.log('  🤖 Mimi Seed — BigQuery 서비스 계정 연결');
+    console.log('');
+    console.log('  서비스 계정 인증은 Google Workspace 의 재인증(reauth) 정책에서');
+    console.log('  면제되므로, OAuth 가 invalid_rapt 로 막히는 환경에서도 동작해.');
+    console.log('');
+    const existing = getBigQueryServiceAccountKey();
+    if (existing) {
+        console.log(`  ✅ 이미 연결됨 (${existing.client_email})`);
+        const answer = await ask('  다시 설정할래? (y/N): ');
+        if (answer.toLowerCase() !== 'y') {
+            rl.close();
+            return;
+        }
+    }
+    console.log('  BigQuery 를 읽을 수 있는 서비스 계정 키 JSON 이 필요해:');
+    console.log('  1. GCP Console → IAM & Admin → Service Accounts');
+    console.log('  2. 서비스 계정 선택(또는 생성) → Keys → Add Key → JSON');
+    console.log('  3. 그 서비스 계정에 프로젝트 IAM 역할 부여:');
+    console.log('     • roles/bigquery.jobUser    (쿼리 작업 생성)');
+    console.log('     • roles/bigquery.dataViewer (데이터셋 읽기)');
+    console.log('  4. 다운로드한 JSON 파일 경로를 입력해');
+    console.log('');
+    const jsonPath = await ask('  서비스 계정 JSON 파일 경로: ');
+    const trimmedPath = jsonPath.trim().replace(/^["']|["']$/g, '');
+    if (!fs.existsSync(trimmedPath)) {
+        console.log(`  ❌ 파일 없음: ${trimmedPath}`);
+        rl.close();
+        process.exit(1);
+    }
+    const json = fs.readFileSync(trimmedPath, 'utf-8');
+    let parsed;
+    try {
+        parsed = saveBigQueryServiceAccountJson(json);
+    }
+    catch (e) {
+        console.log(`  ❌ ${e instanceof Error ? e.message : String(e)}`);
+        rl.close();
+        process.exit(1);
+    }
+    console.log('');
+    console.log(`  ✅ 저장 완료! (${parsed.client_email})`);
+    if (parsed.project_id)
+        console.log(`     서비스 계정 프로젝트: ${parsed.project_id}`);
+    console.log('');
+    // 선택적 연결 테스트 — projectId 를 입력하면 datasets.list 로 권한 확인.
+    const testProject = await ask(`  연결 테스트할 GCP 프로젝트 ID (엔터 시 건너뜀${parsed.project_id ? `, 기본 ${parsed.project_id}` : ''}): `);
+    const projectId = testProject.trim() || parsed.project_id || '';
+    if (projectId) {
+        console.log(`  🔎 ${projectId} 데이터셋 조회 중...`);
+        try {
+            const jwt = new JWT({
+                email: parsed.client_email,
+                key: parsed.private_key,
+                scopes: [
+                    'https://www.googleapis.com/auth/bigquery.readonly',
+                    'https://www.googleapis.com/auth/cloud-platform',
+                ],
+            });
+            const datasets = await bigquery.listDatasets(jwt, projectId);
+            console.log(`  ✅ 접근 OK — 데이터셋 ${datasets.length}개`);
+            for (const d of datasets.slice(0, 10))
+                console.log(`     • ${d.datasetId} (${d.location})`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.log(`  ⚠️  접근 실패: ${msg}`);
+            console.log('');
+            console.log('  IAM 역할이 없으면 아래를 실행해 (프로젝트 소유자 계정에서):');
+            console.log(`    gcloud projects add-iam-policy-binding ${projectId} \\`);
+            console.log(`      --member="serviceAccount:${parsed.client_email}" --role="roles/bigquery.jobUser"`);
+            console.log(`    gcloud projects add-iam-policy-binding ${projectId} \\`);
+            console.log(`      --member="serviceAccount:${parsed.client_email}" --role="roles/bigquery.dataViewer"`);
+        }
+    }
+    console.log('');
+    console.log('  이제 Claude Code 에서:');
+    console.log('    "BigQuery 로 GA4 트래픽 분석해줘"');
+    console.log('');
+    rl.close();
+}
+main();

package/dist/auth/errors.d.ts

@@ -1,4 +1,4 @@
-export type AuthErrorCode = 'UNAUTHENTICATED' | 'NO_REFRESH_TOKEN' | 'INVALID_GRANT' | 'INVALID_CLIENT' | 'UNAUTHORIZED_CLIENT' | 'REFRESH_NETWORK_ERROR' | 'REFRESH_UNKNOWN' | 'CALLBACK_PORT_IN_USE' | 'CALLBACK_TIMEOUT' | 'BROWSER_OPEN_FAILED' | 'USER_DENIED' | 'CODE_EXCHANGE_FAILED' | 'TOKEN_RESPONSE_INVALID';
+export type AuthErrorCode = 'UNAUTHENTICATED' | 'NO_REFRESH_TOKEN' | 'INVALID_GRANT' | 'RAPT_REQUIRED' | 'INVALID_CLIENT' | 'UNAUTHORIZED_CLIENT' | 'REFRESH_NETWORK_ERROR' | 'REFRESH_UNKNOWN' | 'CALLBACK_PORT_IN_USE' | 'CALLBACK_TIMEOUT' | 'BROWSER_OPEN_FAILED' | 'USER_DENIED' | 'CODE_EXCHANGE_FAILED' | 'TOKEN_RESPONSE_INVALID';
 export interface AuthErrorPayload {
     code: AuthErrorCode;
     message: string;

package/dist/auth/errors.js

@@ -28,6 +28,17 @@ export function classifyError(e, ctx) {
             cause: raw,
         };
     }
+    if (oauthCode === 'invalid_rapt' || oauthCode === 'rapt_required') {
+        return {
+            code: 'RAPT_REQUIRED',
+            message: 'Google Workspace 재인증(reauth) 정책으로 토큰 갱신이 거부되었습니다 (invalid_rapt).',
+            hint: 'mimi-seed-auth 로 재로그인하거나, 재인증 정책의 영향을 받지 않는 서비스 계정 인증을 사용하세요 ' +
+                '(BigQuery: mimi-seed-bigquery-auth).',
+            retriable: false,
+            needsReauth: true,
+            cause: raw,
+        };
+    }
     if (oauthCode === 'invalid_client') {
         return {
             code: 'INVALID_CLIENT',
@@ -128,7 +139,7 @@ function extractOAuthErrorCode(e, raw) {
             return dataErr;
     }
     // message에 'invalid_grant' 같은 표준 코드가 박혀 있는 경우
-    const m = raw.match(/\b(invalid_grant|invalid_client|invalid_request|unauthorized_client|access_denied|unsupported_grant_type)\b/);
+    const m = raw.match(/\b(invalid_grant|invalid_client|invalid_request|unauthorized_client|access_denied|unsupported_grant_type|invalid_rapt|rapt_required)\b/);
     return m?.[1];
 }
 function isNetworkError(e, raw) {

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

@@ -11,6 +11,13 @@ export declare function getStoredCredentials(): {
 } | null;
 export declare function saveCredentials(clientId: string, clientSecret: string): void;
 export declare function getStoredTokens(): StoredTokens | null;
+/**
+ * tokens.json mtime — 마지막 refresh 시각의 근사값.
+ * (saveTokens 가 매번 writeFileSync 으로 갱신하므로 mtime ≈ 마지막 갱신/저장.)
+ * Google refresh_token 은 7일(미인증 앱) ~ 6개월(인증 앱) 미사용 시 revoke 됨.
+ * auth_status 응답 enrichment 에 사용.
+ */
+export declare function getTokensLastRefreshMs(): number | null;
 export declare function createOAuth2Client(clientId: string, clientSecret: string): import("google-auth-library").OAuth2Client;
 /**
  * Get authenticated OAuth2 client.
@@ -59,4 +66,9 @@ export type RefreshStatus = {
  *
  * MCP 도구와 CLI 양쪽에서 공유.
  */
+/**
+ * 사전 갱신 마진. 기존 60_000(1분)에서 300_000(5분)으로 상향 — Google OAuth access_token 의
+ * 통상 lifetime 이 1h 이므로, 5분 마진으로 매 도구 호출 시 만료 임박 시 사전 갱신해
+ * "토큰 만료 → 도구 fail → 재호출" 의 단절 마찰 제거. 5분 마진은 평균 도구 작업 시간을 흡수.
+ */
 export declare function ensureFreshAccessToken(marginMs?: number): Promise<RefreshStatus>;