elder_docs 0.1.0

data/lib/elder_docs/assets/viewer/data.js

@@ -0,0 +1,2 @@
+window.ElderDocsData = {"openapi":{"openapi":"3.0.0","info":{"title":"Test API - ElderDocs Demo","version":"1.0.0","description":"A comprehensive test API showcasing various endpoints, methods, and payloads for ElderDocs demonstration"},"servers":[{"url":"https://jsonplaceholder.typicode.com","description":"Test server (JSONPlaceholder)"},{"url":"https://api.example.com","description":"Production server"}],"paths":{"/posts":{"get":{"summary":"Get all posts","description":"Retrieve a list of all blog posts with optional filtering and pagination","parameters":[{"name":"userId","in":"query","description":"Filter posts by user ID","required":false,"schema":{"type":"integer"}},{"name":"_limit","in":"query","description":"Limit the number of results","required":false,"schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}}}}},"post":{"summary":"Create a new post","description":"Create a new blog post with title, body, and user ID","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePostRequest"},"example":{"title":"My New Post","body":"This is the content of my new post","userId":1}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"400":{"description":"Bad request - invalid input"}}}},"/posts/{id}":{"get":{"summary":"Get post by ID","description":"Retrieve a specific post by its unique identifier","parameters":[{"name":"id","in":"path","required":true,"description":"Post ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"404":{"description":"Post not found"}}},"put":{"summary":"Update entire post","description":"Replace all fields of an existing post","parameters":[{"name":"id","in":"path","required":true,"description":"Post ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePostRequest"},"example":{"id":1,"title":"Updated Post Title","body":"Updated post content","userId":1}}}},"responses":{"200":{"description":"Post updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}}}},"patch":{"summary":"Partially update post","description":"Update only specified fields of a post","parameters":[{"name":"id","in":"path","required":true,"description":"Post ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"}}},"example":{"title":"Partially Updated Title"}}}},"responses":{"200":{"description":"Post partially updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}}}},"delete":{"summary":"Delete a post","description":"Permanently delete a post by ID","parameters":[{"name":"id","in":"path","required":true,"description":"Post ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Post deleted successfully"},"404":{"description":"Post not found"}}}},"/users":{"get":{"summary":"List all users","description":"Get a list of all registered users","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}}}}}},"/users/{id}":{"get":{"summary":"Get user by ID","description":"Retrieve detailed information about a specific user","parameters":[{"name":"id","in":"path","required":true,"description":"User ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"404":{"description":"User not found"}}}},"/comments":{"get":{"summary":"Get all comments","description":"Retrieve comments with optional filtering","parameters":[{"name":"postId","in":"query","description":"Filter comments by post ID","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"List of comments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}}}}}},"post":{"summary":"Create a comment","description":"Add a new comment to a post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommentRequest"},"example":{"postId":1,"name":"John Doe","email":"john@example.com","body":"This is a great post!"}}}},"responses":{"201":{"description":"Comment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}}}}}}},"components":{"schemas":{"Post":{"type":"object","properties":{"id":{"type":"integer","description":"Unique post identifier"},"title":{"type":"string","description":"Post title"},"body":{"type":"string","description":"Post content"},"userId":{"type":"integer","description":"ID of the user who created the post"}}},"CreatePostRequest":{"type":"object","required":["title","body","userId"],"properties":{"title":{"type":"string","description":"Post title","minLength":1,"maxLength":200},"body":{"type":"string","description":"Post content"},"userId":{"type":"integer","description":"User ID"}}},"UpdatePostRequest":{"type":"object","required":["id","title","body","userId"],"properties":{"id":{"type":"integer"},"title":{"type":"string"},"body":{"type":"string"},"userId":{"type":"integer"}}},"User":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"username":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"}}},"phone":{"type":"string"},"website":{"type":"string"}}},"Comment":{"type":"object","properties":{"id":{"type":"integer"},"postId":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"body":{"type":"string"}}},"CreateCommentRequest":{"type":"object","required":["postId","name","email","body"],"properties":{"postId":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"body":{"type":"string"}}}}}},"articles":[{"id":"getting_started","title":"🚀 Getting Started","markdown_content":"# Welcome to ElderDocs!\n\nThis is a **dead simple** API documentation platform.\n\n## Quick Start\n\n1. **Select an endpoint** from the sidebar\n2. **Fill in parameters** (if needed)\n3. **Click SEND REQUEST**\n4. **See the response** instantly\n\nThat's it! No complicated setup needed.\n\n## Features\n\n- ✅ **Interactive API Explorer** - Try endpoints right in your browser\n- ✅ **Multiple Auth Types** - Bearer tokens, API keys, Basic auth, OAuth2\n- ✅ **Beautiful Design** - Bright yellow and white with sharp corners\n- ✅ **Big Fonts** - Easy to read, easy to use\n- ✅ **Real-time Testing** - See responses immediately\n\n## Authentication\n\nChoose your authentication method from the dropdown:\n\n- **Bearer Token**: Standard OAuth2 bearer tokens\n- **API Key Header**: Custom API key headers\n- **Basic Auth**: Username:password format\n- **OAuth 2.0**: OAuth token support\n\nEnter your credentials once, and they'll be saved for all requests!"},{"id":"api_basics","title":"📖 API Basics","markdown_content":"## Understanding HTTP Methods\n\n### GET\n\nUse GET to **retrieve** data. It's safe and doesn't modify anything.\n\n```bash\nGET /posts\n```\n\n### POST\n\nUse POST to **create** new resources.\n\n```bash\nPOST /posts\nContent-Type: application/json\n\n{\n  \"title\": \"My Post\",\n  \"body\": \"Content here\",\n  \"userId\": 1\n}\n```\n\n### PUT\n\nUse PUT to **replace** an entire resource.\n\n```bash\nPUT /posts/1\n```\n\n### PATCH\n\nUse PATCH to **partially update** a resource.\n\n```bash\nPATCH /posts/1\n```\n\n### DELETE\n\nUse DELETE to **remove** a resource.\n\n```bash\nDELETE /posts/1\n```\n\n## Response Codes\n\n- **200 OK**: Success!\n- **201 Created**: Resource created\n- **400 Bad Request**: Invalid input\n- **404 Not Found**: Resource doesn't exist\n- **500 Server Error**: Something went wrong"},{"id":"testing_tips","title":"💡 Testing Tips","markdown_content":"## Pro Tips for Testing\n\n### 1. Start Simple\n\nBegin with GET requests - they're the easiest!\n\n### 2. Check Required Fields\n\nRequired parameters are marked with a red asterisk (*).\n\n### 3. Use Examples\n\nMany endpoints have example payloads. Copy and modify them!\n\n### 4. Read the Response\n\nThe response shows:\n\n- **Status code** (200, 404, etc.)\n- **Response time** (how fast the API responded)\n- **Response body** (the actual data)\n\n### 5. Try Different Auth Methods\n\nSwitch between authentication types to see which works best for your API.\n\n### 6. Path Parameters\n\nFor endpoints like `/posts/{id}`, enter the ID in the Path Parameters section.\n\n### 7. Query Parameters\n\nAdd filters and pagination using Query Parameters.\n\n## Common Issues\n\n**CORS Error?**\n\nSome APIs block browser requests. Use a CORS proxy or test from your backend.\n\n**401 Unauthorized?**\n\nCheck your authentication credentials.\n\n**404 Not Found?**\n\nVerify the endpoint path and any path parameters."}],"api_server":"https://jsonplaceholder.typicode.com","api_servers":[],"auth_types":["bearer","api_key","basic","oauth2"],"ui_config":{},"generated_at":"2025-11-24T14:13:51+05:30"};
+window.dispatchEvent(new Event('elderdocs:data_loaded'));

