feat: bash compatibility — compound arrays, grep -f, awk getline, jq env/input

## Summary

- **Compound associative array init**: `declare -A m=([k]=v)` now
tokenized as single word; lexer peeks for `[` after `=(` to distinguish
from indexed arrays
- **grep -f pattern-only mode**: fix parse requiring positional pattern
when `-f` is specified; unskip grep -r and grep -f tests with proper VFS
file setup
- **AWK getline**: implement `getline` statement with index-based
iteration; fix ORS and missing-field test expectations
- **JQ env access**: expose bashkit shell vars to process env so jaq's
`env` builtin works; RAII drop guard for cleanup on all return paths
- **String ops, read -r, heredocs** (from prior commit on branch):
prefix/suffix replace, heredoc tests, read builtin backslash handling

## Test plan

- [x] `cargo clippy --all-targets --all-features -- -D warnings` clean
- [x] `cargo test --all-features` — all pass (69 lib + 101 doc)
- [x] `cargo test --test spec_tests` — 13 suites green
- [x] 9 previously-skipped tests unskipped
- [x] ~12 new spec + unit tests added (positive and negative)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: chaliy

crates/bashkit/src/builtins/awk.rs

@@ -83,6 +83,7 @@ enum AwkAction {
     Break,
     Continue,
     Delete(String, AwkExpr), // delete arr[key]
+    Getline,                 // getline — read next input record into $0
     #[allow(dead_code)] // Exit code support for future
     Exit(Option<AwkExpr>),
     Expression(AwkExpr),
@@ -484,6 +485,9 @@ impl<'a> AwkParser<'a> {
         if self.matches_keyword("delete") {
             return self.parse_delete();
         }
+        if self.matches_keyword("getline") {
+            return Ok(AwkAction::Getline);
+        }
         if self.matches_keyword("exit") {
             self.skip_whitespace();
             if self.pos < self.input.len() {
@@ -1049,7 +1053,7 @@ impl<'a> AwkParser<'a> {
         let remaining = &self.input[self.pos..];
         let keywords = [
             "in", "if", "else", "while", "for", "do", "break", "continue", "next", "exit",
-            "delete", "print", "printf",
+            "delete", "getline", "print", "printf",
         ];
         for kw in keywords {
             if remaining.starts_with(kw) {
@@ -1510,13 +1514,19 @@ enum AwkFlow {
 struct AwkInterpreter {
     state: AwkState,
     output: String,
+    /// Lines of current input file (set before main loop)
+    input_lines: Vec<String>,
+    /// Current line index within input_lines
+    line_index: usize,
 }
 
 impl AwkInterpreter {
     fn new() -> Self {
         Self {
             state: AwkState::default(),
             output: String::new(),
+            input_lines: Vec::new(),
+            line_index: 0,
         }
     }
 
@@ -2380,6 +2390,15 @@ impl AwkInterpreter {
                 AwkFlow::Continue
             }
             AwkAction::Next => AwkFlow::Next,
+            AwkAction::Getline => {
+                // Advance to next input line and update $0, NR, NF, FNR
+                self.line_index += 1;
+                if self.line_index < self.input_lines.len() {
+                    let line = self.input_lines[self.line_index].clone();
+                    self.state.set_line(&line);
+                }
+                AwkFlow::Continue
+            }
             AwkAction::Break => AwkFlow::Break,
             AwkAction::Continue => AwkFlow::LoopContinue,
             AwkAction::Exit(expr) => {
@@ -2556,8 +2575,13 @@ impl Builtin for Awk {
 
         'files: for input in inputs {
             interp.state.fnr = 0;
-            for line in input.lines() {
-                interp.state.set_line(line);
+            // Index-based iteration so getline can advance the index
+            interp.input_lines = input.lines().map(|l| l.to_string()).collect();
+            interp.line_index = 0;
+
+            while interp.line_index < interp.input_lines.len() {
+                let line = interp.input_lines[interp.line_index].clone();
+                interp.state.set_line(&line);
 
                 for rule in &program.main_rules {
                     // Check pattern
@@ -2587,6 +2611,7 @@ impl Builtin for Awk {
                         }
                     }
                 }
+                interp.line_index += 1;
             }
         }
 
@@ -3024,6 +3049,29 @@ mod tests {
         assert_eq!(result.stdout, "line1\n");
     }
 
+    #[tokio::test]
+    async fn test_awk_getline_basic() {
+        let result = run_awk(&["{getline; print}"], Some("line1\nline2"))
+            .await
+            .unwrap();
+        assert_eq!(result.stdout, "line2\n");
+    }
+
+    #[tokio::test]
+    async fn test_awk_getline_updates_fields() {
+        let result = run_awk(&["{getline; print $1}"], Some("a b\nc d"))
+            .await
+            .unwrap();
+        assert_eq!(result.stdout, "c\n");
+    }
+
+    #[tokio::test]
+    async fn test_awk_getline_at_eof() {
+        // getline at EOF should keep current $0
+        let result = run_awk(&["{getline; print}"], Some("only")).await.unwrap();
+        assert_eq!(result.stdout, "only\n");
+    }
+
     #[tokio::test]
     async fn test_awk_revenue_calculation() {
         // This is the exact eval task pattern

crates/bashkit/src/builtins/grep.rs

@@ -278,8 +278,8 @@ impl GrepOptions {
             i += 1;
         }
 
-        // First positional is pattern (if no -e patterns)
-        if opts.patterns.is_empty() {
+        // First positional is pattern (if no -e patterns and no -f file)
+        if opts.patterns.is_empty() && opts.pattern_file.is_none() {
             if positional.is_empty() {
                 return Err(Error::Execution("grep: missing pattern".to_string()));
             }

crates/bashkit/src/builtins/jq.rs

@@ -22,6 +22,21 @@ use crate::interpreter::ExecResult;
 /// produce deeply nested parse trees in jaq.
 const MAX_JQ_JSON_DEPTH: usize = 100;
 
+/// RAII guard that restores process env vars when dropped.
+/// Ensures cleanup even on early-return error paths.
+struct EnvRestoreGuard(Vec<(String, Option<String>)>);
+
+impl Drop for EnvRestoreGuard {
+    fn drop(&mut self) {
+        for (k, old) in &self.0 {
+            match old {
+                Some(v) => std::env::set_var(k, v),
+                None => std::env::remove_var(k),
+            }
+        }
+    }
+}
+
 /// jq command - JSON processor
 pub struct Jq;
 
@@ -328,20 +343,40 @@ impl Builtin for Jq {
             json_vals.into_iter().map(Val::from).collect()
         };
 
+        // Expose bashkit's shell env/variables to the process environment so
+        // jaq's built-in `env` function (which reads std::env::vars()) works.
+        // Include both ctx.env (prefix assignments like FOO=bar jq ...)
+        // and ctx.variables (set via export builtin).
+        // Uses a drop guard to ensure cleanup on all return paths.
+        let mut seen = std::collections::HashSet::new();
+        let mut env_backup: Vec<(String, Option<String>)> = Vec::new();
+        for (k, v) in ctx.env.iter().chain(ctx.variables.iter()) {
+            if seen.insert(k.clone()) {
+                let old = std::env::var(k).ok();
+                std::env::set_var(k, v);
+                env_backup.push((k.clone(), old));
+            }
+        }
+        let _env_guard = EnvRestoreGuard(env_backup);
+
         // Track for -e exit status
         let mut has_output = false;
         let mut all_null_or_false = true;
 
-        for jaq_input in inputs_to_process {
-            // Create empty inputs iterator
-            let inputs = RcIter::new(core::iter::empty());
+        // Shared input iterator: main loop pops one value per filter run,
+        // and jaq's input/inputs functions consume from the same source.
+        let shared_inputs = RcIter::new(inputs_to_process.into_iter().map(Ok::<Val, String>));
+
+        for jaq_input in &shared_inputs {
+            let jaq_input: Val =
+                jaq_input.map_err(|e| Error::Execution(format!("jq: input error: {}", e)))?;
 
             // Run the filter, passing any --arg/--argjson variable values
             let var_vals: Vec<Val> = var_bindings
                 .iter()
                 .map(|(_, v)| Val::from(v.clone()))
                 .collect();
-            let ctx = Ctx::new(var_vals, &inputs);
+            let ctx = Ctx::new(var_vals, &shared_inputs);
             for result in filter.run((ctx, jaq_input)) {
                 match result {
                     Ok(val) => {
@@ -594,6 +629,27 @@ mod tests {
     /// TM-DOS-027: Deeply nested JSON arrays must be rejected
     /// Note: serde_json has a built-in recursion limit (~128 levels) that fires first.
     /// Our check_json_depth is defense-in-depth for values within serde's limit.
+    #[tokio::test]
+    async fn test_jq_input_reads_next() {
+        let result = run_jq_with_args(&["input"], "1\n2").await.unwrap();
+        assert_eq!(result.trim(), "2");
+    }
+
+    #[tokio::test]
+    async fn test_jq_inputs_collects_remaining() {
+        let result = run_jq_with_args(&["-c", "[inputs]"], "1\n2\n3")
+            .await
+            .unwrap();
+        assert_eq!(result.trim(), "[2,3]");
+    }
+
+    #[tokio::test]
+    async fn test_jq_inputs_single_value() {
+        // With single input, inputs yields empty array
+        let result = run_jq_with_args(&["-c", "[inputs]"], "42").await.unwrap();
+        assert_eq!(result.trim(), "[]");
+    }
+
     #[tokio::test]
     async fn test_jq_json_depth_limit_arrays() {
         // Build 150-level nested JSON: [[[[....[1]....]]]]
@@ -787,6 +843,60 @@ mod tests {
         assert_eq!(arr[1]["id"], 2);
     }
 
+    // --- env tests ---
+
+    #[tokio::test]
+    async fn test_jq_env_access() {
+        let jq = Jq;
+        let fs = Arc::new(InMemoryFs::new());
+        let mut vars = HashMap::new();
+        let mut cwd = PathBuf::from("/");
+        let mut env = HashMap::new();
+        env.insert("TESTVAR".to_string(), "hello".to_string());
+        let args = vec!["-n".to_string(), "env.TESTVAR".to_string()];
+
+        let ctx = Context {
+            args: &args,
+            env: &env,
+            variables: &mut vars,
+            cwd: &mut cwd,
+            fs,
+            stdin: None,
+            #[cfg(feature = "http_client")]
+            http_client: None,
+            #[cfg(feature = "git")]
+            git_client: None,
+        };
+
+        let result = jq.execute(ctx).await.unwrap();
+        assert_eq!(result.stdout.trim(), "\"hello\"");
+    }
+
+    #[tokio::test]
+    async fn test_jq_env_missing_var() {
+        let jq = Jq;
+        let fs = Arc::new(InMemoryFs::new());
+        let mut vars = HashMap::new();
+        let mut cwd = PathBuf::from("/");
+        let args = vec!["-n".to_string(), "env.NO_SUCH_VAR_999".to_string()];
+
+        let ctx = Context {
+            args: &args,
+            env: &HashMap::new(),
+            variables: &mut vars,
+            cwd: &mut cwd,
+            fs,
+            stdin: None,
+            #[cfg(feature = "http_client")]
+            http_client: None,
+            #[cfg(feature = "git")]
+            git_client: None,
+        };
+
+        let result = jq.execute(ctx).await.unwrap();
+        assert_eq!(result.stdout.trim(), "null");
+    }
+
     // --- Argument parsing bug regression tests ---
 
     #[tokio::test]

crates/bashkit/src/parser/lexer.rs

@@ -477,6 +477,57 @@ impl<'a> Lexer<'a> {
                 } else {
                     word.push('\\');
                 }
+            } else if ch == '(' && word.ends_with('=') && self.looks_like_assoc_assign() {
+                // Associative compound assignment: var=([k]="v" ...) — keep entire
+                // (...) as part of word so declare -A m=([k]="v") stays one token.
+                // Regular indexed arr=(a b "c d") is left for parser token-by-token path.
+                word.push(ch);
+                self.advance();
+                let mut depth = 1;
+                while let Some(c) = self.peek_char() {
+                    word.push(c);
+                    self.advance();
+                    match c {
+                        '(' => depth += 1,
+                        ')' => {
+                            depth -= 1;
+                            if depth == 0 {
+                                break;
+                            }
+                        }
+                        '"' => {
+                            while let Some(qc) = self.peek_char() {
+                                word.push(qc);
+                                self.advance();
+                                if qc == '"' {
+                                    break;
+                                }
+                                if qc == '\\' {
+                                    if let Some(esc) = self.peek_char() {
+                                        word.push(esc);
+                                        self.advance();
+                                    }
+                                }
+                            }
+                        }
+                        '\'' => {
+                            while let Some(qc) = self.peek_char() {
+                                word.push(qc);
+                                self.advance();
+                                if qc == '\'' {
+                                    break;
+                                }
+                            }
+                        }
+                        '\\' => {
+                            if let Some(esc) = self.peek_char() {
+                                word.push(esc);
+                                self.advance();
+                            }
+                        }
+                        _ => {}
+                    }
+                }
             } else if self.is_word_char(ch) {
                 word.push(ch);
                 self.advance();
@@ -756,6 +807,26 @@ impl<'a> Lexer<'a> {
         Some(Token::Word(word))
     }
 
+    /// Peek ahead (without consuming) to see if `=(` starts an associative
+    /// compound assignment like `([key]=val ...)`.  Returns true when the
+    /// first non-whitespace char after `(` is `[`.
+    fn looks_like_assoc_assign(&self) -> bool {
+        let mut chars = self.chars.clone();
+        // Skip the `(` we haven't consumed yet
+        if chars.next() != Some('(') {
+            return false;
+        }
+        // Skip optional whitespace
+        for ch in chars {
+            match ch {
+                ' ' | '\t' => continue,
+                '[' => return true,
+                _ => return false,
+            }
+        }
+        false
+    }
+
     fn is_word_char(&self, ch: char) -> bool {
         !matches!(
             ch,
@@ -958,4 +1029,25 @@ mod tests {
         let content = lexer.read_heredoc("EOF");
         assert_eq!(content, "hello\nworld\n");
     }
+
+    #[test]
+    fn test_assoc_compound_assignment() {
+        // declare -A m=([foo]="bar" [baz]="qux") should keep the compound
+        // assignment as a single Word token
+        let mut lexer = Lexer::new(r#"m=([foo]="bar" [baz]="qux")"#);
+        assert_eq!(
+            lexer.next_token(),
+            Some(Token::Word(r#"m=([foo]="bar" [baz]="qux")"#.to_string()))
+        );
+        assert_eq!(lexer.next_token(), None);
+    }
+
+    #[test]
+    fn test_indexed_array_not_collapsed() {
+        // arr=("hello world") should NOT be collapsed — parser handles
+        // quoted elements token-by-token via the LeftParen path
+        let mut lexer = Lexer::new(r#"arr=("hello world")"#);
+        assert_eq!(lexer.next_token(), Some(Token::Word("arr=".to_string())));
+        assert_eq!(lexer.next_token(), Some(Token::LeftParen));
+    }
 }