belt 0.6.3 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a728d2756664cff1204c7926b8db4cbe7d327e1aacf6d544b9d39db2e2e258c
-  data.tar.gz: 5b4eb1d119a8343abbdfe5fc329f167546bc963ecb7ef415d0c54b5c049cf084
+  metadata.gz: 39a9c396d05b2acfc5c69adc875f0050beb9395a2dc9f31dd4ac2d2221e011db
+  data.tar.gz: ddf3e2d95ea98eafc808f0d2e144196257f4880fb1b8d65ae063dd27becb9213
 SHA512:
-  metadata.gz: bad0ef5562fe52c213e58b8ae0451e8fe48ae1f1b347f2cb6662e891e9b5893b59210002d5fedf0c3e3b03fcb72ed24ab05c5485c2156e034e1207a5c0f54316
-  data.tar.gz: 2a92ccf0e821c055f0cbf661c5d5446ba98fd7bd45fb25b7fda6a774027f29aba07411fc962afb0b3f150c6685a768790c2981ba8548f9549b3828c969ed88ec
+  metadata.gz: f3463e2d5e75fc653437accecb76a3a66683cd28bf7781a9aadbef167b2cf3f18ad4d5e32fb3cb5f57c6e406929253f6f762ebecec5a4d20b2723c9a8118efd8
+  data.tar.gz: f1ccdeca8439a8063940c981f9c05a24abb319bcb0aa76c7212e0883fc6a9c4db7ee10f0e2da1f93105d1bca68844bd108ca7e820b8a462c900d309d35231905

data/CHANGELOG.md

@@ -1,6 +1,41 @@
 # Changelog
 
-## Unreleased
+## 0.6.5
+
+### Added
+
+- **Per-route throttling in `routes.rb`.** Any route or resource accepts
+  `throttle: { rate: 2, burst: 5 }` (requests/second + burst). `belt routes -f json` emits it
+  as `throttle` on the route and conveyor-belt 0.0.20+ applies it as API Gateway stage method
+  settings, winning over the Lambda's `throttle:` in `config/lambda/<fn>.yml`. Malformed values
+  raise at load time. (Fizzy #1756)
+
+## 0.6.4
+
+### Added
+
+- **Plugins can register top-level commands.** A gem that ships
+  `lib/belt/commands/<name>_command.rb` defining `Belt::Commands::<Name>Command.run(args)`
+  gets `belt <name> ...` (underscores in the file name become hyphens), listed under
+  "Plugin Commands" in `belt --help`. Discovery mirrors `GeneratorRegistry`
+  (`Belt::CLI::CommandRegistry`). Optional `.description` for help text and `.standalone?`
+  to run outside a Belt project. Built-in commands and terraform actions win on a name
+  clash. `belt help` / `belt --help` / `belt -h` now print usage and exit 0.
+
+### Fixed
+
+- **The data-migrations step of `belt deploy` no longer fails with "You have already
+  activated json X, but your Gemfile requires json Y".** The child `belt db:migrate` now
+  starts with the app's bundle loaded (`BUNDLE_GEMFILE` + `-rbundler/setup`), so the belt
+  CLI's own `require 'json'` can't activate a newer json than the app's lockfile pins.
+- **A fresh environment's Lambdas missing their `config/lambda/*.yml` `env_vars`** (nested
+  envs especially, since they are always created fresh) is fixed in conveyor-belt 0.0.19:
+  the provider's create path read only the HCL `lambda_config` map and ignored
+  `lambda_config_dir`, so the YAML env vars, `iam_policy_arns` and triggers landed only on
+  a second deploy. Existing apps on `version = "~> 0.0.16"` pick it up with
+  `terraform init -upgrade` in the env's infrastructure directory.
+
+## 0.6.3
 
 ### Added
 

data/README.md

@@ -209,6 +209,15 @@ end
 
 **Key point:** `namespace` and `scope` are purely organizational — they affect URL paths and controller module resolution but never change which Lambda handles the request. Use `function` when you need routes to go to a different Lambda.
 
+**Per-route throttling:** any route or resource accepts `throttle: { rate:, burst: }` (steady-state requests per second plus the burst the token bucket absorbs). `belt routes -f json` emits it and the conveyor-belt provider (0.0.20+) applies it as API Gateway stage method settings. A route's `throttle` wins over the serving Lambda's `throttle:` in `config/lambda/<fn>.yml`, which in turn wins over the provider's stage-level `throttle` block.
+
+```ruby
+gateway :api, auth: :none do
+  post '/connect/chat', to: 'chat#create', throttle: { rate: 2, burst: 5 }
+  resources :leads, only: [:create], throttle: { rate: 1, burst: 3 }
+end
+```
+
 ### Nested Resource DSL
 
 Inside a `resources` block, you can use Rails-like `member`, `collection`, `scope`, and singular `resource` for DRYer route definitions:
