sylo-allen-bradley 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yeti-Trix <131923258+Yeti-Trix@users.noreply.github.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# sylo-allen-bradley
+
+Sylo package: **Studio 5000 Logix Designer SDK wrapper** — controller
+upload/download and `.acd`↔L5X export/import (`allen_bradley_sdk_*` tools).
+**The SDK itself is not bundled and cannot be redistributed** — it ships with
+the licensed Studio 5000 v36+ installation (Windows, Python 3.12 only) and
+requires a valid Studio 5000 license.
+
+Split out of the old monolith on 2026-09-09:
+
+- **`sylo-plc-comms`** — CIP/OPC UA tag tools (`plc_comms_*`). No SDK required.
+- **`sylo-logicforge`** — L5X parse/review/IO-scaffold, Parse Rules UI, bundled LogicForge backend, canonical download allowlist.
+- This package — SDK tools only: `allen_bradley_sdk_upload_from_plc`, `allen_bradley_sdk_download_to_plc`, `allen_bradley_sdk_export_l5x`, `allen_bradley_sdk_import_l5x`.
+
+## Logix Designer SDK wheel (not bundled)
+
+The Rockwell-proprietary `logix_designer_sdk` Python wheel ships with your own
+licensed Studio 5000 v36+ install. Resolution order (`scripts/_sdk_paths.py`):
+
+1. `LOGIX_DESIGNER_SDK_WHEEL` environment variable — explicit wheel path
+2. `LOGIX_DESIGNER_SDK_SITE` — unpacked SDK tree
+3. A wheel dropped under `packages/sylo-logicforge/vendor/logicforge/` (local only, not committed)
+4. Legacy sibling checkout (`~/Documents/GitHub/sylo-allen-bradley/`)
+5. `LOGICFORGE_SOURCE` dev-checkout overlay
+6. Rockwell install locations (`C:\Program Files (x86)\Rockwell Software\...`)
+
+Without the SDK the package still loads — only the direct `.acd` operations
+report that the SDK is missing. Use `sylo-plc-comms` for live tag reads/writes
+(no SDK) and `sylo-logicforge` for L5X parse/IO-scaffold work.
+
+## Downloads are allowlist-gated
+
+`allen_bradley_sdk_download_to_plc` is the only tool that writes to a live
+controller project. It is hard-gated by the operator-managed allowlist whose
+canonical file lives in `sylo-logicforge`
+(`packages/sylo-logicforge/assets/download-allowlist.json`) — the agent cannot
+download to any IP not present and enabled there.

package/extensions/index.ts

