@oss-autopilot/core 1.17.4 → 3.0.0

package/dist/cli-registry.js

@@ -9,7 +9,7 @@
  * so that only the invoked command's dependencies are evaluated.
  */
 import { errorMessage, resolveErrorCode } from './core/errors.js';
-import { outputJson, outputJsonError } from './formatters/json.js';
+import { outputJson, outputJsonError, outputJsonValidated } from './formatters/json.js';
 /** Shared error handler for CLI action catch blocks. */
 function handleCommandError(err, json) {
     const msg = errorMessage(err);
@@ -30,11 +30,26 @@ function handleCommandError(err, json) {
  * modes (e.g. `--compact`, `--markdown`, `--badge`) inline their own
  * branching rather than squeezing through this helper.
  */
-async function executeAction(options, run, display) {
+async function executeAction(options, run, display, 
+/** Optional Zod schema. When provided, the JSON output is validated against
+ * it (#1105). On mismatch, executeAction throws and the standard error
+ * envelope fires — surfacing a contract drift instead of silently shipping
+ * a broken shape.
+ *
+ * Typed as `ZodType<unknown>` because validation is a runtime concern: the
+ * schema runs `safeParse(data: unknown)`, and Zod-inferred union types do
+ * not always structurally match hand-written TS union interfaces. The test
+ * harness still catches drift via `safeParse`. */
+schema) {
     try {
         const data = await run();
         if (options.json) {
-            outputJson(data);
+            if (schema) {
+                outputJsonValidated(schema, data);
+            }
+            else {
+                outputJson(data);
+            }
         }
         else {
             await display(data);
@@ -69,11 +84,12 @@ export const commands = [
                         const { runDaily } = await import('./commands/daily.js');
                         const data = await runDaily();
                         if (options.compact) {
-                            const { toCompactDailyOutput } = await import('./formatters/json.js');
-                            outputJson(toCompactDailyOutput(data));
+                            const { toCompactDailyOutput, outputJsonValidated, CompactDailyOutputSchema } = await import('./formatters/json.js');
+                            outputJsonValidated(CompactDailyOutputSchema, toCompactDailyOutput(data));
                         }
                         else {
-                            outputJson(data);
+                            const { outputJsonValidated, DailyOutputSchema } = await import('./formatters/json.js');
+                            outputJsonValidated(DailyOutputSchema, data);
                         }
                     }
                     else {
@@ -98,24 +114,27 @@ export const commands = [
                 .description('Show current status and stats')
                 .option('--json', 'Output as JSON')
                 .option('--offline', 'Show cache-freshness metadata (lastUpdated). Status always reads local state — no GitHub API calls are made either way.')
-                .action((options) => executeAction(options, async () => {
-                const { runStatus } = await import('./commands/status.js');
-                return runStatus({ offline: options.offline });
-            }, (data) => {
-                console.log('\n\ud83d\udcca OSS Status\n');
-                console.log(`Merged PRs: ${data.stats.mergedPRs}`);
-                console.log(`Closed PRs: ${data.stats.closedPRs}`);
-                console.log(`Merge Rate: ${data.stats.mergeRate}`);
-                console.log(`Needs Response: ${data.stats.needsResponse}`);
-                if (data.offline) {
-                    console.log(`\nLast Updated: ${data.lastUpdated || 'Never'}`);
-                    console.log('(Status reads from local state — no GitHub API calls)');
-                }
-                else {
-                    console.log(`\nLast Run: ${data.lastRunAt || 'Never'}`);
-                }
-                console.log('\nRun with --json for structured output');
-            }));
+                .action(async (options) => {
+                const { StatusOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => {
+                    const { runStatus } = await import('./commands/status.js');
+                    return runStatus({ offline: options.offline });
+                }, (data) => {
+                    console.log('\n\ud83d\udcca OSS Status\n');
+                    console.log(`Merged PRs: ${data.stats.mergedPRs}`);
+                    console.log(`Closed PRs: ${data.stats.closedPRs}`);
+                    console.log(`Merge Rate: ${data.stats.mergeRate}`);
+                    console.log(`Needs Response: ${data.stats.needsResponse}`);
+                    if (data.offline) {
+                        console.log(`\nLast Updated: ${data.lastUpdated || 'Never'}`);
+                        console.log('(Status reads from local state — no GitHub API calls)');
+                    }
+                    else {
+                        console.log(`\nLast Run: ${data.lastRunAt || 'Never'}`);
+                    }
+                    console.log('\nRun with --json for structured output');
+                }, StatusOutputSchema);
+            });
         },
     },
     // ── State ──────────────────────────────────────────────────────────────
@@ -124,10 +143,12 @@ export const commands = [
         register(program) {
             program
                 .command('state')
-                .description('Manage state persistence (local/gist)')
+                .description('Manage state persistence (local/gist). Gist mode uses ETag-based optimistic concurrency: ' +
+                'a concurrent push from another machine surfaces as a CONCURRENCY error rather than silently overwriting (#1115).')
                 .option('--show', 'Display current persistence mode and Gist ID')
                 .option('--sync', 'Force push state to Gist (no-op if not in Gist mode)')
                 .option('--unlink', 'Switch from Gist back to local persistence')
+                .option('--validate', 'When used with --show, also report stored PR entries with unparseable URLs')
                 .option('--json', 'Output as JSON')
                 .action(async (options) => {
                 if (options.unlink) {
@@ -152,13 +173,25 @@ export const commands = [
                 }
                 else {
                     // Default: --show
-                    await executeAction(options, async () => (await import('./commands/state-cmd.js')).runStateShow(), (data) => {
+                    await executeAction(options, async () => (await import('./commands/state-cmd.js')).runStateShow({ validate: !!options.validate }), (data) => {
                         console.log(`\nPersistence: ${data.persistence}`);
                         if (data.gistId)
                             console.log(`Gist ID: ${data.gistId}`);
                         if (data.gistDegraded)
                             console.log('Status: DEGRADED (using local cache)');
-                        console.log(`Last run: ${data.lastRunAt ?? 'Never'}\n`);
+                        console.log(`Last run: ${data.lastRunAt ?? 'Never'}`);
+                        if (data.invalidEntries) {
+                            if (data.invalidEntries.length === 0) {
+                                console.log('Validation: no invalid PR URLs in stored state.');
+                            }
+                            else {
+                                console.log(`Validation: ${data.invalidEntries.length} stored PR(s) with invalid URLs:`);
+                                for (const e of data.invalidEntries) {
+                                    console.log(`  [${e.kind}] ${e.url}  ${e.title}`);
+                                }
+                            }
+                        }
+                        console.log('');
                     });
                 }
             });
@@ -172,50 +205,53 @@ export const commands = [
                 .command('search [count]')
                 .description('Search for new issues to work on')
                 .option('--json', 'Output as JSON')
-                .action((count, options) => executeAction(options, async () => {
-                const { runSearch, MAX_SEARCH_RESULTS } = await import('./commands/search.js');
-                let maxResults = 5;
-                if (count !== undefined) {
-                    const parsed = Number(count);
-                    if (!Number.isFinite(parsed) || parsed < 1 || !Number.isInteger(parsed)) {
-                        throw new Error(`Invalid count "${count}". Must be a positive integer.`);
-                    }
-                    maxResults = parsed;
-                }
-                if (maxResults > MAX_SEARCH_RESULTS) {
-                    console.warn(`Capping search to ${MAX_SEARCH_RESULTS} results (requested: ${maxResults})`);
-                    maxResults = MAX_SEARCH_RESULTS;
-                }
-                if (!options.json) {
-                    console.log(`\nSearching for issues (max ${maxResults})...\n`);
-                }
-                return runSearch({ maxResults });
-            }, (data) => {
-                if (data.candidates.length === 0) {
+                .action(async (count, options) => {
+                const { SearchOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => {
+                    const { runSearch, MAX_SEARCH_RESULTS } = await import('./commands/search.js');
+                    let maxResults = 5;
+                    if (count !== undefined) {
+                        const parsed = Number(count);
+                        if (!Number.isFinite(parsed) || parsed < 1 || !Number.isInteger(parsed)) {
+                            throw new Error(`Invalid count "${count}". Must be a positive integer.`);
+                        }
+                        maxResults = parsed;
+                    }
+                    if (maxResults > MAX_SEARCH_RESULTS) {
+                        console.warn(`Capping search to ${MAX_SEARCH_RESULTS} results (requested: ${maxResults})`);
+                        maxResults = MAX_SEARCH_RESULTS;
+                    }
+                    if (!options.json) {
+                        console.log(`\nSearching for issues (max ${maxResults})...\n`);
+                    }
+                    return runSearch({ maxResults });
+                }, (data) => {
+                    if (data.candidates.length === 0) {
+                        if (data.rateLimitWarning) {
+                            console.warn(`\n${data.rateLimitWarning}\n`);
+                        }
+                        else {
+                            console.log('No matching issues found.');
+                        }
+                        return;
+                    }
                     if (data.rateLimitWarning) {
                         console.warn(`\n${data.rateLimitWarning}\n`);
                     }
-                    else {
-                        console.log('No matching issues found.');
+                    console.log(`Found ${data.candidates.length} candidates:\n`);
+                    for (const candidate of data.candidates) {
+                        const { issue, recommendation, reasonsToApprove, reasonsToSkip, viabilityScore } = candidate;
+                        console.log(`[${recommendation.toUpperCase()}] ${issue.repo}#${issue.number}: ${issue.title}`);
+                        console.log(`  URL: ${issue.url}`);
+                        console.log(`  Viability: ${viabilityScore}/100`);
+                        if (reasonsToApprove.length > 0)
+                            console.log(`  Approve: ${reasonsToApprove.join(', ')}`);
+                        if (reasonsToSkip.length > 0)
+                            console.log(`  Skip: ${reasonsToSkip.join(', ')}`);
+                        console.log('---');
                     }
-                    return;
-                }
-                if (data.rateLimitWarning) {
-                    console.warn(`\n${data.rateLimitWarning}\n`);
-                }
-                console.log(`Found ${data.candidates.length} candidates:\n`);
-                for (const candidate of data.candidates) {
-                    const { issue, recommendation, reasonsToApprove, reasonsToSkip, viabilityScore } = candidate;
-                    console.log(`[${recommendation.toUpperCase()}] ${issue.repo}#${issue.number}: ${issue.title}`);
-                    console.log(`  URL: ${issue.url}`);
-                    console.log(`  Viability: ${viabilityScore}/100`);
-                    if (reasonsToApprove.length > 0)
-                        console.log(`  Approve: ${reasonsToApprove.join(', ')}`);
-                    if (reasonsToSkip.length > 0)
-                        console.log(`  Skip: ${reasonsToSkip.join(', ')}`);
-                    console.log('---');
-                }
-            }));
+                }, SearchOutputSchema);
+            });
         },
     },
     // ── Vet ────────────────────────────────────────────────────────────────
@@ -292,16 +328,57 @@ export const commands = [
                 .description('Append an issue URL to the skipped-issues file (idempotent)')
                 .option('--path <file>', 'Skipped-issues file path (falls back to config.skippedIssuesPath)')
                 .option('--json', 'Output as JSON')
-                .action((issueUrl, options) => executeAction(options, async () => (await import('./commands/skip-add.js')).runSkipAdd({ issueUrl, skipFilePath: options.path }), (data) => {
-                if (data.added) {
-                    console.log(`Added to skip list: ${data.url} (${data.date})`);
-                    console.log(`  File: ${data.path}`);
-                }
-                else {
-                    console.log(`Already on skip list: ${data.url}`);
-                    console.log(`  File: ${data.path}`);
-                }
-            }));
+                .action(async (issueUrl, options) => {
+                const { SkipAddOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/skip-add.js')).runSkipAdd({ issueUrl, skipFilePath: options.path }), (data) => {
+                    if (data.added) {
+                        console.log(`Added to skip list: ${data.url} (${data.date})`);
+                        console.log(`  File: ${data.path}`);
+                    }
+                    else {
+                        console.log(`Already on skip list: ${data.url}`);
+                        console.log(`  File: ${data.path}`);
+                    }
+                }, SkipAddOutputSchema);
+            });
+        },
+    },
+    // ── List Move Tier ─────────────────────────────────────────────────────
+    {
+        name: 'list-move-tier',
+        localOnly: true,
+        register(program) {
+            program
+                .command('list-move-tier <issue-url>')
+                .description('Move an issue between Pursue / Maybe / Skip sections of a curated list (#1107)')
+                .requiredOption('--tier <tier>', 'Target tier: pursue, maybe, or skip')
+                .requiredOption('--list-path <file>', 'Path to the markdown issue list')
+                .option('--json', 'Output as JSON')
+                .action(async (issueUrl, options) => {
+                const { ListMoveTierOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => {
+                    const tier = String(options.tier).toLowerCase();
+                    if (tier !== 'pursue' && tier !== 'maybe' && tier !== 'skip') {
+                        throw new Error(`Invalid --tier "${options.tier}". Must be one of: pursue, maybe, skip.`);
+                    }
+                    return (await import('./commands/list-move-tier.js')).runListMoveTier({
+                        issueUrl,
+                        tier,
+                        listPath: options.listPath,
+                    });
+                }, (data) => {
+                    if (data.moved) {
+                        const fromLabel = data.fromTier ? ` (from ${data.fromTier})` : '';
+                        const countLabel = data.count > 1 ? ` × ${data.count}` : '';
+                        console.log(`Moved ${data.url} to ${data.toTier}${fromLabel}${countLabel}`);
+                        console.log(`  File: ${data.filePath}`);
+                    }
+                    else {
+                        console.log(`No move: ${data.url} — ${data.reason ?? 'unchanged'}`);
+                        console.log(`  File: ${data.filePath}`);
+                    }
+                }, ListMoveTierOutputSchema);
+            });
         },
     },
     // ── Track ──────────────────────────────────────────────────────────────
@@ -319,37 +396,9 @@ export const commands = [
             }));
         },
     },
-    // ── Untrack ────────────────────────────────────────────────────────────
-    {
-        name: 'untrack',
-        localOnly: true,
-        register(program) {
-            program
-                .command('untrack <pr-url>')
-                .description('[DEPRECATED] No-op in v2. Use `shelve` to hide a PR from the daily digest.')
-                .option('--json', 'Output as JSON')
-                .action((prUrl, options) => executeAction(options, async () => (await import('./commands/track.js')).runUntrack({ prUrl }), () => {
-                // Stderr so scripts piping stdout don't see the deprecation notice.
-                console.error('[DEPRECATED] `untrack` is a no-op in v2. PRs are fetched fresh on each daily run —');
-                console.error('there is no local tracking list to remove from. Use `shelve` to hide a PR instead.');
-            }));
-        },
-    },
-    // ── Read ───────────────────────────────────────────────────────────────
-    {
-        name: 'read',
-        localOnly: true,
-        register(program) {
-            program
-                .command('read [pr-url]')
-                .description('Mark PR comments as read')
-                .option('--all', 'Mark all PRs as read')
-                .option('--json', 'Output as JSON')
-                .action((prUrl, options) => executeAction(options, async () => (await import('./commands/read.js')).runRead({ prUrl, all: options.all }), () => {
-                console.log('Note: In v2, PR read state is not tracked locally. PRs are fetched fresh on each daily run.');
-            }));
-        },
-    },
+    // The v1→v2 `untrack` and `read` stubs were removed in v4 (#1133). Use
+    // `shelve`/`unshelve` to hide PRs from the daily digest. Scripts that hard-
+    // coded these commands now get an "unknown command" error from commander.
     // ── Comments ───────────────────────────────────────────────────────────
     {
         name: 'comments',
@@ -360,7 +409,7 @@ export const commands = [
                 .option('--bots', 'Include bot comments')
                 .option('--json', 'Output as JSON')
                 .action((prUrl, options) => executeAction(options, async () => (await import('./commands/comments.js')).runComments({ prUrl, showBots: options.bots }), async (data) => {
-                const { formatRelativeTime } = await import('./core/utils.js');
+                const { formatRelativeTime } = await import('./core/dates.js');
                 console.log(`\nFetching comments for: ${prUrl}\n`);
                 console.log(`## ${data.pr.title}\n`);
                 console.log(`**Status:** ${data.pr.state} | **Mergeable:** ${data.pr.mergeable ?? 'checking...'}`);
@@ -415,23 +464,26 @@ export const commands = [
                 .description('Post a comment to a PR or issue')
                 .option('--stdin', 'Read message from stdin')
                 .option('--json', 'Output as JSON')
-                .action((url, messageParts, options) => executeAction(options, async () => {
-                let message;
-                if (options.stdin) {
-                    const chunks = [];
-                    for await (const chunk of process.stdin) {
-                        chunks.push(chunk);
-                    }
-                    message = Buffer.concat(chunks).toString('utf-8').trim();
-                }
-                else {
-                    message = messageParts.join(' ');
-                }
-                const { runPost } = await import('./commands/comments.js');
-                return runPost({ url, message });
-            }, (data) => {
-                console.log(`Comment posted: ${data.commentUrl}`);
-            }));
+                .action(async (url, messageParts, options) => {
+                const { PostOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => {
+                    let message;
+                    if (options.stdin) {
+                        const chunks = [];
+                        for await (const chunk of process.stdin) {
+                            chunks.push(chunk);
+                        }
+                        message = Buffer.concat(chunks).toString('utf-8').trim();
+                    }
+                    else {
+                        message = messageParts.join(' ');
+                    }
+                    const { runPost } = await import('./commands/comments.js');
+                    return runPost({ url, message });
+                }, (data) => {
+                    console.log(`Comment posted: ${data.commentUrl}`);
+                }, PostOutputSchema);
+            });
         },
     },
     // ── Claim ──────────────────────────────────────────────────────────────
@@ -442,13 +494,16 @@ export const commands = [
                 .command('claim <issue-url> [message...]')
                 .description('Claim an issue by posting a comment')
                 .option('--json', 'Output as JSON')
-                .action((issueUrl, messageParts, options) => executeAction(options, async () => {
-                const { runClaim } = await import('./commands/comments.js');
-                const message = messageParts.length > 0 ? messageParts.join(' ') : undefined;
-                return runClaim({ issueUrl, message });
-            }, (data) => {
-                console.log(`Issue claimed: ${data.commentUrl}`);
-            }));
+                .action(async (issueUrl, messageParts, options) => {
+                const { ClaimOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => {
+                    const { runClaim } = await import('./commands/comments.js');
+                    const message = messageParts.length > 0 ? messageParts.join(' ') : undefined;
+                    return runClaim({ issueUrl, message });
+                }, (data) => {
+                    console.log(`Issue claimed: ${data.commentUrl}`);
+                }, ClaimOutputSchema);
+            });
         },
     },
     // ── Config ─────────────────────────────────────────────────────────────
@@ -461,28 +516,31 @@ export const commands = [
                 .description('Show or update configuration')
                 .option('--json', 'Output as JSON')
                 .option('--list-keys', 'List every known config key with descriptions')
-                .action((key, value, options) => executeAction(options, async () => (await import('./commands/config.js')).runConfig({
-                key,
-                value,
-                listKeys: options.listKeys,
-            }), (data) => {
-                if ('keys' in data) {
-                    console.log('\nConfig keys\n');
-                    for (const def of data.keys) {
-                        const flag = def.settableVia === 'auto' ? '(auto)' : `[${def.settableVia}]`;
-                        console.log(`  ${def.key.padEnd(28)} ${flag.padEnd(10)} ${def.description}`);
-                        console.log(`  ${''.padEnd(28)} ${''.padEnd(10)} value: ${def.valueHint}`);
-                    }
-                    console.log('');
-                }
-                else if ('config' in data) {
-                    console.log('\n\u2699\ufe0f Current Configuration:\n');
-                    console.log(JSON.stringify(data.config, null, 2));
-                }
-                else {
-                    console.log(`Set ${data.key} to: ${data.value}`);
-                }
-            }));
+                .action(async (key, value, options) => {
+                const { ConfigCommandOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/config.js')).runConfig({
+                    key,
+                    value,
+                    listKeys: options.listKeys,
+                }), (data) => {
+                    if ('keys' in data) {
+                        console.log('\nConfig keys\n');
+                        for (const def of data.keys) {
+                            const flag = def.settableVia === 'auto' ? '(auto)' : `[${def.settableVia}]`;
+                            console.log(`  ${def.key.padEnd(28)} ${flag.padEnd(10)} ${def.description}`);
+                            console.log(`  ${''.padEnd(28)} ${''.padEnd(10)} value: ${def.valueHint}`);
+                        }
+                        console.log('');
+                    }
+                    else if ('config' in data) {
+                        console.log('\n\u2699\ufe0f Current Configuration:\n');
+                        console.log(JSON.stringify(data.config, null, 2));
+                    }
+                    else {
+                        console.log(`Set ${data.key} to: ${data.value}`);
+                    }
+                }, ConfigCommandOutputSchema);
+            });
         },
     },
     // ── Init ───────────────────────────────────────────────────────────────
@@ -493,10 +551,13 @@ export const commands = [
                 .command('init <username>')
                 .description('Initialize with your GitHub username and import open PRs')
                 .option('--json', 'Output as JSON')
-                .action((username, options) => executeAction(options, async () => (await import('./commands/init.js')).runInit({ username }), (data) => {
-                console.log(`\nUsername set to @${data.username}.`);
-                console.log('Run `oss-autopilot daily` to fetch your open PRs from GitHub.');
-            }));
+                .action(async (username, options) => {
+                const { InitOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/init.js')).runInit({ username }), (data) => {
+                    console.log(`\nUsername set to @${data.username}.`);
+                    console.log('Run `oss-autopilot daily` to fetch your open PRs from GitHub.');
+                }, InitOutputSchema);
+            });
         },
     },
     // ── Setup ──────────────────────────────────────────────────────────────
@@ -510,56 +571,59 @@ export const commands = [
                 .option('--reset', 'Re-run setup even if already complete')
                 .option('--set <settings...>', 'Set specific values (key=value)')
                 .option('--json', 'Output as JSON')
-                .action((options) => executeAction(options, async () => (await import('./commands/setup.js')).runSetup({ reset: options.reset, set: options.set }), (data) => {
-                if ('success' in data) {
-                    // --set mode
-                    for (const [key, value] of Object.entries(data.settings)) {
-                        console.log(`\u2713 ${key}: ${value}`);
-                    }
-                    if (data.warnings) {
-                        for (const w of data.warnings) {
-                            console.warn(w);
+                .action(async (options) => {
+                const { SetupOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/setup.js')).runSetup({ reset: options.reset, set: options.set }), (data) => {
+                    if ('success' in data) {
+                        // --set mode
+                        for (const [key, value] of Object.entries(data.settings)) {
+                            console.log(`\u2713 ${key}: ${value}`);
+                        }
+                        if (data.warnings) {
+                            for (const w of data.warnings) {
+                                console.warn(w);
+                            }
                         }
                     }
-                }
-                else if ('setupComplete' in data && data.setupComplete) {
-                    // Already complete
-                    console.log('\n\u2699\ufe0f  OSS Autopilot Setup\n');
-                    console.log('\u2713 Setup already complete!\n');
-                    console.log('Current settings:');
-                    console.log(`  GitHub username:    ${data.config.githubUsername || '(not set)'}`);
-                    console.log(`  Max active PRs:     ${data.config.maxActivePRs}`);
-                    console.log(`  Dormant threshold:  ${data.config.dormantThresholdDays} days`);
-                    console.log(`  Approaching dormant: ${data.config.approachingDormantDays} days`);
-                    console.log(`  Languages:          ${data.config.languages.join(', ')}`);
-                    console.log(`  Labels:             ${data.config.labels.join(', ')}`);
-                    console.log(`\nRun 'setup --reset' to reconfigure.`);
-                }
-                else if ('setupRequired' in data) {
-                    // Needs setup
-                    console.log('\n\u2699\ufe0f  OSS Autopilot Setup\n');
-                    console.log('SETUP_REQUIRED');
-                    console.log('---');
-                    console.log('Please configure the following settings:\n');
-                    for (const prompt of data.prompts) {
-                        console.log(`SETTING: ${prompt.setting}`);
-                        console.log(`PROMPT: ${prompt.prompt}`);
-                        const currentVal = Array.isArray(prompt.current) ? prompt.current.join(', ') : prompt.current;
-                        console.log(`CURRENT: ${currentVal ?? '(not set)'}`);
-                        if (prompt.required)
-                            console.log('REQUIRED: true');
-                        if (prompt.default !== undefined) {
-                            const defaultVal = Array.isArray(prompt.default) ? prompt.default.join(', ') : prompt.default;
-                            console.log(`DEFAULT: ${defaultVal}`);
+                    else if ('setupComplete' in data && data.setupComplete) {
+                        // Already complete
+                        console.log('\n\u2699\ufe0f  OSS Autopilot Setup\n');
+                        console.log('\u2713 Setup already complete!\n');
+                        console.log('Current settings:');
+                        console.log(`  GitHub username:    ${data.config.githubUsername || '(not set)'}`);
+                        console.log(`  Max active PRs:     ${data.config.maxActivePRs}`);
+                        console.log(`  Dormant threshold:  ${data.config.dormantThresholdDays} days`);
+                        console.log(`  Approaching dormant: ${data.config.approachingDormantDays} days`);
+                        console.log(`  Languages:          ${data.config.languages.join(', ')}`);
+                        console.log(`  Labels:             ${data.config.labels.join(', ')}`);
+                        console.log(`\nRun 'setup --reset' to reconfigure.`);
+                    }
+                    else if ('setupRequired' in data) {
+                        // Needs setup
+                        console.log('\n\u2699\ufe0f  OSS Autopilot Setup\n');
+                        console.log('SETUP_REQUIRED');
+                        console.log('---');
+                        console.log('Please configure the following settings:\n');
+                        for (const prompt of data.prompts) {
+                            console.log(`SETTING: ${prompt.setting}`);
+                            console.log(`PROMPT: ${prompt.prompt}`);
+                            const currentVal = Array.isArray(prompt.current) ? prompt.current.join(', ') : prompt.current;
+                            console.log(`CURRENT: ${currentVal ?? '(not set)'}`);
+                            if (prompt.required)
+                                console.log('REQUIRED: true');
+                            if (prompt.default !== undefined) {
+                                const defaultVal = Array.isArray(prompt.default) ? prompt.default.join(', ') : prompt.default;
+                                console.log(`DEFAULT: ${defaultVal}`);
+                            }
+                            if (prompt.type)
+                                console.log(`TYPE: ${prompt.type}`);
+                            console.log('');
                         }
-                        if (prompt.type)
-                            console.log(`TYPE: ${prompt.type}`);
-                        console.log('');
+                        console.log('---');
+                        console.log('END_SETUP_PROMPTS');
                     }
-                    console.log('---');
-                    console.log('END_SETUP_PROMPTS');
-                }
-            }));
+                }, SetupOutputSchema);
+            });
         },
     },
     // ── Check Setup ────────────────────────────────────────────────────────
@@ -571,15 +635,18 @@ export const commands = [
                 .command('checkSetup')
                 .description('Check if setup is complete')
                 .option('--json', 'Output as JSON')
-                .action((options) => executeAction(options, async () => (await import('./commands/setup.js')).runCheckSetup(), (data) => {
-                if (data.setupComplete) {
-                    console.log('SETUP_COMPLETE');
-                    console.log(`username=${data.username}`);
-                }
-                else {
-                    console.log('SETUP_INCOMPLETE');
-                }
-            }));
+                .action(async (options) => {
+                const { CheckSetupOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/setup.js')).runCheckSetup(), (data) => {
+                    if (data.setupComplete) {
+                        console.log('SETUP_COMPLETE');
+                        console.log(`username=${data.username}`);
+                    }
+                    else {
+                        console.log('SETUP_INCOMPLETE');
+                    }
+                }, CheckSetupOutputSchema);
+            });
         },
     },
     // ── Dashboard Serve ────────────────────────────────────────────────────
@@ -618,24 +685,27 @@ export const commands = [
                 .command('parse-issue-list <path>')
                 .description('Parse a markdown issue list into structured JSON')
                 .option('--json', 'Output as JSON')
-                .action((filePath, options) => executeAction(options, async () => (await import('./commands/parse-list.js')).runParseList({ filePath }), async (data) => {
-                const path = await import('path');
-                const resolvedPath = path.resolve(filePath);
-                console.log(`\n\ud83d\udccb Issue List: ${resolvedPath}\n`);
-                console.log(`Available: ${data.availableCount} | Completed: ${data.completedCount}\n`);
-                if (data.available.length > 0) {
-                    console.log('--- Available ---');
-                    for (const item of data.available) {
-                        console.log(`  [${item.tier}] ${item.repo}#${item.number}: ${item.title}`);
+                .action(async (filePath, options) => {
+                const { ParseIssueListOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/parse-list.js')).runParseList({ filePath }), async (data) => {
+                    const path = await import('path');
+                    const resolvedPath = path.resolve(filePath);
+                    console.log(`\n\ud83d\udccb Issue List: ${resolvedPath}\n`);
+                    console.log(`Available: ${data.availableCount} | Completed: ${data.completedCount}\n`);
+                    if (data.available.length > 0) {
+                        console.log('--- Available ---');
+                        for (const item of data.available) {
+                            console.log(`  [${item.tier}] ${item.repo}#${item.number}: ${item.title}`);
+                        }
                     }
-                }
-                if (data.completed.length > 0) {
-                    console.log('\n--- Completed ---');
-                    for (const item of data.completed) {
-                        console.log(`  [${item.tier}] ${item.repo}#${item.number}: ${item.title}`);
+                    if (data.completed.length > 0) {
+                        console.log('\n--- Completed ---');
+                        for (const item of data.completed) {
+                            console.log(`  [${item.tier}] ${item.repo}#${item.number}: ${item.title}`);
+                        }
                     }
-                }
-            }));
+                }, ParseIssueListOutputSchema);
+            });
         },
     },
     // ── Check Integration ──────────────────────────────────────────────────
@@ -649,27 +719,30 @@ export const commands = [
                 .description('Detect new files on this branch that no other file references')
                 .option('--base <branch>', 'Base branch to compare against', 'main')
                 .option('--json', 'Output as JSON')
-                .action((options) => executeAction(options, async () => (await import('./commands/check-integration.js')).runCheckIntegration({ base: options.base }), (data) => {
-                if (data.newFiles.length === 0) {
-                    console.log('\nNo new code files to check.');
-                    return;
-                }
-                console.log(`\n\ud83d\udd0d Integration Check (base: ${options.base})\n`);
-                console.log(`New files: ${data.newFiles.length} | Unreferenced: ${data.unreferencedCount}\n`);
-                for (const file of data.newFiles) {
-                    const status = file.isIntegrated ? '\u2705' : '\u26a0\ufe0f';
-                    console.log(`${status} ${file.path}`);
-                    if (file.isIntegrated) {
-                        console.log(`   Referenced by: ${file.referencedBy.join(', ')}`);
+                .action(async (options) => {
+                const { CheckIntegrationOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/check-integration.js')).runCheckIntegration({ base: options.base }), (data) => {
+                    if (data.newFiles.length === 0) {
+                        console.log('\nNo new code files to check.');
+                        return;
                     }
-                    else {
-                        console.log('   Not referenced by any file');
-                        if (file.suggestedEntryPoints && file.suggestedEntryPoints.length > 0) {
-                            console.log(`   Suggested entry points: ${file.suggestedEntryPoints.join(', ')}`);
+                    console.log(`\n\ud83d\udd0d Integration Check (base: ${options.base})\n`);
+                    console.log(`New files: ${data.newFiles.length} | Unreferenced: ${data.unreferencedCount}\n`);
+                    for (const file of data.newFiles) {
+                        const status = file.isIntegrated ? '\u2705' : '\u26a0\ufe0f';
+                        console.log(`${status} ${file.path}`);
+                        if (file.isIntegrated) {
+                            console.log(`   Referenced by: ${file.referencedBy.join(', ')}`);
+                        }
+                        else {
+                            console.log('   Not referenced by any file');
+                            if (file.suggestedEntryPoints && file.suggestedEntryPoints.length > 0) {
+                                console.log(`   Suggested entry points: ${file.suggestedEntryPoints.join(', ')}`);
+                            }
                         }
                     }
-                }
-            }));
+                }, CheckIntegrationOutputSchema);
+            });
         },
     },
     // ── Doctor ─────────────────────────────────────────────────────────────
@@ -681,17 +754,20 @@ export const commands = [
                 .command('doctor')
                 .description('Run a system-health diagnostic (token, bundle, state, scout, rate limit)')
                 .option('--json', 'Output as JSON')
-                .action((options) => executeAction(options, async () => (await import('./commands/doctor.js')).runDoctor(), (data) => {
-                console.log('\nSystem health\n');
-                for (const check of data.checks) {
-                    const icon = check.status === 'ok' ? '[OK]   ' : check.status === 'warning' ? '[WARN] ' : '[ERR]  ';
-                    console.log(`${icon}${check.name}: ${check.message}`);
-                    if (check.remediation) {
-                        console.log(`       ↳ ${check.remediation}`);
+                .action(async (options) => {
+                const { DoctorOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/doctor.js')).runDoctor(), (data) => {
+                    console.log('\nSystem health\n');
+                    for (const check of data.checks) {
+                        const icon = check.status === 'ok' ? '[OK]   ' : check.status === 'warning' ? '[WARN] ' : '[ERR]  ';
+                        console.log(`${icon}${check.name}: ${check.message}`);
+                        if (check.remediation) {
+                            console.log(`       ↳ ${check.remediation}`);
+                        }
                     }
-                }
-                console.log(`\n${data.summary.ok} ok / ${data.summary.warnings} warning / ${data.summary.errors} error\n`);
-            }));
+                    console.log(`\n${data.summary.ok} ok / ${data.summary.warnings} warning / ${data.summary.errors} error\n`);
+                }, DoctorOutputSchema);
+            });
         },
     },
     // ── Local Repos ────────────────────────────────────────────────────────
@@ -705,19 +781,22 @@ export const commands = [
                 .option('--scan', 'Force re-scan (ignores cache)')
                 .option('--paths <dirs...>', 'Directories to scan')
                 .option('--json', 'Output as JSON')
-                .action((options) => executeAction(options, async () => (await import('./commands/local-repos.js')).runLocalRepos({
-                scan: options.scan,
-                paths: options.paths,
-            }), (data) => {
-                if (data.fromCache) {
-                    console.log(`\n\ud83d\udcc1 Local Repos (cached ${data.cachedAt})\n`);
-                    printRepos(data.repos);
-                }
-                else {
-                    console.log(`Found ${Object.keys(data.repos).length} repos:\n`);
-                    printRepos(data.repos);
-                }
-            }));
+                .action(async (options) => {
+                const { LocalReposOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/local-repos.js')).runLocalRepos({
+                    scan: options.scan,
+                    paths: options.paths,
+                }), (data) => {
+                    if (data.fromCache) {
+                        console.log(`\n\ud83d\udcc1 Local Repos (cached ${data.cachedAt})\n`);
+                        printRepos(data.repos);
+                    }
+                    else {
+                        console.log(`Found ${Object.keys(data.repos).length} repos:\n`);
+                        printRepos(data.repos);
+                    }
+                }, LocalReposOutputSchema);
+            });
         },
     },
     // ── Startup ────────────────────────────────────────────────────────────
