@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,229 @@
+/**
+ * Read the saved project through the code engine.
+ *
+ * These reads describe the saved project, not the loaded IDE instance. Anything
+ * that needs the live object model says so in its coverage.
+ *
+ * @module dsh-engineering-mwi/read/service
+ */
+import { MwiError } from "../core/errors.js";
+/** Kinds `mw_list` can enumerate. */
+export const LIST_KINDS = ['pou', 'variable', 'global', 'type', 'task', 'library'];
+/** Kinds `mw_get` can read. */
+export const GET_KINDS = ['pou', 'type', 'task', 'block', 'eip'];
+/** The saved-project read service. */
+export class ReadService {
+    engine;
+    /**
+     * @param engine - Code engine over the project files.
+     */
+    constructor(engine) {
+        this.engine = engine;
+    }
+    /** Confirm the engine can read one project. */
+    async workflow(project) {
+        return await this.engine.run('workflow_check', { project: project.directory }, 120_000);
+    }
+    /**
+     * List one kind.
+     *
+     * @param project - Project to read.
+     * @param kind - Listing kind.
+     * @param options - Filter, paging and the POU for variable reads.
+     * @returns Rows and the total before paging.
+     */
+    async list(project, kind, options = {}) {
+        const rows = await this.rows(project, kind, options.pou);
+        const filter = options.filter?.toLowerCase();
+        const filtered = filter === undefined ? rows : rows.filter(row => JSON.stringify(row).toLowerCase().includes(filter));
+        const offset = options.offset ?? 0;
+        const limit = options.limit ?? 50;
+        return { rows: filtered.slice(offset, offset + limit), total: filtered.length };
+    }
+    /**
+     * Read one component by name.
+     *
+     * @param project - Project to read.
+     * @param kind - Component kind.
+     * @param name - Exact name.
+     * @param library - Library name for a block interface.
+     * @returns The component document.
+     */
+    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 };
+        }
+        if (kind === 'block') {
+            return await this.engine.run('block_interface', {
+                project: project.directory,
+                name,
+                ...(library === undefined ? {} : { library }),
+            }, 60_000);
+        }
+        if (kind === 'eip')
+            return await this.engine.run('eip_map', { project: project.directory }, 60_000);
+        const rows = await this.rows(project, kind === 'type' ? 'type' : 'task');
+        const found = rows.find(row => String(row.name).toLowerCase() === name.toLowerCase());
+        if (found === undefined) {
+            throw new MwiError('COMPONENT_NOT_FOUND', `No ${kind} named ${name} exists in ${project.name}.`, 'Call mw_list for the exact names.', rows.slice(0, 20).map(row => String(row.name)));
+        }
+        return { found };
+    }
+    /**
+     * Search POU bodies for literal text.
+     *
+     * @param project - Project to read.
+     * @param query - Case-insensitive literal text.
+     * @param limit - Most matches.
+     * @returns Matches in project order.
+     */
+    async search(project, query, limit = 50) {
+        const bodies = await this.bodies(project, 100);
+        const matches = [];
+        let truncated = false;
+        for (const body of bodies) {
+            for (const [index, line] of body.lines.entries()) {
+                if (!line.toLowerCase().includes(query.toLowerCase()))
+                    continue;
+                if (matches.length >= limit) {
+                    truncated = true;
+                    break;
+                }
+                matches.push({ pou: body.pou, line: index + 1, text: line.trim() });
+            }
+            if (truncated)
+                break;
+        }
+        return { matches, truncated, scanned: bodies.length };
+    }
+    /**
+     * Find a symbol in POU bodies.
+     *
+     * @param project - Project to read.
+     * @param symbol - Declared or written symbol name.
+     * @param limit - Most matches.
+     * @returns Matches with the line that contains them.
+     */
+    async references(project, symbol, limit = 50) {
+        const pattern = new RegExp(`(?<![\\w.])${symbol.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}(?![\\w])`, 'iu');
+        const bodies = await this.bodies(project, 100);
+        const matches = [];
+        let truncated = false;
+        for (const body of bodies) {
+            for (const [index, line] of body.lines.entries()) {
+                if (!pattern.test(line))
+                    continue;
+                if (matches.length >= limit) {
+                    truncated = true;
+                    break;
+                }
+                matches.push({ pou: body.pou, line: index + 1, text: line.trim() });
+            }
+            if (truncated)
+                break;
+        }
+        return { matches, truncated, scanned: bodies.length };
+    }
+    /**
+     * Run the static review surface.
+     *
+     * @param project - Project to read.
+     * @param options - Optional POU and proposed body.
+     * @returns Workflow, validation, unsupported-construct and program-review results.
+     */
+    async review(project, options = {}) {
+        const workflow = await this.engine.run('workflow_check', { project: project.directory }, 120_000);
+        const validate = await this.engine.run('validate', { project: project.directory }, 120_000);
+        const unsupported = await this.engine.run('unsupported', { project: project.directory }, 60_000);
+        const review = options.pou === undefined && options.body === undefined
+            ? undefined
+            : await this.engine.run('check_program', {
+                project: project.directory,
+                ...(options.pou === undefined ? {} : { pou: options.pou }),
+                ...(options.body === undefined ? {} : { body: options.body }),
+            }, 180_000);
+        return { workflow, validate, unsupported, ...(review === undefined ? {} : { review }) };
+    }
+    /**
+     * Search help and reviewed references.
+     *
+     * @param project - Project used for the workspace cache.
+     * @param source - Help source: help, manual, reference or pattern.
+     * @param query - Search term; omitted lists what is available.
+     * @param limit - Most rows.
+     * @returns The engine document with its source named.
+     */
+    async help(project, source, query, limit = 10) {
+        if (source === 'help') {
+            return await this.engine.run('installed_help', {
+                ...(query === undefined ? {} : { query }),
+                limit,
+            }, 120_000);
+        }
+        if (source === 'manual') {
+            return await this.engine.run('manual', { ...(query === undefined ? {} : { term: query }) }, 120_000);
+        }
+        if (source === 'reference') {
+            return await this.engine.run('reference', { ...(query === undefined ? {} : { query }) }, 120_000);
+        }
+        return await this.engine.run('pattern', { ...(query === undefined ? {} : { name: query }) }, 60_000);
+    }
+    /** Read every POU body, capped. */
+    async bodies(project, cap) {
+        const listed = await this.engine.run('pous', { project: project.directory }, 120_000);
+        const pous = listed.pous ?? [];
+        const readable = pous.filter(pou => pou.has_st_body !== false && (pou.stream_language ?? 'ST') !== 'LD' && (pou.stream_language ?? 'ST') !== 'FBD').slice(0, cap);
+        const bodies = [];
+        for (const pou of readable) {
+            try {
+                const text = await this.engine.run('read_text', { project: project.directory, pou: pou.name }, 60_000);
+                const body = typeof text.text === 'string' ? text.text : typeof text.body === 'string' ? text.body : '';
+                bodies.push({ pou: pou.name, lines: body.split(/\r?\n/u) });
+            }
+            catch {
+                // A graphical or protected POU has no text body; it is skipped and the
+                // coverage names the gap.
+            }
+        }
+        return bodies;
+    }
+    /** Map one kind to rows. */
+    async rows(project, kind, pou) {
+        if (kind === 'pou') {
+            const listed = await this.engine.run('pous', { project: project.directory }, 120_000);
+            return (listed.pous ?? []).map(row => ({
+                name: String(row.name), language: row.language, has_st_body: row.has_st_body,
+            }));
+        }
+        if (kind === 'global') {
+            const globals = await this.engine.run('globals', { project: project.directory }, 120_000);
+            return (globals.variables ?? []).map(row => ({ ...row, name: String(row.name) }));
+        }
+        if (kind === 'variable') {
+            if (pou === undefined)
+                throw new MwiError('POU_REQUIRED', 'Listing variables needs a POU.', 'Pass pou, or use kind global for resource globals.');
+            const text = await this.engine.run('read_text', { project: project.directory, pou }, 60_000);
+            return (text.variables ?? []).map(row => ({ ...row, name: String(row.name) }));
+        }
+        if (kind === 'type') {
+            const types = await this.engine.run('types', { project: project.directory }, 120_000);
+            return (types.types ?? []).map(row => ({ ...row, name: String(row.name) }));
+        }
+        if (kind === 'task') {
+            const tasks = await this.engine.run('tasks', { project: project.directory }, 120_000);
+            const bindings = tasks.bindings ?? [];
+            const unassigned = tasks.unassigned ?? [];
+            return [
+                ...bindings.map(row => ({ ...row, name: String(row.name) })),
+                ...unassigned.map(name => ({ name, kind: 'UNASSIGNED' })),
+            ];
+        }
+        if (kind === 'library') {
+            const library = await this.engine.run('library', { project: project.directory }, 120_000);
+            const blocks = library.blocks ?? library.libraries ?? [];
+            return blocks.map(row => ({ ...row, name: String(row.name ?? row.library ?? '') }));
+        }
+        throw new MwiError('UNKNOWN_KIND', `Unknown listing kind ${kind}.`, `Use one of: ${LIST_KINDS.join(', ')}.`);
+    }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The `mwi-read` entry: the saved project model, code, help and review evidence.
+ *
+ * The row registers on Windows only, like the session row: the engine reads a
+ * MotionWorks project and the bridge covers the same installation.
+ *
+ * @module dsh-engineering-mwi/read
+ */
+import type { PluginContext } from './core/tool.ts';
+/** Plugin name in a composition. */
+export declare const name = "mwi-read";
+/** Services this plugin cannot register without. */
+export declare const inject: readonly ["tools"];
+/**
+ * Register the read tools.
+ *
+ * @param ctx - Plugin context with the tool registry.
+ */
+export declare function apply(ctx: PluginContext): void;
+export { readTools } from './tools/read.ts';
+export { ReadService } from './read/service.ts';

