traceforge-pcb 1.0.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 (219) hide show
  1. traceforge/__init__.py +3 -0
  2. traceforge/__main__.py +3 -0
  3. traceforge/acp_server.py +570 -0
  4. traceforge/agent.py +680 -0
  5. traceforge/altium/__init__.py +6 -0
  6. traceforge/altium/cfb.py +70 -0
  7. traceforge/altium/cli.py +60 -0
  8. traceforge/altium/model.py +163 -0
  9. traceforge/altium/outputs.py +24 -0
  10. traceforge/altium/pcb.py +301 -0
  11. traceforge/altium/project.py +328 -0
  12. traceforge/altium/schematic.py +400 -0
  13. traceforge/altium/tools.py +166 -0
  14. traceforge/approval.py +219 -0
  15. traceforge/attachments.py +346 -0
  16. traceforge/background.py +253 -0
  17. traceforge/bench/__init__.py +5 -0
  18. traceforge/bench/adapters.py +337 -0
  19. traceforge/bench/checks.py +410 -0
  20. traceforge/bench/cli.py +121 -0
  21. traceforge/bench/design.py +439 -0
  22. traceforge/bench/kicad.py +99 -0
  23. traceforge/bench/partscheck.py +159 -0
  24. traceforge/bench/review.py +100 -0
  25. traceforge/bench/runner.py +226 -0
  26. traceforge/bench/score.py +204 -0
  27. traceforge/bench/tasks.py +102 -0
  28. traceforge/chat.py +1185 -0
  29. traceforge/checks.py +328 -0
  30. traceforge/checks_sides.py +118 -0
  31. traceforge/cli.py +2224 -0
  32. traceforge/clipboard.py +107 -0
  33. traceforge/config.py +299 -0
  34. traceforge/context.py +276 -0
  35. traceforge/design/__init__.py +1 -0
  36. traceforge/design/constraints.py +397 -0
  37. traceforge/design/generate.py +1789 -0
  38. traceforge/design/outline.py +905 -0
  39. traceforge/design/schematic_layout.py +932 -0
  40. traceforge/design/schematic_lint.py +329 -0
  41. traceforge/design/schematic_route.py +207 -0
  42. traceforge/design/sheets.py +854 -0
  43. traceforge/design/sides.py +328 -0
  44. traceforge/design/spec.py +462 -0
  45. traceforge/design/specsheet.py +2351 -0
  46. traceforge/design/specsheet_render.py +183 -0
  47. traceforge/desktop/__init__.py +109 -0
  48. traceforge/desktop/keys.py +90 -0
  49. traceforge/desktop/project.py +443 -0
  50. traceforge/desktop/review.py +20 -0
  51. traceforge/desktop/server.py +1277 -0
  52. traceforge/desktop/static/app.css +223 -0
  53. traceforge/desktop/static/app.js +683 -0
  54. traceforge/desktop/static/highlight.js +77 -0
  55. traceforge/desktop/static/index.html +89 -0
  56. traceforge/desktop/static/md.js +90 -0
  57. traceforge/desktop/static/viewer.js +213 -0
  58. traceforge/desktop/symbols.py +212 -0
  59. traceforge/desktop/update.py +65 -0
  60. traceforge/diagnostics.py +67 -0
  61. traceforge/errata.py +219 -0
  62. traceforge/fab.py +108 -0
  63. traceforge/fab_layers.py +44 -0
  64. traceforge/features/__init__.py +6 -0
  65. traceforge/features/candidates.py +117 -0
  66. traceforge/features/cli.py +200 -0
  67. traceforge/features/package.py +433 -0
  68. traceforge/features/revdiff.py +224 -0
  69. traceforge/features/sarif.py +145 -0
  70. traceforge/features/viewer.py +265 -0
  71. traceforge/firmware/__init__.py +3 -0
  72. traceforge/firmware/cli.py +174 -0
  73. traceforge/firmware/drivers.py +372 -0
  74. traceforge/firmware/drivers_data.py +256 -0
  75. traceforge/firmware/mcus.py +177 -0
  76. traceforge/firmware/netlist.py +55 -0
  77. traceforge/firmware/pinmap.py +296 -0
  78. traceforge/firmware/scaffold.py +466 -0
  79. traceforge/firmware/toolchain.py +262 -0
  80. traceforge/hooks.py +237 -0
  81. traceforge/kicad/__init__.py +0 -0
  82. traceforge/kicad/cli.py +519 -0
  83. traceforge/kicad/diffpair.py +174 -0
  84. traceforge/kicad/edgegeom.py +191 -0
  85. traceforge/kicad/edit.py +405 -0
  86. traceforge/kicad/escape.py +1410 -0
  87. traceforge/kicad/formats.py +1073 -0
  88. traceforge/kicad/impedance.py +320 -0
  89. traceforge/kicad/install.py +75 -0
  90. traceforge/kicad/libraries.py +490 -0
  91. traceforge/kicad/models3d.py +942 -0
  92. traceforge/kicad/outputs.py +81 -0
  93. traceforge/kicad/pcb.py +787 -0
  94. traceforge/kicad/planes.py +1242 -0
  95. traceforge/kicad/project.py +136 -0
  96. traceforge/kicad/route.py +2698 -0
  97. traceforge/kicad/routegeom.py +164 -0
  98. traceforge/kicad/schematic.py +268 -0
  99. traceforge/kicad/sides.py +34 -0
  100. traceforge/kicad/stackup.py +424 -0
  101. traceforge/kicad_plugin/__init__.py +12 -0
  102. traceforge/kicad_plugin/actions.py +92 -0
  103. traceforge/kicad_plugin/cli.py +66 -0
  104. traceforge/kicad_plugin/client.py +86 -0
  105. traceforge/kicad_plugin/context.py +257 -0
  106. traceforge/kicad_plugin/discovery.py +81 -0
  107. traceforge/kicad_plugin/install.py +203 -0
  108. traceforge/kicad_plugin/overlay.py +60 -0
  109. traceforge/kicad_plugin/payload/action_plugin.py +65 -0
  110. traceforge/kicad_plugin/payload/ipc_main.py +42 -0
  111. traceforge/kicad_plugin/payload/plugin.json +90 -0
  112. traceforge/kicad_plugin/payload/requirements.txt +1 -0
  113. traceforge/kicad_plugin/views.py +202 -0
  114. traceforge/langchain.py +57 -0
  115. traceforge/local.py +580 -0
  116. traceforge/mcp_server.py +304 -0
  117. traceforge/models.py +310 -0
  118. traceforge/next_steps.py +110 -0
  119. traceforge/parts/__init__.py +52 -0
  120. traceforge/parts/alternates.py +488 -0
  121. traceforge/parts/bom.py +423 -0
  122. traceforge/parts/brief.py +705 -0
  123. traceforge/parts/catalog.py +297 -0
  124. traceforge/parts/cli_sourcing.py +156 -0
  125. traceforge/parts/data/duty_rates.yaml +37 -0
  126. traceforge/parts/data/hs_codes.yaml +103 -0
  127. traceforge/parts/datasheet.py +278 -0
  128. traceforge/parts/fx.py +100 -0
  129. traceforge/parts/model.py +185 -0
  130. traceforge/parts/net.py +187 -0
  131. traceforge/parts/offers.py +46 -0
  132. traceforge/parts/packages.py +397 -0
  133. traceforge/parts/pinout.py +714 -0
  134. traceforge/parts/providers/__init__.py +17 -0
  135. traceforge/parts/providers/base.py +100 -0
  136. traceforge/parts/providers/jlc.py +364 -0
  137. traceforge/parts/providers/keyed.py +661 -0
  138. traceforge/parts/report.py +508 -0
  139. traceforge/parts/supply.py +330 -0
  140. traceforge/parts/verify.py +455 -0
  141. traceforge/parts/web.py +575 -0
  142. traceforge/plans.py +70 -0
  143. traceforge/preferences.py +127 -0
  144. traceforge/prices.py +130 -0
  145. traceforge/prices.yaml +28 -0
  146. traceforge/prompts/__init__.py +54 -0
  147. traceforge/prompts/system.md +103 -0
  148. traceforge/providers.py +764 -0
  149. traceforge/remote/__init__.py +33 -0
  150. traceforge/remote/client.py +422 -0
  151. traceforge/remote/oidc.py +240 -0
  152. traceforge/remote/orgs.py +510 -0
  153. traceforge/remote/server.py +690 -0
  154. traceforge/remote/store.py +100 -0
  155. traceforge/review_changes.py +187 -0
  156. traceforge/routing.py +99 -0
  157. traceforge/runtime.py +435 -0
  158. traceforge/sessions.py +324 -0
  159. traceforge/sexpr.py +279 -0
  160. traceforge/sim/__init__.py +17 -0
  161. traceforge/sim/acmath.py +234 -0
  162. traceforge/sim/circuit.py +499 -0
  163. traceforge/sim/cli.py +162 -0
  164. traceforge/sim/engine.py +172 -0
  165. traceforge/sim/ltspice.py +175 -0
  166. traceforge/sim/measure.py +123 -0
  167. traceforge/sim/models.py +76 -0
  168. traceforge/sim/project.py +218 -0
  169. traceforge/sim/rawfile.py +123 -0
  170. traceforge/sim/results.py +298 -0
  171. traceforge/sim/tune.py +172 -0
  172. traceforge/skill_commands.py +165 -0
  173. traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
  174. traceforge/skill_library/compliance-review/SKILL.md +51 -0
  175. traceforge/skill_library/design-review/SKILL.md +47 -0
  176. traceforge/skill_library/errata-hunt/SKILL.md +30 -0
  177. traceforge/skill_library/firmware/SKILL.md +26 -0
  178. traceforge/skill_library/power-budget/SKILL.md +27 -0
  179. traceforge/skill_library/release-package/SKILL.md +29 -0
  180. traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
  181. traceforge/skill_library/thermal-review/SKILL.md +15 -0
  182. traceforge/skills.py +131 -0
  183. traceforge/thermal.py +557 -0
  184. traceforge/tools/__init__.py +48 -0
  185. traceforge/tools/agent_tools.py +213 -0
  186. traceforge/tools/base.py +303 -0
  187. traceforge/tools/batch.py +155 -0
  188. traceforge/tools/connections.py +245 -0
  189. traceforge/tools/files.py +777 -0
  190. traceforge/tools/firmware_tools.py +218 -0
  191. traceforge/tools/kicad_tools.py +1072 -0
  192. traceforge/tools/models3d_tools.py +141 -0
  193. traceforge/tools/parts_tools.py +473 -0
  194. traceforge/tools/processes.py +246 -0
  195. traceforge/tools/review_tools.py +178 -0
  196. traceforge/tools/sim_tools.py +230 -0
  197. traceforge/tui.py +620 -0
  198. traceforge/updates.py +124 -0
  199. traceforge/validate/__init__.py +77 -0
  200. traceforge/validate/builtins.py +1091 -0
  201. traceforge/validate/circuits.py +1240 -0
  202. traceforge/validate/config.py +410 -0
  203. traceforge/validate/default.yaml +113 -0
  204. traceforge/validate/design.py +191 -0
  205. traceforge/validate/explain.py +112 -0
  206. traceforge/validate/grounding.py +169 -0
  207. traceforge/validate/ipc2221.py +350 -0
  208. traceforge/validate/multilayer.py +805 -0
  209. traceforge/validate/netmodel.py +261 -0
  210. traceforge/validate/partcheck.py +472 -0
  211. traceforge/validate/report.py +280 -0
  212. traceforge/validate/review.py +322 -0
  213. traceforge/validate/runner.py +662 -0
  214. traceforge/workspace.py +171 -0
  215. traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
  216. traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
  217. traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
  218. traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
  219. traceforge_pcb-1.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,262 @@
