@cats-inc/cats-platform 0.2.8 → 0.3.5

package/scripts/build-desktop-installer.mjs

@@ -37,8 +37,9 @@ Options:
   --skip-mobile                           Skip the mobile bundle (\`expo export\`). Also honored via
                                           CATS_SKIP_MOBILE=1 in the environment or .env.
   --release                               Build an official release package: embed the release
-                                          descriptor, require platform signing credentials, and
-                                          allow signing identity discovery. Requires a GitHub
+                                          descriptor, require platform signing credentials (plus
+                                          macOS notarization credentials), and allow signing
+                                          identity discovery. Requires a GitHub
                                           Actions tag run whose tag matches the package version.
                                           Also honored via CATS_DESKTOP_RELEASE_MODE=1.
   --preview                               Build an unsupported unsigned GitHub prerelease preview.
@@ -46,6 +47,12 @@ Options:
                                           omits the official descriptor, and disables signing
                                           identity discovery. Also honored via
                                           CATS_DESKTOP_PREVIEW_MODE=1.
+  --sign                                  Let local packaging use a signing identity from the
+                                          OS keychain. Off by default so an unconfigured machine
+                                          cannot pick up an unrelated certificate. Ignored by
+                                          --release and --preview, which always sign when their
+                                          credentials are present. Also honored via
+                                          CATS_DESKTOP_SIGN_LOCAL=1.
   --publish <never|always>                Publish policy, default never. Publishing requires
                                           --release or --preview plus a GitHub token. Also honored
                                           via CATS_DESKTOP_PUBLISH.
@@ -99,6 +106,7 @@ export function parseArgs(argv, env = process.env) {
   let skipMobile = parseBooleanFlag(env.CATS_SKIP_MOBILE);
   let releaseMode = parseBooleanFlag(env.CATS_DESKTOP_RELEASE_MODE);
   let previewMode = parseBooleanFlag(env.CATS_DESKTOP_PREVIEW_MODE);
+  let allowLocalSigning = parseBooleanFlag(env.CATS_DESKTOP_SIGN_LOCAL);
   let publish = resolvePublishPolicy(env.CATS_DESKTOP_PUBLISH);
   // GITHUB_REF_NAME is a runner-provided default. A workflow `env:` block
   // cannot override anything in the GITHUB_ namespace, and a preview run is
@@ -118,6 +126,7 @@ export function parseArgs(argv, env = process.env) {
         skipMobile,
         releaseMode,
         previewMode,
+        allowLocalSigning,
         publish,
         tag,
         ...(appsLock ? { appsLock } : {}),
@@ -144,6 +153,14 @@ export function parseArgs(argv, env = process.env) {
       previewMode = false;
       continue;
     }
+    if (value === '--sign') {
+      allowLocalSigning = true;
+      continue;
+    }
+    if (value === '--no-sign') {
+      allowLocalSigning = false;
+      continue;
+    }
     if (value === '--publish') {
       publish = resolvePublishPolicy(argv[index + 1] ?? '');
       index += 1;
@@ -194,6 +211,7 @@ export function parseArgs(argv, env = process.env) {
     skipMobile,
     releaseMode,
     previewMode,
+    allowLocalSigning,
     publish,
     tag,
     ...(appsLock ? { appsLock } : {}),
@@ -241,28 +259,45 @@ async function resolveCommandInvocation(command, args) {
   };
 }
 
+const MACOS_NOTARIZATION_CREDENTIAL_KEYS = [
+  'APPLE_API_KEY',
+  'APPLE_API_KEY_ID',
+  'APPLE_API_ISSUER',
+];
+
 const SIGNING_CREDENTIAL_KEYS = [
   'WIN_CSC_LINK',
   'CSC_LINK',
   'WIN_CSC_KEY_PASSWORD',
   'CSC_KEY_PASSWORD',
+  ...MACOS_NOTARIZATION_CREDENTIAL_KEYS,
 ];
 
 /**
  * Local and test packaging must never reach for a signing identity, because an
  * unconfigured machine would otherwise pick up an unrelated certificate from
- * the OS keychain. Release mode leaves identity discovery to the workflow so a
- * configured certificate can actually be used.
+ * the OS keychain. Both guarded workflow paths leave identity discovery alone
+ * so a configured certificate can actually be used.
+ *
+ * ADR-117: a preview is signed on any platform whose credentials exist, so
+ * preview mode is a signing path too. Signing is artifact trust; it says
+ * nothing about whether the build claims official release identity.
+ *
+ * `--sign` is the local escape hatch. It is an explicit request rather than an
+ * inference from the environment, because a developer machine may hold
+ * unrelated certificates.
  *
- * Empty credential variables are dropped in both modes: electron-builder treats
+ * Empty credential variables are dropped in every mode: electron-builder treats
  * an empty CSC_LINK as a relative path and resolves it against the project
  * root.
  */
 export function buildInstallerEnvironment(baseEnv = process.env, options = {}) {
-  const releaseMode = options.releaseMode === true;
+  const signingAllowed = options.releaseMode === true
+    || options.previewMode === true
+    || options.allowLocalSigning === true;
   const env = { ...baseEnv };
 
-  if (!releaseMode) {
+  if (!signingAllowed) {
     env.CSC_IDENTITY_AUTO_DISCOVERY = 'false';
   }
 
@@ -286,6 +321,22 @@ export function hasMacosSigningCredentials(env = process.env) {
   return typeof link === 'string' && link.trim() !== '';
 }
 
+/**
+ * electron-builder reads notarization credentials straight from the
+ * environment and only warns when they are absent, so a misconfigured release
+ * would otherwise produce a signed but un-notarized app. Gatekeeper rejects
+ * that on every machine except the one that built it.
+ *
+ * App Store Connect API keys are used rather than an Apple ID and
+ * app-specific password: they are revocable on their own and survive an Apple
+ * ID password change, which a CI secret has no way to notice.
+ */
+export function hasMacosNotarizationCredentials(env = process.env) {
+  return MACOS_NOTARIZATION_CREDENTIAL_KEYS.every(
+    (key) => typeof env[key] === 'string' && env[key].trim() !== '',
+  );
+}
+
 /**
  * Signing is a release gate, not a nice-to-have.
  *
@@ -302,16 +353,53 @@ export function resolveSigningProblems({ env = process.env, target } = {}) {
     }];
   }
 
-  if (target === 'macos' && !hasMacosSigningCredentials(env)) {
-    return [{
-      code: 'release_macos_signing_missing',
-      message: 'An official macOS release requires CSC_LINK.',
-    }];
+  if (target === 'macos') {
+    const problems = [];
+    if (!hasMacosSigningCredentials(env)) {
+      problems.push({
+        code: 'release_macos_signing_missing',
+        message: 'An official macOS release requires CSC_LINK.',
+      });
+    }
+    if (!hasMacosNotarizationCredentials(env)) {
+      problems.push({
+        code: 'release_macos_notarization_missing',
+        message: 'An official macOS release requires APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER.',
+      });
+    }
+    return problems;
   }
 
   return [];
 }
 
+/**
+ * ADR-117: trust is resolved per platform from the credentials actually
+ * present. The build states which it got, because a silently unsigned artifact
+ * is indistinguishable from a signed one until a user tries to install it.
+ */
+export function describeArtifactTrust(target, env = process.env) {
+  if (target === 'linux') {
+    return 'unsigned (Linux packages are not signed)';
+  }
+
+  if (target === 'windows') {
+    return hasWindowsSigningCredentials(env)
+      ? 'signed'
+      : 'unsigned (no Windows certificate configured)';
+  }
+
+  const signed = hasMacosSigningCredentials(env);
+  const notarized = hasMacosNotarizationCredentials(env);
+  if (signed && notarized) {
+    return 'signed and notarized';
+  }
+  if (signed) {
+    return 'signed but NOT notarized (no App Store Connect API key) — Gatekeeper will reject the download';
+  }
+  return 'unsigned (no Developer ID certificate)';
+}
+
 /**
  * Release and preview publication are only meaningful inside the guarded
  * workflow. Anything else could publish from an unreviewed tree, so the
@@ -648,8 +736,14 @@ export function electronBuilderArgs(target, archOverride, formatOverride, option
   }
 
   const releaseMode = options.releaseMode === true;
+  const previewMode = options.previewMode === true;
+  // Signing overrides key off artifact trust, not release identity, so both
+  // guarded paths qualify. Local packaging never does, even with `--sign`:
+  // an ad-hoc local build has no reason to reach Apple's notary service.
+  const signedBuild = releaseMode || previewMode;
   const publish = resolvePublishPolicy(options.publish ?? 'never');
   const signWindowsExecutable = options.signWindowsExecutable === true;
+  const notarizeMacos = options.notarizeMacos === true;
   const formats = normalizeFormats(target, formatOverride);
   const platformFlag = target === 'windows' ? '--win' : target === 'macos' ? '--mac' : '--linux';
   const args = ['electron-builder', platformFlag];
@@ -667,10 +761,17 @@ export function electronBuilderArgs(target, archOverride, formatOverride, option
   // package.json pins signAndEditExecutable to false so unsigned local builds
   // avoid the winCodeSign download. A release build with real credentials has
   // to opt back in, and only then.
-  if (releaseMode && target === 'windows' && signWindowsExecutable) {
+  if (signedBuild && target === 'windows' && signWindowsExecutable) {
     args.push('-c.win.signAndEditExecutable=true');
   }
 
+  // package.json pins mac.notarize to false so an unsigned preview never waits
+  // on Apple and a half-configured environment cannot quietly ship an
+  // un-notarized build. A release build with real credentials opts back in.
+  if (signedBuild && target === 'macos' && notarizeMacos) {
+    args.push('-c.mac.notarize=true');
+  }
+
   args.push('--publish', publish);
   return args;
 }
@@ -687,7 +788,11 @@ async function main() {
   // in an OS temporary directory so retries never redownload a moving asset.
   const selectedApps = parsed.appsLock ? await resolveAppLock(resolve(parsed.appsLock)) : null;
   const appLockForBuild = selectedApps ? await materializeAppSelection(selectedApps) : null;
-  const envOptions = { releaseMode: parsed.releaseMode };
+  const envOptions = {
+    releaseMode: parsed.releaseMode,
+    previewMode: parsed.previewMode,
+    allowLocalSigning: parsed.allowLocalSigning,
+  };
 
   if (parsed.releaseMode && parsed.previewMode) {
     throw new Error('--release and --preview are mutually exclusive build modes.');
@@ -717,10 +822,11 @@ async function main() {
           .join('\n')}`,
       );
     }
