@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/create-version/process.js

@@ -0,0 +1,334 @@
+/**
+ * Process and Git helpers of `astra-rp create-version`: captured and inherited
+ * commands that never reject, a Git reader bound to a repository, commit
+ * listing and manifest reads at any revision.
+ *
+ * @module create-version/process
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+
+import { isRecord } from "./json.js";
+import { FIELD_SEPARATOR, PACKAGE_MANIFEST_FILE, RECORD_SEPARATOR, VERSION_FIELD_CHANGE_PATTERN } from "../constants/create-version.js";
+
+/**
+ * @typedef {{ status: number, stdout: string, stderr: string }} CapturedResult
+ * @typedef {{ cwd?: string, shell?: boolean, env?: NodeJS.ProcessEnv }} CommandOptions
+ * @typedef {{ git: (gitArguments: string[]) => Promise<string>, tryGit: (gitArguments: string[]) => Promise<string | null> }} GitReader
+ * @typedef {{ sha: string, subject: string, body: string }} CommitRecord
+ */
+
+/** Windows resolves `pnpm.cmd` and `npm.cmd` only through a shell. */
+export const USES_SHELL_FOR_PACKAGE_MANAGERS = process.platform === "win32";
+
+/**
+ * Double-quotes every argument for a Windows shell command line; callers validate them first against
+ * characters that could break out of the quotes.
+ *
+ * @param {readonly string[]} commandArguments - Validated arguments.
+ * @returns {string} Arguments quoted and joined with spaces.
+ */
+export function quoteShellArguments(commandArguments) {
+  return commandArguments.map((commandArgument) => `"${commandArgument}"`).join(" ");
+}
+
+/**
+ * Runs a command and captures its output. Leading whitespace is kept because
+ * `git status --porcelain` encodes the file state in the first columns.
+ *
+ * @param {string} command - Executable name, or a full command line when `shell` is set.
+ * @param {string[]} commandArguments - Arguments.
+ * @param {CommandOptions} [options] - Spawn options.
+ * @returns {Promise<CapturedResult>} Result; never rejects.
+ */
+export function runCaptured(command, commandArguments, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, commandArguments, {
+      cwd: options.cwd,
+      env: options.env,
+      shell: options.shell ?? false,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.setEncoding("utf8").on("data", (chunk) => (stdout += chunk));
+    child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+    child.on("error", (error) => resolve({ status: 1, stdout, stderr: error.message }));
+    child.on("close", (status) => resolve({ status: status ?? 1, stdout: stdout.trimEnd(), stderr: stderr.trim() }));
+  });
+}
+
+/**
+ * @typedef {CommandOptions & { input: string, timeoutMs: number }} InputCommandOptions
+ * @typedef {CapturedResult & { timedOut: boolean, spawnErrorCode: string | null }} InputCommandResult
+ */
+
+/**
+ * Whether stoppable commands run as the leader of their own process group: true outside Windows,
+ * where signaling the negative pid reaches every process the command started.
+ */
+const RUNS_COMMANDS_IN_OWN_PROCESS_GROUP = process.platform !== "win32";
+
+/**
+ * Stops a command together with every process it started, such as the shell or Git commands an
+ * agent CLI is running: on Windows `taskkill /t` ends the whole tree (a shell-launched `.cmd` shim
+ * runs the real program as a grandchild); elsewhere the command leads its own process group, which
+ * is killed as a whole. A group that already ended leaves nothing to stop; any other failure is
+ * logged so a process left running is not silent.
+ *
+ * @param {import("node:child_process").ChildProcess} child - Command to stop, spawned with `detached`
+ *   outside Windows.
+ * @param {string} command - Executable name or command line, only used to describe a failure.
+ * @returns {void}
+ */
+function stopProcessTree(child, command) {
+  if (child.pid === undefined) return;
+  if (!RUNS_COMMANDS_IN_OWN_PROCESS_GROUP) {
+    // A tree that already ended makes taskkill fail, which leaves nothing to stop.
+    spawnSync("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore", windowsHide: true });
+    return;
+  }
+  try {
+    process.kill(-child.pid, "SIGKILL");
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ESRCH") return;
+    console.error(`astra-rp create-version: stopProcessTree failed to kill the process group of "${command}" (pid ${child.pid}) after its timeout`, error);
+  }
+}
+
+/**
+ * Runs a command that reads `input` from stdin and captures its output, stopping it after
+ * `timeoutMs`. Used for agent CLIs that receive their prompt through stdin. Outside Windows the
+ * command runs in its own process group so a timeout also stops the processes it started; the
+ * promise still waits for its pipes to close when it ends normally, so no `unref` is needed.
+ *
+ * @param {string} command - Executable name, or a full command line when `shell` is set.
+ * @param {string[]} commandArguments - Arguments.
+ * @param {InputCommandOptions} options - Spawn options, stdin contents and time limit.
+ * @returns {Promise<InputCommandResult>} Result, whether it was stopped for taking too long and the
+ *   spawn error code (such as `ENOENT`); never rejects.
+ */
+export function runCapturedWithInput(command, commandArguments, options) {
+  return new Promise((resolve) => {
+    const child = spawn(command, commandArguments, {
+      cwd: options.cwd,
+      env: options.env,
+      shell: options.shell ?? false,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+      detached: RUNS_COMMANDS_IN_OWN_PROCESS_GROUP,
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    /** @type {string | null} */
+    let spawnErrorCode = null;
+
+    child.stdout.setEncoding("utf8").on("data", (chunk) => (stdout += chunk));
+    child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+    // A command that exits without reading stdin closes the pipe: its exit code tells what happened.
+    child.stdin.on("error", () => {});
+    child.stdin.end(options.input);
+    let settled = false;
+    /** @param {number} status - Exit code to report. */
+    const finish = (status) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ status, stdout: stdout.trim(), stderr: stderr.trim(), timedOut, spawnErrorCode });
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stopProcessTree(child, command);
+      // Grandchildren that ignore the signal keep the pipes open and would delay `close` forever.
+      finish(1);
+    }, options.timeoutMs);
+    // A command that could not start may never emit `close`.
+    child.on("error", (error) => {
+      spawnErrorCode = /** @type {NodeJS.ErrnoException} */ (error).code ?? null;
+      stderr = error.message;
+      finish(1);
+    });
+    child.on("close", (status) => finish(status ?? 1));
+  });
+}
+
+/**
+ * Runs a command with inherited stdio so its progress stays visible.
+ *
+ * @param {string} command - Executable name, or a full command line when `shell` is set.
+ * @param {string[]} commandArguments - Arguments.
+ * @param {CommandOptions} [options] - Spawn options.
+ * @returns {Promise<number>} Exit code; never rejects.
+ */
+export function runInherited(command, commandArguments, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, commandArguments, { cwd: options.cwd, env: options.env, shell: options.shell ?? false, stdio: "inherit" });
+    child.on("error", () => resolve(1));
+    child.on("close", (status) => resolve(status ?? 1));
+  });
+}
+
+/**
+ * Forwards complete output lines, retaining incomplete chunks so a split credential is redacted.
+ *
+ * @param {import("node:stream").Readable} source - Child stream.
+ * @param {NodeJS.WriteStream} destination - Parent stream.
+ * @param {string[]} secrets - Values that must not be logged.
+ * @returns {void}
+ */
+function streamRedactedOutput(source, destination, secrets) {
+  let pending = "";
+  /** @param {string} value - Complete output line or final tail. */
+  const write = (value) => destination.write(secrets.filter(Boolean).reduce((output, secret) => output.replaceAll(secret, "[redactado]"), value));
+  source.setEncoding("utf8");
+  source.on("data", (chunk) => {
+    pending += chunk;
+    let newline;
+    while ((newline = pending.indexOf("\n")) !== -1) {
+      write(pending.slice(0, newline + 1));
+      pending = pending.slice(newline + 1);
+    }
+  });
+  source.on("end", () => { if (pending) write(pending); });
+}
+
+/**
+ * Streams a client that may print its own command on failure, redacting credentials across chunks.
+ *
+ * @param {string} command - Executable or trusted shell command.
+ * @param {string[]} commandArguments - Client arguments.
+ * @param {CommandOptions} options - Child environment and checkout.
+ * @param {string[]} secrets - Values to redact; never included in diagnostics.
+ * @returns {Promise<number>} Exit code with interactive stdin and safe terminal output.
+ */
+export function runRedactedInherited(command, commandArguments, options, secrets) {
+  return new Promise((resolve) => {
+    const child = spawn(command, commandArguments, { cwd: options.cwd, env: options.env, shell: options.shell ?? false, stdio: ["inherit", "pipe", "pipe"], windowsHide: true });
+    streamRedactedOutput(child.stdout, process.stdout, secrets);
+    streamRedactedOutput(child.stderr, process.stderr, secrets);
+    child.on("error", () => resolve(1));
+    child.on("close", (status) => resolve(status ?? 1));
+  });
+}
+
+/**
+ * Runs a trusted, configured command line (for example `pnpm check`) through the shell.
+ *
+ * @param {string} commandLine - Command line written in the project configuration, never user input.
+ * @param {string} cwd - Working directory.
+ * @returns {Promise<number>} Exit code; never rejects.
+ */
+export function runCommandLine(commandLine, cwd) {
+  return runInherited(commandLine, [], { cwd, shell: true });
+}
+
+/**
+ * Creates a Git reader bound to a repository.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {GitReader} Readers.
+ */
+export function createGitReader(repositoryRoot) {
+  /** @param {string[]} gitArguments */
+  const tryGit = async (gitArguments) => {
+    const result = await runCaptured("git", gitArguments, { cwd: repositoryRoot });
+    return result.status === 0 ? result.stdout : null;
+  };
+
+  /** @param {string[]} gitArguments */
+  const git = async (gitArguments) => {
+    const result = await runCaptured("git", gitArguments, { cwd: repositoryRoot });
+
+    if (result.status !== 0) {
+      throw new Error(`astra-rp create-version: git ${gitArguments.join(" ")} failed in ${repositoryRoot}: ${result.stderr}`);
+    }
+
+    return result.stdout;
+  };
+
+  return { git, tryGit };
+}
+
+/**
+ * Parses `git log` records produced with {@link FIELD_SEPARATOR} and {@link RECORD_SEPARATOR}.
+ *
+ * @param {string} output - Raw `git log` output.
+ * @returns {CommitRecord[]} Commits, newest first.
+ */
+export function parseCommitLog(output) {
+  return output
+    .split(RECORD_SEPARATOR)
+    .map((record) => record.trim())
+    .filter(Boolean)
+    .map((record) => {
+      const [sha = "", subject = "", body = ""] = record.split(FIELD_SEPARATOR);
+      return { sha, subject, body: body.trim() };
+    });
+}
+
+/**
+ * Lists the commits of a revision range, optionally only those touching some paths.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} range - Revision range such as `abc..origin/main`.
+ * @param {readonly string[]} [paths] - Paths relative to the root; every commit when empty.
+ * @returns {Promise<CommitRecord[]>} Commits, newest first.
+ */
+export async function listCommits(reader, range, paths = []) {
+  const pathArguments = paths.length > 0 ? ["--", ...paths] : [];
+  const output = await reader.tryGit(["log", `--format=%H${FIELD_SEPARATOR}%s${FIELD_SEPARATOR}%b${RECORD_SEPARATOR}`, range, ...pathArguments]);
+  return output ? parseCommitLog(output) : [];
+}
+
+/**
+ * Reads a `package.json` at a revision.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} revision - Revision such as `HEAD`, `v1.2.0` or `origin/main`.
+ * @param {string} [manifestPath] - Manifest path relative to the root, with `/` separators (a
+ *   workspace package's `packages/x/package.json`); the root `package.json` by default.
+ * @returns {Promise<Record<string, unknown> | null>} Parsed manifest, or `null` when missing, unreadable or not a JSON object.
+ */
+export async function readPackageManifestAt(reader, revision, manifestPath = PACKAGE_MANIFEST_FILE) {
+  const manifest = await reader.tryGit(["show", `${revision}:${manifestPath}`]);
+
+  try {
+    const parsed = manifest ? JSON.parse(manifest) : null;
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads the `version` field of a `package.json` at a revision.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} revision - Revision such as `HEAD` or `origin/main`.
+ * @param {string} [manifestPath] - Manifest path relative to the root; the root `package.json` by default.
+ * @returns {Promise<string | null>} Version, or `null` when unreadable.
+ */
+export async function readPackageVersionAt(reader, revision, manifestPath = PACKAGE_MANIFEST_FILE) {
+  const manifest = await readPackageManifestAt(reader, revision, manifestPath);
+  return typeof manifest?.version === "string" ? manifest.version : null;
+}
+
+/**
+ * Finds the newest top-level version change, including compact JSON and excluding edits to nested versions.
+ *
+ * @param {GitReader} reader - Read-only Git boundary.
+ * @param {string} revision - History to inspect.
+ * @param {string} [manifestPath] - Package manifest path.
+ * @returns {Promise<string | null>} Commit that actually changed the top-level version.
+ */
+export async function findVersionChangeCommit(reader, revision, manifestPath = PACKAGE_MANIFEST_FILE) {
+  const history = await reader.tryGit(["log", "--format=%H", `-G${VERSION_FIELD_CHANGE_PATTERN}`, revision, "--", manifestPath]);
+  for (const sha of (history ?? "").split("\n").filter(Boolean)) {
+    const [version, previous] = await Promise.all([readPackageVersionAt(reader, sha, manifestPath), readPackageVersionAt(reader, `${sha}^`, manifestPath)]);
+    if (version !== null && version !== previous) return sha;
+  }
+  return null;
+}

package/src/create-version/registry-config.js

@@ -0,0 +1,121 @@
+/**
+ * Validates provider-specific publication options while keeping legacy npm configuration intact.
+ *
+ * @module create-version/registry-config
+ */
+
+import path from "node:path";
+import { CHANGELOG_FILE } from "../constants/changelog.js";
+
+import {
+  BROWSER_AUTHENTICATION,
+  JSR_CLIENTS,
+  JSR_REGISTRY_PROVIDER,
+  NPM_REGISTRY_PROVIDER,
+  REGISTRY_ACCESS_MODES,
+  REGISTRY_AUTHENTICATION_MODES,
+  REGISTRY_DIST_TAG_PATTERN,
+  REGISTRY_PROVIDERS,
+  REGISTRY_TOKEN_VARIABLE_PATTERN,
+  REGISTRY_TOKEN_VARIABLES,
+  TOKEN_AUTHENTICATION,
+} from "../constants/registry.js";
+import { NPM_DIST_TAG, NPM_REGISTRY_PROTOCOLS } from "../constants/create-version.js";
+import { isRecord } from "./json.js";
+
+/**
+ * @typedef {"npm" | "github" | "gitlab" | "jsr"} RegistryProvider
+ * @typedef {"token" | "oidc" | "browser"} RegistryAuthentication
+ * @typedef {{ registryUrl?: string, packageName?: string, authentication?: RegistryAuthentication, tokenEnv?: string, access?: "public" | "restricted", tag?: string, configFile?: string, jsrClient?: "npx" | "deno" }} PublicationOptions
+ * @typedef {{ registryUrl: string | null, packageName: string | null, authentication: RegistryAuthentication, tokenEnv: string, access: "public" | "restricted" | null, tag: string | null, configFile: string | null, jsrClient: "npx" | "deno" }} ResolvedPublicationOptions
+ */
+
+/**
+ * Identifies one of the four built-in publishers.
+ *
+ * @param {unknown} value - Configured publisher or registry.
+ * @returns {value is RegistryProvider} Whether it is a provider name.
+ */
+export function isRegistryProvider(value) {
+  return typeof value === "string" && /** @type {readonly string[]} */ (REGISTRY_PROVIDERS).includes(value);
+}
+
+/**
+ * Tells whether a URL is a plain http(s) URL: without credentials, query nor fragment.
+ *
+ * @param {URL} url - Parsed URL.
+ * @returns {boolean} Whether a registry can be addressed by it.
+ */
+export function isPlainHttpUrl(url) {
+  return NPM_REGISTRY_PROTOCOLS.includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash;
+}
+
+/**
+ * Resolves publication options for a single selected provider; arrays are deliberately unsupported.
+ *
+ * @param {unknown} value - Raw `publication` configuration.
+ * @param {RegistryProvider} [provider] - Selected publisher or monitored registry.
+ * @returns {ResolvedPublicationOptions} Validated options and provider defaults.
+ * @throws {Error} When a field is invalid or unsupported by the selected provider.
+ */
+export function resolvePublicationOptions(value, provider = NPM_REGISTRY_PROVIDER) {
+  if (value !== undefined && !isRecord(value)) {
+    throw new Error("astra-rp create-version: publication must be an object for a single registry");
+  }
+  const options = /** @type {PublicationOptions} */ (value ?? {});
+  const authentication = options.authentication ?? (provider === JSR_REGISTRY_PROVIDER ? BROWSER_AUTHENTICATION : TOKEN_AUTHENTICATION);
+  if (!(/** @type {readonly string[]} */ (REGISTRY_AUTHENTICATION_MODES)).includes(authentication)) {
+    throw new Error("astra-rp create-version: publication.authentication must be token, oidc or browser");
+  }
+  if (authentication !== TOKEN_AUTHENTICATION && provider !== NPM_REGISTRY_PROVIDER && provider !== JSR_REGISTRY_PROVIDER) {
+    throw new Error(`astra-rp create-version: ${provider} only supports token authentication`);
+  }
+  if (authentication === BROWSER_AUTHENTICATION && provider !== JSR_REGISTRY_PROVIDER) {
+    throw new Error("astra-rp create-version: browser authentication is supported only by JSR");
+  }
+  const tokenEnv = options.tokenEnv ?? REGISTRY_TOKEN_VARIABLES[provider];
+  if (typeof tokenEnv !== "string" || !REGISTRY_TOKEN_VARIABLE_PATTERN.test(tokenEnv)) {
+    throw new Error("astra-rp create-version: publication.tokenEnv must be an environment variable name");
+  }
+  for (const field of ["registryUrl", "packageName", "configFile"]) {
+    const candidate = options[/** @type {"registryUrl" | "packageName" | "configFile"} */ (field)];
+    if (candidate !== undefined && (typeof candidate !== "string" || candidate.trim() === "")) {
+      throw new Error(`astra-rp create-version: publication.${field} must be a non-empty string`);
+    }
+  }
+  if (options.registryUrl !== undefined) {
+    const url = new URL(options.registryUrl);
+    if (!isPlainHttpUrl(url)) {
+      throw new Error("astra-rp create-version: publication.registryUrl must be an http(s) URL without credentials, query or fragment");
+    }
+  }
+  if (options.access !== undefined && !(/** @type {readonly string[]} */ (REGISTRY_ACCESS_MODES)).includes(options.access)) {
+    throw new Error("astra-rp create-version: publication.access must be public or restricted");
+  }
+  if (options.tag !== undefined && (typeof options.tag !== "string" || !REGISTRY_DIST_TAG_PATTERN.test(options.tag))) {
+    throw new Error("astra-rp create-version: publication.tag must be a distribution tag without shell characters");
+  }
+  if (provider === JSR_REGISTRY_PROVIDER && (options.access === "restricted" || options.tag !== undefined)) {
+    throw new Error("astra-rp create-version: JSR supports public packages and does not support npm distribution tags");
+  }
+  if (provider !== JSR_REGISTRY_PROVIDER && (options.configFile !== undefined || options.jsrClient !== undefined)) {
+    throw new Error("astra-rp create-version: publication.configFile and publication.jsrClient require publish: jsr");
+  }
+  const jsrClient = options.jsrClient ?? "npx";
+  if (!(/** @type {readonly string[]} */ (JSR_CLIENTS)).includes(jsrClient)) {
+    throw new Error("astra-rp create-version: publication.jsrClient must be npx or deno");
+  }
+  if (options.configFile !== undefined && (path.win32.parse(options.configFile).root !== "" || options.configFile.split(/[\\/]/u).includes("..") || /[%!"\r\n]/u.test(options.configFile) || path.win32.basename(options.configFile).toLowerCase() === CHANGELOG_FILE.toLowerCase())) {
+    throw new Error("astra-rp create-version: publication.configFile must be a safe path inside the package root");
+  }
+  return {
+    registryUrl: options.registryUrl ?? null,
+    packageName: options.packageName ?? null,
+    authentication,
+    tokenEnv,
+    access: options.access ?? (provider === NPM_REGISTRY_PROVIDER ? "public" : null),
+    tag: provider === JSR_REGISTRY_PROVIDER ? null : options.tag ?? NPM_DIST_TAG,
+    configFile: options.configFile?.replaceAll("\\", "/") ?? null,
+    jsrClient,
+  };
+}

package/src/create-version/registry-http.js

@@ -0,0 +1,62 @@
+/**
+ * Reads provider metadata without following registry forwarding redirects or exposing upstream bodies.
+ *
+ * @module create-version/registry-http
+ */
+
+import { NPM_LOOKUP_STATUS } from "../constants/create-version.js";
+import { GITLAB_REGISTRY_PROVIDER, JSR_REGISTRY_PROVIDER, REGISTRY_LOOKUP_TIMEOUT_MS } from "../constants/registry.js";
+import { findHighestStableVersion } from "../versions.js";
+
+/**
+ * Fetches versions directly from GitLab or JSR; a forwarding redirect means absent in this registry.
+ *
+ * @param {{ provider: import("./registry-config.js").RegistryProvider, registryUrl: string, packageName: string, label: string, tag: string | null, options?: { tokenEnv: string } }} registry - Selected registry.
+ * @param {string | null} token - Read credential, never included in returned state.
+ * @returns {Promise<import("./npm.js").NpmLookup>} Shared published-version contract.
+ */
+export async function lookupHttpRegistry(registry, token) {
+  const baseUrl = registry.registryUrl.endsWith("/") ? registry.registryUrl : `${registry.registryUrl}/`;
+  const resource = registry.provider === JSR_REGISTRY_PROVIDER ? `${registry.packageName}/meta.json` : encodeURIComponent(registry.packageName);
+  const url = new URL(resource, baseUrl);
+  const empty = { status: NPM_LOOKUP_STATUS.ok, publishedVersions: [], latestVersion: null, reason: null, registryLabel: registry.label, tag: registry.tag };
+  try {
+    const response = await fetch(url, {
+      redirect: "manual",
+      headers: { Accept: "application/json", "Cache-Control": "no-cache", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      signal: AbortSignal.timeout(REGISTRY_LOOKUP_TIMEOUT_MS),
+    });
+    if (response.status === 404) {
+      await response.body?.cancel();
+      if (registry.provider === GITLAB_REGISTRY_PROVIDER && !token) {
+        return { ...empty, status: NPM_LOOKUP_STATUS.failed, reason: `GitLab: HTTP 404 sin ${registry.options?.tokenEnv ?? "credencial de lectura"}; no se puede distinguir un paquete ausente de un proyecto privado. Definí la credencial antes de diagnosticar.` };
+      }
+      return empty;
+    }
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      const redirected = location ? new URL(location, url) : null;
+      await response.body?.cancel();
+      return registry.provider !== JSR_REGISTRY_PROVIDER && redirected && ["registry.npmjs.org", "npmjs.com", "www.npmjs.com"].includes(redirected.hostname)
+        ? empty
+        : { ...empty, status: NPM_LOOKUP_STATUS.failed, reason: `${registry.label}: la consulta se redirigió fuera del endpoint de metadata; no se confirmó el paquete.` };
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      return { ...empty, status: NPM_LOOKUP_STATUS.failed, reason: `${registry.label}: GET de ${registry.packageName} respondió HTTP ${response.status}; revisá el endpoint y los permisos de lectura.` };
+    }
+    const metadata = /** @type {{ versions?: Record<string, unknown> | string[], "dist-tags"?: Record<string, string> } | null} */ (await response.json());
+    const versions = metadata?.versions;
+    if (!versions || typeof versions !== "object") {
+      return { ...empty, status: NPM_LOOKUP_STATUS.failed, reason: `${registry.label}: no se pudo leer la lista de versiones de ${registry.packageName}.` };
+    }
+    const publishedVersions = Array.isArray(versions) ? versions : Object.keys(versions);
+    const latestVersion = registry.provider === JSR_REGISTRY_PROVIDER
+      ? findHighestStableVersion(publishedVersions)
+      : metadata?.["dist-tags"]?.[registry.tag ?? "latest"] ?? null;
+    return { ...empty, publishedVersions, latestVersion: typeof latestVersion === "string" ? latestVersion : null };
+  } catch (error) {
+    const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+    return { ...empty, status: NPM_LOOKUP_STATUS.failed, reason: `${registry.label}: ${timedOut ? "se agotó el tiempo" : "falló la conexión o la lectura de metadata"} al consultar ${registry.packageName}.` };
+  }
+}