@@ -859,17 +938,20 @@ export const commands = [
                 .command('override <pr-url> <status>')
                 .description('Manually override PR status (needs_addressing or waiting_on_maintainer)')
                 .option('--json', 'Output as JSON')
-                .action((prUrl, status, options) => executeAction(options, async () => {
-                const validStatuses = ['needs_addressing', 'waiting_on_maintainer'];
-                if (!validStatuses.includes(status)) {
-                    throw new Error(`Invalid status "${status}". Must be one of: ${validStatuses.join(', ')}`);
-                }
-                const target = status === 'needs_addressing' ? 'attention' : 'waiting';
-                const { runMove } = await import('./commands/move.js');
-                return runMove({ prUrl, target });
-            }, (data) => {
-                console.log(data.description);
-            }));
+                .action(async (prUrl, status, options) => {
+                const { MoveOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => {
+                    const validStatuses = ['needs_addressing', 'waiting_on_maintainer'];
+                    if (!validStatuses.includes(status)) {
+                        throw new Error(`Invalid status "${status}". Must be one of: ${validStatuses.join(', ')}`);
+                    }
+                    const target = status === 'needs_addressing' ? 'attention' : 'waiting';
+                    const { runMove } = await import('./commands/move.js');
+                    return runMove({ prUrl, target });
+                }, (data) => {
+                    console.log(data.description);
+                }, MoveOutputSchema);
+            });
         },
     },
     // ── Clear Override ────────────────────────────────────────────────────
