fs.ts

/**
 * GRIDA-SEC-004 — workspace file I/O helpers.
 *
 * Owns guarded file operations for an already-opened workspace. The
 * registry owns which roots are opened; this module owns containment,
 * text/binary policy, and atomic writes inside those roots.
 */

import fs from "node:fs/promises";
import {
  constants as fsConstants,
  type Dirent,
  type ReadStream as NodeReadStream,
} from "node:fs";
import path from "node:path";
import { atomicWrite } from "../storage/atomic-write";

// ─────────────────────────── workspace fs ───────────────────────────
/**
 * GRIDA-SEC-004 — workspace file I/O helpers.
 *
 * The client talks in `{workspaceId, relPath}` (NOT absolute paths)
 * for everything in `/workspaces/{readdir,readfile,writefile}`. We
 * resolve `relPath` against the workspace's `root` (which is itself
 * already-`realpath`'d by `WorkspaceRegistry.open`), then verify the
 * resulting absolute path is contained within the workspace.
 *
 * Containment is enforced twice for reads:
 *   1. After `path.resolve`, before touching disk — catches the
 *      easy `../../etc/passwd` case immediately, no fs round trip.
 *   2. After `fs.realpath` on the final target — catches the symlink
 *      case where the target's literal path looks fine but follows
 *      out of the workspace.
 *
 * Writes follow the same atomic temp-file + rename discipline as
 * `auth.json` / `recent.json` (same directory as target, randomized
 * name, mode 0o600, then rename).
 *
 * The "shell.run cwd must be inside a workspace" gate from `shell/`
 * uses the same `containsPath` semantics — kept consistent so a
 * relative path that's safe to read is also safe to spawn into.
 */

export namespace workspaceFs {
  /** Hard cap on a single read/write. Larger files surface as an error
   * rather than silently allocating tens of MB of buffer + JSON-encoded
   * string. The client is supposed to be reading source files —
   * 1 MiB is plenty for that, and binary blobs (PNGs, fonts, etc.) get
   * sensibly rejected as a side effect. */
  export const MAX_FILE_BYTES = 1_048_576; // 1 MiB

  /**
   * A containment scope for the agent's file I/O: a real directory `root` plus
   * an `id` used only in error detail. This module is "containment-checked I/O
   * over a root" — NOT tied to the workspace registry. A registered
   * `Workspace` is one scope (the user's project); the per-session scratch dir
   * is another. Modeling reach as a scope (not a Workspace) is what lets the
   * fs tools and the shell share ONE notion of where the agent may read/write,
   * instead of each defining it separately (the bug this generalization fixes:
   * scratch was reachable by the shell but invisible to read_file/view_image).
   */
  export type Scope = { id: string; root: string };

  export type ErrorCode =
    | "workspace-not-found"
    | "path-not-relative"
    | "path-contains-null"
    | "path-escapes-workspace"
    | "not-a-directory"
    | "not-a-file"
    | "file-too-large"
    | "file-not-utf8"
    | "modified-since";

  export type ErrorDetail = {
    code: ErrorCode;
    workspace_id?: string;
    rel_path?: string;
    size?: number;
    /**
     * Current on-disk mtime, set on `modified-since` so the client can
     * reconcile (reload / overwrite-with-this-as-the-new-baseline)
     * without a second round trip. Omitted when the expected file is
     * gone on disk (deleted out from under the caller).
     */
    mtime?: number;
  };

  /**
   * Thrown by {@link readDir}, {@link readFile}, {@link writeFile}, etc.
   * on any structured failure (path escape, not-a-directory, etc.). The
   * route handler translates these into 4xx JSON responses.
   *
   * ENOENT / EACCES from the underlying fs calls intentionally propagate
   * as plain Node errors so the route can surface them as 404 / 403 —
   * the structured codes above are reserved for daemon-policy failures
   * (escape attempts, oversized files, non-text content), not for raw
   * OS errors.
   */
  export class Exception extends Error {
    constructor(public readonly detail: ErrorDetail) {
      super(detail.code);
      this.name = "WorkspaceFsException";
    }
  }

