docs: 3.0 execution plan for sprints 2c → 5

Self-contained plan another agent can follow without our session context.
Lays out, per sprint: objective, files to touch, migration pattern, code
samples, acceptance criteria, and commit message conventions. To be
deleted at the 3.0 release.

Author: devalade

docs/3.0-execution-plan.md

@@ -0,0 +1,332 @@
+# shipnode 3.0 — Plan d'exécution (Sprints 2c → 5)
+
+Document de travail temporaire. À supprimer à la release 3.0.
+
+## Contexte de départ
+
+- **Repo**: `~/Works/personal/shipnode`
+- **Branche**: `v3` (synchronisée avec `origin/v3`)
+- **HEAD actuel**: `7c711ff feat(builder): ShipnodeAppBuilder + .apps([]) workspace composition (sprint 2b)`
+- **Tests**: 199 passent (`pnpm test`)
+- **Typecheck**: clean (`pnpm lint` = `tsc --noEmit`)
+- **package.json**: `"version": "2.5.3"` — sera bumpé à `3.0.0` en Sprint 5
+
+## Lectures obligatoires avant tout code
+
+1. `docs/adr/0004-workspace-multi-app.md` — le design figé pour 3.0 (workspace = N apps partageant ssh/cloudflare/etc., release per-app, CLI `--app` flag, schema-first canonical source, couches internes propres)
+2. `CHANGELOG.md` section `[Unreleased]` — explique le refactor schema-first déjà fait (Sprint 1) et le dual-shape transitionnel (Sprint 2a)
+3. `src/config/schema.ts` — comprendre comment `ShipnodeConfigBaseSchema` + `z.preprocess` synthétise `apps[0]` depuis les legacy top-level fields
+4. `src/config/assembly.ts` — comprendre comment `assembleConfig` mirror `apps[0]` vers les legacy top-level fields après parse
+5. `src/config/builder.ts` — comprendre `ShipnodeBuilder` (legacy) vs `ShipnodeAppBuilder` (nouveau, pour `.apps([])`)
+
+## Invariants à respecter — non-négociables
+
+1. **Chaque commit doit laisser le repo vert**: `pnpm lint` et `pnpm test` passent. Aucun commit "WIP" rouge.
+2. **Pas de régression 2.x**: toute config 2.x existante (sans `.apps([])`) doit continuer à parser, à passer la validation, et à produire le même comportement de déploiement qu'avant. C'est le rôle du dual-shape (legacy top-level mirrors + `apps[]` canonique) — il reste en place jusqu'à 3.0 stable.
+3. **Commits atomiques, un par sous-sprint**, avec message conventionnel `feat|refactor|test|docs(scope): description (sprint 2c)` — pas de co-author, pas de footer "Generated with Claude".
+4. **Push après chaque sous-sprint** (`git push origin v3`).
+5. **Pas d'agents spawnés** — l'agent exécutant utilise ses propres outils (Read/Edit/Write/Bash).
+6. **Pas de breaking change inattendu**: si une refonte casserait un test 2.x existant pour de bonnes raisons, en parler avant de pousser (mettre un commentaire `TODO(sprint-2g)` et continuer).
+
+## Sprint 2c — Migration downstream vers `config.apps[i]`
+
+### Objectif
+Les consumers internes (services, strategies, CLI commands, domain modules) lisent les fields per-app depuis `config.apps[i]` plutôt que depuis les legacy top-level mirrors. Pour la transition: `i = 0` partout — c'est encore single-app sous le capot. La vraie itération multi-app vient en 2d.
+
+### Stratégie recommandée
+Créer un helper unique `src/domain/workspace.ts` qui expose:
+
+```ts
+export function getActiveApp(config: ShipnodeConfig, name?: string): ShipnodeApp {
+  if (name) {
+    const found = config.apps.find((a) => a.name === name);
+    if (!found) throw new Error(`No app named "${name}" in this workspace`);
+    return found;
+  }
+  return config.apps[0];
+}
+```
+
+Tous les consumers downstream appellent `getActiveApp(config)` (ou `getActiveApp(config, opts.app)` quand le `--app` flag arrive en 2e). Ça centralise le point de migration pour passer du single-app au multi-app.
+
+### Fichiers à migrer (par couche)
+
+**Domain + services** (impact métier):
+- `src/domain/deploy/backend-strategy.ts`
+- `src/domain/deploy/frontend-strategy.ts`
+- `src/domain/deploy/orchestrator.ts`
+- `src/domain/pm2/apps.ts`
+- `src/services/caddy.service.ts`
+- `src/services/deploy.service.ts`
+- `src/services/health.service.ts`
+- `src/infrastructure/ssh/connection.ts`
+
+**CLI commands** (adapters):
+- `src/cli/commands/deploy.ts`
+- `src/cli/commands/env.ts`
+- `src/cli/commands/restart.ts`
+- `src/cli/commands/stop.ts`
+- `src/cli/commands/logs.ts`
+- `src/cli/commands/status.ts`
+- `src/cli/commands/metrics.ts`
+- `src/cli/commands/run.ts`
+- `src/cli/commands/rollback.ts`
+- `src/cli/commands/migrate.ts`
+- `src/cli/commands/doctor.ts`
+- `src/cli/commands/config.ts`
+- `src/cli/commands/ci.ts`
+
+### Pattern de migration
+
+Pour chaque fichier, remplacer:
+
+| Avant | Après |
+|---|---|
+| `config.app` | `getActiveApp(config).appType` |
+| `config.domain` | `getActiveApp(config).domain` |
+| `config.pm2` | `getActiveApp(config).pm2` |
+| `config.healthCheck` | `getActiveApp(config).healthCheck` |
+| `config.envFile` | `getActiveApp(config).envFile` |
+| `config.keepReleases` | `getActiveApp(config).keepReleases` |
+| `config.sharedDirs` | `getActiveApp(config).sharedDirs` |
+| `config.sharedFiles` | `getActiveApp(config).sharedFiles` |
+| `config.buildDir` | `getActiveApp(config).buildDir` |
+| `config.appRoot` | `getActiveApp(config).appRoot` |
+| `config.hooks` | `getActiveApp(config).hooks` |
+
+**NE PAS toucher** (ces fields restent workspace-level et restent au top-level de `config`):
+- `config.ssh`, `config.remotePath`, `config.nodeVersion`, `config.pkgManager`, `config.installCommand`
+- `config.database`, `config.redis`, `config.backup`, `config.cloudflare`, `config.aliases`
+
+### Critère d'acceptance
+- `pnpm test` passe (199+ tests, parce que le helper aura ses propres tests)
+- `pnpm lint` clean
+- Le grep suivant ne retourne plus aucune occurrence dans `src/` (hors tests):
+  ```
+  grep -rnE 'config\.(app|domain|pm2|healthCheck|envFile|keepReleases|sharedDirs|sharedFiles|buildDir|appRoot|hooks)\b' src/ | grep -v '\.test\.'
+  ```
+- Tests existants sur les strategies/services/commands continuent à passer sans modification (parce que `getActiveApp(config)` retourne `apps[0]` qui mirror les legacy top-level)
+- Nouveau test `tests/unit/workspace.test.ts` couvre `getActiveApp`: défaut → `apps[0]`, avec name → match exact, name introuvable → throw
+
+### Commit
+`refactor(downstream): consume config.apps via getActiveApp helper (sprint 2c)`
+
+---
+
+## Sprint 2d — Strategies + orchestrator vraiment multi-app
+
+### Objectif
+Le deploy orchestrator itère sur `config.apps[]` et déploie chaque app séquentiellement. Le layout disque devient per-app: `${remotePath}/${app.name}/releases/<ts>/` et `${remotePath}/${app.name}/current`.
+
+### Changements clés
+- `src/domain/deploy/orchestrator.ts`: boucle sur `config.apps`, appelle la strategy appropriée (backend/frontend) par app. Stop sur première erreur. Affiche un résumé total à la fin.
+- `src/domain/deploy/backend-strategy.ts` et `frontend-strategy.ts`: signature change — prend `(workspace: ShipnodeConfig, app: ShipnodeApp)` au lieu de `(config: ShipnodeConfig)`. `app` est l'app à déployer, `workspace` donne accès à ssh/database/etc. partagés.
+- `src/services/caddy.service.ts`: génère **un site block par app** ayant un `domain`. Le `Caddyfile` agrège tous les sites du workspace.
+- Layout disque per-app:
+  - `${remotePath}/${app.name}/releases/<ts>/`
+  - `${remotePath}/${app.name}/current` → release active
+  - `${remotePath}/${app.name}/shared/${app.envFile}` → .env de cette app
+  - Le `${remotePath}/shared/` partagé disparaît (chaque app a son shared)
+- Rollback per-app: `${remotePath}/${app.name}/.releases.json` historique séparé par app
+
+### Compat single-app
+Une config 2.x (qui n'utilise pas `.apps([])`) produit `apps = [{ name: 'app', ... }]` après assemble. Le layout disque devient donc `${remotePath}/app/releases/<ts>/` au lieu de l'ancien `${remotePath}/releases/<ts>/`.
+
+**ATTENTION**: c'est un break disque pour les déploiements existants en place. Deux options:
+- **Option A** (recommandé): au premier deploy 3.0 sur un serveur existant, détecter l'ancien layout (`${remotePath}/releases/` existe), faire une migration automatique (`mv ${remotePath}/releases ${remotePath}/app/releases` + `ln -sf app/current current`). Documenter dans le migration guide.
+- **Option B**: garder l'ancien layout flat quand `config.apps.length === 1` et `apps[0].name === 'app'` (sentinelle "auto-named"). Évite la migration disque mais perpétue 2 code paths.
+
+Choisir Option A — moins de dette technique. Faire la migration disque dans une nouvelle commande `shipnode migrate` ou directement au début du deploy si detected.
+
+### Critère d'acceptance
+- `pnpm test` passe avec les nouveaux tests multi-app
+- Tests existants single-app continuent à passer après ajustements de path
+- `tests/unit/orchestrator.test.ts` couvre: deploy de 2 apps séquentiel, échec sur app[0] empêche app[1], résumé final
+- `tests/unit/backend-strategy.test.ts` et `frontend-strategy.test.ts` adaptés à la nouvelle signature
+- `tests/unit/caddy.service.test.ts` (à créer si absent) couvre: génération du Caddyfile avec N site blocks
+- Le grep `config\.apps\[0\]` ne doit revenir QUE depuis le helper `getActiveApp` (toute itération sur les apps passe par `for (const app of config.apps)`)
+
+### Commits (peut être split)
+- `refactor(deploy): orchestrator iterates over config.apps (sprint 2d)`
+- `feat(deploy): per-app release directories at ${remotePath}/${app.name}/`
+- `feat(caddy): one site block per app having a domain`
+
+---
+
+## Sprint 2e — CLI `--app <name>` flag
+
+### Objectif
+Les commandes `deploy`, `env`, `restart`, `stop`, `logs`, `status`, `metrics`, `run` acceptent un flag `--app <name>` qui les fait opérer sur une app spécifique. Sans flag, elles opèrent sur **toutes les apps** du workspace (séquentiellement pour deploy/env/restart/stop; agrégé pour logs/status/metrics).
+
+`rollback` **exige** `--app` (rolling back tout le workspace ne fait pas sens — voir ADR).
+
+`cloudflare init`, `cloudflare audit`, `cloudflare status`, `harden`, `doctor`, `setup`, `backup setup` restent **workspace-level** (n'acceptent pas `--app`).
+
+### Implémentation
+- Ajouter `--app <name>` option dans chaque CLI command concernée (via `commander`)
+- Le command appelle `getActiveApp(config, opts.app)` — déjà en place depuis 2c
+- Pour `deploy`/`env`/`restart`/`stop` sans `--app`: itérer `for (const app of config.apps)` et appeler la logique pour chaque
+- Pour `logs`/`status`/`metrics` sans `--app`: tag chaque ligne d'output avec le nom de l'app
+- Pour `rollback` sans `--app`: erreur explicite "`rollback requires --app <name>; available: ${apps.map(a=>a.name).join(', ')}`"
+
+### Critère d'acceptance
+- Tests CLI commands updated pour vérifier le flag
+- Tests pour le mode "sans --app" sur un workspace multi-app: deploy toutes les apps en séquence
+- Test rollback sans --app → throw explicite
+
+### Commits (split possible)
+- `feat(cli): --app <name> flag on deploy/env/restart/stop (sprint 2e)`
+- `feat(cli): --app on logs/status/metrics/run with per-app prefix`
+- `feat(cli): rollback requires --app explicitly`
+
+---
+
+## Sprint 2f — Cleanup legacy top-level mirrors
+
+### Objectif
+Maintenant que tous les downstream lisent `apps[i]`, les legacy top-level mirrors (`config.app`, `config.domain`, `config.pm2`, etc.) ne sont plus consommés par le code de shipnode lui-même. On peut les retirer du shape canonique pour ne pas perpétuer la dette.
+
+### Changements
+- `src/shared/types.ts`: retirer les legacy fields top-level de `ShipnodeConfig`. Garder uniquement les workspace-level fields + `apps: ShipnodeApp[]`.
+- `src/config/schema.ts`:
+  - Retirer les legacy fields top-level de `ShipnodeConfigBaseSchema`.
+  - Retirer les refines top-level (`frontend cannot declare pm2` et `domain requires web app`) — ils vivent désormais uniquement sur `ShipnodeAppSchema`.
+  - **Garder** la `z.preprocess` qui synthétise `apps[0]` depuis les legacy fields d'INPUT (c'est ce qui permet à une config 2.x de continuer à parser).
+- `src/config/assembly.ts`: retirer le post-parse mirror. `assembleConfig` redevient le 5-liner de Sprint 1 (normalize pm2 + parse). Plus de mirror.
+- `tests/unit/assembly.test.ts`: retirer les tests qui asserentaient `config.domain === config.apps[0].domain` etc.
+
+### Compat externe
+Si un user externe lisait `config.domain` directement (ex: dans un script appelant `loadConfig()`), ça casse. C'est OK — c'est une 3.0 major, et le migration guide (Sprint 5) documente le changement.
+
+### Critère d'acceptance
+- `pnpm test` passe
+- `pnpm lint` clean
+- Le shape `ShipnodeConfig` exporté n'a plus de fields per-app au top level
+- Le z.preprocess fait toujours son job pour les configs 2.x en input
+- Test ajouté: une config 2.x avec `app: 'backend'`, `domain: 'x'`, `pm2: {...}` parse et produit `apps[0]` correct, MAIS `config.domain` (top-level) est `undefined` (et probablement non-typé maintenant)
+
+### Commit
+`refactor(config): remove legacy top-level mirrors from canonical shape (sprint 2f)`
+
+---
+
+## Sprint 2g — Tests + CHANGELOG récap Sprint 2
+
+### Objectif
+- Récapituler l'intégralité du Sprint 2 dans une entrée `[Unreleased]` du CHANGELOG (vue d'ensemble du workspace multi-app)
+- Ajouter des tests d'intégration de bout en bout: une config workspace multi-app → assemble → orchestrator dry-run → vérifications du plan de déploiement
+- Ajouter un test "compat 2.x": une config 2.x → assemble → orchestrator dry-run → équivalent du déploiement 2.x
+
+### Commit
+`docs(changelog): consolidate sprint 2 workspace multi-app changes (sprint 2g)`
+
+---
+
+## Sprint 3 — Couches internes (cli adapters / services / domain)
+
+Voir ADR 0004 section "Internal layers".
+
+### Objectif
+- `cli/commands/*.ts` deviennent des thin adapters (~50 lignes max)
+- `services/*-orchestrator.ts` contiennent la logique d'orchestration
+- `infrastructure/*` contient les I/O (SSH, prompts, terminal UI, cloudflared API client)
+- `domain/*` reste pure logic, pas d'I/O
+
+### Priorité (du plus grand au plus petit gain)
+1. `src/cli/commands/cloudflare.ts` (249 lignes mélangées) → `services/cloudflare.orchestrator.ts` + `cloudflare.ts` (~50 lignes)
+2. `src/cli/commands/setup.ts` — extraire les bash strings dans `infrastructure/provisioning/scripts/*.sh` (fichiers `.sh`, pas embedded strings)
+3. `src/cli/commands/deploy.ts` — déjà partiellement séparé, fignoler
+4. `src/cli/commands/harden.ts` — même pattern que setup
+5. Le reste au fur et à mesure
+
+### Critère d'acceptance
+- Aucun `cli/commands/*.ts` ne dépasse 80 lignes
+- Aucun import depuis `infrastructure/*` dans `domain/*`
+- Aucun appel SSH/exec direct depuis `cli/commands/*.ts`
+- Tests existants passent (les services ont leurs propres tests, les adapters CLI sont triviaux)
+
+### Commits (split par module refactorisé)
+- `refactor(cloudflare): extract orchestrator to services/cloudflare.orchestrator (sprint 3)`
+- `refactor(setup): move provisioning scripts to .sh files`
+- `refactor(deploy): finalize CLI/service split`
+- `refactor(harden): extract orchestrator + .sh scripts`
+
+---
+
+## Sprint 4 — `domain/cloudflare/` + multi-hostname tunnel
+
+### Objectif
+Cloudflare devient un objet de domaine de premier rang. `cloudflare init` devient idempotent et gère plusieurs hostnames sur un même tunnel naturellement.
+
+### Modèle domain
+Créer `src/domain/cloudflare/`:
+- `tunnel.ts`: `class Tunnel { name, id?, credentialsPath, ingress: Ingress[], catchAll }` avec méthodes `addIngress(hostname, service)`, `toYaml()`, `fromYaml(content)`.
+- `ingress.ts`: `interface Ingress { hostname: string, service: string }` (service est `http://localhost:${port}` typiquement).
+
+### Refactor de `cloudflare init`
+- Lire l'éventuel `/etc/cloudflared/config.yml` existant côté serveur
+- Construire/mettre à jour le `Tunnel` depuis l'état serveur + le workspace local
+- Pour chaque `app` du workspace ayant `domain` ET `pm2.apps` avec port:
+  - `tunnel.addIngress(app.domain, 'http://localhost:${webPort}')`
+  - `cloudflared tunnel route dns ${tunnelName} ${app.domain}` (idempotent)
+- Émettre `tunnel.toYaml()` → `/etc/cloudflared/config.yml`
+- `systemctl restart cloudflared`
+- Optionnel: lock down firewall (UFW) si `cloudflare.lockdownFirewall === true`
+
+### Breaking
+- `CloudflareConfig.appHostname` **supprimé**. Émettre un warning si présent dans la config + fallback sur `apps[0].domain` pour le run en cours.
+- `CloudflareConfig.sshHostname` reste (cas d'usage SSH-over-tunnel toujours pertinent).
+
+### Critère d'acceptance
+- Test unitaire `tests/unit/cloudflare.tunnel.test.ts`: `Tunnel.fromYaml().addIngress(...).toYaml()` round-trip
+- Test orchestrator: deux apps → deux ingress entries + deux DNS routes + un seul service systemd
+- Le YAML émis est diffable et propre (ingress entries triées par hostname pour stabilité)
+
+### Commit
+`feat(cloudflare): multi-hostname tunnel via domain/cloudflare model (sprint 4)`
+
+---
+
+## Sprint 5 — Migration guide + 3.0 release
+
+### Objectif
+- Écrire `docs/migrations/2.x-to-3.0.md` avec exemples concrets avant/après
+- Mettre à jour `README.md` pour le nouveau workspace
+- Compléter `CHANGELOG.md` section `[3.0.0]` avec **toutes** les sorties Sprint 1-4 fusionnées
+- Bumper `package.json` à `3.0.0`
+- Tag annoté `v3.0.0`
+- Merge `v3` → `v2` (ou rename `v2` → `v2-lts` selon la stratégie de maintenance long terme — à clarifier avec le mainteneur)
+- `npm publish` (le mainteneur le fait à la main; l'agent ne publish PAS)
+- Mettre à jour `~/Works/personal/biormin/` pour consommer `@devalade/shipnode@3.0.0`:
+  - Fusionner `shipnode.backend.config.ts` + `shipnode.frontend.config.ts` en un seul `shipnode.config.ts` avec `.apps([api, web])` + workspace `.cloudflare()`
+  - Adapter les scripts `package.json` `deploy:backend`/`deploy:frontend` → `deploy --app api` / `deploy --app web` (ou juste `deploy` pour tout)
+  - Tester un deploy de bout en bout sur `server.biormin.com`
+
+### Critère d'acceptance
+- `docs/migrations/2.x-to-3.0.md` couvre: ajout de `apps[]`, déplacement des fields per-app, suppression de `CloudflareConfig.appHostname`, layout disque per-app, `--app` flag, rollback flow
+- `README.md` montre un workspace multi-app comme exemple principal
+- Test e2e biormin (au moins en dry-run) passe
+
+### Commits
+- `docs: migration guide 2.x → 3.0 (sprint 5)`
+- `chore: release v3.0.0`
+- Sur le repo biormin: `chore(shipnode): migrate to 3.0 workspace config`
+
+---
+
+## Notes pour le reviewer (l'humain qui valide)
+
+- Chaque sous-sprint produit un commit (ou plusieurs si le split est naturel) sur `v3` avec un message explicite
+- Le reviewer peut lire le diff par commit (`git log v3 --oneline` puis `git show <hash>`) et challenger chaque décision
+- En cas de désaccord majeur (genre l'Option A vs B sur le layout disque en 2d, ou l'idempotence cloudflare init en 4), l'agent doit s'arrêter et demander plutôt que pousser quelque chose qui sera reverté
+- Le mainteneur conserve l'autorité finale sur l'API publique (signature des builders, noms de méthodes, etc.) — c'est à confirmer si quelque chose semble border
+
+## Ce qui n'est PAS dans ce plan
+
+- Plugin system / extensibilité framework
+- Provisioning refactor en TypeScript typé (les scripts bash restent des `.sh` extraits, pas plus)
+- Tests d'intégration E2E CLI (besoin d'une cible VPS ou Docker — à évaluer après 3.0)
+- Multi-host workspace
+- Service mesh entre apps
+
+Voir ADR 0004 section "Out of scope" pour justification.