belt 0.3.2 → 0.3.4

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

data/lib/belt/docs/structure.md

@@ -0,0 +1,93 @@
+# 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)
+├── 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.
+
+## 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/route_dsl.rb

@@ -428,6 +428,23 @@ module Belt
         end
       end
 
+      # Rails-like `root` — defines a GET / route.
+      #
+      # Examples:
+      #   root to: "welcome#show"
+      #   root action: :show, controller: :welcome
+      #   root "pages#home"
+      def root(options_or_target = nil, **options)
+        if options_or_target.is_a?(String)
+          options[:to] = options_or_target
+        elsif options_or_target.is_a?(Hash)
+          options = options_or_target.merge(options)
+        end
+        options[:auth] ||= :none
+        route_options = apply_scope_to_route(options)
+        @gateway.send(:get, '/', route_options)
+      end
+
       def resources(name, options = {}, &)
         options = apply_scope_options(options)
 

data/lib/belt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.3.2'
+  VERSION = '0.3.4'
 end

data/lib/templates/new_app/AGENTS.md.erb

@@ -2,6 +2,18 @@
 
 This file explains the project structure, tooling, and conventions for AI agents working in this codebase.
 
+## Quick Reference
+
+```bash
+belt explain <topic>      # Get documentation on any Belt concept
+belt explain routing      # How routes work
+belt explain controllers  # Controller patterns and response helpers
+belt explain models       # ActiveItem (DynamoDB ORM)
+belt explain deployment   # Deploy lifecycle
+belt explain generators   # Scaffolding new resources
+belt explain --help       # List all available topics
+```
+
 ## Stack
 
 - **Belt** — CLI and runtime framework (like Rails for serverless). Provides Lambda handler, action router, controller base class, and CLI tooling.
@@ -33,6 +45,79 @@ This file explains the project structure, tooling, and conventions for AI agents
 └── AGENTS.md                           # This file
 ```
 
+## Common Tasks (Copy-Paste Recipes)
+
+### Add a new REST resource
+
+```bash
+belt generate resource order item_id:string quantity:number total:number status:string
+belt setup tables <env>
+belt apply <env>
+```
+
+This creates: model, controller (with all CRUD actions), route entry, and DynamoDB schema.
+
+### Add a model only (no API endpoint)
+
+```bash
+belt generate model audit_log user_id:string action:string resource:string
+belt setup tables <env>
+belt apply <env>
+```
+
+### Add a controller only (route already exists)
+
+```bash
+belt generate controller admin/reports
+```
+
+### Add a new route to an existing resource
+
+Edit `config/routes.rb`:
+```ruby
+# Inside the gateway block, add:
+get "posts/search", controller: :posts, action: :search
+```
+
+Then add the `search` action to `lambda/controllers/<%= @app_name %>/posts_controller.rb`.
+
+### Deploy changes
+
+```bash
+belt deploy <env>          # full deploy (init → plan → apply)
+belt deploy <env> --auto   # skip confirmation
+```
+
+### Inspect current routes
+
+```bash
+belt routes                # human-readable table
+belt routes -f json        # machine-readable
+belt routes -g posts       # filter by pattern
+```
+
+### Open a console
+
+```bash
+belt c <env>               # interactive Ruby session with app loaded
+belt c <env> --run "Post.count"  # one-liner
+```
+
+### Check system health
+
+```bash
+belt doctor                # verify AWS creds, Terraform, Ruby, etc.
+```
+
+### Add a new environment
+
+```bash
+belt generate environment staging
+belt setup state           # if no state bucket exists
+belt setup tables staging
+belt deploy staging
+```
+
 ## Belt CLI Commands
 
 ```bash
@@ -43,12 +128,17 @@ belt generate controller <name>                        # Generate controller onl
 belt generate environment <env_name>                   # Generate Terraform environment directory
 belt setup state                                       # Create/select S3 state bucket
 belt setup tables <env>                                # Generate DynamoDB table definitions from schema
+belt explain <topic>                                   # Show documentation for a concept
 belt init <env>                                        # terraform init
 belt plan <env>                                        # terraform plan
 belt apply <env>                                       # terraform apply
 belt destroy <env>                                     # terraform destroy
-belt destroy environment <env>                         # same (mirrors generate environment)
 belt output <env>                                      # terraform output
+belt routes [-g PATTERN] [-f json]                     # Show route definitions
+belt contracts [-g PATTERN] [-f json]                  # Show API contracts
+belt console <env>                                     # Interactive Ruby console
+belt logs <lambda> [-f] [-s 5m] [-e env]               # View Lambda logs
+belt doctor                                            # Check dependencies
 ```
 
 ## How Routing Works
@@ -62,12 +152,12 @@ belt output <env>                                      # terraform output
    end
    ```
 
-2. Conveyor Belt creates an API Gateway where the gateway name becomes a base path mapping. URLs look like:
+2. Conveyor Belt creates API Gateway routes. URLs look like:
    ```
    https://api.<env>.example.com/<%= @app_name %>/things
    ```
 
-3. The Lambda entry point (`lambda/<%= @app_name %>.rb`) uses `Belt::ActionRouter` to dispatch requests to controllers based on the route manifest in `lambda/lib/routes/`.
+3. The Lambda entry point (`lambda/<%= @app_name %>.rb`) uses `Belt::ActionRouter` to dispatch requests to controllers based on the route manifest.
 
 4. `resources :things` generates: `GET /things`, `POST /things`, `GET /things/:id`, `PUT /things/:id`, `DELETE /things/:id`. **PUT, not PATCH.**
 
