proxy2model 2.0.0__py3-none-any.whl

proxy2model/cli/common.py

@@ -0,0 +1,190 @@
+"""Shared by the commands: names, the fingerprint key, saved inputs, loading a model."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+
+from ..atomic import atomic_write
+from ..ingest.parse import Exchange
+from ..core.model import from_dict
+from ..ingest.redact import set_fingerprint_key
+from ..db import store
+
+
+_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+
+
+DEFAULT_INPUT = "_default"
+EXPORTS = "exports"            # graph.json, graph.graphml and build.svg, inside the model folder
+
+
+def _name(kind: str):
+    def check(value: str) -> str:
+        if not _NAME_RE.match(value):
+            raise argparse.ArgumentTypeError(
+                f"{kind} must be letters, digits, '.', '_' or '-' (got {value!r})")
+        return value
+    return check
+
+
+def _init_key() -> None:
+    """Keep one fingerprint key per user, outside any output directory.
+
+    Fingerprints from separate runs (e.g. one per role) must be comparable, but
+    the key must not travel with the outputs — otherwise anyone holding
+    model.json could confirm a guessed secret against its fingerprint.
+    """
+    if os.environ.get("PROXY2MODEL_FP_KEY"):
+        return
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
+    path = os.path.join(base, "proxy2model", "fingerprint.key")
+    old = os.path.join(base, "burp2model", "fingerprint.key")
+    if not os.path.exists(path) and os.path.exists(old) and os.path.getsize(old) >= 16:
+        path = old          # keep fingerprints comparable with builds made before the rename
+    try:
+        if not os.path.exists(path) or os.path.getsize(path) < 16:
+            # never run with a missing, empty or truncated key
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with atomic_write(path, "wb", perms=0o600) as f:      # whole or absent, never half a key
+                f.write(os.urandom(32))
+        with open(path, "rb") as f:
+            set_fingerprint_key(f.read())
+    except OSError as e:
+        print(f"warning: no persistent fingerprint key ({e}); fingerprints from "
+              "separate runs will not match", file=sys.stderr)
+
+
+def _inputs_dir(outdir: str) -> str:
+    return os.path.join(outdir, "inputs")
+
+
+INPUTS_VERSION = 1
+
+
+def _save_input(outdir: str, key: str, exchanges: list[Exchange], stats: dict) -> None:
+    d = _inputs_dir(outdir)
+    os.makedirs(d, exist_ok=True)
+    with atomic_write(os.path.join(d, key + ".jsonl")) as f:
+        f.write(json.dumps({"_stats": stats, "_version": INPUTS_VERSION}) + "\n")
+        for ex in exchanges:
+            f.write(json.dumps(ex.to_record()) + "\n")
+
+
+def _stage_input(outdir: str, exchanges, stats: dict) -> tuple[str, int]:
+    """Write parsed exchanges straight to a staging file as they stream in, so a large export is never
+    held in memory. The stats line goes last, when the counts are final. Returns (path, exchanges written)."""
+    d = _inputs_dir(outdir)
+    os.makedirs(d, exist_ok=True)
+    path = os.path.join(d, ".staging")
+    n = 0
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            for ex in exchanges:
+                f.write(json.dumps(ex.to_record()) + "\n")
+                n += 1
+            f.write(json.dumps({"_stats": stats, "_version": INPUTS_VERSION}) + "\n")
+    except BaseException:
+        if os.path.exists(path):
+            os.remove(path)
+        raise
+    return path, n
+
+
+def _drop_if_empty(outdir: str) -> None:
+    """A build that read nothing leaves no folders behind."""
+    for d in (_inputs_dir(outdir), outdir):
+        try:
+            os.rmdir(d)
+        except OSError:
+            pass
+
+
+def _clear_inputs(outdir: str, only: str | None = None, keep: str | None = None) -> None:
+    d = _inputs_dir(outdir)
+    if not os.path.isdir(d):
+        return
+    for fn in os.listdir(d):
+        if fn.endswith(".jsonl") and (only is None or fn == only + ".jsonl") and fn != f"{keep}.jsonl":
+            os.remove(os.path.join(d, fn))
+
+
+def _load_inputs(outdir: str) -> tuple[list[Exchange], dict, list[str]]:
+    """All saved inputs, re-indexed so evidence ids are unique across them."""
+    d = _inputs_dir(outdir)
+    exchanges: list[Exchange] = []
+    stats = {"items": 0, "parsed": 0, "skipped": 0}
+    names = []
+    for fn in sorted(os.listdir(d)) if os.path.isdir(d) else []:
+        if not fn.endswith(".jsonl"):
+            continue
+        try:
+            with open(os.path.join(d, fn), encoding="utf-8") as f:
+                loaded = []
+                for line in f:
+                    rec = json.loads(line)
+                    if "_stats" in rec:
+                        if rec.get("_version", 1) > INPUTS_VERSION:
+                            raise ValueError(f"saved by a newer proxy2model "
+                                             f"(inputs v{rec['_version']})")
+                        for k in stats:
+                            stats[k] += rec["_stats"].get(k, 0)
+                        continue
+                    loaded.append(Exchange.from_record(rec))
+        except (ValueError, KeyError, TypeError) as e:
+            print(f"warning: skipping unreadable saved input {fn}: {e}\n"
+                  f"  re-run the build for that capture (or use --fresh)", file=sys.stderr)
+            continue
+        names.append(fn[:-6])
+        for ex in loaded:
+            ex.index = len(exchanges) + 1
+            exchanges.append(ex)
+    return exchanges, stats, names
+
+
+def _scope(args) -> list[str] | None:
+    """Normalise --scope values: accept `https://shop.com:443/x` for `shop.com`."""
+    if not args.scope:
+        return None
+    out = []
+    for s in args.scope:
+        for x in s.split(","):
+            x = x.strip().lower()
+            if not x:
+                continue
+            x = re.sub(r"^[a-z][a-z0-9+.-]*://", "", x)   # scheme
+            x = x.split("/")[0]                            # path
+            if not x.startswith("[") and x.count(":") == 1:
+                x = x.split(":")[0]                        # port
+            if x:
+                out.append(x)
+    return out or None
+
+
+def _db_path(args) -> str | None:
+    path = os.path.join(args.out, args.webapp, store.DB_NAME)
+    if not os.path.exists(path):
+        print(f"no graph database at {path} — run `proxy2model build` first", file=sys.stderr)
+        return None
+    return path
+
+
+def _model_path(args) -> str | None:
+    path = os.path.join(args.out, args.webapp, "model.json")
+    if not os.path.exists(path):
+        print(f"no model at {path} — run `proxy2model build` first", file=sys.stderr)
+        return None
+    return path
+
+
+def _reload(path: str):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return from_dict(json.load(f))
+    except (OSError, ValueError, KeyError, TypeError) as e:
+        print(f"could not load {path}: {e}\nre-run `proxy2model build` to regenerate it.",
+              file=sys.stderr)
+        return None

proxy2model/cli/history.py

@@ -0,0 +1,224 @@
+"""History commands: what changed between builds, the build list, and watching a folder of exports."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import sys
+
+from ..core import diff as diffmod
+from ..db import store
+from ..atomic import atomic_write, keep_aside
+from ..core.model import from_dict
+
+
+def _main(argv):
+    from .app import main
+    return main(argv)
+
+
+def _db_path(args):
+    from .common import _db_path as db_path
+    return db_path(args)
+
+
+def _changes_since_previous(db_path: str, build_id: int | None) -> dict | None:
+    """The drift from the build before this one, for the report. None on a first build or any trouble."""
+    if not build_id or build_id < 2:
+        return None
+    try:
+        conn = store.open_db(db_path)
+        try:
+            ids = [r[0] for r in conn.execute("SELECT id FROM builds WHERE id<? ORDER BY id DESC LIMIT 1", (build_id,))]
+            if not ids:
+                return None
+            old, ometa = _snapshot_of(conn, ids[0])
+            new, nmeta = _snapshot_of(conn, build_id)
+            return diffmod.diff_models(old, new, ometa, nmeta, hist=lambda k, key: store.history(conn, k, key))
+        finally:
+            conn.close()
+    except (ValueError, KeyError, TypeError, OSError, sqlite3.Error):
+        return None
+
+
+def _snapshot_of(conn, bid: int):
+    snap = store.load_build(conn, bid)
+    if snap is None:
+        raise ValueError(f"no build #{bid} in graph.db")
+    row = conn.execute("SELECT built_at, label FROM builds WHERE id=?", (bid,)).fetchone()
+    return from_dict(snap), {"id": bid, "built_at": row["built_at"], "label": row["label"] or ""}
+
+
+def cmd_watch(args) -> int:
+    """Poll a folder: every settled new export is built, labelled with its file name, and diffed."""
+    import fnmatch
+    import time
+    folder = args.folder
+    if not os.path.isdir(folder):
+        print(f"watch: {folder} is not a folder", file=sys.stderr)
+        return 2
+    pats = [p.strip() for p in args.pattern.split(",") if p.strip()]
+    outdir = os.path.join(args.out, args.webapp)
+    state_path = os.path.join(outdir, "watch.json")
+    done = _load_watch_state(state_path)
+
+    def stat(fn):
+        try:
+            st = os.stat(os.path.join(folder, fn))
+        except OSError:                             # gone between the listing and the look
+            return None
+        return (st.st_mtime_ns, fn, st.st_size) if os.path.isfile(os.path.join(folder, fn)) else None
+
+    def listing():
+        try:
+            names = os.listdir(folder)
+        except OSError as e:
+            print(f"watch: cannot list {folder} ({e}); will look again", file=sys.stderr)
+            return []
+        found = [stat(fn) for fn in names if any(fnmatch.fnmatch(fn.lower(), x.lower()) for x in pats)]
+        return sorted(t for t in found if t)
+
+    sig = lambda t: [t[0], t[2]]                    # noqa: E731
+    if args.skip_existing and not done:
+        done = {fn: sig((m, fn, sz)) for m, fn, sz in listing()}
+    last: dict[str, list] = {}
+    built = 0
+    print(f"watch: {folder}  ({', '.join(pats)}) → {args.webapp}"
+          + ("" if args.once else f"  every {args.interval:g}s, Ctrl-C to stop"), file=sys.stderr)
+    try:
+        while True:
+            for mtime, fn, size in listing():
+                if done.get(fn) == sig((mtime, fn, size)) or size == 0:
+                    continue
+                # still being written (or copied): the size and the time must hold still for one interval
+                if not args.once and last.get(fn) != sig((mtime, fn, size)):
+                    last[fn] = sig((mtime, fn, size))
+                    continue
+                label = os.path.splitext(fn)[0]
+                argv = ["build", os.path.join(folder, fn), "-w", args.webapp, "--out", args.out, "--label", label]
+                for flag, val in (("--role", args.role), ("--skip-tools", args.skip_tools)):
+                    if val:
+                        argv += [flag, val]
+                for sc in args.scope or []:
+                    argv += ["--scope", sc]
+                if args.osint:
+                    argv.append("--osint")
+                print(f"\nwatch: new export {fn}", file=sys.stderr)
+                rc = _main(argv)
+                after = stat(fn)
+                if after is None or sig(after) != sig((mtime, fn, size)):
+                    # the file moved under the build: what was read may be part of it. Build it again once it settles.
+                    print(f"watch: {fn} changed while it was being read; will build it again once it settles",
+                          file=sys.stderr)
+                    last.pop(fn, None)
+                    continue
+                if rc != 0:
+                    print(f"watch: could not build from {fn}; will try again if it changes", file=sys.stderr)
+                    done[fn] = sig((mtime, fn, size))
+                    continue
+                done[fn] = sig((mtime, fn, size))
+                built += 1
+                os.makedirs(outdir, exist_ok=True)
+                with atomic_write(state_path) as f:
+                    json.dump(done, f, indent=1, sort_keys=True)
+                try:
+                    conn = store.open_db(os.path.join(outdir, store.DB_NAME))
+                    try:
+                        n = len(store.list_builds(conn))
+                    finally:
+                        conn.close()
+                except (OSError, ValueError, sqlite3.Error):
+                    n = 0
+                if n > 1:
+                    print("", file=sys.stderr)
+                    _main(["diff", args.webapp, "--out", args.out])
+            if args.once:
+                break
+            time.sleep(max(0.2, args.interval))
+    except KeyboardInterrupt:
+        print("\nwatch: stopped", file=sys.stderr)
+    if args.once and not built:
+        print("watch: nothing new to build", file=sys.stderr)
+    return 0
+
+
+def _load_watch_state(path: str) -> dict:
+    """Which exports were already built. A damaged state file is kept aside rather than read as "nothing
+    built yet", which would rebuild every export in the folder as a new build."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            done = json.load(f)
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError) as e:
+        done = e
+    if isinstance(done, dict):
+        return done
+    try:
+        aside = keep_aside(path)
+        print(f"watch: {path} was unreadable; kept it aside as {aside}. Exports already built "
+              f"will be built again (use --skip-existing to skip them)", file=sys.stderr)
+    except OSError:
+        pass
+    return {}
+
+
+def cmd_builds(args) -> int:
+    dbp = _db_path(args)
+    if dbp is None:
+        return 2
+    try:
+        conn = store.open_db(dbp)
+        try:
+            rows = store.list_builds(conn)
+        finally:
+            conn.close()
+    except (ValueError, sqlite3.Error) as e:
+        print(f"could not read {dbp}: {e}", file=sys.stderr)
+        return 2
+    print(f"{args.webapp}: {len(rows)} build(s) kept in graph.db")
+    print(f"  {'id':>3}  {'built (UTC)':<20} {'nodes':>6} {'edges':>6} {'requests':>8}  label")
+    for r in rows:
+        print(f"  {r['id']:>3}  {r['built_at']:<20} {r['nodes']:>6} {r['edges']:>6} {r['exchanges']:>8}  {r['label']}")
+    if len(rows) > 1:
+        print(f"\ncompare two:  proxy2model diff {args.webapp} {rows[-2]['id']} {rows[-1]['id']}")
+    return 0
+
+
+def cmd_diff(args) -> int:
+    dbp = _db_path(args)
+    if dbp is None:
+        return 2
+    try:
+        conn = store.open_db(dbp)
+    except (ValueError, sqlite3.Error) as e:
+        print(f"could not diff: {e}", file=sys.stderr)
+        return 2
+    try:
+        b_ref = args.b if args.b is not None else "latest"
+        a_ref = args.a if args.a is not None else "previous"
+        newer = store.resolve_build(conn, b_ref)
+        if args.a is None and args.b is None:
+            older = store.resolve_build(conn, "previous")
+        else:
+            older = store.resolve_build(conn, a_ref if args.a is not None else "previous")
+        if older == newer:
+            print(f"build #{older} is compared with itself; pick two different builds "
+                  f"(`proxy2model builds {args.webapp}` lists them)", file=sys.stderr)
+            return 2
+        if older > newer:
+            older, newer = newer, older
+        old, ometa = _snapshot_of(conn, older)
+        new, nmeta = _snapshot_of(conn, newer)
+        d = diffmod.diff_models(old, new, ometa, nmeta, hist=lambda k, key: store.history(conn, k, key))
+    except (ValueError, KeyError, TypeError, OSError, sqlite3.Error) as e:
+        print(f"could not diff: {e}", file=sys.stderr)
+        return 2
+    finally:
+        conn.close()
+    if args.json:
+        print(json.dumps(d, indent=2))
+    else:
+        print(diffmod.format_text(d))
+    return 0

proxy2model/cli/mcp.py

@@ -0,0 +1,184 @@
+"""`mcp`: serve built models to an AI agent over the Model Context Protocol (stdio).
+
+Each tool runs the same command a researcher would type, so an agent gets exactly the answers
+the CLI gives: cited, deterministic, no model call inside. It reads models under one output
+folder and never builds, crawls or contacts anything.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import sys
+
+from .. import __version__
+from .common import _NAME_RE
+
+PROTOCOLS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+
+_APP = {"type": "string", "description": "model name used at build time (the -w value)"}
+TOOLS = [
+    {"name": "list_models", "description": "The models built in this output folder, with their size and roles.",
+     "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "query", "description": "Ask a model a factual question; every line cites evidence ids. "
+                                     "Ask `help` first for what it answers (list-apis, reconcile, auth-surface, "
+                                     "unknowns, provenance /path, ...). Questions it cannot answer are refused.",
+     "inputSchema": {"type": "object", "required": ["app", "question"],
+                     "properties": {"app": _APP, "question": {"type": "string"}}}},
+    {"name": "bql", "description": "Filter and walk graph.db with BQL, e.g. `req.method:POST AND resp.code.gte:400`, "
+                                   "`static-only`, `reach \"POST /api/checkout\"`. `help` prints the language.",
+     "inputSchema": {"type": "object", "required": ["app", "expression"],
+                     "properties": {"app": _APP, "expression": {"type": "string"},
+                                    "limit": {"type": "integer", "minimum": 1, "maximum": 1000}}}},
+    {"name": "cross_role", "description": "What the lower-privileged role reached that only the higher one should.",
+     "inputSchema": {"type": "object", "required": ["app", "low", "high"],
+                     "properties": {"app": _APP, "low": {"type": "string"}, "high": {"type": "string"}}}},
+    {"name": "builds", "description": "The builds of a model kept in graph.db, to pick two for diff.",
+     "inputSchema": {"type": "object", "required": ["app"], "properties": {"app": _APP}}},
+    {"name": "diff", "description": "What changed between two builds: new workflows, changed fingerprints, gone things.",
+     "inputSchema": {"type": "object", "required": ["app"],
+                     "properties": {"app": _APP,
+                                    "from": {"type": "string", "description": "build id or label (default: previous)"},
+                                    "to": {"type": "string", "description": "build id or label (default: latest)"}}}},
+    {"name": "gaps", "description": "The model's open questions, ranked by how much resolving each would tell you.",
+     "inputSchema": {"type": "object", "required": ["app"], "properties": {"app": _APP}}},
+    {"name": "openapi", "description": "The observed API as an OpenAPI 3.0 document (JSON).",
+     "inputSchema": {"type": "object", "required": ["app"], "properties": {"app": _APP}}},
+]
+
+
+class ToolError(Exception):
+    pass
+
+
+def _name(value, what: str) -> str:
+    if not isinstance(value, str) or not _NAME_RE.match(value):
+        raise ToolError(f"{what} must be letters, digits, '.', '_' or '-'")
+    return value
+
+
+def _text(value, what: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ToolError(f"{what} is required")
+    return value
+
+
+def _run(argv: list[str]) -> tuple[int, str]:
+    """Run one CLI command and capture what it prints."""
+    from .app import main
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        try:
+            rc = main(argv)
+        except SystemExit as e:                     # argparse refusing an argument
+            rc = e.code if isinstance(e.code, int) else 2
+    text = out.getvalue()
+    if err.getvalue().strip():
+        text = (text + "\n" + err.getvalue()).strip()
+    return rc or 0, text.strip()
+
+
+def list_models(root: str) -> str:
+    rows = []
+    for name in sorted(os.listdir(root)) if os.path.isdir(root) else []:
+        path = os.path.join(root, name, "model.json")
+        if not os.path.isfile(path):
+            continue
+        try:
+            with open(path, encoding="utf-8") as f:
+                m = json.load(f)
+        except (OSError, ValueError):
+            continue
+        c = m.get("counts", {})
+        rows.append(f"{name}: {c.get('endpoints', 0)} APIs, {c.get('routes', 0)} routes, "
+                    f"{c.get('hosts', 0)} hosts, {len(m.get('evidence', []))} requests"
+                    + (f", roles {', '.join(m.get('roles', []))}" if m.get("roles") else ""))
+    return "\n".join(rows) or f"no models in {root} (build one with `proxy2model FILE -w NAME`)"
+
+
+def call(tool: str, a: dict, root: str) -> tuple[bool, str]:
+    """(ok, text) for one tool call. Options go before `--`, values after, so no value is read as a flag."""
+    out = ["--out", root]
+    if tool == "list_models":
+        return True, list_models(root)
+    app = _name(a.get("app"), "app")
+    if tool == "query":
+        argv = ["query", *out, "--", app, _text(a.get("question"), "question")]
+    elif tool == "bql":
+        limit = a.get("limit", 100)
+        if not isinstance(limit, int) or not 1 <= limit <= 1000:
+            raise ToolError("limit must be 1 to 1000")
+        argv = ["q", *out, "--limit", str(limit), "--", app, _text(a.get("expression"), "expression")]
+    elif tool == "cross_role":
+        argv = ["cross-role", *out, "--low", _name(a.get("low"), "low"), "--high", _name(a.get("high"), "high"),
+                "--", app]
+    elif tool == "builds":
+        argv = ["builds", *out, "--", app]
+    elif tool == "diff":
+        refs = [_text(a[k], k) for k in ("from", "to") if a.get(k) is not None]
+        if a.get("to") is not None and a.get("from") is None:
+            refs = ["previous"] + refs
+        argv = ["diff", *out, "--", app, *refs]
+    elif tool == "gaps":
+        argv = ["gaps", *out, "--", app]
+    elif tool == "openapi":
+        argv = ["openapi", *out, "--", app]
+    else:
+        raise ToolError(f"unknown tool {tool!r}")
+    rc, text = _run(argv)
+    return rc == 0, text or "(no output)"
+
+
+def handle(msg: dict, root: str) -> dict | None:
+    """One JSON-RPC message in, the response out (None for a notification)."""
+    mid, method, params = msg.get("id"), msg.get("method"), msg.get("params") or {}
+    if mid is None:
+        return None                                  # notifications/initialized and friends
+    if method == "initialize":
+        wanted = params.get("protocolVersion")
+        result = {"protocolVersion": wanted if wanted in PROTOCOLS else PROTOCOLS[0],
+                  "capabilities": {"tools": {}},
+                  "serverInfo": {"name": "proxy2model", "version": __version__},
+                  "instructions": "Models of web apps built from captured traffic. Start with list_models, then "
+                                  "query <app> help. Every answer cites evidence ids (ev_N); absence means the "
+                                  "capture did not show it, not that it does not exist. Never call anything a "
+                                  "vulnerability: these are leads to verify in an authorized session."}
+    elif method == "ping":
+        result = {}
+    elif method == "tools/list":
+        result = {"tools": TOOLS}
+    elif method == "tools/call":
+        try:
+            ok, text = call(params.get("name"), params.get("arguments") or {}, root)
+        except ToolError as e:
+            ok, text = False, str(e)
+        result = {"content": [{"type": "text", "text": text}], "isError": not ok}
+    else:
+        return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"unknown method {method}"}}
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def serve_stdio(root: str, stdin=None, stdout=None) -> int:
+    stdin, stdout = stdin or sys.stdin, stdout or sys.stdout
+    for line in stdin:
+        if not line.strip():
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            reply = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "parse error"}}
+        else:
+            reply = handle(msg, root) if isinstance(msg, dict) else \
+                {"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "invalid request"}}
+        if reply is not None:
+            stdout.write(json.dumps(reply) + "\n")
+            stdout.flush()
+    return 0
+
+
+def cmd_mcp(args) -> int:
+    root = os.path.abspath(args.out)
+    print(f"proxy2model mcp: serving models in {root} over stdio", file=sys.stderr)
+    return serve_stdio(root)

proxy2model/cli/ui.py

@@ -0,0 +1,62 @@
+"""Terminal output: a little colour on a terminal, plain text when piped or NO_COLOR is set."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_CODES = {"bold": "1", "dim": "2", "accent": "38;5;208", "green": "32", "yellow": "33", "red": "31", "cyan": "36"}
+
+
+def color_on(stream=None) -> bool:
+    stream = stream or sys.stdout
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    return hasattr(stream, "isatty") and stream.isatty() and os.environ.get("TERM") != "dumb"
+
+
+def style(text, *names: str, stream=None) -> str:
+    if not names or not color_on(stream):
+        return str(text)
+    return "\033[" + ";".join(_CODES[n] for n in names) + "m" + str(text) + "\033[0m"
+
+
+def title(command: str, subject: str = "") -> str:
+    """`proxy2model · build · shop`"""
+    parts = [style("proxy2model", "bold", "accent"), style(command, "bold")]
+    if subject:
+        parts.append(subject)
+    return style(" · ", "dim").join(parts)
+
+
+def row(label: str, value: str, width: int = 8) -> str:
+    """One `  label   value` line; continuation lines of `value` line up under it."""
+    pad = " " * (width + 4)
+    lines = str(value).split("\n")
+    out = "  " + style(label.ljust(width), "dim") + "  " + lines[0]
+    return "\n".join([out] + [pad + ln for ln in lines[1:]])
+
+
+def stat(n, noun: str) -> str:
+    """`3 routes`, `1 host`: the count bold, the noun plural when it should be."""
+    return f"{style(n, 'bold')} {noun if n == 1 else noun + 's'}"
+
+
+def files(entries: list[tuple[str, str]]) -> str:
+    """Aligned `name   what it is` lines."""
+    w = max(len(n) for n, _ in entries)
+    return "\n".join(f"{n.ljust(w)}   {style(d, 'dim')}" for n, d in entries)
+
+
+def ok(msg: str) -> str:
+    return style("✓", "green", stream=sys.stderr) + " " + msg
+
+
+def warn(msg: str) -> str:
+    return style("warning:", "yellow", stream=sys.stderr) + " " + msg
+
+
+def error(msg: str) -> str:
+    return style("error:", "red", "bold", stream=sys.stderr) + " " + msg

proxy2model/core/__init__.py

@@ -0,0 +1 @@
+"""The model: building it, reasoning over it, and comparing builds."""