@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

package/vendor/mwi/lib/tools/session.js

@@ -0,0 +1,166 @@
+/**
+ * The session row: find, stage, open and close the project; report IDE state.
+ *
+ * An IDE that is not running is a state, not a failure: the tools report it and
+ * point at the start tool. Every mutation that touches the IDE names the consent
+ * it needs in its parameters.
+ *
+ * @module dsh-engineering-mwi/tools/session
+ */
+import { boolean, choice, integer, object, string } from "../core/params.js";
+import { success } from "../core/result.js";
+import { MwiError } from "../core/errors.js";
+import { tool } from "../core/tool.js";
+import { findProjects, stageRootOf, workspaceOf } from "../session/workspace.js";
+import { runtimeFor } from "../session/service.js";
+/** What every IDE answer cannot establish. */
+const IDE_COVERAGE = {
+    complete: false,
+    unverified: [
+        'runtime behavior of the loaded project',
+        'graphical placement and wiring of saved code',
+        'whether the loaded project matches the saved project after external changes',
+    ],
+};
+/** Run a bridge operation, return undefined when the IDE is simply not running. */
+async function optional(call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (error instanceof MwiError && error.code === 'IDE_NOT_RUNNING')
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * The session tools.
+ *
+ * @param runtimeOf - Workspace runtime factory; defaults to the PowerShell bridge.
+ * @returns Tool definitions in registration order.
+ */
+export function sessionTools(runtimeOf = runtimeFor) {
+    return [
+        tool({
+            name: 'mw_project_find',
+            description: 'Find MotionWorks IEC projects inside the calling workspace. Returns each .mwt, its expanded directory and whether a staged copy exists. Call this before staging or opening anything.',
+            parameters: object({
+                filter: string('Optional case-insensitive substring matched against the project name or path.'),
+                limit: integer('Most projects to return. Defaults to 20.', { minimum: 1, maximum: 100 }),
+            }),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const projects = findProjects(workspace, {
+                    filter: typeof args.filter === 'string' ? args.filter : undefined,
+                    limit: typeof args.limit === 'number' ? args.limit : 20,
+                });
+                const staged = projects.filter(project => project.staged !== null).length;
+                return success(projects.length === 0
+                    ? `No MotionWorks project was found inside ${workspace}.`
+                    : `Found ${projects.length} MotionWorks project(s) in ${workspace}; ${staged} already staged.`, { workspace, stage_root: stageRootOf(workspace), projects }, projects.length === 0
+                    ? []
+                    : [{ tool: 'mw_project_stage', why: 'Stage the intended project before opening it.', args: { source: projects[0]?.mwt } }], { complete: false, unverified: ['projects outside the workspace are never listed or staged'] });
+            },
+        }),
+        tool({
+            name: 'mw_ide_status',
+            description: 'Report whether MotionWorks IEC is running, which project is open, the automation version, the active view, the compile state and any blocking dialog. Call it before and after operations that change the IDE.',
+            parameters: object({}),
+            async run(_args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const status = await optional(async () => await runtimeOf(workspace).status());
+                if (status === undefined) {
+                    return success('MotionWorks IEC is not running.', { ide_running: false, workspace, stage_root: stageRootOf(workspace) }, [{ tool: 'mw_ide_start', why: 'Start the IDE with a staged workspace project.' }], IDE_COVERAGE);
+                }
+                const state = await optional(async () => await runtimeOf(workspace).ideState());
+                const blocked = state?.blocked === true;
+                return success(blocked
+                    ? 'MotionWorks IEC is running and blocked by a dialog.'
+                    : status.is_project_open === true
+                        ? `MotionWorks IEC is running with ${String(status.active_project ?? 'a project')} open.`
+                        : 'MotionWorks IEC is running with no project open.', { workspace, stage_root: stageRootOf(workspace), ...status, ...(state === undefined ? {} : { ide_state: state }) }, blocked
+                    ? [{ tool: 'mw_ide_status', why: 'Re-read after the dialog is resolved.' }]
+                    : [{ tool: 'mw_project_find', why: 'Confirm the project is the one in the workspace.' }], IDE_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_project_stage',
+            description: 'Copy one workspace project into the stage so the IDE opens a copy, never the original. The .mwt and its expanded directory are copied and the wrapper is bound to the staged directory.',
+            parameters: object({
+                source: string('Workspace project folder or its .mwt. Must be inside the workspace.'),
+                replace_existing: boolean('Replace an existing stage after review; defaults false. The previous stage is retained under backups/.'),
+            }, ['source']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const record = await runtimeOf(workspace).stage(String(args.source), { replace: args.replace_existing === true });
+                return success(`Staged ${record.name} from ${record.source}.`, record, [{ tool: 'mw_project_open', why: 'Open the staged project in the IDE.', args: { path: record.staged_mwt } }], { complete: false, unverified: ['the staged copy is byte-identical to the source; the source itself is untouched'] });
+            },
+        }),
+        tool({
+            name: 'mw_project_open',
+            description: 'Open one staged project in the running IDE. Refuses a path that is not a proven stage, and refuses to replace another open project without the exact approved path.',
+            parameters: object({
+                path: string('Staged .mwt path returned by mw_project_stage.'),
+                user_approved: boolean('True only after the user approved saving and closing another open project.'),
+                expected_project: string('Exact open project path named in that approval.'),
+            }, ['path']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const opened = await runtimeOf(workspace).open(String(args.path), {
+                    userApproved: args.user_approved === true,
+                    expectedProject: typeof args.expected_project === 'string' ? args.expected_project : undefined,
+                });
+                return success(opened.matches_request === false
+                    ? 'The open call returned, but the IDE has a different project open.'
+                    : `Opened ${String(opened.active_project ?? args.path)}.`, opened, [{ tool: 'mw_ide_status', why: 'Confirm the active project and compile state.' }], IDE_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_ide_start',
+            description: 'Start MotionWorks IEC with one staged project, or attach to the IDE that is already running. Refuses when several stages exist without a project argument.',
+            parameters: object({
+                project: string('Staged .mwt to start with. Omit when exactly one project is staged.'),
+            }),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const started = await runtimeOf(workspace).start(typeof args.project === 'string' ? args.project : undefined);
+                return success(started.already_running === true ? 'MotionWorks IEC was already running.' : 'MotionWorks IEC started.', started, [{ tool: 'mw_ide_status', why: 'Confirm the project and compile state after startup.' }], IDE_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_worksheet_open',
+            description: 'Open one code or variable worksheet, or resource globals, in the open staged project and verify the active view. Read-only: no edit, save, compile or download.',
+            parameters: object({
+                kind: choice('Worksheet kind: code or variables.', ['code', 'variables']),
+                pou: string('POU name for a code worksheet. Omit for globals.'),
+                inspect_only: boolean('Check the current editor instead of opening one; defaults false.'),
+            }, ['kind']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const kind = args.kind === 'code' ? 'code' : 'variables';
+                const opened = await runtimeOf(workspace).worksheet({
+                    kind,
+                    ...(typeof args.pou === 'string' ? { pou: args.pou } : {}),
+                    inspectOnly: args.inspect_only === true,
+                });
+                return success(`Opened the ${kind} worksheet${typeof args.pou === 'string' ? ` for ${args.pou}` : ''}.`, opened, [{ tool: 'mw_ide_status', why: 'Confirm the active view before editing.' }], IDE_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_project_close',
+            description: 'Close MotionWorks IEC, saving the open project, after explicit user approval for that exact project.',
+            parameters: object({
+                user_approved: boolean('True only after the user approved saving and closing MotionWorks.'),
+                expected_project: string('Exact open project path named in the approval.'),
+            }, ['user_approved']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const closed = await runtimeOf(workspace).close({
+                    userApproved: args.user_approved === true,
+                    expectedProject: typeof args.expected_project === 'string' ? args.expected_project : undefined,
+                });
+                return success(closed.closed === true ? 'MotionWorks IEC closed.' : 'MotionWorks IEC is still running.', closed, closed.closed === true ? [] : [{ tool: 'mw_ide_status', why: 'Inspect why the IDE did not close.' }], { complete: false, unverified: ['unsaved state after close'] });
+            },
+        }),
+    ];
+}

package/vendor/mwi/lib/tools/verify.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The verify row: compile, diagnostics and saved-source verification.
+ *
+ * Every tool here requires the open project to be a proven stage; the runtime
+ * refuses a workspace original.
+ *
+ * @module dsh-engineering-mwi/tools/verify
+ */
+import { type ToolDefinition } from '../core/tool.ts';
+import type { SessionRuntime } from '../session/service.ts';
+/** How the tools reach a workspace runtime; injectable for tests. */
+export type VerifyRuntimeFactory = (workspace: string) => SessionRuntime;
+/**
+ * The verify tools.
+ *
+ * @param runtimeOf - Workspace runtime factory; defaults to the PowerShell bridge.
+ * @returns Tool definitions in registration order.
+ */
+export declare function verifyTools(runtimeOf?: VerifyRuntimeFactory): readonly ToolDefinition[];

package/vendor/mwi/lib/tools/verify.js

@@ -0,0 +1,85 @@
+/**
+ * The verify row: compile, diagnostics and saved-source verification.
+ *
+ * Every tool here requires the open project to be a proven stage; the runtime
+ * refuses a workspace original.
+ *
+ * @module dsh-engineering-mwi/tools/verify
+ */
+import { choice, integer, object, string } from "../core/params.js";
+import { success } from "../core/result.js";
+import { tool } from "../core/tool.js";
+import { workspaceOf } from "../session/workspace.js";
+import { runtimeFor } from "../session/service.js";
+/** What a compile verdict cannot establish. */
+const VERIFY_COVERAGE = {
+    complete: false,
+    unverified: [
+        'runtime behavior of the compiled project',
+        'controller state and online logic',
+        'graphical placement and wiring',
+    ],
+};
+/**
+ * The verify tools.
+ *
+ * @param runtimeOf - Workspace runtime factory; defaults to the PowerShell bridge.
+ * @returns Tool definitions in registration order.
+ */
+export function verifyTools(runtimeOf = runtimeFor) {
+    return [
+        tool({
+            name: 'mw_compile',
+            description: 'Run Make (link changed sources), Build (full compile), or read the compile state of the open staged project. A verdict is the vendor engine\'s, not proof of runtime behavior.',
+            parameters: object({
+                mode: choice('Compile operation: make, build or state.', ['make', 'build', 'state']),
+            }),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const mode = (args.mode === 'make' || args.mode === 'build' ? args.mode : 'state');
+                const result = await runtimeOf(workspace).compile(mode);
+                const state = mode === 'state'
+                    ? `compiled=${String(result.is_compiled ?? 'unknown')}, modified=${String(result.is_modified ?? 'unknown')}`
+                    : `verdict ${String(result.verdict ?? result.status ?? 'reported')}`;
+                return success(`${mode === 'state' ? 'Compile state' : mode}: ${state}.`, result, [{ tool: 'mw_diagnostics', why: 'Read the IDE messages the verdict does not include.' }], VERIFY_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_diagnostics',
+            description: 'Read one IDE output pane (Errors, Warnings or Build) as text, with the compile state attached. The API returns a verdict but not the messages, so this is the only source for exact text.',
+            parameters: object({
+                pane: string('Output pane name. Defaults to Errors.'),
+                limit: integer('Most messages. Defaults to 200, maximum 500.', { minimum: 1, maximum: 500 }),
+            }),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const pane = typeof args.pane === 'string' && args.pane !== '' ? args.pane : 'Errors';
+                const result = await runtimeOf(workspace).diagnostics(pane, typeof args.limit === 'number' ? args.limit : 200);
+                const count = typeof result.count === 'number' ? result.count : 0;
+                return success(count === 0
+                    ? `${pane} has no messages; compile state is reported separately.`
+                    : `${pane}: ${count} message(s).`, result, [{ tool: 'mw_compile', why: 'Read the verdict behind these messages.' }], VERIFY_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_verify',
+            description: 'Capture a baseline of the saved project source and compile state, or compare the open project against a captured baseline. Reports added, removed and changed source files.',
+            parameters: object({
+                mode: choice('Capture a baseline or compare against one.', ['baseline', 'compare']),
+                baseline_id: string('Baseline id returned by a capture. Required when mode is compare.'),
+            }),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const mode = args.mode === 'compare' ? 'compare' : 'baseline';
+                const result = await runtimeOf(workspace).verify(mode, typeof args.baseline_id === 'string' ? args.baseline_id : undefined);
+                if (mode === 'baseline') {
+                    return success(`Captured baseline ${String(result.baseline_id)} for ${String(result.project)}.`, result, [{ tool: 'mw_verify', why: 'Compare against this baseline after a change.', args: { mode: 'compare', baseline_id: result.baseline_id } }], VERIFY_COVERAGE);
+                }
+                const matched = result.matched === true;
+                return success(matched ? 'The saved source matches the baseline.' : `The saved source changed since the baseline: ${String(result.changed?.length ?? 0)} changed file(s).`, result, matched
+                    ? [{ tool: 'mw_compile', why: 'Compile the verified source.' }]
+                    : [{ tool: 'mw_review', why: 'Review the changed project before compiling.' }], VERIFY_COVERAGE);
+            },
+        }),
+    ];
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The `mwi-verify` entry: compile, diagnostics and verification.
+ *
+ * @module dsh-engineering-mwi/verify
+ */
+import type { PluginContext } from './core/tool.ts';
+/** Plugin name in a composition. */
+export declare const name = "mwi-verify";
+/** Services this plugin cannot register without. */
+export declare const inject: readonly ["tools"];
+/**
+ * Register the verify tools.
+ *
+ * @param ctx - Plugin context with the tool registry.
+ */
+export declare function apply(ctx: PluginContext): void;
+export { verifyTools } from './tools/verify.ts';

package/vendor/mwi/lib/verify.js

@@ -0,0 +1,29 @@
+/**
+ * The `mwi-verify` entry: compile, diagnostics and verification.
+ *
+ * @module dsh-engineering-mwi/verify
+ */
+import { verifyTools } from "./tools/verify.js";
+/** Plugin name in a composition. */
+export const name = 'mwi-verify';
+/** Services this plugin cannot register without. */
+export const inject = ['tools'];
+/**
+ * Register the verify tools.
+ *
+ * @param ctx - Plugin context with the tool registry.
+ */
+export function apply(ctx) {
+    if (process.platform !== 'win32') {
+        try {
+            ctx.logger?.info?.(`mwi-verify: 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 verifyTools())
+        ctx.tools.register(definition);
+}
+export { verifyTools } from "./tools/verify.js";