sap-ai-dev-toolkit 0.8.1 → 0.8.3

package/README.md

@@ -33,7 +33,7 @@
 SAP AI Dev Toolkit connects your AI coding assistant to the SAP development tools available for each selected destination. Agents can inspect ABAP and CDS, propose changes, run checks, and return the evidence—without losing sight of which SAP system each operation targets.
 
 <p align="center">
-  <strong>Agent chat</strong> → <strong>destination-scoped MCP</strong> → <strong>VSP + BAS destination</strong> → <strong>SAP ADT</strong> → <strong>your SAP system</strong><br>
+  <strong>Agent chat</strong> → <strong>destination-scoped MCP</strong> → <strong>VSP + configured route (BAS, CF, or local SAP GUI)</strong> → <strong>SAP ADT</strong> → <strong>your SAP system</strong><br>
   <em>results and diagnostics flow back along the same path</em>
 </p>
 
@@ -52,7 +52,7 @@ To also add optional full-stack SAP companion MCP servers for Fiori, UI5, CAP, a
 sap-ai-dev --setup --tools
 ```
 
-Then connect a destination in SAP Business Application Studio, or run the same setup locally to discover SAP GUI systems and create VS Code MCP entries:
+After setup, connect a selected BAS destination or local SAP GUI system from your MCP-capable editor:
 
 1. Open the Command Palette.
 2. Run **MCP: List Servers**.
@@ -79,11 +79,11 @@ Use the attached destination-prefixed tools directly in chat. Do not launch `sap
 
 **Included skills:** `abap-development` · `abap-testing-quality` · `cds-development` · `rap-development` · `abap-debugging` · `abap-runtime-analysis` · `rap-service-delivery` · `sap-standard-api-analysis` · `clean-core-extensibility` · `sap-sdlc-orchestration` · `sap-transport-release` · `hana-cloud-inspection` · `hana-cloud-native-development` · `hana-cloud-validation`
 
-Agents and skills install for the harnesses you pick during global installation: a multi-select offers GitHub Copilot and Claude Code pre-checked, plus OpenAI Codex, Cursor, Gemini CLI, opencode, and Pi Coding Agent. In non-interactive installs they are installed for GitHub Copilot only. Repository-scoped installation instructions appear below.
+Agents and skills install for the harnesses you pick during global installation: a multi-select offers GitHub Copilot and Claude Code pre-checked, plus OpenAI Codex, Cursor, Gemini CLI, opencode, and Pi Coding Agent. In non-interactive installs they are installed for GitHub Copilot only; run `sap-ai-dev --setup` afterwards to configure destinations or local SAP GUI systems. Repository-scoped installation instructions appear below.
 
 ## ✨ Your SAP development cockpit, inside your AI assistant
 
-`sap-ai-dev-toolkit` installs `sap-ai-dev`, discovers your BAS destinations, and exposes a curated SAP development toolset through MCP. Instead of manually switching between chat, terminal commands, repository searches, ADT screens, and SAP checks, describe the outcome you want and let the appropriate bundled agent coordinate the available tools.
+`sap-ai-dev-toolkit` installs `sap-ai-dev`, discovers your BAS destinations or local SAP GUI systems, and exposes a curated SAP development toolset through MCP. Instead of manually switching between chat, terminal commands, repository searches, ADT screens, and SAP checks, describe the outcome you want and let the appropriate bundled agent coordinate the available tools.
 
 <p align="center"><strong>💬 Request → 🔎 Inspect → 🧠 Reason → 🧑‍💻 Implement → 🧪 Verify → 📋 Report</strong></p>
 
@@ -94,7 +94,7 @@ The workflow covers ABAP, CDS, RAP, repository analysis, table and query access,
 | | Feature | What it gives you |
 | --- | --- | --- |
 | 🤖 | **AI-driven ABAP development** | Describe the outcome; a task-fit agent coordinates inspection, implementation, validation, and a clear report. |
-| 🧭 | **Destination-aware by design** | Discover BAS destinations and connect each MCP server to one selected SAP system. |
+| 🧭 | **Destination-aware by design** | Discover BAS destinations or local SAP GUI systems and connect each MCP server to one selected SAP system. |
 | 🔎 | **Understand before editing** | Trace source, callers, definitions, package contents, dependencies, and CDS impact in one workflow. |
 | 🧩 | **CDS + RAP development** | Explore models and dependencies, then build RAP business objects and services with system context. |
 | 🗃️ | **Ground decisions in SAP data** | Inspect DDIC structures, read table contents, and run controlled ABAP SQL queries. |
