chore: release v3.0.0 (sprint 5)

Author: devalade

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to `@devalade/shipnode` will be documented here.
 
-## [3.0.0] - unreleased
+## [3.0.0] - 2026-07-01
 
 ### Added
 - **Multi-app workspaces** — a single `shipnode.config.ts` can now declare multiple applications deployed to the same server, each with its own domain, PM2 process set, health check, env file, build steps, and hooks:
@@ -12,22 +12,31 @@ All notable changes to `@devalade/shipnode` will be documented here.
   - Orchestrator iterates over all apps, selecting the right strategy per-app (backend/frontend).
 - **`--app <name>` CLI flag** — target a single app in a multi-app workspace (`shipnode deploy --app api`, `shipnode logs --app web`). Commands without `--app` apply to all apps. `rollback` requires `--app`.
 - **`getActiveApp(config, name?)` workspace helper** — selects the right app by name or returns `apps[0]` when called without a name.
+- **`domain/cloudflare/` domain model** — `Tunnel` class with typed `Ingress` entries, `toYaml()`/`fromYaml()` serialization, and sorted hostname output for stable, diffable configs.
+- **Multi-hostname tunnel** — `cloudflare init` now enumerates all workspace apps with `domain` + web port and creates one ingress entry per app, with automatic DNS routing.
 
 ### Changed
 - **Config shape split: workspace-level vs. per-app fields.** Workspace-level (`remotePath`, `ssh`, `pkgManager`, `aliases`, `nodeVersion`, etc.) stays on the root config. Per-app fields (`domain`, `pm2`, `healthCheck`, `envFile`, `keepReleases`, `buildDir`, `appRoot`, `sharedDirs`, `sharedFiles`, `hooks`) moved into `apps[]`.
   - Legacy top-level input fields are still accepted and synthesized onto `apps[0]` via `z.preprocess` — backward compatible.
 - **Schema-based assembly** — `assembleConfig` no longer enumerates every field manually. The zod schema is the single source of truth; assembly normalizes legacy input and calls `ShipnodeConfigSchema.parse()`. Prevents drift between builder, schema, and assembly (fixes the pattern that dropped `.aliases()` in 2.5.1).
 - **`BuilderState` is now a standalone type** with workspace-level and legacy input fields, no longer derives from `ShipnodeConfig` (which no longer has those legacy mirrors).
+- **CLI commands are now thin adapters** — `cli/commands/` files are under 80 lines (cloudflare went from 249→49). Business logic extracted to `services/*-orchestrator.ts` and I/O to `infrastructure/`.
+- **`cloudflare init` rewritten** — uses the `Tunnel` domain model, iterates over `config.apps` for ingress entries instead of a single `appHostname`.
 
 ### Removed
 - Legacy top-level mirrors from `ShipnodeConfig` TypeScript shape:
   `config.app`, `config.pm2`, `config.domain`, `config.healthCheck`,
   `config.envFile`, `config.keepReleases`, `config.buildDir`, `config.appRoot`,
   `config.sharedDirs`, `config.sharedFiles`, `config.hooks` — read from `config.apps[i]` instead.
+- **`CloudflareConfig.appHostname`** — use per-app `domain` instead. Ingress entries are now derived automatically from apps with `domain` + web port.
 
 ### Internal
 - **`HooksConfigSchema` uses `z.custom<HookFn>` instead of `z.function()`** — preserves reference equality so `config.hooks.postDeploy === userFn` is true after parse.
 - **Schema-coverage test** (`tests/unit/builder.test.ts`) — every builder setter is exercised in a round-trip; prevents future drift between builder, schema, and assembly.
+- **`src/infrastructure/cloudflare/api.ts`** — Cloudflare API client extracted from CLI command.
+- **`src/infrastructure/provisioning/commands.ts`** — database/Redis setup command builders extracted from setup command.
+- **`src/infrastructure/provisioning/security.ts`** — SSH/UFW/fail2ban command builders extracted from harden command.
+- **`tests/unit/cloudflare.tunnel.test.ts`** — `Tunnel.fromYaml().addIngress(...).toYaml()` round-trip tests.
 
 ## [2.5.2] - 2026-06-30
 

