@saifymatteo/pi-x-ide 0.0.0-stage → 1.20.2

package/dist/src/shared/display-width.js

@@ -0,0 +1,99 @@
+const ESC = String.fromCharCode(27);
+const ANSI_PATTERN = new RegExp(`${ESC}\\[[0-?]*[ -/]*[@-~]`, "g");
+const EMOJI_VARIATION_SELECTOR = 0xfe0f;
+const COMBINING_ENCLOSING_KEYCAP = 0x20e3;
+const graphemeSegmenter = typeof Intl.Segmenter === "function" ? new Intl.Segmenter(undefined, { granularity: "grapheme" }) : undefined;
+export function visibleWidth(input) {
+    let width = 0;
+    for (const grapheme of graphemes(stripAnsi(input)))
+        width += graphemeWidth(grapheme);
+    return width;
+}
+export function truncateToWidth(input, maxWidth, ellipsis = "...", pad = false) {
+    if (maxWidth <= 0)
+        return "";
+    const inputWidth = visibleWidth(input);
+    if (inputWidth <= maxWidth)
+        return padToWidth(input, maxWidth, pad);
+    const suffix = fitSuffix(ellipsis, maxWidth);
+    const suffixWidth = visibleWidth(suffix);
+    const contentLimit = Math.max(0, maxWidth - suffixWidth);
+    let output = "";
+    let used = 0;
+    for (const grapheme of graphemes(stripAnsi(input))) {
+        const width = graphemeWidth(grapheme);
+        if (used + width > contentLimit)
+            break;
+        output += grapheme;
+        used += width;
+    }
+    return padToWidth(output + suffix, maxWidth, pad);
+}
+function stripAnsi(input) {
+    return input.replace(ANSI_PATTERN, "");
+}
+function* graphemes(input) {
+    if (graphemeSegmenter) {
+        for (const segment of graphemeSegmenter.segment(input))
+            yield segment.segment;
+        return;
+    }
+    yield* input;
+}
+function padToWidth(input, maxWidth, pad) {
+    if (!pad)
+        return input;
+    return input + " ".repeat(Math.max(0, maxWidth - visibleWidth(input)));
+}
+function fitSuffix(ellipsis, maxWidth) {
+    if (visibleWidth(ellipsis) <= maxWidth)
+        return ellipsis;
+    let output = "";
+    let used = 0;
+    for (const grapheme of graphemes(stripAnsi(ellipsis))) {
+        const width = graphemeWidth(grapheme);
+        if (used + width > maxWidth)
+            break;
+        output += grapheme;
+        used += width;
+    }
+    return output;
+}
+function graphemeWidth(grapheme) {
+    if (grapheme.length === 0)
+        return 0;
+    const codePoints = [...grapheme].map((char) => char.codePointAt(0)).filter((value) => value !== undefined);
+    if (codePoints.every(isZeroWidthCodePoint))
+        return 0;
+    if (codePoints.every(isControlCodePoint))
+        return 0;
+    if (codePoints.includes(EMOJI_VARIATION_SELECTOR) || codePoints.includes(COMBINING_ENCLOSING_KEYCAP))
+        return 2;
+    return codePoints.some(isWideCodePoint) ? 2 : 1;
+}
+function isZeroWidthCodePoint(codePoint) {
+    return ((codePoint >= 0x0300 && codePoint <= 0x036f) ||
+        (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+        (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+        (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+        (codePoint >= 0xfe20 && codePoint <= 0xfe2f) ||
+        codePoint === 0x200d ||
+        codePoint === 0xfe0e ||
+        codePoint === 0xfe0f);
+}
+function isControlCodePoint(codePoint) {
+    return codePoint <= 0x001f || (codePoint >= 0x007f && codePoint <= 0x009f);
+}
+function isWideCodePoint(codePoint) {
+    return ((codePoint >= 0x1100 && codePoint <= 0x11ff) ||
+        (codePoint >= 0x2e80 && codePoint <= 0xa4cf) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+        (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+        (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+        (codePoint >= 0x1f1e6 && codePoint <= 0x1f1ff) ||
+        (codePoint >= 0x1f300 && codePoint <= 0x1faff) ||
+        (codePoint >= 0x20000 && codePoint <= 0x3fffd));
+}

package/dist/src/shared/effect-errors.js

@@ -0,0 +1,36 @@
+import * as Data from "effect/Data";
+function describeUnknown(value) {
+    return value instanceof Error ? value.message : String(value);
+}
+export class LockFileParseError extends Data.TaggedError("LockFileParseError") {
+    get message() {
+        return this.path ? `LockFileParseError: ${this.reason} (${this.path})` : `LockFileParseError: ${this.reason}`;
+    }
+}
+export class LockDirReadError extends Data.TaggedError("LockDirReadError") {
+    get message() {
+        return `LockDirReadError: failed to read ${this.path}: ${describeUnknown(this.cause)}`;
+    }
+}
+export class IdeConnectTimeoutError extends Data.TaggedError("IdeConnectTimeoutError") {
+    get message() {
+        return `IdeConnectTimeoutError: ${this.name} at ${this.host}:${this.port}`;
+    }
+}
+export class IdeConnectError extends Data.TaggedError("IdeConnectError") {
+    get message() {
+        return `IdeConnectError: ${this.host}:${this.port}: ${describeUnknown(this.cause)}`;
+    }
+}
+export class ConfigParseError extends Data.TaggedError("ConfigParseError") {
+    get message() {
+        return `ConfigParseError: ${this.reason} (${this.path})`;
+    }
+}
+export class InstallCommandError extends Data.TaggedError("InstallCommandError") {
+    get message() {
+        const exitPart = this.code === undefined ? "" : ` exited ${String(this.code)}`;
+        const detail = this.stderr.trim() || this.stdout?.trim() || "command failed";
+        return `InstallCommandError: ${this.cli}${exitPart}: ${detail}`;
+    }
+}

package/dist/src/shared/effect-runtime.js

@@ -0,0 +1,36 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { logExtensionError } from "./errors.js";
+function reportBoundaryFailure(scope, error, onError) {
+    if (onError)
+        onError(error);
+    else
+        logExtensionError(scope, error);
+}
+function failureFromCause(cause) {
+    return Cause.squash(cause);
+}
+export async function runEffect(scope, effect, onError) {
+    const exit = await Effect.runPromiseExit(effect);
+    if (Exit.isSuccess(exit)) {
+        return exit.value;
+    }
+    reportBoundaryFailure(scope, failureFromCause(exit.cause), onError);
+    return undefined;
+}
+export function runEffectSync(scope, effect, onError) {
+    const exit = Effect.runSyncExit(effect);
+    if (Exit.isSuccess(exit)) {
+        return exit.value;
+    }
+    reportBoundaryFailure(scope, failureFromCause(exit.cause), onError);
+    return undefined;
+}
+export async function runEffectOrThrow(effect) {
+    const exit = await Effect.runPromiseExit(effect);
+    if (Exit.isSuccess(exit)) {
+        return exit.value;
+    }
+    throw failureFromCause(exit.cause);
+}

package/dist/src/shared/effect-schema.js

@@ -0,0 +1,120 @@
+import * as Either from "effect/Either";
+import * as Schema from "effect/Schema";
+const FiniteNumber = Schema.Number.pipe(Schema.finite());
+const NonNegativeFinite = FiniteNumber.pipe(Schema.greaterThanOrEqualTo(0));
+const PortNumber = FiniteNumber.pipe(Schema.greaterThan(0), Schema.lessThanOrEqualTo(65_535));
+export const PositionSchema = Schema.Struct({
+    line: NonNegativeFinite,
+    character: NonNegativeFinite,
+});
+export const SelectionRangeSchema = Schema.Struct({
+    text: Schema.String,
+    selection: Schema.Struct({
+        start: PositionSchema,
+        end: PositionSchema,
+    }),
+});
+export const IdeSourceSchema = Schema.Literal("vscode", "zed", "nvim", "jetbrains", "unknown");
+export const IdeLockFileSchema = Schema.Struct({
+    version: Schema.Literal(1),
+    ide: IdeSourceSchema,
+    name: Schema.String,
+    transport: Schema.Literal("ws"),
+    host: Schema.String,
+    port: PortNumber,
+    authToken: Schema.String,
+    workspaceFolders: Schema.mutable(Schema.Array(Schema.String)),
+    pid: Schema.optional(FiniteNumber),
+    runningInWindows: Schema.optional(Schema.Boolean),
+    createdAt: Schema.String,
+    updatedAt: Schema.String,
+});
+export const EditorSelectionSnapshotSchema = Schema.Struct({
+    source: IdeSourceSchema,
+    filePath: Schema.String,
+    workspaceFolder: Schema.optional(Schema.String),
+    ranges: Schema.mutable(Schema.Array(SelectionRangeSchema)),
+    receivedAt: Schema.optional(FiniteNumber),
+});
+export const SelectionChangedParamsSchema = EditorSelectionSnapshotSchema;
+export const SelectionClearedParamsSchema = Schema.Struct({
+    source: IdeSourceSchema,
+    reason: Schema.Literal("no-active-editor"),
+    receivedAt: Schema.optional(FiniteNumber),
+});
+export const AtMentionedParamsSchema = Schema.Struct({
+    source: IdeSourceSchema,
+    filePath: Schema.String,
+    workspaceFolder: Schema.optional(Schema.String),
+    ranges: Schema.mutable(Schema.Array(SelectionRangeSchema)),
+    receivedAt: Schema.optional(FiniteNumber),
+    rangeText: Schema.String,
+});
+const IdeDiagnosticCodeSchema = Schema.Union(Schema.String, FiniteNumber, Schema.Struct({
+    value: Schema.Union(Schema.String, FiniteNumber),
+    target: Schema.optional(Schema.String),
+}));
+const DiagnosticContextLineSchema = Schema.Struct({
+    line: NonNegativeFinite,
+    text: Schema.String,
+    isPrimary: Schema.Boolean,
+});
+const RangeSchema = Schema.Struct({
+    start: PositionSchema,
+    end: PositionSchema,
+});
+const IdeDiagnosticRelatedInformationSchema = Schema.Struct({
+    filePath: Schema.String,
+    range: RangeSchema,
+    message: Schema.String,
+});
+export const IdeDiagnosticSchema = Schema.Struct({
+    severity: Schema.Literal("error", "warning"),
+    message: Schema.String,
+    source: Schema.optional(Schema.String),
+    code: Schema.optional(IdeDiagnosticCodeSchema),
+    range: RangeSchema,
+    selectedText: Schema.String,
+    contextLines: Schema.mutable(Schema.Array(DiagnosticContextLineSchema)),
+    relatedInformation: Schema.optional(Schema.mutable(Schema.Array(IdeDiagnosticRelatedInformationSchema))),
+});
+export const DiagnosticFixRequestedParamsSchema = Schema.Struct({
+    action: Schema.optional(Schema.Literal("fix", "send-diagnostic")),
+    source: Schema.Literal("vscode"),
+    filePath: Schema.String,
+    workspaceFolder: Schema.optional(Schema.String),
+    documentVersion: Schema.optional(FiniteNumber),
+    triggerRange: RangeSchema,
+    diagnostics: Schema.mutable(Schema.Array(IdeDiagnosticSchema)).pipe(Schema.minItems(1)),
+    receivedAt: Schema.optional(FiniteNumber),
+});
+export const JsonRpcRequestSchema = Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: Schema.Union(Schema.String, FiniteNumber),
+    method: Schema.String,
+});
+function decodeUnknown(schema, input) {
+    const result = Schema.decodeUnknownEither(schema)(input);
+    return Either.isRight(result) ? result.right : undefined;
+}
+export function decodeLockFile(input) {
+    return decodeUnknown(IdeLockFileSchema, input);
+}
+export function decodeEditorSelectionSnapshot(input) {
+    return decodeUnknown(EditorSelectionSnapshotSchema, input);
+}
+export function decodeSelectionChangedParams(input) {
+    return decodeEditorSelectionSnapshot(input);
+}
+export function decodeSelectionClearedParams(input) {
+    return decodeUnknown(SelectionClearedParamsSchema, input);
+}
+export function decodeAtMentionedParams(input) {
+    return decodeUnknown(AtMentionedParamsSchema, input);
+}
+export function decodeDiagnosticFixRequestedParams(input) {
+    return decodeUnknown(DiagnosticFixRequestedParamsSchema, input);
+}
+export function decodeJsonRpcRequest(input) {
+    return decodeUnknown(JsonRpcRequestSchema, input);
+}

package/dist/src/shared/errors.js

@@ -0,0 +1,48 @@
+let extensionErrorReporter;
+export function setExtensionErrorReporter(reporter) {
+    extensionErrorReporter = reporter;
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function isStaleContextError(error) {
+    return errorMessage(error).includes("stale after session replacement or reload");
+}
+export function toError(error, prefix) {
+    if (error instanceof Error) {
+        if (!prefix)
+            return error;
+        return new Error(`${prefix}: ${error.message}`, { cause: error });
+    }
+    return new Error(prefix ? `${prefix}: ${String(error)}` : String(error));
+}
+export function formatExtensionError(scope, error) {
+    return `[pi-x-ide] ${scope}: ${errorMessage(error)}`;
+}
+export function logExtensionError(scope, error) {
+    extensionErrorReporter?.(scope, error);
+}
+export function safeRun(scope, action, onError) {
+    try {
+        return action();
+    }
+    catch (error) {
+        if (onError)
+            onError(error);
+        else
+            logExtensionError(scope, error);
+        return undefined;
+    }
+}
+export async function safeRunAsync(scope, action, onError) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        if (onError)
+            onError(error);
+        else
+            logExtensionError(scope, error);
+        return undefined;
+    }
+}

package/dist/src/shared/format.js

@@ -0,0 +1,92 @@
+import { toRelativeDisplayPath } from "./paths.js";
+export const SYSTEM_REMINDER_TAG = "system-reminder";
+export const SELECTED_CONTEXT_MARKER = "selected-context";
+export function rangeToLineSpan(range) {
+    return {
+        startLine: range.selection.start.line + 1,
+        endLine: range.selection.end.line + 1,
+    };
+}
+export function formatLineRange(range) {
+    const { startLine, endLine } = rangeToLineSpan(range);
+    return startLine === endLine ? `L${startLine}` : `L${startLine}-L${endLine}`;
+}
+export function formatLineSpan(range) {
+    return `#${formatLineRange(range)}`;
+}
+export function formatRangeMention(snapshot, options = {}) {
+    const rel = toRelativeDisplayPath(snapshot.filePath, snapshot.workspaceFolder, options.cwd, options.env);
+    const first = snapshot.ranges[0];
+    return first ? `@${rel}${formatLineSpan(first)}` : `@${rel}`;
+}
+export function parseRangeMention(input) {
+    const match = input.trim().match(/^@(.+?)(?:#L(\d+)(?:-L(\d+))?)?$/);
+    if (!match)
+        return undefined;
+    const startLine = match[2] ? Number(match[2]) : undefined;
+    const endLine = match[3] ? Number(match[3]) : startLine;
+    for (const value of [startLine, endLine]) {
+        if (value !== undefined && (!Number.isInteger(value) || value < 1))
+            return undefined;
+    }
+    return { path: match[1], startLine, endLine };
+}
+export function describeRanges(ranges) {
+    if (ranges.length === 0)
+        return "open file";
+    if (ranges.length === 1)
+        return formatLineSpan(ranges[0]);
+    return ranges.map((range, index) => `${index + 1}:${formatLineSpan(range)}`).join(" ");
+}
+export function snapshotKey(snapshot) {
+    return JSON.stringify({
+        source: snapshot.source,
+        filePath: snapshot.filePath,
+        workspaceFolder: snapshot.workspaceFolder,
+        ranges: snapshot.ranges.map((range) => ({
+            start: range.selection.start,
+            end: range.selection.end,
+            textLength: range.text.length,
+        })),
+    });
+}
+export function formatEditorContextMessage(snapshot, options = {}) {
+    const filePath = toRelativeDisplayPath(snapshot.filePath, snapshot.workspaceFolder, undefined, options.env).replaceAll("`", "\\`");
+    const lines = ["### IDE Context", `- **IDE**: ${snapshot.source}`, `- **File**: \`${filePath}\``];
+    if (snapshot.ranges.length > 0) {
+        lines.push(`- **Selection**: ${snapshot.ranges.map(formatLineRange).join(", ")}`);
+    }
+    return lines.join("\n");
+}
+export function formatEditorContext(snapshot, options = {}) {
+    const filePath = toRelativeDisplayPath(snapshot.filePath, undefined, undefined, options.env);
+    const maxChars = options.maxChars ?? 24_000;
+    if (snapshot.ranges.length === 0) {
+        return `<${SYSTEM_REMINDER_TAG}><${SELECTED_CONTEXT_MARKER}>
+The user currently has \`${filePath}\` open in ${snapshot.source}. This may or may not be relevant.
+</${SELECTED_CONTEXT_MARKER}></${SYSTEM_REMINDER_TAG}>
+`;
+    }
+    const sections = [];
+    let remaining = maxChars;
+    let truncated = false;
+    for (const [index, range] of snapshot.ranges.entries()) {
+        const label = snapshot.ranges.length === 1 ? "The user selected" : `Selection ${index + 1}`;
+        let text = range.text;
+        if (text.length > remaining) {
+            text = text.slice(0, Math.max(0, remaining));
+            truncated = true;
+        }
+        remaining -= text.length;
+        const rangeStr = formatLineRange(range);
+        sections.push(`${label} ${rangeStr} from \`${filePath}\` in ${snapshot.source}:\n\`\`\`\n${text}\n\`\`\``);
+        if (remaining <= 0)
+            break;
+    }
+    const suffix = truncated ? "\n[Selection text truncated to keep the prompt size bounded.]" : "";
+    return `<${SYSTEM_REMINDER_TAG}><${SELECTED_CONTEXT_MARKER}>
+${sections.join("\n")}
+This may or may not be relevant.${suffix}
+</${SELECTED_CONTEXT_MARKER}></${SYSTEM_REMINDER_TAG}>
+`;
+}

package/dist/src/shared/ide-server.js

@@ -0,0 +1,167 @@
+import { createServer } from "node:http";
+import WebSocket, { WebSocketServer } from "ws";
+import { AUTH_HEADER, PROTOCOL_VERSION, } from "./protocol.js";
+import { isJsonRpcRequest } from "./jsonrpc-guard.js";
+import { logExtensionError } from "./errors.js";
+import { decodeRawData } from "./ws.js";
+export class IdeWebSocketServer {
+    authToken;
+    serverInfo;
+    getInitialSelection;
+    httpServer;
+    wss;
+    sockets = new Set();
+    constructor(authToken, serverInfo, getInitialSelection) {
+        this.authToken = authToken;
+        this.serverInfo = serverInfo;
+        this.getInitialSelection = getInitialSelection;
+    }
+    get port() {
+        const address = this.httpServer?.address();
+        if (!address || typeof address === "string")
+            return 0;
+        return address.port;
+    }
+    get clientCount() {
+        return this.openSockets.length;
+    }
+    async start() {
+        this.httpServer = createServer();
+        this.wss = new WebSocketServer({
+            server: this.httpServer,
+            verifyClient: ({ req }, done) => {
+                const header = req.headers[AUTH_HEADER];
+                const token = Array.isArray(header) ? header[0] : header;
+                done(token === this.authToken, token === this.authToken ? undefined : 401, "Unauthorized");
+            },
+        });
+        this.wss.on("connection", (socket) => {
+            this.sockets.add(socket);
+            socket.on("close", () => this.sockets.delete(socket));
+            socket.on("error", () => this.sockets.delete(socket));
+            socket.on("message", (raw) => {
+                try {
+                    this.handleMessage(socket, decodeRawData(raw));
+                }
+                catch (error) {
+                    logExtensionError("IDE WebSocket server message", error);
+                    this.sockets.delete(socket);
+                    socket.close();
+                }
+            });
+        });
+        await new Promise((resolve, reject) => {
+            this.httpServer.once("error", reject);
+            this.httpServer.listen(0, "127.0.0.1", () => {
+                this.httpServer.off("error", reject);
+                resolve();
+            });
+        });
+        return this.port;
+    }
+    broadcast(value) {
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (error) {
+            logExtensionError("IDE WebSocket server broadcast serialization", error);
+            return;
+        }
+        for (const socket of this.openSockets)
+            this.sendText(socket, text, "broadcast");
+    }
+    sendToFirstClient(value) {
+        const [socket] = this.openSockets;
+        if (!socket)
+            return false;
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (error) {
+            logExtensionError("IDE WebSocket server send serialization", error);
+            return false;
+        }
+        return this.sendText(socket, text, "targeted send");
+    }
+    async stop() {
+        for (const socket of this.sockets)
+            socket.close();
+        this.sockets.clear();
+        await Promise.all([
+            new Promise((resolve) => this.wss?.close(() => resolve()) ?? resolve()),
+            new Promise((resolve) => this.httpServer?.close(() => resolve()) ?? resolve()),
+        ]);
+    }
+    handleMessage(socket, text) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (!isJsonRpcRequest(parsed))
+            return;
+        if (parsed.method !== "initialize")
+            return;
+        const ide = this.serverInfo.ide ?? "vscode";
+        const result = {
+            protocolVersion: PROTOCOL_VERSION,
+            server: {
+                name: this.serverInfo.name,
+                version: this.serverInfo.version,
+                ide,
+            },
+        };
+        this.sendValue(socket, { jsonrpc: "2.0", id: parsed.id, result }, "initialize response");
+        const snapshot = this.getInitialSelection?.();
+        this.sendValue(socket, {
+            jsonrpc: "2.0",
+            method: snapshot ? "selection_changed" : "selection_cleared",
+            params: snapshot
+                ? {
+                    ...snapshot,
+                    receivedAt: Date.now(),
+                }
+                : {
+                    source: ide,
+                    reason: "no-active-editor",
+                    receivedAt: Date.now(),
+                },
+        }, "initial selection");
+    }
+    sendValue(socket, value, label) {
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (error) {
+            logExtensionError(`IDE WebSocket server ${label} serialization`, error);
+            return false;
+        }
+        return this.sendText(socket, text, label);
+    }
+    sendText(socket, text, label) {
+        try {
+            socket.send(text, (error) => {
+                if (!error)
+                    return;
+                logExtensionError(`IDE WebSocket server ${label}`, error);
+                this.sockets.delete(socket);
+                socket.close();
+            });
+            return true;
+        }
+        catch (error) {
+            logExtensionError(`IDE WebSocket server ${label}`, error);
+            this.sockets.delete(socket);
+            socket.close();
+            return false;
+        }
+    }
+    get openSockets() {
+        return [...this.sockets].filter((socket) => socket.readyState === WebSocket.OPEN);
+    }
+}

package/dist/src/shared/jsonrpc-guard.js

@@ -0,0 +1,12 @@
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+export function isJsonRpcRequest(value) {
+    return (isRecord(value) &&
+        value.jsonrpc === "2.0" &&
+        (typeof value.id === "string" || isFiniteNumber(value.id)) &&
+        typeof value.method === "string");
+}

package/dist/src/shared/lock-file-heartbeat.js

@@ -0,0 +1,58 @@
+export const LOCK_FILE_HEARTBEAT_INTERVAL_MS = 15 * 60 * 1000;
+export function startLockFileHeartbeat(refresh, options = {}) {
+    const intervalMs = options.intervalMs ?? LOCK_FILE_HEARTBEAT_INTERVAL_MS;
+    let terminal = false;
+    let terminalPromise;
+    let pendingCount = 0;
+    let queueTail = Promise.resolve();
+    const contain = async (work) => {
+        try {
+            await work();
+        }
+        catch {
+        }
+    };
+    const runRefresh = async () => {
+        try {
+            await refresh();
+        }
+        catch (error) {
+            await contain(() => options.onError?.(error));
+        }
+    };
+    const accept = () => {
+        pendingCount += 1;
+        const request = queueTail.then(async () => {
+            try {
+                await runRefresh();
+            }
+            finally {
+                pendingCount -= 1;
+            }
+        });
+        queueTail = request;
+        return request;
+    };
+    const timer = setInterval(() => {
+        if (terminal || pendingCount > 0)
+            return;
+        void accept();
+    }, intervalMs);
+    timer.unref();
+    const handle = {
+        refreshNow() {
+            if (terminalPromise)
+                return terminalPromise;
+            return accept();
+        },
+        stop() {
+            if (!terminalPromise) {
+                terminal = true;
+                clearInterval(timer);
+                terminalPromise = queueTail;
+            }
+            return terminalPromise;
+        },
+    };
+    return handle;
+}