pywrit 0.2.9__tar.gz → 0.2.11__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pywrit
3
- Version: 0.2.9
3
+ Version: 0.2.11
4
4
  Summary: Python client + CLI for Writ — the gate before the write
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://github.com/withwrit/pywrit
@@ -151,6 +151,18 @@ optional extra (tree-sitter based):
151
151
  Without the extra, the scanner prints a one-line hint and keeps going —
152
152
  Python scanning never needs it.
153
153
 
154
+ Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
155
+ benchmark/, demo/, and build-tooling files such as gulpfile.js or
156
+ webpack.config.*) are suppressed by default: the report counts them per
157
+ class and names every suppressed path instead of listing them as findings.
158
+ Pass `--include-non-product` to report them like any other finding.
159
+
160
+ Every scan report ends with a one-line pointer to the Writ GitHub App
161
+ (install: https://github.com/apps/writ-scanner, guide:
162
+ https://docs.withwrit.com/git-hub-app), which runs the scan on every push
163
+ and pull request; the JSON report (`--format json`) carries the same
164
+ pointer under `github_app`.
165
+
154
166
  TS/JS is **scan-only**: findings are listed with verbs for your policy file,
155
167
  but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
156
168
  Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
@@ -183,16 +195,17 @@ example workflow: [examples/github-action/writ-scan.yml](examples/github-action/
183
195
 
184
196
  ## GitHub App
185
197
 
186
- Install the [Writ GitHub App](https://docs.withwrit.com/git-hub-app) on selected
198
+ Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
187
199
  repositories: every push and pull request is scanned for ungated write-sites,
188
200
  with results as a check run on the PR and in the
189
201
  [portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
202
+ Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
190
203
 
191
204
  ## MCP server (`writ-mcp`)
192
205
 
193
206
  Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
194
207
  [Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
195
- built on the MCP Python SDK) that exposes the Writ gate as **8 MCP tools**:
208
+ built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
196
209
  the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
197
210
  `DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
198
211
  every decision.
@@ -212,13 +225,21 @@ pip install writ-mcp # then run `writ-mcp`
212
225
  | `writ_receipts` | Read the tenant's audit log |
213
226
  | `writ_policy` | Manage the verb policy |
214
227
  | `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
228
+ | `writ_github_installations` | List connected GitHub App installations |
229
+ | `writ_github_set_threshold` | Set the check-run fail threshold per install |
230
+ | `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
231
+ | `writ_manifests` | List repos with risk profiles or fetch one manifest |
232
+ | `writ_explain_receipt` | Explain a receipt in plain language |
233
+ | `writ_tenant_notify` | Get or update step-up notification settings |
234
+ | `writ_principals` | List the tenant's principals |
235
+ | `writ_verbs` | List the tenant's verb vocabulary |
236
+ | `writ_keys` | List API key metadata |
215
237
 
216
238
  The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
217
239
  free, no credit card. `writ_sandbox` works with no key at all.
218
240
 
219
241
  The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
220
- official MCP Registry as `io.github.withwrit/writ`, on
221
- [Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
242
+ official MCP Registry as `io.github.withwrit/writ` and listed on
222
243
  [Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
223
244
 
224
245
  ## Python client
@@ -129,6 +129,18 @@ optional extra (tree-sitter based):
129
129
  Without the extra, the scanner prints a one-line hint and keeps going —
130
130
  Python scanning never needs it.
131
131
 
132
+ Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
133
+ benchmark/, demo/, and build-tooling files such as gulpfile.js or
134
+ webpack.config.*) are suppressed by default: the report counts them per
135
+ class and names every suppressed path instead of listing them as findings.
136
+ Pass `--include-non-product` to report them like any other finding.
137
+
138
+ Every scan report ends with a one-line pointer to the Writ GitHub App
139
+ (install: https://github.com/apps/writ-scanner, guide:
140
+ https://docs.withwrit.com/git-hub-app), which runs the scan on every push
141
+ and pull request; the JSON report (`--format json`) carries the same
142
+ pointer under `github_app`.
143
+
132
144
  TS/JS is **scan-only**: findings are listed with verbs for your policy file,
133
145
  but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
134
146
  Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
@@ -161,16 +173,17 @@ example workflow: [examples/github-action/writ-scan.yml](examples/github-action/
161
173
 
162
174
  ## GitHub App
163
175
 
164
- Install the [Writ GitHub App](https://docs.withwrit.com/git-hub-app) on selected
176
+ Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
165
177
  repositories: every push and pull request is scanned for ungated write-sites,
166
178
  with results as a check run on the PR and in the
167
179
  [portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
180
+ Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
168
181
 
169
182
  ## MCP server (`writ-mcp`)
170
183
 
171
184
  Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
172
185
  [Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
173
- built on the MCP Python SDK) that exposes the Writ gate as **8 MCP tools**:
186
+ built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
174
187
  the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
175
188
  `DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
176
189
  every decision.
@@ -190,13 +203,21 @@ pip install writ-mcp # then run `writ-mcp`
190
203
  | `writ_receipts` | Read the tenant's audit log |
191
204
  | `writ_policy` | Manage the verb policy |
192
205
  | `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
206
+ | `writ_github_installations` | List connected GitHub App installations |
207
+ | `writ_github_set_threshold` | Set the check-run fail threshold per install |
208
+ | `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
209
+ | `writ_manifests` | List repos with risk profiles or fetch one manifest |
210
+ | `writ_explain_receipt` | Explain a receipt in plain language |
211
+ | `writ_tenant_notify` | Get or update step-up notification settings |
212
+ | `writ_principals` | List the tenant's principals |
213
+ | `writ_verbs` | List the tenant's verb vocabulary |
214
+ | `writ_keys` | List API key metadata |
193
215
 
194
216
  The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
195
217
  free, no credit card. `writ_sandbox` works with no key at all.
196
218
 
197
219
  The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
198
- official MCP Registry as `io.github.withwrit/writ`, on
199
- [Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
220
+ official MCP Registry as `io.github.withwrit/writ` and listed on
200
221
  [Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
201
222
 
202
223
  ## Python client
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pywrit"
7
- version = "0.2.9"
7
+ version = "0.2.11"
8
8
  description = "Python client + CLI for Writ — the gate before the write"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -27,7 +27,7 @@ from .errors import (
27
27
  WritError,
28
28
  )
29
29
 
30
- __version__ = "0.2.8"
30
+ __version__ = "0.2.11"
31
31
 
32
32
  __all__ = [
33
33
  "WritClient",
@@ -591,6 +591,19 @@ _SCORE_GAPS = [
591
591
  "indirect writes through shared HTTP clients several layers down",
592
592
  ]
593
593
 
594
+ # Every scan report closes with a pointer at the GitHub App: the local scan
595
+ # is invisible by design, the app is the visible surface (a scan on every
596
+ # push and pull request, check runs, history in the portal). The same
597
+ # pointer rides the JSON report under `github_app` for machine consumers.
598
+ # Text and JSON share these constants so they cannot drift.
599
+ _GITHUB_APP_INSTALL_URL = "https://github.com/apps/writ-scanner"
600
+ _GITHUB_APP_DOCS_URL = "https://docs.withwrit.com/git-hub-app"
601
+ _GITHUB_APP_NOTE = ("Run this scan on every push and pull request with the "
602
+ "Writ GitHub App: check runs on each change, history in "
603
+ "the portal.")
604
+ _GITHUB_APP_LINE = "%s Install: %s (guide: %s)" % (
605
+ _GITHUB_APP_NOTE, _GITHUB_APP_INSTALL_URL, _GITHUB_APP_DOCS_URL)
606
+
594
607
 
595
608
  def _risk_tier(verb):
596
609
  """Classify an inferred verb (domain.action) into high/medium/low risk.
@@ -826,6 +839,54 @@ _TSJS_EXTS = {".ts": "typescript", ".tsx": "tsx", ".js": "javascript",
826
839
  _TSJS_SKIP_DIR_NAMES = _SKIP_DIR_NAMES | {".next", "vendor", "venv", ".venv"}
827
840
  _TSJS_TEST_DIRS = {"tests", "testing", "__tests__"}
828
841
  _TSJS_MAX_BYTES = 1000000 # larger files are almost always bundles
842
+
843
+ # Non-product path classes. Write findings from these paths parse as real
844
+ # writes but are almost never product behavior — docs tooling, build/test
845
+ # scripts, demos, benchmarks (the axios-class scan noise: gulpfile.js,
846
+ # docs/scripts/*, sandbox/*, scripts/benchmark-*). They are suppressed from
847
+ # the report by default — counted per class under "suppressed" — and
848
+ # restored with --include-non-product. Matching is by whole directory
849
+ # segment or exact build-file basename, never filename substring, so
850
+ # product code next to an excluded directory (and files like
851
+ # lib/benchmark-utils.ts) stays reported. This is the single, central
852
+ # exclusion list for TS/JS; don't scatter string matches elsewhere.
853
+ _TSJS_NON_PRODUCT_DIRS = {
854
+ "docs": {"docs", "doc"},
855
+ "scripts": {"scripts"},
856
+ "examples": {"examples", "example"},
857
+ "sandbox": {"sandbox"},
858
+ "benchmark": {"benchmark", "benchmarks"},
859
+ "demo": {"demo", "demos"},
860
+ }
861
+ _TSJS_BUILD_TOOL_FILE = _re.compile(
862
+ r"^(gulpfile|gruntfile)(\.babel)?\.(js|mjs|cjs|ts)$"
863
+ r"|^(webpack|rollup|vite|esbuild|tsup|snowpack|babel)\.config\.(js|mjs|cjs|ts)$"
864
+ r"|^karma\.conf\.(js|mjs|cjs|ts)$", _re.I)
865
+
866
+
867
+ def _tsjs_non_product_class(path, root):
868
+ """Return the non-product path class for a TS/JS file, or None.
869
+
870
+ Directory classes match on whole path segments (docs/, scripts/,
871
+ sandbox/, examples/, benchmark/, demo/ at any depth), so a product
872
+ file beside an excluded directory is unaffected. Build-tooling files
873
+ (gulpfile.js, Gruntfile.js, webpack.config.*, rollup.config.*,
874
+ vite.config.*, and equivalents) match by exact basename anywhere in
875
+ the tree so monorepo package configs are covered too.
876
+ """
877
+ rel = path.relative_to(root)
878
+ segs = set(rel.parts[:-1])
879
+ for cls, names in _TSJS_NON_PRODUCT_DIRS.items():
880
+ if segs & names:
881
+ return cls
882
+ if _TSJS_BUILD_TOOL_FILE.match(path.name):
883
+ return "build-tooling"
884
+ return None
885
+
886
+
887
+ def _tsjs_suppressed_total(suppressed):
888
+ """Total suppressed sites across all non-product classes."""
889
+ return sum(b["sites"] for b in (suppressed or {}).values())
829
890
  _TSJS_HINT = ("hint: %d TS/JS file(s) not scanned; install the extra: "
830
891
  "pip install 'pywrit[polyglot]'")
831
892
  _TSJS_WRITE_METHODS = {"post", "put", "patch", "delete"}
@@ -1289,12 +1350,17 @@ def _tsjs_verb(rel, func_name, cls_name, kind):
1289
1350
  return infer_verb(base, snake, cls_name, kind)
1290
1351
 
1291
1352
 
1292
- def _tsjs_scan(root, excludes):
1293
- """Return dict with files, skipped, sites, gated, or hint when the
1294
- extra is missing. Never raises on a bad file."""
1353
+ def _tsjs_scan(root, excludes, include_non_product=False):
1354
+ """Return dict with files, skipped, sites, gated, suppressed, or hint
1355
+ when the extra is missing. Never raises on a bad file.
1356
+
1357
+ Findings from non-product paths (_tsjs_non_product_class) are not
1358
+ dropped — they are counted per path class in res["suppressed"] so the
1359
+ report can say exactly what was held back. include_non_product restores
1360
+ the old behavior of reporting every site."""
1295
1361
  files = _tsjs_collect_files(root, excludes)
1296
1362
  res = {"files": files, "skipped": [], "sites": [], "gated": set(),
1297
- "missing_extra": False}
1363
+ "suppressed": {}, "missing_extra": False}
1298
1364
  if not files:
1299
1365
  return res
1300
1366
  parsers = _tsjs_parsers()
@@ -1312,6 +1378,14 @@ def _tsjs_scan(root, excludes):
1312
1378
  except Exception:
1313
1379
  res["skipped"].append(str(path))
1314
1380
  continue
1381
+ cls = None if include_non_product \
1382
+ else _tsjs_non_product_class(path, root)
1383
+ if cls is not None and sites:
1384
+ bucket = res["suppressed"].setdefault(
1385
+ cls, {"sites": 0, "files": {}})
1386
+ bucket["sites"] += len(sites)
1387
+ bucket["files"][str(path)] = len(sites)
1388
+ continue
1315
1389
  res["sites"].extend(sites)
1316
1390
  res["gated"].update((str(path),) + g for g in gated)
1317
1391
  return res
@@ -1372,13 +1446,32 @@ def print_scan_json(root, files, skipped, sites, gated_funcs, tsjs, ts_sites):
1372
1446
  "files_scanned": len(files) + len(tsjs.get("files", [])),
1373
1447
  "files_skipped": len(skipped) + len(tsjs.get("skipped", [])),
1374
1448
  "tsjs_hint": bool(tsjs.get("missing_extra")),
1449
+ "github_app": {
1450
+ "install_url": _GITHUB_APP_INSTALL_URL,
1451
+ "docs_url": _GITHUB_APP_DOCS_URL,
1452
+ "note": _GITHUB_APP_NOTE,
1453
+ },
1375
1454
  "findings": _scan_findings_json(root, sites, gated_funcs, tsjs,
1376
1455
  ts_sites),
1377
1456
  }
1457
+ ts_suppressed = tsjs.get("suppressed") or {}
1458
+ ts_sup_total = _tsjs_suppressed_total(ts_suppressed)
1459
+ if ts_sup_total:
1460
+ # Non-product findings held back by default: never dropped
1461
+ # silently — the report names every suppressed path.
1462
+ doc["tsjs_suppressed_non_product"] = {
1463
+ "sites": ts_sup_total,
1464
+ "by_class": {c: ts_suppressed[c]["sites"]
1465
+ for c in sorted(ts_suppressed)},
1466
+ "files": sorted(
1467
+ str(_pathlib.Path(f).relative_to(root))
1468
+ for c in ts_suppressed.values()
1469
+ for f in c["files"]),
1470
+ }
1378
1471
  print(json.dumps(doc, indent=2))
1379
1472
 
1380
1473
 
1381
- def _scan_repo(root, excludes):
1474
+ def _scan_repo(root, excludes, include_non_product=False):
1382
1475
  """Collect Python and TS/JS files and find write sites.
1383
1476
 
1384
1477
  Returns (files, skipped, sites, gated, tsjs). This is the read-only
@@ -1402,7 +1495,8 @@ def _scan_repo(root, excludes):
1402
1495
  sites.extend(v.sites)
1403
1496
  gated.update((str(path), n, ln) for (n, ln) in v.gated)
1404
1497
 
1405
- tsjs = _tsjs_scan(root, excludes or [])
1498
+ tsjs = _tsjs_scan(root, excludes or [],
1499
+ include_non_product=include_non_product)
1406
1500
  return files, skipped, sites, gated, tsjs
1407
1501
 
1408
1502
 
@@ -1516,7 +1610,9 @@ def scan_cmd(args):
1516
1610
  print("error: not a directory: %s" % args.path, file=sys.stderr)
1517
1611
  return 2
1518
1612
 
1519
- files, skipped, sites, gated, tsjs = _scan_repo(root, args.exclude or [])
1613
+ files, skipped, sites, gated, tsjs = _scan_repo(
1614
+ root, args.exclude or [],
1615
+ include_non_product=getattr(args, "include_non_product", False))
1520
1616
  analysis = _analyze_scan(root, files, skipped, sites, gated, tsjs)
1521
1617
  by_func = analysis["by_func"]
1522
1618
  ts_by_func = analysis["ts_by_func"]
@@ -1538,6 +1634,7 @@ def scan_cmd(args):
1538
1634
 
1539
1635
  if args.score:
1540
1636
  print_score_report(root, sites, gated_funcs)
1637
+ print(_GITHUB_APP_LINE)
1541
1638
  return 0
1542
1639
 
1543
1640
  print("writ scan: %s" % root)
@@ -1560,6 +1657,19 @@ def scan_cmd(args):
1560
1657
  print(" %s:%d [%s] %s %s(): %s" % (
1561
1658
  _pathlib.Path(s.file).relative_to(root), s.lineno, s.kind,
1562
1659
  rid, s.func or "<module>", s.snippet))
1660
+ suppressed = tsjs.get("suppressed") or {}
1661
+ sup_total = _tsjs_suppressed_total(suppressed)
1662
+ if sup_total:
1663
+ by_class = ", ".join("%s: %d" % (c, suppressed[c]["sites"])
1664
+ for c in sorted(suppressed))
1665
+ print(" ts/js non-product: %d site(s) suppressed (%s); "
1666
+ "re-run with --include-non-product to show them"
1667
+ % (sup_total, by_class))
1668
+ for cls in sorted(suppressed):
1669
+ for f in sorted(suppressed[cls]["files"]):
1670
+ print(" suppressed %s: %d site(s) [%s]" % (
1671
+ _pathlib.Path(f).relative_to(root),
1672
+ suppressed[cls]["files"][f], cls))
1563
1673
  if verbs:
1564
1674
  print(" verbs discovered: %d" % len(verbs))
1565
1675
  for vname in sorted(verbs):
@@ -1584,6 +1694,7 @@ def scan_cmd(args):
1584
1694
  "gate them by hand).")
1585
1695
  else:
1586
1696
  print("nothing to instrument.")
1697
+ print(_GITHUB_APP_LINE)
1587
1698
  return 0
1588
1699
 
1589
1700
  do_apply = args.apply
@@ -1605,7 +1716,10 @@ def scan_cmd(args):
1605
1716
  if not args.key:
1606
1717
  print("error: --push-policy needs --key", file=sys.stderr)
1607
1718
  return 2
1608
- return request("PUT", "/v1/policy", verbs, key=args.key)
1719
+ code = request("PUT", "/v1/policy", verbs, key=args.key)
1720
+ print(_GITHUB_APP_LINE)
1721
+ return code
1722
+ print(_GITHUB_APP_LINE)
1609
1723
  return 0
1610
1724
 
1611
1725
 
@@ -2138,6 +2252,13 @@ def main():
2138
2252
  help="Output format: human-readable text (default) or "
2139
2253
  "machine-readable JSON risk report (read-only; no "
2140
2254
  "policy file, no diffs)")
2255
+ scan.add_argument("--include-non-product", action="store_true",
2256
+ help="Include TS/JS findings from non-product paths that the "
2257
+ "scan suppresses by default: docs/, scripts/, sandbox/, "
2258
+ "examples/, benchmark/, demo/ directories and "
2259
+ "build-tooling files (gulpfile.js, webpack.config.*, "
2260
+ "rollup.config.*, vite.config.*, ...). Suppressed sites "
2261
+ "are always reported as a per-class count.")
2141
2262
  scan.add_argument("--push-policy", action="store_true",
2142
2263
  help="PUT the discovered policy to the gate (needs --key)")
2143
2264
  scan.add_argument("--key", default="",
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pywrit
3
- Version: 0.2.9
3
+ Version: 0.2.11
4
4
  Summary: Python client + CLI for Writ — the gate before the write
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://github.com/withwrit/pywrit
@@ -151,6 +151,18 @@ optional extra (tree-sitter based):
151
151
  Without the extra, the scanner prints a one-line hint and keeps going —
152
152
  Python scanning never needs it.
153
153
 
154
+ Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
155
+ benchmark/, demo/, and build-tooling files such as gulpfile.js or
156
+ webpack.config.*) are suppressed by default: the report counts them per
157
+ class and names every suppressed path instead of listing them as findings.
158
+ Pass `--include-non-product` to report them like any other finding.
159
+
160
+ Every scan report ends with a one-line pointer to the Writ GitHub App
161
+ (install: https://github.com/apps/writ-scanner, guide:
162
+ https://docs.withwrit.com/git-hub-app), which runs the scan on every push
163
+ and pull request; the JSON report (`--format json`) carries the same
164
+ pointer under `github_app`.
165
+
154
166
  TS/JS is **scan-only**: findings are listed with verbs for your policy file,
155
167
  but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
156
168
  Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
@@ -183,16 +195,17 @@ example workflow: [examples/github-action/writ-scan.yml](examples/github-action/
183
195
 
184
196
  ## GitHub App
185
197
 
186
- Install the [Writ GitHub App](https://docs.withwrit.com/git-hub-app) on selected
198
+ Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
187
199
  repositories: every push and pull request is scanned for ungated write-sites,
188
200
  with results as a check run on the PR and in the
189
201
  [portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
202
+ Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
190
203
 
191
204
  ## MCP server (`writ-mcp`)
192
205
 
193
206
  Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
194
207
  [Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
195
- built on the MCP Python SDK) that exposes the Writ gate as **8 MCP tools**:
208
+ built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
196
209
  the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
197
210
  `DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
198
211
  every decision.
@@ -212,13 +225,21 @@ pip install writ-mcp # then run `writ-mcp`
212
225
  | `writ_receipts` | Read the tenant's audit log |
213
226
  | `writ_policy` | Manage the verb policy |
214
227
  | `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
228
+ | `writ_github_installations` | List connected GitHub App installations |
229
+ | `writ_github_set_threshold` | Set the check-run fail threshold per install |
230
+ | `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
231
+ | `writ_manifests` | List repos with risk profiles or fetch one manifest |
232
+ | `writ_explain_receipt` | Explain a receipt in plain language |
233
+ | `writ_tenant_notify` | Get or update step-up notification settings |
234
+ | `writ_principals` | List the tenant's principals |
235
+ | `writ_verbs` | List the tenant's verb vocabulary |
236
+ | `writ_keys` | List API key metadata |
215
237
 
216
238
  The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
217
239
  free, no credit card. `writ_sandbox` works with no key at all.
218
240
 
219
241
  The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
220
- official MCP Registry as `io.github.withwrit/writ`, on
221
- [Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
242
+ official MCP Registry as `io.github.withwrit/writ` and listed on
222
243
  [Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
223
244
 
224
245
  ## Python client
@@ -337,6 +337,144 @@ class MissingExtraTest(unittest.TestCase):
337
337
  " orders.create\n" % root.resolve()), out)
338
338
 
339
339
 
340
+ class NonProductScanTest(unittest.TestCase):
341
+ """Axios-class noise: non-product paths are suppressed by default,
342
+ counted per class with paths named, and restored by the flag."""
343
+
344
+ WRITE = 'fetch("https://api.example.com/x", {method: "POST"})\n'
345
+
346
+ def _layout(self, root):
347
+ (root / "lib").mkdir(parents=True)
348
+ (root / "lib" / "core.js").write_text(self.WRITE)
349
+ for d in ("docs/scripts", "scripts", "sandbox", "examples"):
350
+ p = root / d
351
+ p.mkdir(parents=True)
352
+ (p / "tool.js").write_text(self.WRITE)
353
+ (root / "gulpfile.js").write_text(self.WRITE)
354
+ (root / "lib" / "benchmark-utils.ts").write_text(self.WRITE)
355
+
356
+ @unittest.skipUnless(HAVE_EXTRA, "polyglot extra not installed")
357
+ def test_suppressed_by_default_and_restored_by_flag(self):
358
+ with tempfile.TemporaryDirectory() as td:
359
+ root = pathlib.Path(td)
360
+ self._layout(root)
361
+ res = cli._tsjs_scan(root, [])
362
+ self.assertEqual(len(res["sites"]), 2) # lib/core.js + benchmark-utils.ts
363
+ total = cli._tsjs_suppressed_total(res["suppressed"])
364
+ self.assertEqual(total, 5)
365
+ res2 = cli._tsjs_scan(root, [], include_non_product=True)
366
+ self.assertEqual(len(res2["sites"]), 7)
367
+ self.assertEqual(res2["suppressed"], {})
368
+
369
+ def test_path_class_units(self):
370
+ root = pathlib.Path("/repo")
371
+ self.assertEqual(
372
+ cli._tsjs_non_product_class(root / "docs" / "a.js", root), "docs")
373
+ self.assertEqual(
374
+ cli._tsjs_non_product_class(root / "gulpfile.js", root),
375
+ "build-tooling")
376
+ self.assertIsNone(
377
+ cli._tsjs_non_product_class(root / "lib" / "benchmark-utils.ts",
378
+ root))
379
+ self.assertIsNone(
380
+ cli._tsjs_non_product_class(root / "lib" / "core.js", root))
381
+
382
+
383
+ class GitHubAppLineTest(unittest.TestCase):
384
+ """Regression: every scan report ends with the GitHub App line.
385
+
386
+ The local scan is invisible by design; the GitHub App is the visible
387
+ surface. The text report's last line points at it on every outcome
388
+ (findings found, zero findings, suppressed-only, --score), and the
389
+ JSON report carries the same pointer under `github_app`.
390
+ """
391
+
392
+ LINE = ("Run this scan on every push and pull request with the Writ "
393
+ "GitHub App: check runs on each change, history in the portal. "
394
+ "Install: https://github.com/apps/writ-scanner "
395
+ "(guide: https://docs.withwrit.com/git-hub-app)")
396
+
397
+ FINDING_REPO = {
398
+ "app.py": ('import requests\n\n\n'
399
+ 'def send(url):\n'
400
+ ' return requests.post(url, json={})\n'),
401
+ }
402
+ CLEAN_REPO = {
403
+ "app.py": ('def read():\n'
404
+ ' return open("/tmp/x").read()\n'),
405
+ }
406
+
407
+ def _repo(self, root, files):
408
+ for rel, src in files.items():
409
+ p = root / rel
410
+ p.parent.mkdir(parents=True, exist_ok=True)
411
+ p.write_text(src)
412
+
413
+ def _last_line(self, out):
414
+ lines = [ln for ln in out.splitlines() if ln.strip()]
415
+ return lines[-1] if lines else ""
416
+
417
+ def test_findings_found_run_ends_with_app_line(self):
418
+ with tempfile.TemporaryDirectory() as td:
419
+ root = pathlib.Path(td) / "repo"
420
+ root.mkdir()
421
+ self._repo(root, self.FINDING_REPO)
422
+ code, out = _run_scan(root)
423
+ self.assertEqual(code, 0)
424
+ self.assertIn("write sites: 1 in 1 function(s)", out)
425
+ self.assertEqual(self._last_line(out), self.LINE)
426
+
427
+ def test_zero_findings_run_ends_with_app_line(self):
428
+ with tempfile.TemporaryDirectory() as td:
429
+ root = pathlib.Path(td) / "repo"
430
+ root.mkdir()
431
+ self._repo(root, self.CLEAN_REPO)
432
+ code, out = _run_scan(root)
433
+ self.assertEqual(code, 0)
434
+ self.assertIn("write sites: 0 in 0 function(s)", out)
435
+ self.assertEqual(self._last_line(out), self.LINE)
436
+
437
+ def test_score_only_run_ends_with_app_line(self):
438
+ with tempfile.TemporaryDirectory() as td:
439
+ root = pathlib.Path(td) / "repo"
440
+ root.mkdir()
441
+ self._repo(root, self.FINDING_REPO)
442
+ code, out = _run_scan(root, score=True)
443
+ self.assertEqual(code, 0)
444
+ self.assertEqual(self._last_line(out), self.LINE)
445
+
446
+ def test_json_report_carries_github_app_field(self):
447
+ import json as j
448
+ with tempfile.TemporaryDirectory() as td:
449
+ root = pathlib.Path(td) / "repo"
450
+ root.mkdir()
451
+ self._repo(root, self.FINDING_REPO)
452
+ code, out = _run_scan(root, format="json")
453
+ self.assertEqual(code, 0, out)
454
+ app = j.loads(out)["github_app"]
455
+ self.assertEqual(app, {
456
+ "install_url": "https://github.com/apps/writ-scanner",
457
+ "docs_url": "https://docs.withwrit.com/git-hub-app",
458
+ "note": ("Run this scan on every push and pull request with "
459
+ "the Writ GitHub App: check runs on each change, "
460
+ "history in the portal."),
461
+ })
462
+
463
+ @unittest.skipUnless(HAVE_EXTRA, "polyglot extra not installed")
464
+ def test_suppressed_only_run_ends_with_app_line(self):
465
+ with tempfile.TemporaryDirectory() as td:
466
+ root = pathlib.Path(td) / "repo"
467
+ root.mkdir()
468
+ self._repo(root, {
469
+ "docs/scripts/tool.js": NonProductScanTest.WRITE * 3,
470
+ })
471
+ code, out = _run_scan(root)
472
+ self.assertEqual(code, 0)
473
+ self.assertIn("ts/js write sites: 0 in 0 function(s)", out)
474
+ self.assertIn("ts/js non-product: 3 site(s) suppressed", out)
475
+ self.assertEqual(self._last_line(out), self.LINE)
476
+
477
+
340
478
  class CliSyncTest(unittest.TestCase):
341
479
  def test_download_copy_is_byte_identical(self):
342
480
  web = HERE.parent.parent / "gate" / "web" / "writ"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes