@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+/** Host half of the engineering bundle: registers nothing; the patch and the client face do the work. */
+export declare function apply(): void

package/lib/index.js

@@ -0,0 +1,9 @@
+/**
+ * Host half of the engineering bundle.
+ *
+ * The bundle's work happens in its patch (`cordis.patch.yml`: the tool policy
+ * and the product rows) and in its client face (`./client`). This entry exists
+ * because a client bundle is discovered through a *mounted* package row, and a
+ * row mounts a package root. It registers nothing of its own.
+ */
+export function apply() {}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Engineering",
+    "description": "Automation-engineering plugins for Studio 5000, FactoryTalk View, FactoryTalk Optix, MotionWorks IEC and CAD drawings."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "工程",
+    "description": "面向 Studio 5000、FactoryTalk View、FactoryTalk Optix、MotionWorks IEC 与 CAD 图纸的自动化工程插件。"
+  }
+}

package/package.json

@@ -1,6 +1,97 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0",
+  "description": "AryaCode engineering bundle: one install surface and one tool-exposure policy for the Studio 5000 L5X, FactoryTalk View and MotionWorks IEC plugins, with skill links for Optix and CAD.",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "plugin",
+    "bundle",
+    "engineering",
+    "automation",
+    "plc",
+    "studio-5000",
+    "factorytalk",
+    "motionworks"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KonnectSuite/dsh-engineering.git"
+  },
+  "homepage": "https://github.com/KonnectSuite/dsh-engineering#readme",
+  "bugs": {
+    "url": "https://github.com/KonnectSuite/dsh-engineering/issues"
+  },
+  "files": [
+    "cordis.patch.yml",
+    "lib/**/*",
+    "locale/*.json",
+    "vendor/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar-documentpreview",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-api-workspace-files",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-tool-ft-optix": "https://github.com/KonnectSuite/KonnectSuite.github.io/releases/download/plugins-v0.3.0/deepseek-ai-dsh-tool-ft-optix-0.2.1-rc.3.tgz"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-tool-skill": "^0.2.0-rc.2"
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.0",
+    "tsx": "^4.23.15"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./l5x": "./vendor/l5x/lib/index.js",
+    "./l5x/skill": "./vendor/l5x/lib/skill.js",
+    "./l5x/editing": "./vendor/l5x/lib/editing.js",
+    "./l5x/live": "./vendor/l5x/lib/live.js",
+    "./l5x/studio": "./vendor/l5x/lib/studio.js",
+    "./ftview": "./vendor/ftview/lib/index.js",
+    "./ftview/skill": "./vendor/ftview/lib/skill.js",
+    "./ftview/edit": "./vendor/ftview/lib/edit.js",
+    "./ftview/studio": "./vendor/ftview/lib/studio.js",
+    "./mwi": "./vendor/mwi/lib/index.js",
+    "./mwi/read": "./vendor/mwi/lib/read.js",
+    "./mwi/skill": "./vendor/mwi/lib/skill.js",
+    "./mwi/verify": "./vendor/mwi/lib/verify.js",
+    "./mwi/edit": "./vendor/mwi/lib/edit.js"
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/patch.spec.mjs test/docs.spec.mjs test/tool-reference.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs",
+    "docs:tools": "tsx scripts/gen-tool-reference.ts",
+    "docs:check": "tsx scripts/gen-tool-reference.ts --check",
+    "build:client": "node scripts/build-client.mjs",
+    "assemble": "node scripts/assemble.mjs"
+  }
 }

package/vendor/ftview/README.md

