sap-ai-dev-toolkit 0.9.3 → 0.9.4

package/README.md

@@ -325,7 +325,7 @@ Typical local setup flow:
 sap-ai-dev --setup
 ```
 
-1. Select the discovered SAP GUI system with **Space** and confirm with **Enter**.
+1. Select the discovered SAP GUI system with **Space** and confirm with **Enter**. If no SAP GUI entries are found, setup offers the manual entry wizard: enter a system name, ADT URL, client(s), and login mode instead.
 2. Confirm the detected/default SAP client, or enter multiple clients such as `100,200`.
 3. Accept the proposed ADT URL when it is correct, or edit it if your landscape exposes ADT through a different HTTP(S) host/port.
 4. If setup discovers certificate DNS names for an IP-based HTTPS URL, accept the yes/no TLS self-healing prompt.
@@ -352,7 +352,7 @@ To configure without a global install, run the guided setup directly through npm
 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). 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**.
+This lists discovered systems in the same checkbox picker, with nothing selected by default. Use **Space** to choose destinations, **Enter** to confirm, **a** to toggle all (select all if any are unchecked; otherwise clear the selection), and **m** to configure an undiscovered system manually in the manual entry wizard; configured systems join the picker pre-selected. 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:
 
@@ -447,7 +447,9 @@ 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; generated entries fall back to the pinned npx launcher automatically 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, **a** to toggle all (select all if any are unchecked; otherwise clear the selection), and **m** to configure an undiscovered system manually in the manual entry wizard; configured systems join the picker pre-selected. 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.
+
+When nothing is detected — no BAS destinations, no Cloud Foundry imports, or no local SAP GUI entries — setup offers the **manual entry wizard** instead of stopping. The same wizard is available at any point in the destination picker via the **m** shortcut. It asks for a system name, the ADT HTTP(S) base URL (for example `https://myhost.example:44300`), one or more 3-digit SAP clients, and (on Windows) the login mode. You can add several systems in one run; each becomes the same isolated per-system/client MCP server the discovery flows generate, including credential input prompts and TLS self-healing for IP-based HTTPS URLs. Declining the wizard when nothing was detected exits setup without changes; aborting it inside the picker (Ctrl+C) returns to the selection unchanged.
 
 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.
 

package/package.json

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

package/src/bas-discovery.mjs

@@ -17,19 +17,26 @@ function scalar(value) {
 }
 
 function propertiesOf(item) {
+  // Nested property maps (BAS wraps destination attributes in `properties`,
+  // some proxies use `configuration` or a key/value array) only fill gaps:
+  // a nested `Name` — e.g. the Cloud Connector system name `_SIDCLNTOX` —
+  // must never overwrite the real destination name at the top level.
   const result = {};
-  for (const [key, value] of Object.entries(item || {})) result[keyName(key)] = scalar(value);
-  const maps = Object.entries(item || {}).filter(([key]) => ['properties', 'propertymap', 'destinationproperties', 'configuration'].includes(keyName(key))).map(([, value]) => value);
+  const entries = Object.entries(item || {});
+  const maps = entries.filter(([key]) => ['properties', 'propertymap', 'destinationproperties', 'configuration'].includes(keyName(key))).map(([, value]) => value);
   for (const map of maps) {
     if (Array.isArray(map)) {
       for (const entry of map) {
         const key = entry?.key ?? entry?.name ?? entry?.property;
-        if (key != null) result[keyName(key)] = scalar(entry?.value ?? entry?.val);
+        if (key != null && !(keyName(key) in result)) result[keyName(key)] = scalar(entry?.value ?? entry?.val);
       }
     } else if (map && typeof map === 'object') {
-      for (const [key, value] of Object.entries(map)) result[keyName(key)] = scalar(value);
+      for (const [key, value] of Object.entries(map)) {
+        if (!(keyName(key) in result)) result[keyName(key)] = scalar(value);
+      }
     }
   }
+  for (const [key, value] of entries) result[keyName(key)] = scalar(value);
   return result;
 }
 
