pywrit 0.2.5__tar.gz → 0.2.7__tar.gz

{pywrit-0.2.5/src/pywrit.egg-info → pywrit-0.2.7}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: pywrit
-Version: 0.2.5
+Version: 0.2.7
 Summary: Python client + CLI for Writ — the gate before the write
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/AvenueDAdmin/pywrit
 Project-URL: Documentation, https://withwrit.com/docs
 Requires-Python: >=3.9
@@ -40,6 +40,18 @@ pip install pywrit
 
 Requires Python 3.9+. Installs the `writ` command and the `pywrit` Python client.
 
+**JavaScript/TypeScript devs:** run the scanner with no Python setup via npm:
+
+```bash
+npx writ-scan .
+```
+
+The `writ-scan` package wraps the same scanner (including TS/JS support). On
+first run it installs `pywrit[polyglot]` from PyPI using your Python 3.9+
+(one-time); afterwards it starts instantly. See [`npm/`](npm/) for details,
+environment overrides (`WRIT_PYTHON`, `WRIT_SCAN_NO_INSTALL`), and the
+install test.
+
 ## 60-second quickstart: scan → apply → gate
 
 **1. Scan.** See which functions write, and how many of them are gated.
@@ -142,6 +154,23 @@ clients, Prisma writes, and JS SDK calls such as `stripe.refunds.create(...)`.
 
 ![writ scan on a TypeScript agent finds 5 write sites, 1 of 5 gated](https://raw.githubusercontent.com/AvenueDAdmin/pywrit/main/docs/assets/scan-tsjs.gif)
 
+## GitHub Action
+
+Scan every pull request for ungated write sites. Findings land as check
+annotations on the exact file and line, plus a Markdown risk report in the
+job summary. The check fails when an ungated finding meets your
+`fail-on-risk` threshold (default: `high`).
+
+```yaml
+- uses: actions/checkout@v4
+- uses: AvenueDAdmin/pywrit@v0
+  with:
+    fail-on-risk: high   # high | medium | low | never
+```
+
+No API key needed. Full reference: [docs/github-action.md](docs/github-action.md) ·
+example workflow: [examples/github-action/writ-scan.yml](examples/github-action/writ-scan.yml)
+
 ## Python client
 
 ```python
@@ -205,6 +234,32 @@ writ grant --sponsor acme --agent agent-7 --verb payments.refund \
 Sponsor-token commands (`revoke`, `reinstate`, `revoked`, `grant`) read
 `--sponsor-token` or `WRIT_SPONSOR_TOKEN`. Run `writ --help` for the full command list.
 
+## README badge
+
+Show that your agent's writes are gated by Writ. Two flavors:
+
+**Static** (works today, no API key) — same design, no live count:
+
+```md
+[![agent writes gated by Writ](https://cdn.jsdelivr.net/gh/AvenueDAdmin/pywrit@main/badge/writ-gated.svg)](https://withwrit.com)
+```
+
+**Dynamic** (live 30-day gated-write count from your audit log) — mint a badge
+token, then embed the snippet the API returns:
+
+```bash
+curl -s https://api.withwrit.com/v1/badge/tokens \
+  -H "Authorization: Bearer writ_..." \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+The dynamic endpoint ships with the gate — until it's live, `POST /v1/badge/tokens`
+returns 404 and the static badge above is the one to use.
+
+See [`badge/`](badge/) for embed docs and the verification model (what the
+badge proves — and what it doesn't).
+
 ## Docs
 
 Full docs: [docs.withwrit.com](https://docs.withwrit.com) ·

{pywrit-0.2.5 → pywrit-0.2.7}/README.md

@@ -18,6 +18,18 @@ pip install pywrit
 
 Requires Python 3.9+. Installs the `writ` command and the `pywrit` Python client.
 
+**JavaScript/TypeScript devs:** run the scanner with no Python setup via npm:
+
+```bash
+npx writ-scan .
+```
+
+The `writ-scan` package wraps the same scanner (including TS/JS support). On
+first run it installs `pywrit[polyglot]` from PyPI using your Python 3.9+
+(one-time); afterwards it starts instantly. See [`npm/`](npm/) for details,
+environment overrides (`WRIT_PYTHON`, `WRIT_SCAN_NO_INSTALL`), and the
+install test.
+
 ## 60-second quickstart: scan → apply → gate
 
 **1. Scan.** See which functions write, and how many of them are gated.
@@ -120,6 +132,23 @@ clients, Prisma writes, and JS SDK calls such as `stripe.refunds.create(...)`.
 
 ![writ scan on a TypeScript agent finds 5 write sites, 1 of 5 gated](https://raw.githubusercontent.com/AvenueDAdmin/pywrit/main/docs/assets/scan-tsjs.gif)
 
+## GitHub Action
+
+Scan every pull request for ungated write sites. Findings land as check
+annotations on the exact file and line, plus a Markdown risk report in the
+job summary. The check fails when an ungated finding meets your
+`fail-on-risk` threshold (default: `high`).
+
+```yaml
+- uses: actions/checkout@v4
+- uses: AvenueDAdmin/pywrit@v0
+  with:
+    fail-on-risk: high   # high | medium | low | never
+```
+
+No API key needed. Full reference: [docs/github-action.md](docs/github-action.md) ·
+example workflow: [examples/github-action/writ-scan.yml](examples/github-action/writ-scan.yml)
+
 ## Python client
 
 ```python
@@ -183,6 +212,32 @@ writ grant --sponsor acme --agent agent-7 --verb payments.refund \
 Sponsor-token commands (`revoke`, `reinstate`, `revoked`, `grant`) read
 `--sponsor-token` or `WRIT_SPONSOR_TOKEN`. Run `writ --help` for the full command list.
 
+## README badge
+
+Show that your agent's writes are gated by Writ. Two flavors:
+
+**Static** (works today, no API key) — same design, no live count:
+
+```md
+[![agent writes gated by Writ](https://cdn.jsdelivr.net/gh/AvenueDAdmin/pywrit@main/badge/writ-gated.svg)](https://withwrit.com)
+```
+
+**Dynamic** (live 30-day gated-write count from your audit log) — mint a badge
+token, then embed the snippet the API returns:
+
+```bash
+curl -s https://api.withwrit.com/v1/badge/tokens \
+  -H "Authorization: Bearer writ_..." \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+The dynamic endpoint ships with the gate — until it's live, `POST /v1/badge/tokens`
+returns 404 and the static badge above is the one to use.
+
+See [`badge/`](badge/) for embed docs and the verification model (what the
+badge proves — and what it doesn't).
+
 ## Docs
 
 Full docs: [docs.withwrit.com](https://docs.withwrit.com) ·

{pywrit-0.2.5 → pywrit-0.2.7}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pywrit"
-version = "0.2.5"
+version = "0.2.7"
 description = "Python client + CLI for Writ — the gate before the write"
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
 requires-python = ">=3.9"
 dependencies = ["httpx>=0.27"]
 

{pywrit-0.2.5 → pywrit-0.2.7}/src/pywrit/__init__.py

@@ -27,7 +27,7 @@ from .errors import (
     WritError,
 )
 
-__version__ = "0.2.5"
+__version__ = "0.2.7"
 
 __all__ = [
     "WritClient",

{pywrit-0.2.5 → pywrit-0.2.7}/src/pywrit/cli.py

@@ -1072,6 +1072,68 @@ def _tsjs_scan(root, excludes):
         res["gated"].update((str(path),) + g for g in gated)
     return res
 
+# ---------------------------------------------------------------------------
+# writ scan --format json: machine-readable risk report for CI (GitHub Action,
+# editor integrations). Pure read-only: prints one JSON document to stdout.
+# ---------------------------------------------------------------------------
+_RISK_ORDER = {"high": 0, "medium": 1, "low": 2}
+
+
+def _scan_findings_json(root, sites, gated_funcs, tsjs, ts_sites):
+    """Return the findings list for `writ scan --format json`.
+
+    Each finding is a dict with file (repo-relative, posix), line, function,
+    verb, risk tier, gated flag, kind, language, and a short snippet.
+    """
+    findings = []
+    for s in sites:
+        rel = _pathlib.Path(s.file).relative_to(root)
+        verb = infer_verb(rel, s.func, s.cls, s.kind)
+        findings.append({
+            "file": rel.as_posix(),
+            "line": s.lineno,
+            "function": s.func or "<module>",
+            "verb": verb,
+            "risk": _risk_tier(verb),
+            "gated": (s.file, s.func) in gated_funcs,
+            "kind": s.kind,
+            "language": "python",
+            "snippet": (s.snippet or "")[:200],
+        })
+    for s, _rid, fkey in ts_sites:
+        rel = _pathlib.Path(s.file).relative_to(root)
+        verb = _tsjs_verb(rel, fkey[0], s.cls, s.kind)
+        findings.append({
+            "file": rel.as_posix(),
+            "line": s.lineno,
+            "function": fkey[0] or "<module>",
+            "verb": verb,
+            "risk": _risk_tier(verb),
+            "gated": (s.file,) + fkey in tsjs["gated"],
+            "kind": s.kind,
+            "language": "tsjs",
+            "snippet": (s.snippet or "")[:200],
+        })
+    findings.sort(key=lambda f: (_RISK_ORDER[f["risk"]], f["file"], f["line"]))
+    return findings
+
+
+def print_scan_json(root, files, skipped, sites, gated_funcs, tsjs, ts_sites):
+    """Print the machine-readable scan report. Read-only: no files written."""
+    from . import __version__
+    doc = {
+        "scanner": "pywrit",
+        "version": __version__,
+        "root": str(root),
+        "files_scanned": len(files) + len(tsjs.get("files", [])),
+        "files_skipped": len(skipped) + len(tsjs.get("skipped", [])),
+        "tsjs_hint": bool(tsjs.get("missing_extra")),
+        "findings": _scan_findings_json(root, sites, gated_funcs, tsjs,
+                                        ts_sites),
+    }
+    print(json.dumps(doc, indent=2))
+
+
 def scan_cmd(args):
     import json as _json
     root = _pathlib.Path(args.path).resolve()
@@ -1114,6 +1176,13 @@ def scan_cmd(args):
     total = len(sites)
     pct = (100 * gated_site_count // total) if total else 100
 
+    if getattr(args, "format", "text") == "json":
+        # Machine-readable risk report for CI. Read-only: no policy file,
+        # no diffs, no prompts.
+        print_scan_json(root, files, skipped, sites, gated_funcs, tsjs,
+                        ts_sites)
+        return 0
+
     verbs = {}
     for (f, func_name, cls_name), ss in sorted(by_func.items()):
         rel = _pathlib.Path(f).relative_to(root)
@@ -1601,6 +1670,10 @@ def main():
                       help="Apply without prompting")
     scan.add_argument("--score", action="store_true",
                       help="Print only the Writ Score risk report (no diff, no policy file)")
+    scan.add_argument("--format", choices=("text", "json"), default="text",
+                      help="Output format: human-readable text (default) or "
+                           "machine-readable JSON risk report (read-only; no "
+                           "policy file, no diffs)")
     scan.add_argument("--push-policy", action="store_true",
                       help="PUT the discovered policy to the gate (needs --key)")
     scan.add_argument("--key", default="",

{pywrit-0.2.5 → pywrit-0.2.7/src/pywrit.egg-info}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: pywrit
-Version: 0.2.5
+Version: 0.2.7
 Summary: Python client + CLI for Writ — the gate before the write
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/AvenueDAdmin/pywrit
 Project-URL: Documentation, https://withwrit.com/docs
 Requires-Python: >=3.9
@@ -40,6 +40,18 @@ pip install pywrit
 
 Requires Python 3.9+. Installs the `writ` command and the `pywrit` Python client.
 
+**JavaScript/TypeScript devs:** run the scanner with no Python setup via npm:
+
+```bash
+npx writ-scan .
+```
+
+The `writ-scan` package wraps the same scanner (including TS/JS support). On
+first run it installs `pywrit[polyglot]` from PyPI using your Python 3.9+
+(one-time); afterwards it starts instantly. See [`npm/`](npm/) for details,
+environment overrides (`WRIT_PYTHON`, `WRIT_SCAN_NO_INSTALL`), and the
+install test.
+
 ## 60-second quickstart: scan → apply → gate
 
 **1. Scan.** See which functions write, and how many of them are gated.
@@ -142,6 +154,23 @@ clients, Prisma writes, and JS SDK calls such as `stripe.refunds.create(...)`.
 
 ![writ scan on a TypeScript agent finds 5 write sites, 1 of 5 gated](https://raw.githubusercontent.com/AvenueDAdmin/pywrit/main/docs/assets/scan-tsjs.gif)
 
+## GitHub Action
+
+Scan every pull request for ungated write sites. Findings land as check
+annotations on the exact file and line, plus a Markdown risk report in the
+job summary. The check fails when an ungated finding meets your
+`fail-on-risk` threshold (default: `high`).
+
+```yaml
+- uses: actions/checkout@v4
+- uses: AvenueDAdmin/pywrit@v0
+  with:
+    fail-on-risk: high   # high | medium | low | never
+```
+
+No API key needed. Full reference: [docs/github-action.md](docs/github-action.md) ·
+example workflow: [examples/github-action/writ-scan.yml](examples/github-action/writ-scan.yml)
+
 ## Python client
 
 ```python
@@ -205,6 +234,32 @@ writ grant --sponsor acme --agent agent-7 --verb payments.refund \
 Sponsor-token commands (`revoke`, `reinstate`, `revoked`, `grant`) read
 `--sponsor-token` or `WRIT_SPONSOR_TOKEN`. Run `writ --help` for the full command list.
 
+## README badge
+
+Show that your agent's writes are gated by Writ. Two flavors:
+
+**Static** (works today, no API key) — same design, no live count:
+
+```md
+[![agent writes gated by Writ](https://cdn.jsdelivr.net/gh/AvenueDAdmin/pywrit@main/badge/writ-gated.svg)](https://withwrit.com)
+```
+
+**Dynamic** (live 30-day gated-write count from your audit log) — mint a badge
+token, then embed the snippet the API returns:
+
+```bash
+curl -s https://api.withwrit.com/v1/badge/tokens \
+  -H "Authorization: Bearer writ_..." \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+The dynamic endpoint ships with the gate — until it's live, `POST /v1/badge/tokens`
+returns 404 and the static badge above is the one to use.
+
+See [`badge/`](badge/) for embed docs and the verification model (what the
+badge proves — and what it doesn't).
+
 ## Docs
 
 Full docs: [docs.withwrit.com](https://docs.withwrit.com) ·

{pywrit-0.2.5 → pywrit-0.2.7}/src/pywrit.egg-info/SOURCES.txt

@@ -12,4 +12,5 @@ src/pywrit.egg-info/entry_points.txt
 src/pywrit.egg-info/requires.txt
 src/pywrit.egg-info/top_level.txt
 tests/test_client.py
+tests/test_scan_json.py
 tests/test_scan_tsjs.py

pywrit-0.2.7/tests/test_scan_json.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Tests for `writ scan --format json` (the GitHub Action's input).
+
+Run with: python -m pytest tests/test_scan_json.py
+"""
+
+import argparse
+import contextlib
+import io
+import json
+import pathlib
+import tempfile
+import unittest
+
+from pywrit import cli
+
+
+def _args(path, **kw):
+    ns = argparse.Namespace(path=str(path), exclude=[], policy_out="writ-policy.json",
+                            apply=False, yes=False, score=False, push_policy=False,
+                            key="", format="json")
+    for k, v in kw.items():
+        setattr(ns, k, v)
+    return ns
+
+
+def _run_scan_json(root, **kw):
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        code = cli.scan_cmd(_args(root, **kw))
+    return code, json.loads(buf.getvalue())
+
+
+FIXTURE = '''\
+import requests
+
+
+def issue_refund(payment_id, amount_cents):
+    """High risk: money movement, ungated."""
+    resp = requests.post(
+        "https://api.example.com/refunds",
+        json={"payment": payment_id, "amount": amount_cents},
+    )
+    return resp.json()
+
+
+def send_receipt(order_id, email):
+    """Medium risk: outbound email, ungated."""
+    import smtplib
+
+    server = smtplib.SMTP("smtp.example.com")
+    server.sendmail("noreply@example.com", [email], "receipt %s" % order_id)
+
+
+def cancel_subscription(subscription_id):
+    """Gated: already behind a writ gate, must not be reported."""
+    if _writ_check("subscriptions.cancel", subscription_id,
+                   "user requested cancellation") != "ALLOW":
+        raise RuntimeError("denied")
+    requests.post("https://api.example.com/subs/cancel",
+                  json={"id": subscription_id})
+'''
+
+NOTIFY_FIXTURE = '''\
+import smtplib
+
+
+def send_receipt(order_id, email):
+    """Medium risk: outbound email, ungated."""
+    server = smtplib.SMTP("smtp.example.com")
+    server.sendmail("noreply@example.com", [email], "receipt %s" % order_id)
+
+
+def log_event(name):
+    """Low risk: local append-only log, ungated."""
+    with open("events.log", "a") as fh:
+        fh.write(name + "\\n")
+'''
+
+
+class ScanJsonTest(unittest.TestCase):
+    def _repo(self, td):
+        root = pathlib.Path(td) / "repo"
+        root.mkdir()
+        (root / "billing.py").write_text(FIXTURE, encoding="utf-8")
+        (root / "notify.py").write_text(NOTIFY_FIXTURE, encoding="utf-8")
+        return root
+
+    def test_json_document_shape(self):
+        with tempfile.TemporaryDirectory() as td:
+            code, doc = _run_scan_json(self._repo(td))
+        self.assertEqual(code, 0)
+        for key in ("scanner", "version", "root", "files_scanned",
+                    "files_skipped", "findings"):
+            self.assertIn(key, doc)
+        self.assertEqual(doc["scanner"], "pywrit")
+        self.assertGreaterEqual(len(doc["findings"]), 3)
+
+    def test_finding_fields_and_risk_tiers(self):
+        with tempfile.TemporaryDirectory() as td:
+            _code, doc = _run_scan_json(self._repo(td))
+        by_func = {f["function"]: f for f in doc["findings"]}
+        for name in ("issue_refund", "send_receipt", "log_event",
+                     "cancel_subscription"):
+            self.assertIn(name, by_func, doc["findings"])
+            for key in ("file", "line", "function", "verb", "risk", "gated",
+                        "kind", "language", "snippet"):
+                self.assertIn(key, by_func[name])
+        # refunds are money movement -> high; email send -> medium;
+        # local log append -> low
+        self.assertEqual(by_func["issue_refund"]["risk"], "high")
+        self.assertEqual(by_func["send_receipt"]["risk"], "medium")
+        self.assertEqual(by_func["log_event"]["risk"], "low")
+        # gated writes are flagged so the action can skip them
+        self.assertTrue(by_func["cancel_subscription"]["gated"])
+        self.assertFalse(by_func["issue_refund"]["gated"])
+        self.assertEqual(by_func["issue_refund"]["file"], "billing.py")
+        self.assertEqual(by_func["send_receipt"]["file"], "notify.py")
+        for f in doc["findings"]:
+            self.assertIsInstance(f["line"], int)
+            self.assertGreater(f["line"], 0)
+
+    def test_findings_sorted_high_first(self):
+        with tempfile.TemporaryDirectory() as td:
+            _code, doc = _run_scan_json(self._repo(td))
+        order = {"high": 0, "medium": 1, "low": 2}
+        tiers = [order[f["risk"]] for f in doc["findings"]]
+        self.assertEqual(tiers, sorted(tiers))
+
+    def test_json_is_read_only(self):
+        # --format json must not write the policy file or anything else.
+        with tempfile.TemporaryDirectory() as td:
+            root = self._repo(td)
+            code, _doc = _run_scan_json(root)
+            self.assertEqual(code, 0)
+            self.assertEqual(
+                sorted(p.name for p in root.iterdir()),
+                ["billing.py", "notify.py"])
+
+    def test_empty_repo_gives_empty_findings(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = pathlib.Path(td) / "repo"
+            root.mkdir()
+            (root / "clean.py").write_text("X = 1\n", encoding="utf-8")
+            code, doc = _run_scan_json(root)
+        self.assertEqual(code, 0)
+        self.assertEqual(doc["findings"], [])
+
+
+if __name__ == "__main__":
+    unittest.main()