belt 0.3.2 → 0.3.4

data/lib/belt/docs/deployment.md

@@ -0,0 +1,141 @@
+# Deployment
+
+Belt deploys serverless applications to AWS using Terraform. The CLI wraps
+`terraform init/plan/apply` with conventions for environment management,
+Lambda packaging, and pre-deploy backups.
+
+## Quick Deploy
+
+```bash
+belt deploy <env>              # init → plan → apply (interactive)
+belt deploy prod --auto        # skip confirmation prompt
+belt deploy prod --skip-backup # skip pre-deploy backup
+belt deploy --backup-only      # create recovery point without deploying
+```
+
+## First-Time Setup
+
+```bash
+# 1. Create S3 bucket for Terraform state
+belt setup state
+
+# 2. Scaffold an environment
+belt generate environment dev01
+
+# 3. Generate DynamoDB table definitions from schema
+belt setup tables dev01
+
+# 4. Initialize and deploy
+belt deploy dev01
+```
+
+## Environment Structure
+
+Each environment lives in `infrastructure/<env>/`:
+
+```
+infrastructure/
+├── modules/
+│   └── main/            # Shared Terraform module
+├── dev01/
+│   ├── main.tf          # Module reference + provider
+│   ├── variables.tf     # Variable declarations
+│   ├── terraform.tfvars # Environment-specific values
+│   ├── backend.tf       # S3 state backend
+│   └── outputs.tf       # Exported values
+└── prod/
+    └── ...
+```
+
+## What Gets Deployed
+
+The Conveyor Belt Terraform provider reads your Ruby DSL and creates:
+
+1. **API Gateway** — HTTP API with routes matching your DSL
+2. **Lambda functions** — packaged Ruby code (one per `gateway`/`function` block)
+3. **IAM roles** — least-privilege policies for DynamoDB table access
+4. **CloudWatch logs** — log groups for each Lambda
+5. **DynamoDB tables** — from your schema definition
+6. **Custom domain** — if configured (Route53 + ACM certificate)
+
+## Lambda Packaging
+
+Belt packages the `lambda/` directory plus vendored gems. For `path:` gems
+(local development), Belt materializes them into `vendor/cache` automatically.
+
+The Lambda entry point is specified in `config/lambda/<name>.yml`:
+
+```yaml
+handler: lambda/<name>.lambda_handler
+runtime: ruby3.3
+timeout: 30
+memory: 256
+environment:
+  ENVIRONMENT: ${var.environment}
+```
+
+## Route Manifests
+
+Before deploying, generate the route manifest used at runtime:
+
+```bash
+belt routes --namespace api
+# → writes lambda/lib/routes/api_routes.rb
+```
+
+This is typically done automatically by `belt deploy`.
+
+## Terraform Commands
+
+Belt wraps Terraform with environment awareness:
+
+```bash
+belt init <env>       # terraform init with correct backend
+belt plan <env>       # terraform plan
+belt apply <env>      # terraform apply
+belt destroy <env>    # terraform destroy (careful!)
+belt output <env>     # terraform output
+```
+
+Or use `belt deploy <env>` which runs init → plan → apply in sequence.
+
+## Pre-Deploy Backups
+
+Configure in `infrastructure/<env>/belt.rb`:
+
+```ruby
+Belt.configure do |config|
+  config.backups do
+    dynamodb :all
+    retention snapshots: 90
+  end
+end
+```
+
+Backups run automatically before each deploy (DynamoDB snapshots, Cognito
+exports, S3 syncs). See `belt explain backups` for full documentation.
+
+## Environment Variables
+
+Set `BELT_ENV` to avoid typing the environment every time:
+
+```bash
+export BELT_ENV=dev01
+belt deploy           # uses BELT_ENV
+belt deploy prod      # explicit arg wins
+```
+
+## Frontend Deployment
+
+For apps with a frontend:
+
+```bash
+belt deploy frontend <env>    # build + deploy to S3/CloudFront
+belt frontend env <env>       # generate .env from Terraform outputs
+```
+
+## See Also
+
+- `belt explain routing` — how routes map to infrastructure
+- `belt explain backups` — pre-deploy backup configuration
+- `belt doctor` — check system dependencies before deploying

data/lib/belt/docs/generators.md

