@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/l5x/lib/engine/tag-resolution.js

@@ -0,0 +1,169 @@
+import { controllerElementOf } from "../model/parse.js";
+import { elementChildren, firstChild } from "../model/xml.js";
+const integerWidths = { SINT: 8, INT: 16, DINT: 32, LINT: 64 };
+const builtins = {
+    TIMER: { EN: 'BOOL', TT: 'BOOL', DN: 'BOOL', PRE: 'DINT', ACC: 'DINT' },
+    TIMER_T: { EN: 'BOOL', TT: 'BOOL', DN: 'BOOL', PRE: 'TIME', ACC: 'TIME' },
+    COUNTER: { CU: 'BOOL', CD: 'BOOL', DN: 'BOOL', OV: 'BOOL', UN: 'BOOL', PRE: 'DINT', ACC: 'DINT' },
+    STRING: { LEN: 'DINT', DATA: 'SINT' },
+};
+const declarations = new WeakMap();
+const key = (scope, name) => `${scope.toLowerCase()}::${name.toLowerCase()}`;
+const dimensionsOf = (element) => {
+    const value = element.attrs.Dimensions ?? element.attrs.Dimension ?? '';
+    return value === '' || value === '0' ? [] : value.split(/[,\s]+/u).map(Number);
+};
+function tableOf(document) {
+    const cached = declarations.get(document);
+    if (cached !== undefined)
+        return cached;
+    const table = new Map();
+    const add = (container, scope, family, child) => {
+        const entries = container === undefined ? undefined : firstChild(container, family);
+        if (entries === undefined)
+            return;
+        for (const element of elementChildren(entries, child)) {
+            const name = element.attrs.Name ?? '';
+            table.set(key(scope, name), { name, scope, type: element.attrs.DataType ?? '', dimensions: dimensionsOf(element), ...(element.attrs.AliasFor === undefined ? {} : { alias: element.attrs.AliasFor }) });
+        }
+    };
+    const controller = controllerElementOf(document);
+    add(controller, 'controller', 'Tags', 'Tag');
+    const programs = firstChild(controller, 'Programs');
+    if (programs !== undefined)
+        for (const program of elementChildren(programs, 'Program'))
+            add(program, program.attrs.Name ?? '', 'Tags', 'Tag');
+    const aois = firstChild(controller, 'AddOnInstructionDefinitions');
+    if (aois !== undefined)
+        for (const aoi of elementChildren(aois, 'AddOnInstructionDefinition')) {
+            const scope = `AOI::${aoi.attrs.Name ?? ''}`;
+            add(aoi, scope, 'Parameters', 'Parameter');
+            add(aoi, scope, 'LocalTags', 'LocalTag');
+        }
+    declarations.set(document, table);
+    return table;
+}
+function segmentsOf(symbol) {
+    const parts = [];
+    let start = 0;
+    let depth = 0;
+    for (let cursor = 0; cursor < symbol.length; cursor++) {
+        if (symbol[cursor] === '[')
+            depth++;
+        if (symbol[cursor] === ']')
+            depth--;
+        if (depth < 0)
+            return undefined;
+        if (symbol[cursor] === '.' && depth === 0) {
+            parts.push(symbol.slice(start, cursor));
+            start = cursor + 1;
+        }
+    }
+    if (depth !== 0)
+        return undefined;
+    parts.push(symbol.slice(start));
+    const result = [];
+    for (const part of parts) {
+        const matched = /^([A-Za-z_][A-Za-z0-9_:]*|\d+)(?:\[([^\[\]]+)\])?$/u.exec(part);
+        if (matched === null)
+            return undefined;
+        result.push({ name: matched[1], ...(matched[2] === undefined ? {} : { indices: matched[2].split(',').map(value => value.trim()) }) });
+    }
+    return result;
+}
+/** Resolve an address without discarding indices or assuming an absent member exists.
+ * @param document - Export containing tag, AOI and UDT declarations.
+ * @param scope - Program name, controller, or AOI::name.
+ * @param symbol - Address, optionally qualified as Program:name.Tag.
+ * @returns Resolution with canonical declaration spelling, final type, alias chain and unresolved reason.
+ */
+export function resolveTag(document, scope, symbol) {
+    const table = tableOf(document);
+    const aliases = [];
+    let indicesVerified = true;
+    const fail = (reason) => ({ symbol, scope, resolved: false, aliases, indices_verified: indicesVerified, reason });
+    let localScope = scope;
+    let address = symbol;
+    const qualified = /^Program:([A-Za-z_][A-Za-z0-9_]*)\.(.+)$/iu.exec(address);
+    if (qualified !== null) {
+        localScope = qualified[1];
+        address = qualified[2];
+    }
+    let segments = segmentsOf(address);
+    if (segments === undefined || segments.length === 0)
+        return fail('Malformed address');
+    let declaration = table.get(key(localScope, segments[0].name));
+    if (declaration === undefined && !localScope.startsWith('AOI::') && qualified === null)
+        declaration = table.get(key('controller', segments[0].name));
+    if (declaration === undefined)
+        return fail('Declaration is absent from the export');
+    const seen = new Set();
+    while (declaration.alias !== undefined) {
+        const identity = key(declaration.scope, declaration.name);
+        if (seen.has(identity))
+            return fail('Cyclic alias');
+        seen.add(identity);
+        aliases.push(`${declaration.scope}::${declaration.name}`);
+        const targetQualification = /^Program:([A-Za-z_][A-Za-z0-9_]*)\.(.+)$/iu.exec(declaration.alias);
+        const targetScope = targetQualification?.[1] ?? declaration.scope;
+        const target = segmentsOf(targetQualification?.[2] ?? declaration.alias);
+        if (target === undefined)
+            return fail('Malformed alias target');
+        if (segments[0].indices !== undefined)
+            return fail('Subscript on an alias requires explicit target verification');
+        segments = [...target, ...segments.slice(1)];
+        declaration = table.get(key(targetScope, target[0].name)) ?? (targetQualification === null ? table.get(key('controller', target[0].name)) : undefined);
+        if (declaration === undefined)
+            return fail('Alias target is absent from the export');
+    }
+    let dataType = declaration.type;
+    let dimensions = declaration.dimensions;
+    const canonical = [];
+    for (const [position, segment] of segments.entries()) {
+        let name = declaration.name;
+        if (position > 0) {
+            const previousType = dataType.toUpperCase();
+            if (/^\d+$/u.test(segment.name)) {
+                if (position !== segments.length - 1 || segment.indices !== undefined || Number(segment.name) >= (integerWidths[previousType] ?? 0))
+                    return fail('Invalid integer bit address');
+                name = segment.name;
+                dataType = 'BOOL';
+                dimensions = [];
+            }
+            else {
+                const builtin = builtins[previousType]?.[segment.name.toUpperCase()];
+                const udt = document.udts.find(entry => entry.name.toLowerCase() === dataType.toLowerCase());
+                const member = udt?.members.find(entry => entry.name.toLowerCase() === segment.name.toLowerCase());
+                const aoi = document.aois.find(entry => entry.name.toLowerCase() === dataType.toLowerCase());
+                const parameter = aoi?.parameters.find(entry => entry.name.toLowerCase() === segment.name.toLowerCase());
+                if (builtin === undefined && member === undefined && parameter === undefined)
+                    return fail(`Member ${segment.name} is absent from ${dataType}`);
+                name = member?.name ?? parameter?.name ?? segment.name.toUpperCase();
+                dataType = builtin ?? member?.dataType ?? parameter.dataType;
+                dimensions = member?.dimension === undefined ? [] : [member.dimension];
+                if (previousType === 'STRING' && name === 'DATA')
+                    dimensions = [82];
+            }
+        }
+        if (segment.indices !== undefined) {
+            if (segment.indices.length !== dimensions.length)
+                return fail('Array rank does not match its declaration');
+            for (const [index, value] of segment.indices.entries()) {
+                if (/^\d+$/u.test(value)) {
+                    if (Number(value) >= dimensions[index])
+                        return fail('Array subscript is outside its declared bounds');
+                }
+                else {
+                    if (/^-\d+$/u.test(value))
+                        return fail('Array subscript is negative');
+                    indicesVerified = false;
+                }
+            }
+            name += `[${segment.indices.join(',')}]`;
+        }
+        else if (dimensions.length > 0 && position !== segments.length - 1)
+            return fail('Array member requires a subscript');
+        canonical.push(name);
+    }
+    return { symbol, scope, resolved: true, canonical: `${declaration.scope}::${canonical.join('.')}`, data_type: dataType, aliases, indices_verified: indicesVerified };
+}

