@babylonjs-toolkit/agent 1.1.1 → 1.1.2

package/README.md

@@ -24,7 +24,7 @@ and instruction files are only read at session start.
 | Command | What it does |
 |---------|--------------|
 | `bt-agent install` | Install skills + persona into every target (the default) |
-| `bt-agent update` | Reinstall, and remove skills this package no longer ships |
+| `bt-agent update` | Fetch the newest release from npm, reinstall it, and prune dropped skills |
 | `bt-agent uninstall` | Remove what it installed — and nothing else |
 | `bt-agent doctor` | Verify the install; prints `INSTALL OK` or lists what is missing |
 | `bt-agent targets` | Show every target and the paths it writes to |
@@ -36,9 +36,30 @@ and instruction files are only read at session start.
 | `--legacy-codex` | Also write `~/.codex/skills` for pre-`.agents` Codex builds |
 | `--no-persona` | Install skills only; leave instruction files alone |
 | `--persona-only` | Install/refresh the Agent Persona only; do not copy skills |
+| `--no-self-update` | `update` only: reinstall the bundled files; do not fetch npm |
 | `--dry-run` | Print what would happen and change nothing |
 | `--json` | Machine-readable output |
 
+### Updating
+
+```bash
+bt-agent update
+```
+
+`update` asks npm for the newest published version. If there is one it upgrades the
+global package for you — with whichever manager installed it (`npm`, `pnpm`, `yarn`
+or `bun`) — then hands over to the freshly installed CLI to copy the new skills,
+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
+- the registry is unreachable — it reinstalls the version you already have
+- the global install needs elevated permissions — it prints the exact command to run
+
+Use `--no-self-update` to skip the npm check entirely.
+
 ### What it writes
 
 | Target | Skills | Agent Persona |

package/bin/bt-agent.js

@@ -4,7 +4,8 @@
 const { install, uninstall } = require('../lib/install');
 const { doctor } = require('../lib/doctor');
 const { TARGETS, targetIds } = require('../lib/targets');