@@ -830,6 +839,8 @@ No central registry file, no initializer hook. Belt discovers generators by scan
 
 That is the whole contract. After `bundle install`, `belt generate <name>` and `belt destroy <name>` just work.
 
+Plugins can also add a top-level command: a file at `lib/belt/commands/<name>_command.rb` defining `Belt::Commands::<Name>Command.run(args)` becomes `belt <name> ...` and shows up under "Plugin Commands" in `belt --help`. Optional `.description` and `.standalone?` (run outside a project). Built-in commands win on a name clash. See `Belt::CLI::CommandRegistry` and `belt explain plugins`.
+
 See `Belt::CLI::GeneratorRegistry` and the CHANGELOG entry for **0.1.13 Generator Extension API**.
 
 ### Plugin layout (canonical)

data/lib/belt/cli/command_registry.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Belt
+  module CLI
+    # Discovers top-level CLI commands provided by external gems.
+    #
+    # Gems register commands by placing a file at:
+    #   lib/belt/commands/<name>_command.rb
+    #
+    # Each command class must:
+    #   - Be named <Name>Command (e.g., ConnectCommand)
+    #   - Live in the Belt::Commands module
+    #   - Implement .run(args)
+    #   - Implement .description for help text (optional)
+    #   - Implement .standalone? returning true to run outside a Belt project (optional)
+    #
+    # Example gem structure:
+    #   belt-connect/
+    #     lib/
+    #       belt/
+    #         commands/
+    #           connect_command.rb
+    #
+    # The command is then available as:
+    #   belt connect ...
+    #
+    # Underscores in the file name become hyphens in the command name
+    # (lib/belt/commands/feature_flags_command.rb → `belt feature-flags`).
+    # Built-in commands win on a name clash; see Belt::CLI.plugin_command.
+    module CommandRegistry
+      COMMAND_PATH = 'lib/belt/commands'
+
+      class << self
+        # Returns a hash of { "name" => command_class } for all discovered commands.
+        def discovered_commands
+          @discovered_commands ||= discover_all
+        end
+
+        # Returns just the names of discovered commands.
+        def command_names
+          discovered_commands.keys
+        end
+
+        # Returns the command class for a given name, or nil if not found.
+        def find(name)
+          discovered_commands[name]
+        end
+
+        # Reset cache (useful in tests)
+        def reset!
+          @discovered_commands = nil
+        end
+
+        private
+
+        def discover_all
+          commands = {}
+
+          Gem.loaded_specs.each_value do |spec|
+            commands_dir = File.join(spec.gem_dir, COMMAND_PATH)
+            next unless File.directory?(commands_dir)
+
+            Dir.glob(File.join(commands_dir, '*_command.rb')).each do |file|
+              basename = File.basename(file, '.rb').sub(/_command\z/, '')
+              klass = load_command_class(file, basename)
+              commands[basename.tr('_', '-')] = klass if klass
+            end
+          end
+
+          commands
+        end
+
+        def load_command_class(file, basename)
+          require file
+
+          class_name = "#{classify(basename)}Command"
+          Belt::Commands.const_get(class_name, false)
+        rescue LoadError, NameError => e
+          warn "[Belt] Warning: Failed to load command '#{basename}' from #{file}: #{e.message}"
+          nil
+        end
+
+        def classify(name)
+          name.split('_').map(&:capitalize).join
+        end
+      end
+    end
+  end
+
+  # Namespace for top-level command classes provided by external gems
+  module Commands
+  end
+end

data/lib/belt/cli/deploy_command.rb

@@ -923,13 +923,27 @@ module Belt
         return true if @skip_migrations || !DbMigrateCommand.migrations?(@project_root)
 
         puts "\n━━━ data migrations ━━━"
-        return true if system(Gem.ruby, BELT_EXE, 'db:migrate', @env, '--yes', chdir: @project_root)
+        return true if system(migration_child_env, Gem.ruby, BELT_EXE, 'db:migrate', @env, '--yes',
+                              chdir: @project_root)
 
         puts "\n  ⚠ Data migrations failed for #{@env}. The deploy itself succeeded."
         puts "    Fix the migration and run `belt db:migrate #{@env}` to retry."
         false
       end
 
+      # Load the app's bundle before the belt CLI does. Otherwise the CLI's own
+      # `require 'json'` activates the newest installed json, and db:migrate's
+      # `bundler/setup` then fails with "You have already activated json X,
+      # but your Gemfile requires json Y" (Fizzy #1734).
+      def migration_child_env
+        gemfile = File.join(@project_root, 'Gemfile')
+        return {} unless File.exist?(gemfile)
+
+        rubyopt = ENV.fetch('RUBYOPT', '')
+        rubyopt = "-rbundler/setup #{rubyopt}".strip unless rubyopt.include?('bundler/setup')
+        { 'BUNDLE_GEMFILE' => gemfile, 'RUBYOPT' => rubyopt }
+      end
+
       def deploy_frontend_if_exists
         require_relative 'frontend_registry'
         require_relative 'frontend_deploy_command'