@@ -881,9 +963,12 @@ export const commands = [
                 .command('clear-override <pr-url>')
                 .description('Clear a manual status override for a PR')
                 .option('--json', 'Output as JSON')
-                .action((prUrl, options) => executeAction(options, async () => (await import('./commands/move.js')).runMove({ prUrl, target: 'auto' }), (data) => {
-                console.log(data.description);
-            }));
+                .action(async (prUrl, options) => {
+                const { MoveOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/move.js')).runMove({ prUrl, target: 'auto' }), (data) => {
+                    console.log(data.description);
+                }, MoveOutputSchema);
+            });
         },
     },
     // ── PR Template ──────────────────────────────────────────────────────
@@ -894,18 +979,21 @@ export const commands = [
                 .command('pr-template <repo>')
                 .description("Fetch a repository's PR description template")
                 .option('--json', 'Output as JSON')
-                .action((repo, options) => executeAction(options, async () => (await import('./commands/pr-template.js')).runPRTemplate({ repo }), (data) => {
-                if (data.template) {
-                    console.log(`\nPR template found at: ${data.source}\n`);
-                    console.log(data.template);
-                }
-                else if (data.error) {
-                    console.error(`\nWarning: Could not check for PR template: ${data.error}`);
-                }
-                else {
-                    console.log('\nNo PR template found for this repository.');
-                }
-            }));
+                .action(async (repo, options) => {
+                const { PRTemplateOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/pr-template.js')).runPRTemplate({ repo }), (data) => {
+                    if (data.template) {
+                        console.log(`\nPR template found at: ${data.source}\n`);
+                        console.log(data.template);
+                    }
+                    else if (data.error) {
+                        console.error(`\nWarning: Could not check for PR template: ${data.error}`);
+                    }
+                    else {
+                        console.log('\nNo PR template found for this repository.');
+                    }
+                }, PRTemplateOutputSchema);
+            });
         },
     },
     // ── Detect Formatters ────────────────────────────────────────────────
@@ -918,39 +1006,42 @@ export const commands = [
                 .description('Detect formatters and linters configured in a repository')
                 .option('--ci-log <path>', 'Analyze CI log file for formatting failures')
                 .option('--json', 'Output as JSON')
-                .action((repoPath, options) => executeAction(options, async () => (await import('./commands/detect-formatters.js')).runDetectFormatters({
-                repoPath,
-                ciLog: options.ciLog,
-            }), (data) => {
-                if (data.formatters.length === 0) {
-                    console.log('\nNo formatters detected.');
-                }
-                else {
-                    console.log(`\nDetected ${data.formatters.length} formatter(s):\n`);
-                    for (const f of data.formatters) {
-                        console.log(`  ${f.name} (${f.configPath})`);
-                        console.log(`    Fix:   ${f.fixCommand}`);
-                        console.log(`    Check: ${f.checkCommand}`);
+                .action(async (repoPath, options) => {
+                const { DetectFormattersOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/detect-formatters.js')).runDetectFormatters({
+                    repoPath,
+                    ciLog: options.ciLog,
+                }), (data) => {
+                    if (data.formatters.length === 0) {
+                        console.log('\nNo formatters detected.');
                     }
-                }
-                if (data.packageJsonScripts.length > 0) {
-                    console.log('\npackage.json scripts:');
-                    for (const s of data.packageJsonScripts) {
-                        console.log(`  ${s.name}: ${s.command}`);
+                    else {
+                        console.log(`\nDetected ${data.formatters.length} formatter(s):\n`);
+                        for (const f of data.formatters) {
+                            console.log(`  ${f.name} (${f.configPath})`);
+                            console.log(`    Fix:   ${f.fixCommand}`);
+                            console.log(`    Check: ${f.checkCommand}`);
+                        }
                     }
-                }
-                if (data.ciDiagnosis) {
-                    console.log('');
-                    if (data.ciDiagnosis.isFormattingFailure) {
-                        console.log(`CI Diagnosis: Formatting failure detected (${data.ciDiagnosis.formatter})`);
-                        console.log(`  Fix: ${data.ciDiagnosis.fixCommand}`);
-                        console.log(`  Evidence: ${data.ciDiagnosis.evidence.join(', ')}`);
+                    if (data.packageJsonScripts.length > 0) {
+                        console.log('\npackage.json scripts:');
+                        for (const s of data.packageJsonScripts) {
+                            console.log(`  ${s.name}: ${s.command}`);
+                        }
                     }
-                    else {
-                        console.log('CI Diagnosis: No formatting failure detected.');
+                    if (data.ciDiagnosis) {
+                        console.log('');
+                        if (data.ciDiagnosis.isFormattingFailure) {
+                            console.log(`CI Diagnosis: Formatting failure detected (${data.ciDiagnosis.formatter})`);
+                            console.log(`  Fix: ${data.ciDiagnosis.fixCommand}`);
+                            console.log(`  Evidence: ${data.ciDiagnosis.evidence.join(', ')}`);
+                        }
+                        else {
+                            console.log('CI Diagnosis: No formatting failure detected.');
+                        }
                     }
-                }
-            }));
+                }, DetectFormattersOutputSchema);
+            });
         },
     },
     // ── Stats ─────────────────────────────────────────────────────────────