bashkit 0.20.1

//! Built-in shell commands
//!
//! This module provides the [`Builtin`] trait for implementing custom commands
//! and the [`Context`] struct for execution context.
//!
//! # Custom Builtins
//!
//! Implement the [`Builtin`] trait to create custom commands:
//!
//! ```rust
//! use bashkit::{Builtin, BuiltinContext, ExecResult, async_trait};
//!
//! struct MyCommand;
//!
//! #[async_trait]
//! impl Builtin for MyCommand {
//!     async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
//!         Ok(ExecResult::ok("Hello!\n".to_string()))
//!     }
//! }
//! ```
//!
//! Register via [`BashBuilder::builtin`](crate::BashBuilder::builtin).

mod alias;
mod archive;
pub(crate) mod arg_parser;
mod assert;
mod atomic_write;
mod awk;
mod base64;
mod basenc;
mod bc;
mod caller;
mod cat;
mod checksum;
mod clap_cache;
mod clap_env;
mod clear;
mod cmp;
mod column;
mod comm;
mod compgen;
mod coreutils_extra;
mod csv;
mod curl;
mod cuttr;
mod date;
mod dd;
mod diff;
mod dirstack;
mod disk;
mod dotenv;
mod echo;
mod environ;
mod envsubst;
mod expand;
mod export;
mod expr;
mod factor;
mod fc;
mod fileops;
mod find;
mod flow;
mod fmt;
mod fold;
mod generated;
mod glob_cmd;
mod grep;
mod grep_pattern;
mod headtail;
mod help;
mod hextools;
mod http;
mod iconv;
mod inspect;
mod install;
mod introspect;
mod jobctl;
mod join;
#[cfg(feature = "jq")]
mod jq;
mod json;
mod log;
mod ls;
mod make;
mod man;
mod mapfile;
mod mkfifo;
#[cfg(feature = "terminal")]
mod nano;
mod navigation;
mod nl;
mod numfmt;
#[cfg(feature = "terminal")]
mod pager;
mod parallel;
mod paste;
mod patch;
mod path;
mod pipeline;
mod pr;
mod printf;
pub(crate) mod random;
mod read;
mod retry;
mod rg;
pub(crate) mod search_common;
mod sed;
mod semver;
mod seq;
mod shellenv;
mod shuf;
mod sleep;
mod sortuniq;
mod source;
mod split;
mod strings;
mod sysextra;
mod system;
mod template;
mod test;
mod textrev;
pub(crate) mod timeout;
mod tomlq;
mod trap;
mod tree;
mod truncate;
mod tsort;
mod vars;
mod verify;
#[cfg(feature = "terminal")]
mod vi;
mod wait;
mod wc;
mod yes;
#[cfg(feature = "jq")]
mod yq;
mod zip_cmd;

mod helpers;
pub(crate) use crate::execution_capability::ExecutionExtensions;
pub(crate) use helpers::{BuiltinHelper, invalid_option};

pub(crate) mod limits;
pub(crate) use limits::MAX_FORMAT_WIDTH;

pub(crate) mod git;

pub(crate) mod ssh;

#[cfg(any(feature = "python", feature = "typescript", feature = "cpython"))]
mod runtime_limits;

#[cfg(feature = "cpython")]
mod cpython;
#[cfg(feature = "python")]
mod python;

#[cfg(feature = "typescript")]
mod typescript;

#[cfg(feature = "sqlite")]
mod sqlite;

pub use alias::{Alias, Unalias};
pub use archive::{Bunzip2, Bzcat, Bzip2, Gunzip, Gzip, Tar};
pub use assert::Assert;
pub use awk::Awk;
pub use base64::Base64;
pub use basenc::{Base32, Basenc};
pub use bc::Bc;
pub use caller::Caller;
pub use cat::Cat;
pub use checksum::{B2sum, Cksum, Md5sum, Sha1sum, Sha224sum, Sha256sum, Sha384sum, Sha512sum};
pub use clear::Clear;
pub use cmp::Cmp;
pub use column::Column;
pub use comm::Comm;
pub use compgen::{Compgen, ShellOnly};
pub use csv::Csv;
pub use curl::{Curl, Wget};
pub use cuttr::{Cut, Tr};
pub use date::Date;
pub use dd::Dd;
pub use diff::Diff;
pub use dirstack::{Dirs, Popd, Pushd};
pub use disk::{Df, Du};
pub use dotenv::Dotenv;
pub use echo::Echo;
pub use environ::{Env, History, Printenv};
pub use envsubst::Envsubst;
pub use expand::{Expand, Unexpand};
pub use export::Export;
pub use expr::Expr;
pub use factor::Factor;
pub use fc::Fc;
pub use fileops::{Chmod, Chown, Cp, Ln, Mkdir, Mktemp, Mv, Rm, Touch};
pub use find::Find;
pub use flow::{Break, Colon, Continue, Exit, False, Return, True};
pub use fmt::Fmt;
pub use fold::Fold;
pub use glob_cmd::GlobCmd;
pub use grep::Grep;
pub use headtail::{Head, Tail};
pub use help::Help;
pub use hextools::{Hexdump, Od, Xxd};
pub use http::Http;
pub use iconv::Iconv;
pub use inspect::{File, Less, Stat};
pub use install::Install;
pub(crate) use introspect::CommandHash;
pub use introspect::{Hash, Type, Which};
pub(crate) use jobctl::signal_name;
pub use join::Join;
#[cfg(feature = "jq")]
pub use jq::Jq;
pub use json::Json;
pub use log::Log;
pub use ls::{Ls, Rmdir};
pub(crate) use ls::{fnmatch, glob_match};
pub use make::Make;
pub use man::Man;
pub use mapfile::Mapfile;
pub use mkfifo::Mkfifo;
pub use navigation::{Cd, Pwd};
pub use nl::Nl;
pub use numfmt::Numfmt;
pub use parallel::Parallel;
pub use paste::Paste;
pub use patch::Patch;
pub use path::{Basename, Dirname, Readlink, Realpath};
pub use pipeline::{Tee, Watch, Xargs};
pub use pr::Pr;
pub use printf::Printf;
pub use random::{Openssl, Uuidgen};
pub use read::Read;
pub(crate) use read::consumed_len as read_consumed_len;
pub use retry::Retry;
pub use rg::Rg;
pub use sed::Sed;
pub use semver::Semver;
pub use seq::Seq;
pub use shellenv::{Enable, Locale, Ulimit, Umask};
pub use shuf::Shuf;
pub use tsort::Tsort;

pub use coreutils_extra::{Chgrp, GrepAlias, Link, Shasum, Sum};
pub use jobctl::{Bg, Disown, Fg, Jobs, Kill, Pgrep, Ps};
#[cfg(feature = "terminal")]
pub use nano::Nano;
#[cfg(feature = "terminal")]
pub use pager::More;
pub use sleep::Sleep;
pub use sortuniq::{Sort, Uniq};
pub use source::Source;
pub use split::Split;
pub use strings::Strings;
pub use sysextra::{Arch, Free, Getconf, Hostid, RunAs, SyncCmd, Tty, Uptime, UserInfo};
pub use system::{DEFAULT_HOSTNAME, DEFAULT_USERNAME, Hostname, Id, Nproc, Uname, Whoami};
pub(crate) use system::{VIRTUAL_KERNEL_RELEASE, VIRTUAL_KERNEL_VERSION, VIRTUAL_NPROC};
pub use template::Template;
pub use test::{Bracket, Test};
pub use textrev::{Rev, Tac};
pub use timeout::Timeout;
pub use tomlq::Tomlq;
pub use trap::Trap;
pub use tree::Tree;
pub use truncate::Truncate;
pub use vars::{Eval, Local, Readonly, Set, Shift, Shopt, Times, Unset};
pub(crate) use vars::{
    SET_O_OPTIONS, SHOPT_OPTIONS, bashopts_value, dollar_dash, set_o_var_by_letter,
    set_o_var_by_name, shellopts_value, shopt_known, shopt_on,
};
pub use verify::Verify;
#[cfg(feature = "terminal")]
pub use vi::Vi;
#[cfg(all(feature = "terminal", feature = "git"))]
pub(crate) use vi::edit_file;
pub use wait::Wait;
pub use wc::Wc;
pub use yes::Yes;
#[cfg(feature = "jq")]
pub use yq::Yq;
pub use zip_cmd::{Unzip, Zip};

#[cfg(feature = "git")]
pub use git::Git;

#[cfg(feature = "ssh")]
pub use ssh::{Scp, Sftp, Ssh};

#[cfg(any(feature = "python", feature = "typescript", feature = "cpython"))]
pub use runtime_limits::RuntimeLimits;

#[cfg(feature = "cpython")]
pub(crate) use cpython::check_http_request_invariants;
#[cfg(feature = "cpython")]
pub use cpython::{CPython, CPythonLimits};
#[cfg(feature = "python")]
pub(crate) use python::PythonInprocessOptIn;
#[cfg(feature = "python")]
pub use python::{Python, PythonExternalFnHandler, PythonExternalFns, PythonLimits};

#[cfg(feature = "typescript")]
pub use typescript::{
    TypeScriptConfig, TypeScriptExtension, TypeScriptExternalFnHandler, TypeScriptExternalFns,
    TypeScriptLimits,
};

#[cfg(feature = "sqlite")]
pub(crate) use sqlite::SqliteInprocessOptIn;
#[cfg(feature = "sqlite")]
pub use sqlite::{Sqlite, SqliteBackend, SqliteLimits};

use async_trait::async_trait;
use clap::{CommandFactory, FromArgMatches};
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::Arc;

use crate::error::Result;
use crate::fs::FileSystem;
use crate::interpreter::ExecResult;

pub(crate) async fn read_text_file(
    fs: &dyn FileSystem,
    path: &Path,
    cmd_name: &str,
) -> std::result::Result<String, ExecResult> {
    let content = read_stream_file(fs, path, cmd_name).await?;

    Ok(content.to_string())
}

pub(crate) async fn read_stream_file(
    fs: &dyn FileSystem,
    path: &Path,
    cmd_name: &str,
) -> std::result::Result<crate::StreamData, ExecResult> {
    fs.read_file(path)
        .await
        .map(crate::StreamData::from)
        .map_err(|e| {
            // Never the `Display` of a `crate::Error`: `io error: ` is a Rust
            // enum shape no tool prints. See `error::io_error_reason`.
            ExecResult::err(
                format!(
                    "{cmd_name}: {}: {}\n",
                    path.display(),
                    crate::error::io_error_reason(&e)
                ),
                1,
            )
        })
}

