@forgeax/engine-project 0.0.0-dev.8d955ade1c79

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@forgeax/engine-project",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Game-project SSOT — zod schema + injectable loader + resolve layer for forge.json, the authoritative game manifest contract.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-pack": "0.0.0-dev.8d955ade1c79",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.3",
+    "vitest": "4.1.5"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "pure data/contract package; no runtime canvas or frame loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "no perf-critical hot path in contract layer; throughput not instrumented"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "package-level gate scripts declared in engine CI yaml directly; no standalone binary gate"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/__tests__/ac14-migration.test.ts

@@ -0,0 +1,124 @@
+// ac14-migration.test.ts — w23: AC-14 integration — all 6 migrated forge.json pass loadGameProject
+//
+// Loads each migrated game's forge.json via node:fs readFileSync adapter,
+// asserts r.ok===true, verifies schemaVersion/defaultScene/entry per D-3 GUID table.
+// This is the R-3 risk closure evidence (plan-strategy section 4 R-3, section 5.4).
+//
+// Fixture approach: 6 migrated forge.json copies live under __tests__/fixtures/games/
+// (plan w23 description secondary path: the live paths under packages/games/ use a
+// Chinese directory name that triggers the engine english-only gate; fixtures avoid
+// the CJK path literal while testing the same post-migration forge.json content).
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { loadGameProject } from '../loader.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const fixturesDir = resolve(__dirname, 'fixtures/games');
+
+function fsRead(filePath: string): (path: string) => Promise<string> {
+  return async () => readFileSync(filePath, 'utf-8');
+}
+
+interface GameFixture {
+  name: string;
+  dir: string;
+  hasDefaultScene: boolean;
+  expectedDefaultScene?: string;
+  expectedEntry?: string;
+}
+
+// 6 migrated games per D-3 GUID table (plan-strategy section 2)
+// Fixture dirs use romanized names (original Chinese dir -> cow-level)
+const GAMES: GameFixture[] = [
+  {
+    name: 'hellforge',
+    dir: 'hellforge',
+    hasDefaultScene: true,
+    expectedDefaultScene: '15acc839-d847-527c-8284-bfb36d7c50de',
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'cow-survivor',
+    dir: 'cow-survivor',
+    hasDefaultScene: true,
+    expectedDefaultScene: '7b4d43d4-5b19-5903-8966-f89671d21565',
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'spin-cube',
+    dir: 'spin-cube',
+    hasDefaultScene: false,
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'cow-level',
+    dir: 'cow-level',
+    hasDefaultScene: false,
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'fps',
+    dir: 'fps',
+    hasDefaultScene: false,
+    expectedEntry: 'main.ts',
+  },
+  {
+    name: 'shoot-opt',
+    dir: 'shoot-opt',
+    hasDefaultScene: false,
+    expectedEntry: 'src/main.ts',
+  },
+];
+
+describe('AC-14 — migrated game forge.json validation', () => {
+  for (const game of GAMES) {
+    const forgePath = resolve(fixturesDir, game.dir, 'forge.json');
+
+    describe(game.name, () => {
+      it('loads successfully (r.ok === true)', async () => {
+        const result = await loadGameProject(fsRead(forgePath));
+        expect(result.ok).toBe(true);
+      });
+
+      it('has schemaVersion === "1.0.0"', async () => {
+        const result = await loadGameProject(fsRead(forgePath));
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+          expect(result.value.schemaVersion).toBe('1.0.0');
+        }
+      });
+
+      if (game.hasDefaultScene) {
+        it(`has defaultScene === "${game.expectedDefaultScene}"`, async () => {
+          const result = await loadGameProject(fsRead(forgePath));
+          expect(result.ok).toBe(true);
+          if (result.ok) {
+            expect(result.value.defaultScene).toBe(game.expectedDefaultScene);
+          }
+        });
+      } else {
+        it('has no defaultScene (undefined)', async () => {
+          const result = await loadGameProject(fsRead(forgePath));
+          expect(result.ok).toBe(true);
+          if (result.ok) {
+            expect(result.value.defaultScene).toBeUndefined();
+          }
+        });
+      }
+
+      if (game.expectedEntry) {
+        it(`has entry === "${game.expectedEntry}"`, async () => {
+          const result = await loadGameProject(fsRead(forgePath));
+          expect(result.ok).toBe(true);
+          if (result.ok) {
+            expect(result.value.entry).toBe(game.expectedEntry);
+          }
+        });
+      }
+    });
+  }
+});

