belt 0.2.17 → 0.3.14

data/lib/belt/cli/destroy_command.rb

@@ -2,6 +2,8 @@
 
 require 'fileutils'
 require_relative 'app_detection'
+require_relative 'auth_command'
+require_relative 'frontend_registry'
 require_relative 'generator_registry'
 require_relative 'tables_command'
 require_relative '../inflector'
@@ -9,7 +11,7 @@ require_relative '../inflector'
 module Belt
   module CLI
     class DestroyCommand
-      GENERATORS = %w[scaffold resource model controller environment frontend views].freeze
+      GENERATORS = %w[scaffold resource model controller environment frontend views index auth].freeze
 
       include AppDetection
 
@@ -50,21 +52,28 @@ module Belt
           flags = parse_environment_flags(args)
           new(generator, name, [], **flags).destroy
         when 'frontend'
-          new(generator, nil, []).destroy
+          frontend_name = FrontendRegistry.extract_flag!(args, '--frontend')
+          new(generator, nil, [], frontend_name: frontend_name).destroy
+        when 'auth'
+          Belt::CLI::AuthCommand.destroy(args)
         when 'views'
+          frontend_name = FrontendRegistry.extract_flag!(args, '--frontend')
           name = args.shift
           if name.nil? || name.empty?
-            puts 'Usage: belt destroy views <name>'
+            puts 'Usage: belt destroy views <name> [--frontend NAME]'
             exit 1
           end
-          new(generator, name, args.map { |a| parse_field(a) }).destroy
+          new(generator, name, args.map { |a| parse_field(a) }, frontend_name: frontend_name).destroy
+        when 'index'
+          Belt::CLI::IndexCommand.run(['remove'] + args)
         else
+          frontend_name = FrontendRegistry.extract_flag!(args, '--frontend')
           name = args.shift
           if name.nil? || name.empty?
             puts "Usage: belt destroy #{generator} <name>"
             exit 1
           end
-          new(generator, name, args.map { |a| parse_field(a) }).destroy
+          new(generator, name, args.map { |a| parse_field(a) }, frontend_name: frontend_name).destroy
         end
       end
 
@@ -98,8 +107,9 @@ module Belt
             resource      Alias for scaffold
             model         Remove an ActiveItem model
             controller    Remove a controller
+            auth          Remove Cognito user pool infrastructure
             environment   Remove a deployment environment and tear down infrastructure
-            frontend      Remove the frontend/ directory
+            frontend      Remove a frontend directory (use --frontend NAME when several exist)
             views         Remove React pages for a resource
 
           Environment options:
@@ -114,7 +124,9 @@ module Belt
             belt d environment dev --skip-terraform
             belt d environment dev --force
             belt d frontend
+            belt d frontend --frontend ops
             belt d views post
+            belt d views post --frontend ops
 
           ⚠ This is destructive. Files will be permanently deleted.
 
@@ -123,12 +135,14 @@ module Belt
         HELP
       end
 
-      def initialize(generator, name, fields, force: false, skip_terraform: false)
+      # rubocop:disable Metrics/ParameterLists -- keyword options for destroy flags
+      def initialize(generator, name, fields, force: false, skip_terraform: false, frontend_name: nil)
         @generator = generator
         @name = name&.downcase&.gsub(/[^a-z0-9_]/, '_')
         @fields = fields
         @force = force
         @skip_terraform = skip_terraform
+        @frontend_name = frontend_name
         @app_name = detect_namespace
         @singular_name = @name ? Belt::Inflector.singularize(@name) : nil
         @resource_name = @singular_name ? Belt::Inflector.pluralize(@singular_name) : nil
@@ -136,6 +150,7 @@ module Belt
         @removed = []
         @updated = []
       end
+      # rubocop:enable Metrics/ParameterLists
 
       def destroy
         case @generator
@@ -344,39 +359,62 @@ module Belt
       end
 
       def destroy_frontend
