archi-cli 0.1.0__py3-none-any.whl

archi_tool/engine.py

@@ -0,0 +1,266 @@
+"""Fetch and cache the Archi engine so `normalize` works without a manual
+install.
+
+`normalize` drives Archi's headless command-line application. Archi is a full
+cross-platform desktop distribution (~165 MB, with a bundled Java runtime, so
+it is self-contained) published on GitHub releases at ``archimatetool/archi.io``.
+There is no smaller headless-only artifact; we download the full distribution
+once, cache it per user, and point ARCHI_APP at the extracted binary.
+
+The version is pinned so the download is deterministic and reproducible. Bump
+ARCHI_VERSION deliberately.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import platform
+import shutil
+import subprocess
+import tarfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from .model import ModelError
+
+ARCHI_VERSION = "5.9.0"
+RELEASE_BASE = (
+    "https://github.com/archimatetool/archi.io/releases/download"
+    f"/{ARCHI_VERSION}")
+
+# per platform: (asset filename, relative path to the binary inside the
+# extracted tree). Archi bundles its own JRE, so no system Java is needed.
+_PLATFORMS = {
+    "linux": (
+        f"Archi-Linux64-{ARCHI_VERSION}.tgz",
+        "Archi/Archi"),
+    "windows": (
+        f"Archi-Win64-{ARCHI_VERSION}.zip",
+        "Archi/Archi.exe"),
+    # macOS ships a .dmg; both Intel and Apple Silicon expose the same binary
+    # path once the app bundle is copied out of the mounted image
+    "darwin-arm64": (
+        f"Archi-Mac-Silicon-{ARCHI_VERSION}.dmg",
+        "Archi.app/Contents/MacOS/Archi"),
+    "darwin-x86_64": (
+        f"Archi-Mac-{ARCHI_VERSION}.dmg",
+        "Archi.app/Contents/MacOS/Archi"),
+}
+
+
+def cache_dir() -> Path:
+    """Per-user cache root, overridable for tests and air-gapped setups."""
+    override = os.environ.get("ARCHI_CACHE")
+    if override:
+        return Path(override)
+    base = os.environ.get("XDG_CACHE_HOME") or (Path.home() / ".cache")
+    return Path(base) / "archi-cli"
+
+
+def _platform_key() -> str:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    if system == "darwin":
+        # Archi ships both Intel and Apple Silicon builds
+        return "darwin-arm64" if machine in ("arm64", "aarch64") else "darwin-x86_64"
+    if system in ("linux", "windows"):
+        # only 64-bit x86 builds exist; refuse ARM rather than hand back an
+        # unrunnable x86 binary that fails cryptically at normalize time
+        if machine not in ("x86_64", "amd64"):
+            raise ModelError(
+                f"Archi levert alleen een x86_64-build voor {system}, geen "
+                f"'{machine}'. Installeer Archi handmatig en zet ARCHI_APP.")
+        return system
+    raise ModelError(
+        f"Geen Archi-download bekend voor platform '{system}'. Installeer "
+        "Archi handmatig en zet ARCHI_APP.")
+
+
+def cached_binary() -> Path | None:
+    """The extracted engine binary for the pinned version, if present."""
+    key = _platform_key()
+    _, rel = _PLATFORMS[key]
+    binary = cache_dir() / ARCHI_VERSION / rel
+    return binary if binary.exists() else None
+
+
+def _download(url, dest):
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    # a plain urlopen keeps the dependency footprint at zero beyond stdlib
+    with urllib.request.urlopen(url) as response, open(dest, "wb") as out:
+        shutil.copyfileobj(response, out)
+
+
+def _expected_sha1(asset) -> str | None:
+    """Fetch the release's SUMSSHA1 file and return the hash for ``asset``.
+
+    Returns None only when the checksum file can't be fetched (a transient
+    network failure shouldn't block install; the download itself is over HTTPS
+    from GitHub). If the file *is* fetched but lists no hash for ``asset``,
+    that is suspicious (renamed/tampered manifest) and raises rather than
+    silently skipping verification.
+    """
+    url = f"{RELEASE_BASE}/Archi-{ARCHI_VERSION}-SUMSSHA1"
+    try:
+        with urllib.request.urlopen(url) as response:
+            text = response.read().decode("utf-8", "replace")
+    except OSError:
+        return None
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1].lstrip("*") == asset:
+            return parts[0].lower()
+    raise ModelError(
+        f"Checksumbestand bevat geen hash voor {asset}; verificatie "
+        "afgebroken.")
+
+
+def _sha1(path) -> str:
+    digest = hashlib.sha1()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _extract(archive, key, target):
+    """Unpack the downloaded archive into ``target``; format follows platform."""
+    if key == "linux":
+        with tarfile.open(archive, "r:gz") as tar:
+            _safe_extract_tar(tar, target)
+    elif key == "windows":
+        with zipfile.ZipFile(archive) as zf:
+            _safe_extract_zip(zf, target)
+    else:  # macOS .dmg: mount, copy the .app out, unmount
+        _extract_dmg(archive, target)
+
+
+def _is_within(base, target) -> bool:
+    base = Path(base).resolve()
+    try:
+        Path(target).resolve().relative_to(base)
+        return True
+    except ValueError:
+        return False
+
+
+def _safe_extract_tar(tar, target):
+    # filter="data" (Python 3.12+) refuses absolute paths, parent traversal,
+    # and — crucially — symlinks/hardlinks that point outside the tree, which a
+    # name-only check misses. The Archi tgz has 145 legit *relative in-tree*
+    # symlinks (bundled JRE license files), which this filter allows.
+    try:
+        tar.extractall(target, filter="data")
+    except tarfile.FilterError as exc:
+        raise ModelError(f"Onveilig pad in archief: {exc}")
+
+
+def _safe_extract_zip(zf, target):
+    # zip has no symlink members, so a name check is sufficient here
+    for name in zf.namelist():
+        if not _is_within(target, Path(target) / name):
+            raise ModelError(f"Onveilig pad in archief: {name}")
+    zf.extractall(target)
+
+
+def _parse_mount_point(hdiutil_stdout) -> str | None:
+    """Extract the /Volumes mount point from `hdiutil attach` output.
+
+    Output is tab-separated with a dev node, a type and (for the data volume)
+    a mount point. A multi-partition image has extra lines without a mount
+    point, so we select the line whose last field is an actual /Volumes path
+    rather than blindly taking the last line.
+    """
+    for line in reversed(hdiutil_stdout.splitlines()):
+        field = line.split("\t")[-1].strip()
+        if field.startswith("/Volumes/"):
+            return field
+    return None
+
+
+def _extract_dmg(archive, target):
+    """Mount a .dmg, copy the Archi.app out, detach again. macOS only."""
+    mount = subprocess.run(
+        ["hdiutil", "attach", "-nobrowse", "-readonly", str(archive)],
+        capture_output=True, text=True)
+    if mount.returncode != 0:
+        raise ModelError("Kon de Archi-.dmg niet mounten:\n" + mount.stderr)
+    mount_point = _parse_mount_point(mount.stdout)
+    if not mount_point:
+        raise ModelError(
+            "Kon het mountpunt van de Archi-.dmg niet bepalen:\n"
+            + mount.stdout)
+    try:
+        source = Path(mount_point) / "Archi.app"
+        if not source.exists():
+            raise ModelError(
+                f"Archi.app niet gevonden in de gemounte image ({mount_point})")
+        Path(target).mkdir(parents=True, exist_ok=True)
+        shutil.copytree(source, Path(target) / "Archi.app")
+    finally:
+        detach = subprocess.run(["hdiutil", "detach", mount_point],
+                                capture_output=True, text=True)
+        if detach.returncode != 0:
+            # a copytree can leave the volume briefly busy; force as a fallback
+            subprocess.run(["hdiutil", "detach", "-force", mount_point],
+                           capture_output=True, text=True)
+
+
+def find_or_none():
+    """Any already-available Archi binary (installed, on PATH, or cached),
+    without triggering a download. Returns a path string or None."""
+    from .normalize import find_archi_binary
+    return find_archi_binary()
+
+
+def download_engine(*, quiet=False) -> Path:
+    """Download and extract the pinned Archi engine into the cache. Returns
+    the binary path. Raises ModelError on any failure.
+
+    Extraction happens in a staging directory and is only moved into place
+    atomically once the binary is present, so a crash mid-extract never leaves
+    a half-populated cache that later looks complete.
+    """
+    key = _platform_key()
+    asset, rel = _PLATFORMS[key]
+    version_dir = cache_dir() / ARCHI_VERSION
+    binary = version_dir / rel
+    if binary.exists():
+        return binary
+
+    url = f"{RELEASE_BASE}/{asset}"
+    if not quiet:
+        print(f"Archi-engine ophalen ({asset}, ~165 MB, eenmalig) …")
+    cache_dir().mkdir(parents=True, exist_ok=True)
+    staging = version_dir.with_name(f"{ARCHI_VERSION}.staging")
+    shutil.rmtree(staging, ignore_errors=True)
+    archive = staging / "_download" / asset
+    try:
+        _download(url, archive)
+        expected = _expected_sha1(asset)
+        if expected is not None:
+            actual = _sha1(archive)
+            if actual != expected:
+                raise ModelError(
+                    f"Checksum van {asset} klopt niet (verwacht {expected}, "
+                    f"kreeg {actual}); download afgebroken.")
+        _extract(archive, key, staging)
+        shutil.rmtree(staging / "_download", ignore_errors=True)
+        staged_binary = staging / rel
+        if not staged_binary.exists():
+            raise ModelError(
+                "Archi-engine uitgepakt maar de binary staat niet op de "
+                f"verwachte plek: {staged_binary}")
+        if key != "windows":
+            staged_binary.chmod(0o755)
+        # atomic swap into the real cache location
+        shutil.rmtree(version_dir, ignore_errors=True)
+        os.replace(staging, version_dir)
+    except OSError as exc:
+        raise ModelError(
+            f"Kon de Archi-engine niet ophalen van {url}: {exc}")
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)
+
+    return binary

archi_tool/model.py

@@ -0,0 +1,280 @@
+"""Load, query, mutate and save native Archi .archimate models.
+
+The .archimate format is Eclipse EMF XML. Only the root element lives in the
+archimate namespace; all other elements (folder, element, property, child,
+bounds, sourceConnection, documentation) are unqualified. Concepts carry an
+xsi:type attribute such as "archimate:Capability"; relationship types end in
+"Relationship" (American spelling: RealizationRelationship). Folders per
+ArchiMate layer are fixed by Archi and identified by their type attribute.
+"""
+from __future__ import annotations
+
+import uuid
+
+from lxml import etree
+
+ARCHIMATE_NS = "http://www.archimatetool.com/archimate"
+XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
+XSI_TYPE = "{%s}type" % XSI_NS
+MODEL_TAG = "{%s}model" % ARCHIMATE_NS
+
+DIAGRAM_TYPE = "ArchimateDiagramModel"
+
+ELEMENT_LAYERS = {
+    "strategy": {"Resource", "Capability", "CourseOfAction", "ValueStream"},
+    "business": {
+        "BusinessActor", "BusinessRole", "BusinessCollaboration",
+        "BusinessInterface", "BusinessProcess", "BusinessFunction",
+        "BusinessInteraction", "BusinessEvent", "BusinessService",
+        "BusinessObject", "Contract", "Representation", "Product",
+    },
+    "application": {
+        "ApplicationComponent", "ApplicationCollaboration",
+        "ApplicationInterface", "ApplicationFunction", "ApplicationInteraction",
+        "ApplicationProcess", "ApplicationEvent", "ApplicationService",
+        "DataObject",
+    },
+    "technology": {
+        "Node", "Device", "SystemSoftware", "TechnologyCollaboration",
+        "TechnologyInterface", "Path", "CommunicationNetwork",
+        "TechnologyFunction", "TechnologyProcess", "TechnologyInteraction",
+        "TechnologyEvent", "TechnologyService", "Artifact", "Material",
+        "Equipment", "Facility", "DistributionNetwork",
+    },
+    "motivation": {
+        "Stakeholder", "Driver", "Assessment", "Goal", "Outcome",
+        "Principle", "Requirement", "Constraint", "Meaning", "Value",
+    },
+    "implementation_migration": {
+        "WorkPackage", "Deliverable", "ImplementationEvent", "Plateau", "Gap",
+    },
+    "other": {"Location", "Grouping", "Junction"},
+}
+FOLDER_BY_ELEMENT_TYPE = {
+    t: layer for layer, types in ELEMENT_LAYERS.items() for t in types
+}
+
+RELATIONSHIP_TYPES = {
+    "Composition", "Aggregation", "Assignment", "Realization", "Serving",
+    "Access", "Influence", "Triggering", "Flow", "Specialization",
+    "Association",
+}
+
+
+class ModelError(Exception):
+    """User-facing error; message is Dutch."""
+
+
+def new_id() -> str:
+    return "id-" + str(uuid.uuid4())
+
+
+def xsi_type(node) -> str:
+    """Return the bare xsi:type ("archimate:Capability" -> "Capability")."""
+    value = node.get(XSI_TYPE) or ""
+    return value.split(":", 1)[-1]
+
+
+def is_relationship(node) -> bool:
+    return node.tag == "element" and xsi_type(node).endswith("Relationship")
+
+
+def is_diagram(node) -> bool:
+    return node.tag == "element" and xsi_type(node) == DIAGRAM_TYPE
+
+
+def is_element(node) -> bool:
+    return (node.tag == "element"
+            and not is_relationship(node) and not is_diagram(node))
+
+
+class ArchiModel:
+    def __init__(self, path):
+        self.path = str(path)
+        self.tree = etree.parse(self.path)
+        self.root = self.tree.getroot()
+        if self.root.tag != MODEL_TAG:
+            raise ModelError(
+                f"Geen .archimate-model: rootelement is {self.root.tag}")
+
+    # --- queries ---------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        return self.root.get("name") or ""
+
+    def id_index(self) -> dict:
+        return {n.get("id"): n for n in self.root.iter() if n.get("id")}
+
+    def folder(self, folder_type: str):
+        for f in self.root.iter("folder"):
+            if f.get("type") == folder_type:
+                return f
+        raise ModelError(f"Folder met type '{folder_type}' niet gevonden")
+
+    def elements(self) -> list:
+        return [n for n in self.root.iter("element") if is_element(n)]
+
+    def relationships(self) -> list:
+        return [n for n in self.root.iter("element") if is_relationship(n)]
+
+    def diagrams(self) -> list:
+        return [n for n in self.root.iter("element") if is_diagram(n)]
+
+    def properties(self, node) -> dict:
+        return {p.get("key"): p.get("value") for p in node.findall("property")}
+
+    def documentation(self, node) -> str:
+        doc = node.find("documentation")
+        return (doc.text or "") if doc is not None else ""
+
+    def resolve(self, ref: str):
+        """Resolve a concept by id, or by exact name if that is unique."""
+        index = self.id_index()
+        if ref in index:
+            return index[ref]
+        matches = [n for n in self.root.iter("element") if n.get("name") == ref]
+        if len(matches) == 1:
+            return matches[0]
+        if not matches:
+            raise ModelError(f"Niet gevonden: '{ref}' (geen id en geen naam)")
+        ids = ", ".join(m.get("id") for m in matches)
+        raise ModelError(
+            f"Naam '{ref}' is niet uniek ({len(matches)}x); "
+            f"gebruik het id. Kandidaten: {ids}")
+
+    def relations_of(self, concept_id: str) -> list:
+        return [r for r in self.relationships()
+                if concept_id in (r.get("source"), r.get("target"))]
+
+    # --- mutations ---------------------------------------------------------
+
+    def set_model_name(self, name: str):
+        self.root.set("name", name)
+
+    def add_element(self, el_type: str, name: str, folder_type: str = None,
+                    properties: dict = None, documentation: str = None):
+        if el_type not in FOLDER_BY_ELEMENT_TYPE:
+            known = ", ".join(sorted(FOLDER_BY_ELEMENT_TYPE))
+            raise ModelError(
+                f"Onbekend elementtype '{el_type}'. Toegestaan: {known}")
+        target = self.folder(folder_type or FOLDER_BY_ELEMENT_TYPE[el_type])
+        el = etree.SubElement(target, "element", {
+            XSI_TYPE: f"archimate:{el_type}", "name": name, "id": new_id()})
+        if documentation:
+            doc = etree.SubElement(el, "documentation")
+            doc.text = documentation
+        for key, value in (properties or {}).items():
+            etree.SubElement(el, "property", {"key": key, "value": value})
+        return el
+
+    def add_relation(self, rel_type: str, source: str, target: str,
+                     name: str = None):
+        rel_type = rel_type.removesuffix("Relationship")
+        if rel_type not in RELATIONSHIP_TYPES:
+            known = ", ".join(sorted(RELATIONSHIP_TYPES))
+            raise ModelError(
+                f"Onbekend relatietype '{rel_type}'. Toegestaan: {known}")
+        src = self.resolve(source)
+        tgt = self.resolve(target)
+        # resolve() also matches views and relations by name; only elements
+        # are valid endpoints (ArchiMate allows a relation endpoint solely
+        # for Association)
+        for role, node in (("source", src), ("target", tgt)):
+            if is_diagram(node):
+                raise ModelError(
+                    f"{role} '{node.get('name')}' is een view; relaties "
+                    "kunnen geen views verbinden")
+            if is_relationship(node) and rel_type != "Association":
+                raise ModelError(
+                    f"{role} '{node.get('name')}' is zelf een relatie; "
+                    "alleen een AssociationRelationship mag een relatie "
+                    "als eindpunt hebben")
+        attrs = {XSI_TYPE: f"archimate:{rel_type}Relationship",
+                 "id": new_id(),
+                 "source": src.get("id"), "target": tgt.get("id")}
+        if name:
+            attrs["name"] = name
+        return etree.SubElement(self.folder("relations"), "element", attrs)
+
+    def set_property(self, ref: str, key: str, value: str):
+        el = self.resolve(ref)
+        for p in el.findall("property"):
+            if p.get("key") == key:
+                p.set("value", value)
+                return
+        etree.SubElement(el, "property", {"key": key, "value": value})
+
+    def rename(self, ref: str, name: str):
+        self.resolve(ref).set("name", name)
+
+    def set_documentation(self, ref: str, text: str):
+        el = self.resolve(ref)
+        doc = el.find("documentation")
+        if doc is None:
+            doc = etree.Element("documentation")
+            el.insert(0, doc)
+        doc.text = text
+
+    def remove(self, ref: str, cascade: bool = False):
+        el = self.resolve(ref)
+        el_id = el.get("id")
+        if is_relationship(el):
+            connections = [c for c in self.root.iter("sourceConnection")
+                           if c.get("archimateRelationship") == el_id]
+            if connections and not cascade:
+                raise ModelError(
+                    f"Relatie {el_id} wordt gebruikt in {len(connections)} "
+                    "view-verbinding(en); gebruik --cascade om die mee te "
+                    "verwijderen")
+            for c in connections:
+                self._remove_connection(c)
+        else:
+            relations = self.relations_of(el_id)
+            diagram_objects = [d for d in self.root.iter("child")
+                               if d.get("archimateElement") == el_id]
+            if (relations or diagram_objects) and not cascade:
+                raise ModelError(
+                    f"Element {el_id} heeft {len(relations)} relatie(s) en "
+                    f"{len(diagram_objects)} view-object(en); gebruik "
+                    "--cascade om die mee te verwijderen")
+            for r in relations:
+                self.remove(r.get("id"), cascade=True)
+            for d in diagram_objects:
+                self._remove_diagram_object(d)
+        el.getparent().remove(el)
+
+    def _remove_connection(self, conn):
+        conn_id = conn.get("id")
+        for node in self.root.iter("child"):
+            listed = (node.get("targetConnections") or "").split()
+            if conn_id in listed:
+                remaining = [i for i in listed if i != conn_id]
+                if remaining:
+                    node.set("targetConnections", " ".join(remaining))
+                else:
+                    del node.attrib["targetConnections"]
+        conn.getparent().remove(conn)
+
+    def _remove_diagram_object(self, obj):
+        for sub in list(obj.findall("child")):
+            self._remove_diagram_object(sub)
+        for conn in list(obj.findall("sourceConnection")):
+            self._remove_connection(conn)
+        obj_id = obj.get("id")
+        incoming = [c for c in self.root.iter("sourceConnection")
+                    if c.get("target") == obj_id]
+        for conn in incoming:
+            self._remove_connection(conn)
+        obj.getparent().remove(obj)
+
+    # --- persistence -------------------------------------------------------
+
+    def save(self, path=None):
+        etree.indent(self.root, space="  ")
+        body = etree.tostring(self.root, encoding="unicode")
+        # newline="\n" keeps LF on every platform (no CRLF churn on Windows)
+        with open(path or self.path, "w", encoding="utf-8", newline="\n") as f:
+            f.write('<?xml version="1.0" encoding="UTF-8"?>\n')
+            f.write(body)
+            f.write("\n")

archi_tool/normalize.py

@@ -0,0 +1,91 @@
+"""Normalize a .archimate file through the headless Archi CLI.
+
+Archi is the canonical serializer: a load + save roundtrip rewrites the file
+exactly as Archi itself would, so git diffs stay small regardless of whether
+the last edit came from this tool or from the Archi GUI. A throwaway
+workspace (-data) avoids lock conflicts with a running Archi GUI.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+
+from .model import ModelError
+
+ARCHI_CANDIDATES = [
+    "/Applications/Archi.app/Contents/MacOS/Archi",   # macOS
+    r"C:\Program Files\Archi\Archi.exe",              # Windows (winget/inno, machine scope)
+    # Windows Inno installer without admin rights falls back to user scope;
+    # %LOCALAPPDATA% stays unexpanded (and never matches) on other platforms
+    os.path.expandvars(r"%LOCALAPPDATA%\Programs\Archi\Archi.exe"),
+    "/opt/Archi/Archi",                               # Linux tgz
+]
+
+
+def find_archi_binary():
+    """Locate an already-available Archi binary. Returns None if none is
+    found; fetching a cached copy is handled separately by normalize()."""
+    override = os.environ.get("ARCHI_APP")
+    if override:
+        # an explicit override must not silently fall through to defaults
+        return override if os.path.exists(override) else None
+    for candidate in ARCHI_CANDIDATES:
+        if os.path.exists(candidate):
+            return candidate
+    # a previously downloaded engine in the per-user cache, before any PATH
+    # lookup, so a fetched engine always wins
+    from .engine import cached_binary
+    cached = cached_binary()
+    if cached:
+        return str(cached)
+    on_path = shutil.which("Archi")
+    # on case-insensitive filesystems (macOS, Windows) which("Archi") can match
+    # our own `archi` entry point; reject it so we never drive ourselves
+    if on_path and not _is_own_entry_point(on_path):
+        return on_path
+    return None
+
+
+def _is_own_entry_point(path) -> bool:
+    """True when ``path`` is this package's own `archi` CLI rather than the
+    real Archi desktop app (a case-insensitive PATH collision)."""
+    ours = shutil.which("archi")
+    if ours and os.path.exists(ours) and os.path.exists(path):
+        return os.path.samefile(ours, path)
+    return False
+
+
+def normalize(path, *, download=True) -> None:
+    binary = find_archi_binary()
+    if not binary and download:
+        # nothing installed and downloading is allowed: fetch the pinned
+        # engine into the per-user cache (once), then use it
+        from .engine import download_engine
+        binary = str(download_engine())
+    if not binary:
+        raise ModelError(
+            "Archi niet gevonden. Haal de engine op met `archi setup`, "
+            "installeer Archi zelf (macOS: brew install --cask archi; "
+            "Windows: winget install --id Archi.Archi -e), of zet de env var "
+            "ARCHI_APP naar het pad van de Archi-binary.")
+    absolute = os.path.abspath(path)
+    with tempfile.TemporaryDirectory() as workspace:
+        result = subprocess.run(
+            [binary, "-application", "com.archimatetool.commandline.app",
+             "-consoleLog", "-nosplash", "-data", workspace,
+             "--loadModel", absolute, "--saveModel", absolute],
+            capture_output=True, text=True)
+    if result.returncode != 0:
+        output = result.stdout + result.stderr
+        if "gtk_init_check" in output or "No more handles" in output:
+            # Archi's command-line app still needs an X display on Linux; on a
+            # headless host it must run under a virtual framebuffer
+            raise ModelError(
+                "Archi kon geen X-display openen (headless Linux). Draai "
+                "normalize onder een virtueel scherm, bijvoorbeeld:\n"
+                "  xvfb-run -a archi normalize\n"
+                "(installeer xvfb, bv. `apt-get install xvfb`). Op een "
+                "desktop met display is dit niet nodig.")
+        raise ModelError("Archi-normalisatie mislukt:\n" + output)