@oss-autopilot/core 0.44.3 → 0.44.15

package/dist/core/state.d.ts

@@ -2,7 +2,7 @@
  * State management for the OSS Contribution Agent
  * Persists state to a JSON file in ~/.oss-autopilot/
  */
-import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, StateEvent, StateEventType, DailyDigest, LocalRepoCache, SnoozeInfo } from './types.js';
+import { AgentState, TrackedIssue, RepoScore, RepoScoreUpdate, StateEvent, StateEventType, DailyDigest, LocalRepoCache, SnoozeInfo, StatusOverride, FetchedPRStatus } from './types.js';
 /**
  * Acquire an advisory file lock using exclusive-create (`wx` flag).
  * If the lock file already exists but is stale (older than LOCK_TIMEOUT_MS or corrupt),
@@ -257,6 +257,27 @@ export declare class StateManager {
      * @returns Array of PR URLs whose snoozes were expired.
      */
     expireSnoozes(): string[];
+    /**
+     * Set a manual status override for a PR.
+     * @param url - The full GitHub PR URL.
+     * @param status - The target status to override to.
+     * @param lastActivityAt - The PR's current updatedAt timestamp (for auto-clear detection).
+     */
+    setStatusOverride(url: string, status: FetchedPRStatus, lastActivityAt: string): void;
+    /**
+     * Clear a status override for a PR.
+     * @param url - The full GitHub PR URL.
+     * @returns true if found and removed, false if no override existed.
+     */
+    clearStatusOverride(url: string): boolean;
+    /**
+     * Get the status override for a PR, if one exists and hasn't been auto-cleared.
+     * @param url - The full GitHub PR URL.
+     * @param currentUpdatedAt - The PR's current updatedAt from GitHub. If newer than
+     *   the stored lastActivityAt, the override is stale and auto-cleared.
+     * @returns The override metadata, or undefined if none exists or it was auto-cleared.
+     */
+    getStatusOverride(url: string, currentUpdatedAt?: string): StatusOverride | undefined;
     /**
      * Get the score record for a repository.
      * @param repo - Repository in "owner/repo" format.

package/dist/core/state.js

@@ -4,7 +4,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { INITIAL_STATE, } from './types.js';
+import { INITIAL_STATE, isBelowMinStars, } from './types.js';
 import { getStatePath, getBackupDir, getDataDir } from './utils.js';
 import { ValidationError, errorMessage } from './errors.js';
 import { debug, warn } from './logger.js';
@@ -843,6 +843,53 @@ export class StateManager {
         }
         return expired;
     }
+    // === Status Overrides ===
+    /**
+     * Set a manual status override for a PR.
+     * @param url - The full GitHub PR URL.
+     * @param status - The target status to override to.
+     * @param lastActivityAt - The PR's current updatedAt timestamp (for auto-clear detection).
+     */
+    setStatusOverride(url, status, lastActivityAt) {
+        if (!this.state.config.statusOverrides) {
+            this.state.config.statusOverrides = {};
+        }
+        this.state.config.statusOverrides[url] = {
+            status,
+            setAt: new Date().toISOString(),
+            lastActivityAt,
+        };
+    }
+    /**
+     * Clear a status override for a PR.
+     * @param url - The full GitHub PR URL.
+     * @returns true if found and removed, false if no override existed.
+     */
+    clearStatusOverride(url) {
+        if (!this.state.config.statusOverrides || !(url in this.state.config.statusOverrides)) {
+            return false;
+        }
+        delete this.state.config.statusOverrides[url];
+        return true;
+    }
+    /**
+     * Get the status override for a PR, if one exists and hasn't been auto-cleared.
+     * @param url - The full GitHub PR URL.
+     * @param currentUpdatedAt - The PR's current updatedAt from GitHub. If newer than
+     *   the stored lastActivityAt, the override is stale and auto-cleared.
+     * @returns The override metadata, or undefined if none exists or it was auto-cleared.
+     */
+    getStatusOverride(url, currentUpdatedAt) {
+        const override = this.state.config.statusOverrides?.[url];
+        if (!override)
+            return undefined;
+        // Auto-clear if the PR has new activity since the override was set
+        if (currentUpdatedAt && currentUpdatedAt > override.lastActivityAt) {
+            this.clearStatusOverride(url);
+            return undefined;
+        }
+        return override;
+    }
     // === Repository Scoring ===
     /**
      * Get the score record for a repository.
@@ -1060,6 +1107,8 @@ export class StateManager {
         for (const [repoKey, score] of Object.entries(this.state.repoScores)) {
             if (this.isExcluded(repoKey))
                 continue;
+            if (isBelowMinStars(score.stargazersCount, this.state.config.minStars ?? 50))
+                continue;
             totalTracked++;
             totalMerged += score.mergedPRCount;
             totalClosed += score.closedWithoutMergeCount;

package/dist/core/test-utils.js

@@ -17,9 +17,11 @@ export function makeFetchedPR(overrides = {}) {
         repo,
         number,
         title: 'Test PR',
-        status: 'healthy',
-        displayLabel: '[Healthy]',
-        displayDescription: 'Everything looks good',
+        status: 'waiting_on_maintainer',
+        waitReason: 'pending_review',
+        stalenessTier: 'active',
+        displayLabel: '[Waiting on Maintainer]',
+        displayDescription: 'Awaiting review',
         createdAt: '2025-06-01T00:00:00Z',
         updatedAt: '2025-06-15T00:00:00Z',
         daysSinceActivity: 2,
@@ -41,20 +43,8 @@ export function makeDailyDigest(overrides = {}) {
     return {
         generatedAt: '2025-06-20T00:00:00Z',
         openPRs: [],
-        prsNeedingResponse: [],
-        ciFailingPRs: [],
-        ciBlockedPRs: [],
-        ciNotRunningPRs: [],
-        mergeConflictPRs: [],
-        needsRebasePRs: [],
-        missingRequiredFilesPRs: [],
-        incompleteChecklistPRs: [],
-        needsChangesPRs: [],
-        changesAddressedPRs: [],
+        needsAddressingPRs: [],
         waitingOnMaintainerPRs: [],
-        approachingDormant: [],
-        dormantPRs: [],
-        healthyPRs: [],
         recentlyClosedPRs: [],
         recentlyMergedPRs: [],
         shelvedPRs: [],

package/dist/core/types.d.ts

@@ -52,37 +52,35 @@ export interface DetermineStatusInput {
     dormantThreshold: number;
     approachingThreshold: number;
     latestCommitDate?: string;
+    /** GitHub login of the HEAD commit's author (from `repos.getCommit`). */
+    latestCommitAuthor?: string;
+    /** GitHub login of the PR contributor (configured username). */
+    contributorUsername?: string;
     lastMaintainerCommentDate?: string;
     latestChangesRequestedDate?: string;
     /** True if at least one failing CI check is classified as 'actionable'. */
     hasActionableCIFailure?: boolean;
 }
 /**
- * Computed status for a {@link FetchedPR}, determined by `PRMonitor.determineStatus()`.
- * Statuses are checked in priority order — the first match wins.
- *
- * **Action required (contributor must act):**
- * - `needs_response` — Maintainer commented after the contributor's last activity
- * - `needs_changes` — Reviewer requested changes (via review, not just a comment)
- * - `failing_ci` — One or more CI checks are failing (at least one is actionable)
- * - `ci_not_running` — No CI checks have been triggered *(reserved)*
- * - `merge_conflict` — PR has merge conflicts with the base branch
- * - `needs_rebase` — PR branch is significantly behind upstream *(reserved)*
- * - `missing_required_files` — Required files like changesets or CLA are missing *(reserved)*
- * - `incomplete_checklist` — PR body has unchecked required checkboxes
- *
- * **Waiting (no action needed right now):**
- * - `ci_blocked` — All failing CI checks are non-actionable (infrastructure, fork limitation, auth gate)
- * - `changes_addressed` — Contributor pushed commits after reviewer feedback; awaiting re-review
- * - `waiting` — CI is pending or no specific action needed
- * - `waiting_on_maintainer` — PR is approved and CI passes; waiting for maintainer to merge
- * - `healthy` — Everything looks good; normal review cycle
+ * Granular reason why a PR needs addressing (contributor's turn).
+ * Active values (produced by determineStatus): needs_response, needs_changes,
+ * failing_ci, merge_conflict, incomplete_checklist.
+ * Reserved (display mappings exist but detection not yet wired): ci_not_running,
+ * needs_rebase, missing_required_files.
+ */
+export type ActionReason = 'needs_response' | 'needs_changes' | 'failing_ci' | 'merge_conflict' | 'incomplete_checklist' | 'ci_not_running' | 'needs_rebase' | 'missing_required_files';
+/** Granular reason why a PR is waiting on the maintainer. */
+export type WaitReason = 'pending_review' | 'pending_merge' | 'changes_addressed' | 'ci_blocked';
+/** How stale is the PR based on days since activity. Orthogonal to status. */
+export type StalenessTier = 'active' | 'approaching_dormant' | 'dormant';
+/**
+ * Top-level classification of a PR's state. Only two values:
+ * - `needs_addressing` — Contributor's turn. See `actionReason` for what to do.
+ * - `waiting_on_maintainer` — Maintainer's turn. See `waitReason` for why.
  *
- * **Staleness warnings:**
- * - `approaching_dormant` — No activity for `approachingDormantDays` (default 25)
- * - `dormant` — No activity for `dormantThresholdDays` (default 30)
+ * Staleness (active/approaching_dormant/dormant) is tracked separately in `stalenessTier`.
  */
