vektor-guard 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vektor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# vektor-guard
+
+**Stop your AI agent from running `DROP TABLE` on production.**
+
+Works inside Claude Desktop, Cursor, or wherever you already work — no new app to learn.
+
+---
+
+## Why this exists
+
+In July 2026 a developer gave an AI agent write access to a production Supabase instance. A single `prisma migrate diff` — with `--shadow-database-url` resolving to the production connection — dropped every table. Two tables that were never defined in the `migrations` folder were gone for good.
+
+The agent had safety instructions. It reasoned past them.
+
+That is the problem this solves: instructions are not a control. An agent that *decides* not to run something is a different thing from an agent that *cannot* run it without a human saying yes. `vektor-guard` is the second kind.
+
+## Install (2 minutes)
+
+Add this to your MCP client config:
+
+**Claude Desktop** — `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`)
+
+```json
+{
+  "mcpServers": {
+    "vektor-guard": {
+      "command": "npx",
+      "args": ["-y", "-p", "vektor-guard", "vektor-guard-mcp"]
+    }
+  }
+}
+```
+
+**Cursor** — `.cursor/mcp.json` in your project, same shape.
+
+Restart the client. The agent now has an `inspect_sql` tool it can call before running anything.
+
+Tell it once, in your project rules or system prompt:
+
+> Before running any SQL that writes, alters, or drops, call `inspect_sql` first. If it returns BLOCKED, stop and ask me.
+
+## What it catches
+
+| Operation | Why |
+|---|---|
+| `DROP TABLE` | Destroys a table and every row in it |
+| `TRUNCATE` | Empties a table irreversibly |
+| `DELETE` without `WHERE` | Removes every row |
+| `ALTER TABLE … DROP COLUMN` | Destroys a column and its data |
+| `DROP DATABASE` / `DROP SCHEMA` | Destroys everything |
+| `CREATE DATABASE` | How a Prisma shadow-database step begins — the July case |
+
+It is deliberately conservative, and it is not fooled by the usual ways a keyword hides:
+
+```sql
+-- caught: a comment between the keywords
+DROP /* nothing to see here */ TABLE users;
+
+-- NOT flagged: the keyword is data, not structure
+INSERT INTO audit (note) VALUES ('someone ran DROP TABLE users');
+```
+
+Statements are split quote-, comment- and dollar-quote-aware, and string literals are masked before the rules run.
+
+## Two levels
+
+**Free (what you just installed).** Local pattern matching. Nothing leaves your machine — no connection string, no SQL, no telemetry. It tells you *what* is dangerous.
+
+It cannot tell you *how much* is at stake, because it never connects to anything. "Deletes every row" is as specific as it gets.
+
+**With a Vektor API key.** The same call is answered by Vektor's engine against your actual database:
+
+```
+BLOCKED — 1 destructive operation(s) found. Do NOT run this SQL.
+
+[delete-without-where] DELETE without a WHERE clause removes every row in the table.
+  table: orders
+  rows at risk: 2,310,884
+  → DELETE FROM orders
+```
+
+```json
+{
+  "mcpServers": {
+    "vektor-guard": {
+      "command": "npx",
+      "args": ["-y", "-p", "vektor-guard", "vektor-guard-mcp"],
+      "env": {
+        "VEKTOR_API_KEY": "vk_live_...",
+        "VEKTOR_DATABASE_URL": "postgresql://..."
+      }
+    }
+  }
+}
+```
+
+The connection is opened read-only and the credential is used for the call and discarded — there is no apply path in the connector, and nothing is stored server-side.
+
+If the engine is unreachable, it falls back to the local check and **says so** in the result. An unavailable engine never reads as "safe".
+
+Get a key at [vektor.dev](https://vektor.dev).
+
+## Also a CLI
+
+Same rules, no MCP client needed — useful in CI:
+
+```bash
+npx vektor-guard --file prisma/migrations/20260724_init/migration.sql
+cat migration.sql | npx vektor-guard
+npx vektor-guard "DELETE FROM users;"
+```
+
+Exit codes: `0` clean · `2` blocked · `1` usage error. `--allow-destructive` downgrades blocks to warnings.
+
+**GitHub Actions:**
+
+```yaml
+- name: Check migrations for destructive operations
+  run: |
+    for file in $(git diff --name-only origin/main -- '**/migration.sql'); do
+      npx -y vektor-guard --file "$file"
+    done
+```
+
+## Limits, stated plainly
+
+- It is a **lexical** check, not a full SQL parser. It errs toward flagging.
+- It cannot stop an agent that never calls it — it is a tool the agent must be told to use, not a network-level proxy.
+- The free tier has no idea how big your tables are.
+- It does not replace backups, PITR, or least-privilege database credentials. It is one layer.
+
+## Tests
+
+```bash
+node test.mjs      # the rules
+node test-mcp.mjs  # the MCP protocol, end to end
+```
+
+## About
+
+Extracted from the engine of [Vektor](https://vektor.dev) — a desktop IDE for designing and safely operating PostgreSQL schemas. This part is MIT and always will be.
+
+MIT © 2026 Vektor

package/mcp-server.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+// vektor-guard MCP server — the safety layer between an AI agent and your database.
+//
+// Speaks the Model Context Protocol over stdio, so Claude Desktop, Cursor, or any
+// other MCP client can call it. Add five lines to a config file and the agent gains
+// a tool it must go through before it can propose destructive SQL.
+//
+//   {
+//     "mcpServers": {
+//       "vektor-guard": { "command": "npx", "args": ["-y", "vektor-guard-mcp"] }
+//     }
+//   }
+//
+// TWO LEVELS, and the difference is honest:
+//
+//   Free (no key)     Local pattern matching. Catches DROP TABLE, TRUNCATE,
+//                     DELETE without WHERE, ALTER … DROP COLUMN, and the Prisma
+//                     shadow-database case. Nothing leaves the machine. It cannot
+//                     tell you how many rows are at stake, because it never
+//                     connects to anything.
+//
+//   With VEKTOR_API_KEY   The same call is answered by Vektor's engine against
+//                     the real database: actual row counts, lock modes, and the
+//                     full execution plan. "Deletes every row" becomes "deletes
+//                     2,310,884 rows and holds ACCESS EXCLUSIVE for ~8s".
+//
+// Protocol implemented directly rather than via a dependency: MCP over stdio is
+// newline-delimited JSON-RPC 2.0, and a security tool with no supply chain is
+// worth more than one with a convenient SDK.
+
+import { createInterface } from "node:readline";
+
+import { initParser, inspectSql, SEVERITY } from "./rules.mjs";
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_NAME = "vektor-guard";
+const SERVER_VERSION = "0.2.0";
+
+const API_BASE = process.env.VEKTOR_API_URL ?? "https://api.vektor.dev";
+const API_KEY = process.env.VEKTOR_API_KEY ?? null;
+/** The database the paid tier inspects. Never read unless a key is present —
+ *  the free tier must not touch a connection string at all. */
+const DATABASE_URL = process.env.VEKTOR_DATABASE_URL ?? null;
+
+// --------------------------------------------------------------------------- //
+// The tools this server exposes
+// --------------------------------------------------------------------------- //
+
+const TOOLS = [
+  {
+    name: "inspect_sql",
+    description:
+      "Check SQL for destructive operations BEFORE running it. Call this on any " +
+      "statement that writes, alters, or drops — DROP TABLE, TRUNCATE, DELETE, " +
+      "ALTER TABLE, or a migration file. Returns whether it is safe and, when a " +
+      "Vektor API key is configured, how many real rows would be affected.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sql: {
+          type: "string",
+          description: "The SQL to inspect. May contain several statements.",
+        },
+      },
+      required: ["sql"],
+    },
+  },
+  {
+    name: "guard_status",
+    description:
+      "Report which mode the guard is running in (local pattern matching, or " +
+      "connected to the Vektor engine with real database analysis) and what " +
+      "quota remains. Useful when a user asks why a result lacks row counts.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+// --------------------------------------------------------------------------- //
+// Talking to the Vektor engine (paid tier only)
+// --------------------------------------------------------------------------- //
+
+async function callEngine(path, body) {
+  const response = await fetch(`${API_BASE}${path}`, {
+    method: body ? "POST" : "GET",
+    headers: {
+      Authorization: `Bearer ${API_KEY}`,
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `Vektor engine answered ${response.status}${detail ? `: ${detail.slice(0, 300)}` : ""}`,
+    );
+  }
+  return response.json();
+}
+
+// --------------------------------------------------------------------------- //
+// Rendering a verdict for the agent to read
+// --------------------------------------------------------------------------- //
+
+function renderLocal(verdict) {
+  const violations = verdict.findings;
+  if (violations.length === 0) {
+    return (
+      "SAFE — no destructive operations found (local pattern check).\n\n" +
+      "Note: this was a local check with no database connection, so row counts " +
+      "and lock durations are unknown."
+    );
+  }
+
+  const blocked = violations.filter((v) => v.severity === SEVERITY.BLOCK);
+  const lines = [
+    blocked.length === 0
+      ? `WARNING — ${violations.length} finding(s). Review before running.`
+      : `BLOCKED — ${blocked.length} destructive operation(s) found. Do NOT run this SQL.`,
+    "",
+  ];
+  for (const violation of violations) {
+    lines.push(`[${violation.rule}] ${violation.reason}`);
+    lines.push(`  → ${violation.statement.slice(0, 200)}`);
+    lines.push("");
+  }
+  lines.push(
+    "Ask the user to confirm explicitly before proceeding. If this is intentional, " +
+      "the user should run it themselves rather than having you do it.",
+  );
+  return lines.join("\n");
+}
+
+function renderEngine(verdict) {
+  const { allowed, findings, row_counts_supplied: withCounts } = verdict;
+
+  if (findings.length === 0) {
+    return withCounts
+      ? "SAFE — no destructive operations found, checked against the live database."
+      : "SAFE — no destructive operations found.";
+  }
+
+  const lines = [
+    allowed
+      ? `WARNING — ${findings.length} finding(s). Review before running.`
+      : `BLOCKED — ${findings.length} destructive operation(s) found. Do NOT run this SQL.`,
+    "",
+  ];
+  for (const finding of findings) {
+    lines.push(`[${finding.rule}] ${finding.reason}`);
+    if (finding.table) lines.push(`  table: ${finding.table}`);
+    if (finding.estimated_rows !== null && finding.estimated_rows !== undefined) {
+      lines.push(`  rows at risk: ${finding.estimated_rows.toLocaleString("en-US")}`);
+    }
+    lines.push(`  → ${finding.statement.slice(0, 200)}`);
+    lines.push("");
+  }
+  lines.push(
+    "Ask the user to confirm explicitly before proceeding. If this is intentional, " +
+      "the user should run it themselves rather than having you do it.",
+  );
+  return lines.join("\n");
+}
+
+// --------------------------------------------------------------------------- //
+// Tool dispatch
+// --------------------------------------------------------------------------- //
+
+async function runInspectSql(sql) {
+  if (!API_KEY) {
+    return renderLocal(inspectSql(sql));
+  }
+
+  try {
+    const body = await callEngine("/api/connector/inspect-sql", {
+      sql,
+      dsn: DATABASE_URL,
+    });
+    return renderEngine(body.verdict);
+  } catch (error) {
+    // The engine being unreachable must never mean "safe". Fall back to the
+    // local check, and say plainly that is what happened.
+    return (
+      `${renderLocal(inspectSql(sql))}\n\n` +
+      `(Vektor engine unavailable — ${error.message}. This was a local check only.)`
+    );
+  }
+}
+
+async function guardStatus() {
+  if (!API_KEY) {
+    return (
+      "Mode: LOCAL (free). Pattern matching only, nothing leaves this machine.\n" +
+      "Row counts and lock durations are not available in this mode.\n\n" +
+      "Set VEKTOR_API_KEY (and VEKTOR_DATABASE_URL) to analyse against the real database."
+    );
+  }
+
+  try {
+    const health = await callEngine("/api/connector/health");
+    return (
+      `Mode: ENGINE (${health.tier}). Connected to the Vektor engine.\n` +
+      `Quota: ${health.quota_used} of ${health.daily_quota} calls used today.\n` +
+      `Database analysis: ${DATABASE_URL ? "enabled" : "no VEKTOR_DATABASE_URL set — row counts unavailable"}.`
+    );
+  } catch (error) {
+    return `Mode: LOCAL (fallback). The Vektor engine is unreachable — ${error.message}`;
+  }
+}
+
+async function runTool(name, args) {
+  if (name === "inspect_sql") {
+    const sql = args?.sql;
+    if (typeof sql !== "string" || !sql.trim()) {
+      throw new Error("`sql` is required and must be a non-empty string.");
+    }
+    return runInspectSql(sql);
+  }
+  if (name === "guard_status") return guardStatus();
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+// --------------------------------------------------------------------------- //
+// JSON-RPC over stdio
+// --------------------------------------------------------------------------- //
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+async function handle(request) {
+  const { id, method, params } = request;
+
+  // Notifications have no id and expect no response.
+  if (id === undefined || id === null) return;
+
+  if (method === "initialize") {
+    reply(id, {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+    });
+    return;
+  }
+
+  if (method === "tools/list") {
+    reply(id, { tools: TOOLS });
+    return;
+  }
+
+  if (method === "tools/call") {
+    try {
+      const text = await runTool(params?.name, params?.arguments);
+      reply(id, { content: [{ type: "text", text }] });
+    } catch (error) {
+      // isError, rather than a protocol error: the agent should read the failure
+      // and tell the user, not treat the tool as broken and route around it.
+      reply(id, {
+        content: [{ type: "text", text: `vektor-guard failed: ${error.message}` }],
+        isError: true,
+      });
+    }
+    return;
+  }
+
+  if (method === "ping") {
+    reply(id, {});
+    return;
+  }
+
+  replyError(id, -32601, `Method not found: ${method}`);
+}
+
+async function main() {
+  // The parser is WebAssembly and must be loaded before the first tool call.
+  await initParser();
+  const lines = createInterface({ input: process.stdin });
+
+  lines.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let request;
+    try {
+      request = JSON.parse(trimmed);
+    } catch {
+      replyError(null, -32700, "Parse error");
+      return;
+    }
+    void handle(request);
+  });
+
+  lines.on("close", () => process.exit(0));
+}
+
+if (process.argv[1]?.endsWith("mcp-server.mjs")) {
+  void main();
+}
+
+export { renderLocal, renderEngine, runTool, handle };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "vektor-guard",
+  "version": "0.3.0",
+  "description": "Stop your AI agent from running DROP TABLE on production. Decides on PostgreSQL's own parse tree, not patterns. MCP server for Claude Desktop and Cursor, plus a CLI.",
+  "type": "module",
+  "bin": {
+    "vektor-guard": "vektor-guard.mjs",
+    "vektor-guard-mcp": "mcp-server.mjs"
+  },
+  "exports": {
+    ".": "./vektor-guard.mjs",
+    "./mcp": "./mcp-server.mjs"
+  },
+  "files": [
+    "vektor-guard.mjs",
+    "rules.mjs",
+    "mcp-server.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test.mjs && node test-mcp.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "ai-safety",
+    "sql",
+    "postgres",
+    "prisma",
+    "migration",
+    "guard",
+    "drop-table"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "libpg-query": "^17.7.4"
+  }
+}

