@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,270 @@
+/**
+ * The draft family: one operation per call, accumulated, validated, applied.
+ *
+ * Replaces a single tool that took a JSON string of every operation. Each tool
+ * here is flat, names its own intent, and returns the growing operation count,
+ * so a small model can see the draft take shape without holding a nested
+ * document in its head.
+ *
+ * @module dsh-engineering-l5x/tools/drafts
+ */
+import { prepareChangeSet } from "../engine/change-set.js";
+import { L5xError } from "../core/errors.js";
+import { success } from "../core/result.js";
+import { choice, integer, object, string } from "../core/params.js";
+import { PROJECT_ID, optionalInteger, optionalNumber, optionalString, requiredString, tool } from "./common.js";
+/** A prepared draft is not a Studio acceptance. */
+const DRAFT_COVERAGE = {
+    complete: false,
+    unverified: [
+        'Studio 5000 import and build are not performed by this surface',
+        'runtime behavior',
+        'the source export is never modified',
+    ],
+};
+/** The version-1 request the change-set engine accepts. */
+function requestOf(draft) {
+    return JSON.stringify({ version: 1, operations: draft.operations });
+}
+/** The success document every append answers with. */
+function appended(draft, operation) {
+    return success(`Draft ${draft.id}: ${draft.operations.length} ${draft.operations.length === 1 ? 'operation' : 'operations'}.`, { draft_id: draft.id, operation_count: draft.operations.length, last_operation: operation }, [{ tool: 'draft_validate', args: { draft_id: draft.id }, why: 'Validate the whole draft before writing anything.' }]);
+}
+/**
+ * The draft tools, bound to one chat's project and draft stores.
+ *
+ * @param session - Project handles for the calling chat.
+ * @param drafts - Drafts for the calling chat.
+ * @param maxOperations - Inclusive operations per draft.
+ * @param maxFileBytes - Byte budget the preparation may read.
+ * @returns Tool definitions in registration order.
+ */
+export function draftTools(session, drafts, maxOperations, maxFileBytes) {
+    return [
+        tool({
+            name: 'draft_rung',
+            description: 'Append one ladder rung operation to the chat draft: replace, insert or delete. Nothing is written until draft_apply.',
+            parameters: object({
+                program: string('Program that owns the routine. Example: "MainProgram".'),
+                routine: string('Routine the rung belongs to. Example: "MainRoutine".'),
+                mode: choice('replace rewrites an existing rung, insert adds one, delete removes one.', ['replace', 'insert', 'delete']),
+                rung: integer('Rung number the operation targets. Required for replace and delete; for insert it is the new rung number.', { minimum: 0 }),
+                text: string('NeutralText for replace or insert. Omit for delete. Example: "XIC(Start)OTE(Run);"'),
+                before_rung: integer('For insert only: insert before this rung number instead of after rung.', { minimum: 0 }),
+                project_id: PROJECT_ID,
+            }, ['program', 'routine', 'mode']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const program = requiredString(args, 'program');
+                const routine = requiredString(args, 'routine');
+                const mode = requiredString(args, 'mode');
+                const text = optionalString(args, 'text');
+                const rung = optionalInteger(args, 'rung');
+                const before = optionalInteger(args, 'before_rung');
+                let operation;
+                if (mode === 'delete') {
+                    if (rung === undefined)
+                        throw invalid('rung', 'Required when mode is delete.', 'Pass the rung number to remove.');
+                    operation = { operation: 'delete_rung', program, routine, rung };
+                }
+                else if (mode === 'replace') {
+                    if (rung === undefined || text === undefined)
+                        throw invalid('rung and text', 'Required when mode is replace.', 'Pass the rung number and its new NeutralText.');
+                    operation = { operation: 'replace_rung', program, routine, rung, text };
+                }
+                else if (mode === 'insert') {
+                    if (rung === undefined || text === undefined)
+                        throw invalid('rung and text', 'Required when mode is insert.', 'Pass the new rung number and its NeutralText.');
+                    operation = { operation: 'insert_rung', program, routine, rung, text, ...(before === undefined ? {} : { before_rung: before }) };
+                }
+                else {
+                    throw invalid('mode', `Unknown mode ${JSON.stringify(mode)}.`, 'Pass one of: replace, insert, delete.');
+                }
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'draft_st',
+            description: 'Append one Structured Text body replacement to the chat draft. Nothing is written until draft_apply.',
+            parameters: object({
+                program: string('Program that owns the routine. Example: "MainProgram".'),
+                routine: string('Structured Text routine to replace. Example: "Calc".'),
+                code: string('Full replacement body, one statement per line. Example: "Counter := Counter + 1;\\nIF Counter > 10 THEN Counter := 0; END_IF;"'),
+                project_id: PROJECT_ID,
+            }, ['program', 'routine', 'code']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const operation = {
+                    operation: 'replace_st',
+                    program: requiredString(args, 'program'),
+                    routine: requiredString(args, 'routine'),
+                    code: requiredString(args, 'code'),
+                };
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'draft_routine',
+            description: 'Append one new routine to the chat draft. Nothing is written until draft_apply.',
+            parameters: object({
+                program: string('Program that will own the new routine. Example: "MainProgram".'),
+                name: string('New routine name, a Logix identifier of at most 40 characters. Example: "Calc".'),
+                language: choice('Language of the new routine: RLL for ladder, ST for Structured Text.', ['RLL', 'ST']),
+                code: string('Body: NeutralText rungs for RLL, statements for ST.'),
+                project_id: PROJECT_ID,
+            }, ['program', 'name', 'language', 'code']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const operation = {
+                    operation: 'add_routine',
+                    program: requiredString(args, 'program'),
+                    name: requiredString(args, 'name'),
+                    language: requiredString(args, 'language'),
+                    code: requiredString(args, 'code'),
+                };
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'draft_tag',
+            description: 'Append one new tag to the chat draft. Nothing is written until draft_apply.',
+            parameters: object({
+                scope: string('Declaring scope: "controller" or a program name. Example: "controller".'),
+                name: string('New tag name, a Logix identifier of at most 40 characters. Example: "SP_Start".'),
+                data_type: string('Declared data type. Example: "REAL" or a UDT name.'),
+                description: string('Tag description shown in Studio. Example: "Start threshold".'),
+                value: integer('Optional scalar initial value. Example: 80.'),
+                dimensions: string('Optional array dimensions, space separated. Example: "4 2".'),
+                external_access: choice('Optional external access.', ['Read/Write', 'Read Only', 'None']),
+                project_id: PROJECT_ID,
+            }, ['scope', 'name', 'data_type', 'description']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const value = optionalNumber(args, 'value');
+                const dimensions = optionalString(args, 'dimensions');
+                const externalAccess = optionalString(args, 'external_access');
+                const operation = {
+                    operation: 'add_tag',
+                    scope: requiredString(args, 'scope'),
+                    name: requiredString(args, 'name'),
+                    data_type: requiredString(args, 'data_type'),
+                    description: requiredString(args, 'description'),
+                    ...(value === undefined ? {} : { value }),
+                    ...(dimensions === undefined ? {} : { dimensions }),
+                    ...(externalAccess === undefined ? {} : { external_access: externalAccess }),
+                };
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'draft_tag_description',
+            description: 'Append one existing tag description change to the chat draft. Nothing is written until draft_apply.',
+            parameters: object({
+                scope: string('Declaring scope: "controller" or a program name.'),
+                name: string('Existing tag name. Example: "LineSpeed".'),
+                description: string('New description text for the existing tag.'),
+                project_id: PROJECT_ID,
+            }, ['scope', 'name', 'description']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const operation = {
+                    operation: 'set_tag_description',
+                    scope: requiredString(args, 'scope'),
+                    name: requiredString(args, 'name'),
+                    description: requiredString(args, 'description'),
+                };
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'draft_udt_member',
+            description: 'Append one new member to a standard data type in the chat draft. Refused later if the type already has instances. Nothing is written until draft_apply.',
+            parameters: object({
+                udt: string('Existing standard data type name. Example: "Motor_UDT".'),
+                name: string('New member name. Example: "Speed".'),
+                data_type: string('Member data type. Example: "REAL".'),
+                description: string('Description text for the new member.'),
+                project_id: PROJECT_ID,
+            }, ['udt', 'name', 'data_type', 'description']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const operation = {
+                    operation: 'add_udt_member',
+                    udt: requiredString(args, 'udt'),
+                    name: requiredString(args, 'name'),
+                    data_type: requiredString(args, 'data_type'),
+                    description: requiredString(args, 'description'),
+                };
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'draft_udt_description',
+            description: 'Append one standard data type description change, or one member description change when member is supplied. Nothing is written until draft_apply.',
+            parameters: object({
+                udt: string('Existing standard data type name.'),
+                member: string('Member name to change. Omit to change the type description itself.'),
+                description: string('New description text for the type or the member.'),
+                project_id: PROJECT_ID,
+            }, ['udt', 'description']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const udt = requiredString(args, 'udt');
+                const description = requiredString(args, 'description');
+                const member = optionalString(args, 'member');
+                const operation = member === undefined
+                    ? { operation: 'set_udt_description', udt, description }
+                    : { operation: 'set_udt_member_description', udt, member, description };
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'draft_validate',
+            description: 'Validate the accumulated draft against the open project and return its hash, diff summary and check findings. Writes nothing.',
+            parameters: object({
+                draft_id: string('Draft handle returned by a draft_* tool. Omit when exactly one draft exists in this chat.'),
+                project_id: PROJECT_ID,
+            }, []),
+            async run(args, exec) {
+                const draft = drafts.get(exec, optionalString(args, 'draft_id'));
+                const project = await session.require(draft.projectId, exec);
+                const prepared = prepareChangeSet(project, requestOf(draft), { operations: maxOperations, bytes: maxFileBytes });
+                return success(`${draft.operations.length} ${draft.operations.length === 1 ? 'operation' : 'operations'} prepared; draft hash ${prepared.draft_sha256.slice(0, 12)}.`, {
+                    draft_id: draft.id,
+                    operation_count: draft.operations.length,
+                    source_sha256: prepared.source_sha256,
+                    draft_sha256: prepared.draft_sha256,
+                    validation: prepared.validation,
+                    checks: prepared.checks,
+                    diff: prepared.diff,
+                }, [{ tool: 'draft_apply', args: { draft_id: draft.id }, why: 'Write the validated draft to a new L5X.' }], DRAFT_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'draft_apply',
+            description: 'Apply the validated draft to ONE new L5X file beside the source. Never overwrites, never imports into Studio, never contacts a controller.',
+            parameters: object({
+                draft_id: string('Draft handle returned by a draft_* tool. Omit when exactly one draft exists in this chat.'),
+                output_path: string('New .L5X path to write. It must not exist.'),
+                project_id: PROJECT_ID,
+            }, ['output_path']),
+            async run(args, exec) {
+                const draft = drafts.get(exec, optionalString(args, 'draft_id'));
+                const project = await session.require(draft.projectId, exec);
+                const prepared = prepareChangeSet(project, requestOf(draft), { operations: maxOperations, bytes: maxFileBytes });
+                const target = await session.writeNew(requiredString(args, 'output_path'), prepared.xml, exec);
+                drafts.remove(exec, draft.id);
+                return success(`Wrote ${draft.operations.length} ${draft.operations.length === 1 ? 'operation' : 'operations'} to ${target}.`, {
+                    output_path: target,
+                    draft_sha256: prepared.draft_sha256,
+                    operation_count: draft.operations.length,
+                    validation: prepared.validation,
+                }, [{ tool: 'open_project', args: { path: target }, why: 'Reopen the written draft and review it.' }], DRAFT_COVERAGE);
+            },
+        }),
+    ];
+}
+/** One argument failure with the fix. */
+function invalid(field, message, fix) {
+    return new L5xError('INVALID_ARGUMENT', `${field}: ${message}`, fix);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * SDK-free live reads over EtherNet/IP.
+ *
+ * Two tools: a bounded foreground poll, and a session-owned trend job the chart
+ * can follow without a model call per sample. Both read declared scalar tags,
+ * never write, and state that live logic is not the exported logic.
+ *
+ * @module dsh-engineering-l5x/tools/live
+ */
+import type { PluginContext, ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+import { type DirectPolling } from '../engine/direct-polling.ts';
+/**
+ * The live tools.
+ *
+ * @param session - Project handles for the calling chat.
+ * @param polling - The polling engine and its configuration.
+ * @param ctx - Plugin context that may provide the job service.
+ * @returns Tool definitions in registration order.
+ */
+export declare function liveTools(session: ProjectSession, polling: DirectPolling, ctx: PluginContext): readonly ToolDefinition[];

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

@@ -0,0 +1,175 @@
+/**
+ * SDK-free live reads over EtherNet/IP.
+ *
+ * Two tools: a bounded foreground poll, and a session-owned trend job the chart
+ * can follow without a model call per sample. Both read declared scalar tags,
+ * never write, and state that live logic is not the exported logic.
+ *
+ * @module dsh-engineering-l5x/tools/live
+ */
+import { success } from "../core/result.js";
+import { integer, list, object, objectItem, string } from "../core/params.js";
+import { pollingRequest } from "../engine/direct-polling.js";
+import { L5xError } from "../core/errors.js";
+import { PROJECT_ID, optionalInteger, optionalString, requiredString, tool } from "./common.js";
+/** A direct read is not a guarantee about the scan. */
+const LIVE_COVERAGE = {
+    complete: false,
+    unverified: [
+        'live logic matching the exported logic',
+        'values synchronized to the controller scan',
+        'transitions between sweeps',
+    ],
+};
+/** The tags argument, as flat objects rather than a JSON string. */
+function tagsOf(args) {
+    const raw = args.tags;
+    if (!Array.isArray(raw)) {
+        throw new L5xError('INVALID_POLL', 'tags must be an array of 1 to 16 tag objects.', 'Pass [{ "name": "LineSpeed" }], not a JSON string.');
+    }
+    const tags = raw.map((entry) => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw new L5xError('INVALID_POLL', 'Each tag must be an object with a name.', 'Pass [{ "name": "LineSpeed" }].');
+        }
+        const row = entry;
+        const name = row.name;
+        if (typeof name !== 'string' || name === '') {
+            throw new L5xError('INVALID_POLL', 'Each tag needs a name.', 'Pass [{ "name": "LineSpeed" }].');
+        }
+        const program = row.program;
+        return program === undefined ? { name } : { name, scope: program };
+    });
+    return JSON.stringify(tags);
+}
+/** The same tag parameter for both tools. */
+const TAGS_PARAM = list('Controller-scoped scalar tags to read, 1 to 16. Each entry names the tag and optionally its program.', objectItem('One declared scalar tag.', {
+    name: string('Tag name. Example: "LineSpeed".'),
+    program: string('Program scope for a program-scoped tag. Omit for a controller tag.'),
+}, ['name']), { minItems: 1, maxItems: 16 });
+/**
+ * The live tools.
+ *
+ * @param session - Project handles for the calling chat.
+ * @param polling - The polling engine and its configuration.
+ * @param ctx - Plugin context that may provide the job service.
+ * @returns Tool definitions in registration order.
+ */
+export function liveTools(session, polling, ctx) {
+    return [
+        tool({
+            name: 'poll_live_tags',
+            description: 'Read declared scalar PLC tags directly over EtherNet/IP without Studio, FactoryTalk Linx, an ACD upload or the SDK. Explicit controller IPv4 and slot required. Returns timestamped sweeps, quality and controller identity; no writes.',
+            parameters: object({
+                project_id: PROJECT_ID,
+                ip_address: string('Controller IPv4 address the human named. Example: "192.168.1.10".'),
+                slot: integer('CPU slot, 0 to 31. Default 0.', { minimum: 0, maximum: 31, default: 0 }),
+                tags: TAGS_PARAM,
+                sample_count: integer('Number of sweeps to read. Default 1.', { minimum: 1, maximum: 1200, default: 1 }),
+                interval_ms: integer('Requested interval between sweeps. Default 200.', { minimum: 50, maximum: 600000, default: 200 }),
+            }, ['ip_address', 'tags']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const { request, evidence } = pollingRequest(project, {
+                    ip_address: requiredString(args, 'ip_address'),
+                    slot: optionalInteger(args, 'slot') ?? 0,
+                    sample_count: optionalInteger(args, 'sample_count') ?? 1,
+                    interval_ms: optionalInteger(args, 'interval_ms') ?? polling.config.defaultIntervalMs,
+                    tags_json: tagsOf(args),
+                }, polling.config);
+                const frames = await polling.start(request, () => { }, exec.signal).done;
+                await session.require(project.id, exec);
+                return success(`Read ${request.samples} sweep(s) from ${request.ip}.`, {
+                    project_id: project.id,
+                    source_sha256: project.sha256,
+                    ip_address: request.ip,
+                    slot: request.slot,
+                    provider: 'ethernet-ip',
+                    sdk_required: false,
+                    controller_contacted: true,
+                    live_logic_matches_export: 'unverified',
+                    requested_interval_ms: request.interval,
+                    evidence,
+                    controller: frames.find(frame => frame.type === 'identity'),
+                    samples: frames.filter(frame => frame.type === 'sample'),
+                    limitation: 'Sequential explicit reads can miss transitions and are not synchronized to the PLC scan.',
+                }, [], LIVE_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'start_plc_trend',
+            description: 'Start a bounded, read-only PLC trend as a session-owned background job. Explicit IPv4, slot and declared scalar tags required. SDK-independent EtherNet/IP; the chart follows the job without a model call per sample.',
+            parameters: object({
+                project_id: PROJECT_ID,
+                ip_address: string('Controller IPv4 address the human named. Example: "192.168.1.10".'),
+                slot: integer('CPU slot, 0 to 31. Default 0.', { minimum: 0, maximum: 31, default: 0 }),
+                tags: TAGS_PARAM,
+                sample_count: integer('Number of sweeps in the trend. Default 300.', { minimum: 1, maximum: 1200, default: 300 }),
+                interval_ms: integer('Requested interval between sweeps. Default 200.', { minimum: 50, maximum: 600000, default: 200 }),
+            }, ['ip_address', 'tags']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const { request, evidence } = pollingRequest(project, {
+                    ip_address: requiredString(args, 'ip_address'),
+                    slot: optionalInteger(args, 'slot') ?? 0,
+                    sample_count: optionalInteger(args, 'sample_count') ?? 300,
+                    interval_ms: optionalInteger(args, 'interval_ms') ?? polling.config.defaultIntervalMs,
+                    tags_json: tagsOf(args),
+                }, polling.config);
+                const jobs = ctx.get?.('jobs');
+                const owner = exec.sessionId;
+                if (jobs === undefined || owner === undefined) {
+                    throw new L5xError('TREND_JOBS_UNAVAILABLE', 'Live trends require the session-owned job service.', 'Use poll_live_tags for a foreground read, or run in a session with the jobs service.');
+                }
+                const jobId = jobs.start({
+                    kind: 'plc-trend',
+                    owner,
+                    label: `PLC trend ${request.ip} slot ${request.slot}`,
+                    run(job) {
+                        job.append(JSON.stringify({
+                            type: 'source',
+                            project_id: project.id,
+                            source_sha256: project.sha256,
+                            ip_address: request.ip,
+                            slot: request.slot,
+                            tags: request.tags,
+                            evidence,
+                            requested_interval_ms: request.interval,
+                            live_logic_matches_export: 'unverified',
+                        }) + '\n');
+                        const handle = polling.start(request, frame => job.append(JSON.stringify(frame) + '\n'));
+                        const done = handle.done
+                            .then(async (frames) => {
+                            await session.require(project.id);
+                            return {
+                                status: 'completed',
+                                result: JSON.stringify({
+                                    project_id: project.id,
+                                    source_sha256: project.sha256,
+                                    sample_count: frames.filter(frame => frame.type === 'sample').length,
+                                    live_logic_matches_export: 'unverified',
+                                }),
+                            };
+                        })
+                            .catch((error) => ({
+                            status: error instanceof L5xError && error.code === 'POLL_CANCELLED' ? 'killed' : 'failed',
+                            detail: error instanceof Error ? error.message : 'Polling failed',
+                        }));
+                        return { cancel: handle.cancel, done };
+                    },
+                });
+                return success(`Trend ${jobId} started for ${request.samples} sweep(s) from ${request.ip}.`, {
+                    job_id: jobId,
+                    owner_session_id: owner,
+                    project_id: project.id,
+                    source_sha256: project.sha256,
+                    provider: 'ethernet-ip',
+                    sample_count: request.samples,
+                    requested_interval_ms: request.interval,
+                    live_logic_matches_export: 'unverified',
+                    view: 'plc-trend',
+                    stop: 'Use the trend Stop control or stop the job.',
+                }, [], LIVE_COVERAGE);
+            },
+        }),
+    ];
+}

package/vendor/l5x/lib/tools/read.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The offline read surface: open, look, and read one component.
+ *
+ * Every tool answers with the same document — `summary`, `data`, optional
+ * `coverage`, and concrete `next` calls — and every expected failure answers
+ * with a code, a message and a fix. The tool descriptions name the one intent
+ * each tool serves; parameters carry their own meaning and an example.
+ *
+ * @module dsh-engineering-l5x/tools/read
+ */
+import type { ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+/**
+ * The offline tools, bound to one chat's project store.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export declare function readTools(session: ProjectSession): readonly ToolDefinition[];