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.
- traceforge/__init__.py +3 -0
- traceforge/__main__.py +3 -0
- traceforge/acp_server.py +570 -0
- traceforge/agent.py +680 -0
- traceforge/altium/__init__.py +6 -0
- traceforge/altium/cfb.py +70 -0
- traceforge/altium/cli.py +60 -0
- traceforge/altium/model.py +163 -0
- traceforge/altium/outputs.py +24 -0
- traceforge/altium/pcb.py +301 -0
- traceforge/altium/project.py +328 -0
- traceforge/altium/schematic.py +400 -0
- traceforge/altium/tools.py +166 -0
- traceforge/approval.py +219 -0
- traceforge/attachments.py +346 -0
- traceforge/background.py +253 -0
- traceforge/bench/__init__.py +5 -0
- traceforge/bench/adapters.py +337 -0
- traceforge/bench/checks.py +410 -0
- traceforge/bench/cli.py +121 -0
- traceforge/bench/design.py +439 -0
- traceforge/bench/kicad.py +99 -0
- traceforge/bench/partscheck.py +159 -0
- traceforge/bench/review.py +100 -0
- traceforge/bench/runner.py +226 -0
- traceforge/bench/score.py +204 -0
- traceforge/bench/tasks.py +102 -0
- traceforge/chat.py +1185 -0
- traceforge/checks.py +328 -0
- traceforge/checks_sides.py +118 -0
- traceforge/cli.py +2224 -0
- traceforge/clipboard.py +107 -0
- traceforge/config.py +299 -0
- traceforge/context.py +276 -0
- traceforge/design/__init__.py +1 -0
- traceforge/design/constraints.py +397 -0
- traceforge/design/generate.py +1789 -0
- traceforge/design/outline.py +905 -0
- traceforge/design/schematic_layout.py +932 -0
- traceforge/design/schematic_lint.py +329 -0
- traceforge/design/schematic_route.py +207 -0
- traceforge/design/sheets.py +854 -0
- traceforge/design/sides.py +328 -0
- traceforge/design/spec.py +462 -0
- traceforge/design/specsheet.py +2351 -0
- traceforge/design/specsheet_render.py +183 -0
- traceforge/desktop/__init__.py +109 -0
- traceforge/desktop/keys.py +90 -0
- traceforge/desktop/project.py +443 -0
- traceforge/desktop/review.py +20 -0
- traceforge/desktop/server.py +1277 -0
- traceforge/desktop/static/app.css +223 -0
- traceforge/desktop/static/app.js +683 -0
- traceforge/desktop/static/highlight.js +77 -0
- traceforge/desktop/static/index.html +89 -0
- traceforge/desktop/static/md.js +90 -0
- traceforge/desktop/static/viewer.js +213 -0
- traceforge/desktop/symbols.py +212 -0
- traceforge/desktop/update.py +65 -0
- traceforge/diagnostics.py +67 -0
- traceforge/errata.py +219 -0
- traceforge/fab.py +108 -0
- traceforge/fab_layers.py +44 -0
- traceforge/features/__init__.py +6 -0
- traceforge/features/candidates.py +117 -0
- traceforge/features/cli.py +200 -0
- traceforge/features/package.py +433 -0
- traceforge/features/revdiff.py +224 -0
- traceforge/features/sarif.py +145 -0
- traceforge/features/viewer.py +265 -0
- traceforge/firmware/__init__.py +3 -0
- traceforge/firmware/cli.py +174 -0
- traceforge/firmware/drivers.py +372 -0
- traceforge/firmware/drivers_data.py +256 -0
- traceforge/firmware/mcus.py +177 -0
- traceforge/firmware/netlist.py +55 -0
- traceforge/firmware/pinmap.py +296 -0
- traceforge/firmware/scaffold.py +466 -0
- traceforge/firmware/toolchain.py +262 -0
- traceforge/hooks.py +237 -0
- traceforge/kicad/__init__.py +0 -0
- traceforge/kicad/cli.py +519 -0
- traceforge/kicad/diffpair.py +174 -0
- traceforge/kicad/edgegeom.py +191 -0
- traceforge/kicad/edit.py +405 -0
- traceforge/kicad/escape.py +1410 -0
- traceforge/kicad/formats.py +1073 -0
- traceforge/kicad/impedance.py +320 -0
- traceforge/kicad/install.py +75 -0
- traceforge/kicad/libraries.py +490 -0
- traceforge/kicad/models3d.py +942 -0
- traceforge/kicad/outputs.py +81 -0
- traceforge/kicad/pcb.py +787 -0
- traceforge/kicad/planes.py +1242 -0
- traceforge/kicad/project.py +136 -0
- traceforge/kicad/route.py +2698 -0
- traceforge/kicad/routegeom.py +164 -0
- traceforge/kicad/schematic.py +268 -0
- traceforge/kicad/sides.py +34 -0
- traceforge/kicad/stackup.py +424 -0
- traceforge/kicad_plugin/__init__.py +12 -0
- traceforge/kicad_plugin/actions.py +92 -0
- traceforge/kicad_plugin/cli.py +66 -0
- traceforge/kicad_plugin/client.py +86 -0
- traceforge/kicad_plugin/context.py +257 -0
- traceforge/kicad_plugin/discovery.py +81 -0
- traceforge/kicad_plugin/install.py +203 -0
- traceforge/kicad_plugin/overlay.py +60 -0
- traceforge/kicad_plugin/payload/action_plugin.py +65 -0
- traceforge/kicad_plugin/payload/ipc_main.py +42 -0
- traceforge/kicad_plugin/payload/plugin.json +90 -0
- traceforge/kicad_plugin/payload/requirements.txt +1 -0
- traceforge/kicad_plugin/views.py +202 -0
- traceforge/langchain.py +57 -0
- traceforge/local.py +580 -0
- traceforge/mcp_server.py +304 -0
- traceforge/models.py +310 -0
- traceforge/next_steps.py +110 -0
- traceforge/parts/__init__.py +52 -0
- traceforge/parts/alternates.py +488 -0
- traceforge/parts/bom.py +423 -0
- traceforge/parts/brief.py +705 -0
- traceforge/parts/catalog.py +297 -0
- traceforge/parts/cli_sourcing.py +156 -0
- traceforge/parts/data/duty_rates.yaml +37 -0
- traceforge/parts/data/hs_codes.yaml +103 -0
- traceforge/parts/datasheet.py +278 -0
- traceforge/parts/fx.py +100 -0
- traceforge/parts/model.py +185 -0
- traceforge/parts/net.py +187 -0
- traceforge/parts/offers.py +46 -0
- traceforge/parts/packages.py +397 -0
- traceforge/parts/pinout.py +714 -0
- traceforge/parts/providers/__init__.py +17 -0
- traceforge/parts/providers/base.py +100 -0
- traceforge/parts/providers/jlc.py +364 -0
- traceforge/parts/providers/keyed.py +661 -0
- traceforge/parts/report.py +508 -0
- traceforge/parts/supply.py +330 -0
- traceforge/parts/verify.py +455 -0
- traceforge/parts/web.py +575 -0
- traceforge/plans.py +70 -0
- traceforge/preferences.py +127 -0
- traceforge/prices.py +130 -0
- traceforge/prices.yaml +28 -0
- traceforge/prompts/__init__.py +54 -0
- traceforge/prompts/system.md +103 -0
- traceforge/providers.py +764 -0
- traceforge/remote/__init__.py +33 -0
- traceforge/remote/client.py +422 -0
- traceforge/remote/oidc.py +240 -0
- traceforge/remote/orgs.py +510 -0
- traceforge/remote/server.py +690 -0
- traceforge/remote/store.py +100 -0
- traceforge/review_changes.py +187 -0
- traceforge/routing.py +99 -0
- traceforge/runtime.py +435 -0
- traceforge/sessions.py +324 -0
- traceforge/sexpr.py +279 -0
- traceforge/sim/__init__.py +17 -0
- traceforge/sim/acmath.py +234 -0
- traceforge/sim/circuit.py +499 -0
- traceforge/sim/cli.py +162 -0
- traceforge/sim/engine.py +172 -0
- traceforge/sim/ltspice.py +175 -0
- traceforge/sim/measure.py +123 -0
- traceforge/sim/models.py +76 -0
- traceforge/sim/project.py +218 -0
- traceforge/sim/rawfile.py +123 -0
- traceforge/sim/results.py +298 -0
- traceforge/sim/tune.py +172 -0
- traceforge/skill_commands.py +165 -0
- traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
- traceforge/skill_library/compliance-review/SKILL.md +51 -0
- traceforge/skill_library/design-review/SKILL.md +47 -0
- traceforge/skill_library/errata-hunt/SKILL.md +30 -0
- traceforge/skill_library/firmware/SKILL.md +26 -0
- traceforge/skill_library/power-budget/SKILL.md +27 -0
- traceforge/skill_library/release-package/SKILL.md +29 -0
- traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
- traceforge/skill_library/thermal-review/SKILL.md +15 -0
- traceforge/skills.py +131 -0
- traceforge/thermal.py +557 -0
- traceforge/tools/__init__.py +48 -0
- traceforge/tools/agent_tools.py +213 -0
- traceforge/tools/base.py +303 -0
- traceforge/tools/batch.py +155 -0
- traceforge/tools/connections.py +245 -0
- traceforge/tools/files.py +777 -0
- traceforge/tools/firmware_tools.py +218 -0
- traceforge/tools/kicad_tools.py +1072 -0
- traceforge/tools/models3d_tools.py +141 -0
- traceforge/tools/parts_tools.py +473 -0
- traceforge/tools/processes.py +246 -0
- traceforge/tools/review_tools.py +178 -0
- traceforge/tools/sim_tools.py +230 -0
- traceforge/tui.py +620 -0
- traceforge/updates.py +124 -0
- traceforge/validate/__init__.py +77 -0
- traceforge/validate/builtins.py +1091 -0
- traceforge/validate/circuits.py +1240 -0
- traceforge/validate/config.py +410 -0
- traceforge/validate/default.yaml +113 -0
- traceforge/validate/design.py +191 -0
- traceforge/validate/explain.py +112 -0
- traceforge/validate/grounding.py +169 -0
- traceforge/validate/ipc2221.py +350 -0
- traceforge/validate/multilayer.py +805 -0
- traceforge/validate/netmodel.py +261 -0
- traceforge/validate/partcheck.py +472 -0
- traceforge/validate/report.py +280 -0
- traceforge/validate/review.py +322 -0
- traceforge/validate/runner.py +662 -0
- traceforge/workspace.py +171 -0
- traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
- traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
- traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
- traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
- 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
|