bashkit 0.4.0__tar.gz → 0.5.0__tar.gz

{bashkit-0.4.0 → bashkit-0.5.0}/Cargo.lock

@@ -345,7 +345,7 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
 [[package]]
 name = "bashkit"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -393,7 +393,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-bench"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -407,7 +407,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-cli"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -421,9 +421,20 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "bashkit-coreutils-port"
+version = "0.5.0"
+dependencies = [
+ "anyhow",
+ "prettyplease",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "bashkit-eval"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -440,7 +451,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-js"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "bashkit",
  "napi",
@@ -453,7 +464,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-python"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "bashkit",
  "num-bigint",

{bashkit-0.4.0 → bashkit-0.5.0}/Cargo.toml

@@ -7,7 +7,7 @@ resolver = "2"
 members = ["crates/*"]
 
 [workspace.package]
-version = "0.4.0"
+version = "0.5.0"
 edition = "2024"
 license = "MIT"
 authors = ["Everruns"]

{bashkit-0.4.0 → bashkit-0.5.0}/PKG-INFO

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

{bashkit-0.4.0 → bashkit-0.5.0}/crates/bashkit/Cargo.toml

@@ -77,8 +77,9 @@ hmac = "0.13"
 # Logging/tracing (optional)
 tracing = { workspace = true, optional = true }
 
-# CLI-style argument parsing for custom builtins.
-clap = { workspace = true, optional = true }
+# CLI-style argument parsing for custom builtins and ported coreutils
+# argument surfaces. Always on — see specs/coreutils-args-port.md.
+clap = { workspace = true }
 
 # Embedded Python interpreter (optional)
 monty = { git = "https://github.com/pydantic/monty", rev = "49faa4c", optional = true }
@@ -91,9 +92,7 @@ zapcode-core = { version = "1.5", optional = true }
 turso_core = { workspace = true, optional = true }
 
 [features]
-default = ["clap-builtins"]
-# Enable `ClapBuiltin` for custom builtins with `#[derive(clap::Parser)]`.
-clap-builtins = ["dep:clap"]
+default = []
 # Enable jq builtin via embedded jaq interpreter
 # Usage: cargo build --features jq
 jq = ["dep:jaq-core", "dep:jaq-std", "dep:jaq-json"]

bashkit-0.5.0/crates/bashkit/docs/clap-builtins.md

@@ -0,0 +1,138 @@
+# Clap Builtins
+
+`ClapBuiltin` lets Rust applications define custom Bashkit commands with
+`#[derive(clap::Parser)]` argument structs. Handlers receive a
+`BashkitContext` that captures stdout, stderr, and exit code for the virtual
+shell. `clap` is an unconditional dependency of `bashkit`, so this trait is
+always available.
+
+## Basic Usage
+
+```rust
+use bashkit::clap::Parser;
+use bashkit::{Bash, BashkitContext, ClapBuiltin, async_trait};
+
+#[derive(Parser)]
+#[command(name = "greet", about = "Print a greeting")]
+struct GreetArgs {
+    #[arg(short, long, default_value = "World")]
+    name: String,
+
+    #[arg(short, long)]
+    shout: bool,
+}
+
+struct Greet;
+
+#[async_trait]
+impl ClapBuiltin for Greet {
+    type Args = GreetArgs;
+
+    async fn execute_clap(
+        &self,
+        args: Self::Args,
+        ctx: &mut BashkitContext<'_>,
+    ) -> bashkit::Result<()> {
+        let greeting = format!("Hello, {}!", args.name);
+        let greeting = if args.shout {
+            greeting.to_uppercase()
+        } else {
+            greeting
+        };
+        ctx.write_stdout(format!("{greeting}\n"));
+        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 --shout").await?;
+    assert_eq!(result.stdout, "HELLO, ALICE!\n");
+
+    let help = bash.exec("greet --help").await?;
+    assert_eq!(help.exit_code, 0);
+    assert!(help.stdout.contains("Usage: greet"));
+    assert!(help.stderr.is_empty());
+
+    let error = bash.exec("greet --unknown").await?;
+    assert_eq!(error.exit_code, 2);
+    assert!(error.stderr.contains("unexpected argument"));
+    Ok(())
+}
+```
+
+## Subcommands
+
+Use normal clap subcommands for nested command surfaces.
+
+```rust
+use bashkit::clap::{Parser, Subcommand};
+use bashkit::{Bash, BashkitContext, ClapBuiltin, async_trait};
+
+#[derive(Parser)]
+#[command(name = "math")]
+struct MathArgs {
+    #[command(subcommand)]
+    command: MathCommand,
+}
+
+#[derive(Subcommand)]
+enum MathCommand {
+    Add { left: i64, right: i64 },
+    StdinLen,
+}
+
+struct Math;
+
+#[async_trait]
+impl ClapBuiltin for Math {
+    type Args = MathArgs;
+
+    async fn execute_clap(
+        &self,
+        args: Self::Args,
+        ctx: &mut BashkitContext<'_>,
+    ) -> bashkit::Result<()> {
+        let value = match args.command {
+            MathCommand::Add { left, right } => left + right,
+            MathCommand::StdinLen => ctx.stdin().unwrap_or("").len() as i64,
+        };
+        ctx.write_stdout(format!("{value}\n"));
+        Ok(())
+    }
+}
+
+#[tokio::main]
+async fn main() -> bashkit::Result<()> {
+    let mut bash = Bash::builder().builtin("math", Box::new(Math)).build();
+
+    let sum = bash.exec("math add 20 22").await?;
+    assert_eq!(sum.stdout, "42\n");
+
+    let stdin_len = bash.exec("printf abc | math stdin-len").await?;
+    assert_eq!(stdin_len.stdout, "3\n");
+    Ok(())
+}
+```
+
+## Behavior
+
+- The clap parser receives only the command arguments, not the shell command
+  name from the script.
+- `BashkitContext::write_stdout()` and `write_stderr()` append virtual command
+  output; direct `println!`/`eprintln!` writes to the host process instead.
+- Set non-zero command status with `ctx.set_exit_code(code)` or
+  `ctx.fail(message, code)`.
+- `--help` and `--version` return exit code `0` with clap output on stdout.
+- Parse failures return clap's exit code, usually `2`, with diagnostics on
+  stderr.
+- Diagnostics are capped at 1 KB so custom builtins keep Bashkit's builtin
+  error-output safety guarantees.
+
+## See Also
+
+- [`crates/bashkit/examples/clap_builtin.rs`](../examples/clap_builtin.rs)
+- [`crates/bashkit/examples/clap_builtin_subcommands.rs`](../examples/clap_builtin_subcommands.rs)
+- [`crates/bashkit/docs/custom_builtins.md`](./custom_builtins.md)

{bashkit-0.4.0 → bashkit-0.5.0}/crates/bashkit/docs/custom_builtins.md

@@ -7,7 +7,7 @@ virtual filesystem.
 
 **See also:**
 - [API Documentation](https://docs.rs/bashkit) - Full API reference
-- [Clap Builtins](../../../docs/clap-builtins.md) - Derive parser structs for custom builtin args
+- [Clap Builtins](./clap-builtins.md) - Derive parser structs for custom builtin args
 - [Hooks](./hooks.md) - Interceptor hooks for the execution pipeline
 - [Compatibility Reference](./compatibility.md) - Supported bash features
 - [Threat Model](./threat-model.md) - Security considerations
@@ -156,10 +156,9 @@ Arguments are passed as a slice of strings, excluding the command name itself:
 let first_arg = ctx.args.first().map(|s| s.as_str()).unwrap_or("default");
 ```
 
-For custom builtins with richer flags, options, or subcommands, enable the
-default `clap-builtins` feature and implement `ClapBuiltin` with a
-`#[derive(clap::Parser)]` argument type. See the `clap_builtins_guide` rustdoc
-module for tested examples.
+For custom builtins with richer flags, options, or subcommands, implement
+`ClapBuiltin` with a `#[derive(clap::Parser)]` argument type. See the
+`clap_builtins_guide` rustdoc module for tested examples.
 
 ### Environment Variables
 

bashkit-0.5.0/crates/bashkit/src/builtins/cat.rs

@@ -0,0 +1,193 @@
+//! cat builtin.
+//!
+//! Argument surface is generated from uutils/coreutils' `uu_app()` via the
+//! `bashkit-coreutils-port` codegen tool — see `generated/cat_args.rs` and
+//! `crates/bashkit-coreutils-port/`. Behaviour is implemented locally
+//! against the bashkit VFS.
+
+use async_trait::async_trait;
+use std::ffi::OsString;
+use std::path::Path;
+
+use super::generated::cat_args::cat_command;
+use super::{Builtin, Context, read_text_file};
+use crate::error::Result;
+use crate::interpreter::ExecResult;
+
+pub struct Cat;
+
+#[async_trait]
+impl Builtin for Cat {
+    async fn execute(&self, ctx: Context<'_>) -> Result<ExecResult> {
+        // clap expects argv[0] = program name; bashkit's ctx.args excludes it.
+        let argv: Vec<OsString> = std::iter::once(OsString::from("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) {
+            Ok(m) => m,
+            Err(e) => {
+                let kind = e.kind();
+                let rendered = e.render().to_string();
+                if matches!(
+                    kind,
+                    clap::error::ErrorKind::DisplayHelp | clap::error::ErrorKind::DisplayVersion
+                ) {
+                    return Ok(ExecResult::ok(rendered));
+                }
+                return Ok(ExecResult::err(rendered, 2));
+            }
+        };
+
+        // Composite flags: -A = -vET, -e = -vE, -t = -vT.
+        let g = |k: &str| matches.get_flag(k);
+        let show_all = g("show-all");
+        let number_nonblank = g("number-nonblank");
+        let nonprint_ends = g("e");
+        let nonprint_tabs = g("t");
+        let show_ends = g("show-ends") || show_all || nonprint_ends;
+        let show_tabs = g("show-tabs") || show_all || nonprint_tabs;
+        let show_nonprinting = g("show-nonprinting") || show_all || nonprint_ends || nonprint_tabs;
+        let number_all = g("number") && !number_nonblank;
+        let squeeze = g("squeeze-blank");
+
+        // GNU `cat` reads stdin when FILE is "-" or absent. clap defaults
+        // FILE to "-" so absence and "-" are unified.
+        let files: Vec<String> = matches
+            .get_many::<OsString>("file")
+            .map(|vs| vs.map(|v| v.to_string_lossy().into_owned()).collect())
+            .unwrap_or_default();
+
+        let mut raw = String::new();
+        for file in &files {
+            if file == "-" {
+                if let Some(stdin) = ctx.stdin {
+                    raw.push_str(stdin);
+                }
+            } else {
+                let path = if Path::new(file).is_absolute() {
+                    file.clone()
+                } else {
+                    ctx.cwd.join(file).to_string_lossy().into_owned()
+                };
+                match read_text_file(&*ctx.fs, Path::new(&path), "cat").await {
+                    Ok(t) => raw.push_str(&t),
+                    Err(e) => return Ok(e),
+                }
+            }
+        }
+
+        let output = render(
+            &raw,
+            show_ends,
+            show_tabs,
+            show_nonprinting,
+            number_all,
+            number_nonblank,
+            squeeze,
+        );
+        Ok(ExecResult::ok(output))
+    }
+}
+
+/// Apply cat's display transforms in a single pass.
+///
+/// One pass because numbering interacts with squeezing — squeezed blank
+/// lines must not be numbered. Two passes mis-number `cat -ns`.
+fn render(
+    raw: &str,
+    show_ends: bool,
+    show_tabs: bool,
+    show_nonprinting: bool,
+    number_all: bool,
+    number_nonblank: bool,
+    squeeze: bool,
+) -> String {
+    use std::fmt::Write;
+
+    let mut out = String::with_capacity(raw.len());
+    let mut counter: u64 = 0;
+    let mut prev_blank = false;
+
+    let mut iter = raw.split_inclusive('\n').peekable();
+    if iter.peek().is_none() {
+        return out;
+    }
+
+    for chunk in iter {
+        let (body, sep): (&str, &str) = match chunk.strip_suffix('\n') {
+            Some(b) => (b, "\n"),
+            None => (chunk, ""),
+        };
+        let is_blank = body.is_empty();
+
+        if squeeze && is_blank && prev_blank {
+            continue;
+        }
+        prev_blank = is_blank;
+
+        if number_all || (number_nonblank && !is_blank) {
+            counter += 1;
+            let _ = write!(out, "{counter:>6}\t");
+        }
+
+        if show_nonprinting || show_tabs {
+            for b in body.bytes() {
+                emit_byte(&mut out, b, show_tabs, show_nonprinting);
+            }
+        } else {
+            out.push_str(body);
+        }
+
+        if show_ends && !sep.is_empty() {
+            out.push('$');
+        }
+        out.push_str(sep);
+    }
+    out
+}
+
+/// GNU cat -v style byte rendering.
+///
+/// - tab (0x09): literal '\t' unless `show_tabs` (then `^I`).
+/// - bytes < 0x20 (other than tab/newline): `^X` (X = byte + 64) when
+///   show_nonprinting; passed through otherwise.
+/// - 0x7F (DEL): `^?`.
+/// - 0x80..=0xFF (high bit set): `M-` prefix + low-7-bit rendered same way.
+fn emit_byte(out: &mut String, b: u8, show_tabs: bool, show_nonprinting: bool) {
+    match b {
+        b'\t' if show_tabs => {
+            out.push('^');
+            out.push('I');
+        }
+        b'\t' => out.push('\t'),
+        b'\n' => out.push('\n'),
+        0..=31 if show_nonprinting => {
+            out.push('^');
+            out.push((b + 64) as char);
+        }
+        0x7f if show_nonprinting => {
+            out.push('^');
+            out.push('?');
+        }
+        128..=255 if show_nonprinting => {
+            out.push_str("M-");
+            let low = b & 0x7f;
+            if (0..32).contains(&low) {
+                out.push('^');
+                out.push((low + 64) as char);
+            } else if low == 0x7f {
+                out.push('^');
+                out.push('?');
+            } else {
+                out.push(low as char);
+            }
+        }
+        _ => out.push(b as char),
+    }
+}

{bashkit-0.4.0 → bashkit-0.5.0}/crates/bashkit/src/builtins/compgen.rs

@@ -29,10 +29,10 @@ const BUILTIN_COMMANDS: &[&str] = &[
     "history", "hostname", "iconv", "id", "jq", "json", "join", "kill", "ln", "local", "log", "ls",
     "mkdir", "mktemp", "mv", "nl", "od", "paste", "popd", "printenv", "printf", "pushd", "pwd",
     "read", "readlink", "readonly", "realpath", "retry", "return", "rev", "rm", "rmdir", "sed",
-    "semver", "seq", "set", "shift", "shopt", "sleep", "sort", "source", "split", "stat",
-    "strings", "tac", "tail", "tar", "tee", "test", "timeout", "touch", "tr", "tree", "true",
-    "uname", "unexpand", "uniq", "unset", "wait", "watch", "wc", "wget", "whoami", "xargs", "xxd",
-    "yes",
+    "semver", "seq", "set", "shift", "shopt", "shuf", "sleep", "sort", "source", "split", "stat",
+    "strings", "tac", "tail", "tar", "tee", "test", "timeout", "touch", "tr", "tree", "truncate",
+    "true", "uname", "unexpand", "uniq", "unset", "wait", "watch", "wc", "wget", "whoami", "xargs",
+    "xxd", "yes",
 ];
 
 #[async_trait]

bashkit-0.5.0/crates/bashkit/src/builtins/generated/cat_args.rs

@@ -0,0 +1,132 @@
+// GENERATED by bashkit-coreutils-port. DO NOT EDIT.
+//
+// Source: uutils/coreutils@39364b6 src/uu/cat/
+// Regenerate: cargo run -p bashkit-coreutils-port -- <UUTILS_DIR> cat <REV>
+//
+// Original uutils licensed MIT; see THIRD_PARTY_LICENSES.
+
+#![allow(unused_imports, dead_code)]
+use clap::{Arg, ArgAction, Command, builder::ValueParser};
+use std::ffi::OsString;
+use std::ops::RangeInclusive;
+use std::str::FromStr;
+mod options {
+    pub static FILE: &str = "file";
+    pub static SHOW_ALL: &str = "show-all";
+    pub static NUMBER_NONBLANK: &str = "number-nonblank";
+    pub static SHOW_NONPRINTING_ENDS: &str = "e";
+    pub static SHOW_ENDS: &str = "show-ends";
+    pub static NUMBER: &str = "number";
+    pub static SQUEEZE_BLANK: &str = "squeeze-blank";
+    pub static SHOW_NONPRINTING_TABS: &str = "t";
+    pub static SHOW_TABS: &str = "show-tabs";
+    pub static SHOW_NONPRINTING: &str = "show-nonprinting";
+    pub static IGNORED_U: &str = "ignored-u";
+}
+/// Vendored stand-in for `uucore::format_usage`.
+///
+/// Upstream wraps the usage line with stylized "Usage:" prefix logic
+/// driven by uucore's locale stack. For our purposes the raw string
+/// is enough; clap's `override_usage` accepts the literal as-is.
+fn format_usage(s: &str) -> String {
+    s.to_string()
+}
+pub fn cat_command() -> Command {
+    Command::new("cat")
+        .version(env!("CARGO_PKG_VERSION"))
+        .override_usage(
+            format_usage(&::std::string::String::from("cat [OPTION]... [FILE]...")),
+        )
+        .about(
+            ::std::string::String::from(
+                "Concatenate FILE(s), or standard input, to standard output\nWith no FILE, or when FILE is -, read standard input.",
+            ),
+        )
+        .infer_long_args(true)
+        .args_override_self(true)
+        .arg(
+            Arg::new(options::FILE)
+                .hide(true)
+                .action(ArgAction::Append)
+                .value_parser(clap::value_parser!(OsString))
+                .default_value("-")
+                .value_hint(clap::ValueHint::FilePath),
+        )
+        .arg(
+            Arg::new(options::SHOW_ALL)
+                .short('A')
+                .long(options::SHOW_ALL)
+                .help(::std::string::String::from("equivalent to -vET"))
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::NUMBER_NONBLANK)
+                .short('b')
+                .long(options::NUMBER_NONBLANK)
+                .help(
+                    ::std::string::String::from(
+                        "number nonempty output lines, overrides -n",
+                    ),
+                )
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::SHOW_NONPRINTING_ENDS)
+                .short('e')
+                .help(::std::string::String::from("equivalent to -vE"))
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::SHOW_ENDS)
+                .short('E')
+                .long(options::SHOW_ENDS)
+                .help(::std::string::String::from("display $ at end of each line"))
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::NUMBER)
+                .short('n')
+                .long(options::NUMBER)
+                .help(::std::string::String::from("number all output lines"))
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::SQUEEZE_BLANK)
+                .short('s')
+                .long(options::SQUEEZE_BLANK)
+                .help(
+                    ::std::string::String::from("suppress repeated empty output lines"),
+                )
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::SHOW_NONPRINTING_TABS)
+                .short('t')
+                .help(::std::string::String::from("equivalent to -vT"))
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::SHOW_TABS)
+                .short('T')
+                .long(options::SHOW_TABS)
+                .help(::std::string::String::from("display TAB characters at ^I"))
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::SHOW_NONPRINTING)
+                .short('v')
+                .long(options::SHOW_NONPRINTING)
+                .help(
+                    ::std::string::String::from(
+                        "use ^ and M- notation, except for LF (\\n) and TAB (\\t)",
+                    ),
+                )
+                .action(ArgAction::SetTrue),
+        )
+        .arg(
+            Arg::new(options::IGNORED_U)
+                .short('u')
+                .help(::std::string::String::from("(ignored)"))
+                .action(ArgAction::SetTrue),
+        )
+}

