@oss-autopilot/core 3.8.0 → 3.10.0

package/dist/commands/index.d.ts

@@ -21,6 +21,8 @@ export { executeDailyCheck } from './daily.js';
 export { runStartup } from './startup.js';
 /** Return contribution statistics (merge rate, PR counts, repo breakdown) from local state. */
 export { runStatus } from './status.js';
+/** On-demand strategy snapshot via the typed `computeStrategy` core function (#1243 step 4). */
+export { runStrategy } from './strategy.js';
 /** Search GitHub for contributable issues using multi-strategy discovery. */
 export { runSearch, MAX_SEARCH_RESULTS } from './search.js';
 /** Surface feature-scoped opportunities in repos with 3+ merged PRs (scout 0.9.0). */

package/dist/commands/index.js

@@ -22,6 +22,8 @@ export { executeDailyCheck } from './daily.js';
 export { runStartup } from './startup.js';
 /** Return contribution statistics (merge rate, PR counts, repo breakdown) from local state. */
 export { runStatus } from './status.js';
+/** On-demand strategy snapshot via the typed `computeStrategy` core function (#1243 step 4). */
+export { runStrategy } from './strategy.js';
 /** Search GitHub for contributable issues using multi-strategy discovery. */
 export { runSearch, MAX_SEARCH_RESULTS } from './search.js';
 /** Surface feature-scoped opportunities in repos with 3+ merged PRs (scout 0.9.0). */

package/dist/commands/search.js

@@ -5,7 +5,8 @@
 import { buildCandidateLinkedPR, createAutopilotScout } from './scout-bridge.js';
 import { getStateManager } from '../core/index.js';
 import { gradeFromCandidate } from '../core/issue-grading.js';
-import { warn } from '../core/logger.js';
+import { computeStrategy } from '../core/strategy.js';
+import { debug, warn } from '../core/logger.js';
 const MODULE = 'search';
 /**
  * Hard cap on issue-search result count. Shared between CLI (`cli-registry.ts`),
@@ -46,8 +47,23 @@ function sanitizeViabilityScore(raw) {
 }
 export async function runSearch(options) {
     const scout = await createAutopilotScout();
-    const result = await scout.search({ maxResults: options.maxResults });
     const stateManager = getStateManager();
+    // Derive personalization from local history (#1244). `computeStrategy`
+    // returns null below the merged-PR floor — in that case we pass nothing
+    // and scout's sort behaves exactly as before. Once strategy data is
+    // available, scout boosts language/repo matches into a separate sort
+    // tier (still no filtering).
+    const strategy = computeStrategy(stateManager.getState());
+    const preferLanguages = strategy?.recommendations.languages ?? undefined;
+    const preferRepos = strategy?.recommendations.repos ?? undefined;
+    if (preferLanguages?.length || preferRepos?.length) {
+        debug(MODULE, `Applying strategy bias to search: preferLanguages=${JSON.stringify(preferLanguages ?? [])}, preferRepos=${JSON.stringify(preferRepos ?? [])}`);
+    }
+    const result = await scout.search({
+        maxResults: options.maxResults,
+        preferLanguages,
+        preferRepos,
+    });
     const searchOutput = {
         candidates: result.candidates.map((c) => {
             const repoScoreRecord = stateManager.getRepoScore(c.issue.repo);
@@ -97,6 +113,8 @@ export async function runSearch(options) {
                     }
                     : undefined,
                 ...(linkedPR ? { linkedPR } : {}),
+                ...(typeof c.boostScore === 'number' ? { boostScore: c.boostScore } : {}),
+                ...(c.boostReasons && c.boostReasons.length > 0 ? { boostReasons: c.boostReasons } : {}),
             };
         }),
         excludedRepos: result.excludedRepos,

package/dist/commands/strategy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * strategy command (#1243 step 4).
+ *
+ * Runs the typed `computeStrategy` core function against local state on
+ * demand. The daily auto-display already emits `strategySummary` under
+ * a cadence gate; this command is the *ungated* path used by the
+ * `contribution-strategist` agent so a user asking "how am I doing?"
+ * always gets an answer (or a clear "not enough data yet" message) even
+ * when the daily cadence has not fired.
+ *
+ * Read-only: no API calls, no state mutation.
+ */
+import { type StrategyResult } from '../core/strategy.js';
+/**
+ * On-demand strategy snapshot. Mirrors `StrategyOutputSchema` in
+ * `formatters/json.ts` structurally — that schema uses `.passthrough()`
+ * for forward compatibility on the JSON-validation surface, so its
+ * inferred type carries an extra `unknown` index signature that does
+ * not match `StrategyResult`. The command's TypeScript shape is the
+ * exact structural form below.
+ */
+export interface StrategyCommandOutput {
+    strategy: StrategyResult | null;
+    message?: string;
+}
+/**
+ * Compute the on-demand strategy snapshot. Returns `{ strategy: null,
+ * message }` when state is below the merged-PR floor, and `{ strategy }`
+ * with the full typed result otherwise.
+ */
+export declare function runStrategy(): Promise<StrategyCommandOutput>;

