@forgeax/game 0.3.3 → 0.3.5

package/README.md

@@ -10,7 +10,7 @@ runtime.
 
 > [!IMPORTANT]
 > The published package carries `forgeax-game` and scoped `game` binary aliases and resolves the exact
-> `@forgeax/engine-sdk@0.1.7` and `pnpm@11.7.0` dependencies. It has no
+> `@forgeax/engine-sdk@0.1.26` and `pnpm@11.7.0` dependencies. It has no
 > `@forgeax/game-runtime` dependency and no static Preview fallback.
 
 ## Supported flow
@@ -44,9 +44,11 @@ cd ./empty-game-directory
 npx -y @forgeax/game init
 ```
 
-The first command writes only the `forgeax` MCP member in the canonical Codex,
+The first command writes the `forgeax` MCP member in the canonical Codex,
 Cursor, and Claude Code user configs. It preserves unrelated bytes and values,
 reports `CURRENT` on an idempotent rerun, and says which host must restart or reload.
+Existing older package-owned Asset3D MCP entries are also refreshed; absent or
+custom Asset3D entries are not added or overwritten.
 The second command must run from the intended blank directory. It creates the Engine
 game there, binds the exact release identity, and reports the canonical root and
 host-skill result. Existing exact games are read back and bound without recreation;
@@ -60,9 +62,13 @@ npx -y @forgeax/game@latest update --ide codex
 ```
 
 `update` reports the configured transition, for example
-`plugin 0.3.2 -> 0.3.3`. It refreshes configuration, skills, and routing from the
+`plugin 0.3.4 -> 0.3.5`. It refreshes configuration, skills, and routing from the
 package being executed; it does not independently fetch another package.
 
+See [0.3.5 compatibility notes](docs/release-0.3.5.md) before upgrading games pinned
+to older Engine versions. This release recognizes strict v2 manifests without
+requiring the removed `entry` field, but does not migrate game dependencies.
+
 > [!NOTE]
 > Asset3D is optional and **disabled by default**. The two commands above never contact
 > the internal asset catalog, provision the bundled platform Provider, or add
@@ -203,8 +209,9 @@ environment contract. The Provider access check returns only the exact download
 origins required by the sandbox. Failed validation or installation rolls back a
 newly written credential.
 
-The npm package carries the digest-pinned Darwin arm64 Provider archive as an inert
-asset. `enable` reuses the exact verified Provider from
+The npm package carries digest-pinned Darwin arm64 and Linux x64 Provider archives
+as inert assets. `enable` selects only the archive matching the current host and
+reuses the exact verified Provider from
 `~/.forgeax/providers/asset3d-search/<sha256>/`, or provisions that packaged archive
 when the cache is absent. It never downloads Provider code from GitHub or another
 repository. Only after Provider verification and its MCP handshake succeed does it merge the `forgeax` and
@@ -278,7 +285,9 @@ and evidence boundaries.
 
 See [docs/runtime.md](docs/runtime.md) for the exact artifact and lifecycle contract.
 For the current AW-default plus explicit EA environment contract and maintainer
-publish checklist, see [docs/release-0.3.3.md](docs/release-0.3.3.md). The original AW
+publish checklist, see [docs/release-0.3.4.md](docs/release-0.3.4.md). The AW-default
+plus explicit EA environment contract was introduced in
+[docs/release-0.3.3.md](docs/release-0.3.3.md). The original AW
 production default is recorded in [docs/release-0.3.2.md](docs/release-0.3.2.md), authenticated Provider
 delivery is documented in [docs/release-0.3.1.md](docs/release-0.3.1.md),
 and the original two-command onboarding contract remains documented in

package/dist/main.js

