@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/ftview/lib/core.js

@@ -0,0 +1,160 @@
+/**
+ * Shared result, error and parameter conventions for the engineering bundle.
+ *
+ * Every tool answers with `summary`, `data`, `next` and `coverage`, and every
+ * parameter is described at the point of declaration. Failures carry a stable
+ * code, a message in the reader's terms, and the fix that unblocks the caller.
+ *
+ * @module dsh-engineering-ftview/core
+ */
+/** A failure the caller can usually repair. */
+export class EngineeringError extends Error {
+    code;
+    fix;
+    candidates;
+    /**
+     * @param code - Stable identifier for tests and logs.
+     * @param message - What failed, in the reader's terms.
+     * @param fix - The next call or check.
+     * @param candidates - Known names the caller probably meant.
+     */
+    constructor(code, message, fix, candidates = []) {
+        super(message);
+        this.name = 'EngineeringError';
+        this.code = code;
+        this.fix = fix;
+        this.candidates = candidates;
+    }
+}
+/**
+ * Convert any thrown value into the error envelope.
+ *
+ * @param error - The thrown value.
+ * @returns The envelope the tool registry reports.
+ */
+export function errorEnvelope(error) {
+    if (error instanceof EngineeringError) {
+        return { error: { code: error.code, message: error.message, fix: error.fix, candidates: error.candidates } };
+    }
+    return {
+        error: {
+            code: 'INTERNAL',
+            message: error instanceof Error ? error.message : String(error),
+            fix: 'Retry the call; if it fails the same way, report the message and the arguments used.',
+            candidates: [],
+        },
+    };
+}
+/** Build one success document. */
+export function success(summary, data, next, coverage) {
+    return { summary, data, next, coverage };
+}
+/** A described string parameter. */
+export function string(description, extra = {}) {
+    return { type: 'string', description, ...extra };
+}
+/** A described integer parameter with an optional range. */
+export function integer(description, extra = {}) {
+    return { type: 'integer', description, ...extra };
+}
+/** A described enum parameter. */
+export function choice(description, values, extra = {}) {
+    return { type: 'string', description, enum: values, ...extra };
+}
+/** One object element of an array parameter. */
+export function objectItem(description, properties, required = []) {
+    return { type: 'object', description, properties, required, additionalProperties: false };
+}
+/** An array of one parameter type. */
+export function list(description, items, extra = {}) {
+    return { type: 'array', description, items, ...extra };
+}
+/**
+ * Build a parameter object.
+ *
+ * @param properties - Named parameters, each already described.
+ * @param required - Names the caller must supply.
+ * @returns The schema a tool definition declares.
+ */
+export function object(properties, required = []) {
+    return { type: 'object', properties, required, additionalProperties: false };
+}
+/**
+ * Present the harness filesystem with string paths.
+ *
+ * The model, edits and discovery compose paths (`${root}/${file}`); the harness
+ * service takes opaque targets. This adapter resolves each path before calling
+ * the service and returns display strings, so path composition stays readable.
+ * A provider that already returns strings, such as a test double, passes through.
+ *
+ * @param service - The harness filesystem service.
+ * @returns The same operations addressed by path strings.
+ */
+export function stringFs(service) {
+    const targetOf = async (path, signal) => await service.resolve(path, signal === undefined ? {} : { signal });
+    const fs = {
+        async resolve(path, options) {
+            const value = await service.resolve(path, options);
+            return typeof value === 'string' ? value : value.displayPath;
+        },
+        async stat(path, signal) {
+            return await service.stat(await targetOf(path, signal), signal);
+        },
+        async readBytes(path, signal, maxBytes) {
+            return await service.readBytes(await targetOf(path, signal), signal, maxBytes);
+        },
+    };
+    if (service.listDir !== undefined) {
+        fs.listDir = async (path, signal) => await service.listDir(await targetOf(path, signal), signal);
+    }
+    if (service.writeText !== undefined) {
+        fs.writeText = async (path, text, options, signal) => {
+            await service.writeText(await targetOf(path, signal), text, options, signal);
+        };
+    }
+    return fs;
+}
+/** Render one tool answer as JSON text for the transcript. */
+function jsonText(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+/**
+ * Wrap one tool body in the shared envelope and error handling.
+ *
+ * @param spec - Tool identity and body.
+ * @returns The definition the registry accepts.
+ */
+export function tool(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.parameters,
+        output: { schema: { type: 'object', additionalProperties: true }, render: jsonText },
+        async execute(args, exec) {
+            try {
+                return await spec.run(args, exec);
+            }
+            catch (error) {
+                return errorEnvelope(error);
+            }
+        },
+    };
+}
+/** A required string argument. */
+export function requiredString(args, name) {
+    const value = args[name];
+    if (typeof value !== 'string' || value === '') {
+        throw new EngineeringError('INVALID_ARGUMENT', `${name} is required and must be a non-empty string.`, `Pass ${name}, for example "${name}".`);
+    }
+    return value;
+}
+/** An optional string argument. */
+export function optionalString(args, name) {
+    const value = args[name];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/** An optional integer argument. */
+export function optionalInteger(args, name) {
+    const value = args[name];
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Drafts for staged ME edits.
+ *
+ * One draft per opened export per chat. Operations accumulate until validate or
+ * apply; nothing here reads or writes export files.
+ *
+ * @module dsh-engineering-ftview/edit/drafts
+ */
+import { type ExecContext } from '../core.ts';
+import type { EditOperation } from './operations.ts';
+/** One accumulated edit list. */
+export interface EditDraft {
+    readonly id: string;
+    readonly viewId: string;
+    readonly operations: readonly EditOperation[];
+    readonly createdAt: string;
+}
+/** Drafts, scoped to the chat that created them. */
+export declare class EditDrafts {
+    private readonly chats;
+    private readonly detached;
+    /**
+     * Append one operation to the draft for a view, creating it on first use.
+     *
+     * @param exec - Calling context.
+     * @param viewId - View the draft edits.
+     * @param operation - Operation to append.
+     * @param maxOperations - Inclusive cap for one draft.
+     * @returns The updated draft.
+     */
+    append(exec: ExecContext | undefined, viewId: string, operation: EditOperation, maxOperations: number): EditDraft;
+    /**
+     * Resolve one draft by handle.
+     *
+     * @param exec - Calling context.
+     * @param id - Draft handle; empty selects the chat's only draft.
+     * @returns The draft.
+     */
+    get(exec: ExecContext | undefined, id: string | undefined): EditDraft;
+    /**
+     * Drop one draft after it is applied.
+     *
+     * @param exec - Calling context.
+     * @param id - Draft handle.
+     */
+    remove(exec: ExecContext | undefined, id: string): void;
+    /** The draft map for one calling chat. */
+    private draftsOf;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Drafts for staged ME edits.
+ *
+ * One draft per opened export per chat. Operations accumulate until validate or
+ * apply; nothing here reads or writes export files.
+ *
+ * @module dsh-engineering-ftview/edit/drafts
+ */
+import { randomUUID } from 'node:crypto';
+import { EngineeringError } from "../core.js";
+/** Drafts, scoped to the chat that created them. */
+export class EditDrafts {
+    chats = new WeakMap();
+    detached = new Map();
+    /**
+     * Append one operation to the draft for a view, creating it on first use.
+     *
+     * @param exec - Calling context.
+     * @param viewId - View the draft edits.
+     * @param operation - Operation to append.
+     * @param maxOperations - Inclusive cap for one draft.
+     * @returns The updated draft.
+     */
+    append(exec, viewId, operation, maxOperations) {
+        const drafts = this.draftsOf(exec);
+        const current = [...drafts.values()].find(draft => draft.viewId === viewId);
+        if (current === undefined) {
+            const created = { id: randomUUID(), viewId, operations: [operation], createdAt: new Date().toISOString() };
+            drafts.set(created.id, created);
+            return created;
+        }
+        if (current.operations.length >= maxOperations) {
+            throw new EngineeringError('DRAFT_TOO_LARGE', `This draft already holds ${current.operations.length} operations, the configured maximum.`, 'Validate and apply this draft, then start another for the remaining edits.');
+        }
+        const updated = { ...current, operations: [...current.operations, operation] };
+        drafts.set(updated.id, updated);
+        return updated;
+    }
+    /**
+     * Resolve one draft by handle.
+     *
+     * @param exec - Calling context.
+     * @param id - Draft handle; empty selects the chat's only draft.
+     * @returns The draft.
+     */
+    get(exec, id) {
+        const drafts = this.draftsOf(exec);
+        const ids = [...drafts.keys()];
+        if (id === undefined || id === '') {
+            const only = ids[0];
+            if (only === undefined)
+                throw new EngineeringError('NO_DRAFT', 'No edit draft exists in this chat.', 'Add an operation with an ftview_draft_* tool first.');
+            if (ids.length > 1)
+                throw new EngineeringError('AMBIGUOUS_DRAFT', `${ids.length} drafts exist in this chat, so draft_id is required.`, `Pass one of: ${ids.join(', ')}.`, ids);
+            return drafts.get(only);
+        }
+        const draft = drafts.get(id);
+        if (draft === undefined) {
+            throw new EngineeringError('UNKNOWN_DRAFT', `No draft exists with draft_id ${JSON.stringify(id)} in this chat.`, ids.length === 0 ? 'Add an operation with an ftview_draft_* tool first.' : `Pass one of this chat's draft ids: ${ids.join(', ')}.`, ids);
+        }
+        return draft;
+    }
+    /**
+     * Drop one draft after it is applied.
+     *
+     * @param exec - Calling context.
+     * @param id - Draft handle.
+     */
+    remove(exec, id) {
+        this.draftsOf(exec).delete(id);
+    }
+    /** The draft map for one calling chat. */
+    draftsOf(exec) {
+        const chat = exec?.chat;
+        if (chat === undefined)
+            return this.detached;
+        const existing = this.chats.get(chat);
+        if (existing !== undefined)
+            return existing;
+        const created = new Map();
+        this.chats.set(chat, created);
+        return created;
+    }
+}

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 };