gowalk-cicd 1.0.47 → 1.0.49

package/CLAUDE.md

@@ -149,6 +149,31 @@ node /path/to/gowalk-cicd/bin/cli.mjs
   must not discard the symbols of a build that is already live. Symbol
   artifacts carry no `retention-days` so the repository's setting governs and
   can be raised to cover a release's life.
+- Crashlytics symbol upload is gated on the `firebase-app-id` action input,
+  which `deploy.yml` feeds from the `FIREBASE_APP_ID` repository variable on
+  both actions. Actions never read `vars.*` themselves — an unavailable
+  context inside a composite action invalidates every consumer's workflow —
+  so the variable crosses the workflow/action boundary as an input and the
+  feature reaches consumers only after the one-off `npx gowalk-cicd` that
+  refreshes `deploy.yml`. The variable holds one id per platform
+  (`1:<n>:android:<hash>`, `1:<n>:ios:<hash>`, comma/whitespace-separated);
+  each action picks its own and fails on anything that is not an id. Android
+  runs `firebase crashlytics:symbols:upload` (the only Android path Firebase
+  documents; needs Node + Java, no credentials) on the `--split-debug-info`
+  directory — `android-action/scripts/crashlytics_symbols.py`. iOS runs the
+  FirebaseCrashlytics pod's `upload-symbols` on the archive's dSYMs —
+  `action/scripts/crashlytics_dsyms.py` — because Flutter's `.symbols` are
+  ELF debug info the Firebase CLI's generators reject for Apple targets, and
+  `App.framework.dSYM` is the documented Apple path. Both run before the
+  store upload and fail closed — except an iOS id on an app with no
+  FirebaseCrashlytics `upload-symbols` tool, which is a warn-and-skip: an app
+  that does not embed the SDK has nothing to symbolicate. Logic belongs in
+  those scripts, where it is unit-tested, not inline in YAML. Supporting
+  invariants: the workflow's disk-space step must never remove
+  `/usr/local/lib/node_modules` (npm and npx live there); `firebase-tools` is
+  pinned exactly because the Android job holds the keystore and the Play
+  service account; the CLI runs from a temp cwd so its `.crashlytics/` debris
+  never lands in the checkout.
 - The JDK is chosen by `scripts/select_jdk.py`, called from the workflow before
   `setup-java`. The `JAVA_VERSION` repo variable always wins; otherwise Flutter
   gets 17 and native Gradle gets 21, except that a positively-detected Kotlin

package/README.md

@@ -254,9 +254,11 @@ zip I/O error: No space left on device
 ```
 
 The Android job removes the preinstalled toolchains a Flutter build never uses
-(.NET, the Android NDK, GHC, PowerShell, Swift, Chromium, global node modules)
-and prunes Docker images, reclaiming roughly 25 GB in a few seconds. It prints
-`df -h /` before and after. Linux only; skipped in Bitrise mode.
+(.NET, the Android NDK, GHC, PowerShell, Swift, Chromium) and prunes Docker
+images, reclaiming roughly 25 GB in a few seconds. It prints `df -h /` before
+and after. Linux only; skipped in Bitrise mode. npm survives on purpose: the
+[Crashlytics symbol upload](#crashlytics-symbol-upload-firebase_app_id) runs
+the Firebase CLI through `npx`.
 
 ### Private git dependencies (Flutter)
 
@@ -493,14 +495,53 @@ flutter symbolize -i crash.txt -d app.android-arm64.symbols
 ```
 
 A crash reporter never sees the artifact, and from the first obfuscated build
