system-diff 0.1.0__py3-none-any.whl

system_diff/png.py

@@ -0,0 +1,121 @@
+"""SVG -> PNG, each FILE.svg -> FILE.png beside it, at twice the size for sharp text.
+
+Only for places that show a PNG and not an SVG with its styles (some PR pages, some previews, some proxies); GitHub shows
+the SVG itself. Headless Chromium draws them, in this order: Docker here (the pinned image below only for its Chromium
+and puppeteer), else Playwright if it is installed (`pip install system-diff[png]`, then `playwright install chromium`),
+else Docker on HOST over SSH (`--host`).
+"""
+from __future__ import annotations
+
+import io
+import os
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+from pathlib import Path
+from typing import List, Optional
+
+IMAGE = os.getenv("SYSTEM_DIFF_RENDER_IMAGE", "minlag/mermaid-cli:11.4.2")
+
+SHOT_JS = r"""// Every /data/N.svg -> /data/N.png: the SVG's own width and height, at device scale 2.
+const fs = require("fs");
+const puppeteer = require("/home/mermaidcli/node_modules/puppeteer");
+const config = JSON.parse(fs.readFileSync("/puppeteer-config.json", "utf8"));
+(async () => {
+  const browser = await puppeteer.launch(config);
+  const page = await browser.newPage();
+  for (const f of fs.readdirSync("/data").filter((x) => x.endsWith(".svg"))) {
+    const head = fs.readFileSync(`/data/${f}`, "utf8").slice(0, 400);
+    const width = Math.ceil(+(head.match(/\bwidth="([\d.]+)"/) || [0, 1200])[1]);
+    const height = Math.ceil(+(head.match(/\bheight="([\d.]+)"/) || [0, 800])[1]);
+    await page.setViewport({ width, height, deviceScaleFactor: 2 });
+    await page.goto(`file:///data/${f}`, { waitUntil: "load" });
+    await page.screenshot({ path: `/data/${f.replace(/\.svg$/, ".png")}`, clip: { x: 0, y: 0, width, height } });
+  }
+  await browser.close();
+})().catch((e) => { console.error(`render failed: ${e.message}`); process.exit(1); });
+"""
+IN_CONTAINER = "cd /data && HOME=/tmp node shot.js"
+
+
+def _docker_here() -> bool:
+    if not shutil.which("docker"):
+        return False
+    return subprocess.run(["docker", "info"], capture_output=True).returncode == 0
+
+
+def _playwright(stage: Path, names: List[str]) -> bool:
+    try:
+        from playwright.sync_api import sync_playwright  # type: ignore[import-not-found]
+    except ImportError:
+        return False
+    import re
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        for name in names:
+            svg = stage / name
+            head = svg.read_text(encoding="utf-8")[:400]
+            width = int(float((re.search(r'\bwidth="([\d.]+)"', head) or [0, 1200])[1]) + 0.999)
+            height = int(float((re.search(r'\bheight="([\d.]+)"', head) or [0, 800])[1]) + 0.999)
+            page = browser.new_page(viewport={"width": width, "height": height}, device_scale_factor=2)
+            page.goto(svg.resolve().as_uri())
+            page.screenshot(path=str(svg.with_suffix(".png")), clip={"x": 0, "y": 0, "width": width, "height": height})
+            page.close()
+        browser.close()
+    return True
+
+
+def _over_ssh(stage: Path, host: str) -> None:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w") as tar:
+        for f in sorted(stage.iterdir()):
+            tar.add(f, arcname=f.name)
+    remote = ("set -e; d=$(mktemp -d $HOME/.system-diff-render.XXXXXX); trap 'rm -rf $d' EXIT; tar -x -C $d; "
+              f"chmod 777 $d; docker run --rm -v $d:/data --entrypoint sh {IMAGE} -c '{IN_CONTAINER}' >&2; "
+              "cd $d && tar -cf - *.png")
+    got = subprocess.run(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=15", host, remote],
+                         input=buf.getvalue(), capture_output=True)
+    if got.returncode != 0:
+        raise RuntimeError(f"drawing on {host} failed: {got.stderr.decode(errors='replace')[-800:]}")
+    with tarfile.open(fileobj=io.BytesIO(got.stdout)) as tar:
+        for m in tar.getmembers():  # only flat PNGs come back; nothing a remote sends may land elsewhere
+            name = Path(m.name).name
+            if m.isfile() and name.endswith(".png"):
+                (stage / name).write_bytes(tar.extractfile(m).read())
+
+
+def render(svgs: List[Path], host: Optional[str] = None) -> List[Path]:
+    """Draw each SVG as a PNG beside it. Raises RuntimeError naming what is missing when nothing can draw."""
+    for f in svgs:
+        if f.suffix != ".svg" or not f.is_file():
+            raise ValueError(f"not an .svg file: {f}")
+    stage = Path(tempfile.mkdtemp(prefix="system-diff-render."))
+    try:
+        names = []
+        for i, f in enumerate(svgs):
+            shutil.copyfile(f, stage / f"{i}.svg")
+            names.append(f"{i}.svg")
+        (stage / "shot.js").write_text(SHOT_JS, encoding="utf-8", newline="\n")
+        if _docker_here():
+            user = ["-u", f"{os.getuid()}:{os.getgid()}"] if sys.platform.startswith("linux") else []
+            done = subprocess.run(["docker", "run", "--rm", *user, "-v", f"{stage}:/data", "--entrypoint", "sh", IMAGE,
+                                   "-c", IN_CONTAINER])
+            if done.returncode != 0:
+                raise RuntimeError("Chromium could not draw the pictures (output above)")
+        elif not _playwright(stage, names):
+            if not host:
+                raise RuntimeError("nothing here can draw PNGs: no Docker, no Playwright "
+                                   "(`pip install system-diff[png]`), and no --host with Docker")
+            _over_ssh(stage, host)
+        out = []
+        for i, f in enumerate(svgs):
+            png = stage / f"{i}.png"
+            if not png.is_file():
+                raise RuntimeError(f"no picture came back for {f}")
+            shutil.copyfile(png, f.with_suffix(".png"))
+            out.append(f.with_suffix(".png"))
+        return out
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)

