botversion-sdk 2.2.3 → 2.3.1

package/undo/lib/snapshot-store.js

@@ -0,0 +1,265 @@
+// lib/snapshot-store.js
+"use strict";
+// SNAPSHOT STORE (Phase 2) - shared by every database hook (pg, Prisma, later others).
+// Saves the encrypted before/after rows of an AI write into the host's own snapshot table.
+//
+// The hook gives this file a function  run(sql, params) -> Promise<{ rows }>  that talks to the host's
+// database on the SAME connection as the host's write. This file never opens a connection of its own.
+// Postgres SQL only for now (other databases come in Phase 5).
+// Logs contain table names, counts and error codes only - never row values or SQL text.
+
+const crypto = require("crypto");
+const log = require("./log");
+const snapshotCrypto = require("./snapshot-crypto");
+
+const TABLE = "botversion_undo_snapshots";
+const ROW_LIMIT = 500; // more rows than this in one write = not capturable
+const WINDOW_MINUTES = 30; // how long a snapshot stays usable
+const CLEANUP_EVERY_MS = 60000; // expired rows are deleted at most once a minute
+
+const INSERT_COLS = `INSERT INTO ${TABLE} (id, action_id, seq, table_name, operation, primary_key, before_data, after_data, is_linked, requester_hash, status, expires_at) `;
+
+// One set of SQL texts per database type. Callers that pass no dialect get Postgres (the old behavior).
+const DIALECTS = {
+  postgres: {
+    name: "postgres",
+    insertSql:
+      INSERT_COLS +
+      `VALUES ($1::uuid, $2, $3, $4, $5, $6, $7, $8, $9, $10, 'captured', now() + interval '${WINDOW_MINUTES} minutes')`,
+    // ::text because Prisma's raw queries cannot read the regclass type.
+    existsSql: "SELECT to_regclass($1::text)::text AS t",
+    cleanupSql: `DELETE FROM ${TABLE} WHERE expires_at < now()`,
+    afterSql: `UPDATE ${TABLE} SET after_data = $1 WHERE id = $2::uuid`,
+    deleteIds: (ids) => ({
+      sql: `DELETE FROM ${TABLE} WHERE id = ANY($1::uuid[])`,
+      params: [ids],
+    }),
+  },
+  mysql: {
+    name: "mysql",
+    // UTC_TIMESTAMP so the expiry does not depend on the connection's time zone.
+    insertSql:
+      INSERT_COLS +
+      `VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'captured', DATE_ADD(UTC_TIMESTAMP(3), INTERVAL ${WINDOW_MINUTES} MINUTE))`,
+    existsSql:
+      "SELECT table_name AS t FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ? LIMIT 1",
+    cleanupSql: `DELETE FROM ${TABLE} WHERE expires_at < UTC_TIMESTAMP(3)`,
+    afterSql: `UPDATE ${TABLE} SET after_data = ? WHERE id = ?`,
+    deleteIds: (ids) => ({
+      sql: `DELETE FROM ${TABLE} WHERE id IN (${ids.map(() => "?").join(", ")})`,
+      params: ids.slice(),
+    }),
+  },
+  sqlite: {
+    name: "sqlite",
+    // Times are saved as ISO text, so text comparison sorts them correctly.
+    insertSql:
+      INSERT_COLS +
+      `VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'captured', strftime('%Y-%m-%dT%H:%M:%fZ','now','+${WINDOW_MINUTES} minutes'))`,
+    existsSql:
+      "SELECT name AS t FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1",
+    cleanupSql: `DELETE FROM ${TABLE} WHERE expires_at < strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
+    afterSql: `UPDATE ${TABLE} SET after_data = ? WHERE id = ?`,
+    deleteIds: (ids) => ({
+      sql: `DELETE FROM ${TABLE} WHERE id IN (${ids.map(() => "?").join(", ")})`,
+      params: ids.slice(),
+    }),
+  },
+  sqlserver: {
+    name: "sqlserver",
+    // SYSUTCDATETIME so the expiry does not depend on the server's time zone. Prisma numbers its SQL Server placeholders @P1, @P2...
+    insertSql:
+      INSERT_COLS +
+      `VALUES (@P1, @P2, @P3, @P4, @P5, @P6, @P7, @P8, @P9, @P10, 'captured', DATEADD(MINUTE, ${WINDOW_MINUTES}, SYSUTCDATETIME()))`,
+    existsSql:
+      "SELECT TOP 1 table_name AS t FROM information_schema.tables WHERE table_name = @P1",
+    cleanupSql: `DELETE FROM ${TABLE} WHERE expires_at < SYSUTCDATETIME()`,
+    afterSql: `UPDATE ${TABLE} SET after_data = @P1 WHERE id = @P2`,
+    deleteIds: (ids) => ({
+      sql: `DELETE FROM ${TABLE} WHERE id IN (${ids.map((_, i) => "@P" + (i + 1)).join(", ")})`,
+      params: ids.slice(),
+    }),
+  },
+};
+
+// No dialect given = Postgres. An unknown name is a bug in the caller, so it throws.
+function sqlFor(dialect) {
+  const d = DIALECTS[dialect || "postgres"];
+  if (!d) throw new Error("unknown database dialect");
+  return d;
+}
+
+// SQL + parameters that remove snapshot rows by id (used when a half-saved set must be discarded).
+function deleteByIds(ids, dialect) {
+  return sqlFor(dialect).deleteIds(ids);
+}
+
+const tableReady = {}; // per dialect, so two database types in one app do not mix up
+let lastCleanup = 0;
+const warned = new Set();
+
+function warnOnce(key, message) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  log.warn(message);
+}
+
+// Our own table is never captured (otherwise saving a snapshot would create a snapshot of itself).
+function isOwnTable(name) {
+  if (typeof name !== "string") return false;
+  const last = name
+    .split(".")
+    .pop()
+    .replace(/["`\[\]]/g, "");
+  return last.toLowerCase() === TABLE;
+}
+
+// info = { rowCount, primaryKeyColumns }. Tells a hook whether a write may be captured, before it reads anything.
+function checkCapturable(info) {
+  let r = { ok: true };
+  if (!snapshotCrypto.hasKey()) r = { ok: false, reason: "no-encryption-key" };
+  else {
+    const pk = info && info.primaryKeyColumns;
+    if (!Array.isArray(pk) || pk.length === 0)
+      r = { ok: false, reason: "no-primary-key" };
+    else if (!(info.rowCount <= ROW_LIMIT))
+      r = { ok: false, reason: "too-many-rows" };
+  }
+  return r;
+}
+
+// Order number of a write inside one AI action (1, 2, 3...). Undo reverses them last to first.
+function nextSeq(store) {
+  store.seq = (store.seq || 0) + 1;
+  return store.seq;
+}
+
+// If the host's write is inside a transaction, one failed statement of ours would break the host's whole
+// transaction. A savepoint lets us undo only our own statements. Outside a transaction it is not needed.
+async function guarded(run, inTransaction, work) {
+  if (!inTransaction) return work();
+  await run("SAVEPOINT botversion_undo", []);
+  try {
+    const result = await work();
+    await run("RELEASE SAVEPOINT botversion_undo", []);
+    return result;
+  } catch (e) {
+    try {
+      await run("ROLLBACK TO SAVEPOINT botversion_undo", []);
+    } catch (_) {
+      /* nothing more we can do */
+    }
+    throw e;
+  }
+}
+
+// Does the snapshot table exist? (a SELECT that does not fail when it is missing, so it cannot break a transaction)
+async function ensureTable(run, dialect) {
+  const d = sqlFor(dialect);
+  if (tableReady[d.name]) return { ok: true };
+  const found = await run(d.existsSql, [TABLE]);
+  if (found && found.rows && found.rows[0] && found.rows[0].t) {
+    tableReady[d.name] = true;
+    return { ok: true };
+  }
+  warnOnce(
+    "missing",
+    `Undo setup problem: the table "${TABLE}" was not found. Run the snapshot table command (dashboard, guide, or the startup message). Until then AI writes cannot be undone.`,
+  );
+  return { ok: false, reason: "table-missing" };
+}
+
+// Deletes expired snapshots, at most once a minute. A failure is reported to the caller (never ignored silently).
+async function cleanupExpired(run, dialect) {
+  if (Date.now() - lastCleanup < CLEANUP_EVERY_MS) return;
+  await run(sqlFor(dialect).cleanupSql, []);
+  lastCleanup = Date.now();
+}
+
+// Saves one snapshot row.
+// entry = { table, operation: 'insert'|'update'|'delete', primaryKey: {col: value}, before: row|null, after: row|null, isLinked }
+// Returns { ok: true, id, seq } or { ok: false, reason }. Never throws.
+async function saveSnapshot(run, store, entry, opts) {
+  const inTransaction = !!(opts && opts.inTransaction);
+  try {
+    if (!store || !store.actionId) return { ok: false, reason: "no-action" };
+    if (isOwnTable(entry.table)) return { ok: false, reason: "own-table" };
+    if (!snapshotCrypto.hasKey())
+      return { ok: false, reason: "no-encryption-key" };
+
+    const id = crypto.randomUUID();
+    let seq = 0;
+    const params = [
+      id,
+      store.actionId,
+      0, // the order number is filled in just before saving, so a failed attempt leaves no gap
+
+      String(entry.table),
+      String(entry.operation),
+      snapshotCrypto.encrypt(entry.primaryKey),
+      entry.before == null ? null : snapshotCrypto.encrypt(entry.before),
+      entry.after == null ? null : snapshotCrypto.encrypt(entry.after),
+      !!entry.isLinked,
+      store.requesterHash || null,
+    ];
+
+    const result = await guarded(run, inTransaction, async () => {
+      // Prisma's helper carries its own database type (run.dialect); other hooks pass it in opts.
+      const dialect = (opts && opts.dialect) || run.dialect;
+      const ready = await ensureTable(run, dialect);
+      if (!ready.ok) return ready;
+      await cleanupExpired(run, dialect);
+      seq = nextSeq(store);
+      params[2] = seq;
+      await run(sqlFor(dialect).insertSql, params);
+      return { ok: true };
+    });
+    if (!result.ok) {
+      return result;
+    }
+    (store.savedIds || (store.savedIds = [])).push(id); // remembered so a visual run can roll back only this request
+    return { ok: true, id, seq };
+  } catch (e) {
+    warnOnce(
+      "save-failed",
+      `Undo setup problem: a snapshot could not be saved (database error code ${(e && e.code) || "unknown"}). Check the snapshot table and that the login can INSERT, SELECT, UPDATE and DELETE on it.`,
+    );
+    return { ok: false, reason: "save-failed" };
+  }
+}
+
+// Adds the after-state (the rows as they are after the write) to a snapshot saved earlier.
+// Returns { ok: true } or { ok: false, reason }. Never throws.
+async function saveAfter(run, id, after, opts) {
+  const inTransaction = !!(opts && opts.inTransaction);
+  try {
+    const encrypted = snapshotCrypto.encrypt(after);
+    await guarded(run, inTransaction, () =>
+      run(sqlFor((opts && opts.dialect) || run.dialect).afterSql, [
+        encrypted,
+        id,
+      ]),
+    );
+    return { ok: true };
+  } catch (e) {
+    warnOnce(
+      "after-failed",
+      `Undo setup problem: the after-state of a snapshot could not be saved (database error code ${(e && e.code) || "unknown"}).`,
+    );
+    return { ok: false, reason: "save-failed" };
+  }
+}
+
+module.exports = {
+  TABLE,
+  ROW_LIMIT,
+  WINDOW_MINUTES,
+  isOwnTable,
+  checkCapturable,
+  nextSeq,
+  saveSnapshot,
+  saveAfter,
+  guarded,
+  sqlFor,
+  deleteByIds,
+};

