procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/framework-map/tests/test_fm_store_tree.py

@@ -0,0 +1,75 @@
+"""The user-data tree in the map must list what the resolvers actually create.
+
+fm_builder._store_tree used to read the REAL folders off the local disk so a new
+subfolder could never be omitted. That made a VERSIONED artifact depend on whose
+machine built it. The list is canonical now, so this test carries the guarantee
+the disk read used to: create a user-data root through tools/_lib/userdata and
+assert the canonical list matches the directories that appear.
+
+Add a resolver to userdata (or a folder to _CANON_FOLDERS) and this test tells
+you the other half is missing, at build time rather than in someone's diff.
+"""
+from __future__ import annotations
+
+import pytest
+
+import fm_builder
+import fm_strings
+
+from tools._lib import userdata
+
+
+def _make_every_userdata_dir(component: str = "probe") -> None:
+    """Call every directory resolver userdata exposes, so each folder is created."""
+    userdata.state_dir(component)
+    userdata.config_dir(component)
+    userdata.prompts_dir(component)
+    userdata.sessions_dir()
+    userdata.exports_dir()
+    userdata.schedule_dir()
+    userdata.store_db_path()          # parent only; the file itself is not created
+
+
+def test_canonical_folders_match_what_userdata_creates(tmp_path, monkeypatch):
+    monkeypatch.setenv("AAT_USERDATA_DIR", str(tmp_path / "ud"))
+    monkeypatch.delenv("AAT_USER_ID", raising=False)
+    monkeypatch.delenv("AAT_WORKSPACE_ID", raising=False)
+
+    _make_every_userdata_dir()
+
+    live = {p.name for p in userdata.base().iterdir() if p.is_dir()}
+    assert live == set(fm_builder._CANON_FOLDERS), (
+        "fm_builder._CANON_FOLDERS is out of step with tools/_lib/userdata: "
+        f"only on disk={sorted(live - set(fm_builder._CANON_FOLDERS))}, "
+        f"only in the list={sorted(set(fm_builder._CANON_FOLDERS) - live)}")
+
+
+# The store panel is part of the architecture narrative, which not every
+# distribution of the framework ships. Where its copy is absent there is nothing
+# to assert about it, so these skip rather than fail.
+requires_store_copy = pytest.mark.skipif(
+    "sc1_h" not in fm_strings.S["en"],
+    reason="this distribution does not ship the store panel copy")
+
+@requires_store_copy
+def test_every_canonical_folder_is_described_in_both_languages():
+    """A folder with no description renders as a bare name with a blank column."""
+    for lang in ("en", "ro"):
+        S = fm_builder.fm_strings.S[lang]
+        described = ({"config": S["tc_config"], "sessions": S["tc_sessions"],
+                      "schedule": S["tc_schedule"]} | fm_builder._FOLDER_EXTRA[lang])
+        missing = [f for f in fm_builder._CANON_FOLDERS if not described.get(f)]
+        assert not missing, f"{lang}: folders with no description: {missing}"
+
+
+@requires_store_copy
+def test_store_tree_is_independent_of_the_local_user_data_folder(tmp_path, monkeypatch):
+    """The whole point: same bytes on a machine with user data and on a clean one."""
+    monkeypatch.setenv("AAT_USERDATA_DIR", str(tmp_path / "empty"))
+    clean = fm_builder._store_tree("en")
+
+    populated_root = tmp_path / "populated"
+    monkeypatch.setenv("AAT_USERDATA_DIR", str(populated_root))
+    _make_every_userdata_dir()
+    (populated_root / "a-folder-someone-added-locally").mkdir()
+    assert fm_builder._store_tree("en") == clean

procesio_cli/tools/framework-map/tool.yaml

