belt 0.6.2 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05d5db875d229ad413bf8af05004a92961776b347db0884ded768f35fcfe245e
-  data.tar.gz: d6f1590f52f2a04b9457b82cf0c0cad094b96b8e04e112672df37d1e5ccf173b
+  metadata.gz: 2fcb629702530cd06ffb9af298dcd259c4fc0503107ef19ab58a58da476617b4
+  data.tar.gz: 167a12259478e5079620446f76dad474cde1d456f08b328663fe11f82860fa66
 SHA512:
-  metadata.gz: 5b9c29157f8d7b698c8f68c807564299f881b220473ef4a51194352092f5a8967dfce0495fb12bc24a813b4ab2e077358c3800151ccf8737059888560a62ad97
-  data.tar.gz: 6629a4a02a92e571d1e835ba0f12894f8bad945eb89bf79a2bc4696538378f45dfd7b5f5e3fc4090d9e61120c51d032b2fab5d5e2bdc17cfdfe81d25950061db
+  metadata.gz: bb37dd0fe9e0cd392a0824d14b0ab4c51c5d002b36240fc7795ad11ce2313dd0014bea535c020fab6e4ec8988c7cf4d5a90992e2f8cfcdbcea35bc780586592f
+  data.tar.gz: d8d7423e5b3cd0c3d1598ff7b9e82446c9de4705b68313ade0ee0479ec26a87b5d4e3acd23a52b664ec2f50fd37e66cb046e1383f18bbf696cd01a13d24b140e

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 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 migrations.** `db/migrate/<timestamp>_<name>.rb` files define `Belt::Migration`
+  subclasses whose `up` runs in the booted app context (same as `belt console`).
+  `belt deploy <env>` runs pending ones after terraform apply and the nested-env data copy
+  (also after `--rebuild`; opt out with `--skip-migrations`). Each version runs once per
+  environment, nested envs included, recorded in SSM at
+  `/belt/<app>/<env>/schema_migrations/<version>`. A failed migration stays pending, the
+  deploy carries on and exits non-zero. New `belt db:migrate [env]` and
+  `belt db:migrate:status [env]` run or check them by hand. See `belt explain migrations`.
+
 ## 0.6.2
 
 ### Fixed

data/README.md

@@ -731,6 +731,29 @@ puts "Created post: #{post.id}"
 
 Refuses to run against an environment that already has data (pass `--force` to override). `belt new` scaffolds a starter `config/seeds.rb`. See `belt explain data_seeding` for details.
 
+### `belt db:migrate` — data migrations
+
+For changes to rows that already exist (backfilling an attribute, populating a new GSI for old records), add a migration to `db/migrate/`:
+
+```ruby
+# db/migrate/20261030120000_index_usernames.rb
+class IndexUsernames < Belt::Migration
+  def up
+    PoshNosh::MatchStore.new.index_usernames!
+  end
+end
+```
+
+`belt deploy <env>` runs pending migrations after terraform apply, once per environment (nested envs included). Applied versions are recorded in SSM under `/belt/<app>/<env>/schema_migrations/`.
+
+```bash
+belt db:migrate dev01            # run pending migrations by hand
+belt db:migrate:status prod      # which have run
+belt deploy dev --skip-migrations
+```
+
+Migrations must be idempotent and batch-safe. See `belt explain migrations`.
+
 ## Testing
 
 Belt ships an in-process **end-to-end harness** that drives the real router — no AWS, no HTTP server, no browser. It's the tier between controller unit tests (dispatch an action directly, never touch routing) and full cloud e2e (needs a deployed stack).
