@saptools/cf-hana 0.1.5 → 0.2.0

package/dist/cli.js

@@ -52,6 +52,59 @@ function errorMessage(error) {
   return String(error);
 }
 
+// src/result-preview.ts
+function normalizePreviewChar(value) {
+  return value === "\r" || value === "\n" || value === "	" ? " " : value;
+}
+function previewText(value, limit) {
+  let originalLength = 0;
+  let text = "";
+  for (const char of value) {
+    if (originalLength < limit) {
+      text += normalizePreviewChar(char);
+    }
+    originalLength += 1;
+  }
+  return {
+    text,
+    truncated: originalLength > limit,
+    originalLength,
+    unit: "chars"
+  };
+}
+function previewBuffer(value, limit) {
+  const fullLength = 2 + value.length * 2;
+  const visibleBytes = Math.max(0, Math.floor((limit - 2) / 2));
+  const hex = value.subarray(0, visibleBytes).toString("hex");
+  return {
+    text: `0x${hex}`.slice(0, limit),
+    truncated: fullLength > limit,
+    originalLength: value.length,
+    unit: "bytes"
+  };
+}
+function scalarText(value) {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return value.toString();
+}
+function previewCell(value, limit) {
+  if (value === null) {
+    return { text: "", truncated: false, originalLength: 0, unit: "chars" };
+  }
+  if (Buffer.isBuffer(value)) {
+    return previewBuffer(value, limit);
+  }
+  if (typeof value === "string") {
+    return previewText(value, limit);
+  }
+  return previewText(scalarText(value), limit);
+}
+
 // src/format.ts
 function cellText(value, nullText) {
   if (value === null) {
@@ -126,6 +179,22 @@ function formatCsv(result) {
   }
   return lines.join("\r\n");
 }
+function formatCompactCsv(result, cellLimit) {
+  const headers = result.columns.map((column) => column.name);
+  const lines = [headers.map((header) => csvEscape(header)).join(",")];
+  let truncatedCells = 0;
+  for (const row of result.rows) {
+    const cells = result.columns.map((column) => {
+      const preview = previewCell(row[column.name] ?? null, cellLimit);
+      if (preview.truncated) {
+        truncatedCells += 1;
+      }
+      return csvEscape(preview.text);
+    });
+    lines.push(cells.join(","));
+  }
+  return { text: lines.join("\r\n"), truncatedCells };
+}
 function formatResult(result, format) {
   switch (format) {
     case "table":
@@ -481,14 +550,17 @@ function buildDelete(schema, table, where) {
 // src/catalog.ts
 async function listSchemas(connection) {
   const result = await connection.query(
-    "SELECT SCHEMA_NAME FROM SYS.SCHEMAS ORDER BY SCHEMA_NAME"
+    "SELECT SCHEMA_NAME FROM SYS.SCHEMAS ORDER BY SCHEMA_NAME",
+    [],
+    { autoLimit: false }
   );
   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]
+    [schema],
+    { autoLimit: false }
   );
   return result.rows.map((row) => ({
     schema: row.SCHEMA_NAME,
@@ -500,7 +572,8 @@ async function listTables(connection, schema) {
 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]
+    [schema, table],
+    { autoLimit: false }
   );
   return result.rows.map((row) => ({
     name: row.COLUMN_NAME,
@@ -514,13 +587,18 @@ async function listColumns(connection, schema, table) {
 
 // src/config.ts
 var CLI_NAME = "cf-hana";
-var CLI_VERSION = "0.1.5";
+var CLI_VERSION = "0.2.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;
+var DEFAULT_AUTO_LIMIT = 100;
+var DEFAULT_CELL_LIMIT = 128;
+var MAX_CELL_LIMIT = 1e4;
+var DEFAULT_RESULT_TTL_MINUTES = 60;
+var DEFAULT_RESULT_SEARCH_LIMIT = 20;
+var MAX_RESULT_STORE_BYTES = 256 * 1024 * 1024;
 function envName(suffix) {
   return `${ENV_PREFIX}_${suffix}`;
 }
@@ -633,7 +711,13 @@ function toConnectionTarget(binding, role) {
 }
 
 // src/driver/fake.ts
+import { appendFile } from "fs/promises";
 function fakeExec(sql) {
+  const kind = classifyStatement(sql);
+  const forcedFailure = readEnv(envName("FAKE_FAIL_STATEMENT"))?.toLowerCase();
+  if (forcedFailure === kind) {
+    throw new Error(`fake driver forced ${kind.toUpperCase()} failure`);
+  }
   if (sql.toUpperCase().includes("DUMMY")) {
     return {
       rows: [{ "1": 1 }],
@@ -641,7 +725,6 @@ function fakeExec(sql) {
       affectedRows: 0
     };
   }
-  const kind = classifyStatement(sql);
   if (kind === "select") {
     return {
       rows: [
@@ -660,10 +743,23 @@ function fakeExec(sql) {
   }
   return { rows: [], columns: [], affectedRows: 0 };
 }
+async function traceFakeExec(sql, params) {
+  const tracePath = readEnv(envName("FAKE_TRACE_FILE"));
+  if (tracePath === void 0) {
+    return;
+  }
+  const entry = { sql, paramCount: params.length };
+  await appendFile(tracePath, `${JSON.stringify(entry)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+}
 var FakeConnection = class {
   closed = false;
-  exec(sql, _params) {
-    return Promise.resolve(fakeExec(sql));
+  async exec(sql, params) {
+    await traceFakeExec(sql, params);
+    return fakeExec(sql);
   }
   setAutoCommit(_enabled) {
     return Promise.resolve();
@@ -937,7 +1033,7 @@ function createDriver(name) {
 }
 
 // src/history.ts
-import { appendFile, mkdir as mkdir2, readdir, rm } from "fs/promises";
+import { appendFile as appendFile2, mkdir as mkdir2, readdir, rm } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { join as join2 } from "path";
 var SAPTOOLS_DIR_NAME2 = ".saptools";
@@ -999,7 +1095,7 @@ async function appendSqlHistory(input, options = {}) {
     ...input
   };
   await mkdir2(historyDir, { recursive: true, mode: 448 });
-  await appendFile(sqlHistoryFilePath(now, options.saptoolsRoot), `${JSON.stringify(entry)}
+  await appendFile2(sqlHistoryFilePath(now, options.saptoolsRoot), `${JSON.stringify(entry)}
 `, {
     encoding: "utf8",
     mode: 384
@@ -1156,10 +1252,28 @@ function applyAutoLimit(sql, limit) {
   if (/\blimit\b/i.test(stripped) || /\btop\s+\d/i.test(stripped)) {
     return { sql, applied: false };
   }
-  return { sql: appendLimit(sql, limit), applied: true };
+  return {
+    sql: appendLimit(sql, limit + 1),
+    applied: true,
+    requestedLimit: limit
+  };
 }
 
 // src/connection.ts
+function assertValidAutoLimit(value) {
+  if (value !== false && (!Number.isSafeInteger(value) || value <= 0 || value >= Number.MAX_SAFE_INTEGER)) {
+    throw new CfHanaError("CONFIG", "autoLimit must be a positive safe integer");
+  }
+}
+function boundedRows(rows, requestedLimit) {
+  if (requestedLimit === void 0) {
+    return { rows, truncated: false };
+  }
+  return {
+    rows: rows.slice(0, requestedLimit),
+    truncated: rows.length > requestedLimit
+  };
+}
 async function withTimeout(work, timeoutMs, onTimeout) {
   let timer;
   const timeout = new Promise((_resolve, reject) => {
@@ -1233,6 +1347,7 @@ var Connection = class _Connection {
     }
     const kind = classifyStatement(sql);
     const autoLimit = options.autoLimit ?? this.config.autoLimit;
+    assertValidAutoLimit(autoLimit);
     const limited = kind === "select" ? applyAutoLimit(sql, autoLimit) : { sql, applied: false };
     const timeoutMs = options.timeoutMs ?? this.config.queryTimeoutMs;
     const started = Date.now();
@@ -1244,12 +1359,13 @@ var Connection = class _Connection {
       }
     );
     const elapsedMs = Date.now() - started;
+    const selected = boundedRows(execResult.rows, limited.requestedLimit);
     return {
-      rows: execResult.rows,
+      rows: selected.rows,
       columns: execResult.columns,
-      rowCount: kind === "select" ? execResult.rows.length : execResult.affectedRows,
+      rowCount: kind === "select" ? selected.rows.length : execResult.affectedRows,
       statement: kind,
-      truncated: limited.applied && execResult.rows.length === autoLimit,
+      truncated: selected.truncated,
       elapsedMs
     };
   }
@@ -1681,17 +1797,711 @@ async function connect(selector, options) {
   return await HanaClient.connect(selector, options);
 }
 
-// src/cli.ts
+// src/cli-results.ts
+import { writeFile as writeFile3 } from "fs/promises";
+
+// src/result-inspect.ts
+function assertPositiveInteger(name, value) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new CfHanaError(
+      "CONFIG",
+      `${name} ${String(value)} must be a positive safe integer`
+    );
+  }
+}
+function selectResultRow(session, rowNumber) {
+  assertPositiveInteger("row", rowNumber);
+  const row = session.result.rows[rowNumber - 1];
+  if (row === void 0) {
+    throw new CfHanaError("QUERY", `Saved result row ${String(rowNumber)} not found`);
+  }
+  return row;
+}
+function selectResultCell(session, rowNumber, columnName) {
+  const row = selectResultRow(session, rowNumber);
+  const column = session.result.columns.find((item) => item.name === columnName);
+  if (column === void 0) {
+    throw new CfHanaError("QUERY", `Saved result column "${columnName}" not found`);
+  }
+  return {
+    row: rowNumber,
+    column: column.name,
+    typeName: column.typeName,
+    value: row[column.name] ?? null
+  };
+}
+function textRange(value, offset, length) {
+  let index = 0;
+  let selected = "";
+  for (const char of value) {
+    if (index >= offset && index < offset + length) {
+      selected += char;
+    }
+    index += 1;
+  }
+  return { type: "text", originalLength: index, offset, value: selected };
+}
+function readCellWindow(value, offset, length) {
+  if (!Number.isSafeInteger(offset) || offset < 0) {
+    throw new CfHanaError("CONFIG", "offset must be a non-negative safe integer");
+  }
+  assertPositiveInteger("length", length);
+  if (Buffer.isBuffer(value)) {
+    return {
+      type: "binary",
+      originalLength: value.length,
+      offset,
+      value: `0x${value.subarray(offset, offset + length).toString("hex")}`
+    };
+  }
+  if (typeof value === "string") {
+    return textRange(value, offset, length);
+  }
+  const text = previewCell(value, Number.MAX_SAFE_INTEGER).text;
+  const window = textRange(text, offset, length);
+  return { ...window, type: "scalar" };
+}
+function decodePointerToken(token) {
+  if (/~(?:[^01]|$)/.test(token)) {
+    throw new CfHanaError("CONFIG", "Invalid JSON Pointer escape");
+  }
+  return token.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function pointerTokens(pointer) {
+  if (pointer === "") {
+    return [];
+  }
+  if (!pointer.startsWith("/")) {
+    throw new CfHanaError("CONFIG", "JSON Pointer must be empty or start with /");
+  }
+  return pointer.slice(1).split("/").map(decodePointerToken);
+}
+function resolvePointer(root, pointer) {
+  let current = root;
+  for (const token of pointerTokens(pointer)) {
+    if (Array.isArray(current)) {
+      const index = Number(token);
+      if (!Number.isSafeInteger(index) || index < 0 || index >= current.length) {
+        throw new CfHanaError("QUERY", `JSON Pointer path "${pointer}" not found`);
+      }
+      current = current[index];
+      continue;
+    }
+    if (typeof current === "object" && current !== null && token in current) {
+      current = current[token];
+      continue;
+    }
+    throw new CfHanaError("QUERY", `JSON Pointer path "${pointer}" not found`);
+  }
+  return current;
+}
+function escapePointerToken(token) {
+  return token.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function jsonType(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  return typeof value;
+}
+function jsonValueText(value, limit) {
+  if (Array.isArray(value)) {
+    return `items=${String(value.length)}`;
+  }
+  if (typeof value === "object" && value !== null) {
+    return `keys=${String(Object.keys(value).length)}`;
+  }
+  if (typeof value === "string") {
+    return previewCell(value, limit).text;
+  }
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return "";
+}
+function jsonSearchText(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return "";
+}
+function inspectionRow(path, value, limit) {
+  return { path, type: jsonType(value), value: jsonValueText(value, limit) };
+}
+function inspectJsonCell(value, pointer, limit) {
+  if (typeof value !== "string") {
+    throw new CfHanaError("QUERY", "JSON Pointer requires a text cell");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new CfHanaError("QUERY", "Saved result cell does not contain valid JSON", {
+      cause: error
+    });
+  }
+  const selected = resolvePointer(parsed, pointer);
+  if (Array.isArray(selected)) {
+    return selected.map(
+      (item, index) => inspectionRow(`${pointer}/${String(index)}`, item, limit)
+    );
+  }
+  if (typeof selected === "object" && selected !== null) {
+    return Object.entries(selected).map(
+      ([key, item]) => inspectionRow(`${pointer}/${escapePointerToken(key)}`, item, limit)
+    );
+  }
+  return [inspectionRow(pointer, selected, limit)];
+}
+function plainTextMatches(text, term, row, column, limit, previewLength) {
+  const matches = [];
+  const lowerText = text.toLowerCase();
+  let offset = lowerText.indexOf(term);
+  while (offset >= 0 && matches.length < limit) {
+    const start = Math.max(0, offset - 32);
+    matches.push({
+      row,
+      column,
+      offset,
+      path: "",
+      preview: textRange(text, start, previewLength).value.replaceAll(/[\r\n\t]/g, " ")
+    });
+    offset = lowerText.indexOf(term, offset + Math.max(1, term.length));
+  }
+  return matches;
+}
+function jsonSearchMatches(root, term, row, column, limit, previewLength) {
+  const matches = [];
+  const stack = [
+    { path: "", value: root }
+  ];
+  while (stack.length > 0 && matches.length < limit) {
+    const entry = stack.pop();
+    if (entry === void 0) {
+      break;
+    }
+    if (typeof entry.value === "object" && entry.value !== null) {
+      const entries = Array.isArray(entry.value) ? entry.value.map((item, index) => [String(index), item]) : Object.entries(entry.value);
+      for (const [key, value] of entries.reverse()) {
+        const path = `${entry.path}/${escapePointerToken(key)}`;
+        if (key.toLowerCase().includes(term)) {
+          matches.push({ row, column, path, preview: jsonValueText(value, previewLength) });
+          if (matches.length >= limit) {
+            break;
+          }
+        }
+        stack.push({ path, value });
+      }
+      continue;
+    }
+    const text = jsonSearchText(entry.value);
+    if (text.toLowerCase().includes(term)) {
+      matches.push({
+        row,
+        column,
+        path: entry.path,
+        preview: previewCell(text, previewLength).text
+      });
+    }
+  }
+  return matches;
+}
+function searchCell(value, term, row, column, limit, previewLength) {
+  if (typeof value !== "string") {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed === "object" && parsed !== null) {
+      return jsonSearchMatches(parsed, term, row, column, limit, previewLength);
+    }
+  } catch {
+  }
+  return plainTextMatches(value, term, row, column, limit, previewLength);
+}
+function searchResultSession(session, searchTerm, options) {
+  assertPositiveInteger("limit", options.limit);
+  const term = searchTerm.trim().toLowerCase();
+  if (term.length === 0) {
+    throw new CfHanaError("CONFIG", "search text must not be empty");
+  }
+  const previewLength = options.previewLength ?? 128;
+  assertPositiveInteger("preview length", previewLength);
+  const rows = options.row === void 0 ? session.result.rows.map((row, index) => ({ row, rowNumber: index + 1 })) : [{ row: selectResultRow(session, options.row), rowNumber: options.row }];
+  const columns = options.column === void 0 ? session.result.columns : [selectResultCell(session, rows[0]?.rowNumber ?? 1, options.column)].map((item) => ({ name: item.column, typeName: item.typeName }));
+  const matches = [];
+  for (const item of rows) {
+    for (const column of columns) {
+      const remaining = options.limit - matches.length;
+      matches.push(
+        ...searchCell(
+          item.row[column.name] ?? null,
+          term,
+          item.rowNumber,
+          column.name,
+          remaining,
+          previewLength
+        )
+      );
+      if (matches.length >= options.limit) {
+        return matches;
+      }
+    }
+  }
+  return matches;
+}
+
+// src/result-store.ts
+import { randomBytes } from "crypto";
+import { mkdir as mkdir3, readFile, readdir as readdir2, rename, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { join as join3 } from "path";
+var RESULT_REF_PATTERN = /^q[0-9a-f]{8}$/;
+var MANIFEST_FILE_NAME = "manifest.json";
+function resultsRoot(saptoolsRoot) {
+  return join3(saptoolsRoot ?? join3(homedir3(), ".saptools"), "cf-hana", "results");
+}
+function sessionDirectory(ref, saptoolsRoot) {
+  return join3(resultsRoot(saptoolsRoot), ref);
+}
+function manifestPath(ref, saptoolsRoot) {
+  return join3(sessionDirectory(ref, saptoolsRoot), MANIFEST_FILE_NAME);
+}
+function encodeCell(value) {
+  if (value === null) {
+    return { kind: "null" };
+  }
+  if (Buffer.isBuffer(value)) {
+    return { kind: "buffer", value: value.toString("base64") };
+  }
+  if (value instanceof Date) {
+    return { kind: "date", value: value.toISOString() };
+  }
+  if (typeof value === "string") {
+    return { kind: "string", value };
+  }
+  if (typeof value === "number") {
+    return { kind: "number", value };
+  }
+  return { kind: "boolean", value };
+}
+function decodeCell(cell) {
+  switch (cell.kind) {
+    case "null":
+      return null;
+    case "buffer":
+      return Buffer.from(cell.value, "base64");
+    case "date":
+      return new Date(cell.value);
+    case "string":
+      return cell.value;
+    case "number":
+      return cell.value;
+    case "boolean":
+      return cell.value;
+  }
+}
+function assertUniqueColumns(columns) {
+  const names = /* @__PURE__ */ new Set();
+  for (const column of columns) {
+    if (names.has(column.name)) {
+      throw new CfHanaError(
+        "CONFIG",
+        `Saved results require unique SQL aliases; duplicate column "${column.name}"`
+      );
+    }
+    names.add(column.name);
+  }
+}
+function encodeResult(result) {
+  assertUniqueColumns(result.columns);
+  return {
+    columns: result.columns,
+    rows: result.rows.map(
+      (row) => result.columns.map((column) => encodeCell(row[column.name] ?? null))
+    ),
+    rowCount: result.rowCount,
+    statement: result.statement,
+    truncated: result.truncated,
+    elapsedMs: result.elapsedMs
+  };
+}
+function decodeResult(result) {
+  const rows = result.rows.map((cells) => {
+    const row = {};
+    let index = 0;
+    for (const column of result.columns) {
+      row[column.name] = decodeCell(cells[index] ?? { kind: "null" });
+      index += 1;
+    }
+    return row;
+  });
+  return { ...result, rows };
+}
+function resolveRef(value) {
+  const ref = value ?? `q${randomBytes(4).toString("hex")}`;
+  if (!RESULT_REF_PATTERN.test(ref)) {
+    throw new CfHanaError("CONFIG", "Invalid saved result ref");
+  }
+  return ref;
+}
+function resolveTtl(value) {
+  const ttl = value ?? DEFAULT_RESULT_TTL_MINUTES;
+  if (!Number.isSafeInteger(ttl) || ttl <= 0) {
+    throw new CfHanaError("CONFIG", "Result TTL must be a positive safe integer");
+  }
+  return ttl;
+}
+function toStoredSession(input, ref, now) {
+  const ttlMinutes = resolveTtl(input.ttlMinutes);
+  return {
+    version: 1,
+    ref,
+    createdAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + ttlMinutes * 6e4).toISOString(),
+    ttlMinutes,
+    info: input.info,
+    result: encodeResult(input.result)
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStoredSession(value) {
+  if (!isRecord(value) || !isRecord(value["result"]) || !isRecord(value["info"])) {
+    return false;
+  }
+  const result = value["result"];
+  return value["version"] === 1 && typeof value["ref"] === "string" && typeof value["createdAt"] === "string" && typeof value["expiresAt"] === "string" && typeof value["ttlMinutes"] === "number" && Array.isArray(result["columns"]) && Array.isArray(result["rows"]);
+}
+async function readStoredSession(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return isStoredSession(parsed) ? parsed : void 0;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    return void 0;
+  }
+}
+function toSession(stored, saptoolsRoot) {
+  return {
+    ...stored,
+    result: decodeResult(stored.result),
+    directory: sessionDirectory(stored.ref, saptoolsRoot),
+    path: manifestPath(stored.ref, saptoolsRoot)
+  };
+}
+async function listSessionRefs(saptoolsRoot) {
+  try {
+    const entries = await readdir2(resultsRoot(saptoolsRoot), { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory() && RESULT_REF_PATTERN.test(entry.name)).map((entry) => entry.name);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+async function createResultSession(input, options = {}) {
+  await pruneResultSessions(options);
+  const ref = resolveRef(options.ref);
+  const stored = toStoredSession(input, ref, options.now?.() ?? /* @__PURE__ */ new Date());
+  const serialized = `${JSON.stringify(stored)}
+`;
+  if (Buffer.byteLength(serialized) > (options.maxBytes ?? MAX_RESULT_STORE_BYTES)) {
+    throw new CfHanaError("CONFIG", "Saved result exceeds the storage limit");
+  }
+  const root = resultsRoot(options.saptoolsRoot);
+  const finalDirectory = sessionDirectory(ref, options.saptoolsRoot);
+  const tempDirectory = `${finalDirectory}.tmp-${process.pid.toString()}`;
+  await mkdir3(root, { recursive: true, mode: 448 });
+  await rm2(tempDirectory, { recursive: true, force: true });
+  await mkdir3(tempDirectory, { mode: 448 });
+  try {
+    await writeFile2(join3(tempDirectory, MANIFEST_FILE_NAME), serialized, {
+      encoding: "utf8",
+      mode: 384
+    });
+    await rename(tempDirectory, finalDirectory);
+  } catch (error) {
+    await rm2(tempDirectory, { recursive: true, force: true });
+    throw error;
+  }
+  return toSession(stored, options.saptoolsRoot);
+}
+async function readResultSession(ref, options = {}) {
+  const resolvedRef = resolveRef(ref);
+  await pruneResultSessions(options);
+  const stored = await readStoredSession(manifestPath(resolvedRef, options.saptoolsRoot));
+  if (stored === void 0) {
+    throw new CfHanaError("QUERY", "Saved result not found or expired");
+  }
+  return toSession(stored, options.saptoolsRoot);
+}
+async function listResultSessions(options = {}) {
+  await pruneResultSessions(options);
+  const refs = await listSessionRefs(options.saptoolsRoot);
+  const stored = await Promise.all(
+    refs.map(async (ref) => await readStoredSession(manifestPath(ref, options.saptoolsRoot)))
+  );
+  return stored.filter((item) => item !== void 0).map((item) => ({
+    ref: item.ref,
+    createdAt: item.createdAt,
+    expiresAt: item.expiresAt,
+    rowCount: item.result.rowCount,
+    columnCount: item.result.columns.length,
+    truncated: item.result.truncated
+  })).sort((left, right) => left.ref.localeCompare(right.ref));
+}
+async function pruneResultSessions(options = {}) {
+  const refs = await listSessionRefs(options.saptoolsRoot);
+  const now = (options.now?.() ?? /* @__PURE__ */ new Date()).getTime();
+  let removed = 0;
+  for (const ref of refs) {
+    const stored = await readStoredSession(manifestPath(ref, options.saptoolsRoot));
+    if (stored === void 0 || Date.parse(stored.expiresAt) <= now) {
+      await rm2(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
+      removed += 1;
+    }
+  }
+  return removed;
+}
+async function clearResultSessions(options = {}) {
+  const refs = await listSessionRefs(options.saptoolsRoot);
+  await Promise.all(
+    refs.map(async (ref) => {
+      await rm2(sessionDirectory(ref, options.saptoolsRoot), { recursive: true, force: true });
+    })
+  );
+  return refs.length;
+}
+
+// src/cli-results.ts
 function print(text) {
   process.stdout.write(`${text}
 `);
 }
+function parseIntOption(value) {
+  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 positive(name, value, fallback) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+    throw new CfHanaError("CONFIG", `${name} must be a positive safe integer`);
+  }
+  return resolved;
+}
+function boundedLength(value) {
+  const resolved = positive("--length", value, DEFAULT_CELL_LIMIT);
+  if (resolved > MAX_CELL_LIMIT) {
+    throw new CfHanaError("CONFIG", `--length must be at most ${String(MAX_CELL_LIMIT)}`);
+  }
+  return resolved;
+}
+function nonNegative(name, value) {
+  const resolved = value ?? 0;
+  if (!Number.isSafeInteger(resolved) || resolved < 0) {
+    throw new CfHanaError("CONFIG", `${name} must be a non-negative safe integer`);
+  }
+  return resolved;
+}
+function resultFromRows(rows, columns) {
+  return {
+    rows,
+    columns,
+    rowCount: rows.length,
+    statement: "select",
+    truncated: false,
+    elapsedMs: 0
+  };
+}
+function csv(rows, columns, limit) {
+  const result = resultFromRows(
+    rows,
+    columns.map((name) => ({ name, typeName: "" }))
+  );
+  return formatCompactCsv(result, limit).text;
+}
+async function runShow(ref, options) {
+  const session = await readResultSession(ref);
+  const length = boundedLength(options.length);
+  if (options.row === void 0) {
+    if (options.column !== void 0 || options.path !== void 0 || options.offset !== void 0) {
+      throw new CfHanaError("CONFIG", "--column, --path, and --offset require --row");
+    }
+    print(summaryCsv(session, length));
+    return;
+  }
+  if (options.column === void 0) {
+    if (options.path !== void 0 || options.offset !== void 0) {
+      throw new CfHanaError("CONFIG", "--path and --offset require --column");
+    }
+    const row = selectResultRow(session, options.row);
+    print(formatCompactCsv(resultFromRows([row], session.result.columns), length).text);
+    return;
+  }
+  const selected = selectResultCell(session, options.row, options.column);
+  if (options.path !== void 0) {
+    const rows = inspectJsonCell(selected.value, options.path, length).map((row) => ({
+      PATH: row.path,
+      TYPE: row.type,
+      VALUE: row.value
+    }));
+    print(csv(rows, ["PATH", "TYPE", "VALUE"], length));
+    return;
+  }
+  const window = readCellWindow(selected.value, nonNegative("--offset", options.offset), length);
+  print(
+    csv(
+      [
+        {
+          ROW: selected.row,
+          COLUMN: selected.column,
+          TYPE: window.type,
+          ORIGINAL_LENGTH: window.originalLength,
+          OFFSET: window.offset,
+          VALUE: window.value
+        }
+      ],
+      ["ROW", "COLUMN", "TYPE", "ORIGINAL_LENGTH", "OFFSET", "VALUE"],
+      length
+    )
+  );
+}
+function summaryCsv(session, length) {
+  const compact = formatCompactCsv(session.result, DEFAULT_CELL_LIMIT);
+  return csv(
+    [
+      {
+        REF: session.ref,
+        ROWS: session.result.rowCount,
+        COLUMNS: session.result.columns.length,
+        ROW_TRUNCATED: session.result.truncated,
+        TRUNCATED_CELLS: compact.truncatedCells,
+        EXPIRES_AT: session.expiresAt
+      }
+    ],
+    ["REF", "ROWS", "COLUMNS", "ROW_TRUNCATED", "TRUNCATED_CELLS", "EXPIRES_AT"],
+    length
+  );
+}
+async function runSearch(ref, text, options) {
+  const session = await readResultSession(ref);
+  const length = boundedLength(options.length);
+  const matches = searchResultSession(session, text, {
+    limit: positive("--limit", options.limit, DEFAULT_RESULT_SEARCH_LIMIT),
+    previewLength: length,
+    ...options.row === void 0 ? {} : { row: options.row },
+    ...options.column === void 0 ? {} : { column: options.column }
+  });
+  const rows = matches.map((match) => ({
+    ROW: match.row,
+    COLUMN: match.column,
+    OFFSET: match.offset ?? null,
+    PATH: match.path,
+    PREVIEW: match.preview
+  }));
+  print(csv(rows, ["ROW", "COLUMN", "OFFSET", "PATH", "PREVIEW"], length));
+}
+function cellExportValue(value) {
+  if (Buffer.isBuffer(value)) {
+    return value;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value === null) {
+    return "";
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return value.toString();
+}
+async function runExport(ref, options) {
+  if (options.row === void 0 || options.column === void 0) {
+    throw new CfHanaError("CONFIG", "result export requires --row and --column");
+  }
+  if (options.output === void 0 || options.output.trim().length === 0) {
+    throw new CfHanaError("CONFIG", "result export requires --output");
+  }
+  const session = await readResultSession(ref);
+  const selected = selectResultCell(session, options.row, options.column);
+  await writeFile3(options.output, cellExportValue(selected.value), { mode: 384 });
+  print(`wrote=${options.output}`);
+}
+async function runList() {
+  const summaries = await listResultSessions();
+  const rows = summaries.map((summary) => ({
+    REF: summary.ref,
+    ROWS: summary.rowCount,
+    COLUMNS: summary.columnCount,
+    ROW_TRUNCATED: summary.truncated,
+    EXPIRES_AT: summary.expiresAt
+  }));
+  print(csv(rows, ["REF", "ROWS", "COLUMNS", "ROW_TRUNCATED", "EXPIRES_AT"], DEFAULT_CELL_LIMIT));
+}
+async function runPrune() {
+  print(`removed=${String(await pruneResultSessions())}`);
+}
+async function runClear() {
+  print(`removed=${String(await clearResultSessions())}`);
+}
+function registerResultCommands(program) {
+  const result = program.command("result").description("inspect saved query refs");
+  result.command("show <ref>").description("show a saved result, row, cell, or JSON path").option("--row <n>", "one-based result row", parseIntOption).option("--column <name>", "exact column name").option("--offset <n>", "text code-point or binary byte offset", parseIntOption).option("--length <n>", "maximum characters or bytes to print", parseIntOption).option("--path <pointer>", "JSON Pointer inside a saved text cell").action(async (ref, _options, command) => {
+    await runShow(ref, command.opts());
+  });
+  result.command("search <ref> <text>").description("search saved text and JSON values").option("--row <n>", "one-based result row", parseIntOption).option("--column <name>", "exact column name").option("--limit <n>", "maximum matches to print", parseIntOption).option("--length <n>", "maximum preview characters", parseIntOption).action(async (ref, text, _options, command) => {
+    await runSearch(ref, text, command.opts());
+  });
+  result.command("export <ref>").description("write one exact saved cell to a file").requiredOption("--output <path>", "output file path").option("--row <n>", "one-based result row", parseIntOption).option("--column <name>", "exact column name").action(async (ref, _options, command) => {
+    await runExport(ref, command.opts());
+  });
+  result.command("list").description("list active saved refs").action(async () => {
+    await runList();
+  });
+  result.command("prune").description("remove expired saved refs").action(async () => {
+    await runPrune();
+  });
+  result.command("clear").description("remove all saved refs").action(async () => {
+    await runClear();
+  });
+}
+
+// src/cli.ts
+function print2(text) {
+  process.stdout.write(`${text}
+`);
+}
 function fail(message) {
   process.stderr.write(`${CLI_NAME}: ${message}
 `);
   process.exit(1);
 }
-function parseIntOption(value) {
+function parseIntOption2(value) {
   const trimmed = value.trim();
   if (!/^-?\d+$/.test(trimmed)) {
     throw new CfHanaError("CONFIG", `Expected an integer but received "${value}"`);
@@ -1749,6 +2559,21 @@ function toConnectOptions(opts) {
     ...opts.timeout === void 0 ? {} : { queryTimeoutMs: opts.timeout, connectTimeoutMs: opts.timeout }
   };
 }
+function resolveCellLimit(value) {
+  const limit = value ?? DEFAULT_CELL_LIMIT;
+  assertPositiveOption("--cell-limit", limit);
+  if (limit > MAX_CELL_LIMIT) {
+    throw new CfHanaError("CONFIG", `--cell-limit must be at most ${String(MAX_CELL_LIMIT)}`);
+  }
+  return limit;
+}
+function assertQueryOptions(sql, opts) {
+  resolveCellLimit(opts.cellLimit);
+  assertPositiveOption("--result-ttl-minutes", opts.resultTtlMinutes);
+  if (opts.save && classifyStatement(sql) !== "select") {
+    throw new CfHanaError("CONFIG", "--save is only available for SELECT/WITH statements");
+  }
+}
 function rowsToResult(rows) {
   const first = rows[0];
   const columns = first === void 0 ? [] : Object.keys(first).map((name) => ({ name, typeName: "" }));
@@ -1773,10 +2598,19 @@ function formatInfo(info) {
   ].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");
+  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");
+}
+function withFormattedConnectionOptions(command) {
+  return withConnectionOptions(command).option(
+    "--format <format>",
+    "output format: table, json, or csv",
+    "table"
+  );
 }
 async function runQuery(selector, sql, command) {
   const opts = command.opts();
+  assertQueryOptions(sql, opts);
+  const cellLimit = resolveCellLimit(opts.cellLimit);
   const client = await connect(selector, toConnectOptions(opts));
   try {
     const params = opts.param ?? [];
@@ -1786,7 +2620,32 @@ async function runQuery(selector, sql, command) {
 `);
     }
     const result = await client.query(sql, params);
-    print(formatResult(result, parseFormat(opts.format)));
+    if (result.statement === "select") {
+      const compact = formatCompactCsv(result, cellLimit);
+      if (opts.save) {
+        const session = await createResultSession({
+          result,
+          info: client.info,
+          ...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) {
+        process.stderr.write(`${CLI_NAME}: row limit reached; rerun with --limit for more rows
+`);
+      }
+      if (compact.truncatedCells > 0) {
+        process.stderr.write(
+          `${CLI_NAME}: compacted ${String(compact.truncatedCells)} cell(s); use --save to inspect exact values by ref
+`
+        );
+      }
+      return;
+    }
+    print2(formatTable(result));
   } finally {
     await client.close();
   }
@@ -1801,7 +2660,7 @@ async function runTables(selector, schema, command) {
       TABLE: table.name,
       TYPE: table.type
     }));
-    print(formatResult(rowsToResult(rows), parseFormat(opts.format)));
+    print2(formatResult(rowsToResult(rows), parseFormat(opts.format)));
   } finally {
     await client.close();
   }
@@ -1819,7 +2678,7 @@ async function runColumns(selector, target, command) {
       NULLABLE: column.nullable,
       POSITION: column.position
     }));
-    print(formatResult(rowsToResult(rows), parseFormat(opts.format)));
+    print2(formatResult(rowsToResult(rows), parseFormat(opts.format)));
   } finally {
     await client.close();
   }
@@ -1830,7 +2689,7 @@ async function runCount(selector, target, command) {
   const client = await connect(selector, toConnectOptions(opts));
   try {
     const total = await client.count({ schema, table });
-    print(String(total));
+    print2(String(total));
   } finally {
     await client.close();
   }
@@ -1841,7 +2700,7 @@ async function runPing(selector, command) {
   try {
     const started = Date.now();
     await client.query("SELECT 1 FROM DUMMY");
-    print(
+    print2(
       `OK  ${client.info.host}  schema=${client.info.schema}  ${String(Date.now() - started)}ms`
     );
   } finally {
@@ -1852,7 +2711,7 @@ async function runInfo(selector, command) {
   const opts = command.opts();
   const client = await connect(selector, toConnectOptions(opts));
   try {
-    print(formatInfo(client.info));
+    print2(formatInfo(client.info));
   } finally {
     await client.close();
   }
@@ -1861,18 +2720,22 @@ 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, [])
+    program.command("query <selector> <sql>").description("run a single SQL statement").option("--param <value>", "bind a SQL parameter (repeatable)", collectParam, []).option("--save", "save exact returned rows for follow-up inspection", false).option("--cell-limit <n>", "maximum visible characters per data cell", parseIntOption2).option(
+      "--result-ttl-minutes <n>",
+      "minutes before a saved result expires",
+      parseIntOption2
+    )
   ).action(async (selector, sql, _options, command) => {
     await runQuery(selector, sql, command);
   });
-  withConnectionOptions(
+  withFormattedConnectionOptions(
     program.command("tables <selector> [schema]").description("list tables in a schema")
   ).action(
     async (selector, schema, _options, command) => {
       await runTables(selector, schema, command);
     }
   );
-  withConnectionOptions(
+  withFormattedConnectionOptions(
     program.command("columns <selector> <schema.table>").description("list the columns of a table")
   ).action(async (selector, target, _options, command) => {
     await runColumns(selector, target, command);
@@ -1892,6 +2755,7 @@ function buildProgram() {
   ).action(async (selector, _options, command) => {
     await runInfo(selector, command);
   });
+  registerResultCommands(program);
   return program;
 }
 try {