diff --git a/.gitignore b/.gitignore
index 3c7ad902a..f4a66720c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,7 @@
*.snap
.flatpak-builder
+__pycache__/
+*.pyc
# Qt build output
*.user
# doxygen Doxyfile output
diff --git a/misc/qet-mcp/README.md b/misc/qet-mcp/README.md
index d995a4411..f4a869f33 100644
--- a/misc/qet-mcp/README.md
+++ b/misc/qet-mcp/README.md
@@ -30,14 +30,20 @@ here read the model.
| `qet_project_info` | title, format version, folios, element and conductor counts |
| `qet_elements` | placed elements: uuid, type, position, label, information bag |
| `qet_conductors` | conductors and their documentation fields; filter by attribute |
-| `qet_diff` | **what an edit actually changed** — moves with deltas, adds, removes, relabels, conductor field changes |
+| `qet_diff` | **what an edit actually changed** — element moves, adds, removes, relabels; conductor changes; and folio fields, texts, shapes, images, symbol text fields and terminal strips |
| `qet_scan` | sweep a directory of projects, counting nodes carrying an attribute |
| `qet_element_info` | a `.elmt`: translated names, terminals, info fields, part counts |
| `qet_export` | run a headless export (pdf, png, svg, bom, cables, wires, wiring, nets, links, info) |
+| `qet_edit` | **change a project** — place, move, rotate, label, wire, number, cross-reference, add text, shapes and images, restyle a symbol's text fields, delete; then diff the result |
+| `qet_element_build` | **author a `.elmt`** — draw a new symbol, with terminals to wire it by |
+| `qet_project_new` | **start from nothing** — an empty project with a title and folios |
+| `qet_element_search` | **find a symbol** in a collection by name (any language), type or terminal count |
+| `qet_check` | **design-rule checks** — duplicate labels, unlabelled masters, unnumbered conductors, empty folios |
+| `qet_query` | **ask the project database** — read-only SQL over the views and tables |
-Only `qet_export` launches QElectroTech. Everything else parses the file
-directly, which is faster, needs no display, and cannot be confused by a
-dialog.
+`qet_export` and `qet_edit` launch QElectroTech. Everything else parses the
+file directly, which is faster, needs no display, and cannot be confused by
+a dialog.
## Running it
@@ -56,12 +62,80 @@ Register it with an MCP client, for example:
"mcpServers": {
"qet": {
"command": "python3",
- "args": ["/path/to/qelectrotech/misc/qet-mcp/qet_mcp.py"]
+ "args": ["/path/to/qelectrotech/misc/qet-mcp/qet_mcp.py"],
+ "env": {
+ "QET_MCP_WORKSPACE": "/home/you/drawings",
+ "QET_ENABLE_SCRIPTING": "1"
+ }
}
}
}
```
+## Five tools need scripting switched on
+
+A QElectroTech with JavaScript scripting switched off refuses `--run`, and
+off is the default from
+[#984](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/984)
+onwards. Five tools here drive it that way and stop working until it is
+turned on:
+
+| | |
+|---|---|
+| need `QET_ENABLE_SCRIPTING=1` | `qet_query`, `qet_continuity`, `qet_check`, `qet_project_new`, `qet_edit` |
+| unaffected | everything else — they read the `.qet` directly, or, in `qet_export`'s case, use a plain CLI flag |
+
+The variable goes in the environment this server is started in, which for an
+MCP client is the `env` block above; the server passes its environment
+straight through to QElectroTech. It does not set the variable itself, on
+purpose — a switch a program turns on for itself is not a switch. Whoever
+configured this server and pointed it at a QElectroTech binary made that
+choice, and their interactive QElectroTech keeps whatever its own setting
+says.
+
+Without it, those five come back `"ok": false` with a `hint` naming the
+variable. Older builds, from before the setting existed, need nothing.
+
+## What the server is allowed to touch
+
+Every path in a tool call is chosen by the model, so without a policy this
+server would be a read/write primitive for anything the operating system
+lets the process reach: read any project on the disk, export one somewhere
+else, overwrite an unrelated file, embed an arbitrary local image or PDF.
+
+So **data paths are confined to a workspace**:
+
+| | |
+|---|---|
+| `QET_MCP_WORKSPACE` | the directories tool calls may read and write, separated by `:` (`;` on Windows) |
+| unset | the directory the server was started in |
+| `QET_MCP_ALLOW_ANY_PATH=1` | turns the check off entirely |
+
+Set the workspace to the folder your drawings live in. A path outside it is
+refused with an error naming what was allowed; symlinks are resolved first,
+so a link planted inside the workspace is judged by where it points.
+
+Two arguments are deliberately **not** confined: `binary` (the
+`qelectrotech` executable) and `elements_dir` (the element collection).
+Those are configuration, chosen once by whoever runs the server, and both
+normally live in `/usr` or a build tree — outside any sensible workspace.
+Confining them would reject the ordinary case while stopping nothing.
+
+`QET_MCP_ALLOW_ANY_PATH=1` is equivalent to granting the client local
+filesystem access with this process's privileges. It exists so that is a
+deliberate choice rather than the default.
+
+**Nothing is overwritten unasked.** `qet_export`, `qet_edit`,
+`qet_project_new` and `qet_element_build` refuse an `output` that already
+exists unless the call passes `"overwrite": true`. Replacing a file is the
+one step this server cannot undo, so it is the one step it will not take on
+its own.
+
+The confinement is applied where tool arguments enter the server, not inside
+each tool. Importing `qet_mcp` and calling `tool_export()` from your own
+Python is not confined and is not meant to be — that is your code calling a
+library, and you already chose the paths.
+
## Worked examples
**What did that edit change?**
@@ -79,6 +153,74 @@ Register it with an MCP client, for example:
Four elements moved by one uniform delta; nothing was relabelled. That is
the answer a screenshot gave wrongly.
+**Draw something, and check it landed**
+
+```json
+{"name": "qet_edit", "arguments": {
+ "binary": "/path/to/qelectrotech",
+ "project": "in.qet", "output": "out.qet",
+ "elements_dir": "/path/to/qelectrotech/elements",
+ "operations": [
+ {"op": "add_folio", "id": "f"},
+ {"op": "set_folio_title", "folio": "$f", "title": "Starter"},
+ {"op": "add_element", "id": "k1", "folio": "$f", "path": "common://.../coil.elmt", "x": 100, "y": 100},
+ {"op": "add_element", "id": "k2", "folio": "$f", "path": "common://.../coil.elmt", "x": 320, "y": 100},
+ {"op": "add_conductor", "folio": "$f", "from": "$k1", "from_terminal": 0, "to": "$k2", "to_terminal": 0},
+ {"op": "set_conductor", "folio": "$f", "element": "$k1", "terminal": 0, "property": "num", "value": "W7"},
+ {"op": "set_label", "folio": "$f", "element": "$k1", "label": "KM1"}
+ ]}}
+```
+
+An op that creates something takes an `"id"`; later ops name it as `"$id"`.
+Terminals are addressed by index — top to bottom, then left to right, **not**
+the order the `.elmt` lists them. `qet_element_info` and `qet_element_search`
+both report that index order. The answer carries a per-operation result
+*and* a `qet_diff`, because "addConductor → true" says the call was
+accepted, not that the file came out right:
+
+```json
+"diff": {"elements": {"before": 11, "after": 13, "added": ["{0aa3…}", "{6f63…}"]},
+ "conductors": {"before": 47, "after": 48, "added": ["4:{0aa3…}/{2904…}--{6f63…}/{2904…}"],
+ "removed": []}}
+```
+
+**Draw a symbol that does not exist yet**
+
+```json
+{"name": "qet_element_build", "arguments": {
+ "output": "/path/to/collection/99_custom/my_resistor.elmt",
+ "names": {"en": "Test resistor", "fr": "Résistance de test"},
+ "parts": [
+ {"type": "rect", "x": -10, "y": -20, "width": 20, "height": 40},
+ {"type": "line", "x1": 0, "y1": -30, "x2": 0, "y2": -20},
+ {"type": "line", "x1": 0, "y1": 20, "x2": 0, "y2": 30},
+ {"type": "text", "x": 14, "y": -4, "text": "R"}
+ ],
+ "terminals": [{"x": 0, "y": -30, "orientation": "n", "name": "1"},
+ {"x": 0, "y": 30, "orientation": "s", "name": "2"}]}}
+```
+
+Then place it with `qet_edit` like any catalogue element. Unlike a
+project, a `.elmt` is not rewritten by QElectroTech on a round trip, so
+generating one here is safe in a way that generating a `.qet` would not
+be — there is no `toXml()` waiting to drop what this writer did not know
+to emit.
+
+**Ask a question the XML cannot answer**
+
+```json
+{"name": "qet_query", "arguments": {
+ "binary": "/path/to/qelectrotech", "project": "industrial.qet",
+ "sql": "SELECT label, COUNT(*) AS n FROM element_nomenclature_view WHERE label <> '' GROUP BY label HAVING n > 1 ORDER BY n DESC"}}
+```
+
+```json
+"rows": [{"label": "V6", "n": 7}, {"label": "V5", "n": 6}, {"label": "V4", "n": 6}]
+```
+
+Duplicate element labels in a shipped example — a design-rule question,
+answered by the database that already knew it.
+
**How much of a corpus uses a field?**
```json
@@ -92,14 +234,43 @@ the answer a screenshot gave wrongly.
Across the shipped examples: 3190 conductors, not one with a cable value.
+## Testing
+
+```bash
+python3 test_qet_mcp.py # unit + protocol, no QElectroTech needed
+QET_BINARY=/path/to/qelectrotech \
+QET_ELEMENTS=/path/to/qelectrotech/elements \
+QET_EXAMPLES=/path/to/qelectrotech/examples \
+QET_ENABLE_SCRIPTING=1 \
+ python3 test_qet_mcp.py # everything
+```
+
+`QET_ENABLE_SCRIPTING=1` matters from #984 onwards: without it the
+integration tests that drive QElectroTech through a script all fail, and
+they fail as "the edit did nothing" rather than as "scripting is off", which
+reads like a regression in the thing under test.
+
+176 tests in three layers: unit (validation, script generation, the terminal
+order rule, the diff, the part schema), the real stdio transport, and
+integration against a built QElectroTech. Several exist because the
+behaviour they pin was once wrong and looked right, and say so in their
+docstrings. To check the suite itself rather than trust it, each of those
+bugs was reintroduced in turn and the suite confirmed to fail: ten in the
+Python, plus the hang guard on `addConductor` and the database refresh in
+`ConductorCreator` in the C++.
+
## Notes and limits
-- **The project database is not reachable from outside the application.**
- `projectDataBase::newQuery()` and `isReadOnlySelect()` are C++-internal
- and the JavaScript scripting API exposes no SQL binding, so structural
- queries here are done over the XML. A `--query` CLI verb, or a scripting
- binding, would let this server expose the guarded read-only SQL surface
- instead, and would be a better foundation.
+- **The project database is reachable now, through `qet_query`.** It was
+ not when this server was written, which is why every other structural
+ tool here re-derives its answer from the XML. Prefer the views —
+ `element_nomenclature_view`, `project_summary_view`, `wiring_list_view`
+ — which exist to be queried; the underlying tables are how the cache is
+ arranged today and a column may move. Call `qet_query` with no `sql` to
+ list both. Only `SELECT` and `WITH` are accepted, which is the rule
+ QElectroTech applies to its own custom-query box, not one invented here.
+ An empty result and a failed query are told apart: `row_count` 0 with no
+ `error` means nothing matched, and a typo'd column name says so.
- **`qet_export` isolates its launch.** SingleApplication keys its socket
on `applicationFilePath()`, so a second launch of the same binary path
forwards its request to an already-running instance and returns *that*
@@ -115,16 +286,64 @@ Across the shipped examples: 3190 conductors, not one with a cable value.
its ends with `terminal1`/`terminal2`, and the project format has two
schemes: folio-scoped integer ids in older files, terminal-definition
uuids plus `element1`/`element2` in newer ones. The integer ids are
- **renumbered on every save**, so keying on them made all 47 conductors of
- an untouched `ArduinoLCD.qet` read as 29 removed and 29 re-added the
- moment the other side had been through QElectroTech. Ends are now keyed
- by owning element uuid plus terminal, which is stable across a save:
- measured at 0 colliding keys over 3190 conductors in the 24 shipped
- examples, and 0 churn on a re-saved but otherwise untouched project.
- Where an element predates persisted uuids the end cannot be resolved and
- keeps a `#`-marked unstable key; the diff then reports `unstable_keys`
- and says so rather than pretending to be comparable.
+ **renumbered on every save**, so keying on them — which this tool did at
+ first — made all 47 conductors of an untouched folio read as removed and
+ re-added the moment the other side had been through QElectroTech, which
+ is exactly what `qet_edit` produces. They are now keyed by owning element
+ uuid plus terminal, which is stable across a save: measured at 0 colliding
+ keys over 3190 conductors in the 24 shipped examples, and 0 churn on a
+ no-op edit. Where an element predates persisted uuids the end cannot be
+ resolved and keeps a `#`-marked unstable key; the diff then reports
+ `unstable_keys` and says so rather than pretending to be comparable.
+- **Texts, shapes and images have no uuid**, so `qet_diff` cannot say "the same
+ text, edited": an edited text reads as the old one removed and a new one
+ added, both shown. Shapes and images are keyed by position, so a restyle
+ or rescale *is* reported as a change to that item, but a move reads as a
+ removal plus an addition. The folio `version` attribute is left out of the
+ comparison on purpose: QElectroTech rewrites it on every save, and
+ including it made every folio of any re-saved project look edited.
- **Elements** written before persisted uuids fall back to a positional key,
- which makes a move in such a file read as a remove plus an add rather
- than as a move.
-- Read-only by design. Nothing here writes to a project.
+ which makes a move in such a file read as a remove plus an add.
+- **`qet_edit` needs a build whose scripting API carries the drawing verbs.**
+ Against an older one it reports exactly which methods are missing and
+ changes nothing. `addElement` and the move/delete verbs shipped with the
+ scripting API; `addConductor`, `rotateElement`, `setElementLabel`,
+ `setElementInfo` and `setFolioTitle` are newer.
+- **`elements_dir` is not optional for `common://` paths.** The sandboxed
+ run has its own empty HOME, so QElectroTech falls back to the compiled-in
+ collection path, which on a machine that never ran `make install` does not
+ exist. The only symptom is `addElement` reporting that a file plainly
+ present "does not resolve to an element". An absolute `.elmt` path works
+ without it.
+- **`set_conductor` changes the whole potential, not one segment.** That is
+ what the application does — a wire number describes a potential — so name
+ a terminal carrying exactly one conductor and the change reaches every
+ conductor electrically joined to it. A terminal several conductors meet
+ at names none of them and is refused, so address a potential from one of
+ its leaves. Property names are the file's own, so `qet_conductors` reads
+ back exactly what was set.
+- **`link_elements` takes a folio for each end**, because a master and its
+ slave are normally on different folios. Whether a pair may be linked is
+ decided by QElectroTech's own `isLinkable()`, so a script cannot make a
+ link the GUI would refuse.
+- **An element must live inside a collection to be placeable.** This is
+ not about the path syntax: an absolute `.elmt` path works, but only if
+ the file sits under a directory QElectroTech knows as a collection.
+ Write it under the tree you pass as `elements_dir` and `qet_edit` can
+ place it, by absolute path or as `common://…`; write it anywhere else
+ and `add_element` reports only "does not resolve to an element".
+- **`qet_element_build` computes the `.elmt` size header, and checks it.**
+ `width`/`height`/`hotspot_x`/`hotspot_y` relate to the drawing by a
+ containment constraint, not a formula — the declared box runs from
+ `(-hotspot_x, -hotspot_y)` to `(width - hotspot_x, height - hotspot_y)`
+ and the drawing must fit inside it. The shipped collection shows authors
+ picking their own margins (one element pads 2 units left and 3 right,
+ another 8 and 2), so there is no convention to copy, only an invariant
+ to satisfy. A drawing that escaped its box is the classic way a
+ hand-written element renders clipped in the collection panel while
+ looking fine in XML.
+- **QElectroTech interrupts a script at 30 s** of its own accord, separately
+ from this tool's `timeout`. A very long operation list will hit that
+ first.
+- **`qet_edit` never writes the input.** It saves to a separate file and
+ diffs the two, so the original is always the thing the diff is against.
diff --git a/misc/qet-mcp/__pycache__/qet_mcp.cpython-314.pyc b/misc/qet-mcp/__pycache__/qet_mcp.cpython-314.pyc
deleted file mode 100644
index bb43f416c..000000000
Binary files a/misc/qet-mcp/__pycache__/qet_mcp.cpython-314.pyc and /dev/null differ
diff --git a/misc/qet-mcp/fixtures/plc_master_test.elmt b/misc/qet-mcp/fixtures/plc_master_test.elmt
new file mode 100644
index 000000000..39a140262
--- /dev/null
+++ b/misc/qet-mcp/fixtures/plc_master_test.elmt
@@ -0,0 +1,44 @@
+
+
+
+ ملف KA بمحتفظ مغناطيسي
+ Bobina
+ Bistabilní remanentní relé
+ Remanenzrelais
+ Πηνίο με μανδάλωση
+ Coil
+ Bobina KA de remanencia
+ Bobine KA à rémanence
+ Tekercs
+ Bobina
+ spoel remanent
+ Spoel KA remanent
+ Cewka przekaźnika remanencyjnego
+ Bobina
+ Обмотка
+ 剩磁保持线圈
+
+
+ plc
+
+ Author: The QElectroTech team
+License: see http://qelectrotech.org/wiki/doc/elements_license
+
+
+
+
+ A2
+
+
+ A1
+
+
+
+
+ label
+
+
+
+
+
+
diff --git a/misc/qet-mcp/fixtures/plc_slave_test.elmt b/misc/qet-mcp/fixtures/plc_slave_test.elmt
new file mode 100644
index 000000000..c5ecac2b3
--- /dev/null
+++ b/misc/qet-mcp/fixtures/plc_slave_test.elmt
@@ -0,0 +1,16 @@
+
+
+
+ PLC Slave Test
+
+
+ plc
+ NO
+ 1
+
+
+
+
+
+
+
diff --git a/misc/qet-mcp/qet_mcp.py b/misc/qet-mcp/qet_mcp.py
index 3e1966d02..c76d5275c 100755
--- a/misc/qet-mcp/qet_mcp.py
+++ b/misc/qet-mcp/qet_mcp.py
@@ -52,6 +52,7 @@ No third-party dependencies — the MCP SDK is not assumed to be present.
from __future__ import annotations
import json
+import re
import os
import shutil
import subprocess
@@ -148,8 +149,8 @@ def _terminal_index(diagram: ET.Element) -> dict:
save and terminal1="34" terminal2="15" after one. Keying a conductor on
that pair, which this tool used to do, made every conductor in the file
read as removed-and-re-added whenever the "after" side had been through
- QElectroTech -- which is the common case for "what did that edit change",
- so the conductor half of the diff was noise precisely when it was needed.
+ QElectroTech -- which is exactly the case qet_edit produces, so the
+ conductor half of the diff was noise precisely when it was needed.
So resolve each id to (owning element uuid, terminal position and
orientation inside that element). Element uuids are persisted and
@@ -288,6 +289,144 @@ def tool_conductors(path: str, folio: int | None = None,
"conductors": rows[:limit]}
+# No "version": that attribute is the file-format stamp QElectroTech rewrites
+# on every save, so diffing it made every folio of any re-saved project look
+# edited, and it is not something a script can set (see setFolioProperty).
+_FOLIO_FIELDS = ("title", "author", "plant", "locmach", "indexrev",
+ "folio", "filename",
+ # the frame: attribute names as the file writes them
+ "cols", "colsize", "rows", "rowsize", "displaycols", "displayrows",
+ "titleblocktemplate")
+
+
+def _plain_text(html: str) -> str:
+ """The visible text of an independent text's HTML, which is what a
+ person means by "the text". The file stores a whole HTML document."""
+ import re
+ body = re.search(r"]*>(.*)", html or "", re.S)
+ inner = body.group(1) if body else (html or "")
+ inner = re.sub(r"<[^>]+>", "", inner)
+ for a, b in (("<", "<"), (">", ">"), ("&", "&"), (""", '"'), ("'", "'")):
+ inner = inner.replace(a, b)
+ return " ".join(inner.split())
+
+
+def _extras(root: ET.Element) -> dict:
+ """Everything a folio holds besides elements and conductors.
+
+ Independent texts, shapes and images have no uuid, so nothing here can
+ say "this is the same text, edited". A change to one therefore reads as
+ the old one removed and a new one added, with both shown -- accurate,
+ if less tidy than a move. Position is the identity they have.
+ """
+ folios, texts, shapes, images = {}, {}, {}, {}
+ for n, d in _folios(root):
+ folios[n] = {f: d.get(f, "") for f in _FOLIO_FIELDS}
+ for t in d.iter("input"):
+ key = (n, t.get("x", ""), t.get("y", ""), _plain_text(t.get("text", "")))
+ texts[key] = {"rotation": t.get("rotation", "0"),
+ "font": t.get("font", ""), "color": t.get("color", "")}
+ for sh in d.iter("shape"):
+ pen, brush = sh.find("pen"), sh.find("brush")
+ key = (n, sh.get("type", ""), sh.get("x1", ""), sh.get("y1", ""),
+ sh.get("x2", ""), sh.get("y2", ""))
+ shapes[key] = {
+ "line_color": pen.get("color", "") if pen is not None else "",
+ "line_style": pen.get("style", "") if pen is not None else "",
+ "line_width": pen.get("widthF", "") if pen is not None else "",
+ "fill": (brush.get("color", "") if brush is not None and
+ brush.get("style", "") != "NoBrush" else "none"),
+ "rotation": sh.get("rotation", "0")}
+ for im in d.iter("image"):
+ key = (n, im.get("x", ""), im.get("y", ""))
+ images[key] = {"scale": im.get("size", ""), "rotation": im.get("rotation", "")}
+
+ element_texts = {}
+ for n, d in _folios(root):
+ for el in d.iter("element"):
+ uuid = el.get("uuid", "")
+ seen = {}
+ for t in el.iter("dynamic_elmt_text"):
+ src = t.get("text_from", "")
+ what = (t.findtext("info_name") if src == "ElementInfo"
+ else t.findtext("composite_text") if src == "CompositeText"
+ else t.findtext("text")) or ""
+ base = (uuid, src, what)
+ seen[base] = seen.get(base, 0) + 1
+ fs = (t.get("font", "").split(",") + ["", ""])[1]
+ element_texts[base + (seen[base],)] = {
+ "x": t.get("x", ""), "y": t.get("y", ""), "size": fs,
+ "frame": t.get("frame", ""), "rotation": t.get("rotation", ""),
+ "width": t.get("text_width", ""),
+ "shows": t.findtext("text") or ""}
+
+ strips = {}
+ for st in root.iter("terminal_strip"):
+ data = st.find("terminal_strip_data")
+ if data is None:
+ continue
+ info = {i.get("name"): (i.text or "") for i in data.iter("information")}
+ strips[data.get("uuid", "")] = {
+ "installation": info.get("installation", ""),
+ "location": info.get("location", ""),
+ "name": info.get("name", ""),
+ "terminals": sum(1 for _ in st.iter("real_terminal"))}
+ return {"folios": folios, "texts": texts, "shapes": shapes,
+ "images": images, "strips": strips, "element_texts": element_texts}
+
+
+def _diff_keyed(a: dict, b: dict, label) -> dict:
+ """added / removed / changed for two dicts keyed by identity."""
+ changed = []
+ for k in sorted(set(a) & set(b), key=str):
+ delta = {f: [a[k][f], b[k][f]] for f in a[k] if a[k][f] != b[k].get(f)}
+ if delta:
+ changed.append({"item": label(k), "changed": delta})
+ return {"before": len(a), "after": len(b),
+ "added": [label(k) for k in sorted(set(b) - set(a), key=str)][:50],
+ "removed": [label(k) for k in sorted(set(a) - set(b), key=str)][:50],
+ "changed": changed[:50]}
+
+
+def _diff_extras(before: ET.Element, after: ET.Element) -> dict:
+ a, b = _extras(before), _extras(after)
+ out = {}
+ ta, tb = before.get("title", ""), after.get("title", "")
+ out["project"] = {"changed": {"title": [ta, tb]} if ta != tb else {}}
+ # Folios are keyed by position. A reorder or a removal in the middle
+ # shifts every later index, so a folio "changing" its title alongside a
+ # folio count change can just be the shift -- the count says which.
+ folio_changes = []
+ for n in sorted(set(a["folios"]) & set(b["folios"])):
+ delta = {f: [a["folios"][n][f], b["folios"][n][f]] for f in _FOLIO_FIELDS
+ if a["folios"][n][f] != b["folios"][n][f]}
+ if delta:
+ folio_changes.append({"folio": n, "changed": delta})
+ out["folios"] = {"before": len(a["folios"]), "after": len(b["folios"]),
+ "changed": folio_changes[:50]}
+ if len(a["folios"]) != len(b["folios"]) and folio_changes:
+ out["folios"]["note"] = ("the folio count changed, so changes listed here may be "
+ "later folios shifting position rather than edits")
+ out["texts"] = _diff_keyed(a["texts"], b["texts"],
+ lambda k: {"folio": k[0], "x": k[1], "y": k[2], "text": k[3]})
+ out["shapes"] = _diff_keyed(a["shapes"], b["shapes"],
+ lambda k: {"folio": k[0], "type": k[1],
+ "from": [k[2], k[3]], "to": [k[4], k[5]]})
+ out["images"] = _diff_keyed(a["images"], b["images"],
+ lambda k: {"folio": k[0], "x": k[1], "y": k[2]})
+ # Keyed by element, what the field is bound to, and the nth such field.
+ # A field's own text is also compared ("shows"), so relabelling an
+ # element shows up here as well as in the element's information.
+ out["element_texts"] = _diff_keyed(
+ a["element_texts"], b["element_texts"],
+ lambda k: {"element": k[0], "source": k[1], "bound_to": k[2], "n": k[3]})
+ out["terminal_strips"] = _diff_keyed(
+ a["strips"], b["strips"],
+ lambda k: (lambda v: f"{v['installation']} {v['location']} {v['name']}".strip())(
+ (b["strips"].get(k) or a["strips"].get(k))))
+ return out
+
+
def tool_diff(before: str, after: str) -> dict:
"""Structural diff of two .qet files.
@@ -372,6 +511,7 @@ def tool_diff(before: str, after: str) -> dict:
"changed_count": len(conductor_changes),
**unstable,
},
+ **_diff_extras(_root(before), _root(after)),
}
@@ -421,14 +561,41 @@ def tool_scan(directory: str, tag: str = "conductor",
}
+def _terminals_in_index_order(terminal_nodes) -> tuple:
+ """Order an element's terminals the way QElectroTech indexes them.
+
+ Not file order. Element::parseTerminal() re-sorts the terminals every
+ time it adds one, top to bottom and then left to right, on each
+ terminal's local (y, x) -- Terminal::dockConductor() is mapToScene() of
+ its position, evaluated while the element still sits unrotated at the
+ origin. So the terminal a script reaches as index 0 is the topmost one,
+ whatever order the .elmt lists them in: bobine_ka_a_remanence.elmt
+ writes A2 (y=20) before A1 (y=-20), and add_conductor's index 0 is A1.
+ Getting this wrong wires the wrong end of a coil and nothing complains.
+
+ Returns (nodes in index order, ambiguous). Two terminals at the same
+ point tie, and the C++ sort is not stable, so which one is index 0 is
+ not defined; ambiguous says so instead of pretending.
+ """
+ def key(t):
+ try:
+ return (float(t.get("y", 0)), float(t.get("x", 0)))
+ except ValueError:
+ return (0.0, 0.0)
+ ordered = sorted(terminal_nodes, key=key)
+ keys = [key(t) for t in ordered]
+ return ordered, len(keys) != len(set(keys))
+
+
def tool_element_info(path: str) -> dict:
"""Introspect a .elmt: names, terminals, and which info fields it carries."""
root = _root(path)
names = {n.get("lang"): (n.text or "") for n in root.iter("name")}
- terminals = [{"x": t.get("x"), "y": t.get("y"),
+ ordered, ambiguous = _terminals_in_index_order(list(root.iter("terminal")))
+ terminals = [{"index": i, "x": t.get("x"), "y": t.get("y"),
"orientation": t.get("orientation"),
"name": t.get("name", ""), "type": t.get("type", "")}
- for t in root.iter("terminal")]
+ for i, t in enumerate(ordered)]
info_fields = sorted({(i.text or "").strip()
for i in root.iter("info_name") if (i.text or "").strip()})
parts = {}
@@ -441,12 +608,18 @@ def tool_element_info(path: str) -> dict:
"width": root.get("width"), "height": root.get("height"),
"names": names,
"terminal_count": len(terminals), "terminals": terminals,
+ "terminal_order": "index order: top to bottom then left to right, "
+ "not the file's order" + (
+ "; two terminals share a point, so their relative "
+ "index is undefined" if ambiguous else ""),
"info_fields": info_fields,
"parts": parts,
}
-def _run_qet(binary: str, args: list[str], timeout: int = 180) -> dict:
+def _run_qet(binary: str, args: list[str], timeout: int = 180,
+ elements_dir: str | None = None,
+ script: str | None = None, tail: int = 4000) -> dict:
"""Launch QElectroTech headlessly, carrying the known launch traps.
SingleApplication keys its socket on applicationFilePath(), so a second
@@ -454,6 +627,31 @@ def _run_qet(binary: str, args: list[str], timeout: int = 180) -> dict:
instance and returns THAT process's answer with no error. Copying the
binary to a unique path gives this run its own socket. A symlink will
not do: applicationFilePath() resolves it back.
+
+ The sandbox HOME that isolation buys also costs something, and it is
+ not obvious: with no settings file, QETApp::commonElementsDir() falls
+ back to the compiled-in QET_COMMON_COLLECTION_PATH, which on a machine
+ that has never run `make install` does not exist. Every "common://..."
+ path then fails to resolve and the only symptom is addElement()
+ reporting "does not resolve to an element" for a file that is plainly
+ there. elements_dir writes the one setting that fixes it. The file name
+ is not free-choice: QSettings derives it from the organisation and
+ application names main.cpp sets before this branch runs, so it must be
+ QElectroTech/QElectroTech.conf and nothing else.
+
+ script, when given, is written into the sandbox and passed to --run.
+ It lives inside the temporary directory so it cannot collide with a
+ concurrent call, and it is returned to the caller on failure, because a
+ generated script nobody can see is not debuggable.
+
+ The environment is inherited, not rebuilt, so QET_ENABLE_SCRIPTING
+ reaches QElectroTech from wherever this server was started -- normally
+ the "env" block of the MCP client's own configuration. That is the
+ consent: whoever configured this server and pointed it at a
+ QElectroTech binary made the choice, and their interactive
+ QElectroTech keeps whatever its own setting says. This server does not
+ set the variable itself, because a switch a program turns on for
+ itself is not a switch.
"""
src = Path(binary).expanduser()
if not src.is_file() or not os.access(src, os.X_OK):
@@ -465,6 +663,19 @@ def _run_qet(binary: str, args: list[str], timeout: int = 180) -> dict:
home = sandbox / "home"
(home / ".config").mkdir(parents=True)
(home / ".local" / "share").mkdir(parents=True)
+ if elements_dir:
+ coll = Path(elements_dir).expanduser()
+ if not coll.is_dir():
+ raise ValueError(f"no such elements directory: {coll}")
+ cfg = home / ".config" / "QElectroTech"
+ cfg.mkdir(parents=True, exist_ok=True)
+ (cfg / "QElectroTech.conf").write_text(
+ "[elements-collections]\n"
+ f"common-collection-path={coll}\n", encoding="utf-8")
+ if script is not None:
+ script_path = sandbox / "qet-mcp-edit.js"
+ script_path.write_text(script, encoding="utf-8")
+ args = ["--run", str(script_path), *args]
env = dict(os.environ,
HOME=str(home),
XDG_CONFIG_HOME=str(home / ".config"),
@@ -477,8 +688,26 @@ def _run_qet(binary: str, args: list[str], timeout: int = 180) -> dict:
return {"ok": False, "timed_out": True, "timeout_s": timeout,
"hint": "a modal dialog during load will hang a headless "
"run; check the project's format version"}
- return {"ok": p.returncode == 0, "exit_code": p.returncode,
- "stdout": p.stdout[-4000:], "stderr": p.stderr[-4000:]}
+ result = {"ok": p.returncode == 0, "exit_code": p.returncode,
+ "stdout": p.stdout[-tail:], "stderr": p.stderr[-tail:]}
+ # QElectroTech refuses --run when scripting is switched off, which
+ # it is by default. Its own message is clear but French, and it
+ # names a settings dialog that nobody driving this server is
+ # looking at -- so say the thing that actually applies here. Keyed
+ # on QElectroTech naming the variable, with exit 3 as a fallback
+ # for a future build that words the refusal differently.
+ if script is not None and not result["ok"] and (
+ "QET_ENABLE_SCRIPTING" in p.stderr or p.returncode == 3):
+ result["hint"] = (
+ "this tool drives QElectroTech through a script, and this "
+ "QElectroTech has scripting switched off. Add "
+ "QET_ENABLE_SCRIPTING=1 to the environment this server is "
+ "started in -- in an MCP client that is the \"env\" block of "
+ "its entry in the client configuration. Only qet_query, "
+ "qet_continuity, qet_check, qet_project_new and qet_edit "
+ "need it; every other tool either reads the file directly "
+ "or uses a plain CLI flag.")
+ return result
def tool_export(binary: str, project: str, format: str, output: str,
@@ -505,6 +734,1273 @@ def tool_export(binary: str, project: str, format: str, output: str,
return result
+# --------------------------------------------------------------------------
+# qet_element_build: author a .elmt definition
+# --------------------------------------------------------------------------
+
+# Derived from the 6,918 shipped elements rather than from documentation:
+# these are the attributes each part tag actually carries. Everything not
+# listed here is refused, so a typo becomes an error instead of an
+# attribute QElectroTech silently ignores.
+PART_SCHEMA = {
+ "line": {"required": ("x1", "y1", "x2", "y2"),
+ "optional": ("end1", "end2", "length1", "length2")},
+ "rect": {"required": ("x", "y", "width", "height"), "optional": ("rx", "ry")},
+ "ellipse": {"required": ("x", "y", "width", "height"), "optional": ()},
+ "circle": {"required": ("x", "y", "diameter"), "optional": ()},
+ "arc": {"required": ("x", "y", "width", "height", "start", "angle"),
+ "optional": ()},
+ "polygon": {"required": ("points",), "optional": ("closed",)},
+ "text": {"required": ("x", "y", "text"), "optional": ("size", "rotation", "color")},
+}
+
+DEFAULT_STYLE = "line-style:normal;line-weight:normal;filling:none;color:black"
+
+TERMINAL_ORIENTATIONS = ("n", "s", "e", "w")
+
+# As used in the collection. "thumbnail" is included because it is the
+# second most common value, not because this tool can build a good one.
+LINK_TYPES = ("simple", "thumbnail", "master", "slave", "terminal",
+ "next_report", "previous_report")
+
+
+def _f(value, where: str) -> float:
+ try:
+ return float(value)
+ except (TypeError, ValueError):
+ raise ValueError(f"{where}: expected a number, got {value!r}")
+
+
+def _part_extent(kind: str, part: dict) -> list:
+ """The x,y points a part reaches, for the bounding box."""
+ g = lambda k: _f(part[k], f"{kind}.{k}")
+ if kind == "line":
+ return [(g("x1"), g("y1")), (g("x2"), g("y2"))]
+ if kind in ("rect", "ellipse", "arc"):
+ x, y, w, h = g("x"), g("y"), g("width"), g("height")
+ return [(x, y), (x + w, y + h)]
+ if kind == "circle":
+ x, y, d = g("x"), g("y"), g("diameter")
+ return [(x, y), (x + d, y + d)]
+ if kind == "polygon":
+ return [(_f(px, "polygon point"), _f(py, "polygon point"))
+ for px, py in part["points"]]
+ if kind == "text":
+ return [(g("x"), g("y"))]
+ return []
+
+
+def _element_geometry(parts: list, terminals: list) -> dict:
+ """Bounding box, then a declared box that contains it.
+
+ The .elmt header carries width/height/hotspot_x/hotspot_y, and the
+ relationship to the drawing is a containment constraint rather than a
+ formula: the declared box runs from (-hotspot_x, -hotspot_y) to
+ (width - hotspot_x, height - hotspot_y) in the element's own
+ coordinates, and the drawing has to fit inside it. Checked against the
+ shipped collection, where authors chose their own margins -- one
+ element pads 2 units on the left and 3 on the right, another 8 and 2 --
+ so there is nothing to copy, only an invariant to satisfy.
+
+ Sizes are rounded out to multiples of 10, which is what every element
+ sampled from the collection uses and what keeps terminals on the grid.
+ """
+ points = []
+ for part in parts:
+ points += _part_extent(part["type"], part)
+ for t in terminals:
+ points.append((_f(t["x"], "terminal.x"), _f(t["y"], "terminal.y")))
+ if not points:
+ raise ValueError("an element needs at least one part or terminal")
+
+ min_x = min(x for x, _ in points)
+ max_x = max(x for x, _ in points)
+ min_y = min(y for _, y in points)
+ max_y = max(y for _, y in points)
+
+ import math
+ pad = 5.0
+ hotspot_x = int(math.ceil((-min_x + pad) / 10.0) * 10)
+ hotspot_y = int(math.ceil((-min_y + pad) / 10.0) * 10)
+ width = int(math.ceil((max_x + hotspot_x + pad) / 10.0) * 10)
+ height = int(math.ceil((max_y + hotspot_y + pad) / 10.0) * 10)
+
+ # The invariant, asserted rather than trusted: an element whose drawing
+ # escapes its declared box is the classic way a hand-written .elmt
+ # renders clipped in the collection panel while looking fine in XML.
+ if not (-hotspot_x <= min_x and max_x <= width - hotspot_x
+ and -hotspot_y <= min_y and max_y <= height - hotspot_y):
+ raise ValueError(
+ f"internal error: declared box ({-hotspot_x}, {-hotspot_y}) to "
+ f"({width - hotspot_x}, {height - hotspot_y}) does not contain the "
+ f"drawing ({min_x}, {min_y}) to ({max_x}, {max_y})")
+
+ return {"width": width, "height": height,
+ "hotspot_x": hotspot_x, "hotspot_y": hotspot_y,
+ "bbox": [min_x, min_y, max_x, max_y]}
+
+
+def _validate_part(index: int, part) -> str:
+ if not isinstance(part, dict):
+ raise ValueError(f"part {index} is not an object: {part!r}")
+ kind = part.get("type")
+ if kind not in PART_SCHEMA:
+ raise ValueError(f"part {index}: unknown type {kind!r}; expected one of "
+ f"{', '.join(sorted(PART_SCHEMA))}")
+ spec = PART_SCHEMA[kind]
+ for key in spec["required"]:
+ if key not in part:
+ raise ValueError(f"part {index} ({kind}) is missing {key!r}")
+ allowed = set(spec["required"]) | set(spec["optional"]) | {"type", "style", "antialias"}
+ for key in part:
+ if key not in allowed:
+ raise ValueError(f"part {index} ({kind}): unexpected {key!r}; "
+ f"allowed: {', '.join(sorted(allowed))}")
+ if kind == "polygon":
+ pts = part["points"]
+ if not isinstance(pts, list) or len(pts) < 2:
+ raise ValueError(f"part {index} (polygon) needs at least two points")
+ for pt in pts:
+ if not (isinstance(pt, (list, tuple)) and len(pt) == 2):
+ raise ValueError(f"part {index} (polygon): each point is [x, y], got {pt!r}")
+ return kind
+
+
+def _part_element(part: dict) -> ET.Element:
+ kind = part["type"]
+ node = ET.Element(kind)
+ if kind == "polygon":
+ for n, (px, py) in enumerate(part["points"], start=1):
+ node.set(f"x{n}", _fmt(px))
+ node.set(f"y{n}", _fmt(py))
+ node.set("closed", "true" if part.get("closed", True) else "false")
+ elif kind == "text":
+ node.set("x", _fmt(part["x"]))
+ node.set("y", _fmt(part["y"]))
+ node.set("text", str(part["text"]))
+ node.set("rotation", _fmt(part.get("rotation", 0)))
+ node.set("font", f"Sans Serif,{int(part.get('size', 9))},-1,5,50,0,0,0,0,0")
+ node.set("color", str(part.get("color", "#000000")))
+ return node
+ else:
+ for key in PART_SCHEMA[kind]["required"] + PART_SCHEMA[kind]["optional"]:
+ if key in part:
+ node.set(key, _fmt(part[key]))
+ node.set("antialias", "true" if part.get("antialias", True) else "false")
+ node.set("style", part.get("style", DEFAULT_STYLE))
+ return node
+
+
+def _fmt(v) -> str:
+ """Numbers the way QElectroTech writes them: no trailing .0."""
+ if isinstance(v, bool):
+ return "true" if v else "false"
+ if isinstance(v, (int, float)):
+ f = float(v)
+ return str(int(f)) if f == int(f) else repr(f)
+ return str(v)
+
+
+def tool_element_build(output: str, names: dict, parts: list,
+ terminals: list | None = None,
+ link_type: str = "simple",
+ informations: dict | None = None,
+ uuid: str | None = None) -> dict:
+ """Write a .elmt element definition.
+
+ Unlike a project, an element definition is not rewritten by
+ QElectroTech on a round trip, so generating one here is safe in a way
+ that generating a .qet would not be: there is no toXml() that will
+ drop what this writer did not know to emit.
+
+ What it will not do is invent geometry. The caller supplies the parts;
+ this validates them against the schema the shipped collection actually
+ uses, computes the width/height/hotspot header so the declared box
+ contains the drawing, and refuses anything it cannot place.
+ """
+ terminals = terminals or []
+ if not isinstance(names, dict) or not names:
+ raise ValueError('names must be a non-empty object, e.g. {"en": "Coil", "fr": "Bobine"}')
+ if link_type not in LINK_TYPES:
+ raise ValueError(f"unknown link_type {link_type!r}; expected one of "
+ f"{', '.join(LINK_TYPES)}")
+ if not isinstance(parts, list):
+ raise ValueError("parts must be a list")
+ for i, part in enumerate(parts):
+ _validate_part(i, part)
+ for i, t in enumerate(terminals):
+ if not isinstance(t, dict):
+ raise ValueError(f"terminal {i} is not an object: {t!r}")
+ for key in ("x", "y", "orientation"):
+ if key not in t:
+ raise ValueError(f"terminal {i} is missing {key!r}")
+ if t["orientation"] not in TERMINAL_ORIENTATIONS:
+ raise ValueError(f"terminal {i}: orientation is one of "
+ f"{', '.join(TERMINAL_ORIENTATIONS)}, got {t['orientation']!r}")
+ # A master with no terminal cannot be wired, and a slave with none
+ # cannot be placed on a rail -- both are silent failures at use time.
+ if link_type in ("master", "slave", "simple") and not terminals:
+ raise ValueError(f"a {link_type} element with no terminals cannot be connected; "
+ "add terminals, or use link_type 'thumbnail' for a drawing-only element")
+
+ geometry = _element_geometry(parts, terminals)
+
+ root = ET.Element("definition", {
+ "version": "0.100.0", "type": "element", "link_type": link_type,
+ "width": str(geometry["width"]), "height": str(geometry["height"]),
+ "hotspot_x": str(geometry["hotspot_x"]), "hotspot_y": str(geometry["hotspot_y"]),
+ })
+ ET.SubElement(root, "uuid", {"uuid": uuid or "{" + str(__import__("uuid").uuid4()) + "}"})
+ names_node = ET.SubElement(root, "names")
+ for lang in sorted(names):
+ ET.SubElement(names_node, "name", {"lang": lang}).text = str(names[lang])
+ if informations:
+ kind = ET.SubElement(root, "kindInformations")
+ for key in sorted(informations):
+ ET.SubElement(kind, "kindInformation", {"name": key}).text = str(informations[key])
+ ET.SubElement(root, "informations")
+ description = ET.SubElement(root, "description")
+ for part in parts:
+ description.append(_part_element(part))
+ for t in terminals:
+ attrs = {"x": _fmt(t["x"]), "y": _fmt(t["y"]),
+ "orientation": t["orientation"],
+ "type": t.get("type", "Generic"),
+ "uuid": "{" + str(__import__("uuid").uuid4()) + "}"}
+ if t.get("name"):
+ attrs["name"] = str(t["name"])
+ ET.SubElement(description, "terminal", attrs)
+
+ out = Path(output).expanduser()
+ out.parent.mkdir(parents=True, exist_ok=True)
+ ET.indent(root, space=" ")
+ out.write_bytes(ET.tostring(root, encoding="utf-8", xml_declaration=True))
+
+ # Read it back with the same reader every other tool here uses, rather
+ # than reporting what was intended.
+ check = tool_element_info(str(out))
+ return {"ok": True, "output": str(out), "bytes": out.stat().st_size,
+ **geometry,
+ # The order add_conductor will use, which is not the order the
+ # caller listed them in.
+ "terminal_index_order": [t["name"] or f"({t['x']},{t['y']})"
+ for t in check["terminals"]],
+ "verified": check}
+
+
+# --------------------------------------------------------------------------
+# qet_edit: drive the scripting API, then prove what it did
+# --------------------------------------------------------------------------
+
+# op name -> (qet method, argument spec). A spec entry is (json key, kind),
+# where kind says how the value is turned into JavaScript and, for "folio"
+# and "elmt", that it may be a "$name" reference to an earlier op's result.
+OPS = {
+ "add_folio": (None, []),
+ "set_folio_title": ("setFolioTitle", [("folio", "folio"), ("title", "str")]),
+ "add_element": ("addElement", [("folio", "folio"), ("path", "str"),
+ ("x", "num"), ("y", "num")]),
+ "set_position": ("setElementPosition", [("folio", "folio"), ("element", "elmt"),
+ ("x", "num"), ("y", "num")]),
+ "move_element": ("moveElement", [("folio", "folio"), ("element", "elmt"),
+ ("dx", "num"), ("dy", "num")]),
+ "rotate_element": ("rotateElement", [("folio", "folio"), ("element", "elmt"),
+ ("angle", "num")]),
+ "set_label": ("setElementLabel", [("folio", "folio"), ("element", "elmt"),
+ ("label", "str")]),
+ "set_info": ("setElementInfo", [("folio", "folio"), ("element", "elmt"),
+ ("key", "str"), ("value", "str")]),
+ "add_conductor": ("addConductor", [("folio", "folio"),
+ ("from", "elmt"), ("from_terminal", "num"),
+ ("to", "elmt"), ("to_terminal", "num")]),
+ "delete_element": ("deleteElement", [("folio", "folio"), ("element", "elmt")]),
+ "set_conductor": ("setConductorProperty", [("folio", "folio"), ("element", "elmt"),
+ ("terminal", "num"), ("property", "str"),
+ ("value", "str")]),
+ "move_conductor_segment": ("moveConductorSegment", [("folio", "folio"), ("element", "elmt"),
+ ("terminal", "num"), ("segment", "num"),
+ ("dx", "num"), ("dy", "num")]),
+ "link_elements": ("linkElements", [("folio", "folio"), ("element", "elmt"),
+ ("to_folio", "folio"), ("to", "elmt")]),
+ "link_plc_io": ("linkElements", [("folio", "folio"), ("element", "elmt"),
+ ("to_folio", "folio"), ("to", "elmt"),
+ ("io_index", "folio")]),
+ "unlink_element": ("unlinkElement", [("folio", "folio"), ("element", "elmt")]),
+ "add_plc_io": ("addPlcIO", [("folio", "folio"), ("element", "elmt"),
+ ("type", "str"), ("address", "str"),
+ ("function", "str"), ("comment", "str")]),
+ "set_plc_io": ("setPlcIO", [("folio", "folio"), ("element", "elmt"),
+ ("index", "folio"), ("property", "str"),
+ ("value", "str")]),
+ "remove_plc_io": ("removePlcIO", [("folio", "folio"), ("element", "elmt"),
+ ("index", "folio")]),
+ # Texts and shapes have no uuid; they are addressed by index into a
+ # position-sorted listing, and add_text/add_shape return that index so
+ # it can be named as "$id". Indexes shift when one is added or deleted.
+ "delete_conductor": ("deleteConductor", [("folio", "folio"), ("element", "elmt"),
+ ("terminal", "num")]),
+ "remove_folio": ("removeFolio", [("folio", "folio")]),
+ "set_folio": ("setFolioProperty", [("folio", "folio"), ("property", "str"),
+ ("value", "str")]),
+ "add_terminal_strip": ("addTerminalStrip", [("installation", "str"), ("location", "str"),
+ ("name", "str")]),
+ "remove_terminal_strip": ("removeTerminalStrip", [("strip", "folio")]),
+ "add_to_strip": ("addTerminalToStrip", [("strip", "folio"), ("folio", "folio"),
+ ("element", "elmt")]),
+ "group_terminals": ("groupTerminals", [("strip", "folio"), ("indices", "indices")]),
+ "bridge_terminals": ("bridgeTerminals", [("strip", "folio"), ("indices", "indices")]),
+ "sort_terminal_strip": ("sortTerminalStrip", [("strip", "folio")]),
+ "add_autonum": ("addAutoNum", [("kind", "str"), ("name", "str"),
+ ("parts", "list")]),
+ "remove_autonum": ("removeAutoNum", [("kind", "str"), ("name", "str")]),
+ "use_conductor_autonum": ("useConductorAutoNum", [("folio", "folio"), ("name", "str")]),
+ "use_element_autonum": ("useElementAutoNum", [("name", "str")]),
+ "number_element": ("numberElement", [("folio", "folio"), ("element", "elmt")]),
+ # The text fields drawn on a symbol. Indexed within the element's own
+ # list, which follows its definition and shifts on delete (and undo of a
+ # delete puts the field back at the end).
+ "add_element_text": ("addElementText", [("folio", "folio"), ("element", "elmt"),
+ ("source", "str"), ("value", "str"),
+ ("x", "num"), ("y", "num")]),
+ "set_element_text": ("setElementTextProperty", [("folio", "folio"), ("element", "elmt"),
+ ("index", "folio"), ("property", "str"),
+ ("value", "str")]),
+ "delete_element_text": ("deleteElementText", [("folio", "folio"), ("element", "elmt"),
+ ("index", "folio")]),
+ # Returns the uuids of the copies IN THE ORDER the elements were named,
+ # so "$copies[0]" is the copy of the first one. Conductors between the
+ # copied elements are copied with them; copies arrive without labels or
+ # wire numbers, as they do on a paste in the application.
+ "insert_folio": ("insertFolio", [("position", "folio")]),
+ # Reads, not edits: the result is reported in the operations list, so a
+ # follow-up call can lay something out relative to it.
+ "element_geometry": ("elementGeometry", [("folio", "folio"), ("element", "elmt")]),
+ # Undo/redo act on QElectroTech's undo stack for this run, one command at
+ # a time. Consecutive edits to the same property or information key merge
+ # into one command, so one undo can revert several of them.
+ "undo": ("undo", []),
+ "redo": ("redo", []),
+ "search_and_replace": ("searchAndReplace", [("kind", "str"), ("field", "str"),
+ ("pattern", "str"), ("replacement", "str"),
+ ("regex", "bool"), ("case_sensitive", "bool")]),
+ "set_project_title": ("setProjectTitle", [("title", "str")]),
+ "set_folio_border": ("setFolioBorder", [("folio", "folio"), ("property", "str"),
+ ("value", "str")]),
+ "embed_title_block_template": ("embedTitleBlockTemplate", [("name", "str")]),
+ "duplicate_elements": ("duplicateElements", [("folio", "folio"), ("elements", "elmts"),
+ ("to_folio", "folio"), ("x", "num"), ("y", "num")]),
+ "add_text": ("addText", [("folio", "folio"), ("text", "str"),
+ ("x", "num"), ("y", "num")]),
+ "set_text": ("setTextContent", [("folio", "folio"), ("index", "folio"),
+ ("text", "str")]),
+ "set_text_color": ("setTextColor", [("folio", "folio"), ("index", "folio"),
+ ("color", "str")]),
+ "rotate_text": ("setTextRotation", [("folio", "folio"), ("index", "folio"),
+ ("angle", "num")]),
+ "delete_text": ("deleteText", [("folio", "folio"), ("index", "folio")]),
+ "add_shape": ("addShape", [("folio", "folio"), ("shape", "str"),
+ ("x1", "num"), ("y1", "num"),
+ ("x2", "num"), ("y2", "num")]),
+ "set_shape": ("setShapeProperty", [("folio", "folio"), ("index", "folio"),
+ ("property", "str"), ("value", "str")]),
+ "add_image": ("addImage", [("folio", "folio"), ("file", "str"),
+ ("x", "num"), ("y", "num")]),
+ "add_pdf_page": ("addPdfPage", [("folio", "folio"), ("file", "str"),
+ ("page", "num"), ("dpi", "num"),
+ ("x", "num"), ("y", "num")]),
+ "scale_image": ("setImageScale", [("folio", "folio"), ("index", "folio"),
+ ("factor", "num")]),
+ "rotate_image": ("setImageRotation", [("folio", "folio"), ("index", "folio"),
+ ("angle", "num")]),
+ "delete_image": ("deleteImage", [("folio", "folio"), ("index", "folio")]),
+ "delete_shape": ("deleteShape", [("folio", "folio"), ("index", "folio")]),
+ "add_polygon": ("addPolygon", [("folio", "folio"), ("points", "points"),
+ ("closed", "bool")]),
+ "set_shape_polygon": ("setShapePolygon", [("folio", "folio"), ("index", "folio"),
+ ("points", "points")]),
+ "add_path": ("addPath", [("folio", "folio"), ("nodes", "nodes"),
+ ("closed", "bool")]),
+ "set_shape_path_nodes": ("setShapePathNodes", [("folio", "folio"), ("index", "folio"),
+ ("nodes", "nodes")]),
+ "set_shape_closed": ("setShapeClosed", [("folio", "folio"), ("index", "folio"),
+ ("closed", "bool")]),
+ "add_table": ("addTable", [("folio", "folio"), ("kind", "str"),
+ ("name", "str"), ("query", "str")]),
+ "set_table_position": ("setTablePosition", [("folio", "folio"), ("table", "folio"),
+ ("x", "num"), ("y", "num")]),
+ "delete_table": ("deleteTable", [("folio", "folio"), ("table", "folio")]),
+}
+
+SHAPES = ["line", "rectangle", "ellipse", "polygon"]
+FOLIO_BORDER_PROPERTIES = ["columns", "column-width", "display-columns",
+ "rows", "row-height", "display-rows"]
+ELEMENT_TEXT_SOURCES = ["text", "info", "composite"]
+ELEMENT_TEXT_PROPERTIES = ["text", "source", "info", "composite", "frame", "size",
+ "x", "y", "rotation", "width"]
+SHAPE_PROPERTIES = ["color", "fill", "width", "line-style", "rotation"]
+AUTONUM_KINDS = ["conductor", "element", "folio"]
+SEARCH_REPLACE_KINDS = ["element_info", "conductor", "text"]
+FOLIO_PROPERTIES = ["title", "author", "filename", "plant", "locmach",
+ "indexrev", "folio", "template"]
+
+# Accepted by set_conductor. The names are the project file's own, so what
+# a script sets is what qet_conductors reports back.
+CONDUCTOR_PROPERTIES = ["num", "formula", "function", "bus", "cable",
+ "tension_protocol", "conductor_color",
+ "conductor_section", "color", "text_color",
+ # the conductor's look, under the file's own names
+ "color2", "bicolor", "style", "dash-size",
+ "condsize", "numsize", "displaytext"]
+
+# Methods this tool needs that only exist in a build carrying the drawing
+# verbs. Probed in the script rather than assumed, because the failure mode
+# otherwise is a TypeError on line N of a generated file the caller never
+# sees, reported as "the edit failed".
+_REQUIRED_METHODS = sorted({m for m, _ in OPS.values() if m} |
+ {"save", "folioCount", "conductorCount", "elementCount"})
+
+_MARKER = "QETEDIT "
+
+
+def _js(value) -> str:
+ """A JSON literal is a JavaScript literal for every type used here."""
+ return json.dumps(value)
+
+
+def _build_script(operations: list, output: str) -> str:
+ """Turn the operation list into a script, or raise on a bad operation.
+
+ Every op is validated here, before QElectroTech is launched at all: a
+ typo in an op name should cost nothing, not a process start and a
+ JavaScript exception.
+ """
+ refs: set[str] = set()
+ lines = [
+ "// generated by qet-mcp; do not edit",
+ "var R = {};", # $name -> value from an earlier op
+ "var missing = [];",
+ f"var need = {_js(_REQUIRED_METHODS)};",
+ "for (var i = 0; i < need.length; i++) {",
+ " if (typeof qet[need[i]] !== 'function') missing.push(need[i]);",
+ "}",
+ f"qet.log({_js(_MARKER)} + JSON.stringify("
+ "{kind: 'capabilities', missing: missing}));",
+ "var stop = false;",
+ "if (missing.length === 0) {",
+ ]
+
+ def ref_or(value, kind: str, op_index: int, key: str) -> str:
+ if kind == "elmts":
+ if not isinstance(value, list) or not value or not all(isinstance(v, str) for v in value):
+ raise ValueError(f"operation {op_index}: {key!r} must be a non-empty list of "
+ f"elements (uuids or \"$id\" references), got {value!r}")
+ return "[" + ", ".join(ref_or(v, "elmt", op_index, key) for v in value) + "]"
+ if isinstance(value, str) and value.startswith("$"):
+ indexed = re.fullmatch(r"\$([A-Za-z0-9_]+)\[(\d+)\]", value)
+ if indexed:
+ # one item of a list result, e.g. the second copy from
+ # duplicate_elements
+ name, n = indexed.group(1), int(indexed.group(2))
+ if name not in refs:
+ raise ValueError(
+ f"operation {op_index} refers to {value!r}, which no earlier "
+ f"operation defined (set \"id\": {name!r} on the op that creates it)")
+ return f"R[{_js(name)}][{n}]"
+ name = value[1:]
+ if name not in refs:
+ raise ValueError(
+ f"operation {op_index} refers to {value!r}, which no earlier "
+ f"operation defined (set \"id\": {name!r} on the op that creates it)")
+ return f"R[{_js(name)}]"
+ if kind == "num":
+ if not isinstance(value, (int, float)) or isinstance(value, bool):
+ raise ValueError(f"operation {op_index}: {key!r} must be a number, "
+ f"got {value!r}")
+ return _js(value)
+ if kind == "list":
+ if not isinstance(value, list) or not all(isinstance(x, str) for x in value):
+ raise ValueError(f"operation {op_index}: {key!r} must be a list of strings, "
+ f"got {value!r}")
+ return _js(value)
+ if kind == "indices":
+ if (not isinstance(value, list) or not value
+ or not all(isinstance(x, int) and not isinstance(x, bool) for x in value)):
+ raise ValueError(f"operation {op_index}: {key!r} must be a non-empty list of "
+ f"integer indices, got {value!r}")
+ return _js(value)
+ if kind == "folio":
+ if not isinstance(value, int) or isinstance(value, bool):
+ raise ValueError(f"operation {op_index}: {key!r} must be a folio index "
+ f"or a \"$name\" reference, got {value!r}")
+ return _js(value)
+ if kind == "bool":
+ if not isinstance(value, bool):
+ raise ValueError(f"operation {op_index}: {key!r} must be true or false, "
+ f"got {value!r}")
+ return _js(value)
+ if kind in ("points", "nodes"):
+ def _num(v):
+ return isinstance(v, (int, float)) and not isinstance(v, bool)
+ if not isinstance(value, list) or len(value) < 2:
+ raise ValueError(f"operation {op_index}: {key!r} must be a list of at "
+ f"least 2 {'points' if kind == 'points' else 'nodes'}, "
+ f"got {value!r}")
+ for item in value:
+ if not isinstance(item, dict) or not _num(item.get("x")) or not _num(item.get("y")):
+ raise ValueError(f"operation {op_index}: {key!r} entries must be "
+ f"{{\"x\": num, \"y\": num, ...}}, got {item!r}")
+ if kind == "nodes":
+ if "kind" in item and item["kind"] not in ("corner", "smooth", "symmetric"):
+ raise ValueError(f"operation {op_index}: {key!r} entry kind "
+ f"{item['kind']!r} must be corner, smooth or symmetric")
+ for hkey in ("inHandle", "outHandle"):
+ if hkey in item and (not isinstance(item[hkey], dict)
+ or not _num(item[hkey].get("x"))
+ or not _num(item[hkey].get("y"))):
+ raise ValueError(f"operation {op_index}: {key!r} entry "
+ f"{hkey!r} must be {{\"x\": num, \"y\": num}}")
+ return _js(value)
+ return _js("" if value is None else str(value))
+
+ for i, op in enumerate(operations):
+ if not isinstance(op, dict):
+ raise ValueError(f"operation {i} is not an object: {op!r}")
+ name = op.get("op")
+ if name not in OPS:
+ raise ValueError(f"operation {i}: unknown op {name!r}; "
+ f"expected one of {', '.join(sorted(OPS))}")
+ method, spec = OPS[name]
+ if name == "set_conductor" and op.get("property") not in CONDUCTOR_PROPERTIES:
+ raise ValueError(f"operation {i}: unknown conductor property "
+ f"{op.get('property')!r}; expected one of "
+ f"{', '.join(CONDUCTOR_PROPERTIES)}")
+ if name == "set_folio" and op.get("property") not in FOLIO_PROPERTIES:
+ raise ValueError(f"operation {i}: unknown folio property "
+ f"{op.get('property')!r}; expected one of "
+ f"{', '.join(FOLIO_PROPERTIES)}")
+ if name in ("add_autonum", "remove_autonum") and op.get("kind") not in AUTONUM_KINDS:
+ raise ValueError(f"operation {i}: unknown kind {op.get('kind')!r}; "
+ f"expected one of {', '.join(AUTONUM_KINDS)}")
+ if name == "search_and_replace":
+ if op.get("kind") not in SEARCH_REPLACE_KINDS:
+ raise ValueError(f"operation {i}: unknown kind {op.get('kind')!r}; "
+ f"expected one of {', '.join(SEARCH_REPLACE_KINDS)}")
+ if op.get("kind") == "conductor" and op.get("field") not in CONDUCTOR_PROPERTIES:
+ raise ValueError(f"operation {i}: unknown conductor field "
+ f"{op.get('field')!r}; expected one of "
+ f"{', '.join(CONDUCTOR_PROPERTIES)}")
+ if op.get("kind") == "element_info" and not op.get("field"):
+ raise ValueError(f"operation {i}: element_info needs a non-empty "
+ f"\"field\" (information key)")
+ if name == "set_folio_border" and op.get("property") not in FOLIO_BORDER_PROPERTIES:
+ raise ValueError(f"operation {i}: unknown folio border property "
+ f"{op.get('property')!r}; expected one of "
+ f"{', '.join(FOLIO_BORDER_PROPERTIES)}")
+ if name == "add_element_text" and op.get("source") not in ELEMENT_TEXT_SOURCES:
+ raise ValueError(f"operation {i}: unknown source {op.get('source')!r}; "
+ f"expected one of {', '.join(ELEMENT_TEXT_SOURCES)}")
+ if name == "set_element_text" and op.get("property") not in ELEMENT_TEXT_PROPERTIES:
+ raise ValueError(f"operation {i}: unknown element-text property "
+ f"{op.get('property')!r}; expected one of "
+ f"{', '.join(ELEMENT_TEXT_PROPERTIES)}")
+ if name == "set_shape" and op.get("property") not in SHAPE_PROPERTIES:
+ raise ValueError(f"operation {i}: unknown shape property "
+ f"{op.get('property')!r}; expected one of "
+ f"{', '.join(SHAPE_PROPERTIES)}")
+ if name == "add_shape" and op.get("shape") not in SHAPES:
+ raise ValueError(f"operation {i}: unknown shape {op.get('shape')!r}; "
+ f"expected one of {', '.join(SHAPES)}")
+ args = []
+ for key, kind in spec:
+ if key not in op:
+ raise ValueError(f"operation {i} ({name}) is missing {key!r}")
+ args.append(ref_or(op[key], kind, i, key))
+
+ ident = op.get("id")
+ if ident is not None:
+ if not isinstance(ident, str) or not ident or ident.startswith("$"):
+ raise ValueError(f"operation {i}: \"id\" must be a non-empty name "
+ f"without a leading $, got {ident!r}")
+ if ident in refs:
+ raise ValueError(f"operation {i}: \"id\" {ident!r} is already used")
+
+ call = "qet.addFolio()" if method is None else f"qet.{method}({', '.join(args)})"
+ lines.append(" if (!stop) {")
+ lines.append(f" var v{i} = {call};")
+ if ident is not None:
+ lines.append(f" R[{_js(ident)}] = v{i};")
+ refs.add(ident)
+ lines.append(
+ f" qet.log({_js(_MARKER)} + JSON.stringify("
+ f"{{kind: 'op', index: {i}, op: {_js(name)}, "
+ f"id: {_js(ident)}, result: v{i}}}));")
+ # An op that failed usually invalidates the ones after it -- a
+ # conductor to an element that was never placed is not a second,
+ # independent finding, it is noise on top of the first one. The
+ # three falsey returns are the three the API uses: false for a
+ # refused edit, "" for an addElement that placed nothing, -1 for an
+ # addFolio that added none.
+ # An empty list is a failure too (duplicateElements returns [] when it
+ # refuses). Duck-typed on .length, not Array.isArray: QJSEngine hands
+ # an empty QStringList back as an array-like wrapper for which
+ # Array.isArray is false, so that test never fired and the run went
+ # on past the failed operation.
+ lines.append(f" if (v{i} === false || v{i} === '' || v{i} === -1 || "
+ f"(typeof v{i} === 'object' && v{i} !== null && "
+ f"(v{i}.length === 0 || (v{i}.length === undefined && "
+ f"Object.keys(v{i}).length === 0)))) "
+ "stop = true;")
+ lines.append(" }")
+ lines.append(" // ---- end of operations ----")
+
+ # Save even after a failed op: a partial result that can be inspected
+ # beats no result at all, and the diff is what says how far it got.
+ lines.append(f" var saved = qet.save({_js(output)});")
+ lines.append(f" qet.log({_js(_MARKER)} + JSON.stringify("
+ "{kind: 'save', result: saved, stopped_early: stop}));")
+ lines.append("}")
+ return "\n".join(lines) + "\n"
+
+
+def _parse_script_output(text: str) -> dict:
+ """Read the marker lines the generated script emits.
+
+ They arrive on stderr, not stdout: QetScriptApi::log() is a
+ QTextStream(stderr). Read both anyway rather than depending on that --
+ the cost is nothing and the failure it prevents is silent (an edit that
+ worked, reported as having run no operations at all, which is what the
+ first version of this tool did)."""
+ caps, ops, saved, stopped = None, [], None, False
+ for line in text.splitlines():
+ idx = line.find(_MARKER)
+ if idx < 0:
+ continue
+ try:
+ rec = json.loads(line[idx + len(_MARKER):])
+ except json.JSONDecodeError:
+ continue
+ if rec.get("kind") == "capabilities":
+ caps = rec.get("missing") or []
+ elif rec.get("kind") == "op":
+ rec.pop("kind", None)
+ # Not "in (False, ...)": 0 == False in Python, and 0 is a valid
+ # index/folio result. The script side already uses strict ===.
+ r = rec.get("result")
+ rec["succeeded"] = not (r is None or r is False or r == "" or r == [] or r == {} or
+ (isinstance(r, int) and not isinstance(r, bool) and r == -1))
+ ops.append(rec)
+ elif rec.get("kind") == "save":
+ saved = bool(rec.get("result"))
+ stopped = bool(rec.get("stopped_early"))
+ return {"missing_methods": caps, "operations": ops, "saved": saved,
+ "stopped_early": stopped}
+
+
+def tool_query(binary: str, project: str, sql: str,
+ elements_dir: str | None = None, timeout: int = 180) -> dict:
+ """Run a read-only SELECT against the project's SQLite database.
+
+ This is the surface the rest of this server has done without. Every
+ other structural tool here re-derives its answer from the XML, because
+ the database was unreachable from outside the application; it is
+ reachable now, through the same guarded path QElectroTech's own
+ "Requête SQL personnalisée" box uses, so a structural question can be
+ asked of the database that already knows it.
+
+ The three *_view names are the surface to depend on --
+ element_nomenclature_view, project_summary_view, wiring_list_view.
+ They exist to be queried. The underlying tables are how the cache is
+ arranged today and a column may move; qet_query with sql omitted
+ lists both.
+ """
+ proj = Path(project).expanduser()
+ if not proj.is_file():
+ raise ValueError(f"no such project: {proj}")
+
+ if sql:
+ # Same first-word rule projectDataBase::isReadOnlySelect() applies,
+ # checked here too so an obvious write is refused without paying
+ # for a process launch. QET still enforces it; this is not the
+ # guard, only an early one.
+ head = sql.strip().lstrip("(").split(None, 1)[0].upper() if sql.strip() else ""
+ if head not in ("SELECT", "WITH"):
+ raise ValueError("only read-only queries are allowed: a statement must "
+ f"begin with SELECT or WITH, not {head or '(nothing)'}")
+
+ script = ("var out = %s ? qet.query(%s) : qet.tables();\n"
+ "qet.log(%s + JSON.stringify({kind: 'query', rows: out, "
+ "error: qet.queryError ? qet.queryError() : ''}));\n"
+ % (json.dumps(bool(sql)), json.dumps(sql or ""), json.dumps(_MARKER)))
+
+ result = _run_qet(binary, [str(proj)], timeout=timeout,
+ elements_dir=elements_dir, script=script, tail=400_000)
+ streams = result.get("stdout", "") + "\n" + result.get("stderr", "")
+ rows, error = None, ""
+ for line in streams.splitlines():
+ idx = line.find(_MARKER)
+ if idx < 0:
+ continue
+ try:
+ rec = json.loads(line[idx + len(_MARKER):])
+ except json.JSONDecodeError:
+ continue
+ if rec.get("kind") == "query":
+ rows, error = rec.get("rows"), rec.get("error") or ""
+ for key in ("stdout", "stderr"):
+ kept = [ln for ln in result.get(key, "").splitlines() if _MARKER not in ln]
+ result[key] = "\n".join(kept)[-4000:]
+
+ if rows is None:
+ result["ok"] = False
+ result.setdefault("hint", "the query returned nothing at all -- this build's "
+ "scripting API may predate qet.query()")
+ return result
+ if error:
+ result["ok"] = False
+ result["error"] = error
+ result["rows"] = rows
+ result["row_count"] = len(rows)
+ result["listing"] = not sql
+ return result
+
+
+# --------------------------------------------------------------------------
+# qet_continuity: electrical continuity / ERC-style structural checks
+# --------------------------------------------------------------------------
+
+def tool_continuity(binary: str, project: str, folio: int | None = None,
+ elements_dir: str | None = None, timeout: int = 180) -> dict:
+ """Run qet.checkContinuity() and get its findings back.
+
+ Three checks, against the live Terminal/Conductor object graph rather
+ than a heuristic read of the XML (that is qet_check's job, and the two
+ are complementary, not redundant -- qet_check looks at labels and
+ numbering conventions, this looks at the electrical graph itself):
+ unconnected_terminal (info -- routine, not necessarily a mistake),
+ potential_mismatch (error -- two conductors QElectroTech's own
+ setConductorProperty() would always keep identical, found disagreeing,
+ which only happens from hand-edited XML, a legacy file, or an external
+ tool), and report_link_mismatch (warning -- a next_report/
+ previous_report folio-jump pair whose conductors disagree on colour,
+ style, num, etc.; unlike potential_mismatch this one CAN happen through
+ ordinary use, since LinkElementCommand::isLinkable() never checks
+ conductor properties, only type and freedom -- see
+ qelectrotech/qelectrotech-source-mirror#974, which this check
+ reproduces exactly: one folio-link conductor drawn in two different
+ colours on either side of the link). See qet.checkContinuity()'s own
+ doc comment (qetscriptapi.cpp) for what this deliberately does not
+ check: pin electrical direction/power conflicts and No/Nc/Common
+ contact shorts, since QElectroTech's terminal data model does not
+ carry the information either would need.
+ """
+ proj = Path(project).expanduser()
+ if not proj.is_file():
+ raise ValueError(f"no such project: {proj}")
+
+ folio_arg = -1 if folio is None else folio
+ script = ("var out = qet.checkContinuity(%s);\n"
+ "qet.log(%s + JSON.stringify({kind: 'continuity', findings: out}));\n"
+ % (json.dumps(folio_arg), json.dumps(_MARKER)))
+
+ result = _run_qet(binary, [str(proj)], timeout=timeout,
+ elements_dir=elements_dir, script=script, tail=400_000)
+ streams = result.get("stdout", "") + "\n" + result.get("stderr", "")
+ findings = None
+ for line in streams.splitlines():
+ idx = line.find(_MARKER)
+ if idx < 0:
+ continue
+ try:
+ rec = json.loads(line[idx + len(_MARKER):])
+ except json.JSONDecodeError:
+ continue
+ if rec.get("kind") == "continuity":
+ findings = rec.get("findings")
+ for key in ("stdout", "stderr"):
+ kept = [ln for ln in result.get(key, "").splitlines() if _MARKER not in ln]
+ result[key] = "\n".join(kept)[-4000:]
+
+ if findings is None:
+ result["ok"] = False
+ result.setdefault("hint", "no findings came back at all -- this build's "
+ "scripting API may predate qet.checkContinuity()")
+ return result
+ result["findings"] = findings
+ result["finding_count"] = len(findings)
+ result["errors"] = sum(1 for f in findings if f.get("severity") == "error")
+ result["warnings"] = sum(1 for f in findings if f.get("severity") == "warning")
+ result["info"] = sum(1 for f in findings if f.get("severity") == "info")
+ return result
+
+
+# --------------------------------------------------------------------------
+# qet_element_search: find a symbol in the collection
+# --------------------------------------------------------------------------
+
+_ELEMENT_INDEX: dict = {}
+
+
+def _fold(text: str) -> str:
+ """Case- and accent-insensitive form, so 'resistance' finds 'Résistance'."""
+ import unicodedata
+ return "".join(c for c in unicodedata.normalize("NFKD", text.lower())
+ if not unicodedata.combining(c))
+
+
+def _collection_signature(root: Path):
+ """Cheap change detector: file count and newest mtime, no parsing."""
+ count, newest = 0, 0.0
+ for f in root.rglob("*.elmt"):
+ count += 1
+ try:
+ newest = max(newest, f.stat().st_mtime)
+ except OSError:
+ pass
+ return count, newest
+
+
+def _index_collection(root: Path) -> list:
+ """Parse every .elmt under root once and keep what a search needs.
+
+ Cached for the life of the process and rebuilt when the file count or
+ the newest modification time changes -- which is what makes a symbol
+ written by qet_element_build findable straight away, without the caller
+ knowing there is an index at all.
+ """
+ key = str(root.resolve())
+ sig = _collection_signature(root)
+ cached = _ELEMENT_INDEX.get(key)
+ if cached and cached["sig"] == sig:
+ return cached["items"]
+
+ items = []
+ for f in sorted(root.rglob("*.elmt")):
+ try:
+ d = ET.parse(f).getroot()
+ except (ET.ParseError, OSError):
+ continue
+ if d.tag != "definition":
+ continue
+ names = {n.get("lang", ""): (n.text or "").strip() for n in d.iter("name")}
+ kind = ""
+ for ki in d.iter("kindInformation"):
+ if ki.get("name") == "type":
+ kind = (ki.text or "").strip()
+ ordered, ambiguous = _terminals_in_index_order(list(d.iter("terminal")))
+ terminals = [t.get("name") or "" for t in ordered]
+ rel = f.relative_to(root).as_posix()
+ items.append({
+ "path": "common://" + rel,
+ "file": str(f),
+ "name": names.get("en") or names.get("fr") or next(iter(names.values()), ""),
+ "names": names,
+ "link_type": d.get("link_type", "simple"),
+ "kind": kind,
+ "terminals": len(terminals),
+ "terminal_names": terminals, # index order, not file order
+ "terminal_order_ambiguous": ambiguous,
+ "width": d.get("width"), "height": d.get("height"),
+ "haystack": _fold(" ".join([*names.values(), rel, kind])),
+ })
+ _ELEMENT_INDEX[key] = {"sig": sig, "items": items}
+ return items
+
+
+def tool_element_search(directory: str, query: str = "", link_type: str | None = None,
+ min_terminals: int | None = None, max_terminals: int | None = None,
+ kind: str | None = None, limit: int = 25) -> dict:
+ """Search an element collection by name, type and terminal count.
+
+ Matches every word of query against all the translated names, the
+ element's path and its kind, ignoring case and accents -- so a French
+ or German search finds the same symbol an English one does. Results
+ carry a common:// path that qet_edit's add_element takes directly, and
+ the terminal names in the order add_conductor indexes them -- which is
+ top to bottom then left to right, not the order the file lists them.
+ """
+ root = Path(directory).expanduser()
+ if not root.is_dir():
+ raise ValueError(f"no such directory: {root}")
+ if link_type is not None and link_type not in LINK_TYPES:
+ raise ValueError(f"unknown link_type {link_type!r}; expected one of "
+ f"{', '.join(LINK_TYPES)}")
+ if limit < 1:
+ raise ValueError("limit must be >= 1")
+
+ words = _fold(query).split()
+ matches = []
+ for it in _index_collection(root):
+ if link_type and it["link_type"] != link_type:
+ continue
+ if kind and _fold(kind) not in _fold(it["kind"]):
+ continue
+ if min_terminals is not None and it["terminals"] < min_terminals:
+ continue
+ if max_terminals is not None and it["terminals"] > max_terminals:
+ continue
+ if not all(w in it["haystack"] for w in words):
+ continue
+ matches.append(it)
+
+ # Whole-name hits before substring hits, then shorter names first: a
+ # search for "coil" should offer "Coil" before "Remanence coil, latching".
+ def rank(it):
+ name = _fold(it["name"])
+ exact = 0 if (words and name == " ".join(words)) else 1
+ starts = 0 if (words and name.startswith(words[0])) else 1
+ return (exact, starts, len(it["name"]), it["path"])
+ matches.sort(key=rank)
+
+ shown = [{k: v for k, v in it.items() if k not in ("haystack", "names", "file")}
+ | {"languages": sorted(it["names"])} for it in matches[:limit]]
+ return {"query": query, "total_matches": len(matches), "returned": len(shown),
+ "indexed": len(_ELEMENT_INDEX[str(root.resolve())]["items"]),
+ "results": shown}
+
+
+# Design-rule checks, each one a read-only query over the project database.
+#
+# Every check is a SELECT that returns the offending rows, so "no rows" is a
+# pass and the same query is what a human would write by hand. The severity
+# and the note say how much to trust a hit, because these are heuristics
+# tuned against the 24 shipped examples, not standards:
+#
+# - Every text comparison is COALESCE'd. A value that was never set is NULL
+# in the database when the element was placed in this session and an empty
+# string when it was loaded from a file, and `col = ''` matches only the
+# second -- which made the first version of these checks silently pass on
+# exactly the freshly-edited projects qet_edit produces. The JavaScript
+# side renders both as "", so the difference is invisible until a check
+# fails to fire. Likewise exclude_from_bom is text, not a number.
+# - An unnumbered conductor is '' in some files and '_' in others: '_' is the
+# placeholder QElectroTech assigns when no numbering is configured, so
+# testing for '' alone passed on industrial.qet's 36 placeholder conductors
+# and on every project qet_edit builds without a numbering context.
+# - Slaves and terminals are excluded from the duplicate-label check on
+# purpose. A slave contact carries its master coil's label by design, and
+# terminals repeat their numbers from one strip to the next; counting
+# either would bury the real findings.
+# - "simple" elements are checked for duplicates too but only as a warning:
+# industrial.qet reuses V1..V6 across folios on purpose.
+CHECKS = {
+ "duplicate_master_labels": {
+ "severity": "error",
+ "note": "Two master elements with the same label are ambiguous in every "
+ "report that keys on it (BOM, cross-references, wiring list).",
+ "sql": "SELECT label, COUNT(*) AS n FROM element_nomenclature_view "
+ "WHERE COALESCE(label,'') <> '' AND element_type = 'master' "
+ "GROUP BY label HAVING n > 1 ORDER BY n DESC, label",
+ },
+ "duplicate_simple_labels": {
+ "severity": "warning",
+ "note": "Legitimate when a label is reused on purpose across folios "
+ "(industrial.qet does); worth a look otherwise.",
+ "sql": "SELECT label, COUNT(*) AS n FROM element_nomenclature_view "
+ "WHERE COALESCE(label,'') <> '' AND element_type = 'simple' "
+ "GROUP BY label HAVING n > 1 ORDER BY n DESC, label",
+ },
+ "unlabelled_masters": {
+ "severity": "warning",
+ "note": "A master with no label cannot be told apart from its slaves' "
+ "cross-references.",
+ "sql": "SELECT folio, diagram_position, element_sub_type FROM "
+ "element_nomenclature_view WHERE element_type = 'master' AND COALESCE(label,'') = '' "
+ "ORDER BY folio, diagram_position",
+ },
+ "unnumbered_conductors": {
+ "severity": "info",
+ "note": "Conductors with no wire number -- empty, or QElectroTech's own "
+ "'_' placeholder, which is what a conductor gets when no "
+ "numbering is configured. If every conductor is unnumbered the "
+ "project simply does not use wire numbering; a few among many "
+ "numbered ones is the finding.",
+ "sql": "SELECT COUNT(*) AS unnumbered, (SELECT COUNT(*) FROM wiring_list_view) AS total "
+ "FROM wiring_list_view WHERE COALESCE(wire_number,'') IN ('', '_') "
+ "HAVING unnumbered > 0",
+ },
+ "empty_folios": {
+ "severity": "info",
+ "note": "Folios with no element on them. Often cover pages, sometimes "
+ "left behind by a deleted drawing.",
+ "sql": "SELECT p.pos AS position, p.title AS title FROM diagram d "
+ "JOIN project_summary_view p ON p.pos = d.pos "
+ "WHERE NOT EXISTS (SELECT 1 FROM element e WHERE e.diagram_uuid = d.uuid) "
+ "ORDER BY p.pos",
+ },
+ "masters_without_manufacturer_reference": {
+ "severity": "info",
+ "note": "Masters that will show a blank article number in the BOM.",
+ "sql": "SELECT label, folio, diagram_position FROM element_nomenclature_view "
+ "WHERE element_type = 'master' AND COALESCE(manufacturer_reference,'') = '' "
+ "AND COALESCE(exclude_from_bom,'') IN ('', '0', 'false') "
+ "ORDER BY folio, diagram_position",
+ },
+}
+
+
+def tool_check(binary: str, project: str, checks: list | None = None,
+ sample: int = 10, elements_dir: str | None = None,
+ timeout: int = 180) -> dict:
+ """Run design-rule checks over a project in one QElectroTech launch.
+
+ Every check is a read-only SELECT over the project database, so this is
+ qet_query with the questions already written down. It exists because the
+ useful questions are always the same handful and re-deriving them per
+ conversation is where the mistakes creep in -- the first draft of the
+ duplicate-label check counted slave contacts, which share their coil's
+ label by design and flagged nearly every relay.
+ """
+ proj = Path(project).expanduser()
+ if not proj.is_file():
+ raise ValueError(f"no such project: {proj}")
+ chosen = list(CHECKS) if not checks else list(checks)
+ for name in chosen:
+ if name not in CHECKS:
+ raise ValueError(f"unknown check {name!r}; expected one of "
+ f"{', '.join(sorted(CHECKS))}")
+ if sample < 0:
+ raise ValueError("sample must be >= 0")
+
+ queries = {name: CHECKS[name]["sql"] for name in chosen}
+ script = ("var Q = %s;\nfor (var k in Q) {\n"
+ " var rows = qet.query(Q[k]);\n"
+ " qet.log(%s + JSON.stringify({kind: 'check', name: k, rows: rows, "
+ "error: qet.queryError()}));\n}\n" % (json.dumps(queries), json.dumps(_MARKER)))
+ result = _run_qet(binary, [str(proj)], timeout=timeout,
+ elements_dir=elements_dir, script=script, tail=2_000_000)
+ streams = result.get("stdout", "") + "\n" + result.get("stderr", "")
+
+ got = {}
+ for line in streams.splitlines():
+ idx = line.find(_MARKER)
+ if idx < 0:
+ continue
+ try:
+ rec = json.loads(line[idx + len(_MARKER):])
+ except json.JSONDecodeError:
+ continue
+ if rec.get("kind") == "check":
+ got[rec["name"]] = rec
+
+ findings, errors, passed = [], [], []
+ for name in chosen:
+ rec = got.get(name)
+ if rec is None:
+ errors.append({"check": name, "error": "no result came back"})
+ continue
+ if rec.get("error"):
+ errors.append({"check": name, "error": rec["error"]})
+ continue
+ rows = rec.get("rows") or []
+ if not rows:
+ passed.append(name)
+ continue
+ findings.append({"check": name, "severity": CHECKS[name]["severity"],
+ "count": len(rows), "note": CHECKS[name]["note"],
+ "rows": rows[:sample]})
+
+ order = {"error": 0, "warning": 1, "info": 2}
+ findings.sort(key=lambda f: (order[f["severity"]], f["check"]))
+ answer = {"ok": not errors and not any(f["severity"] == "error" for f in findings),
+ "summary": {"errors": sum(f["severity"] == "error" for f in findings),
+ "warnings": sum(f["severity"] == "warning" for f in findings),
+ "info": sum(f["severity"] == "info" for f in findings),
+ "passed": len(passed), "check_failures": len(errors)},
+ "findings": findings, "passed": passed, "check_failures": errors}
+ # This answer is built fresh rather than layered onto the launch result,
+ # so a reason the launch failed at all has to be carried across
+ # explicitly. Without it every check reads "no result came back", which
+ # is true and tells nobody why.
+ if result.get("hint"):
+ answer["ok"] = False
+ answer["hint"] = result["hint"]
+ answer["exit_code"] = result.get("exit_code")
+ return answer
+
+
+def tool_project_new(binary: str, output: str, title: str = "Untitled",
+ folios=1, author: str = "", overwrite: bool = False,
+ elements_dir: str | None = None, timeout: int = 180) -> dict:
+ """Create a new, empty project so qet_edit has something to start from.
+
+ Every other edit tool needs an existing .qet, which made building a
+ schematic from nothing impossible. The obvious candidate,
+ examples/Projet_vierge.qet, is not blank: it is a 600 KB real project
+ with 23 elements and 15 conductors.
+
+ So this writes the smallest project QElectroTech will open -- one
+ element with a title, no folios -- and then has QElectroTech itself
+ add the folios and save. What is left on disk is QElectroTech's own
+ canonical output, not the hand-written skeleton, which is why this is
+ not the "write .qet XML directly" route that was rejected: the
+ skeleton never reaches the result, and the result is checked by
+ reading it back.
+
+ folios is a count, or a list of folio titles.
+ """
+ out = Path(output).expanduser()
+ if out.exists() and not overwrite:
+ raise ValueError(f"{out} already exists; pass overwrite=true to replace it")
+ if isinstance(folios, bool) or not isinstance(folios, (int, list)):
+ raise ValueError("folios must be a count or a list of titles")
+ titles = ([""] * folios) if isinstance(folios, int) else [str(t) for t in folios]
+ if not 0 <= len(titles) <= 200:
+ raise ValueError("folios must be between 0 and 200")
+ if not isinstance(title, str) or not title.strip():
+ raise ValueError("title must be a non-empty string")
+
+ from xml.sax.saxutils import quoteattr
+ script = ["var t = %s;" % json.dumps(titles), "var made = [];",
+ "for (var i = 0; i < t.length; i++) {",
+ " var f = qet.addFolio(); made.push(f);",
+ " if (f >= 0 && t[i]) qet.setFolioTitle(f, t[i]);",
+ " if (f >= 0 && %s) qet.setFolioProperty(f, 'author', %s);" %
+ (json.dumps(bool(author)), json.dumps(author)),
+ "}",
+ "var saved = qet.save(%s);" % json.dumps(str(out)),
+ "qet.log(%s + JSON.stringify({kind: 'new', folios: made, saved: saved}));"
+ % json.dumps(_MARKER)]
+
+ out.parent.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(prefix="qet-mcp-new-") as tmp:
+ skeleton = Path(tmp) / "skeleton.qet"
+ skeleton.write_text('