stryke/

perl_fs.rs

//! Perl-style filesystem helpers (`stat`, `glob`, etc.).

use rand::Rng;
use rayon::prelude::*;
use std::env;
use std::io::{self, BufRead, Write};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::UNIX_EPOCH;

use crate::pmap_progress::PmapProgress;
use crate::value::StrykeValue;
use parking_lot::{Mutex, RwLock};

/// zshrs `glob()` and [`StrykeGlobOptsGuard`] both touch zshrs process-global option
/// state. `glob_par` invokes `stryke_glob` from rayon workers while other threads run
/// plain `glob` — interleaved guard `new`/`Drop` corrupts `bareglobqual` / `nullglob`
/// and breaks qualifier parsing (e.g. `(N)`), yielding mass false positives. Serialize
/// the option snapshot + expansion critical section (same cost order as one glob at a
/// time; `glob_par` still parallelizes unrelated work outside zsh).
static ZSH_GLOB_GLOBAL_MUTEX: Mutex<()> = Mutex::new(());

/// Keys touched by [`StrykeGlobOptsGuard`] — must match restore in `Drop`.
const STRYKE_GLOB_OPT_KEYS: &[&str] = &[
    "nullglob",
    "markdirs",
    "dotglob",
    "globdots",
    "listtypes",
    "numericglobsort",
    "chaselinks",
    "extendedglob",
    "caseglob",
    "nocaseglob",
    "globstarshort",
    "bareglobqual",
    "braceccl",
];

/// zshrs `glob()` reads options from the global store (`opt_state_*`). Apply
/// the former `GlobOptions` preset for this expansion only, then restore on drop.
pub(crate) struct StrykeGlobOptsGuard {
    snap: std::collections::HashMap<String, bool>,
}

impl StrykeGlobOptsGuard {
    pub(crate) fn new() -> Self {
        let snap = zsh::options::opt_state_snapshot();
        zsh::options::opt_state_set("nullglob", true);
        zsh::options::opt_state_set("markdirs", false);
        zsh::options::opt_state_set("dotglob", false);
        zsh::options::opt_state_set("globdots", false);
        zsh::options::opt_state_set("listtypes", false);
        zsh::options::opt_state_set("numericglobsort", false);
        zsh::options::opt_state_set("chaselinks", false);
        zsh::options::opt_state_set("extendedglob", true);
        zsh::options::opt_state_set("caseglob", true);
        zsh::options::opt_state_set("nocaseglob", false);
        zsh::options::opt_state_set("globstarshort", true);
        zsh::options::opt_state_set("bareglobqual", true);
        zsh::options::opt_state_set("braceccl", true);
        Self { snap }
    }
}

impl Drop for StrykeGlobOptsGuard {
    fn drop(&mut self) {
        for &key in STRYKE_GLOB_OPT_KEYS {
            if let Some(v) = self.snap.get(key) {
                zsh::options::opt_state_set(key, *v);
            } else {
                zsh::options::opt_state_unset(key);
            }
        }
    }
}

pub use crate::perl_decode::{
    decode_utf8_or_latin1, decode_utf8_or_latin1_line, decode_utf8_or_latin1_read_until,
};

/// Read a file as text for Perl source or slurped data. Unlike [`std::fs::read_to_string`], this
/// does not reject bytes that are not valid UTF-8 (stock `perl` accepts such files by default).
pub fn read_file_text_perl_compat(path: impl AsRef<Path>) -> io::Result<String> {
    let bytes = std::fs::read(path.as_ref())?;
    Ok(decode_utf8_or_latin1(&bytes))
}

/// `haswilds` on a raw (untokenized) pattern. zshrs 0.11.47's `haswilds`
/// recognizes only glob-TOKENIZED metacharacters (`Star` = U+0087, etc.); 0.11.29
/// also matched bare `*` / `?` / `[`. strykelang hands the glob engine raw
/// patterns, so without tokenizing a copy first every glob is misclassified as a
/// literal path and returned verbatim instead of being expanded.
pub(crate) fn raw_haswilds(pattern: &str) -> bool {
    let mut tok = pattern.to_string();
    zsh::glob::tokenize(&mut tok);
    zsh::ported::pattern::haswilds(&tok)
}

/// Preset for stryke glob (via [`StrykeGlobOptsGuard`] + `zsh::glob::glob_path`): full
/// extended glob, bare-qualifier shorthand on (`*(/)` works without `(#q.../)`),
/// `nullglob` requested so a no-match yields an empty list (Perl `glob` semantics);
/// since 0.11.47's `glob_path` no longer honors that on its own, the empty-on-no-match
/// guarantee is enforced by the post-pass below that drops the echoed pattern.
/// `globstarshort` makes `**.stk` match every `.stk` file at any depth; `braceccl`
/// enables `{a,b,c}` / `{abc}` brace expansion — wired through zshrs's global option
/// store like stock zsh.
pub(crate) fn stryke_glob(pattern: &str) -> Vec<String> {
    // zshrs glob fails to match wildcards behind a `./` directory segment
    // (works for literal filenames but not patterns like `./lib/*.stk`,
    // nor for `/abs/./lib/*.stk` which `resolve_stryke_path` produces when
    // joining cwd with a `./`-prefixed relative path). Collapse leading
    // `./` and mid-path `/./` before delegating, then re-prepend the
    // leading `./` to each result so callers see the form they asked for.
    // `.` as a directory component is always the current directory; no
    // filesystem entry can legitimately bear that name, so collapsing is
    // safe and matches OS / `std::fs` behaviour.
    let (stripped_leading, had_dot_slash) = if let Some(rest) = pattern.strip_prefix("./") {
        (rest.to_string(), true)
    } else {
        (pattern.to_string(), false)
    };
    let normalized = stripped_leading.replace("/./", "/");
    let is_relative_pattern = !std::path::Path::new(&normalized).is_absolute();

    // zshrs 0.11.47's `glob_path` is a thin wrapper over `globdata_glob`, whose
    // matcher recognizes only glob-TOKENIZED metacharacters (`Star` = U+0087,
    // etc.) as wildcards — the production prefork path hands it token bytes. A
    // raw `*` reaches the matcher as a literal char, matches nothing, and the
    // pattern echoes back (0.11.46's standalone `glob_path` matched raw strings;
    // the 0.11.47 rewrite dropped that tolerance). Tokenize before delegating so
    // the matcher sees real wildcards. EXCEPTION: a trailing `(...)` qualifier
    // stays raw — `parse_qualifiers` scans for a literal `)` (a tokenized
    // `Outpar` is invisible to it), and the qualifier-driven walk already
    // handles raw `**`/`*` correctly, so tokenizing a qualifier pattern would
    // strip its `**` recursion.
    let has_qual = zsh::glob::split_qualifier(&normalized).1.is_some();
    let glob_arg = if has_qual {
        normalized.clone()
    } else {
        let mut tok = normalized.clone();
        zsh::glob::tokenize(&mut tok);
        tok
    };
    let results = {
        let _lock = ZSH_GLOB_GLOBAL_MUTEX.lock();
        let _opts = StrykeGlobOptsGuard::new();
        zsh::glob::glob_path(&glob_arg)
    };

    // `globdata_glob` echoes the literal (untokenized) pattern back on no-match
    // instead of honoring nullglob — the 0.11.47 port dropped the `gf_nullglob`
    // empty-result guard from the c:1872-1888 terminal block, so the
    // ordinary-string fallback fires even with `nullglob` set. stryke wants Perl
    // nullglob semantics (empty list on no match), so when the sole "match" is
    // the pattern itself echoed back AND the pattern actually globs (has a
    // wildcard or qualifier — a literal path legitimately equals its own match),
    // suppress it.
    let results = if results.len() == 1
        && results[0] == normalized
        && (has_qual || zsh::ported::pattern::haswilds(&glob_arg))
    {
        Vec::new()
    } else {
        results
    };
    // zshrs emits absolute paths even when called with a relative pattern;
    // strip the cwd prefix so the user sees what they asked for. Leading-`./`
    // patterns get the prefix re-attached (existing contract); other relative
    // patterns return bare relative paths. Check both the raw cwd and its
    // canonical form because macOS reports `/var/...` via `current_dir()` but
    // the glob engine emits the canonical `/private/var/...`.
    let stripped: Vec<String> = if is_relative_pattern {
        let cwd = std::env::current_dir().ok();
        let cwd_canonical = cwd
            .as_ref()
            .and_then(|p| std::fs::canonicalize(p).ok())
            .map(|p| p.to_string_lossy().into_owned());
        let cwd_plain = cwd.as_ref().map(|p| p.to_string_lossy().into_owned());
        results
            .into_iter()
            .map(|p| {
                for pref in [cwd_canonical.as_deref(), cwd_plain.as_deref()]
                    .into_iter()
                    .flatten()
                {
                    if let Some(rest) = p.strip_prefix(pref) {
                        let r = rest.trim_start_matches('/');
                        return if r.is_empty() {
                            ".".to_string()
                        } else {
                            r.to_string()
                        };
                    }
                }
                p
            })
            .collect()
    } else {
        results
    };
    if had_dot_slash {
        stripped
            .into_iter()
            .map(|p| {
                if p.starts_with("./") {
                    p
                } else {
                    format!("./{}", p)
                }
            })
            .collect()
    } else {
        stripped
    }
}