@@ -807,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/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   Belt routing DSL, writing BeltController actions, modeling DynamoDB data
   with ActiveItem, wiring Cognito auth, configuring the Lambda handler,
   running `belt` CLI commands (new, generate, deploy, console, routes, logs,
-  server, setup, plugin, explain, db:copy/db:seed), Terraform via belt,
+  server, setup, plugin, explain, db:copy/db:seed/db:migrate), Terraform via belt,
   backups, observability, or authoring Belt plugins. Triggers on "belt new",
   "belt deploy", "belt generate", "belt routes", "BeltController", "ActiveItem",
   "Belt::LambdaHandler", "belt console", "belt server", "conveyor-belt". Do NOT

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/db_migrate_command.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'stringio'
+require_relative 'app_detection'
+require_relative 'environment_config'
+require_relative 'migration_store'
+require_relative '../inflector'
+require_relative '../migration'
+
+module Belt
+  module CLI
+    # `belt db:migrate` / `belt db:migrate:status` — data migrations.
+    #
+    # Each `db/migrate/<timestamp>_<name>.rb` defines a `Belt::Migration`
+    # subclass named after the file (`20261030120000_index_usernames.rb` →
+    # `IndexUsernames`). Pending ones run oldest-first in the same booted app
+    # context `belt console` uses, and each is recorded in SSM (see
+    # MigrationStore) only after its `up` returns, so a failure is retried on
+    # the next run. `belt deploy` runs this after terraform apply.
+    class DbMigrateCommand
+      include AppDetection
+
+      MIGRATIONS_DIR = File.join('db', 'migrate')
+      FILENAME_PATTERN = /\A(\d+)_([a-z0-9_]+)\.rb\z/
+
+      MigrationFile = Struct.new(:version, :name, :path) do
+        def class_name
+          Belt::Inflector.camelize(name)
+        end
+
+        def label
+          name.tr('_', ' ').capitalize
+        end
+      end
+
+      def self.run(args, status: false)
+        new(args, status: status).run
+      end
+
+      def self.migrations?(root = Dir.pwd)
+        Dir.glob(File.join(root, MIGRATIONS_DIR, '*.rb')).any?
+      end
+
+      def initialize(args, status: false)
+        @options = { status: status, yes: false }
+        parse_options(args)
+      end
+
+      def run
+        ENV['BUNDLE_GEMFILE'] ||= File.join(Belt.root, 'Gemfile')
+        unless File.exist?(ENV['BUNDLE_GEMFILE'])
+          abort "Error: No Gemfile found at #{ENV['BUNDLE_GEMFILE']}. Are you in a Belt project?"
+        end
+
+        @environment = @env_arg || ENV.fetch('BELT_ENV', nil) || 'dev'
+        ENV['ENVIRONMENT'] = @environment
+        apply_env_config!
+
+        @store = MigrationStore.new(app_name: detect_app_name, env: @environment)
+        @options[:status] ? print_status : migrate
+      rescue MigrationStore::Error => e
+        abort "Error: #{e.message}"
+      end
+
+      private
+
+      def parse_options(args)
+        OptionParser.new do |opts|
+          opts.banner = if @options[:status]
+                          'Usage: belt db:migrate:status [environment]'
+                        else
+                          'Usage: belt db:migrate [environment] [options]'
+                        end
+
+          unless @options[:status]
+            opts.on('-y', '--yes', 'Skip the production confirmation prompt') { @options[:yes] = true }
+          end
+
+          opts.on('-h', '--help', 'Show this help') do
+            puts opts
+            exit
+          end
+        end.parse!(args)
+
+        @env_arg = args.shift
+      end
+
+      def apply_env_config!
+        env_config = EnvironmentConfig.load(@environment)
+        env_config.apply!
+        puts "  🔑 Using AWS profile: #{env_config.aws_profile}" if env_config.aws_profile?
+      end
+
+      def migrate
+        pending = pending_migrations
+        if pending.empty?
+          puts "belt → no pending migrations for #{@environment}"
+          return
+        end
+
+        production_guard!
+        boot_app
+
+        puts "belt → running #{pending.size} migration(s) against #{@environment}"
+        pending.each { |file| run_migration(file) }
+        puts "✅ Migrations complete (#{@environment})"
+      end
+
+      def run_migration(file)
+        puts "  == #{file.version} #{file.label}"
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        instantiate(file).up
+        @store.record!(file.version, file.name)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        puts format('  == %<version>s migrated (%<elapsed>.1fs)', version: file.version, elapsed: elapsed)
+      rescue MigrationStore::Error
+        raise
+      rescue StandardError, ScriptError => e
+        abort "\n❌ Migration #{file.version} (#{file.name}) failed: #{e.class}: #{e.message}\n" \
+              "#{Array(e.backtrace).first(5).join("\n")}\n\n" \
+              'Later migrations were not run. Fix it and re-run ' \
+              "`belt db:migrate #{@environment}` (migrations must be safe to re-run)."
+      end
+
+      def instantiate(file)
+        load File.expand_path(file.path)
+        klass = Object.const_get(file.class_name) if Object.const_defined?(file.class_name)
+        unless klass.is_a?(Class) && klass < Belt::Migration
+          raise NameError, "#{file.path} must define `class #{file.class_name} < Belt::Migration`"
+        end
+
+        klass.new(version: file.version, name: file.name)
+      end
+
+      def print_status
+        applied = @store.applied_versions
+        files = migration_files
+
+        puts "\nenvironment: #{@environment}\n\n"
+        puts ' Status   Migration ID    Migration Name'
+        puts '-' * 50
+        files.each do |file|
+          puts status_line(applied.include?(file.version) ? 'up' : 'down', file.version, file.label)
+        end
+        (applied - files.map(&:version)).sort.each do |version|
+          puts status_line('up', version, '** NO FILE **')
+        end
+        puts '  (no migrations in db/migrate)' if files.empty? && applied.empty?
+      end
+
+      def status_line(state, version, label)
+        format('  %<state>-6s  %<version>-14s  %<label>s', state: state, version: version, label: label)
+      end
+
+      def pending_migrations
+        applied = @store.applied_versions
+        migration_files.reject { |file| applied.include?(file.version) }
+      end
+
+      def migration_files
+        Dir.glob(File.join(MIGRATIONS_DIR, '*.rb')).map do |path|
+          match = File.basename(path).match(FILENAME_PATTERN)
+          abort "Error: #{path} must be named <timestamp>_<snake_case_name>.rb" unless match
+
+          MigrationFile.new(match[1], match[2], path)
+        end.sort_by(&:version)
+      end
+
+      def production_guard!
+        return unless @environment == 'prod' && !@options[:yes]
+
+        $stdout.write "\n⚠️  WARNING: You are about to migrate PRODUCTION data!\nType 'yes' to continue: "
+        response = $stdin.gets&.chomp
+        abort "\n❌ Cancelled." unless response&.downcase == 'yes'
+      end
+
+      def boot_app
+        suppress_warnings { require 'bundler/setup' }
+
+        environment_file = File.join(Belt.root, 'lambda', 'config', 'environment.rb')
+        if File.exist?(environment_file)
+          load environment_file
+        else
+          require 'belt'
+          load_dir('lib')
+          load_dir('models')
+        end
+      end
+
+      def load_dir(subdir)
+        dir = File.join(Belt.root, 'lambda', subdir)
+        Dir.glob(File.join(dir, '**', '*.rb')).each { |f| require f } if Dir.exist?(dir)
+      end
+
+      def suppress_warnings
+        original_verbose = $VERBOSE
+        $VERBOSE = nil
+        original_stderr = $stderr
+        $stderr = StringIO.new
+        yield
+      ensure
+        $stderr = original_stderr
+        $VERBOSE = original_verbose
+      end
+    end
+  end
+end