system_diff/readme.py

@@ -0,0 +1,39 @@
+"""The README's generated system-map section: the picture, how it is made, and a warning when the picture is stale."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Iterable
+
+from .pictures import write_if_changed
+
+
+def readme_section(dormant: Dict[str, dict], cfg: Dict[str, Any], stale: Iterable[str] = ()) -> str:
+    """The generated block. `stale`: pictures that could not be redrawn this time, named, so no one mistakes an old
+    picture for the current system; the SVGs beside them are always current."""
+    r = cfg["readme"]
+    stale = list(stale)
+    tag = ""
+    if stale:
+        tag = r["stale"].format(pictures=", ".join(f"`{x}`" for x in stale), it="it" if len(stale) == 1 else "them")
+    note = ""
+    if dormant:
+        names = ", ".join(f"{v['label']} ({', '.join(v['used_by'])})" for v in dormant.values())
+        note = r["dormant"].format(names=names)
+    return (
+        f"{r['begin']}\n"
+        f"{tag}"
+        f"![System map, generated from the code]({r['image']})\n\n"
+        "<details><summary>How this map is made</summary>\n\n"
+        f"{r['how'].format(dormant=note)}\n\n</details>\n"
+        f"{r['end']}"
+    )
+
+
+def update_readme(readme: Path, dormant: Dict[str, dict], cfg: Dict[str, Any], stale: Iterable[str] = ()) -> bool:
+    """Rewrite the section between the README's markers. True when the file changed."""
+    r = cfg["readme"]
+    text = readme.read_text(encoding="utf-8")
+    if r["begin"] not in text or r["end"] not in text:
+        raise SystemExit(f"{readme} has no {r['begin']} … {r['end']} section: add the two lines where the map goes")
+    start, end = text.index(r["begin"]), text.index(r["end"]) + len(r["end"])
+    return write_if_changed(readme, text[:start] + readme_section(dormant, cfg, stale) + text[end:])

