@forgeax/engine-devkit 0.1.4 → 0.1.6

package/dist/project.d.ts

@@ -1,5 +1,4 @@
 import type { CommandError, CommandResult, ProjectFacts } from './types.js';
 export declare function readProjectFacts(rootInput?: string): Promise<CommandResult<ProjectFacts>>;
-export declare function isCommandError(value: unknown): value is CommandError;
 export declare function commandError(cause: unknown, fallbackCode: string): CommandError;
 //# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyC5E,wBAAsB,gBAAgB,CACpC,SAAS,SAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAiItC;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAWpE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,YAAY,CAQ/E"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyC5E,wBAAsB,gBAAgB,CACpC,SAAS,SAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAiItC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,YAAY,CAiB/E"}

package/dist/rhi-debug/cli-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-context.d.ts","sourceRoot":"","sources":["../../src/rhi-debug/cli-context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAe,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,wBAAgB,iCAAiC,IAAI,wBAAwB,CAkE5E"}
+{"version":3,"file":"cli-context.d.ts","sourceRoot":"","sources":["../../src/rhi-debug/cli-context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAe,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,wBAAgB,iCAAiC,IAAI,wBAAwB,CAmE5E"}

package/dist/sdk-bootstrap.d.ts

@@ -13,7 +13,16 @@ export interface SdkInitState {
 export interface SdkInitReport extends SdkInitState {
     readonly root: string;
     readonly store: 'offline' | 'registry';
+    readonly onboarding: AgentOnboarding;
 }
+export interface AgentOnboarding {
+    readonly read: readonly string[];
+    readonly next: {
+        readonly cwd: string;
+        readonly argv: readonly string[];
+    };
+}
+export declare function agentOnboarding(sdk: SdkContext, projectRoot?: string): AgentOnboarding;
 export declare function sdkProjectInstallArgs(store: string | undefined): string[];
 export declare function readSdkInitState(sdk: SdkContext): Promise<SdkInitState | undefined>;
 export declare function requireSdkInitialization(sdk: SdkContext): Promise<CommandResult<SdkInitState>>;

package/dist/sdk-bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-bootstrap.d.ts","sourceRoot":"","sources":["../src/sdk-bootstrap.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,QAAA,MAAM,uBAAuB,EAAG,OAAgB,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,uBAAuB,CAAC;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;CACxC;AAeD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAWzE;AAkDD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAOzF;AAED,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAkBtC;AAsBD,wBAAsB,cAAc,CAClC,GAAG,EAAE,UAAU,EACf,OAAO,GAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACtE,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAiDvC"}
+{"version":3,"file":"sdk-bootstrap.d.ts","sourceRoot":"","sources":["../src/sdk-bootstrap.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,QAAA,MAAM,uBAAuB,EAAG,OAAgB,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,uBAAuB,CAAC;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;KAClC,CAAC;CACH;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,eAAe,CAgBtF;AAeD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAWzE;AAkDD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAOzF;AAED,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAkBtC;AAsBD,wBAAsB,cAAc,CAClC,GAAG,EAAE,UAAU,EACf,OAAO,GAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACtE,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAkDvC"}

package/dist/sdk-cli.mjs

@@ -1,9 +1,9 @@
 #!/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;
@@ -4776,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,
@@ -4894,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",
@@ -4945,6 +4942,20 @@ async function findSdkContext() {
 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);
 }
@@ -4959,7 +4970,7 @@ function sdkProjectInstallArgs(store) {
     "--side-effects-cache=true",
     "--child-concurrency=1"
   ];
-  return store === void 0 ? common : [...common, "--offline", "--trust-lockfile", "--store-dir", store];
+  return store === void 0 ? common : [...common, "--offline", "--config.trust-lockfile=true", "--store-dir", store];
 }
 function sdkBootstrapInstallArgs(store) {
   const common = [
@@ -4968,7 +4979,7 @@ function sdkBootstrapInstallArgs(store) {
     "--child-concurrency=1",
     "--side-effects-cache=true"
   ];
-  return store === void 0 ? common : [...common, "--offline", "--trust-lockfile", "--store-dir", store];
+  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);
@@ -5058,7 +5069,8 @@ async function sdkInitCommand(sdk, options = {}) {
   const report = {
     ...state,
     root: sdk.root,
-    store: sdk.store === void 0 ? "registry" : "offline"
+    store: sdk.store === void 0 ? "registry" : "offline",
+    onboarding: agentOnboarding(sdk)
   };
   if (options.dryRun === true || options.install === false) return { ok: true, value: report };
   let staging;
@@ -5085,6 +5097,102 @@ async function sdkInitCommand(sdk, options = {}) {
     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",
@@ -5657,9 +5765,16 @@ async function newCommand(options = {}) {
         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 });
@@ -5686,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");
@@ -5700,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
 `);
-  else process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
+    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}
 `);
   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: