Skip to content
Merged
26 changes: 26 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,3 +171,29 @@ unified press click source on each of the five routes. Use GA4 DebugView to
verify one `press_app_click` per real press link click and one
`download_click` per *Play* click, without counting app detail clicks
as installs. Store acquired users must be verified separately in Play Console.


## Fail-closed offline preflight before VPS publishing (2026-11-13)

The app-discovery publish command now runs a local Python stdlib-only source
integrity check **before both --dry-run and --apply**. It fails and sends no
files if a broken Google Play package link, duplicated/missing catalog card,
incorrect schema count, missing 5-language catalog interface, incorrect press
canonical/hreflang/sitemap, missing support destination or incorrect
press-to-store analytics identity is detected.

Run from the intended production checkout:

```bash
python3 -m unittest scripts.test_preflight_app_discovery scripts.test_publish_preflight_gate -v
python3 scripts/preflight_app_discovery.py
bash scripts/publish_app_discovery.sh --dry-run
```

The JSON report marks `source_only: true`. A PASS proves only that
the checked-out source files agree; it does **not** prove that the domain is
already updated, that the Play listing is available in every country, or
that first-time app installs increased. After reviewing the dry-run destination
and file list on the authorized host, use the existing `--apply` flag,
then the live-smoke scripts. Preserve a rollback copy or backup before applying.
Do not execute an unintended VPS transfer just because the source preflight passes.
182 changes: 182 additions & 0 deletions scripts/preflight_app_discovery.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
#!/usr/bin/env python3
"""Offline, read-only preflight for the SK Apps website acquisition release.

Run: python3 scripts/preflight_app_discovery.py
No remote network, credentials, publishing, DNS, analytics, or store changes.
This verifies *source files* only; successful preflight is not live deployment.
"""
import argparse
import json
import re
import sys
from html.parser import HTMLParser
from pathlib import Path
from urllib.parse import parse_qs, urlsplit
from xml.etree import ElementTree

ORIGIN = "https://appdevelopsk.com"
PRESS = {
"en": "press/index.html",
"es": "press/es/index.html",
"pt-BR": "press/pt-br/index.html",
"ja": "press/ja/index.html",
"id": "press/id/index.html",
}
PILOTS = {"blur", "twotaku", "instant-judge", "debate-me", "future-me"}


def page_url(filename):
return ORIGIN + "/" + filename.removesuffix("index.html")


def play_package(href):
parts = urlsplit(href)
ids = parse_qs(parts.query).get("id", [])
if (parts.scheme != "https" or parts.hostname != "play.google.com"
or parts.username or parts.password
or parts.path != "/store/apps/details" or len(ids) != 1
or not re.fullmatch(r"[A-Za-z0-9_.]+", ids[0])):
return None
return ids[0]


class Markup(HTMLParser):
def __init__(self):
super().__init__(convert_charrefs=True)
self.tags = []
self.cards = []
self.current_card = None

def handle_starttag(self, tag, attrs):
a = dict(attrs)
self.tags.append((tag, a))
if tag == "a" and "app-card" in a.get("class", "").split():
if self.current_card is not None:
raise ValueError("Nested catalog cards")
self.current_card = {"package": play_package(a.get("href", "")), "slug": None}
elif tag == "img" and self.current_card is not None:
match = re.fullmatch(r"icons/apps/([a-z0-9-]+)\.png", a.get("src", ""))
if match:
self.current_card["slug"] = match.group(1)

def handle_endtag(self, tag):
if tag == "a" and self.current_card is not None:
self.cards.append(self.current_card)
self.current_card = None


def load_html(root, filename):
return (root / filename).read_text(encoding="utf-8")


def parse_html(text):
parser = Markup()
parser.feed(text)
return parser


def verify(root):
errors = []
result = {"source_only": True, "catalog_cards": 0, "press_locales": {}, "ok": False}
try:
catalog = load_html(root, "apps.html")
doc = parse_html(catalog)
except (OSError, UnicodeError, ValueError) as exc:
return {**result, "errors": ["apps.html unavailable or malformed: " + type(exc).__name__]}

cards = doc.cards
result["catalog_cards"] = len(cards)
if len(cards) != 92:
errors.append("Catalog must contain exactly 92 verified Play cards")
if any(not c["package"] or not c["slug"] for c in cards):
errors.append("Catalog card has invalid Google Play URL or icon slug")
slugs = [c["slug"] for c in cards]
packages = [c["package"] for c in cards]
if len(set(slugs)) != len(cards) or len(set(packages)) != len(cards):
errors.append("Catalog has duplicate slug or Play package")
if not re.search(r'"numberOfItems"\s*:\s*92\b', catalog):
errors.append("Catalog JSON-LD item count differs from 92 cards")
if not PILOTS.issubset(set(slugs)):
errors.append("A pilot app is absent from catalog")
if not all(x in catalog for x in ('id="catalog-language"', "catalog_language_selected", "download_click")):
errors.append("Catalog five-language UI or GA4 outbound tracking missing")
for lang in PRESS:
if 'option value="' + lang + '"' not in catalog:
errors.append("Catalog language selector missing " + lang)