@@ -0,0 +1,55 @@
+# dsh-engineering-ftview
+
+FactoryTalk View ME tools for the `dsh-engineering` bundle. Three loader entries share one package:
+
+| Entry | Tools | Purpose |
+|---|---|---|
+| `dsh-engineering-ftview` | 6 read tools | Open an export folder, list and read displays and HMI tags, search, check, compare |
+| `dsh-engineering-ftview/edit` | 5 tools | Stage display and tag changes, validate, apply to a new folder |
+| `dsh-engineering-ftview/studio` | 3 tools | Discover Studio, preflight changed files, plan the manual import |
+
+The `factorytalk-view` guidance ships as the separate `dsh-engineering-ftview/skill` entry.
+
+## Read surface
+
+`ftview_open` scans one export folder and returns a `view_id`. `ftview_list` pages displays or tags,
+`ftview_get` reads one display (named objects) or one tag row, `ftview_find` searches names and text,
+`ftview_check` reports tag CSV integrity, duplicate names and unparsed files, and `ftview_compare`
+diffs two exports by display name, tag name and file hash.
+
+This is a TypeScript redesign, not a port of the old Python plugin: no `engine.py`, no `lxml`, no
+`ftview_project_start`/`environment`/`stage_register` tools.
+
+## Editing
+
+`ftview_draft_display_set`, `ftview_draft_display_add` and `ftview_draft_tag_upsert` stage one change
+per call; `ftview_validate` applies the staged edits to a re-parsed copy and reports changed files;
+`ftview_apply` writes a new export folder, leaving the source untouched.
+
+## Studio
+
+`ftview_studio_status` discovers installed FactoryTalk View ME tooling and schemas.
+`ftview_studio_preflight` checks changed files for import problems, including Studio name
+restrictions. `ftview_studio_handoff` returns the ordered manual import plan. No vendor utility runs.
+
+## Configuration
+
+| Entry | Option | Default |
+|---|---|---|
+| read | `maxFiles` | 2000 |
+| edit | `maxDraftOperations` | 100 |
+| studio | `searchRoots` | the two Rockwell Programs folders |
+
+## Boundary
+
+The surface parses documented text exports (display XML and the HMI tag CSV). It does not decode MER
+or MED, contact a terminal, validate against vendor XSD, bind tags to a PLC, or drive Studio.
+FactoryTalk View SE and FactoryTalk Optix are different products and are not analyzed here.
+
+## Develop
+
+```sh
+pnpm install
+pnpm run build
+pnpm test
+```

package/vendor/ftview/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: factorytalk-view
+description: Design and support FactoryTalk View ME and PanelView Plus applications from documented text exports: displays, HMI tags, structural checks and export comparison.
+whenToUse: Use when the user asks about FactoryTalk View ME, PanelView Plus, ME display exports, HMI tags, or comparing ME exports. Route FactoryTalk View SE and Optix to their own surfaces.
+---
+
+# FactoryTalk View ME engineering
+
+## Boundary
+
+This surface reads and stages changes to documented text exports: display XML and the HMI tag CSV.
+A staged edit is written to a NEW export folder; the source is never modified. The Studio entry plans
+a manual import for a human; it does not drive Studio, contact a terminal, or decode MER or MED
+databases.
+
+## Start
+
+1. Call `ftview_open` with the export folder. Keep the returned `view_id`.
+2. Later calls may omit `view_id` when exactly one export is open.
+3. Ask only for the exports the task needs: display XML for display work, the tag CSV for tag work,
+   L5X only when PLC binding matters.
+
+## Inspect
+
+- `ftview_list` enumerates displays or tags, with a name filter and paging.
+- `ftview_get` reads one display (its named objects) or one tag row.
+- `ftview_find` searches displays, object names, object attribute values and tags.
+
+## Check and compare
+
+- `ftview_check` reports structural findings: tag CSV integrity, duplicate display/object/tag names,
+  and files that did not parse. It is not vendor schema validation and says nothing about PLC
+  binding.
+- `ftview_compare` compares two opened exports by display name, tag name and file hash.
+
+## Editing
+
+The `ftview-edit` entry stages changes; it may be disabled in this profile. If a draft tool is
+unavailable, say editing is not enabled here rather than trying another tool.
+
+- `ftview_draft_display_set` stages one attribute change on a display or one of its named objects.
+- `ftview_draft_display_add` stages a new display by copying an existing display file.
+- `ftview_draft_tag_upsert` stages one HMI tag description/type change or a new tag row.
+- One operation per call. Each returns the draft id and the operation count; nothing is written yet.
+- `ftview_validate` applies the staged edits to a re-parsed copy and reports the changed files.
+- `ftview_apply` writes a NEW export folder. It never modifies the source.
+
+After applying, reopen the written folder with `ftview_open` and compare it with the source using
+`ftview_compare`.
+
+## Studio
+
+The `ftview-studio` entry plans a manual import; it may be disabled.
+
+- `ftview_studio_status` discovers installed ME tooling, schemas and help files.
+- `ftview_studio_preflight` checks the files that differ between two exports for Studio import
+  problems, including name restrictions.
+- `ftview_studio_handoff` returns the ordered manual import plan for a human in FactoryTalk View
+  Studio. No vendor utility runs and no file is written.
+
+## Reporting
+
+- Every result carries `summary`, `data`, `next` and `coverage`. Read `coverage` before claiming
+  completeness.
+- State what the export cannot prove: XSD validity, PLC binding, runtime behavior, visual rendering,
+  and anything absent from the supplied export.
+- Quote the display file and object name for a finding.
+- Do not call a tag unused from the absence of references in displays; other consumers are invisible
+  here.
+
+## Out of scope
+
+FactoryTalk View SE and FactoryTalk Optix are different products and are not analyzed here. MER/MED
+databases are not decoded, and no tool contacts a PanelView terminal or changes runtime data.

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

