belt 0.2.19 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f706cafa79246d178c2aee6bfb05536bcb5f03111a24f13624e769ef7d9916a
-  data.tar.gz: a99d09c6d472d4826acf78dee6a4fded952c8745071b63c6ea4f54dbfd6b0aef
+  metadata.gz: cacb19365ad96e079f7a796dc74390f70089bff236581a65b30fabb6e5719008
+  data.tar.gz: c723291b6e114a285b146fead8f5626fe812d798c2230f90999bde34af67806a
 SHA512:
-  metadata.gz: 2009deb03f2f725c4e960e73abf7745b8a9fdd5899ea76178b3942f21c504fe76338912ba57f05b913db3a18494f635c508e4696a3c347e40ddcb973e4c61541
-  data.tar.gz: b84417ce5814e266715b5dc54b4a965261f8011fee552f9f594c82137751565ff29b20f17444b2be986abfd79c02059b935ae5aa97fcbdbbfdcc79ffafa0421b
+  metadata.gz: 8ac85878df33cec2aa990e527530e54368972e6cca18f18f1e080f4154c50b5d539536fdcb55dfa6b2de675c2f271ed60cb578c3e4acedd4c2bc8c39f48cefd3
+  data.tar.gz: fe809339def0c18771870b7bc7bd7740c83aab12dfcef9eb7f4a3b07420bf139dce02fe0c8845bf84e994eb9743e2aa635f0fb0d6e2f0ff369f12b15cabdcc6b

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.3.0
+
+Version bump only — no code changes from 0.2.21.
+
+**Why 0.3.0 instead of another patch?** The route DSL changes in 0.2.21 (`gateway`/`function`/`namespace`/`scope`) were a minor-version level change (new features, new keywords). RubyGems doesn't allow republishing the same version, so we're bumping to 0.3.0 to correct the semver trajectory.
+
+If you're on 0.2.21, you already have the DSL changes. This release is purely for version hygiene.
+
+## 0.2.21
+
+### Route DSL: `gateway`, `function`, `namespace`, and `scope` keywords
+
+The route DSL now uses terminology that matches AWS infrastructure:
+
+- **`gateway`** — Creates an API Gateway with a default Lambda function of the same name (replaces top-level `namespace`)
+- **`function`** — Targets enclosed routes to a different Lambda function
+- **`namespace`** — Rails-like path + module prefix (e.g., `/admin/users` with `admin/users` controller). Does NOT change Lambda target.
+- **`scope`** — Flexible grouping with `path:`, `module:`, `auth:`, `tables:` options. Does NOT change Lambda target.
+
+```ruby
+Belt.application.routes.draw do
+  gateway :api, auth: :cognito do
+    resources :posts                    # → lambda: "api", path: /posts
+
+    function :onboarding do
+      resources :steps                  # → lambda: "onboarding", path: /steps
+    end
+
+    namespace :admin do
+      resources :users                  # → lambda: "api", path: /admin/users, controller: "admin/users"
+    end
+
+    scope path: 'v2', module: 'v2' do
+      resources :widgets                # → lambda: "api", path: /v2/widgets, controller: "v2/widgets"
+    end
+  end
+end
+```
+
+**ActionRouter** now accepts `gateway:` keyword (preferred):
+
+```ruby
+ROUTER = Belt::ActionRouter.new(routes: Routes::API, gateway: 'api')
+```
+
+**100% backward compatible:** `namespace :api do` at top level still works (aliased to `gateway`), and `ActionRouter.new(namespace: 'api')` still works.
+
 ## 0.2.18
 
 ### New generator: `belt generate auth`

data/README.md

@@ -105,7 +105,7 @@ require "belt"
 
 include Belt::LambdaHandler
 
-ROUTER = Belt::ActionRouter.new(routes: Routes::API, namespace: "api")
+ROUTER = Belt::ActionRouter.new(routes: Routes::API, gateway: "api")
 
 def execute(path:, body:, event:)
   ROUTER.route(event: event, body: body)
