queue-aiops 0.7.0__tar.gz → 0.8.0__tar.gz

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.8.0 — 2026-08-10
+
+### Fixed
+- **An undetermined outcome no longer exits as a plain failure.** A write whose response was lost carries *both* `error` and `outcomeUnknown`, and the harness deliberately judges unknown first when writing the audit row — the change may have taken effect, so a blind retry could apply it twice. The CLI guard judged `error` first, so the audit said "may have taken effect" while the exit status told a script it had not happened. The two layers now agree (exit 2, not 1), and a test pins the ordering so it cannot silently flip back.
+- **The CLI reported a refused or failed governed write as a success.** 8 write call sites printed the governed twin's payload and exited **0** whatever it said — and `@tool_errors` flattens every refusal, guard rejection and upstream failure into `{"error": ...}` rather than raising, so nothing downstream of a `&&` chain or a CI step could tell a blocked write from a landed one. The dry-run path already exited non-zero, which made the asymmetry worse: the preview was stricter than the write it previews. Results now route through a `checked()` helper — exit 1 on an error payload, exit 2 on an undetermined outcome, unchanged on success. This defect class had been fixed repo-by-repo several times and kept coming back; an audit across the whole line found it live in **18 of the 24 tools at once (87 call sites)**, so each tool now carries an invariant test that fails if any future CLI command prints a governed result without checking it.
+
 ## v0.7.0 — 2026-08-10
 
 ### Fixed

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queue-aiops
-Version: 0.7.0
+Version: 0.8.0
 Summary: Governed AI-ops for redis + rabbitmq: memory-pressure/latency/queue-backlog/connection-churn RCAs, slowlog and SCAN-budgeted big-key sampling, queues/policies/nodes, and governed writes (config set, client kill, purge/delete queue, policies) with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "queue-aiops"
-version = "0.7.0"
+version = "0.8.0"
 description = "Governed AI-ops for redis + rabbitmq: memory-pressure/latency/queue-backlog/connection-churn RCAs, slowlog and SCAN-budgeted big-key sampling, queues/policies/nodes, and governed writes (config set, client kill, purge/delete queue, policies) with a built-in governance harness (audit, budget, undo, risk tiers)"
 readme = "README.md"
 license = "MIT"

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/queue_aiops/cli/_common.py

@@ -76,6 +76,53 @@ def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = No
     console.print("[magenta]  Run without --dry-run to execute.[/]\n")
 
 
+#: Exit status for a write whose outcome could not be determined. Kept distinct
+#: from 0 (confirmed) and 1 (failed) on purpose: a write whose response was lost
+#: is not a failure, but it is emphatically not a success either, and a script
+#: must be able to tell all three apart.
+EXIT_UNDETERMINED = 2
+
+
+def checked(result: Any) -> Any:
+    """Return ``result``, or abort when it reports a failed/undetermined write.
+
+    Every CLI command that calls a governed twin MUST pass the result through
+    here before printing its success line.
+
+    Governed twins are wrapped in ``@tool_errors``, which flattens any exception
+    into ``{"error": ...}`` and **returns** it. The CLI therefore never sees the
+    exception, so a command that prints its result unconditionally reports a
+    refused or failed operation exactly like a successful one — and exits 0, so
+    a script cannot tell either. The dry-run path already refused with a
+    non-zero status, which made the asymmetry worse: the preview was stricter
+    than the real call.
+
+    ``outcomeUnknown`` (set by the harness when a write's response is lost) is
+    neither success nor failure — the change may still have landed. It gets its
+    own line and :data:`EXIT_UNDETERMINED`, never a silent success.
+    """
+    if not isinstance(result, dict):
+        return result
+    error = result.get("error")
+    # ``outcomeUnknown`` is judged BEFORE ``error``, matching the harness: a
+    # write whose response was lost carries BOTH keys, and it is audited
+    # `unknown` precisely because it may have taken effect. Reporting that as a
+    # plain failure would tell a script the change did not happen and invite the
+    # double-apply the payload's own note warns about.
+    if result.get("outcomeUnknown"):
+        console.print(
+            f"[yellow]Outcome undetermined: {result.get('note') or ''}[/]"
+        )
+        raise typer.Exit(EXIT_UNDETERMINED)
+    if error:
+        console.print(f"[red]Error: {error}[/]")
+        hint = result.get("hint")
+        if hint:
+            console.print(f"[dim]{hint}[/]")
+        raise typer.Exit(1)
+    return result
+
+
 def dry_run_preview(
     preview: Any, *, operation: str, api_call: str, parameters: dict | None = None
 ) -> None:

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/queue_aiops/cli/rabbit_cmds.py

