@allansantos-dev/smart-tool 0.9.81 → 0.9.82

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 (50) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/NOTICE +1 -1
  3. package/README.md +41 -13
  4. package/agent_redirect.py +32 -0
  5. package/autostart.py +32 -25
  6. package/browser_bridge.py +320 -0
  7. package/browser_control.py +76 -39
  8. package/browser_service_client.py +1 -7
  9. package/client_hooks.py +41 -42
  10. package/code_graph.py +56 -15
  11. package/code_graph_java.mjs +21 -12
  12. package/code_health.py +14 -9
  13. package/codex_config.py +3 -0
  14. package/daemon_launcher.py +37 -5
  15. package/doc_candidates.py +63 -0
  16. package/doc_check.py +9 -3
  17. package/doc_extras.py +2 -3
  18. package/doc_insights.py +26 -2
  19. package/doc_prose.py +59 -11
  20. package/doc_registry.py +241 -0
  21. package/doc_scope.py +205 -39
  22. package/doc_turn.py +205 -0
  23. package/doc_validate.py +52 -9
  24. package/document_read.py +4 -2
  25. package/edit_shape.py +119 -0
  26. package/endpoint_sync.py +3 -21
  27. package/engine_home.py +95 -0
  28. package/hook_call.py +132 -0
  29. package/hook_decision.py +100 -6
  30. package/hooks/pretool_router.py +36 -30
  31. package/hooks/turn_end.py +40 -0
  32. package/index_views.py +5 -0
  33. package/install.py +24 -9
  34. package/lazy_mcp_proxy.py +10 -9
  35. package/local_embedder.py +8 -1
  36. package/locales/pt-BR.json +1 -2
  37. package/model_breaker.py +6 -5
  38. package/package.json +2 -2
  39. package/process_limits.py +17 -3
  40. package/project_identity.py +19 -1
  41. package/project_scan.py +98 -0
  42. package/scout_access.py +48 -0
  43. package/shell_reads.py +67 -0
  44. package/smart_tool_daemon.py +144 -39
  45. package/tray.py +31 -0
  46. package/venv_launch.py +67 -0
  47. package/version.py +1 -1
  48. package/web_adapters/node/engine-home.mjs +42 -0
  49. package/web_adapters/node/package-lock.json +13 -0
  50. package/web_adapters/node/package.json +1 -0
package/doc_validate.py CHANGED
@@ -122,7 +122,7 @@ def _function_line(model, function, number):
122
122
  """True when the project file's line holds the function's own name (its definition line)."""
123
123
  text = model.read(function["path"])
124
124
  lines = text.split("\n") if text else []
125
- name = function["name"].split(".")[-1].split("@")[0]
125
+ name = function["name"].split("(", 1)[0].split(".")[-1].split("@")[0]
126
126
  return 0 < number <= len(lines) and re.search(rf"\b{re.escape(name)}\b", lines[number - 1]) is not None
127
127
 
128
128
 
@@ -198,15 +198,55 @@ class _Validation:
198
198
  by_path = defaultdict(list)
199
199
  for symbol in self.model.graph.get("symbols") or []:
200
200
  by_path[symbol["path"]].append(symbol)
201
- current, stamps = doc_scope._current_code(self.root, {m["id"].rpartition("::")[0] for m in markers}, by_path)
201
+ current = doc_scope._current_code(self.root, {m["id"].rpartition("::")[0] for m in markers}, by_path)
202
202
  for marker in markers:
203
203
  now = current.get(marker["id"])
