@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/l5x/lib/tools/studio.js

@@ -0,0 +1,193 @@
+/**
+ * The online-supervised entry's offline half: SDK status, ACD export, L5X
+ * verification, routine build into a new ACD, and review-evidence checking.
+ *
+ * No tool here contacts a controller. Upload, mode change and download belong
+ * to the controller tools, which require per-call human approval and are not
+ * part of this entry yet.
+ *
+ * @module dsh-engineering-l5x/tools/studio
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { L5xError } from "../core/errors.js";
+import { success } from "../core/result.js";
+import { object, string } from "../core/params.js";
+import { editOfflineAcd, exportAcdToL5x, studioSdkStatus, verifyOfflineL5x, } from "../engine/studio-sdk.js";
+import { engineeringCapabilities } from "../engine/capabilities.js";
+import { routineEditPlan } from "../engine/acd-edit.js";
+import { reviewDownloadSource } from "../engine/download-review.js";
+import { verifyReviewEvidence } from "../engine/review-evidence.js";
+import { PROJECT_ID, optionalString, requiredString, tool } from "./common.js";
+/** Build verdicts come from Studio, not from this plugin. */
+const STUDIO_COVERAGE = {
+    complete: false,
+    unverified: [
+        'the build verdict is Studio 5000\'s; this plugin reports it',
+        'runtime behavior',
+        'controller state and online logic',
+    ],
+};
+/**
+ * The studio tools, bound to one chat's projects and export provenance.
+ *
+ * @param session - Project handles for the calling chat.
+ * @param state - ACD export records for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export function studioTools(session, state) {
+    return [
+        tool({
+            name: 'studio_sdk_status',
+            description: 'Preflight the Logix Designer SDK service, FactoryTalk Linx services, SDK package, .NET and installed Studio versions. Call before any SDK tool; no project or controller operation.',
+            parameters: object({}),
+            async run(_args, _exec) {
+                const status = await studioSdkStatus();
+                return success(status.available ? 'The Studio 5000 SDK is available for offline work.' : `The Studio 5000 SDK is unavailable: ${status.reason}`, status, status.available ? [{ tool: 'studio_capabilities', why: 'See what this SDK release can do for the open project.' }] : [], STUDIO_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'studio_capabilities',
+            description: 'Report offline, SDK, revision-specific build, reference and live-read capabilities with next steps. Optional project_id checks the selected revision; no controller contact.',
+            parameters: object({ project_id: PROJECT_ID }, []),
+            async run(args, exec) {
+                const status = await studioSdkStatus();
+                const projectArg = optionalString(args, 'project_id');
+                const project = projectArg === undefined ? undefined : await session.require(projectArg, exec);
+                return success(`Studio capabilities for ${project?.document.controller.name ?? 'this machine'}.`, engineeringCapabilities(status, project), [{ tool: 'studio_sdk_status', why: 'Inspect the SDK services in detail.' }], STUDIO_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'export_acd_to_l5x',
+            description: 'Export one existing offline ACD to a new full L5X with the running Logix Designer SDK service. No controller connection or upload; refuses to overwrite.',
+            parameters: object({
+                acd_path: string('Existing offline ACD. Example: "C:/Projects/Line/Line.ACD".'),
+                output_path: string('New .L5X path to write. It must not exist.'),
+            }, ['acd_path', 'output_path']),
+            async run(args, exec) {
+                const acdPath = await session.resolvePath(requiredString(args, 'acd_path'), exec);
+                const outputPath = await session.resolvePath(requiredString(args, 'output_path'), exec);
+                const result = await exportAcdToL5x(acdPath, outputPath, exec.signal);
+                state.record(exec, {
+                    acdPath: result.source_acd,
+                    l5xPath: result.output_path,
+                    acdSha256: result.source_sha256,
+                    l5xSha256: result.output_sha256,
+                });
+                return success(`Exported ${result.source_acd} to ${result.output_path}.`, result, [{ tool: 'open_project', args: { path: result.output_path }, why: 'Open the exported L5X to read it.' }], STUDIO_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'verify_offline_l5x',
+            description: 'Import a full L5X into a new offline ACD and build it with the Studio SDK. Build needs project revision 37+; probe=true attempts a lower revision and reports the SDK error. No controller operation.',
+            parameters: object({
+                project_id: PROJECT_ID,
+                baseline_id: string('Project handle of the unchanged baseline export this draft came from. Example: "3f2c...".'),
+                output_path: string('New .ACD path to write. It must not exist.'),
+                probe: { type: 'boolean', default: false, description: 'Attempt the build on a revision below 37 and report the SDK error instead of refusing early.' },
+            }, ['baseline_id', 'output_path']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const baseline = await session.require(requiredString(args, 'baseline_id'), exec);
+                const review = reviewDownloadSource(baseline, project);
+                const captured = state.forL5x(exec, baseline.path);
+                const baselineVerified = captured?.l5xSha256 === baseline.sha256;
+                const outputPath = await session.resolvePath(requiredString(args, 'output_path'), exec);
+                const build = await verifyOfflineL5x(project, outputPath, exec.signal, { probeBuild: args.probe === true });
+                const blockers = [
+                    ...review.blockers,
+                    ...(baselineVerified ? [] : ['Baseline is not an L5X exported from an ACD in this chat']),
+                ];
+                const eligible = build.offline_build === 'passed' && blockers.length === 0 && build.output_path !== null && build.output_sha256 !== null;
+                const verificationId = eligible ? randomUUID() : null;
+                if (verificationId !== null) {
+                    state.addVerified(exec, verificationId, {
+                        path: build.output_path,
+                        sha256: build.output_sha256,
+                        baselinePath: baseline.path,
+                        sourcePath: project.path,
+                        review: { baseline_sha256: review.baseline_sha256, source_sha256: review.source_sha256 },
+                    });
+                }
+                return success(`Offline build ${build.offline_build}; ${blockers.length} blocker(s).`, {
+                    ...build,
+                    baseline_sha256: baseline.sha256,
+                    baseline_acd_sha256: captured?.acdSha256 ?? null,
+                    change_count: review.change_count,
+                    change_summary: review.changes.slice(0, 30).map(change => ({ kind: change.kind, component: change.component, key: change.key })),
+                    safety_changed: review.safety_changed,
+                    blockers,
+                    download_ready: eligible,
+                    verification_id: verificationId,
+                }, [], STUDIO_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'build_acd_from_draft',
+            description: 'Import one changed existing RLL or ST routine into a NEW offline ACD copy, build it, export it, and check preservation. No controller connection; requires the original ACD and a baseline exported in this chat.',
+            parameters: object({
+                acd_path: string('Original offline ACD the baseline was exported from.'),
+                baseline_id: string('Project handle of the unchanged baseline export.'),
+                project_id: PROJECT_ID,
+                program: string('Program that owns the changed routine. Example: "MainProgram".'),
+                routine: string('Routine whose edited logic is imported. Example: "MainRoutine".'),
+                output_path: string('New .ACD path to write. It must not exist.'),
+                result_export_path: string('New .L5X path for the built ACD export. It must not exist.'),
+            }, ['acd_path', 'baseline_id', 'program', 'routine', 'output_path', 'result_export_path']),
+            async run(args, exec) {
+                const baseline = await session.require(requiredString(args, 'baseline_id'), exec);
+                const draft = await session.require(optionalString(args, 'project_id'), exec);
+                const program = requiredString(args, 'program');
+                const routine = requiredString(args, 'routine');
+                routineEditPlan(baseline, draft, program, routine);
+                const acdPath = await session.resolvePath(requiredString(args, 'acd_path'), exec);
+                const acdSha256 = createHash('sha256').update(await readFile(acdPath)).digest('hex');
+                const captured = state.forL5x(exec, baseline.path);
+                if (captured?.acdSha256 !== acdSha256 || captured.l5xSha256 !== baseline.sha256) {
+                    throw new L5xError('BASELINE_MISMATCH', 'The baseline was not exported from this ACD in this chat, or either file has changed since.', 'Export the source ACD with export_acd_to_l5x, open that exact L5X, and keep both files unchanged.');
+                }
+                const outputPath = await session.resolvePath(requiredString(args, 'output_path'), exec);
+                const exportPath = await session.resolvePath(requiredString(args, 'result_export_path'), exec);
+                const build = await editOfflineAcd(acdPath, draft, program, routine, outputPath, exportPath, exec.signal);
+                const review = reviewDownloadSource(baseline, draft);
+                const passed = build.offline_build === 'passed' && build.result_export_path !== null && build.output_path !== null && build.output_sha256 !== null;
+                const eligible = passed && review.blockers.length === 0;
+                const verificationId = eligible ? randomUUID() : null;
+                if (verificationId !== null) {
+                    state.addVerified(exec, verificationId, {
+                        path: build.output_path,
+                        sha256: build.output_sha256,
+                        baselinePath: baseline.path,
+                        sourcePath: draft.path,
+                        review: { baseline_sha256: review.baseline_sha256, source_sha256: review.source_sha256 },
+                    });
+                }
+                return success(`Offline ACD build ${build.offline_build}${build.failure_stage === null ? '' : ` at ${build.failure_stage}`}.`, {
+                    ...build,
+                    change_count: review.change_count,
+                    blockers: review.blockers,
+                    download_ready: eligible,
+                    verification_id: verificationId,
+                    controller_operation: 'none',
+                    next_step: eligible
+                        ? 'Download the built ACD with download_project and its verification_id after per-call approval.'
+                        : passed
+                            ? 'Read the review blockers; the build is not eligible for download.'
+                            : 'Read the build log; the source ACD was preserved and a failed output is not verified.',
+                }, [], STUDIO_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'studio_review_evidence',
+            description: 'Before reporting Studio findings, verify exact program, routine and rung or ST line names with verbatim quotes. Does not verify interpretation or runtime behavior.',
+            parameters: object({
+                project_id: PROJECT_ID,
+                citations: string('Citations to verify, one per line or as JSON. Example: "MainProgram/MainRoutine rung 4: XIC(Start)OTE(Run);"'),
+            }, ['citations']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                return success('Review evidence checked against the export.', verifyReviewEvidence(project, requiredString(args, 'citations')), [], STUDIO_COVERAGE);
+            },
+        }),
+    ];
+}

package/vendor/l5x/poll-worker.mjs

@@ -0,0 +1,77 @@
+/** Isolated, read-only EtherNet/IP sampler. Parent owns deadlines and awaited termination. */
+import { isMainThread, parentPort, workerData } from 'node:worker_threads'
+import { setTimeout as delay } from 'node:timers/promises'
+import { performance } from 'node:perf_hooks'
+import ethernetIp from 'st-ethernet-ip'
+import { isIPv4 } from 'node:net'
+
+/**
+ * Sample explicit scalar tags without SDK discovery, subscriptions, or writes.
+ * @param {object} spec Validated worker request.
+ * @param {(frame: object) => void} emit Frame sink.
+ * @returns {Promise<void>} Completion after connection cleanup.
+ */
+export async function collect(spec, emit) {
+  if (!spec || typeof spec.ip !== 'string' || !isIPv4(spec.ip) || !Number.isInteger(spec.slot) || spec.slot < 0 || spec.slot > 31
+    || !Array.isArray(spec.tags) || spec.tags.length < 1 || spec.tags.length > 256
+    || !Number.isInteger(spec.samples) || spec.samples < 1 || spec.samples > 100000
+    || !Number.isInteger(spec.interval) || spec.interval < 1
+    || !Number.isInteger(spec.timeout) || spec.timeout < 1)
+    throw new Error('Invalid polling worker request')
+  const plc = new ethernetIp.Controller(false)
+  plc.timeout_sp = spec.timeout
+  // The worker lifetime bounds the driver's internal timers and sockets.
+  plc.on('error', error => { void error /* Driver requests report transport failures; prevent an unhandled socket event. */ })
+  try {
+    await plc.connect(spec.ip, spec.slot, false)
+    await plc.readControllerProps()
+    emit({ type: 'identity', controller: {
+      product_name: plc.properties.name, serial_number: plc.properties.serial_number,
+      revision: plc.properties.version, status: plc.properties.status,
+    } })
+    const tags = spec.tags.map(entry => {
+      if (!entry || typeof entry.name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.name)
+        || !['BOOL', 'INT', 'DINT', 'REAL'].includes(entry.data_type)
+        || (entry.program !== undefined && (typeof entry.program !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(entry.program))))
+        throw new Error('Invalid polling worker tag')
+      return { entry, tag: new ethernetIp.Tag(entry.name, entry.program) }
+    })
+    const started = performance.now()
+    for (let index = 0; index < spec.samples; index++) {
+      const sweepStart = performance.now()
+      const values = []
+      for (const { entry, tag } of tags) {
+        try {
+          await plc.readTag(tag)
+          const value = tag.value
+          const typeMatches = tag.type === entry.data_type
+          const scalarMatches = entry.data_type === 'BOOL' ? typeof value === 'boolean'
+            : typeof value === 'number' && Number.isFinite(value)
+          values.push({ tag: entry.program ? `Program:${entry.program}.${entry.name}` : entry.name,
+            data_type: entry.data_type, actual_data_type: tag.type,
+            value: typeMatches && scalarMatches ? value : null,
+            quality: typeMatches && scalarMatches ? 'good' : 'bad', observed_at: new Date().toISOString(),
+            ...typeMatches && scalarMatches ? {} : { error: 'Live type or value differs from the export declaration' } })
+        } catch (error) {
+          values.push({ tag: entry.program ? `Program:${entry.program}.${entry.name}` : entry.name,
+            data_type: entry.data_type, value: null, quality: 'bad', observed_at: new Date().toISOString(),
+            error: error instanceof Error ? error.message : 'Tag read failed' })
+        }
+      }
+      const sweepEnd = performance.now()
+      emit({ type: 'sample', index, elapsed_ms: sweepStart - started, sweep_ms: sweepEnd - sweepStart,
+        overrun: sweepEnd - sweepStart > spec.interval, values })
+      if (index + 1 < spec.samples) await delay(Math.max(0, spec.interval - (performance.now() - sweepStart)))
+    }
+  } finally {
+    // Unconnected explicit messaging needs no Forward Close request.
+    const closed = new Promise(resolve => plc.once('close', resolve))
+    if (!plc.closed) { if (!plc.destroyed) plc.destroy(); await closed }
+  }
+}
+
+if (!isMainThread) {
+  try { await collect(workerData, frame => parentPort.postMessage(frame)) }
+  catch (error) { parentPort.postMessage({ type: 'failure', message: error instanceof Error ? error.message : 'Polling failed' }) }
+  finally { parentPort.close() }
+}

