polyctl 0.7.0__py3-none-any.whl

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.
Files changed (99) hide show
  1. polyctl/__init__.py +7 -0
  2. polyctl/__main__.py +5 -0
  3. polyctl/a2a.py +226 -0
  4. polyctl/a2a_mcp.py +546 -0
  5. polyctl/acp.py +417 -0
  6. polyctl/adapters/README.md +101 -0
  7. polyctl/adapters/aider.json +32 -0
  8. polyctl/adapters/amazon-q.json +15 -0
  9. polyctl/adapters/amp.json +16 -0
  10. polyctl/adapters/antigravity.json +120 -0
  11. polyctl/adapters/claude-code.json +229 -0
  12. polyctl/adapters/cloud-generic.json +57 -0
  13. polyctl/adapters/codex.json +47 -0
  14. polyctl/adapters/command-code.json +45 -0
  15. polyctl/adapters/copilot.json +17 -0
  16. polyctl/adapters/cursor-agent.json +29 -0
  17. polyctl/adapters/deepseek.json +13 -0
  18. polyctl/adapters/droid.json +34 -0
  19. polyctl/adapters/gemini.json +30 -0
  20. polyctl/adapters/grok.json +22 -0
  21. polyctl/adapters/hermes.json +34 -0
  22. polyctl/adapters/kilocode.json +30 -0
  23. polyctl/adapters/kimi.json +23 -0
  24. polyctl/adapters/kiro.json +332 -0
  25. polyctl/adapters/ollama.json +29 -0
  26. polyctl/adapters/omp.json +34 -0
  27. polyctl/adapters/openai-api.json +68 -0
  28. polyctl/adapters/opencode.json +162 -0
  29. polyctl/adapters/pi.json +24 -0
  30. polyctl/adapters/pr-agent.json +54 -0
  31. polyctl/adapters/profiles.json +9 -0
  32. polyctl/adapters/qoder.json +163 -0
  33. polyctl/adapters/qwen.json +27 -0
  34. polyctl/adapters/reasonix.json +25 -0
  35. polyctl/adapters/rewriters/rtk.json +24 -0
  36. polyctl/adapters/trae.json +31 -0
  37. polyctl/adapters/vendors.json +42 -0
  38. polyctl/adapters/warp.json +88 -0
  39. polyctl/allowlist.py +1756 -0
  40. polyctl/api_review.py +920 -0
  41. polyctl/cli.py +835 -0
  42. polyctl/conformance_harness.py +9 -0
  43. polyctl/demo.py +503 -0
  44. polyctl/drivers.py +146 -0
  45. polyctl/email.py +160 -0
  46. polyctl/features.py +98 -0
  47. polyctl/journal.py +144 -0
  48. polyctl/language.py +945 -0
  49. polyctl/lib.py +1296 -0
  50. polyctl/matrix.py +660 -0
  51. polyctl/mcp.py +1362 -0
  52. polyctl/ntfy.py +169 -0
  53. polyctl/outbound.py +39 -0
  54. polyctl/parts/__init__.py +5 -0
  55. polyctl/parts/cli_authority.py +2615 -0
  56. polyctl/parts/cli_channels.py +1325 -0
  57. polyctl/parts/cli_checks.py +2293 -0
  58. polyctl/parts/cli_completion.py +686 -0
  59. polyctl/parts/cli_evidence.py +141 -0
  60. polyctl/parts/cli_gain.py +375 -0
  61. polyctl/parts/cli_harness.py +392 -0
  62. polyctl/parts/cli_hooks.py +1816 -0
  63. polyctl/parts/cli_install.py +638 -0
  64. polyctl/parts/cli_lanes.py +106 -0
  65. polyctl/parts/cli_maintenance.py +2536 -0
  66. polyctl/parts/cli_next.py +248 -0
  67. polyctl/parts/cli_pr.py +53 -0
  68. polyctl/parts/cli_project.py +2857 -0
  69. polyctl/parts/cli_review.py +5158 -0
  70. polyctl/parts/cli_status.py +898 -0
  71. polyctl/parts/lib_adapters.py +2933 -0
  72. polyctl/parts/lib_alarms.py +2106 -0
  73. polyctl/parts/lib_events.py +224 -0
  74. polyctl/parts/lib_evidence.py +412 -0
  75. polyctl/parts/lib_gates.py +2099 -0
  76. polyctl/parts/lib_lanes.py +829 -0
  77. polyctl/parts/lib_mail.py +1541 -0
  78. polyctl/parts/lib_next.py +652 -0
  79. polyctl/parts/lib_pr.py +331 -0
  80. polyctl/parts/lib_slices.py +3337 -0
  81. polyctl/parts/lib_state.py +2415 -0
  82. polyctl/parts/lib_transcript.py +4118 -0
  83. polyctl/pressure.py +325 -0
  84. polyctl/prices.json +47 -0
  85. polyctl/procs.py +1194 -0
  86. polyctl/settings.py +505 -0
  87. polyctl/skill/SKILL.md +365 -0
  88. polyctl/skillkit.py +503 -0
  89. polyctl/storage.py +2055 -0
  90. polyctl/telegram.py +327 -0
  91. polyctl/tiers.py +123 -0
  92. polyctl/verdicts.py +41 -0
  93. polyctl/watchdog.py +3887 -0
  94. polyctl/web.py +337 -0
  95. polyctl-0.7.0.dist-info/METADATA +235 -0
  96. polyctl-0.7.0.dist-info/RECORD +99 -0
  97. polyctl-0.7.0.dist-info/WHEEL +4 -0
  98. polyctl-0.7.0.dist-info/entry_points.txt +5 -0
  99. polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
