belt 0.2.8 → 0.2.10

data/lib/belt/cli/new_command.rb

@@ -18,6 +18,7 @@ module Belt
         bucket = nil
         environments = nil
         domain = nil
+        verbose = false
 
         i = 0
         while i < args.length
@@ -49,6 +50,8 @@ module Belt
             domain = args[i]
           when /^--domain=/
             domain = arg.split('=', 2).last
+          when '-v', '--verbose'
+            verbose = true
           else
             app_name ||= arg unless arg.start_with?('-')
           end
@@ -65,22 +68,33 @@ module Belt
           puts '  --state-bucket BUCKET_NAME     Alias for --bucket'
           puts '  --environments dev,prod        Comma-separated environments (default: dev,prod)'
           puts '                                 Use "none" to skip environment setup'
+          puts '  -v, --verbose                  List every created file (Rails-style)'
           exit 1
         end
 
-        new(app_name, frontend: frontend, bucket: bucket, environments: environments, domain: domain).generate
+        new(
+          app_name,
+          frontend: frontend,
+          bucket: bucket,
+          environments: environments,
+          domain: domain,
+          verbose: verbose
+        ).generate
       end
 
-      def initialize(app_name, frontend: nil, bucket: nil, environments: nil, domain: nil)
+      # rubocop:disable Metrics/ParameterLists -- keyword options for generator flags
+      def initialize(app_name, frontend: nil, bucket: nil, environments: nil, domain: nil, verbose: false)
         @app_name = app_name.gsub(/[^a-z0-9_-]/i, '_').downcase
         @module_name = @app_name.split(/[-_]/).map(&:capitalize).join
         @frontend = frontend
         @bucket = bucket
         @domain = domain
         @environments = parse_environments(environments)
+        @verbose = verbose
         @resolved_bucket = nil
         @state_setup_succeeded = false
       end
+      # rubocop:enable Metrics/ParameterLists
 
       def generate
         if Dir.exist?(@app_name)
@@ -88,9 +102,12 @@ module Belt
           exit 1
         end
 
+        preflight_check
+
         puts "Creating new Belt application: #{@app_name}"
         create_structure
         generate_module
+        puts '  create  app skeleton' unless @verbose
         generate_environments
         generate_frontend if @frontend
         init_git
@@ -110,6 +127,19 @@ module Belt
         env_string.split(',').map(&:strip).reject(&:empty?)
       end
 
+      def preflight_check
+        missing = []
+        { 'aws' => 'AWS CLI', 'terraform' => 'Terraform' }.each do |cmd, label|
+          _, status = Open3.capture2e(cmd, '--version')
+          missing << label unless status.success?
+        end
+
+        return if missing.empty?
+
+        puts "⚠ Missing: #{missing.join(', ')}"
+        puts "  Belt requires these tools to deploy. Install them, then run `belt doctor` to verify.\n\n"
+      end
+
       def create_structure
         directories.each { |dir| create_dir(dir) }
         files.each { |src, dest| create_file(src, dest) }
@@ -162,7 +192,7 @@ module Belt
           template_path = File.join(module_template_dir, template_name)
           content = ERB.new(File.read(template_path), trim_mode: '-').result(binding)
           File.write(dest_path, content)
-          puts "  create  #{dest_path}"
+          puts "  create  #{dest_path}" if @verbose
         end
       end
 
@@ -171,43 +201,62 @@ module Belt
 
         Dir.chdir(@app_name) do
           @environments.each do |env_name|
-            Belt::CLI::EnvironmentCommand.new(env_name, quiet: true, domain: @domain).generate
+            Belt::CLI::EnvironmentCommand.new(
+              env_name,
+              quiet: !@verbose,
+              announce: false,
+              domain: @domain
+            ).generate
           end
         end
+        puts "  create  environments (#{@environments.join(', ')})" unless @verbose
       end
 
       def setup_state
         return if @environments.empty?
 
