npm package: @fnd-platform/pipeline
Description: CDK Pipeline constructs for automated deployments in fnd-platform
Latest version: 1.0.0-alpha.5

# @fnd-platform/pipeline

CDK Pipeline constructs for automated CI/CD deployments in fnd-platform applications. Provides CodePipeline integration with multi-stage deployment, caching, and build metrics.

## Installation

```bash
npm install @fnd-platform/pipeline
# or
pnpm add @fnd-platform/pipeline
```

## Quick Start

```typescript
import * as cdk from 'aws-cdk-lib';
import {
  FndPipeline,
  createGitHubSource,
  createDevStage,
  createProdStage,
} from '@fnd-platform/pipeline';

const app = new cdk.App();

const pipeline = new FndPipeline(app, 'Pipeline', {
  appName: 'my-app',
  source: createGitHubSource({
    owner: 'my-org',
    repo: 'my-repo',
    branch: 'main',
    connectionArn: 'arn:aws:codestar-connections:...',
  }),
});

// Add deployment stages
pipeline.addStage(
  createDevStage({
    env: { account: '111111111111', region: 'us-east-1' },
  })
);

pipeline.addStage(
  createProdStage({
    env: { account: '222222222222', region: 'us-east-1' },
    manualApproval: true,
  })
);
```

## Features

- **CodePipeline Integration** - Native AWS CI/CD with CDK
- **Multi-Stage Deployment** - Dev, staging, production environments
- **Source Providers** - GitHub (OAuth, CodeStar) and CodeCommit
- **Build Caching** - pnpm store, NX cache, and Docker layer caching
- **Build Metrics** - CloudWatch metrics and alarms
- **Manual Approvals** - Production gate approvals
- **Post-Deploy Validation** - Smoke tests and health checks

## Source Configuration

### GitHub with CodeStar Connection

```typescript
import { createGitHubSource } from '@fnd-platform/pipeline';

const source = createGitHubSource({
  owner: 'my-org',
  repo: 'my-repo',
  branch: 'main',
  connectionArn: 'arn:aws:codestar-connections:us-east-1:123456789:connection/xxx',
});
```

### GitHub with OAuth

```typescript
const source = createGitHubSource({
  owner: 'my-org',
  repo: 'my-repo',
  branch: 'main',
  oauthToken: cdk.SecretValue.secretsManager('github-token'),
});
```

### CodeCommit

```typescript
import { createCodeCommitSource } from '@fnd-platform/pipeline';

const source = createCodeCommitSource({
  repositoryName: 'my-repo',
  branch: 'main',
});
```

## Multi-Stage Deployment

### Using Stage Helpers

```typescript
import {
  createDevStage,
  createStagingStage,
  createProdStage,
  withManualApproval,
  withSmokeTest,
} from '@fnd-platform/pipeline';

// Dev stage - auto deploys
pipeline.addStage(
  createDevStage({
    env: { account: '111111111111', region: 'us-east-1' },
  })
);

// Staging with smoke tests
pipeline.addStage(
  createStagingStage({
    env: { account: '111111111111', region: 'us-east-1' },
    ...withSmokeTest({ endpoint: 'https://staging.example.com/health' }),
  })
);

// Production with manual approval
pipeline.addStage(
  createProdStage({
    env: { account: '222222222222', region: 'us-east-1' },
    ...withManualApproval({ approvers: ['admin@example.com'] }),
  })
);
```

### Custom Stage

```typescript
import { FndDeploymentStage } from '@fnd-platform/pipeline';

const customStage = new FndDeploymentStage(app, 'CustomStage', {
  stageName: 'custom',
  env: { account: '333333333333', region: 'eu-west-1' },
  environmentVariables: {
    FEATURE_FLAG_X: 'true',
  },
});

pipeline.addStage(customStage);
```

## Build Configuration

### Custom Build Commands

```typescript
import { getBuildCommands } from '@fnd-platform/pipeline';

const pipeline = new FndPipeline(app, 'Pipeline', {
  appName: 'my-app',
  source: source,
  buildCommands: getBuildCommands({
    install: ['pnpm install --frozen-lockfile'],
    build: ['pnpm build', 'pnpm test'],
    synth: ['cd packages/infra && pnpm cdk synth'],
  }),
});
```

### Build Defaults

```typescript
import {
  DEFAULT_INSTALL_COMMANDS,
  DEFAULT_BUILD_COMMANDS,
  DEFAULT_TEST_COMMANDS,
  DEFAULT_SYNTH_COMMANDS,
} from '@fnd-platform/pipeline';

// Defaults:
// Install: ['pnpm install --frozen-lockfile']
// Build: ['pnpm build']
// Test: ['pnpm test']
// Synth: ['pnpm cdk synth']
```