system_diff/sources.py

@@ -0,0 +1,76 @@
+"""Where the files come from: a commit, read straight from git's object store (no checkout), or a directory."""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Dict, Iterable, Optional
+
+
+def git(*args: str, cwd: Path) -> str:
+    return subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True, text=True,
+                          encoding="utf-8", errors="replace").stdout
+
+
+def repo_root(start: Optional[Path] = None) -> Path:
+    """The repository holding `start` (default: the current directory), or `start` itself outside one."""
+    here = Path(start or Path.cwd()).resolve()
+    try:
+        return Path(git("rev-parse", "--show-toplevel", cwd=here).strip())
+    except (OSError, subprocess.CalledProcessError):
+        return here
+
+
+class GitSource:
+    """The files of a commit."""
+
+    def __init__(self, ref: str, root: Path):
+        self.root, self.ref = Path(root), ref
+        self.label = git("rev-parse", "--short", ref, cwd=self.root).strip()
+        self.files = [f for f in git("ls-tree", "-r", "-z", "--name-only", ref, cwd=self.root).split("\0") if f]
+        self._cache: Dict[str, str] = {}
+
+    def read_many(self, paths: Iterable[str]) -> Dict[str, str]:
+        paths = list(paths)
+        want = [p for p in paths if p not in self._cache]
+        if want:
+            out = subprocess.run(["git", "cat-file", "--batch"], cwd=self.root, check=True, capture_output=True,
+                                 input="".join(f"{self.ref}:{p}\n" for p in want).encode()).stdout
+            i = 0
+            for p in want:
+                header_end = out.index(b"\n", i)
+                parts = out[i:header_end].split()
+                i = header_end + 1
+                if len(parts) < 3 or parts[1] == b"missing":
+                    self._cache[p] = ""
+                    continue
+                size = int(parts[2])
+                self._cache[p] = out[i:i + size].decode("utf-8", errors="replace")
+                i += size + 1
+        return {p: self._cache.get(p, "") for p in paths}
+
+    def read(self, path: str) -> str:
+        return self.read_many([path])[path]
+
+
+class DirSource:
+    """The files of a directory: the working tree, or a test fixture."""
+
+    def __init__(self, directory: Path, skip: Optional[re.Pattern] = None, label: str = "working tree"):
+        self.dir, self.label = Path(directory), label
+        files = []
+        for top, dirs, names in os.walk(self.dir):
+            rel = os.path.relpath(top, self.dir).replace(os.sep, "/")
+            dirs[:] = sorted(x for x in dirs if x != ".git" and not (skip and skip.search(f"{rel}/{x}/")))
+            files += [(f"{rel}/{n}" if rel != "." else n) for n in names]
+        self.files = sorted(files)
+
+    def read_many(self, paths: Iterable[str]) -> Dict[str, str]:
+        return {p: self.read(p) for p in paths}
+
+    def read(self, path: str) -> str:
+        try:
+            return (self.dir / path).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return ""

system_diff/watch.py