package/vendor/mwi/lib/read.js

@@ -0,0 +1,33 @@
+/**
+ * The `mwi-read` entry: the saved project model, code, help and review evidence.
+ *
+ * The row registers on Windows only, like the session row: the engine reads a
+ * MotionWorks project and the bridge covers the same installation.
+ *
+ * @module dsh-engineering-mwi/read
+ */
+import { readTools } from "./tools/read.js";
+/** Plugin name in a composition. */
+export const name = 'mwi-read';
+/** Services this plugin cannot register without. */
+export const inject = ['tools'];
+/**
+ * Register the read tools.
+ *
+ * @param ctx - Plugin context with the tool registry.
+ */
+export function apply(ctx) {
+    if (process.platform !== 'win32') {
+        try {
+            ctx.logger?.info?.(`mwi-read: skipped because this host is ${process.platform}; MotionWorks IEC requires Windows.`);
+        }
+        catch {
+            // A logger that refuses must not turn an unsupported host into a crash.
+        }
+        return;
+    }
+    for (const definition of readTools())
+        ctx.tools.register(definition);
+}
+export { readTools } from "./tools/read.js";
+export { ReadService } from "./read/service.js";

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

@@ -0,0 +1,34 @@
+/**
+ * Resolve the project a read applies to.
+ *
+ * A read never stages or opens anything: it uses an explicit project inside the
+ * workspace, or the single staged project when no project is named.
+ *
+ * @module dsh-engineering-mwi/session/project
+ */
+/** One project a read can address. */
+export interface ProjectRef {
+    /** Project name. */
+    readonly name: string;
+    /** Expanded project directory. */
+    readonly directory: string;
+    /** The `.mwt` wrapper. */
+    readonly mwt: string;
+    /** Whether the project is a staged copy. */
+    readonly staged: boolean;
+}
+/**
+ * Resolve one project path.
+ *
+ * @param workspace - Absolute workspace root.
+ * @param requested - Project directory `.mwt` or name, relative to the workspace.
+ * @returns The resolved project.
+ */
+export declare function resolveProject(workspace: string, requested: string): ProjectRef;
+/**
+ * Resolve the project a call means when it names none.
+ *
+ * @param workspace - Absolute workspace root.
+ * @returns The single staged project.
+ */
+export declare function defaultProject(workspace: string): ProjectRef;

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

