belt 0.2.17 → 0.3.14

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

data/lib/belt/docs/structure.md

@@ -0,0 +1,96 @@
+# Project Structure
+
+A Belt application follows a conventional directory layout. Understanding
+this structure helps you navigate and extend the app effectively.
+
+## Standard Layout
+
+```
+my-app/
+├── lambda/                        # Application code (deployed to Lambda)
+│   ├── api.rb                     # Lambda entry point
+│   ├── config/
+│   │   └── environment.rb         # App boot file (models, libs, AWS setup)
+│   ├── controllers/
+│   │   ├── application_controller.rb
+│   │   └── my_app/               # Namespaced controllers
+│   │       ├── posts_controller.rb
+│   │       └── admin/
+│   │           └── users_controller.rb
+│   ├── models/
+│   │   ├── application_record.rb  # Base model class
+│   │   ├── post.rb
+│   │   └── concerns/             # Shared model behavior
+│   ├── lib/
+│   │   └── routes/               # Auto-generated route manifests
+│   │       └── api_routes.rb
+│   └── Gemfile                    # Lambda-specific dependencies
+├── config/
+│   ├── routes.rb                  # Route definitions (DSL)
+│   ├── contracts.rb               # API request/response contracts
+│   └── lambda/                    # Per-lambda configuration
+│       └── api.yml                # Timeout, memory, env vars
+├── infrastructure/
+│   ├── modules/                   # Shared Terraform modules
+│   │   └── main/
+│   ├── schema.tf.rb               # DynamoDB table schema (Ruby DSL)
+│   ├── dev01/                     # Per-environment Terraform
+│   │   ├── main.tf
+│   │   ├── variables.tf
+│   │   ├── terraform.tfvars
+│   │   ├── backend.tf
+│   │   └── outputs.tf
+│   └── prod/
+│       └── ...
+├── frontend/                      # Optional frontend (React/Vue/Svelte)
+├── config/frontends.yml           # Optional: multiple named frontends
+├── Gemfile                        # Project-level dependencies (CLI, dev tools)
+├── Rakefile                       # Rake tasks
+├── AGENTS.md                      # AI agent guide
+└── .gitignore
+```
+
+## Key Files
+
+### `lambda/api.rb` — Lambda Entry Point
+
+The file AWS Lambda invokes. Includes `Belt::LambdaHandler` and defines `execute`.
+
+### `lambda/config/environment.rb` — Boot File
+
+Loaded by both Lambda and `belt console`. Sets up AWS clients, requires models,
+configures the app. Everything your app needs to run.
+
+### `config/routes.rb` — Route Definitions
+
+The Ruby DSL that defines your API. Read by both the Conveyor Belt Terraform
+provider (for infrastructure) and `belt routes` (for manifests).
+
+### `config/lambda/api.yml` — Lambda Config
+
+Per-function settings: handler path, runtime, timeout, memory, environment
+variables, layers, triggers.
+
+### `infrastructure/schema.tf.rb` — Table Schema
+
+DynamoDB table definitions in Ruby DSL. Used by `belt setup tables` to generate
+Terraform resources.
+
+## Conventions
+
+- **Controller namespacing**: Controllers live under `lambda/controllers/<app_name>/`
+  to avoid conflicts across modules.
+- **Route manifests**: Generated files in `lambda/lib/routes/` — don't edit manually.
+  Regenerate with `belt routes --namespace <name>`.
+- **Two Gemfiles**: Project root Gemfile is for dev tools (belt CLI, rspec).
+  `lambda/Gemfile` is what gets packaged into the Lambda.
+- **Config over code**: Lambda configuration (timeout, memory, env vars) goes in
+  YAML files, not hardcoded in Terraform.
+- **Frontends**: Default directory is `frontend/`. Multiple SPAs (customer + ops,
+  etc.) are declared in `config/frontends.yml`. See `belt explain frontend`.
+
+## See Also
+
+- `belt explain routing` — how routes.rb maps to infrastructure
+- `belt explain controllers` — controller conventions
+- `belt explain deployment` — how this structure gets deployed

data/lib/belt/inflector.rb

@@ -42,6 +42,14 @@ module Belt
       word.to_s.split('_').map(&:capitalize).join
     end
 
+    # "conversation_id" → "conversationId"
+    def camelize_lower(word)
+      parts = word.to_s.split('_')
+      return word if parts.empty?
+
+      parts.first + parts[1..].map(&:capitalize).join
+    end
+
     # "BlogPost" → "blog_post"
     def underscore(word)
       word.to_s