nodejs/stdlib/

fs.rs

//! Node `fs` module: synchronous file operations, the async callback forms, and
//! the file-descriptor / directory / stream / watcher surfaces.
//!
//! Path operations map straight onto `std::fs`; descriptor operations
//! (`open`/`read`/`write`/`fstat`/…) keep a thread-local table of open
//! `std::fs::File`s keyed by a synthetic integer fd (starting at 3, after the
//! stdio fds). Ownership / timestamp / statvfs operations that `std::fs` does not
//! cover use `libc` directly (all targets are unix). Async callback variants run
//! the same synchronous work then schedule the callback as a microtask, matching
//! Node's ordering for simple scripts.

use super::{arg_num, arg_str, native_tag};
use crate::host::{invoke, with_host, JsObj};
use fusevm::Value;
use indexmap::IndexMap;
use std::cell::RefCell;
use std::collections::HashMap;
use std::ffi::CString;
use std::fs::File;
use std::io::{Read, Seek, SeekFrom, Write};
use std::os::unix::fs::{MetadataExt, PermissionsExt};
use std::os::unix::io::AsRawFd;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use std::time::{Duration, UNIX_EPOCH};

pub const METHODS: &[&str] = &[
    // path — sync
    "readFileSync",
    "writeFileSync",
    "appendFileSync",
    "existsSync",
    "readdirSync",
    "mkdirSync",
    "rmdirSync",
    "unlinkSync",
    "rmSync",
    "statSync",
    "lstatSync",
    "statfsSync",
    "accessSync",
    "chmodSync",
    "chownSync",
    "lchownSync",
    "copyFileSync",
    "cpSync",
    "linkSync",
    "symlinkSync",
    "readlinkSync",
    "realpathSync",
    "renameSync",
    "truncateSync",
    "utimesSync",
    "lutimesSync",
    "mkdtempSync",
    "opendirSync",
    "globSync",
    // fd — sync
    "openSync",
    "closeSync",
    "readSync",
    "writeSync",
    "readvSync",
    "writevSync",
    "fstatSync",
    "fchmodSync",
    "fchownSync",
    "ftruncateSync",
    "futimesSync",
    "fsyncSync",
    "fdatasyncSync",
    // path — async (callback)
    "readFile",
    "writeFile",
    "appendFile",
    "readdir",
    "mkdir",
    "rmdir",
    "rm",
    "unlink",
    "stat",
    "lstat",
    "statfs",
    "access",
    "chmod",
    "chown",
    "lchown",
    "copyFile",
    "cp",
    "link",
    "symlink",
    "readlink",
    "realpath",
    "rename",
    "truncate",
    "utimes",
    "lutimes",
    "mkdtemp",
    "opendir",
    "glob",
    "exists",
    // fd — async (callback)
    "open",
    "close",
    "read",
    "write",
    "readv",
    "writev",
    "fstat",
    "fchmod",
    "fchown",
    "ftruncate",
    "futimes",
    "fsync",
    "fdatasync",
    // watchers + streams
    "watchFile",
    "unwatchFile",
    "createReadStream",
    "createWriteStream",
];

// ── file-descriptor table ────────────────────────────────────────────────────

thread_local! {
    static FD_TABLE: RefCell<HashMap<i32, File>> = RefCell::new(HashMap::new());
    static NEXT_FD: RefCell<i32> = const { RefCell::new(3) };
    static WATCHERS: RefCell<Vec<WatchEntry>> = const { RefCell::new(Vec::new()) };
    static NEXT_WATCH_ID: RefCell<u64> = const { RefCell::new(1) };
}

struct WatchEntry {
    // Reserved for a future StatWatcher handle; assigned but not yet read.
    #[allow(dead_code)]
    id: u64,
    path: String,
    listener: Value,
    stop: Arc<AtomicBool>,
}

fn register_fd(file: File) -> i32 {
    NEXT_FD.with(|n| {
        let fd = *n.borrow();
        *n.borrow_mut() = fd + 1;
        FD_TABLE.with(|t| t.borrow_mut().insert(fd, file));
        fd
    })
}

fn with_file<R>(fd: i32, f: impl FnOnce(&File) -> R) -> Option<R> {
    FD_TABLE.with(|t| t.borrow().get(&fd).map(f))
}

fn close_fd(fd: i32) -> bool {
    FD_TABLE.with(|t| t.borrow_mut().remove(&fd).is_some())
}

// ── dispatch ─────────────────────────────────────────────────────────────────

pub fn call(method: &str, args: &[Value]) -> Option<Result<Value, String>> {
    Some(match method {
        // ── path, sync ──
        "readFileSync" => read_file_sync(args),
        "writeFileSync" => write_file_impl(args),
        "appendFileSync" => append_file_impl(args),
        "existsSync" => Ok(Value::Bool(Path::new(&arg_str(args, 0)).exists())),
        "readdirSync" => readdir_impl(args),
        "mkdirSync" => mkdir_impl(args),
        "rmdirSync" | "unlinkSync" | "rmSync" => rm_impl(method, args),
        "statSync" => stat_impl("statSync", args, true),
        "lstatSync" => stat_impl("lstatSync", args, false),
        "statfsSync" => statfs_impl(args),
        "accessSync" => access_impl(args),
        "chmodSync" => chmod_impl(args),
        "chownSync" => chown_impl(args, true),
        "lchownSync" => chown_impl(args, false),
        "copyFileSync" => copy_file_impl(args),
        "cpSync" => cp_impl(args),
        "linkSync" => link_impl(args),
        "symlinkSync" => symlink_impl(args),
        "readlinkSync" => readlink_impl(args),
        "realpathSync" => realpath_impl(args),
        "renameSync" => rename_impl(args),
        "truncateSync" => truncate_impl(args),
        "utimesSync" => utimes_impl(args, true),
        "lutimesSync" => utimes_impl(args, false),
        "mkdtempSync" => mkdtemp_impl(args),
        "opendirSync" => opendir_impl(args),
        "globSync" => glob_impl(args),
        // ── fd, sync ──
        "openSync" => open_impl(args),
        "closeSync" => close_impl(args),
        "readSync" => read_impl(args).map(|n| Value::Float(n as f64)),
        "writeSync" => write_impl(args).map(|n| Value::Float(n as f64)),
        "readvSync" => readv_impl(args).map(|n| Value::Float(n as f64)),
        "writevSync" => writev_impl(args).map(|n| Value::Float(n as f64)),
        "fstatSync" => fstat_impl(args),
        "fchmodSync" => fchmod_impl(args),
        "fchownSync" => fchown_impl(args),
        "ftruncateSync" => ftruncate_impl(args),
        "futimesSync" => futimes_impl(args),
        "fsyncSync" => fsync_impl(args, false),
        "fdatasyncSync" => fsync_impl(args, true),
        // ── path, async ──
        "readFile" => return Some(read_file_async(args)),
        "writeFile" => async_cb(args, write_file_impl(args)),
        "appendFile" => async_cb(args, append_file_impl(args)),
        "readdir" => async_cb(args, readdir_impl(args)),
        "mkdir" => async_cb(args, mkdir_impl(args)),
        "rmdir" => async_cb(args, rm_impl("rmdir", args)),
        "rm" => async_cb(args, rm_impl("rm", args)),
        "unlink" => async_cb(args, rm_impl("unlink", args)),
        "stat" => async_cb(args, stat_impl("stat", args, true)),
        "lstat" => async_cb(args, stat_impl("lstat", args, false)),
        "statfs" => async_cb(args, statfs_impl(args)),
        "access" => async_cb(args, access_impl(args)),
        "chmod" => async_cb(args, chmod_impl(args)),
        "chown" => async_cb(args, chown_impl(args, true)),
        "lchown" => async_cb(args, chown_impl(args, false)),
        "copyFile" => async_cb(args, copy_file_impl(args)),
        "cp" => async_cb(args, cp_impl(args)),
        "link" => async_cb(args, link_impl(args)),
        "symlink" => async_cb(args, symlink_impl(args)),
        "readlink" => async_cb(args, readlink_impl(args)),
        "realpath" => async_cb(args, realpath_impl(args)),
        "rename" => async_cb(args, rename_impl(args)),
        "truncate" => async_cb(args, truncate_impl(args)),
        "utimes" => async_cb(args, utimes_impl(args, true)),
        "lutimes" => async_cb(args, utimes_impl(args, false)),
        "mkdtemp" => async_cb(args, mkdtemp_impl(args)),
        "opendir" => async_cb(args, opendir_impl(args)),
        "glob" => async_cb(args, glob_impl(args)),
        "exists" => exists_async(args),
        // ── fd, async ──
        "open" => async_cb(args, open_impl(args)),
        "close" => async_cb(args, close_impl(args)),
        "read" => return Some(read_write_async(args, read_impl(args))),
        "write" => return Some(read_write_async(args, write_impl(args))),
        "readv" => async_cb(args, readv_impl(args).map(|n| Value::Float(n as f64))),
        "writev" => async_cb(args, writev_impl(args).map(|n| Value::Float(n as f64))),
        "fstat" => async_cb(args, fstat_impl(args)),
        "fchmod" => async_cb(args, fchmod_impl(args)),
        "fchown" => async_cb(args, fchown_impl(args)),
        "ftruncate" => async_cb(args, ftruncate_impl(args)),
        "futimes" => async_cb(args, futimes_impl(args)),
        "fsync" => async_cb(args, fsync_impl(args, false)),
        "fdatasync" => async_cb(args, fsync_impl(args, true)),
        // ── watchers + streams ──
        "watchFile" => watch_file(args),
        "unwatchFile" => unwatch_file(args),
        "createReadStream" => create_read_stream(args),
        "createWriteStream" => create_write_stream(args),
        _ => return None,
    })
}

