feat(yq): add jq-backed YAML processor (#2266)

## What changed
Replaces the bespoke dotted-path `yaml` helper with a feature-gated `yq`
builtin backed by the existing jq/jaq evaluator. Agents can process YAML
or JSON from stdin/files with identity, nested selection, iteration,
`select`, `map`, assignment, multi-document streams, YAML/JSON
conversion, raw/compact/exit-status/slurp/null-input modes, combined
short flags, and atomic in-place updates.

Adds parser/document/depth/output controls, deterministic bounded
diagnostics, no-leak property coverage, generated builtin metadata, user
docs, limitations, and threat-model entries. TOML/CSV/XML and
mikefarah/yq node/style operators remain explicit unsupported
boundaries.

## Why
The old `yaml` command implemented a narrow second query language that
did not match the jq-style yq surface commonly generated by agents.
Sharing jq/jaq avoids duplicate evaluator semantics and inherits its
work, deadline, and output controls.

## Before / After
Before:
```console
$ printf "items:\n  - type: fruit\n    name: apple\n" | yq ".items[] | select(.type == \"fruit\") | .name"
bash: yq: command not found
```

After:
```console
$ printf "%s\n" "---" "type: fruit" "name: apple" "---" "type: veg" "name: kale" "---" "type: fruit" "name: pear" | yq -s -o=json -I=0 "[.[] | select(.type == \"fruit\") | .name]"
["apple","pear"]
```

Proof: 14/14 portable yq specs, 9 yq integration tests, arbitrary-YAML
no-leak property, conditional mikefarah/yq differential, WASM feature
check, real-`rg` regression, and post-rebase `just pre-pr`.

## Risk
- Medium
- Removes the nonstandard `yaml` helper and makes `yq` available with
the `jq` feature. YAML mapping keys sort deterministically at the
JSON-value boundary; source order, comments, styles, and anchors are not
preserved. Custom tags and non-string keys fail closed. In-place writes
depend on VFS sibling rename semantics and are covered for success,
parse/filter/exit-status failure, stdout suppression, and mode
preservation.

## Checklist
- [x] Tests added or updated
- [x] Backward compatibility considered

Author: chaliy

Cargo.lock

@@ -32,6 +32,7 @@ anyhow = "1"
 # Serialization
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+serde_yaml_ng = "0.10"
 
 # JSON processing (jq) - verified embeddable
 jaq-core = "3.0"

Cargo.toml

@@ -30,6 +30,7 @@ anyhow = { workspace = true }
 # Serialization
 serde = { workspace = true }
 serde_json = { workspace = true }
+serde_yaml_ng = { workspace = true, optional = true }
 
 # Regex
 regex = { workspace = true }
@@ -123,7 +124,7 @@ default = ["bash_tool"]
 bash_tool = ["dep:tower", "dep:futures-core"]
 # Enable jq builtin via embedded jaq interpreter
 # Usage: cargo build --features jq
-jq = ["dep:jaq-core", "dep:jaq-std", "dep:jaq-json"]
+jq = ["dep:jaq-core", "dep:jaq-std", "dep:jaq-json", "dep:serde_yaml_ng"]
 http_client = ["reqwest", "rustls"]
 # Enable Ed25519 request signing per RFC 9421 / web-bot-auth profile
 bot-auth = ["http_client", "dep:ed25519-dalek", "dep:rand", "dep:zeroize"]

crates/bashkit/Cargo.toml

@@ -99,7 +99,7 @@ through configurable limits.
 | Compound assign overflow (TM-DOS-043) | `((x+=1))` with x=i64::MAX | `wrapping_*` ops | **MITIGATED** |
 | Lexer stack overflow (TM-DOS-044) | ~50 nested `$()` in quotes | Depth tracking | **MITIGATED** |
 | parse_word_string limits (TM-DOS-050) | Parameter expansion ignores limits | Propagate limits | **MITIGATED** |
-| YAML parser recursion (TM-DOS-051) | Deeply nested YAML stack overflow | Add depth limit | **MITIGATED** |
+| Removed YAML helper parser (TM-DOS-051) | Former custom parser recursed over indentation | Parser deleted; yq uses TM-DOS-101 controls | **REMOVED** |
 | Template engine recursion (TM-DOS-052) | Nested `{{#if}}`/`{{#each}}` overflow | Add depth limit | **MITIGATED** |
 | Template output explosion (TM-DOS-053) | `{{#each}}` on large array | Bounded by `max_file_size` | MITIGATED |
 | glob ExtGlob blowup (TM-DOS-054) | `glob --files "+(a\|aa)"` | Same as TM-DOS-031 | **MITIGATED** |
@@ -158,6 +158,7 @@ let bash = Bash::builder()
 | Suspended host-call retention (TM-DOS-098) | Script repeats event-backed calls or host never resumes one | Capacity-one channel, normal execution limits, and handle-owned session released on drop | MITIGATED |
 | `time` report amplification (TM-DOS-099) | Attacker-controlled `-f` format expands repeatedly or targets the VFS with `-o` | Incremental rendering is capped by the stderr limit before emission or file replacement | MITIGATED |
 | jq control normalization amplification (TM-DOS-100) | Literal controls expand sixfold as `\u00XX` | Charge single-pass work and lease live bytes before allocation growth | MITIGATED |
+| yq structured-data amplification (TM-DOS-101) | Deep/multi-document YAML or JSON, runaway filters, expanded output | Parser depth and 4096-document caps, aggregate budgets, shared jaq work/deadline/output limits, final render cap | MITIGATED |
 
 ### Sandbox Escape (TM-ESC-*)
 
@@ -846,6 +847,7 @@ read-only by default and gated by an allowlist.
 | Permissive RealFs mount (TM-FS-013) | `mount_real_readonly_at("/", …)` exposes the whole host | Allowlist-first: broad roots (`/`, `/etc`, `/root`, `/home`, …) and any path component matching `.ssh`, `.aws`, `.kube`, `.docker`, `.gnupg`, `.gcloud` are refused unless explicitly allowlisted | MITIGATED |
 | Partial filesystem mutation (TM-FS-014) | Failed write/copy or cross-mount move leaves corruption, duplication, or retained quota | Failure-atomic `FileSystem` contract; RealFs sibling staging; MountableFs destination rollback; NamespaceFs cross-device rejection; shared conformance + failpoint tests | MITIGATED |
 | Partial tar extraction (TM-FS-015) | A late unsafe or malformed entry leaves earlier files behind | Validate the complete archive and file limits before the first VFS mutation | MITIGATED |
+| yq in-place partial update (TM-FS-016) | A failed transform or write truncates the source file | Evaluate and serialize before writing; random sibling temporary file, mode preservation, and rename-on-success | MITIGATED |
 
 ### Unicode Security (TM-UNI-*)
 

crates/bashkit/docs/threat-model.md

@@ -0,0 +1,66 @@
+# yq builtin
+
+Bashkit ships a `yq` structured-data processor for the command shape agents
+commonly use with mikefarah/yq. It parses YAML or JSON, evaluates the existing
+`jq`/jaq expression engine, then emits YAML or JSON. Bashkit deliberately does
+not maintain a second YAML-specific query language.
+
+Enable the Cargo `jq` feature to register both `jq` and `yq`.
+
+## Examples
+
+```bash
+yq '.server.port' config.yml
+yq '.items[] | select(.enabled) | .name' config.yml
+yq '.values | map(. * 2)' config.yml
+yq -o=json -I=0 '.' config.yml
+yq -p=json -o=yaml '.' data.json
+yq -i '.server.port = 8080' config.yml
+```
+
+With no expression, `.` is used. Input comes from the listed VFS files or
+stdin. YAML streams containing `---` are processed one document at a time;
+`-s` presents all input documents to the filter as one array. The optional
+`e` / `eval` subcommand alias is accepted for common generated invocations.
+
+## Flags
+
+| Flag | Behaviour |
+|------|-----------|
+| `-p`, `--input-format` | `auto`, `yaml`, or `json` |
+| `-o`, `--output-format` | `yaml` or `json` |
+| `-r`, `--raw-output` | Unwrap string results |
+| `-c`, `--compact-output` | Compact JSON output |
+| `-e`, `--exit-status` | Nonzero for no output, `null`, or `false` |
+| `-s`, `--slurp` | Read all documents into an array |
+| `-n`, `--null-input` | Evaluate once with `null` input |
+| `-i`, `--inplace` | Atomically replace exactly one input file |
+| `-I`, `--indent` | Set JSON indentation; `0` is compact |
+| `-N`, `--no-doc` | Omit separators between YAML results |
+| `--expression` | Force an otherwise ambiguous argument to be the expression |
+
+Short boolean flags combine (`-rce`, `-sn`). Attached value forms such as
+`-o=json`, `-p=json`, and `-I=0` are accepted.
+
+In-place evaluation and serialization finish before a sibling temporary file
+is written and renamed over the source. A parse, filter, output-limit, write,
+or rename failure leaves the source unchanged.
+
+## Compatibility boundary
+
+The expression language is jq, not mikefarah/yq's node/style language. Common
+selection, iteration, `select`, `map`, construction, reduction, and assignment
+filters work. mikefarah/yq-only operators for comments, styles, anchors, tags,
+file metadata, and cross-file evaluation are not implemented.
+
+YAML custom tags and non-string mapping keys are rejected rather than silently
+losing information. Mapping keys are sorted deterministically at the JSON-value
+boundary. Comments, scalar style, and anchors are not retained after
+conversion. The parser follows YAML 1.1. TOML, CSV, and XML conversion are not
+part of this builtin; Bashkit's separate `tomlq` and `csv` helpers remain
+available for their existing narrow command surfaces.
+
+## See also
+
+- [`jq_guide`](crate::jq_guide) — the shared expression engine and its jq compatibility notes.
+- [`threat_model`](crate::threat_model) — structured-input resource and information-disclosure controls.

crates/bashkit/docs/yq.md

@@ -17,7 +17,7 @@ use std::collections::BTreeMap;
 /// Families registered by compile feature alone (present in a default-built
 /// `Bash` whenever the feature is on).
 const CFG_REGISTERED: &[(&str, &[&str])] = &[
-    ("jq", &["jq"]),
+    ("jq", &["jq", "yq"]),
     ("git", &["git"]),
     ("ssh", &["ssh", "scp", "sftp"]),
 ];
@@ -63,16 +63,16 @@ fn main() {
         .iter()
         .map(|name| {
             serde_json::json!({
-                "name": name,
                 "feature": feature_of.get(name),
+                "name": name,
             })
         })
         .collect();
 
     let doc = serde_json::json!({
         "_generated": "just regen-builtins — do not edit by hand",
-        "count": builtins.len(),
         "builtins": builtins,
+        "count": builtins.len(),
     });
     println!("{}", serde_json::to_string_pretty(&doc).expect("serialize"));
 }

crates/bashkit/examples/dump_builtins.rs

@@ -83,9 +83,6 @@ pub(crate) const TEMPLATE_MAX_DEPTH: usize = 100;
 /// timeout: max timeout duration in seconds (5 minutes).
 pub(crate) const TIMEOUT_MAX_SECONDS: u64 = 300;
 
-/// yaml: max nesting depth.
-pub(crate) const YAML_MAX_DEPTH: usize = 100;
-
 /// yes: max lines and total output bytes per invocation.
 pub(crate) const YES_MAX_LINES: usize = 10_000;
 pub(crate) const YES_MAX_OUTPUT_BYTES: usize = 1_048_576;

crates/bashkit/src/builtins/limits.rs

@@ -108,8 +108,9 @@ mod vars;
 mod verify;
 mod wait;
 mod wc;
-mod yaml;
 mod yes;
+#[cfg(feature = "jq")]
+mod yq;
 mod zip_cmd;
 
 mod helpers;
@@ -218,8 +219,9 @@ pub use vars::{Eval, Local, Readonly, Set, Shift, Shopt, Times, Unset};
 pub use verify::Verify;
 pub use wait::Wait;
 pub use wc::Wc;
-pub use yaml::Yaml;
 pub use yes::Yes;
+#[cfg(feature = "jq")]
+pub use yq::Yq;
 pub use zip_cmd::{Unzip, Zip};
 
 #[cfg(feature = "git")]
@@ -1596,7 +1598,7 @@ mod tests {
             "tee",
             "csv",
             "json",
-            "yaml",
+            "yq",
             "tomlq",
             "jq",
             "semver",