@4da/mcp-server 4.6.1 → 4.6.3

package/dist/live/platform.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Target/platform awareness for dependency relevance.
+ *
+ * Cargo (and other ecosystems) gate dependencies behind a target: e.g.
+ * `[target.'cfg(windows)'.dependencies]` or `[target.x86_64-pc-windows-msvc.dependencies]`.
+ * A dependency that is only active on a platform the user does not build is NOT
+ * relevant to them - surfacing its advisory would be noise (the classic
+ * "GTK/webkit vuln shown to a Windows user" problem).
+ *
+ * This module evaluates a target spec against the HOST platform so the scanner
+ * can tag each dependency `platformActive` and let consumers suppress or label
+ * the irrelevant ones. It is deliberately conservative: anything it cannot
+ * confidently evaluate is treated as ACTIVE, so we never hide a real advisory.
+ */
+export function hostTarget() {
+    const os = process.platform === "win32"
+        ? "windows"
+        : process.platform === "darwin"
+            ? "macos"
+            : process.platform === "linux"
+                ? "linux"
+                : String(process.platform);
+    const family = os === "windows" ? "windows" : "unix";
+    const arch = process.arch === "x64"
+        ? "x86_64"
+        : process.arch === "arm64"
+            ? "aarch64"
+            : process.arch === "ia32"
+                ? "x86"
+                : String(process.arch);
+    return { os, family, arch };
+}
+// =============================================================================
+// Target evaluation
+// =============================================================================
+/**
+ * Is a dependency's target spec active on the host?
+ * `target` is null/empty for unconditional deps (always active).
+ * Returns true when active OR when the spec can't be confidently evaluated.
+ */
+export function targetActiveOnHost(target, host = hostTarget()) {
+    if (!target)
+        return true;
+    const spec = target.trim();
+    // Explicit target triple, e.g. "x86_64-pc-windows-msvc" or "aarch64-apple-darwin".
+    if (!spec.startsWith("cfg(")) {
+        return tripleActiveOnHost(spec, host);
+    }
+    // cfg(...) predicate. Strip the outer cfg( ).
+    const inner = spec.slice(4, spec.lastIndexOf(")"));
+    return evalCfg(inner, host);
+}
+/** Evaluate a cfg predicate body (already unwrapped from `cfg( ... )`). */
+export function evalCfg(expr, host = hostTarget()) {
+    const e = expr.trim();
+    if (!e)
+        return true;
+    // not( ... )
+    const not = matchCall(e, "not");
+    if (not !== null)
+        return !evalCfg(not, host);
+    // all( a, b, ... )
+    const all = matchCall(e, "all");
+    if (all !== null)
+        return splitArgs(all).every((a) => evalCfg(a, host));
+    // any( a, b, ... )
+    const any = matchCall(e, "any");
+    if (any !== null)
+        return splitArgs(any).some((a) => evalCfg(a, host));
+    // key = "value"
+    const kv = e.match(/^([a-z_]+)\s*=\s*"([^"]*)"$/);
+    if (kv)
+        return evalPredicate(kv[1], kv[2], host);
+    // bare identifier: windows | unix
+    if (e === "windows")
+        return host.family === "windows";
+    if (e === "unix")
+        return host.family === "unix";
+    // Unknown predicate -> conservatively active (never hide a real advisory).
+    return true;
+}
+function evalPredicate(key, value, host) {
+    switch (key) {
+        case "target_os":
+            return value === host.os;
+        case "target_family":
+            return value === host.family;
+        case "target_arch":
+            return value === host.arch;
+        case "windows":
+            return host.family === "windows";
+        case "unix":
+            return host.family === "unix";
+        default:
+            return true; // unknown key -> conservatively active
+    }
+}
+/** Match `name( ...body... )` and return the body, or null if not that call. */
+function matchCall(expr, name) {
+    if (!expr.startsWith(name))
+        return null;
+    const rest = expr.slice(name.length).trimStart();
+    if (!rest.startsWith("(") || !rest.endsWith(")"))
+        return null;
+    return rest.slice(1, -1);
+}
+/** Split top-level comma-separated args, respecting nested parentheses. */
+function splitArgs(body) {
+    const args = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of body) {
+        if (ch === "(")
+            depth++;
+        if (ch === ")")
+            depth--;
+        if (ch === "," && depth === 0) {
+            if (current.trim())
+                args.push(current.trim());
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        args.push(current.trim());
+    return args;
+}
+/** Evaluate an explicit target triple (e.g. x86_64-pc-windows-msvc) against the host. */
+function tripleActiveOnHost(triple, host) {
+    const t = triple.toLowerCase();
+    // OS component
+    const tripleOs = t.includes("windows")
+        ? "windows"
+        : t.includes("darwin") || t.includes("apple")
+            ? "macos"
+            : t.includes("linux")
+                ? "linux"
+                : null;
+    if (tripleOs && tripleOs !== host.os)
+        return false;
+    // Arch component (best-effort)
+    const tripleArch = t.startsWith("x86_64")
+        ? "x86_64"
+        : t.startsWith("aarch64")
+            ? "aarch64"
+            : t.startsWith("i686") || t.startsWith("i586")
+                ? "x86"
+                : null;
+    if (tripleArch && tripleArch !== host.arch)
+        return false;
+    return true;
+}
+//# sourceMappingURL=platform.js.map

package/dist/live/semver-utils.d.ts

@@ -2,4 +2,12 @@ import type { SemverDistance } from "./types.js";
 export declare function parseSemver(version: string): [number, number, number] | null;
 export declare function computeSemverDistance(current: string, latest: string): SemverDistance | null;
 export declare function isPreRelease(version: string): boolean;
+/**
+ * Compare two versions by MAJOR.MINOR.PATCH. Returns 1 if a > b, -1 if a < b,
+ * 0 if equal or either is unparseable. Prerelease/build suffixes are ignored
+ * (sufficient for choosing the highest fix version among advisories).
+ */
+export declare function compareSemver(a: string, b: string): number;
+/** Highest version (by MAJOR.MINOR.PATCH) from a list, or null if empty. */
+export declare function maxSemver(versions: string[]): string | null;
 //# sourceMappingURL=semver-utils.d.ts.map

package/dist/live/semver-utils.js

@@ -25,4 +25,28 @@ export function computeSemverDistance(current, latest) {
 export function isPreRelease(version) {
     return /[-+]/.test(version.replace(/^v/, "").replace(/^\d+\.\d+\.\d+/, "").slice(0, 1));
 }
+/**
+ * Compare two versions by MAJOR.MINOR.PATCH. Returns 1 if a > b, -1 if a < b,
+ * 0 if equal or either is unparseable. Prerelease/build suffixes are ignored
+ * (sufficient for choosing the highest fix version among advisories).
+ */
+export function compareSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb)
+        return 0;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return 1;
+        if (pa[i] < pb[i])
+            return -1;
+    }
+    return 0;
+}
+/** Highest version (by MAJOR.MINOR.PATCH) from a list, or null if empty. */
+export function maxSemver(versions) {
+    if (versions.length === 0)
+        return null;
+    return versions.reduce((max, v) => (compareSemver(v, max) > 0 ? v : max), versions[0]);
+}
 //# sourceMappingURL=semver-utils.js.map

