botversion-sdk 2.2.3 → 2.3.1

package/undo/lib/gate.js

@@ -0,0 +1,164 @@
+// lib/gate.js
+"use strict";
+// CONFIRM GATE (Phase 4): stops a write that cannot be saved, rolls back the earlier writes of the
+// same action, and answers the browser with "needs confirmation". Logs: reasons and counts only.
+
+const log = require("./log");
+const guard = require("./capture-guard");
+const undoPrisma = require("./undo-prisma");
+const undoPg = require("./undo-pg");
+const undoMysql = require("./undo-mysql");
+const undoMongo = require("./undo-mongo");
+const undoSqlite = require("./undo-sqlite");
+const undoMssql = require("./undo-mssql");
+
+const { Refuse } = undoPrisma;
+
+class Blocked extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BotVersionBlocked";
+    this.code = "BOTVERSION_NEEDS_CONFIRM";
+  }
+}
+
+// Undoes everything saved so far for this action and removes those snapshot rows.
+async function rollbackAction(st) {
+  const opts = { discard: true };
+  // Visual runs roll back only what THIS request saved; earlier steps are still on screen and stay undoable.
+  if (st.visual) {
+    opts.onlyIds = (st.savedIds || []).slice();
+    if (!opts.onlyIds.length) return { undone: 0 };
+  }
+  // Try each database in turn; move on when this one says "not mine" (unsupported), "no client here" (no-client) or "nothing saved here" (not-found, another database may hold it).
+  let unsupported = null;
+  let notFound = null;
+  let last = null;
+  for (const u of [
+    undoPrisma,
+    undoPg,
+    undoMysql,
+    undoMongo,
+    undoSqlite,
+    undoMssql,
+  ]) {
+    try {
+      return await u.undoAction(st.actionId, st.requesterHash, opts);
+    } catch (e) {
+      const next =
+        e instanceof Refuse &&
+        (e.code === "unsupported" ||
+          e.code === "no-client" ||
+          e.code === "not-found");
+      if (!next) throw e;
+      if (e.code === "unsupported" && !unsupported) unsupported = e;
+      if (e.code === "not-found" && !notFound) notFound = e;
+      last = e;
+    }
+  }
+  throw unsupported || notFound || last;
+}
+
+// Answers the browser request itself, then silences the host so it cannot answer a second time.
+function reply(st, info) {
+  const res = st.res;
+  if (!res || res.headersSent || res.writableEnded) return;
+  const body = JSON.stringify({
+    botversionNeedsConfirm: true,
+    actionId: st.actionId,
+    reason: info.why,
+    where: info.where,
+    rolledBack: info.rolledBack,
+    undone: info.undone,
+    visual: !!st.visual,
+    message: st.visual
+      ? "This step changes data in a way that cannot be undone once it runs. Confirm to continue."
+      : info.rolledBack
+        ? "This change cannot be undone once it runs. Earlier steps of this action were rolled back. Confirm to run the whole action again."
+        : "This change cannot be undone once it runs, and earlier steps of this action could not be rolled back automatically.",
+  });
+  try {
+    res.statusCode = 409;
+    res.removeHeader("Content-Length");
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.setHeader("Cache-Control", "no-store");
+    res.end(body);
+    const self = () => res;
+    res.writeHead = self;
+    res.setHeader = self;
+    res.removeHeader = self;
+    res.flushHeaders = self;
+    res.write = () => true;
+    res.end = self;
+  } catch (_) {
+    /* never break the host */
+  }
+}
+
+// Always throws Blocked (so the host's write does not run).
+async function block(st, where, why) {
+  try {
+    if (!st.blocked) {
+      const info = {
+        where: String(where || "?"),
+        why: String(why || "unknown"),
+        rolledBack: false,
+        undone: 0,
+      };
+      st.blocked = info;
+      try {
+        const r = await guard.runUnhooked(() => rollbackAction(st));
+        info.rolledBack = true;
+        info.undone = r.undone;
+      } catch (e) {
+        // not-found = nothing earlier was saved, so there is nothing to roll back
+        if (e instanceof Refuse && e.code === "not-found")
+          info.rolledBack = true;
+      }
+      reply(st, info);
+    }
+  } catch (_) {
+    /* never break the host */
+  }
+  throw new Blocked("BotVersion: this change needs the user's confirmation");
+}
+
+// Same as block(), but answers at once. Used by better-sqlite3, which cannot wait for promises.
+// Only better-sqlite3 writes can be rolled back this way; writes made earlier in other databases are reported as not rolled back.
+// Always throws Blocked (so the host's write does not run).
+function blockSync(st, where, why) {
+  try {
+    if (!st.blocked) {
+      const info = {
+        where: String(where || "?"),
+        why: String(why || "unknown"),
+        rolledBack: false,
+        undone: 0,
+      };
+      st.blocked = info;
+      try {
+        const r = guard.runUnhooked(() =>
+          st.visual && !(st.savedIds || []).length
+            ? { undone: 0 }
+            : undoSqlite.rollbackSync(
+                st.actionId,
+                st.requesterHash,
+                st.visual ? { onlyIds: st.savedIds.slice() } : undefined,
+              ),
+        );
+        info.rolledBack = true;
+        info.undone = r.undone;
+      } catch (e) {
+        // not-found = nothing earlier was saved, so there is nothing to roll back
+        if (e instanceof Refuse && e.code === "not-found")
+          info.rolledBack = true;
+      }
+      reply(st, info);
+    }
+  } catch (_) {
+    /* never break the host */
+  }
+  throw new Blocked("BotVersion: this change needs the user's confirmation");
+}
+
+module.exports = { block, blockSync, Blocked };

