akm-cli/dist/sources/freshness.js

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
/**
 * Shared freshness-window skeleton for mirror caches (git repos, website
 * snapshots). A marker file's mtime records the last successful refresh:
 * within `ttlMs` the cached copy is served without refreshing; on refresh
 * failure the cached copy is still served while the marker is younger than
 * `staleMs`, so search stays available through upstream outages.
 */
import fs from "node:fs";
import { isExpired } from "./providers/provider-utils.js";
/**
 * Run the fresh → refresh → stale-fallback ladder around `refresh()`.
 * Resolves when the cached copy is usable (fresh, refreshed, or stale-but-
 * within-window); rethrows the refresh error otherwise.
 */
export async function withFreshnessCache(options) {
    const usable = options.isUsable ?? (() => true);
    let mtime = 0;
    try {
        mtime = fs.statSync(options.markerPath).mtimeMs;
    }
    catch {
        /* no marker — never successfully refreshed */
    }
    if (!options.force && mtime && !isExpired(mtime, options.ttlMs) && usable()) {
        return;
    }
    try {
        await options.refresh();
    }
    catch (err) {
        if (options.allowStaleOnRefreshFailure !== false && mtime && !isExpired(mtime, options.staleMs) && usable()) {
            return;
        }
        throw err;
    }
}