@zowe/cli 8.36.1 → 8.37.1

package/node_modules/js-yaml/lib/loader.js

@@ -371,19 +371,28 @@ function captureSegment (state, start, end, checkJson) {
   }
 }
 
+function chargeMergeWork (state) {
+  state.totalMergeKeys++
+
+  if (state.maxTotalMergeKeys !== -1 && state.totalMergeKeys > state.maxTotalMergeKeys) {
+    throwError(state, 'merge keys exceeded maxTotalMergeKeys (' + state.maxTotalMergeKeys + ')')
+  }
+}
+
 function mergeMappings (state, destination, source, overridableKeys) {
   if (!common.isObject(source)) {
     throwError(state, 'cannot merge mappings; the provided source object is unacceptable')
   }
 
+  // Count the source mapping itself to bound sequences of empty mappings.
+  chargeMergeWork(state)
+
   const sourceKeys = Object.keys(source)
 
   for (let index = 0, quantity = sourceKeys.length; index < quantity; index += 1) {
     const key = sourceKeys[index]
 
-    if (state.maxTotalMergeKeys !== -1 && ++state.totalMergeKeys > state.maxTotalMergeKeys) {
-      throwError(state, 'merge keys exceeded maxTotalMergeKeys (' + state.maxTotalMergeKeys + ')')
-    }
+    chargeMergeWork(state)
 
     if (!_hasOwnProperty.call(destination, key)) {
       setProperty(destination, key, source[key])
@@ -426,6 +435,10 @@ function storeMappingPair (state, _result, overridableKeys, keyTag, keyNode, val
 
   if (keyTag === 'tag:yaml.org,2002:merge') {
     if (Array.isArray(valueNode)) {
+      if (valueNode.length > 100) {
+        throwError(state, 'abnormal merge sequence size')
+      }
+
       for (let index = 0, quantity = valueNode.length; index < quantity; index += 1) {
         mergeMappings(state, _result, valueNode[index], overridableKeys)
       }

package/node_modules/js-yaml/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-yaml",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "description": "YAML 1.2 parser and serializer",
   "keywords": [
     "yaml",

package/node_modules/sanitize-html/README.md

@@ -696,6 +696,19 @@ And you can forbid the use of protocol-relative URLs (starting with `//`) to acc
 allowProtocolRelative: false
 ```
 
+### SVG animations of URL attributes are discarded
+
+For security reasons, if your `allowedTags` includes the SVG animation elements (`animate`, `animateColor`, `animateMotion`, `animateTransform` and `set`), note that an animation which targets a URL attribute is always discarded:
+
+```html
+<!-- Discarded: this would set the link's href to javascript: after sanitization -->
+<animate attributeName="href" values="#safe;javascript:alert(1)" dur=".01s" fill="freeze">
+```
+
+An animation element carries no URL itself. It names the attribute it animates with `attributeName` and supplies the new value in `values`, `from`, `to` or `by`, which the browser copies into the target attribute after sanitization. Scheme checking those values is not sufficient, because `values` is a semicolon-separated *list* of destinations, so we discard the animation instead whenever `attributeName` selects `href`, `xlink:href` or any other attribute listed in `allowedSchemesAppliedToAttributes`.
+
+Animations of attributes that are not URLs, such as `fill` or `opacity`, are unaffected.
+
 ### Discarding the entire contents of a disallowed tag
 
 Normally, with a few exceptions, if a tag is not allowed, all of the text within it is preserved, and so are any allowed tags within it.

package/node_modules/sanitize-html/index.js

@@ -12,6 +12,17 @@ const mediaTags = [
 ];
 // Tags that are inherently vulnerable to being used in XSS attacks.
 const vulnerableTags = [ 'script', 'style' ];
+// SVG SMIL animation elements. These do not carry a URL themselves: they
+// retarget an attribute of another element, naming it with `attributeName`
+// and supplying the new value(s) in `values`, `from`, `to` and `by`.
+const svgAnimationTags = [
+  'animate', 'animatecolor', 'animatemotion', 'animatetransform', 'set'
+];
+// Attribute names that always name a URL sink, whatever
+// `allowedSchemesAppliedToAttributes` has been narrowed to. A namespace prefix
+// is ignored when matching, so `xlink:href` and any other prefixed spelling of
+// `href` are covered.
+const alwaysUrlAttributes = [ 'href' ];
 
 function each(obj, cb) {
   if (obj) {
@@ -272,7 +283,7 @@ function sanitizeHtml(html, options, _recursing) {
         }
       }
 
-      if (!tagAllowed(name) || (options.disallowedTagsMode === 'recursiveEscape' && !isEmptyObject(skipMap)) || (options.nestingLimit != null && depth >= options.nestingLimit)) {
+      if (!tagAllowed(name) || animatesUrlAttribute(name, attribs) || (options.disallowedTagsMode === 'recursiveEscape' && !isEmptyObject(skipMap)) || (options.nestingLimit != null && depth >= options.nestingLimit)) {
         skip = true;
         skipMap[depth] = true;
         if (options.disallowedTagsMode === 'discard' || options.disallowedTagsMode === 'completelyDiscard') {
@@ -540,8 +551,13 @@ function sanitizeHtml(html, options, _recursing) {
         result += ' />';
       } else {
         result += '>';
-        if (frame.innerText && !hasText && !options.textFilter) {
-          result += escapeHtml(frame.innerText);
+        if (frame.innerText && !hasText) {
+          const escaped = escapeHtml(frame.innerText);
+          if (options.textFilter) {
+            result += options.textFilter(escaped, name);
+          } else {
+            result += escaped;
+          }
           addedText = true;
         }
       }
@@ -573,14 +589,39 @@ function sanitizeHtml(html, options, _recursing) {
         // which have their own collection of XSS vectors.
         result += text;
       } else if (tag && tagAllowed(tag) && (options.disallowedTagsMode === 'discard' || options.disallowedTagsMode === 'completelyDiscard') && (tag === 'textarea' || tag === 'xmp')) {
-        // htmlparser2 treats <textarea> and <xmp> as raw text elements and
-        // does NOT decode entities inside them. The text is already properly
-        // encoded, so pass it through without additional escaping to avoid
-        // double-encoding. Other "nonTextTags" like <option> are not raw text
-        // elements in htmlparser2, so their contents are decoded and must be
-        // escaped below like any other text (important to prevent XSS via
-        // entity-encoded payloads such as <option>&lt;script&gt;...&lt;/script&gt;</option>).
-        result += text;
+        // <textarea> and <xmp> hold text that must not be re-emitted verbatim:
+        // if a raw `<` survives into the output it can reopen a tag when the
+        // result is re-parsed by a browser, smuggling non-allowlisted markup
+        // through the allowlist (mutation-XSS, GHSA-jxwj-j7wr-gfrw — e.g. the
+        // `</textarea/>` solidus mis-close). We therefore ALWAYS escape this
+        // content rather than passing it through. Escaping unconditionally also
+        // closes the related SVG/MathML foreign-content bypass (where the HTML5
+        // parser treats <textarea>/<xmp> as ordinary foreign elements and a
+        // browser re-parses their contents as live markup, e.g.
+        // `<svg><textarea><img src=x onerror=alert(1)></textarea></svg>`): since
+        // we never re-emit raw text for these tags, no namespace check is
+        // needed. The two tags need different escaping because htmlparser2
+        // tokenizes them differently:
+        if (tag === 'xmp') {
+          // <xmp> is a raw-text (CDATA) element: entities are NOT decoded, so
+          // its content reaches us as raw source that is already entity-encoded.
+          // Escape only the angle brackets so a literal `<` cannot reopen a tag,
+          // while leaving `&` untouched to avoid double-encoding entities that
+          // are already encoded in the source.
+          result += text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        } else {
+          // <textarea> is an RCDATA element: htmlparser2 (>= 11) decodes
+          // entities inside it, so its content reaches us as plain decoded text.
+          // It must therefore be fully escaped like any other text — escaping
+          // `&` as well as `<`/`>` — so entities round-trip faithfully (no
+          // double-encoding, see the CVE-2026-40186 regression tests) and no
+          // `<` can reopen a tag.
+          result += escapeHtml(text, false);
+        }
+        // Other "nonTextTags" like <option> are not raw text elements in
+        // htmlparser2, so their contents are decoded and must be escaped below
+        // like any other text (important to prevent XSS via entity-encoded
+        // payloads such as <option>&lt;script&gt;...&lt;/script&gt;</option>).
       } else if (!addedText) {
         const escaped = escapeHtml(text, false);
         if (options.textFilter) {
@@ -743,6 +784,39 @@ function sanitizeHtml(html, options, _recursing) {
     });
   }
 
+  // True if this is an SVG SMIL animation element that animates a URL-bearing
+  // attribute, e.g. `<animate attributeName="href" values="#safe;javascript:...">`.
+  //
+  // Such an element carries no URL of its own: the browser copies the animation
+  // values into the target attribute *after* sanitization, so a `javascript:`
+  // destination reaches a live link sink without ever being scheme checked.
+  // `values` compounds this, because it is a semicolon-separated LIST of
+  // destinations: checking it as one flat URL only validates its first entry, so
+  // a leading `#safe` fragment carries the rest of the list past the policy.
+  //
+  // Re-checking each entry of each value attribute would leave the safety of the
+  // output resting on our imitation of SMIL list parsing, so we reject the
+  // animation on the strength of its target instead. Animations of attributes
+  // that are not URL sinks, such as `fill` or `opacity`, are unaffected.
+  function animatesUrlAttribute(name, attribs) {
+    if (svgAnimationTags.indexOf(name.toLowerCase()) === -1) {
+      return false;
+    }
+    const schemeCheckedAttributes = options.allowedSchemesAppliedToAttributes || [];
+    return Object.keys(attribs || {}).some(function(attributeName) {
+      if (attributeName.toLowerCase() !== 'attributename') {
+        return false;
+      }
+      const target = (attribs[attributeName] || '').trim().toLowerCase();
+      // The target may be namespace prefixed (`xlink:href`). Which prefixes are
+      // in scope depends on the document, so consider the local name too.
+      const localName = target.slice(target.lastIndexOf(':') + 1);
+      return alwaysUrlAttributes.indexOf(localName) !== -1 ||
+        schemeCheckedAttributes.indexOf(target) !== -1 ||
+        schemeCheckedAttributes.indexOf(localName) !== -1;
+    });
+  }
+
   function parseUrl(value) {
     value = value.replace(/^(\w+:)?\s*[\\/]\s*[\\/]/, '$1//');
     if (value.startsWith('relative:')) {
@@ -953,7 +1027,7 @@ sanitizeHtml.defaults = {
     'alt'
   ],
   // Lots of these won't come up by default because we don't allow them
-  selfClosing: [ 'img', 'br', 'hr', 'area', 'base', 'basefont', 'input', 'link', 'meta' ],
+  selfClosing: [ 'img', 'br', 'hr', 'area', 'base', 'basefont', 'input', 'link', 'meta', 'col' ],
   // URL schemes we permit
   allowedSchemes: [ 'http', 'https', 'ftp', 'mailto', 'tel' ],
   allowedSchemesByTag: {},

package/node_modules/sanitize-html/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sanitize-html",
-  "version": "2.17.5",
+  "version": "2.17.7",
   "description": "Clean up user-submitted HTML, preserving allowlisted elements and allowlisted attributes on a per-element basis",
   "sideEffects": false,
   "main": "index.js",
@@ -21,10 +21,13 @@
   ],
   "author": "Apostrophe Technologies, Inc.",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "dependencies": {
     "deepmerge": "^4.2.2",
     "escape-string-regexp": "^4.0.0",
-    "htmlparser2": "^10.1.0",
+    "htmlparser2": "^12.0.0",
     "is-plain-object": "^5.0.0",
     "parse-srcset": "^1.0.2",
     "postcss": "^8.3.11",

package/node_modules/which/README.md

@@ -9,40 +9,37 @@ needed when the PATH changes.
 ## USAGE
 
 ```javascript
-var which = require('which')
+const which = require('which')
 
 // async usage
-which('node', function (er, resolvedPath) {
-  // er is returned if no "node" is found on the PATH
-  // if it is found, then the absolute path to the exec is returned
-})
+// rejects if not found
+const resolved = await which('node')
 
-// or promise
-which('node').then(resolvedPath => { ... }).catch(er => { ... not found ... })
+// if nothrow option is used, returns null if not found
+const resolvedOrNull = await which('node', { nothrow: true })
 
 // sync usage
 // throws if not found
-var resolved = which.sync('node')
+const resolved = which.sync('node')
 
 // if nothrow option is used, returns null if not found
-resolved = which.sync('node', {nothrow: true})
+const resolvedOrNull = which.sync('node', { nothrow: true })
 
 // Pass options to override the PATH and PATHEXT environment vars.
-which('node', { path: someOtherPath }, function (er, resolved) {
-  if (er)
-    throw er
-  console.log('found at %j', resolved)
-})
+await which('node', { path: someOtherPath, pathExt: somePathExt })
 ```
 
 ## CLI USAGE
 
-Same as the BSD `which(1)` binary.
+Just like the BSD `which(1)` binary but using `node-which`.
 
 ```
-usage: which [-as] program ...
+usage: node-which [-as] program ...
 ```
 
+You can learn more about why the binary is `node-which` and not `which` 
+[here](https://github.com/npm/node-which/pull/67)
+
 ## OPTIONS
 
 You may pass an options object as the second argument.

package/node_modules/which/package.json

@@ -1,43 +1,57 @@
 {
-  "author": "Isaac Z. Schlueter <i@izs.me> (http://blog.izs.me)",
+  "author": "GitHub Inc.",
   "name": "which",
   "description": "Like which(1) unix command. Find the first instance of an executable in the PATH.",
-  "version": "2.0.2",
+  "version": "4.0.0",
   "repository": {
     "type": "git",
-    "url": "git://github.com/isaacs/node-which.git"
+    "url": "https://github.com/npm/node-which.git"
   },
-  "main": "which.js",
+  "main": "lib/index.js",
   "bin": {
-    "node-which": "./bin/node-which"
+    "node-which": "./bin/which.js"
   },
   "license": "ISC",
   "dependencies": {
-    "isexe": "^2.0.0"
+    "isexe": "^3.1.1"
   },
   "devDependencies": {
-    "mkdirp": "^0.5.0",
-    "rimraf": "^2.6.2",
-    "tap": "^14.6.9"
+    "@npmcli/eslint-config": "^4.0.0",
+    "@npmcli/template-oss": "4.18.0",
+    "tap": "^16.3.0"
   },
   "scripts": {
     "test": "tap",
-    "preversion": "npm test",
-    "postversion": "npm publish",
-    "prepublish": "npm run changelog",
-    "prechangelog": "bash gen-changelog.sh",
-    "changelog": "git add CHANGELOG.md",
-    "postchangelog": "git commit -m 'update changelog - '${npm_package_version}",
-    "postpublish": "git push origin --follow-tags"
+    "lint": "eslint \"**/*.js\"",
+    "postlint": "template-oss-check",
+    "template-oss-apply": "template-oss-apply --force",
+    "lintfix": "npm run lint -- --fix",
+    "snap": "tap",
+    "posttest": "npm run lint"
   },
   "files": [
-    "which.js",
-    "bin/node-which"
+    "bin/",
+    "lib/"
   ],
   "tap": {
-    "check-coverage": true
+    "check-coverage": true,
+    "nyc-arg": [
+      "--exclude",
+      "tap-snapshots/**"
+    ]
   },
   "engines": {
-    "node": ">= 8"
+    "node": "^16.13.0 || >=18.0.0"
+  },
+  "templateOSS": {
+    "//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.",
+    "ciVersions": [
+      "16.13.0",
+      "16.x",
+      "18.0.0",
+      "18.x"
+    ],
+    "version": "4.18.0",
+    "publish": "true"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zowe/cli",
-  "version": "8.36.1",
+  "version": "8.37.1",
   "zoweVersion": "v3.6.0",
   "description": "Zowe CLI is a command line interface (CLI) that provides a simple and streamlined way to interact with IBM z/OS.",
   "author": "Zowe",
@@ -42,7 +42,7 @@
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "scripts": {
-    "postinstall": "node ./scripts/validatePlugins && node ./scripts/printSuccessMessage",
+    "postinstall": "node ./scripts/validatePlugins && node ./scripts/printSuccessMessage && node ./scripts/validateSecretsPrebuild",
     "build": "tsc --pretty",
     "watch": "tsc --pretty --watch",
     "clean": "rimraf lib",
@@ -55,17 +55,17 @@
     "prepublishOnly": "bash ../../scripts/bundleDaemon.sh"
   },
   "dependencies": {
-    "@zowe/core-for-zowe-sdk": "8.36.1",
-    "@zowe/imperative": "8.36.1",
-    "@zowe/provisioning-for-zowe-sdk": "8.36.1",
-    "@zowe/zos-console-for-zowe-sdk": "8.36.1",
-    "@zowe/zos-files-for-zowe-sdk": "8.36.1",
-    "@zowe/zos-jobs-for-zowe-sdk": "8.36.1",
-    "@zowe/zos-logs-for-zowe-sdk": "8.36.1",
-    "@zowe/zos-tso-for-zowe-sdk": "8.36.1",
-    "@zowe/zos-uss-for-zowe-sdk": "8.36.1",
-    "@zowe/zos-workflows-for-zowe-sdk": "8.36.1",
-    "@zowe/zosmf-for-zowe-sdk": "8.36.1",
+    "@zowe/core-for-zowe-sdk": "8.37.1",
+    "@zowe/imperative": "8.37.1",
+    "@zowe/provisioning-for-zowe-sdk": "8.37.1",
+    "@zowe/zos-console-for-zowe-sdk": "8.37.1",
+    "@zowe/zos-files-for-zowe-sdk": "8.37.1",
+    "@zowe/zos-jobs-for-zowe-sdk": "8.37.1",
+    "@zowe/zos-logs-for-zowe-sdk": "8.37.1",
+    "@zowe/zos-tso-for-zowe-sdk": "8.37.1",
+    "@zowe/zos-uss-for-zowe-sdk": "8.37.1",
+    "@zowe/zos-workflows-for-zowe-sdk": "8.37.1",
+    "@zowe/zosmf-for-zowe-sdk": "8.37.1",
     "find-process": "^1.4.7",
     "lodash": "^4.17.23",
     "minimatch": "^10.2.3",
@@ -74,13 +74,13 @@
   "devDependencies": {
     "@types/diff": "^5.0.9",
     "@types/lodash": "^4.17.6",
-    "@zowe/cli-test-utils": "8.36.1",
+    "@zowe/cli-test-utils": "8.37.1",
     "comment-json": "^4.2.3",
     "strip-ansi": "^6.0.1",
     "which": "^4.0.0"
   },
   "optionalDependencies": {
-    "@zowe/secrets-for-zowe-sdk": "8.36.1"
+    "@zowe/secrets-for-zowe-sdk": "8.37.0"
   },
   "engines": {
     "node": ">=20.9.0"

package/scripts/validateSecretsPrebuild.js

@@ -0,0 +1,231 @@
+/*
+* This program and the accompanying materials are made available under the terms of the
+* Eclipse Public License v2.0 which accompanies this distribution, and is available at
+* https://www.eclipse.org/legal/epl-v20.html
+*
+* SPDX-License-Identifier: EPL-2.0
+*
+* Copyright Contributors to the Zowe Project.
+*
+*/
+
+/* Verify that the Secrets SDK has a keyring prebuild this platform can load.
+ *
+ * @zowe/secrets-for-zowe-sdk is an optional dependency of the CLI, so npm
+ * quietly omits it whenever its install script fails - for example, when no
+ * prebuild ships for the platform and no Rust toolchain is available to build
+ * one. The CLI still installs and reports success in that state, but secure
+ * credential storage is unavailable and the only symptom the user ever sees is
+ * a "Failed to load Keytar module" error the first time a command reads a
+ * credential. This script turns that into an actionable warning at install
+ * time, while the user is still looking at the terminal.
+ *
+ * This script is run in our package.json:scripts:postinstall as:
+ *    node ./scripts/validateSecretsPrebuild.js
+ * It runs last in the chain so that any warning is the final thing printed,
+ * rather than scrolling past above the "successfully installed" message.
+ *
+ * A missing prebuild is a warning, not an error: nothing here is allowed to
+ * exit non-zero, because doing so would fail the whole `npm install`.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const SECRETS_PKG = "@zowe/secrets-for-zowe-sdk";
+const DOC_LINK = "https://github.com/zowe/zowe-cli/blob/master/packages/secrets/README.md#troubleshooting";
+
+/* The platform target that the keyring loader builds its binary file name from.
+ * Kept deliberately identical to getTargetName() in the Secrets SDK's
+ * src/keyring/index.js, so that the file name we report as missing is the exact
+ * file name the loader looked for.
+ */
+function getTargetName() {
+    switch (process.platform) {
+        case "win32":
+            return `win32-${process.arch}-msvc`;
+        case "linux": {
+            const isMusl = process.report.getReport().header.glibcVersionRuntime == null;
+            const abi = isMusl ? "musl" : "gnu";
+            return process.arch === "arm" ? `linux-arm-${abi}eabihf` : `linux-${process.arch}-${abi}`;
+        }
+        default:
+            return `${process.platform}-${process.arch}`;
+    }
+}
+
+function resolveQuietly(request) {
+    try {
+        return require.resolve(request, { paths: [__dirname, process.cwd()] });
+    } catch (_err) {
+        return undefined;
+    }
+}
+
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf-8"));
+    } catch (_err) {
+        return {};
+    }
+}
+
+/* Look for the prebuild in both places the keyring loader accepts: its own
+ * directory, where a local `npm run rebuild` writes the binary, and the
+ * package's prebuilds folder, where the published binaries live.
+ */
+function findPrebuild(pkgDir, target) {
+    const binaryName = `keyring.${target}.node`;
+    return [path.join(pkgDir, "src", "keyring"), path.join(pkgDir, "prebuilds")]
+        .map((dir) => path.join(dir, binaryName))
+        .find((file) => fs.existsSync(file));
+}
+
+/* Returns a description of what is wrong, or undefined when the Secrets SDK is
+ * usable. We only load the module - we never call into it, since reading the
+ * credential vault during an install could prompt the user for keychain access.
+ */
+function diagnose(target) {
+    const pkgJsonFile = resolveQuietly(`${SECRETS_PKG}/package.json`);
+
+    if (pkgJsonFile == null) {
+        return {
+            kind: "notInstalled",
+            problem: `${SECRETS_PKG} is not installed.`,
+            cause: "npm omits this optional dependency when its install script fails, which " +
+                "usually means no prebuild shipped for this platform and no Rust toolchain " +
+                "was available to build one."
+        };
+    }
+
+    const pkgDir = path.dirname(pkgJsonFile);
+    const version = readJson(pkgJsonFile).version;
+
+    if (findPrebuild(pkgDir, target) == null) {
+        return {
+            kind: "noPrebuild",
+            problem: `${SECRETS_PKG}@${version} contains no keyring prebuild for ${target}.`,
+            cause: `The keyring loader expects keyring.${target}.node, which is not present ` +
+                "in this installation, so the module has to be built from source here."
+        };
+    }
+
+    try {
+        const { keyring } = require(pkgDir);
+        if (typeof keyring.getPassword !== "function") {
+            return {
+                kind: "noPrebuild",
+                problem: `The keyring prebuild for ${target} loaded but is missing expected functions.`,
+                cause: `${SECRETS_PKG}@${version} looks like a partial or corrupted installation.`
+            };
+        }
+        return undefined;
+    } catch (err) {
+        return {
+            kind: "unloadable",
+            problem: `The keyring prebuild for ${target} is present but could not be loaded.`,
+            cause: `The operating system rejected the native module: ${err.message}`
+        };
+    }
+}
+
+/* The repair steps the user should follow, tailored to what we found. We do not
+ * attempt the repair ourselves: rebuilding a native module needs prerequisites
+ * we cannot install, and re-entering npm from inside a lifecycle script is not
+ * safe.
+ */
+function repairSteps(problem) {
+    const isGlobal = process.env.npm_config_global === "true";
+    const cliVersion = readJson(path.join(process.cwd(), "package.json")).version;
+    const reinstall = isGlobal
+        ? `npm install -g @zowe/cli@${cliVersion} --foreground-scripts`
+        : "npm install --foreground-scripts";
+
+    switch (problem.kind) {
+        case "notInstalled":
+            // We cannot tell why npm skipped the package, so the first step is to
+            // make it say so out loud rather than to guess at a prerequisite.
+            return `To repair:
+
+1. Re-run the Zowe CLI install with --foreground-scripts. That prints the
+   install script output that npm hid the first time:
+
+     ${reinstall}
+
+2. Install whatever that output reports as missing, then repeat Step 1.
+   - A failed Rust/cargo command means the module had to be built from
+     source: install the toolchain from https://rustup.rs
+   - A missing shared library on Linux (e.g. libsecret-1.so.0) means the
+     libsecret runtime is absent: install it with "apt install libsecret-1-0"
+     or "yum install libsecret"`;
+
+        case "noPrebuild":
+            return `To repair:
+
+1. Install the Rust toolchain from https://rustup.rs so the keyring module
+   can be built for this platform.
+
+2. Rebuild the Secrets SDK in place, without reinstalling the CLI:
+
+     npm rebuild ${SECRETS_PKG}
+
+   If that is not an option, reinstall the CLI instead:
+
+     ${reinstall}`;
+
+        default:
+            // The binary is fine; the OS could not satisfy its dependencies. A
+            // rebuild produces the same binary, so do not suggest one.
+            return `To repair:
+
+1. Install the credential storage prerequisites for your platform. On Linux
+   this is the libsecret runtime: "apt install libsecret-1-0" or
+   "yum install libsecret".
+
+2. Re-run the failed Zowe CLI command. No reinstall is needed once the
+   prerequisites are in place.`;
+    }
+}
+
+function printWarning(problem, target) {
+    console.log(`
+Warning: Zowe CLI cannot use secure credential storage
+
+${problem.problem}
+${problem.cause}
+
+Zowe CLI is installed and will run, but it cannot store or read credentials
+securely until this is resolved. Commands that need a stored credential fail
+with "Failed to load Keytar module".
+
+${repairSteps(problem)}
+
+Detected platform: ${target} (node ${process.version})
+Full troubleshooting steps:
+  ${DOC_LINK}
+`);
+}
+
+function validateSecretsPrebuild() {
+    /* Only check an end-user install. A source checkout that has not been built
+     * yet has no lib/main.js and no compiled Secrets SDK either, so checking
+     * there would warn every contributor who runs `npm install` before
+     * `npm run build`. This is the same guard validatePlugins.js uses.
+     */
+    if (!fs.existsSync(path.join(process.cwd(), "lib", "main.js"))) {
+        return;
+    }
+
+    const target = getTargetName();
+    const problem = diagnose(target);
+    if (problem != null) {
+        printWarning(problem, target);
+    }
+}
+
+try {
+    validateSecretsPrebuild();
+} catch (err) {
+    // A diagnostic must never break an install, so swallow anything unexpected.
+    console.log(`Could not verify secure credential storage for Zowe CLI: ${err.message}`);
+}