@oss-autopilot/core 0.59.0 → 0.60.1

package/dist/core/state-schema.js

@@ -0,0 +1,214 @@
+/**
+ * Zod schemas for all types persisted in state.json.
+ *
+ * This file is the single source of truth for persisted type shapes.
+ * Types are inferred via `z.infer<>` at the bottom of this file and
+ * re-exported through types.ts.
+ *
+ * Schemas are defined bottom-up (leaf types first, composites last).
+ * Unknown keys are stripped by default (Zod 4 behavior).
+ */
+import { z } from 'zod';
+// ── 1. Enum / union schemas ───────────────────────────────────────────
+export const IssueStatusSchema = z.enum(['candidate', 'claimed', 'in_progress', 'pr_submitted']);
+export const FetchedPRStatusSchema = z.enum(['needs_addressing', 'waiting_on_maintainer']);
+export const ProjectCategorySchema = z.enum([
+    'nonprofit',
+    'devtools',
+    'infrastructure',
+    'web-frameworks',
+    'data-ml',
+    'education',
+]);
+export const IssueScopeSchema = z.enum(['beginner', 'intermediate', 'advanced']);
+export const StateEventTypeSchema = z.enum([
+    'pr_tracked',
+    'pr_merged',
+    'pr_closed',
+    'pr_dormant',
+    'daily_check',
+    'comment_posted',
+]);
+// ── 2. Leaf schemas ──────────────────────────────────────────────────
+export const RepoSignalsSchema = z.object({
+    hasActiveMaintainers: z.boolean(),
+    isResponsive: z.boolean(),
+    hasHostileComments: z.boolean(),
+});
+export const RepoScoreSchema = z.object({
+    repo: z.string(),
+    score: z.number(),
+    mergedPRCount: z.number(),
+    closedWithoutMergeCount: z.number(),
+    avgResponseDays: z.number().nullable(),
+    lastMergedAt: z.string().optional(),
+    lastEvaluatedAt: z.string(),
+    signals: RepoSignalsSchema,
+    stargazersCount: z.number().optional(),
+    language: z.string().nullable().optional(),
+});
+export const StateEventSchema = z.object({
+    id: z.string(),
+    type: StateEventTypeSchema,
+    at: z.string(),
+    data: z.record(z.string(), z.unknown()),
+});
+export const StoredMergedPRSchema = z.object({
+    url: z.string(),
+    title: z.string(),
+    mergedAt: z.string(),
+});
+export const StoredClosedPRSchema = z.object({
+    url: z.string(),
+    title: z.string(),
+    closedAt: z.string(),
+});
+// ── 3. Contribution schemas ──────────────────────────────────────────
+export const ContributionGuidelinesSchema = z.object({
+    branchNamingConvention: z.string().optional(),
+    commitMessageFormat: z.string().optional(),
+    prTitleFormat: z.string().optional(),
+    requiredChecks: z.array(z.string()).optional(),
+    testFramework: z.string().optional(),
+    testCoverageRequired: z.boolean().optional(),
+    testFileNaming: z.string().optional(),
+    linter: z.string().optional(),
+    formatter: z.string().optional(),
+    styleGuideUrl: z.string().optional(),
+    issueClaimProcess: z.string().optional(),
+    reviewProcess: z.string().optional(),
+    claRequired: z.boolean().optional(),
+    rawContent: z.string().optional(),
+});
+export const IssueVettingResultSchema = z.object({
+    passedAllChecks: z.boolean(),
+    checks: z.object({
+        noExistingPR: z.boolean(),
+        notClaimed: z.boolean(),
+        projectActive: z.boolean(),
+        clearRequirements: z.boolean(),
+        contributionGuidelinesFound: z.boolean(),
+    }),
+    contributionGuidelines: ContributionGuidelinesSchema.optional(),
+    notes: z.array(z.string()),
+});
+export const TrackedIssueSchema = z.object({
+    id: z.number(),
+    url: z.string(),
+    repo: z.string(),
+    number: z.number(),
+    title: z.string(),
+    status: IssueStatusSchema,
+    labels: z.array(z.string()),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    vetted: z.boolean(),
+    vettingResult: IssueVettingResultSchema.optional(),
+});
+// ── 4. PR reference schemas ──────────────────────────────────────────
+export const ShelvedPRRefSchema = z.object({
+    number: z.number(),
+    url: z.string(),
+    title: z.string(),
+    repo: z.string(),
+    daysSinceActivity: z.number(),
+    status: FetchedPRStatusSchema,
+});
+export const StatusOverrideSchema = z.object({
+    status: FetchedPRStatusSchema,
+    setAt: z.string(),
+    lastActivityAt: z.string(),
+});
+// ── 5. Config schema ─────────────────────────────────────────────────
+export const AgentConfigSchema = z.object({
+    setupComplete: z.boolean().default(false),
+    setupCompletedAt: z.string().optional(),
+    maxActivePRs: z.number().default(10),
+    dormantThresholdDays: z.number().default(30),
+    approachingDormantDays: z.number().default(25),
+    maxIssueAgeDays: z.number().default(90),
+    languages: z.array(z.string()).default(['typescript', 'javascript']),
+    labels: z.array(z.string()).default(['good first issue', 'help wanted']),
+    scope: z.array(IssueScopeSchema).optional(),
+    excludeRepos: z.array(z.string()).default([]),
+    excludeOrgs: z.array(z.string()).optional(),
+    trustedProjects: z.array(z.string()).default([]),
+    githubUsername: z.string().default(''),
+    minRepoScoreThreshold: z.number().default(4),
+    starredRepos: z.array(z.string()).default([]),
+    starredReposLastFetched: z.string().optional(),
+    showHealthCheck: z.boolean().optional(),
+    squashByDefault: z.union([z.boolean(), z.literal('ask')]).default(true),
+    localRepoScanPaths: z.array(z.string()).optional(),
+    minStars: z.number().default(50),
+    includeDocIssues: z.boolean().default(true),
+    aiPolicyBlocklist: z.array(z.string()).default(['matplotlib/matplotlib']),
+    shelvedPRUrls: z.array(z.string()).default([]),
+    dismissedIssues: z.record(z.string(), z.string()).default({}),
+    statusOverrides: z.record(z.string(), StatusOverrideSchema).optional(),
+    issueListPath: z.string().optional(),
+    projectCategories: z.array(ProjectCategorySchema).default([]),
+    preferredOrgs: z.array(z.string()).default([]),
+});
+// ── 6. Cache schemas ─────────────────────────────────────────────────
+export const LocalRepoCacheSchema = z.object({
+    repos: z.record(z.string(), z.object({
+        path: z.string(),
+        exists: z.boolean(),
+        currentBranch: z.string().nullable(),
+    })),
+    scanPaths: z.array(z.string()),
+    cachedAt: z.string(),
+});
+// ── 7. Digest schemas ────────────────────────────────────────────────
+export const ClosedPRSchema = z.object({
+    url: z.string(),
+    repo: z.string(),
+    number: z.number(),
+    title: z.string(),
+    closedAt: z.string(),
+    closedBy: z.string().optional(),
+});
+export const MergedPRSchema = z.object({
+    url: z.string(),
+    repo: z.string(),
+    number: z.number(),
+    title: z.string(),
+    mergedAt: z.string(),
+});
+export const DailyDigestSummarySchema = z.object({
+    totalActivePRs: z.number(),
+    totalNeedingAttention: z.number(),
+    totalMergedAllTime: z.number(),
+    mergeRate: z.number(),
+});
+export const DailyDigestSchema = z.object({
+    generatedAt: z.string(),
+    // FetchedPR arrays — ephemeral, regenerated each run. Validated loosely.
+    openPRs: z.array(z.any()),
+    needsAddressingPRs: z.array(z.any()),
+    waitingOnMaintainerPRs: z.array(z.any()),
+    recentlyClosedPRs: z.array(ClosedPRSchema),
+    recentlyMergedPRs: z.array(MergedPRSchema),
+    shelvedPRs: z.array(ShelvedPRRefSchema),
+    autoUnshelvedPRs: z.array(ShelvedPRRefSchema),
+    summary: DailyDigestSummarySchema,
+});
+// ── 8. Root schema ───────────────────────────────────────────────────
+export const AgentStateSchema = z.object({
+    version: z.literal(2),
+    repoScores: z.record(z.string(), RepoScoreSchema).default({}),
+    config: AgentConfigSchema.default(() => AgentConfigSchema.parse({})),
+    events: z.array(StateEventSchema).default([]),
+    lastRunAt: z.string().default(() => new Date().toISOString()),
+    lastDigestAt: z.string().optional(),
+    lastDigest: DailyDigestSchema.optional(),
+    monthlyMergedCounts: z.record(z.string(), z.number()).optional(),
+    monthlyClosedCounts: z.record(z.string(), z.number()).optional(),
+    monthlyOpenedCounts: z.record(z.string(), z.number()).optional(),
+    dailyActivityCounts: z.record(z.string(), z.number()).optional(),
+    localRepoCache: LocalRepoCacheSchema.optional(),
+    mergedPRs: z.array(StoredMergedPRSchema).optional(),
+    closedPRs: z.array(StoredClosedPRSchema).optional(),
+    activeIssues: z.array(TrackedIssueSchema).default([]),
+});

