procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/mysql/tests/test_mysql.py

@@ -0,0 +1,201 @@
+"""mysql dispatch + introspection tests against an injected fake cursor.
+
+No live DB and no pymysql are needed: we inject a ``conn_factory`` into
+``dispatch``. The connection-kwargs builder + masked DSN are tested directly
+(connection_kwargs imports pymysql only for the DictCursor class, which is
+present in the venv, but never opens a socket).
+"""
+from __future__ import annotations
+
+import datetime as dt
+import decimal
+
+import pytest
+
+from tools._lib import dbquery
+from tools.mysql import connection, main
+
+
+# --- fake DBAPI (DictCursor-style: rows are dicts) --------------------------
+
+class FakeCursor:
+    def __init__(self, description, rows):
+        self.description = description
+        self._rows = rows
+        self.executed = []
+        self.closed = False
+
+    def execute(self, sql, params=None):
+        self.executed.append((sql, params))
+
+    def fetchall(self):
+        return list(self._rows)
+
+    def close(self):
+        self.closed = True
+
+
+class FakeConn:
+    def __init__(self, queue):
+        self._queue = list(queue)
+        self.cursors = []
+        self.closed = False
+
+    def cursor(self):
+        cur = self._queue.pop(0)
+        self.cursors.append(cur)
+        return cur
+
+    def close(self):
+        self.closed = True
+
+
+def _factory(*cursors):
+    conn = FakeConn(cursors)
+    return lambda _profile: conn, conn
+
+
+@pytest.fixture
+def one_profile(tmp_path, monkeypatch):
+    from tools._lib import dbprofiles
+    pfile = tmp_path / "profiles.json"
+    monkeypatch.setattr(main, "PROFILES_PATH", pfile)
+    monkeypatch.setattr(dbprofiles.creds, "has", lambda *a: False)
+    monkeypatch.setattr(dbprofiles.creds, "get_optional", lambda *a: None)
+    main._store().add("default", {"host": "h", "database": "d", "username": "u"})
+    return pfile
+
+
+def test_dispatch_query_database_override(one_profile):
+    """--database overrides the profile's database, so ONE profile (one host +
+    login + credential) can query any database on that host."""
+    captured = {}
+    conn = FakeConn([FakeCursor(description=[], rows=[])])
+
+    def factory(profile):
+        captured["db"] = profile.get("database")
+        return conn
+
+    main.dispatch(
+        "query",
+        ["--profile", "default", "--sql", "SELECT 1", "--database", "OtherDB"],
+        conn_factory=factory,
+    )
+    assert captured["db"] == "OtherDB"      # overrode the profile's "d"
+
+
+# --- connection kwargs ------------------------------------------------------
+
+def test_connection_kwargs_basic():
+    profile = {"host": "h", "database": "d", "username": "u", "port": 3307}
+    k = connection.connection_kwargs(profile, "secret")
+    assert k["host"] == "h"
+    assert k["port"] == 3307
+    assert k["user"] == "u"
+    assert k["password"] == "secret"
+    assert k["database"] == "d"
+    assert k["autocommit"] is True
+    assert "ssl" not in k                       # tls off by default
+
+
+def test_connection_kwargs_tls_no_verify():
+    profile = {"host": "h", "tls": True, "tls_verify_cert": False}
+    k = connection.connection_kwargs(profile, "x")
+    ctx = k["ssl"]
+    assert ctx.check_hostname is False
+
+
+def test_masked_dsn_hides_password():
+    profile = {"host": "h", "database": "d", "username": "u"}
+    masked = connection.masked_dsn(profile)
+    assert ":***@" in masked
+    assert "mysql://u:***@h:3306/d" in masked
+
+
+# --- run_query: %s placeholders, dict rows, coercion ------------------------
+
+def test_run_query_binds_params_and_coerces():
+    cur = FakeCursor(
+        description=[("id", None), ("ts", None), ("amt", None)],
+        rows=[{"id": 1, "ts": dt.datetime(2026, 1, 1), "amt": decimal.Decimal("9.99")}],
+    )
+    out = connection.run_query(FakeConn([cur]),
+                               "SELECT * FROM t WHERE id = %s", [1], None)
+    assert cur.executed == [("SELECT * FROM t WHERE id = %s", [1])]
+    assert out["rows"][0]["ts"] == "2026-01-01T00:00:00"
+    assert out["rows"][0]["amt"] == "9.99"
+    assert out["truncated"] is False
+
+
+def test_run_query_truncates():
+    cur = FakeCursor(description=[("n", None)],
+                     rows=[{"n": i} for i in range(5)])
+    out = connection.run_query(FakeConn([cur]), "SELECT n FROM t", None, 2)
+    assert out["row_count"] == 2
+    assert out["truncated"] is True
+
+
+# --- dispatch ---------------------------------------------------------------
+
+def test_dispatch_query_read_only_ok(one_profile):
+    cur = FakeCursor(description=[("c", None)], rows=[{"c": 7}])
+    factory, conn = _factory(cur)
+    result = main.dispatch(
+        "query", ["--profile", "default", "--sql", "SELECT c FROM t"],
+        conn_factory=factory,
+    )
+    assert result["rows"] == [{"c": 7}]
+    assert result["write"] is False
+    assert conn.closed is True
+
+
+def test_dispatch_query_blocks_replace_upsert(one_profile):
+    # REPLACE is MySQL's upsert; the guard must block it read-only.
+    cur = FakeCursor(description=[], rows=[])
+    factory, _ = _factory(cur)
+    with pytest.raises(dbquery.WriteGuardError):
+        main.dispatch(
+            "query", ["--profile", "default", "--sql", "REPLACE INTO t VALUES (1)"],
+            conn_factory=factory,
+        )
+
+
+def test_dispatch_query_allows_write_flag(one_profile):
+    cur = FakeCursor(description=[], rows=[])
+    factory, _ = _factory(cur)
+    result = main.dispatch(
+        "query",
+        ["--profile", "default", "--sql", "DELETE FROM t WHERE id=%s",
+         "--params", "[1]", "--write"],
+        conn_factory=factory,
+    )
+    assert result["write"] is True
+
+
+def test_dispatch_tables_default_database(one_profile):
+    cur = FakeCursor(description=[("TABLE_NAME", None)], rows=[{"TABLE_NAME": "issues"}])
+    factory, _ = _factory(cur)
+    result = main.dispatch("tables", ["--profile", "default"], conn_factory=factory)
+    sql, params = cur.executed[0]
+    assert "DATABASE()" in sql                   # falls back to profile db
+    assert result["tables"][0]["TABLE_NAME"] == "issues"
+
+
+def test_dispatch_columns_parameterised(one_profile):
+    cur = FakeCursor(description=[("COLUMN_NAME", None)], rows=[{"COLUMN_NAME": "id"}])
+    factory, _ = _factory(cur)
+    main.dispatch("columns", ["--profile", "default", "--table", "redmine.issues"],
+                  conn_factory=factory)
+    sql, params = cur.executed[0]
+    assert "%s" in sql
+    assert params == ["issues", "redmine"]
+
+
+def test_dispatch_unknown_action():
+    with pytest.raises(main.UsageError):
+        main.dispatch("nope", [])
+
+
+def test_dispatch_missing_required_arg():
+    with pytest.raises(main.UsageError):
+        main.dispatch("query", ["--profile", "default"])     # no --sql

