@forgeax/engine-devkit 0.1.3 → 0.1.4

package/dist/index.mjs

@@ -10,7 +10,10 @@ import { fbxImporter } from '@forgeax/engine-fbx';
 import { fontImporter } from '@forgeax/engine-font/font-importer';
 import { gltfImporter } from '@forgeax/engine-gltf';
 import { imageImporter } from '@forgeax/engine-image/image-importer';
+import { BUILTIN_MESH_ASSETS } from '@forgeax/engine-pack/builtin';
+import { scanInventory } from '@forgeax/engine-pack/scanner';
 import { validatePreviewArtifactManifest, createMaterialPreviewContribution, createMeshPreviewContribution, createVfxPreviewContribution, createTexturePreviewContribution, describeResourcePreviewFailure, validateCanonicalKitReceipt } from '@forgeax/engine-preview';
+import { createMaterialPackCooker } from '@forgeax/engine-shader-compiler';
 import { err, ok, createStandaloneRuntimeAssetBinding } from '@forgeax/engine-types';
 import { createParticleCodeNativeCookerFromRoots } from '@forgeax/engine-vfx-compiler';
 import { pluginPack, reloadAssetHost } from '@forgeax/engine-vite-plugin-pack';
@@ -20,9 +23,9 @@ import { runCliGltf } from '@forgeax/engine-gltf/cli-gltf';
 import { scanEntries } from '@forgeax/engine-pack/cli-asset';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 import { execFile } from 'child_process';
+import { tmpdir } from 'os';
 import { promisify } from 'util';
 import { createRhiDebugError, decodeTape, openReplay, buildFrameModel } from '@forgeax/engine-rhi-debug';
-import { tmpdir } from 'os';
 import { build, createServer, preview } from 'vite';
 import { startVitest } from 'vitest/node';
 import materialPreviewPlugin from '@forgeax/engine-preview/material';