package/vendor/l5x/lib/engine/usage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Indexed and bit-level usage of one array tag.
+ *
+ * Reviewing alarm words, HMI index maps and timer tables means asking which
+ * elements and bits a program already uses. Parsing references answers that from
+ * the same evidence the reference tools report; it does not prove runtime
+ * consumption by an external HMI or another controller.
+ */
+import { type ProjectSnapshot } from '../session.ts';
+/** Map one declared tag's indexed and bit-level occurrences.
+ * @param project - Opened export.
+ * @param scope - Declaring scope: `controller` or a program name.
+ * @param name - Declared tag name.
+ * @returns Used and free element bits, read/write counts and examples.
+ */
+export declare function usageMap(project: ProjectSnapshot, scope: string, name: string): object;

package/vendor/l5x/lib/engine/usage.js

@@ -0,0 +1,92 @@
+/**
+ * Indexed and bit-level usage of one array tag.
+ *
+ * Reviewing alarm words, HMI index maps and timer tables means asking which
+ * elements and bits a program already uses. Parsing references answers that from
+ * the same evidence the reference tools report; it does not prove runtime
+ * consumption by an external HMI or another controller.
+ */
+import { evidenceOf } from "./analysis.js";
+import { EngineeringError } from "../session.js";
+/** Bits an element exposes when the declared type has a fixed width. */
+const ELEMENT_BITS = { DINT: 32, INT: 16, SINT: 8 };
+function rowOf(rows, index) {
+    const existing = rows.get(index);
+    if (existing !== undefined)
+        return existing;
+    const created = { index, bits: new Set(), reads: 0, writes: 0, unknown: 0, dynamic: false, examples: [] };
+    rows.set(index, created);
+    return created;
+}
+function count(row, access) {
+    if (access === 'read')
+        row.reads += 1;
+    else if (access === 'write')
+        row.writes += 1;
+    else
+        row.unknown += 1;
+}
+/** Map one declared tag's indexed and bit-level occurrences.
+ * @param project - Opened export.
+ * @param scope - Declaring scope: `controller` or a program name.
+ * @param name - Declared tag name.
+ * @returns Used and free element bits, read/write counts and examples.
+ */
+export function usageMap(project, scope, name) {
+    const tag = project.document.tags.find(entry => entry.name.toLowerCase() === name.toLowerCase() && entry.scope.toLowerCase() === scope.toLowerCase());
+    if (tag === undefined)
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `Tag ${name} is not declared in scope ${scope}`);
+    const rows = new Map();
+    const scopePrefix = `${tag.scope}::`.toLowerCase();
+    for (const reference of evidenceOf(project)) {
+        // The raw operand keeps array indices and bit digits that the canonical
+        // resolver drops; the resolved scope proves it names this declaration.
+        if (reference.resolved !== undefined && !reference.resolved.toLowerCase().startsWith(scopePrefix))
+            continue;
+        const raw = reference.symbol.toLowerCase();
+        if (!raw.startsWith(tag.name.toLowerCase()))
+            continue;
+        const suffix = reference.symbol.slice(tag.name.length);
+        // `Alarm` must not claim `Alarms[0]`; the next character settles it.
+        if (suffix !== '' && !/^[.[]/u.test(suffix))
+            continue;
+        // A member path after an index (`Alarms[0].6`) is a bit; a member after the
+        // tag itself (`Cooling.Blower_1`) is structure access, not an array index.
+        const indexes = [...suffix.matchAll(/\[([^\]]*)\]/gu)].map(match => match[1] ?? '');
+        const bits = [...suffix.replace(/\[[^\]]*\]/gu, '').matchAll(/\.(\d+)/gu)].map(match => Number.parseInt(match[1] ?? '', 10));
+        const wholeElement = indexes.length === 0;
+        const dynamic = indexes.some(value => !/^\d+$/u.test(value));
+        const index = dynamic || indexes.length === 0 ? null : Number.parseInt(indexes[0], 10);
+        const row = rowOf(rows, wholeElement ? null : index);
+        if (dynamic) {
+            row.dynamic = true;
+        }
+        else {
+            for (const bit of bits)
+                if (Number.isInteger(bit))
+                    row.bits.add(bit);
+        }
+        count(row, reference.access);
+        if (row.examples.length < 3)
+            row.examples.push(`${reference.routine}${reference.rung === undefined ? '' : ` rung ${reference.rung}`}${reference.line === undefined ? '' : ` line ${reference.line}`}: ${reference.symbol}`);
+    }
+    const width = ELEMENT_BITS[tag.dataType.toUpperCase()];
+    const indexes = [...rows.values()].filter(row => row.index !== null).sort((left, right) => left.index - right.index);
+    const whole = rows.get(null);
+    return {
+        project_id: project.id, source_sha256: project.sha256,
+        tag: { name: tag.name, scope: tag.scope, data_type: tag.dataType },
+        element_bit_width: width ?? null,
+        indexes: indexes.map(row => ({
+            index: row.index,
+            bits_used: [...row.bits].sort((left, right) => left - right),
+            bits_free: width === undefined ? null : Array.from({ length: width }, (_value, bit) => bit).filter(bit => !row.bits.has(bit)),
+            dynamic_index: row.dynamic,
+            reads: row.reads, writes: row.writes, unknown: row.unknown,
+            examples: row.examples,
+        })),
+        whole_element: whole === undefined ? null : { reads: whole.reads, writes: whole.writes, unknown: whole.unknown, bits_used: [...whole.bits].sort((left, right) => left - right), examples: whole.examples },
+        complete: false,
+        note: 'Counts cover exported RLL/ST/FBD operands only. External HMI, produced/consumed and driver consumers are not visible; dynamic indices are not expanded.',
+    };
+}

