Skip to content

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 explicit version. Its cut job runs the script non-interactively on main, 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.