@oss-scout/core 0.7.1 → 0.8.0

package/dist/core/bootstrap.js

@@ -51,6 +51,8 @@ export async function bootstrapScout(scout, token) {
         scout.setStarredRepos(starredRepos);
     }
     catch (err) {
+        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+            throw err;
         warn(MODULE, `Failed to fetch starred repos: ${errorMessage(err)}`);
         errors.push("starred repos fetch failed");
     }

package/dist/core/gist-state-store.d.ts

@@ -50,11 +50,14 @@ export interface GistOctokitLike {
         }>;
     };
 }
+/** Why bootstrap fell back to local-cache mode, when known. */
+export type DegradedReason = "rate_limit" | "network" | "server" | "unknown";
 export interface BootstrapResult {
     gistId: string;
     state: ScoutState;
     created: boolean;
     degraded?: boolean;
+    degradedReason?: DegradedReason;
 }
 export declare class GistStateStore {
     private octokit;

package/dist/core/gist-state-store.js

@@ -9,13 +9,44 @@ import * as path from "path";
 import { ScoutStateSchema } from "./schemas.js";
 import { getDataDir } from "./utils.js";
 import { debug, warn } from "./logger.js";
-import { errorMessage } from "./errors.js";
+import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
 const MODULE = "gist-state";
 const GIST_DESCRIPTION = "oss-scout-state";
 const GIST_FILENAME = "state.json";
 const GIST_ID_FILE = "gist-id";
 const CACHE_FILE = "state-cache.json";
 const SEARCH_MAX_PAGES = 5;
+/** Classify an unknown error into a DegradedReason for user-facing messaging. */
+function classifyDegradedReason(err) {
+    if (isRateLimitError(err))
+        return "rate_limit";
+    const status = getHttpStatusCode(err);
+    // GitHub's abuse-detection responses arrive as 403 with "abuse detection"
+    // in the message but no "rate limit" substring — match resolveErrorCode's
+    // logic in errors.ts so we don't misclassify as 'unknown'.
+    if (status === 403 &&
+        errorMessage(err).toLowerCase().includes("abuse detection")) {
+        return "rate_limit";
+    }
+    if (status !== undefined && status >= 500 && status < 600)
+        return "server";
+    if (err && typeof err === "object" && "code" in err) {
+        const code = err.code;
+        if (code === "ECONNREFUSED" ||
+            code === "ENOTFOUND" ||
+            code === "ETIMEDOUT" ||
+            code === "ECONNRESET" ||
+            code === "EAI_AGAIN") {
+            return "network";
+        }
+    }
+    // Node 18+ fetch errors arrive as `Error: fetch failed` with the cause set.
+    if (err instanceof Error &&
+        err.message.toLowerCase().includes("fetch failed")) {
+        return "network";
+    }
+    return "unknown";
+}
 function getGistIdPath() {
     return path.join(getDataDir(), GIST_ID_FILE);
 }
@@ -37,8 +68,13 @@ export class GistStateStore {
             return await this.bootstrapFromApi();
         }
         catch (err) {
+            // 401 means the token is invalid — fail loudly so the user re-auths.
+            // Rate-limit / network / 5xx fall back to local cache so the user can
+            // keep working offline until the issue resolves.
+            if (getHttpStatusCode(err) === 401)
+                throw err;
             warn(MODULE, `API bootstrap failed: ${errorMessage(err)}`);
-            return this.bootstrapFromCache();
+            return this.bootstrapFromCache(classifyDegradedReason(err));
         }
     }
     /**
@@ -66,6 +102,11 @@ export class GistStateStore {
             return true;
         }
         catch (err) {
+            // Both auth and rate-limit propagate per documented strategy.
+            // Local cache write already happened above, so the user's work isn't
+            // lost — but they need clear feedback that the sync failed.
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
             warn(MODULE, `Failed to push: ${errorMessage(err)}`);
             return false;
         }
@@ -84,6 +125,8 @@ export class GistStateStore {
             return state;
         }
         catch (err) {
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
             warn(MODULE, `Failed to pull: ${errorMessage(err)}`);
             return null;
         }
@@ -107,7 +150,14 @@ export class GistStateStore {
                 }
             }
             catch (err) {
-                debug(MODULE, `Cached gist ID invalid: ${errorMessage(err)}`);
+                // Only "the cached gist was deleted server-side" (404) justifies
+                // falling through to search. Auth/rate-limit/network must propagate
+                // so the outer bootstrap() catch can apply the documented strategy
+                // — otherwise a 401 here silently creates a brand-new empty gist
+                // for users with stale cached IDs.
+                if (getHttpStatusCode(err) !== 404)
+                    throw err;
+                debug(MODULE, `Cached gist gone (404): ${errorMessage(err)}`);
             }
             debug(MODULE, "Cached gist ID invalid, searching...");
         }
@@ -125,7 +175,7 @@ export class GistStateStore {
             // Gist exists but content failed validation — fall back to cache
             // to avoid overwriting the user's data by creating a new gist.
             warn(MODULE, `Found existing gist ${foundId} but content failed validation. Using local cache to avoid data loss.`);
-            return this.bootstrapFromCache();
+            return this.bootstrapFromCache("unknown");
         }
         // 3. Create new gist
         debug(MODULE, "No existing gist found, creating new one");
@@ -136,7 +186,7 @@ export class GistStateStore {
         this.writeCache(freshState);
         return { gistId: newId, state: freshState, created: true };
     }
-    bootstrapFromCache() {
+    bootstrapFromCache(reason) {
         const cached = this.readCache();
         if (cached) {
             debug(MODULE, "Bootstrapped from local cache (degraded mode)");
@@ -148,11 +198,18 @@ export class GistStateStore {
                 state: cached,
                 created: false,
                 degraded: true,
+                degradedReason: reason,
             };
         }
         debug(MODULE, "No cache available, using fresh state (degraded mode)");
         const fresh = ScoutStateSchema.parse({ version: 1 });
-        return { gistId: "", state: fresh, created: false, degraded: true };
+        return {
+            gistId: "",
+            state: fresh,
+            created: false,
+            degraded: true,
+            degradedReason: reason,
+        };
     }
     // ── Gist API operations ──────────────────────────────────────────────
     async fetchGistState(gistId) {

package/dist/core/issue-discovery.js

@@ -203,6 +203,8 @@ async function runPhase3(octokit, vetter, langQuery, minStars, projectCategories
         };
     }
     catch (error) {
+        if (getHttpStatusCode(error) === 401)
+            throw error;
         const errMsg = errorMessage(error);
         warn(MODULE, `Error in maintained-repo search: ${errMsg}`);
         return {

package/dist/core/issue-vetting.js

@@ -7,7 +7,7 @@
  * - repo-health.ts       — project health, contribution guidelines
  */
 import { parseGitHubUrl } from "./utils.js";
