shakers-cli-beta 0.10.4 → 0.11.0

package/bin/shakers.js

@@ -46,7 +46,11 @@ const { run: runRegister } = require('./register');
 const { run: runOnboarding } = require('./onboarding');
 const { run: runConfig } = require('./config');
 const { run: runMcp } = require('./mcp');
+const { run: runUpdate } = require('./update');
 const { checkOnboardingCompleted } = require('../src/onboarding-availability');
+const { emitCommandAudit } = require('../src/command-audit');
+const { readPackageInfo } = require('../src/update-flow');
+const { isSuppressed, maybeNotify, triggerBackgroundCheck } = require('../src/update-notifier');
 
 let VERSION = '';
 try {
@@ -95,13 +99,14 @@ const HANDLERS = {
   register: runRegister,
   onboarding: runOnboarding,
   config: runConfig,
+  update: runUpdate,
   login: runLogin,
   logout: runLogout,
   superadmin: runSuperadmin,
   mcp: runMcp,
 };
 
-const SESSION_EXEMPT = new Set(['ai-usage', 'register', 'config', 'login', 'logout', 'superadmin', 'mcp', 'share', 'alma']);
+const SESSION_EXEMPT = new Set(['ai-usage', 'register', 'config', 'login', 'logout', 'superadmin', 'mcp', 'share', 'alma', 'update']);
 
 // Command FAMILIES — a navigation layer over the flat commands (which all stay
 // valid as aliases). `shakers <family> <sub>` resolves to the flat handler; every
@@ -119,7 +124,7 @@ const FAMILIES = {
     invitations: 'invitations', applications: 'applications',
   },
   usage: { run: 'ai-usage', report: 'report', share: 'share' },
-  account: { login: 'login', logout: 'logout', register: 'register', config: 'config' },
+  account: { login: 'login', logout: 'logout', register: 'register', config: 'config', update: 'update' },
   certs: { list: 'certifications', certify: 'certify' },
 };
 
@@ -212,12 +217,13 @@ function usageText(lang, { hideOnboarding = false } = {}) {
       + `  Sesión:\n`
       + `    login        Inicia sesión en tu cuenta de Shakers\n`
       + `    logout       Cierra la sesión\n`
-      + `    config       Lee/escribe la configuración (bases de hub/certs)\n\n`
+      + `    config       Lee/escribe la configuración (bases de hub/certs)\n`
+      + `    update       Actualiza el CLI a la última versión publicada (--check solo informa)\n\n`
       + `  Familias (agrupan los comandos de arriba; los nombres planos siguen valiendo como alias):\n`
       + `    add <skill|agent|project|role>     ·  role <add|change>\n`
       + `    profile <show|rate|languages|socials|experiences|portfolios|availability|certifications>\n`
       + `    projects <find|show|save|unsave|invitations|applications>\n`
-      + `    usage <run|report|share>  ·  certs <list|certify>  ·  account <login|logout|register|config>\n`
+      + `    usage <run|report|share>  ·  certs <list|certify>  ·  account <login|logout|register|config|update>\n`
       + `    Ejecuta \`shakers <familia>\` (sin subcomando) para ver sus subcomandos.\n\n`
       + `  Ejecuta shakers <comando> --help para las opciones de cada comando.\n\n`;
   }
@@ -255,12 +261,13 @@ function usageText(lang, { hideOnboarding = false } = {}) {
     + `  Session:\n`
     + `    login        Sign in to your Shakers account\n`
     + `    logout       Sign out\n`
-    + `    config       Read/write configuration (hub/certs bases)\n\n`
+    + `    config       Read/write configuration (hub/certs bases)\n`
+    + `    update       Update the CLI to the latest published version (--check only reports)\n\n`
     + `  Families (group the commands above; the flat names still work as aliases):\n`
     + `    add <skill|agent|project|role>     ·  role <add|change>\n`
     + `    profile <show|rate|languages|socials|experiences|portfolios|availability|certifications>\n`
     + `    projects <find|show|save|unsave|invitations|applications>\n`
-    + `    usage <run|report|share>  ·  certs <list|certify>  ·  account <login|logout|register|config>\n`
+    + `    usage <run|report|share>  ·  certs <list|certify>  ·  account <login|logout|register|config|update>\n`
     + `    Run \`shakers <family>\` (no subcommand) to list its subcommands.\n\n`
     + `  Run \`shakers <command> --help\` for a command's options.\n\n`;
 }
