@forgeax/engine-pack 0.1.27 → 0.1.29

package/README.md

@@ -37,11 +37,22 @@ export default definePack({
   build: ({ packageId: subjectId }) =>
     ok({
       'mesh/main': { kind: 'mesh', materialSlots: [] },
+      'scene/hero': {
+        kind: 'scene',
+        entities: { body: { components: {} } },
+      },
       'scene/main': {
         kind: 'scene',
-        entities: [],
-        mounts: [],
-        mesh: AssetGuid.format(AssetGuid.derive(subjectId, 'mesh/main')),
+        entities: {
+          root: { components: {} },
+          hero: {
+            components: {},
+            instance: {
+              source: AssetGuid.format(AssetGuid.derive(subjectId, 'scene/hero')),
+              overrides: [{ target: ['body'], components: {} }],
+            },
+          },
+        },
       },
     }),
 });
@@ -147,8 +158,8 @@ source.
 
 | Need | Entry | Safe action |
 |:--|:--|:--|
-| Inspect one asset | `forgeax-engine-remote-asset lookup --guid ... --project ... --catalog ... --json` | Read structured evidence and diagnostics |
-| Verify a result | `forgeax-engine-remote-asset verify --guid ... --project ... --catalog ... --json` | Repair the producer or package, then retry |
+| Inspect one asset | `forgeax asset inspect --subject <guid> --root <project> --json` | Read structured evidence and diagnostics |
+| Verify a result | `forgeax asset verify --root <project> --json` | Repair the producer or package, then retry |
 | Rebuild a cooked result | Pack/import runner and the declared producer | Cold cook after discarding invalid DDC |
 | Preview old output | Catalog evidence with explicit last-known-good state | Preview only; never publish it as current |
 
@@ -191,7 +202,7 @@ sampler、强度或非默认坐标等附加元数据才使用结构化纹理对
 > package moves and DDC relocation. Paths and array positions are locators,
 > not identities.
 
-Disk schema, GUID tools (`AssetGuid` brand + UUIDv7/v5), mesh-binary wire facts, and scanner fail-fast chain (13-member `PackErrorCode`) for the forgeax engine asset package system. The three CLI surfaces -- `scan`, `lookup`, `verify` -- are shipped as the standalone plugin bin `forgeax-engine-remote-asset` (resolved via PATH-prefix discovery for `forgeax-engine-remote-`; filesystem-mode; offline; no WS connection required).
+Disk schema, GUID tools (`AssetGuid` brand + UUIDv7/v5), mesh-binary wire facts, and scanner fail-fast chain (13-member `PackErrorCode`) for the ForgeaX asset package system. The unified `asset list`, `asset inspect`, and `asset verify` commands call this owner in filesystem mode; they are offline and require no WS connection.
 
 > Package name vs directory: this package is published as `@forgeax/engine-pack` but lives at `packages/pack` on disk. The `@forgeax/engine-` prefix is the IDE-autocomplete entrypoint AI users discover the package family by; the directory drops the prefix to keep tree depth flat (mirrors the `packages/runtime` / `@forgeax/engine-runtime` pair). All other packages in the engine family follow the same convention.
 
