deepdebug-local-agent 1.0.22 → 1.1.0

package/src/adapters/cobol/cobol-parser.js

@@ -0,0 +1,37 @@
+// src/adapters/cobol/cobol-parser.js
+// Multi-pattern parser surface for COBOL/JES2 spool exports. Each regex is
+// exported as a named const for isolated unit-testing (T-2-03-equivalent
+// mitigation surface). The `extractCobolCode` helper picks the first matching
+// pattern in priority order.
+//
+// Priority (highest first): SYSTEM COMPLETION CODE → SQLCODE → FILE STATUS →
+// ABEND CODE → IEF info code. The first three are hard error conditions; IEF
+// info codes are the lowest priority because the same line often carries
+// the actual completion code (e.g. `IEF450I ... ABEND=S0C7`) and the
+// system-completion match is more specific.
+
+export const COBOL_COMPLETION_REGEX = /SYSTEM COMPLETION CODE=([SU]?\w{3,4})/;
+export const COBOL_SQLCODE_REGEX = /SQLCODE\s*=?\s*(-?\d+)/;
+export const COBOL_IEF_REGEX = /\b(IEF\d{3}I)\b/;
+export const COBOL_FILE_STATUS_REGEX = /FILE STATUS\s+(\d+)/;
+export const COBOL_ABEND_CODE_REGEX = /ABEND CODE=(\w+)/;
+
+export function extractCobolCode(line) {
+  let m = line.match(COBOL_COMPLETION_REGEX);
+  if (m) {
+    const raw = m[1];
+    // System codes start with 'S' (system) or 'U' (user). 0C7 → S0C7
+    // normalization per IBM convention.
+    if (/^[SU]/.test(raw)) return raw;
+    return `S${raw}`;
+  }
+  m = line.match(COBOL_SQLCODE_REGEX);
+  if (m) return m[1]; // includes leading '-' for negative codes
+  m = line.match(COBOL_FILE_STATUS_REGEX);
+  if (m) return `FILE_STATUS_${m[1]}`;
+  m = line.match(COBOL_ABEND_CODE_REGEX);
+  if (m) return m[1];
+  m = line.match(COBOL_IEF_REGEX);
+  if (m) return m[1];
+  return null;
+}

package/src/adapters/cobol/index.js

