tools/warp_engine
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite READMEs in English for the WarpEngine split

Browse Source 
- root README: monorepo layout with libs/, the WarpEngine/host layering,
  rebuild note for the root build context, make api-test and snapshot docs
- warp_engine README translated to English

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
mr.zero
2026-08-04 19:36:40 +02:00
co-authored by Claude Fable 5
parent 0f5315f705
commit 9f806ff57a
1 changed files with 43 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+43 -36
View File
@@ -1,24 +1,29 @@
# WarpEngine # WarpEngine
Mountable Rails engine: retro szoftverkatalógus CI-pipeline-ból hívható release-updaterrel, Mountable Rails engine: a retro software catalog with a CI-pipeline-callable
publikus read-only JSON API-val és a host adminjába betöltődő ActiveAdmin erőforrásokkal. release updater, a public read-only JSON API, and ActiveAdmin resources that
load into the host application's admin.
## Mit ad ## What it provides
- **Modellek**: `Software`, `Release`, `ReleaseAsset`, `ExternalLink`, `PlatformLink`, - **Models**: `Software`, `Release`, `ReleaseAsset`, `ExternalLink`,
`Image`, `SoftwareImage`, `Download` (mind `WarpEngine::` alatt, prefix nélküli táblákkal) `PlatformLink`, `Image`, `SoftwareImage`, `Download` (all under
- **Updater**: `GET /update?platform=&name=&version=` (`X-Update-Secret` fejléc vagy `WarpEngine::`, with unprefixed table names)
`?secret=`) — a CI a build-artifactokat a `file_container_path` alá másolja - **Updater**: `GET /update?platform=&name=&version=` (auth via the
(`<name>-<version>*` konvencióval), majd meghívja az endpointot; az updater kicsomagol, `X-Update-Secret` header or `?secret=`) — CI copies build artifacts under
metadatát parse-ol, és upserteli a Software/Release/ReleaseAsset/ExternalLink rekordokat. `file_container_path` using the `<name>-<version>*` naming convention, then
Támogatott platformok: tic80, ebitengine, love, c64, godot, bevy, phaser. calls the endpoint; the updater extracts archives, parses metadata, and
- **Publikus API**: `/api/software`, `/api/software/highlighted`, `/api/builds`, upserts the Software/Release/ReleaseAsset/ExternalLink records.
`/api/softwares/:name/builds`, `/api/image/:id`, `/api/download?path=`, `/file/*path` Supported platforms: tic80, ebitengine, love, c64, godot, bevy, phaser.
- **Admin**: ActiveAdmin resource-fájlok (softwares a 3 szintű beágyazott formmal, - **Public API**: `/api/software`, `/api/software/highlighted`, `/api/builds`,
releases, external links, platform links, images orphan-kezeléssel, Files fájlkezelő `/api/softwares/:name/builds`, `/api/image/:id`, `/api/download?path=`,
picker móddal, download stats) — a host ActiveAdmin példányába töltődnek be. `/file/*path`
- **Admin**: ActiveAdmin resource files (softwares with a 3-level nested form,
releases, external links, platform links, images with orphan management, a
Files file-manager page with picker mode, download stats) — loaded into the
host's single ActiveAdmin instance.
## Telepítés ## Installation
```ruby ```ruby
# Gemfile # Gemfile
@@ -26,24 +31,24 @@ gem "warp_engine", path: "../../libs/ruby/warp_engine"
``` ```
```sh ```sh
rails g warp_engine:install # initializer + create_warp_engine_tables migráció rails g warp_engine:install # initializer + create_warp_engine_tables migration
rails db:migrate rails db:migrate
``` ```
```ruby ```ruby
# config/routes.rb — utolsó sorként, hogy a host route-jai nyerjenek # config/routes.rb — keep it the last entry so host routes win
mount WarpEngine::Engine => "/" mount WarpEngine::Engine => "/"
``` ```
## Konfiguráció ## Configuration
```ruby ```ruby
Rails.application.config.to_prepare do Rails.application.config.to_prepare do
WarpEngine.configure do |c| WarpEngine.configure do |c|
c.file_container_path = ENV.fetch("FILE_CONTAINER_PATH", "/softwares") c.file_container_path = ENV.fetch("FILE_CONTAINER_PATH", "/softwares")
c.image_container_path = ENV.fetch("IMAGE_CONTAINER_PATH", "/images") c.image_container_path = ENV.fetch("IMAGE_CONTAINER_PATH", "/images")
c.update_secret = ENV["UPDATE_SECRET"] # nil => /update mindig elutasít c.update_secret = ENV["UPDATE_SECRET"] # nil => /update rejects everything
# Ha a host modelljei is használnak katalógus-képeket: # If host models also reference catalog images:
c.image_owners = [ c.image_owners = [
{ {
label: "member", label: "member",
@@ -55,28 +60,30 @@ Rails.application.config.to_prepare do
end end
``` ```
## Host-elvárások ## Host expectations
- **ActiveAdmin + Devise a hostban él**: auth, téma, assetek és a `/admin` route-ok a - **ActiveAdmin + Devise live in the host**: authentication, theme, assets and
host dolga; az engine csak resource-fájlokat ad a `ActiveAdmin.application.load_paths`-hoz. the `/admin` routes are the host's responsibility; the engine only appends
- **Files picker JS**: a release-asset path-mezők melletti fájlkiválasztó a host its resource files to `ActiveAdmin.application.load_paths`.
`active_admin.js`-ében élő pár soros JS-re támaszkodik (iframe a - **Files picker JS**: the file-picker next to release-asset path inputs relies
`/admin/files?picker=1&field=<dom_id>` címre) — új hostba ezt is át kell venni. on a few lines of JS in the host's `active_admin.js` (an iframe pointing at
- **apipie**: ha a host apipie-dokut generál, vegye fel a matcherbe: `/admin/files?picker=1&field=<dom_id>`) — copy that over to a new host too.
- **apipie**: if the host generates apipie docs, add the engine to the matcher:
`"#{WarpEngine::Engine.root}/app/controllers/**/*.rb"`. `"#{WarpEngine::Engine.root}/app/controllers/**/*.rb"`.
## Viselkedési megjegyzések ## Behavioral notes
- Minden modell soft-delete-es (`default_scope { where(deleted_at: nil) }`); az updater - Every model is soft-deleted (`default_scope { where(deleted_at: nil) }`);
`.unscoped`-dal "feltámasztja" az újra beküldött, korábban törölt rekordokat. the updater "resurrects" re-submitted, previously deleted records via
- A JSON-formátum szándékosan bug-kompatibilis az egykori Go backenddel `.unscoped`.
(Go zero-time timestampek, camelCase kulcsok, legacy flat path mezők). - The JSON shape is intentionally bug-compatible with the former Go backend
- Modell-kiterjesztési pontok: `ActiveSupport.on_load(:warp_engine_<model>)` hookok. (Go zero-time timestamps, camelCase keys, legacy flat path fields).
- Model extension points: `ActiveSupport.on_load(:warp_engine_<model>)` hooks.
## Tesztek ## Tests
```sh ```sh
bundle install bundle install
bundle exec rake app:db:prepare RAILS_ENV=test # warp_engine_test DB a dummy apphoz bundle exec rake app:db:prepare RAILS_ENV=test # warp_engine_test DB for the dummy app
bundle exec rspec bundle exec rspec
``` ```