@@ -201,9 +212,10 @@ Pack owns the offline half of the GUID evidence chain: `source inventory -> cata
 
 The catalog is a locator, not proof. `lookup/verify --guid --project --catalog --json` joins the source meta or authored pack, the catalog row, the receipt, and the package descriptors. Both commands emit one JSON record on stdout or one structured `{code, expected, hint, detail}` record on stderr; there is no runtime or WebSocket dependency.
 
-## VFX Pack v2 migration
+## VFX Program v3 in Pack v2
 
-VFX source v2 is cooked in one atomic producer step. The executable contract is
+VFX source v3 is cooked in one atomic producer step and stored in the ordinary
+Pack v2 envelope. The executable contract is
 `scripts/asset-cook-contract.mjs`; a package-local scripts path is not valid.
 The cook publishes the Pack payload and
 `particle-effect/program.json` with the same source fingerprint. Runtime loads
@@ -266,7 +278,7 @@ vectors, colors, and asset-GUID constraints. The isolated Pack worker passes
 only serializable authoring data to the build and never exposes filesystem or
 runtime state.
 
-`forgeax-engine-remote-asset meta <source.pack.ts> --json` executes module initialization, validates the default export, and projects canonical Meta without calling `build`. `@forgeax/engine-pack/source-node` accepts a host executor with `load` and optional `dispose`; `timeoutMs` bounds module initialization and `buildTimeoutMs` bounds one `build(context)` call. A build timeout returns one structured `pack-source-load-failed` Result with `detail.phase: 'build'`, the configured `timeoutMs`, and deterministic cleanup of the isolated worker and compile root.
+`forgeax asset inspect --subject <source.pack.ts> --root <project> --json` executes module initialization, validates the default export, and projects canonical Meta without calling `build`. `@forgeax/engine-pack/source-node` accepts a host executor with `load` and optional `dispose`; `timeoutMs` bounds module initialization and `buildTimeoutMs` bounds one `build(context)` call. A build timeout returns one structured `pack-source-load-failed` Result with `detail.phase: 'build'`, the configured `timeoutMs`, and deterministic cleanup of the isolated worker and compile root.
 
 The default worker executes the complete relative TypeScript module closure on the supported Node floor, including Node 22 hosts that do not load `.ts` files directly. It transpiles that closure into a disposable ESM directory, resolves bare imports through the source project's nearest `node_modules`, and removes the directory when the worker is disposed. Bulk producers use the internal `createScriptablePackModuleExecutorPool()` with two recyclable workers; a pooled lease is released after metadata projection or one build, so a generation never retains one live Worker-backed definition per source.
 
@@ -460,21 +472,22 @@ Exhaustive `switch (err.code)` without `default` -- TS guards completeness.
 
 Access `err.detail.<field>` directly after narrowing via `switch (err.code)` -- full IDE autocomplete.
 
-## CLI plugin -- `forgeax-engine-remote-asset`
+## Unified asset commands
 
-The CLI subcommands ship as a standalone plugin bin `forgeax-engine-remote-asset` (entry `dist/cli-asset.mjs`) declared in this package's `package.json#bin`, discovered via PATH-prefix scan for `forgeax-engine-remote-`.
+DevKit loads the Pack producer behind the unified `forgeax asset` command;
+this package does not publish an independent executable.
 
 | Subcommand | Description | Exit code |
 |:--|:--|:--|
-| `forgeax-engine-remote-asset scan [--roots <dir>...]` | Print JSON array of all discovered `PackEntry` objects to stdout | 0 always |
-| `forgeax-engine-remote-asset lookup <guid>` | Print matching `PackEntry` as JSON to stdout (cwd as scan root) | 0 found / 1 not found |
-| `forgeax-engine-remote-asset verify [--strict]` | Run fail-fast 7-step scanner; print `PackError` JSON to stderr on first failure; prints `material-validated: <N>` count at end | 0 clean / 1 error |
+| `forgeax asset list --root <project> --json` | Print discovered `PackEntry` objects | 0 on valid roots |
+| `forgeax asset inspect --subject <guid> --root <project> --json` | Print matching asset evidence | 0 found / 1 not found |
+| `forgeax asset verify --root <project> --json` | Run the fail-fast scanner and return the first structured `PackError` | 0 clean / 1 error |
 
 ```bash
 # Direct invocation (after pnpm -F @forgeax/engine-pack build)
-forgeax-engine-remote-asset scan --roots apps/hello/room/assets
-forgeax-engine-remote-asset lookup 01935f3b-aaaa-7000-8000-000000000001
-forgeax-engine-remote-asset verify --strict
+forgeax asset list --root ./game --json
+forgeax asset inspect --subject 01935f3b-aaaa-7000-8000-000000000001 --root ./game --json
+forgeax asset verify --root ./game --json
 ```
 
 ## Scanner 7-step validation chain