/// `slurp`/`cat`/`c` payload — accepts a literal path OR a zsh-style glob
/// pattern (forwarded to [`zsh::glob`], so the entire qualifier set `(/)`,
/// `(.)`, `(@)`, `(L+10)`, `(mh-1)`, `(om)`, `(N)`, … all work). World-first:
/// zsh glob qualifiers in a scripting language. When the qualifier filters
/// away every regular file (e.g. `c("**(/)")` returns directories only) we
/// hard-fail rather than silently return empty — slurping a directory is
/// meaningless and asking for it is a bug.
///
/// Routing: a path goes through the glob expander when it has wildcards
/// (per zshrs's [`zsh::ported::pattern::haswilds`]) OR a trailing bare qualifier
/// suffix (`dir(/)` / `name(.)`). Otherwise we read the literal path so a
/// missing file produces the proper `No such file or directory` instead of
/// a silent empty.
pub fn read_file_text_or_glob(path: &str) -> io::Result<String> {
    let (stripped, qual) = zsh::glob::split_qualifier(path);
    let is_glob = qual.is_some() || raw_haswilds(stripped);
    if !is_glob {
        return read_file_text_perl_compat(path);
    }
    let paths = stryke_glob(path);
    if paths.is_empty() {
        return Err(io::Error::new(
            io::ErrorKind::NotFound,
            format!("no files matched glob: {}", path),
        ));
    }
    let strict = qual.is_some();
    let mut out = String::new();
    for p in &paths {
        match slurp_glob_entry(p, strict, |p| read_file_text_perl_compat(p))? {
            Some(s) => out.push_str(&s),
            None => continue,
        }
    }
    Ok(out)
}

/// Shared per-entry policy for slurp-over-a-glob. A qualifier glob (`**(/)`) is
/// an explicit selection, so `strict` hard-fails on any non-regular or
/// unreadable match (and the error now names the offending path). A plain
/// wildcard sweep (`**.rs`) is broad and incidental: a dangling symlink,
/// vanished file, or directory caught by the pattern is skipped (logged at
/// debug) so one bad entry can't abort the whole sweep — matching `grep -r` /
/// `cat`-over-a-glob. Returns `Ok(None)` for a skipped entry.
fn slurp_glob_entry<T>(
    p: &str,
    strict: bool,
    read: impl FnOnce(&str) -> io::Result<T>,
) -> io::Result<Option<T>> {
    let meta = match std::fs::metadata(p) {
        Ok(m) => m,
        Err(e) => {
            if strict {
                return Err(io::Error::new(e.kind(), format!("{}: {}", p, e)));
            }
            tracing::debug!("slurp: skipping unreadable glob match {}: {}", p, e);
            return Ok(None);
        }
    };
    if !meta.is_file() {
        if strict {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                format!("not a regular file: {}", p),
            ));
        }
        tracing::debug!("slurp: skipping non-regular glob match: {}", p);
        return Ok(None);
    }
    match read(p) {
        Ok(v) => Ok(Some(v)),
        Err(e) => {
            if strict {
                return Err(io::Error::new(e.kind(), format!("{}: {}", p, e)));
            }
            tracing::debug!("slurp: skipping unreadable glob match {}: {}", p, e);
            Ok(None)
        }
    }
}

/// Bytes-faithful slurp: matches Perl's default byte-string semantics. Returns the
/// concatenated raw bytes for a glob, or the raw bytes of a single file. The
/// returned [`StrykeValue::bytes`] stringifies via `decode_utf8_or_latin1` so
/// `eq`/regex/substr on text content still match, while `length()` reports byte
/// count and `spew`/encoders see the original bytes — making `slurp` byte-perfect
/// for binary files without changing text-file behaviour.
pub fn read_bytes_or_glob(path: &str) -> io::Result<Arc<Vec<u8>>> {
    let (stripped, qual) = zsh::glob::split_qualifier(path);
    let is_glob = qual.is_some() || raw_haswilds(stripped);
    if !is_glob {
        return read_file_bytes(path);
    }
    let paths = stryke_glob(path);
    if paths.is_empty() {
        return Err(io::Error::new(
            io::ErrorKind::NotFound,
            format!("no files matched glob: {}", path),
        ));
    }
    let strict = qual.is_some();
    let mut out = Vec::new();
    for p in &paths {
        match slurp_glob_entry(p, strict, |p| std::fs::read(p))? {
            Some(bytes) => out.extend_from_slice(&bytes),
            None => continue,
        }
    }
    Ok(Arc::new(out))
}

/// Pattern routes to [`zsh::glob`] when it has wildcards or a bare qualifier
/// suffix; literal paths short-circuit so callers can preserve "no such
/// file" diagnostics. Wraps zshrs's own predicates so stryke owns no
/// pattern-parsing logic of its own.
fn pattern_is_glob(path: &str) -> bool {
    let (stripped, qual) = zsh::glob::split_qualifier(path);
    qual.is_some() || raw_haswilds(stripped) || zsh::glob::hasbraces(stripped, true)
}

/// Like [`BufRead::read_line`] but decodes with [`decode_utf8_or_latin1_read_until`] (no U+FFFD).
pub fn read_line_perl_compat(reader: &mut impl BufRead, buf: &mut String) -> io::Result<usize> {
    read_line_perl_compat_with_sep(reader, buf, Some(b'\n'))
}

/// Like [`read_line_perl_compat`] but honors an explicit input record separator byte. Mirrors
/// perl `$/`:
/// - `Some(byte)` — read until `byte`; trailing `byte` is included in the buffer.
/// - `None`       — slurp: read to EOF.
pub fn read_line_perl_compat_with_sep(
    reader: &mut impl BufRead,
    buf: &mut String,
    sep: Option<u8>,
) -> io::Result<usize> {
    buf.clear();
    let mut raw = Vec::new();
    let n = match sep {
        None => reader.read_to_end(&mut raw)?,
        Some(byte) => reader.read_until(byte, &mut raw)?,
    };
    if n == 0 {
        return Ok(0);
    }
    buf.push_str(&decode_utf8_or_latin1_read_until(&raw));
    Ok(n)
}

/// One line from `reader` (delimiter `\n`), content **without** trailing `\n` / `\r\n` / `\r`,
/// same as [`BufRead::lines`] but UTF-8 or Latin-1 per line.
///
/// Legacy newline-stripping reader kept for out-of-tree callers. New callers in line-mode
/// processing should use [`read_logical_line_perl_compat_with_sep`] (which preserves the
/// separator in the record per perl `<>` semantics) plus the caller's own chomp logic.
pub fn read_logical_line_perl_compat(reader: &mut impl BufRead) -> io::Result<Option<String>> {
    let mut buf = Vec::new();
    let n = reader.read_until(b'\n', &mut buf)?;
    if n == 0 {
        return Ok(None);
    }
    if buf.ends_with(b"\n") {
        buf.pop();
        if buf.ends_with(b"\r") {
            buf.pop();
        }
    }
    Ok(Some(decode_utf8_or_latin1_line(&buf)))
}

