@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/mwi/lib/core/ps-bridge.js

@@ -0,0 +1,127 @@
+/**
+ * The PowerShell transport for the MotionWorks COM bridge.
+ *
+ * The bridge is a 32-bit PowerShell process that polls a request file and writes
+ * one response file. Files, not stdio: a confined harness cannot open named
+ * pipes, and `Mwt.exe` is a 32-bit LocalServer32 that a 64-bit client cannot
+ * instantiate at all.
+ *
+ * This client owns the mailbox, serializes requests, starts the bridge once and
+ * maps the bridge's answer onto the typed bridge contract.
+ *
+ * @module dsh-engineering-mwi/core/ps-bridge
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { MwiError } from "./errors.js";
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * A serialized client over the file mailbox, matching the legacy bridge protocol.
+ */
+export class PowerShellBridgeTransport {
+    options;
+    ipcDir;
+    requestPath;
+    responsePath;
+    startupMs;
+    spawned = false;
+    queue = Promise.resolve();
+    /**
+     * @param options - Bridge location and workspace authorization.
+     */
+    constructor(options) {
+        this.options = options;
+        this.ipcDir = options.ipcDir ?? join(tmpdir(), '@aryacode/dsh-engineering-mwi', `${process.pid}-${randomUUID()}`);
+        this.requestPath = join(this.ipcDir, 'req.json');
+        this.responsePath = join(this.ipcDir, 'res.json');
+        this.startupMs = options.startupMs ?? 12_000;
+    }
+    /** The mailbox this client owns; exposed for diagnostics. */
+    get mailbox() {
+        return this.ipcDir;
+    }
+    /**
+     * Send one request and wait for its response.
+     *
+     * @param request - Operation and arguments.
+     * @param timeoutMs - Hard operation budget.
+     * @param signal - Cancellation owned by the caller.
+     * @returns The bridge's answer.
+     */
+    async send(request, timeoutMs, signal) {
+        const pending = this.queue.then(async () => await this.exchange(request, timeoutMs, signal));
+        this.queue = pending.catch(() => undefined);
+        return await pending;
+    }
+    /** Run one request after the previous one settled. */
+    async exchange(request, timeoutMs, signal) {
+        mkdirSync(this.ipcDir, { recursive: true });
+        this.spawnBridge();
+        const id = randomUUID();
+        const payload = {
+            id,
+            verb: request.operation,
+            ...request.arguments,
+            workspace: this.options.workspace,
+            stage_root: this.options.stageRoot,
+        };
+        const staged = `${this.requestPath}.tmp`;
+        rmSync(this.responsePath, { force: true });
+        writeFileSync(staged, JSON.stringify(payload), 'utf8');
+        renameSync(staged, this.requestPath);
+        const deadline = Date.now() + Math.max(timeoutMs, this.startupMs);
+        while (Date.now() < deadline) {
+            if (signal?.aborted === true)
+                throw new MwiError('ABORTED', 'The MotionWorks call was cancelled.', 'Retry when the IDE is idle.');
+            const response = this.readResponse();
+            if (response !== undefined && response.id === id) {
+                return response.ok
+                    ? { ok: true, result: response.data }
+                    : { ok: false, error: { code: this.codeOf(response), message: response.error ?? 'The MotionWorks bridge refused the request.' } };
+            }
+            await sleep(120);
+        }
+        throw new MwiError('BRIDGE_TIMEOUT', `The MotionWorks bridge did not answer ${request.operation} within ${Math.round(timeoutMs / 1000)} s.`, 'Inspect the IDE: a modal dialog or a busy project blocks the bridge. Resolve it, then retry.');
+    }
+    /** Read the current response file, ignoring partial or malformed writes. */
+    readResponse() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.responsePath, 'utf8'));
+            return typeof parsed?.id === 'string' ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Map a bridge refusal to a stable code the model can act on. */
+    codeOf(response) {
+        const text = response.error ?? '';
+        if (/no running MotionWorks IDE/i.test(text))
+            return 'IDE_NOT_RUNNING';
+        if (/REFUSED/i.test(text))
+            return 'REFUSED';
+        if (/unknown verb/i.test(text))
+            return 'BRIDGE_UNKNOWN_OPERATION';
+        return 'BRIDGE_FAILED';
+    }
+    /** Start the 32-bit bridge once per client. */
+    spawnBridge() {
+        if (this.spawned)
+            return;
+        const launcher = join(this.options.bridgeDir, 'start_bridge.cmd');
+        const child = spawn('cmd.exe', ['/c', launcher], {
+            env: { ...process.env, MW_BRIDGE_DIR: this.ipcDir },
+            windowsHide: true,
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.on('error', () => {
+            this.spawned = false;
+        });
+        child.unref();
+        this.spawned = true;
+    }
+}

package/vendor/mwi/lib/core/result.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The model-facing success document.
+ *
+ * Every tool answers with a summary first and concrete next calls last, as in
+ * the other engineering products.
+ *
+ * @module dsh-engineering-mwi/core/result
+ */
+/** One call the reader can make next, with the reason it is useful. */
+export interface NextStep {
+    /** Tool name registered by this plugin. */
+    readonly tool: string;
+    /** Why this call answers the current question. */
+    readonly why: string;
+    /** Arguments worth passing; omitted when the tool needs none. */
+    readonly args?: Readonly<Record<string, unknown>>;
+}
+/** How much of the requested question the answer actually covers. */
+export interface Coverage {
+    /** Whether the requested scope was answered in full. */
+    readonly complete: boolean;
+    /** What this answer cannot establish, named rather than implied. */
+    readonly unverified: readonly string[];
+}
+/** A successful tool answer. */
+export interface Success<T> {
+    /** One sentence the reader can act on. */
+    readonly summary: string;
+    /** Tool-specific payload. */
+    readonly data: T;
+    /** Present when the answer has limits worth stating. */
+    readonly coverage?: Coverage;
+    /** Concrete next calls, most useful first. */
+    readonly next: readonly NextStep[];
+}
+/**
+ * Build a success document.
+ *
+ * @param summary - One sentence naming what was read.
+ * @param data - Tool-specific payload.
+ * @param next - Concrete next calls; may be empty when the answer is terminal.
+ * @param coverage - Limits of the answer, when it has any.
+ * @returns The document the tool returns.
+ */
+export declare function success<T>(summary: string, data: T, next?: readonly NextStep[], coverage?: Coverage): Success<T>;

package/vendor/mwi/lib/core/result.js

@@ -0,0 +1,20 @@
+/**
+ * The model-facing success document.
+ *
+ * Every tool answers with a summary first and concrete next calls last, as in
+ * the other engineering products.
+ *
+ * @module dsh-engineering-mwi/core/result
+ */
+/**
+ * Build a success document.
+ *
+ * @param summary - One sentence naming what was read.
+ * @param data - Tool-specific payload.
+ * @param next - Concrete next calls; may be empty when the answer is terminal.
+ * @param coverage - Limits of the answer, when it has any.
+ * @returns The document the tool returns.
+ */
+export function success(summary, data, next = [], coverage) {
+    return coverage === undefined ? { summary, data, next } : { summary, data, coverage, next };
+}

package/vendor/mwi/lib/core/tool.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The tool contract shared by every MWI row.
+ *
+ * The legacy surface declared 63 tools in one file. The redesign keeps one
+ * builder here so every tool carries a description, described parameters, the
+ * canonical output declaration and the shared failure document.
+ *
+ * @module dsh-engineering-mwi/core/tool
+ */
+import type { Parameters } from './params.ts';
+/** One content block the registry renders for the model. */
+export interface TextBlock {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** The canonical output declaration every tool must carry. */
+export interface ToolOutput {
+    readonly schema: {
+        readonly type: 'object';
+        readonly additionalProperties: boolean;
+    };
+    render(args: unknown, value: unknown): readonly TextBlock[];
+}
+/** The execution context a tool receives from the registry. */
+export interface ToolExec {
+    readonly signal?: AbortSignal;
+    readonly cwd?: string;
+    /** The calling chat; staged project handles are scoped to it. */
+    readonly chat?: object;
+    readonly sessionId?: string;
+    readonly agent?: unknown;
+}
+/** A registered tool. */
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Parameters;
+    readonly output: ToolOutput;
+    execute(args: Readonly<Record<string, unknown>>, exec?: ToolExec): Promise<unknown>;
+}
+/** The registry service. */
+export interface ToolRegistry {
+    register(definition: ToolDefinition): unknown;
+}
+/** One tool body, before the shared output and failure document are attached. */
+export interface ToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Parameters;
+    run(args: Readonly<Record<string, unknown>>, exec: ToolExec): Promise<unknown>;
+}
+/** The services a composition must provide before an MWI row loads. */
+export interface PluginContext {
+    readonly tools: ToolRegistry;
+    readonly logger?: {
+        info?(message: string): void;
+        warn?(message: string): void;
+    };
+    /** Register a service other entries in the same composition can consume. */
+    provide?(name: string, value: unknown): void;
+    /** Read a service another entry in the same composition provided. */
+    get?(name: string): unknown;
+}
+/**
+ * Render one tool answer as pretty JSON.
+ *
+ * @param _args - Accepted arguments; unused by this renderer.
+ * @param value - The validated canonical value.
+ * @returns One text block.
+ */
+export declare function jsonText(_args: unknown, value: unknown): readonly TextBlock[];
+/**
+ * Attach the canonical output declaration and the shared failure handling.
+ *
+ * @param spec - The tool body and its metadata.
+ * @returns The definition the registry receives.
+ */
+export declare function tool(spec: ToolSpec): ToolDefinition;
+/** Read one required string argument, or refuse with a fix. */
+export declare function requiredString(args: Readonly<Record<string, unknown>>, name: string): string;