@@ -0,0 +1,54 @@
+/**
+ * Resolve the project a read applies to.
+ *
+ * A read never stages or opens anything: it uses an explicit project inside the
+ * workspace, or the single staged project when no project is named.
+ *
+ * @module dsh-engineering-mwi/session/project
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { MwiError } from "../core/errors.js";
+import { isInside, stageRootOf } from "./workspace.js";
+/**
+ * Resolve one project path.
+ *
+ * @param workspace - Absolute workspace root.
+ * @param requested - Project directory `.mwt` or name, relative to the workspace.
+ * @returns The resolved project.
+ */
+export function resolveProject(workspace, requested) {
+    const asked = resolve(workspace, requested);
+    const isMwt = asked.toLowerCase().endsWith('.mwt');
+    const mwt = isMwt ? asked : `${asked}.mwt`;
+    const directory = isMwt ? asked.slice(0, -4) : asked;
+    if (!isInside(workspace, directory)) {
+        throw new MwiError('OUTSIDE_WORKSPACE', `${directory} is outside the workspace ${workspace}.`, 'Read a project inside the workspace.');
+    }
+    if (!existsSync(directory) || !existsSync(mwt)) {
+        throw new MwiError('PROJECT_NOT_FOUND', `No project exists at ${directory}.`, 'Call mw_project_find for the workspace projects.');
+    }
+    return { name: basename(directory), directory, mwt, staged: isInside(stageRootOf(workspace), directory) };
+}
+/**
+ * Resolve the project a call means when it names none.
+ *
+ * @param workspace - Absolute workspace root.
+ * @returns The single staged project.
+ */
+export function defaultProject(workspace) {
+    let names = [];
+    try {
+        names = readdirSync(stageRootOf(workspace)).filter(name => name.toLowerCase().endsWith('.mwt'));
+    }
+    catch {
+        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.');
+    }
+    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, '')));
+    }
+    return resolveProject(workspace, join(stageRootOf(workspace), names[0]));
+}

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

