@girardmedia/bootspring 2.0.51 → 2.0.53

package/bin/bootspring.js

@@ -6,6 +6,8 @@
  */
 
 const path = require('path');
+const selfUpdate = require('../core/self-update');
+const { ensureProjectMcpConfig } = require('../core/mcp-config');
 
 const VERSION = require('../package.json').version;
 
@@ -32,6 +34,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 +106,17 @@ async function main() {
     return;
   }
 
+  const updateResult = selfUpdate.ensureLatestVersion(args);
+  if (updateResult.updated) {
+    process.exitCode = updateResult.exitCode;
+    return;
+  }
+
+  const mcpConfigResult = ensureProjectMcpConfig(process.cwd(), { createIfMissing: false });
+  if (mcpConfigResult.status === 'updated') {
+    console.error('[bootspring] Updated .mcp.json to use the managed latest-package launcher.');
+  }
+
   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, ensureProjectMcpConfig } = require('../core/mcp-config');
 const { runQuestionnaire } = require('../generators/questionnaire');
 const claudeTemplate = require('../generators/templates/claude.template');
 const seedTemplate = require('../generators/templates/seed.template');
@@ -542,7 +543,6 @@ ${utils.COLORS.dim}Development scaffolding with intelligence${utils.COLORS.reset
   }
 
   // 4. MCP configuration (local or global)
-  const mcpPath = path.join(projectRoot, '.mcp.json');
   const globalMcpPath = getGlobalMcpPath();
   const isGlobal = isGloballyInstalled();
   const hasGlobalMcp = isGlobalMcpConfigured();
