Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

15.9 KB
Raw Blame
// Where a whiteboard node's drawing lives (nodes/WhiteboardNode.tsx).
//
// The scene is NOT in the node's data. A board with a pasted screenshot is megabytes, and node
// data rides every 800 ms workspace save (the whole workspace in one IPC message, one ≤8 MiB
// Server Edition frame), the 256 KB-per-node team-sync cap, 100 canvas-undo snapshots and the
// phone mirror. So each board is a side file beside project.json, like a canvas image:
//
//   <cwd>/.nodeterm/whiteboards/<nodeId>.excalidraw   (+ <nodeId>.png, the picture the node shows)
//
// falling back to `<userData>/whiteboards/` for a cwd-less canvas, an SSH project (its cwd is on
// the remote host) or a project folder that has been deleted — the same cases, for the same
// reasons, as `canvasImageTarget` in canvas-images.ts.
//
// A folder project whose canvas is kept in app data (issue #1145) writes nothing into its folder:
// its boards go to the same layout under its own app-data root (`appDataProjectRoot` in
// workspace-store.ts), and the folder's boards — drawn before the move — are only read. See
// `WhiteboardLocation`.
//
// **The path is derived HERE from (project, node id), never accepted from the renderer.** A
// node's data comes from the git-shared project.json, which anyone with commit access can edit;
// taking a path from it would let a crafted canvas aim a read or an overwrite anywhere this
// process can reach. A node id is validated with `isSafeNodeId` (no separators, no `..`), so the
// only files this module ever touches are `<id>.excalidraw` / `<id>.png` in those two folders.
//
// **The project folder is bound by its REAL path** (`projectBoardsDir`). The id check covers the
// file name only: a repository can commit `.nodeterm` or `.nodeterm/whiteboards` as a symlink to any
// directory on this machine, and every component before the file name used to be followed — a save
// wrote `<id>.excalidraw` / `<id>.png` on the other side, and a read (which a hosted-team Viewer can
// ask for) served that side's files past the realpath jail every `fs:*` call gets. Each existing
// component is resolved and must stay inside the project's real root before anything is created
// through it; otherwise the project folder is not used and the board falls back to the app folder.

import { promises as fs } from 'fs'
import { isAbsolute, join, relative, sep } from 'path'
import { renameAtomic, tempNameFor, writeFileAtomic } from './fs-atomic'
import { readRegularFileBytesNoFollow } from './read-regular-file'
import { isSafeNodeId } from '../shared/safe-id'
import type { WhiteboardFile, WhiteboardSaveResult } from '../shared/whiteboard'

/** `isSafeNodeId` alone would pass a NUMBER (its regex coerces it); these arrive over IPC. */
const safeId = (id: unknown): id is string => typeof id === 'string' && isSafeNodeId(id)

export type { WhiteboardFile, WhiteboardSaveResult }

export const projectWhiteboardsDir = (projectCwd: string): string =>
  join(projectCwd, '.nodeterm', 'whiteboards')

export const appWhiteboardsDir = (userDataDir: string): string => join(userDataDir, 'whiteboards')

/** A scene is JSON text. 64 MB holds a board full of pasted screenshots with room to spare. */
export const WHITEBOARD_SCENE_MAX_BYTES = 64 * 1024 * 1024
/** The resting picture is capped at 1600 px on its long side, so 16 MB is generous. */
export const WHITEBOARD_THUMB_MAX_BYTES = 16 * 1024 * 1024

export interface WhiteboardLocation {
  /** The directory whose `.nodeterm/whiteboards/` takes this project's boards. */
  projectCwd?: string
  /**
   * `projectCwd` is the app's own directory — a folder project kept in app data, whose root is
   * `appDataProjectRoot` — so a write creates it. Never set for a user's folder: one that is gone
   * is not resurrected.
   */
  createRoot?: boolean
  /**
   * A root that is READ and never written: the other side of a folder project that moved its canvas
   * between its folder and app data (issue #1145), so a board drawn before the move still opens.
   * Read after every folder a save can land in, so a board saved since is never shadowed by it.
   */
  readOnlyRoot?: string
  userDataDir: string
}


