@girardmedia/bootspring 2.0.51 → 2.0.52

package/bin/bootspring.js

@@ -6,6 +6,7 @@
  */
 
 const path = require('path');
+const selfUpdate = require('../core/self-update');
 
 const VERSION = require('../package.json').version;
 
@@ -32,6 +33,7 @@ const COMMANDS = {
   orchestrator: { handler: '../cli/orchestrator.js', description: 'Run hosted workflow orchestration' },
   quality: { handler: '../cli/quality.js', description: 'Fetch hosted quality gates' },
   billing: { handler: '../cli/billing.js', description: 'View subscription and usage' },
+  update: { handler: '../cli/update.js', description: 'Check for and apply updates' },
   todo: { handler: '../cli/todo.js', description: 'Manage local todo.md tasks' },
   dashboard: { handler: '../cli/dashboard.js', description: 'Open the cloud dashboard' },
   mcp: { handler: '../cli/mcp.js', description: 'Start the hosted MCP proxy' },
@@ -103,6 +105,12 @@ async function main() {
     return;
   }
 
+  const updateResult = selfUpdate.ensureLatestVersion(args);
+  if (updateResult.updated) {
+    process.exitCode = updateResult.exitCode;
+    return;
+  }
+
   try {
     await runCommand(command, args.slice(1));
   } catch (error) {

package/cli/auth.js

@@ -14,7 +14,7 @@ const api = require('../core/api-client');
 const session = require('../core/session');
 const { redactErrorMessage, redactSensitiveString } = require('../core/redaction');
 
-const API_BASE = process.env.BOOTSPRING_API_URL || 'https://www.bootspring.com';
+const API_BASE = process.env.BOOTSPRING_API_URL || api.API_BASE || 'https://api.bootspring.com';
 
 /**
  * Make a direct API request (without v1 prefix)
@@ -90,6 +90,17 @@ const colors = {
   magenta: '\x1b[35m'
 };
 
+function getAuthIdentity() {
+  const user = auth.getUser();
+  const fallbackTier = typeof auth.getTier === 'function' ? String(auth.getTier() || 'free') : 'free';
+
+  return {
+    email: user?.email || (auth.isApiKeyAuth() ? '(api-key auth)' : '(unknown user)'),
+    name: user?.name || '(not set)',
+    tier: String(user?.tier || fallbackTier || 'free')
+  };
+}
+
 /**
  * Prompt for input
  */
@@ -172,6 +183,25 @@ async function activateLinkedProjectSession(apiKey, projectId) {
   return api.loginWithApiKey(apiKey, projectId ? { projectId } : {});
 }
 
+function getRetryAfterMs(error, fallbackMs) {
+  const retryAfterSeconds = Number.parseInt(String(error?.details?.retryAfter || ''), 10);
+  if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0) {
+    return retryAfterSeconds * 1000;
+  }
+
+  return fallbackMs;
+}
+
+async function fetchProjects(authApiKey = null) {
+  if (authApiKey) {
+    const response = await directRequest('GET', '/projects', { apiKey: authApiKey });
+    return response.projects || [];
+  }
+
+  const response = await api.listProjects();
+  return response.projects || [];
+}
+
 /**
  * Device authorization flow - browser-based login
  */
@@ -214,6 +244,7 @@ async function loginWithBrowser(noBrowser = false) {
   // Spinner animation
   const spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
   let spinnerIndex = 0;
+  let pollBackoffNotified = false;
 
   const pollForToken = () => {
     return new Promise((resolve, reject) => {
@@ -245,6 +276,14 @@ async function loginWithBrowser(noBrowser = false) {
               error.status === 400 && error.details?.error === 'authorization_pending') {
             // Still waiting, continue polling
             setTimeout(poll, pollInterval);
+          } else if (error.status === 429 || error.code === 'too_many_attempts') {
+            const backoffMs = getRetryAfterMs(error, pollInterval * 4);
+            if (!pollBackoffNotified) {
+              process.stdout.write('\r' + ' '.repeat(80) + '\r');
+              console.log(`${colors.yellow}Rate limited while waiting for browser authorization. Keeping this session alive and retrying automatically...${colors.reset}`);
+              pollBackoffNotified = true;
+            }
+            setTimeout(poll, backoffMs);
           } else if (error.message?.includes('access_denied') || error.code === 'access_denied') {
             process.stdout.write('\r' + ' '.repeat(50) + '\r');
             reject(new Error('Authorization was denied'));
@@ -419,26 +458,34 @@ async function login(args = []) {
 
   // Check if already logged in
   if (auth.isAuthenticated()) {
-    const user = auth.getUser();
+    const identity = getAuthIdentity();
 
     // Check if this directory already has a local config
     const existingConfig = session.findLocalConfig();
     if (existingConfig && existingConfig._dir === process.cwd()) {
       // Directory already linked to a project
-      console.log(`${colors.green}Already authenticated as ${user.email}${colors.reset}`);
+      console.log(`${colors.green}Already authenticated as ${identity.email}${colors.reset}`);
       console.log(`${colors.dim}Project: ${colors.reset}${colors.green}${existingConfig.projectName}${colors.reset} ${colors.dim}(from .bootspring.json)${colors.reset}`);
       console.log(`\n${colors.dim}To switch projects, run: bootspring switch <project>${colors.reset}`);
       console.log(`${colors.dim}To use a different account, run: bootspring auth logout${colors.reset}`);
       return;
     }
 
-    // Directory not linked - go through browser flow to select/create project
-    console.log(`${colors.green}Authenticated as ${user.email}${colors.reset}`);
+    // Directory not linked - link locally first to avoid unnecessary reauthentication.
+    console.log(`${colors.green}Authenticated as ${identity.email}${colors.reset}`);
     console.log(`${colors.dim}This directory is not linked to a project yet.${colors.reset}\n`);
-    console.log(`${colors.dim}Opening browser to select or create a project...${colors.reset}\n`);
+    console.log(`${colors.dim}Fetching your available projects so this folder can be linked without a new browser login...${colors.reset}\n`);
 
-    // Use device flow to select project via dashboard (allows creating new projects)
-    await loginWithBrowser(noBrowser);
+    const linked = await requireProjectSelection({
+      force: true,
+      lockToDirectory: true,
+      authApiKey: auth.isApiKeyAuth() ? auth.getApiKey() : null
+    });
+
+    if (!linked) {
+      console.log(`\n${colors.dim}Falling back to browser project selection...${colors.reset}\n`);
+      await loginWithBrowser(noBrowser);
+    }
     return;
   }
 
@@ -461,8 +508,8 @@ async function register() {
 
   // Check if already logged in
   if (auth.isAuthenticated()) {
-    const user = auth.getUser();
-    console.log(`${colors.yellow}You are already logged in as ${user.email}${colors.reset}`);
+    const identity = getAuthIdentity();
+    console.log(`${colors.yellow}You are already logged in as ${identity.email}${colors.reset}`);
     console.log('Run \'bootspring auth logout\' first to create a new account.');
     return;
   }
@@ -549,12 +596,12 @@ async function whoami() {
     return;
   }
 
-  const user = auth.getUser();
+  const identity = getAuthIdentity();
   const isApiKey = auth.isApiKeyAuth();
   console.log(`\n${colors.bold}Current User${colors.reset}\n`);
-  console.log(`  ${colors.cyan}Email:${colors.reset}  ${user.email}`);
-  console.log(`  ${colors.cyan}Name:${colors.reset}   ${user.name || '(not set)'}`);
-  console.log(`  ${colors.cyan}Tier:${colors.reset}   ${user.tier}`);
+  console.log(`  ${colors.cyan}Email:${colors.reset}  ${identity.email}`);
+  console.log(`  ${colors.cyan}Name:${colors.reset}   ${identity.name}`);
+  console.log(`  ${colors.cyan}Tier:${colors.reset}   ${identity.tier}`);
   console.log(`  ${colors.cyan}Auth:${colors.reset}   ${isApiKey ? colors.magenta + 'API Key' : colors.green + 'Session'}${colors.reset}`);
 
   // Try to get fresh data from API
@@ -591,9 +638,9 @@ async function status() {
   let keyProject = null;
 
   if (isAuth) {
-    const user = auth.getUser();
-    console.log(`  ${colors.cyan}User:${colors.reset}          ${user.email || user.tier}`);
-    console.log(`  ${colors.cyan}Tier:${colors.reset}          ${user.tier}`);
+    const identity = getAuthIdentity();
+    console.log(`  ${colors.cyan}User:${colors.reset}          ${identity.email || identity.tier}`);
+    console.log(`  ${colors.cyan}Tier:${colors.reset}          ${identity.tier}`);
     console.log(`  ${colors.cyan}Auth Method:${colors.reset}   ${isApiKey ? colors.magenta + 'API Key' : colors.green + 'Session'}${colors.reset}`);
 
     // If using API key, validate it and get the associated project
@@ -689,18 +736,18 @@ async function requireProjectSelection(options = {}) {
   if (!force) {
     // Check if project context already exists
     if (session.getEffectiveProject && session.getEffectiveProject()) {
-      return;
+      return true;
     }
 
     // Check legacy hasProjectContext
     if (session.hasProjectContext && session.hasProjectContext()) {
-      return;
+      return true;
     }
 
     // Check local .bootspring.json
     const localConfig = session.findLocalConfig && session.findLocalConfig();
     if (localConfig?.projectId) {
-      return;
+      return true;
     }
   }
 
@@ -712,53 +759,54 @@ async function requireProjectSelection(options = {}) {
 
   let projects = [];
   try {
-    const response = await directRequest('GET', '/projects', authApiKey ? { apiKey: authApiKey } : {});
-    projects = response.projects || [];
+    projects = await fetchProjects(authApiKey);
   } catch (error) {
     console.log(`${colors.red}Failed to fetch projects: ${redactErrorMessage(error)}${colors.reset}`);
     console.log(`${colors.dim}Run 'bootspring switch <project>' manually to set project${colors.reset}`);
-    return;
+    return false;
   }
 
   if (projects.length === 0) {
     console.log(`${colors.yellow}No projects found${colors.reset}`);
     console.log(`${colors.dim}Create a project at https://bootspring.com/dashboard/projects${colors.reset}`);
-    return;
+    return false;
   }
+  let selectedProject = null;
 
-  // Show numbered list
-  console.log(`\n${colors.bold}Your Projects${colors.reset}\n`);
-  for (let i = 0; i < projects.length; i++) {
-    const project = projects[i];
-    console.log(`  ${colors.cyan}[${i + 1}]${colors.reset} ${colors.bold}${project.name}${colors.reset} ${colors.dim}(${project.slug})${colors.reset}`);
-  }
+  if (projects.length === 1) {
+    selectedProject = projects[0];
+    console.log(`\n${colors.dim}Only one project is available. Linking automatically...${colors.reset}`);
+  } else {
+    console.log(`\n${colors.bold}Your Projects${colors.reset}\n`);
+    for (let i = 0; i < projects.length; i++) {
+      const project = projects[i];
+      console.log(`  ${colors.cyan}[${i + 1}]${colors.reset} ${colors.bold}${project.name}${colors.reset} ${colors.dim}(${project.slug})${colors.reset}`);
+    }
 
-  // Prompt for selection
-  const selection = await prompt(`\n${colors.cyan}Enter number or name:${colors.reset} `);
+    const selection = await prompt(`\n${colors.cyan}Enter number or name:${colors.reset} `);
 
-  if (!selection) {
-    console.log(`${colors.yellow}No project selected${colors.reset}`);
-    console.log(`${colors.dim}Run 'bootspring switch <project>' to set project later${colors.reset}`);
-    return;
-  }
+    if (!selection) {
+      console.log(`${colors.yellow}No project selected${colors.reset}`);
+      console.log(`${colors.dim}Run 'bootspring switch <project>' to set project later${colors.reset}`);
+      return false;
+    }
 
-  // Find project by number or name
-  let selectedProject = null;
-  const num = parseInt(selection, 10);
+    const num = parseInt(selection, 10);
 
-  if (!isNaN(num) && num >= 1 && num <= projects.length) {
-    selectedProject = projects[num - 1];
-  } else {
-    selectedProject = projects.find(
-      p => p.name.toLowerCase() === selection.toLowerCase() ||
-           p.slug === selection.toLowerCase()
-    );
+    if (!isNaN(num) && num >= 1 && num <= projects.length) {
+      selectedProject = projects[num - 1];
+    } else {
+      selectedProject = projects.find(
+        p => p.name.toLowerCase() === selection.toLowerCase() ||
+             p.slug === selection.toLowerCase()
+      );
+    }
   }
 
   if (!selectedProject) {
-    console.log(`${colors.red}Project not found: ${selection}${colors.reset}`);
+    console.log(`${colors.red}Project not found${colors.reset}`);
     console.log(`${colors.dim}Run 'bootspring switch <project>' to try again${colors.reset}`);
-    return;
+    return false;
   }
 
   // Set project in session
@@ -780,6 +828,8 @@ async function requireProjectSelection(options = {}) {
       console.log(`${colors.yellow}Warning: Could not create local config: ${redactErrorMessage(error)}${colors.reset}`);
     }
   }
+
+  return true;
 }
 
 // Alias for backwards compatibility (exported for potential external use)

package/cli/init.js

@@ -15,6 +15,7 @@ const { execSync } = require('child_process');
 const config = require('../core/config');
 const utils = require('../core/utils');
 const contextLoader = require('../core/context-loader');
+const { getManagedMcpServerConfig } = require('../core/mcp-config');
 const { runQuestionnaire } = require('../generators/questionnaire');
 const claudeTemplate = require('../generators/templates/claude.template');
 const seedTemplate = require('../generators/templates/seed.template');
@@ -581,11 +582,7 @@ ${utils.COLORS.dim}Development scaffolding with intelligence${utils.COLORS.reset
       if (!settings.mcpServers) {
         settings.mcpServers = {};
       }
-      settings.mcpServers.bootspring = {
-        command: 'bootspring',
-        args: ['mcp'],
-        env: {}
-      };
+      settings.mcpServers.bootspring = getManagedMcpServerConfig();
 
       if (utils.writeFile(globalMcpPath, JSON.stringify(settings, null, 2))) {
         globalSpinner.succeed(`Configured global MCP at ${globalMcpPath}`);
@@ -600,11 +597,7 @@ ${utils.COLORS.dim}Development scaffolding with intelligence${utils.COLORS.reset
     const mcpSpinner = utils.createSpinner('Creating .mcp.json').start();
     const mcpConfig = {
       mcpServers: {
-        bootspring: {
-          command: 'npx',
-          args: ['bootspring', 'mcp'],
-          env: {}
-        }
+        bootspring: getManagedMcpServerConfig()
       }
     };
     if (utils.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2))) {

package/cli/mcp.js

@@ -8,6 +8,7 @@ const config = require('../core/config');
 const utils = require('../core/utils');
 const api = require('../core/api-client');
 const auth = require('../core/auth');
+const { getManagedMcpServerConfig } = require('../core/mcp-config');
 const { redactErrorMessage } = require('../core/redaction');
 
 const C = utils.COLORS;
@@ -22,11 +23,7 @@ function generateConfig() {
   const mcpPath = path.join(cfg._projectRoot, '.mcp.json');
   const mcpConfig = {
     mcpServers: {
-      bootspring: {
-        command: 'npx',
-        args: ['bootspring', 'mcp'],
-        env: {}
-      }
+      bootspring: getManagedMcpServerConfig()
     }
   };
 

package/cli/update.js

@@ -0,0 +1,132 @@
+/**
+ * Bootspring Update Command
+ * Check for updates and manage versions.
+ */
+
+const utils = require('../core/utils');
+const selfUpdate = require('../core/self-update');
+
+function printCheckResult(result) {
+  if (!result.latest) {
+    console.log(`${utils.COLORS.dim}Current version: ${result.current}${utils.COLORS.reset}`);
+    console.log(`${utils.COLORS.dim}Could not fetch the latest npm version.${utils.COLORS.reset}`);
+    return;
+  }
+
+  if (result.updateAvailable) {
+    console.log(`${utils.COLORS.green}Update available:${utils.COLORS.reset} ${result.current} -> ${result.latest}`);
+    console.log(`${utils.COLORS.dim}Run: bootspring update apply${utils.COLORS.reset}`);
+    return;
+  }
+
+  if (selfUpdate.compareVersions(result.current, result.latest) === 0) {
+    console.log(`${utils.COLORS.green}Already on the latest version:${utils.COLORS.reset} ${result.current}`);
+    return;
+  }
+
+  console.log(`${utils.COLORS.dim}Running a development version (${result.current}). npm latest is ${result.latest}.${utils.COLORS.reset}`);
+}
+
+async function checkForUpdates() {
+  console.log(`\n${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Update Check${utils.COLORS.reset}\n`);
+  const spinner = utils.createSpinner('Checking npm for the latest release').start();
+  const result = selfUpdate.checkForUpdates();
+
+  if (!result.latest) {
+    spinner.warn('Could not fetch the latest version');
+  } else if (result.updateAvailable) {
+    spinner.succeed(`Update available: ${result.current} -> ${result.latest}`);
+  } else {
+    spinner.succeed(`Current version: ${result.current}`);
+  }
+
+  printCheckResult(result);
+}
+
+async function applyUpdate() {
+  console.log(`\n${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Update${utils.COLORS.reset}\n`);
+
+  const result = selfUpdate.checkForUpdates();
+  if (!result.updateAvailable || !result.latest) {
+    printCheckResult(result);
+    return;
+  }
+
+  const context = selfUpdate.getInstallContext();
+  const target = context.mode === 'local'
+    ? context.projectRoot || process.cwd()
+    : 'global install';
+  const spinner = utils.createSpinner(`Updating ${target}`).start();
+
+  try {
+    selfUpdate.applyUpdate(context);
+    spinner.succeed(`Updated to ${result.latest}`);
+    console.log(`${utils.COLORS.dim}Restart any running MCP clients so they pick up the new binary.${utils.COLORS.reset}`);
+  } catch (error) {
+    spinner.fail('Update failed');
+    console.log(`${utils.COLORS.red}${error.message}${utils.COLORS.reset}`);
+  }
+}
+
+function showVersion() {
+  const result = selfUpdate.checkForUpdates();
+  const context = selfUpdate.getInstallContext();
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring${utils.COLORS.reset}
+
+${utils.COLORS.bold}Version${utils.COLORS.reset}
+  Installed: ${utils.COLORS.cyan}${selfUpdate.CURRENT_VERSION}${utils.COLORS.reset}
+  Latest:    ${utils.COLORS.cyan}${result.latest || 'unknown'}${utils.COLORS.reset}
+  Install:   ${context.mode}
+`);
+}
+
+function showHelp() {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Update${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring update check
+  bootspring update apply
+  bootspring update version
+`);
+}
+
+async function run(args) {
+  const parsedArgs = utils.parseArgs(args);
+  const subcommand = parsedArgs._[0] || 'check';
+
+  switch (subcommand) {
+    case 'check':
+      await checkForUpdates();
+      break;
+    case 'apply':
+    case 'upgrade':
+    case 'install':
+      await applyUpdate();
+      break;
+    case 'version':
+    case '-v':
+    case '--version':
+      showVersion();
+      break;
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+    default:
+      utils.print.error(`Unknown subcommand: ${subcommand}`);
+      showHelp();
+  }
+}
+
+module.exports = {
+  run,
+  checkForUpdates,
+  applyUpdate,
+  getCurrentVersion: () => selfUpdate.CURRENT_VERSION,
+  getLatestVersion: selfUpdate.getLatestVersion,
+  compareVersions: selfUpdate.compareVersions
+};

package/core/mcp-config.js

@@ -0,0 +1,14 @@
+const PACKAGE_NAME = require('../package.json').name || '@girardmedia/bootspring';
+
+function getManagedMcpServerConfig() {
+  return {
+    command: 'npx',
+    args: ['-y', PACKAGE_NAME, 'mcp'],
+    env: {}
+  };
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  getManagedMcpServerConfig
+};

package/core/self-update.js

@@ -0,0 +1,259 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+const { PACKAGE_NAME } = require('./mcp-config');
+
+const pkg = require('../package.json');
+const CURRENT_VERSION = pkg.version || '0.0.0';
+const DEFAULT_INTERVAL_MS = Number.parseInt(
+  process.env.BOOTSPRING_AUTO_UPDATE_INTERVAL_MS || `${6 * 60 * 60 * 1000}`,
+  10
+);
+const STATE_PATH = path.join(os.homedir(), '.bootspring', 'update-state.json');
+
+function getNpmCommand() {
+  if (process.env.BOOTSPRING_NPM_COMMAND) {
+    return process.env.BOOTSPRING_NPM_COMMAND;
+  }
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function compareVersions(a, b) {
+  const aParts = String(a || '0.0.0').split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const bParts = String(b || '0.0.0').split('.').map((part) => Number.parseInt(part, 10) || 0);
+
+  for (let index = 0; index < 3; index += 1) {
+    if ((aParts[index] || 0) < (bParts[index] || 0)) {
+      return -1;
+    }
+    if ((aParts[index] || 0) > (bParts[index] || 0)) {
+      return 1;
+    }
+  }
+
+  return 0;
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeState(nextState) {
+  try {
+    fs.mkdirSync(path.dirname(STATE_PATH), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(STATE_PATH, JSON.stringify(nextState, null, 2));
+  } catch {
+    // Best-effort cache only.
+  }
+}
+
+function getInstallContext() {
+  const packageRoot = path.resolve(__dirname, '..');
+  const scriptPath = path.resolve(process.argv[1] || path.join(packageRoot, 'bin', 'bootspring.js'));
+  const nodeModulesSegment = `${path.sep}node_modules${path.sep}`;
+  const forcedMode = process.env.BOOTSPRING_AUTO_UPDATE_INSTALL_MODE;
+
+  if (forcedMode === 'global' || forcedMode === 'local') {
+    const projectRoot = forcedMode === 'local'
+      ? process.env.BOOTSPRING_AUTO_UPDATE_PROJECT_ROOT || process.cwd()
+      : null;
+    return { mode: forcedMode, packageRoot, projectRoot, scriptPath };
+  }
+
+  if (packageRoot.includes(`${path.sep}_npx${path.sep}`) || scriptPath.includes(`${path.sep}_npx${path.sep}`)) {
+    return { mode: 'ephemeral', packageRoot, projectRoot: null, scriptPath };
+  }
+
+  if (!packageRoot.includes(nodeModulesSegment)) {
+    return { mode: 'development', packageRoot, projectRoot: null, scriptPath };
+  }
+
+  if (
+    scriptPath.includes(`${nodeModulesSegment}.bin${path.sep}`) ||
+    scriptPath.includes(`${nodeModulesSegment}@girardmedia${path.sep}bootspring${path.sep}bin${path.sep}`)
+  ) {
+    const [projectRoot] = packageRoot.split(nodeModulesSegment);
+    return { mode: 'local', packageRoot, projectRoot: projectRoot || process.cwd(), scriptPath };
+  }
+
+  return { mode: 'global', packageRoot, projectRoot: null, scriptPath };
+}
+
+function shouldSkipAutoUpdate(args = []) {
+  if (
+    process.env.BOOTSPRING_SKIP_AUTO_UPDATE === 'true' ||
+    process.env.BOOTSPRING_AUTO_UPDATE_APPLIED === 'true' ||
+    process.env.NODE_ENV === 'test' ||
+    process.env.CI
+  ) {
+    return true;
+  }
+
+  const tokens = Array.isArray(args) ? args.filter(Boolean) : [];
+  if (tokens.length === 0) {
+    return true;
+  }
+
+  if (
+    tokens[0] === 'help' ||
+    tokens[0] === 'update' ||
+    tokens[0] === '--version' ||
+    tokens[0] === '-v' ||
+    tokens.includes('--help') ||
+    tokens.includes('-h')
+  ) {
+    return true;
+  }
+
+  const context = getInstallContext();
+  if (context.mode === 'ephemeral') {
+    return true;
+  }
+
+  if (context.mode === 'development' && process.env.BOOTSPRING_ALLOW_DEV_AUTO_UPDATE !== 'true') {
+    return true;
+  }
+
+  return false;
+}
+
+function getLatestVersion() {
+  try {
+    const output = execFileSync(
+      getNpmCommand(),
+      ['view', PACKAGE_NAME, 'version', '--json'],
+      {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 10000,
+        env: {
+          ...process.env,
+          npm_config_update_notifier: 'false'
+        }
+      }
+    ).trim();
+
+    if (!output) {
+      return null;
+    }
+
+    return JSON.parse(output);
+  } catch {
+    return null;
+  }
+}
+
+function applyUpdate(context) {
+  const args = context.mode === 'local'
+    ? ['install', `${PACKAGE_NAME}@latest`]
+    : ['install', '-g', `${PACKAGE_NAME}@latest`];
+
+  execFileSync(getNpmCommand(), args, {
+    cwd: context.projectRoot || process.cwd(),
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 120000,
+    env: {
+      ...process.env,
+      npm_config_update_notifier: 'false'
+    }
+  });
+}
+
+function relaunch(args = []) {
+  const result = spawnSync(process.execPath, [process.argv[1], ...args], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      BOOTSPRING_AUTO_UPDATE_APPLIED: 'true'
+    }
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+function checkForUpdates(options = {}) {
+  const latestVersion = getLatestVersion();
+  const currentVersion = options.currentVersion || CURRENT_VERSION;
+  return {
+    current: currentVersion,
+    latest: latestVersion,
+    updateAvailable: Boolean(latestVersion) && compareVersions(currentVersion, latestVersion) < 0
+  };
+}
+
+function ensureLatestVersion(args = []) {
+  if (shouldSkipAutoUpdate(args)) {
+    return { updated: false, skipped: true };
+  }
+
+  const context = getInstallContext();
+  const state = readState();
+  const lastCheckedAt = Date.parse(state.lastCheckedAt || '');
+  const now = Date.now();
+  const cacheFresh = Number.isFinite(lastCheckedAt) && now - lastCheckedAt < DEFAULT_INTERVAL_MS;
+
+  let latestVersion = state.latestVersion || null;
+  if (!cacheFresh || state.currentVersion !== CURRENT_VERSION) {
+    latestVersion = getLatestVersion();
+    writeState({
+      ...state,
+      currentVersion: CURRENT_VERSION,
+      latestVersion,
+      lastCheckedAt: new Date(now).toISOString()
+    });
+  }
+
+  if (!latestVersion || compareVersions(CURRENT_VERSION, latestVersion) >= 0) {
+    return { updated: false, skipped: false, current: CURRENT_VERSION, latest: latestVersion };
+  }
+
+  const installTarget = context.mode === 'local' ? context.projectRoot || process.cwd() : 'global install';
+  console.error(`[bootspring] Updating ${CURRENT_VERSION} -> ${latestVersion} before continuing (${installTarget}).`);
+
+  try {
+    applyUpdate(context);
+    writeState({
+      ...readState(),
+      currentVersion: latestVersion,
+      latestVersion,
+      lastCheckedAt: new Date(now).toISOString(),
+      lastUpdatedAt: new Date().toISOString()
+    });
+    return {
+      updated: true,
+      current: CURRENT_VERSION,
+      latest: latestVersion,
+      exitCode: relaunch(args)
+    };
+  } catch (error) {
+    console.error(`[bootspring] Auto-update failed: ${error.message}`);
+    return {
+      updated: false,
+      skipped: false,
+      current: CURRENT_VERSION,
+      latest: latestVersion,
+      error
+    };
+  }
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  CURRENT_VERSION,
+  compareVersions,
+  getInstallContext,
+  getLatestVersion,
+  checkForUpdates,
+  ensureLatestVersion,
+  applyUpdate
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@girardmedia/bootspring",
-  "version": "2.0.51",
+  "version": "2.0.52",
   "description": "Thin client for Bootspring cloud MCP, hosted agents, and paywalled workflow intelligence",
   "keywords": [
     "ai",
@@ -61,6 +61,7 @@
     "cli/skill.js",
     "cli/switch.js",
     "cli/todo.js",
+    "cli/update.js",
     "core/api-client.d.ts",
     "core/api-client.js",
     "core/auth.d.ts",
@@ -76,12 +77,14 @@
     "core/entitlements.js",
     "core/index.d.ts",
     "core/index.js",
+    "core/mcp-config.js",
     "core/policies.d.ts",
     "core/policies.js",
     "core/policy-matrix.js",
     "core/project-activity.js",
     "core/redaction.d.ts",
     "core/redaction.js",
+    "core/self-update.js",
     "core/session.js",
     "core/task-extractor.js",
     "core/telemetry.d.ts",