belt 0.4.4 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a4efb62a37845ad3c311558cebdd71fcf74ba7ae31870f3c2728e286dc33a72
-  data.tar.gz: 8278be1ba1c44b6d355d00963ca1d33c401749b0af584a4cb5c07f6ae25bca54
+  metadata.gz: f29c42b3eb7869a90ab1a0a22d56fd6b1304dbd6e22f32503669b3c9b0974890
+  data.tar.gz: f313115ee77ceafb82a4c424c6721f6776f3b869c1b71cc1e458332bc16b53fd
 SHA512:
-  metadata.gz: b3d9d4782cd23143c6674b674780072784077105eeef396ec04d55b194ef102c643c5cd646311cdf024983c1e1a7f70407bea5bb2e0cb5261938e58d0dcceb87
-  data.tar.gz: a7e6cc11a4e2625b135cf967af4f614dcaa21fd7ee7b8cfcbea42bd68eea8976368a6392e257f2f229f8a6e9673414546044628cefa1f4fe0d6a2d9042b0b90f
+  metadata.gz: 57150cb2d0934d723b6fafb9eaee652dc933c4522fcae787518d2e03990da13e1c9f229d498b990a86fb1daa90ec3916e4e049e411a418a4534e76f4274a658e
+  data.tar.gz: 8e2d42b8ba9417dacdf725a66cc0e0a0d37e3a7ae59c3085a50f40c7c1e38eb298be49fa0a0ac3d3489e445e3907d85174bc07f45959a385ccbe55a605a5016d

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.4.6
+
+### Added
+
+- **Agent Skill (`SKILL.md`) — installable via `npx skills add stowzilla/belt`.**
+  A root-level `SKILL.md` with trigger-rich frontmatter, a lean activation body
+  (core patterns + decision guide), and on-demand `references/` docs (CLI, routing,
+  controllers, models+auth, deploy/ops, plugins). A CI workflow validates the
+  frontmatter and that every reference link resolves.
+- **`SKILL.md` + `references/` now ship inside the `belt` gem.** The gemspec
+  `files` manifest was extended so a `gem install belt` lands the skill on disk
+  alongside the runtime. The `skills` CLI resolves git repos and local paths (not
+  RubyGems), so a gem install won't *auto-register* the skill — but the files are
+  present and can be picked up via a local-path install
+  (`npx skills add <gem-install-dir>`), and belt.dev tooling can vendor them.
+
+### 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 +48,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/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: belt
+license: MIT
+description: >-
+  Build, run, and deploy serverless Ruby apps on AWS Lambda with the Belt
+  framework (Rails-inspired). Use when working in a Belt app or the belt gem:
+  scaffolding apps/models/controllers/frontends, defining routes with the
+  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,
+  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
+  activate for physical belts, conveyor hardware, or unrelated Ruby web
+  frameworks like Rails/Sinatra outside a Belt project.
+metadata:
+  author: stowzilla
+  version: "0.1.0"
+---
+
+# Belt
+
+Belt is a Rails-inspired framework for serverless Ruby on AWS Lambda. It ships a
+runtime (`BeltController`, `Belt::LambdaHandler`, `Belt::ActionRouter`,
+`Belt::Authentication`), a DynamoDB ORM (`ActiveItem`), logging/metrics
+(`lambda_loadout`), a routing DSL consumed by the **conveyor-belt** Terraform
+provider, and a `belt` CLI. Optional features (`belt-messaging`, `belt-pay`)
+ship as separate plugin gems.
+
+## First: orient yourself
+
+Belt has an authoritative, in-repo docs system. **Use it before guessing.**
+
+```bash
+belt explain <topic>   # routing controllers models deployment generators
+                       # lambda_handler observability console backups
+                       # data_seeding plugins structure frontend authentication
+belt --help            # full command list
+belt routes            # list every endpoint (verb, path, controller#action)
+belt doctor            # check deps + AWS config
+```
+
+- **Working in a Belt app?** Read the app's own `AGENTS.md` (scaffolded by `belt new`).
+- **Working on the belt gem itself?** Read `AGENTS.md` + `README.md` at the gem root.
+- The `belt explain` docs live at `lib/belt/docs/*.md` in the gem — the single
+  source of truth for CLI behavior, controller lifecycle, and routing.
+
+## Decision guide
+
+| I want to… | Do this |
+|---|---|
+| Scaffold an app | `belt new <name> --frontend react` |
+| Add a resource | `belt generate scaffold post title:string body:text` |
+| See all routes | `belt routes` (add `-f json` for tooling) |
+| Deploy to AWS | `belt deploy <env>` (`--auto` to skip prompt) |
+| Poke at data live | `belt console <env>` |
+| Run a local frontend | `belt server` (see references for env targeting) |
+| Add Cognito auth | `belt generate auth` → `cognito_authenticatable` in a model |
+| Build a plugin | `belt plugin new <name>` |
+| Learn a concept | `belt explain <topic>` |
+
+## Core patterns (memorize these)
+
+**Controller** — assigns become the JSON body; explicit helpers win.
+
+```ruby
+class PostsController < BeltController::Base
+  before_action :authenticate_user!
+
+  def index
+    @posts = Post.where(user_id: current_user.id, index: "UserIndex")
+  end
+
+  def create
+    @post = Post.create!(params.require(:post).permit(:title, :body).to_h)
+    response_status :created   # → 201 + { post: {...} }
+  end
+
+  def destroy
+    Post.find(params["id"]).destroy
+    head :no_content
+  end
+end
+```
+
+**Model** — ActiveItem over DynamoDB.
+
+```ruby
+class Post < ActiveItem::Base
+  self.primary_key = :id
+  attr_accessor :id, :user_id, :title, :body, :created_at
+  validates :title, presence: true
+  before_create { self.id ||= SecureRandom.uuid }
+end
+```
+
+**Routes DSL** — `infrastructure/routes.tf.rb`. `gateway`/`function` pick the
+Lambda; `namespace`/`scope` only affect paths + controller module.
+
+```ruby
+Belt.application.routes.draw do
+  gateway :api, auth: :cognito do
+    resources :posts do
+      member     { post :publish }     # /posts/:post_id/publish
+      collection { get  :recent }       # /posts/recent
+    end
+  end
+end
+```
+
+**Lambda entry point** — `Belt::LambdaHandler` gives observability, CORS
+preflight, JSON parsing, and error wrapping for free.
+
+```ruby
+require "belt"
+include Belt::LambdaHandler
+ROUTER = Belt::ActionRouter.new(routes: Routes::API, gateway: "api")
+
+def execute(path:, body:, event:)
+  ROUTER.route(event: event, body: body)
+end
+```
+
+## Golden rules for agents
+
+1. **`belt explain <topic>` before inventing behavior.** The docs are canonical.
+2. **`namespace`/`scope` never change which Lambda serves a route** — only
+   `gateway` and `function` do. Do not conflate them.
+3. **Controllers need no registration.** Belt discovers them by convention.
+4. **Runtime code stays in gems; generators copy only what the app must own.**
+5. **Never commit secrets** (`.env`, AWS keys, real account IDs).
+6. **`rubocop` + `rspec` must pass** before a PR on the belt gem.
+
+## Deeper references
+
+Load these only when the task needs them:
+
+- [references/cli.md](references/cli.md) — every `belt` command, flags, env vars, Terraform shorthand
+- [references/routing.md](references/routing.md) — full routing DSL, nested resources, request/response model inference
+- [references/controllers.md](references/controllers.md) — callbacks, strong params, responses, error handling, formats
+- [references/models-and-auth.md](references/models-and-auth.md) — ActiveItem + Cognito authentication
+- [references/deploy-and-ops.md](references/deploy-and-ops.md) — deploy lifecycle, environments, backups, seeding, observability
+- [references/plugins.md](references/plugins.md) — authoring Belt plugin gems and the GeneratorRegistry contract

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