spec_forge 0.7.1 → 1.0.0

data/lib/spec_forge/cli/new.rb

@@ -3,70 +3,121 @@
 module SpecForge
   class CLI
     #
-    # Command for generating new specs or factories
+    # Command for generating new blueprints or factories from templates
     #
-    # @example Creating a new spec
-    #   spec_forge new spec users
+    # Creates workflow blueprints or test data factories with sensible defaults
+    # and realistic examples to get you started quickly.
+    #
+    # @example Creating a new blueprint
+    #   spec_forge new blueprint users
     #
     # @example Creating a new factory
     #   spec_forge new factory user
     #
     class New < Command
       command_name "new"
-      summary "Create new test specs or data factories"
+      summary "Create new workflow blueprints or data factories"
 
       description <<~DESC
-        Generate new files from templates.
+        Generate new files from templates with realistic examples.
 
         Types:
-          • spec - Creates YAML test files with common patterns
-          • factory - Creates FactoryBot factories for test data
-
-        Files are created in the appropriate spec_forge/ subdirectory.
+          • blueprint - Creates workflow files with complete CRUD examples
+          • factory   - Creates FactoryBot factories for test data
+
+        Blueprints include examples of:
+          • Variable storage and interpolation
+          • Sequential request workflows
+          • Multiple HTTP methods (GET, POST, PATCH, DELETE)
+          • Different expectation patterns
+          • Response value chaining
+
+        Files are created in the appropriate spec_forge/ subdirectory
+        with proper naming conventions and ready-to-run examples.
       DESC
 
       syntax "new <type> <name>"
 
-      example "new spec users",
-        "Creates a new spec located at 'spec_forge/specs/users.yml'"
+      example "new blueprint users",
+        "Creates spec_forge/blueprints/users.yml with CRUD examples"
 
-      example "new factory user",
-        "Creates a new factory located at 'spec_forge/factories/user.yml'"
+      example "new blueprint auth/login",
+        "Creates spec_forge/blueprints/auth/login.yml in subdirectory"
 
-      example "generate spec accounts",
-        "Uses the generate alias (shorthand 'g') instead of 'new'"
+      example "new factory user",
+        "Creates spec_forge/factories/user.yml"
 
-      aliases :generate, :g
+      aliases :generate, :g, :n
 
       #
-      # Creates a new spec or factory file in the corresponding directory using templates
+      # Creates a new blueprint or factory file from templates
+      #
+      # @return [void]
       #
       def call
-        type = arguments.first.downcase
+        type = arguments.first&.downcase
         name = arguments.second
 
-        # Cleanup
-        name.delete_suffix!(".yml") if name.end_with?(".yml")
-        name.delete_suffix!(".yaml") if name.end_with?(".yaml")
+        if type.nil? || name.nil?
+          puts "Error: Both type and name are required."
+          puts "Usage: spec_forge new <type> <name>"
+          puts ""
+          puts "Examples:"
+          puts "  spec_forge new blueprint users"
+          puts "  spec_forge new factory user"
+          exit(1)
+        end
+
+        # Clean up the name
+        name = normalize_name(name)
 
         case type
-        when "spec"
-          create_new_spec(name)
-        when "factory"
+        when "blueprint", "blueprints", "spec", "specs"
+          create_new_blueprint(name)
+        when "factory", "factories"
           create_new_factory(name)
+        else
+          puts "Error: Unknown type '#{type}'"
+          puts "Valid types: blueprint, factory"
+          exit(1)
         end
       end
 
       private
 
-      def create_new_spec(name)
+      #
+      # Normalizes the name by removing extensions
+      #
+      # @param name [String] The raw name from user input
+      #
+      # @return [String] Cleaned name without extensions
+      #
+      def normalize_name(name)
+        name.delete_suffix(".yml").delete_suffix(".yaml")
+      end
+
+      #
+      # Creates a new blueprint file with workflow template
+      #
+      # @param name [String] The blueprint name
+      #
+      # @return [void]
+      #
+      def create_new_blueprint(name)
         actions.template(
-          "new_spec.yml.tt",
-          SpecForge.forge_path.join("specs", "#{name}.yml"),
+          "new_blueprint.yml.tt",
+          SpecForge.forge_path.join("blueprints", "#{name}.yml"),
           context: Proxy.new(name).call
         )
       end
 
