@aryacode/dsh-engineering 0.6.0 → 0.8.0

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

@@ -7,9 +7,13 @@
  *
  * @module dsh-engineering-ftview/edit/tools
  */
-import { createHash } from 'node:crypto';
-import { EngineeringError, object, optionalString, requiredString, string, success, tool } from "../core.js";
+import { createHash, randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { EngineeringError, integer, object, optionalInteger, optionalString, requiredString, string, success, tool } from "../core.js";
 import { EDIT_COVERAGE, prepareEdit } from "./prepare.js";
+import { exportApplication } from "../vendor.js";
+import { allMatched, verifyDisplays } from "../handoff.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. */
@@ -27,6 +31,41 @@ function nextValidate(draftId) {
 function objectCount(display, name) {
     return display.objects.filter(object => object.name === name).length;
 }
+/** One display by name, with a repairable failure. */
+function displayOf(view, name) {
+    const display = view.app.displays.find(candidate => candidate.name === name);
+    if (display === undefined) {
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `No display is named ${JSON.stringify(name)} in this export.`, 'Call ftview_list with kind "display" to see the display names.', view.app.displays.slice(0, 5).map(candidate => candidate.name));
+    }
+    return display;
+}
+/** Parse one JSON object argument into string attributes. */
+function jsonObject(value, name) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== 'string')
+        throw new EngineeringError('INVALID_ARGUMENT', `${name} must be a JSON object string.`, `Pass ${name} as a JSON object, for example {"height":"40"}.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new EngineeringError('INVALID_ARGUMENT', `${name} is not valid JSON.`, `Pass ${name} as a JSON object, for example {"height":"40"}.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new EngineeringError('INVALID_ARGUMENT', `${name} must be a JSON object.`, `Pass ${name} as a JSON object, for example {"height":"40"}.`);
+    }
+    const result = {};
+    for (const [key, entry] of Object.entries(parsed)) {
+        if (typeof entry === 'number' || typeof entry === 'boolean')
+            result[key] = String(entry);
+        else if (typeof entry === 'string')
+            result[key] = entry;
+        else
+            throw new EngineeringError('INVALID_ARGUMENT', `${name}.${key} must be a string, number or boolean.`, 'Pass scalar values only.');
+    }
+    return result;
+}
 /**
  * The editing tools.
  *
@@ -131,9 +170,146 @@ export function editTools(session, drafts, fs, maxOperations) {
                 return staged(draft, draft.operations[draft.operations.length - 1]);
             },
         }),
+        tool({
+            name: 'ftview_draft_display_create',
+            description: 'Stage a brand-new display with a schema-valid skeleton. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                name: string('New display name, unique in the export. Example: "Arya Overview".'),
+                width: integer('Display width in pixels. Example: 800.', { minimum: 1, maximum: 16384 }),
+                height: integer('Display height in pixels. Example: 600.', { minimum: 1, maximum: 16384 }),
+                display_type: string('Optional display type as Studio writes it, for example "replace" or "onTop".'),
+                back_color: string('Optional background colour. Example: "#C6C6C6".'),
+                display_number: integer('Optional display number.', { minimum: 0 }),
+                file: string('Optional export-relative file path. Defaults to "Displays/<name>.xml".'),
+            }, ['name', 'width', 'height']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const name = requiredString(args, '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.');
+                }
+                const displayType = optionalString(args, 'display_type');
+                const backColor = optionalString(args, 'back_color');
+                const displayNumber = optionalInteger(args, 'display_number');
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'display_create',
+                    file: optionalString(args, 'file') ?? `Displays/${name}.xml`,
+                    name,
+                    width: optionalInteger(args, 'width') ?? 800,
+                    height: optionalInteger(args, 'height') ?? 600,
+                    ...(displayType === undefined ? {} : { displayType }),
+                    ...(backColor === undefined ? {} : { backColor }),
+                    ...(displayNumber === undefined ? {} : { displayNumber }),
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_object_add',
+            description: 'Stage one new object inside a display: geometry, attributes and tag connections. Validated against the vendor schema on ftview_validate. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list.'),
+                type: string('Object element type as the export writes it, e.g. "momentaryButton", "text", "panel", "numericDisplay", "gotoButton".'),
+                name: string('New object name, unique inside the display.'),
+                attributes_json: string('Object attributes as a JSON object, e.g. {"height":"50","width":"120","left":"20","top":"40"}.'),
+                caption: string('Optional caption text (text objects and buttons).'),
+                connections_json: string('Optional connections as a JSON object, e.g. {"Value":"SystemRunning"}.'),
+                parent: string('Optional group name to add inside. Omit to add at the display root.'),
+                index: integer('Optional position among siblings, for z-order.', { minimum: 0 }),
+            }, ['display', 'type', 'name']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const display = displayOf(view, requiredString(args, 'display'));
+                const attributes = { ...jsonObject(args.attributes_json, 'attributes_json') };
+                const caption = optionalString(args, 'caption');
+                if (caption !== undefined)
+                    attributes.caption = caption;
+                const connections = jsonObject(optionalString(args, 'connections_json'), 'connections_json');
+                const parent = optionalString(args, 'parent');
+                const index = optionalInteger(args, 'index');
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'object_add',
+                    file: display.file,
+                    type: requiredString(args, 'type'),
+                    name: requiredString(args, 'name'),
+                    attributes,
+                    ...(parent === undefined ? {} : { parent }),
+                    ...(index === undefined ? {} : { index }),
+                    ...(Object.keys(connections).length === 0 ? {} : { connections }),
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_object_set',
+            description: 'Stage attribute, caption or connection changes on one existing object. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list.'),
+                object: string('Object name inside the display.'),
+                attributes_json: string('Attributes to set as a JSON object, e.g. {"visible":"0","left":"30"}.'),
+                caption: string('Optional new caption text.'),
+                connections_json: string('Connections to set as a JSON object, e.g. {"Value":"SystemRunning"}.'),
+            }, ['display', 'object']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const display = displayOf(view, requiredString(args, 'display'));
+                const object = requiredString(args, 'object');
+                const attributes = jsonObject(args.attributes_json, 'attributes_json');
+                const connections = jsonObject(optionalString(args, 'connections_json'), 'connections_json');
+                const caption = optionalString(args, 'caption');
+                if (Object.keys(attributes).length === 0 && Object.keys(connections).length === 0 && caption === undefined) {
+                    throw new EngineeringError('INVALID_ARGUMENT', 'No change was requested.', 'Pass attributes_json, connections_json or caption.');
+                }
+                const { draft } = stage(exec, optionalString(args, 'view_id'), {
+                    kind: 'object_set',
+                    file: display.file,
+                    object,
+                    attributes,
+                    ...(caption === undefined ? {} : { caption }),
+                    ...(Object.keys(connections).length === 0 ? {} : { connections }),
+                });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_object_delete',
+            description: 'Stage the removal of one object from a display. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list.'),
+                object: string('Object name to remove.'),
+            }, ['display', 'object']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const display = displayOf(view, requiredString(args, 'display'));
+                const object = requiredString(args, 'object');
+                const { draft } = stage(exec, optionalString(args, 'view_id'), { kind: 'object_delete', file: display.file, object });
+                return staged(draft, draft.operations[draft.operations.length - 1]);
+            },
+        }),
+        tool({
+            name: 'ftview_draft_object_order',
+            description: 'Stage a z-order move for one object among its siblings. Nothing is written until ftview_apply.',
+            parameters: object({
+                view_id: VIEW_ID,
+                display: string('Display name as listed by ftview_list.'),
+                object: string('Object name to move.'),
+                index: integer('New position among the object siblings, 0 = back.', { minimum: 0 }),
+            }, ['display', 'object', 'index']),
+            async run(args, exec) {
+                const view = session.require(optionalString(args, 'view_id'), exec);
+                const display = displayOf(view, requiredString(args, 'display'));
+                const object = requiredString(args, 'object');
+                const { draft } = stage(exec, optionalString(args, 'view_id'), { kind: 'object_order', file: display.file, object, index: optionalInteger(args, 'index') ?? 0 });
+                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.',
+            description: 'Prepare the staged edits: apply them to a re-parsed copy, validate the changed displays against the installed Gfx-ME schema, and report the changed files and findings. Writes nothing.',
             parameters: object({ draft_id: DRAFT_ID }, []),
             async run(args, exec) {
                 const draft = drafts.get(exec, optionalString(args, 'draft_id'));
@@ -142,16 +318,47 @@ export function editTools(session, drafts, fs, maxOperations) {
                 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).`, {
+                const schemaErrors = prepared.schema.findings.filter(finding => finding.error);
+                return success(`${draft.operations.length} operation(s); ${prepared.texts.size} file(s) change; ${prepared.findings.length} finding(s); schema ${prepared.schema.ran ? `ran (${schemaErrors.length} error(s))` : 'unavailable'}.`, {
                     draft_id: draft.id,
                     draft_sha256: prepared.hash,
                     changed_files: [...prepared.texts.keys()],
                     added: prepared.added,
                     findings: prepared.findings,
                     by_rule: byRule,
+                    schema: prepared.schema,
                 }, [{ tool: 'ftview_apply', args: { draft_id: draft.id }, why: 'Write the prepared export to a new folder.' }], EDIT_COVERAGE);
             },
         }),
+        tool({
+            name: 'ftview_verify_import',
+            description: 'Export the application again through the vendor engine and compare it object by object with the staged draft, proving whether the import landed. Writes only a temporary export folder.',
+            parameters: object({
+                view_id: VIEW_ID,
+                draft_id: DRAFT_ID,
+                application: string('Application name as ftview_apps lists it. The same application the package was imported into.'),
+            }, ['application']),
+            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 expected = new Map([...prepared.texts].filter(([file]) => /\.xml$/iu.test(file) && !/batchimport/iu.test(file)));
+                if (expected.size === 0) {
+                    throw new EngineeringError('NOTHING_TO_VERIFY', 'This draft changes no display, so there is nothing to compare.', 'Stage a display edit first, import it in Studio, then run this again.');
+                }
+                const root = join(tmpdir(), `ftview-verify-${randomUUID()}`);
+                const exported = await exportApplication(requiredString(args, 'application'), root);
+                if (exported.error !== undefined) {
+                    throw new EngineeringError('VENDOR_EXPORT_FAILED', exported.error, 'Close the application in Studio if it is open, then retry.');
+                }
+                const results = await verifyDisplays(fs, root, expected);
+                const matched = results.filter(result => result.matched).length;
+                const differences = results.flatMap(result => result.differences.map(difference => ({ file: result.file, ...difference })));
+                return success(`${matched}/${results.length} display(s) match the draft${allMatched(results) ? '' : `; ${differences.length} difference(s)`}. Export kept at ${root}.`, { application: requiredString(args, 'application'), export_root: root, displays: results, differences, matched: allMatched(results) }, matched === results.length
+                    ? [{ tool: 'ftview_draft_display_create', why: 'Author the next screen against the verified export.' }]
+                    : [{ tool: 'ftview_validate', args: { draft_id: draft.id }, why: 'Re-read the draft findings before correcting the difference.' }], 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.',
@@ -163,6 +370,10 @@ export function editTools(session, drafts, fs, maxOperations) {
                 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 schemaErrors = prepared.schema.findings.filter(finding => finding.error);
+                if (schemaErrors.length > 0) {
+                    throw new EngineeringError('SCHEMA_INVALID', `${schemaErrors.length} schema error(s); nothing was written. First: ${schemaErrors[0]?.file}: ${schemaErrors[0]?.message}`, 'Fix the offending attributes or elements and run ftview_validate again; apply refuses a document the vendor schema rejects.', schemaErrors.slice(0, 5).map(finding => `${finding.file}: ${finding.message}`));
+                }
                 const outputRoot = await fs.resolve(requiredString(args, 'output_root'), {
                     ...(exec.cwd === undefined ? {} : { cwd: exec.cwd }),
                     ...(exec.signal === undefined ? {} : { signal: exec.signal }),
@@ -190,8 +401,41 @@ export function editTools(session, drafts, fs, maxOperations) {
                     await fs.writeText(`${outputRoot}/${file}`, text, { kind: 'createIfAbsent' }, exec.signal);
                     written += 1;
                 }
+                // The vendor's own import file: Studio's Batch Import reads this list
+                // from the Displays folder. Writing it here is what turns a folder of
+                // XML into a one-step import.
+                const changedDisplays = [...prepared.texts.keys()]
+                    .filter(file => /^Displays\/.+\.xml$/iu.test(file) && !/batchimport/iu.test(file));
+                let manifest;
+                if (changedDisplays.length > 0) {
+                    const entries = changedDisplays
+                        .map(file => `    <import importFile="${file.replace(/^Displays\//u, '').replaceAll('&', '&amp;').replaceAll('"', '&quot;')}"/>`)
+                        .join('\n');
+                    manifest = `Displays/BatchImport_${view.app.name}.xml`;
+                    await fs.writeText(`${outputRoot}/${manifest}`, `<?xml version="1.0" encoding="UTF-8"?>\n<gfxImport>\n${entries}\n</gfxImport>\n`, { kind: 'createIfAbsent' }, exec.signal);
+                    written += 1;
+                    const steps = [
+                        `# Import ${view.app.name}`,
+                        '',
+                        `Open FactoryTalk View Studio → Application Manager, open **${view.app.name}**, and import the displays listed in \`Displays/BatchImport_${view.app.name}.xml\` (${changedDisplays.length} file(s)).`,
+                        '',
+                        'Then:',
+                        '1. Verify each display opens without warnings.',
+                        '2. Create the runtime application (`.mer`).',
+                        '3. Run `ftview_verify_import` with the draft id to prove the import matches this draft.',
+                        '',
+                        'Changed displays:',
+                        ...changedDisplays.map(file => `- ${file}`),
+                        '',
+                    ].join('\n');
+                    await fs.writeText(`${outputRoot}/IMPORT.md`, steps, { 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);
+                return success(`Wrote ${written} file(s) to ${outputRoot}${manifest === undefined ? '' : `; import manifest ${manifest}`}.`, { output_root: outputRoot, draft_id: draft.id, files_written: written, changed_files: [...prepared.texts.keys()], ...(manifest === undefined ? {} : { manifest }), schema: prepared.schema }, [
+                    { tool: 'ftview_open', args: { root: outputRoot }, why: 'Reopen the written export and check it.' },
+                    { tool: 'ftview_verify_import', args: { application: view.app.name }, why: 'After Studio imports it, prove the import matches this draft.' },
+                ], APPLY_COVERAGE);
             },
         }),
     ];

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

@@ -0,0 +1,58 @@
+/**
+ * Prove that what Studio imported is what we authored.
+ *
+ * An export is the vendor's own view of an application. Comparing a fresh
+ * export against the prepared draft, object by object, is the only evidence
+ * that the import took: file hashes would say nothing about what the engine
+ * kept, normalised or rejected.
+ *
+ * @module dsh-engineering-ftview/handoff
+ */
+import type { FsService } from './core.ts';
+/** One object as it exists in a display. */
+export interface ObjectSignature {
+    /** Element type, e.g. `momentaryButton`. */
+    readonly type: string;
+    /** Object name when it has one. */
+    readonly name?: string;
+    /** Attributes, decoded, sorted by name. */
+    readonly attributes: Readonly<Record<string, string>>;
+    /** Nested objects, in document order. */
+    readonly children: readonly ObjectSignature[];
+}
+/** One difference between intended and imported. */
+export interface SignatureDifference {
+    /** Where the difference sits, e.g. `Main Screen > StartButton > caption`. */
+    readonly path: string;
+    /** What the draft had. */
+    readonly expected?: string;
+    /** What the import produced. */
+    readonly actual?: string;
+}
+/** Compare one display's intended and imported trees. */
+export interface DisplayVerification {
+    /** Export-relative display file. */
+    readonly file: string;
+    /** True when the trees are identical. */
+    readonly matched: boolean;
+    /** Differences, capped by the caller. */
+    readonly differences: readonly SignatureDifference[];
+}
+/**
+ * Signature of one display document: its objects, nested, without layout noise.
+ *
+ * @param xml - Display XML.
+ * @returns Root signature.
+ */
+export declare function signatureOf(xml: string): ObjectSignature;
+/**
+ * Compare the prepared draft's displays with a fresh export.
+ *
+ * @param fs - Filesystem provider.
+ * @param root - Export folder produced by the vendor after the import.
+ * @param expected - Export-relative file to intended XML.
+ * @returns One verification per display.
+ */
+export declare function verifyDisplays(fs: FsService, root: string, expected: ReadonlyMap<string, string>): Promise<readonly DisplayVerification[]>;
+/** Whether every verification matched. */
+export declare function allMatched(results: readonly DisplayVerification[]): boolean;