polyctl/ntfy.py ADDED
@@ -0,0 +1,169 @@
1
+ """ntfy: an outbound phone channel beside Telegram.
2
+
3
+ For a person who would rather use ntfy (open source and self-hostable, with its
4
+ own phone app) than a Telegram bot. Alerts go out; nothing comes back in.
5
+
6
+ Each alert is one HTTP POST to the topic URL with Python's urllib, carrying the
7
+ same text Telegram gets, a `Priority` header mapped from the alarm level (`urgent`
8
+ for red, `high` for orange, `default` for the rest), and `Authorization: Bearer
9
+ <token>` when an access token was set. Settings live in `~/.polyctl/ntfy.json`, mode
10
+ 0600 from creation, never in a repository.
11
+ """
12
+ import json
13
+ import os
14
+ import urllib.error
15
+ import urllib.parse
16
+ import urllib.request
17
+
18
+ from . import lib as A, outbound, storage
19
+ UTF8 = "utf-8" # every text file polyctl writes or reads; Windows would otherwise use cp1252
20
+
21
+ CONF = os.path.join(A.HOME, ".polyctl", "ntfy.json")
22
+ LOOPBACK = ("127.0.0.1", "localhost", "::1")
23
+ # ntfy priority names (docs.ntfy.sh/publish/#message-priority): 5 is urgent/max, 4 is high, 3 is default.
24
+ PRIORITIES = {"red": "urgent", "orange": "high"}
25
+ # ntfy treats a body past 4,096 bytes as an attachment (docs.ntfy.sh/publish/#limitations) (NOTIFY-NTFY-2).
26
+ MAX_MESSAGE_BYTES = 4096
27
+
28
+
29
+ def priority(level=None):
30
+ """The ntfy `Priority` header value for an alarm level: red highest, orange high, the rest default."""
31
+ return PRIORITIES.get(level, "default")
32
+
33
+
34
+ def _parse_topic_url(url):
35
+ """Validate and split a topic URL; returns `(clean_url, hostname)` or raises `ValueError`."""
36
+ if not isinstance(url, str):
37
+ raise ValueError("a topic URL is required")
38
+ clean = url.strip()
39
+ if not clean or any(ch.isspace() or not ch.isprintable() for ch in clean):
40
+ raise ValueError("a topic URL cannot contain spaces or control characters")
41
+ try:
42
+ parts = urllib.parse.urlsplit(clean)
43
+ _ = parts.port
44
+ except ValueError as exc:
45
+ raise ValueError("invalid topic URL") from exc
46
+ if parts.username is not None or parts.password is not None or parts.query or parts.fragment:
47
+ raise ValueError("a topic URL takes only the server and topic path; pass a token with --token-env")
48
+ hostname = (parts.hostname or "").lower()
49
+ if not hostname or not parts.path.strip("/"):
50
+ raise ValueError("a topic URL needs a host and a topic path, such as https://ntfy.sh/<topic>")
51
+ if parts.scheme != "https" and not (parts.scheme == "http" and hostname in LOOPBACK):
52
+ raise ValueError("a topic URL must use https:// (or http:// on 127.0.0.1)")
53
+ return clean, hostname
54
+
55
+
56
+ def _valid_token(token):
57
+ return isinstance(token, str) and bool(token) and not any(ch.isspace() or not ch.isprintable() for ch in token)
58
+
59
+
60
+ def config():
61
+ """The ntfy channel's settings from `~/.polyctl/ntfy.json`, or None when it cannot send.
62
+
63
+ 0600, outside any repository.
64
+ """
65
+ if not os.path.exists(CONF):
66
+ return None
67
+ try:
68
+ with open(CONF, encoding=UTF8) as fh:
69
+ c = json.load(fh)
70
+ except (OSError, ValueError):
71
+ return None
72
+ if not isinstance(c, dict):
73
+ return None
74
+ try:
75
+ clean_url, _ = _parse_topic_url(c.get("topic_url"))
76
+ except ValueError:
77
+ return None
78
+ token = c.get("token")
79
+ if token is not None and not _valid_token(token):
80
+ return None
81
+ out = {"topic_url": clean_url}
82
+ if token:
83
+ out["token"] = token
84
+ return out
85
+
86
+
87
+ def host(c=None):
88
+ """The ntfy server's host, without the topic path or token."""
89
+ c = config() if c is None else c
90
+ if not c or not isinstance(c.get("topic_url"), str):
91
+ return None
92
+ try:
93
+ return (urllib.parse.urlsplit(c["topic_url"]).hostname or "").lower() or None
94
+ except ValueError:
95
+ return None
96
+
97
+
98
+ def save(topic_url, token=None):
99
+ """Write the topic URL and optional access token to `CONF`, mode 0600 from its creation."""
100
+ clean_url, _ = _parse_topic_url(topic_url)
101
+ data = {"topic_url": clean_url}
102
+ if token is not None:
103
+ clean_token = str(token).strip() if isinstance(token, str) else ""
104
+ if not _valid_token(clean_token):
105
+ raise ValueError("an access token cannot be empty or contain spaces or control characters")
106
+ data["token"] = clean_token
107
+ storage.replace_file_durably(CONF, (json.dumps(data, indent=2) + "\n").encode(UTF8), mode=0o600)
108
+ return config()
109
+
110
+
111
+ def _scrub(text, c):
112
+ """Remove the access token and the secret topic path from an error string before recording it."""
113
+ out = str(text)
114
+ if c.get("token"):
115
+ out = out.replace(c["token"], "<token>")
116
+ if c.get("topic_url"):
117
+ parts = urllib.parse.urlsplit(c["topic_url"])
118
+ masked = f"{parts.scheme}://{parts.hostname or '?'}/<topic>"
119
+ out = out.replace(c["topic_url"], masked)
120
+ topic = parts.path.strip("/")
121
+ if topic:
122
+ out = out.replace(topic, "<topic>")
123
+ return out
124
+
125
+
126
+ def _encode_message(text):
127
+ """Encode `text` as UTF-8 within ntfy's 4,096-byte message limit, cut at a character boundary (NOTIFY-NTFY-2)."""
128
+ raw = str(text).encode(UTF8)
129
+ if len(raw) <= MAX_MESSAGE_BYTES:
130
+ return raw
131
+ return raw[:MAX_MESSAGE_BYTES].decode(UTF8, errors="ignore").encode(UTF8)
132
+
133
+
134
+ def send(text, root=None, level=None):
135
+ """Publish one alert to the configured ntfy topic. Returns True on HTTP 2xx, False otherwise; never raises."""
136
+ c = config()
137
+ if not c:
138
+ return False
139
+ headers = {"Priority": priority(level)}
140
+ if c.get("token"):
141
+ headers["Authorization"] = f"Bearer {c['token']}"
142
+ req = urllib.request.Request(
143
+ c["topic_url"],
144
+ data=_encode_message(text),
145
+ headers=headers,
146
+ method="POST",
147
+ )
148
+ server_host = host(c)
149
+ open_url = (outbound.opener(urllib.request.ProxyHandler({}))
150
+ if server_host in LOOPBACK else outbound.OPENER).open
151
+ try:
152
+ with open_url(req, timeout=15) as resp:
153
+ status = getattr(resp, "status", None) or resp.getcode()
154
+ resp.read(200)
155
+ if 200 <= int(status) < 300:
156
+ return True
157
+ why = f"HTTP {status}"
158
+ except urllib.error.HTTPError as exc:
159
+ body = ""
160
+ try:
161
+ body = exc.read(200).decode(UTF8, errors="replace").strip()
162
+ except Exception:
163
+ body = ""
164
+ why = f"HTTP {exc.code}" + (f": {body}" if body else "")
165
+ except Exception as exc:
166
+ why = str(exc)
167
+ if root:
168
+ A.record_notice(root, "ntfy send failed", _scrub(why, c)[:200], sent=False, key="ntfy-error")
169
+ return False
polyctl/outbound.py ADDED
@@ -0,0 +1,39 @@
1
+ """A request carrying a credential in a header leaves by one opener, which follows no redirect (HUNT-LEADS-SEC).
2
+
3
+ urllib answers a 301, 302 or 303 by asking the place the answer names, with every header of the request but its
4
+ content headers - an `Authorization` among them - and to another host as readily as to the same one: measured on
5
+ 2026-10-12, a POST carrying `Authorization: Bearer` to a listener on 127.0.0.1 that answered 302 reached a second
6
+ listener as a GET with the same header. The A2A bridge carried an agent's header that way (A2A-HARDEN), the account
7
+ lookup carried the OIDC access token a harness's CLI holds (HUNT-LEADS-SEC), and the API reviewer held its key
8
+ back with a copy of the handler below. One handler now, for all three.
9
+
10
+ A redirect is an answer here: urllib raises it as the HTTPError of its status, and the caller says that status -
11
+ and, where it prints for a person, to write the URL the endpoint moved to where the endpoint is named. A credential
12
+ written into a URL's path - Telegram's bot token, formsubmit's alias - is not carried by a redirect: urllib asks the
13
+ place the answer names, and the token was in the place it left.
14
+ """
15
+ import urllib.request
16
+
17
+
18
+ class NoRedirect(urllib.request.HTTPRedirectHandler):
19
+ """Follow no redirect: an answer that sends the request elsewhere is an error, said as its HTTP status."""
20
+
21
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
22
+ return None
23
+
24
+
25
+ def opener(*handlers):
26
+ """An opener of urllib's own handlers and `handlers`, following no redirect.
27
+
28
+ `build_opener` puts NoRedirect in place of its redirect handler, as it puts a ProxyHandler given here in place of
29
+ the one that reads the environment's proxies.
30
+ """
31
+ return urllib.request.build_opener(NoRedirect, *handlers)
32
+
33
+
34
+ OPENER = opener()
35
+
36
+
37
+ def is_redirect(code):
38
+ """Whether an HTTP status is one of the 3xx answers this opener does not follow."""
39
+ return isinstance(code, int) and 300 <= code < 400
@@ -0,0 +1,5 @@
1
+ """Parts of polyctl's large modules, moved out whole and run in their module's namespace (#44).
2
+
3
+ A part is not importable on its own: it is loaded by `_part(name, globals())` in the
4
+ module it came from, so its names stay that module's. See docs/slices.md.
5
+ """