mapped = {c["slug"]: c["package"] for c in cards}
expected_hreflang = {lang: page_url(filename) for lang, filename in PRESS.items()}
expected_hreflang["x-default"] = expected_hreflang["en"]
for lang, filename in PRESS.items():
checks = []
try:
html = load_html(root, filename)
p = parse_html(html)
nodes = p.tags
links = [a for tag, a in nodes if tag == "link"]
actual_langs = [a.get("lang") for tag, a in nodes if tag == "html"]
canonicals = [a.get("href") for a in links if a.get("rel") == "canonical"]
alternates = [a for a in links if a.get("rel") == "alternate"]
actual_hreflang = {a.get("hreflang"): a.get("href") for a in alternates}
anchors = [a for tag, a in nodes if tag == "a" and a.get("data-cta")]
details = [a for a in anchors if a.get("data-cta") == "details"]
stores = [a for a in anchors if a.get("data-cta") == "store"]
if actual_langs != [lang]:
checks.append("html lang")
if canonicals != [page_url(filename)]:
checks.append("canonical")
if len(alternates) != len(expected_hreflang) or actual_hreflang != expected_hreflang:
checks.append("reciprocal hreflang")
if len(details) != 5 or len(stores) != 5 or len(anchors) != 10:
checks.append("five detail and store CTAs")
if sum(tag == "article" for tag, _ in nodes) != 5 or sum(tag == "h1" for tag, _ in nodes) != 1:
checks.append("five app cards and one H1")
if "press_app_click" not in html or "'download_click'" not in html:
checks.append("GA4 press/store event contract")
for cta, group in (("details", details), ("store", stores)):
if {a.get("data-app-slug") for a in group} != PILOTS:
checks.append(cta + " app slug coverage")
for a in group:
slug = a.get("data-app-slug")
pkg = a.get("data-app-package")
if not slug or pkg != mapped.get(slug):
checks.append(cta + " catalog package mismatch")
if cta == "details":
if a.get("href") != "/support/" + str(slug) + "/":
checks.append("detail support destination mismatch")
elif not (root / "support" / slug / "index.html").is_file():
checks.append("missing support page")
elif play_package(a.get("href", "")) != pkg:
checks.append("store destination mismatch")
result["press_locales"][lang] = "pass" if not checks else "fail"
errors.extend(lang + ": " + problem for problem in sorted(set(checks)))
except (OSError, UnicodeError, ValueError) as exc:
result["press_locales"][lang] = "fail"
errors.append(lang + ": source unavailable or malformed (" + type(exc).__name__ + ")")

try:
root_xml = ElementTree.parse(root / "sitemap.xml").getroot()
locations = {(node.text or "").strip() for node in root_xml.iter()
if node.tag.rsplit("}", 1)[-1] == "loc"}
for lang, url in expected_hreflang.items():
if lang != "x-default" and url not in locations:
errors.append("sitemap missing " + lang + " press URL")
except (OSError, ElementTree.ParseError) as exc:
errors.append("sitemap.xml unavailable or invalid: " + type(exc).__name__)

result["errors"] = sorted(set(errors))
result["ok"] = not errors
return result


def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[1])
args = parser.parse_args()
report = verify(args.root)
print(json.dumps(report, ensure_ascii=False, sort_keys=True, indent=2))
return 0 if report["ok"] else 1


