@oss-autopilot/core 0.58.0 → 0.60.0

package/dist/core/logger.d.ts

@@ -9,18 +9,31 @@ export declare function enableDebug(): void;
 export declare function isDebugEnabled(): boolean;
 /**
  * Log a debug message. Only outputs when --debug is enabled.
+ * @param module - Module name for log prefix
+ * @param message - Log message
+ * @param args - Additional values to log
  */
 export declare function debug(module: string, message: string, ...args: unknown[]): void;
 /**
  * Log an informational message. Always outputs to stderr.
  * Use for user-facing progress indicators during long-running operations.
+ * @param module - Module name for log prefix
+ * @param message - Log message
+ * @param args - Additional values to log
  */
 export declare function info(module: string, message: string, ...args: unknown[]): void;
 /**
  * Log a warning. Always outputs.
+ * @param module - Module name for log prefix
+ * @param message - Warning message
+ * @param args - Additional values to log
  */
 export declare function warn(module: string, message: string, ...args: unknown[]): void;
 /**
  * Time an async operation and log duration in debug mode.
+ * @param module - Module name for log prefix
+ * @param label - Operation label for the timing log
+ * @param fn - Async function to time
+ * @returns The result of the async function
  */
 export declare function timed<T>(module: string, label: string, fn: () => Promise<T>): Promise<T>;

package/dist/core/logger.js

