belt 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b99fa5db1ad085eaffe7967b3ebd767780190dfdab73f4715d12d57351b556c4
-  data.tar.gz: 1dd0a58fe2d7190214a3c88d936d0f868cba27264e469e9450e59a948fbef130
+  metadata.gz: 17b4d2d7497d0961b96e4628ee718fae22f5da62e321652cd3ff252351883836
+  data.tar.gz: 155caff17e7ca310097baf72376ed8ad8a1515c2ce397769b2db2d6cb5653a26
 SHA512:
-  metadata.gz: 7d9c381fc41b28b4302c17ce25f13bc09adaecfa9f593d1de03437ae0104bdca03b510dcd99578a0a7aa4f931e19e33b6b7426e3145582b25aad2ea3ead6c42c
-  data.tar.gz: 9d78f571938ce9236c3103decacb5078e10c9023c29000d0a817d5ac9c5f9cb07312eff1e54323a4cc96db66f13111cb51a87779a1fb4dc99dc656faa3bd2f5e
+  metadata.gz: 491589da65264857a3c6964ec522344b2dd222a3cab655235039bb39c48ad84c23a3ed83bc20aeaa31de2da197ba51d71c37dfed9395eeaf66464cebcbce28cb
+  data.tar.gz: 9d407911c6bec8492f26ece6bda2f592e67056a44a85ae6c09c99cd877992ffa356893d0a955fea0436684278911164916a1d8066490cb0be80e30368a134837

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.3.0
+
+### Pre-Deploy Backups
+
+Belt now runs automated backups before each deploy when configured. No standalone scripts or generators — `belt deploy` owns the entire lifecycle.
+
+**New: Backup Config DSL** — configure backups per environment in `infrastructure/<env>/belt.rb`:
+
+```ruby
+Belt.configure do |config|
+  config.backups do
+    dynamodb :all                    # PITR + on-demand snapshot before deploy
+    cognito :users, :pool_config    # Export users + pool config to backup bucket
+    s3 :legal_documents             # Sync bucket to backup bucket
+    retention snapshots: 90, cognito: 10, s3: 10
+  end
+end
+```
+
+Simple mode: `config.backups = true` enables DynamoDB backups for all tables.
+
+**Backup types supported:**
+- **DynamoDB**: Verifies PITR is enabled, creates on-demand snapshots (retained per policy)
+- **Cognito**: Paginated user export + pool configuration → versioned backup bucket
+- **S3**: Syncs configured buckets to a dedicated backup bucket
+
+**Deploy lifecycle (updated):**
+1. Validate
+2. Generate route manifests
+3. **Run backups** (if configured for this environment)
+4. `terraform init`
+5. `terraform plan`
+6. Confirm apply
+7. `terraform apply`
+
+**New CLI flags:**
+- `belt deploy prod --skip-backup` — skip backup phase (CI re-runs, etc.)
+- `belt deploy prod --backup-only` — run backups without deploying
+
+**TablesCommand** — all generated DynamoDB tables now include PITR and deletion protection by default:
+
+```hcl
+point_in_time_recovery {
+  enabled = var.enable_pitr  # true by default
+}
+deletion_protection_enabled = var.deletion_protection  # true in prod, false in dev
+```
+
+## 0.2.5
+
+### Table Generation Separation
+
+- Separated table generation from API schema contracts
+
+### Schema DSL
+
+- Added index support to schema DSL for custom GSIs
+
 ## 0.1.13
 
 ### Generator Extension API

data/README.md

@@ -395,6 +395,146 @@ end
 
 When `--tables-file` is provided, Belt parses `aws_dynamodb_table` resource blocks from your Terraform files and infers which tables each route accesses based on the resource name in the route path. Routes can also declare tables explicitly in the DSL via `tables: [:posts, :comments]`.
 