204
- check.verify(now == marker["signature"], f"{marker['file']}:{marker['line']}",
205
- f"`{marker['id']}` ({marker['file']}:{marker['line']}) has the signature of the code",
206
- f"`{marker['id']}` " + ("no longer exists in the code" if now is None else "changed its signature"))
207
- for item in doc_scope.stale_prose(self.pages, stamps):
204
+ parts = doc_scope.changed_parts(marker, now) if now else []
205
+ check.verify(now is not None and not parts, f"{marker['file']}:{marker['line']}",
206
+ f"`{marker['id']}` ({marker['file']}:{marker['line']}) has the signature, body and docstring of "
207
+ "the code", f"`{marker['id']}` " + ("no longer exists in the code" if now is None
208
+ else f"changed its {' and '.join(parts)} since generation"))
209
+ for item in doc_scope.stale_prose(self.pages, doc_scope.prose_stamps(self.model)):
208
210
  check.fail(f"{item['file']}:{item['line']}", f"the paragraph of `{item['id']}` was written for other code of "
209
- "the function: its body changed since")
211
+ "the feature: its entry point or a function its flow reaches changed since")
212
+
213
+ def chain(self):
214
+ check = self.check("chain", "Every feature a technical entry names lists that entry in its section of the "
215
+ "functional overview, and the other way round")
216
+ technical, functional = {"": set(), "possible ": set()}, {"": set(), "possible ": set()}
217
+ for rel, found in self.sections.items():
218
+ if not rel.startswith("technical/"):
219
+ continue
220
+ for anchor, section in found.items():
221
+ if anchor not in self.model.function_of:
222
+ continue
223
+ if not any(l.startswith("- Feature: ") for _n, l in section["body"]):
224
+ check.fail(f"{rel}:{section['line']}", f"`{anchor}` has no Feature line")
225
+ for number, line in section["body"]:
226
+ kind = "" if line.startswith("- Feature: ") else "possible " if line.startswith(
227
+ "- Possible feature: ") else None
228
+ for _label, target in _ANY_LINK.findall(line) if kind is not None else ():
229
+ path, _sep, feature = target.strip("<>").partition("#")
230
+ if _resolve(rel, path) == "functional.md":
231
+ technical[kind].add((html.unescape(feature), anchor, f"{rel}:{number}"))
232
+ for feature, section in self.sections.get("functional.md", {}).items():
233
+ if section["heading"] is None or feature.startswith("cli:"):
234
+ continue
235
+ for number, line in section["body"]:
236
+ kind = "possible " if line.startswith("- possible: ") else ""
237
+ for _label, target in _ANY_LINK.findall(line):
238
+ path, _sep, anchor = target.strip("<>").partition("#")
239
+ if _resolve("functional.md", path).startswith("technical/"):
240
+ functional[kind].add((feature, html.unescape(anchor), f"functional.md:{number}"))
241
+ for kind in technical:
242
+ written = {(f, a) for f, a, _w in functional[kind]}
243
+ named = {(f, a) for f, a, _w in technical[kind]}
244
+ for feature, anchor, where in sorted(technical[kind]):
245
+ check.verify((feature, anchor) in written, where, f"`{anchor}` and feature `{feature}` link each other",
246
+ f"`{anchor}` names {kind}feature `{feature}`, whose section does not list it")
247
+ for feature, anchor, where in sorted(functional[kind]):
248
+ check.verify((feature, anchor) in named, where, f"`{anchor}` and feature `{feature}` link each other",
249
+ f"{kind}feature `{feature}` lists `{anchor}`, whose technical entry does not name it")
210
250
 
211
251
  def links(self):
212
252
  check = self.check("links", "Every link resolves to an existing page, file and anchor")
@@ -274,7 +314,7 @@ class _Validation:
274
314
  for path, at in _PATH_LINE.findall(line):
275
315
  source = self.model.read(path)
276
316
  rows = source.split("\n") if source else []
277
- word = name.group(1).split(".")[-1]
317
+ word = name.group(1).split("(", 1)[0].split(".")[-1]
278
318
  held = 0 < int(at) <= len(rows) and word in rows[int(at) - 1]
279
319
  check.verify(held, f"{rel}:{number}", f"`{name.group(1)}` is at {path}:{at}",
280
320
  f"line {at} of `{path}` does not hold `{name.group(1)}`")
