sap-ai-dev-toolkit 0.9.2 → 0.9.3

package/README.md

@@ -41,15 +41,17 @@ SAP AI Dev Toolkit connects your AI coding assistant to the SAP development tool
 
 ## ⚡ Quick start
 
+The default installation is a single npx command — no global install, nothing left behind except the generated MCP configuration:
+
 ```sh
-npm install --global sap-ai-dev-toolkit
-sap-ai-dev --setup
+npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
 ```
 
-Or run the whole toolkit once with npx — no global install, nothing left behind except the generated MCP configuration:
+Prefer a persistent global install instead?
 
 ```sh
-npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
+npm install --global sap-ai-dev-toolkit
+sap-ai-dev --setup
 ```
 
 To also add optional full-stack SAP companion MCP servers for Fiori, UI5, CAP, and browser validation, run:
@@ -248,17 +250,23 @@ Once the destination server is enabled in your chat's tools picker, ask for outc
 
 ## 📦 Installation
 
-Install globally from SAP Business Application Studio or from a local workstation with SAP GUI installed, then run setup explicitly for your environment:
+The default installation is a single npx command that runs the guided setup directly through npm — no global install required. It works in SAP Business Application Studio and on local workstations alike:
+
+```sh
+npx --yes --ignore-scripts sap-ai-dev-toolkit --setup
+```
+
+Prefer a persistent global install? Install globally from SAP Business Application Studio or from a local workstation with SAP GUI installed, then run setup explicitly for your environment:
 
 | Environment / device | What to run | What setup does |
 | --- | --- | --- |