/// Check args for `--help` and optionally `--version`.
///
/// Returns `Some(ExecResult)` when the flag is found, `None` otherwise.
/// Call at the top of `execute()` to add standard help/version support.
///
/// Only matches long flags (`--help`, `--version`) because short flags
/// `-h` and `-V` have different meanings in many tools (e.g. `sort -V`
/// for version sort, `ls -h` for human-readable, `grep -h` to suppress
/// filenames).  Tools that want `-h`/`-V` as aliases should handle them
/// in their own `execute()` method.
pub(crate) fn check_help_version(
    args: &[String],
    help_text: &str,
    version: Option<&str>,
) -> Option<ExecResult> {
    for arg in args {
        match arg.as_str() {
            "--" => break,
            "--help" => return Some(ExecResult::ok(help_text.to_string())),
            "--version" => {
                if let Some(ver) = version {
                    return Some(ExecResult::ok(format!("{ver}\n")));
                }
            }
            // Stop checking after first non-flag argument
            s if !s.starts_with('-') => break,
            _ => {}
        }
    }
    None
}

// Re-export ShellRef for internal builtins
pub(crate) use crate::interpreter::ShellRef;

// Re-export for use by builtins
pub use crate::interpreter::BuiltinSideEffect;

/// A bundle of shell capabilities registered together.
///
/// Extensions are intended for embedders that want to contribute a family of
/// builtins as one unit. Builders expand extensions into normal builtin
/// registrations so command dispatch remains unchanged.
pub trait Extension: Send + Sync {
    /// Return builtin commands contributed by this extension.
    ///
    /// Later registrations with the same name replace earlier registrations,
    /// matching [`BashBuilder::builtin`](crate::BashBuilder::builtin).
    fn builtins(&self) -> Vec<(String, Box<dyn Builtin>)>;
}

/// Host-owned, mutable registry of builtin commands.
///
/// Unlike [`BashBuilder::builtin`](crate::BashBuilder::builtin), entries can be
/// inserted and removed at any point during the lifetime of the `Bash`
/// instance — the interpreter consults the registry at command-dispatch time.
///
/// Cloning the registry produces a new handle that shares the same underlying
/// storage; mutations made via any handle are visible to all others. This
/// lets embedders (FFI bindings, REPLs, plugin systems) hand a handle to the
/// builder and retain another for runtime registration.
///
/// In the command-resolution order, host-registered builtins are checked
/// after shell functions and POSIX special builtins, but before baked-in
/// builtins — so embedders can override baked-in commands.
#[derive(Clone, Default)]
pub struct BuiltinRegistry {
    inner: Arc<std::sync::RwLock<HashMap<String, RegisteredBuiltin>>>,
}

#[derive(Clone, Copy, PartialEq, Eq)]
pub(crate) enum BuiltinAccess {
    Scoped,
    TrustedHost,
}

#[derive(Clone)]
pub(crate) struct RegisteredBuiltin {
    pub(crate) builtin: Arc<dyn Builtin>,
    pub(crate) access: BuiltinAccess,
}

impl BuiltinRegistry {
    /// Register or replace a streaming command in the live registry.
    pub fn insert_command(&self, name: impl Into<String>, command: impl crate::Command + 'static) {
        let name = name.into();
        self.insert(
            name.clone(),
            Arc::new(crate::command::CommandAdapter {
                name,
                command: Arc::new(command),
            }),
        );
    }

    /// Create an empty registry.
    pub fn new() -> Self {
        Self::default()
    }

    /// Register or replace a builtin under `name`.
    pub fn insert(&self, name: impl Into<String>, builtin: Arc<dyn Builtin>) {
        if let Ok(mut guard) = self.inner.write() {
            guard.insert(
                name.into(),
                RegisteredBuiltin {
                    builtin,
                    access: BuiltinAccess::Scoped,
                },
            );
        }
    }

    /// Register a builtin with intentionally unscoped host-facility access.
    ///
    /// This is for trusted host integrations whose retained VFS handle is
    /// deliberately session-scoped. Prefer [`insert`](Self::insert), whose
    /// handles are revoked at the end of every execution.
    pub fn insert_trusted(&self, name: impl Into<String>, builtin: Arc<dyn Builtin>) {
        if let Ok(mut guard) = self.inner.write() {
            guard.insert(
                name.into(),
                RegisteredBuiltin {
                    builtin,
                    access: BuiltinAccess::TrustedHost,
                },
            );
        }
    }

    /// Remove the entry for `name`, returning the previously registered
    /// builtin if any.
    pub fn remove(&self, name: &str) -> Option<Arc<dyn Builtin>> {
        self.inner
            .write()
            .ok()
            .and_then(|mut g| g.remove(name))
            .map(|entry| entry.builtin)
    }

    /// Look up the builtin registered under `name`, returning a cloned handle.
    pub fn lookup(&self, name: &str) -> Option<Arc<dyn Builtin>> {
        self.lookup_entry(name).map(|entry| entry.builtin)
    }

    pub(crate) fn lookup_entry(&self, name: &str) -> Option<RegisteredBuiltin> {
        self.inner.read().ok().and_then(|g| g.get(name).cloned())
    }

    /// Return the set of currently registered builtin names.
    pub fn names(&self) -> Vec<String> {
        self.inner
            .read()
            .map(|g| g.keys().cloned().collect())
            .unwrap_or_default()
    }

    /// True if no builtins are registered.
    pub fn is_empty(&self) -> bool {
        self.inner.read().map(|g| g.is_empty()).unwrap_or(true)
    }
}

/// Resolve a command name to a builtin at dispatch time.
///
/// [`BuiltinRegistry`] answers "which names are registered" from a map fixed
/// before the name is known. A resolver is asked *about a specific name*, after
/// every other dispatch route has missed and immediately before the 127
/// "command not found" path — so an embedder can decide at runtime, per name,
/// without enumerating the set in advance.
///
/// Decision: resolvers return a [`Builtin`] rather than executing directly.
/// The resolved builtin runs through the same dispatch path as every other
/// builtin, so `before_tool` hooks fire with the resolved name and can veto it,
/// `catch_unwind` contains panics from both resolution and execution, and
/// redirects and stdin behave identically. A bespoke execution path would have
/// to re-earn all of that.
///
/// Returning `None` falls through to the normal `command not found` error.
///
/// # Security
///
/// A resolver is embedder-supplied host code, exactly like a builtin passed to
/// [`BashBuilder::builtin`](crate::BashBuilder::builtin) — it grants no
/// capability the embedder did not already have. What it *does* change is that
/// the set of names reaching host code stops being enumerable in advance, so
/// `Bash::builtin_names()` no longer bounds it. `before_tool` remains the
/// enforcement backstop; see `knowledge/integrations/script-analysis.md`.
/// Resolver panics become a sanitized, non-zero shell result rather than
/// unwinding through the interpreter.
///
/// # Example
///
/// ```
/// use bashkit::{Builtin, BuiltinContext, CommandResolver, ExecResult, async_trait};
/// use std::sync::Arc;
///
/// struct Echoer(String);
///
/// #[async_trait]
/// impl Builtin for Echoer {
///     async fn execute(&self, _ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
///         Ok(ExecResult::ok(format!("ran {}\n", self.0)))
///     }
/// }
///
/// struct AnyToolResolver;
///
/// impl CommandResolver for AnyToolResolver {
///     fn resolve(&self, name: &str) -> Option<Arc<dyn Builtin>> {
///         name.starts_with("tool-").then(|| Arc::new(Echoer(name.into())) as Arc<dyn Builtin>)
///     }
/// }
/// ```
pub trait CommandResolver: Send + Sync {
    /// Return a builtin to run for `name`, or `None` to fall through to
    /// `command not found`.
    ///
    /// Called on every unresolved command, so keep it cheap — cache rather
    /// than probing the filesystem on each call.
    fn resolve(&self, name: &str) -> Option<Arc<dyn Builtin>>;
}
/// Per-exec wall-clock deadline for builtins with synchronous VM sections.
#[derive(Debug, Clone)]
pub(crate) struct ExecutionDeadline {
    #[allow(dead_code)]
    started_at: crate::time_compat::Instant,
    timeout: std::time::Duration,
}

impl ExecutionDeadline {
    /// Create a deadline anchored at the start of `Bash::exec*`.
    pub(crate) fn new(timeout: std::time::Duration) -> Self {
        Self {
            started_at: crate::time_compat::Instant::now(),
            timeout,
        }
    }

    /// Remaining budget; never returns zero so downstream VM timers stay active.
    #[allow(dead_code)]
    pub(crate) fn remaining(&self) -> std::time::Duration {
        let remaining = self.timeout.saturating_sub(self.started_at.elapsed());
        if remaining.is_zero() {
            std::time::Duration::from_millis(1)
        } else {
            remaining
        }
    }

    /// Whether the wall-clock budget is exhausted. Builtins with synchronous
    /// loops the async timeout cannot preempt poll this to abort.
    #[allow(dead_code)]
    pub(crate) fn is_expired(&self) -> bool {
        self.started_at.elapsed() >= self.timeout
    }
}

/// A sub-command that a builtin wants the interpreter to execute.
///
/// Builtins like `timeout`, `xargs`, and `find -exec` need to execute
/// other commands. They return an [`ExecutionPlan`] describing what to
/// run, and the interpreter handles actual execution.
#[derive(Debug, Clone)]
pub struct SubCommand {
    /// Command name (e.g. "echo", "rm").
    pub name: String,
    /// Command arguments.
    pub args: Vec<String>,
    /// Optional stdin to pipe into the command.
    pub stdin: Option<crate::StreamData>,
    /// Command-scoped environment assignments (`VAR=value cmd ...`), applied
    /// only to this command's environment. Used by `xargs --process-slot-var`
    /// to expose a per-invocation parallel-slot index.
    pub assignments: Vec<(String, String)>,
}

