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";
@@ -295,10 +296,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 +391,7 @@ export async function executeWhile(
     }
   } finally {
     ctx.state.loopDepth--;
-    ctx.state.groupStdin = savedGroupStdin;
+    ctx.state.stdinCursor = savedCursor;
   }
 
   return result(stdout, stderr, exitCode);

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

@@ -47,6 +47,14 @@ export async function executePipeline(
   const isMultiCommandPipeline = node.commands.length > 1;
   const savedLastArg = ctx.state.lastArg;
 
+  // Save the cursor so we can restore it after the pipeline. The first
+  // command shares the cursor and may advance its position. Non-first
+  // commands must not see it (they read from the pipe, not from the loop's
+  // stdin). After the pipeline the cursor — with its potentially-advanced
+  // position — is put back so the next loop iteration reads from the right
+  // place.
+  const savedCursor = ctx.state.stdinCursor;
+
   for (let i = 0; i < node.commands.length; i++) {
     const command = node.commands[i];
     const isLast = i === node.commands.length - 1;
@@ -58,12 +66,10 @@ export async function executePipeline(
       // Clear $_ for each pipeline command - they each get fresh subshell context
       ctx.state.lastArg = "";
 
-      // After the first command, clear groupStdin so subsequent commands
-      // only see stdin from the pipeline (even if empty), not the original groupStdin
-      // This prevents commands like head from incorrectly falling back to groupStdin
-      // when they receive empty output from a previous command (e.g., grep with no matches)
+      // Non-first commands get their stdin from the pipe, not from the loop's
+      // cursor. Clear it so they cannot accidentally fall back to it.
       if (!isFirst) {
-        ctx.state.groupStdin = undefined;
+        ctx.state.stdinCursor = undefined;
       }
     }
 
@@ -238,5 +244,14 @@ export async function executePipeline(
   }
   // With lastpipe, the last command already updated $_ in the main shell context
 
+  // Restore the cursor ref for non-first pipeline commands. Those commands had
+  // it cleared (they must only read from the pipe), but the savedCursor still
+  // holds the shared object whose position may have been advanced by the first
+  // command. Putting it back lets the next loop iteration read from the right
+  // place.
+  if (isMultiCommandPipeline) {
+    ctx.state.stdinCursor = savedCursor;
+  }
+
   return lastResult;
 }

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

@@ -14,6 +14,7 @@ import type {
 } from "../ast/types.js";
 import { Parser } from "../parser/parser.js";
 import type { ParseException } from "../parser/types.js";
+import { StdinCursor } from "../stdin-cursor.js";
 import type { ExecResult } from "../types.js";
 import {
   BreakError,
@@ -109,10 +110,11 @@ export async function executeSubshell(
   const savedBashPid = ctx.state.bashPid;
   ctx.state.bashPid = ctx.state.nextVirtualPid++;
 
-  // Save any existing groupStdin and set new one from pipeline
-  const savedGroupStdin = ctx.state.groupStdin;
+  // Install a fresh cursor when subshell has its own stdin; otherwise share
+  // the outer cursor so reads inside the subshell advance the outer position.
+  const savedCursor = ctx.state.stdinCursor;
   if (stdin) {
-    ctx.state.groupStdin = stdin;
+    ctx.state.stdinCursor = new StdinCursor(stdin);
   }
 
   let stdout = "";
@@ -130,7 +132,7 @@ export async function executeSubshell(
     ctx.state.fullyUnsetLocals = savedFullyUnsetLocals;
     ctx.state.loopDepth = savedLoopDepth;
     ctx.state.parentHasLoopContext = savedParentHasLoopContext;
-    ctx.state.groupStdin = savedGroupStdin;
+    if (stdin) ctx.state.stdinCursor = savedCursor;
     ctx.state.bashPid = savedBashPid;
     ctx.state.lastArg = savedLastArg;
   };
@@ -272,10 +274,11 @@ export async function executeGroup(
     }
   }
 
-  // Save any existing groupStdin and set new one from pipeline
-  const savedGroupStdin = ctx.state.groupStdin;
+  // Install a fresh cursor when the group has its own stdin source; otherwise
+  // share the outer cursor so reads inside the group advance the outer position.
+  const savedCursor = ctx.state.stdinCursor;
   if (effectiveStdin) {
-    ctx.state.groupStdin = effectiveStdin;
+    ctx.state.stdinCursor = new StdinCursor(effectiveStdin);
   }
 
   try {
@@ -286,8 +289,7 @@ export async function executeGroup(
       exitCode = res.exitCode;
     }
   } catch (error) {
-    // Restore groupStdin before handling error
-    ctx.state.groupStdin = savedGroupStdin;
+    if (effectiveStdin) ctx.state.stdinCursor = savedCursor;
     // ExecutionLimitError must always propagate - these are safety limits
     if (error instanceof ExecutionLimitError) {
       throw error;
@@ -303,8 +305,7 @@ export async function executeGroup(
     return result(stdout, `${stderr}${getErrorMessage(error)}\n`, 1);
   }
 
-  // Restore groupStdin
-  ctx.state.groupStdin = savedGroupStdin;
+  if (effectiveStdin) ctx.state.stdinCursor = savedCursor;
 
   // Apply output redirections
   const bodyResult = result(stdout, stderr, exitCode);
@@ -353,15 +354,15 @@ export async function executeUserScript(
   const savedParentHasLoopContext = ctx.state.parentHasLoopContext;
   const savedLastArg = ctx.state.lastArg;
   const savedBashPid = ctx.state.bashPid;
-  const savedGroupStdin = ctx.state.groupStdin;
+  const savedCursor = ctx.state.stdinCursor;
   const savedSource = ctx.state.currentSource;
 
   // Set up subshell-like environment
   ctx.state.parentHasLoopContext = savedLoopDepth > 0;
   ctx.state.loopDepth = 0;
   ctx.state.bashPid = ctx.state.nextVirtualPid++;
   if (stdin) {
-    ctx.state.groupStdin = stdin;
+    ctx.state.stdinCursor = new StdinCursor(stdin);
   }
   ctx.state.currentSource = scriptPath;
 
@@ -387,7 +388,7 @@ export async function executeUserScript(
     ctx.state.parentHasLoopContext = savedParentHasLoopContext;
     ctx.state.lastArg = savedLastArg;
     ctx.state.bashPid = savedBashPid;
-    ctx.state.groupStdin = savedGroupStdin;
+    if (stdin) ctx.state.stdinCursor = savedCursor;
     ctx.state.currentSource = savedSource;
   };