package/dist/live/types.d.ts

@@ -1,4 +1,4 @@
-export type OsvEcosystem = "npm" | "crates.io" | "PyPI" | "Go" | "Maven" | "NuGet" | "RubyGems" | "Packagist";
+export type OsvEcosystem = "npm" | "crates.io" | "PyPI" | "Go" | "Maven" | "NuGet" | "RubyGems" | "Packagist" | "Pub";
 export interface ResolvedDependency {
     name: string;
     version: string | null;
@@ -6,17 +6,27 @@ export interface ResolvedDependency {
     isDev: boolean;
     isDirect: boolean;
     devScopeKnown: boolean;
+    /** Target spec gating this dep (e.g. `cfg(windows)`), or null if unconditional. */
+    target: string | null;
+    /** False when `target` is not active on the host platform (advisory is not relevant). */
+    platformActive: boolean;
 }
+/**
+ * An OSV record. The `/v1/querybatch` endpoint returns only `{ id, modified }`
+ * per vulnerability (a lightweight index); the rich fields are populated only
+ * after hydrating each advisory via `/v1/vulns/{id}`. Hence every field beyond
+ * `id` is optional — consumers must tolerate the un-hydrated shape.
+ */
 export interface OsvVulnerability {
     id: string;
-    summary: string;
-    details: string;
-    aliases: string[];
-    severity: Array<{
+    summary?: string;
+    details?: string;
+    aliases?: string[];
+    severity?: Array<{
         type: string;
         score: string;
     }>;
-    affected: Array<{
+    affected?: Array<{
         package: {
             name: string;
             ecosystem: string;
@@ -29,12 +39,18 @@ export interface OsvVulnerability {
             }>;
         }>;
     }>;
-    references: Array<{
+    references?: Array<{
         type: string;
         url: string;
     }>;
-    published: string;
-    modified: string;
+    /** GitHub-advisory severity label: LOW | MODERATE | HIGH | CRITICAL. */
+    database_specific?: {
+        severity?: string;
+    };
+    /** Set (to an RFC3339 timestamp) when the advisory has been withdrawn/retracted. */
+    withdrawn?: string;
+    published?: string;
+    modified?: string;
 }
 export interface VulnerabilityEntry {
     package: string;
@@ -51,6 +67,10 @@ export interface VulnerabilityEntry {
     fixedVersion: string | null;
     published: string;
     references: string[];
+    /** Target spec gating the affected dep, or null if unconditional. */
+    target: string | null;
+    /** False when the affected dep is not active on the host platform. */
+    platformActive: boolean;
 }
 export interface VulnerabilityScanResult {
     scannedAt: string;
@@ -58,6 +78,8 @@ export interface VulnerabilityScanResult {
     ecosystemsScanned: string[];
     totalScanned: number;
     totalVulnerable: number;
+    /** Vulnerable packages that are NOT active on the host platform (relevance noise). */
+    platformInactiveVulnerable: number;
     bySeverity: {
         critical: number;
         high: number;

package/dist/live/version-resolver.d.ts

@@ -6,11 +6,21 @@
  * Uses only Node.js built-ins — no external parsers.
  */
 import type { OsvEcosystem, ResolvedDependency } from "./types.js";
+/**
+ * Map a language/ecosystem alias to its OSV ecosystem id (case-insensitive).
+ *
+ * Falls back to "npm" ONLY for genuinely unrecognized input — a last resort, not
+ * a real default. OSV-unindexed languages (Swift, C/C++) and unknowns produce no
+ * OSV matches anyway (their package names don't collide with the npm namespace),
+ * so this never fabricates a vulnerability. Ecosystems that lack a version
+ * resolver here (NuGet/Maven/Packagist/RubyGems/Pub) still get the CORRECT label,
+ * so the moment a resolver is added the scan is right by construction.
+ */
 export declare function mapEcosystem(language: string): OsvEcosystem;
-export declare function resolveVersions(cwd: string, deps: string[], devDeps: string[], language: string): ResolvedDependency[];
+export declare function resolveVersions(cwd: string, deps: string[], devDeps: string[], language: string, targets?: Record<string, string>): ResolvedDependency[];
 /**
  * Resolve the complete lockfile package set for vulnerability scanning.
  * Direct dependency health and upgrade planning continue to use resolveVersions.
  */
-export declare function resolveAuditVersions(cwd: string, deps: string[], devDeps: string[], language: string): ResolvedDependency[];
+export declare function resolveAuditVersions(cwd: string, deps: string[], devDeps: string[], language: string, targets?: Record<string, string>): ResolvedDependency[];
 //# sourceMappingURL=version-resolver.d.ts.map

package/dist/live/version-resolver.js

@@ -8,52 +8,90 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { targetActiveOnHost } from "./platform.js";
+// Alias -> OSV ecosystem. Mirrors the desktop app's canonical
+// `Ecosystem::parse` (src-tauri/src/ecosystem.rs) so both sides recognize the
+// SAME aliases — they previously drifted (the Rust side knew csharp/dart/php
+// while this map keyed C# as "dotnet" and omitted Dart entirely, mislabeling
+// those deps). Keep this in sync with that enum.
 const ECOSYSTEM_MAP = {
     npm: "npm",
+    javascript: "npm",
+    typescript: "npm",
+    node: "npm",
+    js: "npm",
+    ts: "npm",
     rust: "crates.io",
+    cargo: "crates.io",
+    "crates.io": "crates.io",
+    crates: "crates.io",
     python: "PyPI",
+    pypi: "PyPI",
+    pip: "PyPI",
+    py: "PyPI",
     go: "Go",
+    golang: "Go",
     java: "Maven",
+    maven: "Maven",
+    kotlin: "Maven",
+    gradle: "Maven",
+    csharp: "NuGet",
+    "c#": "NuGet",
     dotnet: "NuGet",
-    ruby: "RubyGems",
+    nuget: "NuGet",
     php: "Packagist",
+    composer: "Packagist",
+    packagist: "Packagist",
+    ruby: "RubyGems",
+    rubygems: "RubyGems",
+    gem: "RubyGems",
+    dart: "Pub",
+    flutter: "Pub",
+    pub: "Pub",
 };
+/**
+ * Map a language/ecosystem alias to its OSV ecosystem id (case-insensitive).
+ *
+ * Falls back to "npm" ONLY for genuinely unrecognized input — a last resort, not
+ * a real default. OSV-unindexed languages (Swift, C/C++) and unknowns produce no
+ * OSV matches anyway (their package names don't collide with the npm namespace),
+ * so this never fabricates a vulnerability. Ecosystems that lack a version
+ * resolver here (NuGet/Maven/Packagist/RubyGems/Pub) still get the CORRECT label,
+ * so the moment a resolver is added the scan is right by construction.
+ */
 export function mapEcosystem(language) {
-    return ECOSYSTEM_MAP[language] || "npm";
+    return ECOSYSTEM_MAP[language.trim().toLowerCase()] || "npm";
 }
-export function resolveVersions(cwd, deps, devDeps, language) {
+export function resolveVersions(cwd, deps, devDeps, language, targets = {}) {
     const ecosystem = mapEcosystem(language);
     const results = [];
     const versionMap = resolveVersionMap(cwd, ecosystem);
-    for (const name of deps) {
-        results.push({
-            name,
-            version: versionMap.get(normalizePackageName(name, ecosystem)) || null,
-            ecosystem,
-            isDev: false,
-            isDirect: true,
-            devScopeKnown: true,
-        });
-    }
-    for (const name of devDeps) {
-        results.push({
+    const build = (name, isDev) => {
+        const target = targets[name] ?? null;
+        return {
             name,
             version: versionMap.get(normalizePackageName(name, ecosystem)) || null,
             ecosystem,
-            isDev: true,
+            isDev,
             isDirect: true,
             devScopeKnown: true,
-        });
-    }
+            target,
+            platformActive: targetActiveOnHost(target),
+        };
+    };
+    for (const name of deps)
+        results.push(build(name, false));
+    for (const name of devDeps)
+        results.push(build(name, true));
     return results;
 }
 /**
  * Resolve the complete lockfile package set for vulnerability scanning.
  * Direct dependency health and upgrade planning continue to use resolveVersions.
  */
-export function resolveAuditVersions(cwd, deps, devDeps, language) {
+export function resolveAuditVersions(cwd, deps, devDeps, language, targets = {}) {
     const ecosystem = mapEcosystem(language);
-    const direct = resolveVersions(cwd, deps, devDeps, language);
+    const direct = resolveVersions(cwd, deps, devDeps, language, targets);
     const versionMap = resolveVersionMap(cwd, ecosystem);
     const directNames = new Set(deps.map((name) => normalizePackageName(name, ecosystem)));
     const devNames = new Set(devDeps.map((name) => normalizePackageName(name, ecosystem)));
@@ -62,6 +100,9 @@ export function resolveAuditVersions(cwd, deps, devDeps, language) {
     for (const [name, version] of versionMap) {
         const normalized = normalizePackageName(name, ecosystem);
         const isDirect = directNames.has(normalized) || devNames.has(normalized);
+        // Transitive deps from the lockfile carry no per-dep target info (Cargo.lock
+        // doesn't encode it), so they are treated as unconditionally active.
+        const target = targets[name] ?? null;
         const candidate = {
             name,
             version,
@@ -69,6 +110,8 @@ export function resolveAuditVersions(cwd, deps, devDeps, language) {
             isDev: devNames.has(normalized),
             isDirect,
             devScopeKnown: isDirect,
+            target,
+            platformActive: targetActiveOnHost(target),
         };
         const key = dependencyKey(candidate);
         if (!seen.has(key)) {

package/dist/llm.js

@@ -107,7 +107,7 @@ export function getLLMConfig(_db) {
         const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
         const llm = settings.llm || {};
         const config = {
-            provider: llm.provider,
+            provider: (llm.provider ?? null),
             anthropic_api_key: llm.api_key || llm.anthropic_api_key,
             openai_api_key: llm.openai_api_key,
             ollama_url: llm.base_url || llm.ollama_url || "http://localhost:11434",

package/dist/project-scanner.d.ts

@@ -23,6 +23,8 @@ export interface ProjectScanResult {
         deps: string[];
         devDeps: string[];
     }>;
+    /** dependency name -> target spec (e.g. "cfg(windows)") for platform-gated deps. */
+    depTargets: Record<string, string>;
 }
 /**
  * Scan a directory for project context.

package/dist/project-scanner.js

@@ -111,6 +111,7 @@ export function scanCurrentProject(cwd) {
         projectName: path.basename(cwd),
         projectPath: cwd,
         depsByEcosystem: {},
+        depTargets: {},
     };
     const langSet = new Set();
     const fwSet = new Set();
@@ -189,6 +190,9 @@ export function scanCurrentProject(cwd) {
             parseTOMLDependencies(content, "[dependencies]", rustDeps, fwSet, RUST_FRAMEWORK_MAP);
             parseTOMLDependencies(content, "[dev-dependencies]", rustDevDeps, fwSet, RUST_FRAMEWORK_MAP);
             parseTOMLDependencies(content, "[build-dependencies]", rustDevDeps, fwSet, RUST_FRAMEWORK_MAP);
+            // Platform-gated deps: [target.'cfg(...)'.dependencies] / [target.<triple>.dependencies].
+            // Previously skipped entirely (e.g. windows-sys, winreg, libc were invisible).
+            parseTargetDependencies(content, rustDeps, rustDevDeps, result.depTargets, fwSet, RUST_FRAMEWORK_MAP);
             // Add to flat arrays for backward compat
             result.dependencies.push(...rustDeps);
             result.devDependencies.push(...rustDevDeps);
@@ -360,6 +364,36 @@ function parseTOMLDependencies(content, sectionHeader, target, frameworkSet, fra
         }
     }
 }
+/**
+ * Parse `[target.<spec>.dependencies]` (and dev/build variants) sections, which the
+ * plain section parser skips. Records each dep's target spec so the scanner can flag
+ * platform relevance. `<spec>` is a cfg() predicate or an explicit target triple.
+ */
+function parseTargetDependencies(content, deps, devDeps, depTargets, frameworkSet, frameworkMap) {
+    const headerRegex = /^\[target\.(.+?)\.(dependencies|dev-dependencies|build-dependencies)\]\s*$/gm;
+    let m;
+    while ((m = headerRegex.exec(content)) !== null) {
+        const spec = m[1].trim().replace(/^['"]|['"]$/g, ""); // strip surrounding quotes
+        const isDev = m[2] !== "dependencies";
+        // Body runs from the end of this header line to the next section header.
+        const rest = content.slice(m.index + m[0].length);
+        const nextHeader = rest.search(/^\[/m);
+        const body = nextHeader === -1 ? rest : rest.slice(0, nextHeader);
+        for (const line of body.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const depMatch = trimmed.match(/^([a-zA-Z_][\w-]*)\s*=/);
+            if (depMatch) {
+                const name = depMatch[1];
+                (isDev ? devDeps : deps).push(name);
+                depTargets[name] = spec;
+                if (name in frameworkMap)
+                    frameworkSet.add(frameworkMap[name]);
+            }
+        }
+    }
+}
 /** Detect Python framework from package name */
 function detectPythonFramework(name, fwSet) {
     const pythonFrameworks = {

package/dist/scheduler/core.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Scheduler core — the cadence engine (S1).
+ *
+ * A minimal, dependency-free job scheduler: register named jobs with an interval, tick them
+ * manually (tests, one-shots) or let start()/stop() drive them on timers. The one hard rule:
+ * the SAME job never overlaps itself — a tick that arrives while the job's fn is still
+ * running resolves as a no-op instead of double-running the pull.
+ */
+type JobFn = () => Promise<void>;
+export interface SchedulerJobView {
+    name: string;
+    intervalMs: number;
+    lastRun: number | null;
+}
+export interface Scheduler {
+    register(name: string, intervalMs: number, fn: JobFn): void;
+    start(): void;
+    stop(): void;
+    tick(name: string): Promise<void>;
+    jobs(): SchedulerJobView[];
+    jobCount(): number;
+}
+export declare function createScheduler(): Scheduler;
+export {};
+//# sourceMappingURL=core.d.ts.map

package/dist/scheduler/core.js

@@ -0,0 +1,61 @@
+/**
+ * Scheduler core — the cadence engine (S1).
+ *
+ * A minimal, dependency-free job scheduler: register named jobs with an interval, tick them
+ * manually (tests, one-shots) or let start()/stop() drive them on timers. The one hard rule:
+ * the SAME job never overlaps itself — a tick that arrives while the job's fn is still
+ * running resolves as a no-op instead of double-running the pull.
+ */
+export function createScheduler() {
+    const jobs = new Map();
+    async function tick(name) {
+        const job = jobs.get(name);
+        if (!job) {
+            throw new Error(`scheduler: no job registered under "${name}"`);
+        }
+        if (job.running) {
+            return; // the same job never overlaps — a concurrent tick is a no-op
+        }
+        job.running = true;
+        try {
+            await job.fn();
+            job.lastRun = Date.now();
+        }
+        finally {
+            job.running = false;
+        }
+    }
+    return {
+        register(name, intervalMs, fn) {
+            jobs.set(name, { name, intervalMs, fn, lastRun: null, running: false, timer: null });
+        },
+        start() {
+            for (const job of jobs.values()) {
+                if (job.timer)
+                    continue;
+                job.timer = setInterval(() => {
+                    void tick(job.name).catch(() => {
+                        // a failing scheduled run must never take the process down; the job's
+                        // freshness simply doesn't advance, which is the observable signal
+                    });
+                }, job.intervalMs);
+            }
+        },
+        stop() {
+            for (const job of jobs.values()) {
+                if (job.timer) {
+                    clearInterval(job.timer);
+                    job.timer = null;
+                }
+            }
+        },
+        tick,
+        jobs() {
+            return [...jobs.values()].map(({ name, intervalMs, lastRun }) => ({ name, intervalMs, lastRun }));
+        },
+        jobCount() {
+            return jobs.size;
+        },
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/scheduler/freshness.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Freshness watermarks (S2) — when was each named feed last refreshed, and is it stale?
+ *
+ * A tiny persistent map: mark a name fresh at a moment, ask how stale it is against a budget.
+ * Persistence is an explicit save()/load() to a JSON file so the scheduler can survive a
+ * restart without inventing freshness it does not have — a missing file simply means
+ * "nothing is known", which reads as stale (the honest default).
+ */
+export interface Freshness {
+    markFresh(name: string, at?: number): void;
+    lastFresh(name: string): number | null;
+    isStale(name: string, maxAgeMs: number, now?: number): boolean;
+    save(): void;
+    load(): void;
+}
+export declare function createFreshness(filePath?: string): Freshness;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/scheduler/freshness.js

@@ -0,0 +1,41 @@
+/**
+ * Freshness watermarks (S2) — when was each named feed last refreshed, and is it stale?
+ *
+ * A tiny persistent map: mark a name fresh at a moment, ask how stale it is against a budget.
+ * Persistence is an explicit save()/load() to a JSON file so the scheduler can survive a
+ * restart without inventing freshness it does not have — a missing file simply means
+ * "nothing is known", which reads as stale (the honest default).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export function createFreshness(filePath) {
+    let marks = new Map();
+    return {
+        markFresh(name, at) {
+            marks.set(name, at ?? Date.now());
+        },
+        lastFresh(name) {
+            return marks.get(name) ?? null;
+        },
+        isStale(name, maxAgeMs, now) {
+            const last = marks.get(name);
+            if (last === undefined) {
+                return true; // never refreshed is the stalest state there is
+            }
+            return (now ?? Date.now()) - last > maxAgeMs;
+        },
+        save() {
+            if (!filePath)
+                return;
+            mkdirSync(dirname(filePath), { recursive: true });
+            writeFileSync(filePath, JSON.stringify(Object.fromEntries(marks)), "utf8");
+        },
+        load() {
+            if (!filePath || !existsSync(filePath))
+                return;
+            const raw = JSON.parse(readFileSync(filePath, "utf8"));
+            marks = new Map(Object.entries(raw));
+        },
+    };
+}
+//# sourceMappingURL=freshness.js.map