@@ -140,7 +140,7 @@ Define routes in `infrastructure/routes.tf.rb`:
 
 ```ruby
 Belt.application.routes.draw do
-  namespace :api do
+  gateway :api do
     resources :posts, only: [:index, :show, :create]
   end
 end
@@ -170,6 +170,45 @@ The provider will:
 - Generate IAM policies for DynamoDB table access
 - Set up CloudWatch log groups
 
+### Route DSL Keywords
+
+The routes DSL has four keywords that map to infrastructure and code organization:
+
+| Keyword | Purpose | Affects Lambda? |
+|---------|---------|-----------------|
+| `gateway` | Creates an API Gateway + default Lambda | Yes — sets the default Lambda for all routes inside |
+| `function` | Routes to a different Lambda | Yes — overrides the gateway's default |
+| `namespace` | Adds path prefix + controller module | No — Rails-like code organization only |
+| `scope` | Flexible path/module/auth grouping | No — grouping and shared options only |
+
+**Example combining all four:**
+
+```ruby
+Belt.application.routes.draw do
+  gateway :api, auth: :cognito do
+    resources :posts                    # → lambda: api, path: /posts, controller: posts
+
+    namespace :admin do
+      resources :users                  # → lambda: api, path: /admin/users, controller: admin/users
+    end
+
+    function :worker do
+      resources :jobs                   # → lambda: worker, path: /jobs, controller: jobs
+
+      namespace :internal do
+        resources :tasks                # → lambda: worker, path: /internal/tasks, controller: internal/tasks
+      end
+    end
+
+    scope path: 'v2', module: 'legacy' do
+      resources :widgets                # → lambda: api, path: /v2/widgets, controller: legacy/widgets
+    end
+  end
+end
+```
+
+**Key point:** `namespace` and `scope` are purely organizational — they affect URL paths and controller module resolution but never change which Lambda handles the request. Use `function` when you need routes to go to a different Lambda.
+
 ## BeltController Features
 
 ### Callbacks
@@ -423,7 +462,7 @@ The command expects `infrastructure/routes.tf.rb` in the current working directo
 
 ```ruby
 Belt.application.routes.draw do
-  namespace :api do
+  gateway :api do
     resources :posts, only: [:index, :show, :create, :destroy]
     resource :profile, only: [:show, :update]
     get "health", action: :health

data/lib/belt/action_router.rb

@@ -7,22 +7,26 @@ module Belt
   # Routes incoming requests to controllers based on a route manifest.
   #
   # Usage:
-  #   ROUTER = Belt::ActionRouter.new(routes: MY_ROUTES, namespace: "api")
+  #   ROUTER = Belt::ActionRouter.new(routes: MY_ROUTES, gateway: "api")
   #   response = ROUTER.route(event: event, body: body)
   #
   class ActionRouter
     class RouteNotFound < StandardError; end
 
-    def initialize(routes:, namespace:)
-      @namespace = namespace.to_s
-      @namespace_module_name = "#{@namespace.split('_').map(&:capitalize).join}Controllers"
+    def initialize(routes:, gateway: nil, namespace: nil)
+      # Accept `gateway:` (preferred) or legacy `namespace:` keyword
+      gw = gateway || namespace
+      raise ArgumentError, 'Belt::ActionRouter requires a gateway: (or legacy namespace:) argument' unless gw
+
+      @gateway = gw.to_s
+      @gateway_module_name = "#{@gateway.split('_').map(&:capitalize).join}Controllers"
       @routes = build_route_table(routes)
     end
 
     def route(event:, body:)
       method = event['httpMethod']
       full_path = event['path']
-      match_path = strip_namespace_prefix(full_path)
+      match_path = strip_gateway_prefix(full_path)
 
       route_info = find_route(method, match_path)
 
@@ -56,10 +60,10 @@ module Belt
 
     private
 
-    def strip_namespace_prefix(path)
+    def strip_gateway_prefix(path)
       return '/' if path.nil?
 
-      prefix = "/#{@namespace}"
+      prefix = "/#{@gateway}"
       if path.start_with?(prefix)
         stripped = path.sub(prefix, '')
         stripped.empty? ? '/' : stripped
@@ -127,15 +131,15 @@ module Belt
       return false if name.start_with?('/') || name.end_with?('/')
       return false if name.include?('\\')
 
-      # Allow only lowercase letters, digits, underscores, and a single forward slash for nesting
+      # Allow only lowercase letters, digits, underscores, and forward slashes for nesting
       name.match?(%r{\A[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)?\z})
     end
 
     def resolve_controller(controller_name)
-      # Try namespace module first (app's own controllers)
+      # Try gateway module first (app's own controllers)
       begin
-        namespace_module = Object.const_get(@namespace_module_name)
-        return resolve_from_module(namespace_module, controller_name)
+        gateway_module = Object.const_get(@gateway_module_name)
+        return resolve_from_module(gateway_module, controller_name)
       rescue NameError
         # Fall through to controller_paths lookup
       end
@@ -144,13 +148,13 @@ module Belt
       resolve_from_paths(controller_name)
     end
 
-    def resolve_from_module(namespace_module, controller_name)
+    def resolve_from_module(gateway_module, controller_name)
       if controller_name.include?('/')
         parts = controller_name.split('/')
-        parent = namespace_module.const_get(parts[0].split('_').map(&:capitalize).join)
+        parent = gateway_module.const_get(parts[0].split('_').map(&:capitalize).join)
         parent.const_get("#{parts[1].split('_').map(&:capitalize).join}Controller")
       else
-        namespace_module.const_get("#{controller_name.split('_').map(&:capitalize).join}Controller")
+        gateway_module.const_get("#{controller_name.split('_').map(&:capitalize).join}Controller")
       end
     end
 
@@ -176,9 +180,9 @@ module Belt
         class_name = "#{controller_name.split(%r{[_/]}).map(&:capitalize).join}Controller"
         return Object.const_get(class_name) if Object.const_defined?(class_name)
 
-        # Try under namespace module (e.g., BrablogControllers::PostsController)
-        if Object.const_defined?(@namespace_module_name)
-          ns = Object.const_get(@namespace_module_name)
+        # Try under gateway module (e.g., ApiControllers::PostsController)
+        if Object.const_defined?(@gateway_module_name)
+          ns = Object.const_get(@gateway_module_name)
           return ns.const_get(class_name) if ns.const_defined?(class_name)
         end
       end

data/lib/belt/cli/app_detection.rb

@@ -3,12 +3,14 @@
 module Belt
   module CLI
     module AppDetection
-      # Detects the primary namespace from the route definitions.
+      # Detects the primary gateway from the route definitions.
       # Used by generators to determine controller directory and route file naming.
       def detect_namespace
         routes_file = find_routes_file_path
         if routes_file && File.exist?(routes_file)
-          match = File.read(routes_file).match(/namespace :(\w+)/)
+          content = File.read(routes_file)
+          # Prefer `gateway :name` but fall back to legacy `namespace :name` at top-level
+          match = content.match(/^\s*gateway :(\w+)/) || content.match(/^\s*namespace :(\w+)/)
           return match[1] if match
         end
         File.basename(Dir.pwd)

data/lib/belt/cli/auth_command.rb

@@ -101,14 +101,48 @@ module Belt
         write_cognito_tf
         write_cognito_outputs_tf
         patch_main_tf
+        patch_env_outputs
         generate_frontend_auth if frontend?
 
         puts "\n✓ Auth generated!"
+        print_next_steps
+      end
+
+      def print_next_steps
         puts "\nNext steps:"
-        puts '  1. Review infrastructure/modules/app/cognito.tf'
-        puts '  2. Customize password policy, MFA, or Lambda triggers as needed'
-        puts '  3. Run `belt apply <env>` to deploy'
-        puts '  4. Create your account: aws cognito-idp admin-create-user ...' unless @signup
+        puts '  1. Add auth: :cognito to your routes namespace:'
+        puts ''
+        puts '       namespace :api, auth: :cognito do'
+        puts '         # your resources...'
+        puts '       end'
+        puts ''
+        if frontend?
+          puts '  2. Wire auth into your frontend/src/App.jsx:'
+          puts ''
+          puts "       import Login from './pages/auth/Login'"
+          puts "       import ProtectedRoute from './components/ProtectedRoute'"
+          puts ''
+          puts '       // Add login route:'
+          puts '       <Route path="/login" element={<Login onLogin={() => window.location.href = \'/\'} />} />'
+          puts ''
+          puts '       // Wrap protected routes:'
+          puts '       <Route path="/*" element={<ProtectedRoute><YourApp /></ProtectedRoute>} />'
+          puts ''
+          puts '  3. Deploy: belt deploy'
+          print_create_user_step(4) unless @signup
+        else
+          puts '  2. Deploy: belt deploy'
+          print_create_user_step(3) unless @signup
+        end
+      end
+
+      def print_create_user_step(step_num)
+        puts "  #{step_num}. Create your account:"
+        puts '       aws cognito-idp admin-create-user \\'
+        puts '         --user-pool-id <pool-id-from-terraform-output> \\'
+        puts '         --username your@email.com \\'
+        puts '         --temporary-password TempPass123 \\'
+        puts '         --message-action SUPPRESS'
       end
 
       def remove
