Move Red's extracted cache under red/ with a legacy migration

Importing Red unpacked data/generated, assets/generated and
rom-cache.complete straight into the save-dir root, while Blue and
Yellow land under blue/ and yellow/. Red now uses cachePrefix red/
like the others.

CacheFs.migrateLegacyRedCache moves a pre-existing root cache into
red/ on first boot, from RomImporter.new before the readiness loop
and from mountVersion, so existing installs keep their import instead
of being asked for the ROM again. The move only runs when the root
marker resolves to the save directory, so a dev checkout's source
tree is never touched, and the portable game folder is skipped when
it is the physfs source.

Closes #899

src/import/CacheFs.lua

@@ -33,11 +33,11 @@ local Platform = require("src.core.Platform")
 local SEP = package.config:sub(1, 1)
 
 -- Cache-relative paths are prefixed with this before every read/write, so a
--- Blue/Yellow import lands under its GameVersion.cachePrefix (blue/, yellow/)
--- while a Red import keeps the historical root.  The launcher sets it per
--- import / per readiness check; it stays "" for Red.  Runtime *reads*
--- (require / newImage) do NOT go through here -- CacheFs.mountVersion overlays
--- the active version's subtree onto the un-prefixed paths instead.
+-- version's import lands under its GameVersion.cachePrefix (red/, blue/,
+-- yellow/).  The launcher sets it per import / per readiness check; it stays
+-- "" outside those flows.  Runtime *reads* (require / newImage) do NOT go
+-- through here -- CacheFs.mountVersion overlays the active version's subtree
+-- onto the un-prefixed paths instead.
 CacheFs.prefix = ""
 
 local function withPrefix(rel)
@@ -383,17 +383,120 @@ function CacheFs.removeTree(rel)
   walk(rel)
 end
 
+-- One-time move of Red's pre-#899 cache (data/generated, assets/generated
+-- and the rom-cache.complete marker at the cache root) into red/, the
+-- layout Blue and Yellow always used.  Idempotent: an existing red/ cache
+-- wins and a missing root marker means nothing to do.
+--
+-- The two cache homes are handled separately: the save directory goes
+-- through love.filesystem so every host (NX included) and the headless test
+-- stub take the same path, and the portable game folder goes through
+-- os.rename on real paths -- skipped for a source run, where the game
+-- folder IS the checkout and its data/generated is Red's source data, not
+-- a cache.  Called from RomImporter.new (before the readiness loop) and
+-- from mountVersion, so no boot path can probe red/ before the move ran.
+function CacheFs.migrateLegacyRedCache()
+  if not (love and love.filesystem and love.filesystem.getInfo) then return end
+  local fs = love.filesystem
+
+  local function hasFile(p) return fs.getInfo(p, "file") ~= nil end
+  local function hasDir(p) return fs.getInfo(p, "directory") ~= nil end
+
+  local function moveFile(src, dst)
+    local data = fs.read(src)
+    if data then
+      local parent = dst:match("^(.*)/[^/]+$")
+      if parent and fs.createDirectory then fs.createDirectory(parent) end
+      fs.write(dst, data)
+    end
+    fs.remove(src)
+  end
+
+  local function moveTree(src, dst)
+    for _, child in ipairs(fs.getDirectoryItems(src) or {}) do
+      local sp, dp = src .. "/" .. child, dst .. "/" .. child
+      if hasDir(sp) then moveTree(sp, dp) else moveFile(sp, dp) end
+    end
+    -- remove only takes an empty directory; a non-empty one simply stays
+    fs.remove(src)
+  end
+
+  -- --- save directory
+  if hasDir("red/data/generated") or hasFile("red/rom-cache.complete") then
+    -- already on the new layout
+  elseif hasFile("rom-cache.complete") then
+    -- The marker must be a save-dir file before anything moves: a developer
+    -- checkout also resolves data/generated at the root, but from the physfs
+    -- SOURCE, and moving that tree would gut the repository.
+    local real = fs.getRealDirectory and fs.getRealDirectory("rom-cache.complete")
+    if not real or (fs.getSaveDirectory and real == fs.getSaveDirectory()) then
+      -- cheap path first: renames inside the same directory; the copy below
+      -- covers whatever rename could not take (or hosts where the save dir
+      -- is not a plain os path, like the headless stub)
+      local saveDir = fs.getSaveDirectory and fs.getSaveDirectory()
+      if saveDir and fs.createDirectory then
+        fs.createDirectory("red/data")
+        fs.createDirectory("red/assets")
+        os.rename(saveDir .. SEP .. "data" .. SEP .. "generated",
+                  saveDir .. SEP .. "red" .. SEP .. "data" .. SEP .. "generated")
+        os.rename(saveDir .. SEP .. "assets" .. SEP .. "generated",
+                  saveDir .. SEP .. "red" .. SEP .. "assets" .. SEP .. "generated")
+        os.rename(saveDir .. SEP .. "rom-cache.complete",
+                  saveDir .. SEP .. "red" .. SEP .. "rom-cache.complete")
+      end
+      if hasDir("data/generated") then
+        moveTree("data/generated", "red/data/generated")
+      end
+      if hasDir("assets/generated") then
+        moveTree("assets/generated", "red/assets/generated")
+      end
+      if hasFile("rom-cache.complete") then
+        moveFile("rom-cache.complete", "red/rom-cache.complete")
+      end
+      -- drop the emptied roots; a non-empty one (e.g. mods/ beside them is
+      -- untouched -- only data and assets are cache subtrees) simply stays
+      fs.remove("data")
+      fs.remove("assets")
+    end
+  end
+
+  -- --- portable game folder (desktop only): rename on real paths
+  local root = CacheFs.root()
+  if root and not (fs.getSource and root == fs.getSource()) then
+    local function rootHas(rel)
+      local f = io.open(realPath(root, rel), "rb")
+      if f then f:close() return true end
+      return false
+    end
+    if rootHas("rom-cache.complete") and not rootHas("red/rom-cache.complete") then
+      local mkdir = resolveMkdir()
+      if mkdir then
+        mkdir(realPath(root, "red"))
+        mkdir(realPath(root, "red/data"))
+        mkdir(realPath(root, "red/assets"))
+        os.rename(realPath(root, "data/generated"),
+                  realPath(root, "red/data/generated"))
+        os.rename(realPath(root, "assets/generated"),
+                  realPath(root, "red/assets/generated"))
+        os.rename(realPath(root, "rom-cache.complete"),
+                  realPath(root, "red/rom-cache.complete"))
+      end
+    end
+  end
+end
+
 -- Overlay the active version's extracted cache onto the un-prefixed read
 -- paths, so require("data.generated.*") and love.graphics.newImage(
 -- "assets/generated/*") resolve to that version's files.
 --
