stacktape 3.5.8 → 3.6.0-beta.0

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

@@ -0,0 +1,157 @@
+---
+docType: getting-started
+title: Introduction
+tags:
+  - introduction
+  - getting-started
+source: docs/_curated-docs/getting-started/intro.mdx
+priority: 2
+---
+
+# Stacktape
+
+Stacktape is a cloud development framework that lets you deploy production-grade infrastructure to **your own AWS account** with minimal configuration. Think of it as PaaS-level simplicity with full AWS ownership.
+
+**What it does:**
+
+- Takes a ~30 line config and generates ~1,200+ lines of CloudFormation
+- Handles packaging, bundling, permissions, networking, and security
+- Deploys containers, serverless functions, databases, and 30+ AWS resource types
+- Provides a development mode for fast local iteration
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g stacktape
+```
+
+### 2. Login
+
+```bash
+stacktape login
+```
+
+### 3. Configure AWS credentials
+
+```bash
+stacktape aws-profile:create
+```
+
+### 4. Create your config
+
+Create `stacktape.ts`:
+
+```typescript
+import {
+  defineConfig,
+  LambdaFunction,
+  HttpApiGateway,
+  HttpApiIntegration,
+  DynamoDbTable,
+  StacktapeLambdaBuildpackPackaging
+} from 'stacktape';
+
+export default defineConfig(() => {
+  const db = new DynamoDbTable({
+    primaryKey: { partitionKey: { name: 'id', type: 'string' } }
+  });
+
+  const api = new HttpApiGateway({});
+
+  const handler = new LambdaFunction({
+    packaging: new StacktapeLambdaBuildpackPackaging({
+      entryfilePath: './src/handler.ts'
+    }),
+    connectTo: [db],
+    events: [
+      new HttpApiIntegration({
+        httpApiGatewayName: api.resourceName,
+        method: 'GET',
+        path: '/'
+      })
+    ]
+  });
+
+  return { resources: { api, handler, db } };
+});
+```
+
+Create `src/handler.ts`:
+
+```typescript
+export const handler = async () => ({
+  statusCode: 200,
+  body: JSON.stringify({ message: 'Hello from Stacktape!' })
+});
+```
+
+### 5. Deploy
+
+```bash
+stacktape deploy --stage dev --region us-east-1
+```
+
+Your API is now live on AWS.
+
+## What happens during deploy
+
+1. **Config parsing** - Resolves directives like `$Secret()` and validates the config
+2. **Code packaging** - Bundles Lambda functions with esbuild, builds Docker images
+3. **CloudFormation generation** - Transforms your config into AWS CloudFormation
+4. **Deployment** - Creates all resources in AWS in the correct dependency order
+
+## Core concepts
+
+**Stage** - An isolated environment (`dev`, `staging`, `production`). Each stage creates completely separate resources.
+
+**connectTo** - Automatically configures IAM permissions, injects environment variables, and sets up networking between resources.
+
+```typescript
+const handler = new LambdaFunction({
+  connectTo: [db] // Grants permissions, injects STP_DB_TABLE_NAME
+  // ...
+});
+```
+
+**Directives** - Special functions for dynamic values:
+
+- `$Secret('name')` - Reference AWS Secrets Manager
+- `$ResourceParam('resource', 'param')` - Get values from other resources
+- `$Stage()` - Current stage name
+
+## Config formats
+
+Stacktape supports TypeScript (recommended), YAML, and JSON configs.
+
+**TypeScript** - Full type safety, autocomplete, conditional logic:
+
+```typescript
+export default defineConfig(({ stage }) => ({
+  resources: {
+    db: new RelationalDatabase({
+      instanceSize: stage === 'prod' ? 'db.t4g.medium' : 'db.t4g.micro'
+    })
+  }
+}));
+```
+
+**YAML** - Simpler syntax, no build step:
+
+```yaml
+resources:
+  handler:
+    type: function
+    properties:
+      packaging:
+        type: stacktape-lambda-buildpack
+        properties:
+          entryfilePath: ./src/handler.ts
+```
+
+## Next steps
+
+- [Workflow](/getting-started/workflow) - Understand the development and deployment workflow
+- [Dev Mode](/getting-started/dev-mode) - Run locally with real cloud resources
+- [Using with AI](/getting-started/using-with-ai) - Let AI agents build your infrastructure

package/ai-docs/getting-started/using-with-ai.md

@@ -0,0 +1,228 @@
+---
+docType: getting-started
+title: Using with AI
+tags:
+  - using
+  - with
+  - getting-started
+source: docs/_curated-docs/getting-started/using-with-ai.mdx
+priority: 2
+---
+
+# Using with AI
+
+Stacktape's dev mode has an **agent mode** designed for AI coding assistants. It provides an HTTP API that lets AI agents start dev environments, trigger rebuilds, read logs, and even query databases - all programmatically.
+
+## The AI workflow
+
+When an AI agent builds infrastructure with Stacktape, the workflow looks like this:
+
+1. **Write config** - AI writes/edits `stacktape.ts` based on your requirements
+2. **Start dev mode** - AI starts agent mode to run the stack locally
+3. **Write application code** - AI implements your handlers, services, etc.
+4. **Test and iterate** - AI reads logs, triggers rebuilds, fixes errors
+5. **Deploy** - Once working locally, AI deploys to AWS
+
+The key is the **feedback loop**: the AI can see what's happening (logs, errors) and iterate until it works.
+
+## Starting agent mode
+
+```bash
+stacktape dev --agent --agentPort 9900 --resources all --stage dev --region us-east-1
+```
+
+| Flag          | Description                                 |
+| ------------- | ------------------------------------------- |
+| `--agent`     | Enable agent mode with HTTP API             |
+| `--agentPort` | Port for the HTTP server (default: 7331)    |
+| `--resources` | Workloads to run (`all` or comma-separated) |
+
+The command outputs API endpoints when ready:
+
+```
+AGENT_READY on port 9900
+GET  /status         - workload status
+GET  /logs           - get logs
+POST /rebuild/{name} - rebuild workload
+POST /stop           - shutdown
+```
+
+## API endpoints
+
+### Check status
+
+```bash
+curl http://localhost:9900/status
+```
+
+```json
+{
+  "phase": "ready",
+  "ready": true,
+  "workloads": {
+    "myApi": "http://localhost:3000",
+    "myWorker": "running"
+  }
+}
+```
+
+**Phase values:** `starting`, `ready`, `rebuilding`, `stopping`, `stopped`
+
+### Get verbose status
+
+```bash
+curl "http://localhost:9900/status?verbose=true"
+```
+
+Returns full details including ports, source directories, and local database status.
+
+### Read logs
+
+```bash
+curl "http://localhost:9900/logs?limit=50"
+```
+
+```json
+{
+  "logs": "14:30:15 [myApi] Server started\n14:30:16 [myWorker] Processing...",
+  "count": 2,
+  "nextCursor": 1706000001
+}
+```
+
+**Cursor-based pagination:** Use `nextCursor` from the response as `cursor` in the next request to get only new logs.
+
+```bash
+curl "http://localhost:9900/logs?cursor=1706000001"
+```
+
+### Rebuild a workload
+
+After making code changes:
+
+```bash
+curl -X POST http://localhost:9900/rebuild/myApi
+```
+
+### Rebuild all
+
+```bash
+curl -X POST http://localhost:9900/rebuild/all
+```
+
+### Stop dev mode
+
+```bash
+curl -X POST http://localhost:9900/stop
+```
+
+## Database endpoints
+
+Agent mode exposes endpoints to query locally-emulated databases directly.
+
+### PostgreSQL / MySQL
+
+```bash
+# Execute SQL
+curl -X POST http://localhost:9900/postgres/myDb/query \
+  -H "Content-Type: application/json" \
+  -d '{"sql": "SELECT * FROM users LIMIT 10"}'
+
+# Get schema
+curl http://localhost:9900/postgres/myDb/schema
+
+# List tables
+curl http://localhost:9900/postgres/myDb/tables
+```
+
+### Redis
+
+```bash
+# Execute command
+curl -X POST http://localhost:9900/redis/myCache/command \
+  -d '{"command": ["GET", "mykey"]}'
+
+# List keys
+curl http://localhost:9900/redis/myCache/keys
+```
+
+### DynamoDB
+
+```bash
+# Scan table
+curl -X POST http://localhost:9900/dynamodb/myTable/scan
+
+# Query
+curl -X POST http://localhost:9900/dynamodb/myTable/query \
+  -d '{"partitionKey": "user123"}'
+```
+
+## AI agent example session
+
+Here's what an AI session might look like:
+
+```
+User: Build me an API that stores and retrieves notes
+
+AI: I'll create the config and start dev mode.
+
+[Writes stacktape.ts with Lambda + DynamoDB]
+[Writes src/handler.ts with basic CRUD]
+
+$ stacktape dev --agent --agentPort 9900 --resources all --stage dev
+
+AI: Dev mode is starting. Let me check the status...
+
+$ curl http://localhost:9900/status
+{"phase":"ready","ready":true,"workloads":{"api":"http://localhost:3000"}}
+
+AI: Everything is running. Let me test the endpoint...
+
+$ curl http://localhost:3000/notes
+{"error":"Table not found"}
+
+AI: There's an error. Let me check the logs...
+
+$ curl http://localhost:9900/logs
+{"logs":"[api] ERROR: STP_NOTES_TABLE_NAME is undefined"}
+
+AI: The environment variable isn't being injected. I need to add connectTo.
+
+[Edits stacktape.ts to add connectTo: [notesTable]]
+
+$ curl -X POST http://localhost:9900/rebuild/api
+
+AI: Rebuilt. Testing again...
+
+$ curl http://localhost:3000/notes
+{"notes":[]}
+
+AI: Working! The API is ready.
+```
+
+## Best practices for AI agents
+
+1. **Poll status first** - Wait for `phase === "ready"` before making requests
+2. **Use cursors for logs** - Always use `nextCursor` to avoid re-fetching old logs
+3. **Rebuild specific workloads** - Faster than rebuilding everything
+4. **Check sourceDir in verbose status** - Know where source files are when debugging
+5. **Use database endpoints** - Query data directly to verify behavior
+
+## Stopping agent mode
+
+From another terminal:
+
+```bash
+stacktape dev --stop --agentPort 9900
+```
+
+Or via API:
+
+```bash
+curl -X POST http://localhost:9900/stop
+```
+
+## Next steps
+
+- [Dev Mode](/getting-started/dev-mode) - Understanding dev mode in depth
+- [Console](/getting-started/console) - Web-based management

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

@@ -0,0 +1,197 @@
+---
+docType: getting-started
+title: Workflow
+tags:
+  - workflow
+  - getting-started
+source: docs/_curated-docs/getting-started/workflow.mdx
+priority: 2
+---
+
+# Workflow
+
+Stacktape is an Infrastructure-as-Code (IaC) tool. You define your infrastructure in a config file, and Stacktape translates it into AWS CloudFormation and deploys it.
+
+## The mental model
+
+**Traditional IaC (CloudFormation, Terraform):**
+
+- You write hundreds of lines describing every detail
+- You manage IAM policies, security groups, VPC configs manually
+- Mistakes are common, debugging is painful
+
+**Stacktape:**
+
+- You write what you want at a high level (~30 lines)
+- Stacktape generates the low-level details (~1,200+ lines of CloudFormation)
+- Best practices are built in (security, networking, permissions)
+
+You still own everything. It all deploys to your AWS account. You can inspect, override, or eject at any time.
+
+## Configuration file
+
+Your config file (`stacktape.ts`, `stacktape.yml`, or `stacktape.json`) defines:
+
+- **Resources** - Lambda functions, databases, queues, buckets, etc.
+- **Connections** - Which resources can access each other
+- **Scripts** - Database migrations, seed scripts, utilities
+
+```typescript
+// stacktape.ts
+import { defineConfig, LambdaFunction, RelationalDatabase } from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const db = new RelationalDatabase({
+    engine: { type: 'postgres', version: '16' },
+    primaryInstance: {
+      instanceSize: stage === 'prod' ? 'db.t4g.medium' : 'db.t4g.micro'
+    }
+  });
+
+  const api = new LambdaFunction({
+    packaging: { type: 'stacktape-lambda-buildpack', properties: { entryfilePath: './src/api.ts' } },
+    connectTo: [db]
+  });
+
+  return { resources: { db, api } };
+});
+```
+
+## Stages and environments
+
+Each deployment has a **stage** (environment name). Stages are completely isolated - separate databases, separate functions, separate everything.
+
+```bash
+stacktape deploy --stage dev --region us-east-1    # my-app-dev stack
+stacktape deploy --stage staging --region us-east-1 # my-app-staging stack
+stacktape deploy --stage prod --region us-east-1    # my-app-prod stack
+```
+
+Use stages in your config for environment-specific settings:
+
+```typescript
+export default defineConfig(({ stage }) => ({
+  resources: {
+    db: new RelationalDatabase({
+      primaryInstance: {
+        instanceSize: stage === 'prod' ? 'db.t4g.medium' : 'db.t4g.micro',
+        multiAz: stage === 'prod'
+      }
+    })
+  }
+}));
+```
+
+## The connectTo pattern
+
+When you connect resources with `connectTo`, Stacktape automatically:
+
+1. **Grants IAM permissions** - The source resource can access the target
+2. **Injects environment variables** - Connection strings, hostnames, ARNs
+3. **Configures networking** - Security groups, VPC placement if needed
+
+```typescript
+const db = new DynamoDbTable({
+  /* ... */
+});
+
+const handler = new LambdaFunction({
+  connectTo: [db] // Handler gets read/write access to db
+  // ...
+});
+// Environment: STP_DB_TABLE_NAME, STP_DB_TABLE_ARN
+```
+
+This replaces pages of IAM policies and networking configs with a single line.
+
+## Deployment flow
+
+When you run `stacktape deploy`:
+
+1. **Parse** - Load config, resolve directives (`$Secret()`, `$Stage()`, etc.)
+2. **Validate** - Check config structure and resource compatibility
+3. **Package** - Bundle Lambda code with esbuild, build Docker images
+4. **Generate** - Transform config into CloudFormation template
+5. **Deploy** - Upload artifacts to S3, execute CloudFormation
+
+```
+$ stacktape deploy --stage dev --region us-east-1
+
+Packaging handler...           [2.1s]
+Uploading artifacts...         [1.4s]
+Deploying stack my-app-dev...  [45s]
+
+Stack deployed successfully!
+
+Outputs:
+  api.url: https://abc123.execute-api.us-east-1.amazonaws.com
+```
+
+## Development workflow
+
+For active development, use **dev mode** instead of deploying every change:
+
+```bash
+stacktape dev --stage dev --region us-east-1
+```
+
+This runs your workloads locally while connected to (or emulating) cloud resources. See [Dev Mode](/getting-started/dev-mode).
+
+## Typical iteration cycle
+
+1. **Write config** - Define your infrastructure in `stacktape.ts`
+2. **Dev mode** - Iterate locally with `stacktape dev`
+3. **Deploy** - Ship to dev/staging with `stacktape deploy`
+4. **Test** - Verify in cloud environment
+5. **Production** - Deploy to prod stage
+
+## Extending Stacktape
+
+Need something Stacktape doesn't support natively? You have options:
+
+**Overrides** - Modify any generated CloudFormation property:
+
+```typescript
+const fn = new LambdaFunction({
+  // ...
+  overrides: {
+    lambda: { Description: 'Custom description' }
+  }
+});
+```
+
+**Raw CloudFormation** - Add any AWS resource:
+
+```typescript
+export default defineConfig(() => ({
+  resources: {
+    /* ... */
+  },
+  cloudformationResources: {
+    myTopic: {
+      Type: 'AWS::SNS::Topic',
+      Properties: { TopicName: 'my-topic' }
+    }
+  }
+}));
+```
+
+**Transforms** - Programmatically modify resources (TypeScript only):
+
+```typescript
+const fn = new LambdaFunction({
+  // ...
+  transforms: {
+    lambda: (props) => ({
+      ...props,
+      MemorySize: (props.MemorySize ?? 128) * 2
+    })
+  }
+});
+```
+
+## Next steps
+
+- [Dev Mode](/getting-started/dev-mode) - Local development with cloud resources
+- [Using with AI](/getting-started/using-with-ai) - AI-assisted development
+- [Console](/getting-started/console) - Web-based management