@daemux/store-automator 0.10.95 → 0.10.97

package/templates/scripts/ci/ios-native/manage_marketing_version.py

@@ -2,257 +2,322 @@
 """
 Resolve the App Store Connect version slot for this run.
 
-CI -- not the Xcode project -- decides the marketing version. The archive
-step overrides the pbxproj MARKETING_VERSION at build time via
-`MARKETING_VERSION=...` on the xcodebuild command line.
-
-Algorithm (improvement over gowalk-step's "latest by createdDate"):
-  1. Fetch all appStoreVersions for the app.
-  2. Partition by state:
-       editable  (PREPARE_FOR_SUBMISSION, REJECTED, METADATA_REJECTED,
-                  DEVELOPER_REJECTED, INVALID_BINARY, WAITING_FOR_REVIEW,
-                  IN_REVIEW)
-       blocking  (PENDING_DEVELOPER_RELEASE)
-       terminal  (READY_FOR_SALE, PROCESSING_FOR_APP_STORE,
-                  PENDING_APPLE_RELEASE, REPLACED_WITH_NEW_VERSION,
-                  REMOVED_FROM_SALE, NOT_APPLICABLE)
-  3. If editable: REUSE the HIGHEST SEMVER among editable. Picking the
-     highest semver (not the latest createdDate) matches how Apple's UI
-     presents the "next" version and avoids the "later version closed"
-     error Apple returns on uploads to a lower editable version when a
-     higher one already exists.
-  4. Elif blocking: fail with a clear error -- a human must release the
-     pending version manually before CI can proceed.
-  5. Elif terminal: pick the highest-semver terminal version.
-       - READY_FOR_SALE -> CREATE the next version via rollover bump.
-       - anything else  -> fail (manual intervention required; state is
-         neither editable nor live).
-  6. No versions at all -> first release, CREATE "1.0.0".
-  7. 409 on CREATE (race) -> re-fetch, match by versionString, REUSE.
-
-Env: ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_PATH, APP_STORE_APPLE_ID.
+The project's MARKETING_VERSION build setting is the single source of truth
+for the marketing version. CI does not bump it. This script finds-or-creates
+the App Store Connect (ASC) row matching that exact version, and only the
+build number is bumped automatically (see next_build_number.py).
+
+Algorithm:
+  1. Read MARKETING_VERSION from env (set by action.yml from
+     xcodebuild -showBuildSettings or PlistBuddy).
+  2. Floor-check (non-strict): target >= combined floor across
+     appStoreVersions + preReleaseVersions + builds->preReleaseVersion.
+  3. If the target row already exists in /appStoreVersions:
+       - any non-editable match (terminal/blocking) -> SystemExit(2);
+         the slot is taken by a shipped or in-review row.
+       - editable-only match -> REUSE its id (steady-state TestFlight
+         iteration at unchanged MARKETING_VERSION).
+  4. CREATE path: floor-check (strict, target > floor); PATCH-rename any
+     stale editable to target; or POST a new row.
+
+This module is intentionally thin: floor logic lives in
+``mmv_floor_check``; CREATE wiring (POST/PATCH-rename, stale-editable
+detection) lives in ``mmv_decide_create``. Both submodules re-bind back
+through this one so test patches at ``mmv.<seam>`` keep winning.
+
+Env: ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_PATH, APP_STORE_APPLE_ID,
+     MARKETING_VERSION (project source of truth, set by action.yml).
 Stdout: {"decision":"REUSE|CREATE","versionString":"...","appStoreVersionId":"..."}
-Stderr: [decision] log lines + ::error:: on fatal conditions.
 """
 
 from __future__ import annotations
 
 import json
 import os
-import re
 import sys
 
 from asc_common import (
     BLOCKING_STATES,
-    EDITABLE_STATES,
+    IN_REVIEW_STATES,
+    REUSABLE_STATES,
     TERMINAL_STATES,
-    get_json,
     make_jwt,
-    request,
 )
 