package/vendor/mwi/lib/core/tool.js

@@ -0,0 +1,55 @@
+/**
+ * The tool contract shared by every MWI row.
+ *
+ * The legacy surface declared 63 tools in one file. The redesign keeps one
+ * builder here so every tool carries a description, described parameters, the
+ * canonical output declaration and the shared failure document.
+ *
+ * @module dsh-engineering-mwi/core/tool
+ */
+import { errorEnvelope, MwiError } from "./errors.js";
+/**
+ * Render one tool answer as pretty JSON.
+ *
+ * @param _args - Accepted arguments; unused by this renderer.
+ * @param value - The validated canonical value.
+ * @returns One text block.
+ */
+export function jsonText(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value, undefined, 2) }];
+}
+/**
+ * Attach the canonical output declaration and the shared failure handling.
+ *
+ * @param spec - The tool body and its metadata.
+ * @returns The definition the registry receives.
+ */
+export function tool(spec) {
+    if (!spec.name.startsWith('mw_')) {
+        throw new Error(`MWI tool ${spec.name} must use the mw_ prefix so the motionworks-iec switch governs it`);
+    }
+    if (spec.description.trim() === '')
+        throw new Error(`MWI tool ${spec.name} has no description`);
+    return {
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.parameters,
+        output: { schema: { type: 'object', additionalProperties: true }, render: jsonText },
+        async execute(args, exec) {
+            try {
+                return await spec.run(args, exec ?? {});
+            }
+            catch (error) {
+                return errorEnvelope(error);
+            }
+        },
+    };
+}
+/** Read one required string argument, or refuse with a fix. */
+export function requiredString(args, name) {
+    const value = args[name];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new MwiError('INVALID_ARGUMENT', `Argument ${name} must be a non-empty string.`, `Pass ${name} as a non-empty string; see the tool description for its expected value.`);
+    }
+    return value;
+}