// ── async callback plumbing ──────────────────────────────────────────────────

/// Schedule the trailing callback as a microtask: `cb(null, value)` on success,
/// `cb(err)` (an error string, matching the existing `readFile`/`writeFile`
/// callbacks) on failure. Always returns `undefined` (the method's own result).
fn async_cb(args: &[Value], result: Result<Value, String>) -> Result<Value, String> {
    let Some(cb) = args.last().cloned().filter(is_fn) else {
        return Ok(Value::Undef);
    };
    match result {
        Ok(v) => with_host(|h| {
            let n = h.null();
            h.queue_micro(cb, vec![n, v]);
        }),
        Err(e) => with_host(|h| {
            let ev = h.new_str(e);
            h.queue_micro(cb, vec![ev]);
        }),
    }
    Ok(Value::Undef)
}

/// `read`/`write` callbacks carry a third argument: `cb(err, count, buffer)`.
fn read_write_async(args: &[Value], result: Result<usize, String>) -> Result<Value, String> {
    let Some(cb) = args.last().cloned().filter(is_fn) else {
        return Ok(Value::Undef);
    };
    let buffer = args.get(1).cloned().unwrap_or(Value::Undef);
    match result {
        Ok(n) => with_host(|h| {
            let nul = h.null();
            h.queue_micro(cb, vec![nul, Value::Float(n as f64), buffer]);
        }),
        Err(e) => with_host(|h| {
            let ev = h.new_str(e);
            h.queue_micro(cb, vec![ev]);
        }),
    }
    Ok(Value::Undef)
}

fn is_fn(v: &Value) -> bool {
    with_host(|h| crate::host::is_callable(h, v))
}

// ── read/write/append ────────────────────────────────────────────────────────

fn read_file_sync(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let enc = encoding_arg(args, 1);
    match std::fs::read(&path) {
        Ok(bytes) => Ok(match enc {
            Some(_) => with_host(|h| h.new_str(String::from_utf8_lossy(&bytes).into_owned())),
            None => super::buffer::from_bytes(&bytes),
        }),
        Err(e) => Err(err_str("readFileSync", &path, &e)),
    }
}

fn write_file_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let data = value_bytes(args.get(1).unwrap_or(&Value::Undef));
    match std::fs::write(&path, data) {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("writeFile", &path, &e)),
    }
}

fn append_file_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let data = value_bytes(args.get(1).unwrap_or(&Value::Undef));
    let r = std::fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open(&path)
        .and_then(|mut f| f.write_all(&data));
    match r {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("appendFile", &path, &e)),
    }
}

fn read_file_async(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let Some(cb) = args.last().cloned().filter(is_fn) else {
        return Ok(Value::Undef);
    };
    let enc = if args.len() >= 3 {
        encoding_arg(args, 1)
    } else {
        None
    };
    let (err, data) = match std::fs::read(&path) {
        Ok(bytes) => (
            with_host(|h| h.null()),
            match enc {
                Some(_) => with_host(|h| h.new_str(String::from_utf8_lossy(&bytes).into_owned())),
                None => super::buffer::from_bytes(&bytes),
            },
        ),
        Err(e) => (
            with_host(|h| h.new_str(err_str("readFile", &path, &e))),
            Value::Undef,
        ),
    };
    with_host(|h| h.queue_micro(cb, vec![err, data]));
    Ok(Value::Undef)
}

fn exists_async(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let Some(cb) = args.last().cloned().filter(is_fn) else {
        return Ok(Value::Undef);
    };
    let ex = Path::new(&path).exists();
    with_host(|h| h.queue_micro(cb, vec![Value::Bool(ex)]));
    Ok(Value::Undef)
}

// ── directories ──────────────────────────────────────────────────────────────

fn mkdir_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let recursive = opt_flag(args, "recursive");
    let r = if recursive {
        std::fs::create_dir_all(&path)
    } else {
        std::fs::create_dir(&path)
    };
    match r {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("mkdir", &path, &e)),
    }
}

fn rm_impl(op: &str, args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let p = Path::new(&path);
    let force = opt_flag(args, "force");
    let r = if p.is_dir() {
        if opt_flag(args, "recursive") {
            std::fs::remove_dir_all(p)
        } else {
            std::fs::remove_dir(p)
        }
    } else {
        std::fs::remove_file(p)
    };
    match r {
        Ok(_) => Ok(Value::Undef),
        Err(e) if force && e.kind() == std::io::ErrorKind::NotFound => Ok(Value::Undef),
        Err(e) => Err(err_str(op, &path, &e)),
    }
}

fn readdir_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let file_types = opt_flag(args, "withFileTypes");
    let recursive = opt_flag(args, "recursive");
    let mut names: Vec<(String, String, std::fs::FileType)> = Vec::new();
    collect_dir(Path::new(&path), &path, "", recursive, &mut names)
        .map_err(|e| err_str("readdir", &path, &e))?;
    names.sort_by(|a, b| a.0.cmp(&b.0));
    Ok(with_host(|h| {
        let items: Vec<Value> = names
            .into_iter()
            .map(|(rel, parent, ft)| {
                if file_types {
                    let base = rel.rsplit('/').next().unwrap_or(&rel).to_string();
                    build_dirent(h, base, &parent, ft)
                } else {
                    h.new_str(rel)
                }
            })
            .collect();
        h.new_array(items)
    }))
}

/// Collect directory entries. `rel_prefix` is the path (relative to the root)
/// under which `dir`'s children are listed; `parent` is the absolute-ish parent
/// path recorded on each `Dirent`.
fn collect_dir(
    dir: &Path,
    parent: &str,
    rel_prefix: &str,
    recursive: bool,
    out: &mut Vec<(String, String, std::fs::FileType)>,
) -> std::io::Result<()> {
    for e in std::fs::read_dir(dir)? {
        let e = e?;
        let name = e.file_name().to_string_lossy().into_owned();
        let rel = if rel_prefix.is_empty() {
            name.clone()
        } else {
            format!("{rel_prefix}/{name}")
        };
        let ft = e.file_type()?;
        out.push((rel.clone(), parent.to_string(), ft));
        if recursive && ft.is_dir() {
            let sub = e.path();
            let sub_parent = sub.to_string_lossy().into_owned();
            collect_dir(&sub, &sub_parent, &rel, recursive, out)?;
        }
    }
    Ok(())
}