package/vendor/l5x/studio-bridge/NuGet.Config

@@ -0,0 +1 @@
+<configuration><packageSources><clear/><add key="LocalRockwellSdk" value="C:\Users\Public\Documents\Studio 5000\Logix Designer SDK\dotnet"/><add key="nuget.org" value="https://api.nuget.org/v3/index.json"/></packageSources></configuration>

package/vendor/l5x/studio-bridge/Program.cs

@@ -0,0 +1,304 @@
+using RockwellAutomation.LogixDesigner;
+using RockwellAutomation.LogixDesigner.Logging;
+
+// Deliberately narrow: no online edits, tag setters, forces, bit toggles, or data writes.
+// The plugin obtains human approval before invoking upload, mode change, or download.
+if (args.Length < 3 || args.Length > 9
+    || !new[] { "edit-routine", "verify", "export-l5x", "read-mode", "read-dint", "read-tag", "sample-tags", "get-comm-path", "upload-new", "go-online", "change-mode", "download" }.Contains(args[0]))
+{
+    Console.Error.WriteLine("Unsupported Studio bridge command or argument count.");
+    return 2;
+}
+
+// Offline-only component import. Never reuse a diagnostic/online project handle.
+if (args[0] == "edit-routine")
+{
+    if (args.Length != 9 || !Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)
+        || !Path.GetExtension(args[2]).Equals(".l5x", StringComparison.OrdinalIgnoreCase)
+        || !Path.GetExtension(args[3]).Equals(".acd", StringComparison.OrdinalIgnoreCase)
+        || !Path.GetExtension(args[6]).Equals(".l5x", StringComparison.OrdinalIgnoreCase)
+        || new[] { args[4], args[5] }.Any(name => !System.Text.RegularExpressions.Regex.IsMatch(name, "^[A-Za-z_][A-Za-z0-9_]*$"))) return 2;
+    string working = Path.GetFullPath(args[3]);
+    string componentFile = working + ".routine.l5x";
+    if (File.Exists(working) || File.Exists(args[6]) || File.Exists(componentFile)) return 2;
+    try
+    {
+        string Hash(string file) => Convert.ToHexString(System.Security.Cryptography.SHA256.HashData(File.ReadAllBytes(file)));
+        if (!Hash(args[1]).Equals(args[7], StringComparison.OrdinalIgnoreCase)
+            || !Hash(args[2]).Equals(args[8], StringComparison.OrdinalIgnoreCase)) throw new InvalidOperationException("Source changed before offline edit");
+        File.Copy(args[1], working, false);
+        if (!Hash(working).Equals(args[7], StringComparison.OrdinalIgnoreCase)) throw new InvalidOperationException("Copied ACD hash mismatch");
+        using LogixProject edit = await LogixProject.OpenLogixProjectAsync(working, new StdOutEventLogger());
+        await edit.GoOfflineAsync();
+        string xpath = $"Controller/Programs/Program[@Name='{args[4]}']/Routines/Routine[@Name='{args[5]}']";
+        await edit.PartialExportToXmlFileAsync(xpath, componentFile);
+        var options = new System.Xml.XmlReaderSettings { DtdProcessing = System.Xml.DtdProcessing.Prohibit, XmlResolver = null };
+        using var draftReader = System.Xml.XmlReader.Create(args[2], options);
+        var draft = System.Xml.Linq.XDocument.Load(draftReader, System.Xml.Linq.LoadOptions.PreserveWhitespace);
+        using var componentReader = System.Xml.XmlReader.Create(componentFile, options);
+        var component = System.Xml.Linq.XDocument.Load(componentReader, System.Xml.Linq.LoadOptions.PreserveWhitespace);
+        componentReader.Close();
+        draftReader.Close();
+        System.Xml.Linq.XElement FindRoutine(System.Xml.Linq.XDocument doc) => doc.Root!.Element("Controller")!.Element("Programs")!
+            .Elements("Program").Single(p => (string?)p.Attribute("Name") == args[4]).Element("Routines")!
+            .Elements("Routine").Single(r => (string?)r.Attribute("Name") == args[5]);
+        var target = FindRoutine(component);
+        var replacement = new System.Xml.Linq.XElement(FindRoutine(draft));
+        replacement.SetAttributeValue("Use", (string?)target.Attribute("Use") ?? "Target");
+        target.ReplaceWith(replacement);
+        component.Save(componentFile);
+        Console.WriteLine("OFFLINE_COMPONENT_IMPORT_STARTED");
+        await edit.PartialImportFromXmlFileAsync(xpath, componentFile, LogixProject.ImportCollisionOptions.OverwriteOnColl, false);
+        await edit.BuildAsync(LogixProject.RequestedBuildTarget.DefaultTarget);
+        await edit.SaveAsync();
+        await edit.SaveAsAsync(Path.GetFullPath(args[6]), true, true);
+        if (!Hash(args[1]).Equals(args[7], StringComparison.OrdinalIgnoreCase)) throw new InvalidOperationException("Original ACD changed during edit");
+        Console.WriteLine("OFFLINE_ACD_EDIT_SUCCEEDED");
+        return 0;
+    }
+    catch (Exception error)
+    {
+        Console.Error.WriteLine($"OFFLINE_ACD_EDIT_FAILED: {error.GetType().Name}: {error.Message}");
+        return 1;
+    }
+}
+
+if (args[0] == "upload-new")
+{
+    if (args.Length != 3 || !Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)
+        || File.Exists(args[1]) || string.IsNullOrWhiteSpace(args[2])) return 2;
+    try
+    {
+        using LogixProject _ = await LogixProject.UploadToNewProjectAsync(Path.GetFullPath(args[1]), args[2], new StdOutEventLogger());
+        Console.WriteLine("UPLOAD_TO_NEW_ACD_SUCCEEDED");
+        return 0;
+    }
+    catch (Exception error)
+    {
+        Console.Error.WriteLine($"UPLOAD_TO_NEW_ACD_FAILED: {error.GetType().Name}: {error.Message}");
+        return 1;
+    }
+}
+
+if (args[0] is "go-online" or "change-mode" or "download")
+{
+    if ((args[0] == "change-mode" ? args.Length != 6 : args.Length != 4)
+        || !Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)
+        || string.IsNullOrWhiteSpace(args[2])
+        || !System.Text.RegularExpressions.Regex.IsMatch(args[3], "^[a-fA-F0-9]{64}$")) return 2;
+    string actionFile = Path.GetFullPath(args[1]);
+    if (!File.Exists(actionFile)) return 2;
+    try
+    {
+        string actualHash = Convert.ToHexString(System.Security.Cryptography.SHA256.HashData(await File.ReadAllBytesAsync(actionFile)));
+        if (!actualHash.Equals(args[3], StringComparison.OrdinalIgnoreCase))
+        {
+            Console.Error.WriteLine("ACD hash changed after approval.");
+            return 2;
+        }
+        using LogixProject action = await LogixProject.OpenLogixProjectAsync(actionFile, new StdOutEventLogger());
+        await action.SetCommunicationsPathAsync(args[2]);
+        if (args[0] == "go-online")
+        {
+            await action.GoOnlineAsync();
+            Console.WriteLine("GO_ONLINE_SUCCEEDED");
+            return 0;
+        }
+        if (args[0] == "change-mode")
+        {
+            var observed = await action.ReadControllerModeAsync();
+            if (!Enum.TryParse<LogixProject.ControllerMode>(args[5], false, out var expected)
+                || observed != expected)
+            {
+                Console.Error.WriteLine($"Controller mode changed since approval; expected {args[5]}, observed {observed}");
+                return 2;
+            }
+            LogixProject.RequestedControllerMode target = args[4] switch
+            {
+                "Program" => LogixProject.RequestedControllerMode.Program,
+                "Run" => LogixProject.RequestedControllerMode.Run,
+                "Test" => LogixProject.RequestedControllerMode.Test,
+                _ => throw new ArgumentException("Unsupported controller mode")
+            };
+            await action.ChangeControllerModeAsync(target);
+            Console.WriteLine($"CONTROLLER_MODE_AFTER={await action.ReadControllerModeAsync()}");
+            return 0;
+        }
+        var before = await action.ReadControllerModeAsync();
+        if (before != LogixProject.ControllerMode.Program)
+        {
+            Console.Error.WriteLine($"Download requires Program mode; current mode: {before}");
+            return 2;
+        }
+        Console.WriteLine($"CONTROLLER_MODE_BEFORE={before}");
+        await action.DownloadAsync();
+        Console.WriteLine("DOWNLOAD_SUCCEEDED");
+        return 0;
+    }
+    catch (Exception error)
+    {
+        Console.Error.WriteLine($"CONTROLLER_ACTION_FAILED: {error.GetType().Name}: {error.Message}");
+        return 1;
+    }
+}
+
+if (args[0] == "verify" && !Path.GetExtension(args[1]).Equals(".l5x", StringComparison.OrdinalIgnoreCase)) return 2;
+if (args[0] == "export-l5x" && (!Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)
+    || !Path.GetExtension(args[2]).Equals(".l5x", StringComparison.OrdinalIgnoreCase))) return 2;
+if (args[0] == "read-dint" && !Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)) return 2;
+if (args[0] == "read-tag" && !Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)) return 2;
+if (args[0] == "sample-tags" && !Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)) return 2;
+if (args[0] == "read-mode" && !Path.GetExtension(args[1]).Equals(".l5x", StringComparison.OrdinalIgnoreCase)
+    && !Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)) return 2;
+if (args[0] == "get-comm-path" && !Path.GetExtension(args[1]).Equals(".l5x", StringComparison.OrdinalIgnoreCase)
+    && !Path.GetExtension(args[1]).Equals(".acd", StringComparison.OrdinalIgnoreCase)) return 2;
+string source = Path.GetFullPath(args[1]);
+if (!File.Exists(source))
+{
+    Console.Error.WriteLine("Input L5X must exist.");
+    return 2;
+}
+
+try
+{
+    if (args[0] == "sample-tags")
+    {
+        if (args.Length != 6 || string.IsNullOrWhiteSpace(args[2])
+            || !int.TryParse(args[4], out int count) || count is < 1 or > 20
+            || !int.TryParse(args[5], out int intervalMs) || intervalMs is < 250 or > 5000
+            || (long)count * intervalMs > 30000) return 2;
+        var tags = System.Text.Json.JsonSerializer.Deserialize<List<WatchTag>>(args[3]);
+        if (tags is null || tags.Count is < 1 or > 16 || tags.Any(tag => tag.Name is null || tag.DataType is null
+            || !System.Text.RegularExpressions.Regex.IsMatch(tag.Name, "^[A-Za-z_][A-Za-z0-9_]*$")
+            || !new[] { "BOOL", "INT", "DINT", "REAL" }.Contains(tag.DataType))) return 2;
+        using LogixProject monitor = await LogixProject.OpenLogixProjectAsync(source, new StdOutEventLogger());
+        await monitor.SetCommunicationsPathAsync(args[2]);
+        await monitor.GoOnlineAsync();
+        var clock = System.Diagnostics.Stopwatch.StartNew();
+        for (int sample = 0; sample < count; sample++)
+        {
+            var started = clock.ElapsedMilliseconds;
+            var values = new List<object>();
+            int successfulReads = 0;
+            foreach (var tag in tags)
+            {
+                string path = $"Controller/Tags/Tag[@Name='{tag.Name}']";
+                var readAt = DateTimeOffset.UtcNow;
+                try
+                {
+                    object value = tag.DataType switch
+                    {
+                        "BOOL" => await monitor.GetTagValueBOOLAsync(path, LogixProject.OperationMode.Online),
+                        "INT" => await monitor.GetTagValueINTAsync(path, LogixProject.OperationMode.Online),
+                        "DINT" => await monitor.GetTagValueDINTAsync(path, LogixProject.OperationMode.Online),
+                        "REAL" => await monitor.GetTagValueREALAsync(path, LogixProject.OperationMode.Online),
+                        _ => throw new ArgumentException("Unsupported tag type")
+                    };
+                    values.Add(new { tag = tag.Name, data_type = tag.DataType, value, observed_at = readAt, quality = "good" });
+                    successfulReads++;
+                }
+                catch (Exception error)
+                {
+                    values.Add(new { tag = tag.Name, data_type = tag.DataType, value = (object?)null, observed_at = readAt,
+                        quality = "error", error = $"{error.GetType().Name}: {error.Message}" });
+                    if (error.Message.Contains("RxE_COMM_", StringComparison.OrdinalIgnoreCase))
+                    {
+                        Console.Error.WriteLine($"SAMPLING_FAILED: FactoryTalk Linx communication failed while reading {tag.Name}: {error.Message}");
+                        return 1;
+                    }
+                }
+            }
+            Console.WriteLine("SAMPLE_JSON=" + System.Text.Json.JsonSerializer.Serialize(new
+            {
+                sample, elapsed_ms = clock.ElapsedMilliseconds, sweep_ms = clock.ElapsedMilliseconds - started, values
+            }));
+            if (successfulReads == 0)
+            {
+                Console.Error.WriteLine("SAMPLING_FAILED: Every tag read failed; stopping instead of repeating the same communication error.");
+                return 1;
+            }
+            if (clock.ElapsedMilliseconds >= 30000 && sample + 1 < count)
+            {
+                Console.Error.WriteLine("SAMPLING_FAILED: Reads exceeded the 30 second monitoring window; reduce tags or requested rate.");
+                return 1;
+            }
+            if (sample + 1 < count)
+            {
+                long wait = (sample + 1L) * intervalMs - clock.ElapsedMilliseconds;
+                if (wait > 0) await Task.Delay((int)wait);
+            }
+        }
+        Console.WriteLine("SAMPLING_SUCCEEDED");
+        return 0;
+    }
+    if (args[0] == "export-l5x")
+    {
+        if (args.Length != 3 || File.Exists(args[2])) return 2;
+        using LogixProject project = await LogixProject.OpenLogixProjectAsync(source, new StdOutEventLogger());
+        await project.SaveAsAsync(Path.GetFullPath(args[2]), true, true);
+        if (new FileInfo(args[2]).Length == 0) return 1;
+        Console.WriteLine("EXPORTED_L5X_SUCCEEDED");
+        return 0;
+    }
+    if (args[0] == "get-comm-path")
+    {
+        if (args.Length != 3 || args[2] != "--read-only") return 2;
+        using LogixProject project = await LogixProject.OpenLogixProjectAsync(source, new StdOutEventLogger());
+        Console.WriteLine($"PROJECT_COMM_PATH={await project.GetCommunicationsPathAsync()}");
+        return 0;
+    }
+    if (args[0] == "read-mode")
+    {
+        if (args.Length != 3) return 2;
+        if (string.IsNullOrWhiteSpace(args[2])) return 2;
+        using LogixProject monitor = await LogixProject.OpenLogixProjectAsync(source, new StdOutEventLogger());
+        await monitor.SetCommunicationsPathAsync(args[2]);
+        var mode = await monitor.ReadControllerModeAsync();
+        Console.WriteLine($"READ_CONTROLLER_MODE={mode}");
+        return 0;
+    }
+
+    if (args[0] is "read-dint" or "read-tag")
+    {
+        if (args.Length != (args[0] == "read-tag" ? 5 : 4)
+            || !System.Text.RegularExpressions.Regex.IsMatch(args[3], "^[A-Za-z_][A-Za-z0-9_]*$")) return 2;
+        string dataType = args[0] == "read-dint" ? "DINT" : args[4];
+        if (!new[] { "BOOL", "INT", "DINT", "REAL" }.Contains(dataType)) return 2;
+        using LogixProject monitor = await LogixProject.OpenLogixProjectAsync(source, new StdOutEventLogger());
+        await monitor.SetCommunicationsPathAsync(args[2]);
+        string tagPath = $"Controller/Tags/Tag[@Name='{args[3]}']";
+        string value = dataType switch
+        {
+            "BOOL" => (await monitor.GetTagValueBOOLAsync(tagPath, LogixProject.OperationMode.Online)).ToString().ToLowerInvariant(),
+            "INT" => (await monitor.GetTagValueINTAsync(tagPath, LogixProject.OperationMode.Online)).ToString(System.Globalization.CultureInfo.InvariantCulture),
+            "DINT" => (await monitor.GetTagValueDINTAsync(tagPath, LogixProject.OperationMode.Online)).ToString(System.Globalization.CultureInfo.InvariantCulture),
+            "REAL" => (await monitor.GetTagValueREALAsync(tagPath, LogixProject.OperationMode.Online)).ToString("R", System.Globalization.CultureInfo.InvariantCulture),
+            _ => throw new ArgumentException("Unsupported tag type")
+        };
+        Console.WriteLine(args[0] == "read-dint" ? $"READ_DINT={value}" : $"READ_TAG={value}");
+        return 0;
+    }
+
+    if (args.Length != 3) return 2;
+    if (!Path.GetExtension(args[2]).Equals(".acd", StringComparison.OrdinalIgnoreCase)) return 2;
+    string output = Path.GetFullPath(args[2]);
+    if (File.Exists(output) || source.Equals(output, StringComparison.OrdinalIgnoreCase))
+    {
+        Console.Error.WriteLine("Output must be a new, distinct ACD file.");
+        return 2;
+    }
+    using LogixProject imported = await LogixProject.OpenLogixProjectAsync(source, new StdOutEventLogger());
+    await imported.SaveAsAsync(output, false, false);
+    using LogixProject offline = await LogixProject.OpenLogixProjectAsync(output, new StdOutEventLogger());
+    await offline.BuildAsync(LogixProject.RequestedBuildTarget.DefaultTarget);
+    await offline.SaveAsync();
+    Console.WriteLine("OFFLINE_BUILD_SUCCEEDED");
+    return 0;
+}
+catch (Exception error)
+{
+    Console.Error.WriteLine($"SDK_OPERATION_FAILED: {error.GetType().Name}: {error.Message}");
+    return 1;
+}
+
+internal sealed record WatchTag(string Name, string DataType);