@@ -0,0 +1,27 @@
+/**
+ * Structural checks shared by the read and editing entries.
+ *
+ * @module dsh-engineering-ftview/checks
+ */
+import type { DisplayFile, TagRow } from './model.ts';
+/** One finding the check reports. */
+export interface Finding {
+    readonly rule: string;
+    readonly severity: 'error' | 'warning' | 'info';
+    readonly message: string;
+    readonly evidence: unknown;
+}
+/** The application parts the checks read. */
+export interface Checkable {
+    readonly displays: readonly DisplayFile[];
+    readonly tags: readonly TagRow[];
+    readonly tagErrors: readonly string[];
+    readonly diagnostics: readonly string[];
+}
+/**
+ * Run the structural checks.
+ *
+ * @param app - Displays, tags and the diagnostics from scanning.
+ * @returns Findings in rule order.
+ */
+export declare function findingsOf(app: Checkable): Finding[];

package/vendor/ftview/lib/checks.js

@@ -0,0 +1,39 @@
+/**
+ * Structural checks shared by the read and editing entries.
+ *
+ * @module dsh-engineering-ftview/checks
+ */
+/**
+ * Run the structural checks.
+ *
+ * @param app - Displays, tags and the diagnostics from scanning.
+ * @returns Findings in rule order.
+ */
+export function findingsOf(app) {
+    const findings = [];
+    for (const error of app.tagErrors)
+        findings.push({ rule: 'TAG_CSV', severity: 'warning', message: error, evidence: { file: 'tag CSV' } });
+    for (const diagnostic of app.diagnostics)
+        findings.push({ rule: 'UNPARSED_FILE', severity: 'warning', message: diagnostic, evidence: { file: diagnostic.split(':')[0] } });
+    const displayNames = new Set();
+    for (const display of app.displays) {
+        if (displayNames.has(display.name))
+            findings.push({ rule: 'DUPLICATE_DISPLAY_NAME', severity: 'warning', message: `Two displays are named ${JSON.stringify(display.name)}.`, evidence: { display: display.name, file: display.file } });
+        displayNames.add(display.name);
+        const objectNames = new Set();
+        for (const object of display.objects) {
+            if (object.name === undefined)
+                continue;
+            if (objectNames.has(object.name))
+                findings.push({ rule: 'DUPLICATE_OBJECT_NAME', severity: 'warning', message: `Display ${JSON.stringify(display.name)} has more than one object named ${JSON.stringify(object.name)}.`, evidence: { display: display.name, object: object.name } });
+            objectNames.add(object.name);
+        }
+    }
+    const tagNames = new Set();
+    for (const tag of app.tags) {
+        if (tagNames.has(tag.name))
+            findings.push({ rule: 'DUPLICATE_TAG_NAME', severity: 'error', message: `The tag CSV declares ${JSON.stringify(tag.name)} more than once.`, evidence: { tag: tag.name } });
+        tagNames.add(tag.name);
+    }
+    return findings;
+}

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