/// Builtins of GNU bash 5.2 (`enable -a`). Every other registered command
/// stands in for a program, so `type`/`which`/`command -v` report it at its
/// `/usr/bin` path when the root filesystem provides one.
pub(crate) const BASH_BUILTIN_NAMES: &[&str] = &[
    ".",
    ":",
    "[",
    "alias",
    "bg",
    "bind",
    "break",
    "builtin",
    "caller",
    "cd",
    "command",
    "compgen",
    "complete",
    "compopt",
    "continue",
    "declare",
    "dirs",
    "disown",
    "echo",
    "enable",
    "eval",
    "exec",
    "exit",
    "export",
    "false",
    "fc",
    "fg",
    "getopts",
    "hash",
    "help",
    "history",
    "jobs",
    "kill",
    "let",
    "local",
    "logout",
    "mapfile",
    "popd",
    "printf",
    "pushd",
    "pwd",
    "read",
    "readarray",
    "readonly",
    "return",
    "set",
    "shift",
    "shopt",
    "source",
    "suspend",
    "test",
    "times",
    "trap",
    "true",
    "type",
    "typeset",
    "ulimit",
    "umask",
    "unalias",
    "unset",
    "wait",
];

/// Search `PATH` (shell variable, then environment) on the VFS for an
/// executable regular file named `name`.
pub(crate) async fn search_path(ctx: &Context<'_>, name: &str) -> Option<String> {
    search_path_all(ctx, name, true).await.into_iter().next()
}

/// Every executable `name` along `PATH`, in order (`type -a`); stops at the
/// first when `first_only`. A relative `PATH` entry (`_tmp`, or an empty one,
/// which means `.`) is looked up from the current directory but reported as
/// written (`_tmp/pwd`), as bash does.
pub(crate) async fn search_path_all(
    ctx: &Context<'_>,
    name: &str,
    first_only: bool,
) -> Vec<String> {
    search_path_with(ctx, name, first_only, false).await
}

/// bash's `find_user_command`: the first executable `name` along `PATH`, or
/// failing that the first regular file of that name (`type -t` says `file`,
/// running it fails with "Permission denied").
pub(crate) async fn search_path_or_file(ctx: &Context<'_>, name: &str) -> Option<String> {
    search_path_with(ctx, name, true, true)
        .await
        .into_iter()
        .next()
}

async fn search_path_with(
    ctx: &Context<'_>,
    name: &str,
    first_only: bool,
    file_fallback: bool,
) -> Vec<String> {
    let mut found = Vec::new();
    let mut fallback = None;
    if name.is_empty() || name.contains('/') {
        return found;
    }
    let path_var = ctx
        .variables
        .get("PATH")
        .or_else(|| ctx.env.get("PATH"))
        .cloned()
        .unwrap_or_default();
    for dir in path_var.split(':') {
        let candidate = path_candidate(dir, name);
        let resolved = resolve_path(ctx.cwd, &candidate);
        let Ok(meta) = ctx.fs.stat(&resolved).await else {
            continue;
        };
        if !meta.file_type.is_file() || found.contains(&candidate) {
            continue;
        }
        if meta.mode & 0o111 == 0 {
            if file_fallback && fallback.is_none() {
                fallback = Some(candidate);
            }
            continue;
        }
        found.push(candidate);
        if first_only {
            break;
        }
    }
    if found.is_empty()
        && let Some(file) = fallback
    {
        found.push(file);
    }
    found
}

/// `dir/name` for one `PATH` entry; an empty entry is the current directory.
pub(crate) fn path_candidate(dir: &str, name: &str) -> String {
    if dir.is_empty() {
        format!("./{name}")
    } else {
        format!("{}/{name}", dir.trim_end_matches('/'))
    }
}

/// One step requested by a [`PlanDriver`].
pub enum PlanStep {
    /// Run `command` (in `cwd` when set, restoring the shell cwd afterwards)
    /// and pass its result to the next [`PlanDriver::next`] call.
    Run {
        /// The command to execute.
        command: SubCommand,
        /// Working directory for this command only.
        cwd: Option<PathBuf>,
    },
    /// Like [`PlanStep::Run`], but the command's output is only returned to
    /// the driver, never streamed (`$(shell ...)` in make).
    Capture {
        /// The command to execute.
        command: SubCommand,
        /// Working directory for this command only.
        cwd: Option<PathBuf>,
    },
    /// Stream output the driver produced itself (progress lines, errors)
    /// now, ordered before the next command's output. The driver still
    /// returns its full output in [`PlanStep::Done`] for callers that
    /// capture instead of stream. The next call is `next(None)`.
    Emit {
        /// Standard output to stream.
        stdout: crate::StreamData,
        /// Standard error to stream.
        stderr: crate::StreamData,
    },
    /// The plan is finished; this is the builtin's result.
    Done(ExecResult),
}

/// Resumable sub-command driver for [`ExecutionPlan::Driver`].
///
/// The interpreter calls `next(None)` first, then `next(Some(result))` after
/// each [`PlanStep::Run`], until the driver returns [`PlanStep::Done`].
#[async_trait]
pub trait PlanDriver: Send {
    /// Advance the plan with the previous command's result.
    async fn next(&mut self, last: Option<ExecResult>) -> Result<PlanStep>;
}

impl std::fmt::Debug for dyn PlanDriver {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("PlanDriver")
    }
}

/// Execution plan returned by builtins that need to run sub-commands.
///
/// Instead of executing commands directly (which would require interpreter
/// access), builtins return a plan that the interpreter fulfills.
#[derive(Debug)]
pub enum ExecutionPlan {
    /// Run a single command with a timeout.
    Timeout {
        /// Maximum duration before killing the command.
        duration: std::time::Duration,
        /// Whether to preserve the command's exit status on timeout.
        preserve_status: bool,
        /// The command to execute.
        command: SubCommand,
    },
    /// Run one command in a modified copy of the environment (`env`).
    /// Changes are scoped to the command, like a child process.
    Env {
        /// The command to execute.
        command: SubCommand,
        /// Start from an empty environment (`env -i`).
        clear: bool,
        /// Names to remove (`env -u NAME`).
        unset: Vec<String>,
        /// Assignments to apply (`env NAME=VALUE`).
        set: Vec<(String, String)>,
        /// Working directory for the command (`env -C DIR`).
        chdir: Option<String>,
    },
    /// Run a sequence of commands, collecting their output.
    Batch {
        /// Commands to execute in order.
        commands: Vec<SubCommand>,
    },
    /// Step-wise driver: the builtin decides each next command from the
    /// previous one's result (e.g. `find -exec ... \;` as a predicate).
    Driver(Box<dyn PlanDriver>),
    /// Run a sequence of commands, then merge builtin-generated stderr/exit semantics.
    BatchWithStatus {
        /// Commands to execute in order.
        commands: Vec<SubCommand>,
        /// Builtin-generated stderr to prepend to command stderr.
        stderr_prefix: String,
        /// Force non-zero exit (1) when command sequence would otherwise succeed.
        force_error_exit: bool,
    },
}

/// Resolve a path relative to the current working directory.
///
/// If the path is absolute, returns it unchanged.
/// If relative, joins it with the cwd.
///
/// # Example
///
/// ```ignore
/// let abs = resolve_path(Path::new("/home"), "/etc/passwd");
/// assert_eq!(abs, PathBuf::from("/etc/passwd"));
///
/// let rel = resolve_path(Path::new("/home"), "file.txt");
/// assert_eq!(rel, PathBuf::from("/home/file.txt"));
///
/// // Paths are normalized (. and .. resolved)
/// let dot = resolve_path(Path::new("/"), ".");
/// assert_eq!(dot, PathBuf::from("/"));
/// ```
pub fn resolve_path(cwd: &Path, path_str: &str) -> PathBuf {
    let path = Path::new(path_str);
    let joined = if path.is_absolute() {
        path.to_path_buf()
    } else {
        vfs_join(cwd, path)
    };
    // Normalize the path to handle . and .. components
    normalize_path(&joined)
}

// Re-export shared normalize_path for use by builtins
use crate::fs::normalize_path;
use crate::fs::vfs_join;

/// Execution context for builtin commands.
///
/// Provides access to the shell execution environment including arguments,
/// variables, filesystem, and pipeline input.
///
/// # Example
///
/// ```rust
/// use bashkit::{Builtin, BuiltinContext, ExecResult, async_trait};
///
/// struct Echo;
///
/// #[async_trait]
/// impl Builtin for Echo {
///     async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
///         // Access command arguments
///         let output = ctx.args.join(" ");
///
///         // Access environment variables
///         let _home = ctx.env.get("HOME");
///
///         // Access pipeline input
///         if let Some(stdin) = ctx.stdin {
///             return Ok(ExecResult::ok(stdin.to_string()));
///         }
///
///         Ok(ExecResult::ok(format!("{}\n", output)))
///     }
/// }
/// ```
pub struct Context<'a> {
    /// Command arguments (not including the command name).
    ///
    /// For `mycommand arg1 arg2`, this contains `["arg1", "arg2"]`.
    pub args: &'a [String],

    /// Environment variables.
    ///
    /// Read-only access to variables set via [`BashBuilder::env`](crate::BashBuilder::env)
    /// or the `export` builtin.
    pub env: &'a HashMap<String, String>,

    /// Shell variables (mutable).
    ///
    /// Allows builtins to set or modify shell variables.
    #[allow(dead_code)] // Will be used by set, export, declare builtins
    pub variables: &'a mut HashMap<String, String>,

    /// Current working directory (mutable).
    ///
    /// Used by `cd` and path resolution.
    pub cwd: &'a mut PathBuf,

    /// Virtual filesystem.
    ///
    /// Provides async file operations (read, write, mkdir, etc.). Custom and
    /// extension builtins receive a revocable view: cloned handles fail after
    /// the current execution completes or is cancelled.
    pub fs: Arc<dyn FileSystem>,

    /// Standard input from pipeline.
    ///
    /// Contains output from the previous command in a pipeline.
    /// For `echo hello | mycommand`, stdin will be `Some("hello\n")`.
    pub stdin: Option<&'a crate::StreamData>,

    /// HTTP client for network operations (curl, wget).
    ///
    /// Only available when the `network` feature is enabled and
    /// a [`NetworkAllowlist`](crate::NetworkAllowlist) is configured via
    /// [`BashBuilder::network`](crate::BashBuilder::network).
    #[cfg(feature = "http_client")]
    pub http_client: Option<&'a std::sync::Arc<crate::network::HttpClient>>,

    /// Git client for git operations.
    ///
    /// Only available when the `git` feature is enabled and
    /// a [`GitConfig`](crate::GitConfig) is configured via
    /// [`BashBuilder::git`](crate::BashBuilder::git).
    #[cfg(feature = "git")]
    pub git_client: Option<&'a crate::builtins::git::GitClient>,

    /// SSH client for ssh/scp/sftp operations.
    ///
    /// Only available when the `ssh` feature is enabled and
    /// an [`SshConfig`](crate::SshConfig) is configured via
    /// [`BashBuilder::ssh`](crate::BashBuilder::ssh).
    #[cfg(feature = "ssh")]
    pub ssh_client: Option<&'a crate::builtins::ssh::SshClient>,

    /// Direct access to interpreter shell state.
    ///
    /// Provides internal builtins with:
    /// - **Mutable access** to aliases and traps (simple HashMap state)
    /// - **Read-only access** to functions, builtins, call stack, history, jobs
    ///
    /// `None` for custom/external builtins; `Some(...)` for internal builtins
    /// that need interpreter state (e.g. `type`, `alias`, `trap`).
    ///
    /// Design: aliases/traps are directly mutable because they're simple HashMaps
    /// with no invariants. Arrays use [`BuiltinSideEffect`] because they need
    /// budget checking. History uses side effects for VFS persistence.
    pub(crate) shell: Option<ShellRef<'a>>,
}

