@oss-scout/core 0.1.1 → 0.2.1

package/dist/core/utils.js

@@ -1,39 +1,58 @@
 /**
  * Shared utility functions for oss-scout.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
-import { execFileSync } from 'child_process';
-import { ConfigurationError, errorMessage } from './errors.js';
-import { debug } from './logger.js';
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { execFileSync } from "child_process";
+import { ConfigurationError, errorMessage } from "./errors.js";
+import { debug } from "./logger.js";
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-const MODULE = 'utils';
+const MODULE = "utils";
 let cachedGitHubToken = null;
 let tokenFetchAttempted = false;
 export function getDataDir() {
-    const dir = path.join(os.homedir(), '.oss-scout');
+    const dir = path.join(os.homedir(), ".oss-scout");
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     }
     return dir;
 }
 export function getCacheDir() {
-    const dir = path.join(getDataDir(), 'cache');
+    const dir = path.join(getDataDir(), "cache");
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     }
     return dir;
 }
+/**
+ * Extract "owner/repo" from any GitHub URL format:
+ * - https://github.com/owner/repo
+ * - https://github.com/owner/repo/pull/123
+ * - https://github.com/owner/repo/issues/123
+ * - https://api.github.com/repos/owner/repo
+ * - https://api.github.com/repos/owner/repo/...
+ */
+export function extractRepoFromUrl(url) {
+    // API URLs: https://api.github.com/repos/owner/repo[/...]
+    const apiMatch = url.match(/api\.github\.com\/repos\/([^/]+\/[^/]+)/);
+    if (apiMatch)
+        return apiMatch[1];
+    // Web URLs: https://github.com/owner/repo[/...]
+    const webMatch = url.match(/github\.com\/([^/]+\/[^/]+)/);
+    if (webMatch)
+        return webMatch[1];
+    return null;
+}
 const OWNER_PATTERN = /^[a-zA-Z0-9_-]+$/;
 const REPO_PATTERN = /^[a-zA-Z0-9_.-]+$/;
 function isValidOwnerRepo(owner, repo) {
     return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo);
 }
 export function parseGitHubUrl(url) {
-    if (!url.startsWith('https://github.com/'))
+    if (!url.startsWith("https://github.com/"))
         return null;
     const prMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
     if (prMatch) {
@@ -41,7 +60,7 @@ export function parseGitHubUrl(url) {
         const repo = prMatch[2];
         if (!isValidOwnerRepo(owner, repo))
             return null;
-        return { owner, repo, number: parseInt(prMatch[3], 10), type: 'pull' };
+        return { owner, repo, number: parseInt(prMatch[3], 10), type: "pull" };
     }
     const issueMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
     if (issueMatch) {
@@ -49,7 +68,7 @@ export function parseGitHubUrl(url) {
         const repo = issueMatch[2];
         if (!isValidOwnerRepo(owner, repo))
             return null;
-        return { owner, repo, number: parseInt(issueMatch[3], 10), type: 'issues' };
+        return { owner, repo, number: parseInt(issueMatch[3], 10), type: "issues" };
     }
     return null;
 }
@@ -58,12 +77,12 @@ export function daysBetween(from, to = new Date()) {
 }
 export function getCLIVersion() {
     try {
-        const pkgPath = path.join(path.dirname(process.argv[1]), '..', 'package.json');
-        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+        const pkgPath = path.join(path.dirname(process.argv[1]), "..", "package.json");
+        return JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
     }
     catch (err) {
         debug(MODULE, `Could not read CLI version: ${errorMessage(err)}`);
-        return 'unknown';
+        return "unknown";
     }
 }
 export function getGitHubToken() {
@@ -77,30 +96,30 @@ export function getGitHubToken() {
         return cachedGitHubToken;
     }
     try {
-        const token = execFileSync('gh', ['auth', 'token'], {
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
+        const token = execFileSync("gh", ["auth", "token"], {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
             timeout: 2000,
         }).trim();
         if (token && token.length > 0) {
             cachedGitHubToken = token;
-            debug(MODULE, 'Using GitHub token from gh CLI');
+            debug(MODULE, "Using GitHub token from gh CLI");
             return cachedGitHubToken;
         }
     }
     catch (err) {
-        debug(MODULE, 'gh auth token failed', err);
+        debug(MODULE, "gh auth token failed", err);
     }
     return null;
 }
 export function requireGitHubToken() {
     const token = getGitHubToken();
     if (!token) {
-        throw new ConfigurationError('GitHub authentication required.\n\n' +
-            'Options:\n' +
-            '  1. Use gh CLI: gh auth login\n' +
-            '  2. Set GITHUB_TOKEN environment variable\n\n' +
-            'The gh CLI is recommended - install from https://cli.github.com');
+        throw new ConfigurationError("GitHub authentication required.\n\n" +
+            "Options:\n" +
+            "  1. Use gh CLI: gh auth login\n" +
+            "  2. Set GITHUB_TOKEN environment variable\n\n" +
+            "The gh CLI is recommended - install from https://cli.github.com");
     }
     return token;
 }

package/dist/formatters/json.d.ts

@@ -1,6 +1,6 @@
 /**
  * JSON output formatter for oss-scout CLI.
  */
-import type { ErrorCode } from '../core/errors.js';
+import type { ErrorCode } from "../core/errors.js";
 export declare function formatJsonSuccess<T>(data: T): string;
 export declare function formatJsonError(error: string, errorCode?: ErrorCode): string;

package/dist/index.d.ts

@@ -14,10 +14,10 @@
  *
  * @packageDocumentation
  */
-export { createScout, OssScout } from './scout.js';
-export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectHealth, SearchPriority, CheckResult, VetListOptions, VetListResult, VetListEntry, VetListSummary, } from './core/types.js';
-export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, SearchStrategy, } from './core/schemas.js';
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from './core/schemas.js';
-export { requireGitHubToken, getGitHubToken } from './core/utils.js';
-export { IssueDiscovery } from './core/issue-discovery.js';
-export { IssueVetter, type ScoutStateReader } from './core/issue-vetting.js';
+export { createScout, OssScout } from "./scout.js";
+export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectHealth, SearchPriority, CheckResult, VetListOptions, VetListResult, VetListEntry, VetListSummary, } from "./core/types.js";
+export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, SearchStrategy, } from "./core/schemas.js";
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from "./core/schemas.js";
+export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
+export { IssueDiscovery } from "./core/issue-discovery.js";
+export { IssueVetter, type ScoutStateReader } from "./core/issue-vetting.js";