package/dist/build.mjs

@@ -8450,7 +8450,7 @@ var meta_schema_default = {
   properties: {
     schemaVersion: {
       oneOf: [{ type: "string" }, { type: "integer" }],
-      description: "Schema version. Strings (e.g. '1.0.0') for hand-authored .meta.json; integers (1, 2, ...) for importer-emitted .meta.json (forgeax-engine-remote-asset import writes schemaVersion: 1 as the wire format SSOT, GltfMetaJson literal type)."
+      description: "Schema version. Strings (e.g. '1.0.0') for hand-authored .meta.json; integers (1, 2, ...) for importer-emitted .meta.json (forgeax asset import writes schemaVersion: 1 as the wire format SSOT, GltfMetaJson literal type)."
     },
     kind: {
       type: "string",
@@ -9061,9 +9061,17 @@ var WorkerScriptablePackExecutor = class {
         }
       };
       worker.on("message", onMessage);
-      worker.once("error", rejectLoad);
+      const fail = (error) => {
+        rejectLoad(error);
+        const active = this.build;
+        this.build = void 0;
+        active?.reject(error);
+        void this.dispose("failure");
+      };
+      worker.once("error", fail);
       worker.once("exit", (code) => {
-        if (code !== 0) rejectLoad(new Error(`ScriptablePack worker exited with code ${code}`));
+        if (this.disposal !== void 0) return;
+        fail(new Error(`ScriptablePack worker exited with code ${code}`));
       });
     });
   }
@@ -9298,16 +9306,17 @@ function makePackError(code, detail) {
     detail
   });
 }
