@aryacode/dsh-engineering 0.4.6 → 0.4.20

package/vendor/mwi/lib/core/code-engine.d.ts

@@ -8,6 +8,7 @@
  *
  * @module dsh-engineering-mwi/core/code-engine
  */
+import { MwiError } from './errors.ts';
 /** Where the engine lives and which workspace it serves. */
 export interface CodeEngineOptions {
     /** Absolute workspace root. */
@@ -23,6 +24,18 @@ export interface CodeEngineOptions {
 export type EngineResult = Readonly<Record<string, unknown>>;
 /** Resolve the first usable Python 3 interpreter. */
 export declare function findPython(): string;
+/**
+ * Translate one engine refusal into the failure the caller should act on.
+ *
+ * The engine guard is shared with the retired staging flow, so its refusal says
+ * "stage a copy". In this bundle a real workspace project is opened directly, and
+ * the identity record that an open writes is exactly what the guard accepts: point
+ * at the open instead of letting the caller loop back into staging.
+ *
+ * @param message - The refusal text the engine wrote.
+ * @returns The error to throw.
+ */
+export declare function engineFailure(message: string): MwiError;
 /** The typed engine client. */
 export declare class CodeEngine {
     private readonly options;

package/vendor/mwi/lib/core/code-engine.js

@@ -28,6 +28,23 @@ export function findPython() {
     }
     return 'python';
 }
+/**
+ * Translate one engine refusal into the failure the caller should act on.
+ *
+ * The engine guard is shared with the retired staging flow, so its refusal says
+ * "stage a copy". In this bundle a real workspace project is opened directly, and
+ * the identity record that an open writes is exactly what the guard accepts: point
+ * at the open instead of letting the caller loop back into staging.
+ *
+ * @param message - The refusal text the engine wrote.
+ * @returns The error to throw.
+ */
+export function engineFailure(message) {
+    if (/outside the staging root/iu.test(message)) {
+        return new MwiError('NOT_ATTACHED', message, 'Call mw_project_open with this project first: it writes the verified attachment record the engine guard requires. mw_project_stage is only an optional sandbox.');
+    }
+    return new MwiError('ENGINE_REFUSED', message, 'Read the message, correct the request, and retry. Do not retry the same invalid request.');
+}
 /** The typed engine client. */
 export class CodeEngine {
     options;
@@ -83,7 +100,7 @@ export class CodeEngine {
                 if (existsSync(responsePath)) {
                     const payload = await this.readResponse(responsePath);
                     if (payload.ok === false) {
-                        throw new MwiError('ENGINE_REFUSED', typeof payload.error === 'string' ? payload.error : `The MotionWorks engine refused ${verb}.`, 'Read the message, correct the request, and retry. Do not retry the same invalid request.');
+                        throw engineFailure(typeof payload.error === 'string' ? payload.error : `The MotionWorks engine refused ${verb}.`);
                     }
                     return payload;
                 }

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

@@ -1,7 +1,7 @@
 /**
  * The `mwi-edit` entry: staged edits, validation and apply.
  *
- * Off by default. The row writes only the staged project and verifies that
+ * On by default; a read-only profile can switch it off. The row writes only the staged project and verifies that
  * unrelated saved and native state did not change.
  *
  * @module dsh-engineering-mwi/edit

package/vendor/mwi/lib/edit.js

@@ -1,7 +1,7 @@
 /**
  * The `mwi-edit` entry: staged edits, validation and apply.
  *
- * Off by default. The row writes only the staged project and verifies that
+ * On by default; a read-only profile can switch it off. The row writes only the staged project and verifies that
  * unrelated saved and native state did not change.
  *
  * @module dsh-engineering-mwi/edit

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

@@ -6,6 +6,7 @@
  *
  * @module dsh-engineering-mwi/read/service
  */
+import { createHash } from 'node:crypto';
 import { MwiError } from "../core/errors.js";
 /** Kinds `mw_list` can enumerate. */
 export const LIST_KINDS = ['pou', 'variable', 'global', 'type', 'task', 'library'];
@@ -52,7 +53,13 @@ export class ReadService {
     async get(project, kind, name, library) {
         if (kind === 'pou') {
             const text = await this.engine.run('read_text', { project: project.directory, pou: name }, 60_000);
-            return { ...text, project: project.directory };
+            // The edit preconditions take the hash of exactly this body. Computing it
+            // here is what makes the documented `expected_body_sha256` obtainable from
+            // this read at all: the engine returns the body, not its digest, and a
+            // caller that has to find the hash elsewhere is a caller that guesses.
+            const body = typeof text.body === 'string' ? text.body : undefined;
+            const digest = body === undefined ? {} : { text_body_sha256: createHash('sha256').update(body).digest('hex') };
+            return { ...text, project: project.directory, ...digest };
         }
         if (kind === 'block') {
             return await this.engine.run('block_interface', {

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

@@ -0,0 +1,55 @@
+/**
+ * Pre-edit backups shared by the automation surfaces.
+ *
+ * Editing happens on the real workspace project. The first write takes one
+ * complete, hash-verified copy under
+ * `<workspace>/.motionworks/attached/backups/<id>`, writes a manifest beside it
+ * and records the project identity in `<workspace>/.motionworks/attached/records`.
+ *
+ * That layout is the contract the shipped bridge (`Get-DirectIdentity`) and the
+ * read-only engine (`assert_direct_attached`) already verify before they open,
+ * read or write a real project. A copy anywhere else is not evidence: those
+ * guards refuse the open, so the tools must write exactly this shape.
+ *
+ * @module dsh-engineering-mwi/session/backup
+ */
+/** One file in a backup manifest. */
+export interface BackupFile {
+    /** Path relative to the project's parent directory. */
+    readonly path: string;
+    /** SHA-256 of the copied bytes. */
+    readonly sha256: string;
+}
+/** One verified pre-edit backup. */
+export interface BackupRecord {
+    /** Project name, the `.mwt` basename. */
+    readonly name: string;
+    /** Workspace that owns the backup. */
+    readonly workspace: string;
+    /** The real `.mwt` the backup was taken from. */
+    readonly mwt: string;
+    /** The real expanded directory. */
+    readonly directory: string;
+    /** Directory holding the copy. */
+    readonly backup: string;
+    /** Manifest path inside the backup directory. */
+    readonly manifest: string;
+    /** When the copy was written. */
+    readonly created_at: string;
+}
+/** The shared backup root of one workspace. */
+export declare function backupRootOf(workspace: string): string;
+/** The identity record directory of one workspace. */
+export declare function recordRootOf(workspace: string): string;
+/** Read the record for a project, when a valid backup exists. */
+export declare function findBackup(workspace: string, path: string): BackupRecord | undefined;
+/** Every project with a valid backup in this workspace, one row per project. */
+export declare function listBackups(workspace: string): BackupRecord[];
+/**
+ * Back up one real project, or return the valid backup already recorded.
+ *
+ * @param workspace - Absolute workspace root.
+ * @param path - Real `.mwt` or its expanded directory.
+ * @returns The verified backup record.
+ */
+export declare function ensureBackup(workspace: string, path: string): BackupRecord;

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

@@ -0,0 +1,232 @@
+/**
+ * Pre-edit backups shared by the automation surfaces.
+ *
+ * Editing happens on the real workspace project. The first write takes one
+ * complete, hash-verified copy under
+ * `<workspace>/.motionworks/attached/backups/<id>`, writes a manifest beside it
+ * and records the project identity in `<workspace>/.motionworks/attached/records`.
+ *
+ * That layout is the contract the shipped bridge (`Get-DirectIdentity`) and the
+ * read-only engine (`assert_direct_attached`) already verify before they open,
+ * read or write a real project. A copy anywhere else is not evidence: those
+ * guards refuse the open, so the tools must write exactly this shape.
+ *
+ * @module dsh-engineering-mwi/session/backup
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { MwiError } from "../core/errors.js";
+import { isInside } from "./workspace.js";
+/** The shared backup root of one workspace. */
+export function backupRootOf(workspace) {
+    return join(workspace, '.motionworks', 'attached', 'backups');
+}
+/** The identity record directory of one workspace. */
+export function recordRootOf(workspace) {
+    return join(workspace, '.motionworks', 'attached', 'records');
+}
+function digest(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+function same(left, right) {
+    return resolve(left).toLowerCase() === resolve(right).toLowerCase();
+}
+/** Refuse a link anywhere in a tree the backup will copy. */
+function assertPlainTree(path, workspace) {
+    if (!isInside(workspace, path)) {
+        throw new MwiError('OUTSIDE_WORKSPACE', `${path} is outside ${workspace}.`, 'Back up a project from the calling workspace.');
+    }
+    if (lstatSync(path).isSymbolicLink()) {
+        throw new MwiError('LINKED_PROJECT', `The project contains a link: ${path}.`, 'Back up a project whose files are all local; links are refused.');
+    }
+    if (!statSync(path).isDirectory())
+        return;
+    for (const entry of readdirSync(path))
+        assertPlainTree(join(path, entry), workspace);
+}
+/** Every file under a directory, in stable order. */
+function tree(path, files) {
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+        const child = join(path, entry.name);
+        if (entry.isDirectory())
+            tree(child, files);
+        else
+            files.push(child);
+    }
+}
+/** Read and fully validate one identity record. */
+function valid(workspace, record) {
+    try {
+        if (record.mode !== 'direct' || typeof record.mwt !== 'string' || typeof record.directory !== 'string')
+            return false;
+        if (!same(record.workspace, workspace))
+            return false;
+        if (!isInside(workspace, record.mwt) || !isInside(workspace, record.directory))
+            return false;
+        if (!same(record.directory, record.mwt.slice(0, -4)))
+            return false;
+        if (!isInside(backupRootOf(workspace), record.backup) || !isInside(record.backup, record.backup_manifest))
+            return false;
+        if (!existsSync(record.mwt) || !existsSync(record.directory) || !existsSync(record.backup_manifest))
+            return false;
+        if (digest(record.backup_manifest) !== record.backup_manifest_sha256)
+            return false;
+        const manifest = JSON.parse(readFileSync(record.backup_manifest, 'utf8'));
+        if (!Array.isArray(manifest.files))
+            return false;
+        for (const file of manifest.files) {
+            if (typeof file?.path !== 'string')
+                return false;
+            const member = join(record.backup, file.path);
+            if (!isInside(record.backup, member) || !existsSync(member))
+                return false;
+        }
+        assertPlainTree(record.directory, workspace);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The record shape the tools return, from an on-disk identity record. */
+function toBackup(record) {
+    return {
+        name: basename(record.mwt, '.mwt'),
+        workspace: record.workspace,
+        mwt: record.mwt,
+        directory: record.directory,
+        backup: record.backup,
+        manifest: record.backup_manifest,
+        created_at: record.attached_at,
+    };
+}
+/** Read every identity record in the workspace, valid or not. */
+function records(workspace) {
+    let names = [];
+    try {
+        names = readdirSync(recordRootOf(workspace)).filter(name => name.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        try {
+            const record = JSON.parse(readFileSync(join(recordRootOf(workspace), name), 'utf8'));
+            if (typeof record?.mwt === 'string' && typeof record?.directory === 'string')
+                found.push(record);
+        }
+        catch {
+            continue;
+        }
+    }
+    return found;
+}
+/** Read the record for a project, when a valid backup exists. */
+export function findBackup(workspace, path) {
+    for (const record of records(workspace)) {
+        if (!same(path, record.mwt) && !same(path, record.directory))
+            continue;
+        if (!valid(workspace, record))
+            continue;
+        return toBackup(record);
+    }
+    return undefined;
+}
+/** Every project with a valid backup in this workspace, one row per project. */
+export function listBackups(workspace) {
+    const found = [];
+    for (const record of records(workspace)) {
+        if (!valid(workspace, record))
+            continue;
+        if (found.some(existing => same(existing.mwt, record.mwt)))
+            continue;
+        found.push(toBackup(record));
+    }
+    return found;
+}
+/**
+ * Back up one real project, or return the valid backup already recorded.
+ *
+ * @param workspace - Absolute workspace root.
+ * @param path - Real `.mwt` or its expanded directory.
+ * @returns The verified backup record.
+ */
+export function ensureBackup(workspace, path) {
+    const asked = resolve(path);
+    const mwt = asked.toLowerCase().endsWith('.mwt') ? asked : `${asked}.mwt`;
+    const directory = mwt.slice(0, -4);
+    if (!existsSync(mwt) || !existsSync(directory)) {
+        throw new MwiError('PROJECT_INCOMPLETE', `${mwt} has no expanded project directory beside it.`, 'Open a complete project: the .mwt and its sibling folder.');
+    }
+    if (!isInside(workspace, mwt) || !isInside(workspace, directory)) {
+        throw new MwiError('OUTSIDE_WORKSPACE', `${mwt} is outside ${workspace}.`, 'Work on a project inside the calling workspace.');
+    }
+    if (isInside(join(workspace, '.motionworks'), mwt)) {
+        throw new MwiError('REFUSED', `${mwt} lives under .motionworks.`, 'Use the staged-project path for a project in the stage.');
+    }
+    assertPlainTree(mwt, workspace);
+    assertPlainTree(directory, workspace);
+    const existing = findBackup(workspace, mwt);
+    if (existing !== undefined)
+        return existing;
+    // A record that no longer validates must be inspected, not silently replaced:
+    // a missing or altered backup member is the evidence a restore would need.
+    for (const record of records(workspace)) {
+        if (same(record.mwt, mwt)) {
+            throw new MwiError('BACKUP_INVALID', `The existing backup identity for ${mwt} does not verify.`, `Inspect ${record.backup} and its manifest before attaching again; a tampered or incomplete backup is not replaced automatically.`);
+        }
+    }
+    const id = randomUUID();
+    const target = join(backupRootOf(workspace), id);
+    const files = [];
+    const sources = [mwt];
+    tree(directory, sources);
+    const before = sources.map(source => ({ source, sha256: digest(source) }));
+    mkdirSync(target, { recursive: true });
+    try {
+        for (const item of before) {
+            const rel = relative(dirname(mwt), item.source);
+            const destination = join(target, rel);
+            mkdirSync(dirname(destination), { recursive: true });
+            copyFileSync(item.source, destination);
+            if (digest(destination) !== item.sha256 || digest(item.source) !== item.sha256) {
+                throw new MwiError('BACKUP_UNSTABLE', `The project changed while it was being copied: ${item.source}.`, `Keep ${target} for inspection and retry on an unchanged project.`);
+            }
+            files.push({ path: rel, sha256: item.sha256 });
+        }
+        for (const item of before) {
+            if (digest(item.source) !== item.sha256) {
+                throw new MwiError('BACKUP_UNSTABLE', `The project changed after it was copied: ${item.source}.`, `Keep ${target} for inspection and retry on an unchanged project.`);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof MwiError)
+            throw error;
+        throw new MwiError('BACKUP_FAILED', error.message, `Keep ${target} for inspection; no identity was written.`);
+    }
+    const manifest = join(target, 'backup-manifest.json');
+    writeFileSync(manifest, JSON.stringify({ workspace, mwt, directory, files }, null, 2));
+    const record = {
+        mode: 'direct',
+        workspace,
+        mwt,
+        directory,
+        session_id: null,
+        backup: target,
+        backup_manifest: manifest,
+        backup_manifest_sha256: digest(manifest),
+        attached_at: new Date().toISOString(),
+    };
+    mkdirSync(recordRootOf(workspace), { recursive: true });
+    const pending = join(recordRootOf(workspace), `${id}.json.tmp`);
+    const final = join(recordRootOf(workspace), `${id}.json`);
+    writeFileSync(pending, JSON.stringify(record, null, 2));
+    renameSync(pending, final);
+    if (!valid(workspace, record)) {
+        throw new MwiError('BACKUP_UNVERIFIED', `The backup at ${target} did not verify.`, `Keep ${target} for inspection and take a fresh copy of an unchanged project.`);
+    }
+    return toBackup(record);
+}

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

@@ -28,7 +28,10 @@ export declare function resolveProject(workspace: string, requested: string): Pr
 /**
  * Resolve the project a call means when it names none.
  *
+ * An attached direct project wins over a stale staged copy: the direct
+ * workflow has no stage, and a leftover stage must not make the call ambiguous.
+ *
  * @param workspace - Absolute workspace root.
- * @returns The single staged project.
+ * @returns The single attached or staged project.
  */
 export declare function defaultProject(workspace: string): ProjectRef;

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

@@ -9,6 +9,7 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { MwiError } from "../core/errors.js";
+import { listBackups } from "./backup.js";
 import { isInside, stageRootOf } from "./workspace.js";
 /**
  * Resolve one project path.
@@ -33,10 +34,20 @@ export function resolveProject(workspace, requested) {
 /**
  * Resolve the project a call means when it names none.
  *
+ * An attached direct project wins over a stale staged copy: the direct
+ * workflow has no stage, and a leftover stage must not make the call ambiguous.
+ *
  * @param workspace - Absolute workspace root.
- * @returns The single staged project.
+ * @returns The single attached or staged project.
  */
 export function defaultProject(workspace) {
+    const attached = listBackups(workspace);
+    if (attached.length === 1) {
+        return resolveProject(workspace, attached[0].mwt);
+    }
+    if (attached.length > 1) {
+        throw new MwiError('AMBIGUOUS_PROJECT', `${attached.length} projects have a pre-edit backup.`, 'Pass project: the project directory or .mwt.', attached.map(record => record.name));
+    }
     let names = [];
     try {
         names = readdirSync(stageRootOf(workspace)).filter(name => name.toLowerCase().endsWith('.mwt'));
@@ -45,7 +56,7 @@ export function defaultProject(workspace) {
         names = [];
     }
     if (names.length === 0) {
-        throw new MwiError('NO_PROJECT', 'No project is staged in this workspace.', 'Call mw_project_find, then mw_project_stage, or pass project explicitly.');
+        throw new MwiError('NO_PROJECT', 'No project is open, backed up or staged in this workspace.', 'Call mw_project_find, then mw_project_open with the workspace .mwt.');
     }
     if (names.length > 1) {
         throw new MwiError('AMBIGUOUS_PROJECT', `${names.length} projects are staged.`, 'Pass project: the project directory or .mwt.', names.map(name => name.replace(/\.mwt$/iu, '')));

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

@@ -8,6 +8,7 @@
  * @module dsh-engineering-mwi/session/service
  */
 import { type StageOptions, type StageRecord } from './stage.ts';
+import { type BackupRecord } from './backup.ts';
 import { ReadService } from '../read/service.ts';
 /** The bridge directory shipped with this package. */
 export declare const BRIDGE_DIR: string;
@@ -32,7 +33,9 @@ export interface SessionRuntime {
     ideState(): Promise<Record<string, unknown>>;
     /** Stage one workspace project. */
     stage(source: string, options?: StageOptions): Promise<StageRecord>;
-    /** Open a staged project. */
+    /** Back up a real workspace project before the first write, or reuse its verified backup. */
+    attach(path: string): BackupRecord;
+    /** Open a staged or a real (backed-up) project. */
     open(path: string, options: {
         userApproved?: boolean;
         expectedProject?: string;
@@ -100,8 +103,12 @@ export declare class PowerShellSessionRuntime implements SessionRuntime {
     status(): Promise<Record<string, unknown>>;
     /** @returns The bridge's live state document. */
     ideState(): Promise<Record<string, unknown>>;
+    /** @returns The open project path, or undefined when no IDE or no project is open. */
+    private activeProject;
     /** @returns The written stage record. */
     stage(source: string, options?: StageOptions): Promise<StageRecord>;
+    /** @returns The verified pre-edit backup record. */
+    attach(path: string): BackupRecord;
     /** @returns The bridge's open result. */
     open(path: string, options: {
         userApproved?: boolean;
@@ -116,7 +123,7 @@ export declare class PowerShellSessionRuntime implements SessionRuntime {
         userApproved: boolean;
         expectedProject?: string;
     }): Promise<Record<string, unknown>>;
-    /** @returns The stage record for a path. */
+    /** @returns The stage record for a path, when it is staged or directly backed up. */
     stagedAt(path: string): StageRecord | undefined;
     /** @returns The bridge's compile result. */
     compile(mode: 'make' | 'build' | 'state'): Promise<Record<string, unknown>>;
@@ -147,12 +154,12 @@ export declare class PowerShellSessionRuntime implements SessionRuntime {
         expectedBody?: string;
         expectedHash?: string;
     }): Promise<Record<string, unknown>>;
-    /** 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. */
     private openStagedRecord;
-    /** 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. */
     private singleStage;
-    /** Resolve a requested staged project. */
-    private stageMwt;
+    /** Resolve a requested project, taking a backup for a real workspace project. */
+    private projectMwt;
 }
 /**
  * Resolve the runtime for one workspace.