refactor(config): schema as single source of truth (sprint 1/5 for 3.0)

The 2.x assembleConfig listed every field into a withDefaults object;
adding a field meant editing assembly.ts, schema.ts, types.ts and the
builder. .aliases() got dropped that way in 2.5.1 because the four
slipped out of sync with no test to catch it.

Now: schema defines everything, assembleConfig is a 5-line transformer
(normalize legacy pm2 input, parse). Defaults that were in the assembly
(app, remotePath) moved into the schema. HooksConfigSchema swapped from
z.function() to z.custom<HookFn>: z.function() wraps the user function
and broke reference equality, so config.hooks.postDeploy was not the
function the user passed.

New schema-coverage test in builder.test.ts exercises every setter in
one round-trip and asserts every field survives the parse. That is the
test that would have caught .aliases().

All 192 unit tests pass. No public-API change.

Author: devalade

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to `@devalade/shipnode` will be documented here.
 
 ## [Unreleased]
 
+### Changed (internal, towards 3.0)
+- **Schema is now the single source of truth for the config shape.** `assembleConfig` no longer enumerates every field into a `withDefaults` object — that pattern was how `.aliases()` got dropped in 2.5.1. The function is now a thin transformer: normalize the legacy `pm2 { name }` input onto canonical `pm2.apps`, then hand the whole partial to `ShipnodeConfigSchema.parse`. New fields added to the schema (and their builder methods) are preserved automatically. Schema defaults moved to the schema itself (`app: 'backend'`, `remotePath: '/var/www/app'`) so they are reachable without going through the assembler.
+- **`HooksConfigSchema` uses `z.custom<HookFn>` instead of `z.function()`.** `z.function()` wraps the user's function in a validator, breaking reference equality — `config.hooks.postDeploy === userFn` was false after parse. The custom-with-refine variant validates "is callable" while preserving the reference, which is what the deploy orchestrator needs to invoke the original hook. Aligned with zod 4's deprecation of `z.function()` for value validation.
+- **Schema-coverage test (`tests/unit/builder.test.ts`).** Every builder setter is exercised in a single round-trip; the resulting config is asserted to contain each field written by the builder. Prevents future drift between builder, schema, and assembly.
+
 ## [2.5.2] - 2026-06-30
 
 ### Fixed

src/config/assembly.ts

@@ -1,32 +1,5 @@
-import type {
-  ShipnodeConfig,
-  SshConfig,
-  HealthCheckConfig,
-  Pm2App,
-  Pm2Config,
-} from '../shared/types.js';
+import type { ShipnodeConfig, Pm2App, Pm2Config } from '../shared/types.js';
 import { ShipnodeConfigSchema } from './schema.js';
-import { DEFAULTS } from '../shared/constants.js';
-
-function defaultSshConfig(overrides?: Partial<SshConfig>): SshConfig {
-  return {
-    host: '',
-    user: '',
-    port: DEFAULTS.SSH_PORT,
-    ...overrides,
-  };
-}
-
-function defaultHealthCheckConfig(overrides?: Partial<HealthCheckConfig>): HealthCheckConfig {
-  return {
-    enabled: DEFAULTS.HEALTH_CHECK_ENABLED,
-    path: DEFAULTS.HEALTH_CHECK_PATH,
-    timeout: DEFAULTS.HEALTH_CHECK_TIMEOUT,
-    retries: DEFAULTS.HEALTH_CHECK_RETRIES,
-    startupDelay: DEFAULTS.HEALTH_CHECK_STARTUP_DELAY,
-    ...overrides,
-  };
-}
 
 // Loose input shape: also accepts the pre-multi-process `pm2: { name, instances, maxMemory }`
 // + top-level `backend: { port }` form, which assembleConfig folds into pm2.apps[0].
