bashkit 0.17.0__tar.gz → 0.17.1__tar.gz

{bashkit-0.17.0 → bashkit-0.17.1}/Cargo.lock

@@ -342,7 +342,7 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
 [[package]]
 name = "bashkit"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -402,7 +402,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-bench"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -417,7 +417,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-capi"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "bashkit",
  "serde",
@@ -427,7 +427,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-cli"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -441,7 +441,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-coreutils-port"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "anyhow",
  "prettyplease",
@@ -455,7 +455,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-eval"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -472,7 +472,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-js"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "bashkit",
  "napi",
@@ -484,7 +484,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-python"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "bashkit",
  "num-bigint",
@@ -496,7 +496,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-wasm"
-version = "0.17.0"
+version = "0.17.1"
 dependencies = [
  "bashkit",
  "console_error_panic_hook",

{bashkit-0.17.0 → bashkit-0.17.1}/Cargo.toml

@@ -7,7 +7,7 @@ resolver = "2"
 members = ["crates/*"]
 
 [workspace.package]
-version = "0.17.0"
+version = "0.17.1"
 edition = "2024"
 license = "MIT"
 authors = ["Mykhailo Chalyi <mike@chaliy.name>", "Everruns"]

{bashkit-0.17.0 → bashkit-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bashkit
-Version: 0.17.0
+Version: 0.17.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{bashkit-0.17.0 → bashkit-0.17.1}/crates/bashkit/Cargo.toml

@@ -264,6 +264,10 @@ harness = false
 name = "hotpath"
 harness = false
 
+[[bench]]
+name = "builtin_args"
+harness = false
+
 [[bench]]
 name = "file_ops"
 harness = false

{bashkit-0.17.0 → bashkit-0.17.1}/crates/bashkit/README.md

@@ -431,7 +431,7 @@ Enable the `sqlite` feature to embed [Turso](https://github.com/tursodatabase/tu
 
 ```toml
 [dependencies]
-bashkit = { version = "0.17.0", features = ["sqlite"] }
+bashkit = { version = "0.17.1", features = ["sqlite"] }
 ```
 
 ```rust

bashkit-0.17.1/crates/bashkit/benches/builtin_args.rs

@@ -0,0 +1,178 @@
+//! Per-invocation argument-parsing cost for builtins.
+//!
+//! Motivation: every ported coreutils builtin rebuilds its whole `clap::Command`
+//! on each invocation (`cat_command()` in `builtins/generated/cat_args.rs` is
+//! called from `builtins/cat.rs` per exec, and the same holds for `ls`, `od`,
+//! `stat`, …). Real scripts call these in loops, so the arg tree is constructed
+//! N times for N invocations. This bench exists to answer one question: is that
+//! construction cost visible next to the interpreter and the builtin body, or
+//! is it noise?
+//!
+//! Decision: measured end-to-end through the public `Bash::exec` API, not
+//! against `cat_command()` directly. `mod builtins` is private in `lib.rs`, and
+//! widening the public surface for a bench is worse than reading the cost as a
+//! difference between comparable scripts. The numbers are therefore read as
+//! deltas, not absolutes:
+//!
+//!   - `clap_vs_handrolled`: `cat` / `ls` (clap-parsed) against `echo` /
+//!     `printf` (hand-parsed) and `:` (no args at all). The `:` row is the
+//!     loop-and-dispatch floor; everything above it is arg handling plus body.
+//!   - `arg_surface_size`: `cat` (12 args) against `ls` (~60 args) on inputs
+//!     sized so the bodies do near-identical work. clap's per-parse cost scales
+//!     with the number of declared args while the body does not, so this delta
+//!     tracks arg-surface cost.
+//!   - `flag_count`: same builtin, more flags on the command line. Costs ~0.45
+//!     µs per extra flag — note this measures only the *matching* of additional
+//!     argv entries, NOT the fixed per-parse cost, which dominates (see below).
+//!
+//! Each bench runs `INVOCATIONS` calls inside one script and declares
+//! `Throughput::Elements(INVOCATIONS)`, so criterion reports per-invocation
+//! time directly and the one-time `Bash::new()` cost amortizes away.
+//!
+//! What this measured, and what came of it: clap costs ~10 µs per `cat`
+//! invocation and ~73% of an `ls` invocation. The expensive part is *parsing*,
+//! not constructing the `Command` (construction is ~1.1 µs of `cat`'s 7.3 µs
+//! round trip) — but most of that parse cost is clap's one-time `_build_self`,
+//! which `builtins::clap_cache` now hoists into a cached pre-built `Command`.
+//! Worth −15% on `ls` end-to-end, −2% on `cat`. Keep this bench as the guard:
+//! a regression here means the cache stopped being hit.
+//!
+//! Run with: `cargo bench --bench builtin_args`
+//! Save baseline: `cargo bench --bench builtin_args -- --save-baseline before`
+//! Compare:      `cargo bench --bench builtin_args -- --baseline before`
+//!
+//! First-run results belong in `crates/bashkit/benches/results/` as
+//! `criterion-builtin_args-<moniker>-<timestamp>.md` (see AGENTS.md → Benches).
+
+use bashkit::{Bash, FileSystem, InMemoryFs};
+use criterion::{Criterion, Throughput, criterion_group, criterion_main};
+use std::path::Path;
+use std::sync::Arc;
+use tokio::runtime::Runtime;
+
+/// Invocations per iteration. Large enough that `Bash::new()` and parse of the
+/// surrounding loop amortize out, small enough that a 100-sample criterion run
+/// stays under a minute per bench.
+const INVOCATIONS: u64 = 500;
+
+/// Seed a VFS with one tiny file in a single-entry directory.
+///
+/// Both are deliberately minimal: a 4-byte file so `cat`'s body is one small
+/// read, and a directory holding exactly that file so `ls`'s body is one small
+/// readdir. Keeping the bodies trivial is what makes the `cat` vs `ls` delta
+/// readable as arg-surface cost rather than as I/O.
+fn seed(rt: &Runtime) -> Arc<InMemoryFs> {
+    let fs = Arc::new(InMemoryFs::new());
+    rt.block_on(async {
+        let fs_dyn: Arc<dyn FileSystem> = fs.clone();
+        fs_dyn.mkdir(Path::new("/d"), true).await.expect("mkdir /d");
+        fs_dyn
+            .write_file(Path::new("/d/f"), b"abc\n")
+            .await
+            .expect("write /d/f");
+    });
+    fs
+}
+
+/// Wrap `body` in a loop of `INVOCATIONS` iterations.
+///
+/// `for ((...))` rather than `for x in $(seq ...)`: the C-style loop keeps the
+/// measured work to the builtin under test, with no command substitution and no
+/// `seq` invocation in the middle of the thing we are timing.
+fn loop_script(body: &str) -> String {
+    format!("for ((i=0; i<{INVOCATIONS}; i++)); do {body}; done")
+}
+
+fn run(rt: &Runtime, fs: &Arc<InMemoryFs>, script: &str) {
+    rt.block_on(async {
+        let mut bash = Bash::builder().fs(fs.clone()).build();
+        let result = bash.exec(script).await.expect("exec failed");
+        std::hint::black_box(result);
+    });
+}
+
+/// Register one `INVOCATIONS`-sized loop bench in `g`.
+fn bench_loop(
+    g: &mut criterion::BenchmarkGroup<'_, criterion::measurement::WallTime>,
+    rt: &Runtime,
+    fs: &Arc<InMemoryFs>,
+    name: &str,
+    body: &str,
+) {
+    let script = loop_script(body);
+    g.bench_function(name, |b| b.iter(|| run(rt, fs, &script)));
+}
+
+/// clap-parsed builtins against hand-parsed ones and against the empty floor.
+fn bench_clap_vs_handrolled(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let fs = seed(&rt);
+    let mut g = c.benchmark_group("builtin_args/clap_vs_handrolled");
+    g.throughput(Throughput::Elements(INVOCATIONS));
+
+    // Floor: loop + dispatch only, no arguments, no body.
+    bench_loop(&mut g, &rt, &fs, "colon_noop", ":");
+    // Hand-parsed builtins, one argument each.
+    bench_loop(&mut g, &rt, &fs, "echo_handrolled", "echo x > /dev/null");
+    bench_loop(
+        &mut g,
+        &rt,
+        &fs,
+        "printf_handrolled",
+        "printf x > /dev/null",
+    );
+    // clap-parsed builtins, one argument each.
+    bench_loop(&mut g, &rt, &fs, "cat_clap", "cat /d/f > /dev/null");
+    bench_loop(&mut g, &rt, &fs, "ls_clap", "ls /d > /dev/null");
+
+    g.finish();
+}
+
+/// Small vs large clap arg surface, bodies held near-constant.
+///
+/// `cat` declares ~12 args, `ls` ~60. If `Command` construction dominates, this
+/// gap tracks the arg count; if it does not, the two rows land close together
+/// and caching the built `Command` is not worth doing.
+fn bench_arg_surface_size(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let fs = seed(&rt);
+    let mut g = c.benchmark_group("builtin_args/arg_surface_size");
+    g.throughput(Throughput::Elements(INVOCATIONS));
+
+    bench_loop(&mut g, &rt, &fs, "cat_12_args", "cat /d/f > /dev/null");
+    bench_loop(&mut g, &rt, &fs, "ls_60_args", "ls /d > /dev/null");
+
+    g.finish();
+}
+
+/// Same builtin, growing flag count on the command line.
+///
+/// Construction cost is identical across these rows, so any spread is match /
+/// value-parse cost. Splitting the two matters for the fix: caching a built
+/// `Command` helps only the construction half.
+fn bench_flag_count(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let fs = seed(&rt);
+    let mut g = c.benchmark_group("builtin_args/flag_count");
+    g.throughput(Throughput::Elements(INVOCATIONS));
+
+    bench_loop(&mut g, &rt, &fs, "cat_0_flags", "cat /d/f > /dev/null");
+    bench_loop(&mut g, &rt, &fs, "cat_1_flag", "cat -n /d/f > /dev/null");
+    bench_loop(
+        &mut g,
+        &rt,
+        &fs,
+        "cat_3_flags",
+        "cat -n -E -T /d/f > /dev/null",
+    );
+
+    g.finish();
+}
+
+criterion_group!(
+    benches,
+    bench_clap_vs_handrolled,
+    bench_arg_surface_size,
+    bench_flag_count
+);
+criterion_main!(benches);

bashkit-0.17.1/crates/bashkit/benches/results/criterion-builtin_args-baseline-linux-x86_64-1787421390.md

@@ -0,0 +1,93 @@
+# builtin_args — first run (baseline)
+
+`cargo bench --bench builtin_args -- --warm-up-time 1 --measurement-time 3`
+
+Host: 4× Intel Xeon @ 2.10 GHz, linux-x86_64, cloud runner (noisy; treat
+absolutes as indicative, deltas as the signal).
+Bashkit: v0.17.0, `4b634fd`.
+
+Question this run answers: ported coreutils builtins rebuild their whole
+`clap::Command` on every invocation. Is that visible?
+
+## Raw
+
+500 invocations per iteration; per-invocation column is `time ÷ 500`.
+
+| bench | time / 500 inv | per invocation | vs `:` floor |
+|---|---|---|---|
+| `clap_vs_handrolled/colon_noop` | 1.658 ms | 3.32 µs | — |
+| `clap_vs_handrolled/echo_handrolled` | 2.002 ms | 4.00 µs | +0.69 µs |
+| `clap_vs_handrolled/printf_handrolled` | 2.049 ms | 4.10 µs | +0.78 µs |
+| `clap_vs_handrolled/cat_clap` | 7.006 ms | 14.01 µs | +10.70 µs |
+| `clap_vs_handrolled/ls_clap` | 30.408 ms | 60.82 µs | +57.50 µs |
+| `arg_surface_size/cat_12_args` | 7.017 ms | 14.03 µs | +10.71 µs |
+| `arg_surface_size/ls_60_args` | 29.497 ms | 58.99 µs | +55.68 µs |
+| `flag_count/cat_0_flags` | 7.263 ms | 14.53 µs | — |
+| `flag_count/cat_1_flag` | 7.484 ms | 14.97 µs | +0.44 µs / flag |
+| `flag_count/cat_3_flags` | 7.952 ms | 15.90 µs | +0.46 µs / flag |
+
+## Reading
+
+1. **clap is the dominant per-invocation cost.** `cat` on a 4-byte file costs
+   14.0 µs against 4.0 µs for `echo` — a builtin whose body does comparable
+   work minus the file read. Roughly 10 µs per invocation is arg handling. For
+   `ls` the clap share is ~73% of a 60.8 µs invocation.
+2. **Cost scales with arg-surface size.** `ls` (~60 args) costs 59–61 µs
+   against `cat`'s 14 µs. `ls`'s body does more than `cat`'s (readdir, stat,
+   column layout), so this row is not a clean isolation, but it is the largest
+   number on the board.
+3. **The `flag_count` rows do NOT isolate construction cost.** Adding flags to
+   the argv costs ~0.45 µs each, which initially read as "construction
+   dominates, matching is cheap". A follow-up standalone clap harness showed
+   that inference is wrong — see below.
+
+## Correction: where the time actually goes
+
+Measured directly against `cat_command()` outside bashkit (200k iterations):
+
+| step | `cat` |
+|---|---|
+| construct `Command` only | 1.09 µs |
+| `Command::clone()` only | 0.83 µs |
+| construct + `try_get_matches_from` | 7.69 µs |
+| parse alone (clone + parse − clone) | 6.27 µs |
+
+**Parsing dominates, not construction** — 6.3 µs of the 7.7 µs round trip.
+Caching to skip construction alone is worth ~1 µs of `cat`'s 14 µs, and
+`Command::clone()` is not even cheaper than rebuilding (0.83 vs 1.09 µs, inside
+noise end-to-end; a naive `LazyLock` + clone prototype measured as a 2.7%
+*regression*).
+
+The cacheable part is inside the parse: clap finalizes a `Command`
+(`_build_self` — resolves groups, propagates settings, indexes args) on first
+parse and skips it when the `Built` flag is set. Calling `Command::build()`
+once and cloning the finalized value carries that flag:
+
+| | `cat` (12 args) | `ls` (~60 args) |
+|---|---|---|
+| fresh build + parse | 7.34 µs | 44.65 µs |
+| cached *unbuilt* + parse | 7.02 µs (−4.3%) | 37.80 µs (−15.3%) |
+| cached *built* + parse | 6.50 µs (−11.4%) | 35.53 µs (−20.4%) |
+
+## Outcome
+
+Implemented as `builtins::clap_cache::cached_command!` across all 11 ported
+builtins. End-to-end re-run on this host (`--save-baseline cached`):
+
+| bench | before | after | change |
+|---|---|---|---|
+| `clap_vs_handrolled/cat_clap` | 7.006 ms | 6.862 ms | −2.1% |
+| `clap_vs_handrolled/ls_clap` | 30.408 ms | 25.852 ms | **−15.0%** |
+| `arg_surface_size/cat_12_args` | 7.017 ms | 6.717 ms | −4.3% |
+| `arg_surface_size/ls_60_args` | 29.497 ms | 26.728 ms | −9.4% |
+| `flag_count/cat_0_flags` | 7.263 ms | 6.553 ms | −9.8% |
+
+`ls` drops from 60.8 to 51.7 µs per invocation. The win tracks arg-surface
+size, so the large ports gain most and `cat` gains little.
+
+## Context
+
+Run in response to the usage-rs question (jdx/usage). Conclusion on adoption was
+no — our clap definitions are codegen output from uutils' `uu_app()`, not
+hand-maintained CLI boilerplate — but the perf claim behind it pointed at a real
+cost, which this bench now quantifies and guards.

{bashkit-0.17.0 → bashkit-0.17.1}/crates/bashkit/docs/logging.md

@@ -14,7 +14,7 @@ Add the `logging` feature to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-bashkit = { version = "0.17.0", features = ["logging"] }
+bashkit = { version = "0.17.1", features = ["logging"] }
 tracing-subscriber = "0.3"  # or your preferred subscriber
 ```
 

{bashkit-0.17.0 → bashkit-0.17.1}/crates/bashkit/docs/sqlite.md

@@ -13,7 +13,7 @@ the `sqlite` feature. The engine is [Turso](https://github.com/tursodatabase/tur
 
 ```toml
 # Cargo.toml
-bashkit = { version = "0.17.0", features = ["sqlite"] }
+bashkit = { version = "0.17.1", features = ["sqlite"] }
 ```
 
 ```rust,ignore

{bashkit-0.17.0 → bashkit-0.17.1}/crates/bashkit/src/builtins/cat.rs

@@ -5,17 +5,21 @@
 //! `crates/bashkit-coreutils-port/`. Behaviour is implemented locally
 //! against the bashkit VFS.
 
+use super::clap_cache::cached_command;
 use async_trait::async_trait;
 use std::ffi::OsString;
 use std::path::Path;
 
-use super::generated::cat_args::cat_command;
 use super::{Builtin, Context};
 use crate::error::Result;
 use crate::interpreter::ExecResult;
 
 pub struct Cat;
 
+// Cached `cat` arg surface: pre-built once, cloned per invocation.
+// See `builtins::clap_cache` for why it is built, not just constructed.
+cached_command!(cat_cmd, super::generated::cat_args::cat_command());
+
 #[async_trait]
 impl Builtin for Cat {
     async fn execute(&self, ctx: Context<'_>) -> Result<ExecResult> {
@@ -24,12 +28,7 @@ impl Builtin for Cat {
             .chain(ctx.args.iter().map(OsString::from))
             .collect();
 
-        // GNU coreutils' help layout opens with the usage line; clap's
-        // default template leads with the `about`. uutils handles this via
-        // uucore's `localized_help_template`, which we drop during codegen
-        // because it pulls in Fluent. Re-apply a GNU-equivalent template.
-        let cmd = cat_command().help_template("Usage: {usage}\n{about}\n\n{all-args}\n");
-        let matches = match cmd.try_get_matches_from(argv) {
+        let matches = match cat_cmd().try_get_matches_from(argv) {
             Ok(m) => m,
             Err(e) => {
                 let kind = e.kind();

bashkit-0.17.1/crates/bashkit/src/builtins/clap_cache.rs

@@ -0,0 +1,131 @@
+//! Cached `clap::Command` construction for the coreutils-ported builtins.
+//!
+//! # Decision: cache a *built* `Command`, clone per invocation
+//!
+//! Every ported builtin used to call `<util>_command()` (generated from
+//! uutils' `uu_app()`) on each invocation, so a script running `cat` in a
+//! loop reconstructed the whole arg tree N times. Measured on a 4-core Xeon
+//! (`cargo bench --bench builtin_args`, plus a standalone clap micro-harness),
+//! per invocation:
+//!
+//! | | `cat` (12 args) | `ls` (~60 args) |
+//! |---|---|---|
+//! | construct `Command` only | 1.1 µs | — |
+//! | construct + `try_get_matches_from` | 7.3 µs | 44.7 µs |
+//! | clone cached *unbuilt* + parse | 7.0 µs | 37.8 µs |
+//! | clone cached *built* + parse | 6.5 µs | 35.5 µs |
+//!
+//! Two things follow, and both shaped this module:
+//!
+//! 1. **Construction is not the expensive half — parsing is.** Building `cat`'s
+//!    tree costs 1.1 µs of the 7.3 µs round trip. Caching to avoid construction
+//!    alone is worth ~4%, which is why this is not a plain `LazyLock<Command>`
+//!    holding the output of `<util>_command()`.
+//! 2. **Most of the parse cost is `_build_self`, and it is cacheable.** clap
+//!    finalizes a `Command` (resolves groups, propagates settings, indexes
+//!    args) on first parse, and skips that work when the `Built` flag is
+//!    already set. Calling [`clap::Command::build`] once and cloning the
+//!    finalized value carries the flag along, so each invocation pays only
+//!    matching: −11% for `cat`, −20% for `ls`.
+//!
+//! The win scales with arg-surface size, so the large ports (`ls`, `stat`,
+//! `od`) benefit most. `Command::clone` is *not* cheaper than
+//! `<util>_command()` on its own (0.83 µs vs 1.1 µs, and the difference is
+//! inside noise end-to-end) — the skipped `_build_self` is the entire point.
+//!
+//! `help_template` must be applied before `build()`, which is why the macro
+//! owns both steps rather than leaving the template to callers.
+
+/// GNU coreutils' help layout opens with the usage line; clap's default
+/// template leads with the `about`. uutils handles this via uucore's
+/// `localized_help_template`, which codegen drops because it pulls in Fluent
+/// (see `knowledge/runtimes/coreutils-args-port.md`). Re-applied here so every
+/// ported builtin renders GNU-equivalent help from one definition.
+pub const GNU_HELP_TEMPLATE: &str = "Usage: {usage}\n{about}\n\n{all-args}\n";
+
+/// Define a cached accessor for a generated `clap::Command`.
+///
+/// Expands to `fn $name() -> clap::Command` returning a clone of a
+/// process-lifetime `Command` that has already had [`GNU_HELP_TEMPLATE`]
+/// applied and [`clap::Command::build`] called on it.
+///
+/// ```ignore
+/// cached_command!(cat_cmd, super::generated::cat_args::cat_command());
+/// let matches = cat_cmd().try_get_matches_from(argv)?;
+/// ```
+macro_rules! cached_command {
+    ($(#[$attr:meta])* $name:ident, $builder:expr) => {
+        $(#[$attr])*
+        fn $name() -> clap::Command {
+            static CACHE: std::sync::LazyLock<clap::Command> = std::sync::LazyLock::new(|| {
+                let mut cmd = $builder.help_template($crate::builtins::clap_cache::GNU_HELP_TEMPLATE);
+                // Finalize once. Clones inherit the `Built` flag, so
+                // `try_get_matches_from` skips `_build_self` per invocation.
+                cmd.build();
+                cmd
+            });
+            CACHE.clone()
+        }
+    };
+}
+
+pub(crate) use cached_command;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    cached_command!(cat_cmd, crate::builtins::generated::cat_args::cat_command());
+
+    /// A cached, pre-built command must parse identically to a freshly
+    /// constructed one. Guards the `build()`-then-`clone()` shortcut against
+    /// clap changing what `Built` implies.
+    #[test]
+    fn cached_command_parses_like_a_fresh_one() {
+        let argv = ["cat", "-n", "-E", "/d/f"];
+        let fresh = crate::builtins::generated::cat_args::cat_command()
+            .help_template(GNU_HELP_TEMPLATE)
+            .try_get_matches_from(argv)
+            .expect("fresh parse");
+        let cached = cat_cmd().try_get_matches_from(argv).expect("cached parse");
+
+        assert_eq!(fresh.get_flag("number"), cached.get_flag("number"));
+        assert_eq!(fresh.get_flag("show-ends"), cached.get_flag("show-ends"));
+        assert_eq!(fresh.get_flag("show-tabs"), cached.get_flag("show-tabs"));
+        let raw = |m: &clap::ArgMatches| {
+            m.get_raw("file")
+                .map(|v| v.map(|s| s.to_owned()).collect::<Vec<_>>())
+        };
+        assert_eq!(raw(&fresh), raw(&cached));
+    }
+
+    /// Repeated calls must not accumulate state — each clone parses from
+    /// scratch, and a parse error on one call must not poison the next.
+    #[test]
+    fn cached_command_is_reusable_across_calls() {
+        assert!(cat_cmd().try_get_matches_from(["cat", "--nope"]).is_err());
+        let ok = cat_cmd()
+            .try_get_matches_from(["cat", "-n", "/d/f"])
+            .expect("parse after an earlier error");
+        assert!(ok.get_flag("number"));
+        // Same argv twice yields the same result (no residue on the cache).
+        let again = cat_cmd()
+            .try_get_matches_from(["cat", "-n", "/d/f"])
+            .expect("second parse");
+        assert!(again.get_flag("number"));
+    }
+
+    /// Help rendering must survive the pre-`build()` template application —
+    /// the GNU layout leads with `Usage:`, clap's default does not.
+    #[test]
+    fn cached_command_renders_gnu_help_layout() {
+        let err = cat_cmd()
+            .try_get_matches_from(["cat", "--help"])
+            .expect_err("--help exits via Err");
+        let rendered = err.render().to_string();
+        assert!(
+            rendered.starts_with("Usage:"),
+            "help must open with the usage line, got: {rendered}"
+        );
+    }
+}

{bashkit-0.17.0 → bashkit-0.17.1}/crates/bashkit/src/builtins/fileops.rs

@@ -4,6 +4,7 @@
 // THREAT[TM-INF-018]: timezone-naive `touch -t` stamps are UTC; host-local
 // conversion would leak process timezone through a later `date -r`.
 
+use super::clap_cache::cached_command;
 use crate::time_compat::SystemTime;
 use async_trait::async_trait;
 use chrono::{DateTime, Datelike, NaiveDate, Utc};
@@ -1015,10 +1016,13 @@ fn mktemp_name(template: Option<&str>, suffix: &str) -> String {
     }
 }
 
+// Cached `mktemp` arg surface: pre-built once, cloned per invocation.
+// See `builtins::clap_cache` for why it is built, not just constructed.
+cached_command!(mktemp_cmd, super::generated::mktemp_args::mktemp_command());
+
 #[async_trait]
 impl Builtin for Mktemp {
     async fn execute(&self, ctx: Context<'_>) -> Result<ExecResult> {
-        use super::generated::mktemp_args::mktemp_command;
         use std::ffi::OsString;
         use std::path::PathBuf;
 
@@ -1026,8 +1030,7 @@ impl Builtin for Mktemp {
             .chain(ctx.args.iter().map(OsString::from))
             .collect();
 
-        let cmd = mktemp_command().help_template("Usage: {usage}\n{about}\n\n{all-args}\n");
-        let matches = match cmd.try_get_matches_from(argv) {
+        let matches = match mktemp_cmd().try_get_matches_from(argv) {
             Ok(m) => m,
             Err(e) => {
                 let kind = e.kind();
@@ -1134,7 +1137,6 @@ impl Builtin for Mktemp {
         Ok(ExecResult::err(msg, 1))
     }
 }
-
 #[cfg(test)]
 mod tests {
     use super::*;

{bashkit-0.17.0 → bashkit-0.17.1}/crates/bashkit/src/builtins/hextools.rs

@@ -1,5 +1,6 @@
 //! od, xxd, and hexdump builtins - byte-level inspection tools
 
+use super::clap_cache::cached_command;
 use async_trait::async_trait;
 
 use super::{Builtin, Context};
@@ -221,18 +222,20 @@ fn od_dump(data: &[u8], opts: &OdOptions) -> String {
     output
 }
 
+// Cached `od` arg surface: pre-built once, cloned per invocation.
+// See `builtins::clap_cache` for why it is built, not just constructed.
+cached_command!(od_cmd, super::generated::od_args::od_command());
+
 #[async_trait]
 impl Builtin for Od {
     async fn execute(&self, ctx: Context<'_>) -> Result<ExecResult> {
-        use super::generated::od_args::od_command;
         use std::ffi::OsString;
 
         let argv: Vec<OsString> = std::iter::once(OsString::from("od"))
             .chain(ctx.args.iter().map(OsString::from))
             .collect();
 
-        let cmd = od_command().help_template("Usage: {usage}\n{about}\n\n{all-args}\n");
-        let matches = match cmd.try_get_matches_from(argv) {
+        let matches = match od_cmd().try_get_matches_from(argv) {
             Ok(m) => m,
             Err(e) => {
                 let kind = e.kind();
@@ -662,7 +665,6 @@ async fn collect_input(
 
     Ok(data)
 }
-
 #[cfg(test)]
 mod tests {
     use super::*;