data/lib/belt/cli/routes_command.rb

@@ -165,6 +165,7 @@ module Belt
         }
         rc = route.response_context.to_s
         hash[:response_context] = rc unless rc.empty?
+        hash[:throttle] = route.throttle if route.throttle
         hash
       end
 

data/lib/belt/cli.rb

@@ -31,6 +31,7 @@ require_relative 'cli/logs_command'
 require_relative 'cli/doctor_command'
 require_relative 'cli/plugin_command'
 require_relative 'cli/explain_command'
+require_relative 'cli/command_registry'
 
 module Belt
   module CLI
@@ -56,7 +57,8 @@ module Belt
       'dns' => Belt::CLI::DnsCommand,
       'frontend' => Belt::CLI::FrontendEnvCommand,
       %w[server s] => Belt::CLI::ServerCommand,
-      %w[version --version -v] => ->(_args) { puts "Belt #{Belt::VERSION}" }
+      %w[version --version -v] => ->(_args) { puts "Belt #{Belt::VERSION}" },
+      %w[help --help -h] => ->(_args) { puts usage }
     }.freeze
 
     COMMANDS = COMMANDS_DEFINITION.each_with_object({}) do |(keys, handler), hash|
@@ -66,7 +68,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 explain].freeze
+    STANDALONE_COMMANDS = %w[new version --version -v help --help -h doctor explain].freeze
 
     def self.start(args)
       command = args.shift
@@ -76,8 +78,10 @@ module Belt
         exit 1
       end
 
+      plugin = plugin_command(command)
+
       # For project-level commands, find and chdir to the project root
-      ensure_project_root!(command) unless STANDALONE_COMMANDS.include?(command)
+      ensure_project_root!(command) unless standalone?(command, plugin)
 
       # `belt destroy` is ambiguous: could be terraform destroy or belt destroy <generator>.
       return if command == 'destroy' && route_destroy_command(args)
@@ -85,7 +89,7 @@ module Belt
       # Terraform shorthand: belt init wups, belt plan wups, belt apply wups, belt destroy wups
       return Belt::CLI::TerraformCommand.run(command, args) if TERRAFORM_ACTIONS.include?(command)
 
-      handler = COMMANDS[command]
+      handler = COMMANDS[command] || plugin
 
       # If no built-in command matched, try running it as a rake task
       if handler.nil?
@@ -102,7 +106,43 @@ module Belt
       end
     end
 
+    # Returns the gem-provided command class for `name`, or nil. Built-in
+    # commands and terraform actions win on a name clash.
+    def self.plugin_command(name)
+      return nil if name.nil? || builtin_command?(name)
+
+      CommandRegistry.find(name)
+    end
+
+    def self.builtin_command?(name)
+      COMMANDS.key?(name) || TERRAFORM_ACTIONS.include?(name)
+    end
+
+    def self.standalone?(command, plugin)
+      return STANDALONE_COMMANDS.include?(command) unless plugin
+
+      plugin.respond_to?(:standalone?) && plugin.standalone?
+    end
+
     def self.usage
+      base_usage.sub("\nRake Tasks:\n", "#{plugin_usage}\nRake Tasks:\n")
+    end
+
+    # "Plugin Commands:" help section for gem-provided commands ("" when none).
+    def self.plugin_usage
+      names = CommandRegistry.command_names.reject { |name| builtin_command?(name) }.sort
+      return '' if names.empty?
+
+      lines = names.map do |name|
+        klass = CommandRegistry.find(name)
+        description = klass.respond_to?(:description) ? klass.description.to_s : ''
+        "  #{name.ljust(42)}  #{description}".rstrip
+      end
+
+      "\nPlugin Commands:\n#{lines.join("\n")}\n"
+    end
+
+    def self.base_usage
       <<~USAGE
         Usage: belt <command> [options]
 
@@ -151,6 +191,7 @@ module Belt
           destroy [environment] <env>                 terraform destroy for environment
           output [environment] <env>                  terraform output for environment
           --version                                   Show Belt version
+          help, --help, -h                            Show this help
 
         Rake Tasks:
           Any rake task from your Gemfile dependencies can be run directly:

data/lib/belt/docs/plugins.md

@@ -45,6 +45,38 @@ Belt discovers plugins automatically when:
 
 Optional: `.destroy(args)` and `.description` for destroy path and help text.
 