/// One record from `reader` honoring an explicit input record separator byte. Matches perl's
/// `<>` which leaves the IRS *in* `$_` — chomp / `-l` strip the IRS in the autoprint pipeline,
/// not at the reader.
///
/// - `Some(byte)` — read until `byte`; trailing `byte` (and `\r` adjacent for `\n`) is kept in the
///   returned record so the caller can emit it verbatim (perl `-p` behavior) or chomp it
///   (perl `-l` / explicit chomp).
/// - `None` — slurp mode (perl `-0777`): reads to EOF as one record.
pub fn read_logical_line_perl_compat_with_sep(
    reader: &mut impl BufRead,
    sep: Option<u8>,
) -> io::Result<Option<String>> {
    let mut buf = Vec::new();
    let n = match sep {
        None => reader.read_to_end(&mut buf)?,
        Some(byte) => reader.read_until(byte, &mut buf)?,
    };
    if n == 0 {
        return Ok(None);
    }
    Ok(Some(decode_utf8_or_latin1_line(&buf)))
}

/// Perl `-t` — true if the handle/path refers to a terminal ([`libc::isatty`] on Unix).
/// Recognizes `STDIN`/`STDOUT`/`STDERR`, `/dev/stdin` (etc.), `/dev/fd/N`, small numeric fds, or opens a path and tests its fd.
pub fn filetest_is_tty(path: &str) -> bool {
    #[cfg(unix)]
    {
        use std::os::unix::io::AsRawFd;
        if let Some(fd) = tty_fd_literal(path) {
            return unsafe { libc::isatty(fd) != 0 };
        }
        if let Ok(f) = std::fs::File::open(path) {
            return unsafe { libc::isatty(f.as_raw_fd()) != 0 };
        }
    }
    #[cfg(not(unix))]
    {
        let _ = path;
    }
    false
}

#[cfg(unix)]
fn tty_fd_literal(path: &str) -> Option<i32> {
    match path {
        "" | "STDIN" | "-" | "/dev/stdin" => Some(0),
        "STDOUT" | "/dev/stdout" => Some(1),
        "STDERR" | "/dev/stderr" => Some(2),
        p if p.starts_with("/dev/fd/") => p.strip_prefix("/dev/fd/").and_then(|s| s.parse().ok()),
        _ => path.parse::<i32>().ok().filter(|&n| (0..128).contains(&n)),
    }
}

/// Check if effective uid/gid has the given access to a file.
/// `check` is one of 4 (read), 2 (write), 1 (execute).
#[cfg(unix)]
pub fn filetest_effective_access(path: &str, check: u32) -> bool {
    use std::os::unix::fs::MetadataExt;
    let meta = match std::fs::metadata(path) {
        Ok(m) => m,
        Err(_) => return false,
    };
    let mode = meta.mode();
    let euid = unsafe { libc::geteuid() };
    let egid = unsafe { libc::getegid() };
    // Root can read/write anything, execute if any x bit set
    if euid == 0 {
        return if check == 1 { mode & 0o111 != 0 } else { true };
    }
    if meta.uid() == euid {
        return mode & (check << 6) != 0;
    }
    if meta.gid() == egid {
        return mode & (check << 3) != 0;
    }
    mode & check != 0
}

/// Check if real uid/gid has the given access (uses libc::access).
#[cfg(unix)]
pub fn filetest_real_access(path: &str, amode: libc::c_int) -> bool {
    match std::ffi::CString::new(path) {
        Ok(c) => unsafe { libc::access(c.as_ptr(), amode) == 0 },
        Err(_) => false,
    }
}

/// Is the file owned by effective uid?
#[cfg(unix)]
pub fn filetest_owned_effective(path: &str) -> bool {
    use std::os::unix::fs::MetadataExt;
    std::fs::metadata(path)
        .map(|m| m.uid() == unsafe { libc::geteuid() })
        .unwrap_or(false)
}

/// Is the file owned by real uid?
#[cfg(unix)]
pub fn filetest_owned_real(path: &str) -> bool {
    use std::os::unix::fs::MetadataExt;
    std::fs::metadata(path)
        .map(|m| m.uid() == unsafe { libc::getuid() })
        .unwrap_or(false)
}

/// Is the file a named pipe (FIFO)?
#[cfg(unix)]
pub fn filetest_is_pipe(path: &str) -> bool {
    use std::os::unix::fs::FileTypeExt;
    std::fs::metadata(path)
        .map(|m| m.file_type().is_fifo())
        .unwrap_or(false)
}

/// Is the file a socket?
#[cfg(unix)]
pub fn filetest_is_socket(path: &str) -> bool {
    use std::os::unix::fs::FileTypeExt;
    std::fs::metadata(path)
        .map(|m| m.file_type().is_socket())
        .unwrap_or(false)
}

/// Is the file a block device?
#[cfg(unix)]
pub fn filetest_is_block_device(path: &str) -> bool {
    use std::os::unix::fs::FileTypeExt;
    std::fs::metadata(path)
        .map(|m| m.file_type().is_block_device())
        .unwrap_or(false)
}

/// Is the file a character device?
#[cfg(unix)]
pub fn filetest_is_char_device(path: &str) -> bool {
    use std::os::unix::fs::FileTypeExt;
    std::fs::metadata(path)
        .map(|m| m.file_type().is_char_device())
        .unwrap_or(false)
}

/// Is setuid bit set?
#[cfg(unix)]
pub fn filetest_is_setuid(path: &str) -> bool {
    use std::os::unix::fs::MetadataExt;
    std::fs::metadata(path)
        .map(|m| m.mode() & 0o4000 != 0)
        .unwrap_or(false)
}

/// Is setgid bit set?
#[cfg(unix)]
pub fn filetest_is_setgid(path: &str) -> bool {
    use std::os::unix::fs::MetadataExt;
    std::fs::metadata(path)
        .map(|m| m.mode() & 0o2000 != 0)
        .unwrap_or(false)
}

/// Is sticky bit set?
#[cfg(unix)]
pub fn filetest_is_sticky(path: &str) -> bool {
    use std::os::unix::fs::MetadataExt;
    std::fs::metadata(path)
        .map(|m| m.mode() & 0o1000 != 0)
        .unwrap_or(false)
}

/// Is the file a text file? (Perl heuristic: read first block, check for high proportion of printable chars)
pub fn filetest_is_text(path: &str) -> bool {
    filetest_text_binary(path, true)
}

/// Is the file a binary file? (opposite of text)
pub fn filetest_is_binary(path: &str) -> bool {
    filetest_text_binary(path, false)
}

fn filetest_text_binary(path: &str, want_text: bool) -> bool {
    use std::io::Read;
    let mut f = match std::fs::File::open(path) {
        Ok(f) => f,
        Err(_) => return false,
    };
    let mut buf = [0u8; 512];
    let n = match f.read(&mut buf) {
        Ok(n) => n,
        Err(_) => return false,
    };
    if n == 0 {
        // Empty files are considered text in Perl
        return want_text;
    }
    let slice = &buf[..n];
    // Count bytes that are "non-text": NUL and control chars (except \t \n \r \x1b)
    let non_text = slice
        .iter()
        .filter(|&&b| b == 0 || (b < 0x20 && b != b'\t' && b != b'\n' && b != b'\r' && b != 0x1b))
        .count();
    let is_text = (non_text as f64 / n as f64) < 0.30;
    if want_text {
        is_text
    } else {
        !is_text
    }
}

/// File age in fractional days since now. `which`: 'M' = mtime, 'A' = atime, 'C' = ctime.
#[cfg(unix)]
pub fn filetest_age_days(path: &str, which: char) -> Option<f64> {
    use std::os::unix::fs::MetadataExt;
    let meta = std::fs::metadata(path).ok()?;
    let t = match which {
        'M' => meta.mtime() as f64,
        'A' => meta.atime() as f64,
        _ => meta.ctime() as f64,
    };
    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs_f64();
    Some((now - t) / 86400.0)
}

