belt 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe786827b1e1dc99140a55faddd4573d80799ddbbd4e82d4533f6f5b3b1fa063
-  data.tar.gz: 17de4ce04575bd50a45b99a677b01853537981993ef502c718cd74db84e5524c
+  metadata.gz: 2363120fdf3ee1746c38f73fc9807426a9b8a4b36d2fbcf0a8abe6b86a665197
+  data.tar.gz: 5c416967aa56c9fcd95cc6d9f9cead9de86b4e73c0b74dcee7476d9c29532212
 SHA512:
-  metadata.gz: ce42cd482a549027a830297f0fb88987d152821b835950d3480193bc868ab77fa9f0378cb504b419bf372443eb81971e1ecc00c505747162daab502cace2d705
-  data.tar.gz: 8bf51156214ee553a992c0821ed2a8e170fe4cba2503e78917e0a10244ea8f6de7e587cb3d8d0e5d1a63040ee2afc04de331dcdf7e5174d7fcefa3c9dd983746
+  metadata.gz: a81c85e8cab3d6fbd79b4fc71fec279d7d3bd4c31379264d509b55779da555999eb3ed2e0ead55bc6475ad4a43d7e25d1fda529ba4fd87748efc9e36cd9a9438
+  data.tar.gz: 2818d26460222cd45860d33a512fe06c0d5deb89436e7c4947e71c42d5270df0612c3fc6f72221f1bec3c304a93d03ad33a8fc9fc430394e379696d3384f42d3

data/lib/belt/action_router.rb

@@ -31,8 +31,15 @@ module Belt
       route_info = find_route(method, match_path)
 
       unless route_info
-        Belt::Observability::Logger.instance&.warn('Route not found', method: method, path: full_path)
-        return error_response('Not found', 404, event)
+        # Fallback: serve the Belt welcome page for GET / when no explicit root route exists.
+        # This handles the case where API Gateway delivers the request (e.g. via a catch-all
+        # integration or proxy route) but the route manifest doesn't include GET /.
+        if method == 'GET' && root_path?(match_path)
+          route_info = { verb: 'GET', pattern: '/', segments: [], controller: 'welcome', action: 'show' }
+        else
+          Belt::Observability::Logger.instance&.warn('Route not found', method: method, path: full_path)
+          return error_response('Not found', 404, event)
+        end
       end
 
       path_params = extract_path_params(route_info[:pattern], match_path)
@@ -60,6 +67,10 @@ module Belt
 
     private
 
+    def root_path?(path)
+      path == '/' || path.empty?
+    end
+
     def strip_gateway_prefix(path)
       return '/' if path.nil?
 

data/lib/belt/cli/explain_command.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Belt
+  module CLI
+    class ExplainCommand
+      DOCS_DIR = File.expand_path('../docs', __dir__)
+
+      TOPICS = Dir.glob(File.join(DOCS_DIR, '*.md')).map do |path|
+        File.basename(path, '.md')
+      end.sort.freeze
+
+      ALIASES = {
+        'routes' => 'routing',
+        'route' => 'routing',
+        'router' => 'routing',
+        'controller' => 'controllers',
+        'model' => 'models',
+        'activeitem' => 'models',
+        'dynamodb' => 'models',
+        'deploy' => 'deployment',
+        'deploying' => 'deployment',
+        'terraform' => 'deployment',
+        'generate' => 'generators',
+        'generator' => 'generators',
+        'scaffold' => 'generators',
+        'handler' => 'lambda_handler',
+        'lambda' => 'lambda_handler',
+        'entry_point' => 'lambda_handler',
+        'entrypoint' => 'lambda_handler',
+        'project' => 'structure',
+        'layout' => 'structure',
+        'directory' => 'structure',
+        'logs' => 'observability',
+        'logging' => 'observability',
+        'metrics' => 'observability',
+        'backup' => 'backups',
+        'plugin' => 'plugins',
+        'irb' => 'console',
+        'repl' => 'console'
+      }.freeze
+
+      def self.run(args)
+        if args.empty? || args.include?('--help') || args.include?('-h')
+          puts usage
+          return
+        end
+
+        topic = resolve_topic(args.first)
+
+        if topic.nil?
+          puts "Unknown topic: #{args.first}\n\n"
+          puts 'Available topics:'
+          TOPICS.each { |t| puts "  #{t}" }
+          puts "\nRun `belt explain <topic>` for details."
+          exit 1
+        end
+
+        display_topic(topic)
+      end
+
+      def self.resolve_topic(input)
+        normalized = input.downcase.gsub('-', '_')
+        return normalized if TOPICS.include?(normalized)
+        return ALIASES[normalized] if ALIASES[normalized]
+
+        # Fuzzy match: find topics that start with or contain the input
+        match = TOPICS.find { |t| t.start_with?(normalized) }
+        match || TOPICS.find { |t| t.include?(normalized) }
+      end
+
+      def self.display_topic(topic)
+        path = File.join(DOCS_DIR, "#{topic}.md")
+        content = File.read(path)
+        puts content
+      end
+
+      def self.usage
+        topic_list = TOPICS.map { |t| "  #{t}" }.join("\n")
+
+        <<~USAGE
+          Usage: belt explain <topic>
+
+          Display documentation for a Belt concept or feature.
+
+          Available topics:
+          #{topic_list}
+
+          Aliases:
+            routes, route, router     → routing
+            controller                → controllers
+            model, activeitem         → models
+            deploy, terraform         → deployment
+            generate, scaffold        → generators
+            handler, lambda           → lambda_handler
+            project, layout           → structure
+            logs, logging, metrics    → observability
+            backup                    → backups
+            plugin                    → plugins
+            irb, repl                 → console
+
+          Examples:
+            belt explain routing
+            belt explain controllers
+            belt explain deploy
+            belt explain models
+        USAGE
+      end
+    end
+  end
+end

