@aryacode/dsh-engineering 0.4.6 → 0.4.20

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

@@ -24,6 +24,7 @@ import { CodeEngine } from "../core/code-engine.js";
 import { MwiError } from "../core/errors.js";
 import { PowerShellBridgeTransport } from "../core/ps-bridge.js";
 import { StageService } from "./stage.js";
+import { ensureBackup, findBackup, listBackups } from "./backup.js";
 import { compareVariables } from "../edit/compare.js";
 import { ReadService } from "../read/service.js";
 import { stageRootOf, workspaceOf, isInside } from "./workspace.js";
@@ -33,6 +34,25 @@ export const BRIDGE_DIR = fileURLToPath(new URL('../../bridge/', import.meta.url
 export const CODE_DIR = fileURLToPath(new URL('../../code/', import.meta.url));
 /** Vendored proven mutation helpers. */
 export const LEGACY_DIR = fileURLToPath(new URL('../../legacy/', import.meta.url));
+/** A stage-shaped view of a real, backed-up project. */
+function directRecord(backup) {
+    return {
+        name: backup.name,
+        source: backup.mwt,
+        source_directory: backup.directory,
+        workspace: backup.workspace,
+        staged_mwt: backup.mwt,
+        staged_directory: backup.directory,
+        bound_to: backup.directory,
+        previous_embedded_path: null,
+        staged_at: backup.created_at,
+    };
+}
+/** Whether two paths name the same project, with or without the `.mwt` suffix. */
+function sameProject(left, right) {
+    const bare = (path) => resolve(path).toLowerCase().replace(/\.mwt$/u, '');
+    return bare(left) === bare(right);
+}
 /** Hash every file in a native package, refusing links and oversized trees. */
 function nativePackageManifest(directory, workspace) {
     const files = [];
@@ -92,6 +112,19 @@ export class PowerShellSessionRuntime {
     async ideState() {
         return await this.bridge.run('ide_state', { include_window_state: true });
     }
+    /** @returns The open project path, or undefined when no IDE or no project is open. */
+    async activeProject() {
+        let status;
+        try {
+            status = await this.status();
+        }
+        catch (error) {
+            if (error instanceof MwiError && error.code === 'IDE_NOT_RUNNING')
+                return undefined;
+            throw error;
+        }
+        return status.is_project_open === true && typeof status.active_project === 'string' ? status.active_project : undefined;
+    }
     /** @returns The written stage record. */
     async stage(source, options = {}) {
         return await this.stages.stage(source, {
@@ -116,11 +149,40 @@ export class PowerShellSessionRuntime {
             },
         });
     }
+    /** @returns The verified pre-edit backup record. */
+    attach(path) {
+        return ensureBackup(this.workspace, path);
+    }
     /** @returns The bridge's open result. */
     async open(path, options) {
-        const resolved = resolve(path);
-        if (!isInside(stageRootOf(this.workspace), resolved) || !existsSync(resolved)) {
-            throw new MwiError('NOT_STAGED', `${resolved} is not a staged project.`, 'Stage the workspace project with mw_project_stage, then open the staged .mwt.');
+        const resolved = resolve(this.workspace, path);
+        if (!isInside(stageRootOf(this.workspace), resolved)) {
+            const record = this.attach(resolved);
+            // An already-open project is attached, not reopened: OpenProject reloads the
+            // files, and a reload over unsaved editor changes is data loss the backup
+            // cannot undo. The verified identity is the whole job in that case.
+            const active = await this.activeProject();
+            if (active !== undefined && sameProject(active, record.mwt)) {
+                return {
+                    requested: record.mwt,
+                    is_project_open: true,
+                    active_project: active,
+                    matches_request: true,
+                    already_open: true,
+                    backup: record.backup,
+                    backup_manifest: record.manifest,
+                };
+            }
+            const binding = await this.engine.run('check_mwt', { project: record.mwt });
+            return await this.bridge.run('open', {
+                path: record.mwt,
+                wrapper_sha256: binding.wrapper_sha256,
+                user_approved: options.userApproved === true,
+                ...(options.expectedProject === undefined ? {} : { expected_project: options.expectedProject }),
+            });
+        }
+        if (!existsSync(resolved)) {
+            throw new MwiError('NOT_STAGED', `${resolved} is not a staged project.`, 'Pass a workspace .mwt, or stage the workspace project with mw_project_stage.');
         }
         const name = resolved.replace(/\\/gu, '/').split('/').pop()?.replace(/\.mwt$/iu, '') ?? '';
         if (this.stages.identityOf(name) === undefined) {
@@ -136,11 +198,11 @@ export class PowerShellSessionRuntime {
     }
     /** @returns The bridge's start result. */
     async start(project) {
-        const staged = project === undefined ? this.singleStage() : this.stageMwt(project);
-        const binding = await this.engine.run('check_mwt', { project: staged });
+        const target = project === undefined ? this.singleStage() : this.projectMwt(project);
+        const binding = await this.engine.run('check_mwt', { project: target });
         return await this.bridge.run('start_ide', {
             include_trial_method: true,
-            path: staged,
+            path: target,
             wrapper_sha256: binding.wrapper_sha256,
         });
     }
@@ -150,9 +212,9 @@ export class PowerShellSessionRuntime {
         if (status.is_project_open !== true || typeof status.active_project !== 'string') {
             throw new MwiError('NO_PROJECT', 'No project is open in the IDE.', 'Open a staged project first with mw_project_open.');
         }
-        const record = this.stages.stagedAt(status.active_project);
+        const record = this.stagedAt(status.active_project);
         if (record === undefined) {
-            throw new MwiError('NOT_STAGED', `The open project is not a proven stage: ${status.active_project}.`, 'Open a staged project before navigating worksheets.');
+            throw new MwiError('NOT_ATTACHED', `The open project is not proven: ${status.active_project}.`, 'Open the workspace project with mw_project_open first.');
         }
         const target = await this.engine.run('worksheet_target', {
             project: record.staged_directory,
@@ -175,9 +237,13 @@ export class PowerShellSessionRuntime {
             ...(options.expectedProject === undefined ? {} : { expected_project: options.expectedProject }),
         });
     }
-    /** @returns The stage record for a path. */
+    /** @returns The stage record for a path, when it is staged or directly backed up. */
     stagedAt(path) {
-        return this.stages.stagedAt(path);
+        const staged = this.stages.stagedAt(path);
+        if (staged !== undefined)
+            return staged;
+        const backup = findBackup(this.workspace, path);
+        return backup === undefined ? undefined : directRecord(backup);
     }
     /** @returns The bridge's compile result. */
     async compile(mode) {
@@ -466,10 +532,20 @@ export class PowerShellSessionRuntime {
         mkdirSync(evidenceDirectory, { recursive: true });
         const evidence = join(evidenceDirectory, `native-code-${randomUUID()}.json`);
         const args = { project, pou: input.pou, baseline_saved: true };
+        let expectedHash = input.expectedHash;
+        if (input.changes !== undefined && expectedHash === undefined) {
+            // The hash guards the exact find/replace against a stale body. The caller no
+            // longer has to carry it: hash the body this edit is about to patch.
+            const read = await this.engine.run('read_text', { project, pou: input.pou });
+            if (typeof read.body !== 'string' || read.body.length === 0) {
+                throw new MwiError('EDIT_REFUSED', `Cannot read ${input.pou} to hash it: ${String(read.body_error ?? 'empty body')}.`, 'Read the POU with mw_get, then retry the edit.');
+            }
+            expectedHash = createHash('sha256').update(read.body).digest('hex');
+        }
         if (input.changes !== undefined) {
             args.changes = input.changes;
-            if (input.expectedHash !== undefined)
-                args.expected_body_sha256 = input.expectedHash;
+            if (expectedHash !== undefined)
+                args.expected_body_sha256 = expectedHash;
         }
         else {
             args.code = input.body;
@@ -506,42 +582,57 @@ export class PowerShellSessionRuntime {
             throw new MwiError('EDIT_REFUSED', `${error.message}; evidence at ${evidence}`, 'Read the refusal, correct the request, and retry. Do not repeat an unverified edit.');
         }
     }
-    /** The open project must be a proven stage; every compile and verify depends on it. */
+    /** The open project must be a proven stage or a verified direct backup; every compile and verify depends on it. */
     async openStagedRecord() {
-        const status = await this.status();
-        if (status.is_project_open !== true || typeof status.active_project !== 'string') {
-            throw new MwiError('NO_PROJECT', 'No project is open in the IDE.', 'Open a staged project with mw_project_open before compiling.');
-        }
-        const record = this.stages.stagedAt(status.active_project);
-        if (record === undefined) {
-            throw new MwiError('NOT_STAGED', `The open project is not a proven stage: ${status.active_project}.`, 'Open a staged project; the verify row never compiles a workspace original.');
-        }
-        return record;
+        const active = await this.activeProject();
+        if (active === undefined) {
+            throw new MwiError('NO_PROJECT', 'No project is open in the IDE.', 'Open a project with mw_project_open before compiling.');
+        }
+        const record = this.stagedAt(active);
+        if (record !== undefined)
+            return record;
+        // The IDE already has a workspace project open that this bundle did not open.
+        // Take the verified backup now rather than refuse: the edit still needs the
+        // same rollback evidence, and the guarded edit itself still refuses an
+        // unsaved project before it writes.
+        if (!isInside(this.workspace, active) || isInside(join(this.workspace, '.motionworks'), active)) {
+            throw new MwiError('NOT_ATTACHED', `The open project has no proven backup: ${active}.`, 'Open a workspace project with mw_project_open so a verified backup is taken first.');
+        }
+        return directRecord(this.attach(active));
     }
-    /** The only staged project, or a refusal that explains the choice. */
+    /** The only openable project, staged or backed up, or a refusal that explains the choice. */
     singleStage() {
-        let names = [];
+        const stages = [];
         try {
-            names = readdirSync(stageRootOf(this.workspace)).filter(name => name.toLowerCase().endsWith('.mwt'));
+            for (const name of readdirSync(stageRootOf(this.workspace))) {
+                if (name.toLowerCase().endsWith('.mwt'))
+                    stages.push(join(stageRootOf(this.workspace), name));
+            }
         }
         catch {
-            names = [];
+            // No stage directory.
+        }
+        const attached = listBackups(this.workspace).map(record => record.mwt);
+        // Direct editing is the default: a proven backup wins over a stale stage copy.
+        const candidates = attached.length > 0 ? attached : stages;
+        if (candidates.length === 0) {
+            throw new MwiError('NO_PROJECT', 'No project is staged or backed up in this workspace.', 'Call mw_project_find, then mw_project_open with the workspace .mwt.');
         }
-        if (names.length === 0)
-            throw new MwiError('NO_STAGE', 'No project is staged in this workspace.', 'Call mw_project_find, then mw_project_stage.');
-        if (names.length > 1) {
-            throw new MwiError('AMBIGUOUS_STAGE', `${names.length} projects are staged.`, 'Pass project: the staged .mwt to start.', names);
+        if (candidates.length > 1) {
+            throw new MwiError('AMBIGUOUS_PROJECT', `${candidates.length} projects are openable.`, 'Pass project: the exact .mwt to start.', candidates);
         }
-        return join(stageRootOf(this.workspace), names[0]);
+        return candidates[0];
     }
-    /** Resolve a requested staged project. */
-    stageMwt(project) {
+    /** Resolve a requested project, taking a backup for a real workspace project. */
+    projectMwt(project) {
         const resolved = resolve(this.workspace, project);
         const mwt = resolved.toLowerCase().endsWith('.mwt') ? resolved : `${resolved}.mwt`;
-        if (!isInside(stageRootOf(this.workspace), mwt) || !existsSync(mwt)) {
-            throw new MwiError('NOT_STAGED', `${mwt} is not a staged project.`, 'Stage the workspace project first, then pass the staged .mwt.');
+        if (isInside(stageRootOf(this.workspace), mwt)) {
+            if (!existsSync(mwt))
+                throw new MwiError('NOT_STAGED', `${mwt} is not a staged project.`, 'Stage the workspace project first, or open the workspace .mwt directly.');
+            return mwt;
         }
-        return mwt;
+        return ensureBackup(this.workspace, mwt).mwt;
     }
 }
 const runtimes = new Map();

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

@@ -6,6 +6,16 @@
  *
  * @module dsh-engineering-mwi/session/workspace
  */
+/**
+ * Set the workspace root from the product row's config.
+ *
+ * The host does not always pass the session cwd to tool calls (it is undefined
+ * in the current desktop build), so the row carries the workspace explicitly.
+ * An empty string clears it and falls back to the marker / process directory.
+ *
+ * @param root - Absolute workspace root, or an empty string.
+ */
+export declare function configureWorkspace(root: string | undefined): void;
 /** One MotionWorks project found in the workspace. */
 export interface FoundProject {
     /** Project name: the `.mwt` basename. */

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

@@ -6,10 +6,38 @@
  *
  * @module dsh-engineering-mwi/session/workspace
  */
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 /** Directories never scanned for projects. */
 const SKIP = new Set(['node_modules', '.git', 'stage', 'backups', '_backups', '__pycache__', 'chm_out', 'help_extract', '.dsh']);
+/** Workspace root set from the row's config, when one is configured. */
+let configured;
+/**
+ * Set the workspace root from the product row's config.
+ *
+ * The host does not always pass the session cwd to tool calls (it is undefined
+ * in the current desktop build), so the row carries the workspace explicitly.
+ * An empty string clears it and falls back to the marker / process directory.
+ *
+ * @param root - Absolute workspace root, or an empty string.
+ */
+export function configureWorkspace(root) {
+    const value = typeof root === 'string' ? root.trim() : '';
+    configured = value === '' ? undefined : resolve(value);
+}
+/** Read the documented `mwi.workspace` marker from the profile directory. */
+function recordedWorkspace() {
+    try {
+        const marker = join(process.env.DSH_PROFILE_DIR ?? '', 'mwi.workspace');
+        if (!existsSync(marker))
+            return undefined;
+        const recorded = readFileSync(marker, 'utf8').replace(/^\uFEFF/u, '').trim();
+        return recorded === '' ? undefined : resolve(recorded);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Resolve the caller's workspace.
  *
@@ -17,7 +45,9 @@ const SKIP = new Set(['node_modules', '.git', 'stage', 'backups', '_backups', '_
  * @returns The absolute workspace root.
  */
 export function workspaceOf(cwd) {
-    return resolve(cwd ?? process.cwd());
+    if (typeof cwd === 'string' && cwd.trim() !== '')
+        return resolve(cwd);
+    return configured ?? recordedWorkspace() ?? resolve(process.cwd());
 }
 /**
  * The stage root of one workspace.
@@ -52,9 +82,20 @@ export function findProjects(workspace, options = {}) {
     const filter = options.filter?.toLowerCase();
     const stage = stageRootOf(workspace);
     const found = [];
+    const seen = new Set();
     const walk = (directory, depth) => {
         if (found.length >= limit || depth > 6)
             return;
+        let real;
+        try {
+            real = realpathSync(directory);
+        }
+        catch {
+            return;
+        }
+        if (seen.has(real))
+            return;
+        seen.add(real);
         let entries;
         try {
             entries = readdirSync(directory, { withFileTypes: true });
@@ -66,7 +107,16 @@ export function findProjects(workspace, options = {}) {
             if (found.length >= limit)
                 return;
             const absolute = join(directory, entry.name);
-            if (entry.isDirectory()) {
+            let isDirectory = entry.isDirectory();
+            if (!isDirectory && entry.isSymbolicLink()) {
+                try {
+                    isDirectory = statSync(absolute).isDirectory();
+                }
+                catch {
+                    isDirectory = false;
+                }
+            }
+            if (isDirectory) {
                 if (SKIP.has(entry.name) || isInside(stage, absolute))
                     continue;
                 walk(absolute, depth + 1);

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

@@ -22,8 +22,8 @@ export interface SkillContext {
 /** Registration metadata, kept here so a test can assert it without the file. */
 export declare const SKILL: {
     readonly name: "motionworks-iec";
-    readonly description: "Operate a running Yaskawa MotionWorks IEC 3 Pro IDE through staged projects — find and stage a workspace project, read the live object model and POU code, edit declarations and code, compile, read diagnostics, and verify a staged change.";
-    readonly whenToUse: "The user has MotionWorks IEC 3 Pro open or asks for work in it — a build or compile verdict, the live project model, reading or changing POU code, variable declarations, tasks, or the IDE error list. Also use when a MotionWorks project is mentioned: find which project is in the workspace before answering. For a question about a project outside the workspace, say it cannot be staged.";
+    readonly description: "Operate a running Yaskawa MotionWorks IEC 3 Pro IDE on the real project files — find and open a workspace project (one verified backup first), read the live object model and POU code, edit declarations and code, compile, read diagnostics, and verify the change.";
+    readonly whenToUse: "The user has MotionWorks IEC 3 Pro open or asks for work in it — a build or compile verdict, the live project model, reading or changing POU code, variable declarations, tasks, or the IDE error list. Also use when a MotionWorks project is mentioned: find which project is in the workspace before answering. For a question about a project outside the workspace, say it cannot be opened.";
 };
 /**
  * Register the MotionWorks IEC skill.

package/vendor/mwi/lib/skill.js

@@ -17,8 +17,8 @@ export const inject = ['skills'];
 /** Registration metadata, kept here so a test can assert it without the file. */
 export const SKILL = {
     name: 'motionworks-iec',
-    description: 'Operate a running Yaskawa MotionWorks IEC 3 Pro IDE through staged projects — find and stage a workspace project, read the live object model and POU code, edit declarations and code, compile, read diagnostics, and verify a staged change.',
-    whenToUse: 'The user has MotionWorks IEC 3 Pro open or asks for work in it — a build or compile verdict, the live project model, reading or changing POU code, variable declarations, tasks, or the IDE error list. Also use when a MotionWorks project is mentioned: find which project is in the workspace before answering. For a question about a project outside the workspace, say it cannot be staged.',
+    description: 'Operate a running Yaskawa MotionWorks IEC 3 Pro IDE on the real project files — find and open a workspace project (one verified backup first), read the live object model and POU code, edit declarations and code, compile, read diagnostics, and verify the change.',
+    whenToUse: 'The user has MotionWorks IEC 3 Pro open or asks for work in it — a build or compile verdict, the live project model, reading or changing POU code, variable declarations, tasks, or the IDE error list. Also use when a MotionWorks project is mentioned: find which project is in the workspace before answering. For a question about a project outside the workspace, say it cannot be opened.',
 };
 /**
  * Register the MotionWorks IEC skill.

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

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * Editing is on by default; a read-only profile can switch it off. Every tool writes the open project (the real files
+ * for a workspace project, with a verified backup already taken) and the proven
+ * native helpers verify that unrelated saved and native state did not change.
  *
  * @module dsh-engineering-mwi/tools/edit
  */

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

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * Editing is on by default; a read-only profile can switch it off. Every tool writes the open project (the real files
+ * for a workspace project, with a verified backup already taken) and the proven
+ * native helpers verify that unrelated saved and native state did not change.
  *
  * @module dsh-engineering-mwi/tools/edit
  */
@@ -32,7 +32,7 @@ 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.',
+            description: 'Replace one ST or IL body in the open 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.', {
@@ -51,17 +51,16 @@ export function editTools(runtimeOf = runtimeFor) {
                 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.');
+                    throw new MwiError('INVALID_ARGUMENT', 'Supply either changes, or body with expected_body.', 'Use changes for a small exact patch, or body for a full replacement; do not mix them.');
                 }
                 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) }),
+                    ...(hasChanges
+                        ? { changes, ...(typeof args.expected_body_sha256 === 'string' ? { expectedHash: args.expected_body_sha256 } : {}) }
+                        : { body: String(args.body), expectedBody: String(args.expected_body) }),
                 });
                 const verification = result.verification;
                 const accepted = verification?.accepted === true;
@@ -72,7 +71,7 @@ export function editTools(runtimeOf = runtimeFor) {
         }),
         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.',
+            description: 'Add, edit or delete one declaration in the open 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.'),
@@ -225,7 +224,7 @@ export function editTools(runtimeOf = runtimeFor) {
         }),
         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.',
+            description: 'Export one writable POU to a private workspace package, or import that untouched package into this 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.'),
@@ -255,7 +254,7 @@ export function editTools(runtimeOf = runtimeFor) {
         }),
         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.',
+            description: 'Validate the open 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.'),
@@ -268,18 +267,18 @@ export function editTools(runtimeOf = runtimeFor) {
                 });
                 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_apply', why: 'Save the validated 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.',
+            description: 'Save the open project through the IDE. A workspace project is written in place; its verified pre-edit backup stays under <workspace>/backups/.',
             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);
+                return success('Saved the open project through the IDE.', result, [{ tool: 'mw_compile', why: 'Compile the saved project.' }], EDIT_COVERAGE);
             },
         }),
     ];

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

@@ -75,7 +75,7 @@ export function readTools(readsOf = workspace => runtimeFor(workspace).reads) {
         }),
         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.',