@@ -0,0 +1,208 @@
+/**
+ * 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
+ */
+/** How completely an answer covers the request. */
+export interface Coverage {
+    readonly complete: boolean;
+    readonly unverified: readonly string[];
+}
+/** One suggested follow-up call. */
+export interface NextStep {
+    readonly tool: string;
+    readonly args?: Readonly<Record<string, unknown>>;
+    readonly why: string;
+}
+/** The success document every tool returns. */
+export interface Success {
+    readonly summary: string;
+    readonly data: unknown;
+    readonly next: readonly NextStep[];
+    readonly coverage: Coverage;
+}
+/** A failure the caller can usually repair. */
+export declare class EngineeringError extends Error {
+    readonly code: string;
+    readonly fix: string;
+    readonly candidates: readonly string[];
+    /**
+     * @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: string, message: string, fix: string, candidates?: readonly string[]);
+}
+/**
+ * Convert any thrown value into the error envelope.
+ *
+ * @param error - The thrown value.
+ * @returns The envelope the tool registry reports.
+ */
+export declare function errorEnvelope(error: unknown): {
+    error: {
+        code: string;
+        message: string;
+        fix: string;
+        candidates: readonly string[];
+    };
+};
+/** Build one success document. */
+export declare function success(summary: string, data: unknown, next: readonly NextStep[], coverage: Coverage): Success;
+/** One JSON Schema property, always described. */
+export interface ParameterSchema {
+    readonly type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object';
+    readonly description: string;
+    readonly enum?: readonly string[];
+    readonly items?: ParameterSchema;
+    readonly default?: unknown;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly properties?: Readonly<Record<string, ParameterSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+}
+/** A described string parameter. */
+export declare function string(description: string, extra?: Partial<ParameterSchema>): ParameterSchema;
+/** A described integer parameter with an optional range. */
+export declare function integer(description: string, extra?: Partial<ParameterSchema>): ParameterSchema;
+/** A described enum parameter. */
+export declare function choice(description: string, values: readonly string[], extra?: Partial<ParameterSchema>): ParameterSchema;
+/** One object element of an array parameter. */
+export declare function objectItem(description: string, properties: Readonly<Record<string, ParameterSchema>>, required?: readonly string[]): ParameterSchema;
+/** An array of one parameter type. */
+export declare function list(description: string, items: ParameterSchema, extra?: Partial<ParameterSchema>): ParameterSchema;
+/** The `parameters` object of one tool. */
+export interface Parameters {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, ParameterSchema>>;
+    readonly required: readonly string[];
+    readonly additionalProperties: false;
+}
+/**
+ * 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 declare function object(properties: Readonly<Record<string, ParameterSchema>>, required?: readonly string[]): Parameters;
+/** One directory entry the filesystem provider reports. */
+export interface DirEntry {
+    readonly name: string;
+    readonly type: string;
+}
+/** The filesystem operations this package uses. */
+export interface FsService {
+    resolve(path: string, options?: {
+        readonly signal?: AbortSignal;
+        readonly cwd?: string;
+    }): Promise<string>;
+    stat(path: string, signal?: AbortSignal): Promise<{
+        readonly type: string;
+    } | undefined>;
+    readBytes(path: string, signal: AbortSignal | undefined, maxBytes?: number): Promise<Uint8Array>;
+    listDir?(path: string, signal?: AbortSignal): Promise<readonly DirEntry[]>;
+    writeText?(path: string, text: string, options?: {
+        readonly kind?: 'createIfAbsent' | 'overwrite';
+    }, signal?: AbortSignal): Promise<void>;
+}
+/** A path resolved by the harness filesystem into its backend identity. */
+export interface FsTarget {
+    /** Opaque key for stale guards and target lookup. */
+    readonly targetKey: unknown;
+    /** Path for model- and UI-facing output. */
+    readonly displayPath: string;
+}
+/** The harness filesystem as it is actually provided: operations take resolved targets. */
+export interface RawFsService {
+    resolve(path: string, options?: {
+        readonly signal?: AbortSignal;
+        readonly cwd?: string;
+    }): Promise<FsTarget | string>;
+    stat(target: FsTarget | string, signal?: AbortSignal): Promise<{
+        readonly type: string;
+    } | undefined>;
+    readBytes(target: FsTarget | string, signal: AbortSignal | undefined, maxBytes?: number): Promise<Uint8Array>;
+    listDir?(target: FsTarget | string, signal?: AbortSignal): Promise<readonly DirEntry[]>;
+    writeText?(target: FsTarget | string, text: string, options?: {
+        readonly kind?: 'createIfAbsent' | 'overwrite';
+    }, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * 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 declare function stringFs(service: RawFsService): FsService;
+/** The tool registry the plugin registers into. */
+export interface ToolRegistry {
+    register(definition: ToolDefinition): void;
+}
+/** The services a composition must provide before this plugin loads. */
+export interface PluginContext {
+    readonly tools: ToolRegistry;
+    readonly fs: RawFsService;
+    provide?(name: string, value: unknown): void;
+    get?(name: string): unknown;
+}
+/** The context a tool body receives. */
+export interface ExecContext {
+    readonly signal?: AbortSignal;
+    readonly cwd?: string;
+    readonly chat?: object;
+}
+/** One text block the transcript renders. */
+export interface TextBlock {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** The output declaration every registered tool carries. */
+export interface ToolOutput {
+    readonly schema: {
+        readonly type: 'object';
+        readonly additionalProperties: boolean;
+    };
+    render(args: unknown, value: unknown): readonly TextBlock[];
+}
+/** One registered tool. */
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Parameters;
+    readonly output: ToolOutput;
+    execute(args: Readonly<Record<string, unknown>>, exec: ExecContext): Promise<unknown>;
+}
+/** One tool body before the shared envelope and error handling are attached. */
+export interface ToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Parameters;
+    run(args: Readonly<Record<string, unknown>>, exec: ExecContext): Promise<unknown>;
+}
+/**
+ * Wrap one tool body in the shared envelope and error handling.
+ *
+ * @param spec - Tool identity and body.
+ * @returns The definition the registry accepts.
+ */
+export declare function tool(spec: ToolSpec): ToolDefinition;
+/** A required string argument. */
+export declare function requiredString(args: Readonly<Record<string, unknown>>, name: string): string;
+/** An optional string argument. */
+export declare function optionalString(args: Readonly<Record<string, unknown>>, name: string): string | undefined;
+/** An optional integer argument. */
+export declare function optionalInteger(args: Readonly<Record<string, unknown>>, name: string): number | undefined;