belt 0.3.3 → 0.3.5

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

data/lib/belt/docs/frontend.md

@@ -0,0 +1,103 @@
+# Frontends
+
+Belt can host one or more JavaScript SPAs (React, Vue, or Svelte) next to the
+Lambda API. A typical app has a single `frontend/` directory. Some apps — Stowzilla
+is the example that drove this — have several independent SPAs (customer, ops,
+partners) that share the same models and API.
+
+## Single frontend (default)
+
+```bash
+belt new blog --frontend react
+# or, in an existing app:
+belt generate frontend react
+```
+
+That creates `frontend/`, S3 + CloudFront infrastructure, and wires CORS so the
+SPA can call the API. No config file is required.
+
+```bash
+belt server                       # local Vite dev server
+belt frontend env dev01           # write frontend/.env from terraform outputs
+belt deploy frontend dev01        # npm ci → build → S3 sync → CloudFront invalidation
+```
+
+## Multiple frontends
+
+Declare them in `config/frontends.yml` (or `.belt/frontends.yml`):
+
+```yaml
+frontends:
+  customer:
+    path: app
+    dist: build
+    default: true
+    bucket_output: web_app_bucket_name
+    url_output: web_app_url
+    cloudfront_domain_output: web_app_cloudfront_domain
+  ops:
+    path: ops-app
+    dist: build
+    bucket_output: ops_app_bucket_name
+    url_output: ops_app_url
+    cloudfront_domain_output: ops_app_cloudfront_domain
+```
+
+`path` is the directory. `dist` is the build output (`dist` by default; belt
+also auto-detects `build/` after `npm run build`). Terraform output names default
+to `frontend_*` for the `frontend` app and `{name}_frontend_*` for others — override
+them when existing infrastructure uses different names.
+
+If terraform exports a CloudFront **domain** instead of a distribution ID, set
+`cloudfront_domain_output` and skip `distribution_output`. Belt looks the ID up
+via AWS and will not probe `{name}_frontend_distribution_id`.
+
+```bash
+belt frontend list
+belt generate frontend react --name ops --path ops-app
+belt generate views bag --frontend ops
+belt generate scaffold order --frontend customer
+belt server --frontend ops
+belt frontend env dev01 --frontend customer
+belt deploy frontend dev01                  # all configured frontends
+belt deploy frontend dev01 --frontend ops   # just ops
+```
+
+If several frontends exist and you omit `--frontend`, generators and `belt server`
+use the one marked `default: true`. If none is default, they ask you to pick.
+
+`belt deploy frontend <env>` with no `--frontend` deploys every frontend that
+has a `package.json`. Full `belt deploy <env>` does the same after terraform apply.
+
+## Env maps
+
+Each frontend can have its own `env.yml` mapping process env names to terraform
+outputs:
+
+```yaml
+# app/env.yml
+VITE_API_URL: api_url
+VITE_COGNITO_USER_POOL_ID: cognito_user_pool_id
+VITE_COGNITO_CLIENT_ID: cognito_user_pool_client_id
+```
+
+The default `frontend/` directory also accepts `.belt/frontend_env.yml` as a
+fallback. See the existing env-map behavior: only mapped keys are written into
+`.env`; missing terraform outputs warn and do not clobber local values.
+
+## Infrastructure
+
+`belt setup frontend` (and `belt generate frontend`) writes S3 + CloudFront into
+`infrastructure/modules/app/frontend.tf`. Additional named frontends get
+`{name}_frontend.tf` with unique resource names and outputs
+(`ops_frontend_bucket_name`, …). Extra frontends get a CloudFront URL only —
+custom DNS stays on the default frontend unless you add records yourself.
+
+CORS: each CloudFront domain is added to `frontend_urls` on the conveyor-belt
+resource so SPA → API calls work.
+
+## See Also
+
+- `belt explain deployment` — how frontend deploy fits into `belt deploy`
+- `belt explain generators` — `belt generate frontend` / views
+- `belt explain structure` — where frontend directories live

data/lib/belt/docs/generators.md

@@ -51,8 +51,12 @@ Adds a frontend framework to the project:
 belt generate frontend react
 belt generate frontend vue
 belt generate frontend svelte
+belt generate frontend react --name ops --path ops-app
 ```
 
+`--name` and `--path` scaffold an additional SPA and register it in
+`config/frontends.yml`. See `belt explain frontend`.
+
 ### Views
 
 Generates React pages for a resource's REST actions:
@@ -60,8 +64,12 @@ Generates React pages for a resource's REST actions:
 ```bash
 belt generate views post title:string body:text status:string
 belt g views comment body:text author:string
+belt g views bag --frontend ops
 ```
 
+When the app has multiple frontends, pass `--frontend <name>` (or mark one
+`default: true` in `config/frontends.yml`).
+
 ### Auth
 
 Sets up Cognito authentication:
@@ -94,6 +102,7 @@ belt destroy model comment
 belt destroy controller admin/users
 belt destroy environment staging
 belt destroy frontend
+belt destroy frontend --frontend ops
 belt destroy views post
 ```
 

data/lib/belt/docs/structure.md

@@ -43,6 +43,7 @@ my-app/
 │   └── prod/
 │       └── ...
 ├── frontend/                      # Optional frontend (React/Vue/Svelte)
+├── config/frontends.yml           # Optional: multiple named frontends
 ├── Gemfile                        # Project-level dependencies (CLI, dev tools)
 ├── Rakefile                       # Rake tasks
 ├── AGENTS.md                      # AI agent guide
@@ -85,6 +86,8 @@ Terraform resources.
   `lambda/Gemfile` is what gets packaged into the Lambda.
 - **Config over code**: Lambda configuration (timeout, memory, env vars) goes in
   YAML files, not hardcoded in Terraform.
+- **Frontends**: Default directory is `frontend/`. Multiple SPAs (customer + ops,
+  etc.) are declared in `config/frontends.yml`. See `belt explain frontend`.
 
 ## See Also
 

data/lib/belt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.3.3'
+  VERSION = '0.3.5'
 end

data/lib/templates/frontend/react/env.yml.example

@@ -1,6 +1,6 @@
 # Declarative frontend env map for belt.
 # Left: env var your build tool reads. Right: terraform output name.
-# Copy to frontend/env.yml (or .belt/frontend_env.yml) and adjust.
+# Copy to <frontend>/env.yml (or .belt/frontend_env.yml for the default frontend/) and adjust.
 #
 # belt deploy frontend <env>  → injects these into npm run build
 # belt frontend env <env>     → smart-merges into frontend/.env for local dev