@@ -167,6 +201,7 @@ module Belt
         pages_dir = 'frontend/src/pages/auth'
         FileUtils.mkdir_p(pages_dir)
         copy_frontend_file(frontend_template_dir, 'Login.jsx', File.join(pages_dir, 'Login.jsx'))
+        copy_frontend_file(frontend_template_dir, 'auth.css', File.join(pages_dir, 'auth.css'))
         if @signup
           # Generate auth pages
           copy_frontend_file(frontend_template_dir, 'SignUp.jsx', File.join(pages_dir, 'SignUp.jsx'))
@@ -244,6 +279,42 @@ module Belt
         insert_cognito_into_resource(content, main_tf, arn_value)
       end
 
+      def patch_env_outputs
+        env_dirs = Dir.glob('infrastructure/*/outputs.tf')
+                      .reject { |f| f.include?('modules') }
+
+        env_dirs.each do |outputs_file|
+          content = File.read(outputs_file)
+
+          next if content.include?('cognito_user_pool_id')
+
+          cognito_outputs = @pools.map do |pool|
+            suffix = pool[:suffix]
+            <<~HCL
+
+              output "cognito_user_pool_id#{suffix}" {
+                description = "Cognito User Pool ID#{pool[:label]}"
+                value       = module.app.cognito_user_pool_id#{suffix}
+              }
+
+              output "cognito_client_id#{suffix}" {
+                description = "Cognito User Pool Client ID#{pool[:label]}"
+                value       = module.app.cognito_client_id#{suffix}
+              }
+
+              output "cognito_region" {
+                description = "AWS region for Cognito"
+                value       = var.aws_region
+              }
+            HCL
+          end.join
+
+          File.write(outputs_file, content + cognito_outputs)
+          env_name = File.basename(File.dirname(outputs_file))
+          puts "  update  #{outputs_file} (added cognito outputs for #{env_name})"
+        end
+      end
+
       def build_arn_value(arns)
         if arns.length == 1
           "[#{arns.first}]"

data/lib/belt/cli/console_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'optparse'
+require 'stringio'
 require_relative 'environment_config'
 
 module Belt
@@ -59,7 +60,10 @@ module Belt
         boot_app
         puts banner
         ARGV.clear
-        require 'irb'
+        suppress_warnings do
+          require 'irb'
+          require 'rdoc'
+        end
         IRB.start
       end
 
@@ -72,7 +76,7 @@ module Belt
       end
 
       def boot_app
-        require 'bundler/setup'
+        suppress_warnings { require 'bundler/setup' }
 
         environment_file = File.join(Belt.root, 'lambda', 'config', 'environment.rb')
         if File.exist?(environment_file)
@@ -132,6 +136,17 @@ module Belt
           result.inspect
         end
       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

@@ -145,9 +145,9 @@ module Belt
 
       def run
         validate!
-        env_dir = File.join(@infra_dir, @env)
-
         load_and_apply_env_config!
+        run_preflight_checks!
+        env_dir = File.join(@infra_dir, @env)
 
         puts "belt → deploying #{@env} (in #{env_dir}/)\n\n"
 
@@ -263,6 +263,14 @@ module Belt
               "Create it with: belt generate environment #{@env}"
       end
 
+      def run_preflight_checks!
+        require_relative 'doctor_command'
+        doctor = DoctorCommand.new(preflight: true)
+        return if doctor.run
+
+        abort 'Deploy blocked. Fix the issues above, then try again.'
+      end
+
       def validate_aws!
         stdout, status = Open3.capture2('aws', 'sts', 'get-caller-identity', '--output', 'json')
         unless status.success?

data/lib/belt/cli/destroy_command.rb

@@ -10,7 +10,7 @@ require_relative '../inflector'
 module Belt
   module CLI
     class DestroyCommand
-      GENERATORS = %w[scaffold resource model controller environment frontend views auth].freeze
+      GENERATORS = %w[scaffold resource model controller environment frontend views index auth].freeze
 
       include AppDetection
 
@@ -61,6 +61,8 @@ module Belt
             exit 1
           end
           new(generator, name, args.map { |a| parse_field(a) }).destroy
+        when 'index'
+          Belt::CLI::IndexCommand.run(['remove'] + args)
         else
           name = args.shift
           if name.nil? || name.empty?