@oss-scout/core 0.2.0 → 0.3.0

package/dist/core/utils.js

@@ -1,39 +1,58 @@
 /**
  * Shared utility functions for oss-scout.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
-import { execFileSync } from 'child_process';
-import { ConfigurationError, errorMessage } from './errors.js';
-import { debug } from './logger.js';
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { execFileSync } from "child_process";
+import { ConfigurationError, errorMessage } from "./errors.js";
+import { debug } from "./logger.js";
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-const MODULE = 'utils';
+const MODULE = "utils";
 let cachedGitHubToken = null;
 let tokenFetchAttempted = false;
 export function getDataDir() {
-    const dir = path.join(os.homedir(), '.oss-scout');
+    const dir = path.join(os.homedir(), ".oss-scout");
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     }
     return dir;
 }
 export function getCacheDir() {
-    const dir = path.join(getDataDir(), 'cache');
+    const dir = path.join(getDataDir(), "cache");
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     }
     return dir;
 }
+/**
+ * Extract "owner/repo" from any GitHub URL format:
+ * - https://github.com/owner/repo
+ * - https://github.com/owner/repo/pull/123
+ * - https://github.com/owner/repo/issues/123
+ * - https://api.github.com/repos/owner/repo
+ * - https://api.github.com/repos/owner/repo/...
+ */
+export function extractRepoFromUrl(url) {
+    // API URLs: https://api.github.com/repos/owner/repo[/...]
+    const apiMatch = url.match(/api\.github\.com\/repos\/([^/]+\/[^/]+)/);
+    if (apiMatch)
+        return apiMatch[1];
+    // Web URLs: https://github.com/owner/repo[/...]
+    const webMatch = url.match(/github\.com\/([^/]+\/[^/]+)/);
+    if (webMatch)
+        return webMatch[1];
+    return null;
+}
 const OWNER_PATTERN = /^[a-zA-Z0-9_-]+$/;
 const REPO_PATTERN = /^[a-zA-Z0-9_.-]+$/;
 function isValidOwnerRepo(owner, repo) {
     return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo);
 }
 export function parseGitHubUrl(url) {
-    if (!url.startsWith('https://github.com/'))
+    if (!url.startsWith("https://github.com/"))
         return null;
     const prMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
     if (prMatch) {
@@ -41,7 +60,7 @@ export function parseGitHubUrl(url) {
         const repo = prMatch[2];
         if (!isValidOwnerRepo(owner, repo))
             return null;
-        return { owner, repo, number: parseInt(prMatch[3], 10), type: 'pull' };
+        return { owner, repo, number: parseInt(prMatch[3], 10), type: "pull" };
     }
     const issueMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
     if (issueMatch) {
@@ -49,7 +68,7 @@ export function parseGitHubUrl(url) {
         const repo = issueMatch[2];
         if (!isValidOwnerRepo(owner, repo))
             return null;
-        return { owner, repo, number: parseInt(issueMatch[3], 10), type: 'issues' };
+        return { owner, repo, number: parseInt(issueMatch[3], 10), type: "issues" };
     }
     return null;
 }
@@ -58,12 +77,12 @@ export function daysBetween(from, to = new Date()) {
 }
 export function getCLIVersion() {
     try {
-        const pkgPath = path.join(path.dirname(process.argv[1]), '..', 'package.json');
-        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+        const pkgPath = path.join(path.dirname(process.argv[1]), "..", "package.json");
+        return JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
     }
     catch (err) {
         debug(MODULE, `Could not read CLI version: ${errorMessage(err)}`);
-        return 'unknown';
+        return "unknown";
     }
 }
 export function getGitHubToken() {
@@ -77,30 +96,30 @@ export function getGitHubToken() {
         return cachedGitHubToken;
     }
     try {
-        const token = execFileSync('gh', ['auth', 'token'], {
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
+        const token = execFileSync("gh", ["auth", "token"], {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
             timeout: 2000,
         }).trim();
         if (token && token.length > 0) {
             cachedGitHubToken = token;
-            debug(MODULE, 'Using GitHub token from gh CLI');
+            debug(MODULE, "Using GitHub token from gh CLI");
             return cachedGitHubToken;
         }
     }
     catch (err) {
-        debug(MODULE, 'gh auth token failed', err);
+        debug(MODULE, "gh auth token failed", err);
     }
     return null;
 }
 export function requireGitHubToken() {
     const token = getGitHubToken();
     if (!token) {
-        throw new ConfigurationError('GitHub authentication required.\n\n' +
-            'Options:\n' +
-            '  1. Use gh CLI: gh auth login\n' +
-            '  2. Set GITHUB_TOKEN environment variable\n\n' +
-            'The gh CLI is recommended - install from https://cli.github.com');
+        throw new ConfigurationError("GitHub authentication required.\n\n" +
+            "Options:\n" +
+            "  1. Use gh CLI: gh auth login\n" +
+            "  2. Set GITHUB_TOKEN environment variable\n\n" +
+            "The gh CLI is recommended - install from https://cli.github.com");
     }
     return token;
 }

package/dist/formatters/json.d.ts

@@ -1,6 +1,6 @@
 /**
  * JSON output formatter for oss-scout CLI.
  */
-import type { ErrorCode } from '../core/errors.js';
+import type { ErrorCode } from "../core/errors.js";
 export declare function formatJsonSuccess<T>(data: T): string;
 export declare function formatJsonError(error: string, errorCode?: ErrorCode): string;

package/dist/index.d.ts

@@ -14,10 +14,10 @@
  *
  * @packageDocumentation
  */
-export { createScout, OssScout } from './scout.js';
-export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectHealth, SearchPriority, CheckResult, VetListOptions, VetListResult, VetListEntry, VetListSummary, } from './core/types.js';
-export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, SearchStrategy, } from './core/schemas.js';
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from './core/schemas.js';
-export { requireGitHubToken, getGitHubToken } from './core/utils.js';
-export { IssueDiscovery } from './core/issue-discovery.js';
-export { IssueVetter, type ScoutStateReader } from './core/issue-vetting.js';
+export { createScout, OssScout } from "./scout.js";
+export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectHealth, SearchPriority, CheckResult, VetListOptions, VetListResult, VetListEntry, VetListSummary, } from "./core/types.js";
+export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, SearchStrategy, SkippedIssue, } from "./core/schemas.js";
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, } from "./core/schemas.js";
+export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
+export { IssueDiscovery } from "./core/issue-discovery.js";
+export { IssueVetter, type ScoutStateReader } from "./core/issue-vetting.js";