package/undo/lib/hooks/better-sqlite3.js

@@ -0,0 +1,198 @@
+// lib/hooks/better-sqlite3.js
+"use strict";
+// DATABASE HOOK: better-sqlite3.
+// Covers Knex, Drizzle, TypeORM, Sequelize (and anything else) running on better-sqlite3, because they all call its Statement methods.
+//
+// better-sqlite3 answers at once (no promises), so the hook answers at once too (see capture-sqlite.js).
+// How it gets in without the host changing anything:
+//  1. It patches Database.prototype of the host's own copy of the package right now, and watches Node's module loader
+//     for any other copy loaded later.
+//  2. Its Statement class is not exported, so it is patched the first time a statement is prepared
+//     (the statement's own prototype is the Statement class).
+// Normal (untagged) requests are never touched.
+
+const path = require("path");
+const log = require("../log");
+const loader = require("../loader-watch");
+const tagger = require("../tagger");
+const guard = require("../capture-guard");
+const capture = require("../capture-sqlite");
+const undoSqlite = require("../undo-sqlite");
+const S = require("../sqlite-sql");
+
+const MARK = Symbol.for("botversion.undoExp.betterSqlitePatched");
+const attachedCopies = [];
+
+function looksLikeBetterSqlite(exp) {
+  return !!(
+    typeof exp === "function" &&
+    exp.prototype &&
+    typeof exp.prototype.prepare === "function" &&
+    typeof exp.prototype.exec === "function" &&
+    typeof exp.prototype.transaction === "function" &&
+    typeof exp.prototype.pragma === "function"
+  );
+}
+
+// Counts the query for the request summary. Must never throw.
+function count() {
+  const st = tagger.getCurrent();
+  if (st && !guard.isUnhooked()) st.queries++;
+}
+
+function patchExports(exp, where) {
+  if (!looksLikeBetterSqlite(exp)) return false;
+  const proto = exp.prototype;
+  if (proto.prepare[MARK]) return false; // already patched
+
+  const origPrepare = proto.prepare;
+  const origExec = proto.exec;
+  const stmtOrig = {}; // the Statement class's own run / get / all, filled in when it is patched
+  const patchedProtos = new WeakSet();
+  const boundArgs = new WeakMap(); // statement -> values given to stmt.bind(...)
+  const opsCache = new WeakMap();
+
+  const callOriginal = (name, stmt, params) =>
+    (stmtOrig[name] || stmt[name]).apply(stmt, params);
+
+  // How capture and Undo talk to this database without being seen by the hook again.
+  const opsFor = (db) => {
+    let o = opsCache.get(db);
+    if (!o) {
+      o = {
+        kind: "better",
+        isOpen: () => db.open !== false,
+        query(sql, params) {
+          const s = db.prepare(sql);
+          const p = S.cleanParams(params);
+          if (s.reader) return { rows: callOriginal("all", s, p) };
+          const r = callOriginal("run", s, p);
+          return {
+            rows: [],
+            changes: r.changes,
+            lastInsertRowid: r.lastInsertRowid,
+          };
+        },
+        script(sql) {
+          guard.runUnhooked(() => origExec.call(db, sql));
+        },
+      };
+      opsCache.set(db, o);
+    }
+    undoSqlite.remember(db, o); // Undo reuses the host's own database object
+    return o;
+  };
+  const ctx = { opsFor, boundOf: (s) => boundArgs.get(s) };
+
+  const patchStatement = (sp) => {
+    if (!sp || patchedProtos.has(sp)) return;
+    patchedProtos.add(sp);
+    try {
+      for (const name of ["run", "get", "all"]) {
+        const original = sp[name];
+        if (typeof original !== "function") continue;
+        stmtOrig[name] = original;
+        sp[name] = function () {
+          try {
+            count();
+          } catch (_) {
+            /* observation problems must never affect the host */
+          }
+          // Tagged write: capture saves the snapshot, then runs the host's call itself.
+          // This may throw only the host's own error or Blocked (the confirm gate).
+          const handled = capture.captureBetter(
+            this,
+            name,
+            arguments,
+            original,
+            ctx,
+          );
+          if (handled) return handled.value;
+          return original.apply(this, arguments);
+        };
+      }
+      const origIterate = sp.iterate;
+      if (typeof origIterate === "function") {
+        sp.iterate = function () {
+          try {
+            count();
+          } catch (_) {
+            /* never break the host */
+          }
+          capture.refuseWriteBetter(
+            this,
+            "iterate",
+            this.source,
+            arguments.length
+              ? Array.prototype.slice.call(arguments)
+              : boundArgs.get(this) || [],
+            ctx,
+          );
+          return origIterate.apply(this, arguments);
+        };
+      }
+      const origBind = sp.bind;
+      if (typeof origBind === "function") {
+        sp.bind = function () {
+          try {
+            boundArgs.set(this, Array.prototype.slice.call(arguments));
+          } catch (_) {
+            /* never break the host */
+          }
+          return origBind.apply(this, arguments);
+        };
+      }
+    } catch (e) {}
+  };
+
+  const wrappedPrepare = function prepare() {
+    const stmt = origPrepare.apply(this, arguments);
+    try {
+      if (stmt && typeof stmt === "object")
+        patchStatement(Object.getPrototypeOf(stmt));
+    } catch (_) {
+      /* never break the host */
+    }
+    return stmt;
+  };
+  Object.defineProperty(wrappedPrepare, MARK, { value: true });
+  proto.prepare = wrappedPrepare;
+
+  proto.exec = function exec(sql) {
+    try {
+      count();
+    } catch (_) {
+      /* never break the host */
+    }
+    capture.refuseWriteBetter(this, "exec", sql, [], ctx);
+    return origExec.apply(this, arguments);
+  };
+
+  attachedCopies.push(where || "unknown location");
+  return true;
+}
+
+// hostRoot = folder of the host project (found by the scanner).
+function attach(hostRoot) {
+  // 1. The host's own copy, if it can be found right now.
+  try {
+    const resolved = require.resolve("better-sqlite3", {
+      paths: [hostRoot, process.cwd()],
+    });
+    patchExports(require(resolved), path.dirname(resolved));
+  } catch (_) {
+    // Not installed or not loadable: fine, other databases may be in use.
+  }
+  // 2. Any other copy that loads later.
+  loader.onLoad(
+    (request) =>
+      request === "better-sqlite3" ||
+      /[\\/]better-sqlite3[\\/]lib[\\/]index\.js$/.test(request),
+    (exp, request, parent) => {
+      patchExports(exp, loader.whereOf(request, parent));
+    },
+  );
+  return attachedCopies.slice();
+}
+
+module.exports = { attach, attachedCopies };

