@forgeax/engine-project 0.1.2

package/dist/index.mjs

@@ -0,0 +1,291 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { z } from 'zod';
+
+// src/errors.ts
+var GameProjectErrorClass = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(args) {
+    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;
+  }
+};
+var GameProjectError = GameProjectErrorClass;
+
+// src/paths.ts
+var FORGE_JSON = "forge.json";
+var GuidString = z.string().refine(
+  (val) => AssetGuid.parse(val).ok,
+  (val) => {
+    const parsed = AssetGuid.parse(val);
+    const message = !parsed.ok ? parsed.error.hint : `invalid GUID: ${val}`;
+    return { message };
+  }
+);
+var PhysicsUnion = z.union([z.enum(["3d", "2d", "rapier-3d", "rapier-2d"]), z.boolean()]);
+var SkinSchema = z.object({
+  sceneGuid: z.string().optional(),
+  clipGuids: z.array(z.string()).optional(),
+  clipDefault: z.string().optional(),
+  scale: z.number().optional(),
+  pos: z.array(z.number()).optional()
+}).passthrough();
+var PreviewSchema = z.object({ skin: SkinSchema }).passthrough();
+var NpcBudgetSchema = z.object({
+  maxCallsPerMinute: z.number().int().positive().optional(),
+  maxTokensPerMinute: z.number().int().positive().optional(),
+  maxConcurrent: z.number().int().positive().optional()
+}).strict();
+var NpcConfigSchema = z.object({
+  model: z.string().min(1).optional(),
+  maxTokens: z.number().int().positive().optional(),
+  budget: NpcBudgetSchema.optional()
+}).strict();
+var PluginRealmSchema = z.enum(["host", "engine", "build"]);
+var PluginInjectSchema = z.union([
+  z.array(z.string().min(1)),
+  z.record(z.string().min(1), z.unknown())
+]);
+var PluginEntryBase = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  disabled: z.boolean().nullable().optional(),
+  inject: PluginInjectSchema.nullable().optional(),
+  realm: PluginRealmSchema.optional()
+});
+var GameProjectPluginEntrySchema = z.lazy(
+  () => z.union([
+    PluginEntryBase.extend({
+      group: z.literal(true),
+      config: z.array(GameProjectPluginEntrySchema)
+    }).strict(),
+    PluginEntryBase.extend({
+      group: z.union([z.literal(false), z.null()]).optional(),
+      config: z.unknown().optional()
+    }).strict()
+  ])
+);
+var GameProjectPluginsSchema = z.array(GameProjectPluginEntrySchema).superRefine((entries, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (items) => {
+    for (const entry of items) {
+      if (seen.has(entry.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `duplicate plugin entry id: ${entry.id}`
+        });
+      }
+      seen.add(entry.id);
+      if (entry.group === true) visit(entry.config);
+    }
+  };
+  visit(entries);
+});
+var GameProjectSchema = z.object({
+  /** Stable game slug; matches the `.forgeax/games/<id>/` directory name. */
+  id: z.string(),
+  /** Human-facing display name (may contain any unicode). */
+  name: z.string(),
+  /** forge.json schema version, e.g. "1.0.0" — required so loaders can gate on format. */
+  schemaVersion: z.string(),
+  /** Optional bootstrap hook: entry module relative to game root (e.g. "main.ts", "src/main.ts"). */
+  entry: z.string().optional(),
+  /** Optional realm-local ExecutionBootstrapEntry module relative to game root. */
+  executionEntry: z.string().optional(),
+  /** Optional GUID of the scene to load first; must be a real scene asset GUID (GuidString-validated). */
+  defaultScene: GuidString.optional(),
+  /** Optional physics backend: enum tag ('3d'/'2d'/'rapier-3d'/'rapier-2d') or boolean on/off. */
+  physics: PhysicsUnion.optional(),
+  /** Optional flag requesting pointer-lock (FPS-style mouse capture) at play time. */
+  pointerLock: z.boolean().optional(),
+  /** Optional input scheme hint consumed by play-runtime (e.g. "fps"). */
+  input: z.string().optional(),
+  /** Optional editor preview config (skin scene/clips for the launcher card). */
+  preview: PreviewSchema.optional(),
+  /** Native DeepSeek Harness Entry tree, plus the ForgeaX build-only realm selector. */
+  plugins: GameProjectPluginsSchema.optional(),
+  /** Optional Digital Life NPC Brain policy consumed by the server adapter. */
+  npc: NpcConfigSchema.optional()
+}).strict();
+
+// src/loader.ts
+function err(code, expected, hint, detail) {
+  return { ok: false, error: new GameProjectError({ code, expected, hint, detail }) };
+}
+function ok(value) {
+  return { ok: true, value };
+}
+function readerFailureToken(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const metadata = error;
+  if (typeof metadata.code === "string") {
+    return metadata.code;
+  }
+  if (typeof metadata.name === "string") {
+    return metadata.name;
+  }
+  return void 0;
+}
+function readerFailureCause(token) {
+  switch (token) {
+    case "EACCES":
+    case "EPERM":
+    case "PermissionDeniedError":
+    case "NotAllowedError":
+    case "SecurityError":
+      return "permission-denied";
+    case "EAGAIN":
+    case "EBUSY":
+    case "EINTR":
+    case "ECONNABORTED":
+    case "ECONNREFUSED":
+    case "ECONNRESET":
+    case "EHOSTUNREACH":
+    case "ENETDOWN":
+    case "ENETUNREACH":
+    case "ETIMEDOUT":
+    case "EPIPE":
+    case "ABORT_ERR":
+    case "AbortError":
+    case "TimeoutError":
+      return "transient";
+    default:
+      return "unknown";
+  }
+}
+function readerFailure(error) {
+  const token = readerFailureToken(error);
+  if (token === "ENOENT") {
+    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",
+      { path: FORGE_JSON }
+    );
+  }
+  return err(
+    "forge-read-failed",
+    "forge.json reader to complete without refusal",
+    "retry the project reader; if the refusal persists, verify access to the game directory",
+    { path: FORGE_JSON, cause: readerFailureCause(token) }
+  );
+}
+function validateGameProject(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return err(
+      "forge-parse-failed",
+      "forge.json to be valid JSON",
+      "check forge.json for JSON syntax errors (trailing commas, unquoted keys, etc.)",
+      {
+        path: FORGE_JSON,
+        rawMessage: e instanceof Error ? e.message : String(e)
+      }
+    );
+  }
+  const schemaResult = GameProjectSchema.safeParse(parsed);
+  if (!schemaResult.success) {
+    const zodErrors = schemaResult.error.issues;
+    const unknownFieldIssues = zodErrors.filter((i) => i.code === "unrecognized_keys");
+    if (unknownFieldIssues.length > 0) {
+      const fieldNames = unknownFieldIssues.flatMap((i) => i.keys ?? []);
+      return err(
+        "forge-unknown-field",
+        "forge.json to not contain unknown fields (e.g. scenes[])",
+        "remove unknown fields from forge.json; refer to GameProjectSchema in @forgeax/engine-project for the authoritative field list",
+        { path: FORGE_JSON, fieldNames }
+      );
+    }
+    const guidFieldIssues = zodErrors.filter(
+      (i) => Array.isArray(i.path) && i.path.includes("defaultScene")
+    );
+    if (guidFieldIssues.length > 0) {
+      const rawInput = typeof parsed.defaultScene === "string" ? String(parsed.defaultScene) : "";
+      return err(
+        "forge-guid-malformed",
+        "defaultScene to be a valid 36-char RFC 4122 dash-form UUID",
+        "use a valid scene GUID; find it in the scene pack.json assets[].guid where kind=scene",
+        {
+          field: "defaultScene",
+          rawInput
+        }
+      );
+    }
+    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)",
+      { path: FORGE_JSON, zodErrors }
+    );
+  }
+  return ok(schemaResult.data);
+}
+async function loadGameProject(read) {
+  let raw;
+  try {
+    raw = await read(FORGE_JSON);
+  } catch (error) {
+    return readerFailure(error);
+  }
+  return validateGameProject(raw);
+}
+function loadGameProjectSync(read) {
+  let raw;
+  try {
+    raw = read(FORGE_JSON);
+  } catch (error) {
+    return readerFailure(error);
+  }
+  return validateGameProject(raw);
+}
+async function resolveDefaultScene(opts) {
+  const { read, resolveGuid } = opts;
+  const gpResult = await loadGameProject(read);
+  if (!gpResult.ok) {
+    return gpResult;
+  }
+  const gp = gpResult.value;
+  const defaultSceneGuid = gp.defaultScene;
+  if (defaultSceneGuid === void 0 || defaultSceneGuid === null) {
+    return err(
+      "forge-scene-unresolved",
+      "a defaultScene field in forge.json to resolve",
+      "add a defaultScene with a valid scene asset GUID to forge.json, or select a scene at runtime",
+      { guid: "" }
+    );
+  }
+  const guidStr = defaultSceneGuid;
+  const resolveResult = await resolveGuid(guidStr);
+  if (!resolveResult.ok) {
+    return err(
+      "forge-scene-unresolved",
+      "the defaultScene GUID to resolve to an existing scene asset",
+      "verify the defaultScene GUID matches a scene asset's pack.json assets[].guid (where kind=scene)",
+      { guid: guidStr }
+    );
+  }
+  const asset = resolveResult.value;
+  if (asset.kind !== "scene") {
+    return err(
+      "forge-scene-unresolved",
+      "the defaultScene GUID to point to a scene asset (kind=scene)",
+      `resolved asset kind is "${asset.kind}", not "scene"; verify the GUID points to a scene pack entry`,
+      { guid: guidStr }
+    );
+  }
+  return ok({ guid: guidStr, kind: "scene" });
+}
+
+export { FORGE_JSON, GameProjectError, GameProjectPluginEntrySchema, GameProjectPluginsSchema, GameProjectSchema, PluginRealmSchema, loadGameProject, loadGameProjectSync, resolveDefaultScene };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/paths.ts","../src/schema.ts","../src/loader.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["// errors.ts — GameProjectError closed error surface (D-2)\n//\n// Four-field surface: .code / .expected / .hint / .detail\n// Structurally parallel to PackError (engine-pack) — same interface shape\n// (charter P4 consistent abstraction), but own code union (D-2: pipe isolation).\n// GUID format failure translates PackError → GameProjectError(code='forge-guid-malformed')\n// so PackError never leaks to engine-project public surface.\n//\n// AI users consume via exhaustive switch on .code — no default case needed:\n// ```ts\n// switch (err.code) {\n//   case 'forge-missing':    console.error(err.detail.path); break;\n//   case 'forge-read-failed': console.error(err.detail.path, err.detail.cause); break;\n//   case 'forge-parse-failed': console.error(err.detail.rawMessage); break;\n//   // ... all 7 cases\n// }\n// ```\n\nimport type { z } from 'zod';\n\n/** forge.json file not found at the expected path. */\nexport interface ForgeMissingDetail {\n  readonly path: string;\n}\n\n/** Why the injected forge.json reader refused without exposing source details. */\nexport type ForgeReadFailureCauseCode = 'permission-denied' | 'transient' | 'unknown';\n\n/** forge.json could not be read for a reason other than a missing file. */\nexport interface ForgeReadFailedDetail {\n  readonly path: string;\n  readonly cause: ForgeReadFailureCauseCode;\n}\n\n/** forge.json exists but contains invalid JSON. */\nexport interface ForgeParseFailedDetail {\n  readonly path: string;\n  readonly rawMessage: string;\n}\n\n/** forge.json is valid JSON but fails zod schema validation (missing required fields, wrong types). */\nexport interface ForgeSchemaInvalidDetail {\n  readonly path: string;\n  /** The zod issues from `safeParse(...).error.issues` — each names the failing path + reason. */\n  readonly zodErrors: readonly z.ZodIssue[];\n}\n\n/** forge.json has .strict() rejected an unknown field (e.g. scenes[]). */\nexport interface ForgeUnknownFieldDetail {\n  readonly path: string;\n  readonly fieldNames: string[];\n}\n\n/** defaultScene GUID string is not a valid 36-char RFC 4122 dash-form UUID.\n *  cause is the original PackError from AssetGuid.parse (for debugging), NOT part of reserved union. */\nexport interface ForgeGuidMalformedDetail {\n  readonly field: string;\n  readonly rawInput: string;\n  readonly cause?: unknown; // PackError from engine-pack, optional for debugging (D-2)\n}\n\n/** defaultScene GUID is valid format but resolveGuid could not find it or found wrong kind. */\nexport interface ForgeSceneUnresolvedDetail {\n  readonly guid: string;\n}\n\ntype GameProjectErrorDetailByCode = {\n  'forge-missing': ForgeMissingDetail;\n  'forge-read-failed': ForgeReadFailedDetail;\n  'forge-parse-failed': ForgeParseFailedDetail;\n  'forge-schema-invalid': ForgeSchemaInvalidDetail;\n  'forge-unknown-field': ForgeUnknownFieldDetail;\n  'forge-guid-malformed': ForgeGuidMalformedDetail;\n  'forge-scene-unresolved': ForgeSceneUnresolvedDetail;\n};\n\nexport type GameProjectErrorCode = keyof GameProjectErrorDetailByCode;\nexport type GameProjectErrorDetail = GameProjectErrorDetailByCode[GameProjectErrorCode];\n\n// ── constructor args ────────────────────────────────────────────────────────\n\nexport type GameProjectErrorArgs<C extends GameProjectErrorCode = GameProjectErrorCode> = {\n  readonly code: C;\n  readonly expected: string;\n  readonly hint: string;\n  readonly detail: GameProjectErrorDetailByCode[C];\n};\n\n// ── GameProjectError class (D-2) ─────────────────────────────────────────────\n\n/**\n * Structured error for the @forgeax/engine-project loader + resolve layer.\n *\n * AI users consume via exhaustive switch on .code — no default case needed.\n * Aligns with PackError four-field surface (.code/.expected/.hint/.detail)\n * per charter P4 (consistent abstraction) and AC-10.\n */\nclass GameProjectErrorClass extends Error {\n  readonly code: GameProjectErrorCode;\n  readonly expected: string;\n  readonly hint: string;\n  readonly detail: GameProjectErrorDetail;\n\n  constructor(args: GameProjectErrorArgs) {\n    super(`[GameProjectError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);\n    this.name = 'GameProjectError';\n    this.code = args.code;\n    this.expected = args.expected;\n    this.hint = args.hint;\n    this.detail = args.detail;\n  }\n}\n\ntype GameProjectErrorVariant<C extends GameProjectErrorCode> = GameProjectErrorClass & {\n  readonly code: C;\n  readonly detail: GameProjectErrorDetailByCode[C];\n};\n\nexport type GameProjectError = {\n  [C in GameProjectErrorCode]: GameProjectErrorVariant<C>;\n}[GameProjectErrorCode];\n\ninterface GameProjectErrorConstructor {\n  new <C extends GameProjectErrorCode>(args: GameProjectErrorArgs<C>): GameProjectErrorVariant<C>;\n  readonly prototype: GameProjectErrorClass;\n}\n\nexport const GameProjectError: GameProjectErrorConstructor =\n  GameProjectErrorClass as unknown as GameProjectErrorConstructor;\n","// paths.ts — path constants SSOT (D-8 bottom tier)\n//\n// All path literals for forge.json live here as the single authoritative source.\n// Consumers import FORGE_JSON rather than hardcoding 'forge.json' strings.\n\n/** The forge.json manifest filename, relative to a game root directory. */\nexport const FORGE_JSON = 'forge.json' as const;\n","// schema.ts — GameProjectSchema + GuidString refinement (D-4, D-7)\n//\n// D-4 fields: id:string / name:string / schemaVersion:string / entry?:string /\n// executionEntry?:string /\n// defaultScene?:GuidString / physics?:union(enum+bool) / pointerLock?:bool /\n// input?:string / preview?:nested-object. .strict() rejects unknown fields.\n//\n// D-7: GuidString refinement lives here (engine-project), calls\n// AssetGuid.parse from engine-pack, translates PackError to zod error message.\n\nimport { AssetGuid } from '@forgeax/engine-pack/guid';\nimport { z } from 'zod';\n\n// ── GuidString: zod refinement calling AssetGuid.parse (AC-04) ──────────────\nexport const GuidString = z.string().refine(\n  (val) => AssetGuid.parse(val).ok,\n  (val) => {\n    const parsed = AssetGuid.parse(val);\n    const message = !parsed.ok ? parsed.error.hint : `invalid GUID: ${val}`;\n    return { message };\n  },\n);\n\n// ── physics union: all 5 known values (D-4) ─────────────────────────────────\nconst PhysicsUnion = z.union([z.enum(['3d', '2d', 'rapier-3d', 'rapier-2d']), z.boolean()]);\n\n// ── preview.skin nested object (D-4) ────────────────────────────────────────\nconst SkinSchema = z\n  .object({\n    sceneGuid: z.string().optional(),\n    clipGuids: z.array(z.string()).optional(),\n    clipDefault: z.string().optional(),\n    scale: z.number().optional(),\n    pos: z.array(z.number()).optional(),\n  })\n  .passthrough();\n\nconst PreviewSchema = z.object({ skin: SkinSchema }).passthrough();\n\n// Digital Life NPC runtime policy embedded in forge.json. The Brain owns\n// prompt/model execution; the game manifest only declares the bounded model\n// and governor ceilings consumed by the server-side NPC adapter.\nconst NpcBudgetSchema = z\n  .object({\n    maxCallsPerMinute: z.number().int().positive().optional(),\n    maxTokensPerMinute: z.number().int().positive().optional(),\n    maxConcurrent: z.number().int().positive().optional(),\n  })\n  .strict();\n\nconst NpcConfigSchema = z\n  .object({\n    model: z.string().min(1).optional(),\n    maxTokens: z.number().int().positive().optional(),\n    budget: NpcBudgetSchema.optional(),\n  })\n  .strict();\n\nexport const PluginRealmSchema = z.enum(['host', 'engine', 'build']);\n\nconst PluginInjectSchema = z.union([\n  z.array(z.string().min(1)),\n  z.record(z.string().min(1), z.unknown()),\n]);\n\nconst PluginEntryBase = z.object({\n  id: z.string().min(1),\n  name: z.string().min(1),\n  disabled: z.boolean().nullable().optional(),\n  inject: PluginInjectSchema.nullable().optional(),\n  realm: PluginRealmSchema.optional(),\n});\n\nexport interface GameProjectPluginEntry {\n  readonly id: string;\n  readonly name: string;\n  readonly config?: unknown;\n  readonly group?: boolean | null | undefined;\n  readonly disabled?: boolean | null | undefined;\n  readonly inject?: readonly string[] | Readonly<Record<string, unknown>> | null | undefined;\n  readonly realm?: z.infer<typeof PluginRealmSchema> | undefined;\n}\n\nexport const GameProjectPluginEntrySchema: z.ZodType<GameProjectPluginEntry> = z.lazy(() =>\n  z.union([\n    PluginEntryBase.extend({\n      group: z.literal(true),\n      config: z.array(GameProjectPluginEntrySchema),\n    }).strict(),\n    PluginEntryBase.extend({\n      group: z.union([z.literal(false), z.null()]).optional(),\n      config: z.unknown().optional(),\n    }).strict(),\n  ]),\n);\n\nexport const GameProjectPluginsSchema = z\n  .array(GameProjectPluginEntrySchema)\n  .superRefine((entries, ctx) => {\n    const seen = new Set<string>();\n    const visit = (items: readonly GameProjectPluginEntry[]): void => {\n      for (const entry of items) {\n        if (seen.has(entry.id)) {\n          ctx.addIssue({\n            code: z.ZodIssueCode.custom,\n            message: `duplicate plugin entry id: ${entry.id}`,\n          });\n        }\n        seen.add(entry.id);\n        if (entry.group === true) visit(entry.config as readonly GameProjectPluginEntry[]);\n      }\n    };\n    visit(entries);\n  });\n\n// ── GameProjectSchema: strict zod object (AC-03, AC-05) ─────────────────────\n// This schema is the authoritative field list for forge.json (charter P2) —\n// read it instead of prose docs. Each field carries its contract inline.\nexport const GameProjectSchema = z\n  .object({\n    /** Stable game slug; matches the `.forgeax/games/<id>/` directory name. */\n    id: z.string(),\n    /** Human-facing display name (may contain any unicode). */\n    name: z.string(),\n    /** forge.json schema version, e.g. \"1.0.0\" — required so loaders can gate on format. */\n    schemaVersion: z.string(),\n    /** Optional bootstrap hook: entry module relative to game root (e.g. \"main.ts\", \"src/main.ts\"). */\n    entry: z.string().optional(),\n    /** Optional realm-local ExecutionBootstrapEntry module relative to game root. */\n    executionEntry: z.string().optional(),\n    /** Optional GUID of the scene to load first; must be a real scene asset GUID (GuidString-validated). */\n    defaultScene: GuidString.optional(),\n    /** Optional physics backend: enum tag ('3d'/'2d'/'rapier-3d'/'rapier-2d') or boolean on/off. */\n    physics: PhysicsUnion.optional(),\n    /** Optional flag requesting pointer-lock (FPS-style mouse capture) at play time. */\n    pointerLock: z.boolean().optional(),\n    /** Optional input scheme hint consumed by play-runtime (e.g. \"fps\"). */\n    input: z.string().optional(),\n    /** Optional editor preview config (skin scene/clips for the launcher card). */\n    preview: PreviewSchema.optional(),\n    /** Native DeepSeek Harness Entry tree, plus the ForgeaX build-only realm selector. */\n    plugins: GameProjectPluginsSchema.optional(),\n    /** Optional Digital Life NPC Brain policy consumed by the server adapter. */\n    npc: NpcConfigSchema.optional(),\n  })\n  .strict();\n\n// ── GameProject type: z.infer-derived (AC-02, AC-05) ────────────────────────\nexport type GameProject = z.infer<typeof GameProjectSchema>;\n","// loader.ts — loadGameProject + resolveDefaultScene (D-6, AC-06/07/08/09)\n//\n// loadGameProject: injection-only `read:(path)=>Promise<string>`, returns\n//   GuidResult<GameProject, GameProjectError>. Reader failures preserve ENOENT\n//   as forge-missing and classify all other refusals as forge-read-failed;\n//   validation then has the remaining five return paths:\n//   2. JSON.parse fails → ok:false, error(code='forge-parse-failed')\n//   3. schema.parse fails (missing fields) → ok:false, error(code='forge-schema-invalid')\n//   3b. schema.parse fails (unknown fields via .strict()) → ok:false, error(code='forge-unknown-field')\n//   4. defaultScene GUID format invalid → ok:false, error(code='forge-guid-malformed')\n//   5. all valid → ok:true, value:GameProject\n//\n// resolveDefaultScene: {read, resolveGuid} dual-injection (AC-07). Independent\n//   of loadGameProject (does NOT call resolveGuid internally).\n//\n// D-6: return type GuidResult<T,E> — same as AssetGuid.parse (engine-pack).\n// D-2: PackError→GameProjectError translation for GUID format failures.\n\nimport type { GuidResult } from '@forgeax/engine-pack/guid';\nimport {\n  type ForgeReadFailureCauseCode,\n  GameProjectError,\n  type GameProjectErrorArgs,\n  type GameProjectErrorCode,\n} from './errors.js';\nimport { FORGE_JSON } from './paths.js';\nimport type { GameProject } from './schema.js';\nimport { GameProjectSchema } from './schema.js';\n\n// ── helpers ─────────────────────────────────────────────────────────────────\n\nfunction err<C extends GameProjectErrorCode>(\n  code: C,\n  expected: string,\n  hint: string,\n  detail: GameProjectErrorArgs<C>['detail'],\n) {\n  return { ok: false as const, error: new GameProjectError({ code, expected, hint, detail }) };\n}\n\nfunction ok<T>(value: T) {\n  return { ok: true as const, value };\n}\n\ntype ReaderErrorMetadata = {\n  readonly code?: unknown;\n  readonly name?: unknown;\n};\n\nfunction readerFailureToken(error: unknown): string | undefined {\n  if (typeof error !== 'object' || error === null) {\n    return undefined;\n  }\n\n  const metadata = error as ReaderErrorMetadata;\n  if (typeof metadata.code === 'string') {\n    return metadata.code;\n  }\n  if (typeof metadata.name === 'string') {\n    return metadata.name;\n  }\n  return undefined;\n}\n\nfunction readerFailureCause(token: string | undefined): ForgeReadFailureCauseCode {\n  switch (token) {\n    case 'EACCES':\n    case 'EPERM':\n    case 'PermissionDeniedError':\n    case 'NotAllowedError':\n    case 'SecurityError':\n      return 'permission-denied';\n    case 'EAGAIN':\n    case 'EBUSY':\n    case 'EINTR':\n    case 'ECONNABORTED':\n    case 'ECONNREFUSED':\n    case 'ECONNRESET':\n    case 'EHOSTUNREACH':\n    case 'ENETDOWN':\n    case 'ENETUNREACH':\n    case 'ETIMEDOUT':\n    case 'EPIPE':\n    case 'ABORT_ERR':\n    case 'AbortError':\n    case 'TimeoutError':\n      return 'transient';\n    default:\n      return 'unknown';\n  }\n}\n\nfunction readerFailure(error: unknown) {\n  const token = readerFailureToken(error);\n  if (token === 'ENOENT') {\n    return err(\n      'forge-missing',\n      'forge.json file to exist at the game root',\n      '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',\n      { path: FORGE_JSON },\n    );\n  }\n\n  return err(\n    'forge-read-failed',\n    'forge.json reader to complete without refusal',\n    'retry the project reader; if the refusal persists, verify access to the game directory',\n    { path: FORGE_JSON, cause: readerFailureCause(token) },\n  );\n}\n\n// ── validateGameProject: sync pure core (JSON.parse → schema validate → 5 return paths) ──\n\n/**\n * Validate raw forge.json text against GameProjectSchema.\n * Pure sync function — no I/O, no `read` injection.\n *\n * ## Return paths (4 — missing/read-error handled by callers)\n *\n * | # | Condition | ok | code |\n * |:--|:--|:--|:--|\n * | 1 | `JSON.parse` fails | false | `forge-parse-failed` |\n * | 2a | zod `.strict()` unknown fields (e.g. `scenes[]`) | false | `forge-unknown-field` |\n * | 2b | zod required field missing / wrong type | false | `forge-schema-invalid` |\n * | 2c | `defaultScene` present, GUID format invalid | false | `forge-guid-malformed` |\n * | 3 | all valid | true | — |\n */\nexport function validateGameProject(raw: string): GuidResult<GameProject, GameProjectError> {\n  // ── 1. Parse JSON ─────────────────────────────────────────────────────────\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (e: unknown) {\n    return err(\n      'forge-parse-failed',\n      'forge.json to be valid JSON',\n      'check forge.json for JSON syntax errors (trailing commas, unquoted keys, etc.)',\n      {\n        path: FORGE_JSON,\n        rawMessage: e instanceof Error ? e.message : String(e),\n      },\n    );\n  }\n\n  // ── 2. Schema validate (.strict() rejects unknown fields) ─────────────────\n  const schemaResult = GameProjectSchema.safeParse(parsed);\n  if (!schemaResult.success) {\n    const zodErrors = schemaResult.error.issues;\n\n    // 2a: unknown fields (scenes[] etc.) — detect by looking for unrecognized_keys\n    const unknownFieldIssues = zodErrors.filter((i) => i.code === 'unrecognized_keys');\n    if (unknownFieldIssues.length > 0) {\n      const fieldNames = unknownFieldIssues.flatMap((i) => (i as { keys?: string[] }).keys ?? []);\n      return err(\n        'forge-unknown-field',\n        'forge.json to not contain unknown fields (e.g. scenes[])',\n        'remove unknown fields from forge.json; refer to GameProjectSchema in @forgeax/engine-project for the authoritative field list',\n        { path: FORGE_JSON, fieldNames },\n      );\n    }\n\n    // 2c: GuidString refinement failure → forge-guid-malformed (D-2 translation)\n    const guidFieldIssues = zodErrors.filter(\n      (i) => Array.isArray(i.path) && i.path.includes('defaultScene'),\n    );\n    if (guidFieldIssues.length > 0) {\n      const rawInput =\n        typeof (parsed as Record<string, unknown>).defaultScene === 'string'\n          ? String((parsed as Record<string, unknown>).defaultScene)\n          : '';\n      return err(\n        'forge-guid-malformed',\n        'defaultScene to be a valid 36-char RFC 4122 dash-form UUID',\n        'use a valid scene GUID; find it in the scene pack.json assets[].guid where kind=scene',\n        {\n          field: 'defaultScene',\n          rawInput,\n        },\n      );\n    }\n\n    // 2b: missing required fields or wrong types\n    return err(\n      'forge-schema-invalid',\n      'forge.json to satisfy GameProjectSchema',\n      'check forge.json against GameProjectSchema (z.infer for types); required fields: id, name, schemaVersion (all strings)',\n      { path: FORGE_JSON, zodErrors },\n    );\n  }\n\n  // ── 3. Success ────────────────────────────────────────────────────────────\n  return ok(schemaResult.data);\n}\n\n// ── loadGameProject: async (injection-only read) ────────────────────────────────\n\n/**\n * Load and validate a game project manifest from the abstract async reader.\n *\n * Wraps `validateGameProject`: reads `FORGE_JSON` via `read`, then validates.\n * If `read` throws/rejects → `forge-missing` for ENOENT, otherwise\n * `forge-read-failed` with a bounded cause code.\n *\n * ## Return paths (5)\n *\n * | # | Condition | ok | code |\n * |:--|:--|:--|:--|\n * | 1 | `read(FORGE_JSON)` throws / rejects with ENOENT | false | `forge-missing` |\n * | 1b | `read(FORGE_JSON)` refuses for another reason | false | `forge-read-failed` |\n * | 2 | `JSON.parse` fails | false | `forge-parse-failed` |\n * | 3a | zod `.strict()` unknown fields (e.g. `scenes[]`) | false | `forge-unknown-field` |\n * | 3b | zod required field missing / wrong type | false | `forge-schema-invalid` |\n * | 4 | `defaultScene` present, GUID format invalid (AssetGuid.parse fails) | false | `forge-guid-malformed` |\n * | 5 | all valid | true | — |\n *\n * ## Charter mapping\n *\n * - **P3 (explicit failure)**: every failure path returns structured `GameProjectError`\n *   with `.code`/`.expected`/`.hint`/`.detail`; no silent catch-and-ignore or fallback.\n * - **P4 (consistent abstraction)**: return shape is `GuidResult` (same alias as\n *   `AssetGuid.parse` from engine-pack).\n * - **SSOT**: this is the ONE authoritative forge.json loader — all consumers\n *   import it instead of hand-rolling their own fetch+as / JSON.parse+as.\n */\nexport async function loadGameProject(\n  read: (path: string) => Promise<string>,\n): Promise<GuidResult<GameProject, GameProjectError>> {\n  let raw: string;\n  try {\n    raw = await read(FORGE_JSON);\n  } catch (error: unknown) {\n    return readerFailure(error);\n  }\n\n  return validateGameProject(raw);\n}\n\n// ── loadGameProjectSync: sync companion (for sync-only callers like ContextSlot) ──\n\n/**\n * Synchronous version of loadGameProject — for callers that cannot use async\n * (e.g. sync `ContextSlot` content functions).\n *\n * Accepts a sync `read:(path)=>string` injection (same contract shape,\n * sync return). If `read` throws → `forge-missing` for ENOENT, otherwise\n * `forge-read-failed` with a bounded cause code.\n *\n * Uses the same `validateGameProject` pure core as `loadGameProject`.\n */\nexport function loadGameProjectSync(\n  read: (path: string) => string,\n): GuidResult<GameProject, GameProjectError> {\n  let raw: string;\n  try {\n    raw = read(FORGE_JSON);\n  } catch (error: unknown) {\n    return readerFailure(error);\n  }\n\n  return validateGameProject(raw);\n}\n\n// ── resolveDefaultScene: {read, resolveGuid} dual injection (AC-07) ─────────\n\n/** Resolved scene asset with GUID and kind='scene' confirmation. */\nexport interface ResolvedScene {\n  readonly guid: string;\n  readonly kind: 'scene';\n}\n\n/**\n * Resolve the defaultScene GUID to a scene asset using the injected resolveGuid.\n *\n * ## Dual injection (AC-07)\n *\n * - `read`: same `(path)=>Promise<string>` as loadGameProject — reads forge.json.\n * - `resolveGuid`: resolves a GUID string to an asset with `kind` field.\n *   Signature: `(guid: string) => Promise<{ok:true, value:{kind:string, guid:string}} | {ok:false, error:unknown}>`\n *\n * `loadGameProject` does NOT call resolveGuid; resolveDefaultScene calls both\n * independently (charter SSOT: two-layer separation, format vs resolve).\n *\n * ## Return paths\n *\n * | Condition | ok | code |\n * |:--|:--|:--|\n * | loadGameProject returns !ok | false | propagated from loader |\n * | no defaultScene | false | `forge-scene-unresolved` |\n * | resolveGuid returns !ok | false | `forge-scene-unresolved` |\n * | resolveGuid returns asset.kind !== 'scene' | false | `forge-scene-unresolved` |\n * | resolveGuid returns asset.kind === 'scene' | true | — |\n */\nexport async function resolveDefaultScene(opts: {\n  read: (path: string) => Promise<string>;\n  resolveGuid: (\n    guid: string,\n  ) => Promise<{ ok: true; value: { kind: string; guid: string } } | { ok: false; error: unknown }>;\n}): Promise<GuidResult<ResolvedScene, GameProjectError>> {\n  const { read, resolveGuid } = opts;\n\n  // 1. Load the game project\n  const gpResult = await loadGameProject(read);\n  if (!gpResult.ok) {\n    return gpResult; // propagate loader error\n  }\n\n  // 2. Check if defaultScene exists\n  const gp = gpResult.value;\n  const defaultSceneGuid = gp.defaultScene;\n  if (defaultSceneGuid === undefined || defaultSceneGuid === null) {\n    return err(\n      'forge-scene-unresolved',\n      'a defaultScene field in forge.json to resolve',\n      'add a defaultScene with a valid scene asset GUID to forge.json, or select a scene at runtime',\n      { guid: '' },\n    );\n  }\n\n  // 3. Resolve the GUID\n  const guidStr = defaultSceneGuid as string;\n  const resolveResult = await resolveGuid(guidStr);\n\n  if (!resolveResult.ok) {\n    return err(\n      'forge-scene-unresolved',\n      'the defaultScene GUID to resolve to an existing scene asset',\n      \"verify the defaultScene GUID matches a scene asset's pack.json assets[].guid (where kind=scene)\",\n      { guid: guidStr },\n    );\n  }\n\n  // 4. Verify kind === 'scene'\n  const asset = resolveResult.value;\n  if (asset.kind !== 'scene') {\n    return err(\n      'forge-scene-unresolved',\n      'the defaultScene GUID to point to a scene asset (kind=scene)',\n      `resolved asset kind is \"${asset.kind}\", not \"scene\"; verify the GUID points to a scene pack entry`,\n      { guid: guidStr },\n    );\n  }\n\n  return ok({ guid: guidStr, kind: 'scene' });\n}\n"]}