@@ -0,0 +1,61 @@
+name: framework-map
+description: >-
+  Regenerate the interactive, bilingual (EN default / RO) framework map - a
+  single self-contained HTML file that visualises every tool, agent, skill and
+  action from the live registry (drillable to the argument level), plus the
+  orchestration loop, the who-triggers-what diagram, schedules, the
+  context/state/knowledge store and worked use cases. Built for presenting the
+  Agents-and-Tools framework to a team.
+version: 0.1.0
+runtime: python
+entrypoint: main.py
+
+actions:
+  - name: build
+    description: >-
+      Extract the live registry, compress it, apply the RO catalog translations
+      (falling back to English where a translation is missing), assemble the
+      single-file HTML, and write it. Reports counts, category breakdown, and any
+      catalog strings still awaiting an RO translation.
+    args:
+      - name: out
+        type: string
+        required: false
+        default: framework-map.html
+        description: Output path for the HTML file. Relative paths resolve from the repo root.
+    output_schema: |
+      { "path": "string", "bytes": int, "tools": int, "agents": int,
+        "skills": int, "actions": int, "tool_actions": int, "agent_actions": int,
+        "categories": { "<name>": int }, "uncategorized": ["string"],
+        "ro_untranslated": { "tool_desc": [], "triggers": [], "agent_desc": [],
+                             "skill_desc": [], "category": [] } }
+    examples:
+      - cmd: python scripts/run-tool.py framework-map build
+        output: '{"path": ".../framework-map.html", "bytes": 1280000, "tools": 44, "agents": 8, "skills": 12, "actions": 1500, ...}'
+      - cmd: python scripts/run-tool.py framework-map build --out outputs/map.html
+        output: '{"path": ".../outputs/map.html", "bytes": 1280000, ...}'
+
+  - name: check
+    description: >-
+      Report current counts, the category breakdown, any uncategorized tools, and
+      any catalog strings (tool/agent/skill descriptions, triggers, categories)
+      still missing an RO translation. Writes nothing - use before build to see
+      what a new tool/agent needs.
+    output_schema: |
+      { "tools": int, "agents": int, "skills": int, "actions": int,
+        "categories": {}, "uncategorized": [], "ro_untranslated": {} }
+    examples:
+      - cmd: python scripts/run-tool.py framework-map check
+        output: '{"tools": 44, "agents": 8, "skills": 12, "actions": 1500, "ro_untranslated": {}}'
+
+secrets: []
+
+routing:
+  triggers:
+    - regenerate / rebuild the framework map or the agents-and-tools visualization
+    - update the framework HTML with the new tools / agents / mechanics
+    - refresh the agents and tools diagram / presentation page
+    - which tools or agents changed / still need an RO translation
+    - build the bilingual framework map (EN/RO)
+  primary_action: build
+  example: "framework-map build   (dry-run counts + untranslated: framework-map check)"

procesio_cli/tools/mysql/MOVED-TO-CENTRAL.md

@@ -0,0 +1,29 @@
+# profiles.json moved to the central user-data folder
+
+`tools/mysql/profiles.json` is no longer here. User-specific connection profiles
+now live in the central, git-ignored user-data folder so the framework stays free
+of user data (hand the repo to someone else, wipe that folder, done).
+
+New location (resolved by `tools/_lib/userdata.py`):
+
+```
+context-state-knowledge/config/mysql/profiles.json
+```
+
+Override the root with the `AAT_USERDATA_DIR` environment variable. Passwords were
+never in this file - they remain in Windows Credential Manager under
+`agents-and-tools:mysql:<profile>`.
+
+The tool resolves the path via `userdata.config_dir("mysql")`; nothing else
+changes. Add/list profiles exactly as before (`run-tool.py mysql add-profile ...`).
+
+**Fresh install / wiped user data?** `profiles.template.json` here seeds an EMPTY
+`{}` on purpose: in this format every top-level key is a live profile, so a
+placeholder entry would show up in `profiles`, get suggested by error hints, and
+invite credentials for a fake host. Use `add-profile`, which builds the file:
+
+```bash
+python scripts/run-tool.py mysql add-profile --name myprofile \
+  --host db.example.com --port 3306 --database mydb --username user --tls
+python scripts/set-credential.py mysql myprofile   # password -> CredMan
+```

procesio_cli/tools/mysql/README.md

