belt 0.3.2 → 0.3.3

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

data/lib/belt/docs/plugins.md

@@ -0,0 +1,94 @@
+# Plugins
+
+Belt plugins are separate gems that extend the CLI and runtime. They're
+discovered automatically — no registration file or initializer hook needed.
+
+## Using a Plugin
+
+```ruby
+# Gemfile
+gem "belt-messaging"
+```
+
+```bash
+bundle install
+belt generate messaging    # run the plugin's generator
+belt destroy messaging     # remove what the generator created
+```
+
+## Available Plugins
+
+| Gem | Purpose |
+|-----|---------|
+| `belt-messaging` | Two-way SMS via AWS End User Messaging |
+| `belt-pay` | Stripe payments & subscriptions |
+
+## Creating a Plugin
+
+Scaffold a new plugin gem:
+
+```bash
+belt plugin new notifications
+belt plugin new pay --path ~/Code --summary "Stripe payments for Belt"
+```
+
+This creates a gem with the correct structure and Belt integration points.
+
+## Plugin Discovery Contract
+
+Belt discovers plugins automatically when:
+
+1. Gem is in the app's `Gemfile` and bundled
+2. Gem has a file at `lib/belt/generators/<name>_generator.rb`
+3. Class is `Belt::Generators::<Name>Generator`
+4. Class implements `.run(args)` (required)
+
+Optional: `.destroy(args)` and `.description` for destroy path and help text.
+
+## Generator Checklist
+
+A good plugin generator typically installs:
+
+1. **Terraform module** → `infrastructure/modules/<name>/`
+2. **Lambda config** → `config/lambda/<name>.yml`
+3. **Lambda entrypoint** → `lambda/<name>.rb` using `Belt::LambdaHandler`
+4. **Routes / schema** → inject into routes or schema when needed
+5. **Optional overrides** → `--controllers` flag for app-local subclasses
+6. **Destroy path** → removes everything the generator created
+7. **Help text** → `.description` + `--help`
+
+## Plugin Layout
+
+```
+belt-messaging/
+├── belt-messaging.gemspec
+├── lib/
+│   ├── belt-messaging.rb              # require entrypoint
+│   └── belt/
+│       ├── messaging.rb               # Runtime API
+│       ├── messaging/
+│       │   ├── configuration.rb
+│       │   ├── version.rb
+│       │   ├── controllers/           # Default controllers
+│       │   └── templates/             # ERB templates for generator
+│       └── generators/
+│           └── messaging_generator.rb # ← auto-discovered
+└── spec/
+```
+
+## Development Workflow
+
+Point a Belt app at your plugin during development:
+
+```ruby
+# In the app Gemfile
+gem "belt-notifications", path: "../belt-notifications"
+```
+
+`belt deploy` detects `path:` gems and vendors them into `vendor/cache`
+for Lambda packaging.
+
+## See Also
+
+- `belt explain generators` — built-in generators
+- `belt plugin new --help` — scaffold options

data/lib/belt/docs/routing.md

@@ -0,0 +1,138 @@
+# Routing
+
+Belt routes map HTTP requests to controller actions. Routes are defined in
+`config/routes.rb` using a Ruby DSL that mirrors infrastructure (API Gateway + Lambda).
+
+## Defining Routes
+
+```ruby
+Belt.application.routes.draw do
+  gateway :api do
+    resources :posts
+    resources :comments, only: [:index, :create]
+    resource :profile, only: [:show, :update]
+    get "health", action: :health
+  end
+end
+```
+
+## Route DSL Keywords
+
+| Keyword | Purpose | Creates Lambda? |
+|---------|---------|-----------------|
+| `gateway` | Creates an API Gateway + default Lambda | Yes |
+| `function` | Routes to a different Lambda (overrides gateway default) | Yes |
+| `namespace` | Adds path prefix + controller module nesting | No |
+| `scope` | Flexible path/module/auth grouping | No |
+
+## How `resources` Maps to Verbs
+
+`resources :posts` generates:
+
+| Verb | Path | Action |
+|------|------|--------|
+| GET | /posts | index |
+| POST | /posts | create |
+| GET | /posts/{post_id} | show |
+| PUT | /posts/{post_id} | update |
+| DELETE | /posts/{post_id} | destroy |
+
+**Note:** Belt uses PUT, not PATCH, for updates.
+
+Use `only:` or `except:` to limit generated routes:
+
+```ruby
+resources :posts, only: [:index, :show, :create]
+resources :comments, except: [:destroy]
+```
+
+## Singular Resources
+
+`resource :profile` (no `:id` in the path):
+
+| Verb | Path | Action |
+|------|------|--------|
+| GET | /profile | show |
+| PUT | /profile | update |
+| POST | /profile | create |
+| DELETE | /profile | destroy |
+
+## Namespace and Scope
+
+```ruby
+gateway :api do
+  # Namespace: adds path prefix AND controller module
+  namespace :admin do
+    resources :users  # → /admin/users → Admin::UsersController
+  end
+
+  # Scope: flexible grouping without full nesting
+  scope path: 'v2', module: 'legacy' do
+    resources :widgets  # → /v2/widgets → Legacy::WidgetsController
+  end
+end
+```
+
+## Multiple Lambdas
+
+Use `function` when routes should be handled by a separate Lambda:
+
+```ruby
+gateway :api do
+  resources :posts        # → handled by "api" Lambda
+
+  function :worker do
+    resources :jobs       # → handled by "worker" Lambda
+  end
+end
+```
+
+## Authentication
+
+```ruby
+gateway :api, auth: :cognito do
+  resources :posts                    # requires cognito auth
+  get "health", action: :health, auth: :none  # public
+end
+```
+
+## Table Access
+
+Declare which DynamoDB tables a route accesses (used by Terraform for IAM):
+
+```ruby
+resources :posts, tables: [:posts, :comments]
+```
+
+## Inspecting Routes
+
+```bash
+belt routes                    # display all routes
+belt routes -g posts           # filter by pattern
+belt routes -f json            # machine-readable output
+belt routes --namespace api    # generate Ruby route manifest
+```
+
+## Runtime Routing
+
+The Lambda entry point uses `Belt::ActionRouter` with the generated route manifest:
+
+```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
+```
+
+The router matches the incoming HTTP method + path against the manifest and
+dispatches to the appropriate controller and action.
+
+## See Also
+
+- `belt explain controllers` — how controllers handle requests
+- `belt explain deployment` — how routes become infrastructure
+- `belt routes --help` — full CLI options