@forgeax/engine-project 0.1.2

package/src/__tests__/resolve.test.ts

@@ -0,0 +1,160 @@
+// resolve.test.ts — w5: resolveDefaultScene double-injection tests
+import { describe, expect, it, vi } from 'vitest';
+import { resolveDefaultScene } from '../loader.js';
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+function makeRead(content: string): (path: string) => Promise<string> {
+  return async (_path: string) => content;
+}
+
+function makeReaderError(code: string, message = `reader refusal: ${code}`): Error {
+  const error = new Error(message);
+  Object.assign(error, { code });
+  return error;
+}
+
+const VALID_WITH_SCENE = JSON.stringify({
+  id: 'test-game',
+  name: 'Test Game',
+  schemaVersion: '1.0.0',
+  defaultScene: '15acc839-d847-527c-8284-bfb36d7c50de',
+});
+
+const WITHOUT_SCENE = JSON.stringify({
+  id: 'no-scene',
+  name: 'No Scene',
+  schemaVersion: '1.0.0',
+});
+
+// ── signature verification ──────────────────────────────────────────────────
+describe('resolveDefaultScene — signature', () => {
+  it('accepts {read, resolveGuid} as both injection points', async () => {
+    const read = makeRead(VALID_WITH_SCENE);
+    const resolveGuid = async (guid: string) => ({
+      ok: true as const,
+      value: { kind: 'scene', guid },
+    });
+    const result = await resolveDefaultScene({ read, resolveGuid });
+    expect(result.ok).toBe(true);
+  });
+});
+
+// ── resolve success path ────────────────────────────────────────────────────
+describe('resolveDefaultScene — success path', () => {
+  it('resolves when resolveGuid returns {ok:true} with kind=scene', async () => {
+    const read = makeRead(VALID_WITH_SCENE);
+    const resolveGuid = vi.fn(async (_guid: string) => ({
+      ok: true as const,
+      value: { kind: 'scene', guid: _guid },
+    }));
+
+    const result = await resolveDefaultScene({ read, resolveGuid });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.kind).toBe('scene');
+      expect(result.value.guid).toBe('15acc839-d847-527c-8284-bfb36d7c50de');
+    }
+    expect(resolveGuid).toHaveBeenCalledWith('15acc839-d847-527c-8284-bfb36d7c50de');
+  });
+});
+
+describe('resolveDefaultScene — reader refusal and retry', () => {
+  it('propagates a bounded read failure, then recovers with the same reader', async () => {
+    let refused = true;
+    const reads: string[] = [];
+    const read = async (path: string): Promise<string> => {
+      reads.push(path);
+      if (refused) {
+        throw makeReaderError('EAGAIN', 'secret transient reader source');
+      }
+      return VALID_WITH_SCENE;
+    };
+    const resolveGuid = vi.fn(async (guid: string) => ({
+      ok: true as const,
+      value: { kind: 'scene', guid },
+    }));
+
+    const first = await resolveDefaultScene({ read, resolveGuid });
+    expect(first).toMatchObject({
+      ok: false,
+      error: { code: 'forge-read-failed', detail: { path: 'forge.json', cause: 'transient' } },
+    });
+    expect(resolveGuid).not.toHaveBeenCalled();
+    if (!first.ok) {
+      expect(first.error.message).not.toContain('secret transient reader source');
+    }
+
+    refused = false;
+    const second = await resolveDefaultScene({ read, resolveGuid });
+    expect(second).toEqual({
+      ok: true,
+      value: { kind: 'scene', guid: '15acc839-d847-527c-8284-bfb36d7c50de' },
+    });
+    expect(reads).toEqual(['forge.json', 'forge.json']);
+    expect(resolveGuid).toHaveBeenCalledTimes(1);
+    expect(resolveGuid).toHaveBeenCalledWith('15acc839-d847-527c-8284-bfb36d7c50de');
+  });
+});
+
+// ── resolve failure: GUID not found ─────────────────────────────────────────
+describe('resolveDefaultScene — GUID not found', () => {
+  it('returns {ok:false} when resolveGuid returns {ok:false}', async () => {
+    const read = makeRead(VALID_WITH_SCENE);
+    const resolveGuid = async (_guid: string) => ({
+      ok: false as const,
+      error: new Error('not found'),
+    });
+
+    const result = await resolveDefaultScene({ read, resolveGuid });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-scene-unresolved');
+    }
+  });
+});
+
+// ── resolve failure: kind not scene ─────────────────────────────────────────
+describe('resolveDefaultScene — kind mismatch', () => {
+  it('returns {ok:false} when resolved asset kind !== scene', async () => {
+    const read = makeRead(VALID_WITH_SCENE);
+    const resolveGuid = async (_guid: string) => ({
+      ok: true as const,
+      value: { kind: 'texture', guid: _guid },
+    });
+
+    const result = await resolveDefaultScene({ read, resolveGuid });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-scene-unresolved');
+    }
+  });
+});
+
+// ── no defaultScene ─────────────────────────────────────────────────────────
+describe('resolveDefaultScene — no defaultScene', () => {
+  it('returns {ok:false} when forge.json has no defaultScene', async () => {
+    const read = makeRead(WITHOUT_SCENE);
+    const resolveGuid = async (_guid: string) => ({
+      ok: true as const,
+      value: { kind: 'scene', guid: _guid },
+    });
+
+    const result = await resolveDefaultScene({ read, resolveGuid });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('forge-scene-unresolved');
+    }
+  });
+});
+
+// ── loadGameProject isolation ───────────────────────────────────────────────
+describe('resolveDefaultScene — loadGameProject isolation', () => {
+  it('resolveDefaultScene accepts {read, resolveGuid} — loadGameProject accepts read only', () => {
+    // Type-level verification:
+    // loadGameProject: (read: (path)=>Promise<string>) => ...
+    // resolveDefaultScene: ({read, resolveGuid}) => ...
+    // The dual-injection signature separates resolve from format.
+    const _read = makeRead(VALID_WITH_SCENE);
+    expect(typeof _read).toBe('function');
+  });
+});