@@ -0,0 +1,196 @@
+# mysql
+
+Read-only **MySQL / MariaDB** queries over `pymysql`, with named connection
+profiles. SELECT-only by default; `--write` is required (and gated by the shared
+guard) for any non-SELECT. JSON in / JSON out.
+
+> MySQL has no `ApplicationIntent=ReadOnly` equivalent, so for this engine the
+> **write-guard is the read-only enforcement**. Its keyword list is the superset
+> of both engines (adds `REPLACE`, `CALL`, `LOAD`, `LOCK`, `RENAME`, …).
+
+## Credentials (the model)
+
+A profile splits into two halves:
+
+- **Non-secret config** (host, database, username, port, charset, TLS flags,
+  timeouts) lives in `tools/mysql/profiles.json`. Never a password.
+- **The password** lives ONLY in Windows Credential Manager, under the target
+  `agents-and-tools:mysql:<profile-name>` — the secret name **is** the profile
+  name. Read at runtime via `creds.get("mysql", <profile>)`.
+
+For a profile named `default`, set its password with:
+
+```powershell
+python scripts/set-credential.py mysql default
+```
+
+If it's missing, DB actions fail with code `auth_required` and that exact hint.
+
+## Actions
+
+```powershell
+# List profiles (no passwords). Works with no DB and no driver installed.
+python scripts/run-tool.py mysql profiles
+
+# Add a profile (config only — password set separately, see above).
+python scripts/run-tool.py mysql add-profile `
+  --name default --host 10.0.0.5 --database redmine --username readonly --tls yes
+
+# Connectivity check: masked DSN + server version (never the password).
+python scripts/run-tool.py mysql test-connection --profile default
+
+# Read-only query. Params are bound via %s placeholders, never interpolated.
+python scripts/run-tool.py mysql query --profile default `
+  --sql "SELECT * FROM issues WHERE project_id = %s LIMIT 10" --params '[3]'
+
+# A write needs the explicit flag (still gated, still parameterised):
+python scripts/run-tool.py mysql query --profile default `
+  --sql "DELETE FROM cache WHERE id = %s" --params '[7]' --write
+
+# Schema introspection (defaults to the profile's database).
+python scripts/run-tool.py mysql tables  --profile default
+python scripts/run-tool.py mysql columns --profile default --table issues
+```
+
+## Multiple databases (one profile, many DBs)
+
+`--database` is just the **default schema** and is optional — one profile (one host +
+login + credential) already reaches every database on the host. Pick one per call:
+
+```powershell
+python scripts/run-tool.py mysql query   --profile prod --database redmine   --sql "SELECT * FROM issues LIMIT 5"
+python scripts/run-tool.py mysql tables  --profile prod --database wordpress
+python scripts/run-tool.py mysql columns --profile prod --database wordpress --table wp_posts
+```
+
+`--database` sets the connection's default schema for that call, so `tables`/`columns`
+introspect it and unqualified names resolve to it. You can also reach another schema
+inline with a qualified name (`SELECT * FROM otherdb.t`) if the login has grants.
+Prefer one named profile per database? That works too — both styles are fine.
+
+## Schema mirror, diff & migrations
+
+Three actions extend the tool from "query a DB" to "version a DB's schema". They
+share the engine-agnostic machinery in `tools/_lib/dbschema.py`; the MySQL-specific
+half (catalog enumeration, `SHOW CREATE`, the `__schema_migrations` table) lives in
+`tools/mysql/schema.py`.
+
+### `schema-extract` — mirror every object to local `.sql` files (read-only)
+
+Writes one file per object under `<out>/schema/<Type>/<schema>.<name>.sql` plus a
+`_manifest.json` of `relpath -> sha256`. **Incremental** by default — a re-run with no
+schema changes writes nothing. Read-only (only `SELECT` / `SHOW CREATE`).
+
+```powershell
+# Mirror the profile's database to ./db-mirror/<profile>/
+python scripts/run-tool.py mysql schema-extract --profile default
+
+# Pick a database, a subset of object types, and a custom output dir.
+python scripts/run-tool.py mysql schema-extract --profile prod `
+  --database redmine --types TABLE,VIEW,PROCEDURE --out .\mirrors\redmine
+
+# See what would change without touching disk.
+python scripts/run-tool.py mysql schema-extract --profile default --dry-run
+
+# Force a clean re-extract.
+python scripts/run-tool.py mysql schema-extract --profile default --full
+```
+
+`--types` accepts any of `TABLE,VIEW,PROCEDURE,FUNCTION,TRIGGER,EVENT`. Returns
+`{profile, database, out, written, unchanged, removed, total, by_type, dry_run}`.
+
+### `schema-diff` — compare two schema sides (read-only)
+
+Each side is **either** a mirror directory **or** `profile:NAME` (extracted live to a
+temp mirror first). Reports objects added / removed / changed, with a unified diff per
+change (suppress bodies with `--no-diff-text`).
+
+```powershell
+# Two already-extracted mirrors.
+python scripts/run-tool.py mysql schema-diff --left .\mirrors\dev --right .\mirrors\rel
+
+# Live: same profile, two databases on the host.
+python scripts/run-tool.py mysql schema-diff `
+  --left profile:prod --database-left app_dev `
+  --right profile:prod --database-right app_release
+
+# Just the changed/added/removed name lists (no diff bodies).
+python scripts/run-tool.py mysql schema-diff --left .\a --right .\b --no-diff-text
+```
+
+Returns `{left, right, added[], removed[], changed[{relpath, diff}], unchanged,
+identical, summary}`. Read-only end to end.
+
+### `migrate` — forward-only versioned migration runner
+
+Applies pending `NNNN_<slug>.sql` files in numeric order, tracking applied state in a
+`__schema_migrations` table inside the target DB. `list` (the default) is read-only;
+`apply` is the **only writer** and is gated behind `--apply`.
+
+```powershell
+# List applied vs pending + drift + danger warnings (read-only).
+python scripts/run-tool.py mysql migrate --profile default --dir .\db-migrations\app
+
+# Validate without persisting: each migration runs in a rolled-back transaction.
+python scripts/run-tool.py mysql migrate --profile default --dir .\db-migrations\app `
+  --mode apply --apply --dry-run
+
+# Actually apply pending migrations (requires --apply).
+python scripts/run-tool.py mysql migrate --profile default --dir .\db-migrations\app `
+  --mode apply --apply
+```
+
+- Default `--dir` is `./db-migrations/<profile>`.
+- `apply` **refuses to run on drift** (an applied migration whose file `sha256` changed
+  on disk) unless `--accept-drift` is passed.
+- Each file runs in its own transaction; the runner **stops on the first error**.
+- `danger_warnings` (DROP/TRUNCATE TABLE, unqualified UPDATE/DELETE) are surfaced per
+  pending file but do **not** block.
+
+**DELIMITER / multi-statement caveat (important):** MySQL stored-routine bodies contain
+semicolons, so a migration file is executed as a **single statement** — there is no
+client-side `;`-splitting and no `DELIMITER` handling. Author each migration as **one
+statement per file** (e.g. a single `CREATE PROCEDURE ... BEGIN ... END` with **no**
+`DELIMITER` lines, or one plain DDL statement). Files with several `;`-separated plain
+statements, or `DELIMITER`-wrapped bodies, are **not** supported in one file. (`GO`
+batch-splitting is SQL-Server-only and is not used here.)
+
+> **Safety:** `schema-extract`, `schema-diff`, and `migrate --mode list` are read-only.
+> `migrate --mode apply` is the only write path and requires the explicit `--apply` flag.
+
+## add-profile options
+
+| flag | default | notes |
+|------|---------|-------|
+| `--name` | — (required) | profile + credential name |
+| `--host` | — (required) | |
+| `--database` | login default | default schema (optional); override per call with `query/tables/columns --database` |
+| `--username` | `root` | |
+| `--port` | `3306` | |
+| `--charset` | `utf8mb4` | |
+| `--tls` | `no` | `yes`/`no` — wrap the socket in TLS |
+| `--tls-verify-cert` | `no` | `yes`/`no` — verify the server cert chain |
+| `--connect-timeout` | `30` | seconds |
+| `--statement-timeout` | `300` | read timeout, seconds, `0` = unbounded |
+| `--overwrite` | off | replace an existing profile |
+
+## Safety
+
+- **Read-only by default** — `INSERT/UPDATE/DELETE/REPLACE/MERGE/TRUNCATE/ALTER/
+  CREATE/DROP/GRANT/CALL/LOAD/LOCK/…` and multi-statement batches are rejected
+  unless `--write` is passed. The guard lives in `tools/_lib/dbquery.py`.
+- Values are always **parameterised** (`%s`), never spliced into the SQL.
+- A **max-rows cap** (`--max-rows`, default 1000) returns a `truncated` flag.
+- TLS without cert-verification encrypts the channel for IP-only hosts (the
+  SQL-Server `TrustServerCertificate=yes` analogue).
+
+## Dependencies
+
+`pymysql` + `cryptography` (the latter for MySQL 8 `caching_sha2_password`).
+Imported lazily — if absent, DB actions fail with `missing_dependency`;
+`profiles` / `add-profile` keep working.
+
+## Errors
+
+`invalid_argument` (2), `auth_required`, `write_blocked` (2),
+`missing_dependency`, `db_error`, `error`.