@@ -14,6 +14,9 @@ export function isDebugEnabled() {
 }
 /**
  * Log a debug message. Only outputs when --debug is enabled.
+ * @param module - Module name for log prefix
+ * @param message - Log message
+ * @param args - Additional values to log
  */
 export function debug(module, message, ...args) {
     if (!debugEnabled)
@@ -24,6 +27,9 @@ export function debug(module, message, ...args) {
 /**
  * Log an informational message. Always outputs to stderr.
  * Use for user-facing progress indicators during long-running operations.
+ * @param module - Module name for log prefix
+ * @param message - Log message
+ * @param args - Additional values to log
  */
 export function info(module, message, ...args) {
     const timestamp = new Date().toISOString();
@@ -31,6 +37,9 @@ export function info(module, message, ...args) {
 }
 /**
  * Log a warning. Always outputs.
+ * @param module - Module name for log prefix
+ * @param message - Warning message
+ * @param args - Additional values to log
  */
 export function warn(module, message, ...args) {
     const timestamp = new Date().toISOString();
@@ -38,6 +47,10 @@ export function warn(module, message, ...args) {
 }
 /**
  * Time an async operation and log duration in debug mode.
+ * @param module - Module name for log prefix
+ * @param label - Operation label for the timing log
+ * @param fn - Async function to time
+ * @returns The result of the async function
  */
 export async function timed(module, label, fn) {
     if (!debugEnabled)

package/dist/core/pr-monitor.d.ts

@@ -21,6 +21,9 @@ export { determineStatus } from './status-determination.js';
 /**
  * Check if a PR has a merge conflict based on GitHub's mergeable flag and mergeable_state.
  * Returns true when mergeable is explicitly false or the mergeable_state is 'dirty'.
+ *
+ * @param mergeable - GitHub's mergeable flag (null when not yet computed)
+ * @param mergeableState - GitHub's mergeable_state string
  */
 export declare function hasMergeConflict(mergeable: boolean | null, mergeableState: string | null): boolean;
 export interface PRCheckFailure {
@@ -31,13 +34,35 @@ export interface FetchPRsResult {
     prs: FetchedPR[];
     failures: PRCheckFailure[];
 }
+/**
+ * Fetches and enriches open PRs from GitHub for the configured user.
+ *
+ * In v2, all PR data is fetched fresh on each run — no local PR tracking.
+ * CI status, reviews, merge conflicts, and maintainer comments are enriched
+ * for each PR to compute a {@link FetchedPRStatus}.
+ */
 export declare class PRMonitor {
     private octokit;
     private stateManager;
+    /**
+     * @param githubToken - GitHub personal access token or token from `gh auth token`
+     */
     constructor(githubToken: string);
     /**
-     * Fetch all open PRs for the configured user fresh from GitHub
-     * This is the main entry point for the v2 architecture
+     * Fetch all open PRs for the configured user fresh from GitHub.
+     * This is the main entry point for the v2 architecture.
+     *
+     * @returns All open PRs enriched with status, plus any failures
+     * @throws {ConfigurationError} If no GitHub username is configured
+     *
+     * @example
+     * ```typescript
+     * import { PRMonitor, requireGitHubToken } from '@oss-autopilot/core';
+     *
+     * const monitor = new PRMonitor(requireGitHubToken());
+     * const { prs, failures } = await monitor.fetchUserOpenPRs();
+     * console.log(`Found ${prs.length} open PRs, ${failures.length} failures`);
+     * ```
      */
     fetchUserOpenPRs(): Promise<FetchPRsResult>;
     /**
@@ -51,7 +76,8 @@ export declare class PRMonitor {
     private buildFetchedPR;
     /**
      * Fetch merged PR counts and latest merge dates per repository for the configured user.
-     * Delegates to github-stats module.
+     * @param starFilter - Optional filter to exclude low-star repos
+     * @returns Per-repo merged counts with monthly breakdowns
      */
     fetchUserMergedPRCounts(starFilter?: StarFilter): Promise<PRCountsResult<{
         count: number;
@@ -59,7 +85,8 @@ export declare class PRMonitor {
     }>>;
     /**
      * Fetch closed-without-merge PR counts per repository for the configured user.
-     * Delegates to github-stats module.
+     * @param starFilter - Optional filter to exclude low-star repos
+     * @returns Per-repo closed counts with monthly breakdowns
      */
     fetchUserClosedPRCounts(starFilter?: StarFilter): Promise<PRCountsResult<number>>;
     /**
@@ -72,20 +99,28 @@ export declare class PRMonitor {
     }>>;
     /**
      * Fetch PRs closed without merge in the last N days.
-     * Delegates to github-stats module.
+     * @param days - Lookback window in days (default: 7)
+     * @returns Recently closed PRs
      */
     fetchRecentlyClosedPRs(days?: number): Promise<ClosedPR[]>;
     /**
      * Fetch PRs merged in the last N days.
-     * Delegates to github-stats module.
+     * @param days - Lookback window in days (default: 7)
+     * @returns Recently merged PRs
      */
     fetchRecentlyMergedPRs(days?: number): Promise<MergedPR[]>;
     /**
-     * Generate a daily digest from fetched PRs
+     * Generate a daily digest from fetched PRs.
+     * @param prs - All open PRs (active + shelved)
+     * @param recentlyClosedPRs - PRs closed without merge in the last 7 days
+     * @param recentlyMergedPRs - PRs merged in the last 7 days
+     * @returns Daily digest with categorized PRs and summary stats
      */
     generateDigest(prs: FetchedPR[], recentlyClosedPRs?: ClosedPR[], recentlyMergedPRs?: MergedPR[]): DailyDigest;
     /**
-     * Update repository scores based on observed PR (called when we detect merged/closed PRs)
+     * Update repository scores based on observed PR (called when we detect merged/closed PRs).
+     * @param repo - Repository in "owner/repo" format
+     * @param wasMerged - true if the PR was merged, false if closed without merge
      */
     updateRepoScoreFromObservedPR(repo: string, wasMerged: boolean): Promise<void>;
 }

package/dist/core/pr-monitor.js

@@ -35,22 +35,47 @@ export { determineStatus } from './status-determination.js';
 /**
  * Check if a PR has a merge conflict based on GitHub's mergeable flag and mergeable_state.
  * Returns true when mergeable is explicitly false or the mergeable_state is 'dirty'.
+ *
+ * @param mergeable - GitHub's mergeable flag (null when not yet computed)
+ * @param mergeableState - GitHub's mergeable_state string
  */
 export function hasMergeConflict(mergeable, mergeableState) {
     return mergeable === false || mergeableState === 'dirty';
 }
 const MODULE = 'pr-monitor';
 const MAX_CONCURRENT_REQUESTS = DEFAULT_CONCURRENCY;
+/**
+ * Fetches and enriches open PRs from GitHub for the configured user.
+ *
+ * In v2, all PR data is fetched fresh on each run — no local PR tracking.
+ * CI status, reviews, merge conflicts, and maintainer comments are enriched
+ * for each PR to compute a {@link FetchedPRStatus}.
+ */
 export class PRMonitor {
     octokit;
     stateManager;
+    /**
+     * @param githubToken - GitHub personal access token or token from `gh auth token`
+     */
     constructor(githubToken) {
         this.octokit = getOctokit(githubToken);
         this.stateManager = getStateManager();
     }
     /**
-     * Fetch all open PRs for the configured user fresh from GitHub
-     * This is the main entry point for the v2 architecture
+     * Fetch all open PRs for the configured user fresh from GitHub.
+     * This is the main entry point for the v2 architecture.
+     *
+     * @returns All open PRs enriched with status, plus any failures
+     * @throws {ConfigurationError} If no GitHub username is configured
+     *
+     * @example
+     * ```typescript
+     * import { PRMonitor, requireGitHubToken } from '@oss-autopilot/core';
+     *
+     * const monitor = new PRMonitor(requireGitHubToken());
+     * const { prs, failures } = await monitor.fetchUserOpenPRs();
+     * console.log(`Found ${prs.length} open PRs, ${failures.length} failures`);
+     * ```
      */
     async fetchUserOpenPRs() {
         const config = this.stateManager.getState().config;
@@ -287,7 +312,8 @@ export class PRMonitor {
     }
     /**
      * Fetch merged PR counts and latest merge dates per repository for the configured user.
-     * Delegates to github-stats module.
+     * @param starFilter - Optional filter to exclude low-star repos
+     * @returns Per-repo merged counts with monthly breakdowns
      */
     async fetchUserMergedPRCounts(starFilter) {
         const config = this.stateManager.getState().config;
@@ -295,7 +321,8 @@ export class PRMonitor {
     }
     /**
      * Fetch closed-without-merge PR counts per repository for the configured user.
-     * Delegates to github-stats module.
+     * @param starFilter - Optional filter to exclude low-star repos
+     * @returns Per-repo closed counts with monthly breakdowns
      */
     async fetchUserClosedPRCounts(starFilter) {
         const config = this.stateManager.getState().config;
@@ -357,7 +384,8 @@ export class PRMonitor {
     }
     /**
      * Fetch PRs closed without merge in the last N days.
-     * Delegates to github-stats module.
+     * @param days - Lookback window in days (default: 7)
+     * @returns Recently closed PRs
      */
     async fetchRecentlyClosedPRs(days = 7) {
         const config = this.stateManager.getState().config;
@@ -365,14 +393,19 @@ export class PRMonitor {
     }
     /**
      * Fetch PRs merged in the last N days.
-     * Delegates to github-stats module.
+     * @param days - Lookback window in days (default: 7)
+     * @returns Recently merged PRs
      */
     async fetchRecentlyMergedPRs(days = 7) {
         const config = this.stateManager.getState().config;
         return fetchRecentlyMergedPRsImpl(this.octokit, config, days);
     }
     /**
-     * Generate a daily digest from fetched PRs
+     * Generate a daily digest from fetched PRs.
+     * @param prs - All open PRs (active + shelved)
+     * @param recentlyClosedPRs - PRs closed without merge in the last 7 days
+     * @param recentlyMergedPRs - PRs merged in the last 7 days
+     * @returns Daily digest with categorized PRs and summary stats
      */
     generateDigest(prs, recentlyClosedPRs = [], recentlyMergedPRs = []) {
         const now = new Date().toISOString();
@@ -399,7 +432,9 @@ export class PRMonitor {
         };
     }
     /**
-     * Update repository scores based on observed PR (called when we detect merged/closed PRs)
+     * Update repository scores based on observed PR (called when we detect merged/closed PRs).
+     * @param repo - Repository in "owner/repo" format
+     * @param wasMerged - true if the PR was merged, false if closed without merge
      */
     async updateRepoScoreFromObservedPR(repo, wasMerged) {
         if (wasMerged) {

package/dist/core/state-persistence.d.ts

@@ -24,6 +24,7 @@ export declare function releaseLock(lockPath: string): void;
 export declare function atomicWriteFileSync(filePath: string, data: string, mode?: number): void;
 /**
  * Create a fresh state (v2: fresh GitHub fetching).
+ * Leverages Zod schema defaults to produce a complete state.
  */
 export declare function createFreshState(): AgentState;
 /**

package/dist/core/state-persistence.js

@@ -5,13 +5,11 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { INITIAL_STATE } from './types.js';
+import { AgentStateSchema } from './state-schema.js';
 import { getStatePath, getBackupDir, getDataDir } from './utils.js';
 import { errorMessage } from './errors.js';
 import { debug, warn } from './logger.js';
 const MODULE = 'state';
-// Current state version
-const CURRENT_STATE_VERSION = 2;
 // Lock file timeout: if a lock is older than this, it is considered stale
 const LOCK_TIMEOUT_MS = 30_000; // 30 seconds
 // Legacy path for migration
@@ -139,66 +137,12 @@ function migrateV1ToV2(rawState) {
     debug(MODULE, `Migration complete. Preserved ${Object.keys(repoScores).length} repo scores.`);
     return migratedState;
 }
-/**
- * Validate that a loaded state has the required structure.
- * Handles both v1 (with PR arrays) and v2 (without).
- */
-function isValidState(state) {
-    if (!state || typeof state !== 'object')
-        return false;
-    const s = state;
-    // Migrate older states that don't have repoScores
-    if (s.repoScores === undefined) {
-        s.repoScores = {};
-    }
-    // Migrate older states that don't have events
-    if (s.events === undefined) {
-        s.events = [];
-    }
-    // Migrate older states that don't have mergedPRs
-    if (s.mergedPRs === undefined) {
-        s.mergedPRs = [];
-    }
-    // Base requirements for all versions
-    const hasBaseFields = typeof s.version === 'number' &&
-        typeof s.repoScores === 'object' &&
-        s.repoScores !== null &&
-        Array.isArray(s.events) &&
-        typeof s.config === 'object' &&
-        s.config !== null;
-    if (!hasBaseFields)
-        return false;
-    // v1 requires base PR arrays to be present (they will be dropped during migration)
-    if (s.version === 1) {
-        return (Array.isArray(s.activePRs) &&
-            Array.isArray(s.dormantPRs) &&
-            Array.isArray(s.mergedPRs) &&
-            Array.isArray(s.closedPRs));
-    }
-    // v2+ doesn't require PR arrays
-    return true;
-}
 /**
  * Create a fresh state (v2: fresh GitHub fetching).
+ * Leverages Zod schema defaults to produce a complete state.
  */
 export function createFreshState() {
-    return {
-        version: CURRENT_STATE_VERSION,
-        activeIssues: [],
-        repoScores: {},
-        config: {
-            ...INITIAL_STATE.config,
-            setupComplete: false,
-            languages: [...INITIAL_STATE.config.languages],
-            labels: [...INITIAL_STATE.config.labels],
-            excludeRepos: [],
-            trustedProjects: [],
-            shelvedPRUrls: [],
-            dismissedIssues: {},
-        },
-        events: [],
-        lastRunAt: new Date().toISOString(),
-    };
+    return AgentStateSchema.parse({ version: 2 });
 }
 /**
  * Migrate state from legacy ./data/ location to ~/.oss-autopilot/.
@@ -298,13 +242,15 @@ function tryRestoreFromBackup() {
         const backupPath = path.join(backupDir, backupFile);
         try {
             const data = fs.readFileSync(backupPath, 'utf-8');
-            let state = JSON.parse(data);
-            if (isValidState(state)) {
+            let raw = JSON.parse(data);
+            // Migrate from v1 to v2 if needed (before schema validation)
+            if (typeof raw === 'object' && raw !== null && raw.version === 1) {
+                raw = migrateV1ToV2(raw);
+            }
+            const parsed = AgentStateSchema.safeParse(raw);
+            if (parsed.success) {
+                const state = parsed.data;
                 debug(MODULE, `Successfully restored state from backup: ${backupFile}`);
-                // Migrate from v1 to v2 if needed
-                if (state.version === 1) {
-                    state = migrateV1ToV2(state);
-                }
                 const repoCount = Object.keys(state.repoScores).length;
                 debug(MODULE, `Restored state v${state.version}: ${repoCount} repo scores`);
                 // Overwrite the corrupted main state file with the restored backup (atomic write)
@@ -313,6 +259,10 @@ function tryRestoreFromBackup() {
                 debug(MODULE, 'Restored backup written to main state file');
                 return state;
             }
+            // safeParse failed — log and try next backup
+            const summary = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+            warn(MODULE, `Backup ${backupFile} failed schema validation: ${summary}`);
+            debug(MODULE, `Backup ${backupFile} full validation errors:`, parsed.error.issues);
         }
         catch (backupErr) {
             // This backup is also corrupted, try the next one
@@ -335,10 +285,29 @@ export function loadState() {
     try {
         if (fs.existsSync(statePath)) {
             const data = fs.readFileSync(statePath, 'utf-8');
-            let state = JSON.parse(data);
-            // Validate required fields exist
-            if (!isValidState(state)) {
-                warn(MODULE, 'Invalid state file structure, attempting to restore from backup...');
+            let raw = JSON.parse(data);
+            // Migrate from v1 to v2 if needed (before schema validation)
+            let wasMigrated = false;
+            if (typeof raw === 'object' && raw !== null && raw.version === 1) {
+                raw = migrateV1ToV2(raw);
+                wasMigrated = true;
+            }
+            // Validate through Zod schema (strips unknown keys in memory; stale keys persist on disk until next save)
+            const parsed = AgentStateSchema.safeParse(raw);
+            if (!parsed.success) {
+                const summary = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+                warn(MODULE, `Invalid state file structure: ${summary}`);
+                warn(MODULE, 'Attempting to restore from backup...');
+                debug(MODULE, 'Full validation errors:', parsed.error.issues);
+                // Preserve the rejected state file so the user can recover
+                try {
+                    const rejectedPath = statePath + '.rejected-' + Date.now();
+                    fs.copyFileSync(statePath, rejectedPath);
+                    warn(MODULE, `Previous state preserved at: ${rejectedPath}`);
+                }
+                catch (preserveErr) {
+                    warn(MODULE, `Could not preserve rejected state file: ${errorMessage(preserveErr)}`);
+                }
                 const restoredState = tryRestoreFromBackup();
                 if (restoredState) {
                     const mtimeMs = safeGetMtimeMs(statePath);
@@ -347,23 +316,16 @@ export function loadState() {
                 warn(MODULE, 'No valid backup found, starting fresh');
                 return { state: createFreshState(), mtimeMs: 0 };
             }
-            // Migrate from v1 to v2 if needed
-            if (state.version === 1) {
-                state = migrateV1ToV2(state);
-                // Save the migrated state immediately (atomic write)
-                atomicWriteFileSync(statePath, JSON.stringify(state, null, 2), 0o600);
-                debug(MODULE, 'Migrated state saved');
+            // Save migrated state only after validation succeeds
+            if (wasMigrated) {
+                atomicWriteFileSync(statePath, JSON.stringify(parsed.data, null, 2), 0o600);
+                debug(MODULE, 'Migrated and validated state saved');
             }
-            // Strip legacy fields from persisted state (snoozedPRs and PR dismiss
-            // entries were removed in the three-state PR model simplification)
+            const state = parsed.data;
+            // Strip PR URLs from dismissedIssues (PR dismiss removed).
+            // This filters values inside a known field — Zod .strip() only removes unknown keys.
             try {
                 let needsCleanupSave = false;
-                const rawConfig = state.config;
-                if (rawConfig.snoozedPRs) {
-                    delete rawConfig.snoozedPRs;
-                    needsCleanupSave = true;
-                }
-                // Strip PR URLs from dismissedIssues (PR dismiss removed)
                 if (state.config.dismissedIssues) {
                     const PR_URL_RE = /\/pull\/\d+$/;
                     for (const url of Object.keys(state.config.dismissedIssues)) {
@@ -375,7 +337,7 @@ export function loadState() {
                 }
                 if (needsCleanupSave) {
                     atomicWriteFileSync(statePath, JSON.stringify(state, null, 2), 0o600);
-                    warn(MODULE, 'Cleaned up removed features (snoozedPRs, dismissed PR URLs) from persisted state');
+                    warn(MODULE, 'Cleaned up dismissed PR URLs from persisted state');
                 }
             }
             catch (cleanupError) {