package/vendor/l5x/lib/engine/xml-regions.d.ts

@@ -0,0 +1,23 @@
+/** Element positions in the original export, including its start and closing tags. */
+export interface XmlRegion {
+    readonly kind: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly start: number;
+    readonly contentStart: number;
+    readonly contentEnd: number;
+    readonly end: number;
+    readonly children: readonly XmlRegion[];
+    readonly selfClosing: boolean;
+}
+/** Locate elements in XML that has already passed the L5X parser.
+ * @param xml - Validated export text.
+ * @returns Source regions; malformed or unsupported markup throws before editing.
+ */
+export declare function xmlRegions(xml: string): readonly XmlRegion[];
+/** Find exactly one direct child, with optional case-insensitive Logix name matching.
+ * @param parents - Source regions to search.
+ * @param kind - XML element name.
+ * @param name - Optional Name attribute.
+ * @returns Unique matching region, or throws for absent or ambiguous targets.
+ */
+export declare function uniqueRegion(parents: readonly XmlRegion[], kind: string, name?: string): XmlRegion;

package/vendor/l5x/lib/engine/xml-regions.js

@@ -0,0 +1,77 @@
+/** Locate validated XML elements without serializing untouched source bytes. */
+import { documentRoot, parseXml } from "../model/xml.js";
+import { EngineeringError } from "../session.js";
+/** Locate elements in XML that has already passed the L5X parser.
+ * @param xml - Validated export text.
+ * @returns Source regions; malformed or unsupported markup throws before editing.
+ */
+export function xmlRegions(xml) {
+    const roots = [];
+    const stack = [];
+    let cursor = 0;
+    while (cursor < xml.length) {
+        const start = xml.indexOf('<', cursor);
+        if (start < 0)
+            break;
+        const skip = xml.startsWith('<!--', start) ? '-->' : xml.startsWith('<![CDATA[', start) ? ']]>' : xml.startsWith('<?', start) ? '?>' : undefined;
+        if (skip !== undefined) {
+            const end = xml.indexOf(skip, start + 2);
+            if (end < 0)
+                throw new EngineeringError('INVALID_XML_REGION', 'Unterminated XML text block');
+            cursor = end + skip.length;
+            continue;
+        }
+        if (xml.startsWith('<!', start))
+            throw new EngineeringError('UNSUPPORTED_XML', 'XML declarations other than comments and CDATA cannot be edited');
+        let quote = '';
+        let end = start + 1;
+        for (; end < xml.length; end++) {
+            const char = xml[end];
+            if (quote !== '') {
+                if (char === quote)
+                    quote = '';
+            }
+            else if (char === '"' || char === "'")
+                quote = char;
+            else if (char === '>')
+                break;
+        }
+        if (end === xml.length)
+            throw new EngineeringError('INVALID_XML_REGION', 'Unterminated XML element');
+        cursor = end + 1;
+        const markup = xml.slice(start, cursor);
+        if (markup.startsWith('</')) {
+            const region = stack.pop();
+            if (region === undefined || markup.slice(2, -1).trim() !== region.kind)
+                throw new EngineeringError('INVALID_XML_REGION', 'Mismatched closing element');
+            region.contentEnd = start;
+            region.end = cursor;
+            continue;
+        }
+        const selfClosing = /\/\s*>$/u.test(markup);
+        const element = documentRoot(parseXml(selfClosing ? markup : markup.slice(0, -1) + '/>'));
+        const region = { kind: element.name, attributes: element.attrs, start, contentStart: cursor, contentEnd: cursor, end: cursor, children: [], selfClosing };
+        const parent = stack[stack.length - 1];
+        if (parent === undefined)
+            roots.push(region);
+        else
+            parent.children.push(region);
+        if (!selfClosing)
+            stack.push(region);
+    }
+    if (stack.length > 0)
+        throw new EngineeringError('INVALID_XML_REGION', 'Unclosed XML element');
+    return roots;
+}
+/** Find exactly one direct child, with optional case-insensitive Logix name matching.
+ * @param parents - Source regions to search.
+ * @param kind - XML element name.
+ * @param name - Optional Name attribute.
+ * @returns Unique matching region, or throws for absent or ambiguous targets.
+ */
+export function uniqueRegion(parents, kind, name) {
+    const matches = parents.filter(region => region.kind === kind && (name === undefined || region.attributes.Name?.toLowerCase() === name.toLowerCase()));
+    if (matches.length !== 1)
+        throw new EngineeringError('AMBIGUOUS_TARGET', `Expected one ${kind}${name === undefined ? '' : ` named ${name}`}; found ${matches.length}`);
+    return matches[0];
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Byte-to-text decoding for one Studio 5000 export.
+ *
+ * An export's encoding is a property of the machine that wrote it: Studio
+ * writes UTF-16 with a byte-order mark for some generated files and UTF-8 for
+ * others. The byte-order mark wins; the XML declaration is consulted only when
+ * there is none.
+ *
+ * @module dsh-engineering-l5x/fs
+ */
+/**
+ * Decode one export's bytes.
+ *
+ * @param bytes - The file contents.
+ * @returns The decoded XML text.
+ */
+export declare function decodeExport(bytes: Uint8Array): string;

package/vendor/l5x/lib/fs.js

@@ -0,0 +1,36 @@
+/**
+ * Byte-to-text decoding for one Studio 5000 export.
+ *
+ * An export's encoding is a property of the machine that wrote it: Studio
+ * writes UTF-16 with a byte-order mark for some generated files and UTF-8 for
+ * others. The byte-order mark wins; the XML declaration is consulted only when
+ * there is none.
+ *
+ * @module dsh-engineering-l5x/fs
+ */
+import { L5xError } from "./core/errors.js";
+/**
+ * Decode one export's bytes.
+ *
+ * @param bytes - The file contents.
+ * @returns The decoded XML text.
+ */
+export function decodeExport(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0xFF && bytes[1] === 0xFE)
+        return new TextDecoder('utf-16le').decode(bytes);
+    if (bytes.length >= 2 && bytes[0] === 0xFE && bytes[1] === 0xFF)
+        return new TextDecoder('utf-16be').decode(bytes);
+    if (bytes.length >= 3 && bytes[0] === 0xEF && bytes[1] === 0xBB && bytes[2] === 0xBF)
+        return new TextDecoder('utf-8').decode(bytes);
+    const head = new TextDecoder('latin1').decode(bytes.subarray(0, 256));
+    const declared = /^<\?xml[^>]*?encoding\s*=\s*["']([^"']+)["']/u.exec(head)?.[1];
+    if (declared !== undefined && declared.toLowerCase() !== 'utf-8') {
+        try {
+            return new TextDecoder(declared).decode(bytes);
+        }
+        catch {
+            throw new L5xError('UNSUPPORTED_ENCODING', `The export declares encoding ${JSON.stringify(declared)}, which this host cannot decode.`, 'Re-export the project as UTF-8 from Studio 5000 and reopen it.');
+        }
+    }
+    return new TextDecoder('utf-8').decode(bytes);
+}

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

