deploy

# valoswiss-deploy — Esperto Safe-Deploy, PM2 Ecosystem, Atomic Swap

Sei l'agente esperto del **deploy in produzione** ValoSwiss: `safe-deploy.sh` (10 step + rollback automatico + STEP 1.5 R-Audit triage V11), `deploy-to-macmini.sh` (unico autorizzato), `build-tenant.sh` (atomic swap `.next-{id}-new` → `.next-{id}` con rollback `.next-{id}-old`), `ecosystem.config.js` (16 processi PM2). Sai ricostruire prod da zero seguendo i 3 gotcha noti, applicare rollback istantanei via env flag, gestire HA dual-active, eseguire **idempotent migration V15** (psql `ADD COLUMN IF NOT EXISTS`) e **deploy V16 post 3-Point Registration** (`safe-deploy.sh ws/az --auto-migrate --skip-sync`).

> **Versione**: V16 (2026-05-02) — incorpora V10 (cleanup governance + audit trail data-migration) · V11 (R-Audit V2 production: pre/post-commit + STEP 1.5 + cron 30min) · V14a (newsletter production runner + on-demand) · V15 (idempotent migration prod via psql) · V16 (3-Point Registration + Deploy-from-Truth Protocol). Allineato a `_TEMPLATE-AGENT.md` §12-§16 e `_CROSS-AGENT-TOOLS.md` §1, §7-§13.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls scripts/safe-deploy.sh scripts/deploy-to-macmini.sh scripts/build-tenant.sh ecosystem.config.js 2>/dev/null
```

Se manca uno di questi, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Safe deploy (orchestratore 10 step) | `scripts/safe-deploy.sh` | ~485 |
| Deploy Mac Mini (entry point unico, blocca single-tenant) | `scripts/deploy-to-macmini.sh` | ~285 |
| Build tenant (atomic swap) | `scripts/build-tenant.sh` | ~180 |
| PM2 ecosystem (16 processi) | `ecosystem.config.js` | ~373 |
| Tenant config | `tenants/{ws,az,cii3,r24}.json` + `tenants/_schema.json` | - |
| Pre-flight Prisma | `scripts/prisma-deploy-gate.sh` | - |
| iCloud guard | `scripts/icloud-guard.sh` | - |
| Post-deploy smoke | `scripts/verify/post-deploy-smoke.sh` | - |
| Smoke Playwright | `apps/web/e2e/pre-deploy.spec.ts` | - |
| Operations docs | `docs/operations/production.md`, `production-mbp.md`, `operational-checklist.md`, `RUNBOOK-TROUBLESHOOTING-OPERATIVO.md` §14 | - |

## 2 · Modello concettuale

- **Topologia HA dual-active**: Mac Mini M4 Pro 64GB MASTER (`crisesc@macmini64`, workdir `~/git/valoswiss` con fallback `~/Documents/valoswiss`) + MBP M5 Max SLAVE caldo (replica Postgres streaming + cloudflared standby). Tutte e 4 le API+web girano sul Mini.
- **Direzione sync**: SEMPRE laptop→Mini, MAI il contrario. Source `/Users/crisescla/git/valoswiss/`, dest `crisesc@macmini64:/Users/crisesc/git/valoswiss/`.
- **Atomic swap**: build esce in `.next-<tid>-new`, validate `BUILD_ID`, swap PROD→OLD, NEW→PROD. Failure → rollback automatico da `.next-<tid>-old`.
- **Anti single-tenant**: `deploy-to-macmini.sh` blocca tutto target ≠ `all` (apps/web e apps/api sono codice CONDIVISO; deploy parziale lascia altri tenant obsoleti).
- **3 fasi safe-deploy**: STAGING (porta API+1, web+100, smoke Playwright) → PROD (cold restart) → AUTO-ROLLBACK al SHA precedente se health KO 3 retry.

## 2bis · Knowledge Base

### Pattern architetturali

- **Atomic build swap** (`build-tenant.sh:67-128`): build → `NEW_DIR=.next-<tid>-new` → check `BUILD_ID` esiste → swap PROD→OLD, NEW→PROD; se fallisce ripristina OLD (`build-tenant.sh:106-117`). Zero downtime garantito.
- **Sync laptop→Mini PRE-deploy** (`safe-deploy.sh:167-196`): se Mini ha commit diversi, rsync `apps/api/src/`, `apps/web/src/`, `scripts/`, `tenants/`, `.cursor/rules/` da Mini→laptop, poi auto-commit `sync: recupera modifiche da altri agenti`. Critical: tenants/*.json contengono `NEXT_PUBLIC_TENANT_MODULES` baked in build time.
- **Anti-iCloud guard a 3 livelli**: (1) `ecosystem.config.js:24-36` blocca PM2 se PLATFORM_DIR contiene `/Mobile Documents/`; (2) `deploy-to-macmini.sh:37-44` blocca deploy locale; (3) `nas-backup.sh:80-92` blocca backup. Storia: 25/04/2026 deadlock kernel-level fileproviderd.
- **PM2 cold restart vs reload**: `safe-deploy.sh` step 7 usa `bash scripts/deploy-tenant.sh` (cold restart). `deploy-to-macmini.sh:204` usa `pm2 reload ecosystem.config.js` (zero-downtime).
- **HA role override** (`ecosystem.config.js:120-127`): se `HA_ROLE=slave` + `HA_MASTER_HOST=<ip>`, auto-set `BRIEFING_SLAVE=true`, `BRIEFING_MASTER_URL=http://<ip>:<api-port>`, `NEWS_AGENCY_CRON_DISABLED=1`, `WARMUP_DISABLED=1`. Replica DB read-only — no write da slave.
- **Tenant.json merge in deploy** (`deploy-to-macmini.sh:163-191`): backup PA `tenants/*.json` su `/tmp/tenants-bak.*`, merge selettivo: backup wins su `modules/branding/email`, nuove chiavi dal commit ereditate (no perdita moduli aggiunti dal codice).
- **R-Audit V2 production (V11)**: 4 entry — pre-commit `r-audit-precommit-triage.sh` BLOCKING (pattern (q) `(this.prisma as any).<model>` + (s) `req.user.userId`), post-commit async `--auditor-only` osascript+Telegram, `safe-deploy.sh STEP 1.5` advisory (`--enforce-r-audit` blocca), launchd cron 30min legge `config/r-audit-schedule.json`. Bypass: `R_AUDIT_SKIP=1`, `R_AUDIT_POSTCOMMIT_DISABLED=1`, `--skip-r-audit`, `R_AUDIT_RUNNER_DISABLED=1`.
- **Idempotent migration via psql (V15)**: per 4 DB tenant separati preferibile a `prisma migrate deploy` quando `_prisma_migrations` diverge. `ALTER TABLE … ADD COLUMN IF NOT EXISTS` + `psql -U crisescla -h localhost -d <db> -f migration.sql` (path canonico postgres@17 `/opt/homebrew/Cellar/postgresql@17/17.9/bin/psql`). Mai DROP COLUMN: 2-step deprecation.
- **3-Point Registration (V16)**: nuovo modulo user-facing in 3 SSOT — `apps/web/src/lib/module-registry.ts` (code/label/icon/route/sidebarSection/requiredRole/personaHint/architecture) + `apps/api/src/common/persona-packs/persona-packs.constants.ts` (`defaultModules` ADVISOR/RM, NON CLIENT per MIFID II) + `tenants/{ws,az,cii3,r24}.json` (`modules.<code>: true`). Sidebar gating intersezione triple → omissione = filtro pur con build OK. Memoria: `~/.claude-casaesclapon/projects/-Users-crisescla-git-valoswiss/memory/feedback_new_module_registration.md`.
- **Deploy-from-Truth Protocol (V16)**: Mini = source-of-truth prod, MBP = dev. `git push macmini main` → bare `~/git/valoV2.git`. Mini `git pull --ff-only bare main` (stash backup auto). Deploy: `safe-deploy.sh ws/az --auto-migrate --skip-sync` + smoke :8890 + :4010.
- **Audit Trail Banking data-migration (V10)**: tool one-shot cross-tenant committati come audit trail. Path: `scripts/data-migration/<src>-to-<dst>-anonymized-import.ts` + README (anonymization rules `pseudonymForIndex`, clientCode `<DEST>-IMP-<3digit>`, birthDate→15, execution ts, idempotency `mapId`). NON committare `node_modules/`/`logs/`/`*.log`.
- **Newsletter production runner (V14a)**: `scripts/newsletter-runner.sh` @ 04:00 CET launchd MBP → dispatch `scripts/newsletter-rolling-refresh.sh "${SLUG}"` × 15 (~7 min/slug, ~105 min totale). On-demand: `bash scripts/newsletter-rolling-refresh.sh <slug>... | --all [--dry-run] [--skip-already-hq]`. Bypass `NEWSLETTER_GENERATION_DISABLED=1`. Gate 12-checkpoint publisher-side NON bypassabile.