data/lib/belt/cli/deploy_command.rb

@@ -16,11 +16,13 @@ require_relative 'cognito_sharer'
 require_relative 'dynamo_copier'
 require_relative 'dns_command'
 require_relative 'apex_dns_sync'
+require_relative 'db_migrate_command'
 
 module Belt
   module CLI
     class DeployCommand
       DEFAULT_DOCKER_BUILD_IMAGE = 'public.ecr.aws/sam/build-ruby3.4:latest-x86_64'
+      BELT_EXE = File.expand_path('../../../exe/belt', __dir__)
       def self.run(args)
         # Handle `belt deploy frontend <env>` as before
         if args.first == 'frontend'
@@ -33,6 +35,7 @@ module Belt
         rebuild = false
         skip_backup = false
         backup_only = false
+        skip_migrations = false
         filtered_args = []
 
         args.each do |arg|
@@ -45,6 +48,8 @@ module Belt
             skip_backup = true
           when '--backup-only'
             backup_only = true
+          when '--skip-migrations'
+            skip_migrations = true
           when '-h', '--help'
             puts help_text
             exit 0
@@ -79,12 +84,13 @@ module Belt
           end
         end
 
+        options = { auto_approve: auto_approve, skip_migrations: skip_migrations, extra_args: filtered_args }
         if backup_only
