@forgeax/engine-project 0.1.21 → 0.1.24

package/src/__tests__/loader.test.ts

@@ -16,13 +16,15 @@ function makeReadThrow(err: Error): (path: string) => Promise<string> {
 const VALID_FORGE_JSON = JSON.stringify({
   id: 'test-game',
   name: 'Test Game',
-  schemaVersion: '1.0.0',
+  schemaVersion: '2.0.0',
+  plugins: [],
 });
 
 const VALID_WITH_DEFAULT_SCENE = JSON.stringify({
   id: 'test-game',
   name: 'Test Game',
-  schemaVersion: '1.0.0',
+  schemaVersion: '2.0.0',
+  plugins: [],
   defaultScene: '15acc839-d847-527c-8284-bfb36d7c50de',
 });
 
@@ -31,27 +33,31 @@ const INVALID_JSON = '{id: broken';
 const WITH_SCENES_ARRAY = JSON.stringify({
   id: 'has-scenes',
   name: 'Has Scenes',
-  schemaVersion: '1.0.0',
+  schemaVersion: '2.0.0',
+  plugins: [],
   scenes: [{ id: 'l1', name: 'Level 1', pack: 'scenes/level1.pack.json' }],
 });
 
 const WITH_BAD_GUID = JSON.stringify({
   id: 'bad-guid',
   name: 'Bad GUID',
-  schemaVersion: '1.0.0',
+  schemaVersion: '2.0.0',
+  plugins: [],
   defaultScene: 'not-a-guid',
 });
 
 const WITHOUT_DEFAULT_SCENE = JSON.stringify({
   id: 'no-default',
   name: 'No Default',
-  schemaVersion: '1.0.0',
+  schemaVersion: '2.0.0',
+  plugins: [],
 });
 
-const WITH_NPC_POLICY = JSON.stringify({
+const WITH_LEGACY_POLICY = JSON.stringify({
   id: 'npc-game',
   name: 'NPC Game',
-  schemaVersion: '1.0.0',
+  schemaVersion: '2.0.0',
+  plugins: [],
   npc: {
     model: 'deepseek-v4-flash-openai',
     maxTokens: 220,
@@ -124,7 +130,7 @@ describe('loadGameProject — return path 5: valid forge.json', () => {
       expect(result.value).toBeDefined();
       expect(result.value.id).toBe('test-game');
       expect(result.value.name).toBe('Test Game');
-      expect(result.value.schemaVersion).toBe('1.0.0');
+      expect(result.value.schemaVersion).toBe('2.0.0');
     }
   });
 
@@ -145,13 +151,10 @@ describe('loadGameProject — return path 5: valid forge.json', () => {
     }
   });
 
-  it('accepts the Digital Life NPC policy in forge.json', async () => {
-    const result = await loadGameProject(makeRead(WITH_NPC_POLICY));
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.npc?.model).toBe('deepseek-v4-flash-openai');
-      expect(result.value.npc?.budget?.maxConcurrent).toBe(4);
-    }
+  it('rejects the removed NPC policy instead of dual-reading it', async () => {
+    const result = await loadGameProject(makeRead(WITH_LEGACY_POLICY));
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('forge-unknown-field');
   });
 
   it('is idempotent — same read returns same result', async () => {

package/src/__tests__/resolve.test.ts

@@ -10,14 +10,16 @@ function makeRead(content: string): (path: string) => Promise<string> {
 const VALID_WITH_SCENE = JSON.stringify({
   id: 'test-game',
   name: 'Test Game',
-  schemaVersion: '1.0.0',
+  schemaVersion: '2.0.0',
+  plugins: [],
   defaultScene: '15acc839-d847-527c-8284-bfb36d7c50de',
 });
 
 const WITHOUT_SCENE = JSON.stringify({
   id: 'no-scene',
   name: 'No Scene',
-  schemaVersion: '1.0.0',
+  schemaVersion: '2.0.0',
+  plugins: [],
 });
 
 // ── signature verification ──────────────────────────────────────────────────

package/src/__tests__/schema-v2.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+
+import { GameProjectSchema } from '../schema.js';
+
+const validProject = {
+  id: 'schema-v2-game',
+  name: 'Schema V2 Game',
+  schemaVersion: '2.0.0',
+  plugins: [],
+};
+
+describe('GameProjectSchema v2', () => {
+  it('requires the strict schema 2.0 project shape and allows an empty EntryTree', () => {
+    const result = GameProjectSchema.safeParse(validProject);
+
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.data.plugins).toEqual([]);
+  });
+
+  it('rejects every schema version other than 2.0.0', () => {
+    for (const schemaVersion of ['1.0.0', '2.1.0', 'v2']) {
+      const result = GameProjectSchema.safeParse({ ...validProject, schemaVersion });
+      expect(result.success, schemaVersion).toBe(false);
+    }
+  });
+
+  it('requires plugins as the only installable capability root', () => {
+    const { plugins: _plugins, ...withoutPlugins } = validProject;
+    const result = GameProjectSchema.safeParse(withoutPlugins);
+
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects legacy root fields instead of preserving a dual manifest path', () => {
+    const legacyFields = [
+      'entry',
+      'executionEntry',
+      'physics',
+      'pointerLock',
+      'input',
+      'preview',
+      'npc',
+    ] as const;
+
+    for (const field of legacyFields) {
+      const result = GameProjectSchema.safeParse({
+        ...validProject,
+        [field]: field === 'pointerLock' ? true : './legacy.ts',
+      });
+      expect(result.success, field).toBe(false);
+    }
+  });
+
+  it('accepts enabled, disabled, and realm-inherited Entry states', () => {
+    const result = GameProjectSchema.safeParse({
+      ...validProject,
+      plugins: [
+        { id: 'enabled', name: './enabled.plugin.ts', realm: 'engine' },
+        { id: 'disabled', name: './disabled.plugin.ts', disabled: true, realm: 'engine' },
+        { id: 'inherited', name: './inherited.plugin.ts' },
+      ],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects nullable disabled state because absence means enabled', () => {
+    const result = GameProjectSchema.safeParse({
+      ...validProject,
+      plugins: [{ id: 'nullable', name: './nullable.plugin.ts', disabled: null }],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts a Group root with nested children and inherited realm', () => {
+    const result = GameProjectSchema.safeParse({
+      ...validProject,
+      plugins: [
+        {
+          id: 'game',
+          name: 'cordis:group',
+          group: true,
+          realm: 'engine',
+          config: [
+            { id: 'world', name: './world.plugin.ts' },
+            { id: 'player', name: './player.plugin.ts', inject: ['world'] },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects a Group whose config is not an EntryTree', () => {
+    const result = GameProjectSchema.safeParse({
+      ...validProject,
+      plugins: [{ id: 'invalid-group', name: 'cordis:group', group: true, config: {} }],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects duplicate Entry ids across a Group ownership path', () => {
+    const result = GameProjectSchema.safeParse({
+      ...validProject,
+      plugins: [
+        { id: 'same', name: './root.plugin.ts' },
+        {
+          id: 'group',
+          name: 'cordis:group',
+          group: true,
+          config: [{ id: 'same', name: './child.plugin.ts' }],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an unknown physical realm before module activation', () => {
+    const result = GameProjectSchema.safeParse({
+      ...validProject,
+      plugins: [{ id: 'unknown', name: './unknown.plugin.ts', realm: 'worker' }],
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/__tests__/schema.test.ts

@@ -1,99 +1,22 @@
-// schema.test.ts — w2: GameProjectSchema + GuidString refinement tests
 import { describe, expect, it } from 'vitest';
 import { GameProjectSchema, GuidString } from '../schema.js';
 
-// ── valid full forge.json ──────────────────────────────────────────────────
-describe('GameProjectSchema — acceptance', () => {
-  it('accepts a valid full forge.json', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'hellforge',
-      name: 'Hellforge',
-      schemaVersion: '1.0.0',
-      defaultScene: '15acc839-d847-527c-8284-bfb36d7c50de',
-      physics: '3d',
-      pointerLock: true,
-      input: 'fps',
-      preview: {
-        skin: {
-          sceneGuid: '11111111-1111-1111-1111-111111111111',
-          clipGuids: [],
-          clipDefault: 'idle',
-          scale: 1,
-          pos: [0, 0],
-        },
-      },
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('accepts minimal forge.json with only id+name+schemaVersion', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'minimal',
-      name: 'Minimal Game',
-      schemaVersion: '1.0.0',
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('accepts forge.json without entry (entry is optional)', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'no-entry',
-      name: 'No Entry Game',
-      schemaVersion: '1.0.0',
-    });
-    expect(result.success).toBe(true);
-  });
+const base = {
+  id: 'test-game',
+  name: 'Test Game',
+  schemaVersion: '2.0.0',
+  plugins: [],
+};
 
-  it('accepts forge.json without defaultScene (defaultScene is optional)', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'no-default',
-      name: 'No Default Game',
-      schemaVersion: '1.0.0',
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('keeps forge.json as the engine-project manifest, not a Catalog asset', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'manifest-only',
-      name: 'Manifest Only',
-      schemaVersion: '1.0.0',
-    });
-    expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data).not.toHaveProperty('guid');
-      expect(result.data).not.toHaveProperty('sourceKey');
-      expect(result.data).not.toHaveProperty('assets');
-    }
-  });
-
-  it('accepts forge.json with entry field present', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'with-entry',
-      name: 'With Entry',
-      schemaVersion: '1.0.0',
-      entry: 'main.ts',
-    });
-    expect(result.success).toBe(true);
+describe('GameProjectSchema schema 2.0', () => {
+  it('accepts a minimal strict manifest', () => {
+    expect(GameProjectSchema.safeParse(base).success).toBe(true);
   });
 
-  it('accepts an explicit realm-local execution entry', () => {
+  it('accepts defaultScene and a nested native Entry tree', () => {
     const result = GameProjectSchema.safeParse({
-      id: 'worker-game',
-      name: 'Worker Game',
-      schemaVersion: '1.0.0',
-      entry: 'main.ts',
-      executionEntry: 'runtime.ts',
-    });
-    expect(result.success).toBe(true);
-    if (result.success) expect(result.data.executionEntry).toBe('runtime.ts');
-  });
-
-  it('accepts a DSH-aligned plugin Entry tree with ForgeaX realm placement', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'plugin-game',
-      name: 'Plugin Game',
-      schemaVersion: '1.0.0',
+      ...base,
+      defaultScene: '15acc839-d847-527c-8284-bfb36d7c50de',
       plugins: [
         {
           id: 'engine-features',
@@ -114,11 +37,49 @@ describe('GameProjectSchema — acceptance', () => {
     expect(result.success).toBe(true);
   });
 
-  it('rejects duplicate plugin Entry ids anywhere in one tree', () => {
+  it('rejects every schema version except 2.0.0', () => {
+    for (const schemaVersion of ['1.0.0', '2.1.0', 'v2']) {
+      expect(GameProjectSchema.safeParse({ ...base, schemaVersion }).success).toBe(false);
+    }
+  });
+
+  it('requires plugins and rejects nullable entry controls', () => {
+    const { plugins: _plugins, ...withoutPlugins } = base;
+    expect(GameProjectSchema.safeParse(withoutPlugins).success).toBe(false);
+    expect(GameProjectSchema.safeParse({ ...base, disabled: null }).success).toBe(false);
+    expect(
+      GameProjectSchema.safeParse({
+        ...base,
+        plugins: [{ id: 'nullable', name: './x', disabled: null }],
+      }).success,
+    ).toBe(false);
+  });
+
+  it('rejects every legacy root field without a compatibility parser', () => {
+    for (const field of [
+      'entry',
+      'executionEntry',
+      'physics',
+      'pointerLock',
+      'input',
+      'preview',
+      'npc',
+    ]) {
+      expect(GameProjectSchema.safeParse({ ...base, [field]: 'legacy' }).success).toBe(false);
+    }
+  });
+
+  it('rejects unknown top-level fields', () => {
+    const result = GameProjectSchema.safeParse({ ...base, scenes: [] });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues.some((issue) => issue.code === 'unrecognized_keys')).toBe(true);
+    }
+  });
+
+  it('rejects duplicate plugin ids across one Entry tree', () => {
     const result = GameProjectSchema.safeParse({
-      id: 'duplicate-plugins',
-      name: 'Duplicate Plugins',
-      schemaVersion: '1.0.0',
+      ...base,
       plugins: [
         { id: 'same', name: './one.ts' },
         {
@@ -133,185 +94,16 @@ describe('GameProjectSchema — acceptance', () => {
   });
 });
 
-// ── GuidString refinement ───────────────────────────────────────────────────
-describe('GuidString refinement', () => {
-  it('accepts valid 36-char dash-form UUID v4', () => {
-    const result = GuidString.safeParse('d953a1db-483a-4b7d-8b71-b8f144488c48');
-    expect(result.success).toBe(true);
-  });
-
-  it('accepts valid 36-char dash-form UUID v7', () => {
-    const result = GuidString.safeParse('15acc839-d847-527c-8284-bfb36d7c50de');
-    expect(result.success).toBe(true);
-  });
-
-  it('accepts valid 36-char dash-form UUID (uppercase hex)', () => {
-    const result = GuidString.safeParse('7B4D43D4-5B19-5903-8966-F89671D21565');
-    expect(result.success).toBe(true);
-  });
-
-  it('rejects malformed UUID string (too short)', () => {
-    const result = GuidString.safeParse('not-a-guid');
-    expect(result.success).toBe(false);
-  });
-
-  it('rejects plain slug string (non-UUID)', () => {
-    const result = GuidString.safeParse('rogue-encampment');
-    expect(result.success).toBe(false);
-  });
-
-  it('rejects empty string', () => {
-    const result = GuidString.safeParse('');
-    expect(result.success).toBe(false);
+describe('GuidString', () => {
+  it('accepts UUID values used by scene assets', () => {
+    expect(GuidString.safeParse('d953a1db-483a-4b7d-8b71-b8f144488c48').success).toBe(true);
+    expect(GuidString.safeParse('15acc839-d847-527c-8284-bfb36d7c50de').success).toBe(true);
+    expect(GuidString.safeParse('7B4D43D4-5B19-5903-8966-F89671D21565').success).toBe(true);
   });
 
-  it('rejects string with only 35 chars', () => {
-    const result = GuidString.safeParse('a2345678-1234-1234-1234-12345678901');
-    expect(result.success).toBe(false);
-  });
-});
-
-// ── strict rejection of unknown fields ──────────────────────────────────────
-describe('GameProjectSchema — strict rejection', () => {
-  it('rejects scenes[] as unknown field', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'has-scenes',
-      name: 'Has Scenes',
-      schemaVersion: '1.0.0',
-      scenes: [{ id: 'l1', name: 'Level 1', pack: 'scenes/level1.pack.json' }],
-    });
-    expect(result.success).toBe(false);
-    if (!result.success) {
-      // zod puts unrecognized_keys in the first issue
-      expect(result.error.issues.some((i) => i.code === 'unrecognized_keys')).toBe(true);
+  it('rejects malformed or non-UUID strings', () => {
+    for (const value of ['', 'not-a-guid', 'rogue-encampment']) {
+      expect(GuidString.safeParse(value).success).toBe(false);
     }
   });
-
-  it('rejects any unknown top-level field', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'extra-field',
-      name: 'Extra',
-      schemaVersion: '1.0.0',
-      unknownField: 'should not be here',
-    });
-    expect(result.success).toBe(false);
-  });
-});
-
-// ── physics union (D-4: all 5 known values) ─────────────────────────────────
-describe('GameProjectSchema — physics union', () => {
-  const physicsValues = ['3d', '2d', 'rapier-3d', 'rapier-2d', true] as const;
-
-  for (const phys of physicsValues) {
-    it(`accepts physics=${JSON.stringify(phys)}`, () => {
-      const result = GameProjectSchema.safeParse({
-        id: 'phys-test',
-        name: 'Physics Test',
-        schemaVersion: '1.0.0',
-        physics: phys,
-      });
-      expect(result.success).toBe(true);
-    });
-  }
-
-  it('rejects arbitrary string for physics', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'bad-physics',
-      name: 'Bad Physics',
-      schemaVersion: '1.0.0',
-      physics: 'custom-engine',
-    });
-    expect(result.success).toBe(false);
-  });
-
-  it('rejects number for physics', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'bad-physics-num',
-      name: 'Bad Physics Num',
-      schemaVersion: '1.0.0',
-      physics: 42,
-    });
-    expect(result.success).toBe(false);
-  });
-
-  it('accepts physics=false (boolean true/false both valid per D-4)', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'physics-false',
-      name: 'Physics False',
-      schemaVersion: '1.0.0',
-      physics: false,
-    });
-    expect(result.success).toBe(true);
-  });
-});
-
-// ── pointerLock boolean ─────────────────────────────────────────────────────
-describe('GameProjectSchema — pointerLock', () => {
-  it('accepts pointerLock=false', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'pl-false',
-      name: 'PL False',
-      schemaVersion: '1.0.0',
-      pointerLock: false,
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('rejects non-boolean pointerLock', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'pl-string',
-      name: 'PL String',
-      schemaVersion: '1.0.0',
-      pointerLock: 'true',
-    });
-    expect(result.success).toBe(false);
-  });
-});
-
-// ── input string ────────────────────────────────────────────────────────────
-describe('GameProjectSchema — input', () => {
-  it('accepts input string', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'with-input',
-      name: 'With Input',
-      schemaVersion: '1.0.0',
-      input: 'fps',
-    });
-    expect(result.success).toBe(true);
-  });
-});
-
-// ── preview.skin nested object ──────────────────────────────────────────────
-describe('GameProjectSchema — preview.skin', () => {
-  it('accepts full preview.skin object', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'with-preview',
-      name: 'With Preview',
-      schemaVersion: '1.0.0',
-      preview: {
-        skin: {
-          sceneGuid: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
-          clipGuids: ['bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'],
-          clipDefault: 'walk',
-          scale: 2.5,
-          pos: [100, 200, 300],
-        },
-      },
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it('accepts minimal preview.skin (sceneGuid only)', () => {
-    const result = GameProjectSchema.safeParse({
-      id: 'preview-min',
-      name: 'Preview Min',
-      schemaVersion: '1.0.0',
-      preview: {
-        skin: {
-          sceneGuid: 'cccccccc-cccc-cccc-cccc-cccccccccccc',
-        },
-      },
-    });
-    expect(result.success).toBe(true);
-  });
 });

package/src/__tests__/structural.test.ts

@@ -64,7 +64,8 @@ describe('AC-02: exports accessible', () => {
     const result = mod.GameProjectSchema.safeParse({
       id: 'test',
       name: 'Test',
-      schemaVersion: '1.0.0',
+      schemaVersion: '2.0.0',
+      plugins: [],
     });
     expect(result.success).toBe(true);
     if (result.success) {
@@ -72,7 +73,7 @@ describe('AC-02: exports accessible', () => {
       const gp = result.data;
       expect(gp.id).toBe('test');
       expect(gp.name).toBe('Test');
-      expect(gp.schemaVersion).toBe('1.0.0');
+      expect(gp.schemaVersion).toBe('2.0.0');
     }
   });
 

package/src/loader.ts

@@ -114,7 +114,7 @@ export function validateGameProject(raw: string): GuidResult<GameProject, GamePr
     return err(
       'forge-schema-invalid',
       'forge.json to satisfy GameProjectSchema',
-      'check forge.json against GameProjectSchema (z.infer for types); required fields: id, name, schemaVersion (all strings)',
+      'check forge.json against GameProjectSchema (z.infer for types); required fields: id, name, schemaVersion=2.0.0, and plugins',
       { path: FORGE_JSON, zodErrors },
     );
   }
@@ -161,7 +161,7 @@ export async function loadGameProject(
     return err(
       'forge-missing',
       'forge.json file to exist at the game root',
-      'verify the game directory contains forge.json; if this is a new game, scaffold via the Studio UI or create a forge.json with id, name, schemaVersion fields',
+      'verify the game directory contains forge.json; if this is a new game, scaffold via the Studio UI or create a schema 2.0 forge.json with id, name, schemaVersion=2.0.0, and plugins',
       { path: FORGE_JSON },
     );
   }
@@ -190,7 +190,7 @@ export function loadGameProjectSync(
     return err(
       'forge-missing',
       'forge.json file to exist at the game root',
-      'verify the game directory contains forge.json; if this is a new game, scaffold via the Studio UI or create a forge.json with id, name, schemaVersion fields',
+      'verify the game directory contains forge.json; if this is a new game, scaffold via the Studio UI or create a schema 2.0 forge.json with id, name, schemaVersion=2.0.0, and plugins',
       { path: FORGE_JSON },
     );
   }