fix(test-suite): fail fast on missing gh package scope (#2270)

Author: Eikix

test-suite/fhevm/README.md

@@ -62,6 +62,8 @@ Most users should start with `latest-main`.
 
 Use `latest-supported`, network targets, or `sha` when you are reproducing a known supported or deployed bundle rather than validating current mainline behavior.
 
+Live target resolution uses GitHub metadata. For `latest-main`, `sha`, and network targets, install `gh` and authenticate it with package-read access, for example `gh auth refresh -s read:packages`, or provide a `GH_TOKEN` with that scope.
+
 Compat is mainly there to protect those reproduction and cross-era paths. For the common `latest-main` path, the mental model should stay simple: mainline baseline, optional surgical local or CI repo-owned overrides, explicit topology when needed. For the shim/incompatibility decision tree, see `COMPAT.md`.
 
 ## Quick Start

test-suite/fhevm/src/resolve.test.ts

@@ -3,7 +3,7 @@ import { writeFile } from "node:fs/promises";
 import { describe, expect, test } from "bun:test";
 
 import { validateBundleCompatibility } from "./compat/compat";
-import { shouldRetryGitHubCliError, shouldStopPackageTagScan } from "./resolve/github";
+import { explainGitHubCliError, shouldRetryGitHubCliError, shouldStopPackageTagScan } from "./resolve/github";
 import {
   SIMPLE_ACL_MIN_SHA,
   SHA_RUNTIME_COMPAT_MIN_SHA,
@@ -154,6 +154,14 @@ describe("resolve", () => {
     expect(shouldRetryGitHubCliError("gh: HTTP 404")).toBe(false);
   });
 
+  test("rewrites missing package scope errors into actionable guidance", () => {
+    expect(
+      explainGitHubCliError(
+        "gh: You need at least read:packages scope to get a package's versions. (HTTP 403)",
+      ),
+    ).toContain("gh auth refresh -s read:packages");
+  });
+
   test("stops package tag scans when the requested tag is found", () => {
     expect(
       shouldStopPackageTagScan(

test-suite/fhevm/src/resolve/github.ts

@@ -13,11 +13,14 @@ const GH_API_RETRY_DELAY_MS = 1_000;
 const GH_PACKAGE_VERSION_LIMIT = 5_000;
 
 /** Rewrites raw `gh` failures into actionable user-facing guidance. */
-const explainGitHubCliError = (message: string): string => {
+export const explainGitHubCliError = (message: string): string => {
   const lower = message.toLowerCase();
   if (lower.includes("enoent") || lower.includes("not found")) {
     return "GitHub CLI `gh` is required. Install `gh`, authenticate with `gh auth login` or GH_TOKEN, or use `--lock-file` / `--target latest-supported` to avoid GitHub resolution.";
   }
+  if (lower.includes("read:packages") || lower.includes("scope to get a package") || (lower.includes("http 403") && lower.includes("package"))) {
+    return "GitHub API is missing package-read scope. Run `gh auth refresh -s read:packages`, export GH_TOKEN with `read:packages`, or use `--lock-file` / `--target latest-supported` to avoid GitHub resolution.";
+  }
   if (lower.includes("401") || lower.includes("authentication")) {
     return "GitHub API not authenticated. Run `gh auth login`, export GH_TOKEN, or use `--lock-file` / `--target latest-supported` to avoid GitHub resolution.";
   }