-          new(env, auto_approve: auto_approve, skip_backup: false, extra_args: filtered_args).run_backup_only
+          new(env, **options, skip_backup: false).run_backup_only
         elsif rebuild
-          new(env, auto_approve: auto_approve, skip_backup: skip_backup, extra_args: filtered_args).run_rebuild
+          new(env, **options, skip_backup: skip_backup).run_rebuild
         else
-          new(env, auto_approve: auto_approve, skip_backup: skip_backup, extra_args: filtered_args).run
+          new(env, **options, skip_backup: skip_backup).run
         end
       end
 
@@ -105,6 +111,7 @@ module Belt
             7. Prompt for confirmation (unless --auto)
             8. terraform apply   (deploy changes)
             9. Nested envs: share parent Cognito + copy DynamoDB if empty
+           10. Run pending data migrations in db/migrate (see `belt db:migrate`)
 
           Options:
             --auto, --yes, -y    Skip confirmation prompt (auto-approve)
@@ -114,6 +121,7 @@ module Belt
             --skip-backup        Skip pre-deploy backup phase
             --no-backup          Alias for --skip-backup
             --backup-only        Run backups only, do not deploy
+            --skip-migrations    Don't run pending db/migrate data migrations
             -h, --help           Show this help
 
           Environment:
@@ -144,10 +152,11 @@ module Belt
         HELP
       end
 
-      def initialize(env, auto_approve: false, skip_backup: false, extra_args: [])
+      def initialize(env, auto_approve: false, skip_backup: false, skip_migrations: false, extra_args: [])
         @env = env
         @auto_approve = auto_approve
         @skip_backup = skip_backup
+        @skip_migrations = skip_migrations
         @extra_args = extra_args
         @infra_dir = TerraformCommand.find_infrastructure_dir
         @project_root = find_project_root
@@ -188,9 +197,12 @@ module Belt
 
         run_nested_env_hooks
 
+        migrations_ok = run_migrations
+
         deploy_frontend_if_exists
 
         puts "\n   Run `belt server` to view your app locally (auto-connects to the deployed API)."
+        exit 1 unless migrations_ok
       end
 
       def run_backup_only
@@ -232,6 +244,7 @@ module Belt
         ensure_lockfile_consistent!
         generate_routes(lambda_dir)
         build_and_deploy(lambda_dir, function_name)
+        exit 1 unless run_migrations
       end
 
       private
@@ -901,6 +914,36 @@ module Belt
         [raw, sanitized].uniq
       end
 
+      # Runs pending db/migrate data migrations in a child `belt db:migrate`
+      # so the app's code is booted in its own process, not the deployer's.
+      # Runs after the nested-env DynamoDB copy so copied rows get migrated
+      # too. Returns false on failure: the infra is already live, so the rest
+      # of the deploy continues and the exit status reports the failure.
+      def run_migrations # rubocop:disable Naming/PredicateMethod
+        return true if @skip_migrations || !DbMigrateCommand.migrations?(@project_root)
+
+        puts "\n━━━ data migrations ━━━"
+        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/explain_command.rb