/// 13-element `stat` / `lstat` list (empty vector on failure).
pub fn stat_path(path: &str, symlink: bool) -> StrykeValue {
    let res = if symlink {
        std::fs::symlink_metadata(path)
    } else {
        std::fs::metadata(path)
    };
    match res {
        Ok(meta) => StrykeValue::array(perl_stat_from_metadata(&meta)),
        Err(_) => StrykeValue::array(vec![]),
    }
}
/// `perl_stat_from_metadata` — see implementation.
pub fn perl_stat_from_metadata(meta: &std::fs::Metadata) -> Vec<StrykeValue> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        vec![
            StrykeValue::integer(meta.dev() as i64),
            StrykeValue::integer(meta.ino() as i64),
            StrykeValue::integer(meta.mode() as i64),
            StrykeValue::integer(meta.nlink() as i64),
            StrykeValue::integer(meta.uid() as i64),
            StrykeValue::integer(meta.gid() as i64),
            StrykeValue::integer(meta.rdev() as i64),
            StrykeValue::integer(meta.len() as i64),
            StrykeValue::integer(meta.atime()),
            StrykeValue::integer(meta.mtime()),
            StrykeValue::integer(meta.ctime()),
            StrykeValue::integer(meta.blksize() as i64),
            StrykeValue::integer(meta.blocks() as i64),
        ]
    }
    #[cfg(not(unix))]
    {
        let len = meta.len() as i64;
        vec![
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(len),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
            StrykeValue::integer(0),
        ]
    }
}
/// `link_hard` — see implementation.
pub fn link_hard(old: &str, new: &str) -> StrykeValue {
    StrykeValue::integer(if std::fs::hard_link(old, new).is_ok() {
        1
    } else {
        0
    })
}
/// `link_sym` — see implementation.
pub fn link_sym(old: &str, new: &str) -> StrykeValue {
    #[cfg(unix)]
    {
        use std::os::unix::fs::symlink;
        StrykeValue::integer(if symlink(old, new).is_ok() { 1 } else { 0 })
    }
    #[cfg(not(unix))]
    {
        let _ = (old, new);
        StrykeValue::integer(0)
    }
}
/// `read_link` — see implementation.
pub fn read_link(path: &str) -> StrykeValue {
    match std::fs::read_link(path) {
        Ok(p) => StrykeValue::string(p.to_string_lossy().into_owned()),
        Err(_) => StrykeValue::UNDEF,
    }
}

/// Absolute path with symlinks resolved (`std::fs::canonicalize`); all path components must exist.
pub fn realpath_resolved(path: &str) -> io::Result<String> {
    std::fs::canonicalize(path).map(|p| p.to_string_lossy().into_owned())
}

/// Normalize `.` / `..` and redundant separators without touching the disk (Perl
/// `File::Spec->canonpath`-like). Unlike [`std::path::Path::components`] alone, this collapses
/// `foo/..` in relative paths instead of preserving `..` for symlink safety.
pub fn canonpath_logical(path: &str) -> String {
    use std::path::Component;
    if path.is_empty() {
        return String::new();
    }
    let mut stack: Vec<String> = Vec::new();
    let mut anchored = false;
    for c in Path::new(path).components() {
        match c {
            Component::Prefix(p) => {
                stack.push(p.as_os_str().to_string_lossy().into_owned());
            }
            Component::RootDir => {
                anchored = true;
                stack.clear();
            }
            Component::CurDir => {}
            Component::Normal(s) => {
                stack.push(s.to_string_lossy().into_owned());
            }
            Component::ParentDir => {
                if anchored {
                    if !stack.is_empty() {
                        stack.pop();
                    }
                } else if stack.is_empty() || stack.last().is_some_and(|t| t == "..") {
                    stack.push("..".to_string());
                } else {
                    stack.pop();
                }
            }
        }
    }
    let body = stack.join("/");
    if anchored {
        if body.is_empty() {
            "/".to_string()
        } else {
            format!("/{body}")
        }
    } else if body.is_empty() {
        ".".to_string()
    } else {
        body
    }
}

/// List file/directory names inside `dir` (non-recursive), sorted.
/// Returns an empty list if `dir` cannot be read.
pub fn list_files(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    if let Ok(entries) = std::fs::read_dir(dir) {
        for entry in entries.flatten() {
            if let Some(name) = entry.file_name().to_str() {
                names.push(name.to_string());
            }
        }
    }
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}

/// List only regular file names inside `dir` (non-recursive), sorted.
/// Excludes directories, symlinks, and special files.
/// Returns an empty list if `dir` cannot be read.
pub fn list_filesf(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    if let Ok(entries) = std::fs::read_dir(dir) {
        for entry in entries.flatten() {
            if entry.file_type().map(|ft| ft.is_file()).unwrap_or(false) {
                if let Some(name) = entry.file_name().to_str() {
                    names.push(name.to_string());
                }
            }
        }
    }
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}

/// List only regular file paths under `dir` **recursively**, sorted.
/// Returns relative paths from `dir` (e.g. `"sub/file.txt"`).
/// Returns an empty list if `dir` cannot be read.
pub fn list_filesf_recursive(dir: &str) -> StrykeValue {
    let root = std::path::Path::new(dir);
    let mut paths: Vec<String> = Vec::new();
    fn walk(base: &std::path::Path, rel: &str, out: &mut Vec<String>) {
        let Ok(entries) = std::fs::read_dir(base) else {
            return;
        };
        for entry in entries.flatten() {
            let ft = match entry.file_type() {
                Ok(ft) => ft,
                Err(_) => continue,
            };
            let name = match entry.file_name().into_string() {
                Ok(n) => n,
                Err(_) => continue,
            };
            let child_rel = if rel.is_empty() {
                name.clone()
            } else {
                format!("{rel}/{name}")
            };
            if ft.is_file() {
                out.push(child_rel);
            } else if ft.is_dir() {
                walk(&base.join(&name), &child_rel, out);
            }
        }
    }
    walk(root, "", &mut paths);
    paths.sort();
    StrykeValue::array(paths.into_iter().map(StrykeValue::string).collect())
}

/// List only directory names inside `dir` (non-recursive), sorted.
/// Returns an empty list if `dir` cannot be read.
pub fn list_dirs(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    if let Ok(entries) = std::fs::read_dir(dir) {
        for entry in entries.flatten() {
            if entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
                if let Some(name) = entry.file_name().to_str() {
                    names.push(name.to_string());
                }
            }
        }
    }
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}

/// List subdirectory paths under `dir` **recursively**, sorted.
/// Returns relative paths from `dir` (e.g. `"sub/nested"`).
/// Returns an empty list if `dir` cannot be read.
pub fn list_dirs_recursive(dir: &str) -> StrykeValue {
    let root = std::path::Path::new(dir);
    let mut paths: Vec<String> = Vec::new();
    fn walk(base: &std::path::Path, rel: &str, out: &mut Vec<String>) {
        let Ok(entries) = std::fs::read_dir(base) else {
            return;
        };
        for entry in entries.flatten() {
            let ft = match entry.file_type() {
                Ok(ft) => ft,
                Err(_) => continue,
            };
            if !ft.is_dir() {
                continue;
            }
            let name = match entry.file_name().into_string() {
                Ok(n) => n,
                Err(_) => continue,
            };
            let child_rel = if rel.is_empty() {
                name.clone()
            } else {
                format!("{rel}/{name}")
            };
            out.push(child_rel.clone());
            walk(&base.join(&name), &child_rel, out);
        }
    }
    walk(root, "", &mut paths);
    paths.sort();
    StrykeValue::array(paths.into_iter().map(StrykeValue::string).collect())
}

/// List only symlink names inside `dir` (non-recursive), sorted.
/// Returns an empty list if `dir` cannot be read.
pub fn list_sym_links(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    if let Ok(entries) = std::fs::read_dir(dir) {
        for entry in entries.flatten() {
            if entry.file_type().map(|ft| ft.is_symlink()).unwrap_or(false) {
                if let Some(name) = entry.file_name().to_str() {
                    names.push(name.to_string());
                }
            }
        }
    }
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}

/// List only Unix socket names inside `dir` (non-recursive), sorted.
/// Returns an empty list if `dir` cannot be read or on non-Unix platforms.
pub fn list_sockets(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    #[cfg(unix)]
    {
        use std::os::unix::fs::FileTypeExt;
        if let Ok(entries) = std::fs::read_dir(dir) {
            for entry in entries.flatten() {
                if entry.file_type().map(|ft| ft.is_socket()).unwrap_or(false) {
                    if let Some(name) = entry.file_name().to_str() {
                        names.push(name.to_string());
                    }
                }
            }
        }
    }
    let _ = dir;
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}