--- Non-Red versions live under blue/ / yellow/ in the save directory.  On
--- desktop fused+portable we PHYSFS_mount that folder by absolute path.  On
--- NX (and any host without a working FFI mount) love.filesystem.mount of
--- the save-dir-relative name must succeed, or Play boots with Red's paths
--- and Data:load dies.  Always also prepend-mount the version's
--- data/generated + assets/generated onto the un-prefixed paths so PhysFS
--- directory non-merge (archive data/ vs save generated) cannot hide them.
+-- Each version lives under its cachePrefix folder in the save directory.
+-- On desktop fused+portable we PHYSFS_mount that folder by absolute path.
+-- On NX (and any host without a working FFI mount) love.filesystem.mount
+-- of the save-dir-relative name must succeed, or Play boots with another
+-- version's paths and Data:load dies.  Always also prepend-mount the
+-- version's data/generated + assets/generated onto the un-prefixed paths
+-- so PhysFS directory non-merge (archive data/ vs save generated) cannot
+-- hide them.
 local function mountGeneratedTrees(prefix)
   prefix = prefix or ""
   if not (love and love.filesystem and love.filesystem.mount) then
@@ -416,10 +519,13 @@ local function mountGeneratedTrees(prefix)
 end
 
 function CacheFs.mountVersion(version)