@@ -62,36 +35,14 @@ function normalizePm2(
 /**
  * Assemble a partial config into a fully-validated ShipnodeConfig.
  *
- * Single boundary between user intent and trusted config. Accepts both the legacy
- * `pm2: { name } + backend: { port }` shape and the canonical `pm2: { apps: [...] }`
- * shape; emits the canonical shape only.
+ * 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.
  */
 export function assembleConfig(partial: AssembleInput): ShipnodeConfig {
-  const pm2 = normalizePm2(partial.pm2, partial.backend);
-
-  const withDefaults = {
-    app: partial.app ?? 'backend',
-    ssh: partial.ssh ?? defaultSshConfig(),
-    remotePath: partial.remotePath ?? '/var/www/app',
-    pm2,
-    domain: partial.domain,
-    keepReleases: partial.keepReleases ?? DEFAULTS.KEEP_RELEASES,
-    healthCheck: defaultHealthCheckConfig(partial.healthCheck),
-    envFile: partial.envFile ?? DEFAULTS.ENV_FILE,
-    nodeVersion: partial.nodeVersion ?? DEFAULTS.NODE_VERSION,
-    pkgManager: partial.pkgManager,
-    installCommand: partial.installCommand,
-    sharedDirs: partial.sharedDirs,
-    sharedFiles: partial.sharedFiles,
-    buildDir: partial.buildDir,
-    appRoot: partial.appRoot,
-    database: partial.database,
-    redis: partial.redis,
-    backup: partial.backup,
-    cloudflare: partial.cloudflare,
-    hooks: partial.hooks,
-    aliases: partial.aliases,
-  };
-
-  return ShipnodeConfigSchema.parse(withDefaults) as ShipnodeConfig;
+  const { backend, ...rest } = partial;
+  const pm2 = normalizePm2(partial.pm2, backend);
+  return ShipnodeConfigSchema.parse({ ...rest, pm2 }) as ShipnodeConfig;
 }

src/config/schema.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { isValidIpOrHostname, isValidDomain, isValidPm2Name } from '../domain/validation/ip.js';
+import type { HookFn } from '../shared/types.js';
 
 export const SshConfigSchema = z.object({
   host: z.string().refine(isValidIpOrHostname, 'Must be a valid IP address or hostname'),
@@ -76,15 +77,22 @@ export const CloudflareConfigSchema = z.object({
   bootstrapSshHost: z.string().optional(),
 }).optional();
 
+// z.custom<HookFn> rather than z.function(): we only need a runtime "is it callable" check;
+// z.function() wraps the user's function in a validator-wrapper, breaking reference equality
+// and making `hooks.postDeploy === userFn` false after parse. The wrap is deprecated in zod 4
+// anyway. We validate callable-ness with a refine.
+const HookFnSchema = z
+  .custom<HookFn>((fn) => typeof fn === 'function', { message: 'hook must be a function' });
+
 export const HooksConfigSchema = z.object({
-  preDeploy: z.function().args(z.any()).returns(z.promise(z.void()).or(z.void())).optional(),
-  postDeploy: z.function().args(z.any()).returns(z.promise(z.void()).or(z.void())).optional(),
+  preDeploy: HookFnSchema.optional(),
+  postDeploy: HookFnSchema.optional(),
 }).optional();
 
 export const ShipnodeConfigSchema = z.object({
-  app: z.enum(['backend', 'frontend']),
+  app: z.enum(['backend', 'frontend']).default('backend'),
   ssh: SshConfigSchema,
-  remotePath: z.string().min(1, 'Remote path is required'),
+  remotePath: z.string().min(1, 'Remote path is required').default('/var/www/app'),
   pm2: Pm2ConfigSchema.optional(),
   domain: z.string().refine(isValidDomain, 'Must be a valid domain (no protocol)').optional(),
   keepReleases: z.number().int().min(1).default(5),

tests/unit/builder.test.ts

@@ -2,6 +2,66 @@ import { describe, it, expect, vi } from 'vitest';
 import { shipnode, ShipnodeBuilder } from '../../src/config/builder.js';
 
 describe('ShipnodeBuilder', () => {
+  // Schema-coverage regression: every setter on the builder must produce a field that
+  // survives the round-trip through assembleConfig + zod parse. This is what would
+  // have caught the .aliases() drop (and would catch any future field that gets added
+  // to the builder but forgotten in the schema or vice-versa).
+  it('every setter writes a field that survives the parse round-trip', () => {
+    const preDeploy = vi.fn();
+    const postDeploy = vi.fn();
+    const config = new ShipnodeBuilder()
+      .backend()
+      .ssh({ host: '192.168.1.1', user: 'deploy', port: 2222, identityFile: '/k/id' })
+      .deployTo('/var/www/myapp')
+      .pm2('myapp', { instances: 2, maxMemory: '1G' })
+      .port(3333)
+      .worker({ name: 'mailer', command: 'node dist/mailer.js', instances: 1, maxMemory: '512M', env: { Q: 'mail' } })
+      .domain('api.example.com')
+      .keepReleases(10)
+      .sharedDirs(['storage', 'uploads'])
+      .sharedFiles(['.htpasswd'])
+      .healthCheck('/healthz', { timeout: 60, retries: 5, startupDelay: 10 })
+      .envFile('.env.production')
+      .nodeVersion('22')
+      .pkgManager('pnpm', { installCommand: 'pnpm install --frozen-lockfile' })
+      .buildDir('build')
+      .appRoot('apps/backend')
+      .database({ type: 'postgres', host: 'localhost', port: 5432, name: 'db', user: 'u', password: 'p' })
+      .redis({ host: 'localhost', port: 6379, password: 'rp' })
+      .backup({ s3Bucket: 'backups', s3Prefix: 'prod', schedule: 'daily', retentionDays: 30 })
+      .cloudflare({ zone: 'example.com', appHostname: 'api.example.com', tunnelName: 't', lockdownFirewall: true })
+      .preDeploy(preDeploy)
+      .postDeploy(postDeploy)
+      .aliases({ migrate: 'pnpm db:apply', seed: 'pnpm db:seed' })
+      .build();
+
+    expect(config.app).toBe('backend');
+    expect(config.ssh).toEqual({ host: '192.168.1.1', user: 'deploy', port: 2222, identityFile: '/k/id' });
+    expect(config.remotePath).toBe('/var/www/myapp');
+    expect(config.pm2?.apps).toHaveLength(2);
+    expect(config.pm2?.apps[0]).toMatchObject({ name: 'myapp', port: 3333, instances: 2, maxMemory: '1G' });
+    expect(config.pm2?.apps[1]).toMatchObject({ name: 'mailer', command: 'node dist/mailer.js', instances: 1, maxMemory: '512M', env: { Q: 'mail' } });
+    expect(config.domain).toBe('api.example.com');
+    expect(config.keepReleases).toBe(10);
+    expect(config.sharedDirs).toEqual(['storage', 'uploads']);
+    expect(config.sharedFiles).toEqual(['.htpasswd']);
+    expect(config.healthCheck).toEqual({ enabled: true, path: '/healthz', timeout: 60, retries: 5, startupDelay: 10 });
+    expect(config.envFile).toBe('.env.production');
+    expect(config.nodeVersion).toBe('22');
+    expect(config.pkgManager).toBe('pnpm');
+    expect(config.installCommand).toBe('pnpm install --frozen-lockfile');
+    expect(config.buildDir).toBe('build');
+    expect(config.appRoot).toBe('apps/backend');
+    expect(config.database).toMatchObject({ type: 'postgres', host: 'localhost', port: 5432, name: 'db', user: 'u', password: 'p' });
+    expect(config.redis).toEqual({ host: 'localhost', port: 6379, password: 'rp' });
+    expect(config.backup).toMatchObject({ s3Bucket: 'backups', s3Prefix: 'prod', schedule: 'daily', retentionDays: 30 });
+    expect(config.cloudflare).toMatchObject({ zone: 'example.com', appHostname: 'api.example.com', tunnelName: 't', lockdownFirewall: true });
+    expect(config.hooks?.preDeploy).toBe(preDeploy);
+    expect(config.hooks?.postDeploy).toBe(postDeploy);
+    expect(config.aliases).toEqual({ migrate: 'pnpm db:apply', seed: 'pnpm db:seed' });
+  });
+
+
   it('builds a minimal backend config', () => {
     const config = new ShipnodeBuilder()
       .backend()