fn opendir_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let rd = std::fs::read_dir(&path).map_err(|e| err_str("opendir", &path, &e))?;
    let mut entries: Vec<(String, std::fs::FileType)> = rd
        .filter_map(|e| e.ok())
        .filter_map(|e| {
            e.file_type()
                .ok()
                .map(|ft| (e.file_name().to_string_lossy().into_owned(), ft))
        })
        .collect();
    entries.sort_by(|a, b| a.0.cmp(&b.0));
    Ok(with_host(|h| {
        let dirents: Vec<Value> = entries
            .into_iter()
            .map(|(name, ft)| build_dirent(h, name, &path, ft))
            .collect();
        let arr = h.new_array(dirents);
        let mut m = IndexMap::new();
        m.insert("@@native".into(), h.new_str("Dir"));
        m.insert("path".into(), h.new_str(path.clone()));
        m.insert("@@entries".into(), arr);
        m.insert("@@pos".into(), Value::Float(0.0));
        h.new_object(m)
    }))
}

// ── ownership / permissions / timestamps ─────────────────────────────────────

fn access_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    match std::fs::metadata(&path) {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("access", &path, &e)),
    }
}

fn chmod_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let mode = arg_num(args, 1) as u32;
    match std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode)) {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("chmod", &path, &e)),
    }
}

fn chown_impl(args: &[Value], follow: bool) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let uid = arg_num(args, 1) as libc::uid_t;
    let gid = arg_num(args, 2) as libc::gid_t;
    let c = cpath(&path, "chown")?;
    let rc = unsafe {
        if follow {
            libc::chown(c.as_ptr(), uid, gid)
        } else {
            libc::lchown(c.as_ptr(), uid, gid)
        }
    };
    ok_or_errno(rc, "chown", &path)
}

fn utimes_impl(args: &[Value], follow: bool) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let times = [
        to_timeval(time_secs(args, 1)),
        to_timeval(time_secs(args, 2)),
    ];
    let c = cpath(&path, "utimes")?;
    let rc = unsafe {
        if follow {
            libc::utimes(c.as_ptr(), times.as_ptr())
        } else {
            libc::lutimes(c.as_ptr(), times.as_ptr())
        }
    };
    ok_or_errno(rc, "utimes", &path)
}

// ── copy / link / rename / truncate ──────────────────────────────────────────

const COPYFILE_EXCL: u32 = 1;

fn copy_file_impl(args: &[Value]) -> Result<Value, String> {
    let src = arg_str(args, 0);
    let dest = arg_str(args, 1);
    let mode = arg_num(args, 2);
    if !mode.is_nan() && (mode as u32) & COPYFILE_EXCL != 0 && Path::new(&dest).exists() {
        return Err(format!(
            "Error: EEXIST: file already exists, copyfile '{src}' -> '{dest}'"
        ));
    }
    match std::fs::copy(&src, &dest) {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("copyFile", &src, &e)),
    }
}

fn cp_impl(args: &[Value]) -> Result<Value, String> {
    let src = arg_str(args, 0);
    let dest = arg_str(args, 1);
    let recursive = opt_flag(args, "recursive");
    let r = if recursive {
        cp_recursive(Path::new(&src), Path::new(&dest))
    } else {
        std::fs::copy(&src, &dest).map(|_| ())
    };
    match r {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("cp", &src, &e)),
    }
}

fn cp_recursive(src: &Path, dest: &Path) -> std::io::Result<()> {
    if src.is_dir() {
        std::fs::create_dir_all(dest)?;
        for e in std::fs::read_dir(src)? {
            let e = e?;
            cp_recursive(&e.path(), &dest.join(e.file_name()))?;
        }
        Ok(())
    } else {
        if let Some(parent) = dest.parent() {
            std::fs::create_dir_all(parent).ok();
        }
        std::fs::copy(src, dest).map(|_| ())
    }
}

fn link_impl(args: &[Value]) -> Result<Value, String> {
    let existing = arg_str(args, 0);
    let new = arg_str(args, 1);
    match std::fs::hard_link(&existing, &new) {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("link", &existing, &e)),
    }
}

fn symlink_impl(args: &[Value]) -> Result<Value, String> {
    let target = arg_str(args, 0);
    let path = arg_str(args, 1);
    match std::os::unix::fs::symlink(&target, &path) {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("symlink", &path, &e)),
    }
}

fn readlink_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    match std::fs::read_link(&path) {
        Ok(p) => Ok(with_host(|h| h.new_str(p.to_string_lossy().into_owned()))),
        Err(e) => Err(err_str("readlink", &path, &e)),
    }
}

fn realpath_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    match std::fs::canonicalize(&path) {
        Ok(p) => Ok(with_host(|h| h.new_str(p.to_string_lossy().into_owned()))),
        Err(e) => Err(err_str("realpath", &path, &e)),
    }
}

fn rename_impl(args: &[Value]) -> Result<Value, String> {
    let from = arg_str(args, 0);
    let to = arg_str(args, 1);
    match std::fs::rename(&from, &to) {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("rename", &from, &e)),
    }
}

fn truncate_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let len = arg_num(args, 1);
    let len = if len.is_nan() { 0 } else { len as u64 };
    let r = std::fs::OpenOptions::new()
        .write(true)
        .open(&path)
        .and_then(|f| f.set_len(len));
    match r {
        Ok(_) => Ok(Value::Undef),
        Err(e) => Err(err_str("truncate", &path, &e)),
    }
}

fn mkdtemp_impl(args: &[Value]) -> Result<Value, String> {
    let prefix = arg_str(args, 0);
    for _ in 0..64 {
        let candidate = format!("{prefix}{}", random_suffix());
        match std::fs::create_dir(&candidate) {
            Ok(_) => return Ok(with_host(|h| h.new_str(candidate))),
            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
            Err(e) => return Err(err_str("mkdtemp", &prefix, &e)),
        }
    }
    Err(format!(
        "Error: EEXIST: file already exists, mkdtemp '{prefix}'"
    ))
}

/// Six random `[0-9A-Za-z]` characters — Node's `mkdtemp` suffix alphabet.
fn random_suffix() -> String {
    const CHARS: &[u8; 62] = b"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
    let mut raw = [0u8; 6];
    if getrandom::getrandom(&mut raw).is_err() {
        // Fall back to a clock-derived seed; uniqueness is retried by the caller.
        let nanos = std::time::SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map(|d| d.subsec_nanos())
            .unwrap_or(0);
        raw = nanos
            .to_le_bytes()
            .iter()
            .cycle()
            .take(6)
            .copied()
            .collect::<Vec<_>>()
            .try_into()
            .unwrap();
    }
    raw.iter()
        .map(|b| CHARS[(*b as usize) % 62] as char)
        .collect()
}

// ── file descriptors ─────────────────────────────────────────────────────────

fn open_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let flags = match args.get(1) {
        Some(v) if !matches!(v, Value::Undef) && !is_fn(v) => arg_str(args, 1),
        _ => "r".to_string(),
    };
    match open_options(&flags).open(&path) {
        Ok(f) => Ok(Value::Float(register_fd(f) as f64)),
        Err(e) => Err(err_str("open", &path, &e)),
    }
}

fn open_options(flags: &str) -> std::fs::OpenOptions {
    let mut o = std::fs::OpenOptions::new();
    match flags {
        "r" | "rs" | "sr" => {
            o.read(true);
        }
        "r+" | "rs+" | "sr+" => {
            o.read(true).write(true);
        }
        "w" => {
            o.write(true).create(true).truncate(true);
        }
        "wx" | "xw" => {
            o.write(true).create_new(true);
        }
        "w+" => {
            o.read(true).write(true).create(true).truncate(true);
        }
        "wx+" | "xw+" => {
            o.read(true).write(true).create_new(true);
        }
        "a" => {
            o.append(true).create(true);
        }
        "ax" | "xa" => {
            o.append(true).create_new(true);
        }
        "a+" => {
            o.read(true).append(true).create(true);
        }
        "ax+" | "xa+" => {
            o.read(true).append(true).create_new(true);
        }
        _ => {
            o.read(true);
        }
    }
    o
}

