@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/ftview/lib/studio/preflight.js

@@ -0,0 +1,64 @@
+/**
+ * Preflight and handoff for a manual FactoryTalk View Studio import.
+ *
+ * This entry never runs a vendor utility. Preflight reports what a Studio
+ * import would touch and which prerequisites are missing; handoff returns the
+ * ordered manual steps. Automation through `SEAddComponent.exe` is deliberately
+ * absent until it can be validated in a licensed environment.
+ *
+ * @module dsh-engineering-ftview/studio/preflight
+ */
+/** File names the Add Component utility refuses (vendor restriction). */
+const UNSAFE_NAME = /[%.":?*<>#{}\[\]\\/;=&+\-\u2019]/u;
+/**
+ * Compare two exports and check whether the changed displays can be imported.
+ *
+ * @param before - The earlier export.
+ * @param after - The edited export.
+ * @param discovery - Studio tooling that was found.
+ * @returns Changed files, blockers, warnings and readiness.
+ */
+export function studioPreflight(before, after, discovery) {
+    const beforeHashes = new Map(before.files.map(file => [file.file, file.sha256]));
+    const changed = after.files.filter(file => beforeHashes.get(file.file) !== file.sha256).map(file => file.file);
+    const blockers = [];
+    const warnings = [];
+    if (changed.length === 0)
+        blockers.push('No file differs between the two exports, so there is nothing to import.');
+    for (const display of after.displays) {
+        if (!changed.includes(display.file))
+            continue;
+        const stem = display.file.replace(/\\/gu, '/').split('/').pop()?.replace(/\.xml$/iu, '') ?? display.file;
+        if (UNSAFE_NAME.test(stem))
+            blockers.push(`Display file ${JSON.stringify(display.file)} has a name Studio's import refuses; rename it in Studio first.`);
+        if (display.parseError !== undefined)
+            blockers.push(`Display ${JSON.stringify(display.name)} does not parse: ${display.parseError}`);
+    }
+    if (discovery.utilities.length === 0)
+        warnings.push('No SEAddComponent utility was discovered: only the manual Studio import is available.');
+    if (discovery.schemas.length === 0)
+        warnings.push('No ME XSD was discovered: schema validation is unavailable.');
+    return { changed, blockers, warnings, ready: blockers.length === 0, utility_available: discovery.utilities.length > 0 };
+}
+/**
+ * Produce the ordered manual import plan.
+ *
+ * @param before - The earlier export.
+ * @param after - The edited export.
+ * @param discovery - Studio tooling that was found.
+ * @returns The plan.
+ */
+export function handoffPlan(before, after, discovery) {
+    const changed = studioPreflight(before, after, discovery).changed;
+    return {
+        application: after.name,
+        changed,
+        utility_available: discovery.utilities.length > 0,
+        steps: [
+            { step: 1, action: `Open the ME application for ${after.name} in FactoryTalk View Studio.` },
+            { step: 2, action: 'Import only the changed display components listed here, using the Graphics editor or Add Component.', files: changed },
+            { step: 3, action: 'Save the application and export a fresh full export folder.' },
+            { step: 4, action: 'Reopen both exports with ftview_open and run ftview_compare to confirm only the intended files changed.' },
+        ],
+    };
+}

package/vendor/ftview/lib/studio/tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The FTView Studio entry: discovery, preflight and the manual handoff plan.
+ *
+ * @module dsh-engineering-ftview/studio/tools
+ */
+import { type ToolDefinition } from '../core.ts';
+import type { ViewSession } from '../session.ts';
+/**
+ * The Studio tools.
+ *
+ * @param session - View handles from the read entry.
+ * @param roots - Install roots to search.
+ * @returns Tool definitions in registration order.
+ */
+export declare function studioTools(session: ViewSession, roots: readonly string[]): readonly ToolDefinition[];

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

@@ -0,0 +1,83 @@
+/**
+ * The FTView Studio entry: discovery, preflight and the manual handoff plan.
+ *
+ * @module dsh-engineering-ftview/studio/tools
+ */
+import { object, optionalString, requiredString, string, success, tool } from "../core.js";
+import { discoverStudio } from "./discover.js";
+import { handoffPlan, studioPreflight } from "./preflight.js";
+/** Nothing here proves what Studio will do. */
+const COVERAGE = {
+    complete: false,
+    unverified: [
+        'FactoryTalk View Studio import behavior',
+        'vendor XSD validation',
+        'runtime behavior on the terminal',
+        'automation through SEAddComponent (not executed)',
+    ],
+};
+/** A compact view of the discovery for tool output. */
+function discoveryData(discovery) {
+    return {
+        searched: discovery.searched,
+        products: discovery.products,
+        schemas: discovery.schemas,
+        utilities: discovery.utilities,
+        help: discovery.help,
+        truncated: discovery.truncated,
+    };
+}
+/**
+ * The Studio tools.
+ *
+ * @param session - View handles from the read entry.
+ * @param roots - Install roots to search.
+ * @returns Tool definitions in registration order.
+ */
+export function studioTools(session, roots) {
+    return [
+        tool({
+            name: 'ftview_studio_status',
+            description: 'Discover installed FactoryTalk View ME tooling: product folders, ME XSD schemas, help files and the Add Component utility. Read-only; does not start Studio or prove licensing.',
+            parameters: object({}),
+            async run(_args, exec) {
+                const discovery = await discoverStudio(session.fs, roots, exec.signal);
+                const products = discovery.products.length;
+                const utilities = discovery.utilities.length;
+                return success(`Searched ${discovery.searched.length} root(s): ${products} product folder(s), ${utilities} Add Component utility, ${discovery.schemas.length} schema(s).`, discoveryData(discovery), utilities === 0 ? [] : [{ tool: 'ftview_studio_preflight', why: 'Check a change set before importing it.' }], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_studio_preflight',
+            description: 'Check the files that differ between two opened exports for a manual Studio import: parse state, name restrictions, discovered utility and schemas. Writes nothing and starts no Studio.',
+            parameters: object({
+                before_id: string('View id of the export before the edit.'),
+                after_id: string('View id of the edited export.'),
+            }, ['before_id', 'after_id']),
+            async run(args, exec) {
+                const before = session.require(requiredString(args, 'before_id'), exec).app;
+                const after = session.require(requiredString(args, 'after_id'), exec).app;
+                const discovery = await discoverStudio(session.fs, roots, exec.signal);
+                const check = studioPreflight(before, after, discovery);
+                return success(`${check.changed.length} file(s) differ; ${check.blockers.length} blocker(s).`, { ...check, discovery: discoveryData(discovery) }, check.ready ? [{ tool: 'ftview_studio_handoff', args: { before_id: requiredString(args, 'before_id'), after_id: requiredString(args, 'after_id') }, why: 'Get the ordered manual import steps.' }] : [], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_studio_handoff',
+            description: 'Return the ordered manual FactoryTalk View Studio import plan for the changed displays between two opened exports. No vendor utility runs and no file is written.',
+            parameters: object({
+                before_id: string('View id of the export before the edit.'),
+                after_id: string('View id of the edited export.'),
+                application: string('ME application name the human opens in Studio. Example: "Line".'),
+            }, ['before_id', 'after_id', 'application']),
+            async run(args, exec) {
+                const before = session.require(requiredString(args, 'before_id'), exec).app;
+                const after = session.require(requiredString(args, 'after_id'), exec).app;
+                const discovery = await discoverStudio(session.fs, roots, exec.signal);
+                const plan = handoffPlan(before, after, discovery);
+                const application = optionalString(args, 'application') ?? plan.application;
+                return success(`${plan.changed.length} changed file(s) to import into ${application} by hand.`, { ...plan, application }, [], COVERAGE);
+            },
+        }),
+    ];
+}

package/vendor/ftview/lib/studio.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The FTView Studio entry: discovery, preflight and manual handoff.
+ *
+ * Deliberately does not execute vendor utilities. The old plugin's
+ * `ftview_studio_apply` ran `SEAddComponent.exe` behind a capability probe that
+ * only a licensed Studio install can produce; that path is out of scope until
+ * it can be validated, so this entry stops at a verifiable handoff.
+ *
+ * @module dsh-engineering-ftview/studio
+ */
+import type { PluginContext } from './core.ts';
+/** Plugin name in a composition. */
+export declare const name = "ftview-studio";
+/** The read entry's view service must already be mounted. */
+export declare const inject: readonly ["tools", "fs", "ftviewViews"];
+/** Configuration for the Studio entry. */
+export interface Config {
+    /** Install roots to search. Defaults to the two Rockwell Programs folders. */
+    searchRoots?: string[];
+}
+/**
+ * Register the Studio tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's view service.
+ * @param config - Deployment limits.
+ */
+export declare function apply(ctx: PluginContext, config?: Config): void;
+export { discoverStudio, DEFAULT_SEARCH_ROOTS } from './studio/discover.ts';
+export { handoffPlan, studioPreflight } from './studio/preflight.ts';
+export { studioTools } from './studio/tools.ts';

package/vendor/ftview/lib/studio.js

@@ -0,0 +1,37 @@
+/**
+ * The FTView Studio entry: discovery, preflight and manual handoff.
+ *
+ * Deliberately does not execute vendor utilities. The old plugin's
+ * `ftview_studio_apply` ran `SEAddComponent.exe` behind a capability probe that
+ * only a licensed Studio install can produce; that path is out of scope until
+ * it can be validated, so this entry stops at a verifiable handoff.
+ *
+ * @module dsh-engineering-ftview/studio
+ */
+import { DEFAULT_SEARCH_ROOTS } from "./studio/discover.js";
+import { studioTools } from "./studio/tools.js";
+/** Plugin name in a composition. */
+export const name = 'ftview-studio';
+/** The read entry's view service must already be mounted. */
+export const inject = ['tools', 'fs', 'ftviewViews'];
+/**
+ * Register the Studio tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's view service.
+ * @param config - Deployment limits.
+ */
+export function apply(ctx, config = {}) {
+    const session = ctx.get?.('ftviewViews');
+    if (session === undefined) {
+        throw new Error('ftview-studio: the ftviewViews service is unavailable; mount the FTView read entry before this one');
+    }
+    const roots = config.searchRoots ?? [...DEFAULT_SEARCH_ROOTS];
+    if (!Array.isArray(roots) || roots.some(root => typeof root !== 'string' || root === '')) {
+        throw new Error('ftview-studio: searchRoots must be an array of non-empty absolute paths');
+    }
+    for (const definition of studioTools(session, roots))
+        ctx.tools.register(definition);
+}
+export { discoverStudio, DEFAULT_SEARCH_ROOTS } from "./studio/discover.js";
+export { handoffPlan, studioPreflight } from "./studio/preflight.js";
+export { studioTools } from "./studio/tools.js";

package/vendor/ftview/lib/tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The FTView read surface: six intents over one opened export folder.
+ *
+ * @module dsh-engineering-ftview/tools
+ */
+import { type ToolDefinition } from './core.ts';
+import type { ViewSession } from './session.ts';
+/**
+ * The read tools, bound to one chat's view store.
+ *
+ * @param session - View handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export declare function ftviewTools(session: ViewSession): readonly ToolDefinition[];

package/vendor/ftview/lib/tools.js

@@ -0,0 +1,202 @@
+/**
+ * The FTView read surface: six intents over one opened export folder.
+ *
+ * @module dsh-engineering-ftview/tools
+ */
+import { EngineeringError, choice, integer, object, optionalInteger, optionalString, requiredString, string, success, tool } from "./core.js";
+import { findingsOf } from "./checks.js";
+/** What this surface cannot prove. */
+const COVERAGE = {
+    complete: false,
+    unverified: [
+        'vendor XSD schema validation',
+        'PLC binding and runtime behavior',
+        'visual rendering',
+        'displays or tags absent from the supplied export',
+    ],
+};
+/** The view handle parameter, described once. */
+const VIEW_ID = string('View handle returned by ftview_open. Omit when exactly one export is open in this chat.');
+/** Page parameters shared by the list-shaped tools. */
+const PAGE = {
+    offset: integer('Number of rows to skip. Default 0.', { minimum: 0, default: 0 }),
+    limit: integer('Most rows to return. Default 50, maximum 200.', { minimum: 1, maximum: 200, default: 50 }),
+};
+/** Slice one page. */
+function page(rows, offset, limit) {
+    return { rows: rows.slice(offset, offset + limit), offset, limit, total: rows.length, truncated: offset + limit < rows.length };
+}
+/** Display rows shared by list and compare. */
+function displayRows(displays) {
+    return displays.map(display => ({ name: display.name, file: display.file, objects: display.objects.length }));
+}
+/** Tag rows shared by list and compare. */
+function tagRows(tags) {
+    return tags.map(tag => ({ name: tag.name, type: tag.type, description: tag.description }));
+}
+/** The closest names for a not-found failure. */
+function nearest(names, wanted) {
+    const lower = wanted.toLowerCase();
+    return names.filter(name => name.toLowerCase().includes(lower)).slice(0, 5);
+}
+/**
+ * The read tools, bound to one chat's view store.
+ *
+ * @param session - View handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export function ftviewTools(session) {
+    return [
+        tool({
+            name: 'ftview_open',
+            description: 'Open one FactoryTalk View ME export folder and return its application summary: displays, tag rows, structural diagnostics and coverage. Read-only; does not decode MER, contact a terminal, or change files.',
+            parameters: object({
+                root: string('Export folder containing the display XML files and the HMI tag CSV. Example: "C:/Projects/Line/ME Export".'),
+            }, ['root']),
+            async run(args, exec) {
+                const view = await session.open(requiredString(args, 'root'), exec);
+                const { app } = view;
+                return success(`${app.name}: ${app.displays.length} displays, ${app.tags.length} tags, ${app.diagnostics.length + app.tagErrors.length} diagnostic(s).`, {
+                    view_id: view.id,
+                    root: app.root,
+                    name: app.name,
+                    displays: app.displays.length,
+                    tags: app.tags.length,
+                    tag_files: app.tagFiles,
+                    diagnostics: app.diagnostics,
+                    tag_errors: app.tagErrors,
+                    files: app.files.length,
+                }, [
+                    { tool: 'ftview_list', args: { view_id: view.id, kind: 'display' }, why: 'List the displays you can read.' },
+                    { tool: 'ftview_check', args: { view_id: view.id }, why: 'See the structural findings before reporting.' },
+                ], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_list',
+            description: 'List the displays or the HMI tags in one opened export, with a name filter and paging.',
+            parameters: object({
+                view_id: VIEW_ID,
+                kind: choice('What to list: the display files or the HMI tag rows.', ['display', 'tag']),
+                filter: string('Optional case-insensitive substring for the display or tag name.'),
+                ...PAGE,
+            }, ['kind']),
+            async run(args, exec) {
+                const { app } = session.require(optionalString(args, 'view_id'), exec);
+                const kind = requiredString(args, 'kind');
+                const filter = optionalString(args, 'filter')?.toLowerCase();
+                const rows = kind === 'tag'
+                    ? tagRows(filter === undefined ? app.tags : app.tags.filter(tag => tag.name.toLowerCase().includes(filter) || tag.description.toLowerCase().includes(filter)))
+                    : displayRows(filter === undefined ? app.displays : app.displays.filter(display => display.name.toLowerCase().includes(filter) || display.file.toLowerCase().includes(filter)));
+                const sliced = page(rows, optionalInteger(args, 'offset') ?? 0, optionalInteger(args, 'limit') ?? 50);
+                return success(`${sliced.total} ${kind === 'tag' ? 'tags' : 'displays'}${sliced.truncated ? `; showing ${sliced.offset + 1}-${sliced.offset + sliced.rows.length}` : ''}.`, { kind, ...sliced }, [{ tool: 'ftview_get', args: { view_id: optionalString(args, 'view_id'), kind, name: 'NAME' }, why: 'Read one row in full.' }], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_get',
+            description: 'Read one display or one HMI tag in full: a display exposes its named objects; a tag exposes its CSV row.',
+            parameters: object({
+                view_id: VIEW_ID,
+                kind: choice('What to read: one display file or one HMI tag row.', ['display', 'tag']),
+                name: string('Exact display name or tag name. Example: "Main" or "StartPB".'),
+            }, ['kind', 'name']),
+            async run(args, exec) {
+                const { app } = session.require(optionalString(args, 'view_id'), exec);
+                const kind = requiredString(args, 'kind');
+                const name = requiredString(args, 'name');
+                if (kind === 'tag') {
+                    const tag = app.tags.find(candidate => candidate.name === name);
+                    if (tag === undefined) {
+                        const candidates = nearest(app.tags.map(candidate => candidate.name), name);
+                        throw new EngineeringError('COMPONENT_NOT_FOUND', `No tag is named ${JSON.stringify(name)} in this export.`, candidates.length > 0 ? `Pass one of: ${candidates.join(', ')}.` : 'Call ftview_list with kind "tag" to see the exported tag names.', candidates);
+                    }
+                    return success(`Tag ${tag.name}.`, tag, [], COVERAGE);
+                }
+                const display = app.displays.find(candidate => candidate.name === name);
+                if (display === undefined) {
+                    const candidates = nearest(app.displays.map(candidate => candidate.name), name);
+                    throw new EngineeringError('COMPONENT_NOT_FOUND', `No display is named ${JSON.stringify(name)} in this export.`, candidates.length > 0 ? `Pass one of: ${candidates.join(', ')}.` : 'Call ftview_list with kind "display" to see the exported display names.', candidates);
+                }
+                return success(`Display ${display.name}: ${display.objects.length} objects.`, { name: display.name, file: display.file, objects: display.objects.slice(0, 200), object_count: display.objects.length }, [], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_find',
+            description: 'Search one opened export by name or text across displays, display objects and HMI tags.',
+            parameters: object({
+                view_id: VIEW_ID,
+                query: string('Text to search for, case-insensitive. Example: "StartPB".'),
+                limit: integer('Most matches to return. Default 50, maximum 200.', { minimum: 1, maximum: 200, default: 50 }),
+            }, ['query']),
+            async run(args, exec) {
+                const { app } = session.require(optionalString(args, 'view_id'), exec);
+                const query = requiredString(args, 'query').toLowerCase();
+                const matches = [];
+                for (const display of app.displays) {
+                    if (display.name.toLowerCase().includes(query) || display.file.toLowerCase().includes(query)) {
+                        matches.push({ kind: 'display', where: display.file, text: display.name });
+                    }
+                    for (const object of display.objects) {
+                        const named = object.name ?? '';
+                        const values = Object.values(object.attributes);
+                        const hit = named.toLowerCase().includes(query) || values.some(value => value.toLowerCase().includes(query));
+                        if (hit)
+                            matches.push({ kind: 'object', where: display.file, text: named === '' ? object.type : `${object.type} ${named}` });
+                    }
+                }
+                for (const tag of app.tags) {
+                    if (tag.name.toLowerCase().includes(query) || tag.description.toLowerCase().includes(query)) {
+                        matches.push({ kind: 'tag', where: 'tag CSV', text: `${tag.name}${tag.description === '' ? '' : ` — ${tag.description}`}` });
+                    }
+                }
+                const limit = optionalInteger(args, 'limit') ?? 50;
+                return success(`${matches.length} match(es) for ${JSON.stringify(requiredString(args, 'query'))}${matches.length > limit ? `; showing ${limit}` : ''}.`, { query: requiredString(args, 'query'), total: matches.length, matches: matches.slice(0, limit) }, [], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_check',
+            description: 'Run structural checks over one opened export: tag CSV integrity, duplicate names within displays and the tag file, and files that did not parse. Vendor XSD validation and PLC binding are not performed.',
+            parameters: object({ view_id: VIEW_ID }, []),
+            async run(args, exec) {
+                const { app } = session.require(optionalString(args, 'view_id'), exec);
+                const findings = findingsOf(app);
+                const byRule = {};
+                for (const finding of findings)
+                    byRule[finding.rule] = (byRule[finding.rule] ?? 0) + 1;
+                return success(`${findings.length} finding(s) in ${app.name}.`, { total: findings.length, by_rule: byRule, findings, coverage: { schema: 'not run', plc_binding: 'not run' } }, [], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_compare',
+            description: 'Compare two opened exports by display name, tag name and file content hash.',
+            parameters: object({
+                before_id: string('View id of the earlier export.'),
+                after_id: string('View id of the later export.'),
+                ...PAGE,
+            }, ['before_id', 'after_id']),
+            async run(args, exec) {
+                const before = session.require(requiredString(args, 'before_id'), exec).app;
+                const after = session.require(requiredString(args, 'after_id'), exec).app;
+                const names = (app) => ({
+                    displays: new Map(app.displays.map(display => [display.name, display.file])),
+                    tags: new Map(app.tags.map(tag => [tag.name, tag.type])),
+                });
+                const oldNames = names(before);
+                const newNames = names(after);
+                const diff = (left, right) => ({
+                    added: [...right.keys()].filter(name => !left.has(name)),
+                    removed: [...left.keys()].filter(name => !right.has(name)),
+                });
+                const hashOf = new Map(before.files.map(file => [file.file, file.sha256]));
+                const changedFiles = after.files.filter(file => hashOf.get(file.file) !== file.sha256).map(file => file.file);
+                const limit = optionalInteger(args, 'limit') ?? 50;
+                return success(`${diff(oldNames.displays, newNames.displays).added.length + diff(oldNames.displays, newNames.displays).removed.length} display change(s), ${diff(oldNames.tags, newNames.tags).added.length + diff(oldNames.tags, newNames.tags).removed.length} tag change(s), ${changedFiles.length} changed file(s).`, {
+                    displays: diff(oldNames.displays, newNames.displays),
+                    tags: diff(oldNames.tags, newNames.tags),
+                    files_changed: changedFiles.slice(0, limit),
+                    truncated: changedFiles.length > limit,
+                }, [], COVERAGE);
+            },
+        }),
+    ];
+}

package/vendor/l5x/README.md

@@ -0,0 +1,62 @@
+# dsh-engineering-l5x
+
+Studio 5000 L5X tools for the `dsh-engineering` bundle. Four loader entries share one package:
+
+| Entry | Tools | Needs |
+|---|---|---|
+| `dsh-engineering-l5x` | 11 offline read and reference tools | Node |
+| `dsh-engineering-l5x/editing` | 9 `draft_*` tools | the read entry |
+| `dsh-engineering-l5x/studio` | 6 Logix Designer SDK tools and 7 supervised controller tools | Studio 5000, Logix Designer SDK, FactoryTalk Linx |
+| `dsh-engineering-l5x/live` | `poll_live_tags`, `start_plc_trend` | a reachable controller |
+
+The `rockwell-l5x` guidance ships as the separate `dsh-engineering-l5x/skill` entry, and the PLC
+trend card ships as the client face (`dsh.client`).
+
+## Read surface
+
+`open_project` opens one export and returns a `project_id`. `project_overview`, `list_components` and
+`get_component` walk the structure; `search_logic`, `find_references`, `trace_dependencies`,
+`resolve_tag` and `usage_map` answer where a symbol is used; `run_checks` and `compare_projects`
+produce review evidence. Every result carries `summary`, `data`, `coverage` and `next`.
+
+Reading accepts L5X revision 19 or later and never needs Studio. A changed export is refused with
+`STALE_EXPORT`; reopen it before continuing.
+
+## Editing
+
+`draft_rung`, `draft_st`, `draft_routine`, `draft_tag`, `draft_tag_description`, `draft_udt_member` and
+`draft_udt_description` append one operation per call; `draft_validate` prepares the draft and
+`draft_apply` writes one new L5X beside the source. Nothing overwrites, imports, connects or changes
+a controller.
+
+## Studio and controller
+
+`studio_sdk_status`, `studio_capabilities`, `export_acd_to_l5x`, `verify_offline_l5x`,
+`build_acd_from_draft` and `studio_review_evidence` cover offline SDK work. The controller tools
+(`capture_controller_snapshot`, `go_online`, `read_controller_mode`, `read_live_tag`,
+`change_controller_mode`, `download_project`, `controller_approval_status`) are read-only unless the
+operation is an upload, mode change or download; those require per-call human approval and a
+`verification_id` from a passed build.
+
+## Live
+
+`poll_live_tags` and `start_plc_trend` read declared scalar tags over EtherNet/IP without Studio,
+Linx, an ACD or the SDK. They are read-only and report that live logic matching the export is
+unverified.
+
+## Configuration
+
+| Entry | Option | Default |
+|---|---|---|
+| read | `maxFileBytes` | 64 MiB |
+| editing | `maxFileBytes`, `maxDraftOperations` | 64 MiB, 200 |
+| studio | `maxFileBytes` | 64 MiB |
+| live | `enabled`, `minIntervalMs`, `defaultIntervalMs`, `maxTags`, `maxSamples` | true, 50 ms, 200 ms, 16, 1200 |
+
+## Develop
+
+```sh
+pnpm install
+pnpm run build
+pnpm test
+```

package/vendor/l5x/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: rockwell-l5x
+description: Read and review Studio 5000 L5X exports: open a project, list and read components, find references, trace dependencies, resolve addresses, map bit usage, run checks, and compare exports.
+whenToUse: Use when the user asks about a Studio 5000 L5X export, Logix tags, routines, UDTs, AOIs, I/O modules, references, dependency tracing, checks, or comparison between exports.
+---
+
+# Rockwell L5X engineering
+
+## Boundary
+
+This surface reads and drafts. A draft writes only a new L5X file: it never overwrites the source, imports into Studio, connects to a controller, changes mode, or writes runtime data.
+
+## Start
+
+1. Call `open_project` with the export path. Keep the returned `project_id`.
+2. Later calls may omit `project_id` when exactly one project is open; pass it when several are.
+3. A read refuses a changed export with `STALE_EXPORT`; call `open_project` again before continuing.
+
+## Find the thing
+
+- `list_components` enumerates one kind: program, task, tag, udt, routine, aoi, module, alarm. Filter by name, page with offset and limit.
+- `get_component` reads one in full by exact name. Pass `scope` for a program-scoped tag or routine.
+- `search_logic` finds literal text in rungs, ST lines and diagram labels.
+- `find_references` answers where a symbol is read or written. Use `detail: "evidence"` for rung or line rows with access type and context.
+- `trace_dependencies` follows upstream or downstream operands. It is static evidence, not runtime causality.
+- `resolve_tag` resolves an alias chain, member, integer bit or array subscript.
+- `usage_map` reports which array elements and bits a tag uses and which remain free.
+
+## Scope rules
+
+- Program-scoped tags and routines need `scope` set to the program name.
+- AOI members are written `AOI_Name::Member`, for example `AOI_EncoderScale::Out_FPM`. `find_references` accepts that spelling; `trace_dependencies` splits it and resolves the member against the AOI.
+- An unresolved symbol is refused with `UNRESOLVED_SYMBOL` and candidate scope names. Do not guess past it; fix the scope or the spelling.
+
+## Checks and comparison
+
+- `run_checks` returns findings with a rule and severity. Filter with `severity` or `rule`, page with offset and limit. Findings are candidates for engineering review, never proof of a defect or of safety.
+- `compare_projects` diffs two open exports by component. Export timestamps and XML formatting are ignored by design.
+
+## Live reads
+
+The `l5x-live` entry reads declared scalar tags straight from a controller over EtherNet/IP, without Studio 5000, FactoryTalk Linx or the SDK. It may be disabled; if `poll_live_tags` is unavailable, say live reads are not enabled rather than trying another tool.
+
+- `poll_live_tags` takes an explicit IPv4 address, a CPU slot and 1 to 16 declared scalar tags (`BOOL`, `INT`, `DINT`, `REAL`), and returns timestamped sweeps, quality and the controller identity.
+- `start_plc_trend` samples the same way as a session-owned job the chart can follow; stop it through the job controls.
+- These are read-only. Never write controller data, force tags, toggle bits or edit online.
+- Report `live_logic_matches_export: "unverified"`: the read proves a value at a moment, not that the controller runs the exported logic, and sequential reads can miss transitions.
+
+## Reporting
+
+- Every result carries `summary`, `data`, `coverage` and `next`. Read `coverage` before claiming the answer is complete.
+- State what the export cannot prove: FBD and SFC execution semantics, dynamic indices, runtime behavior, external HMI and driver consumers, and whether online logic matches the export.
+- Quote the program, routine and rung or ST line for each finding.
+- Do not call a tag unused, or an output permanently zero, from the absence of references alone. External consumers are invisible here.
+
+## Revisions
+
+- Reading accepts any export revision 19 or later. Revisions outside the observed matrix open and report `verification: "untested_revision"`.
+- Reading never needs Studio 5000. The studio entry adds offline import and build, and its controller
+  tools handle upload, mode change and download under per-call approval.
+
+## Studio
+
+The `l5x-studio` entry adds offline SDK work; it may be disabled. Call `studio_sdk_status` before using it.
+
+- `export_acd_to_l5x` writes one new full L5X from an ACD. No controller contact.
+- `verify_offline_l5x` imports a full L5X into a new offline ACD and builds it. Build needs project revision 37 or later; `probe: true` attempts a lower revision and reports the SDK error. A Studio-exported L5X builds; an L5X produced by `export_acd_to_l5x` may be refused by the SDK as "no changes".
+- `build_acd_from_draft` imports one changed RLL or ST routine into a new ACD copy, builds it and exports it. The baseline must be an L5X exported from that ACD in this chat, and neither file may change afterwards.
+- `studio_review_evidence` checks program, routine and rung or line names and verbatim quotes before you report findings.
+- `controller_approval_status` reports whether this session can ask a human. `capture_controller_snapshot`, `change_controller_mode` and `download_project` each require per-call human approval of the exact controller, route and target, and proceed only on `allowed-once`; `download_project` accepts only a `verification_id` from a passed build in this chat.
+- `go_online`, `read_controller_mode` and `read_live_tag` are read-only and need no approval. Never write controller data, force tags, toggle bits or edit online.
+
+## Editing
+
+Editing uses the `draft_*` family. It may be disabled in this profile; if a draft tool is unavailable, say editing is not enabled here rather than trying another tool.
+
+- One operation per call: `draft_rung`, `draft_st`, `draft_routine`, `draft_tag`, `draft_tag_description`, `draft_udt_member`, `draft_udt_description`. Each returns the draft id and the operation count.
+- `draft_validate` prepares the accumulated draft against the project and returns its hash, diff summary and check findings. Read the findings before applying.
+- `draft_apply` writes the draft to ONE new `.L5X` path. It never overwrites an existing file.
+- After applying, reopen the written file with `open_project` to review it.
+- Drafts belong to this chat. Another chat starts with none, and an applied draft is cleared.

package/vendor/l5x/lib/approvals.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Human approval for the controller actions that change a machine.
+ *
+ * Reading a controller needs no approval. Uploading a snapshot, changing mode
+ * and downloading a project each ask the session's approval service for this
+ * exact operation, and proceed only on `allowed-once`. A session whose policy
+ * is not `ask` cannot request approval at all, and the tool refuses before it
+ * touches the controller.
+ *
+ * @module dsh-engineering-l5x/approvals
+ */
+import type { ExecContext, PluginContext } from './core/tool.ts';
+/** The approval service the composition may provide. */
+export interface ApprovalService {
+    request?(request: {
+        readonly agent: unknown;
+        readonly toolName: string;
+        readonly callId: unknown;
+        readonly reason: string;
+        readonly signal?: AbortSignal;
+    }): Promise<string>;
+    overrideOf?(session: unknown): 'ask' | 'never' | undefined;
+    readonly config?: {
+        readonly policy?: 'ask' | 'never';
+    };
+}
+/**
+ * Report whether this session can request per-operation approval.
+ *
+ * @param ctx - Plugin context that may provide the approval service.
+ * @param exec - Calling context carrying the agent.
+ * @returns The status fields the tool shows the reader.
+ */
+export declare function approvalStatus(ctx: PluginContext, exec?: ExecContext): Record<string, unknown>;
+/**
+ * Refuse when approval cannot be requested at all.
+ *
+ * @param ctx - Plugin context.
+ * @param exec - Calling context.
+ */
+export declare function ensureApprovalReady(ctx: PluginContext, exec?: ExecContext): void;
+/**
+ * Ask for approval of one exact operation and refuse unless it is granted once.
+ *
+ * @param ctx - Plugin context.
+ * @param exec - Calling context.
+ * @param toolName - Tool asking, recorded with the request.
+ * @param reason - Exact operation the human is approving.
+ */
+export declare function requireHumanApproval(ctx: PluginContext, exec: ExecContext | undefined, toolName: string, reason: string): Promise<void>;