package/vendor/mwi/lib/edit/compare.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Compare saved declarations with the native rows an edit expects.
+ *
+ * The evidence names the exact fields that differ; it never repairs a mismatch.
+ *
+ * @module dsh-engineering-mwi/edit/compare
+ */
+/** The declaration fields a saved/native comparison covers. */
+export declare const VARIABLE_FIELDS: readonly ["name", "type", "section", "group", "address", "initial_value", "description"];
+/** A comparison outcome the edit helpers accept. */
+export interface VariableComparison {
+    readonly accepted: boolean;
+    readonly evidence_kind: 'saved-declarations-only';
+    readonly expected_count: number;
+    readonly saved_count: number;
+    readonly missing: string[];
+    readonly unexpected: string[];
+    readonly changed: {
+        name: string;
+        fields: string[];
+        expected: Record<string, null | string>;
+        saved: Record<string, null | string>;
+    }[];
+    readonly errors: string[];
+}
+/**
+ * Compare expected and actual declaration rows by upper-cased name.
+ *
+ * @param expected - Declarations the edit expects after the mutation.
+ * @param actual - Declarations read back from the saved project.
+ * @returns The comparison with every difference named.
+ */
+export declare function compareVariables(expected: readonly Record<string, unknown>[], actual: readonly Record<string, unknown>[]): VariableComparison;