/** `writeFileAtomic` writes TEXT (utf-8), which would mangle a PNG. Same publish discipline for
 *  bytes: an exclusive-create temp (named like every other, so the stale-temp sweep knows it),
 *  then the retrying atomic rename. */
async function writeBytesAtomic(target: string, data: Buffer): Promise<void> {
  const tmp = tempNameFor(target)
  try {
    await fs.writeFile(tmp, data, { flag: 'wx' })
    await renameAtomic(tmp, target)
  } catch (e) {
    await fs.rm(tmp, { force: true }).catch(() => {})
    throw e
  }
}

/** `child` is `root` or below it, by path SEGMENTS (a sibling `root-x` is not inside `root`). A
 *  path on another Windows drive comes back from `relative` absolute, and is not inside either. */
const within = (root: string, child: string): boolean => {
  const rel = relative(root, child)
  return rel === '' || (!isAbsolute(rel) && rel.split(sep)[0] !== '..')
}

/**
 * The project's whiteboards folder by its real path, or null when it must not be used: the project
 * folder is gone, a component of `.nodeterm/whiteboards` leads outside the project (or dangles), or
 * — for a read — the folder does not exist. `create` makes it for a write; a read never creates.
 *
 * Every component that exists is resolved BEFORE anything is created through it: `mkdir -p` on a
 * `.nodeterm` that links out of the project would make `whiteboards` on the other side. A project
 * folder that is GONE is refused too, so a write never resurrects a directory the user deleted.
 */
async function projectBoardsDir(projectCwd: string, create: boolean, createRoot = false): Promise<string | null> {
  if (create && createRoot) await fs.mkdir(projectCwd, { recursive: true }).catch(() => undefined)
  const root = await fs.realpath(projectCwd).catch(() => null)
  if (!root || !(await fs.stat(root).then((s) => s.isDirectory(), () => false))) return null
  const boards = join(root, '.nodeterm', 'whiteboards')
  for (const p of [join(root, '.nodeterm'), boards]) {
    const present = await fs.lstat(p).then(
      () => true,
      (e: NodeJS.ErrnoException) => (e?.code === 'ENOENT' ? false : null)
    )
    if (present === null) return null
    if (!present) {
      if (!create) return null
      break
    }
    // A dangling link has no real path: refused, never created through.
    const real = await fs.realpath(p).catch(() => null)
    if (!real || !within(root, real)) return null
  }
  if (create) await fs.mkdir(boards, { recursive: true })
  const real = await fs.realpath(boards).catch(() => null)
  if (!real || !within(root, real)) return null
  return (await fs.stat(real).then((s) => s.isDirectory(), () => false)) ? real : null
}

/** The folders a board may be in, most specific first. `write` creates the project's folder; a read
 *  only looks in one that exists. A project folder that cannot be used (see `projectBoardsDir`) is
 *  left out, so the board lands in — or is read from — the app folder alone. The read-only root is
 *  never a write target, and a read reaches it last. */
async function candidateDirs(loc: WhiteboardLocation, write: boolean): Promise<string[]> {
  const dirs: string[] = []
  if (loc.projectCwd) {
    const dir = await projectBoardsDir(loc.projectCwd, write, loc.createRoot === true).catch(() => null)
    if (dir) dirs.push(dir)
  }
  dirs.push(appWhiteboardsDir(loc.userDataDir))
  if (!write && loc.readOnlyRoot) {
    const dir = await projectBoardsDir(loc.readOnlyRoot, false).catch(() => null)
    if (dir && !dirs.includes(dir)) dirs.push(dir)
  }
  return dirs
}

/** The revision of this node's OWN board — the file `readWhiteboard` would answer for it — or null
 *  when it has none. Stat only: the scene is not read. */
async function ownRev(dirs: string[], nodeId: string): Promise<string | null> {
  for (const dir of dirs) {
    const st = await readRegularFileBytesNoFollow(join(dir, `${nodeId}.excalidraw`), WHITEBOARD_SCENE_MAX_BYTES, {
      read: false
    })
    if (st) return st.stamp
  }
  return null
}