package/vendor/ftview/lib/handoff.js

@@ -0,0 +1,95 @@
+/**
+ * Prove that what Studio imported is what we authored.
+ *
+ * An export is the vendor's own view of an application. Comparing a fresh
+ * export against the prepared draft, object by object, is the only evidence
+ * that the import took: file hashes would say nothing about what the engine
+ * kept, normalised or rejected.
+ *
+ * @module dsh-engineering-ftview/handoff
+ */
+import { attributeOf, parseDisplayTree } from "./display-tree.js";
+/** One signature of a node, recursively. */
+function signatureOfNode(node) {
+    const attributes = {};
+    for (const name of Object.keys(node.attributes).sort())
+        attributes[name] = attributeOf(node, name) ?? '';
+    return {
+        type: node.type,
+        ...(node.attributes.name === undefined ? {} : { name: attributeOf(node, 'name') }),
+        attributes,
+        children: node.children.filter(child => child.attributes.name !== undefined || ['group', 'connections', 'states'].includes(child.type)).map(signatureOfNode),
+    };
+}
+/**
+ * Signature of one display document: its objects, nested, without layout noise.
+ *
+ * @param xml - Display XML.
+ * @returns Root signature.
+ */
+export function signatureOf(xml) {
+    const tree = parseDisplayTree(xml);
+    return { type: tree.root.type, attributes: {}, children: tree.root.children.map(signatureOfNode) };
+}
+/** Collect differences between two signatures at one path. */
+function diff(expected, actual, path, out) {
+    if (out.length >= 50)
+        return;
+    if (expected.type !== actual.type) {
+        out.push({ path, expected: expected.type, actual: actual.type });
+        return;
+    }
+    const names = new Set([...Object.keys(expected.attributes), ...Object.keys(actual.attributes)]);
+    for (const name of names) {
+        if (expected.attributes[name] !== actual.attributes[name]) {
+            out.push({ path: `${path} @${name}`, expected: expected.attributes[name], actual: actual.attributes[name] });
+            if (out.length >= 50)
+                return;
+        }
+    }
+    const expectedChildren = expected.children;
+    const actualChildren = actual.children;
+    for (let index = 0; index < Math.max(expectedChildren.length, actualChildren.length); index += 1) {
+        const left = expectedChildren[index];
+        const right = actualChildren[index];
+        const label = left?.name ?? right?.name ?? `child[${index}]`;
+        if (left === undefined) {
+            out.push({ path: `${path} > ${label}`, actual: 'present in import, missing in draft' });
+            continue;
+        }
+        if (right === undefined) {
+            out.push({ path: `${path} > ${label}`, expected: 'present in draft, missing in import' });
+            continue;
+        }
+        diff(left, right, `${path} > ${label}`, out);
+    }
+}
+/**
+ * Compare the prepared draft's displays with a fresh export.
+ *
+ * @param fs - Filesystem provider.
+ * @param root - Export folder produced by the vendor after the import.
+ * @param expected - Export-relative file to intended XML.
+ * @returns One verification per display.
+ */
+export async function verifyDisplays(fs, root, expected) {
+    const results = [];
+    for (const [file, intended] of expected) {
+        const bytes = await fs.readBytes(`${root}/${file}`, undefined, 64 * 1024 * 1024);
+        const actual = new TextDecoder('utf-8').decode(bytes);
+        const differences = [];
+        try {
+            diff(signatureOf(intended), signatureOf(actual), file, differences);
+        }
+        catch (error) {
+            results.push({ file, matched: false, differences: [{ path: file, expected: 'a parsable display', actual: error instanceof Error ? error.message : String(error) }] });
+            continue;
+        }
+        results.push({ file, matched: differences.length === 0, differences });
+    }
+    return results;
+}
+/** Whether every verification matched. */
+export function allMatched(results) {
+    return results.every(result => result.matched);
+}

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

