lasal-mcp 0.1.0

package/dist/utils/preflight.js

@@ -0,0 +1,194 @@
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { dirname, join } from "path";
+import { XMLParser } from "fast-xml-parser";
+import * as net from "net";
+// Helper to find .lss file from .lcp path
+export function findLssPath(lcpPath) {
+    const lcpDir = dirname(lcpPath);
+    try {
+        const files = readdirSync(lcpDir);
+        for (const f of files) {
+            if (f.endsWith(".lss"))
+                return join(lcpDir, f);
+        }
+    }
+    catch { }
+    const parentDir = dirname(lcpDir);
+    try {
+        const parentFiles = readdirSync(parentDir);
+        for (const f of parentFiles) {
+            if (f.endsWith(".lss"))
+                return join(parentDir, f);
+        }
+    }
+    catch { }
+    return null;
+}
+/** True when the connection targets a local LARS (or other local) runtime. */
+export function isLoopbackTarget(conn) {
+    const ip = conn.ip;
+    if (!ip)
+        return false;
+    return ip === "127.0.0.1" || ip === "localhost" || ip.startsWith("127.");
+}
+/** Extract the IP and optional port from a connection string like 'TCPIP:10.0.0.5:1964'. */
+export function parseConnectionTarget(conn) {
+    let target = conn;
+    const m = conn.match(/TCPIP:(.+)/i);
+    if (m)
+        target = m[1];
+    if (target.includes(":")) {
+        const [ipPart, portPart] = target.split(":");
+        if (ipPart && portPart) {
+            const port = parseInt(portPart, 10);
+            if (!isNaN(port) && port > 0 && port <= 65535) {
+                return { ip: ipPart, port };
+            }
+        }
+        return { ip: target.split(":")[0] };
+    }
+    if (target.includes("."))
+        return { ip: target };
+    return { ip: target };
+}
+export function resolveConnection(lcpPath, explicit) {
+    if (explicit) {
+        const { ip, port } = parseConnectionTarget(explicit);
+        return { connection: explicit, ip, port, source: "explicit" };
+    }
+    const lssPath = findLssPath(lcpPath);
+    if (!lssPath) {
+        return { connection: "", source: "lss", warning: `No .lss file found near ${lcpPath}` };
+    }
+    if (!existsSync(lssPath)) {
+        return { connection: "", source: "lss", warning: `LSS file not found at ${lssPath}` };
+    }
+    try {
+        const raw = readFileSync(lssPath, "latin1");
+        const xmlParser = new XMLParser({ ignoreAttributes: false, parseAttributeValue: false });
+        const doc = xmlParser.parse(raw);
+        const tcpip = doc.SlnStation?.OnlineConnectionInfo?.TCPIP;
+        if (tcpip) {
+            const ip = tcpip["@_IP"];
+            const port = tcpip["@_PORT"] ?? "1954";
+            const portNum = parseInt(port, 10);
+            return {
+                connection: `TCPIP:${ip}${port && port !== "1954" ? `:${port}` : ""}`,
+                ip,
+                port: !isNaN(portNum) ? portNum : undefined,
+                source: "lss",
+            };
+        }
+        return { connection: "", source: "lss", warning: `LSS file ${lssPath} has no <TCPIP> element` };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { connection: "", source: "lss", warning: `Failed to parse .lss at ${lssPath}: ${msg}` };
+    }
+}
+export function pingHost(ip, port = 1954, timeoutMs = 1000) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        let resolved = false;
+        socket.setTimeout(timeoutMs);
+        socket.on("connect", () => {
+            if (!resolved) {
+                resolved = true;
+                socket.destroy();
+                resolve(true);
+            }
+        });
+        const onError = () => {
+            if (!resolved) {
+                resolved = true;
+                socket.destroy();
+                resolve(false);
+            }
+        };
+        socket.on("error", onError);
+        socket.on("timeout", onError);
+        socket.connect(port, ip);
+    });
+}
+export async function preflightPlc(lcpPath, explicitConn) {
+    const problems = [];
+    if (!existsSync(lcpPath)) {
+        problems.push({
+            code: "LCP_NOT_FOUND",
+            message: `Project LCP file does not exist at ${lcpPath}`,
+            fix: "Select a valid project using select_project or specify a correct lcp_path.",
+        });
+        return { ok: false, problems, connection: "" };
+    }
+    const connInfo = resolveConnection(lcpPath, explicitConn);
+    if (!connInfo.ip) {
+        problems.push({
+            code: "NO_IP_RESOLVED",
+            message: "Could not resolve an IP address for the connection.",
+            fix: "Provide an explicit connection string (e.g. TCPIP:10.195.0.50) or set the target IP using set_target_ip.",
+        });
+        return { ok: false, problems, connection: connInfo.connection };
+    }
+    const port = connInfo.port ?? 1954;
+    const reachable = await pingHost(connInfo.ip, port, 2000);
+    if (!reachable) {
+        problems.push({
+            code: "HOST_UNREACHABLE",
+            message: `PLC host at ${connInfo.ip} is unreachable on port ${port}.`,
+            fix: "Ensure the PLC is powered on and connected to the network. Verify the IP using lasal_status or set the correct IP.",
+        });
+    }
+    return {
+        ok: problems.length === 0,
+        problems,
+        connection: connInfo.connection,
+        ip: connInfo.ip,
+    };
+}
+export async function preflightHmi(lvpPath, explicitConn) {
+    const problems = [];
+    if (!existsSync(lvpPath)) {
+        problems.push({
+            code: "LVP_NOT_FOUND",
+            message: `VISUDesigner LVP file does not exist at ${lvpPath}`,
+            fix: "Verify that the VISUDesigner project path is correct.",
+        });
+        return { ok: false, problems, connection: "" };
+    }
+    if (!explicitConn) {
+        problems.push({
+            code: "NO_CONN_SPECIFIED",
+            message: "No connection string specified for HMI download.",
+            fix: "Specify a visu_connection parameter.",
+        });
+        return { ok: false, problems, connection: "" };
+    }
+    let ip;
+    let port = 1954;
+    const { ip: parsedIp, port: parsedPort } = parseConnectionTarget(explicitConn);
+    ip = parsedIp;
+    if (parsedPort)
+        port = parsedPort;
+    if (!ip) {
+        problems.push({
+            code: "INVALID_HMI_CONN",
+            message: `Invalid HMI connection string: ${explicitConn}`,
+            fix: "Provide a valid HMI connection string, e.g. 'TCPIP:10.195.0.51'.",
+        });
+        return { ok: false, problems, connection: explicitConn };
+    }
+    const reachable = await pingHost(ip, port, 2000);
+    if (!reachable) {
+        problems.push({
+            code: "HMI_UNREACHABLE",
+            message: `HMI host at ${ip} is unreachable on port ${port}.`,
+            fix: "Ensure the HMI is powered on and connected to the network. Verify the IP using lasal_status.",
+        });
+    }
+    return {
+        ok: problems.length === 0,
+        problems,
+        connection: explicitConn,
+        ip,
+    };
+}

