sap-ai-dev-toolkit 0.9.7 → 0.9.9

package/package.json

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

package/scripts/postinstall.mjs

@@ -3,6 +3,7 @@ import { closeSync, openSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { installBinary } from '../src/binary.mjs';
+import { detectAdtUrl } from '../src/local-sap-gui.mjs';
 import { runSetup } from '../src/setup.mjs';
 import { installUserAssetsForHarnesses } from '../src/install-user-assets.mjs';
 import { installMcpServersForHarnesses } from '../src/harness-mcp-config.mjs';
@@ -76,8 +77,9 @@ async function withInstallTerminal(action) {
   }
 }
 
-async function runInstallSetup() {
-  return withInstallTerminal(terminal => runSetup({ env: runtimeEnv, ...(terminal || {}) }));
+async function runInstallSetup(binary) {
+  const detect = binary ? target => detectAdtUrl(binary, { ...target, env: runtimeEnv }) : undefined;
+  return withInstallTerminal(terminal => runSetup({ env: runtimeEnv, ...(terminal || {}), detectAdtUrl: detect }));
 }
 
 function harnessSelectionLabels(ids) {
@@ -300,15 +302,16 @@ async function main() {
   // runs `go` (only the repository-only build:vsp script does), so a toolchain
   // download at install time was pure cost. The pinned, checksum-verified VSP
   // binary ships with the package; the download below is the fallback.
+  let binary = brandedEnvValue(runtimeEnv, 'BINARY');
   try {
-    if (brandedEnvValue(runtimeEnv, 'BINARY')) {
+    if (binary) {
       await announce('Using the SAP_AI_DEV_TOOLKIT_BINARY override.', 'info');
     } else {
       // The bundled binary resolves in milliseconds; the animation only
       // appears when provisioning actually takes time (download fallback).
       const stopBinaryProgress = startProgress('Preparing the pinned VSP runtime for this platform', { output: process.stderr, env: runtimeEnv });
       try {
-        await installBinary(pkg, { env: runtimeEnv });
+        binary = await installBinary(pkg, { env: runtimeEnv });
         stopBinaryProgress();
         await announce('Pinned VSP binary installed and ready.', 'success');
       } catch (error) {
@@ -326,7 +329,7 @@ async function main() {
   let setupResult;
   let setupCompleted = false;
   try {
-    setupResult = await runInstallSetup();
+    setupResult = await runInstallSetup(binary);
     setupCompleted = true;
   } catch (error) {
     await announce(`BAS MCP setup failed: ${error.message}`, 'error');

package/src/launcher.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { isIP } from 'node:net';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverDestinations, remediation, slugifyDestination, statusRows } from './bas-discovery.mjs';
-import { detectAdtUrl, discoverSapGuiSystems, hasExplicitPort } from './local-sap-gui.mjs';
-import { binaryTarget, downloadBinary, findBinary } from './binary.mjs';
+import { adtBaseUrl, adtPort, detectAdtUrl, discoverSapGuiSystems, hasExplicitPort, hasPathPrefix } from './local-sap-gui.mjs';
+import { binaryTarget, cacheDirectory, downloadBinary, findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
 import { installMcpConfig, npxMcpLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
 import { runSetup } from './setup.mjs';
@@ -165,7 +166,14 @@ function probeDiagnostic(destination) {
 
 // npx MCP entries run with --ignore-scripts, so postinstall's verified
 // download fallback never ran; a missing or corrupt bundled binary heals here.
-async function binaryOrError() {
+// Port detection and the server share one resolution, so a failed download is not repeated.
+let binaryResolution;
+function binaryOrError() {
+  binaryResolution ??= resolveBinary();
+  return binaryResolution;
+}
+
+async function resolveBinary() {
   const notes = [];
   const found = await findBinary(pkg, { env: runtimeEnv, log: note => notes.push(note) });
   if (found) return found;
@@ -190,6 +198,68 @@ async function detectLocalAdtUrl(target) {
   return detectAdtUrl(await binaryOrError(), { ...target, env: runtimeEnv });
 }
 
+const adtUrlCachePath = () => join(cacheDirectory(runtimeEnv), 'adt-urls.json');
+
+async function cachedAdtUrls() {
+  try { return JSON.parse(await readFile(adtUrlCachePath(), 'utf8')) || {}; }
+  catch { return {}; }
+}
+
+async function rememberAdtUrl(configured, found) {
+  try {
+    const path = adtUrlCachePath();
+    const urls = { ...await cachedAdtUrls(), [configured.toLowerCase()]: found };
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(urls, null, 2)}\n`);
+    await rename(temporary, path);
+  } catch {
+    // The cache only saves a later scan.
+  }
+}
+
+// A named port gets one probe, a scan result is remembered, and every port is
+// swept only when the configuration never named one.
+async function resolveLocalAdtUrl(name, configured, client) {
+  const log = message => logLine(`[sap-ai-dev] ${name}: ${message}`);
+  const detect = target => detectLocalAdtUrl({ client, ...target }).catch(error => ({ url: '', reason: error.message, failed: true }));
+  const explicit = hasExplicitPort(configured);
+  let verdict = { url: '', reason: '' };
+  if (explicit) {
+    verdict = await detect({ url: configured, ports: [adtPort(configured)] });
+    if (verdict.url) return { url: verdict.url, verified: true };
+    log(`ADT did not answer at ${configured}: ${verdict.reason}`);
+    if (verdict.unresolved || verdict.failed) return { url: configured, verified: false, reason: verdict.reason };
+  }
+  const remembered = (await cachedAdtUrls())[configured.toLowerCase()];
+  if (remembered) {
+    const recheck = await detect({ url: remembered, ports: [adtPort(remembered)] });
+    if (recheck.url) {
+      log(`ADT answers at ${recheck.url} (found by an earlier port scan)`);
+      return { url: recheck.url, verified: true };
+    }
+  }
+  const host = new URL(configured).hostname;
+  log(`port scan in progress on ${host} (usual ADT ports)`);
+  verdict = await detect({ url: configured });
+  if (!verdict.url && !explicit && !verdict.unresolved && !verdict.failed) {
+    log(`no ADT port on the usual ports (${verdict.reason}); port scan in progress on every conventional SAP port of ${host} (can take a minute)`);
+    verdict = await detect({ url: configured, exhaustive: true });
+  }
+  if (verdict.url) {
+    log(`port scan finished; ADT answers at ${verdict.url}`);
+    await rememberAdtUrl(configured, verdict.url);
+    return { url: verdict.url, verified: true };
+  }
+  log(`port scan finished; ${verdict.reason}; keeping ${configured}. Add the ADT port to SAP_URL or rerun sap-ai-dev --setup.`);
+  return { url: configured, verified: false, reason: verdict.reason };
+}
+
+function noProxyEnv(env, host) {
+  const noProxy = [env.NO_PROXY || env.no_proxy, host].filter(Boolean).join(',');
+  return { NO_PROXY: noProxy, no_proxy: noProxy };
+}
+
 async function discoverForCommand() {
   const env = { ...runtimeEnv };
   if (env.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry') env.SAP_AI_DEV_TOOLKIT_DESTINATION = '';
@@ -206,50 +276,54 @@ async function configuredLocalSapGuiDestination(env) {
   if (!env.SAP_URL) throw new Error('SAP_URL is required for local SAP GUI MCP entries. Rerun sap-ai-dev --setup and enter the ADT URL.');
   const client = env.SAP_CLIENT || '001';
   const systemId = env.SAP_SYSTEM_ID || '';
+  const configuredUrl = adtBaseUrl(env.SAP_URL);
   // Older entries used windows-sso, browser-saml or saml-password; all of them now mean browser SSO.
-  if (!['', 'basic'].includes(String(env.SAP_AUTH_MODE || '').toLowerCase())) {
-    const cacheKey = `${systemId || new URL(env.SAP_URL).hostname}-${client}`.toLowerCase().replace(/[^a-z0-9.-]+/g, '-');
-    let url = env.SAP_URL;
-    // SAP GUI landscapes carry no HTTP port, and the SSO browser cannot sign in on a guessed one.
-    if (!hasExplicitPort(url)) {
-      const detected = await detectLocalAdtUrl({ url, client }).catch(() => '');
-      logLine(detected
-        ? `[sap-ai-dev] ${name}: SAP_URL has no port; ADT answers at ${detected}`
-        : `[sap-ai-dev] ${name}: SAP_URL has no port and no ADT port answered on ${new URL(url).hostname}; add the port to SAP_URL or rerun sap-ai-dev --setup`);
-      url = detected || url;
-    }
+  const sso = !['', 'basic'].includes(String(env.SAP_AUTH_MODE || '').toLowerCase());
+  const tlsServerName = String(env.SAP_TLS_SERVER_NAME || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME || '').trim();
+  const tlsServerNames = String(env.SAP_TLS_SERVER_NAMES || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES || tlsServerName).split(',').map(value => value.trim()).filter(Boolean);
+  const tlsCaFile = String(env.SAP_TLS_CA_FILE || env.SAP_AI_DEV_TOOLKIT_TLS_CA_FILE || '').trim();
+  // SNI-routed Basic entries pin port and certificate names on purpose; SSO ignores those names.
+  const adt = (sso || !tlsServerNames.length) && !hasPathPrefix(configuredUrl)
+    ? await resolveLocalAdtUrl(name, configuredUrl, client)
+    : { url: configuredUrl };
+  // The scan reached ADT directly, so an env proxy the browser's PAC would bypass must not reroute VSP.
+  const direct = adt.verified ? noProxyEnv(env, new URL(adt.url).hostname) : {};
+  const probe = adt.verified === undefined
+    ? { status: 'configured', available: true }
+    : (adt.verified ? { status: `adt-verified at ${adt.url}`, available: true } : { status: `adt-unverified: ${adt.reason}`, available: false });
+  if (sso) {
+    const cacheKey = `${systemId || new URL(configuredUrl).hostname}-${client}`.toLowerCase().replace(/[^a-z0-9.-]+/g, '-');
+    if (isIP(new URL(adt.url).hostname.replace(/^\[(.*)\]$/, '$1'))) logLine(`[sap-ai-dev] ${name}: SSO is configured for an IP address; Kerberos and the browser certificate check need the DNS host name`);
     return {
       source: 'sap-gui-local',
       name,
-      url,
+      url: adt.url,
       client,
       systemId,
       authentication: 'SSO',
       // SAP_SAML_AUTH survives sanitizeChildEnv and would make VSP demand SAML credentials.
-      childEnv: { SAP_SSO: 'true', SAP_SSO_SYSTEM: cacheKey, SAP_SAML_AUTH: '' },
-      probe: { status: 'configured', available: true }
+      childEnv: { SAP_SSO: 'true', SAP_SSO_SYSTEM: cacheKey, SAP_SAML_AUTH: '', ...direct },
+      probe
     };
   }
-  const tlsServerName = String(env.SAP_TLS_SERVER_NAME || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAME || '').trim();
-  const tlsServerNames = String(env.SAP_TLS_SERVER_NAMES || env.SAP_AI_DEV_TOOLKIT_TLS_SERVER_NAMES || tlsServerName).split(',').map(value => value.trim()).filter(Boolean);
-  const tlsCaFile = String(env.SAP_TLS_CA_FILE || env.SAP_AI_DEV_TOOLKIT_TLS_CA_FILE || '').trim();
   const tlsRoute = tlsServerNames.length
-    ? await createTlsServerNameAdtProxy({ destinationUrl: env.SAP_URL, tlsServerNames, caFile: tlsCaFile || undefined })
+    ? await createTlsServerNameAdtProxy({ destinationUrl: configuredUrl, tlsServerNames, caFile: tlsCaFile || undefined })
     : null;
   return {
     source: 'sap-gui-local',
     name,
-    url: tlsRoute?.url || env.SAP_URL,
-    backendUrl: tlsRoute ? env.SAP_URL : undefined,
+    url: tlsRoute?.url || adt.url,
+    backendUrl: tlsRoute ? configuredUrl : undefined,
     client,
     systemId,
     authentication: 'Basic',
     childEnv: {
       SAP_USER: env.SAP_USER || env.SAP_USERNAME || '',
-      SAP_PASSWORD: env.SAP_PASSWORD || env.SAP_PASS || ''
+      SAP_PASSWORD: env.SAP_PASSWORD || env.SAP_PASS || '',
+      ...direct
     },
     close: tlsRoute?.close,
-    probe: { status: tlsRoute ? 'configured-tls-server-name' : 'configured', available: true }
+    probe: tlsRoute ? { status: 'configured-tls-server-name', available: true } : probe
   };
 }
 

package/src/local-sap-gui.mjs

@@ -1,4 +1,5 @@
 import { platform, homedir } from 'node:os';
+import { isIP } from 'node:net';
 import { promisify } from 'node:util';
 import { execFile } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -149,6 +150,8 @@ function normalizeRecord(record, sourcePath) {
   const port = endpoint ? Number(endpoint[2]) : 0;
   const instance = instanceFrom(record) || (port >= 3200 && port <= 3299 ? String(port - 3200).padStart(2, '0') : '');
   const client = text(record.client || record.sapclient) || '001';
+  // A load-balanced entry names the message server, whose port is 3600 + its instance.
+  const messageServerPort = text(record.msport).match(/^36(\d{2})$/);
   return {
     source: 'sap-gui-local',
     name,
@@ -157,6 +160,7 @@ function normalizeRecord(record, sourcePath) {
     systemId,
     instance,
     client,
+    ...(messageServerPort ? { messageServer: { host, httpPort: 8100 + Number(messageServerPort[1]) } } : {}),
     authentication: ssoHintFrom(record) ? 'Basic/SSO hint' : 'Basic',
     authMode: 'basic',
     ssoHint: ssoHintFrom(record),
@@ -182,6 +186,7 @@ function parseLandscapeXml(content, sourcePath) {
       // For load-balanced entries `server` is a logon group, not a host.
       if (!messageServer?.host) continue;
       record.server = messageServer.host;
+      record.msport = messageServer.port;
     }
     const normalized = normalizeRecord(record, sourcePath);
     if (normalized) records.push(normalized);
@@ -407,21 +412,110 @@ export function hasExplicitPort(url) {
   return /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*:\d+(?:[/?#]|$)/i.test(String(url || '').trim());
 }
 
+// VSP appends every ADT path to the base URL, so a pasted ADT path would double up.
+export function adtBaseUrl(url) {
+  return String(url || '').trim().replace(/[?#].*$/, '').replace(/\/sap\/bc\/adt(?:\/.*)?$/i, '').replace(/\/+$/, '');
+}
+
+// A gateway path prefix cannot be probed by host and port alone.
+export function hasPathPrefix(url) {
+  return /^[a-z][a-z0-9+.-]*:\/\/[^/?#]+\/[^?#]/i.test(adtBaseUrl(url));
+}
+
+export function adtPort(url) {
+  const parsed = new URL(url);
+  return Number(parsed.port) || (parsed.protocol === 'http:' ? 80 : 443);
+}
+
+// A redirect proves less than a 401 or 200: a gateway can redirect every path.
+function adtRank(finding) {
+  return (finding.secure ? 0 : 2) + (finding.status >= 300 && finding.status < 400 ? 1 : 0);
+}
+
+// Picks the ADT URL from VSP detect's JSON, or explains why there is none.
+export function adtVerdict(result, protocol = 'https:') {
+  const findings = Array.isArray(result?.findings) ? result.findings.filter(Boolean) : [];
+  const usable = findings
+    .filter(finding => finding.kind === 'adt' && /^https?:\/\//i.test(String(finding.url || '')) && (finding.secure || protocol === 'http:'))
+    .sort((left, right) => adtRank(left) - adtRank(right));
+  if (usable.length) return { url: usable[0].url, reason: '' };
+  const host = result?.host || 'the host';
+  const unsearched = Array.isArray(result?.unsearched) ? result.unsearched[0] : undefined;
+  if (unsearched) {
+    const unresolved = /does not resolve/i.test(String(unsearched.reason));
+    return { url: '', unresolved, reason: unresolved ? `${unsearched.object} does not resolve; connect to the company network or VPN` : `${unsearched.object}: ${unsearched.reason}` };
+  }
+  const plain = findings.find(finding => finding.kind === 'adt');
+  // The SSO session cookie is the whole credential; https is never traded for http silently.
+  if (plain) return { url: '', reason: `only plain HTTP answers ADT (${plain.url}); enter it explicitly to accept an unencrypted connection` };
+  const inactive = findings.find(finding => finding.kind === 'sap-without-adt');
+  if (inactive) return { url: '', reason: `SAP answers at ${inactive.url} but /sap/bc/adt is not active; ask basis to activate it in SICF` };
+  const tls = findings.find(finding => finding.kind === 'tls-name-mismatch');
+  if (tls && /certificate required|bad certificate/i.test(String(tls.detail))) {
+    return { url: '', reason: `port ${tls.port} demands a client certificate (smart card), which VSP cannot present` };
+  }
+  if (tls) return { url: '', reason: `port ${tls.port} presents a certificate ${tls.certHost ? `for ${tls.certHost}` : 'this machine does not trust'}${tls.detail ? ` (${tls.detail})` : ''}` };
+  const open = findings.filter(finding => ['open', 'http'].includes(finding.kind)).map(finding => finding.port);
+  if (open.length) return { url: '', reason: `${open.length === 1 ? `port ${open[0]} on ${host} accepts` : `ports ${open.join(', ')} on ${host} accept`} connections but none answered as ADT` };
+  return { url: '', reason: `no port answered on ${host}` };
+}
+
 // A portless URL means 443, which on-premise ICMs rarely serve; VSP's `detect`
 // probes the conventional ADT ports and reports which one answers.
-export async function detectAdtUrl(binary, { url, client, env = process.env, timeoutMs = 60_000 } = {}) {
+export async function detectAdtUrl(binary, { url, client, instance, env = process.env, exhaustive = false, ports = [], timeoutMs = 180_000 } = {}) {
   let configured;
-  try { configured = new URL(url); } catch { return ''; }
-  const args = ['detect', configured.hostname.replace(/^\[(.*)\]$/, '$1'), '--json', ...(client ? ['--client', String(client)] : [])];
+  try { configured = new URL(url); } catch { return { url: '', reason: `${url} is not a valid URL` }; }
+  const host = configured.hostname.replace(/^\[(.*)\]$/, '$1');
+  const args = ['detect', host, '--json',
+    ...(client ? ['--client', String(client)] : []),
+    ...(/^\d{2}$/.test(String(instance || '')) ? ['--instance', String(instance)] : []),
+    ...(exhaustive ? ['--all'] : []),
+    ...ports.flatMap(port => ['--port', String(port)])];
+  // A corporate HTTPS_PROXY rarely routes internal SAP hosts; probe them directly.
+  const noProxy = [env.NO_PROXY || env.no_proxy, host].filter(Boolean).join(',');
   const [command, ...prefixArgs] = /\.(?:mjs|cjs|js)$/i.test(binary)
     ? [process.execPath, binary]
     : (/\.(?:cmd|bat)$/i.test(binary) && platform() === 'win32' ? ['cmd', '/c', binary] : [binary]);
+  let stdout;
   try {
-    const { stdout } = await execFileAsync(command, [...prefixArgs, ...args], { env, windowsHide: true, timeout: timeoutMs, maxBuffer: 1024 * 1024 });
-    const adt = (JSON.parse(stdout)?.findings || []).filter(finding => finding?.kind === 'adt' && /^https?:\/\//i.test(String(finding.url || '')));
-    // The SSO session cookie is the whole credential; never trade https for http.
-    return (adt.find(finding => finding.secure) || (configured.protocol === 'http:' ? adt[0] : undefined))?.url || '';
-  } catch {
-    return '';
+    ({ stdout } = await execFileAsync(command, [...prefixArgs, ...args], { env: { ...env, NO_PROXY: noProxy, no_proxy: noProxy }, windowsHide: true, timeout: timeoutMs, maxBuffer: 1024 * 1024 }));
+  } catch (error) {
+    const why = error.killed ? `timed out after ${Math.round(timeoutMs / 1000)} s` : (typeof error.code === 'string' ? error.code : `exit code ${error.code}`);
+    const blocked = ['EACCES', 'EPERM', 'UNKNOWN'].includes(error.code) ? '; antivirus or application control may block it' : '';
+    return { url: '', reason: `VSP detect could not run (${why}) from ${binary}${blocked}` };
   }
+  try { return adtVerdict(JSON.parse(stdout), configured.protocol); }
+  catch { return { url: '', reason: 'VSP detect returned unreadable output' }; }
+}
+
+// Application servers appear by their SM51 names, host_SID_NN.
+export function parseMessageServerServers(body, { host = '', systemId = '' } = {}) {
+  const domain = isIP(host) ? '' : (/^[^.]+\.(.+)$/.exec(host)?.[1] || '');
+  const servers = new Map();
+  for (const [, name, sid, instance] of String(body).matchAll(/\b([A-Za-z0-9][A-Za-z0-9.-]*)_([A-Za-z][A-Za-z0-9]{2})_(\d{2})\b/g)) {
+    if (systemId && sid.toUpperCase() !== systemId.toUpperCase()) continue;
+    const appHost = name.includes('.') || !domain ? name : `${name}.${domain}`;
+    servers.set(`${appHost.toLowerCase()}:${instance}`, { host: appHost, instance });
+  }
+  return [...servers.values()];
+}
+
+// A load-balanced landscape entry names the message server, which serves no
+// ADT; its HTTP port lists the application servers that do, the same source
+// SAP Web Dispatcher reads.
+export async function messageServerAppServers({ host, httpPort, systemId } = {}, { timeoutMs = 5000 } = {}) {
+  if (!host || !httpPort) return [];
+  const authority = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+  for (const path of ['/msgserver/text/logon', '/msgserver/text/serverlist']) {
+    let body = '';
+    try {
+      const response = await fetch(`http://${authority}:${httpPort}${path}`, { signal: AbortSignal.timeout(timeoutMs) });
+      if (response.ok) body = await response.text();
+    } catch {
+      continue;
+    }
+    const servers = parseMessageServerServers(body, { host, systemId });
+    if (servers.length) return servers;
+  }
+  return [];
 }

package/src/setup.mjs

@@ -4,7 +4,7 @@ import { platform } from 'node:os';
 import { isIP } from 'node:net';
 import { checkboxPrompt, colorText, formatStatus, selectPrompt, startProgress, textPrompt } from './terminal-ui.mjs';
 import { discoverDestinations, remediation } from './bas-discovery.mjs';
-import { defaultAdtUrl, discoverSapGuiSystems, hasExplicitPort } from './local-sap-gui.mjs';
+import { adtBaseUrl, adtPort, defaultAdtUrl, discoverSapGuiSystems, hasExplicitPort, hasPathPrefix, messageServerAppServers } from './local-sap-gui.mjs';
 import { discoverCloudFoundryDestinations, getCloudFoundryTarget, deleteManagedCloudFoundryServiceKeys, findOrphanedCloudFoundryServiceKeys } from './cf-destination.mjs';
 import { SAP_DEVELOPMENT_MCP_SERVERS, collectCloudFoundryKeyReferencesFromAllEntries, collectManagedCloudFoundryKeyReferences, installMcpConfig, readMcpConfig, resolveMcpConfigPath } from './mcp-config.mjs';
 import { discoverCertificateDnsNames } from './tls-adt-proxy.mjs';
@@ -124,21 +124,96 @@ function localAuthenticationLabel(authMode) {
   return authMode === 'sso' ? 'SSO' : 'Basic';
 }
 
-// The SSO browser signs in on the ADT URL itself, and SAP GUI landscapes never
-// carry the HTTP port, so a portless URL would send it to 443.
-async function detectSsoAdtPort(destination, label, client, { output = stdout, env = process.env, detectAdtUrl } = {}) {
-  if (!detectAdtUrl || hasExplicitPort(destination.url)) return;
-  const stopProgress = startProgress(`Detecting the ADT port for ${label}`, { output, env, label: 'SSO' });
-  let detected = '';
-  try { detected = await detectAdtUrl({ url: destination.url, client }); }
-  catch { detected = ''; }
-  finally { stopProgress(); }
-  if (detected) {
-    destination.url = detected;
-    print(output, formatStatus(`ADT answers at ${detected}; SSO signs in there.`, 'success', output, 'SSO'));
-    return;
+// Ports typed at the prompt are range-checked before anything parses them as a URL.
+export function adtCandidate(answer, baseUrl) {
+  const value = String(answer || '').trim();
+  if (/^\d+$/.test(value)) {
+    const port = Number(value);
+    if (port < 1 || port > 65535) throw new Error('Enter a port between 1 and 65535, or a full URL.');
+    const base = new URL(baseUrl);
+    return `${base.protocol}//${base.hostname}:${port}`;
+  }
+  const validation = validateAdtUrlCandidate(value);
+  if (validation !== true) throw new Error(validation);
+  return adtBaseUrl(value);
+}
+
+// Cheapest evidence first: named ports get one probe, then the host's usual
+// ports, then the message server's application servers, then every port.
+async function findAdtUrl(destination, label, client, { candidates = [], scan = true, output = stdout, env = process.env, detectAdtUrl } = {}) {
+  const detect = async (message, target) => {
+    print(output, formatStatus(message, 'progress', output, 'ADT'));
+    const stopProgress = startProgress(message, { output, env, label: 'ADT' });
+    try { return await detectAdtUrl({ client, ...target }); }
+    catch (error) { return { url: '', reason: error.message }; }
+    finally { stopProgress(); }
+  };
+  let verdict = { url: '', reason: `no port was checked for ${label}` };
+  for (const candidate of [...new Set([destination.url, ...candidates].filter(url => url && hasExplicitPort(url)))]) {
+    verdict = await detect(`Checking ADT at ${candidate}`, { url: candidate, ports: [adtPort(candidate)] });
+    if (verdict.url || verdict.unresolved) return verdict;
+  }
+  if (!scan) return verdict;
+  const host = new URL(destination.url).hostname;
+  verdict = await detect(`Port scan in progress on ${host} to find the ADT port for ${label}`, { url: destination.url, ...(destination.instance ? { instance: destination.instance } : {}) });
+  if (verdict.url || verdict.unresolved) return verdict;
+  if (destination.messageServer) {
+    print(output, formatStatus(`Asking the message server ${destination.messageServer.host}:${destination.messageServer.httpPort} for the application servers of ${label}`, 'progress', output, 'ADT'));
+    for (const server of (await messageServerAppServers({ ...destination.messageServer, systemId: destination.systemId })).slice(0, 3)) {
+      const found = await detect(`Port scan in progress on application server ${server.host} (instance ${server.instance})`, { url: `${new URL(destination.url).protocol}//${server.host}`, instance: server.instance });
+      if (found.url) return found;
+    }
   }
-  print(output, formatStatus(`No ADT port answered for ${label}; SSO keeps ${destination.url}. If the browser cannot reach it, rerun setup and enter the ADT URL with its port, for example ${new URL(destination.url).origin}:44300.`, 'warning', output, 'SSO'));
+  return detect(`No ADT port on the usual ports for ${label} (${verdict.reason}); port scan in progress on every conventional SAP port of ${host} (this can take a minute)`, { url: destination.url, exhaustive: true });
+}
+
+// An SSO sign-in can only start where ADT answers, so for SSO setup does not
+// end on an unverified URL unless the user chooses to.
+async function settleAdtUrl(destination, label, client, { insist = false, candidates = [], input = stdin, output = stdout, env = process.env, detectAdtUrl } = {}) {
+  if (!detectAdtUrl) return 'unchecked';
+  if (hasPathPrefix(destination.url)) {
+    print(output, formatStatus(`${destination.url} has a gateway path, so setup uses it as entered without a port scan.`, 'info', output, 'ADT'));
+    return 'unchecked';
+  }
+  const options = { candidates, output, env, detectAdtUrl };
+  let verdict = await findAdtUrl(destination, label, client, options);
+  while (!verdict.url) {
+    print(output, formatStatus(`No ADT answer for ${label}: ${verdict.reason}.`, 'warning', output, 'ADT'));
+    if (!insist) return 'unverified';
+    const choice = await selectPrompt({
+      message: `ADT for ${label}`,
+      defaultValue: 'enter',
+      choices: [
+        { name: 'Enter the ADT port or URL (basis finds it in SMICM > Goto > Services)', value: 'enter', shortcut: 'e' },
+        { name: 'Scan again, for example after connecting the VPN', value: 'retry', shortcut: 'r' },
+        { name: `Keep ${destination.url} without an ADT answer`, value: 'keep', shortcut: 'k' },
+        { name: 'Skip this system', value: 'skip', shortcut: 's' }
+      ]
+    }, { input, output });
+    if (choice === 'keep') return 'unverified';
+    if (choice === 'skip') return 'skipped';
+    if (choice === 'enter') {
+      const answer = await textPrompt({
+        message: `ADT port or URL for ${label}`,
+        placeholder: '44300 or https://host:44300',
+        validate: value => {
+          try { adtCandidate(value, destination.url); return true; }
+          catch (error) { return error.message; }
+        }
+      }, { input, output });
+      destination.url = adtCandidate(answer, destination.url);
+    }
+    const retry = choice === 'retry';
+    verdict = await findAdtUrl(destination, label, client, { ...options, candidates: retry ? candidates : [], scan: retry || !hasExplicitPort(destination.url) });
+  }
+  destination.url = verdict.url;
+  print(output, formatStatus(`ADT answers at ${verdict.url}.`, 'success', output, 'ADT'));
+  return 'verified';
+}
+
+function warnSsoIpHost(destination, label, output) {
+  if (!isIP(new URL(destination.url).hostname.replace(/^\[(.*)\]$/, '$1'))) return;
+  print(output, formatStatus(`${label} uses an IP address; SSO needs the DNS host name for Kerberos and the browser certificate check. Enter the host name if the sign-in fails.`, 'warning', output, 'SSO'));
 }
 
 async function confirmPrompt(message, { input = stdin, output = stdout } = {}) {
@@ -232,7 +307,7 @@ async function runManualEntryWizard({ env = process.env, input = stdin, output =
       source: 'sap-gui-local',
       name,
       serverName: name,
-      url,
+      url: adtBaseUrl(url),
       host: parsedUrl?.hostname || '',
       client: '001',
       authentication: 'Basic',
@@ -243,16 +318,21 @@ async function runManualEntryWizard({ env = process.env, input = stdin, output =
       // 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 });
-    if (authMode === 'sso') await detectSsoAdtPort(destination, name, clients[0], { output, env, detectAdtUrl });
-    destination.authentication = localAuthenticationLabel(authMode);
-    destination.authMode = authMode;
-    for (const client of clients) {
-      expanded.push(buildLocalClientDestination(destination, client, authMode, { multipleClients: clients.length > 1 }));
+    const adt = await settleAdtUrl(destination, name, clients[0], { insist: authMode === 'sso', input, output, env, detectAdtUrl });
+    if (adt === 'skipped') {
+      print(output, formatStatus(`Skipped ${name}; no MCP server was added for it.`, 'info', output, 'Manual entry'));
+    } else {
+      if (authMode === 'sso') warnSsoIpHost(destination, name, output);
+      else await maybeConfigureTlsSelfHeal(destination, name, { input, output });
+      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'));
     }
-    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;
@@ -273,6 +353,18 @@ function localClientDestinationName(destination, client, { multipleClients = fal
 }
 
 
+// Two systems sharing a SID cannot be told apart, so neither URL is offered for them.
+function previousLocalAdtUrls(config) {
+  const urls = new Map();
+  for (const entry of Object.values(config?.servers || {})) {
+    const entryEnv = entry?.env || {};
+    if (entryEnv.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE !== 'sap-gui-local' || !entryEnv.SAP_SYSTEM_ID || !entryEnv.SAP_URL) continue;
+    const key = String(entryEnv.SAP_SYSTEM_ID).toUpperCase();
+    urls.set(key, urls.has(key) && urls.get(key) !== entryEnv.SAP_URL ? '' : entryEnv.SAP_URL);
+  }
+  return urls;
+}
+
 function safeProbe(probe) {
   const result = {};
   if (typeof probe?.status === 'string') result.status = probe.status;
@@ -310,6 +402,7 @@ function safeLocalSapGuiDestination(destination) {
     proxyType: 'Internet',
     tlsServerName: destination.tlsServerName,
     tlsServerNames: destination.tlsServerNames,
+    messageServer: destination.messageServer,
     probe: safeProbe(destination.probe),
     childEnv: destination.childEnv || {}
   };
@@ -364,7 +457,7 @@ 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, detectAdtUrl } = {}) {
+async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin, output = stdout, env = process.env, detectAdtUrl, previousAdtUrls = new Map() } = {}) {
   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);
@@ -398,6 +491,7 @@ async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin
     message: colorText('🧭 Select destinations', 'cyan', output),
     choices,
     required: false,
+    searchable: true,
     shortcuts: { all: 'a' },
     actions: { m: addManually },
     confirmEmpty: 'Press Enter again to continue with none (removes this add-on’s MCP entries).'
@@ -425,17 +519,24 @@ async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin
       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 guess = defaultAdtUrl(destination);
+      // A URL an earlier setup verified beats the 443NN naming convention.
+      const fallback = previousAdtUrls.get(String(destination.systemId || '').toUpperCase()) || guess;
       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 });
+      destination.url = adtBaseUrl(url || fallback);
       const authMode = await chooseLocalAuthMode({ ...destination, name: promptLabel }, { input, output, env });
-      if (authMode === 'sso') await detectSsoAdtPort(destination, promptLabel, clients[0], { output, env, detectAdtUrl });
+      const adt = await settleAdtUrl(destination, promptLabel, clients[0], { insist: authMode === 'sso', candidates: url ? [] : [guess], input, output, env, detectAdtUrl });
+      if (adt === 'skipped') {
+        print(output, formatStatus(`Skipped ${promptLabel}; no MCP server was added for it.`, 'info', output, 'Local SAP GUI'));
+        continue;
+      }
+      if (authMode === 'sso') warnSsoIpHost(destination, promptLabel, output);
+      else await maybeConfigureTlsSelfHeal(destination, promptLabel, { input, output });
       destination.authentication = localAuthenticationLabel(authMode);
       destination.authMode = authMode;
       for (const client of clients) {
@@ -503,9 +604,12 @@ export async function runSetup({
   let createdKeys = [];
   let configPath;
   let managedKeys = [];
+  let previousAdtUrls = new Map();
   try {
     configPath = await resolveMcpConfigPath(env);
-    managedKeys = collectManagedCloudFoundryKeyReferences(await readMcpConfig(configPath));
+    const existingConfig = await readMcpConfig(configPath);
+    managedKeys = collectManagedCloudFoundryKeyReferences(existingConfig);
+    previousAdtUrls = previousLocalAdtUrls(existingConfig);
   } catch {
     warnings.push('Existing MCP config could not be read before setup; existing CF service keys will not be reused.');
   }
@@ -607,7 +711,7 @@ export async function runSetup({
     selected = await runManualEntryWizard({ env, input, output, detectAdtUrl });
     if (!selected.length) return await exitWithoutDestinations();
   } else {
-    selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env, detectAdtUrl });
+    selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env, detectAdtUrl, previousAdtUrls });
   }
 
   let sapDevelopmentServers = [];

package/src/terminal-ui.mjs

@@ -213,11 +213,13 @@ export async function selectPrompt({ message, choices, defaultValue } = {}, { in
   });
 }
 
-export async function checkboxPrompt({ message, choices: initialChoices, required = false, shortcuts = { all: 'a' }, actions = {}, validate, confirmEmpty = '' } = {}, { input = process.stdin, output = process.stdout } = {}) {
+export async function checkboxPrompt({ message, choices: initialChoices, required = false, shortcuts = { all: 'a' }, actions = {}, validate, confirmEmpty = '', searchable = false } = {}, { 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;
+  let searchQuery = '';
+  let searchMode = false;
   const selectable = enabledChoices(choices);
   const selected = new Set(choices.flatMap((choice, index) => choice.checked && !choice.disabled ? [index] : []));
   let cursor = firstEnabledIndex(choices);
@@ -228,40 +230,73 @@ export async function checkboxPrompt({ message, choices: initialChoices, require
   // With confirmEmpty set, Enter on an empty selection shows it and waits for a second Enter.
   let awaitingEmptyConfirm = false;
 
+  const matchingIndexes = () => choices
+    .map((choice, index) => ({ choice, index }))
+    .filter(({ choice }) => !searchQuery || String(choice.name || '').toLowerCase().startsWith(searchQuery.toLowerCase()))
+    .map(({ index }) => index);
+  const visibleIndexes = () => {
+    const indexes = matchingIndexes();
+    if (searchable && (!indexes.includes(cursor) || choices[cursor]?.disabled)) {
+      cursor = indexes.find(index => !choices[index]?.disabled) ?? -1;
+    }
+    return indexes;
+  };
+  const moveCursor = step => {
+    if (!searchable) {
+      cursor = nextEnabledIndex(choices, cursor, step);
+      return;
+    }
+    const indexes = visibleIndexes();
+    const visibleChoices = indexes.map(index => choices[index]);
+    if (!visibleChoices.some(choice => !choice.disabled)) return;
+    const position = nextEnabledIndex(visibleChoices, indexes.indexOf(cursor), step);
+    cursor = indexes[position] ?? -1;
+  };
+
   const write = text => output.write(text);
   const clearRendered = () => {
     if (!renderedLines) return;
     write(`\u001b[${renderedLines}A\u001b[J`);
     renderedLines = 0;
   };
-  const ensureVisible = pageSize => {
-    if (cursor < top) top = cursor;
-    if (cursor >= top + pageSize) top = cursor - pageSize + 1;
-    top = clamp(top, 0, Math.max(0, choices.length - pageSize));
+  const ensureVisible = (pageSize, visibleCount, cursorPosition) => {
+    if (cursorPosition >= 0 && cursorPosition < top) top = cursorPosition;
+    if (cursorPosition >= top + pageSize) top = cursorPosition - pageSize + 1;
+    top = clamp(top, 0, Math.max(0, visibleCount - pageSize));
   };
   const footer = error => {
     if (error) return [[error, 'red']];
     if (awaitingEmptyConfirm) return [['Nothing is selected yet. Press Space to select the highlighted item (❯).', 'yellow'], [confirmEmpty, 'yellow']];
+    if (searchable && matchingIndexes().length === 0) return [['No choices match.', 'yellow']];
     if (!selected.size) return [['Press Space to select the highlighted item (❯), then Enter to confirm.', 'cyan']];
     return [[`${selected.size} selected. Press Enter to confirm, or Space to change.`, 'green']];
   };
   const render = (error = '') => {
     const columns = Number.isFinite(output?.columns) ? output.columns : 80;
-    const pageSize = checkboxPageSize(output, choices.length);
-    ensureVisible(pageSize);
+    const indexes = visibleIndexes();
+    const pageSize = searchable
+      ? Math.max(1, checkboxPageSize(output, indexes.length + 1) - 1)
+      : checkboxPageSize(output, indexes.length);
+    const cursorPosition = indexes.indexOf(cursor);
+    ensureVisible(pageSize, indexes.length, cursorPosition);
     const lines = [];
     lines.push(truncateToColumns(`${message} (Space: select, ${shortcuts?.all || 'a'}: toggle all, Enter: confirm)`, columns));
-    const end = Math.min(choices.length, top + pageSize);
+    if (searchable) {
+      const hint = searchQuery ? 'Backspace edits; Esc clears' : 'type prefix; / before a or m';
+      lines.push(truncateToColumns(`Search: ${searchQuery || 'type prefix'} (${hint})`, columns));
+    }
+    const end = Math.min(indexes.length, top + pageSize);
     for (let index = top; index < end; index += 1) {
-      const choice = choices[index];
-      const pointer = index === cursor ? '❯' : ' ';
+      const choiceIndex = indexes[index];
+      const choice = choices[choiceIndex];
+      const pointer = choiceIndex === cursor ? '❯' : ' ';
       // A red ✗ for "not selected yet" was read as an error, so unselected rows show an empty box.
-      const box = choice.disabled ? '[-]' : (selected.has(index) ? colorText('[✓]', 'green', output) : '[ ]');
+      const box = choice.disabled ? '[-]' : (selected.has(choiceIndex) ? colorText('[✓]', 'green', output) : '[ ]');
       const disabled = choice.disabled ? ` — ${choice.disabled}` : '';
       lines.push(truncateToColumns(`${pointer} ${box} ${choice.name}${disabled}`, columns));
     }
-    if (choices.length > pageSize) {
-      lines.push(truncateToColumns(colorText(`  Showing ${top + 1}-${end} of ${choices.length}; use ↑/↓ to scroll.`, 'cyan', output), columns));
+    if (indexes.length > pageSize) {
+      lines.push(truncateToColumns(colorText(`  Showing ${top + 1}-${end} of ${indexes.length}; use ↑/↓ to scroll.`, 'cyan', output), columns));
     }
     for (const [text, color] of footer(error)) lines.push(truncateToColumns(colorText(`  ${text}`, color, output), columns));
     clearRendered();
@@ -328,16 +363,25 @@ export async function checkboxPrompt({ message, choices: initialChoices, require
     };
     const onKeypress = (_chunk, key = {}) => {
       if (key.ctrl && key.name === 'c') return fail(new Error('Prompt interrupted'));
-      if (key.name === 'up' || key.name === 'k') cursor = nextEnabledIndex(choices, cursor, -1);
-      else if (key.name === 'down' || key.name === 'j') cursor = nextEnabledIndex(choices, cursor, 1);
-      else if (key.name === 'space' && !choices[cursor]?.disabled) {
+      else if (searchable && key.name === 'escape') {
+        searchQuery = '';
+        searchMode = false;
+        top = 0;
+      } else if (searchable && searchMode && (key.name === 'backspace' || key.name === 'delete')) {
+        searchQuery = Array.from(searchQuery).slice(0, -1).join('');
+        if (!searchQuery) searchMode = false;
+        top = 0;
+      } else if (searchable && !searchMode && String(_chunk ?? '') === '/' && !key.ctrl && !key.meta) searchMode = true;
+      else if (key.name === 'up' || (!searchable && key.name === 'k')) moveCursor(-1);
+      else if (key.name === 'down' || (!searchable && key.name === 'j')) moveCursor(1);
+      else if (key.name === 'space' && cursor >= 0 && !choices[cursor]?.disabled) {
         if (selected.has(cursor)) selected.delete(cursor);
         else selected.add(cursor);
-      } else if (shortcuts?.all && key.name === shortcuts.all) {
+      } else if ((!searchable || !searchMode) && shortcuts?.all && key.name === shortcuts.all) {
         const allSelected = enabledChoices(choices).every(choice => selected.has(choices.indexOf(choice)));
         selected.clear();
         if (!allSelected) for (const choice of enabledChoices(choices)) selected.add(choices.indexOf(choice));
-      } else if (actionShortcutFor(_chunk, key)) {
+      } else if ((!searchable || !searchMode) && actionShortcutFor(_chunk, key)) {
         awaitingEmptyConfirm = false;
         void runAction(actionShortcutFor(_chunk, key));
         return;
@@ -351,6 +395,10 @@ export async function checkboxPrompt({ message, choices: initialChoices, require
           return render();
         }
         return finish(values);
+      } else if (searchable && !key.ctrl && !key.meta && Array.from(String(_chunk ?? '')).length === 1 && !/[\u0000-\u001f\u007f]/u.test(String(_chunk))) {
+        searchMode = true;
+        searchQuery += String(_chunk);
+        top = 0;
       } else {
         return;
       }