belt 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d587a60fbaef9f5755a1746b766d5fdc6e6bf6efbc34ee58e3901b0324fbc199
-  data.tar.gz: ac3bca34eb3552cf18693605b4c42ba11d11ea1d5437d201b6db838443951c28
+  metadata.gz: 6527c1a9570ed74381b685347d178f0e20db869d39791c06b5685a45ba94c4dd
+  data.tar.gz: b60a0994c0646820e74eaf8d81918b4b52b95b570f9fc9ca3d74994b36bbfc6b
 SHA512:
-  metadata.gz: fdcd4a4c7efbce1ef89e394f86f3b3252307f4e4d1462ff8582bd0de6fb5ce9d3e7d34cceacc43dd3d50c3165ef1e7f01592b220dcddeb246d81c371fcb59281
-  data.tar.gz: 8ba38580f372f91d188aad8fc843435dc7f35ef90b7142027f9201317761f4de231d310ab58f5f5536400d6060925d425fcc8d208716381048f96bb6db15b574
+  metadata.gz: eb607dbfcc355a2b79dc82b3117f9e10937f32b9449cf6d3861685130f63271207d9b94992d1d86a5f49396acc0d7756f485b6c0db24d3aa70d738d95601fb6e
+  data.tar.gz: 1aa7b6eee506bc68947a8eaacc3cf773cb4929207831d21b9fac098bcf82de3a6062918faa0244bce389d4d5f680d4508f49a6e2c5a36dc843a82ad1d2164393

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.1.1
+
+### `belt routes` CLI command
+
+- Added `belt routes` — displays all routes defined in `infrastructure/routes.tf.rb`
+- Concise table output with VERB, PATH, CONTROLLER#ACTION (shows GATEWAY/LAMBDA columns when multiple namespaces exist)
+- JSON output via `--format json` includes routes array and optional schema models
+- Filter routes with `--grep PATTERN` (case-insensitive, matches verb, path, gateway, lambda, controller, or action)
+- Generate Ruby route manifest files with `--namespace NAMESPACE` (or `all` for every gateway/lambda)
+- `--output-dir DIR` controls where generated files are written (warns if used without `--namespace`)
+- Added `Belt.root` — project root detection by walking up to find `infrastructure/routes.tf.rb`, with fallback to `pwd`
+- Default output directory for generated routes: `#{Belt.root}/lambda/lib/routes`
+
+### `belt tasks` CLI command
+
+- Added `belt tasks` — lists available rake tasks from the project's Rakefile
+- Filter tasks with `--grep PATTERN`
+- Show all tasks (including undescribed) with `--all`
+- Run rake tasks directly: `belt lambda:build_layer` invokes `bundle exec rake lambda:build_layer`
+
+### Other changes
+
+- Added `Belt::RouteDSL` — full route DSL parser (resources, nested resources, scopes, mounts, schemas)
+- Added `Belt::TableInference` — infers DynamoDB table access from Terraform definitions
+- Renamed `TerraDispatch` references to `Belt` in templates and DSL entry points
+- Removed `activeitem` dependency from generated Gemfile template
+- Added Rakefile template to `belt new` scaffolding
+
 ## 0.0.7
 
 - Fixed `discover_gem_paths` to use `Gem.loaded_specs` instead of `Gem::Specification.each` — the latter silently returns nothing on Lambda's vendored bundle layout, causing gem controllers/models to not be found
@@ -26,4 +54,4 @@
 - Added `BeltController::Base` with callbacks, strong params, CORS, error handling
 - Added `ActionController::Parameters` (strong params without Rails)
 - Added response helpers and CORS origin resolution
-- Bundled dependencies: activeitem, lambda_loadout, s3arch
+- Bundled dependencies: activeitem, lambda_loadout

data/README.md

@@ -9,7 +9,6 @@ Belt bundles everything you need to go from zero to production:
 - **Belt::ActionRouter** — request routing to controllers from route manifests
 - **ActiveItem** — DynamoDB ORM (queries, validations, associations, transactions)
 - **Lambda Loadout** — structured logging, CloudWatch metrics (EMF), error alerting
-- **S3arch** — full-text search via SQLite FTS5, stored on S3, queried from Lambda
 
 ## Installation
 
@@ -35,6 +34,8 @@ my-app/
 │   ├── routes.tf.rb        # Belt provider route definitions
 │   └── schema.tf.rb        # DynamoDB table schemas
 ├── lambda/
+│   ├── config/
+│   │   └── environment.rb  # App boot file (used by console + Lambda)
 │   ├── controllers/
 │   │   └── posts_controller.rb
 │   ├── models/
@@ -42,6 +43,7 @@ my-app/
 │   ├── lib/
 │   │   └── routes.rb
 │   └── api.rb              # Lambda entry point
+├── .irbrc                  # Console customization (optional)
 ├── Gemfile
 └── Gemfile.lock
 ```
@@ -129,7 +131,7 @@ terraform {
 Define routes in `infrastructure/routes.tf.rb`:
 
 ```ruby
-TerraDispatch.routes.draw do
+Belt.application.routes.draw do
   namespace :api do
     resources :posts, only: [:index, :show, :create]
   end
@@ -139,7 +141,7 @@ end
 Define tables in `infrastructure/schema.tf.rb`:
 
 ```ruby
-TerraDispatch.schema.define do
+Belt.application.schema.define do
   model :post do
     partition_key :id, :string
     global_secondary_index :UserIndex, partition_key: :user_id
@@ -201,80 +203,196 @@ error_response("Not found", 404)                        # 404 JSON error
 html_response("<h1>Hello</h1>")                         # 200 HTML with CORS
 ```
 
-## Holsters (Belt's Engines)
+## Controller Discovery
 
-Holsters are Belt's equivalent of Rails Engines. A holster lets a gem provide its own controllers, models, routes, and schema — all discovered automatically via convention.
+Belt discovers controllers from the app's namespace module first, then searches `Belt.all_controller_paths` — which includes app-defined paths. No registration needed.
 
-### Creating a Holster
+## Belt::Observability
 
-In your gem, subclass `Belt::Holster`:
+Belt provides global `Belt::Observability::Logger` and `Belt::Observability::Metrics` facades that are set automatically by `Belt::LambdaHandler`. Access them from anywhere:
 
 ```ruby
-# lib/s3arch/holster.rb
-module S3arch
-  class Holster < Belt::Holster
-  end
-end
+Belt::Observability::Logger.info("Something happened", user_id: "123")
+Belt::Observability::Metrics.track_event("OrderCreated", model: "Order")
 ```
 
-That's it. Belt discovers all `Holster` subclasses at boot. By convention, it expects:
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `ENVIRONMENT` | Controls verbose error responses (`dev*`, `local`, `test`) |
+| `BELT_METRICS_NAMESPACE` | CloudWatch metrics namespace (default: `Belt`) |
+| `ACTION` | Service name for logging (falls back to function name) |
+| `ERROR_NOTIFICATION_TOPIC_ARN` | SNS topic for error alerts |
+| `CORS_ALLOWED_ORIGINS` | Comma-separated origins (overrides domain vars) |
+| `CUSTOMER_APP_DOMAIN` | Primary app domain for CORS |
+| `OPS_APP_DOMAIN` | Internal tools domain for CORS |
+
+## CLI
 