package/src/__tests__/errors.test-d.ts

@@ -0,0 +1,69 @@
+import type { GameProjectError as GameProjectErrorType } from '../index.js';
+import { GameProjectError } from '../index.js';
+
+const positiveErrors: GameProjectErrorType[] = [
+  new GameProjectError({
+    code: 'forge-missing',
+    expected: 'forge.json to exist',
+    hint: 'create forge.json',
+    detail: { path: 'forge.json' },
+  }),
+  new GameProjectError({
+    code: 'forge-parse-failed',
+    expected: 'valid JSON',
+    hint: 'fix JSON',
+    detail: { path: 'forge.json', rawMessage: 'Unexpected token' },
+  }),
+  new GameProjectError({
+    code: 'forge-schema-invalid',
+    expected: 'schema-valid JSON',
+    hint: 'fix fields',
+    detail: { path: 'forge.json', zodErrors: [] },
+  }),
+  new GameProjectError({
+    code: 'forge-unknown-field',
+    expected: 'known fields',
+    hint: 'remove the field',
+    detail: { path: 'forge.json', fieldNames: ['scenes'] },
+  }),
+  new GameProjectError({
+    code: 'forge-guid-malformed',
+    expected: 'a valid GUID',
+    hint: 'use a scene GUID',
+    detail: { field: 'defaultScene', rawInput: 'not-a-guid' },
+  }),
+  new GameProjectError({
+    code: 'forge-scene-unresolved',
+    expected: 'a resolvable scene',
+    hint: 'check the scene pack',
+    detail: { guid: '15acc839-d847-527c-8284-bfb36d7c50de' },
+  }),
+];
+
+new GameProjectError({
+  code: 'forge-guid-malformed',
+  expected: 'a valid GUID',
+  hint: 'use a scene GUID',
+  // @ts-expect-error code/detail pairs remain correlated.
+  detail: { path: 'forge.json' },
+});
+
+function describe(error: GameProjectErrorType): string {
+  switch (error.code) {
+    case 'forge-missing':
+      return error.detail.path;
+    case 'forge-parse-failed':
+      return error.detail.rawMessage;
+    case 'forge-schema-invalid':
+      return String(error.detail.zodErrors.length);
+    case 'forge-unknown-field':
+      return error.detail.fieldNames.join(',');
+    case 'forge-guid-malformed':
+      return error.detail.rawInput;
+    case 'forge-scene-unresolved':
+      return error.detail.guid;
+  }
+}
+
+void positiveErrors;
+void describe;

package/src/__tests__/errors.test.ts

