@aryacode/dsh-engineering 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.8.4] - 2026-10-27
+
+### Added
+
+- **`ftview_export` now brings the alarm setup and the tag database.** The vendor export server covers
+  displays, global objects and project settings; alarms and tags live beside the application in the
+  Studio project store and were missing from a "full" export, so tag bindings had nothing to check
+  against. The export now copies `Alarms/Alarms.xml` and `Tags/<application>.csv` into the export in the
+  same layout Studio uses, and reports a warning for each when the stored snapshot is older than the
+  application database (on the commissioning application both were dated 2026-09-29 against a database
+  modified 2026-10-27).
+
+### Documentation
+
+- FTView skill, getting-started and the handbook now describe the alarms/tags copy and its staleness
+  warning instead of "the vendor export carries no tag CSV".
+## [0.8.3] - 2026-10-27
+
+### Documentation
+
+- **A workflow handbook, generated from one source.** `docs/handbook/Engineering-Handbook.pdf` (7 pages),
+  an editable `.docx` and a printable `.html` cover the four products: what each row needs, the shared
+  read → act → verify → hand-off loop, what the agent does, what stays human, and a "what proves what"
+  table.
+- **Six workflow diagrams** in `docs/diagrams/` (SVG masters and PNG): the shared loop and one per
+  product, with agent steps, human steps and proof steps visually distinguished. They are embedded in
+  `docs/getting-started.md` and in the handbook.
+- The diagrams and handbook are **generated**, not hand-drawn: `scripts/gen-diagrams.py` owns the layout
+  and `scripts/gen-handbook.py` the prose, so a changed workflow is one edit and one regeneration.
+- README: the handbook in the documentation table and the generators in the Development commands.
 ## [0.8.2] - 2026-10-27
 
 ### Documentation

package/README.md

@@ -238,6 +238,7 @@ even when the implementation behind a row is replaced.
 | Document | Owns |
 |---|---|
 | [Getting started](docs/getting-started.md) | The first session: what each row needs, the shared loop, and a paste-ready prompt per product |
+| [Workflow handbook (PDF)](docs/handbook/Engineering-Handbook.pdf) | The whole surface as a printable handbook with the four workflow diagrams; [editable DOCX](docs/handbook/Engineering-Handbook.docx) and [HTML](docs/handbook/Engineering-Handbook.html) beside it |
 | [Tool reference](docs/reference/tools.md) | Every tool, parameter and description (generated) |
 | [Examples](docs/examples.md) | End-to-end sessions per product |
 | [Architecture](docs/architecture.md) | Composition, row model, configuration, client faces, packaging |
@@ -256,8 +257,14 @@ pnpm build:client  # regenerate lib/client.js from the committed face bundles
 pnpm test          # patch, docs, tool-reference, manifest and client-face checks
 pnpm docs:tools    # regenerate the tool reference from the registered definitions
 pnpm docs:check    # fail if the committed reference has drifted
