feat(builder): ShipnodeAppBuilder + .apps([]) workspace composition (sprint 2b)

Adds the public API surface for workspace multi-app declared in ADR 0004:

- New ShipnodeAppBuilder class with the per-app methods (backend/
  frontend/name/pm2/port/worker/domain/appRoot/envFile/healthCheck/
  noHealthCheck/keepReleases/sharedDirs/sharedFiles/buildDir/preDeploy/
  postDeploy).
- shipnode.app() on the root builder returns a new ShipnodeAppBuilder.
- Standalone app() factory exported from the package root, for
  composing apps outside the workspace expression.
- shipnode.apps([api, web]) on the root builder accepts the array and
  hands it to assembleConfig as apps[].

Legacy single-app builders (every 2.x config) keep working unchanged
because .apps([]) is not called and the schema's z.preprocess
synthesizes apps[0] from the legacy top-level fields. When .apps([])
IS called, those apps win over any per-app methods called on the root
builder (apps wins; mixing is supported but discouraged).

4 new tests in builder.test.ts cover: factory equivalence, multi-app
composition, workers in app builders, frontend+pm2 refine rejection.

199 tests pass. No downstream consumer migrated yet — that's sprint 2c.

Author: devalade

src/config/builder.ts

@@ -1,5 +1,6 @@
 import type {
   ShipnodeConfig,
+  ShipnodeApp,
   SshConfig,
   Pm2App,
   HealthCheckConfig,
@@ -12,7 +13,12 @@ import type {
 } from '../shared/types.js';
 import { assembleConfig } from './assembly.js';
 
-type BuilderState = Omit<Partial<ShipnodeConfig>, 'pm2'> & {
+type BuilderState = Omit<Partial<ShipnodeConfig>, 'pm2' | 'apps'> & {
+  pm2?: { apps: Pm2App[] };
+  apps?: Partial<ShipnodeApp>[];
+};
+
+type AppBuilderState = Omit<Partial<ShipnodeApp>, 'pm2'> & {
   pm2?: { apps: Pm2App[] };
 };
 
@@ -179,13 +185,156 @@ export class ShipnodeBuilder {
     return this;
   }
 
+  /**
+   * Start a new per-app sub-builder. Pair with `.apps([api, web])` on the workspace
+   * builder to declare a multi-app deployment. See docs/adr/0004-workspace-multi-app.md.
+   */
+  app(): ShipnodeAppBuilder {
+    return new ShipnodeAppBuilder();
+  }
+
+  /**
+   * Declare the apps that compose this workspace. Each app gets its own release
+   * directory, PM2 process group, Caddy site, and Cloudflare ingress entry. When
+   * `.apps([])` is called, the per-app methods on this root builder (.pm2/.port/
+   * .worker/.domain/.healthCheck/.preDeploy/.postDeploy/.appRoot/.envFile/etc.) are
+   * ignored — the apps declared here take over. When `.apps([])` is not called, the
+   * per-app methods continue to write to an implicit single default app (legacy 2.x
+   * behavior). Mixing both is supported but `.apps([])` wins.
+   */
+  apps(apps: ShipnodeAppBuilder[]): this {
+    this.config.apps = apps.map((b) => b.toApp());
+    return this;
+  }
+
   build(): ShipnodeConfig {
     return assembleConfig(this.config);
   }
 }
 
+/**
+ * Per-app builder. Created via `shipnode.app()` or the standalone `app()` factory.
+ * Mirrors the per-app subset of the workspace builder. Pass the result to
+ * `shipnode.apps([...])` on the workspace builder to compose a multi-app deployment.
+ */
+export class ShipnodeAppBuilder {
+  private state: AppBuilderState = {};
+
+  private firstPm2App(): Pm2App {
+    if (!this.state.pm2) this.state.pm2 = { apps: [] };
+    if (this.state.pm2.apps.length === 0) this.state.pm2.apps.push({ name: this.state.name ?? 'app' });
+    return this.state.pm2.apps[0];
+  }
+
+  backend(): this {
+    this.state.appType = 'backend';
+    return this;
+  }
+
+  frontend(): this {
+    this.state.appType = 'frontend';
+    return this;
+  }
+
+  name(n: string): this {
+    this.state.name = n;
+    return this;
+  }
+
+  pm2(name: string, opts?: { instances?: number; maxMemory?: string }): this {
+    const app = this.firstPm2App();
+    app.name = name;
+    if (opts?.instances !== undefined) app.instances = opts.instances;
+    if (opts?.maxMemory !== undefined) app.maxMemory = opts.maxMemory;
+    return this;
+  }
+
+  port(n: number): this {
+    this.firstPm2App().port = n;
+    return this;
+  }
+
+  worker(opts: WorkerOptions): this {
+    if (!this.state.pm2) this.state.pm2 = { apps: [] };
+    this.state.pm2.apps.push({ ...opts });
+    return this;
+  }
+
+  domain(d: string): this {
+    this.state.domain = d;
+    return this;
+  }
+
+  appRoot(dir: string): this {
+    this.state.appRoot = dir;
+    return this;
+  }
+
+  envFile(f: string): this {
+    this.state.envFile = f;
+    return this;
+  }
+
+  keepReleases(n: number): this {
+    this.state.keepReleases = n;
+    return this;
+  }
+
+  sharedDirs(dirs: string[]): this {
+    this.state.sharedDirs = dirs;
+    return this;
+  }
+
+  sharedFiles(files: string[]): this {
+    this.state.sharedFiles = files;
+    return this;
+  }
+
+  buildDir(dir: string): this {
+    this.state.buildDir = dir;
+    return this;
+  }
+
+  healthCheck(path: string, opts?: Partial<HealthCheckConfig>): this {
+    this.state.healthCheck = {
+      ...(this.state.healthCheck ?? {}),
+      enabled: true,
+      path,
+      timeout: opts?.timeout ?? 30,
+      retries: opts?.retries ?? 3,
+      startupDelay: opts?.startupDelay ?? 3,
+    };
+    return this;
+  }
+
+  noHealthCheck(): this {
+    this.state.healthCheck = { enabled: false, path: '/health', timeout: 30, retries: 3, startupDelay: 3 };
+    return this;
+  }
+
+  preDeploy(fn: HookFn): this {
+    this.state.hooks = { ...(this.state.hooks ?? {}), preDeploy: fn };
+    return this;
+  }
+
+  postDeploy(fn: HookFn): this {
+    this.state.hooks = { ...(this.state.hooks ?? {}), postDeploy: fn };
+    return this;
+  }
+
+  /** Internal: hand off the accumulated state to the workspace builder. */
+  toApp(): Partial<ShipnodeApp> {
+    return this.state as Partial<ShipnodeApp>;
+  }
+}
+
 export const shipnode = new ShipnodeBuilder();
 
+/** Standalone factory for a per-app sub-builder. Equivalent to `shipnode.app()`. */
+export function app(): ShipnodeAppBuilder {
+  return new ShipnodeAppBuilder();
+}
+
 export function defineConfig(builder: ShipnodeBuilder): ShipnodeBuilder {
   return builder;
 }

src/index.ts

@@ -1,5 +1,5 @@
-export { shipnode, defineConfig } from './config/builder.js';
-export type { ShipnodeConfig, SshConfig, Pm2Config, Pm2App, HealthCheckConfig, DatabaseConfig, HookContext, HookFn, AppType, PkgManager } from './shared/types.js';
+export { shipnode, app, defineConfig, ShipnodeAppBuilder } from './config/builder.js';
+export type { ShipnodeConfig, ShipnodeApp, SshConfig, Pm2Config, Pm2App, HealthCheckConfig, DatabaseConfig, HookContext, HookFn, AppType, PkgManager } from './shared/types.js';
 export { loadConfig } from './config/loader.js';
 export { detectFramework, detectPkgManager, parsePackageJson } from './domain/framework/detector.js';
 export type { FrameworkDetectionResult } from './shared/types.js';

tests/unit/builder.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { shipnode, ShipnodeBuilder } from '../../src/config/builder.js';
+import { shipnode, ShipnodeBuilder, ShipnodeAppBuilder, app } from '../../src/config/builder.js';
 
 describe('ShipnodeBuilder', () => {
   // Schema-coverage regression: every setter on the builder must produce a field that
@@ -324,3 +324,90 @@ describe('ShipnodeBuilder', () => {
     expect(config.cloudflare?.lockdownFirewall).toBe(true);
   });
 });
+
+describe('ShipnodeAppBuilder + workspace .apps([])', () => {
+  it('shipnode.app() and the standalone app() factory both produce a ShipnodeAppBuilder', () => {
+    expect(shipnode.app()).toBeInstanceOf(ShipnodeAppBuilder);
+    expect(app()).toBeInstanceOf(ShipnodeAppBuilder);
+  });
+
+  it('composes a multi-app workspace via .apps([api, web])', () => {
+    const api = app()
+      .backend()
+      .name('api')
+      .appRoot('apps/backend')
+      .domain('api.example.com')
+      .pm2('api')
+      .port(3333)
+      .envFile('.env.production')
+      .postDeploy(vi.fn());
+
+    const web = app()
+      .backend()
+      .name('web')
+      .appRoot('apps/frontend')
+      .domain('example.com')
+      .pm2('web')
+      .port(3000);
+
+    const config = new ShipnodeBuilder()
+      .ssh({ host: '1.2.3.4', user: 'root' })
+      .deployTo('/var/www/example')
+      .nodeVersion('24')
+      .apps([api, web])
+      .build();
+
+    expect(config.apps).toHaveLength(2);
+    expect(config.apps[0]).toMatchObject({
+      name: 'api',
+      appType: 'backend',
+      appRoot: 'apps/backend',
+      domain: 'api.example.com',
+      envFile: '.env.production',
+    });
+    expect(config.apps[0].pm2?.apps[0]).toMatchObject({ name: 'api', port: 3333 });
+    expect(config.apps[1]).toMatchObject({
+      name: 'web',
+      appType: 'backend',
+      appRoot: 'apps/frontend',
+      domain: 'example.com',
+    });
+    expect(config.apps[1].pm2?.apps[0]).toMatchObject({ name: 'web', port: 3000 });
+    // Legacy top-level mirrors point to apps[0]
+    expect(config.domain).toBe('api.example.com');
+    expect(config.appRoot).toBe('apps/backend');
+  });
+
+  it('app builder collects workers alongside the web app', () => {
+    const api = app()
+      .backend()
+      .name('api')
+      .pm2('api')
+      .port(3333)
+      .worker({ name: 'mailer', command: 'node dist/mailer.js' })
+      .worker({ name: 'queue', command: 'node dist/queue.js' });
+
+    const config = new ShipnodeBuilder()
+      .ssh({ host: '1.2.3.4', user: 'root' })
+      .deployTo('/var/www/app')
+      .apps([api])
+      .build();
+
+    expect(config.apps[0].pm2?.apps).toHaveLength(3);
+    expect(config.apps[0].pm2?.apps.map((a) => a.name)).toEqual(['api', 'mailer', 'queue']);
+  });
+
+  it('frontend app cannot declare pm2 (refine on ShipnodeAppSchema)', () => {
+    const bad = app()
+      .frontend()
+      .name('web')
+      .pm2('web')
+      .port(3000);
+
+    expect(() => new ShipnodeBuilder()
+      .ssh({ host: '1.2.3.4', user: 'root' })
+      .deployTo('/var/www/app')
+      .apps([bad])
+      .build()).toThrow();
+  });
+});