feat: add convenience cmd line option to set up xtrace

[reubeno]

This adds a command-line option --xtrace-file to brush that automates setting up set -x style tracing to an output file, including:

• Opening the file for writing (always truncating if existing)
• Injecting the file into the shell's file descriptor table
• Initializing BASH_XTRACEFD to the file descriptor (before any init/rc scripts run in the shell)

[github-actions]

Test Results

    3 files     29 suites   14m 17s ⏱️
1 587 tests 1 587 ✅ 0 💤 0 ❌
4 737 runs  4 737 ✅ 0 💤 0 ❌

Results for commit d40f98d.

[github-actions]

Public API changes for crate: brush-core

Added items

+pub brush_core::error::ErrorKind::TooManyOpenFiles
+pub fn brush_core::openfiles::OpenFiles::add(&mut self, file: brush_core::openfiles::OpenFile) -> core::result::Result<brush_core::ShellFd, brush_core::error::Error>
+pub brush_core::ErrorKind::TooManyOpenFiles

Public API changes for crate: brush-interactive

Added items

+pub brush_interactive::ShellError::FailedToCreateXtraceFile(std::path::PathBuf, std::io::error::Error)

Public API changes for crate: brush-shell

Added items

+pub brush_shell::args::CommandLineArgs::xtrace_file_path: core::option::Option<std::path::PathBuf>

Performance Benchmark Report

Benchmark name	Baseline (μs)	Test/PR (μs)	Delta (μs)	Delta %
clone_shell_object	16.71 μs	16.79 μs	0.08 μs	⚪ Unchanged
eval_arithmetic	0.15 μs	0.15 μs	-0.00 μs	⚪ Unchanged
expand_one_string	1.51 μs	1.52 μs	0.01 μs	⚪ Unchanged
for_loop	22.36 μs	22.38 μs	0.02 μs	⚪ Unchanged
function_call	2.21 μs	2.29 μs	0.07 μs	⚪ Unchanged
instantiate_shell	51.44 μs	51.38 μs	-0.06 μs	⚪ Unchanged
instantiate_shell_with_init_scripts	24841.47 μs	24632.03 μs	-209.44 μs	⚪ Unchanged
parse_bash_completion	1998.99 μs	2041.83 μs	42.84 μs	⚪ Unchanged
parse_sample_script	1.95 μs	2.02 μs	0.07 μs	🟠 +3.49%
run_echo_builtin_command	15.17 μs	15.46 μs	0.28 μs	⚪ Unchanged
tokenize_sample_script	3.38 μs	3.37 μs	-0.02 μs	⚪ Unchanged

Code Coverage Report: Only Changed Files listed

Package	Base Coverage	New Coverage	Difference
brush-core/src/openfiles.rs	🟠 61.06%	🟠 58.26%	🔴 -2.8%
brush-shell/src/entry.rs	🟢 87.5%	🟢 80.9%	🔴 -6.6%
Overall Coverage	🟢 75.22%	🟢 75.11%	🔴 -0.11%

Minimum allowed coverage is 70%, this run produced 75.11%

Test Summary: bash-completion test suite

Outcome	Count	Percentage
✅ Pass	1557	73.83
❗️ Error	19	0.90
❌ Fail	179	8.49
⏩ Skip	339	16.07
❎ Expected Fail	13	0.62
✔️ Unexpected Pass	2	0.09
📊 Total	2109	100.00

[Copilot]

Pull request overview

This PR adds a --xtrace-file command-line option that provides a convenient way to enable execution tracing (set -x) and redirect the trace output to a specified file. This automates three manual steps: opening a file for the trace output, assigning it to a file descriptor, and setting the BASH_XTRACEFD variable to point to that descriptor—all before any initialization or rc scripts execute.

Key changes:

• New command-line option --xtrace-file FILE that enables xtrace and directs output to the specified file
• New OpenFiles::add() method that automatically finds and assigns the next available file descriptor
• New error types for handling file creation failures and file descriptor exhaustion

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
brush-shell/src/args.rs	Adds --xtrace-file command-line argument definition under UI options
brush-shell/src/entry.rs	Implements enable_xtrace_to_file() function that opens the file, adds it to the FD table, and configures xtrace
brush-interactive/src/error.rs	Adds FailedToCreateXtraceFile error variant for file creation failures
brush-core/src/openfiles.rs	Implements add() method to automatically assign file descriptors, with constants for FD range limits (3-1024)
brush-core/src/error.rs	Adds TooManyOpenFiles error kind for when all file descriptors are exhausted