-        dir = 'frontend'
+        frontend = FrontendRegistry.new.resolve!(@frontend_name)
+        dir = frontend.path
         if Dir.exist?(dir)
           FileUtils.rm_rf(dir)
           @removed << dir
           puts "  remove  #{dir}/"
 
-          # Remove frontend.tf from the module
-          module_frontend = 'infrastructure/modules/app/frontend.tf'
-          if File.exist?(module_frontend)
-            FileUtils.rm_f(module_frontend)
-            @removed << module_frontend
-            puts "  remove  #{module_frontend}"
+          tf_file = File.join('infrastructure/modules/app', "#{frontend.tf_name}.tf")
+          if File.exist?(tf_file)
+            FileUtils.rm_f(tf_file)
+            @removed << tf_file
+            puts "  remove  #{tf_file}"
           end
 
-          puts "\n✓ Frontend removed!"
+          puts "\n✓ #{frontend.label.capitalize} removed!"
         else
-          puts '✗ No frontend/ directory found.'
+          puts "✗ No #{dir}/ directory found."
           exit 1
         end
       end
 
+      def target_frontends
+        registry = FrontendRegistry.new
+        return [] if registry.empty?
+
+        if @frontend_name
+          [registry.resolve!(@frontend_name)]
+        else
+          registry.all
+        end
+      end
+
       def destroy_views
         return unless @resource_name
 
-        pages_dir = "frontend/src/pages/#{@resource_name}"
-
-        if Dir.exist?(pages_dir)
-          FileUtils.rm_rf(pages_dir)
-          @removed << pages_dir
-          puts "  remove  #{pages_dir}/"
+        targets = target_frontends
+        if targets.empty?
+          pages_dir = "frontend/src/pages/#{@resource_name}"
+          if Dir.exist?(pages_dir)
+            FileUtils.rm_rf(pages_dir)
+            @removed << pages_dir
+            puts "  remove  #{pages_dir}/"
+          end
+          remove_view_routes_from('frontend/src/App.jsx')
+          return
         end
 
-        remove_view_routes
+        targets.each do |frontend|
+          pages_dir = "#{frontend.src_dir}/pages/#{@resource_name}"
+          if Dir.exist?(pages_dir)
+            FileUtils.rm_rf(pages_dir)
+            @removed << pages_dir
+            puts "  remove  #{pages_dir}/"
+          end
+          remove_view_routes_from(frontend.app_jsx)
+        end
       end
 
       def remove_file(path)
@@ -461,8 +499,7 @@ module Belt
         Belt::CLI::TablesCommand.sync_all_environments
       end
 
-      def remove_view_routes
-        app_jsx = 'frontend/src/App.jsx'
+      def remove_view_routes_from(app_jsx)
         return unless File.exist?(app_jsx)
 
         content = File.read(app_jsx)

data/lib/belt/cli/doctor_command.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'open3'
+require_relative '../../belt/inflector'
 
 module Belt
   module CLI
@@ -17,13 +18,14 @@ module Belt
 
       def self.run(args)
         verbose = args.include?('--verbose') || args.include?('-v')
+        preflight = args.include?('--preflight')
 
         if args.include?('--help') || args.include?('-h')
           puts usage
           exit 0
         end
 
-        new(verbose: verbose).run
+        new(verbose: verbose, preflight: preflight).run
       end
 
       def self.usage
@@ -33,24 +35,50 @@ module Belt
           Check system dependencies and AWS configuration for Belt.
 
           Options:
-            -v, --verbose    Show detailed output for each check
-            -h, --help       Show this help
+            -v, --verbose      Show detailed output for each check
+            --preflight        Run only deploy-critical checks (indexes, credentials)
+            -h, --help         Show this help
         USAGE
       end
 
-      def initialize(verbose: false)
+      def initialize(verbose: false, preflight: false)
         @verbose = verbose
+        @preflight = preflight
         @issues = []
         @warnings = []
       end
 