-        Dir.chdir(@app_name) do
-          # Shared bucket: one per AWS account, all belt apps share it
-          @resolved_bucket = @bucket || 'belt-terraform-state'
-
-          # Attempt to actually create the bucket if credentials are available
-          if aws_configured?
-            puts "\n  Setting up Terraform state bucket..."
-            begin
-              Belt::CLI::SetupCommand.new(['--bucket', @resolved_bucket]).run_state_setup
-              @state_setup_succeeded = true
-            rescue SystemExit
-              puts '  ⚠ State bucket setup encountered an issue — run `belt setup state` to retry.'
-              @state_setup_succeeded = false
-            end
-          else
-            puts "\n  State bucket: #{@resolved_bucket}"
-            puts "  State keys:   #{s3_safe_name(@app_name)}/<env>/terraform.tfstate"
-            if @aws_error&.include?('ForbiddenException') || @aws_error&.include?('AccessDenied')
-              puts '  ⚠ AWS credentials found but access denied — check your profile/role configuration.'
-              puts "    #{@aws_error}" if @aws_error
-            else
-              puts '  ⚠ AWS credentials not detected — skipping state bucket creation.'
-            end
-            puts '  Run `belt setup state` after configuring credentials (aws sso login / AWS_PROFILE).'
-            @state_setup_succeeded = false
-          end
+        Dir.chdir(@app_name) { create_or_skip_state_bucket }
+      end
+
+      def create_or_skip_state_bucket
+        # Shared bucket: one per AWS account, all belt apps share it.
+        # Account ID suffix makes the name globally unique (S3 is a global namespace).
+        @resolved_bucket = if @bucket
+                             @bucket
+                           elsif aws_configured?
+                             "belt-terraform-state-#{@aws_account_id}"
+                           else
+                             'belt-terraform-state'
+                           end
+
+        if aws_configured?
+          create_state_bucket!
+        else
+          warn_missing_aws_for_state
+          @state_setup_succeeded = false
         end
       end
 
+      def create_state_bucket!
+        setup = Belt::CLI::SetupCommand.new(['--bucket', @resolved_bucket], quiet: true)
+        setup.run_state_setup
+        @resolved_bucket = setup.bucket_name
+        @state_setup_succeeded = true
+        puts "  ✓      state bucket #{@resolved_bucket}"
+      rescue SystemExit
+        puts '  ⚠      state bucket setup failed — run `belt setup state` to retry'
+        @state_setup_succeeded = false
+      end
+
+      def warn_missing_aws_for_state
+        if @aws_error&.include?('ForbiddenException') || @aws_error&.include?('AccessDenied')
+          puts '  ⚠      AWS credentials found but access denied — check profile/role'
+        else
+          puts '  ⚠      AWS credentials not detected — skipped state bucket'
+        end
+        puts '         run `belt doctor`, then `belt setup state`'
+      end
+
       def aws_configured?
         output, status = Open3.capture2e('aws', 'sts', 'get-caller-identity')
         if status.success?
@@ -226,45 +275,64 @@ module Belt
 
       def create_dir(dir)
         FileUtils.mkdir_p(dir)
-        puts "  create  #{dir}/"
+        puts "  create  #{dir}/" if @verbose
       end
 
       def create_file(template_name, dest_path)
         template_path = File.join(TEMPLATE_DIR, template_name)
         content = ERB.new(File.read(template_path), trim_mode: '-').result(binding)
         File.write(dest_path, content)
-        puts "  create  #{dest_path}"
+        puts "  create  #{dest_path}" if @verbose
       end
 
       def init_git
         Dir.chdir(@app_name) do
           system('git', 'init', '--quiet')
         end
-        puts "  init    #{@app_name}/.git/"
+        if @verbose
+          puts "  init    #{@app_name}/.git/"
+        else
+          puts '  init    git'
+        end
       end
 
       def run_bundle_install
         Dir.chdir(@app_name) do
-          puts "\n  Running bundle install..."
+          puts "\n  Running bundle install..." if @verbose
+          # Always --quiet: bundle's own progress is noise either way
           success = system('bundle', 'install', '--quiet')
           if success
-            puts '  ✓ Bundle installed'
+            puts '  ✓      bundle install'
           else
-            puts '  ⚠ bundle install failed — run it manually after resolving issues.'
+            puts '  ⚠      bundle install failed — run it manually after resolving issues'
           end
         end
       end
 
       def generate_frontend