if __name__ == "__main__":
sys.exit(main())
5 changes: 5 additions & 0 deletions scripts/publish_app_discovery.sh
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,11 @@ files=(index.html apps.html sitemap.xml robots.txt guides/quick-games/index.html
for file in "${files[@]}"; do
[[ -s "$file" ]] || { echo "Missing source file: $file" >&2; exit 2; }
done
# Fail closed before preview or transfer if 92 app mappings, five localized
# press pages, canonical/hreflang, source GA4 contracts, or sitemap drift.
# This check is purely local and prints a source-only JSON report.
command -v python3 >/dev/null 2>&1 || { echo 'python3 required for safe publish preflight' >&2; exit 2; }
python3 scripts/preflight_app_discovery.py
echo "Source checkout: $(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
echo "Target: $host:$root; mode: $mode"
# --relative recreates only the listed nested file paths. No --delete.
Expand Down
102 changes: 102 additions & 0 deletions scripts/test_preflight_app_discovery.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
"""Source preflight and deliberate corruption tests.

Run from repo root:
python3 -m unittest scripts.test_preflight_app_discovery -v
"""
import importlib.util
import shutil
import tempfile
import unittest
from pathlib import Path

FILE = Path(__file__).with_name("preflight_app_discovery.py")
SPEC = importlib.util.spec_from_file_location("preflight_app_discovery", FILE)
checker = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(checker)
ROOT = Path(__file__).resolve().parents[1]


class PreflightTests(unittest.TestCase):
def test_current_source_passes(self):
result = checker.verify(ROOT)
self.assertTrue(result["ok"], result["errors"])
self.assertEqual(result["catalog_cards"], 92)
self.assertEqual(result["press_locales"], {x: "pass" for x in checker.PRESS})

def fixture_root(self, dest):
for source in ["apps.html", "sitemap.xml", *checker.PRESS.values(),
*["support/" + slug + "/index.html" for slug in checker.PILOTS]]:
target = dest / source
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(ROOT / source, target)

def test_invalid_localized_canonical_is_rejected(self):
with tempfile.TemporaryDirectory() as work:
root = Path(work)
self.fixture_root(root)
page = root / checker.PRESS["ja"]
text = page.read_text(encoding="utf-8")
self.assertIn(checker.page_url(checker.PRESS["ja"]), text)
page.write_text(text.replace(
checker.page_url(checker.PRESS["ja"]),
"https://bad.example/press/ja/", 1), encoding="utf-8")
result = checker.verify(root)
self.assertFalse(result["ok"])
self.assertIn("ja: canonical", result["errors"])

def test_changed_play_package_or_card_count_is_rejected(self):
with tempfile.TemporaryDirectory() as work:
root = Path(work)
self.fixture_root(root)
page = root / "apps.html"
text = page.read_text(encoding="utf-8")
self.assertIn('class="app-card"', text)
page.write_text(text.replace('class="app-card"', 'class="other-card"', 1),
encoding="utf-8")
result = checker.verify(root)
self.assertFalse(result["ok"])
self.assertTrue(any("92" in s for s in result["errors"]))

def test_missing_sitemap_entry_is_rejected(self):
with tempfile.TemporaryDirectory() as work:
root = Path(work)
self.fixture_root(root)
file = root / "sitemap.xml"
content = file.read_text(encoding="utf-8")
self.assertIn(checker.page_url(checker.PRESS["id"]), content)
file.write_text(content.replace(
checker.page_url(checker.PRESS["id"]),
"https://bad.example/press/id/"), encoding="utf-8")
result = checker.verify(root)
self.assertFalse(result["ok"])
self.assertIn("sitemap missing id press URL", result["errors"])

def test_mismatched_app_tracking_identity_is_rejected(self):
with tempfile.TemporaryDirectory() as work:
root = Path(work)
self.fixture_root(root)
file = root / checker.PRESS["es"]
content = file.read_text(encoding="utf-8")
self.assertIn('data-app-package="com.blurapp.blur_app"', content)
file.write_text(content.replace(
'data-app-package="com.blurapp.blur_app"',
'data-app-package="com.example.wrong"'), encoding="utf-8")
result = checker.verify(root)
self.assertFalse(result["ok"])
self.assertIn("es: details catalog package mismatch", result["errors"])
self.assertIn("es: store catalog package mismatch", result["errors"])

def test_bad_play_url_is_never_accepted(self):
self.assertIsNone(checker.play_package("https://evil.example/store/apps/details?id=com.blurapp.blur_app"))
self.assertIsNone(checker.play_package("https://fakeuser@play.google.com/store/apps/details?id=com.blurapp.blur_app"))
self.assertIsNone(checker.play_package("https://play.google.com/store/apps/details?id=com.a&id=com.b"))
self.assertEqual(checker.play_package(
"https://play.google.com/store/apps/details?id=com.blurapp.blur_app&hl=en"
), "com.blurapp.blur_app") # Extra escaped query params do not corrupt the package ID
self.assertEqual(checker.play_package(
"https://play.google.com/store/apps/details?id=com.blurapp.blur_app&hl=en"
), "com.blurapp.blur_app")


if __name__ == "__main__":
unittest.main()
36 changes: 36 additions & 0 deletions scripts/test_publish_preflight_gate.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
"""Verify source preflight is mandatory before any VPS rsync.

Run: python3 -m unittest scripts.test_publish_preflight_gate -v
"""
import unittest
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]


class PublishGateTests(unittest.TestCase):
def test_offline_preflight_runs_before_transfer(self):
script = (ROOT / "scripts/publish_app_discovery.sh").read_text(encoding="utf-8")
check = "python3 scripts/preflight_app_discovery.py"
self.assertEqual(script.count(check), 1)
self.assertLess(script.index(check), script.index("rsync $rsync_flags"))
self.assertIn('--dry-run) flags=(--dry-run)', script)
self.assertIn('--apply) flags=()', script)

def test_publish_does_not_deploy_on_source_preflight_error(self):
script = (ROOT / "scripts/publish_app_discovery.sh").read_text(encoding="utf-8")
self.assertIn("set -euo pipefail", script)
self.assertIn("Missing source file:", script)
self.assertIn("python3 required for safe publish preflight", script)
self.assertNotIn("|| true", script)
self.assertNotIn("rsync --delete", script)

def test_preflight_is_explicitly_source_only(self):
source = (ROOT / "scripts/preflight_app_discovery.py").read_text(encoding="utf-8")
self.assertIn('"source_only": True', source)
for forbidden in ("urlopen(", "subprocess.run(", "os.system(", "socket.connect("):
self.assertNotIn(forbidden, source)


if __name__ == "__main__":
unittest.main()
Loading