data/lib/elder_docs/assets/viewer/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <title>ElderDocs - API Documentation</title>
+    <script type="module" crossorigin src="/docs/assets/index-886f4858.js"></script>
+    <link rel="stylesheet" href="/docs/assets/index-161b367b.css">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script src="/docs/data.js"></script>
+    
+  </body>
+</html>
+

data/lib/elder_docs/cli.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'elder_docs/generator'
+
+module ElderDocs
+  class CLI < Thor
+    desc 'deploy', 'Generate and deploy API documentation'
+    method_option :definitions, type: :string, default: 'definitions.json', aliases: '-d'
+    method_option :articles, type: :string, default: 'articles.json', aliases: '-a'
+    method_option :output, type: :string, default: nil, aliases: '-o'
+    method_option :api_server, type: :string, default: nil, desc: 'Default API server URL'
+    method_option :skip_build, type: :boolean, default: false, desc: 'Skip frontend build if assets exist'
+    method_option :force_build, type: :boolean, default: false, desc: 'Force rebuilding frontend assets'
+    
+    def deploy
+      say '🚀 Starting ElderDocs deployment...', :green
+      
+      definitions_path = options[:definitions]
+      articles_path = options[:articles]
+      
+      unless File.exist?(definitions_path)
+        say "❌ Error: #{definitions_path} not found in current directory", :red
+        exit 1
+      end
+      
+      unless File.exist?(articles_path)
+        say "⚠️  Warning: #{articles_path} not found. Creating empty articles file...", :yellow
+        File.write(articles_path, [].to_json)
+      end
+      
+      generator = Generator.new(
+        definitions_path: definitions_path,
+        articles_path: articles_path,
+        output_path: options[:output] || default_output_path,
+        api_server: options[:api_server],
+        skip_build: options[:skip_build],
+        force_build: options[:force_build]
+      )
+      
+      begin
+        generator.generate!
+        say '✅ Documentation generated successfully!', :green
+        say "📦 Assets placed in: #{generator.output_path}", :cyan
+      rescue Generator::ValidationError => e
+        say "❌ Validation Error: #{e.message}", :red
+        exit 1
+      rescue StandardError => e
+        say "❌ Error: #{e.message}", :red
+        say e.backtrace.first(5).join("\n"), :yellow if options[:verbose]
+        exit 1
+      end
+    end
+    
+    desc 'version', 'Show ElderDocs version'
+    def version
+      say "ElderDocs version #{ElderDocs::VERSION}", :green
+    end
+    
+    default_task :deploy
+    
+    private
+    
+    def default_output_path
+      File.join(File.dirname(__FILE__), '..', '..', 'lib', 'elder_docs', 'assets', 'viewer')
+    end
+  end
+end
+