package/dist/core/types.d.ts

@@ -1,14 +1,8 @@
 /**
  * Core types for the Open Source Contribution Agent
  */
-/**
- * Lifecycle of a discovered issue through the contribution pipeline.
- * - `candidate` — Discovered but not yet claimed
- * - `claimed` — Contributor has claimed the issue (e.g., commented "I'll work on this")
- * - `in_progress` — Work is underway locally
- * - `pr_submitted` — A PR has been opened for this issue
- */
-export type IssueStatus = 'candidate' | 'claimed' | 'in_progress' | 'pr_submitted';
+import type { FetchedPRStatus, RepoSignals, TrackedIssue, IssueVettingResult, IssueScope, AgentConfig, AgentState } from './state-schema.js';
+export type { IssueStatus, FetchedPRStatus, ProjectCategory, IssueScope, StateEventType, RepoSignals, RepoScore, StateEvent, StoredMergedPR, StoredClosedPR, ContributionGuidelines, IssueVettingResult, TrackedIssue, ShelvedPRRef, StatusOverride, AgentConfig, LocalRepoCache, ClosedPR, MergedPR, DailyDigest, AgentState, } from './state-schema.js';
 /** CI pipeline status for a PR's latest commit. */
 export type CIStatus = 'passing' | 'failing' | 'pending' | 'unknown';
 /**
@@ -82,14 +76,6 @@ export type ActionReason = 'needs_response' | 'needs_changes' | 'failing_ci' | '
 export type WaitReason = 'pending_review' | 'pending_merge' | 'changes_addressed' | 'ci_blocked' | 'stale_ci_failure';
 /** How stale is the PR based on days since activity. Orthogonal to status. */
 export type StalenessTier = 'active' | 'approaching_dormant' | 'dormant';