-      def run
+      def run # rubocop:disable Naming/PredicateMethod
+        if @preflight
+          run_preflight
+        else
+          run_full
+        end
+
+        @issues.empty?
+      end
+
+      # Returns true if all preflight checks pass, false otherwise.
+      def run_preflight
+        check_aws_identity_quiet
+        check_table_indexes
+        check_cognito_auth
+        return if @issues.empty?
+
+        puts "\nPreflight checks failed:\n"
+        @issues.each { |i| puts "  ✗ #{i}" }
+        puts ''
+      end
+
+      def run_full
         puts "Belt Doctor\n"
         puts "Checking your system for Belt prerequisites...\n\n"
 
         check_tools
         check_aws_credentials
         check_aws_identity
+        check_table_indexes
+        check_cognito_auth
 
         puts ''
         print_summary
@@ -132,28 +160,144 @@ module Belt
           print_ok('Authentication', "account #{account}")
           puts "         ARN: #{arn}" if @verbose
         else
-          error = output.strip
-          if error.include?('ExpiredToken') || error.include?('expired')
-            print_fail('Authentication', 'credentials expired')
-            puts '         Run: aws sso login'
-            @issues << 'AWS credentials are expired — run `aws sso login`'
-          elsif error.include?('InvalidClientTokenId') || error.include?('SignatureDoesNotMatch')
-            print_fail('Authentication', 'invalid credentials')
-            puts '         Your access key or secret is incorrect.'
-            puts '         Run: aws configure'
-            @issues << 'AWS credentials are invalid'
-          elsif error.include?('Could not connect') || error.include?('Unable to locate credentials')
-            print_fail('Authentication', 'unable to authenticate')
-            puts '         Run: aws configure sso    # or set AWS_PROFILE'
-            @issues << 'Unable to authenticate with AWS'
+          handle_aws_identity_error(output.strip)
+        end
+      end
+
+      def check_aws_identity_quiet
+        _, status = Open3.capture2e('aws', 'sts', 'get-caller-identity')
+        return if status.success?
+
+        @issues << 'AWS credentials invalid or expired — run `aws sso login`'
+      end
+
+      def handle_aws_identity_error(error)
+        if error.include?('ExpiredToken') || error.include?('expired')
+          print_fail('Authentication', 'credentials expired')
+          puts '         Run: aws sso login'
+          @issues << 'AWS credentials are expired — run `aws sso login`'
+        elsif error.include?('InvalidClientTokenId') || error.include?('SignatureDoesNotMatch')
+          print_fail('Authentication', 'invalid credentials')
+          puts '         Your access key or secret is incorrect.'
+          puts '         Run: aws configure'
+          @issues << 'AWS credentials are invalid'
+        elsif error.include?('Could not connect') || error.include?('Unable to locate credentials')
+          print_fail('Authentication', 'unable to authenticate')
+          puts '         Run: aws configure sso    # or set AWS_PROFILE'
+          @issues << 'Unable to authenticate with AWS'
+        else
+          print_fail('Authentication', 'failed')
+          puts "         #{error.lines.first&.strip}" if error.length.positive?
+          @issues << 'AWS authentication failed'
+        end
+      end
+
+      def check_table_indexes
+        return unless Belt.root?
+
+        models_dir = File.join(Belt.root, 'lambda/models')
+        dynamodb_tf = File.join(Belt.root, 'infrastructure/modules/app/dynamodb.tf')
+
+        return unless Dir.exist?(models_dir)
+
+        puts ''
+        puts '── Tables & Indexes ──'
+
+        unless File.exist?(dynamodb_tf)
+          print_warn('dynamodb.tf', 'not found — run `belt setup tables` to generate')
+          @warnings << 'dynamodb.tf not generated — run `belt setup tables`'
+          return
+        end
+
+        tf_content = File.read(dynamodb_tf)
+        model_files = Dir.glob(File.join(models_dir, '*.rb'))
+                         .reject { |f| File.basename(f) == 'application_record.rb' }
+
+        model_files.each do |file|
+          check_model_indexes(file, tf_content)
+        end
+      end
+
+      def check_model_indexes(file, tf_content)
+        content = File.read(file)
+        class_match = content.match(/^class\s+(\w+)\s*<\s*ApplicationRecord/)
+        return unless class_match
+
+        model_name = Belt::Inflector.underscore(class_match[1])
+        table_name = Belt::Inflector.pluralize(model_name)
+
+        # Check if table exists in dynamodb.tf
+        unless tf_content.include?("resource \"aws_dynamodb_table\" \"#{table_name}\"")
+          print_fail(table_name, 'table not in dynamodb.tf')
+          @issues << "Table '#{table_name}' missing from dynamodb.tf — run `belt setup tables`"
+          return
+        end
+
+        # Extract expected indexes from belongs_to
+        expected_indexes = extract_expected_indexes(content)
+        return if expected_indexes.empty?
+
+        # Check each expected index exists in the TF file
+        # Scope check to this table's resource block
+        table_block = tf_content[/resource "aws_dynamodb_table" "#{table_name}" \{.*?^\}/m]
+        return unless table_block
+
+        missing = []
+        expected_indexes.each do |idx|
+          if table_block.include?("name            = \"#{idx[:name]}\"")
+            print_ok(table_name, idx[:name]) if @verbose
           else