@@ -10,6 +10,7 @@ import typer
 from queue_aiops.cli._common import (
     DryRunOption,
     TargetOption,
+    checked,
     cli_errors,
     console,
     double_confirm,
@@ -157,7 +158,7 @@ def rabbit_purge(
             parameters={"vhost": vhost, "name": name})
         return
     double_confirm("purge queue", name)
-    console.print_json(json.dumps(gov.purge_queue(vhost=vhost, name=name, target=target)))
+    console.print_json(json.dumps(checked(gov.purge_queue(vhost=vhost, name=name, target=target))))
 
 
 @rabbitmq_app.command("delete-queue")
@@ -180,7 +181,7 @@ def rabbit_delete_queue(
             parameters={"vhost": vhost, "name": name})
         return
     double_confirm("delete queue", name)
-    console.print_json(json.dumps(gov.delete_queue(vhost=vhost, name=name, target=target)))
+    console.print_json(json.dumps(checked(gov.delete_queue(vhost=vhost, name=name, target=target))))
 
 
 @rabbitmq_app.command("declare-queue")
@@ -211,9 +212,9 @@ def rabbit_declare_queue(
                         "auto_delete": auto_delete})
         return
     double_confirm("declare queue", name)
-    console.print_json(json.dumps(gov.declare_queue(
+    console.print_json(json.dumps(checked(gov.declare_queue(
         vhost=vhost, name=name, durable=durable, auto_delete=auto_delete, target=target
-    )))
+    ))))
 
 
 @rabbitmq_app.command("set-policy")
@@ -252,10 +253,10 @@ def rabbit_set_policy(
                         "apply_to": apply_to})
         return
     double_confirm("set policy", name)
-    console.print_json(json.dumps(gov.set_policy(
+    console.print_json(json.dumps(checked(gov.set_policy(
         vhost=vhost, name=name, pattern=pattern, definition=definition_obj,
         priority=priority, apply_to=apply_to, target=target,
-    )))
+    ))))
 
 
 @rabbitmq_app.command("delete-policy")
@@ -278,4 +279,6 @@ def rabbit_delete_policy(
             parameters={"vhost": vhost, "name": name})
         return
     double_confirm("delete policy", name)
-    console.print_json(json.dumps(gov.delete_policy(vhost=vhost, name=name, target=target)))
+    console.print_json(
+        json.dumps(checked(gov.delete_policy(vhost=vhost, name=name, target=target)))
+    )

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/queue_aiops/cli/redis_cmds.py

