@dewtech/dare-cli 2.17.0 → 3.1.0

package/templates/stacks/ruby-rails-8/app/llm/prompts/prompt_loader.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — PromptLoader
+# Loads .txt or .jinja2 prompt templates from app/llm/prompts/
+# Performs simple variable interpolation
+#
+# Usage:
+#   prompt = LLM::Prompts::PromptLoader.load("summarize", "v1", text: "Long document text...")
+#   response = LLMProvider.instance.complete(model: "gpt-4o", prompt: prompt)
+
+module LLM
+  module Prompts
+    class PromptLoader
+      PROMPTS_DIR = Rails.root.join("app", "llm", "prompts")
+
+      # Load a prompt template and interpolate variables.
+      #
+      # @param name     [String] template name (e.g. "summarize")
+      # @param version  [String] version suffix (e.g. "v1")
+      # @param vars     [Hash]   variables to interpolate into the template
+      # @return [String] rendered prompt
+      def self.load(name, version = "v1", **vars)
+        template = find_template!(name, version)
+        interpolate(template, vars)
+      end
+
+      private_class_method def self.find_template!(name, version)
+        # Search order: .jinja2 first, then .txt, then .erb
+        candidates = [
+          PROMPTS_DIR.join("#{name}_#{version}.jinja2"),
+          PROMPTS_DIR.join("#{name}_#{version}.txt"),
+          PROMPTS_DIR.join("#{name}.jinja2"),
+          PROMPTS_DIR.join("#{name}.txt"),
+        ]
+
+        path = candidates.find(&:exist?)
+        raise ArgumentError, "Prompt template not found: #{name}/#{version}. Searched:\n#{candidates.map(&:to_s).join("\n")}" unless path
+
+        path.read
+      end
+
+      # Simple variable interpolation: {{ variable_name }} syntax (Jinja2-compatible)
+      # Also supports <%= variable_name %> (ERB) and {{variable_name}} without spaces
+      private_class_method def self.interpolate(template, vars)
+        result = template.dup
+        vars.each do |key, value|
+          result.gsub!(/\{\{\s*#{Regexp.escape(key.to_s)}\s*\}\}/, value.to_s)
+          result.gsub!(/<%=\s*#{Regexp.escape(key.to_s)}\s*%>/, value.to_s)
+        end
+        result
+      end
+    end
+  end
+end

package/templates/stacks/ruby-rails-8/app/llm/prompts/summarize_v1.jinja2

@@ -0,0 +1,12 @@
+You are a professional document summarizer. Summarize the following text concisely.
+
+Rules:
+- Be factual and objective
+- Keep the summary under 150 words
+- Preserve the main ideas and key facts
+- Use plain language
+
+Text to summarize:
+{{ text }}
+
+Summary:

package/templates/stacks/ruby-rails-8/app/llm/providers/dummy_provider.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — DummyProvider for testing and development
+# Returns deterministic canned responses — no network calls
+
+module LLM
+  module Providers
+    class DummyProvider < LLMProvider
+      DEFAULT_RESPONSE = "This is a dummy LLM response. Configure a real provider in config/dare.yml."
+
+      def initialize(responses: {})
+        # Allow injecting specific responses by prompt keyword for tests:
+        # DummyProvider.new(responses: { "summarize" => "Summary here" })
+        @responses = responses
+      end
+
+      def complete(model:, prompt:, max_tokens: 1024, temperature: 0.7, **_opts)
+        matched_key = @responses.keys.find { |k| prompt.to_s.downcase.include?(k.to_s.downcase) }
+        @responses.fetch(matched_key, DEFAULT_RESPONSE)
+      end
+
+      def chat(model:, messages:, max_tokens: 1024, temperature: 0.7, **_opts)
+        last_content = messages.last&.dig(:content) || messages.last&.dig("content") || ""
+        complete(model: model, prompt: last_content, max_tokens: max_tokens)
+      end
+
+      def stream(model:, prompt:, max_tokens: 1024, &block)
+        response = complete(model: model, prompt: prompt, max_tokens: max_tokens)
+        response.chars.each_slice(10).map(&:join).each do |chunk|
+          block.call(chunk)
+        end
+      end
+    end
+  end
+end

package/templates/stacks/ruby-rails-8/app/llm/providers/llm_provider.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — LLMProvider interface
+# Convention (ADR-04): all LLM calls go through this interface
+# Implementations: OpenaiProvider, DummyProvider, LocalLlamaProvider
+#
+# Usage:
+#   LLMProvider.instance.complete(model: "gpt-4o", prompt: "Summarize...", max_tokens: 150)
+
+module LLM
+  module Providers
+    class LLMProvider
+      include Singleton
+
+      # ── Factory: configure at boot from dare.yml ─────────────────────────
+
+      # Override the singleton instance (useful in tests to inject DummyProvider)
+      def self.configure(provider_instance)
+        @configured_instance = provider_instance
+      end
+
+      def self.instance
+        @configured_instance ||= build_from_config
+      end
+
+      def self.build_from_config
+        provider_name = Rails.configuration.dare.llm_provider
+
+        case provider_name
+        when "openai"
+          LLM::Providers::OpenaiProvider.new
+        when "dummy"
+          LLM::Providers::DummyProvider.new
+        else
+          raise ArgumentError, "Unknown LLM provider: #{provider_name}. Valid: openai, dummy"
+        end
+      end
+
+      # ── Interface — subclasses must implement ─────────────────────────────
+
+      # Complete a prompt and return the response text.
+      #
+      # @param model      [String]  e.g. "gpt-4o"
+      # @param prompt     [String]  the full prompt text
+      # @param max_tokens [Integer] maximum tokens in response
+      # @param temperature [Float]  0.0 to 1.0
+      # @return [String] the completion text
+      def complete(model:, prompt:, max_tokens: 1024, temperature: 0.7, **_opts)
+        raise NotImplementedError, "#{self.class} must implement #complete"
+      end
+
+      # Chat-style completion with messages array
+      #
+      # @param model    [String]
+      # @param messages [Array<Hash>] [{role: "user", content: "..."}]
+      # @return [String] assistant message content
+      def chat(model:, messages:, max_tokens: 1024, temperature: 0.7, **_opts)
+        raise NotImplementedError, "#{self.class} must implement #chat"
+      end
+
+      # Stream a completion — yields chunks as they arrive.
+      def stream(model:, prompt:, max_tokens: 1024, &block)
+        raise NotImplementedError, "#{self.class} must implement #stream"
+      end
+    end
+  end
+end

package/templates/stacks/ruby-rails-8/app/llm/providers/openai_provider.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — OpenAI LLM provider
+# Uses Faraday for HTTP — no heavy SDK dependency
+
+module LLM
+  module Providers
+    class OpenaiProvider < LLMProvider
+      BASE_URL = "https://api.openai.com/v1"
+
+      def initialize(api_key: nil)
+        @api_key = api_key || Rails.configuration.dare.llm_api_key
+        raise ArgumentError, "OpenAI API key not configured. Set OPENAI_API_KEY." if @api_key.blank?
+      end
+
+      def complete(model:, prompt:, max_tokens: 1024, temperature: 0.7, **_opts)
+        messages = [{ role: "user", content: prompt }]
+        chat(model: model, messages: messages, max_tokens: max_tokens, temperature: temperature)
+      end
+
+      def chat(model:, messages:, max_tokens: 1024, temperature: 0.7, **_opts)
+        response = connection.post("/v1/chat/completions") do |req|
+          req.headers["Authorization"] = "Bearer #{@api_key}"
+          req.headers["Content-Type"]  = "application/json"
+          req.body = {
+            model:       model,
+            messages:    messages,
+            max_tokens:  max_tokens,
+            temperature: temperature
+          }.to_json
+        end
+
+        handle_response(response)
+          .dig("choices", 0, "message", "content")
+          .to_s
+          .strip
+      end
+
+      def stream(model:, prompt:, max_tokens: 1024, &block)
+        # Streaming via SSE — basic implementation
+        # For production use consider openai-ruby gem with native streaming
+        raise NotImplementedError, "Streaming not yet implemented in OpenaiProvider. Use chat() instead."
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: BASE_URL) do |f|
+          f.request  :retry, max: 2, interval: 0.5, retry_statuses: [429, 503]
+          f.response :raise_error
+          f.adapter  Faraday.default_adapter
+        end
+      end
+
+      def handle_response(response)
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise "OpenAI returned non-JSON response: #{response.body.truncate(200)}"
+      end
+    end
+  end
+end

package/templates/stacks/ruby-rails-8/app/llm/rate_limit/token_bucket.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — Token Bucket rate limiter for LLM API calls
+# Prevents exceeding OpenAI/provider rate limits (tokens per minute)
+# Uses Redis for distributed state across multiple app instances
+#
+# Usage:
+#   bucket = LLM::RateLimit::TokenBucket.new(user_id: current_user.id)
+#   unless bucket.consume!(tokens: estimated_tokens)
+#     raise RateLimitExceeded, "LLM token limit reached. Retry after #{bucket.retry_after}s"
+#   end
+
+module LLM
+  module RateLimit
+    class TokenBucket
+      class RateLimitExceeded < StandardError
+        attr_reader :retry_after
+
+        def initialize(retry_after: 60)
+          @retry_after = retry_after
+          super("LLM token rate limit exceeded. Retry after #{retry_after} seconds.")
+        end
+      end
+
+      # Default: 100K tokens per minute per user (well below OpenAI limits)
+      DEFAULT_CAPACITY   = 100_000
+      DEFAULT_REFILL_RPM = 100_000  # tokens refilled per minute
+      WINDOW_SECONDS     = 60
+
+      def initialize(user_id:, capacity: DEFAULT_CAPACITY)
+        @user_id  = user_id
+        @capacity = capacity
+        @redis    = Redis.new(url: Rails.configuration.dare.redis_url)
+      end
+
+      # Attempt to consume tokens. Returns true if allowed, false if rate-limited.
+      def consume!(tokens: 1)
+        key       = redis_key
+        now       = Time.now.to_f
+        window_start = now - WINDOW_SECONDS
+
+        # Redis pipeline: count tokens used in current window + add new entry
+        used = @redis.multi do |pipeline|
+          pipeline.zremrangebyscore(key, "-inf", window_start)
+          pipeline.zadd(key, now, "#{now}:#{tokens}")
+          pipeline.zrange(key, 0, -1)
+          pipeline.expire(key, WINDOW_SECONDS * 2)
+        end
+
+        # Tally tokens from sorted set entries
+        entries = used[2] || []
+        total_used = entries.sum do |entry|
+          entry.split(":").last.to_i
+        end
+
+        if total_used > @capacity
+          # Roll back the zadd we just did
+          @redis.zrem(key, "#{now}:#{tokens}")
+          return false
+        end
+
+        true
+      end
+
+      def retry_after
+        # Time until oldest entry expires
+        oldest = @redis.zrange(redis_key, 0, 0, with_scores: true).first
+        return 0 unless oldest
+
+        oldest_time = oldest[1]
+        remaining = (oldest_time + WINDOW_SECONDS) - Time.now.to_f
+        [remaining.ceil, 0].max
+      end
+
+      private
+
+      def redis_key
+        "llm_token_bucket:#{@user_id}"
+      end
+    end
+  end
+end

package/templates/stacks/ruby-rails-8/app/llm/validators/summarize_output_schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SummarizeOutput",
+  "description": "Schema for LLM summarize operation output",
+  "type": "object",
+  "required": ["summary"],
+  "properties": {
+    "summary": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 2000,
+      "description": "The summarized text"
+    },
+    "word_count": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional word count of the summary"
+    }
+  },
+  "additionalProperties": false
+}

