@oss-scout/core 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Core types for oss-scout — ephemeral types that are never persisted.
+ */
+import type { RepoSignals, TrackedIssue, IssueVettingResult, IssueScope, ScoutState, SearchStrategy } from './schemas.js';
+export type { ProjectCategory, IssueScope, RepoSignals, RepoScore, StoredMergedPR, StoredClosedPR, ContributionGuidelines, IssueVettingResult, TrackedIssue, ScoutPreferences, SavedCandidate, ScoutState, SearchStrategy, } from './schemas.js';
+/** Health snapshot of a GitHub repository. */
+export interface ProjectHealth {
+    repo: string;
+    lastCommitAt: string;
+    daysSinceLastCommit: number;
+    openIssuesCount: number;
+    avgIssueResponseDays: number;
+    ciStatus: 'passing' | 'failing' | 'unknown';
+    isActive: boolean;
+    stargazersCount?: number;
+    forksCount?: number;
+    language?: string | null;
+    checkFailed?: boolean;
+    failureReason?: string;
+}
+/** Priority tier for issue search results. */
+export type SearchPriority = 'merged_pr' | 'preferred_org' | 'starred' | 'normal';
+/** A fully vetted issue candidate with scoring. */
+export interface IssueCandidate {
+    issue: TrackedIssue;
+    vettingResult: IssueVettingResult;
+    projectHealth: ProjectHealth;
+    recommendation: 'approve' | 'skip' | 'needs_review';
+    reasonsToSkip: string[];
+    reasonsToApprove: string[];
+    viabilityScore: number;
+    searchPriority: SearchPriority;
+}
+/** Subset of RepoScore fields that callers may update. */
+export interface RepoScoreUpdate {
+    mergedPRCount?: number;
+    closedWithoutMergeCount?: number;
+    avgResponseDays?: number | null;
+    lastMergedAt?: string;
+    signals?: Partial<RepoSignals>;
+    stargazersCount?: number;
+    language?: string | null;
+}
+/** Result of a check (e.g., no existing PR, not claimed). */
+export interface CheckResult {
+    passed: boolean;
+    inconclusive?: boolean;
+    reason?: string;
+}
+export declare const SCOPE_LABELS: Record<IssueScope, string[]>;
+/** Options for batch vetting saved results. */
+export interface VetListOptions {
+    concurrency?: number;
+    prune?: boolean;
+}
+/** A single entry in the vet-list result. */
+export interface VetListEntry {
+    issueUrl: string;
+    repo: string;
+    number: number;
+    title: string;
+    status: 'still_available' | 'claimed' | 'closed' | 'has_pr' | 'error';
+    recommendation?: 'approve' | 'skip' | 'needs_review';
+    viabilityScore?: number;
+    errorMessage?: string;
+}
+/** Summary counts for a vet-list run. */
+export interface VetListSummary {
+    total: number;
+    stillAvailable: number;
+    claimed: number;
+    closed: number;
+    hasPR: number;
+    errors: number;
+}
+/** Result of a batch vet-list operation. */
+export interface VetListResult {
+    results: VetListEntry[];
+    summary: VetListSummary;
+    prunedCount?: number;
+}
+/** Configuration for creating an OssScout instance. */
+export type ScoutConfig = {
+    /** GitHub token with `repo` read scope. Add `gist` scope for persistence. */
+    githubToken: string;
+    /** Use gist-backed persistence (default for standalone CLI). */
+    persistence?: 'gist';
+    /** Gist ID override. Skips gist discovery/creation if provided. */
+    gistId?: string;
+} | {
+    /** GitHub token with `repo` read scope. */
+    githubToken: string;
+    /** Caller provides state directly. */
+    persistence: 'provided';
+    /** Pre-loaded state. Required when persistence is 'provided'. */
+    initialState: ScoutState;
+};
+/** Options for the search method. */
+export interface SearchOptions {
+    maxResults?: number;
+    strategies?: SearchStrategy[];
+}
+/** Result of a search operation. */
+export interface SearchResult {
+    candidates: IssueCandidate[];
+    excludedRepos: string[];
+    aiPolicyBlocklist: string[];
+    rateLimitWarning?: string;
+    strategiesUsed: SearchStrategy[];
+}
+/** Record of a merged PR for state contribution. */
+export interface MergedPRRecord {
+    url: string;
+    title: string;
+    mergedAt: string;
+    repo: string;
+}
+/** Record of a closed PR for state contribution. */
+export interface ClosedPRRecord {
+    url: string;
+    title: string;
+    closedAt: string;
+    repo: string;
+}