package/vendor/mwi/lib/edit/compare.js

@@ -0,0 +1,70 @@
+/**
+ * Compare saved declarations with the native rows an edit expects.
+ *
+ * The evidence names the exact fields that differ; it never repairs a mismatch.
+ *
+ * @module dsh-engineering-mwi/edit/compare
+ */
+/** The declaration fields a saved/native comparison covers. */
+export const VARIABLE_FIELDS = ['name', 'type', 'section', 'group', 'address', 'initial_value', 'description'];
+/**
+ * Compare expected and actual declaration rows by upper-cased name.
+ *
+ * @param expected - Declarations the edit expects after the mutation.
+ * @param actual - Declarations read back from the saved project.
+ * @returns The comparison with every difference named.
+ */
+export function compareVariables(expected, actual) {
+    const errors = [];
+    const index = (rows, label, strict) => {
+        if (!Array.isArray(rows))
+            throw new Error(`${label} declarations must be an array`);
+        const result = new Map();
+        for (const row of rows) {
+            if (typeof row?.name !== 'string' || row.name.trim() === '')
+                throw new Error(`${label}: missing variable name`);
+            if (strict && VARIABLE_FIELDS.some(field => !Object.hasOwn(row, field) || (row[field] !== null && typeof row[field] !== 'string'))) {
+                throw new Error(`${label}: supply every declaration field for ${String(row.name)}, including explicit nulls`);
+            }
+            const key = row.name.toUpperCase();
+            if (result.has(key))
+                errors.push(`${label}: duplicate variable ${String(row.name)}`);
+            result.set(key, row);
+        }
+        return result;
+    };
+    const wanted = index(expected, 'expected', true);
+    const found = index(actual, 'saved', false);
+    const missing = [];
+    const unexpected = [];
+    const changed = [];
+    for (const [key, row] of wanted) {
+        const saved = found.get(key);
+        if (saved === undefined) {
+            missing.push(String(row.name));
+            continue;
+        }
+        const fields = VARIABLE_FIELDS.filter(field => (row[field] ?? null) !== (saved[field] ?? null));
+        if (fields.length > 0) {
+            changed.push({
+                name: String(row.name),
+                fields: [...fields],
+                expected: Object.fromEntries(fields.map(field => [field, (row[field] ?? null)])),
+                saved: Object.fromEntries(fields.map(field => [field, (saved[field] ?? null)])),
+            });
+        }
+    }
+    for (const [key, row] of found)
+        if (!wanted.has(key))
+            unexpected.push(String(row.name));
+    return {
+        accepted: errors.length === 0 && missing.length === 0 && unexpected.length === 0 && changed.length === 0,
+        evidence_kind: 'saved-declarations-only',
+        expected_count: expected.length,
+        saved_count: actual.length,
+        missing,
+        unexpected,
+        changed,
+        errors,
+    };
+}

