bdy 1.24.8 → 1.25.0-dev

package/distTs/src/command/yaml/schemaUtils.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureYamlSchema = ensureYamlSchema;
+exports.loadRawSchema = loadRawSchema;
+exports.getDefValidator = getDefValidator;
+exports.validateAgainstDef = validateAgainstDef;
+exports.validateAgainstSchema = validateAgainstSchema;
+exports.getAllDefs = getAllDefs;
+exports.getSharedDefs = getSharedDefs;
+exports.resolveRefs = resolveRefs;
+const utils_1 = require("../../utils");
+const input_1 = __importDefault(require("../../input"));
+const diskCache_1 = require("../../diskCache");
+const texts_1 = require("../../texts");
+function schemaUrl() {
+    const env = (0, utils_1.getApiEnv)(input_1.default.restApiTokenClient(true).baseUrl);
+    return `https://es.buddy.works/yaml-schema/${env}/yaml-schema.json`;
+}
+async function ensureYamlSchema() {
+    const url = schemaUrl();
+    const paths = (0, diskCache_1.cachePaths)('yaml-schema', url);
+    if ((0, diskCache_1.isHardFresh)((0, diskCache_1.readMeta)(paths.meta)))
+        return;
+    if ((await (0, diskCache_1.refresh)(url, paths)) === 'none') {
+        throw new Error((0, texts_1.ERR_YAML_SCHEMA_FETCH_FAILED)(url));
+    }
+}
+function readCachedSchema() {
+    const path = (0, diskCache_1.cachePaths)('yaml-schema', schemaUrl()).raw;
+    const raw = (0, diskCache_1.readCached)(path);
+    if (!raw)
+        throw new Error((0, texts_1.ERR_YAML_SCHEMA_READ_FAILED)(path));
+    return JSON.parse(raw);
+}
+let cachedRaw = null;
+let ajvInstance = null;
+const validatorCache = new Map();
+function loadRawSchema() {
+    if (cachedRaw)
+        return cachedRaw;
+    cachedRaw = readCachedSchema();
+    return cachedRaw;
+}
+// Read off the schema, not listed: AJV strict mode rejects any x- keyword it was
+// not told about, and the backend keeps adding them.
+function vendorKeywords(schema) {
+    const found = new Set();
+    const walk = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            node.forEach(walk);
+            return;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key.startsWith('x-'))
+                found.add(key);
+            walk(value);
+        }
+    };
+    walk(schema);
+    return [...found];
+}
+function getAjv() {
+    if (ajvInstance)
+        return ajvInstance;
+    const Ajv = require('ajv/dist/2020').default;
+    const addFormats = require('ajv-formats').default;
+    const schema = loadRawSchema();
+    const ajv = new Ajv({ allErrors: true, coerceTypes: true });
+    addFormats(ajv);
+    for (const kw of vendorKeywords(schema))
+        ajv.addKeyword(kw);
+    ajv.addKeyword('discriminator');
+    ajv.addSchema(schema);
+    ajvInstance = ajv;
+    return ajv;
+}
+function getDefValidator(defName) {
+    if (validatorCache.has(defName))
+        return validatorCache.get(defName);
+    const ajv = getAjv();
+    const raw = loadRawSchema();
+    const validate = ajv.compile({ $ref: `${raw.$id}#/$defs/${defName}` });
+    validatorCache.set(defName, validate);
+    return validate;
+}
+function formatErrors(errors) {
+    if (!errors)
+        return [];
+    return errors.map((err) => {
+        let errPath = err.instancePath.replace(/^\//, '').replace(/\//g, '.');
+        if (err.keyword === 'required' && err.params?.missingProperty) {
+            errPath = errPath ? `${errPath}.${err.params.missingProperty}` : err.params.missingProperty;
+        }
+        return { path: errPath, message: err.message || 'unknown error' };
+    });
+}
+function validateAgainstDef(defName, data) {
+    const validate = getDefValidator(defName);
+    const valid = validate(data);
+    return { valid: !!valid, errors: formatErrors(validate.errors) };
+}
+function validateAgainstSchema(schema, data) {
+    const ajv = getAjv();
+    const validate = ajv.compile(schema);
+    const valid = validate(data);
+    return { valid: !!valid, errors: formatErrors(validate.errors) };
+}
+function getAllDefs() {
+    const raw = loadRawSchema();
+    return raw.$defs || {};
+}
+function getSharedDefs() {
+    const defs = getAllDefs();
+    const shared = {};
+    for (const [k, v] of Object.entries(defs)) {
+        if (!k.endsWith('ActionYaml')) {
+            shared[k] = v;
+        }
+    }
+    return shared;
+}
+function resolveRefs(properties, sharedDefs, depth = 0) {
+    if (depth > 5)
+        return properties;
+    const resolved = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        if (prop.$ref) {
+            const refName = prop.$ref.replace('#/$defs/', '');
+            const refDef = sharedDefs[refName];
+            if (refDef) {
+                resolved[key] = { ...refDef, description: prop.description || refDef.description };
+                if (refDef.properties) {
+                    resolved[key].properties = resolveRefs(refDef.properties, sharedDefs, depth + 1);
+                }
+            }
+            else {
+                resolved[key] = prop;
+            }
+        }
+        else if (prop.type === 'array' && prop.items?.$ref) {
+            const refName = prop.items.$ref.replace('#/$defs/', '');
+            const refDef = sharedDefs[refName];
+            if (refDef) {
+                const resolvedItems = { ...refDef };
+                if (refDef.properties) {
+                    resolvedItems.properties = resolveRefs(refDef.properties, sharedDefs, depth + 1);
+                }
+                resolved[key] = { ...prop, items: resolvedItems };
+            }
+            else {
+                resolved[key] = prop;
+            }
+        }
+        else {
+            resolved[key] = prop;
+        }
+    }
+    return resolved;
+}

package/distTs/src/command/yaml/validate.js

@@ -0,0 +1,300 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const path_1 = require("path");
+const utils_1 = require("../../utils");
+const output_1 = __importDefault(require("../../output"));
+const texts_1 = require("../../texts");
+const schemaUtils_1 = require("./schemaUtils");
+// Valid top-level keys the schema's PipelineYaml.properties omits (everything
+// else is derived from the schema, so this only covers genuine gaps).
+const SCHEMA_OMITTED_TOP_LEVEL_KEYS = ['git_config_ref'];
+const LABEL_KEYS = ['action', 'target', 'name', 'key', 'title', 'trigger_condition'];
+function stripRef(ref) {
+    return ref.replace('#/$defs/', '');
+}
+function prettifyKey(key) {
+    return key
+        .split('_')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+function outputErrors(result, indent) {
+    for (const err of result.errors) {
+        output_1.default.muted(`${indent}${err.path}: ${err.message}`);
+    }
+}
+function valueType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function reportWrongContainer(header, expected, value) {
+    output_1.default.error(header);
+    output_1.default.muted(`  ${(0, texts_1.ERR_YAML_MUST_BE)(expected, valueType(value))}`);
+    return 1;
+}
+// Array whose items reference a def — directly, or via a single $ref branch in
+// items.oneOf (how `targets` mixes a string ref with an object form).
+function itemRef(prop) {
+    if (!prop || prop.type !== 'array' || !prop.items)
+        return null;
+    if (prop.items.$ref)
+        return { defName: stripRef(prop.items.$ref), scalar: null };
+    if (Array.isArray(prop.items.oneOf)) {
+        const refs = prop.items.oneOf.filter((b) => b && b.$ref);
+        const scalars = prop.items.oneOf.filter((b) => b && !b.$ref);
+        if (refs.length === 1) {
+            return {
+                defName: stripRef(refs[0].$ref),
+                scalar: scalars.length === 1 ? scalars[0] : null,
+            };
+        }
+    }
+    return null;
+}
+function classifySections(props) {
+    const itemSections = [];
+    const objectSections = [];
+    const settingsProps = {};
+    for (const [key, prop] of Object.entries(props)) {
+        const ref = itemRef(prop);
+        if (ref) {
+            itemSections.push({ key, ...ref });
+        }
+        else if (prop && prop.$ref) {
+            objectSections.push({ key, defName: stripRef(prop.$ref), scalar: null });
+        }
+        else {
+            settingsProps[key] = prop;
+        }
+    }
+    return { itemSections, objectSections, settingsProps };
+}
+function discriminatorProp(def) {
+    return def && def.oneOf && def.discriminator ? def.discriminator.propertyName : null;
+}
+// Resolve a discriminated def to its concrete branch by the item's `type`, so
+// AJV always validates against a single def (never a oneOf). Plain defs pass through.
+function resolveDef(defs, refName, value) {
+    const def = defs[refName];
+    const prop = discriminatorProp(def);
+    if (!prop)
+        return { defName: refName };
+    const dv = value?.[prop];
+    if (dv === undefined || dv === null)
+        return { missingType: prop };
+    for (const branch of def.oneOf) {
+        const branchName = branch && branch.$ref ? stripRef(branch.$ref) : null;
+        if (!branchName)
+            continue;
+        if (defs[branchName]?.properties?.[prop]?.const === dv)
+            return { defName: branchName };
+    }
+    return { unknownType: String(dv), prop };
+}
+function itemLabel(value, index, discProp) {
+    let name;
+    for (const k of LABEL_KEYS) {
+        if (value && value[k]) {
+            name = String(value[k]);
+            break;
+        }
+    }
+    if (!name && !discProp && value && value.type)
+        name = String(value.type);
+    if (!name)
+        name = `#${index + 1}`;
+    return discProp && value && value[discProp] ? `${name} (${value[discProp]})` : name;
+}
+function validateScalarItem(item, section) {
+    // Null errors even where the section takes a string: coerceTypes cannot fix a root scalar.
+    if (item === null || !section.scalar) {
+        output_1.default.error(`  ${String(item)}: ${(0, texts_1.ERR_YAML_MUST_BE)('object', valueType(item))}`);
+        return 1;
+    }
+    const result = (0, schemaUtils_1.validateAgainstSchema)({ ...section.scalar, $defs: (0, schemaUtils_1.loadRawSchema)().$defs }, item);
+    if (result.valid) {
+        output_1.default.green(`  ${String(item)}`);
+        return 0;
+    }
+    output_1.default.error(`  ${String(item)}`);
+    outputErrors(result, '    ');
+    return result.errors.length;
+}
+function validateItemSection(defs, items, section) {
+    const refName = section.defName;
+    const discProp = discriminatorProp(defs[refName]);
+    let errors = 0;
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            errors += validateScalarItem(item, section);
+            continue;
+        }
+        const label = itemLabel(item, i, discProp);
+        const resolved = resolveDef(defs, refName, item);
+        if ('missingType' in resolved) {
+            output_1.default.error(`  ${label}: ${(0, texts_1.ERR_YAML_ITEM_MISSING)(resolved.missingType)}`);
+            errors++;
+            continue;
+        }
+        if ('unknownType' in resolved) {
+            output_1.default.error(`  ${label}: ${(0, texts_1.ERR_YAML_ITEM_UNKNOWN)(resolved.prop, resolved.unknownType)}`);
+            errors++;
+            continue;
+        }
+        const result = (0, schemaUtils_1.validateAgainstDef)(resolved.defName, item);
+        if (result.valid) {
+            output_1.default.green(`  ${label}`);
+        }
+        else {
+            errors += result.errors.length;
+            output_1.default.error(`  ${label}`);
+            outputErrors(result, '    ');
+        }
+    }
+    return errors;
+}
+function validateObjectSection(defs, label, value, refName) {
+    const resolved = resolveDef(defs, refName, value);
+    if ('missingType' in resolved) {
+        output_1.default.error(label);
+        output_1.default.muted(`  ${(0, texts_1.ERR_YAML_ITEM_MISSING)(resolved.missingType)}`);
+        return 1;
+    }
+    if ('unknownType' in resolved) {
+        output_1.default.error(label);
+        output_1.default.muted(`  ${(0, texts_1.ERR_YAML_ITEM_UNKNOWN)(resolved.prop, resolved.unknownType)}`);
+        return 1;
+    }
+    const result = (0, schemaUtils_1.validateAgainstDef)(resolved.defName, value);
+    if (result.valid) {
+        output_1.default.green(label);
+        return 0;
+    }
+    output_1.default.error(label);
+    outputErrors(result, '  ');
+    return result.errors.length;
+}
+function validateSinglePipeline(parsed, label) {
+    let errors = 0;
+    const defs = (0, schemaUtils_1.getAllDefs)();
+    const pipelineDef = defs['PipelineYaml'];
+    const props = pipelineDef?.properties || {};
+    const allKnownKeys = new Set([...Object.keys(props), ...SCHEMA_OMITTED_TOP_LEVEL_KEYS]);
+    const unknownKeys = Object.keys(parsed).filter((k) => !allKnownKeys.has(k));
+    if (unknownKeys.length > 0) {
+        output_1.default.yellow(`${label}${(0, texts_1.TXT_YAML_UNKNOWN_TOP_LEVEL_KEYS)(unknownKeys.join(', '))}`);
+    }
+    const { itemSections, objectSections, settingsProps } = classifySections(props);
+    if (Object.keys(settingsProps).length > 0) {
+        const settingsData = {};
+        for (const key of Object.keys(settingsProps)) {
+            if (key in parsed)
+                settingsData[key] = parsed[key];
+        }
+        const rawSchema = (0, schemaUtils_1.loadRawSchema)();
+        const result = (0, schemaUtils_1.validateAgainstSchema)({
+            type: 'object',
+            properties: settingsProps,
+            required: (pipelineDef?.required || []).filter((r) => r in settingsProps),
+            $defs: rawSchema.$defs,
+        }, settingsData);
+        if (result.valid) {
+            output_1.default.green(`${label}Pipeline settings`);
+        }
+        else {
+            errors += result.errors.length;
+            output_1.default.error(`${label}Pipeline settings`);
+            outputErrors(result, '  ');
+        }
+    }
+    const itemByKey = new Map(itemSections.map((s) => [s.key, s]));
+    const objByKey = new Map(objectSections.map((s) => [s.key, s.defName]));
+    for (const key of Object.keys(props)) {
+        if (!(key in parsed))
+            continue;
+        const value = parsed[key];
+        // A valueless section is an absent one: the backend drops the key on save.
+        if (value === null)
+            continue;
+        const header = `${label}${prettifyKey(key)}`;
+        if (itemByKey.has(key)) {
+            if (!Array.isArray(value)) {
+                errors += reportWrongContainer(header, 'array', value);
+                continue;
+            }
+            output_1.default.blue(header);
+            errors += validateItemSection(defs, value, itemByKey.get(key));
+        }
+        else if (objByKey.has(key)) {
+            if (typeof value !== 'object' || Array.isArray(value)) {
+                errors += reportWrongContainer(header, 'object', value);
+                continue;
+            }
+            errors += validateObjectSection(defs, header, value, objByKey.get(key));
+        }
+    }
+    return errors;
+}
+function validatePipelineFile(file) {
+    const filePath = (0, path_1.resolve)(file);
+    if (!(0, fs_1.existsSync)(filePath)) {
+        output_1.default.exitError((0, texts_1.ERR_YAML_VALIDATE_FILE_NOT_FOUND)(file));
+        return;
+    }
+    const YAML = require('yaml');
+    const content = (0, fs_1.readFileSync)(filePath, 'utf8');
+    let parsed;
+    try {
+        parsed = YAML.parse(content);
+    }
+    catch (e) {
+        output_1.default.exitError((0, texts_1.ERR_YAML_PARSE)(e.message));
+        return;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        output_1.default.exitError(texts_1.ERR_YAML_NOT_ARRAY);
+        return;
+    }
+    if (!Array.isArray(parsed)) {
+        output_1.default.exitError(texts_1.ERR_YAML_PLAIN_OBJECT);
+        return;
+    }
+    if (parsed.length === 0) {
+        output_1.default.exitError(texts_1.ERR_YAML_EMPTY_ARRAY);
+        return;
+    }
+    let errors = 0;
+    for (let i = 0; i < parsed.length; i++) {
+        const pipeline = parsed[i];
+        if (!pipeline || typeof pipeline !== 'object' || Array.isArray(pipeline)) {
+            output_1.default.error(`  ${(0, texts_1.ERR_YAML_PIPELINE_NOT_OBJECT)(i + 1)}`);
+            errors++;
+            continue;
+        }
+        const pipelineLabel = parsed.length > 1 ? `[${pipeline.pipeline || i + 1}] ` : '';
+        errors += validateSinglePipeline(pipeline, pipelineLabel);
+    }
+    output_1.default.normal('');
+    if (errors > 0) {
+        output_1.default.exitError((0, texts_1.ERR_YAML_VALIDATE_FAILED_COUNT)(errors));
+    }
+    else {
+        output_1.default.exitSuccess(texts_1.TXT_YAML_VALIDATE_ALL_PASS);
+    }
+}
+const commandYamlValidate = (0, utils_1.newCommand)('validate', texts_1.DESC_COMMAND_YAML_VALIDATE);
+commandYamlValidate.argument('<file>', texts_1.OPTION_YAML_VALIDATE_FILE);
+commandYamlValidate.addHelpText('after', `\nEXAMPLES:${texts_1.EXAMPLE_YAML_VALIDATE}`);
+commandYamlValidate.action(async (file) => {
+    await (0, schemaUtils_1.ensureYamlSchema)();
+    validatePipelineFile(file);
+});
+exports.default = commandYamlValidate;

package/distTs/src/command/yaml.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("../utils");
+const texts_1 = require("../texts");
+const pipeline_1 = __importDefault(require("./yaml/pipeline"));
+const actions_1 = __importDefault(require("./yaml/actions"));
+const validate_1 = __importDefault(require("./yaml/validate"));
+const commandYaml = (0, utils_1.newCommand)('yaml', texts_1.DESC_COMMAND_YAML);
+commandYaml.addCommand(pipeline_1.default);
+commandYaml.addCommand(actions_1.default);
+commandYaml.addCommand(validate_1.default);
+commandYaml.addHelpText('after', `
+EXAMPLES:${texts_1.EXAMPLE_YAML_PIPELINE}
+${texts_1.EXAMPLE_YAML_ACTIONS_LIST}
+${texts_1.EXAMPLE_YAML_ACTIONS_INFO}
+${texts_1.EXAMPLE_YAML_VALIDATE}`);
+exports.default = commandYaml;

package/distTs/src/diskCache.js

@@ -0,0 +1,200 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_TTL_MS = void 0;
+exports.cacheRoot = cacheRoot;
+exports.hashKey = hashKey;
+exports.cachePaths = cachePaths;
+exports.readMeta = readMeta;
+exports.isHardFresh = isHardFresh;
+exports.writeAtomic = writeAtomic;
+exports.writeCache = writeCache;
+exports.readCached = readCached;
+exports.sweepStaleCache = sweepStaleCache;
+exports.refresh = refresh;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const undici_1 = require("undici");
+const utils_1 = require("./utils");
+exports.CACHE_TTL_MS = 60 * 60 * 1000; // 1h
+function ensureDir(dir) {
+    if ((0, node_fs_1.existsSync)(dir))
+        return;
+    try {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        (0, utils_1.chownToHomeOwner)(dir);
+    }
+    catch {
+        // ignore
+    }
+}
+function cacheRoot() {
+    const dir = node_path_1.default.join((0, utils_1.getHomeDirectory)(), 'cache');
+    ensureDir(dir);
+    return dir;
+}
+function hashKey(input) {
+    return (0, node_crypto_1.createHash)('sha256').update(input).digest('hex').slice(0, 16);
+}
+function cachePaths(subdir, url) {
+    const dir = node_path_1.default.join(cacheRoot(), subdir);
+    ensureDir(dir);
+    const key = hashKey(url);
+    return {
+        raw: node_path_1.default.join(dir, `${key}.json`),
+        schema: node_path_1.default.join(dir, `${key}.v8`),
+        meta: node_path_1.default.join(dir, `${key}.meta.json`),
+    };
+}
+function readMeta(metaPath) {
+    // `?? ''`, not `?? '{}'`: JSON.parse(null) returns null instead of throwing.
+    try {
+        return JSON.parse(readCached(metaPath) ?? '');
+    }
+    catch {
+        return {};
+    }
+}
+function isHardFresh(meta, ttlMs = exports.CACHE_TTL_MS) {
+    return !!meta.fetchedAt && Date.now() - meta.fetchedAt < ttlMs;
+}
+function writeAtomic(filePath, data) {
+    const tmp = `${filePath}.${process.pid}.tmp`;
+    try {
+        (0, node_fs_1.writeFileSync)(tmp, data);
+        (0, node_fs_1.renameSync)(tmp, filePath);
+    }
+    catch (e) {
+        try {
+            (0, node_fs_1.unlinkSync)(tmp);
+        }
+        catch {
+            // ignore
+        }
+        throw e;
+    }
+}
+const memory = new Map();
+function writeCache(filePath, data) {
+    try {
+        writeAtomic(filePath, data);
+        memory.delete(filePath);
+        return true;
+    }
+    catch {
+        memory.set(filePath, data);
+        return false;
+    }
+}
+function readCached(filePath) {
+    const mem = memory.get(filePath);
+    if (mem !== undefined)
+        return mem;
+    try {
+        return (0, node_fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+const TMP_GRACE_MS = 60 * 60 * 1000; // 1h
+const BLOB_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30d
+function remove(p) {
+    try {
+        (0, node_fs_1.unlinkSync)(p);
+    }
+    catch {
+        // ignore
+    }
+}
+function sweepTmp(dir, now) {
+    for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.tmp'))
+            continue;
+        const p = node_path_1.default.join(dir, entry.name);
+        try {
+            // Not younger than the grace period: a concurrent bdy is writing its own <pid>.tmp now.
+            if (now - (0, node_fs_1.statSync)(p).mtimeMs > TMP_GRACE_MS)
+                remove(p);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+function sweepBlobs(dir, now) {
+    const keys = new Set();
+    for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+        if (entry.isFile() && !entry.name.endsWith('.tmp'))
+            keys.add(entry.name.split('.')[0]);
+    }
+    for (const key of keys) {
+        const meta = readMeta(node_path_1.default.join(dir, `${key}.meta.json`));
+        let age;
+        if (meta.fetchedAt) {
+            age = now - meta.fetchedAt;
+        }
+        else {
+            try {
+                age = now - (0, node_fs_1.statSync)(node_path_1.default.join(dir, `${key}.json`)).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (age <= BLOB_MAX_AGE_MS)
+            continue;
+        for (const ext of ['json', 'v8', 'meta.json'])
+            remove(node_path_1.default.join(dir, `${key}.${ext}`));
+    }
+}
+function sweepStaleCache() {
+    const root = cacheRoot();
+    const now = Date.now();
+    try {
+        sweepTmp(root, now);
+        for (const entry of (0, node_fs_1.readdirSync)(root, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const sub = node_path_1.default.join(root, entry.name);
+            sweepTmp(sub, now);
+            sweepBlobs(sub, now);
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+async function refresh(url, paths) {
+    const hasRaw = (0, node_fs_1.existsSync)(paths.raw);
+    const meta = hasRaw ? readMeta(paths.meta) : {};
+    // The server serves a strong content-based ETag, so revalidate with If-None-Match.
+    const headers = {};
+    if (hasRaw && meta.etag)
+        headers['if-none-match'] = meta.etag;
+    try {
+        const res = await (0, undici_1.request)(url, { headers });
+        const etag = res.headers['etag'];
+        if (res.statusCode === 304 && hasRaw) {
+            await res.body.dump();
+            writeCache(paths.meta, JSON.stringify({ etag: meta.etag, fetchedAt: Date.now() }));
+            return 'unchanged';
+        }
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+            const onDisk = writeCache(paths.raw, await res.body.text());
+            // fetchedAt only for a body that landed, or the next run trusts a meta with no raw.
+            if (onDisk) {
+                writeCache(paths.meta, JSON.stringify({ etag: typeof etag === 'string' ? etag : undefined, fetchedAt: Date.now() }));
+            }
+            return onDisk ? 'updated' : hasRaw ? 'unchanged' : 'updated-memory';
+        }
+        await res.body.dump();
+    }
+    catch {
+        // network error — fall back to the cached body if present
+    }
+    return hasRaw ? 'unchanged' : 'none';
+}