@@ -323,6 +326,42 @@ function isResourcePreviewIgnoredPath(path) {
 function isProjectSourceIgnoredPath(path) {
   return ignoreDevKitCatalogPath(path) || path.endsWith(".wgsl.meta.json");
 }
+async function prepareBuiltinPack(projectRoots, generated, ignorePath) {
+  const inventory = await scanInventory(projectRoots, { ignorePath });
+  if (!inventory.ok) return void 0;
+  const declared = /* @__PURE__ */ new Set();
+  for (const declaration of inventory.value.declarations.values()) {
+    if (declaration.format === "pack.json") {
+      for (const asset of declaration.value.assets) declared.add(asset.guid.toLowerCase());
+      continue;
+    }
+    for (const asset of declaration.value.subAssets) declared.add(asset.guid.toLowerCase());
+  }
+  const missing = BUILTIN_MESH_ASSETS.filter((asset) => !declared.has(asset.guid.toLowerCase()));
+  if (missing.length === 0) return void 0;
+  const packPath = resolve(generated, "engine-builtins.pack.json");
+  await writeFile(
+    packPath,
+    `${JSON.stringify(
+      {
+        schemaVersion: "2.0.0",
+        kind: "internal-text-package",
+        assets: missing.map((asset) => ({
+          guid: asset.guid,
+          kind: "mesh",
+          payload: { geometry: asset.geometry },
+          refs: [],
+          artifacts: {}
+        }))
+      },
+      null,
+      2
+    )}
+`,
+    "utf8"
+  );
+  return packPath;
+}
 function findEngineWorkspaceRoot() {
   let cursor = dirname(fileURLToPath(import.meta.url));
   for (; ; ) {
@@ -338,6 +377,7 @@ async function engineWorkspacePackages() {
     const workspaceRoot = findEngineWorkspaceRoot();
     if (workspaceRoot === void 0) return /* @__PURE__ */ new Map();
     const packageRoot = resolve(workspaceRoot, "packages");
+    if (!existsSync(packageRoot)) return /* @__PURE__ */ new Map();
     const packages = /* @__PURE__ */ new Map();
     for (const entry of await readdir(packageRoot, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
@@ -432,6 +472,18 @@ async function createEngineWorkspaceResolver() {
     }
   };
 }
+async function consumerEngineAliases(projectRoot) {
+  const root = resolve(projectRoot, "node_modules", ".pnpm", "node_modules", "@forgeax");
+  try {
+    const entries2 = await readdir(root, { withFileTypes: true });
+    return entries2.filter((entry) => entry.isDirectory() && entry.name.startsWith("engine-")).map((entry) => ({
+      find: `@forgeax/${entry.name}`,
+      replacement: resolve(root, entry.name)
+    })).sort((a, b) => a.find.localeCompare(b.find));
+  } catch {
+    return [];
+  }
+}
 async function resolveCanonicalKit() {
   const packageJson = hostRequire.resolve("@forgeax/engine-preview/package.json");
   const root = resolve(packageJson, "..", "assets/canonical-kit");
@@ -506,6 +558,7 @@ function hostSource(facts, bootstrapRoot, canonicalEnvironmentGuid) {
   const plugins = bootstrapRoot === "resource-bootstrap" ? [] : [
     `webAudioPlugin()`,
     `audioPlugin()`,
+    `skinningPlugin()`,
     ...facts.physics === void 0 ? [] : [`physicsPlugin('${facts.physics === "2d" ? "rapier-2d" : "rapier-3d"}')`]
   ];
   const bootstrapPlugin = facts.bootstrapEntry === void 0 ? "" : `const bootstrapModule = await import(${JSON.stringify(
@@ -523,20 +576,21 @@ await app.pluginContext.plugin({
   },
 });`;
   return `import { forgeaxBundlerAdapter } from 'virtual:forgeax/bundler';
-import { createApp, createToolPreviewHost, createToolPreviewRecipe, fitToolPreviewCameraToAabb, gameHostPlugin, replayToolPreviewCapture } from '@forgeax/engine-app';
-import { createCatalogSource } from '@forgeax/engine-assets-runtime';
-import { installCatalogLoader, projectPluginEntries } from '@forgeax/engine-plugin/loader';
-import { audioPlugin } from '@forgeax/engine-audio';
-import { webAudioPlugin } from '@forgeax/engine-audio-webaudio';
-import { physicsPlugin } from '@forgeax/engine-physics';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import { createDevImportTransport } from '@forgeax/engine-runtime';
-import { mat4 } from '@forgeax/engine-math';
-import { CAMERA_PROJECTION_ORTHOGRAPHIC, Camera, DirectionalLight, Materials, MeshFilter, MeshRenderer, Skylight, SkyboxBackground, TONEMAP_NONE, TONEMAP_REINHARD_EXTENDED } from '@forgeax/engine-render';
-import { projectSceneAsset, Transform, worldInstantiateScene } from '@forgeax/engine-scene';
-import { createStandaloneRuntimeAssetBinding } from '@forgeax/engine-types';
-import { ParticleEffectPlayer, vfxGpuEffectContribution } from '@forgeax/engine-vfx';
-import { createVfxRuntimeHost } from '@forgeax/engine-vfx-render';
+import { createApp, createToolPreviewHost, createToolPreviewRecipe, fitToolPreviewCameraToAabb, gameHostPlugin, replayToolPreviewCapture } from '@forgeax/engine/app';
+import { createCatalogSource } from '@forgeax/engine/assets-runtime';
+import { installCatalogLoader, projectPluginEntries } from '@forgeax/engine/plugin/loader';
+import { audioPlugin } from '@forgeax/engine/audio';
+import { webAudioPlugin } from '@forgeax/engine/audio-webaudio';
+import { physicsPlugin } from '@forgeax/engine/physics';
+import { skinningPlugin } from '@forgeax/engine/skinning';
+import { createPrimitiveMesh } from '@forgeax/engine/geometry';
+import { createDevImportTransport } from '@forgeax/engine/runtime';
+import { mat4 } from '@forgeax/engine/math';
+import { CAMERA_PROJECTION_ORTHOGRAPHIC, Camera, DirectionalLight, Materials, MeshFilter, MeshRenderer, Skylight, SkyboxBackground, TONEMAP_NONE, TONEMAP_REINHARD_EXTENDED } from '@forgeax/engine/render';
+import { projectSceneAsset, Transform, worldInstantiateScene } from '@forgeax/engine/scene';
+import { createStandaloneRuntimeAssetBinding } from '@forgeax/engine/types';
+import { ParticleEffectPlayer, vfxGpuEffectContribution } from '@forgeax/engine/vfx';
+import { createVfxRuntimeHost } from '@forgeax/engine/vfx-render';
 
 const pluginCatalog = new Map([
 ${catalogModules(facts).map(
@@ -635,15 +689,16 @@ const resizeCanvas = () => {
 const resizeObserver = new ResizeObserver(resizeCanvas);
 resizeObserver.observe(canvas);
 resizeCanvas();
-const binding = import.meta.env.DEV
-  ? createStandaloneRuntimeAssetBinding(${JSON.stringify(facts.id)})
-  : undefined;
-const assetCatalog = binding === undefined
-  ? undefined
-  : createCatalogSource({ url: binding.catalogUrl, expectedScope: binding });
+const runtimeScopeBinding = createStandaloneRuntimeAssetBinding(${JSON.stringify(facts.id)});
+const assetCatalog = createCatalogSource({
+  url: import.meta.env.DEV
+    ? runtimeScopeBinding.catalogUrl
+    : new URL('pack-index.json', document.baseURI).href,
+  expectedScope: runtimeScopeBinding,
+});
 const bundler = {
   ...forgeaxBundlerAdapter(),
-  ...(binding === undefined ? {} : { importTransport: createDevImportTransport(binding) }),
+  ...(import.meta.env.DEV ? { importTransport: createDevImportTransport(runtimeScopeBinding) } : {}),
 };
 
 function previewStable(value) {
@@ -1022,12 +1077,18 @@ if (query.has('forgeax-tool-replay')) {
     window.addEventListener('pagehide', () => void host.value.dispose(), { once: true });
   }
 } else {
+  // WebDriver/headless browsers cannot satisfy the trusted-gesture requirement
+  // for pointer lock. Keep the game running and let its keyboard fallback own
+  // camera input; real browser users retain the normal click-to-lock path.
+  const pointerLockAllowed =
+    typeof navigator !== 'undefined' && navigator.webdriver === true ? () => false : undefined;
   const result = await createApp(
     canvas,
     {
       ...(assetCatalog === undefined ? {} : { assetCatalog }),
       ...(vfxRuntimeHost === undefined ? {} : { assetDecoders: [vfxGpuEffectContribution] }),
       plugins: [${plugins.join(", ")}],
+      ...(pointerLockAllowed === undefined ? {} : { pointerLockAllowed }),
     },
     bundler,
   );
@@ -1086,10 +1147,32 @@ function htmlSource(title) {
     <div id="app-shell"><canvas id="app"></canvas><div id="game-ui"></div></div><div id="forgeax-fatal" role="alert"></div>
     <script>
       (() => {
+        const formatStartupFailure = (reason) => {
+          if (reason instanceof Error) return reason.message;
+          if (reason !== null && typeof reason === 'object') {
+            const record = reason;
+            const lines = [];
+            for (const key of ['code', 'expected', 'hint']) {
+              if (typeof record[key] === 'string' && record[key].length > 0) {
+                lines.push(key + ': ' + record[key]);
+              }
+            }
+            const detail = record.detail;
+            if (detail !== null && typeof detail === 'object') {
+              for (const key of ['reason', 'guid']) {
+                if (typeof detail[key] === 'string' && detail[key].length > 0) {
+                  lines.push('detail.' + key + ': ' + detail[key]);
+                }
+              }
+            }
+            if (lines.length > 0) return lines.join('\\n');
+          }
+          return String(reason ?? 'Unknown startup failure');
+        };
         const show = (reason) => {
           const notice = document.querySelector('#forgeax-fatal');
           if (!(notice instanceof HTMLElement)) return;
-          const message = reason instanceof Error ? reason.message : String(reason ?? 'Unknown startup failure');
+          const message = formatStartupFailure(reason);
           notice.textContent = 'ForgeaX game failed to start.\\n' + message;
           notice.style.display = 'grid';
         };
@@ -1104,29 +1187,32 @@ function htmlSource(title) {
 }
 async function createViteConfig(facts, command, base = "/", options = {}) {
   const bootstrapRoot = options.bootstrapRoot ?? "project-bootstrap";
-  const canonicalKit = bootstrapRoot === "resource-bootstrap" ? await resolveCanonicalKit() : void 0;
+  const canonicalKit = await resolveCanonicalKit();
   const generated = resolve(facts.root, ".forgeax", "generated");
   await mkdir(generated, { recursive: true });
+  const projectRoots = facts.assetRoots.map((root) => resolve(facts.root, root));
+  const ignorePath = bootstrapRoot === "resource-bootstrap" ? isResourcePreviewIgnoredPath : isProjectSourceIgnoredPath;
+  const builtinPack = await prepareBuiltinPack(projectRoots, generated, ignorePath);
   await Promise.all([
     writeFile(resolve(generated, "index.html"), htmlSource(facts.name)),
     writeFile(resolve(generated, "main.ts"), hostSource(facts, bootstrapRoot, canonicalKit?.guid))
   ]);
   const roots = [
-    ...facts.assetRoots.map((root) => resolve(facts.root, root)),
+    ...projectRoots,
+    ...builtinPack === void 0 ? [] : [builtinPack],
     ...canonicalKit === void 0 ? [] : [canonicalKit.root]
   ];
   const importers = [...projectImporters(facts)];
   const runtimeBinding = createStandaloneRuntimeAssetBinding(facts.id);
   const engineWorkspaceResolver = await createEngineWorkspaceResolver();
+  const consumerAliases = await consumerEngineAliases(facts.root);
   const plugins = [
     ...engineWorkspaceResolver === void 0 ? [] : [engineWorkspaceResolver],
     forgeaxShader(),
     pluginPack({
       roots,
-      base,
       runtimeBinding,
       ddc: devKitDdcRoots(facts.root),
-      scriptablePack: {},
       refresh: command === "serve" ? reloadAssetHost() : void 0,
       importers: [
         audioImporter,
@@ -1136,8 +1222,8 @@ async function createViteConfig(facts, command, base = "/", options = {}) {
         fontImporter,
         ...importers
       ],
-      cookers: [createParticleCodeNativeCookerFromRoots(roots)],
-      ...bootstrapRoot === "resource-bootstrap" ? { ignorePath: isResourcePreviewIgnoredPath } : { ignorePath: isProjectSourceIgnoredPath }
+      cookers: [createMaterialPackCooker(roots), createParticleCodeNativeCookerFromRoots(roots)],
+      ignorePath
     })
   ];
   return {
@@ -1146,7 +1232,10 @@ async function createViteConfig(facts, command, base = "/", options = {}) {
     configFile: false,
     publicDir: facts.assetPublicDir === void 0 ? false : resolve(facts.root, facts.assetPublicDir),
     plugins,
-    resolve: { dedupe: ["@forgeax/engine-app", "@forgeax/engine-ecs", "@forgeax/engine-runtime"] },
+    resolve: {
+      alias: consumerAliases,
+      dedupe: ["@forgeax/engine-app", "@forgeax/engine-ecs", "@forgeax/engine-runtime"]
+    },
     server: { fs: { allow: [facts.root, ...roots] } },
     build: {
       target: "esnext",
@@ -1698,6 +1787,7 @@ function createInitPlan(facts, sdk) {
     value: {
       root: facts.root,
       version: sdk?.sdkVersion ?? devkitVersion,
+      ...sdk === void 0 ? {} : { pnpmVersion: sdk.requirements.pnpm },
       archiveBacked: sdk !== void 0,
       dependencyChanges,
       scriptChanges
@@ -1718,23 +1808,8 @@ async function applyInitPlan(facts, plan, options) {
   for (const change of plan.scriptChanges) scripts[change.name] = change.to;
   manifest.scripts = scripts;
   if (plan.archiveBacked) {
-    manifest.packageManager = "pnpm@10.33.2";
-    const pnpmValue = manifest.pnpm;
-    const pnpm = pnpmValue !== null && typeof pnpmValue === "object" ? pnpmValue : {};
-    manifest.pnpm = {
-      ...pnpm,
-      onlyBuiltDependencies: [
-        "@forgeax/engine-codec",
-        "@forgeax/engine-fbx",
-        "@forgeax/engine-wgpu-wasm",
-        "esbuild"
-      ],
-      supportedArchitectures: {
-        os: ["darwin", "linux", "win32"],
-        cpu: ["x64", "arm64"],
-        libc: ["glibc", "musl"]
-      }
-    };
+    if (plan.pnpmVersion === void 0) throw new Error("sdk-pnpm-version-missing");
+    manifest.packageManager = `pnpm@${plan.pnpmVersion}`;
   }
   await writeFile(resolve(facts.root, "package.json"), `${JSON.stringify(manifest, null, 2)}
 `);
@@ -1800,6 +1875,154 @@ var init_sdk = __esm({
   "src/sdk.ts"() {
   }
 });
+function sdkInitPath(sdk) {
+  return resolve(sdk.root, ...SDK_INIT_PATH);
+}
+function commandFailure(code, expected, hint, detail = {}) {
+  return { ok: false, error: { code, expected, hint, detail } };
+}
+function sdkProjectInstallArgs(store) {
+  const common = [
+    "install",
+    "--frozen-lockfile",
+    "--ignore-scripts",
+    "--side-effects-cache=true",
+    "--child-concurrency=1"
+  ];
+  return store === void 0 ? common : [...common, "--offline", "--trust-lockfile", "--store-dir", store];
+}
+function sdkBootstrapInstallArgs(store) {
+  const common = [
+    "install",
+    "--frozen-lockfile",
+    "--child-concurrency=1",
+    "--side-effects-cache=true"
+  ];
+  return store === void 0 ? common : [...common, "--offline", "--trust-lockfile", "--store-dir", store];
+}
+function supportedPnpm(version) {
+  const [major = 0, minor = 0] = version.split(".").map(Number);
+  return major === 11 && minor >= 7;
+}
+async function currentPnpm() {
+  try {
+    const result = await execFileAsync("pnpm", ["--version"], { maxBuffer: 1024 * 1024 });
+    const version = result.stdout.trim();
+    if (version.length === 0) throw new Error("pnpm returned an empty version");
+    return { ok: true, value: version };
+  } catch (cause) {
+    return commandFailure(
+      "pnpm-unavailable",
+      "pnpm 11.7.0 or newer in the pnpm 11 line to be available on PATH",
+      "Install or activate pnpm 11, then rerun forgeax init from the SDK root.",
+      { reason: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+function matchesState(sdk, state) {
+  if (state === null || typeof state !== "object" || Array.isArray(state)) return false;
+  const value = state;
+  return value.schemaVersion === SDK_INIT_SCHEMA_VERSION && value.sdkVersion === sdk.manifest.sdkVersion && value.engineCommit === sdk.manifest.engineCommit && typeof value.pnpm === "string" && supportedPnpm(value.pnpm) && value.node === process.versions.node && value.platform === process.platform && value.arch === process.arch;
+}
+async function readSdkInitState(sdk) {
+  try {
+    const value = JSON.parse(await readFile(sdkInitPath(sdk), "utf8"));
+    return matchesState(sdk, value) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function requireSdkInitialization(sdk) {
+  const state = await readSdkInitState(sdk);
+  if (state === void 0) {
+    return commandFailure(
+      "sdk-not-initialized",
+      "the downloaded SDK to be initialized for this Node/pnpm/platform tuple",
+      "Run ./bin/forgeax init from the SDK root once, then run forgeax new outside the SDK.",
+      {
+        sdkRoot: sdk.root,
+        sdkVersion: sdk.manifest.sdkVersion,
+        pnpm: sdk.manifest.requirements.pnpm,
+        node: process.versions.node,
+        platform: process.platform,
+        arch: process.arch
+      }
+    );
+  }
+  return { ok: true, value: state };
+}
+async function copyBootstrapInputs(sdk, root) {
+  const template = sdk.templates.get(sdk.defaultTemplate);
+  if (template === void 0) throw new Error("sdk-default-template-missing");
+  for (const name of ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml"]) {
+    await cp(resolve(template, name), resolve(root, name));
+  }
+  try {
+    await cp(resolve(template, ".npmrc"), resolve(root, ".npmrc"));
+  } catch (cause) {
+    if (cause === null || typeof cause !== "object" || !("code" in cause) || cause.code !== "ENOENT") {
+      throw cause;
+    }
+  }
+}
+async function sdkInitCommand(sdk, options = {}) {
+  const pnpmResult = await currentPnpm();
+  if (!pnpmResult.ok) return pnpmResult;
+  if (!supportedPnpm(pnpmResult.value)) {
+    return commandFailure(
+      "pnpm-version-unsupported",
+      "pnpm >=11.7.0 <12",
+      "Activate pnpm 11.7.0 or newer in the pnpm 11 line, then rerun forgeax init.",
+      { actual: pnpmResult.value, expected: sdk.manifest.requirements.pnpm }
+    );
+  }
+  const state = {
+    schemaVersion: SDK_INIT_SCHEMA_VERSION,
+    sdkVersion: sdk.manifest.sdkVersion,
+    engineCommit: sdk.manifest.engineCommit,
+    pnpm: pnpmResult.value,
+    node: process.versions.node,
+    platform: process.platform,
+    arch: process.arch
+  };
+  const report = {
+    ...state,
+    root: sdk.root,
+    store: sdk.store === void 0 ? "registry" : "offline"
+  };
+  if (options.dryRun === true || options.install === false) return { ok: true, value: report };
+  let staging;
+  try {
+    staging = await mkdtemp(resolve(tmpdir(), "forgeax-sdk-init-"));
+    await copyBootstrapInputs(sdk, staging);
+    await execFileAsync("pnpm", sdkBootstrapInstallArgs(sdk.store), {
+      cwd: staging,
+      env: { ...process.env, CI: "true" },
+      maxBuffer: 16 * 1024 * 1024
+    });
+    await mkdir(resolve(sdk.root, ".forgeax"), { recursive: true });
+    await writeFile(sdkInitPath(sdk), `${JSON.stringify(state, null, 2)}
+`);
+    return { ok: true, value: report };
+  } catch (cause) {
+    return commandFailure(
+      "sdk-init-failed",
+      "the SDK dependency closure to install and build native packages successfully",
+      "Inspect the pnpm output, repair Node/pnpm or platform permissions, then rerun forgeax init from the SDK root.",
+      { reason: cause instanceof Error ? cause.message : String(cause), sdkRoot: sdk.root }
+    );
+  } finally {
+    if (staging !== void 0) await rm(staging, { recursive: true, force: true });
+  }
+}
+var execFileAsync, SDK_INIT_PATH, SDK_INIT_SCHEMA_VERSION;
+var init_sdk_bootstrap = __esm({
+  "src/sdk-bootstrap.ts"() {
+    execFileAsync = promisify(execFile);
+    SDK_INIT_PATH = [".forgeax", "sdk-init.json"];
+    SDK_INIT_SCHEMA_VERSION = "1.0.0";
+  }
+});
 function slash(path) {
   return path.split(sep).join("/");
 }
@@ -2165,6 +2388,20 @@ async function canonicalProspectivePath(path) {
     }
   }
 }
+async function configureSdkStore(root, store) {
+  if (store === void 0) return;
+  const path = resolve(root, ".npmrc");
+  let content = "";
+  try {
+    content = await readFile(path, "utf8");
+  } catch (cause) {
+    if (!isMissingPathError(cause)) throw cause;
+  }
+  const lines = content.split(/\r?\n/).filter((line) => line.trim().length > 0 && !/^\s*store-dir\s*=/.test(line));
+  lines.push(`store-dir=${store}`);
+  await writeFile(path, `${lines.join("\n")}
+`);
+}
 function containsOrEquals(parent, child) {
   const path = relative(parent, child);
   return path === "" || path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
@@ -2175,25 +2412,14 @@ function nodeSupported() {
 }
 function pnpmSupported(version) {
   const [major = 0, minor = 0] = version.split(".").map(Number);
-  return major === 10 && minor >= 33;
-}
-function sdkInstallArgs(store) {
-  if (store === void 0) return ["install", "--frozen-lockfile"];
-  return [
-    "install",
-    "--offline",
-    "--frozen-lockfile",
-    "--side-effects-cache=false",
-    "--store-dir",
-    store
-  ];
+  return major === 11 && minor >= 7;
 }
 async function doctorCommand(options = {}) {
   const facts = await readProjectFacts(options.root);
   if (!facts.ok) return facts;
   let pnpm;
   try {
-    pnpm = (await execFileAsync("pnpm", ["--version"], { cwd: facts.value.root })).stdout.trim();
+    pnpm = (await execFileAsync2("pnpm", ["--version"], { cwd: facts.value.root })).stdout.trim();
   } catch (cause) {
     return {
       ok: false,
@@ -2221,7 +2447,7 @@ async function doctorCommand(options = {}) {
       ok: false,
       error: {
         code: "pnpm-version-unsupported",
-        expected: "pnpm >=10.33.0 <11",
+        expected: "pnpm >=11.7.0 <12",
         hint: "Enable the packageManager-declared pnpm version with Corepack and retry.",
         detail: { actual: pnpm }
       }
@@ -2260,12 +2486,20 @@ async function doctorCommand(options = {}) {
   };
 }
 async function initCommand(options = {}) {
-  const facts = await readProjectFacts(options.root);
-  if (!facts.ok) return facts;
   try {
     const sdk = await findSdkContext();
+    const root = await canonicalProspectivePath(options.root ?? process.cwd());
+    if (sdk !== void 0 && root === await canonicalProspectivePath(sdk.root)) {
+      return sdkInitCommand(sdk, options);
+    }
+    const facts = await readProjectFacts(root);
+    if (!facts.ok) return facts;
     const plan = createInitPlan(facts.value, sdk?.manifest);
     if (!plan.ok) return plan;
+    if (sdk !== void 0 && options.dryRun !== true) {
+      const initialized = await requireSdkInitialization(sdk);
+      if (!initialized.ok) return initialized;
+    }
     const applied = await applyInitPlan(facts.value, plan.value, options);
     if (!applied.ok || options.dryRun === true) return applied;
     if (sdk !== void 0) {
@@ -2275,12 +2509,31 @@ async function initCommand(options = {}) {
         resolve(template, "pnpm-lock.yaml"),
         resolve(facts.value.root, "pnpm-lock.yaml")
       );
+      await copyFile(
+        resolve(template, "pnpm-workspace.yaml"),
+        resolve(facts.value.root, "pnpm-workspace.yaml")
+      );
+      try {
+        await readFile(resolve(facts.value.root, ".npmrc"), "utf8");
+      } catch (cause) {
+        if (!isMissingPathError(cause)) throw cause;
+        try {
+          await copyFile(resolve(template, ".npmrc"), resolve(facts.value.root, ".npmrc"));
+        } catch (templateCause) {
+          if (!isMissingPathError(templateCause)) throw templateCause;
+        }
+      }
       await copySdkSkills(sdk, facts.value.root);
       await installProjectSkills(facts.value.root, sdk.manifest);
+      await configureSdkStore(
+        facts.value.root,
+        sdk.store === void 0 ? void 0 : await canonicalProspectivePath(sdk.store)
+      );
     }
     if (options.install === false) return applied;
-    const installArgs = sdk === void 0 ? ["install", "--frozen-lockfile=false"] : sdkInstallArgs(sdk.store);
-    await execFileAsync("pnpm", installArgs, {
+    const store = sdk === void 0 || sdk.store === void 0 ? void 0 : await canonicalProspectivePath(sdk.store);
+    const installArgs = sdk === void 0 ? ["install", "--frozen-lockfile=false"] : sdkProjectInstallArgs(store);
+    await execFileAsync2("pnpm", installArgs, {
       cwd: facts.value.root,
       env: { ...process.env, CI: "true" },
       maxBuffer: 16 * 1024 * 1024
@@ -2358,12 +2611,15 @@ async function newCommand(options = {}) {
         value: { root, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
       };
     }
+    const initialized = await requireSdkInitialization(sdk);
+    if (!initialized.ok) return initialized;
     const parent = dirname(root);
     await mkdir(parent, { recursive: true });
     let staging = await mkdtemp(
       resolve(parent, `.${basename(root)}.forgeax-staging-`)
     );
     const committedNames = [];
+    let committed = false;
     try {
       for (const name of await readdir(template)) {
         await cp(resolve(template, name), resolve(staging, name), {
@@ -2374,14 +2630,12 @@ async function newCommand(options = {}) {
       }
       await copySdkSkills(sdk, staging);
       await installProjectSkills(staging, sdk.manifest);
-      await execFileAsync("pnpm", sdkInstallArgs(sdk.store), {
-        cwd: staging,
-        env: { ...process.env, CI: "true" },
-        maxBuffer: 16 * 1024 * 1024
-      });
+      const store = sdk.store === void 0 ? void 0 : await canonicalProspectivePath(sdk.store);
+      await configureSdkStore(staging, store);
       if (!targetExists) {
         await rename(staging, root);
         staging = void 0;
+        committedNames.push(...await readdir(root));
       } else {
         for (const name of await readdir(staging)) {
           await rename(resolve(staging, name), resolve(root, name));
@@ -2390,29 +2644,49 @@ async function newCommand(options = {}) {
         await rm(staging, { recursive: true, force: true });
         staging = void 0;
       }
+      committed = true;
+      await execFileAsync2("pnpm", sdkProjectInstallArgs(store), {
+        cwd: root,
+        env: { ...process.env, CI: "true" },
+        maxBuffer: 16 * 1024 * 1024
+      });
       return {
         ok: true,
         value: { root, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
       };
     } catch (cause) {
       if (staging !== void 0) await rm(staging, { recursive: true, force: true });
-      await Promise.all(
-        committedNames.map((name) => rm(resolve(root, name), { recursive: true, force: true }))
-      );
+      if (committed) {
+        if (!targetExists) {
+          await rm(root, { recursive: true, force: true });
+          return { ok: false, error: commandError(cause, "project-create-failed") };
+        }
+        const cleanupNames = /* @__PURE__ */ new Set([...committedNames, "node_modules"]);
+        await Promise.all(
+          [...cleanupNames].map(
+            (name) => rm(resolve(root, name), { recursive: true, force: true })
+          )
+        );
+      } else {
+        await Promise.all(
+          committedNames.map((name) => rm(resolve(root, name), { recursive: true, force: true }))
+        );
+      }
       return { ok: false, error: commandError(cause, "project-create-failed") };
     }
   } catch (cause) {
     return { ok: false, error: commandError(cause, "project-create-failed") };
   }
 }
-var execFileAsync;
+var execFileAsync2;
 var init_bootstrap_commands = __esm({
   "src/bootstrap-commands.ts"() {
     init_init();
     init_project();
     init_sdk();
+    init_sdk_bootstrap();
     init_skill_install();
-    execFileAsync = promisify(execFile);
+    execFileAsync2 = promisify(execFile);
   }
 });
 
@@ -2471,7 +2745,7 @@ function withoutEntry(entries2, id) {
 }
 async function mutateDependency(root, action, dependency) {
   if (dependency === void 0) return;
-  await execFileAsync2("pnpm", [action, dependency], { cwd: root, maxBuffer: 16 * 1024 * 1024 });
+  await execFileAsync3("pnpm", [action, dependency], { cwd: root, maxBuffer: 16 * 1024 * 1024 });
 }
 async function pluginInstallCommand(options) {
   const root = resolve(options.root ?? process.cwd());
@@ -2573,10 +2847,10 @@ async function pluginUninstallCommand(options) {
     };
   }
 }
-var execFileAsync2;
+var execFileAsync3;
 var init_plugin_authoring = __esm({
   "src/plugin-authoring.ts"() {
-    execFileAsync2 = promisify(execFile);
+    execFileAsync3 = promisify(execFile);
   }
 });
 var RhiError;
@@ -3431,7 +3705,7 @@ async function sdkInstallCommand(options) {
   try {
     staging = await mkdtemp(resolve(parent, `.${basename(root)}.forgeax-sdk-staging-`));
     download = await mkdtemp(resolve(parent, `.${basename(root)}.forgeax-sdk-download-`));
-    await execFileAsync3(
+    await execFileAsync4(
       process.env.FORGEAX_NPM_CLIENT ?? "npm",
       [
         "install",
@@ -3472,11 +3746,11 @@ async function sdkInstallCommand(options) {
     if (download !== void 0) await rm(download, { recursive: true, force: true });
   }
 }
-var execFileAsync3;
+var execFileAsync4;
 var init_sdk_install = __esm({
   "src/sdk-install.ts"() {
     init_project();
-    execFileAsync3 = promisify(execFile);
+    execFileAsync4 = promisify(execFile);
   }
 });
 async function shaderCheckCommand(options = {}) {
@@ -4319,7 +4593,7 @@ __export(contributions_exports, {
   createBuildContribution: () => createBuildContribution,
   createDefaultContributions: () => createDefaultContributions
 });
-function commandFailure(error) {
+function commandFailure2(error) {
   return { ok: false, error: { ...error, detail: error.detail } };
 }
 function createBuildContribution(projectRoot = process.cwd()) {
@@ -4328,7 +4602,7 @@ function createBuildContribution(projectRoot = process.cwd()) {
     async (options) => {
       const { buildCommand: buildCommand2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
       const result = await buildCommand2({ ...options, root: options.root ?? projectRoot });
-      return result.ok ? result.value : commandFailure(result.error);
+      return result.ok ? result.value : commandFailure2(result.error);
     }
   );
 }
@@ -4338,7 +4612,7 @@ function createAuthorContribution(projectRoot = process.cwd()) {
     async (options) => {
       const { pluginInstallCommand: pluginInstallCommand2 } = await Promise.resolve().then(() => (init_plugin_authoring(), plugin_authoring_exports));
       const result = await pluginInstallCommand2({ ...options, root: options.root ?? projectRoot });
-      return result.ok ? result.value : commandFailure(result.error);
+      return result.ok ? result.value : commandFailure2(result.error);
     }
   );
 }
@@ -4727,14 +5001,14 @@ async function createCarrierProviderService(options) {
       );
     }
   });
-  await new Promise((resolve15, reject) => {
+  await new Promise((resolve16, reject) => {
     const onError = (error) => {
       server.off("listening", onListening);
       reject(error);
     };
     const onListening = () => {
       server.off("error", onError);
-      resolve15();
+      resolve16();
     };
     server.once("error", onError);
     server.once("listening", onListening);
@@ -4752,7 +5026,7 @@ async function createCarrierProviderService(options) {
       if (closed) return;
       closed = true;
       await new Promise(
-        (resolve15, reject) => server.close((error) => error === void 0 ? resolve15() : reject(error))
+        (resolve16, reject) => server.close((error) => error === void 0 ? resolve16() : reject(error))
       );
     }
   };
@@ -5046,14 +5320,14 @@ function projectUri(projectRoot, path) {
 async function allocateLoopbackPort() {
   const probe = createServer$2();
   try {
-    await new Promise((resolve15, reject) => {
+    await new Promise((resolve16, reject) => {
       const onError = (error) => {
         probe.off("listening", onListening);
         reject(error);
       };
       const onListening = () => {
         probe.off("error", onError);
-        resolve15();
+        resolve16();
       };
       probe.once("error", onError);
       probe.once("listening", onListening);
@@ -5066,7 +5340,7 @@ async function allocateLoopbackPort() {
     return address.port;
   } finally {
     if (probe.listening) {
-      await new Promise((resolve15) => probe.close(() => resolve15()));
+      await new Promise((resolve16) => probe.close(() => resolve16()));
     }
   }
 }
@@ -5713,14 +5987,14 @@ async function createAuthenticatedLoopbackService(options) {
       reply2(response, 400, { error: message });
     }
   });
-  await new Promise((resolve15, reject) => {
+  await new Promise((resolve16, reject) => {
     const onError = (error) => {
       server.off("listening", onListening);
       reject(error);
     };
     const onListening = () => {
       server.off("error", onError);
-      resolve15();
+      resolve16();
     };
     server.once("error", onError);
     server.once("listening", onListening);
@@ -5728,7 +6002,7 @@ async function createAuthenticatedLoopbackService(options) {
   });
   const address = server.address();
   if (address === null || typeof address === "string") {
-    await new Promise((resolve15) => server.close(() => resolve15()));
+    await new Promise((resolve16) => server.close(() => resolve16()));
     throw new Error("loopback service did not expose a TCP address");
   }
   const endpoint = `http://${host}:${address.port}/run`;
@@ -5743,8 +6017,8 @@ async function createAuthenticatedLoopbackService(options) {
     async close() {
       if (closed) return;
       closed = true;
-      await new Promise((resolve15, reject) => {
-        server.close((error) => error === void 0 ? resolve15() : reject(error));
+      await new Promise((resolve16, reject) => {
+        server.close((error) => error === void 0 ? resolve16() : reject(error));
       });
       transport.close();
     }