procesio_cli/tools/mysql/SKILL.md

@@ -0,0 +1,37 @@
+---
+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.
+---
+
+# mysql
+
+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.
+
+## How to call it
+
+```bash
+python scripts/run-tool.py mysql <action> [--args]
+# e.g. mysql query --profile default --sql "SELECT * FROM issues LIMIT 10"
+```
+
+One JSON object on stdout for success; `{"error": {"code", "message", "details"}}` and a non-zero exit on failure. Progress and logs go to stderr only.
+
+**Start with `query`.**
+
+## Actions
+
+| action | required args | what it does |
+|---|---|---|
+| `add-profile` | `--name`, `--host` | Store a connection profile (config only; set the password separately via set-credential). |
+| `columns` | `--profile`, `--table` | List a table's columns (name, type, nullable, key, length, default). |
+| `migrate` | `--profile` | Forward-only versioned migration runner. mode=list (default, read-only) shows applied/pending + drift + danger warnings; mode=apply (gated by --apply) runs… |
+| `profiles` | — | List configured connection profiles (no passwords). |
+| `query` | `--profile`, `--sql` | Run read-only SQL (SELECT by default; --write allows non-SELECT). Params bound via %s placeholders, never interpolated. |
+| `schema-diff` | `--left`, `--right` | 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… |
+| `schema-extract` | `--profile` | 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… |
+| `tables` | `--profile` | List tables and views, optionally restricted to one schema. |
+| `test-connection` | `--profile` | Connect and return the masked connection string + server version (never the password). |
+
+---
+
+Generated from `tools/mysql/tool.yaml` by `scripts/build-tool-skill.py`. Do not edit by hand — change the manifest and regenerate.