+## Backups
+
+Belt integrates automated pre-deploy backups directly into the deploy lifecycle. No standalone scripts, no generators — `belt deploy` handles everything.
+
+### Quick Start Guide
+
+This walks you through enabling backups for an existing Belt app from scratch.
+
+#### Step 1: Create a backup config
+
+Create `infrastructure/<env>/belt.rb` in your environment directory (e.g. `infrastructure/prod/belt.rb`):
+
+```ruby
+# infrastructure/prod/belt.rb
+Belt.configure do |config|
+  config.backups do
+    dynamodb :all
+    retention snapshots: 90
+  end
+end
+```
+
+That's the minimum — every DynamoDB table in this environment will get an on-demand snapshot before each deploy, retained for 90 days. PITR (point-in-time recovery) will be verified as enabled.
+
+#### Step 2: Deploy
+
+```bash
+belt deploy prod
+```
+
+Output:
+
+```
+━━━ pre-deploy backup ━━━
+  📦 Creating backup bucket: my-app-backups-prod
+  ✅ Backup bucket created and secured
+  🔍 Verifying PITR: my-app-prod-posts → enabled ✓
+  📸 Snapshot: my-app-prod-posts → my-app-prod-posts-20260723-170000 ✓
+  🧹 Cleanup: 0 expired snapshots removed
+
+━━━ terraform init ━━━
+...
+```
+
+The backup bucket is created automatically on first run (versioned, public access blocked). Subsequent deploys reuse it.
+
+#### Step 3: Add more backup types (optional)
+
+As your app grows, add Cognito and S3 backups:
+
+```ruby
+# infrastructure/prod/belt.rb
+Belt.configure do |config|
+  config.backups do
+    dynamodb :all                    # On-demand snapshots + PITR verification
+    cognito :users, :pool_config    # Export user list + pool settings to S3
+    s3 :legal_documents             # Sync bucket contents to backup bucket
+    retention snapshots: 90, cognito: 10, s3: 10
+  end
+end
+```
+
+| Backup type | What it does | Retention default |
+|-------------|-------------|-------------------|
+| `dynamodb :all` | PITR check + on-demand snapshot per table | 90 days |
+| `dynamodb :posts, :users` | Same, but only named tables | 90 days |
+| `cognito :users` | Paginated user export → JSON in backup bucket | 10 copies |
+| `cognito :pool_config` | Pool configuration export → JSON | 10 copies |
+| `s3 :bucket_name` | Full sync to backup bucket | 10 copies |
+
+#### Step 4: Keep dev lightweight
+
+Don't configure backups for dev environments — just omit the file or the backups block:
+
+```ruby
+# infrastructure/dev01/belt.rb
+Belt.configure do |config|
+  # No backups block = no backups run during deploy
+end
+```
+
+Or simply don't create `infrastructure/dev01/belt.rb` at all.
+
+### Simple mode
+
+If you only need DynamoDB backups with all defaults:
+
+```ruby
+# infrastructure/prod/belt.rb
+Belt.configure do |config|
+  config.backups = true
+end
+```
+
+This enables DynamoDB snapshots for all tables with 90-day retention.
+
+### CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `--skip-backup` | Skip backup phase (useful for CI re-runs) |
+| `--backup-only` | Run backups without deploying |
+
+```bash
+# Normal deploy (runs backups first if configured)
+belt deploy prod
+
+# Skip backups this time
+belt deploy prod --skip-backup
+
+# Just create a recovery point, don't deploy
+belt deploy prod --backup-only
+```
+
+### DynamoDB Protection Defaults
+
+All DynamoDB tables generated by Belt include safety defaults:
+
+```hcl
+point_in_time_recovery {
+  enabled = var.enable_pitr  # true by default
+}
+deletion_protection_enabled = var.deletion_protection  # true in prod, false in dev
+```
+
+These are set via Terraform variables in each environment's `terraform.tfvars`. PITR gives you 35 days of continuous recovery regardless of the snapshot schedule.
+
+### How It Works
+
+1. **Backup bucket** — Belt creates `<app-name>-backups-<env>` on first run (versioned, public access blocked)
+2. **Table discovery** — Table names are read from `terraform output` (requires at least one prior successful deploy)
+3. **DynamoDB** — Verifies PITR is enabled, then creates an on-demand backup named `<table>-<timestamp>`
+4. **Cognito** — Uses `list-users` (paginated) and `describe-user-pool` to export JSON to the backup bucket
+5. **S3** — Runs `aws s3 sync` from source bucket to `s3://<backup-bucket>/s3/<bucket-name>/<timestamp>/`
+6. **Cleanup** — Removes snapshots/copies older than the configured retention
+
+### First Deploy Note
+
+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.
+
 ## License
 
 MIT

