procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/_lib/dbprofiles.py

@@ -0,0 +1,147 @@
+"""Named connection-profile store shared by the `sqlserver` and `mysql` tools.
+
+Split storage, by design (see CLAUDE.md Hard rule 1 — no secrets in files):
+
+  * NON-SECRET config (profile name, server/host, port, database, username,
+    driver, TLS flags, timeouts) lives in a ``profiles.json`` file INSIDE the
+    tool directory. It never contains a password.
+  * The PASSWORD lives ONLY in Windows Credential Manager, under the target
+    ``agents-and-tools:<tool>:<profile-name>`` — i.e. the secret name IS the
+    profile name. Read at runtime via ``tools._lib.creds.get(tool, profile)``.
+
+So a profile named ``default`` on the ``sqlserver`` tool keeps its host/db/etc.
+in ``tools/sqlserver/profiles.json`` and its password under the credential
+target ``agents-and-tools:sqlserver:default``. Set it with:
+
+    python scripts/set-credential.py sqlserver default
+
+This module is a thin, dependency-light wrapper (only stdlib + creds). It does
+not import any DB driver, so it stays unit-testable and import-safe.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from tools._lib import creds
+
+
+class ProfileError(Exception):
+    """Bad profile usage (unknown name, duplicate, missing field). -> invalid_argument."""
+
+
+class AuthRequiredError(Exception):
+    """A profile exists but its password is not in Credential Manager. -> auth_required."""
+
+
+class ProfileStore:
+    """Reads/writes the per-tool ``profiles.json`` and resolves passwords.
+
+    Parameters
+    ----------
+    tool : str
+        The tool name (``"sqlserver"`` or ``"mysql"``). Used as the Credential
+        Manager namespace AND must match the manifest ``name``.
+    path : Path
+        Absolute path to this tool's ``profiles.json``.
+    """
+
+    def __init__(self, tool: str, path: Path):
+        self.tool = tool
+        self.path = Path(path)
+
+    # -- raw file I/O -------------------------------------------------------
+
+    def _read(self) -> dict[str, dict]:
+        if not self.path.exists():
+            return {}
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _write(self, data: dict[str, dict]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    # -- CRUD ---------------------------------------------------------------
+
+    def names(self) -> list[str]:
+        return sorted(self._read().keys())
+
+    def exists(self, name: str) -> bool:
+        return name in self._read()
+
+    def get(self, name: str) -> dict:
+        """Return one profile's NON-SECRET config dict (raises if unknown)."""
+        data = self._read()
+        if name not in data:
+            known = ", ".join(sorted(data)) or "(none)"
+            raise ProfileError(
+                f"no profile named '{name}'. Known: {known}. "
+                f"Add one with: run-tool {self.tool} add-profile --name {name} ..."
+            )
+        blob = dict(data[name])
+        blob["name"] = name
+        return blob
+
+    def add(self, name: str, config: dict[str, Any], *, overwrite: bool = False) -> dict:
+        """Store a NON-SECRET profile config. Strips any password-like field."""
+        if not name:
+            raise ProfileError("profile --name is required")
+        data = self._read()
+        if name in data and not overwrite:
+            raise ProfileError(
+                f"profile '{name}' already exists. Pass --overwrite to replace it."
+            )
+        clean = {
+            k: v for k, v in config.items()
+            if v is not None and k not in ("name", "password", "pwd", "pass")
+        }
+        data[name] = clean
+        self._write(data)
+        view = dict(clean)
+        view["name"] = name
+        view["has_password"] = creds.has_for_report(self.tool, name)
+        return view
+
+    def remove(self, name: str) -> None:
+        data = self._read()
+        if name not in data:
+            raise ProfileError(f"no profile named '{name}'")
+        del data[name]
+        self._write(data)
+
+    # -- password (Credential Manager only) ---------------------------------
+
+    def password(self, name: str) -> str:
+        """Fetch the profile password from Credential Manager.
+
+        Raises ``AuthRequiredError`` (mapped to ``auth_required``) when absent,
+        pointing the user at ``scripts/set-credential.py``.
+        """
+        pw = creds.get_optional(self.tool, name)
+        if pw is None:
+            raise AuthRequiredError(
+                f"no password stored for profile '{name}'. Store it with:\n"
+                f"    python scripts/set-credential.py {self.tool} {name}\n"
+                f"(saved to Windows Credential Manager target "
+                f"agents-and-tools:{self.tool}:{name})"
+            )
+        return pw
+
+    # -- public, password-free views ---------------------------------------
+
+    def public_view(self, name: str) -> dict:
+        """A profile dict safe to return/log: no password, presence flagged."""
+        blob = self.get(name)
+        blob["has_password"] = creds.has_for_report(self.tool, name)
+        return blob
+
+    def list_public(self) -> list[dict]:
+        return [self.public_view(n) for n in self.names()]

