@saptools/cf-hana 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.3 - 2026-06-23
+
+- Add local SQL history for successful direct `query` and `execute` calls under
+  `~/.saptools/cf-hana/histories/YYYY-MM-DD.jsonl`.
+- Rotate SQL history with five-day retention and keep parameter values,
+  credentials, certificates, and result rows out of the history file.
+- Keep helper-driven catalog SQL out of user SQL history and document the new
+  local state behavior.
+
+## 0.1.2 - 2026-06-23
+
+- Harden connection pooling so queued callers continue after transient reconnect failures.
+- Preserve query results when HANA statement cleanup fails and close partially opened clients on schema setup errors.
+- Strengthen read-only and destructive-statement checks around comments, quoted identifiers, and unknown statements.
+- Improve `explain()` statement isolation, cleanup, and read-only behavior.
+- Validate CLI numeric options strictly and align E2E diagnostics with project defaults.
+
 ## 0.1.1 - 2026-05-22
 
 - Patch release to publish via npm trusted publishing after the manual `0.1.0` bootstrap.

package/README.md

@@ -22,6 +22,8 @@ login on the hot path) and connections are pooled and reused within a process.
 - **Query-builder shorthands** — `selectFrom`, `count`, `insertInto`, `update`,
   `deleteFrom` — query a table by name without writing SQL.
 - **Schema introspection** — list schemas, tables, and columns.
+- **Local SQL history** — direct SQL calls are appended to dated JSONL files
+  under `~/.saptools/cf-hana/histories/` with five-day retention.
 - **Safety guard** — opt-in read-only mode and a destructive-statement guard
   (blocks `DROP`/`TRUNCATE`/`ALTER` and unscoped `UPDATE`/`DELETE`).
 - **Typed results** — `query<TRow>()` returns typed rows.
@@ -44,7 +46,7 @@ driver is bundled as a dependency — there is no native build step.
 import { connect, query } from "@saptools/cf-hana";
 
 // Open a reusable, pooled client for one CF app's HANA database.
-const db = await connect("eu10/acme/dev/orders-srv");
+const db = await connect("eu10/example-org/space-demo/app-demo");
 
 const open = await db.query("SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?", ["OPEN"]);
 console.log(open.rows);
