@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

package/vendor/ftview/lib/edit/operations.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Text-level edits over an ME export.
+ *
+ * Every transform changes only the targeted bytes: an attribute on one tag, a
+ * display's name attribute, or one tag CSV row. Nothing is re-serialized, so
+ * unknown elements, comments and formatting survive.
+ *
+ * @module dsh-engineering-ftview/edit/operations
+ */
+/** Set one attribute on a display or one of its named objects. */
+export interface DisplaySetOperation {
+    readonly kind: 'display_set';
+    readonly file: string;
+    readonly object?: string;
+    readonly attribute: string;
+    readonly value: string;
+}
+/** Add a display by copying an existing display file under a new name. */
+export interface DisplayAddOperation {
+    readonly kind: 'display_add';
+    readonly copyFrom: string;
+    readonly name: string;
+}
+/** Insert or update one HMI tag row. */
+export interface TagUpsertOperation {
+    readonly kind: 'tag_upsert';
+    readonly name: string;
+    readonly description?: string;
+    readonly type?: string;
+}
+/** One staged edit. */
+export type EditOperation = DisplaySetOperation | DisplayAddOperation | TagUpsertOperation;
+/** Escape one XML attribute value. */
+export declare function escapeAttribute(value: string): string;
+/** Escape one CSV cell when it needs quoting. */
+export declare function encodeCell(value: string): string;
+/**
+ * Set one attribute on a display root or object, preserving the rest byte for byte.
+ *
+ * @param xml - Display XML.
+ * @param object - Object name, or undefined for the display root.
+ * @param attribute - Attribute to set; a plain XML name.
+ * @param value - New value.
+ * @returns The modified XML.
+ */
+export declare function setAttribute(xml: string, object: string | undefined, attribute: string, value: string): string;
+/**
+ * Rename a display root.
+ *
+ * @param xml - Display XML.
+ * @param name - New display name.
+ * @returns The modified XML.
+ */
+export declare function renameDisplay(xml: string, name: string): string;
+/**
+ * Insert or update one tag row in the CSV.
+ *
+ * @param csv - Whole tag CSV.
+ * @param tag - Tag name and the columns to set.
+ * @returns The modified CSV.
+ */
+export declare function upsertTag(csv: string, tag: TagUpsertOperation): string;

package/vendor/ftview/lib/edit/operations.js

