@oss-scout/core 0.11.0 → 1.1.0

package/dist/commands/command-scout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared scout construction for CLI commands.
+ *
+ * Picks the persistence mode from `state.preferences.persistence` so the
+ * `gist` preference is actually honored (#115). Previously every command
+ * hardcoded `provided` mode, leaving gist sync unreachable no matter what
+ * `oss-scout config set persistence gist` wrote.
+ */
+import type { ScoutState } from "../core/schemas.js";
+import { type OssScout } from "../scout.js";
+/**
+ * Build a scout for a CLI command from already-loaded local state and a token.
+ *
+ * - `persistence: "gist"` preference → gist-backed scout. createScout loads
+ *   local state itself and merges it with the gist, and `checkpoint()` pushes
+ *   to the gist. The caller still calls `saveLocalState` to keep the local
+ *   file fresh as an offline cache.
+ * - otherwise → provided-state scout backed by the local file. The command's
+ *   `saveLocalState` + `checkpoint()` persist locally.
+ */
+export declare function buildCommandScout(state: ScoutState, token: string): Promise<OssScout>;

package/dist/commands/command-scout.js

@@ -0,0 +1,21 @@
+import { createScout } from "../scout.js";
+/**
+ * Build a scout for a CLI command from already-loaded local state and a token.
+ *
+ * - `persistence: "gist"` preference → gist-backed scout. createScout loads
+ *   local state itself and merges it with the gist, and `checkpoint()` pushes
+ *   to the gist. The caller still calls `saveLocalState` to keep the local
+ *   file fresh as an offline cache.
+ * - otherwise → provided-state scout backed by the local file. The command's
+ *   `saveLocalState` + `checkpoint()` persist locally.
+ */
+export async function buildCommandScout(state, token) {
+    if (state.preferences.persistence === "gist") {
+        return createScout({ githubToken: token, persistence: "gist" });
+    }
+    return createScout({
+        githubToken: token,
+        persistence: "provided",
+        initialState: state,
+    });
+}

package/dist/commands/config.js

@@ -2,82 +2,8 @@
  * Config command — view and update oss-scout preferences.
  */
 import { loadLocalState, saveLocalState } from "../core/local-state.js";
-import { ScoutPreferencesSchema, IssueScopeSchema, ProjectCategorySchema, PersistenceModeSchema, SearchStrategySchema, } from "../core/schemas.js";
-import { ValidationError } from "../core/errors.js";
-const FIELD_CONFIGS = {
-    languages: { type: "array" },
-    labels: { type: "array" },
-    excludeRepos: { type: "array" },
-    excludeOrgs: { type: "array" },
-    aiPolicyBlocklist: { type: "array" },
-    minStars: { type: "number" },
-    maxIssueAgeDays: { type: "number" },
-    minRepoScoreThreshold: { type: "number" },
-    interPhaseDelayMs: { type: "number" },
-    includeDocIssues: { type: "boolean" },
-    scope: { type: "enum-array", validValues: IssueScopeSchema.options },
-    projectCategories: {
-        type: "enum-array",
-        validValues: ProjectCategorySchema.options,
-    },
-    persistence: { type: "enum", validValues: PersistenceModeSchema.options },
-    defaultStrategy: {
-        type: "enum-array",
-        validValues: SearchStrategySchema.options,
-    },
-    githubUsername: { type: "string" },
-    broadPhaseDelayMs: { type: "number" },
-    skipBroadWhenSufficientResults: { type: "number" },
-    featuresAnchorThreshold: { type: "number" },
-    featuresSplitRatio: { type: "float" },
-};
-function parseBoolean(value) {
-    const lower = value.toLowerCase();
-    if (lower === "true" || lower === "yes")
-        return true;
-    if (lower === "false" || lower === "no")
-        return false;
-    throw new ValidationError(`Invalid boolean value: "${value}". Use true/false or yes/no.`);
-}
-function parseNumber(value, key) {
-    const num = parseInt(value, 10);
-    if (isNaN(num)) {
-        throw new ValidationError(`Invalid number for "${key}": "${value}"`);
-    }
-    return num;
-}
-function parseFloat(value, key) {
-    const num = Number.parseFloat(value);
-    if (isNaN(num)) {
-        throw new ValidationError(`Invalid number for "${key}": "${value}"`);
-    }
-    return num;
-}
-function parseArrayValue(value) {
-    return value
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0);
-}
-/**
- * Apply an array update: plain set, +append, or -remove.
- */
-function updateArray(current, value) {
-    if (value.startsWith("+")) {
-        const toAdd = parseArrayValue(value.slice(1));
-        const merged = [...current];
-        for (const item of toAdd) {
-            if (!merged.includes(item))
-                merged.push(item);
-        }
-        return merged;
-    }
-    if (value.startsWith("-")) {
-        const toRemove = new Set(parseArrayValue(value.slice(1)));
-        return current.filter((item) => !toRemove.has(item));
-    }
-    return parseArrayValue(value);
-}
+import { ScoutPreferencesSchema } from "../core/schemas.js";
+import { applyPreferenceField } from "../core/preference-fields.js";
 function formatArray(arr) {
     return arr.length > 0 ? arr.join(", ") : "(none)";
 }
