@narumitw/pi-files 0.0.0-stage → 0.1.0

package/src/file-context-preview-ui.ts

@@ -0,0 +1,354 @@
+import type { KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { ContentSearchMatch } from "./content-search.js";
+import { highlightContentRanges } from "./content-search-ui.js";
+import { safeTerminalText as safeHistoryText } from "./file-browser.js";
+import { bindingHint } from "./file-browser-ui.js";
+import type { LoadedProjectTextFile } from "./file-context.js";
+import type { GitBlameInfo, GitFileContext, GitHistoryEntry, GitProjectInfo, GitRevisionFile } from "./git-context.js";
+
+export interface SelectedContextState {
+  count: number;
+  totalBytes: number;
+  maximumCount: number;
+  maximumBytes: number;
+  maximumSnippetLines?: number;
+  maximumSnippetBytes?: number;
+}
+
+interface FilePreviewRenderOptions {
+  theme: Theme;
+  keybindings: KeybindingsManager;
+  width: number;
+  availableRows: number;
+  file: LoadedProjectTextFile;
+  fileGit?: GitFileContext;
+  project?: GitProjectInfo;
+  revision?: GitRevisionFile;
+  contentMatch?: ContentSearchMatch;
+  blame?: GitBlameInfo;
+  cursor: number;
+  anchor?: number;
+  scrollOffset: number;
+  error?: string;
+  selectedContext?: SelectedContextState;
+  canContinue: boolean;
+  canEdit: boolean;
+}
+
+export function renderFilePreview(options: FilePreviewRenderOptions): string[] {
+  const { file, theme, width } = options;
+  const range = selectionRange(options.anchor, options.cursor);
+  const selectedText = file.lines.slice(range.start, range.end + 1).join("\n");
+  const selectedBytes = Buffer.byteLength(selectedText, "utf8");
+  const estimatedTokens = Math.max(1, Math.ceil(selectedBytes / 4));
+  const externalEditorKey = bindingHint(options.keybindings, "app.editor.external", []);
+  const footer = options.error
+    ? { lines: [escapeTerminalControls(options.error)], primaryIndexes: [0] }
+    : previewFooterLines(
+        width,
+        range.start + 1,
+        range.end + 1,
+        estimatedTokens,
+        selectedBytes,
+        options.selectedContext,
+        options.canContinue,
+        options.canEdit ? externalEditorKey : "",
+      );
+  const previewHeight = Math.max(1, options.availableRows - 1 - (options.blame ? 1 : 0) - footer.lines.length);
+  const scrollOffset = visiblePreviewOffset(options.scrollOffset, options.cursor, previewHeight);
+  const digits = String(Math.max(1, file.lines.length)).length;
+  const changedLines = new Set(options.fileGit?.hunks.flatMap((hunk) => hunk.changedLines) ?? []);
+  const deletedAtLines = new Set(
+    (options.fileGit?.hunks ?? [])
+      .filter((hunk) => hunk.changedLines.length === 0 && hunk.oldCount > 0)
+      .map((hunk) => Math.max(1, hunk.newStart)),
+  );
+  const previewLines = file.lines.slice(scrollOffset, scrollOffset + previewHeight).map((rawLine, visibleIndex) => {
+    const index = scrollOffset + visibleIndex;
+    const selected = index >= range.start && index <= range.end;
+    const cursor = index === options.cursor ? ">" : " ";
+    const marker = changedLines.has(index + 1) ? "+" : deletedAtLines.has(index + 1) ? "-" : " ";
+    const number = String(index + 1).padStart(digits, " ");
+    const contentMatch =
+      options.contentMatch?.path === file.path &&
+      options.contentMatch.lineNumber === index + 1 &&
+      options.contentMatch.line === rawLine
+        ? options.contentMatch
+        : undefined;
+    const content = contentMatch
+      ? highlightContentRanges(rawLine, contentMatch.ranges, theme)
+      : escapeTerminalControls(rawLine);
+    const line = `${cursor}${marker}${number} │ ${content}`;
+    const styled = selected
+      ? theme.bg("selectedBg", theme.fg("text", line))
+      : index === options.cursor
+        ? theme.fg("accent", line)
+        : line;
+    return truncateToWidth(styled, width, "");
+  });
+  if (previewLines.length === 0) {
+    previewLines.push(truncateToWidth(theme.fg("muted", "  Empty file"), width, ""));
+  }
+  const gitLabel = options.revision
+    ? `${escapeTerminalControls(options.revision.revision)}@${options.revision.commit.slice(0, 12)} · historical`
+    : options.project
+      ? `${escapeTerminalControls(options.project.branch)}@${options.project.head.slice(0, 12)}${options.project.dirty ? " · dirty" : ""}${options.fileGit?.status ? ` · ${options.fileGit.status.label}` : " · clean"}`
+      : "";
+  const blameLabel = options.blame
+    ? `L${options.cursor + 1} · ${options.blame.committed ? options.blame.commit.slice(0, 12) : "uncommitted"} · ${escapeTerminalControls(options.blame.author)} · ${escapeTerminalControls(options.blame.summary)}`
+    : "";
+  const titleLine = truncateToWidth(
+    theme.fg("accent", theme.bold(`${escapeTerminalControls(file.path)}${gitLabel ? ` · ${gitLabel}` : ""}`)),
+    width,
+    "",
+  );
+  const blameLine = blameLabel ? truncateToWidth(theme.fg("muted", blameLabel), width, "") : undefined;
+  const renderedFooter = footer.lines.map((line) =>
+    truncateToWidth(theme.fg(options.error ? "error" : "muted", line), width, ""),
+  );
+  return fitPreviewRows(
+    titleLine,
+    blameLine,
+    previewLines,
+    renderedFooter,
+    footer.primaryIndexes,
+    options.availableRows,
+  );
+}
+
+export function renderFilePreviewHelp(
+  theme: Theme,
+  keybindings: KeybindingsManager,
+  width: number,
+  availableRows: number,
+  canEdit: boolean,
+): string[] {
+  const externalEditorKey = bindingHint(keybindings, "app.editor.external", []);
+  const editDetailed = canEdit
+    ? externalEditorKey
+      ? `${externalEditorKey.padEnd(6, " ")} Edit the current worktree file in the external editor`
+      : "Edit   External editor action is unbound"
+    : "Edit   Historical revisions are read-only";
+  const editCompact = canEdit
+    ? externalEditorKey
+      ? `${externalEditorKey} edit worktree`
+      : "External editor unbound"
+    : "Historical revision · read-only";
+  const detailed = [
+    theme.fg("accent", theme.bold("Preview actions")),
+    "Enter  Add selected lines and close File Context",
+    "A      Add selected lines and keep browsing",
+    "Space  Set or clear the range anchor; arrows extend the range",
+    "[ / ]  Select the previous or next changed hunk",
+    "B      Blame: show ownership for the current line when Git is available",
+    "H      History: browse earlier versions of this file",
+    "R      Revision: open a commit, branch, or tag",
+    "D      Git diff: review and add one explicit changed hunk",
+    editDetailed,
+    "Esc    Return to the preview without changing selected context",
+  ];
+  const compact = [
+    theme.fg("accent", theme.bold("Preview actions")),
+    "Enter add · A keep browsing · Space range",
+    "↑↓ extend · [/] hunk · B blame",
+    "H history · R revision · D Git diff",
+    editCompact,
+    "Esc back without changing context",
+  ];
+  const lines = availableRows < detailed.length ? compact : detailed;
+  return fitRows(
+    lines.map((line) => truncateToWidth(line, width, "")),
+    availableRows,
+  );
+}
+
+function previewFooterLines(
+  width: number,
+  startLine: number,
+  endLine: number,
+  tokens: number,
+  selectedBytes: number,
+  state: SelectedContextState | undefined,
+  canContinue: boolean,
+  externalEditorKey: string,
+): { lines: string[]; primaryIndexes: number[] } {
+  const nextCount = state ? state.count + 1 : undefined;
+  const nextBytes = state ? state.totalBytes + selectedBytes : undefined;
+  const selectedLines = endLine - startLine + 1;
+  const snippetOverLimit =
+    state !== undefined &&
+    ((state.maximumSnippetLines !== undefined && selectedLines > state.maximumSnippetLines) ||
+      (state.maximumSnippetBytes !== undefined && selectedBytes > state.maximumSnippetBytes));
+  const aggregateOverLimit =
+    state !== undefined &&
+    nextCount !== undefined &&
+    (nextCount > state.maximumCount || (nextBytes ?? 0) > state.maximumBytes);
+  const warning = snippetOverLimit
+    ? "Snippet limit exceeded"
+    : aggregateOverLimit
+      ? "Next prompt limit exceeded"
+      : undefined;
+  if (width < 74) {
+    const selection = `L${startLine}-${endLine} · ~${tokens} tok`;
+    const capacity = state ? (warning ?? `Next ${nextCount}/${state.maximumCount}`) : undefined;
+    const lines = [
+      [selection, capacity].filter(Boolean).join(" · "),
+      canContinue ? "Enter add · A keep browsing" : "Enter add & close",
+      "↑↓ move · Space range · Esc back",
+      [externalEditorKey ? `${externalEditorKey} edit` : "", "? actions"].filter(Boolean).join(" · "),
+      "B blame · H history · R revision",
+      "D diff · [/] hunk",
+    ];
+    return { lines, primaryIndexes: [1, 3] };
+  }
+  const selection = `Lines ${startLine}-${endLine} · ~${tokens} tokens`;
+  const capacity = state
+    ? snippetOverLimit
+      ? "Snippet limit exceeded; shorten the range before adding"
+      : aggregateOverLimit
+        ? "Next prompt limit exceeded; shorten the range or review selected context"
+        : `Next prompt: ${nextCount}/${state.maximumCount} snippets · ~${estimateTokens(nextBytes ?? 0)} tokens`
+    : undefined;
+  const primaryActions = canContinue
+    ? "Enter add & close · A add & continue · ↑↓ move · Space range · Esc back"
+    : "Enter add & close · ↑↓ move · Space range · Esc back";
+  const editActions = [externalEditorKey ? `${externalEditorKey} edit` : "", "? actions"].filter(Boolean).join(" · ");
+  return {
+    lines: [
+      [selection, capacity].filter(Boolean).join(" · "),
+      primaryActions,
+      editActions,
+      "B blame · H history · R revision · D diff · [/] hunk",
+    ],
+    primaryIndexes: [1, 2],
+  };
+}
+
+function selectionRange(anchor: number | undefined, cursor: number) {
+  const rangeAnchor = anchor ?? cursor;
+  return {
+    start: Math.min(rangeAnchor, cursor),
+    end: Math.max(rangeAnchor, cursor),
+  };
+}
+
+function visiblePreviewOffset(current: number, cursor: number, height: number): number {
+  if (cursor < current) return cursor;
+  if (cursor >= current + height) return cursor - height + 1;
+  return current;
+}
+
+function estimateTokens(bytes: number): number {
+  return bytes === 0 ? 0 : Math.max(1, Math.ceil(bytes / 4));
+}
+
+function fitPreviewRows(
+  title: string,
+  blame: string | undefined,
+  previewLines: readonly string[],
+  footerLines: readonly string[],
+  primaryFooterIndexes: readonly number[],
+  height: number,
+): string[] {
+  let visibleTitle: string | undefined = title;
+  let visibleBlame = blame;
+  const visiblePreview = [...previewLines];
+  const visibleFooter = footerLines.map((line, index) => ({
+    line,
+    primary: primaryFooterIndexes.includes(index),
+  }));
+  const rowCount = () => (visibleTitle ? 1 : 0) + (visibleBlame ? 1 : 0) + visiblePreview.length + visibleFooter.length;
+
+  while (rowCount() > height) {
+    if (visibleBlame) {
+      visibleBlame = undefined;
+      continue;
+    }
+    if (visiblePreview.length > 1) {
+      visiblePreview.pop();
+      continue;
+    }
+    let optionalFooter = -1;
+    for (let index = visibleFooter.length - 1; index >= 0; index -= 1) {
+      if (!visibleFooter[index]?.primary) {
+        optionalFooter = index;
+        break;
+      }
+    }
+    if (optionalFooter >= 0) {
+      visibleFooter.splice(optionalFooter, 1);
+      continue;
+    }
+    if (visibleTitle) {
+      visibleTitle = undefined;
+      continue;
+    }
+    if (visiblePreview.length > 0) {
+      visiblePreview.pop();
+      continue;
+    }
+    break;
+  }
+
+  return [
+    ...(visibleTitle ? [visibleTitle] : []),
+    ...(visibleBlame ? [visibleBlame] : []),
+    ...visiblePreview,
+    ...visibleFooter.map(({ line }) => line),
+  ];
+}
+
+export function fitRows(lines: string[], height: number): string[] {
+  if (lines.length <= height) return lines;
+  if (height <= 1) return lines.slice(0, 1);
+  return [...lines.slice(0, height - 1), lines.at(-1) ?? ""];
+}
+
+function escapeTerminalControls(text: string): string {
+  return [...text]
+    .map((character) => {
+      if (character === "\t") return "    ";
+      const code = character.charCodeAt(0);
+      if (code <= 31 || (code >= 127 && code <= 159)) {
+        return `\\x${code.toString(16).padStart(2, "0")}`;
+      }
+      return character;
+    })
+    .join("");
+}
+
+export function formatHistoryDate(authorTime: number): string {
+  const date = new Date(authorTime * 1_000);
+  return Number.isFinite(date.getTime()) ? date.toISOString().slice(0, 10) : "unknown-date";
+}
+
+export function renderFileHistory(options: {
+  width: number;
+  availableRows: number;
+  theme: Theme;
+  path: string;
+  history: readonly GitHistoryEntry[];
+  index: number;
+  error?: string;
+}): string[] {
+  const { width, availableRows, theme, history, index: selectedIndex, error } = options;
+  const listHeight = Math.max(1, availableRows - 3);
+  const title = theme.fg("accent", theme.bold(`File history · ${safeHistoryText(options.path)}`));
+  const start = Math.max(0, selectedIndex - listHeight + 1);
+  const entries = history.slice(start, start + listHeight).map((entry, visibleIndex) => {
+    const index = start + visibleIndex;
+    const prefix = index === selectedIndex ? "> " : "  ";
+    const date = formatHistoryDate(entry.authorTime);
+    const line = `${prefix}${entry.commit.slice(0, 12)} · ${date} · ${safeHistoryText(entry.author)} · ${safeHistoryText(entry.summary)}`;
+    return truncateToWidth(index === selectedIndex ? theme.bg("selectedBg", theme.fg("text", line)) : line, width, "");
+  });
+  if (entries.length === 0) {
+    entries.push(truncateToWidth(theme.fg("muted", "  No file history"), width, ""));
+  }
+  const footer = error ? safeHistoryText(error) : "↑↓ navigate · Enter open revision · Esc preview";
+  return fitRows(
+    [truncateToWidth(title, width, ""), ...entries, truncateToWidth(theme.fg("muted", footer), width, "")],
+    availableRows,
+  );
+}

package/src/file-context-settings.ts

@@ -0,0 +1,301 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+
+export const FILE_CONTEXT_SETTINGS_FILE = "pi-file-context.json";
+const MAX_SETTINGS_BYTES = 64 * 1024;
+
+export interface FileContextSettings {
+  openShortcut: KeyId | null;
+}
+
+export interface LoadedFileContextSettings {
+  settings: FileContextSettings;
+  warning?: string;
+  invalidReason?: string;
+}
+
+export interface UpdateFileContextSettingsOptions {
+  settingsPath?: string;
+  signal?: AbortSignal;
+  beforeRename?: (temporaryPath: string, settingsPath: string) => Promise<void>;
+}
+
+export const DEFAULT_FILE_CONTEXT_SETTINGS: FileContextSettings = {
+  openShortcut: "ctrl+shift+x",
+};
+
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+const BASE_KEYS = new Set([
+  ..."abcdefghijklmnopqrstuvwxyz0123456789",
+  "`",
+  "-",
+  "=",
+  "[",
+  "]",
+  "\\",
+  ";",
+  "'",
+  ",",
+  ".",
+  "/",
+  "!",
+  "@",
+  "#",
+  "$",
+  "%",
+  "^",
+  "&",
+  "*",
+  "(",
+  ")",
+  "_",
+  "+",
+  "|",
+  "~",
+  "{",
+  "}",
+  ":",
+  "<",
+  ">",
+  "?",
+  "escape",
+  "esc",
+  "enter",
+  "return",
+  "tab",
+  "space",
+  "backspace",
+  "delete",
+  "insert",
+  "clear",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "up",
+  "down",
+  "left",
+  "right",
+  ...Array.from({ length: 12 }, (_unused, index) => `f${index + 1}`),
+]);
+
+type SettingsDocument = Record<string, unknown>;
+type SettingsSnapshot =
+  | { kind: "missing" }
+  | { kind: "invalid"; reason: string; warning: string }
+  | { kind: "loaded"; document: SettingsDocument; settings: FileContextSettings };
+
+const mutationQueues = new Map<string, Promise<void>>();
+
+export function fileContextSettingsPath(): string {
+  return join(getAgentDir(), FILE_CONTEXT_SETTINGS_FILE);
+}
+
+export async function loadFileContextSettings(
+  settingsPath = fileContextSettingsPath(),
+): Promise<LoadedFileContextSettings> {
+  await awaitFileContextSettingsWrites(settingsPath);
+  const snapshot = await readSettingsSnapshot(settingsPath);
+  if (snapshot.kind === "loaded") return { settings: snapshot.settings };
+  if (snapshot.kind === "missing") {
+    return { settings: { ...DEFAULT_FILE_CONTEXT_SETTINGS } };
+  }
+  return {
+    settings: { ...DEFAULT_FILE_CONTEXT_SETTINGS },
+    warning: snapshot.warning,
+    invalidReason: snapshot.reason,
+  };
+}
+
+export function updateFileContextSettings(
+  openShortcut: KeyId | null,
+  options: UpdateFileContextSettingsOptions = {},
+): Promise<FileContextSettings> {
+  const settingsPath = options.settingsPath ?? fileContextSettingsPath();
+  return enqueueMutation(settingsPath, async () => {
+    options.signal?.throwIfAborted();
+    const snapshot = await readSettingsSnapshot(settingsPath);
+    if (snapshot.kind === "invalid") {
+      throw new Error(`File Context settings are invalid: ${snapshot.reason}`);
+    }
+    const updated: SettingsDocument = {
+      ...(snapshot.kind === "loaded" ? snapshot.document : {}),
+      openShortcut,
+    };
+    const settings = normalizeFileContextSettings(updated);
+    if (!settings) throw new Error("File Context settings update is invalid");
+    await publishSettings(settingsPath, updated, options);
+    return settings;
+  });
+}
+
+export async function awaitFileContextSettingsWrites(settingsPath = fileContextSettingsPath()): Promise<void> {
+  await mutationQueues.get(settingsPath);
+}
+
+export function normalizeKeyId(value: unknown): KeyId | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  const base = [...BASE_KEYS]
+    .sort((left, right) => right.length - left.length)
+    .find((candidate) => normalized === candidate || normalized.endsWith(`+${candidate}`));
+  if (!base) return undefined;
+  const prefix = normalized.slice(0, normalized.length - base.length);
+  if (!prefix) return base as KeyId;
+  if (/^f(?:[1-9]|1[0-2])$/.test(base) || !prefix.endsWith("+")) return undefined;
+  const modifiers = prefix.slice(0, -1).split("+");
+  if (
+    modifiers.length === 0 ||
+    modifiers.some((modifier) => !MODIFIERS.has(modifier)) ||
+    new Set(modifiers).size !== modifiers.length
+  ) {
+    return undefined;
+  }
+  return normalized as KeyId;
+}
+
+function normalizeFileContextSettings(value: unknown): FileContextSettings | undefined {
+  if (!isSettingsDocument(value)) return undefined;
+  if (!Object.hasOwn(value, "openShortcut")) {
+    return { ...DEFAULT_FILE_CONTEXT_SETTINGS };
+  }
+  const openShortcut = Reflect.get(value, "openShortcut");
+  if (openShortcut === null) return { openShortcut: null };
+  const normalized = normalizeKeyId(openShortcut);
+  return normalized ? { openShortcut: normalized } : undefined;
+}
+
+function enqueueMutation<T>(settingsPath: string, mutation: () => Promise<T>): Promise<T> {
+  const previous = mutationQueues.get(settingsPath) ?? Promise.resolve();
+  const result = previous.then(mutation, mutation);
+  const settled = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  mutationQueues.set(settingsPath, settled);
+  void settled.finally(() => {
+    if (mutationQueues.get(settingsPath) === settled) mutationQueues.delete(settingsPath);
+  });
+  return result;
+}
+
+async function readSettingsSnapshot(settingsPath: string): Promise<SettingsSnapshot> {
+  let source: string;
+  try {
+    source = await readSettingsContents(settingsPath);
+  } catch (error: unknown) {
+    if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
+    const reason = safeReadError(error);
+    return {
+      kind: "invalid",
+      reason,
+      warning: `Cannot read File Context settings: ${reason}`,
+    };
+  }
+
+  let document: unknown;
+  try {
+    document = JSON.parse(source) as unknown;
+  } catch (error: unknown) {
+    return {
+      kind: "invalid",
+      reason: "invalid JSON",
+      warning: `Cannot parse File Context settings: ${formatError(error)}`,
+    };
+  }
+  if (!isSettingsDocument(document)) {
+    return {
+      kind: "invalid",
+      reason: "settings must contain a JSON object",
+      warning: "File Context settings must contain a JSON object.",
+    };
+  }
+  const settings = normalizeFileContextSettings(document);
+  if (!settings) {
+    return {
+      kind: "invalid",
+      reason: 'setting "openShortcut" must be a valid Pi key string or null',
+      warning: 'File Context setting "openShortcut" must be a valid Pi key string or null.',
+    };
+  }
+  return { kind: "loaded", document, settings };
+}
+
+async function readSettingsContents(settingsPath: string): Promise<string> {
+  const flags = constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (constants.O_NOFOLLOW ?? 0);
+  const handle = await open(settingsPath, flags);
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) throw new Error("settings path is not a regular file");
+    if (stats.size > MAX_SETTINGS_BYTES) {
+      throw new Error(`settings file exceeds ${MAX_SETTINGS_BYTES} bytes`);
+    }
+    const buffer = Buffer.alloc(MAX_SETTINGS_BYTES + 1);
+    let offset = 0;
+    while (offset < buffer.byteLength) {
+      const { bytesRead } = await handle.read(buffer, offset, buffer.byteLength - offset, offset);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    if (offset > MAX_SETTINGS_BYTES) {
+      throw new Error(`settings file exceeds ${MAX_SETTINGS_BYTES} bytes`);
+    }
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, offset));
+    } catch {
+      throw new Error("settings file is not valid UTF-8");
+    }
+  } finally {
+    await handle.close();
+  }
+}
+
+async function publishSettings(
+  settingsPath: string,
+  document: SettingsDocument,
+  options: UpdateFileContextSettingsOptions,
+): Promise<void> {
+  options.signal?.throwIfAborted();
+  const contents = `${JSON.stringify(document, null, 2)}\n`;
+  if (Buffer.byteLength(contents, "utf8") > MAX_SETTINGS_BYTES) {
+    throw new Error(`settings document exceeds ${MAX_SETTINGS_BYTES} bytes`);
+  }
+  const directory = dirname(settingsPath);
+  await mkdir(directory, { recursive: true });
+  options.signal?.throwIfAborted();
+  const temporaryPath = join(directory, `.${basename(settingsPath)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, contents, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+      signal: options.signal,
+    });
+    await options.beforeRename?.(temporaryPath, settingsPath);
+    options.signal?.throwIfAborted();
+    await rename(temporaryPath, settingsPath);
+  } finally {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+  }
+}
+
+function isSettingsDocument(value: unknown): value is SettingsDocument {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}
+
+function safeReadError(error: unknown): string {
+  if (isNodeError(error) && error.code === "ELOOP") return "settings path is not a regular file";
+  return formatError(error);
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}