sap-ai-dev-toolkit 0.9.94 → 0.9.97

package/README.md

@@ -338,7 +338,7 @@ Some current npm versions also require install hooks to be approved. If npm repo
 
 The setup report uses icons and terminal colors; set `NO_COLOR=1` to disable ANSI colors. Long-running steps (BAS destination discovery, ADT probes, VSP runtime provisioning, `--doctor` checks) show an animated progress line so the terminal never looks stuck; it appears only on interactive terminals and is disabled automatically on CI — set `SAP_AI_DEV_TOOLKIT_DISABLE_SCAN_ANIMATION=true` to turn it off. The table is a weather report, not a bouncer: green **PASS** means the ADT probe responded, red **FAIL** means it failed, and yellow **SKIPPED** means it was skipped. Probe failures do not block MCP registration or startup for destinations you select.
 
-Run `sap-ai-dev --setup` later to change the destination selection or remove generated destination entries. Run `sap-ai-dev --setup --tools` to also choose optional companion tools. Generated destination entries use the global `sap-ai-dev` command when it is on `PATH`; otherwise (for example after a pure npx setup) they automatically launch the pinned package version through `npx`, routed through `cmd /c npx` on Windows so every MCP host can spawn them. Pass `--npx` to force the npx launcher even when a global command exists; companion tools already use `npx` with their own npm packages.
+Run `sap-ai-dev --setup` later to change the destination selection or remove generated destination entries. Run `sap-ai-dev --setup --tools` to also choose optional companion tools. Generated destination entries use the global `sap-ai-dev` command when it is on `PATH` and is the same package version as the setup that writes them; otherwise (for example after a pure npx setup, or when an older global install is still on `PATH`) they automatically launch the pinned package version through `npx`, routed through `cmd /c npx` on Windows so every MCP host can spawn them. Setup warns when it skips a global install of another version. Pass `--npx` to force the npx launcher even when a global command exists; companion tools already use `npx` with their own npm packages.
 
 If a setup step is skipped or fails, rerun it from an interactive terminal:
 
@@ -824,6 +824,7 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 | `SAP_AI_DEV_TOOLKIT_BINARY_URL` | Alternate VSP binary download URL (checksum-verified). Legacy `BAS_VSP_BINARY_URL` still works. |
 | `SAP_AI_DEV_TOOLKIT_RELEASE_BASE_URL` | Override the base URL that VSP release binaries are downloaded from. |
 | `SAP_AI_DEV_TOOLKIT_CACHE_DIR` | Binary cache directory. Legacy `BAS_VSP_CACHE_DIR` still works. |
+| `SAP_AI_DEV_TOOLKIT_VERSION` | Written by setup into each destination entry: the toolkit version that configured it. An older `sap-ai-dev` started from that entry hands off to this version through `npx` (see Self-healing modes). |
 | `BAS_CF_SPACE_GUID`, `BAS_CF_DESTINATION_INSTANCE_GUID`, `BAS_CF_DESTINATION_INSTANCE`, `BAS_CF_DESTINATION_KEY`, `BAS_CF_DESTINATION_NAME`, `BAS_CF_CONNECTIVITY_INSTANCE_GUID`, `BAS_CF_CONNECTIVITY_INSTANCE`, `BAS_CF_CONNECTIVITY_KEY` | Written into generated Cloud Foundry destination entries; they reference service instances and key **names** (never credentials). |
 | `GO_BINARY` | Explicit Go executable for the repository-only `build:vsp` script; not used during installation. |
 | `SAP_AI_DEV_TOOLKIT_SKIP_PROBE=true` | Skip destination probes; useful for controlled diagnostics or fixtures. |
@@ -834,6 +835,7 @@ The response contains a `tools` array. A `RunQuery` entry resembles this excerpt
 
 VSP children connect to each configured destination URL directly. BAS destination authentication remains selected through VSP's `--proxy-auth` path; Cloud Foundry on-premise destinations continue through the separate Connectivity proxy.
 Child crash recovery restarts a failed VSP child, re-initializes it, re-registers tools, and retries the interrupted `tools/call` once before surfacing an error. State-changing tools are not retried.
+Stale launcher recovery: when an MCP entry starts a `sap-ai-dev` older than the `SAP_AI_DEV_TOOLKIT_VERSION` setup recorded in it (for example an outdated global install left on `PATH`), the launcher logs a warning and hands off to that version through `npx` on the same stdio, so the host never runs the stale launcher or VSP binary. A source checkout (`npm link`) always runs as-is.
 Existing installs that still set the previous `BAS_VSP_*` environment variables remain supported. The setup wizard writes new MCP entries with the `SAP_AI_DEV_TOOLKIT_*` names.
 
 #### Server logging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.9.94",
+  "version": "0.9.97",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",