fn close_impl(args: &[Value]) -> Result<Value, String> {
    let fd = arg_num(args, 0) as i32;
    if close_fd(fd) {
        Ok(Value::Undef)
    } else {
        Err("Error: EBADF: bad file descriptor, close".to_string())
    }
}

fn read_impl(args: &[Value]) -> Result<usize, String> {
    let fd = arg_num(args, 0) as i32;
    let buffer = args.get(1).cloned().unwrap_or(Value::Undef);
    let cap = buf_len(&buffer);
    let offset = num_or(args, 2, 0.0) as usize;
    let length = num_or(args, 3, (cap.saturating_sub(offset)) as f64) as usize;
    let position = position_arg(args, 4);
    let n = with_file(fd, |file| {
        let mut fr: &File = file;
        if let Some(pos) = position {
            fr.seek(SeekFrom::Start(pos)).ok();
        }
        let mut buf = vec![0u8; length];
        fr.read(&mut buf).map(|n| {
            buf.truncate(n);
            buf
        })
    });
    match n {
        Some(Ok(data)) => Ok(write_into_buffer(&buffer, offset, &data)),
        Some(Err(e)) => Err(err_str("read", "", &e)),
        None => Err("Error: EBADF: bad file descriptor, read".to_string()),
    }
}

fn write_impl(args: &[Value]) -> Result<usize, String> {
    let fd = arg_num(args, 0) as i32;
    let src = args.get(1).cloned().unwrap_or(Value::Undef);
    let is_buffer = native_tag(&src).as_deref() == Some("Buffer");
    // Buffer form: write(fd, buffer, offset, length, position)
    // String form: write(fd, string, position, encoding)
    let (data, position) = if is_buffer {
        let all = buf_bytes(&src);
        let offset = num_or(args, 2, 0.0) as usize;
        let length = num_or(args, 3, (all.len().saturating_sub(offset)) as f64) as usize;
        let end = (offset + length).min(all.len());
        (
            all[offset.min(all.len())..end].to_vec(),
            position_arg(args, 4),
        )
    } else {
        (
            with_host(|h| h.str_of(&src)).into_bytes(),
            position_arg(args, 2),
        )
    };
    let r = with_file(fd, |file| {
        let mut fr: &File = file;
        if let Some(pos) = position {
            fr.seek(SeekFrom::Start(pos)).ok();
        }
        fr.write(&data)
    });
    match r {
        Some(Ok(n)) => Ok(n),
        Some(Err(e)) => Err(err_str("write", "", &e)),
        None => Err("Error: EBADF: bad file descriptor, write".to_string()),
    }
}

fn readv_impl(args: &[Value]) -> Result<usize, String> {
    let fd = arg_num(args, 0) as i32;
    let buffers = array_items(args.get(1));
    let position = position_arg(args, 2);
    let total = with_file(fd, |file| {
        let mut fr: &File = file;
        if let Some(pos) = position {
            fr.seek(SeekFrom::Start(pos)).ok();
        }
        let mut chunks: Vec<(Value, Vec<u8>)> = Vec::new();
        for b in &buffers {
            let cap = buf_len(b);
            let mut buf = vec![0u8; cap];
            match fr.read(&mut buf) {
                Ok(0) => break,
                Ok(n) => {
                    buf.truncate(n);
                    chunks.push((b.clone(), buf));
                }
                Err(e) => return Err(e),
            }
        }
        Ok(chunks)
    });
    match total {
        Some(Ok(chunks)) => Ok(chunks.iter().map(|(b, d)| write_into_buffer(b, 0, d)).sum()),
        Some(Err(e)) => Err(err_str("readv", "", &e)),
        None => Err("Error: EBADF: bad file descriptor, readv".to_string()),
    }
}

fn writev_impl(args: &[Value]) -> Result<usize, String> {
    let fd = arg_num(args, 0) as i32;
    let buffers = array_items(args.get(1));
    let position = position_arg(args, 2);
    let mut data = Vec::new();
    for b in &buffers {
        data.extend(buf_bytes(b));
    }
    let r = with_file(fd, |file| {
        let mut fr: &File = file;
        if let Some(pos) = position {
            fr.seek(SeekFrom::Start(pos)).ok();
        }
        fr.write(&data)
    });
    match r {
        Some(Ok(n)) => Ok(n),
        Some(Err(e)) => Err(err_str("writev", "", &e)),
        None => Err("Error: EBADF: bad file descriptor, writev".to_string()),
    }
}

fn fstat_impl(args: &[Value]) -> Result<Value, String> {
    let fd = arg_num(args, 0) as i32;
    let md = with_file(fd, |file| file.metadata());
    match md {
        Some(Ok(md)) => Ok(with_host(|h| build_stats(h, &md))),
        Some(Err(e)) => Err(err_str("fstat", "", &e)),
        None => Err("Error: EBADF: bad file descriptor, fstat".to_string()),
    }
}

fn fchmod_impl(args: &[Value]) -> Result<Value, String> {
    let fd = arg_num(args, 0) as i32;
    let mode = arg_num(args, 1) as libc::mode_t;
    let rc = with_file(fd, |file| unsafe { libc::fchmod(file.as_raw_fd(), mode) });
    fd_result(rc, "fchmod")
}

fn fchown_impl(args: &[Value]) -> Result<Value, String> {
    let fd = arg_num(args, 0) as i32;
    let uid = arg_num(args, 1) as libc::uid_t;
    let gid = arg_num(args, 2) as libc::gid_t;
    let rc = with_file(fd, |file| unsafe {
        libc::fchown(file.as_raw_fd(), uid, gid)
    });
    fd_result(rc, "fchown")
}

fn futimes_impl(args: &[Value]) -> Result<Value, String> {
    let fd = arg_num(args, 0) as i32;
    let times = [
        to_timeval(time_secs(args, 1)),
        to_timeval(time_secs(args, 2)),
    ];
    let rc = with_file(fd, |file| unsafe {
        libc::futimes(file.as_raw_fd(), times.as_ptr())
    });
    fd_result(rc, "futimes")
}

fn ftruncate_impl(args: &[Value]) -> Result<Value, String> {
    let fd = arg_num(args, 0) as i32;
    let len = arg_num(args, 1);
    let len = if len.is_nan() { 0 } else { len as u64 };
    match with_file(fd, |file| file.set_len(len)) {
        Some(Ok(_)) => Ok(Value::Undef),
        Some(Err(e)) => Err(err_str("ftruncate", "", &e)),
        None => Err("Error: EBADF: bad file descriptor, ftruncate".to_string()),
    }
}

fn fsync_impl(args: &[Value], data_only: bool) -> Result<Value, String> {
    let fd = arg_num(args, 0) as i32;
    let op = if data_only { "fdatasync" } else { "fsync" };
    let r = with_file(fd, |file| {
        if data_only {
            file.sync_data()
        } else {
            file.sync_all()
        }
    });
    match r {
        Some(Ok(_)) => Ok(Value::Undef),
        Some(Err(e)) => Err(err_str(op, "", &e)),
        None => Err(format!("Error: EBADF: bad file descriptor, {op}")),
    }
}

/// Translate the return of a `with_file` libc call: `None` = bad fd, `Some(0)` =
/// success, `Some(_)` = the C failure whose reason is in `errno`.
fn fd_result(rc: Option<libc::c_int>, op: &str) -> Result<Value, String> {
    match rc {
        Some(0) => Ok(Value::Undef),
        Some(_) => Err(err_str(op, "", &std::io::Error::last_os_error())),
        None => Err(format!("Error: EBADF: bad file descriptor, {op}")),
    }
}

// ── stat / statfs ────────────────────────────────────────────────────────────

fn stat_impl(op: &str, args: &[Value], follow: bool) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let md = if follow {
        std::fs::metadata(&path)
    } else {
        std::fs::symlink_metadata(&path)
    };
    match md {
        Ok(md) => Ok(with_host(|h| build_stats(h, &md))),
        Err(e) => Err(err_str(op, &path, &e)),
    }
}

