refactor(interpreter): replace groupStdin string with StdinCursor class

Replaces the `groupStdin?: string` snapshot pattern in IOState with a
`StdinCursor` object that tracks a position index into the original
content. The cursor is shared by reference across commands in the same
while-loop body, so any command that consumes stdin advances the
position in-place without needing explicit snapshot/restore gymnastics.

Key changes:
- New `StdinCursor` class with `remaining`, `advance(n)`, `readAll()`
- `read` and `mapfile` builtins call `advance` / `readAll` on the cursor
- `file-reader.ts` calls `ctx.stdinCursor?.readAll()` so cat, grep,
  head, awk, sed etc. inside while loops all advance position correctly
- `pipeline-execution.ts` simplified: save ref before pipeline, null it
  for non-first commands, restore after — the shared object carries
  any position advancement made by the first command
- `executeGroup`, `executeSubshell`, `executeUserScript`, `eval` all
  install a fresh cursor only when they have their own stdin source;
  otherwise they share the outer cursor
- `Bash.ts` constructs a StdinCursor from the top-level stdin option
  instead of passing a raw string

Fixes the case where `cat | tr` (or any file-reader-based command) was
used as the first command in a while-loop pipeline body and failed to
advance the loop's stdin position.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HyEbpGVknBW94w6XpvP462

Author: a0preetham

.changeset/while-loop-stdin-cursor.md

@@ -0,0 +1,40 @@
+---
+"just-bash": patch
+---
+
+interpreter: fix pipelines inside while-loop bodies eating loop stdin
+
+Commands inside a `while` loop body that were the first stage of a pipeline
+(e.g. `cat | tr a-z A-Z`) or that read stdin directly (e.g. `grep pattern`)
+were silently consuming the loop's stdin without advancing the shared position,
+causing subsequent `read` calls in the loop condition to see stale or
+already-consumed input.
+
+Replaces the `groupStdin?: string` snapshot in `IOState` with a `StdinCursor`
+class that tracks a byte offset into the original content. The cursor is shared
+by reference across all commands in a loop body, so any command that consumes
+stdin advances the position in-place. The loop's `read` builtin then resumes
+from the correct position on the next iteration without needing
+snapshot/restore logic.
+
+**Before** — a pipeline in the while body would silently reset stdin:
+
+```bash
+# Expected: A B C — Actual (before fix): infinite loop / wrong lines
+while IFS= read -r line; do
+  echo "$line" | cat
+done <<'EOF'
+A
+B
+C
+EOF
+```
+
+**After** — all commands share the cursor and advance it atomically:
+
+```bash
+# Works correctly in all body patterns
+while IFS= read -r line; do echo "$line" | cat; done  # pipeline body
+while IFS= read -r line; do cat | tr a-z A-Z; done    # file-reader first
+while IFS= read -r line; do grep "pat"; done           # direct stdin read
+```

packages/just-bash/src/Bash.ts

@@ -62,6 +62,7 @@ import {
   SecurityViolationError,
 } from "./security/defense-in-depth-box.js";
 import type { DefenseInDepthConfig } from "./security/types.js";