package/dist/utils/projectScanner.js

@@ -0,0 +1,212 @@
+import { existsSync, readdirSync, statSync, readFileSync } from "fs";
+import { join, dirname, resolve, basename } from "path";
+import { XMLParser } from "fast-xml-parser";
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    parseAttributeValue: false,
+    isArray: (name) => name === "File" || name === "SlnClassProject" || name === "SlnVISUDesignerProject",
+});
+function readLatin1(path) {
+    return readFileSync(path, "latin1");
+}
+/** Parse an .lsm file and all referenced .lss files to build a solution map. */
+export function parseSolution(lsmPath) {
+    const lsmDir = dirname(lsmPath);
+    const lsmContent = readLatin1(lsmPath);
+    const doc = parser.parse(lsmContent);
+    const solution = doc.Solution ?? {};
+    const stationFiles = solution.SlnStationFiles?.File ?? [];
+    const stations = [];
+    for (const sf of stationFiles) {
+        if (!sf["@_Path"])
+            continue;
+        const lssPath = resolve(lsmDir, sf["@_Path"].replace(/\\/g, "/"));
+        if (!existsSync(lssPath))
+            continue;
+        const station = parseLss(lssPath);
+        stations.push(station);
+    }
+    return { lsmPath, stations };
+}
+/** Parse a .lss file to extract connection info and project paths. */
+export function parseLss(lssPath) {
+    const lssDir = dirname(lssPath);
+    const content = readLatin1(lssPath);
+    const doc = parser.parse(content);
+    const stn = doc.SlnStation ?? {};
+    const tcpip = stn.OnlineConnectionInfo?.TCPIP ?? {};
+    const lcpPaths = [];
+    const lvpPaths = [];
+    const projects = stn.SlnProjects ?? {};
+    for (const cp of (projects.SlnClassProject ?? [])) {
+        if (cp["@_File"]) {
+            const abs = resolve(lssDir, cp["@_File"].replace(/\\/g, "/"));
+            if (existsSync(abs))
+                lcpPaths.push(abs);
+        }
+    }
+    for (const vp of (projects.SlnVISUDesignerProject ?? [])) {
+        if (vp["@_File"]) {
+            const abs = resolve(lssDir, vp["@_File"].replace(/\\/g, "/"));
+            if (existsSync(abs))
+                lvpPaths.push(abs);
+        }
+    }
+    return {
+        name: stn["@_Name"] ?? basename(lssPath, ".lss"),
+        lssPath,
+        ip: tcpip["@_IP"],
+        port: tcpip["@_PORT"],
+        ssltls: tcpip["@_SSLTLS"],
+        lcpPaths,
+        lvpPaths,
+    };
+}
+/** Locate the .lsm file for a solution directory. */
+export function findLsmPath(solutionDir) {
+    const name = basename(solutionDir);
+    const direct = join(solutionDir, `${name}.lsm`);
+    if (existsSync(direct))
+        return direct;
+    // Fall back: search for any .lsm in the directory
+    try {
+        for (const f of readdirSync(solutionDir)) {
+            if (f.endsWith(".lsm"))
+                return join(solutionDir, f);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}
+/** Resolve all .lcp files in a solution directory (via .lsm + .lss), or fall back to filesystem scan. */
+export function findLcpFiles(solutionDir) {
+    const lsmPath = findLsmPath(solutionDir);
+    if (lsmPath) {
+        const solution = parseSolution(lsmPath);
+        const paths = solution.stations.flatMap((s) => s.lcpPaths);
+        if (paths.length > 0)
+            return paths;
+    }
+    // Fallback: filesystem search under Stations/
+    return findFilesDeep(join(solutionDir, "Stations"), ".lcp");
+}
+/** Resolve all .lvp files in a solution directory (via .lsm + .lss), or fall back to filesystem scan. */
+export function findLvpFiles(solutionDir) {
+    const lsmPath = findLsmPath(solutionDir);
+    if (lsmPath) {
+        const solution = parseSolution(lsmPath);
+        const paths = solution.stations.flatMap((s) => s.lvpPaths);
+        if (paths.length > 0)
+            return paths;
+    }
+    return findFilesDeep(join(solutionDir, "Stations"), ".lvp");
+}
+function findFilesDeep(dir, ext) {
+    const results = [];
+    if (!existsSync(dir))
+        return results;
+    function walk(d) {
+        for (const entry of readdirSync(d)) {
+            const full = join(d, entry);
+            try {
+                if (statSync(full).isDirectory())
+                    walk(full);
+                else if (entry.endsWith(ext))
+                    results.push(full);
+            }
+            catch {
+                /* skip inaccessible */
+            }
+        }
+    }
+    walk(dir);
+    return results;
+}
+/**
+ * Read the VISUDesigner station manager mapping (name -> stationId) from a .lvp's
+ * Stations/Stations.json. Returns e.g. { PLC: 10, HMI: 255, Local: 0 }.
+ */
+export function readVisuStationIds(lvpPath) {
+    const result = {};
+    try {
+        const lvpDir = dirname(lvpPath);
+        const file = join(lvpDir, "Stations", "Stations.json");
+        if (!existsSync(file))
+            return result;
+        const doc = JSON.parse(readFileSync(file, "utf-8"));
+        if (!Array.isArray(doc?.stations))
+            return result;
+        for (const st of doc.stations) {
+            if (!st || typeof st !== "object")
+                continue;
+            const stRec = st;
+            const name = typeof stRec.name === "string" ? stRec.name : undefined;
+            const id = typeof stRec.stationId === "number"
+                ? stRec.stationId
+                : typeof stRec.stationId === "string"
+                    ? parseInt(stRec.stationId, 10)
+                    : NaN;
+            if (name && !isNaN(id))
+                result[name] = id;
+        }
+    }
+    catch { }
+    return result;
+}
+/** Read the current TCPIP connection from a .lss file (IP + port). */
+export function readLssConnection(lssPath) {
+    if (!existsSync(lssPath))
+        return { error: `LSS file not found: ${lssPath}` };
+    try {
+        const content = readLatin1(lssPath);
+        const m = content.match(/<TCPIP\s[^>]*?IP="([^"]*)"[^>]*?PORT="([^"]*)"/);
+        if (m?.[1] && m?.[2])
+            return { ip: m[1], port: m[2] };
+        const m2 = content.match(/<TCPIP\s[^>]*?IP="([^"]*)"/);
+        if (m2?.[1])
+            return { ip: m2[1], port: "1954" };
+        return { error: `No <TCPIP .../> element found in ${lssPath}` };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { error: `Failed to parse ${lssPath}: ${msg}` };
+    }
+}
+/** Surgically update the TCPIP IP (and optionally port/ssltls) in a .lss file, byte-preserving everything else. */
+export function updateLssConnection(lssPath, updates) {
+    let content = readLatin1(lssPath);
+    const tcpipRe = /(<TCPIP\s[^>]*?>)/s;
+    const m = tcpipRe.exec(content);
+    if (!m) {
+        // No <TCPIP> element yet (e.g. a Local/simulation station) — insert one
+        // right after the <SlnStation ...> opening tag.
+        const stationRe = /(<SlnStation\s[^>]*>)/s;
+        const sm = stationRe.exec(content);
+        if (!sm)
+            throw new Error(`No <SlnStation ...> element found in ${lssPath}`);
+        const tag = `<OnlineConnectionInfo>\n\t\t<TCPIP ConfigName="MCP" BUS="3" Password="" IP="${updates.ip ?? "127.0.0.1"}" PORT="${updates.port ?? "1954"}" SomeFlags="0" PLCID="" Repeater="0" SSLTLS="${updates.ssltls ?? "0"}" Favorite="0"/>\n\t</OnlineConnectionInfo>`;
+        content = content.slice(0, sm.index + sm[1].length) + "\n\t" + tag + content.slice(sm.index + sm[1].length);
+        writeFileSync(lssPath, content, "latin1");
+        return;
+    }
+    let tag = m[1];
+    if (updates.ip !== undefined)
+        tag = setAttr(tag, "IP", updates.ip);
+    if (updates.port !== undefined)
+        tag = setAttr(tag, "PORT", updates.port);
+    if (updates.ssltls !== undefined)
+        tag = setAttr(tag, "SSLTLS", updates.ssltls);
+    content = content.slice(0, m.index) + tag + content.slice(m.index + m[1].length);
+    writeFileSync(lssPath, content, "latin1");
+}
+function setAttr(tag, name, value) {
+    const re = new RegExp(`(\\b${name}\\s*=\\s*")[^"]*(")`);
+    if (re.test(tag))
+        return tag.replace(re, `$1${value}$2`);
+    // Attribute not present — insert before the closing >
+    return tag.replace(/(\/?>)$/, ` ${name}="${value}"$1`);
+}
+import { writeFileSync } from "fs";

package/dist/utils/resolvePaths.js

@@ -0,0 +1,46 @@
+import { existsSync } from "fs";
+import { join, basename } from "path";
+import { readState } from "../state.js";
+import { findLcpFiles, findLvpFiles } from "./projectScanner.js";
+export function resolveLcpPath(lcpPath) {
+    if (lcpPath) {
+        if (!existsSync(lcpPath))
+            return { error: `File not found: ${lcpPath}` };
+        return { path: lcpPath };
+    }
+    const state = readState();
+    if (!state.currentProject)
+        return { error: "No project selected. Call select_project first." };
+    // Legacy flat layout: {dir}/{name}.lcp
+    const name = basename(state.currentProject);
+    const direct = join(state.currentProject, `${name}.lcp`);
+    if (existsSync(direct))
+        return { path: direct };
+    // Multi-station layout: search via .lsm → .lss
+    const found = findLcpFiles(state.currentProject);
+    if (found.length === 0)
+        return { error: `No .lcp files found in ${state.currentProject}` };
+    if (found.length === 1)
+        return { path: found[0] };
+    return {
+        error: `Multiple .lcp stations found — specify lcp_path:\n` + found.map((f) => `  ${f}`).join("\n"),
+    };
+}
+export function resolveLvpPath(lvpPath) {
+    if (lvpPath) {
+        if (!existsSync(lvpPath))
+            return { error: `File not found: ${lvpPath}` };
+        return { path: lvpPath };
+    }
+    const state = readState();
+    if (!state.currentProject)
+        return { error: "No project selected. Call select_project first." };
+    const found = findLvpFiles(state.currentProject);
+    if (found.length === 0)
+        return { error: `No .lvp files found in ${state.currentProject}` };
+    if (found.length === 1)
+        return { path: found[0] };
+    return {
+        error: `Multiple .lvp stations found — specify lvp_path:\n` + found.map((f) => `  ${f}`).join("\n"),
+    };
+}

package/dist/utils/respond.js

@@ -0,0 +1,14 @@
+export function respond(body) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+        ...(body.ok ? {} : { isError: true }),
+    };
+}
+export function fail(message, hints, extra) {
+    return respond({
+        ok: false,
+        error: message,
+        hints,
+        ...extra,
+    });
+}

