belt 0.2.17 → 0.3.14

data/lib/belt/docs/backups.md

@@ -0,0 +1,101 @@
+# Backups
+
+Belt integrates automated pre-deploy backups into the deploy lifecycle.
+When configured, `belt deploy` creates recovery points before applying changes.
+
+## Quick Setup
+
+Create `infrastructure/<env>/belt.rb`:
+
+```ruby
+Belt.configure do |config|
+  config.backups do
+    dynamodb :all
+    retention snapshots: 90
+  end
+end
+```
+
+Then deploy normally — backups run automatically:
+
+```bash
+belt deploy prod
+```
+
+## Simple Mode
+
+For DynamoDB-only backups with defaults (all tables, 90-day retention):
+
+```ruby
+Belt.configure do |config|
+  config.backups = true
+end
+```
+
+## Full Configuration
+
+```ruby
+Belt.configure do |config|
+  config.backups do
+    dynamodb :all                     # All tables: PITR check + on-demand snapshot
+    dynamodb :posts, :users           # Or specific tables only
+    cognito :users, :pool_config      # Export user list + pool settings to S3
+    s3 :legal_documents               # Sync bucket to backup bucket
+    retention snapshots: 90, cognito: 10, s3: 10
+  end
+end
+```
+
+## Backup Types
+
+| Type | What It Does | Default Retention |
+|------|-------------|-------------------|
+| `dynamodb :all` | PITR verification + on-demand snapshot per table | 90 days |
+| `dynamodb :table1, :table2` | Same, specific tables only | 90 days |
+| `cognito :users` | Paginated user export → JSON in backup bucket | 10 copies |
+| `cognito :pool_config` | Pool configuration export → JSON | 10 copies |
+| `s3 :bucket_name` | Full sync to backup bucket | 10 copies |
+
+## CLI Flags
+
+```bash
+belt deploy prod                # normal deploy (runs backups first)
+belt deploy prod --skip-backup  # skip backup phase
+belt deploy prod --backup-only  # just create recovery point, don't deploy
+```
+
+## How It Works
+
+1. Creates backup bucket `<app-name>-backups-<env>` on first run (versioned, public access blocked)
+2. Reads table names from `terraform output`
+3. Verifies PITR is enabled on each DynamoDB table
+4. Creates on-demand backup named `<table>-<timestamp>`
+5. For Cognito/S3: exports to backup bucket under timestamped prefixes
+6. Cleans up expired snapshots/copies beyond retention
+
+## First Deploy
+
+On a brand-new environment with no prior deploys, there are no Terraform outputs
+to read table names from. Belt warns and skips the backup phase gracefully.
+After the first successful deploy, backups run normally.
+
+## DynamoDB Protection Defaults
+
+All Belt-generated DynamoDB tables include:
+- **PITR** (Point-in-Time Recovery) — enabled by default (35 days continuous)
+- **Deletion protection** — enabled in prod, disabled in dev
+
+## Skipping Backups in Dev
+
+Don't create `infrastructure/dev01/belt.rb`, or omit the backups block:
+
+```ruby
+Belt.configure do |config|
+  # No backups block = no backups during deploy
+end
+```
+
+## See Also
+
+- `belt explain deployment` — the full deploy lifecycle
+- `belt deploy --help` — all deploy options

data/lib/belt/docs/console.md

@@ -0,0 +1,65 @@
+# Console
+
+`belt console` (alias: `belt c`) starts an interactive Ruby session with your
+application fully loaded — models, configuration, AWS clients, everything.
+
+## Basic Usage
+
+```bash
+belt console             # uses BELT_ENV or defaults to 'dev'
+belt c prod              # specify environment
+belt c dev01             # any environment name
+```
+
+## What Gets Loaded
+
+1. `lambda/config/environment.rb` — your app's boot file (AWS setup, models, libs)
+2. IRB starts with `reload!` available
+3. `.irbrc` from project root (optional console customization)
+
+## Runner Mode
+
+Execute a command and exit (useful for scripts/CI):
+
+```bash
+belt c dev01 --run "Customer.first"
+belt c prod --run "Post.count"
+belt c dev01 --run "User.where(status: 'active', index: 'StatusIndex').count"
+```
+
+## Production Safety
+
+When the environment is `prod`, Belt shows a confirmation prompt before
+starting the console. This prevents accidentally running destructive commands
+against production data.
+
+## Common Tasks
+
+```ruby
+# Find a record
+post = Post.find("post-id-123")
+
+# Query with index
+users = User.where(status: "active", index: "StatusIndex")
+
+# Create a record
+Post.create!(title: "Test", body: "Hello", user_id: "u-123")
+
+# Count records
+Order.count
+
+# Reload code changes
+reload!
+```
+
+## Environment Resolution
+
+Priority order:
+1. Explicit argument: `belt c prod`
+2. `BELT_ENV` environment variable
+3. Default: `dev`
+
+## See Also
+
+- `belt explain models` — ActiveItem query methods
+- `belt explain structure` — where environment.rb lives

