macverdict 0.2.0__py3-none-any.whl

macverdict/__init__.py

@@ -0,0 +1,8 @@
+"""macverdict: tells you why your Mac was slow, and what to do about it. (Formerly macpulse.)"""
+
+__version__ = "0.2.0"
+
+from .checks import Finding, evaluate, health_score
+from .collectors import collect
+
+__all__ = ["collect", "evaluate", "health_score", "Finding", "__version__"]

macverdict/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

macverdict/checks.py

@@ -0,0 +1,147 @@
+"""Turn a snapshot into findings with plain-English advice, and a 0-100 score."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from .fmt import human_bytes
+
+GB = 1024 ** 3
+LEVELS = ("ok", "info", "warn", "critical")
+PENALTY = {"ok": 0, "info": 2, "warn": 10, "critical": 25}
+
+
+@dataclass
+class Finding:
+    level: str  # one of LEVELS
+    area: str
+    message: str
+    advice: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _cpu(s: dict) -> list[Finding]:
+    cpu, cores = s["cpu"], s["system"]["cpu_count"] or 1
+    load_ratio = cpu["load_avg"][1] / cores
+    out = []
+    if cpu["percent"] >= 90:
+        out.append(Finding("warn", "cpu", f"CPU is busy at {cpu['percent']:.0f}%.",
+                           "Check the top CPU processes below; quit anything you are not using."))
+    if load_ratio >= 1.5:
+        out.append(Finding("warn", "cpu", f"5-minute load is {cpu['load_avg'][1]:.1f} on {cores} cores.",
+                           "Sustained load above core count means work is queuing up."))
+    if not out:
+        out.append(Finding("ok", "cpu", f"CPU {cpu['percent']:.0f}%, load {cpu['load_avg'][1]:.1f} on {cores} cores."))
+    for p in s.get("top_cpu", [])[:1]:
+        if p["cpu_percent"] >= 80:
+            out.append(Finding("info", "cpu", f"{p['name']} (pid {p['pid']}) is using {p['cpu_percent']:.0f}% CPU.",
+                               "Expected if it is doing real work; otherwise it may be stuck."))
+    return out
+
+
+def _memory(s: dict) -> list[Finding]:
+    m = s["memory"]
+    level = (m.get("pressure") or {}).get("level")
+    swap = m["swap_used"]
+    out = []
+    if level == "critical":
+        out.append(Finding("critical", "memory", "Memory pressure is CRITICAL.",
+                           "macOS is compressing and swapping heavily. Close large apps or browser tabs."))
+    elif level == "warn":
+        out.append(Finding("warn", "memory", "Memory pressure is elevated.",
+                           "Close apps you are not using; this is the main cause of slowdowns on 8-16 GB Macs."))
+    if swap >= 6 * GB:
+        out.append(Finding("critical", "memory", f"Swap in use: {human_bytes(swap)}.",
+                           "Heavy swapping wears the SSD and slows everything. A restart clears it."))
+    elif swap >= 2 * GB:
+        out.append(Finding("warn", "memory", f"Swap in use: {human_bytes(swap)}.",
+                           "Some swapping is normal, but sustained growth means you need more free RAM."))
+    if not out:
+        out.append(Finding("ok", "memory", f"Memory pressure {level or 'n/a'}, {m['percent']:.0f}% used, "
+                                           f"swap {human_bytes(swap)}."))
+    biggest = (s.get("apps") or s.get("top_memory") or [])[:1]
+    for p in biggest:
+        if p["rss"] >= 0.25 * m["total"]:
+            out.append(Finding("info", "memory", f"{p['name']} is using {human_bytes(p['rss'])} of RAM.",
+                               "Restarting a long-running app often returns leaked memory."))
+    return out
+
+
+def _disk(s: dict) -> list[Finding]:
+    d = s["disk"]
+    pct, free = d["free_percent"], d["free"]
+    if pct < 5 or free < 10 * GB:
+        return [Finding("critical", "disk", f"Only {human_bytes(free)} free ({pct:.0f}%).",
+                        "macOS needs free space for swap and updates. Clear Downloads, caches, or old iOS backups.")]
+    if pct < 15:
+        return [Finding("warn", "disk", f"Disk is getting full: {human_bytes(free)} free ({pct:.0f}%).",
+                        "Use System Settings > General > Storage to find large files.")]
+    return [Finding("ok", "disk", f"{human_bytes(free)} free ({pct:.0f}%).")]
+
+
+def _battery(s: dict) -> list[Finding]:
+    b = s.get("battery")
+    if not b:
+        return []
+    out = []
+    health = b.get("max_capacity_percent") or b.get("health_percent")
+    if health is not None and health < 80:
+        out.append(Finding("warn", "battery", f"Battery maximum capacity is {health:.0f}%.",
+                           "Apple considers batteries below 80% consumed; consider a service appointment."))
+    if (b.get("cycle_count") or 0) >= 1000:
+        out.append(Finding("info", "battery", f"Battery has {b['cycle_count']} cycles (rated for 1000).", ""))
+    temp = b.get("temperature_c")
+    if temp is not None and temp >= 45:
+        out.append(Finding("critical", "battery", f"Battery is hot: {temp:.0f}°C.",
+                           "Move the Mac off soft surfaces and out of the sun; stop heavy work until it cools."))
+    elif temp is not None and temp >= 38:
+        out.append(Finding("warn", "battery", f"Battery is warm: {temp:.0f}°C.",
+                           "The MacBook Air is fanless, so sustained heat leads to throttling."))
+    if not out:
+        out.append(Finding("ok", "battery", f"{b['percent']:.0f}% charged, capacity {health}%, "
+                                            f"{b.get('cycle_count')} cycles, {temp}°C."))
+    return out
+
+
+def _thermal(s: dict) -> list[Finding]:
+    t = s["thermal"]
+    state = t.get("state")
+    if state == "critical":
+        return [Finding("critical", "thermal", "macOS reports CRITICAL heat and is slowing the Mac hard.",
+                        "Stop heavy work now and give it airflow: hard surface, out of the sun.")]
+    if t["throttled"]:
+        detail = f"limited to {t['cpu_speed_limit']}% speed" if t["cpu_speed_limit"] < 100 else "thermal state is serious"
+        return [Finding("warn", "thermal", f"Your Mac is slowing itself down to cool off ({detail}).",
+                        "Reduce load or improve airflow. On a fanless MacBook Air this is the main cause of "
+                        "slowdowns during long heavy tasks.")]
+    if state == "fair":
+        return [Finding("info", "thermal", "Your Mac is warm (thermal state: fair).",
+                        "Not slowing down yet, but sustained heavy work may start throttling.")]
+    return [Finding("ok", "thermal", "No thermal throttling.")]
+
+
+def _uptime(s: dict) -> list[Finding]:
+    days = (s["timestamp"] - s["system"]["boot_time"]) / 86400
+    if days >= 14:
+        return [Finding("info", "uptime", f"Up for {days:.0f} days.",
+                        "A restart clears swap, leaked memory and pending updates.")]
+    return []
+
+
+RULES = (_cpu, _memory, _disk, _battery, _thermal, _uptime)
+
+
+def evaluate(snapshot: dict) -> list[Finding]:
+    findings = [f for rule in RULES for f in rule(snapshot)]
+    return sorted(findings, key=lambda f: -LEVELS.index(f.level))
+
+
+def health_score(findings: list[Finding]) -> int:
+    return max(0, 100 - sum(PENALTY[f.level] for f in findings))
+
+
+def worst_level(findings: list[Finding]) -> str:
+    return max((f.level for f in findings), key=LEVELS.index, default="ok")

macverdict/cli.py

@@ -0,0 +1,336 @@
+"""Command-line interface: `macverdict check | record | report | history | schedule | export`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import webbrowser
+from pathlib import Path
+
+from . import __version__, insights, notifier, report, scheduler, storage
+from .checks import evaluate, health_score, worst_level
+from .collectors import collect
+from .fmt import color, days_label, human_bytes, human_duration
+
+
+def _print_check(snap: dict, findings: list, score: int) -> None:
+    s = snap["system"]
+    tone = "ok" if score >= 85 else "warn" if score >= 60 else "critical"
+    print(color(f"macverdict · {s.get('chip')} · macOS {s.get('macos')} · "
+                f"{human_bytes(s['memory_total'])} RAM · up {human_duration(snap['timestamp'] - s['boot_time'])}", "dim"))
+    print(f"\nHealth score: {color(str(score), tone)} / 100\n")
+    for f in findings:
+        print(f"  {color(f.level.upper().ljust(8), f.level)} {f.area.ljust(8)} {f.message}")
+        if f.advice and f.level != "ok":
+            print(color(f"  {'':8} {'':8} → {f.advice}", "dim"))
+    def procs(a: dict) -> str:
+        n = a.get("processes", 1)
+        return color(f"  ({n} processes)", "dim") if n > 1 else ""
+
+    print(color("\n  Top CPU", "bold"))
+    for a in insights.apps_in(snap, "cpu_percent")[:3]:
+        print(f"    {a['cpu_percent']:6.1f}%  {a['name']}{procs(a)}")
+    print(color("  Top memory", "bold"))
+    for a in insights.apps_in(snap, "rss")[:3]:
+        print(f"    {human_bytes(a['rss']):>9}  {a['name']}{procs(a)}")
+    print()
+
+
+def cmd_setup(args) -> int:
+    """Everything a new user needs, in one command."""
+    print("Setting up macverdict on this Mac...\n")
+    if storage.legacy_dir().exists():
+        if (storage.data_dir() / "history.db").exists():
+            print(color("  ✓", "ok"), "Your history from macpulse (macverdict's old name) is here; "
+                  "the old folder is kept as a backup.")
+        removed = scheduler.remove_legacy()
+        if removed:
+            print(color("  ✓", "ok"), f"Removed macpulse's old {' and '.join(removed)}.")
+    if args.no_notify:
+        print(color("  -", "dim"), "Alerts turned off (--no-notify).")
+    else:
+        try:
+            notifier.install()
+            print(color("  ✓", "ok"), "Built the macverdict alert app (clicking an alert opens your report).")
+        except RuntimeError as e:
+            print(color("  -", "dim"), f"Skipped clickable alerts: {e}")
+            print(color("    ", "dim"), "Alerts still work; they just open Script Editor when clicked.")
+    scheduler.install(args.every, notify=not args.no_notify)
+    shown_as = '"macverdict"' if notifier.is_installed() else '"python3"'
+    print(color("  ✓", "ok"), f"Recording in the background every {args.every} minutes "
+          f"(listed as {shown_as} in System Settings > General > Login Items).")
+    if not args.no_notify:
+        if notifier.is_installed():
+            status = notifier.send("macverdict is set up", "You'll only hear from macverdict when something is "
+                                   "critical. Click to see your report.", notifier.report_command(), timeout=60)
+            if status == "ok":
+                print(color("  ✓", "ok"), "Sent a test alert, and macOS is allowing alerts from macverdict.")
+            else:
+                print(color("  !", "warn"), f"The test alert didn't go through ({status}).")
+                print("    Allow alerts in System Settings > Notifications > macverdict, then run `macverdict notify-test`.")
+        else:
+            scheduler.notify("macverdict is set up", "You'll only hear from macverdict when something is critical.",
+                             open_report=False)
+            print(color("  ✓", "ok"), "Sent a test alert.")
+    print("\nDone. Try these:")
+    print("  macverdict            check your Mac right now")
+    print("  macverdict insights   why it was slow, RAM verdict, battery forecast (best after a few days)")
+    print("  macverdict report     everything in your browser")
+    print("  macverdict uninstall  stop and remove the background parts")
+    return 0
+
+
+def cmd_uninstall(args) -> int:
+    agent = scheduler.uninstall()
+    app = notifier.uninstall()
+    print("Stopped background recording." if agent else "Background recording wasn't on.")
+    if app:
+        print("Removed the macverdict alert app.")
+    print(f"Your history is kept in {storage.data_dir()}; delete that folder to remove it too.")
+    print("To remove the command itself: brew uninstall macverdict, pipx uninstall macverdict, "
+          "or uv tool uninstall macverdict (whichever you used).")
+    return 0
+
+
+def cmd_check(args) -> int:
+    snap = collect(args.interval)
+    findings = evaluate(snap)
+    score = health_score(findings)
+    if args.json:
+        print(json.dumps({"score": score, "findings": [f.to_dict() for f in findings], "snapshot": snap}, indent=2))
+    else:
+        _print_check(snap, findings, score)
+        if not scheduler.status()["installed"]:
+            print(color("Tip: run `macverdict setup` to record in the background and unlock `macverdict insights`.\n",
+                        "dim"))
+    if args.save:
+        with storage.connect() as conn:
+            storage.save(conn, snap, findings, score)
+    return 2 if worst_level(findings) == "critical" else 0
+
+
+def cmd_record(args) -> int:
+    snap = collect(args.interval)
+    findings = evaluate(snap)
+    score = health_score(findings)
+    with storage.connect() as conn:
+        storage.save(conn, snap, findings, score)
+        storage.prune(conn, args.keep_days)
+    if args.notify:
+        bad = [f for f in findings if f.level in ("warn", "critical")]
+        if any(f.level == "critical" for f in bad):
+            scheduler.notify(f"macverdict: health {score}/100", "; ".join(f.message for f in bad[:2]))
+    if not args.quiet:
+        print(f"recorded: score {score}, cpu {snap['cpu']['percent']:.0f}%, "
+              f"pressure {snap['memory']['pressure']['level']}, swap {human_bytes(snap['memory']['swap_used'])}")
+    return 0
+
+
+INSIGHT_STYLE = {"good": "ok", "ok": "info", "attention": "warn"}
+
+
+def cmd_insights(args) -> int:
+    with storage.connect() as conn:
+        rows = storage.load(conn, args.days, full=True)
+    if not rows:
+        print("No history yet. Run `macverdict schedule install` and check back in a day or two.")
+        return 0
+    memory_total = rows[-1]["snapshot"]["system"]["memory_total"]
+    model = insights.hardware_model()
+    found = insights.build(rows, memory_total, model)
+    if args.json:
+        print(json.dumps([i.to_dict() for i in found], indent=2))
+        return 0
+    print(color(f"macverdict insights · {model or 'Mac'} · {human_bytes(memory_total)} RAM · "
+                f"last {days_label(args.days)}", "dim"))
+    for i in found:
+        style = INSIGHT_STYLE[i.level]
+        print(f"\n{color('●', style)} {color(i.title, 'bold')}")
+        print(f"  {color(i.headline, style)}")
+        for d in i.details:
+            print(f"    · {d}")
+        if i.confidence:
+            print(color(f"    {i.confidence}", "dim"))
+    print()
+    return 0
+
+
+def cmd_report(args) -> int:
+    snap = collect(args.interval)
+    findings = evaluate(snap)
+    with storage.connect() as conn:
+        storage.save(conn, snap, findings, health_score(findings))
+        rows = storage.load(conn, args.days, full=True)
+    found = insights.build(rows, snap["system"]["memory_total"], insights.hardware_model())
+    out = Path(args.out) if args.out else storage.data_dir() / "report.html"
+    out.write_text(report.build(rows, snap, findings, args.days, found))
+    print(f"Report written to {out}")
+    if not args.no_open:
+        webbrowser.open(out.resolve().as_uri())
+    return 0
+
+
+def cmd_history(args) -> int:
+    with storage.connect() as conn:
+        rows = storage.load(conn, args.days)
+    if not rows:
+        print("No history yet. Run `macverdict record`, or `macverdict schedule install` to record automatically.")
+        return 0
+    metrics = [("score", "Health score", ""), ("cpu_percent", "CPU %", ""), ("mem_percent", "Memory %", ""),
+               ("swap_used", "Swap", "bytes"), ("disk_free_percent", "Disk free %", ""),
+               ("battery_temp_c", "Battery °C", "")]
+    print(f"{len(rows)} samples over the last {days_label(args.days)}\n")
+    print(f"  {'metric':<14}{'min':>10}{'avg':>10}{'max':>10}")
+    for key, label, kind in metrics:
+        vals = [r[key] for r in rows if r[key] is not None]
+        if not vals:
+            continue
+        lo, avg, hi = min(vals), sum(vals) / len(vals), max(vals)
+        f = human_bytes if kind == "bytes" else (lambda v: f"{v:.1f}")
+        print(f"  {label:<14}{f(lo):>10}{f(avg):>10}{f(hi):>10}")
+    pressures = [r["pressure"] for r in rows]
+    elevated = sum(p in ("warn", "critical") for p in pressures)
+    print(f"\n  Memory pressure elevated in {elevated}/{len(rows)} samples; "
+          f"throttled in {sum(r['throttled'] or 0 for r in rows)}/{len(rows)}.")
+    return 0
+
+
+def cmd_schedule(args) -> int:
+    if args.action == "install":
+        path = scheduler.install(args.every, notify=not args.no_notify)
+        print(f"Installed launchd agent ({path}); recording every {args.every} min.")
+        print(f"Data: {storage.data_dir()}")
+        if not args.no_notify and not notifier.is_installed():
+            print("Tip: run `macverdict notifier install` so alerts open your report when clicked.")
+    elif args.action == "remove":
+        print("Removed launchd agent." if scheduler.uninstall() else "No agent was installed.")
+    else:
+        st = scheduler.status()
+        if not st["installed"]:
+            print("Not scheduled. Run `macverdict schedule install`.")
+        else:
+            print(f"Scheduled every {st['every_minutes']} min · loaded: {st['loaded']} · {st['plist']}")
+    return 0
+
+
+def cmd_notify_test(args) -> int:
+    if not notifier.is_installed():
+        scheduler.notify("macverdict test", "Notifications work.", open_report=False)
+        print("Sent with osascript (shown as Script Editor; clicking opens Script Editor).\n"
+              "For banners that open your report when clicked: macverdict notifier install\n"
+              "No banner? Allow notifications for Script Editor in System Settings > Notifications.")
+        return 0
+    status = notifier.send("macverdict test", "Notifications work. Click to open your report.",
+                           notifier.report_command(), timeout=60)
+    if status == "ok":
+        print("Sent. Click the banner to open your macverdict report.")
+        return 0
+    print(f"The macverdict notifier couldn't post ({status}).\n"
+          "Allow it in System Settings > Notifications > macverdict, then run this again.")
+    return 1
+
+
+def cmd_notifier(args) -> int:
+    if args.action == "install":
+        try:
+            path = notifier.install()
+        except RuntimeError as e:
+            print(e, file=sys.stderr)
+            return 1
+        print(f"Built {path}.")
+        if scheduler.refresh():
+            print("Background agent now runs as \"macverdict\" in System Settings > General > Login Items.")
+        print("Run `macverdict notify-test` and click Allow if macOS asks.")
+    elif args.action == "remove":
+        print("Removed the notifier." if notifier.uninstall() else "The notifier wasn't installed.")
+        scheduler.refresh()
+    else:
+        print(f"Installed at {notifier.app_path()}" if notifier.is_installed()
+              else "Not installed. Run `macverdict notifier install` (needs Xcode Command Line Tools).")
+    return 0
+
+
+def cmd_export(args) -> int:
+    with storage.connect() as conn:
+        rows = storage.load(conn, args.days)
+    storage.export_csv(rows, Path(args.out))
+    print(f"Exported {len(rows)} rows to {args.out}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="macverdict", description="Performance diagnostics and history for your Mac.")
+    p.add_argument("--version", action="version", version=f"macverdict {__version__}")
+    sub = p.add_subparsers(dest="command")
+
+    def add(name, func, help_):
+        sp = sub.add_parser(name, help=help_)
+        sp.set_defaults(func=func)
+        sp.add_argument("--interval", type=float, default=1.0, help="seconds to sample CPU/IO rates (default 1)")
+        return sp
+
+    st = sub.add_parser("setup", help="one-step setup: background recording and alerts")
+    st.add_argument("--every", type=int, default=15, help="minutes between samples (default 15)")
+    st.add_argument("--no-notify", action="store_true", help="never show alerts")
+    st.set_defaults(func=cmd_setup)
+
+    un = sub.add_parser("uninstall", help="stop background recording and remove the alert app")
+    un.set_defaults(func=cmd_uninstall)
+
+    c = add("check", cmd_check, "diagnose this Mac right now (default)")
+    c.add_argument("--json", action="store_true", help="print machine-readable JSON")
+    c.add_argument("--save", action="store_true", help="also store this sample in history")
+
+    r = add("record", cmd_record, "take a sample and store it (used by the scheduler)")
+    r.add_argument("--notify", action="store_true", help="show a macOS notification on critical findings")
+    r.add_argument("--quiet", action="store_true")
+    r.add_argument("--keep-days", type=float, default=90, help="delete samples older than this (default 90)")
+
+    rp = add("report", cmd_report, "build an HTML report with trends and open it")
+    rp.add_argument("--days", type=float, default=7)
+    rp.add_argument("--out", help="output path (default: data folder/report.html)")
+    rp.add_argument("--no-open", action="store_true")
+
+    ins = sub.add_parser("insights", help="why your Mac was slow, RAM verdict, battery forecast, throttling")
+    ins.add_argument("--days", type=float, default=30)
+    ins.add_argument("--json", action="store_true")
+    ins.set_defaults(func=cmd_insights)
+
+    h = sub.add_parser("history", help="summarise stored samples in the terminal")
+    h.add_argument("--days", type=float, default=7)
+    h.set_defaults(func=cmd_history)
+
+    s = sub.add_parser("schedule", help="record automatically with launchd")
+    s.add_argument("action", choices=["install", "remove", "status"])
+    s.add_argument("--every", type=int, default=15, help="minutes between samples (default 15)")
+    s.add_argument("--no-notify", action="store_true", help="never show notifications")
+    s.set_defaults(func=cmd_schedule)
+
+    n = sub.add_parser("notify-test", help="send a test notification")
+    n.set_defaults(func=cmd_notify_test)
+
+    nt = sub.add_parser("notifier", help="build macverdict's own notification app (clickable alerts)")
+    nt.add_argument("action", choices=["install", "remove", "status"])
+    nt.set_defaults(func=cmd_notifier)
+
+    e = sub.add_parser("export", help="export history to CSV")
+    e.add_argument("out")
+    e.add_argument("--days", type=float, default=90)
+    e.set_defaults(func=cmd_export)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    if sys.platform != "darwin":
+        print("macverdict only supports macOS.", file=sys.stderr)
+        return 1
+    parser = build_parser()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    commands = {"check", "record", "report", "history", "schedule", "export", "notify-test", "notifier", "insights", "setup", "uninstall"}
+    # `macverdict` and `macverdict --json` mean `macverdict check ...`.
+    if not argv or (argv[0] not in commands and argv[0] not in ("-h", "--help", "--version")
+                    and argv[0].startswith("-")):
+        argv.insert(0, "check")
+    args = parser.parse_args(argv)
+    return args.func(args)