@@ -0,0 +1,128 @@
+# Generators
+
+Belt generators scaffold code and infrastructure for common patterns.
+Run `belt generate --help` to see all available generators (built-in + plugins).
+
+## Built-in Generators
+
+### Resource (scaffold)
+
+Creates model + controller + routes + schema entry:
+
+```bash
+belt generate resource post title:string body:text user_id:string status:string
+belt g resource comment body:text author:string post_id:string
+```
+
+This is the most common generator — it sets up everything for a new REST endpoint.
+
+### Model
+
+Creates just the model file + schema entry:
+
+```bash
+belt generate model post title:string body:text user_id:string
+belt g model payment amount:number currency:string
+```
+
+### Controller
+
+Creates just the controller:
+
+```bash
+belt generate controller posts
+belt g controller admin/users
+```
+
+### Environment
+
+Scaffolds a new Terraform environment directory:
+
+```bash
+belt generate environment staging
+belt g environment prod
+```
+
+### Frontend
+
+Adds a frontend framework to the project:
+
+```bash
+belt generate frontend react
+belt generate frontend vue
+belt generate frontend svelte
+```
+
+### Views
+
+Generates React pages for a resource's REST actions:
+
+```bash
+belt generate views post title:string body:text status:string
+belt g views comment body:text author:string
+```
+
+### Auth
+
+Sets up Cognito authentication:
+
+```bash
+belt generate auth
+belt g auth --provider cognito
+```
+
+## Field Types
+
+When specifying fields, use these types:
+
+| Type | DynamoDB Type | Notes |
+|------|---------------|-------|
+| `string` | S | Default if no type given |
+| `text` | S | Same as string (semantic hint) |
+| `number` | N | Numeric values |
+| `boolean` | BOOL | True/false |
+| `list` | L | Array values |
+| `map` | M | Nested objects |
+
+## Destroying Generated Code
+
+Every generator has a matching destroy command:
+
+```bash
+belt destroy resource post
+belt destroy model comment
+belt destroy controller admin/users
+belt destroy environment staging
+belt destroy frontend
+belt destroy views post
+```
+
+## Plugin Generators
+
+Gems that follow the Belt plugin contract are auto-discovered:
+
+```bash
+belt generate messaging     # from belt-messaging gem
+belt generate pay           # from belt-pay gem
+belt generate --help        # lists all available generators
+```
+
+## Generator Workflow (Common Pattern)
+
+```bash
+# 1. Generate the resource
+belt generate resource order item_id:string quantity:number total:number status:string
+
+# 2. Generate DynamoDB table from schema
+belt setup tables dev01
+
+# 3. Deploy
+belt deploy dev01
+```
+
+## See Also
+
+- `belt explain models` — how generated models work
+- `belt explain controllers` — how generated controllers work
+- `belt explain routing` — how generated routes work
+- `belt explain deployment` — deploying generated code

data/lib/belt/docs/lambda_handler.md

