belt 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a4efb62a37845ad3c311558cebdd71fcf74ba7ae31870f3c2728e286dc33a72
-  data.tar.gz: 8278be1ba1c44b6d355d00963ca1d33c401749b0af584a4cb5c07f6ae25bca54
+  metadata.gz: 1436a1cb03096bd9de50abd65ecfbb973fc0f054c7e45902bdadd78516806a0c
+  data.tar.gz: 88ddfe6f1b1789a539bd71d407a736514ef091d2b126fc8c3296e5ee2f4e23ca
 SHA512:
-  metadata.gz: b3d9d4782cd23143c6674b674780072784077105eeef396ec04d55b194ef102c643c5cd646311cdf024983c1e1a7f70407bea5bb2e0cb5261938e58d0dcceb87
-  data.tar.gz: a7e6cc11a4e2625b135cf967af4f614dcaa21fd7ee7b8cfcbea42bd68eea8976368a6392e257f2f229f8a6e9673414546044628cefa1f4fe0d6a2d9042b0b90f
+  metadata.gz: a5e7bee23ca7077b19273c9c7605da6c42a1ec8226332d629a6d7a51b9f3ece913cc415005b905a32774eb0b8e47159fa2abeee08e5b3b4888008981a116ad82
+  data.tar.gz: 33ffbdc6d97e3600f09d90877d0edde784f2d5b377d3250d4044ff456256ecb7642936f7c4531b47dc88d7be69c6160e3b694873a6f7d712fb532e62cbb97d85

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## Unreleased
+
+### Bug Fix
+
+- **`belt deploy frontend` now explains *why* the S3 bucket lookup failed.**
+  Previously any nil bucket output produced the same misleading
+  `Could not determine S3 bucket. Run belt apply <env> first.` — even when the env
+  had simply never been applied, or when the AWS profile/SSO session had expired.
+  `fetch_tf_output` swallows terraform's stderr, so the real cause was invisible.
+  The frontend deploy now re-probes terraform with stderr captured and emits a
+  targeted message for three cases: no Terraform state yet (provision the backend
+  first), a credential/SSO failure (fix the `aws_profile` / run `aws sso login`),
+  or an applied backend that's missing the frontend's bucket output (check
+  `config/frontends.yml`). This surfaces most often during ephemeral environment
+  setup, where the frontend step can run before the backend is applied.
+
 ## 0.4.3
 
 ### Bug Fix
@@ -18,6 +34,42 @@
 
 ## Unreleased
 