/// Stdin pipe of a streaming filter stage, see [`Context::stdin_stream`].
pub(crate) struct StdinStream {
    pipe: std::sync::Arc<crate::interpreter::pipe::Pipe>,
    budget: crate::ExecutionBudget,
}

impl StdinStream {
    /// Next chunk of input; empty at end of input.
    pub(crate) async fn read(&self) -> Result<Vec<u8>> {
        let bytes = self.budget.run(self.pipe.read_some()).await?;
        // THREAT[TM-DOS-096]: streaming consumers share the same input ledger
        // as buffered utilities and public CommandInput readers.
        self.budget.consume_input(bytes.len())?;
        self.budget
            .consume_work(1 + bytes.len().div_ceil(1024) as u64)?;
        Ok(bytes)
    }

    /// Everything left, for filters that need their whole input.
    pub(crate) async fn read_to_end(&self) -> Result<crate::limits::BudgetedBytes> {
        let mut bytes = crate::limits::BudgetedBytes::new(Some(&self.budget))?;
        loop {
            let chunk = self.read().await?;
            if chunk.is_empty() {
                return Ok(bytes);
            }
            bytes.try_extend_from_slice(&chunk)?;
        }
    }
}

/// Collected input keeps both byte and text storage admitted while in use.
pub(crate) struct CollectedInput {
    data: crate::StreamData,
    _storage: crate::stream::StreamStorage,
}

impl std::ops::Deref for CollectedInput {
    type Target = crate::StreamData;
    fn deref(&self) -> &Self::Target {
        &self.data
    }
}

/// Bytes a streaming filter handles per step (one pipe's capacity).
pub(crate) const STREAM_CHUNK_BYTES: usize = 4 * 1024;

/// Input of a streaming filter cut into pieces the filter can handle one at
/// a time: the data buffered before the stage started, then the stdin pipe
/// as it fills (or one file's bytes). Each piece ends where `cut` says (a
/// record end, a UTF-8 boundary) and is at most about
/// [`STREAM_CHUNK_BYTES`] unless one record is longer; the tail comes at
/// end of input.
pub(crate) struct InputChunks<'c> {
    buf: crate::limits::BudgetedBytes,
    pos: usize,
    buffered: Option<std::borrow::Cow<'c, [u8]>>,
    buffered_pos: usize,
    budget: Option<crate::ExecutionBudget>,
    input: Option<StdinStream>,
    eof: bool,
}

impl<'c> InputChunks<'c> {
    /// Stdin of this builtin: `ctx.stdin`, then the streaming pipe if any.
    pub(crate) fn stdin(ctx: &Context<'c>) -> Result<Self> {
        let budget = ctx.shell.as_ref().map(|s| s.execution_budget.clone());
        Ok(Self {
            buf: crate::limits::BudgetedBytes::new(budget.as_ref())?,
            pos: 0,
            buffered: ctx.stdin.map(|s| std::borrow::Cow::Borrowed(s.as_bytes())),
            buffered_pos: 0,
            budget,
            input: ctx.stdin_stream(),
            eof: false,
        })
    }

    /// Input that is already all in memory (a file's contents).
    pub(crate) fn bytes(ctx: &Context<'c>, bytes: Vec<u8>) -> Result<Self> {
        let mut input = Self::stdin(ctx)?;
        input.buffered = Some(std::borrow::Cow::Owned(bytes));
        input.input = None;
        Ok(input)
    }

    /// Next piece, or `None` at end of input. `cut(data)` returns how many
    /// leading bytes of `data` can be handled now (0 for "need more").
    pub(crate) async fn next(
        &mut self,
        cut: impl Fn(&[u8]) -> usize,
    ) -> Result<Option<crate::limits::BudgetedBytes>> {
        loop {
            let rest = &self.buf[self.pos..];
            let window = rest.len().min(STREAM_CHUNK_BYTES);
            let mut n = cut(&rest[..window]);
            if n == 0 && rest.len() > window {
                n = cut(rest);
            }
            if n == 0 && self.eof {
                n = rest.len();
            }
            if n > 0 {
                // THREAT[TM-DOS-103]: include long records and their returned
                // copies in live storage; a bounded pipe alone is insufficient.
                let mut piece = crate::limits::BudgetedBytes::new(self.budget.as_ref())?;
                piece.try_extend_from_slice(&rest[..n])?;
                self.pos += n;
                return Ok(Some(piece));
            }
            if self.eof {
                return Ok(None);
            }
            self.buf.copy_within(self.pos.., 0);
            let remaining = self.buf.len() - self.pos;
            self.buf.truncate(remaining);
            self.pos = 0;
            if let Some(buffered) = &self.buffered {
                let end = (self.buffered_pos + STREAM_CHUNK_BYTES).min(buffered.len());
                self.buf
                    .try_extend_from_slice(&buffered[self.buffered_pos..end])?;
                self.buffered_pos = end;
                if end == buffered.len() {
                    self.buffered = None;
                }
                continue;
            }
            let more = match &self.input {
                Some(input) => input.read().await?,
                None => Vec::new(),
            };
            if more.is_empty() {
                self.eof = true;
            } else {
                self.buf.try_extend_from_slice(&more)?;
            }
        }
    }
}

/// [`InputChunks`] cut after the last `term`-terminated record.
pub(crate) fn cut_records(term: u8) -> impl Fn(&[u8]) -> usize {
    move |data| data.iter().rposition(|&b| b == term).map_or(0, |p| p + 1)
}

/// [`InputChunks`] cut at the last complete UTF-8 character; invalid bytes
/// are passed through so the filter can treat them as bytes.
pub(crate) fn cut_utf8(data: &[u8]) -> usize {
    match std::str::from_utf8(data) {
        Err(e) if e.error_len().is_none() => e.valid_up_to(),
        _ => data.len(),
    }
}

/// Stdout pipe of a streaming pipeline stage, see [`Context::stdout_stream`].
pub(crate) struct StdoutStream(crate::command::CommandOutput);

impl StdoutStream {
    /// Wait for room in the pipe, then write. False once nobody reads.
    pub(crate) async fn write(&self, data: &[u8]) -> Result<bool> {
        match self.0.write_all(data).await {
            Ok(()) => Ok(true),
            Err(crate::Error::Io(error)) if error.kind() == std::io::ErrorKind::BrokenPipe => {
                Ok(false)
            }
            Err(error) => Err(error),
        }
    }
}

impl<'a> Context<'a> {
    /// Exact pipeline stdin bytes.
    pub fn stdin_bytes(&self) -> Option<&[u8]> {
        self.stdin.map(crate::StreamData::as_bytes)
    }