data/lib/belt/docs/controllers.md

@@ -0,0 +1,155 @@
+# Controllers
+
+Belt controllers inherit from `BeltController::Base` and handle HTTP requests
+dispatched by `Belt::ActionRouter`. They provide callbacks, strong parameters,
+response helpers, and error handling — similar to Rails ActionController.
+
+## Basic Controller
+
+```ruby
+module MyApp
+  class PostsController < ApplicationController
+    def index
+      @posts = Post.all
+    end
+
+    def show
+      @post = Post.find(params["id"])
+    end
+
+    def create
+      attrs = params.require(:post).permit(:title, :body).to_h
+      @post = Post.create!(attrs.merge(user_id: current_user_id))
+      response_status :created
+    end
+
+    def destroy
+      Post.find(params["id"]).destroy
+      head :no_content
+    end
+  end
+end
+```
+
+## Response Behavior
+
+### Implicit Responses (default: JSON)
+
+When an action sets instance variables and returns without calling a response
+helper, Belt auto-serializes assigns into a JSON response:
+
+```ruby
+def index
+  @posts = Post.all  # → { "posts": [...] }
+end
+
+def show
+  @post = Post.find(params["id"])  # → { "post": {...} }
+end
+```
+
+### Explicit Response Helpers
+
+```ruby
+success_response({ id: "123", name: "Example" })       # 200 JSON
+success_response({ id: "123" }, :created)               # 201 JSON
+error_response("Not found", :not_found)                 # 404 JSON
+error_response("Nope", :unprocessable_entity)           # 422 JSON
+html_response("<h1>Hello</h1>")                         # 200 HTML
+head :no_content                                        # 204 empty
+head :created                                           # 201 empty
+```
+
+### Non-200 with Implicit Assigns
+
+```ruby
+def create
+  @post = Post.create!(...)
+  response_status :created   # → 201 + { "post": {...} }
+end
+```
+
+### Default Format
+
+```ruby
+# Global (in config/environment.rb)
+Belt.configure do |config|
+  config.default_format = :json   # or :html
+end
+
+# Per-controller
+class PagesController < ApplicationController
+  self.default_format = :html
+end
+```
+
+- `:json` — assigns become JSON body
+- `:html` — renders `views/<controller>/<action>.html.erb`
+
+## Callbacks
+
+```ruby
+class ApplicationController < BeltController::Base
+  before_action :authenticate!
+  before_action :require_admin!, except: [:health]
+  skip_before_action :authenticate!, only: [:health]
+end
+```
+
+Callbacks run in definition order. `before_action` can halt the request by
+calling a response helper (e.g., `error_response`).
+
+## Strong Parameters
+
+```ruby
+params.require(:user).permit(:name, :email, address: [:street, :city])
+```
+
+- `params` — merged hash of path parameters + parsed JSON body
+- `require(:key)` — raises if key missing
+- `permit(:field1, :field2)` — whitelists allowed fields
+- Nested: `permit(:name, address: [:street, :city])`
+
+## Error Handling
+
+```ruby
+class ApplicationController < BeltController::Base
+  rescue_from ActiveItem::RecordNotFound, with: :not_found
+  rescue_from MyCustomError, with: :handle_custom
+
+  private
+
+  def not_found(exception, _context = {})
+    error_response(exception.message, :not_found)
+  end
+
+  def handle_custom(exception, _context = {})
+    error_response(exception.message, :unprocessable_entity)
+  end
+end
+```
+
+## Controller Discovery
+
+Belt resolves controllers by:
+1. Checking the app's namespace module (e.g., `MyApp::PostsController`)
+2. Searching `Belt.all_controller_paths`
+
+No manual registration required. Controllers are auto-discovered from the
+`lambda/controllers/` directory.
+
+## CORS
+
+CORS headers are handled automatically by `Belt::LambdaHandler`. Controllers
+don't need to set them manually. Configure allowed origins via environment
+variables:
+
+- `CORS_ALLOWED_ORIGINS` — comma-separated origins
+- `CUSTOMER_APP_DOMAIN` — primary app domain
+- `OPS_APP_DOMAIN` — internal tools domain
+
+## See Also
+
+- `belt explain routing` — how requests reach controllers
+- `belt explain models` — ActiveItem ORM
+- `belt explain parameters` — strong parameters in detail

data/lib/belt/docs/deployment.md