+python scripts/gen-diagrams.py   # regenerate docs/diagrams/*.svg and *.png
+python scripts/gen-handbook.py   # rebuild the PDF, DOCX and HTML handbook from those figures
 ```
 
+The diagrams and the handbook are generated, not hand-drawn: layout lives in
+`scripts/gen-diagrams.py` and the prose in `scripts/gen-handbook.py`, so a changed workflow is one edit
+and one regeneration. Both need Pillow; the handbook also needs python-docx and reportlab.
+
 Tests run through `tsx` so they can read the TypeScript tool factories. A registered tool that no
 skill governs fails the suite — the policy is a test, not a convention.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "AryaCode engineering bundle: one install surface for the Studio 5000 L5X, FactoryTalk View ME, MotionWorks IEC and FactoryTalk Optix surfaces, one row per product, with the ladder and display previews.",
   "keywords": [
     "dsh",

package/vendor/ftview/SKILL.md

@@ -77,7 +77,10 @@ Start from the application, not from a folder someone emailed:
 
 1. `ftview_apps` lists the ME applications installed on this host.
 2. `ftview_export` writes one to a NEW folder through the vendor export server. No Studio window is
-   needed and the application is not modified.
+   needed and the application is not modified. It also copies the alarm setup (`Alarms/Alarms.xml`) and
+   the tag CSV (`Tags/<application>.csv`) from the Studio project store, and reports a `warning` for
+   either when the stored file is older than the application database — say so rather than treating
+   those tags or alarms as current.
 3. `ftview_open` that folder, then author against it:
    - `ftview_draft_display_create` for a new display;
    - `ftview_draft_object_add` for one object (`text`, `panel`, `momentaryButton`, `numericDisplay`,

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

@@ -64,10 +64,13 @@ export function vendorTools(fs) {
                 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 files = exported.value?.files ?? [];
+                const warnings = exported.value?.warnings ?? [];
                 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);
+                const alarms = files.filter(file => /^Alarms\//iu.test(file));
+                const tags = files.filter(file => /^Tags\/.+\.csv$/iu.test(file));
+                return success(`Exported ${application}: ${files.length} file(s), ${displays.length} display(s)${alarms.length === 0 ? ', no alarms' : ', alarms'}${tags.length === 0 ? ', no tags CSV' : ', tags CSV'}${manifests.length === 0 ? '' : `, ${manifests.length} import manifest(s)`}${warnings.length === 0 ? '' : `; ${warnings.length} warning(s)`}.`, { application, output_root: destination, files, display_count: displays.length, alarms, tags, manifests, warnings }, [{ tool: 'ftview_open', args: { root: destination }, why: 'Open the fresh export and author against it.' }], VENDOR_COVERAGE);
             },
         }),
     ];

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

@@ -37,13 +37,53 @@ export interface VendorResult<T> {
  */
 export declare function listApplications(): Promise<VendorResult<readonly MeApplication[]>>;
 /**
- * Export one application's displays and globals into a new folder.
+ * Export one application's displays, globals, alarms and tags into a new folder.
+ *
+ * The export server covers displays, global objects and project settings. The
+ * alarm setup and the tag database live beside the application in the Studio
+ * project store, and `ExportAll` does not copy them, so this function does:
+ * without them a "full" export has no tags to bind and no alarms to review.
+ *
+ * Those two files are snapshots Studio writes when it exports them from their
+ * editors, not live views of the database, so each copy is checked against the
+ * application database's timestamp and a stale one is reported rather than
+ * silently handed over as current.
  *
  * @param application - Application name as listed.
  * @param destination - Folder to create and fill.
- * @returns Files written, relative to the destination.
+ * @param documentsRoot - Public Documents folder, injectable for tests.
+ * @returns Files written and any freshness warnings.
+ */
+export declare function exportApplication(application: string, destination: string, documentsRoot?: string): Promise<VendorResult<ExportResult>>;
+/** One export run's files and freshness warnings. */
+export interface ExportResult {
+    /** Files written, relative to the destination. */
+    readonly files: readonly string[];
+    /** Components that are missing or older than the application database. */
+    readonly warnings: readonly string[];
+}
+/** What the project store contributed to an export. */
+export interface ProjectExtras {
+    /** Export-relative paths copied from the store. */
+    readonly copied: readonly string[];
+    /** Why a component is missing or possibly stale. */
+    readonly warnings: readonly string[];
+}
+/** The Studio project store that holds one application's alarms and tags. */
+export declare function projectFolder(application: string, documentsRoot?: string): string | undefined;
+/**
+ * Copy the alarm setup and the tag CSV from the project store into an export.
+ *
+ * The file names and layout match what Studio writes when it exports the whole
+ * application (`Alarms/Alarms.xml`, `Tags/<application>.csv`), so a reader
+ * cannot tell this export from a hand-made one.
+ *
+ * @param application - Application name.
+ * @param destination - Export folder that already exists.
+ * @param documentsRoot - Public Documents folder, injectable for tests.
+ * @returns Paths copied and any staleness warnings.
  */
-export declare function exportApplication(application: string, destination: string): Promise<VendorResult<readonly string[]>>;
+export declare function copyProjectExtras(application: string, destination: string, documentsRoot?: string): ProjectExtras;
 /**
  * Back one application up to a zip.
  *

package/vendor/ftview/lib/vendor.js

@@ -11,7 +11,7 @@
  * @module dsh-engineering-ftview/vendor
  */
 import { spawn } from 'node:child_process';
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 /** CLSID of the ME export server (`MEExport.exe`). */
 export const EXPORT_CLSID = '9d882577-aa92-466b-a749-6d6b5093b623';
@@ -88,13 +88,24 @@ export async function listApplications() {
     }
 }
 /**
- * Export one application's displays and globals into a new folder.
+ * Export one application's displays, globals, alarms and tags into a new folder.
+ *
+ * The export server covers displays, global objects and project settings. The
+ * alarm setup and the tag database live beside the application in the Studio
+ * project store, and `ExportAll` does not copy them, so this function does:
+ * without them a "full" export has no tags to bind and no alarms to review.
+ *
+ * Those two files are snapshots Studio writes when it exports them from their
+ * editors, not live views of the database, so each copy is checked against the
+ * application database's timestamp and a stale one is reported rather than
+ * silently handed over as current.
  *
  * @param application - Application name as listed.
  * @param destination - Folder to create and fill.
- * @returns Files written, relative to the destination.
+ * @param documentsRoot - Public Documents folder, injectable for tests.
+ * @returns Files written and any freshness warnings.
  */
-export async function exportApplication(application, destination) {
+export async function exportApplication(application, destination, documentsRoot) {
     if (existsSync(destination))
         return { error: `A file or folder already exists at ${destination}. Export into a new folder.` };
     const result = await runPowerShell('powershell.exe', EXPORT_SCRIPT, { clsid: EXPORT_CLSID, app: application, dest: destination });
@@ -102,6 +113,7 @@ export async function exportApplication(application, destination) {
         return { error: `Export failed: ${result.stderr.trim() || `exit ${result.code}`}` };
     if (!existsSync(destination))
         return { error: 'The engine reported success but wrote no folder.' };
+    const extras = copyProjectExtras(application, destination, documentsRoot);
     const files = [];
     const walk = (directory, prefix) => {
         for (const entry of readdirSync(directory, { withFileTypes: true })) {
@@ -113,7 +125,85 @@ export async function exportApplication(application, destination) {
         }
     };
     walk(destination, '');
-    return { value: files.sort() };
+    return { value: { files: files.sort(), warnings: extras.warnings } };
+}
+/** The Studio project store that holds one application's alarms and tags. */
+export function projectFolder(application, documentsRoot = join(process.env.PUBLIC ?? 'C:/Users/Public', 'Documents')) {
+    const folder = join(documentsRoot, 'RSView Enterprise/ME/HMI projects', application);
+    return existsSync(folder) ? folder : undefined;
+}
+/** A readable date for one file's timestamp. */
+function modifiedOn(path) {
+    try {
+        return statSync(path).mtime.toISOString().slice(0, 10);
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** A warning when one copied snapshot predates the application database. */
+function freshness(file, relative, database) {
+    if (database === undefined)
+        return undefined;
+    try {
+        if (statSync(file).mtimeMs + 60_000 >= statSync(database).mtimeMs)
+            return undefined;
+        return `${relative} was written ${modifiedOn(file)}, older than the application database (${modifiedOn(database)}); it may not reflect recent changes. Studio refreshes it on its next full export.`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Copy the alarm setup and the tag CSV from the project store into an export.
+ *
+ * The file names and layout match what Studio writes when it exports the whole
+ * application (`Alarms/Alarms.xml`, `Tags/<application>.csv`), so a reader
+ * cannot tell this export from a hand-made one.
+ *
+ * @param application - Application name.
+ * @param destination - Export folder that already exists.
+ * @param documentsRoot - Public Documents folder, injectable for tests.
+ * @returns Paths copied and any staleness warnings.
+ */
+export function copyProjectExtras(application, destination, documentsRoot) {
+    const source = projectFolder(application, documentsRoot);
+    if (source === undefined) {
+        return { copied: [], warnings: [`No Studio project folder was found for ${application}, so alarms and tags were not exported.`] };
+    }
+    const database = join(source, `${application}.med`);
+    const copied = [];
+    const warnings = [];
+    const alarms = join(source, 'Alarms.xml');
+    if (existsSync(alarms)) {
+        const target = join(destination, 'Alarms');
+        mkdirSync(target, { recursive: true });
+        copyFileSync(alarms, join(target, 'Alarms.xml'));
+        copied.push('Alarms/Alarms.xml');
+        const warning = freshness(alarms, 'Alarms/Alarms.xml', existsSync(database) ? database : undefined);
+        if (warning !== undefined)
+            warnings.push(warning);
+    }
+    else {
+        warnings.push('No Alarms.xml in the application store, so alarms were not exported. Export alarm setup from Studio once.');
+    }
+    // Studio names the tag file `<application>-Tags.CSV`; match the suffix
+    // case-insensitively because older applications used `.csv`.
+    const entries = readdirSync(source, { withFileTypes: true });
+    const tags = entries.find(entry => entry.isFile() && /-tags\.csv$/iu.test(entry.name));
+    if (tags !== undefined) {
+        const target = join(destination, 'Tags');
+        mkdirSync(target, { recursive: true });
+        copyFileSync(join(source, tags.name), join(target, `${application}.csv`));
+        copied.push(`Tags/${application}.csv`);
+        const warning = freshness(join(source, tags.name), `Tags/${application}.csv`, existsSync(database) ? database : undefined);
+        if (warning !== undefined)
+            warnings.push(warning);
+    }
+    else {
+        warnings.push('No tag CSV in the application store, so tags were not exported. Export the tag database from Studio once.');
+    }
+    return { copied, warnings };
 }
 /**
  * Back one application up to a zip.