@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/mwi/code/engine/motionworks_iec_mcp/grid.py

@@ -0,0 +1,227 @@
+"""Native variable records adapted from the supplied MotionWorksTools workflow.
+
+Four UTF-16 cells plus a 16-byte record tail; the group trailer is NOT a record.
+Unknown bytes between native records are retained. Donors must match type and usage.
+"""
+from __future__ import annotations
+import re
+import struct
+from .errors import UnsupportedFormat, NotFound
+
+USAGES = (1, 5, 0x40001, 6, 22)
+
+
+def read_record(raw: bytes, offset: int) -> dict:
+    if offset < 12 or offset + 24 > len(raw):
+        raise UnsupportedFormat('Truncated variable record header')
+    fields = struct.unpack_from('<6I', raw, offset)
+    pos, cells, spans = offset + 24, [], []
+    for _ in range(4):
+        if pos + 4 > len(raw):
+            raise UnsupportedFormat('Truncated variable cell length')
+        size = struct.unpack_from('<I', raw, pos)[0]
+        if size < 2 or size % 2 or size > 65536 or pos + 4 + size > len(raw):
+            raise UnsupportedFormat('Invalid UTF-16 variable cell length')
+        data = raw[pos + 4:pos + 4 + size]
+        if not data.endswith(b'\0\0'):
+            raise UnsupportedFormat('Variable cell lacks a terminator')
+        try:
+            value = data[:-2].decode('utf-16le')
+        except UnicodeDecodeError as exc:
+            raise UnsupportedFormat('Invalid UTF-16 variable cell') from exc
+        if '\0' in value:
+            raise UnsupportedFormat('Embedded NUL in variable cell')
+        spans.append((pos, pos + 4, pos + 4 + size))
+        cells.append(value)
+        pos += 4 + size
+    if pos + 16 > len(raw):
+        raise UnsupportedFormat('Truncated variable record tail')
+    return dict(offset=offset, end=pos + 16, fields=fields, handle=fields[0], usage=fields[1],
+                group=fields[2], row=fields[4], cells=cells, spans=spans,
+                type=cells[0], address=cells[1], initial_value=cells[2], name=cells[3],
+                tail=raw[pos:pos + 16], type_at=spans[0][0], between_at=spans[0][2],
+                initial_at=spans[2][0], name_at=spans[3][0], after_name=pos, strings_end=pos)
+
+
+def parse(raw: bytes) -> list[dict]:
+    if len(raw) < 12 or struct.unpack_from('<I', raw)[0] != 524289:
+        raise UnsupportedFormat('Unrecognized native variable worksheet header')
+    high, count = struct.unpack_from('<2I', raw, 4)
+    records = []
+    for offset in range(12, max(12, len(raw) - 23)):
+        h, u, g, f, row, z = struct.unpack_from('<6I', raw, offset)
+        if not (1000 <= h <= high and u in USAGES and 1 <= g <= 32 and f == z == 0 and 0 < row < 1000000):
+            continue
+        try:
+            record = read_record(raw, offset)
+        except UnsupportedFormat:
+            continue
+        if re.fullmatch(r'[A-Za-z_][A-Za-z_0-9]*', record['name']):
+            records.append(record)
+    if len(records) != count:
+        raise UnsupportedFormat(f'Variable grid header says {count} records; parsed {len(records)}')
+    for key in ('handle', 'name'):
+        values = [str(r[key]).casefold() for r in records]
+        if len(set(values)) != len(values):
+            raise UnsupportedFormat(f'Duplicate variable grid {key}')
+    rows = [(r['group'], r['row']) for r in records]
+    if len(set(rows)) != len(rows):
+        raise UnsupportedFormat('Duplicate worksheet row within a group')
+    for left, right in zip(records, records[1:]):
+        if left['end'] > right['offset']:
+            raise UnsupportedFormat('Overlapping variable records')
+    end = records[-1]['end'] if records else 12
+    if end >= len(raw):
+        raise UnsupportedFormat('Native worksheet group trailer is missing')
+    return records
+
+
+def encode(record: dict, *, cells=None, handle=None, row=None) -> bytes:
+    fields = list(record['fields'])
+    if handle is not None: fields[0] = handle
+    if row is not None: fields[4] = row
+    out = struct.pack('<6I', *fields)
+    for cell in cells if cells is not None else record['cells']:
+        value = (cell + '\0').encode('utf-16le')
+        out += struct.pack('<I', len(value)) + value
+    return out + record['tail']
+
+
+def find(records, name):
+    matches = [r for r in records if r['name'].casefold() == name.casefold()]
+    if len(matches) != 1:
+        raise NotFound(f'Expected one grid record for {name!r}; found {len(matches)}')
+    return matches[0]
+
+
+def require_known_extent(records, record):
+    index = records.index(record)
+    if index + 1 < len(records) and records[index + 1]['offset'] != record['end']:
+        raise UnsupportedFormat('Selected native record has an unrecognized extension; refusing to synthesize or remove it')
+
+
+def add(raw, name, type_name, *, usage=1, address='', initial_value=None,
+        donor_name=None, donor_grid=None, group=None, row=None):
+    records = parse(raw)
+    if any(r['name'].casefold() == name.casefold() for r in records):
+        raise UnsupportedFormat(f'Variable {name} already exists in the worksheet')
+    donors = parse(donor_grid if donor_grid is not None else raw)
+    allowed = set(usage if isinstance(usage, (list, tuple)) else [usage])
+    # The type must match the donor. Measured on a real project, two records of different types
+    # looked interchangeable - six uint32 fields, a 16-byte tail, group 1 - but building one from
+    # a donor of another type produced a record the project could no longer parse, and MotionWorks
+    # had already rewritten it by the time it was read back. Treat the type as part of the layout
+    # contract; a donor of the wrong type is not a safe source.
+    candidates = [r for r in donors if r['usage'] in allowed
+                  and r['type'].casefold() == type_name.casefold()
+                  and bool(r['address']) == bool(address)
+                  and (group is None or r['group'] == group)
+                  and (donor_name is None or r['name'].casefold() == donor_name.casefold())]
+    if not candidates:
+        raise UnsupportedFormat('No compatible native donor: match type, usage, group and addressed/unaddressed layout')
+    # Different hidden flags/tails cannot be resolved by guessing. Equivalent donors are interchangeable.
+    shapes = {(r['fields'][1:4], r['tail']) for r in candidates}
+    if len(shapes) != 1 and donor_name is None:
+        raise UnsupportedFormat('Ambiguous native donors; pass donor explicitly')
+    donor = candidates[0]
+    require_known_extent(donors, donor)
+    if donor_grid is not None and donor['group'] != 1:
+        raise UnsupportedFormat('Cross-worksheet donors require the Default group')
+    handle = max([struct.unpack_from('<I', raw, 4)[0]] + [r['handle'] for r in records]) + 1
+    # Rows are native worksheet identifiers, NOT declaration source line numbers.
+    new_row = max([0] + [r['row'] for r in records if r['group'] == donor['group']]) + 1
+    if row is not None:
+        new_row = row
+    if (donor['group'], new_row) in {(r['group'], r['row']) for r in records}:
+        raise UnsupportedFormat('Requested worksheet row already exists')
+    cells = [type_name, address or '', donor['initial_value'] if initial_value is None else initial_value, name]
+    record = encode(donor, cells=cells, handle=handle, row=new_row)
+    end = records[-1]['end'] if records else 12
+    out = bytearray(raw[:end] + record + raw[end:])
+    struct.pack_into('<II', out, 4, handle, len(records) + 1)
+    parse(bytes(out))
+    return bytes(out), handle
+
+
+def edit(raw, name, *, new_name=None, type_name=None, initial_value=None, address=None,
+         donor_name=None):
+    records = parse(raw)
+    current = find(records, name)
+    require_known_extent(records, current)
+    donor = current
+    wanted_type = type_name if type_name is not None else current['type']
+    wanted_address = address if address is not None else current['address']
+    if wanted_type.casefold() != current['type'].casefold() or bool(wanted_address) != bool(current['address']):
+        matches = [r for r in records if r['type'].casefold() == wanted_type.casefold()
+                   and r['usage'] == current['usage'] and r['group'] == current['group']
+                   and bool(r['address']) == bool(wanted_address)
+                   and (donor_name is None or r['name'].casefold() == donor_name.casefold())]
+        if not matches or (len({r['tail'] for r in matches}) != 1 and donor_name is None):
+            raise UnsupportedFormat('Type/address-layout change requires an unambiguous compatible native donor')
+        donor = matches[0]
+        require_known_extent(records, donor)
+    cells = [wanted_type, wanted_address, current['initial_value'] if initial_value is None else initial_value,
+             current['name'] if new_name is None else new_name]
+    replacement = encode(donor, cells=cells, handle=current['handle'], row=current['row'])
+    # Preserve the edited variable's translation ID rather than the type donor's.
+    replacement = bytearray(replacement)
+    replacement[-8:-4] = current['tail'][8:12]
+    replacement = bytes(replacement)
+    out = raw[:current['offset']] + replacement + raw[current['end']:]
+    parse(out)
+    return out, dict(handle=current['handle'], row=current['row'], **{'from': name, 'to': cells[3]})
+
+
+def delete(raw, name):
+    records = parse(raw)
+    record = find(records, name)
+    require_known_extent(records, record)
+    out = bytearray(raw[:record['offset']] + raw[record['end']:])
+    struct.pack_into('<I', out, 8, len(records) - 1)
+    parse(bytes(out))
+    return bytes(out), dict(handle=record['handle'], row=record['row'], removed=name)
+
+
+def pair_findings(text, raw):
+    """Report every declaration/worksheet inconsistency instead of raising on the first.
+
+    A project may already carry a record the compiler and the IDE both accept while the two
+    redundant stores disagree, and a vendor-authored project does exactly that. Collecting the
+    findings lets a caller keep working on an unrelated variable while still proving that the
+    edit introduces no new disagreement of its own.
+    """
+    from .variables import parse_declarations
+    findings = []
+    table = parse_declarations(text)
+    if table.warnings or table.duplicates():
+        # The declaration table itself is untrustworthy, so every comparison below would be noise.
+        return ['Declaration parser warnings: ' + '; '.join(table.warnings)]
+    records = parse(raw)
+    expected = {v.name.casefold(): v for v in table.variables}
+    actual = {r['name'].casefold(): r for r in records}
+    if expected.keys() != actual.keys():
+        return [f'Declaration/grid mismatch: text-only={sorted(expected.keys()-actual.keys())}, grid-only={sorted(actual.keys()-expected.keys())}']
+    for name, variable in expected.items():
+        record = actual[name]
+        if variable.type_name.casefold() != record['type'].casefold() or (variable.address or '').casefold() != record['address'].casefold():
+            findings.append(f'Declaration/grid type or address differs for {variable.name}')
+            continue
+        expected_initial = variable.initial_value.strip().upper() if variable.initial_value is not None else None
+        actual_initial = record['initial_value'].strip().upper()
+        primitive_defaults = {'BOOL': {'FALSE', '0'}, 'INT': {'0'}, 'DINT': {'0'}, 'SINT': {'0'},
+                              'UINT': {'0'}, 'UDINT': {'0'}, 'USINT': {'0'}, 'REAL': {'0', '0.0'}, 'LREAL': {'0', '0.0'}}
+        empty_default = not actual_initial and expected_initial in primitive_defaults.get(variable.type_name.upper(), set())
+        if expected_initial is not None and expected_initial != actual_initial and not empty_default:
+            findings.append(f'Declaration/grid initial value differs for {variable.name}')
+        allowed = {'VAR_EXTERNAL': (5,), 'VAR_GLOBAL': (6, 22), 'VAR': (1, 0x40001)}.get(variable.section)
+        if allowed and record['usage'] not in allowed:
+            findings.append(f'Declaration/grid usage differs for {variable.name}')
+    return findings
+
+
+def validate_pair(text, raw):
+    findings = pair_findings(text, raw)
+    if findings:
+        raise UnsupportedFormat(findings[0])
+    records = parse(raw)
+    return {'ok': True, 'variables': len(records), 'trailer_bytes': len(raw) - (records[-1]['end'] if records else 12)}

