sxn 0.2.0

data/lib/sxn/rules.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "rules/errors"
+require_relative "rules/base_rule"
+require_relative "rules/copy_files_rule"
+require_relative "rules/setup_commands_rule"
+require_relative "rules/template_rule"
+require_relative "rules/rules_engine"
+require_relative "rules/project_detector"
+
+module Sxn
+  # The Rules module provides a comprehensive system for automating project setup
+  # through configurable rules. It includes secure file copying, command execution,
+  # template processing, and intelligent project detection.
+  #
+  # @example Basic usage
+  #   engine = Rules::RulesEngine.new("/path/to/project", "/path/to/session")
+  #   detector = Rules::ProjectDetector.new("/path/to/project")
+  #
+  #   # Detect project characteristics and suggest rules
+  #   suggested_rules = detector.suggest_default_rules
+  #
+  #   # Apply rules to set up the session
+  #   result = engine.apply_rules(suggested_rules)
+  #
+  #   if result.success?
+  #     puts "Applied #{result.applied_rules.size} rules successfully"
+  #   else
+  #     puts "Failed to apply rules: #{result.errors}"
+  #     engine.rollback_rules
+  #   end
+  #
+  module Rules
+    # Get all available rule types
+    #
+    # @return [Array<String>] Available rule type names
+    def self.available_types
+      RulesEngine::RULE_TYPES.keys
+    end
+
+    # Create a rule instance from configuration
+    #
+    # @param name [String] Rule name
+    # @param type [String] Rule type
+    # @param config [Hash] Rule configuration
+    # @param project_path [String] Project root path
+    # @param session_path [String] Session directory path
+    # @param dependencies [Array<String>] Rule dependencies
+    # @return [BaseRule] Rule instance
+    # @raise [ArgumentError] if rule type is invalid
+    def self.create_rule(name, type, config, project_path, session_path, dependencies: [])
+      # Convert symbol to string for consistent lookup
+      type_key = type.to_s
+      rule_class = RulesEngine::RULE_TYPES[type_key]
+      raise ArgumentError, "Invalid rule type: #{type}" unless rule_class
+
+      # Create rule instance - rule classes all follow BaseRule constructor pattern
+      case type_key
+      when "copy_files"
+        CopyFilesRule.new(name, config, project_path, session_path, dependencies: dependencies)
+      when "setup_commands"
+        SetupCommandsRule.new(name, config, project_path, session_path, dependencies: dependencies)
+      when "template"
+        TemplateRule.new(name, config, project_path, session_path, dependencies: dependencies)
+      else
+        raise ArgumentError, "Invalid rule type: #{type}"
+      end
+    end
+
+    # Validate a rules configuration hash
+    #
+    # @param rules_config [Hash] Rules configuration
+    # @param project_path [String] Project root path
+    # @param session_path [String] Session directory path
+    # @return [Boolean] true if valid
+    # @raise [ValidationError] if configuration is invalid
+    def self.validate_configuration(rules_config, project_path, session_path)
+      engine = RulesEngine.new(project_path, session_path)
+      engine.validate_rules_config(rules_config)
+      true
+    end
+
+    # Get rule type information
+    #
+    # @return [Hash] Rule type information including descriptions and supported options
+    def self.rule_type_info
+      {
+        "copy_files" => {
+          description: "Securely copy or symlink files with permission control and optional encryption",
+          config_schema: {
+            "files" => {
+              type: "array",
+              required: true,
+              description: "List of files to copy",
+              items: {
+                "source" => { type: "string", required: true, description: "Source file path" },
+                "destination" => { type: "string", required: false,
+                                   description: "Destination path (defaults to source)" },
+                "strategy" => { type: "string", required: false, enum: %w[copy symlink], default: "copy" },
+                "permissions" => { type: "string", required: false, description: "File permissions (e.g., '0600')" },
+                "encrypt" => { type: "boolean", required: false, default: false },
+                "required" => { type: "boolean", required: false, default: true }
+              }
+            }
+          }
+        },
+        "setup_commands" => {
+          description: "Execute project setup commands securely with environment control",
+          config_schema: {
+            "commands" => {
+              type: "array",
+              required: true,
+              description: "List of commands to execute",
+              items: {
+                "command" => { type: "array", required: true, description: "Command and arguments" },
+                "env" => { type: "object", required: false, description: "Environment variables" },
+                "timeout" => { type: "integer", required: false, default: 60, maximum: 1800 },
+                "condition" => { type: "string", required: false, description: "Execution condition" },
+                "working_directory" => { type: "string", required: false, description: "Working directory" },
+                "description" => { type: "string", required: false, description: "Command description" },
+                "required" => { type: "boolean", required: false, default: true }
+              }
+            },
+            "continue_on_failure" => { type: "boolean", required: false, default: false }
+          }
+        },
+        "template" => {
+          description: "Process and apply template files with variable substitution",
+          config_schema: {
+            "templates" => {
+              type: "array",
+              required: true,
+              description: "List of templates to process",
+              items: {
+                "source" => { type: "string", required: true, description: "Template file path" },
+                "destination" => { type: "string", required: true, description: "Output file path" },
+                "variables" => { type: "object", required: false, description: "Additional template variables" },
+                "engine" => { type: "string", required: false, enum: ["liquid"], default: "liquid" },
+                "required" => { type: "boolean", required: false, default: true },
+                "overwrite" => { type: "boolean", required: false, default: false }
+              }
+            }
+          }
+        }
+      }
+    end
+  end
+end