@@ -0,0 +1,36 @@
+/**
+ * The rebuilt offline L5X read surface.
+ *
+ * Eleven read tools, one intent each, with described parameters, a
+ * summary-first result and repairable failures. The project handles it opens are
+ * provided as the `l5xProjects` service so the editing entry can draft against
+ * the same exports without opening them twice.
+ *
+ * @module dsh-engineering-l5x
+ */
+import type { PluginContext } from './core/tool.ts';
+/** Plugin name in a composition. */
+export declare const name = "l5x-read";
+/** Services this plugin cannot register without. */
+export declare const inject: readonly ["tools", "fs"];
+/** Service name the editing entry consumes. */
+export declare const PROJECTS_SERVICE = "l5xProjects";
+/** Configuration for the read surface. */
+export interface Config {
+    /** Largest export, in bytes, one open will read. Defaults to 64 MiB. */
+    maxFileBytes?: number;
+}
+/**
+ * Register the offline read surface.
+ *
+ * @param ctx - Plugin context with the tool registry and filesystem provider.
+ * @param config - Deployment limits.
+ */
+export declare function apply(ctx: PluginContext, config?: Config): void;
+export { ProjectSession } from './session.ts';
+export { readTools } from './tools/read.ts';
+export { referenceTools } from './tools/references.ts';
+export { checkTools } from './tools/checks.ts';
+export { L5xError } from './core/errors.ts';
+export type { NextStep, Coverage, Success } from './core/result.ts';
+export type { ToolDefinition } from './core/tool.ts';