package/vendor/mwi/code/engine/motionworks_iec_mcp/ide.py

@@ -0,0 +1,317 @@
+"""Detect and close the MotionWorks IEC IDE.
+
+Writing to a project while the IDE has it open is unsafe: the IDE holds project state
+in memory and rewrites whole files on save, so an external edit is either discarded or
+leaves an internally inconsistent project. Every Tier 2 write therefore gates on the
+IDE being closed -- and, when asked, closes it rather than merely refusing.
+
+**Discovery is by window ownership, chosen after two other approaches failed
+measurement here:**
+
+1. ``CreateToolhelp32Snapshot``, the obvious ctypes approach, enumerates only 50 of
+   ~460 processes and **silently omits ``Mwt.exe``**. A safety gate built on it says
+   "the IDE is closed" while the IDE is running, which is the worst failure it can
+   have: a write would then proceed under an open IDE.
+2. Enumerating from a **child process** does not help. This Python process runs in a
+   restricted Job object whose view is truncated, and children inherit it -- a
+   PowerShell script spawned from Python sees the same ~52 processes, while the same
+   script run by hand sees all ~460.
+
+In-process ``EnumWindows`` is not restricted, and the IDE is a GUI application, so it
+always owns windows. Every candidate PID's image name is then **verified** with
+``QueryFullProcessImageNameW`` before it is reported or closed, because acting on an
+unverified PID would mean killing the wrong process.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+#: Executable names that indicate the IDE. Only these block writing.
+MAIN_PROCESSES = ("mwt", "mwt.exe", "mwiec", "motionworks")
+#: Helper processes that can hold the same project files open. They are closed
+#: alongside the IDE and reported, but a bare write gate does not fail on them.
+HELPER_PROCESSES = (
+    "mwcameditor",
+    "yaskawa.plottool",
+    "plc_simulator",
+    # Yaskawa's licence verifier. It owns the "Use Trial" dialog, keeps the
+    # single-instance lock alive while it waits for an answer, and can outlive
+    # Mwt.exe -- which exits while the dialog is still up. Closing MotionWorks
+    # must therefore close this too, or the next launch is blocked.
+    "mwctverify",
+)
+#: Everything the module will detect or close.
+ALL_PROCESSES = MAIN_PROCESSES + HELPER_PROCESSES
+
+
+def _window_owner_pids() -> set:
+    """PIDs that own a top-level window, found in-process via ``EnumWindows``."""
+    if sys.platform != "win32":
+        return set()
+    import ctypes
+    from ctypes import wintypes
+
+    user32 = ctypes.windll.user32
+    pids = set()
+    callback_type = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
+    get_pid = user32.GetWindowThreadProcessId
+    get_pid.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.DWORD)]
+
+    def visit(hwnd, _lparam):
+        pid = wintypes.DWORD()
+        get_pid(hwnd, ctypes.byref(pid))
+        if pid.value:
+            pids.add(pid.value)
+        return True
+
+    try:
+        if not user32.EnumWindows(callback_type(visit), 0):
+            raise RuntimeError('Could not enumerate IDE windows; offline write refused')
+    except Exception as exc:
+        raise RuntimeError('Could not verify that the IDE is closed') from exc
+    return pids
+
+
+def _image_name(pid: int):
+    """The executable name of ``pid``, or None if it cannot be queried."""
+    if sys.platform != "win32":
+        return None
+    import ctypes
+    from ctypes import wintypes
+
+    PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    kernel32 = ctypes.windll.kernel32
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.QueryFullProcessImageNameW.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.LPWSTR, ctypes.POINTER(wintypes.DWORD)]
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+    if not handle:
+        return None
+    try:
+        size = wintypes.DWORD(1024)
+        buffer = ctypes.create_unicode_buffer(size.value)
+        ok = kernel32.QueryFullProcessImageNameW(handle, 0, buffer, ctypes.byref(size))
+        if not ok:
+            return None
+        # Strip the .exe suffix: the process-name lists here are written without it,
+        # and leaving it on silently breaks detection. Measured: "mwctVerify.exe"
+        # failed to match "mwctverify" in HELPER_PROCESSES, so the licence verifier
+        # went unreported even though it owned the window being looked for.
+        name = buffer.value.rsplit(chr(92), 1)[-1]
+        if name.casefold().endswith(".exe"):
+            name = name[:-4]
+        return name
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+def _terminate(pid: int) -> bool:
+    """Terminate a process by PID; True if the call was accepted."""
+    if sys.platform != "win32":
+        return False
+    import ctypes
+
+    PROCESS_TERMINATE = 0x0001
+    SYNCHRONIZE = 0x00100000
+    kernel32 = ctypes.windll.kernel32
+    handle = kernel32.OpenProcess(PROCESS_TERMINATE | SYNCHRONIZE, False, pid)
+    if not handle:
+        return False
+    try:
+        kernel32.TerminateProcess(handle, 1)
+        # Wait, so a caller never proceeds while the process still holds files open.
+        kernel32.WaitForSingleObject(handle, 10_000)
+        return True
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+#: The PowerShell fallback helper, written to a file and invoked with ``-File``:
+#: ``-Command`` with inline script text is mangled by this shell's quoting and
+#: silently returns nothing. Only useful to callers *outside* the restricted job.
+_HELPER = r"""
+param([string]$Out = '')
+
+$names = @('Mwt', 'Mwcameditor', 'Yaskawa.PlotTool', 'plc_simulator')
+$found = @(Get-Process -ErrorAction SilentlyContinue |
+    Where-Object { $names -contains $_.ProcessName })
+$lines = New-Object System.Collections.Generic.List[string]
+foreach ($p in $found) { $lines.Add(("running`t{0}`t{1}" -f $p.Id, $p.ProcessName)) }
+$lines.Add("done`t0`t$($found.Count)")
+if ($Out) { Set-Content -LiteralPath $Out -Value $lines -Encoding ascii } else { $lines }
+"""
+
+
+def _run_helper(timeout_s: float = 20.0):
+    """Run the PowerShell helper; returns ``(kind, pid, name)`` rows."""
+    import subprocess
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as tmp:
+        script = Path(tmp) / "ide_helper.ps1"
+        listing = Path(tmp) / "ide_helper.out"
+        script.write_text(_HELPER, encoding="ascii")
+        try:
+            subprocess.run(
+                [
+                    "powershell.exe",
+                    "-NoLogo",
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-ExecutionPolicy",
+                    "Bypass",
+                    "-File",
+                    str(script),
+                    "-Out",
+                    str(listing),
+                ],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=timeout_s + 120,
+                creationflags=0x08000000,  # CREATE_NO_WINDOW
+            )
+        except Exception:  # noqa: BLE001
+            return []
+        try:
+            text = listing.read_text(encoding="ascii", errors="replace")
+        except OSError:
+            return []
+
+    rows = []
+    for line in text.splitlines():
+        parts = line.split("\t")
+        if len(parts) == 3:
+            rows.append((parts[0], parts[1], parts[2]))
+    return rows
+
+
+def motionworks_running(include_helpers: bool = True):
+    """Return ``(pid, exe_name)`` for running MotionWorks-related processes.
+
+    An empty list means it is safe to write. Only :data:`MAIN_PROCESSES` block
+    writing; the helpers are informational.
+    """
+    if sys.platform != "win32":
+        return []
+    wanted = MAIN_PROCESSES + HELPER_PROCESSES if include_helpers else MAIN_PROCESSES
+    found = []
+    for pid in sorted(_window_owner_pids()):
+        # Verify before reporting: the caller may close these PIDs.
+        name = _image_name(pid)
+        if name and name.casefold() in wanted:
+            found.append((pid, name))
+    return found
+
+
+def ide_blocks_writes():
+    """Return whether the IDE blocks writing, plus the offending processes."""
+    procs = motionworks_running(include_helpers=False)
+    return bool(procs), procs
+
+
+def close_motionworks(timeout: float = 15.0):
+    """Close every running MotionWorks instance and verify it is gone.
+
+    The IDE is asked to quit through COM first, when pywin32 is installed and the
+    automation server is already running, so it can flush its own state. Anything
+    still alive is then terminated by PID. The list is **re-read** afterwards, so
+    ``remaining`` is what is actually still running rather than an assumption -- a
+    caller must not write while it is non-empty.
+    """
+    import time
+
+    if sys.platform != "win32":
+        return {"before": [], "closed": [], "remaining": [], "ok": True}
+
+    before = motionworks_running(include_helpers=True)
+
+    # Ask nicely, if the automation server is reachable. 32-bit pywin32 is an
+    # optional extra, so this is skipped rather than failing when absent.
+    if any(name.casefold() in MAIN_PROCESSES for _, name in before):
+        try:
+            import win32com.client  # type: ignore[import-not-found]
+
+            app = win32com.client.GetActiveObject("Ade.Application.550")
+            app.Quit(0)
+            time.sleep(1.5)
+        except Exception:  # noqa: BLE001 - not installed, or nothing to quit
+            pass
+
+    closed = []
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        still = motionworks_running(include_helpers=True)
+        if not still:
+            break
+        for pid, name in still:
+            if _terminate(pid):
+                closed.append((pid, name))
+        time.sleep(0.4)
+
+    remaining = motionworks_running(include_helpers=True)
+    return {
+        "before": before,
+        "closed": closed,
+        "remaining": remaining,
+        "ok": not remaining,
+    }
+
+
+def auto_close_enabled() -> bool:
+    """Whether write tools should close the IDE themselves.
+
+    Controlled by ``MOTIONWORKS_MCP_CLOSE_IDE``: ``1``/``true``/``yes``/``on`` means
+    a write closes a running IDE and proceeds rather than refusing. Off by default,
+    because silently closing an application the user may be working in is not a
+    decision to make on their behalf.
+    """
+    import os
+
+    value = os.environ.get("MOTIONWORKS_MCP_CLOSE_IDE", "")
+    return value.strip().casefold() in {"1", "true", "yes", "on"}
+
+
+def ensure_ide_closed(auto_close: bool | None = None, timeout: float = 15.0):
+    """Raise :class:`IdeRunning` unless the IDE is closed, closing it if configured.
+
+    Every write path calls this instead of inspecting processes itself, so the
+    close-or-refuse policy lives in exactly one place.
+
+    Args:
+        auto_close: Override the environment setting; ``None`` uses
+            :func:`auto_close_enabled`.
+        timeout: How long to wait for the IDE to exit when closing it.
+    """
+    from .errors import IdeRunning
+
+    if sys.platform != "win32":
+        return
+    # Project identity can only be verified by the bridge close tool.
+    auto_close = False
+    procs = require_ide_closed(auto_close=auto_close, timeout=timeout)
+    if procs:
+        described = ", ".join(f"{name} (pid {pid})" for pid, name in procs)
+        raise IdeRunning(
+            f"MotionWorks is running ({described}), so nothing was written. Close "
+            f"MotionWorks IEC through the guarded mw_ide_close tool and retry."
+        )
+
+
+def require_ide_closed(auto_close: bool = False, timeout: float = 15.0):
+    """Ensure the IDE is closed, closing it first when asked.
+
+    Returns the processes *still* running (empty means safe to write). With
+    ``auto_close`` the IDE is shut down when found; without it this only reports, so
+    a caller can refuse and tell the user to close it.
+    """
+    blocking, procs = ide_blocks_writes()
+    if not blocking:
+        return []
+    if not auto_close:
+        return procs
+    close_motionworks(timeout=timeout)
+    _, procs = ide_blocks_writes()
+    return procs