package/dist/index.js

@@ -15,11 +15,11 @@
  * @packageDocumentation
  */
 // Main API
-export { createScout, OssScout } from './scout.js';
+export { createScout, OssScout } from "./scout.js";
 // Schemas (for consumers who need runtime validation)
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from './core/schemas.js';
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, } from "./core/schemas.js";
 // Utilities
-export { requireGitHubToken, getGitHubToken } from './core/utils.js';
+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 { IssueDiscovery } from "./core/issue-discovery.js";
+export { IssueVetter } from "./core/issue-vetting.js";

package/dist/scout.d.ts

@@ -4,10 +4,10 @@
  * Provides personalized issue discovery, vetting, and scoring.
  * Implements ScoutStateReader to bridge state with the search engine.
  */
-import type { ScoutStateReader } from './core/issue-vetting.js';
-import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate } from './core/schemas.js';
-import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectCategory, VetListOptions, VetListResult } from './core/types.js';
-import { GistStateStore } from './core/gist-state-store.js';
+import type { ScoutStateReader } from "./core/issue-vetting.js";
+import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate } from "./core/schemas.js";
+import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, RepoScoreUpdate, ProjectCategory, VetListOptions, VetListResult } from "./core/types.js";
+import { GistStateStore } from "./core/gist-state-store.js";
 /**
  * Create an OssScout instance.
  *
@@ -114,7 +114,6 @@ export declare class OssScout implements ScoutStateReader {
      * Get the full state snapshot for serialization or external consumption.
      */
     getState(): Readonly<ScoutState>;
