@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/agent/move.ts

@@ -0,0 +1,178 @@
+import { access, constants } from "node:fs";
+import { lstat, rename, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+import { promisify } from "node:util";
+import type { JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+import type { MutationStat } from "./delete.js";
+import { CODING_LOCAL_EFFECT } from "./effects.js";
+import type { ExecutionPolicy } from "./execution-policy.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import type { CodingLifecycleEvent } from "./lifecycle-events.js";
+import { resolveContainedMutationPath } from "./mutation-path.js";
+
+const accessAsync = promisify(access);
+
+export interface MoveOperations {
+  lstat: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<MutationStat>;
+  rename: (from: string, to: string, options?: { signal?: AbortSignal }) => Promise<void>;
+  unlink: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<void>;
+  access: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<void>;
+}
+
+export interface MoveToolOptions {
+  executionPolicy?: ExecutionPolicy;
+  operations?: MoveOperations;
+  /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+  onEvent?: (event: CodingLifecycleEvent) => void;
+}
+
+const defaultMoveOperations: MoveOperations = {
+  lstat: async (path) => {
+    const st = await lstat(path);
+    return {
+      isFile: () => st.isFile(),
+      isDirectory: () => st.isDirectory(),
+      isSymbolicLink: () => st.isSymbolicLink(),
+      size: st.size,
+    };
+  },
+  rename: (from, to) => rename(from, to).then(() => {}),
+  unlink: (path) => unlink(path).then(() => {}),
+  access: (path) => accessAsync(path, constants.F_OK),
+};
+
+function errorResult(toolCallId: string, message: string): ToolResult {
+  return {
+    toolCallId,
+    name: "move",
+    content: [{ type: "text", text: message }],
+    error: { message },
+  };
+}
+
+async function withDualFileMutationQueue<T>(pathA: string, pathB: string, fn: () => Promise<T>): Promise<T> {
+  const [first, second] = pathA <= pathB ? [pathA, pathB] : [pathB, pathA];
+  return withFileMutationQueue(first, () => withFileMutationQueue(second, fn));
+}
+
+export function createMoveTool(cwd: string, options?: MoveToolOptions): ToolDefinition {
+  const ops = options?.operations ?? defaultMoveOperations;
+
+  return {
+    name: "move",
+    kind: "move",
+    effect: CODING_LOCAL_EFFECT,
+    effects: ["write"],
+    description:
+      "High-risk: move or rename a file within the workspace. Set overwrite=true to replace an existing destination file only (directories/non-empty dest rejected). Does not create parent directories. No trash — host undo is not automatic.",
+    parameters: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Source path (relative or absolute)" },
+        to: { type: "string", description: "Destination path (relative or absolute)" },
+        overwrite: {
+          type: "boolean",
+          description: "Replace an existing destination file when true (default false).",
+        },
+      },
+      required: ["from", "to"],
+      additionalProperties: false,
+    } as JsonObject,
+    async execute(args, context: ToolExecutionContext): Promise<ToolResult> {
+      const toolCallId = context.toolCallId;
+      const from = typeof args.from === "string" ? args.from : "";
+      const to = typeof args.to === "string" ? args.to : "";
+      const overwrite = args.overwrite === true;
+
+      if (from.length === 0) return errorResult(toolCallId, "from is required and must be a non-empty string.");
+      if (to.length === 0) return errorResult(toolCallId, "to is required and must be a non-empty string.");
+
+      try {
+        let fromPath: string;
+        try {
+          fromPath = await resolveContainedMutationPath(cwd, from);
+        } catch (error) {
+          const err = error as NodeJS.ErrnoException;
+          if (err.code === "ENOENT") return errorResult(toolCallId, `Source does not exist: ${from}`);
+          throw error;
+        }
+        const toPath = await resolveContainedMutationPath(cwd, to, { allowMissing: true });
+
+        const policyCheck = await enforceExecutionPolicy(
+          options?.executionPolicy,
+          {
+            kind: "move",
+            operation: "move",
+            paths: [fromPath, toPath],
+            risk: "high",
+            metadata: { overwrite, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+          },
+          toolCallId,
+          "move",
+          (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }),
+        );
+        if (!policyCheck.allowed) return policyCheck.result;
+        const allowedFrom = policyCheck.action.paths?.[0] ?? fromPath;
+        const allowedTo = policyCheck.action.paths?.[1] ?? toPath;
+
+        return await withDualFileMutationQueue(allowedFrom, allowedTo, async () => {
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+          let fromStat: MutationStat;
+          try {
+            fromStat = await ops.lstat(allowedFrom, { signal: context.signal });
+          } catch (error) {
+            const err = error as NodeJS.ErrnoException;
+            if (err.code === "ENOENT") return errorResult(toolCallId, `Source does not exist: ${from}`);
+            const message = error instanceof Error ? error.message : String(error);
+            return errorResult(toolCallId, message);
+          }
+
+          const destParent = dirname(allowedTo);
+          try {
+            await ops.access(destParent, { signal: context.signal });
+          } catch {
+            return errorResult(toolCallId, `Destination parent directory does not exist: ${destParent}`);
+          }
+
+          let destStat: MutationStat | undefined;
+          try {
+            destStat = await ops.lstat(allowedTo, { signal: context.signal });
+          } catch (error) {
+            const err = error as NodeJS.ErrnoException;
+            if (err.code !== "ENOENT") {
+              const message = error instanceof Error ? error.message : String(error);
+              return errorResult(toolCallId, message);
+            }
+          }
+
+          if (destStat) {
+            if (!overwrite) return errorResult(toolCallId, `Destination already exists: ${to}. Pass overwrite=true to replace.`);
+            if (destStat.isDirectory()) return errorResult(toolCallId, `Destination is a directory: ${to}`);
+            await ops.unlink(allowedTo, { signal: context.signal });
+          }
+
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+          await ops.rename(allowedFrom, allowedTo, { signal: context.signal });
+          options?.onEvent?.({ type: "file_changed", path: allowedTo, op: "move", toolCallId });
+
+          return {
+            toolCallId,
+            name: "move",
+            content: [{ type: "text", text: `Successfully moved ${from} to ${allowedTo}` }],
+            metadata: {
+              from: allowedFrom,
+              to: allowedTo,
+              bytes: fromStat.isFile() ? fromStat.size : undefined,
+              overwrite,
+            },
+          };
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return errorResult(toolCallId, message);
+      }
+    },
+  };
+}

package/coding/src/agent/mutation-path.ts

@@ -0,0 +1,52 @@
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { resolveToCwd } from "./path-utils.js";
+
+function isPathInsideRoot(root: string, target: string): boolean {
+  const from = resolve(root);
+  const to = resolve(target);
+  if (to === from) return true;
+  const rel = relative(from, to);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    ((error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR")
+  );
+}
+
+/**
+ * Resolve a mutation target under `root`. Symlink paths are kept as the link
+ * location (not followed). Non-symlink existing paths are realpath'd.
+ */
+export async function resolveContainedMutationPath(root: string, inputPath: string, options?: { allowMissing?: boolean }): Promise<string> {
+  const rootResolved = resolve(root);
+  let rootReal: string;
+  try {
+    rootReal = await realpath(rootResolved);
+  } catch {
+    throw new Error(`workspace root is missing or unreadable: ${rootResolved}`);
+  }
+
+  const candidate = resolveToCwd(inputPath, rootReal);
+  if (!isPathInsideRoot(rootReal, candidate)) {
+    throw new Error(`path escapes workspace root: ${inputPath}`);
+  }
+
+  try {
+    const st = await lstat(candidate);
+    if (st.isSymbolicLink()) return candidate;
+    const real = await realpath(candidate);
+    if (!isPathInsideRoot(rootReal, real)) {
+      throw new Error(`path resolves outside workspace root: ${inputPath}`);
+    }
+    return real;
+  } catch (error) {
+    if (options?.allowMissing && isMissingPathError(error)) return candidate;
+    throw error;
+  }
+}

package/coding/src/agent/output-accumulator.ts

@@ -0,0 +1,304 @@
+/** Streaming UTF-8 output retention with bounded memory and spill storage. */
+import { randomBytes } from "node:crypto";
+import { closeSync, openSync, readSync, writeSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  DEFAULT_MAX_TOTAL_OUTPUT_BYTES,
+  HARD_MAX_BYTES,
+  HARD_MAX_LINES,
+  HARD_MAX_TOTAL_OUTPUT_BYTES,
+  validateCodingLimit,
+} from "./limits.js";
+import { type TruncationResult, truncateTail } from "./truncate.js";
+
+export interface OutputAccumulatorOptions {
+  maxLines?: number;
+  maxBytes?: number;
+  maxTotalOutputBytes?: number;
+  tempFilePrefix?: string;
+  onLimit?: () => void;
+  onStorageError?: () => void;
+}
+
+export interface OutputSnapshot {
+  content: string;
+  truncation: TruncationResult;
+  fullOutputPath?: string;
+}
+
+function defaultTempFilePath(prefix: string): string {
+  return join(tmpdir(), `${prefix}-${randomBytes(16).toString("hex")}.log`);
+}
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, "utf-8");
+}
+
+export class OutputAccumulator {
+  private readonly maxLines: number;
+  private readonly maxBytes: number;
+  private readonly maxTotalOutputBytes: number;
+  private readonly maxRollingBytes: number;
+  private readonly tempFilePrefix: string;
+  private readonly onLimit?: () => void;
+  private readonly onStorageError?: () => void;
+  private readonly decoder = new TextDecoder();
+  private rawChunks: Buffer[] = [];
+  private tailText = "";
+  private tailBytes = 0;
+  private tailStartsAtLineBoundary = true;
+  private totalRawBytes = 0;
+  private totalDecodedBytes = 0;
+  private completedLines = 0;
+  private totalLines = 0;
+  private currentLineBytes = 0;
+  private hasOpenLine = false;
+  private finished = false;
+  private exceeded = false;
+  private tempFilePath?: string;
+  private tempFileFd?: number;
+  private tempFileError?: Error;
+
+  constructor(options: OutputAccumulatorOptions = {}) {
+    this.maxLines = validateCodingLimit("maxLines", options.maxLines ?? DEFAULT_MAX_LINES, HARD_MAX_LINES);
+    this.maxBytes = validateCodingLimit("maxBytes", options.maxBytes ?? DEFAULT_MAX_BYTES, HARD_MAX_BYTES);
+    this.maxTotalOutputBytes = validateCodingLimit(
+      "maxTotalOutputBytes",
+      options.maxTotalOutputBytes ?? DEFAULT_MAX_TOTAL_OUTPUT_BYTES,
+      HARD_MAX_TOTAL_OUTPUT_BYTES,
+    );
+    if (this.maxTotalOutputBytes < this.maxBytes) {
+      throw new Error("maxTotalOutputBytes must be at least maxBytes");
+    }
+    this.maxRollingBytes = this.maxBytes * 2;
+    this.tempFilePrefix = options.tempFilePrefix ?? "prism-output";
+    if (!/^[A-Za-z0-9._-]+$/.test(this.tempFilePrefix)) {
+      throw new Error("tempFilePrefix may contain only letters, numbers, dot, underscore, and hyphen");
+    }
+    this.onLimit = options.onLimit;
+    this.onStorageError = options.onStorageError;
+  }
+
+  append(data: Buffer): boolean {
+    if (this.finished) throw new Error("Cannot append to a finished output accumulator");
+    const remaining = this.maxTotalOutputBytes - this.totalRawBytes;
+    const accepted = remaining > 0 ? data.subarray(0, remaining) : data.subarray(0, 0);
+    if (accepted.length > 0) {
+      this.totalRawBytes += accepted.length;
+      this.appendDecodedText(this.decoder.decode(accepted, { stream: true }));
+      if (this.tempFileFd !== undefined || this.shouldUseTempFile()) {
+        this.ensureTempFile();
+        this.writeTemp(accepted);
+      } else {
+        this.rawChunks.push(Buffer.from(accepted));
+      }
+    }
+    if (accepted.length !== data.length && !this.exceeded) {
+      this.exceeded = true;
+      this.onLimit?.();
+    }
+    return !this.exceeded;
+  }
+
+  finish(): void {
+    if (this.finished) return;
+    this.finished = true;
+    this.appendDecodedText(this.decoder.decode());
+    if (this.shouldUseTempFile()) this.ensureTempFile();
+  }
+
+  snapshot(options: { persistIfTruncated?: boolean } = {}): OutputSnapshot {
+    const tailTruncation = truncateTail(this.getSnapshotText(), {
+      maxLines: this.maxLines,
+      maxBytes: this.maxBytes,
+    });
+    const truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes || this.exceeded;
+    const truncation: TruncationResult = {
+      ...tailTruncation,
+      truncated,
+      truncatedBy: truncated
+        ? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes || this.exceeded ? "bytes" : "lines"))
+        : null,
+      totalLines: this.totalLines,
+      totalLinesKnown: true,
+      totalBytes: this.totalDecodedBytes,
+      totalBytesKnown: !this.exceeded,
+      maxLines: this.maxLines,
+      maxBytes: this.maxBytes,
+    };
+    if (options.persistIfTruncated && truncation.truncated) this.ensureTempFile();
+    return {
+      content: truncation.content,
+      truncation,
+      fullOutputPath: this.tempFileError ? undefined : this.tempFilePath,
+    };
+  }
+
+  async closeTempFile(): Promise<void> {
+    if (this.tempFileFd !== undefined) {
+      const fd = this.tempFileFd;
+      this.tempFileFd = undefined;
+      try {
+        closeSync(fd);
+      } catch (error) {
+        this.recordTempError(error);
+      }
+    }
+    if (this.tempFileError) throw this.tempFileError;
+  }
+
+  async cleanupTempFile(): Promise<void> {
+    const path = this.tempFilePath;
+    let closeError: unknown;
+    try {
+      await this.closeTempFile();
+    } catch (error) {
+      closeError = error;
+    }
+    this.tempFilePath = undefined;
+    this.tempFileError = undefined;
+    if (path) await rm(path, { force: true });
+    if (closeError) throw closeError;
+  }
+
+  getLastLineBytes(): number {
+    return this.currentLineBytes;
+  }
+
+  getTotalRawBytes(): number {
+    return this.totalRawBytes;
+  }
+
+  /**
+   * Cursor-paged raw bytes for process sessions.
+   * Reads from spill file when present, otherwise from in-memory chunks.
+   */
+  readRaw(cursor: number, maxBytes: number): { readonly data: Buffer; readonly nextCursor: number } {
+    if (!Number.isSafeInteger(cursor) || cursor < 0) {
+      throw new Error("cursor must be a non-negative safe integer");
+    }
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+      throw new Error("maxBytes must be a positive safe integer");
+    }
+    const total = this.totalRawBytes;
+    if (cursor >= total) return { data: Buffer.alloc(0), nextCursor: cursor };
+    const length = Math.min(maxBytes, total - cursor);
+    if (this.tempFilePath) {
+      const fd = openSync(this.tempFilePath, "r");
+      try {
+        const data = Buffer.alloc(length);
+        const n = readSync(fd, data, 0, length, cursor);
+        return { data: n === length ? data : data.subarray(0, n), nextCursor: cursor + n };
+      } finally {
+        closeSync(fd);
+      }
+    }
+    const data = Buffer.alloc(length);
+    let offset = 0;
+    let skipped = 0;
+    for (const chunk of this.rawChunks) {
+      if (offset >= length) break;
+      if (skipped + chunk.length <= cursor) {
+        skipped += chunk.length;
+        continue;
+      }
+      const start = Math.max(0, cursor - skipped);
+      const take = Math.min(chunk.length - start, length - offset);
+      chunk.copy(data, offset, start, start + take);
+      offset += take;
+      skipped += chunk.length;
+    }
+    return { data: offset === length ? data : data.subarray(0, offset), nextCursor: cursor + offset };
+  }
+
+  isOutputLimitExceeded(): boolean {
+    return this.exceeded;
+  }
+
+  hasStorageError(): boolean {
+    return this.tempFileError !== undefined;
+  }
+
+  private appendDecodedText(text: string): void {
+    if (text.length === 0) return;
+    const bytes = byteLength(text);
+    this.totalDecodedBytes += bytes;
+    this.tailText += text;
+    this.tailBytes += bytes;
+    if (this.tailBytes > this.maxRollingBytes * 2) this.trimTail();
+    let newlines = 0;
+    let lastNewline = -1;
+    for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) {
+      newlines++;
+      lastNewline = i;
+    }
+    if (newlines === 0) {
+      this.currentLineBytes += bytes;
+      this.hasOpenLine = true;
+    } else {
+      this.completedLines += newlines;
+      const tail = text.slice(lastNewline + 1);
+      this.currentLineBytes = byteLength(tail);
+      this.hasOpenLine = tail.length > 0;
+    }
+    this.totalLines = this.completedLines + (this.hasOpenLine ? 1 : 0);
+  }
+
+  private trimTail(): void {
+    const buffer = Buffer.from(this.tailText, "utf-8");
+    if (buffer.length <= this.maxRollingBytes) {
+      this.tailBytes = buffer.length;
+      return;
+    }
+    let start = buffer.length - this.maxRollingBytes;
+    while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) start++;
+    this.tailStartsAtLineBoundary = start === 0 ? this.tailStartsAtLineBoundary : buffer[start - 1] === 0x0a;
+    this.tailText = buffer.subarray(start).toString("utf-8");
+    this.tailBytes = byteLength(this.tailText);
+  }
+
+  private getSnapshotText(): string {
+    if (this.tailStartsAtLineBoundary) return this.tailText;
+    const firstNewline = this.tailText.indexOf("\n");
+    return firstNewline === -1 ? this.tailText : this.tailText.slice(firstNewline + 1);
+  }
+
+  private shouldUseTempFile(): boolean {
+    return this.totalRawBytes > this.maxBytes || this.totalDecodedBytes > this.maxBytes || this.totalLines > this.maxLines;
+  }
+
+  private ensureTempFile(): void {
+    if (this.tempFilePath || this.tempFileError) return;
+    const path = defaultTempFilePath(this.tempFilePrefix);
+    try {
+      this.tempFileFd = openSync(path, "wx", 0o600);
+      this.tempFilePath = path;
+      for (const chunk of this.rawChunks) this.writeTemp(chunk);
+    } catch (error) {
+      this.recordTempError(error);
+    } finally {
+      this.rawChunks = [];
+    }
+  }
+
+  private writeTemp(data: Buffer): void {
+    // ponytail: synchronous spill is zero-queue backpressure; use a bounded async writer only if measured throughput requires it.
+    if (this.tempFileFd === undefined || this.tempFileError) return;
+    try {
+      let offset = 0;
+      while (offset < data.length) offset += writeSync(this.tempFileFd, data, offset);
+    } catch (error) {
+      this.recordTempError(error);
+    }
+  }
+
+  private recordTempError(error: unknown): void {
+    if (this.tempFileError) return;
+    this.tempFileError = error instanceof Error ? error : new Error(String(error));
+    this.onStorageError?.();
+  }
+}

