@topogram/cli 0.3.64 → 0.3.66

package/src/cli/commands/migrate.js

@@ -0,0 +1,153 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../../format.js";
+import {
+  DEFAULT_TOPO_FOLDER_NAME,
+  DEFAULT_WORKSPACE_PATH,
+  LEGACY_TOPOGRAM_FOLDER_NAME,
+  PROJECT_CONFIG_FILE
+} from "../../workspace-paths.js";
+
+/**
+ * @param {string|null|undefined} inputPath
+ * @returns {string}
+ */
+function projectRootForMigration(inputPath) {
+  const absolute = path.resolve(inputPath || ".");
+  const base = path.basename(absolute);
+  if (base === DEFAULT_TOPO_FOLDER_NAME || base === LEGACY_TOPOGRAM_FOLDER_NAME) {
+    return path.dirname(absolute);
+  }
+  return absolute;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {string[]}
+ */
+function caseCollisionEntries(projectRoot) {
+  if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
+    return [];
+  }
+  return fs.readdirSync(projectRoot)
+    .filter((/** @type {string} */ entry) => entry.toLowerCase() === DEFAULT_TOPO_FOLDER_NAME && entry !== DEFAULT_TOPO_FOLDER_NAME);
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ write: boolean, path: string|null, before: any|null, after: any|null }}
+ */
+function plannedProjectConfigUpdate(projectRoot) {
+  const configPath = path.join(projectRoot, PROJECT_CONFIG_FILE);
+  if (!fs.existsSync(configPath)) {
+    return { write: false, path: null, before: null, after: null };
+  }
+  const before = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  const after = { ...before };
+  const currentWorkspace = before.workspace;
+  if (currentWorkspace == null || currentWorkspace === "./topogram" || currentWorkspace === "topogram") {
+    after.workspace = DEFAULT_WORKSPACE_PATH;
+  }
+  return {
+    write: JSON.stringify(before) !== JSON.stringify(after),
+    path: configPath,
+    before,
+    after
+  };
+}
+
+/**
+ * @param {string|null|undefined} inputPath
+ * @param {{ write?: boolean, json?: boolean }} [options]
+ * @returns {number}
+ */
+export function runMigrateCommand(inputPath, options = {}) {
+  const projectRoot = projectRootForMigration(inputPath);
+  const legacyPath = path.join(projectRoot, LEGACY_TOPOGRAM_FOLDER_NAME);
+  const topoPath = path.join(projectRoot, DEFAULT_TOPO_FOLDER_NAME);
+  const write = Boolean(options.write);
+  /** @type {Array<Record<string, any>>} */
+  const diagnostics = [];
+  /** @type {Array<Record<string, any>>} */
+  const actions = [];
+
+  if (fs.existsSync(legacyPath) && fs.lstatSync(legacyPath).isSymbolicLink()) {
+    diagnostics.push({ severity: "error", message: `Refusing to migrate symlinked ${LEGACY_TOPOGRAM_FOLDER_NAME}/ at ${legacyPath}.` });
+  }
+  const collisions = caseCollisionEntries(projectRoot);
+  if (collisions.length > 0) {
+    diagnostics.push({ severity: "error", message: `Refusing to migrate because case-conflicting topo path(s) exist: ${collisions.join(", ")}.` });
+  }
+  if (fs.existsSync(legacyPath) && fs.existsSync(topoPath)) {
+    diagnostics.push({ severity: "error", message: `Refusing to migrate because both ${LEGACY_TOPOGRAM_FOLDER_NAME}/ and ${DEFAULT_TOPO_FOLDER_NAME}/ exist.` });
+  }
+  if (!fs.existsSync(legacyPath) && !fs.existsSync(topoPath)) {
+    diagnostics.push({ severity: "error", message: `No ${LEGACY_TOPOGRAM_FOLDER_NAME}/ or ${DEFAULT_TOPO_FOLDER_NAME}/ workspace folder found at ${projectRoot}.` });
+  }
+  if (fs.existsSync(topoPath) && fs.statSync(topoPath).isDirectory() && fs.readdirSync(topoPath).length > 0 && fs.existsSync(legacyPath)) {
+    diagnostics.push({ severity: "error", message: `Refusing to overwrite non-empty ${DEFAULT_TOPO_FOLDER_NAME}/ at ${topoPath}.` });
+  }
+
+  if (fs.existsSync(legacyPath) && diagnostics.length === 0) {
+    actions.push({
+      kind: "rename",
+      from: legacyPath,
+      to: topoPath
+    });
+  }
+  const configUpdate = plannedProjectConfigUpdate(projectRoot);
+  if (configUpdate.write) {
+    actions.push({
+      kind: "update_config",
+      path: configUpdate.path,
+      workspace: DEFAULT_WORKSPACE_PATH
+    });
+  }
+
+  const ok = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length === 0;
+  if (ok && write) {
+    for (const action of actions) {
+      if (action.kind === "rename") {
+        fs.renameSync(action.from, action.to);
+      }
+      if (action.kind === "update_config" && configUpdate.path && configUpdate.after) {
+        fs.writeFileSync(configUpdate.path, `${JSON.stringify(configUpdate.after, null, 2)}\n`, "utf8");
+      }
+    }
+  }
+
+  const payload = {
+    ok,
+    dryRun: !write,
+    projectRoot,
+    legacyPath,
+    topoPath,
+    actions,
+    diagnostics,
+    errors: diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message)
+  };
+  if (options.json) {
+    console.log(stableStringify(payload));
+  } else if (payload.ok) {
+    console.log(write ? "Workspace folder migration complete." : "Workspace folder migration dry run.");
+    if (actions.length === 0) {
+      console.log("No changes needed.");
+    }
+    for (const action of actions) {
+      if (action.kind === "rename") {
+        console.log(`Rename: ${action.from} -> ${action.to}`);
+      }
+      if (action.kind === "update_config") {
+        console.log(`Update ${action.path}: workspace ${DEFAULT_WORKSPACE_PATH}`);
+      }
+    }
+  } else {
+    for (const error of payload.errors) {
+      console.error(error);
+    }
+  }
+  return payload.ok ? 0 : 1;
+}

