stack-guardian 0.1.0__py3-none-any.whl

stack_guardian/serve.py

@@ -0,0 +1,198 @@
+"""Tiny read-only HTTP endpoint for a stack_guardian health snapshot.
+
+One machine asks another for its *current* health by GETting /snapshot; the
+server collects a fresh snapshot on every request, never caches, and refuses
+every write verb.  Binds to loopback unless the caller explicitly opts in to a
+remote bind with allow_remote=True.
+"""
+
+import http.server
+import json
+import sys
+
+LOOPBACK = ("127.0.0.1", "::1", "localhost")
+
+_READ_ONLY = {"error": "read-only: GET /snapshot or /health"}
+
+
+def make_handler(get_snapshot):
+    """Return a BaseHTTPRequestHandler subclass bound to get_snapshot."""
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        server_version = "stack-guardian-serve"
+
+        def _reply(self, code, obj):
+            body = json.dumps(obj, default=str).encode("utf-8")
+            self.send_response(code)
+            if code == 405:
+                self.send_header("Allow", "GET")
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _get(self):
+            path = self.path.split("?", 1)[0]
+            if path == "/health":
+                self._reply(200, {"ok": True})
+            elif path == "/snapshot":
+                try:
+                    snapshot = get_snapshot()
+                except Exception as exc:  # noqa: BLE001 - report, never crash the server
+                    self._reply(500, {"error": "%s: %s" % (type(exc).__name__, exc)})
+                else:
+                    self._reply(200, snapshot)
+            else:
+                self._reply(404, {"error": "not found"})
+
+        def _refuse_write(self):
+            self._reply(405, dict(_READ_ONLY))
+
+        def do_GET(self):  # noqa: N802 - name fixed by BaseHTTPRequestHandler
+            self._get()
+
+        def do_POST(self):  # noqa: N802
+            self._refuse_write()
+
+        def do_PUT(self):  # noqa: N802
+            self._refuse_write()
+
+        def do_DELETE(self):  # noqa: N802
+            self._refuse_write()
+
+        def do_PATCH(self):  # noqa: N802
+            self._refuse_write()
+
+        def log_message(self, *args):
+            pass
+
+    return Handler
+
+
+def make_server(get_snapshot, host="127.0.0.1", port=0, allow_remote=False):
+    """Build (but do not start) a threaded server, refusing non-loopback binds."""
+    if host not in LOOPBACK and not allow_remote:
+        raise ValueError("refusing to bind %s without allow_remote=True" % host)
+    return http.server.ThreadingHTTPServer((host, port), make_handler(get_snapshot))
+
+
+def _opt(argv, name):
+    """Return the token following `name` in argv, or None when there is none."""
+    if name in argv:
+        i = argv.index(name)
+        if i + 1 < len(argv):
+            return argv[i + 1]
+    return None
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if "--selftest" in argv:
+        return _selftest()
+    nodes = _opt(argv, "--nodes")
+    if nodes is None:
+        print("stack-guardian-serve: usage: --nodes FILE [--port N] [--host H --allow-remote]",
+              file=sys.stderr)
+        return 3
+    from . import collect as sg_collect
+
+    def snap():
+        with open(nodes, encoding="utf-8") as fh:
+            return sg_collect.snapshot(json.load(fh))
+
+    server = make_server(snap, _opt(argv, "--host") or "127.0.0.1",
+                         int(_opt(argv, "--port") or "8788"), "--allow-remote" in argv)
+    print("serving http://%s:%d/snapshot" % server.server_address[:2], flush=True)
+    server.serve_forever()
+    return 0
+
+
+def _selftest():
+    import threading
+    import urllib.error
+    import urllib.request
+    state = {"n": 0}
+
+    def snap():
+        state["n"] += 1
+        return {"schema": 1, "taken_at": "T", "nodes": {"a": {"reachable": True}}, "n": state["n"]}
+
+    def boom():
+        raise RuntimeError("collector died")
+
+    def start(fn):
+        s = make_server(fn)
+        threading.Thread(target=s.serve_forever, daemon=True).start()
+        return s, "http://127.0.0.1:%d" % s.server_address[1]
+
+    def get(url, method="GET"):
+        req = urllib.request.Request(url, method=method, data=b"{}" if method != "GET" else None)
+        try:
+            with urllib.request.urlopen(req, timeout=10) as r:
+                return r.status, r.headers.get("Content-Type"), json.loads(r.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            return e.code, e.headers.get("Content-Type"), json.loads(e.read().decode("utf-8"))
+
+    s, base = start(snap)
+    bad, bad_base = start(boom)
+    try:
+        def c_snapshot():
+            code, ctype, body = get(base + "/snapshot")
+            return code == 200 and ctype == "application/json" and body["nodes"] == {"a": {"reachable": True}}
+
+        def c_fresh_each_call():
+            a = get(base + "/snapshot")[2]["n"]
+            b = get(base + "/snapshot?x=1")[2]["n"]
+            return b == a + 1
+
+        def c_health():
+            return get(base + "/health")[:3:2] == (200, {"ok": True})
+
+        def c_not_found():
+            return get(base + "/etc/passwd")[0] == 404
+
+        def c_post_refused():
+            code, _, body = get(base + "/snapshot", "POST")
+            return code == 405 and body["error"].startswith("read-only")
+
+        def c_delete_refused():
+            return get(base + "/snapshot", "DELETE")[0] == 405
+
+        def c_collector_error_500():
+            code, _, body = get(bad_base + "/snapshot")
+            return code == 500 and body["error"] == "RuntimeError: collector died"
+
+        def c_loopback_default():
+            return s.server_address[0] == "127.0.0.1"
+
+        def c_remote_refused():
+            try:
+                make_server(snap, host="0.0.0.0")  # nosec B104 - asserts the refusal; nothing binds
+            except ValueError as exc:
+                return "allow_remote" in str(exc)
+            return False
+
+        checks = [("snapshot", c_snapshot), ("fresh_each_call", c_fresh_each_call), ("health", c_health),
+                  ("not_found", c_not_found), ("post_refused", c_post_refused), ("delete_refused", c_delete_refused),
+                  ("collector_error_500", c_collector_error_500), ("loopback_default", c_loopback_default),
+                  ("remote_refused", c_remote_refused)]
+        passed = failed = 0
+        for name, fn in checks:
+            try:
+                ok = bool(fn())
+            except Exception as exc:  # noqa: BLE001
+                ok = False
+                print("FAIL %s -- raised %s: %s" % (name, type(exc).__name__, exc))
+            else:
+                print(("ok %s" if ok else "FAIL %s") % name)
+            passed += ok
+            failed += not ok
+        print("serve selftest: %d checks, %d passed, %d failed" % (len(checks), passed, failed))
+        return 0 if failed == 0 and checks else 1
+    finally:
+        s.shutdown()
+        bad.shutdown()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

stack_guardian/state.py

@@ -0,0 +1,266 @@
+"""Run history for stack-guardian: the last runs per node, streaks, and confidence grading."""
+import json
+import os
+import shutil
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+STATE_ENV = "STACK_GUARDIAN_STATE"
+KEEP = 5
+BAD = ("WARN", "FAIL")
+
+
+def state_path() -> Path:
+    """Path(os.environ[STATE_ENV]) if that variable is set and non-empty, else Path.home() / ".stack-guardian" / "state.json"."""
+    path = os.environ.get(STATE_ENV, "")
+    if path:
+        return Path(path)
+    return Path.home() / ".stack-guardian" / "state.json"
+
+
+def fresh() -> dict:
+    """a NEW dict every call: {"schema": 1, "nodes": {}}"""
+    return {"schema": 1, "nodes": {}}
+
+
+def load(path=None) -> dict:
+    """path or state_path(); json.loads of the file (utf-8). Missing file, unreadable file, invalid JSON, a non-dict,
+    "schema" != 1, or "nodes" not a dict -> fresh(). Never raises. Anything but a missing file prints one stderr line."""
+    if path is None:
+        path = state_path()
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except FileNotFoundError:
+        return fresh()
+    except (OSError, TypeError, ValueError) as exc:
+        return _discard(path, "%s: %s" % (type(exc).__name__, exc))
+    if not isinstance(data, dict) or data.get("schema") != 1 or not isinstance(data.get("nodes"), dict):
+        return _discard(path, "not a schema 1 state")
+    return data
+
+
+def _discard(path, why):
+    print("stack-guardian: state %s discarded (%s); starting fresh" % (path, why), file=sys.stderr)
+    return fresh()
+
+
+def save(state, path=None) -> None:
+    """path or state_path(); create parent folders; write json.dumps(state, sort_keys=True) to a unique temp file
+    beside it, then os.replace(tmp, path) -- concurrent saves never share a temp file and none is left behind."""
+    if path is None:
+        path = state_path()
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(state, fh, sort_keys=True)
+        for attempt in range(20):
+            try:
+                os.replace(tmp_path, path)
+                break
+            except PermissionError:  # Windows: another save is replacing the same file this instant
+                if attempt == 19:
+                    raise
+                time.sleep(0.01)
+    except Exception:
+        # Clean up the temporary file if something goes wrong
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def record_run(state, node, findings, at) -> dict:
+    """runs = state["nodes"][node]["runs"] (create the levels that are missing); append
+    {"at": at, "codes": {f["code"]: f["level"] for each finding f whose f.get("node", "") is node or ""}}
+    then keep only the last KEEP runs (oldest dropped). Mutates and returns `state`."""
+    if node not in state["nodes"]:
+        state["nodes"][node] = {"runs": []}
+    runs = state["nodes"][node]["runs"]
+    
+    # Filter findings for this node
+    node_findings = [f for f in findings if f.get("node", "") == node or f.get("node", "") == ""]
+    
+    # Create the run entry
+    run_entry = {
+        "at": at,
+        "codes": {f["code"]: f["level"] for f in node_findings}
+    }
+    
+    runs.append(run_entry)
+    
+    # Keep only the last KEEP runs
+    if len(runs) > KEEP:
+        runs[:] = runs[-KEEP:]
+    
+    return state
+
+
+def streak(state, node, code) -> int:
+    """how many of the MOST RECENT runs of `node`, counting back from the newest, have codes[code] in BAD; stop at the first
+    run that does not. Unknown node -> 0."""
+    if node not in state["nodes"]:
+        return 0
+    
+    runs = state["nodes"][node]["runs"]
+    count = 0
+    
+    # Iterate from newest to oldest
+    for run in reversed(runs):
+        if code in run["codes"] and run["codes"][code] in BAD:
+            count += 1
+        else:
+            break
+    
+    return count
+
+
+def clear_streak(state, node, code) -> int:
+    """how many of the most recent runs, counting back from the newest, do NOT have codes[code] in BAD; stop at the first that does."""
+    if node not in state["nodes"]:
+        return 0
+    
+    runs = state["nodes"][node]["runs"]
+    count = 0
+    
+    # Iterate from newest to oldest
+    for run in reversed(runs):
+        if code in run["codes"] and run["codes"][code] in BAD:
+            break
+        else:
+            count += 1
+    
+    return count
+
+
+def grade(state, node, finding) -> dict:
+    """Returns a COPY (dict(finding)); never mutates the input. Only for level in BAD:
+    streak(state, node, finding["code"]) >= 2 -> confidence "VERIFIED";
+    otherwise a "VERIFIED" confidence becomes "LIKELY" (LIKELY and INSUFFICIENT stay).
+    Call it AFTER record_run for the current run (the current run counts as one sample). Other levels: copy unchanged."""
+    result = dict(finding)
+    
+    if finding["level"] in BAD:
+        st = streak(state, node, finding["code"])
+        if st >= 2:
+            result["confidence"] = "VERIFIED"
+        elif result["confidence"] == "VERIFIED":
+            result["confidence"] = "LIKELY"
+    
+    return result
+
+
+def due(state, node, code, fail_after=1) -> bool:
+    """streak(state, node, code) >= fail_after"""
+    return streak(state, node, code) >= fail_after
+
+
+def _selftest():
+    tmp = tempfile.mkdtemp()
+    old_env = os.environ.get(STATE_ENV)
+    try:
+        def f(code, level="FAIL", node="gpu-box", confidence="VERIFIED"):
+            return {"code": code, "level": level, "node": node, "confidence": confidence}
+
+        def t_missing_file_fresh():
+            return load(os.path.join(tmp, "absent.json")) == {"schema": 1, "nodes": {}}
+
+        def t_corrupt_file_fresh():
+            p = os.path.join(tmp, "bad.json")
+            with open(p, "w", encoding="utf-8") as fh:
+                fh.write("{not json")
+            return load(p) == {"schema": 1, "nodes": {}}
+
+        def t_save_load_roundtrip():
+            p = os.path.join(tmp, "sub", "s.json")
+            s = record_run(fresh(), "gpu-box", [f("x.y")], "2026-10-03T18:00:00")
+            save(s, p)
+            return load(p) == s and not os.path.exists(p + ".tmp")
+
+        def t_keeps_last_5():
+            s = fresh()
+            for i in range(7):
+                record_run(s, "gpu-box", [], "t%d" % i)
+            runs = s["nodes"]["gpu-box"]["runs"]
+            return len(runs) == KEEP and runs[0]["at"] == "t2" and runs[-1]["at"] == "t6"
+
+        def t_other_node_ignored():
+            s = record_run(fresh(), "gpu-box", [f("a.b", node="gpu-box-2"), f("c.d")], "t0")
+            return s["nodes"]["gpu-box"]["runs"][0]["codes"] == {"c.d": "FAIL"}
+
+        def t_streak_counts_recent_bad_runs():
+            s = fresh()
+            record_run(s, "gpu-box", [f("x.y")], "t0")
+            record_run(s, "gpu-box", [], "t1")
+            record_run(s, "gpu-box", [f("x.y", "WARN")], "t2")
+            record_run(s, "gpu-box", [f("x.y")], "t3")
+            return streak(s, "gpu-box", "x.y") == 2 and clear_streak(s, "gpu-box", "x.y") == 0
+
+        def t_one_sample_is_likely_at_most():
+            s = record_run(fresh(), "gpu-box", [f("x.y")], "t0")
+            return grade(s, "gpu-box", f("x.y"))["confidence"] == "LIKELY"
+
+        def t_two_samples_verified():
+            s = fresh()
+            record_run(s, "gpu-box", [f("x.y", confidence="LIKELY")], "t0")
+            record_run(s, "gpu-box", [f("x.y", confidence="LIKELY")], "t1")
+            return grade(s, "gpu-box", f("x.y", confidence="LIKELY"))["confidence"] == "VERIFIED"
+
+        def t_ok_finding_untouched():
+            s = record_run(fresh(), "gpu-box", [f("x.ok", "OK")], "t0")
+            return grade(s, "gpu-box", f("x.ok", "OK"))["confidence"] == "VERIFIED"
+
+        def t_due_respects_fail_after():
+            s = fresh()
+            record_run(s, "gpu-box", [f("x.y")], "t0")
+            first = due(s, "gpu-box", "x.y", fail_after=2)
+            record_run(s, "gpu-box", [f("x.y")], "t1")
+            return first is False and due(s, "gpu-box", "x.y", fail_after=2) is True
+
+        def t_env_path():
+            os.environ[STATE_ENV] = os.path.join(tmp, "env.json")
+            return state_path() == Path(tmp) / "env.json"
+
+        checks = [
+            ("missing_file_fresh", t_missing_file_fresh),
+            ("corrupt_file_fresh", t_corrupt_file_fresh),
+            ("save_load_roundtrip", t_save_load_roundtrip),
+            ("keeps_last_5", t_keeps_last_5),
+            ("other_node_ignored", t_other_node_ignored),
+            ("streak_counts_recent_bad_runs", t_streak_counts_recent_bad_runs),
+            ("one_sample_is_likely_at_most", t_one_sample_is_likely_at_most),
+            ("two_samples_verified", t_two_samples_verified),
+            ("ok_finding_untouched", t_ok_finding_untouched),
+            ("due_respects_fail_after", t_due_respects_fail_after),
+            ("env_path", t_env_path),
+        ]
+        passed = 0
+        for name, fn in checks:
+            try:
+                ok = bool(fn())
+            except Exception as exc:  # noqa: BLE001 - a crashed check is a failed check
+                ok = False
+                name = "%s (raised %s: %s)" % (name, type(exc).__name__, exc)
+            passed += ok
+            print(("ok   " if ok else "FAIL ") + name)
+        failed = len(checks) - passed
+        print("sg_state selftest: %d checks, %d passed, %d failed" % (len(checks), passed, failed))
+        return 0 if failed == 0 and checks else 1
+    finally:
+        if old_env is None:
+            os.environ.pop(STATE_ENV, None)
+        else:
+            os.environ[STATE_ENV] = old_env
+
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    if "--selftest" in sys.argv:
+        sys.exit(_selftest())
+    print(json.dumps(load(), indent=1))

stack_guardian-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: stack-guardian
+Version: 0.1.0
+Summary: A health doctor for a home AI stack: Ollama nodes, GPUs and tailnet, with graded confidence.
+Author: LuminariSoftwares
+License: MIT
+Project-URL: Homepage, https://github.com/LuminariSoftwares/stack-guardian
+Project-URL: Issues, https://github.com/LuminariSoftwares/stack-guardian/issues
+Project-URL: Changelog, https://github.com/LuminariSoftwares/stack-guardian/blob/main/CHANGELOG.md
+Keywords: ollama,gpu,vram,tailscale,health-check,local-llm,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# stack-guardian
+
+[![ci](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/ci.yml)
+[![privacy](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/privacy.yml/badge.svg)](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/privacy.yml)
+
+A health doctor for a home AI stack. It collects a snapshot of your nodes (Ollama endpoints, loaded models, NVIDIA
+GPUs, tailnet peers), runs small Python rules against it, remembers the last runs, and reports findings with a
+confidence grade: one sample is at most `LIKELY`, the same finding twice in a row is `VERIFIED`. A finding can carry a
+typed fix that you run on purpose, never automatically.
+
+Status: **0.1.0, first release.** Standard library only, Python 3.11+.
+
+## Install
+
+```
+pip install stack-guardian
+```
+
+This gives you three commands: `stack-guardian` (the CLI), `stack-guardian-serve` and `stack-guardian-mcp`.
+
+Try it offline first: the example snapshot makes every shipped rule fire once.
+
+```
+curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/snapshot.json
+curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/ctx.json
+stack-guardian doctor --snapshot snapshot.json --ctx ctx.json
+```
+
+From a clone instead (for writing rules or running the tests):
+
+```
+git clone https://github.com/LuminariSoftwares/stack-guardian.git
+cd stack-guardian
+python -m venv .venv
+.venv\Scripts\activate          # Windows;  macOS/Linux: source .venv/bin/activate
+pip install -e .
+stack-guardian doctor --snapshot examples/snapshot.json --ctx examples/ctx.json
+```
+
+## For coding agents
+
+- **MCP server** (any MCP client): `stack-guardian-mcp` speaks MCP over stdio with three read-only tools,
+  `stack_health`, `stack_snapshot` and `explain`. In Claude Code:
+
+  ```
+  claude mcp add stack-guardian -e STACK_GUARDIAN_NODES=/path/to/nodes.json -- stack-guardian-mcp
+  ```
+
+  Other clients: command `stack-guardian-mcp`, args `["--nodes", "/path/to/nodes.json"]`. `stack_health` grades
+  against the saved run history without adding to it, and reuses one snapshot for 10 s (`--ttl SECONDS`).
+- **DSH plugin** (`npm install dsh-stack-guardian`, source in `dsh/`, Node 20+): adds one line at the start of a DeepSeek Harness session when the doctor reports
+  WARN or FAIL, and nothing otherwise. It runs `stack-guardian doctor --json --quiet`, so set `STACK_GUARDIAN_NODES`
+  to your nodes file in the harness environment.
+
+## What it does
+
+### 1. `doctor` - run the checks
+
+Describe your nodes in a JSON file (see [examples/nodes.json](examples/nodes.json)) and check them live:
+
+```
+stack-guardian doctor --nodes examples/nodes.json --ctx examples/ctx.json
+```
+
+With neither `--snapshot` nor `--nodes`, `doctor` reads the nodes file named by `$STACK_GUARDIAN_NODES`.
+
+Options: `--checks-dir DIR` (your own rules, default is the shipped `checks.d`), `--ctx FILE` (rule settings such as
+the model each node is expected to hold), `--state FILE` (default `$STACK_GUARDIAN_STATE` or
+`~/.stack-guardian/state.json`), `--json`, `--quiet` (print nothing when all is OK).
+
+Exit codes: `0` all OK/INFO, `1` a WARN, `2` a FAIL, `3` usage, `4` the doctor itself crashed.
+
+Shipped rules: `node.unreachable`, `ollama.unreachable`, `model.not_loaded`, `vram.unattributed`, `gpu.unavailable`,
+`tailnet.unavailable`, `tailnet.peer_offline`, `tailnet.relayed`. Each raises one finding per affected node. A rule that
+raises becomes a `check.crashed` WARN - a buggy rule never reports a broken stack.
+
+### 2. `doctor --fix ID` - run a finding's typed fix
+
+A rule may attach `fix={"action": ..., "args": {...}}` to a finding. There are exactly three actions and never a raw
+shell string:
+
+| action | what it does | needs |
+|---|---|---|
+| `unload_model` | POST `keep_alive: 0` to an Ollama `/api/generate` | `node`, `url`, `model` |
+| `restart_lane` | runs the argv list you declared for that lane | `lane` declared in `--config` |
+| `set_env` | writes `NAME=value` to `<state folder>/env` and sets it for the process | `name`, `value` |
+
+```
+stack-guardian doctor --checks-dir examples/checks.d --snapshot examples/snapshot.json --fix ollama.stuck --config examples/lanes.json
+```
+
+That is a **dry run**: it prints the plan and changes nothing. Add `--apply` to perform it. An applied fix first saves
+the snapshot under `<state folder>/snapshots/`, then runs, then appends one JSON line to `<state folder>/fixes.jsonl`
+(`--audit FILE` to move it). A `set_env` value is never written to the audit, only its length. `ID` is the finding
+code, or `code@node` when several nodes raise the same code. With `--fix`, the exit code is the fix's: `0` plan or
+success, `1` refused or failed, `3` usage.
+
+### 3. Other commands
+
+- `stack-guardian snapshot --nodes FILE` prints the raw snapshot the rules read.
+- `stack-guardian-serve --nodes FILE [--port 8788]` serves a fresh snapshot at `GET /snapshot` (read-only, loopback
+  unless you pass `--host H --allow-remote`), so one machine can ask another for its health.
+  no auth: bind to localhost or a tailnet IP only.
+- `stack-guardian-mcp --nodes FILE [--ctx FILE] [--state FILE] [--ttl SECONDS]`: see [For coding agents](#for-coding-agents).
+
+## Writing a rule
+
+```python
+from stack_guardian import finding as F
+
+def ollama_up(snapshot, ctx):
+    if not snapshot["nodes"]["gpu-box"].get("reachable"):
+        return F.make_finding("ollama.unreachable", "missing", "FAIL", "gpu-box", "Ollama does not answer")
+    return None
+
+CHECKS = [("ollama.up", ollama_up)]
+```
+
+Drop the file in a folder and point `--checks-dir` at it. A full example with a fix is in
+[examples/checks.d/20_ollama_fix.py](examples/checks.d/20_ollama_fix.py). A rule may also return a list of findings,
+one per node.
+
+## Examples
+
+| file | what it is |
+|---|---|
+| `examples/nodes.json` | three nodes: a local one with GPUs, two remote ones over the tailnet |
+| `examples/ctx.json` | rule settings: which model gpu-box-2 should hold |
+| `examples/snapshot.json` | an offline snapshot on which every shipped rule fires once, for trying `doctor` and `--fix` |
+| `examples/lanes.json` | the lanes `restart_lane` is allowed to run |
+| `examples/checks.d/20_ollama_fix.py` | a custom rule whose finding carries a fix |
+
+## Test
+
+```
+pip install pytest
+python -m pytest -q
+```
+
+CI runs this on Ubuntu, Windows and macOS with Python 3.11, plus a privacy scan of every tracked file.
+
+## License
+
+MIT

stack_guardian-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+stack_guardian/__init__.py,sha256=T3q-qBicefSvI0yTpw112QZ33IqkIjPVF4TodgQWO9g,496
+stack_guardian/__main__.py,sha256=ibl4GU_04RgSpLteRQsvqE5RZw4s2n1_Cph0hHqkmGw,94
+stack_guardian/cli.py,sha256=3JxijTGy_pWq_yWTzv-Fh0j_RjkYScGqMSk9m-bN6Ws,13462
+stack_guardian/collect.py,sha256=56SfzV0RwiLsJTFhrkw2gzdxMweacVbOdLYtqjwDHzE,8799
+stack_guardian/core.py,sha256=eRWpjWWRpSIn3inEz3oDkCNhwTrxV7yW53lQLVEPeSM,8841
+stack_guardian/finding.py,sha256=QdnHq0ecNGMxrhRgpWgiy-wf_4Ho-Tzut5A3ecBmilw,16032
+stack_guardian/fixes.py,sha256=okQPfm4Yd3bVm57WA4lUUGoXRHbLwWcAP_L8AFk2WW0,12912
+stack_guardian/mcp_server.py,sha256=i4WhO451NJcy237fqfIVj1sIUh1VYxueB94hOPPAzIY,15701
+stack_guardian/multinode.py,sha256=t8GWoQP6Tnu6mv20A0jSkHi1jnrtLjvKISKAM3eSNig,6175
+stack_guardian/parsers.py,sha256=wUmfQrrDDNrmH0jXLQeM6hiOvDXKec2x_8odRQHs8vs,26281
+stack_guardian/serve.py,sha256=2-KnIdHC0e8to6tTVEmk-pVQFXdtbgPorWBTuiT_npk,7026
+stack_guardian/state.py,sha256=kh_9cgxqk2EMSsC_uFiJ7e6585Ij54PL3q2owOysnmA,9965
+stack_guardian/checks.d/10_core.py,sha256=gZ0PAz6ZPzRhayO1q58WouBmQtivAxvU7rBPCYioQ9s,8428
+stack_guardian-0.1.0.dist-info/licenses/LICENSE,sha256=fZftfP7aXYDvruO-a2SUD2UxszjndCeOA8u0pXRjQS8,1074
+stack_guardian-0.1.0.dist-info/METADATA,sha256=QzhI-i-f47Xv-7ju-TC4MYIEzqGuLAkHLFU-Xuefo4s,7388
+stack_guardian-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+stack_guardian-0.1.0.dist-info/entry_points.txt,sha256=0RxeHy2S0emvaG_zUmYE0DwKeCq6Q5V7zxUf3lo9zx4,160
+stack_guardian-0.1.0.dist-info/top_level.txt,sha256=7J59zP8x8_DwTUFQiW-Grx_r2Cn_j-jDZYtn1q5lHgk,15
+stack_guardian-0.1.0.dist-info/RECORD,,

stack_guardian-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stack_guardian-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+stack-guardian = stack_guardian.cli:main
+stack-guardian-mcp = stack_guardian.mcp_server:main
+stack-guardian-serve = stack_guardian.serve:main

stack_guardian-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LuminariSoftwares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.