data/lib/sxn/runtime_validations.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Sxn
+  # Runtime validation helpers for Thor commands and type safety
+  module RuntimeValidations
+    class << self
+      # Validate Thor command arguments at runtime
+      def validate_thor_arguments(command_name, args, options, validations)
+        # Validate argument count
+        if validations[:args]
+          count_range = validations[:args][:count]
+          raise ArgumentError, "#{command_name} expects #{count_range} arguments, got #{args.size}" if count_range && !count_range.include?(args.size)
+
+          # Validate argument types
+          if validations[:args][:types]
+            args.each_with_index do |arg, index|
+              expected_types = Array(validations[:args][:types][index] || validations[:args][:types].last)
+              unless expected_types.any? { |type| arg.is_a?(type) }
+                raise TypeError, "#{command_name} argument #{index + 1} must be #{expected_types.join(" or ")}"
+              end
+            end
+          end
+        end
+
+        # Validate options
+        if validations[:options]
+          options.each do |key, value|
+            validate_option_type(command_name, key, value, validations[:options][key.to_sym]) if validations[:options][key.to_sym]
+          end
+        end
+
+        true
+      end
+
+      # Validate and coerce types for runtime safety
+      def validate_and_coerce_type(value, target_type, context = nil)
+        case target_type.name
+        when "String"
+          value.to_s
+        when "Integer"
+          Integer(value)
+        when "Float"
+          Float(value)
+        when "TrueClass", "FalseClass", "Boolean"
+          !!value
+        when "Array"
+          Array(value)
+        when "Hash"
+          value.is_a?(Hash) ? value : {}
+        else
+          value
+        end
+      rescue StandardError => e
+        raise TypeError, "Cannot coerce #{value.class} to #{target_type} in #{context}: #{e.message}"
+      end
+
+      # Validate template variables for Liquid templates
+      def validate_template_variables(variables)
+        return {} unless variables.is_a?(Hash)
+
+        # Ensure all required variable categories exist
+        validated = {
+          session: variables[:session] || {},
+          project: variables[:project] || {},
+          git: variables[:git] || {},
+          user: variables[:user] || {},
+          environment: variables[:environment] || {},
+          timestamp: variables[:timestamp] || {},
+          custom: variables[:custom] || {}
+        }
+
+        # Ensure no nil values in the hash
+        validated.each do |key, value|
+          validated[key] = {} unless value.is_a?(Hash)
+        end
+
+        validated
+      end
+
+      private
+
+      def validate_option_type(command_name, key, value, expected_type)
+        case expected_type
+        when :boolean
+          raise TypeError, "#{command_name} option --#{key} must be boolean" unless [true, false, nil].include?(value)
+        when :string
+          raise TypeError, "#{command_name} option --#{key} must be a string" unless value.nil? || value.is_a?(String)
+        when :integer
+          raise TypeError, "#{command_name} option --#{key} must be an integer" unless value.nil? || value.is_a?(Integer)
+        when :array
+          raise TypeError, "#{command_name} option --#{key} must be an array" unless value.nil? || value.is_a?(Array)
+        end
+      end
+    end
+  end
+end

