@base_bit/vmg-cli 0.0.3 → 0.0.5

package/README.md

@@ -32,6 +32,48 @@ absolute private writable base; `vmg doctor --json` reports the resource locatio
 A damaged cache is an error: stop processes using the affected hash, remove only
 that hash directory and retry. Older hashes are retained across upgrades.
 
-Upgrade with `npm install -g @base_bit/vmg-cli@latest`; uninstall with
+Upgrade with `vmg update` (or `npm install -g @base_bit/vmg-cli@latest`); uninstall with
 `npm uninstall -g @base_bit/vmg-cli`. Cached runtime resources remain on disk.
 The independently distributed native binary continues to work without npm.
+
+## Updates
+
+```sh
+vmg update --check             # Query latest without installing
+vmg update                    # Upgrade a confirmed npm global installation
+vmg update --check --json      # Structured result for scripts
+vmg update --timeout-seconds 300
+```
+
+The npm launcher queries the configured npm registry in global mode (including
+user/global npm configuration and environment settings, excluding project
+`.npmrc`). It compares semantic versions against `latest`, never downgrades, and
+installs the exact checked version with its matching platform package. Automatic
+installation requires the current package to be directly inside the active npm
+global root with a matching prefix; linked packages and detected pnpm/yarn layouts
+are excluded. If a different Node/npm installation is active, switch back to the
+one that owns VMG. Project-local, npx and other package-manager installs receive
+manual instructions. Standalone binaries must be replaced manually.
+
+Updates retain the npm prefix, enable optional dependencies and disable install
+scripts. Success means the entry package, platform package and native executable
+all report the requested version. No administrator escalation is attempted. npm
+installation is not an atomic transaction: errors, interruption or timeout can
+leave an incomplete installation; follow the reported reinstall instruction.
+Concurrent updates to the same installation wait for a lock within the timeout.
+A stale lock error names the file to remove after confirming no update is running.
+Old runtime caches are retained.
+
+Ordinary interactive commands check in parallel at most once every **12 hours**,
+with a three-second limit. Checks stop when the command exits. Notices go to
+stderr and show the current/latest versions. Network or cache failures are silent
+and do not change the command's result. Checks are disabled for non-interactive
+runs, CI, `--json`, help and version output. Set `VMG_NO_UPDATE_NOTIFIER=1` to opt
+out. Attempts and results are cached separately under `vmg/updates` in the user's
+cache directory (on macOS, `~/Library/Caches`, or absolute `XDG_CACHE_HOME`).
+
+Explicit `update --check` bypasses that cache and reports registry errors. Its
+successful exit status is 0 even when an update is available. `--json` returns
+`ok`, `currentVersion`, `latestVersion`, `updateAvailable` and `updated`; successful
+installation additionally includes `installedVersion`. Errors and unsupported
+installation attempts exit nonzero; npm logs never mix into JSON stdout.

package/bin/npm-update.mjs