package/vendor/l5x/lib/index.js

@@ -0,0 +1,42 @@
+/**
+ * The rebuilt offline L5X read surface.
+ *
+ * Eleven read tools, one intent each, with described parameters, a
+ * summary-first result and repairable failures. The project handles it opens are
+ * provided as the `l5xProjects` service so the editing entry can draft against
+ * the same exports without opening them twice.
+ *
+ * @module dsh-engineering-l5x
+ */
+import { ProjectSession } from "./session.js";
+import { readTools } from "./tools/read.js";
+import { referenceTools } from "./tools/references.js";
+import { checkTools } from "./tools/checks.js";
+/** Plugin name in a composition. */
+export const name = 'l5x-read';
+/** Services this plugin cannot register without. */
+export const inject = ['tools', 'fs'];
+/** Service name the editing entry consumes. */
+export const PROJECTS_SERVICE = 'l5xProjects';
+/**
+ * Register the offline read surface.
+ *
+ * @param ctx - Plugin context with the tool registry and filesystem provider.
+ * @param config - Deployment limits.
+ */
+export function apply(ctx, config = {}) {
+    const maxFileBytes = config.maxFileBytes ?? 64 * 1024 * 1024;
+    if (!Number.isInteger(maxFileBytes) || maxFileBytes <= 0) {
+        throw new Error('l5x-read: maxFileBytes must be a positive integer');
+    }
+    const session = new ProjectSession(ctx.fs, maxFileBytes);
+    ctx.provide?.(PROJECTS_SERVICE, session);
+    for (const definition of [...readTools(session), ...referenceTools(session), ...checkTools(session)]) {
+        ctx.tools.register(definition);
+    }
+}
+export { ProjectSession } from "./session.js";
+export { readTools } from "./tools/read.js";
+export { referenceTools } from "./tools/references.js";
+export { checkTools } from "./tools/checks.js";
+export { L5xError } from "./core/errors.js";

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