package/dist/core/types.js

@@ -0,0 +1,9 @@
+/**
+ * Core types for oss-scout — ephemeral types that are never persisted.
+ */
+// ── Const arrays and mappings ───────────────────────────────────────
+export const SCOPE_LABELS = {
+    beginner: ['good first issue', 'help wanted', 'easy', 'up-for-grabs', 'first-timers-only', 'beginner'],
+    intermediate: ['enhancement', 'feature', 'feature-request', 'contributions welcome'],
+    advanced: ['proposal', 'RFC', 'accepted', 'design'],
+};

package/dist/core/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared utility functions for oss-scout.
+ */
+export declare function sleep(ms: number): Promise<void>;
+export declare function getDataDir(): string;
+export declare function getCacheDir(): string;
+interface ParsedGitHubUrl {
+    owner: string;
+    repo: string;
+    number: number;
+    type: 'pull' | 'issues';
+}
+export declare function parseGitHubUrl(url: string): ParsedGitHubUrl | null;
+export declare function daysBetween(from: Date, to?: Date): number;
+export declare function getCLIVersion(): string;
+export declare function getGitHubToken(): string | null;
+export declare function requireGitHubToken(): string;
+export {};

package/dist/core/utils.js

@@ -0,0 +1,106 @@
+/**
+ * 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';
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const MODULE = 'utils';
+let cachedGitHubToken = null;
+let tokenFetchAttempted = false;
+export function getDataDir() {
+    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');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+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/'))
+        return null;
+    const prMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+    if (prMatch) {
+        const owner = prMatch[1];
+        const repo = prMatch[2];
+        if (!isValidOwnerRepo(owner, repo))
+            return null;
+        return { owner, repo, number: parseInt(prMatch[3], 10), type: 'pull' };
+    }
+    const issueMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
+    if (issueMatch) {
+        const owner = issueMatch[1];
+        const repo = issueMatch[2];
+        if (!isValidOwnerRepo(owner, repo))
+            return null;
+        return { owner, repo, number: parseInt(issueMatch[3], 10), type: 'issues' };
+    }
+    return null;
+}
+export function daysBetween(from, to = new Date()) {
+    return Math.max(0, Math.floor((to.getTime() - from.getTime()) / (1000 * 60 * 60 * 24)));
+}
+export function getCLIVersion() {
+    try {
+        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';
+    }
+}
+export function getGitHubToken() {
+    if (cachedGitHubToken)
+        return cachedGitHubToken;
+    if (tokenFetchAttempted)
+        return null;
+    tokenFetchAttempted = true;
+    if (process.env.GITHUB_TOKEN) {
+        cachedGitHubToken = process.env.GITHUB_TOKEN;
+        return cachedGitHubToken;
+    }
+    try {
+        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');
+            return cachedGitHubToken;
+        }
+    }
+    catch (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');
+    }
+    return token;
+}

package/dist/formatters/json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * JSON output formatter for oss-scout CLI.
+ */
+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/formatters/json.js