package/dist/index.js

@@ -15,11 +15,11 @@
  * @packageDocumentation
  */
 // Main API
-export { createScout, OssScout } from './scout.js';
+export { createScout, OssScout } from "./scout.js";
 // Schemas (for consumers who need runtime validation)
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from './core/schemas.js';
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, } from "./core/schemas.js";
 // Utilities
-export { requireGitHubToken, getGitHubToken } from './core/utils.js';
+export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
 // Internal classes (for advanced use)
-export { IssueDiscovery } from './core/issue-discovery.js';
-export { IssueVetter } from './core/issue-vetting.js';
+export { IssueDiscovery } from "./core/issue-discovery.js";
+export { IssueVetter } from "./core/issue-vetting.js";

package/dist/scout.d.ts

@@ -4,10 +4,10 @@
  * Provides personalized issue discovery, vetting, and scoring.
  * Implements ScoutStateReader to bridge state with the search engine.
  */
-import type { ScoutStateReader } from './core/issue-vetting.js';
-import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate } from './core/schemas.js';
-import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectCategory, VetListOptions, VetListResult } from './core/types.js';
-import { GistStateStore } from './core/gist-state-store.js';
+import type { ScoutStateReader } from "./core/issue-vetting.js";
+import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate, SkippedIssue } from "./core/schemas.js";
+import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectCategory, VetListOptions, VetListResult } from "./core/types.js";
+import { GistStateStore } from "./core/gist-state-store.js";
 /**
  * Create an OssScout instance.
  *
@@ -44,6 +44,7 @@ export declare class OssScout implements ScoutStateReader {
     constructor(githubToken: string, initialState: ScoutState, gistStore?: GistStateStore | null);
     /**
      * Multi-strategy issue search. Returns scored, sorted candidates.
+     * Automatically culls expired skip entries and filters skipped issues.
      */
     search(options?: SearchOptions): Promise<SearchResult>;
     /**
@@ -59,7 +60,6 @@ export declare class OssScout implements ScoutStateReader {
     private classifyVetResult;
     getReposWithMergedPRs(): string[];
     getStarredRepos(): string[];
-    getPreferredOrgs(): string[];
     getProjectCategories(): ProjectCategory[];
     getRepoScore(repo: string): number | null;
     /** Get current preferences (read-only). */
