feat(config): introduce ShipnodeApp shape and apps[] (sprint 2a)

Lays the foundation for the workspace multi-app design from ADR 0004.
The canonical config now carries an apps[] array (one ShipnodeApp per
deploy unit) in addition to the legacy top-level per-app fields, which
mirror apps[0] for downstream compat during the 3.0 transition.

Key changes:
- ShipnodeAppSchema (new): name, appType, appRoot, domain, pm2,
  healthCheck, envFile, keepReleases, sharedDirs, sharedFiles, buildDir,
  hooks. Refines moved here (frontend cannot declare pm2; domain
  requires a web app).
- ShipnodeConfigSchema: workspace-level fields (ssh, remotePath,
  nodeVersion, pkgManager, installCommand, database, redis, backup,
  cloudflare, aliases) + apps[] + legacy top-level mirrors.
- z.preprocess wraps the schema to synthesize apps[0] from legacy
  top-level fields when the input doesn't carry apps. Lets every 2.x
  config (including direct schema.parse calls) work unmodified.
- assembleConfig: post-parse mirror forces top-level fields to match
  apps[0], so the canonical output is internally consistent.

The builder still only sets legacy fields; sprint 2b adds .app() and
.apps([]). Downstream code still reads from legacy fields; sprint 2c
will migrate it to read from apps[].

195 tests pass (3 new in assembly.test.ts covering apps[] population).

Author: devalade

src/config/assembly.ts

@@ -1,4 +1,4 @@
-import type { ShipnodeConfig, Pm2App, Pm2Config } from '../shared/types.js';
+import type { ShipnodeConfig, Pm2App, Pm2Config, ShipnodeApp } from '../shared/types.js';
 import { ShipnodeConfigSchema } from './schema.js';
 
 // Loose input shape: also accepts the pre-multi-process `pm2: { name, instances, maxMemory }`
@@ -10,9 +10,10 @@ type LegacyPm2Input = {
   apps?: Pm2App[];
 };
 
