@saptools/cf-hana 0.1.0

package/dist/cli.js

@@ -0,0 +1,1425 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/errors.ts
+var CfHanaError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "CfHanaError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var CredentialsNotFoundError = class extends CfHanaError {
+  constructor(message, options) {
+    super("CREDENTIALS_NOT_FOUND", message, options);
+    this.name = "CredentialsNotFoundError";
+  }
+};
+var QueryError = class extends CfHanaError {
+  sqlState;
+  constructor(message, options) {
+    super("QUERY", message, options);
+    this.name = "QueryError";
+    this.sqlState = options?.sqlState;
+  }
+};
+var ReadOnlyViolationError = class extends CfHanaError {
+  constructor(message, options) {
+    super("READ_ONLY_VIOLATION", message, options);
+    this.name = "ReadOnlyViolationError";
+  }
+};
+var DestructiveStatementError = class extends CfHanaError {
+  constructor(message, options) {
+    super("DESTRUCTIVE_BLOCKED", message, options);
+    this.name = "DestructiveStatementError";
+  }
+};
+function errorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+// src/statements.ts
+var LEADING_NOISE = /^(?:\s|--[^\n]*\n?|\/\*[\s\S]*?\*\/)+/;
+var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT", "WITH"]);
+var DML_KEYWORDS = /* @__PURE__ */ new Set(["INSERT", "UPDATE", "DELETE", "MERGE", "UPSERT", "REPLACE"]);
+var DDL_KEYWORDS = /* @__PURE__ */ new Set(["CREATE", "DROP", "ALTER", "TRUNCATE", "RENAME", "COMMENT"]);
+function firstKeyword(sql) {
+  const stripped = sql.replace(LEADING_NOISE, "");
+  const match = /^[A-Za-z]+/.exec(stripped);
+  return (match?.[0] ?? "").toUpperCase();
+}
+function classifyStatement(sql) {
+  const keyword = firstKeyword(sql);
+  if (SELECT_KEYWORDS.has(keyword)) {
+    return "select";
+  }
+  if (DML_KEYWORDS.has(keyword)) {
+    return "dml";
+  }
+  if (DDL_KEYWORDS.has(keyword)) {
+    return "ddl";
+  }
+  return "unknown";
+}
+function quoteIdentifier(identifier) {
+  if (identifier.length === 0) {
+    throw new QueryError("A SQL identifier must not be empty");
+  }
+  if (identifier.includes("\0")) {
+    throw new QueryError("A SQL identifier must not contain a NUL character");
+  }
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+function qualifiedName(schema, table) {
+  return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+}
+function countPlaceholders(sql) {
+  let count = 0;
+  let index = 0;
+  const length = sql.length;
+  while (index < length) {
+    const char = sql[index];
+    if (char === "'" || char === '"') {
+      const quote = char;
+      index += 1;
+      while (index < length) {
+        if (sql[index] === quote) {
+          if (sql[index + 1] === quote) {
+            index += 2;
+            continue;
+          }
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      index += 2;
+      while (index < length && sql[index] !== "\n") {
+        index += 1;
+      }
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      index += 2;
+      while (index < length && !(sql[index] === "*" && sql[index + 1] === "/")) {
+        index += 1;
+      }
+      index += 2;
+      continue;
+    }
+    if (char === "?") {
+      count += 1;
+    }
+    index += 1;
+  }
+  return count;
+}
+function assertParamArity(sql, params) {
+  const expected = countPlaceholders(sql);
+  if (expected !== params.length) {
+    throw new QueryError(
+      `SQL expects ${String(expected)} bound parameter(s) but received ${String(params.length)} value(s)`
+    );
+  }
+}
+
+// src/builder.ts
+function buildWhere(where) {
+  if (where === void 0) {
+    return { clause: "", params: [] };
+  }
+  const entries = Object.entries(where);
+  if (entries.length === 0) {
+    return { clause: "", params: [] };
+  }
+  const conditions = entries.map(([column]) => `${quoteIdentifier(column)} = ?`);
+  return {
+    clause: ` WHERE ${conditions.join(" AND ")}`,
+    params: entries.map(([, value]) => value)
+  };
+}
+function buildSelect(spec) {
+  const columns = spec.columns === void 0 || spec.columns.length === 0 ? "*" : spec.columns.map((column) => quoteIdentifier(column)).join(", ");
+  const where = buildWhere(spec.where);
+  const clauses = [
+    `SELECT ${columns} FROM ${qualifiedName(spec.schema, spec.table)}${where.clause}`
+  ];
+  if (spec.orderBy !== void 0 && spec.orderBy.length > 0) {
+    clauses.push(`ORDER BY ${spec.orderBy.map((column) => quoteIdentifier(column)).join(", ")}`);
+  }
+  if (spec.limit !== void 0) {
+    clauses.push(`LIMIT ${String(spec.limit)}`);
+  }
+  if (spec.offset !== void 0) {
+    clauses.push(`OFFSET ${String(spec.offset)}`);
+  }
+  return { sql: clauses.join(" "), params: where.params };
+}
+function buildCount(spec) {
+  const where = buildWhere(spec.where);
+  return {
+    sql: `SELECT COUNT(*) AS "COUNT" FROM ${qualifiedName(spec.schema, spec.table)}${where.clause}`,
+    params: where.params
+  };
+}
+function buildInsert(schema, table, values) {
+  const entries = Object.entries(values);
+  if (entries.length === 0) {
+    throw new QueryError("INSERT requires at least one column value");
+  }
+  const columns = entries.map(([column]) => quoteIdentifier(column)).join(", ");
+  const placeholders = entries.map(() => "?").join(", ");
+  return {
+    sql: `INSERT INTO ${qualifiedName(schema, table)} (${columns}) VALUES (${placeholders})`,
+    params: entries.map(([, value]) => value)
+  };
+}
+function buildUpdate(schema, table, values, where) {
+  const valueEntries = Object.entries(values);
+  if (valueEntries.length === 0) {
+    throw new QueryError("UPDATE requires at least one column value");
+  }
+  const whereClause = buildWhere(where);
+  if (whereClause.clause === "") {
+    throw new QueryError("UPDATE requires a non-empty WHERE filter to avoid a full-table write");
+  }
+  const assignments = valueEntries.map(([column]) => `${quoteIdentifier(column)} = ?`).join(", ");
+  return {
+    sql: `UPDATE ${qualifiedName(schema, table)} SET ${assignments}${whereClause.clause}`,
+    params: [...valueEntries.map(([, value]) => value), ...whereClause.params]
+  };
+}
+function buildDelete(schema, table, where) {
+  const whereClause = buildWhere(where);
+  if (whereClause.clause === "") {
+    throw new QueryError("DELETE requires a non-empty WHERE filter to avoid a full-table delete");
+  }
+  return {
+    sql: `DELETE FROM ${qualifiedName(schema, table)}${whereClause.clause}`,
+    params: whereClause.params
+  };
+}
+
+// src/catalog.ts
+async function listSchemas(connection) {
+  const result = await connection.query(
+    "SELECT SCHEMA_NAME FROM SYS.SCHEMAS ORDER BY SCHEMA_NAME"
+  );
+  return result.rows.map((row) => row.SCHEMA_NAME);
+}
+async function listTables(connection, schema) {
+  const result = await connection.query(
+    "SELECT SCHEMA_NAME, TABLE_NAME, TABLE_TYPE FROM SYS.TABLES WHERE SCHEMA_NAME = ? ORDER BY TABLE_NAME",
+    [schema]
+  );
+  return result.rows.map((row) => ({
+    schema: row.SCHEMA_NAME,
+    name: row.TABLE_NAME,
+    type: row.TABLE_TYPE,
+    rowCount: void 0
+  }));
+}
+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",
+    [schema, table]
+  );
+  return result.rows.map((row) => ({
+    name: row.COLUMN_NAME,
+    dataType: row.DATA_TYPE_NAME,
+    length: row.LENGTH ?? void 0,
+    scale: row.SCALE ?? void 0,
+    nullable: row.IS_NULLABLE === "TRUE",
+    position: row.POSITION
+  }));
+}
+
+// src/config.ts
+var CLI_NAME = "cf-hana";
+var CLI_VERSION = "0.1.0";
+var ENV_PREFIX = "CF_HANA";
+var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
+var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
+var DEFAULT_POOL_MAX = 4;
+var DEFAULT_POOL_IDLE_MS = 6e4;
+var DEFAULT_AUTO_LIMIT = 1e3;
+function envName(suffix) {
+  return `${ENV_PREFIX}_${suffix}`;
+}
+function readEnv(name) {
+  const value = process.env[name];
+  if (value === void 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? void 0 : trimmed;
+}
+function readSapCredentials(overrides) {
+  const email = overrides?.email ?? readEnv("SAP_EMAIL");
+  const password = overrides?.password ?? readEnv("SAP_PASSWORD");
+  if (email === void 0 || password === void 0) {
+    return void 0;
+  }
+  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"
+      };
+    }
+  }
+  const credentials = readSapCredentials({
+    email: options.email,
+    password: options.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.`
+    );
+  }
+  const fetched = await fetchAppDbBindings({
+    selector,
+    email: credentials.email,
+    password: credentials.password
+  });
+  if (fetched.bindings.length === 0) {
+    throw new CredentialsNotFoundError(
+      `App "${fetched.selector}" has no HANA service binding.`
+    );
+  }
+  return {
+    selector: fetched.selector,
+    appName: fetched.appName,
+    bindings: fetched.bindings,
+    source: "fresh"
+  };
+}
+function selectBinding(bindings, selector) {
+  if (selector.bindingName !== void 0) {
+    const match = bindings.find((binding) => binding.name === selector.bindingName);
+    if (match === void 0) {
+      throw new CfHanaError(
+        "AMBIGUOUS_BINDING",
+        `No HANA binding named "${selector.bindingName}"`
+      );
+    }
+    return match;
+  }
+  if (selector.bindingIndex !== void 0) {
+    const match = bindings[selector.bindingIndex];
+    if (match === void 0) {
+      throw new CfHanaError(
+        "AMBIGUOUS_BINDING",
+        `No HANA binding at index ${String(selector.bindingIndex)}`
+      );
+    }
+    return match;
+  }
+  const first = bindings[0];
+  if (first === void 0) {
+    throw new CredentialsNotFoundError("No HANA bindings are available for this app");
+  }
+  if (bindings.length > 1) {
+    const labels = bindings.map((binding, index) => binding.name ?? `#${String(index)}`).join(", ");
+    throw new CfHanaError(
+      "AMBIGUOUS_BINDING",
+      `App has multiple HANA bindings (${labels}); choose one with bindingName or bindingIndex`
+    );
+  }
+  return first;
+}
+function toConnectionTarget(binding, role) {
+  const credentials = binding.credentials;
+  const port = Number.parseInt(credentials.port, 10);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new CfHanaError("CONFIG", `Invalid HANA port in binding: "${credentials.port}"`);
+  }
+  return {
+    host: credentials.host,
+    port,
+    user: role === "hdi" ? credentials.hdiUser : credentials.user,
+    password: role === "hdi" ? credentials.hdiPassword : credentials.password,
+    schema: credentials.schema,
+    certificate: credentials.certificate,
+    databaseId: credentials.databaseId
+  };
+}
+
+// src/driver/fake.ts
+function fakeExec(sql) {
+  if (sql.toUpperCase().includes("DUMMY")) {
+    return {
+      rows: [{ "1": 1 }],
+      columns: [{ name: "1", typeName: "INTEGER" }],
+      affectedRows: 0
+    };
+  }
+  const kind = classifyStatement(sql);
+  if (kind === "select") {
+    return {
+      rows: [
+        { ID: 1, NAME: "sample-row" },
+        { ID: 2, NAME: "second-row" }
+      ],
+      columns: [
+        { name: "ID", typeName: "INTEGER" },
+        { name: "NAME", typeName: "NVARCHAR" }
+      ],
+      affectedRows: 0
+    };
+  }
+  if (kind === "dml") {
+    return { rows: [], columns: [], affectedRows: 1 };
+  }
+  return { rows: [], columns: [], affectedRows: 0 };
+}
+var FakeConnection = class {
+  closed = false;
+  exec(sql, _params) {
+    return Promise.resolve(fakeExec(sql));
+  }
+  setAutoCommit(_enabled) {
+    return Promise.resolve();
+  }
+  commit() {
+    return Promise.resolve();
+  }
+  rollback() {
+    return Promise.resolve();
+  }
+  close() {
+    this.closed = true;
+    return Promise.resolve();
+  }
+  isClosed() {
+    return this.closed;
+  }
+};
+function createFakeDriver() {
+  return {
+    name: "fake",
+    connect: (_params) => Promise.resolve(new FakeConnection())
+  };
+}
+
+// src/driver/hdb.ts
+import { createClient } from "hdb";
+var TYPE_NAMES = {
+  0: "NULL",
+  1: "TINYINT",
+  2: "SMALLINT",
+  3: "INTEGER",
+  4: "BIGINT",
+  5: "DECIMAL",
+  6: "REAL",
+  7: "DOUBLE",
+  8: "CHAR",
+  9: "VARCHAR",
+  10: "NCHAR",
+  11: "NVARCHAR",
+  12: "BINARY",
+  13: "VARBINARY",
+  14: "DATE",
+  15: "TIME",
+  16: "TIMESTAMP",
+  25: "CLOB",
+  26: "NCLOB",
+  27: "BLOB",
+  28: "BOOLEAN",
+  29: "STRING",
+  30: "NSTRING",
+  47: "DECIMAL",
+  51: "TEXT",
+  52: "SHORTTEXT",
+  62: "DECIMAL"
+};
+function typeName(code) {
+  return TYPE_NAMES[code] ?? `TYPE_${String(code)}`;
+}
+function extractSqlState(error) {
+  const value = error.sqlState;
+  return typeof value === "string" ? value : void 0;
+}
+function toQueryError(error) {
+  const sqlState = extractSqlState(error);
+  return sqlState === void 0 ? new QueryError(error.message, { cause: error }) : new QueryError(error.message, { cause: error, sqlState });
+}
+function toColumns(metadata) {
+  if (metadata === void 0) {
+    return [];
+  }
+  return metadata.map((column) => ({
+    name: column.columnDisplayName ?? column.columnName ?? "",
+    typeName: typeName(column.dataType)
+  }));
+}
+function toExecResult(statement, raw) {
+  if (typeof raw === "number") {
+    return { rows: [], columns: [], affectedRows: raw };
+  }
+  if (Array.isArray(raw)) {
+    return {
+      rows: raw,
+      columns: toColumns(statement.resultSetMetadata),
+      affectedRows: 0
+    };
+  }
+  return { rows: [], columns: [], affectedRows: 0 };
+}
+var HdbConnection = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  closed = false;
+  async exec(sql, params) {
+    const statement = await this.prepareStatement(sql);
+    try {
+      const raw = await this.executeStatement(statement, params);
+      return toExecResult(statement, raw);
+    } finally {
+      statement.drop();
+    }
+  }
+  setAutoCommit(enabled) {
+    this.client.setAutoCommit(enabled);
+    return Promise.resolve();
+  }
+  async commit() {
+    await new Promise((resolve, reject) => {
+      this.client.commit((error) => {
+        if (error) {
+          reject(toQueryError(error));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+  async rollback() {
+    await new Promise((resolve, reject) => {
+      this.client.rollback((error) => {
+        if (error) {
+          reject(toQueryError(error));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    await new Promise((resolve) => {
+      this.client.disconnect(() => {
+        resolve();
+      });
+    });
+    this.client.close();
+  }
+  isClosed() {
+    return this.closed || this.client.readyState === "closed" || this.client.readyState === "disconnected";
+  }
+  async prepareStatement(sql) {
+    return await new Promise((resolve, reject) => {
+      this.client.prepare(sql, (error, statement) => {
+        if (error) {
+          reject(toQueryError(error));
+        } else {
+          resolve(statement);
+        }
+      });
+    });
+  }
+  async executeStatement(statement, params) {
+    return await new Promise((resolve, reject) => {
+      statement.exec([...params], (error, result) => {
+        if (error) {
+          reject(toQueryError(error));
+        } else {
+          resolve(result);
+        }
+      });
+    });
+  }
+};
+function openClient(client, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      client.close();
+      reject(
+        new CfHanaError(
+          "TIMEOUT",
+          `HANA connection timed out after ${String(timeoutMs)}ms`
+        )
+      );
+    }, timeoutMs);
+    timer.unref();
+    client.connect((error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      if (error) {
+        reject(
+          new CfHanaError("CONNECTION", `Failed to connect to HANA: ${error.message}`, {
+            cause: error
+          })
+        );
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+function setCurrentSchema(client, schema) {
+  return new Promise((resolve, reject) => {
+    client.exec(`SET SCHEMA ${quoteIdentifier(schema)}`, (error) => {
+      if (error) {
+        reject(toQueryError(error));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+async function connectHdb(params) {
+  const client = createClient({
+    host: params.host,
+    port: params.port,
+    user: params.user,
+    password: params.password,
+    ca: params.certificate,
+    useTLS: true
+  });
+  await openClient(client, params.connectTimeoutMs);
+  await setCurrentSchema(client, params.schema);
+  return new HdbConnection(client);
+}
+function createHdbDriver() {
+  return {
+    name: "hdb",
+    connect: connectHdb
+  };
+}
+
+// src/driver/index.ts
+function createDriver(name) {
+  const resolved = name ?? readEnv(envName("DRIVER")) ?? "hdb";
+  switch (resolved) {
+    case "hdb":
+      return createHdbDriver();
+    case "fake":
+      return createFakeDriver();
+    default:
+      throw new CfHanaError("CONFIG", `Unknown HANA driver: ${resolved}`);
+  }
+}
+
+// src/safety.ts
+var DESTRUCTIVE_DDL_KEYWORDS = /* @__PURE__ */ new Set(["DROP", "TRUNCATE", "ALTER"]);
+var UNSCOPED_WRITE_KEYWORDS = /* @__PURE__ */ new Set(["UPDATE", "DELETE"]);
+function stripStringLiterals(sql) {
+  return sql.replace(/'(?:[^']|'')*'/g, "''");
+}
+function hasWhereClause(sql) {
+  return /\bwhere\b/i.test(stripStringLiterals(sql));
+}
+function inspectStatement(sql) {
+  const kind = classifyStatement(sql);
+  const keyword = firstKeyword(sql);
+  if (kind === "ddl") {
+    return { kind, destructive: DESTRUCTIVE_DDL_KEYWORDS.has(keyword) };
+  }
+  if (kind === "dml") {
+    return {
+      kind,
+      destructive: UNSCOPED_WRITE_KEYWORDS.has(keyword) && !hasWhereClause(sql)
+    };
+  }
+  return { kind, destructive: false };
+}
+function evaluateGuard(sql, config) {
+  const inspection = inspectStatement(sql);
+  if (config.readOnly && (inspection.kind === "dml" || inspection.kind === "ddl")) {
+    return {
+      allowed: false,
+      destructive: inspection.destructive,
+      violation: "read-only",
+      reason: `read-only mode blocks ${inspection.kind.toUpperCase()} statements`
+    };
+  }
+  if (inspection.destructive && !config.allowDestructive) {
+    return {
+      allowed: false,
+      destructive: true,
+      violation: "destructive",
+      reason: "destructive statement blocked (DROP/TRUNCATE/ALTER or unscoped UPDATE/DELETE); allow it explicitly to proceed"
+    };
+  }
+  return {
+    allowed: true,
+    destructive: inspection.destructive,
+    violation: void 0,
+    reason: void 0
+  };
+}
+function applyAutoLimit(sql, limit) {
+  if (limit === false || classifyStatement(sql) !== "select") {
+    return { sql, applied: false };
+  }
+  const stripped = stripStringLiterals(sql);
+  if (/\blimit\b/i.test(stripped) || /\btop\s+\d/i.test(stripped)) {
+    return { sql, applied: false };
+  }
+  const trimmed = sql.replace(/[\s;]+$/, "");
+  return { sql: `${trimmed} LIMIT ${String(limit)}`, applied: true };
+}
+
+// src/connection.ts
+async function withTimeout(work, timeoutMs, onTimeout) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      onTimeout();
+      reject(
+        new CfHanaError("TIMEOUT", `Statement timed out after ${String(timeoutMs)}ms`)
+      );
+    }, timeoutMs);
+    timer.unref();
+  });
+  try {
+    return await Promise.race([work, timeout]);
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  }
+}
+var Connection = class _Connection {
+  constructor(driverConnection, config) {
+    this.driverConnection = driverConnection;
+    this.config = config;
+  }
+  driverConnection;
+  config;
+  static async open(driver, config) {
+    const driverConnection = await driver.connect({
+      host: config.host,
+      port: config.port,
+      user: config.user,
+      password: config.password,
+      schema: config.schema,
+      certificate: config.certificate,
+      connectTimeoutMs: config.connectTimeoutMs
+    });
+    return new _Connection(driverConnection, config);
+  }
+  async query(sql, params, options) {
+    const result = await this.run(sql, params ?? [], options ?? {});
+    return result;
+  }
+  async execute(sql, params, options) {
+    return await this.run(sql, params ?? [], options ?? {});
+  }
+  async setAutoCommit(enabled) {
+    await this.driverConnection.setAutoCommit(enabled);
+  }
+  async commit() {
+    await this.driverConnection.commit();
+  }
+  async rollback() {
+    await this.driverConnection.rollback();
+  }
+  async close() {
+    await this.driverConnection.close();
+  }
+  get isClosed() {
+    return this.driverConnection.isClosed();
+  }
+  async run(sql, params, options) {
+    assertParamArity(sql, params);
+    const decision = evaluateGuard(sql, {
+      readOnly: this.config.readOnly,
+      allowDestructive: options.allowDestructive ?? this.config.allowDestructive
+    });
+    if (!decision.allowed) {
+      if (decision.violation === "read-only") {
+        throw new ReadOnlyViolationError(
+          decision.reason ?? "read-only mode blocks this statement"
+        );
+      }
+      throw new DestructiveStatementError(
+        decision.reason ?? "destructive statement blocked"
+      );
+    }
+    const kind = classifyStatement(sql);
+    const autoLimit = options.autoLimit ?? this.config.autoLimit;
+    const limited = kind === "select" ? applyAutoLimit(sql, autoLimit) : { sql, applied: false };
+    const timeoutMs = options.timeoutMs ?? this.config.queryTimeoutMs;
+    const started = Date.now();
+    const execResult = await withTimeout(
+      this.driverConnection.exec(limited.sql, params),
+      timeoutMs,
+      () => {
+        void this.closeQuietly();
+      }
+    );
+    const elapsedMs = Date.now() - started;
+    return {
+      rows: execResult.rows,
+      columns: execResult.columns,
+      rowCount: kind === "select" ? execResult.rows.length : execResult.affectedRows,
+      statement: kind,
+      truncated: limited.applied && execResult.rows.length === autoLimit,
+      elapsedMs
+    };
+  }
+  async closeQuietly() {
+    try {
+      await this.driverConnection.close();
+    } catch {
+    }
+  }
+};
+
+// src/pool.ts
+async function closeQuietly(connection) {
+  try {
+    await connection.close();
+  } catch {
+  }
+}
+var ConnectionPool = class {
+  constructor(driver, config, options) {
+    this.driver = driver;
+    this.config = config;
+    this.maxSize = Math.max(1, options?.max ?? DEFAULT_POOL_MAX);
+    this.idleTimeoutMs = options?.idleTimeoutMs ?? DEFAULT_POOL_IDLE_MS;
+  }
+  driver;
+  config;
+  idle = [];
+  busy = /* @__PURE__ */ new Set();
+  waiters = [];
+  maxSize;
+  idleTimeoutMs;
+  created = 0;
+  draining = false;
+  /** Total connections currently owned by the pool (idle + busy). */
+  get size() {
+    return this.created;
+  }
+  /** Connections currently idle and immediately reusable. */
+  get available() {
+    return this.idle.length;
+  }
+  /** Borrow a connection, opening or queueing as needed. */
+  async acquire() {
+    if (this.draining) {
+      throw new CfHanaError("POOL_CLOSED", "Connection pool is draining");
+    }
+    const reused = this.takeIdleConnection();
+    if (reused !== void 0) {
+      this.busy.add(reused);
+      return reused;
+    }
+    if (this.created < this.maxSize) {
+      return await this.openBusyConnection();
+    }
+    return await new Promise((resolve, reject) => {
+      this.waiters.push({ resolve, reject });
+    });
+  }
+  /** Return a borrowed connection to the pool. */
+  release(connection) {
+    if (!this.busy.delete(connection)) {
+      return;
+    }
+    if (connection.isClosed) {
+      this.created -= 1;
+      this.servePendingWaiters();
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter !== void 0) {
+      this.busy.add(connection);
+      waiter.resolve(connection);
+      return;
+    }
+    if (this.draining) {
+      this.created -= 1;
+      void closeQuietly(connection);
+      return;
+    }
+    this.idle.push({ connection, since: Date.now() });
+  }
+  /** Run `work` with a borrowed connection, releasing it afterwards. */
+  async withConnection(work) {
+    const connection = await this.acquire();
+    try {
+      return await work(connection);
+    } finally {
+      this.release(connection);
+    }
+  }
+  /** Reject queued waiters and close idle connections. */
+  async drain() {
+    this.draining = true;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      if (waiter !== void 0) {
+        waiter.reject(new CfHanaError("POOL_CLOSED", "Connection pool was drained"));
+      }
+    }
+    const idleConnections = this.idle.splice(0).map((entry) => entry.connection);
+    this.created -= idleConnections.length;
+    await Promise.all(idleConnections.map((connection) => closeQuietly(connection)));
+  }
+  takeIdleConnection() {
+    for (; ; ) {
+      const entry = this.idle.pop();
+      if (entry === void 0) {
+        return void 0;
+      }
+      if (entry.connection.isClosed) {
+        this.created -= 1;
+        continue;
+      }
+      if (this.idleTimeoutMs > 0 && Date.now() - entry.since > this.idleTimeoutMs) {
+        this.created -= 1;
+        void closeQuietly(entry.connection);
+        continue;
+      }
+      return entry.connection;
+    }
+  }
+  async openBusyConnection() {
+    this.created += 1;
+    let connection;
+    try {
+      connection = await Connection.open(this.driver, this.config);
+    } catch (error) {
+      this.created -= 1;
+      throw error;
+    }
+    this.busy.add(connection);
+    return connection;
+  }
+  servePendingWaiters() {
+    while (this.waiters.length > 0 && this.created < this.maxSize) {
+      const waiter = this.waiters.shift();
+      if (waiter === void 0) {
+        return;
+      }
+      this.created += 1;
+      void Connection.open(this.driver, this.config).then(
+        (connection) => {
+          this.busy.add(connection);
+          waiter.resolve(connection);
+        },
+        (error) => {
+          this.created -= 1;
+          waiter.reject(error);
+        }
+      );
+    }
+  }
+};
+
+// src/transaction.ts
+var Transaction = class {
+  constructor(connection) {
+    this.connection = connection;
+  }
+  connection;
+  finished = false;
+  /** Whether the transaction has already been committed or rolled back. */
+  get isFinished() {
+    return this.finished;
+  }
+  async query(sql, params, options) {
+    this.assertActive();
+    return await this.connection.query(sql, params, options);
+  }
+  async execute(sql, params, options) {
+    this.assertActive();
+    return await this.connection.execute(sql, params, options);
+  }
+  async commit() {
+    this.assertActive();
+    this.finished = true;
+    await this.connection.commit();
+  }
+  async rollback() {
+    this.assertActive();
+    this.finished = true;
+    await this.connection.rollback();
+  }
+  assertActive() {
+    if (this.finished) {
+      throw new CfHanaError(
+        "QUERY",
+        "This transaction has already been committed or rolled back"
+      );
+    }
+  }
+};
+
+// src/client.ts
+var HanaClient = class _HanaClient {
+  constructor(pool, info) {
+    this.pool = pool;
+    this.info = info;
+  }
+  pool;
+  info;
+  /** Open a client for a `region/org/space/app` selector (or a bare app name). */
+  static async connect(selector, options = {}) {
+    const resolved = await resolveAppBindings(selector, options);
+    const role = options.role ?? "runtime";
+    const binding = selectBinding(resolved.bindings, options);
+    const target = toConnectionTarget(binding, role);
+    const driver = createDriver();
+    const config = {
+      host: target.host,
+      port: target.port,
+      user: target.user,
+      password: target.password,
+      schema: target.schema,
+      certificate: target.certificate,
+      connectTimeoutMs: options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+      queryTimeoutMs: options.queryTimeoutMs ?? DEFAULT_QUERY_TIMEOUT_MS,
+      readOnly: options.readOnly ?? false,
+      allowDestructive: options.allowDestructive ?? false,
+      autoLimit: options.autoLimit ?? DEFAULT_AUTO_LIMIT
+    };
+    const poolOptions = options.pool === false ? { max: 1 } : options.pool ?? {};
+    const info = {
+      selector: resolved.selector,
+      appName: resolved.appName,
+      host: target.host,
+      schema: target.schema,
+      role,
+      driver: driver.name,
+      credentialSource: resolved.source
+    };
+    return new _HanaClient(new ConnectionPool(driver, config, poolOptions), info);
+  }
+  /** Run a SELECT (or any read) statement and return typed rows. */
+  async query(sql, params, options) {
+    return await this.pool.withConnection(
+      (connection) => connection.query(sql, params, options)
+    );
+  }
+  /** Run a DML/DDL statement and return its affected-row count. */
+  async execute(sql, params, options) {
+    return await this.pool.withConnection(
+      (connection) => connection.execute(sql, params, options)
+    );
+  }
+  /** Run a typed `SELECT` built from a spec. */
+  async selectFrom(spec) {
+    const built = buildSelect(spec);
+    return await this.query(built.sql, built.params);
+  }
+  /** Count rows in a table, optionally filtered. */
+  async count(spec) {
+    const built = buildCount(spec);
+    const result = await this.query(built.sql, built.params);
+    return result.rows[0]?.COUNT ?? 0;
+  }
+  /** Insert a single row. */
+  async insertInto(schema, table, values) {
+    const built = buildInsert(schema, table, values);
+    return await this.execute(built.sql, built.params);
+  }
+  /** Update rows matching a non-empty `where` filter. */
+  async update(schema, table, values, where) {
+    const built = buildUpdate(schema, table, values, where);
+    return await this.execute(built.sql, built.params);
+  }
+  /** Delete rows matching a non-empty `where` filter. */
+  async deleteFrom(schema, table, where) {
+    const built = buildDelete(schema, table, where);
+    return await this.execute(built.sql, built.params);
+  }
+  /** Run `work` inside a transaction, auto-committing on success. */
+  async transaction(work) {
+    return await this.pool.withConnection(async (connection) => {
+      await connection.setAutoCommit(false);
+      const tx = new Transaction(connection);
+      try {
+        const result = await work(tx);
+        if (!tx.isFinished) {
+          await tx.commit();
+        }
+        return result;
+      } catch (error) {
+        if (!tx.isFinished) {
+          try {
+            await tx.rollback();
+          } catch {
+          }
+        }
+        throw error;
+      } finally {
+        await connection.setAutoCommit(true);
+      }
+    });
+  }
+  /** List every schema visible to the connected user. */
+  async listSchemas() {
+    return await this.pool.withConnection((connection) => listSchemas(connection));
+  }
+  /** List the tables in a schema. */
+  async listTables(schema) {
+    return await this.pool.withConnection((connection) => listTables(connection, schema));
+  }
+  /** List the columns of a table. */
+  async listColumns(schema, table) {
+    return await this.pool.withConnection(
+      (connection) => listColumns(connection, schema, table)
+    );
+  }
+  /** Return the HANA execution plan for a statement. */
+  async explain(sql, params) {
+    return await this.pool.withConnection(async (connection) => {
+      const statementName = `cf_hana_${String(Date.now())}`;
+      await connection.execute(
+        `EXPLAIN PLAN SET STATEMENT_NAME = '${statementName}' FOR ${sql}`,
+        params
+      );
+      try {
+        return await connection.query(
+          "SELECT OPERATOR_NAME, TABLE_NAME, TABLE_TYPE, EXECUTION_ENGINE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ? ORDER BY OPERATOR_ID",
+          [statementName]
+        );
+      } finally {
+        await connection.execute(
+          "DELETE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ?",
+          [statementName]
+        );
+      }
+    });
+  }
+  /** Close every pooled connection. The client must not be used afterwards. */
+  async close() {
+    await this.pool.drain();
+  }
+};
+
+// src/api.ts
+async function connect(selector, options) {
+  return await HanaClient.connect(selector, options);
+}
+
+// src/format.ts
+function cellText(value, nullText) {
+  if (value === null) {
+    return nullText;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Buffer.isBuffer(value)) {
+    return `0x${value.toString("hex")}`;
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return typeof value === "number" ? value.toString() : value;
+}
+function serializeCell(value) {
+  if (value === null) {
+    return null;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Buffer.isBuffer(value)) {
+    return `0x${value.toString("hex")}`;
+  }
+  return value;
+}
+function csvEscape(text) {
+  if (/[",\r\n]/.test(text)) {
+    return `"${text.replace(/"/g, '""')}"`;
+  }
+  return text;
+}
+function formatTable(result) {
+  if (result.columns.length === 0) {
+    return `(${String(result.rowCount)} row(s) affected)`;
+  }
+  const headers = result.columns.map((column) => column.name);
+  const rows = result.rows.map(
+    (row) => result.columns.map((column) => cellText(row[column.name] ?? null, "NULL"))
+  );
+  const widths = headers.map((header, index) => {
+    const widest = rows.reduce(
+      (max, cells) => Math.max(max, (cells[index] ?? "").length),
+      header.length
+    );
+    return widest;
+  });
+  const renderRow = (cells) => cells.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join(" | ");
+  const separator = widths.map((width) => "-".repeat(width)).join("-+-");
+  const body = rows.map((cells) => renderRow(cells));
+  return [renderRow(headers), separator, ...body].join("\n");
+}
+function formatJson(result) {
+  const rows = result.rows.map((row) => {
+    const serialized = {};
+    for (const [key, value] of Object.entries(row)) {
+      serialized[key] = serializeCell(value);
+    }
+    return serialized;
+  });
+  return JSON.stringify(rows, null, 2);
+}
+function formatCsv(result) {
+  const headers = result.columns.map((column) => column.name);
+  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(",")
+    );
+  }
+  return lines.join("\r\n");
+}
+function formatResult(result, format) {
+  switch (format) {
+    case "table":
+      return formatTable(result);
+    case "json":
+      return formatJson(result);
+    case "csv":
+      return formatCsv(result);
+  }
+}
+
+// src/cli.ts
+function print(text) {
+  process.stdout.write(`${text}
+`);
+}
+function fail(message) {
+  process.stderr.write(`${CLI_NAME}: ${message}
+`);
+  process.exit(1);
+}
+function parseIntOption(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed)) {
+    throw new CfHanaError("CONFIG", `Expected an integer but received "${value}"`);
+  }
+  return parsed;
+}
+function collectParam(value, previous) {
+  return [...previous, value];
+}
+function parseRole(role) {
+  if (role === "runtime" || role === "hdi") {
+    return role;
+  }
+  throw new CfHanaError("CONFIG", `Invalid --role "${role}" (expected runtime or hdi)`);
+}
+function parseFormat(format) {
+  if (format === "table" || format === "json" || format === "csv") {
+    return format;
+  }
+  throw new CfHanaError("CONFIG", `Invalid --format "${format}" (expected table, json, or csv)`);
+}
+function parseQualifiedName(value) {
+  const dot = value.indexOf(".");
+  if (dot <= 0 || dot >= value.length - 1) {
+    throw new CfHanaError("CONFIG", `Expected schema.table but received "${value}"`);
+  }
+  return { schema: value.slice(0, dot), table: value.slice(dot + 1) };
+}
+function toConnectOptions(opts) {
+  return {
+    refresh: opts.refresh,
+    role: parseRole(opts.role),
+    readOnly: opts.readOnly,
+    allowDestructive: opts.allowDestructive,
+    autoLimit: opts.autoLimit ? opts.limit ?? DEFAULT_AUTO_LIMIT : false,
+    ...opts.binding === void 0 ? {} : { bindingName: opts.binding },
+    ...opts.bindingIndex === void 0 ? {} : { bindingIndex: opts.bindingIndex },
+    ...opts.timeout === void 0 ? {} : { queryTimeoutMs: opts.timeout, connectTimeoutMs: opts.timeout }
+  };
+}
+function rowsToResult(rows) {
+  const first = rows[0];
+  const columns = first === void 0 ? [] : Object.keys(first).map((name) => ({ name, typeName: "" }));
+  return {
+    rows,
+    columns,
+    rowCount: rows.length,
+    statement: "select",
+    truncated: false,
+    elapsedMs: 0
+  };
+}
+function formatInfo(info) {
+  return [
+    `selector           ${info.selector}`,
+    `app                ${info.appName}`,
+    `host               ${info.host}`,
+    `schema             ${info.schema}`,
+    `role               ${info.role}`,
+    `driver             ${info.driver}`,
+    `credential source  ${info.credentialSource}`
+  ].join("\n");
+}
+function withConnectionOptions(command) {
+  return command.option("--format <format>", "output format: table, json, or csv", "table").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", parseIntOption).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", parseIntOption).option("--limit <n>", "row cap auto-applied to bare SELECT statements", parseIntOption).option("--no-auto-limit", "disable the automatic SELECT row cap");
+}
+async function runQuery(selector, sql, command) {
+  const opts = command.opts();
+  const client = await connect(selector, toConnectOptions(opts));
+  try {
+    const result = await client.query(sql, opts.param ?? []);
+    print(formatResult(result, parseFormat(opts.format)));
+  } finally {
+    await client.close();
+  }
+}
+async function runTables(selector, schema, command) {
+  const opts = command.opts();
+  const client = await connect(selector, toConnectOptions(opts));
+  try {
+    const tables = await client.listTables(schema ?? client.info.schema);
+    const rows = tables.map((table) => ({
+      SCHEMA: table.schema,
+      TABLE: table.name,
+      TYPE: table.type
+    }));
+    print(formatResult(rowsToResult(rows), parseFormat(opts.format)));
+  } finally {
+    await client.close();
+  }
+}
+async function runColumns(selector, target, command) {
+  const opts = command.opts();
+  const { schema, table } = parseQualifiedName(target);
+  const client = await connect(selector, toConnectOptions(opts));
+  try {
+    const columns = await client.listColumns(schema, table);
+    const rows = columns.map((column) => ({
+      COLUMN: column.name,
+      TYPE: column.dataType,
+      LENGTH: column.length ?? null,
+      NULLABLE: column.nullable,
+      POSITION: column.position
+    }));
+    print(formatResult(rowsToResult(rows), parseFormat(opts.format)));
+  } finally {
+    await client.close();
+  }
+}
+async function runCount(selector, target, command) {
+  const opts = command.opts();
+  const { schema, table } = parseQualifiedName(target);
+  const client = await connect(selector, toConnectOptions(opts));
+  try {
+    const total = await client.count({ schema, table });
+    print(String(total));
+  } finally {
+    await client.close();
+  }
+}
+async function runPing(selector, command) {
+  const opts = command.opts();
+  const client = await connect(selector, toConnectOptions(opts));
+  try {
+    const started = Date.now();
+    await client.query("SELECT 1 FROM DUMMY");
+    print(
+      `OK  ${client.info.host}  schema=${client.info.schema}  ${String(Date.now() - started)}ms`
+    );
+  } finally {
+    await client.close();
+  }
+}
+async function runInfo(selector, command) {
+  const opts = command.opts();
+  const client = await connect(selector, toConnectOptions(opts));
+  try {
+    print(formatInfo(client.info));
+  } finally {
+    await client.close();
+  }
+}
+function buildProgram() {
+  const program = new Command();
+  program.name(CLI_NAME).description("Run SQL against SAP HANA Cloud databases bound to a Cloud Foundry app").version(CLI_VERSION);
+  withConnectionOptions(
+    program.command("query <selector> <sql>").description("run a single SQL statement").option("--param <value>", "bind a SQL parameter (repeatable)", collectParam, [])
+  ).action(async (selector, sql, _options, command) => {
+    await runQuery(selector, sql, command);
+  });
+  withConnectionOptions(
+    program.command("tables <selector> [schema]").description("list tables in a schema")
+  ).action(
+    async (selector, schema, _options, command) => {
+      await runTables(selector, schema, command);
+    }
+  );
+  withConnectionOptions(
+    program.command("columns <selector> <schema.table>").description("list the columns of a table")
+  ).action(async (selector, target, _options, command) => {
+    await runColumns(selector, target, command);
+  });
+  withConnectionOptions(
+    program.command("count <selector> <schema.table>").description("count rows in a table")
+  ).action(async (selector, target, _options, command) => {
+    await runCount(selector, target, command);
+  });
+  withConnectionOptions(
+    program.command("ping <selector>").description("connect and measure round-trip latency")
+  ).action(async (selector, _options, command) => {
+    await runPing(selector, command);
+  });
+  withConnectionOptions(
+    program.command("info <selector>").description("print the resolved connection metadata")
+  ).action(async (selector, _options, command) => {
+    await runInfo(selector, command);
+  });
+  return program;
+}
+try {
+  await buildProgram().parseAsync(process.argv);
+} catch (error) {
+  fail(errorMessage(error));
+}
+//# sourceMappingURL=cli.js.map