belt 0.6.3 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a728d2756664cff1204c7926b8db4cbe7d327e1aacf6d544b9d39db2e2e258c
-  data.tar.gz: 5b4eb1d119a8343abbdfe5fc329f167546bc963ecb7ef415d0c54b5c049cf084
+  metadata.gz: 2fcb629702530cd06ffb9af298dcd259c4fc0503107ef19ab58a58da476617b4
+  data.tar.gz: 167a12259478e5079620446f76dad474cde1d456f08b328663fe11f82860fa66
 SHA512:
-  metadata.gz: bad0ef5562fe52c213e58b8ae0451e8fe48ae1f1b347f2cb6662e891e9b5893b59210002d5fedf0c3e3b03fcb72ed24ab05c5485c2156e034e1207a5c0f54316
-  data.tar.gz: 2a92ccf0e821c055f0cbf661c5d5446ba98fd7bd45fb25b7fda6a774027f29aba07411fc962afb0b3f150c6685a768790c2981ba8548f9549b3828c969ed88ec
+  metadata.gz: bb37dd0fe9e0cd392a0824d14b0ab4c51c5d002b36240fc7795ad11ce2313dd0014bea535c020fab6e4ec8988c7cf4d5a90992e2f8cfcdbcea35bc780586592f
+  data.tar.gz: d8d7423e5b3cd0c3d1598ff7b9e82446c9de4705b68313ade0ee0479ec26a87b5d4e3acd23a52b664ec2f50fd37e66cb046e1383f18bbf696cd01a13d24b140e

data/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
-## Unreleased
+## 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

@@ -830,6 +830,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.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/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.6.3'
+  VERSION = '0.6.4'
 
   # 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.4
 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