@@ -52,6 +52,10 @@ module Belt
         'db:copy' => 'data_seeding',
         'copy' => 'data_seeding',
         'db_copy' => 'data_seeding',
+        'migration' => 'migrations',
+        'migrate' => 'migrations',
+        'db:migrate' => 'migrations',
+        'data_migrations' => 'migrations',
         'e2e' => 'testing',
         'test' => 'testing',
         'tests' => 'testing',
@@ -120,6 +124,7 @@ module Belt
             irb, repl                 → console
             seeds, seed, db:seed      → data_seeding
             db:copy, copy             → data_seeding
+            migrate, db:migrate       → migrations
             e2e, test, harness        → testing
 
           Examples:

data/lib/belt/cli/migration_store.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'time'
+
+module Belt
+  module CLI
+    # Records which data migrations have run against an environment, as one
+    # SSM parameter per version:
+    #
+    #   /belt/<app>/<env>/schema_migrations/<version>
+    #
+    # SSM rather than a DynamoDB table so the record isn't part of the
+    # `<app>-<env>-*` tables that `belt db:copy` and the nested-env copy move
+    # between environments — each stack keeps its own history.
+    class MigrationStore
+      class Error < StandardError; end
+
+      def initialize(app_name:, env:)
+        @app_name = app_name
+        @env = env
+      end
+
+      def path
+        "/belt/#{@app_name}/#{@env}/schema_migrations"
+      end
+
+      # Versions already applied to this environment, as strings.
+      def applied_versions
+        data = aws_json('ssm', 'get-parameters-by-path', '--path', path, '--output', 'json')
+        Array(data['Parameters']).map { |param| File.basename(param['Name']) }
+      end
+
+      def record!(version, name)
+        value = JSON.generate('name' => name, 'applied_at' => Time.now.utc.iso8601)
+        aws_json('ssm', 'put-parameter', '--name', "#{path}/#{version}", '--type', 'String',
+                 '--value', value, '--overwrite', '--output', 'json')
+      end
+
+      private
+
+      def aws_json(*args)
+        command = "aws #{args.first(2).join(' ')}"
+        output, error, status = Open3.capture3('aws', *args)
+        raise Error, "#{command} failed: #{error.strip}" unless status.success?
+
+        output.strip.empty? ? {} : JSON.parse(output)
+      rescue JSON::ParserError => e
+        raise Error, "#{command} returned invalid JSON: #{e.message}"
+      end
+    end
+  end
+end

data/lib/belt/cli.rb

@@ -26,10 +26,12 @@ require_relative 'cli/tasks_command'
 require_relative 'cli/console_command'
 require_relative 'cli/db_copy_command'
 require_relative 'cli/db_seed_command'
+require_relative 'cli/db_migrate_command'
 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
@@ -43,6 +45,8 @@ module Belt
       %w[console c] => Belt::CLI::ConsoleCommand,
       'db:copy' => Belt::CLI::DbCopyCommand,
       'db:seed' => Belt::CLI::DbSeedCommand,
+      'db:migrate' => Belt::CLI::DbMigrateCommand,
+      'db:migrate:status' => ->(args) { Belt::CLI::DbMigrateCommand.run(args, status: true) },
       'logs' => Belt::CLI::LogsCommand,
       %w[tasks --tasks -T] => Belt::CLI::TasksCommand,
       'setup' => Belt::CLI::SetupCommand,
@@ -53,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|
@@ -63,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
@@ -73,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)
@@ -82,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?
@@ -99,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]
 
@@ -131,6 +174,8 @@ module Belt
           c                                           Alias for console
           db:copy <from-env> <to-env> [--force]        Copy DynamoDB data between environments
           db:seed [environment] [--force]              Run config/seeds.rb against an environment
+          db:migrate [environment] [--yes]             Run pending db/migrate data migrations
+          db:migrate:status [environment]              Show which data migrations have run
           logs [lambda] [-f] [-s 5m] [-e env]         View Lambda function logs
           tasks [-g PATTERN] [-a]                     List available rake tasks
           -T [-g PATTERN] [-a]                        Alias for tasks
