stacktape 3.5.8 → 3.6.0-beta.0

package/ai-docs/config-ref/web-app-firewall.md

@@ -0,0 +1,212 @@
+---
+docType: config-ref
+title: Web App Firewall
+resourceType: web-app-firewall
+tags:
+  - web-app-firewall
+  - waf
+  - firewall
+source: types/stacktape-config/web-app-firewall.d.ts
+priority: 1
+---
+
+# Web App Firewall
+
+Protects your APIs and websites from common attacks (SQL injection, XSS, bots, DDoS).
+
+Attach to an HTTP API Gateway, Application Load Balancer, or CDN. Comes with AWS-managed rule sets
+by default. Costs ~$5/month base + $1/million requests inspected.
+
+Resource type: `web-app-firewall`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Protects your APIs and websites from common attacks (SQL injection, XSS, bots, DDoS).
+ *
+ * ---
+ *
+ * Attach to an HTTP API Gateway, Application Load Balancer, or CDN. Comes with AWS-managed rule sets
+ * by default. Costs ~$5/month base + $1/million requests inspected.
+ */
+interface WebAppFirewall {
+  type: 'web-app-firewall';
+  properties?: WebAppFirewallProps;
+  overrides?: ResourceOverrides;
+}
+
+interface WebAppFirewallProps {
+  /**
+   * #### `cdn` for CloudFront-attached resources, `regional` for ALBs, User Pools, or direct API Gateways.
+   */
+  scope: 'regional' | 'cdn';
+  /**
+   * #### What happens when no rule matches a request.
+   *
+   * ---
+   *
+   * - **`Allow`** (recommended): Allow all traffic, block only what rules catch.
+   * - **`Block`**: Block all traffic, allow only what rules explicitly permit (returns 403).
+   *
+   * @default Allow
+   */
+  defaultAction?: 'Allow' | 'Block';
+  /**
+   * #### Firewall rules: managed rule groups (AWS presets), custom rule groups, or rate-based rules.
+   *
+   * ---
+   *
+   * If omitted, Stacktape uses `AWSManagedRulesCommonRuleSet` + `AWSManagedRulesKnownBadInputsRuleSet` by default.
+   */
+  rules?: (ManagedRuleGroup | CustomRuleGroup | RateBasedStatement)[];
+  /**
+   * #### Custom response bodies for `Block` actions. Map of key → content type + body.
+   */
+  customResponseBodies?: CustomResponseBodies;
+  /**
+   * #### Seconds a solved CAPTCHA stays valid before requiring re-verification.
+   * @default 300
+   */
+  captchaImmunityTime?: number;
+  /**
+   * #### Seconds a solved challenge stays valid before requiring re-verification.
+   * @default 300
+   */
+  challengeImmunityTime?: number;
+  /**
+   * #### Domains accepted in WAF tokens. Enables token sharing across multiple protected websites.
+   */
+  tokenDomains?: string[];
+  /**
+   * #### Disable CloudWatch metrics for the firewall.
+   * @default false
+   */
+  disableMetrics?: boolean;
+  /**
+   * #### Save samples of matched requests for inspection in the AWS WAF console.
+   * @default false
+   */
+  sampledRequestsEnabled?: boolean;
+}
+
+interface CommonRuleProps {
+  /**
+   * #### Evaluation order. Lower = evaluated first. Must be unique across all rules.
+   */
+  priority: number;
+  /*
+   * #### The name of the rule.
+   *
+   * ---
+   *
+   * - For a `managed-rule-group`, this is the name of the rule group used along with the `vendorName`.
+   * - For other rule types, this is an arbitrary value used to identify the rule.
+   */
+  name: string;
+  /**
+   * #### Disable CloudWatch metrics for this rule.
+   * @default false
+   */
+  disableMetrics?: boolean;
+  /**
+   * #### Save samples of requests matching this rule for inspection in the WAF console.
+   * @default false
+   */
+  sampledRequestsEnabled?: boolean;
+}
+
+interface ManagedRuleGroup {
+  type: 'managed-rule-group';
+  properties: ManagedRuleGroupProps;
+}
+
+interface ManagedRuleGroupProps extends CommonRuleProps {
+  /**
+   * #### Vendor name (e.g., `AWS` for AWS-managed rules).
+   */
+  vendorName: string;
+  /**
+   * #### Rules within this group to skip (by rule name). Useful for disabling false positives.
+   */
+  excludedRules?: string[];
+  /**
+   * #### `None` = apply normally, `Count` = log matches without blocking (dry-run mode).
+   */
+  overrideAction?: 'None' | 'Count';
+}
+
+interface CustomRuleGroup {
+  type: 'custom-rule-group';
+  properties: CustomRuleGroupProps;
+}
+
+interface CustomRuleGroupProps extends CommonRuleProps {
+  /**
+   * #### ARN of the custom WAF rule group.
+   */
+  arn: string;
+  /**
+   * #### `None` = apply normally, `Count` = log matches without blocking (dry-run mode).
+   */
+  overrideAction?: 'None' | 'Count';
+}
+
+interface RateBasedStatement {
+  type: 'rate-based-rule';
+  properties: RateBasedStatementProps;
+}
+
+interface RateBasedStatementProps extends CommonRuleProps {
+  /**
+   * #### Max requests per IP in a 5-minute window. Range: 100–20,000,000. Exceeding triggers the `action`.
+   */
+  limit: number;
+  /**
+   * #### `IP` = direct client IP, `FORWARDED_IP` = IP from a header (e.g., `X-Forwarded-For` behind a proxy).
+   */
+  aggregateBasedOn?: 'IP' | 'FORWARDED_IP';
+  /**
+   * #### Header and fallback settings when using `FORWARDED_IP` aggregation.
+   */
+  forwardedIPConfig?: ForwardedIPConfig;
+  /**
+   * #### What to do when the rate limit is exceeded.
+   *
+   * ---
+   *
+   * - `Block`: Return 403 (most common for rate limiting).
+   * - `Count`: Log only, don't block (useful for testing thresholds).
+   * - `Captcha`/`Challenge`: Verify the client is human.
+   *
+   * @default Block
+   */
+  action?: 'Allow' | 'Block' | 'Count' | 'Captcha' | 'Challenge';
+}
+
+interface ForwardedIPConfig {
+  /**
+   * #### What to do when the header is missing. `MATCH` = apply rule action, `NO_MATCH` = skip.
+   */
+  fallbackBehavior: 'MATCH' | 'NO_MATCH';
+  /**
+   * #### HTTP header containing the client IP (e.g., `X-Forwarded-For`).
+   */
+  headerName: string;
+}
+
+interface CustomResponseBodies {
+  [key: string]: {
+    /**
+     * #### MIME type: `application/json`, `text/plain`, or `text/html`.
+     */
+    contentType: string;
+    /**
+     * #### Response body content.
+     */
+    content: string;
+  };
+}
+
+type WebAppFirewallReferencableParams = 'arn' | 'scope';
+```

package/ai-docs/config-ref/web-service.md

@@ -0,0 +1,178 @@
+---
+docType: config-ref
+title: Web Service
+resourceType: web-service
+tags:
+  - web-service
+  - container
+  - docker
+  - ecs
+  - fargate
+  - http-service
+source: types/stacktape-config/web-services.d.ts
+priority: 1
+---
+
+# Web Service
+
+A container running 24/7 with a public HTTPS URL.
+
+Use for APIs, web apps, and any service that needs to be always-on and reachable from the internet.
+Includes TLS/SSL, auto-scaling, health checks, and zero-downtime deployments.
+
+Resource type: `web-service`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### A container running 24/7 with a public HTTPS URL.
+ *
+ * ---
+ *
+ * Use for APIs, web apps, and any service that needs to be always-on and reachable from the internet.
+ * Includes TLS/SSL, auto-scaling, health checks, and zero-downtime deployments.
+ */
+interface WebService {
+  type: 'web-service';
+  properties: WebServiceProps;
+  overrides?: ResourceOverrides;
+}
+
+interface WebServiceProps extends SimpleServiceContainer {
+  /**
+   * #### CORS settings. Overrides any CORS headers from your application.
+   *
+   * ---
+   *
+   * Only works with `http-api-gateway` load balancing (the default).
+   */
+  cors?: HttpApiCorsConfig;
+  /**
+   * #### Custom domains (e.g., `api.example.com`). Stacktape auto-creates DNS records and TLS certificates.
+   *
+   * ---
+   *
+   * Your domain must be added as a Route53 hosted zone in your AWS account first.
+   */
+  customDomains?: DomainConfiguration[];
+  /**
+   * #### How traffic reaches your containers. Affects pricing, features, and protocol support.
+   *
+   * ---
+   *
+   * - **`http-api-gateway`** (default): Pay-per-request (~$1/million requests). Best for most apps.
+   *   Cheapest at low traffic, but costs grow with volume.
+   *
+   * - **`application-load-balancer`**: Flat ~$18/month + usage. Required for gradual deployments
+   *   (`deployment`), firewalls (`useFirewall`), and WebSocket support.
+   *   More cost-effective above ~500k requests/day. AWS Free Tier eligible.
+   *
+   * - **`network-load-balancer`**: For non-HTTP traffic (TCP/TLS) like MQTT, game servers, or custom protocols.
+   *   Requires explicit `ports` configuration. Does not support CDN, firewall, or gradual deployments.
+   */
+  loadBalancing?: WebServiceHttpApiGatewayLoadBalancing | WebServiceAlbLoadBalancing | WebServiceNlbLoadBalancing;
+  /**
+   * #### Put a CDN (CloudFront) in front of this service for caching and lower latency worldwide.
+   */
+  cdn?: CdnConfiguration;
+  /**
+   * #### Alarms for this service (merged with global alarms from the Stacktape Console).
+   */
+  alarms?: (HttpApiGatewayAlarm | ApplicationLoadBalancerAlarm)[];
+  /**
+   * #### Global alarm names to exclude from this service.
+   */
+  disabledGlobalAlarms?: string[];
+  /**
+   * #### Gradual traffic shifting for safe deployments (canary, linear, or all-at-once).
+   *
+   * ---
+   *
+   * Requires `loadBalancing` type `application-load-balancer`.
+   */
+  deployment?: ContainerWorkloadDeploymentConfig;
+  /**
+   * #### Name of a `web-app-firewall` resource to protect this service from common web exploits.
+   */
+  useFirewall?: string;
+}
+
+type WebServiceReferencableParam = HttpApiGatewayReferencableParam | ContainerWorkloadReferencableParam;
+
+interface WebServiceHttpApiGatewayLoadBalancing {
+  type: HttpApiGateway['type'];
+}
+
+interface WebServiceAlbLoadBalancing {
+  type: ApplicationLoadBalancer['type'];
+  properties?: WebServiceAlbLoadBalancingProps;
+}
+
+interface WebServiceAlbLoadBalancingProps {
+  /**
+   * #### Path the load balancer pings to check container health.
+   * @default /
+   */
+  healthcheckPath?: string;
+  /**
+   * #### Seconds between health checks.
+   * @default 5
+   */
+  healthcheckInterval?: number;
+  /**
+   * #### Seconds before a health check is considered failed.
+   * @default 4
+   */
+  healthcheckTimeout?: number;
+}
+
+interface WebServiceNlbLoadBalancing {
+  type: NetworkLoadBalancer['type'];
+  properties: WebServiceNlbLoadBalancingProps;
+}
+
+interface WebServiceNlbLoadBalancingProps {
+  /**
+   * #### Health check path (only used when `healthCheckProtocol` is `HTTP`).
+   * @default /
+   */
+  healthcheckPath?: string;
+  /**
+   * #### Seconds between health checks (5-300).
+   * @default 5
+   */
+  healthcheckInterval?: number;
+  /**
+   * #### Seconds before a health check is considered failed (2-120).
+   * @default 4
+   */
+  healthcheckTimeout?: number;
+  /**
+   * #### Health check protocol: `TCP` (port check) or `HTTP` (path check).
+   * @default TCP
+   */
+  healthCheckProtocol?: 'HTTP' | 'TCP';
+  /**
+   * #### Health check port. Defaults to the traffic port.
+   */
+  healthCheckPort?: number;
+  ports: WebServiceNlbLoadBalancingPort[];
+}
+
+interface WebServiceNlbLoadBalancingPort {
+  /**
+   * #### Public port exposed by the load balancer.
+   */
+  port: number;
+  /**
+   * #### Protocol: `TLS` (encrypted) or `TCP` (raw).
+   * @default TLS
+   */
+  protocol?: 'TCP' | 'TLS';
+  /**
+   * #### Port on the container that receives the traffic. Defaults to `port`.
+   */
+  containerPort?: number;
+}
+```

