belt 0.0.6 → 0.1.0

data/lib/templates/frontend_infra/frontend.tf.erb

@@ -0,0 +1,159 @@
+# Auto-generated by Belt — frontend hosting infrastructure
+# Re-run `belt setup frontend <%= @env %>` to regenerate
+
+resource "random_string" "frontend_suffix" {
+  length  = 8
+  special = false
+  upper   = false
+}
+
+# S3 bucket for frontend static assets
+resource "aws_s3_bucket" "frontend" {
+  bucket = "<%= @app_name %>-frontend-${var.environment}-${random_string.frontend_suffix.result}"
+
+  lifecycle {
+    ignore_changes = [bucket]
+  }
+}
+
+resource "aws_s3_bucket_public_access_block" "frontend" {
+  bucket = aws_s3_bucket.frontend.id
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "frontend" {
+  bucket = aws_s3_bucket.frontend.id
+
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "AES256"
+    }
+    bucket_key_enabled = true
+  }
+}
+
+resource "aws_s3_bucket_website_configuration" "frontend" {
+  bucket = aws_s3_bucket.frontend.id
+
+  index_document {
+    suffix = "index.html"
+  }
+
+  error_document {
+    key = "index.html"
+  }
+}
+
+# CloudFront OAC — restricts S3 access to CloudFront only
+resource "aws_cloudfront_origin_access_control" "frontend" {
+  name                              = "<%= @app_name %>-${var.environment}-frontend-oac"
+  description                       = "OAC for frontend bucket"
+  origin_access_control_origin_type = "s3"
+  signing_behavior                  = "always"
+  signing_protocol                  = "sigv4"
+}
+
+# CloudFront distribution
+resource "aws_cloudfront_distribution" "frontend" {
+  origin {
+    domain_name              = aws_s3_bucket.frontend.bucket_regional_domain_name
+    origin_id                = "S3-${aws_s3_bucket.frontend.id}"
+    origin_access_control_id = aws_cloudfront_origin_access_control.frontend.id
+  }
+
+  enabled             = true
+  is_ipv6_enabled     = true
+  default_root_object = "index.html"
+
+  default_cache_behavior {
+    allowed_methods        = ["GET", "HEAD", "OPTIONS"]
+    cached_methods         = ["GET", "HEAD"]
+    target_origin_id       = "S3-${aws_s3_bucket.frontend.id}"
+    compress               = true
+    viewer_protocol_policy = "redirect-to-https"
+
+    forwarded_values {
+      query_string = false
+      cookies {
+        forward = "none"
+      }
+    }
+  }
+
+  # SPA routing — serve index.html for all 404/403 paths
+  custom_error_response {
+    error_code         = 404
+    response_code      = 200
+    response_page_path = "/index.html"
+  }
+
+  custom_error_response {
+    error_code         = 403
+    response_code      = 200
+    response_page_path = "/index.html"
+  }
+
+  restrictions {
+    geo_restriction {
+      restriction_type = "none"
+    }
+  }
+
+  viewer_certificate {
+    cloudfront_default_certificate = true
+  }
+
+  tags = {
+    Name        = "<%= @app_name %>-${var.environment}-frontend"
+    Environment = var.environment
+    ManagedBy   = "Terraform"
+  }
+}
+
+# S3 bucket policy — allow CloudFront OAC access only
+resource "aws_s3_bucket_policy" "frontend" {
+  bucket = aws_s3_bucket.frontend.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid    = "AllowCloudFrontServicePrincipal"
+        Effect = "Allow"
+        Principal = {
+          Service = "cloudfront.amazonaws.com"
+        }
+        Action   = "s3:GetObject"
+        Resource = "${aws_s3_bucket.frontend.arn}/*"
+        Condition = {
+          StringEquals = {
+            "AWS:SourceArn" = aws_cloudfront_distribution.frontend.arn
+          }
+        }
+      }
+    ]
+  })
+
+  depends_on = [aws_s3_bucket_public_access_block.frontend]
+}
+
+# Outputs for belt deploy
+output "frontend_bucket_name" {
+  value = aws_s3_bucket.frontend.id
+}
+
+output "frontend_distribution_id" {
+  value = aws_cloudfront_distribution.frontend.id
+}
+
+output "frontend_url" {
+  value = "https://${aws_cloudfront_distribution.frontend.domain_name}"
+}
+
+output "api_url" {
+  value = values(dispatcher.main.api_gateway_urls)[0]
+}