@@ -58,16 +60,16 @@ await db.transaction(async (tx) => {
 await db.close();
 
 // One-shot: connect, run one query, close.
-const rows = await query("orders-srv", "SELECT COUNT(*) AS N FROM ORDERS");
+const rows = await query("app-demo", "SELECT COUNT(*) AS N FROM ORDERS");
 ```
 
 ## The selector
 
 Every entry point takes a selector as its first argument:
 
-- **Explicit** — `region/org/space/app` (e.g. `eu10/acme/dev/orders-srv`). Works
-  without any cached topology.
-- **Bare app name** — `orders-srv`. Resolved against the topology cached by
+- **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.
 
 ## CLI
@@ -87,11 +89,11 @@ Common options: `--format <table|json|csv>`, `--refresh`, `--role <runtime|hdi>`
 accepts `--param <value>` (repeatable) to bind `?` placeholders.
 
 ```bash
-cf-hana query eu10/acme/dev/orders-srv "SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?" \
+cf-hana query eu10/example-org/space-demo/app-demo "SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?" \
   --param OPEN --format json
-cf-hana tables orders-srv
-cf-hana columns orders-srv ORDERS_APP.ORDERS
-cf-hana ping eu10/acme/dev/orders-srv
+cf-hana tables app-demo
+cf-hana columns app-demo ORDERS_APP.ORDERS
+cf-hana ping eu10/example-org/space-demo/app-demo
 ```
 
 ## Programmatic API
@@ -117,11 +119,28 @@ Credentials are resolved **cache-first**:
    live from Cloud Foundry. The live fetch needs `SAP_EMAIL` and `SAP_PASSWORD`
    (or the `email` / `password` options) and never persists anything to disk.
 
-`cf-hana` itself writes nothing under `~/.saptools/` — it only reads what
+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.
 
+## SQL history
+
+Successful direct SQL calls are appended to daily JSONL files:
+
+```text
+~/.saptools/cf-hana/histories/YYYY-MM-DD.jsonl
+```
+
+Each entry includes the timestamp, package version, selector, app name, schema,
+role, operation (`query` or `execute`), statement kind, SQL text, parameter
+count, row count, truncation flag, and elapsed time. Parameter values,
+credentials, certificates, and result rows are not stored.
+
+History retention runs opportunistically after each append and deletes dated
+history files older than five days. Helper-driven catalog SQL such as `tables`
+and `columns` is not recorded as user SQL history.
+
 ## Safety
 
 - **Read-only mode** (`readOnly` / `--read-only`) rejects every DML and DDL statement.

package/dist/cli.js

@@ -247,7 +247,7 @@ async function listColumns(connection, schema, table) {
 
 // src/config.ts
 var CLI_NAME = "cf-hana";
-var CLI_VERSION = "0.1.1";
+var CLI_VERSION = "0.1.3";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -498,7 +498,7 @@ var HdbConnection = class {
       const raw = await this.executeStatement(statement, params);
       return toExecResult(statement, raw);
     } finally {
-      statement.drop();
+      dropStatementQuietly(statement);
     }
   }
   setAutoCommit(enabled) {
@@ -565,6 +565,12 @@ var HdbConnection = class {
     });
   }
 };
+function dropStatementQuietly(statement) {
+  try {
+    statement.drop();
+  } catch {
+  }
+}
 function openClient(client, timeoutMs) {
   return new Promise((resolve, reject) => {
     let settled = false;
@@ -600,6 +606,20 @@ function openClient(client, timeoutMs) {
     });
   });
 }
+async function closeClientQuietly(client) {
+  try {
+    await new Promise((resolve) => {
+      client.disconnect(() => {
+        resolve();
+      });
+    });
+  } catch {
+  }
+  try {
+    client.close();
+  } catch {
+  }
+}
 function setCurrentSchema(client, schema) {
   return new Promise((resolve, reject) => {
     client.exec(`SET SCHEMA ${quoteIdentifier(schema)}`, (error) => {
@@ -621,7 +641,12 @@ async function connectHdb(params) {
     useTLS: true
   });
   await openClient(client, params.connectTimeoutMs);
-  await setCurrentSchema(client, params.schema);
+  try {
+    await setCurrentSchema(client, params.schema);
+  } catch (error) {
+    await closeClientQuietly(client);
+    throw error;
+  }
   return new HdbConnection(client);
 }
 function createHdbDriver() {
@@ -644,14 +669,178 @@ function createDriver(name) {
   }
 }
 
+// src/history.ts
+import { appendFile, mkdir, readdir, rm } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+var SAPTOOLS_DIR_NAME = ".saptools";
+var CF_HANA_DIR_NAME = "cf-hana";
+var HISTORIES_DIR_NAME = "histories";
+var HISTORY_RETENTION_DAYS = 5;
+var HISTORY_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+function defaultSaptoolsRoot() {
+  return join(homedir(), SAPTOOLS_DIR_NAME);
+}
+function padDatePart(value) {
+  return value.toString().padStart(2, "0");
+}
+function dateKey(date) {
+  return [
+    date.getFullYear().toString(),
+    padDatePart(date.getMonth() + 1),
+    padDatePart(date.getDate())
+  ].join("-");
+}
+function retentionCutoffKey(now) {
+  const cutoff = new Date(now);
+  cutoff.setHours(0, 0, 0, 0);
+  cutoff.setDate(cutoff.getDate() - HISTORY_RETENTION_DAYS);
+  return dateKey(cutoff);
+}
+function resolveSaptoolsRoot(root) {
+  return root ?? defaultSaptoolsRoot();
+}
+function cfHanaHistoryDirectory(saptoolsRoot) {
+  return join(resolveSaptoolsRoot(saptoolsRoot), CF_HANA_DIR_NAME, HISTORIES_DIR_NAME);
+}
+function sqlHistoryFilePath(now = /* @__PURE__ */ new Date(), saptoolsRoot) {
+  return join(cfHanaHistoryDirectory(saptoolsRoot), `${dateKey(now)}.jsonl`);
+}
+async function pruneSqlHistory(now, saptoolsRoot) {
+  const historyDir = cfHanaHistoryDirectory(saptoolsRoot);
+  let files;
+  try {
+    files = await readdir(historyDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  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(join(historyDir, file), { force: true });
+    })
+  );
+}
+async function appendSqlHistory(input, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const historyDir = cfHanaHistoryDirectory(options.saptoolsRoot);
+  const entry = {
+    at: now.toISOString(),
+    ...input
+  };
+  await mkdir(historyDir, { recursive: true, mode: 448 });
+  await appendFile(sqlHistoryFilePath(now, options.saptoolsRoot), `${JSON.stringify(entry)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+  try {
+    await pruneSqlHistory(now, options.saptoolsRoot);
+  } catch {
+  }
+  return entry;
+}
+
 // 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 skipQuotedText(sql, start) {
+  const quote = sql[start];
+  let index = start + 1;
+  while (index < sql.length) {
+    if (sql[index] === quote) {
+      if (sql[index + 1] === quote) {
+        index += 2;
+        continue;
+      }
+      index += 1;
+      break;
+    }
+    index += 1;
+  }
+  return index;
+}
+function skipLineComment(sql, start) {
+  let index = start + 2;
+  while (index < sql.length && sql[index] !== "\n") {
+    index += 1;
+  }
+  return index;
+}
+function skipBlockComment(sql, start) {
+  let index = start + 2;
+  while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
+    index += 1;
+  }
+  return Math.min(index + 2, sql.length);
+}
+function maskIgnoredSqlText(sql) {
+  let masked = "";
+  let index = 0;
+  while (index < sql.length) {
+    const char = sql[index];
+    if (char === "'" || char === '"') {
+      const end = skipQuotedText(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      const end = skipLineComment(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      const end = skipBlockComment(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    masked += char ?? "";
+    index += 1;
+  }
+  return masked;
 }
 function hasWhereClause(sql) {
-  return /\bwhere\b/i.test(stripStringLiterals(sql));
+  return /\bwhere\b/i.test(maskIgnoredSqlText(sql));
+}
+function trailingLineCommentIndex(sql) {
+  let index = 0;
+  while (index < sql.length) {
+    const char = sql[index];
+    if (char === "'" || char === '"') {
+      index = skipQuotedText(sql, index);
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      index = skipBlockComment(sql, index);
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      const lineEnd = sql.indexOf("\n", index + 2);
+      if (lineEnd === -1 || sql.slice(lineEnd + 1).trim().length === 0) {
+        return index;
+      }
+      index = lineEnd + 1;
+      continue;
+    }
+    index += 1;
+  }
+  return void 0;
+}
+function appendLimit(sql, limit) {
+  const trimmed = sql.replace(/[\s;]+$/, "");
+  const commentIndex = trailingLineCommentIndex(trimmed);
+  if (commentIndex === void 0) {
+    return `${trimmed} LIMIT ${String(limit)}`;
+  }
+  const beforeComment = trimmed.slice(0, commentIndex).replace(/[\s;]+$/, "");
+  const comment = trimmed.slice(commentIndex);
+  return `${beforeComment} LIMIT ${String(limit)} ${comment}`;
 }
 function inspectStatement(sql) {
   const kind = classifyStatement(sql);
@@ -669,12 +858,12 @@ function inspectStatement(sql) {
 }
 function evaluateGuard(sql, config) {
   const inspection = inspectStatement(sql);
-  if (config.readOnly && (inspection.kind === "dml" || inspection.kind === "ddl")) {
+  if (config.readOnly && inspection.kind !== "select") {
     return {
       allowed: false,
       destructive: inspection.destructive,
       violation: "read-only",
-      reason: `read-only mode blocks ${inspection.kind.toUpperCase()} statements`
+      reason: inspection.kind === "unknown" ? "read-only mode only permits SELECT/WITH statements" : `read-only mode blocks ${inspection.kind.toUpperCase()} statements`
     };
   }
   if (inspection.destructive && !config.allowDestructive) {
@@ -696,12 +885,11 @@ function applyAutoLimit(sql, limit) {
   if (limit === false || classifyStatement(sql) !== "select") {
     return { sql, applied: false };
   }
-  const stripped = stripStringLiterals(sql);
+  const stripped = maskIgnoredSqlText(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 };
+  return { sql: appendLimit(sql, limit), applied: true };
 }
 
 // src/connection.ts
@@ -750,6 +938,12 @@ var Connection = class _Connection {
   async execute(sql, params, options) {
     return await this.run(sql, params ?? [], options ?? {});
   }
+  assertAllowed(sql, options) {
+    this.evaluateSafety(sql, options ?? {});
+  }
+  async executeInternal(sql, params, options) {
+    return await this.run(sql, params ?? [], options ?? {}, { bypassSafety: true });
+  }
   async setAutoCommit(enabled) {
     await this.driverConnection.setAutoCommit(enabled);
   }
@@ -765,21 +959,10 @@ var Connection = class _Connection {
   get isClosed() {
     return this.driverConnection.isClosed();
   }
-  async run(sql, params, options) {
+  async run(sql, params, options, runOptions = {}) {
     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"
-      );
+    if (runOptions.bypassSafety !== true) {
+      this.evaluateSafety(sql, options);
     }
     const kind = classifyStatement(sql);
     const autoLimit = options.autoLimit ?? this.config.autoLimit;
@@ -809,6 +992,23 @@ var Connection = class _Connection {
     } catch {
     }
   }
+  evaluateSafety(sql, options) {
+    const decision = evaluateGuard(sql, {
+      readOnly: this.config.readOnly,
+      allowDestructive: options.allowDestructive ?? this.config.allowDestructive
+    });
+    if (decision.allowed) {
+      return;
+    }
+    if (decision.violation === "read-only") {
+      throw new ReadOnlyViolationError(
+        decision.reason ?? "read-only mode blocks this statement"
+      );
+    }
+    throw new DestructiveStatementError(
+      decision.reason ?? "destructive statement blocked"
+    );
+  }
 };
 
 // src/pool.ts
@@ -949,6 +1149,7 @@ var ConnectionPool = class {
         (error) => {
           this.created -= 1;
           waiter.reject(error);
+          this.servePendingWaiters();
         }
       );
     }
@@ -995,6 +1196,11 @@ var Transaction = class {
 };
 
 // src/client.ts
+var explainStatementCounter = 0;
+function nextExplainStatementName() {
+  explainStatementCounter = (explainStatementCounter + 1) % Number.MAX_SAFE_INTEGER;
+  return `cf_hana_${String(process.pid)}_${String(Date.now())}_${String(explainStatementCounter)}`;
+}
 var HanaClient = class _HanaClient {
   constructor(pool, info) {
     this.pool = pool;
@@ -1036,41 +1242,43 @@ var HanaClient = class _HanaClient {
   }
   /** 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)
-    );
+    const resolvedParams = params ?? [];
+    const result = await this.runQuery(sql, resolvedParams, options);
+    await this.recordSqlHistory("query", sql, resolvedParams, result);
+    return result;
   }
   /** 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)
-    );
+    const resolvedParams = params ?? [];
+    const result = await this.runExecute(sql, resolvedParams, options);
+    await this.recordSqlHistory("execute", sql, resolvedParams, result);
+    return result;
   }
   /** Run a typed `SELECT` built from a spec. */
   async selectFrom(spec) {
     const built = buildSelect(spec);
-    return await this.query(built.sql, built.params);
+    return await this.runQuery(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);
+    const result = await this.runQuery(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);
+    return await this.runExecute(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);
+    return await this.runExecute(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);
+    return await this.runExecute(built.sql, built.params);
   }
   /** Run `work` inside a transaction, auto-committing on success. */
   async transaction(work) {
@@ -1113,21 +1321,35 @@ var HanaClient = class _HanaClient {
   /** 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(
+      connection.assertAllowed(sql);
+      const statementName = nextExplainStatementName();
+      await connection.executeInternal(
         `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",
+      const cleanup = async () => {
+        await connection.executeInternal(
+          "DELETE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ?",
           [statementName]
         );
-      } finally {
-        await connection.execute(
-          "DELETE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ?",
+      };
+      let queryCompleted = false;
+      try {
+        const result = await connection.query(
+          "SELECT OPERATOR_NAME, TABLE_NAME, TABLE_TYPE, EXECUTION_ENGINE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ? ORDER BY OPERATOR_ID",
           [statementName]
         );
+        queryCompleted = true;
+        await cleanup();
+        return result;
+      } catch (error) {
+        if (!queryCompleted) {
+          try {
+            await cleanup();
+          } catch {
+          }
+        }
+        throw error;
       }
     });
   }
@@ -1135,6 +1357,35 @@ var HanaClient = class _HanaClient {
   async close() {
     await this.pool.drain();
   }
+  async runQuery(sql, params, options) {
+    return await this.pool.withConnection(
+      (connection) => connection.query(sql, params, options)
+    );
+  }
+  async runExecute(sql, params, options) {
+    return await this.pool.withConnection(
+      (connection) => connection.execute(sql, params, options)
+    );
+  }
+  async recordSqlHistory(operation, sql, params, result) {
+    try {
+      await appendSqlHistory({
+        version: CLI_VERSION,
+        operation,
+        selector: this.info.selector,
+        appName: this.info.appName,
+        schema: this.info.schema,
+        role: this.info.role,
+        statement: result.statement,
+        sql,
+        paramCount: params.length,
+        rowCount: result.rowCount,
+        truncated: result.truncated,
+        elapsedMs: result.elapsedMs
+      });
+    } catch {
+    }
+  }
 };
 
 // src/api.ts
@@ -1238,12 +1489,26 @@ function fail(message) {
   process.exit(1);
 }
 function parseIntOption(value) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isInteger(parsed)) {
+  const trimmed = value.trim();
+  if (!/^-?\d+$/.test(trimmed)) {
     throw new CfHanaError("CONFIG", `Expected an integer but received "${value}"`);
   }
+  const parsed = Number(trimmed);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new CfHanaError("CONFIG", `Expected a safe integer but received "${value}"`);
+  }
   return parsed;
 }
+function assertPositiveOption(name, value) {
+  if (value !== void 0 && value <= 0) {
+    throw new CfHanaError("CONFIG", `${name} must be a positive integer`);
+  }
+}
+function assertNonNegativeOption(name, value) {
+  if (value !== void 0 && value < 0) {
+    throw new CfHanaError("CONFIG", `${name} must be a non-negative integer`);
+  }
+}
 function collectParam(value, previous) {
   return [...previous, value];
 }
@@ -1267,6 +1532,9 @@ function parseQualifiedName(value) {
   return { schema: value.slice(0, dot), table: value.slice(dot + 1) };
 }
 function toConnectOptions(opts) {
+  assertPositiveOption("--limit", opts.limit);
+  assertPositiveOption("--timeout", opts.timeout);
+  assertNonNegativeOption("--binding-index", opts.bindingIndex);
   return {
     refresh: opts.refresh,
     role: parseRole(opts.role),