data/lib/belt/cli/backup_config.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Belt
+  module CLI
+    class BackupConfig
+      attr_reader :dynamodb_tables, :cognito_exports, :s3_buckets, :retention
+
+      # Load backup config from infrastructure/<env>/belt.rb
+      # Returns nil if no config file exists or backups aren't configured
+      def self.load(env, infra_dir: nil)
+        infra_dir ||= 'infrastructure'
+        config_file = File.join(infra_dir, env, 'belt.rb')
+        return nil unless File.exist?(config_file)
+
+        config = new
+        evaluator = ConfigEvaluator.new(config)
+        evaluator.evaluate(File.read(config_file), config_file)
+
+        # Return nil if no backups were configured
+        config.any? ? config : nil
+      end
+
+      def initialize
+        @dynamodb_tables = nil # nil = not configured, :all = all tables, Array = specific tables
+        @cognito_exports = []  # e.g. [:users, :pool_config]
+        @s3_buckets = []       # e.g. [:legal_documents]
+        @retention = { snapshots: 90, cognito: 10, s3: 10 }
+      end
+
+      def dynamodb?
+        !@dynamodb_tables.nil?
+      end
+
+      def cognito?
+        @cognito_exports.any?
+      end
+
+      def any?
+        dynamodb? || cognito? || @s3_buckets.any?
+      end
+
+      # Evaluates the belt.rb config file in an isolated context
+      # that intercepts Belt.configure calls
+      class ConfigEvaluator
+        def initialize(config)
+          @config = config
+        end
+
+        def evaluate(content, filename)
+          # The config file calls Belt.configure { |config| ... }
+          # We wrap the content to intercept the Belt constant lookup
+          # by evaluating in a module where Belt is redefined
+          config = @config
+          sandbox = Module.new
+          # Define a Belt module inside the sandbox that has .configure
+          belt_proxy = Module.new do
+            define_singleton_method(:configure) do |&block|
+              block.call(ConfigDSL.new(config))
+            end
+          end
+          sandbox.const_set(:Belt, belt_proxy)
+
+          # Evaluate the file content within the sandbox module
+          sandbox.module_eval(content, filename)
+        end
+      end
+
+      # DSL yielded to the block inside Belt.configure { |config| ... }
+      class ConfigDSL
+        def initialize(config)
+          @config = config
+        end
+
+        def backups(enabled = nil, &block)
+          if enabled == true
+            # Simple mode: config.backups = true → just DynamoDB for all tables
+            @config.instance_variable_set(:@dynamodb_tables, :all)
+          elsif block
+            backup_dsl = BackupDSL.new(@config)
+            backup_dsl.instance_eval(&block)
+          end
+        end
+      end
+
+      # DSL for the backups block
+      class BackupDSL
+        def initialize(config)
+          @config = config
+        end
+
+        def dynamodb(scope = :all)
+          if scope == :all
+            @config.instance_variable_set(:@dynamodb_tables, :all)
+          else
+            tables = Array(scope)
+            @config.instance_variable_set(:@dynamodb_tables, tables.map(&:to_s))
+          end
+        end
+
+        def cognito(*exports)
+          @config.instance_variable_set(:@cognito_exports, exports.flatten.map(&:to_sym))
+        end
+
+        def s3(*buckets)
+          @config.instance_variable_set(:@s3_buckets, buckets.flatten.map(&:to_sym))
+        end
+
+        def retention(opts = {})
+          current = @config.instance_variable_get(:@retention)
+          merged = current.merge(opts.transform_keys(&:to_sym))
+
+          # Convert duration objects (90.days) to integer days
+          merged.transform_values! do |v|
+            v.respond_to?(:to_i) ? v.to_i : v
+          end
+
+          @config.instance_variable_set(:@retention, merged)
+        end
+      end
+    end
+  end
+end