@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,87 @@
+/**
+ * Bounded discovery of FactoryTalk View Studio ME tooling.
+ *
+ * Reads directories through the filesystem provider, never executes anything.
+ * A missing install is reported as such; absence of a utility is not an error,
+ * because the manual Studio workflow does not need it.
+ *
+ * @module dsh-engineering-ftview/studio/discover
+ */
+import { createHash } from 'node:crypto';
+/** Directory depth the discovery walks below each root. */
+const MAX_DEPTH = 4;
+/** Directory entries the discovery visits per root before it stops. */
+const MAX_ENTRIES_PER_ROOT = 4000;
+/** Known install roots for FactoryTalk View on Windows. */
+export const DEFAULT_SEARCH_ROOTS = [
+    'C:/Program Files (x86)/Rockwell Software',
+    'C:/Program Files/Rockwell Software',
+];
+/** Walk one root and collect products, schemas, utilities and help files. */
+async function walkRoot(fs, root, signal, found) {
+    const queue = [{ path: root, depth: 0 }];
+    let visited = 0;
+    while (queue.length > 0) {
+        signal?.throwIfAborted();
+        const current = queue.shift();
+        let entries;
+        try {
+            entries = fs.listDir === undefined ? [] : await fs.listDir(current.path, signal);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            visited += 1;
+            if (visited > MAX_ENTRIES_PER_ROOT) {
+                found.truncated = true;
+                return;
+            }
+            const path = `${current.path}/${entry.name}`;
+            if (entry.type === 'directory') {
+                if (/FactoryTalk View/i.test(entry.name))
+                    found.products.push(path);
+                if (current.depth < MAX_DEPTH)
+                    queue.push({ path, depth: current.depth + 1 });
+                continue;
+            }
+            if (/^SEAddComponent\.exe$/iu.test(entry.name)) {
+                try {
+                    const bytes = await fs.readBytes(path, signal, 64 * 1024 * 1024);
+                    found.utilities.push({ path, bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') });
+                }
+                catch {
+                    found.utilities.push({ path, bytes: 0, sha256: '' });
+                }
+                continue;
+            }
+            if (/^Gfx-ME.*\.xsd$/iu.test(entry.name))
+                found.schemas.push(path);
+            if (/\.chm$/iu.test(entry.name))
+                found.help.push(path);
+        }
+    }
+}
+/**
+ * Discover View Studio tooling under the configured roots.
+ *
+ * @param fs - Filesystem provider.
+ * @param roots - Absolute roots to search.
+ * @param signal - Cancellation.
+ * @returns What was found, plus the roots that were searched.
+ */
+export async function discoverStudio(fs, roots, signal) {
+    const found = { products: [], schemas: [], utilities: [], help: [], truncated: false };
+    const searched = [];
+    for (const root of roots) {
+        const resolved = await fs.resolve(root, {
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const info = await fs.stat(resolved, signal);
+        searched.push(resolved);
+        if (info === undefined || info.type !== 'directory')
+            continue;
+        await walkRoot(fs, resolved, signal, found);
+    }
+    return { searched, ...found };
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 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
+ */
+import type { Application } from '../model.ts';
+import type { StudioDiscovery } from './discover.ts';
+/** The result of checking one change set for Studio. */
+export interface StudioCheck {
+    readonly changed: readonly string[];
+    readonly blockers: readonly string[];
+    readonly warnings: readonly string[];
+    readonly ready: boolean;
+    readonly utility_available: boolean;
+}
+/** One manual step. */
+export interface HandoffStep {
+    readonly step: number;
+    readonly action: string;
+    readonly files?: readonly string[];
+}
+/** The manual plan. */
+export interface HandoffPlan {
+    readonly application: string;
+    readonly changed: readonly string[];
+    readonly steps: readonly HandoffStep[];
+    readonly utility_available: boolean;
+}
+/**
+ * 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 declare function studioPreflight(before: Application, after: Application, discovery: StudioDiscovery): StudioCheck;
+/**
+ * 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 declare function handoffPlan(before: Application, after: Application, discovery: StudioDiscovery): HandoffPlan;

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
+```