@yoonion/mimi-seed-mcp 0.13.12 → 0.13.14

package/dist/appstore/errors.js

@@ -34,8 +34,11 @@ const CODE_HINTS = {
     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 으로 우회.',
+    // 상태 전이 거부. cancel 은 WAITING_FOR_REVIEW 까지 되고, IN_REVIEW 이후만 막힌다.
+    // (예전 문구는 "큐 진입 후라 불가"였는데, 그건 cancel 이 submitted:false 를 보내
+    //  항상 실패하던 버그의 증상을 상태 탓으로 오해한 것이었다 — 2026-07-25 정정.)
+    STATE_ERROR: '현재 상태에서 허용되지 않는 작업. 제출된 묶음은 항목 제거(removed)가 막히니 '
+        + 'appstore_cancel_review 로 묶음째 취소하세요. IN_REVIEW 이후면 그마저도 불가 — 심사 결과를 기다립니다.',
     // JWT 거부 — 잘못된 자격증명
     NOT_AUTHORIZED: 'API 키가 거부됐어요 — issuerId/keyId/.p8 조합 불일치 가능. appstore_verify_credentials 로 진단하고 mimi-seed auth appstore 로 재등록.',
 };

package/dist/appstore/product-review.d.ts

@@ -12,12 +12,15 @@ export declare function updateProductReviewNote(args: {
 }>;
 /**
  * 기존 IAP/구독 상품에 App Review 스크린샷을 reserve → upload → commit 한다.
- * App Store Connect API는 상품당 심사용 스크린샷 하나를 허용한다.
+ * App Store Connect API는 상품당 심사용 스크린샷 하나를 허용한다 —
+ * 이미 있으면 409 `MEDIA_ASSET_CREATION_NOT_ALLOWED: Screenshot already exists` 다.
+ * 갈아끼우려면 replace: true (기존 것을 지우고 올린다).
  */
 export declare function uploadProductReviewScreenshot(args: {
     internalId: string;
     productType: AppStoreProductType;
     filePath: string;
+    replace?: boolean;
 }): Promise<{
     id: string;
     internalId: string;
@@ -26,4 +29,5 @@ export declare function uploadProductReviewScreenshot(args: {
     fileSize: number;
     state?: string;
     verified: boolean;
+    replacedId?: string;
 }>;

package/dist/appstore/product-review.js

@@ -70,12 +70,31 @@ async function uploadChunks(buffer, operations) {
         }
     }
 }
+/**
+ * 상품에 이미 붙어 있는 심사 스크린샷 id 를 찾는다. 없으면 null.
+ *
+ * 조회 경로가 상품 종류마다 다르다 — 구독은 v1, IAP 는 **v2** 다.
+ * v1 으로 IAP 를 조회하면 스크린샷이 있어도 404 가 나서 "없음"으로 오독하기 쉽다
+ * (2026-07-25 실측: 404 를 믿고 업로드했다가 "Screenshot already exists" 409).
+ */
+async function findExistingReviewScreenshotId(internalId, productType, authHeaders) {
+    const product = productResource(productType);
+    try {
+        const res = await apiRequest(product.base, `${product.path}/${internalId}/appStoreReviewScreenshot`, authHeaders, { method: 'GET' });
+        return res?.data?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * 기존 IAP/구독 상품에 App Review 스크린샷을 reserve → upload → commit 한다.
- * App Store Connect API는 상품당 심사용 스크린샷 하나를 허용한다.
+ * App Store Connect API는 상품당 심사용 스크린샷 하나를 허용한다 —
+ * 이미 있으면 409 `MEDIA_ASSET_CREATION_NOT_ALLOWED: Screenshot already exists` 다.
+ * 갈아끼우려면 replace: true (기존 것을 지우고 올린다).
  */
 export async function uploadProductReviewScreenshot(args) {
-    const { internalId, productType, filePath } = args;
+    const { internalId, productType, filePath, replace = false } = args;
     if (!path.isAbsolute(filePath)) {
         throw new Error(`절대 경로가 필요해: ${filePath}`);
     }
@@ -94,6 +113,15 @@ export async function uploadProductReviewScreenshot(args) {
     const checksum = crypto.createHash('md5').update(buffer).digest('hex');
     const resource = reviewScreenshotResource(productType);
     const authHeaders = await authHeadersOrThrow();
+    // 상품당 1장이라 새로 올리려면 기존 것을 먼저 지워야 한다.
+    let replacedId;
+    if (replace) {
+        const existing = await findExistingReviewScreenshotId(internalId, productType, authHeaders);
+        if (existing) {
+            await apiRequest(V1_BASE, `${resource.path}/${existing}`, authHeaders, { method: 'DELETE' });
+            replacedId = existing;
+        }
+    }
     const reserved = await apiRequest(V1_BASE, resource.path, authHeaders, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -148,5 +176,5 @@ export async function uploadProductReviewScreenshot(args) {
     catch {
         // commit 성공 후 확인 GET만 실패하면 재업로드를 유도하지 않는다.
     }
-    return { id: screenshotId, internalId, productType, fileName, fileSize, state, verified };
+    return { id: screenshotId, internalId, productType, fileName, fileSize, state, verified, replacedId };
 }

package/dist/appstore/tools.d.ts

@@ -40,6 +40,23 @@ export declare function createVersion(input: CreateVersionInput): Promise<{
     releaseType: any;
     createdDate: any;
 }>;
+/**
+ * 기존 버전 레코드의 versionString 을 바꾼다 (예: 2.0.5 → 2.0.6).
+ *
+ * 왜 필요한가: ASC 는 편집 가능한 버전이 이미 있으면 새 버전 생성을 거부한다
+ *   409 ENTITY_ERROR.RELATIONSHIP.INVALID "You cannot create a new version of the App in the current state"
+ * 그래서 거절/철회된 버전으로 다음 릴리스를 내보내려면 **같은 레코드의 이름을 올려야** 한다.
+ * 빌드는 CFBundleShortVersionString 이 일치하는 버전에만 붙으므로, 2.0.6 빌드를 올렸다면
+ * 버전 레코드도 2.0.6 이어야 attach 가 된다.
+ *
+ * 편집 가능한 상태(PREPARE_FOR_SUBMISSION / DEVELOPER_REJECTED / REJECTED 등)에서만 통한다.
+ */
+export declare function updateVersionString(versionId: string, versionString: string): Promise<{
+    versionId: string;
+    versionString: any;
+    state: any;
+    platform: any;
+}>;
 export declare function attachBuildToVersion(versionId: string, buildId: string): Promise<{
     versionId: string;
     buildId: string;
@@ -137,9 +154,11 @@ export declare function createReviewResponse(reviewId: string, responseBody: str
 /**
  * submit_for_review dry-run 프리뷰 — 비가역 제출 직전 사용자 확인용.
  *
- * 1.4.x 배포 사고 누적: submit 직후 cancel_review 가 큐 진입으로 막혀 새 versionString
- * bump 으로 우회해야 하는 케이스가 반복됨 (reference_appstore_cancel_review_window).
- * 호출자가 의도한 그 버전·빌드인지 미리 보여줘서 잘못된 versionId 제출 차단.
+ * 1.4.x 배포 사고 누적: submit 직후 되돌리지 못해 새 versionString bump 으로 우회해야
+ * 하는 케이스가 반복됨 (reference_appstore_cancel_review_window). 그 원인이던
+ * cancel_review 버그(submitted:false → 항상 409)는 2026-07-25 에 canceled:true 로 고쳤고,
+ * 이제 WAITING_FOR_REVIEW 까지는 되돌릴 수 있다. 그래도 IN_REVIEW 이후는 못 되돌리니
+ * 호출자가 의도한 그 버전·빌드인지 미리 보여줘서 잘못된 versionId 제출을 차단한다.
  */
 export declare function buildSubmitForReviewPreview(versionId: string): Promise<{
     versionId: string;
@@ -189,6 +208,10 @@ export interface ReviewSubmissionSummary {
         targetId?: string;
         versionString?: string;
         appVersionState?: string;
+        /** IAP/구독/구독그룹 항목의 식별자 — productId 또는 referenceName. */
+        label?: string;
+        /** 대상 리소스 자체의 상태 (상품이면 READY_TO_SUBMIT / WAITING_FOR_REVIEW 등). */
+        targetState?: string;
     }>;
 }
 export declare function listReviewSubmissions(args: {
@@ -206,6 +229,30 @@ export declare function removeReviewSubmissionItem(itemId: string): Promise<{
     state?: string;
     removed: boolean;
 }>;
+/**
+ * 이미 존재하는 묶음에 앱 버전을 항목으로 끼워 넣는다.
+ *
+ * 앱 첫 심사에서 반드시 필요하다. 웹에서 상품을 담으면 **상품만 든 묶음**이 새로 생기는데,
+ * 그대로 제출하면 Apple 이 막는다:
+ *   409 ENTITY_ERROR.RELATIONSHIP.REQUIRED
+ *   "must have an approved appStoreVersions ... or an appStoreVersions must be included
+ *    in this review submission"
+ * 즉 상품 묶음에는 앱 버전이 함께 있어야 한다. reviewSubmissionItems 는 상품 관계는
+ * 거부하지만 **appStoreVersion 관계는 받는다** — 그래서 버전만 이쪽으로 옮기면 된다.
+ *
+ * 버전이 다른 묶음에 이미 물려 있으면 그 묶음을 먼저 정리해야 한다:
+ *   - 미제출(READY_FOR_REVIEW) 묶음이면 appstore_remove_review_submission_item
+ *   - 제출된(WAITING_FOR_REVIEW) 묶음이면 항목 제거가 막히므로 appstore_cancel_review 로 묶음째 취소
+ */
+export declare function addVersionToReviewSubmission(args: {
+    submissionId: string;
+    versionId: string;
+}): Promise<{
+    itemId?: string;
+    submissionId: string;
+    versionId: string;
+    itemCount: number;
+}>;
 export declare function cancelVersionReview(versionId: string): Promise<{
     submissionId: string;
     previousState: string;

package/dist/appstore/tools.js

@@ -196,6 +196,33 @@ export async function createVersion(input) {
         createdDate: created?.data?.attributes?.createdDate,
     };
 }
+/**
+ * 기존 버전 레코드의 versionString 을 바꾼다 (예: 2.0.5 → 2.0.6).
+ *
+ * 왜 필요한가: ASC 는 편집 가능한 버전이 이미 있으면 새 버전 생성을 거부한다
+ *   409 ENTITY_ERROR.RELATIONSHIP.INVALID "You cannot create a new version of the App in the current state"
+ * 그래서 거절/철회된 버전으로 다음 릴리스를 내보내려면 **같은 레코드의 이름을 올려야** 한다.
+ * 빌드는 CFBundleShortVersionString 이 일치하는 버전에만 붙으므로, 2.0.6 빌드를 올렸다면
+ * 버전 레코드도 2.0.6 이어야 attach 가 된다.
+ *
+ * 편집 가능한 상태(PREPARE_FOR_SUBMISSION / DEVELOPER_REJECTED / REJECTED 등)에서만 통한다.
+ */
+export async function updateVersionString(versionId, versionString) {
+    const patched = await apiPatch(`/appStoreVersions/${versionId}`, {
+        data: {
+            type: 'appStoreVersions',
+            id: versionId,
+            attributes: { versionString },
+        },
+    });
+    const attrs = patched?.data?.attributes ?? {};
+    return {
+        versionId,
+        versionString: attrs.versionString ?? versionString,
+        state: attrs.appStoreState ?? attrs.appVersionState,
+        platform: attrs.platform,
+    };
+}
 export async function attachBuildToVersion(versionId, buildId) {
     // /relationships/build 엔드포인트는 204 No Content 반환
     await apiPatch(`/appStoreVersions/${versionId}/relationships/build`, {
@@ -556,9 +583,11 @@ async function isVersionAttached(submissionId, versionId) {
 /**
  * submit_for_review dry-run 프리뷰 — 비가역 제출 직전 사용자 확인용.
  *
- * 1.4.x 배포 사고 누적: submit 직후 cancel_review 가 큐 진입으로 막혀 새 versionString
- * bump 으로 우회해야 하는 케이스가 반복됨 (reference_appstore_cancel_review_window).
- * 호출자가 의도한 그 버전·빌드인지 미리 보여줘서 잘못된 versionId 제출 차단.
+ * 1.4.x 배포 사고 누적: submit 직후 되돌리지 못해 새 versionString bump 으로 우회해야
+ * 하는 케이스가 반복됨 (reference_appstore_cancel_review_window). 그 원인이던
+ * cancel_review 버그(submitted:false → 항상 409)는 2026-07-25 에 canceled:true 로 고쳤고,
+ * 이제 WAITING_FOR_REVIEW 까지는 되돌릴 수 있다. 그래도 IN_REVIEW 이후는 못 되돌리니
+ * 호출자가 의도한 그 버전·빌드인지 미리 보여줘서 잘못된 versionId 제출을 차단한다.
  */
 export async function buildSubmitForReviewPreview(versionId) {
     const { appId, platform } = await getVersionAppAndPlatform(versionId);
@@ -742,10 +771,21 @@ export async function addProductToReviewSubmission(args) {
         const enriched = new Error([
             `상품 ${internalId} (${productType}) 은 API 로 심사 제출할 수 없는 상태야 — Apple 응답: "no pending version for submission".`,
             '',
-            '이건 보통 **앱 첫 심사** 케이스다. 한 번도 승인된 적 없는 상품은 공개 API 로 심사에 못 넣고,',
-            'App Store Connect 웹의 해당 버전 페이지 → "앱 내 구입 및 구독" 섹션에서 상품을 선택해',
-            '버전과 같은 묶음으로 제출해야 한다 (reviewSubmissionItems 는 상품 관계를 받지 않는다 — 2026-07 실측).',
-            '버전이 이미 심사 대기 중이면 appstore_cancel_review 로 내린 뒤 웹에서 담고 재제출한다.',
+            '**앱 첫 심사** 케이스다. 한 번도 승인된 적 없는 상품은 공개 API 로 심사에 못 넣는다.',
+            '앱 버전을 심사 대기로 만들어도 이 벽은 그대로다 (2026-07-25 재확인).',
+            '',
+            '실제로 통하는 순서 (PenguinRun 2.0.6 실측):',
+            '  1. appstore_submit_for_review 로 앱 버전을 먼저 제출한다.',
+            '     → 상품은 자동으로 안 딸려간다. 버전 1개짜리 묶음 A 가 생긴다. 이건 정상이다.',
+            '  2. 그래야 ASC 웹에 상품의 "심사 추가" UI 가 나타난다. 웹에서 상품을 담으면',
+            '     상품들만 든 **새 묶음 B** 가 READY_FOR_REVIEW(미제출)로 생성된다.',
+            '  3. B 를 그냥 제출하면 409: "an appStoreVersions must be included in this review submission".',
+            '     상품 묶음에는 앱 버전이 반드시 함께 있어야 한다.',
+            '  4. appstore_cancel_review 로 묶음 A 를 취소해 버전을 풀어준다.',
+            '  5. POST /reviewSubmissionItems 로 B 에 appStoreVersion 을 추가한다.',
+            '     (상품 관계는 거부되지만 **버전 관계는 받는다**.)',
+            '  6. B 를 submitted=true 로 PATCH → 버전+상품이 한 묶음으로 제출된다.',
+            '',
             '이미 승인된 적 있는 상품이라면: 변경분(pending version)이 실제로 있는지 확인.',
         ].join('\n'));
         enriched.cause = error.cause;
@@ -779,22 +819,30 @@ export async function listReviewSubmissions(args) {
     const submissions = (data?.data ?? []);
     const result = [];
     for (const sub of submissions) {
+        // 버전만 include 하면 IAP·구독·구독그룹 항목이 전부 "?" 로 남아, 정작 중요한
+        // "이 묶음에 상품이 들어갔나"를 이 도구로 판별할 수 없었다 (2026-07-25 실측).
         const itemsData = await apiGet(`/reviewSubmissions/${sub.id}/items`, {
-            include: 'appStoreVersion',
+            include: 'appStoreVersion,inAppPurchaseV2,subscription,subscriptionGroup',
             'fields[appStoreVersions]': 'versionString,appVersionState',
+            'fields[inAppPurchases]': 'productId,name,state',
+            'fields[subscriptions]': 'productId,name,state',
+            'fields[subscriptionGroups]': 'referenceName',
             limit: '50',
         }).catch(() => null);
         const included = new Map((itemsData?.included ?? []).map((inc) => [`${inc.type}:${inc.id}`, inc]));
         const items = (itemsData?.data ?? []).map((item) => {
             const target = Object.entries(item.relationships ?? {}).find(([key, rel]) => key !== 'reviewSubmission' && rel?.data?.id)?.[1]?.data;
             const inc = target?.type && target.id ? included.get(`${target.type}:${target.id}`) : undefined;
+            const a = inc?.attributes;
             return {
                 id: item.id,
                 state: item.attributes?.state,
                 targetType: target?.type,
                 targetId: target?.id,
-                versionString: inc?.attributes?.versionString,
-                appVersionState: inc?.attributes?.appVersionState,
+                versionString: a?.versionString,
+                appVersionState: a?.appVersionState,
+                label: a?.productId ?? a?.referenceName ?? a?.name,
+                targetState: a?.state,
             };
         });
         result.push({
@@ -817,6 +865,41 @@ export async function removeReviewSubmissionItem(itemId) {
         removed: patched?.data?.attributes?.removed ?? true,
     };
 }
+/**
+ * 이미 존재하는 묶음에 앱 버전을 항목으로 끼워 넣는다.
+ *
+ * 앱 첫 심사에서 반드시 필요하다. 웹에서 상품을 담으면 **상품만 든 묶음**이 새로 생기는데,
+ * 그대로 제출하면 Apple 이 막는다:
+ *   409 ENTITY_ERROR.RELATIONSHIP.REQUIRED
+ *   "must have an approved appStoreVersions ... or an appStoreVersions must be included
+ *    in this review submission"
+ * 즉 상품 묶음에는 앱 버전이 함께 있어야 한다. reviewSubmissionItems 는 상품 관계는
+ * 거부하지만 **appStoreVersion 관계는 받는다** — 그래서 버전만 이쪽으로 옮기면 된다.
+ *
+ * 버전이 다른 묶음에 이미 물려 있으면 그 묶음을 먼저 정리해야 한다:
+ *   - 미제출(READY_FOR_REVIEW) 묶음이면 appstore_remove_review_submission_item
+ *   - 제출된(WAITING_FOR_REVIEW) 묶음이면 항목 제거가 막히므로 appstore_cancel_review 로 묶음째 취소
+ */
+export async function addVersionToReviewSubmission(args) {
+    const { submissionId, versionId } = args;
+    const created = await apiPost('/reviewSubmissionItems', {
+        data: {
+            type: 'reviewSubmissionItems',
+            relationships: {
+                reviewSubmission: { data: { type: 'reviewSubmissions', id: submissionId } },
+                appStoreVersion: { data: { type: 'appStoreVersions', id: versionId } },
+            },
+        },
+    });
+    // 제출 전에 몇 개가 들어있는지 보여준다 — 첫 심사에서 "상품이 빠졌는지"를 눈으로 확인해야 한다.
+    const items = await apiGet(`/reviewSubmissions/${submissionId}/items`, { limit: '50' }).catch(() => null);
+    return {
+        itemId: created?.data?.id,
+        submissionId,
+        versionId,
+        itemCount: (items?.data ?? []).length,
+    };
+}
 /**
  * 버전을 물고 있는 낡은 묶음(UNRESOLVED_ISSUES)에서 해당 버전 항목을 removed=true 로
  * 풀어준다. 항목이 풀리면 Apple 이 옛 묶음을 COMPLETE 로 정리하고, 종종 새
@@ -846,7 +929,7 @@ async function releaseVersionFromStaleSubmissions(appId, platform, versionId) {
 // ─── 심사 철회 (Cancel Review) ───
 // WAITING_FOR_REVIEW 상태의 reviewSubmission에만 적용 가능.
 // IN_REVIEW 진입 후에는 Apple API가 거부함 (409).
-// submitted=false PATCH → version이 PREPARE_FOR_SUBMISSION으로 복귀.
+// PATCH attributes.canceled=true → state CANCELING → COMPLETE, version 은 편집 가능 상태로 복귀.
 export async function cancelVersionReview(versionId) {
     const { appId, platform } = await getVersionAppAndPlatform(versionId);
     // 취소 가능한 상태(WAITING_FOR_REVIEW)의 submission 검색
@@ -866,15 +949,21 @@ export async function cancelVersionReview(versionId) {
     }
     const submissionId = submission.id;
     const previousState = submission.attributes?.state ?? 'WAITING_FOR_REVIEW';
-    // submitted=false → WAITING_FOR_REVIEW → READY_FOR_REVIEW (version은 PREPARE_FOR_SUBMISSION으로 복귀)
+    // 취소 속성은 canceled 다. submitted:false 는 Apple 이 거부한다:
+    //   409 ENTITY_ERROR.ATTRIBUTE.INVALID "submitted must be set to true if present"
+    // 예전 구현이 submitted:false 를 보내서 이 도구는 사실상 항상 실패했고, 그 탓에
+    // "큐 진입 후에는 웹에서만 취소 가능" 이라는 잘못된 통설이 굳어 있었다.
+    // 실제로는 WAITING_FOR_REVIEW 에서도 canceled:true 가 통한다 (2026-07-25 실측):
+    //   200 → state: CANCELING → (수십 초) → COMPLETE, 항목은 REMOVED, 버전은 편집 가능 복귀.
     const patched = await apiPatch(`/reviewSubmissions/${submissionId}`, {
         data: {
             type: 'reviewSubmissions',
             id: submissionId,
-            attributes: { submitted: false },
+            attributes: { canceled: true },
         },
     });
-    const newState = patched?.data?.attributes?.state ?? 'READY_FOR_REVIEW';
+    // CANCELING 은 비동기다 — 호출 직후엔 아직 COMPLETE 가 아니다.
+    const newState = patched?.data?.attributes?.state ?? 'CANCELING';
     return { submissionId, previousState, newState, versionId };
 }
 // ─── 인앱 구매 (IAP) 생성 ───

package/dist/playstore/tools.d.ts

@@ -22,7 +22,11 @@ export interface PlayStatisticsQuery {
     userCohort?: 'OS_PUBLIC' | 'APP_TESTERS' | 'OS_BETA';
     timeZone?: string;
 }
-export declare function withEdit<T>(auth: OAuth2Client | JWT, packageName: string, fn: (editId: string) => Promise<T>, commit?: boolean): Promise<T>;
+export interface EditCommitInfo {
+    /** true 면 커밋은 됐지만 심사 전송은 Play Console 에서 사람이 눌러야 한다. */
+    changesNotSentForReview: boolean;
+}
+export declare function withEdit<T>(auth: OAuth2Client | JWT, packageName: string, fn: (editId: string) => Promise<T>, commit?: boolean, onCommit?: (info: EditCommitInfo) => void): Promise<T>;
 export declare function getStatistics(auth: OAuth2Client | JWT, packageName: string, query: PlayStatisticsQuery): Promise<unknown>;
 export declare function getAppDetails(auth: OAuth2Client | JWT, packageName: string): Promise<import("googleapis/build/src/apis/androidpublisher/v3.js").androidpublisher_v3.Schema$AppDetails>;
 export declare function updateAppDetails(auth: OAuth2Client | JWT, packageName: string, data: {
@@ -95,6 +99,9 @@ export interface PromoteReleaseOptions {
     copyReleaseNotes?: boolean;
 }
 export declare function promoteRelease(auth: OAuth2Client | JWT, packageName: string, fromTrack: string, toTrack: string, versionCode: string, options?: PromoteReleaseOptions): Promise<{
+    changesNotSentForReview: boolean;
+    nextAction: string | undefined;
+    warnings: string[] | undefined;
     packageName: string;
     fromTrack: string;
     toTrack: string;

package/dist/playstore/tools.js

@@ -41,7 +41,26 @@ function dateToReportingDateTime(date, timeZone) {
         timeZone: { id: timeZone },
     };
 }
-export async function withEdit(auth, packageName, fn, commit = false) {
+// Play 는 앱/계정 상태에 따라 "커밋과 동시에 심사 전송"을 거부한다:
+//   Changes cannot be sent for review automatically.
+//   Please set the query parameter changesNotSentForReview to true.
+// 이 경우 그 파라미터를 붙여야만 커밋이 통과한다. 예전 구현은 파라미터를 노출하지도,
+// 폴백하지도 않아서 그런 앱에서는 promote/submit 계열이 **100% 실패**했다
+// (PenguinRun 2026-07-25 실측 — 결국 Android Publisher API 를 직접 쳐서 우회해야 했다).
+async function commitEdit(auth, packageName, editId) {
+    try {
+        await publisher().edits.commit({ auth, packageName, editId });
+        return { changesNotSentForReview: false };
+    }
+    catch (err) {
+        const msg = String(err?.message ?? err);
+        if (!/changesNotSentForReview/i.test(msg))
+            throw err;
+        await publisher().edits.commit({ auth, packageName, editId, changesNotSentForReview: true });
+        return { changesNotSentForReview: true };
+    }
+}
+export async function withEdit(auth, packageName, fn, commit = false, onCommit) {
     const res = await publisher().edits.insert({ auth, packageName });
     const editId = res.data.id;
     if (!editId)
@@ -49,7 +68,12 @@ export async function withEdit(auth, packageName, fn, commit = false) {
     try {
         const result = await fn(editId);
         if (commit) {
-            await publisher().edits.commit({ auth, packageName, editId });
+            // 반드시 먼저 커밋하고 나서 콜백에 넘긴다.
+            // onCommit?.(await commitEdit(...)) 로 쓰면 안 된다 — 옵셔널 호출은 수신자가
+            // nullish 일 때 인자 자체를 평가하지 않아서, onCommit 을 안 넘긴 호출자(대부분)에서
+            // 커밋이 통째로 사라진다. playstore-listing 테스트가 이걸 잡아냈다.
+            const info = await commitEdit(auth, packageName, editId);
+            onCommit?.(info);
         }
         return result;
     }
@@ -379,7 +403,9 @@ export async function promoteRelease(auth, packageName, fromTrack, toTrack, vers
     if (status === 'inProgress' && (userFraction == null || userFraction <= 0 || userFraction >= 1)) {
         throw new Error('status="inProgress"일 때 userFraction은 0과 1 사이 필수 (예: 0.1 → 10%).');
     }
-    return withEdit(auth, packageName, async (editId) => {
+    let commitInfo = { changesNotSentForReview: false };
+    const warnings = [];
+    const out = await withEdit(auth, packageName, async (editId) => {
         // 1. source 트랙에서 versionCode 매칭 release 찾기
         const fromData = await publisher().edits.tracks.get({
             auth, packageName, editId, track: fromTrack,
@@ -405,6 +431,20 @@ export async function promoteRelease(auth, packageName, fromTrack, toTrack, vers
         if (status === 'inProgress' && userFraction != null) {
             newRelease.userFraction = userFraction;
         }
+        // 2-b. 릴리스 노트 회귀 가드.
+        //   CI 가 internal 에 올릴 때 "v2.0.6 (70)" 같은 플레이스홀더를 한 언어만 넣어두는 경우가 흔한데,
+        //   copyReleaseNotes 기본값(true)으로 production 에 승격하면 살아 있던 다국어 노트가
+        //   그 플레이스홀더로 통째 덮인다 (PenguinRun 2026-07-25 에 실제로 밟을 뻔한 함정).
+        //   막지는 않되(의도적일 수 있으므로) 반드시 눈에 띄게 알린다.
+        if (!releaseNotes && copyReleaseNotes) {
+            const copied = sourceRelease.releaseNotes ?? [];
+            const placeholder = copied.filter((n) => /^\s*v?\d+(\.\d+)*\s*(\(\d+\))?\s*$/.test(n.text ?? ''));
+            if (placeholder.length > 0) {
+                warnings.push(`${fromTrack} 의 릴리스 노트가 버전 문자열뿐이라 플레이스홀더로 보인다 ` +
+                    `(${placeholder.map((n) => `${n.language}="${n.text}"`).join(', ')}). ` +
+                    `이대로 ${toTrack} 에 덮어쓰면 기존 노트가 사라진다 — releaseNotes 를 직접 넘기거나 copyReleaseNotes:false 를 고려할 것.`);
+            }
+        }
         // 3. target 트랙 현재 상태 조회 후 merge
         //    - 같은 versionCode가 이미 target에 있으면 그 항목을 새 release로 교체
         //    - status='completed'면 활성 release가 1개여야 하므로 [newRelease]로 통째 교체
@@ -442,7 +482,19 @@ export async function promoteRelease(auth, packageName, fromTrack, toTrack, vers
             committed: true,
             result: updated.data,
         };
-    }, true);
+    }, true, (info) => { commitInfo = info; });
+    if ((out.releaseNotesLanguages ?? []).length === 0) {
+        warnings.push(`${toTrack} 에 릴리스 노트 없이 승격됐다 — 스토어의 "새로운 기능"이 비어 보인다.`);
+    }
+    return {
+        ...out,
+        changesNotSentForReview: commitInfo.changesNotSentForReview,
+        // Play 가 자동 심사 전송을 거부한 경우, 사람이 콘솔에서 눌러야 실제 심사가 시작된다.
+        nextAction: commitInfo.changesNotSentForReview
+            ? 'Play Console 에서 "변경사항 검토 후 게시"(심사를 위해 전송)를 눌러야 심사가 시작된다.'
+            : undefined,
+        warnings: warnings.length ? warnings : undefined,
+    };
 }
 export async function listReviews(auth, packageName) {
     const res = await publisher().reviews.list({ auth, packageName });

package/dist/registers/appstore.js

@@ -554,12 +554,16 @@ export function registerAppstoreTools(server) {
                 }],
         };
     });
-    server.tool('appstore_upload_product_review_screenshot', '기존 App Store IAP/구독 상품의 심사용 스크린샷을 reserve → upload → commit. 상품당 1장, 절대 파일 경로 필요.', {
+    server.tool('appstore_upload_product_review_screenshot', [
+        '기존 App Store IAP/구독 상품의 심사용 스크린샷을 reserve → upload → commit. 상품당 1장, 절대 파일 경로 필요.',
+        '이미 있으면 409 "Screenshot already exists" — 갈아끼우려면 replace: true (기존 것을 지우고 올린다).',
+    ].join(' '), {
         appId: z.string().describe('App Store 앱 ID (숫자형, appstore_list_apps 결과)'),
         productId: z.string().describe('상품 ID (appstore_list_products 결과)'),
         productType: z.enum(['subscription', 'consumable', 'non_consumable']).describe('상품 유형'),
         filePath: z.string().describe('업로드할 PNG/JPG의 절대 파일 경로'),
-    }, async ({ appId, productId, productType, filePath }) => {
+        replace: z.boolean().optional().describe('이미 스크린샷이 있으면 지우고 새로 올린다 (기본 false)'),
+    }, async ({ appId, productId, productType, filePath, replace }) => {
         const creds = requireAppStoreCreds();
         const products = await listAppleProducts({
             appId, keyId: creds.keyId, issuerId: creds.issuerId, privateKey: creds.privateKey,
@@ -572,6 +576,7 @@ export function registerAppstoreTools(server) {
             internalId: product.internalId,
             productType,
             filePath,
+            replace,
         });
         return {
             content: [{
@@ -581,6 +586,7 @@ export function registerAppstoreTools(server) {
                         `productId: ${productId}`,
                         `internalId: ${result.internalId}`,
                         `screenshotId: ${result.id}`,
+                        result.replacedId ? `교체됨 (이전 screenshotId: ${result.replacedId})` : '',
                         `file: ${result.fileName} (${result.fileSize} bytes)`,
                         result.state ? `state: ${result.state}` : '',
                         result.verified ? '✓ commit 후 조회 확인' : '⚠ commit은 성공했지만 후속 조회는 확인하지 못함',
@@ -647,10 +653,23 @@ export function registerAppstoreTools(server) {
             if (sub.items.length === 0) {
                 lines.push('  items: (없음)');
             }
+            // 항목 종류별 요약. 상품이 몇 개 들어갔는지가 첫 심사에서 가장 중요한 정보다.
+            const kinds = new Map();
+            for (const item of sub.items) {
+                const k = item.targetType ?? 'unknown';
+                kinds.set(k, (kinds.get(k) ?? 0) + 1);
+            }
+            lines.push(`  항목 ${sub.items.length}개` +
+                (kinds.size ? ` — ${[...kinds].map(([k, n]) => `${k} ${n}`).join(', ')}` : ''));
+            if (sub.items.length === 0) {
+                lines.push('  items: (없음)');
+            }
             for (const item of sub.items) {
                 const target = item.versionString
                     ? `${item.targetType} ${item.versionString} (${item.appVersionState ?? '?'})`
-                    : `${item.targetType ?? '?'} ${item.targetId ?? ''}`;
+                    : item.label
+                        ? `${item.targetType} ${item.label}${item.targetState ? ` (${item.targetState})` : ''}`
+                        : `${item.targetType ?? '?'} ${item.targetId ?? ''}`;
                 lines.push(`  - item ${item.id}`);
                 lines.push(`    state: ${item.state ?? '?'} → ${target}`);
             }
@@ -676,6 +695,53 @@ export function registerAppstoreTools(server) {
                 }],
         };
     });
+    server.tool('appstore_add_version_to_review_submission', '이미 존재하는 심사 묶음에 앱 버전을 항목으로 추가한다 (POST /reviewSubmissionItems). ' +
+        '⚠️ 앱 첫 심사 필수 절차 — 웹에서 IAP/구독을 담으면 "상품만 든 묶음"이 새로 생기는데, ' +
+        '그대로 제출하면 409 "an appStoreVersions must be included in this review submission" 로 막힌다. ' +
+        'reviewSubmissionItems 는 상품 관계는 거부하지만 appStoreVersion 관계는 받으므로, 버전을 이 묶음으로 옮기면 된다. ' +
+        '버전이 다른 묶음에 물려 있으면 먼저 풀 것: 미제출 묶음이면 appstore_remove_review_submission_item, ' +
+        '제출된 묶음이면 항목 제거가 막히므로 appstore_cancel_review 로 묶음째 취소. ' +
+        '추가 후 appstore_submit_for_review 로 제출하면 버전+상품이 한 묶음으로 나간다.', {
+        submissionId: z.string().describe('대상 reviewSubmission ID (appstore_list_review_submissions 결과)'),
+        versionId: z.string().describe('추가할 App Store 버전 ID (appstore_list_versions 결과)'),
+    }, async ({ submissionId, versionId }) => {
+        const result = await appstore.addVersionToReviewSubmission({ submissionId, versionId });
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        '✓ 묶음에 앱 버전 추가됨',
+                        `submissionId: ${result.submissionId}`,
+                        `versionId: ${result.versionId}`,
+                        result.itemId ? `itemId: ${result.itemId}` : '',
+                        `현재 묶음 항목 수: ${result.itemCount}개`,
+                        '제출 전 항목 수를 확인할 것 — 첫 심사라면 상품들이 함께 들어 있어야 한다.',
+                    ].filter(Boolean).join('\n'),
+                }],
+        };
+    });
+    server.tool('appstore_update_version_string', '기존 App Store 버전 레코드의 versionString 을 변경 (예: 2.0.5 → 2.0.6). ' +
+        '⚠️ 편집 가능한 버전이 이미 있으면 appstore_create_version 이 409 "cannot create a new version in the current state" 로 막힌다 — ' +
+        '거절/철회된 버전으로 다음 릴리스를 내보내려면 새로 만들지 말고 이 도구로 **같은 레코드의 이름을 올린다**. ' +
+        '빌드는 CFBundleShortVersionString 이 같은 버전에만 붙으므로, 새 버전의 빌드를 attach 하려면 먼저 이걸 맞춰야 한다. ' +
+        'PREPARE_FOR_SUBMISSION / DEVELOPER_REJECTED 등 편집 가능 상태에서만 통한다.', {
+        versionId: z.string().describe('App Store 버전 ID (appstore_list_versions 결과)'),
+        versionString: z.string().describe('새 버전 문자열 (예: "2.0.6")'),
+    }, async ({ versionId, versionString }) => {
+        const result = await appstore.updateVersionString(versionId, versionString);
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        '✓ 버전 문자열 변경 완료',
+                        `versionId: ${result.versionId}`,
+                        `versionString: ${result.versionString}`,
+                        result.state ? `state: ${result.state}` : '',
+                        '이제 같은 버전의 빌드를 attach 할 수 있다 (appstore_attach_latest_build).',
+                    ].filter(Boolean).join('\n'),
+                }],
+        };
+    });
     server.tool('appstore_update_product', 'App Store IAP 상품의 reference name 변경. productId / 유형은 변경 불가. ' +
         '스토어에 보이는 표시 이름·설명은 appstore_update_product_localization 을 쓴다.', {
         appId: z.string().optional().describe('App Store 앱 ID'),
@@ -781,8 +847,10 @@ export function registerAppstoreTools(server) {
     });
     server.tool('appstore_cancel_review', [
         'App Store 심사 제출을 철회 — WAITING_FOR_REVIEW 상태에서만 가능.',
-        'submitted=false PATCH → reviewSubmission이 READY_FOR_REVIEW로 복귀, 버전은 PREPARE_FOR_SUBMISSION 상태로 돌아가 메타데이터/빌드 수정 가능.',
+        'PATCH attributes.canceled=true → state 가 CANCELING 으로 바뀌고 수십 초 뒤 COMPLETE(항목 REMOVED), 버전은 편집 가능 상태로 복귀해 메타데이터/빌드 수정 가능.',
+        'CANCELING 은 비동기라 호출 직후엔 아직 COMPLETE 가 아니다 — 이어서 작업하려면 상태를 폴링할 것.',
         '⚠️ IN_REVIEW 이상이면 Apple API가 409로 거부함 — 이 경우 App Store Connect 웹에서 직접 처리하거나 심사 결과를 기다려야 함.',
+        '제출된 묶음에서 항목만 빼내는 것(removed)은 막히므로, 버전을 다른 묶음으로 옮기려면 이 도구로 묶음째 취소한다.',
         '철회 후 수정 완료 시 appstore_submit_for_review로 재제출 가능.',
     ].join(' '), {
         versionId: z.string().describe('App Store 버전 ID (appstore_list_versions 결과)'),

package/dist/registers/playstore.js

@@ -563,6 +563,8 @@ export function registerPlaystoreTools(server) {
         'status="completed" + production 으로 전체 출시, status="inProgress" + userFraction 으로 단계 출시(예: 0.1 = 10%).',
         'target에 같은 versionCode가 이미 있으면 해당 항목을 교체. status="completed"면 target 활성 release를 통째로 새 것으로 대체.',
         '⚠️ status="completed"는 비가역에 가까움. playstore_check_submission_risks로 사전 점검 권장.',
+        'Play 가 자동 심사 전송을 거부하는 앱이면 changesNotSentForReview=true 로 자동 폴백해 커밋한다 — 이때 응답의 changesNotSentForReview=true 와 nextAction 을 사용자에게 전달할 것(콘솔에서 "심사를 위해 전송"을 눌러야 심사 시작).',
+        'source 트랙 노트가 버전 문자열뿐인 플레이스홀더면 warnings 로 알린다 — 그대로 승격하면 대상 트랙의 다국어 노트가 덮인다.',
     ].join(' '), {
         packageName: z.string().describe('패키지명 (예: gg.pryzm.coffee)'),
         fromTrack: z.enum(['production', 'beta', 'alpha', 'internal']).describe('출처 트랙 (예: internal)'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoonion/mimi-seed-mcp",
-  "version": "0.13.12",
+  "version": "0.13.14",
   "description": "Mimi Seed MCP server — Firebase + AdMob + Google Play + App Store management for Claude Code / Codex / Cursor / any MCP client.",
   "type": "module",
   "bin": {

package/tool-manifest.json

@@ -1,6 +1,6 @@
 {
   "$comment": "등록된 MCP 도구 + 도메인 메타데이터(label·credential·summary)의 SSOT. src/__tests__/tool-manifest.test.ts 가 실제 서버 등록 목록과 diff 하고 메타데이터 정합성을 검사한다. 도구 추가/삭제/개명 시 이 파일을 함께 갱신할 것 — 산문 문서에는 정확한 개수를 쓰지 말고 이 파일을 가리킬 것. mimi-seed://tools/catalog 리소스가 이 파일을 그대로 서빙한다.",
-  "total": 187,
+  "total": 189,
   "domains": {
     "admob": {
       "label": "AdMob",
@@ -78,6 +78,8 @@
         "appstore_submit_for_review",
         "appstore_list_review_submissions",
         "appstore_remove_review_submission_item",
+        "appstore_add_version_to_review_submission",
+        "appstore_update_version_string",
         "appstore_cancel_review"
       ]
     },