@@ -0,0 +1,126 @@
+/**
+ * Text-level edits over an ME export.
+ *
+ * Every transform changes only the targeted bytes: an attribute on one tag, a
+ * display's name attribute, or one tag CSV row. Nothing is re-serialized, so
+ * unknown elements, comments and formatting survive.
+ *
+ * @module dsh-engineering-ftview/edit/operations
+ */
+import { EngineeringError } from "../core.js";
+import { splitCsv } from "../model.js";
+/** Escape one XML attribute value. */
+export function escapeAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+/** Escape one CSV cell when it needs quoting. */
+export function encodeCell(value) {
+    return /[";\r\n]/u.test(value) ? `"${value.replaceAll('"', '""')}"` : value;
+}
+/** Read one attribute from an attribute string. */
+function attributeValue(attributes, name) {
+    const match = new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, 'u').exec(attributes);
+    return match?.[2] ?? match?.[3];
+}
+/** Find the root tag or the tag whose name attribute equals `object`. */
+function findTag(xml, object) {
+    if (object === undefined) {
+        const root = /<([A-Za-z_][\w.:-]*)((?:[^<>"']|"[^"]*"|'[^']*')*?)(\/?)>/u.exec(xml);
+        if (root === null)
+            throw new EngineeringError('INVALID_DISPLAY', 'The display has no root element.', 'Open the display with ftview_get first; only display XML can be edited.');
+        return { start: root.index, end: root.index + root[0].length, attributes: root[2] ?? '', selfClosing: root[3] === '/' };
+    }
+    const pattern = /<([A-Za-z_][\w.:-]*)((?:[^<>"']|"[^"]*"|'[^']*')*?)(\/?)>/gu;
+    let match;
+    while ((match = pattern.exec(xml)) !== null) {
+        if (attributeValue(match[2] ?? '', 'name') === object) {
+            return { start: match.index, end: match.index + match[0].length, attributes: match[2] ?? '', selfClosing: match[3] === '/' };
+        }
+    }
+    throw new EngineeringError('COMPONENT_NOT_FOUND', `No object in this display is named ${JSON.stringify(object)}.`, 'Call ftview_get with kind "display" to see the object names, then set the attribute on one of them.');
+}
+/**
+ * Set one attribute on a display root or object, preserving the rest byte for byte.
+ *
+ * @param xml - Display XML.
+ * @param object - Object name, or undefined for the display root.
+ * @param attribute - Attribute to set; a plain XML name.
+ * @param value - New value.
+ * @returns The modified XML.
+ */
+export function setAttribute(xml, object, attribute, value) {
+    if (!/^[A-Za-z_][\w.:-]*$/u.test(attribute)) {
+        throw new EngineeringError('INVALID_ATTRIBUTE', `${JSON.stringify(attribute)} is not an XML attribute name.`, 'Pass a plain attribute name such as "visible" or "caption".');
+    }
+    const span = findTag(xml, object);
+    const existing = new RegExp(`\\b${attribute}\\s*=\\s*("[^"]*"|'[^']*')`, 'u');
+    let attributes;
+    if (existing.test(span.attributes)) {
+        attributes = span.attributes.replace(existing, `${attribute}="${escapeAttribute(value)}"`);
+    }
+    else {
+        attributes = `${span.attributes} ${attribute}="${escapeAttribute(value)}"`;
+    }
+    const tagName = /^<([A-Za-z_][\w.:-]*)/u.exec(xml.slice(span.start, span.end))?.[1] ?? '';
+    const rebuilt = `<${tagName}${attributes}${span.selfClosing ? '/' : ''}>`;
+    return xml.slice(0, span.start) + rebuilt + xml.slice(span.end);
+}
+/**
+ * Rename a display root.
+ *
+ * @param xml - Display XML.
+ * @param name - New display name.
+ * @returns The modified XML.
+ */
+export function renameDisplay(xml, name) {
+    return setAttribute(xml, undefined, 'name', name);
+}
+/**
+ * Insert or update one tag row in the CSV.
+ *
+ * @param csv - Whole tag CSV.
+ * @param tag - Tag name and the columns to set.
+ * @returns The modified CSV.
+ */
+export function upsertTag(csv, tag) {
+    const eol = csv.includes('\r\n') ? '\r\n' : '\n';
+    const lines = csv.split(/\r?\n/);
+    const versionIndex = lines.findIndex(line => line.includes('###002'));
+    if (versionIndex < 0) {
+        throw new EngineeringError('TAG_CSV_MISSING', 'The tag CSV has no `###002` version line.', 'Pass an export whose tag file is the documented CSV export.');
+    }
+    const headerIndex = lines.findIndex((line, index) => index > versionIndex && line.trim() !== '');
+    if (headerIndex < 0)
+        throw new EngineeringError('TAG_CSV_MISSING', 'The tag CSV has no header row.', 'Re-export the HMI tag database as a CSV.');
+    const header = splitCsv(lines[headerIndex]).map(cell => cell.trim());
+    const nameIndex = header.indexOf('Tag Name');
+    if (nameIndex < 0)
+        throw new EngineeringError('TAG_CSV_MISSING', 'The tag CSV header has no `Tag Name` column.', 'Re-export the HMI tag database as a CSV.');
+    const descriptionIndex = header.indexOf('Tag Description');
+    const typeIndex = header.indexOf('Tag Type');
+    if (tag.description !== undefined && descriptionIndex < 0)
+        throw new EngineeringError('TAG_CSV_UNSUPPORTED', 'This tag CSV has no `Tag Description` column.', 'Set only the type, or re-export with descriptions enabled.');
+    if (tag.type !== undefined && typeIndex < 0)
+        throw new EngineeringError('TAG_CSV_UNSUPPORTED', 'This tag CSV has no `Tag Type` column.', 'Set only the description, or re-export with tag types.');
+    const rowIndex = lines.findIndex((line, index) => index > headerIndex && line.trim() !== '' && (splitCsv(line)[nameIndex] ?? '').trim() === tag.name);
+    if (rowIndex >= 0) {
+        const cells = splitCsv(lines[rowIndex]);
+        if (tag.description !== undefined)
+            cells[descriptionIndex] = tag.description;
+        if (tag.type !== undefined)
+            cells[typeIndex] = tag.type;
+        lines[rowIndex] = cells.map(encodeCell).join(';');
+        return lines.join(eol);
+    }
+    const cells = new Array(header.length).fill('');
+    cells[nameIndex] = tag.name;
+    if (tag.description !== undefined)
+        cells[descriptionIndex] = tag.description;
+    if (tag.type !== undefined)
+        cells[typeIndex] = tag.type;
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.splice(lines.length - 1, 0, cells.map(encodeCell).join(';'));
+    else
+        lines.push(cells.map(encodeCell).join(';'));
+    return lines.join(eol);
+}

package/vendor/ftview/lib/edit/prepare.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Prepare staged edits against one opened export.
+ *
+ * Preparation reads the source files, applies every operation to the text, and
+ * re-parses the result. It writes nothing: apply is the only writer, and it
+ * writes to a new folder.
+ *
+ * @module dsh-engineering-ftview/edit/prepare
+ */
+import { type Coverage, type FsService } from '../core.ts';
+import { type Finding } from '../checks.ts';
+import { type Application } from '../model.ts';
+import { type EditOperation } from './operations.ts';
+/** One prepared edit set. */
+export interface PreparedEdit {
+    /** Files whose text changed, keyed by export-relative path. */
+    readonly texts: ReadonlyMap<string, string>;
+    /** Files the edit adds. */
+    readonly added: readonly string[];
+    /** Every file written by apply, including unchanged copies. */
+    readonly changed: readonly string[];
+    /** Findings after the edit. */
+    readonly findings: readonly Finding[];
+    /** Stable hash over the source hashes and the operations. */
+    readonly hash: string;
+}
+/** Coverage for anything derived from an export. */
+export declare const EDIT_COVERAGE: Coverage;
+/**
+ * Apply every operation to text and re-parse the result.
+ *
+ * @param fs - Filesystem provider.
+ * @param app - The opened export.
+ * @param operations - Staged operations.
+ * @param signal - Cancellation.
+ * @returns Prepared texts, findings and a hash.
+ */
+export declare function prepareEdit(fs: FsService, app: Application, operations: readonly EditOperation[], signal: AbortSignal | undefined): Promise<PreparedEdit>;

package/vendor/ftview/lib/edit/prepare.js

@@ -0,0 +1,133 @@
+/**
+ * Prepare staged edits against one opened export.
+ *
+ * Preparation reads the source files, applies every operation to the text, and
+ * re-parses the result. It writes nothing: apply is the only writer, and it
+ * writes to a new folder.
+ *
+ * @module dsh-engineering-ftview/edit/prepare
+ */
+import { createHash } from 'node:crypto';
+import { EngineeringError } from "../core.js";
+import { findingsOf } from "../checks.js";
+import { parseDisplay, parseTagCsv } from "../model.js";
+import { renameDisplay, setAttribute, upsertTag } from "./operations.js";
+/** Coverage for anything derived from an export. */
+export const EDIT_COVERAGE = {
+    complete: false,
+    unverified: [
+        'vendor XSD schema validation',
+        'Studio import and runtime behavior',
+        'native binary files are not copied by apply',
+        'unchanged text exports are copied verbatim',
+    ],
+};
+/** Decode UTF-8 file bytes. */
+function decode(bytes) {
+    return new TextDecoder('utf-8').decode(bytes);
+}
+/** Read one source file as text. */
+async function readText(fs, root, file, signal) {
+    return decode(await fs.readBytes(`${root}/${file}`, signal, 64 * 1024 * 1024));
+}
+/** The tag CSV the edit targets, refusing an ambiguous export. */
+function tagFileOf(app) {
+    if (app.tagFiles.length === 0) {
+        throw new EngineeringError('TAG_CSV_MISSING', 'This export has no tag CSV, so tags cannot be edited.', 'Export the HMI tag database as a CSV into the same folder, then reopen the export.');
+    }
+    if (app.tagFiles.length > 1) {
+        throw new EngineeringError('AMBIGUOUS_TAG_CSV', `This export has ${app.tagFiles.length} tag CSV files, so the edit target is ambiguous.`, 'Keep one tag CSV per export folder, then reopen and retry.', app.tagFiles);
+    }
+    return app.tagFiles[0];
+}
+/**
+ * Apply every operation to text and re-parse the result.
+ *
+ * @param fs - Filesystem provider.
+ * @param app - The opened export.
+ * @param operations - Staged operations.
+ * @param signal - Cancellation.
+ * @returns Prepared texts, findings and a hash.
+ */
+export async function prepareEdit(fs, app, operations, signal) {
+    const texts = new Map();
+    const added = [];
+    const displayByFile = new Map(app.displays.map(display => [display.file, display]));
+    const displayNames = new Set(app.displays.map(display => display.name));
+    for (const operation of operations) {
+        if (operation.kind === 'display_set') {
+            if (!displayByFile.has(operation.file)) {
+                throw new EngineeringError('COMPONENT_NOT_FOUND', `The draft targets ${operation.file}, which this export no longer contains.`, 'Reopen the export and stage the edit again.');
+            }
+            const current = texts.get(operation.file) ?? await readText(fs, app.root, operation.file, signal);
+            texts.set(operation.file, setAttribute(current, operation.object, operation.attribute, operation.value));
+            continue;
+        }
+        if (operation.kind === 'display_add') {
+            const source = app.displays.find(display => display.name === operation.copyFrom);
+            if (source === undefined) {
+                throw new EngineeringError('COMPONENT_NOT_FOUND', `No display is named ${JSON.stringify(operation.copyFrom)} to copy.`, 'Call ftview_list with kind "display" to see the display names.', [...displayNames].slice(0, 5));
+            }
+            if (displayNames.has(operation.name) || added.includes(operation.name)) {
+                throw new EngineeringError('COMPONENT_EXISTS', `A display named ${JSON.stringify(operation.name)} already exists in this export or draft.`, 'Pass a new display name, for example "LineOverview2".');
+            }
+            const text = renameDisplay(await readText(fs, app.root, source.file, signal), operation.name);
+            const directory = source.file.includes('/') ? source.file.slice(0, source.file.lastIndexOf('/') + 1) : '';
+            const target = `${directory}${operation.name}.xml`;
+            if (app.files.some(file => file.file.toLowerCase() === target.toLowerCase())) {
+                throw new EngineeringError('COMPONENT_EXISTS', `The export already has a file ${target}.`, 'Pass a different new display name.');
+            }
+            texts.set(target, text);
+            added.push(target);
+            displayNames.add(operation.name);
+            continue;
+        }
+        const tagFile = tagFileOf(app);
+        const current = texts.get(tagFile) ?? await readText(fs, app.root, tagFile, signal);
+        texts.set(tagFile, upsertTag(current, operation));
+    }
+    const displays = [];
+    for (const display of app.displays) {
+        const text = texts.get(display.file);
+        if (text === undefined) {
+            displays.push(display);
+            continue;
+        }
+        const parsed = parseDisplay(display.file, text);
+        if (parsed.parseError !== undefined) {
+            throw new EngineeringError('INVALID_DISPLAY', `The edited ${display.file} no longer parses: ${parsed.parseError}`, 'Undo the last operation and check the display file, then stage it again.');
+        }
+        displays.push(parsed);
+    }
+    for (const file of added) {
+        const text = texts.get(file);
+        const parsed = parseDisplay(file, text);
+        if (parsed.parseError !== undefined) {
+            throw new EngineeringError('INVALID_DISPLAY', `The added ${file} does not parse: ${parsed.parseError}`, 'Copy a different display or pass another name.');
+        }
+        displays.push(parsed);
+    }
+    let tags = app.tags;
+    let tagErrors = app.tagErrors;
+    for (const [file, text] of texts) {
+        if (!app.tagFiles.includes(file))
+            continue;
+        const parsed = parseTagCsv(text);
+        tags = parsed.rows;
+        tagErrors = parsed.errors;
+    }
+    const changedFiles = new Set([...texts.keys()]);
+    const diagnostics = app.diagnostics.filter(diagnostic => {
+        const file = diagnostic.split(':')[0] ?? '';
+        return !changedFiles.has(file);
+    });
+    const findings = findingsOf({ displays, tags, tagErrors, diagnostics });
+    const hashInput = app.files.map(file => `${file.file}:${file.sha256}`).join('\n') + '\n' + JSON.stringify(operations);
+    return {
+        texts,
+        added,
+        changed: [...app.files.map(file => file.file), ...added],
+        findings,
+        hash: createHash('sha256').update(hashInput).digest('hex'),
+    };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * The FTView editing tools: stage, validate, apply.
+ *
+ * One operation per call, accumulated per chat and export, validated against a
+ * re-parsed copy, then written to a new export folder. The source is never
+ * modified.
+ *
+ * @module dsh-engineering-ftview/edit/tools
+ */
+import { type FsService, type ToolDefinition } from '../core.ts';
+import type { ViewSession } from '../session.ts';
+import type { EditDrafts } from './drafts.ts';
+import type { EditOperation } from './operations.ts';
+/**
+ * The editing tools.
+ *
+ * @param session - View handles from the read entry.
+ * @param drafts - Draft store for the calling chat.
+ * @param fs - Filesystem provider used to read sources and write the result.
+ * @param maxOperations - Inclusive operations per draft.
+ * @returns Tool definitions in registration order.
+ */
+export declare function editTools(session: ViewSession, drafts: EditDrafts, fs: FsService, maxOperations: number): readonly ToolDefinition[];
+/** A helper kept for callers that want the operation count type. */
+export type { EditOperation };

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

@@ -0,0 +1,198 @@
+/**
+ * The FTView editing tools: stage, validate, apply.
+ *
+ * One operation per call, accumulated per chat and export, validated against a
+ * re-parsed copy, then written to a new export folder. The source is never
+ * modified.
+ *
+ * @module dsh-engineering-ftview/edit/tools
+ */
+import { createHash } from 'node:crypto';
+import { EngineeringError, object, optionalString, requiredString, string, success, tool } from "../core.js";
+import { EDIT_COVERAGE, prepareEdit } from "./prepare.js";
+/** 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.');
+/** The draft handle parameter, described once. */
+const DRAFT_ID = string('Draft handle returned by an ftview_draft_* tool. Omit when exactly one draft exists in this chat.');
+/** Coverage for apply, which writes text exports only. */
+const APPLY_COVERAGE = {
+    ...EDIT_COVERAGE,
+    unverified: [...EDIT_COVERAGE.unverified, 'files that are not display XML or tag CSV are not copied'],
+};
+/** The next step after staging an operation. */
+function nextValidate(draftId) {
+    return [{ tool: 'ftview_validate', args: { draft_id: draftId }, why: 'Prepare the changed export and read the findings before writing anything.' }];
+}
+/** Count duplicate named objects in one display. */
+function objectCount(display, name) {
+    return display.objects.filter(object => object.name === name).length;
+}
+/**
+ * The editing tools.
+ *
+ * @param session - View handles from the read entry.
+ * @param drafts - Draft store for the calling chat.
+ * @param fs - Filesystem provider used to read sources and write the result.
+ * @param maxOperations - Inclusive operations per draft.
+ * @returns Tool definitions in registration order.
+ */
+export function editTools(session, drafts, fs, maxOperations) {
+    /** Resolve the view and append one operation. */
+    const stage = (exec, viewId, operation) => {
+        const view = session.require(viewId, exec);
+        return { view, draft: drafts.append(exec, view.id, operation, maxOperations) };
+    };
+    const staged = (draft, operation) => 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 }, nextValidate(draft.id), EDIT_COVERAGE);
+    return [
+        tool({
+            name: 'ftview_draft_display_set',
+            description: 'Stage one attribute change on a display or on one of its named objects. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list. Example: "Main".'),
+                object: string('Object name inside the display. Omit to change the display root. Example: "StartPB".'),
+                attribute: string('Attribute to set. Example: "visible" or "caption".'),
+                value: string('New attribute value. Example: "0".'),
+            }, ['display', 'attribute', 'value']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const displayName = requiredString(args, 'display');
+                const display = view.app.displays.find(candidate => candidate.name === displayName);
+                if (display === undefined) {
+                    throw new EngineeringError('COMPONENT_NOT_FOUND', `No display is named ${JSON.stringify(displayName)} in this export.`, 'Call ftview_list with kind "display" to see the display names.', view.app.displays.slice(0, 5).map(candidate => candidate.name));
+                }
+                const objectName = optionalString(args, 'object');
+                if (objectName !== undefined) {
+                    const count = objectCount(display, objectName);
+                    if (count === 0) {
+                        throw new EngineeringError('COMPONENT_NOT_FOUND', `No object in ${JSON.stringify(display.name)} is named ${JSON.stringify(objectName)}.`, 'Call ftview_get with kind "display" to see the object names.', display.objects.flatMap(candidate => candidate.name === undefined ? [] : [candidate.name]).slice(0, 5));
+                    }
+                    if (count > 1) {
+                        throw new EngineeringError('AMBIGUOUS_OBJECT', `${display.name} has ${count} objects named ${JSON.stringify(objectName)}, so the edit target is ambiguous.`, 'This export cannot be edited by name alone; use Studio for that display.');
+                    }
+                }
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'display_set',
+                    file: display.file,
+                    ...(objectName === undefined ? {} : { object: objectName }),
+                    attribute: requiredString(args, 'attribute'),
+                    value: requiredString(args, 'value'),
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_display_add',
+            description: 'Stage a new display by copying an existing display file under a new name. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                copy_from: string('Display name to copy. Example: "Main".'),
+                name: string('New display name, unique in the export. Example: "MainCopy".'),
+            }, ['copy_from', 'name']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const copyFrom = requiredString(args, 'copy_from');
+                const name = requiredString(args, 'name');
+                if (!view.app.displays.some(display => display.name === copyFrom)) {
+                    throw new EngineeringError('COMPONENT_NOT_FOUND', `No display is named ${JSON.stringify(copyFrom)} to copy.`, 'Call ftview_list with kind "display" to see the display names.', view.app.displays.slice(0, 5).map(display => display.name));
+                }
+                if (view.app.displays.some(display => display.name === name)) {
+                    throw new EngineeringError('COMPONENT_EXISTS', `A display named ${JSON.stringify(name)} already exists in this export.`, 'Pass a new display name, for example "LineOverview2".');
+                }
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'display_add',
+                    copyFrom,
+                    name,
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_tag_upsert',
+            description: 'Stage one HMI tag update: change an existing row\'s description or type, or append a new tag row. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                name: string('Tag name. Example: "StartPB".'),
+                description: string('New tag description. Example: "Start pushbutton".'),
+                type: string('New tag type. Example: "A" for analog or "D" for digital.'),
+            }, ['name']),
+            async run(args, exec) {
+                const description = optionalString(args, 'description');
+                const type = optionalString(args, 'type');
+                if (description === undefined && type === undefined) {
+                    throw new EngineeringError('INVALID_ARGUMENT', 'A tag upsert needs a description, a type, or both.', 'Pass description, type, or both; for example "Start pushbutton".');
+                }
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'tag_upsert',
+                    name: requiredString(args, 'name'),
+                    ...(description === undefined ? {} : { description }),
+                    ...(type === undefined ? {} : { type }),
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_validate',
+            description: 'Prepare the staged edits: apply them to a re-parsed copy, report the changed files and the new structural findings. Writes nothing.',
+            parameters: object({ draft_id: DRAFT_ID }, []),
+            async run(args, exec) {
+                const draft = drafts.get(exec, optionalString(args, 'draft_id'));
+                const view = session.require(draft.viewId, exec);
+                const prepared = await prepareEdit(fs, view.app, draft.operations, exec.signal);
+                const byRule = {};
+                for (const finding of prepared.findings)
+                    byRule[finding.rule] = (byRule[finding.rule] ?? 0) + 1;
+                return success(`${draft.operations.length} operation(s); ${prepared.texts.size} file(s) change; ${prepared.findings.length} finding(s).`, {
+                    draft_id: draft.id,
+                    draft_sha256: prepared.hash,
+                    changed_files: [...prepared.texts.keys()],
+                    added: prepared.added,
+                    findings: prepared.findings,
+                    by_rule: byRule,
+                }, [{ tool: 'ftview_apply', args: { draft_id: draft.id }, why: 'Write the prepared export to a new folder.' }], EDIT_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_apply',
+            description: 'Write the prepared edits to a NEW export folder: changed files get the edits, other text exports are copied verbatim. The source folder is never modified.',
+            parameters: object({
+                draft_id: DRAFT_ID,
+                output_root: string('New folder for the edited export. It must not exist. Example: "C:/Projects/Line/ME Export Edited".'),
+            }, ['output_root']),
+            async run(args, exec) {
+                const draft = drafts.get(exec, optionalString(args, 'draft_id'));
+                const view = session.require(draft.viewId, exec);
+                const prepared = await prepareEdit(fs, view.app, draft.operations, exec.signal);
+                const outputRoot = await fs.resolve(requiredString(args, 'output_root'), {
+                    ...(exec.cwd === undefined ? {} : { cwd: exec.cwd }),
+                    ...(exec.signal === undefined ? {} : { signal: exec.signal }),
+                });
+                const existing = await fs.stat(outputRoot, exec.signal);
+                if (existing !== undefined) {
+                    throw new EngineeringError('OUTPUT_EXISTS', `A file or folder already exists at ${requiredString(args, 'output_root')}.`, 'Pass a new output_root; apply never merges into an existing folder.');
+                }
+                if (fs.writeText === undefined) {
+                    throw new EngineeringError('OUTPUT_UNAVAILABLE', 'The filesystem provider in this profile cannot write files.', 'Use a profile whose filesystem provider allows writes.');
+                }
+                const hashes = new Map(view.app.files.map(file => [file.file, file.sha256]));
+                let written = 0;
+                for (const file of view.app.files) {
+                    const bytes = await fs.readBytes(`${view.app.root}/${file.file}`, exec.signal, 64 * 1024 * 1024);
+                    if (createHash('sha256').update(bytes).digest('hex') !== hashes.get(file.file)) {
+                        throw new EngineeringError('STALE_EXPORT', `The export changed on disk since it was opened: ${file.file}.`, 'Reopen the export with ftview_open, stage the edits again, then apply.');
+                    }
+                    const text = prepared.texts.get(file.file) ?? new TextDecoder('utf-8').decode(bytes);
+                    await fs.writeText(`${outputRoot}/${file.file}`, text, { kind: 'createIfAbsent' }, exec.signal);
+                    written += 1;
+                }
+                for (const file of prepared.added) {
+                    const text = prepared.texts.get(file);
+                    await fs.writeText(`${outputRoot}/${file}`, text, { kind: 'createIfAbsent' }, exec.signal);
+                    written += 1;
+                }
+                drafts.remove(exec, draft.id);
+                return success(`Wrote ${written} file(s) to ${outputRoot}.`, { output_root: outputRoot, draft_id: draft.id, files_written: written, changed_files: [...prepared.texts.keys()] }, [{ tool: 'ftview_open', args: { root: outputRoot }, why: 'Reopen the written export and check it.' }], APPLY_COVERAGE);
+            },
+        }),
+    ];
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The L5X-style editing entry for FactoryTalk View ME: drafts over the read
+ * entry's opened views.
+ *
+ * Separate so a read-only profile does not pay for five edit schemas. It
+ * consumes the `ftviewViews` service the read entry provides, so an export is
+ * scanned once and both entries see the same handle.
+ *
+ * @module dsh-engineering-ftview/edit
+ */
+import { type PluginContext } from './core.ts';
+/** Plugin name in a composition. */
+export declare const name = "ftview-edit";
+/** The read entry's view service must already be mounted. */
+export declare const inject: readonly ["tools", "fs", "ftviewViews"];
+/** Configuration for the editing entry. */
+export interface Config {
+    /** Most operations one draft may accumulate. Defaults to 100. */
+    maxDraftOperations?: number;
+}
+/**
+ * Register the editing 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 { EditDrafts } from './edit/drafts.ts';
+export { editTools } from './edit/tools.ts';
+export { prepareEdit } from './edit/prepare.ts';

package/vendor/ftview/lib/edit.js

@@ -0,0 +1,38 @@
+/**
+ * The L5X-style editing entry for FactoryTalk View ME: drafts over the read
+ * entry's opened views.
+ *
+ * Separate so a read-only profile does not pay for five edit schemas. It
+ * consumes the `ftviewViews` service the read entry provides, so an export is
+ * scanned once and both entries see the same handle.
+ *
+ * @module dsh-engineering-ftview/edit
+ */
+import { stringFs } from "./core.js";
+import { EditDrafts } from "./edit/drafts.js";
+import { editTools } from "./edit/tools.js";
+/** Plugin name in a composition. */
+export const name = 'ftview-edit';
+/** The read entry's view service must already be mounted. */
+export const inject = ['tools', 'fs', 'ftviewViews'];
+/**
+ * Register the editing 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-edit: the ftviewViews service is unavailable; mount the FTView read entry before this one');
+    }
+    const maxDraftOperations = config.maxDraftOperations ?? 100;
+    if (!Number.isInteger(maxDraftOperations) || maxDraftOperations <= 0) {
+        throw new Error('ftview-edit: maxDraftOperations must be a positive integer');
+    }
+    for (const definition of editTools(session, new EditDrafts(), stringFs(ctx.fs), maxDraftOperations))
+        ctx.tools.register(definition);
+}
+export { EditDrafts } from "./edit/drafts.js";
+export { editTools } from "./edit/tools.js";
+export { prepareEdit } from "./edit/prepare.js";