+  -- A legacy root Red cache has to move into red/ before anything probes
+  -- red/ paths (idempotent and near-free once migrated, issue #899).
+  if version == "red" then CacheFs.migrateLegacyRedCache() end
   local prefix = require("src.core.GameVersion").cachePrefix(version)
   local sub = prefix:gsub("/+$", "")
 
-  -- Save-dir relative mount first (NX / no-FFI). Prepend so blue|yellow win.
+  -- Save-dir relative mount first (NX / no-FFI). Prepend so the version wins.
   if sub ~= "" and love.filesystem.mount
       and love.filesystem.getInfo(sub, "directory") then
     love.filesystem.mount(sub, "", false)
@@ -436,21 +542,21 @@ function CacheFs.mountVersion(version)
     end
   end
 
-  -- Version-scoped generated trees → un-prefixed paths (Red prefix is "").
+  -- Version-scoped generated trees → un-prefixed paths.
   mountGeneratedTrees(prefix)
   return true
 end
 
 -- Undo mountVersion.  A process normally mounts exactly one version and then
--- boots it, but the launcher can open the save editor on a Blue/Yellow save,
--- close it, and press Play on Red: with that version's subtree still
--- prepended, Red's require("data.generated.*") and its generated art would
--- silently resolve to the other game's files.  Callers must also drop the
--- generated modules from package.loaded (src.core.Data:unloadGenerated) --
--- unmounting alone only fixes the read path, not what require already cached.
+-- boots it, but the launcher can open the save editor on one game's save,
+-- close it, and press Play on another: with the first version's subtree
+-- still prepended, the other's require("data.generated.*") and generated
+-- art would silently resolve to the first game's files.  Callers must also
+-- drop the generated modules from package.loaded
+-- (src.core.Data:unloadGenerated) -- unmounting alone only fixes the read
+-- path, not what require already cached.
 --
--- Returns true when nothing was mounted or the unmount took.  Red is a no-op
--- because its cache lives at the root and was never overlaid.
+-- Returns true when nothing was mounted or the unmount took.
 function CacheFs.unmountVersion(version)
   local prefix = require("src.core.GameVersion").cachePrefix(version)
   if prefix == "" then return true end

src/import/RomImporter.lua

@@ -32,7 +32,7 @@ end
 -- carry Red's bank $1f header, wave-table, and CryData offsets.
 local CACHE_FORMAT = "rom-cache-v9:"
 -- The completion marker is written under each version's cache prefix
--- (rom-cache.complete for Red, blue/rom-cache.complete for Blue).
+-- (red/rom-cache.complete, blue/rom-cache.complete, ...).
 local MARKER_PATH = "rom-cache.complete"
 
 -- The marker a finished import writes for a version: the generation tag plus
@@ -135,8 +135,8 @@ local PAL = {
 
 -- CacheFs.exists checks the game folder directly for a portable install,
 -- otherwise the save directory through love.filesystem.  It honors
--- CacheFs.prefix, so we point it at the version's cache subtree (Red at the
--- root, Blue under blue/).
+-- CacheFs.prefix, so we point it at the version's cache subtree (red/,
+-- blue/, yellow/).
 local function allRequiredFilesExist(version)
   local CacheFs = require("src.import.CacheFs")
   local saved = CacheFs.prefix
@@ -153,11 +153,15 @@ local function allRequiredFilesExist(version)
 end
 
 -- A developer checkout / Python build leaves Red's generated data in the
--- physfs SOURCE at the un-prefixed root; that is always current.  Only Red
--- ships this way (Blue is import-only), so this stays a Red-root check.
+-- physfs SOURCE at the un-prefixed root (the checked-out data/generated and
+-- assets/generated); it is always current and never moves into red/.  Only
+-- Red ships this way (Blue/Yellow are import-only).  The check goes through
+-- love.filesystem directly so the red/ cache prefix cannot hide the source
+-- tree, and the realDirectory test keeps a save-dir cache from counting.
 local function sourceTreeHasData()
-  if not allRequiredFilesExist("red") or not love.filesystem.getRealDirectory then
-    return false
+  if not love.filesystem.getRealDirectory then return false end
+  for _, path in ipairs(REQUIRED_FILES) do
+    if love.filesystem.getInfo(path, "file") == nil then return false end
   end
   local real = love.filesystem.getRealDirectory(REQUIRED_FILES[1])
   return real == love.filesystem.getSource()
@@ -214,8 +218,8 @@ local function purgeSaveDirCache()
     f:close()
     return true
   end
-  -- Purge each version's stale save-directory copy (Red at the root, Blue
-  -- under blue/) so it cannot shadow the portable game-folder cache.
+  -- Purge each version's stale save-directory copy (under its red/ / blue/
+  -- / yellow/ prefix) so it cannot shadow the portable game-folder cache.
   for _, version in ipairs(GameVersion.ORDER) do
     local prefix = GameVersion.cachePrefix(version)
     if saveDirHas(prefix .. MARKER_PATH) or saveDirHas(prefix .. REQUIRED_FILES[1]) then
@@ -1121,6 +1125,11 @@ function RomImporter.new(onComplete, opts)
     _padInited = false,
   }, RomImporter)
 
+  -- Pre-#899 installs keep Red's extracted cache at the save-dir root; move
+  -- it under red/ before the readiness loop looks for red/ paths, or every
+  -- such install would read as "never imported" and demand the ROM again.
+  CacheFs.migrateLegacyRedCache()
+
   for _, version in ipairs(GameVersion.ORDER) do
     local info = GameVersion.info(version)
     local ready = RomImporter.isReady(version) and not self.forceImport