refactor(config): remove legacy top-level mirrors from canonical shape (sprint 2f)

Author: devalade

src/config/assembly.ts

@@ -10,9 +10,30 @@ type LegacyPm2Input = {
   apps?: Pm2App[];
 };
 
-type AssembleInput = Omit<Partial<ShipnodeConfig>, 'pm2' | 'apps'> & {
+type AssembleInput = {
+  ssh?: ShipnodeConfig['ssh'];
+  remotePath?: string;
+  nodeVersion?: string;
+  pkgManager?: ShipnodeConfig['pkgManager'];
+  installCommand?: string;
+  database?: ShipnodeConfig['database'];
+  redis?: ShipnodeConfig['redis'];
+  backup?: ShipnodeConfig['backup'];
+  cloudflare?: ShipnodeConfig['cloudflare'];
+  aliases?: Record<string, string>;
+  // Legacy input fields — synthesized to apps[0] by z.preprocess
+  app?: string;
+  domain?: string;
   pm2?: LegacyPm2Input | Pm2Config;
   backend?: { port?: number };
+  healthCheck?: unknown;
+  envFile?: string;
+  keepReleases?: number;
+  sharedDirs?: string[];
+  sharedFiles?: string[];
+  buildDir?: string;
+  appRoot?: string;
+  hooks?: unknown;
   apps?: Partial<ShipnodeApp>[];
 };
 
@@ -38,35 +59,12 @@ function normalizePm2(
  *
  * 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.
+ * only does what the schema cannot: normalize the legacy `pm2: { name }` input shape
+ * onto canonical `pm2.apps`.
  */
 export function assembleConfig(partial: AssembleInput): ShipnodeConfig {
   const { backend, ...rest } = partial;
   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;
+  return ShipnodeConfigSchema.parse({ ...rest, pm2 });
 }

src/config/builder.ts

@@ -13,8 +13,29 @@ import type {
 } from '../shared/types.js';
 import { assembleConfig } from './assembly.js';
 
-type BuilderState = Omit<Partial<ShipnodeConfig>, 'pm2' | 'apps'> & {
+type BuilderState = {
+  ssh?: SshConfig;
+  remotePath?: string;
+  nodeVersion?: string;
+  pkgManager?: PkgManager;
+  installCommand?: string;
+  database?: DatabaseConfig;
+  redis?: RedisConfig;
+  backup?: BackupConfig;
+  cloudflare?: CloudflareConfig;
+  aliases?: Record<string, string>;
+  // Legacy per-app input fields (synthesized to apps[0] by z.preprocess)
+  app?: string;
   pm2?: { apps: Pm2App[] };
+  domain?: string;
+  keepReleases?: number;
+  healthCheck?: Partial<HealthCheckConfig>;
+  envFile?: string;
+  buildDir?: string;
+  sharedDirs?: string[];
+  sharedFiles?: string[];
+  appRoot?: string;
+  hooks?: { preDeploy?: HookFn; postDeploy?: HookFn };
   apps?: Partial<ShipnodeApp>[];
 };
 

src/config/schema.ts

@@ -118,17 +118,10 @@ export const ShipnodeAppSchema = z.object({
   { 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.
+// modification.
 const ShipnodeConfigBaseSchema = z.object({
   // workspace-level
   ssh: SshConfigSchema,
@@ -144,31 +137,7 @@ const ShipnodeConfigBaseSchema = z.object({
 
   // 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'] },
-).refine(
-  (cfg) => {
-    if (!cfg.domain || cfg.app !== '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'] },
-);
+});
 
 export const ShipnodeConfigSchema = z.preprocess(
   (input: unknown) => {

src/shared/types.ts

@@ -136,30 +136,6 @@ export interface ShipnodeConfig {
 
   /** 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;
-  buildDir?: string;
-  /**
-   * Path (relative to the repo root) of the app within a monorepo whose
-   * compiled output reads `.env` from its own root (AdonisJS, NestJS, etc.).
-   * Shipnode symlinks the shared `.env` into `<appRoot>/build` and
-   * `<appRoot>/dist`. Unset = single-app layout; shipnode auto-detects
-   * `build` / `dist` at the repo root and any obvious `apps/*` / `packages/*`
-   * build outputs.
-   */
-  appRoot?: string;
-  sharedDirs?: string[];
-  sharedFiles?: string[];
-  hooks?: HooksConfig;
 }
 
 export interface ReleaseRecord {

tests/unit/assembly.test.ts

@@ -10,21 +10,20 @@ describe('assembleConfig', () => {
       remotePath: '/var/www/app',
     });
 
-    expect(config.app).toBe('backend');
+    expect(config.apps[0].appType).toBe('backend');
     expect(config.ssh.host).toBe('192.168.1.1');
     expect(config.ssh.user).toBe('deploy');
     expect(config.ssh.port).toBe(22);
     expect(config.remotePath).toBe('/var/www/app');
-    expect(config.keepReleases).toBe(5);
-    expect(config.healthCheck.enabled).toBe(true);
-    expect(config.healthCheck.path).toBe('/health');
-    expect(config.healthCheck.timeout).toBe(30);
-    expect(config.healthCheck.retries).toBe(3);
-    expect(config.healthCheck.startupDelay).toBe(3);
-    expect(config.envFile).toBe('.env');
+    expect(config.apps[0].keepReleases).toBe(5);
+    expect(config.apps[0].healthCheck.enabled).toBe(true);
+    expect(config.apps[0].healthCheck.path).toBe('/health');
+    expect(config.apps[0].healthCheck.timeout).toBe(30);
+    expect(config.apps[0].healthCheck.retries).toBe(3);
+    expect(config.apps[0].healthCheck.startupDelay).toBe(3);
+    expect(config.apps[0].envFile).toBe('.env');
     expect(config.nodeVersion).toBe('lts');
-    // No pm2 declared → no apps at all.
-    expect(config.pm2).toBeUndefined();
+    expect(config.apps[0].pm2).toBeUndefined();
   });
 
   it('preserves explicitly provided values', () => {
@@ -38,13 +37,13 @@ describe('assembleConfig', () => {
       nodeVersion: '22',
     });
 
-    expect(config.app).toBe('frontend');
+    expect(config.apps[0].appType).toBe('frontend');
     expect(config.ssh.port).toBe(2222);
     expect(config.remotePath).toBe('/opt/app');
-    expect(config.keepReleases).toBe(10);
-    expect(config.healthCheck.path).toBe('/api/health');
-    expect(config.healthCheck.timeout).toBe(60);
-    expect(config.envFile).toBe('.env.production');
+    expect(config.apps[0].keepReleases).toBe(10);
+    expect(config.apps[0].healthCheck.path).toBe('/api/health');
+    expect(config.apps[0].healthCheck.timeout).toBe(60);
+    expect(config.apps[0].envFile).toBe('.env.production');
     expect(config.nodeVersion).toBe('22');
   });
 
@@ -56,8 +55,8 @@ describe('assembleConfig', () => {
       pm2: { name: 'api', instances: 2, maxMemory: '1G' },
       backend: { port: 8080 },
     });
-    expect(config.pm2?.apps).toHaveLength(1);
-    expect(config.pm2?.apps[0]).toMatchObject({ name: 'api', port: 8080, instances: 2, maxMemory: '1G' });
+    expect(config.apps[0].pm2?.apps).toHaveLength(1);
+    expect(config.apps[0].pm2?.apps[0]).toMatchObject({ name: 'api', port: 8080, instances: 2, maxMemory: '1G' });
   });
 
   it('accepts the new pm2.apps input shape directly', () => {
@@ -67,9 +66,9 @@ describe('assembleConfig', () => {
       remotePath: '/var/www/app',
       pm2: { apps: [{ name: 'api', port: 3000 }, { name: 'worker', command: 'node dist/worker.js' }] },
     });
-    expect(config.pm2?.apps).toHaveLength(2);
-    expect(config.pm2?.apps[0].name).toBe('api');
-    expect(config.pm2?.apps[1].name).toBe('worker');
+    expect(config.apps[0].pm2?.apps).toHaveLength(2);
+    expect(config.apps[0].pm2?.apps[0].name).toBe('api');
+    expect(config.apps[0].pm2?.apps[1].name).toBe('worker');
   });
 
   it('rejects two pm2.apps entries with ports', () => {
@@ -122,22 +121,6 @@ describe('assembleConfig', () => {
     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',
@@ -179,6 +162,6 @@ describe('assembleConfig', () => {
       remotePath: '/var/www/app',
     });
 
-    expect(config.app).toBe('backend');
+    expect(config.apps[0].appType).toBe('backend');
   });
 });