postgres-aiops 0.2.1__tar.gz → 0.3.0__tar.gz

postgres_aiops-0.3.0/.github/workflows/mcp-publish.yml

@@ -0,0 +1,55 @@
+name: mcp-publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Wait for PyPI
+        # The release event also triggers the PyPI publish workflow; the MCP
+        # registry validates that the package version exists on PyPI, so poll
+        # until it has propagated (every 15s, up to 10 minutes).
+        run: |
+          python3 - <<'EOF'
+          import json
+          import sys
+          import time
+          import urllib.error
+          import urllib.request
+
+          with open("server.json", encoding="utf-8") as f:
+              package = json.load(f)["packages"][0]
+          name, version = package["identifier"], package["version"]
+          url = f"https://pypi.org/pypi/{name}/{version}/json"
+          deadline = time.monotonic() + 600
+          while True:
+              try:
+                  with urllib.request.urlopen(url, timeout=10):
+                      print(f"{name}=={version} is available on PyPI.")
+                      sys.exit(0)
+              except (urllib.error.URLError, OSError) as exc:
+                  print(f"{name}=={version} not on PyPI yet ({exc}); "
+                        "retrying in 15s...")
+              if time.monotonic() >= deadline:
+                  sys.exit(f"Timed out after 10 minutes waiting for "
+                           f"{name}=={version} to appear on PyPI. "
+                           "Check the PyPI publish workflow, then re-run "
+                           "this workflow via workflow_dispatch.")
+              time.sleep(15)
+          EOF
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Login to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: ./mcp-publisher publish

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 .pytest_cache/
 .ruff_cache/
 *.egg-info/
+.coverage

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.3.0 — 2026-07-17
+
+### Added
+- **Undo executor**: `undo list` / `undo apply <id>` (CLI + MCP) — apply a recorded replayable inverse; the dispatched inverse is re-gated by its own risk tier; single-use, dry-run, double-confirm, both wrapper + inverse audited.
+
 ## v0.2.1 — 2026-07-16
 
 ### Fixed

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: postgres-aiops
-Version: 0.2.1
+Version: 0.3.0
 Summary: Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock analysis with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: wei <zhouwei008@gmail.com>
 License-Expression: MIT

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/mcp_server/server.py

@@ -26,6 +26,7 @@ from mcp_server.tools import (  # noqa: F401 — side effects
     replication,
     server,
     tables,
+    undo,
 )
 
 __all__ = ["mcp", "main", "_safe_error", "tool_errors"]

postgres_aiops-0.3.0/mcp_server/tools/undo.py