-    const buildKind = parsed.releaseMode ? 'official' : 'unsigned preview';
+    const buildKind = parsed.releaseMode ? 'official' : 'preview';
     process.stdout.write(
       `[build-desktop-installer] ${buildKind} ${resolvedTarget} build for `
-        + `${process.env.GITHUB_REF_NAME} (publish=${parsed.publish}).\n`,
+        + `${process.env.GITHUB_REF_NAME} (publish=${parsed.publish}, `
+        + `trust=${describeArtifactTrust(resolvedTarget, process.env)}).\n`,
     );
   }
 
@@ -786,8 +892,10 @@ async function main() {
     'npx',
     electronBuilderArgs(resolvedTarget, parsed.arch, parsed.format, {
       releaseMode: parsed.releaseMode,
+      previewMode: parsed.previewMode,
       publish: parsed.publish,
       signWindowsExecutable: hasWindowsSigningCredentials(process.env),
+      notarizeMacos: hasMacosNotarizationCredentials(process.env),
     }),
     PROJECT_ROOT,
     {},

package/scripts/dev-server.mjs

@@ -26,7 +26,10 @@ let crashCount = 0;
 
 function spawnServer() {
   intentionalRestart = false;
-  child = spawn(process.execPath, ['--import', 'tsx', entry], {
+  child = spawn(process.execPath, [
+    '--import', 'tsx', entry,
+    '--startup-mode', 'app-managed', '--managed-by', 'dev-server', '--ready-output', 'plain',
+  ], {
     stdio: 'inherit',
     env: process.env,
   });

package/scripts/linux/install-github-cli.sh

@@ -60,6 +60,11 @@ declare -a applied_changes=()
 declare -a warnings=()
 declare -a manual_steps=()
 
+# A Desktop-launched helper may inherit PATH from before gh was installed.
+# Include our fallback destination and the supported Homebrew locations in this
+# process only; check mode must not edit the user's shell profile.
+export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+
 resolve_gh_path() {
   command -v gh 2>/dev/null || true
 }

package/scripts/linux/install-node.sh

@@ -90,7 +90,7 @@ is_node_installed() {
   if [ "$skip_node_probe" = 'true' ]; then
     return 1
   fi
-  command -v node >/dev/null 2>&1
+  command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1
 }
 
 json_array_from_lines() {
@@ -149,6 +149,12 @@ JSON
   exit "$exit_code"
 }
 
+# Desktop's environment may predate nvm installation. Load it before read-only
+# detection too; a bundled or standalone node without npm is not this substrate.
+if [ "$install_state" = 'auto' ] && [ "$skip_node_probe" = 'false' ]; then
+  load_nvm
+fi
+
 # Mode: check
 if [ "$mode" = 'check' ]; then
   if is_node_installed; then
@@ -214,10 +220,10 @@ case "$mode" in
     ;;
 esac
 
-if command -v node >/dev/null 2>&1; then
+if command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1; then
   emit_result 'ready' 'true' 0
 else
-  warnings+=('Node binary still missing after install.')
+  warnings+=('Node.js or npm is still missing after install.')
   manual_steps+=('Open a new terminal so PATH picks up the nvm-managed node binary.')
   emit_result 'failed' 'false' 1
 fi

package/scripts/linux/node-cli-common.sh

@@ -8,6 +8,7 @@ readonly CATS_PLATFORM_UNIX_NODE_COMMON_SH=1
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=provider-cli-common.sh
 . "$SCRIPT_DIR/provider-cli-common.sh"
+. "$SCRIPT_DIR/verified-npm-update.sh"
 
 normalize_npm_registry() {
   case "$1" in
@@ -52,25 +53,51 @@ ensure_node_and_npm() {
     printf 'npm is required but was not found.\n' >&2
     return 1
   fi
+  # Desktop invokes each helper in a fresh non-login shell. Read the configured
+  # prefix, never source arbitrary shell startup files to recover its commands.
+  local configured_prefix
+  configured_prefix="$(npm config get prefix 2>/dev/null || true)"
+  [ -z "$configured_prefix" ] || prepend_path_if_missing "$configured_prefix/bin"
+  return 0
+}
+
+has_explicit_npm_prefix() {
+  [ -z "${NPM_CONFIG_PREFIX:-${npm_config_prefix:-}}" ] || return 0
+  local npmrc="${NPM_CONFIG_USERCONFIG:-${npm_config_userconfig:-$HOME/.npmrc}}"
+  [ -f "$npmrc" ] && grep -qE '^[[:space:]]*prefix[[:space:]]*=' "$npmrc"
+}
+
+preferred_npm_prefix() {
+  local existing canonical_home
+  existing="$(npm config get prefix 2>/dev/null || true)"
+  if [ -n "$existing" ] && has_explicit_npm_prefix; then printf '%s\n' "$existing"; return 0; fi
+  if [ -d "$existing" ] && [ -w "$existing" ]; then
+    existing="$(cd -P -- "$existing" && pwd -P)"
+    canonical_home="$(cd -P -- "$HOME" && pwd -P)"
+    case "$existing" in "$canonical_home"/*) printf '%s\n' "$existing"; return 0 ;; esac
+  fi
+  printf '%s\n' "$HOME/.npm-global"
 }
 
 ensure_npm_global_path_export() {
-  local shell_rc="$1"
+  local shell_rc="$1" prefix="${2:-$HOME/.npm-global}" export_line
+  printf -v export_line 'export PATH=%q:$PATH' "$prefix/bin"
   append_line_if_missing "$shell_rc" '# Added by cats-platform self-hosted npm helpers' '# Added by cats-platform self-hosted npm helpers'
-  append_line_if_missing "$shell_rc" 'export PATH="$HOME/.npm-global/bin:$PATH"' 'export PATH="$HOME/.npm-global/bin:$PATH"'
-  prepend_path_if_missing "$HOME/.npm-global/bin"
+  append_line_if_missing "$shell_rc" "$export_line" "$export_line"
+  prepend_path_if_missing "$prefix/bin"
 }
 
 node_prefix_ready() {
-  local prefix
+  local prefix desired_prefix
   local registry
   local shell_rc
 
   prefix="$(npm config get prefix 2>/dev/null || printf '')"
   registry="$(normalize_npm_registry "$(npm config get registry 2>/dev/null || printf '')")"
   shell_rc="$(detect_shell_rc)"
+  desired_prefix="$(preferred_npm_prefix)"
 
-  if nvm_is_active; then
+  if nvm_is_active && ! has_explicit_npm_prefix; then
     if npmrc_has_prefix_conflict; then
       return 1
     fi
@@ -78,7 +105,7 @@ node_prefix_ready() {
     return $?
   fi
 
-  if [ "$prefix" != "$HOME/.npm-global" ]; then
+  if [ "$prefix" != "$desired_prefix" ]; then
     return 1
   fi
 
@@ -86,11 +113,11 @@ node_prefix_ready() {
     return 1
   fi
 
-  if [[ ":$PATH:" == *":$HOME/.npm-global/bin:"* ]]; then
+  if [[ ":$PATH:" == *":$desired_prefix/bin:"* ]]; then
     return 0
   fi
 
-  grep -Fq 'export PATH="$HOME/.npm-global/bin:$PATH"' "$shell_rc" 2>/dev/null
+  return 1
 }
 
 node_prefix_help() {
@@ -119,7 +146,7 @@ run_node_prefix_setup() {
   local force='false'
   local emit_json='false'
   local shell_rc
-  local prefix
+  local prefix desired_prefix
   local registry
   local status='ready'
   local execution_mode='apply'
@@ -170,6 +197,7 @@ run_node_prefix_setup() {
     execution_mode='apply'
   fi
 
+  desired_prefix="$HOME/.npm-global"
   load_nvm_if_present
   if ! ensure_node_and_npm; then
     if [ "$emit_json" = 'true' ]; then
@@ -178,7 +206,7 @@ run_node_prefix_setup() {
       printf '"mode":"%s",' "$execution_mode"
       printf '"status":"failed",'
       printf '"restartRequired":false,'
-      printf '"desiredPrefix":"%s",' "$(json_escape "$HOME/.npm-global")"
+      printf '"desiredPrefix":"%s",' "$(json_escape "$desired_prefix")"
       printf '"shellRc":"%s",' "$(json_escape "$(detect_shell_rc)")"
       printf '"plannedActions":[],'
       printf '"appliedChanges":[],'
@@ -191,10 +219,11 @@ run_node_prefix_setup() {
   fi
 
   shell_rc="$(detect_shell_rc)"
+  desired_prefix="$(preferred_npm_prefix)"
   prefix="$(npm config get prefix 2>/dev/null || printf '')"
   registry="$(normalize_npm_registry "$(npm config get registry 2>/dev/null || printf '')")"
 
-  if nvm_is_active; then
+  if nvm_is_active && ! has_explicit_npm_prefix; then
     if npmrc_has_prefix_conflict; then
       planned_actions+=('clear_npm_prefix_conflict')
     fi
@@ -202,13 +231,13 @@ run_node_prefix_setup() {
       planned_actions+=('set_npm_registry')
     fi
   else
-    if [ "$prefix" != "$HOME/.npm-global" ]; then
+    if [ "$prefix" != "$desired_prefix" ]; then
       planned_actions+=('set_npm_prefix')
     fi
     if [ "$registry" != 'https://registry.npmjs.org/' ]; then
       planned_actions+=('set_npm_registry')
     fi
-    if [[ ":$PATH:" != *":$HOME/.npm-global/bin:"* ]]; then
+    if [[ ":$PATH:" != *":$desired_prefix/bin:"* ]]; then
       planned_actions+=('repair_npm_global_path')
     fi
   fi
@@ -224,7 +253,7 @@ run_node_prefix_setup() {
       printf '"mode":"check",'
       printf '"status":"%s",' "$status"
       printf '"restartRequired":false,'
-      printf '"desiredPrefix":"%s",' "$(json_escape "$HOME/.npm-global")"
+      printf '"desiredPrefix":"%s",' "$(json_escape "$desired_prefix")"
       printf '"shellRc":"%s",' "$(json_escape "$shell_rc")"
       printf '"plannedActions":'
       json_string_array "${planned_actions[@]}"
@@ -251,7 +280,7 @@ run_node_prefix_setup() {
       printf '"mode":"%s",' "$execution_mode"
       printf '"status":"ready",'
       printf '"restartRequired":false,'
-      printf '"desiredPrefix":"%s",' "$(json_escape "$HOME/.npm-global")"
+      printf '"desiredPrefix":"%s",' "$(json_escape "$desired_prefix")"
       printf '"shellRc":"%s",' "$(json_escape "$shell_rc")"
       printf '"plannedActions":[],'
       printf '"appliedChanges":[],'
@@ -265,7 +294,7 @@ run_node_prefix_setup() {
     return 0
   fi
 
-  if nvm_is_active; then
+  if nvm_is_active && ! has_explicit_npm_prefix; then
     nvm use --delete-prefix "$(node -v)" --silent >/dev/null 2>&1 || true
     npm config delete prefix >/dev/null 2>&1 || true
     npm config delete globalconfig >/dev/null 2>&1 || true
@@ -275,10 +304,10 @@ run_node_prefix_setup() {
       applied_changes+=('clear_npm_prefix_conflict')
     fi
   else
-    mkdir -p "$HOME/.npm-global"
-    npm config set prefix "$HOME/.npm-global"
+    mkdir -p "$desired_prefix"
+    npm config set prefix "$desired_prefix"
     npm config set registry 'https://registry.npmjs.org/'
-    ensure_npm_global_path_export "$shell_rc"
+    ensure_npm_global_path_export "$shell_rc" "$desired_prefix"
     applied_changes+=('set_npm_prefix' 'set_npm_registry' 'repair_npm_global_path')
   fi
 
@@ -294,7 +323,7 @@ run_node_prefix_setup() {
     printf '"mode":"%s",' "$execution_mode"
     printf '"status":"%s",' "$status"
     printf '"restartRequired":false,'
-    printf '"desiredPrefix":"%s",' "$(json_escape "$HOME/.npm-global")"
+    printf '"desiredPrefix":"%s",' "$(json_escape "$desired_prefix")"
     printf '"shellRc":"%s",' "$(json_escape "$shell_rc")"
     printf '"plannedActions":'
     json_string_array "${planned_actions[@]}"
@@ -340,8 +369,8 @@ remove_superseded_npm_packages() {
   while IFS= read -r legacy; do
     [ -n "$legacy" ] || continue
     npm list -g "$legacy" --depth=0 >/dev/null 2>&1 || continue
-    printf 'Removing superseded package %s (replaced by %s).\n' "$legacy" "$package_name"
-    npm uninstall -g "$legacy" >/dev/null 2>&1 || true
+    printf 'Removing superseded package %s (replaced by %s).\n' "$legacy" "$package_name" >&2
+    npm uninstall -g "$legacy" >/dev/null 2>&1 || return 1
   done <<EOF
 $(node_cli_superseded_packages "$package_name")
 EOF
@@ -1081,9 +1110,6 @@ run_npm_cli_provider() {
     shift
   done
 
-  if [ "$check_only" != 'true' ] && [ "$uninstall" != 'true' ]; then
-    remove_superseded_npm_packages "$package_name"
-  fi
 
   if [ "$force" = 'true' ]; then
     upgrade='false'
@@ -1134,7 +1160,17 @@ run_npm_cli_provider() {
   if command -v "$command_name" >/dev/null 2>&1 || npm list -g "$package_name" --depth=0 >/dev/null 2>&1; then
     installed='true'
     command_path="$(command -v "$command_name" 2>/dev/null || true)"
-    detected_version="$(npm list -g --depth=0 --json "$package_name" 2>/dev/null | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' | head -1)"
+    detected_version="$( (npm list -g --depth=0 --json "$package_name" 2>/dev/null || true) | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{try{console.log(JSON.parse(s).dependencies?.[process.argv[1]]?.version||"")}catch{}})' "$package_name")"
+  fi
+
+  if [ "$installed" = true ] && [ -z "$detected_version" ]; then
+    local legacy
+    while IFS= read -r legacy; do
+      [ -n "$legacy" ] || continue
+      if npm list -g "$legacy" --depth=0 >/dev/null 2>&1; then installed=false; break; fi
+    done <<LEGACY_EOF
+$(node_cli_superseded_packages "$package_name")
+LEGACY_EOF
   fi
 
   if [ "$execution_mode" = 'uninstall' ]; then
@@ -1208,13 +1244,15 @@ run_npm_cli_provider() {
     return 0
   fi
 
-  local is_outdated='false'
-  if [ "$upgrade" = 'true' ] || [ "$force" = 'true' ]; then
-    if [ "$installed" = 'true' ]; then
-      if npm outdated -g "$package_name" --json 2>/dev/null | grep -q "\"$package_name\""; then
-        is_outdated='true'
-      fi
-    fi
+  local is_outdated=false expected_version=''
+  if [ "$check_only" = false ] && [ "$uninstall" = false ] && [ "$dry_run" = false ] && { [ "$upgrade" = true ] || [ "$force" = true ] || [ "$installed" = false ]; }; then
+    if [ "$upgrade" = true ]; then cats_upgrade_npm || return 1; fi
+    expected_version="$(npm view "${package_name}@latest" version --fetch-retries=0 --fetch-timeout=10000 --loglevel=error)" || { printf 'Provider version query failed.\n' >&2; return 1; }
+    [[ "$expected_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9._-]+)?$ ]] || { printf 'Invalid provider version metadata.\n' >&2; return 1; }
+    local comparison
+    comparison="$(cats_version_compare "$detected_version" "$expected_version")"
+    if [ -z "$detected_version" ] || [ "$comparison" = -1 ]; then is_outdated=true
+    elif [ "$comparison" = 0 ] && [[ "$detected_version" == *-* ]] && [[ "$expected_version" != *-* ]]; then is_outdated=true; fi
   fi
 
   local planned_action='skip'
@@ -1293,25 +1331,26 @@ run_npm_cli_provider() {
   fi
 
   local applied=()
-  case "$planned_action" in
-    install)
-      npm install -g --include=optional "$package_name" >/dev/null
-      applied+=("${package_name}:install")
-      ;;
-    upgrade)
-      npm install -g --include=optional "${package_name}@latest" >/dev/null
-      applied+=("${package_name}:upgrade")
-      ;;
-    reinstall)
-      npm install -g --include=optional "$package_name" --force >/dev/null
-      applied+=("${package_name}:reinstall")
-      ;;
-  esac
+  if [ "$dry_run" = true ]; then
+    printf '{"helper":"%s","mode":"%s","status":"preview","plannedActions":["%s:%s"],"appliedChanges":[],"warnings":[],"manualSteps":[],"interruptions":[]}\n' "$helper_id" "$execution_mode" "$package_name" "$planned_action"
+    return 0
+  fi
+  if [ "$check_only" != 'true' ] && [ "$dry_run" != 'true' ]; then
+    remove_superseded_npm_packages "$package_name"
+  fi
+  npm install -g --include=optional --engine-strict --fetch-retries=0 --fetch-timeout=30000 "${package_name}@${expected_version}" >/dev/null || return 1
+  applied+=("${package_name}:${planned_action}")
+  hash -r
 
   local final_command_path
   final_command_path="$(command -v "$command_name" 2>/dev/null || true)"
   local final_version
-  final_version="$(npm list -g --depth=0 --json "$package_name" 2>/dev/null | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' | head -1)"
+  final_version="$(npm list -g --depth=0 --json "$package_name" 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{try{console.log(JSON.parse(s).dependencies?.[process.argv[1]]?.version||"")}catch{}})' "$package_name")"
+
+  if [ -z "$final_command_path" ] || [ "$final_version" != "$expected_version" ]; then
+    printf 'Provider verification failed. Check npm prefix and PATH.\n' >&2
+    return 1
+  fi
 
   if [ "$emit_json" = 'true' ]; then
     printf '{'