/// List only named-pipe (FIFO) names inside `dir` (non-recursive), sorted.
/// Returns an empty list if `dir` cannot be read or on non-Unix platforms.
pub fn list_pipes(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    #[cfg(unix)]
    {
        use std::os::unix::fs::FileTypeExt;
        if let Ok(entries) = std::fs::read_dir(dir) {
            for entry in entries.flatten() {
                if entry.file_type().map(|ft| ft.is_fifo()).unwrap_or(false) {
                    if let Some(name) = entry.file_name().to_str() {
                        names.push(name.to_string());
                    }
                }
            }
        }
    }
    let _ = dir;
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}

/// List only block device names inside `dir` (non-recursive), sorted.
/// Returns an empty list if `dir` cannot be read or on non-Unix platforms.
pub fn list_block_devices(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    #[cfg(unix)]
    {
        use std::os::unix::fs::FileTypeExt;
        if let Ok(entries) = std::fs::read_dir(dir) {
            for entry in entries.flatten() {
                if entry
                    .file_type()
                    .map(|ft| ft.is_block_device())
                    .unwrap_or(false)
                {
                    if let Some(name) = entry.file_name().to_str() {
                        names.push(name.to_string());
                    }
                }
            }
        }
    }
    let _ = dir;
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}

/// List only executable file names inside `dir` (non-recursive), sorted.
/// Returns an empty list if `dir` cannot be read.
pub fn list_executables(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    #[cfg(unix)]
    {
        if let Ok(entries) = std::fs::read_dir(dir) {
            for entry in entries.flatten() {
                if entry.file_type().map(|ft| ft.is_file()).unwrap_or(false)
                    && unix_path_executable(&entry.path())
                {
                    if let Some(name) = entry.file_name().to_str() {
                        names.push(name.to_string());
                    }
                }
            }
        }
    }
    #[cfg(not(unix))]
    {
        if let Ok(entries) = std::fs::read_dir(dir) {
            for entry in entries.flatten() {
                if entry.file_type().map(|ft| ft.is_file()).unwrap_or(false) {
                    let p = entry.path();
                    if let Some(ext) = p.extension() {
                        if ext == "exe" || ext == "bat" || ext == "cmd" {
                            if let Some(name) = entry.file_name().to_str() {
                                names.push(name.to_string());
                            }
                        }
                    }
                }
            }
        }
    }
    let _ = dir;
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}

/// List only character device names inside `dir` (non-recursive), sorted.
/// Returns an empty list if `dir` cannot be read or on non-Unix platforms.
pub fn list_char_devices(dir: &str) -> StrykeValue {
    let mut names: Vec<String> = Vec::new();
    #[cfg(unix)]
    {
        use std::os::unix::fs::FileTypeExt;
        if let Ok(entries) = std::fs::read_dir(dir) {
            for entry in entries.flatten() {
                if entry
                    .file_type()
                    .map(|ft| ft.is_char_device())
                    .unwrap_or(false)
                {
                    if let Some(name) = entry.file_name().to_str() {
                        names.push(name.to_string());
                    }
                }
            }
        }
    }
    let _ = dir;
    names.sort();
    StrykeValue::array(names.into_iter().map(StrykeValue::string).collect())
}
/// `glob_patterns` — see implementation.
pub fn glob_patterns(patterns: &[String]) -> StrykeValue {
    let mut paths: Vec<String> = Vec::new();
    for pat in patterns {
        if !pattern_is_glob(pat) {
            paths.push(normalize_glob_path_display(pat.clone()));
            continue;
        }
        for s in stryke_glob(pat) {
            paths.push(normalize_glob_path_display(s));
        }
    }
    paths.sort();
    paths.dedup();
    StrykeValue::array(paths.into_iter().map(StrykeValue::string).collect())
}

/// `swallow PATTERN` — expand `pattern` through the zsh glob engine (same one
/// `glob`/`slurp` use, full qualifier support), read every matched regular file
/// as raw bytes, and return a hash `{ canonicalized_abspath => bytes }`.
///
/// Symlinks are flattened (`fs::canonicalize`) so a symlink farm collapses to
/// the underlying real paths. Hard-fails on a non-regular-file match the same
/// way [`read_file_text_or_glob`] does — users opt into silence with the `(N)`
/// null-glob qualifier (`swallow "missing*(N)"` returns an empty hash).
///
/// Literal (non-glob) paths are treated as a one-element match so
/// `swallow("README.md")` is equivalent to a single-key hash.
pub fn swallow_to_hash(pattern: &str) -> io::Result<StrykeValue> {
    let paths: Vec<String> = if pattern_is_glob(pattern) {
        stryke_glob(pattern)
    } else {
        vec![pattern.to_string()]
    };
    let (_, qual) = zsh::glob::split_qualifier(pattern);
    let strict = qual.is_some();
    let mut out: indexmap::IndexMap<String, StrykeValue> = indexmap::IndexMap::new();
    for p in &paths {
        // Same policy as `slurp`: a plain wildcard sweep skips matches it can't
        // read as a regular file (dangling symlink, vanished file, directory) —
        // a bad reference is skipped, not a fatal hole; a qualifier glob is an
        // explicit selection and stays strict.
        let entry = slurp_glob_entry(p, strict, |p| {
            let canon = std::fs::canonicalize(p)?.to_string_lossy().into_owned();
            let bytes = read_file_bytes(p)?;
            Ok((canon, StrykeValue::bytes(bytes)))
        })?;
        if let Some((canon, val)) = entry {
            out.insert(canon, val);
        }
    }
    Ok(StrykeValue::hash(out))
}

/// Streaming sibling of [`swallow_to_hash`]: pre-resolves the glob match set
/// (same zsh engine, same plain-sweep-skips / qualifier-strict policy, same
/// canonicalize), then defers the bytes read until each `next_item()` call.
/// Only one file's
/// bytes are resident at any time — useful when iterating directories whose
/// concatenated contents would not fit in memory.
///
/// Per-yield value: `[canonical_abspath, raw_bytes]` as an array ref so users
/// can destructure with `for my ($p, $b) (ingest "**/*.log") { ... }`.
pub struct IngestIterator {
    /// `queue` field.
    queue: Mutex<std::collections::VecDeque<String>>,
}

impl IngestIterator {
    /// `new` — see implementation.
    pub fn new(paths: Vec<String>) -> Self {
        Self {
            queue: Mutex::new(paths.into_iter().collect()),
        }
    }
}

impl crate::value::StrykeIterator for IngestIterator {
    fn next_item(&self) -> Option<StrykeValue> {
        let path = self.queue.lock().pop_front()?;
        let bytes = match std::fs::read(&path) {
            Ok(b) => Arc::new(b),
            // Pre-flight stat/canonicalize already happened in `ingest_iterator`,
            // so a read failure here means the file was removed mid-iteration.
            // End the stream rather than panicking — matches Perl/Unix tradition.
            Err(_) => return None,
        };
        let pair = vec![StrykeValue::string(path), StrykeValue::bytes(bytes)];
        Some(StrykeValue::array_ref(Arc::new(RwLock::new(pair))))
    }
}

/// `ingest PATTERN` — same surface as [`swallow_to_hash`] but returns a lazy
/// iterator instead of materializing a hash. Path discovery + stat +
/// canonicalize are eager (so qualifier support is identical to swallow/slurp,
/// and a plain sweep skips matches it can't stat as a regular file while a
/// qualifier glob stays strict); file content reads are deferred to
/// per-iteration `next_item()` calls via [`IngestIterator`].
pub fn ingest_iterator(pattern: &str) -> io::Result<StrykeValue> {
    let raw_paths: Vec<String> = if pattern_is_glob(pattern) {
        stryke_glob(pattern)
    } else {
        vec![pattern.to_string()]
    };
    let (_, qual) = zsh::glob::split_qualifier(pattern);
    let strict = qual.is_some();
    let mut canon: Vec<String> = Vec::with_capacity(raw_paths.len());
    for p in &raw_paths {
        // Same policy as `slurp`/`swallow`: a plain wildcard sweep skips matches
        // it can't stat as a regular file (dangling symlink, vanished file,
        // directory); a qualifier glob is an explicit selection and stays strict.
        let resolved = slurp_glob_entry(p, strict, |p| {
            std::fs::canonicalize(p).map(|c| c.to_string_lossy().into_owned())
        })?;
        if let Some(c) = resolved {
            canon.push(c);
        }
    }
    Ok(StrykeValue::iterator(Arc::new(IngestIterator::new(canon))))
}

