@oss-autopilot/core 1.17.4 → 3.0.0

package/dist/formatters/json.js

@@ -2,6 +2,7 @@
  * JSON output formatter for CLI --json mode
  * Provides structured output that can be consumed by scripts and plugins
  */
+import { z } from 'zod';
 /**
  * Strip a full DailyOutput down to the compact subset (#763).
  * Omits summary, repoGroups, and full failures array. Retains a failureCount
@@ -60,6 +61,351 @@ export function compactRepoGroups(groups) {
         prUrls: group.prs.map((pr) => pr.url),
     }));
 }
+export const StatusOutputSchema = z.object({
+    stats: z.object({
+        mergedPRs: z.number().int().nonnegative(),
+        closedPRs: z.number().int().nonnegative(),
+        activeIssues: z.number().int().nonnegative(),
+        trustedProjects: z.number().int().nonnegative(),
+        mergeRate: z.string(),
+        needsResponse: z.number().int().nonnegative(),
+    }),
+    lastRunAt: z.string(),
+    offline: z.boolean().optional(),
+    lastUpdated: z.string().optional(),
+});
+// ── Daily output schemas (#1146) ─────────────────────────────────────
+//
+// FetchedPR / CommentedIssue / PRCheckFailure are large heterogeneous shapes
+// whose state-schema counterparts already use `z.any()` / pass-through
+// validation. We mirror that here — strict on the wrapper (so drift in
+// top-level keys / category arrays surfaces immediately) and tolerant on the
+// opaque payload entries.
+const FetchedPRPassthroughSchema = z.record(z.string(), z.unknown());
+const CommentedIssuePassthroughSchema = z.record(z.string(), z.unknown());
+const PRCheckFailurePassthroughSchema = z.record(z.string(), z.unknown());
+const ShelvedPRRefStrictSchema = z.object({
+    number: z.number(),
+    url: z.string(),
+    title: z.string(),
+    repo: z.string(),
+    daysSinceActivity: z.number(),
+    status: z.string(),
+});
+const RecentClosedPRSchema = z.object({
+    number: z.number(),
+    url: z.string(),
+    title: z.string(),
+    closedAt: z.string(),
+});
+const RecentMergedPRSchema = z.object({
+    number: z.number(),
+    url: z.string(),
+    title: z.string(),
+    mergedAt: z.string(),
+});
+const DailyDigestSummarySchemaStrict = z.object({
+    totalActivePRs: z.number(),
+    totalNeedingAttention: z.number(),
+    totalMergedAllTime: z.number(),
+    mergeRate: z.number(),
+});
+const DailyDigestCompactSchema = z.object({
+    generatedAt: z.string(),
+    openPRs: z.array(FetchedPRPassthroughSchema),
+    needsAddressingPRs: z.array(z.string()),
+    waitingOnMaintainerPRs: z.array(z.string()),
+    recentlyClosedPRs: z.array(RecentClosedPRSchema),
+    recentlyMergedPRs: z.array(RecentMergedPRSchema),
+    shelvedPRs: z.array(ShelvedPRRefStrictSchema),
+    autoUnshelvedPRs: z.array(ShelvedPRRefStrictSchema),
+    summary: DailyDigestSummarySchemaStrict,
+});
+const CapacityAssessmentSchema = z.object({
+    hasCapacity: z.boolean(),
+    activePRCount: z.number().int().nonnegative(),
+    maxActivePRs: z.number().int().nonnegative(),
+    shelvedPRCount: z.number().int().nonnegative(),
+    criticalIssueCount: z.number().int().nonnegative(),
+    reason: z.string(),
+});
+const ActionableIssueTypeSchema = z.enum([
+    'ci_failing',
+    'merge_conflict',
+    'needs_response',
+    'needs_changes',
+    'incomplete_checklist',
+]);
+const CompactActionableIssueSchema = z.object({
+    type: ActionableIssueTypeSchema,
+    prUrl: z.string(),
+    label: z.string(),
+    isNewContribution: z.boolean(),
+});
+const ActionMenuItemSchema = z.object({
+    key: z.string(),
+    label: z.string(),
+    description: z.string(),
+    capacityWarning: z.string().optional(),
+});
+const ActionMenuSchema = z.object({
+    items: z.array(ActionMenuItemSchema),
+    context: z.object({
+        hasActionableIssues: z.boolean(),
+        actionableCount: z.number().int().nonnegative(),
+        hasCapacity: z.boolean(),
+        hasIssueResponses: z.boolean(),
+        issueResponseCount: z.number().int().nonnegative(),
+    }),
+});
+const CompactRepoGroupSchema = z.object({
+    repo: z.string(),
+    prUrls: z.array(z.string()),
+});
+const DailyWarningPhaseSchema = z.enum([
+    'fetch',
+    'repo-scores',
+    'analytics',
+    'scout-sync',
+    'partition',
+    'dismiss-filter',
+    'gist-checkpoint',
+]);
+const DailyWarningSchema = z.object({
+    phase: DailyWarningPhaseSchema,
+    operation: z.string(),
+    message: z.string(),
+});
+export const DailyOutputSchema = z.object({
+    digest: DailyDigestCompactSchema,
+    capacity: CapacityAssessmentSchema,
+    summary: z.string(),
+    briefSummary: z.string(),
+    actionableIssues: z.array(CompactActionableIssueSchema),
+    actionMenu: ActionMenuSchema,
+    commentedIssues: z.array(CommentedIssuePassthroughSchema),
+    repoGroups: z.array(CompactRepoGroupSchema),
+    failures: z.array(PRCheckFailurePassthroughSchema),
+    warnings: z.array(DailyWarningSchema),
+});
+export const CompactDailyOutputSchema = z.object({
+    digest: DailyDigestCompactSchema,
+    capacity: CapacityAssessmentSchema,
+    briefSummary: z.string(),
+    actionableIssues: z.array(CompactActionableIssueSchema),
+    actionMenu: ActionMenuSchema,
+    commentedIssues: z.array(CommentedIssuePassthroughSchema),
+    failureCount: z.number().int().nonnegative(),
+    warnings: z.array(DailyWarningSchema),
+});
+// ── Search output schema (#1147) ─────────────────────────────────────
+const SearchPrioritySchema = z.enum(['merged_pr', 'preferred_org', 'starred', 'normal']);
+const SearchCandidateSchema = z.object({
+    issue: z.object({
+        repo: z.string(),
+        repoUrl: z.string(),
+        number: z.number().int(),
+        title: z.string(),
+        url: z.string(),
+        labels: z.array(z.string()),
+    }),
+    recommendation: z.enum(['approve', 'skip', 'needs_review']),
+    reasonsToApprove: z.array(z.string()),
+    reasonsToSkip: z.array(z.string()),
+    searchPriority: SearchPrioritySchema,
+    viabilityScore: z.number(),
+    grade: z.object({
+        letter: z.enum(['A', 'B', 'C', 'F']),
+        reason: z.string(),
+    }),
+    repoScore: z
+        .object({
+        score: z.number(),
+        mergedPRCount: z.number().int().nonnegative(),
+        closedWithoutMergeCount: z.number().int().nonnegative(),
+        isResponsive: z.boolean(),
+        lastMergedAt: z.string().optional(),
+    })
+        .optional(),
+});
+export const SearchOutputSchema = z.object({
+    candidates: z.array(SearchCandidateSchema),
+    excludedRepos: z.array(z.string()),
+    aiPolicyBlocklist: z.array(z.string()),
+    rateLimitWarning: z.string().optional(),
+});
+// ── Doctor / skip-add / list-move-tier output schemas (#1148) ────────
+const DoctorCheckSchema = z.object({
+    name: z.string(),
+    status: z.enum(['ok', 'warning', 'error']),
+    message: z.string(),
+    remediation: z.string().optional(),
+});
+export const DoctorOutputSchema = z.object({
+    checks: z.array(DoctorCheckSchema),
+    summary: z.object({
+        ok: z.number().int().nonnegative(),
+        warnings: z.number().int().nonnegative(),
+        errors: z.number().int().nonnegative(),
+    }),
+});
+export const SkipAddOutputSchema = z.object({
+    added: z.boolean(),
+    alreadyPresent: z.boolean(),
+    url: z.string(),
+    path: z.string(),
+    date: z.string().optional(),
+});
+export const ListMoveTierOutputSchema = z.object({
+    moved: z.boolean(),
+    filePath: z.string(),
+    url: z.string(),
+    toTier: z.enum(['pursue', 'maybe', 'skip']),
+    fromTier: z.string().optional(),
+    count: z.number().int().nonnegative(),
+    reason: z.string().optional(),
+});
+// ── #1155: Zod coverage for remaining CLI commands ───────────────────
+export const PostOutputSchema = z.object({
+    commentUrl: z.string(),
+    url: z.string(),
+});
+export const ClaimOutputSchema = z.object({
+    commentUrl: z.string(),
+    issueUrl: z.string(),
+});
+export const InitOutputSchema = z.object({
+    username: z.string(),
+    message: z.string(),
+});
+export const CheckSetupOutputSchema = z.object({
+    setupComplete: z.boolean(),
+    username: z.string(),
+});
+const SetupSetOutputSchema = z.object({
+    success: z.literal(true),
+    settings: z.record(z.string(), z.string()),
+    warnings: z.array(z.string()).optional(),
+});
+const SetupCompleteOutputSchema = z.object({
+    setupComplete: z.literal(true),
+    config: z.object({
+        githubUsername: z.string(),
+        maxActivePRs: z.number(),
+        dormantThresholdDays: z.number(),
+        approachingDormantDays: z.number(),
+        languages: z.array(z.string()),
+        labels: z.array(z.string()),
+        projectCategories: z.array(z.string()),
+        preferredOrgs: z.array(z.string()),
+        scope: z.array(z.string()),
+        persistence: z.enum(['local', 'gist']),
+    }),
+});
+const SetupRequiredOutputSchema = z.object({
+    setupRequired: z.literal(true),
+    prompts: z.array(z.object({
+        setting: z.string(),
+        prompt: z.string(),
+        current: z.union([z.string(), z.number(), z.array(z.string()), z.null()]),
+        required: z.boolean().optional(),
+        default: z.union([z.string(), z.number(), z.array(z.string())]).optional(),
+        type: z.string().optional(),
+    })),
+});
+export const SetupOutputSchema = z.union([SetupSetOutputSchema, SetupCompleteOutputSchema, SetupRequiredOutputSchema]);
+const ConfigKeyDefSchema = z.object({}).passthrough();
+const ConfigGetOutputSchema = z.object({
+    config: z.record(z.string(), z.unknown()),
+});
+const ConfigSetOutputSchema = z.object({
+    success: z.literal(true),
+    key: z.string(),
+    value: z.string(),
+});
+const ConfigListKeysOutputSchema = z.object({
+    keys: z.array(ConfigKeyDefSchema),
+});
+export const ConfigCommandOutputSchema = z.union([
+    ConfigGetOutputSchema,
+    ConfigSetOutputSchema,
+    ConfigListKeysOutputSchema,
+]);
+export const MoveOutputSchema = z.object({
+    url: z.string(),
+    target: z.enum(['attention', 'waiting', 'shelved', 'auto']),
+    description: z.string(),
+});
+export const PRTemplateOutputSchema = z.object({
+    template: z.string().nullable(),
+    source: z.string().nullable(),
+    error: z.string().optional(),
+});
+const ParsedIssueItemSchema = z.object({
+    repo: z.string(),
+    number: z.number(),
+    title: z.string(),
+    tier: z.string(),
+    url: z.string(),
+    score: z.number().optional(),
+});
+export const ParseIssueListOutputSchema = z.object({
+    available: z.array(ParsedIssueItemSchema),
+    completed: z.array(ParsedIssueItemSchema),
+    availableCount: z.number().int().nonnegative(),
+    completedCount: z.number().int().nonnegative(),
+});
+const NewFileInfoSchema = z.object({
+    path: z.string(),
+    referencedBy: z.array(z.string()),
+    isIntegrated: z.boolean(),
+    suggestedEntryPoints: z.array(z.string()).optional(),
+});
+export const CheckIntegrationOutputSchema = z.object({
+    newFiles: z.array(NewFileInfoSchema),
+    unreferencedCount: z.number().int().nonnegative(),
+});
+const FormatterNameSchema = z.enum([
+    'prettier',
+    'eslint',
+    'biome',
+    'black',
+    'ruff',
+    'rustfmt',
+    'gofmt',
+    'clang-format',
+    'rubocop',
+]);
+const DetectedFormatterSchema = z.object({
+    name: FormatterNameSchema,
+    configPath: z.string(),
+    fixCommand: z.string(),
+    checkCommand: z.string(),
+    supportsFileArgs: z.boolean(),
+});
+const CIFormatterDiagnosisSchema = z.object({
+    isFormattingFailure: z.boolean(),
+    formatter: FormatterNameSchema.optional(),
+    fixCommand: z.string().optional(),
+    evidence: z.array(z.string()),
+});
+export const DetectFormattersOutputSchema = z.object({
+    formatters: z.array(DetectedFormatterSchema),
+    packageJsonScripts: z.array(z.object({ name: z.string(), command: z.string() })),
+    repoPath: z.string(),
+    ciDiagnosis: CIFormatterDiagnosisSchema.optional(),
+});
+const LocalRepoInfoSchema = z.object({
+    path: z.string(),
+    exists: z.boolean(),
+    currentBranch: z.string().nullable(),
+});
+export const LocalReposOutputSchema = z.object({
+    repos: z.record(z.string(), LocalRepoInfoSchema),
+    scanPaths: z.array(z.string()),
+    cachedAt: z.string(),
+    fromCache: z.boolean(),
+});
 /**
  * Convert a full StartupOutput to the compact format (#763).
  * Uses destructuring to auto-forward any new fields added to StartupOutput.
@@ -107,3 +453,37 @@ export function outputJson(data) {
 export function outputJsonError(message, errorCode) {
     console.log(JSON.stringify(jsonError(message, errorCode), null, 2));
 }
+/**
+ * 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 function formatJson(schema, data) {
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `${i.path.length > 0 ? i.path.join('.') : '<root>'}: ${i.message}`)
+            .join('; ');
+        throw new Error(`--json contract drift: command output does not match its declared schema. ${issues}`);
+    }
+    return jsonSuccess(result.data);
+}
+/**
+ * `outputJson(data)` plus Zod validation. Same throwing semantics as
+ * {@link formatJson}; the validated envelope is what gets printed.
+ */
+export function outputJsonValidated(schema, data) {
+    console.log(JSON.stringify(formatJson(schema, data), null, 2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "1.17.4",
+  "version": "3.0.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -49,7 +49,7 @@
     "url": "https://github.com/costajohnt/oss-autopilot/issues"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "dependencies": {
     "@octokit/plugin-throttling": "^11.0.3",
@@ -69,7 +69,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "bundle": "esbuild src/cli.ts --bundle --platform=node --target=node20 --format=cjs --minify --sourcemap --outfile=dist/cli.bundle.cjs",
+    "bundle": "esbuild src/cli.ts --bundle --platform=node --target=node22 --format=cjs --minify --sourcemap --outfile=dist/cli.bundle.cjs",
     "start": "tsx src/cli.ts",
     "dev": "tsx watch src/cli.ts",
     "typecheck": "tsc --noEmit",

package/dist/commands/read.d.ts

@@ -1,18 +0,0 @@
-/**
- * Read command
- * In v2, PR read/unread state is not tracked locally.
- * This command is a no-op preserved for backward compatibility.
- */
-export type ReadOutput = {
-    markedAsRead: number;
-    all: true;
-    message: string;
-} | {
-    marked: boolean;
-    url: string | undefined;
-    message: string;
-};
-export declare function runRead(options: {
-    prUrl?: string;
-    all?: boolean;
-}): Promise<ReadOutput>;

package/dist/commands/read.js

@@ -1,20 +0,0 @@
-/**
- * Read command
- * In v2, PR read/unread state is not tracked locally.
- * This command is a no-op preserved for backward compatibility.
- */
-import { ValidationError } from '../core/errors.js';
-import { validateUrl } from './validation.js';
-export async function runRead(options) {
-    if (!options.all && !options.prUrl) {
-        throw new ValidationError('PR URL or --all flag required');
-    }
-    if (options.prUrl) {
-        validateUrl(options.prUrl);
-    }
-    // In v2, unread state is not tracked locally — PRs are fetched fresh each run.
-    if (options.all) {
-        return { markedAsRead: 0, all: true, message: 'In v2, PR read state is not tracked locally.' };
-    }
-    return { marked: false, url: options.prUrl, message: 'In v2, PR read state is not tracked locally.' };
-}