postgres-aiops 0.2.0__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.0 → postgres_aiops-0.3.0}/.gitignore

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

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

@@ -1,5 +1,24 @@
 # 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
+- **`secrets.enc` now follows `POSTGRES_AIOPS_HOME`** (secretstore hardcoded the real
+  home directory; config/audit/undo already relocated — found in live verification).
+- **Audit fidelity**: failures sanitized into `{"error": ...}` results by the MCP error
+  layer are now audited as `status=error` (they previously read as `ok`, hiding failed
+  attempts from exception reports), and no undo is recorded for a call that failed.
+- Undo replay fix: `create_index` accepts a `definition` (captured `pg_get_indexdef` statement, shape-validated), making `drop_index`'s undo descriptor replayable.
+
+### Tests
+- `doctor` and the `init` wizard are now fully covered (previously ~10–20%); plus a
+  regression test for the sanitized-failure audit status.
+
 ## v0.2.0 — 2026-07-13
 
 Security-hardening release from a line-wide code review.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: postgres-aiops
-Version: 0.2.0
+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.0 → 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.2.0 → postgres_aiops-0.3.0}/mcp_server/tools/remediation.py

@@ -162,12 +162,13 @@ def run_analyze(table: str, dry_run: bool = False, target: Optional[str] = None)
 @governed_tool(risk_level="medium", undo=_create_index_undo)
 @tool_errors("dict")
 def create_index(
-    table: str,
-    columns: list[str],
+    table: Optional[str] = None,
+    columns: Optional[list[str]] = None,
     name: Optional[str] = None,
     unique: bool = False,
     concurrently: bool = False,
     method: Optional[str] = None,
+    definition: Optional[str] = None,
     dry_run: bool = False,
     target: Optional[str] = None,
 ) -> dict:
