Normalize shared manifest loader to remove Asteroids-specific coupling

BUILD_PR_LEVEL_10_10_SHARED_MANIFEST_LOADER_NORMALIZATION

Author: DavidQ

asteroids.txt

@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
-REASONING: medium
-COMMAND: Implement manifest loader that reads asteroids.asset.manifest.json and exposes discovery API without modifying engine core
+REASONING: high
+COMMAND: Normalize shared manifest loader to be game-agnostic, rename file and APIs, parameterize gameId, update tests accordingly

docs/dev/CODEX_COMMANDS.md

@@ -1,2 +1,2 @@
-Define Asteroids manifest loader integration contract
-BUILD_PR_LEVEL_10_09_ASTEROIDS_MANIFEST_LOADER_INTEGRATION
+Normalize shared manifest loader to remove Asteroids-specific coupling
+BUILD_PR_LEVEL_10_10_SHARED_MANIFEST_LOADER_NORMALIZATION

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_10_10_ASTEROIDS_MANIFEST_RUNTIME_HOOK
+BUILD_PR_LEVEL_10_11_ASTEROIDS_MANIFEST_RUNTIME_HOOK

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-Defined loader integration contract
+Identified and corrected shared pipeline coupling issue

docs/dev/reports/change_summary.txt

@@ -1,3 +1,3 @@
-- Contract defined
-- Codex command present
-- No engine changes
+- No game-specific naming in shared loader
+- API parameterized
+- Tests updated

docs/dev/reports/validation_checklist.txt

@@ -0,0 +1,38 @@
+# BUILD_PR_LEVEL_10_10_SHARED_MANIFEST_LOADER_NORMALIZATION
+
+## Problem
+Shared pipeline loader is incorrectly scoped to Asteroids:
+- Filename includes "asteroids"
+- API names are game-specific
+- Hardcoded path to Asteroids assets
+
+This violates shared pipeline contract.
+
+## Purpose
+Normalize loader to be game-agnostic.
+
+## Scope
+- Rename loader to generic name
+- Replace Asteroids-specific API with generic API
+- Parameterize game path input
+
+## Required Changes (Codex)
+- Rename:
+  tools/shared/pipeline/asteroidsAssetManifestLoader.js
+  → tools/shared/pipeline/assetManifestLoader.js
+
+- Replace API:
+  loadAsteroidsAssetManifest → loadAssetManifest(gameId, options?)
+  discoverAsteroidsRuntimeAssets → discoverRuntimeAssets(gameId, options?)
+
+- Remove hardcoded path:
+  games/Asteroids/assets/...
+  → games/<gameId>/assets/...
+
+## Testable Outcome
+- Loader works for Asteroids via parameter
+- No game-specific naming remains
+- Existing Asteroids test updated to pass gameId
+
+## Non-Goals
+- No engine modification

docs/pr/BUILD_PR_LEVEL_10_10_SHARED_MANIFEST_LOADER_NORMALIZATION.md

@@ -1,28 +1,36 @@
 import assert from "node:assert/strict";
 import {
-  ASTEROIDS_ASSET_MANIFEST_RELATIVE_PATH,
-  discoverAsteroidsRuntimeAssets,
-  loadAsteroidsAssetManifest
-} from "../../tools/shared/pipeline/asteroidsAssetManifestLoader.js";
+  discoverRuntimeAssets,
+  getAssetManifestRelativePath,
+  loadAssetManifest
+} from "../../tools/shared/pipeline/assetManifestLoader.js";
 
 function normalizePath(value) {
   return String(value || "").replace(/\\/g, "/");
 }
 
 export async function run() {
-  const loaded = await loadAsteroidsAssetManifest();
+  const gameId = "Asteroids";
+  const loaded = await loadAssetManifest(gameId);
   assert.equal(loaded.status, "ready");
   assert.equal(Array.isArray(loaded.issues), true);
   assert.equal(loaded.issues.length, 0);
   assert.equal(loaded.manifest.gameId, "asteroids");
-  assert.equal(normalizePath(loaded.manifestPath).endsWith(ASTEROIDS_ASSET_MANIFEST_RELATIVE_PATH), true);
+  assert.equal(
+    normalizePath(loaded.manifestPath).endsWith(getAssetManifestRelativePath(gameId)),
+    true
+  );
 
-  const discovered = await discoverAsteroidsRuntimeAssets();
+  const discovered = await discoverRuntimeAssets(gameId);
   assert.equal(discovered.status, "ready");
   assert.equal(discovered.issues.length, 0);
   assert.equal(Object.keys(discovered.runtimeAssetSources).length > 0, true);
   assert.equal(
     discovered.runtimeAssetSources["vector.asteroids.ship"].file.includes("/data/"),
     false
   );
+
+  const missingGameId = await loadAssetManifest("");
+  assert.equal(missingGameId.status, "invalid");
+  assert.equal(missingGameId.issues.includes("gameId is required."), true);
 }