package/src/launcher.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { isIP } from 'node:net';
 import { dirname, join } from 'node:path';
@@ -8,7 +9,7 @@ import { discoverDestinations, remediation, slugifyDestination, statusRows } fro
 import { adtBaseUrl, adtPort, detectAdtUrl, discoverSapGuiSystems, hasExplicitPort, hasPathPrefix } from './local-sap-gui.mjs';
 import { binaryTarget, cacheDirectory, downloadBinary, findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
-import { installMcpConfig, npxMcpLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
+import { configuredVersionHandoff, installMcpConfig, npxPackageLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
 import { runSetup } from './setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { createTlsServerNameAdtProxy } from './tls-adt-proxy.mjs';
@@ -268,6 +269,33 @@ function noProxyEnv(env, host) {
   return { NO_PROXY: noProxy, no_proxy: noProxy };
 }
 
+// Runs a child on this process's stdio and mirrors its exit; rejects only when it cannot start.
+async function runOnOwnStdio(command, commandArgs, env) {
+  const child = spawn(command, commandArgs, { env, stdio: 'inherit' });
+  process.once('SIGINT', () => child.kill('SIGINT'));
+  process.once('SIGTERM', () => child.kill('SIGTERM'));
+  const [code, signal] = await new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (exitCode, exitSignal) => resolve([exitCode, exitSignal]));
+  });
+  if (signal) process.kill(process.pid, signal);
+  process.exitCode = code ?? 1;
+}
+
+// A source checkout runs as-is: its developer chose that code.
+async function handOffToConfiguredVersion() {
+  const handoff = existsSync(join(root, '.git')) ? null : configuredVersionHandoff(runtimeEnv, pkg.version);
+  if (!handoff) return false;
+  logLine(`[sap-ai-dev] sap-ai-dev-toolkit ${pkg.version} is older than ${handoff.version}, which configured this MCP entry; self-healing: handing off to sap-ai-dev-toolkit@${handoff.version} through npx. Run "npm install -g sap-ai-dev-toolkit@${handoff.version}" to update the global install.`);
+  try {
+    await runOnOwnStdio(handoff.command, handoff.args, { ...runtimeEnv, SAP_AI_DEV_TOOLKIT_HANDOFF: pkg.version });
+    return true;
+  } catch (error) {
+    logLine(`[sap-ai-dev] handoff to sap-ai-dev-toolkit@${handoff.version} could not start (${error.message}); continuing with ${pkg.version}`);
+    return false;
+  }
+}
+
 async function discoverForCommand() {
   const env = { ...runtimeEnv };
   if (env.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry') env.SAP_AI_DEV_TOOLKIT_DESTINATION = '';
@@ -349,6 +377,7 @@ async function main() {
     process.stdout.write(usage());
     return;
   }
+  if (!setup && !check && !list && !doctor && !demo && await handOffToConfiguredVersion()) return;
   if (doctor && demo) throw new Error('Use either --doctor or --demo, not both.');
   if (demo) {
     await runOfflineDemo();
@@ -383,14 +412,8 @@ async function main() {
       detectAdtUrl: detectLocalAdtUrl
     };
     if (hasFlag('--npx')) {
-      // Windows has no npx.exe, so generated entries there launch through
-      // `cmd /c npx`; other platforms use npx directly.
-      const launcher = npxMcpLauncher();
-      setupOptions.install = (selected, options) => installMcpConfig(selected, {
-        ...options,
-        command: launcher.command,
-        args: [...launcher.prefixArgs, '--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit@${pkg.version}`, 'sap-ai-dev']
-      });
+      const launcher = npxPackageLauncher(pkg.version);
+      setupOptions.install = (selected, options) => installMcpConfig(selected, { ...options, ...launcher });
     }
     await runSetup(setupOptions);
     return;
@@ -450,15 +473,7 @@ async function main() {
       : (/\.(?:cmd|bat)$/i.test(binary)
         ? { command: 'cmd', prefixArgs: ['/c', binary] }
         : { command: binary, prefixArgs: [] });
-    const child = spawn(spawnTarget.command, [...spawnTarget.prefixArgs, ...process.argv.slice(2)], { env: runtimeEnv, stdio: 'inherit' });
-    process.once('SIGINT', () => child.kill('SIGINT'));
-    process.once('SIGTERM', () => child.kill('SIGTERM'));
-    const [code, signal] = await new Promise((resolve, reject) => {
-      child.once('error', reject);
-      child.once('exit', (exitCode, exitSignal) => resolve([exitCode, exitSignal]));
-    });
-    if (signal) process.kill(process.pid, signal);
-    process.exitCode = code ?? 1;
+    await runOnOwnStdio(spawnTarget.command, [...spawnTarget.prefixArgs, ...process.argv.slice(2)], runtimeEnv);
     return;
   }
 

package/src/mcp-config.mjs

@@ -131,6 +131,26 @@ export function npxMcpLauncher(platform = process.platform) {
     : { command: 'npx', prefixArgs: [] };
 }
 
+export function npxPackageLauncher(version, platform = process.platform) {
+  const { command, prefixArgs } = npxMcpLauncher(platform);
+  return { command, args: [...prefixArgs, '--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit${version ? `@${version}` : ''}`, 'sap-ai-dev'] };
+}
+
+function isOlderVersion(version, other) {
+  const parts = value => Array.from({ length: 3 }, (_, index) => Number.parseInt(String(value).split('.')[index], 10) || 0);
+  const [current, target] = [parts(version), parts(other)];
+  const index = current.findIndex((part, position) => part !== target[position]);
+  return index >= 0 && current[index] < target[index];
+}
+
+// Setup pins its version into each entry, so a stale sap-ai-dev on PATH can hand off
+// to that version through npx instead of running old code; the handoff happens once.
+export function configuredVersionHandoff(env, runningVersion, platform = process.platform) {
+  const configured = brandedEnvValue(env, 'VERSION');
+  if (!configured || brandedEnvValue(env, 'HANDOFF') || !isOlderVersion(runningVersion, configured)) return null;
+  return { version: configured, ...npxPackageLauncher(configured, platform) };
+}
+
 // Normalizes the argument list of npx-launched entries, whether written as
 // `npx ...` or the Windows `cmd /c npx ...` form; returns null when the entry
 // is not npx-launched.
@@ -146,17 +166,36 @@ function npxLaunchArgs(entry) {
   return null;
 }
 
+// The package version a PATH sap-ai-dev starts, found through npm's global
+// layouts (Unix bin symlink, Windows .cmd shim); null when the layout is unknown.
+async function commandPackageVersion(command) {
+  const target = await realpath(command).catch(() => command);
+  for (const manifest of [join(dirname(dirname(target)), 'package.json'), join(dirname(command), 'node_modules', 'sap-ai-dev-toolkit', 'package.json')]) {
+    try {
+      const pkg = JSON.parse(await readFile(manifest, 'utf8'));
+      if (pkg.name === 'sap-ai-dev-toolkit') return pkg.version;
+    } catch {
+      // Try the other layout.
+    }
+  }
+  return null;
+}
+
 // Resolves how generated destination entries launch the toolkit: the global
-// sap-ai-dev command when it is on PATH, otherwise the pinned package
-// through npx (routed through cmd /c on Windows) so entries written by a
-// pure `npx sap-ai-dev-toolkit --setup` run still start on every host.
+// sap-ai-dev command when it is on PATH and is this version, otherwise the
+// pinned package through npx (routed through cmd /c on Windows) so entries
+// written by a pure `npx sap-ai-dev-toolkit --setup` run still start on every host.
 async function resolveLauncherInstallCommand(env) {
   const resolved = await resolveMcpServerCommand(env);
-  if (resolved !== 'sap-ai-dev') return { command: resolved, args: null };
-  const { command, prefixArgs } = npxMcpLauncher();
   const selfVersion = await runningPackageVersion();
-  const packageSpec = selfVersion ? `sap-ai-dev-toolkit@${selfVersion}` : 'sap-ai-dev-toolkit';
-  return { command, args: [...prefixArgs, '--yes', '--ignore-scripts', `--package=${packageSpec}`, 'sap-ai-dev'] };
+  let warning;
+  if (resolved !== 'sap-ai-dev') {
+    const installed = await commandPackageVersion(resolved);
+    if (installed === null || !selfVersion || installed === selfVersion) return { command: resolved, args: null };
+    // A stale global install would keep starting the old launcher and VSP binary.
+    warning = `${resolved} is sap-ai-dev-toolkit ${installed}, not ${selfVersion}; MCP entries start sap-ai-dev-toolkit@${selfVersion} through npx instead. Run "npm install -g sap-ai-dev-toolkit@${selfVersion}" to use the global command.`;
+  }
+  return { ...npxPackageLauncher(selfVersion), warning };
 }
 
 export async function resolveMcpConfigPath(env = process.env) {
@@ -576,12 +615,14 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
     const resolved = await resolveLauncherInstallCommand(env);
     launcherCommand = resolved.command;
     launcherArgs = resolved.args;
+    if (resolved.warning) installWarnings.push(resolved.warning);
   }
   if (launcherCommand) {
     for (const entry of Object.values(generated)) {
       if (isCompanionServer(entry)) continue;
       entry.command = launcherCommand;
       if (launcherArgs?.length) entry.args = [...launcherArgs];
+      if (selfVersion) entry.env.SAP_AI_DEV_TOOLKIT_VERSION = selfVersion;
     }
   }
   const servers = Object.create(null);