fn statfs_impl(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let c = cpath(&path, "statfs")?;
    let mut st: libc::statvfs = unsafe { std::mem::zeroed() };
    if unsafe { libc::statvfs(c.as_ptr(), &mut st) } != 0 {
        return Err(err_str("statfs", &path, &std::io::Error::last_os_error()));
    }
    Ok(with_host(|h| {
        let mut m = IndexMap::new();
        m.insert("type".into(), Value::Float(st.f_fsid as f64));
        m.insert("bsize".into(), Value::Float(st.f_bsize as f64));
        m.insert("blocks".into(), Value::Float(st.f_blocks as f64));
        m.insert("bfree".into(), Value::Float(st.f_bfree as f64));
        m.insert("bavail".into(), Value::Float(st.f_bavail as f64));
        m.insert("files".into(), Value::Float(st.f_files as f64));
        m.insert("ffree".into(), Value::Float(st.f_ffree as f64));
        h.new_object(m)
    }))
}

/// Build a full `fs.Stats` object from `Metadata` (unix fields via `MetadataExt`).
fn build_stats(h: &mut crate::host::JsHost, md: &std::fs::Metadata) -> Value {
    let ns = |s: i64, n: i64| s as f64 * 1000.0 + n as f64 / 1_000_000.0;
    let atime_ms = ns(md.atime(), md.atime_nsec());
    let mtime_ms = ns(md.mtime(), md.mtime_nsec());
    let ctime_ms = ns(md.ctime(), md.ctime_nsec());
    let birth_ms = md
        .created()
        .ok()
        .and_then(|t| t.duration_since(UNIX_EPOCH).ok())
        .map(|d| d.as_secs_f64() * 1000.0)
        .unwrap_or(mtime_ms);
    let ft = md.file_type();
    let date = |h: &mut crate::host::JsHost, ms: f64| {
        let mut d = IndexMap::new();
        d.insert("@@native".into(), h.new_str("Date"));
        d.insert("@@ms".into(), Value::Float(ms));
        h.new_object(d)
    };
    let mut m = IndexMap::new();
    m.insert("@@native".into(), h.new_str("Stats"));
    m.insert("@@isFile".into(), Value::Bool(md.is_file()));
    m.insert("@@isDir".into(), Value::Bool(md.is_dir()));
    m.insert("@@isSymlink".into(), Value::Bool(ft.is_symlink()));
    m.insert("dev".into(), Value::Float(md.dev() as f64));
    m.insert("mode".into(), Value::Float(md.mode() as f64));
    m.insert("nlink".into(), Value::Float(md.nlink() as f64));
    m.insert("uid".into(), Value::Float(md.uid() as f64));
    m.insert("gid".into(), Value::Float(md.gid() as f64));
    m.insert("rdev".into(), Value::Float(md.rdev() as f64));
    m.insert("blksize".into(), Value::Float(md.blksize() as f64));
    m.insert("ino".into(), Value::Float(md.ino() as f64));
    m.insert("size".into(), Value::Float(md.len() as f64));
    m.insert("blocks".into(), Value::Float(md.blocks() as f64));
    m.insert("atimeMs".into(), Value::Float(atime_ms));
    m.insert("mtimeMs".into(), Value::Float(mtime_ms));
    m.insert("ctimeMs".into(), Value::Float(ctime_ms));
    m.insert("birthtimeMs".into(), Value::Float(birth_ms));
    let atime = date(h, atime_ms);
    m.insert("atime".into(), atime);
    let mtime = date(h, mtime_ms);
    m.insert("mtime".into(), mtime);
    let ctime = date(h, ctime_ms);
    m.insert("ctime".into(), ctime);
    let birthtime = date(h, birth_ms);
    m.insert("birthtime".into(), birthtime);
    h.new_object(m)
}

// ── watchFile / unwatchFile ──────────────────────────────────────────────────

fn watch_file(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let Some(listener) = args.last().cloned().filter(is_fn) else {
        return Ok(Value::Undef);
    };
    let interval = interval_opt(args).unwrap_or(5007.0).max(1.0) as u64;
    let abs = std::fs::canonicalize(&path)
        .map(|p| p.to_string_lossy().into_owned())
        .unwrap_or_else(|_| path.clone());

    let stop = Arc::new(AtomicBool::new(false));
    let id = NEXT_WATCH_ID.with(|n| {
        let v = *n.borrow();
        *n.borrow_mut() = v + 1;
        v
    });
    WATCHERS.with(|w| {
        w.borrow_mut().push(WatchEntry {
            id,
            path: abs.clone(),
            listener: listener.clone(),
            stop: stop.clone(),
        });
    });
    with_host(|h| h.incr_handle());

    let tx = with_host(|h| h.io_sender());
    let poll_stop = stop.clone();
    let poll_listener = listener;
    std::thread::spawn(move || {
        let mut prev = stat_parts(&abs);
        loop {
            if poll_stop.load(Ordering::Acquire) {
                break;
            }
            std::thread::sleep(Duration::from_millis(interval));
            if poll_stop.load(Ordering::Acquire) {
                break;
            }
            let curr = stat_parts(&abs);
            if curr != prev {
                let l = poll_listener.clone();
                let (p0, p1, p2) = prev;
                let (c0, c1, c2) = curr;
                let _ = tx.send(Box::new(move || {
                    let cur = with_host(|h| stats_from_parts(h, c0, c1, c2));
                    let old = with_host(|h| stats_from_parts(h, p0, p1, p2));
                    if let Err(e) = invoke(&l, vec![cur, old], None) {
                        eprintln!("{e}");
                    }
                    Ok(())
                }));
                prev = curr;
            }
        }
    });
    Ok(Value::Undef)
}

fn unwatch_file(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let abs = std::fs::canonicalize(&path)
        .map(|p| p.to_string_lossy().into_owned())
        .unwrap_or_else(|_| path.clone());
    let listener = args.get(1).cloned().filter(is_fn);
    let removed = WATCHERS.with(|w| {
        let mut w = w.borrow_mut();
        let mut count = 0;
        w.retain(|e| {
            let matches =
                e.path == abs && listener.as_ref().map(|l| *l == e.listener).unwrap_or(true);
            if matches {
                e.stop.store(true, Ordering::Release);
                count += 1;
            }
            !matches
        });
        count
    });
    for _ in 0..removed {
        with_host(|h| h.decr_handle());
    }
    // Wake the event loop so it can re-evaluate the handle count.
    if removed > 0 {
        let _ = with_host(|h| h.io_sender()).send(Box::new(|| Ok(())));
    }
    Ok(Value::Undef)
}

/// A file's watch-relevant state: `(exists, mtime_ms, size)`.
fn stat_parts(path: &str) -> (bool, i64, u64) {
    match std::fs::metadata(path) {
        Ok(md) => (
            true,
            md.mtime() * 1000 + md.mtime_nsec() / 1_000_000,
            md.len(),
        ),
        Err(_) => (false, 0, 0),
    }
}

fn stats_from_parts(h: &mut crate::host::JsHost, exists: bool, mtime_ms: i64, size: u64) -> Value {
    let ms = mtime_ms as f64;
    let date = |h: &mut crate::host::JsHost, ms: f64| {
        let mut d = IndexMap::new();
        d.insert("@@native".into(), h.new_str("Date"));
        d.insert("@@ms".into(), Value::Float(ms));
        h.new_object(d)
    };
    let mut m = IndexMap::new();
    m.insert("@@native".into(), h.new_str("Stats"));
    m.insert("@@isFile".into(), Value::Bool(exists));
    m.insert("@@isDir".into(), Value::Bool(false));
    m.insert("@@isSymlink".into(), Value::Bool(false));
    m.insert(
        "size".into(),
        Value::Float(if exists { size as f64 } else { 0.0 }),
    );
    m.insert("atimeMs".into(), Value::Float(ms));
    m.insert("mtimeMs".into(), Value::Float(ms));
    m.insert("ctimeMs".into(), Value::Float(ms));
    m.insert("birthtimeMs".into(), Value::Float(ms));
    let mt = date(h, ms);
    m.insert("mtime".into(), mt);
    let at = date(h, ms);
    m.insert("atime".into(), at);
    h.new_object(m)
}

