anton-bakker-deploy-engine 0.1.0 → 0.2.0

package/dist/engine.d.ts

@@ -0,0 +1,23 @@
+import type { GateDefinition, PipelineReport, CheckExecutor, ExecutionContext } from './types.js';
+export declare class PipelineEngine {
+    private gates;
+    private checks;
+    private state;
+    private stateDir;
+    private ctx;
+    constructor(opts: {
+        gates: GateDefinition[];
+        checks: Map<string, CheckExecutor>;
+        ctx: ExecutionContext;
+        stateDir?: string;
+    });
+    private statePath;
+    private saveState;
+    /** Run all gates in order. Returns the pipeline report. */
+    run(): Promise<PipelineReport>;
+    private executeGate;
+    private buildReport;
+    private saveReport;
+    /** Clear state for a fresh run */
+    static clearState(stateDir: string, environment: string): void;
+}

package/dist/engine.js

@@ -0,0 +1,156 @@
+/**
+ * src/engine.ts — Pipeline gate executor with state persistence.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+export class PipelineEngine {
+    gates;
+    checks;
+    state;
+    stateDir;
+    ctx;
+    constructor(opts) {
+        this.gates = opts.gates;
+        this.checks = opts.checks;
+        this.ctx = opts.ctx;
+        this.stateDir = opts.stateDir || join(opts.ctx.projectRoot, 'orchestrator');
+        // Load or create state
+        const statePath = this.statePath();
+        if (!opts.ctx.dryRun && existsSync(statePath)) {
+            this.state = JSON.parse(readFileSync(statePath, 'utf-8'));
+            this.ctx.log(`Resuming run ${this.state.runId} (${this.state.gates.filter(g => g.status === 'passed').length} gates already passed)`);
+        }
+        else {
+            this.state = {
+                runId: `deploy-${new Date().toISOString().replace(/[:.]/g, '-')}`,
+                environment: opts.ctx.environment,
+                commit: opts.ctx.exec('git rev-parse --short HEAD')?.trim() || 'unknown',
+                startedAt: new Date().toISOString(),
+                result: 'running',
+                gates: [],
+            };
+        }
+    }
+    statePath() {
+        return join(this.stateDir, `deploy-state-${this.ctx.environment}.json`);
+    }
+    saveState() {
+        if (this.ctx.dryRun)
+            return;
+        mkdirSync(this.stateDir, { recursive: true });
+        writeFileSync(this.statePath(), JSON.stringify(this.state, null, 2));
+    }
+    /** Run all gates in order. Returns the pipeline report. */
+    async run() {
+        const start = Date.now();
+        for (const gate of this.gates) {
+            // Skip if condition not met
+            if (gate.condition && !gate.condition(this.ctx.envConfig)) {
+                const skipped = {
+                    id: gate.id, name: gate.name, status: 'skipped', onFail: gate.onFail,
+                    checks: [], startedAt: new Date().toISOString(), completedAt: new Date().toISOString(), duration: 0,
+                };
+                this.state.gates.push(skipped);
+                this.ctx.log(`⏭️  Gate ${gate.name}: skipped (condition not met)`);
+                continue;
+            }
+            // Skip if already passed (resume)
+            const existing = this.state.gates.find(g => g.id === gate.id);
+            if (existing?.status === 'passed') {
+                this.ctx.log(`✅ Gate ${gate.name}: already passed (resuming)`);
+                continue;
+            }
+            // Execute gate
+            const gateResult = await this.executeGate(gate);
+            // Replace or append
+            const idx = this.state.gates.findIndex(g => g.id === gate.id);
+            if (idx >= 0)
+                this.state.gates[idx] = gateResult;
+            else
+                this.state.gates.push(gateResult);
+            this.saveState();
+            if (gateResult.status === 'failed') {
+                this.ctx.log(`❌ Gate ${gate.name} FAILED → ${gate.onFail.toUpperCase()}`);
+                this.state.result = gate.onFail === 'rollback' ? 'rolled-back' : 'failed';
+                this.state.completedAt = new Date().toISOString();
+                this.saveState();
+                return this.buildReport(Date.now() - start, gate);
+            }
+        }
+        this.state.result = 'passed';
+        this.state.completedAt = new Date().toISOString();
+        this.saveState();
+        this.saveReport(Date.now() - start);
+        return this.buildReport(Date.now() - start);
+    }
+    async executeGate(gate) {
+        const gateStart = Date.now();
+        this.ctx.log(`\n🔒 Gate ${gate.name}`);
+        const results = [];
+        for (const checkName of gate.checks) {
+            const executor = this.checks.get(checkName);
+            if (!executor) {
+                results.push({ name: checkName, passed: false, error: `No executor registered for '${checkName}'` });
+                this.ctx.log(`  ❌ ${checkName}: no executor registered`);
+                continue;
+            }
+            const checkStart = Date.now();
+            try {
+                const result = await executor(this.ctx);
+                result.duration = Date.now() - checkStart;
+                results.push(result);
+                this.ctx.log(`  ${result.passed ? '✅' : '❌'} ${result.name}: ${result.actual ?? (result.passed ? 'OK' : result.error)}`);
+            }
+            catch (err) {
+                const result = {
+                    name: checkName, passed: false, duration: Date.now() - checkStart,
+                    error: err.message,
+                };
+                results.push(result);
+                this.ctx.log(`  ❌ ${checkName}: ${result.error}`);
+            }
+        }
+        return {
+            id: gate.id, name: gate.name, onFail: gate.onFail,
+            status: results.every(r => r.passed) ? 'passed' : 'failed',
+            checks: results,
+            startedAt: new Date(gateStart).toISOString(),
+            completedAt: new Date().toISOString(),
+            duration: Date.now() - gateStart,
+        };
+    }
+    buildReport(duration, failedGate) {
+        return {
+            state: this.state,
+            summary: {
+                totalGates: this.state.gates.length,
+                passed: this.state.gates.filter(g => g.status === 'passed').length,
+                failed: this.state.gates.filter(g => g.status === 'failed').length,
+                skipped: this.state.gates.filter(g => g.status === 'skipped').length,
+                duration,
+                failedGate: failedGate?.id,
+                action: failedGate?.onFail,
+            },
+        };
+    }
+    saveReport(duration) {
+        if (this.ctx.dryRun)
+            return;
+        const reportDir = join(this.stateDir, 'deploy-reports');
+        mkdirSync(reportDir, { recursive: true });
+        const ts = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 16);
+        const report = this.buildReport(duration);
+        writeFileSync(join(reportDir, `${ts}-${this.ctx.envShort}.json`), JSON.stringify(report, null, 2));
+    }
+    /** Clear state for a fresh run */
+    static clearState(stateDir, environment) {
+        const path = join(stateDir, `deploy-state-${environment}.json`);
+        if (existsSync(path)) {
+            const archiveDir = join(stateDir, 'archive');
+            mkdirSync(archiveDir, { recursive: true });
+            const ts = new Date().toISOString().replace(/[:.]/g, '-');
+            const { renameSync } = require('fs');
+            renameSync(path, join(archiveDir, `state-${ts}.json`));
+        }
+    }
+}

