Scripts¶
Catalog of the helper scripts in scripts/, backend/scripts/ and frontend/scripts/. Each tree is grouped by category: dev/ (local development and QA), ci/ (checks run by CI or task verify), gen/ (code and asset generators), release/ (versioning and shipping), seed/ (location seed data). Task names do not change when a script moves, so prefer task --list over calling a script directly.
scripts/ci/check-scripts-doc.sh fails when a script is added, moved or removed without updating the tables here. Only the first column of each table counts, so keep one row per script.
Repo scripts (scripts/)¶
dev/¶
| Script | What it does | Invoked by |
|---|---|---|
scripts/dev/dev-host-ip.sh |
Prints the LAN IPv4 that devices use to reach this machine: the default-route interface first (a wired adapter beats Wi-Fi), skipping loopback, VPN and bridges; empty when none. | task dev, frontend:sync-env, scripts/dev/backend-run.sh, dev-metro.sh, and the iOS Debug device build (via frontend/plugins/with-dev-host-ip.js); by hand to debug a device that cannot reach the backend. |
scripts/dev/backend-run.sh |
Backend half of task dev: pins the storage host to the LAN IP, loads GCP secrets when authenticated, starts the docs site, runs the API under Air. |
task dev:run (via task dev). |
scripts/dev/sync-frontend-env.sh |
Pins EXPO_PUBLIC_API_URL and EXPO_PUBLIC_WS_URL in frontend/.env.local to the LAN IP. |
task frontend:sync-env, a dependency of every frontend dev task. |
scripts/dev/dev-ios-all.sh |
Builds the iOS dev client for the booted Simulator and a USB iPhone one after the other (separate build folders, signing from app.config.js), installs and launches on both, then starts Metro through dev-metro.sh. Logs go to logs/build-ios-sim.log and logs/build-ios-device.log. |
task dev:ios:all after a native change, with Xcode closed. |
scripts/dev/dev-metro.sh |
Starts Metro for the dev client on the same LAN address as the API (dev-host-ip.sh, so a wired Mac serves bundles over Ethernet) and mirrors Metro and device logs to logs/ (metro.log, ios-device.log, ios-sim.log, android.log). |
task dev:frontend, dev:frontend:clear, the iOS device and Android tasks. |
scripts/dev/pull-secrets.sh |
Pulls backend secrets from GCP Secret Manager and exports them or execs the backend with them; nothing is written to disk. See below. |
scripts/dev/backend-run.sh; by hand for local dev. |
scripts/dev/py-tool.sh |
Runs a Python dev tool (sqlfluff, mkdocs) from .venv-tools/ or PATH, failing with an install hint when absent. |
task db:sql:lint, db:sql:format, docs, docs:build. |
scripts/dev/setup-python-tools.sh |
Creates .venv-tools/ with the pinned sqlfluff and the docs requirements. |
task setup:python-tools (via task setup). |
scripts/dev/wait-for-healthy.sh |
Polls docker inspect until the named containers are healthy, with a timeout. |
task docker:wait (via task dev, db:reset). |
scripts/dev/setup-capture.sh |
One-shot, idempotent bring-up of the link-capture pipeline: prerequisites, Go deps, local stack, capture env keys in backend/.env.local; WITH_OLLAMA=1 adds a local Ollama and the resolver model. |
By hand, the first time you capture a link locally. |
scripts/dev/run_e2e.sh |
Boots the compose stack, waits for backend and frontend, runs the Playwright suite in e2e/, optionally tears down. See below. |
By hand; not wired into CI. |
scripts/dev/flow-validation-scan.sh |
Dumps backend route verbs and paths plus the frontend route tree to .flow-validation/surface.txt with a hash, to detect a stale flow inventory. |
By hand, from the app-qa skill. |
ci/¶
| Script | What it does | Invoked by |
|---|---|---|
scripts/ci/check-scripts-doc.sh |
Fails if a script under scripts/, backend/scripts/ or frontend/scripts/ is missing from this page, or a listed one does not exist. |
task verify, Frontend CI. |
scripts/ci/check-legal-sync.sh |
Fails if a bundled policy's "Last updated" line disagrees with its newest legal_manifest.json entry, and (when operations/legal is reachable via TOMODA_OPERATIONS_LEGAL or a sibling checkout) if a bundled policy differs from its source. |
Frontend CI; by hand after re-syncing policies. |
scripts/ci/compliance-surface.sh |
Prints the app's compliance-relevant surface as stable sorted JSON on stdout; CI diffs it against compliance/surface.json. |
Compliance Surface workflow; by hand via the compliance-reconcile skill. |
release/¶
| Script | What it does | Invoked by |
|---|---|---|
scripts/release/release.sh |
Validates the branch, computes the next semver tag, stamps unreleased policies, writes backend/VERSION and frontend/VERSION, pushes the tag, creates the GitHub Release. See below. |
Release workflow cut job; by hand to cut a release. |
scripts/release/stamp-legal-release.sh |
Sets version and last_updated of every unreleased manifest entry to today's UTC date (STAMP_DATE overrides) and stamps the matching policy files. |
scripts/release/release.sh. |
scripts/release/native-commit.sh |
Commits the build number and native fingerprint a build lane produced onto the latest main (higher build number wins). Usage: <android|ios> <dev|prod>. |
By hand after a native production build (see the native release docs). |
Backend scripts (backend/scripts/)¶
| Script | What it does | Invoked by |
|---|---|---|
backend/scripts/ci/migration-safety-check.sh |
Fails if a migration added since a base ref (default origin/main) drops, renames, retypes, or adds a required column without a default, unless it carries a -- contract: <reason> line. |
task db:migrate:check, Backend CI on pull requests. |
backend/scripts/ci/schema-drift-check.sh |
Applies db/migrations to a throwaway DB and diffs the dumped schema against db/schema/; skips when Postgres is down (hard-fails under CI=true). |
task db:schema:verify, Backend CI, the pre-commit hook. |
backend/scripts/gen/split_schema.py |
Splits a pg_dump -s dump (stdin) into the per-domain db/schema/*.sql snapshot that sqlc reads. Honors SCHEMA_OUT_DIR. |
task db:schema, schema-drift-check.sh. |
backend/scripts/gen/gen-currencies.py |
Downloads the ISO 4217 lists and a pinned CLDR release, then regenerates iso4217.json and frontend/constants/currencies.ts. Needs network and curl; run from backend/. |
By hand when ISO publishes an amendment; review the diff and run the currency tests. |
backend/scripts/seed/load-catalog.sh |
Pulls a published seed set from R2 (an rclone remote r2 if configured, otherwise built from the tomoda-r2-cluster-credentials Secret Manager token) and loads it into local Postgres. Lite by default (skips the notable set, natural places and geo cover photos); FULL=1 loads everything, SIM=1 the small simulation bundle. Validates the cache before loading. Caches in .seed-cache/, marked complete after a full download and keeping only the newest version per mode; vars COVERS (a geo-covers/<set> loaded after the seed), SEED_VERSION, SEED_BUCKET, SEED_R2_SECRET, SEED_R2_PROJECT, CITY_HIGHLIGHTS. The load only enqueues the post-load passes (city linking, highlights, embeddings), so a worker must be running to finish them. |
task db:seed:catalog (needs task dev up). |
backend/scripts/seed/build-sim-seed.py |
Builds the self-contained simulation/<version>/ seed bundle (trimmed collections, downscaled covers, compressed photos) from a full seed cache; paths are flags (--help). |
By an operator when the seed refreshes or the sim scope changes; not wired into a task. |
backend/scripts/seed/gen-sim-hotspots.py |
Regenerates cmd/test/global-hotspots/hotspots.json (major cities per country) that the sim seeds activity at. |
By an operator alongside build-sim-seed.py. |
Backstage master admin¶
| Script | What it does | Invoked by |
|---|---|---|
scripts/backstage-bootstrap.sh |
Port-forwards to the environment's Postgres with your kubeconfig, reads tomoda-db-password-<env> and tomoda-backstage-master-password-<env> with your gcloud credentials, and runs backend/cmd/backstage-bootstrap, which creates the master admin (standalone, role admin) in one transaction. Refuses once an admin exists. With --rotate it only refreshes the master account's password hash from the current secret version and ends the account's live sessions; it never re-activates, re-roles or re-links the account. Never prints the password. |
task backstage:bootstrap ENV=dev\|prod once per environment, after setup-gcp-secrets.sh has generated the secret; then sign in with the password and the code emailed to the developers mailbox, and invite real accounts from Accounts. Add ROTATE=1 after adding a new secret version. |
Frontend scripts (frontend/scripts/)¶
dev/¶
| Script | What it does | Invoked by |
|---|---|---|
frontend/scripts/dev/ios-sim.sh |
Checks Xcode and CocoaPods, cleans iOS build state, boots a Simulator, runs expo run:ios. |
task dev:ios. |
frontend/scripts/dev/ios-device.sh |
Runs expo prebuild --clean and pod install, opens the Xcode workspace, starts Metro for a physical iPhone. |
task dev:ios:device. |
frontend/scripts/dev/ios-device-fast.sh |
Opens the Xcode workspace and starts Metro without prebuild; warns when Podfile.lock is stale. |
task dev:ios:device:fast. |
frontend/scripts/dev/android-emulator.sh |
Checks the Android SDK and a running emulator, cleans Android build state, runs expo run:android. |
task dev:android. |
frontend/scripts/dev/android-e2e.sh |
adb driver for the dev client on an emulator: login, tap by id, open sheets, screenshots. |
By hand, from the app-qa skill. |
frontend/scripts/dev/android-perf.sh |
Resets gfxinfo, runs a scripted interaction, and reports frame and memory stats. |
By hand, from the app-qa skill. |
frontend/scripts/dev/web-e2e.mjs |
Headless Playwright driver for the web app (login, capture, check, sheet) with screenshots. |
By hand, from the app-qa skill. |
frontend/scripts/dev/maintainability-scan.sh |
Prints a scoreboard of frontend anti-pattern counts; --gate also runs tsc, eslint and tests. |
By hand, from the frontend-review skill. |
gen/¶
| Script | What it does | Invoked by |
|---|---|---|
frontend/scripts/gen/build-luts.js |
Converts every .cube LUT in assets/luts/ to a 512x512 Hald PNG for the Skia filter shader. |
task build:luts. |
frontend/scripts/gen/gen-flags.mjs |
Downloads circle-flag SVGs for COUNTRY_CODES and writes assets/flags/flagData.ts. |
By hand after changing the supported country set. |
frontend/scripts/gen/gen-display-names.mjs |
Regenerates i18n/displayNames.json (CLDR country and currency names per app language) for the Hermes polyfill. |
By hand after adding a language. |
frontend/scripts/gen/gen-help-index.mjs |
Regenerates content/help/index.ts from manifest.json and content/help/i18n/, and the backend help index backend/internal/services/help/articles.json; fails on a slug with no file. |
By hand after any help manifest, article or translation change. |
frontend/scripts/gen/gen-share-locales.js |
Generates the OS share-card strings for iOS (Localizable.strings) and Android (strings.xml) across 39 locales. |
By hand after editing the share-card translations. |
release/¶
| Script | What it does | Invoked by |
|---|---|---|
frontend/scripts/release/build-with-secrets.sh |
Pulls the Sentry secrets from GCP, then runs the matching release build, fastlane lane or web export with source-map upload. See below. | task native:* build and release tasks; by hand for a web bundle. |
frontend/scripts/release/bump-version.js |
Increments the iOS build number and Android versionCode in native-build.json; patch/minor/major also bump the marketing version. |
task native:version:*. |
frontend/scripts/release/native-doctor.sh |
Preflight for native release builds: toolchain versions, gcloud auth, signing secrets reachable. |
task native:doctor. |
frontend/scripts/release/seo-meta.mjs |
Injects per-route title, description, canonical, Open Graph and JSON-LD into the exported static web HTML. | npm run build, build-with-secrets.sh web. |
Other tooling¶
Not covered by the check above.
| Path | What it does | Used by |
|---|---|---|
docs/hooks.py |
MkDocs build hook. | mkdocs.yml. |
docker/postgres/initdb.d/10_postgis.sh |
Enables only the extensions the app uses on first init. | Copied into the custom Postgres image. |
backend/cmd/test/scripts/pixelate/ |
Node pixelation wrapper used by the stamp seeder. | task test:install-tools, cmd/test/lib/pixelate.go. |
frontend/fastlane/ |
Fastlane lanes, Appfile, Matchfile. |
frontend/scripts/release/build-with-secrets.sh. |
Usage notes¶
scripts/dev/pull-secrets.sh¶
# Most common: export into current shell, then run task dev
eval $(./scripts/dev/pull-secrets.sh)
task dev
# Or pull and run backend directly in one shot
./scripts/dev/pull-secrets.sh --run
# Pull infra secrets (DB password, etc.) from GCP too; by default these
# use local docker-compose defaults
./scripts/dev/pull-secrets.sh --run --full
Prerequisites: gcloud auth login + gcloud config set project development-485000.
scripts/release/release.sh¶
Two ways to cut a release:
- GitHub Actions (preferred): run the Release workflow (Actions → Release → Run workflow); pick a
bump(patch/minor/major) or pass an explicitversion. Itscutjob runs the script non-interactively onmain, and the same run builds the images, opens the devops deploy PR and, once that PR is merged, publishes prod OTA. See Deployment → Releasing. - Locally:
scripts/release/release.sh # interactive: prompts for the version
RELEASE_BUMP=minor scripts/release/release.sh # non-interactive bump (patch|minor|major)
RELEASE_VERSION=v1.2.3 scripts/release/release.sh # explicit version
Stamps unreleased policy versions with the release day and commits them as legal: stamp policy release date (see scripts/release/stamp-legal-release.sh), bumps backend/VERSION + frontend/VERSION (both, when either service changed), commits, tags vX.Y.Z, pushes, and creates the GitHub Release. Must run on main with a clean working tree. A local cut then offers to dispatch the Release workflow for the new tag (gh workflow run release.yml -f version=vX.Y.Z), which builds and deploys it; without that run nothing ships.
The script is idempotent. A version naming the latest existing tag skips the cut (repair mode: it only makes sure the GitHub Release exists), and in CI a re-run reuses the tag its run already pushed (the tag carries a Release-Run: <run id> trailer).
scripts/dev/run_e2e.sh¶
./scripts/dev/run_e2e.sh
# Builds and starts compose stack, waits for /health, runs Playwright,
# prompts at the end whether to tear down.
Works with both docker and podman (auto-detects). Report at e2e/playwright-report/index.html.
frontend/scripts/release/build-with-secrets.sh¶
cd frontend
# iOS release build
./scripts/release/build-with-secrets.sh ios
# Android release build
./scripts/release/build-with-secrets.sh android
# Cut a beta via fastlane (build + sign + upload)
./scripts/release/build-with-secrets.sh beta-ios # -> TestFlight internal
./scripts/release/build-with-secrets.sh beta-android # -> Play Internal testing
# Regenerate native projects (ios/ and android/) before a release build if app.config.js changed
./scripts/release/build-with-secrets.sh prebuild
# Web export + Sentry source-map upload (release name: com.tomoda.app@<package.json version>)
./scripts/release/build-with-secrets.sh web
Prerequisites: gcloud CLI installed and authenticated (gcloud auth login), with secretAccessor permission on tomoda-sentry-dsn and tomoda-sentry-auth-token in project development-485000. The script aborts with a clear error if either gcloud isn't on PATH, gcloud isn't authenticated, or a secret can't be read.
Secret values are exported into the script process only (never written to disk) and inherited by the child expo / sentry-cli process via exec (native) or in the same shell (web). The shell history captures only the script invocation, not the secret values.
For web specifically: the wrapper runs expo export --platform web into dist/, then calls sentry-cli releases new/sourcemaps upload/releases finalize with --strip-prefix set to the frontend directory so the uploaded artifact paths match what's served from the CDN. The release name is com.tomoda.app@<version from package.json>, override with SENTRY_RELEASE=<custom> if you need a different identifier.
Locale checks¶
Locale completeness (missing, extra or untranslated keys, {{variable}} drift, plural forms) is enforced by frontend/__tests__/i18n/locales.test.ts in npx vitest run. Hardcoded-string sweeps and unused-key removal: the locale-reconcile skill.