// ── read / write streams ─────────────────────────────────────────────────────

fn create_read_stream(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let enc = encoding_arg(args, 1);
    let stream = with_host(|h| {
        let mut extra = IndexMap::new();
        extra.insert("path".into(), h.new_str(path.clone()));
        if let Some(e) = &enc {
            extra.insert("@@encoding".into(), h.new_str(e.clone()));
        }
        extra
    });
    let stream = super::net::new_emitter_object("FSReadStream", stream);
    with_host(|h| h.incr_handle());
    let recv = stream.clone();
    let p = path;
    with_host(|h| {
        h.queue_micro_native(Box::new(move || {
            read_stream_pump(&recv, &p);
            Ok(())
        }))
    });
    Ok(stream)
}

/// Read the whole file and drive the stream's events on the microtask tick after
/// creation (so synchronously-attached `on('data')`/`on('end')` listeners fire).
fn read_stream_pump(recv: &Value, path: &str) {
    with_host(|h| h.decr_handle());
    let bytes = match std::fs::read(path) {
        Ok(b) => b,
        Err(e) => {
            let ev = with_host(|h| crate::builtins::synth_error(h, &err_str("open", path, &e)));
            let _ = super::events::instance_call(
                recv,
                "emit",
                vec![with_host(|h| h.new_str("error")), ev],
            );
            return;
        }
    };
    let enc = get_prop(recv, "@@encoding").map(|v| with_host(|h| h.str_of(&v)));
    let chunk = match enc.as_deref() {
        Some(e) if e != "buffer" => {
            with_host(|h| h.new_str(String::from_utf8_lossy(&bytes).into_owned()))
        }
        _ => super::buffer::from_bytes(&bytes),
    };
    if let Some(dest) = get_prop(recv, "@@pipeDest") {
        let _ = crate::host::call_method(&dest, "write", vec![chunk]);
        let _ = crate::host::call_method(&dest, "end", vec![]);
    } else {
        let name = with_host(|h| h.new_str("data"));
        let _ = super::events::instance_call(recv, "emit", vec![name, chunk]);
    }
    let _ = super::events::instance_call(recv, "emit", vec![with_host(|h| h.new_str("end"))]);
    let _ = super::events::instance_call(recv, "emit", vec![with_host(|h| h.new_str("close"))]);
}

pub const READ_STREAM_METHODS: &[&str] = &[
    "pipe",
    "pause",
    "resume",
    "setEncoding",
    "destroy",
    "close",
    "read",
];

/// `fs.ReadStream` instance dispatch (tag `FSReadStream`). Emitter methods are
/// handled by the parent's shared emitter routing; this covers the stream-only
/// surface.
pub fn read_stream_call(recv: &Value, method: &str, args: Vec<Value>) -> Result<Value, String> {
    match method {
        "pipe" => {
            if let Some(dest) = args.first().cloned() {
                set_prop(recv, "@@pipeDest", dest.clone());
                Ok(dest)
            } else {
                Ok(recv.clone())
            }
        }
        "setEncoding" => {
            set_prop(
                recv,
                "@@encoding",
                with_host(|h| h.new_str(super::arg_str(&args, 0))),
            );
            Ok(recv.clone())
        }
        "pause" | "resume" | "read" => Ok(recv.clone()),
        "destroy" | "close" => {
            let _ =
                super::events::instance_call(recv, "emit", vec![with_host(|h| h.new_str("close"))]);
            Ok(recv.clone())
        }
        _ => Err(crate::host::type_error(&format!(
            "stream.{method} is not a function"
        ))),
    }
}

fn create_write_stream(args: &[Value]) -> Result<Value, String> {
    let path = arg_str(args, 0);
    let flags = match encoding_flag(args, "flags") {
        Some(f) => f,
        None => "w".to_string(),
    };
    let file = open_options(&flags)
        .open(&path)
        .map_err(|e| err_str("open", &path, &e))?;
    let fd = register_fd(file);
    let stream = with_host(|h| {
        let mut extra = IndexMap::new();
        extra.insert("path".into(), h.new_str(path));
        extra.insert("@@wfd".into(), Value::Float(fd as f64));
        extra.insert("bytesWritten".into(), Value::Float(0.0));
        extra
    });
    let stream = super::net::new_emitter_object("FSWriteStream", stream);
    with_host(|h| h.incr_handle());
    let recv = stream.clone();
    with_host(|h| {
        h.queue_micro_native(Box::new(move || {
            let _ =
                super::events::instance_call(&recv, "emit", vec![with_host(|h| h.new_str("open"))]);
            let _ = super::events::instance_call(
                &recv,
                "emit",
                vec![with_host(|h| h.new_str("ready"))],
            );
            Ok(())
        }))
    });
    Ok(stream)
}

pub const WRITE_STREAM_METHODS: &[&str] = &[
    "write",
    "end",
    "destroy",
    "close",
    "cork",
    "uncork",
    "setDefaultEncoding",
];

/// `fs.WriteStream` instance dispatch (tag `FSWriteStream`).
pub fn write_stream_call(recv: &Value, method: &str, args: Vec<Value>) -> Result<Value, String> {
    match method {
        "write" => {
            write_stream_bytes(recv, args.first());
            if let Some(cb) = args.iter().find(|v| is_fn(v)).cloned() {
                let _ = invoke(&cb, vec![], None);
            }
            Ok(Value::Bool(true))
        }
        "end" => {
            if let Some(chunk) = args
                .first()
                .filter(|v| !matches!(v, Value::Undef) && !is_fn(v))
            {
                write_stream_bytes(recv, Some(chunk));
            }
            if let Some(fd) = get_prop(recv, "@@wfd").map(|v| with_host(|h| h.to_number(&v)) as i32)
            {
                close_fd(fd);
            }
            let _ = super::events::instance_call(
                recv,
                "emit",
                vec![with_host(|h| h.new_str("finish"))],
            );
            let _ =
                super::events::instance_call(recv, "emit", vec![with_host(|h| h.new_str("close"))]);
            with_host(|h| h.decr_handle());
            if let Some(cb) = args.iter().find(|v| is_fn(v)).cloned() {
                let _ = invoke(&cb, vec![], None);
            }
            Ok(recv.clone())
        }
        "destroy" | "close" => {
            if let Some(fd) = get_prop(recv, "@@wfd").map(|v| with_host(|h| h.to_number(&v)) as i32)
            {
                close_fd(fd);
            }
            let _ =
                super::events::instance_call(recv, "emit", vec![with_host(|h| h.new_str("close"))]);
            with_host(|h| h.decr_handle());
            Ok(recv.clone())
        }
        "cork" | "uncork" | "setDefaultEncoding" => Ok(recv.clone()),
        _ => Err(crate::host::type_error(&format!(
            "stream.{method} is not a function"
        ))),
    }
}

fn write_stream_bytes(recv: &Value, chunk: Option<&Value>) {
    let Some(chunk) = chunk else { return };
    let data = value_bytes(chunk);
    if let Some(fd) = get_prop(recv, "@@wfd").map(|v| with_host(|h| h.to_number(&v)) as i32) {
        let written = with_file(fd, |file| {
            let mut fr: &File = file;
            fr.write(&data).unwrap_or(0)
        })
        .unwrap_or(0);
        let prev = get_prop(recv, "bytesWritten")
            .map(|v| with_host(|h| h.to_number(&v)))
            .unwrap_or(0.0);
        set_prop(recv, "bytesWritten", Value::Float(prev + written as f64));
    }
}

// ── Stats / Dirent / Dir instance surfaces ───────────────────────────────────

/// `fs.Stats` method dispatch (`isFile`/`isDirectory`/…).
pub fn stats_call(recv: &Value, method: &str) -> Result<Value, String> {
    type_test(recv, method, "stats")
}

pub const DIRENT_METHODS: &[&str] = &[
    "isFile",
    "isDirectory",
    "isSymbolicLink",
    "isBlockDevice",
    "isCharacterDevice",
    "isFIFO",
    "isSocket",
];

