@saptools/cf-hana 0.4.1 → 0.5.1

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 
 // src/config.ts
 var CLI_NAME = "cf-hana";
-var CLI_VERSION = "0.4.0";
+var CLI_VERSION = "0.5.1";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 6e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 6e4;
@@ -18,6 +18,27 @@ var DEFAULT_RESULT_TTL_MINUTES = 10080;
 var DEFAULT_RESULT_SEARCH_LIMIT = 20;
 var DEFAULT_MAX_RESULT_STORE_BYTES = 256 * 1024 * 1024;
 var MAX_RESULT_STORE_BYTES = resolveMaxResultStoreBytes();
+function resolvePositiveIntEnv(suffix, defaultValue) {
+  const raw = readEnv(envName(suffix));
+  if (raw === void 0) {
+    return defaultValue;
+  }
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : defaultValue;
+}
+var DEFAULT_TUNNEL_FALLBACK_BUDGET_MS = resolvePositiveIntEnv(
+  "TUNNEL_FALLBACK_BUDGET_MS",
+  25e3
+);
+var DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS = resolvePositiveIntEnv(
+  "TUNNEL_CANDIDATE_TIMEOUT_MS",
+  15e3
+);
+var DEFAULT_TUNNEL_MAX_CANDIDATES = resolvePositiveIntEnv("TUNNEL_MAX_CANDIDATES", 3);
+var DEFAULT_TUNNEL_KEEPALIVE_SECONDS = resolvePositiveIntEnv(
+  "TUNNEL_KEEPALIVE_SECONDS",
+  1200
+);
 function resolveMaxResultStoreBytes() {
   if (readEnv(envName("DRIVER")) !== "fake") {
     return DEFAULT_MAX_RESULT_STORE_BYTES;
@@ -1052,7 +1073,7 @@ function findTopLevelChar(sql, target, startIndex, endIndex) {
 }
 
 // src/statements.ts
-var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT", "WITH"]);
+var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT"]);
 var DML_KEYWORDS = /* @__PURE__ */ new Set(["INSERT", "UPDATE", "DELETE", "MERGE", "UPSERT", "REPLACE"]);
 var DDL_KEYWORDS = /* @__PURE__ */ new Set(["CREATE", "DROP", "ALTER", "TRUNCATE", "RENAME", "COMMENT"]);
 function firstKeyword(sql) {
@@ -1092,8 +1113,165 @@ function firstKeyword(sql) {
   }
   return sql.slice(index, keywordEnd).toUpperCase();
 }
-function classifyStatement(sql) {
-  const keyword = firstKeyword(sql);
+function skipQuotedText2(sql, start) {
+  const quote = sql[start];
+  let index = start + 1;
+  while (index < sql.length) {
+    if (sql[index] === quote) {
+      if (sql[index + 1] === quote) {
+        index += 2;
+        continue;
+      }
+      index += 1;
+      break;
+    }
+    index += 1;
+  }
+  return index;
+}
+function skipLineComment3(sql, start) {
+  let index = start + 2;
+  while (index < sql.length && sql[index] !== "\n") {
+    index += 1;
+  }
+  return index;
+}
+function skipBlockComment3(sql, start) {
+  let index = start + 2;
+  while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
+    index += 1;
+  }
+  return Math.min(index + 2, sql.length);
+}
+function maskIgnoredSqlText(sql) {
+  let masked = "";
+  let index = 0;
+  while (index < sql.length) {
+    const char = sql[index];
+    if (char === "'" || char === '"') {
+      const end = skipQuotedText2(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      const end = skipLineComment3(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      const end = skipBlockComment3(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    masked += char ?? "";
+    index += 1;
+  }
+  return masked;
+}
+function topLevelKeywordIndex(sql, keyword) {
+  const masked = maskIgnoredSqlText(sql);
+  let depth = 0;
+  for (let index = 0; index < masked.length; index += 1) {
+    const char = masked[index];
+    if (char === "(") {
+      depth += 1;
+      continue;
+    }
+    if (char === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth === 0 && masked.slice(index, index + keyword.length).toUpperCase() === keyword && !/[A-Za-z0-9_$#]/.test(masked.charAt(index - 1)) && !/[A-Za-z0-9_$#]/.test(masked.charAt(index + keyword.length))) {
+      return index;
+    }
+  }
+  return void 0;
+}
+function hasTopLevelKeyword(sql, keyword) {
+  return topLevelKeywordIndex(sql, keyword) !== void 0;
+}
+function isIdentifierChar2(char) {
+  return /[A-Za-z0-9_$#]/.test(char);
+}
+function skipWhitespace(masked, start) {
+  let index = start;
+  while (index < masked.length && /\s/.test(masked.charAt(index))) {
+    index += 1;
+  }
+  return index;
+}
+function matchingCloseParenIndex(masked, openIndex) {
+  let depth = 0;
+  for (let index = openIndex; index < masked.length; index += 1) {
+    const char = masked.charAt(index);
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return void 0;
+}
+function isAsKeywordAt(masked, index) {
+  return masked.slice(index, index + 2).toUpperCase() === "AS" && !isIdentifierChar2(masked.charAt(index - 1)) && !isIdentifierChar2(masked.charAt(index + 2));
+}
+function cteListEndIndex(masked, afterWith) {
+  let index = afterWith;
+  for (; ; ) {
+    index = skipWhitespace(masked, index);
+    while (index < masked.length && isIdentifierChar2(masked.charAt(index))) {
+      index += 1;
+    }
+    index = skipWhitespace(masked, index);
+    if (masked.charAt(index) === "(") {
+      const columnListEnd = matchingCloseParenIndex(masked, index);
+      if (columnListEnd === void 0) {
+        return void 0;
+      }
+      index = skipWhitespace(masked, columnListEnd + 1);
+    }
+    if (!isAsKeywordAt(masked, index)) {
+      return void 0;
+    }
+    index = skipWhitespace(masked, index + 2);
+    if (masked.charAt(index) !== "(") {
+      return void 0;
+    }
+    const closeIndex = matchingCloseParenIndex(masked, index);
+    if (closeIndex === void 0) {
+      return void 0;
+    }
+    index = skipWhitespace(masked, closeIndex + 1);
+    if (masked.charAt(index) === ",") {
+      index += 1;
+      continue;
+    }
+    return index;
+  }
+}
+function resolveWithStatement(sql) {
+  const withIndex = topLevelKeywordIndex(sql, "WITH");
+  if (withIndex === void 0) {
+    return void 0;
+  }
+  const masked = maskIgnoredSqlText(sql);
+  const trailingIndex = cteListEndIndex(masked, withIndex + "WITH".length);
+  if (trailingIndex === void 0) {
+    return void 0;
+  }
+  let keywordEnd = trailingIndex;
+  while (keywordEnd < masked.length && isIdentifierChar2(masked.charAt(keywordEnd))) {
+    keywordEnd += 1;
+  }
+  return { keyword: masked.slice(trailingIndex, keywordEnd).toUpperCase(), index: trailingIndex };
+}
+function classifyByKeyword(keyword) {
   if (SELECT_KEYWORDS.has(keyword)) {
     return "select";
   }
@@ -1105,6 +1283,14 @@ function classifyStatement(sql) {
   }
   return "unknown";
 }
+function classifyStatement(sql) {
+  const keyword = firstKeyword(sql);
+  if (keyword === "WITH") {
+    const resolved = resolveWithStatement(sql);
+    return resolved === void 0 ? "unknown" : classifyByKeyword(resolved.keyword);
+  }
+  return classifyByKeyword(keyword);
+}
 function quoteIdentifier(identifier) {
   if (identifier.length === 0) {
     throw new QueryError("A SQL identifier must not be empty");
@@ -1268,11 +1454,11 @@ function mergeTargetReference(statementSql, target, usingStart) {
     return target.reference;
   }
   if (/^PARTITION\b/i.test(suffix)) {
-    const open = suffix.indexOf("(");
-    if (open === -1) {
+    const open2 = suffix.indexOf("(");
+    if (open2 === -1) {
       return void 0;
     }
-    const close = findTopLevelChar(suffix, ")", open + 1, suffix.length);
+    const close = findTopLevelChar(suffix, ")", open2 + 1, suffix.length);
     if (close === void 0) {
       return void 0;
     }
@@ -1455,13 +1641,19 @@ function dispatchWriteBackupPlan(keyword, statementSql, params) {
   }
 }
 function buildWriteBackupPlan(sql, params = []) {
-  const statementSql = trimStatementSql(sql);
-  const keyword = firstKeyword(statementSql);
+  const trimmed = trimStatementSql(sql);
+  const leading = firstKeyword(trimmed);
+  const withResolved = leading === "WITH" ? resolveWithStatement(trimmed) : void 0;
+  const keyword = withResolved?.keyword ?? leading;
   if (!isWriteKeyword(keyword)) {
     return void 0;
   }
-  assertParamArity(statementSql, params);
-  return dispatchWriteBackupPlan(keyword, statementSql, params);
+  const startIndex = withResolved?.index ?? 0;
+  const statementSql = trimmed.slice(startIndex);
+  const slicedParams = params.slice(countPlaceholders(trimmed.slice(0, startIndex)));
+  assertParamArity(statementSql, slicedParams);
+  const plan = dispatchWriteBackupPlan(keyword, statementSql, slicedParams);
+  return plan === void 0 ? void 0 : { ...plan, statementSql: trimmed };
 }
 
 // src/backup.ts
@@ -1790,9 +1982,9 @@ function buildEnv(ctx, overrides = {}) {
   env["CF_HOME"] = ctx.cfHome;
   return env;
 }
-async function execWithRetries(bin, args, env, timeoutMs = DEFAULT_TIMEOUT_MS) {
+async function execWithRetries(bin, args, env, timeoutMs = DEFAULT_TIMEOUT_MS, maxAttempts = CF_RETRY_ATTEMPTS) {
   let lastErr;
-  for (let attempt = 0; attempt < CF_RETRY_ATTEMPTS; attempt++) {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
     try {
       const { stdout } = await execFileAsync(bin, args, {
         env,
@@ -1811,18 +2003,24 @@ async function execWithRetries(bin, args, env, timeoutMs = DEFAULT_TIMEOUT_MS) {
       if (isEnoent || !isTimeout && !isNetworkFlake) {
         throw err;
       }
-      if (attempt < CF_RETRY_ATTEMPTS - 1) {
+      if (attempt < maxAttempts - 1) {
         await new Promise((r) => setTimeout(r, CF_RETRY_BASE_DELAY_MS * (attempt + 1)));
       }
     }
   }
   throw lastErr;
 }
-async function runCf(args, ctx, overrides = {}) {
+async function runCf(args, ctx, overrides = {}, execOptions = {}) {
   const { bin, argsPrefix } = resolveCfBin();
   const env = buildEnv(ctx, overrides);
   try {
-    return await execWithRetries(bin, [...argsPrefix, ...args], env);
+    return await execWithRetries(
+      bin,
+      [...argsPrefix, ...args],
+      env,
+      execOptions.timeoutMs,
+      execOptions.maxAttempts
+    );
   } catch (lastErr) {
     const e = lastErr;
     const detail = e?.stderr ? String(e.stderr) : e?.message ?? "";
@@ -1852,6 +2050,27 @@ async function cfEnvDirect(appName) {
   delete env["SAP_PASSWORD"];
   return await execWithRetries(bin, [...argsPrefix, "env", appName], env);
 }
+async function cfApps(ctx, timeoutMs) {
+  return await runCf(
+    ["apps"],
+    ctx,
+    {},
+    timeoutMs === void 0 ? {} : { timeoutMs, maxAttempts: 1 }
+  );
+}
+async function cfAppsDirect(timeoutMs) {
+  const { bin, argsPrefix } = resolveCfBin();
+  const env = { ...process.env };
+  delete env["SAP_EMAIL"];
+  delete env["SAP_PASSWORD"];
+  return await execWithRetries(
+    bin,
+    [...argsPrefix, "apps"],
+    env,
+    timeoutMs,
+    timeoutMs === void 0 ? void 0 : 1
+  );
+}
 async function readCurrentCfTarget() {
   const { bin, argsPrefix } = resolveCfBin();
   const env = { ...process.env };
@@ -1901,6 +2120,26 @@ function parseTargetFields(stdout) {
   }
   return map;
 }
+function parseCfAppsOutput(stdout) {
+  const lines = stdout.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => /^\s*name\s+\S/i.test(line));
+  if (headerIndex === -1) {
+    return [];
+  }
+  const rows = [];
+  for (const line of lines.slice(headerIndex + 1)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    const [name, state] = trimmed.split(/\s+/);
+    if (name === void 0 || state === void 0) {
+      continue;
+    }
+    rows.push({ name, state });
+  }
+  return rows;
+}
 function formatCurrentCfAppSelector(target, appName) {
   const name = appName.trim();
   if (!name) {
@@ -2212,7 +2451,10 @@ async function resolveAppBindings(rawSelector, options) {
     source: "live",
     selectorSource: target.selectorSource,
     regionConfirmed: target.regionConfirmed,
-    selectorCanBePinned: target.selectorCanBePinned
+    selectorCanBePinned: target.selectorCanBePinned,
+    apiEndpoint: target.apiEndpoint,
+    orgName: target.orgName,
+    spaceName: target.spaceName
   };
 }
 async function readExplicitBindings(target, options) {
@@ -2278,6 +2520,7 @@ function toConnectionTarget(binding, role) {
 // src/driver/fake.ts
 import { appendFile } from "fs/promises";
 var catalogFailureInjected = false;
+var connectFailureInjectedOnce = false;
 function catalogObjects() {
   return [
     { SCHEMA_NAME: "APP_SCHEMA", OBJECT_NAME: "EXISTING_TABLE", OBJECT_TYPE: "TABLE" },
@@ -2486,10 +2729,28 @@ var FakeConnection = class {
     return this.closed;
   }
 };
+function maybeFailConnect() {
+  const mode = readEnv(envName("FAKE_FAIL_CONNECT"));
+  if (mode !== "once" && mode !== "always") {
+    return;
+  }
+  if (mode === "once" && connectFailureInjectedOnce) {
+    return;
+  }
+  connectFailureInjectedOnce = true;
+  const cause = Object.assign(
+    new Error("Could not connect to any host: [ fake-host:443 - forced fixture failure ]"),
+    { code: "EHDBOPENCONN" }
+  );
+  throw new CfHanaError("CONNECTION", `Failed to connect to HANA: ${cause.message}`, { cause });
+}
 function createFakeDriver() {
   return {
     name: "fake",
-    connect: (_params) => Promise.resolve(new FakeConnection())
+    connect: (_params) => {
+      maybeFailConnect();
+      return Promise.resolve(new FakeConnection());
+    }
   };
 }
 
@@ -2714,7 +2975,15 @@ async function connectHdb(params) {
     user: params.user,
     password: params.password,
     ca: params.certificate,
-    useTLS: true
+    useTLS: true,
+    // HANA Cloud can reactively redirect a connection mid-auth to an
+    // internal per-node hostname (pod-locality routing). That target is
+    // often unreachable outside SAP's own network, and for a tunneled
+    // connection it would silently abandon the SSH forward for a fresh,
+    // untunneled socket. The original bound host is always a real, working
+    // endpoint, so disabling the redirect is safe on the direct path too.
+    disableCloudRedirect: true,
+    ...params.servername === void 0 ? {} : { servername: params.servername }
   });
   await openClient(client, params.connectTimeoutMs);
   try {
@@ -2823,83 +3092,6 @@ async function appendSqlHistory(input, options = {}) {
 // src/safety.ts
 var DESTRUCTIVE_DDL_KEYWORDS = /* @__PURE__ */ new Set(["DROP", "TRUNCATE", "ALTER"]);
 var UNSCOPED_WRITE_KEYWORDS = /* @__PURE__ */ new Set(["UPDATE", "DELETE"]);
-function skipQuotedText2(sql, start) {
-  const quote = sql[start];
-  let index = start + 1;
-  while (index < sql.length) {
-    if (sql[index] === quote) {
-      if (sql[index + 1] === quote) {
-        index += 2;
-        continue;
-      }
-      index += 1;
-      break;
-    }
-    index += 1;
-  }
-  return index;
-}
-function skipLineComment3(sql, start) {
-  let index = start + 2;
-  while (index < sql.length && sql[index] !== "\n") {
-    index += 1;
-  }
-  return index;
-}
-function skipBlockComment3(sql, start) {
-  let index = start + 2;
-  while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
-    index += 1;
-  }
-  return Math.min(index + 2, sql.length);
-}
-function maskIgnoredSqlText(sql) {
-  let masked = "";
-  let index = 0;
-  while (index < sql.length) {
-    const char = sql[index];
-    if (char === "'" || char === '"') {
-      const end = skipQuotedText2(sql, index);
-      masked += " ".repeat(end - index);
-      index = end;
-      continue;
-    }
-    if (char === "-" && sql[index + 1] === "-") {
-      const end = skipLineComment3(sql, index);
-      masked += " ".repeat(end - index);
-      index = end;
-      continue;
-    }
-    if (char === "/" && sql[index + 1] === "*") {
-      const end = skipBlockComment3(sql, index);
-      masked += " ".repeat(end - index);
-      index = end;
-      continue;
-    }
-    masked += char ?? "";
-    index += 1;
-  }
-  return masked;
-}
-function hasTopLevelKeyword(sql, keyword) {
-  const masked = maskIgnoredSqlText(sql);
-  let depth = 0;
-  for (let index = 0; index < masked.length; index += 1) {
-    const char = masked[index];
-    if (char === "(") {
-      depth += 1;
-      continue;
-    }
-    if (char === ")") {
-      depth = Math.max(0, depth - 1);
-      continue;
-    }
-    if (depth === 0 && masked.slice(index, index + keyword.length).toUpperCase() === keyword && !/[A-Za-z0-9_$#]/.test(masked.charAt(index - 1)) && !/[A-Za-z0-9_$#]/.test(masked.charAt(index + keyword.length))) {
-      return true;
-    }
-  }
-  return false;
-}
 function isUnconditionalMergeDelete(sql) {
   return /\bWHEN\s+MATCHED\s+THEN\s+DELETE\b/i.test(maskIgnoredSqlText(sql));
 }
@@ -2942,17 +3134,23 @@ function appendLimit(sql, limit) {
 }
 function inspectStatement(sql) {
   const kind = classifyStatement(sql);
-  const keyword = firstKeyword(sql);
+  const leading = firstKeyword(sql);
+  const withResolved = leading === "WITH" ? resolveWithStatement(sql) : void 0;
+  const keyword = withResolved?.keyword ?? leading;
+  const tail = withResolved === void 0 ? sql : sql.slice(withResolved.index);
   if (kind === "ddl") {
     return { kind, destructive: DESTRUCTIVE_DDL_KEYWORDS.has(keyword) };
   }
   if (kind === "dml") {
-    const destructive = UNSCOPED_WRITE_KEYWORDS.has(keyword) && !hasTopLevelKeyword(sql, "WHERE") || keyword === "MERGE" && isUnconditionalMergeDelete(sql) || keyword === "REPLACE" && isMalformedReplace(sql);
+    const destructive = UNSCOPED_WRITE_KEYWORDS.has(keyword) && !hasTopLevelKeyword(tail, "WHERE") || keyword === "MERGE" && isUnconditionalMergeDelete(tail) || keyword === "REPLACE" && isMalformedReplace(tail);
     return {
       kind,
       destructive
     };
   }
+  if (kind === "unknown") {
+    return { kind, destructive: keyword === "CALL" };
+  }
   return { kind, destructive: false };
 }
 function evaluateGuard(sql, config) {
@@ -2995,6 +3193,707 @@ function applyAutoLimit(sql, limit) {
   };
 }
 
+// src/tunnel/cache.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdir as mkdir4, readdir as readdir2, readFile as readFile3, rename as rename2, rm as rm5, writeFile as writeFile3 } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import { join as join6 } from "path";
+
+// src/tunnel/process.ts
+import { spawn } from "child_process";
+import { mkdtemp as mkdtemp2, open, readFile as readFile2, rm as rm4 } from "fs/promises";
+import { connect as netConnect, createServer } from "net";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join5 } from "path";
+var PORT_POLL_INTERVAL_MS = 100;
+var DEFAULT_PORT_PROBE_TIMEOUT_MS = 500;
+function assertPositiveSafeInteger(label, value) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new CfHanaError("CONFIG", `${label} must be a positive integer`);
+  }
+}
+async function allocateLocalPort() {
+  return await new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      server.close(() => {
+        if (address === null || typeof address === "string") {
+          reject(new CfHanaError("CONNECTION", "Could not allocate a local port for a tunnel"));
+          return;
+        }
+        resolve(address.port);
+      });
+    });
+  });
+}
+function probeLocalPort(port, timeoutMs = DEFAULT_PORT_PROBE_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const socket = netConnect({ host: "127.0.0.1", port });
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      finish(false);
+    }, timeoutMs);
+    timer.unref();
+    socket.once("connect", () => {
+      finish(true);
+    });
+    socket.once("error", () => {
+      finish(false);
+    });
+  });
+}
+function killTunnelProcess(pid) {
+  if (pid === void 0) {
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+  }
+}
+async function withScopedCfSession(selectorSource, target, sapCredentials, work) {
+  if (selectorSource === "ambient") {
+    return await work();
+  }
+  if (sapCredentials === void 0) {
+    throw new CredentialsNotFoundError(
+      "SAP credentials are required to open a tunnel session for an explicit selector"
+    );
+  }
+  const cfHome = await mkdtemp2(join5(tmpdir2(), "saptools-cf-hana-tunnel-"));
+  try {
+    const ctx = { cfHome };
+    await cfApi(target.apiEndpoint, ctx);
+    await cfAuth(sapCredentials.email, sapCredentials.password, ctx);
+    await cfTargetSpace(target.orgName, target.spaceName, ctx);
+    return await work(ctx);
+  } finally {
+    await rm4(cfHome, { recursive: true, force: true });
+  }
+}
+function raceTunnelReadiness(child, localPort, boundMs, probePort, killProcess) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const timers = {};
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearInterval(timers.poll);
+      clearTimeout(timers.deadline);
+      child.removeListener("exit", onAbort);
+      child.removeListener("error", onAbort);
+      if (result === void 0) {
+        killProcess(child.pid);
+      } else {
+        child.unref();
+      }
+      resolve(result);
+    };
+    function onAbort() {
+      finish();
+    }
+    child.on("exit", onAbort);
+    child.on("error", onAbort);
+    timers.poll = setInterval(() => {
+      void probePort(localPort).then((open2) => {
+        if (open2 && child.pid !== void 0) {
+          finish({ localPort, pid: child.pid });
+        }
+      });
+    }, PORT_POLL_INTERVAL_MS);
+    timers.deadline = setTimeout(finish, boundMs);
+  });
+}
+var STDERR_TAIL_MAX_CHARS = 4096;
+async function openStderrCapture() {
+  try {
+    const dir = await mkdtemp2(join5(tmpdir2(), "saptools-cf-hana-tunnel-log-"));
+    const path = join5(dir, "stderr.log");
+    const handle = await open(path, "w");
+    return {
+      path,
+      fd: handle.fd,
+      close: async () => {
+        await handle.close().catch(() => {
+        });
+        await rm4(dir, { recursive: true, force: true });
+      }
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function readStderrTail(path) {
+  try {
+    const content = (await readFile2(path, "utf8")).trim().replace(/\s+/g, " ");
+    if (content.length === 0) {
+      return void 0;
+    }
+    return content.length > STDERR_TAIL_MAX_CHARS ? content.slice(-STDERR_TAIL_MAX_CHARS) : content;
+  } catch {
+    return void 0;
+  }
+}
+async function spawnTunnel(params, deps = {}) {
+  assertPositiveSafeInteger("tunnel keepalive seconds", params.keepaliveSeconds);
+  const remainingMs = params.deadline - Date.now();
+  if (remainingMs <= 0) {
+    return void 0;
+  }
+  const boundMs = Math.min(remainingMs, params.candidateTimeoutMs);
+  const spawnProcess = deps.spawnProcess ?? spawn;
+  const probePort = deps.probePort ?? probeLocalPort;
+  const allocatePort = deps.allocatePort ?? allocateLocalPort;
+  const killProcess = deps.killProcess ?? killTunnelProcess;
+  const localPort = await allocatePort();
+  const { bin, argsPrefix } = resolveCfBin();
+  const forward = `${String(localPort)}:${params.hanaHost}:${String(params.hanaPort)}`;
+  const args = [
+    ...argsPrefix,
+    "ssh",
+    params.app,
+    "-L",
+    forward,
+    "-c",
+    `sleep ${String(params.keepaliveSeconds)}`
+  ];
+  const env = params.cfHome === void 0 ? { ...process.env } : { ...process.env, CF_HOME: params.cfHome };
+  const openCapture = deps.openStderrCapture ?? openStderrCapture;
+  const capture = await openCapture();
+  const stdio = capture === void 0 ? "ignore" : ["ignore", "ignore", capture.fd];
+  const child = spawnProcess(bin, args, { detached: true, stdio, env });
+  const result = await raceTunnelReadiness(child, localPort, boundMs, probePort, killProcess);
+  if (capture !== void 0) {
+    if (result === void 0) {
+      try {
+        const tail = await readStderrTail(capture.path);
+        if (tail !== void 0) {
+          deps.onFailureDiagnostic?.(tail);
+        }
+      } catch {
+      }
+    }
+    await capture.close();
+  }
+  return result;
+}
+
+// src/tunnel/cache.ts
+var DEFAULT_ESTABLISHING_STALE_MS = 2 * DEFAULT_TUNNEL_FALLBACK_BUDGET_MS;
+var DEFAULT_POLL_INTERVAL_MS = 300;
+function isRecord3(value) {
+  return typeof value === "object" && value !== null;
+}
+function defaultIsProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return isRecord3(error) && error["code"] !== "ESRCH";
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function tunnelCacheRoot(saptoolsRoot) {
+  return join6(saptoolsRoot ?? join6(homedir4(), ".saptools"), "cf-hana", "tunnel");
+}
+function tunnelCacheKey(host) {
+  return createHash2("sha256").update(host).digest("hex");
+}
+function tunnelCachePath(host, saptoolsRoot) {
+  return join6(tunnelCacheRoot(saptoolsRoot), `${tunnelCacheKey(host)}.json`);
+}
+function isOrgKey(value) {
+  return isRecord3(value) && typeof value["apiEndpoint"] === "string" && typeof value["orgName"] === "string";
+}
+function hasEstablishingFields(value) {
+  return value["status"] === "establishing" && typeof value["host"] === "string" && typeof value["startedAt"] === "string" && typeof value["ownerPid"] === "number" && isOrgKey(value["orgKey"]);
+}
+function hasReadyFields(value) {
+  return value["status"] === "ready" && typeof value["host"] === "string" && typeof value["localPort"] === "number" && typeof value["pid"] === "number" && typeof value["app"] === "string" && typeof value["expiresAt"] === "string" && isOrgKey(value["orgKey"]);
+}
+function isTunnelCacheRecord(value) {
+  return isRecord3(value) && value["version"] === 1 && (hasEstablishingFields(value) || hasReadyFields(value));
+}
+async function parseTunnelCacheFile(path) {
+  try {
+    const raw = JSON.parse(await readFile3(path, "utf8"));
+    return isTunnelCacheRecord(raw) ? raw : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function readTunnelCacheEntry(host, options = {}) {
+  const entry = await parseTunnelCacheFile(tunnelCachePath(host, options.saptoolsRoot));
+  return entry?.host === host ? entry : void 0;
+}
+function isExpired(entry, now) {
+  const expiresAt = Date.parse(entry.expiresAt);
+  return !Number.isFinite(expiresAt) || now.getTime() >= expiresAt;
+}
+async function isTunnelUsable(entry, options = {}) {
+  const isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  if (!isAlive(entry.pid)) {
+    return false;
+  }
+  if (isExpired(entry, options.now?.() ?? /* @__PURE__ */ new Date())) {
+    return false;
+  }
+  const probePort = options.probePort ?? probeLocalPort;
+  return await probePort(entry.localPort);
+}
+function isEstablishingStale(entry, options) {
+  const isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  if (!isAlive(entry.ownerPid)) {
+    return true;
+  }
+  const startedAt = Date.parse(entry.startedAt);
+  if (!Number.isFinite(startedAt)) {
+    return true;
+  }
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_ESTABLISHING_STALE_MS;
+  return now.getTime() - startedAt >= staleAfterMs;
+}
+async function writeEstablishingMarker(host, ownerPid, orgKey, options) {
+  const root = tunnelCacheRoot(options.saptoolsRoot);
+  await mkdir4(root, { recursive: true, mode: 448 });
+  const record = {
+    version: 1,
+    status: "establishing",
+    host,
+    startedAt: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+    ownerPid,
+    orgKey
+  };
+  try {
+    await writeFile3(tunnelCachePath(host, options.saptoolsRoot), `${JSON.stringify(record)}
+`, {
+      encoding: "utf8",
+      mode: 384,
+      flag: "wx"
+    });
+    return true;
+  } catch (error) {
+    if (isRecord3(error) && error["code"] === "EEXIST") {
+      return false;
+    }
+    throw error;
+  }
+}
+async function claimEstablishing(host, ownerPid, orgKey, options = {}) {
+  if (await writeEstablishingMarker(host, ownerPid, orgKey, options)) {
+    return { outcome: "claimed" };
+  }
+  const existing = await readTunnelCacheEntry(host, options);
+  if (existing === void 0) {
+    return await writeEstablishingMarker(host, ownerPid, orgKey, options) ? { outcome: "claimed" } : { outcome: "wait" };
+  }
+  if (existing.status === "ready") {
+    return { outcome: "already-ready", record: existing };
+  }
+  if (!isEstablishingStale(existing, options)) {
+    return { outcome: "wait" };
+  }
+  await rm5(tunnelCachePath(host, options.saptoolsRoot), { force: true });
+  return await writeEstablishingMarker(host, ownerPid, orgKey, options) ? { outcome: "claimed" } : { outcome: "wait" };
+}
+async function waitForEstablishment(host, deadline, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, options = {}) {
+  for (; ; ) {
+    const entry = await readTunnelCacheEntry(host, options);
+    if (entry === void 0) {
+      return void 0;
+    }
+    if (entry.status === "ready") {
+      return entry;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      return void 0;
+    }
+    await sleep(Math.min(pollIntervalMs, remainingMs));
+  }
+}
+async function finalizeEstablishingReady(host, record, options = {}) {
+  const root = tunnelCacheRoot(options.saptoolsRoot);
+  const path = tunnelCachePath(host, options.saptoolsRoot);
+  const tempPath = `${path}.tmp-${String(process.pid)}`;
+  const stored = { version: 1, status: "ready", host, ...record };
+  await mkdir4(root, { recursive: true, mode: 448 });
+  await rm5(tempPath, { force: true });
+  await writeFile3(tempPath, `${JSON.stringify(stored)}
+`, { encoding: "utf8", mode: 384 });
+  await rename2(tempPath, path);
+}
+async function finalizeEstablishingFailed(host, options = {}) {
+  await rm5(tunnelCachePath(host, options.saptoolsRoot), { force: true });
+}
+async function evictTunnelCache(host, options = {}) {
+  await rm5(tunnelCachePath(host, options.saptoolsRoot), { force: true });
+}
+function sameOrg(a, b) {
+  return a.apiEndpoint === b.apiEndpoint && a.orgName === b.orgName;
+}
+async function reapOneFile(path, currentOrgKey, options) {
+  const entry = await parseTunnelCacheFile(path);
+  if (entry === void 0) {
+    return;
+  }
+  const killProcess = options.killProcess ?? killTunnelProcess;
+  if (entry.status === "establishing") {
+    if (isEstablishingStale(entry, options)) {
+      await rm5(path, { force: true });
+    }
+    return;
+  }
+  const isAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  if (!isAlive(entry.pid)) {
+    await rm5(path, { force: true });
+    return;
+  }
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  if (isExpired(entry, now) || !sameOrg(entry.orgKey, currentOrgKey)) {
+    killProcess(entry.pid);
+    await rm5(path, { force: true });
+  }
+}
+async function reapStaleAndCrossOrgTunnels(currentOrgKey, options = {}) {
+  const root = tunnelCacheRoot(options.saptoolsRoot);
+  let files;
+  try {
+    files = await readdir2(root);
+  } catch {
+    return;
+  }
+  await Promise.all(
+    files.filter((file) => file.endsWith(".json")).map(async (file) => {
+      await reapOneFile(join6(root, file), currentOrgKey, options);
+    })
+  );
+}
+
+// src/tunnel/candidates.ts
+var RUNNING_STATE = "started";
+var VALID_APP_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function isValidAppName(name) {
+  return VALID_APP_NAME.test(name);
+}
+function discoveredAppNames(stdout, targetAppName) {
+  if (stdout === void 0) {
+    return [];
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const names = [];
+  for (const row of parseCfAppsOutput(stdout)) {
+    if (row.state !== RUNNING_STATE) {
+      continue;
+    }
+    if (row.name === targetAppName || seen.has(row.name)) {
+      continue;
+    }
+    if (!isValidAppName(row.name)) {
+      continue;
+    }
+    seen.add(row.name);
+    names.push(row.name);
+  }
+  return names;
+}
+function buildCandidateList(targetAppName, discoveredStdout, maxCandidates) {
+  const discovered = discoveredAppNames(discoveredStdout, targetAppName);
+  return [targetAppName, ...discovered.slice(0, maxCandidates)];
+}
+
+// src/tunnel/classifier.ts
+var CONNECT_TIMEOUT_MESSAGE = "HANA connection timed out";
+var OPEN_CONNECTION_CODE = "EHDBOPENCONN";
+var MAX_CAUSE_DEPTH = 5;
+function causeCode(value) {
+  return typeof value === "object" && value !== null ? value.code : void 0;
+}
+function causeOf(value) {
+  return typeof value === "object" && value !== null ? value.cause : void 0;
+}
+function hasOpenConnectionCause(cause, depth) {
+  if (depth > MAX_CAUSE_DEPTH) {
+    return false;
+  }
+  if (causeCode(cause) === OPEN_CONNECTION_CODE) {
+    return true;
+  }
+  return hasOpenConnectionCause(causeOf(cause), depth + 1);
+}
+function isConnectivityFailure(error) {
+  if (!(error instanceof CfHanaError)) {
+    return false;
+  }
+  if (error.code === "TIMEOUT") {
+    return error.message.includes(CONNECT_TIMEOUT_MESSAGE);
+  }
+  if (error.code !== "CONNECTION") {
+    return false;
+  }
+  return hasOpenConnectionCause(error.cause, 0);
+}
+function isUnattributedQueryFailure(error) {
+  return error instanceof QueryError && error.databaseCode === void 0 && error.sqlState === void 0;
+}
+
+// src/tunnel/fallback.ts
+var EXPIRY_SAFETY_MARGIN_MS = 3e4;
+function directParamsOf(config) {
+  return {
+    host: config.host,
+    port: config.port,
+    user: config.user,
+    password: config.password,
+    schema: config.schema,
+    certificate: config.certificate,
+    connectTimeoutMs: config.connectTimeoutMs
+  };
+}
+function tunneledParams(directParams, localPort) {
+  return { ...directParams, host: "127.0.0.1", port: localPort, servername: directParams.host };
+}
+function orgKeyOf(config) {
+  return { apiEndpoint: config.apiEndpoint, orgName: config.orgName };
+}
+function tunnelExpiryIso() {
+  return new Date(
+    Date.now() + DEFAULT_TUNNEL_KEEPALIVE_SECONDS * 1e3 - EXPIRY_SAFETY_MARGIN_MS
+  ).toISOString();
+}
+async function discardQuietly(work) {
+  await work.catch(() => {
+  });
+}
+function shouldDiscardTunnel(error) {
+  return isConnectivityFailure(error) || isUnattributedQueryFailure(error);
+}
+async function tryReadyRecord(record, driver, config, directParams, cacheOptions) {
+  try {
+    const connection = await driver.connect(tunneledParams(directParams, record.localPort));
+    config.onTunnelStatus?.(`connected via SSH tunnel through ${record.app}`);
+    return connection;
+  } catch (error) {
+    if (shouldDiscardTunnel(error)) {
+      await discardQuietly(evictTunnelCache(config.host, cacheOptions));
+      return void 0;
+    }
+    throw error;
+  }
+}
+function knownCandidates(targetAppName, hintApp) {
+  return hintApp === void 0 || hintApp === targetAppName ? [targetAppName] : [targetAppName, hintApp];
+}
+async function discoverAppsStdout(ctx, timeoutMs) {
+  try {
+    return ctx === void 0 ? await cfAppsDirect(timeoutMs) : await cfApps(ctx, timeoutMs);
+  } catch {
+    return;
+  }
+}
+async function discoverExtraCandidates(config, ctx, alreadyTried, deadline) {
+  const remainingMs = deadline - Date.now();
+  if (remainingMs <= 0) {
+    return [];
+  }
+  const stdout = await discoverAppsStdout(ctx, remainingMs);
+  const base = buildCandidateList(config.appName, stdout, DEFAULT_TUNNEL_MAX_CANDIDATES);
+  return base.filter((app) => !alreadyTried.includes(app));
+}
+async function finalizeCandidateConnection(app, spawned, driver, config, directParams, cacheOptions) {
+  const readyRecord = {
+    localPort: spawned.localPort,
+    pid: spawned.pid,
+    app,
+    orgKey: orgKeyOf(config),
+    expiresAt: tunnelExpiryIso()
+  };
+  try {
+    const connection = await driver.connect(tunneledParams(directParams, spawned.localPort));
+    await discardQuietly(finalizeEstablishingReady(config.host, readyRecord, cacheOptions));
+    config.onTunnelStatus?.(`connected via SSH tunnel through ${app}`);
+    return connection;
+  } catch (error) {
+    if (shouldDiscardTunnel(error)) {
+      await discardQuietly(finalizeEstablishingFailed(config.host, cacheOptions));
+      killTunnelProcess(spawned.pid);
+      return void 0;
+    }
+    await discardQuietly(finalizeEstablishingReady(config.host, readyRecord, cacheOptions));
+    throw error;
+  }
+}
+async function tryCandidate(app, ctx, driver, config, directParams, deadline, overrides) {
+  const cacheOptions = overrides.cache ?? {};
+  config.onTunnelStatus?.(`trying to reach ${config.host} via app ${app}...`);
+  const claim = await claimEstablishing(config.host, process.pid, orgKeyOf(config), cacheOptions);
+  if (claim.outcome === "already-ready") {
+    return await tryReadyRecord(claim.record, driver, config, directParams, cacheOptions);
+  }
+  if (claim.outcome === "wait") {
+    const waitDeadline = Math.min(deadline, Date.now() + DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS);
+    const ready = await waitForEstablishment(config.host, waitDeadline, void 0, cacheOptions);
+    return ready === void 0 ? void 0 : await tryReadyRecord(ready, driver, config, directParams, cacheOptions);
+  }
+  const spawned = await spawnTunnel(
+    {
+      cfHome: ctx?.cfHome,
+      app,
+      hanaHost: config.host,
+      hanaPort: config.port,
+      keepaliveSeconds: DEFAULT_TUNNEL_KEEPALIVE_SECONDS,
+      deadline,
+      candidateTimeoutMs: DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS
+    },
+    {
+      ...overrides.process,
+      onFailureDiagnostic: (message) => {
+        config.onTunnelStatus?.(`tunnel via ${app} failed: ${message}`);
+      }
+    }
+  );
+  if (spawned === void 0) {
+    await discardQuietly(finalizeEstablishingFailed(config.host, cacheOptions));
+    return void 0;
+  }
+  return await finalizeCandidateConnection(app, spawned, driver, config, directParams, cacheOptions);
+}
+async function tryCachedTunnel(driver, config, directParams, cacheOptions) {
+  if (config.refreshTunnel) {
+    const superseded = await readTunnelCacheEntry(config.host, cacheOptions);
+    await discardQuietly(evictTunnelCache(config.host, cacheOptions));
+    if (superseded?.status === "ready") {
+      (cacheOptions.killProcess ?? killTunnelProcess)(superseded.pid);
+    }
+    return { connection: void 0, hintApp: void 0 };
+  }
+  const entry = await readTunnelCacheEntry(config.host, cacheOptions);
+  if (entry?.status !== "ready") {
+    return { connection: void 0, hintApp: void 0 };
+  }
+  if (!await isTunnelUsable(entry, cacheOptions)) {
+    await discardQuietly(evictTunnelCache(config.host, cacheOptions));
+    return { connection: void 0, hintApp: entry.app };
+  }
+  const connection = await tryReadyRecord(entry, driver, config, directParams, cacheOptions);
+  return { connection, hintApp: entry.app };
+}
+async function tryDirectConnect(driver, config, directParams) {
+  if (config.tunnelMode !== "auto") {
+    return { connection: void 0, directError: void 0 };
+  }
+  const boundedDirectParams = {
+    ...directParams,
+    connectTimeoutMs: Math.min(directParams.connectTimeoutMs, DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS)
+  };
+  try {
+    return { connection: await driver.connect(boundedDirectParams), directError: void 0 };
+  } catch (error) {
+    if (!isConnectivityFailure(error)) {
+      throw error;
+    }
+    return { connection: void 0, directError: error };
+  }
+}
+function buildExhaustionError(host, directError, candidates) {
+  if (directError !== void 0) {
+    return directError;
+  }
+  return new CfHanaError(
+    "CONNECTION",
+    `Could not establish an SSH tunnel to ${host} through any candidate app (tried: ${candidates.length > 0 ? candidates.join(", ") : "none"})`
+  );
+}
+async function tryCandidateList(apps, ctx, driver, config, directParams, deadline, overrides, tried) {
+  for (const app of apps) {
+    if (Date.now() >= deadline) {
+      return void 0;
+    }
+    tried.push(app);
+    const connection = await tryCandidate(app, ctx, driver, config, directParams, deadline, overrides);
+    if (connection !== void 0) {
+      return connection;
+    }
+  }
+  return void 0;
+}
+async function runCandidateLoop(ctx, driver, config, directParams, deadline, hintApp, overrides) {
+  const tried = [];
+  const known = knownCandidates(config.appName, hintApp);
+  const knownConnection = await tryCandidateList(
+    known,
+    ctx,
+    driver,
+    config,
+    directParams,
+    deadline,
+    overrides,
+    tried
+  );
+  if (knownConnection !== void 0) {
+    return { connection: knownConnection, candidatesTried: tried };
+  }
+  const discovered = await discoverExtraCandidates(config, ctx, tried, deadline);
+  const discoveredConnection = await tryCandidateList(
+    discovered,
+    ctx,
+    driver,
+    config,
+    directParams,
+    deadline,
+    overrides,
+    tried
+  );
+  return { connection: discoveredConnection, candidatesTried: tried };
+}
+async function connectWithTunnelFallback(driver, config, overrides = {}) {
+  const directParams = directParamsOf(config);
+  const cacheOptions = overrides.cache ?? {};
+  await discardQuietly(reapStaleAndCrossOrgTunnels(orgKeyOf(config), cacheOptions));
+  const cached = await tryCachedTunnel(driver, config, directParams, cacheOptions);
+  if (cached.connection !== void 0) {
+    return cached.connection;
+  }
+  const direct = await tryDirectConnect(driver, config, directParams);
+  if (direct.connection !== void 0) {
+    return direct.connection;
+  }
+  const deadline = Date.now() + DEFAULT_TUNNEL_FALLBACK_BUDGET_MS;
+  const target = {
+    apiEndpoint: config.apiEndpoint,
+    orgName: config.orgName,
+    spaceName: config.spaceName
+  };
+  const loopResult = await withScopedCfSession(
+    config.selectorSource,
+    target,
+    config.sapCredentials,
+    (ctx) => runCandidateLoop(ctx, driver, config, directParams, deadline, cached.hintApp, overrides)
+  );
+  if (loopResult.connection !== void 0) {
+    return loopResult.connection;
+  }
+  throw buildExhaustionError(config.host, direct.directError, loopResult.candidatesTried);
+}
+
 // src/connection.ts
 function assertValidAutoLimit(value) {
   if (value !== false && (!Number.isSafeInteger(value) || value <= 0 || value >= Number.MAX_SAFE_INTEGER)) {
@@ -3088,15 +3987,7 @@ var Connection = class _Connection {
   driverConnection;
   config;
   static async open(driver, config) {
-    const driverConnection = await driver.connect({
-      host: config.host,
-      port: config.port,
-      user: config.user,
-      password: config.password,
-      schema: config.schema,
-      certificate: config.certificate,
-      connectTimeoutMs: config.connectTimeoutMs
-    });
+    const driverConnection = await connectWithTunnelFallback(driver, config);
     return new _Connection(driverConnection, config);
   }
   async query(sql, params, options) {
@@ -3378,6 +4269,31 @@ function toPoolOptions(options) {
   }
   return options.pool ?? {};
 }
+function buildConnectionConfig(resolved, target, options) {
+  const sapCredentials = readSapCredentials({ email: options.email, password: options.password });
+  return {
+    host: target.host,
+    port: target.port,
+    user: target.user,
+    password: target.password,
+    schema: target.schema,
+    certificate: target.certificate,
+    connectTimeoutMs: options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+    queryTimeoutMs: options.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
+    readOnly: options.readOnly ?? false,
+    allowDestructive: options.allowDestructive ?? false,
+    autoLimit: options.autoLimit ?? DEFAULT_AUTO_LIMIT,
+    appName: resolved.appName,
+    orgName: resolved.orgName,
+    spaceName: resolved.spaceName,
+    apiEndpoint: resolved.apiEndpoint,
+    selectorSource: resolved.selectorSource,
+    tunnelMode: options.tunnel === true ? "always" : "auto",
+    refreshTunnel: options.refreshTunnel ?? false,
+    ...sapCredentials === void 0 ? {} : { sapCredentials },
+    ...options.onTunnelStatus === void 0 ? {} : { onTunnelStatus: options.onTunnelStatus }
+  };
+}
 function toSelectedBindingInfo(bindings, selected) {
   const availableBindingNames = bindings.flatMap(
     (binding) => binding.name === void 0 ? [] : [binding.name]
@@ -3405,19 +4321,7 @@ var HanaClient = class _HanaClient {
     const bindingInfo = toSelectedBindingInfo(resolved.bindings, binding);
     const target = toConnectionTarget(binding, role);
     const driver = createDriver();
-    const config = {
-      host: target.host,
-      port: target.port,
-      user: target.user,
-      password: target.password,
-      schema: target.schema,
-      certificate: target.certificate,
-      connectTimeoutMs: options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
-      queryTimeoutMs: options.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
-      readOnly: options.readOnly ?? false,
-      allowDestructive: options.allowDestructive ?? false,
-      autoLimit: options.autoLimit ?? DEFAULT_AUTO_LIMIT
-    };
+    const config = buildConnectionConfig(resolved, target, options);
     const poolOptions = toPoolOptions(options);
     const info = {
       selector: resolved.selector,
@@ -3614,7 +4518,7 @@ async function connect(selector, options) {
 }
 
 // src/cli-results.ts
-import { writeFile as writeFile4 } from "fs/promises";
+import { writeFile as writeFile5 } from "fs/promises";
 
 // src/result-inspect.ts
 function assertPositiveInteger(name, value) {
@@ -3886,19 +4790,19 @@ function searchResultSession(session, searchTerm, options) {
 
 // src/result-store.ts
 import { randomBytes } from "crypto";
-import { mkdir as mkdir4, readFile as readFile2, readdir as readdir2, rename as rename2, rm as rm4, writeFile as writeFile3 } from "fs/promises";
-import { homedir as homedir4 } from "os";
-import { join as join5 } from "path";
+import { mkdir as mkdir5, readFile as readFile4, readdir as readdir3, rename as rename3, rm as rm6, writeFile as writeFile4 } from "fs/promises";
+import { homedir as homedir5 } from "os";
+import { join as join7 } from "path";
 var RESULT_REF_PATTERN = /^q[0-9a-f]{8}$/;
 var MANIFEST_FILE_NAME = "manifest.json";
 function resultsRoot(saptoolsRoot) {
-  return join5(saptoolsRoot ?? join5(homedir4(), ".saptools"), "cf-hana", "results");
+  return join7(saptoolsRoot ?? join7(homedir5(), ".saptools"), "cf-hana", "results");
 }
 function sessionDirectory(ref, saptoolsRoot) {
-  return join5(resultsRoot(saptoolsRoot), ref);
+  return join7(resultsRoot(saptoolsRoot), ref);
 }
 function manifestPath(ref, saptoolsRoot) {
-  return join5(sessionDirectory(ref, saptoolsRoot), MANIFEST_FILE_NAME);
+  return join7(sessionDirectory(ref, saptoolsRoot), MANIFEST_FILE_NAME);
 }
 function encodeCell(value) {
   if (value === null) {
@@ -3997,11 +4901,11 @@ function toStoredSession(input, ref, now) {
     result: encodeResult(input.result)
   };
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isStoredSession(value) {
-  if (!isRecord3(value) || !isRecord3(value["result"]) || !isRecord3(value["info"])) {
+  if (!isRecord4(value) || !isRecord4(value["result"]) || !isRecord4(value["info"])) {
     return false;
   }
   const result = value["result"];
@@ -4009,7 +4913,7 @@ function isStoredSession(value) {
 }
 async function readStoredSession(path) {
   try {
-    const parsed = JSON.parse(await readFile2(path, "utf8"));
+    const parsed = JSON.parse(await readFile4(path, "utf8"));
     return isStoredSession(parsed) ? parsed : void 0;
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -4028,7 +4932,7 @@ function toSession(stored, saptoolsRoot) {
 }
 async function listSessionRefs(saptoolsRoot) {
   try {
-    const entries = await readdir2(resultsRoot(saptoolsRoot), { withFileTypes: true });
+    const entries = await readdir3(resultsRoot(saptoolsRoot), { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory() && RESULT_REF_PATTERN.test(entry.name)).map((entry) => entry.name);
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -4049,17 +4953,17 @@ async function createResultSession(input, options = {}) {
   const root = resultsRoot(options.saptoolsRoot);
   const finalDirectory = sessionDirectory(ref, options.saptoolsRoot);
   const tempDirectory = `${finalDirectory}.tmp-${process.pid.toString()}`;
-  await mkdir4(root, { recursive: true, mode: 448 });
-  await rm4(tempDirectory, { recursive: true, force: true });
-  await mkdir4(tempDirectory, { mode: 448 });
+  await mkdir5(root, { recursive: true, mode: 448 });
+  await rm6(tempDirectory, { recursive: true, force: true });
+  await mkdir5(tempDirectory, { mode: 448 });
   try {
-    await writeFile3(join5(tempDirectory, MANIFEST_FILE_NAME), serialized, {
+    await writeFile4(join7(tempDirectory, MANIFEST_FILE_NAME), serialized, {
       encoding: "utf8",
       mode: 384
     });
-    await rename2(tempDirectory, finalDirectory);
+    await rename3(tempDirectory, finalDirectory);
   } catch (error) {
-    await rm4(tempDirectory, { recursive: true, force: true });
+    await rm6(tempDirectory, { recursive: true, force: true });
     throw error;
   }
   return toSession(stored, options.saptoolsRoot);
@@ -4102,7 +5006,7 @@ async function pruneResultSessions(options = {}) {
   for (const ref of refs) {
     const stored = await readStoredSession(manifestPath(ref, options.saptoolsRoot));
     if (stored === void 0 || Date.parse(stored.expiresAt) <= now) {
-      await rm4(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
+      await rm6(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
       removed += 1;
     }
   }
@@ -4112,7 +5016,7 @@ async function clearResultSessions(options = {}) {
   const refs = await listSessionRefs(options.saptoolsRoot);
   await Promise.all(
     refs.map(async (ref) => {
-      await rm4(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
+      await rm6(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
     })
   );
   return refs.length;
@@ -4282,7 +5186,7 @@ async function runExport(ref, options) {
   }
   const session = await readResultSession(ref);
   const selected = selectResultCell(session, options.row, options.column);
-  await writeFile4(options.output, cellExportValue(selected.value, selected.typeName), {
+  await writeFile5(options.output, cellExportValue(selected.value, selected.typeName), {
     mode: 384
   });
   print(`wrote=${options.output}`);
@@ -4350,8 +5254,12 @@ function printResolvedTarget(info) {
 `
   );
 }
+function printTunnelStatus(message) {
+  process.stderr.write(`${CLI_NAME}: ${message}
+`);
+}
 async function connectForCli(selector, options) {
-  const client = await connect(selector, options);
+  const client = await connect(selector, { ...options, onTunnelStatus: printTunnelStatus });
   printResolvedTarget(client.info);
   return client;
 }
@@ -4416,6 +5324,8 @@ function toConnectOptions(opts) {
     readOnly: opts.readOnly,
     allowDestructive: opts.allowDestructive,
     autoLimit: opts.autoLimit ? opts.limit ?? DEFAULT_AUTO_LIMIT : false,
+    tunnel: opts.tunnel,
+    refreshTunnel: opts.refreshTunnel,
     ...opts.binding === void 0 ? {} : { bindingName: opts.binding },
     ...opts.bindingIndex === void 0 ? {} : { bindingIndex: opts.bindingIndex },
     ...opts.timeout === void 0 ? {} : { queryTimeoutMs: opts.timeout, connectTimeoutMs: opts.timeout }
@@ -4512,7 +5422,15 @@ function formatInfo(info) {
   ].join("\n");
 }
 function withConnectionOptions(command) {
-  return command.option("--refresh", "deprecated compatibility flag; binding discovery is already live", false).option("--role <role>", "HANA user role: runtime or hdi", "runtime").option("--binding <name>", "select a HANA binding by service name").option("--binding-index <n>", "select a HANA binding by index", parseIntOption2).option("--read-only", "block every DML and DDL statement", false).option("--allow-destructive", "permit destructive statements", false).option("--timeout <ms>", "connection and query timeout in milliseconds", parseIntOption2).option("--limit <n>", "row cap auto-applied to bare SELECT statements", parseIntOption2).option("--no-auto-limit", "disable the automatic SELECT row cap").option("--refresh-metadata", "bypass the 30-minute table/view metadata suggestion cache", false);
+  return command.option("--refresh", "deprecated compatibility flag; binding discovery is already live", false).option("--role <role>", "HANA user role: runtime or hdi", "runtime").option("--binding <name>", "select a HANA binding by service name").option("--binding-index <n>", "select a HANA binding by index", parseIntOption2).option("--read-only", "block every DML and DDL statement", false).option("--allow-destructive", "permit destructive statements", false).option("--timeout <ms>", "connection and query timeout in milliseconds", parseIntOption2).option("--limit <n>", "row cap auto-applied to bare SELECT statements", parseIntOption2).option("--no-auto-limit", "disable the automatic SELECT row cap").option("--refresh-metadata", "bypass the 30-minute table/view metadata suggestion cache", false).option(
+    "--tunnel",
+    "skip the direct connection attempt and connect via an SSH tunnel immediately",
+    false
+  ).option(
+    "--refresh-tunnel",
+    "bypass a cached/live SSH tunnel and force a fresh establishment attempt",
+    false
+  );
 }
 function withFormattedConnectionOptions(command) {
   return withConnectionOptions(command).option(