-function* extractMountSourceGuids(asset) {
+function* extractInstanceSourceGuids(asset) {
   if (asset.kind !== "scene") return;
   const payload = asset.payload;
-  if (!payload || !Array.isArray(payload.mounts)) return;
-  for (const rawMount of payload.mounts) {
-    const mount = rawMount;
-    const idx = mount.source;
-    if (typeof idx !== "number" || !Number.isInteger(idx)) continue;
-    if (idx < 0 || idx >= asset.refs.length) continue;
-    const resolved = asset.refs[idx];
+  if (!payload || payload.entities === null || typeof payload.entities !== "object" || Array.isArray(payload.entities))
+    return;
+  for (const rawEntity of Object.values(payload.entities)) {
+    if (rawEntity === null || typeof rawEntity !== "object" || Array.isArray(rawEntity)) continue;
+    const instance = rawEntity.instance;
+    if (instance === null || typeof instance !== "object" || Array.isArray(instance)) continue;
+    const source = instance.source;
+    const resolved = typeof source === "number" && Number.isInteger(source) ? asset.refs[source] : typeof source === "string" ? source : void 0;
     if (typeof resolved !== "string") continue;
     yield resolved.toLowerCase();
   }
@@ -9425,7 +9434,7 @@ async function scanValidated(roots, opts = {}, capture) {
           guidToPath.set(normalizedGuid, packPath);
           packRefs.set(normalizedGuid, [
             ...asset.refs.map((ref) => ref.toLowerCase()),
-            ...extractMountSourceGuids(asset)
+            ...extractInstanceSourceGuids(asset)
           ]);
         }
       }
@@ -9529,7 +9538,7 @@ async function scanValidated(roots, opts = {}, capture) {
       guidToPath.set(normalizedGuid, packPath);
       packRefs.set(normalizedGuid, [
         ...asset.refs.map((ref) => ref.toLowerCase()),
-        ...extractMountSourceGuids(asset)
+        ...extractInstanceSourceGuids(asset)
       ]);
     }
     capture?.declarations.set(packPath, {
@@ -10714,9 +10723,9 @@ function projectAssetRefs(inventory) {
 }
 function projectSceneEntityRefs(inventory) {
   return inventory.declarations.flatMap(
-    (row) => row.sceneBindings === void 0 ? [] : row.sceneBindings.map((bindingKey) => ({
+    (row) => row.sceneEntityKeys === void 0 ? [] : row.sceneEntityKeys.map((address) => ({
       sceneSourceKey: row.sourceKey,
-      bindingKey
+      address
     }))
   );
 }
@@ -10776,49 +10785,23 @@ function validateAuthorInventory(value) {
         { guid, sourceKey: sourceKey2 }
       );
     }
-    if (row.kind === "scene") {
-      const payload = row.payload;
-      const payloadRecord = typeof payload === "object" && payload !== null ? payload : void 0;
-      const entities = payloadRecord !== void 0 && Array.isArray(payloadRecord.entities) ? payloadRecord.entities : [];
-      const bindings = /* @__PURE__ */ new Set();
-      for (const entity of entities) {
-        const bindingKey = typeof entity === "object" && entity !== null && typeof entity.bindingKey === "string" ? entity.bindingKey : void 0;
-        if (bindingKey !== void 0 && bindingKey.length === 0) {
-          return failure2(
-            "inventory-scene-binding-missing",
-            "each declared scene bindingKey is non-empty",
-            "remove the empty bindingKey or declare a stable key in the scene producer",
-            { sourceKey: sourceKey2 }
-          );
-        }
-        if (bindingKey === void 0) continue;
-        if (bindings.has(bindingKey)) {
-          return failure2(
-            "inventory-scene-binding-duplicate",
-            "bindingKey values are unique within one scene",
-            "rename the duplicate bindingKey in the scene producer",
-            { sourceKey: sourceKey2 }
-          );
-        }
-        bindings.add(bindingKey);
-      }
-    }
     guids.add(normalizedGuid);
     sourceKeys.add(sourceKey2);
-    const sceneBindings = row.kind === "scene" && typeof row.payload === "object" && row.payload !== null ? row.payload.entities?.flatMap(
-      (entity) => {
-        if (typeof entity !== "object" || entity === null) return [];
-        const key = entity.bindingKey;
-        return typeof key === "string" && key.length > 0 ? [key] : [];
-      }
-    ) : void 0;
+    const sceneEntityKeys = (() => {
+      if (row.kind !== "scene" || typeof row.payload !== "object" || row.payload === null)
+        return void 0;
+      const entities = row.payload.entities;
+      if (entities === null || typeof entities !== "object" || Array.isArray(entities))
+        return void 0;
+      return Object.keys(entities);
+    })();
     declarations.push({
       guid,
       sourceKey: sourceKey2,
       kind: typeof row.kind === "string" ? row.kind : "unknown",
       payload: typeof row.payload === "object" && row.payload !== null ? row.payload : {},
       refs: Array.isArray(row.refs) ? row.refs.filter((ref) => typeof ref === "string") : [],
-      ...sceneBindings === void 0 ? {} : { sceneBindings }
+      ...sceneEntityKeys === void 0 ? {} : { sceneEntityKeys }
     });
   }
   return ok({ declarations });
@@ -10827,7 +10810,7 @@ function validateAuthorInventory(value) {
 // src/inventory/sync.ts
 function inventoryDigest(inventory) {
   return inventory.declarations.map(
-    (row) => `${row.guid}\0${row.sourceKey}\0${row.kind}\0${row.sceneBindings?.join("\0") ?? ""}`
+    (row) => `${row.guid}\0${row.sourceKey}\0${row.kind}\0${row.sceneEntityKeys?.join("\0") ?? ""}`
   ).sort().join("\n");
 }
 function syncAuthorInventory(inventory) {
@@ -10835,7 +10818,7 @@ function syncAuthorInventory(inventory) {
     declarations: inventory.declarations.map((row) => ({
       ...row,
       refs: [...row.refs],
-      ...row.sceneBindings === void 0 ? {} : { sceneBindings: [...row.sceneBindings] }
+      ...row.sceneEntityKeys === void 0 ? {} : { sceneEntityKeys: [...row.sceneEntityKeys] }
     }))
   };
 }