package/templates/stacks/ruby-rails-8/app/llm/validators/validator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — LLM Output Validator
+# Validates LLM responses against JSON Schema definitions
+# Schemas live in app/llm/validators/*.json
+#
+# Usage:
+#   LLM::Validators::Validator.validate!("summarize_output", response_hash)
+
+module LLM
+  module Validators
+    class Validator
+      SCHEMAS_DIR = Rails.root.join("app", "llm", "validators")
+
+      class ValidationError < StandardError
+        attr_reader :errors
+
+        def initialize(schema_name, errors)
+          @errors = errors
+          super("LLM output failed validation for '#{schema_name}': #{errors.map { |e| e[:error] }.join(", ")}")
+        end
+      end
+
+      # Validate a hash against a named JSON Schema.
+      # Raises ValidationError if invalid.
+      def self.validate!(schema_name, data)
+        schema = load_schema!(schema_name)
+        validator = JSONSchemer.schema(schema)
+        errors = validator.validate(data).to_a
+
+        raise ValidationError.new(schema_name, errors) if errors.any?
+
+        true
+      end
+
+      # Returns true/false without raising
+      def self.valid?(schema_name, data)
+        validate!(schema_name, data)
+        true
+      rescue ValidationError
+        false
+      end
+
+      private_class_method def self.load_schema!(name)
+        path = SCHEMAS_DIR.join("#{name}.json")
+        raise ArgumentError, "Schema not found: #{name}.json in #{SCHEMAS_DIR}" unless path.exist?
+
+        JSON.parse(path.read)
+      end
+    end
+  end
+end