procesio_cli/tools/mysql/connection.py

@@ -0,0 +1,191 @@
+"""pymysql connection factory + query layer for the `mysql` tool.
+
+Lazy driver import: pymysql is only imported when a connection is opened, so
+`add-profile` / `profiles` work without it. If pymysql is missing we raise
+``MissingDependencyError`` (mapped to ``missing_dependency``) with an install
+hint.
+
+MySQL has no ApplicationIntent=ReadOnly equivalent, so read-only is enforced
+by the shared write-guard in dbquery (the dispatch layer calls it before any
+statement runs). A profile's NON-SECRET config (from profiles.json):
+  host     (required)
+  database (optional)  default schema
+  username (optional)  default 'root'
+  port     (optional)  default 3306
+  charset  (optional)  default 'utf8mb4'
+  tls                  bool, default False (wrap socket in TLS)
+  tls_verify_cert      bool, default False (verify the server cert chain)
+  connect_timeout      seconds, default 30
+  statement_timeout    seconds, default 300 (read timeout; 0 = unbounded)
+The password comes from Credential Manager (never the file).
+"""
+from __future__ import annotations
+
+import ssl as _ssl
+from typing import Any
+
+from tools._lib import dbquery
+
+DEFAULT_PORT = 3306
+DEFAULT_USERNAME = "root"
+DEFAULT_CHARSET = "utf8mb4"
+DEFAULT_CONNECT_TIMEOUT = 30
+DEFAULT_STATEMENT_TIMEOUT = 300
+
+
+class MissingDependencyError(Exception):
+    """pymysql not installed. -> missing_dependency."""
+
+
+class DBError(Exception):
+    """A driver-level error opening/executing. -> db_error."""
+
+
+def _import_pymysql():
+    try:
+        import pymysql  # noqa: PLC0415
+        import pymysql.cursors  # noqa: PLC0415
+    except ImportError as e:  # pragma: no cover - depends on host
+        raise MissingDependencyError(
+            "pymysql is not installed. Install with:\n"
+            "    uv pip install pymysql cryptography\n"
+            "(cryptography is needed for MySQL 8 caching_sha2_password auth)."
+        ) from e
+    return pymysql
+
+
+def _ssl_context(profile: dict):
+    if not profile.get("tls"):
+        return None
+    ctx = _ssl.create_default_context()
+    if not profile.get("tls_verify_cert", False):
+        ctx.check_hostname = False
+        ctx.verify_mode = _ssl.CERT_NONE
+    return ctx
+
+
+def connection_kwargs(profile: dict, password: str | None) -> dict:
+    """Build pymysql.connect kwargs (password included when given)."""
+    host = profile.get("host")
+    if not host:
+        raise DBError("profile is missing 'host'")
+    pymysql = _import_pymysql()
+    kwargs: dict[str, Any] = {
+        "host": host,
+        "port": int(profile.get("port", DEFAULT_PORT)),
+        "user": profile.get("username", DEFAULT_USERNAME),
+        "charset": profile.get("charset", DEFAULT_CHARSET),
+        "autocommit": True,
+        "cursorclass": pymysql.cursors.DictCursor,
+        "connect_timeout": int(profile.get("connect_timeout", DEFAULT_CONNECT_TIMEOUT)),
+        "read_timeout": int(profile.get("statement_timeout", DEFAULT_STATEMENT_TIMEOUT)),
+    }
+    if profile.get("database"):
+        kwargs["database"] = profile["database"]
+    if password is not None:
+        kwargs["password"] = password
+    ctx = _ssl_context(profile)
+    if ctx is not None:
+        kwargs["ssl"] = ctx
+    return kwargs
+
+
+def masked_dsn(profile: dict) -> str:
+    """A human-readable, password-free connection summary - safe to return/log."""
+    host = profile.get("host", "?")
+    port = int(profile.get("port", DEFAULT_PORT))
+    user = profile.get("username", DEFAULT_USERNAME)
+    database = profile.get("database", "")
+    tls = "on" if profile.get("tls") else "off"
+    dsn = f"mysql://{user}:***@{host}:{port}/{database}?charset={profile.get('charset', DEFAULT_CHARSET)}&tls={tls}"
+    return dbquery.mask_dsn(dsn)
+
+
+def connect(profile: dict, password: str | None):
+    """Open a pymysql connection for `profile`."""
+    pymysql = _import_pymysql()
+    kwargs = connection_kwargs(profile, password)
+    try:
+        return pymysql.connect(**kwargs)
+    except pymysql.Error as e:  # pragma: no cover - needs a live server
+        raise DBError(str(e)) from e
+
+
+# ---------------------------------------------------------------------------
+# Query + introspection. Each takes a connection-like object so tests can
+# inject a fake. The write-guard is enforced by the dispatch layer.
+# ---------------------------------------------------------------------------
+
+def run_query(
+    conn,
+    sql: str,
+    params: list | tuple | None,
+    max_rows: int | None,
+) -> dict:
+    """Execute one SQL statement; return {columns, rows, row_count, truncated}.
+
+    `params` are passed to ``cursor.execute`` (pymysql uses ``%s`` placeholders);
+    they are never string-interpolated into `sql`.
+    """
+    cur = conn.cursor()
+    try:
+        if params:
+            cur.execute(sql, list(params))
+        else:
+            cur.execute(sql)
+        columns = dbquery.column_names(cur)
+        raw = cur.fetchall() if columns else []
+        capped, truncated = dbquery.cap_rows(list(raw), max_rows)
+        rows = dbquery.rows_to_dicts(columns, capped)
+    finally:
+        try:
+            cur.close()
+        except Exception:  # noqa: BLE001
+            pass
+    return {
+        "columns": columns,
+        "rows": rows,
+        "row_count": len(rows),
+        "truncated": truncated,
+    }
+
+
+def server_version(conn) -> str:
+    out = run_query(conn, "SELECT VERSION() AS version", None, None)
+    rows = out["rows"]
+    return str(rows[0].get("version", "")) if rows else ""
+
+
+def list_tables(conn, schema: str | None) -> list[dict]:
+    sql = (
+        "SELECT TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE "
+        "FROM INFORMATION_SCHEMA.TABLES"
+    )
+    params: list[Any] = []
+    if schema:
+        sql += " WHERE TABLE_SCHEMA = %s"
+        params.append(schema)
+    else:
+        sql += " WHERE TABLE_SCHEMA = DATABASE()"
+    sql += " ORDER BY TABLE_SCHEMA, TABLE_NAME"
+    out = run_query(conn, sql, params or None, None)
+    return out["rows"]
+
+
+def list_columns(conn, table: str) -> list[dict]:
+    """Columns for `table`, which may be ``schema.table`` or just ``table``."""
+    schema, _, name = table.rpartition(".")
+    sql = (
+        "SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_KEY, "
+        "CHARACTER_MAXIMUM_LENGTH, COLUMN_DEFAULT "
+        "FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME = %s"
+    )
+    params: list[Any] = [name]
+    if schema:
+        sql += " AND TABLE_SCHEMA = %s"
+        params.append(schema)
+    else:
+        sql += " AND TABLE_SCHEMA = DATABASE()"
+    sql += " ORDER BY ORDINAL_POSITION"
+    out = run_query(conn, sql, params, None)
+    return out["rows"]