data/lib/sxn/security/secure_command_executor.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require "English"
+require "open3"
+require "ostruct"
+require "timeout"
+require "json"
+
+module Sxn
+  module Security
+    # SecureCommandExecutor provides secure command execution with strict controls.
+    # It prevents shell interpolation by using Process.spawn with arrays,
+    # whitelists allowed commands, cleans environment variables, and logs all executions.
+    #
+    # @example
+    #   executor = SecureCommandExecutor.new("/path/to/project")
+    #   result = executor.execute(["bundle", "install"], env: {"RAILS_ENV" => "development"})
+    #   puts result.success? # => true/false
+    #   puts result.stdout   # => command output
+    #
+    class SecureCommandExecutor
+      # Command execution result
+      class CommandResult
+        attr_reader :exit_status, :stdout, :stderr, :command, :duration
+
+        def initialize(exit_status, stdout, stderr, command, duration)
+          @exit_status = exit_status
+          @stdout = stdout || ""
+          @stderr = stderr || ""
+          @command = command
+          @duration = duration
+        end
+
+        def success?
+          @exit_status.zero?
+        end
+
+        def failure?
+          !success?
+        end
+
+        def to_h
+          {
+            exit_status: @exit_status,
+            stdout: @stdout,
+            stderr: @stderr,
+            command: @command,
+            duration: @duration,
+            success: success?
+          }
+        end
+      end
+
+      # Whitelist of allowed commands with their expected paths
+      # Commands are mapped to either:
+      # - String: exact path to executable
+      # - Array: list of possible paths (first existing one is used)
+      # - Symbol: special handling required
+      ALLOWED_COMMANDS = {
+        # Ruby/Rails commands
+        "bundle" => %w[bundle /usr/local/bin/bundle /opt/homebrew/bin/bundle],
+        "gem" => %w[gem /usr/local/bin/gem /opt/homebrew/bin/gem],
+        "ruby" => %w[ruby /usr/local/bin/ruby /opt/homebrew/bin/ruby],
+        "rails" => :rails_command, # Special handling for bin/rails vs rails
+
+        # Node.js commands
+        "npm" => %w[npm /usr/local/bin/npm /opt/homebrew/bin/npm],
+        "yarn" => %w[yarn /usr/local/bin/yarn /opt/homebrew/bin/yarn],
+        "pnpm" => %w[pnpm /usr/local/bin/pnpm /opt/homebrew/bin/pnpm],
+        "node" => %w[node /usr/local/bin/node /opt/homebrew/bin/node],
+
+        # Git commands
+        "git" => %w[git /usr/bin/git /usr/local/bin/git /opt/homebrew/bin/git],
+
+        # Database commands
+        "psql" => %w[psql /usr/local/bin/psql /opt/homebrew/bin/psql],
+        "mysql" => %w[mysql /usr/local/bin/mysql /opt/homebrew/bin/mysql],
+        "sqlite3" => %w[sqlite3 /usr/bin/sqlite3 /usr/local/bin/sqlite3],
+
+        # Development tools
+        "make" => %w[make /usr/bin/make],
+        "curl" => %w[curl /usr/bin/curl /usr/local/bin/curl],
+        "wget" => %w[wget /usr/bin/wget /usr/local/bin/wget],
+
+        # Project-specific executables (resolved relative to project)
+        "bin/rails" => :project_executable,
+        "bin/setup" => :project_executable,
+        "bin/dev" => :project_executable,
+        "bin/test" => :project_executable,
+        "./bin/rails" => :project_executable,
+        "./bin/setup" => :project_executable
+      }.freeze
+
+      # Environment variables that are safe to preserve
+      SAFE_ENV_VARS = %w[
+        PATH
+        HOME
+        USER
+        LANG
+        LC_ALL
+        TZ
+        TMPDIR
+        RAILS_ENV
+        NODE_ENV
+        BUNDLE_GEMFILE
+        GEM_HOME
+        GEM_PATH
+        RBENV_VERSION
+        NVM_DIR
+        NVM_BIN
+        SSL_CERT_FILE
+        SSL_CERT_DIR
+      ].freeze
+
+      # Maximum command execution timeout (in seconds)
+      MAX_TIMEOUT = 300 # 5 minutes
+
+      # @param project_root [String] The absolute path to the project root directory
+      # @param logger [Logger] Optional logger for audit trail
+      def initialize(project_root, logger: nil)
+        @project_root = File.realpath(project_root)
+        @logger = logger || Sxn.logger
+        @command_whitelist = build_command_whitelist
+      rescue Errno::ENOENT
+        raise ArgumentError, "Project root does not exist: #{project_root}"
+      end
+
+      # Executes a command securely with strict controls
+      #
+      # @param command [Array<String>] Command and arguments as an array
+      # @param env [Hash] Environment variables to set
+      # @param timeout [Integer] Maximum execution time in seconds
+      # @param chdir [String] Directory to run command in (must be within project)
+      # @return [CommandResult] The execution result
+      # @raise [CommandExecutionError] if command is not allowed or execution fails
+      def execute(command, env: {}, timeout: 30, chdir: nil)
+        raise ArgumentError, "Command must be an array" unless command.is_a?(Array)
+        raise ArgumentError, "Command cannot be empty" if command.empty?
+        raise ArgumentError, "Timeout must be positive" unless timeout.positive? && timeout <= MAX_TIMEOUT
+
+        validated_command = validate_and_resolve_command(command)
+        safe_env = build_safe_environment(env)
+        work_dir = chdir ? validate_work_directory(chdir) : @project_root
+
+        start_time = Time.now
+        audit_log("EXEC_START", validated_command, work_dir, safe_env.keys)
+
+        begin
+          result = execute_with_timeout(validated_command, safe_env, work_dir, timeout)
+          duration = Time.now - start_time
+
+          audit_log("EXEC_COMPLETE", validated_command, work_dir, {
+                      exit_status: result.exit_status,
+                      duration: duration,
+                      success: result.success?
+                    })
+
+          CommandResult.new(result.exit_status, result.stdout, result.stderr, validated_command, duration)
+        rescue StandardError => e
+          duration = Time.now - start_time
+          audit_log("EXEC_ERROR", validated_command, work_dir, {
+                      error: e.class.name,
+                      message: e.message,
+                      duration: duration
+                    })
+          raise CommandExecutionError, "Command execution failed: #{e.message}"
+        end
+      end
+
+      # Checks if a command is allowed without executing it
+      #
+      # @param command [Array<String>] Command and arguments as an array
+      # @return [Boolean] true if the command is whitelisted
+      def command_allowed?(command)
+        return false unless command.is_a?(Array) && !command.empty?
+
+        begin
+          validate_and_resolve_command(command)
+          true
+        rescue CommandExecutionError
+          false
+        end
+      end
+
+      # Returns the list of allowed commands
+      #
+      # @return [Array<String>] List of allowed command names
+      def allowed_commands
+        @command_whitelist.keys.sort
+      end
+
+      private
+
+      # Validates that a command is whitelisted and resolves its path
+      def validate_and_resolve_command(command)
+        command_name = command.first
+
+        raise CommandExecutionError, "Command not whitelisted: #{command_name}" unless @command_whitelist.key?(command_name)
+
+        executable_path = @command_whitelist[command_name]
+
+        # Validate that the executable exists and is executable
+        unless File.exist?(executable_path) && File.executable?(executable_path)
+          raise CommandExecutionError, "Command executable not found or not executable: #{executable_path}"
+        end
+
+        # Return command with resolved executable path
+        [executable_path] + command[1..]
+      end
+
+      # Builds the command whitelist by resolving paths
+      def build_command_whitelist
+        whitelist = {}
+
+        ALLOWED_COMMANDS.each do |cmd_name, path_spec|
+          resolved_path = case path_spec
+                          when String
+                            path_spec if File.exist?(path_spec) && File.executable?(path_spec)
+                          when Array
+                            path_spec.find { |path| File.exist?(path) && File.executable?(path) }
+                          when :rails_command
+                            resolve_rails_command
+                          when :project_executable
+                            resolve_project_executable(cmd_name)
+                          end
+
+          whitelist[cmd_name] = resolved_path if resolved_path
+        end
+
+        whitelist
+      end
+
+      # Special handling for Rails command (bin/rails vs global rails)
+      def resolve_rails_command
+        bin_rails = File.join(@project_root, "bin", "rails")
+        return bin_rails if File.exist?(bin_rails) && File.executable?(bin_rails)
+
+        # Fall back to global rails command
+        %w[rails /usr/local/bin/rails /opt/homebrew/bin/rails].find do |path|
+          File.exist?(path) && File.executable?(path)
+        end
+      end
+
+      # Resolves project-specific executables
+      def resolve_project_executable(cmd_name)
+        # Remove leading ./ if present
+        clean_cmd = cmd_name.sub(%r{\A\./}, "")
+        executable_path = File.join(@project_root, clean_cmd)
+
+        return executable_path if File.exist?(executable_path) && File.executable?(executable_path)
+
+        nil
+      end
+
+      # Builds a safe environment by filtering and cleaning variables
+      def build_safe_environment(user_env)
+        safe_env = {}
+
+        # Start with safe environment variables from current environment
+        SAFE_ENV_VARS.each do |var|
+          safe_env[var] = ENV[var] if ENV.key?(var)
+        end
+
+        # Add user-provided environment variables (with validation)
+        user_env.each do |key, value|
+          key_str = key.to_s
+          value_str = value.to_s
+
+          # Validate environment variable names (only alphanumeric and underscore)
+          raise CommandExecutionError, "Invalid environment variable name: #{key_str}" unless key_str.match?(/\A[A-Z_][A-Z0-9_]*\z/)
+
+          # Validate environment variable values (no null bytes)
+          raise CommandExecutionError, "Environment variable contains null bytes: #{key_str}" if value_str.include?("\x00")
+
+          safe_env[key_str] = value_str
+        end
+
+        safe_env
+      end
+
+      # Validates the working directory
+      def validate_work_directory(chdir)
+        path_validator = SecurePathValidator.new(@project_root)
+        validated_path = path_validator.validate_path(chdir)
+
+        raise CommandExecutionError, "Working directory does not exist: #{chdir}" unless File.directory?(validated_path)
+
+        validated_path
+      end
+
+      # Executes command with timeout and captures output
+      def execute_with_timeout(command, env, chdir, timeout)
+        stdout_r, stdout_w = IO.pipe
+        stderr_r, stderr_w = IO.pipe
+
+        begin
+          pid = Process.spawn(
+            env,
+            *command,
+            chdir: chdir,
+            out: stdout_w,
+            err: stderr_w,
+            unsetenv_others: true, # Clear all other environment variables
+            close_others: true     # Close other file descriptors
+          )
+
+          stdout_w.close
+          stderr_w.close
+
+          # Wait for process with timeout
+          begin
+            Timeout.timeout(timeout) do
+              Process.wait(pid)
+            end
+          rescue Timeout::Error
+            Process.kill("TERM", pid)
+            sleep(1)
+            begin
+              Process.kill("KILL", pid)
+            rescue StandardError
+              nil
+            end
+            begin
+              Process.wait(pid)
+            rescue StandardError
+              nil
+            end
+            raise CommandExecutionError, "Command timed out after #{timeout} seconds"
+          end
+
+          exit_status = $CHILD_STATUS.exitstatus
+          stdout = stdout_r.read
+          stderr = stderr_r.read
+
+          OpenStruct.new(exit_status: exit_status, stdout: stdout, stderr: stderr)
+        ensure
+          [stdout_r, stdout_w, stderr_r, stderr_w].each do |io|
+            io.close
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      # Logs command execution for audit trail
+      def audit_log(event, command, chdir, details = {})
+        return unless @logger
+
+        # Ensure details is a hash
+        details = {} unless details.is_a?(Hash)
+
+        log_entry = {
+          timestamp: Time.now.iso8601,
+          event: event,
+          command: command.is_a?(Array) ? command.first : command.to_s, # Only log the executable, not full command for security
+          chdir: chdir,
+          pid: Process.pid
+        }.merge(details)
+
+        @logger.info("SECURITY_AUDIT: #{log_entry.to_json}")
+      end
+    end
+  end
+end