  export type Entry = {
    /** basename of the entry. */
    name: string;
    /** Relative path from workspace root, posix-style separators. */
    rel_path: string;
    kind: "file" | "directory" | "symlink" | "other";
  };

  /**
   * Lists immediate children of `relPath` inside `workspace`. Empty
   * `relPath` lists the workspace root.
   *
   * Sort: directories first, then files, both alphabetical
   * case-insensitive. Useful dotfiles remain visible (`.gitignore`,
   * `.env.example`, `.vscode`, etc.); narrow OS and VCS implementation
   * metadata is omitted from every listing. Direct reads by an explicit
   * relative path remain available.
   *
   * Symlinks are reported with `kind: 'symlink'` and a best-effort
   * target classification — clicking them in the tree is allowed but
   * the read call will re-verify containment of the realpath'd target,
   * so a symlink to `/etc/passwd` shows up in the listing but fails on
   * open.
   */
  export async function readDir(
    workspace: workspaceFs.Scope,
    relPath: string
  ): Promise<Entry[]> {
    const abs = await resolveInside(workspace, relPath, { must_exist: true });
    // No pre-stat — readdir itself surfaces ENOTDIR on a regular-file
    // target, so the stat would just be a redundant syscall + TOCTOU
    // window. Translate the error so the route still emits our
    // structured 4xx code.
    let dirents;
    try {
      dirents = await fs.readdir(abs, { withFileTypes: true });
    } catch (err) {
      if ((err as NodeJS.ErrnoException | undefined)?.code === "ENOTDIR") {
        throw new Exception({
          code: "not-a-directory",
          workspace_id: workspace.id,
          rel_path: relPath,
        });
      }
      throw err;
    }
    const entries = dirents
      .filter((dirent) => isListableEntry(dirent.name))
      .map((dirent) => directoryEntry(relPath, dirent));
    entries.sort((a, b) => {
      if (a.kind === "directory" && b.kind !== "directory") return -1;
      if (b.kind === "directory" && a.kind !== "directory") return 1;
      return a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
    });
    return entries;
  }

  /**
   * Lazily iterate immediate children of `relPath` without materializing the
   * entire directory. This is the bounded-traversal sibling of {@link readDir}:
   * callers that may stop after a work budget should use `for await`, whose
   * early exit runs this generator's `finally` and closes the OS directory
   * handle. Ordering is the filesystem's native enumeration order; callers
   * that require the sorted UI shape should continue to use {@link readDir}.
   *
   * The same GRIDA-SEC-004 containment and ENOTDIR translation apply before
   * any entry is yielded. Raw ENOENT/EACCES errors retain the existing
   * workspaceFs contract and propagate to the owning caller.
   */
  export async function* iterateDir(
    workspace: workspaceFs.Scope,
    relPath: string
  ): AsyncGenerator<Entry, void, void> {
    const abs = await resolveInside(workspace, relPath, { must_exist: true });
    const dir = await (async () => {
      try {
        return await fs.opendir(abs);
      } catch (err) {
        if ((err as NodeJS.ErrnoException | undefined)?.code === "ENOTDIR") {
          throw new Exception({
            code: "not-a-directory",
            workspace_id: workspace.id,
            rel_path: relPath,
          });
        }
        throw err;
      }
    })();

    try {
      while (true) {
        const dirent = await dir.read();
        if (dirent === null) return;
        if (!isListableEntry(dirent.name)) continue;
        yield directoryEntry(relPath, dirent);
      }
    } finally {
      try {
        await dir.close();
      } catch (err) {
        // A consumer can explicitly close a handle it obtained through
        // instrumentation; otherwise this generator is its sole owner.
        if (
          (err as NodeJS.ErrnoException | undefined)?.code !== "ERR_DIR_CLOSED"
        ) {
          // Do not let a close failure replace the traversal error/return that
          // led here, and never log the raw error (it may name the host path).
          console.warn("[workspace-fs] directory iterator close failed");
        }
      }
    }
  }