    /// Pipeline stdin decoded for a text-only builtin.
    pub fn stdin_text_lossy(&self) -> Option<std::borrow::Cow<'_, str>> {
        self.stdin.map(crate::StreamData::text_lossy)
    }

    /// Aggregate budget shared by this request's commands and runtimes.
    pub fn execution_budget(
        &self,
    ) -> Option<crate::ExecutionCapability<crate::limits::ExecutionBudget>> {
        self.execution_extension::<crate::limits::ExecutionBudget>()
    }

    /// Charge bytes materialized after dispatch, such as VFS file contents.
    pub(crate) fn consume_budget_input(&self, bytes: usize) -> Result<()> {
        if let Some(budget) = self.execution_budget() {
            budget
                .try_with(|budget| budget.consume_input(bytes))
                .map_err(|_| crate::Error::Cancelled)??;
        }
        Ok(())
    }

    /// Charge scalable internal work that is not a shell command boundary.
    pub(crate) fn consume_budget_work(&self, units: u64) -> Result<()> {
        if let Some(budget) = self.execution_budget() {
            budget
                .try_with(|budget| budget.consume_work(units))
                .map_err(|_| crate::Error::Cancelled)??;
        }
        Ok(())
    }

    /// Lease intermediate storage until the returned guard drops.
    pub(crate) fn lease_budget_bytes(
        &self,
        bytes: usize,
    ) -> Result<Option<crate::limits::ExecutionBudgetLease>> {
        self.execution_budget()
            .map(|budget| {
                budget
                    .try_with(|budget| budget.lease_bytes(bytes))
                    .map_err(|_| crate::Error::Cancelled)?
                    .map_err(Into::into)
            })
            .transpose()
    }

    /// Run async boundary work under this request's cancellation/lifecycle gate.
    ///
    /// Host callbacks invoked from a builtin should run through this so a
    /// cancelled or over-budget request drops the callback future.
    pub async fn run_budgeted<F>(&self, future: F) -> Result<F::Output>
    where
        F: std::future::Future,
    {
        match self.execution_budget() {
            Some(budget) => {
                let budget = budget
                    .try_with(Clone::clone)
                    .map_err(|_| crate::Error::Cancelled)?;
                budget.run(future).await.map_err(Into::into)
            }
            None => Ok(future.await),
        }
    }

    /// Look up a typed, revocable per-execution extension, if present.
    pub fn execution_extension<T>(&self) -> Option<crate::ExecutionCapability<T>>
    where
        T: Send + Sync + 'static,
    {
        self.shell
            .as_ref()
            .and_then(|shell| shell.execution_extensions.get::<T>())
    }

    /// Streaming stdout when this builtin is a producer stage of a
    /// concurrent pipeline (`yes | head -1`). Write chunks as they are made
    /// instead of returning them in `ExecResult::stdout`; when a write
    /// reports the reader gone, stop and exit 141 (SIGPIPE).
    pub(crate) fn stdout_stream(&self) -> Option<StdoutStream> {
        self.shell
            .as_ref()
            .and_then(|shell| shell.stdout_stream.clone())
            .map(StdoutStream)
    }

    /// Streaming stdin when this builtin is a filter stage of a concurrent
    /// pipeline (`loop | cat | head -1`). `ctx.stdin` then holds only data
    /// already buffered before the stage started; read the rest here.
    pub(crate) fn stdin_stream(&self) -> Option<StdinStream> {
        self.shell.as_ref().and_then(|shell| {
            shell.stdin_pipe.clone().map(|pipe| StdinStream {
                pipe,
                budget: shell.execution_budget.clone(),
            })
        })
    }

    /// All of stdin, including what is still in a streaming stdin pipe, for
    /// a filter stage that needs its whole input before it can write.
    pub(crate) async fn stdin_to_end(&self) -> Result<CollectedInput> {
        let budget = self.shell.as_ref().map(|s| s.execution_budget.clone());
        let mut all = crate::limits::BudgetedBytes::new(budget.as_ref())?;
        if let Some(stdin) = self.stdin {
            all.try_extend_from_slice(stdin.as_bytes())?;
        }
        if let Some(input) = self.stdin_stream() {
            loop {
                let chunk = input.read().await?;
                if chunk.is_empty() {
                    break;
                }
                all.try_extend_from_slice(&chunk)?;
            }
        }
        self.collected_input(all)
    }

    pub(crate) fn collected_input(
        &self,
        bytes: crate::limits::BudgetedBytes,
    ) -> Result<CollectedInput> {
        let (data, storage) = if let Some(shell) = &self.shell {
            crate::StreamData::from_budgeted_bytes(bytes, shell.execution_budget)?
        } else {
            (bytes.into_parts().0.into(), [None, None])
        };
        Ok(CollectedInput {
            data,
            _storage: storage,
        })
    }

    /// Remaining wall-clock budget of the current `exec*` call, if limited.
    pub fn remaining_deadline(&self) -> Option<std::time::Duration> {
        self.execution_extension::<ExecutionDeadline>()?
            .try_with(ExecutionDeadline::remaining)
            .ok()
    }

    #[cfg(any(feature = "python", feature = "typescript"))]
    pub(crate) fn execution_extensions(&self) -> Option<std::sync::Arc<ExecutionExtensions>> {
        self.shell
            .as_ref()
            .map(|shell| shell.execution_extensions.clone())
    }

    /// Bind a host value to the current execution lease.
    pub fn execution_capability<T>(&self, value: T) -> Option<crate::ExecutionCapability<T>>
    where
        T: Send + Sync + 'static,
    {
        self.shell
            .as_ref()
            .and_then(|shell| shell.execution_extensions.capability(value))
    }

    /// Create a new Context for testing purposes.
    ///
    /// This helper handles the conditional `http_client` field automatically.
    #[cfg(test)]
    pub fn new_for_test(
        args: &'a [String],
        env: &'a std::collections::HashMap<String, String>,
        variables: &'a mut std::collections::HashMap<String, String>,
        cwd: &'a mut std::path::PathBuf,
        fs: std::sync::Arc<dyn crate::fs::FileSystem>,
        stdin: Option<&'a str>,
    ) -> Self {
        let stdin = stdin.map(|text| {
            let stream: &'static crate::StreamData =
                Box::leak(Box::new(crate::StreamData::from(text)));
            stream as &'a crate::StreamData
        });
        Self {
            args,
            env,
            variables,
            cwd,
            fs,
            stdin,
            #[cfg(feature = "http_client")]
            http_client: None,
            #[cfg(feature = "git")]
            git_client: None,
            #[cfg(feature = "ssh")]
            ssh_client: None,
            shell: None,
        }
    }
}

#[cfg(test)]
pub(crate) fn test_stream(text: &str) -> &'static crate::StreamData {
    Box::leak(Box::new(crate::StreamData::from(text)))
}

#[cfg(test)]
pub(crate) fn test_stream_opt(text: Option<&str>) -> Option<&'static crate::StreamData> {
    text.map(test_stream)
}

/// Trait for implementing builtin commands.
///
/// All custom builtins must implement this trait. The trait requires `Send + Sync`
/// for thread safety in async contexts.
///
/// # Example
///
/// ```rust
/// use bashkit::{Bash, Builtin, BuiltinContext, ExecResult, async_trait};
///
/// struct Greet {
///     default_name: String,
/// }
///
/// #[async_trait]
/// impl Builtin for Greet {
///     async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
///         let name = ctx.args.first()
///             .map(|s| s.as_str())
///             .unwrap_or(&self.default_name);
///         Ok(ExecResult::ok(format!("Hello, {}!\n", name)))
///     }
/// }
///
/// // Register the builtin
/// let bash = Bash::builder()
///     .builtin("greet", Box::new(Greet { default_name: "World".into() }))
///     .build();
/// ```
///
/// # LLM Hints
///
/// Builtins can provide short hints for LLM system prompts via [`llm_hint`](Builtin::llm_hint).
/// These appear in the tool's `help()` and `system_prompt()` output so LLMs know
/// about capabilities and limitations.
///
/// # Return Values
///
/// Return [`ExecResult::ok`](crate::ExecResult::ok) for success with output,
/// or [`ExecResult::err`](crate::ExecResult::err) for errors with exit code.
#[async_trait]
pub trait Builtin: Send + Sync {
    /// Internal bridge used by registered `Command` adapters.
    #[doc(hidden)]
    fn streams_io(&self) -> bool {
        false
    }
    /// Execute the builtin command.
    ///
    /// # Arguments
    ///
    /// * `ctx` - The execution context containing arguments, environment, and filesystem
    ///
    /// # Returns
    ///
    /// * `Ok(ExecResult)` - Execution result with stdout, stderr, and exit code
    /// * `Err(Error)` - Fatal error that should abort execution
    async fn execute(&self, ctx: Context<'_>) -> Result<ExecResult>;

    /// Return an execution plan for sub-command execution.
    ///
    /// Builtins that need to execute other commands (e.g. `timeout`, `xargs`,
    /// `find -exec`) override this to return an `ExecutionPlan`. The interpreter
    /// fulfills the plan by executing the sub-commands and returning results.
    ///
    /// When this returns `Some(plan)`, the interpreter ignores the `execute()`
    /// result and instead runs the plan. When `None`, normal `execute()` is used.
    ///
    /// The default implementation returns `Ok(None)`.
    async fn execution_plan(&self, _ctx: &Context<'_>) -> Result<Option<ExecutionPlan>> {
        Ok(None)
    }

    /// Optional short hint for LLM system prompts.
    ///
    /// Return a concise one-line description of capabilities and limitations.
    /// These hints are included in `help()` and `system_prompt()` output
    /// when the builtin is registered.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// fn llm_hint(&self) -> Option<&'static str> {
    ///     Some("mycommand: Processes data files. Max 10MB input. No network access.")
    /// }
    /// ```
    fn llm_hint(&self) -> Option<&'static str> {
        None
    }

    /// Clear hidden per-instance state that must not survive snapshot restore.
    ///
    /// Most builtins are stateless and keep the default no-op. Builtins with
    /// session caches must override this so [`Bash::restore_snapshot`](crate::Bash::restore_snapshot)
    /// restores the full observable boundary, not just shell variables and VFS bytes.
    fn reset_session_state(&self) {}
}

/// Trait for custom builtins that parse arguments with [`clap`].
///
/// Implement this trait when a builtin has enough flags/options that deriving a
/// `clap::Parser` struct is clearer than manually inspecting [`Context::args`].
///
/// # Example
///
/// ```rust
/// use bashkit::{Bash, BashkitContext, ClapBuiltin, async_trait};
/// use bashkit::clap::Parser;
///
/// #[derive(Parser)]
/// #[command(name = "greet")]
/// struct GreetArgs {
///     #[arg(short, long, default_value = "World")]
///     name: String,
/// }
///
/// struct Greet;
///
/// #[async_trait]
/// impl ClapBuiltin for Greet {
///     type Args = GreetArgs;
///
///     async fn execute_clap(
///         &self,
///         args: Self::Args,
///         ctx: &mut BashkitContext<'_>,
///     ) -> bashkit::Result<()> {
///         ctx.write_stdout(format!("Hello, {}!\n", args.name));
///         Ok(())
///     }
/// }
///
/// # #[tokio::main]
/// # async fn main() -> bashkit::Result<()> {
/// let mut bash = Bash::builder()
///     .builtin("greet", Box::new(Greet))
///     .build();
/// let result = bash.exec("greet --name Alice").await?;
/// assert_eq!(result.stdout, "Hello, Alice!\n");
/// # Ok(())
/// # }
/// ```
#[async_trait]
pub trait ClapBuiltin: Send + Sync {
    /// Clap parser type for this builtin's arguments.
    type Args: clap::Parser + Send + 'static;

    /// Execute the builtin with already-parsed clap arguments.
    async fn execute_clap(&self, args: Self::Args, ctx: &mut BashkitContext<'_>) -> Result<()>;

    /// Optional short hint for LLM system prompts.
    fn llm_hint(&self) -> Option<&'static str> {
        None
    }

    /// Clear hidden per-instance state that must not survive snapshot restore.
    ///
    /// Most builtins are stateless and keep the default no-op. Builtins with
    /// session caches must override this so [`Bash::restore_snapshot`](crate::Bash::restore_snapshot)
    /// restores the full observable boundary, not just shell variables and VFS bytes.
    fn reset_session_state(&self) {}
}

/// Mutable execution context for [`ClapBuiltin`] implementations.
///
/// This context keeps clap-backed builtins close to normal CLI code: handlers
/// write to stdout/stderr, set an exit code when needed, and return
/// `bashkit::Result<()>` for fatal host-side errors.
pub struct BashkitContext<'a> {
    inner: Context<'a>,

    /// Captured stdout for this builtin invocation.
    pub stdout: String,

    /// Captured stderr for this builtin invocation.
    pub stderr: String,

    /// Exit code for this builtin invocation.
    pub exit_code: i32,
}

impl<'a> BashkitContext<'a> {
    fn new(inner: Context<'a>) -> Self {
        Self {
            inner,
            stdout: String::new(),
            stderr: String::new(),
            exit_code: 0,
        }
    }

    fn into_exec_result(self) -> ExecResult {
        ExecResult {
            stdout: self.stdout.into(),
            stderr: self.stderr.into(),
            exit_code: self.exit_code,
            ..Default::default()
        }
    }

    /// Original shell words passed to the builtin, after shell expansion.
    pub fn raw_args(&self) -> &[String] {
        self.inner.args
    }

