@aryacode/dsh-engineering 0.7.0 → 0.8.0

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

package/vendor/ftview/lib/schema.js

@@ -0,0 +1,156 @@
+/**
+ * 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 { spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where Studio installs its display schemas. */
+const SCHEMA_ROOTS = [
+    'C:/Program Files (x86)/Rockwell Software/RSView Enterprise/Schemas',
+    'C:/Program Files/Rockwell Software/RSView Enterprise/Schemas',
+];
+/** Coverage note shared by every schema-dependent operation. */
+export const SCHEMA_COVERAGE = {
+    complete: false,
+    unverified: [
+        'sequence order and occurrence counts are enforced by Studio, not by this check',
+        'Studio import and runtime behaviour',
+        'semantic intent of the logic behind a display',
+    ],
+};
+/** The schema directory, or undefined when Studio is not installed here. */
+export function schemaDirectory() {
+    const override = process.env.FTVIEW_SCHEMA_DIR;
+    if (override !== undefined && override !== '')
+        return existsSync(override) ? override : undefined;
+    return SCHEMA_ROOTS.find(root => existsSync(root));
+}
+/** Every installed schema version, newest last. */
+export function schemaVersions() {
+    const directory = schemaDirectory();
+    if (directory === undefined)
+        return [];
+    const version = (name) => Number.parseInt(name.replace(/\D+/gu, ''), 10);
+    return readdirSync(directory)
+        .filter(name => /^Gfx-ME\d+\.xsd$/iu.test(name))
+        .sort((left, right) => version(left) - version(right));
+}
+/** The declared schema of one display, from `xsi:noNamespaceSchemaLocation`. */
+export function declaredSchema(xml) {
+    const match = /xsi:noNamespaceSchemaLocation\s*=\s*"([^"]+)"/u.exec(xml);
+    return match?.[1];
+}
+/**
+ * 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 function schemaFor(xml) {
+    const directory = schemaDirectory();
+    if (directory === undefined)
+        return undefined;
+    const declared = declaredSchema(xml);
+    if (declared !== undefined && existsSync(join(directory, declared)))
+        return { path: join(directory, declared), name: declared };
+    const versions = schemaVersions();
+    if (versions.length === 0)
+        return undefined;
+    const newest = versions[versions.length - 1];
+    return { path: join(directory, newest), name: newest };
+}
+/** PowerShell that validates a batch of XML strings against one schema. */
+const VALIDATOR = `
+$ErrorActionPreference = 'Stop'
+$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$schemas = New-Object System.Xml.Schema.XmlSchemaSet
+$null = $schemas.Add('', [string]$payload.schema)
+$results = New-Object System.Collections.ArrayList
+foreach ($item in $payload.items) {
+  $messages = New-Object 'System.Collections.Generic.List[string]'
+  $settings = New-Object System.Xml.XmlReaderSettings
+  $settings.ValidationType = [System.Xml.ValidationType]::Schema
+  $settings.Schemas = $schemas
+  $settings.ValidationFlags = $settings.ValidationFlags -bor [System.Xml.Schema.XmlSchemaValidationFlags]::ReportValidationWarnings
+  $handler = [System.Xml.Schema.ValidationEventHandler]{ param($sender, $eventArgs) $messages.Add("$($eventArgs.Severity): $($eventArgs.Message)") }
+  $settings.add_ValidationEventHandler($handler)
+  $reader = [System.Xml.XmlReader]::Create((New-Object System.IO.StringReader([string]$item.xml)), $settings)
+  try { while ($reader.Read()) { } } catch { $messages.Add("error: $($_.Exception.Message)") } finally { $reader.Dispose() }
+  [void]$results.Add([pscustomobject]@{ file = [string]$item.file; messages = @($messages) })
+}
+$results | ConvertTo-Json -Depth 4 -Compress
+`;
+/**
+ * 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 async function validateSchema(documents, executable = 'powershell.exe') {
+    if (documents.length === 0)
+        return { findings: [], ran: true };
+    // Only Studio documents declare a schema. A hand-made <display> file is not
+    // one, and validating it against Gfx-ME would report a root element the
+    // fixture never claimed to be. Such files are skipped, with a reason.
+    const declared = documents.filter(document => declaredSchema(document.xml) !== undefined);
+    if (declared.length === 0) {
+        return {
+            findings: [],
+            ran: false,
+            unavailable: 'None of the changed documents declares xsi:noNamespaceSchemaLocation, so there is no vendor schema to validate against. Studio exports and authored displays always declare one.',
+        };
+    }
+    const first = declared[0];
+    const schema = schemaFor(first.xml);
+    if (schema === undefined) {
+        return {
+            findings: [],
+            ran: false,
+            unavailable: 'No Gfx-ME*.xsd schema is installed on this host. Install FactoryTalk View Studio, or set FTVIEW_SCHEMA_DIR to the folder that holds Gfx-ME*.xsd.',
+        };
+    }
+    const payload = JSON.stringify({ schema: schema.path, items: declared });
+    const encoded = Buffer.from(VALIDATOR, 'utf16le').toString('base64');
+    const output = await runPowerShell(executable, ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded], payload);
+    if (output.code !== 0) {
+        return {
+            findings: [],
+            ran: false,
+            schema: schema.name,
+            unavailable: `The schema validator did not run: ${output.stderr.trim() || `exit ${output.code}`}`,
+        };
+    }
+    const parsed = JSON.parse(output.stdout);
+    const findings = [];
+    for (const result of Array.isArray(parsed) ? parsed : [parsed]) {
+        for (const message of result.messages ?? []) {
+            findings.push({ file: result.file, message, error: message.startsWith('Error') || message.startsWith('error:') });
+        }
+    }
+    return { findings, ran: true, schema: schema.name };
+}
+/** Run one process with stdin and collect its output. */
+function runPowerShell(executable, args, stdin) {
+    return new Promise(resolvePromise => {
+        const child = spawn(executable, args, { windowsHide: true });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
+        child.stderr?.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
+        child.on('error', error => resolvePromise({ code: -1, stdout, stderr: stderr || error.message }));
+        child.on('close', code => resolvePromise({ code: code ?? -1, stdout, stderr }));
+        child.stdin?.end(stdin, 'utf8');
+    });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Tools that reach the installed ME engine.
+ *
+ * These are the only entry points that talk to Studio's world: listing the
+ * applications it knows and exporting one to a folder. Both are read-only with
+ * respect to the project.
+ *
+ * @module dsh-engineering-ftview/vendor-tools
+ */
+import { type FsService, type ToolDefinition } from './core.ts';
+/**
+ * The vendor tools.
+ *
+ * @param fs - Filesystem provider used to resolve the destination folder.
+ * @returns Tool definitions.
+ */
+export declare function vendorTools(fs: FsService): readonly ToolDefinition[];

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

@@ -0,0 +1,74 @@
+/**
+ * Tools that reach the installed ME engine.
+ *
+ * These are the only entry points that talk to Studio's world: listing the
+ * applications it knows and exporting one to a folder. Both are read-only with
+ * respect to the project.
+ *
+ * @module dsh-engineering-ftview/vendor-tools
+ */
+import { existsSync } from 'node:fs';
+import { EngineeringError, object, optionalString, requiredString, string, success, tool } from "./core.js";
+import { exportApplication, listApplications } from "./vendor.js";
+/** What a vendor call cannot prove. */
+const VENDOR_COVERAGE = {
+    complete: false,
+    unverified: [
+        'the exported XML is a snapshot of the saved application, not of a running terminal',
+        'display compile and download to a PanelView terminal',
+        'Studio import behaviour',
+    ],
+};
+/**
+ * The vendor tools.
+ *
+ * @param fs - Filesystem provider used to resolve the destination folder.
+ * @returns Tool definitions.
+ */
+export function vendorTools(fs) {
+    return [
+        tool({
+            name: 'ftview_apps',
+            description: 'List the FactoryTalk View ME applications installed on this host, through the vendor export server. Requires FactoryTalk View ME on the machine.',
+            parameters: object({
+                filter: string('Case-insensitive substring matched against the application name.'),
+            }, []),
+            async run(args) {
+                const filter = (optionalString(args, 'filter') ?? '').toLowerCase();
+                const listed = await listApplications();
+                if (listed.error !== undefined) {
+                    throw new EngineeringError('VENDOR_UNAVAILABLE', listed.error, 'Install FactoryTalk View ME Studio on this host, or work from an existing export folder.');
+                }
+                const apps = (listed.value ?? []).filter(app => filter === '' || app.name.toLowerCase().includes(filter));
+                return success(`${apps.length} ME application(s)${filter === '' ? '' : ` matching ${JSON.stringify(filter)}`} on this host.`, { total: apps.length, apps }, [{ tool: 'ftview_export', args: { application: apps[0]?.name ?? 'NAME', output_root: 'C:/Exports/NAME' }, why: 'Export one application to a folder this surface can read.' }], VENDOR_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'ftview_export',
+            description: 'Export one installed ME application (displays, global objects, tags) to a NEW folder through the vendor export server. The application is not modified.',
+            parameters: object({
+                application: string('Application name as ftview_apps lists it.'),
+                output_root: string('New folder for the export. It must not exist.'),
+            }, ['application', 'output_root']),
+            async run(args, exec) {
+                const application = requiredString(args, 'application');
+                const requested = requiredString(args, 'output_root');
+                const destination = await fs.resolve(requested, {
+                    ...(exec.cwd === undefined ? {} : { cwd: exec.cwd }),
+                    ...(exec.signal === undefined ? {} : { signal: exec.signal }),
+                });
+                if (existsSync(destination)) {
+                    throw new EngineeringError('OUTPUT_EXISTS', `A file or folder already exists at ${requested}.`, 'Pass a new output_root; export never merges into an existing folder.');
+                }
+                const exported = await exportApplication(application, destination);
+                if (exported.error !== undefined) {
+                    throw new EngineeringError('VENDOR_EXPORT_FAILED', exported.error, 'Check that the application is not open in Studio, then retry with a new output_root.');
+                }
+                const files = exported.value ?? [];
+                const displays = files.filter(file => /\/Displays\/.+\.xml$/iu.test(file) && !/batchimport/iu.test(file));
+                const manifests = files.filter(file => /batchimport/iu.test(file));
+                return success(`Exported ${application}: ${files.length} file(s), ${displays.length} display(s)${manifests.length === 0 ? '' : `, ${manifests.length} import manifest(s)`}.`, { application, output_root: destination, files, display_count: displays.length, manifests }, [{ tool: 'ftview_open', args: { root: destination }, why: 'Open the fresh export and author against it.' }], VENDOR_COVERAGE);
+            },
+        }),
+    ];
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Drive the installed FactoryTalk View ME engine.
+ *
+ * Studio ships two scriptable COM servers that matter here: `MEExportSvr`
+ * (list applications, export displays) and `AppMgrServer` (backup and restore).
+ * The export server runs out of process and works from a 64-bit host; the
+ * application manager is a 32-bit in-process server, so it is reached through
+ * the 32-bit PowerShell. Nothing here edits a project: export reads, backup
+ * copies.
+ *
+ * @module dsh-engineering-ftview/vendor
+ */
+/** CLSID of the ME export server (`MEExport.exe`). */
+export declare const EXPORT_CLSID = "9d882577-aa92-466b-a749-6d6b5093b623";
+/** CLSID of the application manager (`ApplicationManagerServer.dll`). */
+export declare const APP_MANAGER_CLSID = "4fead81a-cd72-42da-b659-f1a41499f0f9";
+/** One installed ME application. */
+export interface MeApplication {
+    /** Application name as Studio stores it. */
+    readonly name: string;
+    /** Target platform when the engine reports one. */
+    readonly platform?: string;
+    /** Version string when the engine reports one. */
+    readonly version?: string;
+}
+/** Result of one vendor call. */
+export interface VendorResult<T> {
+    /** Parsed value on success. */
+    readonly value?: T;
+    /** Human-readable failure. */
+    readonly error?: string;
+}
+/**
+ * List every ME application the engine knows.
+ *
+ * @returns Applications, or the reason the engine could not be reached.
+ */
+export declare function listApplications(): Promise<VendorResult<readonly MeApplication[]>>;
+/**
+ * Export one application's displays and globals into a new folder.
+ *
+ * @param application - Application name as listed.
+ * @param destination - Folder to create and fill.
+ * @returns Files written, relative to the destination.
+ */
+export declare function exportApplication(application: string, destination: string): Promise<VendorResult<readonly string[]>>;
+/**
+ * Back one application up to a zip.
+ *
+ * @param application - Application name.
+ * @param zipPath - Destination zip; must not exist.
+ * @returns The zip path on success.
+ */
+export declare function backupApplication(application: string, zipPath: string): Promise<VendorResult<string>>;
+/** Size of one file, for reports. */
+export declare function fileSize(path: string): number;