+from mmv_floor_check import (
+    BUILD_SETTING_SOURCES,
+    MIGRATION_HINT,
+    SEM_RE,
+    assert_target_meets_floor,
+    bump_patch_for_message,
+    fetch_versions,
+    get_combined_floor,
+    get_ground_truth_floor,
+    maybe_auto_bump,
+    semver_tuple,
+)
+from mmv_decide_create import (
+    create_or_reuse,
+    create_or_reuse_with_stale,
+    create_version,
+    decide_create,
+)
+
+# Re-export the public seams so tests that patch ``mmv.<name>`` keep
+# working. The submodules look these up through this module at call
+# time, so a patch on ``mmv.fetch_versions`` propagates correctly.
+__all__ = (
+    "SEM_RE",
+    "create_or_reuse",
+    "create_version",
+    "decide_for_version",
+    "env",
+    "fetch_versions",
+    "get_combined_floor",
+    "get_ground_truth_floor",
+    "main",
+    "make_jwt",
+    "semver_tuple",
+)
+
+
+_APP_ID_MISSING_HINT = (
+    "::error::APP_STORE_APPLE_ID is empty. This usually means auto-detect "
+    "could not resolve PRODUCT_BUNDLE_IDENTIFIER from your Xcode project "
+    "(check the auto-detect: ... log lines in the 'Resolve credentials + "
+    "auto-detect' step above). Fix options: (1) commit your .xcodeproj or "
+    "add an xcodegen project.yml; (2) pass `app-store-apple-id:` explicitly "
+    "via the action's `with:` block."
+)
 
-SEM_RE = re.compile(r"^(\d+)\.(\d+)(?:\.(\d+))?$")
+_MARKETING_VERSION_MISSING_HINT = (
+    "::error::MARKETING_VERSION env var is missing or invalid. The "
+    "action.yml step that reads it from xcodebuild -showBuildSettings "
+    "(or PlistBuddy fallback) must set it before this script runs. "
+    + MIGRATION_HINT
+)
 
 
 def _log(msg: str) -> None:
     print(f"[decision] {msg}", file=sys.stderr)
 
 