-            print_fail('Authentication', 'failed')
-            puts "         #{error.lines.first&.strip}" if error.length.positive?
-            @issues << 'AWS authentication failed'
+            missing << idx
+          end
+        end
+
+        if missing.empty?
+          print_ok(table_name, "#{expected_indexes.size} index#{'es' if expected_indexes.size > 1} configured")
+        else
+          missing.each do |idx|
+            print_fail(table_name, "missing #{idx[:name]} (required by belongs_to :#{idx[:association]})")
+            @issues << "Table '#{table_name}' missing index '#{idx[:name]}' " \
+                       '— run `belt setup tables` then `belt deploy`'
           end
         end
       end
 
+      def extract_expected_indexes(content)
+        indexes = []
+        content.lines.reject { |line| line.strip.start_with?('#') }.join
+               .scan(/belongs_to\s+:(\w+)/) do |match|
+          association_name = match[0]
+          indexes << {
+            name: "#{Belt::Inflector.classify(association_name)}Index",
+            association: association_name
+          }
+        end
+        indexes
+      end
+
+      def check_cognito_auth
+        return unless Belt.root?
+
+        routes_file = Belt.routes_file
+        return unless routes_file
+
+        content = File.read(routes_file)
+
+        # Check if any routes use auth: :cognito
+        uses_cognito = content.include?('auth: :cognito')
+        return unless uses_cognito
+
+        # Check if cognito.tf exists
+        cognito_tf = File.join(Belt.root, 'infrastructure/modules/app/cognito.tf')
+        return if File.exist?(cognito_tf)
+
+        puts ''
+        puts '── Authentication ──'
+        print_warn('Cognito', 'routes use auth: :cognito but no cognito.tf found')
+        puts '         Run: belt generate auth'
+        @warnings << 'Routes use auth: :cognito but no Cognito pool is configured — run `belt generate auth`'
+      end
+
       def print_summary
         if @issues.empty? && @warnings.empty?
           puts '✓ All checks passed — you\'re ready to belt!'

data/lib/belt/cli/environment_command.rb

@@ -3,6 +3,8 @@
 require 'fileutils'
 require 'erb'
 require_relative 'app_detection'
+require_relative 'frontend_registry'
+require_relative 'frontend_setup_command'
 
 module Belt
   module CLI
@@ -52,6 +54,8 @@ module Belt
           puts "  create  #{dest_path}" unless @quiet
         end
 
+        append_extra_frontend_outputs(File.join(dest_dir, 'outputs.tf'))
+
         return if @quiet || !@announce
 
         puts "\n✓ Environment '#{@env_name}' created!"
@@ -82,6 +86,14 @@ module Belt
         File.write(dest_path, content)
       end
 
+      def append_extra_frontend_outputs(outputs_file)
+        FrontendRegistry.new.all.each do |frontend|
+          next if frontend.tf_name == 'frontend'
+
+          FrontendSetupCommand.append_env_outputs_for(frontend, outputs_file)
+        end
+      end
+
       # Resolve the state bucket name to use in backend.tf.
       # Priority: existing sibling backend.tf → AWS account ID → bare placeholder.
       def resolve_state_bucket