-| **SAP Business Application Studio dev space** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers BAS destinations, optionally imports Cloud Foundry Destination service records, and writes VS Code/BAS MCP entries. |
-| **Windows workstation with SAP GUI** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers SAP GUI landscape entries, asks for SAP client(s) and ADT URL, then writes local VS Code MCP entries. Windows SSO can be selected if the ADT endpoint supports Negotiate/SPNEGO. |
-| **macOS workstation with SAP GUI** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers SAP GUI landscape entries, asks for SAP client(s) and ADT URL, then writes local VS Code MCP entries with secure login prompts. |
+| **Any environment (default — no global install)** | `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. |
+| **SAP Business Application Studio dev space (global install)** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers BAS destinations, optionally imports Cloud Foundry Destination service records, and writes VS Code/BAS MCP entries. |
+| **Windows workstation with SAP GUI (global install)** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers SAP GUI landscape entries, asks for SAP client(s) and ADT URL, then writes local VS Code MCP entries. Windows SSO can be selected if the ADT endpoint supports Negotiate/SPNEGO. |
+| **macOS workstation with SAP GUI (global install)** | `npm install --global sap-ai-dev-toolkit`<br>`sap-ai-dev --setup` | Discovers SAP GUI landscape entries, asks for SAP client(s) and ADT URL, then writes local VS Code MCP entries with secure login prompts. |
 | **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 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
 
@@ -267,6 +275,7 @@ Everything works natively on Windows — PowerShell, cmd, and Windows Terminal a
 - `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`.
+- Setup reads `mcp.json` even when Windows tools saved it with a UTF-8/UTF-16 BOM (PowerShell `>`/`Set-Content`, Notepad "UTF-8 with BOM") and rewrites it as plain UTF-8. If the existing file cannot be used as-is, setup self-heals before falling back to a reset: VS Code-style comments and trailing commas (JSONC) are recovered in place, torn reads from a concurrent editor save are re-read once, and broken `servers`/`inputs` fields are repaired individually. Every lossy change first backs up the original next to the real file as `mcp.json.healed|repaired|invalid-<timestamp>.bak` (exclusive create, so reruns never overwrite an earlier backup; symlinked configs keep their link). `sap-ai-dev --doctor` stays strict and reports such files instead of rewriting them — run `sap-ai-dev --setup` to heal.
 - 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:
@@ -848,6 +857,8 @@ Runtime diagnostics take the stderr lane. In the MCP server's Output view, check
 
 If `GetSystemInfo` or `RunQuery` reports a CSRF-token fetch failure, VSP tries `/sap/bc/adt/core/discovery` first and falls back to `/sap/bc/adt/discovery` when the core endpoint returns HTTP 404 or 5xx without a token. If both endpoints fail, the error includes their HTTP statuses; check BAS destination routing and the SAP ADT service. `GetInstalledComponents` is a separate GET request and a failure there is not evidence of a CSRF problem.
 
+**`MCP config ... contains invalid JSON`** usually means one of three things, all healed automatically by setup: the file starts with a byte-order mark (Windows PowerShell `>` redirection, `Set-Content`, or Notepad's "UTF-8 with BOM" mode — invisible in editors and terminals), it contains comments or trailing commas (VS Code reads `mcp.json` as JSONC), or setup raced an editor save and read a torn file (retried once before healing). Unrecoverable content is backed up as `mcp.json.<kind>-<timestamp>.bak` and replaced; the backup path is printed in the setup warning. On older versions, re-save the file as UTF-8 without BOM (VS Code: "Change File Encoding → Save with Encoding → UTF-8") and rerun `sap-ai-dev --setup`.
+
 If automatic Go or VSP provisioning fails, check network access and the package's supported platform. You can install Go manually or set `GO_BINARY` as an explicit fallback. A trusted prebuilt VSP can be supplied with `SAP_AI_DEV_TOOLKIT_BINARY`.
 
 ## 🧑‍💻 Development

package/package.json

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

package/src/harness-mcp-config.mjs

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { harnessById, harnessRoot } from './harnesses.mjs';
+import { decodeJsonFileBuffer } from './mcp-config.mjs';
 
 const MANAGED_ENV = 'SAP_AI_DEV_TOOLKIT_MANAGED';
 
@@ -24,13 +25,15 @@ function mcpServersPath(harness, { home = process.env.HOME || homedir(), env = p
 async function readJsonConfig(path) {
   let raw;
   try {
-    raw = await readFile(path, 'utf8');
+    raw = await readFile(path);
   } catch (error) {
     if (error.code === 'ENOENT') return {};
     throw error;
   }
   try {
-    const parsed = JSON.parse(raw);
+    // decodeJsonFileBuffer tolerates the UTF-8 BOM / UTF-16 encodings that
+    // Windows tools commonly write (see mcp-config.mjs).
+    const parsed = JSON.parse(decodeJsonFileBuffer(raw));
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('top-level value is not an object');
     return parsed;
   } catch (error) {

package/src/mcp-config.mjs

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { access, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { homedir, platform } from 'node:os';
 import { basename, delimiter, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -79,6 +80,26 @@ async function exists(path) {
   }
 }
 
+// Windows tools (PowerShell `>` redirection and Set-Content, Notepad "UTF-8
+// with BOM", several editors) write mcp.json with a byte-order mark or even
+// UTF-16. JSON.parse rejects a leading BOM (rendering invisibly as
+// "Unexpected token ''"), so decode defensively before parsing.
+export function decodeJsonFileBuffer(buffer) {
+  if (!Buffer.isBuffer(buffer)) return String(buffer ?? '').replace(/^/, '');
+  if (buffer.length >= 2) {
+    if (buffer[0] === 0xFF && buffer[1] === 0xFE) return buffer.subarray(2).toString('utf16le');
+    if (buffer[0] === 0xFE && buffer[1] === 0xFF) {
+      let body = buffer.subarray(2);
+      if (body.length % 2) body = body.subarray(0, body.length - 1);
+      return Buffer.from(body).swap16().toString('utf16le');
+    }
+  }
+  const utf8 = (buffer.length >= 3 && buffer[0] === 0xEF && buffer[1] === 0xBB && buffer[2] === 0xBF)
+    ? buffer.subarray(3).toString('utf8')
+    : buffer.toString('utf8');
+  return utf8.replace(/^\uFEFF/, '');
+}
+
 export async function resolveMcpServerCommand(env = process.env) {
   const executableNames = process.platform === 'win32'
     ? ['sap-ai-dev.cmd', 'sap-ai-dev.exe', 'sap-ai-dev']
@@ -336,36 +357,186 @@ export function collectCloudFoundryKeyReferencesFromAllEntries(config) {
   return collectCloudFoundryKeyReferences(config, false);
 }
 
-async function readConfig(path) {
-  let raw;
+function freshConfig() {
+  return { servers: {}, inputs: [] };
+}
+
+// VS Code parses mcp.json as JSONC: // and /* */ comments plus trailing
+// commas are accepted there but rejected by strict JSON.parse. Strip them in
+// one string-aware pass (string literals are copied verbatim, so "//", "/*",
+// and "," inside values survive) so self-healing can recover hand-written
+// content instead of resetting the file.
+export function loosenJsonText(text) {
+  let out = '';
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const ch = text[i];
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < n && text[j] !== '"') j += text[j] === '\\' ? 2 : 1;
+      out += text.slice(i, Math.min(j + 1, n));
+      i = Math.min(j + 1, n);
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '/') {
+      i += 2;
+      while (i < n && text[i] !== '\n' && text[i] !== '\r') i += 1;
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '*') {
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i = Math.min(i + 2, n);
+      continue;
+    }
+    if (ch === ',') {
+      // A trailing comma is dropped only when nothing but whitespace and
+      // comments separate it from a closing bracket.
+      let k = i + 1;
+      while (k < n) {
+        const lookahead = text[k];
+        if (lookahead === ' ' || lookahead === '\t' || lookahead === '\n' || lookahead === '\r') { k += 1; continue; }
+        if (lookahead === '/' && text[k + 1] === '/') { k += 2; while (k < n && text[k] !== '\n' && text[k] !== '\r') k += 1; continue; }
+        if (lookahead === '/' && text[k + 1] === '*') { k += 2; while (k < n && !(text[k] === '*' && text[k + 1] === '/')) k += 1; k = Math.min(k + 2, n); continue; }
+        break;
+      }
+      if (text[k] === '}' || text[k] === ']') { i += 1; continue; }
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+export function backupPathCandidates(path, kind, now = new Date()) {
+  const stamp = new Date(now).toISOString().replace(/[:.]/g, '-');
+  return ['', '-2', '-3', '-4', '-5'].map(suffix => `${path}.${kind}-${stamp}${suffix}.bak`);
+}
+
+// Backups use exclusive creation (wx) so a repeated setup can never clobber
+// an earlier backup; identical timestamps walk a numeric suffix instead.
+// Failing to write the backup is fatal on purpose: healing must never risk
+// losing the only copy of the original file.
+export async function writeConfigBackup(path, buffer, { kind, now } = {}) {
+  let lastError;
+  for (const candidate of backupPathCandidates(path, kind, now)) {
+    try {
+      await writeFile(candidate, buffer, { flag: 'wx', mode: 0o600 });
+      return candidate;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw new Error(`Could not back up ${path} before healing (${error.message}); the original file was left untouched.`);
+      }
+      lastError = error;
+    }
+  }
+  throw new Error(`Could not back up ${path}: no unique backup name was available (${lastError?.message}).`);
+}
+
+function shapeFailures(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return [{ field: null, message: 'must contain a top-level JSON object' }];
+  }
+  const failures = [];
+  if (config.servers !== undefined && (!config.servers || typeof config.servers !== 'object' || Array.isArray(config.servers))) {
+    failures.push({ field: 'servers', message: 'has a non-object servers value' });
+  }
+  if (config.inputs !== undefined && config.inputs !== null && !Array.isArray(config.inputs)) {
+    failures.push({ field: 'inputs', message: 'has a non-array inputs value' });
+  }
+  return failures;
+}
+
+// Healing ladder (install/setup only; strict readers such as --doctor keep
+// rejecting): BOM/UTF-16 decode -> torn-write re-read -> JSONC recovery ->
+// field-level repair -> full reset. Every lossy step backs up the original
+// first; a backup failure aborts rather than risking data loss.
+async function readConfig(path, options = {}) {
+  const { recoverInvalid = false, warnings, retryDelayMs = 250, readFileImpl = readFile } = options;
+  let buffer;
   try {
-    raw = await readFile(path, 'utf8');
+    buffer = await readFileImpl(path);
   } catch (error) {
-    if (error?.code === 'ENOENT') return { servers: {}, inputs: [] };
+    if (error?.code === 'ENOENT') return freshConfig();
     throw new Error(`MCP config ${path} could not be read: ${error.message}`);
   }
-  let config;
-  try {
-    config = JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`MCP config ${path} contains invalid JSON: ${error.message}`);
+  let text = decodeJsonFileBuffer(buffer);
+  if (!text.trim()) return freshConfig();
+  const tryParse = candidate => {
+    try { return { config: JSON.parse(candidate) }; } catch (error) { return { error }; }
+  };
+  let parsed = tryParse(text);
+  if (parsed.error && retryDelayMs > 0) {
+    // A torn read — setup racing an editor's non-atomic save — looks exactly
+    // like corruption; re-read once before healing so a transient state is
+    // never backed up and replaced.
+    await sleep(retryDelayMs);
+    const second = await readFileImpl(path).catch(() => null);
+    if (second && !second.equals(buffer)) {
+      buffer = second;
+      text = decodeJsonFileBuffer(second);
+      if (!text.trim()) return freshConfig();
+      parsed = tryParse(text);
+    }
   }
-  if (!config || typeof config !== 'object' || Array.isArray(config)) {
-    throw new Error(`MCP config ${path} must contain a top-level JSON object`);
+  let loosened = false;
+  if (parsed.error && recoverInvalid) {
+    const recovered = tryParse(loosenJsonText(text));
+    if (!recovered.error) {
+      parsed = recovered;
+      loosened = true;
+    }
   }
-  if (config.servers !== undefined && (!config.servers || typeof config.servers !== 'object' || Array.isArray(config.servers))) {
-    throw new Error(`MCP config ${path} has a non-object servers value`);
+  const failures = parsed.error ? [{ field: null, message: `contains invalid JSON: ${parsed.error.message}` }] : shapeFailures(parsed.config);
+  if (failures.some(failure => failure.field === null)) {
+    const detail = failures[0].message;
+    if (!recoverInvalid) throw new Error(`MCP config ${path} ${detail}`);
+    return recoverConfig(path, buffer, warnings, {
+      kind: 'invalid',
+      notes: [`was not usable as JSON (${detail.replace(/^contains invalid JSON: /, '')}) and was replaced with a fresh config`],
+      config: freshConfig()
+    });
   }
-  return { ...config, servers: config.servers || {} };
+  const blocking = failures.find(failure => failure.field !== 'inputs');
+  if (!recoverInvalid) {
+    if (blocking) throw new Error(`MCP config ${path} ${blocking.message}`);
+    return { ...parsed.config, servers: parsed.config.servers || {} };
+  }
+  const notes = [];
+  if (loosened) notes.push('contained comments or trailing commas (accepted by VS Code, not strict JSON)');
+  const healed = { ...parsed.config };
+  for (const failure of failures) {
+    if (failure.field === 'servers') { healed.servers = {}; notes.push('had a non-object "servers" value, which was reset'); }
+    if (failure.field === 'inputs') { delete healed.inputs; notes.push('had a non-array "inputs" value, which was removed'); }
+  }
+  if (!notes.length) return { ...parsed.config, servers: parsed.config.servers || {} };
+  return recoverConfig(path, buffer, warnings, {
+    kind: loosened ? 'healed' : 'repaired',
+    notes,
+    config: { ...healed, servers: healed.servers || {} }
+  });
+}
+
+async function recoverConfig(path, buffer, warnings, { kind, notes, config }) {
+  // Back up beside the real file (following symlinks) so a linked mcp.json
+  // keeps its link and the backup sits next to the actual target.
+  const backupBase = await realpath(path).catch(() => path);
+  const backup = await writeConfigBackup(backupBase, buffer, { kind });
+  warnings?.push(`The existing MCP config ${notes.join(' and ')}; the original was backed up to ${backup}.`);
+  return config;
 }
 
 async function writeConfig(path, config) {
-  const directory = dirname(path);
+  // Follow symlinks so a linked mcp.json (dotfiles managers) keeps its link
+  // while the real target is replaced atomically.
+  const target = await realpath(path).catch(() => path);
+  const directory = dirname(target);
   await mkdir(directory, { recursive: true });
-  const temporary = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+  const temporary = join(directory, `.${basename(target)}.${process.pid}.${randomUUID()}.tmp`);
   try {
     await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-    await rename(temporary, path);
+    await rename(temporary, target);
   } catch (error) {
     await rm(temporary, { force: true }).catch(() => {});
     throw new Error(`MCP config ${path} could not be written: ${error.message}`);
@@ -380,7 +551,11 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
   }
   const env = options.env || process.env;
   const path = options.path || await resolveMcpConfigPath(env);
-  const config = await readConfig(path);
+  const installWarnings = [];
+  // recoverInvalid: BOM/encoding damage, VS Code JSONC comments, torn writes
+  // racing an editor save, and corrupt configs are healed (with a backup)
+  // instead of failing the whole setup (self-healing).
+  const config = await readConfig(path, { recoverInvalid: true, warnings: installWarnings });
   const selfVersion = await runningPackageVersion();
   const companionVersions = selfVersion ? { 'sap-ai-dev-toolkit': selfVersion, 'hana-cloud-inspector': selfVersion } : {};
   const generated = {
@@ -434,7 +609,7 @@ export async function installMcpConfig(destinationsOrOptions, options = {}) {
     config.inputs = [...existingInputs, ...generatedInputs.values()];
   }
   await writeConfig(path, config);
-  return { path, servers: generated };
+  return { path, servers: generated, warnings: installWarnings };
 }
 
 export async function repairManagedMcpConfig(discoveredDestinations, { env = process.env, path, discoveryComplete = false, packageVersion } = {}) {
@@ -499,6 +674,6 @@ export async function repairManagedMcpConfig(discoveredDestinations, { env = pro
   return { path: configPath, changed: true, repaired, managedEntries };
 }
 
-export async function readMcpConfig(path) {
-  return readConfig(path);
+export async function readMcpConfig(path, options = {}) {
+  return readConfig(path, options);
 }

package/src/setup.mjs

@@ -531,6 +531,7 @@ export async function runSetup({
     const configuredCount = selected.length + sapDevelopmentServers.length;
     print(output, formatStatus(`Configured ${configuredCount} MCP server${configuredCount === 1 ? '' : 's'}${location}.`, 'success', output, isBas ? 'BAS setup' : 'Local setup'));
     printConnectionInstructions(output, result);
+    warnings.push(...(Array.isArray(result?.warnings) ? result.warnings.filter(message => typeof message === 'string') : []));
     let cleanupWarnings = [];
     const finalPath = result?.path || configPath;
     if (isBas) {