anton-bakker-deploy-engine 0.2.1 → 0.2.3

package/README.md

@@ -1,8 +1,52 @@
 # anton-bakker-deploy-engine
 
-Self-validating AWS deployment verification with a 4-layer model: **exists → configured → functional → project-specific**.
-
-Zero runtime dependencies. TypeScript. ESM.
+A self-validating AWS deployment verification library with a 4-layer verification model and a config-driven pipeline engine.
+
+Zero runtime dependencies. TypeScript. ESM. Node.js ≥ 20.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [Verification Functions](#verification-functions)
+  - [verifyAmplifyOutputs](#verifyamplifyoutputs)
+  - [verifyBuildArtifact](#verifybuildartifact)
+  - [parseTableCount](#parsetablecount)
+  - [assertTableCount](#asserttablecount)
+  - [parseEcsStatus](#parseecsstatus)
+  - [assertCognitoGroups](#assertcognitogroups)
+  - [assertApiHealth](#assertapihealth)
+  - [deriveExpectations](#deriveexpectations)
+  - [summarize](#summarize)
+- [Pipeline Engine](#pipeline-engine)
+  - [Concepts](#concepts)
+  - [Building Gates](#building-gates)
+  - [Writing Check Executors](#writing-check-executors)
+  - [Creating the Execution Context](#creating-the-execution-context)
+  - [Running the Pipeline](#running-the-pipeline)
+  - [State Persistence and Resume](#state-persistence-and-resume)
+  - [Clearing State](#clearing-state)
+  - [Default Environments](#default-environments)
+- [Types Reference](#types-reference)
+- [Publishing](#publishing)
+- [Development](#development)
+- [Licence](#licence)
+
+## Overview
+
+Every AWS deployment can fail silently — tables missing, ECS tasks crashing, environment variables leaking into production builds. This library provides composable verification functions and a pipeline engine that catches these problems automatically.
+
+The 4-layer verification model:
+
+| Layer | Question | Examples |
+|-------|----------|---------|
+| **Exists** | Is the resource present? | amplify_outputs.json readable, index JS bundle exists |
+| **Configured** | Is it set up correctly? | Version is 1.4, data.url is HTTPS, no localhost leaks |
+| **Functional** | Is it working at runtime? | ECS service healthy, API responds, DynamoDB tables present |
+| **Project-specific** | Does it match our source of truth? | Table count matches schema, Cognito groups match auth stack |
+
+You can use the verification functions standalone (for scripts, CI checks, post-deploy validation) or wire them into the pipeline engine for a full gated deployment workflow.
 
 ## Installation
 
@@ -10,125 +54,764 @@ Zero runtime dependencies. TypeScript. ESM.
 npm install anton-bakker-deploy-engine
 ```
 
-Requires Node.js ≥ 20.
+Requires Node.js ≥ 20. Zero runtime dependencies — only uses Node.js built-ins (`fs`, `path`).
+
+## Architecture
 
-## Quick Start
+```
+src/
+├── types.ts      # All type definitions (CheckResult, GateDefinition, etc.)
+├── verify.ts     # Standalone verification functions (Layer 1–4 checks)
+├── pipeline.ts   # Gate builder + default environment configs
+├── engine.ts     # PipelineEngine class (gate executor, state, resume)
+└── index.ts      # Public API — all exports
+```
 
-### Verification Functions (Layer 1–3)
+Everything is exported from the package root:
 
 ```typescript
 import {
-  verifyAmplifyOutputs,
-  verifyBuildArtifact,
-  parseTableCount,
-  assertTableCount,
-  parseEcsStatus,
-  assertCognitoGroups,
-  assertApiHealth,
-  deriveExpectations,
-  summarize,
+  // Verification functions
+  verifyAmplifyOutputs, verifyBuildArtifact, parseTableCount,
+  assertTableCount, parseEcsStatus, assertCognitoGroups,
+  assertApiHealth, deriveExpectations, summarize,
+  // Pipeline engine
+  PipelineEngine, buildGates, DEFAULT_ENVIRONMENTS,
+  // Types
+  type CheckResult, type GateDefinition, type GateResult,
+  type EnvironmentConfig, type PipelineState, type PipelineReport,
+  type CheckExecutor, type ExecutionContext,
 } from 'anton-bakker-deploy-engine';
+```
 
-// Post-build: validate amplify_outputs.json
-const outputChecks = verifyAmplifyOutputs('./amplify_outputs.json');
+## Verification Functions
 
-// Post-build: scan for environment leaks
-const buildChecks = verifyBuildArtifact('./dist');
+All verification functions return `CheckResult` or `CheckResult[]`. Every result has:
 
-// Post-deploy: verify DynamoDB tables
-const { count } = parseTableCount(awsCliOutput, 's20-dev');
-const tableCheck = assertTableCount(count, 124);
+```typescript
+interface CheckResult {
+  name: string;            // Human-readable check description
+  passed: boolean;         // Did it pass?
+  expected?: string | number;  // What was expected
+  actual?: string | number;    // What was found
+  duration?: number;       // Milliseconds (set by pipeline engine)
+  error?: string;          // Error message when passed === false
+}
+```
 
-// Post-deploy: verify ECS health
-const ecsCheck = parseEcsStatus(ecsJsonOutput);
+### verifyAmplifyOutputs
 
-// Aggregate results
-const result = summarize([...outputChecks, ...buildChecks, tableCheck, ecsCheck]);
-console.log(result.passed ? '✅ All checks passed' : `❌ ${result.failed} checks failed`);
+Validates that `amplify_outputs.json` has all required fields for a working Amplify deployment.
+
+```typescript
+function verifyAmplifyOutputs(outputsPath: string): CheckResult[]
 ```
 
-### Pipeline Engine
+**Checks performed:**
+- `version` field is present and equals `"1.4"`
+- `data.url` is present and starts with `https://`
+- `auth.user_pool_id` is present
+- `auth.user_pool_client_id` is present
+
+**Example:**
 
 ```typescript
-import { PipelineEngine, buildGates, DEFAULT_ENVIRONMENTS } from 'anton-bakker-deploy-engine';
-import type { CheckExecutor, ExecutionContext } from 'anton-bakker-deploy-engine';
+const checks = verifyAmplifyOutputs('./amplify_outputs.json');
+// Returns 6 CheckResults
 
-// Register check executors
-const checks = new Map<string, CheckExecutor>();
-checks.set('typecheck', async (ctx) => {
-  const result = ctx.exec('npx tsc --noEmit');
-  return { name: 'TypeScript', passed: result !== null };
-});
-checks.set('api-health', async (ctx) => {
-  const response = ctx.exec(`curl -s https://${ctx.prefix}.example.com/health`);
-  return { name: 'API Health', passed: !!response?.includes('__typename') };
+// All passed?
+if (checks.every(c => c.passed)) {
+  console.log('amplify_outputs.json is valid');
+}
+
+// Find failures
+const failures = checks.filter(c => !c.passed);
+failures.forEach(f => console.error(`${f.name}: ${f.error}`));
+```
+
+**Error handling:** If the file doesn't exist or contains invalid JSON, returns a single failed `CheckResult` with the error message.
+
+### verifyBuildArtifact
+
+Scans the built JavaScript bundle for environment leaks that should never reach production.
+
+```typescript
+function verifyBuildArtifact(distDir: string): CheckResult[]
+```
+
+**Parameters:**
+- `distDir` — path to the build output directory (expects `dist/assets/index-*.js`)
+
+**Checks performed:**
+- No `localhost:4000` in the bundle (GraphQL sandbox leak)
+- No `localhost:5173` in the bundle (Vite dev server leak)
+- No `http://...elb.amazonaws.com` URLs (insecure ALB URLs)
+
+**Example:**
+
+```typescript
+const checks = verifyBuildArtifact('./dist');
+const leaks = checks.filter(c => !c.passed);
+if (leaks.length > 0) {
+  console.error('Environment leaks detected in build:');
+  leaks.forEach(l => console.error(`  ${l.name}: ${l.actual}`));
+  process.exit(1);
+}
+```
+
+**Error handling:** Returns a failed result if `dist/assets` doesn't exist or no `index-*.js` file is found.
+
+### parseTableCount
+
+Parses DynamoDB table count from AWS CLI output, filtering by a table name prefix.
+
+```typescript
+function parseTableCount(
+  awsOutput: string | null,
+  prefix: string
+): CheckResult & { count: number }
+```
+
+**Parameters:**
+- `awsOutput` — raw output from `aws dynamodb list-tables` (JSON array of table names) or a plain number string
+- `prefix` — table name prefix to filter by (e.g. `"s20-dev"`)
+
+**Example:**
+
+```typescript
+import { execSync } from 'child_process';
+
+const output = execSync('aws dynamodb list-tables --output json --query TableNames').toString();
+const result = parseTableCount(output, 's20-dev');
+console.log(`Found ${result.count} tables with prefix s20-dev`);
+```
+
+**Accepts two input formats:**
+1. JSON array: `["s20-dev-Employee", "s20-dev-Division", "other-table"]` → filters by prefix, returns count
+2. Plain number: `"124\n"` → parses as integer
+
+### assertTableCount
+
+Verifies the actual table count meets an expected minimum.
+
+```typescript
+function assertTableCount(actual: number, expected: number): CheckResult
+```
+
+**Example:**
+
+```typescript
+const { count } = parseTableCount(awsOutput, 's20-dev');
+const check = assertTableCount(count, 124);
+if (!check.passed) {
+  console.error(check.error); // "4 tables missing"
+}
+```
+
+### parseEcsStatus
+
+Parses ECS service health from AWS CLI JSON output.
+
+```typescript
+function parseEcsStatus(awsOutput: string | null): CheckResult
+```
+
+**Parameters:**
+- `awsOutput` — JSON string with `status`, `running`/`runningCount`, and `desired`/`desiredCount` fields
+
+**Passes when:** `status === 'ACTIVE'` AND `running >= desired` AND `desired > 0`
+
+**Example:**
+
+```typescript
+const output = execSync(`aws ecs describe-services \
+  --cluster my-cluster --services my-service \
+  --query 'services[0].{status:status,running:runningCount,desired:desiredCount}'`
+).toString();
+
+const check = parseEcsStatus(output);
+if (!check.passed) {
+  console.error(check.error); // "2 tasks not running"
+}
+```
+
+**Accepts both field name styles:** `running`/`desired` and `runningCount`/`desiredCount`.
+
+### assertCognitoGroups
+
+Verifies that all required Cognito user pool groups exist.
+
+```typescript
+function assertCognitoGroups(
+  actualGroups: string[],
+  requiredGroups: string[]
+): CheckResult
+```
+
+**Example:**
+
+```typescript
+const output = execSync(`aws cognito-idp list-groups \
+  --user-pool-id eu-central-1_ABC \
+  --query 'Groups[].GroupName' --output json`
+).toString();
+const actual = JSON.parse(output);
+
+const check = assertCognitoGroups(actual, ['administrators', 'managers', 'root']);
+if (!check.passed) {
+  console.error(check.error); // "Missing: managers, root"
+}
+```
+
+### assertApiHealth
+
+Verifies an API health check response contains `__typename` (GraphQL introspection indicator).
+
+```typescript
+function assertApiHealth(response: string | null): CheckResult
+```
+
+**Example:**
+
+```typescript
+const response = execSync('curl -s https://api.example.com/graphql -d \'{"query":"{__typename}"}\'').toString();
+const check = assertApiHealth(response);
+```
+
+### deriveExpectations
+
+Derives expected deployment values from project source-of-truth files. Reads a GraphQL schema to count model types (which become DynamoDB tables), parses an auth stack for Cognito group definitions, and reads infrastructure config for the API domain.
+
+```typescript
+function deriveExpectations(opts: {
+  schemaPath: string;       // Path to GraphQL schema file
+  authStackPath?: string;   // Path to CDK auth stack (optional)
+  configPath: string;       // Path to infrastructure config JSON
+}): DeployExpectations
+```
+
+**Returns:**
+
+```typescript
+interface DeployExpectations {
+  tableCount: number;       // Number of model types (= expected DynamoDB tables)
+  tableNames: string[];     // Model type names
+  cognitoGroups: string[];  // Group names found in auth stack
+  apiDomain: string;        // Constructed from config dns.apiSubdomain + dns.zoneName
+}
+```
+
+**Schema parsing rules:**
+- Counts all `type X {` definitions in the GraphQL schema
+- Excludes: `Query`, `Mutation`, `Subscription`, types ending in `Input`, types ending in `Connection`
+
+**Auth stack parsing:** Finds Cognito group names via two patterns:
+- Direct assignment: `groupName: 'administrators'`
+- Loop pattern: `for (... of ['administrators', 'managers', 'root'])`
+
+**Example:**
+
+```typescript
+const expectations = deriveExpectations({
+  schemaPath: 'server/src/schema/schema.graphql',
+  authStackPath: 'cdk/lib/auth-stack.ts',
+  configPath: 'cdk/config/infrastructure.json',
 });
 
-// Build gates from environment config
-const envConfig = DEFAULT_ENVIRONMENTS.development;
+console.log(`Expecting ${expectations.tableCount} DynamoDB tables`);
+console.log(`Required Cognito groups: ${expectations.cognitoGroups.join(', ')}`);
+console.log(`API domain: ${expectations.apiDomain}`);
+
+// Use with assertTableCount
+const tableCheck = assertTableCount(actualCount, expectations.tableCount);
+```
+
+**Config file format expected:**
+
+```json
+{
+  "dns": {
+    "apiSubdomain": "api",
+    "zoneName": "example.com"
+  }
+}
+```
+
+If `dns.apiSubdomain` or `dns.zoneName` are missing, defaults to `api.example.com`.
+
+### summarize
+
+Aggregates an array of check results into a single pass/fail summary.
+
+```typescript
+function summarize(checks: CheckResult[]): {
+  passed: boolean;    // true if all checks passed
+  total: number;      // total number of checks
+  failed: number;     // number of failed checks
+  errors: string[];   // error messages from failed checks
+}
+```
+
+**Example:**
+
+```typescript
+const allChecks = [
+  ...verifyAmplifyOutputs('./amplify_outputs.json'),
+  ...verifyBuildArtifact('./dist'),
+  assertTableCount(count, expected),
+  parseEcsStatus(ecsOutput),
+];
+
+const result = summarize(allChecks);
+if (result.passed) {
+  console.log(`✅ All ${result.total} checks passed`);
+} else {
+  console.error(`❌ ${result.failed}/${result.total} checks failed:`);
+  result.errors.forEach(e => console.error(`  - ${e}`));
+  process.exit(1);
+}
+```
+
+## Pipeline Engine
+
+The pipeline engine runs a sequence of gates, where each gate contains one or more checks. Gates execute in order. When a gate fails, the engine takes the configured action (abort, rollback, or alert) and stops.
+
+### Concepts
+
+**Gate** — a named group of checks with a failure action. Example: "Post-Deploy Inventory" gate runs `table-count`, `ecs-status`, and `cognito-groups` checks. If any fail, the action is `rollback`.
+
+**Check executor** — an async function that runs a single named check and returns a `CheckResult`. You register these with the engine.
+
+**Execution context** — environment information passed to every check executor (environment name, region, project root, a shell exec helper, etc.).
+
+**State persistence** — the engine saves its state to disk after each gate. If a run is interrupted, it resumes from the last passed gate.
+
+### Building Gates
+
+Use `buildGates()` to generate a gate sequence from an `EnvironmentConfig`:
+
+```typescript
+import { buildGates, DEFAULT_ENVIRONMENTS } from 'anton-bakker-deploy-engine';
+
+const gates = buildGates(DEFAULT_ENVIRONMENTS.staging);
+```
+
+This produces 10 gates in order:
+
+| # | Gate | Checks | On Fail |
+|---|------|--------|---------|
+| 1 | Preflight | `aws-creds`, `deploy-lock` | abort |
+| 2 | Code Quality | From `preDeployChecks` config | abort |
+| 3 | Infrastructure Validation | `cdk-synth`, `derive-expectations` | abort |
+| 4 | Pre-Deploy Safety | `backup-tables` (if enabled), `prepare-migrations` (if enabled) | abort |
+| 5 | Build | `docker-build`, `frontend-build`, `post-build-verify` | abort |
+| 6 | Deploy | `cdk-deploy`, `ecs-update`, `frontend-deploy`, `seed-data` (if enabled) | rollback |
+| 7 | Post-Deploy Inventory | `table-count`, `ecs-status`, `cognito-groups` | rollback |
+| 8 | Post-Deploy Configuration | `pitr-enabled`, `billing-mode`, `https-enforced`, `s3-not-public` | alert |
+| 9 | Post-Deploy Functional | From `postDeployProbes` config | rollback or alert |
+| 10 | Project Assertions | `manifest-assertions`, `e2e-tests` (if enabled) | alert |
+
+Gates 4 and 10 are conditional — they're skipped if the relevant config flags are off.
+
+You can also build gates manually:
+
+```typescript
+import type { GateDefinition } from 'anton-bakker-deploy-engine';
+
+const gates: GateDefinition[] = [
+  {
+    id: 'preflight',
+    name: 'Preflight',
+    checks: ['aws-creds'],
+    onFail: 'abort',
+  },
+  {
+    id: 'deploy',
+    name: 'Deploy',
+    checks: ['cdk-deploy'],
+    onFail: 'rollback',
+  },
+  {
+    id: 'verify',
+    name: 'Post-Deploy Verification',
+    checks: ['api-health', 'table-count'],
+    onFail: 'rollback',
+  },
+];
+```
+
+**Failure actions:**
+- `abort` — stop the pipeline, do nothing else
+- `rollback` — stop the pipeline, signal that a rollback is needed (the engine sets `result: 'rolled-back'`)
+- `alert` — stop the pipeline, signal that an alert should be sent
+
+**Conditional gates:** Add a `condition` function that receives the `EnvironmentConfig`. The gate is skipped if it returns `false`:
+
+```typescript
+{
+  id: 'backup',
+  name: 'Backup',
+  checks: ['backup-tables'],
+  onFail: 'abort',
+  condition: (env) => env.backupBefore,  // Only run if backups are enabled
+}
+```
+
+### Writing Check Executors
+
+A check executor is an async function that receives the `ExecutionContext` and returns a `CheckResult`:
+
+```typescript
+import type { CheckExecutor } from 'anton-bakker-deploy-engine';
+
+const typecheckExecutor: CheckExecutor = async (ctx) => {
+  const result = ctx.exec('npx tsc --noEmit');
+  return {
+    name: 'TypeScript type check',
+    passed: result !== null,
+    error: result === null ? 'tsc --noEmit failed' : undefined,
+  };
+};
+
+const tableCountExecutor: CheckExecutor = async (ctx) => {
+  const output = ctx.exec(`aws dynamodb list-tables --query TableNames --output json`);
+  const { count } = parseTableCount(output, ctx.prefix);
+  const expected = ctx.expectations?.tableCount as number ?? 0;
+  return assertTableCount(count, expected);
+};
+
+const apiHealthExecutor: CheckExecutor = async (ctx) => {
+  const response = ctx.exec(`curl -sf https://${ctx.prefix}.example.com/health`);
+  return assertApiHealth(response);
+};
+```
+
+Register executors in a `Map<string, CheckExecutor>`:
+
+```typescript
+const checks = new Map<string, CheckExecutor>();
+checks.set('typecheck', typecheckExecutor);
+checks.set('table-count', tableCountExecutor);
+checks.set('api-health', apiHealthExecutor);
+```
+
+The check name in the map must match the check name referenced in gate definitions.
+
+If a check executor throws an exception, the engine catches it and records a failed `CheckResult` with the error message.
+
+If a gate references a check name that has no registered executor, the engine records a failed result with `"No executor registered for 'name'"`.
+
+### Creating the Execution Context
+
+The `ExecutionContext` provides environment information to all check executors:
+
+```typescript
+import type { ExecutionContext } from 'anton-bakker-deploy-engine';
+import { execSync } from 'child_process';
+
+const ctx: ExecutionContext = {
+  environment: 'staging',           // Full environment name
+  envShort: 'stg',                  // Short code for prefixes
+  prefix: 's20-stg',               // Resource name prefix
+  region: 'eu-central-1',          // AWS region
+  account: '123456789012',         // AWS account ID
+  projectRoot: process.cwd(),      // Project root directory
+  dryRun: false,                   // If true, no state is persisted
+  envConfig: DEFAULT_ENVIRONMENTS.staging,
+  expectations: {                  // Optional — from deriveExpectations()
+    tableCount: 124,
+    cognitoGroups: ['administrators', 'managers'],
+  },
+  exec: (cmd) => {                 // Shell command executor
+    try {
+      return execSync(cmd, { encoding: 'utf-8', timeout: 60_000 });
+    } catch {
+      return null;
+    }
+  },
+  log: (msg) => process.stdout.write(msg + '\n'),
+};
+```
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `environment` | `string` | Full environment name (`development`, `staging`, `production`) |
+| `envShort` | `string` | Short code used in resource prefixes (`dev`, `stg`, `prod`) |
+| `prefix` | `string` | Resource name prefix (e.g. `s20-dev`) |
+| `region` | `string` | AWS region |
+| `account` | `string` | AWS account ID |
+| `projectRoot` | `string` | Absolute path to project root |
+| `dryRun` | `boolean` | When `true`, no state files are written to disk |
+| `envConfig` | `EnvironmentConfig` | The environment configuration driving this run |
+| `expectations` | `Record<string, unknown>` | Optional key-value store for derived expectations |
+| `exec` | `(cmd: string) => string \| null` | Runs a shell command, returns stdout or `null` on failure |
+| `log` | `(msg: string) => void` | Logging function |
+
+### Running the Pipeline
+
+```typescript
+import { PipelineEngine, buildGates, DEFAULT_ENVIRONMENTS } from 'anton-bakker-deploy-engine';
+
+const envConfig = DEFAULT_ENVIRONMENTS.staging;
 const gates = buildGates(envConfig);
 
-// Run the pipeline
-const engine = new PipelineEngine({ gates, checks, ctx: myContext });
+const engine = new PipelineEngine({
+  gates,
+  checks,       // Map<string, CheckExecutor>
+  ctx,           // ExecutionContext
+  stateDir: './orchestrator',  // Optional — defaults to <projectRoot>/orchestrator
+});
+
 const report = await engine.run();
+```
 
-if (report.state.result === 'passed') {
-  console.log(`✅ All ${report.summary.totalGates} gates passed`);
-} else {
-  console.log(`❌ Failed at gate: ${report.summary.failedGate}`);
+**Constructor options:**
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `gates` | `GateDefinition[]` | Yes | — | Ordered list of gates to execute |
+| `checks` | `Map<string, CheckExecutor>` | Yes | — | Registered check executors |
+| `ctx` | `ExecutionContext` | Yes | — | Execution context |
+| `stateDir` | `string` | No | `<projectRoot>/orchestrator` | Directory for state and report files |
+
+**The `run()` method returns a `PipelineReport`:**
+
+```typescript
+interface PipelineReport {
+  state: PipelineState;
+  summary: {
+    totalGates: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    duration: number;       // Total milliseconds
+    failedGate?: string;    // ID of the gate that failed
+    action?: 'abort' | 'rollback' | 'alert';  // Failure action
+  };
 }
 ```
 
-## API Reference
+**Handling the result:**
 
-### Verification Functions
+```typescript
+const report = await engine.run();
 
-| Function | Input | Returns | Layer |
-|----------|-------|---------|-------|
-| `verifyAmplifyOutputs(path)` | Path to amplify_outputs.json | `CheckResult[]` | Exists + Configured |
-| `verifyBuildArtifact(distDir)` | Path to dist directory | `CheckResult[]` | Configured |
-| `parseTableCount(output, prefix)` | AWS CLI JSON, table prefix | `CheckResult & { count }` | Functional |
-| `assertTableCount(actual, expected)` | Counts | `CheckResult` | Functional |
-| `parseEcsStatus(output)` | AWS CLI JSON | `CheckResult` | Functional |
-| `assertCognitoGroups(actual, required)` | Group arrays | `CheckResult` | Functional |
-| `assertApiHealth(response)` | API response string | `CheckResult` | Functional |
-| `deriveExpectations(opts)` | Schema/config paths | `DeployExpectations` | Project-specific |
-| `summarize(checks)` | `CheckResult[]` | `{ passed, total, failed, errors }` | — |
+switch (report.state.result) {
+  case 'passed':
+    console.log(`✅ All ${report.summary.totalGates} gates passed in ${report.summary.duration}ms`);
+    break;
+  case 'failed':
+    console.error(`❌ Failed at gate: ${report.summary.failedGate} → ${report.summary.action}`);
+    break;
+  case 'rolled-back':
+    console.error(`🔄 Rolled back at gate: ${report.summary.failedGate}`);
+    // Trigger actual rollback logic here
+    break;
+}
+```
 
-### Pipeline Engine
+### State Persistence and Resume
 
-- **`PipelineEngine`** — Executes gates in order with state persistence and resume
-- **`buildGates(envConfig)`** — Builds gate sequence from environment config
-- **`DEFAULT_ENVIRONMENTS`** — Pre-built configs for development, staging, production
-- **`PipelineEngine.clearState(dir, env)`** — Archive state for a fresh run
+The engine saves its state to `<stateDir>/deploy-state-<environment>.json` after each gate completes. If a run is interrupted (process crash, network failure, timeout), the next run automatically resumes from the last passed gate.
 
-### Types
+**State file location:** `orchestrator/deploy-state-staging.json`
 
-`CheckResult`, `GateDefinition`, `GateResult`, `EnvironmentConfig`, `PipelineState`, `PipelineReport`, `CheckExecutor`, `ExecutionContext`
+**Resume behaviour:**
+- Gates that already passed are skipped with a log message
+- The failed gate is re-executed
+- New gates run normally
 
-## Design Principles
+**Reports:** On successful completion, the engine also saves a report to `<stateDir>/deploy-reports/<timestamp>-<envShort>.json`.
 
-- **Project-agnostic**: no assumptions about consuming project layout
-- **Zero dependencies**: only Node.js built-ins (fs, path)
-- **Composable**: each function is independently usable
-- **Config-driven**: pipeline behaviour determined by `EnvironmentConfig`, not hardcoded logic
+**Dry run mode:** When `ctx.dryRun` is `true`, no state or report files are written. Useful for testing.
 
-## Development
+### Clearing State
 
-```bash
-npm test          # Run tests (vitest)
-npm run build     # Compile TypeScript
-npm run lint      # ESLint with zero warnings
+To force a fresh run (discard previous state), archive the state file:
+
+```typescript
+PipelineEngine.clearState('./orchestrator', 'staging');
+```
+
+This moves `deploy-state-staging.json` to `orchestrator/archive/state-<timestamp>.json`. The next `engine.run()` starts from gate 1.
+
+### Default Environments
+
+`DEFAULT_ENVIRONMENTS` provides pre-built configurations for three environments:
+
+**development:**
+
+```typescript
+{
+  approval: 'never',
+  preDeployChecks: ['typecheck', 'lint', 'server-tests', 'schema-parse', 'merge-markers'],
+  migrations: true,
+  seed: { enabled: true, skipCalendar: true },
+  e2eTests: false,
+  backupBefore: false,
+  cdkNagLevel: 'warning',
+  postDeployProbes: ['api-health', 'table-count', 'ecs-status'],
+  rollbackOnProbeFailure: false,
+}
+```
+
+**staging:**
+
+```typescript
+{
+  approval: 'never',
+  preDeployChecks: ['typecheck', 'lint', 'server-tests', 'web-tests', 'schema-parse', 'merge-markers'],
+  migrations: true,
+  seed: { enabled: true, skipCalendar: false },
+  e2eTests: true,
+  e2eTestSuite: 'web/e2e/migration/',
+  backupBefore: true,
+  cdkNagLevel: 'error',
+  postDeployProbes: ['api-health', 'table-count', 'ecs-status', 'cognito-groups', 'crud-probe'],
+  rollbackOnProbeFailure: true,
+}
 ```
 
+**production:**
+
+```typescript
+{
+  approval: 'broadening',
+  preDeployChecks: ['typecheck', 'lint', 'server-tests', 'web-tests', 'schema-parse',
+                    'merge-markers', 'schema-backward-compat'],
+  migrations: true,
+  seed: { enabled: false },
+  e2eTests: true,
+  e2eTestSuite: 'web/e2e/smoke/',
+  backupBefore: true,
+  cdkNagLevel: 'error',
+  postDeployProbes: ['api-health', 'table-count', 'ecs-status', 'cognito-groups',
+                     'crud-probe', 'auth-probe', 's3-probe'],
+  rollbackOnProbeFailure: true,
+}
+```
+
+**EnvironmentConfig fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `approval` | `'never' \| 'broadening' \| 'always'` | When to require human approval |
+| `preDeployChecks` | `string[]` | Check names to run in the Code Quality gate |
+| `migrations` | `boolean` | Whether to run database migrations |
+| `seed` | `{ enabled, skipCalendar? }` | Whether to seed data after deploy |
+| `e2eTests` | `boolean` | Whether to run E2E tests |
+| `e2eTestSuite` | `string` | Path to E2E test suite |
+| `backupBefore` | `boolean` | Whether to backup DynamoDB tables before deploy |
+| `cdkNagLevel` | `'warning' \| 'error'` | CDK Nag severity level |
+| `postDeployProbes` | `string[]` | Check names to run in the Functional gate |
+| `rollbackOnProbeFailure` | `boolean` | Whether functional probe failures trigger rollback |
+
+You can extend or override defaults:
+
+```typescript
+const myConfig: EnvironmentConfig = {
+  ...DEFAULT_ENVIRONMENTS.staging,
+  backupBefore: false,  // Skip backups for faster deploys
+  postDeployProbes: [...DEFAULT_ENVIRONMENTS.staging.postDeployProbes, 'custom-probe'],
+};
+```
+
+## Types Reference
+
+All types are exported from the package root.
+
+| Type | Description |
+|------|-------------|
+| `CheckResult` | Single pass/fail check with name, expected, actual, error, duration |
+| `GateDefinition` | Gate configuration: id, name, check names, failure action, optional condition |
+| `GateResult` | Gate execution result: status, checks, timing |
+| `EnvironmentConfig` | Environment-specific deployment configuration |
+| `PipelineState` | Full pipeline run state: runId, environment, commit, gates, result |
+| `PipelineReport` | Pipeline state + summary statistics |
+| `CheckExecutor` | `(ctx: ExecutionContext) => Promise<CheckResult>` — async check function |
+| `ExecutionContext` | Runtime context passed to every check executor |
+| `DeployExpectations` | Output of `deriveExpectations()`: table count/names, Cognito groups, API domain |
+
 ## Publishing
 
+The package is published to npm via `scripts/publish.sh`.
+
 ```bash
-npm run release:publish        # Publish with auto-bump
-npm run release:publish:latest # Publish to latest tag
+# Publish (auto-detects tag, auto-bumps patch if version exists)
+npm run release:publish
+
+# Publish explicitly to latest tag
+npm run release:publish:latest
+
+# Publish to beta tag
+NPM_TAG=beta npm run release:publish
 ```
 
-Uses npm token from AWS Secrets Manager (`npm/automation-token/anton-bakker-deploy-engine`).
+**What the publish script does:**
+
+1. Commits and pushes any uncommitted changes
+2. Runs tests (`npm test`)
+3. Builds (`npm run build`)
+4. Fetches the npm automation token from AWS Secrets Manager (`npm/automation-token/anton-bakker-deploy-engine`)
+5. If the current version is already published, auto-bumps patch, commits, and pushes
+6. Publishes to npm with a temporary `.npmrc` (token never stored on disk)
+
+**Environment variables:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AWS_PROFILE` | `BeyondAmbition` | AWS profile for Secrets Manager access |
+| `AWS_REGION` | `eu-west-1` | AWS region for Secrets Manager |
+| `NPM_SECRET_NAME` | `npm/automation-token/anton-bakker-deploy-engine` | Secrets Manager secret ID |
+| `NPM_TAG` | `latest` | npm publish tag |
+| `REGISTRY` | `https://registry.npmjs.org/` | npm registry URL |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Type check (no output)
+npx tsc --noEmit
+
+# Build (compiles to dist/)
+npm run build
+
+# Lint (zero warnings tolerance)
+npm run lint
+```
+
+**Project structure:**
+
+```
+├── src/
+│   ├── types.ts          # Type definitions
+│   ├── verify.ts         # Verification functions
+│   ├── engine.ts         # PipelineEngine class
+│   ├── pipeline.ts       # Gate builder + default configs
+│   └── index.ts          # Public exports
+├── __tests__/
+│   ├── verify.test.ts    # 48 tests for verification functions
+│   ├── engine.test.ts    # 13 tests for engine + pipeline
+│   └── fixtures/         # Test fixtures (schema, config, auth stack)
+├── scripts/
+│   └── publish.sh        # npm publish script
+├── eslint.config.js      # ESLint flat config
+├── tsconfig.json         # TypeScript config (strict, ESM, NodeNext)
+└── package.json
+```
+
+**Test runner:** Vitest. All 61 tests run in ~200ms.
+
+**TypeScript config:** Strict mode, ESM (`"type": "module"`), `NodeNext` module resolution, source maps and declaration maps enabled.
+
+**ESLint rules:** `no-console: error`, `@typescript-eslint/no-unused-vars: error`.
 
 ## Licence