package/templates/stacks/ruby-rails-8/app/models/user.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — User domain model
+# Convention (ADR-05): models are lean data objects — no callbacks, no fat model
+# Business logic lives in app/services/; data access in app/repositories/
+
+class User < ApplicationRecord
+  # ── Validations ─────────────────────────────────────────────────────────
+  validates :email, presence: true,
+                    uniqueness: { case_sensitive: false },
+                    format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :name,  presence: true, length: { minimum: 2, maximum: 100 }
+
+  # ── Scopes ───────────────────────────────────────────────────────────────
+  scope :active, -> { where(active: true) }
+
+  # ── DARE: NO callbacks, NO fat model logic ───────────────────────────────
+  # Use Services for: password hashing, welcome emails, event publishing, etc.
+  # Use Repositories for: queries, bulk updates, custom SQL
+  #
+  # WRONG (fat model):
+  #   before_create :send_welcome_email
+  #   after_save    :publish_event
+  #
+  # RIGHT (service):
+  #   Services::CreateUserService.new(...).execute(params)
+
+  # ── Simple domain helpers (pure data concerns only) ──────────────────────
+  def display_name
+    name.presence || email.split("@").first
+  end
+
+  def can_view?(user_id)
+    id == user_id.to_i || admin?
+  end
+end