    /// Environment variables visible to this builtin.
    pub fn env(&self) -> &HashMap<String, String> {
        self.inner.env
    }

    /// Mutable shell variables.
    pub fn variables(&mut self) -> &mut HashMap<String, String> {
        self.inner.variables
    }

    /// Current working directory.
    pub fn cwd(&self) -> &Path {
        self.inner.cwd
    }

    /// Mutable current working directory.
    pub fn cwd_mut(&mut self) -> &mut PathBuf {
        self.inner.cwd
    }

    /// Virtual filesystem for this shell.
    pub fn fs(&self) -> Arc<dyn FileSystem> {
        Arc::clone(&self.inner.fs)
    }

    /// Pipeline stdin, if the builtin is invoked after a pipe.
    pub fn stdin(&self) -> Option<&str> {
        self.inner.stdin.and_then(|stdin| stdin.text().ok())
    }

    /// Look up a typed per-execution extension, if present.
    pub fn execution_extension<T>(&self) -> Option<crate::ExecutionCapability<T>>
    where
        T: Send + Sync + 'static,
    {
        self.inner.execution_extension::<T>()
    }

    /// Append text to stdout.
    pub fn write_stdout(&mut self, output: impl AsRef<str>) {
        self.stdout.push_str(output.as_ref());
    }

    /// Append text to stderr.
    pub fn write_stderr(&mut self, output: impl AsRef<str>) {
        self.stderr.push_str(output.as_ref());
    }

    /// Set the command exit code.
    pub fn set_exit_code(&mut self, exit_code: i32) {
        self.exit_code = exit_code;
    }

    /// Append stderr text and set a failing exit code.
    pub fn fail(&mut self, stderr: impl AsRef<str>, exit_code: i32) {
        self.write_stderr(stderr);
        self.set_exit_code(exit_code);
    }
}

#[async_trait]
impl<T> Builtin for T
where
    T: ClapBuiltin,
{
    async fn execute(&self, ctx: Context<'_>) -> Result<ExecResult> {
        // No `.color(ColorChoice::Never)` here, and it is not because the
        // workspace pins clap with `default-features = false`. Feature
        // unification is not ours to decide: a consumer that links clap with
        // default features turns `color` on for bashkit's clap too, and
        // `Command::color` does not even exist as a method without that
        // feature, so calling it would make the colourless build stop
        // compiling. Two things keep the output clean instead. clap renders
        // errors and help through `Display for StyledStr`, which strips ANSI
        // with `anstream::adapter::strip_str` whenever `color` is on, and
        // `clap_error_to_exec_result` strips again on our side so the
        // guarantee does not rest on clap's internals. Builtin output is
        // usually an LLM tool result, never a terminal.
        let mut command = <T::Args as CommandFactory>::command();
        let command_name = command.get_name().to_string();
        let argv = std::iter::once(command_name).chain(ctx.args.iter().cloned());

        let mut matches = match command.try_get_matches_from_mut(argv) {
            Ok(matches) => matches,
            Err(error) => return Ok(clap_error_to_exec_result(error)),
        };
        let args = match <T::Args as FromArgMatches>::from_arg_matches_mut(&mut matches) {
            Ok(args) => args,
            Err(error) => return Ok(clap_error_to_exec_result(error)),
        };

        let mut ctx = BashkitContext::new(ctx);
        self.execute_clap(args, &mut ctx).await?;
        Ok(ctx.into_exec_result())
    }

    fn llm_hint(&self) -> Option<&'static str> {
        ClapBuiltin::llm_hint(self)
    }

    fn reset_session_state(&self) {
        ClapBuiltin::reset_session_state(self);
    }
}

/// Drop ANSI escape sequences from rendered clap text.
///
/// THREAT[TM-INF-022]-adjacent: builtin output is usually an LLM tool result,
/// so escape sequences are noise a model has to parse around. clap already
/// strips styling in its `Display` impl when the `color` feature is enabled,
/// but whether that feature is enabled at all depends on how the *consumer*
/// unifies clap's features, so do not depend on it.
///
/// Recognises the ECMA-48 forms clap styling can produce: CSI
/// (`ESC [` … final `0x40..=0x7E`), OSC (`ESC ]` … `BEL` or `ESC \`), and
/// two- or three-byte escapes (`ESC` … intermediates `0x20..=0x2F` … final).
/// A dangling trailing `ESC` is dropped rather than emitted.
fn strip_ansi(text: &str) -> String {
    if !text.contains('\u{1b}') {
        return text.to_string();
    }

    let mut out = String::with_capacity(text.len());
    let mut chars = text.chars().peekable();
    while let Some(ch) = chars.next() {
        if ch != '\u{1b}' {
            out.push(ch);
            continue;
        }
        match chars.next() {
            // CSI: parameters/intermediates then a final byte.
            Some('[') => {
                for next in chars.by_ref() {
                    if ('\u{40}'..='\u{7e}').contains(&next) {
                        break;
                    }
                }
            }
            // OSC: terminated by BEL or ST (ESC \).
            Some(']') => {
                while let Some(next) = chars.next() {
                    if next == '\u{7}' {
                        break;
                    }
                    if next == '\u{1b}' {
                        if chars.peek() == Some(&'\\') {
                            chars.next();
                        }
                        break;
                    }
                }
            }
            // Intermediate byte: consume the rest of the intermediates and the
            // final byte, e.g. `ESC ( B` (charset designation).
            Some(byte) if ('\u{20}'..='\u{2f}').contains(&byte) => {
                while let Some(next) = chars.peek() {
                    if ('\u{20}'..='\u{2f}').contains(next) {
                        chars.next();
                    } else {
                        break;
                    }
                }
                chars.next();
            }
            // Any other two-byte escape; already consumed its selector.
            Some(_) => {}
            // Dangling ESC at end of input.
            None => {}
        }
    }
    out
}

fn clap_error_to_exec_result(error: clap::Error) -> ExecResult {
    let text = strip_ansi(&error.to_string());
    if matches!(
        error.kind(),
        clap::error::ErrorKind::DisplayHelp | clap::error::ErrorKind::DisplayVersion
    ) {
        return ExecResult::ok(text);
    }

    ExecResult::err(cap_diagnostic(text, 1024), error.exit_code())
}

fn cap_diagnostic(mut text: String, max_bytes: usize) -> String {
    if text.len() <= max_bytes {
        return text;
    }

    let cut = text
        .char_indices()
        .map(|(idx, _)| idx)
        .take_while(|idx| *idx <= max_bytes)
        .last()
        .unwrap_or(0);
    text.truncate(cut);
    text
}

#[async_trait]
impl Builtin for std::sync::Arc<dyn Builtin> {
    fn streams_io(&self) -> bool {
        (**self).streams_io()
    }
    async fn execute(&self, ctx: Context<'_>) -> Result<ExecResult> {
        (**self).execute(ctx).await
    }

    async fn execution_plan(&self, ctx: &Context<'_>) -> Result<Option<ExecutionPlan>> {
        (**self).execution_plan(ctx).await
    }

    fn llm_hint(&self) -> Option<&'static str> {
        (**self).llm_hint()
    }
}