@@ -0,0 +1,121 @@
+"""Undo executor — list recorded inverse descriptors and APPLY them.
+
+Every governed write records a replayable inverse descriptor (tool + params) to
+``undo.db``. This module closes the loop: ``undo_apply`` looks up a recorded
+descriptor and dispatches it to the named governed tool, so the inverse runs on
+the SAME governance path as any other call (audited, budget-checked, and — if
+the inverse itself is destructive — re-gated by its own risk tier / approver
+requirement). ``undo_apply`` is itself governed; the real risk is enforced by
+the inner tool it calls.
+
+Note: recorded ``undo_params`` are the redacted safe-params captured at record
+time, so an inverse that would need a secret value cannot be replayed here — by
+design, inverses in this line key off ids/names, not credentials.
+"""
+
+import json
+from typing import Any, Optional
+
+from mcp_server._shared import mcp, tool_errors
+from postgres_aiops.governance import governed_tool
+from postgres_aiops.governance.undo import get_undo_store
+
+
+def _resolve_tool(name: str) -> Any:
+    """Return the governed callable registered under ``name`` (or None)."""
+    tool = mcp._tool_manager._tools.get(name)
+    return getattr(tool, "fn", None) if tool else None
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
+    """[READ] List recorded, not-yet-applied undo tokens (most recent first).
+
+    Each entry names the original tool, the inverse tool that ``undo_apply``
+    would run, and a human note. Use the ``undoId`` with ``undo_apply``.
+
+    Args:
+        limit: Max rows to return (default 50).
+        target: Unused (undo state is host-local); accepted for CLI uniformity.
+    """
+    rows = get_undo_store().list(status="recorded", limit=max(1, min(limit, 500)))
+    return {
+        "count": len(rows),
+        "undos": [
+            {
+                "undoId": r["undo_id"],
+                "ts": r["ts"],
+                "originalTool": r["tool"],
+                "inverseTool": r["undo_tool"],
+                "note": r.get("note", ""),
+            }
+            for r in rows
+        ],
+    }
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
+
+    The inverse runs through its own governed tool, so its real risk tier and
+    any approver requirement are enforced there. Pass dry_run=True to preview
+    the inverse call without executing it. A token can only be applied once.
+
+    Args:
+        undo_id: The undoId from undo_list (or an ``_undo_id`` in a write result).
+        dry_run: If True, preview the inverse tool + params without running it.
+        target: Passed through to the inverse tool when it accepts a target.
+    """
+    store = get_undo_store()
+    rec = store.get(undo_id)
+    if not rec:
+        raise ValueError(f"Unknown undo id '{undo_id}'. Run undo_list to see available tokens.")
+    if rec["status"] != "recorded":
+        raise ValueError(
+            f"Undo '{undo_id}' is already '{rec['status']}' — a token can only be applied once."
+        )
+
+    inverse_tool = rec["undo_tool"]
+    try:
+        params = json.loads(rec["undo_params"]) if rec["undo_params"] else {}
+    except (ValueError, TypeError):
+        params = {}
+    if not isinstance(params, dict):
+        params = {}
+
+    fn = _resolve_tool(inverse_tool)
+    if fn is None:
+        raise ValueError(
+            f"Inverse tool '{inverse_tool}' is not registered on this server; cannot apply."
+        )
+
+    if dry_run:
+        return {
+            "dryRun": True,
+            "undoId": undo_id,
+            "wouldApply": {"tool": inverse_tool, "params": params},
+        }
+
+    call_params = dict(params)
+    if target is not None and "target" not in call_params:
+        call_params["target"] = target
+    result = fn(**call_params)
+
+    # Only mark applied when the inverse did not itself return an error dict.
+    if not (isinstance(result, dict) and result.get("error")):
+        store.mark(undo_id, "applied")
+        applied = True
+    else:
+        applied = False
+
+    return {
+        "undoId": undo_id,
+        "applied": applied,
+        "inverseTool": inverse_tool,
+        "result": result,
+    }

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/postgres_aiops/cli/_root.py

@@ -17,6 +17,7 @@ from postgres_aiops.cli.replication import repl_app
 from postgres_aiops.cli.secret import secret_app
 from postgres_aiops.cli.server import server_app
 from postgres_aiops.cli.table import table_app
+from postgres_aiops.cli.undo import undo_app
 
 app = typer.Typer(
     name="postgres-aiops",
@@ -33,6 +34,7 @@ app.add_typer(repl_app, name="repl")
 app.add_typer(analyze_app, name="analyze")
 app.add_typer(remediate_app, name="remediate")
 app.add_typer(secret_app, name="secret")
+app.add_typer(undo_app, name="undo")
 app.command("init")(init_cmd)
 app.command("overview")(overview_cmd)
 app.command("doctor")(doctor_cmd)

postgres_aiops-0.3.0/postgres_aiops/cli/undo.py

@@ -0,0 +1,62 @@
+"""``postgres-aiops undo`` — list recorded undo tokens and apply them.
+
+Real execution is delegated to the ``@governed_tool``-wrapped functions in
+``mcp_server.tools.undo`` so an applied undo is audited on the SAME governance
+path as any other write (the inverse tool it dispatches is itself re-gated).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from postgres_aiops.cli._common import (
+    DryRunOption,
+    TargetOption,
+    cli_errors,
+    console,
+    double_confirm,
+    dry_run_print,
+)
+
+undo_app = typer.Typer(
+    name="undo",
+    help="List recorded undo tokens and apply their inverse operations.",
+    no_args_is_help=True,
+)
+
+UndoIdArg = Annotated[str, typer.Argument(help="Undo id from 'undo list'")]
+
+
+@undo_app.command("list")
+@cli_errors
+def undo_list_cmd(
+    limit: Annotated[int, typer.Option("--limit", help="Max tokens to show")] = 50,
+    target: TargetOption = None,
+) -> None:
+    """List recorded, not-yet-applied undo tokens."""
+    from mcp_server.tools import undo as gov
+
+    console.print_json(json.dumps(gov.undo_list(limit=limit, target=target)))
+
+
+@undo_app.command("apply")
+@cli_errors
+def undo_apply_cmd(
+    undo_id: UndoIdArg, target: TargetOption = None, dry_run: DryRunOption = False
+) -> None:
+    """Apply a recorded undo (dispatches its inverse tool; dry-run + confirm)."""
+    from mcp_server.tools import undo as gov
+
+    if dry_run:
+        preview = gov.undo_apply(undo_id=undo_id, dry_run=True, target=target)
+        dry_run_print(
+            operation="undo_apply",
+            api_call=f"inverse: {preview.get('wouldApply', {}).get('tool', '?')}",
+            parameters=preview.get("wouldApply", {}).get("params", {}),
+        )
+        return
+    double_confirm("apply undo", undo_id)
+    console.print_json(json.dumps(gov.undo_apply(undo_id=undo_id, target=target)))

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "postgres-aiops"
-version = "0.2.1"
+version = "0.3.0"
 description = "Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock analysis with a built-in governance harness (audit, budget, undo, risk tiers)"
 readme = "README.md"
 license = "MIT"

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/AIops-tools/Postgres-AIops",
     "source": "github"
   },
-  "version": "0.2.1",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "postgres-aiops",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       }

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/tests/test_smoke.py

@@ -34,6 +34,8 @@ EXPECTED_TOOLS = {
     # writes
     "reset_query_stats", "terminate_backend", "cancel_query", "run_vacuum",
     "run_analyze", "create_index", "drop_index", "reindex", "update_setting",
+    # undo executor
+    "undo_list", "undo_apply",
 }
 
 WRITE_RISK = {
@@ -64,6 +66,7 @@ def test_all_modules_import():
         "mcp_server.server", "mcp_server._shared",
         "mcp_server.tools.server", "mcp_server.tools.activity",
         "mcp_server.tools.queries", "mcp_server.tools.indexes",
+        "postgres_aiops.cli.undo", "mcp_server.tools.undo",
         "mcp_server.tools.tables", "mcp_server.tools.replication",
         "mcp_server.tools.analysis", "mcp_server.tools.remediation",
     ):

postgres_aiops-0.3.0/tests/test_undo_executor.py

@@ -0,0 +1,138 @@
+"""Undo EXECUTOR — undo_apply dispatches a recorded inverse through its governed
+tool, on a real undo.db in an isolated home. Closes the loop from "undo recorded"
+to "undo actually executed".
+
+Portable across the line: the dispatched inverse is a synthetic governed tool
+registered on the real MCP instance, so this file is identical everywhere except
+the package import path.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+import pytest
+
+import postgres_aiops.governance.audit as audit_mod
+import postgres_aiops.governance.policy as policy_mod
+import postgres_aiops.governance.undo as undo_mod
+from mcp_server._shared import mcp
+from mcp_server.tools import undo as gov
+from postgres_aiops.governance import governed_tool
+
+_CALLS: list[dict] = []
+
+
+@governed_tool(risk_level="low")
+def _undo_probe(value: str = "", target=None) -> dict:
+    """Synthetic inverse target used only by the undo-executor tests."""
+    _CALLS.append({"value": value})
+    return {"ok": True, "value": value}
+
+
+@pytest.fixture
+def gov_home(tmp_path, monkeypatch):
+    _CALLS.clear()
+    # Register the probe only for the duration of these tests so it never
+    # pollutes the real tool registry (which exact-count smoke tests assert on).
+    mcp.add_tool(_undo_probe, name="_undo_probe")
+    monkeypatch.setenv("POSTGRES_AIOPS_HOME", str(tmp_path))
+    monkeypatch.setenv("POSTGRES_AUDIT_APPROVED_BY", "pytest")
+    audit_mod.reset_engine()
+    policy_mod.reset_policy_engine()
+    undo_mod.reset_undo_store()
+    yield tmp_path
+    mcp._tool_manager._tools.pop("_undo_probe", None)
+    audit_mod.reset_engine()
+    policy_mod.reset_policy_engine()
+    undo_mod.reset_undo_store()
+
+
+def _record(undo_tool="_undo_probe", params=None):
+    descriptor = {"tool": undo_tool, "params": params if params is not None else {"value": "v1"}}
+    return undo_mod.get_undo_store().record(
+        skill="probe", tool="orig_op", undo_descriptor=descriptor,
+    )
+
+
+@pytest.mark.unit
+def test_undo_list_returns_recorded_tokens(gov_home):
+    uid = _record()
+    out = gov.undo_list()
+    assert out["count"] == 1
+    assert out["undos"][0]["undoId"] == uid
+    assert out["undos"][0]["inverseTool"] == "_undo_probe"
+
+
+@pytest.mark.unit
+def test_undo_apply_dispatches_inverse_and_marks_applied(gov_home):
+    uid = _record(params={"value": "restore-me"})
+    result = gov.undo_apply(undo_id=uid)
+    assert result["applied"] is True
+    assert result["inverseTool"] == "_undo_probe"
+    # the inverse governed tool actually ran with the recorded params
+    assert _CALLS == [{"value": "restore-me"}]
+    # the token is consumed (single-use)
+    assert undo_mod.get_undo_store().get(uid)["status"] == "applied"
+    assert uid not in {u["undoId"] for u in gov.undo_list()["undos"]}
+
+
+@pytest.mark.unit
+def test_undo_apply_dry_run_previews_without_running(gov_home):
+    uid = _record()
+    out = gov.undo_apply(undo_id=uid, dry_run=True)
+    assert out["dryRun"] is True
+    assert out["wouldApply"]["tool"] == "_undo_probe"
+    assert _CALLS == []
+    assert undo_mod.get_undo_store().get(uid)["status"] == "recorded"
+
+
+@pytest.mark.unit
+def test_undo_apply_is_single_use(gov_home):
+    uid = _record()
+    gov.undo_apply(undo_id=uid)
+    second = gov.undo_apply(undo_id=uid)
+    assert "already 'applied'" in second["error"]
+
+
+@pytest.mark.unit
+def test_undo_apply_unknown_id_errors(gov_home):
+    out = gov.undo_apply(undo_id="deadbeef")
+    assert "Unknown undo id" in out["error"]
+
+
+@pytest.mark.unit
+def test_undo_apply_unregistered_inverse_errors(gov_home):
+    uid = _record(undo_tool="no_such_tool_xyz")
+    out = gov.undo_apply(undo_id=uid)
+    assert "not registered" in out["error"]
+    assert undo_mod.get_undo_store().get(uid)["status"] == "recorded"
+
+
+@pytest.mark.unit
+def test_cli_undo_apply_dry_run_renders(gov_home):
+    """The `undo apply --dry-run` CLI path must render without error — guards
+    against dry_run_print signature drift across tools (api_call vs detail)."""
+    from typer.testing import CliRunner
+
+    from postgres_aiops.cli import app
+
+    uid = _record()
+    result = CliRunner().invoke(app, ["undo", "apply", uid, "--dry-run"])
+    assert result.exit_code == 0, result.output
+    assert "DRY-RUN" in result.output
+    assert _CALLS == []
+    assert undo_mod.get_undo_store().get(uid)["status"] == "recorded"
+
+
+@pytest.mark.unit
+def test_undo_apply_audits_both_wrapper_and_inverse(gov_home):
+    uid = _record()
+    gov.undo_apply(undo_id=uid)
+    conn = sqlite3.connect(gov_home / "audit.db")
+    try:
+        tools = [r[0] for r in conn.execute("SELECT tool FROM audit_log ORDER BY id")]
+    finally:
+        conn.close()
+    assert "undo_apply" in tools
+    assert "_undo_probe" in tools

{postgres_aiops-0.2.1 → postgres_aiops-0.3.0}/uv.lock

@@ -484,7 +484,7 @@ wheels = [
 
 [[package]]
 name = "postgres-aiops"
-version = "0.2.1"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },

postgres_aiops-0.2.1/.github/workflows/mcp-publish.yml

@@ -1,23 +0,0 @@
-name: mcp-publish
-
-on:
-  workflow_dispatch:
-  release:
-    types: [published]
-
-permissions:
-  id-token: write
-  contents: read
-
-jobs:
-  publish-mcp:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install mcp-publisher
-        run: |
-          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
-      - name: Login to MCP Registry (GitHub OIDC)
-        run: ./mcp-publisher login github-oidc
-      - name: Publish server.json
-        run: ./mcp-publisher publish