@@ -0,0 +1,233 @@
+// errors.test.ts — w3: GameProjectError code union exhaustive tests
+import { describe, expect, it } from 'vitest';
+import type { GameProjectErrorCode, GameProjectErrorDetail } from '../errors.js';
+import { GameProjectError } from '../errors.js';
+
+// ── helper ───────────────────────────────────────────────────────────────────
+function makeErr(): GameProjectError {
+  return new GameProjectError({
+    code: 'forge-missing',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json' },
+  });
+}
+
+const errors: GameProjectError[] = [
+  new GameProjectError({
+    code: 'forge-missing',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json' },
+  }),
+  new GameProjectError({
+    code: 'forge-parse-failed',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json', rawMessage: 'invalid JSON' },
+  }),
+  new GameProjectError({
+    code: 'forge-schema-invalid',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json', zodErrors: [] },
+  }),
+  new GameProjectError({
+    code: 'forge-unknown-field',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { path: '/fake/forge.json', fieldNames: ['scenes'] },
+  }),
+  new GameProjectError({
+    code: 'forge-guid-malformed',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { field: 'defaultScene', rawInput: 'bad-guid', cause: new Error('bad GUID') },
+  }),
+  new GameProjectError({
+    code: 'forge-scene-unresolved',
+    expected: 'test expected',
+    hint: 'test hint',
+    detail: { guid: '15acc839-d847-527c-8284-bfb36d7c50de' },
+  }),
+];
+
+// ── four-property surface ───────────────────────────────────────────────────
+describe('GameProjectError — structural surface', () => {
+  it('has .code, .expected, .hint, .detail', () => {
+    const err = makeErr();
+    expect(err).toHaveProperty('code');
+    expect(err).toHaveProperty('expected');
+    expect(err).toHaveProperty('hint');
+    expect(err).toHaveProperty('detail');
+  });
+
+  it('.code is readonly (TS compile-time, not runtime)', () => {
+    const err = makeErr();
+    // TS `readonly` is compile-time only; at runtime the property exists and
+    // holds its value. AI users cannot assign via the type (charter P2).
+    expect(err.code).toBe('forge-missing');
+    expect(typeof err.code).toBe('string');
+  });
+
+  it('.expected is readonly (TS compile-time)', () => {
+    const err = makeErr();
+    expect(err.expected).toBe('test expected');
+    expect(typeof err.expected).toBe('string');
+  });
+
+  it('.hint is readonly (TS compile-time)', () => {
+    const err = makeErr();
+    expect(err.hint).toBe('test hint');
+    expect(typeof err.hint).toBe('string');
+  });
+
+  it('.detail is readonly (TS compile-time)', () => {
+    const err = makeErr();
+    expect(err.detail).toBeDefined();
+    expect(typeof err.detail).toBe('object');
+  });
+});
+
+// ── code union membership ───────────────────────────────────────────────────
+describe('GameProjectError — code union', () => {
+  const codes: GameProjectErrorCode[] = [
+    'forge-missing',
+    'forge-parse-failed',
+    'forge-schema-invalid',
+    'forge-unknown-field',
+    'forge-guid-malformed',
+    'forge-scene-unresolved',
+  ];
+
+  it('code union has exactly 6 members', () => {
+    expect(codes).toHaveLength(6);
+  });
+
+  it('each code is constructable', () => {
+    expect(errors.map((error) => error.code)).toEqual(codes);
+    for (const err of errors) {
+      expect(err).toBeInstanceOf(Error);
+      expect(err).toBeInstanceOf(GameProjectError);
+    }
+  });
+
+  it('compiles exhaustive switch without default', () => {
+    function switchOnCode(code: GameProjectErrorCode): string {
+      switch (code) {
+        case 'forge-missing':
+          return 'missing';
+        case 'forge-parse-failed':
+          return 'parse-failed';
+        case 'forge-schema-invalid':
+          return 'schema-invalid';
+        case 'forge-unknown-field':
+          return 'unknown-field';
+        case 'forge-guid-malformed':
+          return 'guid-malformed';
+        case 'forge-scene-unresolved':
+          return 'scene-unresolved';
+      }
+    }
+    expect(switchOnCode('forge-missing')).toBe('missing');
+    expect(switchOnCode('forge-scene-unresolved')).toBe('scene-unresolved');
+  });
+});
+
+function describeError(error: GameProjectError): string {
+  switch (error.code) {
+    case 'forge-missing':
+      return `missing:${error.detail.path}`;
+    case 'forge-parse-failed':
+      return `parse:${error.detail.path}:${error.detail.rawMessage}`;
+    case 'forge-schema-invalid':
+      return `schema:${error.detail.path}:${error.detail.zodErrors.length}`;
+    case 'forge-unknown-field':
+      return `unknown:${error.detail.path}:${error.detail.fieldNames.join(',')}`;
+    case 'forge-guid-malformed':
+      return `guid:${error.detail.field}:${error.detail.rawInput}`;
+    case 'forge-scene-unresolved':
+      return `scene:${error.detail.guid}`;
+  }
+}
+
+describe('GameProjectError — code-correlated error narrowing', () => {
+  it('narrows representative detail payloads from error.code', () => {
+    expect(errors.map(describeError)).toEqual([
+      'missing:/fake/forge.json',
+      'parse:/fake/forge.json:invalid JSON',
+      'schema:/fake/forge.json:0',
+      'unknown:/fake/forge.json:scenes',
+      'guid:defaultScene:bad-guid',
+      'scene:15acc839-d847-527c-8284-bfb36d7c50de',
+    ]);
+  });
+});
+
+// ── per-code detail narrowing ───────────────────────────────────────────────
+describe('GameProjectError — detail narrowing per code', () => {
+  it('forge-missing detail contains path:string', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string }> = {
+      path: '/some/game/forge.json',
+    };
+    expect(_detail.path).toBe('/some/game/forge.json');
+  });
+
+  it('forge-parse-failed detail contains path + rawMessage', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string; rawMessage: string }> = {
+      path: '/some/forge.json',
+      rawMessage: 'Unexpected token',
+    };
+    expect(_detail.rawMessage).toBe('Unexpected token');
+  });
+
+  it('forge-schema-invalid detail contains path + zodErrors', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string; zodErrors: unknown }> = {
+      path: '/some/forge.json',
+      zodErrors: [],
+    };
+    expect(_detail.path).toBe('/some/forge.json');
+  });
+
+  it('forge-unknown-field detail contains path + fieldNames', () => {
+    const _detail: Extract<GameProjectErrorDetail, { path: string; fieldNames: string[] }> = {
+      path: '/some/forge.json',
+      fieldNames: ['scenes'],
+    };
+    expect(_detail.fieldNames).toEqual(['scenes']);
+  });
+
+  it('forge-guid-malformed detail contains field + rawInput', () => {
+    const _detail: Extract<GameProjectErrorDetail, { field: string; rawInput: string }> = {
+      field: 'defaultScene',
+      rawInput: 'rogue-encampment',
+    };
+    expect(_detail.rawInput).toBe('rogue-encampment');
+  });
+
+  it('forge-scene-unresolved detail contains guid:string', () => {
+    const _detail: Extract<GameProjectErrorDetail, { guid: string }> = {
+      guid: '15acc839-d847-527c-8284-bfb36d7c50de',
+    };
+    expect(_detail.guid).toBe('15acc839-d847-527c-8284-bfb36d7c50de');
+  });
+});
+
+// ── error message ───────────────────────────────────────────────────────────
+describe('GameProjectError — message', () => {
+  it('is an instance of Error', () => {
+    const err = makeErr();
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('has name GameProjectError', () => {
+    const err = makeErr();
+    expect(err.name).toBe('GameProjectError');
+  });
+
+  it('message contains code for human readability', () => {
+    const err = makeErr();
+    expect(err.message).toContain('GameProjectError');
+    expect(err.message).toContain('forge-missing');
+  });
+});

package/src/__tests__/fixtures/games/cow-level/forge.json

@@ -0,0 +1,7 @@
+{
+  "id": "test3",
+  "name": "test3",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts",
+  "physics": "3d"
+}

package/src/__tests__/fixtures/games/cow-survivor/forge.json

@@ -0,0 +1,8 @@
+{
+  "id": "cow-survivor",
+  "name": "Cow-Level Survivor",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts",
+  "physics": "3d",
+  "defaultScene": "7b4d43d4-5b19-5903-8966-f89671d21565"
+}

package/src/__tests__/fixtures/games/fps/forge.json

@@ -0,0 +1,7 @@
+{
+  "id": "fps",
+  "name": "Sector Strike",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts",
+  "pointerLock": true
+}

package/src/__tests__/fixtures/games/hellforge/forge.json

@@ -0,0 +1,24 @@
+{
+  "id": "hellforge",
+  "name": "ForgeaX: Hellforge",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts",
+  "physics": "3d",
+  "pointerLock": true,
+  "defaultScene": "15acc839-d847-527c-8284-bfb36d7c50de",
+  "preview": {
+    "skin": {
+      "sceneGuid": "5e3028dd-ddf6-4104-86d9-318d3e8fb5a6",
+      "clipGuids": [
+        "c530adf2-8de6-486a-afaa-9af3a6e6dfd1",
+        "f9355148-5ddc-45a4-80d4-ef80fce559b0",
+        "9bb05e7d-6156-424f-8a20-f80373507f65",
+        "7faedc58-49cd-4fc9-93b7-66eca1b79674",
+        "ca6e7f12-8e1a-4b3c-9d50-2a4f1b8c6d04"
+      ],
+      "clipDefault": "idle",
+      "scale": 1,
+      "pos": [0, 0, 0]
+    }
+  }
+}

package/src/__tests__/fixtures/games/shoot-opt/forge.json

@@ -0,0 +1,6 @@
+{
+  "id": "shoot-opt",
+  "name": "shoot-opt",
+  "schemaVersion": "1.0.0",
+  "entry": "src/main.ts"
+}

package/src/__tests__/fixtures/games/spin-cube/forge.json

@@ -0,0 +1,6 @@
+{
+  "id": "spin-cube",
+  "name": "spin-cube",
+  "schemaVersion": "1.0.0",
+  "entry": "main.ts"
+}