belt 0.2.10 → 0.2.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a550043d0d16c901e656de4a9d89a0f473d77778121e2b27fb8791f3edf74d4
-  data.tar.gz: f9404b6e69d725650ee612af06b96917886d2856fca14955bb99cb9555811dcd
+  metadata.gz: 10e92ad2ab3fe79f48f07cca6495ce8b9ccdad09755c7a6517e651deadcc118d
+  data.tar.gz: 6cd8a8ee7ad1023fb949183122c3aca465c216cf91d175e8f9395e8f413ad880
 SHA512:
-  metadata.gz: e719bed32a829bf952c22885d63a1415ea292c3b1770a7f7bdb398ef874a5182a1b8208654e2672d6d7fcccbb4b2e9f24a82186708ed3982d9ca7ec94d9bedbf
-  data.tar.gz: 32fa436e2a97b5d3597af8d2afcfb8657c5de91f12a01b551d8368be97a80fdfd544e5b6b711a930ff741c1e8228d393088893700f13c719b454b59e01c3d6a0
+  metadata.gz: cb7d5dacc2b90e0ae7c4dd9853d76ea42ef8d6e324d30edd91c5fbe6d934affafd2c3bee6fb752960d9c8462a59663244ae448797ab7e57de7ad05c50afa627f
+  data.tar.gz: fd7f4ff9af68c36b34c02c2f4af2c42649f0e9494ac192eaaefeae3111e0da81ced4091b88510b82ac183fefaadfd0677e4d34f270e16a7dcf389b54259e8c52

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.2.12
+
+### Rename: `routes.tf.rb` → `routes.rb`, `schema.tf.rb` → `contracts.rb`
+
+The `.tf.rb` extension was a vestige of when these files produced HCL output — that hasn't been the case for a while. New apps now get clean, Rails-familiar names:
+
+- `config/routes.rb` — API route definitions
+- `config/contracts.rb` — API request/response contracts
+
+**Backward compatible:** All detection helpers (`Belt.root`, `Belt.routes_file`, `Belt.contracts_file`, `find_routes_file_path`, `find_contracts_file_path`) check new names first, then fall back to `*.tf.rb` and `infrastructure/` paths. Existing apps continue working without changes.
+
+### New command: `belt contracts`
+
+Dedicated CLI command for inspecting API contracts, separate from `belt routes`:
+
+```bash
+belt contracts                    # Human-readable table of request/response models
+belt contracts -f json            # JSON output (for tooling/CI)
+belt contracts -g post            # Filter by pattern
+belt contracts --file path.rb     # Explicit file override
+```
+
+Previously, contracts were only accessible as a side-effect of `belt routes -f json --schema <file>`. Now they have their own first-class command. `belt routes -f json` continues to include models for backward compatibility.
+
+### Other changes
+
+- `Belt.schema_file` is now an alias for `Belt.contracts_file`
+- `find_schema_file_path` is now an alias for `find_contracts_file_path`
+- Module template updated: `source` points to `config/routes.rb`
+- All scaffold/generator help text and templates reference new filenames
+
+## Unreleased
+
+## 0.2.11
+
+### Security hardening
+
+- **CORS origin validation**: format validation (scheme required, no paths/queries/fragments), length limit (253 chars) to prevent ReDoS, restrict wildcard matching to valid subdomain chars `[a-z0-9-]`.
+- **Security headers** on all responses: `X-Content-Type-Options: nosniff`, `Vary: Origin`; HTML responses also get `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`.
+- **Path traversal protection** in `ActionRouter`: strict regex for controller names, reject `..` sequences / absolute paths / backslashes, `realpath` validation in `resolve_from_paths`.
+- **Request body size limit** (10 MB): returns 413 for oversized bodies; proper 400 for invalid JSON.
+
+### Safe `belt destroy environment`
+
+Previously `belt destroy environment <name>` immediately deleted the infrastructure directory with no checks — leaving orphaned AWS resources.
+
+Now the command:
+1. Checks if Terraform state exists (local `.terraform` dir or remote state)
+2. If state found, prompts user to run `terraform destroy` first
+3. Requires explicit confirmation before deleting files
+4. Supports `--force` (skip prompts) and `--skip-terraform` flags
+
+### Environment generator state bucket fix
+
+The environment generator was writing `belt-terraform-state` as the backend bucket name, missing the account-ID suffix. Now resolves via sibling `backend.tf`, STS `get-caller-identity`, or placeholder (for later `belt setup state` patch).
+
+### Contributing & plugins
+
+- README: **Plugins** and **Contributing** sections — how to contribute to belt, how plugins register via `GeneratorRegistry`, layout used by `belt-messaging` / `belt-pay`, generator checklist for humans and agents.
+- **`belt plugin new <name>`** — scaffold a new plugin gem (gemspec, `Belt::<Name>` module, generator stub, RSpec, README, AGENTS.md), similar to `rails plugin new`.
+- **`AGENTS.md`** at the belt gem root — agent-oriented map of core layout, CLI, and the plugin/GeneratorRegistry contract (complements README).
+- Plugin scaffold includes **`AGENTS.md`** so new plugins match the agent guidance pattern already used by `belt new` apps.
+
 ## 0.2.10
 
 ### Quiet `belt new` (with optional verbose)