/// `burp HASH` — inverse of `swallow`. Walk a `{ path => content }` hash and
/// write each entry to disk. Parent directories are created on the fly so the
/// canonical `swallow %h |> mutate |> burp` round-trip works even when the
/// destination tree doesn't yet exist. Values that are byte buffers
/// (`StrykeValue::bytes`) write raw bytes; any other scalar stringifies via
/// `to_string()` before being written (matches `spew`/`spurt` semantics).
///
/// Returns the count of files written. Hard-fails on the first I/O error so a
/// half-applied burp surfaces immediately rather than silently dropping
/// entries.
pub fn burp_hash_to_disk(v: &StrykeValue) -> io::Result<i64> {
    let entries: Vec<(String, Vec<u8>)> = if let Some(h) = v.as_hash_map() {
        h.into_iter()
            .map(|(k, val)| (k, value_to_bytes(&val)))
            .collect()
    } else if let Some(href) = v.as_hash_ref() {
        href.read()
            .iter()
            .map(|(k, val)| (k.clone(), value_to_bytes(val)))
            .collect()
    } else {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!(
                "burp: expected a HASH or HASHREF, got {} \
                 — pass `\\%h` or an inline hashref `{{ ... }}`",
                v.type_name()
            ),
        ));
    };
    let mut written: i64 = 0;
    for (path, bytes) in &entries {
        spurt_path(
            path, bytes, /*mkdir_parents=*/ true, /*atomic=*/ false,
        )?;
        written += 1;
    }
    Ok(written)
}

/// Bytes-faithful conversion mirroring `builtins::perl_scalar_as_bytes`: a
/// `bytes` value writes its raw bytes; anything else stringifies through the
/// standard `to_string()` path (which itself byte-decodes a bytes value, so
/// strings written via `burp` round-trip the way Perl callers expect).
fn value_to_bytes(v: &StrykeValue) -> Vec<u8> {
    if let Some(b) = v.as_bytes_arc() {
        return b.as_ref().clone();
    }
    v.to_string().into_bytes()
}

/// Parallel recursive glob: same pattern semantics as [`glob_patterns`], but walks the
/// filesystem with rayon per directory (and parallelizes across patterns).
pub fn glob_par_patterns(patterns: &[String]) -> StrykeValue {
    glob_par_patterns_inner(patterns, None)
}

/// Same as [`glob_par_patterns`], with a stderr progress bar (one tick per pattern) when
/// `progress` is true.
pub fn glob_par_patterns_with_progress(patterns: &[String], progress: bool) -> StrykeValue {
    if patterns.is_empty() {
        return StrykeValue::array(Vec::new());
    }
    let pmap = PmapProgress::new(progress, patterns.len());
    let v = glob_par_patterns_inner(patterns, Some(&pmap));
    pmap.finish();
    v
}

fn glob_par_patterns_inner(patterns: &[String], progress: Option<&PmapProgress>) -> StrykeValue {
    // Parallelize across patterns. Each pattern goes through `zsh::glob::glob_path`
    // single-threaded so the full qualifier machinery is available; intra-
    // pattern parallelism is sacrificed in exchange for `(/)`, `(.)`, `(om)`,
    // `(L+N)`, etc. World-first: zsh glob qualifiers in a scripting language.
    let out: Vec<String> = patterns
        .par_iter()
        .flat_map_iter(|pat| {
            let rows: Vec<String> = if !pattern_is_glob(pat) {
                vec![pat.clone()]
            } else {
                stryke_glob(pat)
            };
            if let Some(p) = progress {
                p.tick();
            }
            rows
        })
        .collect();
    let mut paths: Vec<String> = out.into_iter().map(normalize_glob_path_display).collect();
    paths.sort();
    paths.dedup();
    StrykeValue::array(paths.into_iter().map(StrykeValue::string).collect())
}

/// Display form for glob results. Pass-through — zshrs is authoritative
/// on prefixing (it already emits `./` for cwd matches and bare names
/// for colon-modifier results like `(:t)` / `(:e)` / `(:r)`). Re-adding
/// `./` here used to corrupt colon-modifier output.
fn normalize_glob_path_display(s: String) -> String {
    s
}

/// `rename OLD, NEW` — 1 on success, 0 on failure (Perl-style).
pub fn rename_paths(old: &str, new: &str) -> StrykeValue {
    StrykeValue::integer(if std::fs::rename(old, new).is_ok() {
        1
    } else {
        0
    })
}

#[inline]
fn is_cross_device_rename(e: &io::Error) -> bool {
    if e.kind() == io::ErrorKind::CrossesDevices {
        return true;
    }
    #[cfg(unix)]
    {
        if e.raw_os_error() == Some(libc::EXDEV) {
            return true;
        }
    }
    false
}

fn try_move_path(from: &str, to: &str) -> io::Result<()> {
    match std::fs::rename(from, to) {
        Ok(()) => Ok(()),
        Err(e) => {
            if !is_cross_device_rename(&e) {
                return Err(e);
            }
            let meta = std::fs::symlink_metadata(from)?;
            if meta.is_dir() {
                return Err(io::Error::new(
                    io::ErrorKind::Unsupported,
                    "move: cross-device directory move is not supported",
                ));
            }
            if !meta.is_file() && !meta.is_symlink() {
                return Err(io::Error::new(
                    io::ErrorKind::Unsupported,
                    "move: cross-device move supports files and symlinks only",
                ));
            }
            std::fs::copy(from, to)?;
            std::fs::remove_file(from)?;
            Ok(())
        }
    }
}

/// `move OLD, NEW` / `mv` — like `rename`, but on cross-device failure copies the file then removes
/// the source (directories not supported for cross-device).
pub fn move_path(from: &str, to: &str) -> StrykeValue {
    StrykeValue::integer(if try_move_path(from, to).is_ok() {
        1
    } else {
        0
    })
}

#[cfg(unix)]
fn unix_path_executable(path: &Path) -> bool {
    use std::os::unix::fs::PermissionsExt;
    std::fs::metadata(path)
        .ok()
        .filter(|m| m.is_file())
        .is_some_and(|m| m.permissions().mode() & 0o111 != 0)
}

#[cfg(not(unix))]
fn unix_path_executable(path: &Path) -> bool {
    path.is_file()
}

fn display_executable_path(path: &Path) -> Option<String> {
    if !unix_path_executable(path) {
        return None;
    }
    path.canonicalize()
        .ok()
        .map(|p| p.to_string_lossy().into_owned())
        .or_else(|| Some(path.to_string_lossy().into_owned()))
}

#[cfg(windows)]
fn pathext_suffixes() -> Vec<String> {
    env::var_os("PATHEXT")
        .map(|s| {
            env::split_paths(&s)
                .filter_map(|p| p.to_str().map(str::to_ascii_lowercase))
                .collect()
        })
        .unwrap_or_else(|| vec![".exe".into(), ".cmd".into(), ".bat".into(), ".com".into()])
}

#[cfg(windows)]
fn which_in_dir(dir: &Path, program: &str) -> Option<String> {
    let plain = dir.join(program);
    if let Some(s) = display_executable_path(&plain) {
        return Some(s);
    }
    if !program.contains('.') {
        for ext in pathext_suffixes() {
            let cand = dir.join(format!("{program}{ext}"));
            if let Some(s) = display_executable_path(&cand) {
                return Some(s);
            }
        }
    }
    None
}

#[cfg(not(windows))]
fn which_in_dir(dir: &Path, program: &str) -> Option<String> {
    display_executable_path(&dir.join(program))
}

/// Resolve `program` using `PATH` (and optional current directory when `include_dot`).
/// Returns a path string or `None` if not found.
pub fn which_executable(program: &str, include_dot: bool) -> Option<String> {
    if program.is_empty() {
        return None;
    }
    if program.contains('/') || (cfg!(windows) && program.contains('\\')) {
        return display_executable_path(Path::new(program));
    }
    let path_os = env::var_os("PATH")?;
    for dir in env::split_paths(&path_os) {
        if let Some(s) = which_in_dir(&dir, program) {
            return Some(s);
        }
    }
    if include_dot {
        return which_in_dir(Path::new("."), program);
    }
    None
}