@@ -103,8 +29,13 @@ export function runConfigShow() {
     console.log(`  aiPolicyBlocklist:    ${formatArray(prefs.aiPolicyBlocklist)}`);
     console.log(`  defaultStrategy:      ${prefs.defaultStrategy ? formatArray(prefs.defaultStrategy) : "(all)"}`);
     console.log(`  persistence:          ${prefs.persistence}`);
+    console.log(`  preferLanguages:      ${formatArray(prefs.preferLanguages)}`);
+    console.log(`  preferRepos:          ${formatArray(prefs.preferRepos)}`);
+    console.log(`  diversityRatio:       ${prefs.diversityRatio}`);
     console.log(`  broadPhaseDelayMs:    ${prefs.broadPhaseDelayMs}ms (${(prefs.broadPhaseDelayMs / 1000).toFixed(0)}s)`);
     console.log(`  skipBroadWhenSufficientResults: ${prefs.skipBroadWhenSufficientResults}`);
+    console.log(`  slmTriageModel:       ${prefs.slmTriageModel || "(disabled)"}`);
+    console.log(`  slmTriageHost:        ${prefs.slmTriageHost || "(default 127.0.0.1:11434)"}`);
     console.log(`  featuresAnchorThreshold: ${prefs.featuresAnchorThreshold}`);
     console.log(`  featuresSplitRatio:    ${prefs.featuresSplitRatio}`);
     console.log();
@@ -120,60 +51,10 @@ export function getConfigData() {
  * Update a single preference by key.
  */
 export function runConfigSet(key, value) {
-    const field = FIELD_CONFIGS[key];
-    if (!field) {
-        throw new ValidationError(`Unknown config key: "${key}". Valid keys: ${Object.keys(FIELD_CONFIGS).sort().join(", ")}`);
-    }
     const state = loadLocalState();
-    const prefs = { ...state.preferences };
-    switch (field.type) {
-        case "string":
-            prefs[key] = value;
-            break;
-        case "boolean":
-            prefs[key] = parseBoolean(value);
-            break;
-        case "number":
-            prefs[key] = parseNumber(value, key);
-            break;
-        case "float":
-            prefs[key] = parseFloat(value, key);
-            break;
-        case "array": {
-            const current = prefs[key] ?? [];
-            prefs[key] = updateArray(current, value);
-            break;
-        }
-        case "enum": {
-            const validValues = field.validValues;
-            if (!validValues.includes(value)) {
-                throw new ValidationError(`Invalid value for "${key}": "${value}". Valid: ${validValues.join(", ")}`);
-            }
-            prefs[key] = value;
-            break;
-        }
-        case "enum-array": {
-            const current = prefs[key] ?? [];
-            const updated = updateArray(current, value);
-            const validValues = field.validValues;
-            const invalid = updated.filter((s) => !validValues.includes(s));
-            if (invalid.length > 0) {
-                throw new ValidationError(`Invalid value(s) for "${key}": ${invalid.join(", ")}. Valid: ${validValues.join(", ")}`);
-            }
-            // For 'scope', empty array means undefined (all scopes)
-            if (key === "scope") {
-                prefs[key] =
-                    updated.length > 0 ? updated : undefined;
-            }
-            else {
-                prefs[key] = updated;
-            }
-            break;
-        }
-    }
-    // Validate the full preferences object
-    const validated = ScoutPreferencesSchema.parse(prefs);
+    const validated = applyPreferenceField(state.preferences, key, value);
     state.preferences = validated;
+    state.preferencesUpdatedAt = new Date().toISOString(); // #117 merge recency
     saveLocalState(state);
     return validated;
 }
@@ -184,6 +65,7 @@ export function runConfigReset() {
     const state = loadLocalState();
     const defaults = ScoutPreferencesSchema.parse({});
     state.preferences = defaults;
+    state.preferencesUpdatedAt = new Date().toISOString(); // #117 merge recency
     saveLocalState(state);
     return defaults;
 }

package/dist/commands/features.js

@@ -1,9 +1,7 @@
 /**
  * Features command — surfaces feature opportunities in anchor repos.
  */
-import { createScout } from "../scout.js";
-import { requireGitHubToken } from "../core/utils.js";
-import { saveLocalState } from "../core/local-state.js";
+import { withScout } from "./with-scout.js";
 import { isLinkedPRStalled } from "../core/linked-pr.js";
 function mapLinkedPR(c) {
     const linkedPR = c.vettingResult.linkedPR;
@@ -48,29 +46,18 @@ function mapBiggerBet(c) {
     };
 }
 export async function runFeatures(options) {
-    const token = requireGitHubToken();
-    const scout = options.state
-        ? await createScout({
-            githubToken: token,
-            persistence: "provided",
-            initialState: options.state,
-        })
-        : await createScout({ githubToken: token });
-    const result = await scout.features({
-        count: options.maxResults,
-        anchorThreshold: options.anchorThreshold,
-        splitRatio: options.splitRatio,
-        broad: options.broad,
-    });
-    saveLocalState(scout.getState());
-    const persisted = await scout.checkpoint();
-    if (!persisted) {
-        console.error("Warning: changes saved locally but gist sync failed.");
-    }
-    return {
-        quickWins: result.quickWins.map(mapQuickWin),
-        biggerBets: result.biggerBets.map(mapBiggerBet),
-        anchorRepos: result.anchorRepos,
-        message: result.message,
-    };
+    return withScout(options.state, async (scout) => {
+        const result = await scout.features({
+            count: options.maxResults,
+            anchorThreshold: options.anchorThreshold,
+            splitRatio: options.splitRatio,
+            broad: options.broad,
+        });
+        return {
+            quickWins: result.quickWins.map(mapQuickWin),
+            biggerBets: result.biggerBets.map(mapBiggerBet),
+            anchorRepos: result.anchorRepos,
+            message: result.message,
+        };
+    }, { persist: true });
 }

package/dist/commands/results.d.ts

@@ -2,7 +2,18 @@
  * Results command — display and manage saved search results.
  */
 import type { SavedCandidate } from "../core/schemas.js";
-export declare function runResults(_options: {
+export interface ResultsOptions {
     json?: boolean;
-}): Promise<SavedCandidate[]>;
+    /** Only results first seen at/after this ISO date (or any Date-parseable string). */
+    since?: string;
+    /** Only results first seen during/after the most recent search run. */
+    newOnly?: boolean;
+}
+/**
+ * Return saved results, optionally narrowed to "new" ones. `--since` takes an
+ * explicit cutoff; `--new-only` uses the last search timestamp so a scheduler
+ * can run `search` then `results --new-only` to see just that run's fresh
+ * finds (#170). Both compare against each result's `firstSeenAt`.
+ */
+export declare function runResults(options?: ResultsOptions): Promise<SavedCandidate[]>;
 export declare function runResultsClear(): Promise<void>;

package/dist/commands/results.js

@@ -2,9 +2,36 @@
  * Results command — display and manage saved search results.
  */
 import { loadLocalState, saveLocalState } from "../core/local-state.js";
-export async function runResults(_options) {
+import { ValidationError } from "../core/errors.js";
+/**
+ * Return saved results, optionally narrowed to "new" ones. `--since` takes an
+ * explicit cutoff; `--new-only` uses the last search timestamp so a scheduler
+ * can run `search` then `results --new-only` to see just that run's fresh
+ * finds (#170). Both compare against each result's `firstSeenAt`.
+ */
+export async function runResults(options = {}) {
     const state = loadLocalState();
-    return state.savedResults ?? [];
+    const results = state.savedResults ?? [];
+    let cutoff;
+    if (options.since !== undefined) {
+        const parsed = Date.parse(options.since);
+        if (Number.isNaN(parsed)) {
+            throw new ValidationError(`Invalid --since date: "${options.since}". Use an ISO date like 2026-06-01.`);
+        }
+        cutoff = parsed;
+    }
+    else if (options.newOnly) {
+        // No prior search recorded → everything counts as new.
+        const parsed = state.lastSearchAt ? Date.parse(state.lastSearchAt) : NaN;
+        cutoff = Number.isNaN(parsed) ? undefined : parsed;
+    }
+    if (cutoff === undefined)
+        return results;
+    const threshold = cutoff;
+    return results.filter((r) => {
+        const seen = Date.parse(r.firstSeenAt);
+        return !Number.isNaN(seen) && seen >= threshold;
+    });
 }
 export async function runResultsClear() {
     const state = loadLocalState();

package/dist/commands/search.d.ts

@@ -64,6 +64,10 @@ interface SearchCommandOptions {
     preferLanguages?: string[];
     /** Soft sort boost for candidates in these `owner/repo` slugs (#1244). */
     preferRepos?: string[];
+    /** Soft sort penalty for candidates in these `owner/repo` slugs (#168). */
+    avoidRepos?: string[];
+    /** Soft sort boost for candidates whose labels match these types (#168). */
+    boostIssueTypes?: string[];
     /** Diversity counterweight: fraction of slots reserved for unboosted candidates (#1244). */
     diversityRatio?: number;
 }

package/dist/commands/search.js

@@ -1,76 +1,71 @@
 /**
  * Search command — finds contributable issues using multi-strategy search.
  */
-import { createScout } from "../scout.js";
-import { requireGitHubToken } from "../core/utils.js";
-import { saveLocalState } from "../core/local-state.js";
+import { withScout } from "./with-scout.js";
 import { isLinkedPRStalled } from "../core/linked-pr.js";
 export async function runSearch(options) {
-    const token = requireGitHubToken();
-    const scout = options.state
-        ? await createScout({
-            githubToken: token,
-            persistence: "provided",
-            initialState: options.state,
-        })
-        : await createScout({ githubToken: token });
-    const result = await scout.search({
-        maxResults: options.maxResults,
-        strategies: options.strategies,
-        preferLanguages: options.preferLanguages,
-        preferRepos: options.preferRepos,
-        diversityRatio: options.diversityRatio,
-    });
-    // Persist results to local state and gist
-    scout.saveResults(result.candidates);
-    saveLocalState(scout.getState());
-    const persisted = await scout.checkpoint();
-    if (!persisted) {
-        console.error("Warning: changes saved locally but gist sync failed.");
-    }
-    return {
-        candidates: result.candidates.map((c) => {
-            const repoScoreRecord = scout.getRepoScoreRecord(c.issue.repo);
-            return {
-                issue: {
-                    repo: c.issue.repo,
-                    repoUrl: `https://github.com/${c.issue.repo}`,
-                    number: c.issue.number,
-                    title: c.issue.title,
-                    url: c.issue.url,
-                    labels: c.issue.labels,
-                },
-                recommendation: c.recommendation,
-                reasonsToApprove: c.reasonsToApprove,
-                reasonsToSkip: c.reasonsToSkip,
-                searchPriority: c.searchPriority,
-                viabilityScore: c.viabilityScore,
-                repoScore: repoScoreRecord
-                    ? {
-                        score: repoScoreRecord.score,
-                        mergedPRCount: repoScoreRecord.mergedPRCount,
-                        closedWithoutMergeCount: repoScoreRecord.closedWithoutMergeCount,
-                        isResponsive: repoScoreRecord.signals?.isResponsive ?? false,
-                        lastMergedAt: repoScoreRecord.lastMergedAt,
-                    }
-                    : undefined,
-                linkedPR: c.vettingResult.linkedPR
-                    ? {
-                        number: c.vettingResult.linkedPR.number,
-                        state: c.vettingResult.linkedPR.state,
-                        url: c.vettingResult.linkedPR.url,
-                        updatedAt: c.vettingResult.linkedPR.updatedAt,
-                        isStalled: isLinkedPRStalled(c.vettingResult.linkedPR),
-                    }
-                    : undefined,
-                boostScore: c.boostScore,
-                boostReasons: c.boostReasons,
-                diversitySlot: c.diversitySlot,
-            };
-        }),
-        excludedRepos: result.excludedRepos,
-        aiPolicyBlocklist: result.aiPolicyBlocklist,
-        rateLimitWarning: result.rateLimitWarning,
-        strategiesUsed: result.strategiesUsed,
-    };
+    return withScout(options.state, async (scout) => {
+        const result = await scout.search({
+            maxResults: options.maxResults,
+            strategies: options.strategies,
+            preferLanguages: options.preferLanguages,
+            preferRepos: options.preferRepos,
+            avoidRepos: options.avoidRepos,
+            boostIssueTypes: options.boostIssueTypes,
+            diversityRatio: options.diversityRatio,
+        });
+        scout.saveResults(result.candidates);
+        return {
+            candidates: result.candidates.map((c) => {
+                const repoScoreRecord = scout.getRepoScoreRecord(c.issue.repo);
+                return {
+                    issue: {
+                        repo: c.issue.repo,
+                        repoUrl: `https://github.com/${c.issue.repo}`,
+                        number: c.issue.number,
+                        title: c.issue.title,
+                        url: c.issue.url,
+                        labels: c.issue.labels,
+                    },
+                    recommendation: c.recommendation,
+                    reasonsToApprove: c.reasonsToApprove,
+                    reasonsToSkip: c.reasonsToSkip,
+                    searchPriority: c.searchPriority,
+                    viabilityScore: c.viabilityScore,
+                    repoScore: repoScoreRecord
+                        ? {
+                            score: repoScoreRecord.score,
+                            mergedPRCount: repoScoreRecord.mergedPRCount,
+                            closedWithoutMergeCount: repoScoreRecord.closedWithoutMergeCount,
+                            isResponsive: repoScoreRecord.signals?.isResponsive ?? false,
+                            lastMergedAt: repoScoreRecord.lastMergedAt,
+                        }
+                        : undefined,
+                    linkedPR: c.vettingResult.linkedPR
+                        ? {
+                            number: c.vettingResult.linkedPR.number,
+                            state: c.vettingResult.linkedPR.state,
+                            url: c.vettingResult.linkedPR.url,
+                            updatedAt: c.vettingResult.linkedPR.updatedAt,
+                            isStalled: isLinkedPRStalled(c.vettingResult.linkedPR),
+                        }
+                        : undefined,
+                    // Keep the JSON output shape stable across the #158 internal
+                    // refactor: derive the flat boost fields from the structural
+                    // `personalization` marker.
+                    boostScore: c.personalization?.kind === "boosted"
+                        ? c.personalization.score
+                        : undefined,
+                    boostReasons: c.personalization?.kind === "boosted"
+                        ? c.personalization.reasons
+                        : undefined,
+                    diversitySlot: c.personalization?.kind === "diversity" ? true : undefined,
+                };
+            }),
+            excludedRepos: result.excludedRepos,
+            aiPolicyBlocklist: result.aiPolicyBlocklist,
+            rateLimitWarning: result.rateLimitWarning,
+            strategiesUsed: result.strategiesUsed,
+        };
+    }, { persist: true });
 }

package/dist/commands/setup.d.ts

@@ -5,6 +5,8 @@ import type { ScoutPreferences } from "../core/schemas.js";
 interface ReadlineInterface {
     question(query: string, callback: (answer: string) => void): void;
     close(): void;
+    on?(event: "close", listener: () => void): unknown;
+    off?(event: "close", listener: () => void): unknown;
 }
 export interface SetupOptions {
     rl?: ReadlineInterface;

package/dist/commands/setup.js

@@ -4,17 +4,36 @@
 import * as readline from "readline";
 import { execFile } from "child_process";
 import { ScoutPreferencesSchema, ProjectCategorySchema, IssueScopeSchema, } from "../core/schemas.js";
+import { ConfigurationError } from "../core/errors.js";
 const ALL_CATEGORIES = ProjectCategorySchema.options;
 const ALL_SCOPES = IssueScopeSchema.options;
 function createReadlineInterface() {
+    // Prompts echo on stderr so stdout stays pure for --json output (#131)
     return readline.createInterface({
         input: process.stdin,
-        output: process.stdout,
+        output: process.stderr,
     });
 }
 function ask(rl, query) {
-    return new Promise((resolve) => {
-        rl.question(query, (answer) => resolve(answer.trim()));
+    return new Promise((resolve, reject) => {
+        // Piped stdin that ends early used to leave the pending question
+        // unresolved: the event loop drained and the process exited 0 without
+        // saving anything (#131). Reject on close instead.
+        let settled = false;
+        const onClose = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new ConfigurationError("Input ended before setup finished; preferences were not saved"));
+        };
+        rl.on?.("close", onClose);
+        rl.question(query, (answer) => {
+            if (settled)
+                return;
+            settled = true;
+            rl.off?.("close", onClose);
+            resolve(answer.trim());
+        });
     });
 }
 function detectGitHubUsername() {
@@ -45,12 +64,19 @@ function parseMultiSelect(input, options) {
  * Run the interactive setup flow and return the configured preferences.
  */
 export async function runSetup(options) {
+    // Fail fast in non-interactive contexts (CI, piped stdin): prompting
+    // would hang or silently save defaults (#131). Injected rl (tests, hosts)
+    // opts out of the guard.
+    if (!options?.rl && !process.stdin.isTTY) {
+        throw new ConfigurationError("setup is interactive and requires a terminal. Use `oss-scout config set <key> <value>` for non-interactive configuration.");
+    }
     const rl = options?.rl ?? createReadlineInterface();
     const detect = options?.detectUsername ?? detectGitHubUsername;
     try {
-        console.log("\n🔧 oss-scout setup\n");
+        // Interactive chrome goes to stderr; stdout stays pure for --json (#131)
+        console.error("\n🔧 oss-scout setup\n");
         // Detect GitHub username
-        console.log("Detecting GitHub username...");
+        console.error("Detecting GitHub username...");
         const detectedUsername = await detect();
         const usernameDefault = detectedUsername || "";
         const usernamePrompt = detectedUsername
@@ -84,6 +110,8 @@ export async function runSetup(options) {
         // Repos to exclude
         const excludeInput = await ask(rl, "Repos to exclude (owner/repo, comma-separated, optional): ");
         const excludeRepos = parseCSV(excludeInput);
+        // Optional local SLM pre-triage (Ollama). Empty leaves it disabled.
+        const slmTriageModel = await ask(rl, "Local SLM triage model for faster pre-filtering (Ollama model id, e.g. gemma4:e4b, optional): ");
         const prefs = ScoutPreferencesSchema.parse({
             githubUsername,
             languages,
@@ -92,8 +120,9 @@ export async function runSetup(options) {
             excludeRepos,
             projectCategories,
             minStars: isNaN(minStars) ? 50 : minStars,
+            slmTriageModel,
         });
-        console.log("\n✅ Setup complete! Preferences saved.\n");
+        console.error("\n✅ Setup complete! Preferences saved.\n");
         return prefs;
     }
     finally {

package/dist/commands/skip.d.ts

@@ -25,6 +25,10 @@ export declare function runSkipList(options?: {
 export declare function runSkipClear(): Promise<void>;
 /**
  * Remove a specific issue from the skip list (unskip).
+ *
+ * Deliberately does NOT validate the URL: entries stored before skip-add
+ * validation existed may be junk, and exact-match removal is the only way
+ * to clean them up short of `skip clear`.
  */
 export declare function runSkipRemove(options: {
     issueUrl: string;