+## Top-level Commands
+
+A plugin can also add its own `belt <name> ...` command, the way `belt-connect`
+adds `belt connect`:
+
+1. Gem has a file at `lib/belt/commands/<name>_command.rb`
+2. Class is `Belt::Commands::<Name>Command`
+3. Class implements `.run(args)` (required); `args` is everything after `<name>`
+
+Optional: `.description` (shown under "Plugin Commands" in `belt --help`) and
+`.standalone?` returning `true` to run outside a Belt project. Otherwise the
+command runs from the project root, like built-ins.
+
+Underscores in the file name become hyphens (`feature_flags_command.rb` →
+`belt feature-flags`). Built-in commands and terraform actions win on a name
+clash, so a plugin can't shadow `belt deploy`.
+
+```ruby
+# lib/belt/commands/connect_command.rb
+module Belt
+  module Commands
+    class ConnectCommand
+      def self.description = 'Connect widgets to your app'
+
+      def self.run(args)
+        # belt connect widget orders --env dev → args == ['widget', 'orders', '--env', 'dev']
+      end
+    end
+  end
+end
+```
+
 ## Generator Checklist
 
 A good plugin generator typically installs:
@@ -71,6 +103,8 @@ belt-messaging/
 │       │   ├── version.rb
 │       │   ├── controllers/           # Default controllers
 │       │   └── templates/             # ERB templates for generator
+│       ├── commands/
+│       │   └── messaging_command.rb   # ← optional `belt messaging`
 │       └── generators/
 │           └── messaging_generator.rb # ← auto-discovered
 └── spec/

data/lib/belt/route_dsl.rb

@@ -9,7 +9,7 @@ module Belt
 
   class Route
     attr_reader :method, :path, :auth, :lambda, :cors, :tables, :route_type,
-                :controller, :action, :request_model, :response_model, :response_context
+                :controller, :action, :request_model, :response_model, :response_context, :throttle
 
     def initialize(method, path, options = {})
       @method = method.to_s.upcase
@@ -17,6 +17,7 @@ module Belt
       @auth = options[:auth]
       @lambda = options[:lambda]
       @cors = options.fetch(:cors, true)
+      @throttle = self.class.normalize_throttle(options[:throttle])
       @tables = options[:tables] || []
       @route_type = options[:route_type] || :action
       @controller = options[:controller]
@@ -26,6 +27,31 @@ module Belt
       @response_context = options[:response_context]&.to_s
     end
 
+    # Per-route API Gateway limit: `throttle: { rate: 2, burst: 5 }` (requests per
+    # second, token bucket). Emitted by `belt routes -f json` and applied by the
+    # conveyor-belt provider (0.0.20+) as stage method settings; it wins over the
+    # Lambda's `throttle:` in config/lambda/<fn>.yml. Returns nil when unset.
+    def self.normalize_throttle(raw)
+      return nil if raw.nil?
+
+      unless raw.is_a?(Hash)
+        raise ArgumentError, "throttle must be a Hash like { rate: 2, burst: 5 } (got #{raw.inspect})"
+      end
+
+      rate = raw[:rate] || raw['rate']
+      burst = raw[:burst] || raw['burst']
+      raise ArgumentError, 'throttle needs rate (requests/second) and burst' if rate.nil? || burst.nil?
+
+      unless rate.is_a?(Numeric) && rate.positive?
+        raise ArgumentError, "throttle rate must be a number > 0 (got #{rate.inspect})"
+      end
+      unless burst.is_a?(Integer) && burst.positive?
+        raise ArgumentError, "throttle burst must be an integer > 0 (got #{burst.inspect})"
+      end
+
+      { rate: rate, burst: burst }
+    end
+
     def resource?
       @route_type == :resource || @route_type == :resources
     end
@@ -494,7 +520,8 @@ module Belt
         action: action,
         request_model: options[:request_model],
         response_model: options[:response_model],
-        response_context: options[:response_context]
+        response_context: options[:response_context],
+        throttle: options[:throttle]
       }
 
       @routes << Belt::Route.new(method, path, route_options)

data/lib/belt/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.6.3'
+  VERSION = '0.6.5'
 
   # Ruby version new apps run on in Lambda. Rendered into the conveyor-belt
   # provider block (`ruby_version`) by `belt new` / `belt generate environment`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.6.5
 platform: ruby
 authors:
 - Stowzilla
@@ -118,6 +118,7 @@ files:
 - lib/belt/cli/backup_runner.rb
 - lib/belt/cli/bucket_security.rb
 - lib/belt/cli/cognito_sharer.rb
+- lib/belt/cli/command_registry.rb
 - lib/belt/cli/console_command.rb
 - lib/belt/cli/contracts_command.rb
 - lib/belt/cli/db_copy_command.rb