data/lib/elder_docs/config.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module ElderDocs
+  class Config
+    attr_accessor :mount_path, :api_server, :auth_types, :ui_config, :admin_password
+    
+    def initialize
+      @mount_path = nil
+      @api_server = nil
+      @auth_types = ['bearer', 'api_key', 'basic', 'oauth2']
+      @ui_config = {}
+      @admin_password = nil
+      load_config_file
+    end
+    
+    def load_config_file
+      # Try to find config file in Rails root or current directory
+      config_paths = []
+      
+      if defined?(Rails) && Rails.root
+        config_paths << Rails.root.join('elderdocs.yml').to_s
+      end
+      
+      config_paths << File.join(Dir.pwd, 'elderdocs.yml')
+      
+      config_path = config_paths.find { |path| File.exist?(path) }
+      return unless config_path
+      
+      begin
+          config = YAML.load_file(config_path)
+          @mount_path = config['mount_path'] if config['mount_path']
+          @api_server = config['api_server'] if config['api_server']
+          @api_servers = config['api_servers'] if config['api_servers']
+          @auth_types = config['auth_types'] if config['auth_types']
+          @ui_config = config['ui'] if config['ui']  # YAML uses 'ui' key, but we store as ui_config
+          @admin_password = config['admin_password'] if config['admin_password']
+        rescue => e
+          warn "Warning: Could not load elderdocs.yml: #{e.message}"
+        end
+      end
+      
+      attr_reader :api_servers
+    
+    def self.instance
+      @instance ||= new
+    end
+  end
+  
+  def self.config
+    Config.instance
+  end
+end
+