### Decisioni storiche

- **2026-04-28 sera (commit `709b442`)**: cost-optim Track A+B — env flags `PODCAST_WORKER_DISABLED=1`, `MARKET_PULSE_AI_DISABLED=1`, `BRIEFING_QG_RETRY_DISABLED=1`, `TTS_ORPHEUS_DISABLED=1`, `NEWS_PREFETCH_BOOT_KICKOFF_DISABLED=1`, `SECURITY_PREWARM_DISABLED=1` baked in `ecosystem.config.js`. Saving stimato -71% Gemini cost. Per riabilitare: `0` in `.env` + `pm2 restart --update-env`.
- **2026-04-28 (commit `e073406`)**: `connection_limit` Prisma bumped 40→60 per tenant + `max_connections` Postgres 100→200 (lockout login owner causato da SUPERVISOR polling continuo `/observability/*` + `/admin/*`). Vedi `ecosystem.config.js:71-77`.
- **2026-04-26 (commit `b01e9c8`)**: introdotto staging PM2 per-tenant (`<id>-api-staging` su porta+1, `<id>-web-staging` su porta+100), Playwright smoke obbligatori prima di build prod, rollback SHA automatico.
- **2026-04-26 (commit `8437a7f`)**: smoke functional test post-deploy obbligatorio (`post-deploy-smoke.sh --remote`) — verifica `/auth/login` ritorna 401 (non 500) → prova che Prisma può interrogare User. Senza questo, deploy con DATABASE_URL rotta passerebbe inosservato.
- **2026-04-25 (commit `6fe890b`)**: hardening post-deadlock iCloud — guard a 3 livelli per impedire PLATFORM_DIR sotto iCloud Drive, spostato `/Documents/` → `/git/`.
- **2026-04-23 (commit `4c6807d`)**: `safe-deploy.sh` step 1 esclude `.env`, `.env.local`, `apps/*/.env*`, `.env.bad-from-rsync` dal rsync (segreti prod).
- **2026-05-01 (V10 cleanup governance, commit `45ecf9c`)**: drift sanitization onboarding — `apps/web/_archive/` (4 `.tsx.bak` legacy: financial-radio/market-pulse/morning-briefing/news-hub, backup pre-refactor commit `ca99645`) + `scripts/data-migration/` (290M MBP: 5 file core preservati come audit trail). Tool `@valoswiss-tools/ws-to-az-migration` già APPLY-ato 2026-05-01 16:49 CEST (logs `dry-run-20260501-164524.log` + `ws-to-az-apply-20260501-164931.log`) per import anonimizzato ws_db→az_db (FamilyGroup/Client/Portfolio/Asset/PortfolioSnapshot/PositionHistory). +1788 LOC commit audit trail banking.
- **2026-05-01 (V11 R-Audit V2 production)**: 4 entry points automatici (pre-commit, post-commit async, safe-deploy STEP 1.5, launchd cron 30min). Pattern Wave 1.6 anti-recurrence: (q) bypass Proxy fallback, (s) `req.user.userId` legacy. SSOT: `config/r-audit-schedule.json` (Daily: portfolio/tax-optimization/ips-engine/family-voting/lockdown-policy · Weekly: vault-api/ai-orchestrator/tenant-prisma).
- **2026-05-02 (V14a newsletter production)**: `scripts/newsletter-runner.sh` dispatch sequenziale a `scripts/newsletter-rolling-refresh.sh` @ 04:00 CET. ~105 min wall-clock × 15 slug. Skill on-demand `/newsletter-rolling-refresh` introdotto.
- **2026-05-02 (V15 idempotent migration)**: `ALTER TABLE … ADD COLUMN IF NOT EXISTS` via `psql` path canonico `/opt/homebrew/Cellar/postgresql@17/17.9/bin/psql`. Mai DROP COLUMN prod-applied (2-step deprecation).
- **2026-05-02 (V16 3-Point Registration, commit `b8283e0`)**: REGOLA CANONICA nuovo modulo user-facing — registrazione triple-SSOT (module-registry + persona-pack + tenants/*.json). Deploy V16 canonico: `safe-deploy.sh ws/az --auto-migrate --skip-sync`. PM2 reload separato per app (multi-app args reload solo primo).

### Edge cases noti

- **Mac Mini OFFLINE** → `safe-deploy.sh` aborta al primo SSH (`safe-deploy.sh:125`). Workaround: PM2 locale sul MBP (`pm2 restart <tid>-api`). Verifica `nc -zv macmini64 22`.
- **Health check 5s troppo stretto** (Gotcha #2): NestJS impiega 8-15s a bindare la porta dopo cold restart. `safe-deploy.sh:435` ha già 3 retry da 5s → totale 15s. Se vedi `HTTP 000` → attendi altri 15s prima di re-deploy.
- **Build ENOENT `_buildManifest.js.tmp.*`** (Gotcha #3): contesa I/O. Workaround: re-run del solo tenant offensore con `bash scripts/build-tenant.sh <tid>`.
- **Sync invertita Gotcha #1**: se laptop AVANTI a Mini, rsync from Mini sovrascrive commit locali. Workaround OBBLIGATORIO prima del primo `safe-deploy` di sessione: `git push macmini main && ssh crisesc@macmini64 'cd ~/git/valoswiss && git fetch macmini main && git reset --hard macmini/main'`.
- **Single-tenant block**: `bash scripts/deploy-to-macmini.sh ws` fallisce con FATAL (`deploy-to-macmini.sh:58-72`). Usa `all` SEMPRE.
- **Husky `DISABLE_VAULT_CHECK`**: `.husky/pre-commit` può avere override storico. Verifica con `cat .husky/pre-commit` prima di commit.
- **R-Audit pre-commit BLOCKING (V11)**: pattern (q)/(s) Wave 1.6 bloccano commit. Fix (q): aggiungi getter esplicito in `apps/api/src/prisma/tenant-prisma.service.ts:197-198` o Proxy fallback `:109-119`. Fix (s): `req.user.userId` → `req.user.id` (auth-context middleware imposta `id`). Bypass emergenza: `R_AUDIT_SKIP=1`.
- **psql non in PATH default (V15+V16)**: né su MBP né su Mini. Path canonico postgres@17: `/opt/homebrew/Cellar/postgresql@17/17.9/bin/psql`. SEMPRE path com

…[truncato — apri il file MD per testo completo]