@@ -83,7 +173,13 @@ end
 
 Table names resolve as `{APP_NAME}-{ENVIRONMENT}-{pluralized_model}` (e.g., `<%= @app_name %>-wups-posts`).
 
-Key ActiveItem methods: `create!`, `find`, `where`, `update`, `destroy`, `all`, `count`, `exists?`.
+Key methods: `create!`, `find`, `find_by`, `where`, `update`, `destroy`, `all`, `count`, `exists?`.
+
+Querying with indexes:
+```ruby
+Post.where(user_id: "u-123", index: "UserIndex")
+Post.find_by(status: "active", index: "StatusIndex")
+```
 
 ## How Controllers Work
 
@@ -93,24 +189,35 @@ Controllers inherit from `BeltController::Base`:
 module <%= @module_name %>Controllers
   class ThingsController < ApplicationController
     def index
-      items = Thing.all
-      success_response(things: items.map(&:to_h))
+      @things = Thing.all  # implicit JSON: { "things": [...] }
     end
 
     def show
-      item = Thing.find(params[:id])
-      success_response(thing: item.to_h)
+      @thing = Thing.find(params[:id])  # implicit JSON: { "thing": {...} }
     end
 
     def create
-      item = Thing.create!(params.slice(:title, :content))
-      success_response(thing: item.to_h, status: 201)
+      attrs = params.require(:thing).permit(:title, :content).to_h
+      @thing = Thing.create!(attrs)
+      response_status :created  # 201 + implicit JSON
+    end
+
+    def destroy
+      Thing.find(params[:id]).destroy
+      head :no_content  # 204
     end
   end
 end
 ```
 
-`params` contains merged path parameters and parsed JSON body. Use `success_response` and `error_response` helpers.
+**Key patterns:**
+- `params` = merged path parameters + parsed JSON body
+- Instance variables auto-serialize to JSON response
+- `response_status :created` sets status without explicit response
+- `head :no_content` for empty responses
+- `success_response(data, status)` for explicit control
+- `error_response(message, status)` for error responses
+- `rescue_from` for exception handling
 
 ## Deployment Flow
 
@@ -119,16 +226,30 @@ export AWS_PROFILE=<your_profile>
 belt setup state                  # One-time: create S3 state bucket
 belt generate environment <env>   # One-time: scaffold Terraform configs
 belt setup tables <env>           # Generate DynamoDB table resources
-belt init <env>                   # Initialize Terraform
-belt apply <env>                  # Deploy everything
+belt deploy <env>                 # Deploy everything (init → plan → apply)
 ```
 
-## Adding a New Resource
+## Key Differences from Rails
+
+| Rails | Belt |
+|-------|------|
+| PostgreSQL / MySQL | DynamoDB (NoSQL) |
+| ActiveRecord | ActiveItem |
+| `PATCH` for updates | `PUT` for updates |
+| `rails server` | Deployed to AWS Lambda |
+| `rails routes` | `belt routes` |
+| `rails console` | `belt console <env>` |
+| `config/routes.rb` → URL paths | `config/routes.rb` → URL paths + infrastructure |
+| Migrations | `belt setup tables <env>` |
+| `has_many` / `belongs_to` | Manual (no joins in DynamoDB) |
+| Template rendering | JSON responses (default) |
+
+## Troubleshooting
 
 ```bash
-belt generate resource comment body:text author:string post_id:string
-belt setup tables <env>
-belt apply <env>
+belt doctor                        # Check all dependencies
+belt explain <topic>               # Documentation for any concept
+belt routes -f json                # Verify route configuration
+belt logs <lambda> -e <env> -s 5m  # Check recent Lambda logs
+belt c <env> --run "Post.count"    # Verify data access
 ```
-
-This creates the model, controller, updates routes + schema, generates the DynamoDB table definition, and deploys.

data/lib/templates/new_app/config/routes.rb.erb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
 Belt.application.routes.draw do
   # Creates an API Gateway named "api" with a default Lambda function of the same name.
   # Use `function :other_name do ... end` inside to route specific paths to additional Lambdas.
   gateway :api do
-    # Public stack-check / welcome (HTML for browsers, JSON for the SPA shell)
-    get "/", action: :show, controller: :welcome, auth: :none
+    # Public stack-check / welcome (HTML for browsers, JSON for the SPA shell).
+    # This route is auto-injected by Belt if omitted, but keeping it explicit is clearer.
+    root to: 'welcome#show'
     # resources :posts
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.4
 platform: ruby
 authors:
 - Stowzilla
@@ -116,6 +116,7 @@ files:
 - lib/belt/cli/env_resolver.rb
 - lib/belt/cli/environment_command.rb
 - lib/belt/cli/environment_config.rb
+- lib/belt/cli/explain_command.rb
 - lib/belt/cli/frontend_command.rb
 - lib/belt/cli/frontend_deploy_command.rb
 - lib/belt/cli/frontend_env_command.rb
@@ -140,6 +141,17 @@ files:
 - lib/belt/cli/views_command.rb
 - lib/belt/configuration.rb
 - lib/belt/controllers/welcome_controller.rb
+- lib/belt/docs/backups.md
+- lib/belt/docs/console.md
+- lib/belt/docs/controllers.md
+- lib/belt/docs/deployment.md
+- lib/belt/docs/generators.md
+- lib/belt/docs/lambda_handler.md
+- lib/belt/docs/models.md
+- lib/belt/docs/observability.md
+- lib/belt/docs/plugins.md
+- lib/belt/docs/routing.md
+- lib/belt/docs/structure.md
 - lib/belt/helpers/cors_origin.rb
 - lib/belt/helpers/error_logging.rb
 - lib/belt/helpers/response.rb