package/ai-docs/config-ref/worker-service.md

@@ -0,0 +1,41 @@
+---
+docType: config-ref
+title: Worker Service
+resourceType: worker-service
+tags:
+  - worker-service
+  - background
+  - worker
+  - async-worker
+source: types/stacktape-config/worker-services.d.ts
+priority: 1
+---
+
+# Worker Service
+
+Always-on container with no public URL. For background workers, queue processors, and internal tasks.
+
+Runs 24/7 inside your VPC. Not reachable from the internet. Can connect to databases, queues, and other resources.
+
+Resource type: `worker-service`
+
+## TypeScript Definition
+
+```typescript
+/**
+ * #### Always-on container with no public URL. For background workers, queue processors, and internal tasks.
+ *
+ * ---
+ *
+ * Runs 24/7 inside your VPC. Not reachable from the internet. Can connect to databases, queues, and other resources.
+ */
+interface WorkerService {
+  type: 'worker-service';
+  properties: WorkerServiceProps;
+  overrides?: ResourceOverrides;
+}
+
+interface WorkerServiceProps extends SimpleServiceContainer {}
+
+type WorkerServiceReferencableParams = ContainerWorkloadReferencableParam;
+```

package/ai-docs/getting-started/console.md

@@ -0,0 +1,232 @@
+---
+docType: getting-started
+title: Console
+tags:
+  - console
+  - getting-started
+source: docs/_curated-docs/getting-started/console.mdx
+priority: 2
+---
+
+# Console
+
+The Stacktape Console is a web-based interface for managing your infrastructure. It complements the CLI with visual tools for deployments, monitoring, and team collaboration.
+
+**URL:** [console.stacktape.com](https://console.stacktape.com)
+
+## Key Features
+
+### GitOps Deployments
+
+Connect your GitHub, GitLab, or Bitbucket repository and deploy automatically:
+
+- **Push-to-deploy**: Automatically deploy when you push to a branch
+- **Preview environments**: Create temporary environments for pull requests
+- **PR comments**: Deployment status and links posted directly to your PRs
+
+`[IMAGE PLACEHOLDER: console-gitops-setup]`
+
+### Live Deployment Logs
+
+Watch your deployments in real-time with streaming logs from AWS CodeBuild or EC2 runners.
+
+`[IMAGE PLACEHOLDER: console-deployment-logs]`
+
+### Logs Browser
+
+Browse and search CloudWatch logs with an intuitive interface:
+
+- Filter by time range
+- Search with patterns
+- Live tail for real-time debugging
+
+`[IMAGE PLACEHOLDER: console-logs-browser]`
+
+### Metrics Dashboard
+
+Visualize metrics for all your resources:
+
+- Lambda invocations, duration, errors
+- ECS CPU and memory utilization
+- RDS connections, IOPS, latency
+- API Gateway requests and latency
+- And more...
+
+`[IMAGE PLACEHOLDER: console-metrics-dashboard]`
+
+### Cost Management
+
+Track AWS spending across all your stacks:
+
+- Per-stack cost breakdown
+- Monthly trends and comparisons
+- Service-level cost attribution
+- Multi-account aggregation
+
+`[IMAGE PLACEHOLDER: console-costs-page]`
+
+### S3 File Browser
+
+Browse, upload, and manage files in your S3 buckets directly from the console:
+
+- Folder navigation
+- File upload and download
+- In-browser text editor
+- Delete operations
+
+`[IMAGE PLACEHOLDER: console-s3-browser]`
+
+### Remote Sessions
+
+Open a terminal inside your running containers without SSH keys:
+
+- Secure SSM-based connections
+- No port exposure required
+- Works with private containers
+
+`[IMAGE PLACEHOLDER: console-remote-session]`
+
+### Secrets Management
+
+Create and manage secrets stored in AWS Secrets Manager:
+
+- Create, view, and delete secrets
+- Works across all connected AWS accounts
+- Reference secrets in your configurations with `$Secret('name')`
+
+`[IMAGE PLACEHOLDER: console-secrets-manager]`
+
+### Monitoring & Alarms
+
+Set up alerts for your infrastructure:
+
+- Lambda error rate thresholds
+- Database CPU and storage alerts
+- API latency warnings
+- Notifications via Slack, Teams, or email
+
+## Getting Started with the Console
+
+### Step 1: Create an Account
+
+Visit [console.stacktape.com](https://console.stacktape.com) and sign up with:
+
+- Email and password
+- GitHub OAuth
+- Google OAuth
+
+### Step 2: Connect Your AWS Account
+
+The console needs access to your AWS account to deploy and manage resources.
+
+1. Go to **Settings** → **AWS Accounts**
+2. Click **Connect AWS Account**
+3. You'll be redirected to AWS to create a CloudFormation stack
+4. This stack creates:
+   - An IAM role for Stacktape to assume
+   - An S3 bucket for cost reports
+5. Wait about 1 minute for the stack to complete
+6. Your account shows as "Active"
+
+`[IMAGE PLACEHOLDER: console-aws-account-connection]`
+
+### Step 3: Create Your First Project
+
+1. Click **New Project**
+2. Choose your deployment source:
+   - **From Git repository**: Connect to GitHub, GitLab, or Bitbucket
+   - **From template**: Start with a pre-built example
+3. Configure your project settings:
+   - Project name
+   - Default stage and region
+   - Build settings
+
+### Step 4: Deploy
+
+For Git-connected projects:
+
+1. Push code to your repository
+2. The console automatically detects changes
+3. Watch the deployment progress in real-time
+
+Or trigger a manual deployment from the console.
+
+## Console vs CLI
+
+Both tools deploy to the same infrastructure. Choose based on your workflow:
+
+| Feature                   | CLI                | Console     |
+| ------------------------- | ------------------ | ----------- |
+| Local development         | ✅                 | ❌          |
+| GitOps/CI-CD              | Via GitHub Actions | ✅ Built-in |
+| Log browsing              | Basic              | ✅ Advanced |
+| Metrics visualization     | ❌                 | ✅          |
+| Cost tracking             | ❌                 | ✅          |
+| Team collaboration        | ❌                 | ✅          |
+| S3 file management        | ❌                 | ✅          |
+| Remote container sessions | ✅                 | ✅          |
+
+**Typical workflow:**
+
+- Use the **CLI** for local development and quick iterations
+- Use the **Console** for production deployments, monitoring, and team collaboration
+
+## Pricing
+
+The Stacktape CLI is **free and open source**. The Console has the following tiers:
+
+| Feature              | Free      | Flexible  | Enterprise                   |
+| -------------------- | --------- | --------- | ---------------------------- |
+| CLI deployments      | ✅        | ✅        | ✅                           |
+| Console deployments  | Limited   | ✅        | ✅                           |
+| GitOps               | ❌        | ✅        | ✅                           |
+| Preview environments | ❌        | ✅        | ✅                           |
+| Logs browser         | Limited   | ✅        | ✅                           |
+| Metrics              | Limited   | ✅        | ✅                           |
+| Cost tracking        | ❌        | ✅        | ✅                           |
+| Team members         | 1         | Unlimited | Unlimited                    |
+| Support              | Community | Standard  | Premium (8-min avg response) |
+
+See [stacktape.com/pricing](https://stacktape.com/pricing) for current pricing.
+
+## Team Collaboration
+
+### Invite Team Members
+
+1. Go to **Settings** → **Team**
+2. Click **Invite Member**
+3. Enter their email address
+4. Choose a role:
+   - **Owner**: Full access, billing management
+   - **Admin**: Full access, no billing
+   - **Member**: Deploy and view access
+
+### Multi-Factor Authentication
+
+Enable MFA for additional security:
+
+1. Go to your profile settings
+2. Enable MFA
+3. Choose TOTP (authenticator app) or SMS
+
+## API Keys
+
+Generate API keys for programmatic access:
+
+```bash
+# Set your API key for CLI authentication
+stacktape login --apiKey YOUR_API_KEY
+```
+
+Or use in CI/CD environments:
+
+```bash
+export STACKTAPE_API_KEY=your-api-key
+stacktape deploy --stage production --region us-east-1
+```
+
+## Next steps
+
+- [Intro](/getting-started/intro) - Get started with Stacktape
+- [Workflow](/getting-started/workflow) - Understand the development workflow
+- [Dev Mode](/getting-started/dev-mode) - Local development