package/vendor/l5x/studio-bridge/StudioBridge.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="RockwellAutomation.LogixDesigner.CSClient" Version="2.1.974" />
+  </ItemGroup>
+</Project>

package/vendor/mwi/README.md

@@ -0,0 +1,60 @@
+# dsh-engineering-mwi
+
+MotionWorks IEC 3 Pro tools, redesigned for the `dsh-engineering` bundle. The product works on a
+**staged copy** of a workspace project and drives the running IDE through the existing 32-bit COM
+bridge; the tool surface is new.
+
+This package is **not mounted yet**. The legacy `dsh-tool-motionworks-iec` remains the shipped
+surface until the redesign flips in Phase 5. The migration design and phase order are in
+[docs/port/mwi.md](../../docs/port/mwi.md).
+
+## Rows and progress
+
+| Row | Default | Tools | Status |
+|---|---|---|---|
+| `mwi-session` | on | 7 | implemented and live-verified |
+| `mwi-read` | on | 7 | implemented and live-verified |
+| `mwi-verify` | on | 3 | next |
+| `mwi-edit` | off | 7 | planned |
+| `mwi-skill` | on | the `motionworks-iec` guidance | implemented |
+
+Read tools: `mw_project_overview`, `mw_list`, `mw_get`, `mw_search`, `mw_references`, `mw_review`, `mw_help`.
+
+Session tools: `mw_project_find`, `mw_ide_status`, `mw_project_stage`, `mw_project_open`,
+`mw_ide_start`, `mw_worksheet_open`, `mw_project_close`.
+
+## Live evidence
+
+Verified against MotionWorks IEC 3 Pro 1.19 on 2026-10-23 with a copy of a real project in a temporary
+workspace:
+
+1. `stage` copied the project, bound the wrapper to the staged directory and wrote its identity.
+2. `start` launched the IDE and answered the trial prompt (`posted_bm_click`).
+3. `status` reported the staged project open, `in_stage: true`.
+4. `worksheet` opened `Global_Variables` and verified the active editor and unchanged modified state.
+5. `close` reported `closed: true`, and the next status reported the IDE not running.
+
+## Structure
+
+```
+SKILL.md          the redesigned guidance
+bridge/           the 32-bit PowerShell COM bridge
+code/             the Python engine (wrapper binding, saved-model reads, validation)
+src/core/         params, result, errors, tool, bridge, PowerShell transport, code engine
+src/session/      workspace, stage, runtime
+src/tools/        session row (read/verify/edit rows next)
+test/             contract tests and the live fixtures
+```
+
+## Requirements
+
+Windows, MotionWorks IEC 3 Pro (licensed or trial), Python 3 for the code engine, Windows 32-bit
+PowerShell for the COM bridge, and a computer-use companion for desktop-only operations.
+
+## Develop
+
+```sh
+pnpm install
+pnpm run build
+pnpm test
+```