@@ -42,23 +49,36 @@ function listFromBody(body) {
   if (Array.isArray(body)) return body;
   if (!body || typeof body !== 'object') return null;
   for (const [key, value] of Object.entries(body)) {
-    if (['destinations', 'data'].includes(keyName(key)) && Array.isArray(value)) return value;
+    if (!['destinations', 'destinationlist', 'data', 'items', 'value'].includes(keyName(key))) continue;
+    if (Array.isArray(value)) return value;
+    // Some destination services unwrap records into a name-keyed map
+    // instead of an array; heal the shape so discovery still proceeds.
+    if (value && typeof value === 'object') {
+      const records = Object.entries(value).filter(([, entry]) => entry && typeof entry === 'object').map(([mapName, entry]) => ({ name: mapName, ...entry }));
+      if (records.length) return records;
+    }
   }
   return null;
 }
 
 export function normalizeDestination(item) {
   const values = propertiesOf(item);
-  const name = text(values.name || values.destinationname || values.destname);
+  const name = text(values.name || values.destinationname || values.destname || values.destination || values.sapdestinationname);
   const authentication = text(values.authentication || values.authtype || values.auth);
-  const client = text(values.sapclient || values.client) || '001';
+  const client = text(values.sapclient || values.client || values.mandt) || '001';
   const backendUrl = text(values.url || values.host || values.webideexposedhost);
   const proxyType = text(values.proxytype || values.proxy);
+  // One destination with an unusable name must never abort discovery; the
+  // probe reports `invalid-name` for entries whose url stays null.
+  let url = null;
+  if (name) {
+    try { url = destinationUrl(name); } catch { url = null; }
+  }
   return {
     name,
     authentication: authentication || 'Unknown',
     client,
-    url: name ? destinationUrl(name) : null,
+    url,
     backendUrl: backendUrl || null,
     proxyType: proxyType || null,
     rawKeys: Object.keys(item || {}).map(String)
@@ -67,7 +87,10 @@ export function normalizeDestination(item) {
 
 export function destinationUrl(name) {
   const value = text(name);
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) throw new Error(`Invalid BAS destination name: ${value || '<empty>'}`);
+  // A leading underscore is valid: BAS destination names allow it (Cloud
+  // Connector system names like `_SIDCLNTOX`), and `<name>.dest` resolution
+  // inside a dev space is Host-header matching in the BAS proxy, not DNS.
+  if (!/^[A-Za-z0-9_][A-Za-z0-9._-]*$/.test(value)) throw new Error(`Invalid BAS destination name: ${value || '<empty>'}`);
   return `http://${value}.dest`;
 }
 
@@ -137,7 +160,7 @@ function proxyDispatcher(target, env) {
 
 export async function fetchDestinationList(h2oUrl, options = {}) {
   if (!h2oUrl) throw new Error('H2O_URL is required for BAS destination discovery');
-  const url = `${String(h2oUrl).replace(/\/$/, '')}/api/listDestinations`;
+  const url = `${String(h2oUrl).trim().replace(/\/+$/, '')}/api/listDestinations`;
   const env = options.env || process.env;
   const dispatcher = proxyDispatcher(url, env);
   try {
@@ -147,7 +170,15 @@ export async function fetchDestinationList(h2oUrl, options = {}) {
       ...(dispatcher ? { dispatcher } : {})
     });
     if (!response.ok) throw new Error(`BAS destination discovery failed with HTTP ${response.status}`);
-    return await response.json();
+    // Parse from text so UTF-8 BOMs and text/plain content types from
+    // proxies in front of BAS do not break discovery.
+    const payload = await response.text();
+    try {
+      return JSON.parse(payload.replace(/^\uFEFF/, ''));
+    } catch {
+      const preview = payload.trim().slice(0, 200);
+      throw new Error(`BAS destination discovery returned unparsable JSON${preview ? `: ${preview}` : ''}`);
+    }
   } finally {
     await dispatcher?.close();
   }
@@ -186,7 +217,12 @@ function requestProbe(target, proxyUrl, timeoutMs) {
 }
 
 export async function probeADT(destination, options = {}) {
-  const url = `${destinationUrl(destination.name)}/sap/bc/adt/discovery`;
+  let url;
+  try {
+    url = `${destinationUrl(destination.name)}/sap/bc/adt/discovery`;
+  } catch (error) {
+    return { status: 'invalid-name', available: false, warning: error.message };
+  }
   if (options.skipProbe) return { status: 'skipped', available: true, url };
   try {
     const result = options.probeImpl ? await options.probeImpl(url, options) : await requestProbe(url, options.proxyUrl ?? DEFAULT_PROXY, options.timeoutMs || 5000);
@@ -204,7 +240,13 @@ export async function discoverDestinations(options = {}) {
   const list = listFromBody(body);
   if (!list) throw new Error(`Unrecognized BAS destination response shape; top-level keys: ${Object.keys(body || {}).map(String).join(', ') || '<none>'}`);
   const allow = text(brandedEnvValue(env, 'DESTINATION')).split(',').map(value => value.trim().toLowerCase()).filter(Boolean);
-  const normalized = list.map(normalizeDestination).filter(item => item.name).filter(item => !allow.length || allow.includes(item.name.toLowerCase()));
+  const normalized = list
+    .map(item => {
+      try { return normalizeDestination(item); }
+      catch (error) { return { name: '', probe: { status: 'invalid-name', available: false, warning: error.message } }; }
+    })
+    .filter(item => item.name)
+    .filter(item => !allow.length || allow.includes(item.name.toLowerCase()));
   const brandedProxy = brandedEnvValue(env, 'HTTP_PROXY');
   const configuredProxy = brandedProxy !== undefined ? String(brandedProxy) : (env.HTTP_PROXY ?? env.http_proxy);
   const proxyUrl = configuredProxy !== undefined ? configuredProxy : DEFAULT_PROXY;

package/src/setup.mjs

@@ -112,6 +112,167 @@ async function promptSapClients(destination, { input = stdin, output = stdout }
   return parseSapClientList(answer, fallback);
 }
 
+function validateAdtUrlCandidate(candidate) {
+  if (!candidate) return 'Enter an ADT base URL, for example https://host:44300.';
+  try {
+    const parsed = new URL(candidate);
+    if (!['http:', 'https:'].includes(parsed.protocol)) return 'Use an http:// or https:// URL.';
+    if (parsed.username || parsed.password) return 'Do not embed credentials in the ADT URL; use the login prompts.';
+    if (parsed.search || parsed.hash) return 'Enter an ADT base URL without a query or fragment.';
+    return true;
+  }
+  catch { return 'Enter a valid URL.'; }
+}
+
+function localAuthenticationLabel(authMode) {
+  return ['windows-sso', 'windows-credential-ui', 'windows-sso-basic-fallback'].includes(authMode) ? 'WindowsSSO' : 'Basic';
+}
+
+async function confirmPrompt(message, { input = stdin, output = stdout } = {}) {
+  const answer = await textPrompt({
+    message,
+    placeholder: 'y',
+    required: false,
+    validate: value => /^(?:|y|yes|n|no)$/i.test(String(value || '').trim()) || 'Enter y or n.'
+  }, { input, output });
+  return !/^n(?:o)?$/i.test(String(answer || '').trim());
+}
+
+function buildLocalClientDestination(destination, client, authMode, { multipleClients = false, duplicateSystemName = false } = {}) {
+  const name = localClientDestinationName(destination, client, { multipleClients, duplicateSystemName });
+  const localDestination = { ...destination, name, serverName: name, client };
+  const userInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-user`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+  const passwordInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-password`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+  const credentialInputs = [
+    { id: userInputId, type: 'promptString', description: `SAP user for ${localDestination.name}` },
+    { id: passwordInputId, type: 'promptString', description: `SAP password for ${localDestination.name}`, password: true }
+  ];
+  if (authMode === 'windows-sso') {
+    localDestination.childEnv = { SAP_AUTH_MODE: 'windows-sso' };
+    localDestination.inputs = [];
+  } else if (authMode === 'windows-credential-ui') {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'windows-sso',
+      SAP_AI_DEV_TOOLKIT_WINDOWS_CREDENTIAL_UI: 'true'
+    };
+    localDestination.inputs = [];
+  } else if (authMode === 'windows-sso-basic-fallback') {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'windows-sso',
+      SAP_AUTH_FALLBACK_MODE: 'basic',
+      SAP_USER: `\${input:${userInputId}}`,
+      SAP_PASSWORD: `\${input:${passwordInputId}}`
+    };
+    localDestination.inputs = credentialInputs;
+  } else if (authMode === 'browser-saml') {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'browser-saml',
+      SAP_BROWSER_AUTH: 'true',
+      SAP_SAML_AUTH: 'true'
+    };
+    localDestination.inputs = [];
+  } else if (authMode === 'saml-password') {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'saml-password',
+      SAP_SAML_AUTH: 'true',
+      SAP_SAML_USER: `\${input:${userInputId}}`,
+      SAP_SAML_PASSWORD: `\${input:${passwordInputId}}`
+    };
+    localDestination.inputs = credentialInputs;
+  } else {
+    localDestination.childEnv = {
+      SAP_AUTH_MODE: 'basic',
+      SAP_USER: `\${input:${userInputId}}`,
+      SAP_PASSWORD: `\${input:${passwordInputId}}`
+    };
+    localDestination.inputs = credentialInputs;
+  }
+  return localDestination;
+}
+
+async function maybeConfigureTlsSelfHeal(destination, promptLabel, { input = stdin, output = stdout } = {}) {
+  const parsedAdtUrl = new URL(destination.url);
+  if (parsedAdtUrl.protocol !== 'https:' || !isIP(parsedAdtUrl.hostname)) return;
+  print(output, formatStatus('The ADT URL uses an IP address. Setup will inspect the SAP HTTPS certificate and can enable TLS self-healing automatically; certificate validation remains enabled.', 'warning', output, 'TLS self-heal'));
+  let discoveredNames = [];
+  try { discoveredNames = await discoverCertificateDnsNames(destination.url); }
+  catch { discoveredNames = []; }
+  if (!discoveredNames.length) {
+    print(output, formatStatus('No DNS subjectAltName entries could be read from the SAP HTTPS certificate. TLS self-healing was not configured automatically.', 'warning', output, 'TLS self-heal'));
+    return;
+  }
+  const preview = discoveredNames.slice(0, 5).join(', ');
+  const useDiscovered = await confirmPrompt(`Use discovered certificate DNS name${discoveredNames.length === 1 ? '' : 's'} for ${promptLabel}: ${preview}${discoveredNames.length > 5 ? ', ...' : ''}? (y/Enter=yes, n=no)`, { input, output });
+  if (useDiscovered) {
+    destination.tlsServerNames = discoveredNames;
+    destination.tlsServerName = discoveredNames[0];
+  }
+}
+
+// Manual MCP entry wizard: offered whenever discovery finds nothing to select
+// (no BAS destinations, no Cloud Foundry imports, no SAP GUI entries). It
+// collects the minimal ADT configuration directly from the user and produces
+// the same local destination shape as the SAP GUI flow, so installation,
+// credential inputs, and TLS handling stay identical.
+async function runManualEntryWizard({ env = process.env, input = stdin, output = stdout } = {}) {
+  print(output, '');
+  print(output, colorText('✍️  Manual system entry — skip discovery, add your SAP system directly', 'magenta', output));
+  print(output, colorText('   The ADT URL is the base URL that Eclipse ADT or VS Code ADT tools use, for example https://myhost.example:44300.', 'cyan', output));
+  print(output, colorText('   Setup writes one isolated MCP server per system/client pair, with login prompts and TLS self-healing like every other entry.', 'cyan', output));
+  const expanded = [];
+  const usedNames = new Set();
+  let addAnother = true;
+  while (addAnother) {
+    const name = (await textPrompt({
+      message: 'System name',
+      placeholder: 'S4H sandbox',
+      required: true,
+      validate: value => {
+        const trimmed = String(value || '').trim();
+        if (!trimmed) return 'Enter a name for the system.';
+        if (usedNames.has(trimmed.toLowerCase())) return 'A system with this name was already added; choose another name.';
+        return true;
+      }
+    }, { input, output })).trim();
+    usedNames.add(name.toLowerCase());
+    const url = await textPrompt({
+      message: `ADT URL for ${name}`,
+      placeholder: 'https://host:44300',
+      required: true,
+      validate: validateAdtUrlCandidate
+    }, { input, output });
+    let parsedUrl;
+    try { parsedUrl = new URL(url); }
+    catch { parsedUrl = null; }
+    const destination = {
+      source: 'sap-gui-local',
+      name,
+      serverName: name,
+      url,
+      host: parsedUrl?.hostname || '',
+      client: '001',
+      authentication: 'Basic',
+      authMode: 'basic',
+      proxyType: 'Internet',
+      // Marks wizard-configured systems so the discovery confirmation prompts
+      // (clients, ADT URL, login) skip them when they flow through the
+      // destination picker.
+      configuredManually: true
+    };
+    await maybeConfigureTlsSelfHeal(destination, name, { input, output });
+    const clients = await promptSapClients(destination, { input, output });
+    const authMode = await chooseLocalAuthMode(destination, { input, output, env });
+    destination.authentication = localAuthenticationLabel(authMode);
+    destination.authMode = authMode;
+    for (const client of clients) {
+      expanded.push(buildLocalClientDestination(destination, client, authMode, { multipleClients: clients.length > 1 }));
+    }
+    print(output, formatStatus(`Added ${name} (client${clients.length === 1 ? '' : 's'} ${clients.join(', ')}).`, 'success', output, 'Manual entry'));
+    addAnother = await confirmPrompt('Add another system? (y/Enter=yes, n=no)', { input, output });
+  }
+  return expanded;
+}
+
 function localSystemDiscriminator(destination) {
   return [destination.systemId, destination.host, destination.instance].map(value => String(value || '').trim()).filter(Boolean).join(' ');
 }
@@ -216,6 +377,90 @@ function printConnectionInstructions(output, result) {
 }
 
 
+// Checkbox selection over the discovered destinations plus, outside BAS, the
+// per-system confirmation prompts (clients, ADT URL, TLS self-heal, login).
+async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin, output = stdout, env = process.env } = {}) {
+  const orderedDestinations = [...destinations].sort((left, right) => {
+    const leftRank = left.disabledReason ? 2 : (left.probe?.available === false ? 1 : 0);
+    const rightRank = right.disabledReason ? 2 : (right.probe?.available === false ? 1 : 0);
+    return leftRank - rightRank || String(left.name).localeCompare(String(right.name));
+  });
+  const choices = orderedDestinations.map(destination => {
+    const probe = destination.probe?.status || 'unknown';
+    const source = destination.source === 'cloud-foundry'
+      ? `CF ${destination.cf.destinationInstanceName}`
+      : (destination.source === 'sap-gui-local' ? `SAP GUI ${destination.systemId || destination.host || ''}`.trim() : 'BAS');
+    const disabled = destination.disabledReason;
+    const state = disabled ? 'disabled' : (probe === 'needs-adt-url' ? probe : (destination.probe?.available === false ? `fail:${probe}` : `ok:${probe}`));
+    return {
+      value: destination,
+      name: `${destination.name} (${source}, client ${destination.client}, ${state})`,
+      ...(disabled ? { disabled } : {}),
+      checked: false
+    };
+  });
+  print(output, '');
+  print(output, formatStatus('Choose the destinations to add. Reachable destinations are shown first.', 'step', output, 'Setup'));
+  print(output, '');
+  print(output, colorText('  Space = select/deselect · a = toggle all · m = add a system manually · Enter = confirm.', 'cyan', output));
+  print(output, colorText('  💡 No system listed, or need an extra one? Press m to skip discovery and add any SAP system manually.', 'magenta', output));
+  print(output, '  Nothing selected removes this add-on’s MCP entries.');
+  print(output, '');
+  const addManually = async () => (await runManualEntryWizard({ env, input, output })).map(destination => ({
+    value: destination,
+    name: `${destination.name} (manual, client ${destination.client})`
+  }));
+  let selected = await checkboxPrompt({
+    message: colorText('🧭 Select destinations', 'cyan', output),
+    choices,
+    required: false,
+    shortcuts: { all: 'a' },
+    actions: { m: addManually }
+  }, { input, output });
+
+  if (!isBas && selected.length) {
+    print(output, '');
+    print(output, formatStatus('SAP GUI landscapes do not contain ADT HTTP(S) endpoints or a complete client catalog. Confirm the SAP client(s), ADT URL, and authentication for each selected system.', 'step', output, 'Local SAP GUI'));
+    print(output, '  Enter multiple clients as comma-separated 3-digit values, for example 100,200. Setup creates one isolated MCP server per system/client pair.');
+    if (windowsSsoSetupAvailable(env)) print(output, '  Windows SSO is experimental and only applies to ADT systems configured for HTTP Integrated Authentication (Negotiate/SPNEGO). It uses the current Windows logon session, including smart-card-backed Windows logon; the toolkit cannot prompt for or accept manual bearer/SAML tokens. Username/password remains the default.');
+    const selectedNameCounts = selected.reduce((counts, destination) => {
+      const key = String(destination.name).toLowerCase();
+      counts.set(key, (counts.get(key) || 0) + 1);
+      return counts;
+    }, new Map());
+    const expanded = [];
+    for (const destination of selected) {
+      // Wizard-configured systems are already complete; only discovered SAP
+      // GUI entries need their clients, ADT URL, and login confirmed here.
+      if (destination.configuredManually) {
+        expanded.push(destination);
+        continue;
+      }
+      const duplicateSystemName = (selectedNameCounts.get(String(destination.name).toLowerCase()) || 0) > 1;
+      const discriminator = duplicateSystemName ? localSystemDiscriminator(destination) : '';
+      const promptLabel = discriminator ? `${destination.name} (${discriminator})` : destination.name;
+      const clients = await promptSapClients({ ...destination, name: promptLabel }, { input, output });
+      const fallback = defaultAdtUrl(destination);
+      const url = await textPrompt({
+        message: `ADT URL for ${promptLabel}`,
+        placeholder: fallback || 'https://host:44300',
+        validate: value => validateAdtUrlCandidate(value || fallback),
+        required: false
+      }, { input, output });
+      destination.url = url || fallback;
+      await maybeConfigureTlsSelfHeal(destination, promptLabel, { input, output });
+      const authMode = await chooseLocalAuthMode({ ...destination, name: promptLabel }, { input, output, env });
+      destination.authentication = localAuthenticationLabel(authMode);
+      destination.authMode = authMode;
+      for (const client of clients) {
+        expanded.push(buildLocalClientDestination(destination, client, authMode, { multipleClients: clients.length > 1, duplicateSystemName }));
+      }
+    }
+    selected = expanded;
+  }
+  return selected;
+}
+
 export async function runSetup({
   env = process.env,
   input = stdin,
@@ -237,6 +482,7 @@ export async function runSetup({
     return { skipped: true, reason: 'non-tty' };
   }
   print(output, '');
+  print(output, colorText('💡 Tip: you can skip auto-discovery and add a system manually — press m in the destination picker, or take the wizard offer when nothing is found.', 'magenta', output));
   if (!isBas) print(output, formatStatus('Looking for local SAP GUI system configuration.', 'progress', output, 'Setup'));
 
   let destinations = [];
@@ -349,160 +595,32 @@ export async function runSetup({
     return result.warnings || [];
   };
   const selectable = destinations.filter(destination => !destination.disabledReason);
-  if (!selectable.length) {
-    print(output, formatStatus(isBas ? 'No selectable BAS or Cloud Foundry destinations were found.' : 'No SAP GUI systems were found on this computer.', 'warning', output, 'Setup'));
-    print(output, isBas ? remediation : 'Install SAP GUI and create SAP Logon entries, or set SAP_AI_DEV_MCP_CONFIG and add systems manually. ADT still needs an HTTP(S) URL; SAP GUI files contain DIAG routing only.');
+  const exitWithoutDestinations = async () => {
     await reportWarnings(warnings);
     const cleanupWarnings = await cleanupNewKeysWithoutConfigChange();
     await reportWarnings(cleanupWarnings);
     return { skipped: true, reason: 'no-destinations', warnings: [...warnings, ...cleanupWarnings] };
-  }
-
-  const orderedDestinations = [...destinations].sort((left, right) => {
-    const leftRank = left.disabledReason ? 2 : (left.probe?.available === false ? 1 : 0);
-    const rightRank = right.disabledReason ? 2 : (right.probe?.available === false ? 1 : 0);
-    return leftRank - rightRank || String(left.name).localeCompare(String(right.name));
-  });
-  const choices = orderedDestinations.map(destination => {
-    const probe = destination.probe?.status || 'unknown';
-    const source = destination.source === 'cloud-foundry'
-      ? `CF ${destination.cf.destinationInstanceName}`
-      : (destination.source === 'sap-gui-local' ? `SAP GUI ${destination.systemId || destination.host || ''}`.trim() : 'BAS');
-    const disabled = destination.disabledReason;
-    const state = disabled ? 'disabled' : (probe === 'needs-adt-url' ? probe : (destination.probe?.available === false ? `fail:${probe}` : `ok:${probe}`));
-    return {
-      value: destination,
-      name: `${destination.name} (${source}, client ${destination.client}, ${state})`,
-      ...(disabled ? { disabled } : {}),
-      checked: false
-    };
-  });
-  print(output, '');
-  print(output, formatStatus('Choose the destinations to add. Reachable destinations are shown first.', 'step', output, 'Setup'));
-  print(output, '');
-  print(output, '  Space = select/deselect · a = toggle all · Enter = confirm.');
-  print(output, '  Nothing selected removes this add-on’s MCP entries.');
-  print(output, '');
-  let selected = await checkboxPrompt({
-    message: colorText('🧭 Select destinations', 'cyan', output),
-    choices,
-    required: false,
-    shortcuts: { all: 'a' }
-  }, { input, output });
-
-  if (!isBas && selected.length) {
+  };
+  let selected;
+  if (!selectable.length) {
+    // Nothing was detected — no BAS/CF destinations, or no SAP GUI entries.
+    // Offer the manual MCP entry wizard before giving up.
+    print(output, formatStatus(isBas ? 'No selectable BAS or Cloud Foundry destinations were found.' : 'No SAP GUI systems were found on this computer.', 'warning', output, 'Setup'));
+    print(output, isBas ? remediation : 'Install SAP GUI and create SAP Logon entries, or configure your system manually below. ADT still needs an HTTP(S) URL; SAP GUI files contain DIAG routing only.');
     print(output, '');
-    print(output, formatStatus('SAP GUI landscapes do not contain ADT HTTP(S) endpoints or a complete client catalog. Confirm the SAP client(s), ADT URL, and authentication for each selected system.', 'step', output, 'Local SAP GUI'));
-    print(output, '  Enter multiple clients as comma-separated 3-digit values, for example 100,200. Setup creates one isolated MCP server per system/client pair.');
-    if (windowsSsoSetupAvailable(env)) print(output, '  Windows SSO is experimental and only applies to ADT systems configured for HTTP Integrated Authentication (Negotiate/SPNEGO). It uses the current Windows logon session, including smart-card-backed Windows logon; the toolkit cannot prompt for or accept manual bearer/SAML tokens. Username/password remains the default.');
-    const selectedNameCounts = selected.reduce((counts, destination) => {
-      const key = String(destination.name).toLowerCase();
-      counts.set(key, (counts.get(key) || 0) + 1);
-      return counts;
-    }, new Map());
-    const expanded = [];
-    for (const destination of selected) {
-      const duplicateSystemName = (selectedNameCounts.get(String(destination.name).toLowerCase()) || 0) > 1;
-      const discriminator = duplicateSystemName ? localSystemDiscriminator(destination) : '';
-      const promptLabel = discriminator ? `${destination.name} (${discriminator})` : destination.name;
-      const clients = await promptSapClients({ ...destination, name: promptLabel }, { input, output });
-      const fallback = defaultAdtUrl(destination);
-      const url = await textPrompt({
-        message: `ADT URL for ${promptLabel}`,
-        placeholder: fallback || 'https://host:44300',
-        validate: value => {
-          const candidate = value || fallback;
-          if (!candidate) return 'Enter an ADT base URL, for example https://host:44300.';
-          try {
-            const parsed = new URL(candidate);
-            if (!['http:', 'https:'].includes(parsed.protocol)) return 'Use an http:// or https:// URL.';
-            if (parsed.username || parsed.password) return 'Do not embed credentials in the ADT URL; use the login prompts.';
-            if (parsed.search || parsed.hash) return 'Enter an ADT base URL without a query or fragment.';
-            return true;
-          }
-          catch { return 'Enter a valid URL.'; }
-        },
-        required: false
-      }, { input, output });
-      destination.url = url || fallback;
-      const parsedAdtUrl = new URL(destination.url);
-      if (parsedAdtUrl.protocol === 'https:' && isIP(parsedAdtUrl.hostname)) {
-        print(output, formatStatus('The ADT URL uses an IP address. Setup will inspect the SAP HTTPS certificate and can enable TLS self-healing automatically; certificate validation remains enabled.', 'warning', output, 'TLS self-heal'));
-        let discoveredNames = [];
-        try { discoveredNames = await discoverCertificateDnsNames(destination.url); }
-        catch { discoveredNames = []; }
-        if (discoveredNames.length) {
-          const preview = discoveredNames.slice(0, 5).join(', ');
-          const answer = await textPrompt({
-            message: `Use discovered certificate DNS name${discoveredNames.length === 1 ? '' : 's'} for ${promptLabel}: ${preview}${discoveredNames.length > 5 ? ', ...' : ''}? (y/Enter=yes, n=no)`,
-            placeholder: 'y',
-            required: false,
-            validate: value => /^(?:|y|yes|n|no)$/i.test(String(value || '').trim()) || 'Enter y or n.'
-          }, { input, output });
-          if (!/^n(?:o)?$/i.test(String(answer || '').trim())) {
-            destination.tlsServerNames = discoveredNames;
-            destination.tlsServerName = discoveredNames[0];
-          }
-        } else {
-          print(output, formatStatus('No DNS subjectAltName entries could be read from the SAP HTTPS certificate. TLS self-healing was not configured automatically.', 'warning', output, 'TLS self-heal'));
-        }
-      }
-      const authMode = await chooseLocalAuthMode({ ...destination, name: promptLabel }, { input, output, env });
-      destination.authentication = ['windows-sso', 'windows-credential-ui', 'windows-sso-basic-fallback'].includes(authMode) ? 'WindowsSSO' : 'Basic';
-      destination.authMode = authMode;
-      for (const client of clients) {
-        const name = localClientDestinationName(destination, client, { multipleClients: clients.length > 1, duplicateSystemName });
-        const localDestination = { ...destination, name, serverName: name, client };
-        const userInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-user`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
-        const passwordInputId = `sap-ai-dev-${localDestination.serverName || localDestination.name}-password`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
-        const credentialInputs = [
-          { id: userInputId, type: 'promptString', description: `SAP user for ${localDestination.name}` },
-          { id: passwordInputId, type: 'promptString', description: `SAP password for ${localDestination.name}`, password: true }
-        ];
-        if (authMode === 'windows-sso') {
-          localDestination.childEnv = { SAP_AUTH_MODE: 'windows-sso' };
-          localDestination.inputs = [];
-        } else if (authMode === 'windows-credential-ui') {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'windows-sso',
-            SAP_AI_DEV_TOOLKIT_WINDOWS_CREDENTIAL_UI: 'true'
-          };
-          localDestination.inputs = [];
-        } else if (authMode === 'windows-sso-basic-fallback') {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'windows-sso',
-            SAP_AUTH_FALLBACK_MODE: 'basic',
-            SAP_USER: `\${input:${userInputId}}`,
-            SAP_PASSWORD: `\${input:${passwordInputId}}`
-          };
-          localDestination.inputs = credentialInputs;
-        } else if (authMode === 'browser-saml') {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'browser-saml',
-            SAP_BROWSER_AUTH: 'true',
-            SAP_SAML_AUTH: 'true'
-          };
-          localDestination.inputs = [];
-        } else if (authMode === 'saml-password') {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'saml-password',
-            SAP_SAML_AUTH: 'true',
-            SAP_SAML_USER: `\${input:${userInputId}}`,
-            SAP_SAML_PASSWORD: `\${input:${passwordInputId}}`
-          };
-          localDestination.inputs = credentialInputs;
-        } else {
-          localDestination.childEnv = {
-            SAP_AUTH_MODE: 'basic',
-            SAP_USER: `\${input:${userInputId}}`,
-            SAP_PASSWORD: `\${input:${passwordInputId}}`
-          };
-          localDestination.inputs = credentialInputs;
-        }
-        expanded.push(localDestination);
-      }
-    }
-    selected = expanded;
+    const choice = await selectPrompt({
+      message: colorText('💡 No systems were detected. Configure an SAP system manually?', 'magenta', output),
+      defaultValue: 'manual',
+      choices: [
+        { name: '✍️  Start manual entry wizard (system name, ADT URL, client, login)', value: 'manual', shortcut: 'm' },
+        { name: 'Exit setup without changes', value: 'exit', shortcut: 'e' }
+      ]
+    }, { input, output });
+    if (choice !== 'manual') return await exitWithoutDestinations();
+    selected = await runManualEntryWizard({ env, input, output });
+    if (!selected.length) return await exitWithoutDestinations();
+  } else {
+    selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env });
   }
 
   let sapDevelopmentServers = [];

package/src/terminal-ui.mjs

@@ -213,8 +213,11 @@ export async function selectPrompt({ message, choices, defaultValue } = {}, { in
   });
 }
 
-export async function checkboxPrompt({ message, choices, required = false, shortcuts = { all: 'a' }, validate } = {}, { input = process.stdin, output = process.stdout } = {}) {
-  if (!Array.isArray(choices) || !choices.length) return [];
+export async function checkboxPrompt({ message, choices: initialChoices, required = false, shortcuts = { all: 'a' }, actions = {}, validate } = {}, { input = process.stdin, output = process.stdout } = {}) {
+  if (!Array.isArray(initialChoices) || !initialChoices.length) return [];
+  // Action shortcuts (for example 'm' → manual entry wizard) may append new
+  // choices while the picker is open, so the list itself stays mutable.
+  let choices = initialChoices;
   const selectable = enabledChoices(choices);
   const selected = new Set(choices.flatMap((choice, index) => choice.checked && !choice.disabled ? [index] : []));
   let cursor = firstEnabledIndex(choices);
@@ -261,6 +264,42 @@ export async function checkboxPrompt({ message, choices, required = false, short
   };
 
   return new Promise((resolve, reject) => {
+    const actionShortcuts = new Map(Object.entries(actions).filter(([shortcut, action]) => shortcut && typeof action === 'function'));
+    const actionShortcutFor = (chunk, key = {}) => {
+      if (!actionShortcuts.size) return undefined;
+      const typed = String(chunk ?? '').toLowerCase();
+      if (typed.length === 1 && actionShortcuts.has(typed)) return actionShortcuts.get(typed);
+      if (key.name && actionShortcuts.has(key.name)) return actionShortcuts.get(key.name);
+      return undefined;
+    };
+    // Running an action suspends the picker (listener detached, raw mode off),
+    // lets the action drive its own prompts on the same streams, and appends
+    // the produced items as pre-selected choices before redrawing. An aborted
+    // action (Ctrl+C in a sub-prompt) returns to the picker unchanged instead
+    // of tearing down the whole selection.
+    const runAction = async action => {
+      input.off('keypress', onKeypress);
+      if (typeof input.setRawMode === 'function') input.setRawMode(false);
+      clearRendered();
+      let appended = [];
+      try { appended = await action() || []; }
+      catch { appended = []; }
+      const added = (Array.isArray(appended) ? appended : []).filter(item => item && item.value !== undefined);
+      if (added.length) {
+        for (const item of added) {
+          choices.push({ checked: true, ...item });
+          selected.add(choices.length - 1);
+        }
+        cursor = choices.length - added.length;
+      }
+      if (typeof input.setRawMode === 'function') input.setRawMode(previousRawMode);
+      // Sub-prompts pause the stream on cleanup; resume so keypresses reach
+      // the re-attached picker listener.
+      if (typeof input.resume === 'function') input.resume();
+      input.on('keypress', onKeypress);
+      render();
+    };
+
     const cleanup = () => {
       input.off('keypress', onKeypress);
       if (typeof input.setRawMode === 'function' && previousRawMode !== undefined) input.setRawMode(previousRawMode);
@@ -289,9 +328,12 @@ export async function checkboxPrompt({ message, choices, required = false, short
         if (selected.has(cursor)) selected.delete(cursor);
         else selected.add(cursor);
       } else if (shortcuts?.all && key.name === shortcuts.all) {
-        const allSelected = selectable.every(choice => selected.has(choices.indexOf(choice)));
+        const allSelected = enabledChoices(choices).every(choice => selected.has(choices.indexOf(choice)));
         selected.clear();
-        if (!allSelected) for (const choice of selectable) selected.add(choices.indexOf(choice));
+        if (!allSelected) for (const choice of enabledChoices(choices)) selected.add(choices.indexOf(choice));
+      } else if (actionShortcutFor(_chunk, key)) {
+        void runAction(actionShortcutFor(_chunk, key));
+        return;
       } else if (key.name === 'return' || key.name === 'enter') {
         const values = [...selected].sort((a, b) => a - b).map(index => choices[index].value);
         const validation = typeof validate === 'function' ? validate(values) : true;