data/lib/belt/cli/explain_command.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Belt
+  module CLI
+    class ExplainCommand
+      DOCS_DIR = File.expand_path('../docs', __dir__)
+
+      TOPICS = Dir.glob(File.join(DOCS_DIR, '*.md')).map do |path|
+        File.basename(path, '.md')
+      end.sort.freeze
+
+      ALIASES = {
+        'routes' => 'routing',
+        'route' => 'routing',
+        'router' => 'routing',
+        'controller' => 'controllers',
+        'model' => 'models',
+        'activeitem' => 'models',
+        'dynamodb' => 'models',
+        'deploy' => 'deployment',
+        'deploying' => 'deployment',
+        'terraform' => 'deployment',
+        'generate' => 'generators',
+        'generator' => 'generators',
+        'scaffold' => 'generators',
+        'handler' => 'lambda_handler',
+        'lambda' => 'lambda_handler',
+        'entry_point' => 'lambda_handler',
+        'entrypoint' => 'lambda_handler',
+        'project' => 'structure',
+        'layout' => 'structure',
+        'directory' => 'structure',
+        'logs' => 'observability',
+        'logging' => 'observability',
+        'metrics' => 'observability',
+        'backup' => 'backups',
+        'plugin' => 'plugins',
+        'irb' => 'console',
+        'repl' => 'console',
+        'frontends' => 'frontend',
+        'spa' => 'frontend'
+      }.freeze
+
+      def self.run(args)
+        if args.empty? || args.include?('--help') || args.include?('-h')
+          puts usage
+          return
+        end
+
+        topic = resolve_topic(args.first)
+
+        if topic.nil?
+          puts "Unknown topic: #{args.first}\n\n"
+          puts 'Available topics:'
+          TOPICS.each { |t| puts "  #{t}" }
+          puts "\nRun `belt explain <topic>` for details."
+          exit 1
+        end
+
+        display_topic(topic)
+      end
+
+      def self.resolve_topic(input)
+        normalized = input.downcase.gsub('-', '_')
+        return normalized if TOPICS.include?(normalized)
+        return ALIASES[normalized] if ALIASES[normalized]
+
+        # Fuzzy match: find topics that start with or contain the input
+        match = TOPICS.find { |t| t.start_with?(normalized) }
+        match || TOPICS.find { |t| t.include?(normalized) }
+      end
+
+      def self.display_topic(topic)
+        path = File.join(DOCS_DIR, "#{topic}.md")
+        content = File.read(path)
+        puts content
+      end
+
+      def self.usage
+        topic_list = TOPICS.map { |t| "  #{t}" }.join("\n")
+
+        <<~USAGE
+          Usage: belt explain <topic>
+
+          Display documentation for a Belt concept or feature.
+
+          Available topics:
+          #{topic_list}
+
+          Aliases:
+            routes, route, router     → routing
+            controller                → controllers
+            model, activeitem         → models
+            deploy, terraform         → deployment
+            generate, scaffold        → generators
+            handler, lambda           → lambda_handler
+            project, layout           → structure
+            logs, logging, metrics    → observability
+            backup                    → backups
+            plugin                    → plugins
+            irb, repl                 → console
+
+          Examples:
+            belt explain routing
+            belt explain controllers
+            belt explain deploy
+            belt explain models
+        USAGE
+      end
+    end
+  end
+end

data/lib/belt/cli/frontend_command.rb

@@ -5,6 +5,7 @@ require 'erb'
 require 'json'
 require 'open3'
 require_relative 'app_detection'
+require_relative 'frontend_registry'
 
 module Belt
   module CLI
@@ -15,33 +16,39 @@ module Belt
       include AppDetection
 
       def self.run(args)
+        name = FrontendRegistry.extract_flag!(args, '--name')
+        path = FrontendRegistry.extract_flag!(args, '--path')
         framework = args.shift
 
         if framework.nil? || !FRAMEWORKS.include?(framework)
