@npm-safe/core-dsh 1.0.5

package/dist/scheduler/refresh-scheduler.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Auto-refresh scheduler with rate-limited registry polling.
+ *
+ * {@link RefreshScheduler} orchestrates periodic re-fetching of npm package
+ * metadata and re-running the static analyzer for packages on the user's
+ * watchlist or with stale cache entries. It is a pure scheduling +
+ * orchestration layer: it contains no GUI integration and no CLI command
+ * logic. All registry calls are gated through the injected {@link TokenBucket}
+ * so the scheduler respects the configured rate limit, and progress is
+ * surfaced via three {@link EventEmitter} events:
+ *
+ * - `refresh:start`    — emitted before each package refresh begins.
+ * - `refresh:complete`— emitted after a package refresh succeeds, carrying
+ *   the freshly produced {@link StaticScanReport}.
+ * - `refresh:error`   — emitted when a package refresh fails. The scheduler
+ *   does **not** throw on per-package failures; it emits the error and
+ *   continues with the next package.
+ *
+ * @module scheduler/refresh-scheduler
+ */
+import { EventEmitter } from 'node:events';
+import type { NpmRegistryClient } from '../registry/client.js';
+import type { CacheManager } from '../store/cache-manager.js';
+import type { TokenBucket } from './rate-limiter.js';
+import type { StaticAnalyzer } from '../scanner/static-rules.js';
+import type { StaticScanReport } from '../scanner/types.js';
+import type { LlmScanReport } from '../scanner/types.js';
+import type { LlmScanProvider } from '../llm/provider.js';
+/**
+ * Payload of the `refresh:start` event.
+ */
+export interface RefreshStartPayload {
+    /** Name of the package about to be refreshed. */
+    readonly packageName: string;
+}
+/**
+ * Payload of the `refresh:complete` event.
+ */
+export interface RefreshCompletePayload {
+    /** Name of the package that was refreshed. */
+    readonly packageName: string;
+    /** The static scan report produced during the refresh. */
+    readonly report: StaticScanReport;
+    readonly llmScan?: LlmScanReport;
+}
+/**
+ * Payload of the `refresh:error` event.
+ */
+export interface RefreshErrorPayload {
+    /** Name of the package whose refresh failed. */
+    readonly packageName: string;
+    /** The error that caused the refresh to fail. */
+    readonly error: unknown;
+}
+/**
+ * Auto-refresh scheduler that periodically polls the npm registry for
+ * updated package metadata, re-caches it, and re-runs the static analyzer.
+ *
+ * The scheduler is constructed with four collaborators:
+ *
+ * - {@link NpmRegistryClient} — used to fetch fresh packuments.
+ * - {@link CacheManager} — used to read the watchlist/stale set and persist
+ *   refreshed metadata + security reports.
+ * - {@link TokenBucket} — gates every registry call so the configured rate
+ *   limit is respected.
+ * - {@link StaticAnalyzer} — re-evaluates the refreshed package's README and
+ *   latest version manifest.
+ *
+ * Call {@link RefreshScheduler.start} to begin the refresh loop and
+ * {@link RefreshScheduler.stop} to tear it down.
+ *
+ * @example
+ * ```ts
+ * const scheduler = new RefreshScheduler(client, cache, limiter, analyzer);
+ * scheduler.on('refresh:complete', ({ packageName, report }) => {
+ *   console.log(`${packageName}: score=${report.score}`);
+ * });
+ * scheduler.start(); // refresh hourly
+ * // ... later
+ * scheduler.stop();
+ * ```
+ */
+export declare class RefreshScheduler extends EventEmitter {
+    /** Registry client used to fetch fresh packuments. */
+    private readonly client;
+    /** Cache manager used to read the watchlist and persist results. */
+    private readonly cache;
+    /** Rate limiter gating every registry call. */
+    private readonly limiter;
+    /** Static analyzer re-run on each refreshed package. */
+    private readonly analyzer;
+    /** Optional semantic analyzer for refreshed packages (mutable at runtime). */
+    private llmProvider;
+    /** Handle to the recurring refresh interval, or `null` when stopped. */
+    private intervalId;
+    /**
+     * @param client - Registry client for fetching package metadata.
+     * @param cache - Cache manager for reading the watchlist and persisting
+     *   refreshed metadata + reports.
+     * @param limiter - Token bucket rate limiter; one token is consumed per
+     *   registry fetch.
+     * @param analyzer - Static analyzer re-run on each refreshed package.
+     * @param llmProvider - Optional semantic analyzer for refreshed packages, or
+     *   a getter that returns the current provider. A getter is preferred when the
+     *   provider can be changed at runtime.
+     */
+    constructor(client: NpmRegistryClient, cache: CacheManager, limiter: TokenBucket, analyzer: StaticAnalyzer, llmProvider?: LlmScanProvider | (() => LlmScanProvider | undefined));
+    /**
+     * Replace the LLM provider used during refreshes.
+     *
+     * Safe to call while the scheduler is running; the next refresh cycle uses
+     * the new provider.
+     *
+     * @param provider - The new provider, or `undefined` to disable LLM scanning.
+     */
+    setLlmProvider(provider?: LlmScanProvider): void;
+    /** Resolve the current LLM provider. */
+    private getLlmProvider;
+    /**
+     * Start the periodic refresh loop.
+     *
+     * Immediately kicks off a background {@link RefreshScheduler.refreshWatchlist}
+     * call (without awaiting it), then schedules the same call to repeat every
+     * `intervalMs` milliseconds. Safe to call multiple times; calling while
+     * already running clears the previous interval before starting a new one.
+     *
+     * @param intervalMs - Milliseconds between refresh cycles. Defaults to
+     *   {@link DEFAULT_INTERVAL_MS} (1 hour).
+     */
+    start(intervalMs?: number): void;
+    /**
+     * Stop the periodic refresh loop.
+     *
+     * Clears the recurring interval. Any in-flight refresh that is already
+     * executing continues to completion; this method only prevents future
+     * cycles from being scheduled. Safe to call when not running.
+     */
+    stop(): void;
+    /**
+     * Refresh a single package: fetch its latest metadata from the registry,
+     * persist it to the cache, re-run the static analyzer against the latest
+     * version's README and manifest, and persist the resulting report.
+     *
+     * One token is consumed from the rate limiter before the registry fetch,
+     * so concurrent callers are naturally throttled. Per-package failures are
+     * surfaced via the `refresh:error` event rather than thrown — the promise
+     * resolves normally after emitting the error so a failing package does not
+     * abort a batch.
+     *
+     * **Cooperative cancellation**: when `options.signal` is supplied it is
+     * forwarded to the registry client and the LLM scan. An external abort
+     * propagates as `DOMException('The operation was aborted.', 'AbortError')`
+     * (instead of the usual `false` return) so a caller awaiting refresh can
+     * observe the abort promptly.
+     *
+     * @param name - Fully-qualified package name (scope included when scoped).
+     * @param options - Optional refresh options. `options.signal` is an
+     *   external abort signal forwarded to the registry fetch and LLM scan.
+     * @returns `true` when the refresh succeeds, or `false` after emitting
+     *   `refresh:error`. Never rejects for per-package refresh failures —
+     *   only rejects with `AbortError` when `options.signal` is aborted.
+     */
+    refreshPackage(name: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<boolean>;
+    private scanWithLlm;
+    /**
+     * Refresh every package whose cached metadata has passed its TTL.
+     *
+     * Packages are processed sequentially (one after another) so the rate
+     * limiter is respected and the registry is not hammered in bursts. Each
+     * package's outcome is surfaced via the `refresh:complete` / `refresh:error`
+     * events emitted by {@link RefreshScheduler.refreshPackage}.
+     *
+     * **Cooperative cancellation**: when `options.signal` is supplied, the top
+     * of each loop iteration checks `signal.aborted` and throws
+     * `DOMException('The operation was aborted.', 'AbortError')` so a
+     * mid-batch abort settles promptly instead of continuing to iterate.
+     *
+     * @param options - Optional refresh options. `options.signal` is an
+     *   external abort signal forwarded to each per-package refresh.
+     * @returns `true` when every stale package refresh succeeds, otherwise
+     *   `false` after all stale packages have been attempted. Rejects with
+     *   `AbortError` when `options.signal` is aborted.
+     */
+    refreshAll(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<boolean>;
+    /**
+     * Refresh every package on the user's watchlist.
+     *
+     * Watched packages are processed sequentially so the rate limiter is
+     * respected. Each package's outcome is surfaced via the
+     * `refresh:complete` / `refresh:error` events emitted by
+     * {@link RefreshScheduler.refreshPackage}.
+     *
+     * @returns Resolves once all watched packages have been attempted.
+     */
+    private refreshWatchlist;
+}
+//# sourceMappingURL=refresh-scheduler.d.ts.map

package/dist/scheduler/refresh-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/refresh-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,8EAA8E;IAC9E,OAAO,CAAC,WAAW,CAAkD;IACrE,wEAAwE;IACxE,OAAO,CAAC,UAAU,CAA+C;IAEjE;;;;;;;;;;OAUG;gBAED,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,cAAc,EACxB,WAAW,CAAC,EAAE,eAAe,GAAG,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;IAcrE;;;;;;;OAOG;IACH,cAAc,CAAC,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI;IAIhD,wCAAwC;IACxC,OAAO,CAAC,cAAc;IAItB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,UAAU,GAAE,MAA4B,GAAG,IAAI;IAerD;;;;;;OAMG;IACH,IAAI,IAAI,IAAI;IAOZ;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,OAAO,CAAC;YA0DL,WAAW;IAqCzB;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CACd,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,OAAO,CAAC;IAiBnB;;;;;;;;;OASG;YACW,gBAAgB;CAM/B"}

package/dist/scheduler/refresh-scheduler.js

@@ -0,0 +1,295 @@
+/**
+ * Auto-refresh scheduler with rate-limited registry polling.
+ *
+ * {@link RefreshScheduler} orchestrates periodic re-fetching of npm package
+ * metadata and re-running the static analyzer for packages on the user's
+ * watchlist or with stale cache entries. It is a pure scheduling +
+ * orchestration layer: it contains no GUI integration and no CLI command
+ * logic. All registry calls are gated through the injected {@link TokenBucket}
+ * so the scheduler respects the configured rate limit, and progress is
+ * surfaced via three {@link EventEmitter} events:
+ *
+ * - `refresh:start`    — emitted before each package refresh begins.
+ * - `refresh:complete`— emitted after a package refresh succeeds, carrying
+ *   the freshly produced {@link StaticScanReport}.
+ * - `refresh:error`   — emitted when a package refresh fails. The scheduler
+ *   does **not** throw on per-package failures; it emits the error and
+ *   continues with the next package.
+ *
+ * @module scheduler/refresh-scheduler
+ */
+import { EventEmitter } from 'node:events';
+/**
+ * Default refresh interval: 1 hour in milliseconds.
+ */
+const DEFAULT_INTERVAL_MS = 3_600_000;
+/**
+ * Auto-refresh scheduler that periodically polls the npm registry for
+ * updated package metadata, re-caches it, and re-runs the static analyzer.
+ *
+ * The scheduler is constructed with four collaborators:
+ *
+ * - {@link NpmRegistryClient} — used to fetch fresh packuments.
+ * - {@link CacheManager} — used to read the watchlist/stale set and persist
+ *   refreshed metadata + security reports.
+ * - {@link TokenBucket} — gates every registry call so the configured rate
+ *   limit is respected.
+ * - {@link StaticAnalyzer} — re-evaluates the refreshed package's README and
+ *   latest version manifest.
+ *
+ * Call {@link RefreshScheduler.start} to begin the refresh loop and
+ * {@link RefreshScheduler.stop} to tear it down.
+ *
+ * @example
+ * ```ts
+ * const scheduler = new RefreshScheduler(client, cache, limiter, analyzer);
+ * scheduler.on('refresh:complete', ({ packageName, report }) => {
+ *   console.log(`${packageName}: score=${report.score}`);
+ * });
+ * scheduler.start(); // refresh hourly
+ * // ... later
+ * scheduler.stop();
+ * ```
+ */
+export class RefreshScheduler extends EventEmitter {
+    /** Registry client used to fetch fresh packuments. */
+    client;
+    /** Cache manager used to read the watchlist and persist results. */
+    cache;
+    /** Rate limiter gating every registry call. */
+    limiter;
+    /** Static analyzer re-run on each refreshed package. */
+    analyzer;
+    /** Optional semantic analyzer for refreshed packages (mutable at runtime). */
+    llmProvider;
+    /** Handle to the recurring refresh interval, or `null` when stopped. */
+    intervalId = null;
+    /**
+     * @param client - Registry client for fetching package metadata.
+     * @param cache - Cache manager for reading the watchlist and persisting
+     *   refreshed metadata + reports.
+     * @param limiter - Token bucket rate limiter; one token is consumed per
+     *   registry fetch.
+     * @param analyzer - Static analyzer re-run on each refreshed package.
+     * @param llmProvider - Optional semantic analyzer for refreshed packages, or
+     *   a getter that returns the current provider. A getter is preferred when the
+     *   provider can be changed at runtime.
+     */
+    constructor(client, cache, limiter, analyzer, llmProvider) {
+        super();
+        this.client = client;
+        this.cache = cache;
+        this.limiter = limiter;
+        this.analyzer = analyzer;
+        this.llmProvider = llmProvider
+            ? typeof llmProvider === 'function'
+                ? llmProvider
+                : () => llmProvider
+            : undefined;
+    }
+    /**
+     * Replace the LLM provider used during refreshes.
+     *
+     * Safe to call while the scheduler is running; the next refresh cycle uses
+     * the new provider.
+     *
+     * @param provider - The new provider, or `undefined` to disable LLM scanning.
+     */
+    setLlmProvider(provider) {
+        this.llmProvider = provider ? () => provider : undefined;
+    }
+    /** Resolve the current LLM provider. */
+    getLlmProvider() {
+        return this.llmProvider?.();
+    }
+    /**
+     * Start the periodic refresh loop.
+     *
+     * Immediately kicks off a background {@link RefreshScheduler.refreshWatchlist}
+     * call (without awaiting it), then schedules the same call to repeat every
+     * `intervalMs` milliseconds. Safe to call multiple times; calling while
+     * already running clears the previous interval before starting a new one.
+     *
+     * @param intervalMs - Milliseconds between refresh cycles. Defaults to
+     *   {@link DEFAULT_INTERVAL_MS} (1 hour).
+     */
+    start(intervalMs = DEFAULT_INTERVAL_MS) {
+        // Avoid double-starting: clear any existing interval first.
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+        // Kick off the first cycle immediately in the background.
+        void this.refreshWatchlist();
+        this.intervalId = setInterval(() => {
+            void this.refreshWatchlist();
+        }, intervalMs);
+    }
+    /**
+     * Stop the periodic refresh loop.
+     *
+     * Clears the recurring interval. Any in-flight refresh that is already
+     * executing continues to completion; this method only prevents future
+     * cycles from being scheduled. Safe to call when not running.
+     */
+    stop() {
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    /**
+     * Refresh a single package: fetch its latest metadata from the registry,
+     * persist it to the cache, re-run the static analyzer against the latest
+     * version's README and manifest, and persist the resulting report.
+     *
+     * One token is consumed from the rate limiter before the registry fetch,
+     * so concurrent callers are naturally throttled. Per-package failures are
+     * surfaced via the `refresh:error` event rather than thrown — the promise
+     * resolves normally after emitting the error so a failing package does not
+     * abort a batch.
+     *
+     * **Cooperative cancellation**: when `options.signal` is supplied it is
+     * forwarded to the registry client and the LLM scan. An external abort
+     * propagates as `DOMException('The operation was aborted.', 'AbortError')`
+     * (instead of the usual `false` return) so a caller awaiting refresh can
+     * observe the abort promptly.
+     *
+     * @param name - Fully-qualified package name (scope included when scoped).
+     * @param options - Optional refresh options. `options.signal` is an
+     *   external abort signal forwarded to the registry fetch and LLM scan.
+     * @returns `true` when the refresh succeeds, or `false` after emitting
+     *   `refresh:error`. Never rejects for per-package refresh failures —
+     *   only rejects with `AbortError` when `options.signal` is aborted.
+     */
+    async refreshPackage(name, options) {
+        this.emit('refresh:start', { packageName: name });
+        try {
+            // Gate the registry call through the rate limiter.
+            await this.limiter.consume(1);
+            const meta = await this.client.getPackageMetadata(name, {
+                signal: options?.signal,
+            });
+            // Persist the fresh packument before doing anything else so the
+            // cache is updated even if analysis fails downstream.
+            await this.cache.setPackage(meta);
+            // Derive a package.json-like object from the latest version manifest
+            // for the static analyzer. The analyzer reads `name`, `version`,
+            // `scripts`, `browser`, and `publishConfig.registry`; the manifest
+            // carries `name`/`version`/`scripts` directly, and any extra fields
+            // present on the registry payload (e.g. `browser`, `publishConfig`)
+            // are passed through via the spread.
+            const latestVersion = meta['dist-tags'].latest;
+            const manifest = meta.versions[latestVersion];
+            const packageJson = manifest
+                ? { ...manifest }
+                : undefined;
+            const readme = meta.readme ?? '';
+            const report = this.analyzer.analyze(readme, packageJson);
+            await this.cache.setSecurityReport(report);
+            const llmProvider = this.getLlmProvider();
+            const llmScan = llmProvider
+                ? await this.scanWithLlm(meta, latestVersion, options?.signal)
+                : undefined;
+            this.emit('refresh:complete', { packageName: name, report, llmScan });
+            return true;
+        }
+        catch (error) {
+            // An external abort must propagate as AbortError instead of being
+            // swallowed as a per-package failure — the cooperative-cancellation
+            // contract requires the caller to observe the abort promptly.
+            if (options?.signal?.aborted) {
+                throw new DOMException('The operation was aborted.', 'AbortError');
+            }
+            // Per-package failures are reported, not thrown, so a batch refresh
+            // continues with the remaining packages.
+            this.emit('refresh:error', { packageName: name, error });
+            return false;
+        }
+    }
+    async scanWithLlm(meta, version, signal) {
+        const provider = this.getLlmProvider();
+        if (!provider) {
+            return { enabled: false, reason: 'LLM provider is not configured.' };
+        }
+        try {
+            const manifest = meta.versions[version];
+            const report = await provider.scan({
+                packageName: meta.name,
+                version,
+                description: meta.description ?? '',
+                readme: meta.readme ?? '',
+                packageJson: manifest ? { ...manifest } : undefined,
+                signal,
+            });
+            await this.cache.setLlmScanReport(meta.name, version, report);
+            return report;
+        }
+        catch (error) {
+            // An external abort must propagate as AbortError so the caller
+            // settles promptly (cooperative cancellation).
+            if (signal?.aborted) {
+                throw new DOMException('The operation was aborted.', 'AbortError');
+            }
+            const report = {
+                enabled: false,
+                reason: error instanceof Error ? error.message : String(error),
+                scannedAt: new Date().toISOString(),
+            };
+            await this.cache.setLlmScanReport(meta.name, version, report);
+            return report;
+        }
+    }
+    /**
+     * Refresh every package whose cached metadata has passed its TTL.
+     *
+     * Packages are processed sequentially (one after another) so the rate
+     * limiter is respected and the registry is not hammered in bursts. Each
+     * package's outcome is surfaced via the `refresh:complete` / `refresh:error`
+     * events emitted by {@link RefreshScheduler.refreshPackage}.
+     *
+     * **Cooperative cancellation**: when `options.signal` is supplied, the top
+     * of each loop iteration checks `signal.aborted` and throws
+     * `DOMException('The operation was aborted.', 'AbortError')` so a
+     * mid-batch abort settles promptly instead of continuing to iterate.
+     *
+     * @param options - Optional refresh options. `options.signal` is an
+     *   external abort signal forwarded to each per-package refresh.
+     * @returns `true` when every stale package refresh succeeds, otherwise
+     *   `false` after all stale packages have been attempted. Rejects with
+     *   `AbortError` when `options.signal` is aborted.
+     */
+    async refreshAll(options) {
+        const stale = await this.cache.getStalePackages();
+        let allSucceeded = true;
+        for (const name of stale) {
+            // Short-circuit at the top of each iteration so an aborted batch
+            // settles promptly (cooperative cancellation).
+            if (options?.signal?.aborted) {
+                throw new DOMException('The operation was aborted.', 'AbortError');
+            }
+            const succeeded = await this.refreshPackage(name, {
+                signal: options?.signal,
+            });
+            allSucceeded = allSucceeded && succeeded;
+        }
+        return allSucceeded;
+    }
+    /**
+     * Refresh every package on the user's watchlist.
+     *
+     * Watched packages are processed sequentially so the rate limiter is
+     * respected. Each package's outcome is surfaced via the
+     * `refresh:complete` / `refresh:error` events emitted by
+     * {@link RefreshScheduler.refreshPackage}.
+     *
+     * @returns Resolves once all watched packages have been attempted.
+     */
+    async refreshWatchlist() {
+        const watchlist = await this.cache.getWatchlist();
+        for (const name of watchlist) {
+            await this.refreshPackage(name);
+        }
+    }
+}
+//# sourceMappingURL=refresh-scheduler.js.map

package/dist/scheduler/refresh-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-scheduler.js","sourceRoot":"","sources":["../../src/scheduler/refresh-scheduler.ts"],"names":[],"mappings":"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"}

package/dist/store/cache-manager.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Cache read/write layer for @npm-safe/core.
+ *
+ * {@link CacheManager} sits on top of a {@link DatabaseManager} connection and
+ * provides typed accessors for the cached npm metadata, security scan reports,
+ * watchlist, and key-value settings tables. It owns the TTL policy for the
+ * `packages` table: every {@link CacheManager.setPackage} call stamps the row
+ * with an expiry timestamp (`ttl_until`) computed as `now + cacheTtlMs`, and
+ * {@link CacheManager.getPackage} refuses to return rows whose TTL has
+ * elapsed. Scheduling of refreshes is intentionally out of scope — that is
+ * the job of the refresh-scheduler; this module only reads and writes.
+ *
+ * All methods return `Promise`s for API consistency and future async backing
+ * stores, even though the underlying `better-sqlite3` calls are synchronous.
+ *
+ * @module store/cache-manager
+ */
+import { DatabaseManager } from "./database.js";
+import type { PackageMetadata } from "../registry/types.js";
+import { type LlmScanReport, type StaticScanReport } from "../scanner/types.js";
+/**
+ * Default cache time-to-live for package metadata: 1 hour in milliseconds.
+ */
+export declare const DEFAULT_CACHE_TTL_MS = 3600000;
+/**
+ * Options accepted by the {@link CacheManager} constructor.
+ */
+export interface CacheManagerOptions {
+    /**
+     * Time-to-live for cached package metadata, in milliseconds. A row fetched
+     * via {@link CacheManager.getPackage} is considered stale once `ttl_until`
+     * is in the past. Sub-second TTLs (e.g. `500`) are supported and stored
+     * with millisecond precision. Defaults to {@link DEFAULT_CACHE_TTL_MS}
+     * (1 hour).
+     */
+    readonly cacheTtlMs?: number;
+}
+/**
+ * Cache read/write manager backed by a {@link DatabaseManager} connection.
+ *
+ * The manager is stateless beyond the TTL configuration and the injected
+ * database handle, so it is safe to construct one per request or to share a
+ * long-lived instance. All public methods are async-returning for API
+ * consistency; the underlying `better-sqlite3` calls are synchronous.
+ */
+export declare class CacheManager {
+    /** Underlying better-sqlite3 connection accessor. */
+    private readonly db;
+    /** Cache TTL in milliseconds applied to newly written package rows. */
+    private readonly cacheTtlMs;
+    /**
+     * @param database - The {@link DatabaseManager} supplying the connection.
+     * @param options - Optional configuration; see {@link CacheManagerOptions}.
+     */
+    constructor(database: DatabaseManager, options?: CacheManagerOptions);
+    /**
+     * Returns cached package metadata for `name` if the row is still fresh
+     * (i.e. `ttl_until >= now`). Returns `null` when the row is missing or
+     * stale; callers are expected to re-fetch from the registry and call
+     * {@link CacheManager.setPackage} to refresh the cache.
+     *
+     * @param name - Fully-qualified package name (scope included when scoped).
+     * @returns The cached {@link PackageMetadata}, or `null` if absent/stale.
+     */
+    getPackage(name: string): Promise<PackageMetadata | null>;
+    /**
+     * Upserts a package metadata row, stamping it with a fresh TTL computed as
+     * `now + cacheTtlMs`. The full packument is serialized into the
+     * `registry_data` JSON column; the scalar columns (`latest_version`,
+     * `description`, `homepage`, `repository`) are denormalized for cheap
+     * listing queries.
+     *
+     * @param meta - The packument returned by the npm registry.
+     */
+    setPackage(meta: PackageMetadata): Promise<void>;
+    /**
+     * Returns the most recent static security report for `pkg`@`version`, or
+     * `null` if none is cached. The {@link SecurityLevel} is reconstructed from
+     * the persisted numeric score because the `security_reports` table stores
+     * only the score, not the enum.
+     *
+     * @param pkg - Fully-qualified package name.
+     * @param version - Semver version string.
+     * @returns The cached {@link StaticScanReport}, or `null` if absent.
+     */
+    getSecurityReport(pkg: string, version: string): Promise<StaticScanReport | null>;
+    /**
+     * Upserts a static security report into the `security_reports` table. The
+     * findings array is serialized to JSON in the `findings_json` column; the
+     * numeric score is stored in `overall_score`. The row is keyed by
+     * `(package_name, version, scan_type)` via the table's UNIQUE constraint.
+     *
+     * @param report - The static scan report to persist.
+     */
+    setSecurityReport(report: StaticScanReport): Promise<void>;
+    getLlmScanReport(pkg: string, version: string): Promise<LlmScanReport | null>;
+    setLlmScanReport(packageName: string, version: string, report: LlmScanReport): Promise<void>;
+    /**
+     * Returns the list of package names currently on the user's watchlist.
+     *
+     * @returns All watched package names, in insertion order.
+     */
+    getWatchlist(): Promise<string[]>;
+    /**
+     * Adds `name` to the watchlist. Idempotent: inserting a name that is
+     * already watched is a no-op (INSERT OR IGNORE).
+     *
+     * @param name - Fully-qualified package name to watch.
+     */
+    addToWatchlist(name: string): Promise<void>;
+    /**
+     * Removes `name` from the watchlist. No-op if the name was not watched.
+     *
+     * @param name - Fully-qualified package name to stop watching.
+     */
+    removeFromWatchlist(name: string): Promise<void>;
+    /**
+     * Returns the value stored under `key` in the settings table, or `null`
+     * if the key is unset.
+     *
+     * @param key - Settings key.
+     * @returns The stored value, or `null` if absent.
+     */
+    getSetting(key: string): Promise<string | null>;
+    /**
+     * Upserts `value` under `key` in the settings table (INSERT OR REPLACE).
+     *
+     * @param key - Settings key.
+     * @param value - Settings value to persist.
+     */
+    setSetting(key: string, value: string): Promise<void>;
+    /**
+     * Returns the names of all cached package rows whose TTL has elapsed
+     * (`ttl_until < now`). These are candidates for an incremental refresh by
+     * the refresh-scheduler.
+     *
+     * @returns Package names with expired cache entries.
+     */
+    getStalePackages(): Promise<string[]>;
+    /**
+     * Append an entry to the persistent check history, keeping only the most
+     * recent {@link MAX_CHECK_HISTORY} entries.
+     */
+    addHistoryEntry(entry: {
+        readonly packageName: string;
+        readonly level: string;
+        readonly score: number;
+        readonly timestamp: string;
+    }): Promise<void>;
+    /**
+     * Return the persistent check history, newest first.
+     */
+    getHistory(limit?: number): Promise<ReadonlyArray<{
+        readonly packageName: string;
+        readonly level: string;
+        readonly score: number;
+        readonly timestamp: string;
+    }>>;
+    /**
+     * Remove every entry from the persistent check history.
+     */
+    clearHistory(): Promise<void>;
+}
+/** Maximum number of check-history entries retained in the database. */
+export declare const MAX_CHECK_HISTORY = 1000;
+//# sourceMappingURL=cache-manager.d.ts.map