@dewtech/dare-cli 3.0.0 → 3.1.0

package/templates/stacks/ruby-rails-8/app/controllers/application_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — ApplicationController
+# - CSRF protection active (RS-01)
+# - RFC 7807 Problem Details included (D-006)
+# - Thin controller: HTTP concerns only, delegates to Services
+
+class ApplicationController < ActionController::API
+  include ProblemDetails
+
+  # Enforce JSON responses for all API endpoints
+  before_action :set_default_response_format
+
+  private
+
+  def set_default_response_format
+    request.format = :json
+  end
+
+  # Override in specific controllers if authentication is needed
+  def current_user
+    @current_user ||= authenticate_user_from_token
+  end
+
+  def authenticate_user_from_token
+    token = request.headers["Authorization"]&.sub(/\ABearer /, "")
+    return nil unless token
+
+    # TODO: implement your token strategy here (JWT, session, etc.)
+    # User.find_by_token(token)
+    nil
+  end
+
+  def require_authentication!
+    return if current_user
+
+    render_problem(
+      status: :unauthorized,
+      title:  "Unauthorized",
+      detail: "You must be authenticated to access this resource.",
+      type:   "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401"
+    )
+  end
+end

package/templates/stacks/ruby-rails-8/app/controllers/concerns/problem_details.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — RFC 7807 Problem Details concern
+# Decision: D-006 — all HTTP errors use this format
+#
+# Usage: include ProblemDetails in ApplicationController
+#
+# Format:
+#   {
+#     "type":     "https://example.com/problems/not-found",
+#     "title":    "Resource Not Found",
+#     "status":   404,
+#     "detail":   "User with id=42 was not found.",
+#     "instance": "/api/users/42"
+#   }
+
+module ProblemDetails
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from StandardError,                    with: :render_internal_error
+    rescue_from ActiveRecord::RecordNotFound,     with: :render_not_found
+    rescue_from ActiveRecord::RecordInvalid,      with: :render_unprocessable_entity
+    rescue_from ActionController::ParameterMissing, with: :render_bad_request
+    rescue_from ArgumentError,                    with: :render_bad_request
+  end
+
+  # ── Public helpers ──────────────────────────────────────────────────────────
+
+  # Render a Problem Details response manually.
+  #
+  #   render_problem(status: :not_found, title: "User Not Found", detail: "...")
+  def render_problem(status:, title:, detail: nil, type: nil, **extra)
+    http_status = Rack::Utils.status_code(status)
+
+    body = {
+      type:     type || default_type_uri(http_status),
+      title:    title,
+      status:   http_status,
+      detail:   detail,
+      instance: request.path,
+    }.merge(extra).compact
+
+    render json: body,
+           status: http_status,
+           content_type: "application/problem+json"
+  end
+
+  private
+
+  def render_not_found(exception)
+    render_problem(
+      status: :not_found,
+      title:  "Not Found",
+      detail: exception.message.presence || "The requested resource does not exist."
+    )
+  end
+
+  def render_unprocessable_entity(exception)
+    errors = exception.record&.errors&.full_messages || [exception.message]
+    render_problem(
+      status:  :unprocessable_entity,
+      title:   "Validation Failed",
+      detail:  "One or more fields failed validation.",
+      errors:  errors
+    )
+  end
+
+  def render_bad_request(exception)
+    render_problem(
+      status: :bad_request,
+      title:  "Bad Request",
+      detail: exception.message
+    )
+  end
+
+  def render_internal_error(exception)
+    # Never leak internals in production
+    detail = Rails.env.production? ? "An unexpected error occurred." : exception.message
+
+    Rails.logger.error "[ProblemDetails] #{exception.class}: #{exception.message}\n#{exception.backtrace&.first(10)&.join("\n")}"
+
+    render_problem(
+      status: :internal_server_error,
+      title:  "Internal Server Error",
+      detail: detail
+    )
+  end
+
+  def default_type_uri(status_code)
+    "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/#{status_code}"
+  end
+end

