@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,286 @@
+/**
+ * The edit row: replace code, edit declarations, change structure and apply.
+ *
+ * Editing is off by default. Every tool writes only the staged project, and the
+ * proven native helpers verify that unrelated saved and native state did not
+ * change.
+ *
+ * @module dsh-engineering-mwi/tools/edit
+ */
+import { boolean, choice, integer, list, object, objectItem, record, string } from "../core/params.js";
+import { success } from "../core/result.js";
+import { MwiError } from "../core/errors.js";
+import { tool } from "../core/tool.js";
+import { workspaceOf } from "../session/workspace.js";
+import { runtimeFor } from "../session/service.js";
+/** What a native edit cannot establish. */
+const EDIT_COVERAGE = {
+    complete: false,
+    unverified: [
+        'compilation and controller acceptance; the edit verifies saved/native state only',
+        'runtime behavior of the edited code',
+        'graphical bodies; only ST and IL text bodies are editable',
+    ],
+};
+/**
+ * The edit tools.
+ *
+ * @param runtimeOf - Workspace runtime factory; defaults to the PowerShell bridge.
+ * @returns Tool definitions in registration order.
+ */
+export function editTools(runtimeOf = runtimeFor) {
+    return [
+        tool({
+            name: 'mw_edit_code',
+            description: 'Replace one ST or IL body in the open staged project through the native ChangeCodeWS path. Supply exact find/replace changes with the body hash, or a complete body with the current body. Verifies saved and native state, then leaves compilation to mw_compile.',
+            parameters: object({
+                pou: string('Exact POU name.'),
+                changes: list('Exact find/replace changes; each must match its expected count.', objectItem('One exact change.', {
+                    find: string('Exact text to find.'),
+                    replace: string('Replacement text.'),
+                    count: integer('Expected non-overlapping occurrences; defaults 1.', { minimum: 1, maximum: 100 }),
+                }, ['find', 'replace'])),
+                expected_body_sha256: string('Exact 64-character text_body_sha256 from mw_get for kind pou, when using changes.'),
+                body: string('Complete replacement body, when not using changes.'),
+                expected_body: string('Current body that the complete replacement expects, when using body.'),
+            }, ['pou']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const pou = String(args.pou);
+                const changes = Array.isArray(args.changes) ? args.changes : undefined;
+                const hasChanges = changes !== undefined && changes.length > 0;
+                const hasBody = typeof args.body === 'string';
+                if (hasChanges === hasBody) {
+                    throw new MwiError('INVALID_ARGUMENT', 'Supply either changes with expected_body_sha256, or body with expected_body.', 'Use changes for a small exact patch, or body for a full replacement; do not mix them.');
+                }
+                if (hasChanges && typeof args.expected_body_sha256 !== 'string') {
+                    throw new MwiError('INVALID_ARGUMENT', 'Changes need expected_body_sha256.', 'Read the POU with mw_get and pass its text_body_sha256.');
+                }
+                if (hasBody && typeof args.expected_body !== 'string') {
+                    throw new MwiError('INVALID_ARGUMENT', 'A complete body needs expected_body.', 'Read the POU with mw_get and pass its current body.');
+                }
+                const result = await runtimeOf(workspace).editCode({
+                    pou,
+                    ...(hasChanges ? { changes, expectedHash: String(args.expected_body_sha256) } : { body: String(args.body), expectedBody: String(args.expected_body) }),
+                });
+                const verification = result.verification;
+                const accepted = verification?.accepted === true;
+                return success(accepted ? `Edited ${pou} and verified the saved and native state.` : `Edited ${pou}, but verification reported: ${verification?.errors?.join('; ') ?? 'unknown'}.`, result, accepted
+                    ? [{ tool: 'mw_compile', why: 'Compile the edited project.' }]
+                    : [{ tool: 'mw_verify', why: 'Capture a baseline and inspect the mismatch before another edit.' }], EDIT_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_edit_variables',
+            description: 'Add, edit or delete one declaration in the open staged project through the native IDE API. Edit replaces the complete seven-field declaration and optional boolean flags; delete needs approval and reference review.',
+            parameters: object({
+                operation: choice('Variable operation.', ['add', 'edit', 'delete']),
+                pou: string('POU for a local declaration; omit for resource globals.'),
+                name: string('Existing exact name for edit or delete.'),
+                declaration: record('Complete replacement declaration.', {
+                    name: string('Declaration name.'),
+                    type: string('Data type.'),
+                    section: string('Declaration section, for example VAR, VAR_GLOBAL or VAR_EXTERNAL.'),
+                    group: string('Declaration group.'),
+                    address: string('Direct address, or omit for none.'),
+                    initial_value: string('Initial value, or omit for none.'),
+                    description: string('Description, or omit for none.'),
+                }, ['name', 'type', 'section']),
+                flags: record('Explicit boolean native variable flags; omitted flags stay unchanged.', {
+                    retain: boolean('Retain flag.'),
+                    pdd: boolean('Persistent data flag.'),
+                    opc: boolean('OPC flag.'),
+                    disabled: boolean('Disabled flag.'),
+                    not_on_plc: boolean('Not-on-PLC flag.'),
+                    redundant: boolean('Redundant flag.'),
+                }),
+                user_approved: boolean('Approval for a deletion.'),
+                references_reviewed: boolean('Set after reviewing code and external references.'),
+                rename_reviewed: boolean('Set after reviewing references for a rename.'),
+            }, ['operation']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const operation = String(args.operation);
+                const raw = args.declaration;
+                let declaration;
+                if (operation !== 'delete') {
+                    if (raw === undefined)
+                        throw new MwiError('INVALID_ARGUMENT', 'An add or edit needs a declaration.', 'Pass name, type and section at minimum; every other field is explicit.');
+                    const text = (value) => typeof value === 'string' && value !== '' ? value : null;
+                    declaration = {
+                        name: String(raw.name),
+                        type: String(raw.type),
+                        section: String(raw.section),
+                        group: text(raw.group),
+                        address: text(raw.address),
+                        initial_value: text(raw.initial_value),
+                        description: text(raw.description),
+                    };
+                }
+                const result = await runtimeOf(workspace).editVariable({
+                    operation,
+                    ...(typeof args.pou === 'string' ? { pou: args.pou } : {}),
+                    ...(typeof args.name === 'string' ? { name: args.name } : {}),
+                    ...(declaration === undefined ? {} : { declaration }),
+                    ...(args.flags === undefined ? {} : { flags: args.flags }),
+                    ...(args.user_approved === true ? { user_approved: true } : {}),
+                    ...(args.references_reviewed === true ? { references_reviewed: true } : {}),
+                    ...(args.rename_reviewed === true ? { rename_reviewed: true } : {}),
+                });
+                const verification = result.verification;
+                const accepted = verification?.accepted === true;
+                return success(accepted ? `${operation} verified against the saved declarations.` : `${operation} did not verify: ${verification?.errors?.join('; ') ?? 'unknown'}.`, result, accepted ? [{ tool: 'mw_compile', why: 'Compile after the intended changes are complete.' }] : [{ tool: 'mw_verify', why: 'Inspect the mismatch before another edit.' }], EDIT_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_edit_structure',
+            description: 'Create, copy, rename, delete, convert or assign one POU, or create, edit, delete, assign or unassign one task, through the native IDE API. Deletion and unassignment need approval; rename needs reference review.',
+            parameters: object({
+                scope: choice('Structure kind.', ['pou', 'task']),
+                operation: choice('Operation.', ['create', 'copy', 'rename', 'delete', 'edit', 'assign', 'unassign']),
+                name: string('Existing name for edit/delete/assign, or the new name for create.'),
+                new_name: string('New name for copy or rename.'),
+                language: choice('POU language for creation.', ['ST', 'IL', 'FBD', 'LD']),
+                pou_type: choice('POU type for creation.', ['PROGRAM', 'FUNCTION_BLOCK', 'FUNCTION']),
+                return_type: string('Function return type.'),
+                kind: choice('Task kind for creation.', ['CYCLIC', 'DEFAULT', 'SYSTEM']),
+                pou: string('Program to assign to a task.'),
+                instance: string('Instance name for assign or unassign.'),
+                settings: record('Task settings to change; each value is a string.', {
+                    TYPE: string('Task type.'),
+                    INTERVAL: string('Cyclic interval, for example T#8ms.'),
+                    PRIORITY: string('Task priority.'),
+                    WATCHDOG: string('Watchdog value.'),
+                    WATCHDOG_ENABLED: string('YES or NO.'),
+                }),
+                user_approved: boolean('Approval for deletion or unassignment.'),
+                references_reviewed: boolean('Set after reviewing references for rename or delete.'),
+            }, ['scope', 'operation', 'name']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const result = await runtimeOf(workspace).editStructure({
+                    scope: args.scope,
+                    operation: args.operation,
+                    name: args.name,
+                    ...(typeof args.new_name === 'string' ? { new_name: args.new_name } : {}),
+                    ...(typeof args.language === 'string' ? { language: args.language } : {}),
+                    ...(typeof args.pou_type === 'string' ? { pou_type: args.pou_type } : {}),
+                    ...(typeof args.return_type === 'string' ? { return_type: args.return_type } : {}),
+                    ...(typeof args.kind === 'string' ? { kind: args.kind } : {}),
+                    ...(typeof args.pou === 'string' ? { pou: args.pou } : {}),
+                    ...(typeof args.instance === 'string' ? { instance: args.instance } : {}),
+                    ...(args.settings === undefined ? {} : { settings_changes: args.settings }),
+                    ...(args.user_approved === true ? { user_approved: true } : {}),
+                    ...(args.references_reviewed === true ? { references_reviewed: true } : {}),
+                });
+                const verification = result.verification;
+                const accepted = verification?.accepted === true;
+                return success(accepted ? `${String(args.operation)} verified against the saved and native structure.` : `${String(args.operation)} did not verify: ${verification?.errors?.join('; ') ?? 'unknown'}.`, result, accepted ? [{ tool: 'mw_compile', why: 'Compile after the intended changes are complete.' }] : [{ tool: 'mw_verify', why: 'Inspect the mismatch before another edit.' }], EDIT_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_insert_block',
+            description: 'Insert one FB instance declaration and its ST call into a POU through the native APIs. Bindings are pin/value pairs; outputs and in-outs need existing direct variables. Requires the exact current body hash.',
+            parameters: object({
+                pou: string('Target ST POU.'),
+                block: string('Function-block name to instantiate.'),
+                instance: string('New instance name.'),
+                bindings: list('Pin bindings; every in-out pin must be present.', objectItem('One pin binding.', {
+                    pin: string('Pin name.'),
+                    value: string('Exact expression or existing direct variable.'),
+                }, ['pin', 'value'])),
+                expected_body_sha256: string('Exact 64-character hash of the current POU body, or use expected_body.'),
+                expected_body: string('Current POU body, or use expected_body_sha256.'),
+                library: string('Library that resolves a duplicate block name.'),
+                group: string('Declaration group for the instance; defaults to Default.'),
+                before: string('Unique exact text to insert before; mutually exclusive with offset.'),
+                offset: integer('Zero-based character offset at a line boundary; defaults to append.', { minimum: 0 }),
+            }, ['pou', 'block', 'instance', 'bindings']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                if ((typeof args.expected_body_sha256 === 'string') === (typeof args.expected_body === 'string')) {
+                    throw new MwiError('INVALID_ARGUMENT', 'Supply exactly one of expected_body_sha256 or expected_body.', 'Read the POU with mw_get and pass its body or its hash.');
+                }
+                const bindings = {};
+                for (const entry of args.bindings) {
+                    if (bindings[entry.pin] !== undefined)
+                        throw new MwiError('INVALID_ARGUMENT', `Pin ${entry.pin} is bound twice.`, 'Bind each pin once.');
+                    bindings[entry.pin] = entry.value;
+                }
+                const result = await runtimeOf(workspace).insertBlock({
+                    pou: args.pou,
+                    block: args.block,
+                    instance: args.instance,
+                    bindings,
+                    ...(typeof args.expected_body_sha256 === 'string' ? { expected_body_sha256: args.expected_body_sha256 } : { expected_body: args.expected_body }),
+                    ...(typeof args.library === 'string' ? { library: args.library } : {}),
+                    ...(typeof args.group === 'string' ? { group: args.group } : {}),
+                    ...(typeof args.before === 'string' ? { before: args.before } : {}),
+                    ...(typeof args.offset === 'number' ? { offset: args.offset } : {}),
+                });
+                const verification = result.verification;
+                const accepted = verification?.accepted === true;
+                return success(accepted ? `Inserted ${String(args.instance)} and its call into ${String(args.pou)}.` : `Insertion did not verify: ${verification?.errors?.join('; ') ?? 'unknown'}.`, result, accepted ? [{ tool: 'mw_compile', why: 'Compile the inserted call.' }] : [{ tool: 'mw_verify', why: 'Inspect the partial phase evidence before another attempt.' }], EDIT_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_transfer_pou',
+            description: 'Export one writable POU to a private workspace package, or import that untouched package into this staged project. Import needs the export token and a dependency review; a token is consumed by one attempt.',
+            parameters: object({
+                operation: choice('Package operation.', ['export', 'import']),
+                pou: string('Exact POU to export.'),
+                package_token: string('Token returned by the export.'),
+                dependencies_reviewed: boolean('Set after reviewing the package externals before import.'),
+            }, ['operation']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const operation = String(args.operation);
+                if (operation === 'export' && typeof args.pou !== 'string') {
+                    throw new MwiError('INVALID_ARGUMENT', 'Export needs the exact POU name.', 'Pass pou; import takes no POU name.');
+                }
+                if (operation === 'import' && typeof args.package_token !== 'string') {
+                    throw new MwiError('INVALID_ARGUMENT', 'Import needs package_token.', 'Export first, then import with its token.');
+                }
+                const result = await runtimeOf(workspace).transferPou({
+                    operation,
+                    ...(typeof args.pou === 'string' ? { pou: args.pou } : {}),
+                    ...(typeof args.package_token === 'string' ? { package_token: args.package_token } : {}),
+                    ...(args.dependencies_reviewed === true ? { dependencies_reviewed: true } : {}),
+                });
+                const accepted = result.accepted === true;
+                return success(accepted
+                    ? operation === 'export' ? `Exported ${String(args.pou)}.` : 'Imported the POU package.'
+                    : `Package ${operation} did not verify: ${result.errors?.join('; ') ?? 'unknown'}.`, result, accepted ? [{ tool: 'mw_compile', why: 'Compile after the intended changes are complete.' }] : [{ tool: 'mw_verify', why: 'Inspect the retained package evidence.' }], EDIT_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_validate',
+            description: 'Validate the open staged project before applying: workflow blockers, native validation and an optional program review for one POU or proposed body. Read the findings before saving or compiling.',
+            parameters: object({
+                pou: string('POU to review.'),
+                body: string('Proposed replacement body to review without writing it.'),
+            }),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const result = await runtimeOf(workspace).validate({
+                    ...(typeof args.pou === 'string' ? { pou: args.pou } : {}),
+                    ...(typeof args.body === 'string' ? { body: args.body } : {}),
+                });
+                const ready = result.ready === true;
+                return success(ready ? 'Validation found no blocker.' : `Validation found ${String(result.blockers?.length ?? 0)} blocker(s) and ${String(result.validation_errors?.length ?? 0)} validation error(s).`, result, ready
+                    ? [{ tool: 'mw_apply', why: 'Save the validated staged project.' }]
+                    : [{ tool: 'mw_review', why: 'Inspect the components named by the findings.' }], EDIT_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_apply',
+            description: 'Save the open staged project through the IDE. This writes only the staged copy; promoting source back to the workspace remains a separate, explicit step.',
+            parameters: object({}),
+            async run(_args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const result = await runtimeOf(workspace).apply();
+                return success('Saved the staged project through the IDE.', result, [{ tool: 'mw_compile', why: 'Compile the saved project.' }], EDIT_COVERAGE);
+            },
+        }),
+    ];
+}

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

@@ -0,0 +1,19 @@
+/**
+ * The read row: the saved project model, code, help and review evidence.
+ *
+ * Reads describe the saved project. Anything that needs the loaded IDE instance
+ * belongs to the session or verify rows and says so in its own coverage.
+ *
+ * @module dsh-engineering-mwi/tools/read
+ */
+import { type ToolDefinition } from '../core/tool.ts';
+import { type ReadService } from '../read/service.ts';
+/** How the tools reach the read service; injectable for tests. */
+export type ReadFactory = (workspace: string) => ReadService;
+/**
+ * The read tools.
+ *
+ * @param readsOf - Read service factory; defaults to the cached workspace runtime.
+ * @returns Tool definitions in registration order.
+ */
+export declare function readTools(readsOf?: ReadFactory): readonly ToolDefinition[];

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

@@ -0,0 +1,161 @@
+/**
+ * The read row: the saved project model, code, help and review evidence.
+ *
+ * Reads describe the saved project. Anything that needs the loaded IDE instance
+ * belongs to the session or verify rows and says so in its own coverage.
+ *
+ * @module dsh-engineering-mwi/tools/read
+ */
+import { choice, integer, object, string } from "../core/params.js";
+import { success } from "../core/result.js";
+import { tool } from "../core/tool.js";
+import { defaultProject, resolveProject } from "../session/project.js";
+import { workspaceOf } from "../session/workspace.js";
+import { runtimeFor } from "../session/service.js";
+import { GET_KINDS, LIST_KINDS } from "../read/service.js";
+/** Limits shared by every saved-project read. */
+const READ_COVERAGE = {
+    complete: false,
+    unverified: [
+        'the loaded IDE instance; these reads use the saved project files',
+        'graphical LD/FBD bodies, which are listed but not read as text',
+        'runtime behavior and controller state',
+    ],
+};
+/**
+ * The read tools.
+ *
+ * @param readsOf - Read service factory; defaults to the cached workspace runtime.
+ * @returns Tool definitions in registration order.
+ */
+export function readTools(readsOf = workspace => runtimeFor(workspace).reads) {
+    const projectOf = (args, workspace) => typeof args.project === 'string' ? resolveProject(workspace, args.project) : defaultProject(workspace);
+    return [
+        tool({
+            name: 'mw_project_overview',
+            description: 'Summarize one project from its saved files: languages, POU, variable, type and task counts, readiness and validation findings. Use it before listing components.',
+            parameters: object({
+                project: string('Project directory or .mwt inside the workspace. Omit to use the single staged project.'),
+            }),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const project = projectOf(args, workspace);
+                const reads = readsOf(workspace);
+                const workflow = await reads.workflow(project);
+                const counts = {};
+                for (const kind of ['pou', 'global', 'type', 'task']) {
+                    counts[kind] = (await reads.list(project, kind, { limit: 1 })).total;
+                }
+                return success(`${project.name}: ${counts.pou} POU(s), ${counts.global} global declaration(s), ${counts.type} type(s), ${counts.task} task row(s).`, { project: project.directory, staged: project.staged, counts, workflow }, [{ tool: 'mw_list', why: 'List the components you need.' }], READ_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_list',
+            description: 'List POUs, variables, globals, types, tasks or library blocks from the saved project, with a filter and paging.',
+            parameters: object({
+                kind: choice('What to list.', LIST_KINDS),
+                project: string('Project directory or .mwt inside the workspace. Omit to use the single staged project.'),
+                pou: string('POU whose declarations to list; required for kind variable.'),
+                filter: string('Case-insensitive substring over the returned fields.'),
+                offset: integer('Rows to skip. Defaults to 0.', { minimum: 0 }),
+                limit: integer('Most rows. Defaults to 50, maximum 200.', { minimum: 1, maximum: 200 }),
+            }, ['kind']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const project = projectOf(args, workspace);
+                const kind = String(args.kind);
+                const listed = await readsOf(workspace).list(project, kind, {
+                    filter: typeof args.filter === 'string' ? args.filter : undefined,
+                    offset: typeof args.offset === 'number' ? args.offset : 0,
+                    limit: typeof args.limit === 'number' ? args.limit : 50,
+                    pou: typeof args.pou === 'string' ? args.pou : undefined,
+                });
+                return success(`${listed.total} ${kind}(s) in ${project.name}; showing ${listed.rows.length}.`, { project: project.directory, kind, total: listed.total, rows: listed.rows }, [{ tool: 'mw_get', why: 'Read one row in full.' }], READ_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_get',
+            description: 'Read one POU with its declarations, one type, one task row, one block interface or the EtherNet/IP assembly map.',
+            parameters: object({
+                kind: choice('What to read.', GET_KINDS),
+                name: string('Exact component name; omit only for kind eip.'),
+                project: string('Project directory or .mwt inside the workspace. Omit to use the single staged project.'),
+                library: string('Library name for a block interface.'),
+            }, ['kind']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const project = projectOf(args, workspace);
+                const kind = String(args.kind);
+                const name = typeof args.name === 'string' ? args.name : '';
+                const document = await readsOf(workspace).get(project, kind, name, typeof args.library === 'string' ? args.library : undefined);
+                return success(kind === 'eip' ? `Read the EtherNet/IP assembly map of ${project.name}.` : `Read ${kind} ${name} from ${project.name}.`, { project: project.directory, kind, document }, [{ tool: 'mw_list', why: 'Continue with the components around this one.' }], READ_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_search',
+            description: 'Find literal text across the saved POU bodies, case-insensitively, with the POU and line of each match.',
+            parameters: object({
+                query: string('Literal text to find.'),
+                project: string('Project directory or .mwt inside the workspace. Omit to use the single staged project.'),
+                limit: integer('Most matches. Defaults to 50, maximum 200.', { minimum: 1, maximum: 200 }),
+            }, ['query']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const project = projectOf(args, workspace);
+                const result = await readsOf(workspace).search(project, String(args.query), typeof args.limit === 'number' ? args.limit : 50);
+                return success(`${result.matches.length} match(es) across ${result.scanned} text POU(s).`, { project: project.directory, ...result }, [{ tool: 'mw_get', why: 'Read the POU that contains the match.', args: { kind: 'pou', name: result.matches[0]?.pou } }], READ_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_references',
+            description: 'Find where one symbol appears across the saved POU bodies, with the POU and line. Static evidence only.',
+            parameters: object({
+                symbol: string('Declared or written symbol name.'),
+                project: string('Project directory or .mwt inside the workspace. Omit to use the single staged project.'),
+                limit: integer('Most matches. Defaults to 50, maximum 200.', { minimum: 1, maximum: 200 }),
+            }, ['symbol']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const project = projectOf(args, workspace);
+                const result = await readsOf(workspace).references(project, String(args.symbol), typeof args.limit === 'number' ? args.limit : 50);
+                return success(`${result.matches.length} reference(s) across ${result.scanned} text POU(s).`, { project: project.directory, symbol: args.symbol, ...result }, [{ tool: 'mw_get', why: 'Read the enclosing POU.', args: { kind: 'pou', name: result.matches[0]?.pou } }], READ_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'mw_review',
+            description: 'Run the static review: workflow readiness, native validation, unsupported constructs, and optionally a program review for one POU or proposed body.',
+            parameters: object({
+                project: string('Project directory or .mwt inside the workspace. Omit to use the single staged project.'),
+                pou: string('POU to review.'),
+                body: string('Proposed replacement body to review without writing it.'),
+            }),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const project = projectOf(args, workspace);
+                const review = await readsOf(workspace).review(project, {
+                    ...(typeof args.pou === 'string' ? { pou: args.pou } : {}),
+                    ...(typeof args.body === 'string' ? { body: args.body } : {}),
+                });
+                const workflow = review.workflow;
+                return success(`Reviewed ${project.name}${typeof args.pou === 'string' ? ` (${args.pou})` : ''}; ${workflow?.blockers?.length ?? 0} blocker(s).`, { project: project.directory, ...review }, [{ tool: 'mw_list', why: 'Inspect the components named by a finding.' }], { complete: false, unverified: ['review is static; it does not prove runtime behavior', 'vendor XSD or compiler equivalence'] });
+            },
+        }),
+        tool({
+            name: 'mw_help',
+            description: 'Search installed MotionWorks help, the installed manuals, reviewed Yaskawa references or the versioned ST patterns.',
+            parameters: object({
+                source: choice('Where to search.', ['help', 'manual', 'reference', 'pattern']),
+                query: string('Search term or pattern name; omit to list what is available.'),
+                limit: integer('Most rows. Defaults to 10, maximum 50.', { minimum: 1, maximum: 50 }),
+                project: string('Project directory or .mwt inside the workspace. Omit to use the single staged project.'),
+            }, ['source']),
+            async run(args, exec) {
+                const workspace = workspaceOf(exec.cwd);
+                const project = projectOf(args, workspace);
+                const source = String(args.source);
+                const document = await readsOf(workspace).help(project, source, typeof args.query === 'string' ? args.query : undefined, typeof args.limit === 'number' ? args.limit : 10);
+                return success(`Searched ${source} for ${typeof args.query === 'string' ? args.query : 'available topics'}.`, { project: project.directory, source, document }, [], READ_COVERAGE);
+            },
+        }),
+    ];
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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 { 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 RuntimeFactory = (workspace: string) => SessionRuntime;
+/**
+ * The session tools.
+ *
+ * @param runtimeOf - Workspace runtime factory; defaults to the PowerShell bridge.
+ * @returns Tool definitions in registration order.
+ */
+export declare function sessionTools(runtimeOf?: RuntimeFactory): readonly ToolDefinition[];