stacktape 3.5.8 → 3.6.0

package/ai-docs/recipe/monorepo-setup.md

@@ -0,0 +1,183 @@
+---
+docType: recipe
+title: Monorepo Setup
+tags:
+  - monorepo
+  - setup
+  - recipe
+source: docs/_curated-docs/recipes/monorepo-setup.mdx
+priority: 1
+---
+
+# Monorepo Setup
+
+Deploy multiple services from a single repository.
+
+## Project Structure
+
+## Shared Infrastructure Stack
+
+```typescript
+// packages/infra/stacktape.ts
+import { defineConfig, RelationalDatabase, RdsEnginePostgres, $Secret } from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({ version: '16' }),
+    credentials: {
+      masterUserPassword: $Secret(`db-password-${stage}`)
+    }
+  });
+
+  return {
+    resources: { database }
+  };
+});
+```
+
+## API Service Stack
+
+```typescript
+// packages/api/stacktape.ts
+import { defineConfig, LambdaFunction, HttpApiGateway, $CfStackOutput } from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const api = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/handler.ts'
+      }
+    },
+    environment: {
+      // Reference the shared database from infra stack
+      DATABASE_URL: $CfStackOutput(`infra-${stage}`, 'database', 'connectionString')
+    }
+  });
+
+  const gateway = new HttpApiGateway({
+    routes: [{ path: '/{proxy+}', method: '*', integration: { type: 'function', properties: { function: api } } }]
+  });
+
+  return {
+    resources: { api, gateway }
+  };
+});
+```
+
+## Web Service Stack
+
+```typescript
+// packages/web/stacktape.ts
+import { defineConfig, NextjsWeb, $CfStackOutput } from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const website = new NextjsWeb({
+    appDirectory: './',
+    environment: [
+      {
+        name: 'NEXT_PUBLIC_API_URL',
+        value: $CfStackOutput(`api-${stage}`, 'gateway', 'url')
+      }
+    ]
+  });
+
+  return {
+    resources: { website }
+  };
+});
+```
+
+## Deployment Scripts
+
+```json
+// package.json (root)
+{
+  "scripts": {
+    "deploy:infra": "cd packages/infra && stacktape deploy",
+    "deploy:api": "cd packages/api && stacktape deploy",
+    "deploy:web": "cd packages/web && stacktape deploy",
+    "deploy:all": "npm run deploy:infra && npm run deploy:api && npm run deploy:web"
+  }
+}
+```
+
+## Deploy Order
+
+Infrastructure must be deployed first since other stacks reference it:
+
+```bash
+# 1. Deploy shared infrastructure
+cd packages/infra
+stacktape deploy --stage dev --region us-east-1
+
+# 2. Deploy API (references infra)
+cd packages/api
+stacktape deploy --stage dev --region us-east-1
+
+# 3. Deploy Web (references API)
+cd packages/web
+stacktape deploy --stage dev --region us-east-1
+```
+
+## CI/CD with GitHub Actions
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v1
+
+      - run: bun install
+
+      # Deploy in order
+      - name: Deploy Infrastructure
+        run: |
+          cd packages/infra
+          stacktape deploy --stage production --region us-east-1 --autoConfirmOperation
+        env:
+          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}
+
+      - name: Deploy API
+        run: |
+          cd packages/api
+          stacktape deploy --stage production --region us-east-1 --autoConfirmOperation
+        env:
+          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}
+
+      - name: Deploy Web
+        run: |
+          cd packages/web
+          stacktape deploy --stage production --region us-east-1 --autoConfirmOperation
+        env:
+          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}
+```
+
+## With Turborepo
+
+```json
+// turbo.json
+{
+  "pipeline": {
+    "deploy": {
+      "dependsOn": ["^deploy"],
+      "cache": false
+    }
+  }
+}
+```
+
+```bash
+# Deploy all in dependency order
+turbo run deploy
+```

package/ai-docs/recipe/nextjs-full-stack.md

@@ -0,0 +1,188 @@
+---
+docType: recipe
+title: Next.js Full-Stack
+tags:
+  - next.js
+  - full-stack
+  - recipe
+source: docs/_curated-docs/recipes/nextjs-full-stack.mdx
+priority: 1
+---
+
+# Next.js Full-Stack Application
+
+A complete Next.js application with database, authentication, and file uploads.
+
+## Configuration
+
+```typescript
+import {
+  defineConfig,
+  NextjsWeb,
+  RelationalDatabase,
+  RdsEnginePostgres,
+  UserAuthPool,
+  Bucket,
+  $Secret,
+  $ResourceParam
+} from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const isProduction = stage === 'production';
+
+  // PostgreSQL database
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({
+      version: '16',
+      primaryInstance: {
+        instanceSize: isProduction ? 'db.t4g.small' : 'db.t4g.micro'
+      }
+    }),
+    credentials: {
+      masterUserPassword: $Secret(`db-password-${stage}`)
+    }
+  });
+
+  // User authentication
+  const auth = new UserAuthPool({
+    passwordPolicy: {
+      minimumLength: 8,
+      requireNumbers: true
+    }
+  });
+
+  // File uploads bucket
+  const uploads = new Bucket({
+    directoryUpload: {
+      directoryPath: './public/uploads'
+    }
+  });
+
+  // Next.js application
+  const website = new NextjsWeb({
+    appDirectory: './',
+    connectTo: [database, auth, uploads],
+    serverLambda: {
+      joinDefaultVpc: true, // Required for database access
+      memory: 1024
+    },
+    customDomains: isProduction ? [{ domainName: 'myapp.com' }, { domainName: 'www.myapp.com' }] : [],
+    environment: [
+      { name: 'NEXTAUTH_SECRET', value: $Secret('nextauth-secret') },
+      { name: 'NEXTAUTH_URL', value: isProduction ? 'https://myapp.com' : `https://${stage}.myapp.com` }
+    ]
+  });
+
+  return {
+    hooks: {
+      afterDeploy: [{ scriptName: 'migrate' }]
+    },
+    scripts: {
+      migrate: {
+        executeCommand: 'npx prisma migrate deploy',
+        environment: {
+          DATABASE_URL: $ResourceParam('database', 'connectionString')
+        }
+      }
+    },
+    resources: { database, auth, uploads, website }
+  };
+});
+```
+
+## Project Structure
+
+## Database Access
+
+```typescript
+// lib/db.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = global as unknown as { prisma: PrismaClient };
+
+export const prisma = globalForPrisma.prisma || new PrismaClient();
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+```
+
+```typescript
+// app/api/users/route.ts
+import { prisma } from '@/lib/db';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const users = await prisma.user.findMany();
+  return NextResponse.json(users);
+}
+```
+
+## Authentication
+
+```typescript
+// app/api/auth/[...nextauth]/route.ts
+import NextAuth from 'next-auth';
+import CognitoProvider from 'next-auth/providers/cognito';
+
+const handler = NextAuth({
+  providers: [
+    CognitoProvider({
+      clientId: process.env.STP_AUTH_USER_POOL_CLIENT_ID!,
+      clientSecret: process.env.STP_AUTH_USER_POOL_CLIENT_SECRET!,
+      issuer: process.env.STP_AUTH_USER_POOL_ISSUER_URL!
+    })
+  ]
+});
+
+export { handler as GET, handler as POST };
+```
+
+## File Uploads
+
+```typescript
+// app/api/upload/route.ts
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { NextResponse } from 'next/server';
+
+const s3 = new S3Client({});
+
+export async function POST(request: Request) {
+  const formData = await request.formData();
+  const file = formData.get('file') as File;
+
+  const buffer = Buffer.from(await file.arrayBuffer());
+  const key = `uploads/${Date.now()}-${file.name}`;
+
+  await s3.send(
+    new PutObjectCommand({
+      Bucket: process.env.STP_UPLOADS_BUCKET_NAME,
+      Key: key,
+      Body: buffer,
+      ContentType: file.type
+    })
+  );
+
+  return NextResponse.json({ key });
+}
+```
+
+## Development
+
+```bash
+# Start dev mode
+stacktape dev --stage dev --region us-east-1
+
+# Opens: http://localhost:3000
+# Database emulated locally
+# Auth pool connected to AWS
+```
+
+## Deploy
+
+```bash
+# Create secrets
+stacktape secret:create --region us-east-1  # db-password-dev
+stacktape secret:create --region us-east-1  # nextauth-secret
+
+# Deploy
+stacktape deploy --stage dev --region us-east-1
+```

package/ai-docs/recipe/rest-api-with-database.md

@@ -0,0 +1,156 @@
+---
+docType: recipe
+title: REST API + Database
+tags:
+  - rest
+  - api
+  - database
+  - recipe
+source: docs/_curated-docs/recipes/rest-api-with-database.mdx
+priority: 1
+---
+
+# REST API with PostgreSQL
+
+A complete REST API using Lambda functions connected to a PostgreSQL database.
+
+## Final Configuration
+
+```typescript
+import {
+  defineConfig,
+  LambdaFunction,
+  RelationalDatabase,
+  RdsEnginePostgres,
+  HttpApiGateway,
+  $Secret
+} from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const isProduction = stage === 'production';
+
+  // PostgreSQL database
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({
+      version: '16',
+      primaryInstance: {
+        instanceSize: isProduction ? 'db.t4g.small' : 'db.t4g.micro'
+      }
+    }),
+    credentials: {
+      masterUserPassword: $Secret(`db-password-${stage}`)
+    }
+  });
+
+  // API handler
+  const api = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/handler.ts'
+      }
+    },
+    connectTo: [database],
+    environment: {
+      NODE_ENV: isProduction ? 'production' : 'development'
+    }
+  });
+
+  // HTTP Gateway
+  const gateway = new HttpApiGateway({
+    routes: [{ path: '/{proxy+}', method: '*', integration: { type: 'function', properties: { function: api } } }]
+  });
+
+  return {
+    resources: { database, api, gateway }
+  };
+});
+```
+
+## Project Structure
+
+## Handler Code
+
+```typescript
+// src/handler.ts
+import { APIGatewayProxyHandlerV2 } from 'aws-lambda';
+import { Pool } from 'pg';
+
+// Connection pool (reused across invocations)
+const pool = new Pool({
+  connectionString: process.env.STP_DATABASE_CONNECTION_STRING
+});
+
+export const handler: APIGatewayProxyHandlerV2 = async (event) => {
+  const { httpMethod, path } = event.requestContext.http;
+
+  if (path === '/users' && httpMethod === 'GET') {
+    const result = await pool.query('SELECT * FROM users LIMIT 100');
+    return {
+      statusCode: 200,
+      body: JSON.stringify(result.rows)
+    };
+  }
+
+  if (path === '/users' && httpMethod === 'POST') {
+    const body = JSON.parse(event.body || '{}');
+    const result = await pool.query('INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *', [
+      body.name,
+      body.email
+    ]);
+    return {
+      statusCode: 201,
+      body: JSON.stringify(result.rows[0])
+    };
+  }
+
+  return { statusCode: 404, body: 'Not found' };
+};
+```
+
+## Adding Migrations
+
+Run database migrations on every deployment:
+
+```typescript
+export default defineConfig(({ stage }) => {
+  // ... resources ...
+
+  return {
+    hooks: {
+      afterDeploy: [{ scriptName: 'migrate' }]
+    },
+    scripts: {
+      migrate: {
+        executeCommand: 'npx prisma migrate deploy',
+        environment: {
+          DATABASE_URL: $ResourceParam('database', 'connectionString')
+        }
+      }
+    },
+    resources: { database, api, gateway }
+  };
+});
+```
+
+## Development
+
+```bash
+# Start local development
+stacktape dev --stage dev --region us-east-1
+
+# Database runs locally in Docker
+# API runs locally with hot-reload
+# Requests tunnel through AWS
+```
+
+## Deploy
+
+```bash
+# Create the database password secret first
+stacktape secret:create --region us-east-1
+# name: db-password-dev
+
+# Deploy
+stacktape deploy --stage dev --region us-east-1
+```

package/ai-docs/recipe/scheduled-tasks.md

@@ -0,0 +1,186 @@
+---
+docType: recipe
+title: Scheduled Tasks
+tags:
+  - scheduled
+  - tasks
+  - recipe
+source: docs/_curated-docs/recipes/scheduled-tasks.mdx
+priority: 1
+---
+
+# Scheduled Tasks (Cron Jobs)
+
+Run Lambda functions on a schedule using CloudWatch Events.
+
+## Configuration
+
+```typescript
+import { defineConfig, LambdaFunction, RelationalDatabase, RdsEnginePostgres, $Secret } from 'stacktape';
+
+export default defineConfig(() => {
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({ version: '16' }),
+    credentials: {
+      masterUserPassword: $Secret('db-password')
+    }
+  });
+
+  // Daily cleanup job - runs at 3 AM UTC
+  const dailyCleanup = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/jobs/cleanup.ts'
+      }
+    },
+    timeout: 900, // 15 minutes
+    connectTo: [database],
+    events: [
+      {
+        type: 'schedule',
+        properties: {
+          scheduleRate: 'cron(0 3 * * ? *)' // 3 AM UTC daily
+        }
+      }
+    ]
+  });
+
+  // Hourly metrics job
+  const hourlyMetrics = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/jobs/metrics.ts'
+      }
+    },
+    timeout: 300,
+    connectTo: [database],
+    events: [
+      {
+        type: 'schedule',
+        properties: {
+          scheduleRate: 'rate(1 hour)'
+        }
+      }
+    ]
+  });
+
+  // Weekly report - runs every Monday at 9 AM UTC
+  const weeklyReport = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/jobs/weekly-report.ts'
+      }
+    },
+    timeout: 900,
+    connectTo: [database],
+    events: [
+      {
+        type: 'schedule',
+        properties: {
+          scheduleRate: 'cron(0 9 ? * MON *)' // Monday 9 AM UTC
+        }
+      }
+    ]
+  });
+
+  return {
+    resources: { database, dailyCleanup, hourlyMetrics, weeklyReport }
+  };
+});
+```
+
+## Schedule Expressions
+
+### Rate Expressions
+
+```
+rate(1 minute)
+rate(5 minutes)
+rate(1 hour)
+rate(12 hours)
+rate(1 day)
+rate(7 days)
+```
+
+### Cron Expressions
+
+Format: `cron(minutes hours day-of-month month day-of-week year)`
+
+```
+cron(0 3 * * ? *)       # 3:00 AM UTC every day
+cron(0 */2 * * ? *)     # Every 2 hours
+cron(0 9 ? * MON *)     # 9 AM every Monday
+cron(0 0 1 * ? *)       # Midnight on the 1st of each month
+cron(0 12 ? * MON-FRI *)# Noon on weekdays
+```
+
+## Job Handler
+
+```typescript
+// src/jobs/cleanup.ts
+import { ScheduledHandler } from 'aws-lambda';
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  connectionString: process.env.STP_DATABASE_CONNECTION_STRING
+});
+
+export const handler: ScheduledHandler = async (event) => {
+  console.log('Starting cleanup job', event);
+
+  // Delete old sessions
+  const sessionsResult = await pool.query("DELETE FROM sessions WHERE expires_at < NOW() - INTERVAL '30 days'");
+  console.log(`Deleted ${sessionsResult.rowCount} expired sessions`);
+
+  // Delete old logs
+  const logsResult = await pool.query("DELETE FROM audit_logs WHERE created_at < NOW() - INTERVAL '90 days'");
+  console.log(`Deleted ${logsResult.rowCount} old audit logs`);
+
+  // Vacuum analyze for performance
+  await pool.query('VACUUM ANALYZE');
+
+  console.log('Cleanup complete');
+};
+```
+
+## Weekly Report Example
+
+```typescript
+// src/jobs/weekly-report.ts
+import { ScheduledHandler } from 'aws-lambda';
+import { SESClient, SendEmailCommand } from '@aws-sdk/client-ses';
+
+const ses = new SESClient({});
+
+export const handler: ScheduledHandler = async () => {
+  // Generate report data
+  const report = await generateWeeklyStats();
+
+  // Send email
+  await ses.send(
+    new SendEmailCommand({
+      Source: 'reports@myapp.com',
+      Destination: {
+        ToAddresses: ['team@myapp.com']
+      },
+      Message: {
+        Subject: { Data: `Weekly Report - ${new Date().toLocaleDateString()}` },
+        Body: {
+          Html: { Data: formatReportHtml(report) }
+        }
+      }
+    })
+  );
+};
+```
+
+## Monitoring
+
+View scheduled job logs:
+
+```bash
+stacktape logs --stage dev --region us-east-1 --resourceName dailyCleanup --startTime 24h
+```