package/templates/stacks/ruby-rails-8/app/handlers/summarize_handler.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — SummarizeHandler (thin controller, delegates to service)
+# Convention (ADR-01): HTTP concerns only — params, response codes, delegation
+# No business logic here.
+#
+# POST /api/v1/documents/:id/summarize
+# RFC 7807 errors via ProblemDetails concern (D-006)
+
+class SummarizeHandler < ApplicationController
+  include ProblemDetails
+
+  before_action :authenticate_user!  # assume Devise or similar
+
+  # POST /api/v1/documents/:id/summarize
+  def create
+    result = Services::SummarizeDocumentService.new(
+      document_repository: Repositories::DocumentRepository.new,
+      llm_provider:        LLM::Providers::LLMProvider.instance,
+      event_publisher:     RealtimeService.instance
+    ).execute(
+      document_id: params[:id],
+      user_id:     current_user.id
+    )
+
+    render json: { summary: result.summary, document_id: result.document_id }, status: :ok
+
+  rescue Services::SummarizeDocumentService::DocumentNotFoundError => e
+    render_problem(status: 404, title: "Not Found", detail: e.message)
+  rescue Services::SummarizeDocumentService::SummarizationError => e
+    render_problem(status: 422, title: "Summarization Failed", detail: e.message)
+  end
+end

package/templates/stacks/ruby-rails-8/app/handlers/users_handler.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — UsersHandler (thin controller)
+# Convention (ADR-01): HTTP concerns only — params, response codes, delegation
+# No business logic, no repository calls, no queries here.
+
+class UsersHandler < ApplicationController
+  before_action :require_authentication!, only: %i[update destroy]
+
+  # GET /api/users
+  def index
+    repo  = Repositories::UserRepository.new
+    users = repo.all_active
+
+    render json: UserPresenter.collection(users), status: :ok
+  end
+
+  # GET /api/users/:id
+  def show
+    repo = Repositories::UserRepository.new
+    user = repo.find!(params[:id])
+
+    render json: UserPresenter.new(user).as_json, status: :ok
+  end
+
+  # POST /api/users
+  def create
+    input = params.require(:user).permit(:email, :name, :password)
+
+    user = Services::CreateUserService.new(
+      user_repository: Repositories::UserRepository.new,
+      event_publisher: RealtimeService.instance
+    ).execute(
+      email:    input[:email],
+      name:     input[:name],
+      password: input[:password]
+    )
+
+    render json: UserPresenter.new(user).as_json, status: :created
+
+  rescue Services::CreateUserService::EmailTakenError => e
+    render_problem(
+      status: :conflict,
+      title:  "Email Already Taken",
+      detail: e.message
+    )
+  end
+
+  # PATCH /api/users/:id
+  def update
+    repo  = Repositories::UserRepository.new
+    user  = repo.find!(params[:id])
+    input = params.require(:user).permit(:name)
+
+    repo.update!(user, input.to_h)
+
+    render json: UserPresenter.new(user).as_json, status: :ok
+  end
+
+  # DELETE /api/users/:id
+  def destroy
+    repo = Repositories::UserRepository.new
+    user = repo.find!(params[:id])
+    repo.destroy!(user)
+
+    head :no_content
+  end
+end

package/templates/stacks/ruby-rails-8/app/llm/cache/llm_cache.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# DARE v3.0 — LLM Cache (Redis wrapper)
+# Caches LLM responses to reduce API costs and latency
+# Uses SHA256 of (model + prompt) as cache key
+#
+# Usage:
+#   result = LLM::Cache::LlmCache.instance.fetch(model: "gpt-4o", prompt: prompt) do
+#     LLMProvider.instance.complete(model: "gpt-4o", prompt: prompt)
+#   end
+
+module LLM
+  module Cache
+    class LlmCache
+      include Singleton
+
+      DEFAULT_TTL = 24.hours
+
+      def fetch(model:, prompt:, ttl: DEFAULT_TTL, &block)
+        key = cache_key(model, prompt)
+
+        Rails.cache.fetch(key, expires_in: ttl, &block)
+      end
+
+      def invalidate(model:, prompt:)
+        key = cache_key(model, prompt)
+        Rails.cache.delete(key)
+      end
+
+      def clear_all!
+        # WARNING: clears entire Rails cache — use only in test/dev
+        raise "clear_all! not allowed in production!" if Rails.env.production?
+        Rails.cache.clear
+      end
+
+      private
+
+      def cache_key(model, prompt)
+        hash = Digest::SHA256.hexdigest("#{model}:#{prompt}")
+        "llm_cache:#{hash}"
+      end
+    end
+  end
+end

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