/// `fs.Dirent` method dispatch (tag `Dirent`); `name`/`parentPath`/`path` are
/// plain data properties resolved by the generic object path.
pub fn dirent_call(recv: &Value, method: &str) -> Result<Value, String> {
    type_test(recv, method, "dirent")
}

/// Shared `is*` predicates for `Stats` and `Dirent` (both carry `@@isFile`/
/// `@@isDir`/`@@isSymlink`; the device/FIFO/socket predicates are always false —
/// node-js does not model those file types).
fn type_test(recv: &Value, method: &str, what: &str) -> Result<Value, String> {
    let read = |key: &str| {
        with_host(|h| match h.get(recv) {
            Some(JsObj::Object(p)) => matches!(p.get(key), Some(Value::Bool(true))),
            _ => false,
        })
    };
    match method {
        "isFile" => Ok(Value::Bool(read("@@isFile"))),
        "isDirectory" => Ok(Value::Bool(read("@@isDir"))),
        "isSymbolicLink" => Ok(Value::Bool(read("@@isSymlink"))),
        "isBlockDevice" | "isCharacterDevice" | "isFIFO" | "isSocket" => Ok(Value::Bool(false)),
        _ => Err(crate::host::type_error(&format!(
            "{what}.{method} is not a function"
        ))),
    }
}

pub const DIR_METHODS: &[&str] = &["read", "readSync", "close", "closeSync"];

/// `fs.Dir` method dispatch (tag `Dir`); `path` is a plain data property.
pub fn dir_call(recv: &Value, method: &str, args: Vec<Value>) -> Result<Value, String> {
    match method {
        "readSync" => Ok(dir_next(recv)),
        "read" => {
            let v = dir_next(recv);
            if let Some(cb) = args.first().filter(|c| is_fn(c)).cloned() {
                with_host(|h| {
                    let n = h.null();
                    h.queue_micro(cb, vec![n, v]);
                });
                Ok(Value::Undef)
            } else {
                Ok(settled_ok(v))
            }
        }
        "closeSync" => Ok(Value::Undef),
        "close" => {
            if let Some(cb) = args.first().filter(|c| is_fn(c)).cloned() {
                with_host(|h| {
                    let n = h.null();
                    h.queue_micro(cb, vec![n]);
                });
                Ok(Value::Undef)
            } else {
                Ok(settled_ok(Value::Undef))
            }
        }
        _ => Err(crate::host::type_error(&format!(
            "dir.{method} is not a function"
        ))),
    }
}

/// Advance the `Dir` cursor and return the next `Dirent`, or `null` when drained.
fn dir_next(recv: &Value) -> Value {
    with_host(|h| {
        let (entries, pos) = match h.get(recv) {
            Some(JsObj::Object(p)) => (
                p.get("@@entries").cloned(),
                p.get("@@pos").map(|v| h.to_number(v) as usize).unwrap_or(0),
            ),
            _ => (None, 0),
        };
        let item = match entries.as_ref().and_then(|e| h.get(e)) {
            Some(JsObj::Array(items)) => items.get(pos).cloned(),
            _ => None,
        };
        if item.is_some() {
            if let Some(JsObj::Object(p)) = h.get_mut(recv) {
                p.insert("@@pos".into(), Value::Float((pos + 1) as f64));
            }
        }
        item.unwrap_or_else(|| h.null())
    })
}

fn build_dirent(
    h: &mut crate::host::JsHost,
    name: String,
    parent: &str,
    ft: std::fs::FileType,
) -> Value {
    let mut m = IndexMap::new();
    m.insert("@@native".into(), h.new_str("Dirent"));
    m.insert("name".into(), h.new_str(name));
    let pp = h.new_str(parent.to_string());
    m.insert("parentPath".into(), pp.clone());
    m.insert("path".into(), pp);
    m.insert("@@isFile".into(), Value::Bool(ft.is_file()));
    m.insert("@@isDir".into(), Value::Bool(ft.is_dir()));
    m.insert("@@isSymlink".into(), Value::Bool(ft.is_symlink()));
    h.new_object(m)
}

// ── glob ─────────────────────────────────────────────────────────────────────

fn glob_impl(args: &[Value]) -> Result<Value, String> {
    let pattern = arg_str(args, 0);
    let absolute = pattern.starts_with('/');
    let base = if absolute {
        PathBuf::from("/")
    } else {
        std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
    };
    let segs: Vec<String> = pattern
        .split('/')
        .filter(|s| !s.is_empty())
        .map(String::from)
        .collect();
    let mut out: Vec<String> = Vec::new();
    let prefix = if absolute {
        "/".to_string()
    } else {
        String::new()
    };
    glob_walk(&base, &segs, 0, &prefix, &mut out);
    out.sort();
    out.dedup();
    Ok(with_host(|h| {
        let items: Vec<Value> = out.into_iter().map(|s| h.new_str(s)).collect();
        h.new_array(items)
    }))
}

fn glob_walk(dir: &Path, segs: &[String], idx: usize, prefix: &str, out: &mut Vec<String>) {
    if idx >= segs.len() {
        if !prefix.is_empty() && prefix != "/" {
            out.push(prefix.trim_end_matches('/').to_string());
        }
        return;
    }
    let seg = &segs[idx];
    if seg == "**" {
        glob_walk(dir, segs, idx + 1, prefix, out);
        if let Ok(rd) = std::fs::read_dir(dir) {
            for e in rd.flatten() {
                if e.path().is_dir() {
                    let name = e.file_name().to_string_lossy().into_owned();
                    let np = join_glob(prefix, &name);
                    glob_walk(&e.path(), segs, idx, &np, out);
                }
            }
        }
        return;
    }
    let last = idx + 1 == segs.len();
    if let Ok(rd) = std::fs::read_dir(dir) {
        for e in rd.flatten() {
            let name = e.file_name().to_string_lossy().into_owned();
            if name.starts_with('.') && !seg.starts_with('.') {
                continue;
            }
            if wildcard_match(seg, &name) {
                let np = join_glob(prefix, &name);
                if last {
                    out.push(np);
                } else if e.path().is_dir() {
                    glob_walk(&e.path(), segs, idx + 1, &np, out);
                }
            }
        }
    }
}

fn join_glob(prefix: &str, name: &str) -> String {
    if prefix.is_empty() {
        name.to_string()
    } else if prefix.ends_with('/') {
        format!("{prefix}{name}")
    } else {
        format!("{prefix}/{name}")
    }
}

/// Match a single path segment against a `*`/`?` glob (no character classes).
fn wildcard_match(pat: &str, name: &str) -> bool {
    let p: Vec<char> = pat.chars().collect();
    let n: Vec<char> = name.chars().collect();
    let (mut pi, mut ni) = (0usize, 0usize);
    let (mut star, mut mark) = (None, 0usize);
    while ni < n.len() {
        if pi < p.len() && (p[pi] == '?' || p[pi] == n[ni]) {
            pi += 1;
            ni += 1;
        } else if pi < p.len() && p[pi] == '*' {
            star = Some(pi);
            mark = ni;
            pi += 1;
        } else if let Some(s) = star {
            pi = s + 1;
            mark += 1;
            ni = mark;
        } else {
            return false;
        }
    }
    while pi < p.len() && p[pi] == '*' {
        pi += 1;
    }
    pi == p.len()
}

// ── small helpers ────────────────────────────────────────────────────────────

fn settled_ok(v: Value) -> Value {
    let p = with_host(|h| h.new_promise());
    let id = with_host(|h| h.promise_id(&p).unwrap_or(0));
    crate::host::resolve_promise_val(id, v);
    p
}

fn get_prop(recv: &Value, key: &str) -> Option<Value> {
    with_host(|h| match h.get(recv) {
        Some(JsObj::Object(p)) => p.get(key).cloned(),
        _ => None,
    })
}

fn set_prop(recv: &Value, key: &str, val: Value) {
    with_host(|h| {
        if let Some(JsObj::Object(p)) = h.get_mut(recv) {
            p.insert(key.to_string(), val);
        }
    });
}