@@ -27,5 +27,6 @@ export interface Config {
 export declare function apply(ctx: PluginContext, config?: Config): void;
 export { ViewSession } from './session.ts';
 export { ftviewTools } from './tools.ts';
+export { vendorTools } from './vendor-tools.ts';
 export { EngineeringError } from './core.ts';
 export type { Coverage, NextStep, Success, ToolDefinition } from './core.ts';

package/vendor/ftview/lib/index.js

@@ -9,6 +9,7 @@
 import { stringFs } from "./core.js";
 import { ViewSession } from "./session.js";
 import { ftviewTools } from "./tools.js";
+import { vendorTools } from "./vendor-tools.js";
 /** Plugin name in a composition. */
 export const name = 'ftview-read';
 /** Services this plugin cannot register without. */
@@ -28,9 +29,10 @@ export function apply(ctx, config = {}) {
     }
     const session = new ViewSession(stringFs(ctx.fs), maxFiles);
     ctx.provide?.(VIEWS_SERVICE, session);
-    for (const definition of ftviewTools(session))
+    for (const definition of [...ftviewTools(session), ...vendorTools(stringFs(ctx.fs))])
         ctx.tools.register(definition);
 }
 export { ViewSession } from "./session.js";
 export { ftviewTools } from "./tools.js";
