sap-ai-dev-toolkit 0.9.0 → 0.9.2

package/README.md

@@ -46,6 +46,12 @@ npm install --global sap-ai-dev-toolkit
 sap-ai-dev --setup
 ```
 
+Or run the whole toolkit once with npx — no global install, nothing left behind except the generated MCP configuration:
+
+```sh
+npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
+```
+
 To also add optional full-stack SAP companion MCP servers for Fiori, UI5, CAP, and browser validation, run:
 
 ```sh
@@ -252,7 +258,16 @@ Install globally from SAP Business Application Studio or from a local workstatio
 | **Any local interactive terminal, already installed** | `sap-ai-dev --setup` | Re-runs the wizard to add, update, or remove generated MCP entries. Plain `sap-ai-dev` with no arguments also starts local setup when no BAS environment is detected. |
 | **npm install hook did not show a wizard** | `sap-ai-dev --setup` | This is expected on some npm/Windows combinations because lifecycle scripts may run without an interactive console. The explicit setup command is the reliable path. |
 | **Force npm to show install-time script output** | `npm install --global --foreground-scripts sap-ai-dev-toolkit` | Optional troubleshooting mode if you specifically want to see postinstall output during installation. Still run `sap-ai-dev --setup` afterwards if no destinations were configured. |
-| **No global install / temporary setup** | `npx --yes --ignore-scripts --package=sap-ai-dev-toolkit sap-ai-dev --setup --npx` | Runs the guided setup through npm and writes generated entries that launch the pinned package through `npx`. |
+| **No global install / temporary setup** | `npx --yes --ignore-scripts sap-ai-dev-toolkit --setup` | Runs the guided setup through npm and writes generated entries that launch the pinned package through `npx` (`cmd /c npx` on Windows). Add `--npx` to force the npx launcher even when a global `sap-ai-dev` command exists. |
+
+### 🪟 Windows notes
+
+Everything works natively on Windows — PowerShell, cmd, and Windows Terminal are all supported:
+
+- `npm install --global sap-ai-dev-toolkit` puts three commands on `PATH`: `sap-ai-dev`, its alias `sap-ai-dev-toolkit`, and `sap-ai-hana`. If `sap-ai-dev` is reported as unknown, npm's global bin directory is missing from `PATH` (run `npm prefix -g` to find it) or the install did not complete — `npx --yes --ignore-scripts sap-ai-dev-toolkit --setup` works without any global install.
+- The pinned VSP runtime ships inside the package as a native `vsp-win32-x64.exe`; no Go toolchain, WSL, or extra downloads are required.
+- MCP entries that launch through npm are written as `cmd /c npx ...` on Windows — the form VS Code, Claude Code, and Cursor can spawn there. Entries written on Linux/macOS use plain `npx`.
+- Local SAP GUI discovery reads the Windows landscape files and registry, and setup can write an experimental Windows SSO (`Negotiate`/SPNEGO) entry; see the “Local machine SAP GUI support” section below.
 
 If you previously installed the old package, remove it first because the legacy `bas-vsp-mcp` command is no longer shipped:
 
@@ -312,9 +327,9 @@ The same postinstall offers the bundled agents and skills for several AI coding
 
 Some current npm versions also require install hooks to be approved. If npm reports that `sap-ai-dev-toolkit`'s `postinstall` was blocked, allow it during a fresh install with `npm install --global --allow-scripts=sap-ai-dev-toolkit sap-ai-dev-toolkit`, or run `sap-ai-dev --setup` from an interactive terminal after installation.
 
-The setup report uses icons and terminal colors; set `NO_COLOR=1` to disable ANSI colors. 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.
+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. Use `--npx` to make generated destination entries start the pinned package through npm instead of relying on a global `sap-ai-dev` command; 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`; 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.
 
 If a setup step is skipped or fails, rerun it from an interactive terminal:
 
@@ -325,10 +340,10 @@ sap-ai-dev --setup
 To configure without a global install, run the guided setup directly through npm:
 
 ```sh