@@ -295,6 +302,18 @@ async function main() {
   try { await ensureFreshSession(process.env); } catch { /* never blocks a command */ }
 
   const token = argv.find((a) => !a.startsWith('-'));
+
+  // Single dispatch choke-point (ADR-060): audit EXACTLY once before branching, fire-and-forget (never awaited). MCP tool calls run in-process and never reach here.
+  const auditCommand =
+    !token || token.toLowerCase() === 'help' ? 'help' : token.toLowerCase();
+  emitCommandAudit({ command: auditCommand, argv, env: process.env });
+
+  // Non-blocking update notice: reads a cached version synchronously, registry check runs in a detached worker; stderr-only, suppressed for --json/non-TTY/CI/update/opt-out.
+  if (!isSuppressed({ argv, command: auditCommand, env: process.env })) {
+    maybeNotify({ currentVersion: VERSION, lang, env: process.env });
+    triggerBackgroundCheck({ name: readPackageInfo().name, env: process.env });
+  }
+
   if (!token || token.toLowerCase() === 'help') {
     let hideOnboarding = false;
     try {

package/bin/update-check-worker.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+'use strict';
+
+// Detached worker: fetches the latest version from the PUBLIC, unauthenticated npm registry, writes the `{lastCheck, latest}` cache, fails silent.
+
+const https = require('https');
+const { writeCache } = require('../src/update-notifier');
+
+const FETCH_TIMEOUT_MS = 10000;
+const MAX_BODY_BYTES = 3 * 1024 * 1024;
+
+// Scoped names (`@scope/pkg`) address the registry as `@scope%2fpkg`, `@` literal; install-v1 metadata still carries `dist-tags`.
+function registryUrl(name) {
+  const p = name.startsWith('@') ? `@${name.slice(1).replace('/', '%2f')}` : name;
+  return `https://registry.npmjs.org/${p}`;
+}
+
+function fetchLatest(name, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => {
+      if (!settled) {
+        settled = true;
+        resolve(v);
+      }
+    };
+    let req;
+    try {
+      req = https.get(
+        registryUrl(name),
+        { headers: { Accept: 'application/vnd.npm.install-v1+json' } },
+        (res) => {
+          if (res.statusCode !== 200) {
+            res.resume();
+            return done(null);
+          }
+          let body = '';
+          res.setEncoding('utf8');
+          res.on('data', (c) => {
+            body += c;
+            if (body.length > MAX_BODY_BYTES) req.destroy();
+          });
+          res.on('end', () => {
+            try {
+              const json = JSON.parse(body);
+              const latest = json && json['dist-tags'] && json['dist-tags'].latest;
+              done(typeof latest === 'string' && latest ? latest : null);
+            } catch {
+              done(null);
+            }
+          });
+        },
+      );
+    } catch {
+      return done(null);
+    }
+    req.setTimeout(timeoutMs, () => req.destroy());
+    req.on('error', () => done(null));
+  });
+}
+
+async function main() {
+  const name = process.argv[2];
+  if (!name) return;
+  const latest = await fetchLatest(name, FETCH_TIMEOUT_MS);
+  if (!latest) return;
+  writeCache({ lastCheck: Date.now(), latest });
+}
+
+main();

package/bin/update.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+'use strict';
+
+// `update` — update the CLI to the latest published version (CLI-only, never an MCP tool); `--check` reports without installing. Logic in src/update-flow.js.
+
+const { detectReportLang, getCatalog } = require('../src/i18n');
+const updateFlow = require('../src/update-flow');
+
+function parseUpdateArgs(argv = []) {
+  const o = { help: false, check: false, json: false, lang: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '--check' || a === '--dry-run') o.check = true;
+    else if (a === '--json') o.json = true;
+    else if (a === '--lang') {
+      const v = argv[++i];
+      o.lang = v === 'es' || v === 'en' ? v : null;
+    } else if (a.startsWith('--lang=')) {
+      const v = a.slice(7);
+      o.lang = v === 'es' || v === 'en' ? v : null;
+    }
+  }
+  return o;
+}
+
+async function run(
+  argv = process.argv.slice(2),
+  { out = null, env = process.env, deps = null } = {},
+) {
+  const opts = parseUpdateArgs(argv);
+  const lang = opts.lang || detectReportLang();
+  const t = getCatalog(lang).cli.update;
+  const write = out || ((s) => process.stdout.write(s));
+  const flow = deps || updateFlow;
+
+  if (opts.help) {
+    write(t.help + '\n');
+    return;
+  }
+
+  const info = flow.readPackageInfo();
+  const install = flow.detectInstall(env);
+  const current = info.version;
+
+  if (!opts.json) write(`  ${t.checking}\n`);
+  const latest = flow.fetchLatestVersion(info);
+
+  if (opts.json) {
+    const updateAvailable =
+      latest.ok && current ? flow.compareVersions(current, latest.version) < 0 : null;
+    write(
+      `${JSON.stringify({
+        package: info.name,
+        current: current || null,
+        latest: latest.ok ? latest.version : null,
+        install: install.kind,
+        updateAvailable,
+        reason: latest.ok ? null : latest.reason,
+      })}\n`,
+    );
+    if (!latest.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (current) write(`  ${t.current(current)}\n`);
+
+  if (!latest.ok) {
+    write(`  ${t.latestUnknown(latest.reason)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!current || flow.compareVersions(current, latest.version) >= 0) {
+    write(`  ${t.upToDate(latest.version)}\n`);
+    return;
+  }
+
+  write(`  ${t.available(current, latest.version)}\n`);
+
+  // `--check`: report only, never install.
+  if (opts.check) {
+    write(`  ${t.checkHint}\n`);
+    return;
+  }
+
+  const plan = flow.buildUpdatePlan(install, info, env);
+  if (!plan) {
+    if (install.kind === 'source') write(`  ${t.sourceCheckout}\n`);
+    else write(`  ${t.unknownInstall(flow.manualCommand(info))}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  write(`  ${t.detected(plan.label)}\n`);
+  write(`  ${t.updating(info.name, current, latest.version)}\n\n`);
+
+  const result = flow.runInstall(plan, env);
+  if (result.ok) {
+    write(`\n  ${t.success(latest.version)}\n  ${t.reRun}\n`);
+    return;
+  }
+  write(`\n  ${t.failInstall(result.reason)}\n  ${t.failHint(flow.manualCommand(info))}\n`);
+  process.exitCode = 1;
+}
+
+module.exports = { run, parseUpdateArgs };
+
+if (require.main === module) {
+  run();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakers-cli-beta",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "description": "Shakers AI usage & skills evaluator: a local-first CLI (`shakers` binary) plus a local MCP server. Commands: ai-usage (scan + classify your AI-tool setup, T0-T7), certify (certify Skills from your code), share (branded LinkedIn card).",
   "type": "commonjs",
   "bin": {

package/src/command-audit.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { scrubSecrets } = require('./agent-synthesis');
+const { loadAuthSession } = require('./auth-session-store');
+const { getCertsBase } = require('./config');
+const { postJsonWithTimeout } = require('./backend-request');
+
+// Fire-and-forget: short timeout, every error swallowed, so a logging failure never blocks or fails a command.
+const AUDIT_TIMEOUT_MS = 1500;
+
+// Capped at 200 chars AFTER scrubbing (mirrors MAX_COMMAND_LEN in session-scan.js) so a secret straddling the cut cannot leak.
+const MAX_ARGS_LEN = 200;
+
+function cliVersion() {
+  try {
+    return require(path.join(__dirname, '..', 'package.json')).version || null;
+  } catch {
+    return null;
+  }
+}
+
+// Scrub THEN cap: scrubSecrets can GROW text, so the cap is measured on the scrubbed string that goes on the wire.
+function redactArgs(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return null;
+  const scrubbed = scrubSecrets(argv.join(' ')).trim().slice(0, MAX_ARGS_LEN);
+  return scrubbed || null;
+}
+
+// Anonymous runs carry only a best-effort machine hint; authenticated runs identify via the Bearer instead.
+function machineHint() {
+  let osUser = null;
+  try {
+    const info = os.userInfo();
+    osUser = info && typeof info.username === 'string' ? info.username : null;
+  } catch {
+    osUser = null;
+  }
+  let hostname = null;
+  try {
+    hostname = os.hostname() || null;
+  } catch {
+    hostname = null;
+  }
+  return { osUser, hostname };
+}
+
+// Builds the record + headers; returns null when there is no endpoint to post to.
+function buildAudit(command, argv, env) {
+  let base;
+  try {
+    base = getCertsBase(env);
+  } catch {
+    base = null;
+  }
+  if (!base) return null;
+
+  const session = loadAuthSession(env);
+  const token =
+    session && (session.accessToken || session.hubAccessToken)
+      ? session.accessToken || session.hubAccessToken
+      : null;
+
+  const body = {
+    command: String(command || 'unknown').slice(0, 100),
+    args: redactArgs(argv),
+    cliVersion: cliVersion(),
+    clientTimestamp: new Date().toISOString(),
+  };
+
+  // Machine hint only when anonymous; identity comes from the token otherwise.
+  if (!token) {
+    const { osUser, hostname } = machineHint();
+    body.osUser = osUser;
+    body.hostname = hostname;
+  }
+
+  const headers = token ? { Authorization: `Bearer ${token}` } : null;
+  const endpoint = `${base.replace(/\/+$/, '')}/cli/command-log`;
+  return { endpoint, body, headers };
+}
+
+// Emits ONE fire-and-forget audit record; never throws or rejects. Returns the `.catch`-guarded promise so tests can await it (production does not).
+function emitCommandAudit({ command, argv = [], env = process.env } = {}) {
+  try {
+    const audit = buildAudit(command, argv, env);
+    if (!audit) return Promise.resolve();
+    return postJsonWithTimeout(
+      audit.endpoint,
+      audit.body,
+      AUDIT_TIMEOUT_MS,
+      'POST',
+      null,
+      audit.headers,
+    ).then(
+      () => {},
+      () => {},
+    );
+  } catch {
+    return Promise.resolve();
+  }
+}
+
+module.exports = { emitCommandAudit, redactArgs, buildAudit };

package/src/i18n.js

@@ -487,6 +487,39 @@ const catalogs = {
         yes: 'Sí, iniciar sesión',
         no: 'No, continuar sin cuenta',
       },
+      // `update` command: actualiza el CLI a la última versión publicada (solo CLI, no MCP).
+      update: {
+        help:
+          'update — actualiza el CLI de Shakers a la última versión publicada.\n\n'
+          + '  Uso: shakers update [--check]\n\n'
+          + '    (sin flag)   Comprueba la última versión y, si hay una más nueva, la instala\n'
+          + '                 por el mismo método con el que se instaló este CLI.\n'
+          + '    --check      Solo informa de tu versión frente a la última publicada; no instala.\n'
+          + '    --json       Salida JSON (paquete, versión actual/última, si hay actualización).\n',
+        checking: 'Comprobando actualizaciones…',
+        current: (v) => `Versión instalada: ${v}`,
+        upToDate: (v) => `Ya tienes la última versión (${v}).`,
+        available: (from, to) => `Hay una actualización disponible: ${from} → ${to}`,
+        checkHint: 'Ejecuta `shakers update` (sin --check) para instalarla.',
+        detected: (label) => `Instalación detectada: ${label}`,
+        updating: (name, from, to) => `Actualizando ${name}: ${from} → ${to}…`,
+        success: (v) => `Actualizado a la versión ${v}.`,
+        reRun: 'Vuelve a ejecutar tu comando para usar la nueva versión.',
+        latestUnknown: (reason) =>
+          `No se pudo determinar la última versión (${reason}). Revisa tu conexión y el acceso al registro.`,
+        failInstall: (reason) => `La actualización falló (${reason}).`,
+        failHint: (cmd) =>
+          `Revisa tu conexión y permisos y vuelve a intentarlo, o actualiza a mano:\n    ${cmd}`,
+        sourceCheckout:
+          'Este CLI se ejecuta desde un checkout de código — actualízalo con `git pull` en ese repositorio.',
+        unknownInstall: (cmd) =>
+          `No se pudo detectar cómo se instaló este CLI. Actualiza a mano:\n    ${cmd}`,
+      },
+      // Aviso pasivo "hay una versión nueva" al arrancar cualquier comando (lectura de caché, sin red en el camino caliente).
+      updateNotifier: {
+        available: (from, to) => `Hay una versión nueva del CLI de Shakers: ${from} → ${to}`,
+        howTo: 'Ejecuta `shakers update` para actualizar.',
+      },
       // `report` command (ADR-016): genera y ABRE el informe HTML completo y compartible de este proyecto (uso de IA + Skills certificadas).
       report: {
         help: 'report — genera y abre el informe HTML completo de este proyecto (uso de IA + Skills certificadas) para compartir con tu equipo.\n'
@@ -982,6 +1015,7 @@ const catalogs = {
       noTerminal: 'No hay una terminal donde preguntarte, así que no he tocado nada. Vuelve a ejecutar el instalador en tu terminal para conectarlo.',
       restart: 'Reinicia las apps que estén abiertas para que carguen Shakers.',
       noneFound: 'No he encontrado ninguna app de IA compatible en esta máquina.',
+      failedAll: 'No he podido conectar Shakers a tus apps de IA. Vuelve a ejecutar el instalador para reintentarlo.',
     },
     rate: {
       help: 'rate — ver o fijar tu tarifa por proyecto.\n\nUso:\n  rate [--lang es|en] [--json]      ver tu tarifa\n  rate --set [--lang es|en]         fijarla (interactivo, con confirmación)\n\nRequiere una sesión activa (shakers login).',
@@ -2122,6 +2156,39 @@ const catalogs = {
         yes: 'Yes, sign in',
         no: 'No, continue without an account',
       },
+      // `update` command: updates the CLI to the latest published version (CLI-only, not MCP).
+      update: {
+        help:
+          'update — update the Shakers CLI to the latest published version.\n\n'
+          + '  Usage: shakers update [--check]\n\n'
+          + '    (no flag)    Check the latest version and, if a newer one exists, install it\n'
+          + '                 the same way this CLI was installed.\n'
+          + '    --check      Only report your version vs the latest published; do not install.\n'
+          + '    --json       JSON output (package, current/latest version, whether an update exists).\n',
+        checking: 'Checking for updates…',
+        current: (v) => `Installed version: ${v}`,
+        upToDate: (v) => `You are on the latest version (${v}).`,
+        available: (from, to) => `An update is available: ${from} → ${to}`,
+        checkHint: 'Run `shakers update` (without --check) to install it.',
+        detected: (label) => `Detected install: ${label}`,
+        updating: (name, from, to) => `Updating ${name}: ${from} → ${to}…`,
+        success: (v) => `Updated to version ${v}.`,
+        reRun: 'Re-run your command to use the new version.',
+        latestUnknown: (reason) =>
+          `Could not determine the latest version (${reason}). Check your network and registry access.`,
+        failInstall: (reason) => `The update failed (${reason}).`,
+        failHint: (cmd) =>
+          `Check your network and permissions and try again, or update manually:\n    ${cmd}`,
+        sourceCheckout:
+          'This CLI is running from a source checkout — update it with `git pull` in that repository.',
+        unknownInstall: (cmd) =>
+          `Could not detect how this CLI was installed. Update manually:\n    ${cmd}`,
+      },
+      // Passive "a newer version exists" notice printed when any command starts (cache read, no network on the hot path).
+      updateNotifier: {
+        available: (from, to) => `A newer Shakers CLI is available: ${from} → ${to}`,
+        howTo: 'Run `shakers update` to upgrade.',
+      },
       // `report` command (ADR-016): builds and OPENS the full, shareable HTML report for this project (AI usage + certified Skills).
       report: {
         help: 'report — build and open the full HTML report for this project (AI usage + certified Skills) to share with your team.\n'
@@ -2610,6 +2677,7 @@ const catalogs = {
       noTerminal: 'There is no terminal to ask you on, so nothing was touched. Run the installer again in your terminal to connect it.',
       restart: 'Restart any of these apps that is open so it loads Shakers.',
       noneFound: 'Found no supported AI app on this machine.',
+      failedAll: 'Could not connect Shakers to your AI apps. Re-run this installer to retry.',
     },
     rate: {
       help: 'rate — view or set your per-project rate.\n\nUsage:\n  rate [--lang es|en] [--json]      view your rate\n  rate --set [--lang es|en]         set it (interactive, with confirmation)\n\nRequires an active session (shakers login).',

package/src/mcp-install.js

@@ -266,7 +266,8 @@ async function runMcpInstall({ out = (s) => process.stdout.write(s), lang = null
     out(`  ${c.clients[r.client]}: ${c.status[r.status]}\n`);
     if (r.removedLegacy) out(`    ${c.removedLegacy}\n`);
   }
-  out(`\n  ${c.restart}\n\n`);
+  const touched = results.some((r) => r.status === 'configured' || r.status === 'unchanged');
+  out(`\n  ${touched ? c.restart : c.failedAll}\n\n`);
   if (results.some((r) => r.status === 'failed' || r.status === 'invalid-json')) process.exitCode = 1;
   return { ok: true, results };
 }

package/src/update-flow.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// `update` is explicit and user-invoked (never a hot path), so these timeouts can be generous.
+const VIEW_TIMEOUT_MS = 20000;
+const INSTALL_TIMEOUT_MS = 180000;
+
+// Documented installer one-liner (README `curl | bash`, `release` branch); overridable for a non-default deployment.
+const DEFAULT_INSTALL_URL =
+  'https://raw.githubusercontent.com/devShakers/ai-usage-evaluator/release/install.sh';
+
+// Name/version/registry come from THIS package.json, so a renamed flavor adapts with no code change here.
+function readPackageInfo() {
+  try {
+    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    const registry =
+      pkg.publishConfig && typeof pkg.publishConfig.registry === 'string'
+        ? pkg.publishConfig.registry
+        : null;
+    return {
+      name: typeof pkg.name === 'string' ? pkg.name : null,
+      version: typeof pkg.version === 'string' ? pkg.version : null,
+      registry,
+    };
+  } catch {
+    return { name: null, version: null, registry: null };
+  }
+}
+
+function realPathOrSelf(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+// Root of the installed package = the parent of this src/ directory.
+function packageRoot() {
+  return realPathOrSelf(path.resolve(__dirname, '..'));
+}
+
+function npmGlobalRoot() {
+  try {
+    const out = execFileSync('npm', ['root', '-g'], {
+      encoding: 'utf8',
+      timeout: VIEW_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out ? realPathOrSelf(out.trim()) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Detects how this CLI was installed (prefix | npm-global | npm-local | source | unknown) so the update lands where the CLI lives.
+function detectInstall(env = process.env) {
+  const root = packageRoot();
+  const nodeModulesSeg = `${path.sep}node_modules${path.sep}`;
+
+  if (!root.includes(nodeModulesSeg)) {
+    const home = realPathOrSelf(
+      env.SHAKERS_CLI_HOME ||
+        env.AI_FOOTPRINT_HOME ||
+        path.join(os.homedir(), '.shakers'),
+    );
+    if (root === home) return { kind: 'prefix', root };
+    if (fs.existsSync(path.join(root, '.git'))) return { kind: 'source', root };
+    return { kind: 'unknown', root };
+  }
+
+  const info = readPackageInfo();
+  const gRoot = npmGlobalRoot();
+  const globalPkgPath =
+    gRoot && info.name
+      ? realPathOrSelf(path.join(gRoot, ...info.name.split('/')))
+      : null;
+  if (globalPkgPath && root === globalPkgPath) {
+    return { kind: 'npm-global', root, global: true, projectDir: null };
+  }
+  // `.../project/node_modules/<@scope/name>` → the project dir owning the local node_modules is `up` segments up.
+  const up = info.name && info.name.includes('/') ? 3 : 2;
+  const projectDir = path.resolve(root, ...Array(up).fill('..'));
+  return { kind: 'npm-local', root, global: false, projectDir };
+}
+
+function classifyError(error) {
+  const code = error && error.code;
+  const stderr =
+    (error && error.stderr && error.stderr.toString()) ||
+    (error && error.message) ||
+    '';
+  if (code === 'ENOENT') return 'npm-not-found';
+  if (code === 'ETIMEDOUT' || /ETIMEDOUT|timed out/i.test(stderr))
+    return 'timeout';
+  if (/EACCES|permission denied|EPERM/i.test(stderr)) return 'permission';
+  if (/ENOTFOUND|ECONNREFUSED|network|ECONNRESET|getaddrinfo/i.test(stderr))
+    return 'network';
+  if (/\b401\b|\b403\b|unauthorized|forbidden|authentication/i.test(stderr))
+    return 'auth';
+  if (/E404|not found/i.test(stderr)) return 'not-found';
+  return 'unknown';
+}
+
+// `npm view <name>@latest version` prints only the version string (last line).
+function fetchLatestVersion({ name, registry } = {}) {
+  if (!name) return { ok: false, reason: 'no-package-name' };
+  const args = ['view', `${name}@latest`, 'version'];
+  if (registry) args.push('--registry', registry);
+  try {
+    const out = execFileSync('npm', args, {
+      encoding: 'utf8',
+      timeout: VIEW_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const version = (out || '')
+      .trim()
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .pop();
+    return version ? { ok: true, version } : { ok: false, reason: 'empty-response' };
+  } catch (error) {
+    return { ok: false, reason: classifyError(error) };
+  }
+}
+
+function parseSemver(v) {
+  const core = String(v).trim().replace(/^v/, '').split('-')[0].split('+')[0];
+  return core.split('.').map((n) => parseInt(n, 10) || 0);
+}
+
+// -1/0/1 on the semver core; prerelease suffixes ignored (fine for an "is a newer release available" check).
+function compareVersions(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+function manualCommand({ name, registry } = {}) {
+  if (!name) return 'npm install -g <package>@latest';
+  const reg = registry ? ` --registry ${registry}` : '';
+  return `npm install -g ${name}@latest${reg}`;
+}
+
+// Resolves the exact command this install model needs to pull `@latest`.
+function buildUpdatePlan(install, info, env = process.env) {
+  const { name, registry } = info;
+  if (!name) return null;
+  if (install.kind === 'npm-global') {
+    const args = ['install', '-g', `${name}@latest`];
+    if (registry) args.push('--registry', registry);
+    return { type: 'npm', cmd: 'npm', args, cwd: undefined, label: 'npm (global)' };
+  }
+  if (install.kind === 'npm-local') {
+    const args = ['install', `${name}@latest`];
+    if (registry) args.push('--registry', registry);
+    return {
+      type: 'npm',
+      cmd: 'npm',
+      args,
+      cwd: install.projectDir || undefined,
+      label: 'npm (local project)',
+    };
+  }
+  if (install.kind === 'prefix') {
+    const url = env.SHAKERS_CLI_INSTALL_URL || DEFAULT_INSTALL_URL;
+    return {
+      type: 'installer',
+      url,
+      label: 'installer (~/.shakers)',
+      command: `curl -fsSL "${url}" | bash`,
+    };
+  }
+  return null;
+}
+
+// Inherited stdio so the user sees npm's progress; the installer path keeps SHAKERS_CLI_HOME/BIN so a re-run lands in the same prefix.
+function runInstall(plan, env = process.env) {
+  if (!plan) return { ok: false, reason: 'no-plan' };
+  try {
+    if (plan.type === 'npm') {
+      execFileSync(plan.cmd, plan.args, {
+        stdio: 'inherit',
+        timeout: INSTALL_TIMEOUT_MS,
+        cwd: plan.cwd,
+        env,
+      });
+      return { ok: true };
+    }
+    if (plan.type === 'installer') {
+      execFileSync('bash', ['-c', plan.command], {
+        stdio: 'inherit',
+        timeout: INSTALL_TIMEOUT_MS,
+        env,
+      });
+      return { ok: true };
+    }
+    return { ok: false, reason: 'no-plan' };
+  } catch (error) {
+    return { ok: false, reason: classifyError(error) };
+  }
+}
+
+module.exports = {
+  readPackageInfo,
+  detectInstall,
+  fetchLatestVersion,
+  compareVersions,
+  buildUpdatePlan,
+  runInstall,
+  manualCommand,
+  DEFAULT_INSTALL_URL,
+};

package/src/update-notifier.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+const { getConfigDir } = require('./config-dir');
+const { getCatalog } = require('./i18n');
+const { compareVersions } = require('./update-flow');
+
+// Non-blocking update notifier: the hot path only reads the cache synchronously; a detached unref'd worker does the network check.
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+function cacheFilePath(env = process.env) {
+  return path.join(getConfigDir(env), 'update-check.json');
+}
+
+// `{ lastCheck, latest }` or null. Never throws — a missing/corrupt cache is "no data".
+function readCache(env = process.env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cacheFilePath(env), 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Written by the background worker (and nowhere else on the hot path). Best-effort, atomic + 0600 like every other home-dir write (temp-in-same-dir + fsync + rename).
+function writeCache(data, env = process.env) {
+  const target = cacheFilePath(env);
+  const dir = path.dirname(target);
+  const tmp = path.join(dir, `.update-check.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd = null;
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const payload = JSON.stringify({ lastCheck: data.lastCheck, latest: data.latest });
+    fd = fs.openSync(tmp, 'wx', 0o600);
+    fs.writeFileSync(fd, payload);
+    try { fs.fsyncSync(fd); } catch { /* e.g. EINVAL on some filesystems */ }
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tmp, target);
+    return true;
+  } catch {
+    if (fd !== null) { try { fs.closeSync(fd); } catch { /* already closed */ } }
+    try { fs.unlinkSync(tmp); } catch { /* never existed */ }
+    return false;
+  }
+}
+
+// `stdoutIsTTY` is injectable for tests; defaults to the real tty bit so piped/redirected/mcp-stdio stdout stays quiet.
+function isSuppressed({
+  argv = [],
+  command = null,
+  env = process.env,
+  stdoutIsTTY = process.stdout.isTTY,
+} = {}) {
+  if (env.SHAKERS_CLI_NO_UPDATE_NOTIFIER === '1') return true;
+  if (env.CI && env.CI !== 'false' && env.CI !== '0') return true;
+  if (!stdoutIsTTY) return true;
+  if (Array.isArray(argv) && argv.includes('--json')) return true;
+  if (command === 'update') return true;
+  return false;
+}
+
+// Synchronous: prints to stderr when the cached latest beats the installed version, never polluting stdout. Returns the notice (or null).
+function maybeNotify({ currentVersion, lang, env = process.env, out = null } = {}) {
+  if (!currentVersion) return null;
+  const cache = readCache(env);
+  if (!cache || typeof cache.latest !== 'string' || !cache.latest) return null;
+  if (compareVersions(currentVersion, cache.latest) >= 0) return null;
+  const t = getCatalog(lang).cli.updateNotifier;
+  const write = out || ((s) => process.stderr.write(s));
+  write(`\n  ${t.available(currentVersion, cache.latest)}\n  ${t.howTo}\n\n`);
+  return t.available(currentVersion, cache.latest);
+}
+
+// Spawns the detached, unref'd worker to refresh the cache, but only when it is missing or older than CHECK_INTERVAL_MS. Failures swallowed.
+function triggerBackgroundCheck({ name, env = process.env } = {}) {
+  if (!name) return false;
+  const cache = readCache(env);
+  const now = Date.now();
+  if (
+    cache &&
+    typeof cache.lastCheck === 'number' &&
+    now - cache.lastCheck < CHECK_INTERVAL_MS
+  ) {
+    return false;
+  }
+  try {
+    const worker = path.join(__dirname, '..', 'bin', 'update-check-worker.js');
+    const child = spawn(process.execPath, [worker, name], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  cacheFilePath,
+  readCache,
+  writeCache,
+  isSuppressed,
+  maybeNotify,
+  triggerBackgroundCheck,
+  CHECK_INTERVAL_MS,
+};