package/src/__tests__/schema.test.ts

@@ -0,0 +1,317 @@
+// 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);
+  });
+
+  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);
+  });
+
+  it('accepts an explicit realm-local execution entry', () => {
+    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',
+      plugins: [
+        {
+          id: 'engine-features',
+          name: 'cordis:group',
+          group: true,
+          realm: 'engine',
+          config: [
+            {
+              id: 'gameplay',
+              name: './main.ts',
+              config: { difficulty: 'hard' },
+              inject: ['world', 'renderer'],
+            },
+          ],
+        },
+      ],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects duplicate plugin Entry ids anywhere in one tree', () => {
+    const result = GameProjectSchema.safeParse({
+      id: 'duplicate-plugins',
+      name: 'Duplicate Plugins',
+      schemaVersion: '1.0.0',
+      plugins: [
+        { id: 'same', name: './one.ts' },
+        {
+          id: 'group',
+          name: 'cordis:group',
+          group: true,
+          config: [{ id: 'same', name: './two.ts' }],
+        },
+      ],
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ── 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);
+  });
+
+  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 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

@@ -0,0 +1,175 @@
+// structural.test.ts — w6: Structural verification (AC-01/02/05/06)
+//
+// Post-implementation verification of the built package:
+// AC-01: package directory + package.json name
+// AC-02: four exports accessible + GameProject is z.infer-derived
+// AC-05: zod in dependencies, z.infer used
+// AC-06: no node:fs / fetch imports in source
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+// ── AC-01: package directory exists + package.json name ─────────────────────
+describe('AC-01: package directory', () => {
+  it('package directory exists at packages/engine/packages/engine-project/', () => {
+    const pkgDir = path.resolve(import.meta.dirname, '..', '..');
+    expect(fs.existsSync(pkgDir)).toBe(true);
+
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    expect(fs.existsSync(pkgJsonPath)).toBe(true);
+
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    expect(pkg.name).toBe('@forgeax/engine-project');
+  });
+});
+
+// ── AC-02: four exports accessible ──────────────────────────────────────────
+describe('AC-02: exports accessible', () => {
+  it('loadGameProject is importable', async () => {
+    const mod = await import('../index.js');
+    expect(mod.loadGameProject).toBeDefined();
+    expect(typeof mod.loadGameProject).toBe('function');
+  });
+
+  it('GameProjectSchema is importable', async () => {
+    const mod = await import('../index.js');
+    expect(mod.GameProjectSchema).toBeDefined();
+  });
+
+  it('FORGE_JSON is importable', async () => {
+    const mod = await import('../index.js');
+    expect(mod.FORGE_JSON).toBe('forge.json');
+  });
+
+  it('GameProject type is derived from z.infer', async () => {
+    // Import the schema and check that GameProject is a z.infer type.
+    // At runtime z.infer produces nothing, but we can verify the schema exists
+    // and that the type declaration compiles (verified by typecheck step).
+    const mod = await import('../index.js');
+    expect(mod.GameProjectSchema).toBeDefined();
+    // We can create a valid object and parse it using the schema
+    const result = mod.GameProjectSchema.safeParse({
+      id: 'test',
+      name: 'Test',
+      schemaVersion: '1.0.0',
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      // GameProject type fields are inferrable — this object has id/name/schemaVersion
+      const gp = result.data;
+      expect(gp.id).toBe('test');
+      expect(gp.name).toBe('Test');
+      expect(gp.schemaVersion).toBe('1.0.0');
+    }
+  });
+
+  it('resolveDefaultScene is importable', async () => {
+    const mod = await import('../index.js');
+    expect(mod.resolveDefaultScene).toBeDefined();
+    expect(typeof mod.resolveDefaultScene).toBe('function');
+  });
+
+  it('keeps the validation primitive owner-local', async () => {
+    const mod = await import('../index.js');
+    expect('validateGameProject' in mod).toBe(false);
+  });
+
+  it('GameProjectError is importable', async () => {
+    const mod = await import('../index.js');
+    expect(mod.GameProjectError).toBeDefined();
+  });
+});
+
+// ── AC-05: zod in dependencies, z.infer used ────────────────────────────────
+describe('AC-05: zod dependency', () => {
+  it('package.json deps includes zod', () => {
+    const pkgDir = path.resolve(import.meta.dirname, '..', '..');
+    const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
+    expect(pkg.dependencies).toBeDefined();
+    expect(pkg.dependencies.zod).toBeDefined();
+  });
+
+  it('schema.ts imports zod and uses z.infer', () => {
+    const schemaPath = path.resolve(import.meta.dirname, '..', 'schema.ts');
+    const content = fs.readFileSync(schemaPath, 'utf-8');
+    expect(content).toContain("from 'zod'");
+    expect(content).toContain('z.infer');
+  });
+});
+
+// ── AC-06: no node:fs / fetch in engine-project src/ ────────────────────────
+describe('AC-06: no node:fs / fetch imports in source', () => {
+  const srcDir = path.resolve(import.meta.dirname, '..');
+
+  function grepForbiddenImports(filePath: string): string[] {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const hits: string[] = [];
+
+    // Only check actual imports, not comments
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) {
+        continue;
+      }
+      if (
+        trimmed.includes("from 'node:fs'") ||
+        trimmed.includes('from "node:fs"') ||
+        trimmed.includes("from 'fs'") ||
+        trimmed.includes('from "fs"') ||
+        trimmed.includes('import fs ') ||
+        trimmed.includes('import * as fs ') ||
+        trimmed.includes("require('fs'") ||
+        trimmed.includes('require("fs"') ||
+        trimmed.includes("from 'node:path'") ||
+        trimmed.includes('from "node:path"') ||
+        trimmed.includes('globalThis.fetch') ||
+        trimmed.includes('window.fetch')
+      ) {
+        hits.push(line);
+      }
+    }
+
+    // Also check for fetch() calls that aren't from injection
+    const fetchCallPattern = /\bfetch\s*\(/;
+    if (fetchCallPattern.test(content)) {
+      hits.push('contains fetch() call');
+    }
+
+    return hits;
+  }
+
+  it('source files have no node:fs imports', () => {
+    const entries = fs.readdirSync(srcDir, { recursive: true });
+    const files: string[] = [];
+    for (const entry of entries) {
+      if (
+        typeof entry === 'string' &&
+        entry.endsWith('.ts') &&
+        !entry.includes('__tests__') &&
+        !entry.includes('.test.')
+      ) {
+        files.push(path.join(srcDir, entry));
+      }
+    }
+
+    for (const file of files) {
+      const hits = grepForbiddenImports(file);
+      expect(
+        hits,
+        `${path.relative(srcDir, file)} has forbidden imports: ${hits.join(', ')}`,
+      ).toHaveLength(0);
+    }
+  });
+
+  it('loader.ts uses injection-only read (no fetch/fs)', () => {
+    const loaderPath = path.resolve(import.meta.dirname, '..', 'loader.ts');
+    const content = fs.readFileSync(loaderPath, 'utf-8');
+    // loader.ts should accept (read) as parameter — no direct fs/fetch import
+    expect(content).not.toMatch(/import\s+.*from\s+['"]node:fs['"]/);
+    expect(content).not.toMatch(/import\s+.*from\s+['"]fs['"]/);
+    // The read injection signature: `read: (path: string) => Promise<string>`
+    expect(content).toContain('read: (path: string) => Promise<string>');
+  });
+});