-npx --yes --ignore-scripts --package=sap-ai-dev-toolkit sap-ai-dev --setup --npx
+npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
 ```
 
-This lists discovered systems in the same checkbox picker, with nothing selected by default. Use **Space** to choose destinations, **Enter** to confirm, and **a** to toggle all (select all if any are unchecked; otherwise clear the selection). It writes MCP entries that launch the selected servers through npx. The entries pin the package version used during setup, and `--ignore-scripts` avoids running the install-time wizard a second time. After setup, in BAS or VS Code run **MCP: List Servers**, select each chosen destination, and choose **Start Server**.
+This lists discovered systems in the same checkbox picker, with nothing selected by default. Use **Space** to choose destinations, **Enter** to confirm, and **a** to toggle all (select all if any are unchecked; otherwise clear the selection). Because no global `sap-ai-dev` command is on `PATH`, it writes MCP entries that launch the pinned package version through npx — through `cmd /c npx` on Windows, which is the form VS Code, Claude Code, and Cursor can spawn there. `--ignore-scripts` avoids running the install-time wizard a second time; add `--npx` to force this launcher shape even when the toolkit is installed globally. After setup, in BAS or VS Code run **MCP: List Servers**, select each chosen destination, and choose **Start Server**.
 
 For a non-interactive installation or a platform without a published VSP asset, provide a trusted binary override:
 
@@ -423,7 +438,7 @@ Review skipped or conflicting files and merge changes manually. `LintABAP` analy
 If the `cf` CLI is version 8.18 or newer and authenticated to a targeted space, setup offers an opt-in import from that space's SAP Destination service. It does not create service keys unless you accept. The imported records are limited to the current space and are merged with BAS destinations for selection. OnPremise destinations require choosing a Connectivity service instance; runtime traffic uses that service's proxy, and PrincipalPropagation uses the current CF user's token. Internet destinations use the configured HTTP(S) proxy environment. Setup stores only service-instance/key references in `mcp.json`, not the service-key credentials. At runtime the generated entry verifies the active CF space and resolves those references. Setup removes an add-on-created key only when no remaining CF entry references it and the CLI is targeted to the key's recorded space; keys are left untouched when the space cannot be verified.
 Cloud Foundry HTTP destination probes use forward-form HTTP requests, not CONNECT tunnels; SAP Connectivity requires HTTP from the application to its proxy. OnPremise requests are canceled when the client disconnects or the runtime route closes.
 
-Interactive npm install and `sap-ai-dev --setup` both use a checkbox picker with no destinations selected by default. Use **Space** to choose destinations, **Enter** to confirm, and **a** to toggle all (select all if any are unchecked; otherwise clear the selection). Confirming with none checked removes this package's generated MCP entries. Non-interactive installs skip destination or local SAP GUI system selection without changing MCP config. Run the interactive setup command above; add `--npx` when the package is not installed globally.
+Interactive npm install and `sap-ai-dev --setup` both use a checkbox picker with no destinations selected by default. Use **Space** to choose destinations, **Enter** to confirm, and **a** to toggle all (select all if any are unchecked; otherwise clear the selection). Confirming with none checked removes this package's generated MCP entries. Non-interactive installs skip destination or local SAP GUI system selection without changing MCP config. Run the interactive setup command above; generated entries fall back to the pinned npx launcher automatically when the package is not installed globally.
 
 Setup tidies its own footprint: it reconciles MCP entries managed by this package and removes legacy `sapAiDev_*` / `basVspMcp_*` entries from earlier releases. Existing unrelated MCP servers and top-level configuration such as `inputs` stay untouched.
 
@@ -857,6 +872,8 @@ NPM_PUBLISH_TOKEN=npm_...
 - To publish a patch bump, run `npm run publish:npm -- --patch`; it updates `package.json` and `package-lock.json` before publishing. If publishing fails after the bump, retry without `--patch`.
 - npm's `prepublishOnly` hook builds the pinned VSP binaries for all platforms (including the Go toolchain if missing) and refuses to ship a tarball whose `dist/checksums.txt` does not list all five assets; it guards `npm run publish:npm` and a plain `npm publish` alike. Pass `--skip-build` to republish an already-built `dist/` without rebuilding.
 - Preview the package without publishing, changing its version, or building with `npm run publish:npm -- --dry-run`.
+- GitHub Actions runs the test suite on pushes to `main` and pull requests. A push to `main` that changes the `package.json` version runs the same checks, builds the VSP binaries, publishes that version to npm, and creates a `v<version>` GitHub release with generated notes.
+- The publish workflow uses the `NPM_PUBLISH_TOKEN` GitHub repository secret. Verify it with `gh secret list`; the token value is never stored in the repository.
 
 The token is not printed or stored in the repository.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "SAP AI development toolkit for BAS, ABAP, RAP, CAP, HANA Cloud, Fiori, UI5, and MCP",
   "author": "Gurkan Yilmaz",
   "type": "module",
@@ -17,6 +17,7 @@
   },
   "bin": {
     "sap-ai-dev": "src/launcher.mjs",
+    "sap-ai-dev-toolkit": "src/launcher.mjs",
     "sap-ai-hana": "src/hana-inspector.mjs"
   },
   "scripts": {

package/scripts/postinstall.mjs

@@ -9,7 +9,7 @@ import { installMcpServersForHarnesses } from '../src/harness-mcp-config.mjs';
 import { DEFAULT_HARNESS_IDS, HARNESSES, HARNESS_ENV_VAR, NON_INTERACTIVE_HARNESS_IDS, envHarnessSelection, harnessRoot } from '../src/harnesses.mjs';
 import { ReadStream as TTYReadStream, WriteStream as TTYWriteStream } from 'node:tty';
 import { homedir } from 'node:os';
-import { checkboxPrompt, colorText, formatStatus } from '../src/terminal-ui.mjs';
+import { checkboxPrompt, colorText, formatStatus, startProgress } from '../src/terminal-ui.mjs';
 import { brandedEnvValue, withBrandedEnvironment } from '../src/branding.mjs';
 import { generatedServerName } from '../src/mcp-config.mjs';
 import { redactText } from '../src/redact.mjs';
@@ -232,7 +232,7 @@ async function announceSetup(result) {
     return;
   }
   if (result?.reason === 'non-tty') {
-    await announce('Destination selection was skipped because npm did not provide an interactive terminal.\nMCP config was not changed.\nRun sap-ai-dev --setup from an interactive BAS terminal, or run npx --yes --ignore-scripts --package=sap-ai-dev-toolkit sap-ai-dev --setup --npx.', 'warning');
+    await announce('Destination selection was skipped because npm did not provide an interactive terminal.\nMCP config was not changed.\nRun sap-ai-dev --setup from an interactive terminal, or run npx --yes --ignore-scripts sap-ai-dev-toolkit --setup from any terminal.', 'warning');
     return;
   }
   if (result?.reason === 'no-destinations') {
@@ -304,11 +304,15 @@ async function main() {
     if (brandedEnvValue(runtimeEnv, 'BINARY')) {
       await announce('Using the SAP_AI_DEV_TOOLKIT_BINARY override.', 'info');
     } else {
-      await announce('Preparing the pinned VSP runtime for this platform.', 'progress');
+      // The bundled binary resolves in milliseconds; the animation only
+      // appears when provisioning actually takes time (download fallback).
+      const stopBinaryProgress = startProgress('Preparing the pinned VSP runtime for this platform', { output: process.stderr, env: runtimeEnv });
       try {
         await installBinary(pkg, { env: runtimeEnv });
+        stopBinaryProgress();
         await announce('Pinned VSP binary installed and ready.', 'success');
       } catch (error) {
+        stopBinaryProgress();
         throw new Error(`VSP binary provisioning failed: ${error.message}`);
       }
     }

package/src/launcher.mjs

@@ -7,13 +7,14 @@ import { discoverDestinations, remediation, slugifyDestination, statusRows } fro
 import { discoverSapGuiSystems } from './local-sap-gui.mjs';
 import { findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
-import { installMcpConfig, repairManagedMcpConfig } from './mcp-config.mjs';
+import { installMcpConfig, npxMcpLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
 import { runSetup } from './setup.mjs';
 import { resolveConfiguredCloudFoundryDestination } from './cf-destination.mjs';
 import { createWindowsSsoAdtProxy } from './windows-sso-adt-proxy.mjs';
 import { createTlsServerNameAdtProxy } from './tls-adt-proxy.mjs';
 import { withBrandedEnvironment } from './branding.mjs';
 import { redactText } from './redact.mjs';
+import { startProgress } from './terminal-ui.mjs';
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
 const runtimeEnv = withBrandedEnvironment(process.env);
@@ -53,7 +54,9 @@ function doctorRow(name, stage, status, detail) {
 
 async function runDoctor(destinations) {
   const checks = [];
+  const stopProgress = startProgress(destinations.length === 1 ? `Checking ${destinations[0]?.name || 'destination'}` : `Checking ${destinations.length} destinations`, { output: process.stderr, label: 'Doctor' });
   if (!destinations.length) {
+    stopProgress();
     return { ok: false, destinations: 0, checks: [doctorRow('-', 'destination discovery', 'failed', 'No destinations were found. Check H2O_URL or the configured Cloud Foundry destination.')] };
   }
   let binary;
@@ -76,6 +79,7 @@ async function runDoctor(destinations) {
     checks.push(doctorRow('-', 'MCP config repair', 'failed', redactText(error.message || error).slice(0, 300)));
   }
   for (const destination of destinations) {
+    stopProgress.update(`Checking ${destination.name}: ADT probe, VSP startup, tools/list`);
     const probe = destination.probe;
     const probeStatus = !probe || probe.status === 'skipped' ? 'skipped' : (probe.available === true ? 'passed' : 'failed');
     checks.push(doctorRow(destination.name, 'ADT probe', probeStatus, probe?.status || 'No BAS ADT probe was supplied; GetSystemInfo will check the route.'));
@@ -126,6 +130,7 @@ async function runDoctor(destinations) {
     }
   }
   const required = checks.filter(check => check.status !== 'skipped');
+  stopProgress();
   return { ok: required.every(check => check.status === 'passed'), destinations: destinations.length, checks };
 }
 
@@ -253,11 +258,17 @@ async function main() {
   if (doctor) {
     let report;
     try {
-      const destinations = runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry'
-        ? [await resolveConfiguredCloudFoundryDestination({ env: runtimeEnv })]
-        : (runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'sap-gui-local'
-          ? [await configuredLocalSapGuiDestination(runtimeEnv)]
-          : await discoverForCommand());
+      const stopDiscoveryProgress = startProgress('Discovering SAP destinations', { output: process.stderr, env: runtimeEnv, label: 'Doctor' });
+      let destinations;
+      try {
+        destinations = runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry'
+          ? [await resolveConfiguredCloudFoundryDestination({ env: runtimeEnv })]
+          : (runtimeEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'sap-gui-local'
+            ? [await configuredLocalSapGuiDestination(runtimeEnv)]
+            : await discoverForCommand());
+      } finally {
+        stopDiscoveryProgress();
+      }
       report = await runDoctor(destinations);
     } catch (error) {
       report = { ok: false, destinations: 0, checks: [doctorRow('-', 'destination discovery', 'failed', redactText(error.message || error).slice(0, 300))] };
@@ -272,17 +283,26 @@ async function main() {
       includeSapDevelopmentToolsPrompt: hasFlag('--tools') || hasFlag('--companion-tools')
     };
     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: 'npx',
-        args: ['--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit@${pkg.version}`, 'sap-ai-dev']
+        command: launcher.command,
+        args: [...launcher.prefixArgs, '--yes', '--ignore-scripts', `--package=sap-ai-dev-toolkit@${pkg.version}`, 'sap-ai-dev']
       });
     }
     await runSetup(setupOptions);
     return;
   }
   if (check || list) {
-    const destinations = await discoverForCommand();
+    const stopProgress = startProgress('Discovering SAP destinations and probing ADT endpoints', { output: process.stderr, env: runtimeEnv });
+    let destinations;
+    try {
+      destinations = await discoverForCommand();
+    } finally {
+      stopProgress();
+    }
     const statuses = statusRows(destinations);
     if (list && hasFlag('--json')) json(statuses);
     else for (const row of statuses) console.error(`${row.name}: client=${row.client} authentication=${row.authentication} probe=${row.probe}`);
@@ -319,11 +339,15 @@ async function main() {
       return;
     }
     const binary = await binaryOrError();
-    // Windows cannot exec a .js/.mjs file directly; route JavaScript entries
+    // Windows cannot exec .js/.mjs files directly; route JavaScript entries
     // (test fixtures) through the current Node binary like MCPProxy does.
+    // Windows .cmd/.bat shims (e.g. a SAP_AI_DEV_TOOLKIT_BINARY override)
+    // must go through cmd /c; Node refuses to spawn batch files directly.
     const spawnTarget = /\.(?:mjs|cjs|js)$/i.test(binary)
       ? { command: process.execPath, prefixArgs: [binary] }
-      : { command: binary, prefixArgs: [] };
+      : (/\.(?: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'));
@@ -336,7 +360,13 @@ async function main() {
     return;
   }
 
-  const discovered = await discoverDestinations({ env: runtimeEnv });
+  const stopProgress = startProgress('Discovering BAS destinations and probing ADT endpoints', { output: process.stderr, env: runtimeEnv });
+  let discovered;
+  try {
+    discovered = await discoverDestinations({ env: runtimeEnv });
+  } finally {
+    stopProgress();
+  }
   for (const destination of discovered) logLine(probeDiagnostic(destination));
   const destinations = discovered;
   if (!destinations.length) {

package/src/mcp-config.mjs

@@ -98,6 +98,44 @@ export async function resolveMcpServerCommand(env = process.env) {
   return 'sap-ai-dev';
 }
 
+// Windows ships npx as npx.cmd, not npx.exe: MCP hosts spawn the configured
+// command directly without shell PATH resolution, so npx-launched servers
+// must route through `cmd /c npx` there (the form VS Code, Claude Code, and
+// Cursor document for Windows). Other platforms run npx directly.
+export function npxMcpLauncher(platform = process.platform) {
+  return platform === 'win32'
+    ? { command: 'cmd', prefixArgs: ['/c', 'npx'] }
+    : { command: 'npx', prefixArgs: [] };
+}
+
+// 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.
+function npxLaunchArgs(entry) {
+  const args = Array.isArray(entry?.args) ? entry.args.map(String) : [];
+  if (entry?.command === 'npx') return args;
+  const commandName = typeof entry?.command === 'string'
+    ? entry.command.slice(Math.max(entry.command.lastIndexOf('/'), entry.command.lastIndexOf('\\')) + 1)
+    : '';
+  if (/^cmd(?:\.exe)?$/i.test(commandName) && args[0]?.toLowerCase() === '/c' && /^npx(?:\.cmd)?$/i.test(args[1] || '')) {
+    return args.slice(2);
+  }
+  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.
+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'] };
+}
+
 export async function resolveMcpConfigPath(env = process.env) {
   const configuredPath = [env.SAP_AI_DEV_MCP_CONFIG, brandedEnvValue(env, 'MCP_CONFIG')]
     .find(value => typeof value === 'string' && value.length > 0);
@@ -138,16 +176,17 @@ export function generatedDestinationServerName(destination) {
   return generatedServerName(destination?.source === 'cloud-foundry' ? destination.serverName : destination?.name);
 }
 
-export function buildSapDevelopmentMcpEntries(serverIds = SAP_DEVELOPMENT_MCP_SERVERS.map(server => server.id), { packageVersions = {}, packageManager = 'npx' } = {}) {
+export function buildSapDevelopmentMcpEntries(serverIds = SAP_DEVELOPMENT_MCP_SERVERS.map(server => server.id), { packageVersions = {}, packageManager = 'npx', platform = process.platform } = {}) {
   const selected = new Set(serverIds);
   const entries = Object.create(null);
+  const launcher = packageManager === 'npx' ? npxMcpLauncher(platform) : { command: packageManager, prefixArgs: [] };
   for (const server of SAP_DEVELOPMENT_MCP_SERVERS) {
     if (!selected.has(server.id)) continue;
     const packageSpec = packageVersions[server.id] || packageVersions[server.packageName] || server.packageName;
     entries[server.id] = {
       type: 'stdio',
-      command: packageManager,
-      args: ['--yes', ...(server.ignoreScripts ? ['--ignore-scripts'] : []), `--package=${packageSpec}`, server.bin],
+      command: launcher.command,
+      args: [...launcher.prefixArgs, '--yes', ...(server.ignoreScripts ? ['--ignore-scripts'] : []), `--package=${packageSpec}`, server.bin],
       BAS_EXT: 'true',
       BAS_EXT_KIND: COMPANION_SERVER_KIND,
       displayName: server.name,
@@ -232,16 +271,14 @@ function isPackageLauncher(entry) {
   const legacyCommand = legacyCommands.has(entry?.command) || legacyCommands.has(commandName);
   const currentPackages = [/^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/];
   const legacyPackages = [/^--package=bas-mcp-addon(?:@[^/]+)?$/];
-  const hasPackage = patterns => Array.isArray(entry?.args)
-    && entry.args.some(argument => typeof argument === 'string' && patterns.some(pattern => pattern.test(argument)));
-  const currentNpxLauncher = entry?.command === 'npx'
-    && Array.isArray(entry.args)
-    && entry.args.some(argument => currentCommands.has(argument))
-    && hasPackage(currentPackages);
-  const legacyNpxLauncher = entry?.command === 'npx'
-    && Array.isArray(entry.args)
-    && entry.args.some(argument => legacyCommands.has(argument))
-    && hasPackage(legacyPackages);
+  const hasPackage = (arguments_, patterns) => arguments_.some(argument => patterns.some(pattern => pattern.test(argument)));
+  const npxArgs = npxLaunchArgs(entry);
+  const currentNpxLauncher = npxArgs !== null
+    && npxArgs.some(argument => currentCommands.has(argument))
+    && hasPackage(npxArgs, currentPackages);
+  const legacyNpxLauncher = npxArgs !== null
+    && npxArgs.some(argument => legacyCommands.has(argument))
+    && hasPackage(npxArgs, legacyPackages);
   // Current launchers are treated as managed only when tagged by this add-on.
   // Some early bas-mcp-addon entries were not tagged with BAS_EXT, though, and
   // leaving them behind keeps advertising the old full VSP surface (~159 tools).
@@ -264,10 +301,10 @@ function isManagedBasDestinationEntry(entry) {
     ? entry.command.slice(Math.max(entry.command.lastIndexOf('/'), entry.command.lastIndexOf('\\')) + 1).replace(/\.(?:cmd|exe)$/i, '')
     : '';
   const currentCommand = currentCommands.has(entry?.command) || currentCommands.has(commandName);
-  const currentNpxLauncher = entry?.command === 'npx'
-    && Array.isArray(entry.args)
-    && entry.args.some(argument => currentCommands.has(argument))
-    && entry.args.some(argument => typeof argument === 'string' && /^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/.test(argument));
+  const npxArgs = npxLaunchArgs(entry);
+  const currentNpxLauncher = npxArgs !== null
+    && npxArgs.some(argument => currentCommands.has(argument))
+    && npxArgs.some(argument => /^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/.test(argument));
   return entry?.BAS_EXT === 'true'
     && (currentCommand || currentNpxLauncher)
     && typeof destinationValue(entry?.env) === 'string'
@@ -356,12 +393,18 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
       if (input?.id) generatedInputs.set(input.id, input);
     }
   }
-  const launcherCommand = options.command || (destinations.length ? await resolveMcpServerCommand(env) : null);
+  let launcherCommand = options.command || null;
+  let launcherArgs = options.command ? options.args : null;
+  if (!launcherCommand && destinations.length) {
+    const resolved = await resolveLauncherInstallCommand(env);
+    launcherCommand = resolved.command;
+    launcherArgs = resolved.args;
+  }
   if (launcherCommand) {
     for (const entry of Object.values(generated)) {
       if (isCompanionServer(entry)) continue;
       entry.command = launcherCommand;
-      if (options.command && options.args?.length) entry.args = [...options.args];
+      if (launcherArgs?.length) entry.args = [...launcherArgs];
     }
   }
   const servers = Object.create(null);
@@ -406,7 +449,7 @@ export async function repairManagedMcpConfig(discoveredDestinations, { env = pro
   const config = await readConfig(configPath);
   const managedEntries = Object.values(config.servers).filter(isManagedBasDestinationEntry).length;
   if (!basDestinations.size) return { path: configPath, changed: false, repaired: 0, managedEntries };
-  const localCommand = await resolveMcpServerCommand(env);
+  const localLauncher = await resolveLauncherInstallCommand(env);
   let repaired = 0;
   for (const [serverName, entry] of Object.entries(config.servers)) {
     if (!isManagedBasDestinationEntry(entry)) continue;
@@ -430,14 +473,16 @@ export async function repairManagedMcpConfig(discoveredDestinations, { env = pro
     delete nextEnvironment.BAS_VSP_DESTINATION;
     delete nextEnvironment.BAS_VSP_DESTINATION_SOURCE;
     const nextEntry = { ...entry, type: 'stdio', env: nextEnvironment, BAS_EXT: 'true' };
-    if (entry.command === 'npx') {
+    if (npxLaunchArgs(entry) !== null) {
       if (packageVersion && Array.isArray(entry.args)) {
         nextEntry.args = entry.args.map(argument => typeof argument === 'string' && /^--package=sap-ai-dev-toolkit(?:@[^/]+)?$/.test(argument)
           ? `--package=sap-ai-dev-toolkit@${packageVersion}`
           : argument);
       }
     } else {
-      nextEntry.command = localCommand;
+      nextEntry.command = localLauncher.command;
+      if (localLauncher.args) nextEntry.args = [...localLauncher.args];
+      else delete nextEntry.args;
     }
     if (expectedName === serverName) {
       if (JSON.stringify(nextEntry) === JSON.stringify(entry)) continue;

package/src/mcp-proxy.mjs

@@ -200,9 +200,12 @@ export function childArguments(destination, env = process.env) {
 
 // Windows cannot exec a .js/.mjs file directly (no shebang support), so test
 // fixtures written in JavaScript are launched through the current Node binary.
-// The production VSP binary is a native executable and is unaffected.
+// The production VSP binary is a native executable and is unaffected; a
+// Windows .cmd/.bat override needs cmd /c because Node refuses to spawn
+// batch files directly (EINVAL since the CVE-2024-27980 hardening).
 function spawnCommand(binary) {
   if (/\.(?:mjs|cjs|js)$/i.test(binary)) return [process.execPath, binary];
+  if (/\.(?:cmd|bat)$/i.test(binary) && process.platform === 'win32') return ['cmd', '/c', binary];
   return [binary];
 }
 

package/src/setup.mjs

@@ -2,7 +2,7 @@ import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { platform } from 'node:os';
 import { isIP } from 'node:net';
-import { checkboxPrompt, colorText, formatStatus, selectPrompt, textPrompt } from './terminal-ui.mjs';
+import { checkboxPrompt, colorText, formatStatus, selectPrompt, startProgress, textPrompt } from './terminal-ui.mjs';
 import { discoverDestinations, remediation } from './bas-discovery.mjs';
 import { defaultAdtUrl, discoverSapGuiSystems } from './local-sap-gui.mjs';
 import { discoverCloudFoundryDestinations, getCloudFoundryTarget, deleteManagedCloudFoundryServiceKeys, findOrphanedCloudFoundryServiceKeys } from './cf-destination.mjs';
@@ -237,15 +237,21 @@ export async function runSetup({
     return { skipped: true, reason: 'non-tty' };
   }
   print(output, '');
-  print(output, formatStatus(isBas ? 'Contacting BAS to discover destinations; this may take a moment.' : 'Looking for local SAP GUI system configuration.', 'progress', output, 'Setup'));
+  if (!isBas) print(output, formatStatus('Looking for local SAP GUI system configuration.', 'progress', output, 'Setup'));
 
   let destinations = [];
   if (isBas) {
     let basDestinations;
+    // BAS discovery probes every destination's ADT endpoint (up to a 5s
+    // timeout each); the animated progress line keeps the terminal visibly
+    // alive from the first moment instead of looking stuck.
+    const stopDiscoveryProgress = startProgress('Contacting BAS to discover destinations', { output, env, label: 'Setup' });
     try {
       basDestinations = await discover({ env: { ...env, SAP_AI_DEV_TOOLKIT_DESTINATION: '' } });
     } catch (error) {
       throw new Error(`BAS discovery failed: ${error.message}`);
+    } finally {
+      stopDiscoveryProgress();
     }
     destinations = basDestinations.map(safeBasDestination);
   } else {

package/src/terminal-ui.mjs

@@ -401,3 +401,43 @@ export async function textPrompt({ message, secret = false, required = true, pla
     }
   });
 }
+
+// Animated progress line for long-running steps (destination discovery,
+// ADT probes, VSP binary provisioning). TTY outputs get spinner frames on an
+// unref'd timer that starts after a short delay, so steps that finish quickly
+// never flash anything. Non-TTY outputs (pipes, MCP hosts, --json callers,
+// CI) stay completely silent so machine consumers never see progress noise.
+// Returns stop(); on a TTY, stop() clears the line so it never pollutes
+// scrollback. stop.update(message) retargets the label while running (for
+// example per destination during --doctor).
+export function startProgress(initialMessage, { output = process.stdout, env = process.env, label = 'sap-ai-dev-toolkit' } = {}) {
+  const noop = Object.assign(() => {}, { update: () => {} });
+  if (!output || typeof output.write !== 'function') return noop;
+  const animationDisabled = env.TERM === 'dumb' || env.CI || env.SAP_AI_DEV_TOOLKIT_DISABLE_SCAN_ANIMATION === 'true';
+  if (!output.isTTY || !Number.isFinite(output.columns) || animationDisabled) return noop;
+  let message = String(initialMessage);
+  let index = 0;
+  let active = false;
+  let interval;
+  const render = () => {
+    active = true;
+    index += 1;
+    const columns = Math.max(20, output.columns || 80);
+    const dots = `.${'.'.repeat(index % 3)}${' '.repeat(2 - index % 3)}`;
+    const line = `${label}: ${message} ${dots}`.slice(0, Math.max(1, columns - 1));
+    output.write(`\r\u001b[2K${line}`);
+  };
+  const delay = setTimeout(() => {
+    render();
+    interval = setInterval(render, 120);
+    if (typeof interval.unref === 'function') interval.unref();
+  }, 150);
+  if (typeof delay.unref === 'function') delay.unref();
+  const stop = () => {
+    clearTimeout(delay);
+    if (interval) clearInterval(interval);
+    if (active) output.write('\r\u001b[2K');
+  };
+  stop.update = next => { message = String(next); };
+  return stop;
+}