@oss-scout/core 0.11.0 → 1.0.0

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 { ScoutStateReader, ScoutStateWriter, SLMConfig } from "./core/issue-vetting.js";
 import { type FeatureSearchResult } from "./core/feature-discovery.js";
 import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate, SkippedIssue, Horizon } from "./core/schemas.js";
-import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, OpenPRRecord, RepoScoreUpdate, ProjectCategory, VetListOptions, VetListResult } from "./core/types.js";
+import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, OpenPRRecord, RepoScoreUpdate, ProjectCategory, SyncResult, VetListOptions, VetListResult } from "./core/types.js";
 import { GistStateStore } from "./core/gist-state-store.js";
 /**
  * Create an OssScout instance.
@@ -37,17 +37,43 @@ export declare function createScout(config: ScoutConfig): Promise<OssScout>;
  * Implements ScoutStateReader so the search engine can read state
  * without knowing about the persistence layer.
  */
-export declare class OssScout implements ScoutStateReader {
+export declare class OssScout implements ScoutStateReader, ScoutStateWriter {
     private githubToken;
     private gistStore;
     private state;
     private dirty;
-    constructor(githubToken: string, initialState: ScoutState, gistStore?: GistStateStore | null);
+    /** When true, checkpoint() also writes ~/.oss-scout/state.json. */
+    private persistLocal;
+    constructor(githubToken: string, initialState: ScoutState, gistStore?: GistStateStore | null, opts?: {
+        persistLocal?: boolean;
+    });
+    /**
+     * Drop stale disk-cache entries. Called at the top of every cache-burning
+     * entry point (search, features, vetList); without it ~/.oss-scout/cache
+     * grows without bound. evictStale never throws (fs errors degrade to warn).
+     */
+    private evictStaleCacheEntries;
     /**
      * Multi-strategy issue search. Returns scored, sorted candidates.
      * Automatically culls expired skip entries and filters skipped issues.
      */
     search(options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Populate the `hasActiveMaintainers` repo-score signal from a freshly
+     * computed projectHealth (#167). It was initialized false and never set, so
+     * calculateScore's +1 active-maintainers weight was inert; `isActive`
+     * (recent commit activity) is a real, already-computed proxy.
+     *
+     * `isResponsive` and `avgResponseDays` are deliberately NOT set here:
+     * `projectHealth.avgIssueResponseDays` is a hardcoded `0` placeholder
+     * (repo-health.ts), so deriving responsiveness from it would award +1 to
+     * every repo — a fake signal worse than the inert one. Real responsiveness
+     * needs an actual response-time measurement (extra API calls), deferred.
+     * `hasHostileComments` likewise stays a host-settable capability (it needs
+     * comment sentiment, out of scope). A failed health check is skipped so its
+     * neutral-default fields don't pollute the score.
+     */
+    private updateRepoSignalsFromHealth;
     /**
      * Vet a single issue URL for claimability.
      */
@@ -83,15 +109,21 @@ export declare class OssScout implements ScoutStateReader {
     getReposWithOpenPRs(): string[];
     getStarredRepos(): string[];
     getProjectCategories(): ProjectCategory[];
+    /** Configured GitHub username (used to classify own vs competing PRs, #166). */
+    getGitHubUsername(): string;
     getRepoScore(repo: string): number | null;
     /**
-     * Optional SLM pre-triage config read from preferences (oss-autopilot#1122).
-     * Empty `model` disables the call; the vetter treats it as a no-op.
+     * Number of the user's PRs closed without merge in this repo (#125).
+     * Prefers the tracked repo score; falls back to counting closedPRs so the
+     * scoring penalty works even before a score record exists.
+     */
+    getClosedWithoutMergeCount(repo: string): number;
+    /**
+     * SLM pre-triage config read from preferences (oss-autopilot#1122). Returns
+     * `null` when no `slmTriageModel` is configured — the vetter skips the SLM
+     * call entirely (#158).
      */
-    getSLMTriageConfig(): {
-        model: string;
-        host: string;
-    };
+    getSLMTriageConfig(): SLMConfig | null;
     /** Get current preferences (read-only). */
     getPreferences(): Readonly<ScoutPreferences>;
     /** Get repo score record for a specific repository. */
@@ -110,6 +142,17 @@ export declare class OssScout implements ScoutStateReader {
      * Open PRs signal active engagement even when nothing is merged yet.
      */
     recordOpenPR(pr: OpenPRRecord): void;
+    /**
+     * Reconcile tracked open PRs against their current GitHub state (#164).
+     *
+     * `state.openPRs` was append-only — nothing transitioned an open PR to
+     * merged/closed, so getReposWithOpenPRs() over-reported forever once a PR
+     * merged. This checks each open PR, records merges/closures (which updates
+     * the repo score), prunes resolved entries, and checkpoints. Cheaper than a
+     * full bootstrap, so a host can call it on daily startup. Transient errors
+     * leave the entry in place; auth/rate-limit failures propagate.
+     */
+    syncOpenPRs(): Promise<SyncResult>;
     /**
      * Update repo score with observed signals.
      */
@@ -138,6 +181,12 @@ export declare class OssScout implements ScoutStateReader {
      * Clear all saved results.
      */
     clearResults(): void;
+    /**
+     * Record deletion tombstones (#117) so a later gist merge does not
+     * resurrect these URLs from another machine's copy. A re-add with a newer
+     * timestamp overrides the tombstone in mergeStates.
+     */
+    private addTombstones;
     /**
      * Skip an issue — excludes it from future searches. Auto-culled after 90 days.
      */

package/dist/scout.js

@@ -7,13 +7,13 @@
 import { IssueDiscovery } from "./core/issue-discovery.js";
 import { IssueVetter } from "./core/issue-vetting.js";
 import { discoverFeatures, discoverFeaturesBroad, } from "./core/feature-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";
-import { errorMessage, getHttpStatusCode, isRateLimitError, } from "./core/errors.js";
+import { loadLocalState, saveLocalState } from "./core/local-state.js";
+import { warn, setLogLevel } from "./core/logger.js";
+import { extractRepoFromUrl, parseGitHubUrl } from "./core/utils.js";
+import { errorMessage, getHttpStatusCode, isRateLimitError, rethrowIfFatal, } from "./core/errors.js";
+import { getHttpCache } from "./core/http-cache.js";
 /** Cause-specific user-facing message for degraded (offline) mode. */
 function offlineModeMessage(reason) {
     const tail = "Changes will only be saved locally.";
@@ -93,8 +93,13 @@ function toGistOctokit(octokit) {
  * ```
  */
 export async function createScout(config) {
+    // Apply the host's log-level preference before any bootstrap chatter (#156).
+    if (config.logLevel !== undefined) {
+        setLogLevel(config.logLevel);
+    }
     let state;
     let gistStore = null;
+    let persistLocal = false;
     if (config.persistence === "provided") {
         state = config.initialState;
     }
@@ -114,9 +119,15 @@ export async function createScout(config) {
         }
     }
     else {
-        state = ScoutStateSchema.parse({ version: 1 });
-    }
-    return new OssScout(config.githubToken, state, gistStore);
+        // Default: local-file persistence. The previous else-branch silently
+        // created throwaway in-memory state, so a documented standalone scout
+        // (and the MCP server) read no preferences and persisted nothing while
+        // checkpoint() reported success (#116). Load the real state and save it
+        // on checkpoint.
+        state = loadLocalState();
+        persistLocal = true;
+    }
+    return new OssScout(config.githubToken, state, gistStore, { persistLocal });
 }
 /**
  * Main oss-scout class. Provides search, vetting, and state management.
@@ -129,29 +140,57 @@ export class OssScout {
     gistStore;
     state;
     dirty = false;
-    constructor(githubToken, initialState, gistStore = null) {
+    /** When true, checkpoint() also writes ~/.oss-scout/state.json. */
+    persistLocal;
+    constructor(githubToken, initialState, gistStore = null, opts = {}) {
         this.githubToken = githubToken;
         this.gistStore = gistStore;
         this.state = initialState;
+        this.persistLocal = opts.persistLocal ?? false;
     }
     // ── Search ──────────────────────────────────────────────────────────
+    /**
+     * Drop stale disk-cache entries. Called at the top of every cache-burning
+     * entry point (search, features, vetList); without it ~/.oss-scout/cache
+     * grows without bound. evictStale never throws (fs errors degrade to warn).
+     */
+    evictStaleCacheEntries() {
+        getHttpCache().evictStale();
+    }
     /**
      * Multi-strategy issue search. Returns scored, sorted candidates.
      * Automatically culls expired skip entries and filters skipped issues.
      */
     async search(options) {
+        this.evictStaleCacheEntries();
         // 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);
+        // Per-call flags override the persisted personalization defaults (#168).
+        // An empty preference array reads as "no boost" just like an absent flag.
+        const prefs = this.state.preferences;
+        const prefLangs = prefs.preferLanguages ?? [];
+        const prefRepos = prefs.preferRepos ?? [];
+        const preferLanguages = options?.preferLanguages ??
+            (prefLangs.length > 0 ? prefLangs : undefined);
+        const preferRepos = options?.preferRepos ?? (prefRepos.length > 0 ? prefRepos : undefined);
+        const diversityRatio = options?.diversityRatio ?? prefs.diversityRatio ?? 0;
         const { candidates, strategiesUsed } = await discovery.searchIssues({
             maxResults: options?.maxResults,
             strategies: options?.strategies,
             skippedUrls,
-            preferLanguages: options?.preferLanguages,
-            preferRepos: options?.preferRepos,
-            diversityRatio: options?.diversityRatio,
+            preferLanguages,
+            preferRepos,
+            diversityRatio,
+            interPhaseDelayMs: options?.interPhaseDelayMs,
+            broadPhaseDelayMs: options?.broadPhaseDelayMs,
         });
+        // Feed the freshly observed maintainer-responsiveness signals back into the
+        // repo scores so the next search ranks responsive/active repos higher (#167).
+        for (const c of candidates) {
+            this.updateRepoSignalsFromHealth(c.projectHealth);
+        }
         this.state.lastSearchAt = new Date().toISOString();
         this.dirty = true;
         return {
@@ -162,6 +201,28 @@ export class OssScout {
             strategiesUsed,
         };
     }
+    /**
+     * Populate the `hasActiveMaintainers` repo-score signal from a freshly
+     * computed projectHealth (#167). It was initialized false and never set, so
+     * calculateScore's +1 active-maintainers weight was inert; `isActive`
+     * (recent commit activity) is a real, already-computed proxy.
+     *
+     * `isResponsive` and `avgResponseDays` are deliberately NOT set here:
+     * `projectHealth.avgIssueResponseDays` is a hardcoded `0` placeholder
+     * (repo-health.ts), so deriving responsiveness from it would award +1 to
+     * every repo — a fake signal worse than the inert one. Real responsiveness
+     * needs an actual response-time measurement (extra API calls), deferred.
+     * `hasHostileComments` likewise stays a host-settable capability (it needs
+     * comment sentiment, out of scope). A failed health check is skipped so its
+     * neutral-default fields don't pollute the score.
+     */
+    updateRepoSignalsFromHealth(health) {
+        if (health.checkFailed)
+            return;
+        this.updateRepoScore(health.repo, {
+            signals: { hasActiveMaintainers: health.isActive },
+        });
+    }
     /**
      * Vet a single issue URL for claimability.
      */
@@ -184,6 +245,7 @@ export class OssScout {
      * preferences and excluded repos/orgs.
      */
     async features(options) {
+        this.evictStaleCacheEntries();
         const count = options?.count ?? 10;
         const octokit = getOctokit(this.githubToken);
         const vetter = new IssueVetter(octokit, this);
@@ -218,6 +280,7 @@ export class OssScout {
      * Optionally prunes unavailable issues from saved results.
      */
     async vetList(options) {
+        this.evictStaleCacheEntries();
         const saved = this.getSavedResults();
         const concurrency = options?.concurrency ?? 5;
         const results = [];
@@ -239,6 +302,7 @@ export class OssScout {
                     number: item.number,
                     title: item.title,
                     status: this.classifyVetResult(candidate),
+                    ok: true,
                     recommendation: candidate.recommendation,
                     viabilityScore: candidate.viabilityScore,
                 });
@@ -256,6 +320,7 @@ export class OssScout {
                     number: item.number,
                     title: item.title,
                     status: isGone ? "closed" : "error",
+                    ok: false,
                     errorMessage: errorMessage(error),
                 });
             })
@@ -283,6 +348,33 @@ export class OssScout {
             hasPR: results.filter((r) => r.status === "has_pr").length,
             errors: results.filter((r) => r.status === "error").length,
         };
+        // Claim-watch (#165): compare each result's current status to the status
+        // recorded on the saved result last time, then persist the new status so
+        // the next run can diff again. "error" is transient — never a transition
+        // target and never stored.
+        const prevStatus = new Map((this.state.savedResults ?? []).map((r) => [r.issueUrl, r.lastStatus]));
+        const transitions = results
+            .filter((r) => r.status !== "error")
+            .filter((r) => {
+            const prev = prevStatus.get(r.issueUrl);
+            return prev !== undefined && prev !== r.status;
+        })
+            .map((r) => ({
+            issueUrl: r.issueUrl,
+            repo: r.repo,
+            number: r.number,
+            from: prevStatus.get(r.issueUrl),
+            to: r.status,
+        }));
+        const currentStatus = new Map(results.map((r) => [r.issueUrl, r.status]));
+        for (const saved of this.state.savedResults ?? []) {
+            const status = currentStatus.get(saved.issueUrl);
+            if (status !== undefined && status !== "error") {
+                saved.lastStatus = status;
+            }
+        }
+        if (results.length > 0)
+            this.dirty = true;
         let prunedCount;
         if (options?.prune) {
             const unavailableUrls = new Set(results
@@ -291,11 +383,18 @@ export class OssScout {
             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);
+            if (prunedCount > 0)
+                this.addTombstones([...unavailableUrls]);
             this.dirty = true;
         }
-        return { results, summary, prunedCount };
+        return { results, summary, prunedCount, transitions };
     }
     classifyVetResult(candidate) {
+        // Closed wins over everything: GitHub returns 200 for closed issues, so
+        // the 404/410 catch path alone never saw them (#120). Candidates cached
+        // by older versions lack issueState and read as open.
+        if (candidate.issueState === "closed")
+            return "closed";
         const checks = candidate.vettingResult.checks;
         if (!checks.noExistingPR)
             return "has_pr";
@@ -335,19 +434,35 @@ export class OssScout {
     getProjectCategories() {
         return this.state.preferences.projectCategories;
     }
+    /** Configured GitHub username (used to classify own vs competing PRs, #166). */
+    getGitHubUsername() {
+        return this.state.preferences.githubUsername;
+    }
     getRepoScore(repo) {
         const score = this.state.repoScores[repo];
         return score ? score.score : null;
     }
     /**
-     * Optional SLM pre-triage config read from preferences (oss-autopilot#1122).
-     * Empty `model` disables the call; the vetter treats it as a no-op.
+     * Number of the user's PRs closed without merge in this repo (#125).
+     * Prefers the tracked repo score; falls back to counting closedPRs so the
+     * scoring penalty works even before a score record exists.
+     */
+    getClosedWithoutMergeCount(repo) {
+        const score = this.state.repoScores[repo];
+        if (score)
+            return score.closedWithoutMergeCount;
+        return (this.state.closedPRs ?? []).filter((p) => extractRepoFromUrl(p.url) === repo).length;
+    }
+    /**
+     * SLM pre-triage config read from preferences (oss-autopilot#1122). Returns
+     * `null` when no `slmTriageModel` is configured — the vetter skips the SLM
+     * call entirely (#158).
      */
     getSLMTriageConfig() {
-        return {
-            model: this.state.preferences.slmTriageModel ?? "",
-            host: this.state.preferences.slmTriageHost ?? "",
-        };
+        const model = this.state.preferences.slmTriageModel ?? "";
+        if (!model)
+            return null;
+        return { model, host: this.state.preferences.slmTriageHost ?? "" };
     }
     /** Get current preferences (read-only). */
     getPreferences() {
@@ -402,6 +517,78 @@ export class OssScout {
         ];
         this.dirty = true;
     }
+    /**
+     * Reconcile tracked open PRs against their current GitHub state (#164).
+     *
+     * `state.openPRs` was append-only — nothing transitioned an open PR to
+     * merged/closed, so getReposWithOpenPRs() over-reported forever once a PR
+     * merged. This checks each open PR, records merges/closures (which updates
+     * the repo score), prunes resolved entries, and checkpoints. Cheaper than a
+     * full bootstrap, so a host can call it on daily startup. Transient errors
+     * leave the entry in place; auth/rate-limit failures propagate.
+     */
+    async syncOpenPRs() {
+        const octokit = getOctokit(this.githubToken);
+        const open = this.state.openPRs ?? [];
+        const result = {
+            checked: open.length,
+            merged: 0,
+            closed: 0,
+            stillOpen: 0,
+            errors: 0,
+        };
+        const remaining = [];
+        for (const pr of open) {
+            const parsed = parseGitHubUrl(pr.url);
+            if (!parsed || parsed.type !== "pull") {
+                remaining.push(pr);
+                result.errors++;
+                continue;
+            }
+            const repoFullName = `${parsed.owner}/${parsed.repo}`;
+            try {
+                const { data } = await octokit.pulls.get({
+                    owner: parsed.owner,
+                    repo: parsed.repo,
+                    pull_number: parsed.number,
+                });
+                if (data.merged) {
+                    this.recordMergedPR({
+                        url: pr.url,
+                        title: pr.title,
+                        mergedAt: data.merged_at ?? new Date().toISOString(),
+                        repo: repoFullName,
+                    });
+                    result.merged++;
+                }
+                else if (data.state === "closed") {
+                    this.recordClosedPR({
+                        url: pr.url,
+                        title: pr.title,
+                        closedAt: data.closed_at ?? new Date().toISOString(),
+                        repo: repoFullName,
+                    });
+                    result.closed++;
+                }
+                else {
+                    remaining.push(pr);
+                    result.stillOpen++;
+                }
+            }
+            catch (err) {
+                // Auth/rate-limit aborts the whole sync; a transient/404 leaves the
+                // entry untouched so a later sync can retry rather than losing it.
+                rethrowIfFatal(err);
+                warn("scout", `sync: could not check ${pr.url}: ${errorMessage(err)}`);
+                remaining.push(pr);
+                result.errors++;
+            }
+        }
+        this.state.openPRs = remaining;
+        this.dirty = true;
+        await this.checkpoint();
+        return result;
+    }
     /**
      * Update repo score with observed signals.
      */
@@ -437,6 +624,9 @@ export class OssScout {
      */
     updatePreferences(updates) {
         this.state.preferences = { ...this.state.preferences, ...updates };
+        // Stamp so the gist merge keeps the fresher preferences instead of
+        // always taking the remote copy (#117).
+        this.state.preferencesUpdatedAt = new Date().toISOString();
         this.dirty = true;
     }
     /**
@@ -486,9 +676,25 @@ export class OssScout {
      * Clear all saved results.
      */
     clearResults() {
+        this.addTombstones((this.state.savedResults ?? []).map((r) => r.issueUrl));
         this.state.savedResults = [];
         this.dirty = true;
     }
+    /**
+     * Record deletion tombstones (#117) so a later gist merge does not
+     * resurrect these URLs from another machine's copy. A re-add with a newer
+     * timestamp overrides the tombstone in mergeStates.
+     */
+    addTombstones(urls) {
+        if (urls.length === 0)
+            return;
+        const removedAt = new Date().toISOString();
+        const existing = this.state.tombstones ?? [];
+        const byUrl = new Map(existing.map((t) => [t.url, t]));
+        for (const url of urls)
+            byUrl.set(url, { url, removedAt });
+        this.state.tombstones = [...byUrl.values()];
+    }
     // ── Skip List ───────────────────────────────────────────────────────
     /**
      * Skip an issue — excludes it from future searches. Auto-culled after 90 days.
@@ -507,7 +713,10 @@ export class OssScout {
                 skippedAt: new Date().toISOString(),
             },
         ];
-        // Also remove from saved results if present
+        // Also remove from saved results if present. No tombstone needed: the
+        // skip entry itself is the durable record, and mergeStates reconciles
+        // saved results against the skip list so a merge can't resurrect a
+        // skipped URL into the saved list (#117).
         if (this.state.savedResults) {
             this.state.savedResults = this.state.savedResults.filter((r) => r.issueUrl !== url);
         }
@@ -523,13 +732,17 @@ export class OssScout {
      * Remove a specific issue from the skip list.
      */
     unskipIssue(url) {
+        const before = (this.state.skippedIssues ?? []).length;
         this.state.skippedIssues = (this.state.skippedIssues ?? []).filter((s) => s.url !== url);
+        if (this.state.skippedIssues.length < before)
+            this.addTombstones([url]);
         this.dirty = true;
     }
     /**
      * Clear all skipped issues.
      */
     clearSkippedIssues() {
+        this.addTombstones((this.state.skippedIssues ?? []).map((s) => s.url));
         this.state.skippedIssues = [];
         this.dirty = true;
     }
@@ -573,6 +786,17 @@ export class OssScout {
             if (!ok)
                 return false;
         }
+        if (this.persistLocal) {
+            // Honest persistence: in local mode the previous no-op return true
+            // claimed success while saving nothing (#116). A failed write keeps
+            // the dirty flag and reports failure.
+            try {
+                saveLocalState(this.state);
+            }
+            catch {
+                return false;
+            }
+        }
         this.dirty = false;
         return true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.11.0",
+  "version": "1.0.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": {