package/rules.mjs

@@ -0,0 +1,241 @@
+// Destructive-operation rules, decided on PostgreSQL's own parse tree.
+//
+// This is the same ruleset as `src/vektor/guard/rules.py`, on the same parser:
+// Python binds libpg_query through pglast, this binds it through libpg-query.
+// One parser, two bindings — which is why the two can agree. The previous
+// version matched patterns against text and disagreed with the engine within a
+// day, passing eight valid destructive statements the engine caught.
+//
+// libpg-query ships as WebAssembly, so there is no native toolchain to install
+// and no platform it fails to build on. That is the whole reason it is an
+// acceptable dependency for a package whose selling point was having none.
+
+import { loadModule, parseSync } from "libpg-query";
+
+let ready = false;
+
+/** The parser is WASM and must be initialised once before any parse. */
+export async function initParser() {
+  if (!ready) {
+    await loadModule();
+    ready = true;
+  }
+}
+
+export const SEVERITY = { BLOCK: "block", WARN: "warn" };
+
+// --------------------------------------------------------------------------- //
+// Reading names out of the tree
+// --------------------------------------------------------------------------- //
+
+/** A table name without its schema — what a row-count lookup is keyed on. */
+function bare(name) {
+  return name ? String(name).split(".").pop() : null;
+}
+
+/** The single node inside a libpg-query wrapper: {DropStmt: {...}} -> ["DropStmt", {...}] */
+function unwrap(node) {
+  if (!node || typeof node !== "object") return [null, null];
+  const key = Object.keys(node)[0];
+  return [key, node[key]];
+}
+
+/** Names from a DropStmt.objects, each a List of String parts. */
+function objectNames(objects) {
+  const names = [];
+  for (const obj of objects ?? []) {
+    const parts = (obj?.List?.items ?? []).map((p) => p?.String?.sval).filter(Boolean);
+    if (parts.length) names.push(parts[parts.length - 1]);
+  }
+  return names;
+}
+
+/**
+ * Whether a WHERE clause filters nothing — `WHERE 1=1`, `WHERE true`.
+ *
+ * Only the forms people actually write are recognised. A predicate this cannot
+ * evaluate counts as a real filter, which is the safe direction: `WHERE 1=2`
+ * deletes nothing and flagging it would be a false positive.
+ */
+function filtersNothing(node) {
+  if (!node) return false;
+  const [kind, body] = unwrap(node);
+
+  if (kind === "A_Const") {
+    return body?.boolval?.boolval === true;
+  }
+
+  if (kind === "A_Expr") {
+    const op = body?.name?.[0]?.String?.sval;
+    if (op !== "=") return false;
+    const [lk, lv] = unwrap(body.lexpr);
+    const [rk, rv] = unwrap(body.rexpr);
+    if (lk !== "A_Const" || rk !== "A_Const") return false;
+    for (const field of ["ival", "sval", "fval", "boolval"]) {
+      if (lv?.[field] !== undefined && rv?.[field] !== undefined) {
+        return JSON.stringify(lv[field]) === JSON.stringify(rv[field]);
+      }
+    }
+    return false;
+  }
+
+  if (kind === "BoolExpr" && body?.boolop === "AND_EXPR") {
+    const args = body.args ?? [];
+    return args.length > 0 && args.every(filtersNothing);
+  }
+
+  return false;
+}
+
+// --------------------------------------------------------------------------- //
+// The rules
+// --------------------------------------------------------------------------- //
+
+const DROP_KINDS = {
+  OBJECT_TABLE: ["drop-table", SEVERITY.BLOCK, "DROP TABLE destroys a table and every row in it."],
+  OBJECT_SCHEMA: ["drop-database", SEVERITY.BLOCK, "DROP SCHEMA destroys every object in the schema."],
+  OBJECT_SEQUENCE: ["drop-sequence", SEVERITY.BLOCK, "DROP SEQUENCE destroys a sequence; columns defaulting to it break."],
+  OBJECT_MATVIEW: ["drop-matview", SEVERITY.BLOCK, "DROP MATERIALIZED VIEW destroys the view and its stored rows."],
+  OBJECT_INDEX: ["drop-index", SEVERITY.WARN, "DROP INDEX loses no rows, but queries relying on it can slow by orders of magnitude, and rebuilding it locks writes."],
+  OBJECT_VIEW: ["drop-view", SEVERITY.WARN, "DROP VIEW loses no rows, but anything selecting from it breaks."],
+};
+
+const ALTER_KINDS = {
+  AT_DropColumn: ["drop-column", SEVERITY.BLOCK, "ALTER TABLE … DROP COLUMN destroys a column and all the data in it."],
+  AT_DropConstraint: ["drop-constraint", SEVERITY.WARN, "Dropping a constraint removes a guarantee the data currently satisfies; invalid rows can appear afterwards and are hard to find later."],
+  AT_AlterColumnType: ["column-type-rewrite", SEVERITY.WARN, "Changing a column's type rewrites every row under an ACCESS EXCLUSIVE lock, which blocks reads as well as writes for the duration."],
+};
+
+/** Rules for one statement: [rule, severity, reason, table] tuples. */
+function findingsFor(stmtNode) {
+  const [kind, s] = unwrap(stmtNode);
+  const out = [];
+
+  if (kind === "DropStmt") {
+    const entry = DROP_KINDS[s.removeType];
+    if (entry) {
+      const names = objectNames(s.objects);
+      // One finding per object: `DROP TABLE a, b` risks two tables, and a
+      // single finding could only name one of them.
+      for (const name of names.length ? names : [null]) out.push([...entry, bare(name)]);
+    }
+  } else if (kind === "DropdbStmt") {
+    out.push(["drop-database", SEVERITY.BLOCK, "DROP DATABASE destroys an entire database.", null]);
+  } else if (kind === "DropOwnedStmt") {
+    out.push(["drop-owned", SEVERITY.BLOCK, "DROP OWNED BY destroys every object the named role owns — often the whole application schema.", null]);
+  } else if (kind === "TruncateStmt") {
+    for (const rel of s.relations ?? []) {
+      out.push(["truncate", SEVERITY.BLOCK, "TRUNCATE empties a table irreversibly and cannot be rolled back cheaply.", bare(rel?.RangeVar?.relname)]);
+    }
+  } else if (kind === "DeleteStmt") {
+    const table = bare(s.relation?.relname);
+    if (!s.whereClause) {
+      out.push(["delete-without-where", SEVERITY.BLOCK, "DELETE without a WHERE clause removes every row in the table.", table]);
+    } else if (filtersNothing(s.whereClause)) {
+      out.push(["delete-without-where", SEVERITY.BLOCK, "This DELETE has a WHERE clause that filters nothing, so it removes every row in the table.", table]);
+    }
+  } else if (kind === "UpdateStmt") {
+    const table = bare(s.relation?.relname);
+    if (!s.whereClause || filtersNothing(s.whereClause)) {
+      out.push(["update-without-where", SEVERITY.BLOCK, "This UPDATE has no effective WHERE clause, so it overwrites the named columns in every row. The previous values are gone.", table]);
+    }
+  } else if (kind === "AlterTableStmt") {
+    const table = bare(s.relation?.relname);
+    for (const cmd of s.cmds ?? []) {
+      const entry = ALTER_KINDS[cmd?.AlterTableCmd?.subtype];
+      if (entry) out.push([...entry, table]);
+    }
+  } else if (kind === "VacuumStmt") {
+    const full = (s.options ?? []).some((o) => o?.DefElem?.defname === "full");
+    if (full) {
+      for (const rel of s.rels ?? []) {
+        out.push(["vacuum-full", SEVERITY.WARN, "VACUUM FULL rewrites the whole table under an ACCESS EXCLUSIVE lock and needs room for a second copy on disk.", bare(rel?.VacuumRelation?.relation?.relname)]);
+      }
+    }
+  } else if (kind === "CreatedbStmt") {
+    out.push(["shadow-database", SEVERITY.WARN, "CREATE DATABASE is how a Prisma shadow-database step begins. Flagged because `prisma migrate diff --shadow-database-url` pointed at a real server is the documented way production data has been lost.", null]);
+  } else if (kind === "DoStmt") {
+    out.push(["opaque-block", SEVERITY.WARN, "A DO block runs procedural code whose statements are built at runtime, so what it will execute cannot be read from the SQL. Nothing inside it has been checked.", null]);
+  }
+
+  return out;
+}
+
+// --------------------------------------------------------------------------- //
+// Entry point
+// --------------------------------------------------------------------------- //
+
+const collapse = (text) => String(text).replace(/\s+/g, " ").trim();
+
+/**
+ * Weigh a script on the real parse tree.
+ *
+ * `rowCounts` maps a bare table name to a live row count; omit it and
+ * `estimatedRows` stays null, which reads as "nobody asked the database" rather
+ * than "zero".
+ *
+ * Call `initParser()` once before this.
+ */
+export function inspectSql(sql, rowCounts = {}) {
+  const counts = Object.fromEntries(
+    Object.entries(rowCounts).map(([k, v]) => [k.toLowerCase(), v]),
+  );
+
+  let parsed;
+  try {
+    parsed = parseSync(sql);
+  } catch (error) {
+    // Fail closed. Unreadable is not safe.
+    return {
+      allowed: false,
+      findings: [
+        {
+          rule: "unparseable",
+          severity: SEVERITY.BLOCK,
+          reason:
+            `PostgreSQL could not parse this SQL, so nothing about it has been ` +
+            `verified (${error.message}). Refused rather than assumed safe. Note ` +
+            `that psql meta-commands such as \\d are not SQL and must be removed ` +
+            `before checking.`,
+          statement: collapse(sql).slice(0, 200),
+          table: null,
+          estimatedRows: null,
+        },
+      ],
+      statementsScanned: 0,
+      rowCountsSupplied: Object.keys(counts).length > 0,
+    };
+  }
+
+  const findings = [];
+  let scanned = 0;
+
+  for (const raw of parsed.stmts ?? []) {
+    if (!raw.stmt) continue;
+    scanned += 1;
+
+    // The original text, so a finding quotes what was written rather than a
+    // re-rendering of the tree.
+    const start = raw.stmt_location ?? 0;
+    const text = raw.stmt_len ? sql.slice(start, start + raw.stmt_len) : sql.slice(start);
+    const statement = collapse(text);
+
+    for (const [rule, severity, reason, table] of findingsFor(raw.stmt)) {
+      findings.push({
+        rule,
+        severity,
+        reason,
+        statement,
+        table: table ?? null,
+        estimatedRows: table && counts[table.toLowerCase()] !== undefined ? counts[table.toLowerCase()] : null,
+      });
+    }
+  }
+
+  return {
+    allowed: !findings.some((f) => f.severity === SEVERITY.BLOCK),
+    findings,
+    statementsScanned: scanned,
+    rowCountsSupplied: Object.keys(counts).length > 0,
+  };
+}