package/vendor/mwi/lib/edit.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `mwi-edit` entry: staged edits, validation and apply.
+ *
+ * Off by default. The row writes only the staged project and verifies that
+ * unrelated saved and native state did not change.
+ *
+ * @module dsh-engineering-mwi/edit
+ */
+import type { PluginContext } from './core/tool.ts';
+/** Plugin name in a composition. */
+export declare const name = "mwi-edit";
+/** Services this plugin cannot register without. */
+export declare const inject: readonly ["tools"];
+/**
+ * Register the edit tools.
+ *
+ * @param ctx - Plugin context with the tool registry.
+ */
+export declare function apply(ctx: PluginContext): void;
+export { editTools } from './tools/edit.ts';

package/vendor/mwi/lib/edit.js

@@ -0,0 +1,32 @@
+/**
+ * The `mwi-edit` entry: staged edits, validation and apply.
+ *
+ * Off by default. The row writes only the staged project and verifies that
+ * unrelated saved and native state did not change.
+ *
+ * @module dsh-engineering-mwi/edit
+ */
+import { editTools } from "./tools/edit.js";
+/** Plugin name in a composition. */
+export const name = 'mwi-edit';
+/** Services this plugin cannot register without. */
+export const inject = ['tools'];
+/**
+ * Register the edit tools.
+ *
+ * @param ctx - Plugin context with the tool registry.
+ */
+export function apply(ctx) {
+    if (process.platform !== 'win32') {
+        try {
+            ctx.logger?.info?.(`mwi-edit: skipped because this host is ${process.platform}; MotionWorks IEC requires Windows.`);
+        }
+        catch {
+            // A logger that refuses must not turn an unsupported host into a crash.
+        }
+        return;
+    }
+    for (const definition of editTools())
+        ctx.tools.register(definition);
+}
+export { editTools } from "./tools/edit.js";

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

@@ -0,0 +1,21 @@
+/**
+ * The `mwi-session` entry: project discovery and IDE lifecycle.
+ *
+ * The row registers on Windows only; the IDE is a Windows application and the
+ * bridge cannot exist elsewhere.
+ *
+ * @module dsh-engineering-mwi
+ */
+import type { PluginContext } from './core/tool.ts';
+/** Plugin name in a composition. */
+export declare const name = "mwi-session";
+/** Services this plugin cannot register without. */
+export declare const inject: readonly ["tools"];
+/**
+ * Register the session tools.
+ *
+ * @param ctx - Plugin context with the tool registry.
+ */
+export declare function apply(ctx: PluginContext): void;
+export { sessionTools } from './tools/session.ts';
+export { PowerShellSessionRuntime, runtimeFor } from './session/service.ts';

package/vendor/mwi/lib/index.js

@@ -0,0 +1,33 @@
+/**
+ * The `mwi-session` entry: project discovery and IDE lifecycle.
+ *
+ * The row registers on Windows only; the IDE is a Windows application and the
+ * bridge cannot exist elsewhere.
+ *
+ * @module dsh-engineering-mwi
+ */
+import { sessionTools } from "./tools/session.js";
+/** Plugin name in a composition. */
+export const name = 'mwi-session';
+/** Services this plugin cannot register without. */
+export const inject = ['tools'];
+/**
+ * Register the session tools.
+ *
+ * @param ctx - Plugin context with the tool registry.
+ */
+export function apply(ctx) {
+    if (process.platform !== 'win32') {
+        try {
+            ctx.logger?.info?.(`mwi-session: skipped because this host is ${process.platform}; MotionWorks IEC requires Windows.`);
+        }
+        catch {
+            // A logger that refuses must not turn an unsupported host into a crash.
+        }
+        return;
+    }
+    for (const definition of sessionTools())
+        ctx.tools.register(definition);
+}
+export { sessionTools } from "./tools/session.js";
+export { PowerShellSessionRuntime, runtimeFor } from "./session/service.js";

