feat: update RomM package to 5.1.0

- pin the RomM 5.1.0 multi-architecture image
- mount the main volume at /romm for hardlink support
- update release notes, configuration text, and documentation
- replace the invalid icon with the official RomM isotipo
- ignore local AI workspace files and build artifacts

.ai-workspace/TODO.md

@@ -1,162 +0,0 @@
-# RomM for StartOS 0.4 — Rewrite TODO
-
-## Decision and scope
-
-Rewrite the package as a native StartOS 0.4 SDK-v2 service. The existing package never produced a working installation, so do **not** build an upgrade path from its StartOS 0.3-era manifest, configuration, database, or backups.
-
-The target is a clean installation of RomM. Existing users, if any, must install it as a new service and import their ROM library through a documented manual process.
-
-Initial application target: **RomM 3.5.0**, packaged as revision **`3.5.0:0`**. This keeps the application version stable while the wrapper is replaced. Upgrade RomM separately after the StartOS package works end to end.
-
-## Keep, replace, and discard
-
-### Keep as product requirements
-
-- Package identity: `romm`.
-- Service name, description, license attribution, upstream links, and useful user-facing prose after checking them for accuracy.
-- A persistent RomM library, resources, assets, configuration, and Redis data.
-- A browser UI exposed through one StartOS `ui` interface on RomM's internal port `8080`.
-- RomM's own authentication and first-run setup flow.
-- Useful provider credentials/settings only when they are supported by the selected RomM release.
-- Multi-architecture support for `x86_64` and `aarch64`.
-
-### Replace completely
-
-- `manifest.yaml` with `startos/manifest.ts` and SDK-v2 modules.
-- `scripts/embassy.ts` and its Deno/`embassyd` API with SDK-v2 actions, file models, interfaces, daemons, health checks, backups, and versions.
-- The custom source-build `Dockerfile` with pinned upstream multi-architecture images and small package-owned Dockerfiles only where necessary.
-- `docker_entrypoint.sh` with the upstream RomM image's `/init` process.
-- SQLite assumptions with a persistent MariaDB daemon.
-- Legacy `tor-config`/`lan-config` declarations with a StartOS 0.4 interface. Gateway availability is controlled by StartOS.
-- The empty `icon.png` with a valid icon no larger than 40 KiB.
-- The legacy Makefile with the SDK-v2 `s9pk.mk` build.
-
-### Do not carry forward
-
-- Legacy migration entries or compatibility code for `3.5.0.0`.
-- The old `.env` parser or shell-based `export $(...)` loading.
-- SQLite or `DATABASE_URL` configuration.
-- RAHasher/RetroAchievements code that is not part of the selected RomM release.
-- Unsupported ScreenScraper, scheduler, watcher, logging, Redis, or auth environment variables.
-- Claims that StartOS automatically authenticates the interface or provisions Tor access.
-- Old backups; StartOS 0.3 and 0.4 backups are not compatible.
-
-## Phase 1 — Create the native package skeleton
-
-- [x] Preserve the legacy files temporarily for reference; do not use them in the new build.
-- [x] Scaffold the package with the installed `start-cli s9pk init-package` workflow rather than copying another package wholesale.
-- [x] Use `/Users/alextab93/code/gitea-runner-startos/` only as an SDK-v2 structural reference.
-- [x] Add `package.json` and lockfile with `@start9labs/start-sdk` pinned to the workspace-supported 2.x version (currently `2.0.9`) and `@vercel/ncc`.
-- [x] Replace the Makefile with `ARCHES := x86 arm` and include `node_modules/@start9labs/start-sdk/s9pk.mk`.
-- [x] Create the standard current scaffold structure:
-  - [x] `startos/index.ts`
-  - [x] `startos/manifest/index.ts`
-  - [x] `startos/main.ts`
-  - [x] `startos/init/index.ts`
-  - [x] `startos/interfaces.ts`
-  - [x] `startos/actions/index.ts`
-  - [x] `startos/backups.ts`
-  - [x] `startos/fileModels/store.json.ts`
-  - [x] `startos/versions/index.ts`
-  - [x] `startos/versions/current.ts`
-  - [x] `startos/i18n/index.ts`
-  - [x] `assets/`
-- [x] Export the six required ABI functions from `startos/index.ts`: `createBackup`, `main`, `init`, `uninit`, `manifest`, and `actions`.
-- [x] Set the package version to `3.5.0:0`; there is no predecessor node because this is a clean rewrite.
-
-## Phase 2 — Define the runtime topology
-
-- [x] Pin `rommapp/romm:3.5.0` by immutable digest after verifying both `amd64` and `arm64` manifests.
-- [x] Use the upstream image entrypoint and `/init` command as PID 1; enable init semantics if required by the SDK.
-- [x] Do not rebuild RomM from source in this package.
-- [x] Add a pinned, multi-architecture MariaDB image as a second daemon.
-- [x] Create persistent storage with clear ownership:
-  - [x] RomM data mounted where the official image expects `/romm/library`, `/romm/resources`, `/romm/assets`, and `/romm/config`.
-  - [x] Embedded Redis data mounted at `/redis-data`.
-  - [x] MariaDB data mounted at `/var/lib/mysql`.
-- [x] Prefer separate StartOS volume IDs such as `main` and `database`; there is no legacy data-layout constraint.
-- [x] Generate MariaDB root password, application password, and `ROMM_AUTH_SECRET_KEY` once during initialization.
-- [x] Store secrets with typed SDK file models/store helpers; never regenerate them on a settings change.
-- [x] Pass only variables supported by RomM 3.5.0, including the MariaDB host, database, user, and password.
-- [x] Leave `REDIS_HOST` unset if the official RomM image is expected to manage its embedded Redis; do not pass an empty `REDIS_PORT`.
-- [x] Make the RomM daemon depend on MariaDB readiness.
-- [x] Run both containers with the least privilege compatible with their official initialization processes.
-
-## Phase 3 — Interface, health, and configuration
-
-- [x] Define one `MultiHost`/`createInterface` UI interface bound to internal port `8080`.
-- [x] Label it clearly as the RomM web interface and rely on RomM's native authentication.
-- [x] Do not hard-code Tor or LAN URLs; document that StartOS gateway choices control availability.
-- [x] Add MariaDB readiness using a database-native check or listening-port check.
-- [x] Add RomM readiness using `checkPortListening(8080)`; `/api/heartbeat` was also confirmed during the local runtime smoke test.
-- [x] Expose a small configuration action only for settings verified against the exact RomM 3.5.0 environment-variable documentation/source.
-- [x] Treat credentials as secrets in action inputs and stored files.
-- [x] Ensure values containing spaces, quotes, dollar signs, or newlines are passed through structured environment handling, never shell interpolation.
-- [x] Evaluate safe setup guidance: keep it in `instructions.md`; the action never prefills or reveals stored secrets.
-
-## Phase 4 — Backups and restore
-
-- [x] Back up the MariaDB database with the SDK MySQL/MariaDB dump helper.
-- [x] Back up RomM configuration and application-owned metadata.
-- [x] Include the ROM library in routine StartOS backups for complete restores; document that backups may be very large.
-- [x] Document an independent backup strategy for irreplaceable ROM files even though the library is included.
-- [x] Include Redis data as part of the complete `main` volume and document that choice.
-- [ ] Test restore into an empty service and verify database records, configuration, login, and library visibility.
-
-## Phase 5 — Documentation and assets
-
-- [x] Replace the zero-byte icon with an upstream-authorized PNG or SVG that meets StartOS size/format requirements.
-- [x] Repair or rewrite `README.md`; remove embedded NUL bytes and corrupted tree glyphs.
-- [x] Rewrite `instructions.md` for a clean StartOS 0.4 install.
-- [x] Document the RomM first-run administrator setup.
-- [x] Document required storage, supported gateways, native RomM authentication, provider credentials, and backup limitations accurately.
-- [x] Add a clear statement that the abandoned StartOS 0.3 package is not upgrade-compatible and its backups cannot be restored into this package.
-- [x] Include a manual ROM import guide for users who experimented with the old wrapper.
-- [x] Record all image tags and immutable digests used by the package.
-
-## Phase 6 — Remove the abandoned wrapper
-
-Removed after native build/pack and isolated runtime validation. Full StartOS installation testing remains explicitly unchecked below.
-
-- [x] Remove `manifest.yaml`.
-- [x] Remove `scripts/embassy.ts` and the generated legacy JavaScript, if present.
-- [x] Remove `docker_entrypoint.sh`.
-- [x] Remove the old custom `Dockerfile`, unless a new minimal package Dockerfile intentionally replaces it.
-- [x] Remove `icon_note.txt` after installing the real icon.
-- [x] Remove obsolete documentation and unsupported configuration references.
-- [x] Confirm source and user documentation contain no references to `embassyd`, `DATABASE_URL`, SQLite, RAHasher, `REDIS_PORT=`, legacy `tor-config`, or legacy `lan-config` (the historical checklist wording is excluded from this search).
-
-## Validation gates
-
-Do not mark the rewrite complete until every applicable gate passes.
-
-- [x] Install dependencies reproducibly from the committed lockfile (`npm ci`).
-- [x] Type-check and bundle `startos/index.ts` to `javascript/index.js`.
-- [x] Run `start-cli s9pk list-ingredients .` successfully.
-- [x] Build the package for both `x86_64` and `aarch64`.
-- [x] Pack and verify the `.s9pk` with the current StartOS tooling.
-- [x] Inspect both packed artifacts: SDK `2.0.9`, package `3.5.0:0`, target-specific packed images, `main`/`database` volumes, six ABI exports, one UI interface in bundled source, and no additional package permissions.
-- [ ] Install on a clean StartOS 0.4 system.
-- [x] Verify the pinned MariaDB runtime initializes once and survives service restart (isolated ARM64 runtime smoke test).
-- [x] Verify the pinned RomM runtime reaches ready state, completes first-run admin setup, and serves the browser UI (isolated ARM64 runtime smoke test).
-- [ ] Verify login, logout, session persistence, and secret persistence across configuration changes and restarts.
-- [ ] Import a small representative ROM set and verify scan, metadata, artwork, launch/download paths, and background workers.
-- [ ] Exercise stop/start, reboot, update-to-same-build, backup, restore, and uninstall/reinstall behavior.
-- [ ] Verify both Tor and LAN access only through gateways enabled by the StartOS administrator.
-- [ ] Repeat smoke tests on both supported CPU architectures.
-
-### Current external validation blocker
-
-- The configured StartOS development host is `https://dev-vm.local`, but it is currently unreachable from this workstation. The install and appliance-only checks above must stay unchecked until a StartOS 0.4 host is online and authenticated.
-- Local ARM64 container smoke test completed: MariaDB initialized 11 RomM schema tables, `/api/heartbeat` reported RomM `3.5.0`, every declared persistent mount was writable, and database/library state survived restart. A real administrator was created through RomM's CSRF-protected first-run API, the UI root returned HTML, login and authenticated identity succeeded, the same session remained valid after restart with the fixed auth secret, logout invalidated the session, and the setup wizard switched off.
-- The packaging repository URLs available from the abandoned manifest and local username do not currently resolve on GitHub. Confirm the final repository URL before publishing.
-
-## Definition of done
-
-- A clean StartOS 0.4 install starts RomM and MariaDB without manual shell intervention.
-- The UI is reachable through the declared StartOS interface and protected by RomM authentication.
-- Persistent data and generated secrets survive restarts and configuration changes.
-- Backup and restore behavior is tested and documented, including any ROM-library exclusion.
-- The package builds reproducibly for both architectures and passes StartOS pack/verify checks.
-- Documentation describes only behavior confirmed on a real StartOS 0.4 installation.
-- No runtime or packaging dependency remains on the abandoned StartOS 0.3 wrapper.

