stacktape 3.5.7 → 3.6.0-beta.0

package/ai-docs/concept/directives.md

@@ -0,0 +1,371 @@
+---
+docType: concept
+title: Directives
+tags:
+  - directives
+  - concept
+source: docs/_curated-docs/concepts/directives.mdx
+priority: 1
+---
+
+# Directives
+
+Directives are special functions (prefixed with `$`) that add dynamic behavior to your configuration. They allow you to reference secrets, resource parameters, and other dynamic values.
+
+## Types of Directives
+
+There are two categories of directives:
+
+1. **Local directives**: Resolved when Stacktape parses your config (before deployment)
+2. **Runtime directives**: Resolved by CloudFormation during deployment
+
+## Local Directives
+
+These are resolved immediately when Stacktape reads your configuration.
+
+### $Stage()
+
+Returns the current stage name.
+
+```yaml
+resources:
+  api:
+    type: http-api-gateway
+    properties:
+      customDomains:
+        - domainName: $Format('api-{}.example.com', $Stage())
+```
+
+### $Region()
+
+Returns the current AWS region.
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: AWS_REGION
+          value: $Region()
+```
+
+### $Var()
+
+References a value from the `variables` section.
+
+```yaml
+variables:
+  instanceSize: db.t4g.micro
+  apiDomain: api.example.com
+
+resources:
+  database:
+    type: relational-database
+    properties:
+      engine:
+        type: postgres
+        properties:
+          primaryInstance:
+            instanceSize: $Var('instanceSize')
+```
+
+### $File()
+
+Loads and parses a file. Supports `.env`, `.json`, `.yml`, `.yaml`, and `.ini` files.
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      # Load environment variables from .env file
+      environment: $File('.env')
+```
+
+For `.env` files, this returns an array of `{ name, value }` objects.
+
+### $FileRaw()
+
+Reads a file as a raw UTF-8 string.
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: CONFIG
+          value: $FileRaw('./config.json')
+```
+
+### $Format()
+
+String interpolation using `{}` placeholders.
+
+```yaml
+resources:
+  api:
+    type: http-api-gateway
+    properties:
+      customDomains:
+        - domainName: $Format('{}-api.example.com', $Stage())
+        # dev -> "dev-api.example.com"
+```
+
+Multiple placeholders:
+
+```yaml
+environment:
+  - name: APP_URL
+    value: $Format('https://{}.{}.example.com', $Stage(), $Region())
+    # -> "https://dev.us-east-1.example.com"
+```
+
+### $GitInfo()
+
+Returns information about the current git repository.
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: GIT_COMMIT
+          value: $GitInfo('commit')
+        - name: GIT_BRANCH
+          value: $GitInfo('branch')
+```
+
+Available properties:
+
+- `commit` - Current commit SHA
+- `branch` - Current branch name
+- `username` - Git username
+- `gitUrl` - Repository URL
+
+### $CliArgs()
+
+Accesses additional CLI arguments passed after `--`.
+
+```bash
+stacktape deploy --stage dev --region us-east-1 -- --myArg=value
+```
+
+```yaml
+variables:
+  myArg: $CliArgs('myArg')
+```
+
+### $StackOutput()
+
+References outputs from another Stacktape stack.
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: SHARED_DB_URL
+          value: $StackOutput('shared-infra-dev', 'database', 'connectionString')
+```
+
+Arguments: `(stackName, resourceName, paramName)`
+
+## Runtime Directives
+
+These are resolved by CloudFormation during deployment. Use them for values that don't exist until resources are created.
+
+### $Secret()
+
+References a secret from AWS Secrets Manager.
+
+```yaml
+resources:
+  database:
+    type: relational-database
+    properties:
+      credentials:
+        masterUserPassword: $Secret('db-password')
+```
+
+Create secrets using the CLI:
+
+```bash
+stacktape secret:create --region us-east-1
+# Enter name: db-password
+# Enter value: your-secure-password
+```
+
+#### JSON Secrets
+
+If your secret contains JSON, access specific keys with dot notation:
+
+```bash
+# Create a JSON secret
+stacktape secret:create --region us-east-1
+# name: api-keys
+# value: {"stripe": "sk_...", "sendgrid": "SG..."}
+```
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: STRIPE_KEY
+          value: $Secret('api-keys.stripe')
+        - name: SENDGRID_KEY
+          value: $Secret('api-keys.sendgrid')
+```
+
+### $ResourceParam()
+
+References a parameter from another resource. Used for values that are only known after deployment (URLs, ARNs, etc.).
+
+```yaml
+resources:
+  api:
+    type: http-api-gateway
+
+  frontend:
+    type: hosting-bucket
+    properties:
+      environment:
+        - name: API_URL
+          value: $ResourceParam('api', 'url')
+```
+
+Common parameters by resource type:
+
+| Resource Type         | Parameters                                        |
+| --------------------- | ------------------------------------------------- |
+| `http-api-gateway`    | `url`, `arn`, `id`                                |
+| `relational-database` | `connectionString`, `host`, `port`, `name`, `arn` |
+| `dynamo-db-table`     | `tableName`, `tableArn`, `streamArn`              |
+| `bucket`              | `bucketName`, `bucketArn`, `domainName`           |
+| `sqs-queue`           | `queueUrl`, `queueArn`                            |
+| `sns-topic`           | `topicArn`                                        |
+| `user-auth-pool`      | `id`, `arn`, `clientId`                           |
+
+### $CfResourceParam()
+
+References a parameter from a raw CloudFormation resource.
+
+```yaml
+cloudformationResources:
+  mySnsTopic:
+    Type: AWS::SNS::Topic
+    Properties:
+      TopicName: my-topic
+
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: TOPIC_ARN
+          value: $CfResourceParam('mySnsTopic', 'Arn')
+```
+
+### $CfFormat()
+
+Like `$Format()`, but resolved at CloudFormation deployment time. Use when combining runtime values.
+
+```yaml
+resources:
+  database:
+    type: relational-database
+
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: JDBC_URL
+          value: $CfFormat('jdbc:postgresql://{}:{}/{}',
+            $ResourceParam('database', 'host'),
+            $ResourceParam('database', 'port'),
+            $ResourceParam('database', 'name'))
+```
+
+### $CfStackOutput()
+
+Like `$StackOutput()`, but resolved at deployment time with deletion protection.
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: SHARED_QUEUE_URL
+          value: $CfStackOutput('shared-infra-dev', 'queue', 'queueUrl')
+```
+
+## TypeScript Equivalents
+
+In TypeScript configuration, import directive functions:
+
+```typescript
+import { defineConfig, $Secret, $ResourceParam, $Format } from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const database = new RelationalDatabase({
+    credentials: {
+      masterUserPassword: $Secret('db-password')
+    }
+  });
+
+  const handler = new LambdaFunction({
+    environment: {
+      DB_HOST: $ResourceParam('database', 'host'),
+      APP_URL: $Format('https://{}.example.com', stage)
+    }
+  });
+
+  return { resources: { database, handler } };
+});
+```
+
+## Directive Nesting
+
+Directives can be nested up to 2 levels deep:
+
+```yaml
+# ✅ Valid - 2 levels
+environment:
+  - name: URL
+    value: $Format('{}/api', $ResourceParam('api', 'url'))
+
+# ❌ Invalid - 3 levels (use $Var to work around)
+environment:
+  - name: URL
+    value: $Format('{}/{}', $Format('{}', $Stage()), $ResourceParam('api', 'url'))
+```
+
+Workaround using `$Var()`:
+
+```yaml
+variables:
+  stagePrefix: $Format('{}-', $Stage())
+
+resources:
+  handler:
+    type: function
+    properties:
+      environment:
+        - name: URL
+          value: $Format('{}/{}', $Var('stagePrefix'), $ResourceParam('api', 'url'))
+```
+
+## Where Directives Can Be Used
+
+| Directive Type                        | Where Usable                               |
+| ------------------------------------- | ------------------------------------------ |
+| Local (`$Stage`, `$File`, etc.)       | Anywhere in config                         |
+| Runtime (`$Secret`, `$ResourceParam`) | Only in `resources` and `scripts` sections |
+
+## Next Steps

package/ai-docs/concept/extending-cloudformation.md

@@ -0,0 +1,315 @@
+---
+docType: concept
+title: CloudFormation Resources
+tags:
+  - cloudformation
+  - resources
+  - concept
+source: docs/_curated-docs/concepts/extending-cloudformation.mdx
+priority: 1
+---
+
+# CloudFormation Resources
+
+Use the `cloudformationResources` section to add native CloudFormation resources to your stack. This gives you access to any AWS resource that CloudFormation supports.
+
+## When to Use
+
+- AWS resource not natively supported by Stacktape
+- Need low-level control over resource configuration
+- Migrating existing CloudFormation templates
+
+## Basic Example
+
+Add an SNS topic using CloudFormation:
+
+```ts
+import { defineConfig } from 'stacktape';
+
+export default defineConfig({
+  resources: {
+    processData: {
+      type: 'function',
+      properties: {
+        packaging: {
+          type: 'stacktape-lambda-buildpack',
+          properties: {
+            entryfilePath: 'src/process.ts'
+          }
+        },
+        environment: [
+          {
+            name: 'SNS_TOPIC_ARN',
+            value: '$CfResourceParam(\'AlertTopic\', \'TopicArn\')'
+          }
+        ]
+      }
+    }
+  },
+
+cloudformationResources: {
+AlertTopic: {
+Type: 'AWS::SNS::Topic',
+Properties: {
+TopicName: 'my-alert-topic',
+DisplayName: 'Alert Notifications'
+}
+}
+}
+});
+
+```
+
+## Syntax
+
+CloudFormation resources use the standard CloudFormation syntax:
+
+```ts
+cloudformationResources: {
+  LogicalResourceName: {
+    Type: 'AWS::Service::Resource',
+    Properties: {
+      // Resource-specific properties
+    }
+  }
+}
+```
+
+## Referencing CloudFormation Resources
+
+### Get Resource Attributes
+
+Use `$CfResourceParam()` to get attributes from CloudFormation resources:
+
+```ts
+// Get the ARN of an SNS topic
+'$CfResourceParam(\'AlertTopic\', \'TopicArn\')';
+
+// Get the name of an S3 bucket
+'$CfResourceParam(\'DataBucket\', \'BucketName\')';
+
+// Get the physical ID (usually the resource name)
+'$CfResourceParam(\'AlertTopic\', \'Ref\')';
+```
+
+### In Environment Variables
+
+```ts
+{
+  myFunction: {
+    type: 'function',
+    properties: {
+      packaging: {
+        type: 'stacktape-lambda-buildpack',
+        properties: { entryfilePath: 'src/handler.ts' }
+      },
+      environment: [
+        {
+          name: 'TOPIC_ARN',
+          value: '$CfResourceParam(\'AlertTopic\', \'TopicArn\')'
+        },
+        {
+          name: 'BUCKET_NAME',
+          value: '$CfResourceParam(\'DataBucket\', \'BucketName\')'
+        }
+      ]
+    }
+  }
+}
+```
+
+## Common CloudFormation Resources
+
+### SNS Topic
+
+```ts
+cloudformationResources: {
+  AlertTopic: {
+    Type: 'AWS::SNS::Topic',
+    Properties: {
+      TopicName: 'alerts',
+      DisplayName: 'Alert Notifications'
+    }
+  }
+}
+```
+
+### SNS Subscription
+
+```ts
+cloudformationResources: {
+  EmailSubscription: {
+    Type: 'AWS::SNS::Subscription',
+    Properties: {
+      TopicArn: '$CfResourceParam(\'AlertTopic\', \'TopicArn\')',
+      Protocol: 'email',
+      Endpoint: 'alerts@example.com'
+    }
+  }
+}
+```
+
+### IAM Role
+
+```ts
+cloudformationResources: {
+  CustomRole: {
+    Type: 'AWS::IAM::Role',
+    Properties: {
+      RoleName: 'custom-role',
+      AssumeRolePolicyDocument: {
+        Version: '2012-10-17',
+        Statement: [
+          {
+            Effect: 'Allow',
+            Principal: { Service: 'lambda.amazonaws.com' },
+            Action: 'sts:AssumeRole'
+          }
+        ]
+      },
+      Policies: [
+        {
+          PolicyName: 'custom-policy',
+          PolicyDocument: {
+            Version: '2012-10-17',
+            Statement: [
+              {
+                Effect: 'Allow',
+                Action: ['s3:GetObject'],
+                Resource: '*'
+              }
+            ]
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+### CloudWatch Log Group
+
+```ts
+cloudformationResources: {
+  CustomLogGroup: {
+    Type: 'AWS::Logs::LogGroup',
+    Properties: {
+      LogGroupName: '/custom/logs',
+      RetentionInDays: 30
+    }
+  }
+}
+```
+
+### Secrets Manager Secret
+
+```ts
+cloudformationResources: {
+  ApiSecret: {
+    Type: 'AWS::SecretsManager::Secret',
+    Properties: {
+      Name: 'api-credentials',
+      Description: 'API credentials for third-party service',
+      GenerateSecretString: {
+        SecretStringTemplate: '{"username": "admin"}',
+        GenerateStringKey: 'password',
+        PasswordLength: 32
+      }
+    }
+  }
+}
+```
+
+## Connecting Stacktape and CloudFormation Resources
+
+### Lambda Triggered by SNS
+
+```ts
+import { defineConfig } from 'stacktape';
+
+export default defineConfig({
+  resources: {
+    alertHandler: {
+      type: 'function',
+      properties: {
+        packaging: {
+          type: 'stacktape-lambda-buildpack',
+          properties: { entryfilePath: 'src/alert-handler.ts' }
+        },
+        events: [
+          {
+            type: 'sns',
+            properties: {
+              topicArn: '$CfResourceParam(\'AlertTopic\', \'TopicArn\')'
+            }
+          }
+        ]
+      }
+    }
+  },
+
+cloudformationResources: {
+AlertTopic: {
+Type: 'AWS::SNS::Topic',
+Properties: {
+TopicName: 'alerts'
+}
+}
+}
+});
+
+```
+
+### Referencing Stacktape Resources in CloudFormation
+
+Use `$ResourceParam()` to reference Stacktape resources from CloudFormation:
+
+```ts
+cloudformationResources: {
+  LambdaPermission: {
+    Type: 'AWS::Lambda::Permission',
+    Properties: {
+      FunctionName: '$ResourceParam(\'myFunction\', \'arn\')',
+      Action: 'lambda:InvokeFunction',
+      Principal: 'sns.amazonaws.com',
+      SourceArn: '$CfResourceParam(\'AlertTopic\', \'TopicArn\')'
+    }
+  }
+}
+```
+
+## DependsOn
+
+Control resource creation order:
+
+```ts
+cloudformationResources: {
+  TopicSubscription: {
+    Type: 'AWS::SNS::Subscription',
+    DependsOn: ['AlertTopic'],
+    Properties: {
+      TopicArn: '$CfResourceParam(\'AlertTopic\', \'TopicArn\')',
+      Protocol: 'email',
+      Endpoint: 'admin@example.com'
+    }
+  }
+}
+```
+
+## Finding Resource Types
+
+See the [AWS CloudFormation Resource Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) for all available resource types and their properties.
+
+## Best Practices
+
+1. **Use Stacktape resources when available** - They provide better defaults and integration
+2. **Name resources consistently** - Include stack/stage in names to avoid conflicts
+3. **Document custom resources** - Explain why CloudFormation was needed
+4. **Test thoroughly** - CloudFormation errors can be cryptic
+
+## Limitations
+
+- CloudFormation resources don't benefit from Stacktape's simplified configuration
+- IAM permissions must be managed manually
+- No automatic `connectTo` support
+- Updates may require more careful planning (some properties can't be updated in-place)