/**
 * One save at a time per board in this process, so a compare-and-set can never interleave with
 * another save of the same board in the same core. Two CORES writing one folder (a desktop and a
 * Server Edition on the same project) can still interleave between the check and the rename; that
 * window is a stat and a rename long.
 */
const savesInFlight = new Map<string, Promise<unknown>>()
function oneSaveAtATime<T>(key: string, run: () => Promise<T>): Promise<T> {
  const next = (savesInFlight.get(key) ?? Promise.resolve()).then(run, run)
  const tail = next.catch(() => undefined)
  savesInFlight.set(key, tail)
  void tail.then(() => {
    if (savesInFlight.get(key) === tail) savesInFlight.delete(key)
  })
  return next
}

/**
 * Write a board's scene (and optionally its picture). Resolves `{ok: true, path, rev}`, a conflict
 * (below), or null when the input is refused (bad id, over the cap) or no folder would take it.
 * Never throws: the caller keeps the board open and says the save failed — a drawing that silently
 * was not saved is the failure this must not have. The project folder is tried first; a read-only
 * checkout or a `.nodeterm` that is a file falls back to the app folder, like a canvas image.
 *
 * **Compare-and-set.** `expectedRev` is the revision the editor last read or wrote (`null`: it has
 * no board of its own yet — a new board, or a copy still showing its source). When the board on
 * disk is not that revision, nothing is written and the answer is `{conflict: true, currentRev}`:
 * someone else saved it meanwhile, and replacing their whole board with ours is exactly the loss
 * this exists to prevent. `undefined` (a caller that sends no revision — a renderer on an older
 * build reaching this core over a relay) keeps the unconditional write.
 */
export async function saveWhiteboard(
  loc: WhiteboardLocation,
  nodeId: string,
  scene: string,
  thumbnailBase64?: string,
  expectedRev?: string | null
): Promise<WhiteboardSaveResult | null> {
  if (!safeId(nodeId)) return null
  if (typeof scene !== 'string' || Buffer.byteLength(scene) > WHITEBOARD_SCENE_MAX_BYTES) return null
  if (expectedRev !== undefined && expectedRev !== null && typeof expectedRev !== 'string') return null
  let thumb: Buffer | undefined
  if (typeof thumbnailBase64 === 'string' && thumbnailBase64.length) {
    // Measure the ENCODED length first: decoding a hostile 2 GB string is the allocation the cap
    // exists to prevent (same rule as uploads.ts).
    if (thumbnailBase64.length > WHITEBOARD_THUMB_MAX_BYTES * 1.4) return null
    thumb = Buffer.from(thumbnailBase64, 'base64')
    if (thumb.length > WHITEBOARD_THUMB_MAX_BYTES) return null
  }
  return oneSaveAtATime(JSON.stringify([loc.userDataDir, loc.projectCwd ?? '', nodeId]), async () => {
    if (expectedRev !== undefined) {
      const currentRev = await ownRev(await candidateDirs(loc, false), nodeId)
      if (currentRev !== expectedRev) return { ok: false as const, conflict: true as const, currentRev }
    }
    for (const dir of await candidateDirs(loc, true)) {
      try {
        await fs.mkdir(dir, { recursive: true })
        const scenePath = join(dir, `${nodeId}.excalidraw`)
        await writeFileAtomic(scenePath, scene)
        // The picture is best-effort: a board whose scene saved but whose picture did not is still
        // a saved board (the node re-renders the picture the next time it is opened).
        if (thumb) await writeBytesAtomic(join(dir, `${nodeId}.png`), thumb).catch(() => undefined)
        // An empty string means the board is empty now: drop the old picture instead of showing it.
        else if (thumbnailBase64 === '') await fs.rm(join(dir, `${nodeId}.png`), { force: true }).catch(() => undefined)
        const written = await readRegularFileBytesNoFollow(scenePath, WHITEBOARD_SCENE_MAX_BYTES, { read: false })
        return { ok: true as const, path: scenePath, rev: written?.stamp ?? '' }
      } catch {
        // try the next folder
      }
    }
    return null
  })
}