  /**
   * Read a file's contents as UTF-8 text. Rejects files larger than
   * MAX_FILE_BYTES and files whose bytes don't round-trip through UTF-8
   * (i.e. binary).
   *
   * Returning a binary-detection error rather than the lossy
   * `replacement-char`-replaced text is intentional: the client wants
   * to tell the user "this is a binary file, I can't show it" and offer
   * a different affordance, not display gibberish.
   */
  export async function readFile(
    workspace: workspaceFs.Scope,
    relPath: string
  ): Promise<{ content: string; mtime: number }> {
    const abs = await resolveInside(workspace, relPath, { must_exist: true });
    const stat = await fs.stat(abs);
    if (!stat.isFile()) {
      throw new Exception({
        code: "not-a-file",
        workspace_id: workspace.id,
        rel_path: relPath,
      });
    }
    if (stat.size > MAX_FILE_BYTES) {
      throw new Exception({
        code: "file-too-large",
        workspace_id: workspace.id,
        rel_path: relPath,
        size: stat.size,
      });
    }
    const buf = await fs.readFile(abs);
    // Binary detection: a null byte in the first 8 KiB is a reliable
    // heuristic for non-text content. The encoder round-trip would
    // catch the rest, but null-byte short-circuits the common case
    // (executables, images, archives).
    const head = buf.subarray(0, Math.min(buf.length, 8192));
    for (const byte of head) {
      if (byte === 0) {
        throw new Exception({
          code: "file-not-utf8",
          workspace_id: workspace.id,
          rel_path: relPath,
        });
      }
    }
    const decoder = new TextDecoder("utf-8", { fatal: true });
    let content: string;
    try {
      content = decoder.decode(buf);
    } catch {
      throw new Exception({
        code: "file-not-utf8",
        workspace_id: workspace.id,
        rel_path: relPath,
      });
    }
    return { content, mtime: stat.mtimeMs };
  }

  /**
   * Read `relPath` as opaque bytes, returning the contents base64-
   * encoded along with size + mtime.
   *
   * Companion to `readFile` for the read-only image viewer: that path
   * deliberately refuses non-UTF-8 content (so a tab opening an
   * executable doesn't paint garbage), but the client DOES want
   * images. Keeping these on separate routes preserves the
   * "text-only → reject binary" guarantee of `readFile` while giving
   * known-safe content types (PNG/JPG/WebP/etc.) a path to the
   * client.
   *
   * The 1 MiB source-text cap remains the default. Callers that intentionally
   * buffer binary resources must provide their own finite budget; for example,
   * the Desktop `/workspaces/readfilebytes` route and agent image inspection
   * allow ordinary multi-MiB images. Streamed viewers use {@link openFile}
   * instead of raising this indefinitely.
   *
   * Mime detection lives on the client side: this function is
   * deliberately content-agnostic. The route fans out to whichever
   * viewer the client dispatches based on extension.
   */
  export async function readFileBytes(
    workspace: workspaceFs.Scope,
    relPath: string,
    opts?: { max_bytes?: number }
  ): Promise<{ base64: string; size: number; mtime: number }> {
    // The 1 MiB default suits source-file reads. Callers that legitimately
    // buffer larger binaries must opt into a bounded, caller-owned budget.
    const maxBytes = opts?.max_bytes ?? MAX_FILE_BYTES;
    const abs = await resolveInside(workspace, relPath, { must_exist: true });
    const stat = await fs.stat(abs);
    if (!stat.isFile()) {
      throw new Exception({
        code: "not-a-file",
        workspace_id: workspace.id,
        rel_path: relPath,
      });
    }
    if (stat.size > maxBytes) {
      throw new Exception({
        code: "file-too-large",
        workspace_id: workspace.id,
        rel_path: relPath,
        size: stat.size,
      });
    }
    const buf = await fs.readFile(abs);
    return {
      base64: buf.toString("base64"),
      size: stat.size,
      mtime: stat.mtimeMs,
    };
  }