package/undo/lib/sql-classify-mssql.js

@@ -0,0 +1,230 @@
+// lib/sql-classify-mssql.js
+"use strict";
+// Decides: is this SQL Server (T-SQL) statement a write, what kind, which tables?
+// Uses a real SQL parser (never hand-written text matching).
+// Only the statement SHAPE is returned - never SQL text or values.
+
+let parser = null;
+try {
+  const { Parser } = require("node-sql-parser");
+  parser = new Parser();
+} catch (_) {
+  /* parser missing: nothing is readable */
+}
+
+const OPTS = { database: "TransactSQL" };
+const cache = new Map();
+const CACHE_MAX = 200;
+
+function tableName(t) {
+  if (!t || !t.table) return null;
+  return t.db ? t.db + "." + t.table : t.table;
+}
+
+// True if a nested SELECT appears anywhere inside this part of the tree.
+function containsSubquery(node) {
+  if (!node || typeof node !== "object") return false;
+  if (node.type === "select" || node.ast) return true;
+  for (const key of Object.keys(node)) {
+    if (containsSubquery(node[key])) return true;
+  }
+  return false;
+}
+
+const asList = (x) => (Array.isArray(x) ? x : x ? [x] : []);
+
+function describe(ast, out) {
+  const notes = [];
+  switch (ast.type) {
+    case "insert":
+      if (ast.values && ast.values.type === "select")
+        notes.push("insert-from-select");
+      out.push({
+        kind: "insert",
+        tables: asList(ast.table).map(tableName),
+        notes,
+      });
+      break;
+    case "update": {
+      const tables = asList(ast.table).map(tableName);
+      if (tables.length > 1 || asList(ast.from).length)
+        notes.push("multi-table");
+      if (containsSubquery(ast.where) || containsSubquery(ast.set))
+        notes.push("has-subquery");
+      if (!ast.where) notes.push("no-where");
+      out.push({ kind: "update", tables, notes });
+      break;
+    }
+    case "delete": {
+      const fromList = asList(ast.from);
+      const tables = fromList.map(tableName);
+      // The parser copies the FROM table into `table` (tagged addition); that copy is not a second table.
+      const extra = asList(ast.table).filter(
+        (t) =>
+          !(
+            t &&
+            t.addition === true &&
+            fromList.some((f) => f && f.table === t.table)
+          ),
+      );
+      if (tables.length > 1 || extra.length > 0) notes.push("multi-table");
+      if (containsSubquery(ast.where)) notes.push("has-subquery");
+      if (!ast.where) notes.push("no-where");
+      out.push({ kind: "delete", tables, notes });
+      break;
+    }
+    case "merge": // MERGE = insert, update and delete in one
+      out.push({ kind: "merge", tables: [], notes: ["merge"] });
+      break;
+    case "truncate":
+      out.push({
+        kind: "truncate",
+        tables: asList(ast.name).map(tableName),
+        notes: [],
+      });
+      break;
+    case "drop":
+      out.push({
+        kind: "drop",
+        tables: asList(ast.name).map(tableName),
+        notes: [],
+      });
+      break;
+    case "alter":
+      out.push({
+        kind: "alter",
+        tables: asList(ast.table).map(tableName),
+        notes: [],
+      });
+      break;
+    case "exec": // stored procedure: its writes cannot be seen
+    case "call":
+      out.push({ kind: "call", tables: [], notes: ["stored-procedure"] });
+      break;
+    default:
+      break; // select, set, declare, begin, commit... are not writes
+  }
+}
+
+// T-SQL's OUTPUT clause is not understood by the parser. It only changes what a statement RETURNS, not which rows it
+// writes, so it is removed for READING only; the host's own statement is always sent to the database unchanged.
+function stripOutputClause(sql) {
+  if (typeof sql !== "string" || !/\boutput\b/i.test(sql)) return sql;
+  const END_WORDS = new Set(["VALUES", "SELECT", "DEFAULT", "WHERE", "FROM"]);
+  const n = sql.length;
+  let i = 0;
+  let depth = 0;
+  let start = -1;
+  while (i < n) {
+    const ch = sql[i];
+    if (ch === "'" || ch === '"' || ch === "[") {
+      // skip quoted text and bracketed names ('' and ]] are escaped quotes)
+      const close = ch === "[" ? "]" : ch;
+      i++;
+      while (i < n) {
+        if (sql[i] === close) {
+          if (sql[i + 1] === close) {
+            i += 2;
+            continue;
+          }
+          break;
+        }
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "-" && sql[i + 1] === "-") {
+      while (i < n && sql[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && sql[i + 1] === "*") {
+      const e = sql.indexOf("*/", i + 2);
+      i = e === -1 ? n : e + 2;
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      i++;
+      continue;
+    }
+    if (ch === ")") {
+      depth--;
+      i++;
+      continue;
+    }
+    if (/[A-Za-z_@#]/.test(ch)) {
+      let j = i;
+      while (j < n && /[A-Za-z0-9_@#$]/.test(sql[j])) j++;
+      const word = sql.slice(i, j).toUpperCase();
+      if (depth === 0) {
+        if (start === -1 && word === "OUTPUT") start = i;
+        else if (start !== -1 && END_WORDS.has(word))
+          return sql.slice(0, start) + sql.slice(i);
+      }
+      i = j;
+      continue;
+    }
+    i++;
+  }
+  return start === -1 ? sql : sql.slice(0, start);
+}
+
+// First letters of the statement only (e.g. "INSERT"). Safe for logs.
+function wordOf(sql) {
+  const m = /^\s*([A-Za-z]{1,10})/.exec(sql || "");
+  return m ? m[1].toUpperCase() : "?";
+}
+
+// Returns { writes: [...], parseFailed: bool, firstWord: string, multi: bool }
+function classifyMssql(sql) {
+  if (cache.has(sql)) return cache.get(sql);
+  let result;
+  if (!parser) {
+    result = {
+      writes: [],
+      parseFailed: true,
+      firstWord: wordOf(sql),
+      multi: false,
+    };
+  } else {
+    try {
+      const parsed = parser.astify(stripOutputClause(sql), OPTS);
+      const list = Array.isArray(parsed) ? parsed : [parsed];
+      const writes = [];
+      for (const ast of list) if (ast) describe(ast, writes);
+      result = {
+        writes,
+        parseFailed: false,
+        firstWord: "",
+        multi: list.length > 1,
+      };
+    } catch (_) {
+      result = {
+        writes: [],
+        parseFailed: true,
+        firstWord: wordOf(sql),
+        multi: false,
+      };
+    }
+  }
+  if (cache.size >= CACHE_MAX) cache.clear();
+  cache.set(sql, result);
+  return result;
+}
+
+// Writes the SDK refuses to capture. Used only for log labels.
+function wouldBeNonCapturableMssql(w) {
+  return (
+    ["truncate", "drop", "alter", "merge", "call"].includes(w.kind) ||
+    w.notes.some((n) =>
+      ["insert-from-select", "has-subquery", "multi-table"].includes(n),
+    )
+  );
+}
+
+module.exports = {
+  classifyMssql,
+  wouldBeNonCapturableMssql,
+  stripOutputClause,
+};

package/undo/lib/sql-classify-mysql.js

@@ -0,0 +1,167 @@
+// lib/sql-classify-mysql.js
+"use strict";
+// Decides: is this MySQL statement a write, what kind, which tables?
+// Uses a real SQL parser (never hand-written text matching).
+// Only the statement SHAPE is returned - never SQL text or values.
+
+let parser = null;
+try {
+  const { Parser } = require("node-sql-parser");
+  parser = new Parser();
+} catch (_) {
+  /* parser missing: nothing is readable */
+}
+
+const OPTS = { database: "MySQL" };
+const cache = new Map();
+const CACHE_MAX = 200;
+
+function tableName(t) {
+  if (!t || !t.table) return null;
+  return t.db ? t.db + "." + t.table : t.table;
+}
+
+// True if a nested SELECT appears anywhere inside this part of the tree.
+function containsSubquery(node) {
+  if (!node || typeof node !== "object") return false;
+  if (node.type === "select" || node.ast) return true;
+  for (const key of Object.keys(node)) {
+    if (containsSubquery(node[key])) return true;
+  }
+  return false;
+}
+
+const asList = (x) => (Array.isArray(x) ? x : x ? [x] : []);
+
+function describe(ast, out) {
+  const notes = [];
+  switch (ast.type) {
+    case "insert":
+      if (ast.values && ast.values.type === "select")
+        notes.push("insert-from-select");
+      if (ast.on_duplicate_update) notes.push("upsert");
+      out.push({
+        kind: "insert",
+        tables: asList(ast.table).map(tableName),
+        notes,
+      });
+      break;
+    case "replace": // REPLACE INTO = delete + insert in one
+      out.push({
+        kind: "replace",
+        tables: asList(ast.table).map(tableName),
+        notes: ["replace"],
+      });
+      break;
+    case "update": {
+      const tables = asList(ast.table).map(tableName);
+      if (tables.length > 1) notes.push("multi-table");
+      if (containsSubquery(ast.where) || containsSubquery(ast.set))
+        notes.push("has-subquery");
+      if (!ast.where) notes.push("no-where");
+      out.push({ kind: "update", tables, notes });
+      break;
+    }
+    case "delete": {
+      const fromList = asList(ast.from);
+      const tables = fromList.map(tableName);
+      // The parser copies the FROM table into `table` (tagged addition); that copy is not a second table.
+      const extra = asList(ast.table).filter(
+        (t) =>
+          !(
+            t &&
+            t.addition === true &&
+            fromList.some((f) => f && f.table === t.table)
+          ),
+      );
+      if (tables.length > 1 || extra.length > 0) notes.push("multi-table");
+      if (containsSubquery(ast.where)) notes.push("has-subquery");
+      if (!ast.where) notes.push("no-where");
+      out.push({ kind: "delete", tables, notes });
+      break;
+    }
+    case "truncate":
+      out.push({
+        kind: "truncate",
+        tables: asList(ast.name).map(tableName),
+        notes: [],
+      });
+      break;
+    case "drop":
+      out.push({
+        kind: "drop",
+        tables: asList(ast.name).map(tableName),
+        notes: [],
+      });
+      break;
+    case "alter":
+      out.push({
+        kind: "alter",
+        tables: asList(ast.table).map(tableName),
+        notes: [],
+      });
+      break;
+    case "call": // stored procedure: its writes cannot be seen
+      out.push({ kind: "call", tables: [], notes: ["stored-procedure"] });
+      break;
+    default:
+      break; // select, set, begin, commit... are not writes
+  }
+}
+
+// First letters of the statement only (e.g. "INSERT"). Safe for logs.
+function wordOf(sql) {
+  const m = /^\s*([A-Za-z]{1,10})/.exec(sql || "");
+  return m ? m[1].toUpperCase() : "?";
+}
+
+// Returns { writes: [...], parseFailed: bool, firstWord: string, multi: bool }
+function classifyMysql(sql) {
+  if (cache.has(sql)) return cache.get(sql);
+  let result;
+  if (!parser) {
+    result = {
+      writes: [],
+      parseFailed: true,
+      firstWord: wordOf(sql),
+      multi: false,
+    };
+  } else {
+    try {
+      const parsed = parser.astify(sql, OPTS);
+      const list = Array.isArray(parsed) ? parsed : [parsed];
+      const writes = [];
+      for (const ast of list) if (ast) describe(ast, writes);
+      result = {
+        writes,
+        parseFailed: false,
+        firstWord: "",
+        multi: list.length > 1,
+      };
+    } catch (_) {
+      result = {
+        writes: [],
+        parseFailed: true,
+        firstWord: wordOf(sql),
+        multi: false,
+      };
+    }
+  }
+  if (cache.size >= CACHE_MAX) cache.clear();
+  cache.set(sql, result);
+  return result;
+}
+
+// Writes the final SDK would refuse to capture. Used only for log labels here.
+function wouldBeNonCapturableMysql(w) {
+  return (
+    ["truncate", "drop", "alter", "replace", "call"].includes(w.kind) ||
+    w.notes.some((n) =>
+      ["upsert", "insert-from-select", "has-subquery", "multi-table"].includes(
+        n,
+      ),
+    )
+  );
+}
+
+module.exports = { classifyMysql, wouldBeNonCapturableMysql };