.ai-workspace/UPDATING.md

@@ -1,15 +0,0 @@
-# Updating RomM
-
-This package intentionally begins with RomM `3.5.0` so the StartOS wrapper can be validated independently from an application upgrade.
-
-For a future update:
-
-1. Read the RomM release and database migration notes.
-2. Verify the image tag and both `amd64` and `arm64` manifests.
-3. Pin the new multi-architecture digest in `startos/manifest/index.ts`.
-4. Reinspect the entrypoint, ports, volumes, users, and environment variables.
-5. Update `startos/versions/current.ts`; add a historical node only for an explicit package migration.
-6. Update README and instructions for user-visible behavior.
-7. Test install, upgrade, login, scan, restart, backup, and restore on StartOS.
-
-Do not restore compatibility with the abandoned StartOS 0.3 wrapper.

.gitignore

@@ -1,6 +1,8 @@
 node_modules/
 javascript/
-docker-images/
 *.s9pk
 *.s9pk.*
 result
+
+.ai-workspace
+.DS_Store

README.md

@@ -1,12 +1,12 @@
 # RomM for StartOS
 
-This repository packages [RomM](https://github.com/rommapp/romm) 3.5.0 as a native StartOS 0.4 SDK-v2 service.
+This repository packages [RomM](https://github.com/rommapp/romm) 5.1.0 as a native StartOS 0.4 SDK-v2 service.
 
 RomM scans, enriches, browses, and manages a personal game library from a web interface. This package uses the official RomM container and a private MariaDB sidecar. RomM's bundled Redis instance, web server, migrations, watcher, worker, and scheduler are started by the upstream `/init` process.
 
 ## Architecture
 
-- `rommapp/romm:3.5.0` serves the UI on internal port `8080`.
+- `rommapp/romm:5.1.0` serves the UI on internal port `8080`.
 - `mariadb:11.4.5` stores RomM metadata on internal port `3306`.
 - The daemons share the service network namespace; MariaDB listens only inside the package.
 - RomM starts only after the MariaDB health check succeeds.
@@ -15,9 +15,9 @@ RomM scans, enriches, browses, and manages a personal game library from a web in
 
 ## Persistent data
 
-The `main` volume contains `library/`, `resources/`, `assets/`, `config/`, `redis-data/`, and the package's `store.json`. The `database` volume contains MariaDB at `/var/lib/mysql`.
+The entire `main` volume is mounted at `/romm` and contains `library/`, `resources/`, `assets/`, `config/`, `redis-data/`, and the package's `store.json`. Mounting the parent volume is required by RomM 5.1.0 so hardlinks across its application directories remain on one filesystem. The same `redis-data/` subpath is also mounted at `/redis-data`. The `database` volume contains MariaDB at `/var/lib/mysql`.
 
-Internal MariaDB credentials and `ROMM_AUTH_SECRET_KEY` are generated once during a clean install. The Configure Metadata Providers action stores the exact optional variables supported by RomM 3.5.0: `IGDB_CLIENT_ID`, `IGDB_CLIENT_SECRET`, `MOBYGAMES_API_KEY`, and `STEAMGRIDDB_API_KEY`.
+Internal MariaDB credentials and `ROMM_AUTH_SECRET_KEY` are generated once during a clean install. The Configure Metadata Providers action stores supported optional variables: `IGDB_CLIENT_ID`, `IGDB_CLIENT_SECRET`, `MOBYGAMES_API_KEY`, and `STEAMGRIDDB_API_KEY`.
 
 ## Backups
 
@@ -31,7 +31,7 @@ This is a clean rewrite. The abandoned StartOS 0.3 wrapper never formed a suppor
 
 Both images are pinned to immutable multi-architecture OCI indexes:
 
-- `rommapp/romm:3.5.0@sha256:9ff83725e98e5dfc0b871cb88ca378c539fad66b7afcbe6aad562d2b84d5b802`
+- `rommapp/romm:5.1.0@sha256:ce9d86ab531e09fede45d00f426e3bf2d1f5dd14846f94d6360d77a92a413028`
 - `mariadb:11.4.5@sha256:49117dcc565cf51aa57ac5fca59ab31213402ff0eae6ffc13c46a37b938f7e4b`
 
 The verified Linux platforms are `amd64` and `arm64`.

docker-images/mariadb/Dockerfile

@@ -0,0 +1,10 @@
+FROM mariadb:11.4.5@sha256:49117dcc565cf51aa57ac5fca59ab31213402ff0eae6ffc13c46a37b938f7e4b
+
+# start-sdk 2.0.9's logical backup helper invokes the legacy MySQL command
+# names. MariaDB 11.4 ships only mariadb-* names, so expose compatibility
+# aliases until these commands are configurable by the SDK.
+RUN ln -s /usr/bin/mariadb-admin /usr/local/bin/mysqladmin \
+    && ln -s /usr/bin/mariadb-dump /usr/local/bin/mysqldump \
+    && ln -s /usr/bin/mariadb /usr/local/bin/mysql \
+    && ln -s /usr/bin/mariadb-install-db /usr/local/bin/mysql_install_db \
+    && ln -s /usr/sbin/mariadbd /usr/local/bin/mysqld

instructions.md

@@ -17,7 +17,9 @@ RomM works without external metadata credentials, but enrichment is limited. Run
 
 ## Importing ROMs
 
-Place files in the library using the folder layout documented for RomM 3.5.0, then start a scan from the RomM web interface. Test with a small library before copying a large collection.
+Place files in the library using the folder layout documented for RomM 5.1.0, then start a scan from the RomM web interface. Test with a small library before copying a large collection.
+
+RomM 5.1.0 may use hardlinks between its library and asset directories. Keep all RomM application data in the package-managed storage; do not replace individual `/romm` subdirectories with unrelated external filesystems.
 
 If you experimented with the abandoned StartOS 0.3 wrapper, do not copy its database, `.env`, Redis data, or backup. Copy only ROM files into a clean installation and let RomM rebuild its metadata.
 

startos/actions/configure.ts

@@ -39,7 +39,7 @@ export const configure = sdk.Action.withInput(
   async () => ({
     name: i18n('Configure Metadata Providers'),
     description: i18n(
-      'Save optional API credentials supported by RomM 3.5.0.',
+      'Save optional API credentials supported by RomM 5.1.0.',
     ),
     warning: i18n(
       'Saved values are passed to RomM after the service is restarted. Leave a field blank to remove it.',

startos/i18n/dictionaries/default.ts

@@ -18,7 +18,7 @@ const dict = {
   'SteamGridDB API Key': 14,
   'Optional API key used to retrieve SteamGridDB artwork.': 15,
   'Configure Metadata Providers': 16,
-  'Save optional API credentials supported by RomM 3.5.0.': 17,
+  'Save optional API credentials supported by RomM 5.1.0.': 17,
   'Saved values are passed to RomM after the service is restarted. Leave a field blank to remove it.': 18,
   'Configuration Saved': 19,
   'Restart RomM to apply the metadata provider configuration.': 20,

startos/main.ts

@@ -5,7 +5,8 @@ import {
   databaseName,
   databasePort,
   databaseUser,
-  mainMounts,
+  mainMountpoint,
+  redisMountpoint,
   uiPort,
 } from './utils'
 
@@ -37,32 +38,14 @@ export const main = sdk.setupMain(async ({ effects }) => {
     sdk.Mounts.of()
       .mountVolume({
         volumeId: 'main',
-        subpath: 'library',
+        subpath: null,
-        mountpoint: mainMounts.library,
+        mountpoint: mainMountpoint,
-        readonly: false,
-      })
-      .mountVolume({
-        volumeId: 'main',
-        subpath: 'resources',
-        mountpoint: mainMounts.resources,
-        readonly: false,
-      })
-      .mountVolume({
-        volumeId: 'main',
-        subpath: 'assets',
-        mountpoint: mainMounts.assets,
-        readonly: false,
-      })
-      .mountVolume({
-        volumeId: 'main',
-        subpath: 'config',
-        mountpoint: mainMounts.config,
         readonly: false,
       })
       .mountVolume({
         volumeId: 'main',
         subpath: 'redis-data',
-        mountpoint: mainMounts.redis,
+        mountpoint: redisMountpoint,
         readonly: false,
       }),
     'romm-app-sub',

startos/manifest/index.ts

@@ -15,14 +15,15 @@ export const manifest = setupManifest({
     romm: {
       source: {
         dockerTag:
-          'rommapp/romm:3.5.0@sha256:9ff83725e98e5dfc0b871cb88ca378c539fad66b7afcbe6aad562d2b84d5b802',
+          'rommapp/romm:5.1.0@sha256:ce9d86ab531e09fede45d00f426e3bf2d1f5dd14846f94d6360d77a92a413028',
       },
       arch: ['x86_64', 'aarch64'],
     },
     mariadb: {
       source: {
-        dockerTag:
+        dockerBuild: {
-          'mariadb:11.4.5@sha256:49117dcc565cf51aa57ac5fca59ab31213402ff0eae6ffc13c46a37b938f7e4b',
+          workdir: 'docker-images/mariadb',
+        },
       },
       arch: ['x86_64', 'aarch64'],
     },

startos/utils.ts

@@ -4,10 +4,5 @@ export const uiHostId = 'ui'
 export const databaseName = 'romm'
 export const databaseUser = 'romm'
 
-export const mainMounts = {
+export const mainMountpoint = '/romm'
-  library: '/romm/library',
+export const redisMountpoint = '/redis-data'
-  resources: '/romm/resources',
-  assets: '/romm/assets',
-  config: '/romm/config',
-  redis: '/redis-data',
-} as const

startos/versions/current.ts

@@ -1,13 +1,18 @@
 import { IMPOSSIBLE, VersionInfo } from '@start9labs/start-sdk'
 
 export const current = VersionInfo.of({
-  version: '3.5.0:0',
+  version: '5.1.0:0',
   releaseNotes: {
-    en_US: 'Initial native StartOS 0.4 package for RomM 3.5.0.',
+    en_US:
-    es_ES: 'Paquete nativo inicial de StartOS 0.4 para RomM 3.5.0.',
+      'Updates RomM to 5.1.0 with the redesigned UI, security fixes, enhanced library scanning, and native support for cross-directory hardlinks.',
-    de_DE: 'Erstes natives StartOS-0.4-Paket für RomM 3.5.0.',
+    es_ES:
-    pl_PL: 'Pierwszy natywny pakiet StartOS 0.4 dla RomM 3.5.0.',
+      'Actualiza RomM a 5.1.0 con la interfaz rediseñada, correcciones de seguridad, escaneo mejorado y soporte nativo para enlaces físicos entre directorios.',
-    fr_FR: 'Premier paquet StartOS 0.4 natif pour RomM 3.5.0.',
+    de_DE:
+      'Aktualisiert RomM auf 5.1.0 mit neuer Oberfläche, Sicherheitskorrekturen, verbessertem Bibliotheksscan und nativer Unterstützung für verzeichnisübergreifende Hardlinks.',
+    pl_PL:
+      'Aktualizuje RomM do 5.1.0 z przeprojektowanym interfejsem, poprawkami bezpieczeństwa, ulepszonym skanowaniem i obsługą dowiązań twardych między katalogami.',
+    fr_FR:
+      'Met RomM à jour vers 5.1.0 avec une interface repensée, des correctifs de sécurité, une analyse améliorée et la prise en charge des liens physiques entre répertoires.',
   },
   migrations: {
     up: async () => {},