  /**
   * Open a regular file inside the workspace for streamed reads (#924),
   * pinned to a contained file descriptor. Resolves containment ONCE
   * (one `realpath`), opens an `O_NOFOLLOW` handle, and returns the file's
   * `size`/`mtime` (from `fstat` on THAT handle) plus a `stream` factory over
   * the same handle. The media route needs the size up front (to validate a
   * Range header and set Content-Length/Content-Range) and then a byte stream
   * — folding both into one handle avoids a second containment resolve per
   * request (a seeking `<video>` fires a Range request per skip) AND closes the
   * realpath→read TOCTOU: `resolveInside` validates the path, but a local
   * writer could then swap the regular file for a symlink to an outside target.
   * Opening `O_NOFOLLOW` refuses a final-component symlink planted after the
   * check (same defense as scratch writes), and we fstat + stream from the held
   * handle, so the bytes come from the exact inode we validated — not whatever
   * now lives at the path. This matters more here than on the 1 MiB buffered
   * readers because the stream is uncapped.
   *
   * The factory's `start`/`end` are INCLUSIVE byte offsets (Node
   * `createReadStream` semantics); the route owns Range math and clamps them
   * against `size`. The returned stream's `autoClose` (default) closes the
   * handle on end/error/abort; a caller that takes `size`/`mtime` but never
   * streams (e.g. an empty file, or a 416) MUST call `close()`. Throws
   * `not-a-file` for non-regular targets.
   */
  export async function openFile(
    workspace: workspaceFs.Scope,
    relPath: string
  ): Promise<{
    size: number;
    mtime: number;
    stream: (opts?: { start?: number; end?: number }) => NodeReadStream;
    close: () => Promise<void>;
  }> {
    const abs = await resolveInside(workspace, relPath, { must_exist: true });
    // O_NOFOLLOW (0 where unsupported, e.g. Windows) → a final-component symlink
    // swapped in after `resolveInside` fails the open with ELOOP instead of
    // following out of the workspace.
    const handle = await fs.open(
      abs,
      fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0)
    );
    try {
      const stat = await handle.stat();
      if (!stat.isFile()) {
        throw new Exception({
          code: "not-a-file",
          workspace_id: workspace.id,
          rel_path: relPath,
        });
      }
      return {
        size: stat.size,
        mtime: stat.mtimeMs,
        stream: (opts) =>
          handle.createReadStream({ start: opts?.start, end: opts?.end }),
        close: () => handle.close(),
      };
    } catch (err) {
      await handle.close();
      throw err;
    }
  }

  /**
   * Write `content` to `relPath` atomically (temp + rename in the same
   * directory). Creates parent directories if needed. Returns the new
   * mtime so the client can update its conflict-detection state.
   *
   * Optimistic-concurrency guard (issue #805): when the caller passes
   * `expected_mtime` (the mtime it captured the last time it read or
   * wrote the file), the write is rejected with `modified-since` if the
   * file on disk has advanced past that token — an external writer (or
   * the agent) changed it in the meantime, and a blind write would
   * silently clobber that change with no conflict detection. The caller
   * resolves the conflict (reload from disk / overwrite anyway) and
   * retries. Omitting `expected_mtime` keeps the old last-writer-wins
   * behavior, so the agent's own writes and first-time creates are
   * unaffected.
   *
   * A file that was deleted out from under the caller (ENOENT while an
   * `expected_mtime` was supplied) is also a conflict — we don't
   * silently resurrect it under the old name.
   *
   * Note: we don't enforce MAX_FILE_BYTES on the write side — the
   * client can always re-read a file it just wrote, but a Monaco
   * buffer of 50MB is the user's problem to surface, not the agent host's
   * problem to silently truncate.
   */
  export async function writeFile(
    workspace: workspaceFs.Scope,
    relPath: string,
    content: string,
    options: { expected_mtime?: number } = {}
  ): Promise<{ mtime: number }> {
    // mustExist:false — we may be creating a new file. But the parent
    // dir must be inside the workspace, which `resolveInside` verifies
    // via the string-prefix check. `resolveWritableParent` then runs the
    // workspace-fs's own dir checks; that's why we don't lean on
    // `atomicWrite`'s ensureDir (it would mkdirp outside the workspace
    // policy boundary).
    const abs = await resolveInside(workspace, relPath, { must_exist: false });
    await resolveWritableParent(workspace, abs, relPath);
    // Optimistic-concurrency precondition (issue #805), enforced as
    // atomicWrite's `before_commit` hook so it runs immediately before the
    // rename that publishes the bytes — the check→replace gap is then a single
    // rename syscall, not the whole tmp-write. A mismatch (or an ENOENT: the
    // file was deleted out from under us) aborts the write before the rename;
    // atomicWrite removes the tmp it had staged. Omitting `expected_mtime`
    // keeps last-writer-wins, so agent writes / first creates are unaffected.
    const before_commit =
      options.expected_mtime === undefined
        ? undefined
        : async () => {
            // Plain Stats (not the bigint overload) — mtimeMs is a number that
            // round-trips through the JSON precondition token verbatim.
            let current: import("node:fs").Stats | undefined;
            try {
              current = await fs.stat(abs);
            } catch (err) {
              if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
              // ENOENT → the expected file is gone; fall through to the
              // `!current` conflict rather than re-creating it blindly.
            }
            if (!current || current.mtimeMs !== options.expected_mtime) {
              throw new Exception({
                code: "modified-since",
                workspace_id: workspace.id,
                rel_path: relPath,
                mtime: current?.mtimeMs,
              });
            }
          };
    // User-owned content — default 0o644 instead of `auth.json`'s 0o600.
    await atomicWrite(abs, content, {
      ensure_dir: false,
      mode: 0o644,
      before_commit,
    });
    const stat = await fs.stat(abs);
    return { mtime: stat.mtimeMs };
  }

  /**
   * Delete a regular file inside the workspace. Uses the same realpath
   * containment as reads, so symlinks that leave the workspace are
   * rejected before `rm`.
   */
  export async function deleteFile(
    workspace: workspaceFs.Scope,
    relPath: string
  ): Promise<void> {
    const abs = await resolveInside(workspace, relPath, { must_exist: true });
    const stat = await fs.stat(abs);
    if (!stat.isFile()) {
      throw new Exception({
        code: "not-a-file",
        workspace_id: workspace.id,
        rel_path: relPath,
      });
    }
    await fs.rm(abs);
  }
}