/**
 * The board in the first folder that has one. Both files are read through ONE descriptor each with
 * symlinks refused (`readRegularFileBytesNoFollow`): `.nodeterm/` is git-shared, and a committed
 * symlink named `<id>.excalidraw` must not hand some other file on this machine to the renderer.
 */
async function readIn(
  dirs: string[],
  nodeId: string,
  withScene: boolean
): Promise<Omit<WhiteboardFile, 'fromSource'> | null> {
  for (const dir of dirs) {
    const scene = await readRegularFileBytesNoFollow(join(dir, `${nodeId}.excalidraw`), WHITEBOARD_SCENE_MAX_BYTES, {
      read: withScene
    })
    if (!scene) continue
    const png = await readRegularFileBytesNoFollow(join(dir, `${nodeId}.png`), WHITEBOARD_THUMB_MAX_BYTES)
    return {
      scene: scene.bytes?.toString('utf8'),
      thumbnailBase64: png?.bytes?.toString('base64'),
      updatedAt: scene.mtimeMs,
      rev: scene.stamp
    }
  }
  return null
}

/**
 * Copy the boards under `fromRoot`'s `.nodeterm/whiteboards/` into `toRoot`'s, replacing a file of the
 * same name. Run when a folder project's canvas moves from app data back into its folder (issue
 * #1145): the folder is read first afterwards, and its older file of a board edited in app data
 * would hide the edit. Nothing is deleted on either side. A board is read with symlinks refused and
 * the folder is bound by its real path, like every other board read and write, and the folder's
 * whiteboards directory is made only once there is a board to put in it. One that cannot be read or
 * written stays where it is. Never throws.
 */
export async function carryWhiteboards(fromRoot: string, toRoot: string): Promise<void> {
  const from = await projectBoardsDir(fromRoot, false).catch(() => null)
  if (!from) return
  const ids = (await fs.readdir(from).catch((): string[] => []))
    .filter((name) => name.endsWith('.excalidraw'))
    .map((name) => name.slice(0, -'.excalidraw'.length))
    .filter(safeId)
  let to: string | null | undefined
  for (const id of ids) {
    const board = await readRegularFileBytesNoFollow(join(from, `${id}.excalidraw`), WHITEBOARD_SCENE_MAX_BYTES)
    if (!board?.bytes) continue
    const picture = await readRegularFileBytesNoFollow(join(from, `${id}.png`), WHITEBOARD_THUMB_MAX_BYTES)
    if (to === undefined) to = await projectBoardsDir(toRoot, true).catch(() => null)
    if (!to) return
    try {
      await writeBytesAtomic(join(to, `${id}.excalidraw`), board.bytes)
      // A board with no picture is an empty one: the folder's old picture must not stand in for it.
      if (picture?.bytes) await writeBytesAtomic(join(to, `${id}.png`), picture.bytes)
      else await fs.rm(join(to, `${id}.png`), { force: true })
    } catch {
      // this board stays in app data, where a read still reaches it when the folder has none
    }
  }
}

/**
 * Read a board. `sourceId` is the board a duplicated or reopened node was copied from: until the
 * node saves its own file, it shows (and starts editing from) the source's — so a copy never
 * needed a file copy, and no board file is ever deleted out from under an undo or a reopen.
 * Resolves null when neither exists (a new, empty board).
 *
 * `withScene: false` answers only the picture and the revision — what a board at REST needs. The
 * scene (megabytes once screenshots are pasted in) is fetched when the board is opened, so a
 * canvas of twenty boards does not hold twenty drawings in the renderer.
 */
export async function readWhiteboard(
  loc: WhiteboardLocation,
  nodeId: string,
  sourceId?: string,
  withScene = true
): Promise<WhiteboardFile | null> {
  if (!safeId(nodeId)) return null
  const dirs = await candidateDirs(loc, false)
  const own = await readIn(dirs, nodeId, withScene !== false)
  if (own) return { ...own, fromSource: false }
  if (sourceId !== nodeId && safeId(sourceId)) {
    const copied = await readIn(dirs, sourceId, withScene !== false)
    if (copied) return { ...copied, fromSource: true }
  }
  return null
}