…ls/AsteroidsAssetManifestLoader.test.mjs tests/tools/AssetManifestLoader.test.mjstests/tools/AsteroidsAssetManifestLoader.test.mjs renamed to tests/tools/AssetManifestLoader.test.mjs tests/tools/AsteroidsAssetManifestLoader.test.mjs renamed to tests/tools/AssetManifestLoader.test.mjs

@@ -6,16 +6,18 @@ import {
   validateGameAssetManifestStructure
 } from "./gameAssetManifestDiscovery.js";
 
-export const ASTEROIDS_ASSET_MANIFEST_RELATIVE_PATH = "games/Asteroids/assets/asteroids.asset.manifest.json";
-
 const MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(MODULE_DIRECTORY, "../../../");
 
-function toManifestPath(options = {}) {
+function toManifestPath(gameId, options = {}) {
   if (typeof options.manifestPath === "string" && options.manifestPath.trim()) {
     return path.resolve(options.manifestPath);
   }
-  return path.resolve(REPO_ROOT, ASTEROIDS_ASSET_MANIFEST_RELATIVE_PATH);
+  return path.resolve(REPO_ROOT, getAssetManifestRelativePath(gameId));
+}
+
+function toGameId(gameId) {
+  return String(gameId || "").trim();
 }
 
 async function readManifestJson(manifestPath) {
@@ -26,8 +28,27 @@ async function readManifestJson(manifestPath) {
   };
 }
 
-export async function loadAsteroidsAssetManifest(options = {}) {
-  const manifestPath = toManifestPath(options);
+export function getAssetManifestRelativePath(gameId) {
+  const normalizedGameId = toGameId(gameId);
+  if (!normalizedGameId) {
+    throw new Error("gameId is required to resolve asset manifest path.");
+  }
+  return `games/${normalizedGameId}/assets/${normalizedGameId.toLowerCase()}.asset.manifest.json`;
+}
+
+export async function loadAssetManifest(gameId, options = {}) {
+  const normalizedGameId = toGameId(gameId);
+  if (!normalizedGameId) {
+    return {
+      status: "invalid",
+      manifestPath: "",
+      manifest: null,
+      discovery: null,
+      issues: ["gameId is required."]
+    };
+  }
+
+  const manifestPath = toManifestPath(normalizedGameId, options);
   let payload;
   try {
     payload = await readManifestJson(manifestPath);
@@ -37,11 +58,13 @@ export async function loadAsteroidsAssetManifest(options = {}) {
       manifestPath,
       manifest: null,
       discovery: null,
-      issues: [error instanceof Error ? error.message : "Failed to read Asteroids asset manifest."]
+      issues: [error instanceof Error ? error.message : "Failed to read game asset manifest."]
     };
   }
 
-  const validation = validateGameAssetManifestStructure(payload.manifest, { gameId: "asteroids" });
+  const validation = validateGameAssetManifestStructure(payload.manifest, {
+    gameId: normalizedGameId.toLowerCase()
+  });
   if (!validation.valid) {
     return {
       status: "invalid",
@@ -52,7 +75,9 @@ export async function loadAsteroidsAssetManifest(options = {}) {
     };
   }
 
-  const discovery = discoverRuntimeAssetSourcesFromManifest(payload.manifest, { gameId: "asteroids" });
+  const discovery = discoverRuntimeAssetSourcesFromManifest(payload.manifest, {
+    gameId: normalizedGameId.toLowerCase()
+  });
   return {
     status: discovery.status,
     manifestPath,
@@ -62,8 +87,8 @@ export async function loadAsteroidsAssetManifest(options = {}) {
   };
 }
 
-export async function discoverAsteroidsRuntimeAssets(options = {}) {
-  const loaded = await loadAsteroidsAssetManifest(options);
+export async function discoverRuntimeAssets(gameId, options = {}) {
+  const loaded = await loadAssetManifest(gameId, options);
   if (loaded.status !== "ready") {
     return {
       status: "invalid",