@saptools/cf-hana 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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.

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-api");
+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-api", "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-api`). Works
-  without any cached topology.
-- **Bare app name** — `orders-api`. 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-api "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-api
-cf-hana columns orders-api ORDERS_APP.ORDERS
-cf-hana ping eu10/acme/dev/orders-api
+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.2";
+var CLI_VERSION = "0.1.3";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -669,6 +669,81 @@ 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"]);
@@ -1167,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) {
@@ -1280,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