@deftai/directive-core 0.55.0

package/dist/cache/main.js

@@ -0,0 +1,319 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ALLOWED_SOURCES, DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS, DEFAULT_PRUNE_OLDER_THAN_DAYS, } from "./constants.js";
+import { CacheCapBreachedError, CacheError, CacheFetchError, CacheNotFoundError, CacheValidationError, } from "./errors.js";
+import { cacheFetchAll, cacheRefreshClosed } from "./fetch.js";
+import { pythonBool, pythonJsonPretty } from "./json.js";
+import { cacheGet, cacheInvalidate, cachePrune, cachePruneToCap, cachePut } from "./operations.js";
+import { resolveCaps } from "./quota.js";
+function normaliseLabelFilter(raw) {
+    if (!raw || raw.length === 0)
+        return [];
+    return raw.flatMap((value) => value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0));
+}
+function usage() {
+    process.stderr.write("usage: cache [-h] {put,get,invalidate,fetch-all,prune} ...\n");
+}
+function cmdPut(args) {
+    let source = "";
+    let key = "";
+    let rawFile;
+    let ttlSeconds;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--raw-file") {
+            rawFile = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--ttl-seconds") {
+            ttlSeconds = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (!source) {
+            source = arg ?? "";
+        }
+        else if (!key) {
+            key = arg ?? "";
+        }
+        else {
+            throw new CacheError(`unexpected argument: ${arg}`);
+        }
+    }
+    if (!source || !key || !rawFile) {
+        process.stderr.write("usage: cache put [-h] --raw-file RAW_FILE [--ttl-seconds TTL_SECONDS] {github-issue} key\n");
+        process.stderr.write("cache put: error: the following arguments are required: source, key, --raw-file\n");
+        return 2;
+    }
+    if (!ALLOWED_SOURCES.includes(source)) {
+        process.stderr.write(`cache put: error: invalid source '${source}'\n`);
+        return 2;
+    }
+    const rawPath = resolve(rawFile);
+    if (!existsSync(rawPath)) {
+        throw new CacheError(`--raw-file not found: ${rawPath}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(rawPath, "utf8"));
+    }
+    catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        throw new CacheError(`--raw-file is not valid JSON: ${msg}`);
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CacheError(`--raw-file must be a JSON object (got ${Array.isArray(raw) ? "array" : typeof raw})`);
+    }
+    const result = cachePut(source, key, raw, { ttlSeconds });
+    const flagCats = result.scanResult.flags.map((f) => `'${f.category}'`).join(", ");
+    process.stdout.write(`cache:put source=${result.source} key=${result.key} scan_passed=${pythonBool(result.scanResult.passed)} flags=[${flagCats}] content_written=${pythonBool(result.contentWritten)} dir=${result.entryDir}\n`);
+    return result.scanResult.passed ? 0 : 2;
+}
+function cmdGet(args) {
+    let source = "";
+    let key = "";
+    let allowStale = true;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--allow-stale") {
+            allowStale = true;
+        }
+        else if (arg === "--no-stale") {
+            allowStale = false;
+        }
+        else if (!source) {
+            source = arg ?? "";
+        }
+        else if (!key) {
+            key = arg ?? "";
+        }
+    }
+    if (!source || !key) {
+        process.stderr.write("usage: cache get [-h] {github-issue} key [--allow-stale | --no-stale]\n");
+        return 2;
+    }
+    try {
+        const result = cacheGet(source, key, { allowStale });
+        const payload = {
+            source: result.source,
+            key: result.key,
+            entry_dir: result.entryDir,
+            content_path: result.contentPath,
+            stale: result.stale,
+            meta: result.meta,
+        };
+        process.stdout.write(`${pythonJsonPretty(payload)}\n`);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CacheNotFoundError) {
+            process.stderr.write(`cache:get miss: ${JSON.stringify(err.message)}\n`);
+            return 1;
+        }
+        throw err;
+    }
+}
+function cmdInvalidate(args) {
+    let source = "";
+    let key = "";
+    let reason;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--reason") {
+            reason = args[i + 1];
+            i += 1;
+        }
+        else if (!source) {
+            source = arg ?? "";
+        }
+        else if (!key) {
+            key = arg ?? "";
+        }
+    }
+    if (!source || !key) {
+        process.stderr.write("usage: cache invalidate [-h] {github-issue} key [--reason TEXT]\n");
+        return 2;
+    }
+    const existed = cacheInvalidate(source, key, { reason });
+    process.stdout.write(`cache:invalidate source=${source} key=${key} existed=${pythonBool(existed)}\n`);
+    return 0;
+}
+function cmdFetchAll(args) {
+    let source = "";
+    let repo = "";
+    let batchSize = DEFAULT_BATCH_SIZE;
+    let delayMs = DEFAULT_DELAY_MS;
+    let ttlSeconds;
+    let state = "open";
+    let limit = 1000;
+    const labels = [];
+    let author;
+    let refreshClosed = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--source") {
+            source = args[i + 1] ?? "";
+            i += 1;
+        }
+        else if (arg === "--repo") {
+            repo = args[i + 1] ?? "";
+            i += 1;
+        }
+        else if (arg === "--batch-size") {
+            batchSize = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--delay-ms") {
+            delayMs = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--ttl-seconds") {
+            ttlSeconds = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--state") {
+            state = args[i + 1] ?? "open";
+            i += 1;
+        }
+        else if (arg === "--limit") {
+            limit = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--label") {
+            labels.push(args[i + 1] ?? "");
+            i += 1;
+        }
+        else if (arg === "--author") {
+            author = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--refresh-closed") {
+            refreshClosed = true;
+        }
+    }
+    if (!source || !repo) {
+        process.stderr.write("usage: cache fetch-all --source SOURCE --repo OWNER/NAME [options]\n");
+        return 2;
+    }
+    const report = cacheFetchAll({
+        source,
+        repo,
+        batchSize,
+        delayMs,
+        ttlSeconds,
+        state,
+        limit,
+        labels: normaliseLabelFilter(labels),
+        author: author ?? null,
+    });
+    process.stdout.write(`${report.toJson()}\n`);
+    let rc = report.issuesFailed === 0 ? 0 : 1;
+    if (refreshClosed) {
+        const refresh = cacheRefreshClosed({
+            source,
+            repo,
+            ttlSeconds,
+            delayMs,
+            limit,
+        });
+        process.stdout.write(`${refresh.toJson()}\n`);
+        if (refresh.refreshFailed)
+            rc = 1;
+    }
+    return rc;
+}
+function cmdPrune(args) {
+    let olderThanDays = DEFAULT_PRUNE_OLDER_THAN_DAYS;
+    let source;
+    let dryRun = false;
+    let toCap = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--older-than-days") {
+            olderThanDays = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--source") {
+            source = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--to-cap") {
+            toCap = true;
+        }
+    }
+    if (toCap) {
+        const evicted = cachePruneToCap({ dryRun });
+        const caps = resolveCaps();
+        const payload = {
+            mode: "to-cap",
+            max_bytes: caps.maxBytes,
+            max_entries: caps.maxEntries,
+            dry_run: dryRun,
+            evicted_count: evicted.length,
+            evicted_keys: evicted.map((e) => `${e.source}/${e.key}`),
+            freed_bytes: evicted.reduce((sum, e) => sum + e.sizeBytes, 0),
+        };
+        process.stdout.write(`${pythonJsonPretty(payload)}\n`);
+        return 0;
+    }
+    const removed = cachePrune({ olderThanDays, source, dryRun });
+    const payload = {
+        older_than_days: olderThanDays,
+        source: source ?? "all",
+        dry_run: dryRun,
+        removed_count: removed.length,
+        removed_paths: removed,
+    };
+    process.stdout.write(`${pythonJsonPretty(payload)}\n`);
+    return 0;
+}
+/** CLI entry point (mirrors `scripts/cache.py::main`). */
+export function main(argv) {
+    if (argv.length === 0) {
+        usage();
+        process.stderr.write("cache: error: the following arguments are required: cmd\n");
+        return 2;
+    }
+    const cmd = argv[0];
+    const rest = argv.slice(1);
+    try {
+        switch (cmd) {
+            case "put":
+                return cmdPut(rest);
+            case "get":
+                return cmdGet(rest);
+            case "invalidate":
+                return cmdInvalidate(rest);
+            case "fetch-all":
+                return cmdFetchAll(rest);
+            case "prune":
+                return cmdPrune(rest);
+            default:
+                usage();
+                process.stderr.write(`cache: error: argument cmd: invalid choice: '${cmd}'\n`);
+                return 2;
+        }
+    }
+    catch (err) {
+        if (err instanceof CacheCapBreachedError) {
+            process.stderr.write(`cache: cap breached: ${err.message}\n`);
+            return 3;
+        }
+        if (err instanceof CacheError || err instanceof CacheFetchError) {
+            process.stderr.write(`cache: error: ${err.message}\n`);
+            return 1;
+        }
+        if (err instanceof CacheValidationError) {
+            process.stderr.write(`cache: schema error: ${err.message}\n`);
+            return 2;
+        }
+        /* v8 ignore next -- unexpected internal errors propagate */
+        throw err;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/cache/operations.d.ts

@@ -0,0 +1,34 @@
+import { type CacheCaps, type EntryUsage } from "./quota.js";
+import { SCANNER_VERSION } from "./scanner.js";
+import { type Clock } from "./time.js";
+import type { CacheGetOptions, CachePutOptions, GetResult, PutResult } from "./types.js";
+/** Write a cache entry (mirrors `cache.cache_put`). */
+export declare function cachePut(source: string, key: string, raw: Record<string, unknown>, options?: CachePutOptions): PutResult;
+/** Read a cache entry (mirrors `cache.cache_get`). */
+export declare function cacheGet(source: string, key: string, options?: CacheGetOptions): GetResult;
+/** Delete entry + audit (mirrors `cache.cache_invalidate`). */
+export declare function cacheInvalidate(source: string, key: string, options?: {
+    reason?: string | null;
+    cacheRoot?: string;
+    clock?: Clock;
+}): boolean;
+/** Remove entries past TTL threshold (mirrors `cache.cache_prune`). */
+export declare function cachePrune(options?: {
+    olderThanDays?: number;
+    source?: string | null;
+    dryRun?: boolean;
+    cacheRoot?: string;
+    clock?: Clock;
+}): string[];
+/** LRU-evict until under caps (mirrors `cache.cache_prune_to_cap`). */
+export declare function cachePruneToCap(options?: {
+    cacheRoot?: string;
+    caps?: CacheCaps | null;
+    dryRun?: boolean;
+    clock?: Clock;
+}): EntryUsage[];
+export declare function isFresh(metaPath: string, clock?: Clock): boolean;
+/** Validate repo slug for fetch-all. */
+export declare function validateRepo(repo: string): void;
+export { SCANNER_VERSION };
+//# sourceMappingURL=operations.d.ts.map

package/dist/cache/operations.js

@@ -0,0 +1,348 @@
+import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { ALLOWED_SOURCES, REPO_RE, SOURCE_TTL_SECONDS } from "./constants.js";
+import { CacheCapBreachedError, CacheError, CacheNotFoundError, CacheValidationError, } from "./errors.js";
+import { appendAudit, atomicWriteText, fileSize, removeEntryDir, touchMtime } from "./io.js";
+import { pythonJsonDump } from "./json.js";
+import { entryDir, validateKey } from "./paths.js";
+import { enforceCaps, predictEvictionSet, resolveCaps, } from "./quota.js";
+import { flagsForMeta, SCANNER_VERSION, scan } from "./scanner.js";
+import { addSeconds, parseIso, systemClock, utcIso } from "./time.js";
+import { validateMeta } from "./validate.js";
+function renderContent(source, raw) {
+    if (source === "github-issue") {
+        const number = raw.number;
+        const title = raw.title ?? "";
+        const body = raw.body ?? "";
+        if (typeof number !== "number") {
+            throw new CacheError(`invalid github-issue raw payload: 'number' must be int (got ${typeof number})`);
+        }
+        return `# #${number}: ${title}\n\n${body}`;
+    }
+    throw new CacheError(`unknown source '${source}': v1 supports ${JSON.stringify([...ALLOWED_SOURCES].sort())}`);
+}
+function buildMeta(options) {
+    return {
+        source: options.source,
+        key: options.key,
+        fetched_at: utcIso(options.clock, options.fetchedAt),
+        ttl_seconds: options.ttlSeconds,
+        expires_at: utcIso(options.clock, options.expiresAt),
+        scan_result: {
+            passed: options.scanResult.passed,
+            scanned_at: options.scanResult.scanned_at,
+            scanner_version: options.scanResult.scanner_version,
+            flags: flagsForMeta(options.scanResult.flags),
+        },
+        size_bytes: options.sizeBytes,
+        stale: false,
+    };
+}
+function existingEntrySize(edir) {
+    const metaPath = join(edir, "meta.json");
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+        const size = meta.size_bytes;
+        if (typeof size === "number" && size >= 0)
+            return size;
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function makeEvictAuditCallback(cacheRoot, trigger, clock) {
+    return (victim, reason) => {
+        const lastAccessedIso = victim.lastAccessed > 0 ? utcIso(clock, new Date(victim.lastAccessed * 1000)) : "unknown";
+        appendAudit({
+            event: "cache:evict",
+            source: victim.source,
+            key: victim.key,
+            timestamp: utcIso(clock),
+            reason,
+            trigger,
+            freed_bytes: victim.sizeBytes,
+            last_accessed_at: lastAccessedIso,
+        }, cacheRoot);
+    };
+}
+/** Write a cache entry (mirrors `cache.cache_put`). */
+export function cachePut(source, key, raw, options = {}) {
+    const clock = options.clock ?? systemClock;
+    validateKey(source, key);
+    const fetched = options.fetchedAt ?? clock.now();
+    const ttl = options.ttlSeconds !== undefined && options.ttlSeconds !== null
+        ? options.ttlSeconds
+        : SOURCE_TTL_SECONDS[source];
+    if (typeof ttl !== "number" || ttl < 0 || !Number.isInteger(ttl)) {
+        throw new CacheError(`ttl_seconds must be a non-negative int (got ${JSON.stringify(ttl)})`);
+    }
+    const expires = addSeconds(fetched, ttl);
+    const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    const edir = entryDir(source, key, cacheRoot);
+    const rawText = pythonJsonDump(raw);
+    const rawSize = Buffer.byteLength(rawText, "utf8");
+    const existingSize = existingEntrySize(edir);
+    const isNewEntry = existingSize === null;
+    const incomingDelta = isNewEntry ? rawSize : rawSize - existingSize;
+    const incomingEntries = isNewEntry ? 1 : 0;
+    const enforceResult = enforceCaps(cacheRoot, {
+        caps: options.caps ?? null,
+        incomingBytes: incomingDelta,
+        incomingEntries,
+        protectKeys: [[source, key]],
+        onEvict: (victim, reason) => {
+            makeEvictAuditCallback(cacheRoot, "cache:put", clock)(victim, reason);
+        },
+    });
+    if (enforceResult.wouldBreach) {
+        const resolved = options.caps ?? resolveCaps();
+        const reasonParts = [];
+        if (resolved.maxBytes > 0 &&
+            enforceResult.finalUsage.totalBytes + incomingDelta > resolved.maxBytes) {
+            reasonParts.push("size_cap");
+        }
+        if (resolved.maxEntries > 0 &&
+            enforceResult.finalUsage.totalEntries + incomingEntries > resolved.maxEntries) {
+            reasonParts.push("entry_cap");
+        }
+        throw new CacheCapBreachedError({
+            reason: reasonParts.join("+") || "unknown",
+            maxBytes: resolved.maxBytes,
+            maxEntries: resolved.maxEntries,
+            currentBytes: enforceResult.finalUsage.totalBytes,
+            currentEntries: enforceResult.finalUsage.totalEntries,
+            incomingBytes: incomingDelta,
+        });
+    }
+    atomicWriteText(join(edir, "raw.json"), rawText);
+    const authoritativeSize = fileSize(join(edir, "raw.json"));
+    const rendered = renderContent(source, raw);
+    const scanResult = scan(rendered, utcIso(clock, fetched));
+    const contentPath = join(edir, "content.md");
+    let contentWritten = false;
+    if (scanResult.passed) {
+        atomicWriteText(contentPath, scanResult.transformed_content);
+        contentWritten = true;
+    }
+    else if (existsSync(contentPath)) {
+        try {
+            unlinkSync(contentPath);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const meta = buildMeta({
+        source,
+        key,
+        fetchedAt: fetched,
+        ttlSeconds: ttl,
+        expiresAt: expires,
+        scanResult,
+        sizeBytes: authoritativeSize,
+        clock,
+    });
+    validateMeta(meta);
+    atomicWriteText(join(edir, "meta.json"), pythonJsonDump(meta));
+    appendAudit({
+        event: "cache:put",
+        source,
+        key,
+        timestamp: utcIso(clock),
+        scan_passed: scanResult.passed,
+        scanner_version: scanResult.scanner_version,
+        flags: scanResult.flags.map((f) => ({
+            category: f.category,
+            severity: f.severity,
+            detail: f.detail,
+            match_count: f.match_count,
+        })),
+        content_written: contentWritten,
+    }, cacheRoot);
+    return {
+        source,
+        key,
+        entryDir: edir,
+        meta,
+        scanResult: {
+            passed: scanResult.passed,
+            scanner_version: scanResult.scanner_version,
+            flags: scanResult.flags,
+            transformed_content: scanResult.transformed_content,
+            scanned_at: scanResult.scanned_at,
+        },
+        contentWritten,
+    };
+}
+/** Read a cache entry (mirrors `cache.cache_get`). */
+export function cacheGet(source, key, options = {}) {
+    const clock = options.clock ?? systemClock;
+    const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    const allowStale = options.allowStale ?? true;
+    const edir = entryDir(source, key, cacheRoot);
+    const metaPath = join(edir, "meta.json");
+    if (!existsSync(metaPath)) {
+        throw new CacheNotFoundError(`cache miss for source='${source}' key='${key}' (expected meta.json at ${metaPath})`);
+    }
+    let meta;
+    try {
+        meta = JSON.parse(readFileSync(metaPath, "utf8"));
+    }
+    catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        throw new CacheValidationError(`meta.json at ${metaPath} is not valid JSON: ${msg}`);
+    }
+    validateMeta(meta);
+    const expires = parseIso(String(meta.expires_at));
+    const isStale = clock.now() > expires;
+    if (isStale && !allowStale) {
+        throw new CacheNotFoundError(`cache entry stale for source='${source}' key='${key}'; expires_at=${meta.expires_at} (pass --allow-stale to override)`);
+    }
+    meta.stale = isStale;
+    touchMtime(metaPath);
+    const contentPath = join(edir, "content.md");
+    return {
+        source,
+        key,
+        entryDir: edir,
+        meta,
+        contentPath: existsSync(contentPath) ? contentPath : null,
+        stale: isStale,
+    };
+}
+/** Delete entry + audit (mirrors `cache.cache_invalidate`). */
+export function cacheInvalidate(source, key, options = {}) {
+    const clock = options.clock ?? systemClock;
+    validateKey(source, key);
+    const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    const edir = entryDir(source, key, cacheRoot);
+    const existed = existsSync(edir);
+    if (existed)
+        removeEntryDir(edir);
+    appendAudit({
+        event: "cache:invalidate",
+        source,
+        key,
+        timestamp: utcIso(clock),
+        reason: options.reason ?? "",
+        existed,
+    }, cacheRoot);
+    return existed;
+}
+function metaKeyOrRelpath(metaPath, srcRoot) {
+    const parent = join(metaPath, "..");
+    if (parent.startsWith(srcRoot)) {
+        return parent
+            .slice(srcRoot.length + 1)
+            .split(/[/\\]/)
+            .join("/");
+    }
+    return parent;
+}
+/** Remove entries past TTL threshold (mirrors `cache.cache_prune`). */
+export function cachePrune(options = {}) {
+    const clock = options.clock ?? systemClock;
+    const olderThanDays = options.olderThanDays ?? 30;
+    if (olderThanDays < 0) {
+        throw new CacheError(`--older-than-days must be >= 0 (got ${JSON.stringify(olderThanDays)})`);
+    }
+    const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    if (!existsSync(cacheRoot))
+        return [];
+    const cutoff = addSeconds(clock.now(), -olderThanDays * 24 * 60 * 60);
+    const removed = [];
+    const sources = options.source ? [options.source] : [...ALLOWED_SOURCES];
+    for (const src of sources) {
+        const srcRoot = join(cacheRoot, src);
+        if (!existsSync(srcRoot))
+            continue;
+        const metaPaths = collectMetaPathsUnder(srcRoot);
+        for (const metaPath of metaPaths) {
+            const edir = join(metaPath, "..");
+            let expires;
+            let meta = {};
+            try {
+                meta = JSON.parse(readFileSync(metaPath, "utf8"));
+                expires = parseIso(String(meta.expires_at));
+            }
+            catch {
+                expires = addSeconds(cutoff, -86400);
+                meta = {};
+            }
+            if (expires >= cutoff)
+                continue;
+            if (!options.dryRun) {
+                removeEntryDir(edir);
+                appendAudit({
+                    event: "cache:prune-entry",
+                    source: src,
+                    key: metaKeyOrRelpath(metaPath, srcRoot),
+                    timestamp: utcIso(clock),
+                    expires_at: typeof meta === "object" && meta !== null && "expires_at" in meta
+                        ? meta.expires_at
+                        : "unknown",
+                }, cacheRoot);
+            }
+            removed.push(edir);
+        }
+    }
+    return removed;
+}
+function collectMetaPathsUnder(srcRoot) {
+    const found = [];
+    function walk(dir) {
+        if (!existsSync(dir))
+            return;
+        for (const name of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, name.name);
+            if (name.isDirectory())
+                walk(full);
+            else if (name.name === "meta.json")
+                found.push(full);
+        }
+    }
+    walk(srcRoot);
+    return found;
+}
+/** LRU-evict until under caps (mirrors `cache.cache_prune_to_cap`). */
+export function cachePruneToCap(options = {}) {
+    const clock = options.clock ?? systemClock;
+    const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    const resolved = options.caps ?? resolveCaps();
+    if (!resolved.maxBytes && !resolved.maxEntries)
+        return [];
+    if (options.dryRun) {
+        return predictEvictionSet(cacheRoot, resolved);
+    }
+    const enforceResult = enforceCaps(cacheRoot, {
+        caps: resolved,
+        onEvict: (victim, reason) => {
+            makeEvictAuditCallback(cacheRoot, "cache:prune-to-cap", clock)(victim, reason);
+        },
+    });
+    return enforceResult.evicted;
+}
+export function isFresh(metaPath, clock = systemClock) {
+    if (!existsSync(metaPath))
+        return false;
+    try {
+        const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+        validateMeta(meta);
+        const expires = parseIso(String(meta.expires_at));
+        return clock.now() <= expires;
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate repo slug for fetch-all. */
+export function validateRepo(repo) {
+    if (!REPO_RE.test(repo)) {
+        throw new CacheError(`invalid --repo '${repo}': expected 'owner/repo' (alphanumerics, '.', '_', '-' only)`);
+    }
+}
+export { SCANNER_VERSION };
+//# sourceMappingURL=operations.js.map