@@ -0,0 +1,105 @@
+# Lambda Handler
+
+`Belt::LambdaHandler` is the module you include in your Lambda entry point.
+It provides the `lambda_handler` method that AWS Lambda invokes, wrapping
+your application logic with observability, CORS, and error handling.
+
+## Basic Usage
+
+```ruby
+require "belt"
+
+include Belt::LambdaHandler
+
+ROUTER = Belt::ActionRouter.new(routes: Routes::API, gateway: "api")
+
+def execute(path:, body:, event:)
+  ROUTER.route(event: event, body: body)
+end
+```
+
+## What It Does
+
+When a request arrives, `lambda_handler` automatically:
+
+1. **Initializes observability** — structured logging + CloudWatch metrics
+2. **Handles OPTIONS preflight** — returns CORS headers immediately
+3. **Parses the request body** — JSON string → Ruby hash
+4. **Calls your `execute` method** — with `path:`, `body:`, and `event:`
+5. **Catches unhandled errors** — returns a CORS-enabled error response
+6. **Emits metrics** — request count, latency, error count via EMF
+
+## The `execute` Method
+
+You must define `execute` in your Lambda file. It receives:
+
+| Param | Description |
+|-------|-------------|
+| `path:` | The request path (e.g., `/posts/123`) |
+| `body:` | Parsed request body (Hash or nil) |
+| `event:` | Full API Gateway event (for headers, query params, auth context) |
+
+Return value should be a response hash: `{ statusCode:, headers:, body: }`.
+Typically you just call `ROUTER.route(...)` which returns the correct format.
+
+## Multiple Lambdas
+
+If your app has multiple Lambda functions (via `function` in routes):
+
+```ruby
+# lambda/worker.rb
+require "belt"
+
+include Belt::LambdaHandler
+
+ROUTER = Belt::ActionRouter.new(routes: Routes::WORKER, gateway: "worker")
+
+def execute(path:, body:, event:)
+  ROUTER.route(event: event, body: body)
+end
+```
+
+Each Lambda entry point gets its own route manifest and gateway name.
+
+## Configuration
+
+Configure via `config/lambda/<name>.yml`:
+
+```yaml
+handler: lambda/api.lambda_handler
+runtime: ruby3.3
+timeout: 30
+memory: 256
+layers:
+  - ${var.ruby_layer_arn}
+environment:
+  ENVIRONMENT: ${var.environment}
+  APP_NAME: my-app
+  ERROR_NOTIFICATION_TOPIC_ARN: ${var.sns_topic_arn}
+```
+
+## Observability
+
+The handler sets up `Belt::Observability::Logger` and `Belt::Observability::Metrics`
+automatically. Use them anywhere in your app:
+
+```ruby
+Belt::Observability::Logger.info("Order created", order_id: order.id)
+Belt::Observability::Metrics.track_event("OrderCreated", model: "Order")
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `ENVIRONMENT` | Controls error verbosity (`dev*`, `local`, `test` = verbose) |
+| `BELT_METRICS_NAMESPACE` | CloudWatch namespace (default: `Belt`) |
+| `ACTION` | Service name for logging |
+| `ERROR_NOTIFICATION_TOPIC_ARN` | SNS topic for error alerts |
+| `CORS_ALLOWED_ORIGINS` | Comma-separated allowed origins |
+
+## See Also
+
+- `belt explain routing` — how ActionRouter dispatches requests
+- `belt explain controllers` — how dispatched requests are handled
+- `belt explain deployment` — Lambda packaging and configuration

data/lib/belt/docs/models.md

@@ -0,0 +1,160 @@
+# Models
+
+Belt uses **ActiveItem** as its ORM for DynamoDB. Models inherit from
+`ActiveItem::Base` (typically via an `ApplicationRecord` base class).
+
+## Basic Model
+
+```ruby
+class Post < ApplicationRecord
+  attr_accessor :id, :user_id, :title, :body, :status, :created_at, :updated_at
+
+  validates :title, presence: true
+  validates :status, inclusion: { in: %w[draft published] }, allow_nil: true
+
+  before_create { self.id ||= SecureRandom.uuid }
+  before_save { self.updated_at = Time.now.iso8601 }
+end
+```
+
+## Table Naming
+
+Table names are derived from the environment:
+`{APP_NAME}-{ENVIRONMENT}-{pluralized_model}`
+
+Example: app "blog", environment "prod", model "Post" → `blog-prod-posts`
+
+## Schema Definition
+
+Define table structure in `infrastructure/schema.tf.rb`:
+
+```ruby
+Belt.application.schema.define do
+  model :post do
+    partition_key :id, :string
+    global_secondary_index :UserIndex, partition_key: :user_id
+    global_secondary_index :StatusIndex, partition_key: :status, sort_key: :created_at
+  end
+end
+```
+
+## CRUD Operations
+
+### Create
+
+```ruby
+post = Post.create!(title: "Hello", body: "World", user_id: "u-123")
+# or
+post = Post.new(title: "Hello")
+post.save!
+```
+
+### Read
+
+```ruby
+post = Post.find("post-id-123")           # by primary key
+posts = Post.all                           # scan (use sparingly)
+posts = Post.where(user_id: "u-123", index: "UserIndex")
+post = Post.find_by(user_id: "u-123", index: "UserIndex")  # first match
+```
+
+### Update
+
+```ruby
+post = Post.find("post-id-123")
+post.update(title: "New Title")
+# or
+post.title = "New Title"
+post.save!
+```
+
+### Delete
+
+```ruby
+post = Post.find("post-id-123")
+post.destroy
+```
+
+## Query Patterns
+
+### Using Indexes
+
+```ruby
+# Query a GSI
+Post.where(user_id: "u-123", index: "UserIndex")
+
+# With sort key conditions
+Post.where(
+  status: "published",
+  created_at: { gte: "2024-01-01" },
+  index: "StatusIndex"
+)
+```
+
+### Count and Existence
+
+```ruby
+Post.count                              # total items (scan)
+Post.exists?("post-id-123")            # check by primary key
+```
+
+## Validations
+
+ActiveItem supports ActiveModel-style validations:
+
+```ruby
+validates :title, presence: true
+validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :status, inclusion: { in: %w[active inactive] }
+validates :age, numericality: { greater_than: 0 }
+```
+
+## Callbacks
+
+```ruby
+before_create  { self.id ||= SecureRandom.uuid }
+before_save    { self.updated_at = Time.now.iso8601 }
+after_create   { notify_subscribers }
+before_destroy { cleanup_associations }
+```
+
+## Associations (Manual)
+
+DynamoDB doesn't have joins. Model relationships manually:
+
+```ruby
+class Post < ApplicationRecord
+  def comments
+    Comment.where(post_id: id, index: "PostIndex")
+  end
+
+  def author
+    User.find(user_id)
+  end
+end
+```
+
+## Transactions
+
+```ruby
+ActiveItem::Transaction.write do |tx|
+  tx.put(post)
+  tx.put(comment)
+  tx.delete(draft)
+end
+```
+
+## Generating Models
+
+```bash
+belt generate model post title:string body:text user_id:string
+belt generate resource comment body:text author:string post_id:string
+```
+
+The resource generator creates model + controller + routes + schema entry.
+
+## See Also
+
+- `belt explain controllers` — using models in controllers
+- `belt explain deployment` — how schema becomes infrastructure
+- `belt explain queries` — advanced DynamoDB query patterns

data/lib/belt/docs/observability.md

@@ -0,0 +1,94 @@
+# Observability
+
+Belt provides structured logging and CloudWatch metrics out of the box.
+These are initialized automatically by `Belt::LambdaHandler` — no setup required.
+
+## Logging
+
+Access the logger from anywhere:
+
+```ruby
+Belt::Observability::Logger.info("Order placed", order_id: "o-123", total: 49.99)
+Belt::Observability::Logger.warn("Retry attempt", attempt: 3, service: "payments")
+Belt::Observability::Logger.error("Payment failed", error: e.message, order_id: "o-123")
+```
+
+Logs are structured JSON, compatible with CloudWatch Logs Insights:
+
+```json
+{
+  "level": "INFO",
+  "message": "Order placed",
+  "order_id": "o-123",
+  "total": 49.99,
+  "timestamp": "2024-01-15T10:30:00Z",
+  "service": "api"
+}
+```
+
+## Metrics
+
+Track custom events via CloudWatch Embedded Metric Format (EMF):
+
+```ruby
+Belt::Observability::Metrics.track_event("OrderCreated", model: "Order")
+Belt::Observability::Metrics.track_event("PaymentProcessed", amount: 49.99)
+```
+
+### Built-in Metrics
+
+The Lambda handler automatically emits:
+- `RequestCount` — per invocation
+- `ErrorCount` — on unhandled exceptions
+- `Latency` — request duration in milliseconds
+
+### Namespace
+
+Metrics are published under the namespace set by `BELT_METRICS_NAMESPACE`
+(defaults to `Belt`). View them in CloudWatch → Metrics → Custom namespaces.
+
+## Error Alerting
+
+Set `ERROR_NOTIFICATION_TOPIC_ARN` to an SNS topic ARN. Unhandled errors
+will publish a notification with error details (message, backtrace, request context).
+
+```yaml
+# config/lambda/api.yml
+environment:
+  ERROR_NOTIFICATION_TOPIC_ARN: ${var.sns_topic_arn}
+```
+
+## CloudWatch Logs Insights
+
+Query structured logs:
+
+```
+fields @timestamp, message, order_id
+| filter level = "ERROR"
+| sort @timestamp desc
+| limit 20
+```
+
+## Viewing Logs Locally
+
+```bash
+belt logs api              # tail logs for the "api" Lambda
+belt logs api -f           # follow (live tail)
+belt logs api -s 30m       # last 30 minutes
+belt logs worker -e prod   # specific environment
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `BELT_METRICS_NAMESPACE` | CloudWatch metrics namespace (default: `Belt`) |
+| `ACTION` | Service name in log entries (falls back to function name) |
+| `ERROR_NOTIFICATION_TOPIC_ARN` | SNS topic for error alerts |
+| `ENVIRONMENT` | Controls verbose errors (`dev*`/`local`/`test` = verbose) |
+
+## See Also
+
+- `belt explain lambda_handler` — how observability is initialized
+- `belt explain deployment` — configuring environment variables
+- `belt logs --help` — full CLI options for log viewing