/// Internal alias for `crate::testing` so per-tool `#[cfg(test)]`
/// modules can keep their existing `crate::builtins::debug_leak_check::*`
/// imports. The source of truth is `crate::testing` (which is also
/// reachable from integration tests and cargo-fuzz targets).
#[cfg(test)]
pub(crate) use crate::testing as debug_leak_check;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fs::{FileSystem, InMemoryFs};

    #[test]
    fn test_resolve_path_absolute() {
        let cwd = PathBuf::from("/home/user");
        let result = resolve_path(&cwd, "/tmp/file.txt");
        assert_eq!(result, PathBuf::from("/tmp/file.txt"));
    }

    #[test]
    fn test_resolve_path_relative() {
        let cwd = PathBuf::from("/home/user");
        let result = resolve_path(&cwd, "downloads/file.txt");
        assert_eq!(result, PathBuf::from("/home/user/downloads/file.txt"));
    }

    #[test]
    fn test_resolve_path_dot_from_root() {
        // "." from root should normalize to "/"
        let cwd = PathBuf::from("/");
        let result = resolve_path(&cwd, ".");
        assert_eq!(result, PathBuf::from("/"));
    }

    #[test]
    fn test_resolve_path_dot_from_normal_dir() {
        // "." should be stripped, returning the cwd itself
        let cwd = PathBuf::from("/home/user");
        let result = resolve_path(&cwd, ".");
        assert_eq!(result, PathBuf::from("/home/user"));
    }

    #[test]
    fn test_resolve_path_dotdot() {
        // ".." should go up one directory
        let cwd = PathBuf::from("/home/user");
        let result = resolve_path(&cwd, "..");
        assert_eq!(result, PathBuf::from("/home"));
    }

    #[test]
    fn test_resolve_path_dotdot_from_root() {
        // ".." from root stays at root
        let cwd = PathBuf::from("/");
        let result = resolve_path(&cwd, "..");
        assert_eq!(result, PathBuf::from("/"));
    }

    #[test]
    fn test_resolve_path_complex() {
        // Complex path with . and ..
        let cwd = PathBuf::from("/home/user");
        let result = resolve_path(&cwd, "./downloads/../documents/./file.txt");
        assert_eq!(result, PathBuf::from("/home/user/documents/file.txt"));
    }

    #[tokio::test]
    async fn read_text_file_returns_lossy_utf8() {
        let fs = InMemoryFs::new();
        fs.write_file(Path::new("/tmp/data.bin"), b"hi\xffthere")
            .await
            .unwrap();

        let text = read_text_file(&fs, Path::new("/tmp/data.bin"), "cat")
            .await
            .unwrap();

        assert_eq!(text, "hi\u{fffd}there");
    }

    #[tokio::test]
    async fn read_text_file_formats_missing_file_errors() {
        let fs = InMemoryFs::new();
        let err = read_text_file(&fs, Path::new("/tmp/missing.txt"), "cat")
            .await
            .unwrap_err();

        assert_eq!(err.exit_code, 1);
        assert!(err.stderr.contains("cat: /tmp/missing.txt:"));
    }

    #[test]
    fn check_help_version_returns_help() {
        let args = vec!["--help".to_string()];
        let r = check_help_version(&args, "usage text\n", Some("v1.0"));
        assert!(r.is_some());
        assert_eq!(r.unwrap().stdout, "usage text\n");
    }

    #[test]
    fn check_help_version_returns_version() {
        let args = vec!["--version".to_string()];
        let r = check_help_version(&args, "usage\n", Some("tool 1.0"));
        assert!(r.is_some());
        assert_eq!(r.unwrap().stdout, "tool 1.0\n");
    }

    #[test]
    fn check_help_version_no_version_configured() {
        let args = vec!["--version".to_string()];
        let r = check_help_version(&args, "usage\n", None);
        assert!(r.is_none());
    }

    #[test]
    fn check_help_version_stops_at_non_flag() {
        let args = vec!["file.txt".to_string(), "--help".to_string()];
        let r = check_help_version(&args, "usage\n", None);
        assert!(r.is_none());
    }

    #[test]
    fn check_help_version_stops_at_option_delimiter() {
        let args = vec!["--".to_string(), "--help".to_string()];
        let r = check_help_version(&args, "usage\n", Some("v1"));
        assert!(r.is_none());
    }

    #[test]
    fn check_help_version_no_match() {
        let args = vec!["-c".to_string(), "filter".to_string()];
        let r = check_help_version(&args, "usage\n", Some("v1"));
        assert!(r.is_none());
    }

    // -------------------------------------------------------------------------
    // TM-INF-022: stderr from builtins must not leak Rust Debug shapes.
    //
    // Static guard — walks every `crates/bashkit/src/builtins/*.rs` file
    // and asserts no Rust Debug format directives appear, modulo
    // `// debug-ok: <reason>` per-line opt-outs.
    //
    // Dynamic counterpart: each tool's own `mod tests` exercises its
    // error paths through `super::debug_leak_check::assert_no_leak`.
    // -------------------------------------------------------------------------

    #[test]
    fn no_debug_fmt_in_builtin_source() {
        // Match `{:?}`, `{:#?}`, `{name:?}`, `{name:#?}`. // debug-ok: pattern doc
        let pat = regex::Regex::new(r"\{[A-Za-z0-9_]*:#?\?\}").unwrap();
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/builtins");
        let mut violations = Vec::new();

        // Recursive walk so submodule directories like `builtins/jq/` are
        // covered too. The TM-INF-022 invariant must hold for every builtin
        // source file regardless of layout.
        fn walk(dir: &std::path::Path, violations: &mut Vec<String>, pat: &regex::Regex) {
            for entry in std::fs::read_dir(dir).expect("read builtins dir") {
                let entry = entry.unwrap();
                let path = entry.path();
                if path.is_dir() {
                    walk(&path, violations, pat);
                    continue;
                }
                if path.extension().is_none_or(|e| e != "rs") {
                    continue;
                }
                let src = std::fs::read_to_string(&path).expect("read source");
                for (i, line) in src.lines().enumerate() {
                    if line.contains("// debug-ok:") {
                        continue;
                    }
                    if line.trim_start().starts_with("#[derive(") {
                        continue;
                    }
                    if pat.is_match(line) {
                        // Show parent dir + filename so jq submodules are
                        // distinguishable from the top-level files.
                        let rel = path
                            .strip_prefix(std::path::Path::new(env!("CARGO_MANIFEST_DIR")))
                            .unwrap_or(&path);
                        violations.push(format!(
                            "{}:{}: {}",
                            rel.display(),
                            i + 1,
                            line.trim_end()
                        ));
                    }
                }
            }
        }
        walk(&dir, &mut violations, &pat);

        assert!(
            violations.is_empty(),
            "Rust Debug formatting found in builtin source. This leaks \
             internal struct shapes into stderr where LLM agents see them. \
             Use Display ({{}}) or a domain-specific formatter. Add \
             `// debug-ok: <reason>` to the line for legitimate test \
             asserts.\n\nViolations:\n{}",
            violations.join("\n")
        );
    }

    // -------------------------------------------------------------------------
    // Issue #2425: VFS paths are Unix-style on every host, but
    // `PathBuf::join`/`push` insert the *host* separator, so on Windows a
    // joined path prints as `/d/proj\src\main.rs`.
    //
    // Static guard — the shapes that build a VFS path from a cwd or from a
    // directory entry must go through `crate::fs::vfs_join`. The dynamic
    // counterpart is the `windows_containment_*` tests next to `vfs_join` and
    // the affected builtins, which the Windows CI job runs.
    // -------------------------------------------------------------------------

    #[test]
    fn no_host_separator_joins_on_vfs_paths() {
        // `Path::join` shapes seen on VFS paths: a cwd-relative operand and a
        // directory entry appended during a recursive walk.
        let shapes = ["cwd.join(", ".join(&entry.name)", ".join(&e.name)"];
        // Every crate in the workspace, not just this one: the sibling crates
        // (CLI, bindings, bench) build VFS paths too.
        let workspace = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .parent()
            .expect("crates/ dir");
        let mut violations = Vec::new();

        fn walk(
            dir: &std::path::Path,
            root: &std::path::Path,
            shapes: &[&str],
            violations: &mut Vec<String>,
        ) {
            for entry in std::fs::read_dir(dir).expect("read source dir") {
                let entry = entry.unwrap();
                let path = entry.path();
                if path.is_dir() {
                    walk(&path, root, shapes, violations);
                    continue;
                }
                if path.extension().is_none_or(|e| e != "rs") {
                    continue;
                }
                // Whole test files build VFS paths for fixtures, never for
                // output (inline test modules are skipped below).
                if path.file_name().is_some_and(|n| n == "tests.rs") {
                    continue;
                }
                let src = std::fs::read_to_string(&path).expect("read source");
                // Skip inline `#[cfg(test)] mod ... { ... }` blocks for the
                // same reason. A `#[cfg(test)] mod tests;` declaration is not a
                // block, and the file it names is skipped by name above.
                let mut in_test_mod = false;
                let mut prev_attr = false;
                for (i, line) in src.lines().enumerate() {
                    if in_test_mod {
                        in_test_mod = line != "}";
                        continue;
                    }
                    if prev_attr && line.starts_with("mod ") && line.ends_with('{') {
                        in_test_mod = true;
                        prev_attr = false;
                        continue;
                    }
                    prev_attr = line == "#[cfg(test)]";
                    if line.contains("// host-join-ok:") {
                        continue;
                    }
                    if shapes.iter().any(|shape| line.contains(shape)) {
                        let rel = path.strip_prefix(root).unwrap_or(&path);
                        violations.push(format!("{}:{}: {}", rel.display(), i + 1, line.trim()));
                    }
                }
            }
        }

        for crate_dir in std::fs::read_dir(workspace).expect("read crates dir") {
            let src = crate_dir.expect("crate entry").path().join("src");
            if src.is_dir() {
                walk(&src, workspace, &shapes, &mut violations);
            }
        }

        assert!(
            violations.is_empty(),
            "`Path::join` used to build a VFS path. On Windows it inserts the \
             host separator, so the path prints as `/d/proj\\src\\main.rs` \
             (issue #2425). Use `crate::fs::vfs_join` instead, or add \
             `// host-join-ok: <reason>` for a genuine host path.\n\nViolations:\n{}",
            violations.join("\n")
        );
    }

    /// TM-INF-024: clap `Arg::env(...)` reads defaults from the real
    /// process environment. uutils ships `.env("TABSIZE")` /
    /// `.env("TIME_STYLE")` on `ls`, but bashkit isolates scripts inside
    /// `ctx.env`; if the host parser were allowed to consult `std::env`
    /// the sandbox boundary would leak (host can probe presence, host can
    /// inject values that propagate into bashkit's option-validation
    /// path). Codegen strips `.env(...)` from generated Arg chains and
    /// re-emits the metadata as a `<UTIL>_ENV_DEFAULTS` table that the
    /// `clap_env::apply_env_defaults` shim feeds from `ctx.env`. This
    /// static guard makes sure no future regen (or hand-edit) re-adds
    /// a runtime `.env(...)` call. Defence-in-depth: the workspace
    /// `clap` dep also drops the `env` cargo feature, so a slipped
    /// `.env(...)` won't compile.
    #[test]
    fn no_clap_env_in_generated_parsers() {
        let pat = regex::Regex::new(r"\.env\s*\(").unwrap();
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/builtins/generated");
        let mut violations = Vec::new();
        for entry in std::fs::read_dir(&dir).expect("read generated dir") {
            let entry = entry.unwrap();
            let path = entry.path();
            if path.extension().and_then(|s| s.to_str()) != Some("rs") {
                continue;
            }
            let src = std::fs::read_to_string(&path).expect("read generated file");
            for (i, line) in src.lines().enumerate() {
                // Skip doc/line comments — they reference `.env(...)`
                // when describing the harvest rule. We only care about
                // real call expressions.
                if line.trim_start().starts_with("//") {
                    continue;
                }
                if pat.is_match(line) {
                    let rel = path
                        .strip_prefix(std::path::Path::new(env!("CARGO_MANIFEST_DIR")))
                        .unwrap_or(&path);
                    violations.push(format!("{}:{}: {}", rel.display(), i + 1, line.trim_end()));
                }
            }
        }
        assert!(
            violations.is_empty(),
            "clap `Arg::env(...)` found in a generated parser. This pulls \
             defaults from the host process environment and breaks bashkit's \
             sandbox boundary (TM-INF-024). Re-run `just regen-coreutils-args` \
             — the codegen harvests these into `<UTIL>_ENV_DEFAULTS` instead — \
             or remove the call by hand.\n\n{}",
            violations.join("\n")
        );
    }

    /// TM-INF-024, module-mode half.
    ///
    /// `no_clap_env_in_generated_parsers` covers the args-mode hole
    /// (clap reading defaults from the host process). Vendored uucore
    /// *module* bodies have the same hole one level down: they can call
    /// `std::env::var*` directly. Such a body has no `ctx`, so it cannot
    /// consult bashkit's virtual env — the call would read the host
    /// process environment and let an embedder's environment change what
    /// a sandboxed script does. Upstream added exactly this in
    /// `format/argument.rs` (a `POSIXLY_CORRECT` probe gating a printf
    /// warning); `bashkit-coreutils-port` now folds allow-listed reads to
    /// "unset" and aborts on the rest.
    ///
    /// This scan is recursive (unlike the args-mode one, which only reads
    /// the top level) because vendored modules land in subdirectories.
    #[test]
    fn no_host_env_reads_in_generated_code() {
        let pat = regex::Regex::new(r"env\s*::\s*(var|vars|args)(_os)?\s*\(").unwrap();
        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/builtins/generated");
        let mut violations = Vec::new();

        fn walk(dir: &std::path::Path, out: &mut Vec<String>, pat: &regex::Regex) {
            for entry in std::fs::read_dir(dir).expect("read generated dir") {
                let path = entry.unwrap().path();
                if path.is_dir() {
                    walk(&path, out, pat);
                    continue;
                }
                if path.extension().and_then(|s| s.to_str()) != Some("rs") {
                    continue;
                }
                let src = std::fs::read_to_string(&path).expect("read generated file");
                for (i, line) in src.lines().enumerate() {
                    // Doc comments describe the rule; only real calls count.
                    if line.trim_start().starts_with("//") {
                        continue;
                    }
                    if pat.is_match(line) {
                        let rel = path
                            .strip_prefix(std::path::Path::new(env!("CARGO_MANIFEST_DIR")))
                            .unwrap_or(&path);
                        out.push(format!("{}:{}: {}", rel.display(), i + 1, line.trim_end()));
                    }
                }
            }
        }
        walk(&root, &mut violations, &pat);

        assert!(
            violations.is_empty(),
            "Host-process environment read found in generated code. A vendored \
             body has no `ctx`, so this reads the *host* environment and breaks \
             bashkit's sandbox boundary (TM-INF-024). Re-run the port — it folds \
             names listed in `vendored.toml`'s `host_env` to \"unset\" and \
             rejects the rest.\n\nViolations:\n{}",
            violations.join("\n")
        );
    }

    /// Every `<util>_args.rs` MUST expose a `<UTIL>_ENV_DEFAULTS` static.
    /// The codegen always emits one (possibly empty) so the bashkit-side
    /// surface is uniform — every clap-based builtin can wire through
    /// `apply_env_defaults` without per-util conditional code. Catches
    /// the regression where a regen drops the table because the codegen
    /// branch that emits it was removed or skipped.
    #[test]
    fn every_generated_parser_emits_env_defaults_table() {
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/builtins/generated");
        let mut missing = Vec::new();
        for entry in std::fs::read_dir(&dir).expect("read generated dir") {
            let entry = entry.unwrap();
            let path = entry.path();
            let name = path.file_name().and_then(|s| s.to_str()).unwrap_or("");
            if !name.ends_with("_args.rs") {
                continue;
            }
            // util name is everything before `_args.rs`
            let util = name.trim_end_matches("_args.rs");
            let const_name = format!("{}_ENV_DEFAULTS", util.to_uppercase());
            let needle = format!("pub static {const_name}");
            let src = std::fs::read_to_string(&path).expect("read generated file");
            if !src.contains(&needle) {
                let rel = path
                    .strip_prefix(std::path::Path::new(env!("CARGO_MANIFEST_DIR")))
                    .unwrap_or(&path);
                missing.push(format!("{}: missing `{needle}: ...`", rel.display()));
            }
        }
        assert!(
            missing.is_empty(),
            "Generated parser is missing its `<UTIL>_ENV_DEFAULTS` sidecar. \
             The codegen always emits this (possibly empty) so the bashkit \
             builtin can route argv through `apply_env_defaults` without \
             per-util conditionals. Re-run `just regen-coreutils-args` to \
             regenerate.\n\n{}",
            missing.join("\n")
        );
    }

    /// Pin LS's env-default surface explicitly. uutils' upstream `ls`
    /// uses `.env("TABSIZE")` and `.env("TIME_STYLE")` as of the pinned
    /// rev — both must appear in `LS_ENV_DEFAULTS`, with matching long
    /// flags, or the virtual-env shim silently drops them. Updating
    /// uutils may legitimately add or remove rows; bump this list in
    /// the same PR as the codegen regen.
    #[test]
    fn ls_env_defaults_surface_matches_uutils() {
        use crate::builtins::generated::ls_args::LS_ENV_DEFAULTS;
        let mut got: Vec<(&'static str, &'static str)> = LS_ENV_DEFAULTS
            .iter()
            .map(|d| (d.env_var, d.long))
            .collect();
        got.sort();
        let mut expected = vec![("TABSIZE", "tabsize"), ("TIME_STYLE", "time-style")];
        expected.sort();
        assert_eq!(
            got, expected,
            "LS_ENV_DEFAULTS surface drifted from upstream uutils. Either \
             the codegen harvest dropped a row, or uutils added/removed an \
             `.env(...)` annotation on `ls` — bump this fixture together \
             with the regen."
        );
    }

    /// Every `<util>_args.rs` header MUST reference the same uutils
    /// revision as `generated::UUTILS_REVISION`. The drift workflow
    /// bumps both atomically; this test catches the case where someone
    /// regenerates a single util at a different rev and forgets to
    /// update the pin (or vice versa).
    #[test]
    fn generated_args_headers_match_pinned_uutils_revision() {
        let pin = generated::UUTILS_REVISION;
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/builtins/generated");

        let mut mismatches = Vec::new();
        for entry in std::fs::read_dir(&dir).expect("read generated dir") {
            let entry = entry.unwrap();
            let path = entry.path();
            if path.extension().and_then(|s| s.to_str()) != Some("rs") {
                continue;
            }
            let name = path.file_name().and_then(|s| s.to_str()).unwrap_or("");
            // Only `*_args.rs` carry per-util headers; `mod.rs` holds
            // the pin itself.
            if !name.ends_with("_args.rs") {
                continue;
            }
            let body = std::fs::read_to_string(&path).expect("read generated file");
            let header_rev = body
                .lines()
                .find_map(|l| {
                    l.strip_prefix("// Source: uutils/coreutils@")
                        .and_then(|rest| rest.split_whitespace().next())
                })
                .unwrap_or("");
            if header_rev != pin {
                mismatches.push(format!(
                    "{}: header references uutils@{header_rev}, pin is uutils@{pin}",
                    path.display()
                ));
            }
        }
        assert!(
            mismatches.is_empty(),
            "Generated argument files drift from `generated::UUTILS_REVISION` \
             (`{pin}`). Regenerate every util at the pinned rev or bump the \
             pin to match. The drift workflow does both atomically; manual \
             bumps must too.\n\n{}",
            mismatches.join("\n")
        );
    }

    /// Coarse sweep: every common flag-accepting builtin called with a
    /// bogus flag must produce a clean error. Tools without flag parsing
    /// (`true`, `false`, `:`) and tools that take a path/filter as their
    /// first arg (`cd`, `source`) are excluded.
    #[tokio::test]
    async fn every_builtin_handles_bogus_flag_cleanly() {
        const TOOLS: &[&str] = &[
            "cat",
            "ls",
            "wc",
            "head",
            "tail",
            "sort",
            "uniq",
            "cut",
            "tr",
            "grep",
            "sed",
            "awk",
            "find",
            "tree",
            "diff",
            "comm",
            "paste",
            "column",
            "join",
            "split",
            "fmt",
            "fold",
            "expand",
            "unexpand",
            "nl",
            "tac",
            "truncate",
            "shuf",
            "rev",
            "strings",
            "od",
            "xxd",
            "hexdump",
            "base64",
            "md5sum",
            "sha1sum",
            "sha256sum",
            "sha224sum",
            "sha384sum",
            "sha512sum",
            "b2sum",
            "cksum",
            "base32",
            "basenc",
            "cmp",
            "nproc",
            "tsort",
            "factor",
            "install",
            "locale",
            "tar",
            "gzip",
            "gunzip",
            "bzip2",
            "bunzip2",
            "bzcat",
            "zip",
            "unzip",
            "seq",
            "expr",
            "bc",
            "numfmt",
            "test",
            "pr",
            "printf",
            "echo",
            "env",
            "printenv",
            "stat",
            "file",
            "basename",
            "dirname",
            "realpath",
            "readlink",
            "mktemp",
            "tee",
            "csv",
            "json",
            "yq",
            "tomlq",
            "jq",
            "semver",
            "envsubst",
            "template",
            "patch",
        ];
        for tool in TOOLS {
            let r =
                super::debug_leak_check::run(&format!("{tool} --xyzzy-not-a-real-flag </dev/null"))
                    .await;
            super::debug_leak_check::assert_no_leak(&r, &format!("{tool}_bogus_flag"), &[]);
        }
    }
}