-import { ValidationError, errorMessage, isRateLimitError } from "./errors.js";
+import { ValidationError, errorMessage, getHttpStatusCode, isRateLimitError, } from "./errors.js";
 import { debug, warn } from "./logger.js";
 import { calculateRepoQualityBonus, calculateViabilityScore, } from "./issue-scoring.js";
 import { repoBelongsToCategory } from "./category-mapping.js";
@@ -263,9 +263,16 @@ export class IssueVetter {
         let failedVettingCount = 0;
         let rateLimitFailures = 0;
         let attemptedCount = 0;
+        // Capture the first 401 so we can re-throw after in-flight tasks settle.
+        // Per-item tolerance is right for transient failures, but a 401 means
+        // the token is invalid and no other issue will succeed either —
+        // continuing to log per-issue warnings buries the actual problem.
+        let firstAuthError = null;
         for (const url of urls) {
             if (candidates.length >= maxResults)
                 break;
+            if (firstAuthError)
+                break; // stop scheduling once auth has failed
             attemptedCount++;
             const task = this.vetIssue(url)
                 .then((candidate) => {
@@ -278,6 +285,10 @@ export class IssueVetter {
                 }
             })
                 .catch((error) => {
+                if (getHttpStatusCode(error) === 401) {
+                    firstAuthError ??= error;
+                    return;
+                }
                 failedVettingCount++;
                 if (isRateLimitError(error)) {
                     rateLimitFailures++;
@@ -293,6 +304,12 @@ export class IssueVetter {
         }
         // Wait for remaining
         await Promise.allSettled(pending.values());
+        if (firstAuthError) {
+            if (candidates.length > 0) {
+                warn(MODULE, `Auth failed mid-batch after ${candidates.length} successful vet(s) — discarding partial results`);
+            }
+            throw firstAuthError;
+        }
         const allFailed = failedVettingCount === attemptedCount && attemptedCount > 0;
         if (allFailed) {
             warn(MODULE, `All ${attemptedCount} issue(s) failed vetting. ` +

package/dist/core/repo-health.js

@@ -73,6 +73,9 @@ export async function checkProjectHealth(octokit, owner, repo) {
         });
     }
     catch (error) {
+        if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
+            throw error;
+        }
         const errMsg = errorMessage(error);
         warn(MODULE, `Error checking project health for ${owner}/${repo}: ${errMsg}`);
         return {

package/dist/core/search-phases.js

@@ -370,6 +370,8 @@ export async function searchInRepos(octokit, vetter, repos, baseQualifiers, labe
             }
         }
         catch (error) {
+            if (getHttpStatusCode(error) === 401)
+                throw error;
             failedBatches++;
             if (isRateLimitError(error)) {
                 rateLimitFailures++;

package/dist/scout.js

@@ -11,6 +11,22 @@ import { getOctokit } from "./core/github.js";
 import { loadLocalState } from "./core/local-state.js";
 import { warn } from "./core/logger.js";
 import { extractRepoFromUrl } from "./core/utils.js";
+import { errorMessage, getHttpStatusCode, isRateLimitError, } from "./core/errors.js";
+/** Cause-specific user-facing message for degraded (offline) mode. */
+function offlineModeMessage(reason) {
+    const tail = "Changes will only be saved locally.";
+    switch (reason) {
+        case "rate_limit":
+            return `Gist sync unavailable — GitHub API rate limit exceeded. ${tail} Try again after the rate limit resets.`;
+        case "network":
+            return `Gist sync unavailable — could not reach GitHub. ${tail} Check your network connection.`;
+        case "server":
+            return `Gist sync unavailable — GitHub returned a server error. ${tail} Try again later.`;
+        case "unknown":
+        case undefined:
+            return `Gist sync unavailable — running in offline mode. ${tail}`;
+    }
+}
 /** Wrap a real Octokit instance as GistOctokitLike without unsafe double casts. */
 function toGistOctokit(octokit) {
     return {
@@ -84,7 +100,7 @@ export async function createScout(config) {
         gistStore = new GistStateStore(toGistOctokit(getOctokit(config.githubToken)));
         const result = await gistStore.bootstrap();
         if (result.degraded) {
-            warn("scout", "Gist sync unavailable — running in offline mode. Changes will only be saved locally.");
+            warn("scout", offlineModeMessage(result.degradedReason));
         }
         const localState = loadLocalState();
         state = mergeStates(localState, result.state);
@@ -159,7 +175,15 @@ export class OssScout {
         const concurrency = options?.concurrency ?? 5;
         const results = [];
         const pending = new Map();
+        // First 401 OR rate-limit short-circuits the whole batch. Unlike
+        // vetIssuesParallel (which has a batch-level rateLimitHit flag the
+        // search orchestrator surfaces via rateLimitWarning), vetList is the
+        // user-facing CLI entry point — N rows of "rate limit exceeded" is the
+        // exact silent-failure mode the documented strategy aims to prevent.
+        let firstHardError = null;
         for (const item of saved) {
+            if (firstHardError)
+                break;
             const task = this.vetIssue(item.issueUrl)
                 .then((candidate) => {
                 results.push({
@@ -173,15 +197,19 @@ export class OssScout {
                 });
             })
                 .catch((error) => {
-                const msg = error instanceof Error ? error.message : String(error);
-                const isGone = msg.includes("Not Found") || msg.includes("410");
+                if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
+                    firstHardError ??= error;
+                    return;
+                }
+                const status = getHttpStatusCode(error);
+                const isGone = status === 404 || status === 410;
                 results.push({
                     issueUrl: item.issueUrl,
                     repo: item.repo,
                     number: item.number,
                     title: item.title,
                     status: isGone ? "closed" : "error",
-                    errorMessage: msg,
+                    errorMessage: errorMessage(error),
                 });
             })
                 .finally(() => {
@@ -193,6 +221,12 @@ export class OssScout {
             }
         }
         await Promise.allSettled(pending.values());
+        if (firstHardError) {
+            if (results.length > 0) {
+                warn("scout", `vetList aborted mid-batch after ${results.length} result(s) — discarding partial results due to auth/rate-limit failure`);
+            }
+            throw firstHardError;
+        }
         const summary = {
             total: results.length,
             stillAvailable: results.filter((r) => r.status === "still_available")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Personalized GitHub issue finder with multi-strategy search, deep vetting, and viability scoring — CLI, library, MCP server, and Claude Code plugin",
   "type": "module",
   "bin": {