-export type FetchedPRStatus = 'needs_response' | 'failing_ci' | 'ci_blocked' | 'ci_not_running' | 'merge_conflict' | 'needs_rebase' | 'missing_required_files' | 'incomplete_checklist' | 'needs_changes' | 'changes_addressed' | 'waiting' | 'waiting_on_maintainer' | 'healthy' | 'approaching_dormant' | 'dormant';
+export type FetchedPRStatus = 'needs_addressing' | 'waiting_on_maintainer';
 /**
  * Hints about what a maintainer is asking for in their review comments.
  * Extracted from comment text by keyword matching.
@@ -101,6 +99,12 @@ export interface FetchedPR {
     title: string;
     /** Computed by `PRMonitor.determineStatus()` based on the fields below. */
     status: FetchedPRStatus;
+    /** Granular reason for needs_addressing status. Undefined when waiting_on_maintainer. */
+    actionReason?: ActionReason;
+    /** Granular reason for waiting_on_maintainer status. Undefined when needs_addressing. */
+    waitReason?: WaitReason;
+    /** How stale the PR is based on activity age. Independent of status — a PR can be both needs_addressing and dormant. */
+    stalenessTier: StalenessTier;
     /** Human-readable status label for consistent display (#79). E.g., "[CI Failing]", "[Needs Response]". */
     displayLabel: string;
     /** Brief description of what's happening (#79). E.g., "3 checks failed", "@maintainer commented". */
