stacktape 3.5.7 → 3.6.0-beta.0

package/ai-docs/concept/yaml-config.md

@@ -0,0 +1,338 @@
+---
+docType: concept
+title: YAML Configuration
+tags:
+  - yaml
+  - configuration
+  - concept
+source: docs/_curated-docs/concepts/yaml-config.mdx
+priority: 1
+---
+
+# YAML Configuration
+
+YAML is a human-readable configuration format that works well for straightforward Stacktape configurations.
+
+## Basic Structure
+
+Create `stacktape.yml` in your project root:
+
+```yaml
+resources:
+  api:
+    type: http-api-gateway
+    properties:
+      cors:
+        enabled: true
+
+  handler:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+      events:
+        - type: http-api-integration
+          properties:
+            httpApiGatewayName: api
+            method: GET
+            path: /
+```
+
+## Resource Definition
+
+Each resource has three parts:
+
+```yaml
+resources:
+  resourceName: # Unique name (used for references)
+    type: resource-type # Type of resource
+    properties: # Resource-specific configuration
+      property1: value1
+      property2: value2
+```
+
+## Available Resource Types
+
+### Compute
+
+| Type                       | Description                         |
+| -------------------------- | ----------------------------------- |
+| `function`                 | Lambda function                     |
+| `edge-lambda-function`     | Lambda@Edge function                |
+| `web-service`              | ECS container with public endpoint  |
+| `private-service`          | ECS container with private endpoint |
+| `worker-service`           | ECS background container            |
+| `multi-container-workload` | Multiple containers                 |
+| `batch-job`                | AWS Batch job                       |
+| `nextjs-web`               | Next.js application                 |
+
+### Databases
+
+| Type                     | Description              |
+| ------------------------ | ------------------------ |
+| `relational-database`    | RDS/Aurora database      |
+| `dynamo-db-table`        | DynamoDB table           |
+| `redis-cluster`          | ElastiCache Redis        |
+| `mongo-db-atlas-cluster` | MongoDB Atlas            |
+| `upstash-redis`          | Upstash serverless Redis |
+| `open-search-domain`     | OpenSearch/Elasticsearch |
+
+### Networking
+
+| Type                        | Description      |
+| --------------------------- | ---------------- |
+| `http-api-gateway`          | HTTP API Gateway |
+| `application-load-balancer` | ALB              |
+| `network-load-balancer`     | NLB              |
+
+### Storage
+
+| Type             | Description                      |
+| ---------------- | -------------------------------- |
+| `bucket`         | S3 bucket                        |
+| `hosting-bucket` | S3 + CloudFront for static sites |
+| `efs-filesystem` | EFS shared storage               |
+
+### Messaging
+
+| Type        | Description     |
+| ----------- | --------------- |
+| `sqs-queue` | SQS queue       |
+| `sns-topic` | SNS topic       |
+| `event-bus` | EventBridge bus |
+
+### Security
+
+| Type               | Description                 |
+| ------------------ | --------------------------- |
+| `user-auth-pool`   | Cognito user pool           |
+| `web-app-firewall` | WAF                         |
+| `bastion`          | Bastion host for VPC access |
+
+### Other
+
+| Type            | Description    |
+| --------------- | -------------- |
+| `state-machine` | Step Functions |
+
+## Lambda Function Example
+
+```yaml
+resources:
+  myFunction:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+      memory: 512
+      timeout: 30
+      environment:
+        - name: NODE_ENV
+          value: production
+      events:
+        - type: http-api-integration
+          properties:
+            httpApiGatewayName: api
+            method: POST
+            path: /users
+        - type: schedule-integration
+          properties:
+            scheduleRate: rate(1 hour)
+```
+
+## Container Service Example
+
+```yaml
+resources:
+  webApp:
+    type: web-service
+    properties:
+      packaging:
+        type: stacktape-image-buildpack
+        properties:
+          entryfilePath: ./src/server.ts
+      resources:
+        cpu: 0.5
+        memory: 1024
+      scaling:
+        minInstances: 1
+        maxInstances: 10
+      events:
+        - type: http-api-integration
+          properties:
+            httpApiGatewayName: api
+            containerPort: 3000
+            method: '*'
+            path: '/*'
+```
+
+## Database Example
+
+```yaml
+resources:
+  database:
+    type: relational-database
+    properties:
+      engine:
+        type: postgres
+        properties:
+          version: '16'
+          primaryInstance:
+            instanceSize: db.t4g.micro
+      credentials:
+        masterUserPassword: $Secret('db-password')
+```
+
+## Using Variables
+
+Define reusable values with 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')
+
+  api:
+    type: http-api-gateway
+    properties:
+      customDomains:
+        - domainName: $Var('apiDomain')
+```
+
+## Connecting Resources
+
+Use `connectTo` to automatically handle permissions and credentials:
+
+```yaml
+resources:
+  database:
+    type: relational-database
+    properties:
+      engine:
+        type: postgres
+
+  handler:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+      connectTo:
+        - database # Automatically gets DB credentials
+```
+
+## Scripts
+
+Define reusable scripts:
+
+```yaml
+scripts:
+  migrate:
+    type: local-script
+    properties:
+      executeCommand: npx prisma migrate deploy
+      connectTo:
+        - database
+
+  seed:
+    type: local-script
+    properties:
+      executeCommand: npx prisma db seed
+      connectTo:
+        - database
+```
+
+Run scripts:
+
+```bash
+stacktape script:run --scriptName migrate --stage dev --region us-east-1
+```
+
+## Hooks
+
+Execute scripts during deployment lifecycle:
+
+```yaml
+hooks:
+  beforeDeploy:
+    - scriptName: build
+  afterDeploy:
+    - scriptName: migrate
+    - scriptName: seed
+```
+
+## VS Code Extension
+
+For the best YAML editing experience, install the [Stacktape VS Code extension](https://marketplace.visualstudio.com/items?itemName=stacktape.stacktape):
+
+- Syntax validation
+- Autocompletion
+- Inline documentation
+- Error highlighting
+
+`[IMAGE PLACEHOLDER: vscode-yaml-autocomplete]`
+
+## Limitations vs TypeScript
+
+YAML has some limitations compared to TypeScript:
+
+| Feature           | TypeScript | YAML              |
+| ----------------- | ---------- | ----------------- |
+| Type checking     | ✅         | ❌                |
+| Autocompletion    | ✅ Full    | ✅ With extension |
+| Conditional logic | ✅ Native  | ⚠️ Via directives |
+| Loops             | ✅ Native  | ❌                |
+| Code reuse        | ✅ Imports | ⚠️ Variables only |
+| IDE refactoring   | ✅         | ❌                |
+
+For complex configurations with lots of conditional logic, consider TypeScript.
+
+## Converting YAML to TypeScript
+
+Stacktape's documentation automatically shows TypeScript equivalents for YAML examples. You can also manually convert:
+
+**YAML:**
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+```
+
+**TypeScript:**
+
+```typescript
+import { defineConfig, LambdaFunction, StacktapeLambdaBuildpackPackaging } from 'stacktape';
+
+export default defineConfig(() => {
+  const handler = new LambdaFunction({
+    packaging: new StacktapeLambdaBuildpackPackaging({
+      entryfilePath: './src/handler.ts'
+    })
+  });
+
+  return { resources: { handler } };
+});
+```
+
+## Next Steps

package/ai-docs/config-ref/_root.md

@@ -0,0 +1,142 @@
+---
+docType: config-ref
+title: Stacktape Config
+tags:
+  - root
+  - config
+  - stacktape-config
+  - top-level
+source: types/stacktape-config/_root.d.ts
+priority: 1
+---
+
+# Stacktape Config
+
+## TypeScript Definition
+
+```typescript
+interface StacktapeConfig {
+  /**
+   * #### The name of this service.
+   *
+   * ---
+   *
+   * > **Deprecated:** Use the `--projectName` option in the CLI instead.
+   *
+   * The CloudFormation stack name will be in the format: `{serviceName}-{stage}`.
+   *
+   * Must be alphanumeric and can contain dashes. Must match the regex `[a-zA-Z][-a-zA-Z0-9]*`.
+   *
+   * @deprecated
+   */
+  serviceName?: string;
+  /**
+   * #### Credentials and settings for 3rd-party services (MongoDB Atlas, Upstash).
+   *
+   * ---
+   *
+   * Required only if you use `mongo-db-atlas-cluster` or `upstash-redis` resources in your stack.
+   */
+  providerConfig?: {
+    mongoDbAtlas?: MongoDbAtlasProvider;
+    upstash?: UpstashProvider;
+  };
+  /**
+   * #### Reusable values you can reference anywhere in the config with `$Var().variableName`.
+   *
+   * ---
+   *
+   * Useful for avoiding repetition. For example, define a shared environment name
+   * and reference it in multiple resources.
+   *
+   * ```yaml
+   * variables:
+   *   appPort: 3000
+   * # Then use: $Var().appPort
+   * ```
+   */
+  variables?: { [variableName: string]: any };
+  /**
+   * #### Set a monthly spending limit and get email alerts when costs approach it.
+   *
+   * ---
+   *
+   * The budget resets at the start of each calendar month. You can configure alerts
+   * based on actual spend or AWS-forecasted spend.
+   *
+   * > Not available in all regions (e.g., `ap-east-1`, `af-south-1`).
+   */
+  budgetControl?: BudgetControl;
+  /**
+   * #### Run scripts automatically before/after deploy, delete, or dev commands.
+   *
+   * ---
+   *
+   * Each hook references a script defined in the `scripts` section.
+   * Common uses: run database migrations after deploy, build frontend before deploy,
+   * clean up resources after delete.
+   */
+  hooks?: Hooks;
+  /**
+   * #### Custom shell commands or code you can run manually or as lifecycle hooks.
+   *
+   * ---
+   *
+   * Use `connectTo` in a script to auto-inject database URLs, API keys, etc. as environment variables.
+   * Run scripts with `stacktape script:run --scriptName myScript` or attach them to `hooks`.
+   *
+   * **Script types:**
+   * - **`local-script`**: Runs on your machine (or CI). Good for migrations, builds, seed scripts.
+   * - **`local-script-with-bastion-tunneling`**: Runs locally but tunnels connections to VPC-only
+   *   resources (e.g., private databases) through a bastion host.
+   * - **`bastion-script`**: Runs remotely on the bastion host inside your VPC.
+   *
+   * Scripts can be shell commands or JS/TS/Python files.
+   */
+  scripts?: { [scriptName: string]: LocalScript | BastionScript | LocalScriptWithBastionTunneling };
+  /**
+   * #### Register custom functions that dynamically compute config values at deploy time.
+   *
+   * ---
+   *
+   * Define a directive by pointing to a JS/TS/Python file, then use it anywhere in the config
+   * like a built-in directive (`$MyDirective()`). Useful for fetching external data,
+   * computing dynamic values, or conditional logic.
+   */
+  directives?: DirectiveDefinition[];
+  /**
+   * #### Advanced deployment settings: rollback behavior, termination protection, artifact retention.
+   *
+   * ---
+   *
+   * Most projects don't need to change these. Useful for production stacks where you want
+   * extra safety (termination protection, rollback alarms) or cost control (artifact cleanup).
+   */
+  deploymentConfig?: DeploymentConfig;
+  /**
+   * #### Stack-wide settings: custom outputs, tags, VPC configuration, and stack info saving.
+   */
+  stackConfig?: StackConfig;
+  /**
+   * #### Your app's infrastructure: APIs, databases, containers, functions, buckets, and more.
+   *
+   * ---
+   *
+   * Each entry is a named resource (e.g., `myApi`, `myDatabase`). Stacktape creates and manages
+   * the underlying AWS resources for you. Use `stacktape stack-info --detailed` to inspect them.
+   */
+  resources: { [resourceName: string]: StacktapeResourceDefinition };
+  /**
+   * #### Escape hatch: add raw AWS CloudFormation resources alongside Stacktape-managed ones.
+   *
+   * ---
+   *
+   * For advanced use cases where Stacktape doesn't have a built-in resource type.
+   * These are merged into the CloudFormation template as-is. Use `stacktape stack-info --detailed`
+   * to check existing logical names and avoid conflicts.
+   *
+   * Does not count towards your resource limit.
+   */
+  cloudformationResources?: { [resourceName: string]: CloudformationResource };
+}
+```