@W-23201206: build-mule-integration — port skill scripts bash to Node (hybrid, template-preserving)

Replaces the bash helper scripts with the validated OS-agnostic Node port from
mule-dx-agent-evaluation, while preserving the template surface this skill
already ships:

- scripts/*.sh -> scripts/*.mjs (11 scripts, ESM, zero npm deps) + new lib/*.mjs
  (7 shared modules). Drops scripts/_suggest_nearest.py (its only consumer,
  validate_before_build, now uses lib/nearest.mjs).
- SKILL.md body synced to the Node version (node scripts/<name>.mjs invocations,
  update-mode + Step-8 mule-artifact alignment). Bash->Node is a breaking change
  for direct script callers, so the skill majors: 1.3.0 -> 2.0.0.
- references/template-project-creation.md node-ified (.sh -> .mjs); template
  search (search_templates.mjs), Step 1b, and the Exchange/Local flows preserved.
- package.json: 1.5.0 -> 2.0.0 and files += "*/lib/**" so the imported lib/
  modules publish (Node scripts import from ../lib/*.mjs).

validate-skills (R1-R7) and validate-jtbd both pass; all 18 .mjs node --check clean.

Author: bpolat1

skills/mule-development/build-mule-integration/SKILL.md

@@ -0,0 +1,41 @@
+// anypoint.mjs — wrap anypoint-cli-v4 invocations and toolchain probes.
+// Reproduces NODE_NO_WARNINGS=1, _JAVA_OPTIONS handling, env -u ANYPOINT_ENV via spawn env.
+import { spawnSync } from 'node:child_process';
+
+/** @param {Record<string,string>} [extra] Overrides merged last. @returns {Record<string,string>} A child env mirroring `env -u ANYPOINT_ENV NODE_NO_WARNINGS=1`. */
+export function anypointEnv(extra = {}) {
+  const env = { ...process.env };
+  delete env.ANYPOINT_ENV;
+  env.NODE_NO_WARNINGS = '1';
+  return { ...env, ...extra };
+}
+
+/** @param {string} cmd Executable name. @returns {boolean} True iff resolvable on PATH (uses `where` on Windows, `command -v` on POSIX). */
+export function commandExists(cmd) {
+  const isWin = process.platform === 'win32';
+  if (isWin) {
+    const r = spawnSync('where', [cmd], { stdio: 'ignore' });
+    return r.status === 0;
+  }
+  // POSIX: `command -v` is a shell builtin; invoke it through /bin/sh.
+  // The `'_'` argv[3] slot is `$0` — a script-name placeholder that lets `cmd`
+  // arrive as `$1` for the inline shell snippet.
+  const r = spawnSync('/bin/sh', ['-c', `command -v "$1" >/dev/null 2>&1`, '_', cmd], { stdio: 'ignore' });
+  return r.status === 0;
+}
+
+/** @param {string} cmd Executable. @param {string[]} args Argv. @param {{env?:Record<string,string>}} [opts] @returns {{status:number|null, signal:string|null, error:Error|undefined, stdout:string, stderr:string}} Synchronous spawn capture with anypointEnv() applied. */
+export function runProbe(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, {
+    env: anypointEnv(opts.env),
+    encoding: 'utf8',
+    shell: false,
+  });
+  return {
+    status: r.status,
+    signal: r.signal,
+    error: r.error,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+  };
+}

skills/mule-development/build-mule-integration/lib/anypoint.mjs