@@ -321,21 +325,10 @@ export interface DailyDigest {
     generatedAt: string;
     /** All open PRs authored by the user, fetched from GitHub Search API. */
     openPRs: FetchedPR[];
-    prsNeedingResponse: FetchedPR[];
-    ciFailingPRs: FetchedPR[];
-    ciBlockedPRs: FetchedPR[];
-    ciNotRunningPRs: FetchedPR[];
-    mergeConflictPRs: FetchedPR[];
-    needsRebasePRs: FetchedPR[];
-    missingRequiredFilesPRs: FetchedPR[];
-    incompleteChecklistPRs: FetchedPR[];
-    needsChangesPRs: FetchedPR[];
-    changesAddressedPRs: FetchedPR[];
+    /** PRs where the contributor needs to take action. Subset of openPRs where status === 'needs_addressing'. */
+    needsAddressingPRs: FetchedPR[];
+    /** PRs waiting on the maintainer. Subset of openPRs where status === 'waiting_on_maintainer'. */
     waitingOnMaintainerPRs: FetchedPR[];
-    /** PRs with no activity for 25+ days (configurable via `approachingDormantDays`). */
-    approachingDormant: FetchedPR[];
-    dormantPRs: FetchedPR[];
-    healthyPRs: FetchedPR[];
     /** PRs closed without merge in the last 7 days. Surfaced to alert the contributor. */
     recentlyClosedPRs: ClosedPR[];
     /** PRs merged in the last 7 days. Surfaced as wins in the dashboard. */
@@ -354,7 +347,7 @@ export interface DailyDigest {
         totalActivePRs: number;
         /** Count of PRs requiring contributor action (response, CI fix, conflict resolution, etc.). */
         totalNeedingAttention: number;
-        /** Lifetime merged PR count across all repos, derived from {@link RepoScore} data. */
+        /** Lifetime merged PR count across all repos, derived from RepoScore data. */
         totalMergedAllTime: number;
         /** Percentage of all-time PRs that were merged (merged / (merged + closed)). */
         mergeRate: number;
@@ -411,6 +404,24 @@ export interface SnoozeInfo {
     snoozedAt: string;
     expiresAt: string;
 }
+/** Filter for excluding repos below a minimum star count from PR count queries. */
+export interface StarFilter {
+    minStars: number;
+    knownStarCounts: ReadonlyMap<string, number>;
+}
+/**
+ * Check if a repo should be excluded based on its star count.
+ * Returns true if the repo is known to be below the threshold.
+ * Repos with unknown star counts pass through (fail-open).
+ */
+export declare function isBelowMinStars(stargazersCount: number | undefined, minStars: number): boolean;
+/** Manual status override for a PR, set via dashboard or CLI. Auto-clears when new activity is detected. */
+export interface StatusOverride {
+    status: FetchedPRStatus;
+    setAt: string;
+    /** PR's updatedAt at the time the override was set. Used to detect new activity for auto-clear. */
+    lastActivityAt: string;
+}
 /** User-configurable settings, populated via `/setup-oss` and stored in {@link AgentState}. */
 export interface AgentConfig {
     /** False until the user completes initial setup via `/setup-oss`. */
@@ -457,6 +468,8 @@ export interface AgentConfig {
     dismissedIssues?: Record<string, string>;
     /** PR URLs with snoozed CI failures, mapped to snooze metadata. Snoozed PRs are excluded from actionable CI failure list until expiry. */
     snoozedPRs?: Record<string, SnoozeInfo>;
+    /** Manual status overrides for PRs. Maps PR URL to override metadata. Auto-clears when the PR has new activity. */
+    statusOverrides?: Record<string, StatusOverride>;
 }
 /** Status of a user's comment thread on a GitHub issue. */
 export type IssueConversationStatus = 'new_response' | 'waiting' | 'acknowledged';

package/dist/core/types.js

@@ -1,6 +1,14 @@
 /**
  * Core types for the Open Source Contribution Agent
  */
+/**
+ * Check if a repo should be excluded based on its star count.
+ * Returns true if the repo is known to be below the threshold.
+ * Repos with unknown star counts pass through (fail-open).
+ */
+export function isBelowMinStars(stargazersCount, minStars) {
+    return stargazersCount !== undefined && stargazersCount < minStars;
+}
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
 export const DEFAULT_CONFIG = {
     setupComplete: false,

package/dist/formatters/json.d.ts

@@ -77,20 +77,8 @@ export interface DailyDigestCompact {
     generatedAt: string;
     /** All open PRs authored by the user — the single source of truth for full PR objects. */
     openPRs: FetchedPR[];
-    prsNeedingResponse: string[];
-    ciFailingPRs: string[];
-    ciBlockedPRs: string[];
-    ciNotRunningPRs: string[];
-    mergeConflictPRs: string[];
-    needsRebasePRs: string[];
-    missingRequiredFilesPRs: string[];
-    incompleteChecklistPRs: string[];
-    needsChangesPRs: string[];
-    changesAddressedPRs: string[];
+    needsAddressingPRs: string[];
     waitingOnMaintainerPRs: string[];
-    approachingDormant: string[];
-    dormantPRs: string[];
-    healthyPRs: string[];
     recentlyClosedPRs: DailyDigest['recentlyClosedPRs'];
     recentlyMergedPRs: DailyDigest['recentlyMergedPRs'];
     shelvedPRs: ShelvedPRRef[];

package/dist/formatters/json.js

@@ -12,20 +12,8 @@ export function deduplicateDigest(digest) {
     return {
         generatedAt: digest.generatedAt,
         openPRs: digest.openPRs,
-        prsNeedingResponse: toUrls(digest.prsNeedingResponse),
-        ciFailingPRs: toUrls(digest.ciFailingPRs),
-        ciBlockedPRs: toUrls(digest.ciBlockedPRs),
-        ciNotRunningPRs: toUrls(digest.ciNotRunningPRs),
-        mergeConflictPRs: toUrls(digest.mergeConflictPRs),
-        needsRebasePRs: toUrls(digest.needsRebasePRs),
-        missingRequiredFilesPRs: toUrls(digest.missingRequiredFilesPRs),
-        incompleteChecklistPRs: toUrls(digest.incompleteChecklistPRs),
-        needsChangesPRs: toUrls(digest.needsChangesPRs),
-        changesAddressedPRs: toUrls(digest.changesAddressedPRs),
+        needsAddressingPRs: toUrls(digest.needsAddressingPRs),
         waitingOnMaintainerPRs: toUrls(digest.waitingOnMaintainerPRs),
-        approachingDormant: toUrls(digest.approachingDormant),
-        dormantPRs: toUrls(digest.dormantPRs),
-        healthyPRs: toUrls(digest.healthyPRs),
         recentlyClosedPRs: digest.recentlyClosedPRs,
         recentlyMergedPRs: digest.recentlyMergedPRs,
         shelvedPRs: digest.shelvedPRs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "0.44.3",
+  "version": "0.44.15",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -51,7 +51,7 @@
     "commander": "^14.0.3"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.3.3",
     "@vitest/coverage-v8": "^4.0.18",
     "esbuild": "^0.27.3",
     "tsx": "^4.21.0",