@@ -0,0 +1,48 @@
+/**
+ * The L5X live entry: SDK-free EtherNet/IP reads and trends.
+ *
+ * Reads use the package's polling worker and its own TCP connection, so no
+ * Studio 5000, FactoryTalk Linx service or SDK is required. The entry is off by
+ * default; enabling the row is the switch that permits controller traffic.
+ *
+ * @module dsh-engineering-l5x/live
+ */
+import type { PluginContext } from './core/tool.ts';
+/** Plugin name in a composition. */
+export declare const name = "l5x-live";
+/** The read entry's project service must already be mounted. */
+export declare const inject: readonly ["tools", "l5xProjects"];
+/** Configuration for the live entry. */
+export interface Config {
+    /** Permit controller traffic. Defaults to true; the entry row is the switch. */
+    enabled?: boolean;
+    /** Minimum requested sweep interval. Defaults to 50 ms. */
+    minIntervalMs?: number;
+    /** Default requested sweep interval. Defaults to 200 ms. */
+    defaultIntervalMs?: number;
+    /** Most scalar tags in one window. Defaults to 16. */
+    maxTags?: number;
+    /** Most sweeps in one window. Defaults to 1200. */
+    maxSamples?: number;
+    /** Longest window, in milliseconds. Defaults to 60000. */
+    maxDurationMs?: number;
+    /** Per-read driver timeout. Defaults to 3000 ms. */
+    requestTimeoutMs?: number;
+    /** Most simultaneous controller windows across chats. Defaults to 2. */
+    maxConcurrent?: number;
+    /** Optional IPv4 allowlist; empty permits any explicit address. */
+    allowedAddresses?: string[];
+    /** Chart redraw interval, independent of reads. Defaults to 250 ms. */
+    displayRefreshMs?: number;
+    /** Most points retained per chart. Defaults to 1200. */
+    displayMaxSamples?: number;
+}
+/**
+ * Register the live tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's project service.
+ * @param config - Deployment limits.
+ */
+export declare function apply(ctx: PluginContext, config?: Config): void;
+export { DirectPolling } from './engine/direct-polling.ts';
+export { liveTools } from './tools/live.ts';

