botversion-sdk 2.2.3 → 2.3.1

package/scanner-sdk/scan/text-utils.js

@@ -0,0 +1,517 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scan/text-utils.js
+// PURPOSE: Small shared helpers for reading code text (strings, brackets, comments, path params). No framework logic here.
+// CONTAINS: collectStringConstants, resolveRouteTemplate, blankOutComments, joinMountPath, extractPathParams, buildParamSchema, buildRouteParamMap, removePathParamFields, sliceCallText, regexpToPath, MAX_STATIC_LITERAL_LENGTH, skipStaticString, findStaticClosingBrace, splitStaticEntries
+// USED BY: scanner.js (extractPathParams); scan/field-extractors.js, scan/response-shape.js, scan/express.js, scan/express-files.js, scan/express-static.js, scan/nextjs.js, scan/fastify.js, scan/nestjs.js, scan/koa.js, scan/hapi.js, scan/adonis.js, scan/nuxt.js, scan/sveltekit.js, scan/remix.js
+// DEPENDS ON: (nothing, only Node built-ins)
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+// Code of a handler that is imported from another file, e.g. router.post("/x", receiveWebhook)
+// with: const { receiveWebhook } = require("./controllers/webhookController")
+function importedHandlerCode(content, callText, filePath, opts) {
+  if (!callText) return "";
+  const fs = require("fs");
+  const path = require("path");
+  // Loaded here, not at the top of the file, to avoid a circular import with field-extractors
+  const { findNamedHandlerCode } = require("./field-extractors");
+  const args =
+    splitStaticEntries(
+      callText.slice(callText.indexOf("(") + 1, callText.length - 1),
+    ) || [];
+  let code = "";
+
+  function bindingFor(local) {
+    const safe = local.replace(/\$/g, "\\$");
+    for (const m of content.matchAll(
+      /(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(\s*['"]([^'"]+)['"]\s*\)/g,
+    )) {
+      for (const piece of m[1].split(",")) {
+        const parts = piece.trim().split(":");
+        const imported = parts[0].trim();
+        const localName = (parts[1] || parts[0]).split("=")[0].trim();
+        if (localName === local && imported)
+          return { rel: m[2], imported: imported };
+      }
+    }
+    for (const m of content.matchAll(
+      /import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g,
+    )) {
+      for (const piece of m[1].split(",")) {
+        const parts = piece.trim().split(/\s+as\s+/);
+        const imported = parts[0].trim();
+        const localName = (parts[1] || parts[0]).trim();
+        if (localName === local && imported)
+          return { rel: m[2], imported: imported };
+      }
+    }
+    const whole = new RegExp(
+      "(?:const|let|var)\\s+" +
+        safe +
+        "\\s*=\\s*require\\(\\s*['\"]([^'\"]+)['\"]\\s*\\)(?:\\.([A-Za-z_$][\\w$]*))?",
+    ).exec(content);
+    if (whole) return { rel: whole[1], imported: whole[2] || null };
+    const dflt = new RegExp(
+      "import\\s+" + safe + "\\s+from\\s*['\"]([^'\"]+)['\"]",
+    ).exec(content);
+    if (dflt) return { rel: dflt[1], imported: null };
+    return null;
+  }
+
+  function readTarget(rel) {
+    if (!/^\.{1,2}([\\/]|$)/.test(rel)) return null;
+    const base = path.resolve(path.dirname(filePath), rel);
+    const tries = [
+      base,
+      base + ".js",
+      base + ".ts",
+      path.join(base, "index.js"),
+      path.join(base, "index.ts"),
+    ];
+    for (const t of tries) {
+      try {
+        if (fs.statSync(t).isFile())
+          return blankOutComments(fs.readFileSync(t, "utf8"));
+      } catch (e) {}
+    }
+    return null;
+  }
+
+  args.forEach(function (arg) {
+    const wrapped = /^[\w$.]+\s*\(\s*([\s\S]+?)\s*\)$/.exec(arg);
+    const ref = /^([A-Za-z_$][\w$]*)(?:\s*\.\s*([A-Za-z_$][\w$]*))?$/.exec(
+      wrapped ? wrapped[1] : arg,
+    );
+    if (!ref) return;
+    const binding = bindingFor(ref[1]);
+    if (!binding) return;
+    const handlerName = ref[2] || binding.imported;
+    if (!handlerName) return;
+    const target = readTarget(binding.rel);
+    if (!target) return;
+    // "exports.name = ..." is read like "const name = ..."
+    const readable = target.replace(
+      new RegExp(
+        "(?:module\\.)?exports\\." +
+          handlerName.replace(/\$/g, "\\$") +
+          "\\s*=",
+        "g",
+      ),
+      "\nconst " + handlerName + " =",
+    );
+    const found = findNamedHandlerCode(readable, handlerName);
+    if (found) code += "\n" + found;
+    // whole file text, so helpers the handler calls can be read too
+    if (found && opts && opts.sources) opts.sources.push(readable);
+  });
+  return code;
+}
+
+// Returns the text of the file a name is imported from (comments blanked), or null when it is not
+// imported from a readable relative file
+function readImportedFile(content, localName, filePath) {
+  const fs = require("fs");
+  const path = require("path");
+  let rel = null;
+  for (const m of content.matchAll(
+    /import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g,
+  )) {
+    for (const piece of m[1].split(",")) {
+      const parts = piece.trim().split(/\s+as\s+/);
+      if ((parts[1] || parts[0]).trim() === localName) rel = m[2];
+    }
+  }
+  if (!rel) {
+    for (const m of content.matchAll(
+      /(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(\s*['"]([^'"]+)['"]\s*\)/g,
+    )) {
+      for (const piece of m[1].split(",")) {
+        const parts = piece.trim().split(":");
+        if ((parts[1] || parts[0]).split("=")[0].trim() === localName)
+          rel = m[2];
+      }
+    }
+  }
+  // a whole-module import (const x = require("./x") / import x from "./x") points at the file too
+  if (!rel) {
+    const safeLocal = String(localName).replace(/\$/g, "\\$");
+    const whole = new RegExp(
+      "(?:const|let|var)\\s+" +
+        safeLocal +
+        "\\s*=\\s*require\\(\\s*['\"]([^'\"]+)['\"]\\s*\\)",
+    ).exec(content);
+    const dflt = new RegExp(
+      "import\\s+" + safeLocal + "\\s+from\\s*['\"]([^'\"]+)['\"]",
+    ).exec(content);
+    if (whole) rel = whole[1];
+    else if (dflt) rel = dflt[1];
+  }
+  if (!rel || !/^\.{1,2}([\\/]|$)/.test(rel)) return null;
+  const base = path.resolve(path.dirname(filePath), rel);
+  const tries = [
+    base,
+    base + ".js",
+    base + ".ts",
+    path.join(base, "index.js"),
+    path.join(base, "index.ts"),
+  ];
+  for (const t of tries) {
+    try {
+      if (fs.statSync(t).isFile())
+        return blankOutComments(fs.readFileSync(t, "utf8"));
+    } catch (e) {}
+  }
+  return null;
+}
+
+// Reads simple string constants (const BASE = "/x") so paths written with them can be resolved
+function collectStringConstants(content) {
+  const consts = {};
+  for (const m of content.matchAll(
+    /(?:^|\n)(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(['"`])([^'"`$]*)\2/g,
+  )) {
+    consts[m[1]] = m[3];
+  }
+  for (const m of content.matchAll(
+    /(?:^|\n)(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*`([^`]*)`/g,
+  )) {
+    const value = resolveRouteTemplate(m[2], consts);
+    if (value !== null) consts[m[1]] = value;
+  }
+  return consts;
+}
+
+// Fills in ${NAME} parts of a path using known constants; returns null if any part cannot be known
+function resolveRouteTemplate(text, consts) {
+  let unresolved = false;
+  const out = String(text).replace(
+    /\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g,
+    function (all, name) {
+      if (Object.prototype.hasOwnProperty.call(consts, name))
+        return consts[name];
+      unresolved = true;
+      return all;
+    },
+  );
+  return unresolved ? null : out;
+}
+
+// Replaces comments with spaces (same length) so commented-out routes are never read as real ones
+function blankOutComments(text) {
+  const out = text.split("");
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (ch === "/" && next === "/") {
+      while (i < text.length && text[i] !== "\n") {
+        out[i] = " ";
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      const end = text.indexOf("*/", i + 2);
+      const stop = end === -1 ? text.length : end + 2;
+      for (; i < stop; i++) {
+        if (text[i] !== "\n") out[i] = " ";
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const close = skipStaticString(text, i, text.length);
+      i = close === -1 ? i + 1 : close + 1;
+      continue;
+    }
+    i++;
+  }
+  return out.join("");
+}
+
+// Joins a mount prefix and a route path: ("/api/projects", "/") -> "/api/projects"
+function joinMountPath(prefix, routePath) {
+  var rp = String(routePath || "");
+  if (rp && rp.charAt(0) !== "/") rp = "/" + rp;
+  var p = String(prefix || "") + (rp === "/" ? "" : rp);
+  p = p.replace(/\/{2,}/g, "/");
+  if (p.length > 1) p = p.replace(/\/$/, "");
+  return p || "/";
+}
+
+/**
+ * Extract :param names from a path like /users/:id/posts/:postId
+ */
+function extractPathParams(routePath) {
+  const params = [];
+  // catch-all ":...slug" has the param name "slug"
+  const matches = routePath.match(/:(?:\.\.\.)?([a-zA-Z_][a-zA-Z0-9_]*)/g);
+  if (matches) {
+    matches.forEach(function (m) {
+      params.push(m.replace(/^:(?:\.\.\.)?/, ""));
+    });
+  }
+  return params;
+}
+
+/**
+ * Build a simple schema object from param names
+ */
+function buildParamSchema(params) {
+  const schema = {};
+  params.forEach(function (p) {
+    schema[p] = "string";
+  });
+  return schema;
+}
+
+function buildRouteParamMap(routePath, segments) {
+  const paramMap = {};
+  const parts = routePath.split("/").filter(Boolean);
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+
+    // Skip catch-all [...slug] and optional [[...slug]]
+    if (/^\[?\[\.\.\./.test(part)) continue;
+
+    // Check if this segment is a dynamic param
+    // Handles both Next.js style [id] and Express style :id
+    const nextParamMatch = part.match(/^\[([^\]]+)\]$/);
+    // an optional param (:format?) is still a param
+    const expressParamMatch = part.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)\??$/);
+    const paramMatch = nextParamMatch || expressParamMatch;
+    if (!paramMatch) continue;
+
+    const paramName = paramMatch[1];
+
+    // If param already has a descriptive name like [projectId], use it as-is
+    if (paramName !== "id" && paramName !== "slug" && paramName !== "param") {
+      paramMap[paramName] = paramName;
+      continue;
+    }
+
+    // If param is just [id], look at the parent folder name to figure out type
+    // e.g. projects/[id] → projectId
+    const parentSegment = parts[i - 1];
+    if (parentSegment) {
+      // Remove any dynamic brackets from parent if it's also a param
+      const cleanParent = parentSegment.replace(/^\[([^\]]+)\]$/, "$1");
+      // Singularize simple plural names: projects → project, users → user
+      const singular = cleanParent.replace(/ies$/, "y").replace(/s$/, "");
+      paramMap[paramName] = singular + "Id";
+    } else {
+      // No parent segment, just call it "id"
+      paramMap[paramName] = "id";
+    }
+  }
+
+  return paramMap;
+}
+
+// Drops fields that are really path params (Next.js Pages puts [id] into req.query too)
+function removePathParamFields(schema, routePath) {
+  if (!schema || !schema.properties) return null;
+  const pathParams = new Set(extractPathParams(routePath));
+  const properties = {};
+  Object.keys(schema.properties).forEach(function (k) {
+    if (!pathParams.has(k)) properties[k] = schema.properties[k];
+  });
+  return Object.keys(properties).length > 0
+    ? { type: "object", properties }
+    : null;
+}
+
+// Returns one route's call text, from its start to the matching closing ")" (null if it cannot be matched safely)
+function sliceCallText(content, startIndex) {
+  const open = content.indexOf("(", startIndex);
+  if (open === -1) return null;
+  const limit = Math.min(content.length, open + 20000);
+  let depth = 0;
+  for (let i = open; i < limit; i++) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (ch === "/" && next === "/") {
+      const nl = content.indexOf("\n", i);
+      if (nl === -1) return null;
+      i = nl;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      const end = content.indexOf("*/", i + 2);
+      if (end === -1) return null;
+      i = end + 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      i = skipStaticString(content, i, limit);
+      if (i === -1) return null;
+      continue;
+    }
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") {
+      depth--;
+      if (depth === 0) return content.slice(startIndex, i + 1);
+      if (depth < 0) return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Convert Express regexp back to a mount path string
+ * Used for nested routers (app.use('/api', router))
+ */
+function regexpToPath(regexp, keys) {
+  if (!regexp) return "";
+
+  // Express 4.x stores the original path string directly
+  if (regexp.source === "^\\/?(?=\\/|$)") return "";
+
+  try {
+    var src = regexp.source;
+
+    // Remove anchors and cleanup
+    src = src
+      .replace(/^\^/, "")
+      .replace(/\\\//g, "/")
+      .replace(/\/\?\(\?=\/\|\$\)$/, "")
+      .replace(/\/\?\$?$/, "")
+      .replace(/\(\?:\(\[\^\/\]\+\?\)\)/g, function (_, i) {
+        return keys && keys[i] ? ":" + keys[i].name : ":param";
+      });
+
+    // Clean up any remaining regex artifacts
+    src = src.replace(/\(\?:/g, "").replace(/\)/g, "");
+
+    if (!src || src === "/") return "";
+    if (!src.startsWith("/")) src = "/" + src;
+
+    return src;
+  } catch (e) {
+    return "";
+  }
+}
+
+const MAX_STATIC_LITERAL_LENGTH = 6000;
+
+// Returns the index of the closing quote of the string starting at "start" (-1 if not found)
+function skipStaticString(text, start, limit) {
+  const quote = text[start];
+  for (let i = start + 1; i < limit; i++) {
+    const ch = text[i];
+    if (ch === "\\") {
+      i++;
+      continue;
+    }
+    if (ch === quote) return i;
+    if (quote === "`" && ch === "$" && text[i + 1] === "{") {
+      let depth = 1;
+      i += 2;
+      for (; i < limit && depth > 0; i++) {
+        const c = text[i];
+        if (c === '"' || c === "'" || c === "`") {
+          i = skipStaticString(text, i, limit);
+          if (i === -1) return -1;
+          continue;
+        }
+        if (c === "{") depth++;
+        else if (c === "}") depth--;
+      }
+      i--;
+      continue;
+    }
+    if (quote !== "`" && ch === "\n") return -1;
+  }
+  return -1;
+}
+
+// Returns the index of the "}" that closes the "{" at openIndex (null if it cannot be matched safely)
+function findStaticClosingBrace(text, openIndex) {
+  let depth = 0;
+  const limit = Math.min(text.length, openIndex + MAX_STATIC_LITERAL_LENGTH);
+  for (let i = openIndex; i < limit; i++) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (ch === "/" && next === "/") {
+      const nl = text.indexOf("\n", i);
+      if (nl === -1) return null;
+      i = nl;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      const end = text.indexOf("*/", i + 2);
+      if (end === -1) return null;
+      i = end + 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      i = skipStaticString(text, i, limit);
+      if (i === -1) return null;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(") depth++;
+    else if (ch === "}" || ch === "]" || ch === ")") {
+      depth--;
+      if (depth === 0) return ch === "}" ? i : null;
+      if (depth < 0) return null;
+    }
+  }
+  return null;
+}
+
+// Splits the inside of an object literal on top-level commas (comments removed)
+function splitStaticEntries(inner) {
+  const entries = [];
+  let current = "";
+  let depth = 0;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    const next = inner[i + 1];
+    if (ch === "/" && next === "/") {
+      const nl = inner.indexOf("\n", i);
+      if (nl === -1) break;
+      i = nl;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      const end = inner.indexOf("*/", i + 2);
+      if (end === -1) break;
+      i = end + 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const end = skipStaticString(inner, i, inner.length);
+      if (end === -1) return null;
+      current += inner.slice(i, end + 1);
+      i = end;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(") depth++;
+    else if (ch === "}" || ch === "]" || ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      entries.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) entries.push(current.trim());
+  return entries;
+}
+
+module.exports = {
+  importedHandlerCode,
+  readImportedFile,
+  collectStringConstants,
+  resolveRouteTemplate,
+  blankOutComments,
+  joinMountPath,
+  extractPathParams,
+  buildRouteParamMap,
+  removePathParamFields,
+  sliceCallText,
+  regexpToPath,
+  skipStaticString,
+  findStaticClosingBrace,
+  splitStaticEntries,
+};

package/scanner-sdk/scanner.js

@@ -0,0 +1,52 @@
+// ─────────────────────────────────────────────────────────────
+// FILE: scanner.js
+// PURPOSE: Entry point. Pulls every scanner together and exports the same functions as before.
+// Each framework lives in its own file inside the scan/ folder:
+//   scan/text-utils.js - Small shared helpers for reading code text (strings, brackets, comments, path params). No framework logic here.
+//   scan/route-segments.js - Cuts a file into per-route and per-method pieces, and detects which HTTP methods a file handles.
+//   scan/field-extractors.js - Finds request fields (body, query, file uploads) in handler code and guesses their types.
+//   scan/response-shape.js - Best-effort guessing of response shapes from replies written out in code, e.g. res.json({ id, name }).
+//   scan/express.js - Main Express scan: reads the live Express app, then adds routes found by reading files.
+//   scan/express-files.js - Express helpers: finds the Express files in a project, works out mount prefixes, builds the handler-name -> body-fields map.
+//   scan/express-static.js - Reads Express routes written in files (including .route() chains, constant paths and arrays of paths).
+//   scan/nextjs.js - Finds Next.js API routes (pages/api and app/api).
+//   scan/frontend.js - Finds frontend page routes (Next, Remix, SvelteKit, Nuxt, Astro, React Router, Vue Router, Angular, TanStack).
+//   scan/fastify.js - Finds API routes in Fastify projects.
+//   scan/nestjs.js - Finds API routes in NestJS projects (@Controller, @Get, @Post ...).
+//   scan/koa.js - Finds API routes in Koa projects (router.get/post/...).
+//   scan/hapi.js - Finds API routes in Hapi projects (server.route({...})).
+//   scan/adonis.js - Finds API routes in AdonisJS projects (Route.get / router.post ...).
+//   scan/nuxt.js - Finds Nuxt server API routes (server/api file-based routing).
+//   scan/sveltekit.js - Finds SvelteKit server routes (+server.js / +server.ts).
+//   scan/remix.js - Finds Remix server routes (loader = GET, action = POST/PUT/DELETE/PATCH).
+// ─────────────────────────────────────────────────────────────
+"use strict";
+
+const { scanExpressRoutes } = require("./scan/express");
+const { scanNextJsRoutes, scanNextJsAppRoutes } = require("./scan/nextjs");
+const { extractPathParams } = require("./scan/text-utils");
+const { scanFrontendRoutes } = require("./scan/frontend");
+const { scanFastifyRoutes } = require("./scan/fastify");
+const { scanNestJsRoutes } = require("./scan/nestjs");
+const { scanKoaRoutes } = require("./scan/koa");
+const { scanHapiRoutes } = require("./scan/hapi");
+const { scanAdonisRoutes } = require("./scan/adonis");
+const { scanNuxtServerRoutes } = require("./scan/nuxt");
+const { scanSvelteKitServerRoutes } = require("./scan/sveltekit");
+const { scanRemixServerRoutes } = require("./scan/remix");
+
+module.exports = {
+  scanExpressRoutes,
+  scanNextJsRoutes,
+  scanNextJsAppRoutes,
+  extractPathParams,
+  scanFrontendRoutes,
+  scanFastifyRoutes,
+  scanNestJsRoutes,
+  scanKoaRoutes,
+  scanHapiRoutes,
+  scanAdonisRoutes,
+  scanNuxtServerRoutes,
+  scanSvelteKitServerRoutes,
+  scanRemixServerRoutes,
+};

package/undo/bin/scan.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// bin/scan.js
+"use strict";
+// Command:  npx botversion-undo-exp
+// Prints the same environment report as startup, without starting the app.
+// Run it from the host project's folder.
+
+const scanner = require("../lib/scanner");
+const { printReport } = require("../lib/report");
+const schemaReader = require("../lib/schema-reader");
+
+// "setup" runs the optional setup check instead of the report.
+if (process.argv[2] === "setup") {
+  require("../lib/setup-check").run();
+  return;
+}
+
+const scan = scanner.scan();
+// Structure only (never row data). No hooks are attached in this command, so loading Prisma here is safe.
+scan.structure = scan.prisma
+  ? schemaReader.readPrismaStructure(scan.hostRoot)
+  : { ok: false, noSchemaFile: true };
+printReport(scan, null);

package/undo/index.js

@@ -0,0 +1,104 @@
+// index.js
+"use strict";
+// botversion-undo-experiment
+//
+// Host usage - the same 2-line shape as the real SDK:
+//
+//   const undoExperiment = require('botversion-undo-experiment');
+//   undoExperiment.init();
+//
+// For requests tagged as AI actions, it saves what they write to the database (in the host's
+// snapshot table) so the user can Undo them. Normal requests are never touched.
+// It never breaks the host app: any internal failure is swallowed and logged.
+
+const log = require("./lib/log");
+const tagger = require("./lib/tagger");
+const snapshotCrypto = require("./lib/snapshot-crypto");
+const scanner = require("./lib/scanner");
+const pgHook = require("./lib/hooks/pg");
+const prismaHook = require("./lib/hooks/prisma");
+const mysql2Hook = require("./lib/hooks/mysql2");
+const mongodbHook = require("./lib/hooks/mongodb");
+const betterSqliteHook = require("./lib/hooks/better-sqlite3");
+const sqlite3Hook = require("./lib/hooks/sqlite3");
+const mssqlHook = require("./lib/hooks/mssql");
+const schemaReader = require("./lib/schema-reader");
+const { printReport } = require("./lib/report");
+
+let started = false;
+
+/**
+ * @param {object} [options]
+ * @param {string}  [options.testHeader] header that marks a request as an "AI request" (default x-botversion-action-id)
+ * @param {boolean} [options.quiet]      true = no startup report and no logs
+ * @param {string}  [options.apiKey]     the host's BotVersion API key (used to check action id signatures and to protect saved snapshots; never logged or sent)
+ */
+function init(options) {
+  try {
+    if (started) return { ok: true, alreadyStarted: true };
+    started = true;
+
+    const opts = options && typeof options === "object" ? options : {};
+    if (opts.quiet) log.setQuiet(true);
+    if (opts.testHeader) tagger.setHeaderName(opts.testHeader);
+    if (opts.apiKey) tagger.setApiKey(opts.apiKey);
+    if (opts.apiKey) snapshotCrypto.setApiKey(opts.apiKey);
+
+    // 1. Request tagger (framework independent).
+    const taggerTargets = tagger.install();
+
+    // 2. Look at the host project.
+    const scan = scanner.scan();
+
+    // 3. Database hooks. Only the ones that match what the host has..
+    //    (Final SDK: more hooks are added to this same list.)
+    const pgCopies = pgHook.attach(scan.hostRoot);
+    const mysql2Copies = mysql2Hook.attach(scan.hostRoot);
+    const mongodbCopies = mongodbHook.attach(scan.hostRoot);
+    const betterSqliteCopies = betterSqliteHook.attach(scan.hostRoot);
+    const sqlite3Copies = sqlite3Hook.attach(scan.hostRoot);
+    const mssqlCopies = mssqlHook.attach(scan.hostRoot);
+    const prismaState = prismaHook.attach(
+      scan.hostRoot,
+      scan.prisma && scan.prisma.database
+        ? scan.prisma.database.provider
+        : null,
+    );
+
+    // Database structure (schema only). Runs AFTER the hooks attach so loading Prisma here cannot make the Prisma hook miss it.
+    scan.structure = scan.prisma
+      ? schemaReader.readPrismaStructure(scan.hostRoot)
+      : { ok: false, noSchemaFile: true };
+
+    // 4. Plain-language report.
+    printReport(scan, {
+      taggerTargets,
+      header: tagger.getHeaderName(),
+      signedIds: tagger.hasApiKey(),
+      pgCopies,
+      mysql2Copies,
+      mongodbCopies,
+      betterSqliteCopies,
+      sqlite3Copies,
+      mssqlCopies,
+      prismaState,
+    });
+
+    return { ok: true };
+  } catch (e) {
+    return { ok: false };
+  }
+}
+
+// For hosts that start the experiment with the first-import form (register.js) and pass the key later.
+function setApiKey(key) {
+  try {
+    tagger.setApiKey(key);
+    snapshotCrypto.setApiKey(key);
+  } catch (_) {
+    /* never break the host */
+  }
+}
+
+module.exports = { init, setApiKey };
+module.exports.default = module.exports; // lets `import x from '...'` work in ESM hosts