stacktape 3.5.7 → 3.6.0-beta.0

package/ai-docs/concept/overrides-and-transforms.md

@@ -0,0 +1,352 @@
+---
+docType: concept
+title: Overrides & Transforms
+tags:
+  - overrides
+  - transforms
+  - concept
+source: docs/_curated-docs/concepts/overrides-and-transforms.mdx
+priority: 1
+---
+
+# Overrides & Transforms
+
+Stacktape generates CloudFormation templates from your configuration. Sometimes you need to customize the underlying AWS resources beyond what Stacktape exposes. Overrides and transforms give you this power.
+
+## Understanding Child Resources
+
+Each Stacktape resource creates one or more CloudFormation resources ("child resources"). For example, a `function` creates:
+
+- AWS Lambda Function
+- IAM Role
+- CloudWatch Log Group
+- (Optionally) Event Source Mappings, Permissions, etc.
+
+You can view the child resources for any Stacktape resource:
+
+```bash
+stacktape stack-info --stage dev --region us-east-1 --detailed
+```
+
+Or use the Stacktape Console's resource inspector.
+
+`[IMAGE PLACEHOLDER: console-child-resources-view]`
+
+## Overrides
+
+Overrides let you set specific properties on child CloudFormation resources.
+
+### Basic Override
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+      overrides:
+        # Override the Lambda function's description
+        StpLambdaFunction:
+          Description: 'My custom description'
+```
+
+### Finding Child Resource Names
+
+To override a property, you need to know the logical name of the child resource. Use:
+
+1. **CLI**: `stacktape stack-info --detailed`
+2. **Console**: View resource details
+3. **Compile template**: `stacktape compile-template` and inspect the output
+
+Common child resource names:
+
+| Stacktape Resource    | Child Resources                                                           |
+| --------------------- | ------------------------------------------------------------------------- |
+| `function`            | `StpLambdaFunction`, `StpLambdaFunctionRole`, `StpLambdaFunctionLogGroup` |
+| `web-service`         | `StpEcsService`, `StpEcsTaskDefinition`, `StpEcsTaskRole`                 |
+| `relational-database` | `StpRdsInstance`, `StpRdsSecurityGroup`, `StpRdsSubnetGroup`              |
+| `bucket`              | `StpS3Bucket`                                                             |
+| `http-api-gateway`    | `StpHttpApi`                                                              |
+
+### Override Example: Lambda Reserved Concurrency
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+      overrides:
+        StpLambdaFunction:
+          ReservedConcurrentExecutions: 100
+```
+
+### Override Example: S3 Bucket Policy
+
+```yaml
+resources:
+  uploads:
+    type: bucket
+    properties:
+      overrides:
+        StpS3Bucket:
+          PublicAccessBlockConfiguration:
+            BlockPublicAcls: true
+            BlockPublicPolicy: true
+            IgnorePublicAcls: true
+            RestrictPublicBuckets: true
+```
+
+### Override Example: RDS Parameter Group
+
+```yaml
+resources:
+  database:
+    type: relational-database
+    properties:
+      engine:
+        type: postgres
+        properties:
+          version: '16'
+      overrides:
+        StpRdsParameterGroup:
+          Parameters:
+            max_connections: '200'
+            shared_buffers: '256MB'
+```
+
+## Transforms
+
+Transforms are functions that modify the CloudFormation properties. They're more powerful than overrides because you can compute values based on existing properties.
+
+### Basic Transform
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+      memory: 128
+      transforms:
+        StpLambdaFunction: |
+          (props) => ({
+            ...props,
+            MemorySize: props.MemorySize * 2  // Double the memory
+          })
+```
+
+### TypeScript Transforms
+
+In TypeScript configuration, transforms are cleaner:
+
+```typescript
+import { defineConfig, LambdaFunction, StacktapeLambdaBuildpackPackaging } from 'stacktape';
+
+export default defineConfig(() => {
+  const handler = new LambdaFunction({
+    packaging: new StacktapeLambdaBuildpackPackaging({
+      entryfilePath: './src/handler.ts'
+    }),
+    memory: 128,
+    transforms: {
+      StpLambdaFunction: (props) => ({
+        ...props,
+        MemorySize: (props.MemorySize ?? 128) * 2,
+        Description: `Handler with ${props.MemorySize}MB memory`
+      })
+    }
+  });
+
+  return { resources: { handler } };
+});
+```
+
+### Transform Example: Add Lambda Layers
+
+```typescript
+const handler = new LambdaFunction({
+  packaging: new StacktapeLambdaBuildpackPackaging({
+    entryfilePath: './src/handler.ts'
+  }),
+  transforms: {
+    StpLambdaFunction: (props) => ({
+      ...props,
+      Layers: [...(props.Layers || []), 'arn:aws:lambda:us-east-1:123456789:layer:my-layer:1']
+    })
+  }
+});
+```
+
+### Transform Example: Custom ECS Task Definition
+
+```typescript
+const api = new WebService({
+  packaging: new StacktapeImageBuildpackPackaging({
+    entryfilePath: './src/server.ts'
+  }),
+  transforms: {
+    StpEcsTaskDefinition: (props) => ({
+      ...props,
+      ContainerDefinitions: props.ContainerDefinitions.map((container) => ({
+        ...container,
+        Ulimits: [{ Name: 'nofile', SoftLimit: 65536, HardLimit: 65536 }]
+      }))
+    })
+  }
+});
+```
+
+## Overrides vs Transforms
+
+| Feature        | Overrides               | Transforms               |
+| -------------- | ----------------------- | ------------------------ |
+| Syntax         | Static values           | JavaScript function      |
+| Use case       | Set specific properties | Compute or modify values |
+| Complexity     | Simple                  | More powerful            |
+| Merge behavior | Shallow merge           | Full control             |
+
+Use **overrides** when you know the exact value you want to set.
+Use **transforms** when you need to compute values or modify existing properties.
+
+## Viewing Generated CloudFormation
+
+To see the final CloudFormation template after overrides and transforms:
+
+```bash
+stacktape compile-template --stage dev --region us-east-1
+```
+
+This outputs `compiled-template.yaml` which you can inspect.
+
+## Adding Raw CloudFormation Resources
+
+For resources Stacktape doesn't support, add raw CloudFormation:
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+
+cloudformationResources:
+  # Add a custom SNS topic
+  MyCustomTopic:
+    Type: AWS::SNS::Topic
+    Properties:
+      TopicName: my-custom-topic
+      DisplayName: My Custom Topic
+
+  # Subscribe the function to the topic
+  MyTopicSubscription:
+    Type: AWS::SNS::Subscription
+    Properties:
+      Protocol: lambda
+      TopicArn: !Ref MyCustomTopic
+      Endpoint: !GetAtt StpHandlerStpLambdaFunction.Arn
+```
+
+Reference CloudFormation resources in Stacktape:
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: TOPIC_ARN
+          value: $CfResourceParam('MyCustomTopic', 'Arn')
+```
+
+## AWS CDK Constructs
+
+For complex extensions, use AWS CDK constructs:
+
+```typescript
+// cdk/monitoring.ts
+import { Construct } from 'constructs';
+import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
+
+export class MonitoringDashboard extends Construct {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    new cloudwatch.Dashboard(this, 'Dashboard', {
+      dashboardName: 'my-app-dashboard',
+      widgets: [
+        // Dashboard configuration
+      ]
+    });
+  }
+}
+```
+
+Reference in config:
+
+```yaml
+resources:
+  handler:
+    type: function
+
+cdkConstructs:
+  - constructPath: ./cdk/monitoring.ts
+    constructName: MonitoringDashboard
+```
+
+See [Extending with CDK](/extending/cdk-constructs) for more details.
+
+## Best Practices
+
+1. **Try Stacktape properties first**: Many customizations are available through standard properties
+2. **Use overrides for simple changes**: Static values that don't depend on other properties
+3. **Use transforms for computed values**: When you need to modify or compute based on existing values
+4. **Document your overrides**: Explain why you needed to override
+5. **Test thoroughly**: Overrides bypass Stacktape's validation
+6. **Keep it minimal**: The more you override, the more you need to maintain
+
+## Common Override Scenarios
+
+### Custom Lambda Runtime
+
+```yaml
+overrides:
+  StpLambdaFunction:
+    Runtime: provided.al2023
+```
+
+### ECS Health Check
+
+```yaml
+overrides:
+  StpEcsTaskDefinition:
+    ContainerDefinitions:
+      - HealthCheck:
+          Command: ['CMD-SHELL', 'curl -f http://localhost:3000/health || exit 1']
+          Interval: 30
+          Timeout: 5
+          Retries: 3
+```
+
+### RDS Enhanced Monitoring
+
+```yaml
+overrides:
+  StpRdsInstance:
+    MonitoringInterval: 60
+    MonitoringRoleArn: arn:aws:iam::123456789:role/rds-monitoring-role
+```
+
+## Next Steps

package/ai-docs/concept/stages-and-environments.md

@@ -0,0 +1,347 @@
+---
+docType: concept
+title: Stages & Environments
+tags:
+  - stages
+  - environments
+  - concept
+source: docs/_curated-docs/concepts/stages-and-environments.mdx
+priority: 1
+---
+
+# Stages & Environments
+
+Stages allow you to deploy multiple isolated environments from the same codebase. Each stage creates a completely separate set of AWS resources.
+
+## What is a Stage?
+
+A **stage** is an environment identifier like `dev`, `staging`, or `production`. When you deploy with different stages, Stacktape creates completely separate resources:
+
+```bash
+# Development environment
+stacktape deploy --stage dev --region us-east-1
+# Creates: my-app-dev stack with its own database, functions, etc.
+
+# Production environment
+stacktape deploy --stage production --region us-east-1
+# Creates: my-app-production stack with completely separate resources
+```
+
+## Stack Naming
+
+Your stack name is derived from your project name and stage:
+
+```
+{projectName}-{stage}
+```
+
+For example:
+
+- Project: `my-api`, Stage: `dev` → Stack: `my-api-dev`
+- Project: `my-api`, Stage: `production` → Stack: `my-api-production`
+
+## Stage-Based Configuration
+
+### TypeScript (Recommended)
+
+Use the `stage` parameter in `defineConfig`:
+
+```typescript
+import { defineConfig, RelationalDatabase, LambdaFunction, RdsEnginePostgres, $Secret } from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const isProduction = stage === 'production';
+
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({
+      version: '16',
+      primaryInstance: {
+        // Larger instance for production
+        instanceSize: isProduction ? 'db.t4g.medium' : 'db.t4g.micro',
+        // Multi-AZ only in production
+        multiAz: isProduction
+      }
+    }),
+    credentials: {
+      masterUserPassword: $Secret(`db-password-${stage}`)
+    },
+    // Different backup retention
+    automatedBackupRetentionDays: isProduction ? 7 : 1
+  });
+
+  const handler = new LambdaFunction({
+    // More memory for production
+    memory: isProduction ? 1024 : 256,
+    // Longer timeout for production
+    timeout: isProduction ? 30 : 10,
+    environment: {
+      NODE_ENV: isProduction ? 'production' : 'development',
+      LOG_LEVEL: isProduction ? 'warn' : 'debug'
+    }
+  });
+
+  return { resources: { database, handler } };
+});
+```
+
+### YAML with Directives
+
+In YAML, use variables and the `$Stage()` directive:
+
+```yaml
+variables:
+  instanceSize:
+    $CfIf:
+      - $CfEquals: [$Stage(), 'production']
+      - db.t4g.medium
+      - db.t4g.micro
+
+resources:
+  database:
+    type: relational-database
+    properties:
+      engine:
+        type: postgres
+        properties:
+          primaryInstance:
+            instanceSize: $Var('instanceSize')
+      credentials:
+        masterUserPassword: $Secret($Format('db-password-{}', $Stage()))
+```
+
+## Common Stage Patterns
+
+### Development → Staging → Production
+
+```typescript
+export default defineConfig(({ stage }) => {
+  const config =
+    {
+      dev: {
+        instanceSize: 'db.t4g.micro',
+        minInstances: 1,
+        maxInstances: 1,
+        multiAz: false
+      },
+      staging: {
+        instanceSize: 'db.t4g.small',
+        minInstances: 1,
+        maxInstances: 3,
+        multiAz: false
+      },
+      production: {
+        instanceSize: 'db.t4g.medium',
+        minInstances: 2,
+        maxInstances: 10,
+        multiAz: true
+      }
+    }[stage] || config.dev; // Default to dev for unknown stages
+
+  return {
+    resources: {
+      database: new RelationalDatabase({
+        engine: new RdsEnginePostgres({
+          version: '16',
+          primaryInstance: {
+            instanceSize: config.instanceSize,
+            multiAz: config.multiAz
+          }
+        })
+      }),
+      api: new WebService({
+        scaling: {
+          minInstances: config.minInstances,
+          maxInstances: config.maxInstances
+        }
+      })
+    }
+  };
+});
+```
+
+### Feature Branch Stages
+
+Create temporary environments for feature branches:
+
+```bash
+# Deploy feature branch
+stacktape deploy --stage feature-123 --region us-east-1
+
+# Test the feature
+curl https://feature-123.api.example.com
+
+# Delete when done
+stacktape delete --stage feature-123 --region us-east-1
+```
+
+### Preview Environments
+
+The Stacktape Console can automatically create preview environments for pull requests:
+
+1. Open a PR
+2. Stacktape automatically deploys a `preview-{pr-number}` stage
+3. PR gets a comment with the deployment URL
+4. When PR is merged/closed, the environment is deleted
+
+`[IMAGE PLACEHOLDER: console-preview-environments]`
+
+## Stage-Specific Secrets
+
+Create separate secrets for each stage:
+
+```bash
+# Development secrets
+stacktape secret:create --region us-east-1
+# name: db-password-dev
+# value: dev-password
+
+# Production secrets
+stacktape secret:create --region us-east-1
+# name: db-password-production
+# value: super-secure-production-password
+```
+
+Reference in config:
+
+```typescript
+export default defineConfig(({ stage }) => {
+  const database = new RelationalDatabase({
+    credentials: {
+      masterUserPassword: $Secret(`db-password-${stage}`)
+    }
+  });
+
+  return { resources: { database } };
+});
+```
+
+## Stage-Specific Domains
+
+```typescript
+export default defineConfig(({ stage }) => {
+  const api = new HttpApiGateway({
+    customDomains:
+      stage === 'production' ? [{ domainName: 'api.example.com' }] : [{ domainName: `${stage}.api.example.com` }]
+  });
+
+  return { resources: { api } };
+});
+```
+
+Results:
+
+- `production` → `api.example.com`
+- `staging` → `staging.api.example.com`
+- `dev` → `dev.api.example.com`
+
+## Conditional Resources
+
+Only create certain resources in specific stages:
+
+```typescript
+export default defineConfig(({ stage }) => {
+  const resources: Record<string, any> = {};
+
+  // Always create API
+  resources.api = new HttpApiGateway({});
+
+  // Database only in non-ephemeral stages
+  if (!stage.startsWith('preview-')) {
+    resources.database = new RelationalDatabase({
+      engine: new RdsEnginePostgres({ version: '16' })
+    });
+  }
+
+  // Monitoring only in production
+  if (stage === 'production') {
+    resources.firewall = new WebAppFirewall({ scope: 'regional' });
+  }
+
+  return { resources };
+});
+```
+
+## Sharing Resources Across Stages
+
+Sometimes you want to share certain resources (like a database) across stages. Use a separate "shared infrastructure" stack:
+
+**shared-infra/stacktape.ts:**
+
+```typescript
+export default defineConfig(() => {
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({ version: '16' })
+  });
+
+  return { resources: { database } };
+});
+```
+
+**api/stacktape.ts:**
+
+```typescript
+export default defineConfig(({ stage }) => {
+  const handler = new LambdaFunction({
+    environment: {
+      DATABASE_URL: $StackOutput(`shared-infra-${stage}`, 'database', 'connectionString')
+    }
+  });
+
+  return { resources: { handler } };
+});
+```
+
+## Default Stage and Region
+
+Set defaults to avoid typing them every time:
+
+```bash
+stacktape defaults:configure
+# Set default stage: dev
+# Set default region: us-east-1
+```
+
+Now you can deploy without specifying stage/region:
+
+```bash
+stacktape deploy
+# Uses stage=dev, region=us-east-1
+```
+
+Override when needed:
+
+```bash
+stacktape deploy --stage production --region eu-west-1
+```
+
+## Listing Stages
+
+View all deployed stacks:
+
+```bash
+stacktape stack:list --region us-east-1
+```
+
+Output:
+
+```
+┌──────────────────────┬─────────────┬─────────────────────────┐
+│ Stack Name           │ Status      │ Last Updated            │
+├──────────────────────┼─────────────┼─────────────────────────┤
+│ my-api-dev           │ DEPLOYED    │ 2024-01-15 10:30:00     │
+│ my-api-staging       │ DEPLOYED    │ 2024-01-14 15:45:00     │
+│ my-api-production    │ DEPLOYED    │ 2024-01-10 09:00:00     │
+│ my-api-feature-123   │ DEPLOYED    │ 2024-01-15 11:00:00     │
+└──────────────────────┴─────────────┴─────────────────────────┘
+```
+
+## Best Practices
+
+1. **Use consistent naming**: `dev`, `staging`, `production` or `development`, `test`, `prod`
+2. **Separate secrets per stage**: Never share production secrets with development
+3. **Start small in dev**: Use minimal resources in development to save costs
+4. **Test in staging**: Make staging as close to production as possible
+5. **Protect production**: Add additional safeguards (WAF, monitoring, multi-AZ)
+6. **Clean up feature stages**: Delete temporary stages when no longer needed
+
+## Next Steps