/// Raw bytes of a Buffer arg, or the utf-8 bytes of anything else.
fn value_bytes(v: &Value) -> Vec<u8> {
    if native_tag(v).as_deref() == Some("Buffer") {
        buf_bytes(v)
    } else {
        with_host(|h| h.str_of(v)).into_bytes()
    }
}

fn buf_bytes(v: &Value) -> Vec<u8> {
    with_host(|h| match h.get(v) {
        Some(JsObj::Object(p)) => match p.get("@@bytes").and_then(|b| h.get(b)) {
            Some(JsObj::Array(items)) => items.iter().map(|x| h.to_number(x) as u8).collect(),
            _ => Vec::new(),
        },
        _ => Vec::new(),
    })
}

fn buf_len(v: &Value) -> usize {
    with_host(|h| match h.get(v) {
        Some(JsObj::Object(p)) => match p.get("@@bytes").and_then(|b| h.get(b)) {
            Some(JsObj::Array(items)) => items.len(),
            _ => 0,
        },
        _ => 0,
    })
}

/// Write `data` into a Buffer's backing byte array at `offset`; returns the count
/// actually written (bounded by the buffer capacity).
fn write_into_buffer(buf: &Value, offset: usize, data: &[u8]) -> usize {
    let Some(arr) = get_prop(buf, "@@bytes") else {
        return 0;
    };
    with_host(|h| {
        if let Some(JsObj::Array(items)) = h.get_mut(&arr) {
            let mut n = 0;
            for (i, b) in data.iter().enumerate() {
                let idx = offset + i;
                if idx >= items.len() {
                    break;
                }
                items[idx] = Value::Float(*b as f64);
                n += 1;
            }
            n
        } else {
            0
        }
    })
}

fn array_items(v: Option<&Value>) -> Vec<Value> {
    match v {
        Some(v) => with_host(|h| match h.get(v) {
            Some(JsObj::Array(items)) => items.clone(),
            _ => Vec::new(),
        }),
        None => Vec::new(),
    }
}

fn opt_flag(args: &[Value], key: &str) -> bool {
    with_host(|h| {
        args.iter().any(|v| {
            matches!(h.get(v), Some(JsObj::Object(p)) if matches!(p.get(key), Some(Value::Bool(true))))
        })
    })
}

fn encoding_flag(args: &[Value], key: &str) -> Option<String> {
    with_host(|h| {
        for v in args {
            if let Some(JsObj::Object(p)) = h.get(v) {
                if let Some(val) = p.get(key) {
                    return Some(h.str_of(val));
                }
            }
        }
        None
    })
}

fn interval_opt(args: &[Value]) -> Option<f64> {
    with_host(|h| {
        for v in args {
            if let Some(JsObj::Object(p)) = h.get(v) {
                if let Some(val) = p.get("interval") {
                    return Some(h.to_number(val));
                }
            }
        }
        None
    })
}

fn num_or(args: &[Value], i: usize, default: f64) -> f64 {
    match args.get(i) {
        Some(v) if !matches!(v, Value::Undef) => {
            let n = with_host(|h| h.to_number(v));
            if n.is_nan() {
                default
            } else {
                n
            }
        }
        _ => default,
    }
}

/// A byte `position` argument: `null`/`undefined` means "current file offset".
fn position_arg(args: &[Value], i: usize) -> Option<u64> {
    match args.get(i) {
        Some(Value::Undef) | None => None,
        Some(v) if with_host(|h| h.is_null(v)) => None,
        Some(v) => {
            let n = with_host(|h| h.to_number(v));
            if n.is_nan() || n < 0.0 {
                None
            } else {
                Some(n as u64)
            }
        }
    }
}

/// A timestamp argument in **seconds**. A `Date` argument stores milliseconds, so
/// divide; a bare number is already seconds (Node's `fs.utimes` convention).
fn time_secs(args: &[Value], i: usize) -> f64 {
    match args.get(i) {
        Some(v) if native_tag(v).as_deref() == Some("Date") => arg_num(args, i) / 1000.0,
        _ => arg_num(args, i),
    }
}

fn to_timeval(secs: f64) -> libc::timeval {
    let s = secs.floor();
    let us = ((secs - s) * 1_000_000.0).round();
    libc::timeval {
        tv_sec: s as libc::time_t,
        tv_usec: us as libc::suseconds_t,
    }
}

fn cpath(path: &str, op: &str) -> Result<CString, String> {
    CString::new(path).map_err(|_| format!("Error: EINVAL: invalid argument, {op} '{path}'"))
}

fn ok_or_errno(rc: libc::c_int, op: &str, path: &str) -> Result<Value, String> {
    if rc == 0 {
        Ok(Value::Undef)
    } else {
        Err(err_str(op, path, &std::io::Error::last_os_error()))
    }
}

fn encoding_arg(args: &[Value], i: usize) -> Option<String> {
    match args.get(i) {
        Some(Value::Undef) | None => None,
        Some(v) => {
            let s = with_host(|h| h.str_of(v));
            if s == "undefined" || s == "[object Object]" || s == "null" {
                None
            } else {
                Some(s)
            }
        }
    }
}

/// The failing *syscall* Node names in a filesystem error, for the JS-level
/// entry points whose API name differs from it. `fs.readFileSync('/nope')`
/// reports `open`, not `readFileSync`, because `open(2)` is what failed —
/// and `err.syscall` is load-bearing for packages that branch on it.
fn syscall_name(op: &str) -> &str {
    match op {
        "readFileSync" | "readFile" | "writeFile" | "writeFileSync" | "appendFile"
        | "appendFileSync" | "createReadStream" | "createWriteStream" => "open",
        "readdir" | "readdirSync" | "opendir" => "scandir",
        other => other,
    }
}

/// The `CODE: reason` half of a libuv error message (`ENOENT: no such file or
/// directory`), shared by every syscall wrapper that has to render one.
///
/// Deliberately NOT Rust's `io::Error` `Display`: Rust capitalizes and appends
/// its own `(os error 2)`, so `No such file or directory (os error 2)` is a
/// string no Node has ever printed. `process.chdir` was assembling its message
/// that way.
pub(crate) fn libuv_message(e: &std::io::Error) -> String {
    use std::io::ErrorKind::*;
    let code = match e.kind() {
        NotFound => "ENOENT",
        PermissionDenied => "EACCES",
        AlreadyExists => "EEXIST",
        NotADirectory => "ENOTDIR",
        IsADirectory => "EISDIR",
        DirectoryNotEmpty => "ENOTEMPTY",
        InvalidInput => "EINVAL",
        BrokenPipe => "EPIPE",
        _ => "EIO",
    };
    format!("{code}: {}", libuv_reason(code))
}

/// libuv's own lowercase reason string for a code.
fn libuv_reason(code: &str) -> &'static str {
    match code {
        "ENOENT" => "no such file or directory",
        "EACCES" => "permission denied",
        "EEXIST" => "file already exists",
        "ENOTDIR" => "not a directory",
        "EISDIR" => "illegal operation on a directory",
        "ENOTEMPTY" => "directory not empty",
        "EINVAL" => "invalid argument",
        "EPIPE" => "broken pipe",
        _ => "i/o error",
    }
}

fn err_str(op: &str, path: &str, e: &std::io::Error) -> String {
    use std::io::ErrorKind::*;
    let code = match e.kind() {
        NotFound => "ENOENT",
        PermissionDenied => "EACCES",
        AlreadyExists => "EEXIST",
        NotADirectory => "ENOTDIR",
        IsADirectory => "EISDIR",
        DirectoryNotEmpty => "ENOTEMPTY",
        InvalidInput => "EINVAL",
        BrokenPipe => "EPIPE",
        _ => "EIO",
    };
    // libuv's own reason strings, not Rust's `io::Error` `Display` — Rust
    // capitalizes ("No such file or directory") where libuv (and therefore
    // Node's `err.message`) does not.
    let reason = libuv_reason(code);
    let op = syscall_name(op);
    if path.is_empty() {
        format!("Error: {code}: {reason}, {op}")
    } else {
        format!("Error: {code}: {reason}, {op} '{path}'")
    }
}