@saptools/cf-hana 0.2.1 → 0.3.0

package/dist/cli.js

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { formatCurrentCfAppSelector, readCurrentCfTarget } from "@saptools/cf-sync";
 import { Command } from "commander";
 
 // src/backup.ts
-import { createHash, randomUUID } from "crypto";
 import { mkdir, writeFile } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
@@ -53,6 +51,15 @@ function errorMessage(error) {
   return String(error);
 }
 
+// src/lob.ts
+var TEXT_LOB_TYPES = /* @__PURE__ */ new Set(["CLOB", "NCLOB"]);
+function normalizeTypeName(typeName2) {
+  return typeName2?.trim().toUpperCase() ?? "";
+}
+function isTextLobType(typeName2) {
+  return TEXT_LOB_TYPES.has(normalizeTypeName(typeName2));
+}
+
 // src/result-preview.ts
 function normalizePreviewChar(value) {
   return value === "\r" || value === "\n" || value === "	" ? " " : value;
@@ -93,12 +100,12 @@ function scalarText(value) {
   }
   return value.toString();
 }
-function previewCell(value, limit) {
+function previewCell(value, limit, typeName2) {
   if (value === null) {
     return { text: "", truncated: false, originalLength: 0, unit: "chars" };
   }
   if (Buffer.isBuffer(value)) {
-    return previewBuffer(value, limit);
+    return isTextLobType(typeName2) ? previewText(value.toString("utf8"), limit) : previewBuffer(value, limit);
   }
   if (typeof value === "string") {
     return previewText(value, limit);
@@ -107,7 +114,7 @@ function previewCell(value, limit) {
 }
 
 // src/format.ts
-function cellText(value, nullText) {
+function cellText(value, nullText, column) {
   if (value === null) {
     return nullText;
   }
@@ -115,14 +122,14 @@ function cellText(value, nullText) {
     return value.toISOString();
   }
   if (Buffer.isBuffer(value)) {
-    return `0x${value.toString("hex")}`;
+    return isTextLobType(column?.typeName) ? value.toString("utf8") : `0x${value.toString("hex")}`;
   }
   if (typeof value === "boolean") {
     return value ? "true" : "false";
   }
   return typeof value === "number" ? value.toString() : value;
 }
-function serializeCell(value) {
+function serializeCell(value, column) {
   if (value === null) {
     return null;
   }
@@ -130,7 +137,7 @@ function serializeCell(value) {
     return value.toISOString();
   }
   if (Buffer.isBuffer(value)) {
-    return `0x${value.toString("hex")}`;
+    return isTextLobType(column?.typeName) ? value.toString("utf8") : `0x${value.toString("hex")}`;
   }
   return value;
 }
@@ -146,7 +153,7 @@ function formatTable(result) {
   }
   const headers = result.columns.map((column) => column.name);
   const rows = result.rows.map(
-    (row) => result.columns.map((column) => cellText(row[column.name] ?? null, "NULL"))
+    (row) => result.columns.map((column) => cellText(row[column.name] ?? null, "NULL", column))
   );
   const widths = headers.map((header, index) => {
     const widest = rows.reduce(
@@ -164,7 +171,8 @@ function formatJson(result) {
   const rows = result.rows.map((row) => {
     const serialized = {};
     for (const [key, value] of Object.entries(row)) {
-      serialized[key] = serializeCell(value);
+      const column = result.columns.find((item) => item.name === key);
+      serialized[key] = serializeCell(value, column);
     }
     return serialized;
   });
@@ -175,7 +183,7 @@ function formatCsv(result) {
   const lines = [headers.map((header) => csvEscape(header)).join(",")];
   for (const row of result.rows) {
     lines.push(
-      result.columns.map((column) => csvEscape(cellText(row[column.name] ?? null, ""))).join(",")
+      result.columns.map((column) => csvEscape(cellText(row[column.name] ?? null, "", column))).join(",")
     );
   }
   return lines.join("\r\n");
@@ -186,7 +194,7 @@ function formatCompactCsv(result, cellLimit) {
   let truncatedCells = 0;
   for (const row of result.rows) {
     const cells = result.columns.map((column) => {
-      const preview = previewCell(row[column.name] ?? null, cellLimit);
+      const preview = previewCell(row[column.name] ?? null, cellLimit, column.typeName);
       if (preview.truncated) {
         truncatedCells += 1;
       }
@@ -375,6 +383,28 @@ function findTopLevelKeyword(sql, keyword, startIndex = 0) {
   }
   return void 0;
 }
+function findTopLevelChar(sql, target, startIndex, endIndex) {
+  let index = startIndex;
+  let depth = 0;
+  while (index < endIndex) {
+    const skipped = skipNonCode(sql, index);
+    if (skipped !== void 0) {
+      index = skipped;
+      continue;
+    }
+    const char = sql[index];
+    if (char === target && depth === 0) {
+      return index;
+    }
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")" && depth > 0) {
+      depth -= 1;
+    }
+    index += 1;
+  }
+  return void 0;
+}
 function selectParamsAfterWhere(statementSql, whereIndex, params) {
   return params.slice(countPlaceholders(statementSql.slice(0, whereIndex)));
 }
@@ -412,6 +442,24 @@ function buildUpdateBackupPlan(statementSql, params) {
     params
   );
 }
+function buildUpsertBackupPlan(statementSql, params) {
+  const upsertIndex = findTopLevelKeyword(statementSql, "UPSERT");
+  const valuesIndex = upsertIndex === void 0 ? void 0 : findTopLevelKeyword(statementSql, "VALUES", upsertIndex + "UPSERT".length);
+  if (upsertIndex === void 0 || valuesIndex === void 0) {
+    throw new QueryError("UPSERT backup requires UPSERT <target> VALUES syntax");
+  }
+  const targetStart = upsertIndex + "UPSERT".length;
+  const columnListIndex = findTopLevelChar(statementSql, "(", targetStart, valuesIndex);
+  const targetEnd = columnListIndex ?? valuesIndex;
+  const whereIndex = findTopLevelKeyword(statementSql, "WHERE", valuesIndex + "VALUES".length);
+  return buildSelectPlan(
+    "upsert",
+    statementSql,
+    statementSql.slice(targetStart, targetEnd),
+    whereIndex,
+    params
+  );
+}
 function buildDeleteBackupPlan(statementSql, params) {
   const deleteIndex = findTopLevelKeyword(statementSql, "DELETE");
   const fromIndex = deleteIndex === void 0 ? void 0 : findTopLevelKeyword(statementSql, "FROM", deleteIndex + "DELETE".length);
@@ -431,8 +479,18 @@ function buildDeleteBackupPlan(statementSql, params) {
 function backupTimestamp(now) {
   return now.toISOString().replace(/:/g, "").replace(".", "");
 }
-function backupHash(statementSql) {
-  return createHash("sha256").update(statementSql).update("\0").update(randomUUID()).digest("hex").slice(0, 12);
+function backupMonth(now) {
+  const year = String(now.getUTCFullYear());
+  const month = String(now.getUTCMonth() + 1).padStart(2, "0");
+  return `${year}${month}`;
+}
+function sanitizePathPart(value) {
+  const trimmed = value?.trim() ?? "";
+  const normalized = trimmed.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return normalized.length > 0 ? normalized : "unknown-target";
+}
+function backupBaseName(input, now) {
+  return [sanitizePathPart(input.selector), input.operation, backupTimestamp(now)].join("-");
 }
 function cfHanaBackupRoot(saptoolsRoot) {
   return join(saptoolsRoot ?? defaultSaptoolsRoot(), CF_HANA_DIR_NAME, BACKUPS_DIR_NAME);
@@ -440,33 +498,49 @@ function cfHanaBackupRoot(saptoolsRoot) {
 function buildWriteBackupPlan(sql, params = []) {
   const statementSql = trimStatementSql(sql);
   const keyword = firstKeyword(statementSql);
-  if (keyword !== "UPDATE" && keyword !== "DELETE") {
+  if (keyword !== "UPDATE" && keyword !== "UPSERT" && keyword !== "DELETE") {
     return void 0;
   }
   assertParamArity(statementSql, params);
   if (keyword === "UPDATE") {
     return buildUpdateBackupPlan(statementSql, params);
   }
+  if (keyword === "UPSERT") {
+    return buildUpsertBackupPlan(statementSql, params);
+  }
   return buildDeleteBackupPlan(statementSql, params);
 }
 async function writeSqlBackup(input, options = {}) {
   const now = options.now ?? /* @__PURE__ */ new Date();
-  const directory = join(
-    cfHanaBackupRoot(options.saptoolsRoot),
-    `${backupTimestamp(now)}-${input.operation}-${backupHash(input.statementSql)}`
-  );
-  const statementPath = join(directory, "statement.sql");
-  const backupPath = join(directory, "backup.csv");
+  const directory = join(cfHanaBackupRoot(options.saptoolsRoot), backupMonth(now));
+  const baseName = backupBaseName(input, now);
+  const statementPath = join(directory, `${baseName}.statement.sql`);
+  const backupPath = join(directory, `${baseName}.sql`);
+  const metadataPath = join(directory, `${baseName}.json`);
+  const metadata = {
+    selector: input.selector ?? null,
+    operation: input.operation,
+    statementPath,
+    backupPath,
+    rowCount: input.result.rowCount,
+    createdAt: now.toISOString()
+  };
   await mkdir(directory, { recursive: true, mode: 448 });
   await Promise.all([
     writeFile(statementPath, `${input.statementSql}
 `, { encoding: "utf8", mode: 384 }),
-    writeFile(backupPath, formatCsv(input.result), { encoding: "utf8", mode: 384 })
+    writeFile(backupPath, formatCsv(input.result), { encoding: "utf8", mode: 384 }),
+    writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}
+`, {
+      encoding: "utf8",
+      mode: 384
+    })
   ]);
   return {
     directory,
     statementPath,
     backupPath,
+    metadataPath,
     rowCount: input.result.rowCount
   };
 }
@@ -570,6 +644,18 @@ async function listTables(connection, schema) {
     rowCount: void 0
   }));
 }
+async function listCatalogObjects(connection, schema) {
+  const result = await connection.query(
+    "SELECT SCHEMA_NAME, TABLE_NAME AS OBJECT_NAME, 'TABLE' AS OBJECT_TYPE FROM SYS.TABLES WHERE SCHEMA_NAME = ? UNION ALL SELECT SCHEMA_NAME, VIEW_NAME AS OBJECT_NAME, 'VIEW' AS OBJECT_TYPE FROM SYS.VIEWS WHERE SCHEMA_NAME = ? ORDER BY OBJECT_NAME",
+    [schema, schema],
+    { autoLimit: false }
+  );
+  return result.rows.map((row) => ({
+    schema: row.SCHEMA_NAME,
+    name: row.OBJECT_NAME,
+    type: row.OBJECT_TYPE
+  }));
+}
 async function listColumns(connection, schema, table) {
   const result = await connection.query(
     "SELECT COLUMN_NAME, DATA_TYPE_NAME, LENGTH, SCALE, IS_NULLABLE, POSITION FROM SYS.TABLE_COLUMNS WHERE SCHEMA_NAME = ? AND TABLE_NAME = ? ORDER BY POSITION",
@@ -588,7 +674,7 @@ async function listColumns(connection, schema, table) {
 
 // src/config.ts
 var CLI_NAME = "cf-hana";
-var CLI_VERSION = "0.2.1";
+var CLI_VERSION = "0.3.0";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -620,44 +706,381 @@ function readSapCredentials(overrides) {
   return { email, password };
 }
 
-// src/credentials.ts
-import { fetchAppDbBindings, readDbAppView } from "@saptools/cf-sync";
-async function resolveAppBindings(selector, options) {
-  if (options.refresh !== true) {
-    const view = await readDbAppView(selector);
-    if (view !== void 0 && view.entry.bindings.length > 0) {
-      return {
-        selector: view.entry.selector,
-        appName: view.entry.appName,
-        bindings: view.entry.bindings,
-        source: "cache"
-      };
+// src/cf.ts
+import { execFile } from "child_process";
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var MAX_BUFFER = 16 * 1024 * 1024;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var CF_RETRY_ATTEMPTS = 3;
+var CF_RETRY_BASE_DELAY_MS = 120;
+var REGION_API_MAP = {
+  ae01: "https://api.cf.ae01.hana.ondemand.com",
+  ap01: "https://api.cf.ap01.hana.ondemand.com",
+  ap10: "https://api.cf.ap10.hana.ondemand.com",
+  ap11: "https://api.cf.ap11.hana.ondemand.com",
+  ap12: "https://api.cf.ap12.hana.ondemand.com",
+  ap20: "https://api.cf.ap20.hana.ondemand.com",
+  ap21: "https://api.cf.ap21.hana.ondemand.com",
+  ap30: "https://api.cf.ap30.hana.ondemand.com",
+  br10: "https://api.cf.br10.hana.ondemand.com",
+  br20: "https://api.cf.br20.hana.ondemand.com",
+  br30: "https://api.cf.br30.hana.ondemand.com",
+  ca10: "https://api.cf.ca10.hana.ondemand.com",
+  ca20: "https://api.cf.ca20.hana.ondemand.com",
+  ch20: "https://api.cf.ch20.hana.ondemand.com",
+  eu10: "https://api.cf.eu10.hana.ondemand.com",
+  eu11: "https://api.cf.eu11.hana.ondemand.com",
+  eu12: "https://api.cf.eu12.hana.ondemand.com",
+  eu20: "https://api.cf.eu20.hana.ondemand.com",
+  eu21: "https://api.cf.eu21.hana.ondemand.com",
+  eu30: "https://api.cf.eu30.hana.ondemand.com",
+  "eu10-002": "https://api.cf.eu10-002.hana.ondemand.com",
+  jp10: "https://api.cf.jp10.hana.ondemand.com",
+  jp20: "https://api.cf.jp20.hana.ondemand.com",
+  jp30: "https://api.cf.jp30.hana.ondemand.com",
+  us10: "https://api.cf.us10.hana.ondemand.com",
+  us11: "https://api.cf.us11.hana.ondemand.com",
+  us20: "https://api.cf.us20.hana.ondemand.com",
+  us21: "https://api.cf.us21.hana.ondemand.com",
+  us30: "https://api.cf.us30.hana.ondemand.com",
+  in30: "https://api.cf.in30.hana.ondemand.com"
+};
+function getApiEndpointForRegion(regionKey) {
+  return REGION_API_MAP[regionKey];
+}
+function getRegionKeyForApi(apiEndpoint) {
+  const norm2 = apiEndpoint.trim().replace(/\/+$/, "").toLowerCase();
+  for (const [key, endpoint] of Object.entries(REGION_API_MAP)) {
+    if (endpoint.toLowerCase() === norm2) {
+      return key;
+    }
+  }
+  return void 0;
+}
+async function withCfSession(work) {
+  const cfHome = await mkdtemp(join2(tmpdir(), "saptools-cf-hana-"));
+  const ctx = { cfHome };
+  try {
+    return await work(ctx);
+  } finally {
+    await rm(cfHome, { recursive: true, force: true });
+  }
+}
+function resolveCfBin() {
+  const raw = process.env["CF_HANA_CF_BIN"] ?? "cf";
+  if (/\.(?:c|m)?js$/i.test(raw)) {
+    return { bin: process.execPath, argsPrefix: [raw] };
+  }
+  return { bin: raw, argsPrefix: [] };
+}
+function buildEnv(ctx, overrides = {}) {
+  const env = { ...process.env, ...overrides };
+  delete env["SAP_EMAIL"];
+  delete env["SAP_PASSWORD"];
+  env["CF_HOME"] = ctx.cfHome;
+  return env;
+}
+async function runCf(args, ctx, overrides = {}) {
+  const { bin, argsPrefix } = resolveCfBin();
+  const env = buildEnv(ctx, overrides);
+  let lastErr;
+  for (let attempt = 0; attempt < CF_RETRY_ATTEMPTS; attempt++) {
+    try {
+      const { stdout } = await execFileAsync(bin, [...argsPrefix, ...args], {
+        env,
+        maxBuffer: MAX_BUFFER,
+        timeout: DEFAULT_TIMEOUT_MS
+      });
+      return stdout;
+    } catch (err) {
+      lastErr = err;
+      if (attempt < CF_RETRY_ATTEMPTS - 1) {
+        await new Promise((r) => setTimeout(r, CF_RETRY_BASE_DELAY_MS * (attempt + 1)));
+      }
     }
   }
-  const credentials = readSapCredentials({
-    email: options.email,
-    password: options.password
+  const e = lastErr;
+  const detail = e?.stderr ? String(e.stderr) : e?.message ?? "";
+  const cmd = args[0] === "auth" ? "cf auth" : `cf ${args.join(" ")}`;
+  throw new Error(`${cmd} failed: ${detail}`.trim(), { cause: lastErr });
+}
+async function cfApi(apiEndpoint, ctx) {
+  await runCf(["api", apiEndpoint], ctx);
+}
+async function cfAuth(email, password, ctx) {
+  await runCf(["auth"], ctx, {
+    CF_USERNAME: email,
+    CF_PASSWORD: password
   });
-  if (credentials === void 0) {
-    throw new CredentialsNotFoundError(
-      `No cached HANA credentials for "${selector}". Run \`cf-sync db-sync ${selector}\` first, or set SAP_EMAIL and SAP_PASSWORD to fetch them live.`
+}
+async function cfTargetSpace(orgName, spaceName, ctx) {
+  await runCf(["target", "-o", orgName, "-s", spaceName], ctx);
+}
+async function cfEnv(appName, ctx) {
+  return await runCf(["env", appName], ctx);
+}
+async function cfEnvDirect(appName) {
+  const { bin, argsPrefix } = resolveCfBin();
+  const env = { ...process.env };
+  delete env["SAP_EMAIL"];
+  delete env["SAP_PASSWORD"];
+  const { stdout } = await execFileAsync(bin, [...argsPrefix, "env", appName], {
+    env,
+    maxBuffer: MAX_BUFFER,
+    timeout: DEFAULT_TIMEOUT_MS
+  });
+  return stdout;
+}
+async function readCurrentCfTarget() {
+  const { bin, argsPrefix } = resolveCfBin();
+  const env = { ...process.env };
+  delete env["SAP_EMAIL"];
+  delete env["SAP_PASSWORD"];
+  try {
+    const { stdout } = await execFileAsync(bin, [...argsPrefix, "target"], {
+      env,
+      maxBuffer: MAX_BUFFER,
+      timeout: 1e4
+    });
+    return parseCfTargetOutput(stdout);
+  } catch {
+    return void 0;
+  }
+}
+function parseCfTargetOutput(stdout) {
+  const fields = parseTargetFields(stdout);
+  const api = fields.get("api endpoint");
+  const org = fields.get("org");
+  const space = fields.get("space");
+  if (!api || !org || !space) {
+    return void 0;
+  }
+  const regionKey = getRegionKeyForApi(api);
+  return {
+    apiEndpoint: api,
+    orgName: org,
+    spaceName: space,
+    ...regionKey ? { regionKey } : {}
+  };
+}
+function parseTargetFields(stdout) {
+  const map = /* @__PURE__ */ new Map();
+  for (const line of stdout.split(/\r?\n/)) {
+    const idx = line.indexOf(":");
+    if (idx < 0) {
+      continue;
+    }
+    const key = line.slice(0, idx).trim().toLowerCase();
+    const val = line.slice(idx + 1).trim();
+    if (key && val) {
+      map.set(key, val);
+    }
+  }
+  return map;
+}
+function formatCurrentCfAppSelector(target, appName) {
+  const name = appName.trim();
+  if (!name) {
+    throw new Error("App name is required.");
+  }
+  if (!target.regionKey) {
+    throw new Error(
+      `Current CF API endpoint "${target.apiEndpoint}" does not match a known SAP region. Pass a full region/org/space/app selector.`
     );
   }
-  const fetched = await fetchAppDbBindings({
-    selector,
-    email: credentials.email,
-    password: credentials.password
+  return `${target.regionKey}/${target.orgName}/${target.spaceName}/${name}`;
+}
+function extractVcapSection(stdout) {
+  const start = stdout.indexOf("VCAP_SERVICES:");
+  if (start === -1) {
+    throw new Error("VCAP_SERVICES section not found in cf env output");
+  }
+  const after = stdout.slice(start + "VCAP_SERVICES:".length);
+  const end = after.indexOf("VCAP_APPLICATION:");
+  const block = end === -1 ? after : after.slice(0, end);
+  return block.trim();
+}
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function assertCreds(raw) {
+  if (!isRecord(raw)) {
+    throw new Error("HANA credentials must be an object");
+  }
+  const req = ["host", "port", "user", "password", "schema", "hdi_user", "hdi_password", "url", "database_id", "certificate"];
+  for (const k of req) {
+    if (typeof raw[k] !== "string") {
+      throw new Error(`Missing/invalid HANA credential field: "${k}"`);
+    }
+  }
+  return raw;
+}
+function mapCreds(raw) {
+  return {
+    host: raw.host,
+    port: raw.port,
+    user: raw.user,
+    password: raw.password,
+    schema: raw.schema,
+    hdiUser: raw.hdi_user,
+    hdiPassword: raw.hdi_password,
+    ...raw.url ? { url: raw.url } : {},
+    databaseId: raw.database_id,
+    certificate: raw.certificate
+  };
+}
+function extractHanaBindingsFromCfEnv(stdout) {
+  const jsonText = extractVcapSection(stdout);
+  let vcap;
+  try {
+    vcap = JSON.parse(jsonText);
+  } catch {
+    throw new Error("VCAP_SERVICES is not valid JSON");
+  }
+  if (!isRecord(vcap)) {
+    throw new Error("VCAP_SERVICES must be an object");
+  }
+  const hana = vcap["hana"];
+  if (hana === void 0) {
+    return [];
+  }
+  if (!Array.isArray(hana)) {
+    throw new Error("VCAP_SERVICES.hana must be an array when present");
+  }
+  return hana.map((b) => {
+    if (!isRecord(b)) {
+      throw new Error("HANA binding must be an object");
+    }
+    const credsRaw = assertCreds(b["credentials"]);
+    const name = typeof b["name"] === "string" ? b["name"] : void 0;
+    return {
+      ...name ? { name } : {},
+      credentials: mapCreds(credsRaw)
+    };
   });
-  if (fetched.bindings.length === 0) {
-    throw new CredentialsNotFoundError(
-      `App "${fetched.selector}" has no HANA service binding.`
-    );
+}
+function classifyCfError(stderr = "", stdout = "") {
+  const text = `${stderr} ${stdout}`.toLowerCase();
+  if (text.includes("not logged in") || text.includes("unauthorized") || text.includes("forbidden") || text.includes("credentials were rejected") || text.includes("authentication failed") || text.includes("cf auth") || text.includes("token") || text.includes("expired") || text.includes("session")) {
+    return { isAuthError: true, reason: "auth/session issue" };
+  }
+  return { isAuthError: false, reason: "" };
+}
+
+// src/credentials.ts
+async function resolveAppBindings(rawSelector, options) {
+  const selector = rawSelector.trim();
+  if (!selector) {
+    throw new CfHanaError("CONFIG", "App selector is required");
+  }
+  let target;
+  const isBare = !selector.includes("/");
+  if (isBare) {
+    const current = await readCurrentCfTarget();
+    if (!current) {
+      throw new CfHanaError(
+        "CONFIG",
+        "No current CF target found. Run `cf target -o <org> -s <space>` or pass a full region/org/space/app selector."
+      );
+    }
+    const displaySelector = current.regionKey ? formatCurrentCfAppSelector(current, selector) : `current/${current.orgName}/${current.spaceName}/${selector}`;
+    target = {
+      selector: displaySelector,
+      apiEndpoint: current.regionKey ? getApiEndpointForRegion(current.regionKey) : void 0,
+      orgName: current.orgName,
+      spaceName: current.spaceName,
+      appName: selector
+    };
+  } else {
+    const parts = selector.split("/").map((p) => p.trim());
+    if (parts.length !== 4 || !parts[0] || !parts[1] || !parts[2] || !parts[3]) {
+      throw new CfHanaError(
+        "CONFIG",
+        `Invalid selector "${selector}". Use region/org/space/app or a bare app name.`
+      );
+    }
+    const [regionKey, orgName, spaceName, appName] = parts;
+    const apiEndpoint = getApiEndpointForRegion(regionKey);
+    if (!apiEndpoint) {
+      throw new CfHanaError(
+        "CONFIG",
+        `Unknown region key "${regionKey}". Use a known region or the current CF target.`
+      );
+    }
+    target = { selector, apiEndpoint, orgName, spaceName, appName };
+  }
+  let bindings;
+  const source = "live";
+  if (isBare) {
+    try {
+      const stdout = await cfEnvDirect(target.appName);
+      bindings = extractHanaBindingsFromCfEnv(stdout);
+    } catch (directError) {
+      let stderr = "";
+      if (directError && typeof directError === "object") {
+        const e = directError;
+        stderr = (typeof e.stderr === "string" ? e.stderr : "") || (typeof e.message === "string" ? e.message : "");
+      }
+      const classified = classifyCfError(stderr);
+      if (classified.isAuthError) {
+        const sap = readSapCredentials({ email: options.email, password: options.password });
+        if (!sap) {
+          throw new CredentialsNotFoundError(
+            `Current CF session problem for bare app "${target.appName}" (${classified.reason}).
+Run "cf login" + "cf target", or provide SAP_EMAIL + SAP_PASSWORD.`,
+            { cause: directError }
+          );
+        }
+        if (!target.apiEndpoint) {
+          throw new CfHanaError("CONFIG", "Cannot determine API endpoint for fallback auth.");
+        }
+        const api = target.apiEndpoint;
+        bindings = await withCfSession(async (ctx) => {
+          await cfApi(api, ctx);
+          await cfAuth(sap.email, sap.password, ctx);
+          await cfTargetSpace(target.orgName, target.spaceName, ctx);
+          const stdout = await cfEnv(target.appName, ctx);
+          return extractHanaBindingsFromCfEnv(stdout);
+        });
+      } else {
+        throw new CfHanaError(
+          "CONFIG",
+          `Failed to get HANA bindings for bare app "${target.appName}" using current target (org=${target.orgName}, space=${target.spaceName}). Verify with "cf target" and "cf env ${target.appName}". ${stderr ? `Details: ${stderr}` : ""}`,
+          { cause: directError }
+        );
+      }
+    }
+  } else {
+    const sap = readSapCredentials({ email: options.email, password: options.password });
+    if (!sap) {
+      throw new CredentialsNotFoundError(
+        `SAP_EMAIL and SAP_PASSWORD are required to fetch HANA bindings for explicit selector "${selector}".`
+      );
+    }
+    if (!target.apiEndpoint) {
+      throw new CfHanaError("CONFIG", "Invalid explicit selector.");
+    }
+    const api = target.apiEndpoint;
+    bindings = await withCfSession(async (ctx) => {
+      await cfApi(api, ctx);
+      await cfAuth(sap.email, sap.password, ctx);
+      await cfTargetSpace(target.orgName, target.spaceName, ctx);
+      const stdout = await cfEnv(target.appName, ctx);
+      return extractHanaBindingsFromCfEnv(stdout);
+    });
+  }
+  if (bindings.length === 0) {
+    throw new CredentialsNotFoundError(`App "${target.selector}" has no HANA service binding.`);
   }
   return {
-    selector: fetched.selector,
-    appName: fetched.appName,
-    bindings: fetched.bindings,
-    source: "fresh"
+    selector: target.selector,
+    appName: target.appName,
+    bindings,
+    source
   };
 }
 function selectBinding(bindings, selector) {
@@ -707,18 +1130,63 @@ function toConnectionTarget(binding, role) {
     password: role === "hdi" ? credentials.hdiPassword : credentials.password,
     schema: credentials.schema,
     certificate: credentials.certificate,
-    databaseId: credentials.databaseId
+    databaseId: credentials.databaseId ?? ""
   };
 }
 
 // src/driver/fake.ts
 import { appendFile } from "fs/promises";
+var catalogFailureInjected = false;
+function catalogObjects() {
+  return [
+    { SCHEMA_NAME: "APP_SCHEMA", OBJECT_NAME: "EXISTING_TABLE", OBJECT_TYPE: "TABLE" },
+    { SCHEMA_NAME: "APP_SCHEMA", OBJECT_NAME: "MISSING_TABLE_FIXED", OBJECT_TYPE: "TABLE" },
+    { SCHEMA_NAME: "APP_SCHEMA", OBJECT_NAME: "MISSING_TABLE_VIEW", OBJECT_TYPE: "VIEW" },
+    { SCHEMA_NAME: "APP_SCHEMA", OBJECT_NAME: "STATUS_ITEMS", OBJECT_TYPE: "TABLE" }
+  ];
+}
 function fakeExec(sql) {
   const kind = classifyStatement(sql);
   const forcedFailure = readEnv(envName("FAKE_FAIL_STATEMENT"))?.toLowerCase();
   if (forcedFailure === kind) {
     throw new Error(`fake driver forced ${kind.toUpperCase()} failure`);
   }
+  const upperSql = sql.toUpperCase();
+  if (upperSql.includes("SYS.TABLES") && upperSql.includes("SYS.VIEWS")) {
+    if (readEnv(envName("FAKE_FAIL_CATALOG_ONCE")) === "1" && !catalogFailureInjected) {
+      catalogFailureInjected = true;
+      throw new QueryError("fake transient catalog metadata failure");
+    }
+    return {
+      rows: catalogObjects(),
+      columns: [
+        { name: "SCHEMA_NAME", typeName: "NVARCHAR" },
+        { name: "OBJECT_NAME", typeName: "NVARCHAR" },
+        { name: "OBJECT_TYPE", typeName: "NVARCHAR" }
+      ],
+      affectedRows: 0
+    };
+  }
+  if (upperSql.includes("MISSING_TABLE") || upperSql.includes("MISSING_TABLES")) {
+    throw new QueryError("invalid table name: MISSING_TABLE", { sqlState: "42S02" });
+  }
+  if (sql.toUpperCase().includes("LOB_FIXTURE")) {
+    return {
+      rows: [
+        {
+          LOG_CONTENT: Buffer.from("Example log entry", "utf8"),
+          CLOB_CONTENT: Buffer.from("Clob log entry", "utf8"),
+          PAYLOAD: Buffer.from([0, 1, 2, 255])
+        }
+      ],
+      columns: [
+        { name: "LOG_CONTENT", typeName: "NCLOB" },
+        { name: "CLOB_CONTENT", typeName: "CLOB" },
+        { name: "PAYLOAD", typeName: "BLOB" }
+      ],
+      affectedRows: 0
+    };
+  }
   if (sql.toUpperCase().includes("DUMMY")) {
     return {
       rows: [{ "1": 1 }],
@@ -1034,16 +1502,16 @@ function createDriver(name) {
 }
 
 // src/history.ts
-import { appendFile as appendFile2, mkdir as mkdir2, readdir, rm } from "fs/promises";
+import { appendFile as appendFile2, mkdir as mkdir2, readdir, rm as rm2 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 var SAPTOOLS_DIR_NAME2 = ".saptools";
 var CF_HANA_DIR_NAME2 = "cf-hana";
 var HISTORIES_DIR_NAME = "histories";
 var HISTORY_RETENTION_DAYS = 5;
 var HISTORY_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
 function defaultSaptoolsRoot2() {
-  return join2(homedir2(), SAPTOOLS_DIR_NAME2);
+  return join3(homedir2(), SAPTOOLS_DIR_NAME2);
 }
 function padDatePart(value) {
   return value.toString().padStart(2, "0");
@@ -1065,10 +1533,10 @@ function resolveSaptoolsRoot(root) {
   return root ?? defaultSaptoolsRoot2();
 }
 function cfHanaHistoryDirectory(saptoolsRoot) {
-  return join2(resolveSaptoolsRoot(saptoolsRoot), CF_HANA_DIR_NAME2, HISTORIES_DIR_NAME);
+  return join3(resolveSaptoolsRoot(saptoolsRoot), CF_HANA_DIR_NAME2, HISTORIES_DIR_NAME);
 }
 function sqlHistoryFilePath(now = /* @__PURE__ */ new Date(), saptoolsRoot) {
-  return join2(cfHanaHistoryDirectory(saptoolsRoot), `${dateKey(now)}.jsonl`);
+  return join3(cfHanaHistoryDirectory(saptoolsRoot), `${dateKey(now)}.jsonl`);
 }
 async function pruneSqlHistory(now, saptoolsRoot) {
   const historyDir = cfHanaHistoryDirectory(saptoolsRoot);
@@ -1084,7 +1552,7 @@ async function pruneSqlHistory(now, saptoolsRoot) {
   const cutoffKey = retentionCutoffKey(now);
   await Promise.all(
     files.filter((file) => HISTORY_FILE_PATTERN.test(file)).filter((file) => file.slice(0, 10) < cutoffKey).map(async (file) => {
-      await rm(join2(historyDir, file), { force: true });
+      await rm2(join3(historyDir, file), { force: true });
     })
   );
 }
@@ -1655,7 +2123,8 @@ var HanaClient = class _HanaClient {
       return await writeSqlBackup({
         operation: plan.operation,
         statementSql: plan.statementSql,
-        result
+        result,
+        selector: this.info.selector
       });
     });
   }
@@ -1717,6 +2186,10 @@ var HanaClient = class _HanaClient {
   async listTables(schema) {
     return await this.pool.withConnection((connection) => listTables(connection, schema));
   }
+  /** List table and view names in a schema for typo suggestions. */
+  async listCatalogObjects(schema) {
+    return await this.pool.withConnection((connection) => listCatalogObjects(connection, schema));
+  }
   /** List the columns of a table. */
   async listColumns(schema, table) {
     return await this.pool.withConnection(
@@ -1842,12 +2315,15 @@ function textRange(value, offset, length) {
   }
   return { type: "text", originalLength: index, offset, value: selected };
 }
-function readCellWindow(value, offset, length) {
+function readCellWindow(value, offset, length, typeName2) {
   if (!Number.isSafeInteger(offset) || offset < 0) {
     throw new CfHanaError("CONFIG", "offset must be a non-negative safe integer");
   }
   assertPositiveInteger("length", length);
   if (Buffer.isBuffer(value)) {
+    if (isTextLobType(typeName2)) {
+      return textRange(value.toString("utf8"), offset, length);
+    }
     return {
       type: "binary",
       originalLength: value.length,
@@ -2019,18 +2495,19 @@ function jsonSearchMatches(root, term, row, column, limit, previewLength) {
   }
   return matches;
 }
-function searchCell(value, term, row, column, limit, previewLength) {
-  if (typeof value !== "string") {
+function searchCell(value, term, row, column, typeName2, limit, previewLength) {
+  const text = Buffer.isBuffer(value) && isTextLobType(typeName2) ? value.toString("utf8") : value;
+  if (typeof text !== "string") {
     return [];
   }
   try {
-    const parsed = JSON.parse(value);
+    const parsed = JSON.parse(text);
     if (typeof parsed === "object" && parsed !== null) {
       return jsonSearchMatches(parsed, term, row, column, limit, previewLength);
     }
   } catch {
   }
-  return plainTextMatches(value, term, row, column, limit, previewLength);
+  return plainTextMatches(text, term, row, column, limit, previewLength);
 }
 function searchResultSession(session, searchTerm, options) {
   assertPositiveInteger("limit", options.limit);
@@ -2052,6 +2529,7 @@ function searchResultSession(session, searchTerm, options) {
           term,
           item.rowNumber,
           column.name,
+          column.typeName,
           remaining,
           previewLength
         )
@@ -2066,19 +2544,19 @@ function searchResultSession(session, searchTerm, options) {
 
 // src/result-store.ts
 import { randomBytes } from "crypto";
-import { mkdir as mkdir3, readFile, readdir as readdir2, rename, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir3, readFile, readdir as readdir2, rename, rm as rm3, writeFile as writeFile2 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 var RESULT_REF_PATTERN = /^q[0-9a-f]{8}$/;
 var MANIFEST_FILE_NAME = "manifest.json";
 function resultsRoot(saptoolsRoot) {
-  return join3(saptoolsRoot ?? join3(homedir3(), ".saptools"), "cf-hana", "results");
+  return join4(saptoolsRoot ?? join4(homedir3(), ".saptools"), "cf-hana", "results");
 }
 function sessionDirectory(ref, saptoolsRoot) {
-  return join3(resultsRoot(saptoolsRoot), ref);
+  return join4(resultsRoot(saptoolsRoot), ref);
 }
 function manifestPath(ref, saptoolsRoot) {
-  return join3(sessionDirectory(ref, saptoolsRoot), MANIFEST_FILE_NAME);
+  return join4(sessionDirectory(ref, saptoolsRoot), MANIFEST_FILE_NAME);
 }
 function encodeCell(value) {
   if (value === null) {
@@ -2177,11 +2655,11 @@ function toStoredSession(input, ref, now) {
     result: encodeResult(input.result)
   };
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isStoredSession(value) {
-  if (!isRecord(value) || !isRecord(value["result"]) || !isRecord(value["info"])) {
+  if (!isRecord2(value) || !isRecord2(value["result"]) || !isRecord2(value["info"])) {
     return false;
   }
   const result = value["result"];
@@ -2230,16 +2708,16 @@ async function createResultSession(input, options = {}) {
   const finalDirectory = sessionDirectory(ref, options.saptoolsRoot);
   const tempDirectory = `${finalDirectory}.tmp-${process.pid.toString()}`;
   await mkdir3(root, { recursive: true, mode: 448 });
-  await rm2(tempDirectory, { recursive: true, force: true });
+  await rm3(tempDirectory, { recursive: true, force: true });
   await mkdir3(tempDirectory, { mode: 448 });
   try {
-    await writeFile2(join3(tempDirectory, MANIFEST_FILE_NAME), serialized, {
+    await writeFile2(join4(tempDirectory, MANIFEST_FILE_NAME), serialized, {
       encoding: "utf8",
       mode: 384
     });
     await rename(tempDirectory, finalDirectory);
   } catch (error) {
-    await rm2(tempDirectory, { recursive: true, force: true });
+    await rm3(tempDirectory, { recursive: true, force: true });
     throw error;
   }
   return toSession(stored, options.saptoolsRoot);
@@ -2275,7 +2753,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 rm2(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
+      await rm3(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
       removed += 1;
     }
   }
@@ -2285,7 +2763,7 @@ async function clearResultSessions(options = {}) {
   const refs = await listSessionRefs(options.saptoolsRoot);
   await Promise.all(
     refs.map(async (ref) => {
-      await rm2(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
+      await rm3(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
     })
   );
   return refs.length;
@@ -2373,7 +2851,12 @@ async function runShow(ref, options) {
     print(csv(rows, ["PATH", "TYPE", "VALUE"], length));
     return;
   }
-  const window = readCellWindow(selected.value, nonNegative("--offset", options.offset), length);
+  const window = readCellWindow(
+    selected.value,
+    nonNegative("--offset", options.offset),
+    length,
+    selected.typeName
+  );
   print(
     csv(
       [
@@ -2426,9 +2909,9 @@ async function runSearch(ref, text, options) {
   }));
   print(csv(rows, ["ROW", "COLUMN", "OFFSET", "PATH", "PREVIEW"], length));
 }
-function cellExportValue(value) {
+function cellExportValue(value, typeName2) {
   if (Buffer.isBuffer(value)) {
-    return value;
+    return isTextLobType(typeName2) ? value.toString("utf8") : value;
   }
   if (value instanceof Date) {
     return value.toISOString();
@@ -2450,7 +2933,9 @@ async function runExport(ref, options) {
   }
   const session = await readResultSession(ref);
   const selected = selectResultCell(session, options.row, options.column);
-  await writeFile3(options.output, cellExportValue(selected.value), { mode: 384 });
+  await writeFile3(options.output, cellExportValue(selected.value, selected.typeName), {
+    mode: 384
+  });
   print(`wrote=${options.output}`);
 }
 async function runList() {
@@ -2492,6 +2977,419 @@ function registerResultCommands(program) {
   });
 }
 
+// src/metadata-cache.ts
+import { createHash } from "crypto";
+import { mkdir as mkdir4, readFile as readFile2, rename as rename2, rm as rm4, writeFile as writeFile4 } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import { join as join5 } from "path";
+var METADATA_CACHE_TTL_MS = 30 * 6e4;
+function metadataCacheRoot(saptoolsRoot) {
+  return join5(saptoolsRoot ?? join5(homedir4(), ".saptools"), "cf-hana", "metadata");
+}
+function toMetadataCacheScope(info) {
+  return {
+    selector: info.selector,
+    appName: info.appName,
+    host: info.host,
+    schema: info.schema,
+    role: info.role,
+    driver: info.driver
+  };
+}
+function metadataCacheKey(scope) {
+  return createHash("sha256").update(JSON.stringify(scope)).digest("hex");
+}
+function metadataCachePath(scope, saptoolsRoot) {
+  return join5(metadataCacheRoot(saptoolsRoot), `${metadataCacheKey(scope)}.json`);
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCatalogObject(value) {
+  return isRecord3(value) && typeof value["schema"] === "string" && typeof value["name"] === "string" && (value["type"] === "TABLE" || value["type"] === "VIEW");
+}
+function isScope(value) {
+  return isRecord3(value) && typeof value["selector"] === "string" && typeof value["appName"] === "string" && typeof value["host"] === "string" && typeof value["schema"] === "string" && typeof value["role"] === "string" && typeof value["driver"] === "string";
+}
+function scopesEqual(left, right) {
+  return metadataCacheKey(left) === metadataCacheKey(right);
+}
+function isStored(value) {
+  return isRecord3(value) && value["version"] === 1 && typeof value["createdAt"] === "string" && isScope(value["scope"]) && Array.isArray(value["objects"]) && value["objects"].every(isCatalogObject);
+}
+async function readMetadataCache(scope, options = {}) {
+  try {
+    const parsed = JSON.parse(
+      await readFile2(metadataCachePath(scope, options.saptoolsRoot), "utf8")
+    );
+    if (!isStored(parsed) || !scopesEqual(parsed.scope, scope)) {
+      return void 0;
+    }
+    const createdAt = Date.parse(parsed.createdAt);
+    const now = options.now?.() ?? /* @__PURE__ */ new Date();
+    const ageMs = now.getTime() - createdAt;
+    if (!Number.isFinite(createdAt) || ageMs < 0 || ageMs >= METADATA_CACHE_TTL_MS) {
+      return void 0;
+    }
+    return parsed.objects;
+  } catch {
+    return void 0;
+  }
+}
+async function writeMetadataCache(scope, objects, options = {}) {
+  const root = metadataCacheRoot(options.saptoolsRoot);
+  const path = metadataCachePath(scope, options.saptoolsRoot);
+  const tempPath = `${path}.tmp-${process.pid.toString()}`;
+  const stored = {
+    version: 1,
+    createdAt: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+    scope,
+    objects
+  };
+  await mkdir4(root, { recursive: true, mode: 448 });
+  await rm4(tempPath, { force: true });
+  await writeFile4(tempPath, `${JSON.stringify(stored)}
+`, { encoding: "utf8", mode: 384 });
+  await rename2(tempPath, path);
+}
+async function loadCatalogObjectsWithCache(scope, refresh, loader, options = {}) {
+  if (!refresh) {
+    const cached = await readMetadataCache(scope, options);
+    if (cached !== void 0) {
+      return cached;
+    }
+  }
+  const objects = await loader();
+  try {
+    await writeMetadataCache(scope, objects, options);
+  } catch {
+  }
+  return objects;
+}
+
+// src/suggestions.ts
+var INVALID_OBJECT_PATTERNS = [
+  /invalid\s+(?:table|view|object)\s+name/i,
+  /(?:table|view|object)\s+[^\n]*does\s+not\s+exist/i,
+  /could\s+not\s+find\s+(?:table|view|object)/i
+];
+var REF_KEYWORDS = /* @__PURE__ */ new Set(["FROM", "JOIN", "UPDATE", "INTO", "TABLE"]);
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "AS",
+  "ON",
+  "WHERE",
+  "SET",
+  "VALUES",
+  "USING",
+  "WHEN",
+  "INNER",
+  "LEFT",
+  "RIGHT",
+  "FULL",
+  "OUTER",
+  "CROSS",
+  "JOIN"
+]);
+var CTE_FOLLOWERS = /* @__PURE__ */ new Set(["AS"]);
+function isInvalidCatalogObjectError(error) {
+  if (!(error instanceof QueryError)) {
+    return false;
+  }
+  if (error.sqlState === "42S02" || error.sqlState === "42S01") {
+    return true;
+  }
+  return INVALID_OBJECT_PATTERNS.some((pattern) => pattern.test(error.message));
+}
+function skipLineComment3(sql, index) {
+  let cursor = index + 2;
+  while (cursor < sql.length && sql[cursor] !== "\n") {
+    cursor += 1;
+  }
+  return cursor;
+}
+function skipBlockComment3(sql, index) {
+  let cursor = index + 2;
+  while (cursor < sql.length && !(sql[cursor] === "*" && sql[cursor + 1] === "/")) {
+    cursor += 1;
+  }
+  return Math.min(cursor + 2, sql.length);
+}
+function skipStringLiteral(sql, index) {
+  let cursor = index + 1;
+  while (cursor < sql.length) {
+    if (sql[cursor] === "'" && sql[cursor + 1] === "'") {
+      cursor += 2;
+      continue;
+    }
+    if (sql[cursor] === "'") {
+      return cursor + 1;
+    }
+    cursor += 1;
+  }
+  return cursor;
+}
+function readQuotedIdentifier(sql, index) {
+  let cursor = index + 1;
+  let text = "";
+  while (cursor < sql.length) {
+    if (sql[cursor] === '"' && sql[cursor + 1] === '"') {
+      text += '"';
+      cursor += 2;
+      continue;
+    }
+    if (sql[cursor] === '"') {
+      return { text, next: cursor + 1 };
+    }
+    text += sql.charAt(cursor);
+    cursor += 1;
+  }
+  return { text, next: cursor };
+}
+function readBareWord(sql, index) {
+  let cursor = index;
+  let text = "";
+  while (cursor < sql.length && /[A-Za-z0-9_#$]/.test(sql.charAt(cursor))) {
+    text += sql.charAt(cursor);
+    cursor += 1;
+  }
+  return { text, next: cursor };
+}
+function tokenize(sql) {
+  const tokens = [];
+  let index = 0;
+  while (index < sql.length) {
+    const char = sql.charAt(index);
+    if (/\s/.test(char)) {
+      index += 1;
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      index = skipLineComment3(sql, index);
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      index = skipBlockComment3(sql, index);
+      continue;
+    }
+    if (char === "'") {
+      index = skipStringLiteral(sql, index);
+      continue;
+    }
+    if (char === '"') {
+      const quoted = readQuotedIdentifier(sql, index);
+      tokens.push({ kind: "quoted", text: quoted.text });
+      index = quoted.next;
+      continue;
+    }
+    if (/[A-Za-z_#$]/.test(char)) {
+      const word = readBareWord(sql, index);
+      tokens.push({ kind: "word", text: word.text });
+      index = word.next;
+      continue;
+    }
+    if (char === ".") {
+      tokens.push({ kind: "dot", text: char });
+    } else if (char === ",") {
+      tokens.push({ kind: "comma", text: char });
+    } else if (char === "(") {
+      tokens.push({ kind: "open", text: char });
+    } else if (char === ")") {
+      tokens.push({ kind: "close", text: char });
+    } else {
+      tokens.push({ kind: "other", text: char });
+    }
+    index += 1;
+  }
+  return tokens;
+}
+function upper(token) {
+  return token?.text.toUpperCase() ?? "";
+}
+function isIdentifier(token) {
+  return token?.kind === "word" || token?.kind === "quoted";
+}
+function readName(tokens, start, allowFollowingParens = false) {
+  const first = tokens[start];
+  if (!isIdentifier(first)) {
+    return void 0;
+  }
+  let next = start + 1;
+  let schema;
+  let name = first.text;
+  const maybeObject = tokens[next + 1];
+  if (tokens[next]?.kind === "dot" && isIdentifier(maybeObject)) {
+    schema = name;
+    name = maybeObject.text;
+    next += 2;
+  }
+  if (!allowFollowingParens && tokens[next]?.kind === "open") {
+    return void 0;
+  }
+  return { name: schema === void 0 ? { name } : { schema, name }, next };
+}
+function firstNameFromText(text) {
+  const tokens = tokenize(text);
+  for (let index = 0; index < tokens.length; index += 1) {
+    const read = readName(tokens, index, true);
+    if (read !== void 0) {
+      return read.name;
+    }
+  }
+  return void 0;
+}
+function extractMissingObjectNameFromError(error) {
+  if (!(error instanceof QueryError)) {
+    return void 0;
+  }
+  const message = error.message;
+  const invalidName = /invalid\s+(?:table|view|object)\s+name\s*:?\s*(.+)$/i.exec(message);
+  if (invalidName?.[1] !== void 0) {
+    return firstNameFromText(invalidName[1]);
+  }
+  const missingObject = /(?:table|view|object)\s+(.+?)\s+(?:does\s+not\s+exist|not\s+found)/i.exec(message);
+  if (missingObject?.[1] !== void 0) {
+    return firstNameFromText(missingObject[1]);
+  }
+  return void 0;
+}
+function cteNames(tokens) {
+  const names = /* @__PURE__ */ new Set();
+  if (upper(tokens[0]) !== "WITH") {
+    return names;
+  }
+  let depth = 0;
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (depth === 0 && upper(token) === "SELECT") {
+      break;
+    }
+    if (depth === 0 && isIdentifier(token) && CTE_FOLLOWERS.has(upper(tokens[index + 1]))) {
+      names.add(token.text.toUpperCase());
+    }
+    if (token?.kind === "open") {
+      depth += 1;
+    } else if (token?.kind === "close" && depth > 0) {
+      depth -= 1;
+    }
+  }
+  return names;
+}
+function extractMissingObjectName(sql) {
+  const tokens = tokenize(sql.replace(/^;+|;+$/g, ""));
+  const ctes = cteNames(tokens);
+  let candidate;
+  for (let index = 0; index < tokens.length; index += 1) {
+    const word = upper(tokens[index]);
+    if (!REF_KEYWORDS.has(word)) {
+      continue;
+    }
+    if (word === "TABLE" && upper(tokens[index - 1]) !== "TRUNCATE") {
+      continue;
+    }
+    if (word === "INTO" && !(upper(tokens[index - 1]) === "INSERT" || upper(tokens[index - 1]) === "MERGE")) {
+      continue;
+    }
+    const read = readName(tokens, index + 1, word === "INTO");
+    if (read === void 0) {
+      continue;
+    }
+    if (read.name.schema === void 0 && ctes.has(read.name.name.toUpperCase())) {
+      continue;
+    }
+    if (STOP_WORDS.has(read.name.name.toUpperCase())) {
+      continue;
+    }
+    candidate = read.name;
+    let next = read.next;
+    if (isIdentifier(tokens[next]) && !STOP_WORDS.has(upper(tokens[next]))) {
+      next += 1;
+    }
+    while (tokens[next]?.kind === "comma") {
+      const commaRead = readName(tokens, next + 1);
+      if (commaRead === void 0) {
+        break;
+      }
+      if (!(commaRead.name.schema === void 0 && ctes.has(commaRead.name.name.toUpperCase()))) {
+        candidate = commaRead.name;
+      }
+      next = commaRead.next;
+      if (isIdentifier(tokens[next]) && !STOP_WORDS.has(upper(tokens[next]))) {
+        next += 1;
+      }
+    }
+  }
+  return candidate;
+}
+function singular(value) {
+  if (value.endsWith("ES")) {
+    return value.slice(0, -2);
+  }
+  if (value.endsWith("S")) {
+    return value.slice(0, -1);
+  }
+  return value;
+}
+function norm(value) {
+  return value.toUpperCase().replace(/[^A-Z0-9]+/g, "");
+}
+function distance(a, b) {
+  const previous = Array.from({ length: b.length + 1 }, (_value, index) => index);
+  for (let leftIndex = 1; leftIndex <= a.length; leftIndex += 1) {
+    let last = leftIndex - 1;
+    previous[0] = leftIndex;
+    for (let rightIndex = 1; rightIndex <= b.length; rightIndex += 1) {
+      const old = previous[rightIndex] ?? 0;
+      previous[rightIndex] = Math.min(
+        (previous[rightIndex] ?? 0) + 1,
+        (previous[rightIndex - 1] ?? 0) + 1,
+        last + (a.charAt(leftIndex - 1) === b.charAt(rightIndex - 1) ? 0 : 1)
+      );
+      last = old;
+    }
+  }
+  return previous[b.length] ?? 0;
+}
+function score(requested, candidate) {
+  const requestedName = norm(requested.name);
+  const candidateName = norm(candidate.name);
+  if (requested.schema !== void 0 && norm(requested.schema) !== norm(candidate.schema)) {
+    return 0;
+  }
+  if (requestedName === candidateName) {
+    return 100;
+  }
+  if (singular(requestedName) === singular(candidateName)) {
+    return 92;
+  }
+  let value = 0;
+  if (candidateName.startsWith(requestedName) || requestedName.startsWith(candidateName)) {
+    value = Math.max(value, 80 - Math.abs(candidateName.length - requestedName.length));
+  }
+  if (candidateName.endsWith(requestedName) || requestedName.endsWith(candidateName)) {
+    value = Math.max(value, 70 - Math.abs(candidateName.length - requestedName.length));
+  }
+  const editDistance = distance(requestedName, candidateName);
+  const max = Math.max(requestedName.length, candidateName.length, 1);
+  if (editDistance <= Math.max(3, Math.floor(max * 0.35))) {
+    value = Math.max(value, Math.round(75 * (1 - editDistance / max)));
+  }
+  return value;
+}
+function rankCatalogSuggestions(requested, candidates, limit = 5) {
+  return candidates.map((candidate) => ({ candidate, score: score(requested, candidate) })).filter((item) => item.score >= 45).sort(
+    (left, right) => right.score - left.score || left.candidate.schema.localeCompare(right.candidate.schema) || (left.candidate.type === right.candidate.type ? 0 : left.candidate.type === "TABLE" ? -1 : 1) || left.candidate.name.localeCompare(right.candidate.name)
+  ).slice(0, limit).map((item) => item.candidate);
+}
+function formatSuggestions(suggestions) {
+  if (suggestions.length === 0) {
+    return void 0;
+  }
+  return [
+    "Did you mean:",
+    ...suggestions.map((item) => `  ${item.schema}.${item.name} (${item.type})`)
+  ].join("\n");
+}
+
 // src/cli.ts
 function print2(text) {
   process.stdout.write(`${text}
@@ -2618,7 +3516,7 @@ function formatInfo(info) {
   ].join("\n");
 }
 function withConnectionOptions(command) {
-  return command.option("--refresh", "bypass cached credentials and fetch them 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");
+  return command.option("--refresh", "bypass cached credentials and fetch them 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);
 }
 function withFormattedConnectionOptions(command) {
   return withConnectionOptions(command).option(
@@ -2627,6 +3525,36 @@ function withFormattedConnectionOptions(command) {
     "table"
   );
 }
+async function loadSuggestionCatalogObjects(client, refresh) {
+  try {
+    return await loadCatalogObjectsWithCache(
+      toMetadataCacheScope(client.info),
+      refresh,
+      async () => await client.listCatalogObjects(client.info.schema)
+    );
+  } catch {
+    return await client.listCatalogObjects(client.info.schema);
+  }
+}
+async function enrichAndRethrowQueryError(error, client, sql, refresh) {
+  if (!isInvalidCatalogObjectError(error)) {
+    throw error;
+  }
+  const requested = extractMissingObjectNameFromError(error) ?? extractMissingObjectName(sql);
+  if (requested === void 0) {
+    throw error;
+  }
+  try {
+    const objects = await loadSuggestionCatalogObjects(client, refresh);
+    const text = formatSuggestions(rankCatalogSuggestions(requested, objects));
+    if (text !== void 0) {
+      process.stderr.write(`${text}
+`);
+    }
+  } catch {
+  }
+  throw error;
+}
 async function runQuery(selector, sql, command) {
   const opts = command.opts();
   assertQueryOptions(sql, opts);
@@ -2634,12 +3562,24 @@ async function runQuery(selector, sql, command) {
   const client = await connect(await resolveSelectorArgument(selector), toConnectOptions(opts));
   try {
     const params = opts.param ?? [];
-    const backup = await client.backupWriteStatement(sql, params);
+    let backup;
+    try {
+      backup = await client.backupWriteStatement(sql, params);
+    } catch (error) {
+      await enrichAndRethrowQueryError(error, client, sql, opts.refreshMetadata || opts.refresh);
+    }
     if (backup !== void 0) {
       process.stderr.write(`${CLI_NAME}: backup saved to ${backup.directory}
 `);
     }
-    const result = await client.query(sql, params);
+    const result = await client.query(sql, params).catch(async (error) => {
+      return await enrichAndRethrowQueryError(
+        error,
+        client,
+        sql,
+        opts.refreshMetadata || opts.refresh
+      );
+    });
     if (result.statement === "select") {
       const compact = formatCompactCsv(result, cellLimit);
       if (opts.save) {