mcp-for-i 0.1.13 → 0.2.0

package/dist/ibmi/client.js

@@ -3,8 +3,10 @@ import fs from "fs/promises";
 import path from "path";
 import { Tools } from "./Tools.js";
 import { IBMiContent } from "./IBMiContent.js";
+import { checkHostKey } from "./knownHosts.js";
+import { DEFAULT_MAPEPIRE_PORT, PersistentSqlJob, isQualifiedJobName, normalizeMapepireMode } from "./sqlJob.js";
+import { desiredLibraryList, existingLibrariesSql, invalidNamesWarning, libraryListCommand, libraryNamesFromRows, qshLibraryListPrefix, referencedLibraries, resolveAgainstExisting } from "./libraryList.js";
 const LOCALE = "LC_ALL=EN_US.UTF-8";
-const SQL_HEREDOC_TAG = "__MCP_FOR_I_SQL__";
 export class IBMiClient {
     client;
     content;
@@ -14,10 +16,25 @@ export class IBMiClient {
     currentPort = 22;
     currentUser = "";
     currentConnectionName = "";
+    /** Long-lived SQL job (Mapepire) shared by SQL and CL calls; see sqlJob.ts. */
+    sqlJob;
     config;
-    constructor(config) {
+    connection;
+    /**
+     * The configured library list checked for QZDFMDB2 and qsh jobs, which start
+     * fresh on every call; re-checked when the setting changes.
+     */
+    fallbackLibraryList;
+    constructor(config, options = {}) {
         this.config = config;
         this.content = new IBMiContent(this);
+        this.sqlJob = new PersistentSqlJob({
+            getConfig: () => this.config,
+            getOpenRequest: () => this.sqlJobOpenRequest(),
+            factory: options.sqlJobFactory,
+            cancelStatement: jobName => this.cancelSqlInJob(jobName),
+            fallbackLibraryListWarning: () => this.fallbackLibraryList?.resolved.warning
+        });
     }
     getConfig() {
         return this.config;
@@ -47,20 +64,46 @@ export class IBMiClient {
         this.currentUser = connection.username;
         this.currentConnectionName = connection.name;
         this.client = new NodeSSH();
-        await this.client.connect({
-            host: connection.host,
-            port: connection.port,
-            username: connection.username,
-            password: connection.password,
-            privateKey: connection.privateKeyPath ? await fs.readFile(connection.privateKeyPath, "utf8") : undefined,
-            keepaliveInterval: connection.keepaliveInterval,
-            readyTimeout: connection.readyTimeout,
-            debug: connection.sshDebug ? (msg) => process.stderr.write(`[ssh] ${msg}\n`) : undefined
-        });
-        await this.detectRemoteFeatures();
-        await this.loadDefaultLibraryList();
+        // Trust on first use: the host key is recorded on the first connection and
+        // must match on every later one (see docs/security.md).
+        let hostKeyError;
+        const hostVerifier = (key, verify) => {
+            checkHostKey({ host: connection.host, port: connection.port, key })
+                .then(() => verify(true))
+                .catch((err) => {
+                hostKeyError = err;
+                verify(false);
+            });
+        };
+        try {
+            await this.client.connect({
+                host: connection.host,
+                port: connection.port,
+                username: connection.username,
+                password: connection.password,
+                privateKey: connection.privateKeyPath ? await fs.readFile(connection.privateKeyPath, "utf8") : undefined,
+                keepaliveInterval: connection.keepaliveInterval,
+                readyTimeout: connection.readyTimeout,
+                hostVerifier,
+                debug: connection.sshDebug ? (msg) => process.stderr.write(`[ssh] ${msg}\n`) : undefined
+            });
+        }
+        catch (err) {
+            this.client.dispose();
+            this.client = undefined;
+            throw hostKeyError ?? err;
+        }
+        this.connection = connection;
+        await Promise.all([
+            this.detectRemoteFeatures(),
+            this.loadDefaultLibraryList()
+        ]);
     }
     async disconnect() {
+        // Close the SQL job first: in single mode it runs on this SSH session.
+        await this.sqlJob.close().catch(() => undefined);
+        this.connection = undefined;
+        this.fallbackLibraryList = undefined;
         if (this.client) {
             this.client.dispose();
             this.client = undefined;
@@ -110,19 +153,161 @@ export class IBMiClient {
             command
         };
     }
-    async runSQL(statements) {
+    /**
+     * Runs SQL. Uses the connection's persistent Mapepire job when it is
+     * available (so library list changes and QTEMP carry over), otherwise a new
+     * QZDFMDB2 job. Either way the connection's configured library list and
+     * current library are in effect. When `signal` aborts, a statement running
+     * in the persistent job is cancelled on the IBM i.
+     */
+    async runSQL(statements, options = {}) {
+        const rows = await this.sqlJob.runSql(statements, options);
+        if (rows)
+            return rows;
+        return this.runSqlQzdfmdb2(statements);
+    }
+    /**
+     * Runs a CL command where it affects later SQL and CL: in the persistent
+     * job when there is one, otherwise with `system` in a qsh job.
+     */
+    async runCL(command, options = {}) {
+        try {
+            const messages = await this.sqlJob.runCl(command, options);
+            if (messages) {
+                const stdout = messages.map(m => (m.id ? `${m.id}: ${m.text}` : m.text)).join("\n");
+                return { code: 0, signal: null, stdout, stderr: "", command };
+            }
+        }
+        catch (err) {
+            return { code: 1, signal: null, stdout: "", stderr: err?.message || String(err), command };
+        }
+        // A new job: the qsh liblist builtin sets the configured library list,
+        // which the job `system` starts inherits. Single-quoted for qsh, so
+        // nothing in the command is expanded.
+        const resolved = await this.resolveFallbackLibraryList();
+        const prefix = resolved ? qshLibraryListPrefix(resolved, this.defaultUserLibraries) : "";
+        const run = `system ${Tools.shellQuote(command)}`;
+        return this.sendQsh({ command: prefix ? `${prefix}; ${run}` : run });
+    }
+    /**
+     * Puts the configured library list in effect now (ibmi.libl.* applyToJob).
+     * In the persistent job it is applied immediately; QZDFMDB2 and qsh jobs
+     * start fresh, so there it is checked now and applied on every call.
+     */
+    async applyConfiguredLibraryList() {
+        const result = await this.sqlJob.reapplyLibraryList();
+        if (result)
+            return { applied: "job", ...(result.warning ? { warning: result.warning } : {}) };
+        this.fallbackLibraryList = undefined;
+        const resolved = await this.resolveFallbackLibraryList();
+        return { applied: "per-call", ...(resolved?.warning ? { warning: resolved.warning } : {}) };
+    }
+    /**
+     * The configured library list as it can be applied in a new job. Checked
+     * once per setting value by running the CHGLIBL in a QZDFMDB2 job; when it
+     * fails (CHGLIBL fails entirely when one library is missing) the libraries
+     * that do not exist are left out, so a bad entry cannot fail every batch.
+     */
+    async resolveFallbackLibraryList() {
+        const desired = desiredLibraryList(this.config);
+        const cached = this.fallbackLibraryList;
+        if (cached && cached.signature === desired.signature)
+            return cached.resolved;
+        const full = libraryListCommand(desired.libraries, desired.currentLibrary);
+        const invalid = invalidNamesWarning(desired);
+        let resolved = {
+            command: full,
+            libraries: desired.libraries,
+            currentLibrary: desired.currentLibrary,
+            ...(invalid ? { warning: invalid } : {})
+        };
+        if (full) {
+            try {
+                await this.runQzdfmdb2Batch(`@${full}`);
+            }
+            catch (firstErr) {
+                if (!this.client)
+                    return undefined;
+                const firstError = firstErr?.message || String(firstErr);
+                try {
+                    const names = referencedLibraries(desired);
+                    let rows;
+                    try {
+                        rows = await this.runQzdfmdb2Batch(existingLibrariesSql(names));
+                    }
+                    catch {
+                        // Older releases do not know *ALLSIMPLE.
+                        rows = await this.runQzdfmdb2Batch(existingLibrariesSql(names, false));
+                    }
+                    resolved = resolveAgainstExisting(desired, libraryNamesFromRows(rows));
+                    if (resolved.command)
+                        await this.runQzdfmdb2Batch(`@${resolved.command}`);
+                    if (!resolved.warning)
+                        resolved.warning = `${full} failed: ${firstError}`;
+                }
+                catch (err) {
+                    if (!this.client)
+                        return undefined;
+                    resolved = { libraries: [], warning: `Configured library list not applied: ${full} failed: ${firstError}` };
+                }
+            }
+        }
+        this.fallbackLibraryList = { signature: desired.signature, resolved };
+        return resolved;
+    }
+    sqlJobOpenRequest() {
+        if (!this.client || !this.connection)
+            return undefined;
+        const port = Number(this.config.mapepirePort);
+        return {
+            host: this.connection.host,
+            username: this.connection.username,
+            password: this.connection.password,
+            ssh: this.client,
+            mode: normalizeMapepireMode(this.config.mapepireMode),
+            port: Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_MAPEPIRE_PORT,
+            serverPath: this.config.mapepireServerPath || undefined,
+            javaPath: this.config.mapepireJavaPath || undefined,
+            probeTimeoutMs: 4000,
+            sendCommand: options => this.sendCommand(options)
+        };
+    }
+    /** QSYS2.CANCEL_SQL runs in a separate QZDFMDB2 job, since the target job is busy. */
+    async cancelSqlInJob(jobName) {
+        if (!isQualifiedJobName(jobName))
+            throw new Error(`Invalid job name: ${jobName}`);
+        await this.runQzdfmdb2Batch(`CALL QSYS2.CANCEL_SQL('${jobName.toUpperCase()}')`);
+    }
+    /**
+     * Runs SQL in a new QZDFMDB2 job. The configured library list is set first,
+     * in the same job, by a leading CHGLIBL (libraries that do not exist are
+     * left out so it cannot fail the batch).
+     */
+    async runSqlQzdfmdb2(statements) {
+        if (!Tools.fixSQL(statements, true).trim())
+            return [];
+        const resolved = await this.resolveFallbackLibraryList();
+        const command = resolved?.command;
+        return this.runQzdfmdb2Batch(command ? `@${command}\n${statements}` : statements);
+    }
+    /** Runs SQL in a new QZDFMDB2 job as it is (no library list). */
+    async runQzdfmdb2Batch(statements) {
         const input = Tools.fixSQL(statements, true).trim();
         if (!input)
             return [];
-        const ccsid = this.config.sqlJobCcsid ?? 1208;
-        const command = [
-            `system "CHGJOB CCSID(${ccsid})"`,
-            `cat <<'${SQL_HEREDOC_TAG}' | system "call QSYS/QZDFMDB2 PARM('-d' '-i' '-t')"`,
-            input,
-            SQL_HEREDOC_TAG
-        ].join("\n");
-        const output = await this.sendQsh({
-            command,
+        const ccsid = Number(this.config.sqlJobCcsid ?? 1208);
+        if (!Number.isInteger(ccsid) || ccsid < 1 || ccsid > 65535) {
+            throw new Error(`Invalid sqlJobCcsid: ${this.config.sqlJobCcsid}`);
+        }
+        // The SQL text is never part of the shell command: it goes to QZDFMDB2 on
+        // the SSH channel's stdin. CHGJOB reads /dev/null so it cannot consume it.
+        const script = [
+            `system "CHGJOB CCSID(${ccsid})" </dev/null`,
+            `system "call QSYS/QZDFMDB2 PARM('-d' '-i' '-t')"`
+        ].join("; ");
+        const output = await this.sendCommand({
+            command: `${LOCALE} /QOpenSys/usr/bin/qsh -c ${Tools.shellQuote(script)}`,
+            stdin: `${input}\n`,
             env: { QIBM_PASE_CCSID: String(ccsid) }
         });
         if (output.stdout && output.stdout.trim()) {
@@ -209,13 +394,17 @@ export class IBMiClient {
             stat: ["/QOpenSys/pkgs/bin/stat", "/usr/bin/stat"],
             ls: ["/QOpenSys/pkgs/bin/ls", "/usr/bin/ls"]
         };
-        for (const [name, paths] of Object.entries(featurePaths)) {
-            for (const p of paths) {
-                const res = await this.sendCommand({ command: `test -x ${p} && echo ${p}` });
-                if (res.stdout.trim()) {
-                    this.remoteFeatures[name] = p;
-                    break;
-                }
+        const discoveryCommand = Object.entries(featurePaths).map(([name, paths]) => `for p in ${paths.map(Tools.shellQuote).join(" ")}; do ` +
+            `if [ -x "$p" ]; then printf '%s=%s\\n' ${Tools.shellQuote(name)} "$p"; break; fi; done`).join("; ");
+        const result = await this.sendCommand({ command: discoveryCommand });
+        for (const line of result.stdout.split(/\r?\n/)) {
+            const separator = line.indexOf("=");
+            if (separator <= 0)
+                continue;
+            const name = line.slice(0, separator);
+            const featurePath = line.slice(separator + 1);
+            if (Object.hasOwn(featurePaths, name) && featurePath) {
+                this.remoteFeatures[name] = featurePath;
             }
         }
         // QZDFMDB2.PGM is in QSYS/QZDFMDB2 by default; treat as present

package/dist/ibmi/evfevent.js

@@ -0,0 +1,256 @@
+/**
+ * Parser for IBM i compiler events files (EVFEVENT), written by compilers
+ * when OPTION(*EVENTF) is used.
+ *
+ * Each record starts with a record type padded to 10 characters, followed by
+ * blank separated fixed-width fields:
+ *
+ *   TIMESTAMP  rev yyyymmddhhmmss
+ *   PROCESSOR  rev fileid(000) outputFileId
+ *   FILEID     rev fileid(3) includedAtLine(6) nameLength(3) name timestamp(14) tempFlag(1)
+ *   FILEEND    rev fileid(3) lineCount(6)
+ *   EXPANSION  rev fileid(3) inStart(6) inEnd(6) outStart(6) outEnd(6)
+ *   ERROR      rev fileid(3) annotClass(1) stmtLine(6) startLine(6) startCol(3+)
+ *              endLine(6) endCol(3+) msgid(7) sevChar(1) sev(2) msgLength(3) text
+ *
+ * A new PROCESSOR record starts a new pass (for example the RPG compiler run
+ * after the SQL precompiler) and file ids restart in each pass. Errors that a
+ * later pass reports against a temporary file (temp flag 1, such as
+ * QTEMP/QSQLTEMP1) are mapped back to the original source through the
+ * EXPANSION records of the previous pass.
+ */
+const ERROR_RE = /^ERROR\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+([A-Za-z])\s+(\d+)\s+(\d+)(?:\s(.*))?$/;
+const FILEID_RE = /^FILEID\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/;
+const FILEEND_RE = /^FILEEND\s+(\d+)\s+(\d+)(?:\s+(\d+))?/;
+const EXPANSION_RE = /^EXPANSION\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/;
+const TIMESTAMP_RE = /^TIMESTAMP\s+(\d+)\s+(\d+)/;
+const PROCESSOR_RE = /^PROCESSOR\b/;
+const KNOWN_RECORD_RE = /^(MAPDEFINE|MAPSTART|MAPEND|FEEDBACK|PROGRAM)\b/;
+export function severityFrom(char, level) {
+    switch (char.toUpperCase()) {
+        case "I": return "INFO";
+        case "W": return "WARN";
+        case "E":
+        case "S":
+        case "T":
+        case "U":
+        case "C": return "ERROR";
+    }
+    if (level < 10)
+        return "INFO";
+    if (level < 20)
+        return "WARN";
+    return "ERROR";
+}
+/** Split a FILEID name into library/file/member or an IFS path. */
+export function describeEvfFile(name) {
+    const qsys = name.match(/^([^/()\s]+)\/([^/()\s]+)\(([^()\s]+)\)$/);
+    if (qsys)
+        return { library: qsys[1].toUpperCase(), sourceFile: qsys[2].toUpperCase(), member: qsys[3].toUpperCase() };
+    const qsysPath = name.match(/^\/QSYS\.LIB\/([^/]+)\.LIB\/([^/]+)\.FILE\/([^/]+)\.MBR$/i);
+    if (qsysPath)
+        return { library: qsysPath[1].toUpperCase(), sourceFile: qsysPath[2].toUpperCase(), member: qsysPath[3].toUpperCase() };
+    if (name.startsWith("/"))
+        return { path: name };
+    return {};
+}
+export function parseEvfevent(content) {
+    const lines = Array.isArray(content) ? content : String(content ?? "").split(/\r?\n/);
+    const processors = [];
+    let current;
+    let timestamp;
+    let unparsedLines = 0;
+    const raw = [];
+    const ensureProcessor = () => {
+        if (!current) {
+            current = { index: processors.length + 1, files: new Map(), expansions: [] };
+            processors.push(current);
+        }
+        return current;
+    };
+    for (const rawLine of lines) {
+        const line = String(rawLine ?? "").replace(/\s+$/, "");
+        if (!line.trim())
+            continue;
+        const record = line.trimStart();
+        if (PROCESSOR_RE.test(record)) {
+            current = { index: processors.length + 1, files: new Map(), expansions: [] };
+            processors.push(current);
+            continue;
+        }
+        let match = record.match(TIMESTAMP_RE);
+        if (match) {
+            timestamp = timestamp || match[2];
+            continue;
+        }
+        match = record.match(FILEID_RE);
+        if (match) {
+            const proc = ensureProcessor();
+            const id = match[2];
+            const nameLength = Number(match[4]);
+            const rest = match[5];
+            let name;
+            let temp = false;
+            const tail = rest.match(/^(.*?)\s+(\d{14})\s+([01])\s*$/);
+            if (tail) {
+                name = tail[1].trim();
+                temp = tail[3] === "1";
+            }
+            else {
+                name = (nameLength > 0 ? rest.slice(0, nameLength) : rest).trim();
+                const flag = rest.slice(nameLength).trim().split(/\s+/).pop();
+                temp = flag === "1";
+            }
+            if (!proc.files.has(id)) {
+                proc.files.set(id, { id, name, includedAtLine: Number(match[3]), temp });
+                if (!proc.firstFileId)
+                    proc.firstFileId = id;
+            }
+            continue;
+        }
+        match = record.match(FILEEND_RE);
+        if (match) {
+            const file = current?.files.get(match[2]);
+            if (file && match[3] !== undefined)
+                file.lineCount = Number(match[3]);
+            continue;
+        }
+        match = record.match(EXPANSION_RE);
+        if (match) {
+            ensureProcessor().expansions.push({
+                fileId: match[2],
+                inStart: Number(match[3]),
+                inEnd: Number(match[4]),
+                outStart: Number(match[5]),
+                outEnd: Number(match[6])
+            });
+            continue;
+        }
+        match = record.match(ERROR_RE);
+        if (match) {
+            const proc = ensureProcessor();
+            const statementLine = Number(match[4]);
+            const startLine = Number(match[5]) || statementLine;
+            const endLine = Number(match[7]) || startLine;
+            const severityChar = match[10].toUpperCase();
+            const severityLevel = Number(match[11]);
+            const msgLength = Number(match[12]);
+            const restText = match[13] ?? "";
+            const text = (msgLength > 0 && restText.length > msgLength ? restText.slice(0, msgLength) : restText).trim();
+            raw.push({
+                processor: proc,
+                fileId: match[2],
+                diag: {
+                    line: startLine,
+                    column: Number(match[6]),
+                    endLine,
+                    endColumn: Number(match[8]),
+                    statementLine,
+                    msgid: match[9].toUpperCase(),
+                    severity: severityFrom(severityChar, severityLevel),
+                    severityChar,
+                    severityLevel,
+                    text,
+                    processor: proc.index
+                }
+            });
+            continue;
+        }
+        if (!KNOWN_RECORD_RE.test(record))
+            unparsedLines++;
+    }
+    const diagnostics = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        const diag = resolveDiagnostic(entry.processor, processors, entry.fileId, entry.diag);
+        const key = [diag.file, diag.line, diag.column, diag.msgid, diag.text].join("\u0000");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        diagnostics.push(diag);
+    }
+    const byFile = new Map();
+    for (const diag of diagnostics) {
+        let group = byFile.get(diag.file);
+        if (!group) {
+            group = { file: diag.file, ...describeEvfFile(diag.file), errors: [], counts: { errors: 0, warnings: 0, infos: 0 } };
+            byFile.set(diag.file, group);
+        }
+        group.errors.push(diag);
+        if (diag.severity === "ERROR")
+            group.counts.errors++;
+        else if (diag.severity === "WARN")
+            group.counts.warnings++;
+        else
+            group.counts.infos++;
+    }
+    const files = Array.from(byFile.values());
+    for (const group of files) {
+        group.errors.sort((a, b) => a.line - b.line || a.column - b.column);
+    }
+    return {
+        timestamp,
+        processors: processors.length,
+        files,
+        diagnostics,
+        summary: {
+            total: diagnostics.length,
+            errors: diagnostics.filter(d => d.severity === "ERROR").length,
+            warnings: diagnostics.filter(d => d.severity === "WARN").length,
+            infos: diagnostics.filter(d => d.severity === "INFO").length,
+            highestSeverity: diagnostics.reduce((max, d) => Math.max(max, d.severityLevel), 0)
+        },
+        unparsedLines
+    };
+}
+function resolveDiagnostic(proc, processors, fileId, diag) {
+    const file = proc.files.get(fileId);
+    const name = file?.name || `FILEID ${fileId}`;
+    if (!file?.temp)
+        return { ...diag, file: name };
+    // Errors against a temporary (expanded) file: map through the expansions
+    // recorded by the pass that produced it.
+    const previous = processors
+        .slice(0, processors.indexOf(proc))
+        .reverse()
+        .find(p => p.expansions.length > 0 || p.files.size > 0);
+    if (!previous?.firstFileId)
+        return { ...diag, file: name };
+    const mapLine = (line) => mapExpandedLine(previous, line);
+    const start = mapLine(diag.line);
+    const end = mapLine(diag.endLine);
+    const statement = mapLine(diag.statementLine || diag.line);
+    return {
+        ...diag,
+        file: start.file,
+        line: start.line,
+        endLine: end.file === start.file ? Math.max(end.line, start.line) : start.line,
+        statementLine: statement.file === start.file ? statement.line : start.line,
+        mappedFrom: { file: name, line: diag.line }
+    };
+}
+/** Map a line of a pass's output back to the original file and line. */
+function mapExpandedLine(proc, outputLine) {
+    const mainId = proc.firstFileId;
+    const nameOf = (id) => proc.files.get(id)?.name || `FILEID ${id}`;
+    let offset = 0;
+    const expansions = [...proc.expansions].sort((a, b) => a.outStart - b.outStart);
+    for (const exp of expansions) {
+        if (exp.outEnd < exp.outStart)
+            continue;
+        if (outputLine >= exp.outStart && outputLine <= exp.outEnd) {
+            if (exp.fileId !== mainId && exp.inStart > 0) {
+                // Included source copied line for line.
+                return { file: nameOf(exp.fileId), line: exp.inStart + (outputLine - exp.outStart) };
+            }
+            // Generated code: point at the statement it came from.
+            return { file: nameOf(exp.fileId), line: exp.inStart > 0 ? exp.inStart : Math.max(1, outputLine - offset) };
+        }
+        if (exp.outEnd < outputLine) {
+            const outputLength = exp.outEnd - exp.outStart + 1;
+            const replaced = exp.fileId === mainId && exp.inStart > 0 && exp.inEnd >= exp.inStart ? exp.inEnd - exp.inStart + 1 : 0;
+            offset += outputLength - replaced;
+        }
+    }
+    return { file: nameOf(mainId), line: Math.max(1, outputLine - offset) };
+}