package/dist/loader.d.ts

@@ -0,0 +1,99 @@
+import type { GuidResult } from '@forgeax/engine-pack/guid';
+import { GameProjectError } from './errors.js';
+import type { GameProject } from './schema.js';
+/**
+ * Validate raw forge.json text against GameProjectSchema.
+ * Pure sync function — no I/O, no `read` injection.
+ *
+ * ## Return paths (4 — missing/read-error handled by callers)
+ *
+ * | # | Condition | ok | code |
+ * |:--|:--|:--|:--|
+ * | 1 | `JSON.parse` fails | false | `forge-parse-failed` |
+ * | 2a | zod `.strict()` unknown fields (e.g. `scenes[]`) | false | `forge-unknown-field` |
+ * | 2b | zod required field missing / wrong type | false | `forge-schema-invalid` |
+ * | 2c | `defaultScene` present, GUID format invalid | false | `forge-guid-malformed` |
+ * | 3 | all valid | true | — |
+ */
+export declare function validateGameProject(raw: string): GuidResult<GameProject, GameProjectError>;
+/**
+ * Load and validate a game project manifest from the abstract async reader.
+ *
+ * Wraps `validateGameProject`: reads `FORGE_JSON` via `read`, then validates.
+ * If `read` throws/rejects → `forge-missing` for ENOENT, otherwise
+ * `forge-read-failed` with a bounded cause code.
+ *
+ * ## Return paths (5)
+ *
+ * | # | Condition | ok | code |
+ * |:--|:--|:--|:--|
+ * | 1 | `read(FORGE_JSON)` throws / rejects with ENOENT | false | `forge-missing` |
+ * | 1b | `read(FORGE_JSON)` refuses for another reason | false | `forge-read-failed` |
+ * | 2 | `JSON.parse` fails | false | `forge-parse-failed` |
+ * | 3a | zod `.strict()` unknown fields (e.g. `scenes[]`) | false | `forge-unknown-field` |
+ * | 3b | zod required field missing / wrong type | false | `forge-schema-invalid` |
+ * | 4 | `defaultScene` present, GUID format invalid (AssetGuid.parse fails) | false | `forge-guid-malformed` |
+ * | 5 | all valid | true | — |
+ *
+ * ## Charter mapping
+ *
+ * - **P3 (explicit failure)**: every failure path returns structured `GameProjectError`
+ *   with `.code`/`.expected`/`.hint`/`.detail`; no silent catch-and-ignore or fallback.
+ * - **P4 (consistent abstraction)**: return shape is `GuidResult` (same alias as
+ *   `AssetGuid.parse` from engine-pack).
+ * - **SSOT**: this is the ONE authoritative forge.json loader — all consumers
+ *   import it instead of hand-rolling their own fetch+as / JSON.parse+as.
+ */
+export declare function loadGameProject(read: (path: string) => Promise<string>): Promise<GuidResult<GameProject, GameProjectError>>;
+/**
+ * Synchronous version of loadGameProject — for callers that cannot use async
+ * (e.g. sync `ContextSlot` content functions).
+ *
+ * Accepts a sync `read:(path)=>string` injection (same contract shape,
+ * sync return). If `read` throws → `forge-missing` for ENOENT, otherwise
+ * `forge-read-failed` with a bounded cause code.
+ *
+ * Uses the same `validateGameProject` pure core as `loadGameProject`.
+ */
+export declare function loadGameProjectSync(read: (path: string) => string): GuidResult<GameProject, GameProjectError>;
+/** Resolved scene asset with GUID and kind='scene' confirmation. */
+export interface ResolvedScene {
+    readonly guid: string;
+    readonly kind: 'scene';
+}
+/**
+ * Resolve the defaultScene GUID to a scene asset using the injected resolveGuid.
+ *
+ * ## Dual injection (AC-07)
+ *
+ * - `read`: same `(path)=>Promise<string>` as loadGameProject — reads forge.json.
+ * - `resolveGuid`: resolves a GUID string to an asset with `kind` field.
+ *   Signature: `(guid: string) => Promise<{ok:true, value:{kind:string, guid:string}} | {ok:false, error:unknown}>`
+ *
+ * `loadGameProject` does NOT call resolveGuid; resolveDefaultScene calls both
+ * independently (charter SSOT: two-layer separation, format vs resolve).
+ *
+ * ## Return paths
+ *
+ * | Condition | ok | code |
+ * |:--|:--|:--|
+ * | loadGameProject returns !ok | false | propagated from loader |
+ * | no defaultScene | false | `forge-scene-unresolved` |
+ * | resolveGuid returns !ok | false | `forge-scene-unresolved` |
+ * | resolveGuid returns asset.kind !== 'scene' | false | `forge-scene-unresolved` |
+ * | resolveGuid returns asset.kind === 'scene' | true | — |
+ */
+export declare function resolveDefaultScene(opts: {
+    read: (path: string) => Promise<string>;
+    resolveGuid: (guid: string) => Promise<{
+        ok: true;
+        value: {
+            kind: string;
+            guid: string;
+        };
+    } | {
+        ok: false;
+        error: unknown;
+    }>;
+}): Promise<GuidResult<ResolvedScene, GameProjectError>>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAEL,gBAAgB,EAGjB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAuF/C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAiE1F;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACtC,OAAO,CAAC,UAAU,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC,CASpD;AAID;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC7B,UAAU,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAS3C;AAID,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,WAAW,EAAE,CACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACnG,GAAG,OAAO,CAAC,UAAU,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAC,CA8CvD"}

package/dist/paths.d.ts

@@ -0,0 +1,3 @@
+/** The forge.json manifest filename, relative to a game root directory. */
+export declare const FORGE_JSON: "forge.json";
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAKA,2EAA2E;AAC3E,eAAO,MAAM,UAAU,EAAG,YAAqB,CAAC"}