@forgeax/engine-devkit 0.1.3 → 0.1.6

package/dist/sdk-cli.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
+import { execFile, spawn } from 'child_process';
 import { resolve, dirname, basename, relative, sep, isAbsolute } from 'path';
-import { pathToFileURL, fileURLToPath } from 'url';
-import { execFile } from 'child_process';
 import { readdir, mkdir, mkdtemp, cp, rename, rm, copyFile, readFile, realpath, writeFile, symlink, access, lstat, readlink, rmdir } from 'fs/promises';
 import { promisify } from 'util';
+import { fileURLToPath } from 'url';
+import { tmpdir } from 'os';
 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
@@ -126,6 +127,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
@@ -146,23 +148,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)}
 `);
@@ -4684,7 +4671,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// ../engine-project/dist/index.mjs
+// ../project/dist/index.mjs
 var GuidString = external_exports.string().refine(
   (val) => AssetGuid.parse(val).ok,
   (val) => {
@@ -4789,7 +4776,7 @@ async function readJson(path) {
 function firstUnsupportedStandaloneRealm(entries, inheritedRealm = "engine") {
   for (const entry of entries) {
     const realm = entry.realm ?? inheritedRealm ?? "engine";
-    if (realm === "host") return { id: entry.id, realm };
+    if (realm !== "engine") return { id: entry.id, realm };
     if (entry.group === true) {
       const unsupported = firstUnsupportedStandaloneRealm(
         entry.config,
@@ -4907,13 +4894,10 @@ async function readProjectFacts(rootInput = process.cwd()) {
     }
   };
 }
-function isCommandError(value) {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-  const candidate = value;
-  return typeof candidate.code === "string" && typeof candidate.expected === "string" && typeof candidate.hint === "string" && candidate.detail !== null && typeof candidate.detail === "object" && !Array.isArray(candidate.detail);
-}
 function commandError(cause, fallbackCode) {
-  if (isCommandError(cause)) return cause;
+  if (cause !== null && typeof cause === "object" && "code" in cause && "expected" in cause && "hint" in cause && "detail" in cause) {
+    return cause;
+  }
   return {
     code: fallbackCode,
     expected: "the ForgeaX command to complete",
@@ -4955,6 +4939,260 @@ async function findSdkContext() {
     cursor = parent;
   }
 }
+var execFileAsync = promisify(execFile);
+var SDK_INIT_PATH = [".forgeax", "sdk-init.json"];
+var SDK_INIT_SCHEMA_VERSION = "1.0.0";
+function agentOnboarding(sdk, projectRoot) {
+  const root2 = projectRoot ?? sdk.root;
+  return {
+    read: [
+      resolve(root2, "AGENTS.md"),
+      resolve(root2, "skills", "forgeax-engine-sdk", "SKILL.md"),
+      resolve(root2, "skills", "forgeax-engine-sdk", "references", "feature-catalog.md")
+    ],
+    next: projectRoot === void 0 ? {
+      cwd: root2,
+      argv: ["node", "./bin/forgeax.mjs", "new", "../my-game"]
+    } : { cwd: root2, argv: ["pnpm", "exec", "forgeax", "list", "--json"] }
+  };
+}
+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", "--config.trust-lockfile=true", "--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", "--config.trust-lockfile=true", "--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, root2) {
+  const template2 = sdk.templates.get(sdk.defaultTemplate);
+  if (template2 === void 0) throw new Error("sdk-default-template-missing");
+  for (const name of ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml"]) {
+    await cp(resolve(template2, name), resolve(root2, name));
+  }
+  try {
+    await cp(resolve(template2, ".npmrc"), resolve(root2, ".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",
+    onboarding: agentOnboarding(sdk)
+  };
+  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 });
+  }
+}
+
+// src/sdk-update.ts
+var UPDATE_MIGRATION_RISK = "Install a newer SDK in a separate directory. Existing games remain pinned and are not migrated automatically; review release notes and migrate and test each game before changing its Engine version.";
+function parseVersion(version) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    version
+  );
+  if (match === null) return void 0;
+  const major = match[1];
+  const minor = match[2];
+  const patch = match[3];
+  if (major === void 0 || minor === void 0 || patch === void 0) return void 0;
+  const prerelease = match[4]?.split(".");
+  if (prerelease?.some(
+    (identifier) => identifier.length === 0 || /^\d+$/.test(identifier) && /^0\d+/.test(identifier)
+  )) {
+    return void 0;
+  }
+  return {
+    core: [major, minor, patch],
+    ...prerelease === void 0 ? {} : { prerelease }
+  };
+}
+function compareNumericIdentifier(current, latest) {
+  if (current.length !== latest.length) return latest.length > current.length ? 1 : -1;
+  if (current === latest) return 0;
+  return latest > current ? 1 : -1;
+}
+function comparePrerelease(current, latest) {
+  const length = Math.max(current.length, latest.length);
+  for (let index = 0; index < length; index += 1) {
+    const currentIdentifier = current[index];
+    const latestIdentifier = latest[index];
+    if (currentIdentifier === void 0) return 1;
+    if (latestIdentifier === void 0) return -1;
+    if (currentIdentifier === latestIdentifier) continue;
+    const currentNumeric = /^\d+$/.test(currentIdentifier);
+    const latestNumeric = /^\d+$/.test(latestIdentifier);
+    if (currentNumeric && latestNumeric) {
+      return compareNumericIdentifier(currentIdentifier, latestIdentifier);
+    }
+    if (currentNumeric !== latestNumeric) return latestNumeric ? -1 : 1;
+    return latestIdentifier > currentIdentifier ? 1 : -1;
+  }
+  return 0;
+}
+function newerSdkVersion(currentVersion, latestVersion) {
+  const current = parseVersion(currentVersion);
+  const latest = parseVersion(latestVersion);
+  if (current === void 0 || latest === void 0) return false;
+  for (let index = 0; index < current.core.length; index += 1) {
+    const precedence = compareNumericIdentifier(
+      current.core[index] ?? "0",
+      latest.core[index] ?? "0"
+    );
+    if (precedence !== 0) return precedence > 0;
+  }
+  if (current.prerelease !== void 0 && latest.prerelease === void 0) return true;
+  if (current.prerelease === void 0 || latest.prerelease === void 0) return false;
+  return comparePrerelease(current.prerelease, latest.prerelease) > 0;
+}
+function offline() {
+  return ["1", "true"].includes((process.env.npm_config_offline ?? "").toLowerCase());
+}
+async function checkSdkUpdate(currentVersion) {
+  if (process.env.FORGEAX_DISABLE_UPDATE_CHECK === "1") {
+    return { status: "skipped", currentVersion, reason: "disabled" };
+  }
+  if (offline()) return { status: "skipped", currentVersion, reason: "offline" };
+  try {
+    const registry = process.env.npm_config_registry ?? "https://registry.npmjs.org/";
+    const response = await fetch(
+      new URL("@forgeax%2Fengine-sdk", `${registry.replace(/\/$/, "")}/`),
+      {
+        headers: { accept: "application/vnd.npm.install-v1+json" },
+        signal: AbortSignal.timeout(2e3)
+      }
+    );
+    if (!response.ok) throw new Error(`registry-http-${response.status}`);
+    const metadata = await response.json();
+    const latestVersion = metadata["dist-tags"]?.latest;
+    if (typeof latestVersion !== "string") throw new Error("registry-latest-version-missing");
+    return newerSdkVersion(currentVersion, latestVersion) ? {
+      status: "available",
+      currentVersion,
+      latestVersion,
+      migrationRisk: UPDATE_MIGRATION_RISK
+    } : { status: "current", currentVersion, latestVersion };
+  } catch (cause) {
+    return {
+      status: "unavailable",
+      currentVersion,
+      reason: cause instanceof Error ? cause.message : String(cause)
+    };
+  }
+}
 var PROJECT_SKILL_MOUNT_ROOTS = Object.freeze([
   ".codebuddy/skills",
   ".cursor/skills",
@@ -5246,7 +5484,7 @@ async function installProjectSkills(root2, provenance) {
 }
 
 // src/bootstrap-commands.ts
-var execFileAsync = promisify(execFile);
+var execFileAsync2 = promisify(execFile);
 function isMissingPathError(cause) {
   return cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT";
 }
@@ -5265,6 +5503,20 @@ async function canonicalProspectivePath(path) {
     }
   }
 }
+async function configureSdkStore(root2, store) {
+  if (store === void 0) return;
+  const path = resolve(root2, ".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);
@@ -5275,25 +5527,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,
@@ -5321,7 +5562,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 }
       }
@@ -5360,12 +5601,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 root2 = await canonicalProspectivePath(options.root ?? process.cwd());
+    if (sdk !== void 0 && root2 === await canonicalProspectivePath(sdk.root)) {
+      return sdkInitCommand(sdk, options);
+    }
+    const facts = await readProjectFacts(root2);
+    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) {
@@ -5375,12 +5624,31 @@ async function initCommand(options = {}) {
         resolve(template2, "pnpm-lock.yaml"),
         resolve(facts.value.root, "pnpm-lock.yaml")
       );
+      await copyFile(
+        resolve(template2, "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(template2, ".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
@@ -5458,12 +5726,15 @@ async function newCommand(options = {}) {
         value: { root: root2, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
       };
     }
+    const initialized = await requireSdkInitialization(sdk);
+    if (!initialized.ok) return initialized;
     const parent = dirname(root2);
     await mkdir(parent, { recursive: true });
     let staging = await mkdtemp(
       resolve(parent, `.${basename(root2)}.forgeax-staging-`)
     );
     const committedNames = [];
+    let committed = false;
     try {
       for (const name of await readdir(template2)) {
         await cp(resolve(template2, name), resolve(staging, name), {
@@ -5474,14 +5745,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, root2);
         staging = void 0;
+        committedNames.push(...await readdir(root2));
       } else {
         for (const name of await readdir(staging)) {
           await rename(resolve(staging, name), resolve(root2, name));
@@ -5490,15 +5759,41 @@ async function newCommand(options = {}) {
         await rm(staging, { recursive: true, force: true });
         staging = void 0;
       }
+      committed = true;
+      await execFileAsync2("pnpm", sdkProjectInstallArgs(store), {
+        cwd: root2,
+        env: { ...process.env, CI: "true" },
+        maxBuffer: 16 * 1024 * 1024
+      });
+      const sdkUpdate = await checkSdkUpdate(sdk.manifest.sdkVersion);
       return {
         ok: true,
-        value: { root: root2, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
+        value: {
+          root: root2,
+          template: templateId,
+          sdkVersion: sdk.manifest.sdkVersion,
+          onboarding: agentOnboarding(sdk, root2),
+          sdkUpdate
+        }
       };
     } catch (cause) {
       if (staging !== void 0) await rm(staging, { recursive: true, force: true });
-      await Promise.all(
-        committedNames.map((name) => rm(resolve(root2, name), { recursive: true, force: true }))
-      );
+      if (committed) {
+        if (!targetExists) {
+          await rm(root2, { 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(root2, name), { recursive: true, force: true })
+          )
+        );
+      } else {
+        await Promise.all(
+          committedNames.map((name) => rm(resolve(root2, name), { recursive: true, force: true }))
+        );
+      }
       return { ok: false, error: commandError(cause, "project-create-failed") };
     }
   } catch (cause) {
@@ -5506,11 +5801,42 @@ async function newCommand(options = {}) {
   }
 }
 
+// src/cli-output.ts
+function agentOnboardingLines(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return [];
+  const onboarding = value.onboarding;
+  if (onboarding === null || typeof onboarding !== "object" || Array.isArray(onboarding)) return [];
+  const candidate = onboarding;
+  const lines = Array.isArray(candidate.read) ? candidate.read.filter((path) => typeof path === "string").map((path) => `[forgeax] read: ${path}`) : [];
+  if (typeof candidate.next?.cwd === "string" && Array.isArray(candidate.next.argv) && candidate.next.argv.every((part) => typeof part === "string")) {
+    lines.push(`[forgeax] next cwd: ${candidate.next.cwd}`);
+    lines.push(`[forgeax] next: ${candidate.next.argv.join(" ")}`);
+  }
+  return lines;
+}
+function sdkUpdateLines(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return [];
+  const update = value.sdkUpdate;
+  if (update === null || typeof update !== "object" || Array.isArray(update)) return [];
+  const candidate = update;
+  if (candidate.status !== "available" || typeof candidate.currentVersion !== "string" || typeof candidate.latestVersion !== "string" || typeof candidate.migrationRisk !== "string") {
+    return [];
+  }
+  return [
+    `[forgeax] update available: @forgeax/engine-sdk ${candidate.currentVersion} -> ${candidate.latestVersion}`,
+    `[forgeax] update note: ${candidate.migrationRisk}`
+  ];
+}
+function renderForgeaxUsage() {
+  return "Usage: forgeax new [directory] [--template empty|game-default]\n       forgeax <init|doctor|test|dev|build|package|serve|preview> [directory]\n       forgeax package [directory] [--output release/game-web.zip]\n       forgeax run <rhi.capture|rhi.summary|rhi.inspect> [options]\n       forgeax run <operation-id> --input <request.json>\n       forgeax asset <add|verify|inspect|list> [subject]\n       forgeax shader check [path]\n       forgeax plugin <install|uninstall> <module-or-id> [options]\n       forgeax skill <install|verify> [--root directory]\n       forgeax sdk install <directory> [--version VERSION]\n";
+}
+
 // src/sdk-cli.ts
-var args = process.argv.slice(2);
+var rawArgs = process.argv.slice(2);
+var args = [...rawArgs];
 var commandArg = args.shift();
 var command = commandArg;
-var help = commandArg === "--help" || commandArg === "-h";
+var help = rawArgs.includes("--help") || rawArgs.includes("-h");
 var json = args.includes("--json");
 var dryRun = args.includes("--dry-run");
 var noInstall = args.includes("--no-install");
@@ -5520,23 +5846,43 @@ var positional = args.find(
   (value, index) => !value.startsWith("--") && (templateIndex < 0 || index !== templateIndex + 1)
 );
 var root = command === "new" || command === "init" || command === "doctor" ? positional ?? process.cwd() : process.cwd();
-if (command === "new" || command === "init" || command === "doctor") {
+if (help) {
+  process.stdout.write(renderForgeaxUsage());
+} else if (command === "new" || command === "init" || command === "doctor") {
   const result = await (command === "new" ? newCommand({ root, dryRun, ...template === void 0 ? {} : { template } }) : command === "init" ? initCommand({ root, dryRun, install: !noInstall }) : doctorCommand({ root}));
   const envelope = result.ok ? { schemaVersion: "1.0.0", command, ok: true, value: result.value } : { schemaVersion: "1.0.0", command, ok: false, error: result.error };
   if (json) process.stdout.write(`${JSON.stringify(envelope)}
 `);
-  else if (result.ok) process.stdout.write(`[forgeax] ${command} ready
+  else if (result.ok) {
+    process.stdout.write(`[forgeax] ${command} ready
+`);
+    for (const line of agentOnboardingLines(result.value)) process.stdout.write(`${line}
+`);
+    for (const line of sdkUpdateLines(result.value)) process.stdout.write(`${line}
 `);
-  else process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
+  } else process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
 `);
   if (!result.ok) process.exitCode = 1;
-} else if (command !== void 0 && !help) {
-  const cli = resolve(root, "node_modules", "@forgeax", "engine-devkit", "dist", "cli.mjs");
-  await import(pathToFileURL(cli).href);
+} else if (command !== void 0) {
+  const localForgeax = resolve(
+    root,
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "forgeax.cmd" : "forgeax"
+  );
+  const child = spawn(localForgeax, [command, ...args], {
+    cwd: root,
+    shell: process.platform === "win32",
+    stdio: "inherit"
+  });
+  const exitCode = await new Promise((resolveExit, reject) => {
+    child.once("error", reject);
+    child.once("exit", resolveExit);
+  });
+  if (exitCode !== 0) process.exitCode = exitCode ?? 1;
 } else {
-  const output = "Usage: forgeax new [directory] [--template empty|game-default]\n       forgeax <init|doctor|test|dev|build|serve|preview> [directory]\n       forgeax skill <install|verify>  # from a game project\n";
-  (help ? process.stdout : process.stderr).write(output);
-  if (!help) process.exitCode = 2;
+  process.stderr.write(renderForgeaxUsage());
+  process.exitCode = 2;
 }
 /*! Bundled license information: