stacks-cloud - SKILL.md Agent Skill

name: stacks-cloud description: Use when deploying or managing cloud infrastructure for Stacks — AWS deployment via CloudFormation/CDK, server mode (EC2, ALB, VPC), serverless mode (Lambda, API Gateway, CloudFront), jump boxes, domain management (Route53), S3 storage, SES email, edge computing, security groups, IAM, or the cloud configuration. Covers @stacksjs/cloud, @stacksjs/deploy, storage/framework/cloud/, and cloud/. license: MIT compatibility: Bun >= 1.3.0, TypeScript, AWS allowed-tools: Read Edit Write Bash Grep Glob

Stacks Cloud & Deployment

AWS-focused cloud deployment using CloudFormation via @stacksjs/ts-cloud.

Key Paths

Cloud package: storage/framework/core/cloud/src/
Deploy package: storage/framework/core/deploy/src/
CDK stacks: storage/framework/cloud/ (deploy.ts, cdk.json, package.json)
Cloud config: cloud/ (serverless.ts, servers.ts, deploy-script.ts)
TS Cloud config: .ts-cloud/
Configuration: config/cloud.ts

Deployment Modes

Server Mode (EC2)

EC2 instances with configurable types (t3.micro, t4g.nano, etc.)
Application Load Balancer (ALB)
VPC with public/private subnets
Security groups with firewall rules
Auto-scaling capabilities
SQLite database on instance
Docker support via Dockerfile

Serverless Mode (Lambda)

Lambda functions for API
API Gateway (REST/WebSocket)
CloudFront CDN for static assets
S3 buckets (frontend, docs, logs, assets)
SQS queues for background jobs
DynamoDB (optional)

Deployment Flow

buddy deploy                    # deploy to cloud

Validates APP_KEY format (colon-separated)
Checks AWS region and credentials
Validates app URL, name, team configuration
Creates InfrastructureGenerator from cloud config
Generates CloudFormation template
Creates or updates stack with:
- Capabilities: CAPABILITY_IAM, CAPABILITY_NAMED_IAM
- Tags: Environment, Project, ManagedBy
- OnFailure: ROLLBACK

Cloud Helper Functions

import { getSecurityGroupId, purchaseDomain, hasBeenDeployed, isFirstDeployment, isFailedState } from '@stacksjs/cloud'

// Domain management
await purchaseDomain('example.com', { years: 1, privacy: true, autoRenew: true })

// Infrastructure queries
const sgId = await getSecurityGroupId('my-sg')
const jumpBoxId = await getJumpBoxInstanceId('stack-name')
const deployed = await hasBeenDeployed()
const firstDeploy = await isFirstDeployment()
const failed = await isFailedState()

// Resource management
await addJumpBox('stack-name')
await deleteJumpBox('stack-name')
await deleteEc2Instance(instanceId, 'stack-name')

// Cleanup
await deleteStacksBuckets()
await deleteStacksFunctions()
await deleteLogGroups()
await deleteParameterStore()
await deleteVpcs()
await deleteCdkRemnants()
await deleteIamUsers()
await deleteSubnets()

DNS Functions (AWS Route53)

import { createHostedZone, deleteHostedZone, findHostedZone, getNameservers, updateNameservers } from '@stacksjs/cloud'

const zone = await createHostedZone('example.com')
const zoneId = await findHostedZone('example.com')
const ns = await getNameservers('example.com')
const hostedNs = await getHostedZoneNameservers('example.com')
await updateNameservers(hostedNs, 'example.com')
await deleteHostedZoneRecords('example.com')
await writeNameserversToConfig(nameservers)

Server Configuration (cloud/servers.ts)

export default [
  {
    name: 'app-server-1',
    domain: 'stacksjs.com',
    region: 'us-east-1',
    type: 'app',              // 'app' | 'web' | 'cache' | 'worker' | 'search'
    instance: 't3.micro',
    disk: 20,                  // GB
    os: 'ubuntu-20-lts-x86_64',
    bun: '1.1.26',
    database: { type: 'sqlite', name: 'stacks' }
  },
  // ... more servers
]

Deploy Hooks (cloud/deploy-script.ts)

export default {
  beforeDeploy({ environment, region }) {
    // Pre-deployment: build assets, validate, notify
  },
  afterDeploy({ environment, region, outputs }) {
    // Post-deployment: cache warming, smoke tests, database seeding
    console.log('Public IP:', outputs.PublicIp)
    console.log('DNS:', outputs.DNS)
  }
}

CLI Commands

buddy deploy                          # deploy application
buddy cloud --diff                    # show infrastructure changes
buddy cloud --ssh                     # SSH into cloud
buddy cloud --invalidate-cache        # invalidate CDN
buddy cloud:add --jump-box            # add jump box instance
buddy cloud:remove --force            # destroy cloud resources
buddy cloud:cleanup                   # clean retained resources
buddy cloud:optimize-cost             # remove optional resources
buddy domains:purchase <domain>       # purchase domain via Route53
buddy domains:add <domain>            # add existing domain
buddy domains:remove <domain>         # remove domain

config/cloud.ts

{
  project: { name: 'my-app', slug: 'my-app', region: 'us-east-1' },
  mode: 'server',             // 'server' | 'serverless'
  environments: {
    production: { domain: 'app.com', region: 'us-east-1' },
    staging: { domain: 'staging.app.com' }
  },
  infrastructure: {
    compute: { type: 't3.micro', spot: false },
    loadBalancer: { enabled: true, type: 'application' },
    ssl: { enabled: true },
    dns: { provider: 'route53' },
    storage: { buckets: [] },
    cdn: { enabled: true },
    cache: { enabled: false },
    queue: { enabled: false }
  }
}

Infrastructure Stack (storage/framework/cloud/)

deploy.ts — Main deployment script (CDK app entry)
cdk.json — CDK configuration with 54 AWS context settings
package.json — Cloud package dependencies

Stack naming: {slugified-app-name}-cloud

Gotchas

AWS credentials MUST be configured (buddy configure:aws or env vars)
Default region is us-east-1 (from AWS_DEFAULT_REGION env)
APP_KEY must be colon-separated format (validated during deployment)
Server mode uses EC2 + ALB; serverless uses Lambda + API Gateway + CloudFront
Jump boxes are optional — used for SSH access to private instances
cloud:remove with --force skips confirmation — destructive operation
CDK toolkit stack is named stacks-toolkit
Environment mapping: local → development, others preserved
Deploy hooks run before/after deployment for custom logic
The cloud package has its own package.json with framework dependencies