-    private extractRepoFromUrl;
     private updateRepoScoreFromPRs;
     /**
      * Calculate repo score (1-10) from observed data.

package/dist/scout.js

@@ -4,12 +4,55 @@
  * Provides personalized issue discovery, vetting, and scoring.
  * Implements ScoutStateReader to bridge state with the search engine.
  */
-import { IssueDiscovery } from './core/issue-discovery.js';
-import { ScoutStateSchema } from './core/schemas.js';
-import { GistStateStore, mergeStates } from './core/gist-state-store.js';
-import { getOctokit } from './core/github.js';
-import { loadLocalState } from './core/local-state.js';
-import { warn } from './core/logger.js';
+import { IssueDiscovery } from "./core/issue-discovery.js";
+import { ScoutStateSchema } from "./core/schemas.js";
+import { GistStateStore, mergeStates } from "./core/gist-state-store.js";
+import { getOctokit } from "./core/github.js";
+import { loadLocalState } from "./core/local-state.js";
+import { warn } from "./core/logger.js";
+import { extractRepoFromUrl } from "./core/utils.js";
+/** Wrap a real Octokit instance as GistOctokitLike without unsafe double casts. */
+function toGistOctokit(octokit) {
+    return {
+        gists: {
+            async get(params) {
+                const { data } = await octokit.gists.get(params);
+                if (!data.id)
+                    throw new Error("Gist get returned no id");
+                const files = data.files
+                    ? Object.fromEntries(Object.entries(data.files).map(([k, v]) => [
+                        k,
+                        v ? { content: v.content } : undefined,
+                    ]))
+                    : null;
+                return { data: { id: data.id, files } };
+            },
+            async create(params) {
+                const { data } = await octokit.gists.create(params);
+                if (!data.id)
+                    throw new Error("Gist create returned no id");
+                return { data: { id: data.id } };
+            },
+            async update(params) {
+                const { data } = await octokit.gists.update(params);
+                if (!data.id)
+                    throw new Error("Gist update returned no id");
+                return { data: { id: data.id } };
+            },
+            async list(params) {
+                const { data } = await octokit.gists.list(params);
+                return {
+                    data: data
+                        .filter((g) => g.id)
+                        .map((g) => ({
+                        id: g.id,
+                        description: g.description ?? null,
+                    })),
+                };
+            },
+        },
+    };
+}
 /**
  * Create an OssScout instance.
  *
@@ -34,14 +77,14 @@ import { warn } from './core/logger.js';
 export async function createScout(config) {
     let state;
     let gistStore = null;
-    if (config.persistence === 'provided') {
+    if (config.persistence === "provided") {
         state = config.initialState;
     }
-    else if (config.persistence === 'gist') {
-        gistStore = new GistStateStore(getOctokit(config.githubToken));
+    else if (config.persistence === "gist") {
+        gistStore = new GistStateStore(toGistOctokit(getOctokit(config.githubToken)));
         const result = await gistStore.bootstrap();
         if (result.degraded) {
-            warn('scout', 'Gist sync unavailable — running in offline mode. Changes will only be saved locally.');
+            warn("scout", "Gist sync unavailable — running in offline mode. Changes will only be saved locally.");
         }
         const localState = loadLocalState();
         state = mergeStates(localState, result.state);
@@ -126,13 +169,13 @@ export class OssScout {
             })
                 .catch((error) => {
                 const msg = error instanceof Error ? error.message : String(error);
-                const isGone = msg.includes('Not Found') || msg.includes('410');
+                const isGone = msg.includes("Not Found") || msg.includes("410");
                 results.push({
                     issueUrl: item.issueUrl,
                     repo: item.repo,
                     number: item.number,
                     title: item.title,
-                    status: isGone ? 'closed' : 'error',
+                    status: isGone ? "closed" : "error",
                     errorMessage: msg,
                 });
             })
@@ -147,15 +190,18 @@ export class OssScout {
         await Promise.allSettled(pending.values());
         const summary = {
             total: results.length,
-            stillAvailable: results.filter((r) => r.status === 'still_available').length,
-            claimed: results.filter((r) => r.status === 'claimed').length,
-            closed: results.filter((r) => r.status === 'closed').length,
-            hasPR: results.filter((r) => r.status === 'has_pr').length,
-            errors: results.filter((r) => r.status === 'error').length,
+            stillAvailable: results.filter((r) => r.status === "still_available")
+                .length,
+            claimed: results.filter((r) => r.status === "claimed").length,
+            closed: results.filter((r) => r.status === "closed").length,
+            hasPR: results.filter((r) => r.status === "has_pr").length,
+            errors: results.filter((r) => r.status === "error").length,
         };
         let prunedCount;
         if (options?.prune) {
-            const unavailableUrls = new Set(results.filter((r) => r.status !== 'still_available').map((r) => r.issueUrl));
+            const unavailableUrls = new Set(results
+                .filter((r) => r.status !== "still_available")
+                .map((r) => r.issueUrl));
             const before = (this.state.savedResults ?? []).length;
             this.state.savedResults = (this.state.savedResults ?? []).filter((r) => !unavailableUrls.has(r.issueUrl));
             prunedCount = before - (this.state.savedResults?.length ?? 0);
@@ -166,16 +212,16 @@ export class OssScout {
     classifyVetResult(candidate) {
         const checks = candidate.vettingResult.checks;
         if (!checks.noExistingPR)
-            return 'has_pr';
+            return "has_pr";
         if (!checks.notClaimed)
-            return 'claimed';
-        return 'still_available';
+            return "claimed";
+        return "still_available";
     }
     // ── State Reads (ScoutStateReader implementation) ───────────────────
     getReposWithMergedPRs() {
         const repoCounts = new Map();
         for (const pr of this.state.mergedPRs ?? []) {
-            const repo = this.extractRepoFromUrl(pr.url);
+            const repo = extractRepoFromUrl(pr.url);
             if (repo) {
                 repoCounts.set(repo, (repoCounts.get(repo) ?? 0) + 1);
             }
@@ -353,21 +399,16 @@ export class OssScout {
         return this.state;
     }
     // ── Private helpers ─────────────────────────────────────────────────
-    extractRepoFromUrl(url) {
-        const match = url.match(/github\.com\/([^/]+\/[^/]+)\//);
-        return match ? match[1] : null;
-    }
     updateRepoScoreFromPRs(repo) {
-        const mergedCount = (this.state.mergedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).length;
-        const closedCount = (this.state.closedPRs ?? []).filter((p) => this.extractRepoFromUrl(p.url) === repo).length;
+        const mergedCount = (this.state.mergedPRs ?? []).filter((p) => extractRepoFromUrl(p.url) === repo).length;
+        const closedCount = (this.state.closedPRs ?? []).filter((p) => extractRepoFromUrl(p.url) === repo).length;
         this.updateRepoScore(repo, {
             mergedPRCount: mergedCount,
             closedWithoutMergeCount: closedCount,
             lastMergedAt: mergedCount > 0
                 ? (this.state.mergedPRs ?? [])
-                    .filter((p) => this.extractRepoFromUrl(p.url) === repo)
-                    .sort((a, b) => b.mergedAt.localeCompare(a.mergedAt))[0]
-                    ?.mergedAt
+                    .filter((p) => extractRepoFromUrl(p.url) === repo)
+                    .sort((a, b) => b.mergedAt.localeCompare(a.mergedAt))[0]?.mergedAt
                 : undefined,
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Find open source issues personalized to your contribution history",
   "type": "module",
   "bin": {