data/README.md

@@ -575,6 +575,175 @@ These are set via Terraform variables in each environment's `terraform.tfvars`.
 
 The backup phase reads table names from Terraform outputs. On a brand-new environment that has never been deployed, there are no outputs yet — Belt will warn and skip the backup phase gracefully. After the first successful deploy, backups run normally on subsequent deploys.
 
+## Plugins
+
+Belt is designed to stay lean. Optional capabilities ship as **separate gems** that plug into the CLI and runtime the same way Rails engines and generators do.
+
+### Official / example plugins
+
+| Gem | Purpose | Status |
+|-----|---------|--------|
+| [`belt-messaging`](https://github.com/stowzilla/belt-messaging) | Two-way SMS via AWS End User Messaging (Pinpoint) | Early (not production-hardened) |
+| [`belt-pay`](https://github.com/stowzilla/belt-pay) | Stripe payments & subscriptions | Early (not production-hardened) |
+
+Install a plugin in a Belt app:
+
+```ruby
+# Gemfile
+gem "belt-messaging"
+# gem "belt-pay"
+```
+
+```bash
+bundle install
+belt generate messaging   # or: belt g pay
+belt generate --help      # lists built-ins + gem generators
+```
+
+### How plugins register
+
+No central registry file, no initializer hook. Belt discovers generators by scanning loaded gems:
+
+1. Gem is in the app `Gemfile` and bundled
+2. Gem ships a file at `lib/belt/generators/<name>_generator.rb`
+3. Class lives in `Belt::Generators`, named `<Name>Generator`
+4. Implements `.run(args)` (required), `.destroy(args)` and `.description` (optional)
+
+That is the whole contract. After `bundle install`, `belt generate <name>` and `belt destroy <name>` just work.
+
+See `Belt::CLI::GeneratorRegistry` and the CHANGELOG entry for **0.1.13 Generator Extension API**.
+
+### Plugin layout (canonical)
+
+```
+belt-messaging/
+├── belt-messaging.gemspec
+├── lib/
+│   ├── belt-messaging.rb              # require entrypoint
+│   └── belt/
+│       ├── messaging.rb               # Belt::Messaging API
+│       ├── messaging/
+│       │   ├── configuration.rb
+│       │   ├── version.rb
+│       │   ├── controllers/           # default controllers (optional)
+│       │   └── templates/             # ERB templates for the generator
+│       │       ├── terraform/
+│       │       ├── lambda/
+│       │       ├── config/
+│       │       └── controllers/
+│       └── generators/
+│           └── messaging_generator.rb # ← auto-discovered
+└── spec/
+```
+
+**Runtime code stays in the gem.** Generators copy only what the host app must own (Terraform modules, Lambda entrypoints, optional controller overrides). Prefer gem defaults + `belt g <plugin> --controllers` over dumping everything into the app (same idea as `rails g devise:views`).
+
+### Creating a new plugin
+
+Scaffold a ready-to-fill gem (Rails-style `plugin new`):
+
+```bash
+belt plugin new notifications
+# → ./belt-notifications/
+
+belt plugin new pay --path ~/Code --summary "Stripe payments for Belt"
+# → ~/Code/belt-pay/
+```
+
+Then:
+
+```bash
+cd belt-notifications
+bundle install
+# implement lib/belt/notifications/* and the generator
+```
+
+Point a Belt app at it while developing:
+
+```ruby
+# In the app Gemfile
+gem "belt-notifications", path: "../belt-notifications"
+```
+
+```bash
+bundle install
+belt generate notifications
+```
+
+When packaging Lambdas, `belt deploy` vendors path gems into `vendor/cache` so conveyor-belt can package them.
+
+### Generator checklist (for humans and agents)
+
+A solid plugin generator typically:
+
+1. **Terraform module** → `infrastructure/modules/<name>/` (`main.tf`, `variables.tf`, `outputs.tf`)
+2. **Lambda config** → `config/lambda/<name>.yml` (timeout, memory, env, triggers)
+3. **Lambda entrypoint** → `lambda/<name>.rb` using `Belt::LambdaHandler`
+4. **Routes / schema** → inject into `config/routes.tf.rb` or `infrastructure/schema.tf.rb` when needed
+5. **Optional overrides** → `--controllers` flag for app-local subclasses
+6. **Destroy path** → `belt destroy <name>` removes what generate created
+7. **Help text** → `.description` + `--help` explaining what was installed and next steps
+
+Copy from `belt-messaging` or `belt-pay` rather than inventing a new structure.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/stowzilla/belt).
+
+### Development setup
+
+```bash
+git clone https://github.com/stowzilla/belt.git
+cd belt
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+### Guidelines
+
+1. **Branch from `master`** — open a PR against `master`
+2. **Keep changes focused** — one concern per PR when practical
+3. **Follow existing patterns** — look at neighboring files and `lib/belt/cli/` before inventing new ones
+4. **Tests + lint** — run `bundle exec rspec` and `bundle exec rubocop` before opening (or updating) a PR. CI requires both (plus `bundler-audit`); failing checks block merge on `master`
+5. **Changelog** — note user-facing changes in `CHANGELOG.md` under the next version / Unreleased
+6. **No secrets** — never commit AWS keys, tokens, or real account IDs
+
+### Project layout (for contributors)
+
+| Path | What lives there |
+|------|------------------|
+| `lib/belt.rb` | Public require entry |
+| `lib/belt/` | Framework core (controller, router, handler, observability) |
+| `lib/belt/cli/` | CLI commands (`new`, `generate`, `deploy`, `plugin`, …) |
+| `lib/belt_controller/` | `BeltController::Base` |
+| `lib/templates/` | ERB templates for `belt new`, generators, plugin scaffold |
+| `exe/belt` | CLI executable |
+| `spec/` | RSpec suite |
+| `AGENTS.md` | Agent-oriented map of this gem (layout, CLI, plugin contract) |
+
+AI / coding agents: start with **[AGENTS.md](AGENTS.md)**. Belt apps and plugins scaffolded by the CLI get their own `AGENTS.md` as well (`belt new`, `belt plugin new`).
+
+### Local gem development against an app
+
+```ruby
+# In a Belt app's Gemfile
+gem "belt", path: "../belt"
+```
+
+`belt deploy` detects `path:` gems and materializes them into `vendor/cache` for Lambda packaging so you can iterate without publishing a gem for every try.
+
+### Contributing a plugin
+
+Plugins are separate repositories (not vendored into this repo). To add a new first-class capability:
+
+1. `belt plugin new <name>` (or copy `belt-messaging` / `belt-pay`)
+2. Implement the runtime API + generator contract above
+3. Document install steps in the plugin README (`gem …` → `belt generate …`)
+4. Open a PR on the plugin repo; optionally link it from this README's plugin table
+
+Questions about plugin design or core changes: open a GitHub issue or discuss in the project Discord.
+
 ## License
 
 MIT

data/lib/belt/action_router.rb

@@ -102,15 +102,35 @@ module Belt
     end
 
     def dispatch_to_controller(route_info, event, body)
-      controller_class = resolve_controller(route_info[:controller])
+      controller_name = route_info[:controller]
+
+      # Prevent path traversal — controller names must be simple identifiers or single-level nested
+      unless valid_controller_name?(controller_name)
+        Belt::Observability::Logger.instance&.warn('Invalid controller name', controller: controller_name)
+        return error_response('Not found', 404, event)
+      end
+
+      controller_class = resolve_controller(controller_name)
       controller = controller_class.new(event: event, body: body)
 
-      controller_name = controller_class.name.split('::').last.gsub('Controller', '')
-      Belt::Observability::Logger.instance&.info("Processing by #{controller_name}##{route_info[:action]}")
+      class_label = controller_class.name.split('::').last.gsub('Controller', '')
+      Belt::Observability::Logger.instance&.info("Processing by #{class_label}##{route_info[:action]}")
 
       controller.dispatch(route_info[:action].to_sym)
     end
 
+    # Validate controller names to prevent path traversal.
+    # Allows: "posts", "admin/posts" (single nesting level, no dots or special chars)
+    def valid_controller_name?(name)
+      return false if name.nil? || name.empty?
+      return false if name.include?('..')
+      return false if name.start_with?('/') || name.end_with?('/')
+      return false if name.include?('\\')
+
+      # Allow only lowercase letters, digits, underscores, and a single forward slash for nesting
+      name.match?(%r{\A[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)?\z})
+    end
+
     def resolve_controller(controller_name)
       # Try namespace module first (app's own controllers)
       begin
@@ -137,10 +157,18 @@ module Belt
     def resolve_from_paths(controller_name)
       if controller_name.include?('/')
       end
-      file_name = "#{controller_name}_controller.rb"
+      file_name = "#{controller_name.gsub('/', '_')}_controller.rb"
 
       Belt.all_controller_paths.each do |path|
         full_path = File.join(path, file_name)
+
+        # Ensure resolved path stays within the allowed controller directory
+        begin
+          resolved = File.realpath(full_path)
+        rescue Errno::ENOENT, Errno::EACCES
+          next
+        end
+        next unless resolved.start_with?(File.realpath(path))
         next unless File.exist?(full_path)
 
         require full_path

data/lib/belt/cli/app_detection.rb

@@ -40,17 +40,31 @@ module Belt
         name.to_s.downcase.tr('_', '-')
       end
 
-      # Finds routes.tf.rb checking config/ first, then infrastructure/ (legacy).
+      # Finds routes file checking config/routes.rb first, then legacy paths.
       def find_routes_file_path
-        candidates = ['config/routes.tf.rb', 'infrastructure/routes.tf.rb']
+        candidates = [
+          'config/routes.rb',
+          'config/routes.tf.rb',
+          'infrastructure/routes.tf.rb'
+        ]
         candidates.find { |f| File.exist?(f) }
       end
 
-      # Finds schema.tf.rb checking config/ first, then infrastructure/ (legacy).
-      def find_schema_file_path
-        candidates = ['config/schema.tf.rb', 'infrastructure/schema.tf.rb']
+      # Finds contracts file checking config/contracts.rb first, then legacy paths.
+      def find_contracts_file_path
+        candidates = [
+          'config/contracts.rb',
+          'config/contracts.tf.rb',
+          'config/schema.tf.rb',
+          'infrastructure/schema.tf.rb'
+        ]
         candidates.find { |f| File.exist?(f) }
       end
+
+      # Legacy alias for backward compatibility
+      def find_schema_file_path
+        find_contracts_file_path
+      end
     end
   end
 end

data/lib/belt/cli/contracts_command.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'optparse'
+require_relative '../route_dsl'
+require_relative 'routes_command/schema_loader'
+
+module Belt
+  module CLI
+    class ContractsCommand
+      include RoutesCommand::SchemaLoader
+
+      def self.run(args)
+        new(args).run
+      end
+
+      def initialize(args)
+        @options = {}
+        parse_options(args)
+      end
+
+      def run
+        contracts_file = find_contracts_file
+        unless contracts_file
+          abort 'Error: No contracts file found. ' \
+                'Expected config/contracts.rb (or config/contracts.tf.rb, config/schema.tf.rb)'
+        end
+
+        models = load_contracts(contracts_file)
+
+        if @options[:format] == 'json'
+          output_json(models)
+        else
+          output_concise(models)
+        end
+      end
+
+      private
+
+      def parse_options(args)
+        OptionParser.new do |opts|
+          opts.banner = 'Usage: belt contracts [options]'
+
+          opts.on('-f', '--format FORMAT', 'Output format: concise (default), json') do |format|
+            @options[:format] = format
+          end
+
+          opts.on('-g', '--grep PATTERN', 'Filter contracts matching pattern') do |pattern|
+            @options[:grep] = pattern
+          end
+
+          opts.on('--file FILE', 'Path to contracts file (overrides auto-detection)') do |file|
+            @options[:contracts_file] = file
+          end
+
+          opts.on('-h', '--help', 'Show this help') do
+            puts opts
+            exit
+          end
+        end.parse!(args)
+      end
+
+      def find_contracts_file
+        if @options[:contracts_file]
+          file = @options[:contracts_file]
+          return file if File.exist?(file)
+
+          abort "Error: Specified contracts file not found: #{file}"
+        end
+
+        candidates = [
+          'config/contracts.rb',
+          'config/contracts.tf.rb',
+          'config/schema.tf.rb',
+          'infrastructure/schema.tf.rb'
+        ]
+        candidates.find { |f| File.exist?(f) }
+      end
+
+      def load_contracts(file)
+        Belt.instance_variable_set(:@application, nil)
+        begin
+          eval(File.read(file), binding, file) # rubocop:disable Security/Eval
+        rescue StandardError => e
+          abort "Error: Failed to load contracts file #{file}: #{e.message}"
+        end
+
+        schema = Belt.application.schema.to_h
+        models = build_models_from_schema(schema)
+        models = apply_grep(models) if @options[:grep]
+        models
+      end
+
+      def apply_grep(models)
+        pattern = Regexp.new(@options[:grep], Regexp::IGNORECASE)
+        models.select do |m|
+          m[:name].match?(pattern) ||
+            m[:kind].match?(pattern) ||
+            m[:description].match?(pattern)
+        end
+      end
+
+      def output_json(models)
+        puts JSON.pretty_generate(models: models)
+      end
+
+      def output_concise(models)
+        return puts('No contracts defined.') if models.empty?
+
+        requests = models.select { |m| m[:kind] == 'request' }
+        responses = models.select { |m| m[:kind] == 'response' }
+
+        if requests.any?
+          puts 'REQUEST MODELS'
+          puts '-' * 60
+          requests.each { |m| print_model(m) }
+          puts
+        end
+
+        if responses.any?
+          puts 'RESPONSE MODELS'
+          puts '-' * 60
+          responses.each { |m| print_model(m) }
+        end
+
+        puts "\n#{models.length} contract(s) total (#{requests.length} request, #{responses.length} response)"
+      end
+
+      def print_model(model)
+        required = model[:required] || []
+        props = (model[:properties] || {}).map do |name, meta|
+          type = meta['type'] || meta[:type] || 'string'
+          req_marker = required.include?(name.to_s) ? ' *' : ''
+          "#{name}:#{type}#{req_marker}"
+        end
+
+        puts "  #{model[:name]} (#{model[:kind]})"
+        puts "    #{props.join(', ')}" if props.any?
+      end
+    end
+  end
+end