package/dist/index.d.ts

@@ -4,4 +4,7 @@
  * Self-validating AWS deployment engine.
  * 4-layer verification: exists → configured → functional → project-specific.
  */
-export { verifyAmplifyOutputs, verifyBuildArtifact, parseTableCount, assertTableCount, parseEcsStatus, assertCognitoGroups, assertApiHealth, deriveExpectations, summarize, type CheckResult, type PostBuildResult, type PostDeployResult, type DeployExpectations, } from './verify.js';
+export { PipelineEngine } from './engine.js';
+export { buildGates, DEFAULT_ENVIRONMENTS } from './pipeline.js';
+export { verifyAmplifyOutputs, verifyBuildArtifact, parseTableCount, assertTableCount, parseEcsStatus, assertCognitoGroups, assertApiHealth, deriveExpectations, summarize, } from './verify.js';
+export type { CheckResult, GateDefinition, GateResult, EnvironmentConfig, PipelineState, PipelineReport, CheckExecutor, ExecutionContext, } from './types.js';

package/dist/index.js

@@ -4,12 +4,9 @@
  * Self-validating AWS deployment engine.
  * 4-layer verification: exists → configured → functional → project-specific.
  */
-export { 
-// Post-build verification
-verifyAmplifyOutputs, verifyBuildArtifact, 
-// Post-deploy assertions
-parseTableCount, assertTableCount, parseEcsStatus, assertCognitoGroups, assertApiHealth, 
-// Expectations derivation
-deriveExpectations, 
-// Summary
-summarize, } from './verify.js';
+// Core engine
+export { PipelineEngine } from './engine.js';
+// Pipeline builder
+export { buildGates, DEFAULT_ENVIRONMENTS } from './pipeline.js';
+// Verification functions (Layer 1-3 checks)
+export { verifyAmplifyOutputs, verifyBuildArtifact, parseTableCount, assertTableCount, parseEcsStatus, assertCognitoGroups, assertApiHealth, deriveExpectations, summarize, } from './verify.js';

package/dist/pipeline.d.ts

@@ -0,0 +1,11 @@
+/**
+ * src/pipeline.ts — Builds a pipeline definition from environment config.
+ */
+import type { GateDefinition, EnvironmentConfig } from './types.js';
+/**
+ * Build the gate sequence for a given environment.
+ * No hardcoded environment checks — all driven by config.
+ */
+export declare function buildGates(env: EnvironmentConfig): GateDefinition[];
+/** Default environment configs */
+export declare const DEFAULT_ENVIRONMENTS: Record<string, EnvironmentConfig>;

package/dist/pipeline.js