@@ -0,0 +1,177 @@
+"""`system-diff watch`: a live page of what changed in the system since the checkpoint, for a person to keep beside the
+editor while they, or an AI coding agent, change the code. It redraws when a file changes; "Mark as seen" moves the
+checkpoint, so the page then shows only what is new to them.
+
+Local only: the server listens on 127.0.0.1, and "Mark as seen" needs the page's own token, so no other web page open in
+the same browser can press it.
+"""
+from __future__ import annotations
+
+import json
+import secrets
+import subprocess
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from . import graph
+from .compare import checkpoint, checkpoint_sha, compare, worktree_tree
+
+PAGE = """<!doctype html><html lang="en"><head><meta charset="utf-8"><title>System diff</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+:root { --ink:#161c24; --muted:#667385; --line:#e1e5eb; --bg:#f8f9fb; --work:#1f5fbf; }
+* { box-sizing: border-box; }
+body { margin:0; font:14px/1.45 'Segoe UI', FreeSans, 'Helvetica Neue', Arial, sans-serif; color:var(--ink); background:var(--bg); }
+header { position:sticky; top:0; display:flex; flex-wrap:wrap; gap:12px; align-items:center; padding:12px 20px;
+         background:#fff; border-bottom:1px solid var(--line); }
+h1 { font-size:15px; margin:0; } .since { color:var(--muted); font-size:12.5px; }
+button { margin-left:auto; border:1px solid var(--work); background:var(--work); color:#fff; border-radius:8px;
+         padding:6px 14px; font:inherit; font-weight:600; cursor:pointer; } button:disabled { opacity:.5; cursor:default; }
+main { padding:16px 20px; display:grid; gap:14px; }
+.headline { font-size:16px; font-weight:600; } .error { color:#c4321c; white-space:pre-wrap; }
+.picture { overflow:auto; background:#fff; border:1px solid var(--line); border-radius:10px; padding:8px; }
+.picture svg { display:block; max-width:none; }
+pre { margin:0; padding:12px 14px; background:#fff; border:1px solid var(--line); border-radius:10px; overflow:auto;
+      font:12.5px/1.5 Consolas, Inconsolata, 'DejaVu Sans Mono', monospace; }
+.quiet { color:var(--muted); }
+</style></head><body>
+<header><h1>System diff</h1><span class="since" id="since"></span>
+<button id="seen" type="button" title="Move the checkpoint here: the page then shows only what is new">Mark as seen</button></header>
+<main><div class="headline" id="headline">Reading the code…</div><div class="error" id="error"></div>
+<div class="picture" id="picture" hidden></div><pre id="plan" hidden></pre></main>
+<script>
+const TOKEN = "__TOKEN__";
+let version = -1;
+function show(s) {
+  version = s.version;
+  document.getElementById("since").textContent = "since " + s.base + " · updated " + s.at;
+  document.getElementById("headline").textContent = s.headline;
+  document.getElementById("error").textContent = s.error || "";
+  const pic = document.getElementById("picture"), plan = document.getElementById("plan");
+  pic.hidden = !s.svg; pic.innerHTML = s.svg || "";
+  plan.hidden = !s.changes; plan.textContent = s.plan;
+  document.getElementById("seen").disabled = !s.changes;
+}
+async function poll() {
+  try {
+    const r = await fetch("state?since=" + version, { cache: "no-store" });
+    if (r.status === 200) show(await r.json());
+  } catch (e) { document.getElementById("error").textContent = "The watcher stopped: start system-diff watch again."; }
+  setTimeout(poll, 1500);
+}
+document.getElementById("seen").onclick = async () => {
+  const r = await fetch("seen", { method: "POST", headers: { "X-Token": TOKEN } });
+  if (r.status === 200) show(await r.json());
+};
+poll();
+</script></body></html>
+"""
+
+
+class Watcher:
+    """The current diff, recomputed in the background whenever the working tree or the checkpoint moves."""
+
+    def __init__(self, root: Path, base: str = "checkpoint", config_path: Optional[str] = None, interval: float = 2.0):
+        self.root, self.base, self.config_path, self.interval = root, base, config_path, interval
+        self.token = secrets.token_urlsafe(16)
+        self.lock = threading.Lock()
+        self.state: Dict[str, Any] = {"version": 0, "headline": "Reading the code…", "plan": "", "svg": "",
+                                      "changes": 0, "base": base, "at": "", "error": ""}
+        self.seen_key: Optional[tuple] = None
+        self.stop = threading.Event()
+        # One look at the files at a time: otherwise a slow look that started before "Mark as seen" could finish
+        # after it and put the old diff back on the page.
+        self.busy = threading.Lock()
+
+    def key(self) -> tuple:
+        return worktree_tree(self.root), checkpoint_sha(self.root)
+
+    def refresh(self) -> None:
+        try:
+            c = compare(self.root, self.base, ".", self.config_path)
+            svg = graph.diff_svg(c.diff, c.before, c.after, c.cfg) or ""
+            new = {"headline": c.diff["headline"], "plan": c.diff["plan"], "svg": svg,
+                   "changes": len(c.diff["changes"]), "base": c.base, "error": ""}
+        except (OSError, subprocess.CalledProcessError, ValueError, KeyError) as exc:
+            new = {"error": f"{type(exc).__name__}: {exc}"}
+        with self.lock:
+            self.state.update(new, version=self.state["version"] + 1, at=time.strftime("%H:%M:%S"))
+
+    def tick(self, force: bool = False) -> None:
+        with self.busy:
+            try:
+                key = self.key()
+            except (OSError, subprocess.CalledProcessError) as exc:
+                with self.lock:
+                    self.state.update(error=f"git: {exc}", version=self.state["version"] + 1)
+                return
+            if force or key != self.seen_key:
+                self.seen_key = key
+                self.refresh()
+
+    def loop(self) -> None:
+        while not self.stop.is_set():
+            self.tick()
+            self.stop.wait(self.interval)
+
+    def mark_seen(self) -> None:
+        with self.busy:
+            checkpoint(self.root)
+        self.tick(force=True)  # the page's answer is the diff from the new checkpoint, never an older look
+
+    def snapshot_state(self) -> Dict[str, Any]:
+        with self.lock:
+            return dict(self.state)
+
+
+def handler(w: Watcher):
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *a):  # quiet: the terminal shows the URL, not every poll
+            pass
+
+        def _send(self, code: int, body: bytes, kind: str) -> None:
+            self.send_response(code)
+            self.send_header("Content-Type", kind)
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self):
+            if self.path in ("/", "/index.html"):
+                return self._send(200, PAGE.replace("__TOKEN__", w.token).encode(), "text/html; charset=utf-8")
+            if self.path.startswith("/state"):
+                return self._send(200, json.dumps(w.snapshot_state()).encode(), "application/json")
+            return self._send(404, b"not found", "text/plain")
+
+        def do_POST(self):
+            if self.path != "/seen" or self.headers.get("X-Token") != w.token:
+                return self._send(403, b"forbidden", "text/plain")
+            w.mark_seen()
+            return self._send(200, json.dumps(w.snapshot_state()).encode(), "application/json")
+
+    return Handler
+
+
+def serve(root: Path, base: str = "checkpoint", port: int = 8765, config_path: Optional[str] = None,
+          interval: float = 2.0, ready=None) -> None:
+    """Run until interrupted. `ready(url)` is called once the server listens (tests use port 0)."""
+    w = Watcher(root, base, config_path, interval)
+    server = ThreadingHTTPServer(("127.0.0.1", port), handler(w))
+    thread = threading.Thread(target=w.loop, daemon=True)
+    thread.start()
+    url = f"http://127.0.0.1:{server.server_address[1]}/"
+    if ready:
+        ready(url, server, w)
+    else:
+        print(f"system-diff watch: {url} (Ctrl-C to stop)", flush=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        w.stop.set()
+        server.server_close()

system_diff-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: system-diff
+Version: 0.1.0
+Summary: Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or removes. No dependencies; SVG pictures for PRs and READMEs.
+Project-URL: Homepage, https://github.com/simplifiedmachine/system-diff
+Project-URL: Documentation, https://github.com/simplifiedmachine/system-diff/wiki
+Project-URL: Issues, https://github.com/simplifiedmachine/system-diff/issues
+Author: simplifiedmachine
+License-Expression: MIT
+License-File: LICENSE
+Keywords: architecture,code-review,code-visualization,developer-tools,diagrams,pull-requests,system-design
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mcp>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == 'mcp'
+Provides-Extra: png
+Requires-Dist: playwright>=1.40; extra == 'png'
+Description-Content-Type: text/markdown
+
+# system-diff
+
+Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or
+removes. No dependencies; SVG pictures for PRs and READMEs.
+
+<!-- system-map:begin -->
+![System map, generated from the code](https://raw.githubusercontent.com/simplifiedmachine/system-diff/main/docs/diagrams/system.svg)
+
+<details><summary>How this map is made</summary>
+
+Regenerated by `system-diff` from the code: the parts and their columns from `system-diff.toml`, the connections from imports, API calls and the settings each part reads, the outside systems from the settings a deploy configuration sets, and the tables from the migrations. Parts used everywhere are drawn without the arrows into them, and each part keeps only its strongest connections; `system-diff map` writes all of them to `system.json`.
+
+Read by the code but set by no deploy configuration, so not drawn: Headless Chromium (Docker or Playwright) (png).
+
+</details>
+<!-- system-map:end -->
+
+## What it does
+
+- **`map`**: reads a commit straight from git (no checkout) or a folder, and writes `system.json` (everything it
+  found) and `system.svg` (the picture): a column per role, from what people use through entry points, logic and data
+  access to stored data and outside systems.
+- **`diff`**: the typed difference between two commits, or a commit and your working tree: parts, endpoints,
+  connections, outside systems, tables, settings and deployment files added, changed or removed. One sentence
+  (`headline.txt`), the exact list (`plan.txt`, like `terraform plan`), and a picture of only what changed, with the
+  parts it touches beside it (`diff.svg`). `--narrate` adds a plain-words summary from your own LLM.
+- **`readme`**: keeps a generated system map in your README, between two markers.
+- **`draw`**: hand-made pictures in the same look, from small JSON specs: maps, stages of a process, sequences.
+
+Deterministic: the same code gives the same picture, byte for byte, and a part that did not change keeps its place.
+
+## Install
+
+```sh
+pipx install system-diff
+```
+
+Python 3.11 or newer, nothing else. `pip install "system-diff[png]"` adds PNG output through Playwright; `system-diff
+png` also uses Docker when it is there.
+
+## Use
+
+```sh
+system-diff map --dir . --out docs/diagrams          # the system as it is now
+system-diff diff --base origin/main --out out        # what this branch does to it
+system-diff diff --base HEAD --head . --out out      # what your uncommitted work does to it
+system-diff readme --json docs/diagrams/system.json  # refresh the map in README.md
+```
+
+With no config, every folder of code is a part named by its path. A `system-diff.toml` at the repository root names the
+parts and says what is what:
+
+```toml
+tests = ["tests/**"]
+
+[code]
+roots = ["app/", "web/src/"]
+
+[[components]]
+id = "api"
+label = "API"
+kind = "interface"          # ui | interface | logic | data: the column it is drawn in
+paths = ["app/api/**"]
+
+[[externals]]
+id = "postgres"
+label = "PostgreSQL"
+shape = "db"
+env = ["DATABASE_URL"]      # the settings that reach it
+```
+
+Every key, and how the code is read: [the wiki](https://github.com/simplifiedmachine/system-diff/wiki).
+
+## In pull requests
+
+This repository runs system-diff on itself: the map above is regenerated from its own code, CI fails when it is out of
+date, and every pull request gets its system diff as a comment (`.github/workflows/system-diff.yml`, which you can
+copy).
+
+## With AI coding agents
+
+When an agent changes the code with you, the question is what it did to the system. system-diff answers it as you go:
+
+```sh
+pipx install system-diff
+pipx inject system-diff mcp  # the MCP server's one dependency
+system-diff setup claude     # the hook, a skill and the MCP server, in one step (--scope project, --undo)
+system-diff watch            # http://127.0.0.1:8765/ : the system diff since you last marked it seen
+```
+
+- **After every Claude Code turn**, one line says what changed in the system since your checkpoint ("Adds 1 endpoint
+  (DELETE /api/orders/{id}); changes 1 table (public.orders)."), or nothing when nothing structural did.
+- **The live page** redraws as files change. Press **Mark as seen** once you have understood it: the next diff then
+  shows only what is new to you. `system-diff checkpoint` does the same from the terminal.
+- **The MCP server** gives the agent `system_diff` (the exact plan to explain from, and the picture), `system_map`,
+  `draw` (pictures of processes and sequences in the same look) and `checkpoint`.
+- The working tree is read as a snapshot (untracked files included) without touching your index, HEAD or branches,
+  and the checkpoint lives under `refs/system-diff/`, in your clone only.
+
+## License
+
+MIT

system_diff-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+system_diff/__init__.py,sha256=QegtiHEdVJe5UC9fwHjqYi5Q8zbvDRbAViIa6MEHz9I,289
+system_diff/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+system_diff/agent.py,sha256=mYN3nlxyx4U5vpNtm0UbSZSMym6Zcea7pbz00YcXKC4,9037
+system_diff/cli.py,sha256=3_VPJg4n_R56oy2OZANu3bPPMhrzlB-QDpHjogwiNcI,10958
+system_diff/compare.py,sha256=hf1VOJPVwC1BK4gUAlv98wX07X44fX2eawRS0piDhDU,4578
+system_diff/config.py,sha256=psPCQJLQDiNQ1FIsl6-PKP77hYu51__fRGJgru4oU1A,5961
+system_diff/diff.py,sha256=gcUDrMjjQbq8uloGYs_8O5RnZ_yqqCDjdsNWmuBcqvQ,9020
+system_diff/extract.py,sha256=yUYkyUwhpmhp3sXBySTjWHuHtxvPUeqnv1MuxCfIOIw,13034
+system_diff/graph.py,sha256=OPrMYiWcth_9Yts08hyzG-u0oT8ubkc4V5T59tsH7is,11086
+system_diff/mcp_server.py,sha256=ISLUqwYehOoGsMjQhcakieQc-1-NywKLP9fav0_XMo4,8954
+system_diff/narrate.py,sha256=wRq2oRPt0TZyEdsd-rQcQY0EpiHaFpyKDM3svqMioCA,7691
+system_diff/pictures.py,sha256=G4a8DmvkOttuW962vcGm6CnsbeOTIN_WLrl6ZK0lQGQ,28479
+system_diff/png.py,sha256=HCxc23roQNxHdcsULmMQnvpqLA1Ejkkc1k9lR_Swa14,5775
+system_diff/readme.py,sha256=3qOXsxgaBE8aIbbuK2YDrRy9J3NjbwdzfR0EB3xqgAY,1823
+system_diff/sources.py,sha256=ZtFE89tv7Cscb3qKO95PjbY0OUZm30hj9IeBxCvutxU,3085
+system_diff/watch.py,sha256=VDW4L1HQ6q0i5BMpwfy9qOGE1PW8YBEe9dSYqCBrTog,8303
+system_diff-0.1.0.dist-info/METADATA,sha256=krlsARSg-d2WIEGUVQAlR6KwWZCTbt1lKlGvcyREN-c,6094
+system_diff-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+system_diff-0.1.0.dist-info/entry_points.txt,sha256=8fw6tkuFfZI2L7ScWUXVxj28LK9p6UiImnnB8E1om1E,84
+system_diff-0.1.0.dist-info/licenses/LICENSE,sha256=QHQ-0t-7_4_K7j92CTlQScHiJiDZ91DcpV6WIOIFYQE,1074
+system_diff-0.1.0.dist-info/RECORD,,

system_diff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

system_diff-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sysdiff = system_diff.cli:main
+system-diff = system_diff.cli:main

system_diff-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 simplifiedmachine
+
+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.