@saptools/cf-hana 0.2.2 → 0.3.1

package/dist/cli.js

@@ -26,12 +26,36 @@ var CredentialsNotFoundError = class extends CfHanaError {
 };
 var QueryError = class extends CfHanaError {
   sqlState;
+  databaseCode;
   constructor(message, options) {
     super("QUERY", message, options);
     this.name = "QueryError";
     this.sqlState = options?.sqlState;
+    this.databaseCode = options?.databaseCode;
   }
 };
+function isDatabaseErrorShape(error) {
+  return typeof error === "object" && error !== null && "code" in error;
+}
+function safeDatabaseCode(value) {
+  if (typeof value === "number" && Number.isSafeInteger(value)) {
+    return value;
+  }
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    return void 0;
+  }
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : void 0;
+}
+function databaseCode(error) {
+  if (error instanceof QueryError) {
+    return error.databaseCode ?? databaseCode(error.cause);
+  }
+  if (isDatabaseErrorShape(error)) {
+    return safeDatabaseCode(error.code);
+  }
+  return void 0;
+}
 var ReadOnlyViolationError = class extends CfHanaError {
   constructor(message, options) {
     super("READ_ONLY_VIOLATION", message, options);
@@ -51,6 +75,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;
@@ -91,12 +124,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);
@@ -105,7 +138,7 @@ function previewCell(value, limit) {
 }
 
 // src/format.ts
-function cellText(value, nullText) {
+function cellText(value, nullText, column) {
   if (value === null) {
     return nullText;
   }
@@ -113,14 +146,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;
   }
@@ -128,7 +161,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;
 }
@@ -144,7 +177,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(
@@ -162,7 +195,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;
   });
@@ -173,7 +207,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");
@@ -184,7 +218,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;
       }
@@ -634,6 +668,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",
@@ -652,7 +698,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.1";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -661,7 +707,7 @@ var DEFAULT_POOL_IDLE_MS = 6e4;
 var DEFAULT_AUTO_LIMIT = 100;
 var DEFAULT_CELL_LIMIT = 128;
 var MAX_CELL_LIMIT = 1e4;