@@ -0,0 +1,110 @@
+/**
+ * Build the gate sequence for a given environment.
+ * No hardcoded environment checks — all driven by config.
+ */
+export function buildGates(env) {
+    return [
+        {
+            id: 'preflight',
+            name: 'Preflight',
+            checks: ['aws-creds', 'deploy-lock'],
+            onFail: 'abort',
+        },
+        {
+            id: 'code-quality',
+            name: 'Code Quality',
+            checks: env.preDeployChecks,
+            onFail: 'abort',
+        },
+        {
+            id: 'infra-validation',
+            name: 'Infrastructure Validation',
+            checks: ['cdk-synth', 'derive-expectations'],
+            onFail: 'abort',
+        },
+        {
+            id: 'pre-deploy-safety',
+            name: 'Pre-Deploy Safety',
+            checks: [
+                ...(env.backupBefore ? ['backup-tables'] : []),
+                ...(env.migrations ? ['prepare-migrations'] : []),
+            ],
+            onFail: 'abort',
+            condition: (e) => e.backupBefore || e.migrations,
+        },
+        {
+            id: 'build',
+            name: 'Build',
+            checks: ['docker-build', 'frontend-build', 'post-build-verify'],
+            onFail: 'abort',
+        },
+        {
+            id: 'deploy',
+            name: 'Deploy',
+            checks: ['cdk-deploy', 'ecs-update', 'frontend-deploy', ...(env.seed.enabled ? ['seed-data'] : [])],
+            onFail: 'rollback',
+        },
+        {
+            id: 'inventory',
+            name: 'Post-Deploy Inventory',
+            checks: ['table-count', 'ecs-status', 'cognito-groups'],
+            onFail: 'rollback',
+        },
+        {
+            id: 'configuration',
+            name: 'Post-Deploy Configuration',
+            checks: ['pitr-enabled', 'billing-mode', 'https-enforced', 's3-not-public'],
+            onFail: 'alert',
+        },
+        {
+            id: 'functional',
+            name: 'Post-Deploy Functional',
+            checks: env.postDeployProbes,
+            onFail: env.rollbackOnProbeFailure ? 'rollback' : 'alert',
+        },
+        {
+            id: 'project',
+            name: 'Project Assertions',
+            checks: ['manifest-assertions', ...(env.e2eTests ? ['e2e-tests'] : [])],
+            onFail: 'alert',
+        },
+    ];
+}
+/** Default environment configs */
+export const DEFAULT_ENVIRONMENTS = {
+    development: {
+        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: {
+        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: {
+        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,
+    },
+};

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * src/types.ts — Core types for the deployment pipeline engine.
+ */
+export interface CheckResult {
+    name: string;
+    passed: boolean;
+    expected?: string | number;
+    actual?: string | number;
+    duration?: number;
+    error?: string;
+}
+export interface GateDefinition {
+    id: string;
+    name: string;
+    checks: string[];
+    onFail: 'abort' | 'rollback' | 'alert';
+    condition?: (env: EnvironmentConfig) => boolean;
+}
+export interface EnvironmentConfig {
+    approval: 'never' | 'broadening' | 'always';
+    preDeployChecks: string[];
+    migrations: boolean;
+    seed: {
+        enabled: boolean;
+        skipCalendar?: boolean;
+    };
+    e2eTests: boolean;
+    e2eTestSuite?: string;
+    backupBefore: boolean;
+    cdkNagLevel: 'warning' | 'error';
+    postDeployProbes: string[];
+    rollbackOnProbeFailure: boolean;
+}
+export interface GateResult {
+    id: string;
+    name: string;
+    status: 'passed' | 'failed' | 'skipped';
+    onFail: 'abort' | 'rollback' | 'alert';
+    checks: CheckResult[];
+    startedAt: string;
+    completedAt: string;
+    duration: number;
+}
+export interface PipelineState {
+    runId: string;
+    environment: string;
+    commit: string;
+    startedAt: string;
+    completedAt?: string;
+    result: 'running' | 'passed' | 'failed' | 'rolled-back';
+    gates: GateResult[];
+}
+export interface PipelineReport {
+    state: PipelineState;
+    summary: {
+        totalGates: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        duration: number;
+        failedGate?: string;
+        action?: 'abort' | 'rollback' | 'alert';
+    };
+}
+/** A check executor — runs a named check and returns a result */
+export type CheckExecutor = (ctx: ExecutionContext) => Promise<CheckResult>;
+export interface ExecutionContext {
+    environment: string;
+    envShort: string;
+    prefix: string;
+    region: string;
+    account: string;
+    projectRoot: string;
+    dryRun: boolean;
+    envConfig: EnvironmentConfig;
+    expectations?: Record<string, unknown>;
+    /** Run a shell command, return stdout */
+    exec: (cmd: string) => string | null;
+    /** Log a message */
+    log: (msg: string) => void;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * src/types.ts — Core types for the deployment pipeline engine.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anton-bakker-deploy-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Self-validating AWS deployment engine with 4-layer verification: exists, configured, functional, project-specific",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,4 +33,4 @@
     "vitest": "^4.1.2",
     "@types/node": "^20.0.0"
   }
-}
+}