@oss-scout/core 0.2.0 → 0.2.1

package/dist/core/gist-state-store.d.ts

@@ -4,7 +4,7 @@
  * Stores ScoutState as a private GitHub Gist, with a local file cache
  * as fallback when the API is unavailable.
  */
-import type { ScoutState } from './schemas.js';
+import type { ScoutState } from "./schemas.js";
 /** Minimal Octokit interface for gist operations — keeps the class testable. */
 export interface GistOctokitLike {
     gists: {

package/dist/core/gist-state-store.js

@@ -4,17 +4,17 @@
  * Stores ScoutState as a private GitHub Gist, with a local file cache
  * as fallback when the API is unavailable.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import { ScoutStateSchema } from './schemas.js';
-import { getDataDir } from './utils.js';
-import { debug, warn } from './logger.js';
-import { errorMessage } from './errors.js';
-const MODULE = 'gist-state';
-const GIST_DESCRIPTION = 'oss-scout-state';
-const GIST_FILENAME = 'state.json';
-const GIST_ID_FILE = 'gist-id';
-const CACHE_FILE = 'state-cache.json';
+import * as fs from "fs";
+import * as path from "path";
+import { ScoutStateSchema } from "./schemas.js";
+import { getDataDir } from "./utils.js";
+import { debug, warn } from "./logger.js";
+import { errorMessage } from "./errors.js";
+const MODULE = "gist-state";
+const GIST_DESCRIPTION = "oss-scout-state";
+const GIST_FILENAME = "state.json";
+const GIST_ID_FILE = "gist-id";
+const CACHE_FILE = "state-cache.json";
 const SEARCH_MAX_PAGES = 5;
 function getGistIdPath() {
     return path.join(getDataDir(), GIST_ID_FILE);
@@ -47,7 +47,7 @@ export class GistStateStore {
     async push(state) {
         this.writeCache(state);
         if (!this.gistId) {
-            warn(MODULE, 'No gist ID — cannot push');
+            warn(MODULE, "No gist ID — cannot push");
             return false;
         }
         try {
@@ -57,7 +57,7 @@ export class GistStateStore {
                     [GIST_FILENAME]: { content: JSON.stringify(state, null, 2) },
                 },
             });
-            debug(MODULE, 'State pushed to gist');
+            debug(MODULE, "State pushed to gist");
             return true;
         }
         catch (err) {
@@ -104,7 +104,7 @@ export class GistStateStore {
             catch (err) {
                 debug(MODULE, `Cached gist ID invalid: ${errorMessage(err)}`);
             }
-            debug(MODULE, 'Cached gist ID invalid, searching...');
+            debug(MODULE, "Cached gist ID invalid, searching...");
         }
         // 2. Search user's gists
         const foundId = await this.searchForGist();
@@ -117,9 +117,13 @@ export class GistStateStore {
                 this.writeCache(state);
                 return { gistId: foundId, state, created: false };
             }
+            // Gist exists but content failed validation — fall back to cache
+            // to avoid overwriting the user's data by creating a new gist.
+            warn(MODULE, `Found existing gist ${foundId} but content failed validation. Using local cache to avoid data loss.`);
+            return this.bootstrapFromCache();
         }
         // 3. Create new gist
-        debug(MODULE, 'No existing gist found, creating new one');
+        debug(MODULE, "No existing gist found, creating new one");
         const freshState = ScoutStateSchema.parse({ version: 1 });
         const newId = await this.createGist(freshState);
         this.saveGistId(newId);
@@ -130,20 +134,20 @@ export class GistStateStore {
     bootstrapFromCache() {
         const cached = this.readCache();
         if (cached) {
-            debug(MODULE, 'Bootstrapped from local cache (degraded mode)');
+            debug(MODULE, "Bootstrapped from local cache (degraded mode)");
             const cachedId = this.readCachedGistId();
             if (cachedId)
                 this.gistId = cachedId;
             return {
-                gistId: cachedId ?? '',
+                gistId: cachedId ?? "",
                 state: cached,
                 created: false,
                 degraded: true,
             };
         }
-        debug(MODULE, 'No cache available, using fresh state (degraded mode)');
+        debug(MODULE, "No cache available, using fresh state (degraded mode)");
         const fresh = ScoutStateSchema.parse({ version: 1 });
-        return { gistId: '', state: fresh, created: false, degraded: true };
+        return { gistId: "", state: fresh, created: false, degraded: true };
     }
     // ── Gist API operations ──────────────────────────────────────────────
     async fetchGistState(gistId) {
@@ -187,28 +191,28 @@ export class GistStateStore {
     // ── Local file helpers ───────────────────────────────────────────────
     readCachedGistId() {
         try {
-            const id = fs.readFileSync(getGistIdPath(), 'utf-8').trim();
+            const id = fs.readFileSync(getGistIdPath(), "utf-8").trim();
             return id || null;
         }
         catch (err) {
             const code = err?.code;
-            if (code !== 'ENOENT') {
+            if (code !== "ENOENT") {
                 warn(MODULE, `Failed to read cached gist ID: ${errorMessage(err)}`);
             }
             return null;
         }
     }
     saveGistId(id) {
-        fs.writeFileSync(getGistIdPath(), id + '\n', { mode: 0o600 });
+        fs.writeFileSync(getGistIdPath(), id + "\n", { mode: 0o600 });
     }
     readCache() {
         try {
-            const raw = fs.readFileSync(getCachePath(), 'utf-8');
+            const raw = fs.readFileSync(getCachePath(), "utf-8");
             return ScoutStateSchema.parse(JSON.parse(raw));
         }
         catch (err) {
             const code = err?.code;
-            if (code !== 'ENOENT') {
+            if (code !== "ENOENT") {
                 warn(MODULE, `Failed to read state cache: ${errorMessage(err)}`);
             }
             return null;
@@ -216,7 +220,9 @@ export class GistStateStore {
     }
     writeCache(state) {
         try {
-            fs.writeFileSync(getCachePath(), JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+            fs.writeFileSync(getCachePath(), JSON.stringify(state, null, 2) + "\n", {
+                mode: 0o600,
+            });
         }
         catch (err) {
             warn(MODULE, `Failed to write cache: ${errorMessage(err)}`);
@@ -243,7 +249,8 @@ export function mergeStates(local, remote) {
         closedPRs: unionByUrl(local.closedPRs, remote.closedPRs),
         savedResults: mergeSavedResults(local.savedResults ?? [], remote.savedResults ?? []),
         lastSearchAt: pickFresherTimestamp(local.lastSearchAt, remote.lastSearchAt),
-        lastRunAt: pickFresherTimestamp(local.lastRunAt, remote.lastRunAt) ?? new Date().toISOString(),
+        lastRunAt: pickFresherTimestamp(local.lastRunAt, remote.lastRunAt) ??
+            new Date().toISOString(),
         gistId: remote.gistId ?? local.gistId,
     };
 }
@@ -266,7 +273,9 @@ function mergeStarredRepos(local, remote) {
     const localTs = local.starredReposLastFetched;
     const remoteTs = remote.starredReposLastFetched;
     if (!localTs && !remoteTs)
-        return remote.starredRepos.length >= local.starredRepos.length ? remote.starredRepos : local.starredRepos;
+        return remote.starredRepos.length >= local.starredRepos.length
+            ? remote.starredRepos
+            : local.starredRepos;
     if (!localTs)
         return remote.starredRepos;
     if (!remoteTs)

package/dist/core/github.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared GitHub API client with rate limiting and throttling.
  */
-import { Octokit } from '@octokit/rest';
+import { Octokit } from "@octokit/rest";
 interface RateLimitInfo {
     remaining: number;
     limit: number;

package/dist/core/github.js

@@ -1,15 +1,15 @@
 /**
  * Shared GitHub API client with rate limiting and throttling.
  */
-import { Octokit } from '@octokit/rest';
-import { throttling } from '@octokit/plugin-throttling';
-import { warn } from './logger.js';
-const MODULE = 'github';
+import { Octokit } from "@octokit/rest";
+import { throttling } from "@octokit/plugin-throttling";
+import { warn } from "./logger.js";
+const MODULE = "github";
 const ThrottledOctokit = Octokit.plugin(throttling);
 let _octokit = null;
 let _currentToken = null;
 function formatResetTime(date) {
-    return date.toLocaleTimeString('en-US', { hour12: false });
+    return date.toLocaleTimeString("en-US", { hour12: false });
 }
 export function getRateLimitCallbacks() {
     return {

package/dist/core/http-cache.js

@@ -9,13 +9,13 @@
  * for the same endpoint (e.g., star counts for two PRs in the same repo)
  * share a single HTTP round-trip.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as crypto from 'crypto';
-import { getCacheDir } from './utils.js';
-import { debug, warn } from './logger.js';
-import { errorMessage, getHttpStatusCode } from './errors.js';
-const MODULE = 'http-cache';
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { getCacheDir } from "./utils.js";
+import { debug, warn } from "./logger.js";
+import { errorMessage, getHttpStatusCode } from "./errors.js";
+const MODULE = "http-cache";
 /**
  * Maximum age (in ms) before a cache entry is considered stale and eligible for
  * eviction during cleanup. Defaults to 24 hours. Entries older than this are
@@ -39,7 +39,7 @@ export class HttpCache {
     }
     /** Derive a filesystem-safe cache key from a URL. */
     keyFor(url) {
-        return crypto.createHash('sha256').update(url).digest('hex');
+        return crypto.createHash("sha256").update(url).digest("hex");
     }
     /** Full path to the cache file for a given URL. */
     pathFor(url) {
@@ -65,7 +65,7 @@ export class HttpCache {
     get(url) {
         const filePath = this.pathFor(url);
         try {
-            const raw = fs.readFileSync(filePath, 'utf-8');
+            const raw = fs.readFileSync(filePath, "utf-8");
             const entry = JSON.parse(raw);
             // Sanity-check: the file should contain the URL we asked for
             if (entry.url !== url) {
@@ -76,7 +76,7 @@ export class HttpCache {
         }
         catch (err) {
             const code = err?.code;
-            if (code === 'ENOENT')
+            if (code === "ENOENT")
                 return null;
             if (err instanceof SyntaxError) {
                 debug(MODULE, `Corrupt cache entry, deleting: ${url}`);
@@ -103,7 +103,10 @@ export class HttpCache {
             cachedAt: new Date().toISOString(),
         };
         try {
-            fs.writeFileSync(this.pathFor(url), JSON.stringify(entry), { encoding: 'utf-8', mode: 0o600 });
+            fs.writeFileSync(this.pathFor(url), JSON.stringify(entry), {
+                encoding: "utf-8",
+                mode: 0o600,
+            });
             debug(MODULE, `Cached response for ${url}`);
         }
         catch (err) {
@@ -137,11 +140,11 @@ export class HttpCache {
             const files = fs.readdirSync(this.cacheDir);
             const now = Date.now();
             for (const file of files) {
-                if (!file.endsWith('.json'))
+                if (!file.endsWith(".json"))
                     continue;
                 const filePath = path.join(this.cacheDir, file);
                 try {
-                    const raw = fs.readFileSync(filePath, 'utf-8');
+                    const raw = fs.readFileSync(filePath, "utf-8");
                     const entry = JSON.parse(raw);
                     const age = now - new Date(entry.cachedAt).getTime();
                     if (age > maxAgeMs) {
@@ -163,7 +166,7 @@ export class HttpCache {
         }
         catch (err) {
             const code = err?.code;
-            if (code !== 'ENOENT') {
+            if (code !== "ENOENT") {
                 warn(MODULE, `Failed to evict stale cache entries: ${errorMessage(err)}`);
             }
         }
@@ -179,15 +182,15 @@ export class HttpCache {
         try {
             const files = fs.readdirSync(this.cacheDir);
             for (const file of files) {
-                if (!file.endsWith('.json'))
+                if (!file.endsWith(".json"))
                     continue;
                 fs.unlinkSync(path.join(this.cacheDir, file));
             }
-            debug(MODULE, 'Cache cleared');
+            debug(MODULE, "Cache cleared");
         }
         catch (err) {
             const code = err?.code;
-            if (code !== 'ENOENT') {
+            if (code !== "ENOENT") {
                 warn(MODULE, `Failed to clear cache: ${errorMessage(err)}`);
             }
         }
@@ -197,11 +200,12 @@ export class HttpCache {
      */
     size() {
         try {
-            return fs.readdirSync(this.cacheDir).filter((f) => f.endsWith('.json')).length;
+            return fs.readdirSync(this.cacheDir).filter((f) => f.endsWith(".json"))
+                .length;
         }
         catch (err) {
             const code = err?.code;
-            if (code !== 'ENOENT') {
+            if (code !== "ENOENT") {
                 debug(MODULE, `Failed to read cache size: ${errorMessage(err)}`);
             }
             return 0;
@@ -253,12 +257,12 @@ export async function cachedRequest(cache, url, fetcher) {
         const extraHeaders = {};
         const cached = cache.get(url);
         if (cached) {
-            extraHeaders['if-none-match'] = cached.etag;
+            extraHeaders["if-none-match"] = cached.etag;
         }
         try {
             const response = await fetcher(extraHeaders);
             // Store ETag if present (headers may be absent in test mocks)
-            const etag = response.headers?.['etag'];
+            const etag = response.headers?.["etag"];
             if (etag) {
                 cache.set(url, etag, response.data);
             }
@@ -302,7 +306,7 @@ export async function cachedTimeBased(cache, key, maxAgeMs, fetcher) {
         return cached;
     }
     const result = await fetcher();
-    cache.set(key, '', result);
+    cache.set(key, "", result);
     return result;
 }
 /**

package/dist/core/issue-discovery.d.ts

@@ -11,9 +11,9 @@
  *
  * All state is injected via constructor parameters (ScoutStateReader + ScoutPreferences).
  */
-import { type IssueCandidate } from './types.js';
-import type { ScoutPreferences, SearchStrategy } from './schemas.js';
-import { type ScoutStateReader } from './issue-vetting.js';
+import { type IssueCandidate } from "./types.js";
+import type { ScoutPreferences, SearchStrategy } from "./schemas.js";
+import { type ScoutStateReader } from "./issue-vetting.js";
 /**
  * Multi-phase issue discovery engine that searches GitHub for contributable issues.
  *