sap-ai-dev-toolkit 0.9.6 → 0.9.8

package/README.md

@@ -300,7 +300,7 @@ The installer handles VSP provisioning automatically:
 - Uses the package's bundled patched VSP binary for the current platform, verified against the npm-published `dist/checksums.txt`. When the bundled asset is missing (an interrupted install, an antivirus quarantine, or a git checkout without `dist/`), a checksum-anchored download from the matching GitHub release is the fallback; MCP server startup runs it too, because npx entries skip install scripts.
 - No Go toolchain is downloaded or required at install time; Go is only used by the repository's own `build:vsp` development script.
 
-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.
+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: every row starts with an empty box `[ ]`. Use **Space** to tick a destination (`[✓]`) and **Enter** to confirm; the line under the list always names the next key to press. Press **a** to toggle all destinations (select all if any are unchecked; otherwise clear the selection). Pressing **Enter** with nothing selected asks for a second **Enter**, because 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. Local SAP GUI MCP server keys use the SAP system ID and client (for example `t4d-100`) instead of the longer SAP GUI description, while `SAP_AI_DEV_TOOLKIT_DESTINATION` still preserves the display name. 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 offers Windows / smart card SSO (the default) instead, which writes `SAP_AUTH_MODE=sso` without username/password prompts. At server start, VSP opens Microsoft Edge on the ADT URL; Edge completes the login the same way it does in your browser (smart card certificate and PIN, Kerberos, or company SAML/Entra login), and the session is cached and refreshed automatically. SSO entries need an ADT URL with a host name, not an IP address. 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.
 
@@ -447,7 +447,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, **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.
+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 takes a second **Enter** and 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.
 

package/package.json

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

@@ -4,7 +4,7 @@ import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverDestinations, remediation, slugifyDestination, statusRows } from './bas-discovery.mjs';
-import { discoverSapGuiSystems } from './local-sap-gui.mjs';
+import { detectAdtUrl, discoverSapGuiSystems, hasExplicitPort } from './local-sap-gui.mjs';
 import { binaryTarget, downloadBinary, findBinary } from './binary.mjs';
 import { MCPProxy } from './mcp-proxy.mjs';
 import { installMcpConfig, npxMcpLauncher, repairManagedMcpConfig } from './mcp-config.mjs';
@@ -186,6 +186,10 @@ async function binaryOrError() {
   ].join(' '));
 }
 
+async function detectLocalAdtUrl(target) {
+  return detectAdtUrl(await binaryOrError(), { ...target, env: runtimeEnv });
+}
+
 async function discoverForCommand() {
   const env = { ...runtimeEnv };
   if (env.SAP_AI_DEV_TOOLKIT_DESTINATION_SOURCE === 'cloud-foundry') env.SAP_AI_DEV_TOOLKIT_DESTINATION = '';
@@ -205,10 +209,25 @@ async function configuredLocalSapGuiDestination(env) {
   // 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 host = new URL(url).hostname;
+      logLine(`[sap-ai-dev] ${name}: SAP_URL has no port; port scan in progress on ${host} (usual ADT ports)`);
+      let detected = await detectLocalAdtUrl({ url, client }).catch(() => '');
+      if (!detected) {
+        logLine(`[sap-ai-dev] ${name}: no ADT port on the usual ports; port scan in progress on every conventional SAP port of ${host} (can take a minute)`);
+        detected = await detectLocalAdtUrl({ url, client, exhaustive: true }).catch(() => '');
+      }
+      logLine(detected
+        ? `[sap-ai-dev] ${name}: port scan finished; ADT answers at ${detected}`
+        : `[sap-ai-dev] ${name}: port scan finished; no ADT port answered on ${host}; add the port to SAP_URL or rerun sap-ai-dev --setup`);
+      url = detected || url;
+    }
     return {
       source: 'sap-gui-local',
       name,
-      url: env.SAP_URL,
+      url,
       client,
       systemId,
       authentication: 'SSO',
@@ -280,7 +299,8 @@ async function main() {
   }
   if (setup) {
     const setupOptions = {
-      includeSapDevelopmentToolsPrompt: hasFlag('--tools') || hasFlag('--companion-tools')
+      includeSapDevelopmentToolsPrompt: hasFlag('--tools') || hasFlag('--companion-tools'),
+      detectAdtUrl: detectLocalAdtUrl
     };
     if (hasFlag('--npx')) {
       // Windows has no npx.exe, so generated entries there launch through
@@ -335,7 +355,7 @@ 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();
+      await runSetup({ detectAdtUrl: detectLocalAdtUrl });
       return;
     }
     const binary = await binaryOrError();

package/src/local-sap-gui.mjs

@@ -401,3 +401,31 @@ export function defaultAdtUrl(system) {
   const authority = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
   return /^\d{2}$/.test(instance) ? `https://${authority}:443${instance}` : `https://${authority}`;
 }
+
+// new URL() drops a default port, so `https://host:443` must be read from the text.
+export function hasExplicitPort(url) {
+  return /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*:\d+(?:[/?#]|$)/i.test(String(url || '').trim());
+}
+
+// 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, exhaustive = false, ports = [], timeoutMs = 180_000 } = {}) {
+  let configured;
+  try { configured = new URL(url); } catch { return ''; }
+  const host = configured.hostname.replace(/^\[(.*)\]$/, '$1');
+  const args = ['detect', host, '--json', ...(client ? ['--client', String(client)] : []), ...(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(',');
+  env = { ...env, NO_PROXY: noProxy, no_proxy: noProxy };
+  const [command, ...prefixArgs] = /\.(?:mjs|cjs|js)$/i.test(binary)
+    ? [process.execPath, binary]
+    : (/\.(?:cmd|bat)$/i.test(binary) && platform() === 'win32' ? ['cmd', '/c', binary] : [binary]);
+  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 '';
+  }
+}

package/src/mcp-config.mjs

@@ -106,6 +106,8 @@ export async function resolveMcpServerCommand(env = process.env) {
     : ['sap-ai-dev'];
   const searchPath = String(env.PATH || env.Path || '').split(delimiter).filter(Boolean);
   for (const directory of searchPath) {
+    // npx prepends its disposable cache bin dir; entries pointing there go stale or vanish with the cache.
+    if (/[\\/]_npx[\\/][^\\/]+[\\/]node_modules[\\/]\.bin[\\/]?$/.test(directory)) continue;
     for (const executableName of executableNames) {
       const candidate = resolve(directory, executableName);
       try {

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 } from './local-sap-gui.mjs';
+import { defaultAdtUrl, discoverSapGuiSystems, hasExplicitPort } 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,6 +124,43 @@ 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, { input = stdin, output = stdout, env = process.env, detectAdtUrl } = {}) {
+  if (!detectAdtUrl || hasExplicitPort(destination.url)) return;
+  const scan = async (message, options) => {
+    const stopProgress = startProgress(message, { output, env, label: 'SSO' });
+    try { return await detectAdtUrl({ url: destination.url, client, ...options }); }
+    catch { return ''; }
+    finally { stopProgress(); }
+  };
+  print(output, formatStatus(`Port scan in progress on ${new URL(destination.url).hostname} to find the ADT port for ${label}.`, 'progress', output, 'SSO'));
+  let detected = await scan(`Detecting the ADT port for ${label}`, {});
+  if (!detected) {
+    print(output, formatStatus(`No ADT port answered on the usual ports for ${label}; port scan in progress on every conventional SAP port (this can take a minute).`, 'progress', output, 'SSO'));
+    detected = await scan(`Sweeping SAP HTTP(S) ports for ${label}`, { exhaustive: true });
+  }
+  // Nothing on the machine knows the port, so the person who does is asked until one answers.
+  while (!detected) {
+    const host = new URL(destination.url).hostname;
+    print(output, formatStatus(`No ADT port answered on ${host}. Ask basis or check SMICM (Goto > Services) for the HTTPS port.`, 'warning', output, 'SSO'));
+    const answer = String(await textPrompt({
+      message: `ADT port or URL for ${label}`,
+      placeholder: '44300 or https://host:44300',
+      validate: value => /^\d{2,5}$/.test(String(value).trim()) || validateAdtUrlCandidate(String(value).trim())
+    }, { input, output })).trim();
+    const candidate = /^\d+$/.test(answer) ? `${new URL(destination.url).origin}:${answer}` : answer;
+    const port = Number(new URL(candidate).port || (candidate.startsWith('http:') ? 80 : 443));
+    detected = await detectAdtUrl({ url: candidate, client, ports: [port] }).catch(() => '');
+    if (!detected && await confirmPrompt(`${candidate} did not answer as ADT. Use it anyway? (y/Enter=yes, n=try another)`, { input, output })) {
+      destination.url = candidate;
+      return;
+    }
+  }
+  destination.url = detected;
+  print(output, formatStatus(`ADT answers at ${detected}; SSO signs in there.`, 'success', output, 'SSO'));
+}
+
 async function confirmPrompt(message, { input = stdin, output = stdout } = {}) {
   const answer = await textPrompt({
     message,
@@ -181,7 +218,7 @@ async function maybeConfigureTlsSelfHeal(destination, promptLabel, { input = std
 // 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 } = {}) {
+async function runManualEntryWizard({ env = process.env, input = stdin, output = stdout, detectAdtUrl } = {}) {
   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));
@@ -229,6 +266,7 @@ async function runManualEntryWizard({ env = process.env, input = stdin, output =
     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], { input, output, env, detectAdtUrl });
     destination.authentication = localAuthenticationLabel(authMode);
     destination.authMode = authMode;
     for (const client of clients) {
@@ -346,7 +384,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 } = {}) {
+async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin, output = stdout, env = process.env, detectAdtUrl } = {}) {
   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);
@@ -371,9 +409,8 @@ async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin
   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 => ({
+  const addManually = async () => (await runManualEntryWizard({ env, input, output, detectAdtUrl })).map(destination => ({
     value: destination,
     name: `${destination.name} (manual, client ${destination.client})`
   }));
@@ -381,8 +418,10 @@ async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin
     message: colorText('🧭 Select destinations', 'cyan', output),
     choices,
     required: false,
+    searchable: true,
     shortcuts: { all: 'a' },
-    actions: { m: addManually }
+    actions: { m: addManually },
+    confirmEmpty: 'Press Enter again to continue with none (removes this add-on’s MCP entries).'
   }, { input, output });
 
   if (!isBas && selected.length) {
@@ -417,6 +456,7 @@ async function chooseDiscoveredDestinations(destinations, { isBas, input = stdin
       destination.url = url || fallback;
       await maybeConfigureTlsSelfHeal(destination, promptLabel, { input, output });
       const authMode = await chooseLocalAuthMode({ ...destination, name: promptLabel }, { input, output, env });
+      if (authMode === 'sso') await detectSsoAdtPort(destination, promptLabel, clients[0], { input, output, env, detectAdtUrl });
       destination.authentication = localAuthenticationLabel(authMode);
       destination.authMode = authMode;
       for (const client of clients) {
@@ -437,7 +477,8 @@ export async function runSetup({
   discoverLocalSapGui = discoverSapGuiSystems,
   confirmCfImport = confirmCloudFoundryImport,
   install = installMcpConfig,
-  includeSapDevelopmentToolsPrompt = false
+  includeSapDevelopmentToolsPrompt = false,
+  detectAdtUrl
 } = {}) {
   const isBas = Boolean(env.H2O_URL);
   if (!isBas && (!input.isTTY || !output.isTTY)) {
@@ -584,10 +625,10 @@ export async function runSetup({
       ]
     }, { input, output });
     if (choice !== 'manual') return await exitWithoutDestinations();
-    selected = await runManualEntryWizard({ env, input, output });
+    selected = await runManualEntryWizard({ env, input, output, detectAdtUrl });
     if (!selected.length) return await exitWithoutDestinations();
   } else {
-    selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env });
+    selected = await chooseDiscoveredDestinations(destinations, { isBas, input, output, env, detectAdtUrl });
   }
 
   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 } = {}, { 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);
@@ -225,6 +227,31 @@ export async function checkboxPrompt({ message, choices: initialChoices, require
   let renderedLines = 0;
   let done = false;
   let previousRawMode;
+  // 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 = () => {
@@ -232,32 +259,43 @@ export async function checkboxPrompt({ message, choices: initialChoices, require
     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. Backspace or Esc clears search.', '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) lines.push(truncateToColumns(`Search: ${searchQuery || (searchMode ? '' : 'type a prefix; / for a or m')}`, 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 marker = selected.has(index)
-        ? colorText('✓', 'green', output)
-        : colorText('✗', 'red', output);
+      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(choiceIndex) ? colorText('[✓]', 'green', output) : '[ ]');
       const disabled = choice.disabled ? ` — ${choice.disabled}` : '';
-      const label = `${pointer}${marker} ${choice.name}${disabled}`;
-      lines.push(truncateToColumns(label, columns));
+      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));
     }
-    if (error) lines.push(truncateToColumns(colorText(`  ${error}`, 'red', output), columns));
+    for (const [text, color] of footer(error)) lines.push(truncateToColumns(colorText(`  ${text}`, color, output), columns));
     clearRendered();
     write(`${lines.join('\n')}\n`);
     renderedLines = physicalRows(lines, columns);
@@ -322,16 +360,26 @@ 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;
       } else if (key.name === 'return' || key.name === 'enter') {
@@ -339,10 +387,19 @@ export async function checkboxPrompt({ message, choices: initialChoices, require
         const validation = typeof validate === 'function' ? validate(values) : true;
         if (validation !== true) return render(String(validation));
         if (required && !values.length) return render('Select at least one item.');
+        if (confirmEmpty && !values.length && !awaitingEmptyConfirm) {
+          awaitingEmptyConfirm = true;
+          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;
       }
+      awaitingEmptyConfirm = false;
       render();
     };