@girardmedia/bootspring 2.5.7 → 2.5.9

package/dist/cli-launcher.js

@@ -26,18 +26,19 @@ var C = {
   red: "\x1B[31m"
 };
 var HELP_GROUPS = {
-  "Core": ["auth", "init", "project", "switch", "health", "mcp", "dashboard", "context"],
-  "Build & Deploy": ["build", "deploy", "loop", "quality", "security", "doctor", "update"],
-  "Planning": ["plan", "prd", "seed", "manager"],
-  "Pipeline & Workflows": ["pipeline", "workflow", "harness"],
-  "Agents & Skills": ["agent", "skill", "todo", "billing", "plugin"],
-  "Analysis": ["analyze", "audit", "monitor", "metrics", "validate", "visualize"],
+  "Core": ["auth", "init", "project", "switch", "health", "doctor", "mcp", "dashboard", "context", "setup", "go"],
+  "Build & Deploy": ["build", "deploy", "loop", "quality", "security", "update", "undo", "scaffold", "guardian"],
+  "Planning": ["plan", "prd", "seed", "manager", "spec"],
+  "Pipeline & Workflows": ["pipeline", "workflow", "harness", "flow", "autonomous", "pair"],
+  "Agents & Skills": ["agent", "skill", "todo", "billing", "plugin", "studio", "prompt"],
+  "Analysis & Quality": ["analyze", "audit", "monitor", "metrics", "validate", "visualize", "graph", "diff", "review-code", "arch", "predict", "profile", "runtime", "testgen"],
+  "AI & Models": ["model", "local", "learn", "memory", "suggest", "orchestrator"],
+  "Intelligence": ["observe", "autopilot", "watch", "timemachine", "team", "network", "report"],
   "Pro Tools": ["geo", "marketing", "sales", "jobs"],
   "Docs & Content": ["generate", "content", "docs"],
-  "Intelligence": ["learn", "memory", "suggest", "orchestrator", "watch", "observe", "autopilot"],
   "Business": ["business", "fundraise", "legal", "org"],
-  "Infrastructure": ["workspace", "cloud-sync", "github", "onboard", "checkpoint", "setup"],
-  "Tools": ["log", "mvp", "task", "telemetry"]
+  "Infrastructure": ["workspace", "cloud-sync", "github", "onboard", "checkpoint", "sync", "issue"],
+  "Tools": ["log", "mvp", "task", "telemetry", "visual"]
 };
 function showHelp() {
   console.log(`${C.cyan}${C.bold}\u26A1 Bootspring${C.reset} ${C.dim}v${VERSION}${C.reset}`);
@@ -67,14 +68,15 @@ function showHelp() {
   console.log(`${C.cyan}${C.bold}MORE${C.reset}`);
   console.log(`  ${C.green}bootspring doctor${C.reset}                ${C.dim}Diagnose project issues${C.reset}`);
   console.log(`  ${C.green}bootspring observe${C.reset}               ${C.dim}Session intelligence and analytics${C.reset}`);
-  console.log(`  ${C.green}bootspring commands${C.reset}              ${C.dim}Show all ${Object.values(HELP_GROUPS).flat().length}+ commands${C.reset}`);
+  console.log(`  ${C.green}bootspring commands${C.reset}              ${C.dim}Show all ${Object.values(HELP_GROUPS).flat().length} commands${C.reset}`);
   console.log(`
 ${C.dim}Run "bootspring <command> --help" for details${C.reset}`);
   console.log(`${C.dim}Docs: https://bootspring.com/docs${C.reset}
 `);
 }
 function showFullCommands() {
-  console.log(`${C.cyan}${C.bold}\u26A1 Bootspring${C.reset} ${C.dim}v${VERSION} \u2014 All Commands${C.reset}
+  const total = Object.values(HELP_GROUPS).flat().length;
+  console.log(`${C.cyan}${C.bold}\u26A1 Bootspring${C.reset} ${C.dim}v${VERSION} \u2014 ${total} commands${C.reset}
 `);
   for (const [group, cmds] of Object.entries(HELP_GROUPS)) {
     console.log(`${C.bold}${group}:${C.reset}  ${cmds.map((command) => `${C.green}${command}${C.reset}`).join(", ")}`);

package/dist/core.js

@@ -21625,7 +21625,7 @@ var require_package = __commonJS({
   "../../../package.json"(exports2, module2) {
     module2.exports = {
       name: "bootspring-workspace",
-      version: "2.5.7",
+      version: "2.5.9",
       private: true,
       description: "Workspace tooling for the Bootspring monorepo",
       keywords: [

package/dist/mcp-server.js

@@ -52219,7 +52219,7 @@ var require_package = __commonJS({
   "../../../package.json"(exports2, module2) {
     module2.exports = {
       name: "bootspring-workspace",
-      version: "2.5.7",
+      version: "2.5.9",
       private: true,
       description: "Workspace tooling for the Bootspring monorepo",
       keywords: [
@@ -52481,10 +52481,59 @@ function createAuthError(message) {
     isError: true
   };
 }
+function diagnoseApiSurface() {
+  const required = ["callMcpTool", "listMcpTools", "listMcpResources", "getMcpResource"];
+  const missing = required.filter((fn) => typeof api2?.[fn] !== "function");
+  if (missing.length === 0) return null;
+  return [
+    `Bootspring MCP server v${VERSION} is missing required API methods: ${missing.join(", ")}.`,
+    `This usually means the installed @girardmedia/bootspring package is out of date.`,
+    `Fix:`,
+    `  1. Quit Claude Code completely`,
+    `  2. npm i -g @girardmedia/bootspring@latest`,
+    `  3. Restart Claude Code so the MCP server reloads`
+  ].join("\n");
+}
+function formatProxyError(error) {
+  if (error?.status === 401) {
+    return "Authentication expired. Run `bootspring auth login` to re-authenticate.";
+  }
+  if (error?.status === 403) {
+    return "This MCP capability requires a paid Bootspring plan.";
+  }
+  if (error?.status === 404) {
+    const serverMessage = typeof error?.message === "string" ? error.message : "";
+    if (serverMessage && /mcp tool/i.test(serverMessage)) {
+      return `${serverMessage}. This typically means the hosted API doesn't yet route that tool, or the CLI catalog is ahead of the server catalog.`;
+    }
+    return "This MCP tool is not available on the connected Bootspring API. Check that you are pointed at a current API server.";
+  }
+  if (error?.code === "ECONNREFUSED" || error?.code === "ENOTFOUND" || error?.code === "ETIMEDOUT" || error?.code === "EHOSTUNREACH") {
+    return `Cannot reach Bootspring API (${error.code}). Check your internet connection or BOOTSPRING_API_URL.`;
+  }
+  return error?.message || "Unknown error from Bootspring API.";
+}
+var LOCAL_TOOLS = /* @__PURE__ */ new Set(["bootspring_build", "bootspring_seed", "bootspring_todo"]);
+function formatLocalToolGuidance(name, args) {
+  const action = args && typeof args.action === "string" ? args.action : "";
+  const base = name.replace(/^bootspring_/, "bootspring ");
+  const cmd = action ? `${base} ${action}` : base;
+  return [
+    `\`${name}\` is a local-state tool \u2014 it reads and writes files in your project (.bootspring/state, planning/, etc.) and therefore cannot be executed from the hosted MCP API.`,
+    ``,
+    `Run this in your project terminal:`,
+    `  ${cmd}`,
+    ``,
+    `Everything else in this conversation will still work \u2014 only local-state tools need to run from your shell.`
+  ].join("\n");
+}
 async function resolveTools() {
   if (!auth2.isAuthenticated()) {
     return FALLBACK_TOOLS;
   }
+  if (typeof api2?.listMcpTools !== "function") {
+    return FALLBACK_TOOLS;
+  }
   try {
     const response = await api2.listMcpTools();
     const apiTools = Array.isArray(response) ? response : response.tools || [];
@@ -52499,6 +52548,9 @@ async function resolveResources() {
   if (!auth2.isAuthenticated()) {
     return FALLBACK_RESOURCES;
   }
+  if (typeof api2?.listMcpResources !== "function") {
+    return FALLBACK_RESOURCES;
+  }
   try {
     const response = await api2.listMcpResources();
     return Array.isArray(response) ? response : response.resources || FALLBACK_RESOURCES;
@@ -52507,18 +52559,34 @@ async function resolveResources() {
   }
 }
 async function proxyToolCall(name, args) {
+  if (LOCAL_TOOLS.has(name)) {
+    return {
+      content: [{ type: "text", text: formatLocalToolGuidance(name, args) }]
+    };
+  }
   if (!auth2.isAuthenticated()) {
     return createAuthError("Authentication required. Run `bootspring auth login` first.");
   }
+  const surfaceError = diagnoseApiSurface();
+  if (surfaceError) {
+    return {
+      content: [{ type: "text", text: surfaceError }],
+      isError: true
+    };
+  }
   try {
     const response = await api2.callMcpTool(name, args || {});
+    if (response && response.result && response.result.status === "local_execution_required") {
+      return {
+        content: [{ type: "text", text: response.result.message || formatLocalToolGuidance(name, args) }]
+      };
+    }
     return {
       content: [{ type: "text", text: formatTextContent(response.result || response) }]
     };
   } catch (error) {
-    const message = error.status === 403 ? "This MCP capability requires a paid Bootspring plan." : error.message;
     return {
-      content: [{ type: "text", text: `Error: ${message}` }],
+      content: [{ type: "text", text: `Error: ${formatProxyError(error)} (bootspring v${VERSION})` }],
       isError: true
     };
   }
@@ -52533,6 +52601,16 @@ async function proxyResourceRead(uri) {
       }]
     };
   }
+  const surfaceError = diagnoseApiSurface();
+  if (surfaceError) {
+    return {
+      contents: [{
+        uri,
+        mimeType: "text/plain",
+        text: surfaceError
+      }]
+    };
+  }
   try {
     const response = await api2.getMcpResource(uri);
     return {
@@ -52547,7 +52625,7 @@ async function proxyResourceRead(uri) {
       contents: [{
         uri,
         mimeType: "text/plain",
-        text: `Error: ${error.message}`
+        text: `Error: ${formatProxyError(error)} (bootspring v${VERSION})`
       }]
     };
   }
@@ -52577,6 +52655,10 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error(`Bootspring MCP proxy v${VERSION} started`);
+  const surfaceError = diagnoseApiSurface();
+  if (surfaceError) {
+    console.error("[bootspring-mcp] WARNING: " + surfaceError.split("\n").join(" "));
+  }
 }
 if (require.main === module) {
   main().catch((error) => {
@@ -52591,5 +52673,24 @@ module.exports = {
   resourceHandlers,
   FALLBACK_TOOLS,
   FALLBACK_RESOURCES,
-  main
+  main,
+  // Exposed for tests — lock in the stale-install regression guard
+  _diagnoseApiSurface: diagnoseApiSurface,
+  _formatProxyError: formatProxyError,
+  _LOCAL_TOOLS: LOCAL_TOOLS,
+  _formatLocalToolGuidance: formatLocalToolGuidance,
+  _proxyToolCall: proxyToolCall,
+  _diagnoseFromApi: function diagnoseFromApi(apiShim, version) {
+    const required = ["callMcpTool", "listMcpTools", "listMcpResources", "getMcpResource"];
+    const missing = required.filter((fn) => typeof apiShim?.[fn] !== "function");
+    if (missing.length === 0) return null;
+    return [
+      `Bootspring MCP server v${version} is missing required API methods: ${missing.join(", ")}.`,
+      `This usually means the installed @girardmedia/bootspring package is out of date.`,
+      `Fix:`,
+      `  1. Quit Claude Code completely`,
+      `  2. npm i -g @girardmedia/bootspring@latest`,
+      `  3. Restart Claude Code so the MCP server reloads`
+    ].join("\n");
+  }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@girardmedia/bootspring",
-  "version": "2.5.7",
+  "version": "2.5.9",
   "description": "Thin client for Bootspring cloud MCP, hosted agents, and paywalled workflow intelligence",
   "keywords": [
     "ai",

package/scripts/postinstall.cjs

@@ -6,6 +6,7 @@ const path = require('path');
 
 const c = {
   reset: '\x1b[0m',
+  bold: '\x1b[1m',
   green: '\x1b[32m',
   yellow: '\x1b[33m',
   cyan: '\x1b[36m',
@@ -207,11 +208,31 @@ function registerAllMcp() {
   return [registerClaudeMcp(), registerCodexMcp(), registerGeminiMcp()];
 }
 
+function isFirstInstall() {
+  // Heuristic: a first install is one where Claude Code config does NOT yet
+  // have a bootspring entry. Updates to an existing install will already
+  // have one and shouldn't see the welcome screen.
+  try {
+    const claudeConfig = path.join(HOME, '.claude.json');
+    if (!fs.existsSync(claudeConfig)) return true;
+    const raw = fs.readFileSync(claudeConfig, 'utf8');
+    if (!raw.trim()) return true;
+    const parsed = JSON.parse(raw);
+    return !parsed?.mcpServers?.bootspring;
+  } catch {
+    return false;
+  }
+}
+
 function main() {
   if (process.env.CI || process.env.BOOTSPRING_SKIP_POSTINSTALL) {
     return;
   }
 
+  // Capture this BEFORE we run any registration so the welcome message
+  // only fires the first time bootspring is installed on this machine.
+  const firstInstall = isFirstInstall();
+
   let totalCommandsInstalled = 0;
   let totalSkillsInstalled = 0;
   const installedTo = [];
@@ -260,9 +281,20 @@ ${c.dim}Installed:${c.reset}
       console.log(`${c.yellow}Note:${c.reset} ${c.dim}MCP registration skipped for ${mcpSkipped.map((r) => r.name).join(', ')} — run \`bootspring setup\` to retry.${c.reset}`);
     }
 
-    console.log(`
+    if (firstInstall) {
+      console.log(`
+${c.bold}Next steps:${c.reset}
+  ${c.cyan}1.${c.reset} Restart your assistant (Claude Code / Codex / Gemini) so MCP loads
+  ${c.cyan}2.${c.reset} ${c.green}bootspring auth login${c.reset}     ${c.dim}# authenticate (opens browser)${c.reset}
+  ${c.cyan}3.${c.reset} ${c.green}cd${c.reset} into a project, then ${c.green}bootspring go${c.reset}  ${c.dim}# one-shot setup${c.reset}
+
+${c.dim}Run ${c.reset}${c.green}bootspring${c.reset}${c.dim} with no args to see the welcome screen.${c.reset}
+`);
+    } else {
+      console.log(`
 ${c.dim}Restart your assistant (Claude Code, Codex, or Gemini CLI) to load the bootspring MCP tools.${c.reset}
 `);
+    }
   }
 }