belt 0.3.4 → 0.3.6

data/lib/belt/cli/routes_command/request_model_inference.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Belt
+  module CLI
+    class RoutesCommand
+      # Infers request_model and response_model from contracts using naming conventions.
+      #
+      # Request model convention cascade (first match wins):
+      #   1. :<verb>_<gateway>_<singular_resource>  (e.g. :create_customer_item)
+      #   2. :<verb>_<singular_resource>            (e.g. :create_item)
+      #
+      # Response model convention:
+      #   Singular of the resource name matches a `model` in contracts.
+      #   e.g. `resources :items` → looks for `model :item` in contracts.rb
+      #
+      # Only request_model inference applies to body-accepting verbs (POST/PUT/PATCH).
+      # Response model inference applies to all verbs on resource routes.
+      # Explicit values always win — inference only fills in blanks.
+      module RequestModelInference
+        private
+
+        # Applies convention-based request_model inference to all routes.
+        # Requires the set of known contract names from contracts.rb.
+        def infer_request_models!(routes, contracts_file)
+          contract_names = load_contract_names(contracts_file)
+          return if contract_names[:request].empty? && contract_names[:response].empty?
+
+          routes.each do |route|
+            infer_request_model_for!(route, contract_names[:request])
+            infer_response_model_for!(route, contract_names[:response])
+          end
+        end
+
+        def load_contract_names(contracts_file)
+          empty_result = { request: Set.new, response: Set.new }
+          return empty_result unless contracts_file && File.exist?(contracts_file)
+
+          # Reset application state for clean contract loading
+          Belt.instance_variable_set(:@application, nil)
+          begin
+            eval(File.read(contracts_file), binding, contracts_file) # rubocop:disable Security/Eval
+          rescue StandardError => e
+            warn "Warning: Failed to load contracts for inference: #{e.message}"
+            return empty_result
+          end
+
+          schema = Belt.application.schema.to_h
+          request_names = Set.new
+          response_names = Set.new
+          (schema[:request_models] || {}).each_key { |name| request_names << name.to_s }
+          (schema[:response_models] || {}).each_key { |name| response_names << name.to_s }
+          { request: request_names, response: response_names }
+        end
+
+        def infer_request_model_for!(route, request_contracts)
+          return if request_contracts.empty?
+          return unless route[:request_model].to_s.empty?
+          return unless body_accepting_verb?(route[:verb])
+
+          inferred = infer_request_model_for_route(route, request_contracts)
+          route[:request_model] = inferred if inferred
+        end
+
+        def infer_response_model_for!(route, response_contracts)
+          return if response_contracts.empty?
+          return unless route[:response_model].to_s.empty?
+
+          inferred = infer_response_model_for_route(route, response_contracts)
+          route[:response_model] = inferred if inferred
+        end
+
+        def infer_request_model_for_route(route, contract_names)
+          verb_prefix = infer_verb_prefix(route[:verb], route[:action])
+          return nil unless verb_prefix
+
+          resource_name = extract_singular_resource(route)
+          return nil unless resource_name
+
+          gateway = route[:gateway]
+
+          # Cascade: gateway-scoped first, then generic
+          candidates = [
+            "#{verb_prefix}_#{gateway}_#{resource_name}",
+            "#{verb_prefix}_#{resource_name}"
+          ]
+
+          candidates.find { |candidate| contract_names.include?(candidate) }
+        end
+
+        def infer_response_model_for_route(route, response_contracts)
+          resource_name = extract_singular_resource(route)
+          return nil unless resource_name
+
+          # Convention: singular resource name matches a response model
+          return resource_name if response_contracts.include?(resource_name)
+
+          nil
+        end
+
+        def infer_verb_prefix(verb, action)
+          # Map HTTP verb + action to the contract naming prefix
+          case action
+          when 'create' then 'create'
+          when 'update' then 'update'
+          else
+            # For non-standard actions on body verbs, don't infer
+            case verb
+            when 'POST' then 'create'
+            when 'PUT', 'PATCH' then 'update'
+            end
+          end
+        end
+
+        def extract_singular_resource(route)
+          # Extract the resource name from the path
+          segments = route[:path].split('/').reject(&:empty?)
+          # Find the last non-param segment that looks like a resource
+          resource_segments = segments.reject { |s| s.start_with?('{', ':') }
+          return nil if resource_segments.empty?
+
+          resource = resource_segments.last
+          Belt::Inflector.singularize(resource.gsub('-', '_'))
+        end
+
+        def body_accepting_verb?(verb)
+          %w[POST PUT PATCH].include?(verb)
+        end
+      end
+    end
+  end
+end

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]

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/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,7 +80,7 @@ module Belt
         end
       end
 
-      def initialize(name, fields, force: false, quiet: false)
+      def initialize(name, fields, force: false, quiet: false, frontend: nil)
         @name = name.downcase.gsub(/[^a-z0-9_]/, '_')
         @fields = fields
         @force = force
@@ -84,15 +89,16 @@ module Belt
         @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)
 
@@ -170,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

@@ -100,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
@@ -123,7 +124,7 @@ 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, …)
@@ -150,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

data/lib/belt/docs/deployment.md

@@ -85,6 +85,25 @@ belt routes --namespace api
 
 This is typically done automatically by `belt deploy`.
 
+## Sidecar Lambda Zips
+
+Conveyor Belt packages Ruby lambdas. Some apps also have standalone
+`aws_lambda_function` resources (Node image processors, Cognito triggers)
+whose Terraform uses `filename` + `filebase64sha256` pointing at a zip on disk.
+
+`belt deploy`, `belt plan`, and `belt apply` scan `infrastructure/**/*.tf` for
+those zip paths and build any that are missing (or whose source hash changed):
+
+- Directory with `package.json` — `npm ci` in Docker (`linux/amd64`, Lambda
+  Node image) so native addons like `sharp` match Lambda, then zip
+- Plain JS directory — zip the `.js` / `.mjs` files
+
+The zip lives next to the source (`image-processor/image-processor.zip`). This
+is the same pre-terraform step Stowzilla's `scripts/deploy.sh` does for the
+image processor. Existing zips with no hash file are left alone.
+
+Docker must be running for Node packages.
+
 ## Terraform Commands
 
 Belt wraps Terraform with environment awareness:
@@ -130,10 +149,16 @@ belt deploy prod      # explicit arg wins
 For apps with a frontend:
 
 ```bash
-belt deploy frontend <env>    # build + deploy to S3/CloudFront
-belt frontend env <env>       # generate .env from Terraform outputs
+belt deploy frontend <env>                  # build + deploy all frontends
+belt deploy frontend <env> --frontend ops   # deploy one named frontend
+belt frontend env <env>                     # generate .env from Terraform outputs
+belt frontend list                          # show configured frontends
 ```
 
+The directory is `frontend/` by default. Multiple SPAs are declared in
+`config/frontends.yml` — see `belt explain frontend`. Full `belt deploy <env>`
+deploys every configured frontend after terraform apply.
+
 ## See Also
 
 - `belt explain routing` — how routes map to infrastructure