@@ -242,11 +242,17 @@ 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:
+Install globally from SAP Business Application Studio or from a local workstation with SAP GUI installed, then run setup explicitly for your environment:
 
-```sh
-npm install --global sap-ai-dev-toolkit
-```
+| 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 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`. |
 
 If you previously installed the old package, remove it first because the legacy `bas-vsp-mcp` command is no longer shipped:
 
@@ -272,7 +278,7 @@ The installer handles VSP provisioning automatically:
 
 Setup detects where it is running. With `H2O_URL` set, it treats the environment as SAP Business Application Studio and opens a checkbox picker for BAS destinations, with no destinations selected by default. Use **Space** to choose destinations and **Enter** to confirm. Press **a** to toggle all destinations (select all if any are unchecked; otherwise clear the selection). Confirming with none selected removes this add-on's managed MCP entries. When the `cf` CLI 8.18 or newer is authenticated to a targeted space, setup first offers an optional import from that space's Destination service; type **y** then **Enter** to include it, or press **Enter** to skip. Accepted CF and BAS destinations appear together in the picker.
 
-Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint or a complete ABAP client catalog, so setup asks for the SAP client or comma-separated clients to configure for each selected system (for example `100,200`), proposes an ADT URL from the SAP GUI host and instance when it can, and asks you to confirm or edit that value. Multiple entered clients create separate isolated MCP entries, one per system/client pair. When the ADT URL uses an IP address, setup automatically inspects the SAP HTTPS certificate, extracts DNS subjectAltName entries, and offers to enable secure TLS self-healing with a simple yes/no confirmation; you do not need to type certificate names. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup can instead write an experimental `SAP_AUTH_MODE=windows-sso` entry without username/password prompts; this requires the ADT endpoint to support HTTP Negotiate/SPNEGO. Runtime uses the bundled Windows Negotiate helper by default, or a trusted custom helper configured with `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER`. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config.
+Without `H2O_URL`, interactive setup looks for local SAP GUI system configuration on macOS and Windows (for example SAP GUI landscape XML and `saplogon.ini`). SAP GUI landscape files describe SAP GUI/DIAG connectivity, not the ADT HTTP(S) endpoint or a complete ABAP client catalog, so setup asks for the SAP client or comma-separated clients to configure for each selected system (for example `100,200`), proposes an ADT URL from the SAP GUI host and instance when it can, and asks you to confirm or edit that value. Multiple entered clients create separate isolated MCP entries, one per system/client pair. When the ADT URL uses an IP address, setup automatically inspects the SAP HTTPS certificate, extracts DNS subjectAltName entries, and offers to enable secure TLS self-healing with a simple yes/no confirmation; you do not need to type certificate names. The generated MCP entry uses VS Code input prompts for the SAP user and password at server start; raw SAP credentials are not stored in `mcp.json`. On Windows, setup can instead write an experimental `SAP_AUTH_MODE=windows-sso` entry without username/password prompts; this requires the ADT endpoint to support HTTP Negotiate/SPNEGO. Runtime uses the bundled Windows Negotiate helper by default, or a trusted custom helper configured with `SAP_AI_DEV_TOOLKIT_NEGOTIATE_HELPER`. npm may run its install hook without an interactive terminal, even when the shell is interactive; in that case, destination selection is skipped without changing MCP config, and you should run `sap-ai-dev --setup` afterwards.
 
 ### 🖥️ Local machine SAP GUI support
 
@@ -302,9 +308,9 @@ sap-ai-dev --setup
 5. Choose password or Windows SSO when the prompt is available.
 6. Start each generated MCP server from VS Code's **MCP: List Servers** command.
 
-The same postinstall offers the bundled agents and skills for several AI coding harnesses in a checkbox picker. **GitHub Copilot** and **Claude Code** start pre-checked, so pressing **Enter** alone installs both; **Space** selects or deselects a harness, **a** toggles all seven, and confirming with none selected skips the step without changing files. When destination MCP setup succeeds, the generated managed MCP servers are also mirrored into selected harnesses that have a stable user-level JSON MCP configuration (Claude Code, Cursor, Gemini CLI, and Pi Coding Agent). GitHub Copilot continues to use the BAS/VS Code MCP configuration written during destination setup. With no interactive terminal, the assets are installed for GitHub Copilot only; set `SAP_AI_DEV_TOOLKIT_HARNESSES` to a comma-separated list of harness ids (`github-copilot`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `opencode`, `pi-coding-agent`) to choose non-interactively.
+The same postinstall offers the bundled agents and skills for several AI coding harnesses in a checkbox picker. **GitHub Copilot** and **Claude Code** start pre-checked, so pressing **Enter** alone installs both; **Space** selects or deselects a harness, **a** toggles all seven, and confirming with none selected skips the step without changing files. When MCP setup succeeds, the generated managed MCP servers are also mirrored into selected harnesses that have a stable user-level JSON MCP configuration (Claude Code, Cursor, Gemini CLI, and Pi Coding Agent). GitHub Copilot continues to use the VS Code/BAS MCP configuration written during setup. With no interactive terminal, the assets are installed for GitHub Copilot only; set `SAP_AI_DEV_TOOLKIT_HARNESSES` to a comma-separated list of harness ids (`github-copilot`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `opencode`, `pi-coding-agent`) to choose non-interactively.
 
-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 BAS terminal after installation.
+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.
 
@@ -373,13 +379,13 @@ The package includes five user-invocable custom agents (**SAP Solution Architect
 | 🧱 | `hana-cloud-native-development` | Create CAP CDS or required native HDI source artifacts while avoiding duplicate models. |
 | ✅ | `hana-cloud-validation` | Build locally, review deployment risks, and hand off deployment to the user. |
 
-### 📥 Install for your BAS user
+### 📥 Install agents and skills for your user
 
-After destination setup, the installer prints a 🤖 notice and a checkbox picker asking which AI coding harnesses should receive the bundled agents and skills. **Space** selects or deselects, **a** toggles all, **Enter** confirms. **GitHub Copilot** and **Claude Code** are pre-checked, so pressing **Enter** without changes installs both; confirming with none selected skips the step and leaves your files unchanged.
+During npm postinstall, after the destination or local SAP GUI setup step, the installer prints a 🤖 notice and a checkbox picker asking which AI coding harnesses should receive the bundled agents and skills. **Space** selects or deselects, **a** toggles all, **Enter** confirms. **GitHub Copilot** and **Claude Code** are pre-checked, so pressing **Enter** without changes installs both; confirming with none selected skips the step and leaves your files unchanged.
 
 | Harness | Skills land in | Agents land in | MCP auto-wiring |
 | --- | --- | --- | --- |
-| GitHub Copilot | `$HOME/.copilot/skills/` | `$HOME/.copilot/agents/*.agent.md` | Uses the BAS/VS Code `mcp.json` written by destination setup |
+| GitHub Copilot | `$HOME/.copilot/skills/` | `$HOME/.copilot/agents/*.agent.md` | Uses the VS Code/BAS `mcp.json` written by setup |
 | Claude Code | `$HOME/.claude/skills/` | `$HOME/.claude/agents/<id>.md` (frontmatter reduced to `name` and `description`) | `$HOME/.claude.json` |
 | OpenAI Codex | `$HOME/.agents/skills/` | — | Not changed automatically |
 | Cursor | `$HOME/.cursor/skills/` | — | `$HOME/.cursor/mcp.json` |
@@ -391,13 +397,13 @@ All 14 skills use the portable `SKILL.md` format and are installed verbatim. The
 
 MCP auto-wiring preserves unrelated servers in each harness config and replaces only entries previously managed by `sap-ai-dev-toolkit`. Generated entries carry `SAP_AI_DEV_TOOLKIT_MANAGED=true` in their server environment so future reinstalls can reconcile them without touching user-owned MCP servers.
 
-These user-level customizations are available across workspaces opened by the same BAS user in the same dev space. The harness must be available in BAS and may need a window reload to discover new files. A non-interactive install skips the picker and installs for GitHub Copilot only; override with `SAP_AI_DEV_TOOLKIT_HARNESSES` (comma-separated harness ids). `npm install --ignore-scripts` skips the postinstall wizard entirely.
+These user-level customizations are available across workspaces opened by the same OS user (or the same BAS user in a dev space). The harness may need a window reload to discover new files. A non-interactive install skips the picker and installs for GitHub Copilot only; override with `SAP_AI_DEV_TOOLKIT_HARNESSES` (comma-separated harness ids). `npm install --ignore-scripts` skips the postinstall wizard entirely.
 
 On reinstall or package upgrade, unchanged add-on-managed files are updated per harness. Existing customizations and files edited since the previous install are preserved; postinstall reports paths that need manual review instead of overwriting them.
 
 ### 🗂️ Add the agents and skills to a repository
 
-To commit repository-scoped customizations, copy the packaged files from the BAS workspace root without overwriting existing files:
+To commit repository-scoped customizations, copy the packaged files from the installed package without overwriting existing files:
 
 ```sh
 ADDON_ROOT="$(npm root -g)/sap-ai-dev-toolkit"
@@ -417,7 +423,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 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; add `--npx` 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.
 
@@ -522,9 +528,9 @@ The file must be strict JSON with an object-valued `servers` property. Existing
 
 With `H2O_URL` set, the normal command starts the MCP proxy. Each generated entry supplies one `SAP_AI_DEV_TOOLKIT_DESTINATION`, so each server stays in its own lane and exposes only its selected SAP system.
 
-The proxy exposes a curated subset of VSP tools, plus local `LintABAP`, destination-scoped workflow tools, and the convenience `GetApplicationLog` mapping when the VSP SAP router is available. Hidden VSP tools remain available only behind local workflow chaining where required; they are not advertised or directly callable through the proxy. Direct VSP invocation remains unchanged.
+The proxy exposes a curated subset of VSP tools, plus local `LintABAP`, destination-scoped workflow tools, and the convenience `GetApplicationLog` mapping when the VSP SAP router is available. Hidden VSP tools remain available only behind local workflow chaining where required; they are not advertised or directly callable through the proxy. Direct VSP invocation remains available outside BAS when you pass an explicit VSP argument.
 
-Without `H2O_URL`, the command passes arguments directly to the installed VSP binary—no BAS proxy detour.
+Without `H2O_URL`, generated local SAP GUI entries start a destination-scoped local MCP server. In an interactive local terminal with no arguments, `sap-ai-dev` starts local setup. Other non-setup arguments are passed directly to the installed VSP binary—no BAS proxy detour.
 
 ### 🔄 How an MCP tool call reaches SAP
 
@@ -678,7 +684,7 @@ The proxy starts VSP with `--enable-transports` and omits `--transport-read-only
 - `messages: true` adds BALDAT details and T100 message text; otherwise, the tool returns log headers only.
 - The proxy maps this convenience tool to the single upstream `SAP(action="analyze", type="application_log")` operation. The general-purpose `SAP` router itself is hidden from direct calls.
 
-The proxy intentionally does not expose the full child VSP process. Object deletion, broad trace surfaces, arbitrary SAP router/RFC calls, debugger helper/delete-breakpoint routes, and transport release/delete tools are hidden from direct MCP calls. The curated debugger tools (`SetBreakpoint`, `GetBreakpoints`, `DebuggerAttach`, `DebuggerGetStack`, `DebuggerGetVariables`, `DebuggerStep`, and `DebuggerDetach`) remain available when VSP and the target system expose them. Direct VSP invocation without `H2O_URL` retains the VSP binary's own tool surface.
+The proxy intentionally does not expose the full child VSP process. Object deletion, broad trace surfaces, arbitrary SAP router/RFC calls, debugger helper/delete-breakpoint routes, and transport release/delete tools are hidden from direct MCP calls. The curated debugger tools (`SetBreakpoint`, `GetBreakpoints`, `DebuggerAttach`, `DebuggerGetStack`, `DebuggerGetVariables`, `DebuggerStep`, and `DebuggerDetach`) remain available when VSP and the target system expose them. Direct VSP invocation without `H2O_URL` retains the VSP binary's own tool surface; in an interactive local terminal, use an explicit VSP argument because plain `sap-ai-dev` starts local setup.
 
 ### 🚀 Ready to put the tools to work from chat?
 
@@ -732,9 +738,9 @@ The MCP client discovers the schemas; callers do not need to memorize every argu
 | What to inspect | How |
 | --- | --- |
 | Add-on command options | `sap-ai-dev --help` |
-| BAS destinations and probe status | `sap-ai-dev --list-destinations --json` |
+| BAS destinations and probe status | `sap-ai-dev --list-destinations --json` (BAS only) |
 | Destination availability only | `sap-ai-dev --check` |
-| Generated server names and destination mapping | **MCP: Open User Configuration**; look for lowercase slug entries (for example `demo-abap`) whose `SAP_AI_DEV_TOOLKIT_DESTINATION` names the BAS destination. |
+| Generated server names and destination mapping | **MCP: Open User Configuration**; look for lowercase slug entries (for example `demo-abap`) whose `SAP_AI_DEV_TOOLKIT_DESTINATION` names the BAS destination or local SAP GUI system. |
 | Running server | **MCP: List Servers**; select the server and choose **Start Server**. |
 | Tools and exact schemas | Expand that server in the Chat tools picker. The MCP host requests `tools/list`, whose entries include `name`, `description`, and `inputSchema`; the agent should call those tools through chat, not reproduce the protocol in a terminal. |
 | Runtime and tool-call logs | Select the MCP server in the Output view. Startup, call lifecycle, and child stderr logs are written to stderr; child MCP log notifications are forwarded to the client. Tool arguments and result contents are not logged. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-ai-dev-toolkit",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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

@@ -18,7 +18,8 @@ const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
 const runtimeEnv = withBrandedEnvironment(process.env);
 
-function hasFlag(name) { return process.argv.slice(2).includes(name); }
+function args() { return process.argv.slice(2); }
+function hasFlag(name) { return args().includes(name); }
 function json(value) { process.stdout.write(`${JSON.stringify(value)}\n`); }
 // Timestamped stderr lines so MCP server output shows when each event
 // happened, not just that it did.
@@ -28,7 +29,7 @@ function usage() {
   return [
     'Usage: sap-ai-dev [options]',
     '',
-    'With H2O_URL set, starts the SAP AI Dev Toolkit stdio server for selected BAS destinations; with local SAP GUI setup, starts the selected local ADT system.',
+    'With H2O_URL set, starts the SAP AI Dev Toolkit stdio server for selected BAS destinations; with local SAP GUI setup, starts the selected local ADT system. With no BAS environment and no options in an interactive terminal, starts local setup.',
     'Options:',
     '  --setup                  Configure generated BAS MCP servers',
     '  --tools                  Also offer full-stack SAP companion MCP servers (use with --setup)',
@@ -294,6 +295,11 @@ async function main() {
   }
 
   if (!runtimeEnv.H2O_URL) {
+    if (args().length === 0 && process.stdin.isTTY && process.stdout.isTTY) {
+      console.error('sap-ai-dev: no BAS environment detected; starting local interactive setup. Use --help for other commands.');
+      await runSetup();
+      return;
+    }
     const binary = await binaryOrError();
     const child = spawn(binary, process.argv.slice(2), { env: runtimeEnv, stdio: 'inherit' });
     process.once('SIGINT', () => child.kill('SIGINT'));

package/src/local-sap-gui.mjs

@@ -1,7 +1,12 @@
 import { platform, homedir } from 'node:os';
-import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { basename, dirname, extname, join } from 'node:path';
 import { readdir, readFile, stat } from 'node:fs/promises';
 
+const execFileAsync = promisify(execFile);
+
 function text(value) { return value == null ? '' : String(value).trim(); }
 function decodeXml(value) {
   return text(value)
@@ -18,25 +23,88 @@ async function exists(path) {
 }
 
 function unique(values) {
-  return [...new Set(values.filter(Boolean))];
+  const seen = new Set();
+  return values.map(pathFromEnv).filter(Boolean).filter(value => {
+    const key = String(value).toLowerCase();
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function pathFromEnv(value) {
+  const candidate = text(value);
+  if (!candidate) return '';
+  if (/^file:\/\//i.test(candidate)) {
+    try { return fileURLToPath(candidate); } catch { return candidate.replace(/^file:\/\/\/?/i, ''); }
+  }
+  return candidate;
+}
+
+const WINDOWS_LANDSCAPE_FILES = [
+  'SAPUILandscape.xml',
+  'SAPUILandscapeGlobal.xml',
+  'SAPGUILandscape.xml',
+  'SAPGUILandscapeGlobal.xml',
+  'SAPLogonTree.xml',
+  'SAPLogonTreeGlobal.xml',
+  'saplogon.ini'
+];
+
+const WINDOWS_EXPLICIT_PATH_ENV = [
+  'SAP_AI_DEV_SAP_GUI_LANDSCAPE',
+  'SAP_AI_DEV_SAP_GUI_CONFIG',
+  'SAPUILANDSCAPE',
+  'SAPGUI_LANDSCAPE',
+  'SAPLOGON_LSXML_FILE',
+  'SAPLOGON_INI_FILE'
+];
+
+function addWindowsSapGuiFiles(candidates, directory) {
+  if (!directory) return;
+  for (const name of WINDOWS_LANDSCAPE_FILES) candidates.push(join(directory, name));
+}
+
+function addSapGuiJavaFiles(candidates, directory) {
+  if (!directory) return;
+  candidates.push(join(directory, 'connections'));
+  addWindowsSapGuiFiles(candidates, directory);
 }
 
 export function sapGuiLandscapeCandidates(env = process.env) {
   const home = env.HOME || env.USERPROFILE || homedir();
-  const appData = env.APPDATA || (env.USERPROFILE ? join(env.USERPROFILE, 'AppData', 'Roaming') : '');
-  const candidates = [];
-  if (platform() === 'win32' || appData) {
+  const userProfile = env.USERPROFILE || home;
+  const appData = env.APPDATA || (userProfile ? join(userProfile, 'AppData', 'Roaming') : '');
+  const localAppData = env.LOCALAPPDATA || (userProfile ? join(userProfile, 'AppData', 'Local') : '');
+  const programData = env.PROGRAMDATA || (platform() === 'win32' ? 'C:\\ProgramData' : '');
+  const publicProfile = env.PUBLIC || (platform() === 'win32' ? 'C:\\Users\\Public' : '');
+  const windir = env.WINDIR || env.SystemRoot || (platform() === 'win32' ? 'C:\\Windows' : '');
+  const candidates = WINDOWS_EXPLICIT_PATH_ENV.map(name => env[name]);
+  if (platform() === 'win32' || appData || localAppData || programData) {
+    for (const base of [appData, localAppData, programData, publicProfile]) {
+      if (!base) continue;
+      addWindowsSapGuiFiles(candidates, join(base, 'SAP', 'Common'));
+      addWindowsSapGuiFiles(candidates, join(base, 'SAP'));
+    }
     candidates.push(
-      join(appData || '', 'SAP', 'Common', 'SAPUILandscape.xml'),
-      join(appData || '', 'SAP', 'Common', 'SAPUILandscapeGlobal.xml'),
-      join(appData || '', 'SAP', 'Common', 'saplogon.ini')
+      join(windir || '', 'saplogon.ini'),
+      join(windir || '', 'SAPLogon.ini'),
+      join(userProfile || '', 'saplogon.ini'),
+      join(userProfile || '', 'SAPLogon.ini')
     );
+    addSapGuiJavaFiles(candidates, join(userProfile || '', '.SAPGUI'));
+    addSapGuiJavaFiles(candidates, join(appData || '', 'SAPGUI'));
+    addSapGuiJavaFiles(candidates, join(localAppData || '', 'SAPGUI'));
+    if (env.ProgramFiles) addWindowsSapGuiFiles(candidates, join(env.ProgramFiles, 'SAP', 'FrontEnd', 'SAPgui'));
+    if (env['ProgramFiles(x86)']) addWindowsSapGuiFiles(candidates, join(env['ProgramFiles(x86)'], 'SAP', 'FrontEnd', 'SAPgui'));
   }
   candidates.push(
     join(home, 'Library', 'Preferences', 'SAP', 'SAPGUILandscape.xml'),
     join(home, 'Library', 'Preferences', 'SAP', 'SAPUILandscape.xml'),
     join(home, 'Library', 'Preferences', 'SAP', 'connections'),
-    join(home, '.SAPGUI', 'SAPGUILandscape.xml')
+    join(home, '.SAPGUI', 'SAPGUILandscape.xml'),
+    join(home, '.SAPGUI', 'SAPUILandscape.xml'),
+    join(home, '.SAPGUI', 'connections')
   );
   return unique(candidates);
 }
@@ -162,6 +230,113 @@ async function readGuiFile(path) {
   return bytes.toString('utf8').replace(/^\uFEFF/, '');
 }
 
+function sapGuiSearchRoots(env = process.env) {
+  const home = env.HOME || env.USERPROFILE || homedir();
+  const userProfile = env.USERPROFILE || home;
+  return unique([
+    env.APPDATA && join(env.APPDATA, 'SAP'),
+    env.APPDATA && join(env.APPDATA, 'SAPGUI'),
+    userProfile && join(userProfile, 'AppData', 'Roaming', 'SAP'),
+    userProfile && join(userProfile, 'AppData', 'Roaming', 'SAPGUI'),
+    env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'SAP'),
+    env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'SAPGUI'),
+    userProfile && join(userProfile, 'AppData', 'Local', 'SAP'),
+    userProfile && join(userProfile, 'AppData', 'Local', 'SAPGUI'),
+    env.PROGRAMDATA && join(env.PROGRAMDATA, 'SAP'),
+    env.PUBLIC && join(env.PUBLIC, 'SAP'),
+    userProfile && join(userProfile, '.SAPGUI'),
+    home && join(home, 'Library', 'Preferences', 'SAP'),
+    home && join(home, '.SAPGUI')
+  ]);
+}
+
+async function findSapGuiFilesUnder(root, { maxDepth = 4, maxEntries = 500 } = {}) {
+  const wanted = new Set(WINDOWS_LANDSCAPE_FILES.map(value => value.toLowerCase()).concat(['connections']));
+  const found = [];
+  let visited = 0;
+  async function walk(directory, depth) {
+    if (depth < 0 || visited >= maxEntries) return;
+    let entries;
+    try { entries = await readdir(directory, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (++visited > maxEntries) return;
+      const child = join(directory, entry.name);
+      if (entry.isFile() && wanted.has(basename(entry.name).toLowerCase())) found.push(child);
+      else if (entry.isDirectory()) {
+        if (basename(entry.name).toLowerCase() === 'connections') found.push(child);
+        await walk(child, depth - 1);
+      }
+    }
+  }
+  await walk(root, maxDepth);
+  return found;
+}
+
+const SAP_GUI_REGISTRY_ROOTS = [
+  'HKCU\\Software\\SAP\\SAPLogon',
+  'HKCU\\Software\\SAP\\SAPLogon\\Options',
+  'HKCU\\Software\\WOW6432Node\\SAP\\SAPLogon',
+  'HKCU\\Software\\WOW6432Node\\SAP\\SAPLogon\\Options',
+  'HKLM\\Software\\SAP\\SAPLogon',
+  'HKLM\\Software\\SAP\\SAPLogon\\Options',
+  'HKLM\\Software\\WOW6432Node\\SAP\\SAPLogon',
+  'HKLM\\Software\\WOW6432Node\\SAP\\SAPLogon\\Options'
+];
+
+function registryPathCandidates(value) {
+  const raw = pathFromEnv(value);
+  if (!raw) return [];
+  const lower = raw.toLowerCase();
+  if (/\.(?:xml|ini)$/i.test(lower)) return [raw];
+  if (/\\|\//.test(raw) && !extname(raw)) {
+    const result = [];
+    addWindowsSapGuiFiles(result, raw);
+    result.push(join(raw, 'connections'));
+    return result;
+  }
+  if (/\.(?:xml|ini)(?:\s|$)/i.test(lower)) return [raw.split(/\s+/)[0]];
+  return [];
+}
+
+async function windowsRegistrySapGuiCandidates(env = process.env) {
+  if (platform() !== 'win32') return [];
+  const candidates = [];
+  for (const root of SAP_GUI_REGISTRY_ROOTS) {
+    try {
+      const { stdout } = await execFileAsync('reg.exe', ['query', root, '/s'], { windowsHide: true, timeout: 2000, maxBuffer: 256 * 1024 });
+      for (const line of stdout.split(/\r?\n/)) {
+        const match = line.match(/^\s*\S+\s+REG_(?:SZ|EXPAND_SZ)\s+(.+?)\s*$/i);
+        if (!match) continue;
+        candidates.push(...registryPathCandidates(match[1].replace(/%([^%]+)%/g, (_, name) => env[name] || env[name.toUpperCase()] || `%${name}%`)));
+      }
+    } catch {
+      // Registry access can be blocked by policy or absent on non-standard installs.
+    }
+  }
+  return unique(candidates);
+}
+
+async function selfHealingSapGuiCandidates(env, candidates) {
+  const expanded = [...candidates, ...await windowsRegistrySapGuiCandidates(env)];
+  for (const root of sapGuiSearchRoots(env)) {
+    expanded.push(...await findSapGuiFilesUnder(root));
+  }
+  return unique(expanded);
+}
+
+function broadSapGuiSearchRoots(env = process.env) {
+  const home = env.HOME || env.USERPROFILE || homedir();
+  return unique([home, env.USERPROFILE, env.APPDATA, env.LOCALAPPDATA, env.PROGRAMDATA, env.PUBLIC]);
+}
+
+async function broadSelfHealingSapGuiCandidates(env) {
+  const expanded = [];
+  for (const root of broadSapGuiSearchRoots(env)) {
+    expanded.push(...await findSapGuiFilesUnder(root, { maxDepth: 6, maxEntries: 5000 }));
+  }
+  return unique(expanded);
+}
+
 async function parseConnectionsFile(path) {
   const content = await readGuiFile(path);
   if (content.includes('<')) return parseLandscapeXml(content, path);
@@ -172,9 +347,9 @@ async function parseConnectionsFile(path) {
   }).filter(Boolean);
 }
 
-export async function discoverSapGuiSystems({ env = process.env, paths = sapGuiLandscapeCandidates(env) } = {}) {
+async function parseSapGuiCandidatePaths(candidatePaths) {
   const systems = [];
-  for (const path of unique(paths)) {
+  for (const path of unique(candidatePaths)) {
     if (!path) continue;
     try {
       if (!await exists(path)) continue;
@@ -197,6 +372,13 @@ export async function discoverSapGuiSystems({ env = process.env, paths = sapGuiL
       // Ignore unreadable or unfamiliar SAP GUI files; discovery is best-effort.
     }
   }
+  return systems;
+}
+
+export async function discoverSapGuiSystems({ env = process.env, paths } = {}) {
+  const candidatePaths = paths ? unique(paths) : await selfHealingSapGuiCandidates(env, sapGuiLandscapeCandidates(env));
+  let systems = await parseSapGuiCandidatePaths(candidatePaths);
+  if (!systems.length && !paths) systems = await parseSapGuiCandidatePaths(await broadSelfHealingSapGuiCandidates(env));
   const seen = new Set();
   return systems.filter(system => {
     const key = `${system.name}\0${system.host}\0${system.systemId}\0${system.instance}\0${system.client}`.toLowerCase();

package/src/setup.mjs

@@ -15,6 +15,41 @@ function print(output, message) {
   output.write(`${message}\n`);
 }
 
+function startSapGuiLandscapeAnimation(output, env = process.env) {
+  if (!output?.isTTY || !Number.isFinite(output?.columns)) return () => {};
+  if (env.TERM === 'dumb' || env.CI || env.SAP_AI_DEV_TOOLKIT_DISABLE_SCAN_ANIMATION === 'true') return () => {};
+  const frames = [
+    '=^.^=                         ~(o:>',
+    '  =^.^=                    ~(o:>',
+    '     =^.^=              ~(o:>',
+    '        =^.^=        ~(o:>',
+    '           =^.^=  ~(o:>',
+    '             =^.^= caught it!'
+  ];
+  let index = 0;
+  let active = false;
+  const render = () => {
+    active = true;
+    const columns = Math.max(20, output.columns || 80);
+    const frame = frames[index % frames.length];
+    index += 1;
+    const line = `Scanning SAP GUI landscapes ${frame}`.slice(0, Math.max(1, columns - 1));
+    output.write(`\r\u001b[2K${line}`);
+  };
+  const delay = setTimeout(() => {
+    render();
+    interval = setInterval(render, 160);
+    if (typeof interval.unref === 'function') interval.unref();
+  }, 150);
+  if (typeof delay.unref === 'function') delay.unref();
+  let interval;
+  return () => {
+    clearTimeout(delay);
+    if (interval) clearInterval(interval);
+    if (active) output.write('\r\u001b[2K');
+  };
+}
+
 function windowsSsoSetupAvailable(env = process.env) {
   return platform() === 'win32' || env.SAP_AI_DEV_TOOLKIT_ENABLE_WINDOWS_SSO_SETUP === 'true';
 }
@@ -214,10 +249,13 @@ export async function runSetup({
     destinations = basDestinations.map(safeBasDestination);
   } else {
     let localSystems;
+    const stopScanAnimation = startSapGuiLandscapeAnimation(output, env);
     try {
       localSystems = await discoverLocalSapGui({ env });
     } catch (error) {
       throw new Error(`SAP GUI discovery failed: ${error.message}`);
+    } finally {
+      stopScanAnimation();
     }
     destinations = localSystems.map(safeLocalSapGuiDestination);
   }