-/**
- * Top-level classification of a PR's state. Only two values:
- * - `needs_addressing` — Contributor's turn. See `actionReason` for what to do.
- * - `waiting_on_maintainer` — Maintainer's turn. See `waitReason` for why.
- *
- * Staleness (active/approaching_dormant/dormant) is tracked separately in `stalenessTier`.
- */
-export type FetchedPRStatus = 'needs_addressing' | 'waiting_on_maintainer';
 /**
  * Hints about what a maintainer is asking for in their review comments.
  * Extracted from comment text by keyword matching.
@@ -158,68 +144,6 @@ export interface FetchedPR {
     /** Hints extracted from maintainer comments about what actions they are requesting. */
     maintainerActionHints: MaintainerActionHint[];
 }
-/**
- * Lightweight reference used in {@link DailyDigest} for shelved and auto-unshelved PRs.
- * Contains only the fields needed for display, avoiding duplication of the full
- * {@link FetchedPR} objects already present in `openPRs` and the status-specific arrays.
- * Derived from {@link FetchedPR} via `Pick<>` to stay in sync automatically.
- */
-export type ShelvedPRRef = Pick<FetchedPR, 'number' | 'url' | 'title' | 'repo' | 'daysSinceActivity' | 'status'>;
-/** An issue tracked through the contribution pipeline from discovery to PR submission. */
-export interface TrackedIssue {
-    id: number;
-    url: string;
-    repo: string;
-    number: number;
-    title: string;
-    status: IssueStatus;
-    labels: string[];
-    createdAt: string;
-    updatedAt: string;
-    /** Whether the issue has been through the vetting process (checking for existing PRs, activity, etc.). */
-    vetted: boolean;
-    vettingResult?: IssueVettingResult;
-}
-/**
- * Result of vetting an issue for contribution suitability.
- * An issue passes vetting when all checks are true (no existing PR, not claimed, etc.).
- */
-export interface IssueVettingResult {
-    passedAllChecks: boolean;
-    checks: {
-        noExistingPR: boolean;
-        notClaimed: boolean;
-        projectActive: boolean;
-        clearRequirements: boolean;
-        contributionGuidelinesFound: boolean;
-    };
-    contributionGuidelines?: ContributionGuidelines;
-    /** Free-text observations from the vetting process (e.g., "Issue has 3 linked PRs, all closed"). */
-    notes: string[];
-}
-/**
- * Structured representation of a project's contribution guidelines,
- * extracted from CONTRIBUTING.md or similar files during issue vetting.
- */
-export interface ContributionGuidelines {
-    branchNamingConvention?: string;
-    commitMessageFormat?: string;
-    prTitleFormat?: string;
-    requiredChecks?: string[];
-    testFramework?: string;
-    testCoverageRequired?: boolean;
-    /** Expected test file naming pattern (e.g., `"*.test.ts"`, `"*_spec.rb"`). */
-    testFileNaming?: string;
-    linter?: string;
-    formatter?: string;
-    styleGuideUrl?: string;
-    /** How to claim an issue (e.g., "Comment on the issue before starting work"). */
-    issueClaimProcess?: string;
-    reviewProcess?: string;
-    claRequired?: boolean;
-    /** Raw CONTRIBUTING.md content for reference when structured fields are insufficient. */
-    rawContent?: string;
-}
 /** Health snapshot of a GitHub repository, used to determine if a project is worth contributing to. */
 export interface ProjectHealth {
     repo: string;
@@ -239,38 +163,6 @@ export interface ProjectHealth {
     checkFailed?: boolean;
     failureReason?: string;
 }
-/**
- * Quality score for a repository, used to prioritize issue search results.
- * Score is on a 1-10 scale: base 5, logarithmic merge bonus (max +5: 1->+2, 2->+3, 3->+4, 5+->+5),
- * -1 per closed-without-merge (max -3), +1 if lastMergedAt is set and within 90 days,
- * +1 if responsive, -2 if hostile.
- * Repos below `AgentConfig.minRepoScoreThreshold` are deprioritized.
- */
-export interface RepoScore {
-    repo: string;
-    /** Overall score from 1 (avoid) to 10 (excellent track record). */
-    score: number;
-    /** Number of the contributor's PRs that were merged in this repo. */
-    mergedPRCount: number;
-    /** Number of the contributor's PRs closed without merge (indicates friction). */
-    closedWithoutMergeCount: number;
-    /** Average days for maintainers to respond; null if no data. */
-    avgResponseDays: number | null;
-    lastMergedAt?: string;
-    lastEvaluatedAt: string;
-    /** Qualitative signals about the repo's maintainer culture. */
-    signals: RepoSignals;
-    /** GitHub star count, fetched during daily check for dashboard filtering. */
-    stargazersCount?: number;
-    /** Primary programming language of the repo, fetched during daily check. */
-    language?: string | null;
-}
-/** Full set of qualitative signals about a repo's maintainer culture. */
-export interface RepoSignals {
-    hasActiveMaintainers: boolean;
-    isResponsive: boolean;
-    hasHostileComments: boolean;
-}
 /** Signals computed from observed open PR data, suitable for merging into RepoScore.signals. */
 export type ComputedRepoSignals = Pick<RepoSignals, 'isResponsive' | 'hasActiveMaintainers'>;
 /**
@@ -294,141 +186,6 @@ export interface RepoMetadataEntry {
     stars?: number;
     language?: string | null;
 }
-/**
- * Event types recorded in the {@link AgentState} audit log.
- * - `pr_tracked` — A new PR was added to tracking
- * - `pr_merged` — A tracked PR was merged
- * - `pr_closed` — A tracked PR was closed without merge
- * - `pr_dormant` — A PR crossed the dormant threshold
- * - `daily_check` — A daily digest run completed
- * - `comment_posted` — The agent posted a comment on a PR
- */
-export type StateEventType = 'pr_tracked' | 'pr_merged' | 'pr_closed' | 'pr_dormant' | 'daily_check' | 'comment_posted';
-/** An entry in the state audit log. Events are append-only and used for history tracking. */
-export interface StateEvent {
-    id: string;
-    type: StateEventType;
-    /** ISO 8601 timestamp of when the event occurred. */
-    at: string;
-    /** Event-specific payload (e.g., `{ repo: "owner/repo", number: 42 }` for PR events). */
-    data: Record<string, unknown>;
-}
-/** Minimal record of a PR that was closed without being merged, used in the daily digest and dashboard detail view. */
-export interface ClosedPR {
-    url: string;
-    repo: string;
-    number: number;
-    title: string;
-    closedAt: string;
-    closedBy?: string;
-}
-/** Minimal merged PR data persisted in state.json. Repo/number derived from URL at display time. */
-export interface StoredMergedPR {
-    url: string;
-    title: string;
-    mergedAt: string;
-}
-/** Minimal closed PR data persisted in state.json. Repo/number derived from URL at display time. */
-export interface StoredClosedPR {
-    url: string;
-    title: string;
-    closedAt: string;
-}
-/** Minimal record of a PR that was merged, used in the daily digest and dashboard detail view. */
-export interface MergedPR {
-    url: string;
-    repo: string;
-    number: number;
-    title: string;
-    mergedAt: string;
-}
-/**
- * The daily report produced by `PRMonitor.generateDigest()`.
- * Contains all open PRs fetched fresh from GitHub, categorized by status,
- * plus recently closed PRs and summary statistics. This is persisted in
- * `AgentState.lastDigest` so the HTML dashboard can render it.
- */
-export interface DailyDigest {
-    generatedAt: string;
-    /** All open PRs authored by the user, fetched from GitHub Search API. */
-    openPRs: FetchedPR[];
-    /** PRs where the contributor needs to take action. Subset of openPRs where status === 'needs_addressing'. */
-    needsAddressingPRs: FetchedPR[];
-    /** PRs waiting on the maintainer. Subset of openPRs where status === 'waiting_on_maintainer'. */
-    waitingOnMaintainerPRs: FetchedPR[];
-    /** PRs closed without merge in the last 7 days. Surfaced to alert the contributor. */
-    recentlyClosedPRs: ClosedPR[];
-    /** PRs merged in the last 7 days. Surfaced as wins in the dashboard. */
-    recentlyMergedPRs: MergedPR[];
-    /**
-     * PRs manually shelved by the user (excluded from capacity and actionable issues).
-     * Stored as lightweight references — full data is available in `openPRs`.
-     */
-    shelvedPRs: ShelvedPRRef[];
-    /**
-     * PRs that were auto-unshelved this run because a maintainer engaged.
-     * Stored as lightweight references — full data is available in `openPRs`.
-     */
-    autoUnshelvedPRs: ShelvedPRRef[];
-    summary: {
-        totalActivePRs: number;
-        /** Count of PRs requiring contributor action (response, CI fix, conflict resolution, etc.). */
-        totalNeedingAttention: number;
-        /** Lifetime merged PR count across all repos, derived from RepoScore data. */
-        totalMergedAllTime: number;
-        /** Percentage of all-time PRs that were merged (merged / (merged + closed)). */
-        mergeRate: number;
-    };
-}
-/**
- * Root state object persisted to `~/.oss-autopilot/state.json`.
- *
- * In v2 (current), PRs are fetched fresh from GitHub on each run via the Search API.
- * The primary runtime data lives in `lastDigest` and `repoScores`.
- */
-export interface AgentState {
-    /** Schema version. `2` = v2 fresh-fetch architecture. Used by `StateManager` for migrations. */
-    version: number;
-    /** Per-repo quality scores keyed by `"owner/repo"`. Used to prioritize issue search results. */
-    repoScores: Record<string, RepoScore>;
-    config: AgentConfig;
-    /** Append-only audit log of significant events (PR merged, daily check, etc.). */
-    events: StateEvent[];
-    /** ISO timestamp of the last CLI invocation. */
-    lastRunAt: string;
-    /** ISO timestamp of the last daily digest generation. */
-    lastDigestAt?: string;
-    /** Cached daily digest so the HTML dashboard can render without re-fetching from GitHub. */
-    lastDigest?: DailyDigest;
-    /** Monthly merged PR counts keyed by `"YYYY-MM"`. Powers the contribution timeline chart. */
-    monthlyMergedCounts?: Record<string, number>;
-    /** Monthly closed (without merge) PR counts keyed by `"YYYY-MM"`. Powers the timeline and success rate charts. */
-    monthlyClosedCounts?: Record<string, number>;
-    /** Monthly opened PR counts keyed by `"YYYY-MM"`. Combines PRs opened across merged+closed+open sets. */
-    monthlyOpenedCounts?: Record<string, number>;
-    /** Daily activity counts keyed by `"YYYY-MM-DD"`. Powers the activity heatmap chart. */
-    dailyActivityCounts?: Record<string, number>;
-    /** Cached local repo scan results (#84). Avoids re-scanning the filesystem every session. */
-    localRepoCache?: LocalRepoCache;
-    /** All merged PRs stored incrementally. Source of truth for the merged PR detail view. */
-    mergedPRs?: StoredMergedPR[];
-    /** All closed PRs stored incrementally. Source of truth for the closed PR detail view. */
-    closedPRs?: StoredClosedPR[];
-    activeIssues: TrackedIssue[];
-}
-/** Cached results from scanning the filesystem for local git clones (#84). */
-export interface LocalRepoCache {
-    /** Map of "owner/repo" -> local repo info */
-    repos: Record<string, {
-        path: string;
-        exists: boolean;
-        currentBranch: string | null;
-    }>;
-    /** Directories that were scanned */
-    scanPaths: string[];
-    /** ISO 8601 timestamp of when the scan was performed */
-    cachedAt: string;
-}
 /** Filter for excluding repos below a minimum star count from PR count queries. */
 export interface StarFilter {
     minStars: number;
@@ -439,68 +196,6 @@ export interface StarFilter {
  * Returns true if the repo is below the threshold or has unknown star count.
  */
 export declare function isBelowMinStars(stargazersCount: number | undefined, minStars: number): boolean;
-/** Manual status override for a PR, set via dashboard or CLI. Auto-clears when new activity is detected. */
-export interface StatusOverride {
-    status: FetchedPRStatus;
-    setAt: string;
-    /** PR's updatedAt at the time the override was set. Used to detect new activity for auto-clear. */
-    lastActivityAt: string;
-}
-/** User-configurable settings, populated via `/setup-oss` and stored in {@link AgentState}. */
-export interface AgentConfig {
-    /** False until the user completes initial setup via `/setup-oss`. */
-    setupComplete: boolean;
-    setupCompletedAt?: string;
-    maxActivePRs: number;
-    /** Days of inactivity before a PR is marked `dormant`. Default 30. */
-    dormantThresholdDays: number;
-    /** Days of inactivity before a PR is marked `approaching_dormant`. Default 25. */
-    approachingDormantDays: number;
-    /** Issues older than this (by `updated_at`) are filtered from search results. Default 90. */
-    maxIssueAgeDays: number;
-    /** Programming languages to search for issues in (e.g., `["typescript", "javascript"]`). */
-    languages: string[];
-    /** GitHub labels to filter issues by (e.g., `["good first issue", "help wanted"]`). */
-    labels: string[];
-    /** Issue scope tiers to search (e.g., `["beginner", "intermediate"]`). When set, scope tier labels are merged with custom `labels`. When absent, only `labels` is used (legacy behavior). */
-    scope?: IssueScope[];
-    /** Repos to exclude from issue discovery/search, in `"owner/repo"` format. */
-    excludeRepos: string[];
-    /** Organizations to exclude from issue discovery/search (case-insensitive match on owner segment). */
-    excludeOrgs?: string[];
-    /** Repos where the contributor has had PRs merged. Used for prioritization. */
-    trustedProjects: string[];
-    githubUsername: string;
-    /** Minimum {@link RepoScore} to include a repo in search results. Default 4. */
-    minRepoScoreThreshold: number;
-    /** User's GitHub starred repos, fetched periodically for prioritized issue discovery. */
-    starredRepos: string[];
-    starredReposLastFetched?: string;
-    /** Whether to show the health check notification on session start. Default true. */
-    showHealthCheck?: boolean;
-    /** Whether to squash commits before marking PR ready. `true` (default), `false`, or `"ask"`. */
-    squashByDefault?: boolean | 'ask';
-    /** Directories to scan for local git clones (#84). Falls back to default paths if not set. */
-    localRepoScanPaths?: string[];
-    /** Minimum GitHub star count for Phase 2 (general search) results. Default 50. Phases 0/1 are exempt. */
-    minStars?: number;
-    /** Whether to include documentation-only issues in search results. Default true. */
-    includeDocIssues?: boolean;
-    /** Repos known to have anti-AI contribution policies, in `"owner/repo"` format. Filtered from search results automatically. */
-    aiPolicyBlocklist?: string[];
-    /** PR URLs manually shelved by the user. Shelved PRs are excluded from capacity and actionable issues. Auto-unshelved when maintainers engage. */
-    shelvedPRUrls?: string[];
-    /** Issue URLs dismissed by the user, mapped to ISO timestamp of when dismissed. Issues with new responses after the dismiss timestamp resurface automatically. */
-    dismissedIssues?: Record<string, string>;
-    /** Manual status overrides for PRs. Maps PR URL to override metadata. Auto-clears when the PR has new activity. */
-    statusOverrides?: Record<string, StatusOverride>;
-    /** Path to the user's curated issue list file. Replaces config.md as the primary source for detectIssueList(). */
-    issueListPath?: string;
-    /** Project categories the user is interested in (e.g., devtools, nonprofit). Used to prioritize search results. */
-    projectCategories?: ProjectCategory[];
-    /** GitHub organizations the user wants to prioritize in issue search. Org names only (not owner/repo). */
-    preferredOrgs?: string[];
-}
 /** Status of a user's comment thread on a GitHub issue. */
 export type IssueConversationStatus = 'new_response' | 'waiting' | 'acknowledged';
 /** Base fields shared by all issue conversation states. */
@@ -538,10 +233,8 @@ export type CommentedIssue = CommentedIssueWithResponse | CommentedIssueWithoutR
 export declare const DEFAULT_CONFIG: AgentConfig;
 /** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v2 architecture. */
 export declare const INITIAL_STATE: AgentState;
-export declare const PROJECT_CATEGORIES: readonly ["nonprofit", "devtools", "infrastructure", "web-frameworks", "data-ml", "education"];
-export type ProjectCategory = (typeof PROJECT_CATEGORIES)[number];
-export declare const ISSUE_SCOPES: readonly ["beginner", "intermediate", "advanced"];
-export type IssueScope = (typeof ISSUE_SCOPES)[number];
+export declare const PROJECT_CATEGORIES: ("nonprofit" | "devtools" | "infrastructure" | "web-frameworks" | "data-ml" | "education")[];
+export declare const ISSUE_SCOPES: ("advanced" | "beginner" | "intermediate")[];
 export declare const SCOPE_LABELS: Record<IssueScope, string[]>;
 /** Priority tier for issue search results. Ordered: merged_pr > preferred_org > starred > normal. */
 export type SearchPriority = 'merged_pr' | 'preferred_org' | 'starred' | 'normal';
@@ -555,4 +248,3 @@ export interface IssueCandidate {
     viabilityScore: number;
     searchPriority: SearchPriority;
 }
-export {};

package/dist/core/types.js

@@ -1,6 +1,7 @@
 /**
  * Core types for the Open Source Contribution Agent
  */
+import { AgentConfigSchema, AgentStateSchema, ProjectCategorySchema, IssueScopeSchema } from './state-schema.js';
 /**
  * Check if a repo should be excluded based on its star count.
  * Returns true if the repo is below the threshold or has unknown star count.
@@ -8,49 +9,14 @@
 export function isBelowMinStars(stargazersCount, minStars) {
     return stargazersCount === undefined || stargazersCount < minStars;
 }
+// ── Schema-derived constants ─────────────────────────────────────────
 /** Default configuration applied to new state files. All fields can be overridden via `/setup-oss`. */
-export const DEFAULT_CONFIG = {
-    setupComplete: false,
-    maxActivePRs: 10,
-    dormantThresholdDays: 30,
-    approachingDormantDays: 25,
-    maxIssueAgeDays: 90,
-    languages: ['typescript', 'javascript'],
-    labels: ['good first issue', 'help wanted'],
-    excludeRepos: [],
-    trustedProjects: [],
-    githubUsername: '',
-    minRepoScoreThreshold: 4,
-    starredRepos: [],
-    squashByDefault: true,
-    minStars: 50,
-    includeDocIssues: true,
-    aiPolicyBlocklist: ['matplotlib/matplotlib'],
-    shelvedPRUrls: [],
-    dismissedIssues: {},
-    projectCategories: [],
-    preferredOrgs: [],
-};
+export const DEFAULT_CONFIG = AgentConfigSchema.parse({});
 /** Initial state written to `~/.oss-autopilot/state.json` on first run. Uses v2 architecture. */
-export const INITIAL_STATE = {
-    version: 2, // v2: Fresh GitHub fetching
-    activeIssues: [],
-    repoScores: {},
-    config: DEFAULT_CONFIG,
-    events: [],
-    lastRunAt: new Date().toISOString(),
-};
-// -- Project category types --
-export const PROJECT_CATEGORIES = [
-    'nonprofit',
-    'devtools',
-    'infrastructure',
-    'web-frameworks',
-    'data-ml',
-    'education',
-];
-// -- Issue scope types --
-export const ISSUE_SCOPES = ['beginner', 'intermediate', 'advanced'];
+export const INITIAL_STATE = AgentStateSchema.parse({ version: 2 });
+// ── Const arrays (derived from Zod schemas for runtime iteration) ────
+export const PROJECT_CATEGORIES = ProjectCategorySchema.options;
+export const ISSUE_SCOPES = IssueScopeSchema.options;
 export const SCOPE_LABELS = {
     beginner: ['good first issue', 'help wanted', 'easy', 'up-for-grabs', 'first-timers-only', 'beginner'],
     intermediate: ['enhancement', 'feature', 'feature-request', 'contributions welcome'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "0.59.0",
+  "version": "0.60.1",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -50,7 +50,8 @@
   "dependencies": {
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.1",
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",