#[cfg(test)]
mod clap_output_tests {
    use super::{ClapBuiltin, strip_ansi};

    #[test]
    fn strip_ansi_passes_plain_text_through() {
        assert_eq!(strip_ansi("error: no such flag\n"), "error: no such flag\n");
        assert_eq!(strip_ansi(""), "");
    }

    #[test]
    fn strip_ansi_removes_sgr_sequences() {
        // What clap's styling emits: bold/red around the "error:" label.
        let styled = "\u{1b}[1m\u{1b}[31merror:\u{1b}[0m bad flag\n";
        assert_eq!(strip_ansi(styled), "error: bad flag\n");
    }

    #[test]
    fn strip_ansi_removes_multi_param_csi_and_keeps_text() {
        let styled = "\u{1b}[38;5;9mred\u{1b}[0m and \u{1b}[1;4mbold\u{1b}[0m";
        assert_eq!(strip_ansi(styled), "red and bold");
    }

    #[test]
    fn strip_ansi_drops_non_csi_and_dangling_escapes() {
        // Two-byte escape (ESC + selector) and a trailing lone ESC.
        assert_eq!(strip_ansi("a\u{1b}(Bb"), "ab");
        assert_eq!(strip_ansi("tail\u{1b}"), "tail");
    }

    #[test]
    fn clap_builtin_output_carries_no_escapes() {
        use crate::clap::Parser;
        use crate::{Bash, BashkitContext};
        use async_trait::async_trait;

        #[derive(Parser)]
        #[command(name = "demo", about = "Demo")]
        struct Args {
            #[arg(long)]
            name: String,
        }

        struct Demo;

        #[async_trait]
        impl ClapBuiltin for Demo {
            type Args = Args;
            async fn execute_clap(
                &self,
                args: Self::Args,
                ctx: &mut BashkitContext<'_>,
            ) -> crate::Result<()> {
                ctx.write_stdout(format!("{}\n", args.name));
                Ok(())
            }
        }

        tokio_test::block_on(async {
            let mut bash = Bash::builder().builtin("demo", Box::new(Demo)).build();

            // Parse error, missing required arg, and help all render through
            // clap and must reach the caller without escape sequences.
            for script in ["demo --bogus", "demo", "demo --help"] {
                let result = bash.exec(script).await.expect("exec");
                assert!(
                    !result.stdout.contains('\u{1b}') && !result.stderr.contains('\u{1b}'),
                    "escape sequence in output of `{script}`"
                );
            }
        });
    }
}