@forgeax/engine-pack 0.1.2

package/dist/scriptable-pack.mjs

@@ -0,0 +1,583 @@
+import { err, ok } from '@forgeax/engine-types';
+import { uuidv7obj } from 'uuidv7';
+
+// src/scriptable-pack.ts
+
+// src/errors.ts
+var PackError = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(args) {
+    super(`[PackError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = "PackError";
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+};
+
+// src/guid.ts
+function brand(bytes) {
+  return bytes;
+}
+var HEX_BYTE = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+function bytesToDashForm(bytes) {
+  const h = HEX_BYTE;
+  return `${h[bytes[0]]}${h[bytes[1]]}${h[bytes[2]]}${h[bytes[3]]}-${h[bytes[4]]}${h[bytes[5]]}-${h[bytes[6]]}${h[bytes[7]]}-${h[bytes[8]]}${h[bytes[9]]}-${h[bytes[10]]}${h[bytes[11]]}${h[bytes[12]]}${h[bytes[13]]}${h[bytes[14]]}${h[bytes[15]]}`;
+}
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isValidAssetGuidString(value) {
+  return typeof value === "string" && UUID_RE.test(value);
+}
+function dashFormToBytes(dashForm) {
+  const hex = dashForm.replace(/-/g, "");
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+var AssetGuid = {
+  /**
+   * Parse a 36-char RFC 4122 dash-form UUID string into an AssetGuid.
+   * Returns Ok(AssetGuid) on success or Err(PackError) with code 'pack-guid-malformed' on failure.
+   * Never throws for expected failures (requirements §4.2 / §14 / charter proposition 4).
+   */
+  parse(dashForm) {
+    if (!isValidAssetGuidString(dashForm)) {
+      return {
+        ok: false,
+        error: new PackError({
+          code: "pack-guid-malformed",
+          expected: "36-char RFC 4122 dash-form UUID",
+          hint: "use AssetGuid.random() or a UUIDv7 generator; all GUID fields must be 36-char RFC 4122 dash-form",
+          detail: {
+            raw: dashForm,
+            reason: "expected 36-char RFC 4122 dash-form UUID"
+          }
+        })
+      };
+    }
+    return { ok: true, value: brand(dashFormToBytes(dashForm)) };
+  },
+  /**
+   * Format an AssetGuid as a 36-char RFC 4122 lowercase dash-form string.
+   */
+  format(guid) {
+    return bytesToDashForm(guid);
+  },
+  /**
+   * Test byte-by-byte equality between two AssetGuids.
+   */
+  equals(a, b) {
+    for (let i = 0; i < 16; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  },
+  /**
+   * Mint a new time-ordered UUIDv7 as an AssetGuid.
+   * Works in both Node.js and browser environments.
+   */
+  random() {
+    const uuid = uuidv7obj();
+    const bytes = new Uint8Array(16);
+    bytes.set(uuid.bytes);
+    return brand(bytes);
+  }
+};
+
+// src/scriptable-pack.ts
+var SCRIPTABLE_PACK_ASSET_KINDS = [
+  "mesh",
+  "material",
+  "scene",
+  "texture",
+  "equirect",
+  "sampler",
+  "font",
+  "render-pipeline",
+  "tileset",
+  "video",
+  "skeleton",
+  "skin",
+  "animation-clip",
+  "animation-graph",
+  "audio",
+  "particle-effect"
+];
+function isScriptablePackAssetKind(value) {
+  return SCRIPTABLE_PACK_ASSET_KINDS.includes(value);
+}
+function createScriptablePackAuthoringGateway(port, allocateGuid = AssetGuid.random) {
+  const requests = /* @__PURE__ */ new Map();
+  async function mutationResult(result) {
+    if (!result.ok) return result;
+    const inspected = await port.inspect(result.value.sourcePath);
+    if (!inspected.ok) return inspected;
+    return ok({
+      sourcePath: result.value.sourcePath,
+      revision: inspected.value.revision,
+      meta: inspected.value.meta
+    });
+  }
+  async function dispatch(operation) {
+    switch (operation.kind) {
+      case "preflight": {
+        const preflight = await port.preflight(operation.sourcePath);
+        return preflight.ok ? ok({ sourcePath: operation.sourcePath, ...preflight.value }) : preflight;
+      }
+      case "inspect-meta": {
+        const inspected = await port.inspect(operation.sourcePath);
+        return inspected.ok ? ok({ sourcePath: operation.sourcePath, ...inspected.value }) : inspected;
+      }
+      case "rebuild":
+      case "cold-cook": {
+        const preflight = await port.preflight(operation.sourcePath);
+        if (!preflight.ok) return preflight;
+        if (operation.expectedRevision !== void 0 && operation.expectedRevision !== preflight.value.revision) {
+          return err({
+            code: "pack-source-revision-conflict",
+            expected: operation.expectedRevision,
+            actual: preflight.value.revision,
+            hint: "inspect the current source revision, then retry the build with a new requestId",
+            retryable: true,
+            recoveryActions: ["asset.preflight", "mint-request-id"],
+            detail: { requestId: operation.requestId, sourcePath: operation.sourcePath }
+          });
+        }
+        const rebuilt = await port.rebuild(operation.sourcePath, operation.kind);
+        return rebuilt.ok ? ok({ sourcePath: operation.sourcePath, ...rebuilt.value }) : rebuilt;
+      }
+      case "create-scriptable-pack":
+        return mutationResult(
+          await port.mutate({
+            ...operation,
+            packageId: allocateGuid(),
+            initialOutput: { ...operation.initialOutput, guid: allocateGuid() }
+          })
+        );
+      case "add-output":
+        return mutationResult(await port.mutate({ ...operation, guid: allocateGuid() }));
+      case "clone-scriptable-pack": {
+        const inspected = await port.inspect(operation.sourcePath);
+        if (!inspected.ok) return inspected;
+        const outputGuids = Object.fromEntries(
+          inspected.value.meta.subAssets.map((asset) => [asset.sourceKey, allocateGuid()])
+        );
+        return mutationResult(
+          await port.mutate({
+            ...operation,
+            packageId: allocateGuid(),
+            outputGuids
+          })
+        );
+      }
+      case "add-external-asset":
+      case "rename-display":
+      case "remove-output":
+        return mutationResult(await port.mutate(operation));
+    }
+  }
+  return {
+    execute(operation) {
+      if (operation.requestId.trim().length === 0) {
+        return Promise.resolve(
+          err({
+            code: "pack-source-operation-committed",
+            expected: "a non-empty caller-minted requestId",
+            actual: operation.requestId,
+            hint: "mint a new requestId and retry the operation once",
+            retryable: true,
+            recoveryActions: ["mint-request-id"],
+            detail: { requestId: operation.requestId, sourcePath: operation.sourcePath }
+          })
+        );
+      }
+      const fingerprint = JSON.stringify(operation);
+      const prior = requests.get(operation.requestId);
+      if (prior !== void 0) {
+        if (prior.fingerprint === fingerprint) return prior.result;
+        return Promise.resolve(
+          err({
+            code: "pack-source-operation-committed",
+            expected: "one immutable operation per requestId",
+            actual: operation.kind,
+            hint: "read the original operation result or mint a new requestId",
+            retryable: false,
+            recoveryActions: ["read-operation-run", "mint-request-id"],
+            detail: { requestId: operation.requestId, sourcePath: operation.sourcePath }
+          })
+        );
+      }
+      const result = dispatch(operation);
+      requests.set(operation.requestId, { fingerprint, result });
+      return result;
+    }
+  };
+}
+var SCRIPTABLE_PACK_REQUEST_ID_SCHEMA = {
+  type: "string",
+  minLength: 1,
+  maxLength: 128,
+  pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+  description: "Caller-minted identity for one idempotent ScriptablePack operation."
+};
+var SCRIPTABLE_PACK_SOURCE_PATH_SCHEMA = {
+  type: "string",
+  minLength: 8,
+  pattern: "^[^/].*\\.pack\\.ts$",
+  description: "Game-root-relative ScriptablePack source path."
+};
+var SCRIPTABLE_PACK_OWNER_GUID_SCHEMA = {
+  type: "string",
+  format: "uuid",
+  description: "Catalog GUID used to resolve the producer-owned source subject."
+};
+var SCRIPTABLE_PACK_REVISION_SCHEMA = {
+  type: "string",
+  minLength: 64,
+  maxLength: 64,
+  pattern: "^[a-f0-9]{64}$",
+  description: "SHA-256 source revision returned by preflight."
+};
+var SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA = { type: "string", minLength: 1 };
+var SCRIPTABLE_PACK_ASSET_KIND_SCHEMA = {
+  enum: SCRIPTABLE_PACK_ASSET_KINDS,
+  description: "Ordinary Asset kind supported by the ScriptablePack producer/loader matrix."
+};
+var SCRIPTABLE_PACK_NAME_SCHEMA = { type: "string", minLength: 1 };
+function scriptablePackArgsSchema(properties, required, options = {}) {
+  const subjectRequired = ["requestId", ...required];
+  return {
+    type: "object",
+    properties: {
+      sourcePath: SCRIPTABLE_PACK_SOURCE_PATH_SCHEMA,
+      ownerGuid: SCRIPTABLE_PACK_OWNER_GUID_SCHEMA,
+      requestId: SCRIPTABLE_PACK_REQUEST_ID_SCHEMA,
+      ...properties
+    },
+    required: subjectRequired,
+    ...options.subject === false ? {} : {
+      anyOf: [
+        { required: [...subjectRequired, "sourcePath"] },
+        { required: [...subjectRequired, "ownerGuid"] },
+        ...options.guidSubject === false ? [] : [{ required: [...subjectRequired, "guid"] }]
+      ]
+    },
+    additionalProperties: false
+  };
+}
+var SOURCE_AUTHORING_OPERATION_DESCRIPTORS = [
+  {
+    id: "asset-source.create",
+    kind: "create",
+    domain: "session",
+    title: "Create Asset Source",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        name: SCRIPTABLE_PACK_NAME_SCHEMA,
+        initialOutput: {
+          type: "object",
+          properties: {
+            sourceKey: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA,
+            kind: SCRIPTABLE_PACK_ASSET_KIND_SCHEMA,
+            name: SCRIPTABLE_PACK_NAME_SCHEMA
+          },
+          required: ["sourceKey", "kind"],
+          additionalProperties: false
+        }
+      },
+      ["sourcePath", "initialOutput"],
+      { subject: false }
+    )
+  },
+  {
+    id: "asset-source.add-output",
+    kind: "add-output",
+    domain: "session",
+    title: "Add Asset Source Output",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        sourceKey: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA,
+        assetKind: SCRIPTABLE_PACK_ASSET_KIND_SCHEMA,
+        name: SCRIPTABLE_PACK_NAME_SCHEMA,
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["sourceKey", "assetKind", "expectedRevision"]
+    )
+  },
+  {
+    id: "asset-source.add-external-asset",
+    kind: "add-external-asset",
+    domain: "session",
+    title: "Add Asset Source External Asset",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        alias: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA,
+        guid: { type: "string", format: "uuid" },
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["alias", "guid", "expectedRevision"],
+      { guidSubject: false }
+    )
+  },
+  {
+    id: "asset-source.rename",
+    kind: "rename",
+    domain: "session",
+    title: "Rename Asset Source Display Name",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        target: {
+          oneOf: [
+            {
+              type: "object",
+              properties: { kind: { const: "package" } },
+              required: ["kind"],
+              additionalProperties: false
+            },
+            {
+              type: "object",
+              properties: {
+                kind: { const: "output" },
+                sourceKey: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA
+              },
+              required: ["kind", "sourceKey"],
+              additionalProperties: false
+            }
+          ]
+        },
+        name: SCRIPTABLE_PACK_NAME_SCHEMA,
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["target", "name", "expectedRevision"]
+    )
+  },
+  {
+    id: "asset-source.remove-output",
+    kind: "remove-output",
+    domain: "session",
+    title: "Remove Asset Source Output",
+    destructive: true,
+    argsSchema: scriptablePackArgsSchema(
+      {
+        sourceKey: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA,
+        confirmIncomingRefs: { type: "array", items: { type: "string" } },
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["sourceKey", "expectedRevision"]
+    )
+  },
+  {
+    id: "asset-source.clone",
+    kind: "clone",
+    domain: "session",
+    title: "Clone Asset Source",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        targetPath: SCRIPTABLE_PACK_SOURCE_PATH_SCHEMA,
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["targetPath", "expectedRevision"]
+    )
+  },
+  {
+    id: "asset-source.rebuild",
+    kind: "rebuild",
+    domain: "session",
+    title: "Rebuild Asset Source",
+    argsSchema: scriptablePackArgsSchema({ expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA }, [
+      "expectedRevision"
+    ])
+  },
+  {
+    id: "asset-source.cold-cook",
+    kind: "cold-cook",
+    domain: "session",
+    title: "Cold Cook Asset Source",
+    argsSchema: scriptablePackArgsSchema({ expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA }, [
+      "expectedRevision"
+    ])
+  }
+];
+function actual(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (ArrayBuffer.isView(value)) return value.constructor.name;
+  return typeof value;
+}
+function invalid(propertyPath, expected, value, sourcePath) {
+  return err({
+    code: "pack-source-definition-invalid",
+    expected,
+    hint: "repair the default exported ScriptablePack definition, then inspect Meta again",
+    detail: {
+      ...sourcePath === void 0 ? {} : { sourcePath },
+      propertyPath,
+      actual: actual(value)
+    }
+  });
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isAssetGuid(value) {
+  return value instanceof Uint8Array && value.byteLength === 16;
+}
+function guidKey(guid) {
+  return AssetGuid.format(guid);
+}
+function freezeDefinition(definition) {
+  const assets = Object.fromEntries(
+    Object.entries(definition.assets).map(([sourceKey, descriptor]) => [
+      sourceKey,
+      Object.freeze({ ...descriptor, guid: descriptor.guid.slice() })
+    ])
+  );
+  const externalAssets = Object.fromEntries(
+    Object.entries(definition.externalAssets).map(([alias, guid]) => [
+      alias,
+      guid.slice()
+    ])
+  );
+  return Object.freeze({
+    ...definition,
+    packageId: definition.packageId.slice(),
+    assets: Object.freeze(assets),
+    externalAssets: Object.freeze(externalAssets)
+  });
+}
+function validateScriptablePackDefinition(value, sourcePath) {
+  if (!isRecord(value))
+    return invalid("$", "a ScriptablePack definition object", value, sourcePath);
+  if (value.schemaVersion !== "1.0.0") {
+    return invalid("$.schemaVersion", "the literal '1.0.0'", value.schemaVersion, sourcePath);
+  }
+  if (!isAssetGuid(value.packageId)) {
+    return invalid("$.packageId", "a 16-byte AssetGuid", value.packageId, sourcePath);
+  }
+  if (value.name !== void 0 && typeof value.name !== "string") {
+    return invalid("$.name", "a string when present", value.name, sourcePath);
+  }
+  if (!isRecord(value.assets) || Object.keys(value.assets).length === 0) {
+    return invalid(
+      "$.assets",
+      "a non-empty sourceKey to descriptor object",
+      value.assets,
+      sourcePath
+    );
+  }
+  if (!isRecord(value.externalAssets)) {
+    return invalid(
+      "$.externalAssets",
+      "an alias to AssetGuid object",
+      value.externalAssets,
+      sourcePath
+    );
+  }
+  if (typeof value.build !== "function") {
+    return invalid("$.build", "a build(assetReader) function", value.build, sourcePath);
+  }
+  const packageGuid = guidKey(value.packageId);
+  const localGuids = /* @__PURE__ */ new Set();
+  for (const [sourceKey, descriptor] of Object.entries(value.assets)) {
+    if (sourceKey.trim().length === 0) {
+      return invalid("$.assets", "non-empty sourceKey object keys", sourceKey, sourcePath);
+    }
+    if (!isRecord(descriptor)) {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}]`,
+        "an asset descriptor",
+        descriptor,
+        sourcePath
+      );
+    }
+    if (!isAssetGuid(descriptor.guid)) {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}].guid`,
+        "a 16-byte AssetGuid",
+        descriptor.guid,
+        sourcePath
+      );
+    }
+    if (typeof descriptor.kind !== "string" || !isScriptablePackAssetKind(descriptor.kind)) {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}].kind`,
+        "one of SCRIPTABLE_PACK_ASSET_KINDS",
+        descriptor.kind,
+        sourcePath
+      );
+    }
+    if (descriptor.name !== void 0 && typeof descriptor.name !== "string") {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}].name`,
+        "a string when present",
+        descriptor.name,
+        sourcePath
+      );
+    }
+    const guid = guidKey(descriptor.guid);
+    if (guid === packageGuid || localGuids.has(guid)) {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}].guid`,
+        "a GUID unique within the package and distinct from packageId",
+        descriptor.guid,
+        sourcePath
+      );
+    }
+    localGuids.add(guid);
+  }
+  const externalGuids = /* @__PURE__ */ new Set();
+  for (const [alias, guidValue] of Object.entries(value.externalAssets)) {
+    if (alias.trim().length === 0) {
+      return invalid("$.externalAssets", "non-empty alias object keys", alias, sourcePath);
+    }
+    if (!isAssetGuid(guidValue)) {
+      return invalid(
+        `$.externalAssets[${JSON.stringify(alias)}]`,
+        "a 16-byte AssetGuid",
+        guidValue,
+        sourcePath
+      );
+    }
+    const guid = guidKey(guidValue);
+    if (guid === packageGuid || localGuids.has(guid) || externalGuids.has(guid)) {
+      return invalid(
+        `$.externalAssets[${JSON.stringify(alias)}]`,
+        "a unique foreign GUID not owned by this package",
+        guidValue,
+        sourcePath
+      );
+    }
+    externalGuids.add(guid);
+  }
+  return ok(freezeDefinition(value));
+}
+function projectScriptablePackMeta(definition, source) {
+  const subAssets = Object.entries(definition.assets).sort(([left], [right]) => left.localeCompare(right)).map(([sourceKey, descriptor], sourceIndex) => ({
+    guid: guidKey(descriptor.guid),
+    sourceIndex,
+    sourceKey,
+    kind: descriptor.kind,
+    ...descriptor.name === void 0 ? {} : { name: descriptor.name }
+  }));
+  const externalAssets = Object.entries(definition.externalAssets).sort(([left], [right]) => left.localeCompare(right)).map(([alias, guid]) => ({ alias, guid: guidKey(guid) }));
+  return {
+    schemaVersion: "1.0.0",
+    kind: "external-asset-package",
+    packageId: guidKey(definition.packageId),
+    ...definition.name === void 0 ? {} : { name: definition.name },
+    importer: "pack-ts",
+    source,
+    importSettings: { contractVersion: "1.0.0", externalAssets },
+    subAssets
+  };
+}
+
+export { SCRIPTABLE_PACK_ASSET_KINDS, SOURCE_AUTHORING_OPERATION_DESCRIPTORS, createScriptablePackAuthoringGateway, isScriptablePackAssetKind, projectScriptablePackMeta, validateScriptablePackDefinition };
+//# sourceMappingURL=scriptable-pack.mjs.map
+//# sourceMappingURL=scriptable-pack.mjs.map