@@ -0,0 +1,172 @@
+// exchange-rank.mjs — port of the jq filter used by get_latest_connector.sh.
+//
+// rankCandidates(pageA, pageB, searchTerm) takes the two parsed Exchange asset
+// arrays + the original search term, and returns a list of ranked GAV strings
+// shaped exactly the way the bash original prints to stdout:
+//   "<groupId>:<assetId>:<version>"  one per line.
+//
+// The ranking algorithm is intentionally a verbatim port of the jq filter:
+//   1. Concatenate page A + page B.
+//   2. Keep only type=="extension".
+//   3. Drop pre-release versions matching /-(SNAPSHOT|RC|alpha|beta|M[0-9])/.
+//   4. Group by [groupId, assetId]; within each group keep the highest version,
+//      where versions are compared by splitting on "." and coercing each segment
+//      to a number (non-numeric segments become 0, matching `tonumber? // 0`).
+//   5. Tokenize search term and asset id by lowercase + split("-"), discarding
+//      "" / "mule" / "connector" tokens (jq's `select(. != "" and …)`).
+//   6. Score by token overlap:
+//        score = 2 * exact + substring - unmatched
+//      where:
+//        - exact: asset token appears in search-token set.
+//        - substring: not exact AND token len >= 2 AND there exists a search
+//          token of len >= 2 such that one is a substring of the other.
+//        - unmatched: neither.
+//   7. Group preference: com.mulesoft.connectors=0, org.mule.connectors=1, else=2.
+//   8. Sort ascending by [-score, groupPref, assetId.length].
+//
+// jq numeric comparison on arrays compares element-by-element. We replicate
+// that by sorting groups via a key array and a tuple-aware comparator.
+
+const PRERELEASE_RE = /-(SNAPSHOT|RC|alpha|beta|M[0-9])/;
+
+function tokenize(s) {
+  return String(s)
+    .toLowerCase()
+    .split('-')
+    .filter((t) => t !== '' && t !== 'mule' && t !== 'connector');
+}
+
+// Split version into a tuple of numbers (non-numeric segments → 0). Mirrors
+// `.version | split(".") | map(tonumber? // 0)`.
+function versionKey(version) {
+  return String(version)
+    .split('.')
+    .map((seg) => {
+      // jq's `tonumber?` returns null on failure; `// 0` substitutes 0.
+      // It accepts leading-sign integers and floats; we approximate with
+      // Number() but reject NaN and non-finite.
+      const n = Number(seg);
+      return Number.isFinite(n) ? n : 0;
+    });
+}
+
+// Compare two arrays element-by-element (jq semantics on arrays of numbers).
+// Shorter array sorts before equal-prefix longer one — same as jq's sort_by.
+function compareTuples(a, b) {
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i += 1) {
+    const ai = i < a.length ? a[i] : 0;
+    const bi = i < b.length ? b[i] : 0;
+    if (ai < bi) return -1;
+    if (ai > bi) return 1;
+  }
+  return 0;
+}
+
+function groupPref(groupId) {
+  if (groupId === 'com.mulesoft.connectors') return 0;
+  if (groupId === 'org.mule.connectors') return 1;
+  return 2;
+}
+
+// Pick the highest version from a list of {version} objects, mirroring
+// `(sort_by([.version | split(".") | map(tonumber? // 0)]) | reverse | .[0].version)`.
+function highestVersion(group) {
+  let best = group[0];
+  let bestKey = versionKey(best.version);
+  for (let i = 1; i < group.length; i += 1) {
+    const k = versionKey(group[i].version);
+    if (compareTuples(k, bestKey) > 0) {
+      best = group[i];
+      bestKey = k;
+    }
+  }
+  return best.version;
+}
+
+// Token classification: returns 'exact' | 'substring' | 'none'.
+// `searchTokens` is an array; `searchSet` is a Set of the same tokens for the
+// exact-match check (mirrors jq's `index($t)` on the search-tokens array).
+function classifyToken(t, searchTokens, searchSet) {
+  if (searchSet.has(t)) return 'exact';
+  if (t.length < 2) return 'none';
+  for (const s of searchTokens) {
+    if (s.length < 2) continue;
+    // jq's `index` on strings returns the index of the first match (or null).
+    // The original filter uses `index($t) != null or ($t | index($s)) != null`
+    // which is true when either is a substring of the other.
+    if (s.includes(t) || t.includes(s)) return 'substring';
+  }
+  return 'none';
+}
+
+/** @param {Array<object>} pageA Exchange page-A assets. @param {Array<object>} pageB Exchange page-B assets. @param {string} searchTerm Original user term used for token-overlap scoring. @returns {Array<{groupId:string, assetId:string, version:string, score:number, groupPref:number}>} Ranked candidates, best first; mirrors get_latest_connector.sh's jq pipeline. */
+export function rankCandidates(pageA, pageB, searchTerm) {
+  const all = [...(Array.isArray(pageA) ? pageA : []), ...(Array.isArray(pageB) ? pageB : [])];
+
+  const searchTokens = tokenize(searchTerm);
+  const searchSet = new Set(searchTokens);
+
+  // Filter: type=="extension" and version not pre-release.
+  const filtered = all.filter((row) => {
+    if (!row || typeof row !== 'object') return false;
+    if (row.type !== 'extension') return false;
+    const v = row.version;
+    if (typeof v !== 'string') return false;
+    return !PRERELEASE_RE.test(v);
+  });
+
+  // Group by [groupId, assetId].
+  const groups = new Map();
+  for (const row of filtered) {
+    const key = `${row.groupId} ${row.assetId}`;
+    let bucket = groups.get(key);
+    if (!bucket) {
+      bucket = [];
+      groups.set(key, bucket);
+    }
+    bucket.push(row);
+  }
+
+  // Build candidate per group, scored.
+  const candidates = [];
+  for (const bucket of groups.values()) {
+    const first = bucket[0];
+    const groupId = first.groupId;
+    const assetId = first.assetId;
+    const version = highestVersion(bucket);
+    const assetTokens = tokenize(assetId);
+
+    let exact = 0;
+    let substr = 0;
+    let unmatched = 0;
+    for (const t of assetTokens) {
+      const kind = classifyToken(t, searchTokens, searchSet);
+      if (kind === 'exact') exact += 1;
+      else if (kind === 'substring') substr += 1;
+      else unmatched += 1;
+    }
+
+    const score = 2 * exact + substr - unmatched;
+    const pref = groupPref(groupId);
+
+    candidates.push({
+      groupId,
+      assetId,
+      version,
+      score,
+      groupPref: pref,
+    });
+  }
+
+  // sort_by([-score, groupPref, (assetId | length)])
+  candidates.sort((a, b) => {
+    const sa = -a.score;
+    const sb = -b.score;
+    if (sa !== sb) return sa - sb;
+    if (a.groupPref !== b.groupPref) return a.groupPref - b.groupPref;
+    return a.assetId.length - b.assetId.length;
+  });
+
+  return candidates;
+}