@@ -581,11 +581,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}`);
@@ -595,22 +591,17 @@ ${utils.COLORS.dim}Development scaffolding with intelligence${utils.COLORS.reset
     } catch (error) {
       globalSpinner.fail(`Global MCP config failed: ${error.message}`);
     }
-  } else if (!utils.fileExists(mcpPath)) {
-    // Local .mcp.json
+  } else {
     const mcpSpinner = utils.createSpinner('Creating .mcp.json').start();
-    const mcpConfig = {
-      mcpServers: {
-        bootspring: {
-          command: 'npx',
-          args: ['bootspring', 'mcp'],
-          env: {}
-        }
-      }
-    };
-    if (utils.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2))) {
+    const result = ensureProjectMcpConfig(projectRoot, { createIfMissing: true });
+    if (result.status === 'created') {
       mcpSpinner.succeed('Created .mcp.json (MCP server config)');
+    } else if (result.status === 'updated' || result.status === 'added') {
+      mcpSpinner.succeed('Updated .mcp.json (MCP server config)');
+    } else if (result.status === 'unchanged') {
+      mcpSpinner.succeed('Verified .mcp.json (MCP server config)');
     } else {
-      mcpSpinner.fail('Failed to create .mcp.json');
+      mcpSpinner.fail(`Failed to configure .mcp.json${result.error ? `: ${result.error.message}` : ''}`);
     }
   }
 

package/cli/mcp.js

@@ -3,11 +3,11 @@
  * Manage the hosted MCP proxy configuration.
  */
 
-const path = require('path');
 const config = require('../core/config');
 const utils = require('../core/utils');
 const api = require('../core/api-client');
 const auth = require('../core/auth');
+const { ensureProjectMcpConfig } = require('../core/mcp-config');
 const { redactErrorMessage } = require('../core/redaction');
 
 const C = utils.COLORS;
@@ -19,22 +19,17 @@ async function startServer() {
 
 function generateConfig() {
   const cfg = config.load();
-  const mcpPath = path.join(cfg._projectRoot, '.mcp.json');
-  const mcpConfig = {
-    mcpServers: {
-      bootspring: {
-        command: 'npx',
-        args: ['bootspring', 'mcp'],
-        env: {}
-      }
-    }
-  };
-
   const spinner = utils.createSpinner('Generating .mcp.json').start();
-  if (utils.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2))) {
-    spinner.succeed(`Created ${mcpPath}`);
+  const result = ensureProjectMcpConfig(cfg._projectRoot, { createIfMissing: true });
+
+  if (result.status === 'created') {
+    spinner.succeed(`Created ${result.path}`);
+  } else if (result.status === 'updated' || result.status === 'added') {
+    spinner.succeed(`Updated ${result.path}`);
+  } else if (result.status === 'unchanged') {
+    spinner.succeed(`Already configured ${result.path}`);
   } else {
-    spinner.fail('Failed to create .mcp.json');
+    spinner.fail(`Failed to configure .mcp.json${result.error ? `: ${result.error.message}` : ''}`);
   }
 }
 

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,115 @@
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_NAME = require('../package.json').name || '@girardmedia/bootspring';
+const PROJECT_MCP_FILENAME = '.mcp.json';
+
+function getManagedMcpServerConfig() {
+  return {
+    command: 'npx',
+    args: ['-y', PACKAGE_NAME, 'mcp'],
+    env: {}
+  };
+}
+
+function isManagedMcpServerConfig(serverConfig) {
+  const expected = getManagedMcpServerConfig();
+  return (
+    serverConfig?.command === expected.command &&
+    Array.isArray(serverConfig?.args) &&
+    serverConfig.args.join('\u0000') === expected.args.join('\u0000')
+  );
+}
+
+function normalizeManagedMcpServerConfig(existingServerConfig) {
+  const managedConfig = getManagedMcpServerConfig();
+  const env = existingServerConfig?.env && typeof existingServerConfig.env === 'object' && !Array.isArray(existingServerConfig.env)
+    ? existingServerConfig.env
+    : {};
+
+  return {
+    ...managedConfig,
+    env
+  };
+}
+
+function ensureProjectMcpConfig(projectRoot = process.cwd(), options = {}) {
+  const createIfMissing = options.createIfMissing === true;
+  const mcpPath = path.join(projectRoot, PROJECT_MCP_FILENAME);
+
+  if (!fs.existsSync(mcpPath)) {
+    if (!createIfMissing) {
+      return { status: 'missing', changed: false, path: mcpPath };
+    }
+
+    const nextConfig = {
+      mcpServers: {
+        bootspring: getManagedMcpServerConfig()
+      }
+    };
+
+    try {
+      fs.writeFileSync(mcpPath, JSON.stringify(nextConfig, null, 2));
+      return { status: 'created', changed: true, path: mcpPath, config: nextConfig };
+    } catch (error) {
+      return { status: 'error', changed: false, path: mcpPath, error };
+    }
+  }
+
+  let currentConfig;
+  try {
+    currentConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+  } catch (error) {
+    return { status: 'invalid', changed: false, path: mcpPath, error };
+  }
+
+  if (!currentConfig || typeof currentConfig !== 'object' || Array.isArray(currentConfig)) {
+    return {
+      status: 'invalid',
+      changed: false,
+      path: mcpPath,
+      error: new Error('Project MCP config must be a JSON object')
+    };
+  }
+
+  const currentServers = currentConfig.mcpServers && typeof currentConfig.mcpServers === 'object' && !Array.isArray(currentConfig.mcpServers)
+    ? currentConfig.mcpServers
+    : {};
+  const currentBootspring = currentServers.bootspring;
+
+  if (currentBootspring && isManagedMcpServerConfig(currentBootspring)) {
+    return { status: 'unchanged', changed: false, path: mcpPath, config: currentConfig };
+  }
+
+  if (!currentBootspring && !createIfMissing) {
+    return { status: 'absent', changed: false, path: mcpPath, config: currentConfig };
+  }
+
+  const nextConfig = {
+    ...currentConfig,
+    mcpServers: {
+      ...currentServers,
+      bootspring: normalizeManagedMcpServerConfig(currentBootspring)
+    }
+  };
+
+  try {
+    fs.writeFileSync(mcpPath, JSON.stringify(nextConfig, null, 2));
+    return {
+      status: currentBootspring ? 'updated' : 'added',
+      changed: true,
+      path: mcpPath,
+      config: nextConfig
+    };
+  } catch (error) {
+    return { status: 'error', changed: false, path: mcpPath, error };
+  }
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  PROJECT_MCP_FILENAME,
+  getManagedMcpServerConfig,
+  isManagedMcpServerConfig,
+  ensureProjectMcpConfig
+};

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.53",
   "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",