-type AssembleInput = Omit<Partial<ShipnodeConfig>, 'pm2'> & {
+type AssembleInput = Omit<Partial<ShipnodeConfig>, 'pm2' | 'apps'> & {
   pm2?: LegacyPm2Input | Pm2Config;
   backend?: { port?: number };
+  apps?: Partial<ShipnodeApp>[];
 };
 
 function normalizePm2(
@@ -35,14 +36,37 @@ function normalizePm2(
 /**
  * Assemble a partial config into a fully-validated ShipnodeConfig.
  *
- * The schema is the single source of truth: all defaults, validation, and refinements
- * live there. assembleConfig only does what the schema cannot — normalize the legacy
- * pm2/backend input shape onto canonical pm2.apps — then hands the rest to zod parse.
- * Every field declared in the schema is preserved automatically; adding a new field
- * to the schema (and its corresponding builder method) requires no change here.
+ * The schema is the single source of truth — it knows about defaults, refinements, and
+ * the legacy-fields-to-apps[0] synthesis (via its z.preprocess wrapper). assembleConfig
+ * only does what the schema cannot:
+ *
+ *  1. Normalize the legacy `pm2: { name }` input shape onto canonical `pm2.apps`.
+ *  2. After parse, mirror `apps[0].<field>` back onto the legacy top-level fields so
+ *     downstream code still reading `config.domain`, `config.pm2`, etc. keeps working
+ *     during the 3.0 transition. Sprint 2c will migrate downstream consumers to read
+ *     from `apps[]`, after which the mirror can be removed.
  */
 export function assembleConfig(partial: AssembleInput): ShipnodeConfig {
   const { backend, ...rest } = partial;
-  const pm2 = normalizePm2(partial.pm2, backend);
-  return ShipnodeConfigSchema.parse({ ...rest, pm2 }) as ShipnodeConfig;
+  const pm2 = normalizePm2(rest.pm2, backend);
+
+  const parsed = ShipnodeConfigSchema.parse({ ...rest, pm2 });
+
+  // Force legacy top-level mirrors to match apps[0]: when the user mixed both shapes,
+  // apps wins; when the user only used legacy top-level fields, this is a no-op.
+  const first = parsed.apps[0];
+  return {
+    ...parsed,
+    app: first.appType,
+    pm2: first.pm2,
+    domain: first.domain,
+    healthCheck: first.healthCheck,
+    envFile: first.envFile,
+    keepReleases: first.keepReleases,
+    sharedDirs: first.sharedDirs,
+    sharedFiles: first.sharedFiles,
+    buildDir: first.buildDir,
+    appRoot: first.appRoot,
+    hooks: first.hooks,
+  } as ShipnodeConfig;
 }

src/config/schema.ts

@@ -89,28 +89,75 @@ export const HooksConfigSchema = z.object({
   postDeploy: HookFnSchema.optional(),
 }).optional();
 
-export const ShipnodeConfigSchema = z.object({
-  app: z.enum(['backend', 'frontend']).default('backend'),
-  ssh: SshConfigSchema,
-  remotePath: z.string().min(1, 'Remote path is required').default('/var/www/app'),
-  pm2: Pm2ConfigSchema.optional(),
+// Per-app fields — anything that differs between two apps deployed to the same server.
+// Workspace-level fields (ssh, deployTo, nodeVersion, pkgManager, cloudflare, database,
+// redis, backup, aliases) live on ShipnodeConfigSchema. See docs/adr/0004-workspace-multi-app.md
+// for the rationale of the split.
+export const ShipnodeAppSchema = z.object({
+  name: z.string().refine(isValidPm2Name, 'app name must be alphanumeric, dash, or underscore (max 64 chars)').default('app'),
+  appType: z.enum(['backend', 'frontend']).default('backend'),
+  appRoot: z.string().optional(),
   domain: z.string().refine(isValidDomain, 'Must be a valid domain (no protocol)').optional(),
-  keepReleases: z.number().int().min(1).default(5),
+  pm2: Pm2ConfigSchema.optional(),
   healthCheck: HealthCheckConfigSchema,
   envFile: z.string().default('.env'),
+  keepReleases: z.number().int().min(1).default(5),
+  sharedDirs: z.array(z.string()).optional(),
+  sharedFiles: z.array(z.string()).optional(),
+  buildDir: z.string().optional(),
+  hooks: HooksConfigSchema,
+}).refine(
+  (cfg) => !(cfg.appType === 'frontend' && cfg.pm2),
+  { message: 'frontend apps cannot declare pm2 (frontends are static files served by Caddy)', path: ['pm2'] },
+).refine(
+  (cfg) => {
+    if (!cfg.domain || cfg.appType !== 'backend') return true;
+    const hasWebApp = cfg.pm2?.apps.some((a) => a.port !== undefined);
+    return hasWebApp ?? false;
+  },
+  { message: 'domain requires a web app: one pm2.apps entry must declare a port', path: ['domain'] },
+);
+
+// Dual shape during 3.0 transition: the canonical config carries BOTH `apps[]` (the new
+// workspace shape) AND the legacy top-level per-app fields (app/domain/pm2/healthCheck/
+// envFile/keepReleases/sharedDirs/sharedFiles/buildDir/appRoot/hooks). Downstream code
+// reading the legacy fields keeps working unchanged; new code reads from `apps[]`.
+// Sprint 2c/2d will migrate downstream and drop the legacy fields.
+//
+// A z.preprocess wrapper synthesizes `apps[0]` from the legacy top-level fields when
+// the input doesn't carry `apps`. This lets every 2.x config (including the existing
+// schema.test.ts cases that call ShipnodeConfigSchema.safeParse directly) parse without
+// modification. assembleConfig then post-processes to mirror apps[0] back onto the
+// legacy top-level fields, so the canonical output is internally consistent.
+const ShipnodeConfigBaseSchema = z.object({
+  // workspace-level
+  ssh: SshConfigSchema,
+  remotePath: z.string().min(1, 'Remote path is required').default('/var/www/app'),
   nodeVersion: z.string().default('lts'),
   pkgManager: z.enum(['npm', 'yarn', 'pnpm', 'bun']).optional(),
   installCommand: z.string().min(1).optional(),
-  buildDir: z.string().optional(),
-  appRoot: z.string().optional(),
-  sharedDirs: z.array(z.string()).optional(),
-  sharedFiles: z.array(z.string()).optional(),
   database: DatabaseConfigSchema,
   redis: RedisConfigSchema,
   backup: BackupConfigSchema,
   cloudflare: CloudflareConfigSchema,
-  hooks: HooksConfigSchema,
   aliases: z.record(z.string(), z.string()).optional(),
+
+  // canonical app list (always populated by assembleConfig; .min(1) enforced)
+  apps: z.array(ShipnodeAppSchema).min(1, 'workspace must contain at least one app'),
+
+  // legacy top-level mirrors — kept during 3.0 transition for downstream compat.
+  // Always equal to apps[0].<field> after assembleConfig runs.
+  app: z.enum(['backend', 'frontend']).default('backend'),
+  domain: z.string().refine(isValidDomain, 'Must be a valid domain (no protocol)').optional(),
+  pm2: Pm2ConfigSchema.optional(),
+  healthCheck: HealthCheckConfigSchema,
+  envFile: z.string().default('.env'),
+  keepReleases: z.number().int().min(1).default(5),
+  sharedDirs: z.array(z.string()).optional(),
+  sharedFiles: z.array(z.string()).optional(),
+  buildDir: z.string().optional(),
+  appRoot: z.string().optional(),
+  hooks: HooksConfigSchema,
 }).refine(
   (cfg) => !(cfg.app === 'frontend' && cfg.pm2),
   { message: 'frontend apps cannot declare pm2 (frontends are static files served by Caddy)', path: ['pm2'] },
@@ -123,4 +170,35 @@ export const ShipnodeConfigSchema = z.object({
   { message: 'domain requires a web app: one pm2.apps entry must declare a port', path: ['domain'] },
 );
 
+export const ShipnodeConfigSchema = z.preprocess(
+  (input: unknown) => {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) return input;
+    const obj = input as Record<string, unknown>;
+    if (obj.apps !== undefined) return obj;
+
+    // Synthesize apps[0] from legacy top-level fields. The name defaults to the first
+    // pm2.apps[].name if there is one (so .pm2('biormin') → app.name === 'biormin').
+    const pm2 = obj.pm2 as { apps?: Array<{ name?: string }> } | undefined;
+    const pm2Name = pm2?.apps?.[0]?.name;
+    return {
+      ...obj,
+      apps: [{
+        name: pm2Name ?? 'app',
+        appType: obj.app,
+        appRoot: obj.appRoot,
+        domain: obj.domain,
+        pm2: obj.pm2,
+        healthCheck: obj.healthCheck,
+        envFile: obj.envFile,
+        keepReleases: obj.keepReleases,
+        sharedDirs: obj.sharedDirs,
+        sharedFiles: obj.sharedFiles,
+        buildDir: obj.buildDir,
+        hooks: obj.hooks,
+      }],
+    };
+  },
+  ShipnodeConfigBaseSchema,
+);
+
 export type ShipnodeConfigSchema = z.infer<typeof ShipnodeConfigSchema>;

src/shared/types.ts

@@ -100,19 +100,53 @@ export interface HooksConfig {
   postDeploy?: HookFn;
 }
 
+/**
+ * A single deployment unit (a "deploy unit" in ADR 0004 terminology). A workspace
+ * declares one or more of these; each has its own release directory, PM2 process
+ * group, Caddy site, and Cloudflare ingress entry.
+ */
+export interface ShipnodeApp {
+  name: string;
+  appType: AppType;
+  appRoot?: string;
+  domain?: string;
+  pm2?: Pm2Config;
+  healthCheck: HealthCheckConfig;
+  envFile: string;
+  keepReleases: number;
+  sharedDirs?: string[];
+  sharedFiles?: string[];
+  buildDir?: string;
+  hooks?: HooksConfig;
+}
+
 export interface ShipnodeConfig {
-  app: AppType;
+  // workspace-level
   ssh: SshConfig;
   remotePath: string;
+  nodeVersion: string;
+  pkgManager?: PkgManager;
+  /** Override the install command run on the server. Defaults to the package manager's standard install (e.g. `npm ci`). Use to add flags like `--legacy-peer-deps`, switch to a frozen-lockfile variant, etc. */
+  installCommand?: string;
+  database?: DatabaseConfig;
+  redis?: RedisConfig;
+  backup?: BackupConfig;
+  cloudflare?: CloudflareConfig;
+  aliases?: Record<string, string>;
+
+  /** Canonical app list. Always populated by assembleConfig (length >= 1). */
+  apps: ShipnodeApp[];
+
+  // Legacy top-level mirrors of apps[0].<field>. Kept during the 3.0 transition so
+  // downstream code reading these fields directly keeps working. New code should
+  // read from apps[]. Sprint 2c will migrate the downstream consumers, after which
+  // these mirrors can be removed.
+  app: AppType;
   pm2?: Pm2Config;
   domain?: string;
   keepReleases: number;
   healthCheck: HealthCheckConfig;
   envFile: string;
-  nodeVersion: string;
-  pkgManager?: PkgManager;
-  /** Override the install command run on the server. Defaults to the package manager's standard install (e.g. `npm ci`). Use to add flags like `--legacy-peer-deps`, switch to a frozen-lockfile variant, etc. */
-  installCommand?: string;
   buildDir?: string;
   /**
    * Path (relative to the repo root) of the app within a monorepo whose
@@ -125,12 +159,7 @@ export interface ShipnodeConfig {
   appRoot?: string;
   sharedDirs?: string[];
   sharedFiles?: string[];
-  database?: DatabaseConfig;
-  redis?: RedisConfig;
-  backup?: BackupConfig;
-  cloudflare?: CloudflareConfig;
   hooks?: HooksConfig;
-  aliases?: Record<string, string>;
 }
 
 export interface ReleaseRecord {

tests/unit/assembly.test.ts

@@ -91,6 +91,53 @@ describe('assembleConfig', () => {
     })).toThrow();
   });
 
+  it('synthesizes apps[0] from legacy top-level fields', () => {
+    const config = assembleConfig({
+      app: 'backend',
+      ssh: { host: '1.2.3.4', user: 'deploy' },
+      remotePath: '/var/www/app',
+      pm2: { apps: [{ name: 'api', port: 3000 }] },
+      domain: 'api.example.com',
+      appRoot: 'apps/backend',
+      envFile: '.env.production',
+    });
+    expect(config.apps).toHaveLength(1);
+    expect(config.apps[0]).toMatchObject({
+      name: 'api',
+      appType: 'backend',
+      domain: 'api.example.com',
+      appRoot: 'apps/backend',
+      envFile: '.env.production',
+    });
+    expect(config.apps[0].pm2?.apps[0].name).toBe('api');
+  });
+
+  it('app.name defaults to "app" when no pm2 is declared', () => {
+    const config = assembleConfig({
+      app: 'frontend',
+      ssh: { host: '1.2.3.4', user: 'deploy' },
+      remotePath: '/var/www/static',
+    });
+    expect(config.apps[0].name).toBe('app');
+    expect(config.apps[0].appType).toBe('frontend');
+  });
+
+  it('legacy top-level mirrors are kept in sync with apps[0]', () => {
+    const config = assembleConfig({
+      app: 'backend',
+      ssh: { host: '1.2.3.4', user: 'deploy' },
+      remotePath: '/var/www/app',
+      pm2: { apps: [{ name: 'api', port: 3000 }] },
+      domain: 'api.example.com',
+      envFile: '.env.production',
+    });
+    expect(config.app).toBe(config.apps[0].appType);
+    expect(config.domain).toBe(config.apps[0].domain);
+    expect(config.envFile).toBe(config.apps[0].envFile);
+    expect(config.pm2).toBe(config.apps[0].pm2);
+    expect(config.healthCheck).toEqual(config.apps[0].healthCheck);
+  });
+
   it('preserves aliases through assembly', () => {
     const config = assembleConfig({
       app: 'backend',