@daemux/store-automator 0.10.94 → 0.10.96

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

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""
+CREATE-path helpers for manage_marketing_version.
+
+This module owns the wiring that turns a target versionString into either
+a fresh /appStoreVersions POST or a PATCH-rename of a stale editable. The
+``_no_bump`` sentinel disarms ``asc_version_create.create_or_reuse``'s
+bump-retry loop because the project's MARKETING_VERSION is the single
+source of truth -- CI must never invent a new versionString.
+
+The ``_via_module`` helper provides a late-binding seam back through
+``manage_marketing_version`` so test patches at ``mmv.fetch_versions`` /
+``mmv.create_version`` keep winning even though the call originates here.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from asc_common import EDITABLE_STATES, REUSABLE_STATES
+import asc_build_history
+import asc_version_create
+from mmv_floor_check import assert_target_meets_floor, semver_tuple
+
+
+def _no_bump(current: str) -> str:
+    """Default bump_fn: never bump. CI must not invent a marketing
+    version because the project's build setting is authoritative."""
+    print(
+        f"::error::POST /appStoreVersions returned 409 for {current}; "
+        f"ASC reports this versionString already exists but it was not "
+        f"visible in /appStoreVersions/preReleaseVersions/builds. "
+        f"Inspect the app in App Store Connect manually.",
+        file=sys.stderr,
+    )
+    raise SystemExit(4)
+
+
+def _via_module(name: str):
+    """Late-binding seam for tests that patch attributes on
+    ``manage_marketing_version``. Returns a wrapper that defers attribute
+    lookup to call time so ``mock.patch.object(mmv, name)`` keeps winning."""
+    def _call(*args, **kwargs):
+        import manage_marketing_version
+        return getattr(manage_marketing_version, name)(*args, **kwargs)
+    return _call
+
+
+def create_version(app_id: str, version: str, token: str):
+    return asc_version_create.create_version(app_id, version, token)
+
+
+def create_or_reuse(
+    app_id: str, version: str, token: str,
+    *, bump_fn=None,
+) -> str:
+    """POST a new version at exactly `version`. Caller passes a `bump_fn`
+    that disarms the bump-retry path by raising; this script never wants
+    a server-side bump because the project's MARKETING_VERSION is the
+    single source of truth."""
+    return create_or_reuse_with_stale(
+        app_id, version, token, bump_fn=bump_fn,
+    )
+
+
+def create_or_reuse_with_stale(
+    app_id: str, version: str, token: str,
+    *, bump_fn=None, stale_editable_id: str | None = None,
+) -> str:
+    """``create_or_reuse`` plus the optional stale-editable PATCH-rename
+    seam so ``decide_for_version`` can promote a leftover editable row at
+    a different versionString to the project's freshly-bumped target."""
+    return asc_version_create.create_or_reuse(
+        app_id, version, token,
+        bump_fn=bump_fn or _no_bump,
+        fetch_versions=_via_module("fetch_versions"),
+        fetch_prerelease_versions=asc_build_history.fetch_prerelease_versions,
+        fetch_builds_prerelease_versions=(
+            asc_build_history.fetch_builds_prerelease_versions
+        ),
+        post_fn=_via_module("create_version"),
+        stale_editable_id=stale_editable_id,
+        patch_fn=asc_version_create.patch_version,
+        delete_fn=asc_version_create.delete_version,
+    )
+
+
+def _refuse_downgrade(target: str, version_string: str, vid: str, state: str) -> None:
+    """Emit a SystemExit(2) error when an editable exists at versionString >= target.
+
+    PATCH-renaming a higher-or-equal editable would silently downgrade an
+    in-progress draft. The CREATE-path floor check does NOT catch this
+    because editable rows do not contribute to combined_floor."""
+    print(
+        f"::error::Cannot CREATE MARKETING_VERSION {target}: an "
+        f"editable App Store version exists at {version_string} "
+        f"(id={vid}, state={state}). Renaming a "
+        f"higher or equal-version editable would downgrade an "
+        f"in-progress draft. Either bump MARKETING_VERSION to "
+        f">= {version_string} in your project's build settings "
+        f"(project.yml [xcodegen], the .xcodeproj's "
+        f"MARKETING_VERSION xcconfig, or Info.plist's "
+        f"CFBundleShortVersionString), or manually delete or "
+        f"rename the existing draft in App Store Connect. "
+        f"See .github/actions/ios-native-testflight/MIGRATION.md "
+        f"for the migration procedure.",
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
+def _stale_editable_id(versions: list[dict], target: str) -> str | None:
+    """Return the id of a REUSABLE row at a versionString strictly LESS
+    than target (a leftover lower-version draft to PATCH-rename onto the
+    project's freshly-bumped MARKETING_VERSION). Returns None when no
+    rename is needed.
+
+    SystemExit(2) when an editable exists at a versionString >= target:
+    PATCH-renaming it would silently downgrade an in-progress draft.
+    The CREATE-path floor check does NOT catch this because editable
+    rows do not contribute to combined_floor.
+
+    Issue 13: rows currently under Apple Review (WAITING_FOR_REVIEW /
+    IN_REVIEW) are EDITABLE in ASC's broad sense but mutating them would
+    interfere with the review process. They are still subject to the
+    >= target downgrade check (Issue 10 still applies), but they are
+    NOT candidates for PATCH-rename when version < target — the CREATE
+    path falls through to a plain POST instead, leaving the in-review
+    row alone."""
+    target_t = semver_tuple(target)
+    candidates: list[str] = []
+    for v in versions:
+        state = v.get("state")
+        if state not in EDITABLE_STATES:
+            continue
+        version_string = v.get("versionString") or ""
+        if version_string == target:
+            continue
+        vid = v.get("id")
+        if not vid:
+            continue
+        if semver_tuple(version_string) >= target_t:
+            _refuse_downgrade(target, version_string, vid, state)
+        # In-review rows (WAITING_FOR_REVIEW / IN_REVIEW) are editable
+        # but not safe to rename — leave them alone and POST a fresh row.
+        if state in REUSABLE_STATES:
+            candidates.append(vid)
+    return candidates[0] if candidates else None
+
+
+def decide_create(
+    target_version: str, versions: list[dict],
+    app_id: str, token: str,
+) -> dict:
+    """CREATE path: enforce strict floor, PATCH-rename any stale editable,
+    then POST. SystemExit(2) when target is not strictly above the floor.
+
+    Late-binds ``mmv.create_or_reuse_with_stale`` and ``mmv._result`` so
+    test patches at the parent module win."""
+    import manage_marketing_version as mmv
+    # The strict floor-check may also auto-bump (e.g. on a CREATE-path
+    # call where the project is below the floor and the non-strict
+    # pre-check did not fire because the prior caller skipped it). Use
+    # the returned value for all subsequent reasoning.
+    target_version = assert_target_meets_floor(
+        target_version, app_id, token,
+        appstore_versions=versions, strict=True,
+    )
+    stale_id = _stale_editable_id(versions, target_version)
+    new_id = mmv.create_or_reuse_with_stale(
+        app_id, target_version, token, stale_editable_id=stale_id,
+    )
+    if stale_id:
+        msg = (f"decision=CREATE versionString={target_version} "
+               f"(PATCH-rename of stale editable id={stale_id}) "
+               f"-> appStoreVersion id={new_id}")
+    else:
+        msg = (f"decision=CREATE versionString={target_version} "
+               f"-> appStoreVersion id={new_id}")
+    print(f"[decision] {msg}", file=sys.stderr)
+    return mmv._result("CREATE", target_version, new_id)

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

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""
+Floor-check helpers for manage_marketing_version.
+
+The combined floor is the max versionString across:
+  - /appStoreVersions (caller-provided, ship-blocking states only)
+  - /preReleaseVersions (TestFlight trains)
+  - /builds->preReleaseVersion (hidden trains visible only via builds)
+
+Plus an independent narrow per-state ground-truth query as defence-in-depth
+against truncated/buggy main fetches.
+
+This module owns the semver primitives, the floor-resolving wrappers
+that tests patch (``fetch_versions``, ``get_ground_truth_floor``,
+``get_combined_floor``), and the strict/non-strict assertion that
+``decide_for_version`` runs before REUSE/CREATE branching.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+import asc_version_fetch
+import version_utils
+
+
+SEM_RE = re.compile(r"^(\d+)\.(\d+)(?:\.(\d+))?$")
+
+# DESIGN DECISION: auto-bump policy is read from the env var so the action
+# step can wire it from `inputs.marketing-version-auto-bump` without a
+# CLI-flag re-plumb of every helper. Default 'patch' matches the action
+# input default. ``'none'`` preserves the historical fail-the-build path.
+_AUTO_BUMP_ENV = "MARKETING_VERSION_AUTO_BUMP"
+
+# DESIGN DECISION: auto-bump must only fire when the resulting bumped
+# value can be committed back to the repo in the same run. The
+# commit-back step in action.yml is gated on `event=push` AND
+# `ref=refs/heads/<default_branch>`. Auto-bumping on any other event
+# (workflow_dispatch, pull_request, push to feature branches) would
+# upload an IPA at the bumped version while git stays at the old
+# value, causing the next run to recompute against stale state and
+# either re-bump or drift.
+#
+# These envs are set by the action.yml step from
+# ``${{ github.event_name }}`` and ``${{ github.ref }}`` /
+# ``${{ github.event.repository.default_branch }}``. Empty / unset
+# values are treated as "context unknown -> refuse to auto-bump"
+# (defensive: when run outside the GitHub Actions context, e.g. local
+# dev or a third-party orchestrator, the safe default is to require a
+# human bump).
+_EVENT_ENV = "GITHUB_EVENT_NAME"
+_REF_ENV = "GITHUB_REF"
+_DEFAULT_BRANCH_ENV = "GITHUB_DEFAULT_BRANCH"
+
+# These constants and helpers are intentionally public (no leading
+# underscore) because manage_marketing_version.py imports them across the
+# module boundary. Module-internal helpers below keep the leading
+# underscore to mark them as private.
+MIGRATION_HINT = (
+    "See .github/actions/ios-native-testflight/MIGRATION.md for the "
+    "migration procedure."
+)
+BUILD_SETTING_SOURCES = (
+    "project.yml [xcodegen], the .xcodeproj's MARKETING_VERSION xcconfig, "
+    "or Info.plist's CFBundleShortVersionString"
+)
+
+
+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 bump_patch_for_message(floor: str) -> str:
+    """Suggest a next-patch value to surface in error text. Best-effort."""
+    m = SEM_RE.match(floor or "")
+    if not m:
+        return f"{floor} (bump above this)"
+    major, minor = int(m.group(1)), int(m.group(2))
+    patch = int(m.group(3) or "0")
+    return f"{major}.{minor}.{patch + 1}"
+
+
+def fetch_versions(app_id: str, token: str) -> list[dict]:
+    return asc_version_fetch.fetch_versions(app_id, token)
+
+
+def get_ground_truth_floor(app_id: str, token: str) -> str | None:
+    return asc_version_fetch.get_ground_truth_floor(app_id, token, semver_tuple)
+
+
+def get_combined_floor(
+    app_id: str, token: str, appstore_versions: list[dict],
+) -> tuple[str | None, dict[str, str | None]]:
+    """Wrapper around asc_version_fetch.get_combined_floor that forwards
+    both the floor AND the per-source breakdown so the cross-check error
+    message can name the real source contributing the binding floor (not
+    a synthesized one)."""
+    return asc_version_fetch.get_combined_floor(
+        app_id, token, semver_tuple, appstore_versions=appstore_versions,
+    )
+
+
+def _resolve_floor(app_id: str, token: str, appstore_versions: list[dict]):
+    """Return (floor, per_source). floor is None when every ASC source is
+    empty (true first-release case). Late-binds the seam wrappers via the
+    parent ``manage_marketing_version`` module so test patches at
+    ``mmv.get_combined_floor`` / ``mmv.get_ground_truth_floor`` win."""
+    import manage_marketing_version as mmv
+    combined, per_source = mmv.get_combined_floor(
+        app_id, token, appstore_versions,
+    )
+    narrow = mmv.get_ground_truth_floor(app_id, token)
+    candidates = [c for c in (combined, narrow) if c]
+    floor = max(candidates, key=semver_tuple) if candidates else None
+    return floor, per_source
+
+
+def _floor_error(target: str, floor: str, per_source: dict, *, strict: bool) -> None:
+    relation = "strictly greater than" if strict else "greater than or equal to"
+    print(
+        f"::error::MARKETING_VERSION {target} in your project's build "
+        f"settings (typically " + BUILD_SETTING_SOURCES + f") must be "
+        f"{relation} the App Store Connect floor {floor}. Bump it (e.g. "
+        f"to {bump_patch_for_message(floor)}), commit, and rerun. "
+        f"Sources contributing to floor: "
+        f"appStoreVersions={per_source.get('appStoreVersions') or '<none>'}, "
+        f"preReleaseVersions={per_source.get('preReleaseVersions') or '<none>'}, "
+        f"buildsViaPreRelease={per_source.get('buildsViaPreRelease') or '<none>'}. "
+        + MIGRATION_HINT,
+        file=sys.stderr,
+    )
+    raise SystemExit(2)
+
+
+def _persist_context_ok() -> bool:
+    """True when this run can persist a project-file bump back to the
+    default branch via the action's commit-back step. The commit-back
+    step is gated on ``event=push`` AND ``ref=refs/heads/<default>``;
+    any other context (workflow_dispatch / pull_request / push to a
+    feature branch) would upload an IPA at the bumped version while
+    git stays at the old value, drifting the project from ASC.
+
+    On refusal, emits the ``::warning::`` describing why this run
+    cannot persist the bump (event/ref/default_branch values from the
+    environment). Side-effecting the warning here -- rather than at
+    the caller -- keeps ``maybe_auto_bump`` under the per-function LOC
+    cap without splitting the env-read + warning into two helpers
+    (which would also push the file over the per-file functions cap)."""
+    event = (os.environ.get(_EVENT_ENV) or "").strip()
+    ref = (os.environ.get(_REF_ENV) or "").strip()
+    default_branch = (os.environ.get(_DEFAULT_BRANCH_ENV) or "").strip()
+    ok = (
+        event == "push"
+        and bool(default_branch)
+        and ref == f"refs/heads/{default_branch}"
+    )
+    if ok:
+        return True
+    print(
+        f"::warning::auto-bump=patch is enabled, but this run "
+        f"cannot persist the bump (event={event or '<unset>'}, "
+        f"ref={ref or '<unset>'}, "
+        f"default_branch={default_branch or '<unset>'}). The "
+        f"action's commit-back step only runs on push to "
+        f"refs/heads/{default_branch or '<unset>'}; auto-bumping on "
+        f"any other event would upload an IPA at the bumped version "
+        f"while git stays at the old value. Falling back to fail-on-"
+        f"floor; either push to the default branch with auto-bump "
+        f"enabled, or manually bump MARKETING_VERSION and rerun.",
+        file=sys.stderr,
+    )
+    return False
+
+
+def maybe_auto_bump(target: str, floor: str) -> str | None:
+    """Return the bumped version when auto-bump is enabled, the run
+    can persist the bump, and writes succeed. Returns None when policy
+    is 'none', the persistence context disallows commit-back, or the
+    project-file write failed -- the caller falls back to the historical
+    ``_floor_error`` path.
+
+    Public seam so ``manage_marketing_version`` can fire the auto-roll
+    when target == a terminal-state floor row (READY_FOR_SALE auto-roll)
+    -- not just when target < floor (the historical floor-violation
+    case).
+
+    Side effects: writes the new version into the project file (pbxproj
+    / xcconfig / Info.plist / project.yml depending on resolution) and
+    updates ``os.environ['MARKETING_VERSION']`` so downstream steps see
+    the bumped value. ``version_utils.write_marketing_version`` ALSO
+    runs ``git add -f`` on the touched path so the auto-bump is staged
+    in the index before any later step (e.g. prepare_signing) mutates
+    the same file."""
+    policy = (os.environ.get(_AUTO_BUMP_ENV) or "patch").strip().lower()
+    if policy == "none":
+        return None
+    if policy not in ("patch", "minor"):
+        print(
+            f"::warning::Unknown {_AUTO_BUMP_ENV}={policy!r}; "
+            f"falling back to fail-on-floor behavior",
+            file=sys.stderr,
+        )
+        return None
+    if not _persist_context_ok():
+        return None
+    new_version = version_utils.compute_next_version(target, floor, policy)
+    if not version_utils.write_marketing_version(new_version):
+        print(
+            f"::warning::auto-bump could not locate a writable "
+            f"MARKETING_VERSION source (pbxproj or Info.plist); "
+            f"falling back to fail-on-floor behavior",
+            file=sys.stderr,
+        )
+        return None
+    os.environ["MARKETING_VERSION"] = new_version
+    print(
+        f"::notice::mmv: auto-bumped {target} -> {new_version} "
+        f"(policy={policy}, ASC floor was {floor})",
+        file=sys.stderr,
+    )
+    return new_version
+
+
+def assert_target_meets_floor(
+    target: str, app_id: str, token: str,
+    *, appstore_versions: list[dict], strict: bool,
+) -> str:
+    """Reject when the floor outranks `target`. ``strict=True`` requires
+    target > floor (CREATE: a new row must not collide with anything
+    shipped/uploaded). ``strict=False`` allows target == floor (REUSE:
+    the editable matching target IS a floor contributor, so equality is
+    expected and fine).
+
+    Returns the effective target (which may differ from the input when
+    auto-bump fires on the non-strict pre-check). Callers MUST use the
+    returned value for any subsequent floor-relative reasoning, otherwise
+    they'd compare a stale target against the post-bump state.
+    """
+    floor, per_source = _resolve_floor(app_id, token, appstore_versions)
+    if floor is None:
+        return target
+    target_t, floor_t = semver_tuple(target), semver_tuple(floor)
+    ok = target_t > floor_t if strict else target_t >= floor_t
+    if ok:
+        relation = ">" if strict else ">="
+        print(f"[decision] floor_check OK: target={target} {relation} "
+              f"floor={floor}", file=sys.stderr)
+        return target
+    bumped = maybe_auto_bump(target, floor)
+    if bumped is not None:
+        return bumped
+    _floor_error(target, floor, per_source, strict=strict)
+    raise AssertionError("unreachable")  # _floor_error raises SystemExit

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

@@ -78,29 +78,24 @@ def _log(msg: str) -> None:
     print(msg, file=sys.stderr)
 
 
+# Apple's 409 STATE_ERROR detail string for the known-benign case where
+# the per-localization slot is locked because the parent version is
+# transitioning between states. Substring match (not regex / equality) so
+# we don't break if Apple appends or reformats surrounding context.
+_WHATSNEW_LOCKED_DETAIL = "cannot be edited at this time"
+
+
 def _patch_localization(
     token: str, localization_id: str, whats_new: str
 ) -> bool:
     """PATCH a single localization's whatsNew. Returns True on success,
     False when Apple reports the localization is locked (409 STATE_ERROR).
 
-    Apple returns 409 STATE_ERROR ("Attribute 'whatsNew' cannot be edited
-    at this time") on individual localizations even when the parent
-    appStoreVersion's appStoreState is in the editable allow-list checked
-    upstream. This happens when the per-localization state is locked
-    independently (e.g. submitted, in-review at the localization level,
-    or transitioning) -- a race the version-level state check at the top
-    of main() cannot see.
-
-    Without this allow-list, asc_common.request() raises SystemExit on
-    the 409, which the script's top-level try/except cannot swallow
-    (SystemExit is explicitly re-raised). The whole CI run then fails
-    at exit code 1 even though the IPA upload already succeeded.
-
-    Other non-2xx statuses (auth, 5xx, malformed payloads, real ASC
-    outages) are NOT in the allow-list and continue to fail loud --
-    asc_common.request() retries 5xx automatically and SystemExits on
-    everything else.
+    See _handle_localization_409 for the rationale behind allow_status={409}
+    and the benign-lock vs unexpected-409 routing. Other non-2xx statuses
+    (auth, 5xx, malformed payloads, real ASC outages) are NOT in the
+    allow-list and continue to fail loud -- asc_common.request() retries
+    5xx automatically and SystemExits on everything else.
     """
     resp = request(
         "PATCH",
@@ -116,16 +111,61 @@ def _patch_localization(
         allow_status={409},
     )
     if resp.status_code == 409:
-        _warn(
-            f"appStoreVersionLocalization {localization_id} returned 409 "
-            f"STATE_ERROR (locked); whatsNew not patched for this "
-            f"localization. Other localizations and the rest of the run "
-            f"continue."
-        )
+        _handle_localization_409(localization_id, resp)
         return False
     return True
 
 
+def _handle_localization_409(localization_id: str, resp) -> None:
+    """Route an ASC 409 STATE_ERROR on a localization PATCH to the right
+    log channel based on the response detail.
+
+    Apple returns 409 STATE_ERROR ("Attribute 'whatsNew' cannot be edited
+    at this time") on individual localizations even when the parent
+    appStoreVersion's appStoreState is in the editable allow-list checked
+    upstream. This happens when the per-localization state is locked
+    independently (e.g. submitted, in-review at the localization level,
+    or transitioning) -- a race the version-level state check at the top
+    of main() cannot see.
+
+    The benign-lock detail is logged plain -- it's the expected,
+    non-actionable case and emitting `::warning::` every clean run is
+    noise. Any OTHER 409 detail (genuinely unexpected) is surfaced as
+    `::warning::`.
+
+    ASC error envelope: ``{"errors": [{"status": "409", "code":
+    "STATE_ERROR", "detail": "Attribute 'whatsNew' cannot be edited at
+    this time"}]}``. We collapse every error.detail into one string so
+    the benign-lock substring match survives multi-error responses.
+    Falls back to raw response text if JSON parsing fails (network
+    layer occasionally returns HTML on infrastructure faults).
+    """
+    try:
+        body = resp.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict):
+        errors = body.get("errors") or []
+        parts = [e.get("detail") or e.get("title") or ""
+                 for e in errors if isinstance(e, dict)]
+        detail = " | ".join(p for p in parts if p)
+    else:
+        detail = resp.text or ""
+
+    if _WHATSNEW_LOCKED_DETAIL in detail:
+        _log(
+            f"[whatsNew] localization {localization_id} is currently "
+            f"locked, skipping (detail: {detail!r})"
+        )
+        return
+    _warn(
+        f"appStoreVersionLocalization {localization_id} returned 409 "
+        f"with unexpected detail {detail!r}; whatsNew not patched for "
+        f"this localization. Other localizations and the rest of the "
+        f"run continue."
+    )
+
+
 def _create_localization(
     token: str, version_id: str, locale: str, whats_new: str
 ) -> str:
@@ -178,7 +218,6 @@ def _update_all_localizations(
         f"/appStoreVersions/{version_id}/appStoreVersionLocalizations", token
     )
     entries = locs.get("data") or []
-
     if not entries:
         new_id = _create_localization(token, version_id, seed_locale, whats_new)
         _log(
@@ -186,7 +225,6 @@ def _update_all_localizations(
             f"{version} ({seed_locale}) -- no prior localizations"
         )
         return 1
-
     count = 0
     skipped = 0
     for item in entries:
@@ -204,10 +242,7 @@ def _update_all_localizations(
         else:
             skipped += 1
     if skipped:
-        _log(
-            f"whatsNew skipped for {skipped} locked localization(s) "
-            f"(see warnings above)"
-        )
+        _log(f"whatsNew skipped for {skipped} locked localization(s)")
     return count