@@ -146,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:
@@ -180,6 +226,8 @@ module Belt
           belt db:copy prod dev --force # overwrite dev tables even if non-empty
           belt db:seed                  # run config/seeds.rb against dev (or BELT_ENV)
           belt db:seed dev01
+          belt db:migrate prod          # run pending data migrations against prod
+          belt db:migrate:status dev01
       USAGE
     end
 

data/lib/belt/docs/data_seeding.md

@@ -126,4 +126,5 @@ file, no generator required.
 
 - `belt explain backups` — recovery-point snapshots, not data seeding
 - `belt explain console` — the app-booting mechanism `db:seed` reuses
+- `belt explain migrations` — changing rows already in a deployed env
 - `belt explain deployment` — nested environments and the parent → child copy hook

data/lib/belt/docs/deployment.md

@@ -11,6 +11,7 @@ belt deploy <env>              # init → plan → apply (interactive)
 belt deploy prod --auto        # skip confirmation prompt
 belt deploy prod --skip-backup # skip pre-deploy backup
 belt deploy --backup-only      # create recovery point without deploying
+belt deploy dev --skip-migrations # don't run pending db/migrate migrations
 ```
 
 ## First-Time Setup
@@ -147,6 +148,14 @@ end
 Backups run automatically before each deploy (DynamoDB snapshots, Cognito
 exports, S3 syncs). See `belt explain backups` for full documentation.
 
+## Data Migrations
+
+After terraform apply (and the nested-env data copy), `belt deploy` runs any
+pending `db/migrate/<timestamp>_<name>.rb` data migrations against the env,
+each exactly once per environment. A failing migration doesn't roll back the
+deploy; it's reported and the command exits non-zero. Run them by hand with
+`belt db:migrate <env>`. See `belt explain migrations`.
+
 ## Environment Variables
 
 Set `BELT_ENV` to avoid typing the environment every time:
@@ -176,4 +185,5 @@ deploys every configured frontend after terraform apply.
 
 - `belt explain routing` — how routes map to infrastructure
 - `belt explain backups` — pre-deploy backup configuration
+- `belt explain migrations` — data migrations run after deploy
 - `belt doctor` — check system dependencies before deploying

data/lib/belt/docs/migrations.md

@@ -0,0 +1,104 @@
+# Data Migrations
+
+`belt setup tables` handles the *shape* of a table (keys, GSIs). Data
+migrations handle the *rows already in it*: backfilling a new attribute, or
+populating a new index for records written before it existed.
+
+They live in `db/migrate/`, run automatically after `belt deploy <env>`, and
+each one runs **exactly once per environment** — prod, dev and every nested
+(PR-preview) env keep their own history.
+
+## Writing a migration
+
+One file per migration, named `<timestamp>_<snake_case_name>.rb`, defining a
+`Belt::Migration` subclass named after the file:
+
+```ruby
+# db/migrate/20261030120000_index_usernames.rb
+class IndexUsernames < Belt::Migration
+  def up
+    PoshNosh::MatchStore.new.index_usernames!
+    say 'usernames indexed'
+  end
+end
+```
+
+`up` runs in the same booted app context as `belt console`
+(`lambda/config/environment.rb`, or `lambda/lib` + `lambda/models`), with
+`ENVIRONMENT` set to the target env, so models talk to that env's tables.
+`say` prints an indented progress line.
+
+Use `date -u +%Y%m%d%H%M%S` for the timestamp. Migrations run in timestamp
+order.
+
+## Running them
+
+```bash
+belt deploy dev                  # runs pending migrations after terraform apply
+belt deploy dev --skip-migrations
+
+belt db:migrate                  # dev, or $BELT_ENV if set
+belt db:migrate dev01
+belt db:migrate prod             # prompts for confirmation (--yes to skip)
+belt db:migrate:status prod      # which versions are up / down
+```
+
+```
+ Status   Migration ID    Migration Name
+--------------------------------------------------
+  up      20261030120000  Index usernames
+  down    20261102090000  Backfill display names
+```
+
+During `belt deploy`, migrations run after terraform apply and the
+nested-environment data copy (so rows copied from the parent get migrated
+too), and before the frontend deploy. They also run after
+`belt deploy --rebuild`. Nothing happens if `db/migrate/` is empty.
+
+## Where history is kept
+
+Each applied version is an SSM parameter:
+
+```
+/belt/<app>/<env>/schema_migrations/<version>   → {"name": "...", "applied_at": "..."}
+```
+
+It lives in SSM rather than a DynamoDB table so `belt db:copy` and the
+nested-env copy (which move every `<app>-<env>-*` table) don't carry one env's
+history into another. The deploying credentials need
+`ssm:GetParametersByPath` and `ssm:PutParameter` on `/belt/<app>/*`.
+
+To re-run a migration, delete its parameter:
+
+```bash
+aws ssm delete-parameter --name /belt/myapp/dev/schema_migrations/20261030120000
+```
+
+## Failures
+
+A version is recorded only after `up` returns. If one raises, it and every
+later migration stay pending, and the command exits non-zero. In
+`belt deploy` the infrastructure is already live, so the deploy carries on
+(frontend included), prints a warning and exits 1 at the end. Fix the
+migration and run `belt db:migrate <env>`.
+
+## Write them idempotent and batch-safe
+
+Migrations run against live data, often while the previous code is still
+serving requests:
+
+- **Idempotent.** A migration that dies halfway is re-run from the start, and
+  two overlapping deploys can both run it. Only write rows that still need
+  the change, and make writes safe to repeat (set a value, don't increment).
+- **Batch-safe.** A GSI created in the same deploy may still be backfilling,
+  so don't query the index you're populating — page through the base table
+  and write in small batches. Expect throttling on big tables.
+- **Data only.** Keys, GSIs and table settings belong in Terraform
+  (`belt setup tables`). The deployed code should work both before and
+  after a migration runs.
+
+## See Also
+
+- `belt explain data_seeding` — `db:copy` and `db:seed`
+- `belt explain console` — the app-booting mechanism migrations reuse
+- `belt explain deployment` — the full deploy lifecycle

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/migration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Belt
+  # Base class for data migrations in `db/migrate/<timestamp>_<name>.rb`.
+  #
+  #   # db/migrate/20261030120000_index_usernames.rb
+  #   class IndexUsernames < Belt::Migration
+  #     def up
+  #       PoshNosh::MatchStore.new.index_usernames!
+  #     end
+  #   end
+  #
+  # `belt deploy <env>` runs pending migrations after terraform apply, and
+  # `belt db:migrate <env>` runs them by hand. Each version runs once per
+  # environment (nested envs included); applied versions are recorded in SSM.
+  #
+  # Migrations touch live data, possibly while a new GSI is still backfilling
+  # or the previous code is still serving requests, so `up` must be
+  # idempotent (safe to re-run after a partial failure) and batch-safe (page
+  # through the base table rather than querying a GSI it is populating).
+  class Migration
+    attr_reader :version, :name
+
+    def initialize(version:, name:)
+      @version = version
+      @name = name
+    end
+
+    def up
+      raise NotImplementedError, "#{self.class.name} must define #up"
+    end
+
+    def say(message)
+      puts "    #{message}"
+    end
+  end
+end

data/lib/belt/version.rb

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

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

@@ -137,6 +137,7 @@ 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 db:migrate <env>                                  # Run pending db/migrate data migrations (deploy does this too)
 belt logs <lambda> [-f] [-s 5m] [-e env]               # View Lambda logs
 belt doctor                                            # Check dependencies
 ```
@@ -269,7 +270,8 @@ belt deploy <env>                 # Deploy everything (init → plan → apply)
 | `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>` |
+| Schema migrations | `belt setup tables <env>` |
+| Data migrations (`rails db:migrate`) | `db/migrate/*.rb` + `belt db:migrate <env>` (run by `belt deploy`) |
 | `has_many` / `belongs_to` | Manual (no joins in DynamoDB) |
 | Template rendering | JSON responses (default) |
 

data/references/cli.md

@@ -21,13 +21,15 @@ default environment so you can omit the `<env>` argument.
 | `belt doctor` | Check system deps + AWS config. |
 | `belt plugin new <name>` | Scaffold a Belt plugin gem. |
 | `belt explain <topic>` | Explain a concept (see topic list below). |
-| `belt deploy [env] [--auto] [--skip-backup] [--backup-only]` | Deploy to AWS (init → plan → apply, runs backups first if configured). |
+| `belt deploy [env] [--auto] [--skip-backup] [--backup-only] [--skip-migrations]` | Deploy to AWS (init → plan → apply, runs backups first if configured, data migrations after). |
 | `belt deploy frontend <env> [--frontend NAME]` | Build + deploy frontend(s). |
 | `belt dns <deploy\|add <env>\|show>` | Manage the root DNS zone. |
 | `belt frontend <env <env>\|list>` | Write `<frontend>/.env` from TF outputs, or list frontends. |
 | `belt server [--frontend NAME]` (alias `s`) | Start local dev server. |
 | `belt db:copy <from> <to> [--force]` | Copy DynamoDB data between environments. |
 | `belt db:seed [env] [--force]` | Run `config/seeds.rb` against an environment. |
+| `belt db:migrate [env] [--yes]` | Run pending `db/migrate` data migrations (also runs after `belt deploy`). |
+| `belt db:migrate:status [env]` | Show which data migrations have run against an environment. |
 | `belt version` | Show Belt version. |
 
 ### Terraform shorthand

data/references/deploy-and-ops.md

@@ -64,6 +64,18 @@ belt db:seed [env] [--force]     # run config/seeds.rb in the booted console con
 `db:copy` skips non-empty destination tables by default. `db:seed` refuses to
 run against an env that already has data unless `--force`.
 
+## Data migrations
+
+```bash
+belt db:migrate [env] [--yes]    # run pending db/migrate/<timestamp>_<name>.rb
+belt db:migrate:status [env]     # up/down per version
+```
+
+`belt deploy` runs pending migrations after apply (`--skip-migrations` to
+opt out). Each version runs once per env, recorded in SSM at
+`/belt/<app>/<env>/schema_migrations/<version>`. Write them idempotent and
+batch-safe: see `belt explain migrations`.
+
 ## Observability
 
 `Belt::LambdaHandler` wires these global facades automatically:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.4
 platform: ruby
 authors:
 - Stowzilla
@@ -118,9 +118,11 @@ 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
+- lib/belt/cli/db_migrate_command.rb
 - lib/belt/cli/db_seed_command.rb
 - lib/belt/cli/deploy_command.rb
 - lib/belt/cli/destroy_command.rb
@@ -142,6 +144,7 @@ files:
 - lib/belt/cli/index_command.rb
 - lib/belt/cli/lambda_config_command.rb
 - lib/belt/cli/logs_command.rb
+- lib/belt/cli/migration_store.rb
 - lib/belt/cli/nested_environment.rb
 - lib/belt/cli/new_command.rb
 - lib/belt/cli/path_gem_materializer.rb
@@ -168,6 +171,7 @@ files:
 - lib/belt/docs/frontend.md
 - lib/belt/docs/generators.md
 - lib/belt/docs/lambda_handler.md
+- lib/belt/docs/migrations.md
 - lib/belt/docs/models.md
 - lib/belt/docs/observability.md
 - lib/belt/docs/plugins.md
@@ -181,6 +185,7 @@ files:
 - lib/belt/http_status.rb
 - lib/belt/inflector.rb
 - lib/belt/lambda_handler.rb
+- lib/belt/migration.rb
 - lib/belt/observability.rb
 - lib/belt/parameters.rb
 - lib/belt/rendering.rb