@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,187 @@
+/**
+ * Staging: copy one workspace project into `.motionworks/stage` and bind its wrapper.
+ *
+ * The source is never modified. A stage is refused when it already exists unless
+ * the caller explicitly replaces it after review; the previous stage is moved to
+ * `backups/stage-<id>` rather than discarded.
+ *
+ * @module dsh-engineering-mwi/session/stage
+ */
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, copyFileSync, lstatSync, writeFileSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { basename, join, resolve, sep } from 'node:path';
+import { MwiError } from "../core/errors.js";
+import { isInside, stageRootOf } from "./workspace.js";
+/** Identity suffix, matching the legacy stage record. */
+export const IDENTITY_SUFFIX = '.identity.json';
+/** Count and copy one directory tree, refusing links. */
+function copyTree(from, to, count) {
+    mkdirSync(to, { recursive: true });
+    for (const entry of readdirSync(from, { withFileTypes: true })) {
+        const source = join(from, entry.name);
+        const destination = join(to, entry.name);
+        if (entry.isSymbolicLink())
+            throw new MwiError('LINKED_PROJECT', `The project contains a link: ${source}.`, 'Stage a project whose files are all local; links are refused.');
+        if (entry.isDirectory()) {
+            copyTree(source, destination, count);
+            continue;
+        }
+        copyFileSync(source, destination);
+        count.files += 1;
+    }
+}
+/** Copy one file and count it. */
+function copyFile(from, to, count) {
+    copyFileSync(from, to);
+    count.files += 1;
+}
+/** The service that stages projects for one workspace. */
+export class StageService {
+    engine;
+    workspace;
+    /**
+     * @param engine - Code engine that binds the wrapper.
+     * @param workspace - Absolute workspace root.
+     */
+    constructor(engine, workspace) {
+        this.engine = engine;
+        this.workspace = workspace;
+    }
+    /** The stage root of this workspace. */
+    get stageRoot() {
+        return stageRootOf(this.workspace);
+    }
+    /**
+     * Stage one project.
+     *
+     * @param sourceArg - `.mwt` or project directory inside the workspace.
+     * @param options - Replacement and closed-project checks.
+     * @returns The written stage record.
+     */
+    async stage(sourceArg, options = {}) {
+        const asked = resolve(this.workspace, sourceArg);
+        if (!isInside(this.workspace, asked)) {
+            throw new MwiError('OUTSIDE_WORKSPACE', `${asked} is outside the workspace ${this.workspace}.`, 'Call mw_project_find and stage a project from the workspace; outside projects are never opened.');
+        }
+        const isMwt = asked.toLowerCase().endsWith('.mwt');
+        const mwt = isMwt ? asked : `${asked}.mwt`;
+        const directory = isMwt ? asked.slice(0, -4) : asked;
+        if (!existsSync(mwt))
+            throw new MwiError('PROJECT_NOT_FOUND', `No .mwt exists at ${mwt}.`, 'Pass the project folder or its .mwt, both inside the workspace.');
+        if (!existsSync(directory) || !statSync(directory).isDirectory()) {
+            throw new MwiError('PROJECT_INCOMPLETE', `${mwt} has no expanded project directory beside it.`, 'Stage a complete project: the .mwt and its sibling folder.');
+        }
+        if (isInside(this.stageRoot, mwt) || isInside(this.stageRoot, directory)) {
+            throw new MwiError('ALREADY_STAGED', `${mwt} is already inside the stage.`, 'Stage the original workspace project, not an existing staged copy.');
+        }
+        const name = basename(mwt, '.mwt');
+        const targetMwt = join(this.stageRoot, `${name}.mwt`);
+        const targetDir = join(this.stageRoot, name);
+        const identity = join(this.stageRoot, `${name}${IDENTITY_SUFFIX}`);
+        const previous = [targetMwt, targetDir, identity].filter(path => existsSync(path));
+        if (previous.length > 0 && options.replace !== true) {
+            throw new MwiError('STAGE_EXISTS', `A staged copy named ${name} already exists.`, 'Continue the existing stage, or pass replace_existing:true after reviewing it; the previous stage is retained under backups/.');
+        }
+        if (existsSync(targetDir)) {
+            for (const entry of readdirSync(targetDir)) {
+                if (lstatSync(join(targetDir, entry)).isSymbolicLink()) {
+                    throw new MwiError('LINKED_STAGE', 'The existing stage contains a link.', 'Remove the stage only after review; links are refused.');
+                }
+            }
+        }
+        await options.assertClosed?.();
+        mkdirSync(this.stageRoot, { recursive: true });
+        const pending = join(this.stageRoot, `.pending-${randomUUID()}`);
+        mkdirSync(pending);
+        const count = { files: 0 };
+        let backup = null;
+        try {
+            const incomingMwt = join(pending, `${name}.mwt`);
+            const incomingDir = join(pending, name);
+            copyFile(mwt, incomingMwt, count);
+            copyTree(directory, incomingDir, count);
+            const bound = await this.engine.run('bind_mwt', { mwt: incomingMwt, directory: targetDir });
+            const record = {
+                name,
+                source: mwt,
+                source_directory: directory,
+                workspace: this.workspace,
+                staged_mwt: targetMwt,
+                staged_directory: targetDir,
+                bound_to: bound.bound_to ?? targetDir,
+                previous_embedded_path: bound.paths?.[0]?.from ?? null,
+                staged_at: new Date().toISOString(),
+            };
+            if (previous.length > 0) {
+                backup = join(this.stageRoot, 'backups', `stage-${randomUUID()}`);
+                mkdirSync(backup, { recursive: true });
+                for (const path of previous)
+                    renameSync(path, join(backup, basename(path)));
+            }
+            renameSync(incomingMwt, targetMwt);
+            renameSync(incomingDir, targetDir);
+            writeFileSync(identity, JSON.stringify(record, null, 2));
+            rmSync(pending, { recursive: true, force: true });
+            return record;
+        }
+        catch (error) {
+            rmSync(pending, { recursive: true, force: true });
+            const message = error instanceof Error ? error.message : String(error);
+            throw new MwiError('STAGE_FAILED', message, backup === null
+                ? 'Nothing was written to the stage. Correct the project and retry.'
+                : `The previous stage is retained at ${backup}; inspect it before retrying.`);
+        }
+    }
+    /**
+     * Read one identity record.
+     *
+     * @param name - Project name.
+     * @returns The record, or undefined when the name was not staged.
+     */
+    identityOf(name) {
+        try {
+            return JSON.parse(readFileSync(join(this.stageRoot, `${name}${IDENTITY_SUFFIX}`), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * The staged project whose `.mwt` or directory is `path`.
+     *
+     * @param path - Active or requested project path.
+     * @returns Its identity record, or undefined.
+     */
+    stagedAt(path) {
+        const target = resolve(path).toLowerCase().replace(/\.mwt$/u, '');
+        let names = [];
+        try {
+            names = readdirSync(this.stageRoot).filter(name => name.endsWith(IDENTITY_SUFFIX));
+        }
+        catch {
+            return undefined;
+        }
+        for (const file of names) {
+            const record = this.identityOf(file.slice(0, -IDENTITY_SUFFIX.length));
+            if (record === undefined)
+                continue;
+            if (resolve(record.staged_directory).toLowerCase() === target)
+                return record;
+        }
+        return undefined;
+    }
+    /**
+     * Refuse when the active IDE project is this stage.
+     *
+     * @param targetDir - Stage directory about to be replaced.
+     * @param status - Bridge status document.
+     */
+    static assertClosed(targetDir, status) {
+        if (status.is_project_open !== true || typeof status.active_project !== 'string')
+            return;
+        const active = resolve(status.active_project).toLowerCase().replace(/\.mwt$/u, '');
+        if (active === resolve(targetDir).toLowerCase() || active.startsWith(resolve(targetDir).toLowerCase() + sep)) {
+            throw new MwiError('STAGE_OPEN', `The staged project is open in the IDE: ${status.active_project}.`, 'Save or close the open project with consent before replacing its stage.');
+        }
+    }
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Workspace and stage paths.
+ *
+ * MotionWorks work happens on a project inside the calling workspace. The stage
+ * is the one writable location: `<workspace>/.motionworks/stage`.
+ *
+ * @module dsh-engineering-mwi/session/workspace
+ */
+/** One MotionWorks project found in the workspace. */
+export interface FoundProject {
+    /** Project name: the `.mwt` basename. */
+    readonly name: string;
+    /** Absolute path of the wrapper. */
+    readonly mwt: string;
+    /** Absolute path of the expanded project directory. */
+    readonly directory: string;
+    /** Absolute path of the staged copy, when one exists. */
+    readonly staged: string | null;
+}
+/**
+ * Resolve the caller's workspace.
+ *
+ * @param cwd - Working directory from the tool call.
+ * @returns The absolute workspace root.
+ */
+export declare function workspaceOf(cwd: string | undefined): string;
+/**
+ * The stage root of one workspace.
+ *
+ * @param workspace - Absolute workspace root.
+ * @returns `<workspace>/.motionworks/stage`.
+ */
+export declare function stageRootOf(workspace: string): string;
+/**
+ * Whether a path lies inside a directory.
+ *
+ * @param parent - Directory that must contain the path.
+ * @param child - Path to test.
+ * @returns True when `child` equals or lies below `parent`.
+ */
+export declare function isInside(parent: string, child: string): boolean;
+/**
+ * Find MotionWorks projects under a workspace.
+ *
+ * @param workspace - Absolute workspace root.
+ * @param options - Optional name filter and result cap.
+ * @returns Projects in stable path order.
+ */
+export declare function findProjects(workspace: string, options?: {
+    filter?: string;
+    limit?: number;
+}): FoundProject[];

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

@@ -0,0 +1,90 @@
+/**
+ * Workspace and stage paths.
+ *
+ * MotionWorks work happens on a project inside the calling workspace. The stage
+ * is the one writable location: `<workspace>/.motionworks/stage`.
+ *
+ * @module dsh-engineering-mwi/session/workspace
+ */
+import { existsSync, readdirSync } 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']);
+/**
+ * Resolve the caller's workspace.
+ *
+ * @param cwd - Working directory from the tool call.
+ * @returns The absolute workspace root.
+ */
+export function workspaceOf(cwd) {
+    return resolve(cwd ?? process.cwd());
+}
+/**
+ * The stage root of one workspace.
+ *
+ * @param workspace - Absolute workspace root.
+ * @returns `<workspace>/.motionworks/stage`.
+ */
+export function stageRootOf(workspace) {
+    return join(workspace, '.motionworks', 'stage');
+}
+/**
+ * Whether a path lies inside a directory.
+ *
+ * @param parent - Directory that must contain the path.
+ * @param child - Path to test.
+ * @returns True when `child` equals or lies below `parent`.
+ */
+export function isInside(parent, child) {
+    const base = resolve(parent).toLowerCase();
+    const target = resolve(child).toLowerCase();
+    return target === base || target.startsWith(base + sep);
+}
+/**
+ * Find MotionWorks projects under a workspace.
+ *
+ * @param workspace - Absolute workspace root.
+ * @param options - Optional name filter and result cap.
+ * @returns Projects in stable path order.
+ */
+export function findProjects(workspace, options = {}) {
+    const limit = options.limit ?? 20;
+    const filter = options.filter?.toLowerCase();
+    const stage = stageRootOf(workspace);
+    const found = [];
+    const walk = (directory, depth) => {
+        if (found.length >= limit || depth > 6)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            if (found.length >= limit)
+                return;
+            const absolute = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP.has(entry.name) || isInside(stage, absolute))
+                    continue;
+                walk(absolute, depth + 1);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.mwt'))
+                continue;
+            const name = entry.name.slice(0, -4);
+            if (filter !== undefined && !name.toLowerCase().includes(filter) && !absolute.toLowerCase().includes(filter))
+                continue;
+            found.push({
+                name,
+                mwt: absolute,
+                directory: absolute.slice(0, -4),
+                staged: existsSync(join(stage, `${name}.mwt`)) ? join(stage, `${name}.mwt`) : null,
+            });
+        }
+    };
+    walk(workspace, 0);
+    return found;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * The guidance half of the MotionWorks IEC redesign.
+ *
+ * The tools land in the row entries; this module registers the
+ * `motionworks-iec` skill that tells a model how to use them. It is a separate
+ * loader entry, so a profile can run the tools without the guidance or the
+ * guidance without the tools.
+ *
+ * @module dsh-engineering-mwi/skill
+ */
+/** Plugin name in a composition. */
+export declare const name = "mwi-skill";
+/** Services this plugin cannot register without. */
+export declare const inject: readonly ["skills"];
+/** The plugin context this module needs. */
+export interface SkillContext {
+    get(name: string): unknown;
+    logger?: {
+        info?(message: string): void;
+    };
+}
+/** 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.";
+};
+/**
+ * Register the MotionWorks IEC skill.
+ *
+ * The IDE is a Windows application, so a host elsewhere skips registration
+ * instead of offering guidance no tool can follow.
+ *
+ * @param ctx - Plugin context whose skill registry receives the registration.
+ */
+export declare function apply(ctx: SkillContext): void;

package/vendor/mwi/lib/skill.js

@@ -0,0 +1,56 @@
+/**
+ * The guidance half of the MotionWorks IEC redesign.
+ *
+ * The tools land in the row entries; this module registers the
+ * `motionworks-iec` skill that tells a model how to use them. It is a separate
+ * loader entry, so a profile can run the tools without the guidance or the
+ * guidance without the tools.
+ *
+ * @module dsh-engineering-mwi/skill
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/** Plugin name in a composition. */
+export const name = 'mwi-skill';
+/** Services this plugin cannot register without. */
+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.',
+};
+/**
+ * Register the MotionWorks IEC skill.
+ *
+ * The IDE is a Windows application, so a host elsewhere skips registration
+ * instead of offering guidance no tool can follow.
+ *
+ * @param ctx - Plugin context whose skill registry receives the registration.
+ */
+export function apply(ctx) {
+    if (process.platform !== 'win32') {
+        try {
+            ctx.logger?.info?.(`mwi-skill: skipped because this host is ${process.platform}; MotionWorks IEC requires Windows.`);
+        }
+        catch {
+            // A logger that refuses must not turn an unsupported host into a crash.
+        }
+        return;
+    }
+    const skills = ctx.get('skills');
+    if (skills === undefined || typeof skills.register !== 'function') {
+        throw new Error('mwi-skill: the skills service is unavailable, so the motionworks-iec guidance cannot register');
+    }
+    const skillPath = fileURLToPath(new URL('../SKILL.md', import.meta.url));
+    const raw = readFileSync(skillPath, 'utf8');
+    const content = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, '');
+    skills.register({
+        ...SKILL,
+        content,
+        path: skillPath,
+        source: 'custom',
+        provider: '@aryacode/dsh-engineering-mwi',
+        invocation: { modelInvocable: true, userInvocable: true },
+    });
+}

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

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