bashkit-0.5.0/crates/bashkit/src/builtins/generated/mod.rs

@@ -0,0 +1,34 @@
+// GENERATED MODULE INDEX. Edit individual `*_args.rs` files only via the
+// `bashkit-coreutils-port` codegen tool — see crates/bashkit-coreutils-port.
+//
+// Each `<util>_args.rs` exposes `pub fn <util>_command() -> clap::Command`
+// derived from uutils/coreutils' `uu_app()` definitions, with `translate!()`
+// keys resolved against the corresponding `en-US.ftl`.
+
+/// Pinned uutils/coreutils revision used by:
+///
+/// 1. The `bashkit-coreutils-port` codegen tool (drift workflow checks
+///    out uutils at this rev before regenerating `<util>_args.rs`).
+/// 2. The `coreutils_differential_tests` body-drift harness (drift
+///    workflow builds the `coreutils` multicall from this same rev
+///    before running the harness with `BASHKIT_RUN_COREUTILS_DIFF=1`).
+///
+/// Single source of truth: when this constant moves, both the args
+/// surfaces and the body-drift gate move with it. Bumping is normally
+/// the work of the auto-PR opened by `coreutils-args-drift.yml`; manual
+/// bumps require regenerating every `<util>_args.rs` file at the new
+/// rev so headers stay aligned with this constant. The static test
+/// `builtins::tests::generated_args_headers_match_pinned_uutils_\
+/// revision` enforces that invariant.
+//
+// The constant is read at port time (codegen, drift workflow, justfile)
+// and at test time (the invariant assertion). Nothing in the lib's
+// runtime path needs it, hence `allow(dead_code)`.
+#[allow(dead_code)]
+pub const UUTILS_REVISION: &str = "39364b6";
+
+pub mod cat_args;
+pub mod readlink_args;
+pub mod shuf_args;
+pub mod tac_args;
+pub mod truncate_args;