+import { StdinCursor } from "./stdin-cursor.js";
 import { serialize } from "./transform/serialize.js";
 import type {
   BashTransformResult,
@@ -648,7 +649,11 @@ export class Bash {
       // UTF-8 bytes. Callers that already prepared a byte buffer (e.g.
       // `Buffer.from(buf).toString("latin1")`) opt into raw passthrough
       // via `stdinKind: "bytes"`.
-      groupStdin: encodeStdinForPipeline(options?.stdin, options?.stdinKind),
+      stdinCursor: options?.stdin
+        ? new StdinCursor(
+            encodeStdinForPipeline(options.stdin, options.stdinKind) as string,
+          )
+        : undefined,
       // Cooperative cancellation signal (used by timeout command)
       signal: options?.signal,
       // Extra arguments injected directly into first command's arg list

packages/just-bash/src/commands/grep/grep.ts

@@ -229,7 +229,9 @@ export const grepCommand: Command = {
     // If no files and stdin is provided (including empty string), read from
     // stdin. grep runs regex over text — decode bytes to UTF-8 so multibyte
     // codepoints match `.` / character classes correctly.
+    // Advance the cursor so while-loop iterations know stdin was consumed.
     if (files.length === 0 && ctx.stdin !== undefined) {
+      ctx.stdinCursor?.readAll();
       const result = searchContent(decodeBytesToUtf8(ctx.stdin), regex, {
         invertMatch,
         showLineNumbers,

packages/just-bash/src/interpreter/builtin-dispatch.ts

@@ -412,17 +412,15 @@ export async function executeExternalCommand(
     ctx.state.hashTable.set(commandName, cmdPath);
   }
 
-  // Use groupStdin as fallback if no stdin from redirections/pipeline —
-  // needed for commands inside groups/functions that receive stdin via
-  // heredoc. The pipeline glue (pipeline-execution.ts) and the
-  // stdin-source sites (heredoc, here-string, `< file`, options.stdin)
-  // are responsible for handing us a latin1-shaped byte buffer; we just
-  // brand it. Commands that decode their input internally (sed, jq,
-  // ...) return text via `textOutput()`, and the pipe / redirect layer
-  // converts to bytes on their behalf.
-  const effectiveStdin = unsafeBytesFromLatin1(
-    stdin || ctx.state.groupStdin || "",
-  );
+  // Use the cursor's remaining content as fallback when no pipeline stdin.
+  // The cursor is shared by reference: commands that consume stdin via
+  // file-reader (cat, grep, head, …) call cursor.readAll() which advances
+  // the position, so subsequent loop iterations start from the right place.
+  // Only pass the cursor when stdin is empty (pipeline commands with explicit
+  // stdin must not fall back to the loop's cursor).
+  const cursorContent = !stdin ? ctx.state.stdinCursor?.remaining : undefined;
+  const effectiveStdin = unsafeBytesFromLatin1(stdin || cursorContent || "");
+  const stdinCursor = !stdin ? ctx.state.stdinCursor : undefined;
 
   // Build exported environment for commands that need it (printenv, env, etc.)
   // Most builtins need access to the full env to modify state
@@ -434,6 +432,7 @@ export async function executeExternalCommand(
     env: ctx.state.env,
     exportedEnv,
     stdin: effectiveStdin,
+    stdinCursor,
     limits: ctx.limits,
     exec: ctx.execFn,
     fetch: ctx.fetch,

packages/just-bash/src/interpreter/builtins/eval.ts

@@ -6,6 +6,7 @@
  */
 
 import { type ParseException, parse } from "../../parser/parser.js";
+import { StdinCursor } from "../../stdin-cursor.js";
 import type { ExecResult } from "../../types.js";
 import {
   BreakError,
@@ -50,12 +51,12 @@ export async function handleEval(
     return OK;
   }
 
-  // Save and set groupStdin for piped eval commands
-  // This allows stdin from the pipeline to flow to commands within eval
-  const savedGroupStdin = ctx.state.groupStdin;
-  const effectiveStdin = stdin ?? ctx.state.groupStdin;
-  if (effectiveStdin !== undefined) {
-    ctx.state.groupStdin = effectiveStdin;
+  // If eval received stdin from a pipeline, install a fresh cursor for it so
+  // read commands inside eval consume from that input. If no pipeline stdin,
+  // eval shares the outer cursor — reads inside eval advance it normally.
+  const savedCursor = ctx.state.stdinCursor;
+  if (stdin) {
+    ctx.state.stdinCursor = new StdinCursor(stdin);
   }
 
   try {
@@ -77,7 +78,8 @@ export async function handleEval(
     }
     throw error;
   } finally {
-    // Restore groupStdin
-    ctx.state.groupStdin = savedGroupStdin;
+    if (stdin) {
+      ctx.state.stdinCursor = savedCursor;
+    }
   }
 }

packages/just-bash/src/interpreter/builtins/mapfile.ts

@@ -62,10 +62,10 @@ export function handleMapfile(
     }
   }
 
-  // Use stdin from parameter, or fall back to groupStdin
+  // Use stdin from parameter, or fall back to cursor's remaining content.
   let effectiveStdin = stdin;
-  if (!effectiveStdin && ctx.state.groupStdin !== undefined) {
-    effectiveStdin = ctx.state.groupStdin;
+  if (!effectiveStdin && ctx.state.stdinCursor !== undefined) {
+    effectiveStdin = ctx.state.stdinCursor.remaining;
   }
 
   // Split input by delimiter
@@ -162,9 +162,9 @@ export function handleMapfile(
     String(Math.max(existingLength, newEndIndex)),
   );
 
-  // Consume from groupStdin if we used it
-  if (ctx.state.groupStdin !== undefined && !stdin) {
-    ctx.state.groupStdin = "";
+  // mapfile reads all stdin — exhaust the cursor so the loop advances.
+  if (ctx.state.stdinCursor !== undefined && !stdin) {
+    ctx.state.stdinCursor.readAll();
   }
 
   return result("", "", 0);

packages/just-bash/src/interpreter/builtins/read.ts

@@ -263,7 +263,7 @@ export function handleRead(
     return result("", "", 1);
   }
 
-  // Use stdin from parameter, or fall back to groupStdin (for piped groups/while loops)
+  // Use stdin from parameter, or fall back to stdinCursor (for piped groups/while loops)
   // If -u is specified, use the file descriptor content instead
   let effectiveStdin = stdin;
 
@@ -274,8 +274,8 @@ export function handleRead(
     } else {
       effectiveStdin = "";
     }
-  } else if (!effectiveStdin && ctx.state.groupStdin !== undefined) {
-    effectiveStdin = ctx.state.groupStdin;
+  } else if (!effectiveStdin && ctx.state.stdinCursor !== undefined) {
+    effectiveStdin = ctx.state.stdinCursor.remaining;
   }
 
   // Handle -d '' (empty delimiter) - reads until NUL byte
@@ -308,8 +308,8 @@ export function handleRead(
           );
         }
       }
-    } else if (ctx.state.groupStdin !== undefined && !stdin) {
-      ctx.state.groupStdin = effectiveStdin.substring(bytesConsumed);
+    } else if (ctx.state.stdinCursor !== undefined && !stdin) {
+      ctx.state.stdinCursor.advance(bytesConsumed);
     }
   };
 

packages/just-bash/src/interpreter/control-flow.ts

@@ -21,6 +21,7 @@ import type {
   WhileNode,
   WordNode,
 } from "../ast/types.js";
+import { StdinCursor } from "../stdin-cursor.js";
 import type { ExecResult } from "../types.js";
 import { evaluateArithmetic } from "./arithmetic.js";
 import { matchPattern } from "./conditionals.js";
@@ -66,6 +67,7 @@ export async function executeIf(
 export async function executeFor(
   ctx: InterpreterContext,
   node: ForNode,
+  stdin = "",
 ): Promise<ExecResult> {
   // Pre-open output redirects to truncate files BEFORE expanding words
   // This matches bash behavior where redirect files are opened before
@@ -85,6 +87,41 @@ export async function executeFor(
     return failure(`bash: \`${node.variable}': not a valid identifier\n`);
   }
 
+  // Process stdin redirections so body commands (e.g. read) can consume them.
+  let effectiveStdin = stdin;
+  for (const redir of node.redirections) {
+    if (
+      (redir.operator === "<<" || redir.operator === "<<-") &&
+      redir.target.type === "HereDoc"
+    ) {
+      const hereDoc = redir.target as HereDocNode;
+      let content = await expandWord(ctx, hereDoc.content);
+      if (hereDoc.stripTabs) {
+        content = content
+          .split("\n")
+          .map((line) => line.replace(/^\t+/, ""))
+          .join("\n");
+      }
+      effectiveStdin = content;
+    } else if (redir.operator === "<<<" && redir.target.type === "Word") {
+      effectiveStdin = `${await expandWord(ctx, redir.target as WordNode)}\n`;
+    } else if (redir.operator === "<" && redir.target.type === "Word") {
+      try {
+        const target = await expandWord(ctx, redir.target as WordNode);
+        const filePath = ctx.fs.resolvePath(ctx.state.cwd, target);
+        effectiveStdin = await ctx.fs.readFile(filePath);
+      } catch {
+        const target = await expandWord(ctx, redir.target as WordNode);
+        return failure(`bash: ${target}: No such file or directory\n`);
+      }
+    }
+  }
+
+  const savedCursor = ctx.state.stdinCursor;
+  if (effectiveStdin) {
+    ctx.state.stdinCursor = new StdinCursor(effectiveStdin);
+  }
+
   let words: string[] = [];
   if (node.words === null) {
     words = (ctx.state.env.get("@") || "").split(" ").filter(Boolean);
@@ -148,6 +185,7 @@ export async function executeFor(
     }
   } finally {
     ctx.state.loopDepth--;
+    ctx.state.stdinCursor = savedCursor;
   }
 
   // Note: In bash, the loop variable persists after the loop with its last value
@@ -295,10 +333,10 @@ export async function executeWhile(
     }
   }
 
-  // Save and set groupStdin for piped while loops
-  const savedGroupStdin = ctx.state.groupStdin;
+  // Install a fresh cursor for this loop's stdin, saving any outer cursor.
+  const savedCursor = ctx.state.stdinCursor;
   if (effectiveStdin) {
-    ctx.state.groupStdin = effectiveStdin;
+    ctx.state.stdinCursor = new StdinCursor(effectiveStdin);
   }
 
   ctx.state.loopDepth++;
@@ -390,7 +428,7 @@ export async function executeWhile(
     }
   } finally {
     ctx.state.loopDepth--;
-    ctx.state.groupStdin = savedGroupStdin;
+    ctx.state.stdinCursor = savedCursor;
   }
 
   return result(stdout, stderr, exitCode);
@@ -399,12 +437,47 @@ export async function executeWhile(
 export async function executeUntil(
   ctx: InterpreterContext,
   node: UntilNode,
+  stdin = "",
 ): Promise<ExecResult> {
   let stdout = "";
   let stderr = "";
   let exitCode = 0;
   let iterations = 0;
 
+  let effectiveStdin = stdin;
+  for (const redir of node.redirections) {
+    if (
+      (redir.operator === "<<" || redir.operator === "<<-") &&
+      redir.target.type === "HereDoc"
+    ) {
+      const hereDoc = redir.target as HereDocNode;
+      let content = await expandWord(ctx, hereDoc.content);
+      if (hereDoc.stripTabs) {
+        content = content
+          .split("\n")
+          .map((line) => line.replace(/^\t+/, ""))
+          .join("\n");
+      }
+      effectiveStdin = content;
+    } else if (redir.operator === "<<<" && redir.target.type === "Word") {
+      effectiveStdin = `${await expandWord(ctx, redir.target as WordNode)}\n`;
+    } else if (redir.operator === "<" && redir.target.type === "Word") {
+      try {
+        const target = await expandWord(ctx, redir.target as WordNode);
+        const filePath = ctx.fs.resolvePath(ctx.state.cwd, target);
+        effectiveStdin = await ctx.fs.readFile(filePath);
+      } catch {
+        const target = await expandWord(ctx, redir.target as WordNode);
+        return failure(`bash: ${target}: No such file or directory\n`);
+      }
+    }
+  }
+
+  const savedCursor = ctx.state.stdinCursor;
+  if (effectiveStdin) {
+    ctx.state.stdinCursor = new StdinCursor(effectiveStdin);
+  }
+
   ctx.state.loopDepth++;
   try {
     while (true) {
@@ -451,6 +524,7 @@ export async function executeUntil(
     }
   } finally {
     ctx.state.loopDepth--;
+    ctx.state.stdinCursor = savedCursor;
   }
 
   return result(stdout, stderr, exitCode);

packages/just-bash/src/interpreter/interpreter.ts

@@ -502,13 +502,13 @@ export class Interpreter {
       case "If":
         return executeIf(this.ctx, node);
       case "For":
-        return executeFor(this.ctx, node);
+        return executeFor(this.ctx, node, stdin);
       case "CStyleFor":
         return executeCStyleFor(this.ctx, node);
       case "While":
         return executeWhile(this.ctx, node, stdin);
       case "Until":
-        return executeUntil(this.ctx, node);
+        return executeUntil(this.ctx, node, stdin);
       case "Case":
         return executeCase(this.ctx, node);
       case "Subshell":