README.md

@@ -25,6 +25,8 @@ shipnode deploy
 
 `shipnode init` creates a `shipnode.config.ts` in your project root. You can also write it by hand using the fluent builder:
 
+### Single app (simple)
+
 ```ts
 import { shipnode } from '@devalade/shipnode';
 
@@ -41,6 +43,41 @@ export default shipnode
   .build();
 ```
 
+### Multi-app workspace
+
+A monorepo with two apps? Use `.apps([...])` to deploy them together:
+
+```ts
+const api = shipnode
+  .app()
+  .backend()
+  .name('api')
+  .appRoot('apps/backend')
+  .domain('api.example.com')
+  .port(3333)
+  .pm2('api')
+  .preDeploy(async ({ exec }) => exec('node ace.js migration:run --force'));
+
+const web = shipnode
+  .app()
+  .frontend()
+  .name('web')
+  .appRoot('apps/frontend')
+  .domain('www.example.com');
+
+export default shipnode
+  .ssh({ host: '1.2.3.4', user: 'deploy' })
+  .deployTo('/var/www/example')
+  .nodeVersion('22')
+  .pkgManager('pnpm')
+  .apps([api, web])
+  .cloudflare({ zone: 'example.com', tunnelName: 'example' })
+  .database({ type: 'postgres', host: 'localhost', port: 5432, name: 'example', user: 'example' })
+  .build();
+```
+
+Each app gets its own release directory, Caddy site, PM2 ecosystem, and health check. Deploy everything with `shipnode deploy`, or target one app with `shipnode deploy --app api`.
+
 ### Web + workers
 
 A backend can run additional long-running processes alongside the web server. PM2 supervises all of them under one deployment.

docs/migrations/2.x-to-3.0.md