data/lib/elder_docs/engine/ui_config_controller.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module ElderDocs
+  class Engine
+    class UiConfigController < ActionController::Base
+      include ActionController::MimeResponds
+      
+      # Enable sessions for authentication
+      protect_from_forgery with: :null_session
+      
+      # Simple session-based authentication
+      before_action :authenticate_admin, only: [:update]
+      before_action :check_auth_for_api, only: [:show]
+      
+      def show_login
+        render json: { requires_auth: true }
+      end
+      
+      def login
+        admin_password = ElderDocs.config.admin_password || ENV['ELDERDOCS_ADMIN_PASSWORD'] || 'admin'
+        
+        if params[:password] == admin_password
+          session[:elderdocs_admin] = true
+          render json: { success: true, message: 'Authentication successful' }
+        else
+          render json: { success: false, error: 'Invalid password' }, status: :unauthorized
+        end
+      end
+      
+      def show
+        # If requesting HTML, serve the UI configurator page
+        if request.format.html? || request.headers['Accept']&.include?('text/html')
+          ui_config_path = Engine.root.join('lib', 'elder_docs', 'assets', 'ui_config.html')
+          if ui_config_path.exist?
+            send_file ui_config_path, disposition: 'inline', type: 'text/html'
+          else
+            render plain: 'UI Configurator not found', status: :not_found
+          end
+        else
+          # API endpoint - return JSON config (auth checked in check_auth_for_api)
+          config_path = find_config_file
+          current_config = load_config(config_path)
+          
+          render json: {
+            ui_config: current_config['ui'] || {},
+            config_path: config_path
+          }
+        end
+      end
+      
+      def update
+        config_path = find_config_file
+        
+        # Load existing config
+        config = load_config(config_path) || {}
+        
+        # Update UI config
+        config['ui'] = {
+          'font_heading' => params[:font_heading],
+          'font_body' => params[:font_body],
+          'colors' => {
+            'primary' => params[:color_primary],
+            'secondary' => params[:color_secondary],
+            'background' => params[:color_background],
+            'surface' => params[:color_surface]
+          },
+          'corner_radius' => params[:corner_radius]
+        }
+        
+        # Save to file
+        save_config(config_path, config)
+        
+        # Reload config in memory
+        ElderDocs.config.load_config_file
+        
+        render json: {
+          success: true,
+          message: 'UI configuration saved successfully',
+          ui_config: config['ui']
+        }
+      end
+      
+      def logout
+        session[:elderdocs_admin] = nil
+        render json: { success: true, message: 'Logged out successfully' }
+      end
+      
+      private
+      
+      def authenticate_admin
+        unless session[:elderdocs_admin]
+          render json: { requires_auth: true, error: 'Authentication required' }, status: :unauthorized
+        end
+      end
+      
+      def check_auth_for_api
+        # Only require auth for JSON API requests, not HTML
+        return if request.format.html? || request.headers['Accept']&.include?('text/html')
+        
+        authenticate_admin
+      end
+      
+      def find_config_file
+        config_paths = []
+        
+        if defined?(Rails) && Rails.root
+          config_paths << Rails.root.join('elderdocs.yml').to_s
+        end
+        
+        config_paths << File.join(Dir.pwd, 'elderdocs.yml')
+        
+        config_path = config_paths.find { |path| File.exist?(path) }
+        
+        # Create default config file if it doesn't exist
+        unless config_path
+          config_path = config_paths.first || File.join(Dir.pwd, 'elderdocs.yml')
+          File.write(config_path, {}.to_yaml)
+        end
+        
+        config_path
+      end
+      
+      def load_config(config_path)
+        return {} unless File.exist?(config_path)
+        
+        begin
+          YAML.load_file(config_path) || {}
+        rescue => e
+          Rails.logger.error "Error loading config: #{e.message}"
+          {}
+        end
+      end
+      
+      def save_config(config_path, config)
+        File.write(config_path, config.to_yaml)
+      rescue => e
+        Rails.logger.error "Error saving config: #{e.message}"
+        raise
+      end
+    end
+  end
+end
+