package/dist/commands/strategy.js

@@ -0,0 +1,33 @@
+/**
+ * strategy command (#1243 step 4).
+ *
+ * Runs the typed `computeStrategy` core function against local state on
+ * demand. The daily auto-display already emits `strategySummary` under
+ * a cadence gate; this command is the *ungated* path used by the
+ * `contribution-strategist` agent so a user asking "how am I doing?"
+ * always gets an answer (or a clear "not enough data yet" message) even
+ * when the daily cadence has not fired.
+ *
+ * Read-only: no API calls, no state mutation.
+ */
+import { getStateManager } from '../core/index.js';
+import { computeStrategy, STRATEGY_MIN_PRS } from '../core/strategy.js';
+/**
+ * Compute the on-demand strategy snapshot. Returns `{ strategy: null,
+ * message }` when state is below the merged-PR floor, and `{ strategy }`
+ * with the full typed result otherwise.
+ */
+export async function runStrategy() {
+    const stateManager = getStateManager();
+    const state = stateManager.getState();
+    const strategy = computeStrategy(state);
+    if (strategy === null) {
+        const merged = state.mergedPRs?.length ?? 0;
+        return {
+            strategy: null,
+            message: `Strategy snapshot needs at least ${STRATEGY_MIN_PRS} merged PRs in local state; ` +
+                `currently tracking ${merged}. Keep contributing and the snapshot becomes available automatically.`,
+        };
+    }
+    return { strategy };
+}

package/dist/formatters/json.d.ts