+export { vendorTools } from "./vendor-tools.js";
 export { EngineeringError } from "./core.js";

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

@@ -0,0 +1,68 @@
+/**
+ * Validate display XML against the installed FactoryTalk View schema.
+ *
+ * The vendor ships `Gfx-ME*.xsd` with Studio. Rather than re-implement an XSD
+ * engine, this module asks .NET (through PowerShell) to validate in process,
+ * which is exact and needs no third-party package. When the schema or the host
+ * is unavailable the caller gets a clear `schema_unavailable` result instead of
+ * a silent pass.
+ *
+ * @module dsh-engineering-ftview/schema
+ */
+import type { Coverage } from './core.ts';
+/** One file's validation outcome. */
+export interface SchemaFinding {
+    /** File or display name the finding belongs to. */
+    readonly file: string;
+    /** Schema message, already rendered by .NET. */
+    readonly message: string;
+    /** True when the schema rejected the document. */
+    readonly error: boolean;
+}
+/** One validation run. */
+export interface SchemaValidation {
+    /** Schema file used, or the reason validation could not run. */
+    readonly schema?: string;
+    /** Findings across every document. */
+    readonly findings: readonly SchemaFinding[];
+    /** True when validation actually ran. */
+    readonly ran: boolean;
+    /** Why it could not run, when it did not. */
+    readonly unavailable?: string;
+}
+/** Coverage note shared by every schema-dependent operation. */
+export declare const SCHEMA_COVERAGE: Coverage;
+/** The schema directory, or undefined when Studio is not installed here. */
+export declare function schemaDirectory(): string | undefined;
+/** Every installed schema version, newest last. */
+export declare function schemaVersions(): readonly string[];
+/** The declared schema of one display, from `xsi:noNamespaceSchemaLocation`. */
+export declare function declaredSchema(xml: string): string | undefined;
+/**
+ * Pick the schema file for one document.
+ *
+ * A display names its schema; if that file is not installed, the newest
+ * installed schema is used and the caller is told which one ran.
+ *
+ * @param xml - Display XML, used only for its declared schema.
+ * @returns Absolute schema path and its file name, or undefined.
+ */
+export declare function schemaFor(xml: string): {
+    path: string;
+    name: string;
+} | undefined;
+/** One item handed to the validator. */
+export interface SchemaDocument {
+    /** Name reported in findings. */
+    readonly file: string;
+    /** Display XML. */
+    readonly xml: string;
+}
+/**
+ * Validate one batch of display documents against the installed schema.
+ *
+ * @param documents - Documents to check; an empty list runs nothing.
+ * @param executable - PowerShell to use; defaults to `powershell.exe`.
+ * @returns Findings, whether validation ran, and the schema used.
+ */
+export declare function validateSchema(documents: readonly SchemaDocument[], executable?: string): Promise<SchemaValidation>;