@@ -342,7 +342,7 @@ function engineGameId(root) {
   try {
     const manifest = JSON.parse(readFileSync(join2(root, "forge.json"), "utf8"));
     const pkg = JSON.parse(readFileSync(join2(root, "package.json"), "utf8"));
-    return typeof manifest.id === "string" && SLUG_RE.test(manifest.id) && typeof manifest.entry === "string" && typeof pkg.dependencies?.["@forgeax/engine"] === "string" ? manifest.id : undefined;
+    return typeof manifest.id === "string" && SLUG_RE.test(manifest.id) && (manifest.schemaVersion === "2.0.0" ? typeof manifest.defaultScene === "string" && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(manifest.defaultScene) : (manifest.schemaVersion === undefined || manifest.schemaVersion === "1.0.0") && typeof manifest.entry === "string") && typeof pkg.dependencies?.["@forgeax/engine"] === "string" ? manifest.id : undefined;
   } catch {
     return;
   }
@@ -710,8 +710,8 @@ import { existsSync as existsSync3, lstatSync as lstatSync3, readFileSync as rea
 import { isAbsolute as isAbsolute2, relative as relative3, resolve as resolve4, sep as sep2 } from "node:path";
 
 // src/engine/constants.ts
-var ENGINE_VERSION = "0.1.7";
-var ENGINE_COMMIT = "984e80ac55b5f4f2afed3211c854b482a4018199";
+var ENGINE_VERSION = "0.1.26";
+var ENGINE_COMMIT = "f3d0db12405e168e4204e32a9cde32e0df8d87ae";
 var ENGINE_SDK_PACKAGE = "@forgeax/engine-sdk";
 var PNPM_VERSION = "11.7.0";
 
@@ -732,7 +732,7 @@ import { createRequire } from "node:module";
 import { basename, delimiter, dirname as dirname4, isAbsolute, relative as relative2, resolve as resolve3, sep } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-var SDK_MANIFEST_SCHEMA = "1.6.0";
+var SDK_MANIFEST_SCHEMA = "1.7.0";
 var SDK_CLI_RELATIVE = ["bin", "forgeax.mjs"];
 var CARRIER_ENVIRONMENT_ALLOWLIST = [
   "HOME",
@@ -1690,7 +1690,7 @@ async function startEnginePreview(projectRoot, gameRoot, options = {}) {
     }
     const token = randomBytes(32).toString("hex");
     const previewInstanceId = randomUUID();
-    const child = spawn(process.execPath, [release.cliPath, "preview", "--json"], {
+    const child = spawn(process.execPath, [release.cliPath, "preview", "--port", "0", "--json"], {
       cwd: release.gameRoot,
       detached: true,
       env: { ...process.env, FORGEAX_PREVIEW_INSTANCE_TOKEN: token },
@@ -2946,12 +2946,12 @@ var RELEASE_IDENTITY_MIME = "application/vnd.forgeax.game-release-identity+json"
 var RELEASE_IDENTITY = Object.freeze({
   schema: RELEASE_IDENTITY_SCHEMA,
   gamePackage: "@forgeax/game",
-  gameVersion: "0.3.3",
+  gameVersion: "0.3.5",
   gameBin: "forgeax-game",
   engineSdkPackage: ENGINE_SDK_PACKAGE,
   engineSdkVersion: ENGINE_VERSION,
   engineSourceCommit: ENGINE_COMMIT,
-  carrierIntegrity: "sha512-f3Nz+ZoIOLVjNeKPock46+gwmC1wOWh9TJupQPl25+wZbIN1dJmki5LK6mNhchPxF7fffarbcFWGMqpKHkjQSw==",
+  carrierIntegrity: "sha512-G5ovsbdzkWWeMfFy3MxVk0qcAvWnZxJnlypMGgxFUDaKr3Wv9uVuhPV88LZ1A9mhFJJSfrE1d5R3WvHgulygRQ==",
   sdkManifestDigest: `sha256:${"0".repeat(64)}`,
   sdkTreeDigest: `sha256:${"0".repeat(64)}`,
   fullZipDigest: `sha256:${"0".repeat(64)}`,
@@ -3356,7 +3356,7 @@ function launchSpec(mode) {
   }
   return {
     command: "npx",
-    args: ["-y", "-p", "@forgeax/game@0.3.3", "forgeax-game", "mcp"]
+    args: ["-y", "-p", "@forgeax/game@0.3.5", "forgeax-game", "mcp"]
   };
 }
 function asset3dLaunchSpec(mode) {
@@ -4275,8 +4275,12 @@ var RECEIPT_SCHEMA_SHA256 = "e0dc9e9fe9872f09af9fca6d0c17d22aca63c2b546c55c0b669
 var ASSET3D_PROVIDER_COMMIT = "c181c48fbffc933a7ce9a0836f7878ca5e6d77e1";
 var BUNDLED_ASSET3D_PROVIDERS = Object.freeze({
   "darwin-arm64": {
-    sha256: "c8d2afd7ba68ae4b3540c927a2ff7133a82ea90975d09cab1d10b003fbbdeed3",
+    sha256: "9492c507a3afe5cafcd50b5f782b313c8716c2e52f5def06592c6a100c0459db",
     relativePath: "asset3d/provider/asset3d-search-provider-c181c48fbffc933a7ce9a0836f7878ca5e6d77e1-darwin-arm64.tar.gz"
+  },
+  "linux-x64": {
+    sha256: "e6ac3df76c8b82f9fe2c063dd3f221324a9dad5176fd52535a5144b0ff6002d8",
+    relativePath: "asset3d/provider/asset3d-search-provider-c181c48fbffc933a7ce9a0836f7878ca5e6d77e1-linux-x64.tar.gz"
   }
 });
 var INSTALL_SCHEMA = "forgeax.asset3d-install/1.0.0";
@@ -5868,7 +5872,7 @@ async function runDormantAsset3dMcp() {
           result: {
             protocolVersion,
             capabilities: { tools: {} },
-            serverInfo: { name: "asset3d-search", version: "0.3.3" }
+            serverInfo: { name: "asset3d-search", version: "0.3.5" }
           }
         };
       } else if (request2.method === "tools/list") {
@@ -6082,6 +6086,38 @@ async function runAsset3dMcpProxy(projectRoot, launch) {
   });
 }
 
+// src/asset3d/host-config.ts
+function inspectAsset3dHost(client, root) {
+  const launch = asset3dLaunchSpec("npx");
+  const status = inspectConfig(client, root, launch, ASSET3D_SERVER_KEY);
+  if (status.state !== "different")
+    return status;
+  const previous = configuredGameVersion(client, root, ASSET3D_SERVER_KEY);
+  const current = launch.args.find((arg) => arg.startsWith("@forgeax/game@"))?.slice("@forgeax/game@".length);
+  if (!previous || !current || !/^\d+\.\d+\.\d+$/.test(previous) || !/^\d+\.\d+\.\d+$/.test(current))
+    return status;
+  const oldParts = previous.split(".").map(Number);
+  const newParts = current.split(".").map(Number);
+  const differing = oldParts.findIndex((part, index) => part !== newParts[index]);
+  if (differing < 0 || oldParts[differing] >= newParts[differing])
+    return status;
+  const oldLaunch = { ...launch, args: launch.args.map((arg) => arg === `@forgeax/game@${current}` ? `@forgeax/game@${previous}` : arg) };
+  if (inspectConfig(client, root, oldLaunch, ASSET3D_SERVER_KEY).state !== "current")
+    return status;
+  return { ...status, state: "outdated" };
+}
+function refreshAsset3dHost(client, root) {
+  const status = inspectAsset3dHost(client, root);
+  if (status.state === "outdated") {
+    const result = applyConfig(client, root, asset3dLaunchSpec("npx"), ASSET3D_SERVER_KEY);
+    process.stdout.write(`UPDATED ${client.label} Asset3D bridge: ${result.path}
+`);
+  } else if (status.state === "different" || status.state === "invalid") {
+    process.stderr.write(`WARN ${client.label}: existing ${ASSET3D_SERVER_KEY} configuration was preserved; it is not a recognized older package launcher.
+`);
+  }
+}
+
 // src/cli/dispatch.ts
 var HELP = `ForgeaX game development plugin
 
@@ -6186,6 +6222,7 @@ async function installCommand(args) {
     }
     try {
       const result = applyConfig(client, project.root ?? process.cwd(), launch);
+      refreshAsset3dHost(client, project.root ?? process.cwd());
       process.stdout.write(`${result.changed ? "UPDATED" : "CURRENT"} ${client.label}: ${result.path}${result.backup ? ` (backup: ${result.backup})` : ""}
 `);
       if (client.postInstallNote)
@@ -6565,6 +6602,7 @@ async function updateCommand(args) {
   for (const client of configured) {
     const previousVersion = configuredGameVersion(client, root);
     const result = applyConfig(client, root, launch);
+    refreshAsset3dHost(client, root);
     process.stdout.write(`${result.changed ? "UPDATED" : "CURRENT"} ${client.label}: ${result.path} (plugin ${formatVersionTransition(previousVersion)})
 `);
   }
@@ -6687,7 +6725,7 @@ async function asset3dCommand(args) {
         const client = findClient(id);
         if (!client)
           throw new Error(`asset3d_client_invalid: ${id}`);
-        const state = inspectConfig(client, projectRoot, bridge, ASSET3D_SERVER_KEY);
+        const state = inspectAsset3dHost(client, projectRoot);
         if (state.state === "different") {
           throw new Error(`asset3d_client_server_conflict: ${client.label} already has a different ${ASSET3D_SERVER_KEY} entry`);
         }

package/docs/asset3d.md

@@ -14,11 +14,13 @@ second importer or Preview server.
 
 > [!IMPORTANT]
 > Provider archives are platform-specific artifacts. The npm package embeds the
-> currently released Darwin arm64 archive so a cache-empty user does not depend on a
-> private source repository or release download. Installation deliberately returns
+> currently released Darwin arm64 and Linux x64 archives so a cache-empty user does
+> not depend on a private source repository or release download. Linux requires an
+> x86-64 host and Python 3.11 or 3.12. Installation deliberately returns
 > `provider_platform_mismatch` when an archive target differs from the current host.
-> Each bundled target therefore needs its own digest, offline verification, MCP
-> handshake, and real service-path evidence.
+> Unsupported targets such as Linux arm64 and Windows fail closed. Each bundled
+> target therefore needs its own digest, offline verification, MCP handshake, and
+> real service-path evidence.
 
 ## Trust and data flow
 
@@ -178,11 +180,12 @@ successful; `asset3d abort` removes only its transaction quarantine.
 ## Distribution and evidence boundary
 
 The packed Game Plugin includes the self-contained CLI bundle, existing connector
-Skill, exact K0 TGZ, checked P0 result/receipt schemas, and the immutable URL/digest
-table for supported Provider targets. It does not embed the Provider runtime archive,
-Engine payload, source checkout, credentials, or workspace links. Provider archives
-are separate release assets so a disabled installation downloads nothing. The package
-artifact gate recomputes every embedded predecessor digest.
+Skill, exact K0 TGZ, checked P0 result/receipt schemas, and an inert, digest-pinned
+Provider archive for every supported target. It does not embed a provisioned Python
+environment, managed Provider cache, Engine payload, source checkout, credentials, or
+workspace links. A disabled installation neither extracts an archive nor contacts a
+network service. The package artifact gate recomputes every embedded predecessor
+digest.
 
 Controlled external-consumer evidence may establish package installation, raw MCP
 framing, local redirect/ZIP handling, multi-GLB and texture import, reuse, refresh,

package/docs/release-0.3.4.md

@@ -0,0 +1,66 @@
+# @forgeax/game 0.3.4 release contract
+
+Version `0.3.4` adds a self-contained Linux x64 Asset3D Provider while preserving
+the existing opt-in workflow. Ordinary `install` and `init` remain platform-neutral
+and keep Asset3D disabled. A user enables Asset3D only from an initialized game:
+
+```bash
+npx -y @forgeax/game@0.3.4 asset3d enable
+npx -y @forgeax/game@0.3.4 asset3d doctor --json
+```
+
+## Supported Provider targets
+
+| Host | Provider archive SHA-256 | Status |
+|---|---|---|
+| Darwin arm64 | `9492c507a3afe5cafcd50b5f782b313c8716c2e52f5def06592c6a100c0459db` | Supported |
+| Linux x64 | `e6ac3df76c8b82f9fe2c063dd3f221324a9dad5176fd52535a5144b0ff6002d8` | Supported; Python 3.11 or 3.12 required |
+
+Both archives bind Provider commit
+`c181c48fbffc933a7ce9a0836f7878ca5e6d77e1`. The package build fails if either
+source archive is absent, is a symlink, or differs from its approved digest. The npm
+artifact gate repeats those checks against the packed bytes.
+
+The offline wheelhouses omit upstream dependency test suites and redact
+credential-shaped user-info from dependency documentation examples. Runtime modules
+and package metadata remain present, each rewritten wheel is re-RECORDed and
+hash-locked, and the resulting platform archives are byte-reproducible. This keeps
+test-only public tokens and false credential patterns out of the npm payload.
+
+Linux arm64 and Windows are not part of this release. `asset3d enable` fails closed
+with `asset3d_provider_target_unreleased` on those hosts; it does not install a
+different target or fall back to downloaded Provider code.
+
+## Linux release gate
+
+The Ubuntu x64 CI job performs the Linux-specific verification from the same package
+assets that are published:
+
+1. Provision the Provider into an empty managed cache without downloading Provider
+   code or Python dependencies.
+2. Verify the archive manifest, target, file digests, wheel lock, and converter.
+3. Execute the bundled Linux x64 `FBX2glTF` binary.
+4. Launch the installed Provider over stdio MCP and require `search_asset` in
+   `tools/list`.
+
+This proves Linux provisioning and MCP capability discovery. It does not substitute
+for an authenticated request to the internal AW service, which requires network
+reachability and user credentials and remains a separate environment acceptance
+gate.
+
+## Maintainer checklist
+
+- [ ] `bun run typecheck`
+- [ ] `bun test`
+- [ ] `bun run build`
+- [ ] `npm pack --ignore-scripts --pack-destination <empty-directory>`
+- [ ] `bun run release:check -- <exact-tarball>`
+- [ ] Ubuntu x64 `asset3d-linux-x64` CI job is green on the exact release commit.
+- [ ] The packed artifact contains both Provider archives and no credential, source
+      checkout, managed cache, or provisioned Python environment.
+- [ ] The exact tarball passes the repository secret and private-path scans before
+      publication.
+
+The AW production default and explicit EA override remain as documented in
+[`release-0.3.3.md`](release-0.3.3.md). Credential storage and real search/import
+acceptance boundaries remain unchanged and are defined in [`asset3d.md`](asset3d.md).

package/docs/release-0.3.5.md

@@ -0,0 +1,32 @@
+# @forgeax/game 0.3.5
+
+## Compatibility repair
+
+| Boundary | Release behavior |
+|:--|:--|
+| Engine SDK | Exact dependency 0.1.26, commit `f3d0db12405e168e4204e32a9cde32e0df8d87ae` |
+| Project discovery | Recognizes strict `forge.json` v2 with `defaultScene`; does not inject the forbidden legacy `entry` field |
+| SDK manifest | Validates the released 1.7.0 manifest and exact Engine/DevKit identities |
+| Preview | Uses Engine-owned `--port 0` allocation instead of conflicting with another game on port 5173 |
+| Asset3D upgrade | Refreshes existing older package-owned bridges during install/update; preserves custom configurations |
+
+## Install or update
+
+```bash
+npx -y @forgeax/game@0.3.5 install --ide codex,cursor,claude
+# In a genuinely empty game directory:
+npx -y @forgeax/game@0.3.5 init
+```
+
+For an existing Engine 0.1.26 project, run `update --ide codex` with this package,
+then restart the host session. Asset3D remains opt-in with `asset3d enable`.
+
+> [!IMPORTANT]
+> This release pins Engine 0.1.26. It does not silently migrate games using Engine
+> 0.1.7. Keep those games on plugin 0.3.4 until deliberately migrating through the
+> Engine-supported workflow. Do not add `entry` to a v2 manifest to work around the
+> old plugin's project detection.
+
+The plugin must return Engine-owned Preview readiness and matching root/build
+identity. A direct Engine CLI preview or a listening port alone is not MCP
+acceptance. Asset search/import and visible gameplay require separate verification.

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "bun@1.3.14",
   "name": "@forgeax/game",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "private": false,
   "type": "module",
   "description": "@forgeax/game — an MCP/CLI connector for exact released ForgeaX Engine games and Engine-owned Preview.",
@@ -25,6 +25,8 @@
     "docs/release-0.3.1.md",
     "docs/release-0.3.2.md",
     "docs/release-0.3.3.md",
+    "docs/release-0.3.4.md",
+    "docs/release-0.3.5.md",
     "README.md"
   ],
   "scripts": {
@@ -32,6 +34,7 @@
     "release:check": "bun scripts/check-package-artifact.ts",
     "acceptance": "bun scripts/accept-packed-consumer.ts",
     "acceptance:asset3d": "bun scripts/accept-asset3d-packed-consumer.ts",
+    "verify:asset3d-linux": "bun scripts/verify-linux-asset3d-provider.ts",
     "release:publish": "bun scripts/publish-package.ts",
     "prepack": "bun build.mjs",
     "typecheck": "tsc --noEmit",
@@ -49,7 +52,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@forgeax/engine-sdk": "0.1.7",
+    "@forgeax/engine-sdk": "0.1.26",
     "pnpm": "11.7.0"
   },
   "devDependencies": {