-var DEFAULT_RESULT_TTL_MINUTES = 60;
+var DEFAULT_RESULT_TTL_MINUTES = 10080;
 var DEFAULT_RESULT_SEARCH_LIMIT = 20;
 var MAX_RESULT_STORE_BYTES = 256 * 1024 * 1024;
 function envName(suffix) {
@@ -731,9 +777,9 @@ function getApiEndpointForRegion(regionKey) {
   return REGION_API_MAP[regionKey];
 }
 function getRegionKeyForApi(apiEndpoint) {
-  const norm = apiEndpoint.trim().replace(/\/+$/, "").toLowerCase();
+  const norm2 = apiEndpoint.trim().replace(/\/+$/, "").toLowerCase();
   for (const [key, endpoint] of Object.entries(REGION_API_MAP)) {
-    if (endpoint.toLowerCase() === norm) {
+    if (endpoint.toLowerCase() === norm2) {
       return key;
     }
   }
@@ -1114,12 +1160,88 @@ function toConnectionTarget(binding, role) {
 
 // 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" },
+    { SCHEMA_NAME: "APP_SCHEMA", OBJECT_NAME: "CORE_AUTH_SCOPE", OBJECT_TYPE: "TABLE" }
+  ];
+}
+function tableColumns() {
+  return [
+    { COLUMN_NAME: "ID", DATA_TYPE_NAME: "INTEGER", LENGTH: null, SCALE: null, IS_NULLABLE: "FALSE", POSITION: 1 },
+    { COLUMN_NAME: "IS_ACTIVE", DATA_TYPE_NAME: "BOOLEAN", LENGTH: null, SCALE: null, IS_NULLABLE: "TRUE", POSITION: 2 },
+    { COLUMN_NAME: "SCOPE_NAME", DATA_TYPE_NAME: "NVARCHAR", LENGTH: 255, SCALE: null, IS_NULLABLE: "TRUE", POSITION: 3 }
+  ];
+}
 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("SYS.TABLE_COLUMNS")) {
+    return {
+      rows: tableColumns(),
+      columns: [
+        { name: "COLUMN_NAME", typeName: "NVARCHAR" },
+        { name: "DATA_TYPE_NAME", typeName: "NVARCHAR" },
+        { name: "LENGTH", typeName: "INTEGER" },
+        { name: "SCALE", typeName: "INTEGER" },
+        { name: "IS_NULLABLE", typeName: "NVARCHAR" },
+        { name: "POSITION", typeName: "INTEGER" }
+      ],
+      affectedRows: 0
+    };
+  }
+  if (upperSql.includes("MISSING_TABLE") || upperSql.includes("MISSING_TABLES")) {
+    throw new QueryError("invalid table name: MISSING_TABLE", { sqlState: "42S02" });
+  }
+  if (upperSql.includes("ISACTIVE")) {
+    throw new QueryError("invalid column name: ISACTIVE: line 1 col 8 (at pos 7)", { databaseCode: 260 });
+  }
+  if (upperSql.includes("LOB_ORDER_ERROR")) {
+    throw new QueryError("inconsistent datatype: LOB type is not allowed in ORDER BY clause", { databaseCode: 266 });
+  }
+  if (upperSql.includes("LOB_GROUP_ERROR")) {
+    throw new QueryError("inconsistent datatype: LOB type is not allowed in GROUP BY clause", { databaseCode: 274 });
+  }
+  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 }],
@@ -1227,7 +1349,12 @@ function extractSqlState(error) {
 }
 function toQueryError(error) {
   const sqlState = extractSqlState(error);
-  return sqlState === void 0 ? new QueryError(error.message, { cause: error }) : new QueryError(error.message, { cause: error, sqlState });
+  const code = databaseCode(error);
+  return new QueryError(error.message, {
+    cause: error,
+    ...sqlState === void 0 ? {} : { sqlState },
+    ...code === void 0 ? {} : { databaseCode: code }
+  });
 }
 function toColumns(metadata) {
   if (metadata === void 0) {
@@ -2119,6 +2246,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(
@@ -2244,12 +2375,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,
@@ -2421,18 +2555,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);
@@ -2454,6 +2589,7 @@ function searchResultSession(session, searchTerm, options) {
           term,
           item.rowNumber,
           column.name,
+          column.typeName,
           remaining,
           previewLength
         )
@@ -2775,7 +2911,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(
       [
@@ -2828,9 +2969,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();
@@ -2852,7 +2993,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() {
@@ -2894,6 +3037,445 @@ 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 extractInvalidColumnNameFromError(error) {
+  if (!(error instanceof QueryError)) {
+    return void 0;
+  }
+  const match = /invalid column name:\s*([^:]+)/i.exec(error.message);
+  const name = match?.[1]?.trim();
+  return name === void 0 || name.length === 0 ? void 0 : name;
+}
+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");
+}
+function rankNameSuggestions(requested, candidates, limit = 5) {
+  const requestedName = { name: requested };
+  return candidates.map((candidate) => ({
+    candidate,
+    score: score(requestedName, { schema: "", name: candidate.name, type: "TABLE" })
+  })).filter((item) => item.score >= 45).sort(
+    (left, right) => right.score - left.score || left.candidate.name.localeCompare(right.candidate.name)
+  ).slice(0, limit).map((item) => item.candidate);
+}
+function formatColumnSuggestions(suggestions) {
+  if (suggestions.length === 0) {
+    return void 0;
+  }
+  return [
+    "Did you mean column:",
+    ...suggestions.map((item) => `  ${item.name}`)
+  ].join("\n");
+}
+
 // src/cli.ts
 function print2(text) {
   process.stdout.write(`${text}
@@ -3020,7 +3602,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(
@@ -3029,6 +3611,81 @@ 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);
+  }
+}
+function isLobSortOrGroupError(error) {
+  const code = databaseCode(error);
+  if (code !== 266 && code !== 274) {
+    return false;
+  }
+  return error instanceof QueryError && /LOB type is not allowed in (?:ORDER BY|GROUP BY) clause/i.test(error.message);
+}
+function printLobSortOrGroupHint() {
+  const lines = [
+    `${CLI_NAME}: HANA cannot ORDER BY or GROUP BY NCLOB/CLOB/BLOB columns directly.`,
+    `${CLI_NAME}: Remove the LOB column from ORDER BY/GROUP BY or wrap it as TO_VARCHAR(<column>).`
+  ];
+  process.stderr.write(`${lines.join("\n")}
+`);
+}
+async function printColumnSuggestions(error, client, sql) {
+  if (databaseCode(error) !== 260) {
+    return;
+  }
+  const columnName = extractInvalidColumnNameFromError(error);
+  const tableName = extractMissingObjectName(sql);
+  if (columnName === void 0 || tableName === void 0) {
+    return;
+  }
+  try {
+    const columns = await client.listColumns(
+      tableName.schema ?? client.info.schema,
+      tableName.name
+    );
+    const text = formatColumnSuggestions(rankNameSuggestions(columnName, columns));
+    if (text !== void 0) {
+      process.stderr.write(`${text}
+`);
+    }
+  } catch {
+  }
+}
+async function printCatalogObjectSuggestions(error, client, sql, refresh) {
+  if (!isInvalidCatalogObjectError(error)) {
+    return;
+  }
+  const requested = extractMissingObjectNameFromError(error) ?? extractMissingObjectName(sql);
+  if (requested === void 0) {
+    return;
+  }
+  try {
+    const objects = await loadSuggestionCatalogObjects(client, refresh);
+    const text = formatSuggestions(rankCatalogSuggestions(requested, objects));
+    if (text !== void 0) {
+      process.stderr.write(`${text}
+`);
+    }
+  } catch {
+  }
+}
+async function enrichAndRethrowQueryError(error, client, sql, refresh) {
+  if (isLobSortOrGroupError(error)) {
+    printLobSortOrGroupHint();
+    throw error;
+  }
+  await printColumnSuggestions(error, client, sql);
+  await printCatalogObjectSuggestions(error, client, sql, refresh);
+  throw error;
+}
 async function runQuery(selector, sql, command) {
   const opts = command.opts();
   assertQueryOptions(sql, opts);
@@ -3036,12 +3693,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) {