@oss-scout/core 0.11.0 → 1.0.0

package/dist/core/search-phases.js

@@ -7,7 +7,7 @@
 import { SCOPE_LABELS, } from "./types.js";
 import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
 import { debug, warn } from "./logger.js";
-import { getHttpCache } from "./http-cache.js";
+import { getHttpCache, versionedCacheKey } from "./http-cache.js";
 import { detectLabelFarmingRepos, } from "./issue-filtering.js";
 import { extractRepoFromUrl, sleep } from "./utils.js";
 import { getSearchBudgetTracker } from "./search-budget.js";
@@ -18,8 +18,6 @@ const GITHUB_MAX_BOOLEAN_OPS = 5;
  * Set to 2000ms as a safety floor (max 30/min at the limit). The SearchBudgetTracker
  * adds additional adaptive delays when needed. */
 const INTER_QUERY_DELAY_MS = 2000;
-/** Batch size for repo queries. 3 repos = 2 OR operators, leaving room for labels. */
-const BATCH_SIZE = 3;
 /**
  * Chunk labels into groups that fit within the operator budget.
  * N labels require N-1 OR operators, so maxPerChunk = budget + 1.
@@ -77,14 +75,6 @@ export function interleaveArrays(arrays) {
     }
     return result;
 }
-/** Split repos into batches of the specified size. */
-function batchRepos(repos, batchSize) {
-    const batches = [];
-    for (let i = 0; i < repos.length; i += batchSize) {
-        batches.push(repos.slice(i, i + batchSize));
-    }
-    return batches;
-}
 // ── Search caching ──
 /** TTL for cached search API results (15 minutes). */
 const SEARCH_CACHE_TTL_MS = 15 * 60 * 1000;
@@ -94,7 +84,7 @@ const SEARCH_CACHE_TTL_MS = 15 * 60 * 1000;
  * without consuming GitHub API rate limit points.
  */
 export async function cachedSearchIssues(octokit, params) {
-    const cacheKey = `search:${params.q}:${params.sort}:${params.order}:${params.per_page}`;
+    const cacheKey = versionedCacheKey(`search:${params.q}:${params.sort}:${params.order}:${params.per_page}`);
     const cache = getHttpCache();
     // Check cache first
     const cached = cache.getIfFresh(cacheKey, SEARCH_CACHE_TTL_MS);
@@ -206,17 +196,32 @@ export async function fetchIssuesFromKnownRepos(octokit, vetter, repos, labels,
         const repoFullName = repos[i];
         const [owner, repo] = repoFullName.split("/");
         try {
-            const response = await octokit.issues.listForRepo({
-                owner,
-                repo,
-                state: "open",
-                sort: "created",
-                direction: "desc",
-                per_page: 5,
-                ...(labels.length > 0 ? { labels: labels.join(",") } : {}),
-            });
+            // One query per label: the REST `labels` parameter is AND semantics
+            // (issues carrying ALL listed labels), so a comma-joined list like
+            // "good first issue,help wanted" returned ~nothing (#118). Querying
+            // per label and merging restores the intended any-of behavior.
+            const labelFilters = labels.length > 0 ? labels : [undefined];
+            const seenUrls = new Set();
+            const rawIssues = [];
+            for (const label of labelFilters) {
+                const response = await octokit.issues.listForRepo({
+                    owner,
+                    repo,
+                    state: "open",
+                    sort: "created",
+                    direction: "desc",
+                    per_page: 5,
+                    ...(label !== undefined ? { labels: label } : {}),
+                });
+                for (const issue of response.data) {
+                    if (seenUrls.has(issue.html_url))
+                        continue;
+                    seenUrls.add(issue.html_url);
+                    rawIssues.push(issue);
+                }
+            }
             // Filter out pull requests (REST issues endpoint returns both) and assigned issues
-            const issuesOnly = response.data.filter((item) => !("pull_request" in item) && !item.assignee);
+            const issuesOnly = rawIssues.filter((item) => !("pull_request" in item) && !item.assignee);
             const mapped = issuesOnly.map((issue) => ({
                 html_url: issue.html_url,
                 repository_url: `https://api.github.com/repos/${repoFullName}`,
@@ -378,63 +383,3 @@ export async function filterVetAndScore(vetter, items, filterIssues, excludedRep
     }
     return { candidates: starFiltered, allVetFailed, rateLimitHit };
 }
-/**
- * Search for issues within specific repos using batched queries.
- *
- * To avoid GitHub's secondary rate limit (30 requests/minute), we batch
- * multiple repos into a single search query using OR syntax:
- *   repo:owner1/repo1 OR repo:owner2/repo2 OR repo:owner3/repo3
- *
- * Labels are chunked separately to stay within GitHub's 5 boolean operator limit.
- * Each batch of repos consumes (batch.length - 1) OR operators, and the remaining
- * budget is used for label OR operators.
- *
- * This reduces API calls from N (one per repo) to ceil(N/BATCH_SIZE) * label_chunks.
- */
-export async function searchInRepos(octokit, vetter, repos, baseQualifiers, labels, maxResults, priority, filterFn) {
-    const candidates = [];
-    const batches = batchRepos(repos, BATCH_SIZE);
-    let failedBatches = 0;
-    let rateLimitFailures = 0;
-    for (let batchIdx = 0; batchIdx < batches.length; batchIdx++) {
-        const batch = batches[batchIdx];
-        if (candidates.length >= maxResults)
-            break;
-        // Delay between batches to avoid secondary rate limits
-        if (batchIdx > 0)
-            await sleep(INTER_QUERY_DELAY_MS);
-        try {
-            const repoFilter = batch.map((r) => `repo:${r}`).join(" OR ");
-            const repoOps = batch.length - 1;
-            const perPage = Math.min(30, (maxResults - candidates.length) * 3);
-            const allItems = await searchWithChunkedLabels(octokit, labels, repoOps, (labelQ) => `${baseQualifiers} ${labelQ} (${repoFilter})`
-                .replace(/  +/g, " ")
-                .trim(), perPage);
-            if (allItems.length > 0) {
-                const filtered = filterFn(allItems);
-                const remainingNeeded = maxResults - candidates.length;
-                const { candidates: vetted, rateLimitHit: vetRateLimitHit } = await vetter.vetIssuesParallel(filtered.slice(0, remainingNeeded * 2).map((i) => i.html_url), remainingNeeded, priority);
-                candidates.push(...vetted);
-                if (vetRateLimitHit)
-                    rateLimitFailures++;
-            }
-        }
-        catch (error) {
-            if (getHttpStatusCode(error) === 401)
-                throw error;
-            failedBatches++;
-            if (isRateLimitError(error)) {
-                rateLimitFailures++;
-            }
-            const batchReposStr = batch.join(", ");
-            warn(MODULE, `Error searching issues in batch [${batchReposStr}]:`, errorMessage(error));
-        }
-    }
-    const allBatchesFailed = failedBatches === batches.length && batches.length > 0;
-    const rateLimitHit = rateLimitFailures > 0;
-    if (allBatchesFailed) {
-        warn(MODULE, `All ${batches.length} batch(es) failed for ${priority} phase. ` +
-            `This may indicate a systemic issue (rate limit, auth, network).`);
-    }
-    return { candidates, allBatchesFailed, rateLimitHit };
-}

package/dist/core/types.d.ts

@@ -2,9 +2,10 @@
  * Core types for oss-scout — ephemeral types that are never persisted.
  */
 import type { RepoSignals, TrackedIssue, IssueVettingResult, IssueScope, ScoutState, SearchStrategy } from "./schemas.js";
+import type { LogLevel } from "./logger.js";
 export type { ProjectCategory, IssueScope, RepoSignals, RepoScore, StoredMergedPR, StoredClosedPR, ContributionGuidelines, IssueVettingResult, LinkedPR, TrackedIssue, ScoutPreferences, SavedCandidate, ScoutState, SearchStrategy, } from "./schemas.js";
-/** Health snapshot of a GitHub repository. */
-export interface ProjectHealth {
+/** A successful health snapshot of a GitHub repository. */
+export interface ProjectHealthData {
     repo: string;
     lastCommitAt: string;
     daysSinceLastCommit: number;
@@ -15,9 +16,26 @@ export interface ProjectHealth {
     stargazersCount?: number;
     forksCount?: number;
     language?: string | null;
-    checkFailed?: boolean;
-    failureReason?: string;
+    /** Discriminant: a real snapshot is never `checkFailed`. */
+    checkFailed?: false;
+    failureReason?: undefined;
 }
+/**
+ * The health check itself failed (transient API error). Only the repo and the
+ * failure reason are known — none of the snapshot fields are meaningful, so the
+ * type does not carry them. Narrow on `checkFailed` to reach a real snapshot.
+ */
+export interface ProjectHealthFailure {
+    repo: string;
+    checkFailed: true;
+    failureReason: string;
+}
+/**
+ * Health snapshot of a GitHub repository, or a marker that the check failed.
+ * A discriminated union (on `checkFailed`) so the "failure" shape can't be read
+ * as if it carried real snapshot data. Narrow before reading snapshot fields.
+ */
+export type ProjectHealth = ProjectHealthData | ProjectHealthFailure;
 /** Priority tier for issue search results. */
 export type SearchPriority = "merged_pr" | "starred" | "normal";
 /** Source file the anti-LLM policy match came from, or null when no file matched. */
@@ -43,6 +61,13 @@ export interface SLMTriageSummary {
 /** A fully vetted issue candidate with scoring. */
 export interface IssueCandidate {
     issue: TrackedIssue;
+    /**
+     * GitHub issue state at vet time (#120). GitHub answers 200 for closed
+     * issues, so without this vet-list classified them still_available and
+     * --prune kept them. Optional: cached candidates from older versions
+     * lack it and read as open.
+     */
+    issueState?: "open" | "closed";
     vettingResult: IssueVettingResult;
     projectHealth: ProjectHealth;
     antiLLMPolicy: AntiLLMPolicyResult;
@@ -54,26 +79,22 @@ export interface IssueCandidate {
     viabilityScore: number;
     searchPriority: SearchPriority;
     /**
-     * Personalization sort tier (#1244). Populated only when the caller
-     * passes `preferLanguages` / `preferRepos` to `search()` *and* the
-     * candidate matches at least one. Affects sort order between the
-     * `recommendation` tier and `viabilityScore`; never used as a filter.
-     */
-    boostScore?: number;
-    /**
-     * Human-readable reasons the candidate matched personalization bias
-     * (#1244). Mirrors `reasonsToApprove`/`reasonsToSkip` shape for
-     * symmetry with the existing surface.
+     * Personalization marker (#1244). A candidate is EITHER boosted (it matched
+     * a `preferLanguages` / `preferRepos` bias and gets a soft sort boost between
+     * the `recommendation` tier and `viabilityScore`) OR a diversity slot (it
+     * matched no bias and filled a slot reserved by `diversityRatio`) — never
+     * both. Modelling it as a single discriminated field makes that mutual
+     * exclusivity structural instead of prose across three optional fields.
+     * Absent when no personalization was requested or the candidate matched
+     * nothing.
      */
-    boostReasons?: string[];
-    /**
-     * Marks a candidate that filled a reserved diversity slot (#1244).
-     * Populated only when `diversityRatio > 0` was passed AND the
-     * candidate matched no personalization bias. Mutually exclusive with
-     * a non-zero `boostScore` (a candidate cannot be both biased-toward
-     * and a diversity slot in the same result set).
-     */
-    diversitySlot?: boolean;
+    personalization?: {
+        kind: "boosted";
+        score: number;
+        reasons: string[];
+    } | {
+        kind: "diversity";
+    };
 }
 /** Subset of RepoScore fields that callers may update. */
 export interface RepoScoreUpdate {
@@ -85,29 +106,51 @@ export interface RepoScoreUpdate {
     stargazersCount?: number;
     language?: string | null;
 }
-/** Result of a check (e.g., no existing PR, not claimed). */
-export interface CheckResult {
+/**
+ * Result of a check (e.g., no existing PR, not claimed). Discriminated on
+ * `inconclusive`: a `reason` exists only when the check could not be completed
+ * (a transient API error), and an inconclusive check always reports `passed:
+ * true` because the caller assumes the issue is still eligible. A conclusive
+ * result carries no `reason`.
+ */
+export type CheckResult = {
     passed: boolean;
-    inconclusive?: boolean;
-    reason?: string;
-}
+    inconclusive?: false;
+    reason?: undefined;
+} | {
+    passed: true;
+    inconclusive: true;
+    reason: string;
+};
 export declare const SCOPE_LABELS: Record<IssueScope, string[]>;
 /** Options for batch vetting saved results. */
 export interface VetListOptions {
     concurrency?: number;
     prune?: boolean;
 }
-/** A single entry in the vet-list result. */
-export interface VetListEntry {
+/** Identity fields shared by every vet-list entry, regardless of outcome. */
+export interface VetListEntryBase {
     issueUrl: string;
     repo: string;
     number: number;
     title: string;
     status: "still_available" | "claimed" | "closed" | "has_pr" | "error";
-    recommendation?: "approve" | "skip" | "needs_review";
-    viabilityScore?: number;
-    errorMessage?: string;
 }
+/**
+ * A single entry in the vet-list result. Discriminated on `ok`: a completed vet
+ * (`ok: true`) carries `recommendation` + `viabilityScore` and never an
+ * `errorMessage`; a vet that threw (`ok: false`, including a 404/410 that
+ * classifies the issue as `closed`) carries only the `errorMessage`. This makes
+ * the "score xor error" invariant structural instead of prose.
+ */
+export type VetListEntry = (VetListEntryBase & {
+    ok: true;
+    recommendation: "approve" | "skip" | "needs_review";
+    viabilityScore: number;
+}) | (VetListEntryBase & {
+    ok: false;
+    errorMessage: string;
+});
 /** Summary counts for a vet-list run. */
 export interface VetListSummary {
     total: number;
@@ -117,27 +160,69 @@ export interface VetListSummary {
     hasPR: number;
     errors: number;
 }
+/** Result of reconciling tracked open PRs against their current GitHub state (#164). */
+export interface SyncResult {
+    /** Open PRs checked. */
+    checked: number;
+    /** Transitioned to merged. */
+    merged: number;
+    /** Transitioned to closed-without-merge. */
+    closed: number;
+    /** Still open (kept). */
+    stillOpen: number;
+    /** Could not be checked (parse failure or transient API error). */
+    errors: number;
+}
+/** A saved result whose availability status changed since the last vet-list (#165). */
+export interface VetStatusTransition {
+    issueUrl: string;
+    repo: string;
+    number: number;
+    from: VetListEntry["status"];
+    to: VetListEntry["status"];
+}
 /** Result of a batch vet-list operation. */
 export interface VetListResult {
     results: VetListEntry[];
     summary: VetListSummary;
     prunedCount?: number;
+    /**
+     * Status changes since the previous vet-list run, computed from each saved
+     * result's `lastStatus`. Empty on a first run (no prior status to compare).
+     */
+    transitions: VetStatusTransition[];
 }
 /** Configuration for creating an OssScout instance. */
 export type ScoutConfig = {
-    /** GitHub token with `repo` read scope. Add `gist` scope for persistence. */
+    /** GitHub token with `repo` read scope. Add `gist` scope for gist persistence. */
     githubToken: string;
-    /** Use gist-backed persistence (default for standalone CLI). */
-    persistence?: "gist";
-    /** Gist ID override. Skips gist discovery/creation if provided. */
+    /**
+     * State storage. Omitted defaults to `"local"`: load and persist
+     * `~/.oss-scout/state.json`, no network on construct. `"gist"` syncs
+     * via a private GitHub gist (needs the `gist` token scope).
+     */
+    persistence?: "local" | "gist";
+    /** Gist ID override (gist mode). Skips gist discovery/creation if provided. */
     gistId?: string;
+    /**
+     * Minimum log level emitted to stderr. Omitted leaves the global level
+     * (default "info"). Hosts that don't want the "[INFO] Phase 0..."
+     * chatter can pass "warn" or "silent" (#156).
+     */
+    logLevel?: LogLevel;
 } | {
     /** GitHub token with `repo` read scope. */
     githubToken: string;
-    /** Caller provides state directly. */
+    /** Caller provides and owns state directly (embedding hosts). */
     persistence: "provided";
     /** Pre-loaded state. Required when persistence is 'provided'. */
     initialState: ScoutState;
+    /**
+     * Minimum log level emitted to stderr. Omitted leaves the global level
+     * (default "info"). Hosts that don't want the "[INFO] Phase 0..."
+     * chatter can pass "warn" or "silent" (#156).
+     */
+    logLevel?: LogLevel;
 };
 /** Options for the search method. */
 export interface SearchOptions {
@@ -168,6 +253,19 @@ export interface SearchOptions {
      * clamped to [0, 1].
      */
     diversityRatio?: number;
+    /**
+     * Per-call override for the delay between search phases (ms). Defaults to
+     * the `interPhaseDelayMs` preference (30s). Latency-sensitive callers like
+     * the MCP server pass 0; the sliding-window budget tracker still paces the
+     * actual API calls, so the fixed sleep is the only thing removed (#143).
+     */
+    interPhaseDelayMs?: number;
+    /**
+     * Per-call override for the extra cooldown before the broad phase (ms).
+     * Defaults to the `broadPhaseDelayMs` preference (90s). See
+     * `interPhaseDelayMs` for the rationale (#143).
+     */
+    broadPhaseDelayMs?: number;
 }
 /** Result of a search operation. */
 export interface SearchResult {

package/dist/core/utils.js

@@ -36,14 +36,29 @@ export function getCacheDir() {
  * - https://api.github.com/repos/owner/repo/...
  */
 export function extractRepoFromUrl(url) {
+    // Real URL parsing: the previous regexes were unanchored (any host
+    // containing "github.com" matched) and leaked query/fragment text into
+    // the repo segment ("repo?tab=readme").
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const host = parsed.hostname.toLowerCase().replace(/^www\./, "");
+    const segments = parsed.pathname.split("/").filter(Boolean);
     // API URLs: https://api.github.com/repos/owner/repo[/...]
-    const apiMatch = url.match(/api\.github\.com\/repos\/([^/]+\/[^/]+)/);
-    if (apiMatch)
-        return apiMatch[1];
+    if (host === "api.github.com") {
+        if (segments[0] === "repos" && segments.length >= 3) {
+            return `${segments[1]}/${segments[2]}`;
+        }
+        return null;
+    }
     // Web URLs: https://github.com/owner/repo[/...]
-    const webMatch = url.match(/github\.com\/([^/]+\/[^/]+)/);
-    if (webMatch)
-        return webMatch[1];
+    if (host === "github.com" && segments.length >= 2) {
+        return `${segments[0]}/${segments[1]}`;
+    }
     return null;
 }
 const OWNER_PATTERN = /^[a-zA-Z0-9_-]+$/;
@@ -52,25 +67,38 @@ function isValidOwnerRepo(owner, repo) {
     return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo);
 }
 export function parseGitHubUrl(url) {
-    if (!url.startsWith("https://github.com/"))
-        return null;
-    const prMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
-    if (prMatch) {
-        const owner = prMatch[1];
-        const repo = prMatch[2];
-        if (!isValidOwnerRepo(owner, repo))
-            return null;
-        return { owner, repo, number: parseInt(prMatch[3], 10), type: "pull" };
+    // Accept pasteable variants: http://, www., and bare github.com/... forms
+    // normalize to a parseable URL. Strict canonical-form validation for
+    // command input lives in commands/validation.ts; this parser is lenient.
+    const normalized = /^(?:www\.)?github\.com\//i.test(url)
+        ? `https://${url}`
+        : url;
+    let parsed;
+    try {
+        parsed = new URL(normalized);
     }
-    const issueMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
-    if (issueMatch) {
-        const owner = issueMatch[1];
-        const repo = issueMatch[2];
-        if (!isValidOwnerRepo(owner, repo))
-            return null;
-        return { owner, repo, number: parseInt(issueMatch[3], 10), type: "issues" };
+    catch {
+        return null;
     }
-    return null;
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+        return null;
+    const host = parsed.hostname.toLowerCase().replace(/^www\./, "");
+    if (host !== "github.com")
+        return null;
+    // Exactly owner/repo/(pull|issues)/<digits>; trailing slash tolerated via
+    // filter(Boolean), query/fragment excluded by pathname. A malformed number
+    // segment ("123abc") no longer half-parses to 123.
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    if (segments.length !== 4)
+        return null;
+    const [owner, repo, type, num] = segments;
+    if (type !== "pull" && type !== "issues")
+        return null;
+    if (!isValidOwnerRepo(owner, repo))
+        return null;
+    if (!/^\d+$/.test(num))
+        return null;
+    return { owner, repo, number: parseInt(num, 10), type };
 }
 export function daysBetween(from, to = new Date()) {
     return Math.max(0, Math.floor((to.getTime() - from.getTime()) / (1000 * 60 * 60 * 24)));
@@ -91,8 +119,12 @@ export function getGitHubToken() {
     if (tokenFetchAttempted)
         return null;
     tokenFetchAttempted = true;
-    if (process.env.GITHUB_TOKEN) {
-        cachedGitHubToken = process.env.GITHUB_TOKEN;
+    // Trim: a trailing newline (e.g. GITHUB_TOKEN=$(cat file)) produces a
+    // malformed Authorization header with confusing 401s. A whitespace-only
+    // value falls through to the gh CLI.
+    const envToken = process.env.GITHUB_TOKEN?.trim();
+    if (envToken) {
+        cachedGitHubToken = envToken;
         return cachedGitHubToken;
     }
     try {
@@ -108,7 +140,9 @@ export function getGitHubToken() {
         }
     }
     catch (err) {
-        debug(MODULE, "gh auth token failed", err);
+        // Log only the message: the raw execFileSync error carries stdout/stderr
+        // buffers that could include a token if gh half-succeeded.
+        debug(MODULE, `gh auth token failed: ${errorMessage(err)}`);
     }
     return null;
 }

package/dist/formatters/markdown.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Markdown output formatter (#170) — renders saved results as a table for
+ * digests, notes export, and scheduled GitHub-issue summaries.
+ */
+import type { SavedCandidate } from "../core/schemas.js";
+/**
+ * Render saved results as a GitHub-flavored markdown table, sorted by
+ * viability score descending. Returns a friendly message when empty.
+ */
+export declare function formatResultsMarkdown(results: SavedCandidate[]): string;

package/dist/formatters/markdown.js

@@ -0,0 +1,31 @@
+/**
+ * Markdown output formatter (#170) — renders saved results as a table for
+ * digests, notes export, and scheduled GitHub-issue summaries.
+ */
+/** Escape pipe and newline so a title can't break the markdown table. */
+function cell(value) {
+    return value.replace(/\r?\n/g, " ").replace(/\|/g, "\\|").trim();
+}
+/**
+ * Render saved results as a GitHub-flavored markdown table, sorted by
+ * viability score descending. Returns a friendly message when empty.
+ */
+export function formatResultsMarkdown(results) {
+    if (results.length === 0) {
+        return "_No saved results._";
+    }
+    const sorted = [...results].sort((a, b) => b.viabilityScore - a.viabilityScore);
+    const header = "| Score | Repo | Issue | Recommendation | Title |";
+    const divider = "| ----- | ---- | ----- | -------------- | ----- |";
+    const rows = sorted.map((r) => {
+        const issueLink = `[#${r.number}](${r.issueUrl})`;
+        return `| ${r.viabilityScore} | ${cell(r.repo)} | ${issueLink} | ${cell(r.recommendation)} | ${cell(r.title)} |`;
+    });
+    return [
+        `## oss-scout results (${results.length})`,
+        "",
+        header,
+        divider,
+        ...rows,
+    ].join("\n");
+}

package/dist/index.d.ts

@@ -15,13 +15,17 @@
  * @packageDocumentation
  */
 export { createScout, OssScout } from "./scout.js";
-export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, OpenPRRecord, RepoScoreUpdate, ProjectHealth, SearchPriority, CheckResult, AntiLLMPolicyResult, AntiLLMPolicySourceFile, VetListOptions, VetListResult, VetListEntry, VetListSummary, } from "./core/types.js";
+export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, OpenPRRecord, RepoScoreUpdate, ProjectHealth, ProjectHealthData, ProjectHealthFailure, SearchPriority, CheckResult, AntiLLMPolicyResult, AntiLLMPolicySourceFile, VetListOptions, VetListResult, VetListEntry, VetListEntryBase, VetListSummary, SyncResult, } from "./core/types.js";
 export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, LinkedPR, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, StoredOpenPR, SearchStrategy, SkippedIssue, Horizon, } from "./core/schemas.js";
 export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, HorizonSchema, } from "./core/schemas.js";
+export { applyPreferenceField, FIELD_CONFIGS, PREFERENCE_KEYS, SORTED_PREFERENCE_KEYS, assertFieldConfigsCover, updateArray, type FieldConfig, } from "./core/preference-fields.js";
 export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
 export { IssueDiscovery } from "./core/issue-discovery.js";
-export { IssueVetter, type ScoutStateReader, type FeatureSignals, } from "./core/issue-vetting.js";
+export { IssueVetter, type ScoutStateReader, type ScoutStateWriter, type SLMConfig, type FeatureSignals, } from "./core/issue-vetting.js";
 export { scanForAntiLLMPolicy, ANTI_LLM_KEYWORDS, } from "./core/anti-llm-policy.js";
+export { bootstrapScout, type BootstrapResult } from "./core/bootstrap.js";
+export { setLogLevel, getLogLevel, enableDebug, type LogLevel, } from "./core/logger.js";
 export { discoverFeatures, resolveAnchorRepos, classifyHorizon, splitByHorizon, ANCHOR_THRESHOLD, FEATURE_LABELS, NO_ANCHORS_MESSAGE, NO_RESULTS_MESSAGE, type FeatureCandidate, type FeatureSearchResult, type DiscoverFeaturesOptions, } from "./core/feature-discovery.js";
 export { isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, } from "./core/linked-pr.js";
 export { fetchRoadmapIssueRefs, parseRoadmapIssueRefs, } from "./core/roadmap.js";
+export { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl, } from "./commands/validation.js";

package/dist/index.js

@@ -18,15 +18,23 @@
 export { createScout, OssScout } from "./scout.js";
 // Schemas (for consumers who need runtime validation)
 export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, HorizonSchema, } from "./core/schemas.js";
+// Preference-field metadata + parsing (shared by the CLI and the MCP server)
+export { applyPreferenceField, FIELD_CONFIGS, PREFERENCE_KEYS, SORTED_PREFERENCE_KEYS, assertFieldConfigsCover, updateArray, } from "./core/preference-fields.js";
 // Utilities
 export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
 // Internal classes (for advanced use)
 export { IssueDiscovery } from "./core/issue-discovery.js";
 export { IssueVetter, } from "./core/issue-vetting.js";
 export { scanForAntiLLMPolicy, ANTI_LLM_KEYWORDS, } from "./core/anti-llm-policy.js";
+// Bootstrap (seed state from GitHub) — usable by library/MCP hosts (#156)
+export { bootstrapScout } from "./core/bootstrap.js";
+// Log-level control for library hosts (#156)
+export { setLogLevel, getLogLevel, enableDebug, } from "./core/logger.js";
 // Feature discovery API
 export { discoverFeatures, resolveAnchorRepos, classifyHorizon, splitByHorizon, ANCHOR_THRESHOLD, FEATURE_LABELS, NO_ANCHORS_MESSAGE, NO_RESULTS_MESSAGE, } from "./core/feature-discovery.js";
 // Linked-PR helpers (#97)
 export { isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, } from "./core/linked-pr.js";
 // Roadmap scraping (#95)
 export { fetchRoadmapIssueRefs, parseRoadmapIssueRefs, } from "./core/roadmap.js";
+// Issue-URL validation (shared by the CLI and the MCP server)
+export { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl, } from "./commands/validation.js";