@@ -175,21 +176,34 @@ def create_index(
 
     Supports CONCURRENTLY (non-blocking build). The created name is returned so
     the harness records an undo that drops exactly this index. Pass dry_run=True
-    to preview.
+    to preview. Alternatively pass ``definition`` (a captured pg_get_indexdef
+    statement — this is how drop_index's undo descriptor replays) INSTEAD of
+    table/columns.
 
     Args:
-        table: Table to index (optionally schema-qualified).
-        columns: Column names to index.
+        table: Table to index (optionally schema-qualified). Required unless
+            ``definition`` is given.
+        columns: Column names to index. Required unless ``definition`` is given.
         name: Index name (auto-generated from table+columns when omitted).
         unique: Create a UNIQUE index.
         concurrently: Build with CONCURRENTLY (no table lock).
         method: Index method — btree/hash/gist/gin/brin/spgist (default btree).
+        definition: A full CREATE [UNIQUE] INDEX statement to execute verbatim
+            (shape-validated). Mutually exclusive with table/columns.
         dry_run: If True, preview without creating.
         target: Target name from config; omit for the default.
     """
+    if definition and (table or columns):
+        raise ValueError("Pass either definition OR table+columns, not both.")
+    if not definition and not (table and columns):
+        raise ValueError("create_index requires table+columns (or a definition).")
     conn = _get_connection(target)
     if dry_run:
+        if definition:
+            return {"dryRun": True, "wouldExecute": definition}
         return {"dryRun": True, "wouldCreate": {"table": table, "columns": columns, "name": name}}
+    if definition:
+        return ops.create_index_from_definition(conn, definition)
     return ops.create_index(
         conn, table, columns, name=name, unique=unique,
         concurrently=concurrently, method=method,

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.0 → 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.0 → postgres_aiops-0.3.0}/postgres_aiops/governance/decorators.py

@@ -317,6 +317,8 @@ def _record_undo(state: _CallState, result: Any) -> None:
     """
     if state.undo is None:
         return
+    if isinstance(result, dict) and result.get("error"):
+        return  # sanitized failure — no change happened, so no inverse to record
     try:
         descriptor = state.undo(state.safe_params, result)
     except Exception:  # noqa: BLE001 — undo computation must not fail the call
@@ -356,6 +358,12 @@ def _capture_error(state: _CallState, exc: Exception) -> None:
 
 def _finalize(state: _CallState) -> None:
     """Audit + circuit-breaker bookkeeping. Runs in the wrapper's finally."""
+    # A sanitized failure (@tool_errors converts exceptions into {"error": ...}
+    # dicts BEFORE this harness sees them) must not be audited as success —
+    # compliance exception reports are built from this status.
+    if state.status == "ok" and isinstance(state.result, dict) and state.result.get("error"):
+        state.status = "error"
+
     duration = int((time.time() - state.start) * 1000)
 
     # Accumulate wall-time toward the cumulative time budget (best-effort).

{postgres_aiops-0.2.0 → postgres_aiops-0.3.0}/postgres_aiops/ops/remediation.py

@@ -162,6 +162,36 @@ def create_index(
     }
 
 
+# Shape gate for replaying a captured pg_get_indexdef statement. Server-generated
+# (never user-composed), but validated anyway: single statement, CREATE INDEX only.
+_INDEXDEF_RE = re.compile(
+    r"^CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?"
+    r'("?[A-Za-z_][A-Za-z0-9_$]*"?)\s+ON\s+',
+    re.IGNORECASE,
+)
+
+
+def create_index_from_definition(conn: Any, definition: str) -> dict:
+    """[WRITE] Recreate an index from a captured ``pg_get_indexdef`` statement.
+
+    This is the replay path for ``drop_index``'s undo descriptor: the exact
+    definition captured before the drop is executed verbatim after a shape
+    check (single statement, must be CREATE [UNIQUE] INDEX ... ON ...).
+    """
+    stmt = (definition or "").strip().rstrip(";").strip()
+    if not stmt or ";" in stmt:
+        raise ValueError("definition must be a single CREATE INDEX statement.")
+    m = _INDEXDEF_RE.match(stmt)
+    if not m:
+        raise ValueError("definition must start with CREATE [UNIQUE] INDEX ... ON ...")
+    conn.execute(stmt)  # nosec B608 — shape-validated pg_get_indexdef output
+    return {
+        "action": "create_index",
+        "index": m.group(1).strip('"'),
+        "fromDefinition": True,
+    }
+
+
 def drop_index(conn: Any, name: str, concurrently: bool = False) -> dict:
     """[WRITE] Drop an index. Reversible: captures pg_get_indexdef first so undo recreates it."""
     ident = qualify(name)

{postgres_aiops-0.2.0 → postgres_aiops-0.3.0}/postgres_aiops/secretstore.py

@@ -39,9 +39,11 @@ from cryptography.exceptions import InvalidKey
 from cryptography.fernet import Fernet, InvalidToken
 from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
 
+from postgres_aiops.governance.paths import ops_home
+
 # ─── Tool-specific constants (change these three to vendor for another tool) ──
 APP_NAME = "postgres-aiops"
-CONFIG_DIR = Path.home() / ".postgres-aiops"
+CONFIG_DIR = ops_home()
 MASTER_PASSWORD_ENV = "POSTGRES_AIOPS_MASTER_PASSWORD"  # nosec B105 — env-var name
 # ──────────────────────────────────────────────────────────────────────────────
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "postgres-aiops"
-version = "0.2.0"
+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.0 → postgres_aiops-0.3.0}/server.json

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

{postgres_aiops-0.2.0 → postgres_aiops-0.3.0}/skills/postgres-aiops/SKILL.md

@@ -105,6 +105,7 @@ Pass data straight to the analysis tools — `slow_query_rca(statements=[...])`,
 
 - Every tool is audited to `~/.postgres-aiops/audit.db` (relocatable via `POSTGRES_AIOPS_HOME`).
 - High-risk ops can require a named approver: set `POSTGRES_AUDIT_APPROVED_BY` and `POSTGRES_AUDIT_RATIONALE` (the env-var names the bundled harness reads).
+- **Secure by default (v0.2.0+)**: with no `~/.postgres-aiops/rules.yaml`, high/critical operations are denied unless `POSTGRES_AUDIT_APPROVED_BY` names an approver (set `POSTGRES_AUDIT_RATIONALE` too). `postgres-aiops init` seeds a starter rules.yaml; an operator-authored rules file is honoured as-is.
 - Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI.
 - Reversible writes fetch the real before-state and record an inverse descriptor; irreversible ops (terminate/cancel, vacuum/analyze, reindex, reset stats) record prior stats only.
 - All values are bound query parameters; identifiers that cannot be parameterised are validated and quoted.

postgres_aiops-0.3.0/tests/test_doctor.py

@@ -0,0 +1,184 @@
+"""Tests for ``run_doctor`` — environment and connectivity diagnostics.
+
+Everything is redirected to a tmp dir (config, secret store) and the
+connection layer is faked at the ``ConnectionManager`` boundary, so no test
+ever touches a real PostgreSQL server or ``~/.postgres-aiops``.
+"""
+
+from __future__ import annotations
+
+import pytest
+import yaml
+from rich.console import Console
+
+import postgres_aiops.config as config_mod
+import postgres_aiops.connection as connection_mod
+import postgres_aiops.doctor as doctor_mod
+import postgres_aiops.secretstore as ss
+from postgres_aiops.doctor import run_doctor
+
+MASTER_PW = "test-master-pw"
+
+
+@pytest.fixture
+def doctor_home(tmp_path, monkeypatch):
+    """Isolate config + secret store paths under tmp_path."""
+    config_file = tmp_path / "config.yaml"
+    env_file = tmp_path / ".env"
+    secrets_file = tmp_path / "secrets.enc"
+    monkeypatch.setenv("POSTGRES_AIOPS_HOME", str(tmp_path))
+    monkeypatch.setattr(config_mod, "CONFIG_DIR", tmp_path)
+    monkeypatch.setattr(config_mod, "CONFIG_FILE", config_file)
+    monkeypatch.setattr(config_mod, "ENV_FILE", env_file)
+    monkeypatch.setattr(doctor_mod, "CONFIG_FILE", config_file)
+    monkeypatch.setattr(doctor_mod, "ENV_FILE", env_file)
+    monkeypatch.setattr(doctor_mod, "SECRETS_FILE", secrets_file)
+    monkeypatch.setattr(ss, "CONFIG_DIR", tmp_path)
+    monkeypatch.setattr(ss, "SECRETS_FILE", secrets_file)
+    monkeypatch.setattr(ss, "LEGACY_ENV_FILE", env_file)
+    monkeypatch.setattr(ss, "_cached", None)
+    # Wide console so long messages don't wrap mid-assertion.
+    monkeypatch.setattr(doctor_mod, "_console", Console(width=500))
+    monkeypatch.delenv("PG_PRIMARY_PASSWORD", raising=False)
+    return tmp_path
+
+
+def _write_config(tmp_path, targets: list[dict]) -> None:
+    (tmp_path / "config.yaml").write_text(yaml.safe_dump({"targets": targets}), "utf-8")
+
+
+def _seed_secret(monkeypatch, name: str = "primary", value: str = "s3cret") -> None:
+    monkeypatch.setenv("POSTGRES_AIOPS_MASTER_PASSWORD", MASTER_PW)
+    ss.SecretStore.unlock(MASTER_PW).set(name, value)
+
+
+_TARGET = {"name": "primary", "host": "db1.example.com", "port": 5432}
+
+
+class _HealthyManager:
+    """Stands in for ConnectionManager: every connect() succeeds."""
+
+    def __init__(self, config) -> None:
+        self._config = config
+
+    def connect(self, name):
+        class _Conn:
+            def query_one(self, sql):
+                return {"version": "PostgreSQL 16.4 on x86_64-pc-linux-gnu"}
+
+        return _Conn()
+
+
+class _UnreachableManager:
+    """Stands in for ConnectionManager: every connect() fails."""
+
+    def __init__(self, config) -> None:
+        self._config = config
+
+    def connect(self, name):
+        raise ConnectionError("connection to server at 'db1.example.com' refused")
+
+
+@pytest.mark.unit
+def test_doctor_missing_config_fails_with_init_hint(doctor_home, capsys):
+    assert run_doctor() == 1
+    out = capsys.readouterr().out
+    assert "Config file missing" in out
+    assert "postgres-aiops init" in out
+
+
+@pytest.mark.unit
+def test_doctor_config_load_failure_reported_not_raised(doctor_home, capsys):
+    (doctor_home / "config.yaml").write_text("targets: [unclosed", "utf-8")
+    assert run_doctor() == 1
+    assert "Config load failed" in capsys.readouterr().out
+
+
+@pytest.mark.unit
+def test_doctor_no_targets_configured(doctor_home, capsys):
+    _write_config(doctor_home, [])
+    assert run_doctor() == 1
+    assert "No targets configured" in capsys.readouterr().out
+
+
+@pytest.mark.unit
+def test_doctor_all_healthy_exit_zero(doctor_home, monkeypatch, capsys):
+    _write_config(doctor_home, [_TARGET])
+    _seed_secret(monkeypatch)
+    monkeypatch.setattr(connection_mod, "ConnectionManager", _HealthyManager)
+    assert run_doctor() == 0
+    out = capsys.readouterr().out
+    assert "Config file present" in out
+    assert "1 target(s) configured" in out
+    assert "Encrypted secret store present" in out
+    assert "password present for 'primary'" in out
+    assert "Connected to 'primary' (db1.example.com:5432)" in out
+    assert "PostgreSQL 16.4" in out
+
+
+@pytest.mark.unit
+def test_doctor_skip_auth_skips_connectivity(doctor_home, monkeypatch, capsys):
+    _write_config(doctor_home, [_TARGET])
+    _seed_secret(monkeypatch)
+
+    def _boom(config):  # doctor must not even construct a manager
+        raise AssertionError("ConnectionManager should not be used with --skip-auth")
+
+    monkeypatch.setattr(connection_mod, "ConnectionManager", _boom)
+    assert run_doctor(skip_auth=True) == 0
+    out = capsys.readouterr().out
+    assert "Skipping connectivity check" in out
+    assert "Connected" not in out
+
+
+@pytest.mark.unit
+def test_doctor_unreachable_target_exit_one(doctor_home, monkeypatch, capsys):
+    _write_config(doctor_home, [_TARGET])
+    _seed_secret(monkeypatch)
+    monkeypatch.setattr(connection_mod, "ConnectionManager", _UnreachableManager)
+    assert run_doctor() == 1
+    out = capsys.readouterr().out
+    assert "Connect to 'primary' failed" in out
+    assert "refused" in out
+
+
+@pytest.mark.unit
+def test_doctor_no_secret_store_and_no_password(doctor_home, capsys):
+    _write_config(doctor_home, [_TARGET])
+    assert run_doctor(skip_auth=True) == 1
+    out = capsys.readouterr().out
+    assert "No secret store yet" in out
+    assert "No password for target 'primary'" in out
+
+
+@pytest.mark.unit
+def test_doctor_legacy_env_file_warns_migrate(doctor_home, monkeypatch, capsys):
+    _write_config(doctor_home, [_TARGET])
+    (doctor_home / ".env").write_text("PG_PRIMARY_PASSWORD=legacy\n", "utf-8")
+    monkeypatch.setenv("PG_PRIMARY_PASSWORD", "legacy")
+    assert run_doctor(skip_auth=True) == 0
+    out = capsys.readouterr().out
+    assert "legacy plaintext .env" in out
+    assert "secret migrate" in out
+
+
+@pytest.mark.unit
+def test_doctor_warns_on_loose_secret_permissions(doctor_home, monkeypatch, capsys):
+    _write_config(doctor_home, [_TARGET])
+    _seed_secret(monkeypatch)
+    (doctor_home / "secrets.enc").chmod(0o644)
+    assert run_doctor(skip_auth=True) == 0
+    assert "should be 600" in capsys.readouterr().out
+
+
+@pytest.mark.unit
+def test_cli_doctor_command_exits_with_doctor_code(doctor_home, monkeypatch):
+    from typer.testing import CliRunner
+
+    from postgres_aiops.cli import app
+
+    _write_config(doctor_home, [_TARGET])
+    _seed_secret(monkeypatch)
+    result = CliRunner().invoke(app, ["doctor", "--skip-auth"])
+    assert result.exit_code == 0
+    assert "Skipping connectivity check" in result.output