@@ -101,6 +101,31 @@ export declare class OssScout implements ScoutStateReader {
      * Clear all saved results.
      */
     clearResults(): void;
+    /**
+     * Skip an issue — excludes it from future searches. Auto-culled after 90 days.
+     */
+    skipIssue(url: string, metadata?: {
+        repo?: string;
+        number?: number;
+        title?: string;
+    }): void;
+    /**
+     * Get all skipped issues.
+     */
+    getSkippedIssues(): SkippedIssue[];
+    /**
+     * Remove a specific issue from the skip list.
+     */
+    unskipIssue(url: string): void;
+    /**
+     * Clear all skipped issues.
+     */
+    clearSkippedIssues(): void;
+    /**
+     * Remove skipped issues older than maxDays (default 90). Called automatically during search.
+     * @returns The number of expired entries that were removed.
+     */
+    cullExpiredSkips(maxDays?: number): number;
     /**
      * Check if state has uncommitted changes.
      */
@@ -114,7 +139,6 @@ export declare class OssScout implements ScoutStateReader {
      * Get the full state snapshot for serialization or external consumption.
      */
     getState(): Readonly<ScoutState>;
-    private extractRepoFromUrl;
     private updateRepoScoreFromPRs;
     /**
      * Calculate repo score (1-10) from observed data.

package/dist/scout.js

@@ -4,12 +4,55 @@
  * Provides personalized issue discovery, vetting, and scoring.
  * Implements ScoutStateReader to bridge state with the search engine.
  */
-import { IssueDiscovery } from './core/issue-discovery.js';
-import { ScoutStateSchema } from './core/schemas.js';
-import { GistStateStore, mergeStates } from './core/gist-state-store.js';
-import { getOctokit } from './core/github.js';
-import { loadLocalState } from './core/local-state.js';
-import { warn } from './core/logger.js';
+import { IssueDiscovery } from "./core/issue-discovery.js";
+import { ScoutStateSchema } from "./core/schemas.js";
+import { GistStateStore, mergeStates } from "./core/gist-state-store.js";
+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";
+/** Wrap a real Octokit instance as GistOctokitLike without unsafe double casts. */
+function toGistOctokit(octokit) {
+    return {
+        gists: {
+            async get(params) {
+                const { data } = await octokit.gists.get(params);
+                if (!data.id)
+                    throw new Error("Gist get returned no id");
+                const files = data.files
+                    ? Object.fromEntries(Object.entries(data.files).map(([k, v]) => [
+                        k,
+                        v ? { content: v.content } : undefined,
+                    ]))
+                    : null;
+                return { data: { id: data.id, files } };
+            },
+            async create(params) {
+                const { data } = await octokit.gists.create(params);
+                if (!data.id)
+                    throw new Error("Gist create returned no id");
+                return { data: { id: data.id } };
+            },
+            async update(params) {
+                const { data } = await octokit.gists.update(params);
+                if (!data.id)
+                    throw new Error("Gist update returned no id");
+                return { data: { id: data.id } };
+            },
+            async list(params) {
+                const { data } = await octokit.gists.list(params);
+                return {
+                    data: data
+                        .filter((g) => g.id)
+                        .map((g) => ({
+                        id: g.id,
+                        description: g.description ?? null,
+                    })),
+                };
+            },
+        },
+    };
+}
 /**
  * Create an OssScout instance.
  *
@@ -34,14 +77,14 @@ import { warn } from './core/logger.js';
 export async function createScout(config) {
     let state;
     let gistStore = null;
-    if (config.persistence === 'provided') {
+    if (config.persistence === "provided") {
         state = config.initialState;
     }
-    else if (config.persistence === 'gist') {
-        gistStore = new GistStateStore(getOctokit(config.githubToken));
+    else if (config.persistence === "gist") {
+        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", "Gist sync unavailable — running in offline mode. Changes will only be saved locally.");
         }
         const localState = loadLocalState();
         state = mergeStates(localState, result.state);
@@ -76,12 +119,17 @@ export class OssScout {
     // ── Search ──────────────────────────────────────────────────────────
     /**
      * Multi-strategy issue search. Returns scored, sorted candidates.
+     * Automatically culls expired skip entries and filters skipped issues.
      */
     async search(options) {
+        // Auto-cull expired skips before searching
+        this.cullExpiredSkips();
+        const skippedUrls = new Set((this.state.skippedIssues ?? []).map((s) => s.url));
         const discovery = new IssueDiscovery(this.githubToken, this.state.preferences, this);
         const { candidates, strategiesUsed } = await discovery.searchIssues({
             maxResults: options?.maxResults,
             strategies: options?.strategies,
+            skippedUrls,
         });
         this.state.lastSearchAt = new Date().toISOString();
         this.dirty = true;
@@ -126,13 +174,13 @@ export class OssScout {
             })
                 .catch((error) => {
                 const msg = error instanceof Error ? error.message : String(error);
-                const isGone = msg.includes('Not Found') || msg.includes('410');
+                const isGone = msg.includes("Not Found") || msg.includes("410");
                 results.push({
                     issueUrl: item.issueUrl,
                     repo: item.repo,
                     number: item.number,
                     title: item.title,
-                    status: isGone ? 'closed' : 'error',
+                    status: isGone ? "closed" : "error",
                     errorMessage: msg,
                 });
             })
@@ -147,15 +195,18 @@ export class OssScout {
         await Promise.allSettled(pending.values());
         const summary = {
             total: results.length,
-            stillAvailable: results.filter((r) => r.status === 'still_available').length,
-            claimed: results.filter((r) => r.status === 'claimed').length,
-            closed: results.filter((r) => r.status === 'closed').length,
-            hasPR: results.filter((r) => r.status === 'has_pr').length,
-            errors: results.filter((r) => r.status === 'error').length,
+            stillAvailable: results.filter((r) => r.status === "still_available")
+                .length,
+            claimed: results.filter((r) => r.status === "claimed").length,
+            closed: results.filter((r) => r.status === "closed").length,
+            hasPR: results.filter((r) => r.status === "has_pr").length,
+            errors: results.filter((r) => r.status === "error").length,
         };
         let prunedCount;
         if (options?.prune) {
-            const unavailableUrls = new Set(results.filter((r) => r.status !== 'still_available').map((r) => r.issueUrl));
+            const unavailableUrls = new Set(results
+                .filter((r) => r.status !== "still_available")
+                .map((r) => r.issueUrl));
             const before = (this.state.savedResults ?? []).length;
             this.state.savedResults = (this.state.savedResults ?? []).filter((r) => !unavailableUrls.has(r.issueUrl));
             prunedCount = before - (this.state.savedResults?.length ?? 0);
@@ -166,16 +217,16 @@ export class OssScout {
     classifyVetResult(candidate) {
         const checks = candidate.vettingResult.checks;
         if (!checks.noExistingPR)
-            return 'has_pr';
+            return "has_pr";
         if (!checks.notClaimed)
-            return 'claimed';
-        return 'still_available';
+            return "claimed";
+        return "still_available";
     }
     // ── State Reads (ScoutStateReader implementation) ───────────────────
     getReposWithMergedPRs() {
         const repoCounts = new Map();
         for (const pr of this.state.mergedPRs ?? []) {
-            const repo = this.extractRepoFromUrl(pr.url);
+            const repo = extractRepoFromUrl(pr.url);
             if (repo) {
                 repoCounts.set(repo, (repoCounts.get(repo) ?? 0) + 1);
             }
@@ -188,9 +239,6 @@ export class OssScout {
     getStarredRepos() {
         return this.state.starredRepos;
     }
-    getPreferredOrgs() {
-        return this.state.preferences.preferredOrgs;
-    }
     getProjectCategories() {
         return this.state.preferences.projectCategories;
     }
@@ -323,6 +371,70 @@ export class OssScout {
         this.state.savedResults = [];
         this.dirty = true;
     }
+    // ── Skip List ───────────────────────────────────────────────────────
+    /**
+     * Skip an issue — excludes it from future searches. Auto-culled after 90 days.
+     */
+    skipIssue(url, metadata) {
+        const existing = this.state.skippedIssues ?? [];
+        if (existing.some((s) => s.url === url))
+            return; // already skipped
+        this.state.skippedIssues = [
+            ...existing,
+            {
+                url,
+                repo: metadata?.repo ?? "",
+                number: metadata?.number ?? 0,
+                title: metadata?.title ?? "",
+                skippedAt: new Date().toISOString(),
+            },
+        ];
+        // Also remove from saved results if present
+        if (this.state.savedResults) {
+            this.state.savedResults = this.state.savedResults.filter((r) => r.issueUrl !== url);
+        }
+        this.dirty = true;
+    }
+    /**
+     * Get all skipped issues.
+     */
+    getSkippedIssues() {
+        return this.state.skippedIssues ?? [];
+    }
+    /**
+     * Remove a specific issue from the skip list.
+     */
+    unskipIssue(url) {
+        this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => s.url !== url);
+        this.dirty = true;
+    }
+    /**
+     * Clear all skipped issues.
+     */
+    clearSkippedIssues() {
+        this.state.skippedIssues = [];
+        this.dirty = true;
+    }
+    /**
+     * Remove skipped issues older than maxDays (default 90). Called automatically during search.
+     * @returns The number of expired entries that were removed.
+     */
+    cullExpiredSkips(maxDays = 90) {
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - maxDays);
+        const before = (this.state.skippedIssues ?? []).length;
+        this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => {
+            const d = new Date(s.skippedAt);
+            if (isNaN(d.getTime())) {
+                return true; // keep entries with invalid dates rather than silently dropping
+            }
+            return d >= cutoff;
+        });
+        const culled = before - this.state.skippedIssues.length;
+        if (culled > 0)
+            this.dirty = true;
+        return culled;
+    }
     // ── Persistence ─────────────────────────────────────────────────────
     /**
      * Check if state has uncommitted changes.
@@ -353,21 +465,16 @@ export class OssScout {
         return this.state;
     }
     // ── Private helpers ─────────────────────────────────────────────────
-    extractRepoFromUrl(url) {
-        const match = url.match(/github\.com\/([^/]+\/[^/]+)\//);
-        return match ? match[1] : null;
-    }
     updateRepoScoreFromPRs(repo) {
-        const mergedCount = (this.state.mergedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).length;
-        const closedCount = (this.state.closedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).length;
+        const mergedCount = (this.state.mergedPRs ?? []).filter((p) => extractRepoFromUrl(p.url) === repo).length;
+        const closedCount = (this.state.closedPRs ?? []).filter((p) => extractRepoFromUrl(p.url) === repo).length;
         this.updateRepoScore(repo, {
             mergedPRCount: mergedCount,
             closedWithoutMergeCount: closedCount,
             lastMergedAt: mergedCount > 0
                 ? (this.state.mergedPRs ?? [])
-                    .filter((p) => this.extractRepoFromUrl(p.url) === repo)
-                    .sort((a, b) => b.mergedAt.localeCompare(a.mergedAt))[0]
-                    ?.mergedAt
+                    .filter((p) => extractRepoFromUrl(p.url) === repo)
+                    .sort((a, b) => b.mergedAt.localeCompare(a.mergedAt))[0]?.mergedAt
                 : undefined,
         });
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.2.0",
-  "description": "Find open source issues personalized to your contribution history",
+  "version": "0.3.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": {
     "oss-scout": "./dist/cli.bundle.cjs"
@@ -37,7 +37,11 @@
     "issue-discovery",
     "cli",
     "vetting",
-    "contributions"
+    "contributions",
+    "claude",
+    "mcp-server",
+    "contribution-finder",
+    "personalized"
   ],
   "author": "John Costa",
   "license": "MIT",