@oss-autopilot/core 0.58.0 → 0.59.0

package/dist/commands/startup.js

@@ -15,7 +15,8 @@ import { executeDailyCheck } from './daily.js';
 import { launchDashboardServer } from './dashboard-lifecycle.js';
 /**
  * Parse issueListPath from a config file's YAML frontmatter.
- * Returns the path string or undefined if not found.
+ * @param configContent - Raw content of the config.md file
+ * @returns The path string or undefined if not found
  */
 export function parseIssueListPathFromConfig(configContent) {
     const match = configContent.match(/^---\n([\s\S]*?)\n---/);
@@ -27,8 +28,11 @@ export function parseIssueListPathFromConfig(configContent) {
 }
 /**
  * Count available and completed items in an issue list file.
- * Available: list items (- [) NOT struck through or marked Done.
+ * Available: list items (`- [`) NOT struck through or marked Done.
  * Completed: list items that ARE struck through or marked Done.
+ *
+ * @param content - Raw markdown content of the issue list
+ * @returns Counts of available and completed items
  */
 export function countIssueListItems(content) {
     let availableCount = 0;
@@ -49,7 +53,7 @@ export function countIssueListItems(content) {
 }
 /**
  * Detect an issue list file from config or known paths.
- * Returns IssueListInfo or undefined if no list found.
+ * @returns Issue list info with path and item counts, or undefined if not found
  */
 export function detectIssueList() {
     let issueListPath = '';
@@ -108,6 +112,10 @@ export function detectIssueList() {
         return { path: issueListPath, source, availableCount: 0, completedCount: 0 };
     }
 }
+/**
+ * Open a URL in the default system browser.
+ * @param url - URL to open
+ */
 export function openInBrowser(url) {
     let openCmd;
     let args;
@@ -134,11 +142,12 @@ export function openInBrowser(url) {
 /**
  * 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, dashboardUrl?, issueList? }
+ * 1. Setup incomplete: `{ version, setupComplete: false }`
+ * 2. Auth failure: `{ version, setupComplete: true, authError: "..." }`
+ * 3. Success: `{ version, setupComplete: true, daily, dashboardUrl?, issueList? }`
  *
- * Errors from the daily check propagate to the caller.
+ * @returns Startup output with auth/setup status and daily digest
+ * @throws {Error} If the daily check fails (auth or network errors propagate)
  */
 export async function runStartup() {
     const version = getCLIVersion();

package/dist/commands/status.d.ts

@@ -7,4 +7,12 @@ interface StatusOptions {
     offline?: boolean;
 }
 export type { StatusOutput };
+/**
+ * Return contribution statistics from local state.
+ * No API calls — reads from ~/.oss-autopilot/state.json.
+ *
+ * @param options - Status options
+ * @param options.offline - When true, adds cache freshness metadata
+ * @returns Contribution stats (merge rate, PR counts, repo breakdown)
+ */
 export declare function runStatus(options: StatusOptions): Promise<StatusOutput>;

package/dist/commands/status.js

@@ -3,6 +3,14 @@
  * Shows current status and stats
  */
 import { getStateManager } from '../core/index.js';
+/**
+ * Return contribution statistics from local state.
+ * No API calls — reads from ~/.oss-autopilot/state.json.
+ *
+ * @param options - Status options
+ * @param options.offline - When true, adds cache freshness metadata
+ * @returns Contribution stats (merge rate, PR counts, repo breakdown)
+ */
 export async function runStatus(options) {
     const stateManager = getStateManager();
     const stats = stateManager.getStats();

package/dist/commands/track.d.ts

@@ -9,9 +9,25 @@ export interface UntrackOutput {
     url: string;
     message: string;
 }
+/**
+ * Validate and fetch metadata for a PR URL.
+ *
+ * @param options - Track options
+ * @param options.prUrl - Full GitHub PR URL
+ * @returns PR metadata (repo, number, title, url)
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export declare function runTrack(options: {
     prUrl: string;
 }): Promise<TrackOutput>;
+/**
+ * No-op in v2 — PRs are fetched fresh on each daily run.
+ *
+ * @param options - Untrack options
+ * @param options.prUrl - Full GitHub PR URL
+ * @returns Message explaining v2 behavior
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export declare function runUntrack(options: {
     prUrl: string;
 }): Promise<UntrackOutput>;

package/dist/commands/track.js

@@ -6,6 +6,14 @@
 import { getOctokit, requireGitHubToken } from '../core/index.js';
 import { validateUrl, PR_URL_PATTERN, validateGitHubUrl } from './validation.js';
 import { parseGitHubUrl } from '../core/utils.js';
+/**
+ * Validate and fetch metadata for a PR URL.
+ *
+ * @param options - Track options
+ * @param options.prUrl - Full GitHub PR URL
+ * @returns PR metadata (repo, number, title, url)
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export async function runTrack(options) {
     validateUrl(options.prUrl);
     validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');
@@ -26,6 +34,14 @@ export async function runTrack(options) {
         },
     };
 }
+/**
+ * No-op in v2 — PRs are fetched fresh on each daily run.
+ *
+ * @param options - Untrack options
+ * @param options.prUrl - Full GitHub PR URL
+ * @returns Message explaining v2 behavior
+ * @throws {ValidationError} If the URL is not a valid GitHub PR URL
+ */
 export async function runUntrack(options) {
     validateUrl(options.prUrl);
     validateGitHubUrl(options.prUrl, PR_URL_PATTERN, 'PR');

package/dist/commands/vet.d.ts

@@ -7,4 +7,12 @@ export { type VetOutput } from '../formatters/json.js';
 interface VetOptions {
     issueUrl: string;
 }
+/**
+ * Vet a specific GitHub issue for claimability and project health.
+ *
+ * @param options - Vet options
+ * @param options.issueUrl - Full GitHub issue URL
+ * @returns Vetting result with recommendation, health data, and check outcomes
+ * @throws {ValidationError} If the URL is not a valid GitHub issue URL
+ */
 export declare function runVet(options: VetOptions): Promise<VetOutput>;

package/dist/commands/vet.js

@@ -4,6 +4,14 @@
  */
 import { IssueDiscovery, requireGitHubToken } from '../core/index.js';
 import { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
+/**
+ * Vet a specific GitHub issue for claimability and project health.
+ *
+ * @param options - Vet options
+ * @param options.issueUrl - Full GitHub issue URL
+ * @returns Vetting result with recommendation, health data, and check outcomes
+ * @throws {ValidationError} If the URL is not a valid GitHub issue URL
+ */
 export async function runVet(options) {
     validateUrl(options.issueUrl);
     validateGitHubUrl(options.issueUrl, ISSUE_URL_PATTERN, 'issue');

package/dist/core/daily-logic.d.ts

@@ -25,26 +25,52 @@ export declare const CRITICAL_STATUSES: ReadonlySet<FetchedPRStatus>;
 export declare const CRITICAL_ACTION_REASONS: ReadonlySet<ActionReason>;
 /** Staleness tiers indicating staleness — maintainer comments during these tiers don't count as responsive. */
 export declare const STALE_STATUSES: ReadonlySet<StalenessTier>;
+/**
+ * Apply status overrides from state to the PR list.
+ * Overrides are auto-cleared if the PR has new activity since the override was set.
+ *
+ * When an override changes the status, the contradictory reason field is cleared
+ * and an appropriate default is set so downstream logic (assessCapacity, collectActionableIssues)
+ * works correctly.
+ *
+ * @param prs - The fetched PR list to apply overrides to
+ * @param state - Current agent state containing status overrides
+ * @returns New PR array with overrides applied (original array is not mutated)
+ */
 export declare function applyStatusOverrides(prs: FetchedPR[], state: Readonly<AgentState>): FetchedPR[];
 /**
- * Map a full FetchedPR to a lightweight ShelvedPRRef for digest output.
+ * Project a PR to a lightweight ShelvedPRRef for digest output.
  * Only the fields needed for display are retained, reducing JSON payload size.
+ *
+ * @param pr - Any object with at least the ShelvedPRRef fields
+ * @returns Lightweight reference for display
  */
-export declare function toShelvedPRRef(pr: FetchedPR): ShelvedPRRef;
+export declare function toShelvedPRRef(pr: ShelvedPRRef): ShelvedPRRef;
 /**
  * Group PRs by repository (#80).
  * Ensures one agent per repo during parallel dispatch, preventing branch checkout conflicts.
+ *
+ * @param prs - PRs to group
+ * @returns Array of repo groups, each with the repo name and its PRs
  */
 export declare function groupPRsByRepo(prs: FetchedPR[]): RepoGroup[];
 /**
  * Compute per-repo maintainer signals from observed open PR data.
  * - isResponsive: true if any PR in the repo has a maintainer comment and stalenessTier is active
  * - hasActiveMaintainers: true if any non-stale PR exists in the repo (stalenessTier is 'active')
+ *
+ * @param prs - Open PRs to compute signals from
+ * @returns Map of repo names to maintainer responsiveness signals
  */
 export declare function computeRepoSignals(prs: FetchedPR[]): Map<string, ComputedRepoSignals>;
 /**
  * Assess whether user has capacity for new issues.
  * Only active (non-shelved) PRs count against the limit.
+ *
+ * @param activePRs - Non-shelved open PRs
+ * @param maxActivePRs - User's configured PR limit
+ * @param shelvedPRCount - Number of shelved PRs (for display)
+ * @returns Capacity assessment with reason string
  */
 export declare function assessCapacity(activePRs: FetchedPR[], maxActivePRs: number, shelvedPRCount: number): CapacityAssessment;
 /**
@@ -53,29 +79,56 @@ export declare function assessCapacity(activePRs: FetchedPR[], maxActivePRs: num
  *
  * Note: Recently closed PRs are informational only and excluded from this list.
  * They are available separately in digest.recentlyClosedPRs (#156).
+ *
+ * @param prs - Active (non-shelved) PRs to check
+ * @param lastDigestAt - ISO timestamp of previous digest (for "new contribution" detection)
+ * @returns Ordered actionable issues grouped by priority
  */
 export declare function collectActionableIssues(prs: FetchedPR[], lastDigestAt?: string): ActionableIssue[];
 /**
- * Format a maintainer action hint as a human-readable label
+ * Format a maintainer action hint as a human-readable label.
+ * @param hint - The maintainer action hint enum value
+ * @returns Human-readable label (e.g., "tests requested")
  */
 export declare function formatActionHint(hint: MaintainerActionHint): string;
 /**
  * Compute the action menu from PR data and capacity.
  * The orchestration layer can insert issue-list options (e.g., "Pick from list")
  * using the context flags.
+ *
+ * @param actionableIssues - Issues requiring attention
+ * @param capacity - Current capacity assessment
+ * @param commentedIssues - Issues with comment activity
+ * @returns Action menu with context flags for orchestration
  */
 export declare function computeActionMenu(actionableIssues: ActionableIssue[], capacity: CapacityAssessment, commentedIssues?: CommentedIssue[]): ActionMenu;
 /**
- * Format a brief one-liner summary for the action-first flow
+ * Format a brief one-liner summary for the action-first flow.
+ *
+ * @param digest - The daily digest containing PR summary stats
+ * @param issueCount - Number of actionable issues needing attention
+ * @param issueResponseCount - Number of issue replies from maintainers
+ * @returns One-line status string (e.g., "3 Active PRs | 1 needs attention | 2 issue replies")
  */
 export declare function formatBriefSummary(digest: DailyDigest, issueCount: number, issueResponseCount?: number): string;
 /**
- * Format summary as markdown (used in JSON output for Claude to display verbatim)
+ * Format the full dashboard summary as markdown.
+ * Used in JSON output for Claude to display verbatim — includes all PR sections,
+ * issue replies, and capacity status.
+ *
+ * @param digest - The daily digest with all PR categories
+ * @param capacity - Current capacity assessment for display
+ * @param issueResponses - Issue replies from maintainers to display
+ * @returns Multi-line markdown string suitable for terminal or chat display
  */
 export declare function formatSummary(digest: DailyDigest, capacity: CapacityAssessment, issueResponses?: CommentedIssueWithResponse[]): string;
 /**
- * Print digest to console (simple text output).
- * Unified renderer: uses the same section ordering as formatSummary
+ * Print digest to console as plain text.
+ * Unified renderer: uses the same section ordering as {@link formatSummary}
  * but outputs plain text with console.log instead of markdown links.
+ *
+ * @param digest - The daily digest with all PR categories
+ * @param capacity - Current capacity assessment for display
+ * @param commentedIssues - All commented issues (filtered to responses internally)
  */
 export declare function printDigest(digest: DailyDigest, capacity: CapacityAssessment, commentedIssues?: CommentedIssue[]): void;

package/dist/core/daily-logic.js

@@ -38,6 +38,7 @@ export const STALE_STATUSES = new Set(['dormant', 'approaching_dormant']);
 // ---------------------------------------------------------------------------
 // Status overrides
 // ---------------------------------------------------------------------------
+const VALID_OVERRIDE_STATUSES = new Set(['needs_addressing', 'waiting_on_maintainer']);
 /**
  * Apply status overrides from state to the PR list.
  * Overrides are auto-cleared if the PR has new activity since the override was set.
@@ -45,8 +46,11 @@ export const STALE_STATUSES = new Set(['dormant', 'approaching_dormant']);
  * When an override changes the status, the contradictory reason field is cleared
  * and an appropriate default is set so downstream logic (assessCapacity, collectActionableIssues)
  * works correctly.
+ *
+ * @param prs - The fetched PR list to apply overrides to
+ * @param state - Current agent state containing status overrides
+ * @returns New PR array with overrides applied (original array is not mutated)
  */
-const VALID_OVERRIDE_STATUSES = new Set(['needs_addressing', 'waiting_on_maintainer']);
 export function applyStatusOverrides(prs, state) {
     const overrides = state.config.statusOverrides;
     if (!overrides || Object.keys(overrides).length === 0)
@@ -106,8 +110,11 @@ function buildRepoMap(prs, label) {
 // Domain functions
 // ---------------------------------------------------------------------------
 /**
- * Map a full FetchedPR to a lightweight ShelvedPRRef for digest output.
+ * Project a PR to a lightweight ShelvedPRRef for digest output.
  * Only the fields needed for display are retained, reducing JSON payload size.
+ *
+ * @param pr - Any object with at least the ShelvedPRRef fields
+ * @returns Lightweight reference for display
  */
 export function toShelvedPRRef(pr) {
     return {
@@ -122,6 +129,9 @@ export function toShelvedPRRef(pr) {
 /**
  * Group PRs by repository (#80).
  * Ensures one agent per repo during parallel dispatch, preventing branch checkout conflicts.
+ *
+ * @param prs - PRs to group
+ * @returns Array of repo groups, each with the repo name and its PRs
  */
 export function groupPRsByRepo(prs) {
     const repoMap = buildRepoMap(prs, 'GROUP_BY_REPO');
@@ -135,6 +145,9 @@ export function groupPRsByRepo(prs) {
  * Compute per-repo maintainer signals from observed open PR data.
  * - isResponsive: true if any PR in the repo has a maintainer comment and stalenessTier is active
  * - hasActiveMaintainers: true if any non-stale PR exists in the repo (stalenessTier is 'active')
+ *
+ * @param prs - Open PRs to compute signals from
+ * @returns Map of repo names to maintainer responsiveness signals
  */
 export function computeRepoSignals(prs) {
     const repoMap = buildRepoMap(prs, 'COMPUTE_SIGNALS');
@@ -149,6 +162,11 @@ export function computeRepoSignals(prs) {
 /**
  * Assess whether user has capacity for new issues.
  * Only active (non-shelved) PRs count against the limit.
+ *
+ * @param activePRs - Non-shelved open PRs
+ * @param maxActivePRs - User's configured PR limit
+ * @param shelvedPRCount - Number of shelved PRs (for display)
+ * @returns Capacity assessment with reason string
  */
 export function assessCapacity(activePRs, maxActivePRs, shelvedPRCount) {
     const activePRCount = activePRs.length;
@@ -188,6 +206,10 @@ export function assessCapacity(activePRs, maxActivePRs, shelvedPRCount) {
  *
  * Note: Recently closed PRs are informational only and excluded from this list.
  * They are available separately in digest.recentlyClosedPRs (#156).
+ *
+ * @param prs - Active (non-shelved) PRs to check
+ * @param lastDigestAt - ISO timestamp of previous digest (for "new contribution" detection)
+ * @returns Ordered actionable issues grouped by priority
  */
 export function collectActionableIssues(prs, lastDigestAt) {
     const issues = [];
@@ -256,7 +278,9 @@ export function collectActionableIssues(prs, lastDigestAt) {
     return issues;
 }
 /**
- * Format a maintainer action hint as a human-readable label
+ * Format a maintainer action hint as a human-readable label.
+ * @param hint - The maintainer action hint enum value
+ * @returns Human-readable label (e.g., "tests requested")
  */
 export function formatActionHint(hint) {
     switch (hint) {
@@ -276,6 +300,11 @@ export function formatActionHint(hint) {
  * Compute the action menu from PR data and capacity.
  * The orchestration layer can insert issue-list options (e.g., "Pick from list")
  * using the context flags.
+ *
+ * @param actionableIssues - Issues requiring attention
+ * @param capacity - Current capacity assessment
+ * @param commentedIssues - Issues with comment activity
+ * @returns Action menu with context flags for orchestration
  */
 export function computeActionMenu(actionableIssues, capacity, commentedIssues = []) {
     const issueResponses = commentedIssues.filter((i) => i.status === 'new_response');
@@ -329,7 +358,12 @@ export function computeActionMenu(actionableIssues, capacity, commentedIssues =
 // Rendering / formatting
 // ---------------------------------------------------------------------------
 /**
- * Format a brief one-liner summary for the action-first flow
+ * Format a brief one-liner summary for the action-first flow.
+ *
+ * @param digest - The daily digest containing PR summary stats
+ * @param issueCount - Number of actionable issues needing attention
+ * @param issueResponseCount - Number of issue replies from maintainers
+ * @returns One-line status string (e.g., "3 Active PRs | 1 needs attention | 2 issue replies")
  */
 export function formatBriefSummary(digest, issueCount, issueResponseCount = 0) {
     const attentionText = issueCount > 0 ? `${issueCount} need${issueCount === 1 ? 's' : ''} attention` : 'all on track';
@@ -337,7 +371,14 @@ export function formatBriefSummary(digest, issueCount, issueResponseCount = 0) {
     return `\u{1F4CA} ${digest.summary.totalActivePRs} Active PRs | ${attentionText}${issueReplyText}`;
 }
 /**
- * Format summary as markdown (used in JSON output for Claude to display verbatim)
+ * Format the full dashboard summary as markdown.
+ * Used in JSON output for Claude to display verbatim — includes all PR sections,
+ * issue replies, and capacity status.
+ *
+ * @param digest - The daily digest with all PR categories
+ * @param capacity - Current capacity assessment for display
+ * @param issueResponses - Issue replies from maintainers to display
+ * @returns Multi-line markdown string suitable for terminal or chat display
  */
 export function formatSummary(digest, capacity, issueResponses = []) {
     const lines = [];
@@ -418,9 +459,13 @@ export function formatSummary(digest, capacity, issueResponses = []) {
     return lines.join('\n');
 }
 /**
- * Print digest to console (simple text output).
- * Unified renderer: uses the same section ordering as formatSummary
+ * Print digest to console as plain text.
+ * Unified renderer: uses the same section ordering as {@link formatSummary}
  * but outputs plain text with console.log instead of markdown links.
+ *
+ * @param digest - The daily digest with all PR categories
+ * @param capacity - Current capacity assessment for display
+ * @param commentedIssues - All commented issues (filtered to responses internally)
  */
 export function printDigest(digest, capacity, commentedIssues = []) {
     console.log('\n\u{1F4CA} OSS Daily Check\n');

package/dist/core/formatter-detection.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Formatter Detection Module (#703)
+ *
+ * Programmatically detects formatters/linters configured in a local repo directory
+ * and diagnoses CI formatting failures from log output.
+ */
+export type FormatterName = 'prettier' | 'eslint' | 'biome' | 'black' | 'ruff' | 'rustfmt' | 'gofmt' | 'clang-format' | 'rubocop';
+export interface DetectedFormatter {
+    name: FormatterName;
+    /** Relative to repo root */
+    configPath: string;
+    /** e.g., "npx prettier --write ." */
+    fixCommand: string;
+    /** e.g., "npx prettier --check ." */
+    checkCommand: string;
+    /** Whether the formatter accepts individual file paths as arguments */
+    supportsFileArgs: boolean;
+}
+export interface FormatterDetectionResult {
+    formatters: DetectedFormatter[];
+    packageJsonScripts: {
+        name: string;
+        command: string;
+    }[];
+    repoPath: string;
+}
+export interface CIFormatterDiagnosis {
+    isFormattingFailure: boolean;
+    formatter?: FormatterName;
+    fixCommand?: string;
+    evidence: string[];
+}
+/**
+ * Detect formatters and linters configured in a repository.
+ *
+ * Checks config files in priority order using fs.existsSync() / fs.readFileSync().
+ * Returns all detected formatters, plus any formatting-related package.json scripts.
+ *
+ * @param repoPath - Absolute path to the repository root directory
+ * @returns Detection result with formatters ordered by priority and extracted package.json scripts
+ * @throws {Error} If repoPath does not exist or is not a directory
+ */
+export declare function detectFormatters(repoPath: string): FormatterDetectionResult;
+/**
+ * Diagnose whether CI log output indicates a formatting failure.
+ *
+ * Pattern-matches known formatter error strings. When repoPath is provided,
+ * cross-references with {@link detectFormatters} to provide a targeted fix command.
+ *
+ * @param logOutput - Raw CI log output to analyze
+ * @param repoPath - Optional repo path for cross-referencing with local formatter config
+ * @returns Diagnosis with matched formatter, fix command, and evidence strings
+ */
+export declare function diagnoseCIFormatterFailure(logOutput: string, repoPath?: string): CIFormatterDiagnosis;
+/**
+ * Return the first (highest-priority) detected formatter, or undefined if none found.
+ *
+ * @param result - Detection result from {@link detectFormatters}
+ * @returns The highest-priority formatter, or undefined if none detected
+ */
+export declare function getPreferredFormatter(result: FormatterDetectionResult): DetectedFormatter | undefined;