-          puts "Usage: belt generate frontend <#{FRAMEWORKS.join('|')}>"
+          puts "Usage: belt generate frontend <#{FRAMEWORKS.join('|')}> [--name NAME] [--path DIR]"
           puts "\nScaffolds a frontend application with build tooling and API client."
           puts "\nExamples:"
           puts '  belt generate frontend react'
           puts '  belt generate frontend vue'
+          puts '  belt generate frontend react --name ops --path ops-app'
           exit 1
         end
 
-        new(framework).generate
+        new(framework, name: name, path: path).generate
       end
 
-      def initialize(framework, quiet: false, announce: true)
+      def initialize(framework, quiet: false, announce: true, name: nil, path: nil)
         @framework = framework
         @quiet = quiet
         @announce = announce
         @app_name = detect_app_name
         @module_name = @app_name.split(/[-_]/).map(&:capitalize).join
+        @name = name || (path ? File.basename(path) : 'frontend')
+        @path = path || name || 'frontend'
+        @frontend = Frontend.new(name: @name, path: @path, default: @name == 'frontend' && @path == 'frontend')
       end
 
       def generate
-        dest_dir = 'frontend'
+        dest_dir = @frontend.path
 
         if Dir.exist?(dest_dir) && !Dir.empty?(dest_dir)
-          puts "Directory 'frontend/' already exists and is not empty."
+          puts "Directory '#{dest_dir}/' already exists and is not empty."
           exit 1
         end
 
@@ -54,8 +61,9 @@ module Belt
         end
 
         copy_template(framework_dir, dest_dir)
+        register_frontend!
 
-        puts "\n✓ Frontend (#{@framework}) created in frontend/" unless @quiet
+        puts "\n✓ Frontend (#{@framework}) created in #{dest_dir}/" unless @quiet
 
         install_dependencies(dest_dir)
         setup_frontend_infra_for_existing_environments
@@ -64,7 +72,11 @@ module Belt
         return if @quiet || !@announce
 
         puts "\nNext steps:"
-        puts '  belt server                   # Start local dev server'
+        if @frontend.name == 'frontend'
+          puts '  belt server                   # Start local dev server'
+        else
+          puts "  belt server --frontend #{@frontend.name}"
+        end
         puts '  belt deploy                   # Deploy everything to AWS'
       end
 
@@ -88,9 +100,18 @@ module Belt
         end
       end
 
+      def register_frontend!
+        custom = @frontend.name != 'frontend' || @frontend.path != 'frontend'
+        config_exists = FrontendRegistry.find_config_path
+        return unless custom || config_exists
+
+        dest = FrontendRegistry.register!(name: @frontend.name, path: @frontend.path)
+        puts "  update  #{dest} (#{@frontend.name})" unless @quiet
+      end
+
       def setup_frontend_infra_for_existing_environments
         module_dir = 'infrastructure/modules/app'
-        frontend_tf = File.join(module_dir, 'frontend.tf')
+        frontend_tf = File.join(module_dir, "#{@frontend.tf_name == 'frontend' ? 'frontend' : @frontend.tf_name}.tf")
 
         if File.exist?(frontend_tf)
           puts "  skip    #{frontend_tf} (already exists)" unless @quiet
@@ -101,7 +122,7 @@ module Belt
 
         puts "\n  Setting up frontend infrastructure..." unless @quiet
         require_relative 'frontend_setup_command'
-        FrontendSetupCommand.new(nil, quiet: true).run
+        FrontendSetupCommand.new(nil, quiet: true, frontend: @frontend).run
         puts "  create  #{frontend_tf}" unless @quiet
       end
 
@@ -118,7 +139,7 @@ module Belt
         require_relative 'views_command'
         resources.each do |resource_name|
           fields = ViewsCommand.read_schema_fields(resource_name)
-          ViewsCommand.new(resource_name, fields, force: true).generate
+          ViewsCommand.new(resource_name, fields, force: true, frontend: @frontend).generate
         end
       end