## Caching

### Default Cache Paths

```typescript
import { DEFAULT_CACHE_PATHS, getCachePaths } from '@fnd-platform/pipeline';

// Default cache paths include:
// - node_modules/.cache
// - .nx/cache
// - pnpm store

const cachePaths = getCachePaths({
  mode: 'full', // 'minimal' | 'full'
  includeDocker: true,
});
```

### NX Cloud Integration

```typescript
const pipeline = new FndPipeline(app, 'Pipeline', {
  appName: 'my-app',
  source: source,
  nxCloud: {
    accessToken: cdk.SecretValue.secretsManager('nx-cloud-token'),
  },
});
```

## Build Metrics

### Automatic Metrics

```typescript
import { FndBuildMetrics } from '@fnd-platform/pipeline';

const metrics = new FndBuildMetrics(this, 'Metrics', {
  pipelineName: 'my-pipeline',
  alarmOnFailure: true,
  failureThreshold: 3,
  notificationEmail: 'ops@example.com',
});
```

### Metric Defaults

```typescript
import { DEFAULT_METRICS_NAMESPACE, DEFAULT_FAILURE_THRESHOLD } from '@fnd-platform/pipeline';

// Namespace: 'FndPipeline'
// Failure threshold: 3 consecutive failures
```

## API Reference

See the [full API documentation](../../docs/api/modules/pipeline_src.html) for detailed type definitions and examples.

### Main Construct

```typescript
import { FndPipeline } from '@fnd-platform/pipeline';
```

### Source Utilities

```typescript
import {
  createGitHubSource,
  createCodeCommitSource,
  isGitHubSource,
  isCodeCommitSource,
} from '@fnd-platform/pipeline';
```

### Build Commands

```typescript
import {
  getBuildCommands,
  getPrimaryOutputDirectory,
  DEFAULT_PNPM_STORE_CONFIG,
  DEFAULT_INSTALL_COMMANDS,
  DEFAULT_BUILD_COMMANDS,
  DEFAULT_TEST_COMMANDS,
  DEFAULT_SYNTH_COMMANDS,
  DEFAULT_PRIMARY_OUTPUT_DIRECTORY,
} from '@fnd-platform/pipeline';
```

### Caching

```typescript
import { DEFAULT_CACHE_PATHS, DOCKER_CACHE_PATHS, getCachePaths } from '@fnd-platform/pipeline';
```

### Metrics

```typescript
import {
  FndBuildMetrics,
  DEFAULT_METRICS_NAMESPACE,
  DEFAULT_FAILURE_THRESHOLD,
} from '@fnd-platform/pipeline';
```

### Multi-Stage Deployment

```typescript
import {
  FndDeploymentStage,
  // Stage creation helpers
  createDevStage,
  createStagingStage,
  createProdStage,
  // Stage modifiers
  withManualApproval,
  withPostDeployValidation,
  withSmokeTest,
  // Utilities
  isStandardStageName,
  validateStageConfig,
  mergeStageOptions,
  addFndStage,
  configureMultiStagePipeline,
  // Stage defaults
  DEV_STAGE_DEFAULTS,
  STAGING_STAGE_DEFAULTS,
  PROD_STAGE_DEFAULTS,
} from '@fnd-platform/pipeline';
```

### Types

```typescript
import type {
  // Pipeline types
  FndPipelineProps,
  BuildCommandsConfig,
  // Source types
  FndSourceConfig,
  GitHubSourceConfig,
  GitHubConnectionSourceConfig,
  GitHubOAuthSourceConfig,
  CodeCommitSourceConfig,
  // Cache types
  CacheMode,
  FndCacheConfig,
  FndNxCloudConfig,
  // Metrics types
  FndBuildMetricsConfig,
  FndBuildMetricsProps,
  // Stage types
  StandardStageName,
  StageName,
  StageEnvironmentVariables,
  StageEnvironmentConfig,
  StackBuilderCallback,
  FndDeploymentStageProps,
  StageConfig,
  MultiStagePipelineConfig,
  AddFndStageOptions,
  StageConfigValidationError,
  StageConfigValidationResult,
  ManualApprovalOptions,
  PostDeployValidationOptions,
  SmokeTestOptions,
} from '@fnd-platform/pipeline';
```

## Requirements

- Node.js 20+
- AWS CDK v2
- AWS CLI configured with credentials
- CodeStar Connection (for GitHub)

## Related

- [@fnd-platform/constructs](../constructs/README.md) - CDK constructs
- [@fnd-platform/api](../api/README.md) - API package
- [AWS CDK Pipelines](https://docs.aws.amazon.com/cdk/v2/guide/cdk_pipeline.html)

## License

MIT