Phase 6: polish — apipie matcher, install generator, engine migrations, docs

- host apipie matcher now globs the engine controllers, so /api/docs and
  /api/swagger keep documenting the catalog endpoints
- rails g warp_engine:install: initializer template + a clean
  create_warp_engine_tables migration (signed bigint PKs) for new hosts;
  TTG never runs it
- engine append_migrations initializer: future catalog migrations in the
  engine's db/migrate run via the host's rails db:migrate
- README documents the updater contract, config surface, host expectations
  (admin JS picker, apipie matcher) and the soft-delete/resurrection behavior
- make api-test runs both suites plus a production zeitwerk:check

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

lib/generators/warp_engine/install/install_generator.rb

@@ -0,0 +1,35 @@
+require "rails/generators"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module WarpEngine
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/warp_engine.rb"
+      end
+
+      def copy_migration
+        migration_template "create_warp_engine_tables.rb", "db/migrate/create_warp_engine_tables.rb"
+      end
+
+      def show_readme
+        say <<~MSG
+
+          WarpEngine telepítve. Következő lépések:
+            1. rails db:migrate
+            2. mount WarpEngine::Engine => "/" a config/routes.rb végére
+            3. állítsd be a config/initializers/warp_engine.rb-t
+        MSG
+      end
+    end
+  end
+end

lib/generators/warp_engine/install/templates/create_warp_engine_tables.rb

@@ -0,0 +1,91 @@
+class CreateWarpEngineTables < ActiveRecord::Migration[8.0]
+  def change
+    create_table :softwares do |t|
+      t.string :name, limit: 128
+      t.string :title
+      t.string :author
+      t.text :desc
+      t.text :story
+      t.string :license, limit: 128
+      t.string :platform, limit: 128
+      t.string :site
+      t.string :status, limit: 20, default: "development"
+      t.boolean :highlighted, default: false
+      t.datetime :deleted_at, precision: 3
+      t.timestamps precision: 3, null: true
+      t.index :name, unique: true
+      t.index :deleted_at
+    end
+
+    create_table :releases do |t|
+      t.references :software, foreign_key: { on_delete: :cascade }
+      t.string :version, limit: 64
+      t.datetime :deleted_at, precision: 3
+      t.timestamps precision: 3, null: true
+      t.index :deleted_at
+    end
+
+    create_table :release_assets do |t|
+      t.references :release, null: false, foreign_key: { on_delete: :cascade }
+      t.string :kind, limit: 32, null: false
+      t.string :path, null: false
+      t.datetime :deleted_at, precision: 3
+      t.timestamps precision: 3
+      t.index [ :release_id, :kind ], unique: true
+      t.index :path
+      t.index :deleted_at
+    end
+
+    create_table :external_links do |t|
+      t.references :software, foreign_key: { on_delete: :cascade }
+      t.string :label, limit: 128
+      t.string :url
+      t.datetime :deleted_at, precision: 3
+      t.timestamps precision: 3, null: true
+      t.index :deleted_at
+    end
+
+    create_table :platform_links do |t|
+      t.string :name, limit: 128
+      t.string :platform, limit: 128
+      t.string :url
+      t.integer :position, default: 0, null: false
+      t.datetime :deleted_at, precision: 3
+      t.timestamps precision: 3, null: true
+      t.index :platform
+      t.index :deleted_at
+    end
+
+    create_table :images do |t|
+      t.string :filename, null: false
+      t.string :original_filename, null: false
+      t.string :content_type, default: "application/octet-stream", null: false
+      t.datetime :deleted_at, precision: 3
+      t.timestamps
+      t.index :deleted_at
+    end
+
+    create_table :software_images do |t|
+      t.references :software, null: false, foreign_key: { on_delete: :cascade }
+      t.references :image, null: false, foreign_key: true, index: false
+      t.boolean :is_default, default: false, null: false
+      t.integer :position, default: 0, null: false
+      t.timestamps
+      t.index [ :software_id, :image_id ], unique: true
+      t.index [ :software_id, :position ]
+    end
+
+    create_table :downloads do |t|
+      t.string :file_path, null: false
+      t.references :release, foreign_key: { on_delete: :nullify }, index: false
+      t.string :ip_address
+      t.string :user_agent, limit: 500
+      t.string :referer, limit: 500
+      t.datetime :deleted_at, precision: 3
+      t.timestamps precision: 3, null: true
+      t.index :file_path
+      t.index :release_id
+      t.index :deleted_at
+    end
+  end
+end

lib/generators/warp_engine/install/templates/initializer.rb

@@ -0,0 +1,22 @@
+Rails.application.config.to_prepare do
+  WarpEngine.configure do |c|
+    # A build-artifactok és képek tárolási helye (defaultok az env-ből:
+    # FILE_CONTAINER_PATH ill. IMAGE_CONTAINER_PATH).
+    # c.file_container_path  = "/softwares"
+    # c.image_container_path = "/images"
+
+    # A /update endpoint shared secretje (default: ENV["UPDATE_SECRET"]).
+    # Beállítatlan secret esetén az endpoint minden kérést elutasít.
+    # c.update_secret = ENV["UPDATE_SECRET"]
+
+    # Ha a host modelljei is hivatkoznak katalógus-képekre, regisztráld őket,
+    # hogy az admin Images oldal orphan-detektálása figyelembe vegye:
+    # c.image_owners = [
+    #   {
+    #     label: "member",
+    #     image_ids: -> { Member.where.not(image_id: nil).distinct.pluck(:image_id) },
+    #     usage_label: ->(image) { "member" if Member.where(image_id: image.id).exists? }
+    #   }
+    # ]
+  end
+end

lib/warp_engine/engine.rb

@@ -8,6 +8,16 @@ module WarpEngine
       Rails.autoloaders.main.ignore(Engine.root.join("app/admin"))
     end
 
+    # A jövőbeli katalógus-migrációk az engine db/migrate-jéből futnak a host
+    # rails db:migrate-jével, másolás nélkül.
+    initializer "warp_engine.append_migrations" do |app|
+      unless app.root.to_s.start_with?(root.to_s)
+        config.paths["db/migrate"].expanded.each do |path|
+          app.config.paths["db/migrate"] << path
+        end
+      end
+    end
+
     # Az admin erőforrásokat a HOST ActiveAdmin példánya tölti be; az engine csak
     # regisztrálja a saját app/admin könyvtárát. Auth/téma/route-ok a host dolga.
     initializer "warp_engine.active_admin" do |app|