@@ -500,6 +540,9 @@ class _Validation:
500
540
  tests = self.model.tests_of(anchor) if anchor in self.model.function_of else []
501
541
  check.verify(count == len(tests), f"extras/features-tests.md:{number}", f"`{anchor}`: {count} test(s)",
502
542
  f"`{anchor}` shows {count} test(s), the graph reaches {len(tests)}")
543
+ if not rows and not self.entries and "No entry point found" in text:
544
+ check.ok("extras/features-tests.md says no entry point was found")
545
+ return
503
546
  bare = sum(1 for a in self.entries[:rows] if not self.model.tests_of(a))
504
547
  found = re.search(r"^(\d+) of (\d+) entry point", text, re.M)
505
548
  check.verify(found and [int(found.group(1)), int(found.group(2))] == [bare, rows], "extras/features-tests.md",
@@ -636,7 +679,7 @@ class _Validation:
636
679
  check.fail(f"extras/dependencies.md ({path})", f"`{key[0]}` is not declared in {path}")
637
680
 
638
681
  def run(self):
639
- for step in (self.markers, self.links, self.lines, self.relations, self.coverage, self.entry_points,
682
+ for step in (self.markers, self.chain, self.links, self.lines, self.relations, self.coverage, self.entry_points,
640
683
  self.features, self.command_lines, self.prose, self.entry_tests, self.labels, self.counts,
641
684
  self.glossary, self.navigation, self.versions):
642
685
  step()
package/document_read.py CHANGED
@@ -35,7 +35,8 @@ class NoTextLayer(document_text.DocumentError):
35
35
  """A PDF whose pages carry no text: `pages` is its page count."""
36
36
 
37
37
  def __init__(self, pages):
38
- super().__init__(f'PDF of {pages} pages has no text layer (scanned pages are not read; there is no OCR).')
38
+ super().__init__(f'PDF of {pages} pages has no text layer (scanned pages are not read; set `document_converter` '
39
+ f'to auto, kreuzberg or docling in config.json, with the engine installed, to read them).')
39
40
  self.pages = pages
40
41
 
41
42
 
@@ -214,7 +215,8 @@ def load(path):
214
215
  converted = extension not in KINDS and extension in document_converter.EXTENSIONS and document_converter.enabled()
215
216
  if extension not in KINDS and not converted:
216
217
  raise ValueError(f"read_document reads {', '.join(KINDS)} files; {extension or 'this file'} is not supported "
217
- '(use the normal Read for plain text; legacy .doc, .xls, .xlsb and .ppt and macro files other than .xlsm are not read)')
218
+ '(use the normal Read for plain text; images, legacy .doc, .xls and .ppt, OpenDocument and .rtf are read '
219
+ 'when `document_converter` is set to auto, kreuzberg or docling in config.json with the engine installed; .xlsb and macro files other than .xlsm are never read)')
218
220
  try:
219
221
  info = os.stat(path)
220
222
  except OSError as exc:
package/edit_shape.py ADDED
@@ -0,0 +1,119 @@
1
+ """Facts about the shape of the project that an edit touches, for the edit hook: the import cycle an added import closes, and
2
+ the hotspot or the usual change partner an edited file has.
3
+
4
+ Both read only what is already cached, so the hook never waits for them: the analysis of the code graph (`code_graph.cached_graph`)
5
+ and the history `doc_insights.history` keeps in memory (`doc_insights.cached_history`). Nothing cached means nothing said:
6
+ no analysis starts and no `git` process runs. Only Python imports are mapped to project files.
7
+ """
8
+ import ast
9
+ import collections
10
+
11
+ import code_graph
12
+ import code_health
13
+ import doc_insights
14
+ import index_profile
15
+ import index_scope
16
+
17
+ HOTSPOT_TOP = 10
18
+ HOTSPOT_MIN_COMMITS = 10
19
+ MAX_FINDINGS = 3
20
+
21
+
22
+ def _module_imports(rel, text, known):
23
+ """The project files a Python text imports at module level, with the line of the first import of each.
24
+
25
+ Parameters: rel (str) project-relative path of the file; text (str) its text; known (set of str) the project's files.
26
+ Returns: dict {file: line}; empty when the text does not parse. An import inside a function or a class is left out: it is
27
+ the usual way to break a cycle.
28
+ """
29
+ try:
30
+ tree = ast.parse(text)
31
+ except (SyntaxError, ValueError, RecursionError):
32
+ return {}
33
+ found = {}
34
+ for node in tree.body:
35
+ if isinstance(node, (ast.Import, ast.ImportFrom)):
36
+ for _alias, target, _base in code_graph.python_import_targets(rel, node, known):
37
+ if target and target != rel:
38
+ found.setdefault(target, node.lineno)
39
+ return found
40
+
41
+
42
+ def _chain(edges, start, goal):
43
+ """The shortest chain of files from `start` to `goal` over the import edges, or [] when `goal` cannot be reached."""
44
+ previous, queue = {start: None}, collections.deque([start])
45
+ while queue:
46
+ node = queue.popleft()
47
+ if node == goal:
48
+ chain = []
49
+ while node is not None:
50
+ chain.append(node)
51
+ node = previous[node]
52
+ return chain[::-1]
53
+ for following in sorted(edges.get(node, ())):
54
+ if following not in previous:
55
+ previous[following] = node
56
+ queue.append(following)
57
+ return []
58
+
59
+
60
+ def added_cycles(root, rel, before, after):
61
+ """The imports an edit adds to a Python file that close an import cycle in the cached code graph.
62
+
63
+ Parameters: root (str) project folder; rel (str) project-relative path of the edited file; before (str or None) text
64
+ before the edit; after (str) text after it.
65
+ Returns: list of {"line", "imports", "chain"} (at most MAX_FINDINGS): the added import, the project file it names and the
66
+ chain of files from that one back to `rel`. Empty when the graph is not cached, the file is not Python or no added
67
+ import has a way back.
68
+ """
69
+ if not rel.endswith(".py"):
70
+ return []
71
+ data = code_graph.cached_graph(root)
72
+ if data is None:
73
+ return []
74
+ known = {item["path"] for item in data.get("files") or []}
75
+ edges = code_graph.import_edges(data)
76
+ old = _module_imports(rel, before, known) if before else {}
77
+ found = []
78
+ for target, line in sorted(_module_imports(rel, after, known).items(), key=lambda item: item[1]):
79
+ chain = [] if target in old else _chain(edges, target, rel)
80
+ if chain:
81
+ found.append({"line": line, "imports": target, "chain": chain})
82
+ return found[:MAX_FINDINGS]
83
+
84
+
85
+ class _Indexed:
86
+ """The part of a documentation model that `doc_insights.coupling` reads, over a cached analysis."""
87
+
88
+ def __init__(self, data):
89
+ self.graph = data
90
+ self._files = [item["path"] for item in data.get("files") or []]
91
+
92
+ def files(self):
93
+ """Project-relative paths of the indexed files."""
94
+ return self._files
95
+
96
+
97
+ def history_findings(root, rels):
98
+ """The hotspots and the usual change partners among the files of an edit, from the cached history and graph.
99
+
100
+ Parameters: root (str) project folder; rels (list of str) project-relative paths of every file in the edit.
101
+ Returns: dict {"hotspots": [{"path", "commits", "rank"}], "coupled": [{"path", "with", "shared", "degree"}]}; a hotspot
102
+ is a code file in the first HOTSPOT_TOP of the commits-times-lines ranking with at least HOTSPOT_MIN_COMMITS commits;
103
+ a partner is a file outside the edit that `doc_insights.coupling` pairs with an edited one and that the edited one does
104
+ not import. Both lists are empty when the history or the graph is not cached.
105
+ """
106
+ nothing = {"hotspots": [], "coupled": []}
107
+ commits = doc_insights.cached_history(root)
108
+ data = code_graph.cached_graph(root) if commits else None
109
+ if data is None:
110
+ return nothing
111
+ lines = {item["path"]: item.get("lines") or 0 for item in data.get("files") or []}
112
+ profile = index_profile.current((index_scope.load_scope(root) or {}).get("profile"))
113
+ ranking = doc_insights.ranked_hotspots(commits, lambda path: path in lines and index_profile.kind(path, profile) == "code",
114
+ lines.get)
115
+ edited = set(rels)
116
+ hot = [{"path": path, "commits": count, "rank": rank} for rank, (path, count, _lines, _last)
117
+ in enumerate(ranking[:HOTSPOT_TOP], 1) if path in edited and count >= HOTSPOT_MIN_COMMITS]
118
+ coupled = code_health.partners(doc_insights.coupling(_Indexed(data), commits), edited)
119
+ return {"hotspots": hot, "coupled": coupled[:MAX_FINDINGS]}
package/endpoint_sync.py CHANGED
@@ -1,8 +1,8 @@
1
1
  """Aponta os clientes para a porta em que o daemon subiu, só quando ela muda.
2
2
 
3
3
  O daemon é dono da porta: depois do bind, reescreve apenas as URLs do smart-tool que os clientes guardam (MCP do
4
- Claude Code em ~/.claude.json, hook HTTP em ~/.claude/settings.json, MCP do Codex em ~/.codex/config.toml). Nada roda
5
- por prompt ou por sessão; o Claude Code relê hooks editados pelo file watcher, o MCP já conectado precisa de /mcp.
4
+ Claude Code em ~/.claude.json, MCP do Codex em ~/.codex/config.toml). Os hooks não guardam porta: leem o arquivo de
5
+ execução do daemon a cada chamada. Nada roda por prompt ou por sessão; o MCP já conectado precisa de /mcp.
6
6
  Cada arquivo é relido logo antes da gravação atômica: o Claude Code reescreve o ~/.claude.json com frequência.
7
7
  """
8
8
  import json
@@ -16,8 +16,6 @@ import codex_config
16
16
  import node_locator
17
17
 
18
18
  SERVER = "smart-tool"
19
- HOOK_PATH = "/hooks/pretool"
20
- POST_HOOK_PATH = "/hooks/posttool"
21
19
  _CODEX_URL_RE = re.compile(r'(\[mcp_servers\.smart-tool\][^\[]*?\burl\s*=\s*")http://127\.0\.0\.1:\d+(/mcp")')
22
20
 
23
21
 
@@ -60,21 +58,6 @@ def _claude_mcp(text, base):
60
58
  return json.dumps(data, indent=2, ensure_ascii=False)
61
59
 
62
60
 
63
- def _claude_hook(text, base):
64
- """settings.json text with our PreToolUse and PostToolUse hook URLs moved to base, or None when none changed."""
65
- data = json.loads(text)
66
- changed = False
67
- hooks = (data.get("hooks") or {}) if isinstance(data, dict) else {}
68
- for event, path in (("PreToolUse", HOOK_PATH), ("PostToolUse", POST_HOOK_PATH)):
69
- groups = (hooks.get(event) or []) if isinstance(hooks, dict) else []
70
- for group in groups if isinstance(groups, list) else []:
71
- for hook in (group.get("hooks") or []) if isinstance(group, dict) else []:
72
- if isinstance(hook, dict) and path in str(hook.get("url", "")):
73
- new = _rebase(hook["url"], base)
74
- changed, hook["url"] = changed or new != hook["url"], new
75
- return json.dumps(data, indent=2, ensure_ascii=False) if changed else None
76
-
77
-
78
61
  def _codex_mcp(text, base):
79
62
  port = urllib.parse.urlsplit(base).port
80
63
  new = _CODEX_URL_RE.sub(lambda m: f"{m.group(1)}http://127.0.0.1:{port}{m.group(2)}", text, count=1)
@@ -82,8 +65,7 @@ def _codex_mcp(text, base):
82
65
 
83
66
 
84
67
  def targets():
85
- return ((claude_json(), _claude_mcp), (os.path.join(claude_dir(), "settings.json"), _claude_hook),
86
- (os.path.join(codex_dir(), "config.toml"), _codex_mcp))
68
+ return ((claude_json(), _claude_mcp), (os.path.join(codex_dir(), "config.toml"), _codex_mcp))
87
69
 
88
70
 
89
71
  _CODEX_ANY_URL_RE = re.compile(r'\[mcp_servers\.smart-tool\][^\[]*?\burl\s*=\s*"([^"]+)"')
package/engine_home.py ADDED
@@ -0,0 +1,95 @@
1
+ """Brings the shared engines Smart Tool consumes (the embeddings home and the graph engine) up through the engine
2
+ registry: installs one that is missing, updates one that is outdated with the signed asset checked by the registry kit,
3
+ and reports why it could not when it cannot. Nothing here raises for a machine without Node, without network or without
4
+ the engine: that is a status the searches and the setup screen show.
5
+ """
6
+ import json
7
+ import os
8
+ import subprocess
9
+ import threading
10
+ import time
11
+
12
+ import node_locator
13
+
14
+ ENGINES = ("casa-de-embeddings", "motor-de-grafo")
15
+ SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "web_adapters", "node", "engine-home.mjs")
16
+ TIMEOUT_S = 900
17
+ CHECK_EVERY_S = 24 * 3600
18
+ RETRY_AFTER_S = 600
19
+
20
+ _lock = threading.Lock()
21
+ _last = {}
22
+
23
+
24
+ def forget():
25
+ """Drops what was learned about every engine (tests)."""
26
+ with _lock:
27
+ _last.clear()
28
+
29
+
30
+ def remember(name, status):
31
+ """Keeps `status` as the last answer for `name`, with the time it was kept."""
32
+ with _lock:
33
+ _last[name] = {**status, "at": time.time()}
34
+
35
+
36
+ def status(name):
37
+ """The last status of `name` (`ok`, `url`, `version`, `reason`, `at`), or None when none was asked yet."""
38
+ with _lock:
39
+ return dict(_last[name]) if name in _last else None
40
+
41
+
42
+ def ensure(name):
43
+ """Installs or updates `name`, starts it and waits for it to announce itself.
44
+
45
+ Parameters: name (one of ENGINES). Returns: `{"ok": True, "url", "version", ...}` or `{"ok": False, "reason"}`;
46
+ the result is also kept for `status`. Raises: ValueError for a name that is not an engine of this module."""
47
+ if name not in ENGINES:
48
+ raise ValueError(f"unknown engine {name!r}; Smart Tool consumes {' and '.join(reversed(ENGINES))}")
49
+ result = _run(name)
50
+ remember(name, result)
51
+ return result
52
+
53
+
54
+ def _run(name):
55
+ """One run of the Node script for `name`, as a status."""
56
+ node = node_locator.node()
57
+ if not node:
58
+ return {"ok": False, "reason": f"Node.js was not found, and {name} is installed and updated through it: "
59
+ "install Node.js or let Smart Tool download its own."}
60
+ try:
61
+ done = subprocess.run([node, SCRIPT, name], capture_output=True, text=True, timeout=TIMEOUT_S,
62
+ cwd=os.path.dirname(SCRIPT), env=node_locator.environment(prefer=node),
63
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
64
+ except subprocess.TimeoutExpired:
65
+ return {"ok": False, "reason": f"{name} did not finish installing or starting in {TIMEOUT_S}s."}
66
+ except OSError as exc:
67
+ return {"ok": False, "reason": f"{name} could not be started through Node ({exc})."}
68
+ if done.returncode:
69
+ tail = (done.stderr.strip().splitlines() or ["no error text"])[-1]
70
+ return {"ok": False, "reason": f"{name}: the install step failed (exit {done.returncode}): {tail[:300]}"}
71
+ try:
72
+ answer = json.loads(done.stdout)
73
+ if not isinstance(answer, dict) or type(answer.get("ok")) is not bool:
74
+ raise ValueError("not a status")
75
+ except ValueError:
76
+ return {"ok": False, "reason": f"{name}: the install step gave an answer that is not a status."}
77
+ return answer
78
+
79
+
80
+ def ensure_when_due(name):
81
+ """`ensure(name)` unless it ran recently: a working engine is looked at again after CHECK_EVERY_S, a failed one after
82
+ RETRY_AFTER_S, so a search never waits on an install that just failed. Returns: the status in force."""
83
+ last = status(name)
84
+ wait = CHECK_EVERY_S if last and last["ok"] else RETRY_AFTER_S
85
+ if last and time.time() - last["at"] < wait:
86
+ return last
87
+ return ensure(name)
88
+
89
+
90
+ def explain(name):
91
+ """A sentence for a warning: why `name` is not answering."""
92
+ last = status(name)
93
+ if last is None:
94
+ return f"{name} is being installed or started; it has not answered yet."
95
+ return f"{name} could not be brought up: {last.get('reason') or 'it did not answer'}."
package/hook_call.py ADDED
@@ -0,0 +1,132 @@
1
+ """Client side of every command hook that calls the Smart Tool daemon (PreToolUse, PostToolUse, SubagentStart, Stop).
2
+
3
+ The daemon address is read from its run file on every call, never from a port written into a settings file. A refused or
4
+ reset connection (a daemon restarting) is retried with backoff for `RESTART_WINDOW_S`, so a restart produces no message at
5
+ all; a daemon that stays unreachable fails open with one plain message, and the next calls stay silent until the daemon
6
+ answers again. Imports stay light (stdlib and the run-file reader) so a hook process starts fast.
7
+ """
8
+ import http.client
9
+ import json
10
+ import os
11
+ import socket
12
+ import time
13
+ import urllib.parse
14
+
15
+ import daemon_launcher
16
+ import paths
17
+
18
+ ORIGIN = "smart-tool"
19
+ RESTART_WINDOW_S = 10
20
+ DOWN_MEMORY_S = 60
21
+ CONNECT_TIMEOUT_S = 2
22
+ QUIET_CONNECT_TIMEOUT_S = 0.4
23
+ BACKOFF_S = (0.1, 0.2, 0.4, 0.8, 1.0)
24
+ ROUTE_TIMEOUT_S = {"pretool": 14, "posttool": 59, "subagent-start": 4, "stop": 110}
25
+ DOWN_MARKER = os.path.join(paths.DATA_DIR, "hook-down")
26
+ LOG_NAME = "daemon.log"
27
+ RETRYABLE = (ConnectionError, http.client.RemoteDisconnected, http.client.BadStatusLine)
28
+
29
+
30
+ class Unreachable(Exception):
31
+ """The daemon could not answer: `cause` is a plain-words reason."""
32
+
33
+ def __init__(self, cause):
34
+ """`cause`: the plain-words reason the daemon could not answer."""
35
+ super().__init__(cause)
36
+ self.cause = cause
37
+
38
+
39
+ def _post(url, route, query, raw, timeout, connect_timeout):
40
+ """The JSON the daemon answered to one POST of `raw` on /hooks/<route>, or raises ConnectionError, TimeoutError,
41
+ Unreachable (an HTTP error status). A connect that times out is a ConnectionError: a closed port on Windows may
42
+ take seconds to refuse, and that is a daemon not listening, not a slow one."""
43
+ parsed = urllib.parse.urlsplit(url)
44
+ connection = http.client.HTTPConnection(parsed.hostname, parsed.port, timeout=connect_timeout)
45
+ try:
46
+ try:
47
+ connection.connect()
48
+ except socket.timeout as exc:
49
+ raise ConnectionError(f"connect timed out: {exc}") from None
50
+ connection.sock.settimeout(timeout)
51
+ suffix = f"?{urllib.parse.urlencode(query)}" if query else ""
52
+ connection.request("POST", f"/hooks/{route}{suffix}", body=raw, headers={"Content-Type": "application/json"})
53
+ response = connection.getresponse()
54
+ body = response.read()
55
+ except socket.timeout as exc:
56
+ raise TimeoutError(str(exc)) from None
57
+ except OSError as exc:
58
+ if isinstance(exc, ConnectionError):
59
+ raise
60
+ raise ConnectionError(str(exc)) from None
61
+ finally:
62
+ connection.close()
63
+ if response.status != 200:
64
+ raise Unreachable(f"answered HTTP {response.status}")
65
+ return json.loads(body or b"{}")
66
+
67
+
68
+ def _down_recently():
69
+ try:
70
+ return time.time() - os.path.getmtime(DOWN_MARKER) < DOWN_MEMORY_S
71
+ except OSError:
72
+ return False
73
+
74
+
75
+ def _note_down():
76
+ os.makedirs(paths.DATA_DIR, exist_ok=True)
77
+ with open(DOWN_MARKER, "w", encoding="utf-8") as stream:
78
+ stream.write(str(time.time()))
79
+
80
+
81
+ def _clear_down():
82
+ try:
83
+ os.remove(DOWN_MARKER)
84
+ except OSError:
85
+ pass
86
+
87
+
88
+ def call(route, raw, client="", window_s=None, sleep=time.sleep):
89
+ """`(output, first_failure)` of one hook call. `output` is the daemon's JSON answer ({} when it stayed
90
+ unreachable); `first_failure` is the cause in plain words the first time the daemon is found unreachable, None when
91
+ it answered or when an earlier call already reported the same outage."""
92
+ query = {"client": client} if client else {}
93
+ window = RESTART_WINDOW_S if window_s is None else window_s
94
+ quiet = _down_recently()
95
+ deadline = time.monotonic() + (0 if quiet else window)
96
+ attempt = 0
97
+ cause = "the daemon is not running"
98
+ while True:
99
+ info = daemon_launcher.read_registry()
100
+ try:
101
+ if info:
102
+ output = _post(info["url"], route, query, raw, ROUTE_TIMEOUT_S[route],
103
+ QUIET_CONNECT_TIMEOUT_S if quiet else CONNECT_TIMEOUT_S)
104
+ _clear_down()
105
+ return (output if isinstance(output, dict) else {}), None
106
+ cause = "the daemon is not running (no run file)"
107
+ except TimeoutError:
108
+ return {}, _report(f"the daemon did not answer within {ROUTE_TIMEOUT_S[route]} s (timed out)", quiet)
109
+ except Unreachable as exc:
110
+ return {}, _report(f"the daemon {exc.cause}", quiet)
111
+ except RETRYABLE:
112
+ cause = "the daemon is restarting or not running"
113
+ if time.monotonic() >= deadline:
114
+ return {}, _report(cause, quiet)
115
+ sleep(BACKOFF_S[min(attempt, len(BACKOFF_S) - 1)])
116
+ attempt += 1
117
+
118
+
119
+ def _report(cause, quiet):
120
+ _note_down()
121
+ return None if quiet else cause
122
+
123
+
124
+ AFTER_DOWN = ("Nothing to do: it comes back by itself and further calls stay silent until it does; if it keeps "
125
+ "happening, see {log}.")
126
+
127
+
128
+ def message(event, cause, effect, action=None):
129
+ """The one visible line of a hook that let a call through: which hook, who owns it, why, what happened to the call
130
+ and what the user does."""
131
+ action = action or AFTER_DOWN.format(log=os.path.join(paths.DATA_DIR, LOG_NAME))
132
+ return f"[hook-origin={ORIGIN}] Smart Tool (project smart-tool) {event} hook: {cause}. {effect} {action}"