+Belt includes a command-line interface for project management.
+
+### `belt console` (alias: `belt c`)
+
+Start an interactive Ruby console with your app loaded. Belt uses convention over configuration:
+
+1. Loads `lambda/config/environment.rb` (your app's boot file — AWS setup, models, libs)
+2. Starts IRB with `reload!` available
+3. Reads `.irbrc` from the project root (console-specific customization)
+
+```bash
+belt console           # uses BELT_ENV or defaults to 'dev'
+belt c prod            # specify environment explicitly
+belt c dev02 --run "Customer.first"  # runner mode (execute and exit)
 ```
-your-gem/
-├── infrastructure/
-│   ├── routes.tf.rb      # Holster's route definitions
-│   └── schema.tf.rb      # Holster's DynamoDB tables
-└── lambda/
-    ├── controllers/      # Holster's controllers
-    └── models/           # Holster's models
+
+A production safety prompt is shown when the environment is `prod`.
+
+### `belt routes`
+
+Display route definitions from your `infrastructure/routes.tf.rb`. This is the primary way to inspect what endpoints your app exposes.
+
+```bash
+belt routes
 ```
 
-No configuration needed if you follow the convention. Belt resolves paths relative to your gem's root (two directories up from the holster file).
+Output (single namespace):
 
-### Customizing Paths
+```
+VERB    PATH                   CONTROLLER#ACTION
+------------------------------------------------------------------
+GET     /posts                 posts#index
+GET     /posts/{post_id}       posts#show
+POST    /posts                 posts#create
+DELETE  /posts/{post_id}       posts#destroy
+```
 
-If your gem uses a different layout, override any path:
+When multiple namespaces (API Gateways) exist, GATEWAY and LAMBDA columns are added automatically:
 
-```ruby
-module MyGem
-  class Holster < Belt::Holster
-    self.gem_root = File.expand_path("..", __dir__)
-    self.controllers_path = File.join(gem_root, "app", "controllers")
-  end
-end
+```
+VERB    PATH              GATEWAY  LAMBDA  CONTROLLER#ACTION
+---------------------------------------------------------------
+GET     /posts            blog     blog    posts#index
+POST    /posts            blog     blog    posts#create
+GET     /posts            ops      ops     posts#index
+POST    /posts            ops      ops     posts#create
 ```
 
-### How Belt Uses Holsters
+#### Options
 
-- **Controllers**: `Belt::ActionRouter` searches holster controller paths automatically
-- **Routes**: `Belt.all_routes_paths` collects all holster `routes.tf.rb` files for the Terraform provider
-- **Schema**: `Belt.all_schema_paths` collects all holster `schema.tf.rb` files for the Terraform provider
-- **Models**: `Belt.all_models_paths` collects all holster model directories
+| Flag | Description |
+|------|-------------|
+| `-g, --grep PATTERN` | Filter routes matching pattern (case-insensitive, matches verb, path, gateway, lambda, controller, or action) |
+| `-f, --format FORMAT` | Output format: `concise` (default) or `json` |
+| `--namespace NAMESPACE` | Generate Ruby route files for NAMESPACE (or "all") |
+| `--output-dir DIR` | Output directory for generated Ruby files (default: `lambda/lib/routes/`) |
+| `--schema FILE` | Path to `schema.tf.rb` for model definitions (default: same directory as routes file) |
+| `--tables-file FILE` | Path to Terraform file with `aws_dynamodb_table` resources for table inference |
+| `-h, --help` | Show help |
 
-## Controller Discovery
+#### Examples
 
-Belt discovers controllers from the app's namespace module first, then searches `Belt.all_controller_paths` — which includes both app-defined paths and holster-provided paths. No registration needed.
+```bash
+# Filter routes by pattern
+belt routes -g posts
 
-## Belt::Observability
+# JSON output (for tooling/CI)
+belt routes -f json
 
-Belt provides global `Belt::Observability::Logger` and `Belt::Observability::Metrics` facades that are set automatically by `Belt::LambdaHandler`. Access them from anywhere:
+# Generate Ruby route constant for the "api" namespace
+belt routes --namespace api
+
+# Generate to a custom directory
+belt routes --namespace api --output-dir lib/routes
+
+# Include schema models in JSON output
+belt routes -f json --schema infrastructure/schema.tf.rb
+
+# Infer DynamoDB table access from Terraform
+belt routes -f json --tables-file infrastructure/main.tf
+```
+
+#### JSON Output
+
+With `--format json`, the output includes a `routes` array and optionally a `models` array (when a schema file is found):
+
+```json
+{
+  "routes": [
+    {
+      "name": "posts",
+      "verb": "GET",
+      "path": "/posts",
+      "gateway": "api",
+      "lambda": "api",
+      "controller": "posts",
+      "action": "index",
+      "auth": "cognito",
+      "tables": ["posts"],
+      "request_model": "",
+      "response_model": ""
+    }
+  ],
+  "models": [
+    {
+      "name": "CreatePost",
+      "kind": "request",
+      "description": "Request model: CreatePost",
+      "properties": {
+        "title": { "type": "string" },
+        "body": { "type": "string" }
+      },
+      "required": ["title"]
+    }
+  ]
+}
+```
+
+#### Ruby Output
+
+With `--namespace NAMESPACE`, Belt generates a frozen Ruby constant file at `lambda/lib/routes/<namespace>_routes.rb`:
 
 ```ruby
-Belt::Observability::Logger.info("Something happened", user_id: "123")
-Belt::Observability::Metrics.track_event("OrderCreated", model: "Order")
+# frozen_string_literal: true
+
+# Auto-generated by: belt routes --namespace api
+# Do not edit manually
+
+module Routes
+  API = [
+    {
+      verb: "GET",
+      path: "/posts",
+      gateway: "api",
+      lambda: "api",
+      controller: "posts",
+      action: "index",
+      auth: "cognito",
+      tables: ["posts"]
+    }
+  ].freeze
+end
 ```
 
-## Environment Variables
+This is used by `Belt::ActionRouter` at runtime for request routing.
 
-| Variable | Purpose |
-|----------|---------|
-| `ENVIRONMENT` | Controls verbose error responses (`dev*`, `local`, `test`) |
-| `BELT_METRICS_NAMESPACE` | CloudWatch metrics namespace (default: `Belt`) |
-| `ACTION` | Service name for logging (falls back to function name) |
-| `ERROR_NOTIFICATION_TOPIC_ARN` | SNS topic for error alerts |
-| `CORS_ALLOWED_ORIGINS` | Comma-separated origins (overrides domain vars) |
-| `CUSTOMER_APP_DOMAIN` | Primary app domain for CORS |
-| `OPS_APP_DOMAIN` | Internal tools domain for CORS |
+#### Route File Location
+
+The command expects `infrastructure/routes.tf.rb` in the current working directory. Routes are defined using the same DSL as the Belt Terraform provider:
+
+```ruby
+Belt.application.routes.draw do
+  namespace :api do
+    resources :posts, only: [:index, :show, :create, :destroy]
+    resource :profile, only: [:show, :update]
+    get "health", action: :health
+  end
+end
+```
+
+#### Table Inference
+
+When `--tables-file` is provided, Belt parses `aws_dynamodb_table` resource blocks from your Terraform files and infers which tables each route accesses based on the resource name in the route path. Routes can also declare tables explicitly in the DSL via `tables: [:posts, :comments]`.
 
 ## License
 

data/lib/belt/cli/console_command.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Belt
+  module CLI
+    class ConsoleCommand
+      def self.run(args)
+        new(args).run
+      end
+
+      def initialize(args)
+        @args = args
+        @options = {}
+        parse_options
+      end
+
+      def run
+        ENV['BUNDLE_GEMFILE'] ||= File.join(Belt.root, 'Gemfile')
+
+        unless File.exist?(ENV['BUNDLE_GEMFILE'])
+          abort "Error: No Gemfile found at #{ENV['BUNDLE_GEMFILE']}. Are you in a Belt project?"
+        end
+
+        @environment = @args.first || ENV['BELT_ENV'] || 'dev'
+        ENV['ENVIRONMENT'] = @environment
+
+        if @options[:run]
+          exec_runner(@options[:run])
+        else
+          exec_console
+        end
+      end
+
+      private
+
+      def parse_options
+        OptionParser.new do |opts|
+          opts.banner = 'Usage: belt console [environment] [options]'
+          opts.on('--run COMMAND', 'Execute a command and exit') { |cmd| @options[:run] = cmd }
+          opts.on('-h', '--help', 'Show this help') do
+            puts opts
+            exit
+          end
+        end.parse!(@args)
+      end
+
+      def exec_console
+        production_guard!
+        boot_app
+        puts banner
+        ARGV.clear
+        require 'irb'
+        IRB.start
+      end
+
+      def exec_runner(command)
+        boot_app
+        result = eval(command) # rubocop:disable Security/Eval
+        puts format_result(result)
+      rescue StandardError => e
+        abort "Error: #{e.class}: #{e.message}\n#{e.backtrace.first(5).join("\n")}"
+      end
+
+      def boot_app
+        require 'bundler/setup'
+
+        environment_file = File.join(Belt.root, 'lambda', 'config', 'environment.rb')
+        if File.exist?(environment_file)
+          load environment_file
+        else
+          require 'belt'
+          load_dir('lib')
+          load_dir('models')
+        end
+
+        define_reload!
+      end
+
+      def load_dir(subdir)
+        dir = File.join(Belt.root, 'lambda', subdir)
+        Dir.glob(File.join(dir, '**', '*.rb')).each { |f| require f } if Dir.exist?(dir)
+      end
+
+      def define_reload!
+        root = Belt.root
+        Kernel.define_method(:reload!) do
+          %w[lib models].each do |subdir|
+            dir = File.join(root, 'lambda', subdir)
+            Dir.glob(File.join(dir, '**', '*.rb')).each { |f| load f } if Dir.exist?(dir)
+          end
+          puts '♻️  Reloaded'
+        end
+      end
+
+      def production_guard!
+        return unless @environment == 'prod'
+
+        $stdout.write "\n⚠️  WARNING: You are entering the PRODUCTION console!\nType 'yes' to continue: "
+        response = $stdin.gets&.chomp
+        abort "\n❌ Cancelled." unless response&.downcase == 'yes'
+        puts "\n✅ Entering production console...\n"
+      end
+
+      def banner
+        <<~BANNER
+
+          Belt Console (#{@environment})
+          Type 'reload!' to reload code.
+
+        BANNER
+      end
+
+      def format_result(result)
+        require 'json'
+        if result.respond_to?(:to_h)
+          JSON.pretty_generate(result.to_h)
+        elsif result.respond_to?(:map) && result.respond_to?(:first) && result.first.respond_to?(:to_h)
+          JSON.pretty_generate(result.map(&:to_h))
+        elsif result.nil?
+          'nil'
+        else
+          result.inspect
+        end
+      end
+    end
+  end
+end

data/lib/belt/cli/new_command.rb

@@ -71,6 +71,7 @@ module Belt
           #{@app_name}/lambda/models
           #{@app_name}/lambda/models/concerns
           #{@app_name}/lambda/lib/routes
+          #{@app_name}/lambda/config
           #{@app_name}/lambda/spec
           #{@app_name}/infrastructure
         ]
@@ -79,8 +80,9 @@ module Belt
       def files
         {
           'Gemfile.erb' => "#{@app_name}/Gemfile",
-          'lambda/Gemfile.erb' => "#{@app_name}/lambda/Gemfile",
+          'Rakefile.erb' => "#{@app_name}/Rakefile",
           'lambda/api.rb.erb' => "#{@app_name}/lambda/#{@app_name}.rb",
+          'lambda/config/environment.rb.erb' => "#{@app_name}/lambda/config/environment.rb",
           'lambda/models/application_record.rb.erb' => "#{@app_name}/lambda/models/application_record.rb",
           'lambda/models/concerns/timestampable.rb.erb' => "#{@app_name}/lambda/models/concerns/timestampable.rb",
           'lambda/controllers/application_controller.rb.erb' =>

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Belt
+  module CLI
+    class RoutesCommand
+      # Extracts route controller/action inference logic from RoutesCommand.
+      module RouteInference
+        private
+
+        def infer_controller(route, gateway)
+          return route.controller.to_s if route.controller
+
+          segments = route.path.split('/').reject(&:empty?)
+          non_param = segments.reject { |s| s.start_with?(':', '{') }
+          return gateway.name if non_param.empty?
+
+          return non_param.map { |s| s.gsub('-', '_') }.join('/') if route.resource? && nested_resource?(segments)
+
+          non_param.first.gsub('-', '_')
+        end
+
+        def infer_action(route, _gateway)
+          return route.action.to_s if route.action
+
+          segments = route.path.split('/').reject(&:empty?)
+          verb = route.method
+
+          if route.singular_resource?
+            infer_singular_resource_action(verb)
+          elsif route.plural_resource?
+            infer_plural_resource_action(verb, segments)
+          else
+            infer_plain_action(verb, segments)
+          end
+        end
+
+        def infer_singular_resource_action(verb)
+          case verb
+          when 'GET' then 'show'
+          when 'PUT', 'PATCH' then 'update'
+          when 'DELETE' then 'destroy'
+          when 'POST' then 'create'
+          else 'show'
+          end
+        end
+
+        def infer_plural_resource_action(verb, segments)
+          has_id = segments.any? { |s| s.start_with?(':', '{') }
+          last_is_param = segments.last&.start_with?(':', '{')
+
+          if nested_resource?(segments)
+            child_idx = segments.rindex { |s| !s.start_with?(':', '{') }
+            has_child_id = child_idx && segments[(child_idx + 1)..]&.any? { |s| s.start_with?(':', '{') }
+            restful_action(verb, has_child_id || false)
+          else
+            restful_action(verb, has_id && last_is_param)
+          end
+        end
+
+        def infer_plain_action(verb, segments)
+          non_param = segments.reject { |s| s.start_with?(':', '{') }
+          has_id = segments.any? { |s| s.start_with?(':', '{') }
+          last_is_param = segments.last&.start_with?(':', '{')
+
+          if non_param.length <= 1 && !has_id
+            non_param.first&.gsub('-', '_') || 'index'
+          elsif non_param.length > 1
+            non_param.last.gsub('-', '_')
+          else
+            restful_action(verb, has_id && last_is_param)
+          end
+        end
+
+        def nested_resource?(segments)
+          segments.length >= 3 &&
+            !segments[0].start_with?(':', '{') &&
+            segments[1]&.start_with?(':', '{') &&
+            !segments[2]&.start_with?(':', '{')
+        end
+
+        def restful_action(verb, is_member)
+          case [verb, is_member]
+          when ['GET', false] then 'index'
+          when ['GET', true] then 'show'
+          when ['POST', false] then 'create'
+          when ['PUT', true], ['PATCH', true] then 'update'
+          when ['DELETE', true] then 'destroy'
+          else 'index'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Belt
+  module CLI
+    class RoutesCommand
+      # Extracts schema model loading logic from RoutesCommand.
+      module SchemaLoader
+        private
+
+        def load_schema_models(routes_file)
+          schema_file = resolve_schema_file(routes_file)
+          return [] unless schema_file && File.exist?(schema_file)
+
+          Belt.instance_variable_set(:@application, nil)
+          begin
+            eval(File.read(schema_file), binding, schema_file) # rubocop:disable Security/Eval
+          rescue StandardError => e
+            warn "Warning: Failed to load schema file #{schema_file}: #{e.message}"
+            return []
+          end
+
+          schema = Belt.application.schema.to_h
+          build_models_from_schema(schema)
+        end
+
+        def resolve_schema_file(routes_file)
+          schema_file = @options[:schema_file]
+          unless schema_file
+            routes_dir = File.dirname(File.expand_path(routes_file))
+            schema_file = File.join(routes_dir, 'schema.tf.rb')
+          end
+          schema_file
+        end
+
+        def build_models_from_schema(schema)
+          models = []
+
+          (schema[:request_models] || {}).each_value do |model|
+            models << {
+              name: model[:name],
+              kind: 'request',
+              description: "Request model: #{model[:name]}",
+              properties: stringify_properties(model[:properties] || {}),
+              required: (model[:required] || []).map(&:to_s)
+            }
+          end
+
+          (schema[:response_models] || {}).each_value do |model|
+            (model[:contexts] || {}).each do |ctx_name, ctx|
+              models << {
+                name: "#{model[:name]}_#{ctx_name}_response",
+                kind: 'response',
+                description: "Response model: #{model[:name]} (#{ctx_name} context)",
+                properties: stringify_properties(ctx[:properties] || {}),
+                required: []
+              }
+            end
+          end
+
+          models
+        end
+
+        def stringify_properties(properties)
+          properties.each_with_object({}) do |(key, value), hash|
+            hash[key.to_s] = value.transform_keys(&:to_s)
+          end
+        end
+      end
+    end
+  end
+end