data/lib/belt/cli/routes_command.rb

@@ -114,10 +114,34 @@ module Belt
           gateway.routes.each do |route|
             routes << build_route_hash(route, gateway)
           end
+          inject_welcome_route!(routes, gateway) unless root_route?(gateway)
         end
         routes.sort_by { |r| route_specificity(r[:path], r[:verb]) }
       end
 
+      # Ensure every gateway has a GET / route so the API Gateway resource is created.
+      # Without this, visiting the root URL returns a 404 at the gateway level before
+      # the request ever reaches Lambda.
+      def root_route?(gateway)
+        gateway.routes.any? { |r| r.method == 'GET' && normalize_path(r.path) == '/' }
+      end
+
+      def inject_welcome_route!(routes, gateway)
+        routes << {
+          name: 'root',
+          verb: 'GET',
+          path: '/',
+          gateway: gateway.name,
+          lambda: gateway.default_lambda.to_s,
+          controller: 'welcome',
+          action: 'show',
+          auth: 'none',
+          tables: [],
+          request_model: '',
+          response_model: ''
+        }
+      end
+
       def build_route_hash(route, gateway)
         hash = {
           name: extract_route_name(route.path),

data/lib/belt/cli.rb

@@ -26,6 +26,7 @@ require_relative 'cli/console_command'
 require_relative 'cli/logs_command'
 require_relative 'cli/doctor_command'
 require_relative 'cli/plugin_command'
+require_relative 'cli/explain_command'
 
 module Belt
   module CLI
@@ -42,6 +43,7 @@ module Belt
       'setup' => Belt::CLI::SetupCommand,
       'doctor' => Belt::CLI::DoctorCommand,
       'plugin' => Belt::CLI::PluginCommand,
+      'explain' => Belt::CLI::ExplainCommand,
       'deploy' => Belt::CLI::DeployCommand,
       'frontend' => Belt::CLI::FrontendEnvCommand,
       %w[server s] => Belt::CLI::ServerCommand,
@@ -55,7 +57,7 @@ module Belt
     TERRAFORM_ACTIONS = Belt::CLI::TerraformCommand::ACTIONS
 
     # Commands that can run without being inside a Belt project
-    STANDALONE_COMMANDS = %w[new version --version -v doctor].freeze
+    STANDALONE_COMMANDS = %w[new version --version -v doctor explain].freeze
 
     def self.start(args)
       command = args.shift
@@ -124,6 +126,7 @@ module Belt
           setup frontend <env>                        Generate S3 + CloudFront infrastructure
           doctor                                      Check system dependencies and AWS config
           plugin new <name>                           Scaffold a new Belt plugin gem
+          explain <topic>                             Explain a Belt concept (routing, models, …)
           init [environment] <env>                    terraform init for environment
           plan [environment] <env>                    terraform plan for environment
           apply [environment] <env>                   terraform apply for environment

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,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