@@ -0,0 +1,151 @@
+// src/adapters/cobol/index.js
+// CobolLogAdapter — watches arbitrary files in the configured JES2 spool
+// directory; emits 6-key error events. AD-1 lifecycle, AD-3 polling, AD-4
+// byte-position dedup with TAIL-on-startup default, AD-5 per-file ordering,
+// AD-6 CRLF tolerance + 80-col fixed-width column-1 preservation (z/OS spool
+// trap). T-2-01 mitigation: default polling interval 5000 ms.
+//
+// The glob is `*` (any file) — JES2 spool exports have arbitrary names.
+// This is broader than sibling adapters but the parser regexes are narrow
+// enough (SYSTEM COMPLETION CODE, SQLCODE, IEF, FILE STATUS, ABEND CODE)
+// that lines without any match are silently dropped.
+
+import { EventEmitter } from 'node:events';
+import { stat, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import chokidar from 'chokidar';
+import { extractCobolCode } from './cobol-parser.js';
+
+const ADAPTER = 'cobol';
+
+export class CobolLogAdapter extends EventEmitter {
+  constructor(config = {}) {
+    super();
+    this.spoolDir = config.spoolDir || '/var/spool/jes2';
+    this.interval = config.interval ?? 5000;
+    this.replayOnStart = config.replayOnStart === true;
+    this._watcher = null;
+    this._offsets = new Map(); // filePath → byte offset
+    this._inodes = new Map();  // filePath → inode
+    this._isRunning = false;
+  }
+
+  get isRunning() {
+    return this._isRunning;
+  }
+
+  async start() {
+    if (this._isRunning) return;
+    this._isRunning = true;
+
+    // Glob bound to any file in spool dir. depth:0 prevents recursion.
+    const glob = join(this.spoolDir, '*');
+
+    this._watcher = chokidar.watch(glob, {
+      usePolling: true,
+      interval: this.interval,
+      ignoreInitial: false, // we handle initial ourselves via TAIL seek
+      awaitWriteFinish: false,
+      depth: 0, // do not recurse into subdirs
+    });
+
+    const onAdd = async (filePath) => {
+      if (this.replayOnStart) {
+        this._offsets.set(filePath, 0);
+        // fall through to _readNew below
+      } else {
+        try {
+          const st = await stat(filePath);
+          this._offsets.set(filePath, st.size);
+          this._inodes.set(filePath, st.ino);
+          return; // TAIL mode — don't emit pre-existing content
+        } catch {
+          return;
+        }
+      }
+      this._readNew(filePath).catch(() => { /* ENOENT silence */ });
+    };
+
+    this._watcher.on('add', onAdd);
+    this._watcher.on('change', (fp) => {
+      this._readNew(fp).catch(() => { /* ENOENT silence */ });
+    });
+
+    // Swallow chokidar's own bubbled errors (e.g., watch-path ENOENT) —
+    // dual-layer suppression with the per-read try/catch ensures full
+    // ENOENT silence (canonical pattern from Plan 02-07).
+    this._watcher.on('error', () => {});
+  }
+
+  async stop() {
+    if (!this._isRunning) return;
+    this._isRunning = false;
+    if (this._watcher) {
+      await this._watcher.close().catch(() => {});
+      this._watcher = null;
+    }
+    this._offsets.clear();
+    this._inodes.clear();
+  }
+
+  async _readNew(filePath) {
+    let st;
+    try {
+      st = await stat(filePath);
+    } catch {
+      return; // ENOENT silence
+    }
+    if (!st.isFile()) return; // skip dirs that may surface from broad `*` glob
+
+    const lastOffset = this._offsets.get(filePath) ?? 0;
+    const lastInode = this._inodes.get(filePath);
+
+    // Rotation: inode changed OR size shrunk → reset to 0
+    if ((lastInode !== undefined && st.ino !== lastInode) || st.size < lastOffset) {
+      this._offsets.set(filePath, 0);
+      this._inodes.set(filePath, st.ino);
+      return this._readNew(filePath); // re-enter with offset=0
+    }
+    this._inodes.set(filePath, st.ino);
+
+    if (st.size <= lastOffset) return;
+
+    const fh = await open(filePath, 'r');
+    try {
+      const len = st.size - lastOffset;
+      const buf = Buffer.alloc(len);
+      await fh.read(buf, 0, len, lastOffset);
+      this._offsets.set(filePath, st.size);
+      const text = buf.toString('utf8');
+      // CRLF-tolerant split: \r?\n splits on either ending. The trailing
+      // \r is consumed by the regex so event.message is clean of artifacts
+      // (AD-6 z/OS spool trap).
+      const lines = text.split(/\r?\n/);
+      const sourceDir = filePath.split('/').slice(0, -1).join('/');
+      for (const line of lines) {
+        // CRITICAL: do NOT trim. Column-1 in z/OS spool = print control char
+        // (0/1/space) and is semantically meaningful (page eject markers,
+        // ABEND headers, etc.) — AD-6 fixed-width trap. Skip only truly
+        // empty lines; lines that are pure whitespace (column-1 padding)
+        // are also skipped because no parser regex would match them.
+        if (line.length === 0) continue;
+        const code = extractCobolCode(line);
+        if (!code) continue;
+        // 6-key frozen event payload (AD-4 contract — extra keys forbidden)
+        const event = Object.freeze({
+          adapter: ADAPTER,
+          errorCode: code,
+          file: filePath,
+          message: line,
+          source: sourceDir,
+          timestamp: new Date().toISOString(),
+        });
+        this.emit('error', event);
+      }
+    } finally {
+      await fh.close();
+    }
+  }
+}
+
+export default CobolLogAdapter;

package/src/adapters/ibmmq/ibmmq-parser.js

@@ -0,0 +1,23 @@
+// src/adapters/ibmmq/ibmmq-parser.js
+// T-2-03 isolation surface: regexes exported as named constants for unit testing.
+// Adapter binds chokidar to AMQERR0[1-3].LOG glob only; these regexes never
+// run against arbitrary text by the adapter itself.
+
+// Pattern: AMQ followed by 4 digits, optional suffix letter (E error / W warn / I info).
+// IBM MQ V9 message-code shape per Knowledge Center.
+export const IBMMQ_AMQ_REGEX = /\b(AMQ\d{4}[EWI]?)\b/;
+
+// Secondary capture: MQRC reason code from "ArithInsert1(NNNN)" (formal SLOG)
+// or "returned NNNN" (free-form prose). Group 1 = ArithInsert1 form, group 2 = "returned" form.
+export const IBMMQ_MQRC_REGEX = /(?:ArithInsert1\((\d+)\)|returned\s+(\d+))/;
+
+export function extractAmqCode(line) {
+  const m = line.match(IBMMQ_AMQ_REGEX);
+  return m ? m[1] : null;
+}
+
+export function extractMqrc(line) {
+  const m = line.match(IBMMQ_MQRC_REGEX);
+  if (!m) return null;
+  return m[1] || m[2] || null;
+}

package/src/adapters/ibmmq/index.js

@@ -0,0 +1,137 @@
+// src/adapters/ibmmq/index.js
+// IbmMqLogAdapter — watches AMQERR0[1-3].LOG in the configured MQ errors dir;
+// emits 6-key error events. AD-1 lifecycle, AD-3 polling, AD-4 byte-position
+// dedup with TAIL-on-startup default, AD-5 per-file ordering.
+// T-2-01 mitigation: default polling interval 5000 ms.
+
+import { EventEmitter } from 'node:events';
+import { stat, open } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import chokidar from 'chokidar';
+import { extractAmqCode } from './ibmmq-parser.js';
+
+const ADAPTER = 'ibmmq';
+
+// T-2-03 anchor: only AMQERR01.LOG / AMQERR02.LOG / AMQERR03.LOG are accepted.
+// Equivalent to the glob AMQERR0[1-3].LOG, but enforced post-watch in the handler
+// because chokidar usePolling:true does not engage with bracket-class globs on
+// macOS/Node 24 (verified empirically: AMQERR*.LOG fires events; AMQERR0[1-3].LOG
+// fires nothing). The watcher uses AMQERR*.LOG; this regex narrows back to 01..03.
+const IBMMQ_FILENAME_ANCHOR = /^AMQERR0[1-3]\.LOG$/;
+
+export class IbmMqLogAdapter extends EventEmitter {
+  constructor(config = {}) {
+    super();
+    this.errorsDir = config.errorsDir || '/var/mqm/qmgrs/QM_PRD01/errors';
+    this.interval = config.interval ?? 5000;
+    this.replayOnStart = config.replayOnStart === true;
+    this._watcher = null;
+    this._offsets = new Map();   // filePath → byte offset
+    this._inodes = new Map();    // filePath → inode
+    this._isRunning = false;
+  }
+
+  get isRunning() { return this._isRunning; }
+
+  async start() {
+    if (this._isRunning) return;
+    this._isRunning = true;
+
+    // Watch glob = AMQERR*.LOG (chokidar polling-compatible); the strict anchor
+    // AMQERR0[1-3].LOG is enforced by IBMMQ_FILENAME_ANCHOR on every event.
+    const glob = join(this.errorsDir, 'AMQERR*.LOG');
+
+    this._watcher = chokidar.watch(glob, {
+      usePolling: true,
+      interval: this.interval,
+      ignoreInitial: false, // we handle initial ourselves via TAIL seek
+      awaitWriteFinish: false,
+    });
+
+    const isAnchoredFile = (fp) => IBMMQ_FILENAME_ANCHOR.test(basename(fp));
+
+    const onAdd = async (filePath) => {
+      if (!isAnchoredFile(filePath)) return; // T-2-03: drop non-anchored
+      if (this.replayOnStart) {
+        this._offsets.set(filePath, 0);
+        // fall through to _readNew below
+      } else {
+        try {
+          const st = await stat(filePath);
+          this._offsets.set(filePath, st.size);
+          this._inodes.set(filePath, st.ino);
+          return; // TAIL mode — don't emit pre-existing content
+        } catch { return; }
+      }
+      this._readNew(filePath).catch(() => { /* ENOENT silence */ });
+    };
+
+    this._watcher.on('add', onAdd);
+    this._watcher.on('change', (fp) => {
+      if (!isAnchoredFile(fp)) return; // T-2-03: drop non-anchored
+      this._readNew(fp).catch(() => { /* ENOENT silence */ });
+    });
+
+    // Swallow chokidar's own bubbled errors (e.g., watch-path ENOENT).
+    this._watcher.on('error', () => {});
+  }
+
+  async stop() {
+    if (!this._isRunning) return;
+    this._isRunning = false;
+    if (this._watcher) {
+      await this._watcher.close().catch(() => {});
+      this._watcher = null;
+    }
+    this._offsets.clear();
+    this._inodes.clear();
+  }
+
+  async _readNew(filePath) {
+    let st;
+    try { st = await stat(filePath); } catch { return; } // ENOENT silence
+
+    const lastOffset = this._offsets.get(filePath) ?? 0;
+    const lastInode = this._inodes.get(filePath);
+
+    // Rotation: inode changed OR size shrunk → reset to 0
+    if ((lastInode !== undefined && st.ino !== lastInode) || st.size < lastOffset) {
+      this._offsets.set(filePath, 0);
+      this._inodes.set(filePath, st.ino);
+      return this._readNew(filePath); // re-enter with offset=0
+    }
+    this._inodes.set(filePath, st.ino);
+
+    if (st.size <= lastOffset) return;
+
+    const fh = await open(filePath, 'r');
+    try {
+      const len = st.size - lastOffset;
+      const buf = Buffer.alloc(len);
+      await fh.read(buf, 0, len, lastOffset);
+      this._offsets.set(filePath, st.size);
+      const text = buf.toString('utf8');
+      const lines = text.split(/\r?\n/);
+      const sourceDir = filePath.split('/').slice(0, -1).join('/');
+      for (const line of lines) {
+        if (line.trim().length === 0) continue;
+        const code = extractAmqCode(line);
+        if (!code) continue;
+        // 6-key frozen event payload (AD-4 contract — extra keys forbidden)
+        const event = Object.freeze({
+          adapter: ADAPTER,
+          errorCode: code,
+          file: filePath,
+          message: line,
+          source: sourceDir,
+          timestamp: new Date().toISOString(),
+        });
+        this.emit('error', event);
+      }
+    } finally {
+      await fh.close();
+    }
+  }
+}
+
+export default IbmMqLogAdapter;

package/src/adapters/index.js

@@ -0,0 +1,79 @@
+// src/adapters/index.js
+// Phase 2 — Legacy connectors registry. AD-1: returns unstarted instances; caller starts.
+//
+// Public API:
+//   loadAdapters(config)           → unstarted Adapter[]
+//   stopAll(adapters, timeoutMs?)  → Promise<void>, never throws
+//   ALLOWED_STACK_LIST             → frozen string[] of valid stack names
+
+import { SapLogAdapter } from './sap/index.js';
+import { IbmMqLogAdapter } from './ibmmq/index.js';
+import { As400LogAdapter } from './as400/index.js';
+import { OracleFormsLogAdapter } from './oracle-forms/index.js';
+import { CobolLogAdapter } from './cobol/index.js';
+
+const ALLOWED_STACKS = Object.freeze(['sap', 'ibmmq', 'as400', 'oracle-forms', 'cobol']);
+
+const FACTORIES = Object.freeze({
+  'sap': (cfg) => new SapLogAdapter(cfg),
+  'ibmmq': (cfg) => new IbmMqLogAdapter(cfg),
+  'as400': (cfg) => new As400LogAdapter(cfg),
+  'oracle-forms': (cfg) => new OracleFormsLogAdapter(cfg),
+  'cobol': (cfg) => new CobolLogAdapter(cfg),
+});
+
+/**
+ * Load configured adapter instances WITHOUT starting them (AD-1).
+ *
+ * @param {object} config
+ * @param {string[]} config.legacyStacks subset of ['sap','ibmmq','as400','oracle-forms','cobol']
+ * @param {object} [config.sap]          per-adapter config object
+ * @param {object} [config.ibmmq]
+ * @param {object} [config.as400]
+ * @param {object} [config['oracle-forms']]
+ * @param {object} [config.cobol]
+ * @returns {Array} unstarted adapters; caller invokes .start() on each
+ * @throws {Error} on unknown stack name (message names the offender)
+ */
+export function loadAdapters(config = {}) {
+  const stacks = Array.isArray(config.legacyStacks) ? config.legacyStacks : [];
+  for (const s of stacks) {
+    if (!ALLOWED_STACKS.includes(s)) {
+      throw new Error(`loadAdapters: unknown stack '${s}'. Allowed: ${ALLOWED_STACKS.join(', ')}`);
+    }
+  }
+  return stacks.map((s) => FACTORIES[s](config[s] || {}));
+}
+
+/**
+ * Stop all adapters in parallel with overall timeout (AC-11).
+ * Used by SIGTERM handler. Never throws — failures are swallowed so the
+ * shutdown path always returns and the event loop drains.
+ *
+ * @param {Array} adapters
+ * @param {number} [timeoutMs=5000]
+ * @returns {Promise<void>}
+ */
+export async function stopAll(adapters, timeoutMs = 5000) {
+  if (!Array.isArray(adapters) || adapters.length === 0) return;
+  const stopPromises = adapters.map((a) =>
+    Promise.resolve()
+      .then(() => (typeof a?.stop === 'function' ? a.stop() : undefined))
+      .catch(() => { /* swallow per never-throw contract */ })
+  );
+  // Bounded timer so a non-resolving stop() cannot block process exit.
+  let timer;
+  const timeoutPromise = new Promise((resolve) => {
+    timer = setTimeout(resolve, timeoutMs);
+    // Per project convention, unref the timer so it never holds the loop open
+    // beyond the rest of the work (AD-3 timer hygiene).
+    if (typeof timer.unref === 'function') timer.unref();
+  });
+  try {
+    await Promise.race([Promise.all(stopPromises), timeoutPromise]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export const ALLOWED_STACK_LIST = ALLOWED_STACKS;

package/src/adapters/oracle-forms/index.js

@@ -0,0 +1,145 @@
+// src/adapters/oracle-forms/index.js
+// OracleFormsLogAdapter — watches *.trc files in the configured Forms trace
+// dir; emits 6-key error events. AD-1 lifecycle, AD-3 polling, AD-4 byte-position
+// dedup with TAIL-on-startup default, AD-5 per-file ordering, AD-6 Latin-1
+// mojibake-trap tolerance via latin1 decode (never throws on any byte).
+// T-2-01 mitigation: default polling interval 5000 ms.
+
+import { EventEmitter } from 'node:events';
+import { stat, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import chokidar from 'chokidar';
+import { extractFormsCode } from './oracle-forms-parser.js';
+
+const ADAPTER = 'oracle-forms';
+
+// Decode buffer using Latin-1 (single-byte) encoding — never throws on any
+// byte sequence. ORA/FRM message codes are ASCII so the regex match is
+// unaffected by the choice; accented free-text payload bytes survive into
+// `message` as Latin-1 characters (mojibake-tolerant per AD-6 Forms trap).
+function decodeTolerant(buf) {
+  return buf.toString('latin1');
+}
+
+export class OracleFormsLogAdapter extends EventEmitter {
+  constructor(config = {}) {
+    super();
+    this.traceDir = config.traceDir || '/u01/oracle/forms/trace';
+    this.interval = config.interval ?? 5000;
+    this.replayOnStart = config.replayOnStart === true;
+    this._watcher = null;
+    this._offsets = new Map(); // filePath → byte offset
+    this._inodes = new Map();  // filePath → inode
+    this._isRunning = false;
+  }
+
+  get isRunning() {
+    return this._isRunning;
+  }
+
+  async start() {
+    if (this._isRunning) return;
+    this._isRunning = true;
+
+    // Glob bound to *.trc only (wildcard — chokidar polling-mode bracket-class
+    // workaround from Plan 02-08 does NOT apply here; *.trc is a plain wildcard).
+    const glob = join(this.traceDir, '*.trc');
+
+    this._watcher = chokidar.watch(glob, {
+      usePolling: true,
+      interval: this.interval,
+      ignoreInitial: false, // we handle initial ourselves via TAIL seek
+      awaitWriteFinish: false,
+    });
+
+    const onAdd = async (filePath) => {
+      if (this.replayOnStart) {
+        this._offsets.set(filePath, 0);
+        // fall through to _readNew below
+      } else {
+        try {
+          const st = await stat(filePath);
+          this._offsets.set(filePath, st.size);
+          this._inodes.set(filePath, st.ino);
+          return; // TAIL mode — don't emit pre-existing content
+        } catch {
+          return;
+        }
+      }
+      this._readNew(filePath).catch(() => { /* ENOENT silence */ });
+    };
+
+    this._watcher.on('add', onAdd);
+    this._watcher.on('change', (fp) => {
+      this._readNew(fp).catch(() => { /* ENOENT silence */ });
+    });
+
+    // Swallow chokidar's own bubbled errors (e.g., watch-path ENOENT) —
+    // dual-layer suppression with the per-read try/catch ensures full
+    // ENOENT silence (canonical pattern from Plan 02-07).
+    this._watcher.on('error', () => {});
+  }
+
+  async stop() {
+    if (!this._isRunning) return;
+    this._isRunning = false;
+    if (this._watcher) {
+      await this._watcher.close().catch(() => {});
+      this._watcher = null;
+    }
+    this._offsets.clear();
+    this._inodes.clear();
+  }
+
+  async _readNew(filePath) {
+    let st;
+    try {
+      st = await stat(filePath);
+    } catch {
+      return; // ENOENT silence
+    }
+
+    const lastOffset = this._offsets.get(filePath) ?? 0;
+    const lastInode = this._inodes.get(filePath);
+
+    // Rotation: inode changed OR size shrunk → reset to 0
+    if ((lastInode !== undefined && st.ino !== lastInode) || st.size < lastOffset) {
+      this._offsets.set(filePath, 0);
+      this._inodes.set(filePath, st.ino);
+      return this._readNew(filePath); // re-enter with offset=0
+    }
+    this._inodes.set(filePath, st.ino);
+
+    if (st.size <= lastOffset) return;
+
+    const fh = await open(filePath, 'r');
+    try {
+      const len = st.size - lastOffset;
+      const buf = Buffer.alloc(len);
+      await fh.read(buf, 0, len, lastOffset);
+      this._offsets.set(filePath, st.size);
+      const text = decodeTolerant(buf);
+      const lines = text.split(/\r?\n/);
+      const sourceDir = filePath.split('/').slice(0, -1).join('/');
+      for (const line of lines) {
+        if (line.trim().length === 0) continue;
+        const code = extractFormsCode(line);
+        if (!code) continue;
+        // 6-key frozen event payload (AD-4 contract — extra keys forbidden)
+        const event = Object.freeze({
+          adapter: ADAPTER,
+          errorCode: code,
+          file: filePath,
+          message: line,
+          source: sourceDir,
+          timestamp: new Date().toISOString(),
+        });
+        this.emit('error', event);
+      }
+    } finally {
+      await fh.close();
+    }
+  }
+}
+
+export default OracleFormsLogAdapter;

package/src/adapters/oracle-forms/oracle-forms-parser.js

@@ -0,0 +1,11 @@
+// src/adapters/oracle-forms/oracle-forms-parser.js
+// T-2-03 isolation surface: regex exported as a named const so it can be
+// unit-tested against arbitrary text decoupled from the file-watching
+// machinery in index.js. The watcher itself is bound to a literal *.trc
+// glob so this regex never engages arbitrary text by construction.
+export const ORACLE_FORMS_REGEX = /(?:Line \d+:|^)\s*(ORA-\d{5}|FRM-\d{5}):\s*(.+)/;
+
+export function extractFormsCode(line) {
+  const m = line.match(ORACLE_FORMS_REGEX);
+  return m ? m[1] : null;
+}