@@ -0,0 +1,167 @@
+/**
+ * One workspace's MotionWorks runtime: bridge, code engine, stage and the rows
+ * that need them.
+ *
+ * Runtimes are cached per workspace so one chat reuses the bridge it started and
+ * one workspace's mailbox never answers another's request.
+ *
+ * @module dsh-engineering-mwi/session/service
+ */
+import { type StageOptions, type StageRecord } from './stage.ts';
+import { ReadService } from '../read/service.ts';
+/** The bridge directory shipped with this package. */
+export declare const BRIDGE_DIR: string;
+/** The code engine directory shipped with this package. */
+export declare const CODE_DIR: string;
+/** Vendored proven mutation helpers. */
+export declare const LEGACY_DIR: string;
+/** One open worksheet request. */
+export interface WorksheetRequest {
+    /** `code` or `variables`. */
+    readonly kind: 'code' | 'variables';
+    /** POU name for a code worksheet; omit for globals. */
+    readonly pou?: string;
+    /** Inspect the current editor instead of opening one. */
+    readonly inspectOnly?: boolean;
+}
+/** What the session tools need from a workspace runtime. */
+export interface SessionRuntime {
+    /** IDE status from the bridge. */
+    status(): Promise<Record<string, unknown>>;
+    /** Live IDE state, including window and dialog state. */
+    ideState(): Promise<Record<string, unknown>>;
+    /** Stage one workspace project. */
+    stage(source: string, options?: StageOptions): Promise<StageRecord>;
+    /** Open a staged project. */
+    open(path: string, options: {
+        userApproved?: boolean;
+        expectedProject?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Start the IDE with a staged project. */
+    start(project?: string): Promise<Record<string, unknown>>;
+    /** Open one worksheet in the open project. */
+    worksheet(request: WorksheetRequest): Promise<Record<string, unknown>>;
+    /** Close the IDE project with consent. */
+    close(options: {
+        userApproved: boolean;
+        expectedProject?: string;
+    }): Promise<Record<string, unknown>>;
+    /** The stage record for a path, when it is staged. */
+    stagedAt(path: string): StageRecord | undefined;
+    /** Saved-project reads over the code engine. */
+    readonly reads: ReadService;
+    /** Run Make, Build or read compile state for the open staged project. */
+    compile(mode: 'make' | 'build' | 'state'): Promise<Record<string, unknown>>;
+    /** Read one IDE output pane, with the compile verdict when available. */
+    diagnostics(pane: string, limit: number): Promise<Record<string, unknown>>;
+    /** Capture or compare one saved-source baseline. */
+    verify(mode: 'baseline' | 'compare', baselineId?: string): Promise<Record<string, unknown>>;
+    /** Replace one ST/IL body through the native ChangeCodeWS path. */
+    editCode(input: {
+        pou: string;
+        changes?: readonly Record<string, unknown>[];
+        body?: string;
+        expectedBody?: string;
+        expectedHash?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Validate the current saved project before or after an edit. */
+    validate(options: {
+        pou?: string;
+        body?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Save the open staged project through the IDE. */
+    apply(): Promise<Record<string, unknown>>;
+    /** Insert one FB instance and its ST call into a POU. */
+    insertBlock(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    /** Export one POU to a workspace package, or import it into this project. */
+    transferPou(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    /** Add, edit or delete one native declaration. */
+    editVariable(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    /** Create, copy, rename, delete or assign one POU or task. */
+    editStructure(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    /** Insert one FB instance and its ST call into a POU. */
+    insertBlock(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+}
+/** A workspace runtime over the real bridge and engine. */
+export declare class PowerShellSessionRuntime implements SessionRuntime {
+    readonly workspace: string;
+    private readonly bridge;
+    private readonly engine;
+    private readonly stages;
+    /** Saved-project reads. */
+    readonly reads: ReadService;
+    /** Live POU-package receipts, bound to this runtime. */
+    private readonly packages;
+    /**
+     * @param workspace - Absolute workspace root.
+     */
+    constructor(workspace: string);
+    /** @returns The bridge's status document. */
+    status(): Promise<Record<string, unknown>>;
+    /** @returns The bridge's live state document. */
+    ideState(): Promise<Record<string, unknown>>;
+    /** @returns The written stage record. */
+    stage(source: string, options?: StageOptions): Promise<StageRecord>;
+    /** @returns The bridge's open result. */
+    open(path: string, options: {
+        userApproved?: boolean;
+        expectedProject?: string;
+    }): Promise<Record<string, unknown>>;
+    /** @returns The bridge's start result. */
+    start(project?: string): Promise<Record<string, unknown>>;
+    /** @returns The bridge's worksheet result. */
+    worksheet(request: WorksheetRequest): Promise<Record<string, unknown>>;
+    /** @returns The bridge's close result. */
+    close(options: {
+        userApproved: boolean;
+        expectedProject?: string;
+    }): Promise<Record<string, unknown>>;
+    /** @returns The stage record for a path. */
+    stagedAt(path: string): StageRecord | undefined;
+    /** @returns The bridge's compile result. */
+    compile(mode: 'make' | 'build' | 'state'): Promise<Record<string, unknown>>;
+    /** @returns The output pane and the compile verdict when readable. */
+    diagnostics(pane: string, limit: number): Promise<Record<string, unknown>>;
+    /** @returns A baseline receipt or a comparison against one. */
+    verify(mode: 'baseline' | 'compare', baselineId?: string): Promise<Record<string, unknown>>;
+    /** Export one POU to a workspace package, or import it into this project. */
+    transferPou(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    /** Insert one FB instance and its ST call into a POU. */
+    insertBlock(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    /** Add, edit or delete one native declaration. */
+    editVariable(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    /** Create, copy, rename, delete or assign one POU or task. */
+    editStructure(input: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
+    /** Validate the current saved project. */
+    validate(options: {
+        pou?: string;
+        body?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Save the open staged project through the IDE. */
+    apply(): Promise<Record<string, unknown>>;
+    /** Replace one ST/IL body through the proven native ChangeCodeWS path. */
+    editCode(input: {
+        pou: string;
+        changes?: readonly Record<string, unknown>[];
+        body?: string;
+        expectedBody?: string;
+        expectedHash?: string;
+    }): Promise<Record<string, unknown>>;
+    /** The open project must be a proven stage; every compile and verify depends on it. */
+    private openStagedRecord;
+    /** The only staged project, or a refusal that explains the choice. */
+    private singleStage;
+    /** Resolve a requested staged project. */
+    private stageMwt;
+}
+/**
+ * Resolve the runtime for one workspace.
+ *
+ * @param workspace - Absolute workspace root.
+ * @returns The cached runtime.
+ */
+export declare function runtimeFor(workspace: string): PowerShellSessionRuntime;
+/** Resolve a tool call's workspace. */
+export declare function workspaceFrom(exec: {
+    cwd?: string;
+}): string;