package/undo/lib/hooks/mongodb.js

@@ -0,0 +1,124 @@
+// lib/hooks/mongodb.js
+"use strict";
+// DATABASE HOOK: MongoDB driver (`mongodb`).
+// Covers Mongoose too, because Mongoose runs on top of the same driver's Collection class.
+//
+// Same approach as the pg and mysql2 hooks:
+//  1. It patches the shared Collection prototype of the host's own copy of the driver right now.
+//  2. It also watches Node's module loader, so any OTHER copy of the driver loaded later gets patched when it loads.
+//
+// Logs writes of AI-tagged requests, and for tagged writes saves a snapshot first (see capture-mongo.js).
+// Normal (untagged) requests are never touched. Reads are not hooked at all.
+
+const path = require("path");
+const log = require("../log");
+const loader = require("../loader-watch");
+const tagger = require("../tagger");
+const guard = require("../capture-guard");
+const store = require("../snapshot-store");
+const mstore = require("../snapshot-store-mongo");
+const capture = require("../capture-mongo");
+
+const MARK = Symbol.for("botversion.undoExp.mongodbPatched");
+const attachedCopies = [];
+
+function looksLikeMongodb(exp) {
+  return !!(
+    exp &&
+    typeof exp.MongoClient === "function" &&
+    exp.Collection &&
+    exp.Collection.prototype &&
+    typeof exp.Collection.prototype.insertOne === "function" &&
+    typeof exp.Collection.prototype.updateOne === "function"
+  );
+}
+
+// The driver's own EJSON helper (turns documents into exact text and back). Newer drivers export it; older ones keep it in their `bson` package.
+function findEJSON(exp, where) {
+  try {
+    if (exp.BSON && exp.BSON.EJSON) return exp.BSON.EJSON;
+  } catch (_) {
+    /* try the next place */
+  }
+  try {
+    if (exp.EJSON) return exp.EJSON;
+  } catch (_) {
+    /* try the next place */
+  }
+  try {
+    const p = require.resolve("bson", { paths: [where, process.cwd()] });
+    const b = require(p);
+    if (b && b.EJSON) return b.EJSON;
+  } catch (_) {
+    /* not found */
+  }
+  return null;
+}
+
+// Called for every hooked write. Must never throw and never alter anything.
+// Note: only writes are hooked, so the "queries seen" count of a request counts writes only.
+function observe(method, col) {
+  if (guard.isUnhooked()) return;
+  const st = tagger.getCurrent();
+  if (!st) return; // normal (untagged) request: do nothing at all
+  if (store.isOwnTable(col && col.collectionName)) return;
+  st.queries++;
+  st.writes++;
+}
+
+function patchExports(exp, where) {
+  if (!looksLikeMongodb(exp)) return false;
+  const proto = exp.Collection.prototype;
+  let patched = false;
+  for (const method of capture.HOOKED_METHODS) {
+    const original = proto[method];
+    if (typeof original !== "function" || original[MARK]) continue;
+    const wrapped = function () {
+      try {
+        observe(method, this);
+      } catch (_) {
+        /* observation problems must never affect the host's write */
+      }
+      try {
+        // Tagged write: capture saves the snapshot, then runs the host's write itself.
+        const handled = capture.maybeCapture(this, method, arguments, original);
+        if (handled) return handled.value;
+      } catch (_) {
+        /* capture problems must never affect the host's write */
+      }
+      return original.apply(this, arguments);
+    };
+    Object.defineProperty(wrapped, MARK, { value: true });
+    proto[method] = wrapped;
+    patched = true;
+  }
+  if (!patched) return false;
+  mstore.setEJSON(findEJSON(exp, where));
+  attachedCopies.push(where || "unknown location");
+  return true;
+}
+
+// hostRoot = folder of the host project (found by the scanner).
+function attach(hostRoot) {
+  // 1. The host's own copy of the driver, if it can be found right now.
+  try {
+    const resolved = require.resolve("mongodb", {
+      paths: [hostRoot, process.cwd()],
+    });
+    patchExports(require(resolved), path.dirname(resolved));
+  } catch (_) {
+    // Not installed: fine, other databases may be in use.
+  }
+  // 2. Any other copy of the driver that loads later (nested copies, for example inside Mongoose).
+  loader.onLoad(
+    (request) =>
+      request === "mongodb" ||
+      /[\\/]mongodb[\\/]lib[\\/]index\.js$/.test(request),
+    (exp, request, parent) => {
+      patchExports(exp, loader.whereOf(request, parent));
+    },
+  );
+  return attachedCopies.slice();
+}
+
+module.exports = { attach, attachedCopies };