@@ -0,0 +1,20 @@
+/**
+ * JSON output formatter for oss-scout CLI.
+ */
+export function formatJsonSuccess(data) {
+    const output = {
+        success: true,
+        data,
+        timestamp: new Date().toISOString(),
+    };
+    return JSON.stringify(output, null, 2);
+}
+export function formatJsonError(error, errorCode) {
+    const output = {
+        success: false,
+        error,
+        errorCode,
+        timestamp: new Date().toISOString(),
+    };
+    return JSON.stringify(output, null, 2);
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @oss-scout/core — Find open source issues personalized to your contribution history.
+ *
+ * @example
+ * ```typescript
+ * import { createScout } from '@oss-scout/core';
+ *
+ * const scout = await createScout({ githubToken: 'ghp_...' });
+ * const results = await scout.search({ maxResults: 10 });
+ * for (const c of results.candidates) {
+ *   console.log(`${c.issue.repo}#${c.issue.number}: ${c.viabilityScore}/100`);
+ * }
+ * ```
+ *
+ * @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';

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @oss-scout/core — Find open source issues personalized to your contribution history.
+ *
+ * @example
+ * ```typescript
+ * import { createScout } from '@oss-scout/core';
+ *
+ * const scout = await createScout({ githubToken: 'ghp_...' });
+ * const results = await scout.search({ maxResults: 10 });
+ * for (const c of results.candidates) {
+ *   console.log(`${c.issue.repo}#${c.issue.number}: ${c.viabilityScore}/100`);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Main API
+export { createScout, OssScout } from './scout.js';
+// Schemas (for consumers who need runtime validation)
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from './core/schemas.js';
+// Utilities
+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';

package/dist/scout.d.ts

@@ -0,0 +1,125 @@
+/**
+ * OssScout — the public API for oss-scout.
+ *
+ * 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';
+/**
+ * Create an OssScout instance.
+ *
+ * @param config - Configuration including GitHub token and persistence mode
+ * @returns A ready-to-use OssScout instance
+ *
+ * @example
+ * ```typescript
+ * import { createScout } from '@oss-scout/core';
+ *
+ * // Standalone with gist persistence
+ * const scout = await createScout({ githubToken: 'ghp_...', persistence: 'gist' });
+ *
+ * // As a library (host application provides state)
+ * const scout = await createScout({
+ *   githubToken: 'ghp_...',
+ *   persistence: 'provided',
+ *   initialState: myState,
+ * });
+ * ```
+ */
+export declare function createScout(config: ScoutConfig): Promise<OssScout>;
+/**
+ * Main oss-scout class. Provides search, vetting, and state management.
+ *
+ * Implements ScoutStateReader so the search engine can read state
+ * without knowing about the persistence layer.
+ */
+export declare class OssScout implements ScoutStateReader {
+    private githubToken;
+    private gistStore;
+    private state;
+    private dirty;
+    constructor(githubToken: string, initialState: ScoutState, gistStore?: GistStateStore | null);
+    /**
+     * Multi-strategy issue search. Returns scored, sorted candidates.
+     */
+    search(options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Vet a single issue URL for claimability.
+     */
+    vetIssue(issueUrl: string): Promise<IssueCandidate>;
+    /**
+     * Re-vet all saved results with bounded concurrency.
+     * Classifies each as still_available, claimed, has_pr, closed, or error.
+     * Optionally prunes unavailable issues from saved results.
+     */
+    vetList(options?: VetListOptions): Promise<VetListResult>;
+    private classifyVetResult;
+    getReposWithMergedPRs(): string[];
+    getStarredRepos(): string[];
+    getPreferredOrgs(): string[];
+    getProjectCategories(): ProjectCategory[];
+    getRepoScore(repo: string): number | null;
+    /** Get current preferences (read-only). */
+    getPreferences(): Readonly<ScoutPreferences>;
+    /** Get repo score record for a specific repository. */
+    getRepoScoreRecord(repo: string): Readonly<RepoScore> | undefined;
+    /**
+     * Record that a PR was merged in this repo.
+     * Updates the merged PRs list and recalculates the repo score.
+     */
+    recordMergedPR(pr: MergedPRRecord): void;
+    /**
+     * Record that a PR was closed without merge.
+     */
+    recordClosedPR(pr: ClosedPRRecord): void;
+    /**
+     * Update repo score with observed signals.
+     */
+    updateRepoScore(repo: string, update: Partial<RepoScoreUpdate>): void;
+    /**
+     * Update user preferences.
+     */
+    updatePreferences(updates: Partial<ScoutPreferences>): void;
+    /**
+     * Update starred repos cache.
+     */
+    setStarredRepos(repos: string[]): void;
+    /**
+     * Save search candidates to state, deduplicating by URL.
+     * If a candidate already exists, updates score/recommendation/lastSeenAt
+     * but preserves firstSeenAt.
+     */
+    saveResults(candidates: IssueCandidate[]): void;
+    /**
+     * Get all saved results.
+     */
+    getSavedResults(): SavedCandidate[];
+    /**
+     * Clear all saved results.
+     */
+    clearResults(): void;
+    /**
+     * Check if state has uncommitted changes.
+     */
+    isDirty(): boolean;
+    /**
+     * Push pending changes to the persistence layer.
+     * Pushes to gist if gist persistence is configured.
+     */
+    checkpoint(): Promise<boolean>;
+    /**
+     * 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.
+     * base 5, +1 per merged PR (max +3), -1 per closed-without-merge (max -3),
+     * +1 responsive, +1 active maintainers, -2 hostile comments, clamped 1-10
+     */
+    private calculateScore;
+}