@oss-autopilot/core 1.16.2 → 1.17.0

package/dist/commands/startup.js

@@ -9,7 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFile } from 'child_process';
-import { getStateManager, getGitHubToken, getCLIVersion, detectGitHubUsername } from '../core/index.js';
+import { getStateManager, getGitHubTokenAsync, getCLIVersion, detectGitHubUsername } from '../core/index.js';
 import { errorMessage } from '../core/errors.js';
 import { warn } from '../core/logger.js';
 import { executeDailyCheck } from './daily.js';
@@ -207,8 +207,12 @@ export async function runStartup() {
             return { version, setupComplete: false };
         }
     }
-    // 2. Check auth
-    const token = getGitHubToken();
+    // 2. Check auth — use the async variant so the `gh auth token` CLI fallback
+    // fires for users who ran `gh auth login` but never exported $GITHUB_TOKEN.
+    // The sync `getGitHubToken()` reads only the env var, matching the `preAction`
+    // token check that the CLI's `localOnly: true` flag on `startup` deliberately
+    // skips — the mismatch produced a spurious `authError` for valid users.
+    const token = await getGitHubTokenAsync();
     if (!token) {
         return {
             version,

package/dist/commands/track.js

@@ -13,6 +13,7 @@
  *   a PR from the daily digest.
  */
 import { getOctokit, requireGitHubToken } from '../core/index.js';
+import { ValidationError } from '../core/errors.js';
 import { validateUrl, PR_URL_PATTERN, validateGitHubUrl } from './validation.js';
 import { parseGitHubUrl } from '../core/utils.js';
 /**
@@ -34,7 +35,7 @@ export async function runTrack(options) {
     const octokit = getOctokit(token);
     const parsed = parseGitHubUrl(options.prUrl);
     if (!parsed || parsed.type !== 'pull') {
-        throw new Error(`Invalid PR URL: ${options.prUrl}`);
+        throw new ValidationError(`Invalid PR URL: ${options.prUrl}`);
     }
     const { owner, repo, number } = parsed;
     const { data: ghPR } = await octokit.pulls.get({ owner, repo, pull_number: number });

package/dist/commands/vet-list.d.ts

@@ -8,11 +8,32 @@ interface VetListOptions {
     concurrency?: number;
     prune?: boolean;
 }
+/**
+ * Scout-side enumerated skip reasons (#1043). If scout emits a `skipReason`
+ * field on its vet candidate, we route on that directly rather than doing
+ * fragile substring matches against free-text. The strings scout uses today
+ * (e.g. "Issue is closed", "Issue is already claimed") would silently stop
+ * matching on a rewording — the enum makes the data contract explicit.
+ *
+ * Scout has not yet landed the enum emitter; this PR lands the reader so the
+ * switchover is drop-in when scout ships it. The substring fallback below
+ * covers the transition period.
+ */
+export type ScoutSkipReason = 'issue_closed' | 'has_linked_pr' | 'claimed' | 'score_too_low' | 'anti_llm_policy' | 'other';
+/**
+ * Defensively extract a `skipReason` from a scout candidate. Scout's types
+ * don't expose it yet, and we want to ignore any value scout emits that
+ * isn't one of the expected enum members (forward-compat + poison guard).
+ */
+export declare function extractSkipReason(candidate: unknown): ScoutSkipReason | undefined;
 /**
  * Determine the list status from vetting results.
- * Maps vetting recommendation + reasons to a list-level status.
+ *
+ * Prefers scout's structured `skipReason` enum when present; falls back to
+ * substring matching on the free-text `reasonsToSkip` for the transition
+ * period before scout emits the enum. See #1043.
  */
-export declare function classifyListStatus(vetResult: VetOutput): VetListItemStatus;
+export declare function classifyListStatus(vetResult: VetOutput, skipReason?: ScoutSkipReason): VetListItemStatus;
 /**
  * Re-vet all available issues in a curated issue list.
  * Reads the list file, extracts available (non-done) issues,

package/dist/commands/vet-list.js

@@ -9,18 +9,65 @@ import { detectIssueList } from './startup.js';
 import { computeSuccessGrade, gradeFromCandidate } from '../core/issue-grading.js';
 import { getStateManager } from '../core/index.js';
 const UNKNOWN_GRADE = computeSuccessGrade({ avgResponseDays: null, mergeRate: null, daysSinceLastCommit: null });
+const KNOWN_SKIP_REASONS = new Set([
+    'issue_closed',
+    'has_linked_pr',
+    'claimed',
+    'score_too_low',
+    'anti_llm_policy',
+    'other',
+]);
+function mapSkipReasonToStatus(reason) {
+    switch (reason) {
+        case 'issue_closed':
+            return 'closed';
+        case 'claimed':
+            return 'claimed';
+        case 'has_linked_pr':
+            return 'has_pr';
+        case 'score_too_low':
+        case 'anti_llm_policy':
+        case 'other':
+            return null; // fall through to recommendation / default
+    }
+}
+/**
+ * Defensively extract a `skipReason` from a scout candidate. Scout's types
+ * don't expose it yet, and we want to ignore any value scout emits that
+ * isn't one of the expected enum members (forward-compat + poison guard).
+ */
+export function extractSkipReason(candidate) {
+    if (typeof candidate !== 'object' || candidate === null)
+        return undefined;
+    const raw = candidate.skipReason;
+    if (typeof raw !== 'string')
+        return undefined;
+    return KNOWN_SKIP_REASONS.has(raw) ? raw : undefined;
+}
 /**
  * Determine the list status from vetting results.
- * Maps vetting recommendation + reasons to a list-level status.
+ *
+ * Prefers scout's structured `skipReason` enum when present; falls back to
+ * substring matching on the free-text `reasonsToSkip` for the transition
+ * period before scout emits the enum. See #1043.
  */
-export function classifyListStatus(vetResult) {
-    const skipReasons = vetResult.reasonsToSkip.map((r) => r.toLowerCase());
-    if (skipReasons.some((r) => r.includes('closed')))
-        return 'closed';
-    if (skipReasons.some((r) => r.includes('claimed') || r.includes('assigned')))
-        return 'claimed';
-    if (skipReasons.some((r) => r.includes('existing pr') || r.includes('linked pr') || r.includes('pull request')))
-        return 'has_pr';
+export function classifyListStatus(vetResult, skipReason) {
+    if (skipReason) {
+        const fromEnum = mapSkipReasonToStatus(skipReason);
+        if (fromEnum)
+            return fromEnum;
+        // skipReason was set but maps to 'other' / low-score / policy — let the
+        // recommendation-based branches below decide final status.
+    }
+    else {
+        const skipReasons = vetResult.reasonsToSkip.map((r) => r.toLowerCase());
+        if (skipReasons.some((r) => r.includes('closed')))
+            return 'closed';
+        if (skipReasons.some((r) => r.includes('claimed') || r.includes('assigned')))
+            return 'claimed';
+        if (skipReasons.some((r) => r.includes('existing pr') || r.includes('linked pr') || r.includes('pull request')))
+            return 'has_pr';
+    }
     if (vetResult.recommendation === 'approve' || vetResult.recommendation === 'needs_review') {
         return 'still_available';
     }
@@ -87,7 +134,7 @@ export async function runVetList(options = {}) {
                 };
                 results.push({
                     ...vetResult,
-                    listStatus: classifyListStatus(vetResult),
+                    listStatus: classifyListStatus(vetResult, extractSkipReason(candidate)),
                 });
             }
             catch (error) {

package/dist/core/anti-llm-policy.d.ts

@@ -16,6 +16,11 @@
  * contribution surface without recourse. We only match on phrases
  * that combine a rejection keyword (no / reject / will be closed /
  * don't accept) with an AI/LLM noun.
+ *
+ * **User-facing reference:** `docs/anti-llm-policy.md` — explains the
+ * three categories, example phrases per category, and the false-positive-
+ * resistance design (why "AI division will be closed at end of Q4"
+ * does NOT match).
  */
 export type AntiLLMCategory = 'explicit_ban' | 'tool_ban' | 'reject_framing';
 export interface AntiLLMMatch {

package/dist/core/anti-llm-policy.js

@@ -16,6 +16,11 @@
  * contribution surface without recourse. We only match on phrases
  * that combine a rejection keyword (no / reject / will be closed /
  * don't accept) with an AI/LLM noun.
+ *
+ * **User-facing reference:** `docs/anti-llm-policy.md` — explains the
+ * three categories, example phrases per category, and the false-positive-
+ * resistance design (why "AI division will be closed at end of Q4"
+ * does NOT match).
  */
 const PATTERNS = [
     // Explicit "no X" bans against AI/LLM nouns.

package/dist/core/ci-analysis.js

@@ -21,7 +21,12 @@ const FORK_LIMITATION_PATTERNS = [
     /chromatic/i,
     /percy/i,
     /cloudflare pages/i,
-    /\binternal\b/i,
+    // Tightened from plain `\binternal\b` (#1057 M34). Still catches the
+    // known "Facebook Internal", "Meta Internal", and "Internal - <thing>"
+    // fork-limitation checks (#675), but the negative lookahead prevents
+    // misclassifying legitimate test checks like "Internal API tests" or
+    // "Internal Integration Tests".
+    /\binternal\b(?!\s+(?:api|test|integration|smoke|unit|e2e|regression|functional))/i,
 ];
 /**
  * Known CI check name patterns that indicate authorization gates (#81).

package/dist/core/config-registry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Single source of truth for user-configurable state.json config keys.
+ *
+ * Keys fall into two CLI surfaces:
+ *   - `oss-autopilot setup --set key=value` — direct scalar / list-replace sets
+ *   - `oss-autopilot config <key> <value>`  — list mutators (add-/remove-) and aliases
+ *
+ * A key may be settable via one, the other, or both. `auto` means the field is
+ * populated by internal code (e.g. starredRepos is fetched from GitHub), never
+ * by a user command — it's listed here so `scout-bridge.ts` reads are auditable.
+ *
+ * When adding a new user-configurable state.json field:
+ *   1. Add the field to `AgentConfigSchema` (state-schema.ts).
+ *   2. Add an entry here.
+ *   3. Wire the handler in `commands/setup.ts` and/or `commands/config.ts`.
+ *   4. The registry test (`config-registry.test.ts`) asserts both commands
+ *      handle every non-`auto` key.
+ */
+export type SettableVia = 'setup' | 'config' | 'both' | 'auto';
+export interface ConfigKeyDef {
+    /** The key as users type it (may differ from the underlying state field, e.g. `dormantDays` → `dormantThresholdDays`). */
+    key: string;
+    /** One-line human description — shown by `config --list-keys`. */
+    description: string;
+    /** Which CLI surface accepts this key. */
+    settableVia: SettableVia;
+    /** Short hint for the expected value shape (e.g. `"number"`, `"owner/repo"`, `"comma-separated list"`). */
+    valueHint: string;
+}
+export declare const CONFIG_KEY_REGISTRY: readonly ConfigKeyDef[];
+export declare function isKnownKey(key: string): boolean;
+export declare function getKeyDef(key: string): ConfigKeyDef | undefined;
+/** Keys accepted by the `setup --set` command (includes `both`). */
+export declare function getSetupKeys(): readonly string[];
+/** Keys accepted by the `config <key> <value>` command (includes `both`). */
+export declare function getConfigKeys(): readonly string[];
+/**
+ * Find the closest known key for a typo, limited to keys accepted by the given
+ * CLI surface. Returns `undefined` when no key is close enough (threshold ≤2
+ * edits, case-insensitive) — better to say nothing than suggest a wild guess.
+ */
+export declare function suggestKey(key: string, surface: 'setup' | 'config'): string | undefined;
+/** Format an "unknown key" error, appending a did-you-mean suggestion when confident. */
+export declare function formatUnknownKeyError(key: string, surface: 'setup' | 'config'): string;

package/dist/core/config-registry.js

@@ -0,0 +1,286 @@
+/**
+ * Single source of truth for user-configurable state.json config keys.
+ *
+ * Keys fall into two CLI surfaces:
+ *   - `oss-autopilot setup --set key=value` — direct scalar / list-replace sets
+ *   - `oss-autopilot config <key> <value>`  — list mutators (add-/remove-) and aliases
+ *
+ * A key may be settable via one, the other, or both. `auto` means the field is
+ * populated by internal code (e.g. starredRepos is fetched from GitHub), never
+ * by a user command — it's listed here so `scout-bridge.ts` reads are auditable.
+ *
+ * When adding a new user-configurable state.json field:
+ *   1. Add the field to `AgentConfigSchema` (state-schema.ts).
+ *   2. Add an entry here.
+ *   3. Wire the handler in `commands/setup.ts` and/or `commands/config.ts`.
+ *   4. The registry test (`config-registry.test.ts`) asserts both commands
+ *      handle every non-`auto` key.
+ */
+export const CONFIG_KEY_REGISTRY = [
+    // ── Identity ─────────────────────────────────────────────────────────
+    {
+        key: 'username',
+        description: 'Your GitHub username.',
+        settableVia: 'both',
+        valueHint: 'string',
+    },
+    // ── Capacity / dormancy ──────────────────────────────────────────────
+    {
+        key: 'maxActivePRs',
+        description: 'Soft cap on how many active PRs you want to juggle at once.',
+        settableVia: 'setup',
+        valueHint: 'positive integer',
+    },
+    {
+        key: 'dormantDays',
+        description: 'Alias for dormantThresholdDays: days of inactivity before a PR is considered dormant.',
+        settableVia: 'setup',
+        valueHint: 'positive integer',
+    },
+    {
+        key: 'approachingDays',
+        description: 'Alias for approachingDormantDays: days before dormancy threshold at which to warn.',
+        settableVia: 'setup',
+        valueHint: 'positive integer',
+    },
+    // ── Issue discovery ──────────────────────────────────────────────────
+    {
+        key: 'languages',
+        description: 'Programming languages to filter issue discovery by (whole-list replace).',
+        settableVia: 'setup',
+        valueHint: 'comma-separated list',
+    },
+    {
+        key: 'labels',
+        description: 'Issue labels to search for (whole-list replace).',
+        settableVia: 'setup',
+        valueHint: 'comma-separated list',
+    },
+    {
+        key: 'scope',
+        description: 'Issue complexity scope(s) — beginner, intermediate, advanced.',
+        settableVia: 'setup',
+        valueHint: 'comma-separated list of: beginner,intermediate,advanced',
+    },
+    {
+        key: 'minStars',
+        description: 'Minimum stargazers required for a repo to surface during discovery.',
+        settableVia: 'setup',
+        valueHint: 'non-negative integer',
+    },
+    {
+        key: 'includeDocIssues',
+        description: 'Whether documentation-only issues should appear in discovery.',
+        settableVia: 'setup',
+        valueHint: 'true|false',
+    },
+    {
+        key: 'maxIssueAgeDays',
+        description: 'Maximum age (in days) for an issue to be considered in discovery.',
+        settableVia: 'setup',
+        valueHint: 'positive integer',
+    },
+    {
+        key: 'minRepoScoreThreshold',
+        description: 'Minimum repo maintainer-health score required for discovery (0–10).',
+        settableVia: 'setup',
+        valueHint: 'non-negative integer',
+    },
+    {
+        key: 'projectCategories',
+        description: 'Project categories to prioritize (whole-list replace).',
+        settableVia: 'setup',
+        valueHint: 'comma-separated list of: nonprofit,devtools,infrastructure,web-frameworks,data-ml,education',
+    },
+    {
+        key: 'preferredOrgs',
+        description: 'GitHub orgs to prioritize during discovery (whole-list replace).',
+        settableVia: 'setup',
+        valueHint: 'comma-separated list',
+    },
+    {
+        key: 'aiPolicyBlocklist',
+        description: 'Repos (owner/repo) with anti-AI contribution policies to block from discovery.',
+        settableVia: 'setup',
+        valueHint: 'comma-separated list of owner/repo',
+    },
+    // ── Exclusion list mutators (config-only) ────────────────────────────
+    {
+        key: 'add-language',
+        description: 'Append a language to the discovery languages list.',
+        settableVia: 'config',
+        valueHint: 'string',
+    },
+    {
+        key: 'add-label',
+        description: 'Append a label to the discovery labels list.',
+        settableVia: 'config',
+        valueHint: 'string',
+    },
+    {
+        key: 'remove-label',
+        description: 'Remove a label from the discovery labels list.',
+        settableVia: 'config',
+        valueHint: 'string (must already be present)',
+    },
+    {
+        key: 'add-scope',
+        description: 'Append a scope to the discovery scope list.',
+        settableVia: 'config',
+        valueHint: 'one of: beginner,intermediate,advanced',
+    },
+    {
+        key: 'remove-scope',
+        description: 'Remove a scope from the discovery scope list.',
+        settableVia: 'config',
+        valueHint: 'one of: beginner,intermediate,advanced',
+    },
+    {
+        key: 'exclude-repo',
+        description: 'Exclude a specific repo (owner/repo) from discovery.',
+        settableVia: 'config',
+        valueHint: 'owner/repo',
+    },
+    {
+        key: 'exclude-org',
+        description: 'Exclude an entire org from discovery.',
+        settableVia: 'config',
+        valueHint: 'org name (no slash)',
+    },
+    // ── Tooling ──────────────────────────────────────────────────────────
+    {
+        key: 'issueListPath',
+        description: 'Path to a text file of extra issue URLs to surface.',
+        settableVia: 'both',
+        valueHint: 'filesystem path',
+    },
+    {
+        key: 'skippedIssuesPath',
+        description: 'Path to the skipped-issues file (auto-culls entries older than 90 days).',
+        settableVia: 'setup',
+        valueHint: 'filesystem path',
+    },
+    {
+        key: 'diffTool',
+        description: 'Default diff renderer for reviews.',
+        settableVia: 'both',
+        valueHint: 'one of: inline,sourcetree,vscode,custom',
+    },
+    {
+        key: 'diffToolCustomCommand',
+        description: 'Shell command template used when diffTool=custom.',
+        settableVia: 'both',
+        valueHint: 'shell command with {old}/{new} placeholders',
+    },
+    // ── Behavior ─────────────────────────────────────────────────────────
+    {
+        key: 'squashByDefault',
+        description: 'Default merge strategy — squash-merge, prompt, or standard merge.',
+        settableVia: 'setup',
+        valueHint: 'true|false|ask',
+    },
+    {
+        key: 'persistence',
+        description: 'Where to store state.json — local file or GitHub Gist.',
+        settableVia: 'setup',
+        valueHint: 'one of: local,gist',
+    },
+    {
+        key: 'autoFormatBeforePush',
+        description: 'Opt-in: run the project formatter and append a `style:` commit before every `git push`. Off by default because formatting commits surprise OSS maintainers; the hook also skips automatically when the branch tracks a fork upstream.',
+        settableVia: 'setup',
+        valueHint: 'true|false',
+    },
+    // ── Setup-only completion flag ──────────────────────────────────────
+    {
+        key: 'complete',
+        description: 'Internal marker that initial setup has finished. Normally set by the wizard — `setup --set complete=true` is a manual override.',
+        settableVia: 'setup',
+        valueHint: 'true',
+    },
+    // ── Auto-managed (listed for auditability; not user-settable) ────────
+    {
+        key: 'starredRepos',
+        description: 'Cache of the user’s starred repos. Refreshed automatically during discovery.',
+        settableVia: 'auto',
+        valueHint: '(managed internally)',
+    },
+    {
+        key: 'starredReposLastFetched',
+        description: 'Timestamp of the last starredRepos refresh.',
+        settableVia: 'auto',
+        valueHint: '(managed internally)',
+    },
+];
+const KEY_INDEX = new Map(CONFIG_KEY_REGISTRY.map((def) => [def.key, def]));
+export function isKnownKey(key) {
+    return KEY_INDEX.has(key);
+}
+export function getKeyDef(key) {
+    return KEY_INDEX.get(key);
+}
+/** Keys accepted by the `setup --set` command (includes `both`). */
+export function getSetupKeys() {
+    return CONFIG_KEY_REGISTRY.filter((d) => d.settableVia === 'setup' || d.settableVia === 'both').map((d) => d.key);
+}
+/** Keys accepted by the `config <key> <value>` command (includes `both`). */
+export function getConfigKeys() {
+    return CONFIG_KEY_REGISTRY.filter((d) => d.settableVia === 'config' || d.settableVia === 'both').map((d) => d.key);
+}
+/** Classic iterative Levenshtein. O(n*m) time, O(min(n,m)) space. */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // Ensure b is the shorter (minimizes row width).
+    if (a.length < b.length)
+        [a, b] = [b, a];
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, // deletion
+            curr[j - 1] + 1, // insertion
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+/**
+ * Find the closest known key for a typo, limited to keys accepted by the given
+ * CLI surface. Returns `undefined` when no key is close enough (threshold ≤2
+ * edits, case-insensitive) — better to say nothing than suggest a wild guess.
+ */
+export function suggestKey(key, surface) {
+    const candidates = surface === 'setup' ? getSetupKeys() : getConfigKeys();
+    const lower = key.toLowerCase();
+    let best;
+    for (const candidate of candidates) {
+        const d = levenshtein(lower, candidate.toLowerCase());
+        if (best === undefined || d < best.distance) {
+            best = { key: candidate, distance: d };
+        }
+    }
+    if (!best)
+        return undefined;
+    // Allow up to 2 edits, or 3 when the typo is long (≥8 chars) — forgives one swap + one drop.
+    const threshold = key.length >= 8 ? 3 : 2;
+    return best.distance <= threshold ? best.key : undefined;
+}
+/** Format an "unknown key" error, appending a did-you-mean suggestion when confident. */
+export function formatUnknownKeyError(key, surface) {
+    const suggestion = suggestKey(key, surface);
+    const base = surface === 'setup' ? `Unknown setting "${key}"` : `Unknown config key "${key}"`;
+    if (suggestion) {
+        return `${base}. Did you mean "${suggestion}"? Run \`oss-autopilot config --list-keys\` to see all keys.`;
+    }
+    return `${base}. Run \`oss-autopilot config --list-keys\` to see all keys.`;
+}

package/dist/core/dashboard-data-schema.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Runtime schema for the dashboard server's `GET /api/data` response (#1050).
+ *
+ * The server (`commands/dashboard-data.ts`) and client (`packages/dashboard/`)
+ * run in different processes. TypeScript can't cross the process boundary —
+ * if the server removes or renames a field, the client hits runtime
+ * `undefined` with no diagnostic. This schema is the shared runtime contract:
+ * the server can optionally self-check outgoing payloads, and the dashboard
+ * validates every `/api/data` response before committing to state.
+ *
+ * Intentional scope: this schema validates **top-level presence and primitive
+ * shape** (required vs optional fields, container types like array/object),
+ * but uses `z.array(z.unknown())` for nested PR/issue arrays rather than
+ * pinning every field. The top-level surface is the only place drift tends
+ * to go silently undetected — nested fields already blow up loudly at the
+ * render site when they change. Exhaustive nested validation would turn the
+ * schema into a maintenance burden.
+ */
+import { z } from 'zod';
+export declare const DashboardStatsSchema: z.ZodObject<{
+    activePRs: z.ZodNumber;
+    shelvedPRs: z.ZodNumber;
+    mergedPRs: z.ZodNumber;
+    closedPRs: z.ZodNumber;
+    mergeRate: z.ZodString;
+    availableIssues: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const DashboardDataSchema: z.ZodObject<{
+    stats: z.ZodObject<{
+        activePRs: z.ZodNumber;
+        shelvedPRs: z.ZodNumber;
+        mergedPRs: z.ZodNumber;
+        closedPRs: z.ZodNumber;
+        mergeRate: z.ZodString;
+        availableIssues: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    prsByRepo: z.ZodRecord<z.ZodString, z.ZodObject<{
+        active: z.ZodNumber;
+        merged: z.ZodNumber;
+        closed: z.ZodNumber;
+    }, z.core.$strip>>;
+    topRepos: z.ZodArray<z.ZodObject<{
+        repo: z.ZodString;
+        active: z.ZodNumber;
+        merged: z.ZodNumber;
+        closed: z.ZodNumber;
+    }, z.core.$strip>>;
+    monthlyMerged: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    monthlyOpened: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    monthlyClosed: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    activePRs: z.ZodArray<z.ZodUnknown>;
+    shelvedPRUrls: z.ZodArray<z.ZodString>;
+    recentlyMergedPRs: z.ZodArray<z.ZodUnknown>;
+    recentlyClosedPRs: z.ZodArray<z.ZodUnknown>;
+    autoUnshelvedPRs: z.ZodArray<z.ZodUnknown>;
+    commentedIssues: z.ZodArray<z.ZodUnknown>;
+    issueResponses: z.ZodArray<z.ZodUnknown>;
+    allMergedPRs: z.ZodArray<z.ZodUnknown>;
+    allClosedPRs: z.ZodArray<z.ZodUnknown>;
+    repoMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    vettedIssues: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+    offline: z.ZodOptional<z.ZodBoolean>;
+    lastUpdated: z.ZodOptional<z.ZodString>;
+    partialFailures: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type DashboardDataParsed = z.infer<typeof DashboardDataSchema>;
+/**
+ * Validate a raw `/api/data` payload. Returns `{ok: true, data}` on success or
+ * `{ok: false, message}` with a condensed Zod error string on failure. Never
+ * throws. The dashboard's `useDashboard` hook surfaces the message in the UI.
+ */
+export declare function validateDashboardData(raw: unknown): {
+    ok: true;
+    data: DashboardDataParsed;
+} | {
+    ok: false;
+    message: string;
+};