@@ -0,0 +1,199 @@
+import { spawn } from 'node:child_process';
+import { readFile, realpath, mkdir, open, rename, rm, access } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const packageName = '@base_bit/vmg-cli';
+export const checkInterval = 12 * 60 * 60 * 1000;
+const shellQuote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+const repair = 'npm install -g @base_bit/vmg-cli@latest --include=optional --ignore-scripts';
+const readJson = async path => JSON.parse(await readFile(path, 'utf8'));
+const exists = async path => access(path).then(() => true, () => false);
+
+function versionParts(value) {
+  if (typeof value !== 'string') throw new Error('Invalid npm version');
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(value);
+  if (!match || match[4]?.split('.').some(x => /^\d+$/.test(x) && x.length > 1 && x[0] === '0')) throw new Error(`Invalid npm version: ${value}`);
+  return { core: match.slice(1, 4).map(BigInt), pre: match[4]?.split('.') };
+}
+export function compareVersions(a, b) {
+  const left = versionParts(a), right = versionParts(b);
+  for (let i = 0; i < 3; i++) if (left.core[i] !== right.core[i]) return left.core[i] > right.core[i] ? 1 : -1;
+  if (!left.pre || !right.pre) return left.pre ? -1 : right.pre ? 1 : 0;
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+    const x = left.pre[i], y = right.pre[i];
+    if (x === y) continue;
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1;
+    const nx = /^\d+$/.test(x), ny = /^\d+$/.test(y);
+    if (nx && ny) return BigInt(x) > BigInt(y) ? 1 : -1;
+    if (nx !== ny) return nx ? -1 : 1;
+    return x > y ? 1 : -1;
+  }
+  return 0;
+}
+
+// Parse only the update command. Every other command keeps Rust's parser.
+export function parseUpdate(args) {
+  let command, check = false, json = false, timeout = 120, invalid;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') json = true;
+    else if (arg === '--timeout-seconds' || arg.startsWith('--timeout-seconds=')) {
+      const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : args[++i];
+      if (!/^\d+$/.test(value ?? '') || +value < 1 || +value > 3600) invalid = 'timeout-seconds must be between 1 and 3600';
+      else timeout = +value;
+    } else if (!command && !arg.startsWith('-')) command = arg;
+    else if (arg === '--check' && command === 'update') check = true;
+    else if (arg === '--help' || arg === '-h') return null;
+    else invalid = `Unexpected argument: ${arg}`;
+  }
+  if (command !== 'update') return null;
+  if (invalid) throw new Error(invalid);
+  return { check, json, timeout };
+}
+
+// Own the npm process group; capture logs so --json remains a single result.
+export function runCommand(program, args, { signal, cwd = homedir(), env = process.env } = {}) {
+  signal?.throwIfAborted();
+  return new Promise((resolveResult, reject) => {
+    const child = spawn(program, args, { cwd, env, shell: false, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '', failure, escalation;
+    const kill = sig => { try { process.kill(-child.pid, sig); } catch { child.kill(sig); } };
+    const stop = () => {
+      failure ??= signal?.reason ?? new Error('Command cancelled');
+      kill(failure.signal ?? 'SIGTERM');
+      escalation ??= setTimeout(() => kill('SIGKILL'), 1000);
+    };
+    const collect = stream => bytes => {
+      if (stdout.length + stderr.length + bytes.length > 2 * 1024 * 1024) { failure = new Error('npm output exceeded limit'); stop(); return; }
+      if (stream === 'stdout') stdout += bytes; else stderr += bytes;
+    };
+    child.stdout.on('data', collect('stdout')); child.stderr.on('data', collect('stderr'));
+    signal?.addEventListener('abort', stop, { once: true });
+    if (signal?.aborted) stop();
+    child.once('error', error => { failure = error; });
+    child.once('close', (code, termination) => {
+      clearTimeout(escalation); signal?.removeEventListener('abort', stop);
+      // No npm helper may outlive the owned operation.
+      try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+      if (failure) reject(failure);
+      else if (code !== 0) reject(new Error(`${program} failed (${termination ?? code}): ${stderr.trim() || stdout.trim()}`));
+      else resolveResult(stdout.trim());
+    });
+  });
+}
+
+export function context({ signal, run = runCommand } = {}) {
+  const options = { signal, cwd: homedir() };
+  return { signal, npm: args => run('npm', args, options), run: (program, args) => run(program, args, options) };
+}
+async function latestVersion(ctx) {
+  const latest = JSON.parse(await ctx.npm(['view', `${packageName}@latest`, 'version', '--json', '--prefer-online', '--global']));
+  versionParts(latest);
+  return latest;
+}
+export async function installation(packageJson, ctx) {
+  const rootPath = await ctx.npm(['root', '--global']);
+  const prefix = await ctx.npm(['prefix', '--global']);
+  if (!isAbsolute(rootPath) || !isAbsolute(prefix)) return null;
+  const root = await realpath(rootPath).catch(() => null);
+  if (!root) return null;
+  const expected = join(root, packageName, 'package.json');
+  const actual = await realpath(packageJson);
+  // npm's layout is direct. pnpm stores and linked packages are not ours to mutate.
+  if (actual !== expected || await exists(join(root, '.modules.yaml')) || await exists(join(root, '.yarn-integrity'))) return null;
+  if (root !== await realpath(join(prefix, 'lib', 'node_modules')).catch(() => null)) return null;
+  if ((await readJson(actual)).name !== packageName) return null;
+  return { root, prefix, packageJson: actual };
+}
+
+async function lockInstallation(root, signal) {
+  const path = join(root, '@base_bit', '.vmg-update.lock');
+  for (;;) {
+    signal?.throwIfAborted();
+    try {
+      const file = await open(path, 'wx', 0o600);
+      try { await file.writeFile(JSON.stringify({ pid: process.pid, createdAt: Date.now() })); }
+      catch (error) { await file.close(); await rm(path, { force: true }); throw error; }
+      await file.close();
+      return () => rm(path, { force: true });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const owner = await readJson(path).catch(() => null);
+      if (Number.isSafeInteger(owner?.pid) && owner.pid > 0) {
+        try { process.kill(owner.pid, 0); }
+        catch (cause) {
+          if (cause.code === 'ESRCH') throw new Error(`Stale update lock: ${path}. Remove it after confirming no update is running.`);
+        }
+      }
+      await new Promise(resolveWait => setTimeout(resolveWait, 100));
+    }
+  }
+}
+
+export async function update(packageJson, options, { ctx = context(), platformName, resolveBinary } = {}) {
+  const original = await readJson(packageJson);
+  const latest = await latestVersion(ctx);
+  const summary = { ok: true, currentVersion: original.version, latestVersion: latest, updateAvailable: compareVersions(latest, original.version) > 0, updated: false };
+  if (options.check) return summary;
+  const location = await installation(packageJson, ctx);
+  if (!location) return { ...summary, ok: false, message: 'Automatic updates require a confirmed npm global installation. For a project dependency use its package manager; for npx run npx @base_bit/vmg-cli@latest; for pnpm/yarn use their global update command. For npm global installation: ' + repair };
+  if (!summary.updateAvailable) return summary;
+  const unlock = await lockInstallation(location.root, ctx.signal);
+  let installStarted = false;
+  try {
+    const current = await readJson(packageJson);
+    summary.currentVersion = current.version;
+    summary.updateAvailable = compareVersions(latest, current.version) > 0;
+    if (!summary.updateAvailable) return summary;
+    if (!platformName) throw new Error('This platform is not supported by VMG');
+    const available = JSON.parse(await ctx.npm(['view', `${platformName}@${latest}`, 'version', '--json', '--prefer-online', '--global']));
+    if (available !== latest) throw new Error(`Missing matching platform package ${platformName}@${latest}`);
+    ctx.signal?.throwIfAborted();
+    installStarted = true;
+    await ctx.npm(['install', '--global', '--prefix', location.prefix, `${packageName}@${latest}`, '--include=optional', '--ignore-scripts', '--no-audit', '--no-fund']);
+    ctx.signal?.throwIfAborted();
+    if ((await readJson(packageJson)).version !== latest) throw new Error('Installed entry package does not match the requested version');
+    const binary = resolveBinary(packageJson);
+    if (await ctx.run(binary, ['--version']) !== `vmg ${latest}`) throw new Error('Installed native binary version does not match the requested version');
+    return { ...summary, updated: true, installedVersion: latest };
+  } catch (error) {
+    if (!installStarted) throw error;
+    throw new Error(`${error.message}\nInstallation may be incomplete. Repair the same npm prefix with: npm install -g --prefix ${shellQuote(location.prefix)} ${packageName}@${latest} --include=optional --ignore-scripts`, { cause: error });
+  } finally { await unlock(); }
+}
+
+export function shouldNotify(args, env = process.env, tty = process.stdin.isTTY && process.stderr.isTTY) {
+  return Boolean(tty && !env.CI && env.VMG_NO_UPDATE_NOTIFIER !== '1' && !args.some(x => ['--json', '--help', '-h', '--version', '-V'].includes(x)));
+}
+export function notificationCache(packageJson) {
+  const base = process.env.XDG_CACHE_HOME && resolve(process.env.XDG_CACHE_HOME) === process.env.XDG_CACHE_HOME
+    ? process.env.XDG_CACHE_HOME : process.platform === 'darwin' ? join(homedir(), 'Library', 'Caches') : join(homedir(), '.cache');
+  return join(base, 'vmg', 'updates', createHash('sha256').update(packageJson).digest('hex') + '.json');
+}
+export async function notify(packageJson, { ctx = context(), cachePath = notificationCache(packageJson), now = Date.now(), emit = text => process.stderr.write(text) } = {}) {
+  try {
+    const current = (await readJson(packageJson)).version;
+    const cached = await readJson(cachePath).catch(() => null);
+    let latest = cached?.latest;
+    if (!(Number.isFinite(cached?.checkedAt) && now >= cached.checkedAt && now - cached.checkedAt < checkInterval)) {
+      await mkdir(dirname(cachePath), { recursive: true, mode: 0o700 });
+      // Record attempts too, so offline sessions do not repeatedly spawn npm.
+      const save = async value => {
+        const temporary = `${cachePath}.${randomUUID()}.tmp`;
+        try {
+          const file = await open(temporary, 'wx', 0o600);
+          try { await file.writeFile(JSON.stringify(value)); } finally { await file.close(); }
+          await rename(temporary, cachePath);
+        } finally { await rm(temporary, { force: true }); }
+      };
+      await save({ checkedAt: now });
+      latest = await latestVersion(ctx);
+      ctx.signal?.throwIfAborted();
+      await save({ checkedAt: now, latest });
+    }
+    ctx.signal?.throwIfAborted();
+    if (latest && compareVersions(latest, current) > 0) emit(`VMG update available: ${current} → ${latest}. Run vmg update (npm global installs); otherwise update with your package manager.\n`);
+  } catch { /* Best effort only: never change a normal command's outcome. */ }
+}

package/bin/vmg.mjs

@@ -4,6 +4,7 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseUpdate, update, context, shouldNotify, notify } from './npm-update.mjs';
 
 export const platforms = Object.freeze({ 'darwin-arm64': '@base_bit/vmg-cli-darwin-arm64' });
 
@@ -24,23 +25,64 @@ export function resolveBinary(packageJson, platform = process.platform, arch = p
 }
 
 export function launch(binary, args) {
-  // Keep Rust attached to the terminal. Rust owns the separately grouped bridge
-  // and must finish reaping it before this launcher exits.
-  const child = spawn(binary, args, { stdio: 'inherit', shell: false });
-  const interrupt = () => child.kill('SIGINT'), terminate = () => child.kill('SIGTERM');
-  process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
-  const cleanup = () => { process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); };
-  let spawnFailed = false;
-  child.once('error', error => { spawnFailed = true; cleanup(); console.error(`vmg: Cannot start platform binary: ${error.message}`); process.exitCode = 1; });
-  child.once('close', (code, signal) => {
-    cleanup();
-    if (spawnFailed) return;
-    if (signal) process.kill(process.pid, signal);
-    else process.exitCode = code ?? 1;
+  return new Promise(resolveDone => {
+    // Keep Rust attached to the terminal. Rust owns the separately grouped bridge
+    // and must finish reaping it before this launcher exits.
+    const child = spawn(binary, args, { stdio: 'inherit', shell: false });
+    const interrupt = () => child.kill('SIGINT'), terminate = () => child.kill('SIGTERM');
+    process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
+    const cleanup = () => { process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); };
+    let spawnFailed = false;
+    child.once('error', error => { spawnFailed = true; cleanup(); console.error(`vmg: Cannot start platform binary: ${error.message}`); process.exitCode = 1; });
+    child.once('close', (code, signal) => {
+      cleanup();
+      if (spawnFailed) { resolveDone(); return; }
+      process.exitCode = code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1);
+      resolveDone(signal);
+    });
   });
 }
 