@@ -0,0 +1,299 @@
+/**
+ * sylo-allen-bradley — Studio 5000 Logix Designer SDK wrapper.
+ *
+ * Controller upload/download and .acd ↔ L5X export/import via the Rockwell
+ * Logix Designer SDK. The SDK itself is NOT bundled — it ships with the
+ * licensed Studio 5000 v36+ install (wheel via LOGIX_DESIGNER_SDK_WHEEL /
+ * LOGIX_DESIGNER_SDK_SITE / vendor drop-spot). Split out of the old
+ * sylo-allen-bradley monolith on 2026-09-09: PLC comms moved to
+ * sylo-plc-comms, L5X parse/IO-scaffold to sylo-logicforge.
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+
+const execFileAsync = promisify(execFile)
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const SCRIPTS_DIR = path.join(PACKAGE_ROOT, 'scripts')
+
+type ToolContentBlock = { type: 'text'; text: string }
+
+// All registered tools are SDK-backed — run them on the SDK Python (3.12) so
+// logix_designer_sdk imports (SYLO_SDK_PYTHON / py -3.12 on Windows).
+const SDK_SCRIPTS = new Set([
+  'sdk_export_l5x.py',
+  'sdk_import_l5x.py',
+  'sdk_upload_from_plc.py',
+  'sdk_download_to_plc.py',
+])
+
+function resolvePythonInvocation(sdk = false): { command: string; prefixArgs: string[] } {
+  if (sdk) {
+    const sdkPython = process.env.SYLO_SDK_PYTHON?.trim()
+    if (sdkPython) {
+      return { command: sdkPython, prefixArgs: [] }
+    }
+    if (process.platform === 'win32') {
+      return { command: 'py', prefixArgs: ['-3.12'] }
+    }
+  }
+
+  const envPython = process.env.SYLO_PYTHON?.trim()
+  if (envPython) {
+    return { command: envPython, prefixArgs: [] }
+  }
+  return { command: process.platform === 'win32' ? 'python' : 'python3', prefixArgs: [] }
+}
+
+function toolError(text: string): { content: ToolContentBlock[] } {
+  return { content: [{ type: 'text', text }] }
+}
+
+/**
+ * Scripts emit JSON as the last thing on stdout, but the Logix Designer SDK's
+ * StdOutEventLogger can print INFO lines before it. Parse the trailing JSON
+ * object instead of assuming the whole stream is JSON.
+ */
+function parseTrailingJson(stdout: string): Record<string, unknown> | null {
+  const trimmed = stdout.trim()
+  if (!trimmed) return null
+  try {
+    return JSON.parse(trimmed) as Record<string, unknown>
+  } catch {
+    /* fall through — find last JSON object in mixed output */
+  }
+  let idx = trimmed.lastIndexOf('\n{')
+  while (idx >= 0) {
+    const candidate = trimmed.slice(idx + 1)
+    try {
+      return JSON.parse(candidate) as Record<string, unknown>
+    } catch {
+      idx = trimmed.lastIndexOf('\n{', idx - 1)
+    }
+  }
+  return null
+}
+
+function tail(text: string, lines = 12): string {
+  return text.trim().split('\n').slice(-lines).join('\n').trim()
+}
+
+type ExecOutput = { stdout: string; stderr: string }
+
+async function execScript(
+  scriptName: string,
+  args: string[],
+  timeoutMs: number,
+): Promise<ExecOutput> {
+  const scriptPath = path.join(SCRIPTS_DIR, scriptName)
+  const { command, prefixArgs } = resolvePythonInvocation(SDK_SCRIPTS.has(scriptName))
+  const sdk = SDK_SCRIPTS.has(scriptName)
+  return execFileAsync(command, [...prefixArgs, scriptPath, ...args], {
+    cwd: PACKAGE_ROOT,
+    maxBuffer: 32 * 1024 * 1024,
+    windowsHide: true,
+    timeout: timeoutMs,
+    env: {
+      ...process.env,
+      ...(sdk && process.platform === 'win32' && !process.env.SYLO_PYTHON
+        ? { PYTHONIOENCODING: 'utf-8' }
+        : {}),
+    },
+  })
+}
+
+async function runPythonScript(
+  scriptName: string,
+  args: string[],
+  timeoutMs = 120_000,
+): Promise<{ content: ToolContentBlock[] }> {
+  try {
+    const { stdout, stderr } = await execScript(scriptName, args, timeoutMs)
+    const parsed = parseTrailingJson(stdout) as
+      | { ok?: boolean; error?: string; operator_chat?: string }
+      | null
+    if (!parsed) {
+      return toolError(tail(stdout) || stderr.trim() || `${scriptName} produced no output`)
+    }
+    if (parsed.ok === false) {
+      return toolError(parsed.error ?? `${scriptName} failed`)
+    }
+    if (typeof parsed.operator_chat === 'string' && parsed.operator_chat.trim()) {
+      return { content: [{ type: 'text', text: parsed.operator_chat.trim() }] }
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }] }
+  } catch (err) {
+    // Non-zero exit: scripts print {"ok": false, "error": ...} before exiting 1 —
+    // surface that instead of Node's generic "Command failed" message.
+    const e = err as NodeJS.ErrnoException & { stdout?: string; stderr?: string }
+    const parsed = typeof e.stdout === 'string' ? parseTrailingJson(e.stdout) : null
+    if (parsed && typeof parsed.error === 'string' && parsed.error.trim()) {
+      return toolError(parsed.error.trim())
+    }
+    const detail = [
+      typeof e.stdout === 'string' ? tail(e.stdout) : '',
+      typeof e.stderr === 'string' ? tail(e.stderr) : '',
+    ]
+      .filter(Boolean)
+      .join('\n')
+    const message = err instanceof Error ? err.message : String(err)
+    return toolError(detail ? `${message}\n${detail}` : message)
+  }
+}
+
+export default function syloAllenBradleySdkExtension(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: 'allen_bradley_sdk_upload_from_plc',
+    label: 'Allen-Bradley SDK upload from PLC',
+    description:
+      'Windows + Logix Designer SDK: pull the controller project into a new offline `.acd` (Rockwell "upload"). ' +
+      'Pass controller `ip` or full `comm_path`. Saves to `output_path` and/or creates a run folder. ' +
+      'Read-only toward the PLC — there is no upload-to-PLC risk; downloads are separate. ' +
+      'Follow with allen_bradley_sdk_export_l5x to read logic.',
+    parameters: Type.Object({
+      ip: Type.Optional(
+        Type.String({ description: 'Controller IPv4 address (e.g. 192.168.1.10)' }),
+      ),
+      comm_path: Type.Optional(
+        Type.String({
+          description:
+            'Full Rockwell communications path (overrides ip), e.g. AB_ETHIP-1\\10.0.0.1\\Backplane\\0',
+        }),
+      ),
+      output_path: Type.Optional(Type.String({ description: 'Output .acd file path' })),
+      run_dir: Type.Optional(Type.String({ description: 'Existing run folder from logicforge_run_prepare' })),
+      project_dir: Type.Optional(
+        Type.String({ description: 'Create runs/<run-id>/ and save working/<PLC_*.acd>' }),
+      ),
+      run_id: Type.Optional(Type.String({ description: 'Run id when using project_dir' })),
+    }),
+    async execute(_toolCallId, params) {
+      const ip = String(params.ip ?? '').trim()
+      const commPath = String(params.comm_path ?? '').trim()
+      if (!ip && !commPath) {
+        return toolError('allen_bradley_sdk_upload_from_plc requires ip and/or comm_path.')
+      }
+      const args: string[] = []
+      if (ip) args.push('--ip', ip)
+      if (commPath) args.push('--comm-path', commPath)
+      const output = String(params.output_path ?? '').trim()
+      const runDir = String(params.run_dir ?? '').trim()
+      const projectDir = String(params.project_dir ?? '').trim()
+      const runId = String(params.run_id ?? '').trim()
+      if (output) args.push('--output', output)
+      if (runDir) args.push('--run-dir', runDir)
+      if (projectDir) args.push('--project-dir', projectDir)
+      if (runId) args.push('--run-id', runId)
+      if (!output && !runDir && !projectDir) {
+        return toolError(
+          'allen_bradley_sdk_upload_from_plc requires output_path, run_dir, and/or project_dir for the saved .acd.',
+        )
+      }
+      return runPythonScript('sdk_upload_from_plc.py', args, 600_000)
+    },
+  })
+
+  pi.registerTool({
+    name: 'allen_bradley_sdk_download_to_plc',
+    label: 'Allen-Bradley SDK download to PLC',
+    description:
+      'Windows + Logix Designer SDK: push the working .acd project to a controller (Rockwell "download"). ' +
+      'GATED by the operator-managed download allowlist — the agent cannot download to any IP not present ' +
+      'and enabled there, even with operator permission, and cannot edit the allowlist. ' +
+      'Auto-switches the controller to Program mode first if the key is in REM; refuses if the key is in hard RUN. ' +
+      'Leaves the controller in the configured post_download_mode (Program or Run) when the key is in REM.',
+    parameters: Type.Object({
+      ip: Type.Optional(
+        Type.String({ description: 'Controller IPv4 address — must be in the download allowlist' }),
+      ),
+      comm_path: Type.Optional(
+        Type.String({
+          description:
+            'Full Rockwell communications path (overrides ip), e.g. AB_ETHIP-1\\10.0.0.1\\Backplane\\0',
+        }),
+      ),
+      acd_path: Type.Optional(Type.String({ description: 'Working .acd to push (or use run_dir)' })),
+      run_dir: Type.Optional(
+        Type.String({ description: 'Run folder from logicforge_run_prepare (uses working/*.dev.acd)' }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const ip = String(params.ip ?? '').trim()
+      const commPath = String(params.comm_path ?? '').trim()
+      if (!ip && !commPath) {
+        return toolError('allen_bradley_sdk_download_to_plc requires ip and/or comm_path.')
+      }
+      const args: string[] = []
+      if (ip) args.push('--ip', ip)
+      if (commPath) args.push('--comm-path', commPath)
+      const acd = String(params.acd_path ?? '').trim()
+      const runDir = String(params.run_dir ?? '').trim()
+      if (acd) args.push('--acd', acd)
+      if (runDir) args.push('--run-dir', runDir)
+      if (!acd && !runDir) {
+        return toolError('allen_bradley_sdk_download_to_plc requires acd_path and/or run_dir.')
+      }
+      return runPythonScript('sdk_download_to_plc.py', args, 600_000)
+    },
+  })
+
+  pi.registerTool({
+    name: 'allen_bradley_sdk_export_l5x',
+    label: 'Allen-Bradley SDK export ACD to L5X',
+    description:
+      'Windows + Logix Designer SDK: export `.acd` → `.L5X` (save_as, detailed_l5x) so the agent can read and edit project logic as XML. Pass run_dir or acd + output paths. Set LOGIX_DESIGNER_SDK_WHEEL if import fails. Parse the export with logicforge_parse_l5x (sylo-logicforge).',
+    parameters: Type.Object({
+      acd_path: Type.Optional(Type.String({ description: 'Path to .acd (or use run_dir working copy)' })),
+      output_path: Type.Optional(Type.String({ description: 'Output .l5x; default run_dir/exports/iter-0/controller.l5x' })),
+      run_dir: Type.Optional(Type.String({ description: 'Run folder from logicforge_run_prepare' })),
+      detailed_l5x: Type.Optional(Type.Boolean({ description: 'Default true' })),
+    }),
+    async execute(_toolCallId, params) {
+      const args: string[] = []
+      const acd = String(params.acd_path ?? '').trim()
+      const output = String(params.output_path ?? '').trim()
+      const runDir = String(params.run_dir ?? '').trim()
+      if (acd) args.push('--acd', acd)
+      if (output) args.push('--output', output)
+      if (runDir) args.push('--run-dir', runDir)
+      if (params.detailed_l5x === false) args.push('--no-detailed-l5x')
+      if (!acd && !runDir) {
+        return toolError('allen_bradley_sdk_export_l5x requires acd_path and/or run_dir.')
+      }
+      return runPythonScript('sdk_export_l5x.py', args, 300_000)
+    },
+  })
+
+  pi.registerTool({
+    name: 'allen_bradley_sdk_import_l5x',
+    label: 'Allen-Bradley SDK partial import L5X',
+    description:
+      'Windows + Logix Designer SDK: partial_import_from_xml_file — merge an L5X fragment (tags, routines, modules, etc.) into `.acd`. Default XPath Controller/Tags; use scoped XPath for programs/routines.',
+    parameters: Type.Object({
+      l5x_path: Type.String({ description: 'L5X fragment path' }),
+      run_dir: Type.Optional(Type.String({ description: 'Run folder (uses the working .acd copy)' })),
+      acd_path: Type.Optional(Type.String({ description: 'Target .acd (overrides run_dir working copy)' })),
+      xpath: Type.Optional(Type.String({ description: 'Default Controller/Tags' })),
+    }),
+    async execute(_toolCallId, params) {
+      const l5x = String(params.l5x_path ?? '').trim()
+      if (!l5x) return toolError('allen_bradley_sdk_import_l5x requires l5x_path.')
+      const args = ['--l5x', l5x]
+      const runDir = String(params.run_dir ?? '').trim()
+      const acd = String(params.acd_path ?? '').trim()
+      const xpath = String(params.xpath ?? '').trim()
+      if (runDir) args.push('--run-dir', runDir)
+      if (acd) args.push('--acd', acd)
+      if (xpath) args.push('--xpath', xpath)
+      if (!runDir && !acd) {
+        return toolError('allen_bradley_sdk_import_l5x requires run_dir and/or acd_path.')
+      }
+      return runPythonScript('sdk_import_l5x.py', args, 300_000)
+    },
+  })
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "sylo-allen-bradley",
+  "version": "0.1.0",
+  "description": "Studio 5000 Logix Designer SDK wrapper — controller upload/download and ACD↔L5X export/import. The SDK itself is not bundled (operator-licensed wheel); PLC comms live in sylo-plc-comms, L5X parse/IO scaffold in sylo-logicforge.",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "extensions",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {},
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2"
+  },
+  "dependencies": {
+    "typebox": "^1.1.24"
+  },
+  "license": "MIT"
+}

package/scripts/_download_allowlist.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Shared download-allowlist loader / membership gate.
+
+The canonical allowlist lives at packages/sylo-logicforge/assets/download-allowlist.json
+and is operator-managed via the LogicForge Settings tab. The agent never edits
+it — the download script reads it and refuses any IP not present and enabled.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def package_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def allowlist_path() -> Path:
+    """Allowlist JSON path (env override for project-local testing)."""
+    env = os.environ.get("LOGICFORGE_DOWNLOAD_ALLOWLIST", "").strip()
+    if env:
+        return Path(env).expanduser().resolve()
+    # Canonical file lives with sylo-logicforge (the LogicForge Settings tab
+    # reads/writes it there); resolve across the monorepo so every package
+    # enforces the same operator list.
+    sibling = (
+        Path(__file__).resolve().parents[2]
+        / "sylo-logicforge"
+        / "assets"
+        / "download-allowlist.json"
+    )
+    if sibling.is_file():
+        return sibling
+    return package_root() / "assets" / "download-allowlist.json"
+
+
+def default_allowlist() -> dict[str, Any]:
+    return {
+        "allow_downloads": False,
+        "post_download_mode": "program",
+        "ips": [],
+        "updated_at": None,
+        "notes": "Operator-managed via LogicForge Settings tab.",
+    }
+
+
+def load_allowlist() -> dict[str, Any]:
+    path = allowlist_path()
+    if not path.is_file():
+        return default_allowlist()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return default_allowlist()
+    if not isinstance(data, dict):
+        return default_allowlist()
+    # Normalize / fill missing keys
+    base = default_allowlist()
+    base.update(data)
+    if not isinstance(base.get("ips"), list):
+        base["ips"] = []
+    if base.get("post_download_mode") not in ("program", "run"):
+        base["post_download_mode"] = "program"
+    return base
+
+
+def save_allowlist(data: dict[str, Any]) -> dict[str, Any]:
+    path = allowlist_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = dict(data)
+    data["updated_at"] = datetime.now(timezone.utc).isoformat()
+    if data.get("post_download_mode") not in ("program", "run"):
+        data["post_download_mode"] = "program"
+    if not isinstance(data.get("ips"), list):
+        data["ips"] = []
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return data
+
+
+def _ip_from_comm_path(comm_path: str) -> str | None:
+    """Extract a bare IPv4 from a Rockwell comm path, else None."""
+    import re
+
+    raw = comm_path.strip()
+    # Look for an IPv4 anywhere in the path
+    m = re.search(r"\b\d{1,3}(?:\.\d{1,3}){3}\b", raw)
+    return m.group(0) if m else None
+
+
+def check_ip_allowed(ip_or_comm: str, allowlist: dict[str, Any] | None = None) -> tuple[bool, str]:
+    """Return (allowed, reason). Resolves bare IP from a comm path if needed."""
+    al = allowlist if allowlist is not None else load_allowlist()
+    if not al.get("allow_downloads", False):
+        return False, "Downloads are disabled in the allowlist (allow_downloads=false)."
+
+    ip = ip_or_comm.strip()
+    if "\\" in ip or "/" in ip:
+        ip = _ip_from_comm_path(ip) or ip
+
+    for entry in al.get("ips", []):
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("ip") == ip:
+            if entry.get("enabled", True):
+                return True, ip
+            return False, f"IP {ip} is in the allowlist but disabled."
+    return False, f"IP {ip} is not in the download allowlist. The agent cannot download to it."

package/scripts/_json_out.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Shared JSON stdout helpers for sylo-allen-bradley (SDK) scripts."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def emit(payload: dict[str, Any]) -> None:
+    """Print JSON to stdout and exit with code 0 or 1."""
+    print(json.dumps(payload, indent=2))
+    if payload.get("ok") is False:
+        sys.exit(1)
+
+
+def emit_error(message: str, **extra: Any) -> None:
+    emit({"ok": False, "error": message, **extra})

package/scripts/_run_yaml.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Read/write run.yaml (YAML if PyYAML installed, else JSON)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _parse_simple_yaml(raw: str) -> dict:
+    out: dict = {}
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if ":" not in stripped:
+            continue
+        key, value = stripped.split(":", 1)
+        out[key.strip()] = value.strip().strip("'\"")
+    return out
+
+
+def read_run_yaml(run_dir: Path) -> dict:
+    path = run_dir / "run.yaml"
+    if not path.is_file():
+        return {}
+    raw = path.read_text(encoding="utf-8")
+    try:
+        import yaml  # type: ignore
+
+        data = yaml.safe_load(raw)
+        return data if isinstance(data, dict) else {}
+    except ImportError:
+        pass
+    except Exception:
+        pass
+    try:
+        data = json.loads(raw)
+        return data if isinstance(data, dict) else {}
+    except json.JSONDecodeError:
+        return _parse_simple_yaml(raw)
+
+
+def find_working_acd(run_dir: Path) -> Path | None:
+    """Working ACD for a run: run.yaml working_acd → working/*.acd → legacy working/project.acd."""
+    data = read_run_yaml(run_dir)
+    recorded = data.get("working_acd")
+    if isinstance(recorded, str) and recorded.strip():
+        p = Path(recorded).expanduser()
+        if p.is_file():
+            return p.resolve()
+    working = run_dir / "working"
+    if working.is_dir():
+        acds = sorted(p for p in working.iterdir() if p.is_file() and p.suffix.lower() == ".acd")
+        if len(acds) == 1:
+            return acds[0].resolve()
+        legacy = working / "project.acd"
+        if legacy.is_file():
+            return legacy.resolve()
+        if acds:
+            dev = [p for p in acds if p.stem.lower().endswith(".dev")]
+            if len(dev) == 1:
+                return dev[0].resolve()
+    return None
+
+
+def write_run_yaml(run_dir: Path, patch: dict) -> None:
+    path = run_dir / "run.yaml"
+    data = read_run_yaml(run_dir)
+    data.update(patch)
+    try:
+        import yaml  # type: ignore
+
+        path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+    except ImportError:
+        path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")

package/scripts/_sdk_import.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Shared Logix Designer SDK partial import helper."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from pathlib import Path
+
+
+def sdk_logs_to_stderr():
+    """Route SDK StdOutEventLogger output to stderr so stdout stays clean JSON."""
+    return contextlib.redirect_stdout(sys.stderr)
+
+
+async def partial_import_from_l5x(acd_path: Path, xpath: str, fragment_path: Path) -> None:
+    from logix_designer_sdk import ImportCollisionOptions, LogixProject, StdOutEventLogger
+
+    with sdk_logs_to_stderr():
+        project = await LogixProject.open_logix_project(str(acd_path), StdOutEventLogger())
+        await project.partial_import_from_xml_file(
+            xpath,
+            str(fragment_path),
+            ImportCollisionOptions.OVERWRITE_ON_COLL,
+        )
+        await project.save()