package/coding/src/agent/path-utils.ts

@@ -0,0 +1,120 @@
+/**
+ * Path resolution helpers.
+ *
+ * Behavioral port of pi's core/tools/path-utils for @arnilo/prism-tools/coding.
+ * stdlib only (node:fs, node:os, node:path, node:url). pi's version delegates
+ * homedir/tilde expansion to an internal utils/paths.js; that logic is inlined
+ * here as normalizePath/resolvePath so the package stays self-contained.
+ */
+import { accessSync, constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve as nodeResolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+const NARROW_NO_BREAK_SPACE = "\u202F";
+
+interface NormalizePathOptions {
+  trim?: boolean;
+  normalizeUnicodeSpaces?: boolean;
+  stripAtPrefix?: boolean;
+  expandTilde?: boolean;
+  homeDir?: string;
+}
+
+function normalizePath(input: string, options: NormalizePathOptions = {}): string {
+  let normalized = options.trim ? input.trim() : input;
+  if (options.normalizeUnicodeSpaces) {
+    normalized = normalized.replace(UNICODE_SPACES, " ");
+  }
+  if (options.stripAtPrefix && normalized.startsWith("@")) {
+    normalized = normalized.slice(1);
+  }
+  if (options.expandTilde ?? true) {
+    const home = options.homeDir ?? homedir();
+    if (normalized === "~") return home;
+    if (normalized.startsWith("~/") || (process.platform === "win32" && normalized.startsWith("~\\"))) {
+      return join(home, normalized.slice(2));
+    }
+  }
+  if (/^file:\/\//.test(normalized)) {
+    return fileURLToPath(normalized);
+  }
+  return normalized;
+}
+
+function resolvePath(input: string, baseDir: string = process.cwd(), options: NormalizePathOptions = {}): string {
+  const normalized = normalizePath(input, options);
+  const normalizedBaseDir = normalizePath(baseDir);
+  return isAbsolute(normalized) ? nodeResolve(normalized) : nodeResolve(normalizedBaseDir, normalized);
+}
+
+export async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function expandPath(filePath: string): string {
+  return normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+}
+
+/**
+ * Resolve a path relative to the given cwd. Handles ~ expansion and absolute paths.
+ */
+export function resolveToCwd(filePath: string, cwd: string): string {
+  return resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+}
+
+// macOS screenshot / NFD / curly-quote fallbacks for read paths.
+function tryMacOSScreenshotPath(filePath: string): string {
+  return filePath.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);
+}
+function tryNFDVariant(filePath: string): string {
+  // macOS stores filenames in NFD (decomposed) form; try converting user input to NFD.
+  return filePath.normalize("NFD");
+}
+function tryCurlyQuoteVariant(filePath: string): string {
+  // macOS uses U+2019 in screenshot names; users typically type a straight apostrophe.
+  return filePath.replace(/'/g, "\u2019");
+}
+function fileExists(filePath: string): boolean {
+  try {
+    accessSync(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveReadPath(filePath: string, cwd: string): string {
+  const resolved = resolveToCwd(filePath, cwd);
+  if (fileExists(resolved)) return resolved;
+  const amPmVariant = tryMacOSScreenshotPath(resolved);
+  if (amPmVariant !== resolved && fileExists(amPmVariant)) return amPmVariant;
+  const nfdVariant = tryNFDVariant(resolved);
+  if (nfdVariant !== resolved && fileExists(nfdVariant)) return nfdVariant;
+  const curlyVariant = tryCurlyQuoteVariant(resolved);
+  if (curlyVariant !== resolved && fileExists(curlyVariant)) return curlyVariant;
+  const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+  if (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) return nfdCurlyVariant;
+  return resolved;
+}
+
+export async function resolveReadPathAsync(filePath: string, cwd: string): Promise<string> {
+  const resolved = resolveToCwd(filePath, cwd);
+  if (await pathExists(resolved)) return resolved;
+  const amPmVariant = tryMacOSScreenshotPath(resolved);
+  if (amPmVariant !== resolved && (await pathExists(amPmVariant))) return amPmVariant;
+  const nfdVariant = tryNFDVariant(resolved);
+  if (nfdVariant !== resolved && (await pathExists(nfdVariant))) return nfdVariant;
+  const curlyVariant = tryCurlyQuoteVariant(resolved);
+  if (curlyVariant !== resolved && (await pathExists(curlyVariant))) return curlyVariant;
+  const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+  if (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant))) return nfdCurlyVariant;
+  return resolved;
+}