@oss-autopilot/core 3.13.3 → 3.14.0

package/README.md

@@ -30,10 +30,10 @@ oss-autopilot daily --json
 # Check PR status
 oss-autopilot status --json
 
-# Search for contributable issues
-oss-autopilot search "react" --json
+# Search for contributable issues (positional arg = max result count)
+oss-autopilot search 10 --json
 
-# Track a new PR
+# Inspect a PR (read-only metadata lookup — nothing persists)
 oss-autopilot track https://github.com/owner/repo/pull/123
 
 # View help

package/dist/cli-registry.js

@@ -34,6 +34,35 @@ export function handleCommandError(err, json) {
  * duplicated in every command action. Commands with non-standard output
  * modes (e.g. `--compact`, `--markdown`, `--badge`) inline their own
  * branching rather than squeezing through this helper.
+ *
+ * ── `--json` output validation tiers (#1453) ──────────────────────────────
+ *
+ * Two tiers gate the shape of `--json` output. When adding a command, pick
+ * a tier consciously:
+ *
+ * 1. **Runtime-validated**: the registration passes an exported Zod schema
+ *    (from `formatters/json.ts`) as `executeAction`'s 4th argument — or
+ *    calls `outputJsonValidated` directly — so a drifted shape throws at
+ *    the `--json` boundary instead of silently shipping (#1105).
+ *    Commands: manifest, daily, status, strategy, search, features,
+ *    verify-issue, skip-add, list-move-tier, list-mark-done,
+ *    compliance-score, post, claim, config, init, setup, checkSetup,
+ *    parse-issue-list, orphan-files, doctor, local-repos, move,
+ *    pr-template, repo-vet, detect-formatters.
+ *
+ * 2. **Goldens-only**: no Zod schema exists; the command returns a TS
+ *    interface and its `*.contract.test.ts` golden snapshot is the only
+ *    shape gate. Nothing fires at runtime if the producer drifts after
+ *    the goldens were last updated.
+ *    Commands: state (show/sync/unlink), vet, vet-list, track, comments,
+ *    startup, dismiss, undismiss, stats, and the five
+ *    guidelines subcommands (list/view/store/reset/fetch-corpus).
+ *
+ * (`dashboard serve` is exempt: it has no `--json` mode.)
+ *
+ * To promote a command to tier 1: export a Zod schema from
+ * `formatters/json.ts`, assert it in the command's contract test alongside
+ * the goldens, and pass it to `executeAction` here.
  */
 async function executeAction(options, run, display, 
 /** Optional Zod schema. When provided, the JSON output is validated against
@@ -643,7 +672,7 @@ export const commands = [
         register(program) {
             program
                 .command('track <pr-url>')
-                .description('Fetch metadata for a PR (informational — v2 does not maintain a local tracking list)')
+                .description('Inspect a PR (read-only metadata lookup — nothing is persisted; v2 has no local tracking list)')
                 .option('--json', 'Output as JSON')
                 .action((prUrl, options) => executeAction(options, async () => (await import('./commands/track.js')).runTrack({ prUrl }), (data) => {
                 console.log(`\nPR: ${data.pr.repo}#${data.pr.number} - ${data.pr.title}`);
@@ -653,8 +682,9 @@ export const commands = [
         },
     },
     // 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.
+    // `move <pr-url> shelved|auto` to hide/restore PRs in the daily digest.
+    // Scripts that hard-coded these commands now get an "unknown command"
+    // error from commander.
     // ── Compliance Score ───────────────────────────────────────────────────
     {
         name: 'compliance-score',
@@ -1122,39 +1152,8 @@ export const commands = [
             });
         },
     },
-    // ── Shelve ─────────────────────────────────────────────────────────────
-    // Delegates to runShelve so the CLI emits the same `ShelveOutput`
-    // ({shelved, url}) as the library export + MCP tool. Previously it called
-    // runMove and emitted `MoveOutput` ({url, target, description}), which
-    // drifted from the pinned contract test and broke plugin consumers
-    // reading `data.shelved`. See issue #1037.
-    {
-        name: 'shelve',
-        localOnly: true,
-        register(program) {
-            program
-                .command('shelve <pr-url>')
-                .description('Shelve a PR (exclude from capacity and actionable issues)')
-                .option('--json', 'Output as JSON')
-                .action((prUrl, options) => executeAction(options, async () => (await import('./commands/shelve.js')).runShelve({ prUrl }), (data) => {
-                console.log(data.shelved ? `Shelved ${data.url}` : `Already shelved: ${data.url}`);
-            }));
-        },
-    },
-    // ── Unshelve ───────────────────────────────────────────────────────────
-    {
-        name: 'unshelve',
-        localOnly: true,
-        register(program) {
-            program
-                .command('unshelve <pr-url>')
-                .description('Unshelve a PR (include in capacity and actionable issues again)')
-                .option('--json', 'Output as JSON')
-                .action((prUrl, options) => executeAction(options, async () => (await import('./commands/shelve.js')).runUnshelve({ prUrl }), (data) => {
-                console.log(data.unshelved ? `Unshelved ${data.url}` : `Not currently shelved: ${data.url}`);
-            }));
-        },
-    },
+    // The `shelve`/`unshelve` command aliases were retired in #1466 — they
+    // duplicated `move <pr-url> shelved|auto`. Use `move` directly.
     // ── Move ───────────────────────────────────────────────────────────
     {
         name: 'move',
@@ -1164,9 +1163,12 @@ export const commands = [
                 .command('move <pr-url> <target>')
                 .description('Move a PR between states: attention, waiting, shelved, or auto (reset to computed)')
                 .option('--json', 'Output as JSON')
-                .action((prUrl, target, options) => executeAction(options, async () => (await import('./commands/move.js')).runMove({ prUrl, target }), (data) => {
-                console.log(data.description);
-            }));
+                .action(async (prUrl, target, options) => {
+                const { MoveOutputSchema } = await import('./formatters/json.js');
+                await executeAction(options, async () => (await import('./commands/move.js')).runMove({ prUrl, target }), (data) => {
+                    console.log(data.description);
+                }, MoveOutputSchema);
+            });
         },
     },
     // ── Dismiss ────────────────────────────────────────────────────────────
@@ -1210,48 +1212,8 @@ export const commands = [
             }));
         },
     },
-    // ── Override Status ────────────────────────────────────────────────────
-    {
-        name: 'override',
-        localOnly: true,
-        register(program) {
-            program
-                .command('override <pr-url> <status>')
-                .description('Manually override PR status (needs_addressing or waiting_on_maintainer)')
-                .option('--json', 'Output as JSON')
-                .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 ────────────────────────────────────────────────────
-    {
-        name: 'clear-override',
-        localOnly: true,
-        register(program) {
-            program
-                .command('clear-override <pr-url>')
-                .description('Clear a manual status override for a PR')
-                .option('--json', 'Output as JSON')
-                .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);
-            });
-        },
-    },
+    // The `override`/`clear-override` command aliases were retired in #1466 —
+    // they wrapped `move <pr-url> attention|waiting|auto`. Use `move` directly.
     // ── PR Template ──────────────────────────────────────────────────────
     {
         name: 'pr-template',
@@ -1283,7 +1245,7 @@ export const commands = [
         register(program) {
             program
                 .command('repo-vet <repo>')
-                .description('Compute repo health rubric (1–10 score + verdict) for `owner/repo`')
+                .description('Compute the fresh repo health rubric (1–10 score + verdict) for `owner/repo`; includes the cached history score when one exists')
                 .option('--json', 'Output as JSON')
                 .action(async (repo, options) => {
                 const { RepoVetOutputSchema } = await import('./formatters/json.js');
@@ -1293,7 +1255,12 @@ export const commands = [
                         : data.rubricVerdict === 'proceed_with_caution'
                             ? '⚠️'
                             : '❌';
-                    console.log(`\n${verdictEmoji} ${data.repoSlug}: ${data.rubricScore.toFixed(1)}/10 — ${data.rubricVerdict}`);
+                    console.log(`\n${verdictEmoji} ${data.repoSlug}: health ${data.rubricScore.toFixed(1)}/10 — ${data.rubricVerdict}`);
+                    if (data.historyScore !== undefined) {
+                        // Two different 1–10 scores (#1465) — label both so neither
+                        // reads as "the" repo score. See docs/repo-scores.md.
+                        console.log(`  History score (your past PRs here): ${data.historyScore}/10 — cached, distinct from the fresh health score above`);
+                    }
                     console.log(`  Stars: ${data.repoMeta.stars}  Last push: ${data.repoMeta.lastPushed}`);
                     if (data.prMergeTime.medianDays !== null) {
                         console.log(`  Median merge time (90d): ${data.prMergeTime.medianDays.toFixed(1)} days (${data.prMergeTime.sampleSize} samples)`);