+        frontend_cmd = nil
         Dir.chdir(@app_name) do
-          Belt::CLI::FrontendCommand.new(@frontend).generate
+          frontend_cmd = Belt::CLI::FrontendCommand.new(
+            @frontend,
+            quiet: !@verbose,
+            announce: false
+          )
+          frontend_cmd.generate
+        end
+        return if @verbose
+
+        puts "  create  frontend (#{@frontend})"
+        if frontend_cmd.npm_ok?
+          puts '  ✓      npm dependencies'
+        else
+          puts '  ⚠      npm install failed — run `cd frontend && npm install`'
         end
       end
 
       def print_next_steps
         puts "\nNext steps:"
         unless @state_setup_succeeded
-          puts '  # Configure AWS credentials (aws sso login / AWS_PROFILE)'
+          puts '  belt doctor                   # Verify AWS CLI, Terraform & credentials'
           puts '  belt setup state              # Create the S3 state bucket'
         end
         puts '  belt deploy                   # Deploy to AWS'

data/lib/belt/cli/path_gem_materializer.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'open3'
+require 'rubygems/package'
+
+module Belt
+  module CLI
+    # Turns Gemfile `path:` gems into real `.gem` files in vendor/cache and
+    # rewrites the Gemfile/lock so Docker `bundle install` produces a normal
+    # gem install (with specifications/). Required for Lambda bare `require`
+    # without bundler/setup.
+    #
+    # Only mutates files under +build_dir+ — never the app's real Gemfile.
+    class PathGemMaterializer
+      PathSource = Struct.new(:remote, :gems, keyword_init: true)
+      PathGem = Struct.new(:name, :version, keyword_init: true)
+
+      def self.materialize!(build_dir, project_root:)
+        new(build_dir, project_root: project_root).materialize!
+      end
+
+      def initialize(build_dir, project_root:)
+        @build_dir = build_dir
+        @project_root = project_root
+        @gemfile = File.join(build_dir, 'Gemfile')
+        @lockfile = File.join(build_dir, 'Gemfile.lock')
+      end
+
+      # @return [Array<String>] names of gems materialized (empty if none)
+      def materialize!
+        return [] unless File.exist?(@gemfile) && File.exist?(@lockfile)
+
+        sources = parse_path_sources(File.read(@lockfile))
+        return [] if sources.empty?
+
+        cache_dir = File.join(@build_dir, 'vendor', 'cache')
+        FileUtils.mkdir_p(cache_dir)
+
+        materialized = []
+        sources.each do |source|
+          source_path = resolve_remote(source.remote)
+          abort "✗ path gem source missing: #{source.remote} (resolved #{source_path})" unless Dir.exist?(source_path)
+
+          source.gems.each do |gem|
+            gem_file = build_gem(source_path, gem)
+            dest = File.join(cache_dir, File.basename(gem_file))
+            FileUtils.cp(gem_file, dest)
+            FileUtils.rm_f(gem_file)
+            rewrite_gemfile_path_to_version!(gem.name, gem.version)
+            materialized << gem.name
+          end
+        end
+
+        return [] if materialized.empty?
+
+        relock!(materialized)
+        materialized
+      end
+
+      private
+
+      def parse_path_sources(lockfile_content)
+        sources = []
+        lockfile_content.scan(/^PATH\n  remote: (.+)\n  specs:\n((?:    .+\n)*)/) do |remote, specs_block|
+          gems = []
+          specs_block.each_line do |line|
+            next unless line.match?(/^    \S/)
+            next if line.start_with?('      ') # dependency lines are deeper
+
+            match = line.match(/^    (\S+)\s+\(([^)]+)\)/)
+            gems << PathGem.new(name: match[1], version: match[2]) if match
+          end
+          sources << PathSource.new(remote: remote.strip, gems: gems) if gems.any?
+        end
+        sources
+      end
+
+      def resolve_remote(remote)
+        return remote if remote.start_with?('/')
+
+        File.expand_path(remote, @project_root)
+      end
+
+      def build_gem(source_path, gem)
+        gemspec = find_gemspec(source_path, gem.name)
+        abort "✗ No gemspec for path gem #{gem.name} under #{source_path}" unless gemspec
+
+        Dir.chdir(source_path) do
+          spec = Gem::Specification.load(File.basename(gemspec))
+          abort "✗ Failed to load #{gemspec}" unless spec
+
+          if spec.version.to_s != gem.version
+            abort "✗ path gem #{gem.name} version mismatch: gemspec #{spec.version}, lock #{gem.version}"
+          end
+
+          # Gem::Package.build writes the .gem into cwd
+          built = Gem::Package.build(spec)
+          File.expand_path(built)
+        end
+      end
+
+      def find_gemspec(source_path, gem_name)
+        preferred = File.join(source_path, "#{gem_name}.gemspec")
+        return preferred if File.exist?(preferred)
+
+        Dir.glob(File.join(source_path, '*.gemspec')).first
+      end
+
+      def rewrite_gemfile_path_to_version!(name, version)
+        content = File.read(@gemfile)
+        new_content = content.lines.map { |line| convert_path_line(line, name, version) }.join
+        abort "✗ Could not rewrite path: for gem #{name.inspect} in build Gemfile" if new_content == content
+        File.write(@gemfile, new_content)
+      end
+
+      # Converts `gem 'name', path: '...'` (and variants with other kwargs) into
+      # a version-pinned line. Leaves non-matching lines alone.
+      def convert_path_line(line, name, version)
+        return line unless line.match?(/gem\s+(['"])#{Regexp.escape(name)}\1/)
+        return line unless line.match?(/\bpath:\s*/)
+
+        quote = line[/gem\s+(['"])/, 1] || "'"
+        cleaned = line.sub(/,?\s*path:\s*['"][^'"]+['"]/, '')
+        cleaned.sub(/gem\s+(['"])#{Regexp.escape(name)}\1/) do
+          "gem #{quote}#{name}#{quote}, #{quote}#{version}#{quote}"
+        end
+      end
+
+      def relock!(gem_names)
+        Dir.chdir(@build_dir) do
+          # vendor/cache has the built .gem — Bundler resolves the unpublished version
+          output, status = Open3.capture2e('bundle', 'lock', '--update', *gem_names)
+          return if status.success?
+
+          abort "✗ Failed to re-lock after materializing path gems (#{gem_names.join(', ')}):\n#{output}"
+        end
+      end
+    end
+  end
+end

data/lib/belt/cli/setup_command.rb

@@ -38,11 +38,12 @@ module Belt
         end
       end
 
-      def initialize(args = [])
+      def initialize(args = [], quiet: false)
         @app_name = detect_app_name
         @env_name = nil
         @custom_bucket = nil
         @select_mode = false
+        @quiet = quiet
 
         parse_args(args)
 
@@ -67,7 +68,7 @@ module Belt
         @bucket_name = interactive_bucket_selection if @select_mode
         setup_or_verify_bucket
         apply_lifecycle(@bucket_name)
-        puts '  ensure  lifecycle rules (90-day noncurrent expiration)'
+        say '  ensure  lifecycle rules (90-day noncurrent expiration)'
         update_backend_config
         print_success_message
       end
@@ -81,12 +82,12 @@ module Belt
       end
 
       def verify_existing_bucket
-        puts "Found existing bucket: #{@bucket_name}"
+        say "Found existing bucket: #{@bucket_name}"
         audit = audit_bucket_security(@bucket_name)
-        print_security_audit(audit)
+        print_security_audit(audit) unless @quiet
 
         if audit.values.all?
-          puts "\n✓ Bucket '#{@bucket_name}' passes all security checks"
+          say "\n✓ Bucket '#{@bucket_name}' passes all security checks"
         else
           prompt_and_harden(audit)
         end
@@ -94,6 +95,12 @@ module Belt
 
       def prompt_and_harden(audit)
         puts "\n⚠ Bucket '#{@bucket_name}' has security issues."
+        # Auto-harden during belt new (quiet); interactive otherwise
+        if @quiet
+          harden_bucket(@bucket_name, audit)
+          return
+        end
+
         print "\nApply security hardening? [Y/n] "
         response = $stdin.gets&.strip&.downcase
         if response.nil? || response.empty? || response == 'y'
@@ -105,13 +112,15 @@ module Belt
       end
 
       def create_new_bucket
-        puts "Creating state bucket: #{@bucket_name} (#{@region})"
+        say "Creating state bucket: #{@bucket_name} (#{@region})"
         create_bucket(@bucket_name)
-        puts "  create  s3://#{@bucket_name}"
+        say "  create  s3://#{@bucket_name}"
         harden_bucket(@bucket_name, {})
       end
 
       def print_success_message
+        return if @quiet
+
         puts "\n✓ State bucket '#{@bucket_name}' is ready!"
         if @env_name
           puts "\n  cd infrastructure/#{@env_name} && terraform init"
@@ -120,6 +129,9 @@ module Belt
         end
       end
 
+      # Expose for quiet callers (e.g. belt new) that print their own summary
+      attr_reader :bucket_name
+
       private
 
       def parse_args(args)
@@ -138,8 +150,15 @@ module Belt
         end
       end
 
+      # One shared state bucket per AWS account (all belt apps use it).
+      # Account ID keeps the name globally unique — S3 names are a global namespace.
+      # Pattern: belt-terraform-state-<account_id>
       def resolve_bucket_name
-        @custom_bucket || 'belt-terraform-state'
+        return @custom_bucket if @custom_bucket
+        return "belt-terraform-state-#{@aws_account_id}" if @aws_account_id
+
+        # Placeholder until credentials are available (belt setup state re-resolves)
+        'belt-terraform-state'
       end
 
       # --- Interactive selection ---
@@ -238,9 +257,11 @@ module Belt
       end
 
       def run!(*args)
-        return if system(*args)
+        output, status = Open3.capture2e(*args)
+        return if status.success?
 
         puts "\n✗ Command failed: #{args.shelljoin}"
+        puts output.strip unless output.strip.empty?
         exit 1
       end
 
@@ -249,6 +270,10 @@ module Belt
         status.success? ? output : nil
       end
 
+      def say(message)
+        puts message unless @quiet
+      end
+
       # --- Backend config ---
 
       def update_backend_config
@@ -268,7 +293,7 @@ module Belt
           updated = content.gsub(/bucket\s*=\s*"[^"]+"/, "bucket  = \"#{@bucket_name}\"")
           if updated != content
             File.write(backend_file, updated)
-            puts "  update  #{backend_file} → bucket = \"#{@bucket_name}\""
+            say "  update  #{backend_file} → bucket = \"#{@bucket_name}\""
           end
         end
       end

data/lib/belt/cli.rb

@@ -21,6 +21,7 @@ require_relative 'cli/routes_command'
 require_relative 'cli/lambda_config_command'
 require_relative 'cli/tasks_command'
 require_relative 'cli/console_command'
+require_relative 'cli/doctor_command'
 
 module Belt
   module CLI
@@ -33,6 +34,7 @@ module Belt
       %w[console c] => Belt::CLI::ConsoleCommand,
       %w[tasks --tasks -T] => Belt::CLI::TasksCommand,
       'setup' => Belt::CLI::SetupCommand,
+      'doctor' => Belt::CLI::DoctorCommand,
       'deploy' => Belt::CLI::DeployCommand,
       'frontend' => Belt::CLI::FrontendEnvCommand,
       %w[server s] => Belt::CLI::ServerCommand,
@@ -114,6 +116,7 @@ module Belt
           setup state                                 Create/select S3 state bucket
           setup tables <env>                          Generate DynamoDB tables from schema
           setup frontend <env>                        Generate S3 + CloudFront infrastructure
+          doctor                                      Check system dependencies and AWS config
           init [environment] <env>                    terraform init for environment
           plan [environment] <env>                    terraform plan for environment
           apply [environment] <env>                   terraform apply for environment
@@ -133,6 +136,7 @@ module Belt
 
         Examples:
           belt new blog --frontend react
+          belt new blog --frontend react -v   # list every created file
           belt generate scaffold post title:string content:text status:string
           belt destroy scaffold post
           belt generate frontend react

data/lib/belt/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Belt
+  # Runtime configuration for Belt apps (set in lambda/config/environment.rb).
+  #
+  #   Belt.configure do |config|
+  #     config.default_format = :json  # or :html
+  #   end
+  #
+  # Note: infrastructure/<env>/belt.rb uses a separate sandboxed DSL for CLI
+  # deploy/backup settings — it does not share this object.
+  class Configuration
+    VALID_FORMATS = %i[json html].freeze
+
+    def initialize
+      @default_format = :json
+    end
+
+    attr_reader :default_format
+
+    def default_format=(value)
+      format = value.to_sym
+      unless VALID_FORMATS.include?(format)
+        raise ArgumentError, "default_format must be :json or :html (got #{value.inspect})"
+      end
+
+      @default_format = format
+    end
+  end
+end

data/lib/belt/controllers/welcome_controller.rb

@@ -6,23 +6,90 @@ module Belt
   # Gem-embedded welcome controller that serves the default "it works!" page.
   # Resolved via the ActionRouter's Belt:: namespace fallback when no app-defined
   # WelcomeController exists. Gets replaced once the user defines their own root route.
+  #
+  # Dual format:
+  #   - Browser / no Accept preference → HTML hero + stack check
+  #   - Accept: application/json (SPA / apiClient) → JSON payload for the React shell
+  #
+  # The hero image (lib/belt/assets/belt-default.jpg) is the single source of truth —
+  # HTML embeds it, and JSON returns the same bytes as a data URI so the SPA matches.
   class WelcomeController < BeltController::Base
     skip_before_action :authenticate!
 
     ASSETS_DIR = File.expand_path('../assets', __dir__)
+    # Scaffold gives model + controller + routes + schema (not model-only).
+    SCAFFOLD_HINT_CMD = 'belt generate scaffold Post title content:text'
 
     def show
       @title = ENV.fetch('WELCOME_TITLE', 'Welcome to Belt')
       @subtitle = ENV.fetch('WELCOME_SUBTITLE', 'API Gateway → Lambda → DynamoDB — all connected.')
-      @css = welcome_css
-      @background_image = background_image_base64
       @dynamodb_connected = dynamodb_connected?
+      @scaffold_hint_cmd = SCAFFOLD_HINT_CMD
+
+      return success_response(welcome_payload) if wants_json?
 
+      @css = welcome_css
+      @background_image = background_image_base64
       render
     end
 
     private
 
+    def welcome_payload
+      {
+        title: @title,
+        subtitle: @subtitle,
+        # Same gem asset as the HTML welcome page — edit belt-default.jpg once.
+        background_image: "data:image/jpeg;base64,#{background_image_base64}",
+        stack: {
+          api_gateway: true,
+          lambda: true,
+          dynamodb: @dynamodb_connected
+        },
+        # One tip only (was duplicated as dynamodb_hint + first next_step).
+        next_steps: [
+          "Scaffold a resource: #{SCAFFOLD_HINT_CMD}",
+          'Deploy: belt deploy',
+          'This page will be replaced once you define your own root route.'
+        ]
+      }
+    end
+
+    # SPA apiClient and fetch(..., { headers: { Accept: "application/json" } })
+    def wants_json?
+      return true if params['format'].to_s == 'json'
+
+      accept = header_value('Accept') || header_value('accept') || ''
+      return false if accept.empty?
+
+      # Prefer JSON when it's listed and not beaten by an explicit HTML preference
+      json_q = accept_quality(accept, 'application/json')
+      html_q = accept_quality(accept, 'text/html')
+      json_q.positive? && json_q >= html_q
+    end
+
+    def header_value(name)
+      headers = event.is_a?(Hash) ? event['headers'] : nil
+      return nil unless headers.is_a?(Hash)
+
+      headers[name] || headers[name.downcase] || headers[name.split('-').map(&:capitalize).join('-')]
+    end
+
+    def accept_quality(accept, media_type)
+      accept.split(',').each do |part|
+        type, *params = part.strip.split(';').map(&:strip)
+        # Exact type only — do not treat */* as JSON (curl/browsers send that by default)
+        next unless type == media_type
+
+        q = 1.0
+        params.each do |p|
+          q = p.split('=', 2).last.to_f if p.start_with?('q=')
+        end
+        return q
+      end
+      0.0
+    end
+
     def dynamodb_connected?
       return false unless defined?(Aws::DynamoDB::Client)