package/vektor-guard.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// vektor-guard — a gate that refuses destructive SQL before anything runs it.
+//
+// The rules live in `rules.mjs` and are decided on PostgreSQL's own parse tree,
+// so this CLI and the Vektor engine give the same answer to the same SQL. They
+// used to disagree: this file matched patterns against text and passed eight
+// valid destructive statements the engine caught.
+//
+//   • DROP TABLE / SCHEMA / DATABASE     • DELETE or UPDATE with no real WHERE
+//   • TRUNCATE                           • ALTER TABLE … DROP COLUMN
+//   • DROP OWNED BY                      • a Prisma shadow-database CREATE
+//
+// Usage:
+//   cat migration.sql | npx vektor-guard
+//   npx vektor-guard --file prisma/migrations/…/migration.sql
+//   npx vektor-guard "DELETE FROM users;"        # inline
+//
+// Exit codes: 0 clean · 2 blocked · 1 usage error. `--allow-destructive`
+// downgrades blocks to warnings (exit 0) for the rare intentional case.
+
+import { initParser, inspectSql, SEVERITY } from "./rules.mjs";
+
+export { inspectSql };
+
+// --------------------------------------------------------------------------- //
+// CLI
+// --------------------------------------------------------------------------- //
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    if (process.stdin.isTTY) return resolve("");
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => resolve(data));
+  });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const allow = argv.includes("--allow-destructive");
+  const fileIdx = argv.indexOf("--file");
+  let sql = "";
+
+  if (fileIdx !== -1) {
+    const { readFileSync } = await import("node:fs");
+    sql = readFileSync(argv[fileIdx + 1], "utf8");
+  } else {
+    // No --file, so nothing is the path argument. The previous version excluded
+    // `argv[fileIdx + 1]` here too — with fileIdx === -1 that is argv[0], which
+    // is the inline SQL itself, so `npx vektor-guard "DROP TABLE users;"` (the
+    // invocation the README documents) always answered "no SQL given".
+    const inline = argv.find((a) => !a.startsWith("--"));
+    sql = inline ?? (await readStdin());
+  }
+
+  if (!sql.trim()) {
+    process.stderr.write(
+      "vektor-guard: no SQL given. Pipe it in, pass --file <path>, or an inline string.\n",
+    );
+    process.exit(1);
+  }
+
+  await initParser();
+  const verdict = inspectSql(sql);
+
+  if (verdict.findings.length === 0) {
+    process.stderr.write("vektor-guard: ✓ no destructive operations found.\n");
+    process.exit(0);
+  }
+
+  // Warnings alone do not fail the run. They cover operations that are
+  // legitimate often enough that refusing them categorically is how a guard
+  // gets switched off — which is the failure mode that matters most.
+  const blocked = verdict.findings.filter((f) => f.severity === SEVERITY.BLOCK);
+  const label = blocked.length === 0 || allow ? "⚠ WARNING" : "✗ BLOCKED";
+
+  process.stderr.write(
+    `vektor-guard: ${label} — ${verdict.findings.length} finding(s) in ` +
+      `${verdict.statementsScanned} statement(s):\n`,
+  );
+  for (const f of verdict.findings) {
+    const preview = f.statement.length > 100 ? f.statement.slice(0, 100) + "…" : f.statement;
+    const rows = f.estimatedRows === null ? "" : `\n    rows at risk: ${f.estimatedRows.toLocaleString("en-US")}`;
+    process.stderr.write(`\n  [${f.rule}] ${f.reason}${rows}\n    → ${preview}\n`);
+  }
+  process.stderr.write(
+    blocked.length === 0
+      ? "\nNothing blocking. Review the warnings above.\n"
+      : allow
+        ? "\nAllowed by --allow-destructive.\n"
+        : "\nRefused. Re-run with --allow-destructive only if this is deliberate.\n",
+  );
+  process.exit(blocked.length === 0 || allow ? 0 : 2);
+}
+
+// Run only as a CLI, not when imported for the exported functions.
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("vektor-guard.mjs")) {
+  main();
+}