/// Read entire file as raw bytes (no text decoding).
pub fn read_file_bytes(path: &str) -> io::Result<Arc<Vec<u8>>> {
    Ok(Arc::new(std::fs::read(path)?))
}

/// Temp file adjacent to `target` for atomic replace (`rename` into place).
fn adjacent_temp_path(target: &Path) -> PathBuf {
    let dir = target.parent().unwrap_or_else(|| Path::new("."));
    let name = target
        .file_name()
        .map(|s| s.to_string_lossy().into_owned())
        .unwrap_or_else(|| "file".to_string());
    let rnd: u32 = rand::thread_rng().gen();
    dir.join(format!("{name}.spurt-tmp-{rnd}"))
}

/// Write bytes to `path`. When `mkdir_parents`, creates parent directories. When `atomic`, writes
/// to a unique temp file in the same directory then `rename`s into place (best-effort crash safety).
pub fn spurt_path(path: &str, data: &[u8], mkdir_parents: bool, atomic: bool) -> io::Result<()> {
    let path = Path::new(path);
    if mkdir_parents {
        if let Some(parent) = path.parent() {
            if !parent.as_os_str().is_empty() {
                std::fs::create_dir_all(parent)?;
            }
        }
    }
    if !atomic {
        return std::fs::write(path, data);
    }
    let tmp = adjacent_temp_path(path);
    {
        let mut f = std::fs::File::create(&tmp)?;
        f.write_all(data)?;
        f.sync_all().ok();
    }
    std::fs::rename(&tmp, path)?;
    Ok(())
}

/// `copy FROM, TO` — 1 on success, 0 on failure. When `preserve_metadata`, best-effort copy of
/// access/modification times from the source (after a successful byte copy).
pub fn copy_file(from: &str, to: &str, preserve_metadata: bool) -> StrykeValue {
    let times = if preserve_metadata {
        std::fs::metadata(from).ok().map(|src_meta| {
            let at = src_meta
                .accessed()
                .ok()
                .and_then(|t| t.duration_since(UNIX_EPOCH).ok())
                .map(|d| d.as_secs() as i64)
                .unwrap_or(0);
            let mt = src_meta
                .modified()
                .ok()
                .and_then(|t| t.duration_since(UNIX_EPOCH).ok())
                .map(|d| d.as_secs() as i64)
                .unwrap_or(0);
            (at, mt)
        })
    } else {
        None
    };
    if std::fs::copy(from, to).is_err() {
        return StrykeValue::integer(0);
    }
    if let Some((at, mt)) = times {
        let _ = utime_paths(at, mt, &[to.to_string()]);
    }
    StrykeValue::integer(1)
}

/// [`std::path::Path::file_name`] as a string (empty if none).
pub fn path_basename(path: &str) -> String {
    Path::new(path)
        .file_name()
        .map(|s| s.to_string_lossy().into_owned())
        .unwrap_or_default()
}

/// Parent directory string; `"."` when absent; `"/"` for POSIX root-ish paths.
pub fn path_dirname(path: &str) -> String {
    if path.is_empty() {
        return String::new();
    }
    let p = Path::new(path);
    if path == "/" {
        return "/".to_string();
    }
    match p.parent() {
        None => ".".to_string(),
        Some(parent) => {
            let s = parent.to_string_lossy();
            if s.is_empty() {
                ".".to_string()
            } else {
                s.into_owned()
            }
        }
    }
}

/// `(base, dir, suffix)` like Perl `File::Basename::fileparse` with a single optional suffix.
/// When `suffix` is `Some` and `full_base` ends with it, `base` has the suffix removed and `suffix`
/// is the matched suffix; otherwise `suffix` in the return is empty.
pub fn fileparse_path(path: &str, suffix: Option<&str>) -> (String, String, String) {
    let dir = path_dirname(path);
    let full_base = path_basename(path);
    let (base, sfx) = if let Some(suf) = suffix.filter(|s| !s.is_empty()) {
        if full_base.ends_with(suf) && full_base.len() > suf.len() {
            (
                full_base[..full_base.len() - suf.len()].to_string(),
                suf.to_string(),
            )
        } else {
            (full_base.clone(), String::new())
        }
    } else {
        (full_base.clone(), String::new())
    };
    (base, dir, sfx)
}

/// `chmod MODE, FILES...` — count of files successfully chmod'd.
pub fn chmod_paths(paths: &[String], mode: i64) -> i64 {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut count = 0i64;
        for path in paths {
            if let Ok(meta) = std::fs::metadata(path) {
                let mut perms = meta.permissions();
                let old = perms.mode();
                // Perl passes permission bits (e.g. 0644); preserve st_mode file-type bits.
                perms.set_mode((old & !0o777) | (mode as u32 & 0o777));
                if std::fs::set_permissions(path, perms).is_ok() {
                    count += 1;
                }
            }
        }
        count
    }
    #[cfg(not(unix))]
    {
        let _ = (paths, mode);
        0
    }
}

/// `utime ATIME, MTIME, FILES...` — count of paths successfully updated (Unix `utimes`; 0 on non-Unix).
pub fn utime_paths(atime_sec: i64, mtime_sec: i64, paths: &[String]) -> i64 {
    #[cfg(unix)]
    {
        use std::ffi::CString;
        let mut count = 0i64;
        let tv = [
            libc::timeval {
                tv_sec: atime_sec as libc::time_t,
                tv_usec: 0,
            },
            libc::timeval {
                tv_sec: mtime_sec as libc::time_t,
                tv_usec: 0,
            },
        ];
        for path in paths {
            let Ok(cs) = CString::new(path.as_str()) else {
                continue;
            };
            if unsafe { libc::utimes(cs.as_ptr(), tv.as_ptr()) } == 0 {
                count += 1;
            }
        }
        count
    }
    #[cfg(not(unix))]
    {
        let _ = (atime_sec, mtime_sec, paths);
        0
    }
}

/// `chown UID, GID, FILES...` — count of files successfully chown'd (Unix only; 0 on non-Unix).
pub fn chown_paths(paths: &[String], uid: i64, gid: i64) -> i64 {
    #[cfg(unix)]
    {
        use std::ffi::CString;
        let u = if uid < 0 {
            (!0u32) as libc::uid_t
        } else {
            uid as libc::uid_t
        };
        let g = if gid < 0 {
            (!0u32) as libc::gid_t
        } else {
            gid as libc::gid_t
        };
        let mut count = 0i64;
        for path in paths {
            let Ok(c) = CString::new(path.as_str()) else {
                continue;
            };
            let r = unsafe { libc::chown(c.as_ptr(), u, g) };
            if r == 0 {
                count += 1;
            }
        }
        count
    }
    #[cfg(not(unix))]
    {
        let _ = (paths, uid, gid);
        0
    }
}

