belt 0.2.17 → 0.3.15

data/lib/belt/cli/routes_command.rb

@@ -7,12 +7,14 @@ require_relative '../route_dsl'
 require_relative '../table_inference'
 require_relative 'routes_command/schema_loader'
 require_relative 'routes_command/route_inference'
+require_relative 'routes_command/request_model_inference'
 
 module Belt
   module CLI
     class RoutesCommand
       include SchemaLoader
       include RouteInference
+      include RequestModelInference
 
       def self.run(args)
         new(args).run
@@ -33,6 +35,11 @@ module Belt
         dsl = load_routes(routes_file)
         @table_inference = TableInference.new(@options[:tables_file])
         routes = collect_routes(dsl)
+
+        # Convention-based request_model inference from contracts
+        contracts_file = resolve_contracts_file(routes_file)
+        infer_request_models!(routes, contracts_file) if contracts_file
+
         routes = apply_grep(routes) if @options[:grep]
 
         warn 'Warning: --output-dir has no effect without --namespace' if @options[:output_dir] && !@options[:namespace]
@@ -114,10 +121,34 @@ module Belt
           gateway.routes.each do |route|
             routes << build_route_hash(route, gateway)
           end
+          inject_welcome_route!(routes, gateway) unless root_route?(gateway)
         end
         routes.sort_by { |r| route_specificity(r[:path], r[:verb]) }
       end
 
