Refactor: Add version.json manifest support for mods with permanent version.txt fallback

[darknoon29]

Summary

Add an optional JSON manifest format for OGSpy mods. version.json should become the preferred metadata source while every existing version.txt mod continues to work indefinitely.

This is a metadata-format refactor: it must preserve the current mod install, update, enable/disable, cache, and routing behavior.

Current problem

Mod metadata is stored in a line-oriented version.txt file. Besides the displayed version, this format controls the values required to install and run a mod:

• display name
• version
• title, menu, action, root, link, active, and admin_only
• minimum supported OGSpy version
• optional toolbar version

The parser is repeated across the mod lifecycle and relies on positional lines, which makes metadata difficult to extend and validate safely.

Affected code paths

• includes/mod.php: mod_list(), mod_install(), mod_update(), install_mod(), and update_mod()
• model/Mod_Model.php: persists normalized version and routing metadata
• includes/cache.php: generate_mod_cache()
• views/admin_mod.php: install/update/listing controls
• index.php: mod action routing
• mod/*/version.txt: existing legacy manifests

Proposed contract

1. A mod may provide version.json at its root.
2. When present, version.json is the authoritative metadata source.
3. When version.json is absent, OGSpy reads the existing version.txt format exactly as today. This fallback is permanent; no deprecation deadline is introduced.
4. When version.json exists but is malformed or lacks required values, mod discovery/install/update must produce a controlled, logged metadata error. Do not silently fall back to version.txt in that situation.
5. Both formats are normalized to the same internal metadata structure before database, cache, and routing code consumes them.

Manifest shape

Define and document a versioned schema. It must include the current required metadata, for example:

{
  "name": "Production",
  "version": "1.6.0",
  "config": {
    "title": "production",
    "menu": "production",
    "action": "production",
    "root": "production",
    "link": "production.php",
    "active": true,
    "admin_only": false
  },
  "requirements": {
    "ogspy": ">=3.3.8"
  }
}

Optional typed metadata may include description, authors, license, homepage, requirements.php, requirements.extensions, toolbar_min_version, and a changelog.

Acceptance criteria

• Define and document the version.json schema, required fields, value types, and validation errors.
• Extract duplicated metadata parsing from includes/mod.php into one reader/validator that returns normalized metadata.
• Update mod_list(), mod_install(), mod_update(), install_mod(), and update_mod() to use the normalized reader.
• Verify that equivalent JSON and legacy manifests produce identical database rows and mod-cache entries.
• Preserve update detection, minimum OGSpy-version checks, active/disabled state, admin-only access, and action routing.
• Log and reject malformed or incomplete version.json instead of falling back when that file exists.
• Add focused automated tests for valid JSON listing/install/update, legacy fallback, malformed JSON, missing fields, and incompatible OGSpy versions.
• Provide an example manifest and conversion/documentation guidance for mod maintainers.

Explicit non-goals

• Do not remove version.txt or schedule a deprecation date.
• Do not change the ogspy_mod database schema.
• Do not add automatic resolution or installation of inter-mod dependencies.
• Do not redesign the administration UI or alter normal install/update/uninstall workflows.

Implementation notes

Migrate bundled mods only where conversion can be mechanically verified. It is acceptable for bundled legacy mods to keep version.txt while the new parser, documentation, tests, and a representative version.json example are introduced.