-const { prettyPath } = require('../lib/paths');
+const { selfUpdate, reexec, upgradeCommand, PACKAGE_NAME } = require('../lib/selfupdate');
+const { prettyPath, resolveTargetPath } = require('../lib/paths');
 const { version } = require('../package.json');
 
 const USAGE = `
@@ -18,7 +19,7 @@ Usage
 
 Commands
   install      Install skills + persona into every target        (default)
-  update       Same as install, and remove skills no longer shipped
+  update       Upgrade this package from npm, then reinstall and prune
   uninstall    Remove what this tool installed, and nothing else
   doctor       Verify the install; prints INSTALL OK or INSTALL FAILED
   targets      List the available targets and their paths
@@ -30,6 +31,7 @@ Options
   --no-persona         Install skills only; do not touch instruction files
   --persona-only       Install/refresh the Agent Persona only; do not copy skills
   --no-migrate         Leave a legacy unmarked persona in place, do not convert it
+  --no-self-update     update: reinstall the bundled files only; do not fetch npm
   --dry-run            Print what would happen; change nothing
   --json               Machine-readable output
   -h, --help           Show this help
@@ -40,6 +42,7 @@ Examples
   bt-agent install --legacy-codex
   bt-agent install --project
   bt-agent doctor
+  bt-agent update
 `;
 
 function parseArgs(argv) {
@@ -51,6 +54,7 @@ function parseArgs(argv) {
     persona: true,
     skills: true,
     migrate: true,
+    selfUpdate: true,
     dryRun: false,
     json: false,
     help: false,
@@ -83,6 +87,9 @@ function parseArgs(argv) {
       case '--no-migrate':
         opts.migrate = false;
         break;
+      case '--no-self-update':
+        opts.selfUpdate = false;
+        break;
       case '--dry-run':
         opts.dryRun = true;
         break;
@@ -146,6 +153,44 @@ function printInstall(report) {
   }
 }
 
+function printSelfUpdate(result) {
+  switch (result.status) {
+    case 'upgraded':
+      console.log(`\nUpgraded ${PACKAGE_NAME} ${result.current} -> ${result.latest}.`);
+      break;
+    case 'current':
+      console.log(`\n${PACKAGE_NAME} ${result.current} is the latest published version.`);
+      break;
+    case 'would-upgrade':
+      console.log(`\nWould upgrade ${PACKAGE_NAME} ${result.current} -> ${result.latest} (${result.command}).`);
+      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('Reinstalling the currently installed version instead.');
+      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.`);
+      break;
+    case 'skipped':
+      console.log(`\nSkipping the npm upgrade — ${result.reason}.`);
+      break;
+    default:
+      break;
+  }
+}
+
+/** Name only what this run actually installed. */
+function restartNote(report) {
+  const parts = [];
+  if (report.skillsInstalled !== false) parts.push('skills');
+  if (report.persona.length) parts.push('persona');
+  const what = parts.length === 2 ? 'skills and persona are' : `${parts[0] || 'files'} ${parts[0] === 'skills' ? 'are' : 'is'}`;
+  console.log('\nRestart your agent session (Claude Code, Codex, Copilot, Gemini CLI)');
+  console.log(`so the ${what} picked up.\n`);
+}
+
 function printDoctor(result) {
   const { checked } = result;
   console.log(
@@ -160,6 +205,19 @@ function printDoctor(result) {
   }
 }
 
+function targetsJson(mode, projectRoot) {
+  return TARGETS.map((t) => {
+    const spec = mode === 'project' ? t.project : t.global;
+    return {
+      id: t.id,
+      label: t.label,
+      default: Boolean(t.default),
+      skills: spec.skills ? resolveTargetPath(spec.skills, mode, projectRoot) : null,
+      instructions: spec.instructions ? resolveTargetPath(spec.instructions, mode, projectRoot) : null,
+    };
+  });
+}
+
 function printTargets(mode) {
   console.log('');
   for (const t of TARGETS) {
@@ -197,8 +255,55 @@ function main() {
 
   try {
     switch (opts.command) {
-      case 'install':
       case 'update': {
+        // `update` used to be a plain alias for `install`, which only re-copied the
+        // 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;
+        if (opts.selfUpdate) {
+          selfResult = selfUpdate({
+            dryRun: opts.dryRun,
+            log: (msg) => {
+              if (!opts.json) console.log(msg);
+            },
+          });
+          if (!opts.json) printSelfUpdate(selfResult);
+
+          if (selfResult.status === 'upgraded') {
+            const passthrough = process.argv.slice(2).filter((a) => a !== 'update');
+            const code = reexec(['install', ...passthrough], selfResult.latest);
+            if (code !== null) process.exit(code);
+            // Could not re-exec: fall through and install with what is loaded.
+            if (!opts.json) {
+              console.log('\nCould not restart the upgraded CLI — run `bt-agent install` to finish.');
+            }
+          }
+        }
+
+        const report = install(common);
+        const check = doctor(common);
+
+        if (opts.json) {
+          console.log(JSON.stringify({ ...report, selfUpdate: selfResult, doctor: check }, null, 2));
+        } else {
+          printInstall(report);
+          if (!opts.dryRun) {
+            console.log('');
+            if (check.ok) {
+              console.log('INSTALL OK');
+              restartNote(report);
+            } else {
+              printDoctor(check);
+            }
+          } else {
+            console.log('\nDry run — nothing was written.\n');
+          }
+        }
+        process.exit(opts.dryRun || check.ok ? 0 : 1);
+        break;
+      }
+
+      case 'install': {
         const report = install(common);
         const check = doctor(common);
 
@@ -210,8 +315,7 @@ function main() {
             console.log('');
             if (check.ok) {
               console.log('INSTALL OK');
-              console.log('\nRestart your agent session (Claude Code, Codex, Copilot, Gemini CLI)');
-              console.log('so the skills and persona are picked up.\n');
+              restartNote(report);
             } else {
               printDoctor(check);
             }
@@ -246,7 +350,8 @@ function main() {
       }
 
       case 'targets':
-        printTargets(opts.mode);
+        if (opts.json) console.log(JSON.stringify(targetsJson(opts.mode, process.cwd()), null, 2));
+        else printTargets(opts.mode);
         break;
 
       case 'help':

package/lib/manifest.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const { manifestPath } = require('./paths');
+const { manifestPath, stateDir } = require('./paths');
 
 /**
  * Record of what this tool wrote, so update and uninstall can touch only its own
@@ -30,10 +30,16 @@ function remove(mode, projectRoot) {
   const file = manifestPath(mode, projectRoot);
   try {
     fs.unlinkSync(file);
-    return true;
   } catch {
     return false;
   }
+  // Leave nothing of our own behind: drop the state directory once it is empty.
+  try {
+    fs.rmdirSync(stateDir(mode, projectRoot));
+  } catch {
+    /* the user put something else in there — keep it */
+  }
+  return true;
 }
 
 /** Skill folder names previously installed into `dir`, per the manifest. */

package/lib/selfupdate.js

@@ -0,0 +1,242 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { PACKAGE_ROOT } = require('./paths');
+const pkg = require('../package.json');
+
+const PACKAGE_NAME = pkg.name;
+const CURRENT_VERSION = pkg.version;
+
+/** Set on the re-executed child so the upgraded CLI does not try to upgrade again. */
+const GUARD_ENV = 'BT_AGENT_SELF_UPDATED';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+function segments(p) {
+  return p.split(/[\\/]+/);
+}
+
+/**
+ * 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.
+ */
+function detectInstall() {
+  const parts = segments(PACKAGE_ROOT);
+  const lower = parts.map((s) => s.toLowerCase());
+
+  if (fs.existsSync(path.join(PACKAGE_ROOT, '.git'))) {
+    return { kind: 'dev', manager: null, root: PACKAGE_ROOT };
+  }
+  if (lower.some((s) => s === '_npx' || s === '.npx')) {
+    return { kind: 'npx', manager: null, root: PACKAGE_ROOT };
+  }
+
+  const manager = lower.includes('pnpm') || lower.includes('.pnpm')
+    ? 'pnpm'
+    : lower.includes('.yarn') || lower.includes('yarn')
+      ? 'yarn'
+      : lower.includes('.bun')
+        ? 'bun'
+        : 'npm';
+
+  return { kind: isGlobal() ? 'global' : 'local', manager, root: PACKAGE_ROOT };
+}
+
+/** True when PACKAGE_ROOT lives under this machine's global module directory. */
+function isGlobal() {
+  const roots = [];
+  try {
+    roots.push(String(execFileSync(npmBin(), ['root', '-g'], { encoding: 'utf8', timeout: 20000 })).trim());
+  } catch {
+    /* npm unavailable or slow — fall back to path shape below */
+  }
+
+  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;
+
+  // 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());
+}
+
+function npmBin() {
+  return IS_WINDOWS ? 'npm.cmd' : 'npm';
+}
+
+function managerBin(manager) {
+  const name = manager === 'npm' ? 'npm' : manager;
+  return IS_WINDOWS && name !== 'bun' ? `${name}.cmd` : name;
+}
+
+/** The exact command a user can copy/paste if the automatic upgrade fails. */
+function upgradeCommand(manager, version) {
+  const spec = `${PACKAGE_NAME}@${version || 'latest'}`;
+  switch (manager) {
+    case 'pnpm': return `pnpm add -g ${spec}`;
+    case 'yarn': return `yarn global add ${spec}`;
+    case 'bun': return `bun add -g ${spec}`;
+    default: return `npm install -g ${spec}`;
+  }
+}
+
+function upgradeArgs(manager, version) {
+  const spec = `${PACKAGE_NAME}@${version || 'latest'}`;
+  switch (manager) {
+    case 'pnpm': return ['add', '-g', spec];
+    case 'yarn': return ['global', 'add', spec];
+    case 'bun': return ['add', '-g', spec];
+    default: return ['install', '-g', spec];
+  }
+}
+
+/** Compare two semver-ish versions. Pre-release tags sort before their release. */
+function compareVersions(a, b) {
+  const split = (v) => {
+    const [core, pre] = String(v).split('-');
+    return { nums: core.split('.').map((n) => parseInt(n, 10) || 0), pre: pre || null };
+  };
+  const x = split(a);
+  const y = split(b);
+  for (let i = 0; i < 3; i += 1) {
+    if ((x.nums[i] || 0) !== (y.nums[i] || 0)) return (x.nums[i] || 0) < (y.nums[i] || 0) ? -1 : 1;
+  }
+  if (x.pre === y.pre) return 0;
+  if (!x.pre) return 1;
+  if (!y.pre) return -1;
+  return x.pre < y.pre ? -1 : 1;
+}
+
+/**
+ * Latest published version, from npm first so the user's registry, proxy and auth
+ * settings are honoured, then from registry.npmjs.org if the npm CLI is missing.
+ */
+function fetchLatestVersion({ timeout = 20000 } = {}) {
+  try {
+    const out = execFileSync(npmBin(), ['view', PACKAGE_NAME, 'version'], {
+      encoding: 'utf8',
+      timeout,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const v = String(out).trim().split(/\s+/).pop();
+    if (v) return { version: v };
+  } catch (err) {
+    const reason = (err && (err.stderr || err.message) ? String(err.stderr || err.message) : '').trim();
+    const fallback = fetchLatestFromRegistrySync(timeout);
+    if (fallback) return { version: fallback };
+    return { error: reason.split('\n').filter(Boolean).pop() || 'could not reach the npm registry' };
+  }
+  return { error: 'npm returned no version' };
+}
+
+/** Registry lookup without the npm CLI. Runs in a helper process so it can be sync. */
+function fetchLatestFromRegistrySync(timeout) {
+  const script = `
+    const https = require('https');
+    const url = 'https://registry.npmjs.org/' + encodeURIComponent(${JSON.stringify(PACKAGE_NAME)}).replace('%40','@') + '/latest';
+    const req = https.get(url, { headers: { accept: 'application/json' } }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try { process.stdout.write(String(JSON.parse(body).version || '')); } catch { process.stdout.write(''); }
+      });
+    });
+    req.setTimeout(${Math.max(1000, timeout)}, () => req.destroy());
+    req.on('error', () => process.stdout.write(''));
+  `;
+  try {
+    const out = execFileSync(process.execPath, ['-e', script], { encoding: 'utf8', timeout: timeout + 2000 });
+    return String(out).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Bring the installed package itself up to date.
+ *
+ * `update` used to be a pure alias for `install`: it re-copied the payload already
+ * on disk, so it could never deliver a newer release and `npm install -g` was the
+ * only way to actually update. This fetches the published version first, upgrades
+ * the global package when there is a newer one, and reports what happened.
+ *
+ * Returns a status object; it never throws.
+ */
+function selfUpdate({ dryRun = false, timeout = 20000, log = () => {} } = {}) {
+  const install = detectInstall();
+  const base = { current: CURRENT_VERSION, install: install.kind, manager: install.manager };
+
+  if (process.env[GUARD_ENV]) {
+    return { ...base, status: 'skipped', reason: 'already upgraded in this run' };
+  }
+  if (install.kind !== 'global') {
+    const why = {
+      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',
+    }[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 (compareVersions(latest, CURRENT_VERSION) <= 0) {
+    return { ...base, latest, status: 'current' };
+  }
+
+  const command = upgradeCommand(install.manager, latest);
+  if (dryRun) return { ...base, latest, status: 'would-upgrade', command };
+
+  log(`Upgrading ${CURRENT_VERSION} -> ${latest} (${command})`);
+  try {
+    execFileSync(managerBin(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: 'upgraded', command };
+}
+
+/**
+ * Hand control to the freshly installed CLI so the skills that get copied are the
+ * new ones. The running process still has the previous release's modules in memory.
+ */
+function reexec(argv, version) {
+  const { spawnSync } = require('child_process');
+  const script = process.argv[1];
+  if (!script || !fs.existsSync(script)) return null;
+
+  const result = spawnSync(process.execPath, [script, ...argv], {
+    stdio: 'inherit',
+    env: { ...process.env, [GUARD_ENV]: version || '1' },
+  });
+  if (result.error) return null;
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  CURRENT_VERSION,
+  GUARD_ENV,
+  detectInstall,
+  compareVersions,
+  fetchLatestVersion,
+  upgradeCommand,
+  selfUpdate,
+  reexec,
+};

package/package.json

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