@oss-scout/core 0.2.0 → 0.3.0

package/dist/core/bootstrap.js

@@ -2,22 +2,23 @@
  * First-run bootstrap — fetches starred repos and PR history from GitHub
  * to seed the scout's state with the user's contribution context.
  */
-import { getOctokit, checkRateLimit } from './github.js';
-import { debug, warn } from './logger.js';
-import { errorMessage } from './errors.js';
-const MODULE = 'bootstrap';
+import { getOctokit, checkRateLimit } from "./github.js";
+import { debug, warn } from "./logger.js";
+import { ConfigurationError, errorMessage } from "./errors.js";
+import { extractRepoFromUrl } from "./utils.js";
+const MODULE = "bootstrap";
 const STARRED_MAX_PAGES = 5;
 const SEARCH_MAX_PAGES = 3;
 const PER_PAGE = 100;
 export async function bootstrapScout(scout, token) {
     const username = scout.getPreferences().githubUsername;
     if (!username) {
-        throw new Error('GitHub username not configured. Run `oss-scout setup` first.');
+        throw new ConfigurationError("GitHub username not configured. Run `oss-scout setup` first.");
     }
     const rateLimit = await checkRateLimit(token);
     debug(MODULE, `Rate limit: ${rateLimit.remaining}/${rateLimit.limit}, resets at ${rateLimit.resetAt}`);
     if (rateLimit.remaining < 15) {
-        debug(MODULE, 'Insufficient rate limit, skipping bootstrap');
+        debug(MODULE, "Insufficient rate limit, skipping bootstrap");
         return {
             starredRepoCount: 0,
             mergedPRCount: 0,
@@ -33,7 +34,10 @@ export async function bootstrapScout(scout, token) {
     const starredRepos = [];
     try {
         let starredPage = 0;
-        for await (const response of octokit.paginate.iterator(octokit.activity.listReposStarredByAuthenticatedUser, { per_page: PER_PAGE, headers: { accept: 'application/vnd.github.v3+json' } })) {
+        for await (const response of octokit.paginate.iterator(octokit.activity.listReposStarredByAuthenticatedUser, {
+            per_page: PER_PAGE,
+            headers: { accept: "application/vnd.github.v3+json" },
+        })) {
             for (const repo of response.data) {
                 const r = repo;
                 starredRepos.push(r.full_name);
@@ -47,7 +51,7 @@ export async function bootstrapScout(scout, token) {
     }
     catch (err) {
         warn(MODULE, `Failed to fetch starred repos: ${errorMessage(err)}`);
-        errors.push('starred repos fetch failed');
+        errors.push("starred repos fetch failed");
     }
     // 2. Fetch merged PRs via Search API
     let mergedPRCount = 0;
@@ -59,14 +63,14 @@ export async function bootstrapScout(scout, token) {
                 page,
             });
             for (const item of data.items) {
-                const repoMatch = item.html_url.match(/github\.com\/([^/]+\/[^/]+)\//);
-                if (!repoMatch)
+                const repo = extractRepoFromUrl(item.html_url);
+                if (!repo)
                     continue;
                 scout.recordMergedPR({
                     url: item.html_url,
                     title: item.title,
                     mergedAt: item.closed_at ?? new Date().toISOString(),
-                    repo: repoMatch[1],
+                    repo,
                 });
                 mergedPRCount++;
             }
@@ -77,7 +81,7 @@ export async function bootstrapScout(scout, token) {
     }
     catch (err) {
         warn(MODULE, `Failed to fetch merged PRs: ${errorMessage(err)}`);
-        errors.push('merged PR fetch failed');
+        errors.push("merged PR fetch failed");
     }
     // 3. Fetch closed-without-merge PRs via Search API
     let closedPRCount = 0;
@@ -89,14 +93,14 @@ export async function bootstrapScout(scout, token) {
                 page,
             });
             for (const item of data.items) {
-                const repoMatch = item.html_url.match(/github\.com\/([^/]+\/[^/]+)\//);
-                if (!repoMatch)
+                const repo = extractRepoFromUrl(item.html_url);
+                if (!repo)
                     continue;
                 scout.recordClosedPR({
                     url: item.html_url,
                     title: item.title,
                     closedAt: item.closed_at ?? new Date().toISOString(),
-                    repo: repoMatch[1],
+                    repo,
                 });
                 closedPRCount++;
             }
@@ -107,7 +111,7 @@ export async function bootstrapScout(scout, token) {
     }
     catch (err) {
         warn(MODULE, `Failed to fetch closed PRs: ${errorMessage(err)}`);
-        errors.push('closed PR fetch failed');
+        errors.push("closed PR fetch failed");
     }
     const state = scout.getState();
     const reposScoredCount = Object.keys(state.repoScores).length;

package/dist/core/category-mapping.d.ts

@@ -3,7 +3,7 @@
  *
  * Used by issue discovery to prioritize repos matching user's category preferences.
  */
-import type { ProjectCategory } from './types.js';
+import type { ProjectCategory } from "./types.js";
 /** GitHub topics associated with each project category, used for `topic:` search queries. */
 export declare const CATEGORY_TOPICS: Record<ProjectCategory, string[]>;
 /** Well-known GitHub organizations associated with each project category. */

package/dist/core/category-mapping.js

@@ -5,21 +5,112 @@
  */
 /** GitHub topics associated with each project category, used for `topic:` search queries. */
 export const CATEGORY_TOPICS = {
-    nonprofit: ['nonprofit', 'social-good', 'humanitarian', 'charity', 'social-impact', 'civic-tech'],
-    devtools: ['developer-tools', 'devtools', 'cli', 'sdk', 'linter', 'formatter', 'build-tool'],
-    infrastructure: ['infrastructure', 'cloud', 'kubernetes', 'docker', 'devops', 'monitoring', 'observability'],
-    'web-frameworks': ['web-framework', 'frontend', 'backend', 'fullstack', 'nextjs', 'react', 'vue'],
-    'data-ml': ['machine-learning', 'data-science', 'deep-learning', 'nlp', 'data-pipeline', 'analytics'],
-    education: ['education', 'learning', 'tutorial', 'courseware', 'edtech', 'teaching'],
+    nonprofit: [
+        "nonprofit",
+        "social-good",
+        "humanitarian",
+        "charity",
+        "social-impact",
+        "civic-tech",
+    ],
+    devtools: [
+        "developer-tools",
+        "devtools",
+        "cli",
+        "sdk",
+        "linter",
+        "formatter",
+        "build-tool",
+    ],
+    infrastructure: [
+        "infrastructure",
+        "cloud",
+        "kubernetes",
+        "docker",
+        "devops",
+        "monitoring",
+        "observability",
+    ],
+    "web-frameworks": [
+        "web-framework",
+        "frontend",
+        "backend",
+        "fullstack",
+        "nextjs",
+        "react",
+        "vue",
+    ],
+    "data-ml": [
+        "machine-learning",
+        "data-science",
+        "deep-learning",
+        "nlp",
+        "data-pipeline",
+        "analytics",
+    ],
+    education: [
+        "education",
+        "learning",
+        "tutorial",
+        "courseware",
+        "edtech",
+        "teaching",
+    ],
 };
 /** Well-known GitHub organizations associated with each project category. */
 export const CATEGORY_ORGS = {
-    nonprofit: ['code-for-america', 'opengovfoundation', 'ushahidi', 'hotosm', 'openfn', 'democracyearth'],
-    devtools: ['eslint', 'prettier', 'vitejs', 'biomejs', 'oxc-project', 'ast-grep', 'turbot'],
-    infrastructure: ['kubernetes', 'hashicorp', 'grafana', 'prometheus', 'open-telemetry', 'envoyproxy', 'cncf'],
-    'web-frameworks': ['vercel', 'remix-run', 'sveltejs', 'nuxt', 'astro', 'redwoodjs', 'blitz-js'],
-    'data-ml': ['huggingface', 'mlflow', 'apache', 'dbt-labs', 'dagster-io', 'prefecthq', 'langchain-ai'],
-    education: ['freeCodeCamp', 'TheOdinProject', 'exercism', 'codecademy', 'oppia', 'Khan'],
+    nonprofit: [
+        "code-for-america",
+        "opengovfoundation",
+        "ushahidi",
+        "hotosm",
+        "openfn",
+        "democracyearth",
+    ],
+    devtools: [
+        "eslint",
+        "prettier",
+        "vitejs",
+        "biomejs",
+        "oxc-project",
+        "ast-grep",
+        "turbot",
+    ],
+    infrastructure: [
+        "kubernetes",
+        "hashicorp",
+        "grafana",
+        "prometheus",
+        "open-telemetry",
+        "envoyproxy",
+        "cncf",
+    ],
+    "web-frameworks": [
+        "vercel",
+        "remix-run",
+        "sveltejs",
+        "nuxt",
+        "astro",
+        "redwoodjs",
+        "blitz-js",
+    ],
+    "data-ml": [
+        "huggingface",
+        "mlflow",
+        "apache",
+        "dbt-labs",
+        "dagster-io",
+        "prefecthq",
+        "langchain-ai",
+    ],
+    education: [
+        "freeCodeCamp",
+        "TheOdinProject",
+        "exercism",
+        "codecademy",
+        "oppia",
+        "Khan",
+    ],
 };
 /**
  * Check if a repo belongs to any of the given categories based on its owner matching a category org.
@@ -28,7 +119,7 @@ export const CATEGORY_ORGS = {
 export function repoBelongsToCategory(repoFullName, categories) {
     if (categories.length === 0)
         return false;
-    const owner = repoFullName.split('/')[0]?.toLowerCase();
+    const owner = repoFullName.split("/")[0]?.toLowerCase();
     if (!owner)
         return false;
     for (const category of categories) {

package/dist/core/errors.d.ts

@@ -1,5 +1,12 @@
 /**
  * Custom error type hierarchy for oss-scout.
+ *
+ * Error strategy:
+ * - Auth errors (401) and rate limit errors (429, 403+rate-limit): ALWAYS propagate
+ * - Network errors (ENOTFOUND, ECONNREFUSED, ETIMEDOUT): propagate with context
+ * - Validation errors: propagate
+ * - Cache/filesystem errors: degrade gracefully with warn logging
+ * - API data errors (unexpected shapes): degrade gracefully with warn logging
  */
 export declare class OssScoutError extends Error {
     readonly code: string;
@@ -15,7 +22,7 @@ export declare function errorMessage(e: unknown): string;
 export declare function getHttpStatusCode(error: unknown): number | undefined;
 export declare function isRateLimitError(error: unknown): boolean;
 /** Error codes for JSON output. */
-export type ErrorCode = 'AUTH_REQUIRED' | 'CONFIGURATION' | 'NETWORK' | 'NOT_FOUND' | 'RATE_LIMITED' | 'STATE_CORRUPTED' | 'UNKNOWN' | 'VALIDATION';
+export type ErrorCode = "AUTH_REQUIRED" | "CONFIGURATION" | "NETWORK" | "NOT_FOUND" | "RATE_LIMITED" | "STATE_CORRUPTED" | "UNKNOWN" | "VALIDATION";
 /**
  * Map an unknown error to a structured ErrorCode for JSON output.
  */

package/dist/core/errors.js

@@ -1,33 +1,42 @@
 /**
  * Custom error type hierarchy for oss-scout.
+ *
+ * Error strategy:
+ * - Auth errors (401) and rate limit errors (429, 403+rate-limit): ALWAYS propagate
+ * - Network errors (ENOTFOUND, ECONNREFUSED, ETIMEDOUT): propagate with context
+ * - Validation errors: propagate
+ * - Cache/filesystem errors: degrade gracefully with warn logging
+ * - API data errors (unexpected shapes): degrade gracefully with warn logging
  */
 export class OssScoutError extends Error {
     code;
     constructor(message, code) {
         super(message);
         this.code = code;
-        this.name = 'OssScoutError';
+        this.name = "OssScoutError";
     }
 }
 export class ConfigurationError extends OssScoutError {
     constructor(message) {
-        super(message, 'CONFIGURATION_ERROR');
-        this.name = 'ConfigurationError';
+        super(message, "CONFIGURATION_ERROR");
+        this.name = "ConfigurationError";
     }
 }
 export class ValidationError extends OssScoutError {
     constructor(message) {
-        super(message, 'VALIDATION_ERROR');
-        this.name = 'ValidationError';
+        super(message, "VALIDATION_ERROR");
+        this.name = "ValidationError";
     }
 }
 export function errorMessage(e) {
     return e instanceof Error ? e.message : String(e);
 }
 export function getHttpStatusCode(error) {
-    if (error && typeof error === 'object' && 'status' in error) {
+    if (error && typeof error === "object" && "status" in error) {
         const status = error.status;
-        return typeof status === 'number' && Number.isFinite(status) ? status : undefined;
+        return typeof status === "number" && Number.isFinite(status)
+            ? status
+            : undefined;
     }
     return undefined;
 }
@@ -37,7 +46,7 @@ export function isRateLimitError(error) {
         return true;
     if (status === 403) {
         const msg = errorMessage(error).toLowerCase();
-        return msg.includes('rate limit');
+        return msg.includes("rate limit");
     }
     return false;
 }
@@ -46,24 +55,27 @@ export function isRateLimitError(error) {
  */
 export function resolveErrorCode(err) {
     if (err instanceof ConfigurationError)
-        return 'CONFIGURATION';
+        return "CONFIGURATION";
     if (err instanceof ValidationError)
-        return 'VALIDATION';
+        return "VALIDATION";
     const status = getHttpStatusCode(err);
     if (status === 401)
-        return 'AUTH_REQUIRED';
+        return "AUTH_REQUIRED";
     if (status === 403) {
         const msg = errorMessage(err).toLowerCase();
-        if (msg.includes('rate limit') || msg.includes('abuse detection'))
-            return 'RATE_LIMITED';
-        return 'AUTH_REQUIRED';
+        if (msg.includes("rate limit") || msg.includes("abuse detection"))
+            return "RATE_LIMITED";
+        return "AUTH_REQUIRED";
     }
     if (status === 404)
-        return 'NOT_FOUND';
+        return "NOT_FOUND";
     if (status === 429)
-        return 'RATE_LIMITED';
+        return "RATE_LIMITED";
     const msg = errorMessage(err).toLowerCase();
-    if (msg.includes('enotfound') || msg.includes('econnrefused') || msg.includes('etimedout') || msg.includes('fetch failed'))
-        return 'NETWORK';
-    return 'UNKNOWN';
+    if (msg.includes("enotfound") ||
+        msg.includes("econnrefused") ||
+        msg.includes("etimedout") ||
+        msg.includes("fetch failed"))
+        return "NETWORK";
+    return "UNKNOWN";
 }

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

@@ -4,7 +4,7 @@
  * Stores ScoutState as a private GitHub Gist, with a local file cache
  * as fallback when the API is unavailable.
  */
-import type { ScoutState } from './schemas.js';
+import type { ScoutState } from "./schemas.js";
 /** Minimal Octokit interface for gist operations — keeps the class testable. */
 export interface GistOctokitLike {
     gists: {

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

@@ -4,17 +4,17 @@
  * Stores ScoutState as a private GitHub Gist, with a local file cache
  * as fallback when the API is unavailable.
  */
-import * as fs from 'fs';
-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';
-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';
+import * as fs from "fs";
+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";
+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;
 function getGistIdPath() {
     return path.join(getDataDir(), GIST_ID_FILE);
@@ -47,17 +47,22 @@ export class GistStateStore {
     async push(state) {
         this.writeCache(state);
         if (!this.gistId) {
-            warn(MODULE, 'No gist ID — cannot push');
+            warn(MODULE, "No gist ID — cannot push");
+            return false;
+        }
+        const json = JSON.stringify(state, null, 2);
+        if (json.length > 900000) {
+            warn(MODULE, `State too large for gist (${Math.round(json.length / 1024)}KB). Consider clearing old results with 'oss-scout results clear'.`);
             return false;
         }
         try {
             await this.octokit.gists.update({
                 gist_id: this.gistId,
                 files: {
-                    [GIST_FILENAME]: { content: JSON.stringify(state, null, 2) },
+                    [GIST_FILENAME]: { content: json },
                 },
             });
-            debug(MODULE, 'State pushed to gist');
+            debug(MODULE, "State pushed to gist");
             return true;
         }
         catch (err) {
@@ -104,7 +109,7 @@ export class GistStateStore {
             catch (err) {
                 debug(MODULE, `Cached gist ID invalid: ${errorMessage(err)}`);
             }
-            debug(MODULE, 'Cached gist ID invalid, searching...');
+            debug(MODULE, "Cached gist ID invalid, searching...");
         }
         // 2. Search user's gists
         const foundId = await this.searchForGist();
@@ -117,9 +122,13 @@ export class GistStateStore {
                 this.writeCache(state);
                 return { gistId: foundId, state, created: false };
             }
+            // 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();
         }
         // 3. Create new gist
-        debug(MODULE, 'No existing gist found, creating new one');
+        debug(MODULE, "No existing gist found, creating new one");
         const freshState = ScoutStateSchema.parse({ version: 1 });
         const newId = await this.createGist(freshState);
         this.saveGistId(newId);
@@ -130,20 +139,20 @@ export class GistStateStore {
     bootstrapFromCache() {
         const cached = this.readCache();
         if (cached) {
-            debug(MODULE, 'Bootstrapped from local cache (degraded mode)');
+            debug(MODULE, "Bootstrapped from local cache (degraded mode)");
             const cachedId = this.readCachedGistId();
             if (cachedId)
                 this.gistId = cachedId;
             return {
-                gistId: cachedId ?? '',
+                gistId: cachedId ?? "",
                 state: cached,
                 created: false,
                 degraded: true,
             };
         }
-        debug(MODULE, 'No cache available, using fresh state (degraded mode)');
+        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 };
     }
     // ── Gist API operations ──────────────────────────────────────────────
     async fetchGistState(gistId) {
@@ -187,28 +196,28 @@ export class GistStateStore {
     // ── Local file helpers ───────────────────────────────────────────────
     readCachedGistId() {
         try {
-            const id = fs.readFileSync(getGistIdPath(), 'utf-8').trim();
+            const id = fs.readFileSync(getGistIdPath(), "utf-8").trim();
             return id || null;
         }
         catch (err) {
             const code = err?.code;
-            if (code !== 'ENOENT') {
+            if (code !== "ENOENT") {
                 warn(MODULE, `Failed to read cached gist ID: ${errorMessage(err)}`);
             }
             return null;
         }
     }
     saveGistId(id) {
-        fs.writeFileSync(getGistIdPath(), id + '\n', { mode: 0o600 });
+        fs.writeFileSync(getGistIdPath(), id + "\n", { mode: 0o600 });
     }
     readCache() {
         try {
-            const raw = fs.readFileSync(getCachePath(), 'utf-8');
+            const raw = fs.readFileSync(getCachePath(), "utf-8");
             return ScoutStateSchema.parse(JSON.parse(raw));
         }
         catch (err) {
             const code = err?.code;
-            if (code !== 'ENOENT') {
+            if (code !== "ENOENT") {
                 warn(MODULE, `Failed to read state cache: ${errorMessage(err)}`);
             }
             return null;
@@ -216,7 +225,9 @@ export class GistStateStore {
     }
     writeCache(state) {
         try {
-            fs.writeFileSync(getCachePath(), JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+            fs.writeFileSync(getCachePath(), JSON.stringify(state, null, 2) + "\n", {
+                mode: 0o600,
+            });
         }
         catch (err) {
             warn(MODULE, `Failed to write cache: ${errorMessage(err)}`);
@@ -242,8 +253,10 @@ export function mergeStates(local, remote) {
         mergedPRs: unionByUrl(local.mergedPRs, remote.mergedPRs),
         closedPRs: unionByUrl(local.closedPRs, remote.closedPRs),
         savedResults: mergeSavedResults(local.savedResults ?? [], remote.savedResults ?? []),
+        skippedIssues: mergeSkippedIssues(local.skippedIssues ?? [], remote.skippedIssues ?? []),
         lastSearchAt: pickFresherTimestamp(local.lastSearchAt, remote.lastSearchAt),
-        lastRunAt: pickFresherTimestamp(local.lastRunAt, remote.lastRunAt) ?? new Date().toISOString(),
+        lastRunAt: pickFresherTimestamp(local.lastRunAt, remote.lastRunAt) ??
+            new Date().toISOString(),
         gistId: remote.gistId ?? local.gistId,
     };
 }
@@ -266,7 +279,9 @@ function mergeStarredRepos(local, remote) {
     const localTs = local.starredReposLastFetched;
     const remoteTs = remote.starredReposLastFetched;
     if (!localTs && !remoteTs)
-        return remote.starredRepos.length >= local.starredRepos.length ? remote.starredRepos : local.starredRepos;
+        return remote.starredRepos.length >= local.starredRepos.length
+            ? remote.starredRepos
+            : local.starredRepos;
     if (!localTs)
         return remote.starredRepos;
     if (!remoteTs)
@@ -293,6 +308,18 @@ function mergeSavedResults(local, remote) {
     }
     return [...merged.values()];
 }
+function mergeSkippedIssues(local, remote) {
+    const merged = new Map();
+    for (const item of local)
+        merged.set(item.url, item);
+    for (const item of remote) {
+        const existing = merged.get(item.url);
+        if (!existing || item.skippedAt > existing.skippedAt) {
+            merged.set(item.url, item);
+        }
+    }
+    return [...merged.values()];
+}
 function pickFresherTimestamp(a, b) {
     if (!a)
         return b;

package/dist/core/github.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared GitHub API client with rate limiting and throttling.
  */
-import { Octokit } from '@octokit/rest';
+import { Octokit } from "@octokit/rest";
 interface RateLimitInfo {
     remaining: number;
     limit: number;

package/dist/core/github.js

@@ -1,15 +1,15 @@
 /**
  * Shared GitHub API client with rate limiting and throttling.
  */
-import { Octokit } from '@octokit/rest';
-import { throttling } from '@octokit/plugin-throttling';
-import { warn } from './logger.js';
-const MODULE = 'github';
+import { Octokit } from "@octokit/rest";
+import { throttling } from "@octokit/plugin-throttling";
+import { warn } from "./logger.js";
+const MODULE = "github";
 const ThrottledOctokit = Octokit.plugin(throttling);
 let _octokit = null;
 let _currentToken = null;
 function formatResetTime(date) {
-    return date.toLocaleTimeString('en-US', { hour12: false });
+    return date.toLocaleTimeString("en-US", { hour12: false });
 }
 export function getRateLimitCallbacks() {
     return {