insolvia-scripts

The catalogue of Insolvia's repo scripts and WHICH one to run WHEN — they are the project's tools, not incidental files. Use this the moment a task involves setting up or running any part of the monor

SKILL.md

GitHub

Insolvia repo scripts — which one, when

Full details live in scripts/README.md; this is the fast index so you pick the right tool instead of hand-rolling commands. Every dev-setup.sh is idempotent and takes --check (report without installing).

First-time / toolchain setup

Want to… Run
Install the shared toolchain (Terraform, tflint, AWS CLI, jq, Node ≥24, Watchman, Python 3.12) scripts/dev-setup.sh
Make a read:packages token available so npm ci can pull @insolvia-ai/design-system scripts/github-packages-auth.sh

Run everything at once

Want to… Run
Bring the whole system up in one terminal (API + mailer + app + marketing), prefixed logs, one Ctrl-C stops it all scripts/dev-up.sh — takes no arguments. The mailer runs from a sibling insolvia-services checkout (or $INSOLVIA_SERVICES_DIR) and is skipped without one — the API then records mail in memory
Stop everything after a lost terminal or a killed dev-up, or reclaim ports/containers another checkout's run left held scripts/dev-down.sh (idempotent)
Stop one area only that area's scripts/dev-down.sh (idempotent)

dev-up.sh delegates to the per-area dev-up.sh/dev-down.sh pairs below rather than duplicating them — which is also why it has no --only: to run one part, run that part's own script. It refuses to start until dev-aws-setup.sh has run, because there is no DynamoDB emulator and no fake Cognito.

Run a package locally

Each package has a thin scripts/dev-setup.sh (bootstrap) + dev-up.sh (run):

Package Setup → Run
App (Expo/RN web SPA) apps/insolvia_app/scripts/dev-setup.sh → dev-up.sh (expo start --web, pinned to :3000 — Cognito registers that exact origin)
Marketing site apps/insolvia_marketing/scripts/dev-setup.sh → dev-up.sh (RR7 SSR dev server)
API services/api/scripts/dev-setup.sh → dev-up.sh (compose) → dev-test.sh (ruff+mypy+pytest, the UNIT tier, matches CI) → dev-test-integration.sh (the INTEGRATION tier: the running API over HTTP, signed in as seeds/dev.json's person — needs dev-up.sh and dev-aws-seed.sh)
Mailer In insolvia-services now — ../insolvia-services/services/mailer/scripts/dev-setup.sh → dev-up.sh (compose + Mailpit) → dev-test.sh, run in that checkout

packages/insolvia_api_client deliberately has no scripts — the root workspace install covers it.

Test

Four tiers, each a directory, each aimed at fixed environments — the insolvia-testing skill says how to write one, ADR 0021 says which runs where.

Want to… Run
Run every unit suite in the repo, or only those a set of files can break (what the pre-push hook runs; --list shows the mapping) scripts/dev-test-unit.sh [files…]
One Python unit's full gate (ruff → mypy → pytest, exactly as its PR check) that unit's scripts/dev-test.sh; a bare pytest there is unit-only
The API's integration tier against this machine's dev stack (HTTP, signed in by SRP; no AWS credentials) services/api/scripts/dev-test-integration.sh [pytest args] — needs dev-up.sh running and dev-aws-seed.sh done
The browser suite against this machine's dev stack — both projects, or --project smoke for the unauthenticated half e2e/scripts/dev-test.sh [--headed] [playwright args]
The same tiers against staging or the smoke project against production never from a laptop — api-staging.yml, app-staging.yml and app-prod.yml run them after each deploy

The design system and the design tokens are not in this repo at all; they live in insolvia-ai/design-system and install from GitHub Packages. If an install here 401s on @insolvia-ai/*, that is registry auth, not a missing setup script: run ./scripts/github-packages-auth.sh.

Per-machine dev AWS resources (the API's real dev DB — there is no emulator)

These touch real AWS, so read insolvia-aws-auth first if credentials aren't already working.

Want to… Run
Provision this machine's isolated dev resources (infra/envs/dev: tables, queues, buckets) and wire services/api/.env. Sign-in is the ONE shared dev pool (insolvia-dev-users, insolvia-services', ADR 0026, read through SSM): setup stops naming the missing parameter if that pool was never applied (scripts/apply-dev-auth.sh in insolvia-services, once). On a machine set up before the move, the plan destroys the old per-machine pool — expected; run dev-aws-seed.sh after scripts/dev-aws-setup.sh (--check verifies)
Get a usable signed-in dev environment: creates the dev sign-in account if missing — there is no sign-up screen on any pool (allow_admin_create_user_only) — and seeds its firm and the fixture case seeds/dev.json names (sample documents copied server-side from the shared fixture bucket). Also the fix for "signed in, but every route 403s" (accessor unresolved / no_active_firm_user in the API log): the account exists in Cognito but belongs to no firm, and the first firm cannot come from the API because POST /v1/firm/users is itself behind FIRM_ADMINISTRATION. Password from ~/.config/insolvia/dev.env, DEV_USER_PASSWORD, or a no-echo prompt that offers to write that file scripts/dev-aws-seed.sh (--check)
Wipe this machine's dev data (table delete+recreate incl. firms); resources survive, and so do Cognito accounts — the pool is shared by every machine. Leaves your account without a firm — re-run the row above scripts/dev-aws-reset.sh (--dry-run)
Publish a committed seed-fixture version (seeds/fixtures/<v>/) into the account's shared fixture bucket, idempotently — once, after its PR merges; or capture a new version out of this machine's dev stack (refuses any other source) scripts/dev-fixture.sh publish v1 [--check] · scripts/dev-fixture.sh capture v2 <case-id> <handle>
terraform destroy this machine's dev resources + unwind .env scripts/dev-aws-destroy.sh
Destroy a previous machine-id's orphaned dev resources (leftovers a lost/regenerated ~/.config/insolvia/machine-id strands, which destroy can't reach) scripts/dev-aws-destroy-orphan.sh <short-id>

(dev-aws-common.sh is sourced, not run.)

Environment bootstrap & deploys

Want to… Run Notes
Seed the ECR image an env's Image-package Lambdas need before Terraform can create them scripts/bootstrap-ecr-images.sh <env> [api|admin|jobs|marketing|mcp|filing] [--dispatch] [--yes] Breaks the documented first-apply deadlock. Pushes images only — a missing repository is added in insolvia-services' infra/envs/shared
Apply ci-trust (OIDC provider + deploy role + policy) after a deploy fails on a newly-granted IAM permission Not here — insolvia-services' scripts/apply-ci-trust.sh, run from that checkout Human-gated; CI cannot apply this. See insolvia-deploy-role-permissions
Add / remove / show a required status check on main's protect-main ruleset scripts/update-ruleset.sh [show|add|remove] "<check name>" Resolves the ruleset by name, never a hard-coded id, and re-PUTs the whole ruleset so it can't drop the other rules. Names must match a workflow job's name: exactly. See insolvia-branch-protection

There is no deploy script at all: staging deploys automatically on merge to main, and production ships by approving the release run's promote gate in the GitHub UI. See the insolvia-deploy skill.