package/templates/stacks/ruby-rails-8/app/presenters/user_presenter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — UserPresenter
+# Convention (ADR-05): serialization concern isolated from model and controller
+# Returns plain Hash; handler renders JSON from it
+
+class UserPresenter
+  def initialize(user)
+    @user = user
+  end
+
+  # Full representation — used in show/create responses
+  def as_json(*)
+    {
+      id:         @user.id,
+      email:      @user.email,
+      name:       @user.name,
+      active:     @user.active?,
+      created_at: @user.created_at&.iso8601,
+      updated_at: @user.updated_at&.iso8601,
+    }
+  end
+
+  def to_json(*)
+    as_json.to_json
+  end
+
+  # Collection representation — used in index responses
+  # Wraps an array of presenters into a standard envelope
+  def self.collection(users, meta: {})
+    {
+      data: users.map { |u| new(u).as_json },
+      meta: {
+        count: users.size,
+        **meta
+      }
+    }
+  end
+
+  # Minimal summary representation (e.g. for nested resources)
+  def summary
+    {
+      id:    @user.id,
+      email: @user.email,
+      name:  @user.name
+    }
+  end
+end

package/templates/stacks/ruby-rails-8/app/repositories/document_repository.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — DocumentRepository (interface + ActiveRecord implementation)
+# Convention (ADR-05): data access is isolated here — services never call AR directly
+# This enables easy mocking in unit tests and future DB swaps
+
+module Repositories
+  class DocumentRepository
+    # ── Query ──────────────────────────────────────────────────────────────
+
+    def find(id)
+      Document.find_by(id: id)
+    end
+
+    def find!(id)
+      Document.find(id)
+    rescue ActiveRecord::RecordNotFound
+      raise ActiveRecord::RecordNotFound, "Document with id=#{id} was not found."
+    end
+
+    def all
+      Document.order(created_at: :desc)
+    end
+
+    def by_user(user_id)
+      Document.where(user_id: user_id).order(created_at: :desc)
+    end
+
+    # ── Persistence ────────────────────────────────────────────────────────
+
+    # Builds a new Document (not persisted).
+    def build(attrs = {})
+      Document.new(attrs)
+    end
+
+    # Persist (create or update). Raises ActiveRecord::RecordInvalid on failure.
+    def save!(document)
+      document.save!
+      document
+    end
+
+    # Update summary and timestamp after LLM processing.
+    def update_summary!(document, summary)
+      document.update!(summary: summary, summarized_at: Time.current)
+      document
+    end
+
+    def update!(document, attributes)
+      document.update!(attributes)
+      document
+    end
+
+    def destroy!(document)
+      document.destroy!
+    end
+  end
+end