// ──────────────────────────── private helpers ────────────────────────────

/**
 * Metadata owned by an operating system, archive tool, or VCS should not
 * become product content. Keep this deliberately narrow: editor settings,
 * environment examples, dependency folders, and build output are legitimate
 * workspace entries and remain listable.
 */
const NON_LISTABLE_ENTRY_NAMES = new Set([
  ".ds_store",
  ".git",
  ".hg",
  ".svn",
  "__macosx",
  "cvs",
  "desktop.ini",
  "thumbs.db",
]);

function isListableEntry(name: string): boolean {
  return (
    !NON_LISTABLE_ENTRY_NAMES.has(name.toLowerCase()) && !name.startsWith("._")
  );
}

function directoryEntry(relPath: string, dirent: Dirent): workspaceFs.Entry {
  let kind: workspaceFs.Entry["kind"];
  if (dirent.isDirectory()) kind = "directory";
  else if (dirent.isFile()) kind = "file";
  else if (dirent.isSymbolicLink()) kind = "symlink";
  else kind = "other";
  // Build a posix-style relPath even on Windows for client consistency. The
  // daemon-side resolveInside uses path.resolve (platform-aware) on write.
  const child =
    relPath === "" || relPath === "."
      ? dirent.name
      : `${relPath.replace(/\\/g, "/").replace(/\/+$/, "")}/${dirent.name}`;
  return { name: dirent.name, rel_path: child, kind };
}