-def _result(decision: str, version: str, vid: str) -> dict:
-    return {
+def _result(decision: str, version: str, vid: str, state: str = "") -> dict:
+    out = {
         "decision": decision,
         "versionString": version,
         "appStoreVersionId": vid,
     }
+    if state:
+        out["state"] = state
+    return out
 
 
 def env(name: str) -> str:
     val = os.environ.get(name)
     if not val:
         if name == "APP_STORE_APPLE_ID":
-            print(
-                "::error::APP_STORE_APPLE_ID is empty. This usually means "
-                "auto-detect could not resolve PRODUCT_BUNDLE_IDENTIFIER from "
-                "your Xcode project (check the auto-detect: ... log lines in the "
-                "'Resolve credentials + auto-detect' step above). Fix options: "
-                "(1) commit your .xcodeproj or add an xcodegen project.yml; "
-                "(2) pass `app-store-apple-id:` explicitly via the action's `with:` block.",
-                file=sys.stderr,
-            )
+            msg = _APP_ID_MISSING_HINT
+        elif name == "MARKETING_VERSION":
+            msg = _MARKETING_VERSION_MISSING_HINT
         else:
-            print(f"::error::Missing required env var: {name}", file=sys.stderr)
+            msg = f"::error::Missing required env var: {name}"
+        print(msg, file=sys.stderr)
         raise SystemExit(1)
     return val
 
 
-def semver_tuple(version_string: str) -> tuple[int, int, int]:
-    """Parse 'M.m[.p]' -> (M, m, p). Non-semver returns (-1,-1,-1) so it
-    sorts below any real version."""
-    m = SEM_RE.match(version_string or "")
-    if not m:
-        return (-1, -1, -1)
-    return (int(m.group(1)), int(m.group(2)), int(m.group(3) or "0"))
-
-
-def calculate_next_version(current_version: str) -> str:
-    """Rollover bump: patch+1; patch>=10 resets to 0 and minor+1;
-    minor>=10 resets both to 0 and major+1. Accepts 'M.m' or 'M.m.p'."""
-    m = SEM_RE.match(current_version or "")
-    if not m:
-        raise SystemExit(
-            f"::error::App Store versionString {current_version!r} is not a "
-            f"valid semantic version (expected MAJOR.MINOR[.PATCH])."
-        )
-    major = int(m.group(1))
-    minor = int(m.group(2))
-    patch = int(m.group(3) or "0")
-
-    new_patch = patch + 1
-    new_minor = minor
-    new_major = major
-
-    if new_patch >= 10:
-        new_patch = 0
-        new_minor = minor + 1
-    if new_minor >= 10:
-        new_minor = 0
-        new_patch = 0
-        new_major = major + 1
-
-    return f"{new_major}.{new_minor}.{new_patch}"
-
-
-def fetch_versions(app_id: str, token: str) -> list[dict]:
-    """All appStoreVersions for the app (no sort/limit/filter)."""
-    data = get_json(f"/apps/{app_id}/appStoreVersions", token)
-    out: list[dict] = []
-    for item in data.get("data", []):
-        attrs = item.get("attributes") or {}
-        out.append({
-            "versionString": attrs.get("versionString") or "",
-            "state": attrs.get("appStoreState") or "",
-            "id": item.get("id") or "",
-            "createdDate": attrs.get("createdDate") or "",
-        })
-    return out
-
-
-def create_version(app_id: str, version: str, token: str):
-    body = {
-        "data": {
-            "type": "appStoreVersions",
-            "attributes": {
-                "platform": "IOS",
-                "versionString": version,
-                "releaseType": "AFTER_APPROVAL",
-            },
-            "relationships": {
-                "app": {"data": {"type": "apps", "id": app_id}},
-            },
-        }
-    }
-    return request(
-        "POST", "/appStoreVersions", token,
-        json_body=body, allow_status={409},
-    )
-
-
-def create_or_reuse(app_id: str, version: str, token: str) -> str:
-    """POST a new version; on 409 race, re-fetch and return existing id."""
-    resp = create_version(app_id, version, token)
-    if resp.status_code != 409:
-        return resp.json()["data"]["id"]
-
+def _validate_target(target_version: str) -> None:
+    """SystemExit(1) when target is not a parseable semver."""
+    if SEM_RE.match(target_version or ""):
+        return
     print(
-        f"POST /appStoreVersions returned 409 for {version}; "
-        "re-fetching to locate the existing slot.",
+        f"::error::MARKETING_VERSION {target_version!r} is not a "
+        f"valid semantic version (expected MAJOR.MINOR[.PATCH]). "
+        f"Set MARKETING_VERSION in " + BUILD_SETTING_SOURCES + ". "
+        + MIGRATION_HINT,
         file=sys.stderr,
     )
-    for v in fetch_versions(app_id, token):
-        if v["versionString"] == version:
-            return v["id"]
-    raise SystemExit(
-        f"::error::POST /appStoreVersions returned 409 for {version} but "
-        f"no matching versionString was found on re-fetch."
-    )
-
-
-def _summarize(versions: list[dict]) -> str:
-    return ", ".join(
-        f"{v['versionString']}({v['state']})" for v in versions
-    ) or "<none>"
-
-
-def _pick_highest_semver(versions: list[dict]) -> dict:
-    """Tiebreak by createdDate (newer wins) when semvers collide."""
-    return max(
-        versions,
-        key=lambda v: (semver_tuple(v["versionString"]), v.get("createdDate", "")),
-    )
-
-
-def decide(versions: list[dict], app_id: str, token: str) -> dict:
-    if not versions:
-        new_version = "1.0.0"
-        new_id = create_or_reuse(app_id, new_version, token)
-        _log(f"CREATE {new_version} (first release) -> appStoreVersion id={new_id}")
-        return _result("CREATE", new_version, new_id)
-
-    editable = [v for v in versions if v["state"] in EDITABLE_STATES]
-    blocking = [v for v in versions if v["state"] in BLOCKING_STATES]
-    terminal = [v for v in versions if v["state"] in TERMINAL_STATES]
-    _log(
-        f"editable=[{_summarize(editable)}] "
-        f"blocking=[{_summarize(blocking)}] "
-        f"terminal=[{_summarize(terminal)}]"
-    )
+    raise SystemExit(1)
 
-    if editable:
-        target = _pick_highest_semver(editable)
-        _log(
-            f"REUSE {target['versionString']} (highest-semver editable, "
-            f"state={target['state']}, id={target['id']})"
-        )
-        return _result("REUSE", target["versionString"], target["id"])
 
-    if blocking:
-        target = _pick_highest_semver(blocking)
+def _classify_match_at_target(
+    versions: list[dict], target: str,
+) -> tuple[str, dict | None, bool]:
+    """Classify rows at ``target`` -> ``(status, match, also_editable)``.
+
+    Status values: ``"none"`` (no match -> CREATE), ``"reuse"`` (editable
+    -> REUSE its id), ``"terminal"`` (settled, slot locked -- caller may
+    auto-roll), ``"in_review"`` (under Apple Review or awaiting dev
+    release click -- caller MUST reject), ``"unknown"`` (matched but
+    state is in NO allowlist -- caller MUST reject; round 12 fail-closed
+    so an unfamiliar ASC state can't silently 409 on CREATE). The state
+    taxonomy lives in ``asc_common.py`` next to the constant set
+    definitions; positive allowlists (round 11) replaced the historical
+    ``not in EDITABLE_STATES`` test that misclassified
+    PENDING_DEVELOPER_RELEASE as terminal."""
+    matches = [v for v in versions if v.get("versionString") == target]
+    if not matches:
+        return "none", None, False
+    in_review = [
+        v for v in matches
+        if v.get("state") in IN_REVIEW_STATES
+        or v.get("state") in BLOCKING_STATES
+    ]
+    if in_review:
+        return "in_review", in_review[0], False
+    terminal = [v for v in matches if v.get("state") in TERMINAL_STATES]
+    if terminal:
+        return "terminal", terminal[0], len(matches) > 1
+    reusable = [v for v in matches if v.get("state") in REUSABLE_STATES]
+    if reusable:
+        return "reuse", reusable[0], False
+    # Round 12: matches exist but no state is recognized -- fail closed.
+    return "unknown", matches[0], len(matches) > 1
+
+
+def _reject_match(
+    target: str, match: dict, *,
+    also_editable: bool = False, unknown: bool = False,
+) -> None:
+    """Reject a non-reusable match at ``target``. When ``unknown`` is
+    True the matched row's ASC state is in none of our allowlists --
+    bail rather than guess (round 12: silently CREATEing would 409;
+    silently REUSEing could interfere with whatever Apple is doing
+    with the row). Otherwise this is the historical terminal-collision
+    rejection path."""
+    state, vid = match.get("state", ""), match.get("id", "")
+    if unknown:
         print(
-            f"::error::App Store version {target['versionString']} is "
-            f"{target['state']}. Release it in App Store Connect, then retry.",
+            f"::error::MARKETING_VERSION {target} exists in App Store "
+            f"Connect in unrecognized state {state!r} (id={vid}); "
+            f"bailing rather than guessing whether to REUSE or CREATE. "
+            f"Update mmv classifier (asc_common.TERMINAL_STATES / "
+            f"IN_REVIEW_STATES / BLOCKING_STATES / REUSABLE_STATES) to "
+            f"cover {state!r}, or bump MARKETING_VERSION manually to a "
+            f"fresh value in your project's build settings ("
+            + BUILD_SETTING_SOURCES + "). " + MIGRATION_HINT,
             file=sys.stderr,
         )
-        raise SystemExit(1)
-
-    if terminal:
-        target = _pick_highest_semver(terminal)
-        if target["state"] != "READY_FOR_SALE":
-            print(
-                f"::error::Highest App Store version {target['versionString']} "
-                f"is {target['state']}; neither editable nor live. Manual "
-                f"intervention required in App Store Connect.",
-                file=sys.stderr,
-            )
-            raise SystemExit(1)
-        new_version = calculate_next_version(target["versionString"])
-        new_id = create_or_reuse(app_id, new_version, token)
-        _log(
-            f"CREATE {new_version} (previous={target['versionString']}, "
-            f"previous_state={target['state']}) -> appStoreVersion id={new_id}"
+        raise SystemExit(2)
+    suffix = (
+        " (an editable row at the same versionString also exists)"
+        if also_editable else ""
+    )
+    print(
+        f"::error::MARKETING_VERSION {target} already exists in App "
+        f"Store Connect in state {state} (id={vid}){suffix}. REUSE/CREATE "
+        f"both require a fresh marketing version. Bump MARKETING_VERSION "
+        f"in your project's build settings (" + BUILD_SETTING_SOURCES +
+        "). " + MIGRATION_HINT,
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
+def _reject_in_review_match(target: str, match: dict) -> None:
+    """Issue 13: REUSE/CREATE must NOT touch a row Apple is reviewing
+    OR a row awaiting the developer's manual release click
+    (PENDING_DEVELOPER_RELEASE). Both states require human action;
+    auto-rolling past them would either race App Review or bypass the
+    developer's release decision."""
+    state, vid = match.get("state", ""), match.get("id", "")
+    if state == "PENDING_DEVELOPER_RELEASE":
+        situation = (
+            "is approved by App Review and awaiting your manual release. "
+            "Either release the existing build via App Store Connect, or"
+        )
+    else:
+        situation = (
+            "is currently in App Review and cannot be modified. Either "
+            "wait for review to complete, or"
         )
-        return _result("CREATE", new_version, new_id)
-
-    # Unknown state (not editable, not blocking, not terminal) -- refuse to
-    # guess. Lists both states in the error so ops can update the classifier.
-    unknown = ", ".join(f"{v['versionString']}({v['state']})" for v in versions)
     print(
-        f"::error::No editable/blocking/terminal App Store versions found; "
-        f"all versions have unrecognized states: {unknown}. Update "
-        f"asc_common.EDITABLE_STATES / TERMINAL_STATES / BLOCKING_STATES.",
+        f"::error::MARKETING_VERSION {target} exists in App Store Connect "
+        f"in state {state} (id={vid}). The version {situation} "
+        f"bump MARKETING_VERSION to a fresh value in your project's "
+        f"build settings (" + BUILD_SETTING_SOURCES + "). "
+        + MIGRATION_HINT,
         file=sys.stderr,
     )
-    raise SystemExit(1)
+    raise SystemExit(2)
+
+
+def _auto_roll_past_locked(
+    target_version: str, versions: list[dict],
+) -> tuple[str, str, dict | None, bool]:
+    """Try to auto-roll past a TERMINAL row at target.
+
+    Classifies the row(s) at target. When the match is terminal
+    (READY_FOR_SALE / PROCESSING_FOR_APP_STORE / PENDING_APPLE_RELEASE
+    etc.), fires ``maybe_auto_bump`` to advance the project's
+    MARKETING_VERSION to the next patch and re-classifies against the
+    rolled value. When auto-bump is disabled (policy='none') or the
+    write target is unreachable, returns the original locked
+    classification so the caller can surface the historical
+    SystemExit(2) rejection.
+
+    DESIGN DECISION: in-review collisions (WAITING_FOR_REVIEW /
+    IN_REVIEW / PENDING_DEVELOPER_RELEASE) are deliberately NOT
+    auto-rolled. Apple is either actively reviewing the row at
+    ``target`` or has approved it and is waiting on the developer's
+    manual release click; advancing the project to a new version would
+    either submit a competing build while review is in flight or
+    bypass the developer's release decision -- both states require
+    human action. The historical SystemExit(2) rejection at these
+    states surfaces the conflict loudly so a human can resolve it.
+
+    Returns ``(effective_target, status, match, also_editable)``."""
+    status, match, also_editable = _classify_match_at_target(
+        versions, target_version,
+    )
+    if status != "terminal":
+        return target_version, status, match, also_editable
+    rolled = maybe_auto_bump(target_version, target_version)
+    if rolled is None or rolled == target_version:
+        return target_version, status, match, also_editable
+    _log(f"auto-roll: {target_version} is {match.get('state', '')}, "
+         f"advancing project to {rolled}")
+    new_status, new_match, new_also = _classify_match_at_target(
+        versions, rolled,
+    )
+    return rolled, new_status, new_match, new_also
+
+
+def decide_for_version(
+    target_version: str, versions: list[dict],
+    app_id: str, token: str,
+) -> dict:
+    """Find-or-create the ASC row at exactly ``target_version``.
+
+    Validates semver, runs the non-strict floor check (auto-bump
+    rewrites MARKETING_VERSION when below the ASC floor; the returned
+    effective target is what downstream uses), then classifies any
+    row(s) at target. Terminal collisions auto-roll to the next patch
+    (or reject when policy='none'); in-review and unknown-state
+    collisions reject loudly (see ``_classify_match_at_target`` for
+    the full taxonomy). No match -> CREATE; reusable editable -> REUSE."""
+    _validate_target(target_version)
+    target_version = assert_target_meets_floor(
+        target_version, app_id, token,
+        appstore_versions=versions, strict=False,
+    )
+    target_version, status, match, also_editable = _auto_roll_past_locked(
+        target_version, versions,
+    )
+    if status == "terminal":
+        _reject_match(target_version, match, also_editable=also_editable)
+    if status == "in_review":
+        _reject_in_review_match(target_version, match)
+    if status == "unknown":
+        _reject_match(target_version, match, unknown=True)
+    if status == "none":
+        return decide_create(target_version, versions, app_id, token)
+    vid = match.get("id", "")
+    state = match.get("state", "")
+    _log(f"decision=REUSE versionString={target_version} "
+         f"(matches MARKETING_VERSION; state={state}, id={vid})")
+    return _result("REUSE", target_version, vid, state)
 
 
 def main() -> None:
@@ -260,10 +325,11 @@ def main() -> None:
     issuer_id = env("ASC_ISSUER_ID")
     key_path = env("ASC_KEY_PATH")
     app_id = env("APP_STORE_APPLE_ID")
+    target_version = env("MARKETING_VERSION")
 
     token = make_jwt(key_id, issuer_id, key_path)
     versions = fetch_versions(app_id, token)
-    result = decide(versions, app_id, token)
+    result = decide_for_version(target_version, versions, app_id, token)
     print(json.dumps(result))