/// `touch FILES...` — create files if they don't exist, update atime/mtime to
/// now if they do.  Returns count of files successfully touched.
pub fn touch_paths(paths: &[String]) -> i64 {
    use std::fs::OpenOptions;
    let mut count = 0i64;
    for path in paths {
        if path.is_empty() {
            continue;
        }
        // Create the file if it doesn't exist (like coreutils touch).
        let created = OpenOptions::new()
            .create(true)
            .append(true)
            .open(path)
            .is_ok();
        if !created {
            continue;
        }
        // Update atime + mtime to now.
        #[cfg(unix)]
        {
            use std::ffi::CString;
            if let Ok(cs) = CString::new(path.as_str()) {
                // null timeval pointer ⇒ set both times to now
                unsafe { libc::utimes(cs.as_ptr(), std::ptr::null()) };
            }
        }
        count += 1;
    }
    count
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashSet;

    #[test]
    fn glob_par_matches_sequential_glob_set() {
        let base = std::env::temp_dir().join(format!("stryke_glob_par_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&base);
        std::fs::create_dir_all(base.join("a")).unwrap();
        std::fs::create_dir_all(base.join("b")).unwrap();
        std::fs::create_dir_all(base.join("b/nested")).unwrap();
        std::fs::File::create(base.join("a/x.log")).unwrap();
        std::fs::File::create(base.join("b/y.log")).unwrap();
        std::fs::File::create(base.join("b/nested/z.log")).unwrap();
        std::fs::File::create(base.join("root.txt")).unwrap();

        // Absolute patterns only — never `set_current_dir`; other tests run in parallel.
        let pat = format!("{}/**/*.log", base.display());
        let a = glob_patterns(std::slice::from_ref(&pat));
        let b = glob_par_patterns(std::slice::from_ref(&pat));
        let _ = std::fs::remove_dir_all(&base);

        let set_a: HashSet<String> = a
            .as_array_vec()
            .expect("expected array")
            .into_iter()
            .map(|x| x.to_string())
            .collect();
        let set_b: HashSet<String> = b
            .as_array_vec()
            .expect("expected array")
            .into_iter()
            .map(|x| x.to_string())
            .collect();
        assert_eq!(set_a, set_b);
    }

    #[test]
    fn glob_par_src_rs_matches_when_src_tree_present() {
        let root = Path::new(env!("CARGO_MANIFEST_DIR"));
        let src = root.join("src");
        if !src.is_dir() {
            return;
        }
        let pat = src.join("*.rs").to_string_lossy().into_owned();
        let v = glob_par_patterns(&[pat])
            .as_array_vec()
            .expect("expected array");
        assert!(
            !v.is_empty(),
            "glob_par src/*.rs should find at least one .rs under src/"
        );
    }

    #[test]
    fn glob_par_progress_false_same_as_plain() {
        let tmp = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("target")
            .join(format!("glob_par_prog_false_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&tmp);
        std::fs::create_dir_all(&tmp).unwrap();
        std::fs::write(tmp.join("probe.rs"), b"// x\n").unwrap();
        let pat = tmp.join("*.rs").to_string_lossy().replace('\\', "/");
        let a = glob_par_patterns(std::slice::from_ref(&pat));
        let b = glob_par_patterns_with_progress(std::slice::from_ref(&pat), false);
        let _ = std::fs::remove_dir_all(&tmp);
        let va = a.as_array_vec().expect("a");
        let vb = b.as_array_vec().expect("b");
        assert_eq!(va.len(), vb.len(), "glob_par vs glob_par(..., progress=>0)");
        for (x, y) in va.iter().zip(vb.iter()) {
            assert_eq!(x.to_string(), y.to_string());
        }
    }

    #[test]
    fn read_file_text_perl_compat_maps_invalid_utf8_to_latin1_octets() {
        let path = std::env::temp_dir().join(format!("stryke_bad_utf8_{}.txt", std::process::id()));
        // Lone continuation bytes — invalid UTF-8 as a whole; per-line Latin-1.
        std::fs::write(&path, b"ok\xff\xfe\x80\n").unwrap();
        let s = read_file_text_perl_compat(&path).expect("read");
        assert!(s.starts_with("ok"));
        assert_eq!(&s[2..], "\u{00ff}\u{00fe}\u{0080}\n");
        let _ = std::fs::remove_file(&path);
    }

    #[cfg(unix)]
    #[test]
    fn slurp_glob_skips_dangling_symlink_in_plain_sweep() {
        // A plain wildcard sweep that incidentally matches a broken symlink
        // must skip it and keep reading the real files — one dead entry can't
        // abort the whole `c("**.rs")`-style sweep. Regression for the
        // `slurp: No such file or directory (os error 2)` that std::fs::metadata
        // raised when it followed a dangling link.
        use std::os::unix::fs::symlink;
        let dir = std::env::temp_dir().join(format!("stryke_slurp_dangling_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(dir.join("real.txt"), b"hello").unwrap();
        symlink(dir.join("does_not_exist"), dir.join("dead.txt")).unwrap();
        let pat = format!("{}/*.txt", dir.display());
        let out = read_file_text_or_glob(&pat).expect("plain sweep must not fail on a dangling link");
        assert_eq!(out, "hello");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[cfg(unix)]
    #[test]
    fn swallow_and_ingest_skip_dangling_symlink_in_plain_sweep() {
        // swallow/ingest share slurp's policy: a plain wildcard sweep skips a
        // bad reference (dangling symlink) rather than aborting the per-file
        // result with `not a regular file` / `os error 2`.
        use std::os::unix::fs::symlink;
        let dir = std::env::temp_dir().join(format!("stryke_swallow_dangling_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        std::fs::write(dir.join("real.txt"), b"hello").unwrap();
        symlink(dir.join("does_not_exist"), dir.join("dead.txt")).unwrap();
        let pat = format!("{}/*.txt", dir.display());

        let hash = swallow_to_hash(&pat).expect("swallow must skip the dangling link");
        let keys: Vec<String> = hash.as_hash_map().unwrap().keys().cloned().collect();
        assert_eq!(keys.len(), 1, "only the real file survives: {:?}", keys);
        assert!(keys[0].ends_with("real.txt"));

        // ingest pre-resolves the same match set without aborting.
        ingest_iterator(&pat).expect("ingest must skip the dangling link");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn read_logical_line_perl_compat_splits_and_decodes_per_line() {
        use std::io::Cursor;
        let mut r = Cursor::new(b"a\xff\nb\n");
        assert_eq!(
            read_logical_line_perl_compat(&mut r).unwrap(),
            Some("a\u{00ff}".to_string())
        );
        assert_eq!(
            read_logical_line_perl_compat(&mut r).unwrap(),
            Some("b".to_string())
        );
        assert_eq!(read_logical_line_perl_compat(&mut r).unwrap(), None);
    }

    /// Regression for the `-0` (NUL-separator) bug: stryke v0.16.4 ignored the
    /// configured input record separator and hardcoded `\n`, so a NUL-free file
    /// got split per line instead of read as one record. perl `-0` on the same
    /// input reads the whole 5-byte buffer in one shot. Reported via the
    /// powerliners `togg` shell function whose add-path regex needs to match
    /// across newlines.
    ///
    /// Returns the record with the trailing input (no NUL exists in the file →
    /// trailing `\n` from EOF is preserved) — perl `<>` leaves the IRS / trailing
    /// bytes in `$_`; chomp / `-l` strip them in the autoprint pipeline.
    #[test]
    fn read_logical_line_with_sep_nul_reads_whole_no_nul_file_as_one_record() {
        use std::io::Cursor;
        let mut r = Cursor::new(b"{\n\n}\n");
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(0u8)).unwrap(),
            Some("{\n\n}\n".to_string()),
        );
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(0u8)).unwrap(),
            None,
        );
    }

    /// `-0NN` octal separator (e.g. `-040` = space) splits on that byte. Returns each record
    /// with the trailing separator included (perl `$_` semantics).
    #[test]
    fn read_logical_line_with_sep_splits_on_arbitrary_byte() {
        use std::io::Cursor;
        let mut r = Cursor::new(b"a b c");
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(b' ')).unwrap(),
            Some("a ".to_string()),
        );
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(b' ')).unwrap(),
            Some("b ".to_string()),
        );
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(b' ')).unwrap(),
            Some("c".to_string()),
        );
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(b' ')).unwrap(),
            None,
        );
    }

    /// `-0777` slurp mode reads everything as one record.
    #[test]
    fn read_logical_line_with_sep_none_slurps_to_eof() {
        use std::io::Cursor;
        let mut r = Cursor::new(b"line1\nline2\nline3");
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, None).unwrap(),
            Some("line1\nline2\nline3".to_string()),
        );
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, None).unwrap(),
            None,
        );
    }

    /// Default line mode (`Some(b'\n')`) returns each line *with* trailing `\n`. Distinct from
    /// `read_logical_line_perl_compat` which strips per its legacy contract.
    #[test]
    fn read_logical_line_with_sep_line_mode_preserves_trailing_newline() {
        use std::io::Cursor;
        let mut r = Cursor::new(b"foo\nbar\n");
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(b'\n')).unwrap(),
            Some("foo\n".to_string()),
        );
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(b'\n')).unwrap(),
            Some("bar\n".to_string()),
        );
        assert_eq!(
            read_logical_line_perl_compat_with_sep(&mut r, Some(b'\n')).unwrap(),
            None,
        );
    }
}