@oss-scout/core 0.1.0

package/dist/commands/setup.js

@@ -0,0 +1,104 @@
+/**
+ * Setup command — interactive first-run configuration for oss-scout.
+ */
+import * as readline from 'readline';
+import { execFile } from 'child_process';
+import { ScoutPreferencesSchema, ProjectCategorySchema, IssueScopeSchema } from '../core/schemas.js';
+const ALL_CATEGORIES = ProjectCategorySchema.options;
+const ALL_SCOPES = IssueScopeSchema.options;
+function createReadlineInterface() {
+    return readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+}
+function ask(rl, query) {
+    return new Promise((resolve) => {
+        rl.question(query, (answer) => resolve(answer.trim()));
+    });
+}
+function detectGitHubUsername() {
+    return new Promise((resolve) => {
+        execFile('gh', ['api', 'user', '--jq', '.login'], { timeout: 5000 }, (err, stdout) => {
+            if (err || !stdout.trim()) {
+                resolve('');
+            }
+            else {
+                resolve(stdout.trim());
+            }
+        });
+    });
+}
+function parseCSV(input) {
+    return input
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function parseMultiSelect(input, options) {
+    if (!input)
+        return [];
+    const selected = parseCSV(input);
+    return selected.filter((s) => options.includes(s));
+}
+/**
+ * Run the interactive setup flow and return the configured preferences.
+ */
+export async function runSetup(options) {
+    const rl = options?.rl ?? createReadlineInterface();
+    const detect = options?.detectUsername ?? detectGitHubUsername;
+    try {
+        console.log('\n🔧 oss-scout setup\n');
+        // Detect GitHub username
+        console.log('Detecting GitHub username...');
+        const detectedUsername = await detect();
+        const usernameDefault = detectedUsername || '';
+        const usernamePrompt = detectedUsername
+            ? `GitHub username [${detectedUsername}]: `
+            : 'GitHub username: ';
+        const usernameInput = await ask(rl, usernamePrompt);
+        const githubUsername = usernameInput || usernameDefault;
+        // Languages
+        const defaultLangs = 'typescript, javascript';
+        const langsInput = await ask(rl, `Preferred languages [${defaultLangs}]: `);
+        const languages = langsInput ? parseCSV(langsInput) : ['typescript', 'javascript'];
+        // Issue labels
+        const defaultLabels = 'good first issue, help wanted';
+        const labelsInput = await ask(rl, `Issue labels to search for [${defaultLabels}]: `);
+        const labels = labelsInput ? parseCSV(labelsInput) : ['good first issue', 'help wanted'];
+        // Difficulty scope
+        const scopeOptions = ALL_SCOPES.join(', ');
+        const scopeInput = await ask(rl, `Difficulty scope (${scopeOptions}) [all]: `);
+        const scope = scopeInput ? parseMultiSelect(scopeInput, ALL_SCOPES) : [...ALL_SCOPES];
+        // Minimum stars
+        const minStarsInput = await ask(rl, 'Minimum repo stars [50]: ');
+        const minStars = minStarsInput ? parseInt(minStarsInput, 10) : 50;
+        // Preferred organizations
+        const orgsInput = await ask(rl, 'Preferred organizations (comma-separated, optional): ');
+        const preferredOrgs = parseCSV(orgsInput);
+        // Project categories
+        const categoryOptions = ALL_CATEGORIES.join(', ');
+        const categoriesInput = await ask(rl, `Project categories (${categoryOptions}) [none]: `);
+        const projectCategories = parseMultiSelect(categoriesInput, ALL_CATEGORIES);
+        // Repos to exclude
+        const excludeInput = await ask(rl, 'Repos to exclude (owner/repo, comma-separated, optional): ');
+        const excludeRepos = parseCSV(excludeInput);
+        const prefs = ScoutPreferencesSchema.parse({
+            githubUsername,
+            languages,
+            labels,
+            scope: scope.length > 0 ? scope : undefined,
+            excludeRepos,
+            preferredOrgs,
+            projectCategories,
+            minStars: isNaN(minStars) ? 50 : minStars,
+        });
+        console.log('\n✅ Setup complete! Preferences saved.\n');
+        return prefs;
+    }
+    finally {
+        if (!options?.rl) {
+            rl.close();
+        }
+    }
+}

package/dist/commands/validation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared validation patterns and helpers for CLI commands.
+ */
+export declare const ISSUE_URL_PATTERN: RegExp;
+export declare function validateGitHubUrl(url: string, pattern: RegExp, entityType: 'issue'): void;
+export declare function validateUrl(url: string): string;

package/dist/commands/validation.js

@@ -0,0 +1,17 @@
+/**
+ * Shared validation patterns and helpers for CLI commands.
+ */
+import { ValidationError } from '../core/errors.js';
+export const ISSUE_URL_PATTERN = /^https:\/\/github\.com\/[^/]+\/[^/]+\/issues\/\d+$/;
+const MAX_URL_LENGTH = 2048;
+export function validateGitHubUrl(url, pattern, entityType) {
+    if (pattern.test(url))
+        return;
+    throw new ValidationError(`Invalid ${entityType} URL: ${url}. Expected format: https://github.com/owner/repo/issues/123`);
+}
+export function validateUrl(url) {
+    if (url.length > MAX_URL_LENGTH) {
+        throw new ValidationError(`URL exceeds maximum length of ${MAX_URL_LENGTH} characters`);
+    }
+    return url;
+}

package/dist/commands/vet-list.d.ts

@@ -0,0 +1,9 @@
+import type { ScoutState } from '../core/schemas.js';
+import type { VetListResult } from '../core/types.js';
+interface VetListCommandOptions {
+    concurrency?: number;
+    prune?: boolean;
+    state?: ScoutState;
+}
+export declare function runVetList(options: VetListCommandOptions): Promise<VetListResult>;
+export {};

package/dist/commands/vet-list.js

@@ -0,0 +1,16 @@
+import { createScout } from '../scout.js';
+import { requireGitHubToken } from '../core/utils.js';
+import { saveLocalState } from '../core/local-state.js';
+export async function runVetList(options) {
+    const token = requireGitHubToken();
+    const scout = options.state
+        ? await createScout({ githubToken: token, persistence: 'provided', initialState: options.state })
+        : await createScout({ githubToken: token });
+    const result = await scout.vetList({
+        concurrency: options.concurrency,
+        prune: options.prune,
+    });
+    saveLocalState(scout.getState());
+    await scout.checkpoint();
+    return result;
+}

package/dist/commands/vet.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Vet command — vets a specific issue for claimability.
+ */
+import type { ProjectHealth } from '../core/types.js';
+import type { IssueVettingResult, ScoutState } from '../core/schemas.js';
+export interface VetOutput {
+    issue: {
+        repo: string;
+        number: number;
+        title: string;
+        url: string;
+        labels: string[];
+    };
+    recommendation: 'approve' | 'skip' | 'needs_review';
+    reasonsToApprove: string[];
+    reasonsToSkip: string[];
+    projectHealth: ProjectHealth;
+    vettingResult: IssueVettingResult;
+}
+interface VetCommandOptions {
+    issueUrl: string;
+    state?: ScoutState;
+}
+export declare function runVet(options: VetCommandOptions): Promise<VetOutput>;
+export {};

package/dist/commands/vet.js

@@ -0,0 +1,29 @@
+/**
+ * Vet command — vets a specific issue for claimability.
+ */
+import { createScout } from '../scout.js';
+import { requireGitHubToken } from '../core/utils.js';
+import { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
+export async function runVet(options) {
+    validateUrl(options.issueUrl);
+    validateGitHubUrl(options.issueUrl, ISSUE_URL_PATTERN, 'issue');
+    const token = requireGitHubToken();
+    const scout = options.state
+        ? await createScout({ githubToken: token, persistence: 'provided', initialState: options.state })
+        : await createScout({ githubToken: token });
+    const candidate = await scout.vetIssue(options.issueUrl);
+    return {
+        issue: {
+            repo: candidate.issue.repo,
+            number: candidate.issue.number,
+            title: candidate.issue.title,
+            url: candidate.issue.url,
+            labels: candidate.issue.labels,
+        },
+        recommendation: candidate.recommendation,
+        reasonsToApprove: candidate.reasonsToApprove,
+        reasonsToSkip: candidate.reasonsToSkip,
+        projectHealth: candidate.projectHealth,
+        vettingResult: candidate.vettingResult,
+    };
+}

package/dist/core/bootstrap.d.ts

@@ -0,0 +1,14 @@
+/**
+ * First-run bootstrap — fetches starred repos and PR history from GitHub
+ * to seed the scout's state with the user's contribution context.
+ */
+import type { OssScout } from '../scout.js';
+export interface BootstrapResult {
+    starredRepoCount: number;
+    mergedPRCount: number;
+    closedPRCount: number;
+    reposScoredCount: number;
+    skippedDueToRateLimit: boolean;
+    errors: string[];
+}
+export declare function bootstrapScout(scout: OssScout, token: string): Promise<BootstrapResult>;

package/dist/core/bootstrap.js

@@ -0,0 +1,122 @@
+/**
+ * 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';
+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.');
+    }
+    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');
+        return {
+            starredRepoCount: 0,
+            mergedPRCount: 0,
+            closedPRCount: 0,
+            reposScoredCount: 0,
+            skippedDueToRateLimit: true,
+            errors: [],
+        };
+    }
+    const octokit = getOctokit(token);
+    const errors = [];
+    // 1. Fetch starred repos (up to 500)
+    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 (const repo of response.data) {
+                const r = repo;
+                starredRepos.push(r.full_name);
+            }
+            starredPage++;
+            if (starredPage >= STARRED_MAX_PAGES)
+                break;
+        }
+        debug(MODULE, `Fetched ${starredRepos.length} starred repos`);
+        scout.setStarredRepos(starredRepos);
+    }
+    catch (err) {
+        warn(MODULE, `Failed to fetch starred repos: ${errorMessage(err)}`);
+        errors.push('starred repos fetch failed');
+    }
+    // 2. Fetch merged PRs via Search API
+    let mergedPRCount = 0;
+    try {
+        for (let page = 1; page <= SEARCH_MAX_PAGES; page++) {
+            const { data } = await octokit.search.issuesAndPullRequests({
+                q: `is:pr is:merged author:${username}`,
+                per_page: PER_PAGE,
+                page,
+            });
+            for (const item of data.items) {
+                const repoMatch = item.html_url.match(/github\.com\/([^/]+\/[^/]+)\//);
+                if (!repoMatch)
+                    continue;
+                scout.recordMergedPR({
+                    url: item.html_url,
+                    title: item.title,
+                    mergedAt: item.closed_at ?? new Date().toISOString(),
+                    repo: repoMatch[1],
+                });
+                mergedPRCount++;
+            }
+            if (data.items.length < PER_PAGE)
+                break;
+        }
+        debug(MODULE, `Imported ${mergedPRCount} merged PRs`);
+    }
+    catch (err) {
+        warn(MODULE, `Failed to fetch merged PRs: ${errorMessage(err)}`);
+        errors.push('merged PR fetch failed');
+    }
+    // 3. Fetch closed-without-merge PRs via Search API
+    let closedPRCount = 0;
+    try {
+        for (let page = 1; page <= SEARCH_MAX_PAGES; page++) {
+            const { data } = await octokit.search.issuesAndPullRequests({
+                q: `is:pr is:closed is:unmerged author:${username}`,
+                per_page: PER_PAGE,
+                page,
+            });
+            for (const item of data.items) {
+                const repoMatch = item.html_url.match(/github\.com\/([^/]+\/[^/]+)\//);
+                if (!repoMatch)
+                    continue;
+                scout.recordClosedPR({
+                    url: item.html_url,
+                    title: item.title,
+                    closedAt: item.closed_at ?? new Date().toISOString(),
+                    repo: repoMatch[1],
+                });
+                closedPRCount++;
+            }
+            if (data.items.length < PER_PAGE)
+                break;
+        }
+        debug(MODULE, `Imported ${closedPRCount} closed PRs`);
+    }
+    catch (err) {
+        warn(MODULE, `Failed to fetch closed PRs: ${errorMessage(err)}`);
+        errors.push('closed PR fetch failed');
+    }
+    const state = scout.getState();
+    const reposScoredCount = Object.keys(state.repoScores).length;
+    return {
+        starredRepoCount: starredRepos.length,
+        mergedPRCount,
+        closedPRCount,
+        reposScoredCount,
+        skippedDueToRateLimit: false,
+        errors,
+    };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Category Mapping — static mappings from project categories to GitHub topics and organizations.
+ *
+ * Used by issue discovery to prioritize repos matching user's category preferences.
+ */
+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. */
+export declare const CATEGORY_ORGS: Record<ProjectCategory, string[]>;
+/**
+ * Check if a repo belongs to any of the given categories based on its owner matching a category org.
+ * Comparison is case-insensitive.
+ */
+export declare function repoBelongsToCategory(repoFullName: string, categories: ProjectCategory[]): boolean;
+/**
+ * Get deduplicated GitHub topics for the given categories, for use in `topic:` search queries.
+ */
+export declare function getTopicsForCategories(categories: ProjectCategory[]): string[];

package/dist/core/category-mapping.js

@@ -0,0 +1,58 @@
+/**
+ * Category Mapping — static mappings from project categories to GitHub topics and organizations.
+ *
+ * Used by issue discovery to prioritize repos matching user's category preferences.
+ */
+/** 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'],
+};
+/** 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'],
+};
+/**
+ * Check if a repo belongs to any of the given categories based on its owner matching a category org.
+ * Comparison is case-insensitive.
+ */
+export function repoBelongsToCategory(repoFullName, categories) {
+    if (categories.length === 0)
+        return false;
+    const owner = repoFullName.split('/')[0]?.toLowerCase();
+    if (!owner)
+        return false;
+    for (const category of categories) {
+        const orgs = CATEGORY_ORGS[category];
+        if (!orgs)
+            continue; // Guard against invalid categories from untrusted input
+        if (orgs.some((org) => org.toLowerCase() === owner)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get deduplicated GitHub topics for the given categories, for use in `topic:` search queries.
+ */
+export function getTopicsForCategories(categories) {
+    const topics = new Set();
+    for (const category of categories) {
+        const categoryTopics = CATEGORY_TOPICS[category];
+        if (!categoryTopics)
+            continue; // Guard against invalid categories from untrusted input
+        for (const topic of categoryTopics) {
+            topics.add(topic);
+        }
+    }
+    return [...topics];
+}

package/dist/core/concurrency.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs a worker pool that processes items with bounded concurrency.
+ * N workers consume from a shared index. On any worker error, remaining
+ * workers are aborted via a shared flag and the error is propagated.
+ */
+export declare function runWorkerPool<T>(items: T[], worker: (item: T) => Promise<void>, concurrency: number): Promise<void>;

package/dist/core/concurrency.js

@@ -0,0 +1,25 @@
+/**
+ * Runs a worker pool that processes items with bounded concurrency.
+ * N workers consume from a shared index. On any worker error, remaining
+ * workers are aborted via a shared flag and the error is propagated.
+ */
+export async function runWorkerPool(items, worker, concurrency) {
+    let index = 0;
+    let aborted = false;
+    const poolWorker = async () => {
+        while (index < items.length) {
+            if (aborted)
+                break;
+            const item = items[index++];
+            try {
+                await worker(item);
+            }
+            catch (err) {
+                aborted = true;
+                throw err;
+            }
+        }
+    };
+    const workerCount = Math.min(concurrency, items.length);
+    await Promise.all(Array.from({ length: workerCount }, () => poolWorker()));
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Custom error type hierarchy for oss-scout.
+ */
+export declare class OssScoutError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class ConfigurationError extends OssScoutError {
+    constructor(message: string);
+}
+export declare class ValidationError extends OssScoutError {
+    constructor(message: string);
+}
+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';
+/**
+ * Map an unknown error to a structured ErrorCode for JSON output.
+ */
+export declare function resolveErrorCode(err: unknown): ErrorCode;

package/dist/core/errors.js

@@ -0,0 +1,69 @@
+/**
+ * Custom error type hierarchy for oss-scout.
+ */
+export class OssScoutError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'OssScoutError';
+    }
+}
+export class ConfigurationError extends OssScoutError {
+    constructor(message) {
+        super(message, 'CONFIGURATION_ERROR');
+        this.name = 'ConfigurationError';
+    }
+}
+export class ValidationError extends OssScoutError {
+    constructor(message) {
+        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) {
+        const status = error.status;
+        return typeof status === 'number' && Number.isFinite(status) ? status : undefined;
+    }
+    return undefined;
+}
+export function isRateLimitError(error) {
+    const status = getHttpStatusCode(error);
+    if (status === 429)
+        return true;
+    if (status === 403) {
+        const msg = errorMessage(error).toLowerCase();
+        return msg.includes('rate limit');
+    }
+    return false;
+}
+/**
+ * Map an unknown error to a structured ErrorCode for JSON output.
+ */
+export function resolveErrorCode(err) {
+    if (err instanceof ConfigurationError)
+        return 'CONFIGURATION';
+    if (err instanceof ValidationError)
+        return 'VALIDATION';
+    const status = getHttpStatusCode(err);
+    if (status === 401)
+        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 (status === 404)
+        return 'NOT_FOUND';
+    if (status === 429)
+        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';
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Gist-backed state persistence for oss-scout.
+ *
+ * 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';
+/** Minimal Octokit interface for gist operations — keeps the class testable. */
+export interface GistOctokitLike {
+    gists: {
+        get(params: {
+            gist_id: string;
+        }): Promise<{
+            data: {
+                id: string;
+                files: Record<string, {
+                    content?: string;
+                } | undefined> | null;
+            };
+        }>;
+        create(params: {
+            description: string;
+            public: boolean;
+            files: Record<string, {
+                content: string;
+            }>;
+        }): Promise<{
+            data: {
+                id: string;
+            };
+        }>;
+        update(params: {
+            gist_id: string;
+            files: Record<string, {
+                content: string;
+            }>;
+        }): Promise<{
+            data: {
+                id: string;
+            };
+        }>;
+        list(params: {
+            per_page: number;
+            page: number;
+        }): Promise<{
+            data: Array<{
+                id: string;
+                description: string | null;
+            }>;
+        }>;
+    };
+}
+export interface BootstrapResult {
+    gistId: string;
+    state: ScoutState;
+    created: boolean;
+    degraded?: boolean;
+}
+export declare class GistStateStore {
+    private octokit;
+    private gistId;
+    constructor(octokit: GistOctokitLike);
+    /**
+     * Bootstrap: find an existing gist or create a new one.
+     * Falls back to local cache if the API is unavailable.
+     */
+    bootstrap(): Promise<BootstrapResult>;
+    /**
+     * Push state to the gist. Also writes to local cache as fallback.
+     */
+    push(state: ScoutState): Promise<boolean>;
+    /**
+     * Pull state from the gist and merge with local state.
+     */
+    pull(): Promise<ScoutState | null>;
+    /** Get the current gist ID (if known). */
+    getGistId(): string | null;
+    private bootstrapFromApi;
+    private bootstrapFromCache;
+    private fetchGistState;
+    private searchForGist;
+    private createGist;
+    private readCachedGistId;
+    private saveGistId;
+    private readCache;
+    private writeCache;
+}
+/**
+ * Merge two ScoutState objects with conflict resolution:
+ * - repoScores: per-repo, keep the one with more total PR activity
+ * - mergedPRs/closedPRs: union by URL
+ * - preferences: remote wins
+ * - starredRepos: keep the list with the fresher timestamp
+ * - savedResults: union by issueUrl, keep newer lastSeenAt
+ */
+export declare function mergeStates(local: ScoutState, remote: ScoutState): ScoutState;