procesio_cli/tools/_lib/dbquery.py

@@ -0,0 +1,286 @@
+"""Engine-agnostic SQL helpers shared by the `sqlserver` and `mysql` tools.
+
+PURE module: it imports no database driver and opens no connection, so every
+function here is unit-testable with zero infrastructure. The two tools wire it
+to pyodbc / pymysql at the edges.
+
+What lives here:
+  - ``assert_read_only`` / ``is_write_sql`` — a regex write-statement guard that
+    blocks INSERT/UPDATE/DELETE/MERGE/UPSERT/TRUNCATE/ALTER/CREATE/DROP/GRANT/
+    EXEC/CALL/... and multi-statement batches, unless ``write=True``.
+  - ``rows_to_dicts`` — DBAPI cursor rows -> ``list[dict]`` with JSON-safe
+    coercion (datetime/date/time/timedelta/Decimal/bytes/UUID/memoryview/...).
+  - ``cap_rows`` — apply a max-rows cap and report a ``truncated`` flag.
+  - ``mask_dsn`` — redact a password inside any connection string for logging.
+
+The guard is intentionally conservative: it strips string literals, quoted
+identifiers and comments first, then looks for write keywords as whole words at
+statement level. It is a guard, not a SQL parser — the real read-only guarantee
+for SQL Server also leans on ApplicationIntent=ReadOnly + a read-only login when
+configured; for MySQL (no ApplicationIntent equivalent) THIS guard is the
+enforcement, so its keyword list is the superset of both engines.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import decimal as _decimal
+import re
+import uuid as _uuid
+from typing import Any, Sequence
+
+
+class WriteGuardError(Exception):
+    """Raised when a read-only query receives a write/DDL/multi-statement SQL.
+
+    Tools map this to the framework error code ``write_blocked`` (exit 2).
+    """
+
+
+# Write / schema-change / side-effecting keywords. Superset across SQL Server
+# and MySQL so the single guard protects both engines:
+#   - DML:           INSERT, UPDATE, DELETE, MERGE, REPLACE (MySQL upsert), UPSERT
+#   - DDL:           CREATE, ALTER, DROP, TRUNCATE, RENAME
+#   - permissions:   GRANT, REVOKE, DENY
+#   - procedural:    EXEC, EXECUTE, CALL
+#   - bulk / locks:  BULK, LOAD, LOCK, UNLOCK, HANDLER, DO
+#   - tx / backup:   BACKUP, RESTORE, COMMIT, ROLLBACK, SET, USE
+# SET/USE/COMMIT/ROLLBACK are blocked because they change session/tx state and
+# have no place in a read-only ad-hoc query path.
+WRITE_KEYWORDS: tuple[str, ...] = (
+    "INSERT", "UPDATE", "DELETE", "MERGE", "UPSERT", "REPLACE",
+    "CREATE", "ALTER", "DROP", "TRUNCATE", "RENAME",
+    "GRANT", "REVOKE", "DENY",
+    "EXEC", "EXECUTE", "CALL",
+    "BULK", "LOAD", "LOCK", "UNLOCK", "HANDLER", "DO",
+    "BACKUP", "RESTORE", "COMMIT", "ROLLBACK", "SET", "USE",
+)
+
+_WRITE_KW_RE = re.compile(r"\b(" + "|".join(WRITE_KEYWORDS) + r")\b", re.IGNORECASE)
+
+# Read-only DDL-inspection idioms whose CREATE keyword does not create anything.
+_SHOW_CREATE_RE = re.compile(
+    r"\bSHOW\s+CREATE\s+"
+    r"(?:TABLE|VIEW|PROCEDURE|FUNCTION|TRIGGER|EVENT|DATABASE|SCHEMA)\b",
+    re.IGNORECASE,
+)
+
+# Regexes that strip out non-statement text before keyword scanning so that a
+# keyword inside a literal / identifier / comment never trips the guard.
+_STRIP_RES: tuple[re.Pattern[str], ...] = (
+    re.compile(r"'(?:[^'\\]|\\.|'')*'", re.DOTALL),   # 'single-quoted' ('' or \' escaped)
+    re.compile(r'"(?:[^"\\]|\\.|"")*"', re.DOTALL),   # "double-quoted"
+    re.compile(r"`(?:[^`\\]|\\.)*`", re.DOTALL),       # `backtick identifier` (MySQL)
+    re.compile(r"\[[^\]]*\]"),                          # [bracketed identifier] (T-SQL)
+    re.compile(r"/\*.*?\*/", re.DOTALL),               # /* block comment */
+    re.compile(r"--[^\n]*"),                            # -- line comment
+    re.compile(r"#[^\n]*"),                             # # line comment (MySQL)
+    _SHOW_CREATE_RE,                                    # SHOW CREATE ... (read-only)
+)
+
+
+def _strip_noise(sql: str) -> str:
+    """Remove literals, quoted identifiers, comments, SHOW CREATE prefixes."""
+    out = sql
+    for rx in _STRIP_RES:
+        out = rx.sub(" ", out)
+    return out
+
+
+def _split_statements(stripped: str) -> list[str]:
+    """Split a noise-stripped SQL on semicolons into non-empty statements.
+
+    Operates on already-stripped text, so semicolons inside literals/comments
+    are gone and can't create phantom statements.
+    """
+    return [s.strip() for s in stripped.split(";") if s.strip()]
+
+
+def find_write_keywords(sql: str) -> list[str]:
+    """Return write keywords found at statement level (after noise-stripping)."""
+    stripped = _strip_noise(sql)
+    return [m.group(1).upper() for m in _WRITE_KW_RE.finditer(stripped)]
+
+
+def is_multi_statement(sql: str) -> bool:
+    """True if the SQL is a batch of more than one statement (post-strip)."""
+    return len(_split_statements(_strip_noise(sql))) > 1
+
+
+def is_write_sql(sql: str) -> bool:
+    """True if `sql` would be rejected under read-only rules (write or batch)."""
+    return bool(find_write_keywords(sql)) or is_multi_statement(sql)
+
+
+def assert_read_only(sql: str, *, write: bool = False) -> None:
+    """Raise ``WriteGuardError`` unless `sql` is a single read-only statement.
+
+    When ``write=True`` the guard is bypassed entirely (the tool has already
+    confirmed the caller passed ``--write``). When ``write=False`` (default),
+    any write/DDL/EXEC keyword OR a multi-statement batch is rejected.
+    """
+    if write:
+        return
+    hits = find_write_keywords(sql)
+    if hits:
+        # de-duplicate but keep order for a stable message
+        seen: list[str] = []
+        for h in hits:
+            if h not in seen:
+                seen.append(h)
+        raise WriteGuardError(
+            f"read-only guard blocked write keyword(s) {seen}. "
+            f"Pass --write to allow a non-SELECT statement."
+        )
+    if is_multi_statement(sql):
+        raise WriteGuardError(
+            "read-only guard blocked a multi-statement batch (';' separates "
+            "statements). Run one statement per query, or pass --write."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Line-ending normalization for DDL / script text
+# ---------------------------------------------------------------------------
+
+def normalize_eol(sql: str, style: str = "crlf") -> str:
+    """Normalize every line ending in `sql` to one consistent style.
+
+    Collapses CRLF and lone CR to LF first, then expands to the target style,
+    so the result never contains a mixed CR/LF run. Default ``"crlf"`` matches
+    SQL Server / SSMS: when a ``CREATE``/``ALTER`` of a PROCEDURE, VIEW,
+    FUNCTION or TRIGGER is sent with LF-only newlines, SQL Server stores the
+    object source verbatim, and SSMS then reports *"Inconsistent Line Endings"*
+    on script-out because it prepends a CRLF ``SET ANSI_NULLS…GO`` header.
+    Emitting CRLF keeps stored definitions internally consistent.
+
+    T-SQL is whitespace-insensitive between tokens, so this never changes query
+    semantics *outside* of string literals. The one case to preserve a bare LF
+    is inside a string literal that must stay LF — callers expose an opt-out
+    (the sqlserver tool's ``--no-normalize-eol``) for that. Parameter values are
+    bound separately (``?`` placeholders) and are never passed through here.
+    """
+    lf = sql.replace("\r\n", "\n").replace("\r", "\n")
+    if style == "lf":
+        return lf
+    if style != "crlf":
+        raise ValueError(f"unknown eol style: {style!r} (use 'crlf' or 'lf')")
+    return lf.replace("\n", "\r\n")
+
+
+# ---------------------------------------------------------------------------
+# Row formatting: DBAPI rows -> JSON-safe list[dict]
+# ---------------------------------------------------------------------------
+
+def json_safe(value: Any) -> Any:
+    """Coerce one DBAPI value into something ``json.dumps`` can serialise.
+
+    datetime/date/time -> ISO 8601 string; timedelta -> total seconds (float);
+    Decimal -> str (preserves precision); bytes/bytearray/memoryview -> hex str;
+    UUID -> str. Primitives (str/int/float/bool/None) pass through unchanged.
+    Anything else falls back to ``str(value)``.
+    """
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (_dt.datetime, _dt.date, _dt.time)):
+        return value.isoformat()
+    if isinstance(value, _dt.timedelta):
+        return value.total_seconds()
+    if isinstance(value, _decimal.Decimal):
+        return str(value)
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value).hex()
+    if isinstance(value, memoryview):
+        return value.tobytes().hex()
+    if isinstance(value, _uuid.UUID):
+        return str(value)
+    return str(value)
+
+
+def column_names(cursor) -> list[str]:
+    """Column names from a DBAPI ``cursor.description`` (empty if no result set)."""
+    if not getattr(cursor, "description", None):
+        return []
+    return [d[0] for d in cursor.description]
+
+
+def first_result_columns(cursor) -> list[str]:
+    """Columns of the first result that has any, stepping past row-count-only results.
+
+    A multi-statement batch run without SET NOCOUNT ON opens with "N rows affected"
+    results that carry no columns; the rows the caller wants come after them.
+    """
+    columns = column_names(cursor)
+    nextset = getattr(cursor, "nextset", None)
+    while not columns and nextset is not None and nextset():
+        columns = column_names(cursor)
+    return columns
+
+
+def drain_results(cursor) -> None:
+    """Step through every remaining result of the last ``execute`` so its errors surface.
+
+    The server returns a batch's results in order and the driver raises a statement's
+    error only when the cursor reaches it. A batch whose INSERT reported "1 row affected"
+    and whose next statement failed looks successful until ``nextset()`` gets there, so
+    a caller that must not lose an error drains after every execute.
+    """
+    nextset = getattr(cursor, "nextset", None)
+    if nextset is None:  # test doubles without result sets
+        return
+    while nextset():
+        pass
+
+
+def rows_to_dicts(
+    columns: Sequence[str],
+    raw_rows: Sequence[Any],
+) -> list[dict]:
+    """Map DBAPI rows to JSON-safe dicts keyed by `columns`.
+
+    Accepts both sequence rows (pyodbc tuples) and mapping rows (pymysql
+    DictCursor dicts) — for a dict row we read each column by name, for a
+    sequence row by position. Every value is passed through ``json_safe``.
+    """
+    out: list[dict] = []
+    for row in raw_rows:
+        if isinstance(row, dict):
+            out.append({c: json_safe(row.get(c)) for c in columns})
+        else:
+            out.append({columns[i]: json_safe(row[i]) for i in range(len(columns))})
+    return out
+
+
+def cap_rows(rows: list[Any], max_rows: int | None) -> tuple[list[Any], bool]:
+    """Trim `rows` to at most `max_rows`; return ``(rows, truncated)``.
+
+    ``max_rows is None`` or ``<= 0`` means no cap. ``truncated`` is True only
+    when rows were actually dropped.
+    """
+    if max_rows is None or max_rows <= 0:
+        return rows, False
+    if len(rows) > max_rows:
+        return rows[:max_rows], True
+    return rows, False
+
+
+# ---------------------------------------------------------------------------
+# Connection-string masking (for safe logging / test-connection output)
+# ---------------------------------------------------------------------------
+
+# pyodbc uses PWD=...; pymysql-style DSNs may use password=...; URL DSNs use
+# scheme://user:password@host. Cover all three.
+_MASK_RES: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"(?i)(PWD\s*=)[^;]*"), r"\1***"),
+    (re.compile(r"(?i)(PASSWORD\s*=)[^;]*"), r"\1***"),
+    (re.compile(r"(?i)(PASSWORD\s*:\s*)[^,}\s]+"), r"\1***"),
+    # scheme://user:password@host  ->  scheme://user:***@host
+    (re.compile(r"(://[^:/@\s]+:)[^@/\s]+(@)"), r"\1***\2"),
+)
+
+
+def mask_dsn(dsn: str) -> str:
+    """Replace any password value in a connection string with ``***``."""
+    out = dsn
+    for rx, repl in _MASK_RES:
+        out = rx.sub(repl, out)
+    return out

procesio_cli/tools/_lib/dbschema.py

@@ -0,0 +1,225 @@
+"""Engine-agnostic schema-mirror, diff, and migration helpers.
+
+Shared by the `sqlserver` and `mysql` tools' `schema-extract`, `schema-diff`, and
+`migrate` actions. PURE: no DB driver import, no network — every function is a
+deterministic transform of its inputs, so it is fully unit-testable without a
+database. The engine-specific parts (catalog queries, tracking-table SQL, apply
+path) live in each tool's `schema.py`; this module is the common machinery.
+
+Mirror layout (one file per object):
+    <out>/schema/<Type>/<schema>.<name>.sql      (or <name>.sql when schema is "")
+    <out>/_manifest.json                          {relpath: sha256}
+
+A "record" is a dict: {"type": <dir label>, "schema": <str|"">, "name": <str>,
+"definition": <sql text>}.
+"""
+from __future__ import annotations
+
+import difflib
+import hashlib
+import json
+import re
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# hashing
+# ---------------------------------------------------------------------------
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def sha256_file(path: str | Path) -> str:
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# mirror layout
+# ---------------------------------------------------------------------------
+
+_UNSAFE = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+
+
+def _safe(component: str) -> str:
+    """Make one path component filesystem-safe (Windows + POSIX)."""
+    s = _UNSAFE.sub("_", str(component)).strip().rstrip(".")
+    return s or "_"
+
+
+def mirror_relpath(obj_type: str, schema: str, name: str) -> str:
+    """Deterministic POSIX relpath under the mirror root for one object."""
+    stem = f"{schema}.{name}" if schema else str(name)
+    return f"schema/{_safe(obj_type)}/{_safe(stem)}.sql"
+
+
+def write_mirror(out_dir: str | Path, records, *, full: bool = False,
+                 dry_run: bool = False) -> dict:
+    """Write/update the local mirror from `records`. Incremental by default:
+    only changed/new objects are written, orphaned files are removed, and a
+    `_manifest.json` of relpath->sha256 tracks state. Returns a summary dict.
+    """
+    out = Path(out_dir)
+    schema_root = out / "schema"
+    manifest_path = out / "_manifest.json"
+
+    desired: dict[str, str] = {}      # relpath -> definition text
+    by_type: dict[str, int] = {}
+    for r in records:
+        rel = mirror_relpath(r["type"], r.get("schema", "") or "", r["name"])
+        desired[rel] = r["definition"]
+        by_type[r["type"]] = by_type.get(r["type"], 0) + 1
+
+    prev: dict[str, str] = {}
+    if manifest_path.exists() and not full:
+        try:
+            prev = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            prev = {}
+
+    if full and not dry_run and schema_root.exists():
+        import shutil
+        shutil.rmtree(schema_root)
+        prev = {}
+
+    written = unchanged = removed = 0
+    new_manifest: dict[str, str] = {}
+    for rel, definition in sorted(desired.items()):
+        digest = sha256_text(definition)
+        new_manifest[rel] = digest
+        target = out / rel
+        is_same = prev.get(rel) == digest and (dry_run or target.exists())
+        if is_same and not full:
+            unchanged += 1
+            continue
+        written += 1
+        if not dry_run:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(definition, encoding="utf-8")
+
+    # remove orphans (in the old manifest but no longer desired)
+    for rel in sorted(set(prev) - set(desired)):
+        removed += 1
+        if not dry_run:
+            try:
+                (out / rel).unlink()
+            except OSError:
+                pass
+
+    if not dry_run:
+        out.mkdir(parents=True, exist_ok=True)
+        manifest_path.write_text(
+            json.dumps(new_manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    return {"out": str(out), "written": written, "unchanged": unchanged,
+            "removed": removed, "total": len(desired), "by_type": by_type,
+            "dry_run": dry_run, "manifest": str(manifest_path)}
+
+
+# ---------------------------------------------------------------------------
+# diff
+# ---------------------------------------------------------------------------
+
+def _mirror_files(mirror_dir: str | Path) -> dict[str, str]:
+    """relpath (posix, 'schema/...') -> file text, for every .sql under schema/."""
+    root = Path(mirror_dir) / "schema"
+    out: dict[str, str] = {}
+    if not root.is_dir():
+        return out
+    for p in root.rglob("*.sql"):
+        rel = p.relative_to(Path(mirror_dir)).as_posix()
+        try:
+            out[rel] = p.read_text(encoding="utf-8")
+        except OSError:
+            out[rel] = ""
+    return out
+
+
+def diff_mirrors(left_dir: str | Path, right_dir: str | Path, *,
+                 include_diff: bool = True) -> dict:
+    """Compare two schema mirrors. added = only in right, removed = only in left,
+    changed = present in both with differing content (with a unified diff)."""
+    left = _mirror_files(left_dir)
+    right = _mirror_files(right_dir)
+    added = sorted(set(right) - set(left))
+    removed = sorted(set(left) - set(right))
+    changed = []
+    for rel in sorted(set(left) & set(right)):
+        if left[rel] != right[rel]:
+            entry = {"relpath": rel}
+            if include_diff:
+                entry["diff"] = "".join(difflib.unified_diff(
+                    left[rel].splitlines(keepends=True),
+                    right[rel].splitlines(keepends=True),
+                    fromfile=f"left/{rel}", tofile=f"right/{rel}"))
+            changed.append(entry)
+    unchanged = len(set(left) & set(right)) - len(changed)
+    return {"added": added, "removed": removed, "changed": changed,
+            "unchanged": unchanged,
+            "identical": not added and not removed and not changed,
+            "summary": {"added": len(added), "removed": len(removed),
+                        "changed": len(changed)}}
+
+
+# ---------------------------------------------------------------------------
+# migrations
+# ---------------------------------------------------------------------------
+
+MIGRATION_FILE_RE = re.compile(r"^(\d{3,})_([a-z0-9][a-z0-9_\-]*)\.sql$", re.IGNORECASE)
+
+_DANGER_RE = re.compile(
+    r"\b(DROP\s+(TABLE|DATABASE|SCHEMA|COLUMN)|TRUNCATE\s+TABLE)\b", re.IGNORECASE)
+_UNQUALIFIED_RE = re.compile(
+    r"\b(UPDATE|DELETE)\b(?:(?!\bWHERE\b).)*?(;|\Z)", re.IGNORECASE | re.DOTALL)
+_GO_RE = re.compile(r"^\s*GO\s*$", re.IGNORECASE)
+
+
+def discover_migrations(migrations_dir: str | Path):
+    """Return [(mig_id, Path)] for NNNN_<slug>.sql files, ordered by the numeric
+    prefix. mig_id is the filename stem. Non-matching files are skipped (returned
+    separately so the caller can warn)."""
+    d = Path(migrations_dir)
+    found, skipped = [], []
+    if d.is_dir():
+        for p in sorted(d.iterdir()):
+            if p.is_file() and p.suffix.lower() == ".sql":
+                m = MIGRATION_FILE_RE.match(p.name)
+                (found if m else skipped).append((p.stem if m else p.name, p))
+    found.sort(key=lambda t: int(t[0].split("_", 1)[0]))
+    return found, [name for name, _ in skipped]
+
+
+def pending(applied_ids, migrations):
+    """migrations = [(mig_id, path)]; return those whose id is not in applied_ids."""
+    applied = set(applied_ids)
+    return [(mid, p) for (mid, p) in migrations if mid not in applied]
+
+
+def danger_warnings(sql: str) -> list[str]:
+    out = []
+    m = _DANGER_RE.search(sql)
+    if m:
+        out.append(f"destructive DDL: {m.group(0)}")
+    if _UNQUALIFIED_RE.search(sql):
+        out.append("possible UPDATE/DELETE without a WHERE clause")
+    return out
+
+
+def split_go_batches(sql: str) -> list[str]:
+    """Split a SQL Server script on lines that are exactly `GO` (case-insensitive).
+    Known limitation: a `GO` inside a string literal or block comment that sits
+    alone on a line is still treated as a separator."""
+    # Lines keep their own endings: SQL Server stores a CREATE/ALTER of a module verbatim, so
+    # rejoining with "\n" turned every CRLF-normalized migration into an LF-only definition.
+    batches, cur = [], []
+    for line in sql.splitlines(keepends=True):
+        if _GO_RE.match(line.rstrip("\r\n")):
+            batch = "".join(cur).strip()
+            if batch:
+                batches.append(batch)
+            cur = []
+        else:
+            cur.append(line)
+    batch = "".join(cur).strip()
+    if batch:
+        batches.append(batch)
+    return batches