@@ -0,0 +1,166 @@
+# 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`.
+
+## Sidecar Lambda Zips
+
+Conveyor Belt packages Ruby lambdas. Some apps also have standalone
+`aws_lambda_function` resources (Node image processors, Cognito triggers)
+whose Terraform uses `filename` + `filebase64sha256` pointing at a zip on disk.
+
+`belt deploy`, `belt plan`, and `belt apply` scan `infrastructure/**/*.tf` for
+those zip paths and build any that are missing (or whose source hash changed):
+
+- Directory with `package.json` — `npm ci` in Docker (`linux/amd64`, Lambda
+  Node image) so native addons like `sharp` match Lambda, then zip
+- Plain JS directory — zip the `.js` / `.mjs` files
+
+The zip lives next to the source (`image-processor/image-processor.zip`). This
+is the same pre-terraform step Stowzilla's `scripts/deploy.sh` does for the
+image processor. Existing zips with no hash file are left alone.
+
+Docker must be running for Node packages.
+
+## 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 all frontends
+belt deploy frontend <env> --frontend ops   # deploy one named frontend
+belt frontend env <env>                     # generate .env from Terraform outputs
+belt frontend list                          # show configured frontends
+```
+
+The directory is `frontend/` by default. Multiple SPAs are declared in
+`config/frontends.yml` — see `belt explain frontend`. Full `belt deploy <env>`
+deploys every configured frontend after terraform apply.
+
+## 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/frontend.md

@@ -0,0 +1,103 @@
+# Frontends
+
+Belt can host one or more JavaScript SPAs (React, Vue, or Svelte) next to the
+Lambda API. A typical app has a single `frontend/` directory. Some apps — Stowzilla
+is the example that drove this — have several independent SPAs (customer, ops,
+partners) that share the same models and API.
+
+## Single frontend (default)
+
+```bash
+belt new blog --frontend react
+# or, in an existing app:
+belt generate frontend react
+```
+
+That creates `frontend/`, S3 + CloudFront infrastructure, and wires CORS so the
+SPA can call the API. No config file is required.
+
+```bash
+belt server                       # local Vite dev server
+belt frontend env dev01           # write frontend/.env from terraform outputs
+belt deploy frontend dev01        # npm ci → build → S3 sync → CloudFront invalidation
+```
+
+## Multiple frontends
+
+Declare them in `config/frontends.yml` (or `.belt/frontends.yml`):
+
+```yaml
+frontends:
+  customer:
+    path: app
+    dist: build
+    default: true
+    bucket_output: web_app_bucket_name
+    url_output: web_app_url
+    cloudfront_domain_output: web_app_cloudfront_domain
+  ops:
+    path: ops-app
+    dist: build
+    bucket_output: ops_app_bucket_name
+    url_output: ops_app_url
+    cloudfront_domain_output: ops_app_cloudfront_domain
+```
+
+`path` is the directory. `dist` is the build output (`dist` by default; belt
+also auto-detects `build/` after `npm run build`). Terraform output names default
+to `frontend_*` for the `frontend` app and `{name}_frontend_*` for others — override
+them when existing infrastructure uses different names.
+
+If terraform exports a CloudFront **domain** instead of a distribution ID, set
+`cloudfront_domain_output` and skip `distribution_output`. Belt looks the ID up
+via AWS and will not probe `{name}_frontend_distribution_id`.
+
+```bash
+belt frontend list
+belt generate frontend react --name ops --path ops-app
+belt generate views bag --frontend ops
+belt generate scaffold order --frontend customer
+belt server --frontend ops
+belt frontend env dev01 --frontend customer
+belt deploy frontend dev01                  # all configured frontends
+belt deploy frontend dev01 --frontend ops   # just ops
+```
+
+If several frontends exist and you omit `--frontend`, generators and `belt server`
+use the one marked `default: true`. If none is default, they ask you to pick.
+
+`belt deploy frontend <env>` with no `--frontend` deploys every frontend that
+has a `package.json`. Full `belt deploy <env>` does the same after terraform apply.
+
+## Env maps
+
+Each frontend can have its own `env.yml` mapping process env names to terraform
+outputs:
+
+```yaml
+# app/env.yml
+VITE_API_URL: api_url
+VITE_COGNITO_USER_POOL_ID: cognito_user_pool_id
+VITE_COGNITO_CLIENT_ID: cognito_client_id
+```
+
+The default `frontend/` directory also accepts `.belt/frontend_env.yml` as a
+fallback. See the existing env-map behavior: only mapped keys are written into
+`.env`; missing terraform outputs warn and do not clobber local values.
+
+## Infrastructure
+
+`belt setup frontend` (and `belt generate frontend`) writes S3 + CloudFront into
+`infrastructure/modules/app/frontend.tf`. Additional named frontends get
+`{name}_frontend.tf` with unique resource names and outputs
+(`ops_frontend_bucket_name`, …). Extra frontends get a CloudFront URL only —
+custom DNS stays on the default frontend unless you add records yourself.
+
+CORS: each CloudFront domain is added to `frontend_urls` on the conveyor-belt
+resource so SPA → API calls work.
+
+## See Also
+
+- `belt explain deployment` — how frontend deploy fits into `belt deploy`
+- `belt explain generators` — `belt generate frontend` / views
+- `belt explain structure` — where frontend directories live