/**
 * Resolve `relPath` against `workspace.root` and verify containment.
 * Returns the absolute path (possibly non-existent if `mustExist:false`).
 *
 * The string-level check is done up front so an attack like `../../`
 * fails before any fs syscall. When `mustExist` is true, we additionally
 * `realpath` the target — this is what catches the
 * "/Users/x/ws/symlink-to-elsewhere" trick.
 *
 * The workspace's `root` is itself realpath'd by `WorkspaceRegistry`,
 * so the prefix comparison is canonical-to-canonical.
 */
async function resolveInside(
  workspace: workspaceFs.Scope,
  relPath: string,
  opts: { must_exist: boolean }
): Promise<string> {
  if (path.isAbsolute(relPath)) {
    throw new workspaceFs.Exception({
      code: "path-not-relative",
      workspace_id: workspace.id,
      rel_path: relPath,
    });
  }
  if (relPath.includes("\0")) {
    throw new workspaceFs.Exception({
      code: "path-contains-null",
      workspace_id: workspace.id,
      rel_path: relPath,
    });
  }
  // Allow empty/`.`/trailing slashes — they all resolve to the root.
  const candidate = path.resolve(workspace.root, relPath);
  const prefix = workspacePrefix(workspace);
  if (candidate !== workspace.root && !candidate.startsWith(prefix)) {
    throw new workspaceFs.Exception({
      code: "path-escapes-workspace",
      workspace_id: workspace.id,
      rel_path: relPath,
    });
  }
  if (opts.must_exist) {
    // realpath also fails fast with ENOENT — let that propagate as
    // a Node error so the route can surface a 404.
    const real = await fs.realpath(candidate);
    if (real !== workspace.root && !real.startsWith(prefix)) {
      throw new workspaceFs.Exception({
        code: "path-escapes-workspace",
        workspace_id: workspace.id,
        rel_path: relPath,
      });
    }
    return real;
  }
  return candidate;
}

function workspacePrefix(workspace: workspaceFs.Scope): string {
  return workspace.root.endsWith(path.sep)
    ? workspace.root
    : workspace.root + path.sep;
}

function assertInsideWorkspace(
  workspace: workspaceFs.Scope,
  absPath: string,
  relPath: string
): void {
  const prefix = workspacePrefix(workspace);
  if (absPath !== workspace.root && !absPath.startsWith(prefix)) {
    throw new workspaceFs.Exception({
      code: "path-escapes-workspace",
      workspace_id: workspace.id,
      rel_path: relPath,
    });
  }
}

/**
 * Resolve the parent directory for a write, guarding the symlink case
 * where the string path is under the workspace but an existing parent
 * component points outside it.
 */
async function resolveWritableParent(
  workspace: workspaceFs.Scope,
  absPath: string,
  relPath: string
): Promise<string> {
  const dir = path.dirname(absPath);
  assertInsideWorkspace(workspace, dir, relPath);

  let existing = dir;
  while (true) {
    try {
      const real = await fs.realpath(existing);
      assertInsideWorkspace(workspace, real, relPath);
      break;
    } catch (err) {
      const code = (err as NodeJS.ErrnoException | undefined)?.code;
      if (code !== "ENOENT") throw err;
      const parent = path.dirname(existing);
      if (parent === existing) throw err;
      assertInsideWorkspace(workspace, parent, relPath);
      existing = parent;
    }
  }

  await fs.mkdir(dir, { recursive: true });
  const realDir = await fs.realpath(dir);
  assertInsideWorkspace(workspace, realDir, relPath);
  return realDir;
}