@saptools/cf-hana 0.2.1 → 0.3.0

package/dist/index.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 // src/backup.ts
-import { createHash, randomUUID } from "crypto";
 import { mkdir, writeFile } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
@@ -49,8 +48,17 @@ 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/format.ts
-function cellText(value, nullText) {
+function cellText(value, nullText, column) {
   if (value === null) {
     return nullText;
   }
@@ -58,14 +66,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;
   }
@@ -73,7 +81,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;
 }
@@ -89,7 +97,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(
@@ -107,7 +115,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;
   });
@@ -118,7 +127,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");
@@ -302,6 +311,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)));
 }
@@ -339,6 +370,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);
@@ -358,8 +407,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);
@@ -367,33 +426,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
   };
 }
@@ -497,6 +572,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",
@@ -514,7 +601,7 @@ async function listColumns(connection, schema, table) {
 }
 
 // src/config.ts
-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;
@@ -542,44 +629,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 norm = apiEndpoint.trim().replace(/\/+$/, "").toLowerCase();
+  for (const [key, endpoint] of Object.entries(REGION_API_MAP)) {
+    if (endpoint.toLowerCase() === norm) {
+      return key;
     }
   }
-  const credentials = readSapCredentials({
-    email: options.email,
-    password: options.password
+  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 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) {
@@ -629,18 +1053,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 }],
@@ -956,16 +1425,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");
@@ -987,10 +1456,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);
@@ -1006,7 +1475,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 });
     })
   );
 }
@@ -1577,7 +2046,8 @@ var HanaClient = class _HanaClient {
       return await writeSqlBackup({
         operation: plan.operation,
         statementSql: plan.statementSql,
-        result
+        result,
+        selector: this.info.selector
       });
     });
   }
@@ -1639,6 +2109,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(