@oss-autopilot/core 0.54.0 → 0.55.0

package/dist/core/state.js

@@ -21,6 +21,8 @@ export class StateManager {
     state;
     inMemoryOnly;
     lastLoadedMtimeMs = 0;
+    _batching = false;
+    _batchDirty = false;
     /**
      * Create a new StateManager instance.
      * @param inMemoryOnly - When true, state is held only in memory and never read from or
@@ -38,6 +40,37 @@ export class StateManager {
             this.lastLoadedMtimeMs = result.mtimeMs;
         }
     }
+    /**
+     * Execute multiple mutations as a single batch, deferring disk I/O until the
+     * batch completes. Nested `batch()` calls are flattened — only the outermost saves.
+     */
+    batch(fn) {
+        if (this._batching) {
+            fn();
+            return;
+        }
+        this._batching = true;
+        this._batchDirty = false;
+        try {
+            fn();
+            if (this._batchDirty)
+                this.save();
+        }
+        finally {
+            this._batching = false;
+            this._batchDirty = false;
+        }
+    }
+    /**
+     * Auto-persist after a mutation. Inside a `batch()`, defers to the batch boundary.
+     */
+    autoSave() {
+        if (this._batching) {
+            this._batchDirty = true;
+            return;
+        }
+        this.save();
+    }
     /**
      * Check if initial setup has been completed.
      */
@@ -50,6 +83,7 @@ export class StateManager {
     markSetupComplete() {
         this.state.config.setupComplete = true;
         this.state.config.setupCompletedAt = new Date().toISOString();
+        this.autoSave();
     }
     /**
      * Initialize state with sensible defaults for zero-config onboarding.
@@ -60,10 +94,11 @@ export class StateManager {
             debug(MODULE, `Setup already complete, skipping initializeWithDefaults for "${username}"`);
             return;
         }
-        this.state.config.githubUsername = username;
-        this.markSetupComplete();
-        debug(MODULE, `Initialized with defaults for user "${username}"`);
-        this.save();
+        this.batch(() => {
+            this.updateConfig({ githubUsername: username });
+            this.markSetupComplete();
+            debug(MODULE, `Initialized with defaults for user "${username}"`);
+        });
     }
     /**
      * Persist the current state to disk, creating a timestamped backup of the previous
@@ -100,21 +135,27 @@ export class StateManager {
     setLastDigest(digest) {
         this.state.lastDigest = digest;
         this.state.lastDigestAt = digest.generatedAt;
+        this.autoSave();
     }
     setMonthlyMergedCounts(counts) {
         this.state.monthlyMergedCounts = counts;
+        this.autoSave();
     }
     setMonthlyClosedCounts(counts) {
         this.state.monthlyClosedCounts = counts;
+        this.autoSave();
     }
     setMonthlyOpenedCounts(counts) {
         this.state.monthlyOpenedCounts = counts;
+        this.autoSave();
     }
     setDailyActivityCounts(counts) {
         this.state.dailyActivityCounts = counts;
+        this.autoSave();
     }
     setLocalRepoCache(cache) {
         this.state.localRepoCache = cache;
+        this.autoSave();
     }
     // === Merged PR Storage ===
     getMergedPRs() {
@@ -132,6 +173,7 @@ export class StateManager {
         this.state.mergedPRs.push(...newPRs);
         this.state.mergedPRs.sort((a, b) => b.mergedAt.localeCompare(a.mergedAt));
         debug(MODULE, `Added ${newPRs.length} merged PRs (total: ${this.state.mergedPRs.length})`);
+        this.autoSave();
     }
     getMergedPRWatermark() {
         return this.state.mergedPRs?.[0]?.mergedAt || undefined;
@@ -152,6 +194,7 @@ export class StateManager {
         this.state.closedPRs.push(...newPRs);
         this.state.closedPRs.sort((a, b) => b.closedAt.localeCompare(a.closedAt));
         debug(MODULE, `Added ${newPRs.length} closed PRs (total: ${this.state.closedPRs.length})`);
+        this.autoSave();
     }
     getClosedPRWatermark() {
         return this.state.closedPRs?.[0]?.closedAt || undefined;
@@ -159,6 +202,7 @@ export class StateManager {
     // === Configuration ===
     updateConfig(config) {
         this.state.config = { ...this.state.config, ...config };
+        this.autoSave();
     }
     // === Event Logging ===
     appendEvent(type, data) {
@@ -173,6 +217,7 @@ export class StateManager {
         if (this.state.events.length > MAX_EVENTS) {
             this.state.events = this.state.events.slice(-MAX_EVENTS);
         }
+        this.autoSave();
     }
     getEventsByType(type) {
         return this.state.events.filter((e) => e.type === type);
@@ -192,12 +237,14 @@ export class StateManager {
         }
         this.state.activeIssues.push(issue);
         debug(MODULE, `Added issue: ${issue.repo}#${issue.number}`);
+        this.autoSave();
     }
     // === Trusted Projects ===
     addTrustedProject(repo) {
         if (!this.state.config.trustedProjects.includes(repo)) {
             this.state.config.trustedProjects.push(repo);
             debug(MODULE, `Added trusted project: ${repo}`);
+            this.autoSave();
         }
     }
     static matchesExclusion(repo, repos, orgs) {
@@ -215,6 +262,7 @@ export class StateManager {
         const removedTrusted = beforeTrusted - this.state.config.trustedProjects.length;
         if (removedTrusted > 0) {
             debug(MODULE, `Removed ${removedTrusted} trusted project(s) for excluded repos/orgs`);
+            this.autoSave();
         }
     }
     // === Starred Repos Management ===
@@ -225,6 +273,7 @@ export class StateManager {
         this.state.config.starredRepos = repos;
         this.state.config.starredReposLastFetched = new Date().toISOString();
         debug(MODULE, `Updated starred repos: ${repos.length} repositories`);
+        this.autoSave();
     }
     isStarredReposStale() {
         const lastFetched = this.state.config.starredReposLastFetched;
@@ -245,6 +294,7 @@ export class StateManager {
             return false;
         }
         this.state.config.shelvedPRUrls.push(url);
+        this.autoSave();
         return true;
     }
     unshelvePR(url) {
@@ -256,6 +306,7 @@ export class StateManager {
             return false;
         }
         this.state.config.shelvedPRUrls.splice(index, 1);
+        this.autoSave();
         return true;
     }
     isPRShelved(url) {
@@ -270,6 +321,7 @@ export class StateManager {
             return false;
         }
         this.state.config.dismissedIssues[url] = timestamp;
+        this.autoSave();
         return true;
     }
     undismissIssue(url) {
@@ -277,6 +329,7 @@ export class StateManager {
             return false;
         }
         delete this.state.config.dismissedIssues[url];
+        this.autoSave();
         return true;
     }
     getIssueDismissedAt(url) {
@@ -292,12 +345,14 @@ export class StateManager {
             setAt: new Date().toISOString(),
             lastActivityAt,
         };
+        this.autoSave();
     }
     clearStatusOverride(url) {
         if (!this.state.config.statusOverrides || !(url in this.state.config.statusOverrides)) {
             return false;
         }
         delete this.state.config.statusOverrides[url];
+        this.autoSave();
         return true;
     }
     getStatusOverride(url, currentUpdatedAt) {
@@ -317,15 +372,19 @@ export class StateManager {
     }
     updateRepoScore(repo, updates) {
         repoScoring.updateRepoScore(this.state, repo, updates);
+        this.autoSave();
     }
     incrementMergedCount(repo) {
         repoScoring.incrementMergedCount(this.state, repo);
+        this.autoSave();
     }
     incrementClosedCount(repo) {
         repoScoring.incrementClosedCount(this.state, repo);
+        this.autoSave();
     }
     markRepoHostile(repo) {
         repoScoring.markRepoHostile(this.state, repo);
+        this.autoSave();
     }
     getReposWithMergedPRs() {
         return repoScoring.getReposWithMergedPRs(this.state);

package/dist/core/types.d.ts

@@ -25,7 +25,7 @@ export interface ClassifiedCheck {
     category: CIFailureCategory;
     conclusion?: string;
 }
-/** Return type for PRMonitor.getCIStatus(). */
+/** CI status result returned by getCIStatus(). */
 export interface CIStatusResult {
     status: CIStatus;
     failingCheckNames: string[];
@@ -468,6 +468,8 @@ export interface AgentConfig {
     languages: string[];
     /** GitHub labels to filter issues by (e.g., `["good first issue", "help wanted"]`). */
     labels: string[];
+    /** Issue scope tiers to search (e.g., `["beginner", "intermediate"]`). When set, scope tier labels are merged with custom `labels`. When absent, only `labels` is used (legacy behavior). */
+    scope?: IssueScope[];
     /** Repos to exclude from issue discovery/search, in `"owner/repo"` format. */
     excludeRepos: string[];
     /** Organizations to exclude from issue discovery/search (case-insensitive match on owner segment). */
@@ -498,6 +500,8 @@ export interface AgentConfig {
     dismissedIssues?: Record<string, string>;
     /** Manual status overrides for PRs. Maps PR URL to override metadata. Auto-clears when the PR has new activity. */
     statusOverrides?: Record<string, StatusOverride>;
+    /** Path to the user's curated issue list file. Replaces config.md as the primary source for detectIssueList(). */
+    issueListPath?: string;
     /** Project categories the user is interested in (e.g., devtools, nonprofit). Used to prioritize search results. */
     projectCategories?: ProjectCategory[];
     /** GitHub organizations the user wants to prioritize in issue search. Org names only (not owner/repo). */
@@ -542,6 +546,9 @@ export declare const DEFAULT_CONFIG: AgentConfig;
 export declare const INITIAL_STATE: AgentState;
 export declare const PROJECT_CATEGORIES: readonly ["nonprofit", "devtools", "infrastructure", "web-frameworks", "data-ml", "education"];
 export type ProjectCategory = (typeof PROJECT_CATEGORIES)[number];
+export declare const ISSUE_SCOPES: readonly ["beginner", "intermediate", "advanced"];
+export type IssueScope = (typeof ISSUE_SCOPES)[number];
+export declare const SCOPE_LABELS: Record<IssueScope, string[]>;
 /** Priority tier for issue search results. Ordered: merged_pr > preferred_org > starred > normal. */
 export type SearchPriority = 'merged_pr' | 'preferred_org' | 'starred' | 'normal';
 export interface IssueCandidate {

package/dist/core/types.js

@@ -49,3 +49,10 @@ export const PROJECT_CATEGORIES = [
     'data-ml',
     'education',
 ];
+// -- Issue scope types --
+export const ISSUE_SCOPES = ['beginner', 'intermediate', 'advanced'];
+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/formatters/json.d.ts

@@ -5,7 +5,7 @@
 import type { FetchedPR, DailyDigest, AgentState, RepoGroup, CommentedIssue, ShelvedPRRef } from '../core/types.js';
 import type { ContributionStats } from '../core/stats.js';
 import type { PRCheckFailure } from '../core/pr-monitor.js';
-import type { SearchPriority } from '../core/issue-discovery.js';
+import type { SearchPriority } from '../core/types.js';
 export interface JsonOutput<T = unknown> {
     success: boolean;
     data?: T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {