@saptools/cf-hana 0.3.1 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+<!-- cspell:words VARCHAR -->
+
+## 0.3.4 - 2026-07-02
+
+- Keep explicit selector region lookup map-backed so unknown technical keys fail before isolated authentication unless they are added to the maintained SAP CF region catalog.
+
+## 0.3.3 - 2026-07-02
+
+- Fix Cloud Foundry region resolution for indexed SAP regions such as `eu10-005`, representative `eu20`/`us10` indexed endpoints, and China `platform.sapcloud.cn` endpoints.
+- Keep bare CLI selectors on the core current-session path so healthy `cf env <app>` calls do not require isolated SAP re-authentication.
+- Preserve and validate the current CF API endpoint for auth fallback, reject unsafe endpoint shapes, and keep binding discovery live-only without restoring `cf-sync` cache reads.
+- Update `--refresh`, README, and cf-hana skill text to describe the retained compatibility flag truthfully.
+
+## 0.3.2 - 2026-07-01
+
+- Remove the `cf-hana: saved result expires at...` stderr notice from `query --save` output while keeping result refs available for inspection.
+
 ## 0.3.1 - 2026-07-01
 
 - Add actionable HANA LOB `ORDER BY`/`GROUP BY` hints that recommend removing LOB columns or wrapping them with `TO_VARCHAR(<column>)`.

package/README.md

@@ -2,19 +2,17 @@
 
 > Run SQL directly against SAP HANA Cloud databases bound to a Cloud Foundry app — addressed by a `region/org/space/app` selector.
 
-`@saptools/cf-hana` closes the last gap in the `saptools` chain: `@saptools/cf-sync`
-already discovers Cloud Foundry topology and HANA service bindings, but nothing
-actually executes SQL. This package does. Pass a selector, get a connected,
-pooled client, and run `SELECT` / `INSERT` / `UPDATE` / `DELETE` / DDL.
-
-It is fast because credentials come from `cf-sync`'s on-disk cache (no 5–15s CF
-login on the hot path) and connections are pooled and reused within a process.
+`@saptools/cf-hana` opens live SAP HANA Cloud connections from Cloud Foundry app
+bindings. Pass a selector, get a connected, pooled client, and run `SELECT` /
+`INSERT` / `UPDATE` / `DELETE` / DDL. Bare app names use your active `cf target`
+and current CF session first, so a healthy local CF login does not require SAP
+password re-authentication.
 
 ## Features
 
 - **Selector-based connect** — `region/org/space/app` or a bare app name.
-- **Credentials, handled for you** — cache-first via `@saptools/cf-sync`, with an
-  on-demand live Cloud Foundry fetch as a fallback.
+- **Credentials, handled for you** — HANA bindings are read live from Cloud Foundry.
+  Bare app names use the current CF session first; explicit selectors use isolated live authentication.
 - **Parameterized queries** — values always travel as bound `?` parameters, never
   string-concatenated.
 - **Connection pooling** — pooled, reused connections; opt out with `pool: false`.
@@ -74,8 +72,9 @@ Every entry point takes a selector as its first argument:
 
 - **Explicit** — `region/org/space/app` (e.g.
   `eu10/example-org/space-demo/app-demo`). Works without any cached topology.
-- **Bare app name** — `app-demo`. Resolved against the topology cached by
-  `cf-sync sync`; throws if the name is ambiguous across spaces.
+- **Bare app name** — `app-demo`. Resolved only against the active `cf target`
+  (current org/space/API endpoint) and fetched with `cf env app-demo` using your
+  existing CF session before any isolated re-auth fallback.
 
 ## CLI
 