package/dist/utils/scriptRunner.js

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync } from "fs";
+import { execFile } from "child_process";
+const HINT_TABLE = [
+    {
+        pattern: /connect|timeout|1954|offline/i,
+        hint: "PLC or HMI is unreachable. Check network/power, target IP with lasal_status, or set it via set_target_ip.",
+    },
+    {
+        pattern: /no project|load project|failed to load/i,
+        hint: "Project failed to load. Verify the project path or call select_project.",
+    },
+    {
+        pattern: /lock|locked|sharing violation|permission denied/i,
+        hint: "Project files or engine locked. Close CLASS 2 or VISUDesigner via manage_class2/manage_visudesigner close.",
+    },
+    {
+        pattern: /compile|syntax error|declaration/i,
+        hint: "Compilation failed. Check the compiler log for syntax errors.",
+    },
+    {
+        pattern: /channel not found|not exist|unknown channel/i,
+        hint: "Channel not found. Check ObjectName.ChannelName spelling/casing via inspect_project.",
+    },
+];
+function executeEngine(exe, args, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = execFile(exe, args, {
+            timeout: timeoutMs,
+            windowsHide: true,
+            maxBuffer: 10 * 1024 * 1024,
+        }, (error, _stdout, stderr) => {
+            if (error) {
+                const timedOut = error.killed || error.code === "ETIMEDOUT";
+                resolve({
+                    exitCode: error.code !== undefined && typeof error.code === "number" ? error.code : (child.exitCode ?? 1),
+                    timedOut,
+                    stderr: stderr?.toString() ?? "",
+                });
+            }
+            else {
+                resolve({ exitCode: 0, timedOut: false, stderr: "" });
+            }
+        });
+    });
+}
+function parseLog(logPath, encoding, hasFailed) {
+    const errors = [];
+    const warnings = [];
+    const logTail = [];
+    if (!existsSync(logPath))
+        return { errors, warnings, logTail, logContent: "" };
+    let logContent = "";
+    try {
+        logContent = readFileSync(logPath, encoding);
+        const lines = logContent.split(/\r?\n/);
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            if (trimmed.includes("(ERROR)") || trimmed.includes("(FATAL)")) {
+                errors.push(trimmed);
+            }
+            else if (trimmed.includes("(WARN)")) {
+                warnings.push(trimmed);
+            }
+        }
+        if (hasFailed) {
+            logTail.push(...lines
+                .filter((l) => l.trim())
+                .slice(-15)
+                .map((l) => l.trim()));
+        }
+    }
+    catch { }
+    return { errors, warnings, logTail, logContent };
+}
+function parseSteps(stepsPath, expectedSteps) {
+    const confirmed = new Set();
+    if (existsSync(stepsPath)) {
+        try {
+            const stepsContent = readFileSync(stepsPath, "utf-8");
+            for (const line of stepsContent.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (trimmed.startsWith("STEP ") && trimmed.endsWith(" OK")) {
+                    confirmed.add(trimmed.slice(5, -3).trim());
+                }
+            }
+        }
+        catch { }
+    }
+    const steps = [];
+    let hasFailed = false;
+    for (const label of expectedSteps) {
+        if (confirmed.has(label)) {
+            steps.push({ label, status: "ok" });
+        }
+        else {
+            steps.push({ label, status: hasFailed ? "not_reached" : "failed" });
+            hasFailed = true;
+        }
+    }
+    return { steps, allConfirmed: expectedSteps.every((s) => confirmed.has(s)) };
+}
+export async function runEngineScript(scriptPath, opts, logPath) {
+    const start = Date.now();
+    const args = opts.argsFor(scriptPath);
+    const { exitCode, timedOut, stderr } = await executeEngine(opts.exe, args, opts.timeoutMs);
+    if (timedOut || exitCode !== 0) {
+        opts.killOnFailure();
+    }
+    const errors = [];
+    if (timedOut) {
+        errors.push(`Engine execution timed out after ${opts.timeoutMs / 1000}s.`);
+    }
+    else if (stderr.trim()) {
+        errors.push(...stderr
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean));
+    }
+    const durationMs = Date.now() - start;
+    const hasFailed = exitCode !== 0 || errors.length > 0 || timedOut;
+    const log = parseLog(logPath, opts.logEncoding, hasFailed);
+    errors.push(...log.errors);
+    const { steps, allConfirmed } = parseSteps(opts.stepsPath, opts.expectedSteps);
+    if (!allConfirmed && log.errors.length === 0 && !timedOut) {
+        const lastConfirmed = [...opts.expectedSteps]
+            .reverse()
+            .find((s) => steps.find((st) => st.label === s && st.status === "ok"));
+        const firstMissing = opts.expectedSteps.find((s) => !steps.find((st) => st.label === s && st.status === "ok"));
+        errors.push(`Engine exited but not all expected operations completed. ` +
+            `Last confirmed: ${lastConfirmed ?? "(none)"}. First missing: ${firstMissing ?? "(unknown)"}.`);
+    }
+    const hints = [];
+    if (timedOut) {
+        hints.push("Timed out — for large projects raise the timeout via the tool's timeout_s argument or LASAL_MCP_TIMEOUT_* environment variables.");
+    }
+    const hasFailed2 = exitCode !== 0 || errors.length > 0 || timedOut || !allConfirmed;
+    if (hasFailed2) {
+        for (const mapping of HINT_TABLE) {
+            const matched = errors.some((err) => mapping.pattern.test(err)) ||
+                log.warnings.some((warn) => mapping.pattern.test(warn)) ||
+                log.logTail.some((line) => mapping.pattern.test(line));
+            if (matched && !hints.includes(mapping.hint)) {
+                hints.push(mapping.hint);
+            }
+        }
+    }
+    return {
+        ok: exitCode === 0 && errors.length === 0 && !timedOut && allConfirmed,
+        exitCode,
+        timedOut,
+        steps,
+        errors,
+        warnings: log.warnings,
+        logTail: log.logTail,
+        logPath,
+        durationMs,
+        hints,
+    };
+}