procesio_cli/tools/mysql/tests/test_mysql_schema.py

@@ -0,0 +1,337 @@
+"""schema-extract / schema-diff / migrate tests for the mysql tool.
+
+No live DB, no pymysql socket: a scripted fake connection answers the
+INFORMATION_SCHEMA enumeration + SHOW CREATE / tracking-table queries by
+matching on a substring of the SQL. Mirror writes go to tmp_path.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from tools._lib import dbschema
+from tools.mysql import main, schema
+
+
+# --- scripted fake DB-API (DictCursor: rows are dicts) ----------------------
+
+class FakeCursor:
+    def __init__(self, conn):
+        self.conn = conn
+        self._result: list[dict] = []
+        self.closed = False
+
+    def execute(self, sql, params=None):
+        self.conn.executed.append((sql, list(params) if params else None))
+        self._result = self.conn._answer(sql, params)
+
+    def fetchall(self):
+        return list(self._result)
+
+    def fetchone(self):
+        return self._result[0] if self._result else None
+
+    def close(self):
+        self.closed = True
+
+
+class FakeConn:
+    """Answers queries by scanning ``rules`` (substring -> rows or callable)."""
+
+    def __init__(self, rules):
+        self.rules = rules
+        self.executed: list[tuple] = []
+        self.began = 0
+        self.committed = 0
+        self.rolled_back = 0
+        self.closed = False
+
+    def _answer(self, sql, params):
+        for needle, value in self.rules:
+            if needle in sql:
+                return value(params) if callable(value) else list(value)
+        return []
+
+    def cursor(self):
+        return FakeCursor(self)
+
+    def begin(self):
+        self.began += 1
+
+    def commit(self):
+        self.committed += 1
+
+    def rollback(self):
+        self.rolled_back += 1
+
+    def close(self):
+        self.closed = True
+
+
+# --- extract_objects --------------------------------------------------------
+
+def _extract_rules():
+    return [
+        ("SELECT DATABASE()", [{"db": "redmine"}]),
+        ("TABLE_TYPE = %s",
+         lambda p: ([{"TABLE_NAME": "issues"}] if p and p[-1] == "BASE TABLE"
+                    else [{"TABLE_NAME": "v_open"}] if p and p[-1] == "VIEW" else [])),
+        ("ROUTINE_TYPE = %s",
+         lambda p: ([{"ROUTINE_NAME": "do_thing"}] if p and p[-1] == "PROCEDURE"
+                    else [{"ROUTINE_NAME": "calc"}] if p and p[-1] == "FUNCTION" else [])),
+        ("INFORMATION_SCHEMA.TRIGGERS", [{"TRIGGER_NAME": "trg_ins"}]),
+        ("INFORMATION_SCHEMA.EVENTS", [{"EVENT_NAME": "nightly"}]),
+        ("SHOW CREATE TABLE", [{"Table": "issues", "Create Table": "CREATE TABLE `issues` (\n  id int\n)"}]),
+        ("SHOW CREATE VIEW", [{"View": "v_open", "Create View": "CREATE VIEW `v_open` AS SELECT 1"}]),
+        ("SHOW CREATE PROCEDURE", [{"Procedure": "do_thing", "Create Procedure": "CREATE PROCEDURE do_thing() BEGIN END"}]),
+        ("SHOW CREATE FUNCTION", [{"Function": "calc", "Create Function": "CREATE FUNCTION calc() RETURNS INT RETURN 1"}]),
+        ("SHOW CREATE TRIGGER", [{"Trigger": "trg_ins", "SQL Original Statement": "CREATE TRIGGER trg_ins BEFORE INSERT ON issues FOR EACH ROW SET @x=1"}]),
+        ("SHOW CREATE EVENT", [{"Event": "nightly", "Create Event": "CREATE EVENT nightly ON SCHEDULE EVERY 1 DAY DO SELECT 1"}]),
+    ]
+
+
+def test_extract_objects_all_types():
+    conn = FakeConn(_extract_rules())
+    records = schema.extract_objects(conn)
+    by_type = {r["type"]: r for r in records}
+    assert set(by_type) == {"Tables", "Views", "Procedures", "Functions",
+                            "Triggers", "Events"}
+    assert by_type["Tables"]["name"] == "issues"
+    assert by_type["Tables"]["schema"] == "redmine"
+    assert by_type["Tables"]["definition"].startswith("CREATE TABLE `issues`")
+    # trigger uses the 'SQL Original Statement' key
+    assert by_type["Triggers"]["definition"].startswith("CREATE TRIGGER trg_ins")
+    # definitions are LF-normalized and newline-terminated
+    for r in records:
+        assert "\r" not in r["definition"]
+        assert r["definition"].endswith("\n")
+
+
+def test_extract_objects_types_filter():
+    conn = FakeConn(_extract_rules())
+    records = schema.extract_objects(conn, types="TABLE,VIEW")
+    assert {r["type"] for r in records} == {"Tables", "Views"}
+
+
+def test_create_value_falls_back_case_insensitive():
+    # MariaDB casing variant: 'create table' lowercase key
+    assert schema._create_value({"Table": "t", "create table": "CREATE TABLE t"},
+                                "Create Table") == "CREATE TABLE t"
+
+
+# --- schema-extract dispatch (conn_factory injection -> tmp_path) -----------
+
+@pytest.fixture
+def one_profile(tmp_path, monkeypatch):
+    from tools._lib import dbprofiles
+    pfile = tmp_path / "profiles.json"
+    monkeypatch.setattr(main, "PROFILES_PATH", pfile)
+    monkeypatch.setattr(dbprofiles.creds, "has", lambda *a: False)
+    monkeypatch.setattr(dbprofiles.creds, "get_optional", lambda *a: None)
+    main._store().add("default", {"host": "h", "database": "d", "username": "u"})
+    return pfile
+
+
+def test_schema_extract_dispatch_writes_mirror(one_profile, tmp_path):
+    out = tmp_path / "mirror"
+    conn = FakeConn(_extract_rules())
+    result = main.dispatch(
+        "schema-extract",
+        ["--profile", "default", "--out", str(out)],
+        conn_factory=lambda _p: conn,
+    )
+    assert result["written"] == 6
+    assert result["total"] == 6
+    assert result["by_type"]["Tables"] == 1
+    # files on disk + manifest
+    assert (out / "schema" / "Tables" / "redmine.issues.sql").is_file()
+    manifest = json.loads((out / "_manifest.json").read_text(encoding="utf-8"))
+    assert any("issues" in rel for rel in manifest)
+    assert conn.closed is True
+
+
+def test_schema_extract_dry_run_writes_nothing(one_profile, tmp_path):
+    out = tmp_path / "mirror"
+    conn = FakeConn(_extract_rules())
+    result = main.dispatch(
+        "schema-extract",
+        ["--profile", "default", "--out", str(out), "--dry-run"],
+        conn_factory=lambda _p: conn,
+    )
+    assert result["dry_run"] is True
+    assert result["written"] == 6
+    assert not out.exists()          # nothing written to disk
+
+
+def test_schema_extract_incremental_second_run(one_profile, tmp_path):
+    out = tmp_path / "mirror"
+    main.dispatch("schema-extract", ["--profile", "default", "--out", str(out)],
+                  conn_factory=lambda _p: FakeConn(_extract_rules()))
+    # second run, identical objects -> nothing written
+    result = main.dispatch("schema-extract", ["--profile", "default", "--out", str(out)],
+                           conn_factory=lambda _p: FakeConn(_extract_rules()))
+    assert result["written"] == 0
+    assert result["unchanged"] == 6
+
+
+# --- schema-diff dir-vs-dir (no DB) ----------------------------------------
+
+def _make_mirror(root: Path, files: dict[str, str]):
+    for rel, text in files.items():
+        p = root / "schema" / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text, encoding="utf-8")
+
+
+def test_schema_diff_dir_vs_dir(tmp_path):
+    left = tmp_path / "L"
+    right = tmp_path / "R"
+    _make_mirror(left, {"Tables/a.sql": "CREATE TABLE a (id int);\n",
+                        "Tables/gone.sql": "CREATE TABLE gone (id int);\n"})
+    _make_mirror(right, {"Tables/a.sql": "CREATE TABLE a (id bigint);\n",
+                         "Tables/new.sql": "CREATE TABLE new (id int);\n"})
+    result = main.dispatch("schema-diff", ["--left", str(left), "--right", str(right)])
+    assert result["summary"] == {"added": 1, "removed": 1, "changed": 1}
+    assert result["added"] == ["schema/Tables/new.sql"]
+    assert result["removed"] == ["schema/Tables/gone.sql"]
+    assert "bigint" in result["changed"][0]["diff"]
+
+
+def test_schema_diff_no_diff_text(tmp_path):
+    left = tmp_path / "L"
+    right = tmp_path / "R"
+    _make_mirror(left, {"Tables/a.sql": "x\n"})
+    _make_mirror(right, {"Tables/a.sql": "y\n"})
+    result = main.dispatch(
+        "schema-diff",
+        ["--left", str(left), "--right", str(right), "--no-diff-text"])
+    assert result["summary"]["changed"] == 1
+    assert "diff" not in result["changed"][0]
+
+
+def test_schema_diff_rejects_bad_dir(tmp_path):
+    left = tmp_path / "L"
+    _make_mirror(left, {"Tables/a.sql": "x\n"})
+    with pytest.raises(main.UsageError):
+        main.dispatch("schema-diff",
+                      ["--left", str(left), "--right", str(tmp_path / "nope")])
+
+
+# --- migrate: list + apply gating -------------------------------------------
+
+def _migrations_dir(tmp_path: Path) -> Path:
+    d = tmp_path / "migs"
+    d.mkdir()
+    (d / "0001_create_t.sql").write_text("CREATE TABLE t (id int);\n", encoding="utf-8")
+    (d / "0002_drop_t.sql").write_text("DROP TABLE t;\n", encoding="utf-8")
+    return d
+
+
+def _migrate_rules(applied_rows):
+    return [
+        ("information_schema.tables", [{"x": 1}]),   # tracking_table_exists -> exists
+        ("CREATE TABLE IF NOT EXISTS", []),          # ensure_migrations_table (apply only)
+        (f"FROM `{schema.MIGRATIONS_TABLE}`", applied_rows),  # fetch_applied
+    ]
+
+
+def test_migrate_list_pending_and_drift(one_profile, tmp_path):
+    d = _migrations_dir(tmp_path)
+    # 0001 already applied, but with a STALE sha -> drift
+    applied = [{"migration_id": "0001_create_t", "filename": "0001_create_t.sql",
+                "sha256": "deadbeef", "applied_at": None}]
+    conn = FakeConn(_migrate_rules(applied))
+    result = main.dispatch(
+        "migrate",
+        ["--profile", "default", "--dir", str(d), "--mode", "list"],
+        conn_factory=lambda _p: conn,
+    )
+    assert result["applied_count"] == 1
+    assert result["pending_count"] == 1
+    assert result["pending"][0]["migration_id"] == "0002_drop_t"
+    # 0002 drops a table -> danger warning surfaced
+    assert any("DROP" in w for w in result["pending"][0]["danger_warnings"])
+    assert result["drift"] == ["0001_create_t"]
+
+
+def test_migrate_list_is_read_only_when_table_absent(one_profile, tmp_path):
+    """`list` must NEVER create the tracking table (read-only on production DBs)."""
+    d = _migrations_dir(tmp_path)
+    conn = FakeConn([("information_schema.tables", [])])   # tracking table absent
+    result = main.dispatch(
+        "migrate", ["--profile", "default", "--dir", str(d), "--mode", "list"],
+        conn_factory=lambda _p: conn)
+    assert result["applied_count"] == 0 and result["pending_count"] == 2
+    assert not any("CREATE TABLE" in sql.upper() for sql, _ in conn.executed)
+
+
+def test_migrate_apply_requires_apply_flag(one_profile, tmp_path):
+    d = _migrations_dir(tmp_path)
+    conn = FakeConn(_migrate_rules([]))
+    with pytest.raises(main.UsageError) as ei:
+        main.dispatch(
+            "migrate",
+            ["--profile", "default", "--dir", str(d), "--mode", "apply"],
+            conn_factory=lambda _p: conn,
+        )
+    assert "--apply" in str(ei.value)
+
+
+def test_migrate_apply_runs_pending_and_records(one_profile, tmp_path):
+    d = _migrations_dir(tmp_path)
+    conn = FakeConn(_migrate_rules([]))
+    result = main.dispatch(
+        "migrate",
+        ["--profile", "default", "--dir", str(d), "--mode", "apply", "--apply"],
+        conn_factory=lambda _p: conn,
+    )
+    statuses = [r["status"] for r in result["applied_results"]]
+    assert statuses == ["applied", "applied"]
+    # two files applied -> two transactions committed + two tracking inserts
+    assert conn.committed == 2
+    inserts = [s for s, _ in conn.executed if "INSERT INTO" in s and schema.MIGRATIONS_TABLE in s]
+    assert len(inserts) == 2
+
+
+def test_migrate_apply_dry_run_rolls_back(one_profile, tmp_path):
+    d = _migrations_dir(tmp_path)
+    conn = FakeConn(_migrate_rules([]))
+    result = main.dispatch(
+        "migrate",
+        ["--profile", "default", "--dir", str(d), "--mode", "apply",
+         "--apply", "--dry-run"],
+        conn_factory=lambda _p: conn,
+    )
+    assert all(r["status"] == "dry-run" for r in result["applied_results"])
+    assert conn.rolled_back == 2
+    assert conn.committed == 0
+    # no tracking inserts on dry-run
+    assert not any("INSERT INTO" in s and schema.MIGRATIONS_TABLE in s
+                   for s, _ in conn.executed)
+
+
+def test_migrate_apply_refuses_on_drift(one_profile, tmp_path):
+    d = _migrations_dir(tmp_path)
+    applied = [{"migration_id": "0001_create_t", "filename": "0001_create_t.sql",
+                "sha256": "stale", "applied_at": None}]
+    conn = FakeConn(_migrate_rules(applied))
+    with pytest.raises(main.UsageError) as ei:
+        main.dispatch(
+            "migrate",
+            ["--profile", "default", "--dir", str(d), "--mode", "apply", "--apply"],
+            conn_factory=lambda _p: conn,
+        )
+    assert "drift" in str(ei.value).lower()
+
+
+# --- shared dbschema migration helpers (sanity, no DB) ----------------------
+
+def test_discover_and_pending(tmp_path):
+    d = _migrations_dir(tmp_path)
+    found, skipped = dbschema.discover_migrations(d)
+    assert [mid for mid, _ in found] == ["0001_create_t", "0002_drop_t"]
+    assert skipped == []
+    pend = dbschema.pending({"0001_create_t"}, found)
+    assert [mid for mid, _ in pend] == ["0002_drop_t"]

procesio_cli/tools/mysql/tool.yaml

@@ -0,0 +1,112 @@
+name: mysql
+description: Read-only MySQL/MariaDB queries over pymysql with named connection profiles. SELECT-only by default (--write to override); returns rows as JSON; schema/table introspection. MySQL has no read-only intent, so the write-guard is the enforcement.
+version: 0.1.0
+runtime: python
+entrypoint: main.py
+
+# Secrets are PER-PROFILE and dynamic, so none are declared here.
+# Each profile's password lives in Windows Credential Manager under
+# agents-and-tools:mysql:<profile-name> and is read at runtime via
+# tools._lib.creds.get("mysql", <profile>). Set one with:
+#   python scripts/set-credential.py mysql <profile>
+# Non-secret profile config (host/database/username/port/charset/tls) lives in
+# this tool's profiles.json — never the password.
+secrets: []
+
+routing:
+  triggers:
+    - run a MySQL query
+    - query a MySQL / MariaDB database
+    - read a table from MySQL
+    - list MySQL tables or columns
+  primary_action: query
+  example: mysql query --profile default --sql "SELECT * FROM issues LIMIT 10"
+
+actions:
+  - name: profiles
+    description: List configured connection profiles (no passwords).
+    args: []
+    output_schema: '{ "count": N, "profiles": [ {name, host, database, ..., has_password} ] }'
+
+  - name: add-profile
+    description: Store a connection profile (config only; set the password separately via set-credential).
+    args:
+      - {name: name, type: string, required: true, description: Profile name (also the credential name)}
+      - {name: host, type: string, required: true, description: MySQL host}
+      - {name: database, type: string, description: Default schema/database}
+      - {name: username, type: string, description: MySQL user (default root)}
+      - {name: port, type: integer, description: TCP port (default 3306)}
+      - {name: charset, type: string, description: Connection charset (default utf8mb4)}
+      - {name: tls, type: string, description: Wrap the socket in TLS - yes or no (default no)}
+      - {name: tls-verify-cert, type: string, description: Verify the server cert chain - yes or no (default no)}
+      - {name: connect-timeout, type: integer, description: Connect timeout seconds (default 30)}
+      - {name: statement-timeout, type: integer, description: "Read/statement timeout seconds, 0=unbounded (default 300)"}
+      - {name: overwrite, type: boolean, description: Replace an existing profile}
+    output_schema: '{ "name": "...", "host": "...", "has_password": false, "note": "..." }'
+
+  - name: test-connection
+    description: Connect and return the masked connection string + server version (never the password).
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+    output_schema: '{ "profile": "...", "connection_string": "mysql://user:***@host...", "server_version": "...", "connected": true }'
+
+  - name: query
+    description: Run read-only SQL (SELECT by default; --write allows non-SELECT). Params bound via %s placeholders, never interpolated.
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: sql, type: string, required: true, description: SQL statement}
+      - {name: params, type: string, description: "Parameter values as a JSON array, bound via %s placeholders"}
+      - {name: max-rows, type: integer, description: Cap rows returned (default 1000; 0=unbounded)}
+      - {name: write, type: boolean, description: Allow a non-SELECT/DDL/multi statement (off by default)}
+      - {name: database, type: string, description: Run against this database instead of the profile's}
+    output_schema: '{ "columns": [...], "rows": [ {...} ], "row_count": N, "truncated": false, "write": false }'
+
+  - name: tables
+    description: List tables and views, optionally restricted to one schema.
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: database, type: string, description: List tables from this database instead of the profile's}
+      - {name: schema, type: string, description: Restrict to one schema (default the profile's database)}
+    output_schema: '{ "profile": "...", "count": N, "tables": [ {TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE} ] }'
+
+  - name: columns
+    description: List a table's columns (name, type, nullable, key, length, default).
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: database, type: string, description: Read columns from this database instead of the profile's}
+      - {name: table, type: string, required: true, description: Table name (schema.table or table)}
+    output_schema: '{ "profile": "...", "table": "...", "count": N, "columns": [ {COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_KEY, ...} ] }'
+
+  - name: schema-extract
+    description: "Mirror every object in the database to local .sql files (one per object) under <out>/schema/<Type>/. Read-only and incremental: a re-run with no changes writes nothing."
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: database, type: string, description: Extract this database instead of the profile's}
+      - {name: out, type: string, description: "Mirror output directory (default ./db-mirror/<profile>)"}
+      - {name: types, type: string, description: "Comma list of object types to include: TABLE,VIEW,PROCEDURE,FUNCTION,TRIGGER,EVENT (default all)"}
+      - {name: full, type: boolean, description: "Wipe and re-extract everything (default: incremental)"}
+      - {name: dry-run, type: boolean, description: Report what would change without writing}
+    output_schema: '{ "profile": "...", "database": "...", "out": "...", "written": N, "unchanged": N, "removed": N, "total": N, "by_type": {}, "dry_run": false }'
+
+  - name: schema-diff
+    description: "Compare two schema sides and report objects added/removed/changed with a unified diff per change. Each side is a mirror directory OR profile:NAME (extracted live to a temp mirror). Read-only end to end."
+    args:
+      - {name: left, type: string, required: true, description: "A mirror directory OR profile:NAME to extract live"}
+      - {name: right, type: string, required: true, description: "A mirror directory OR profile:NAME to extract live"}
+      - {name: database-left, type: string, description: "DB override when --left is a profile"}
+      - {name: database-right, type: string, description: "DB override when --right is a profile"}
+      - {name: types, type: string, description: "Comma list of object types to include when a side is a profile"}
+      - {name: no-diff-text, type: boolean, description: "Suppress per-object unified diff bodies (name lists only)"}
+    output_schema: '{ "left": "...", "right": "...", "added": [], "removed": [], "changed": [ {relpath, diff} ], "unchanged": N, "identical": false, "summary": {added, removed, changed} }'
+
+  - name: migrate
+    description: "Forward-only versioned migration runner. mode=list (default, read-only) shows applied/pending + drift + danger warnings; mode=apply (gated by --apply) runs pending in order, recording each in __schema_migrations. --dry-run wraps each in a rolled-back transaction. DELIMITER caveat: each file runs as a single statement."
+    args:
+      - {name: profile, type: string, required: true, description: Profile name}
+      - {name: database, type: string, description: Migrate this database instead of the profile's}
+      - {name: dir, type: string, description: "Migrations directory (default ./db-migrations/<profile>)"}
+      - {name: mode, type: string, description: "list (read-only, default) or apply (writes)"}
+      - {name: dry-run, type: boolean, description: Apply each pending migration in a rolled-back transaction}
+      - {name: apply, type: boolean, description: "Required confirmation to actually write (with --mode apply)"}
+      - {name: accept-drift, type: boolean, description: Proceed with apply even if applied files changed on disk}
+    output_schema: '{ "profile": "...", "database": "...", "dir": "...", "mode": "list", "applied_count": N, "pending": [ {migration_id, filename, sha256, danger_warnings} ], "drift": [], "applied_results": [] }'