@@ -89,7 +88,7 @@ cf-hana info    <selector>                  Print the resolved connection metada
 cf-hana result  <command>                   Inspect saved query refs
 ```
 
-Common options: `--refresh`, `--role <runtime|hdi>`, `--binding <name>` /
+Common options: `--refresh` (deprecated compatibility flag; binding discovery is already live), `--role <runtime|hdi>`, `--binding <name>` /
 `--binding-index <n>`, `--timeout <ms>`, `--read-only`, `--allow-destructive`,
 `--limit <n>`, `--no-auto-limit`. The `query` command also accepts
 `--param <value>` (repeatable), `--cell-limit <n>`, `--save`,
@@ -170,10 +169,11 @@ atomically, and expire after exactly 30 minutes. The cache key is derived from
 non-secret connection identity: selector, app name, host, active schema, role,
 and driver. It does not include passwords, certificates, tokens, SQL parameter
 values, result rows, or table data, and malformed cache files are treated as
-misses. Pass `--refresh-metadata` to bypass this cache for a query; `--refresh`
-also bypasses it because it refreshes the resolved connection identity. If
-metadata lookup or cache I/O fails, cf-hana preserves the original query error
-and simply omits suggestions.
+misses. Pass `--refresh-metadata` to bypass this cache for a query. The legacy
+`--refresh` flag is accepted for compatibility but does not bypass the metadata
+cache and is not a credential-cache control because binding discovery is already
+live. If metadata lookup or cache I/O fails, cf-hana preserves the original
+query error and simply omits suggestions.
 
 ## Programmatic API
 
@@ -187,21 +187,31 @@ and simply omits suggestions.
 
 `ConnectOptions` highlights: `role` (`runtime` | `hdi`), `bindingName` /
 `bindingIndex`, `readOnly`, `allowDestructive`, `autoLimit`, `queryTimeoutMs`,
-`connectTimeoutMs`, `refresh`, `pool`.
+`connectTimeoutMs`, deprecated `refresh`, `pool`.
 
 ## Credentials
 
-Credentials are resolved **cache-first**:
-
-1. Read what `cf-sync db-sync` cached in `~/.saptools/cf-db-bindings.json`.
-2. On a cache miss (or when `refresh: true` / `--refresh` is passed), fetch them
-   live from Cloud Foundry. The live fetch needs `SAP_EMAIL` and `SAP_PASSWORD`
-   (or the `email` / `password` options) and never persists anything to disk.
-
-Credential resolution writes nothing under `~/.saptools/` — it only reads what
-`cf-sync` cached. The connection pool is in-process and in-memory only, so it is
-safe to run many `cf-hana` processes in parallel and alongside any `cf-sync`
-command.
+Credential discovery is **live-only** and does not read `@saptools/cf-sync`
+snapshots or `~/.saptools/cf-db-bindings.json`.
+
+- Bare app selectors (`app-demo`) read the active `cf target`, preserve its exact
+  validated API endpoint, and first run `cf env app-demo` with your current CF
+  session. This path does not require `SAP_EMAIL` or `SAP_PASSWORD` while the
+  current session is healthy.
+- If that direct bare-app call fails with an auth/session error, cf-hana falls
+  back to an isolated temporary `CF_HOME`, runs `cf api <current-endpoint>`,
+  authenticates with `SAP_EMAIL` / `SAP_PASSWORD` (or the programmatic `email` /
+  `password` options), targets the current org/space, and reads `cf env`.
+- Explicit `region/org/space/app` selectors always use isolated live
+  authentication. Region keys support current SAP CF technical keys, including
+  indexed regions such as `eu10-005`, `eu20-001`, `us10-002`, and China
+  endpoints such as `cn40` on `platform.sapcloud.cn`.
+
+The legacy `refresh` / `--refresh` option is retained only for compatibility and
+has no credential-cache meaning; binding discovery is already live. Use
+`--refresh-metadata` when you specifically want to bypass the table/view
+suggestion metadata cache. Credential resolution writes no binding credentials
+under `~/.saptools/`.
 
 ## SQL history
 
@@ -264,9 +274,9 @@ parameters.
 ## Requirements
 
 - Node.js >= 20.
-- A HANA binding reachable from your network. Resolving a bare app name, or a
-  live credential fetch, additionally needs the Cloud Foundry CLI and
-  `SAP_EMAIL` / `SAP_PASSWORD`.
+- A HANA binding reachable from your network. Resolving a bare app name needs the Cloud Foundry CLI and an active `cf target`.
+  Isolated fallback or explicit selectors additionally need `SAP_EMAIL` /
+  `SAP_PASSWORD`.
 
 ## Development
 

package/dist/cli.js

@@ -698,7 +698,7 @@ async function listColumns(connection, schema, table) {
 
 // src/config.ts
 var CLI_NAME = "cf-hana";
-var CLI_VERSION = "0.3.1";
+var CLI_VERSION = "0.3.4";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -750,40 +750,94 @@ var REGION_API_MAP = {
   ap20: "https://api.cf.ap20.hana.ondemand.com",
   ap21: "https://api.cf.ap21.hana.ondemand.com",
   ap30: "https://api.cf.ap30.hana.ondemand.com",
+  ap31: "https://api.cf.ap31.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",
+  cn20: "https://api.cf.cn20.platform.sapcloud.cn",
+  cn40: "https://api.cf.cn40.platform.sapcloud.cn",
+  eu01: "https://api.cf.eu01.hana.ondemand.com",
+  eu02: "https://api.cf.eu02.hana.ondemand.com",
   eu10: "https://api.cf.eu10.hana.ondemand.com",
+  "eu10-002": "https://api.cf.eu10-002.hana.ondemand.com",
+  "eu10-003": "https://api.cf.eu10-003.hana.ondemand.com",
+  "eu10-004": "https://api.cf.eu10-004.hana.ondemand.com",
+  "eu10-005": "https://api.cf.eu10-005.hana.ondemand.com",
+  "eu10-006": "https://api.cf.eu10-006.hana.ondemand.com",
   eu11: "https://api.cf.eu11.hana.ondemand.com",
   eu12: "https://api.cf.eu12.hana.ondemand.com",
+  eu13: "https://api.cf.eu13.hana.ondemand.com",
   eu20: "https://api.cf.eu20.hana.ondemand.com",
+  "eu20-001": "https://api.cf.eu20-001.hana.ondemand.com",
+  "eu20-002": "https://api.cf.eu20-002.hana.ondemand.com",
   eu21: "https://api.cf.eu21.hana.ondemand.com",
+  eu22: "https://api.cf.eu22.hana.ondemand.com",
   eu30: "https://api.cf.eu30.hana.ondemand.com",
-  "eu10-002": "https://api.cf.eu10-002.hana.ondemand.com",
+  eu31: "https://api.cf.eu31.hana.ondemand.com",
+  il30: "https://api.cf.il30.hana.ondemand.com",
+  in30: "https://api.cf.in30.hana.ondemand.com",
+  jp01: "https://api.cf.jp01.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",
+  jp31: "https://api.cf.jp31.hana.ondemand.com",
+  sa30: "https://api.cf.sa30.hana.ondemand.com",
+  sa31: "https://api.cf.sa31.hana.ondemand.com",
+  uk20: "https://api.cf.uk20.hana.ondemand.com",
+  us01: "https://api.cf.us01.hana.ondemand.com",
+  us02: "https://api.cf.us02.hana.ondemand.com",
   us10: "https://api.cf.us10.hana.ondemand.com",
+  "us10-001": "https://api.cf.us10-001.hana.ondemand.com",
+  "us10-002": "https://api.cf.us10-002.hana.ondemand.com",
+  "us10-003": "https://api.cf.us10-003.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",
+  "us21-001": "https://api.cf.us21-001.hana.ondemand.com",
+  us22: "https://api.cf.us22.hana.ondemand.com",
   us30: "https://api.cf.us30.hana.ondemand.com",
-  in30: "https://api.cf.in30.hana.ondemand.com"
+  us32: "https://api.cf.us32.hana.ondemand.com"
 };
+function normalizeSapCfApiEndpoint(apiEndpoint) {
+  const trimmed = apiEndpoint.trim();
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`Invalid or untrusted CF API endpoint "${apiEndpoint}".`);
+  }
+  if (/^https:\/\/[^/]*:\d+(?:[/?#]|$)/i.test(trimmed)) {
+    throw new Error(`Invalid or untrusted CF API endpoint "${apiEndpoint}".`);
+  }
+  if (parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "" || parsed.port !== "" || parsed.pathname.replace(/\/+$/, "") !== "" || parsed.search !== "" || parsed.hash !== "") {
+    throw new Error(`Invalid or untrusted CF API endpoint "${apiEndpoint}".`);
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  const match = /^api\.cf\.([a-z]{2}\d{2}(?:-\d{3})?)\.(hana\.ondemand\.com|platform\.sapcloud\.cn)$/.exec(hostname);
+  if (!match) {
+    throw new Error(`Invalid or untrusted CF API endpoint "${apiEndpoint}".`);
+  }
+  return `https://${hostname}`;
+}
 function getApiEndpointForRegion(regionKey) {
-  return REGION_API_MAP[regionKey];
+  return REGION_API_MAP[regionKey.trim().toLowerCase()];
 }
 function getRegionKeyForApi(apiEndpoint) {
-  const norm2 = apiEndpoint.trim().replace(/\/+$/, "").toLowerCase();
+  let normalized;
+  try {
+    normalized = normalizeSapCfApiEndpoint(apiEndpoint);
+  } catch {
+    return void 0;
+  }
   for (const [key, endpoint] of Object.entries(REGION_API_MAP)) {
-    if (endpoint.toLowerCase() === norm2) {
+    if (endpoint.toLowerCase() === normalized) {
       return key;
     }
   }
-  return void 0;
+  return /^https:\/\/api\.cf\.([a-z]{2}\d{2}(?:-\d{3})?)\.hana\.ondemand\.com$/.exec(normalized)?.[1];
 }
 async function withCfSession(work) {
   const cfHome = await mkdtemp(join2(tmpdir(), "saptools-cf-hana-"));
@@ -883,9 +937,15 @@ function parseCfTargetOutput(stdout) {
   if (!api || !org || !space) {
     return void 0;
   }
-  const regionKey = getRegionKeyForApi(api);
+  let normalizedApi;
+  try {
+    normalizedApi = normalizeSapCfApiEndpoint(api);
+  } catch {
+    return void 0;
+  }
+  const regionKey = getRegionKeyForApi(normalizedApi);
   return {
-    apiEndpoint: api,
+    apiEndpoint: normalizedApi,
     orgName: org,
     spaceName: space,
     ...regionKey ? { regionKey } : {}
@@ -911,12 +971,8 @@ function formatCurrentCfAppSelector(target, appName) {
   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.`
-    );
-  }
-  return `${target.regionKey}/${target.orgName}/${target.spaceName}/${name}`;
+  const region = target.regionKey ?? "current";
+  return `${region}/${target.orgName}/${target.spaceName}/${name}`;
 }
 function extractVcapSection(stdout) {
   const start = stdout.indexOf("VCAP_SERVICES:");
@@ -996,6 +1052,9 @@ function classifyCfError(stderr = "", stdout = "") {
 }
 
 // src/credentials.ts
+function errorMessageFromUnknown(error) {
+  return error instanceof Error ? error.message : "Invalid or untrusted CF API endpoint.";
+}
 async function resolveAppBindings(rawSelector, options) {
   const selector = rawSelector.trim();
   if (!selector) {
@@ -1014,7 +1073,7 @@ async function resolveAppBindings(rawSelector, options) {
     const displaySelector = current.regionKey ? formatCurrentCfAppSelector(current, selector) : `current/${current.orgName}/${current.spaceName}/${selector}`;
     target = {
       selector: displaySelector,
-      apiEndpoint: current.regionKey ? getApiEndpointForRegion(current.regionKey) : void 0,
+      apiEndpoint: current.apiEndpoint,
       orgName: current.orgName,
       spaceName: current.spaceName,
       appName: selector
@@ -1032,10 +1091,16 @@ async function resolveAppBindings(rawSelector, options) {
     if (!apiEndpoint) {
       throw new CfHanaError(
         "CONFIG",
-        `Unknown region key "${regionKey}". Use a known region or the current CF target.`
+        `Unknown SAP CF region "${regionKey}". Verify the current SAP region list or use the current CF target.`
       );
     }
-    target = { selector, apiEndpoint, orgName, spaceName, appName };
+    let normalizedApiEndpoint;
+    try {
+      normalizedApiEndpoint = normalizeSapCfApiEndpoint(apiEndpoint);
+    } catch (error) {
+      throw new CfHanaError("CONFIG", errorMessageFromUnknown(error), { cause: error });
+    }
+    target = { selector, apiEndpoint: normalizedApiEndpoint, orgName, spaceName, appName };
   }
   let bindings;
   const source = "live";
@@ -1059,9 +1124,6 @@ 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);
@@ -1085,9 +1147,6 @@ Run "cf login" + "cf target", or provide SAP_EMAIL + SAP_PASSWORD.`,
         `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);
@@ -3529,25 +3588,6 @@ function parseQualifiedName(value) {
   }
   return { schema: value.slice(0, dot), table: value.slice(dot + 1) };
 }
-async function resolveSelectorArgument(selector) {
-  if (selector.includes("/")) {
-    return selector;
-  }
-  const current = await readCurrentCfTarget().catch((error) => {
-    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.",
-      { cause: error }
-    );
-  });
-  if (current === void 0) {
-    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."
-    );
-  }
-  return formatCurrentCfAppSelector(current, selector);
-}
 function toConnectOptions(opts) {
   assertPositiveOption("--limit", opts.limit);
   assertPositiveOption("--timeout", opts.timeout);
@@ -3602,7 +3642,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").option("--refresh-metadata", "bypass the 30-minute table/view metadata suggestion cache", false);
+  return command.option("--refresh", "deprecated compatibility flag; binding discovery is already live", false).option("--role <role>", "HANA user role: runtime or hdi", "runtime").option("--binding <name>", "select a HANA binding by service name").option("--binding-index <n>", "select a HANA binding by index", parseIntOption2).option("--read-only", "block every DML and DDL statement", false).option("--allow-destructive", "permit destructive statements", false).option("--timeout <ms>", "connection and query timeout in milliseconds", parseIntOption2).option("--limit <n>", "row cap auto-applied to bare SELECT statements", parseIntOption2).option("--no-auto-limit", "disable the automatic SELECT row cap").option("--refresh-metadata", "bypass the 30-minute table/view metadata suggestion cache", false);
 }
 function withFormattedConnectionOptions(command) {
   return withConnectionOptions(command).option(
@@ -3690,14 +3730,14 @@ async function runQuery(selector, sql, command) {
   const opts = command.opts();
   assertQueryOptions(sql, opts);
   const cellLimit = resolveCellLimit(opts.cellLimit);
-  const client = await connect(await resolveSelectorArgument(selector), toConnectOptions(opts));
+  const client = await connect(selector, toConnectOptions(opts));
   try {
     const params = opts.param ?? [];
     let backup;
     try {
       backup = await client.backupWriteStatement(sql, params);
     } catch (error) {
-      await enrichAndRethrowQueryError(error, client, sql, opts.refreshMetadata || opts.refresh);
+      await enrichAndRethrowQueryError(error, client, sql, opts.refreshMetadata);
     }
     if (backup !== void 0) {
       process.stderr.write(`${CLI_NAME}: backup saved to ${backup.directory}
@@ -3708,7 +3748,7 @@ async function runQuery(selector, sql, command) {
         error,
         client,
         sql,
-        opts.refreshMetadata || opts.refresh
+        opts.refreshMetadata
       );
     });
     if (result.statement === "select") {
@@ -3720,8 +3760,6 @@ async function runQuery(selector, sql, command) {
           ...opts.resultTtlMinutes === void 0 ? {} : { ttlMinutes: opts.resultTtlMinutes }
         });
         print2(`ref=${session.ref}`);
-        process.stderr.write(`${CLI_NAME}: saved result expires at ${session.expiresAt}
-`);
       }
       print2(compact.text);
       if (result.truncated) {
@@ -3743,7 +3781,7 @@ async function runQuery(selector, sql, command) {
 }
 async function runTables(selector, schema, command) {
   const opts = command.opts();
-  const client = await connect(await resolveSelectorArgument(selector), toConnectOptions(opts));
+  const client = await connect(selector, toConnectOptions(opts));
   try {
     const tables = await client.listTables(schema ?? client.info.schema);
     const rows = tables.map((table) => ({
@@ -3759,7 +3797,7 @@ async function runTables(selector, schema, command) {
 async function runColumns(selector, target, command) {
   const opts = command.opts();
   const { schema, table } = parseQualifiedName(target);
-  const client = await connect(await resolveSelectorArgument(selector), toConnectOptions(opts));
+  const client = await connect(selector, toConnectOptions(opts));
   try {
     const columns = await client.listColumns(schema, table);
     const rows = columns.map((column) => ({
@@ -3777,7 +3815,7 @@ async function runColumns(selector, target, command) {
 async function runCount(selector, target, command) {
   const opts = command.opts();
   const { schema, table } = parseQualifiedName(target);
-  const client = await connect(await resolveSelectorArgument(selector), toConnectOptions(opts));
+  const client = await connect(selector, toConnectOptions(opts));
   try {
     const total = await client.count({ schema, table });
     print2(String(total));
@@ -3787,7 +3825,7 @@ async function runCount(selector, target, command) {
 }
 async function runPing(selector, command) {
   const opts = command.opts();
-  const client = await connect(await resolveSelectorArgument(selector), toConnectOptions(opts));
+  const client = await connect(selector, toConnectOptions(opts));
   try {
     const started = Date.now();
     await client.query("SELECT 1 FROM DUMMY");
@@ -3800,7 +3838,7 @@ async function runPing(selector, command) {
 }
 async function runInfo(selector, command) {
   const opts = command.opts();
-  const client = await connect(await resolveSelectorArgument(selector), toConnectOptions(opts));
+  const client = await connect(selector, toConnectOptions(opts));
   try {
     print2(formatInfo(client.info));
   } finally {