package/templates/stacks/ruby-rails-8/app/repositories/user_repository.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — UserRepository
+# Convention (ADR-05): data access is isolated here — services never call AR directly
+# This enables easy mocking in unit tests and future DB swaps
+
+module Repositories
+  class UserRepository
+    # ── Query ──────────────────────────────────────────────────────────────
+
+    def find(id)
+      User.find_by(id: id)
+    end
+
+    def find!(id)
+      User.find(id)
+    rescue ActiveRecord::RecordNotFound
+      raise ActiveRecord::RecordNotFound, "User with id=#{id} was not found."
+    end
+
+    def find_by_email(email)
+      User.find_by(email: email.downcase.strip)
+    end
+
+    def all_active
+      User.active.order(created_at: :desc)
+    end
+
+    def paginated(page: 1, per: 25)
+      User.active
+          .order(created_at: :desc)
+          .offset((page.to_i - 1) * per.to_i)
+          .limit(per.to_i)
+    end
+
+    def count
+      User.count
+    end
+
+    # ── Persistence ────────────────────────────────────────────────────────
+
+    # Builds a new User (not persisted). Let the service validate input first.
+    def build(attributes = {})
+      User.new(attributes)
+    end
+
+    # Persist (create or update). Raises ActiveRecord::RecordInvalid on failure.
+    def save!(user)
+      user.save!
+      user
+    end
+
+    # Persist without raising. Returns false on failure.
+    def save(user)
+      user.save
+    end
+
+    def update!(user, attributes)
+      user.update!(attributes)
+      user
+    end
+
+    def destroy!(user)
+      user.destroy!
+    end
+
+    # ── Bulk ───────────────────────────────────────────────────────────────
+
+    def deactivate_all_inactive(since:)
+      User.where("last_active_at < ?", since).update_all(active: false)
+    end
+  end
+end

package/templates/stacks/ruby-rails-8/app/services/create_user_service.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — CreateUserService
+# Convention (ADR-01): one service per operation; injected dependencies for testability
+#
+# Usage:
+#   result = Services::CreateUserService.new(
+#     user_repository: Repositories::UserRepository.new,
+#     event_publisher: RealtimeService.instance
+#   ).execute(email: "user@example.com", name: "Alice")
+#
+# Returns: User (persisted)
+# Raises:  Services::CreateUserService::EmailTakenError
+#          ActiveRecord::RecordInvalid (validation failure)
+
+module Services
+  class CreateUserService
+    # ── Domain errors ──────────────────────────────────────────────────────
+    class EmailTakenError < StandardError
+      def initialize(email)
+        super("Email '#{email}' is already registered.")
+      end
+    end
+
+    # ── Constructor ────────────────────────────────────────────────────────
+    def initialize(user_repository:, event_publisher:)
+      @user_repository = user_repository
+      @event_publisher = event_publisher
+    end
+
+    # ── Main operation ─────────────────────────────────────────────────────
+    def execute(email:, name:, password: nil, **extra_attrs)
+      email = email.to_s.downcase.strip
+
+      # Guard: check for duplicate email
+      if @user_repository.find_by_email(email)
+        raise EmailTakenError, email
+      end
+
+      # Build and persist
+      user = @user_repository.build(
+        email:      email,
+        name:       name.to_s.strip,
+        active:     true,
+        **extra_attrs
+      )
+
+      # Hash password if provided (example using has_secure_password)
+      user.password = password if password.present?
+
+      @user_repository.save!(user)
+
+      # Publish real-time event
+      @event_publisher.publish(
+        type: "user.created",
+        data: {
+          user_id: user.id,
+          email:   user.email,
+          name:    user.name,
+          timestamp: Time.now.to_i
+        }
+      )
+
+      user
+    end
+  end
+end