-every Dart frame it shows is `***` until it has the symbols. If the app uses
-Crashlytics, Sentry or similar, upload the same directory to that service — for
-Crashlytics, `firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID>
-<dir>` with Firebase CLI 11.9 or newer, once per platform with that platform's
-app id (`mobilesdk_app_id` in `google-services.json`, `GOOGLE_APP_ID` in
-`GoogleService-Info.plist`). This package does not do that upload for you: the
-existing Crashlytics run-script phase on iOS uploads only the native dSYMs, and
-App Store Connect's own symbol upload covers only those as well.
+every Dart frame it shows is `***` until it has the symbols. For Crashlytics
+the workflow uploads them itself once the repository variable
+**`FIREBASE_APP_ID`** is set — see below. Sentry or others: upload the same
+directory to that service from your own pipeline.
+
+#### Crashlytics symbol upload (`FIREBASE_APP_ID`)
+
+Set the repository variable `FIREBASE_APP_ID` to the app's Firebase App ID —
+`1:<project number>:<platform>:<hash>`. An app that ships both platforms has
+two ids (they differ in the third segment); list both, separated by a comma:
+
+```
+1:123456789012:android:0a1b2c3d4e5f6a7b,1:123456789012:ios:7b6a5f4e3d2c1b0a
+```
+
+Find them in `lib/firebase_options.dart` (`appId`), in
+`android/app/google-services.json` (`mobilesdk_app_id`) and
+`ios/Runner/GoogleService-Info.plist` (`GOOGLE_APP_ID`), or under *Project
+settings → Your apps* in the Firebase console. No credentials are needed:
+both upload tools authenticate by app id alone.
+
+The variable reaches the actions through `deploy.yml`, which
+[auto-update never touches](#deployyml-is-not-auto-updated) — an existing repo
+must run `npx --yes gowalk-cicd` once before setting it does anything.
+
+| | Android | iOS |
+|---|---|---|
+| What is uploaded | the `--split-debug-info` directory, with the command Firebase documents for Flutter: `firebase crashlytics:symbols:upload --app=<android id> <dir>` (Firebase CLI through `npx`, major-pinned) | every dSYM in the archive — `App.framework.dSYM` carries the Dart frames — with the `upload-symbols` tool from the FirebaseCrashlytics pod: `upload-symbols -ai <ios id> -p ios -- <archive>/dSYMs` |
+| When | in the Android action, right after the build and before the bundle goes to Play | in the iOS action, right after the IPA export and before the TestFlight upload |
+| If it fails | the deploy fails; nothing ships with crashes nobody can read. The symbols are still in the `android-symbols-*` artifact for a manual upload | same — the failure lands before the TestFlight upload, so nothing shipped; fix the cause and re-run the deploy |
+| Variable unset | a `::warning::` when the app depends on `firebase_crashlytics` (every Dart frame will be `***`) | nothing — the run-script phase that `flutterfire configure` adds already uploads `App.framework.dSYM`, and the workflow installs the flutterfire CLI it needs |
+| Variable set for the other platform only | a `::warning::`, no upload | a `::notice::`, no upload |
+
+Why the two platforms differ: Flutter's `.symbols` files are ELF debug info,
+which the Firebase CLI's symbol generators accept for Android and reject for
+Apple targets; Firebase documents dSYMs as the Apple path, and Flutter 3.12+
+puts the Dart debug info into `App.framework.dSYM`. On iOS the explicit
+upload is a belt-and-braces over the run-script phase — it also covers the
+native `Runner.app.dSYM` and every plugin framework — so a phase that is
+missing or failing can never leave a build unreadable.
+
+A value that is not a Firebase App ID fails the deploy rather than being
+skipped: a typo must not become a fleet that silently stops uploading symbols.
+An iOS id on an app that does not embed Crashlytics (no `upload-symbols` tool
+anywhere under the project) is a warning, not a failure — an app without the
+SDK has no Crashlytics crashes to symbolicate. Android apps delivered through
+Bitrise are built by Bitrise and are not covered.
 
 Obfuscation renames identifiers, so code that depends on their spelling breaks
 at runtime, not at build time. Do not rely on `runtimeType.toString()`,
@@ -849,6 +890,9 @@ Changes that need that manual run:
 - **Flutter iOS obfuscation** — the `--obfuscate --split-debug-info` flags on
   the iOS `flutter build ios --config-only` call and the step that retains
   `ios-symbols-*`. See [Dart obfuscation](#dart-obfuscation-flutter-apps).
+- **Crashlytics symbol upload** — `firebase-app-id: ${{ vars.FIREBASE_APP_ID }}`
+  passed to both actions. Until it is, setting the variable does nothing.
+  See [Crashlytics symbol upload](#crashlytics-symbol-upload-firebase_app_id).
 
 ### Opt out
 

package/action/.daemux-version

@@ -1 +1 @@
-1.0.47
+1.0.49

package/action/action.yml

@@ -121,6 +121,17 @@ inputs:
     description: "GitHub Models model id for AI metadata generation."
     required: false
     default: "openai/gpt-4o"
+  firebase-app-id:
+    description: >-
+      Firebase App ID(s) for the Crashlytics dSYM upload — the
+      `1:<project number>:ios:<hash>` value (GOOGLE_APP_ID in
+      GoogleService-Info.plist, or Project settings → Your apps in the Firebase
+      console). Several ids may be listed, separated by commas or whitespace;
+      the iOS one is used. Empty leaves dSYM upload to the app's own
+      Crashlytics run-script phase. The package workflow passes the
+      FIREBASE_APP_ID repository variable.
+    required: false
+    default: ""
   # DESIGN DECISION: marketing-version-auto-bump trades unattended-CI
   # smoothness against silent-semver-decisions visibility. Default
   # 'rollover' lets CI keep the build moving when ASC's combined floor
@@ -705,6 +716,29 @@ runs:
           -exportPath "$RUNNER_TEMP/export"
         ls -la "$RUNNER_TEMP/export"
 
+    # Crashlytics symbolicates from the dSYMs in the archive — for a Flutter
+    # app that includes App.framework.dSYM, where the Dart frames of an
+    # obfuscated build come from, and the only Apple-platform path Firebase
+    # documents for such builds. The run-script phase `flutterfire configure`
+    # adds already uploads that dSYM during the archive; with firebase-app-id
+    # set (deploy.yml passes the FIREBASE_APP_ID repository variable) every
+    # dSYM in the archive is uploaded here as well, with the upload-symbols
+    # tool from the FirebaseCrashlytics pod, so a missing or broken phase
+    # cannot leave a build unreadable. Before the TestFlight upload on
+    # purpose: a failed upload fails the deploy instead of shipping crashes
+    # nobody can read. Logic and its tests live in scripts/crashlytics_dsyms.py.
+    - name: Upload dSYMs to Crashlytics
+      if: ${{ inputs.archive == 'true' && inputs.upload == 'true' && inputs.firebase-app-id != '' }}
+      shell: bash
+      env:
+        FIREBASE_APP_ID: ${{ inputs.firebase-app-id }}
+        PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
+        WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
+      run: |
+        python3 "${{ github.action_path }}/scripts/crashlytics_dsyms.py" \
+          --archive "$RUNNER_TEMP/app.xcarchive" \
+          --search-root "$(dirname "${WORKSPACE:-$PROJECT}")"
+
     - name: Upload to TestFlight
       if: ${{ inputs.archive == 'true' && inputs.upload == 'true' }}
       shell: bash

package/action/prompts/generate_descriptions.prompt.yml

@@ -12,8 +12,11 @@ messages:
       long description, generate ASO-optimized, guideline-compliant descriptions.
 
       STRICT RULES for description:
-      - description: 800-4000 chars. First 3 lines = hook + value prop (visible before Read More).
+      - description: 800-3800 chars. First 3 lines = hook + value prop (visible before Read More).
         Short paragraphs, line breaks, 3-5 bullet features, closing CTA.
+      - The delivery pipeline appends a two-line "Terms of Use: ... / Privacy Policy: ..."
+        footer after your text (that is why the ceiling is 3800, not 4000). Do NOT write
+        that footer, any legal link, or any URL yourself.
 
       CRITICAL:
       - You receive a JSON list of `locales_needing_description`. ONLY generate a

package/action/scripts/asc_metadata_applier.py

@@ -44,6 +44,15 @@ from metadata_constants import (
 APP_INFO_RESOURCE = "appInfoLocalizations"
 VERSION_RESOURCE = "appStoreVersionLocalizations"
 
+# Every App Store description ends with a functional Terms of Use link and the
+# app's own privacy-policy link (Apple's "no functional link to the Terms of
+# Use" metadata rejection). Terms is Apple's standard EULA; the privacy URL is
+# the locale's existing `privacyPolicyUrl`, which the panel sets and the
+# detector reads back into `state.localizations[locale].fields`.
+TERMS_URL = "https://www.apple.com/legal/internet-services/itunes/dev/stdeula/"
+DESCRIPTION_LIMIT = CHAR_LIMITS["description"]
+_FOOTER_SEPARATOR = "\n\n"
+
 # Collapses any run of ASCII whitespace (including the raw control chars AI
 # sometimes emits inside string literals: \n, \r, \t, and interior spaces)
 # into a single space. Applied after non-strict JSON load so field values
@@ -122,6 +131,60 @@ def _validate_field(field: str, value: Any) -> str | None:
     return trimmed
 
 
+def footer_for(privacy_url: str) -> str:
+    """The exact two-line footer appended to every generated description."""
+    return f"Terms of Use: {TERMS_URL}\nPrivacy Policy: {privacy_url}"
+
+
+def with_footer(body: str, privacy_url: str) -> str:
+    """Return ``body`` + one blank line + the footer, inside Apple's limit.
+
+    The body is shortened on a whitespace boundary when body + footer would
+    exceed the description limit; a hard cut happens only when the body has
+    no whitespace at or before the budget. The footer is never shortened.
+    """
+    footer = footer_for(privacy_url)
+    budget = DESCRIPTION_LIMIT - len(_FOOTER_SEPARATOR + footer)
+    text = body.rstrip()
+    if len(text) > budget:
+        cut = max(text.rfind(ch, 0, budget + 1) for ch in (" ", "\n", "\t"))
+        text = text[:cut] if cut > 0 else text[:budget]
+        text = text.rstrip()
+    return text + _FOOTER_SEPARATOR + footer
+
+
+def _describe_with_footer(
+    locale: str, loc_state: dict[str, Any], ver_writes: dict[str, str]
+) -> None:
+    """Attach the footer to a surviving generated description, in place.
+
+    Reads the locale's existing ``privacyPolicyUrl`` from the detector state.
+    An empty URL drops the description entirely (with a warning): a footer
+    with an empty privacy link would ship the exact defect this guards
+    against.
+    """
+    if "description" not in ver_writes:
+        return
+    privacy = ((loc_state.get("fields") or {}).get("privacyPolicyUrl") or "").strip()
+    if not privacy:
+        warn(
+            f"{locale}: privacyPolicyUrl is empty; skipping generated description "
+            "(footer requires it)"
+        )
+        del ver_writes["description"]
+        return
+    complete = with_footer(ver_writes["description"], privacy)
+    footer = footer_for(privacy)
+    if len(complete) > DESCRIPTION_LIMIT or not complete.endswith(footer):
+        warn(
+            f"{locale}: description with footer is invalid "
+            f"(length {len(complete)}); dropping"
+        )
+        del ver_writes["description"]
+        return
+    ver_writes["description"] = complete
+
+
 def _build_writes(
     ai_locale: dict[str, Any],
     empty_list: list[str],
@@ -248,6 +311,7 @@ def _apply_locale(
     """PATCH the writes for one locale. Returns count of fields written."""
     app_writes = _build_writes(ai_locale, empty_list, APP_LEVEL_FIELDS)
     ver_writes = _build_writes(ai_locale, empty_list, VERSION_LEVEL_FIELDS)
+    _describe_with_footer(locale, loc_state, ver_writes)
     return (
         _patch_group(token, APP_INFO_RESOURCE, locale,
                      loc_state.get("app_info_localization_id"), app_writes)

package/action/scripts/crashlytics_dsyms.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Upload every dSYM in the archive to Firebase Crashlytics.
+
+Crashlytics symbolicates Apple crashes from dSYMs. For a Flutter app that
+includes App.framework.dSYM, which is where the Dart frames come from — and
+the only Apple-platform path Firebase documents for Flutter's obfuscated,
+--split-debug-info builds (the .symbols files those flags write are ELF
+debug info that the Firebase CLI's symbol generators reject). The run-script
+phase `flutterfire configure` adds already uploads that one dSYM during the
+archive; this script uploads all of them (App.framework, the app binary,
+plugin frameworks) with the `upload-symbols` tool that ships in the
+FirebaseCrashlytics pod, so a missing or broken phase cannot leave a build
+unreadable, and native frames get their symbols too.
+
+    upload-symbols -ai <FIREBASE_APP_ID> -p ios -- <archive>/dSYMs
+
+No credentials: the tool authenticates by app id alone.
+
+Gating: FIREBASE_APP_ID holds the app's Firebase App ID(s),
+`1:<project number>:<platform>:<hash>`, comma- or whitespace-separated when an
+app ships both platforms; the iOS one is used and its absence is a notice, not
+a failure (the run-script phase is the documented default). With an iOS id
+present, a missing tool or a failed upload fails the step — the action runs it
+before the TestFlight upload, so a deploy never goes out with crashes nobody
+can read.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+APP_ID_RE = re.compile(r"^(\d+):(\d+):(android|ios|web):([0-9A-Fa-f]+)$")
+
+
+class AppIdError(ValueError):
+    """FIREBASE_APP_ID contains something that is not a Firebase App ID."""
+
+
+def parse_app_ids(raw: str) -> list[tuple[str, str]]:
+    """Split FIREBASE_APP_ID into (platform, app id) pairs; garbage is an error."""
+    ids: list[tuple[str, str]] = []
+    for token in re.split(r"[,\s]+", raw.strip()):
+        if not token:
+            continue
+        match = APP_ID_RE.match(token)
+        if match is None:
+            raise AppIdError(
+                f"{token!r} is not a Firebase App ID "
+                "(expected 1:<project number>:<android|ios|web>:<hash>)"
+            )
+        ids.append((match.group(3), token))
+    return ids
+
+
+def _pick(ids: list[tuple[str, str]], platform: str) -> str | None:
+    return next((app_id for found_platform, app_id in ids if found_platform == platform), None)
+
+
+def select_app_id(raw: str, platform: str) -> str | None:
+    return _pick(parse_app_ids(raw), platform)
+
+
+def find_upload_symbols(search_root: Path, home: Path | None = None) -> Path | None:
+    """Locate the FirebaseCrashlytics `upload-symbols` tool.
+
+    CocoaPods puts it at <ios dir>/Pods/FirebaseCrashlytics/upload-symbols; a
+    Swift Package Manager checkout keeps it under Xcode's DerivedData. Only a
+    tool whose parent directory names Crashlytics counts — the name alone is
+    too generic.
+    """
+    direct = search_root / "Pods" / "FirebaseCrashlytics" / "upload-symbols"
+    if direct.is_file():
+        return direct
+    if search_root.is_dir():
+        # A project at the repo root makes search_root the whole checkout, so
+        # prune the trees that are big and can never hold the tool.
+        prune = {".git", "build", ".dart_tool", "node_modules"}
+        hits: list[Path] = []
+        for dirpath, dirnames, filenames in os.walk(search_root):
+            dirnames[:] = [d for d in dirnames if d not in prune]
+            if "upload-symbols" in filenames and Path(dirpath).name in ("FirebaseCrashlytics", "Crashlytics"):
+                candidate = Path(dirpath) / "upload-symbols"
+                if candidate.is_file():
+                    hits.append(candidate)
+        if hits:
+            return sorted(hits)[0]
+    home = Path.home() if home is None else home
+    derived = home / "Library" / "Developer" / "Xcode" / "DerivedData"
+    for candidate in sorted(
+        derived.glob("*/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/upload-symbols")
+    ):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def upload_command(tool: Path, app_id: str, dsyms_dir: Path) -> list[str]:
+    return [str(tool), "-ai", app_id, "-p", "ios", "--", str(dsyms_dir)]
+
+
+def _default_run(cmd: list[str]) -> int:
+    try:
+        return subprocess.run(cmd, check=False).returncode
+    except OSError as exc:
+        print(f"::error::could not run {cmd[0]}: {exc}")
+        return 126
+
+
+def main(argv: list[str] | None = None, environ: dict[str, str] | None = None, run=None,
+         home: Path | None = None) -> int:
+    environ = os.environ if environ is None else environ
+    run = _default_run if run is None else run
+
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--archive", required=True, type=Path, help="the .xcarchive that was exported")
+    parser.add_argument("--search-root", required=True, type=Path,
+                        help="directory holding the Xcode project/workspace (where Pods/ lives)")
+    args = parser.parse_args(argv)
+
+    raw = environ.get("FIREBASE_APP_ID", "")
+    try:
+        ids = parse_app_ids(raw)
+    except AppIdError as exc:
+        print(f"::error::FIREBASE_APP_ID: {exc}")
+        return 1
+
+    app_id = _pick(ids, "ios")
+    if app_id is None:
+        if ids:
+            print(
+                "::notice::FIREBASE_APP_ID names no iOS app (1:<project number>:ios:<hash>); "
+                "relying on the Crashlytics run-script phase for dSYM upload."
+            )
+        else:
+            print("FIREBASE_APP_ID unset; relying on the Crashlytics run-script phase for dSYM upload.")
+        return 0
+
+    dsyms_dir = args.archive / "dSYMs"
+    dsyms = sorted(dsyms_dir.glob("*.dSYM")) if dsyms_dir.is_dir() else []
+    if not dsyms:
+        print(f"::error::no dSYMs in {dsyms_dir}; nothing to upload to Crashlytics")
+        return 1
+
+    tool = find_upload_symbols(args.search_root, home)
+    if tool is None:
+        # No tool means the app does not link the Crashlytics SDK, so there are
+        # no Crashlytics crash reports to symbolicate — skipping loses nothing,
+        # while failing would block every release of a non-Crashlytics app
+        # whose FIREBASE_APP_ID happens to carry an iOS id.
+        print(
+            "::warning::FIREBASE_APP_ID names an iOS app but no FirebaseCrashlytics "
+            f"upload-symbols tool exists under {args.search_root} or Xcode's "
+            "DerivedData, so the app does not appear to embed Crashlytics; "
+            "skipping the dSYM upload. (`flutterfire configure` adds the "
+            "dependency and the run-script phase.)"
+        )
+        return 0
+
+    cmd = upload_command(tool, app_id, dsyms_dir)
+    print(f"Uploading {len(dsyms)} dSYM(s) to Crashlytics app {app_id}:")
+    for dsym in dsyms:
+        print(f"  {dsym.name}")
+    print("  " + " ".join(cmd))
+    rc = run(cmd)
+    if rc != 0:
+        print(
+            f"::error::Crashlytics dSYM upload failed (exit {rc}). This step runs "
+            "before the TestFlight upload, so nothing shipped — fix the cause and "
+            "re-run the deploy."
+        )
+        return 1
+    print(f"Uploaded dSYMs to Crashlytics app {app_id}.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/action/scripts/test_asc_metadata_applier.py

@@ -22,6 +22,10 @@ import asc_metadata_applier as mod  # noqa: E402
 
 
 TOKEN = "TEST_TOKEN"
+# Every real listing the detector reads back carries the panel-set privacy
+# URL; the applier appends the Terms/Privacy footer to generated descriptions
+# from it, and SKIPS the description when it is empty.
+PRIVACY = "https://docs.google.com/document/d/e/abc/pub"
 
 
 def _state(empty_fields, localizations=None):
@@ -34,14 +38,18 @@ def _state(empty_fields, localizations=None):
     }
 
 
-def _loc(app_id="app-en", ver_id="ver-en"):
+def _loc(app_id="app-en", ver_id="ver-en", privacy=PRIVACY):
     return {
         "app_info_localization_id": app_id,
         "version_localization_id": ver_id,
-        "fields": {},
+        "fields": {"privacyPolicyUrl": privacy},
     }
 
 
+def _desc(body):
+    return mod.with_footer(body, PRIVACY)
+
+
 class ValidateFieldTests(unittest.TestCase):
     def test_returns_trimmed_value_under_limit(self):
         self.assertEqual(mod._validate_field("name", "  MyApp  "), "MyApp")
@@ -268,7 +276,7 @@ class ApplyTests(unittest.TestCase):
         self.assertEqual(total, 1)
         self.assertEqual(mock_req.call_count, 1)
         attrs = mock_req.call_args.kwargs["json_body"]["data"]["attributes"]
-        self.assertEqual(attrs, {"description": "Nice app."})
+        self.assertEqual(attrs, {"description": _desc("Nice app.")})
 
     @mock.patch.object(mod, "request")
     def test_double_gate_drops_field_not_in_empty_list(self, mock_req):
@@ -351,7 +359,7 @@ class MainTests(unittest.TestCase):
             mock_req.call_args.args[1], "/appStoreVersionLocalizations/ver-en"
         )
         attrs = mock_req.call_args.kwargs["json_body"]["data"]["attributes"]
-        self.assertEqual(attrs, {"description": "Hi"})
+        self.assertEqual(attrs, {"description": _desc("Hi")})
 
     @mock.patch.dict("os.environ", ENV_FAKE)
     @mock.patch.object(mod, "make_jwt", return_value=TOKEN)
@@ -675,7 +683,7 @@ class ApplyWithFieldsFilterTests(unittest.TestCase):
         self.assertEqual(locales, 1)
         self.assertEqual(mock_req.call_count, 1)
         attrs = mock_req.call_args.kwargs["json_body"]["data"]["attributes"]
-        self.assertEqual(attrs, {"description": "Desc"})
+        self.assertEqual(attrs, {"description": _desc("Desc")})
 
     @mock.patch.object(mod, "request")
     def test_filter_excludes_description(self, mock_req):
@@ -777,7 +785,7 @@ class MainFieldsFilterTests(unittest.TestCase):
         self.assertEqual(rc, 0)
         self.assertEqual(mock_req.call_count, 1)
         attrs = mock_req.call_args.kwargs["json_body"]["data"]["attributes"]
-        self.assertEqual(attrs, {"description": "Desc"})
+        self.assertEqual(attrs, {"description": _desc("Desc")})
 
     @mock.patch.dict("os.environ", ENV_FAKE)
     @mock.patch.object(mod, "make_jwt", return_value=TOKEN)
@@ -831,6 +839,138 @@ class MainFieldsFilterTests(unittest.TestCase):
         self.assertEqual(mock_req.call_count, 2)
 
 
+class DescriptionFooterTests(unittest.TestCase):
+    """Every generated description ends with the two-line Terms/Privacy footer
+    taken from the locale's existing privacyPolicyUrl; no URL, no description."""
+
+    def test_footer_text_is_exact(self):
+        self.assertEqual(
+            mod.footer_for("https://p.example/privacy"),
+            "Terms of Use: https://www.apple.com/legal/internet-services/itunes/dev/stdeula/"
+            "\nPrivacy Policy: https://p.example/privacy",
+        )
+
+    def test_footer_is_appended_verbatim_as_the_last_two_lines(self):
+        out = mod.with_footer("Great app.\n\n- fast\n- small", PRIVACY)
+        lines = out.split("\n")
+        self.assertEqual(lines[-3], "")  # one blank line separates body and footer
+        self.assertEqual(lines[-2], f"Terms of Use: {mod.TERMS_URL}")
+        self.assertEqual(lines[-1], f"Privacy Policy: {PRIVACY}")
+        self.assertTrue(out.startswith("Great app.\n\n- fast\n- small"))
+
+    def test_short_body_is_not_shortened(self):
+        self.assertEqual(mod.with_footer("Hello", PRIVACY),
+                         "Hello\n\n" + mod.footer_for(PRIVACY))
+
+    def test_long_body_is_shortened_on_a_whitespace_boundary(self):
+        body = " ".join(["word"] * 1200)  # 5999 chars, spaces every 5th char
+        out = mod.with_footer(body, PRIVACY)
+        footer = mod.footer_for(PRIVACY)
+        self.assertLessEqual(len(out), mod.DESCRIPTION_LIMIT)
+        self.assertTrue(out.endswith("\n\n" + footer))
+        kept = out[: -len("\n\n" + footer)]
+        self.assertTrue(kept.endswith("word"))       # cut between words, not inside
+        self.assertFalse(kept.endswith(" "))          # trailing whitespace stripped
+        # the budget is used, not wasted: at most one word's width short
+        self.assertGreater(len(out), mod.DESCRIPTION_LIMIT - 6)
+
+    def test_body_exactly_at_budget_keeps_every_character(self):
+        footer = mod.footer_for(PRIVACY)
+        budget = mod.DESCRIPTION_LIMIT - len("\n\n" + footer)
+        body = ("ab " * budget)[:budget].rstrip()
+        out = mod.with_footer(body, PRIVACY)
+        self.assertEqual(out, body + "\n\n" + footer)
+        self.assertLessEqual(len(out), mod.DESCRIPTION_LIMIT)
+
+    def test_body_without_whitespace_is_hard_cut(self):
+        out = mod.with_footer("x" * 5000, PRIVACY)
+        self.assertEqual(len(out), mod.DESCRIPTION_LIMIT)
+        self.assertTrue(out.endswith("\n\n" + mod.footer_for(PRIVACY)))
+
+    @mock.patch.object(mod, "request")
+    def test_locale_with_privacy_url_patches_description_with_footer(self, mock_req):
+        written = mod._apply_locale(
+            TOKEN, "en-US", _loc("app-en", "ver-en"),
+            {"description": "Hello"}, ["description"],
+        )
+        self.assertEqual(written, 1)
+        attrs = mock_req.call_args.kwargs["json_body"]["data"]["attributes"]
+        self.assertEqual(attrs, {"description": "Hello\n\n" + mod.footer_for(PRIVACY)})
+
+    @mock.patch.object(mod, "warn")
+    @mock.patch.object(mod, "request")
+    def test_empty_privacy_url_skips_description_but_not_other_fields(
+            self, mock_req, mock_warn):
+        written = mod._apply_locale(
+            TOKEN, "en-US", _loc("app-en", "ver-en", privacy=""),
+            {"name": "MyApp", "description": "Hello", "keywords": "k1,k2"},
+            ["name", "description", "keywords"],
+        )
+        self.assertEqual(written, 2)
+        patched = [next(iter(c.kwargs["json_body"]["data"]["attributes"]))
+                   for c in mock_req.call_args_list]
+        self.assertEqual(sorted(patched), ["keywords", "name"])
+        self.assertTrue(any("privacyPolicyUrl is empty" in c.args[0]
+                            for c in mock_warn.call_args_list))
+        for call in mock_req.call_args_list:
+            self.assertNotIn("Terms of Use", json.dumps(call.kwargs["json_body"]))
+
+    @mock.patch.object(mod, "warn")
+    @mock.patch.object(mod, "request")
+    def test_missing_fields_block_skips_description(self, mock_req, mock_warn):
+        loc = {"app_info_localization_id": "app-en", "version_localization_id": "ver-en"}
+        written = mod._apply_locale(
+            TOKEN, "en-US", loc, {"description": "Hello"}, ["description"])
+        self.assertEqual(written, 0)
+        mock_req.assert_not_called()
+        self.assertEqual(mock_warn.call_count, 1)
+
+    @mock.patch.object(mod, "request")
+    def test_whitespace_only_privacy_url_counts_as_empty(self, mock_req):
+        written = mod._apply_locale(
+            TOKEN, "en-US", _loc("app-en", "ver-en", privacy="   "),
+            {"description": "Hello"}, ["description"])
+        self.assertEqual(written, 0)
+        mock_req.assert_not_called()
+
+    @mock.patch.object(mod, "request")
+    def test_run_without_description_is_unaffected(self, mock_req):
+        written = mod._apply_locale(
+            TOKEN, "en-US", _loc("app-en", "ver-en", privacy=""),
+            {"name": "MyApp", "keywords": "k1,k2"}, ["name", "keywords"])
+        self.assertEqual(written, 2)
+        self.assertEqual(mock_req.call_count, 2)
+
+    @mock.patch.object(mod, "request")
+    def test_generated_description_over_budget_ships_inside_the_limit(self, mock_req):
+        body = " ".join(["benefit"] * 480)  # under 4000 on its own, over with footer
+        self.assertLessEqual(len(body), mod.DESCRIPTION_LIMIT)
+        written = mod._apply_locale(
+            TOKEN, "en-US", _loc("app-en", "ver-en"),
+            {"description": body}, ["description"])
+        self.assertEqual(written, 1)
+        value = mock_req.call_args.kwargs["json_body"]["data"]["attributes"]["description"]
+        self.assertLessEqual(len(value), mod.DESCRIPTION_LIMIT)
+        self.assertTrue(value.endswith(mod.footer_for(PRIVACY)))
+
+    @mock.patch.object(mod, "request")
+    def test_apply_end_to_end_carries_the_footer_per_locale(self, mock_req):
+        state = _state(
+            empty_fields={"en-US": ["description"], "ja": ["description"]},
+            localizations={
+                "en-US": _loc("app-en", "ver-en", privacy="https://p.example/en"),
+                "ja": _loc("app-ja", "ver-ja", privacy=""),
+            },
+        )
+        ai = {"localizations": {"en-US": {"description": "Hi"},
+                                "ja": {"description": "こんにちは"}}}
+        total, locales = mod.apply(state, ai, TOKEN, fields_filter={"description"})
+        self.assertEqual((total, locales), (1, 1))
+        attrs = mock_req.call_args.kwargs["json_body"]["data"]["attributes"]
+        self.assertEqual(attrs["description"],
+                         "Hi\n\n" + mod.footer_for("https://p.example/en"))
+
+
 class NormalizeWhitespaceTests(unittest.TestCase):
     def test_collapses_embedded_newlines(self):
         self.assertEqual(mod._normalize_whitespace("a\nb"), "a b")