package/vendor/l5x/lib/live.js

@@ -0,0 +1,48 @@
+/**
+ * The L5X live entry: SDK-free EtherNet/IP reads and trends.
+ *
+ * Reads use the package's polling worker and its own TCP connection, so no
+ * Studio 5000, FactoryTalk Linx service or SDK is required. The entry is off by
+ * default; enabling the row is the switch that permits controller traffic.
+ *
+ * @module dsh-engineering-l5x/live
+ */
+import { fileURLToPath } from 'node:url';
+import { DirectPolling } from "./engine/direct-polling.js";
+import { liveTools } from "./tools/live.js";
+import { PROJECTS_SERVICE } from "./index.js";
+/** Plugin name in a composition. */
+export const name = 'l5x-live';
+/** The read entry's project service must already be mounted. */
+export const inject = ['tools', PROJECTS_SERVICE];
+/**
+ * Register the live tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's project service.
+ * @param config - Deployment limits.
+ */
+export function apply(ctx, config = {}) {
+    const session = ctx.get?.(PROJECTS_SERVICE);
+    if (session === undefined) {
+        throw new Error('l5x-live: the l5xProjects service is unavailable; mount the L5X read entry before this one');
+    }
+    const polling = new DirectPolling(fileURLToPath(new URL('../poll-worker.mjs', import.meta.url)), {
+        enabled: config.enabled ?? true,
+        minIntervalMs: config.minIntervalMs ?? 50,
+        defaultIntervalMs: config.defaultIntervalMs ?? 200,
+        maxTags: config.maxTags ?? 16,
+        maxSamples: config.maxSamples ?? 1200,
+        maxDurationMs: config.maxDurationMs ?? 60_000,
+        requestTimeoutMs: config.requestTimeoutMs ?? 3000,
+        maxConcurrent: config.maxConcurrent ?? 2,
+        allowedAddresses: config.allowedAddresses ?? [],
+        displayRefreshMs: config.displayRefreshMs ?? 250,
+        displayMaxSamples: config.displayMaxSamples ?? 1200,
+    });
+    const effect = ctx.effect;
+    effect?.(() => () => { void polling.dispose(); });
+    for (const definition of liveTools(session, polling, ctx))
+        ctx.tools.register(definition);
+}
+export { DirectPolling } from "./engine/direct-polling.js";
+export { liveTools } from "./tools/live.js";