+      # Ensure every gateway has a GET / route so the API Gateway resource is created.
+      # Without this, visiting the root URL returns a 404 at the gateway level before
+      # the request ever reaches Lambda.
+      def root_route?(gateway)
+        gateway.routes.any? { |r| r.method == 'GET' && normalize_path(r.path) == '/' }
+      end
+
+      def inject_welcome_route!(routes, gateway)
+        routes << {
+          name: 'root',
+          verb: 'GET',
+          path: '/',
+          gateway: gateway.name,
+          lambda: gateway.default_lambda.to_s,
+          controller: 'welcome',
+          action: 'show',
+          auth: 'none',
+          tables: [],
+          request_model: '',
+          response_model: ''
+        }
+      end
+
       def build_route_hash(route, gateway)
         hash = {
           name: extract_route_name(route.path),
@@ -250,18 +281,8 @@ module Belt
       def output_concise(routes)
         return puts('No routes defined.') if routes.empty?
 
-        multi_gateway = routes.map { |r| r[:gateway] }.uniq.length > 1
         verb_w = [routes.map { |r| r[:verb].length }.max, 6].max
         path_w = [routes.map { |r| r[:path].length }.max, 4].max
-
-        if multi_gateway
-          output_concise_multi_gateway(routes, verb_w, path_w)
-        else
-          output_concise_single_gateway(routes, verb_w, path_w)
-        end
-      end
-
-      def output_concise_multi_gateway(routes, verb_w, path_w)
         gw_w = [routes.map { |r| r[:gateway].to_s.length }.max, 7].max
         lam_w = [routes.map { |r| r[:lambda].length }.max, 6].max
 
@@ -278,15 +299,6 @@ module Belt
         end
       end
 
-      def output_concise_single_gateway(routes, verb_w, path_w)
-        puts "#{'VERB'.ljust(verb_w)}  #{'PATH'.ljust(path_w)}  CONTROLLER#ACTION"
-        puts '-' * (verb_w + path_w + 30)
-
-        routes.each do |r|
-          puts "#{r[:verb].ljust(verb_w)}  #{r[:path].ljust(path_w)}  #{r[:controller]}##{r[:action]}"
-        end
-      end
-
       def route_specificity(path, verb)
         segments = path.split('/').reject(&:empty?)
         param_count = segments.count { |s| s.start_with?('{') }

data/lib/belt/cli/server_command.rb

@@ -4,6 +4,7 @@ require 'base64'
 require 'json'
 require_relative 'app_detection'
 require_relative 'frontend_env_map'
+require_relative 'frontend_registry'
 require_relative 'terraform_command'
 
 module Belt
@@ -16,6 +17,7 @@ module Belt
       def self.run(args)
         port = DEFAULT_PORT
         open_browser = false
+        frontend_name = FrontendRegistry.extract_flag!(args, '--frontend')
 
         i = 0
         while i < args.length
@@ -34,7 +36,7 @@ module Belt
           i += 1
         end
 
-        new(port: port, open_browser: open_browser).run
+        new(port: port, open_browser: open_browser, frontend_name: frontend_name).run
       end
 
       def self.help_text
@@ -45,37 +47,41 @@ module Belt
                  belt s [options]
 
           Options:
-            -p, --port PORT    Port to serve on (default: #{DEFAULT_PORT})
-            -o, --open         Open browser after starting
-            -h, --help         Show this help
+            -p, --port PORT          Port to serve on (default: #{DEFAULT_PORT})
+            --frontend NAME          Which frontend to start (when several exist)
+            -o, --open               Open browser after starting
+            -h, --help               Show this help
 
           Behavior:
-            • If frontend/ exists → runs the frontend dev server (npm run dev)
-              Injects env from frontend/env.yml (or default VITE_API_URL) using
+            • If a frontend exists → runs its dev server (npx vite)
+              Injects env from <frontend>/env.yml (or default VITE_API_URL) using
               terraform outputs when available.
             • If no frontend → serves the welcome page via a local HTTP server
               After deploy, shows live API URL and deployment status.
 
           Note: The backend is serverless (AWS Lambda). Use `belt deploy` to deploy
           your backend to AWS. Local frontend development reads the env map (or
-          frontend/.env via `belt frontend env <env>`).
+          <frontend>/.env via `belt frontend env <env>`).
 
           Examples:
-            belt server                 # Start on port #{DEFAULT_PORT}
-            belt s -p 4000             # Start on port 4000
-            belt s --open              # Start and open browser
+            belt server                      # Start on port #{DEFAULT_PORT}
+            belt s -p 4000                   # Start on port 4000
+            belt s --frontend ops            # Start the ops frontend
+            belt s --open                    # Start and open browser
         HELP
       end
 
-      def initialize(port:, open_browser: false)
+      def initialize(port:, open_browser: false, frontend_name: nil)
         @port = port
         @open_browser = open_browser
+        @frontend_name = frontend_name
         @app_name = detect_app_name
         @api_url = detect_api_url
+        @frontend = resolve_frontend
       end
 
       def run
-        if Dir.exist?('frontend') && File.exist?('frontend/package.json')
+        if @frontend&.exists?
           run_frontend_dev_server
         else
           run_welcome_server
@@ -84,8 +90,15 @@ module Belt
 
       private
 
+      def resolve_frontend
+        registry = FrontendRegistry.new
+        return nil if registry.empty? && @frontend_name.nil?
+
+        registry.resolve!(@frontend_name)
+      end
+
       def run_frontend_dev_server
-        puts "🚀 Starting frontend dev server on port #{@port}..."
+        puts "🚀 Starting #{@frontend.label} dev server on port #{@port}..."
         build_env = frontend_process_env
         api_url = build_env['VITE_API_URL'] || build_env['REACT_APP_API_URL'] ||
                   build_env['NEXT_PUBLIC_API_URL'] || @api_url
@@ -102,7 +115,7 @@ module Belt
         env = { 'PORT' => @port.to_s }.merge(build_env)
 
         # Prefer the dev script with the port flag for Vite-based setups
-        Dir.chdir('frontend') do
+        Dir.chdir(@frontend.path) do
           exec(env, 'npx', 'vite', '--port', @port.to_s)
         end
       end
@@ -112,7 +125,7 @@ module Belt
         env_name = @deploy_env || ENV.fetch('BELT_ENV', nil) || TerraformCommand.list_environments.first
         return {} unless env_name
 
-        FrontendEnvMap.new(env_name).process_env
+        FrontendEnvMap.new(env_name, frontend_path: @frontend.path).process_env
       rescue StandardError
         # Fall back to legacy api_url detection if map resolution fails
         @api_url ? { 'VITE_API_URL' => @api_url } : {}

data/lib/belt/cli/tables_command.rb

@@ -243,7 +243,9 @@ module Belt
       end
 
       def table_name(model_name)
-        "${var.app_name}-${var.environment}-#{Belt::Inflector.pluralize(model_name)}"
+        # Dasherize to match ActiveItem's table_name_for convention:
+        # class_name.underscore.dasherize.pluralize
+        "${var.app_name}-${var.environment}-#{Belt::Inflector.pluralize(model_name).tr('_', '-')}"
       end
     end
   end

data/lib/belt/cli/terraform_command.rb

@@ -55,6 +55,7 @@ module Belt
       def run
         validate!
         apply_env_config!
+        build_zip_artifacts! if %w[plan apply].include?(@action)
         env_dir = File.join(@infra_dir, @env)
         args = ['terraform', @action, *@extra_args]
         puts "belt → #{args.join(' ')}  (in #{env_dir}/)"
@@ -69,6 +70,14 @@ module Belt
         puts "  🔑 Using AWS profile: #{env_config.aws_profile}" if env_config.aws_profile?
       end
 
+      def build_zip_artifacts!
+        require_relative 'zip_artifact_builder'
+        ZipArtifactBuilder.build!(
+          project_root: File.expand_path('..', @infra_dir),
+          infra_dir: @infra_dir
+        )
+      end
+
       def validate!
         unless @infra_dir
           abort "Error: No infrastructure/ directory found. Run `belt generate environment #{@env}` first."

data/lib/belt/cli/views_command.rb

@@ -3,6 +3,7 @@
 require 'fileutils'
 require 'erb'
 require_relative '../inflector'
+require_relative 'frontend_registry'
 
 module Belt
   module CLI
@@ -11,16 +12,19 @@ module Belt
 
       def self.run(args)
         force = args.delete('--force') || args.delete('-f')
+        frontend_name = FrontendRegistry.extract_flag!(args, '--frontend')
 
         name = args.shift
         if name.nil? || name.empty?
           puts 'Usage: belt generate views <resource> [field:type ...] [options]'
           puts "\nGenerates React pages for all REST actions (index, show, new, edit)."
           puts "\nOptions:"
-          puts '  --force, -f    Overwrite existing files without prompting'
+          puts '  --force, -f         Overwrite existing files without prompting'
+          puts '  --frontend NAME     Target frontend when several exist'
           puts "\nExamples:"
           puts '  belt generate views post title:string content:text status:string'
           puts '  belt generate views comment body:text author:string'
+          puts '  belt generate views bag --frontend ops'
           exit 1
         end
 
@@ -32,7 +36,8 @@ module Belt
         # If no fields provided, try to read from contracts.rb
         fields = read_schema_fields(name) if fields.empty?
 
-        new(name, fields, force: force).generate
+        frontend = FrontendRegistry.new.resolve!(frontend_name)
+        new(name, fields, force: force, frontend: frontend).generate
       end
 
       def self.read_schema_fields(name)
@@ -75,23 +80,25 @@ module Belt
         end
       end
 
-      def initialize(name, fields, force: false)
+      def initialize(name, fields, force: false, quiet: false, frontend: nil)
         @name = name.downcase.gsub(/[^a-z0-9_]/, '_')
         @fields = fields
         @force = force
+        @quiet = quiet
         @overwrite_all = false
         @singular_name = Belt::Inflector.singularize(@name)
         @resource_name = Belt::Inflector.pluralize(@singular_name)
         @class_name = Belt::Inflector.classify(@singular_name)
+        @frontend = frontend || FrontendRegistry.new.resolve!
       end
 
       def generate
-        unless Dir.exist?('frontend/src')
-          puts '✗ No frontend/ directory found. Run `belt generate frontend react` first.'
+        unless Dir.exist?(@frontend.src_dir)
+          puts "✗ No #{@frontend.src_dir}/ directory found. Run `belt generate frontend react` first."
           exit 1
         end
 
-        pages_dir = "frontend/src/pages/#{@resource_name}"
+        pages_dir = "#{@frontend.src_dir}/pages/#{@resource_name}"
         @plural_class_name = Belt::Inflector.camelize(@resource_name)
         FileUtils.mkdir_p(pages_dir)
 
@@ -103,14 +110,7 @@ module Belt
 
         inject_routes
 
-        puts "\n✓ Views for '#{@singular_name}' generated!"
-        puts "\nFiles created:"
-        puts "  #{pages_dir}/#{@plural_class_name}Index.jsx"
-        puts "  #{pages_dir}/#{@class_name}Show.jsx"
-        puts "  #{pages_dir}/#{@class_name}New.jsx"
-        puts "  #{pages_dir}/#{@class_name}Edit.jsx"
-        puts "  #{pages_dir}/#{@class_name}Form.jsx"
-        puts '  frontend/src/App.jsx (updated)'
+        puts "\n✓ Views for '#{@singular_name}' generated!" unless @quiet
       end
 
       private
@@ -176,7 +176,7 @@ module Belt
       end
 
       def inject_routes
-        app_jsx = 'frontend/src/App.jsx'
+        app_jsx = @frontend.app_jsx
         return unless File.exist?(app_jsx)
 
         content = File.read(app_jsx)

data/lib/belt/cli/zip_artifact_builder.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'open3'
+
+module Belt
+  module CLI
+    # Builds zip files that Terraform `filebase64sha256(...)` / `filename = "...zip"`
+    # references before plan/apply. Conveyor Belt packages Ruby lambdas itself;
+    # sidecar functions (Node image processors, Cognito triggers, …) are plain
+    # `aws_lambda_function` resources that expect a zip on disk at plan time.
+    #
+    # Node packages (`package.json`) are installed in Docker on linux/amd64 so
+    # native addons like `sharp` match Lambda. Plain JS directories are zipped
+    # as-is. Existing zips are reused when a source hash still matches.
+    class ZipArtifactBuilder
+      NODE_DOCKER_IMAGE = 'public.ecr.aws/lambda/nodejs:20-x86_64'
+      ZIP_REF = /(?:filebase64sha256\(\s*|filename\s*=\s*)["']([^"']+\.zip)["']/
+
+      def self.build!(project_root: Dir.pwd, infra_dir: 'infrastructure')
+        new(project_root: project_root, infra_dir: infra_dir).build!
+      end
+
+      def initialize(project_root:, infra_dir:)
+        @project_root = File.expand_path(project_root)
+        @infra_dir = File.expand_path(infra_dir, @project_root)
+      end
+
+      Artifact = Struct.new(:zip_path, :source_dir, keyword_init: true)
+
+      def build!
+        artifacts = discover_artifacts
+        return if artifacts.empty?
+
+        artifacts.each { |artifact| ensure_zip!(artifact) }
+      end
+
+      private
+
+      def discover_artifacts
+        return [] unless Dir.exist?(@infra_dir)
+
+        zips = []
+        tf_files.each do |tf_file|
+          File.read(tf_file).scan(ZIP_REF).flatten.each do |raw_path|
+            zip_path = resolve_zip_path(tf_file, raw_path)
+            next unless zip_path
+
+            zips << zip_path
+          end
+        end
+
+        zips.uniq.filter_map do |zip_path|
+          source_dir = File.dirname(zip_path)
+          next unless Dir.exist?(source_dir)
+
+          Artifact.new(zip_path: zip_path, source_dir: source_dir)
+        end
+      end
+
+      def tf_files
+        Dir.glob(File.join(@infra_dir, '**/*.tf')).reject { |path| path.include?('/.terraform/') }
+      end
+
+      # Skip interpolations other than ${path.module} — we can't resolve those
+      # without running terraform.
+      def resolve_zip_path(tf_file, raw_path)
+        return if raw_path.match?(/\$\{(?!path\.module\})/)
+
+        tf_dir = File.dirname(File.expand_path(tf_file, @project_root))
+        expanded = raw_path.gsub('${path.module}', tf_dir)
+        File.expand_path(expanded)
+      end
+
+      def ensure_zip!(artifact)
+        label = relative_to_root(artifact.zip_path)
+        zip_exists = File.file?(artifact.zip_path)
+        hashed = File.file?(hash_file_for(artifact))
+
+        if zip_exists && (!hashed || hash_unchanged?(artifact))
+          puts "  ♻️  #{label} unchanged — skipping rebuild" if hashed
+          return
+        end
+
+        puts "  📦 Building #{label}..."
+        if node_package?(artifact.source_dir)
+          build_node_zip!(artifact)
+        else
+          build_js_zip!(artifact)
+        end
+        write_hash!(artifact)
+        puts "  ✅ #{label} ready"
+      end
+
+      def node_package?(dir)
+        File.file?(File.join(dir, 'package.json'))
+      end
+
+      def build_node_zip!(artifact)
+        ensure_docker!
+        install_node_modules!(artifact.source_dir)
+        zip_contents!(artifact, node_zip_entries(artifact.source_dir))
+      end
+
+      def build_js_zip!(artifact)
+        entries = js_zip_entries(artifact.source_dir)
+        abort "✗ #{relative_to_root(artifact.source_dir)} has no .js/.mjs files to zip" if entries.empty?
+
+        zip_contents!(artifact, entries)
+      end
+
+      def node_zip_entries(dir)
+        entries = js_zip_entries(dir)
+        entries << 'package.json' if File.file?(File.join(dir, 'package.json'))
+        entries << 'node_modules' if Dir.exist?(File.join(dir, 'node_modules'))
+        entries.uniq
+      end
+
+      def js_zip_entries(dir)
+        Dir.children(dir).grep(/\.(mjs|js|cjs)\z/).sort
+      end
+
+      def install_node_modules!(source_dir)
+        lockfile = File.join(source_dir, 'package-lock.json')
+        install = File.file?(lockfile) ? 'npm ci --omit=dev' : 'npm install --omit=dev'
+        uid = Process.uid
+        gid = Process.gid
+
+        docker_cmd = [
+          'docker', 'run', '--rm',
+          '--platform', 'linux/amd64',
+          '--entrypoint', '',
+          '-v', "#{source_dir}:/var/task",
+          '-w', '/var/task',
+          NODE_DOCKER_IMAGE,
+          '/bin/bash', '-c',
+          "rm -rf node_modules && #{install} && chown -R #{uid}:#{gid} ."
+        ]
+
+        output, status = Open3.capture2e(*docker_cmd)
+        return if status.success?
+
+        puts output
+        abort "\n✗ Node Lambda build failed for #{relative_to_root(source_dir)}. " \
+              'Is Docker running?'
+      end
+
+      def zip_contents!(artifact, entries)
+        FileUtils.rm_f(artifact.zip_path)
+        zip_name = File.basename(artifact.zip_path)
+
+        Dir.chdir(artifact.source_dir) do
+          output, status = Open3.capture2e('zip', '-qr', zip_name, *entries)
+          unless status.success?
+            puts output
+            abort "\n✗ zip failed for #{relative_to_root(artifact.zip_path)}"
+          end
+        end
+      end
+
+      def ensure_docker!
+        _, status = Open3.capture2e('docker', 'info')
+        return if status.success?
+
+        abort "✗ Docker is not running. It's required to build Node Lambda zips for linux/amd64."
+      end
+
+      def hash_unchanged?(artifact)
+        hash_file = hash_file_for(artifact)
+        return false unless File.file?(hash_file)
+
+        File.read(hash_file).strip == source_hash(artifact.source_dir)
+      end
+
+      def write_hash!(artifact)
+        File.write(hash_file_for(artifact), "#{source_hash(artifact.source_dir)}\n")
+      end
+
+      def hash_file_for(artifact)
+        File.join(artifact.source_dir, ".#{File.basename(artifact.source_dir)}-hash")
+      end
+
+      def source_hash(dir)
+        files = Dir.children(dir).select do |name|
+          name.match?(/\.(mjs|js|cjs)\z/) || name == 'package.json' || name == 'package-lock.json'
+        end.sort
+
+        digest = Digest::SHA256.new
+        files.each { |name| digest.update(File.binread(File.join(dir, name))) }
+        digest.hexdigest
+      end
+
+      def relative_to_root(path)
+        path.sub(%r{\A#{Regexp.escape(@project_root)}/?}, '')
+      end
+    end
+  end
+end

data/lib/belt/cli.rb

@@ -6,6 +6,7 @@ require_relative 'cli/env_resolver'
 require_relative 'cli/new_command'
 require_relative 'cli/generate_command'
 require_relative 'cli/destroy_command'
+require_relative 'cli/index_command'
 require_relative 'cli/frontend_command'
 require_relative 'cli/frontend_setup_command'
 require_relative 'cli/frontend_deploy_command'
@@ -25,6 +26,7 @@ require_relative 'cli/console_command'
 require_relative 'cli/logs_command'
 require_relative 'cli/doctor_command'
 require_relative 'cli/plugin_command'
+require_relative 'cli/explain_command'
 
 module Belt
   module CLI
@@ -41,6 +43,7 @@ module Belt
       'setup' => Belt::CLI::SetupCommand,
       'doctor' => Belt::CLI::DoctorCommand,
       'plugin' => Belt::CLI::PluginCommand,
+      'explain' => Belt::CLI::ExplainCommand,
       'deploy' => Belt::CLI::DeployCommand,
       'frontend' => Belt::CLI::FrontendEnvCommand,
       %w[server s] => Belt::CLI::ServerCommand,
@@ -54,7 +57,7 @@ module Belt
     TERRAFORM_ACTIONS = Belt::CLI::TerraformCommand::ACTIONS
 
     # Commands that can run without being inside a Belt project
-    STANDALONE_COMMANDS = %w[new version --version -v doctor].freeze
+    STANDALONE_COMMANDS = %w[new version --version -v doctor explain].freeze
 
     def self.start(args)
       command = args.shift
@@ -97,18 +100,19 @@ module Belt
         Commands:
           new <app_name> [--frontend react]           Create a new Belt application
           generate <scaffold|model|controller> <name> Generate components
-          generate frontend <react|vue|svelte>        Scaffold a frontend app
-          generate views <resource> [fields...]       Generate React pages for REST actions
+          generate frontend <react|vue|svelte>        Scaffold a frontend app [--name --path]
+          generate views <resource> [fields...]       Generate React pages [--frontend NAME]
           generate environment <name>                 Create a new environment
           destroy <scaffold|model|controller> <name>  Remove generated components
-          destroy frontend                            Remove the frontend/ directory
+          destroy frontend [--frontend NAME]          Remove a frontend directory
           destroy views <resource>                    Remove React pages for a resource
           destroy environment <name>                  Remove an environment directory
-          server                                      Start local dev server (frontend)
+          server [--frontend NAME]                    Start local dev server (frontend)
           s                                           Alias for server
           deploy [environment]                        Deploy to AWS (init → plan → apply)
-          deploy frontend <env>                       Build and deploy frontend to AWS
-          frontend env <env>                          Write frontend/.env from terraform outputs
+          deploy frontend <env> [--frontend NAME]     Build and deploy frontend(s) to AWS
+          frontend env <env> [--frontend NAME]        Write <frontend>/.env from terraform outputs
+          frontend list                               List configured frontends
           routes [-g PATTERN] [-f json]               Show route definitions
           contracts [-g PATTERN] [-f json]            Show API request/response contracts
           lambda-config [-e ENV] [-f json|terraform]  Show merged lambda configuration
@@ -120,9 +124,10 @@ module Belt
           -T [-g PATTERN] [-a]                        Alias for tasks
           setup state                                 Create/select S3 state bucket
           setup tables <env>                          Generate DynamoDB tables from schema
-          setup frontend <env>                        Generate S3 + CloudFront infrastructure
+          setup frontend [--name NAME]                Generate S3 + CloudFront infrastructure
           doctor                                      Check system dependencies and AWS config
           plugin new <name>                           Scaffold a new Belt plugin gem
+          explain <topic>                             Explain a Belt concept (routing, models, …)
           init [environment] <env>                    terraform init for environment
           plan [environment] <env>                    terraform plan for environment
           apply [environment] <env>                   terraform apply for environment
@@ -146,11 +151,14 @@ module Belt
           belt generate scaffold post title:string content:text status:string
           belt destroy scaffold post
           belt generate frontend react
+          belt generate frontend react --name ops --path ops-app
           belt server                   # Start local frontend server
+          belt server --frontend ops
           belt deploy                   # Deploy dev to AWS
           belt deploy prod --auto       # Deploy prod without confirmation
           belt deploy frontend wups
-          belt frontend env wups        # Smart-merge TF outputs into frontend/.env
+          belt deploy frontend wups --frontend ops
+          belt frontend env wups        # Smart-merge TF outputs into <frontend>/.env
           belt setup frontend wups
           belt apply wups
           belt tasks                    # list all rake tasks