+      #
+      # Creates a new factory file with template
+      #
+      # @param name [String] The factory name
+      #
+      # @return [void]
+      #
       def create_new_factory(name)
         actions.template(
           "new_factory.yml.tt",

data/lib/spec_forge/cli/run.rb

@@ -3,92 +3,124 @@
 module SpecForge
   class CLI
     #
-    # Command for running SpecForge tests with filtering options
+    # Command for running SpecForge blueprints with filtering and output options
     #
-    # @example Running all specs
-    #   spec_forge run
+    # Executes workflow blueprints with support for file filtering, tag-based
+    # selection, and configurable verbosity levels for output detail.
     #
-    # @example Running specific file
-    #   spec_forge run users
+    # @example Running all blueprints
+    #   spec_forge run
     #
-    # @example Running specific spec
-    #   spec_forge run users:create_user
+    # @example Running specific blueprint
+    #   spec_forge run users_workflow
     #
-    # @example Running specific expectation
-    #   spec_forge run users:create_user:"POST /users"
+    # @example Running with tags
+    #   spec_forge run --tags smoke
     #
     class Run < Command
       command_name "run"
-      syntax "run [target]"
-
-      summary "Execute your API tests with smart filtering options"
+      syntax "run [path] [options]"
+      summary "Execute workflow blueprints with optional filtering"
 
       description <<~DESC
-        Execute API tests with filtering options.
+        Execute SpecForge workflow blueprints with flexible filtering options.
+
+        Supports:
+          • File/directory targeting for selective execution
+          • Tag-based filtering to run specific test categories
+          • Multiple verbosity levels for output detail
+          • Tag exclusion to skip certain tests
+
+        Verbosity Levels:
+          (default)  - Minimal output, dots for progress
+          --verbose  - Show all steps with detailed results
+          --debug    - Add full request/response for failures
+          --trace    - Show everything for all steps
+      DESC
 
-        Target formats:
-          • file_name - Run all specs in a file
-          • file:spec - Run specific spec
-          • file:spec:"expectation" - Run individual expectation
+      example "run",
+        "Runs all blueprints in spec_forge/blueprints/"
 
-        Uses RSpec for execution with detailed error reporting.
-      DESC
+      example "run users_workflow",
+        "Runs only the users_workflow.yml blueprint"
+
+      example "run blueprints/integration/",
+        "Runs all blueprints in the integration directory"
 
-      example "spec_forge run",
-        "Run all specs in spec_forge/specs/"
+      example "run --tags smoke",
+        "Runs all blueprints tagged with 'smoke'"
 
-      example "spec_forge run users",
-        "Run all specs in users.yml"
+      example "run --tags smoke,auth --skip-tags slow",
+        "Runs smoke and auth tests, excluding slow ones"
 
-      example "spec_forge run users:create_user",
-        "Run all expectations in the create_user spec"
+      example "run users_workflow --tags smoke --debug",
+        "Runs users_workflow smoke tests with debug output"
 
-      example "spec_forge run users:create_user:\"POST /users\"",
-        "Run expectations matching POST /users"
+      option "--tags=TAGS", "Run only steps with these tags (comma-separated)"
+      option "--skip-tags=TAGS", "Skip steps with these tags (comma-separated)"
+      option "--verbose", "Show detailed step execution (verbosity level 1)"
+      option "--debug", "Show full request/response for failures (verbosity level 2)"
+      option "--trace", "Show everything for all steps (verbosity level 3)"
 
-      example "spec_forge run users:create_user:\"POST /users - Create Admin\"",
-        "Run the specific expectation named \"Create Admin\""
+      aliases :r
 
       #
-      # Loads and runs all specs, or a subset of specs based on the provided arguments
+      # Executes the workflow blueprints with specified filters and options
+      #
+      # @return [void]
       #
       def call
-        return SpecForge.run if arguments.blank?
+        base_path = determine_path
+        tags = parse_tags(options.tags)
+        skip_tags = parse_tags(options.skip_tags)
+        verbosity_level = determine_verbosity_level
+
+        blueprints, forge_hooks = Loader.load_blueprints(base_path:, tags:, skip_tags:)
 
-        # spec_forge users:show_user
-        filter = extract_filter(arguments.first)
+        if blueprints.empty?
+          puts "No blueprints found matching the criteria."
+          exit(0)
+        end
 
-        # Filter and run the specs
-        SpecForge.run(**filter)
+        Forge.ignite.run(blueprints, verbosity_level:, hooks: forge_hooks)
       end
 
       private
 
       #
-      # The input can be
+      # Determines the path to run from command arguments
       #
-      #   "<file_name>" for a file
-      #     Example: "users"
+      # @return [Pathname, nil] The path to execute, or nil for all blueprints
       #
-      #   "<file_name>:<spec_name>" for a single spec
-      #     Example: "users:show_user"
+      def determine_path
+        return nil if arguments.empty?
+
+        Pathname.new(arguments.first)
+      end
+
+      #
+      # Parses comma-separated tags from a string
       #
-      #   "<file_name:<spec_name>:'<verb> <path> - <?name>'" for a single expectation
-      #     Example:
-      #       "users:show_user:'GET /users/:id'"
-      #     Example with name:
-      #       "users:show_user:'GET /users/:id - Returns 404 due to missing user'"
+      # @param tag_string [String, nil] Comma-separated tag string
       #
-      # @private
+      # @return [Array<String>] Array of tag strings
       #
-      def extract_filter(input)
-        # Note: Only split 3 because the expectation name can have colons in them.
-        file_name, spec_name, expectation_name = input.split(":", 3).map(&:strip)
+      def parse_tags(tag_string)
+        return [] if tag_string.blank?
 
-        # Remove the quotes
-        expectation_name.gsub!(/^['"]|['"]$/, "") if expectation_name.present?
+        tag_string.split(",").map(&:strip).reject(&:blank?)
+      end
 
-        {file_name:, spec_name:, expectation_name:}
+      #
+      # Determines verbosity level from command options
+      #
+      # @return [Integer] Verbosity level (0-3)
+      #
+      def determine_verbosity_level
+        return 3 if options.trace
+        return 2 if options.debug
+        return 1 if options.verbose
+        0
       end
     end
   end

data/lib/spec_forge/cli/serve.rb

@@ -62,6 +62,11 @@ module SpecForge
       option "--ui=UI", "Documentation interface: swagger or redoc (default: swagger)"
       option "--port=PORT", "Port to serve documentation on (default: 8080)"
 
+      # Verbosity options
+      option "--verbose", "Show detailed step execution (verbosity level 1)"
+      option "--debug", "Show full request/response for failures (verbosity level 2)"
+      option "--trace", "Show everything for all steps (verbosity level 3)"
+
       aliases :s
 
       #

data/lib/spec_forge/cli.rb

@@ -1,13 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "cli/actions"
-require_relative "cli/command"
-require_relative "cli/docs"
-require_relative "cli/init"
-require_relative "cli/new"
-require_relative "cli/run"
-require_relative "cli/serve"
-
 module SpecForge
   #
   # Command-line interface for SpecForge that provides the overall command structure
@@ -31,14 +23,14 @@ module SpecForge
       program :name, "SpecForge"
       program :version, SpecForge::VERSION
       program :description, <<~DESC.strip
-        Write expressive API tests in YAML with the power of RSpec matchers.
+        Write API tests as sequential workflows in YAML with RSpec matchers.
 
         Quick Start:
-          spec_forge init              # Set up your project
-          spec_forge new spec users    # Create your first test
-          spec_forge run               # Execute tests
-          spec_forge docs              # Generate API docs
-          spec_forge serve             # Serve API docs locally
+          spec_forge init                    # Set up your project
+          spec_forge new blueprint users     # Create your first workflow
+          spec_forge run                     # Execute workflows
+          spec_forge docs                    # Generate OpenAPI docs
+          spec_forge serve                   # Preview docs locally
       DESC
 
       register_commands