data/lib/elder_docs/engine.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module ElderDocs
+  class Engine < ::Rails::Engine
+    isolate_namespace ElderDocs
+    
+    # Define routes inline
+    routes do
+      # UI Configuration endpoints (before catch-all)
+      get '/ui', to: 'engine/ui_config#show'
+      get '/ui/login', to: 'engine/ui_config#show_login'
+      post '/ui/login', to: 'engine/ui_config#login'
+      post '/ui/logout', to: 'engine/ui_config#logout'
+      post '/ui/config', to: 'engine/ui_config#update'
+      
+      # Serve data.js explicitly before catch-all
+      get '/data.js', to: 'engine/docs#show', defaults: { path: 'data.js' }
+      root 'engine/docs#show', defaults: { path: 'index.html' }
+      get '/*path', to: 'engine/docs#show', defaults: { path: 'index.html' }
+    end
+    
+    # Note: Engine must be manually mounted in routes.rb
+    # We provide a helper to check for conflicts
+    initializer 'elder_docs.check_routes' do |app|
+      mount_path = ElderDocs.config.mount_path || '/docs'
+      
+      # Check if route already exists when routes are loaded
+      app.config.after_initialize do
+        begin
+          # Try to generate URL helper for the mount path
+          route_name = mount_path.gsub('/', '_').gsub('-', '_').sub(/^_/, '')
+          if app.routes.url_helpers.respond_to?("#{route_name}_path")
+            Rails.logger.warn "ElderDocs: Route #{mount_path} already exists. Please mount manually in config/routes.rb with a different path."
+          end
+        rescue => e
+          # Route doesn't exist, which is fine
+        end
+      end
+    end
+    
+    # Load UI config controller
+    require_relative 'engine/ui_config_controller'
+    
+    # Create a simple controller to serve the static files
+    # Use API base to avoid CSRF protection
+    class DocsController < ActionController::API
+      include ActionController::MimeResponds
+      
+      def show
+        viewer_path = Engine.root.join('lib', 'elder_docs', 'assets', 'viewer')
+        requested_path = params[:path]
+        requested_path = requested_path.present? ? requested_path : 'index'
+        requested_path = [requested_path, params[:format]].compact.join('.')
+        requested_path = 'index.html' if requested_path == 'index'
+        file_path = viewer_path.join(requested_path)
+        
+        # Security check: ensure file is within viewer directory
+        if file_path.exist? && file_path.to_s.start_with?(viewer_path.to_s)
+          send_file file_path, disposition: 'inline', type: mime_type_for(file_path)
+        else
+          # Fallback to index.html for SPA routing (but not for data.js or assets)
+          if requested_path.end_with?('.js') || requested_path.end_with?('.css') || requested_path.end_with?('.json')
+            head :not_found
+          else
+            send_file viewer_path.join('index.html'), disposition: 'inline', type: 'text/html'
+          end
+        end
+      end
+      
+      private
+      
+      def mime_type_for(file_path)
+        ext = File.extname(file_path.to_s)
+        case ext
+        when '.js'
+          'application/javascript'
+        when '.css'
+          'text/css'
+        when '.json'
+          'application/json'
+        when '.html'
+          'text/html'
+        when '.png'
+          'image/png'
+        when '.jpg', '.jpeg'
+          'image/jpeg'
+        when '.svg'
+          'image/svg+xml'
+        else
+          'application/octet-stream'
+        end
+      end
+    end
+  end
+end
+

