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

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,187 @@
+// 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/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');
+  });
+
+  it('keeps the public package exports stable after the directory move', () => {
+    const pkgDir = path.resolve(import.meta.dirname, '..', '..');
+    const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
+    expect(pkg.exports).toEqual({
+      '.': {
+        types: './dist/index.d.ts',
+        import: './dist/index.mjs',
+      },
+      './package.json': './package.json',
+    });
+  });
+});
+
+// ── 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>');
+  });
+});

package/src/errors.ts

@@ -0,0 +1,118 @@
+// errors.ts — GameProjectError closed error surface (D-2)
+//
+// Four-field surface: .code / .expected / .hint / .detail
+// Structurally parallel to PackError (engine-pack) — same interface shape
+// (charter P4 consistent abstraction), but own code union (D-2: pipe isolation).
+// GUID format failure translates PackError → GameProjectError(code='forge-guid-malformed')
+// so PackError never leaks to engine-project public surface.
+//
+// AI users consume via exhaustive switch on .code — no default case needed:
+// ```ts
+// switch (err.code) {
+//   case 'forge-missing':    console.error(err.detail.path); break;
+//   case 'forge-parse-failed': console.error(err.detail.rawMessage); break;
+//   // ... all 6 cases
+// }
+// ```
+
+import type { z } from 'zod';
+
+/** forge.json file not found at the expected path. */
+export interface ForgeMissingDetail {
+  readonly path: string;
+}
+
+/** forge.json exists but contains invalid JSON. */
+export interface ForgeParseFailedDetail {
+  readonly path: string;
+  readonly rawMessage: string;
+}
+
+/** forge.json is valid JSON but fails zod schema validation (missing required fields, wrong types). */
+export interface ForgeSchemaInvalidDetail {
+  readonly path: string;
+  /** The zod issues from `safeParse(...).error.issues` — each names the failing path + reason. */
+  readonly zodErrors: readonly z.ZodIssue[];
+}
+
+/** forge.json has .strict() rejected an unknown field (e.g. scenes[]). */
+export interface ForgeUnknownFieldDetail {
+  readonly path: string;
+  readonly fieldNames: string[];
+}
+
+/** defaultScene GUID string is not a valid 36-char RFC 4122 dash-form UUID.
+ *  cause is the original PackError from AssetGuid.parse (for debugging), NOT part of reserved union. */
+export interface ForgeGuidMalformedDetail {
+  readonly field: string;
+  readonly rawInput: string;
+  readonly cause?: unknown; // PackError from engine-pack, optional for debugging (D-2)
+}
+
+/** defaultScene GUID is valid format but resolveGuid could not find it or found wrong kind. */
+export interface ForgeSceneUnresolvedDetail {
+  readonly guid: string;
+}
+
+type GameProjectErrorDetailByCode = {
+  'forge-missing': ForgeMissingDetail;
+  'forge-parse-failed': ForgeParseFailedDetail;
+  'forge-schema-invalid': ForgeSchemaInvalidDetail;
+  'forge-unknown-field': ForgeUnknownFieldDetail;
+  'forge-guid-malformed': ForgeGuidMalformedDetail;
+  'forge-scene-unresolved': ForgeSceneUnresolvedDetail;
+};
+
+export type GameProjectErrorCode = keyof GameProjectErrorDetailByCode;
+export type GameProjectErrorDetail = GameProjectErrorDetailByCode[GameProjectErrorCode];
+
+// ── constructor args ────────────────────────────────────────────────────────
+
+export type GameProjectErrorArgs<C extends GameProjectErrorCode = GameProjectErrorCode> = {
+  readonly code: C;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: GameProjectErrorDetailByCode[C];
+};
+
+// ── GameProjectError class (D-2) ─────────────────────────────────────────────
+
+/**
+ * Structured error for the @forgeax/engine-project loader + resolve layer.
+ *
+ * AI users consume via exhaustive switch on .code — no default case needed.
+ * Aligns with PackError four-field surface (.code/.expected/.hint/.detail)
+ * per charter P4 (consistent abstraction) and AC-10.
+ */
+class GameProjectErrorClass extends Error {
+  readonly code: GameProjectErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: GameProjectErrorDetail;
+
+  constructor(args: GameProjectErrorArgs) {
+    super(`[GameProjectError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = 'GameProjectError';
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+}
+
+type GameProjectErrorVariant<C extends GameProjectErrorCode> = GameProjectErrorClass & {
+  readonly code: C;
+  readonly detail: GameProjectErrorDetailByCode[C];
+};
+
+export type GameProjectError = {
+  [C in GameProjectErrorCode]: GameProjectErrorVariant<C>;
+}[GameProjectErrorCode];
+
+interface GameProjectErrorConstructor {
+  new <C extends GameProjectErrorCode>(args: GameProjectErrorArgs<C>): GameProjectErrorVariant<C>;
+  readonly prototype: GameProjectErrorClass;
+}
+
+export const GameProjectError: GameProjectErrorConstructor =
+  GameProjectErrorClass as unknown as GameProjectErrorConstructor;

package/src/index.ts

@@ -0,0 +1,35 @@
+// @forgeax/engine-project — packages/project/ directory, stable public identity, progressive disclosure exports (D-8, charter P1)
+//
+// Export order: most-used first → schema/types middle → constants/resolve last.
+//   Top:    loadGameProject (primary entry point for every consumer)
+//   Middle: GameProjectSchema (self-introspection, charter P2) + GameProject type
+//   Bottom: FORGE_JSON constant + resolveDefaultScene + GameProjectError types
+
+export type {
+  ForgeGuidMalformedDetail,
+  ForgeMissingDetail,
+  ForgeParseFailedDetail,
+  ForgeSceneUnresolvedDetail,
+  ForgeSchemaInvalidDetail,
+  ForgeUnknownFieldDetail,
+  GameProjectErrorCode,
+  GameProjectErrorDetail,
+} from './errors.js';
+export { GameProjectError } from './errors.js';
+export type { ResolvedScene } from './loader.js';
+// ── Top tier: primary entry points ──────────────────────────────────────────
+export {
+  loadGameProject,
+  loadGameProjectSync,
+  resolveDefaultScene,
+} from './loader.js';
+// ── Bottom tier: constants + error types ────────────────────────────────────
+export { FORGE_JSON } from './paths.js';
+export type { GameProject, GameProjectPluginEntry } from './schema.js';
+// ── Middle tier: schema self-introspection + types ──────────────────────────
+export {
+  GameProjectPluginEntrySchema,
+  GameProjectPluginsSchema,
+  GameProjectSchema,
+  PluginRealmSchema,
+} from './schema.js';