1
+ """Find build tools, show install guidance, compile, report size and generate flash commands."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import re
8
+ import shutil
9
+ import subprocess
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+
13
+ from traceforge.firmware.scaffold import MANIFEST
14
+
15
+ TOOLS: dict[str, tuple[str, ...]] = {
16
+ "arduino-cli": ("arduino-cli",),
17
+ "platformio": ("pio", "platformio"),
18
+ "idf.py": ("idf.py",),
19
+ "avr-gcc": ("avr-gcc",),
20
+ "arm-none-eabi-gcc": ("arm-none-eabi-gcc",),
21
+ }
22
+
23
+ INSTALL_GUIDANCE: dict[str, str] = {
24
+ "arduino-cli": "Download from https://arduino.github.io/arduino-cli/ (or `brew install "
25
+ "arduino-cli`), then `arduino-cli core update-index && arduino-cli core install "
26
+ "esp32:esp32` (or ATTinyCore:avr with its board-manager URL).",
27
+ "platformio": "`pip install platformio` (or the PlatformIO IDE extension). Platforms and "
28
+ "toolchains download on the first `pio run`.",
29
+ "idf.py": "Install ESP-IDF: https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/"
30
+ "get-started/ then run `. ./export.sh` so idf.py is on PATH.",
31
+ "avr-gcc": "Debian/Ubuntu: `sudo apt install gcc-avr avr-libc avrdude`; macOS: `brew install "
32
+ "avr-gcc avrdude`.",
33
+ "arm-none-eabi-gcc": "Debian/Ubuntu: `sudo apt install gcc-arm-none-eabi`; macOS: `brew "
34
+ "install --cask gcc-arm-embedded`. Flashing: `st-flash` (stlink) or OpenOCD.",
35
+ }
36
+
37
+ _DIAG = re.compile(
38
+ r"^(?P<file>[^\s:][^:\n]*?):(?P<line>\d+):(?:(?P<col>\d+):)?\s*"
39
+ r"(?P<sev>fatal error|error|warning)\s*:\s*(?P<msg>.*)$",
40
+ re.M,
41
+ )
42
+ _SIZE_BERKELEY = re.compile(r"^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+[0-9a-f]+\s+\S+", re.M)
43
+ _SIZE_AVR = re.compile(r"^(Program|Data):\s+(\d+)\s+bytes(?:\s+\(([\d.]+)% Full\))?", re.M)
44
+ _SIZE_PIO = re.compile(
45
+ r"^(RAM|Flash):\s+\[.*?\]\s+([\d.]+)%\s+\(used (\d+) bytes from (\d+) bytes\)", re.M
46
+ )
47
+
48
+
49
+ @dataclass
50
+ class ToolInfo:
51
+ name: str
52
+ path: str | None
53
+ version: str = ""
54
+ guidance: str = ""
55
+
56
+ @property
57
+ def found(self) -> bool:
58
+ return self.path is not None
59
+
60
+
61
+ @dataclass
62
+ class Diagnostic:
63
+ file: str
64
+ line: int
65
+ column: int
66
+ severity: str
67
+ message: str
68
+
69
+
70
+ @dataclass
71
+ class BuildResult:
72
+ ok: bool
73
+ tool: str
74
+ command: list[str]
75
+ returncode: int
76
+ output: str
77
+ errors: list[Diagnostic] = field(default_factory=list)
78
+ warnings: list[Diagnostic] = field(default_factory=list)
79
+ size: dict[str, int | float] = field(default_factory=dict)
80
+ note: str = ""
81
+
82
+ def as_dict(self) -> dict:
83
+ return {
84
+ "ok": self.ok,
85
+ "tool": self.tool,
86
+ "command": self.command,
87
+ "returncode": self.returncode,
88
+ "errors": [d.__dict__ for d in self.errors],
89
+ "warnings": len(self.warnings),
90
+ "size": self.size,
91
+ "note": self.note,
92
+ }
93
+
94
+
95
+ def find_tool(name: str) -> str | None:
96
+ env = os.environ.get("TRACEFORGE_" + re.sub(r"\W", "_", name).upper())
97
+ if env:
98
+ return env
99
+ for exe in TOOLS[name]:
100
+ found = shutil.which(exe)
101
+ if found:
102
+ return found
103
+ if name == "platformio": # next to the running interpreter (virtualenv)
104
+ import sys
105
+
106
+ candidate = Path(sys.executable).parent / "pio"
107
+ if candidate.exists():
108
+ return str(candidate)
109
+ return None
110
+
111
+
112
+ def detect_tools() -> list[ToolInfo]:
113
+ infos = []
114
+ for name in TOOLS:
115
+ path = find_tool(name)
116
+ version = ""
117
+ if path:
118
+ flag = {"idf.py": "--version", "arduino-cli": "version"}.get(name, "--version")
119
+ try:
120
+ done = subprocess.run( # noqa: S603
121
+ [path, flag], capture_output=True, text=True, timeout=30, check=False
122
+ )
123
+ version = (
124
+ (done.stdout or done.stderr).strip().splitlines()[0]
125
+ if done.stdout or done.stderr
126
+ else ""
127
+ )
128
+ except (OSError, subprocess.TimeoutExpired):
129
+ version = "(version check failed)"
130
+ infos.append(ToolInfo(name, path, version, "" if path else INSTALL_GUIDANCE[name]))
131
+ return infos
132
+
133
+
134
+ def parse_diagnostics(text: str) -> tuple[list[Diagnostic], list[Diagnostic]]:
135
+ errors: list[Diagnostic] = []
136
+ warnings: list[Diagnostic] = []
137
+ for m in _DIAG.finditer(text):
138
+ diag = Diagnostic(
139
+ m["file"].strip(), int(m["line"]), int(m["col"] or 0), m["sev"], m["msg"].strip()
140
+ )
141
+ (warnings if m["sev"] == "warning" else errors).append(diag)
142
+ return errors, warnings
143
+
144
+
145
+ def parse_size(text: str) -> dict[str, int | float]:
146
+ """Parse avr-size -C, `size` (Berkeley) or PlatformIO's RAM/Flash summary."""
147
+ size: dict[str, int | float] = {}
148
+ for m in _SIZE_PIO.finditer(text):
149
+ key = m[1].lower()
150
+ size[f"{key}_used"], size[f"{key}_total"], size[f"{key}_percent"] = (
151
+ int(m[3]), int(m[4]), float(m[2]),
152
+ ) # fmt: skip
153
+ for m in _SIZE_AVR.finditer(text):
154
+ key = "flash" if m[1] == "Program" else "ram"
155
+ size.setdefault(f"{key}_used", int(m[2]))
156
+ if m[3]:
157
+ size.setdefault(f"{key}_percent", float(m[3]))
158
+ if not size:
159
+ m = _SIZE_BERKELEY.search(text)
160
+ if m:
161
+ text_b, data_b, bss_b = int(m[1]), int(m[2]), int(m[3])
162
+ size.update(flash_used=text_b + data_b, ram_used=data_b + bss_b)
163
+ return size
164
+
165
+
166
+ def project_kind(project: Path) -> str:
167
+ manifest = project / MANIFEST
168
+ if manifest.exists():
169
+ return json.loads(manifest.read_text("utf-8")).get("target", "")
170
+ if (project / "platformio.ini").exists():
171
+ return "platformio"
172
+ if (project / "main" / "CMakeLists.txt").exists():
173
+ return "esp-idf"
174
+ if (project / "Makefile").exists():
175
+ text = (project / "Makefile").read_text("utf-8", errors="replace")
176
+ return "avr" if "avr-gcc" in text else "stm32"
177
+ if list(project.glob("*/*.ino")) or list(project.glob("*.ino")):
178
+ return "arduino"
179
+ return ""
180
+
181
+
182
+ def _commands(project: Path, kind: str, action: str) -> tuple[str, list[str]]:
183
+ """(tool name, command) for compile | size | flash."""
184
+ if kind == "platformio":
185
+ pio = find_tool("platformio") or "pio"
186
+ cmd = {"compile": ["run"], "size": ["run", "-t", "size"], "flash": ["run", "-t", "upload"]}
187
+ return "platformio", [pio, *cmd[action], "-d", str(project)]
188
+ if kind == "arduino":
189
+ cli = find_tool("arduino-cli") or "arduino-cli"
190
+ manifest = json.loads((project / MANIFEST).read_text("utf-8"))
191
+ sketch = project / manifest["name"]
192
+ fqbn = manifest.get("fqbn") or "<fqbn>"
193
+ if action == "flash":
194
+ return "arduino-cli", [cli, "upload", "-p", "<port>", "--fqbn", fqbn, str(sketch)]
195
+ extra = ["--show-properties=false"] if action == "size" else []
196
+ return "arduino-cli", [cli, "compile", "--fqbn", fqbn, *extra, str(sketch)]
197
+ if kind == "esp-idf":
198
+ idf = find_tool("idf.py") or "idf.py"
199
+ sub = {"compile": ["build"], "size": ["size"], "flash": ["flash", "-p", "<port>"]}
200
+ return "idf.py", [idf, "-C", str(project), *sub[action]]
201
+ if kind in {"avr", "stm32"}:
202
+ tool = "avr-gcc" if kind == "avr" else "arm-none-eabi-gcc"
203
+ make = shutil.which("make") or "make"
204
+ sub = {"compile": [], "size": ["size"], "flash": ["flash"]}
205
+ return tool, [make, "-C", str(project), *sub[action]]
206
+ raise ValueError(f"cannot tell how to build {project} (no tf_firmware.json, platformio.ini...)")
207
+
208
+
209
+ def _run(tool: str, cmd: list[str], timeout: float, cwd: Path | None = None) -> BuildResult:
210
+ exe = cmd[0]
211
+ if not (os.path.isabs(exe) and os.path.exists(exe)) and shutil.which(exe) is None:
212
+ return BuildResult(
213
+ False, tool, cmd, 127, "", note=f"{tool} not found. {INSTALL_GUIDANCE.get(tool, '')}"
214
+ )
215
+ try:
216
+ done = subprocess.run( # noqa: S603 - fixed tool, list args
217
+ cmd, capture_output=True, text=True, timeout=timeout, check=False, cwd=cwd
218
+ )
219
+ except subprocess.TimeoutExpired:
220
+ return BuildResult(False, tool, cmd, 124, "", note=f"timed out after {timeout:.0f}s")
221
+ output = (done.stdout or "") + (done.stderr or "")
222
+ errors, warnings = parse_diagnostics(output)
223
+ result = BuildResult(done.returncode == 0, tool, cmd, done.returncode, output, errors, warnings)
224
+ result.size = parse_size(output)
225
+ return result
226
+
227
+
228
+ def compile_project(project: str | Path, timeout: float = 1800) -> BuildResult:
229
+ project = Path(project).resolve()
230
+ kind = project_kind(project)
231
+ tool, cmd = _commands(project, kind, "compile")
232
+ result = _run(tool, cmd, timeout)
233
+ if result.ok and not result.size:
234
+ size = size_project(project, timeout=120)
235
+ result.size = size.size
236
+ return result
237
+
238
+
239
+ def size_project(project: str | Path, timeout: float = 600) -> BuildResult:
240
+ project = Path(project).resolve()
241
+ kind = project_kind(project)
242
+ tool, cmd = _commands(project, kind, "size")
243
+ return _run(tool, cmd, timeout)
244
+
245
+
246
+ def flash_command(project: str | Path, port: str | None = None) -> list[str]:
247
+ """The command that would flash the board. Nothing is run."""
248
+ project = Path(project).resolve()
249
+ _tool, cmd = _commands(project, project_kind(project), "flash")
250
+ return [port if part == "<port>" and port else part for part in cmd]
251
+
252
+
253
+ def flash_project(project: str | Path, port: str | None = None, *, approved: bool = False,
254
+ timeout: float = 600) -> BuildResult: # fmt: skip
255
+ """Flash the board. Refuses unless the caller passes ``approved=True`` (user consent)."""
256
+ if not approved:
257
+ raise PermissionError("flashing hardware needs explicit approval (approved=True)")
258
+ cmd = flash_command(project, port)
259
+ if "<port>" in cmd or "<fqbn>" in cmd:
260
+ return BuildResult(False, "flash", cmd, 2, "", note="pass the serial port (--port)")
261
+ tool, _ = _commands(Path(project).resolve(), project_kind(Path(project).resolve()), "flash")
262
+ return _run(tool, cmd, timeout)
traceforge/hooks.py ADDED
@@ -0,0 +1,237 @@
1
+ """Hooks: shell commands that run around agent turns and after file edits.
2
+
3
+ Hooks come from two places:
4
+
5
+ * ``hooks:`` in the user config (``~/.config/traceforge/config.yaml``), which always run;
6
+ * ``.traceforge/hooks.yaml`` (or ``hooks.json``) in the project, which run only once the
7
+ user trusts the folder (see :mod:`traceforge.workspace`).
8
+
9
+ Format (YAML or JSON)::
10
+
11
+ before_turn: # before each prompt is sent to the model
12
+ - git status --short
13
+ after_edit: # after a tool changed files; output goes back to the agent
14
+ - {command: "python scripts/lint_bom.py", timeout: 30}
15
+ after_turn: # after the agent finished a turn; output is shown to the user
16
+ - kicad-cli sch erc --exit-code-violations board.kicad_sch
17
+
18
+ Each hook runs in the workspace with ``TRACEFORGE_EVENT``, ``TRACEFORGE_WORKSPACE``,
19
+ ``TRACEFORGE_THREAD``, ``TRACEFORGE_MODE`` and, for ``after_edit``, ``TRACEFORGE_PATHS``
20
+ (changed files, one per line) in its environment. A ``before_turn`` hook that exits
21
+ with status 2 stops the turn; its output says why. Output of ``before_turn`` hooks is
22
+ added to the prompt as context, and ``after_edit`` output is appended to the tool
23
+ result when the hook fails, so the agent can react to it.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import asyncio
29
+ import json
30
+ import os
31
+ from collections.abc import Iterable
32
+ from dataclasses import dataclass, field
33
+ from pathlib import Path
34
+ from typing import Any
35
+
36
+ import yaml
37
+
38
+ EVENTS = ("before_turn", "after_edit", "after_turn")
39
+ MAX_HOOKS_PER_EVENT = 16
40
+ MAX_OUTPUT = 8_000
41
+ DEFAULT_TIMEOUT = 60.0
42
+ BLOCK_EXIT_CODE = 2
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class Hook:
47
+ event: str
48
+ command: str
49
+ timeout: float = DEFAULT_TIMEOUT
50
+ source: str = "user" # user | project
51
+
52
+
53
+ @dataclass
54
+ class HookResult:
55
+ hook: Hook
56
+ exit_code: int | None
57
+ output: str
58
+ timed_out: bool = False
59
+
60
+ @property
61
+ def ok(self) -> bool:
62
+ return self.exit_code == 0 and not self.timed_out
63
+
64
+ @property
65
+ def blocks(self) -> bool:
66
+ return self.hook.event == "before_turn" and self.exit_code == BLOCK_EXIT_CODE
67
+
68
+ def summary(self) -> str:
69
+ status = "timed out" if self.timed_out else f"exit {self.exit_code}"
70
+ return f"[{self.hook.event} hook: {self.hook.command} ({status})]\n{self.output}".strip()
71
+
72
+
73
+ def _parse(raw: Any, source: str) -> list[Hook]:
74
+ hooks: list[Hook] = []
75
+ if not isinstance(raw, dict):
76
+ return hooks
77
+ for event in EVENTS:
78
+ entries = raw.get(event)
79
+ if isinstance(entries, (str, dict)):
80
+ entries = [entries]
81
+ if not isinstance(entries, list):
82
+ continue
83
+ for entry in entries[:MAX_HOOKS_PER_EVENT]:
84
+ if isinstance(entry, str):
85
+ command, timeout = entry, DEFAULT_TIMEOUT
86
+ elif isinstance(entry, dict) and isinstance(entry.get("command"), str):
87
+ command = entry["command"]
88
+ try:
89
+ timeout = float(entry.get("timeout") or DEFAULT_TIMEOUT)
90
+ except (TypeError, ValueError):
91
+ timeout = DEFAULT_TIMEOUT
92
+ else:
93
+ continue
94
+ command = command.strip()[:4_000]
95
+ if command:
96
+ hooks.append(Hook(event, command, max(1.0, min(timeout, 1800.0)), source))
97
+ return hooks
98
+
99
+
100
+ def _project_file(workspace: Path) -> Path | None:
101
+ for name in ("hooks.yaml", "hooks.yml", "hooks.json"):
102
+ path = workspace / ".traceforge" / name
103
+ if path.is_file():
104
+ return path
105
+ return None
106
+
107
+
108
+ def load_project_hooks(workspace: Path) -> list[Hook]:
109
+ path = _project_file(workspace)
110
+ if path is None:
111
+ return []
112
+ try:
113
+ text = path.read_text(encoding="utf-8")
114
+ raw = json.loads(text) if path.suffix == ".json" else yaml.safe_load(text)
115
+ except (OSError, ValueError, yaml.YAMLError):
116
+ return []
117
+ return _parse(raw, "project")
118
+
119
+
120
+ def project_hook_commands(workspace: Path) -> list[tuple[str, str]]:
121
+ return [(hook.event, hook.command) for hook in load_project_hooks(workspace)]
122
+
123
+
124
+ class HookRunner:
125
+ """Loads and runs the hooks that apply to one workspace."""
126
+
127
+ def __init__(
128
+ self,
129
+ workspace: Path,
130
+ user_hooks: dict[str, Any] | None = None,
131
+ *,
132
+ trusted: bool | None = None,
133
+ ):
134
+ from traceforge.workspace import is_trusted
135
+
136
+ self.workspace = Path(workspace).resolve()
137
+ self.trusted = is_trusted(self.workspace) if trusted is None else trusted
138
+ self.hooks = _parse(user_hooks or {}, "user")
139
+ self.skipped_project_hooks = 0
140
+ project = load_project_hooks(self.workspace)
141
+ if self.trusted:
142
+ self.hooks.extend(project)
143
+ else:
144
+ self.skipped_project_hooks = len(project)
145
+
146
+ def for_event(self, event: str) -> list[Hook]:
147
+ return [hook for hook in self.hooks if hook.event == event]
148
+
149
+ def describe(self) -> dict[str, list[str]]:
150
+ return {
151
+ event: [f"{hook.command} ({hook.source})" for hook in self.for_event(event)]
152
+ for event in EVENTS
153
+ }
154
+
155
+ async def run(
156
+ self, event: str, *, env: dict[str, str] | None = None, paths: Iterable[str] = ()
157
+ ) -> list[HookResult]:
158
+ results = []
159
+ extra = {
160
+ "TRACEFORGE_EVENT": event,
161
+ "TRACEFORGE_WORKSPACE": str(self.workspace),
162
+ "TRACEFORGE_PATHS": "\n".join(paths),
163
+ **(env or {}),
164
+ }
165
+ for hook in self.for_event(event):
166
+ results.append(await run_hook(hook, self.workspace, extra))
167
+ if results[-1].blocks:
168
+ break
169
+ return results
170
+
171
+
172
+ async def run_hook(hook: Hook, cwd: Path, env: dict[str, str]) -> HookResult:
173
+ try:
174
+ process = await asyncio.create_subprocess_shell(
175
+ hook.command,
176
+ cwd=str(cwd),
177
+ stdin=asyncio.subprocess.DEVNULL,
178
+ stdout=asyncio.subprocess.PIPE,
179
+ stderr=asyncio.subprocess.STDOUT,
180
+ env={**os.environ, **env},
181
+ start_new_session=os.name != "nt",
182
+ )
183
+ except OSError as exc:
184
+ return HookResult(hook, None, f"could not start: {exc}")
185
+ try:
186
+ output, _ = await asyncio.wait_for(process.communicate(), hook.timeout)
187
+ except TimeoutError:
188
+ from traceforge.background import kill_process_tree
189
+
190
+ await kill_process_tree(process)
191
+ return HookResult(hook, None, f"timed out after {hook.timeout:.0f}s", timed_out=True)
192
+ text = output.decode("utf-8", errors="replace").strip()
193
+ if len(text) > MAX_OUTPUT:
194
+ text = text[:MAX_OUTPUT] + "\n[hook output truncated]"
195
+ return HookResult(hook, process.returncode, text)
196
+
197
+
198
+ @dataclass
199
+ class HookedExecutor:
200
+ """Wraps a tool executor so ``after_edit`` hooks run after successful file changes."""
201
+
202
+ inner: Any
203
+ runner: HookRunner
204
+ env: dict[str, str] = field(default_factory=dict)
205
+
206
+ def definitions(self) -> list[dict[str, Any]]:
207
+ return self.inner.definitions()
208
+
209
+ def parallel_safe(self, name: str) -> bool:
210
+ return self.inner.parallel_safe(name)
211
+
212
+ def __getattr__(self, name: str) -> Any: # registry, context, policy ...
213
+ return getattr(self.inner, name)
214
+
215
+ async def execute(
216
+ self, name: str, arguments: dict[str, Any], tool_use_id: str
217
+ ) -> tuple[str, bool]:
218
+ text, is_error = await self.inner.execute(name, arguments, tool_use_id)
219
+ if is_error or not self.runner.for_event("after_edit") or not self._writes(name):
220
+ return text, is_error
221
+ path = arguments.get("path") or arguments.get("pcb") or arguments.get("schematic") or ""
222
+ results = await self.runner.run(
223
+ "after_edit", env=self.env, paths=[str(path)] if path else []
224
+ )
225
+ failed = [result.summary() for result in results if not result.ok]
226
+ if failed:
227
+ text = f"{text}\n\nA project after_edit hook reported a problem:\n" + "\n\n".join(
228
+ failed
229
+ )
230
+ return text, is_error
231
+
232
+ def _writes(self, name: str) -> bool:
233
+ from traceforge.tools.base import ToolKind
234
+
235
+ registry = getattr(self.inner, "registry", None)
236
+ tool = registry.get(name) if registry is not None else None
237
+ return tool is not None and tool.kind is ToolKind.WRITE
File without changes