@@ -10,6 +10,7 @@ import typer
 from queue_aiops.cli._common import (
     DryRunOption,
     TargetOption,
+    checked,
     cli_errors,
     console,
     double_confirm,
@@ -138,7 +139,7 @@ def redis_config_set(
         return
     double_confirm("set config parameter", parameter)
     console.print_json(
-        json.dumps(gov.redis_config_set(parameter=parameter, value=value, target=target))
+        json.dumps(checked(gov.redis_config_set(parameter=parameter, value=value, target=target)))
     )
 
 
@@ -165,5 +166,5 @@ def redis_kill_client(
         return
     double_confirm("kill client", who or "(unspecified)")
     console.print_json(
-        json.dumps(gov.redis_kill_client(client_id=client_id, addr=addr, target=target))
+        json.dumps(checked(gov.redis_kill_client(client_id=client_id, addr=addr, target=target)))
     )

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/queue_aiops/cli/undo.py

@@ -15,6 +15,7 @@ import typer
 from queue_aiops.cli._common import (
     DryRunOption,
     TargetOption,
+    checked,
     cli_errors,
     console,
     double_confirm,
@@ -65,4 +66,4 @@ def undo_apply_cmd(
         )
         return
     double_confirm("apply undo", undo_id)
-    console.print_json(json.dumps(gov.undo_apply(undo_id=undo_id, target=target)))
+    console.print_json(json.dumps(checked(gov.undo_apply(undo_id=undo_id, target=target))))

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/AIops-tools/Queue-AIops",
     "source": "github"
   },
-  "version": "0.7.0",
+  "version": "0.8.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "queue-aiops",
-      "version": "0.7.0",
+      "version": "0.8.0",
       "transport": {
         "type": "stdio"
       }

queue_aiops-0.8.0/tests/test_cli_governed_exit.py

@@ -0,0 +1,167 @@
+"""The CLI must never report a failed governed write as a success.
+
+Two regressions are pinned here.
+
+**The behaviour** — ``checked()`` aborts non-zero on an error payload and on an
+undetermined outcome. Governed twins are wrapped in ``@tool_errors``, which
+flattens every exception into ``{"error": ...}`` and *returns* it, so a
+command that prints its result unconditionally exits 0 for an operation that
+was refused or failed.
+
+**The invariant** — every CLI call into a governed write twin routes its result
+through that helper. This is the part that matters over time: the defect was
+fixed repo-by-repo several times and kept coming back, because nothing stopped
+a *new* command from printing a governed result bare. A structural assertion
+does. It was introduced after an audit found the preview path guarded and the
+real write path unguarded in 18 of the 24 tools at once — the preview was
+stricter than the write it previews.
+"""
+
+from __future__ import annotations
+
+import ast
+import pathlib
+
+import pytest
+import typer
+
+from queue_aiops.cli._common import checked
+
+CLI_DIR = pathlib.Path(__file__).resolve().parents[1] / "queue_aiops" / "cli"
+TOOLS_DIR = pathlib.Path(__file__).resolve().parents[1] / "mcp_server" / "tools"
+
+#: Helpers that end the command non-zero when the payload reports a failure.
+CHECKERS = ['checked', 'dry_run_preview']
+
+
+@pytest.mark.unit
+def test_checked_aborts_on_error_payload():
+    with pytest.raises(typer.Exit) as exc:
+        checked({"error": "refused: that would lock this tool out"})
+    assert exc.value.exit_code == 1
+
+
+@pytest.mark.unit
+def test_checked_passes_a_successful_payload_through():
+    payload = {"action": "did_a_thing", "ok": True}
+    assert checked(payload) == payload
+
+
+def _callee(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+def _write_tool_names() -> set[str]:
+    names: set[str] = set()
+    for path in TOOLS_DIR.glob("*.py"):
+        tree = ast.parse(path.read_text())
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef) and "[WRITE]" in (ast.get_docstring(node) or ""):
+                names.add(node.name)
+    return names
+
+
+def _aborts_on_failure(fn: ast.FunctionDef) -> bool:
+    """Does this function raise ``typer.Exit`` off a failure key in the payload?
+
+    Several commands guard with a locally named helper (``_require_ok``,
+    ``_emit``, ...) rather than the shared one. Those are correct guards, so the
+    invariant recognises the *shape* instead of a list of blessed names.
+    """
+    raises_exit = any(
+        isinstance(n, ast.Call) and _callee(n.func) == "Exit" for n in ast.walk(fn)
+    )
+    reads_failure_key = any(
+        isinstance(n, ast.Constant) and n.value in ("error", "outcomeUnknown")
+        for n in ast.walk(fn)
+    )
+    return raises_exit and reads_failure_key
+
+
+def _checker_names() -> set[str]:
+    """CHECKERS, every local guard, and any wrapper delegating to one of them."""
+    funcs: dict[str, list[ast.FunctionDef]] = {}
+    for path in CLI_DIR.rglob("*.py"):
+        for node in ast.walk(ast.parse(path.read_text())):
+            if isinstance(node, ast.FunctionDef):
+                funcs.setdefault(node.name, []).append(node)
+    found = set(CHECKERS) | {
+        name for name, defs in funcs.items() if any(_aborts_on_failure(f) for f in defs)
+    }
+    changed = True
+    while changed:
+        changed = False
+        for name, defs in funcs.items():
+            if name in found:
+                continue
+            for fn in defs:
+                if any(isinstance(n, ast.Call) and _callee(n.func) in found for n in ast.walk(fn)):
+                    found.add(name)
+                    changed = True
+                    break
+    return found
+
+
+@pytest.mark.unit
+def test_every_cli_governed_write_result_is_checked():
+    tools = _write_tool_names()
+    assert tools, "no [WRITE] tools parsed — the invariant would vacuously pass"
+    checkers = _checker_names()
+    unchecked: list[str] = []
+
+    for path in sorted(CLI_DIR.rglob("*.py")):
+        tree = ast.parse(path.read_text())
+        for func in [n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]:
+            parents: dict[ast.AST, ast.AST] = {}
+            for node in ast.walk(func):
+                for child in ast.iter_child_nodes(node):
+                    parents[child] = node
+            guarded = {
+                arg.id
+                for node in ast.walk(func)
+                if isinstance(node, ast.Call) and _callee(node.func) in checkers
+                for arg in list(node.args) + [kw.value for kw in node.keywords]
+                if isinstance(arg, ast.Name)
+            }
+            for node in ast.walk(func):
+                if not (isinstance(node, ast.Call) and _callee(node.func) in tools):
+                    continue
+                parent = parents.get(node)
+                if isinstance(parent, (ast.keyword, ast.Starred)):
+                    parent = parents.get(parent)
+                if isinstance(parent, ast.Call) and _callee(parent.func) in checkers:
+                    continue
+                if isinstance(parent, ast.Assign) and any(
+                    isinstance(t, ast.Name) and t.id in guarded for t in parent.targets
+                ):
+                    continue
+                unchecked.append(f"{path.name}:{node.lineno}:{_callee(node.func)}")
+
+    assert not unchecked, (
+        "these CLI call sites print a governed write's result without routing it "
+        f"through {sorted(checkers)}, so a refusal exits 0: {unchecked}"
+    )
+
+@pytest.mark.unit
+def test_undetermined_outcome_beats_error_and_is_not_a_plain_failure():
+    """A lost response carries BOTH keys — it must exit 2, not 1.
+
+    ``@tool_errors`` flattens the exception into ``{"error": ...}`` and, when
+    the failure is one where the write may still have landed, also sets
+    ``outcomeUnknown``. The harness deliberately judges unknown *before* error
+    when writing the audit row, for the reason its own note gives: the change
+    may have taken effect, so a blind retry could apply it twice. The CLI has to
+    agree, or the audit says "may have taken effect" while the exit status tells
+    a script it did not happen.
+    """
+    with pytest.raises(typer.Exit) as exc:
+        checked({
+            "error": "connection reset while awaiting the response",
+            "outcomeUnknown": True,
+            "note": "may have taken effect",
+        })
+    assert exc.value.exit_code == 2

{queue_aiops-0.7.0 → queue_aiops-0.8.0}/uv.lock

@@ -812,7 +812,7 @@ wheels = [
 
 [[package]]
 name = "queue-aiops"
-version = "0.7.0"
+version = "0.8.0"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },