@litfamily/litopencode 1.0.0

package/dist/cli/update-notifier.js

@@ -0,0 +1,717 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import https from "node:https";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readPackageMetadata } from "./json.js";
+const packageName = "@litfamily/litopencode";
+const cacheSchemaVersion = 1;
+const updateCacheMaxBytes = 64 * 1024;
+const updateLockOwnerMaxBytes = 4 * 1024;
+export const npmLatestUrl = "https://registry.npmjs.org/%40litfamily%2Flitopencode/latest";
+export const updateTimeoutMs = 3000;
+export const updateResponseMaxBytes = 64 * 1024;
+export const updateCheckIntervalMs = 24 * 60 * 60 * 1000;
+export const updateLockStaleMs = 10 * 1000;
+export function parseStableVersion(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(value);
+    if (!match)
+        return undefined;
+    return [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])];
+}
+export function compareStableVersions(left, right) {
+    const leftParts = parseStableVersion(left);
+    const rightParts = parseStableVersion(right);
+    if (!leftParts || !rightParts)
+        return undefined;
+    for (let index = 0; index < leftParts.length; index += 1) {
+        if (leftParts[index] > rightParts[index])
+            return 1;
+        if (leftParts[index] < rightParts[index])
+            return -1;
+    }
+    return 0;
+}
+export function updateCachePath(homeDir = os.homedir()) {
+    return path.join(homeDir, ".litopencode", "update-check.json");
+}
+export function updateLockPath(homeDir = os.homedir()) {
+    return path.join(homeDir, ".litopencode", "update-check.lock");
+}
+export function updateTransitionLockPath(homeDir = os.homedir()) {
+    return path.join(homeDir, ".litopencode", "update-check.transition.lock");
+}
+function safeTimestamp(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function currentUserOwns(stats) {
+    return typeof process.getuid !== "function" || stats.uid === process.getuid();
+}
+function hasPrivateMode(stats) {
+    return process.platform === "win32" || (stats.mode & 0o077) === 0;
+}
+function safePrivateDirectory(stats) {
+    return stats.isDirectory() && currentUserOwns(stats) && hasPrivateMode(stats);
+}
+function safePrivateFile(stats, maximumBytes) {
+    return stats.isFile() && stats.size <= maximumBytes && currentUserOwns(stats) && hasPrivateMode(stats);
+}
+function sameFilesystemEntry(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function safeReadFlags() {
+    let flags = fsSync.constants.O_RDONLY;
+    if (typeof fsSync.constants.O_NOFOLLOW === "number")
+        flags |= fsSync.constants.O_NOFOLLOW;
+    if (typeof fsSync.constants.O_NONBLOCK === "number")
+        flags |= fsSync.constants.O_NONBLOCK;
+    return flags;
+}
+function missingFilesystemEntry(error) {
+    return error.code === "ENOENT";
+}
+async function safeDirectoryStatus(directoryPath) {
+    try {
+        return safePrivateDirectory(await fs.lstat(directoryPath)) ? "safe" : "unsafe";
+    }
+    catch (error) {
+        return missingFilesystemEntry(error) ? "missing" : "unsafe";
+    }
+}
+function safeDirectoryStatusSync(directoryPath) {
+    try {
+        return safePrivateDirectory(fsSync.lstatSync(directoryPath)) ? "safe" : "unsafe";
+    }
+    catch (error) {
+        return missingFilesystemEntry(error) ? "missing" : "unsafe";
+    }
+}
+async function ensureSafePrivateDirectory(directoryPath) {
+    await fs.mkdir(directoryPath, { recursive: true, mode: 0o700 });
+    if ((await safeDirectoryStatus(directoryPath)) !== "safe") {
+        throw new Error("update state directory is unsafe");
+    }
+}
+async function readSafeRegularFile(filePath, maximumBytes) {
+    let handle;
+    try {
+        const pathStats = await fs.lstat(filePath);
+        if (!safePrivateFile(pathStats, maximumBytes))
+            return { status: "unsafe" };
+        handle = await fs.open(filePath, safeReadFlags());
+        const descriptorStats = await handle.stat();
+        if (!safePrivateFile(descriptorStats, maximumBytes) || !sameFilesystemEntry(pathStats, descriptorStats)) {
+            return { status: "unsafe" };
+        }
+        const bytes = Buffer.alloc(maximumBytes + 1);
+        let totalBytes = 0;
+        while (totalBytes < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, totalBytes, bytes.length - totalBytes, totalBytes);
+            if (bytesRead === 0)
+                break;
+            totalBytes += bytesRead;
+        }
+        if (totalBytes > maximumBytes)
+            return { status: "unsafe" };
+        return { status: "ok", text: bytes.subarray(0, totalBytes).toString("utf8") };
+    }
+    catch (error) {
+        return missingFilesystemEntry(error) ? { status: "missing" } : { status: "unsafe" };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function readSafeRegularFileSync(filePath, maximumBytes) {
+    let descriptor;
+    try {
+        const pathStats = fsSync.lstatSync(filePath);
+        if (!safePrivateFile(pathStats, maximumBytes))
+            return { status: "unsafe" };
+        descriptor = fsSync.openSync(filePath, safeReadFlags());
+        const descriptorStats = fsSync.fstatSync(descriptor);
+        if (!safePrivateFile(descriptorStats, maximumBytes) || !sameFilesystemEntry(pathStats, descriptorStats)) {
+            return { status: "unsafe" };
+        }
+        const bytes = Buffer.alloc(maximumBytes + 1);
+        let totalBytes = 0;
+        while (totalBytes < bytes.length) {
+            const bytesRead = fsSync.readSync(descriptor, bytes, totalBytes, bytes.length - totalBytes, totalBytes);
+            if (bytesRead === 0)
+                break;
+            totalBytes += bytesRead;
+        }
+        if (totalBytes > maximumBytes)
+            return { status: "unsafe" };
+        return { status: "ok", text: bytes.subarray(0, totalBytes).toString("utf8") };
+    }
+    catch (error) {
+        return missingFilesystemEntry(error) ? { status: "missing" } : { status: "unsafe" };
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                fsSync.closeSync(descriptor);
+            }
+            catch {
+                // A failed close does not make an advisory read actionable.
+            }
+        }
+    }
+}
+export function parseUpdateCache(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const candidate = value;
+    if (candidate.schemaVersion !== cacheSchemaVersion || candidate.packageName !== packageName)
+        return undefined;
+    const latestVersion = candidate.latestVersion;
+    const checkedAt = candidate.checkedAt;
+    const failedAt = candidate.failedAt;
+    const attemptedAt = candidate.attemptedAt;
+    const ownerGeneration = candidate.ownerGeneration;
+    const hasSuccessfulResult = latestVersion !== undefined || checkedAt !== undefined;
+    if (hasSuccessfulResult && (parseStableVersion(latestVersion) === undefined || !safeTimestamp(checkedAt)))
+        return undefined;
+    if (failedAt !== undefined && !safeTimestamp(failedAt))
+        return undefined;
+    if (attemptedAt !== undefined && !safeTimestamp(attemptedAt))
+        return undefined;
+    if (ownerGeneration !== undefined && (typeof ownerGeneration !== "string" || ownerGeneration.length === 0 || attemptedAt === undefined)) {
+        return undefined;
+    }
+    if (!hasSuccessfulResult && failedAt === undefined && attemptedAt === undefined)
+        return undefined;
+    return {
+        schemaVersion: 1,
+        packageName,
+        ...(hasSuccessfulResult ? { latestVersion: latestVersion, checkedAt: checkedAt } : {}),
+        ...(failedAt === undefined ? {} : { failedAt }),
+        ...(attemptedAt === undefined ? {} : { attemptedAt }),
+        ...(ownerGeneration === undefined ? {} : { ownerGeneration: ownerGeneration })
+    };
+}
+async function readUpdateCacheState(cachePath) {
+    const read = await readSafeRegularFile(cachePath, updateCacheMaxBytes);
+    if (read.status === "unsafe")
+        return { status: "unsafe" };
+    if (read.status === "missing")
+        return { status: "safe", cache: undefined };
+    try {
+        return { status: "safe", cache: parseUpdateCache(JSON.parse(read.text)) };
+    }
+    catch {
+        return { status: "safe", cache: undefined };
+    }
+}
+export async function readUpdateCache(cachePath) {
+    const read = await readUpdateCacheState(cachePath);
+    return read.status === "safe" ? read.cache : undefined;
+}
+function lockIsOwnedBySync(lock) {
+    if (safeDirectoryStatusSync(lock.path) !== "safe")
+        return false;
+    const read = readSafeRegularFileSync(path.join(lock.path, "owner.json"), updateLockOwnerMaxBytes);
+    if (read.status !== "ok")
+        return false;
+    try {
+        const parsed = JSON.parse(read.text);
+        const generation = typeof parsed.generation === "string" ? parsed.generation : parsed.token;
+        return generation === lock.generation && safeTimestamp(parsed.acquiredAt);
+    }
+    catch {
+        return false;
+    }
+}
+function updateCacheCommitIsOwned(cachePath, guard) {
+    if (guard.expectedCacheOwnerGeneration !== undefined) {
+        const read = readSafeRegularFileSync(cachePath, updateCacheMaxBytes);
+        if (read.status !== "ok")
+            return false;
+        try {
+            const current = parseUpdateCache(JSON.parse(read.text));
+            if (current?.ownerGeneration !== guard.expectedCacheOwnerGeneration)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (!lockIsOwnedBySync(guard.refresh))
+        return false;
+    return lockIsOwnedBySync(guard.transition);
+}
+async function commitUpdateCacheAtomically(cachePath, cache, guard) {
+    const directory = path.dirname(cachePath);
+    await ensureSafePrivateDirectory(directory);
+    const temporaryPath = path.join(directory, `.update-check.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+    try {
+        await fs.writeFile(temporaryPath, `${JSON.stringify(cache, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        if (guard && !updateCacheCommitIsOwned(cachePath, guard))
+            return false;
+        fsSync.renameSync(temporaryPath, cachePath);
+        return true;
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+export async function writeUpdateCacheAtomically(cachePath, cache) {
+    await commitUpdateCacheAtomically(cachePath, cache);
+}
+export function shouldRunUpdateNotifier(input) {
+    if (input.exitCode !== 0)
+        return false;
+    if (input.argv[0] !== "install" && input.argv[0] !== "doctor")
+        return false;
+    if (input.argv.some((arg) => arg === "--dry-run" || arg === "--json" || arg === "--help" || arg === "-h"))
+        return false;
+    if (input.stdinIsTTY !== true || input.stdoutIsTTY !== true || input.stderrIsTTY !== true)
+        return false;
+    if (input.env.CI !== undefined)
+        return false;
+    if (input.env.NO_UPDATE_NOTIFIER !== undefined || input.env.LITOPENCODE_NO_UPDATE_CHECK !== undefined)
+        return false;
+    return true;
+}
+export function shouldRefreshUpdateCache(cache, now) {
+    if (cacheHasFutureTimestamp(cache, now))
+        return true;
+    if (cache?.failedAt !== undefined && now - cache.failedAt < updateCheckIntervalMs)
+        return false;
+    if (cache?.checkedAt !== undefined && now - cache.checkedAt < updateCheckIntervalMs)
+        return false;
+    if (cache?.attemptedAt !== undefined && now - cache.attemptedAt < updateCheckIntervalMs)
+        return false;
+    return true;
+}
+function cacheHasFutureTimestamp(cache, now) {
+    return cache !== undefined && [cache.checkedAt, cache.failedAt, cache.attemptedAt]
+        .some((timestamp) => timestamp !== undefined && timestamp > now);
+}
+function successfulCacheFields(cache, now) {
+    if (cache === undefined ||
+        cacheHasFutureTimestamp(cache, now) ||
+        cache.latestVersion === undefined ||
+        cache.checkedAt === undefined) {
+        return {};
+    }
+    return { latestVersion: cache.latestVersion, checkedAt: cache.checkedAt };
+}
+export function renderUpdateNotice(currentVersion, latestVersion) {
+    if (compareStableVersions(latestVersion, currentVersion) !== 1)
+        return undefined;
+    return [
+        `LitOpenCode update available: ${String(currentVersion)} -> ${String(latestVersion)}`,
+        `Run: npm exec --yes --package @litfamily/litopencode@${String(latestVersion)} -- litopencode install --no-model-prompt --no-permission-prompt --no-auto-update`,
+        "Restart OpenCode after installing."
+    ].join("\n");
+}
+function contentType(headers) {
+    const value = headers["content-type"];
+    return typeof value === "string" ? value : undefined;
+}
+export async function readRegistryLatestVersion(response) {
+    if (response.statusCode !== 200)
+        throw new Error("npm latest endpoint must return exact status 200");
+    const responseContentType = contentType(response.headers);
+    if (!responseContentType || !/^application\/json(?:\s*;[^\r\n]*)?$/i.test(responseContentType)) {
+        throw new Error("npm latest endpoint must return a JSON content type");
+    }
+    const declaredLength = response.headers["content-length"];
+    if (typeof declaredLength === "string" && /^\d+$/.test(declaredLength) && BigInt(declaredLength) > BigInt(updateResponseMaxBytes)) {
+        throw new Error("npm latest response exceeds 64 KiB");
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of response) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        totalBytes += buffer.byteLength;
+        if (totalBytes > updateResponseMaxBytes)
+            throw new Error("npm latest response exceeds 64 KiB");
+        chunks.push(buffer);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new Error("npm latest endpoint returned invalid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("npm latest endpoint returned an invalid package record");
+    }
+    const record = parsed;
+    if (record.name !== packageName)
+        throw new Error("npm latest endpoint returned the wrong package identity");
+    if (parseStableVersion(record.version) === undefined)
+        throw new Error("npm latest endpoint returned an invalid stable version");
+    return record.version;
+}
+export function requestRegistryLatestVersionWithTransport(transport) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let request;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            callback();
+        };
+        const deadline = setTimeout(() => {
+            const error = new Error("npm latest request exceeded the 3 second total timeout");
+            finish(() => {
+                request?.destroy(error);
+                reject(error);
+            });
+        }, updateTimeoutMs);
+        try {
+            request = transport(npmLatestUrl, {
+                headers: {
+                    accept: "application/json",
+                    "user-agent": "litopencode-update-check"
+                }
+            }, (response) => {
+                void readRegistryLatestVersion(response).then((version) => finish(() => resolve(version)), (error) => finish(() => {
+                    const responseError = error instanceof Error ? error : new Error(String(error));
+                    request?.destroy(responseError);
+                    reject(responseError);
+                }));
+            });
+            request.once("error", (error) => finish(() => reject(error)));
+        }
+        catch (error) {
+            finish(() => reject(error));
+        }
+    });
+}
+export function requestRegistryLatestVersion() {
+    return requestRegistryLatestVersionWithTransport((url, options, callback) => https.get(url, options, callback));
+}
+async function readLockOwner(lockPath) {
+    if ((await safeDirectoryStatus(lockPath)) !== "safe")
+        return { status: "unsafe" };
+    const read = await readSafeRegularFile(path.join(lockPath, "owner.json"), updateLockOwnerMaxBytes);
+    if (read.status === "unsafe")
+        return { status: "unsafe" };
+    if (read.status === "missing")
+        return { status: "missing" };
+    try {
+        const parsed = JSON.parse(read.text);
+        const generation = typeof parsed.generation === "string" ? parsed.generation : parsed.token;
+        if (typeof generation !== "string" || generation.length === 0 || !safeTimestamp(parsed.acquiredAt)) {
+            return { status: "invalid" };
+        }
+        return { status: "valid", owner: { path: lockPath, generation, acquiredAt: parsed.acquiredAt } };
+    }
+    catch {
+        return { status: "invalid" };
+    }
+}
+async function lockOwner(lockPath) {
+    const read = await readLockOwner(lockPath);
+    return read.status === "valid" ? read.owner : undefined;
+}
+async function lockIsStale(lockPath, now) {
+    const read = await readLockOwner(lockPath);
+    if (read.status === "unsafe")
+        return false;
+    if (read.status === "valid") {
+        return read.owner.acquiredAt > now || now - read.owner.acquiredAt >= updateLockStaleMs;
+    }
+    try {
+        const stats = await fs.lstat(lockPath);
+        if (!safePrivateDirectory(stats))
+            return false;
+        return stats.mtimeMs > now || now - stats.mtimeMs >= updateLockStaleMs;
+    }
+    catch {
+        return true;
+    }
+}
+function wait(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function lockIsOwnedBy(lock) {
+    return (await lockOwner(lock.path))?.generation === lock.generation;
+}
+async function acquireTransitionLock(homeDir) {
+    const lockPath = updateTransitionLockPath(homeDir);
+    await ensureSafePrivateDirectory(path.dirname(lockPath));
+    const deadline = Date.now() + updateLockStaleMs + 1000;
+    while (true) {
+        const generation = randomUUID();
+        const acquiredAt = Date.now();
+        try {
+            await fs.mkdir(lockPath, { mode: 0o700 });
+            const owner = { path: lockPath, generation, acquiredAt };
+            try {
+                await fs.writeFile(path.join(lockPath, "owner.json"), `${JSON.stringify({ generation, acquiredAt })}\n`, {
+                    encoding: "utf8",
+                    flag: "wx",
+                    mode: 0o600
+                });
+                return owner;
+            }
+            catch (error) {
+                await fs.rm(lockPath, { recursive: true, force: true });
+                throw error;
+            }
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const lockStatus = await safeDirectoryStatus(lockPath);
+            if (lockStatus === "missing") {
+                if (Date.now() >= deadline)
+                    throw new Error("update transition mutex acquisition timed out");
+                continue;
+            }
+            if (lockStatus === "unsafe") {
+                throw new Error("update transition mutex is unsafe");
+            }
+            const ownerRead = await readSafeRegularFile(path.join(lockPath, "owner.json"), updateLockOwnerMaxBytes);
+            if (ownerRead.status === "unsafe")
+                throw new Error("update transition mutex owner is unsafe");
+            const currentNow = Date.now();
+            // Never age-evict this mutex: an owner paused at a filesystem await can still resume and mutate.
+            if (currentNow >= deadline)
+                throw new Error("update transition mutex acquisition timed out");
+            await wait(10);
+        }
+    }
+}
+async function releaseOwnedLock(lock) {
+    const owner = await lockOwner(lock.path);
+    if (owner?.generation !== lock.generation)
+        return;
+    await fs.rm(lock.path, { recursive: true, force: true });
+}
+async function withTransitionLock(homeDir, operation) {
+    const transition = await acquireTransitionLock(homeDir);
+    try {
+        return await operation(transition);
+    }
+    finally {
+        await releaseOwnedLock(transition);
+    }
+}
+async function acquireRefreshLock(homeDir, clock) {
+    return withTransitionLock(homeDir, async (transition) => {
+        const lockPath = updateLockPath(homeDir);
+        if (!(await lockIsOwnedBy(transition)))
+            return undefined;
+        try {
+            await fs.mkdir(lockPath, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (!(await lockIsStale(lockPath, clock())))
+                return undefined;
+            if (!(await lockIsOwnedBy(transition)))
+                return undefined;
+            await fs.rm(lockPath, { recursive: true, force: true });
+            await fs.mkdir(lockPath, { mode: 0o700 });
+        }
+        const generation = randomUUID();
+        try {
+            if (!(await lockIsOwnedBy(transition)))
+                return undefined;
+            const acquiredAt = clock();
+            const owner = { path: lockPath, generation, acquiredAt };
+            await fs.writeFile(path.join(lockPath, "owner.json"), `${JSON.stringify({ generation, acquiredAt })}\n`, {
+                encoding: "utf8",
+                flag: "wx",
+                mode: 0o600
+            });
+            return owner;
+        }
+        catch (error) {
+            if (await lockIsOwnedBy(transition))
+                await fs.rm(lockPath, { recursive: true, force: true });
+            throw error;
+        }
+    });
+}
+async function reserveRefreshAttempt(homeDir, cachePath, lock, clock) {
+    return withTransitionLock(homeDir, async (transition) => {
+        const owner = await lockOwner(lock.path);
+        if (owner?.generation !== lock.generation)
+            return false;
+        const cacheRead = await readUpdateCacheState(cachePath);
+        if (cacheRead.status === "unsafe")
+            return false;
+        const current = cacheRead.cache;
+        if (!shouldRefreshUpdateCache(current, clock()))
+            return false;
+        if ((await lockOwner(lock.path))?.generation !== lock.generation)
+            return false;
+        if (!(await lockIsOwnedBy(transition)))
+            return false;
+        const attemptedAt = clock();
+        return commitUpdateCacheAtomically(cachePath, {
+            schemaVersion: 1,
+            packageName,
+            ...successfulCacheFields(current, attemptedAt),
+            attemptedAt,
+            ownerGeneration: lock.generation
+        }, {
+            transition,
+            refresh: lock
+        });
+    });
+}
+async function commitRefreshCompletion(homeDir, cachePath, lock, clock, completion) {
+    return withTransitionLock(homeDir, async (transition) => {
+        const owner = await lockOwner(lock.path);
+        if (owner?.generation !== lock.generation)
+            return false;
+        const cacheRead = await readUpdateCacheState(cachePath);
+        if (cacheRead.status === "unsafe")
+            return false;
+        const current = cacheRead.cache;
+        if (current?.ownerGeneration !== lock.generation)
+            return false;
+        if ((await lockOwner(lock.path))?.generation !== lock.generation)
+            return false;
+        if (!(await lockIsOwnedBy(transition)))
+            return false;
+        const completedAt = clock();
+        let committed;
+        if (completion.status === "success") {
+            committed = await commitUpdateCacheAtomically(cachePath, {
+                schemaVersion: 1,
+                packageName,
+                latestVersion: completion.latestVersion,
+                checkedAt: completedAt
+            }, {
+                transition,
+                refresh: lock,
+                expectedCacheOwnerGeneration: lock.generation
+            });
+        }
+        else {
+            committed = await commitUpdateCacheAtomically(cachePath, {
+                schemaVersion: 1,
+                packageName,
+                ...successfulCacheFields(current, completedAt),
+                failedAt: completedAt
+            }, {
+                transition,
+                refresh: lock,
+                expectedCacheOwnerGeneration: lock.generation
+            });
+        }
+        if (!committed)
+            return false;
+        if ((await lockOwner(lock.path))?.generation !== lock.generation)
+            return false;
+        if (!(await lockIsOwnedBy(transition)))
+            return false;
+        await fs.rm(lock.path, { recursive: true, force: true });
+        return true;
+    });
+}
+async function releaseRefreshLock(homeDir, lock) {
+    await withTransitionLock(homeDir, async (transition) => {
+        if ((await lockOwner(lock.path))?.generation !== lock.generation)
+            return;
+        if (!(await lockIsOwnedBy(transition)))
+            return;
+        await fs.rm(lock.path, { recursive: true, force: true });
+    });
+}
+export async function refreshUpdateCache(options = {}) {
+    const stateDirectory = path.dirname(updateCachePath(options.homeDir));
+    if ((await safeDirectoryStatus(stateDirectory)) === "unsafe")
+        return;
+    const transitionPath = updateTransitionLockPath(options.homeDir);
+    const transitionStatus = await safeDirectoryStatus(transitionPath);
+    if (transitionStatus === "unsafe")
+        return;
+    if (transitionStatus === "safe") {
+        const ownerRead = await readSafeRegularFile(path.join(transitionPath, "owner.json"), updateLockOwnerMaxBytes);
+        if (ownerRead.status === "unsafe")
+            return;
+    }
+    const fixedNow = options.now;
+    const clock = options.clock ?? (fixedNow === undefined ? Date.now : () => fixedNow);
+    const cachePath = updateCachePath(options.homeDir);
+    const lock = await acquireRefreshLock(options.homeDir, clock);
+    if (!lock)
+        return;
+    try {
+        if (!(await reserveRefreshAttempt(options.homeDir, cachePath, lock, clock)))
+            return;
+        try {
+            const latestVersion = await (options.fetchLatestVersion ?? requestRegistryLatestVersion)();
+            if (parseStableVersion(latestVersion) === undefined)
+                throw new Error("update check returned an invalid stable version");
+            await commitRefreshCompletion(options.homeDir, cachePath, lock, clock, { status: "success", latestVersion });
+        }
+        catch {
+            await commitRefreshCompletion(options.homeDir, cachePath, lock, clock, { status: "failure" });
+        }
+    }
+    finally {
+        await releaseRefreshLock(options.homeDir, lock);
+    }
+}
+function detachedUpdateEnvironment(env) {
+    const childEnv = {};
+    for (const key of ["HOME", "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "SystemRoot", "SYSTEMROOT", "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR"]) {
+        if (env[key] !== undefined)
+            childEnv[key] = env[key];
+    }
+    return childEnv;
+}
+export function launchDetachedUpdateRefreshWith(spawnProcess, env, execPath, helperPath) {
+    const child = spawnProcess(execPath, [helperPath, "--refresh"], {
+        detached: true,
+        stdio: "ignore",
+        env: detachedUpdateEnvironment(env)
+    });
+    child.once("error", () => undefined);
+    child.unref();
+}
+export function launchDetachedUpdateRefresh(env = process.env) {
+    const helperPath = fileURLToPath(new URL("./update-check.js", import.meta.url));
+    launchDetachedUpdateRefreshWith(spawn, env, process.execPath, helperPath);
+}
+export async function runUpdateNotifier(options) {
+    if (!shouldRunUpdateNotifier(options))
+        return;
+    try {
+        const metadata = options.currentVersion === undefined ? await readPackageMetadata() : undefined;
+        if (metadata && metadata.name !== packageName)
+            return;
+        const currentVersion = options.currentVersion ?? metadata?.version;
+        if (parseStableVersion(currentVersion) === undefined)
+            return;
+        const stateDirectory = path.dirname(updateCachePath(options.homeDir));
+        if ((await safeDirectoryStatus(stateDirectory)) === "unsafe")
+            return;
+        const now = options.now ?? Date.now();
+        const cacheRead = await readUpdateCacheState(updateCachePath(options.homeDir));
+        if (cacheRead.status === "unsafe")
+            return;
+        const cache = cacheRead.cache;
+        const notice = cache?.latestVersion === undefined || cacheHasFutureTimestamp(cache, now)
+            ? undefined
+            : renderUpdateNotice(currentVersion, cache.latestVersion);
+        if (notice)
+            (options.writeStderr ?? ((text) => process.stderr.write(text)))(`${notice}\n`);
+        if (shouldRefreshUpdateCache(cache, now))
+            (options.launchRefresh ?? (() => launchDetachedUpdateRefresh(options.env)))();
+    }
+    catch {
+        // Update checks are advisory and must never change CLI command behavior.
+    }
+}