+            description: 'Read one POU with its declarations and the text_body_sha256 that the edit preconditions take, 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.'),

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

@@ -12,6 +12,7 @@ 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 { listBackups } from "../session/backup.js";
 import { runtimeFor } from "../session/service.js";
 /** What every IDE answer cannot establish. */
 const IDE_COVERAGE = {
@@ -43,7 +44,7 @@ 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.',
+            description: 'Find MotionWorks IEC projects inside the calling workspace. Returns each .mwt, its expanded directory, whether a staged copy exists and whether a pre-edit backup exists. Call this before 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 }),
@@ -55,11 +56,12 @@ export function sessionTools(runtimeOf = runtimeFor) {
                     limit: typeof args.limit === 'number' ? args.limit : 20,
                 });
                 const staged = projects.filter(project => project.staged !== null).length;
+                const backups = listBackups(workspace);
                 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
+                    : `Found ${projects.length} MotionWorks project(s) in ${workspace}; ${staged} staged, ${backups.length} with a pre-edit backup.`, { workspace, stage_root: stageRootOf(workspace), backups, 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: 'mw_project_open', why: 'Open the workspace project; a verified backup is taken first.', args: { path: projects[0]?.mwt } }], { complete: false, unverified: ['projects outside the workspace are never listed or staged'] });
             },
         }),
         tool({
@@ -85,7 +87,7 @@ export function sessionTools(runtimeOf = runtimeFor) {
         }),
         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.',
+            description: 'Optional sandbox: copy one workspace project into .motionworks/stage so the IDE opens a copy instead of the real files. Normal editing opens the workspace project directly.',
             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/.'),
@@ -98,9 +100,9 @@ export function sessionTools(runtimeOf = runtimeFor) {
         }),
         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.',
+            description: 'Open a workspace project directly, or a staged copy. A direct open first writes and verifies one complete backup under <workspace>/.motionworks/attached/, and a project the IDE already has open is attached without being reloaded. Refuses to replace another open project without the exact approved path.',
             parameters: object({
-                path: string('Staged .mwt path returned by mw_project_stage.'),
+                path: string('Workspace .mwt (edits the real project, backup taken first) or a staged .mwt from 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']),
@@ -112,14 +114,16 @@ export function sessionTools(runtimeOf = runtimeFor) {
                 });
                 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);
+                    : opened.already_open === true
+                        ? `Already open; verified the pre-edit backup for ${String(opened.active_project ?? args.path)}.`
+                        : `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.',
+            description: 'Start MotionWorks IEC with one workspace project (backup first) or a staged copy, or attach to the IDE that is already running. Refuses when several projects are openable without a project argument.',
             parameters: object({
-                project: string('Staged .mwt to start with. Omit when exactly one project is staged.'),
+                project: string('Workspace or staged .mwt to start with. Omit when exactly one project is openable.'),
             }),
             async run(args, exec) {
                 const workspace = workspaceOf(exec.cwd);