package/undo/lib/hooks/mssql.js

@@ -0,0 +1,209 @@
+// lib/hooks/mssql.js
+"use strict";
+// DATABASE HOOK: SQL Server driver (`tedious`).
+// Covers the `mssql` package, Knex, Sequelize and TypeORM running on SQL Server, because they all call tedious.
+//
+// Logs writes of AI-tagged requests, and for tagged UPDATE / INSERT / DELETE saves a snapshot first (see capture-mssql.js).
+// Stored procedures, prepared statements and bulk loads cannot be saved, so a tagged one is blocked until the user confirms.
+// Normal (untagged) requests are never touched.
+
+const path = require("path");
+const log = require("../log");
+const loader = require("../loader-watch");
+const tagger = require("../tagger");
+const guard = require("../capture-guard");
+const capture = require("../capture-mssql");
+const undoMssql = require("../undo-mssql");
+const {
+  classifyMssql,
+  wouldBeNonCapturableMssql,
+} = require("../sql-classify-mssql");
+
+const MARK = Symbol.for("botversion.undoExp.tediousPatched");
+const attachedCopies = [];
+
+function looksLikeTedious(exp) {
+  return !!(
+    exp &&
+    exp.Request &&
+    exp.TYPES &&
+    exp.Connection &&
+    exp.Connection.prototype &&
+    typeof exp.Connection.prototype.execSql === "function" &&
+    typeof exp.Connection.prototype.execSqlBatch === "function" &&
+    typeof exp.Connection.prototype.callProcedure === "function"
+  );
+}
+
+// Capture only works while the connection is idle. If tedious reports another state, the host's call is passed
+// through untouched so the host sees tedious's own answer. If the state cannot be read, capture goes ahead.
+function isIdle(conn) {
+  const n = conn && conn.state && conn.state.name;
+  return typeof n !== "string" || n === "LoggedIn";
+}
+
+// Called for every query on a patched tedious. Must never throw and never alter anything.
+function observe(method, request) {
+  if (guard.isUnhooked()) return;
+  const store = tagger.getCurrent();
+  if (!store) return; // normal (untagged) request: do nothing at all
+
+  store.queries++;
+
+  if (method === "callProcedure") {
+    store.writes++;
+    return;
+  }
+
+  const text =
+    request && typeof request.sqlTextOrProcedure === "string"
+      ? request.sqlTextOrProcedure
+      : null;
+  if (text === null) {
+    return;
+  }
+
+  const paramCount = Array.isArray(request.parameters)
+    ? request.parameters.length
+    : 0;
+  const result = classifyMssql(text);
+
+  if (result.parseFailed) {
+    return;
+  }
+  for (const w of result.writes) {
+    store.writes++;
+    const tables = w.tables.filter(Boolean).join(", ") || "?";
+    const notes = w.notes.length ? "  notes=" + w.notes.join(",") : "";
+  }
+}
+
+function patchExports(exp, where) {
+  if (!looksLikeTedious(exp)) return false;
+  const proto = exp.Connection.prototype;
+  if (proto.execSql[MARK]) return false; // already patched
+
+  const origSql = proto.execSql;
+  const origBatch = proto.execSqlBatch;
+  const origProc = proto.callProcedure;
+  const origExecute = proto.execute; // prepared statements (may not exist in very old versions)
+  const origBulk = proto.execBulkLoad; // bulk loads (may not exist in very old versions)
+
+  // The loaded copy of tedious plus its ORIGINAL execSql / execSqlBatch, so our own reads are never seen by the hook.
+  const copy = { exp, fns: { sql: origSql, batch: origBatch } };
+
+  const seen = new WeakSet(); // connections already handed to Undo
+  const remember = (conn) => {
+    if (!conn || typeof conn !== "object" || seen.has(conn)) return;
+    seen.add(conn);
+    undoMssql.remember(conn, copy); // Undo reuses an idle connection of the host's own
+  };
+
+  // execSql / execSqlBatch: tagged UPDATE/INSERT/DELETE are captured, other writes that cannot be saved are blocked.
+  const wrapQuery = (method, original) => {
+    const wrapped = function (request) {
+      try {
+        observe(method, request);
+      } catch (_) {
+        /* observation problems must never affect the host's query */
+      }
+      try {
+        remember(this);
+      } catch (_) {
+        /* never break the host */
+      }
+      try {
+        // capture runs the host's request itself (or blocks it) and returns true
+        if (isIdle(this) && capture.maybeCapture(this, request, original, copy))
+          return;
+      } catch (_) {
+        /* capture problems must never affect the host's query */
+      }
+      return original.apply(this, arguments);
+    };
+    Object.defineProperty(wrapped, MARK, { value: true });
+    proto[method] = wrapped;
+  };
+  wrapQuery("execSql", origSql);
+  wrapQuery("execSqlBatch", origBatch);
+
+  // Stored procedures and prepared statements: their writes cannot be saved, so a tagged one is blocked until confirmed.
+  const wrapRefuse = (method, original, kind) => {
+    if (typeof original !== "function") return;
+    proto[method] = function (request) {
+      try {
+        observe(method, request);
+      } catch (_) {
+        /* never break the host */
+      }
+      try {
+        remember(this);
+      } catch (_) {
+        /* never break the host */
+      }
+      try {
+        if (isIdle(this) && capture.maybeRefuse(this, request, original, kind))
+          return;
+      } catch (_) {
+        /* never break the host */
+      }
+      return original.apply(this, arguments);
+    };
+  };
+  wrapRefuse("callProcedure", origProc, "procedure");
+  wrapRefuse("execute", origExecute, "prepared");
+
+  // Bulk loads: always a write that cannot be saved.
+  if (typeof origBulk === "function") {
+    proto.execBulkLoad = function (bulk) {
+      try {
+        const st = tagger.getCurrent();
+        if (st && !guard.isUnhooked()) {
+          st.queries++;
+          st.writes++;
+        }
+      } catch (_) {
+        /* never break the host */
+      }
+      try {
+        remember(this);
+      } catch (_) {
+        /* never break the host */
+      }
+      try {
+        if (capture.refuseBulk(bulk)) return;
+      } catch (_) {
+        /* never break the host */
+      }
+      return origBulk.apply(this, arguments);
+    };
+  }
+
+  attachedCopies.push(where || "unknown location");
+  return true;
+}
+
+// hostRoot = folder of the host project (found by the scanner).
+function attach(hostRoot) {
+  // 1. The host's own copy of tedious, if it can be found right now.
+  try {
+    const resolved = require.resolve("tedious", {
+      paths: [hostRoot, process.cwd()],
+    });
+    patchExports(require(resolved), path.dirname(resolved));
+  } catch (_) {
+    // Not installed or not loadable: fine, other databases may be in use.
+  }
+  // 2. Any other copy of tedious that loads later (for example one nested inside the mssql package).
+  loader.onLoad(
+    (request) =>
+      request === "tedious" ||
+      /[\\/]tedious[\\/]lib[\\/]tedious\.js$/.test(request),
+    (exp, request, parent) => {
+      patchExports(exp, loader.whereOf(request, parent));
+    },
+  );
+  return attachedCopies.slice();
+}
+
+module.exports = { attach, attachedCopies };