+## 0.4.5
+
+### Feature
+
+- **`belt db:copy <from-env> <to-env>` — copy DynamoDB data between environments on demand.**
+  Promotes the `DynamoCopier` used by nested (PR-preview) deploys into a standalone
+  command, so you can pull one environment's data into another whenever you want
+  (e.g. prod data into dev for realistic seed data), not just on a nested-env deploy.
+  Matches tables by name suffix after stripping each environment's `<app>-<env>-`
+  prefix. Destination tables that already have data are skipped by default (safe to
+  re-run); pass `--force` to overwrite them. Source/destination AWS profiles are
+  resolved independently from each environment's `infrastructure/<env>/belt.rb`
+  (`config.aws_profile`), or overridden with `--from-profile` / `--to-profile` —
+  needed when source and destination live in different AWS accounts (e.g. prod vs.
+  dev). See `belt explain data_seeding`.
+
+  Cognito identities are per-environment (each environment has its own user pool,
+  so the same person has a different `sub` in each), so `db:copy` re-anchors
+  Cognito-sub foreign keys (e.g. a membership's `cognito_sub`) to the destination
+  environment's user with the matching email, and leaves the destination's own
+  `users` table untouched. Without this a copied row points at a `sub` that doesn't
+  exist in the destination pool and silently vanishes (a copied project you can't
+  see). Rows whose email has no destination user yet have the stale sub cleared so
+  they read as unclaimed (e.g. a pending invitation) rather than dangling. The same
+  re-anchoring now runs in the nested-env deploy hook. Pass `--no-remap-identity` to
+  copy those references verbatim.
+
+- **`belt db:seed [environment]` — Rails-style `config/seeds.rb`.**
+  Loads `config/seeds.rb` in the same booted context `belt console` uses (models,
+  ActiveItem, `ENVIRONMENT` set), targeting the resolved environment's tables.
+  Honours `BELT_ENV` or an explicit environment argument, and prompts for
+  confirmation against `prod` like `belt console` does. Refuses to run if the
+  target environment already has data in any matching table — pass `--force` to
+  seed anyway (seeds.rb is responsible for its own idempotency if re-run).
+  `belt new` now scaffolds a starter `config/seeds.rb` with usage notes.
+
 ## 0.4.4
 
 ### Bug Fix

data/README.md

@@ -701,6 +701,36 @@ 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.
 
+## Data Seeding
+
+Two ways to get realistic data into an environment without hand-crafting rows.
+
+### `belt db:copy` — copy data between environments
+
+```bash
+belt db:copy prod dev            # copy prod's DynamoDB data into dev
+belt db:copy prod dev --force    # overwrite dev tables even if non-empty
+```
+
+Matches tables by name after stripping each environment's `<app>-<env>-` prefix. Destination tables that already have data are skipped by default (safe to re-run). AWS profiles are resolved per-environment from `infrastructure/<env>/belt.rb`, or overridden with `--from-profile` / `--to-profile` — useful when source and destination live in different AWS accounts (e.g. prod vs. dev).
+
+### `belt db:seed` — Rails-style seed file
+
+```bash
+belt db:seed              # seeds dev, or $BELT_ENV if set
+belt db:seed dev01
+```
+
+Loads `config/seeds.rb` in the same booted context `belt console` uses — models are available, targeting the resolved environment's tables:
+
+```ruby
+# config/seeds.rb
+post = Post.create!(title: "Hello, world", body: "Seeded post")
+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.
+
 ## 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.

data/lib/belt/cli/db_copy_command.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative 'app_detection'
+require_relative 'environment_config'
+require_relative 'dynamo_copier'
+
+module Belt
+  module CLI
+    # `belt db:copy <from-env> <to-env>` — copies DynamoDB table contents from
+    # one environment into another on demand (e.g. pulling prod data into dev
+    # for realistic seed data).
+    #
+    # Reuses the same DynamoCopier used by the nested-environment deploy hook,
+    # but resolves table prefixes and AWS profiles for two arbitrary
+    # environments instead of a parent/child pair. Prod and dev commonly live
+    # in separate AWS accounts, so source and destination profiles are
+    # resolved independently (from each environment's `belt.rb`, with
+    # `--from-profile` / `--to-profile` available to override).
+    class DbCopyCommand
+      include AppDetection
+
+      def self.run(args)
+        new(args).run
+      end
+
+      def initialize(args)
+        @options = { force: false, remap_identity: true }
+        parse_options(args)
+      end
+
+      def run
+        unless @from_env && @to_env
+          puts usage
+          exit 1
+        end
+
+        abort "Error: source and destination environment are the same ('#{@from_env}')." if @from_env == @to_env
+
+        app_name = detect_app_name
+
+        from_profile = @options[:from_profile] || EnvironmentConfig.load(@from_env, infra_dir: infra_dir).aws_profile
+        to_profile = @options[:to_profile] || EnvironmentConfig.load(@to_env, infra_dir: infra_dir).aws_profile
+
+        puts "belt → copying DynamoDB data: #{@from_env} → #{@to_env}"
+        puts "  from profile: #{from_profile || '(current credentials)'}"
+        puts "  to profile:   #{to_profile || '(current credentials)'}"
+        puts ''
+
+        success = DynamoCopier.new(
+          from_prefixes: prefixes_for(app_name, @from_env),
+          to_prefixes: prefixes_for(app_name, @to_env),
+          from_profile: from_profile,
+          to_profile: to_profile,
+          force: @options[:force],
+          remap_identity: @options[:remap_identity],
+          label: "#{@from_env} → #{@to_env}"
+        ).run
+
+        abort "\n✗ db:copy finished with errors" unless success
+
+        puts "\n✅ db:copy complete"
+      end
+
+      private
+
+      def infra_dir
+        'infrastructure'
+      end
+
+      def prefixes_for(app_name, env_name)
+        raw = "#{app_name}-#{env_name}-"
+        sanitized = raw.tr('_', '-').downcase
+        [raw, sanitized].uniq
+      end
+
+      def parse_options(args)
+        OptionParser.new do |opts|
+          opts.banner = 'Usage: belt db:copy <from-env> <to-env> [options]'
+
+          opts.on('--force', 'Overwrite destination tables that already have data') do
+            @options[:force] = true
+          end
+
+          opts.on('--no-remap-identity',
+                  'Copy Cognito-sub foreign keys verbatim instead of re-anchoring ' \
+                  "them to the destination environment's users by email") do
+            @options[:remap_identity] = false
+          end
+
+          opts.on('--from-profile PROFILE', 'AWS profile to read the source environment with') do |profile|
+            @options[:from_profile] = profile
+          end
+
+          opts.on('--to-profile PROFILE', 'AWS profile to write the destination environment with') do |profile|
+            @options[:to_profile] = profile
+          end
+
+          opts.on('-h', '--help', 'Show this help') do
+            puts opts
+            exit
+          end
+        end.parse!(args)
+
+        @from_env = args.shift
+        @to_env = args.shift
+      end
+
+      def usage
+        <<~USAGE
+          Usage: belt db:copy <from-env> <to-env> [options]
+
+          Copy DynamoDB table contents from one environment into another.
+          Matches tables by name suffix after stripping each environment's
+          `<app>-<env>-` prefix (e.g. myapp-prod-posts → myapp-dev-posts).
+
+          By default, destination tables that already contain data are
+          skipped (safe to re-run). Use --force to overwrite them.
+
+          Cognito identities are per-environment: each environment has its own
+          user pool, so the same person has a different `sub` in each one. By
+          default db:copy re-anchors Cognito-sub foreign keys (e.g. a
+          membership's cognito_sub) to the destination environment's user with
+          the same email, and leaves the destination's own `users` table
+          untouched. Without this, copied rows would point at subs that don't
+          exist in the destination pool and silently disappear (a copied
+          project you can't see, etc.). Pass --no-remap-identity to copy those
+          references verbatim.
+
+          AWS profiles are resolved from each environment's
+          infrastructure/<env>/belt.rb (config.aws_profile), or overridden
+          with --from-profile / --to-profile — useful when source and
+          destination live in different AWS accounts.
+
+          Options:
+            --force                    Overwrite destination tables with existing data
+            --no-remap-identity        Copy Cognito-sub foreign keys verbatim
+            --from-profile PROFILE     AWS profile for reading the source environment
+            --to-profile PROFILE       AWS profile for writing the destination environment
+            -h, --help                 Show this help
+
+          Examples:
+            belt db:copy prod dev
+            belt db:copy prod dev --force
+            belt db:copy prod dev01 --from-profile prod-readonly --to-profile dev
+        USAGE
+      end
+    end
+  end
+end

data/lib/belt/cli/db_seed_command.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'optparse'
+require_relative 'app_detection'
+require_relative 'environment_config'
+
+module Belt
+  module CLI
+    # `belt db:seed` — Rails-style `rails db:seed` for Belt apps.
+    #
+    # Loads config/seeds.rb in the same booted app context `belt console`
+    # uses (models required, ActiveItem configured), targeting the resolved
+    # environment's DynamoDB tables (`<app>-<env>-*`).
+    #
+    # Refuses to run against an environment that already has data in any of
+    # its tables, to avoid silently clobbering a live environment — pass
+    # --force to seed anyway (seeds.rb itself is responsible for being
+    # idempotent if re-run).
+    class DbSeedCommand
+      include AppDetection
+
+      SEEDS_FILE = File.join('config', 'seeds.rb')
+
+      def self.run(args)
+        new(args).run
+      end
+
+      def initialize(args)
+        @options = { force: 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
+
+        unless File.exist?(SEEDS_FILE)
+          abort "Error: No #{SEEDS_FILE} found. Create one to define your seed data " \
+                '(see `belt explain seeds` for an example).'
+        end
+
+        @environment = @env_arg || ENV.fetch('BELT_ENV', nil) || 'dev'
+        ENV['ENVIRONMENT'] = @environment
+
+        apply_env_config!
+        production_guard!
+        guard_against_existing_data! unless @options[:force]
+
+        boot_app
+
+        puts "belt → seeding #{@environment} from #{SEEDS_FILE}"
+        load File.expand_path(SEEDS_FILE)
+        puts "✅ Seed complete (#{@environment})"
+      end
+
+      private
+
+      def parse_options(args)
+        OptionParser.new do |opts|
+          opts.banner = 'Usage: belt db:seed [environment] [options]'
+
+          opts.on('--force', "Seed even if the environment's tables already have data") do
+            @options[:force] = 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 production_guard!
+        return unless @environment == 'prod'
+
+        $stdout.write "\n⚠️  WARNING: You are about to seed the PRODUCTION environment!\nType 'yes' to continue: "
+        response = $stdin.gets&.chomp
+        abort "\n❌ Cancelled." unless response&.downcase == 'yes'
+      end
+
+      # Refuses to seed if any table matching this environment's prefix
+      # already contains data — avoids clobbering an environment someone
+      # already loaded with real (or prior seed) data.
+      def guard_against_existing_data!
+        app_name = detect_app_name
+        prefixes = prefixes_for(app_name, @environment)
+        tables = list_tables.select { |name| prefixes.any? { |prefix| name.start_with?(prefix) } }
+
+        non_empty = tables.select { |t| table_has_items?(t) }
+        return if non_empty.empty?
+
+        abort "Error: #{@environment} already has data in: #{non_empty.join(', ')}.\n" \
+              'Refusing to seed a non-empty environment. Pass --force to seed anyway ' \
+              '(seeds.rb is responsible for being idempotent).'
+      end
+
+      def prefixes_for(app_name, env_name)
+        raw = "#{app_name}-#{env_name}-"
+        sanitized = raw.tr('_', '-').downcase
+        [raw, sanitized].uniq
+      end
+
+      def list_tables
+        names = []
+        start_name = nil
+        loop do
+          args = ['dynamodb', 'list-tables', '--output', 'json']
+          args += ['--exclusive-start-table-name', start_name] if start_name
+          data = aws_json(*args)
+          return names if data.nil?
+
+          names.concat(Array(data['TableNames']))
+          start_name = data['LastEvaluatedTableName']
+          break if start_name.nil? || start_name.empty?
+        end
+        names
+      end
+
+      def table_has_items?(table_name)
+        data = aws_json('dynamodb', 'scan', '--table-name', table_name,
+                        '--select', 'COUNT', '--limit', '1', '--output', 'json')
+        return false if data.nil?
+
+        data.fetch('Count', 0).to_i.positive?
+      end
+
+      def aws_json(*)
+        output, status = Open3.capture2('aws', *)
+        return nil unless status.success?
+
+        JSON.parse(output)
+      rescue JSON::ParserError
+        nil
+      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

@@ -778,7 +778,26 @@ module Belt
 
         puts "\n━━━ nested environment (parent: #{nested.parent}) ━━━"
         CognitoSharer.new(nested).run
-        DynamoCopier.new(nested, app_name: detect_app_name_for_backup).run
+
+        app_name = detect_app_name_for_backup
+        parent_profile = EnvironmentConfig.load(nested.parent, infra_dir: @infra_dir).aws_profile
+        child_profile = EnvironmentConfig.load(nested.env, infra_dir: @infra_dir).aws_profile
+
+        DynamoCopier.new(
+          from_prefixes: prefixes_for(app_name, nested.parent),
+          to_prefixes: prefixes_for(app_name, nested.env),
+          from_profile: parent_profile,
+          to_profile: child_profile,
+          label: "#{nested.parent} → #{nested.env}"
+        ).run
+      end
+
+      # Both the raw and S3/DNS-safe (underscore→dash, lowercased) forms of the
+      # table-name prefix, since app names may contain underscores.
+      def prefixes_for(app_name, env_name)
+        raw = "#{app_name}-#{env_name}-"
+        sanitized = raw.tr('_', '-').downcase
+        [raw, sanitized].uniq
       end
 
       def deploy_frontend_if_exists

data/lib/belt/cli/dynamo_copier.rb

@@ -3,23 +3,60 @@
 require 'json'
 require 'open3'
 require 'tempfile'
-require_relative 'nested_environment'
 
 module Belt
   module CLI
-    # Copies DynamoDB items from a parent environment into a nested child.
+    # Copies DynamoDB items between two sets of tables identified by name
+    # prefix (typically `<app>-<env>-`). Used both by the nested-environment
+    # (PR preview) deploy hook and the standalone `belt db:copy` command.
     #
-    # Copy is skipped when the child table already has any items, so a PR
-    # sync / second deploy will not clobber test data. If a copy fails the
-    # child table is wiped (it was empty when we started) so the next deploy
-    # retries.
+    # By default, copy is skipped when the destination table already has any
+    # items, so re-running against a live environment will not clobber data.
+    # Pass `force: true` to overwrite non-empty destination tables anyway.
+    # If a copy fails, the destination table is wiped back to its starting
+    # state (empty, or restored — best effort) so a retry starts clean.
     class DynamoCopier
       BATCH_SIZE = 25
       MAX_RETRIES = 8
 
-      def initialize(nested_env, app_name:)
-        @nested = nested_env
-        @app_name = app_name
+      # Belt's `cognito_authenticatable` convention: the identity table is
+      # `<app>-<env>-users`, its primary key attribute is `id` (the Cognito
+      # `sub`), and it carries an `email` attribute. A Cognito `sub` is unique
+      # *per user pool*, and each environment has its own pool — so the same
+      # human has a different `id` in every environment. Any row that
+      # references a user by sub therefore has a stale reference the moment it
+      # crosses an environment boundary.
+      #
+      # `cognito_sub` is the conventional foreign-key attribute name for that
+      # reference (see FeatureParity's Membership, Belt's invitation pattern).
+      # When a referencing row also carries an `email`, we can re-anchor it to
+      # the destination environment's user with the same email.
+      IDENTITY_TABLE_SUFFIX = 'users'
+      IDENTITY_ID_ATTR = 'id'
+      IDENTITY_EMAIL_ATTR = 'email'
+      IDENTITY_FK_ATTR = 'cognito_sub'
+
+      # from_prefixes / to_prefixes: array of candidate table-name prefixes
+      #   (the source/destination env's tables are matched against these).
+      # from_profile / to_profile: AWS_PROFILE to use when reading the source
+      #   / writing the destination, respectively (nil = use current
+      #   credentials / AWS_PROFILE already in the environment).
+      # label: short description used in log output (e.g. "dev01 → dev01-pr").
+      # remap_identity: when true, re-anchor Cognito-sub foreign keys to the
+      #   destination environment's users by email (see IDENTITY_* above). The
+      #   users table itself is left untouched so the destination keeps its own
+      #   pool's identities. Defaults to true — copying identity-referencing
+      #   rows verbatim across environments silently hides the data (the row
+      #   points at a sub that doesn't exist in the destination pool).
+      def initialize(from_prefixes:, to_prefixes:, from_profile: nil, to_profile: nil,
+                     force: false, label: nil, remap_identity: true)
+        @from_prefixes = Array(from_prefixes)
+        @to_prefixes = Array(to_prefixes)
+        @from_profile = from_profile
+        @to_profile = to_profile
+        @force = force
+        @label = label
+        @remap_identity = remap_identity
         @errors = []
       end
 
@@ -28,16 +65,17 @@ module Belt
         # rubocop:enable Naming/PredicateMethod
         pairs = table_pairs
         if pairs.empty?
-          puts '  ℹ  No parent DynamoDB tables found to copy'
+          puts '  ℹ  No matching DynamoDB tables found to copy'
           return true
         end
 
-        puts "  💾 Copying DynamoDB data from '#{@nested.parent}' (empty tables only)"
+        mode = @force ? 'overwriting existing data' : 'empty tables only'
+        puts "  💾 Copying DynamoDB data#{" (#{@label})" if @label} (#{mode})"
 
         copied = 0
         skipped = 0
-        pairs.each do |parent_table, child_table|
-          result = copy_pair(parent_table, child_table)
+        pairs.each do |source_table, dest_table|
+          result = copy_pair(source_table, dest_table)
           case result
           when :copied then copied += 1
           when :skipped then skipped += 1
@@ -51,55 +89,140 @@ module Belt
 
       private
 
-      def copy_pair(parent_table, child_table)
-        short = suffix_for(child_table, child_prefixes)
+      def copy_pair(source_table, dest_table)
+        short = suffix_for(dest_table, @to_prefixes)
 
-        unless table_exists?(child_table)
-          puts "    ⚠  #{short}: child table missing — skip"
+        # The identity (users) table is left alone when remapping: the
+        # destination environment's Cognito pool is authoritative for who its
+        # users are and what `sub` each one has. Overwriting it with the
+        # source pool's identities would create user rows that can never
+        # authenticate here (their sub belongs to the other pool).
+        if @remap_identity && identity_table?(short)
+          puts "    skip  #{short} (identity table — destination pool is authoritative)"
           return :skipped
         end
 
-        if table_has_items?(child_table)
+        unless table_exists?(dest_table, profile: @to_profile)
+          puts "    ⚠  #{short}: destination table missing — skip"
+          return :skipped
+        end
+
+        if !@force && table_has_items?(dest_table, profile: @to_profile)
           puts "    skip  #{short} (already has data)"
           return :skipped
         end
 
-        items = scan_items(parent_table)
+        items = scan_items(source_table, profile: @from_profile)
         if items.nil?
-          fail_table(short, "failed to scan parent #{parent_table}")
+          fail_table(short, "failed to scan source #{source_table}")
           return :failed
         end
 
         if items.empty?
-          puts "    skip  #{short} (parent empty)"
+          puts "    skip  #{short} (source empty)"
           return :skipped
         end
 
+        items, remapped, dropped = remap_identity_refs(items) if @remap_identity
+
         begin
-          write_items(child_table, items)
-          puts "    copy  #{short} (#{items.size} item#{'s' if items.size != 1})"
+          wipe_table(dest_table, profile: @to_profile) if @force
+          write_items(dest_table, items, profile: @to_profile)
+          suffix = ''
+          if @remap_identity && (remapped.to_i.positive? || dropped.to_i.positive?)
+            parts = []
+            parts << "#{remapped} re-anchored" if remapped.to_i.positive?
+            parts << "#{dropped} unmatched" if dropped.to_i.positive?
+            suffix = ", #{parts.join(', ')}"
+          end
+          puts "    copy  #{short} (#{items.size} item#{'s' if items.size != 1}#{suffix})"
           :copied
         rescue StandardError => e
-          wipe_table(child_table)
+          wipe_table(dest_table, profile: @to_profile)
           fail_table(short, e.message)
           :failed
         end
       end
 
+      def identity_table?(suffix)
+        suffix == IDENTITY_TABLE_SUFFIX
+      end
+
+      # Re-anchors Cognito-sub foreign keys to the destination environment's
+      # users. For each item that carries both an email and a `cognito_sub`,
+      # the sub is rewritten to the destination user with the same email. Items
+      # whose email has no destination user keep their attributes but have the
+      # stale sub cleared, so they surface as unclaimed (e.g. a pending
+      # invitation) rather than pointing at a nonexistent identity.
+      #
+      # Returns [items, remapped_count, dropped_count].
+      def remap_identity_refs(items)
+        map = destination_email_to_id
+        remapped = 0
+        dropped = 0
+
+        rewritten = items.map do |item|
+          fk = item[IDENTITY_FK_ATTR]
+          email_attr = item[IDENTITY_EMAIL_ATTR]
+          # Only touch rows that actually reference an identity by sub AND
+          # carry an email to re-anchor on. Everything else passes through.
+          next item unless fk.is_a?(Hash) && fk.key?('S') && !fk['S'].to_s.empty?
+          next item unless email_attr.is_a?(Hash) && !email_attr['S'].to_s.empty?
+
+          email = email_attr['S'].to_s.downcase
+          dest_id = map[email]
+
+          if dest_id
+            next item if dest_id == fk['S']
+
+            remapped += 1
+            item.merge(IDENTITY_FK_ATTR => { 'S' => dest_id })
+          else
+            dropped += 1
+            item.reject { |key, _| key == IDENTITY_FK_ATTR }
+          end
+        end
+
+        [rewritten, remapped, dropped]
+      end
+
+      # email (downcased) => destination user id (Cognito sub), built from the
+      # destination environment's users table as it exists right now.
+      def destination_email_to_id
+        @destination_email_to_id ||= begin
+          table = dest_identity_table
+          map = {}
+          if table
+            items = scan_items(table, profile: @to_profile) || []
+            items.each do |item|
+              email = item.dig(IDENTITY_EMAIL_ATTR, 'S')
+              id = item.dig(IDENTITY_ID_ATTR, 'S')
+              map[email.to_s.downcase] = id if email && id
+            end
+          end
+          map
+        end
+      end
+
+      def dest_identity_table
+        dest_tables = tables_with_prefixes(@to_prefixes, profile: @to_profile)
+        dest_tables.find { |name| suffix_for(name, @to_prefixes) == IDENTITY_TABLE_SUFFIX }
+      end
+
       def table_pairs
-        parent_tables = tables_with_prefixes(parent_prefixes)
-        child_tables = tables_with_prefixes(child_prefixes)
+        source_tables = tables_with_prefixes(@from_prefixes, profile: @from_profile)
+        dest_tables = tables_with_prefixes(@to_prefixes, profile: @to_profile)
         pairs = {}
 
-        parent_tables.each do |parent_table|
-          suffix = suffix_for(parent_table, parent_prefixes)
+        source_tables.each do |source_table|
+          suffix = suffix_for(source_table, @from_prefixes)
           next if suffix.empty?
 
-          child_prefixes.each do |prefix|
+          @to_prefixes.each do |prefix|
             candidate = "#{prefix}#{suffix}"
-            next unless child_tables.include?(candidate)
+            next unless dest_tables.include?(candidate)
 
-            pairs[parent_table] = candidate
+            pairs[source_table] = candidate
             break
           end
         end
@@ -107,20 +230,6 @@ module Belt
         pairs
       end
 
-      def parent_prefixes
-        @parent_prefixes ||= prefixes_for(@nested.parent)
-      end
-
-      def child_prefixes
-        @child_prefixes ||= prefixes_for(@nested.env)
-      end
-
-      def prefixes_for(env_name)
-        raw = "#{@app_name}-#{env_name}-"
-        sanitized = raw.tr('_', '-').downcase
-        [raw, sanitized].uniq
-      end
-
       def suffix_for(table_name, prefixes)
         prefixes.each do |prefix|
           return table_name.delete_prefix(prefix) if table_name.start_with?(prefix)
@@ -128,21 +237,22 @@ module Belt
         table_name
       end
 
-      def tables_with_prefixes(prefixes)
-        all_tables.select { |name| prefixes.any? { |prefix| name.start_with?(prefix) } }
+      def tables_with_prefixes(prefixes, profile:)
+        all_tables(profile: profile).select { |name| prefixes.any? { |prefix| name.start_with?(prefix) } }
       end
 
-      def all_tables
-        @all_tables ||= list_all_tables
+      def all_tables(profile:)
+        @all_tables ||= {}
+        @all_tables[profile] ||= list_all_tables(profile: profile)
       end
 
-      def list_all_tables
+      def list_all_tables(profile:)
         names = []
         start_name = nil
         loop do
           args = ['dynamodb', 'list-tables', '--output', 'json']
           args += ['--exclusive-start-table-name', start_name] if start_name
-          data = aws_json(*args)
+          data = aws_json(*args, profile: profile)
           return names if data.nil?
 
           names.concat(Array(data['TableNames']))
@@ -152,25 +262,25 @@ module Belt
         names
       end
 
-      def table_exists?(name)
-        all_tables.include?(name)
+      def table_exists?(name, profile:)
+        all_tables(profile: profile).include?(name)
       end
 
-      def table_has_items?(table_name)
+      def table_has_items?(table_name, profile:)
         data = aws_json('dynamodb', 'scan', '--table-name', table_name,
-                        '--select', 'COUNT', '--limit', '1', '--output', 'json')
+                        '--select', 'COUNT', '--limit', '1', '--output', 'json', profile: profile)
         return false if data.nil?
 
         data.fetch('Count', 0).to_i.positive?
       end
 
-      def scan_items(table_name)
+      def scan_items(table_name, profile:)
         items = []
         start_key = nil
         loop do
           args = ['dynamodb', 'scan', '--table-name', table_name, '--output', 'json']
           args += ['--exclusive-start-key', JSON.generate(start_key)] if start_key
-          data = aws_json(*args)
+          data = aws_json(*args, profile: profile)
           return nil if data.nil?
 
           items.concat(Array(data['Items']))
@@ -180,17 +290,17 @@ module Belt
         items
       end
 
-      def write_items(table_name, items)
+      def write_items(table_name, items, profile:)
         items.each_slice(BATCH_SIZE) do |batch|
           request = {
             table_name => batch.map { |item| { 'PutRequest' => { 'Item' => item } } }
           }
-          write_batch(request)
+          write_batch(request, profile: profile)
         end
       end
 
-      def write_batch(request_items, attempt = 0)
-        data = batch_write(request_items)
+      def write_batch(request_items, profile:, attempt: 0)
+        data = batch_write(request_items, profile: profile)
         raise "batch-write-item failed for #{request_items.keys.join(', ')}" if data.nil?
 
         unprocessed = data['UnprocessedItems']
@@ -198,24 +308,24 @@ module Belt
         raise "unprocessed items after #{MAX_RETRIES} retries" if attempt >= MAX_RETRIES
 
         sleep(0.2 * (2**attempt))
-        write_batch(unprocessed, attempt + 1)
+        write_batch(unprocessed, profile: profile, attempt: attempt + 1)
       end
 
-      def batch_write(request_items)
+      def batch_write(request_items, profile:)
         Tempfile.create(['belt-dynamo', '.json']) do |file|
           file.write(JSON.generate(request_items))
           file.flush
           aws_json('dynamodb', 'batch-write-item',
                    '--request-items', "file://#{file.path}",
-                   '--output', 'json')
+                   '--output', 'json', profile: profile)
         end
       end
 
-      def wipe_table(table_name)
-        items = scan_items(table_name)
+      def wipe_table(table_name, profile:)
+        items = scan_items(table_name, profile: profile)
         return if items.nil? || items.empty?
 
-        keys = key_attribute_names(table_name)
+        keys = key_attribute_names(table_name, profile: profile)
         return if keys.empty?
 
         items.each_slice(BATCH_SIZE) do |batch|
@@ -224,14 +334,14 @@ module Belt
               { 'DeleteRequest' => { 'Key' => item.slice(*keys) } }
             end
           }
-          batch_write(request)
+          batch_write(request, profile: profile)
         end
       rescue StandardError
         nil
       end
 
-      def key_attribute_names(table_name)
-        data = aws_json('dynamodb', 'describe-table', '--table-name', table_name, '--output', 'json')
+      def key_attribute_names(table_name, profile:)
+        data = aws_json('dynamodb', 'describe-table', '--table-name', table_name, '--output', 'json', profile: profile)
         return [] if data.nil?
 
         Array(data.dig('Table', 'KeySchema')).map { |key| key['AttributeName'] }.compact
@@ -239,11 +349,13 @@ module Belt
 
       def fail_table(short, message)
         @errors << "#{short}: #{message}"
-        puts "    ⚠  #{short}: #{message} (will retry on next deploy if table is empty)"
+        puts "    ⚠  #{short}: #{message}"
       end
 
-      def aws_json(*)
-        output, status = Open3.capture2('aws', *)
+      def aws_json(*args, profile: nil)
+        cmd = ['aws'] + args
+        cmd += ['--profile', profile] if profile && !profile.empty?
+        output, status = Open3.capture2(*cmd)
         return nil unless status.success?
 
         JSON.parse(output)

data/lib/belt/cli/explain_command.rb

@@ -44,7 +44,14 @@ module Belt
         'irb' => 'console',
         'repl' => 'console',
         'frontends' => 'frontend',
-        'spa' => 'frontend'
+        'spa' => 'frontend',
+        'seeds' => 'data_seeding',
+        'seed' => 'data_seeding',
+        'seeding' => 'data_seeding',
+        'db:seed' => 'data_seeding',
+        'db:copy' => 'data_seeding',
+        'copy' => 'data_seeding',
+        'db_copy' => 'data_seeding'
       }.freeze
 
       def self.run(args)
@@ -105,6 +112,8 @@ module Belt
             backup                    → backups
             plugin                    → plugins
             irb, repl                 → console
+            seeds, seed, db:seed      → data_seeding
+            db:copy, copy             → data_seeding
 
           Examples:
             belt explain routing

data/lib/belt/cli/frontend_deploy_command.rb

@@ -119,7 +119,7 @@ module Belt
 
       def sync_to_s3
         bucket = fetch_bucket_name
-        abort "Error: Could not determine S3 bucket. Run `belt apply #{@env}` first." unless bucket
+        abort(bucket_lookup_failure_message) unless bucket
 
         dist = @frontend.dist_dir
         unless Dir.exist?(dist)
@@ -161,6 +161,63 @@ module Belt
         fetch_tf_output(@frontend.bucket_output)
       end
 
+      # The bucket output came back nil. Figure out *why* instead of always
+      # blaming a missing apply. `terraform output` swallows its own stderr in
+      # fetch_tf_output, so re-run it once with stderr captured and translate the
+      # failure into something actionable:
+      #   - no state at all      → env was never applied (or wrong dir)
+      #   - credential/SSO error → the AWS profile/session is the problem
+      #   - output just missing  → applied, but this frontend's output isn't there
+      def bucket_lookup_failure_message
+        _out, err, _status = Open3.capture3(
+          'terraform', 'output', '-raw', @frontend.bucket_output.to_s,
+          chdir: @env_dir
+        )
+        stderr = err.to_s.strip
+        first_line = stderr.lines.first&.strip
+
+        if credential_error?(stderr)
+          [
+            "Error: Could not reach Terraform state for '#{@env}' — AWS credentials failed.",
+            "  #{first_line}",
+            "  Check the aws_profile in infrastructure/#{@env}/belt.rb and that its SSO " \
+            'session is active (`aws sso login --profile <profile>`).'
+          ].join("\n")
+        elsif no_state?(stderr) || !state_present?
+          [
+            "Error: No Terraform state for '#{@env}' yet — nothing to deploy the frontend against.",
+            "  Run `belt deploy #{@env}` to provision the backend first, then retry the frontend deploy."
+          ].join("\n")
+        else
+          lines = [
+            "Error: Terraform output `#{@frontend.bucket_output}` not found for '#{@env}'.",
+            "  The backend is applied but this frontend's bucket output is missing. " \
+            'Check config/frontends.yml and that the frontend module is included in terraform.'
+          ]
+          lines << "  terraform: #{first_line}" if first_line
+          lines.join("\n")
+        end
+      rescue Errno::ENOENT
+        "Error: `terraform` not found on PATH. Install Terraform, then run `belt deploy #{@env}` first."
+      end
+
+      def credential_error?(stderr)
+        stderr.match?(/credential|sso|token|AccessDenied|not authorized|403/i)
+      end
+
+      def no_state?(stderr)
+        stderr.match?(
+          /No state file|no outputs|state.*not.*found|Backend initialization required|not been initialized/i
+        )
+      end
+
+      # A locally-applied env has a terraform.tfstate; a remote-backed one has an
+      # initialized .terraform dir. Absence of both means it was never applied here.
+      def state_present?
+        File.exist?(File.join(@env_dir, 'terraform.tfstate')) ||
+          Dir.exist?(File.join(@env_dir, '.terraform'))
+      end
+
       def fetch_distribution_id
         if probe_distribution_output?
           id = fetch_tf_output(@frontend.distribution_output)

data/lib/belt/cli/new_command.rb

@@ -168,6 +168,7 @@ module Belt
           'lambda/lib/routes/routes.rb.erb' => "#{@app_name}/lambda/lib/routes/api_routes.rb",
           'config/routes.rb.erb' => "#{@app_name}/config/routes.rb",
           'config/contracts.rb.erb' => "#{@app_name}/config/contracts.rb",
+          'config/seeds.rb.erb' => "#{@app_name}/config/seeds.rb",
           'config/lambda/api.yml.erb' => "#{@app_name}/config/lambda/api.yml",
           'README.md.erb' => "#{@app_name}/README.md",
           'AGENTS.md.erb' => "#{@app_name}/AGENTS.md",

data/lib/belt/cli.rb

@@ -24,6 +24,8 @@ require_relative 'cli/contracts_command'
 require_relative 'cli/lambda_config_command'
 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/logs_command'
 require_relative 'cli/doctor_command'
 require_relative 'cli/plugin_command'
@@ -39,6 +41,8 @@ module Belt
       'contracts' => Belt::CLI::ContractsCommand,
       'lambda-config' => Belt::CLI::LambdaConfigCommand,
       %w[console c] => Belt::CLI::ConsoleCommand,
+      'db:copy' => Belt::CLI::DbCopyCommand,
+      'db:seed' => Belt::CLI::DbSeedCommand,
       'logs' => Belt::CLI::LogsCommand,
       %w[tasks --tasks -T] => Belt::CLI::TasksCommand,
       'setup' => Belt::CLI::SetupCommand,
@@ -125,6 +129,8 @@ module Belt
 
           console                                     Start an interactive console (IRB)
           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
           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
@@ -170,6 +176,10 @@ module Belt
           belt tasks                    # list all rake tasks
           belt lambda:build_layer       # run a rake task directly
           belt plugin new messaging     # scaffold a belt-messaging style plugin gem
+          belt db:copy prod dev         # copy prod's DynamoDB data into dev
+          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
       USAGE
     end
 

data/lib/belt/docs/data_seeding.md

@@ -0,0 +1,129 @@
+# Data Seeding
+
+Belt provides two ways to get data into an environment without hand-crafting
+rows: copying data from another environment, and Rails-style seed files.
+
+## `belt db:copy` — copy data between environments
+
+Copies DynamoDB table contents from one environment into another, matching
+tables by name after stripping each environment's `<app>-<env>-` prefix.
+
+```bash
+belt db:copy prod dev            # copy prod data into dev
+belt db:copy prod dev --force    # overwrite dev tables even if non-empty
+```
+
+By default, destination tables that already contain data are skipped — safe
+to re-run against a live environment. `--force` overwrites them instead.
+
+### Cognito identity re-anchoring
+
+Cognito identities are **per-environment**: each environment has its own user
+pool, so the same person has a *different* `sub` in every environment. Any row
+that references a user by their `sub` (e.g. a membership's `cognito_sub`) has a
+reference that's meaningless in another environment — copy it verbatim and the
+row points at a user who doesn't exist in the destination pool, so it silently
+disappears (a copied project you can't see, a member who isn't there).
+
+`belt db:copy` handles this automatically:
+
+- The destination's own `users` table is **left untouched** — the destination
+  pool is authoritative for who its users are and what `sub` each one has.
+- For every other table, any row carrying both an `email` and a `cognito_sub`
+  has its `cognito_sub` **re-anchored** to the destination user with the same
+  email.
+- A row whose email has no destination user yet has its stale `cognito_sub`
+  **cleared**, so it reads as unclaimed (e.g. a pending invitation Belt binds
+  on that person's first login) rather than dangling.
+
+```bash
+belt db:copy prod dev                     # re-anchors identities (default)
+belt db:copy prod dev --no-remap-identity # copy cognito_sub refs verbatim
+```
+
+This relies on Belt's `cognito_authenticatable` convention: the users table is
+`<app>-<env>-users`, its primary key is `id` (the Cognito `sub`), it carries an
+`email`, and `cognito_sub` is the foreign-key attribute referencing it. The
+same re-anchoring runs in the nested (PR-preview) environment deploy hook.
+
+### Cross-account copies
+
+Source and destination environments often live in different AWS accounts
+(e.g. prod vs. dev). `belt db:copy` resolves the AWS profile for each side
+independently from `infrastructure/<env>/belt.rb` (`config.aws_profile`):
+
+```ruby
+# infrastructure/prod/belt.rb
+Belt.configure do |config|
+  config.aws_profile = "prod-readonly"
+end
+```
+
+Override either side explicitly if you don't want to rely on `belt.rb`:
+
+```bash
+belt db:copy prod dev --from-profile prod-readonly --to-profile dev
+```
+
+### How it works
+
+1. Lists tables under each environment's prefix (`<app>-<env>-`) using the
+   AWS CLI (`aws dynamodb list-tables`)
+2. Pairs up tables by matching suffix (e.g. `myapp-prod-posts` ↔ `myapp-dev-posts`)
+3. Scans the source table and `batch-write-item`s into the destination,
+   re-anchoring Cognito-sub foreign keys to the destination's users by email
+   (unless `--no-remap-identity`; see above)
+4. Skips (or overwrites, with `--force`) destination tables that already
+   have items
+
+This is the same mechanism used by nested (PR-preview) environment deploys
+to seed a preview environment's tables from its parent — `belt db:copy` just
+exposes it as a standalone command for any two environments.
+
+## `belt db:seed` — Rails-style seed file
+
+Mirrors `rails db:seed`. Loads `config/seeds.rb` in the same booted context
+`belt console` uses — your models (ActiveItem) are available, targeting the
+resolved environment's tables.
+
+```bash
+belt db:seed              # seeds dev, or $BELT_ENV if set
+belt db:seed dev01        # explicit environment
+belt db:seed prod         # prompts for confirmation, like belt console prod
+```
+
+`config/seeds.rb` is a plain Ruby file:
+
+```ruby
+# frozen_string_literal: true
+
+post = Post.create!(title: "Hello, world", body: "Seeded post")
+puts "Created post: #{post.id}"
+```
+
+### Safety
+
+`belt db:seed` refuses to run if the target environment's tables already
+have data, to avoid clobbering a live environment (or accidentally reseeding
+one that's already loaded). Pass `--force` to seed anyway:
+
+```bash
+belt db:seed dev01 --force
+```
+
+Because of this guard, seeds are typically run once against a fresh
+environment. If you want `seeds.rb` to be safely re-runnable regardless,
+write it idempotently (`find_or_create_by`-style) — `belt db:seed --force`
+does not enforce idempotency for you.
+
+### Scaffolding
+
+`belt new` generates a starter `config/seeds.rb` with usage notes and an
+example. Existing apps can add the file manually — it's just a plain Ruby
+file, no generator required.
+
+## See Also
+
+- `belt explain backups` — recovery-point snapshots, not data seeding
+- `belt explain console` — the app-booting mechanism `db:seed` reuses
+- `belt explain deployment` — nested environments and the parent → child copy hook

data/lib/belt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.4.4'
+  VERSION = '0.4.5'
 end

data/lib/templates/new_app/config/seeds.rb.erb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Seed data for <%= @app_name %>. Run with:
+#
+#   belt db:seed              # seeds dev (or BELT_ENV)
+#   belt db:seed prod         # explicit environment (prompts for confirmation)
+#   BELT_ENV=dev01 belt db:seed
+#
+# This file is loaded in the same booted context as `belt console` — your
+# models (ActiveItem) are available, and they target the resolved
+# environment's DynamoDB tables (<%= @app_name %>-<env>-*).
+#
+# `belt db:seed` refuses to run against an environment that already has
+# data, to avoid clobbering something real. Pass --force to seed anyway.
+# Keep this file idempotent if you expect to re-run it (e.g. find_or_create
+# rather than create).
+#
+# Example:
+#
+#   post = Post.create!(
+#     title: "Hello, world",
+#     body: "This post was created by config/seeds.rb"
+#   )
+#   puts "Created post: #{post.id}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors:
 - Stowzilla
@@ -119,6 +119,8 @@ files:
 - lib/belt/cli/cognito_sharer.rb
 - lib/belt/cli/console_command.rb
 - lib/belt/cli/contracts_command.rb
+- lib/belt/cli/db_copy_command.rb
+- lib/belt/cli/db_seed_command.rb
 - lib/belt/cli/deploy_command.rb
 - lib/belt/cli/destroy_command.rb
 - lib/belt/cli/dns_command.rb
@@ -160,6 +162,7 @@ files:
 - lib/belt/docs/backups.md
 - lib/belt/docs/console.md
 - lib/belt/docs/controllers.md
+- lib/belt/docs/data_seeding.md
 - lib/belt/docs/deployment.md
 - lib/belt/docs/frontend.md
 - lib/belt/docs/generators.md
@@ -231,6 +234,7 @@ files:
 - lib/templates/new_app/config/contracts.rb.erb
 - lib/templates/new_app/config/lambda/api.yml.erb
 - lib/templates/new_app/config/routes.rb.erb
+- lib/templates/new_app/config/seeds.rb.erb
 - lib/templates/new_app/gitignore.erb
 - lib/templates/new_app/lambda/api.rb.erb
 - lib/templates/new_app/lambda/config/environment.rb.erb