data/lib/elder_docs/generator.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openapi_parser'
+require 'fileutils'
+
+module ElderDocs
+  class Generator
+    class ValidationError < StandardError; end
+    
+    attr_reader :definitions_path, :articles_path, :output_path, :api_server, :skip_build, :force_build
+    
+    def initialize(definitions_path:, articles_path:, output_path:, api_server: nil, skip_build: false, force_build: false)
+      @definitions_path = definitions_path
+      @articles_path = articles_path
+      @output_path = output_path
+      @api_server = api_server
+      @skip_build = skip_build
+      @force_build = force_build
+    end
+    
+    def generate!
+      validate_definitions!
+      validate_articles!
+      compile_data!
+      
+      # Check if assets already exist
+      assets_exist = File.exist?(File.join(output_path, 'index.html'))
+      
+      if skip_build || (assets_exist && !force_build)
+        say '⏭️  Skipping frontend build (assets already exist)', :yellow
+        say '💾 Updating data.js only...', :cyan
+        # Still update data.js with latest compiled data
+        FileUtils.mkdir_p(output_path)
+        File.write(File.join(output_path, 'data.js'), @compiled_data_js)
+        say '✅ Data updated', :green
+      else
+        build_frontend!
+        copy_assets!
+      end
+    end
+    
+    private
+    
+    def validate_definitions!
+      say '📋 Validating OpenAPI definitions...', :cyan
+      
+      begin
+        # Parse JSON first to ensure it's valid JSON (read as UTF-8)
+        json_content = File.read(definitions_path, encoding: 'UTF-8')
+        parsed_json = JSON.parse(json_content)
+        
+        # Basic OpenAPI structure validation
+        unless parsed_json.is_a?(Hash)
+          raise ValidationError, 'OpenAPI definition must be a JSON object'
+        end
+        
+        unless parsed_json['openapi'] || parsed_json['swagger']
+          raise ValidationError, 'OpenAPI definition must include "openapi" or "swagger" field'
+        end
+        
+        unless parsed_json['info']
+          raise ValidationError, 'OpenAPI definition must include "info" field'
+        end
+        
+        unless parsed_json['paths']
+          raise ValidationError, 'OpenAPI definition must include "paths" field'
+        end
+        
+        # Try to validate with OpenAPIParser, but don't fail if it has issues
+        begin
+          parser = OpenAPIParser.parse(
+            json_content,
+            {
+              strict_reference_validation: false,
+              coerce_value: false
+            }
+          )
+          
+          unless parser.valid?
+            say '⚠️  Warning: OpenAPI parser validation failed, but continuing anyway', :yellow
+          end
+        rescue => parser_error
+          say "⚠️  Warning: OpenAPI parser error (#{parser_error.message}), but continuing with basic validation", :yellow
+        end
+        
+        # Use the parsed JSON directly, convert symbol keys to string keys for consistency
+        @openapi_data = deep_stringify_keys(parsed_json)
+        say '✅ OpenAPI definitions validated', :green
+      rescue JSON::ParserError => e
+        raise ValidationError, "Invalid JSON in definitions file: #{e.message}"
+      rescue ValidationError
+        raise
+      rescue => e
+        raise ValidationError, "Error processing OpenAPI definition: #{e.message}"
+      end
+    end
+    
+    def deep_stringify_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = deep_stringify_keys(value)
+        end
+      when Array
+        obj.map { |item| deep_stringify_keys(item) }
+      else
+        obj
+      end
+    end
+    
+    def validate_articles!
+      say '📚 Validating articles...', :cyan
+      
+      begin
+        # Read as UTF-8 to handle emojis and special characters
+        articles_content = File.read(articles_path, encoding: 'UTF-8')
+        @articles_data = JSON.parse(articles_content)
+        
+        unless @articles_data.is_a?(Array)
+          raise ValidationError, 'articles.json must be an array'
+        end
+        
+        @articles_data.each_with_index do |article, index|
+          validate_article!(article, index)
+        end
+        
+        say '✅ Articles validated', :green
+      rescue JSON::ParserError => e
+        raise ValidationError, "Invalid JSON in articles file: #{e.message}"
+      end
+    end
+    
+    def validate_article!(article, index)
+      required_fields = %w[id title markdown_content]
+      missing_fields = required_fields - article.keys
+      
+      if missing_fields.any?
+        raise ValidationError, "Article at index #{index} missing required fields: #{missing_fields.join(', ')}"
+      end
+      
+      unless article['id'].is_a?(String) && !article['id'].empty?
+        raise ValidationError, "Article at index #{index} must have a non-empty string 'id'"
+      end
+      
+      unless article['title'].is_a?(String) && !article['title'].empty?
+        raise ValidationError, "Article at index #{index} must have a non-empty string 'title'"
+      end
+      
+      unless article['markdown_content'].is_a?(String)
+        raise ValidationError, "Article at index #{index} must have a string 'markdown_content'"
+      end
+    end
+    
+    def compile_data!
+      say '📦 Compiling data...', :cyan
+      
+      # Get API server from: CLI option > config file > OpenAPI servers
+      final_api_server = api_server || ElderDocs.config.api_server || extract_api_server_from_openapi
+      final_api_servers = ElderDocs.config.api_servers || []
+      
+      compiled_data = {
+        openapi: @openapi_data,
+        articles: @articles_data,
+        api_server: final_api_server,
+        api_servers: final_api_servers,
+        auth_types: ElderDocs.config.auth_types || ['bearer', 'api_key', 'basic', 'oauth2'],
+        ui_config: ElderDocs.config.ui_config || {},
+        generated_at: Time.now.iso8601
+      }
+      
+      @compiled_data_js = <<~JS
+        window.ElderDocsData = #{compiled_data.to_json};
+        window.dispatchEvent(new Event('elderdocs:data_loaded'));
+      JS
+      
+      say '✅ Data compiled', :green
+    end
+    
+    def extract_api_server_from_openapi
+      servers = @openapi_data.dig('servers') || []
+      servers.first&.dig('url') || ''
+    end
+    
+    def build_frontend!
+      say '🔨 Building frontend...', :cyan
+      
+      frontend_dir = File.join(File.dirname(__FILE__), '..', '..', 'frontend')
+      
+      unless Dir.exist?(frontend_dir)
+        raise ValidationError, "Frontend directory not found at #{frontend_dir}"
+      end
+      
+      # Write compiled data to frontend public directory
+      public_dir = File.join(frontend_dir, 'public')
+      FileUtils.mkdir_p(public_dir)
+      File.write(File.join(public_dir, 'data.js'), @compiled_data_js)
+      
+      # Check if node_modules exists, if not, run npm install
+      node_modules = File.join(frontend_dir, 'node_modules')
+      unless Dir.exist?(node_modules)
+        say '📦 Installing npm dependencies...', :cyan
+        system("cd #{frontend_dir} && npm install") || raise('Failed to install npm dependencies')
+      end
+      
+      # Run Vite build
+      say '⚡ Running Vite build...', :cyan
+      build_success = system("cd #{frontend_dir} && npm run build")
+      
+      unless build_success
+        raise ValidationError, 'Frontend build failed'
+      end
+      
+      @build_output_dir = File.join(frontend_dir, 'dist')
+      
+      unless Dir.exist?(@build_output_dir)
+        raise ValidationError, 'Build output directory not found'
+      end
+      
+      say '✅ Frontend built successfully', :green
+    end
+    
+    def copy_assets!
+      say '📁 Copying assets...', :cyan
+      
+      FileUtils.mkdir_p(output_path)
+      FileUtils.rm_rf(Dir.glob(File.join(output_path, '*')))
+      
+      # Copy all files from dist to output_path
+      Dir.glob(File.join(@build_output_dir, '**', '*')).each do |source|
+        next if File.directory?(source)
+        
+        relative_path = source.sub(@build_output_dir + '/', '')
+        dest_path = File.join(output_path, relative_path)
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        FileUtils.cp(source, dest_path)
+      end
+      
+      # Fix asset paths in index.html to work with engine mount point
+      index_html_path = File.join(output_path, 'index.html')
+      if File.exist?(index_html_path)
+        html_content = File.read(index_html_path, encoding: 'UTF-8')
+        # Replace relative paths with paths relative to mount point
+        html_content.gsub!(/src="\.\//, 'src="/docs/')
+        html_content.gsub!(/href="\.\//, 'href="/docs/')
+        html_content.gsub!(/src="\/assets\//, 'src="/docs/assets/')
+        html_content.gsub!(/href="\/assets\//, 'href="/docs/assets/')
+        # Fix data.js path
+        html_content.gsub!(/src="\/data\.js/, 'src="/docs/data.js')
+        File.write(index_html_path, html_content)
+      end
+      
+      say '✅ Assets copied', :green
+    end
+    
+    def say(message, color = nil)
+      return unless defined?(Thor)
+      
+      Thor::Base.shell.new.say(message, color)
+    end
+  end
+end
+