@oss-autopilot/core 1.17.4 → 3.0.0

package/dist/formatters/json.d.ts

@@ -2,11 +2,13 @@
  * JSON output formatter for CLI --json mode
  * Provides structured output that can be consumed by scripts and plugins
  */
+import { z, type ZodType } from 'zod';
 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/types.js';
+import type { SearchPriority, CapacityAssessment, ActionableIssue, ActionableIssueType, CompactActionableIssue, ActionMenuItem, ActionMenu } from '../core/types.js';
 import type { CIFormatterDiagnosis, FormatterDetectionResult } from '../core/formatter-detection.js';
+export type { CapacityAssessment, ActionableIssue, ActionableIssueType, CompactActionableIssue, ActionMenuItem, ActionMenu, };
 export type ErrorCode = 'AUTH_REQUIRED' | 'RATE_LIMITED' | 'VALIDATION' | 'CONFIGURATION' | 'NETWORK' | 'NOT_FOUND' | 'STATE_CORRUPTED' | 'CONCURRENCY' | 'UNKNOWN';
 export interface JsonOutput<T = unknown> {
     success: boolean;
@@ -15,66 +17,6 @@ export interface JsonOutput<T = unknown> {
     errorCode?: ErrorCode;
     timestamp: string;
 }
-export interface CapacityAssessment {
-    hasCapacity: boolean;
-    activePRCount: number;
-    maxActivePRs: number;
-    shelvedPRCount: number;
-    criticalIssueCount: number;
-    reason: string;
-}
-export type ActionableIssueType = 'ci_failing' | 'merge_conflict' | 'needs_response' | 'needs_changes' | 'incomplete_checklist';
-export interface ActionableIssue {
-    type: ActionableIssueType;
-    pr: FetchedPR;
-    label: string;
-    /** True if the PR was created after the last daily digest (first time seen). */
-    isNewContribution: boolean;
-}
-/**
- * Compact version of ActionableIssue for JSON output.
- * References the PR by URL instead of embedding the full object,
- * since the full PR is already available in digest.openPRs.
- * Uses URL (globally unique) instead of number to avoid cross-repo collisions.
- */
-export interface CompactActionableIssue {
-    type: ActionableIssueType;
-    prUrl: string;
-    label: string;
-    /** True if the PR was created after the last daily digest (first time seen). */
-    isNewContribution: boolean;
-}
-/**
- * A single action menu item pre-computed by the CLI.
- * The orchestration layer can use these directly in AskUserQuestion prompts.
- */
-export interface ActionMenuItem {
-    /** Stable identifier for routing (e.g., "address_all", "search", "done"). */
-    key: string;
-    /** Display text for the option (e.g., "Work through all 3 issues (Recommended)"). */
-    label: string;
-    /** Explanation shown below the label. */
-    description: string;
-    /** Present when the action would exceed the user's PR capacity limit (#765). */
-    capacityWarning?: string;
-}
-/**
- * Pre-computed action menu for the orchestration layer.
- * Contains the menu items the CLI can determine from PR data and capacity,
- * plus context flags so the orchestration can insert issue-list options.
- */
-export interface ActionMenu {
-    /** Ordered list of menu items. The orchestration may insert issue-list items after the CLI-generated items (address_all, issue_replies) or at the start when none exist. */
-    items: ActionMenuItem[];
-    /** Context flags for the orchestration layer to decide on issue-list options. */
-    context: {
-        hasActionableIssues: boolean;
-        actionableCount: number;
-        hasCapacity: boolean;
-        hasIssueResponses: boolean;
-        issueResponseCount: number;
-    };
-}
 /**
  * Deduplicated daily digest for JSON output (#287).
  *
@@ -185,19 +127,444 @@ export declare function compactActionableIssues(issues: ActionableIssue[]): Comp
  * Replaces full PR arrays with PR URL arrays.
  */
 export declare function compactRepoGroups(groups: RepoGroup[]): CompactRepoGroup[];
-export interface StatusOutput {
-    stats: {
-        mergedPRs: number;
-        closedPRs: number;
-        activeIssues: number;
-        trustedProjects: number;
-        mergeRate: string;
-        needsResponse: number;
-    };
-    lastRunAt: string;
-    offline?: boolean;
-    lastUpdated?: string;
-}
+export declare const StatusOutputSchema: z.ZodObject<{
+    stats: z.ZodObject<{
+        mergedPRs: z.ZodNumber;
+        closedPRs: z.ZodNumber;
+        activeIssues: z.ZodNumber;
+        trustedProjects: z.ZodNumber;
+        mergeRate: z.ZodString;
+        needsResponse: z.ZodNumber;
+    }, z.core.$strip>;
+    lastRunAt: z.ZodString;
+    offline: z.ZodOptional<z.ZodBoolean>;
+    lastUpdated: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StatusOutput = z.infer<typeof StatusOutputSchema>;
+export declare const DailyOutputSchema: z.ZodObject<{
+    digest: z.ZodObject<{
+        generatedAt: z.ZodString;
+        openPRs: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        needsAddressingPRs: z.ZodArray<z.ZodString>;
+        waitingOnMaintainerPRs: z.ZodArray<z.ZodString>;
+        recentlyClosedPRs: z.ZodArray<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            title: z.ZodString;
+            closedAt: z.ZodString;
+        }, z.core.$strip>>;
+        recentlyMergedPRs: z.ZodArray<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            title: z.ZodString;
+            mergedAt: z.ZodString;
+        }, z.core.$strip>>;
+        shelvedPRs: z.ZodArray<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            title: z.ZodString;
+            repo: z.ZodString;
+            daysSinceActivity: z.ZodNumber;
+            status: z.ZodString;
+        }, z.core.$strip>>;
+        autoUnshelvedPRs: z.ZodArray<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            title: z.ZodString;
+            repo: z.ZodString;
+            daysSinceActivity: z.ZodNumber;
+            status: z.ZodString;
+        }, z.core.$strip>>;
+        summary: z.ZodObject<{
+            totalActivePRs: z.ZodNumber;
+            totalNeedingAttention: z.ZodNumber;
+            totalMergedAllTime: z.ZodNumber;
+            mergeRate: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    capacity: z.ZodObject<{
+        hasCapacity: z.ZodBoolean;
+        activePRCount: z.ZodNumber;
+        maxActivePRs: z.ZodNumber;
+        shelvedPRCount: z.ZodNumber;
+        criticalIssueCount: z.ZodNumber;
+        reason: z.ZodString;
+    }, z.core.$strip>;
+    summary: z.ZodString;
+    briefSummary: z.ZodString;
+    actionableIssues: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            needs_response: "needs_response";
+            needs_changes: "needs_changes";
+            merge_conflict: "merge_conflict";
+            incomplete_checklist: "incomplete_checklist";
+            ci_failing: "ci_failing";
+        }>;
+        prUrl: z.ZodString;
+        label: z.ZodString;
+        isNewContribution: z.ZodBoolean;
+    }, z.core.$strip>>;
+    actionMenu: z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodString;
+            capacityWarning: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        context: z.ZodObject<{
+            hasActionableIssues: z.ZodBoolean;
+            actionableCount: z.ZodNumber;
+            hasCapacity: z.ZodBoolean;
+            hasIssueResponses: z.ZodBoolean;
+            issueResponseCount: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    commentedIssues: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    repoGroups: z.ZodArray<z.ZodObject<{
+        repo: z.ZodString;
+        prUrls: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    failures: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    warnings: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            fetch: "fetch";
+            "repo-scores": "repo-scores";
+            analytics: "analytics";
+            "scout-sync": "scout-sync";
+            partition: "partition";
+            "dismiss-filter": "dismiss-filter";
+            "gist-checkpoint": "gist-checkpoint";
+        }>;
+        operation: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const CompactDailyOutputSchema: z.ZodObject<{
+    digest: z.ZodObject<{
+        generatedAt: z.ZodString;
+        openPRs: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        needsAddressingPRs: z.ZodArray<z.ZodString>;
+        waitingOnMaintainerPRs: z.ZodArray<z.ZodString>;
+        recentlyClosedPRs: z.ZodArray<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            title: z.ZodString;
+            closedAt: z.ZodString;
+        }, z.core.$strip>>;
+        recentlyMergedPRs: z.ZodArray<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            title: z.ZodString;
+            mergedAt: z.ZodString;
+        }, z.core.$strip>>;
+        shelvedPRs: z.ZodArray<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            title: z.ZodString;
+            repo: z.ZodString;
+            daysSinceActivity: z.ZodNumber;
+            status: z.ZodString;
+        }, z.core.$strip>>;
+        autoUnshelvedPRs: z.ZodArray<z.ZodObject<{
+            number: z.ZodNumber;
+            url: z.ZodString;
+            title: z.ZodString;
+            repo: z.ZodString;
+            daysSinceActivity: z.ZodNumber;
+            status: z.ZodString;
+        }, z.core.$strip>>;
+        summary: z.ZodObject<{
+            totalActivePRs: z.ZodNumber;
+            totalNeedingAttention: z.ZodNumber;
+            totalMergedAllTime: z.ZodNumber;
+            mergeRate: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    capacity: z.ZodObject<{
+        hasCapacity: z.ZodBoolean;
+        activePRCount: z.ZodNumber;
+        maxActivePRs: z.ZodNumber;
+        shelvedPRCount: z.ZodNumber;
+        criticalIssueCount: z.ZodNumber;
+        reason: z.ZodString;
+    }, z.core.$strip>;
+    briefSummary: z.ZodString;
+    actionableIssues: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            needs_response: "needs_response";
+            needs_changes: "needs_changes";
+            merge_conflict: "merge_conflict";
+            incomplete_checklist: "incomplete_checklist";
+            ci_failing: "ci_failing";
+        }>;
+        prUrl: z.ZodString;
+        label: z.ZodString;
+        isNewContribution: z.ZodBoolean;
+    }, z.core.$strip>>;
+    actionMenu: z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodString;
+            capacityWarning: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        context: z.ZodObject<{
+            hasActionableIssues: z.ZodBoolean;
+            actionableCount: z.ZodNumber;
+            hasCapacity: z.ZodBoolean;
+            hasIssueResponses: z.ZodBoolean;
+            issueResponseCount: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    commentedIssues: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    failureCount: z.ZodNumber;
+    warnings: z.ZodArray<z.ZodObject<{
+        phase: z.ZodEnum<{
+            fetch: "fetch";
+            "repo-scores": "repo-scores";
+            analytics: "analytics";
+            "scout-sync": "scout-sync";
+            partition: "partition";
+            "dismiss-filter": "dismiss-filter";
+            "gist-checkpoint": "gist-checkpoint";
+        }>;
+        operation: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const SearchOutputSchema: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        issue: z.ZodObject<{
+            repo: z.ZodString;
+            repoUrl: z.ZodString;
+            number: z.ZodNumber;
+            title: z.ZodString;
+            url: z.ZodString;
+            labels: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        recommendation: z.ZodEnum<{
+            approve: "approve";
+            skip: "skip";
+            needs_review: "needs_review";
+        }>;
+        reasonsToApprove: z.ZodArray<z.ZodString>;
+        reasonsToSkip: z.ZodArray<z.ZodString>;
+        searchPriority: z.ZodEnum<{
+            normal: "normal";
+            merged_pr: "merged_pr";
+            preferred_org: "preferred_org";
+            starred: "starred";
+        }>;
+        viabilityScore: z.ZodNumber;
+        grade: z.ZodObject<{
+            letter: z.ZodEnum<{
+                A: "A";
+                B: "B";
+                C: "C";
+                F: "F";
+            }>;
+            reason: z.ZodString;
+        }, z.core.$strip>;
+        repoScore: z.ZodOptional<z.ZodObject<{
+            score: z.ZodNumber;
+            mergedPRCount: z.ZodNumber;
+            closedWithoutMergeCount: z.ZodNumber;
+            isResponsive: z.ZodBoolean;
+            lastMergedAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    excludedRepos: z.ZodArray<z.ZodString>;
+    aiPolicyBlocklist: z.ZodArray<z.ZodString>;
+    rateLimitWarning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const DoctorOutputSchema: z.ZodObject<{
+    checks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        status: z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+            warning: "warning";
+        }>;
+        message: z.ZodString;
+        remediation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    summary: z.ZodObject<{
+        ok: z.ZodNumber;
+        warnings: z.ZodNumber;
+        errors: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const SkipAddOutputSchema: z.ZodObject<{
+    added: z.ZodBoolean;
+    alreadyPresent: z.ZodBoolean;
+    url: z.ZodString;
+    path: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ListMoveTierOutputSchema: z.ZodObject<{
+    moved: z.ZodBoolean;
+    filePath: z.ZodString;
+    url: z.ZodString;
+    toTier: z.ZodEnum<{
+        maybe: "maybe";
+        skip: "skip";
+        pursue: "pursue";
+    }>;
+    fromTier: z.ZodOptional<z.ZodString>;
+    count: z.ZodNumber;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const PostOutputSchema: z.ZodObject<{
+    commentUrl: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+export declare const ClaimOutputSchema: z.ZodObject<{
+    commentUrl: z.ZodString;
+    issueUrl: z.ZodString;
+}, z.core.$strip>;
+export declare const InitOutputSchema: z.ZodObject<{
+    username: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare const CheckSetupOutputSchema: z.ZodObject<{
+    setupComplete: z.ZodBoolean;
+    username: z.ZodString;
+}, z.core.$strip>;
+export declare const SetupOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    settings: z.ZodRecord<z.ZodString, z.ZodString>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    setupComplete: z.ZodLiteral<true>;
+    config: z.ZodObject<{
+        githubUsername: z.ZodString;
+        maxActivePRs: z.ZodNumber;
+        dormantThresholdDays: z.ZodNumber;
+        approachingDormantDays: z.ZodNumber;
+        languages: z.ZodArray<z.ZodString>;
+        labels: z.ZodArray<z.ZodString>;
+        projectCategories: z.ZodArray<z.ZodString>;
+        preferredOrgs: z.ZodArray<z.ZodString>;
+        scope: z.ZodArray<z.ZodString>;
+        persistence: z.ZodEnum<{
+            local: "local";
+            gist: "gist";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    setupRequired: z.ZodLiteral<true>;
+    prompts: z.ZodArray<z.ZodObject<{
+        setting: z.ZodString;
+        prompt: z.ZodString;
+        current: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodArray<z.ZodString>, z.ZodNull]>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>;
+export declare const ConfigCommandOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    key: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    keys: z.ZodArray<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$strip>]>;
+export declare const MoveOutputSchema: z.ZodObject<{
+    url: z.ZodString;
+    target: z.ZodEnum<{
+        auto: "auto";
+        waiting: "waiting";
+        attention: "attention";
+        shelved: "shelved";
+    }>;
+    description: z.ZodString;
+}, z.core.$strip>;
+export declare const PRTemplateOutputSchema: z.ZodObject<{
+    template: z.ZodNullable<z.ZodString>;
+    source: z.ZodNullable<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ParseIssueListOutputSchema: z.ZodObject<{
+    available: z.ZodArray<z.ZodObject<{
+        repo: z.ZodString;
+        number: z.ZodNumber;
+        title: z.ZodString;
+        tier: z.ZodString;
+        url: z.ZodString;
+        score: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    completed: z.ZodArray<z.ZodObject<{
+        repo: z.ZodString;
+        number: z.ZodNumber;
+        title: z.ZodString;
+        tier: z.ZodString;
+        url: z.ZodString;
+        score: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    availableCount: z.ZodNumber;
+    completedCount: z.ZodNumber;
+}, z.core.$strip>;
+export declare const CheckIntegrationOutputSchema: z.ZodObject<{
+    newFiles: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        referencedBy: z.ZodArray<z.ZodString>;
+        isIntegrated: z.ZodBoolean;
+        suggestedEntryPoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    unreferencedCount: z.ZodNumber;
+}, z.core.$strip>;
+export declare const DetectFormattersOutputSchema: z.ZodObject<{
+    formatters: z.ZodArray<z.ZodObject<{
+        name: z.ZodEnum<{
+            prettier: "prettier";
+            eslint: "eslint";
+            biome: "biome";
+            black: "black";
+            ruff: "ruff";
+            rustfmt: "rustfmt";
+            gofmt: "gofmt";
+            "clang-format": "clang-format";
+            rubocop: "rubocop";
+        }>;
+        configPath: z.ZodString;
+        fixCommand: z.ZodString;
+        checkCommand: z.ZodString;
+        supportsFileArgs: z.ZodBoolean;
+    }, z.core.$strip>>;
+    packageJsonScripts: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+    }, z.core.$strip>>;
+    repoPath: z.ZodString;
+    ciDiagnosis: z.ZodOptional<z.ZodObject<{
+        isFormattingFailure: z.ZodBoolean;
+        formatter: z.ZodOptional<z.ZodEnum<{
+            prettier: "prettier";
+            eslint: "eslint";
+            biome: "biome";
+            black: "black";
+            ruff: "ruff";
+            rustfmt: "rustfmt";
+            gofmt: "gofmt";
+            "clang-format": "clang-format";
+            rubocop: "rubocop";
+        }>>;
+        fixCommand: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const LocalReposOutputSchema: z.ZodObject<{
+    repos: z.ZodRecord<z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        exists: z.ZodBoolean;
+        currentBranch: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    scanPaths: z.ZodArray<z.ZodString>;
+    cachedAt: z.ZodString;
+    fromCache: z.ZodBoolean;
+}, z.core.$strip>;
 export interface SearchOutput {
     candidates: Array<{
         issue: {
@@ -445,3 +812,26 @@ export declare function outputJson<T>(data: T): void;
  * Output error JSON to stdout (sets success: false)
  */
 export declare function outputJsonError(message: string, errorCode?: ErrorCode): void;
+/**
+ * Validate `data` against a Zod schema and wrap the result in the standard
+ * JSON output envelope (#1105 long-term ask from #965).
+ *
+ * Throws a contract-drift `Error` if `data` doesn't match the schema. The
+ * error's message lists the failing field paths so a developer can find the
+ * drift quickly. Use this at the `--json` boundary of every CLI command —
+ * whenever the producer adds, renames, or drops a field that doesn't match
+ * the schema, the test harness fails immediately rather than silently
+ * shipping a contract break to consumers (plugin layer, MCP server,
+ * downstream scripts).
+ *
+ * @example
+ *   import { formatJson, StatusOutputSchema } from '../formatters/json.js';
+ *   const envelope = formatJson(StatusOutputSchema, await runStatus());
+ *   console.log(JSON.stringify(envelope, null, 2));
+ */
+export declare function formatJson<T>(schema: ZodType<T>, data: unknown): JsonOutput<T>;
+/**
+ * `outputJson(data)` plus Zod validation. Same throwing semantics as
+ * {@link formatJson}; the validated envelope is what gets printed.
+ */
+export declare function outputJsonValidated<T>(schema: ZodType<T>, data: unknown): void;