package/src/cli/commands/package/constants.js

@@ -0,0 +1,17 @@
+// @ts-check
+
+export const CLI_PACKAGE_NAME = "@topogram/cli";
+export const NPMJS_REGISTRY = "https://registry.npmjs.org";
+
+export const PACKAGE_UPDATE_CLI_CHECK_SCRIPTS = [
+  "cli:surface",
+  "doctor",
+  "catalog:show",
+  "catalog:template-show",
+  "check",
+  "pack:check",
+  "verify"
+];
+export const PACKAGE_UPDATE_CLI_INFO_SCRIPTS = ["cli:surface", "doctor", "catalog:show", "catalog:template-show"];
+export const PACKAGE_UPDATE_CLI_VERIFICATION_SCRIPTS = ["verify", "pack:check", "check"];
+export const ENGINE_ROOT = decodeURIComponent(new URL("../../../../", import.meta.url).pathname);

package/src/cli/commands/package/doctor.js

@@ -0,0 +1,240 @@
+// @ts-check
+
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  catalogDoctorPackageDiagnostic,
+  runNpmViewPackageSpec
+} from "../catalog.js";
+import { CLI_PACKAGE_NAME, ENGINE_ROOT } from "./constants.js";
+import { compareSemver } from "./versions.js";
+
+/**
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+export function readProjectCliDependencySpec(cwd) {
+  const packagePath = path.join(cwd, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    return null;
+  }
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+    const dependencies = {
+      ...(pkg.dependencies && typeof pkg.dependencies === "object" ? pkg.dependencies : {}),
+      ...(pkg.devDependencies && typeof pkg.devDependencies === "object" ? pkg.devDependencies : {})
+    };
+    const spec = dependencies[CLI_PACKAGE_NAME];
+    return typeof spec === "string" && spec ? spec : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string|null} spec
+ * @returns {boolean}
+ */
+export function isLocalCliDependencySpec(spec) {
+  if (!spec) {
+    return false;
+  }
+  return spec.startsWith("file:") ||
+    spec.startsWith(".") ||
+    spec.startsWith("/") ||
+    spec.endsWith(".tgz");
+}
+
+/**
+ * @returns {{ version: string, minimum: string, ok: boolean, diagnostics: any[] }}
+ */
+export function checkDoctorNode() {
+  const version = process.version;
+  const minimum = "20.0.0";
+  const ok = compareSemver(version.replace(/^v/, ""), minimum) >= 0;
+  return {
+    version,
+    minimum: `>=${minimum}`,
+    ok,
+    diagnostics: ok ? [] : [{
+      code: "node_version_unsupported",
+      severity: "error",
+      message: `Topogram requires Node.js >=${minimum}; current version is ${version}.`,
+      path: null,
+      suggestedFix: "Install Node.js 20 or newer."
+    }]
+  };
+}
+
+/**
+ * @returns {{ available: boolean, version: string|null, diagnostics: any[] }}
+ */
+export function checkDoctorNpm() {
+  const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
+  const result = childProcess.spawnSync(npmBin, ["--version"], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      PATH: process.env.PATH || ""
+    }
+  });
+  if (result.status === 0) {
+    return {
+      available: true,
+      version: String(result.stdout || "").trim() || null,
+      diagnostics: []
+    };
+  }
+  return {
+    available: false,
+    version: null,
+    diagnostics: [{
+      code: "npm_not_found",
+      severity: "error",
+      message: "npm was not found on PATH.",
+      path: null,
+      suggestedFix: "Install Node.js/npm, then rerun `topogram doctor`."
+    }]
+  };
+}
+
+/**
+ * @returns {string}
+ */
+export function readInstalledCliPackageVersion() {
+  const packagePath = path.join(ENGINE_ROOT, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    return "0.0.0";
+  }
+  const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+}
+
+/**
+ * @param {string} key
+ * @returns {string|null}
+ */
+export function npmConfigGet(key) {
+  const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
+  const result = childProcess.spawnSync(npmBin, ["config", "get", key], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      PATH: process.env.PATH || ""
+    }
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  const value = String(result.stdout || "").trim();
+  return value && value !== "undefined" && value !== "null" ? value : null;
+}
+
+/**
+ * @param {string} packageSpec
+ * @returns {{ ok: boolean, checkedVersion: string|null, diagnostics: any[] }}
+ */
+export function checkDoctorPackageAccess(packageSpec) {
+  const result = runNpmViewPackageSpec(packageSpec);
+  if (result.status === 0) {
+    return {
+      ok: true,
+      checkedVersion: String(result.stdout || "").trim().replace(/^"|"$/g, "") || null,
+      diagnostics: []
+    };
+  }
+  return {
+    ok: false,
+    checkedVersion: null,
+    diagnostics: [doctorPackageDiagnostic(packageSpec, result)]
+  };
+}
+
+/**
+ * @param {string} spec
+ * @returns {string|null}
+ */
+export function registryPackageNameFromSpec(spec) {
+  if (!spec || spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("file:") || spec.endsWith(".tgz")) {
+    return null;
+  }
+  if (spec.startsWith("@")) {
+    const parts = spec.split("/");
+    if (parts.length < 2) {
+      return null;
+    }
+    return `${parts[0]}/${parts[1].replace(/@[^@]+$/, "")}`;
+  }
+  return spec.replace(/@[^@]+$/, "");
+}
+
+/**
+ * @param {string} packageSpec
+ * @returns {{ ok: boolean, package: string|null, packageSpec: string, currentVersion: string|null, latestVersion: string|null, current: boolean|null, diagnostics: any[] }}
+ */
+export function checkTemplatePackageStatus(packageSpec) {
+  const packageName = registryPackageNameFromSpec(packageSpec);
+  if (!packageName) {
+    return {
+      ok: true,
+      package: null,
+      packageSpec,
+      currentVersion: null,
+      latestVersion: null,
+      current: null,
+      diagnostics: []
+    };
+  }
+  const access = checkDoctorPackageAccess(packageSpec);
+  const latest = checkDoctorPackageAccess(`${packageName}@latest`);
+  const currentVersion = access.checkedVersion;
+  const latestVersion = latest.checkedVersion;
+  return {
+    ok: access.ok && latest.ok,
+    package: packageName,
+    packageSpec,
+    currentVersion,
+    latestVersion,
+    current: currentVersion && latestVersion ? currentVersion === latestVersion : null,
+    diagnostics: [...access.diagnostics, ...latest.diagnostics]
+  };
+}
+
+/**
+ * @param {string} packageSpec
+ * @returns {{ checked: false, ok: null, package: string|null, packageSpec: string, currentVersion: null, latestVersion: null, current: null, reason: string, diagnostics: any[] }}
+ */
+export function localTemplatePackageStatus(packageSpec) {
+  return {
+    checked: false,
+    ok: null,
+    package: registryPackageNameFromSpec(packageSpec),
+    packageSpec,
+    currentVersion: null,
+    latestVersion: null,
+    current: null,
+    reason: "Package registry checks were skipped because --local was used.",
+    diagnostics: []
+  };
+}
+
+/**
+ * @param {string} packageSpec
+ * @param {{ stdout?: string, stderr?: string, error?: Error }} result
+ * @returns {any}
+ */
+function doctorPackageDiagnostic(packageSpec, result) {
+  const diagnostic = catalogDoctorPackageDiagnostic({
+    id: CLI_PACKAGE_NAME,
+    kind: "package",
+    package: CLI_PACKAGE_NAME,
+    defaultVersion: packageSpec.slice(`${CLI_PACKAGE_NAME}@`.length)
+  }, packageSpec, result);
+  return {
+    ...diagnostic,
+    code: diagnostic.code.replace(/^catalog_package_/, "package_registry_"),
+    path: CLI_PACKAGE_NAME
+  };
+}

package/src/cli/commands/package/help.js

@@ -0,0 +1,27 @@
+// @ts-check
+
+import { PACKAGE_UPDATE_CLI_CHECK_SCRIPTS } from "./constants.js";
+
+/**
+ * @returns {void}
+ */
+export function printPackageHelp() {
+  console.log("Usage: topogram package update-cli <version|--latest> [--json]");
+  console.log("");
+  console.log("Updates a consumer project to a Topogram CLI version and runs verification when dependencies are current.");
+  console.log("");
+  console.log("Behavior:");
+  console.log("  - npmjs package inspection confirms the requested public CLI version.");
+  console.log("  - npm install updates package.json and package-lock.json.");
+  console.log("  - Available consumer verification scripts run after install.");
+  console.log(`  - Recognized scripts: ${PACKAGE_UPDATE_CLI_CHECK_SCRIPTS.join(", ")}.`);
+  console.log("  - Verification scripts are selected by strength: verify, then pack:check, then check.");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram package update-cli 0.3.5");
+  console.log("  topogram package update-cli --latest");
+  console.log("  topogram package update-cli --latest --json");
+  console.log("");
+  console.log("Auth help:");
+  console.log("  topogram setup package-auth");
+}

package/src/cli/commands/package/lockfile.js

@@ -0,0 +1,135 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { CLI_PACKAGE_NAME, NPMJS_REGISTRY } from "./constants.js";
+import { readProjectCliDependencySpec } from "./doctor.js";
+import { messageFromError } from "./shared.js";
+import { normalizeRegistryUrl } from "./versions.js";
+
+/**
+ * Remove stale tarball metadata for the CLI package before npm installs the
+ * requested version. npm package registry can repack publish metadata, so copying a
+ * local npm-pack resolved URL or integrity into a consumer lockfile can make
+ * npm ci fail with a checksum mismatch.
+ *
+ * @param {string} cwd
+ * @param {string} version
+ * @returns {boolean}
+ */
+export function sanitizeTopogramLockForPackageUpdate(cwd, version) {
+  const lockPath = path.join(cwd, "package-lock.json");
+  if (!fs.existsSync(lockPath)) {
+    return false;
+  }
+  const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+  const packages = lock && typeof lock === "object" && lock.packages && typeof lock.packages === "object"
+    ? lock.packages
+    : null;
+  const packageEntry = packages?.[`node_modules/${CLI_PACKAGE_NAME}`];
+  if (!packageEntry || typeof packageEntry !== "object" || packageEntry.version !== version) {
+    return false;
+  }
+  let changed = false;
+  for (const key of ["resolved", "integrity"]) {
+    if (Object.prototype.hasOwnProperty.call(packageEntry, key)) {
+      delete packageEntry[key];
+      changed = true;
+    }
+  }
+  if (changed) {
+    fs.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+  }
+  return changed;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {{ checked: boolean, path: string, packageVersion: string|null, dependencySpec: string|null, hasTarballMetadata: boolean, resolvedVersion: string|null, refreshRecommended: boolean, diagnostics: Array<Record<string, any>> }}
+ */
+export function inspectTopogramCliLockfile(cwd) {
+  const lockPath = path.join(cwd, "package-lock.json");
+  /** @type {{ checked: boolean, path: string, packageVersion: string|null, dependencySpec: string|null, hasTarballMetadata: boolean, resolvedVersion: string|null, refreshRecommended: boolean, diagnostics: Array<Record<string, any>> }} */
+  const result = {
+    checked: false,
+    path: lockPath,
+    packageVersion: null,
+    dependencySpec: readProjectCliDependencySpec(cwd),
+    hasTarballMetadata: false,
+    resolvedVersion: null,
+    refreshRecommended: false,
+    diagnostics: []
+  };
+  if (!fs.existsSync(lockPath)) {
+    return result;
+  }
+  result.checked = true;
+  try {
+    const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    const entry = lock?.packages?.[`node_modules/${CLI_PACKAGE_NAME}`];
+    if (!entry || typeof entry !== "object") {
+      return result;
+    }
+    result.packageVersion = typeof entry.version === "string" ? entry.version : null;
+    const resolved = typeof entry.resolved === "string" ? entry.resolved : null;
+    result.resolvedVersion = resolved ? resolvedTopogramCliVersion(resolved) : null;
+    result.hasTarballMetadata = Object.prototype.hasOwnProperty.call(entry, "resolved") ||
+      Object.prototype.hasOwnProperty.call(entry, "integrity");
+    const conventionVersion = readTopogramCliVersionConvention(cwd);
+    const resolvedVersionMismatch = Boolean(result.packageVersion && result.resolvedVersion && result.resolvedVersion !== result.packageVersion);
+    const normalizedResolved = normalizeRegistryUrl(resolved);
+    const normalizedRegistry = normalizeRegistryUrl(NPMJS_REGISTRY) || NPMJS_REGISTRY;
+    const npmjsTarball = Boolean(normalizedResolved && normalizedResolved.startsWith(`${normalizedRegistry}/`));
+    const localTarballMetadata = Boolean(resolved && (
+      /^file:/.test(resolved) ||
+      (!npmjsTarball && /\.tgz(?:$|[?#])/.test(resolved))
+    ));
+    result.refreshRecommended = Boolean(
+      result.packageVersion &&
+      conventionVersion &&
+      conventionVersion === result.packageVersion &&
+      (resolvedVersionMismatch || localTarballMetadata)
+    );
+    if (result.refreshRecommended) {
+      result.diagnostics.push({
+        code: "topogram_cli_lockfile_refresh_available",
+        severity: "warning",
+        message: "package-lock.json contains stale Topogram CLI tarball metadata for the pinned version.",
+        path: lockPath,
+        suggestedFix: `Run \`topogram package update-cli ${result.packageVersion}\` to refresh from npm registry metadata.`
+      });
+    }
+  } catch (error) {
+    result.diagnostics.push({
+      code: "topogram_cli_lockfile_unreadable",
+      severity: "warning",
+      message: `Could not inspect package-lock.json: ${messageFromError(error)}`,
+      path: lockPath,
+      suggestedFix: "Regenerate package-lock.json with npm install."
+    });
+  }
+  return result;
+}
+
+/**
+ * @param {string} resolved
+ * @returns {string|null}
+ */
+function resolvedTopogramCliVersion(resolved) {
+  const match = resolved.match(/\/@topogram\/cli\/-\/cli-([^/.?#]+(?:\.[^/.?#]+){2}(?:[-+][^/?#]+)?)\.tgz/);
+  return match ? match[1] : null;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+export function readTopogramCliVersionConvention(cwd) {
+  const versionPath = path.join(cwd, "topogram-cli.version");
+  if (!fs.existsSync(versionPath)) {
+    return null;
+  }
+  const value = fs.readFileSync(versionPath, "utf8").trim();
+  return value || null;
+}

package/src/cli/commands/package/npm.js

@@ -0,0 +1,97 @@
+// @ts-check
+
+import childProcess from "node:child_process";
+
+import { localNpmrcEnv } from "../../../npm-safety.js";
+import { CLI_PACKAGE_NAME, NPMJS_REGISTRY } from "./constants.js";
+import { isPackageVersion } from "./versions.js";
+
+/**
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {any}
+ */
+export function runNpmForPackageUpdate(args, cwd) {
+  const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
+  return childProcess.spawnSync(npmBin, args, {
+    cwd,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      ...localNpmrcEnv(cwd),
+      PATH: process.env.PATH || ""
+    }
+  });
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function latestTopogramCliVersion(cwd) {
+  const result = runNpmForPackageUpdate(["view", "--json", `--registry=${NPMJS_REGISTRY}`, "--", CLI_PACKAGE_NAME, "version"], cwd);
+  if (result.status !== 0) {
+    throw new Error(formatPackageUpdateNpmError(`${CLI_PACKAGE_NAME}@latest`, "inspect", result));
+  }
+  const raw = String(result.stdout || "").trim();
+  const version = raw.startsWith("\"") ? JSON.parse(raw) : raw;
+  if (!isPackageVersion(version)) {
+    throw new Error(`npm returned invalid latest version '${version || "(empty)"}' for ${CLI_PACKAGE_NAME}.`);
+  }
+  return version;
+}
+
+/**
+ * @param {any} result
+ * @returns {boolean}
+ */
+function isPackageUpdateNpmAuthFailure(result) {
+  const output = [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n").trim();
+  const normalized = output.toLowerCase();
+  return /\b(e401|eneedauth)\b/.test(normalized) ||
+    normalized.includes("unauthenticated") ||
+    normalized.includes("authentication required");
+}
+
+/**
+ * @param {string} spec
+ * @param {"inspect"|"install"|"check"} step
+ * @param {any} result
+ * @returns {string}
+ */
+export function formatPackageUpdateNpmError(spec, step, result) {
+  const output = [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n").trim();
+  const normalized = output.toLowerCase();
+  if (result.error?.code === "ENOENT") {
+    return "npm was not found. Install Node.js/npm and retry.";
+  }
+  if (isPackageUpdateNpmAuthFailure(result)) {
+    return [
+      `Authentication is required to ${step} ${spec}.`,
+      "Configure registry-specific npm auth when using private packages.",
+      output
+    ].filter(Boolean).join("\n");
+  }
+  if (/\be403\b/.test(normalized) || normalized.includes("forbidden") || normalized.includes("permission")) {
+    return [
+      `Package access was denied while trying to ${step} ${spec}.`,
+      "Check npm package registry read access for the consumer environment.",
+      output
+    ].filter(Boolean).join("\n");
+  }
+  if (/\b(e404|404)\b/.test(normalized) || normalized.includes("not found")) {
+    return [
+      `${spec} was not found, or the current token does not have access to it.`,
+      "Check the package version and npm package registry access.",
+      output
+    ].filter(Boolean).join("\n");
+  }
+  if (/\beintegrity\b/.test(normalized) || normalized.includes("integrity checksum failed")) {
+    return [
+      `Package integrity failed while trying to ${step} ${spec}.`,
+      "Regenerate package-lock.json from the published npm package registry tarball.",
+      output
+    ].filter(Boolean).join("\n");
+  }
+  return `Failed to ${step} ${spec}.\n${output || "unknown error"}`.trim();
+}