@oss-autopilot/core 0.41.0 → 0.42.1

package/dist/commands/startup.js

@@ -7,22 +7,11 @@
  * `node cli.bundle.cjs startup --json` call, reducing UI noise in Claude Code.
  */
 import * as fs from 'fs';
-import * as path from 'path';
 import { execFile } from 'child_process';
-import { getStateManager, getGitHubToken } from '../core/index.js';
-import { outputJson, outputJsonError } from '../formatters/json.js';
+import { getStateManager, getGitHubToken, getCLIVersion } from '../core/index.js';
+import { errorMessage } from '../core/errors.js';
 import { executeDailyCheck } from './daily.js';
 import { writeDashboardFromState } from './dashboard.js';
-function getVersion() {
-    try {
-        const pkgPath = path.join(path.dirname(process.argv[1]), '..', 'package.json');
-        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
-    }
-    catch (error) {
-        console.error('[STARTUP] Failed to detect CLI version:', error instanceof Error ? error.message : error);
-        return '0.0.0';
-    }
-}
 /**
  * Parse issueListPath from a config file's YAML frontmatter.
  * Returns the path string or undefined if not found.
@@ -76,7 +65,7 @@ export function detectIssueList() {
             }
         }
         catch (error) {
-            console.error('[STARTUP] Failed to read config:', error instanceof Error ? error.message : error);
+            console.error('[STARTUP] Failed to read config:', errorMessage(error));
         }
     }
     // 2. Probe known paths
@@ -99,7 +88,7 @@ export function detectIssueList() {
         return { path: issueListPath, source, availableCount, completedCount };
     }
     catch (error) {
-        console.error(`[STARTUP] Failed to read issue list at ${issueListPath}:`, error instanceof Error ? error.message : error);
+        console.error(`[STARTUP] Failed to read issue list at ${issueListPath}:`, errorMessage(error));
         return { path: issueListPath, source, availableCount: 0, completedCount: 0 };
     }
 }
@@ -113,85 +102,58 @@ function openInBrowser(filePath) {
         }
     });
 }
-export async function runStartup(options) {
-    const version = getVersion();
+/**
+ * Run startup checks and return structured output.
+ * Returns StartupOutput with one of three shapes:
+ * 1. Setup incomplete: { version, setupComplete: false }
+ * 2. Auth failure: { version, setupComplete: true, authError: "..." }
+ * 3. Success: { version, setupComplete: true, daily, dashboardPath?, issueList? }
+ *
+ * Errors from the daily check propagate to the caller.
+ */
+export async function runStartup() {
+    const version = getCLIVersion();
     const stateManager = getStateManager();
     // 1. Check setup
     if (!stateManager.isSetupComplete()) {
-        if (options.json) {
-            outputJson({ version, setupComplete: false });
-        }
-        else {
-            console.log('Setup incomplete. Run /setup-oss first.');
-        }
-        return;
+        return { version, setupComplete: false };
     }
     // 2. Check auth
     const token = getGitHubToken();
     if (!token) {
-        if (options.json) {
-            outputJson({
-                version,
-                setupComplete: true,
-                authError: 'GitHub authentication required. Install GitHub CLI (https://cli.github.com/) and run "gh auth login", or set GITHUB_TOKEN.',
-            });
-        }
-        else {
-            console.error('Error: GitHub authentication required.');
-        }
-        return;
+        return {
+            version,
+            setupComplete: true,
+            authError: 'GitHub authentication required. Install GitHub CLI (https://cli.github.com/) and run "gh auth login", or set GITHUB_TOKEN.',
+        };
     }
     // 3. Run daily check
+    const daily = await executeDailyCheck(token);
+    // 4. Generate dashboard from state (just saved by daily)
+    // Skip opening on first run (0 PRs) — the welcome flow handles onboarding
+    let dashboardPath;
+    let dashboardOpened = false;
     try {
-        const daily = await executeDailyCheck(token);
-        // 4. Generate dashboard from state (just saved by daily)
-        // Skip opening on first run (0 PRs) — the welcome flow handles onboarding
-        let dashboardPath;
-        let dashboardOpened = false;
-        try {
-            dashboardPath = writeDashboardFromState();
-            if (daily.digest.summary.totalActivePRs > 0) {
-                openInBrowser(dashboardPath);
-                dashboardOpened = true;
-            }
-        }
-        catch (error) {
-            console.error('[STARTUP] Dashboard generation failed:', error instanceof Error ? error.message : error);
-        }
-        // Append dashboard status to brief summary (only startup opens the browser, not daily)
-        if (dashboardOpened) {
-            daily.briefSummary += ' | Dashboard opened in browser';
-        }
-        // 5. Detect issue list
-        const issueList = detectIssueList();
-        // 6. Output
-        if (options.json) {
-            outputJson({
-                version,
-                setupComplete: true,
-                daily,
-                dashboardPath,
-                issueList,
-            });
-        }
-        else {
-            console.log(`OSS Autopilot v${version}`);
-            console.log(daily.briefSummary);
-            if (dashboardPath)
-                console.log(`Dashboard: ${dashboardPath}`);
+        dashboardPath = writeDashboardFromState();
+        if (daily.digest.summary.totalActivePRs > 0) {
+            openInBrowser(dashboardPath);
+            dashboardOpened = true;
         }
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        if (options.json) {
-            outputJsonError(`Daily check failed: ${msg}`);
-        }
-        else {
-            console.error(`[FATAL] Daily check failed: ${msg}`);
-            if (error instanceof Error && error.stack) {
-                console.error(error.stack);
-            }
-        }
-        process.exit(1);
+        console.error('[STARTUP] Dashboard generation failed:', errorMessage(error));
+    }
+    // Append dashboard status to brief summary (only startup opens the browser, not daily)
+    if (dashboardOpened) {
+        daily.briefSummary += ' | Dashboard opened in browser';
     }
+    // 5. Detect issue list
+    const issueList = detectIssueList();
+    return {
+        version,
+        setupComplete: true,
+        daily,
+        dashboardPath,
+        issueList,
+    };
 }

package/dist/commands/status.d.ts

@@ -2,9 +2,9 @@
  * Status command
  * Shows current status and stats
  */
+import type { StatusOutput } from '../formatters/json.js';
 interface StatusOptions {
-    json?: boolean;
     offline?: boolean;
 }
-export declare function runStatus(options: StatusOptions): Promise<void>;
-export {};
+export type { StatusOutput };
+export declare function runStatus(options: StatusOptions): Promise<StatusOutput>;

package/dist/commands/status.js

@@ -3,7 +3,6 @@
  * Shows current status and stats
  */
 import { getStateManager } from '../core/index.js';
-import { outputJson } from '../formatters/json.js';
 export async function runStatus(options) {
     const stateManager = getStateManager();
     const stats = stateManager.getStats();
@@ -11,33 +10,15 @@ export async function runStatus(options) {
     // Status always reads from local state (no API calls), so offline mode
     // simply adds metadata about cache freshness.
     const lastUpdated = state.lastDigestAt || state.lastRunAt;
-    if (options.json) {
-        // Extract only the stats we want to output (exclude totalTracked)
-        const { totalTracked: _totalTracked, ...outputStats } = stats;
-        const output = {
-            stats: outputStats,
-            lastRunAt: state.lastRunAt,
-        };
-        if (options.offline) {
-            output.offline = true;
-            output.lastUpdated = lastUpdated;
-        }
-        outputJson(output);
-    }
-    else {
-        // Simple console output
-        console.log('\n📊 OSS Status\n');
-        console.log(`Merged PRs: ${stats.mergedPRs}`);
-        console.log(`Closed PRs: ${stats.closedPRs}`);
-        console.log(`Merge Rate: ${stats.mergeRate}`);
-        console.log(`Needs Response: ${stats.needsResponse}`);
-        if (options.offline) {
-            console.log(`\nLast Updated: ${lastUpdated || 'Never'}`);
-            console.log('(Offline mode: showing cached data)');
-        }
-        else {
-            console.log(`\nLast Run: ${state.lastRunAt || 'Never'}`);
-        }
-        console.log('\nRun with --json for structured output');
+    // Extract only the stats we want to output (exclude totalTracked)
+    const { totalTracked: _totalTracked, ...outputStats } = stats;
+    const output = {
+        stats: outputStats,
+        lastRunAt: state.lastRunAt,
+    };
+    if (options.offline) {
+        output.offline = true;
+        output.lastUpdated = lastUpdated;
     }
+    return output;
 }

package/dist/commands/track.d.ts

@@ -3,14 +3,15 @@
  * In v2, PRs are fetched fresh from GitHub on each `daily` run.
  * These commands are preserved for backward compatibility.
  */
-interface TrackOptions {
-    prUrl: string;
-    json?: boolean;
+import type { TrackOutput } from '../formatters/json.js';
+export interface UntrackOutput {
+    removed: boolean;
+    url: string;
+    message: string;
 }
-interface UntrackOptions {
+export declare function runTrack(options: {
     prUrl: string;
-    json?: boolean;
-}
-export declare function runTrack(options: TrackOptions): Promise<void>;
-export declare function runUntrack(options: UntrackOptions): Promise<void>;
-export {};
+}): Promise<TrackOutput>;
+export declare function runUntrack(options: {
+    prUrl: string;
+}): Promise<UntrackOutput>;

package/dist/commands/track.js

@@ -3,57 +3,35 @@
  * In v2, PRs are fetched fresh from GitHub on each `daily` run.
  * These commands are preserved for backward compatibility.
  */
-import { getOctokit, getGitHubToken } from '../core/index.js';
-import { outputJson, outputJsonError } from '../formatters/json.js';
+import { getOctokit, requireGitHubToken } from '../core/index.js';
 import { validateUrl, PR_URL_PATTERN, validateGitHubUrl } from './validation.js';
 import { parseGitHubUrl } from '../core/utils.js';
 export async function runTrack(options) {
     validateUrl(options.prUrl);
-    validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR', options.json);
-    // Token is guaranteed by the preAction hook in cli.ts for non-LOCAL_ONLY_COMMANDS.
-    const token = getGitHubToken();
+    validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');
+    const token = requireGitHubToken();
     const octokit = getOctokit(token);
     const parsed = parseGitHubUrl(options.prUrl);
     if (!parsed || parsed.type !== 'pull') {
-        if (options.json) {
-            outputJsonError(`Invalid PR URL: ${options.prUrl}`);
-        }
-        else {
-            console.error(`Error: Invalid PR URL: ${options.prUrl}`);
-        }
-        process.exit(1);
+        throw new Error(`Invalid PR URL: ${options.prUrl}`);
     }
     const { owner, repo, number } = parsed;
-    if (!options.json) {
-        console.log(`\n📌 Fetching PR: ${options.prUrl}\n`);
-    }
     const { data: ghPR } = await octokit.pulls.get({ owner, repo, pull_number: number });
-    const pr = {
-        repo: `${owner}/${repo}`,
-        number,
-        title: ghPR.title,
-        url: options.prUrl,
+    return {
+        pr: {
+            repo: `${owner}/${repo}`,
+            number,
+            title: ghPR.title,
+            url: options.prUrl,
+        },
     };
-    if (options.json) {
-        outputJson({ pr });
-    }
-    else {
-        console.log(`PR: ${pr.repo}#${pr.number} - ${pr.title}`);
-        console.log('Note: In v2, PRs are tracked automatically via the daily run.');
-    }
 }
 export async function runUntrack(options) {
     validateUrl(options.prUrl);
-    validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR', options.json);
-    if (options.json) {
-        outputJson({
-            removed: false,
-            url: options.prUrl,
-            message: 'In v2, PRs are fetched fresh on each daily run — there is no local tracking list to remove from.',
-        });
-    }
-    else {
-        console.log('Note: In v2, PRs are fetched fresh on each daily run — there is no local tracking list to remove from.');
-        console.log('Use `shelve` to temporarily hide a PR from the daily summary.');
-    }
+    validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');
+    return {
+        removed: false,
+        url: options.prUrl,
+        message: 'In v2, PRs are fetched fresh on each daily run — there is no local tracking list to remove from.',
+    };
 }

package/dist/commands/validation.d.ts

@@ -6,9 +6,9 @@ export declare const PR_URL_PATTERN: RegExp;
 /** Matches GitHub issue URLs: https://github.com/owner/repo/issues/123 */
 export declare const ISSUE_URL_PATTERN: RegExp;
 /**
- * Validate a GitHub URL against a pattern. Exits with error if invalid.
+ * Validate a GitHub URL against a pattern. Throws if invalid.
  */
-export declare function validateGitHubUrl(url: string, pattern: RegExp, entityType: 'PR' | 'issue', json?: boolean): void;
+export declare function validateGitHubUrl(url: string, pattern: RegExp, entityType: 'PR' | 'issue'): void;
 /**
  * Validate that a URL does not exceed the maximum allowed length.
  * Returns the URL if valid, throws if too long.

package/dist/commands/validation.js

@@ -2,7 +2,6 @@
  * Shared validation patterns and helpers for CLI commands.
  */
 import { ValidationError } from '../core/errors.js';
-import { outputJsonError } from '../formatters/json.js';
 /** Matches GitHub PR URLs: https://github.com/owner/repo/pull/123 */
 export const PR_URL_PATTERN = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+$/;
 /** Matches GitHub issue URLs: https://github.com/owner/repo/issues/123 */
@@ -16,20 +15,13 @@ const MAX_MESSAGE_LENGTH = 1000;
 /** Pattern for valid GitHub repository identifiers */
 const REPO_PATTERN = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/;
 /**
- * Validate a GitHub URL against a pattern. Exits with error if invalid.
+ * Validate a GitHub URL against a pattern. Throws if invalid.
  */
-export function validateGitHubUrl(url, pattern, entityType, json) {
+export function validateGitHubUrl(url, pattern, entityType) {
     if (pattern.test(url))
         return;
     const example = entityType === 'PR' ? 'https://github.com/owner/repo/pull/123' : 'https://github.com/owner/repo/issues/123';
-    const msg = `Invalid ${entityType} URL: ${url}. Expected format: ${example}`;
-    if (json) {
-        outputJsonError(msg);
-    }
-    else {
-        console.error(`Error: ${msg}`);
-    }
-    process.exit(1);
+    throw new ValidationError(`Invalid ${entityType} URL: ${url}. Expected format: ${example}`);
 }
 /**
  * Validate that a URL does not exceed the maximum allowed length.
@@ -37,7 +29,7 @@ export function validateGitHubUrl(url, pattern, entityType, json) {
  */
 export function validateUrl(url) {
     if (url.length > MAX_URL_LENGTH) {
-        throw new Error(`URL exceeds maximum length of ${MAX_URL_LENGTH} characters`);
+        throw new ValidationError(`URL exceeds maximum length of ${MAX_URL_LENGTH} characters`);
     }
     return url;
 }
@@ -47,7 +39,7 @@ export function validateUrl(url) {
  */
 export function validatePRNumber(num) {
     if (!Number.isInteger(num) || num < 1 || num > MAX_PR_NUMBER) {
-        throw new Error(`PR number must be a positive integer up to ${MAX_PR_NUMBER}`);
+        throw new ValidationError(`PR number must be a positive integer up to ${MAX_PR_NUMBER}`);
     }
     return num;
 }
@@ -57,7 +49,7 @@ export function validatePRNumber(num) {
  */
 export function validateMessage(message) {
     if (message.length > MAX_MESSAGE_LENGTH) {
-        throw new Error(`Message exceeds maximum length of ${MAX_MESSAGE_LENGTH} characters`);
+        throw new ValidationError(`Message exceeds maximum length of ${MAX_MESSAGE_LENGTH} characters`);
     }
     return message;
 }
@@ -67,7 +59,7 @@ export function validateMessage(message) {
  */
 export function validateRepoIdentifier(repo) {
     if (!REPO_PATTERN.test(repo)) {
-        throw new Error(`Invalid repository format: "${repo}". Expected "owner/repo".`);
+        throw new ValidationError(`Invalid repository format: "${repo}". Expected "owner/repo".`);
     }
     return repo;
 }

package/dist/commands/vet.d.ts

@@ -2,9 +2,9 @@
  * Vet command
  * Vets a specific issue before working on it
  */
+import { type VetOutput } from '../formatters/json.js';
+export { type VetOutput } from '../formatters/json.js';
 interface VetOptions {
     issueUrl: string;
-    json?: boolean;
 }
-export declare function runVet(options: VetOptions): Promise<void>;
-export {};
+export declare function runVet(options: VetOptions): Promise<VetOutput>;

package/dist/commands/vet.js

@@ -2,35 +2,25 @@
  * Vet command
  * Vets a specific issue before working on it
  */
-import { IssueDiscovery, getGitHubToken } from '../core/index.js';
-import { outputJson } from '../formatters/json.js';
+import { IssueDiscovery, requireGitHubToken } from '../core/index.js';
 import { validateUrl } from './validation.js';
 export async function runVet(options) {
     validateUrl(options.issueUrl);
-    // Token is guaranteed by the preAction hook in cli.ts for non-LOCAL_ONLY_COMMANDS.
-    const token = getGitHubToken();
+    const token = requireGitHubToken();
     const discovery = new IssueDiscovery(token);
-    if (!options.json) {
-        console.log(`\n🔍 Vetting issue: ${options.issueUrl}\n`);
-    }
     const candidate = await discovery.vetIssue(options.issueUrl);
-    if (options.json) {
-        outputJson({
-            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,
-        });
-    }
-    else {
-        console.log(discovery.formatCandidate(candidate));
-    }
+    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/errors.d.ts

@@ -22,3 +22,12 @@ export declare class ConfigurationError extends OssAutopilotError {
 export declare class ValidationError extends OssAutopilotError {
     constructor(message: string);
 }
+/**
+ * Extract a human-readable message from an unknown error value.
+ */
+export declare function errorMessage(e: unknown): string;
+/**
+ * Safely extract an HTTP status code from an unknown error (e.g. Octokit errors).
+ * Returns undefined if the error doesn't have a numeric `status` property.
+ */
+export declare function getHttpStatusCode(error: unknown): number | undefined;

package/dist/core/errors.js

@@ -32,3 +32,20 @@ export class ValidationError extends OssAutopilotError {
         this.name = 'ValidationError';
     }
 }
+/**
+ * Extract a human-readable message from an unknown error value.
+ */
+export function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Safely extract an HTTP status code from an unknown error (e.g. Octokit errors).
+ * Returns undefined if the error doesn't have a numeric `status` property.
+ */
+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;
+}

package/dist/core/github-stats.d.ts

@@ -4,35 +4,28 @@
  */
 import { Octokit } from '@octokit/rest';
 import { ClosedPR, MergedPR } from './types.js';
+/** TTL for cached PR count results (1 hour). */
+export declare const PR_COUNTS_CACHE_TTL_MS: number;
+/** Return type shared by both merged and closed PR count functions. */
+export interface PRCountsResult<R> {
+    repos: Map<string, R>;
+    monthlyCounts: Record<string, number>;
+    monthlyOpenedCounts: Record<string, number>;
+    dailyActivityCounts: Record<string, number>;
+}
 /**
  * Fetch merged PR counts and latest merge dates per repository for the configured user.
  * Also builds a monthly histogram of all merges for the contribution timeline.
  */
-export declare function fetchUserMergedPRCounts(octokit: Octokit, githubUsername: string): Promise<{
-    repos: Map<string, {
-        count: number;
-        lastMergedAt: string;
-    }>;
-    monthlyCounts: Record<string, number>;
-    monthlyOpenedCounts: Record<string, number>;
-    dailyActivityCounts: Record<string, number>;
-}>;
+export declare function fetchUserMergedPRCounts(octokit: Octokit, githubUsername: string): Promise<PRCountsResult<{
+    count: number;
+    lastMergedAt: string;
+}>>;
 /**
  * Fetch closed-without-merge PR counts per repository for the configured user.
  * Used to populate closedWithoutMergeCount in repo scores for accurate merge rate.
  */
-export declare function fetchUserClosedPRCounts(octokit: Octokit, githubUsername: string): Promise<{
-    repos: Map<string, number>;
-    monthlyCounts: Record<string, number>;
-    monthlyOpenedCounts: Record<string, number>;
-    dailyActivityCounts: Record<string, number>;
-}>;
-/**
- * Fetch GitHub star counts for a list of repositories.
- * Used to populate stargazersCount in repo scores for dashboard filtering by minStars.
- * Fetches concurrently with per-repo error isolation (missing/private repos are skipped).
- */
-export declare function fetchRepoStarCounts(octokit: Octokit, repos: string[]): Promise<Map<string, number>>;
+export declare function fetchUserClosedPRCounts(octokit: Octokit, githubUsername: string): Promise<PRCountsResult<number>>;
 /**
  * Shared helper: search for recent PRs and filter out own repos, excluded repos/orgs.
  * Returns parsed search results that pass all filters.