@@ -184,6 +184,106 @@ export declare const StatusOutputSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type StatusOutput = z.infer<typeof StatusOutputSchema>;
+export declare const StrategyResultSchema: z.ZodObject<{
+    profile: z.ZodObject<{
+        style: z.ZodEnum<{
+            maintainer: "maintainer";
+            explorer: "explorer";
+            specialist: "specialist";
+            generalist: "generalist";
+        }>;
+        totalPRs: z.ZodNumber;
+        mergedCount: z.ZodNumber;
+        mergeRate: z.ZodNumber;
+        primaryLanguages: z.ZodArray<z.ZodString>;
+        favoriteRepos: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    capacity: z.ZodObject<{
+        openPRCount: z.ZodNumber;
+        dormantPRCount: z.ZodNumber;
+        dormantRepoCount: z.ZodNumber;
+        overExtended: z.ZodBoolean;
+        suggestedAction: z.ZodUnion<readonly [z.ZodLiteral<"open_more">, z.ZodLiteral<"follow_up_dormant">, z.ZodLiteral<"wait_on_maintainers">, z.ZodNull]>;
+    }, z.core.$loose>;
+    patterns: z.ZodObject<{
+        prTypeDistribution: z.ZodObject<{
+            docs: z.ZodNumber;
+            fixes: z.ZodNumber;
+            features: z.ZodNumber;
+            refactors: z.ZodNumber;
+            tests: z.ZodNumber;
+            other: z.ZodNumber;
+        }, z.core.$loose>;
+        trajectoryDirection: z.ZodEnum<{
+            growing: "growing";
+            steady: "steady";
+            declining: "declining";
+        }>;
+        averagePRSize: z.ZodNumber;
+    }, z.core.$loose>;
+    recommendations: z.ZodObject<{
+        languages: z.ZodArray<z.ZodString>;
+        repos: z.ZodArray<z.ZodString>;
+        issueTypes: z.ZodArray<z.ZodString>;
+        avoidPatterns: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/**
+ * On-demand strategy snapshot output (#1243 step 4). Wraps the same
+ * `StrategyResult` shape consumed by the daily auto-display, but is
+ * always available — the cadence gate only governs the auto-display,
+ * not direct CLI/MCP calls. `strategy` is null when the minimum-data
+ * gate fails (fewer than `STRATEGY_MIN_PRS` merged PRs); `message`
+ * carries the human-readable explanation in that case.
+ */
+export declare const StrategyOutputSchema: z.ZodObject<{
+    strategy: z.ZodNullable<z.ZodObject<{
+        profile: z.ZodObject<{
+            style: z.ZodEnum<{
+                maintainer: "maintainer";
+                explorer: "explorer";
+                specialist: "specialist";
+                generalist: "generalist";
+            }>;
+            totalPRs: z.ZodNumber;
+            mergedCount: z.ZodNumber;
+            mergeRate: z.ZodNumber;
+            primaryLanguages: z.ZodArray<z.ZodString>;
+            favoriteRepos: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+        capacity: z.ZodObject<{
+            openPRCount: z.ZodNumber;
+            dormantPRCount: z.ZodNumber;
+            dormantRepoCount: z.ZodNumber;
+            overExtended: z.ZodBoolean;
+            suggestedAction: z.ZodUnion<readonly [z.ZodLiteral<"open_more">, z.ZodLiteral<"follow_up_dormant">, z.ZodLiteral<"wait_on_maintainers">, z.ZodNull]>;
+        }, z.core.$loose>;
+        patterns: z.ZodObject<{
+            prTypeDistribution: z.ZodObject<{
+                docs: z.ZodNumber;
+                fixes: z.ZodNumber;
+                features: z.ZodNumber;
+                refactors: z.ZodNumber;
+                tests: z.ZodNumber;
+                other: z.ZodNumber;
+            }, z.core.$loose>;
+            trajectoryDirection: z.ZodEnum<{
+                growing: "growing";
+                steady: "steady";
+                declining: "declining";
+            }>;
+            averagePRSize: z.ZodNumber;
+        }, z.core.$loose>;
+        recommendations: z.ZodObject<{
+            languages: z.ZodArray<z.ZodString>;
+            repos: z.ZodArray<z.ZodString>;
+            issueTypes: z.ZodArray<z.ZodString>;
+            avoidPatterns: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    }, z.core.$loose>>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StrategyCommandOutput = z.infer<typeof StrategyOutputSchema>;
 export declare const DailyOutputSchema: z.ZodObject<{
     digest: z.ZodObject<{
         generatedAt: z.ZodString;
@@ -520,6 +620,8 @@ export declare const SearchOutputSchema: z.ZodObject<{
             updatedAt: z.ZodOptional<z.ZodString>;
             isStalled: z.ZodBoolean;
         }, z.core.$strip>>;
+        boostScore: z.ZodOptional<z.ZodNumber>;
+        boostReasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     excludedRepos: z.ZodArray<z.ZodString>;
     aiPolicyBlocklist: z.ZodArray<z.ZodString>;
@@ -576,6 +678,8 @@ export declare const FeaturesOutputSchema: z.ZodObject<{
             updatedAt: z.ZodOptional<z.ZodString>;
             isStalled: z.ZodBoolean;
         }, z.core.$strip>>;
+        boostScore: z.ZodOptional<z.ZodNumber>;
+        boostReasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
         horizon: z.ZodEnum<{
             "quick-win": "quick-win";
             "bigger-bet": "bigger-bet";
@@ -631,6 +735,8 @@ export declare const FeaturesOutputSchema: z.ZodObject<{
             updatedAt: z.ZodOptional<z.ZodString>;
             isStalled: z.ZodBoolean;
         }, z.core.$strip>>;
+        boostScore: z.ZodOptional<z.ZodNumber>;
+        boostReasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
         horizon: z.ZodEnum<{
             "quick-win": "quick-win";
             "bigger-bet": "bigger-bet";

package/dist/formatters/json.js

@@ -202,7 +202,7 @@ const CompactRepoGroupSchema = z.object({
 // Mirrors {@link StrategyResult} in core/strategy.ts. Kept passthrough on the
 // inner objects so additive shape changes there don't break Zod validation
 // before the schema catches up — drift on required keys still fails.
-const StrategyResultSchema = z
+export const StrategyResultSchema = z
     .object({
     profile: z
         .object({
@@ -258,6 +258,18 @@ const StrategyResultSchema = z
         .passthrough(),
 })
     .passthrough();
+/**
+ * On-demand strategy snapshot output (#1243 step 4). Wraps the same
+ * `StrategyResult` shape consumed by the daily auto-display, but is
+ * always available — the cadence gate only governs the auto-display,
+ * not direct CLI/MCP calls. `strategy` is null when the minimum-data
+ * gate fails (fewer than `STRATEGY_MIN_PRS` merged PRs); `message`
+ * carries the human-readable explanation in that case.
+ */
+export const StrategyOutputSchema = z.object({
+    strategy: StrategyResultSchema.nullable(),
+    message: z.string().optional(),
+});
 export const DailyOutputSchema = z.object({
     digest: DailyDigestCompactSchema,
     capacity: CapacityAssessmentSchema,
@@ -323,6 +335,14 @@ const SearchCandidateSchema = z.object({
     })
         .optional(),
     linkedPR: CandidateLinkedPRSchema.optional(),
+    /**
+     * Personalization sort-tier signal threaded up from oss-scout (#1244).
+     * Present only when local strategy data biased the search and this
+     * candidate matched. `boostReasons` is the human-readable explanation
+     * (e.g. `"repo affinity: vercel/next.js"`, `"language match: TypeScript"`).
+     */
+    boostScore: z.number().optional(),
+    boostReasons: z.array(z.string()).optional(),
 });
 export const SearchOutputSchema = z.object({
     candidates: z.array(SearchCandidateSchema),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -54,18 +54,18 @@
   "dependencies": {
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.1",
-    "@oss-scout/core": "^0.9.0",
+    "@oss-scout/core": "^0.10.0",
     "commander": "^14.0.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "@vitest/coverage-v8": "^4.1.5",
+    "@types/node": "^25.7.0",
+    "@vitest/coverage-v8": "^4.1.6",
     "esbuild": "^0.28.0",
     "tsx": "^4.21.0",
     "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.6"
   },
   "scripts": {
     "build": "tsc",