package/vendor/l5x/lib/model/aois.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Add-on-instruction reader.
+ *
+ * An AOI carries both its interface — parameters and local tags — and its
+ * internal logic, and both are reported together because an instruction is only
+ * usable when its pins and its behavior are known.
+ */
+import type { L5xAoiDefinition, L5xAoiInfo, L5xDocument } from './types.ts';
+import { type XmlElement } from './xml.ts';
+/**
+ * List the add-on instructions the controller defines.
+ *
+ * @param document - The parsed project.
+ * @returns One entry per instruction, in written order.
+ */
+export declare function listAois(document: L5xDocument): readonly L5xAoiInfo[];
+/**
+ * Read every add-on instruction, with its interface and internal logic.
+ *
+ * @param document - The parsed project.
+ * @returns One definition per instruction, in written order.
+ */
+export declare function getAois(document: L5xDocument): readonly L5xAoiDefinition[];
+/**
+ * Read one add-on instruction, with its interface and internal logic.
+ *
+ * @param document - The parsed project.
+ * @param name - Instruction name.
+ * @returns The definition, or undefined when the controller does not define
+ * that instruction.
+ */
+export declare function getAoi(document: L5xDocument, name: string): L5xAoiDefinition | undefined;
+/**
+ * Read every add-on instruction definition of a controller.
+ *
+ * @param controller - The controller element.
+ * @returns The definitions, in written order.
+ */
+export declare function buildAois(controller: XmlElement): readonly L5xAoiDefinition[];