@@ -0,0 +1,140 @@
+# 2.x → 3.0 Migration Guide
+
+## What changed
+
+shipnode 3.0 introduces **multi-app workspaces**: a single `shipnode.config.ts` can now deploy
+multiple applications (e.g. an API backend + a frontend SPA) to the same server, each with its own
+domain, PM2 process set, health check, env file, Caddy site block, and release directory.
+
+Under the hood, `ShipnodeConfig` has been split into **workspace-level** and **per-app** fields,
+the config assembly is now schema-driven (zod is the single source of truth), and the CLI accepts
+`--app <name>` to target a specific app.
+
+## Migration
+
+### 1. Config shape: top-level fields moved to `apps[]`
+
+Per-app fields that were previously top-level on `ShipnodeConfig` have moved into `apps[i]`:
+
+| 2.x | 3.0 |
+|---|---|
+| `config.app` | `config.apps[0].appType` |
+| `config.domain` | `config.apps[0].domain` |
+| `config.pm2` | `config.apps[0].pm2` |
+| `config.healthCheck` | `config.apps[0].healthCheck` |
+| `config.envFile` | `config.apps[0].envFile` |
+| `config.keepReleases` | `config.apps[0].keepReleases` |
+| `config.buildDir` | `config.apps[0].buildDir` |
+| `config.appRoot` | `config.apps[0].appRoot` |
+| `config.sharedDirs` | `config.apps[0].sharedDirs` |
+| `config.sharedFiles` | `config.apps[0].sharedFiles` |
+| `config.hooks` | `config.apps[0].hooks` |
+
+**If you only read `ShipnodeConfig` directly** (e.g. in a script calling `loadConfig()`),
+update your accessors to read from `config.apps[i]`. The legacy top-level mirrors are gone.
+
+**If you only use the builder** (`.backend().ssh(...).build()`), **no config changes required** —
+legacy top-level input fields are still accepted by `assembleConfig` and synthesized onto `apps[0]`.
+
+### 2. Multi-app workspace (optional but recommended)
+
+A single-app config continues to work unchanged:
+
+```ts
+// 2.x style — still works in 3.0
+export default shipnode
+  .backend()
+  .ssh({ host: '1.2.3.4', user: 'deploy' })
+  .deployTo('/var/www/myapp')
+  .pm2('myapp')
+  .port(3000)
+  .domain('api.example.com')
+  .build();
+```
+
+To deploy multiple apps from one config, use the new `.apps([...])` composition:
+
+```ts
+const api = shipnode
+  .app()
+  .backend()
+  .name('api')
+  .appRoot('apps/backend')
+  .domain('api.example.com')
+  .port(3333)
+  .pm2('api');
+
+const web = shipnode
+  .app()
+  .frontend()
+  .name('web')
+  .appRoot('apps/frontend')
+  .domain('www.example.com');
+
+export default shipnode
+  .ssh({ host: '1.2.3.4', user: 'deploy' })
+  .deployTo('/var/www/example')
+  .nodeVersion('22')
+  .pkgManager('pnpm')
+  .apps([api, web])
+  .build();
+```
+
+Each app in a workspace gets its own release directory (`<remotePath>/<app-name>/releases/<ts>/`),
+its own Caddy site block, and its own PM2 ecosystem.
+
+### 3. CLI `--app` flag
+
+Commands now accept `--app <name>` to target a specific app:
+
+```bash
+shipnode deploy --app api
+shipnode logs --app web
+shipnode restart --app worker
+```
+
+Without `--app`, commands apply to all apps in the workspace (sequentially for deploy, aggregated
+for logs/status). `rollback` **requires** `--app`.
+
+### 4. `CloudflareConfig.appHostname` removed
+
+`appHostname` on `CloudflareConfig` is removed. Cloudflare tunnel ingress entries are now derived
+from each app's `domain` + web `port` automatically. If you previously set `appHostname`:
+
+```ts
+// 2.x
+cloudflare: { zone: 'example.com', appHostname: 'api.example.com' }
+
+// 3.0 — set domain on the app instead
+apps: [{ name: 'api', domain: 'api.example.com', ... }]
+```
+
+The `sshHostname` field is unchanged and still produces an SSH ingress entry.
+
+### 5. Disk layout
+
+In 2.x, releases lived at `<remotePath>/releases/<ts>/`. In 3.0, releases live at
+`<remotePath>/<app-name>/releases/<ts>/`. On the first deploy after upgrading, shipnode
+automatically migrates the existing layout.
+
+### 6. Internal API changes
+
+- `assembleConfig()` signature is unchanged
+- `DeployOrchestrator` now accepts `ShipnodeConfig` (with `apps[]`) and iterates all apps
+- `getActiveApp(config, name?)` helper returns `apps[0]` by default or a named app
+- `ShipnodeConfig` TypeScript type no longer has legacy top-level mirrors
+
+## Breaking changes summary
+
+| Change | Impact |
+|---|---|
+| Top-level per-app fields removed from `ShipnodeConfig` | Code reading `config.domain` etc. directly must use `config.apps[i].domain` |
+| `appHostname` removed from `CloudflareConfig` | Set `domain` on the app instead |
+| `--app` required for `rollback` | `shipnode rollback` without `--app` now throws |
+| Per-app release directory layout | Automatic migration on first deploy |
+
+## If something breaks
+
+1. Check your `shipnode.config.ts` parses with `pnpm shipnode config validate`
+2. Run `shipnode config show` to inspect the resolved config
+3. If using the programmatic API, check you're reading per-app fields from `config.apps[i]`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalade/shipnode",
-  "version": "2.5.3",
+  "version": "3.0.0",
   "description": "Deploy Node.js apps to a single VPS with zero configuration",
   "type": "module",
   "main": "dist/index.js",