@babylonjs-toolkit/agent 1.1.2 → 1.1.5

package/README.md

@@ -1,4 +1,4 @@
-# Babylon Toolkit Agent Skills (1.0.0)
+# Babylon Toolkit Agent Skills (1.1.5)
 
 Universal [Agent Skills](https://agentskills.io) for the `Babylon Toolkit` web game development framework.
 Each `SKILL.md` follows the open standard, so the **same file works unchanged** in Claude Code, Codex CLI, and GitHub Copilot.
@@ -53,10 +53,13 @@ refresh the persona, and prune skills the new release no longer ships.
 
 If the upgrade is not possible it says so and continues with what is on disk:
 
-- running through `npx`, from a git checkout, or as a project dependency — there is
-  no global package to upgrade, so it reinstalls the bundled files
+- running through `npx`, from a git checkout, a `npm link`ed working copy, or as a
+  project dependency — there is no global package to upgrade, so it reinstalls the
+  bundled files
 - the registry is unreachable — it reinstalls the version you already have
 - the global install needs elevated permissions — it prints the exact command to run
+- npm reports success but this CLI still runs the old version — you have more than
+  one Node/npm on PATH, and it tells you which path was left behind
 
 Use `--no-self-update` to skip the npm check entirely.
 

package/bin/bt-agent.js

@@ -166,9 +166,17 @@ function printSelfUpdate(result) {
       break;
     case 'upgrade-failed':
       console.log(`\nCould not upgrade ${PACKAGE_NAME} ${result.current} -> ${result.latest}: ${result.reason}`);
-      console.log(`Run this yourself (it may need sudo): ${result.command}`);
+      console.log(`Run this yourself (it may need elevated permissions): ${result.command}`);
+      console.log(`  installed at: ${prettyPath(result.root)}`);
       console.log('Reinstalling the currently installed version instead.');
       break;
+    case 'upgrade-stale':
+      console.log(`\n${result.command} reported success, but this CLI still runs ${result.onDisk} from`);
+      console.log(`  ${prettyPath(result.root)}`);
+      console.log('That path was not updated, so you likely have more than one Node/npm');
+      console.log('installation. Check which one is on PATH:');
+      console.log(process.platform === 'win32' ? '  where bt-agent && npm root -g' : '  which bt-agent && npm root -g');
+      break;
     case 'check-failed':
       console.log(`\nCould not check npm for a newer version: ${result.reason}`);
       console.log(`Reinstalling ${PACKAGE_NAME} ${result.current} from disk.`);
@@ -260,6 +268,7 @@ function main() {
         // payload already on disk — so it could never deliver a new release. Bring
         // the package itself up to date first, then hand over to the new CLI.
         let selfResult = null;
+        let selfFailed = false;
         if (opts.selfUpdate) {
           selfResult = selfUpdate({
             dryRun: opts.dryRun,
@@ -269,6 +278,10 @@ function main() {
           });
           if (!opts.json) printSelfUpdate(selfResult);
 
+          // The files were installed correctly, but the release the user asked for
+          // is not the one now running — that is a failure worth a non-zero exit.
+          selfFailed = selfResult.status === 'upgrade-stale' || selfResult.status === 'upgrade-failed';
+
           if (selfResult.status === 'upgraded') {
             const passthrough = process.argv.slice(2).filter((a) => a !== 'update');
             const code = reexec(['install', ...passthrough], selfResult.latest);
@@ -299,7 +312,7 @@ function main() {
             console.log('\nDry run — nothing was written.\n');
           }
         }
-        process.exit(opts.dryRun || check.ok ? 0 : 1);
+        process.exit(opts.dryRun || (check.ok && !selfFailed) ? 0 : 1);
         break;
       }
 

package/lib/selfupdate.js

@@ -22,10 +22,11 @@ function segments(p) {
 /**
  * Where is this copy of the CLI running from?
  *
- * `update` may only shell out to a package manager when the answer is a global
- * install. An npx run already fetched the newest version, a git checkout is the
- * developer's own working tree, and a project dependency belongs to that project's
- * lockfile — upgrading any of those globally would write files nobody asked for.
+ * `update` may only shell out to a package manager when the answer is a real
+ * global install. An npx run already fetched the newest version, a git checkout or
+ * `npm link` is the developer's own working tree, and a project dependency belongs
+ * to that project's lockfile — upgrading any of those would write files nobody
+ * asked for, and in the linked case would silently replace the link.
  */
 function detectInstall() {
   const parts = segments(PACKAGE_ROOT);
@@ -38,6 +39,13 @@ function detectInstall() {
     return { kind: 'npx', manager: null, root: PACKAGE_ROOT };
   }
 
+  // Every installed copy — global or project — lives under a node_modules
+  // directory. Anything else is a working copy reached through a symlink
+  // (`npm link`, `npm i -g <dir>`); upgrading it would delete the link.
+  if (!lower.includes('node_modules')) {
+    return { kind: 'linked', manager: null, root: PACKAGE_ROOT };
+  }
+
   const manager = lower.includes('pnpm') || lower.includes('.pnpm')
     ? 'pnpm'
     : lower.includes('.yarn') || lower.includes('yarn')
@@ -46,31 +54,43 @@ function detectInstall() {
         ? 'bun'
         : 'npm';
 
-  return { kind: isGlobal() ? 'global' : 'local', manager, root: PACKAGE_ROOT };
+  return { kind: globalKind(), manager, root: PACKAGE_ROOT };
 }
 
-/** True when PACKAGE_ROOT lives under this machine's global module directory. */
-function isGlobal() {
-  const roots = [];
+function npmGlobalRoot() {
   try {
-    roots.push(String(execFileSync(npmBin(), ['root', '-g'], { encoding: 'utf8', timeout: 20000 })).trim());
+    return String(runManager('npm', ['root', '-g'], { encoding: 'utf8', timeout: 20000 })).trim() || null;
   } catch {
-    /* npm unavailable or slow — fall back to path shape below */
+    return null;
   }
+}
 
-  const norm = (p) => path.resolve(p).toLowerCase().replace(/[\\/]+$/, '');
-  const here = norm(PACKAGE_ROOT);
-  if (roots.some((r) => r && here.startsWith(norm(r) + path.sep.toLowerCase()))) return true;
+const norm = (p) => path.resolve(p).toLowerCase().replace(/[\\/]+$/, '');
+
+/** 'global' | 'linked' | 'local' for a package that is not npx or a git checkout. */
+function globalKind() {
+  const root = npmGlobalRoot();
+
+  if (root) {
+    const entry = path.join(root, ...PACKAGE_NAME.split('/'));
+    try {
+      // `npm link` and `npm i -g <dir>` leave a symlink to the developer's tree.
+      // Upgrading that would delete the link and hide their working copy.
+      if (fs.lstatSync(entry).isSymbolicLink() && norm(fs.realpathSync(entry)) === norm(PACKAGE_ROOT)) {
+        return 'linked';
+      }
+    } catch {
+      /* this package is not installed under that prefix */
+    }
+    if (norm(PACKAGE_ROOT).startsWith(norm(root) + path.sep.toLowerCase())) return 'global';
+  }
 
   // pnpm/yarn/bun global stores never match `npm root -g`; recognise their shapes,
   // and treat anything outside the current project tree as global rather than local.
   const parts = segments(PACKAGE_ROOT).map((s) => s.toLowerCase());
-  if (parts.includes('.pnpm') || parts.includes('.yarn') || parts.includes('.bun')) return true;
-  return !here.startsWith(norm(process.cwd()) + path.sep.toLowerCase());
-}
+  if (parts.includes('.pnpm') || parts.includes('.yarn') || parts.includes('.bun')) return 'global';
 
-function npmBin() {
-  return IS_WINDOWS ? 'npm.cmd' : 'npm';
+  return norm(PACKAGE_ROOT).startsWith(norm(process.cwd()) + path.sep.toLowerCase()) ? 'local' : 'global';
 }
 
 function managerBin(manager) {
@@ -78,6 +98,50 @@ function managerBin(manager) {
   return IS_WINDOWS && name !== 'bun' ? `${name}.cmd` : name;
 }
 
+/**
+ * npm's own JS entry point, shipped beside the node binary.
+ *
+ * Running it with `process.execPath` is the one invocation that behaves the same
+ * on every platform. It matters most on Windows: since the CVE-2024-27980 fix,
+ * Node refuses to `execFile` a `.cmd` shim without `shell: true` and throws
+ * EINVAL — which is exactly why `update` reported an upgrade it never performed.
+ */
+function npmCliPath() {
+  const dir = path.dirname(process.execPath);
+  const candidates = [
+    process.env.npm_execpath,
+    path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(dir, '..', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+  for (const c of candidates) {
+    if (c && c.endsWith('.js') && fs.existsSync(c)) return path.resolve(c);
+  }
+  return null;
+}
+
+/** Quote an argument for cmd.exe, which is what `shell: true` uses on Windows. */
+function shellQuote(arg) {
+  return /[\s"^&|<>()]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
+}
+
+/**
+ * Run a package manager command portably.
+ *
+ * npm goes through its JS entry point when we can find it; everything else falls
+ * back to the platform shim, with `shell: true` on Windows so a `.cmd` is allowed.
+ */
+function runManager(manager, args, opts = {}) {
+  if (manager === 'npm') {
+    const cli = npmCliPath();
+    if (cli) return execFileSync(process.execPath, [cli, ...args], opts);
+  }
+  if (IS_WINDOWS && manager !== 'bun') {
+    return execFileSync(managerBin(manager), args.map(shellQuote), { ...opts, shell: true });
+  }
+  return execFileSync(managerBin(manager), args, opts);
+}
+
 /** The exact command a user can copy/paste if the automatic upgrade fails. */
 function upgradeCommand(manager, version) {
   const spec = `${PACKAGE_NAME}@${version || 'latest'}`;
@@ -122,7 +186,7 @@ function compareVersions(a, b) {
  */
 function fetchLatestVersion({ timeout = 20000 } = {}) {
   try {
-    const out = execFileSync(npmBin(), ['view', PACKAGE_NAME, 'version'], {
+    const out = runManager('npm', ['view', PACKAGE_NAME, 'version'], {
       encoding: 'utf8',
       timeout,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -161,6 +225,15 @@ function fetchLatestFromRegistrySync(timeout) {
   }
 }
 
+/** Version of the package as it now sits on disk, read fresh (not the require cache). */
+function installedVersionOnDisk() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Bring the installed package itself up to date.
  *
@@ -183,13 +256,14 @@ function selfUpdate({ dryRun = false, timeout = 20000, log = () => {} } = {}) {
       npx: 'running via npx — npx already fetched the latest version',
       dev: 'running from a git checkout — nothing to upgrade',
       local: 'installed as a project dependency — upgrade it through that project',
+      linked: `linked to ${PACKAGE_ROOT} — upgrade that working copy instead`,
     }[install.kind];
     return { ...base, status: 'skipped', reason: why };
   }
 
   log(`Checking npm for a newer ${PACKAGE_NAME} (installed: ${CURRENT_VERSION})...`);
   const { version: latest, error } = fetchLatestVersion({ timeout });
-  if (!latest) return { ...base, status: 'check-failed', reason: error };
+  if (!latest) return { ...base, status: 'check-failed', reason: error, root: PACKAGE_ROOT };
 
   if (compareVersions(latest, CURRENT_VERSION) <= 0) {
     return { ...base, latest, status: 'current' };
@@ -200,16 +274,25 @@ function selfUpdate({ dryRun = false, timeout = 20000, log = () => {} } = {}) {
 
   log(`Upgrading ${CURRENT_VERSION} -> ${latest} (${command})`);
   try {
-    execFileSync(managerBin(install.manager), upgradeArgs(install.manager, latest), {
+    runManager(install.manager, upgradeArgs(install.manager, latest), {
       stdio: ['ignore', 'inherit', 'inherit'],
       timeout: 10 * 60 * 1000,
     });
   } catch (err) {
     const reason = err && err.message ? String(err.message).split('\n')[0] : 'upgrade command failed';
-    return { ...base, latest, status: 'upgrade-failed', command, reason };
+    return { ...base, latest, status: 'upgrade-failed', command, reason, root: PACKAGE_ROOT };
+  }
+
+  // Trust the files, not the exit code. A machine with more than one npm prefix
+  // (nvm-windows, a second Node install) happily reports success while installing
+  // somewhere this CLI does not run from — which looks exactly like "update did
+  // nothing", so name it instead of claiming an upgrade that did not land here.
+  const onDisk = installedVersionOnDisk();
+  if (onDisk && compareVersions(onDisk, CURRENT_VERSION) <= 0) {
+    return { ...base, latest, status: 'upgrade-stale', command, onDisk, root: PACKAGE_ROOT };
   }
 
-  return { ...base, latest, status: 'upgraded', command };
+  return { ...base, latest, status: 'upgraded', command, onDisk };
 }
 
 /**
@@ -231,6 +314,9 @@ function reexec(argv, version) {
 
 module.exports = {
   PACKAGE_NAME,
+  runManager,
+  npmCliPath,
+  installedVersionOnDisk,
   CURRENT_VERSION,
   GUARD_ENV,
   detectInstall,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babylonjs-toolkit/agent",
-  "version": "1.1.2",
+  "version": "1.1.5",
   "description": "Installs the Babylon Toolkit agent skills and Agent Persona for Claude Code, Codex, GitHub Copilot, Gemini CLI and Antigravity.",
   "keywords": [
     "babylonjs",