data/lib/templates/generate/controller.rb.erb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'application_controller'
+require_relative '../../models/<%= @singular_name %>'
+
+module <%= @module_name %>Controllers
+  class <%= @class_name %>sController < ApplicationController
+    # GET /<%= @resource_name %>
+    def index
+      <%= @resource_name %> = <%= @class_name %>.all
+      success_response(<%= @resource_name %>: <%= @resource_name %>.map(&:to_h))
+    end
+
+    # POST /<%= @resource_name %>
+    def create
+      <%= @singular_name %> = <%= @class_name %>.new(<%= @fields.map { |f| "#{f[:name]}: params[:#{f[:name]}]" }.join(', ') %>)
+
+      if <%= @singular_name %>.save
+        success_response(<%= @singular_name %>: <%= @singular_name %>.to_h)
+      else
+        error_response(<%= @singular_name %>.errors.full_messages.join(', '), 422)
+      end
+    end
+
+    # GET /<%= @resource_name %>/:<%= @singular_name %>_id
+    def show
+      <%= @singular_name %> = <%= @class_name %>.find(params[:<%= @singular_name %>_id])
+      return error_response('<%= @class_name %> not found', 404) unless <%= @singular_name %>
+
+      success_response(<%= @singular_name %>: <%= @singular_name %>.to_h)
+    end
+
+    # PUT /<%= @resource_name %>/:<%= @singular_name %>_id
+    def update
+      <%= @singular_name %> = <%= @class_name %>.find(params[:<%= @singular_name %>_id])
+      return error_response('<%= @class_name %> not found', 404) unless <%= @singular_name %>
+
+      attrs = {}
+<% @fields.each do |field| -%>
+      attrs[:<%= field[:name] %>] = params[:<%= field[:name] %>] if params.key?(:<%= field[:name] %>)
+<% end -%>
+
+      if <%= @singular_name %>.update(attrs)
+        success_response(<%= @singular_name %>: <%= @singular_name %>.to_h)
+      else
+        error_response(<%= @singular_name %>.errors.full_messages.join(', '), 422)
+      end
+    end
+
+    # DELETE /<%= @resource_name %>/:<%= @singular_name %>_id
+    def destroy
+      <%= @singular_name %> = <%= @class_name %>.find(params[:<%= @singular_name %>_id])
+      return error_response('<%= @class_name %> not found', 404) unless <%= @singular_name %>
+
+      <%= @singular_name %>.destroy
+      success_response(message: '<%= @class_name %> deleted')
+    end
+  end
+end

data/lib/templates/generate/model.rb.erb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class <%= @class_name %> < ApplicationRecord
+  include Concerns::Timestampable
+
+<% @fields.each do |field| -%>
+  attr_accessor :<%= field[:name] %>
+<% end -%>
+
+  def to_h
+    {
+      id: id,
+<% @fields.each do |field| -%>
+      <%= field[:name] %>: <%= field[:name] %>,
+<% end -%>
+      created_at: created_at,
+      updated_at: updated_at
+    }
+  end
+end

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

@@ -0,0 +1,130 @@
+# AGENTS.md — <%= @module_name %>
+
+This file explains the project structure, tooling, and conventions for AI agents working in this codebase.
+
+## Stack
+
+- **Belt** — CLI and runtime framework (like Rails for serverless). Provides Lambda handler, action router, controller base class, and CLI tooling.
+- **ActiveItem** — ActiveRecord-like ORM for DynamoDB. Models inherit from `ActiveItem::Base`.
+- **Dispatcher** — Terraform provider that reads a Ruby DSL (`routes.tf.rb`) and creates API Gateway + Lambda + IAM infrastructure.
+- **Lambda Loadout** — Lambda cold-start optimizer (auto-required by Belt).
+
+## Project Structure
+
+```
+<%= @app_name %>/
+├── lambda/
+│   ├── <%= @app_name %>.rb                          # Lambda entry point
+│   ├── controllers/<%= @app_name %>/                # Controllers (namespaced)
+│   │   └── application_controller.rb   # Base controller
+│   ├── models/                         # ActiveItem models
+│   │   ├── application_record.rb       # Base model
+│   │   └── concerns/                   # Shared model concerns
+│   ├── lib/routes/                     # Route manifests (auto-generated)
+│   └── Gemfile                         # Lambda-specific dependencies
+├── infrastructure/
+│   ├── routes.tf.rb                    # API routes (Dispatcher DSL)
+│   ├── schema.tf.rb                    # Model schema definitions
+│   └── <env>/                          # Per-environment Terraform configs
+├── Gemfile                             # Project-level dependencies
+└── AGENTS.md                           # This file
+```
+
+## Belt CLI Commands
+
+```bash
+belt new <app_name>                                    # Scaffold a new project
+belt generate resource <name> <field:type ...>         # Generate model + controller + routes
+belt generate model <name> <field:type ...>            # Generate model only
+belt generate controller <name>                        # Generate controller only
+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 init <env>                                        # terraform init
+belt plan <env>                                        # terraform plan
+belt apply <env>                                       # terraform apply
+belt destroy <env>                                     # terraform destroy
+belt output <env>                                      # terraform output
+```
+
+## How Routing Works
+
+1. `infrastructure/routes.tf.rb` defines routes using a DSL:
+   ```ruby
+   TerraDispatch.routes.draw do
+     namespace :<%= @app_name %> do
+       resources :things, tables: [:things]
+     end
+   end
+   ```
+
+2. Dispatcher creates an API Gateway where the namespace becomes a base path mapping. 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/`.
+
+4. `resources :things` generates: `GET /things`, `POST /things`, `GET /things/:id`, `PUT /things/:id`, `DELETE /things/:id`. **PUT, not PATCH.**
+
+## How Models Work
+
+Models use ActiveItem (DynamoDB ORM):
+
+```ruby
+class Post < ApplicationRecord
+  attr_accessor :title, :content, :status
+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?`.
+
+## How Controllers Work
+
+Controllers inherit from `BeltController::Base`:
+
+```ruby
+module <%= @module_name %>Controllers
+  class ThingsController < ApplicationController
+    def index
+      items = Thing.all
+      success_response(things: items.map(&:to_h))
+    end
+
+    def show
+      item = Thing.find(params[:id])
+      success_response(thing: item.to_h)
+    end
+
+    def create
+      item = Thing.create!(params.slice(:title, :content))
+      success_response(thing: item.to_h, status: 201)
+    end
+  end
+end
+```
+
+`params` contains merged path parameters and parsed JSON body. Use `success_response` and `error_response` helpers.
+
+## Deployment Flow
+
+```bash
+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
+```
+
+## Adding a New Resource
+
+```bash
+belt generate resource comment body:text author:string post_id:string
+belt setup tables <env>
+belt apply <env>
+```
+
+This creates the model, controller, updates routes + schema, generates the DynamoDB table definition, and deploys.

data/lib/templates/new_app/Gemfile.erb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'activeitem'
+gem 'belt'

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

@@ -0,0 +1,25 @@
+# <%= @module_name %>
+
+A serverless application built with [Belt](https://github.com/stowzilla/belt) and [ActiveItem](https://github.com/stowzilla/activeitem).
+
+## Structure
+
+```
+├── infrastructure/
+│   ├── routes.tf.rb        # API route definitions
+│   └── schema.tf.rb        # Model schema definitions
+└── lambda/
+    ├── api.rb              # Lambda entry point
+    ├── controllers/<%= @app_name %>/  # Controllers
+    ├── models/             # ActiveItem models
+    └── lib/routes/         # Route manifest
+```
+
+## Development
+
+```bash
+bundle install
+
+# Deploy
+cd infrastructure && terraform apply
+```

data/lib/templates/new_app/gitignore.erb

@@ -0,0 +1,14 @@
+/.bundle
+/vendor/bundle
+*.gem
+Gemfile.lock
+
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.backup
+.terraform.lock.hcl
+
+# Lambda build artifacts
+/lambda/vendor/
+/lambda/.bundle/

data/lib/templates/new_app/infrastructure/routes.tf.rb.erb

@@ -0,0 +1,5 @@
+TerraDispatch.routes.draw do
+  namespace :<%= @app_name %> do
+    # resources :posts
+  end
+end

data/lib/templates/new_app/infrastructure/schema.tf.rb.erb

@@ -0,0 +1,9 @@
+TerraDispatch.schema.draw do
+  # model :post do
+  #   field :title, type: :string, required: true
+  #   field :slug, type: :string, required: true
+  #   field :content, type: :string
+  #   field :status, type: :string, enum: %w[draft published]
+  #   field :published_at, type: :string
+  # end
+end

data/lib/templates/new_app/lambda/Gemfile.erb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'activeitem'
+gem 'belt'
+gem 'lambda_loadout'

data/lib/templates/new_app/lambda/api.rb.erb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'belt'
+require 'activeitem'
+
+include Belt::LambdaHandler
+
+ActiveItem.configure do |config|
+  config.table_prefix = ENV['APP_NAME']
+  config.environment = ENV['ENVIRONMENT']
+end
+
+require_relative 'lib/routes/<%= @app_name %>_routes'
+<% @resources&.each do |r| -%>
+require_relative 'controllers/<%= @app_name %>/<%= r %>_controller'
+<% end -%>
+
+ROUTER = Belt::ActionRouter.new(routes: Routes::<%= @module_name.upcase %>, namespace: '<%= @app_name %>')
+
+def execute(path:, body:, event:)
+  ROUTER.route(event: event, body: body)
+end

data/lib/templates/new_app/lambda/controllers/application_controller.rb.erb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module <%= @module_name %>Controllers
+  class ApplicationController < BeltController::Base
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Routes
+  <%= @module_name.upcase %> = [
+    # { verb: 'GET', path: '/posts', controller: 'posts', action: 'index' },
+    # { verb: 'POST', path: '/posts', controller: 'posts', action: 'create' },
+    # { verb: 'GET', path: '/posts/{id}', controller: 'posts', action: 'show' },
+    # { verb: 'PUT', path: '/posts/{id}', controller: 'posts', action: 'update' },
+    # { verb: 'DELETE', path: '/posts/{id}', controller: 'posts', action: 'destroy' }
+  ].freeze
+end

data/lib/templates/new_app/lambda/models/application_record.rb.erb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'activeitem'
+
+class ApplicationRecord < ActiveItem::Base
+end

data/lib/templates/new_app/lambda/models/concerns/timestampable.rb.erb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Concerns
+  module Timestampable
+    def self.included(base)
+      base.attr_accessor :created_at, :updated_at
+      base.set_callback :create, :before, :set_timestamps
+      base.set_callback :update, :before, :set_updated_at
+    end
+
+    private
+
+    def set_timestamps
+      now = Time.now.utc.iso8601
+      self.created_at ||= now
+      self.updated_at = now
+    end
+
+    def set_updated_at
+      self.updated_at = Time.now.utc.iso8601
+    end
+  end
+end

data/lib/templates/views/Edit.jsx.erb

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react'
+import { useParams, useNavigate } from 'react-router-dom'
+import { apiClient } from '../../lib/apiClient'
+import <%= @class_name %>Form from './<%= @class_name %>Form'
+
+export default function <%= @class_name %>Edit() {
+  const { id } = useParams()
+  const navigate = useNavigate()
+  const [<%= @singular_name %>, set<%= @class_name %>] = useState(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    apiClient(`/<%= @resource_name %>/${id}`)
+      .then(data => set<%= @class_name %>(data.<%= @singular_name %>))
+      .finally(() => setLoading(false))
+  }, [id])
+
+  async function handleSubmit(attrs) {
+    try {
+      await apiClient(`/<%= @resource_name %>/${id}`, { method: 'PUT', body: attrs })
+      navigate(`/<%= @resource_name %>/${id}`)
+    } catch (e) {
+      setError(e.message)
+    }
+  }
+
+  if (loading) return <p>Loading...</p>
+  if (!<%= @singular_name %>) return <p><%= @class_name %> not found.</p>
+
+  return (
+    <main style={{ padding: '2rem', maxWidth: '800px', margin: '0 auto' }}>
+      <h1>Edit <%= @class_name %></h1>
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+      <<%= @class_name %>Form initialValues={<%= @singular_name %>} onSubmit={handleSubmit} submitLabel="Update" />
+    </main>
+  )
+}

data/lib/templates/views/Form.jsx.erb

@@ -0,0 +1,34 @@
+import { useState } from 'react'
+import { Link } from 'react-router-dom'
+
+export default function <%= @class_name %>Form({ initialValues = {}, onSubmit, submitLabel = 'Create' }) {
+<% @fields.each do |field| -%>
+  const [<%= field[:name] %>, set<%= field[:name].split('_').map(&:capitalize).join %>] = useState(initialValues.<%= field[:name] %> || '')
+<% end -%>
+
+  function handleSubmit(e) {
+    e.preventDefault()
+    onSubmit({ <%= @fields.map { |f| f[:name] }.join(', ') %> })
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+<% @fields.each do |field| -%>
+      <div style={{ marginBottom: '1rem' }}>
+        <label style={{ display: 'block', marginBottom: '0.25rem' }}><%= field[:name].split('_').map(&:capitalize).join(' ') %></label>
+<% if field[:type] == 'text' -%>
+        <textarea value={<%= field[:name] %>} onChange={e => set<%= field[:name].split('_').map(&:capitalize).join %>(e.target.value)}
+          rows={6} style={{ width: '100%' }} />
+<% else -%>
+        <input type="text" value={<%= field[:name] %>} onChange={e => set<%= field[:name].split('_').map(&:capitalize).join %>(e.target.value)}
+          style={{ width: '100%', padding: '0.5rem' }} />
+<% end -%>
+      </div>
+<% end -%>
+
+      <button type="submit">{submitLabel}</button>
+      {' '}
+      <Link to="/<%= @resource_name %>">Cancel</Link>
+    </form>
+  )
+}

data/lib/templates/views/Index.jsx.erb

@@ -0,0 +1,39 @@
+import { useEffect, useState } from 'react'
+import { Link } from 'react-router-dom'
+import { apiClient } from '../../lib/apiClient'
+
+export default function <%= @class_name %>sIndex() {
+  const [<%= @resource_name %>, set<%= @class_name %>s] = useState([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    apiClient('/<%= @resource_name %>')
+      .then(data => set<%= @class_name %>s(data.<%= @resource_name %> || []))
+      .finally(() => setLoading(false))
+  }, [])
+
+  if (loading) return <p>Loading...</p>
+
+  return (
+    <main style={{ padding: '2rem', maxWidth: '800px', margin: '0 auto' }}>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+        <h1><%= @class_name %>s</h1>
+        <Link to="/<%= @resource_name %>/new">New <%= @class_name %></Link>
+      </div>
+
+      {<%= @resource_name %>.length === 0 ? (
+        <p>No <%= @resource_name %> yet.</p>
+      ) : (
+        <ul style={{ listStyle: 'none', padding: 0 }}>
+          {<%= @resource_name %>.map(<%= @singular_name %> => (
+            <li key={<%= @singular_name %>.id} style={{ padding: '0.5rem 0', borderBottom: '1px solid #eee' }}>
+              <Link to={`/<%= @resource_name %>/${<%= @singular_name %>.id}`}>
+                {<%= @singular_name %>.<%= @fields.first&.dig(:name) || 'id' %>}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      )}
+    </main>
+  )
+}

data/lib/templates/views/New.jsx.erb

@@ -0,0 +1,26 @@
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { apiClient } from '../../lib/apiClient'
+import <%= @class_name %>Form from './<%= @class_name %>Form'
+
+export default function <%= @class_name %>New() {
+  const navigate = useNavigate()
+  const [error, setError] = useState(null)
+
+  async function handleSubmit(attrs) {
+    try {
+      const data = await apiClient('/<%= @resource_name %>', { method: 'POST', body: attrs })
+      navigate(`/<%= @resource_name %>/${data.<%= @singular_name %>.id}`)
+    } catch (e) {
+      setError(e.message)
+    }
+  }
+
+  return (
+    <main style={{ padding: '2rem', maxWidth: '800px', margin: '0 auto' }}>
+      <h1>New <%= @class_name %></h1>
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+      <<%= @class_name %>Form onSubmit={handleSubmit} />
+    </main>
+  )
+}