botholomew 0.12.3 → 0.13.0

package/src/fs/atomic.ts

@@ -0,0 +1,217 @@
+import { constants as fsConstants } from "node:fs";
+import {
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+  stat,
+  unlink,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+/**
+ * Write `content` to `targetPath` atomically: write to a sibling temp file,
+ * fsync, then rename. The rename is atomic on POSIX same-filesystem; the
+ * fsync ensures the file's bytes are durable before the rename commits.
+ *
+ * `tempSuffix` may be set to ensure two writers don't collide on a temp
+ * filename in the same directory (use the worker id for status updates).
+ */
+export async function atomicWrite(
+  targetPath: string,
+  content: string | Uint8Array,
+  opts: { tempSuffix?: string } = {},
+): Promise<void> {
+  await mkdir(dirname(targetPath), { recursive: true });
+  const suffix = opts.tempSuffix ?? `${process.pid}.${Date.now()}`;
+  const tmp = `${targetPath}.tmp.${suffix}`;
+  const fh = await open(tmp, "w", 0o644);
+  try {
+    if (typeof content === "string") {
+      await fh.writeFile(content, "utf-8");
+    } else {
+      await fh.writeFile(content);
+    }
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await rename(tmp, targetPath);
+}
+
+/**
+ * Read a file's contents along with its mtime in a single call so callers can
+ * detect concurrent modification before committing an update. Returns null if
+ * the file doesn't exist.
+ */
+export async function readWithMtime(
+  path: string,
+): Promise<{ content: string; mtimeMs: number } | null> {
+  let st: Awaited<ReturnType<typeof stat>>;
+  try {
+    st = await stat(path);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+  const content = await readFile(path, "utf-8");
+  return { content, mtimeMs: st.mtimeMs };
+}
+
+export class MtimeConflictError extends Error {
+  constructor(
+    readonly path: string,
+    readonly expectedMtimeMs: number,
+    readonly actualMtimeMs: number,
+  ) {
+    super(
+      `concurrent modification detected for ${path}: expected mtime ${expectedMtimeMs}, found ${actualMtimeMs}`,
+    );
+    this.name = "MtimeConflictError";
+  }
+}
+
+/**
+ * Atomic write guarded by mtime. Re-stats the target right before the rename
+ * commit; if it has changed since `expectedMtimeMs`, throws MtimeConflictError
+ * without touching the file. Use for read-modify-write of user-editable files
+ * (tasks, schedules) so a concurrent vim save doesn't get clobbered.
+ *
+ * A target that has been deleted between the caller's read and the rename
+ * is also a conflict (the row is gone — we must not silently resurrect it),
+ * so an ENOENT raises MtimeConflictError too.
+ */
+export async function atomicWriteIfUnchanged(
+  targetPath: string,
+  content: string,
+  expectedMtimeMs: number,
+  opts: { tempSuffix?: string } = {},
+): Promise<void> {
+  await mkdir(dirname(targetPath), { recursive: true });
+  const suffix = opts.tempSuffix ?? `${process.pid}.${Date.now()}`;
+  const tmp = `${targetPath}.tmp.${suffix}`;
+  const fh = await open(tmp, "w", 0o644);
+  try {
+    await fh.writeFile(content, "utf-8");
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  try {
+    const st = await stat(targetPath);
+    if (st.mtimeMs !== expectedMtimeMs) {
+      await unlink(tmp).catch(() => {});
+      throw new MtimeConflictError(targetPath, expectedMtimeMs, st.mtimeMs);
+    }
+  } catch (err) {
+    await unlink(tmp).catch(() => {});
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      // Target was deleted between the caller's read and our write. Refuse
+      // to resurrect it — this is a conflict, the same as a stale mtime.
+      throw new MtimeConflictError(targetPath, expectedMtimeMs, 0);
+    }
+    throw err;
+  }
+  await rename(tmp, targetPath);
+}
+
+export class LockHeldError extends Error {
+  constructor(
+    readonly lockPath: string,
+    readonly heldBy: string | null,
+  ) {
+    super(`lock ${lockPath} is held${heldBy ? ` by ${heldBy}` : ""}`);
+    this.name = "LockHeldError";
+  }
+}
+
+/**
+ * Acquire an exclusive lock by creating a sentinel file with O_EXCL. Returns
+ * the path to the lockfile (release with releaseLock). If another worker
+ * already holds the lock, throws LockHeldError including the holder's id.
+ *
+ * The lockfile body is JSON containing the workerId and acquired_at, useful
+ * for the reaper to identify dead-worker locks.
+ */
+export async function acquireLock(
+  lockPath: string,
+  workerId: string,
+): Promise<void> {
+  await mkdir(dirname(lockPath), { recursive: true });
+  const body = JSON.stringify({
+    worker_id: workerId,
+    acquired_at: new Date().toISOString(),
+    pid: process.pid,
+  });
+  let fh: Awaited<ReturnType<typeof open>>;
+  try {
+    fh = await open(
+      lockPath,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+      0o644,
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+      const heldBy = await readLockHolder(lockPath);
+      throw new LockHeldError(lockPath, heldBy);
+    }
+    throw err;
+  }
+  try {
+    await fh.writeFile(body, "utf-8");
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+}
+
+export async function readLockHolder(lockPath: string): Promise<string | null> {
+  try {
+    const text = await readFile(lockPath, "utf-8");
+    const parsed = JSON.parse(text);
+    return typeof parsed.worker_id === "string" ? parsed.worker_id : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function releaseLock(lockPath: string): Promise<void> {
+  try {
+    await unlink(lockPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+}
+
+/**
+ * Run `fn` while holding a lock. Releases the lock even if `fn` throws.
+ * Throws LockHeldError if the lock can't be acquired immediately.
+ */
+export async function withLock<T>(
+  lockPath: string,
+  workerId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  await acquireLock(lockPath, workerId);
+  try {
+    return await fn();
+  } finally {
+    await releaseLock(lockPath);
+  }
+}
+
+/**
+ * Recursively remove a directory if it exists. Used by init --force.
+ */
+export async function rmrf(path: string): Promise<void> {
+  await rm(path, { recursive: true, force: true });
+}
+
+/**
+ * Build an absolute path without going through the sandbox helper. Useful
+ * for internal (non-user-supplied) paths derived from constants.
+ */
+export function joinSafe(...parts: string[]): string {
+  return join(...parts);
+}

package/src/fs/compat.ts

@@ -0,0 +1,86 @@
+import { homedir, platform } from "node:os";
+import { resolve, sep } from "node:path";
+
+export type IncompatibleSync =
+  | "icloud"
+  | "dropbox"
+  | "google-drive"
+  | "onedrive";
+
+export interface FilesystemCompatIssue {
+  kind: IncompatibleSync;
+  detail: string;
+}
+
+/**
+ * Detect whether `projectDir` lives inside a sync-overlay filesystem where
+ * `rename` and `O_EXCL` semantics aren't reliable. These overlays can
+ * resurrect deleted files, double-sync writes, and conflict-rename, all of
+ * which break our claim/atomic-write model.
+ */
+export function detectIncompatibleFilesystem(
+  projectDir: string,
+): FilesystemCompatIssue | null {
+  const abs = resolve(projectDir);
+  const home = homedir();
+  const os = platform();
+
+  // macOS iCloud Drive
+  if (os === "darwin") {
+    const icloud = `${home}${sep}Library${sep}Mobile Documents`;
+    if (abs.startsWith(icloud + sep) || abs === icloud) {
+      return {
+        kind: "icloud",
+        detail: `path is inside iCloud Drive (${icloud})`,
+      };
+    }
+  }
+
+  // Dropbox (default location, varies; this is best-effort)
+  const dropbox = `${home}${sep}Dropbox`;
+  if (abs.startsWith(dropbox + sep) || abs === dropbox) {
+    return { kind: "dropbox", detail: `path is inside ${dropbox}` };
+  }
+
+  // Google Drive (macOS: ~/Library/CloudStorage/GoogleDrive-*; legacy: ~/Google Drive)
+  if (os === "darwin") {
+    const cloudStorage = `${home}${sep}Library${sep}CloudStorage`;
+    if (abs.startsWith(cloudStorage + sep)) {
+      return {
+        kind: "google-drive",
+        detail: `path is inside macOS CloudStorage (${cloudStorage})`,
+      };
+    }
+  }
+  const legacyGdrive = `${home}${sep}Google Drive`;
+  if (abs.startsWith(legacyGdrive + sep) || abs === legacyGdrive) {
+    return { kind: "google-drive", detail: `path is inside ${legacyGdrive}` };
+  }
+
+  // OneDrive
+  const onedrive = `${home}${sep}OneDrive`;
+  if (abs.startsWith(onedrive + sep) || abs === onedrive) {
+    return { kind: "onedrive", detail: `path is inside ${onedrive}` };
+  }
+
+  return null;
+}
+
+/**
+ * Throw a clear error when running in an incompatible filesystem unless
+ * `force` is set. Used by `init` and the worker bootstrap.
+ */
+export function assertCompatibleFilesystem(
+  projectDir: string,
+  force: boolean,
+): void {
+  const issue = detectIncompatibleFilesystem(projectDir);
+  if (!issue) return;
+  if (force) return;
+  throw new Error(
+    `Refusing to operate inside ${issue.kind}: ${issue.detail}.\n` +
+      `Sync-overlay filesystems can resurrect deleted files and break atomic ` +
+      `claim semantics, which Botholomew depends on for tasks and schedules.\n` +
+      `Move the project to a regular local directory, or pass --force to override.`,
+  );
+}

package/src/fs/sandbox.ts

@@ -0,0 +1,279 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { lstat } from "node:fs/promises";
+import { isAbsolute, normalize, resolve, sep } from "node:path";
+
+const MAX_PATH_LENGTH = 4096;
+
+export class PathEscapeError extends Error {
+  constructor(
+    message: string,
+    readonly userPath: string,
+    readonly resolvedPath?: string,
+  ) {
+    super(message);
+    this.name = "PathEscapeError";
+  }
+}
+
+export interface SandboxOptions {
+  /**
+   * Restrict the resolved path to a subtree of the root (e.g., "context").
+   * The area is appended to the canonical root and used as the containment
+   * boundary instead of the root itself.
+   */
+  area?: string;
+  /**
+   * Allow the resolved path to equal the root/area itself (for directory
+   * operations like list/tree). Default true.
+   */
+  allowRoot?: boolean;
+}
+
+let cachedCanonicalRoot: string | null = null;
+let cachedRawRoot: string | null = null;
+
+/**
+ * Resolve the project root once at startup so all subsequent containment
+ * checks compare against the canonical (symlink-followed) path. Idempotent
+ * per root.
+ */
+export function setCanonicalRoot(rawRoot: string): string {
+  if (cachedRawRoot === rawRoot && cachedCanonicalRoot) {
+    return cachedCanonicalRoot;
+  }
+  const canonical = realpathSync(rawRoot);
+  cachedRawRoot = rawRoot;
+  cachedCanonicalRoot = canonical;
+  return canonical;
+}
+
+export function getCanonicalRoot(rawRoot: string): string {
+  if (cachedRawRoot === rawRoot && cachedCanonicalRoot) {
+    return cachedCanonicalRoot;
+  }
+  return setCanonicalRoot(rawRoot);
+}
+
+/**
+ * Resolve a user-supplied path against the project root with traversal and
+ * symlink protection. Always use this for any path that an agent tool may
+ * touch — never `path.resolve` directly.
+ *
+ * Rules:
+ *  1. NUL bytes / overlong paths rejected.
+ *  2. Input is NFC-normalized so macOS NFD-after-vim doesn't desync the index.
+ *  3. After path.resolve, the result must be inside the (canonical) root or
+ *     `<root>/<area>`.
+ *  4. `..` components after normalization are rejected as defense in depth.
+ *  5. Every existing path component is `lstat`'d; any symlink is rejected.
+ *     Hardlinks are out of scope by design.
+ *
+ * Returns the absolute, canonical path safe to pass to fs APIs.
+ */
+export async function resolveInRoot(
+  rawRoot: string,
+  userPath: string,
+  opts: SandboxOptions = {},
+): Promise<string> {
+  validateUserPath(userPath);
+  const normalized = userPath.normalize("NFC");
+
+  const canonicalRoot = getCanonicalRoot(rawRoot);
+  const boundary = opts.area
+    ? resolve(canonicalRoot, opts.area)
+    : canonicalRoot;
+
+  const resolved = resolve(boundary, normalized);
+  ensureContainment(resolved, boundary, opts.allowRoot ?? true, userPath);
+
+  await assertNoSymlinkComponents(resolved, canonicalRoot);
+  return resolved;
+}
+
+/**
+ * Synchronous variant for callers that can't use async (rare). Same semantics.
+ */
+export function resolveInRootSync(
+  rawRoot: string,
+  userPath: string,
+  opts: SandboxOptions = {},
+): string {
+  validateUserPath(userPath);
+  const normalized = userPath.normalize("NFC");
+
+  const canonicalRoot = getCanonicalRoot(rawRoot);
+  const boundary = opts.area
+    ? resolve(canonicalRoot, opts.area)
+    : canonicalRoot;
+
+  const resolved = resolve(boundary, normalized);
+  ensureContainment(resolved, boundary, opts.allowRoot ?? true, userPath);
+
+  assertNoSymlinkComponentsSync(resolved, canonicalRoot);
+  return resolved;
+}
+
+function validateUserPath(userPath: string): void {
+  if (typeof userPath !== "string") {
+    throw new PathEscapeError("path must be a string", String(userPath));
+  }
+  if (userPath.includes("\0")) {
+    throw new PathEscapeError("path contains NUL byte", userPath);
+  }
+  if (userPath.length > MAX_PATH_LENGTH) {
+    throw new PathEscapeError(
+      `path exceeds maximum length (${MAX_PATH_LENGTH})`,
+      userPath,
+    );
+  }
+}
+
+function ensureContainment(
+  resolved: string,
+  boundary: string,
+  allowRoot: boolean,
+  userPath: string,
+): void {
+  if (resolved === boundary) {
+    if (!allowRoot) {
+      throw new PathEscapeError(
+        "path resolves to the area root",
+        userPath,
+        resolved,
+      );
+    }
+    return;
+  }
+  if (!resolved.startsWith(boundary + sep)) {
+    throw new PathEscapeError(
+      `path escapes project root: ${userPath}`,
+      userPath,
+      resolved,
+    );
+  }
+  // Defense in depth: even a successful prefix check shouldn't pass a `..`
+  // segment after normalization. (path.resolve collapses these, but we double
+  // check in case the normalize step introduces one.)
+  const rel = resolved.slice(boundary.length + 1);
+  if (rel.split(sep).some((seg) => seg === ".." || seg === "." || seg === "")) {
+    throw new PathEscapeError(
+      `path contains forbidden component: ${userPath}`,
+      userPath,
+      resolved,
+    );
+  }
+}
+
+async function assertNoSymlinkComponents(
+  resolved: string,
+  canonicalRoot: string,
+): Promise<void> {
+  // Walk from canonical root toward the leaf, lstat'ing each existing
+  // component. The root itself is canonical (already realpath'd) so we skip
+  // it; we only care that nothing the agent writes goes through a symlink.
+  const rel = resolved.slice(canonicalRoot.length);
+  if (!rel || rel === sep) return;
+  const parts = rel.split(sep).filter((p) => p.length > 0);
+  let current = canonicalRoot;
+  for (const part of parts) {
+    current = current + sep + part;
+    try {
+      const st = await lstat(current);
+      if (st.isSymbolicLink()) {
+        throw new PathEscapeError(
+          `path traverses a symlink: ${current}`,
+          resolved,
+          current,
+        );
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        // Component doesn't exist yet — nothing to verify, and the create
+        // call that follows will be performed within an already-vetted parent.
+        return;
+      }
+      throw err;
+    }
+  }
+}
+
+function assertNoSymlinkComponentsSync(
+  resolved: string,
+  canonicalRoot: string,
+): void {
+  const rel = resolved.slice(canonicalRoot.length);
+  if (!rel || rel === sep) return;
+  const parts = rel.split(sep).filter((p) => p.length > 0);
+  let current = canonicalRoot;
+  for (const part of parts) {
+    current = current + sep + part;
+    try {
+      const st = lstatSync(current);
+      if (st.isSymbolicLink()) {
+        throw new PathEscapeError(
+          `path traverses a symlink: ${current}`,
+          resolved,
+          current,
+        );
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw err;
+    }
+  }
+}
+
+/**
+ * Convert an absolute resolved path back to a project-relative path (with
+ * forward slashes, suitable for display and storage).
+ */
+export function toRelativePath(
+  rawRoot: string,
+  absolute: string,
+  area?: string,
+): string {
+  const canonicalRoot = getCanonicalRoot(rawRoot);
+  const boundary = area ? resolve(canonicalRoot, area) : canonicalRoot;
+  if (absolute === boundary) return "";
+  if (!absolute.startsWith(boundary + sep)) {
+    throw new PathEscapeError(
+      `path is outside ${area ?? "root"}`,
+      absolute,
+      absolute,
+    );
+  }
+  return absolute
+    .slice(boundary.length + 1)
+    .split(sep)
+    .join("/");
+}
+
+/**
+ * Reject absolute paths and obvious traversal at the API boundary so error
+ * messages are clear (vs. relying on the resolver to also catch them).
+ */
+export function assertRelative(userPath: string): void {
+  if (typeof userPath !== "string" || userPath.length === 0) {
+    throw new PathEscapeError("path is required", String(userPath));
+  }
+  if (isAbsolute(userPath)) {
+    throw new PathEscapeError(
+      `path must be project-relative, not absolute: ${userPath}`,
+      userPath,
+    );
+  }
+  const norm = normalize(userPath);
+  if (
+    norm === ".." ||
+    norm.startsWith(`..${sep}`) ||
+    norm.includes(`${sep}..${sep}`)
+  ) {
+    throw new PathEscapeError(`path escapes project: ${userPath}`, userPath);
+  }
+}
+
+/** For tests: clear cached canonical root so fresh setup() calls resolve fresh. */
+export function _resetSandboxCacheForTests(): void {
+  cachedCanonicalRoot = null;
+  cachedRawRoot = null;
+}