belt 0.3.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe786827b1e1dc99140a55faddd4573d80799ddbbd4e82d4533f6f5b3b1fa063
-  data.tar.gz: 17de4ce04575bd50a45b99a677b01853537981993ef502c718cd74db84e5524c
+  metadata.gz: 33ab3ee829508580c32a99fd91f008cd09b3dd80e2502f22b03e7e4d5ff9d00a
+  data.tar.gz: 204c45931c8e038037f4d49781bbf43fff9396cd58e32d38d4cdb607fdccdfa7
 SHA512:
-  metadata.gz: ce42cd482a549027a830297f0fb88987d152821b835950d3480193bc868ab77fa9f0378cb504b419bf372443eb81971e1ecc00c505747162daab502cace2d705
-  data.tar.gz: 8bf51156214ee553a992c0821ed2a8e170fe4cba2503e78917e0a10244ea8f6de7e587cb3d8d0e5d1a63040ee2afc04de331dcdf7e5174d7fcefa3c9dd983746
+  metadata.gz: 2f2f957782e6b03ef246167f46309a51a50cc286d3d4c1d8ba4411eba8a2ad558a2556986991848116519c5286bef5d57e5805307bbf314932580b82397beb43
+  data.tar.gz: 587671ca7188c4ff9476ee4568b3f7f513c05eb285088be3b7282a1b2096b4cc7f6a3c7d7f1e609e92e22e87db851b785422fd0ab4ea07e76ecd028cf6b87103

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.4
+
+### Enhancement
+
+- **Flexible config file extensions**: Lambda config files (`config/lambda/*.yml`) and frontend env maps (`frontend/env.yml`, `.belt/frontend_env.yml`) now also accept `.yaml` as a file extension. (#1124)
+
 ## 0.3.2
 
 ### Bug fix

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/frontend_env_command.rb

@@ -36,7 +36,7 @@ module Belt
           puts 'Usage: belt frontend env <environment>'
           puts "\nWrites frontend/.env from terraform outputs using the env map."
           puts 'You can also set BELT_ENV to skip the environment argument.'
-          puts "\nMap file (optional): frontend/env.yml or .belt/frontend_env.yml"
+          puts "\nMap file (optional): frontend/env.{yml,yaml} or .belt/frontend_env.{yml,yaml}"
           puts 'Default without map: VITE_API_URL ← api_url'
           puts "\nExamples:"
           puts '  belt frontend env dev'

data/lib/belt/cli/frontend_env_map.rb

@@ -21,7 +21,9 @@ module Belt
     class FrontendEnvMap
       MAP_CANDIDATES = [
         File.join('frontend', 'env.yml'),
-        File.join('.belt', 'frontend_env.yml')
+        File.join('frontend', 'env.yaml'),
+        File.join('.belt', 'frontend_env.yml'),
+        File.join('.belt', 'frontend_env.yaml')
       ].freeze
 
       DEFAULT_MAP = { 'VITE_API_URL' => 'api_url' }.freeze

data/lib/belt/cli/lambda_config_command.rb

@@ -146,8 +146,13 @@ module Belt
         return {} unless Dir.exist?(config_dir)
 
         configs = {}
-        Dir.glob(File.join(config_dir, '*.yml')).each do |file|
-          name = File.basename(file, '.yml')
+        files = Dir.glob(File.join(config_dir, '*.{yml,yaml}'))
+        # Sort so .yml comes before .yaml for the same basename (yml wins if both exist)
+        files.sort_by! { |f| [File.basename(f).sub(/\.ya?ml\z/, ''), f.end_with?('.yml') ? 0 : 1] }
+        files.each do |file|
+          name = File.basename(file).sub(/\.ya?ml\z/, '')
+          next if configs.key?(name) # .yml takes precedence
+
           raw = YAML.safe_load_file(file, aliases: true) || {}
           configs[name] = resolve_environment(raw, environment)
         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