package/vendor/mwi/lib/read/service.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Read the saved project through the code engine.
+ *
+ * These reads describe the saved project, not the loaded IDE instance. Anything
+ * that needs the live object model says so in its coverage.
+ *
+ * @module dsh-engineering-mwi/read/service
+ */
+import type { EngineResult } from '../core/code-engine.ts';
+import type { ProjectRef } from '../session/project.ts';
+/** The engine surface the reads use; injectable for tests. */
+export interface ReadEngine {
+    run(verb: string, request: Readonly<Record<string, unknown>>, timeoutMs?: number, signal?: AbortSignal): Promise<EngineResult>;
+}
+/** One row in a listing. */
+export interface ListRow {
+    readonly name: string;
+    readonly [field: string]: unknown;
+}
+/** One literal match in a POU body. */
+export interface CodeMatch {
+    readonly pou: string;
+    readonly line: number;
+    readonly text: string;
+}
+/** Kinds `mw_list` can enumerate. */
+export declare const LIST_KINDS: readonly ["pou", "variable", "global", "type", "task", "library"];
+/** Kinds `mw_get` can read. */
+export declare const GET_KINDS: readonly ["pou", "type", "task", "block", "eip"];
+/** The saved-project read service. */
+export declare class ReadService {
+    private readonly engine;
+    /**
+     * @param engine - Code engine over the project files.
+     */
+    constructor(engine: ReadEngine);
+    /** Confirm the engine can read one project. */
+    workflow(project: ProjectRef): Promise<EngineResult>;
+    /**
+     * List one kind.
+     *
+     * @param project - Project to read.
+     * @param kind - Listing kind.
+     * @param options - Filter, paging and the POU for variable reads.
+     * @returns Rows and the total before paging.
+     */
+    list(project: ProjectRef, kind: string, options?: {
+        filter?: string;
+        offset?: number;
+        limit?: number;
+        pou?: string;
+    }): Promise<{
+        rows: ListRow[];
+        total: number;
+    }>;
+    /**
+     * Read one component by name.
+     *
+     * @param project - Project to read.
+     * @param kind - Component kind.
+     * @param name - Exact name.
+     * @param library - Library name for a block interface.
+     * @returns The component document.
+     */
+    get(project: ProjectRef, kind: string, name: string, library?: string): Promise<EngineResult>;
+    /**
+     * Search POU bodies for literal text.
+     *
+     * @param project - Project to read.
+     * @param query - Case-insensitive literal text.
+     * @param limit - Most matches.
+     * @returns Matches in project order.
+     */
+    search(project: ProjectRef, query: string, limit?: number): Promise<{
+        matches: CodeMatch[];
+        truncated: boolean;
+        scanned: number;
+    }>;
+    /**
+     * Find a symbol in POU bodies.
+     *
+     * @param project - Project to read.
+     * @param symbol - Declared or written symbol name.
+     * @param limit - Most matches.
+     * @returns Matches with the line that contains them.
+     */
+    references(project: ProjectRef, symbol: string, limit?: number): Promise<{
+        matches: CodeMatch[];
+        truncated: boolean;
+        scanned: number;
+    }>;
+    /**
+     * Run the static review surface.
+     *
+     * @param project - Project to read.
+     * @param options - Optional POU and proposed body.
+     * @returns Workflow, validation, unsupported-construct and program-review results.
+     */
+    review(project: ProjectRef, options?: {
+        pou?: string;
+        body?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Search help and reviewed references.
+     *
+     * @param project - Project used for the workspace cache.
+     * @param source - Help source: help, manual, reference or pattern.
+     * @param query - Search term; omitted lists what is available.
+     * @param limit - Most rows.
+     * @returns The engine document with its source named.
+     */
+    help(project: ProjectRef, source: string, query: string | undefined, limit?: number): Promise<EngineResult>;
+    /** Read every POU body, capped. */
+    private bodies;
+    /** Map one kind to rows. */
+    private rows;
+}