skills/mule-development/build-mule-integration/lib/exchange-rank.mjs

@@ -0,0 +1,82 @@
+// fsx.mjs — file-system helpers (mkdirp, readJson, writeJson, isFile, isDir,
+// listDir, readJsonOrNull, mktempFile, registerCleanup).
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, statSync, readdirSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import process from 'node:process';
+
+/** @param {string} dir Recursively-created directory. */
+export function mkdirp(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+/** @param {string} p File path. @returns {any} Parsed JSON; throws on read/parse error. */
+export function readJson(p) {
+  return JSON.parse(readFileSync(p, 'utf8'));
+}
+
+/** @param {string} p Output path. @param {any} value JSON-serializable value written 2-space indented with a trailing newline (matches `jq -n` byte layout). */
+export function writeJson(p, value) {
+  const text = JSON.stringify(value, null, 2) + '\n';
+  writeFileSync(p, text);
+}
+
+/** @param {string} p Path. @returns {boolean} True iff path exists and is a regular file. */
+export function isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+/** @param {string} p Path. @returns {boolean} True iff path exists and is a directory. */
+export function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+/** @param {string} dir Directory path. @returns {import('node:fs').Dirent[]} Entries; empty array on error. */
+export function listDir(dir) {
+  try { return readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+}
+
+/** @param {string} p File path. @returns {any|null} Parsed JSON or null on any read/parse error. */
+export function readJsonOrNull(p) {
+  try { return readJson(p); } catch { return null; }
+}
+
+/**
+ * @param {string} template Path containing literal "XXXXXX"; replaced with 6 random chars.
+ * @returns {string} Path of a freshly-created empty file (mirrors `mktemp <template>`).
+ */
+export function mktempFile(template) {
+  const dir = path.dirname(template);
+  mkdirp(dir);
+  const idx = template.lastIndexOf('XXXXXX');
+  if (idx === -1) throw new Error(`mktempFile: template missing XXXXXX: ${template}`);
+  for (let i = 0; i < 100; i += 1) {
+    // CSPRNG-derived suffix (3 random bytes → 6 lowercase hex chars). Matches
+    // the existing /^[A-Za-z0-9]{6}$/ test contract; replaces Math.random()
+    // which leaks the V8 PRNG state to a co-tenant on the same host.
+    const suffix = randomBytes(3).toString('hex');
+    const candidate = template.slice(0, idx) + suffix + template.slice(idx + 6);
+    if (!existsSync(candidate)) {
+      writeFileSync(candidate, '', { flag: 'wx' });
+      return candidate;
+    }
+  }
+  throw new Error(`mktempFile: could not create unique file for ${template}`);
+}
+
+const _cleanupPaths = new Set();
+let _cleanupRegistered = false;
+/** @param {string} p Path to delete on process exit (also on SIGINT/SIGTERM). */
+export function registerCleanup(p) {
+  _cleanupPaths.add(p);
+  if (_cleanupRegistered) return;
+  _cleanupRegistered = true;
+  const cleanup = () => {
+    for (const f of _cleanupPaths) {
+      try { unlinkSync(f); } catch { /* already gone */ }
+    }
+  };
+  process.on('exit', cleanup);
+  process.on('SIGINT', () => { cleanup(); process.exit(130); });
+  process.on('SIGTERM', () => { cleanup(); process.exit(143); });
+}

skills/mule-development/build-mule-integration/lib/fsx.mjs

@@ -0,0 +1,54 @@
+// nearest.mjs — port of skills/build-mule-integration/scripts/_suggest_nearest.py
+//
+// Used by validate_before_build.mjs (and any other validator that needs a
+// "did you mean…" suggestion). Reproduces the Python helper's distance
+// function exactly: Hamming-on-overlap + abs length delta.
+
+/** @param {string} token Reference. @param {string} candidate Candidate. @returns {number} Hamming distance over the overlapping prefix plus abs length delta. */
+export function distance(token, candidate) {
+  const overlap = Math.min(token.length, candidate.length);
+  let mismatches = 0;
+  for (let i = 0; i < overlap; i += 1) {
+    if (token[i] !== candidate[i]) mismatches += 1;
+  }
+  return mismatches + Math.abs(token.length - candidate.length);
+}
+
+/** @param {string} token Reference. @param {string[]} candidates Pool. @returns {string} Closest candidate by `distance()`; "" when pool empty; first wins on ties. */
+export function nearest(token, candidates) {
+  if (!candidates || candidates.length === 0) return '';
+  let best = candidates[0];
+  let bestDist = distance(token, best);
+  for (let i = 1; i < candidates.length; i += 1) {
+    const d = distance(token, candidates[i]);
+    if (d < bestDist) {
+      best = candidates[i];
+      bestDist = d;
+    }
+  }
+  return best;
+}
+
+/** @param {string} nsid An `NS:ID` token. @returns {string} The substring before the first ":", or "" when no colon present. */
+export function nsOf(nsid) {
+  const idx = nsid.indexOf(':');
+  return idx === -1 ? '' : nsid.slice(0, idx);
+}
+
+/**
+ * Find the nearest allowlist entry sharing `miss`'s namespace.
+ *
+ * @param {string} miss The unrecognised `NS:ID` token.
+ * @param {string[]} allowlist Full allowlist (any namespace).
+ * @returns {string} Nearest same-namespace candidate, or "" when the
+ *   namespace pool is empty. **No-colon fallback:** when `miss` contains no
+ *   `:`, `nsOf(miss)` is `""` and the helper widens to the entire allowlist
+ *   (no namespace filter) — matches the Python original's behaviour.
+ */
+export function suggestForMiss(miss, allowlist) {
+  const ns = nsOf(miss);
+  const pool = ns
+    ? allowlist.filter((c) => nsOf(c) === ns)
+    : allowlist.slice();
+  return nearest(miss, pool);
+}

skills/mule-development/build-mule-integration/lib/nearest.mjs

@@ -0,0 +1,43 @@
+// platform.mjs — platform helpers (parseJavaVersion, semver-like sort).
+
+/** @param {string} stderrOrStdout `java -version` output (stderr typically). @returns {{raw:string, major:number|null}} Parsed version; handles legacy "1.8.0_321"→8 and modern "11.0.21"→11. */
+export function parseJavaVersion(stderrOrStdout) {
+  if (!stderrOrStdout) return { raw: '', major: null };
+  const firstLine = String(stderrOrStdout).split(/\r?\n/, 1)[0] || '';
+  // Match the first quoted token, e.g. java version "11.0.21" or openjdk version "1.8.0_321"
+  const m = firstLine.match(/"([^"]+)"/);
+  const raw = m ? m[1] : '';
+  if (!raw) return { raw: '', major: null };
+  const parts = raw.split('.');
+  let major;
+  if (parts[0] === '1' && parts.length > 1) {
+    major = parseInt(parts[1], 10);
+  } else {
+    major = parseInt(parts[0], 10);
+  }
+  return { raw, major: Number.isFinite(major) ? major : null };
+}
+
+/** @param {string[]} arr Strings like "mule-4.5.0". @returns {string[]} New array sorted by `sort -V` semantics (numeric runs compared numerically). */
+export function sortVersionStrings(arr) {
+  const tokenize = (s) => String(s).split(/(\d+)/).map((t) => /^\d+$/.test(t) ? parseInt(t, 10) : t);
+  return [...arr].sort((a, b) => {
+    const ta = tokenize(a);
+    const tb = tokenize(b);
+    const len = Math.max(ta.length, tb.length);
+    for (let i = 0; i < len; i += 1) {
+      const x = ta[i];
+      const y = tb[i];
+      if (x === undefined) return -1;
+      if (y === undefined) return 1;
+      if (typeof x === 'number' && typeof y === 'number') {
+        if (x !== y) return x - y;
+      } else {
+        const sx = String(x);
+        const sy = String(y);
+        if (sx !== sy) return sx < sy ? -1 : 1;
+      }
+    }
+    return 0;
+  });
+}