Phase 4: move catalog controllers and routes into WarpEngine

- update, files and the 6 /api catalog controllers now live in the engine on
  a new WarpEngine::ApiController base (same rescue/mime behavior as host)
- engine routes serve /update, /file/*path, /api/software*, /api/builds*,
  /api/image/:id, /api/download at unchanged public paths via the root mount;
  host routes keep only TTG endpoints (events, members, wiki, rss, swagger)
- /update secret comes from WarpEngine.config.update_secret and an
  unconfigured secret now rejects every request (previously an empty
  UPDATE_SECRET env accepted empty secrets)
- apipie-rails is an engine dependency (DSL in engine controllers); dummy app
  configures apipie with validation off, mirroring the host
- engine request specs: catalog controller specs moved from host plus new
  /update auth contract spec

Verified: engine suite 53 green, host suite 6 green, /api/software and
/api/builds byte-identical to baselines, /update 401/400 behavior intact,
admin and TTG endpoints OK.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

app/controllers/warp_engine/api/builds_controller.rb

@@ -0,0 +1,7 @@
+module WarpEngine
+  class Api::BuildsController < ApiController
+    def index
+      render json: WarpEngine::BuildsService.new.index
+    end
+  end
+end

app/controllers/warp_engine/api/downloads_controller.rb

@@ -0,0 +1,31 @@
+module WarpEngine
+  class Api::DownloadsController < ApiController
+    resource_description do
+      short "File downloads"
+      formats [ "binary" ]
+    end
+
+    api :GET, "/api/download", "Download a file by path"
+    param :path, String, required: true, desc: "File path to download"
+    returns code: 200, desc: "File binary data"
+    error code: 400, desc: "Path is blank"
+    error code: 404, desc: "File not found"
+    def show
+      path = params[:path]
+      return render(json: { error: "Path is required" }, status: :bad_request) if path.blank?
+
+      full_path = WarpEngine::DownloadService.new.create(
+        path: path,
+        ip: request.remote_ip,
+        user_agent: request.user_agent,
+        referer: request.referer
+      )
+
+      if full_path
+        send_file full_path, disposition: "attachment", type: resolve_mime(full_path)
+      else
+        render json: { error: "Not found" }, status: :not_found
+      end
+    end
+  end
+end

app/controllers/warp_engine/api/images_controller.rb

@@ -0,0 +1,17 @@
+module WarpEngine
+  class Api::ImagesController < ApiController
+    resource_description do
+      short "Images"
+      formats [ "binary" ]
+    end
+
+    api :GET, "/api/image/:id", "Get image by ID"
+    param :id, :number, required: true, desc: "Image ID"
+    returns code: 200, desc: "Image binary data"
+    error code: 404, desc: "Image not found"
+    def show
+      image = WarpEngine::ImageService.new.show(WarpEngine::ImageShowInputDto.new(id: params[:id]))
+      send_file image.file_path, type: image.content_type, disposition: "inline"
+    end
+  end
+end

app/controllers/warp_engine/api/software_builds_controller.rb

@@ -0,0 +1,7 @@
+module WarpEngine
+  class Api::SoftwareBuildsController < ApiController
+    def show
+      render json: WarpEngine::BuildsService.new.show(params[:name])
+    end
+  end
+end

app/controllers/warp_engine/api/software_controller.rb

@@ -0,0 +1,61 @@
+module WarpEngine
+  class Api::SoftwareController < ApiController
+    resource_description do
+      short "Software catalog"
+    end
+
+    def_param_group :external_link do
+      property :ID, Integer, desc: "Link ID"
+      property :softwareId, Integer, desc: "Parent software ID"
+      property :label, String, desc: "Link label (e.g. GitHub)"
+      property :url, String, desc: "Link URL"
+    end
+
+    def_param_group :software_image do
+      property :url, String, desc: "Image URL (e.g. /api/image/123)"
+      property :isDefault, :boolean, desc: "Default image flag"
+      property :position, Integer, desc: "Display order"
+    end
+
+    def_param_group :release do
+      property :ID, Integer, desc: "Release ID"
+      property :softwareId, Integer, desc: "Parent software ID"
+      property :version, String, desc: "Version string"
+      property :cartridgePath, String, desc: "Cartridge file path"
+      property :sourcePath, String, desc: "Source file path"
+      property :htmlFolderPath, String, desc: "HTML playable folder path"
+      property :docsFolderPath, String, desc: "Documentation folder path"
+      property :downloadCount, Integer, desc: "Download count for this release"
+    end
+
+    api :GET, "/api/software", "List all software entries with releases"
+    returns code: 200, desc: "Wrapper object with softwares array" do
+      property :softwares, Array, desc: "Array of software entries" do
+        property :ID, Integer, desc: "Software ID"
+        property :name, String, desc: "Internal name"
+        property :title, String, desc: "Display title"
+        property :author, String, desc: "Author name"
+        property :desc, String, desc: "Short description"
+        property :story, String, desc: "Long description / story"
+        property :license, String, desc: "License type"
+        property :platform, String, desc: "Platform (tic80, love, ebitengine, c64, godot, bevy, phaser)"
+        property :status, String, desc: "Status (active, inactive)"
+        property :highlighted, :boolean, desc: "Currently highlighted"
+        property :imageUrl, String, desc: "Default image URL"
+        property :externalLinks, Array, desc: "External links" do
+          property :ID, Integer, desc: "Link ID"
+          property :label, String, desc: "Link label"
+          property :url, String, desc: "Link URL"
+        end
+        property :images, Array, desc: "Image gallery" do
+          property :url, String, desc: "Image URL"
+          property :isDefault, :boolean, desc: "Default image flag"
+          property :position, Integer, desc: "Display order"
+        end
+      end
+    end
+    def index
+      render json: WarpEngine::SoftwareService.new.index
+    end
+  end
+end

app/controllers/warp_engine/api/software_highlighted_controller.rb

@@ -0,0 +1,45 @@
+module WarpEngine
+  class Api::SoftwareHighlightedController < ApiController
+    resource_description do
+      short "Highlighted software"
+    end
+
+    api :GET, "/api/software/highlighted", "Get currently highlighted software entry"
+    returns code: 200, desc: "Highlighted software with releases and stats" do
+      property :software, Hash, desc: "Software entry" do
+        property :ID, Integer, desc: "Software ID"
+        property :name, String, desc: "Internal name"
+        property :title, String, desc: "Display title"
+        property :author, String, desc: "Author name"
+        property :desc, String, desc: "Short description"
+        property :story, String, desc: "Long description / story"
+        property :license, String, desc: "License type"
+        property :platform, String, desc: "Platform (tic80, love, ebitengine, c64, godot, bevy, phaser)"
+        property :status, String, desc: "Status"
+        property :highlighted, :boolean, desc: "Highlighted flag"
+        property :imageUrl, String, desc: "Default image URL"
+      end
+      property :releases, Array, desc: "All releases" do
+        property :ID, Integer, desc: "Release ID"
+        property :version, String, desc: "Version string"
+        property :cartridgePath, String, desc: "Cartridge path"
+        property :sourcePath, String, desc: "Source path"
+        property :htmlFolderPath, String, desc: "HTML folder path"
+        property :docsFolderPath, String, desc: "Docs folder path"
+        property :downloadCount, Integer, desc: "Download count"
+      end
+      property :latestRelease, Hash, desc: "Latest release object"
+      property :webPlayableRelease, Hash, desc: "Web-playable release (if any)"
+      property :totalDownloads, Integer, desc: "Total download count across all releases"
+    end
+    error code: 404, desc: "No highlighted software found"
+    def index
+      result = WarpEngine::SoftwareHighlightedService.new.index
+      if result
+        render json: result
+      else
+        render json: { error: "no highlighted software found" }, status: :not_found
+      end
+    end
+  end
+end

app/controllers/warp_engine/api_controller.rb

@@ -0,0 +1,32 @@
+module WarpEngine
+  class ApiController < ActionController::API
+    resource_description do
+      api_version "1.0"
+      formats [ "json" ]
+    end
+
+    rescue_from StandardError do |e|
+      Rails.logger.error("[#{self.class.name}] #{e.class}: #{e.message}")
+      render json: { error: "Internal server error" }, status: :internal_server_error
+    end
+
+    rescue_from ActiveRecord::RecordNotFound do |e|
+      render json: { error: "Not found" }, status: :not_found
+    end
+
+    rescue_from Errno::ENOENT do |e|
+      render json: { error: "Not found" }, status: :not_found
+    end
+
+    rescue_from ArgumentError do |e|
+      render json: { error: e.message }, status: :bad_request
+    end
+
+    private
+
+    def resolve_mime(path)
+      ext = File.extname(path.to_s).delete_prefix(".")
+      Mime::Type.lookup_by_extension(ext) || "application/octet-stream"
+    end
+  end
+end

app/controllers/warp_engine/files_controller.rb

@@ -0,0 +1,22 @@
+module WarpEngine
+  class FilesController < ApiController
+    resource_description do
+      short "Static files"
+      formats [ "binary" ]
+    end
+
+    api :GET, "/file/*path", "Serve or redirect to a file"
+    param :path, String, required: true, desc: "File path"
+    returns code: 200, desc: "File binary data"
+    returns code: 301, desc: "Redirect to file URL"
+    error code: 404, desc: "File not found"
+    def show
+      result = WarpEngine::FileService.new.show(WarpEngine::FileShowInputDto.new(path: params[:path]))
+      case result.type
+      when :redirect  then redirect_to result.url, status: :moved_permanently
+      when :file      then send_file result.path, disposition: "inline", type: resolve_mime(result.path)
+      when :not_found then head :not_found
+      end
+    end
+  end
+end

app/controllers/warp_engine/update_controller.rb

@@ -0,0 +1,49 @@
+module WarpEngine
+  class UpdateController < ApiController
+    resource_description do
+      short "Software updater"
+      formats [ "text" ]
+    end
+
+    rescue_from ArgumentError do |e|
+      render plain: e.message, status: :bad_request
+    end
+
+    rescue_from StandardError do |e|
+      Rails.logger.error("[UpdateController] #{e.class}: #{e.message}\n#{e.backtrace.first(5).join("\n")}")
+      render plain: "Internal server error", status: :internal_server_error
+    end
+
+    api :GET, "/update", "Update software version in database"
+    param :secret, String, required: true, desc: "Authorization secret"
+    param :platform, String, required: false, desc: "Platform (tic80, love, ebitengine, c64, godot, bevy, phaser)"
+    param :name, String, required: false, desc: "Software name"
+    param :version, String, required: true, desc: "Version string"
+    returns code: 200, desc: "Plain text 'Updated'"
+    error code: 401, desc: "Invalid secret"
+    error code: 400, desc: "Version not provided or invalid arguments"
+    error code: 500, desc: "Internal server error"
+    def update
+      return render plain: "Unauthorized", status: :unauthorized unless authorized?
+      return render plain: "Version not provided", status: :bad_request if params[:version].blank?
+
+      input = WarpEngine::UpdateInputDto.new(
+        platform: params[:platform],
+        name:     params[:name],
+        version:  params[:version]
+      )
+
+      WarpEngine::UpdateService.new.update(input)
+      render plain: "Updated"
+    end
+
+    private
+
+    def authorized?
+      secret = request.headers["X-Update-Secret"].presence || params[:secret]
+      expected = WarpEngine.config.update_secret
+      # Konfigurálatlan secret esetén az endpoint zárva marad.
+      expected.present? && secret == expected
+    end
+  end
+end