+export async function main(args, packageJson) {
+  const options = parseUpdate(args);
+  const controller = new AbortController();
+  if (options) {
+    const stop = signal => {
+      const error = new Error(`Update interrupted by ${signal}`);
+      error.signal = signal; controller.abort(error);
+      process.exitCode = signal === 'SIGINT' ? 130 : 143;
+    };
+    const interrupt = () => stop('SIGINT'), terminate = () => stop('SIGTERM');
+    process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
+    const timer = setTimeout(() => controller.abort(new Error('Update timed out')), options.timeout * 1000);
+    try {
+      const result = await update(packageJson, options, { ctx: context({ signal: controller.signal }), platformName: platforms[`${process.platform}-${process.arch}`], resolveBinary });
+      controller.signal.throwIfAborted();
+      if (options.json) console.log(JSON.stringify(result));
+      else if (result.message) console.log(result.message);
+      else if (result.updated) console.log(`VMG updated: ${result.currentVersion} → ${result.installedVersion}`);
+      else console.log(result.updateAvailable ? `VMG update available: ${result.currentVersion} → ${result.latestVersion}. Run vmg update.` : `VMG ${result.currentVersion} is up to date (latest: ${result.latestVersion}).`);
+      if (!result.ok) process.exitCode = 1;
+    } finally {
+      clearTimeout(timer); process.off('SIGINT', interrupt); process.off('SIGTERM', terminate);
+    }
+    return;
+  }
+  const binary = resolveBinary(packageJson);
+  const finished = launch(binary, args);
+  const timer = setTimeout(() => controller.abort(new Error('Update check timed out')), 3000);
+  const notification = shouldNotify(args) ? notify(packageJson, { ctx: context({ signal: controller.signal }) }) : Promise.resolve();
+  const signal = await finished;
+  controller.abort(new Error('VMG command finished')); clearTimeout(timer);
+  await notification;
+  if (signal) process.kill(process.pid, signal);
+}
+
 if (process.argv[1] && pathToFileURL(realpathSync(resolve(process.argv[1]))).href === import.meta.url) {
-  try { launch(resolveBinary(fileURLToPath(new URL('../package.json', import.meta.url))), process.argv.slice(2)); }
-  catch (error) { console.error(`vmg: ${error.message}`); process.exitCode = 1; }
+  try { await main(process.argv.slice(2), fileURLToPath(new URL('../package.json', import.meta.url))); }
+  catch (error) {
+    if (process.argv.slice(2).includes('--json')) console.error(JSON.stringify({ error: error.message }));
+    else console.error(`vmg: ${error.message}`);
+    process.exitCode ||= 1;
+  }
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.3",
+  "version": "0.0.5",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -15,10 +15,11 @@
     "vmg": "bin/vmg.mjs"
   },
   "optionalDependencies": {
-    "@base_bit/vmg-cli-darwin-arm64": "0.0.3"
+    "@base_bit/vmg-cli-darwin-arm64": "0.0.5"
   },
   "files": [
     "bin/vmg.mjs",
+    "bin/npm-update.mjs",
     "README.md",
     "LICENSE",
     "NOTICE",