Skip to main content

nu_protocol/engine/
stack.rs

1use crate::{
2    Config, ENV_VARIABLE_ID, IntoValue, LAST_VARIABLE_ID, NU_VARIABLE_ID, OutDest, PipelineData,
3    PipelineMetadata, ShellError, Span, Value, VarId,
4    ast::PathMember,
5    engine::{
6        ArgumentStack, DEFAULT_OVERLAY_NAME, EngineState, EnvName, ErrorHandlerStack, Redirection,
7        ScopeBindings, StackCallArgGuard, StackCollectValueGuard, StackIoGuard, StackOutDest,
8        StackWithInvocation, env_var_eq,
9    },
10    ir::ScopeRegion,
11    record, report_shell_warning,
12    shell_error::generic::GenericError,
13    truncate_value_to_budget,
14};
15use std::{
16    borrow::Cow,
17    collections::{HashMap, HashSet},
18    fs::File,
19    path::{Component, MAIN_SEPARATOR},
20    sync::{Arc, Mutex},
21};
22
23/// Shared interactive last-result (`$ans`) storage.
24///
25/// Held in an [`Arc`] so REPL child stacks from [`Stack::with_parent`] see the same
26/// payload and can clear `warn_pending` without mutating an immutable parent frame.
27///
28/// When [`Self::present`] is true, reading `$ans` yields a record with
29/// `exit_code`, `duration`, and `command`. The `last` field is included only when a
30/// payload is stored. When false (never snapshotted after a user command), `$ans`
31/// is `nothing`.
32#[derive(Debug, Default)]
33struct LastResultSlot {
34    /// Whether `$ans` should resolve to a record (vs `nothing`).
35    present: bool,
36    /// Pipeline payload for the `last` field (`None` when payload capture is off).
37    last: Option<Value>,
38    /// Pipeline metadata for replaying `last` (e.g. `ls` path_columns / colors).
39    metadata: Option<PipelineMetadata>,
40    truncated: bool,
41    /// Exit code of the last REPL line (mirrors `$env.LAST_EXIT_CODE`).
42    exit_code: i64,
43    /// Duration of the last REPL line in nanoseconds (Nushell `Duration` value).
44    duration_ns: i64,
45    /// Exact REPL source of the last user line (same buffer reedline stores in history).
46    command: String,
47    /// Set when a store was truncated; moved to `warn_deferred` on first access.
48    warn_pending: bool,
49    /// Set when `$ans` was accessed after a truncated store; reported after output prints.
50    warn_deferred: bool,
51}
52
53/// Environment variables per overlay
54pub type EnvVars = HashMap<String, HashMap<EnvName, Value>>;
55
56/// A runtime value stack used during evaluation
57///
58/// A note on implementation:
59///
60/// We previously set up the stack in a traditional way, where stack frames had parents which would
61/// represent other frames that you might return to when exiting a function.
62///
63/// While experimenting with blocks, we found that we needed to have closure captures of variables
64/// seen outside of the blocks, so that they blocks could be run in a way that was both thread-safe
65/// and followed the restrictions for closures applied to iterators. The end result left us with
66/// closure-captured single stack frames that blocks could see.
67///
68/// Blocks make up the only scope and stack definition abstraction in Nushell. As a result, we were
69/// creating closure captures at any point we wanted to have a Block value we could safely evaluate
70/// in any context. This meant that the parents were going largely unused, with captured variables
71/// taking their place. The end result is this, where we no longer have separate frames, but instead
72/// use the Stack as a way of representing the local and closure-captured state.
73#[derive(Debug, Clone)]
74pub struct Stack {
75    /// Variables
76    pub vars: Vec<(VarId, Value)>,
77    /// Environment variables arranged as a stack to be able to recover values from parent scopes
78    pub env_vars: Vec<Arc<EnvVars>>,
79    /// Tells which environment variables from engine state are hidden, per overlay.
80    pub env_hidden: Arc<HashMap<String, HashSet<EnvName>>>,
81    /// Tracks env vars hidden in this stack context to report repeated `hide-env` calls.
82    ///
83    /// This is separate from `env_hidden`: `env_hidden` controls runtime visibility for engine
84    /// state values, while `env_hide_history` preserves command semantics for repeated hides.
85    pub env_hide_history: Arc<HashMap<String, HashSet<EnvName>>>,
86    /// List of active overlays
87    pub active_overlays: Vec<String>,
88    /// Argument stack for IR evaluation
89    pub arguments: ArgumentStack,
90    /// Error handler stack for IR evaluation
91    pub error_handlers: ErrorHandlerStack,
92    /// Number of nested custom command and closure calls that led to this stack.
93    ///
94    /// Block evaluation fails with `RecursionLimitReached` once this exceeds
95    /// `$env.config.recursion_limit`, before deep recursion can overflow the Rust stack.
96    pub recursion_count: u64,
97    pub parent_stack: Option<Arc<Stack>>,
98    /// Variables that have been deleted (this is used to hide values from parent stack lookups)
99    pub parent_deletions: Vec<VarId>,
100    /// Variables deleted in this stack
101    pub deletions: Vec<VarId>,
102    /// Locally updated config. Use [`.get_config()`](Self::get_config) to access correctly.
103    pub config: Option<Arc<Config>>,
104    pub(crate) out_dest: StackOutDest,
105    /// When `true`, external processes spawned from this stack are detached from
106    /// the controlling terminal, and empty stdin is `/dev/null` instead of inheriting
107    /// the TTY. Used on completion threads so children cannot race reedline.
108    pub suppress_stdin: bool,
109    /// Active block-local scope bindings (commands/modules), outer → inner.
110    ///
111    /// Pushed when evaluating a whole block via `eval_ir_block` (closures, custom commands).
112    /// Used by `scope` together with [`Self::ir_scope_regions`].
113    pub active_scope_bindings: Vec<Arc<ScopeBindings>>,
114    /// Scope regions of the IR block currently being evaluated (inlined keyword bodies).
115    pub ir_scope_regions: Vec<ScopeRegion>,
116    /// Current program counter while evaluating IR (for matching [`Self::ir_scope_regions`]).
117    pub ir_instruction_index: Option<usize>,
118    /// Interactive last-result payload for [`LAST_VARIABLE_ID`] (e.g. `$ans`).
119    ///
120    /// Shared across parent/child stacks so REPL iterations (which use
121    /// [`Stack::with_parent`]) can store and clear truncation warnings correctly.
122    last_result: Arc<Mutex<LastResultSlot>>,
123}
124
125impl Default for Stack {
126    fn default() -> Self {
127        Self::new()
128    }
129}
130
131impl Stack {
132    /// Create a new stack.
133    ///
134    /// stdout and stderr will be set to [`OutDest::Inherit`]. So, if the last command is an external command,
135    /// then its output will be forwarded to the terminal/stdio streams.
136    ///
137    /// Use [`Stack::collect_value`] afterwards if you need to evaluate an expression to a [`Value`]
138    /// (as opposed to a [`PipelineData`](crate::PipelineData)).
139    pub fn new() -> Self {
140        Self {
141            vars: Vec::new(),
142            env_vars: Vec::new(),
143            env_hidden: Arc::new(HashMap::new()),
144            env_hide_history: Arc::new(HashMap::new()),
145            active_overlays: vec![DEFAULT_OVERLAY_NAME.to_string()],
146            arguments: ArgumentStack::new(),
147            error_handlers: ErrorHandlerStack::new(),
148            recursion_count: 0,
149            parent_stack: None,
150            parent_deletions: vec![],
151            deletions: vec![],
152            config: None,
153            out_dest: StackOutDest::new(),
154            suppress_stdin: false,
155            active_scope_bindings: vec![],
156            ir_scope_regions: vec![],
157            ir_instruction_index: None,
158            last_result: Arc::new(Mutex::new(LastResultSlot::default())),
159        }
160    }
161
162    /// Create a new child stack from a parent.
163    ///
164    /// Changes from this child can be merged back into the parent with
165    /// [`Stack::with_changes_from_child`]
166    pub fn with_parent(parent: Arc<Stack>) -> Stack {
167        Stack {
168            // here we are still cloning environment variable-related information
169            env_vars: parent.env_vars.clone(),
170            env_hidden: parent.env_hidden.clone(),
171            env_hide_history: parent.env_hide_history.clone(),
172            active_overlays: parent.active_overlays.clone(),
173            arguments: ArgumentStack::new(),
174            error_handlers: ErrorHandlerStack::new(),
175            recursion_count: parent.recursion_count,
176            vars: vec![],
177            parent_deletions: vec![],
178            deletions: vec![],
179            config: parent.config.clone(),
180            out_dest: parent.out_dest.clone(),
181            suppress_stdin: parent.suppress_stdin,
182            // Child inherits outer block bindings so nested `scope` still sees them.
183            active_scope_bindings: parent.active_scope_bindings.clone(),
184            // Nested IR evaluation installs its own regions/pc.
185            ir_scope_regions: vec![],
186            ir_instruction_index: None,
187            // Share last-result with the parent (REPL uses with_parent every iteration).
188            last_result: parent.last_result.clone(),
189            parent_stack: Some(parent),
190        }
191    }
192
193    /// Push block-local scope bindings for the duration of evaluating a whole block.
194    pub fn push_scope_bindings(&mut self, bindings: Arc<ScopeBindings>) {
195        self.active_scope_bindings.push(bindings);
196    }
197
198    /// Pop the most recently pushed whole-block scope bindings.
199    pub fn pop_scope_bindings(&mut self) {
200        let popped = self.active_scope_bindings.pop();
201        debug_assert!(
202            popped.is_some(),
203            "pop_scope_bindings with empty active_scope_bindings (unbalanced push/pop)"
204        );
205    }
206
207    /// Take an [`Arc`] parent, and a child, and apply all the changes from a child back to the parent.
208    ///
209    /// Here it is assumed that `child` was created by a call to [`Stack::with_parent`] with `parent`.
210    ///
211    /// For this to be performant and not clone `parent`, `child` should be the only other
212    /// referencer of `parent`.
213    pub fn with_changes_from_child(parent: Arc<Stack>, child: Stack) -> Stack {
214        // we're going to drop the link to the parent stack on our new stack
215        // so that we can unwrap the Arc as a unique reference
216        drop(child.parent_stack);
217        let mut unique_stack = Arc::unwrap_or_clone(parent);
218
219        unique_stack
220            .vars
221            .retain(|(var, _)| !child.parent_deletions.contains(var));
222        for (var, value) in child.vars {
223            unique_stack.add_var(var, value);
224        }
225        unique_stack.env_vars = child.env_vars;
226        unique_stack.env_hidden = child.env_hidden;
227        unique_stack.env_hide_history = child.env_hide_history;
228        unique_stack.active_overlays = child.active_overlays;
229        unique_stack.config = child.config;
230        // last_result is Arc-shared with the child; no merge needed.
231        unique_stack
232    }
233
234    pub fn with_env(
235        &mut self,
236        env_vars: &[Arc<EnvVars>],
237        env_hidden: &Arc<HashMap<String, HashSet<EnvName>>>,
238    ) {
239        // Do not clone the environment if it hasn't changed
240        if self.env_vars.iter().any(|scope| !scope.is_empty()) {
241            env_vars.clone_into(&mut self.env_vars);
242        }
243
244        if !self.env_hidden.is_empty() {
245            self.env_hidden.clone_from(env_hidden);
246        }
247    }
248
249    /// Lookup a variable, returning None if it is not present
250    fn lookup_var(&self, var_id: VarId) -> Option<Value> {
251        if var_id == LAST_VARIABLE_ID {
252            return self.assemble_ans_record(Span::unknown());
253        }
254
255        for (id, val) in &self.vars {
256            if var_id == *id {
257                return Some(val.clone());
258            }
259        }
260
261        if let Some(stack) = &self.parent_stack
262            && !self.parent_deletions.contains(&var_id)
263        {
264            return stack.lookup_var(var_id);
265        }
266        None
267    }
268
269    fn with_last_result_slot<R>(&self, f: impl FnOnce(&LastResultSlot) -> R) -> R {
270        match self.last_result.lock() {
271            Ok(slot) => f(&slot),
272            // Poison is rare; recover so `$ans` / capture do not hard-panic the REPL.
273            Err(poisoned) => f(&poisoned.into_inner()),
274        }
275    }
276
277    fn with_last_result_slot_mut<R>(&self, f: impl FnOnce(&mut LastResultSlot) -> R) -> R {
278        match self.last_result.lock() {
279            Ok(mut slot) => f(&mut slot),
280            Err(poisoned) => {
281                let mut slot = poisoned.into_inner();
282                // Drop potentially inconsistent state after a panic while locked.
283                *slot = LastResultSlot::default();
284                f(&mut slot)
285            }
286        }
287    }
288
289    /// Build the `$ans` record when the slot is present; otherwise `None` (→ `nothing`).
290    ///
291    /// Omits the `last` field entirely when no payload is stored (e.g. budget is `0`),
292    /// so `$ans` is `{ exit_code, duration, command }` only. `command` is always included
293    /// once the slot is present.
294    fn assemble_ans_record(&self, span: Span) -> Option<Value> {
295        self.with_last_result_slot(|slot| {
296            if !slot.present {
297                return None;
298            }
299            Some(match &slot.last {
300                Some(last) => Value::record(
301                    record! {
302                        "last" => last.clone().with_span(span),
303                        "exit_code" => Value::int(slot.exit_code, span),
304                        "duration" => Value::duration(slot.duration_ns, span),
305                        "command" => Value::string(slot.command.clone(), span),
306                    },
307                    span,
308                ),
309                None => Value::record(
310                    record! {
311                        "exit_code" => Value::int(slot.exit_code, span),
312                        "duration" => Value::duration(slot.duration_ns, span),
313                        "command" => Value::string(slot.command.clone(), span),
314                    },
315                    span,
316                ),
317            })
318        })
319    }
320
321    /// Drop the entire `$ans` slot (full clear).
322    pub fn clear_last_result(&mut self) {
323        self.with_last_result_slot_mut(|slot| {
324            if let Some(old) = slot.last.take() {
325                drop(old);
326            }
327            *slot = LastResultSlot::default();
328        });
329    }
330
331    /// Drop only `$ans.last` and its metadata/truncation flags, freeing payload memory.
332    ///
333    /// Leaves `present`, `exit_code`, `duration`, and `command` unchanged so a budget of
334    /// `0` can still expose timing/exit status/source without retaining the pipeline value.
335    pub fn clear_last_result_payload(&mut self) {
336        self.with_last_result_slot_mut(|slot| {
337            if let Some(old) = slot.last.take() {
338                drop(old);
339            }
340            slot.metadata = None;
341            slot.truncated = false;
342            slot.warn_pending = false;
343            slot.warn_deferred = false;
344        });
345    }
346
347    /// Store `value` as `$ans.last`, enforcing `budget` via truncation.
348    ///
349    /// When `budget == 0`, payload capture is disabled (clears `.last` only; exit code,
350    /// duration, and `command` stay). Preserves pipeline `metadata` (e.g. `path_columns` used for
351    /// `ls` coloring) so replaying `$ans.last` can match the original display.
352    pub fn set_last_result(
353        &mut self,
354        value: Value,
355        metadata: Option<PipelineMetadata>,
356        budget: usize,
357    ) {
358        if budget == 0 {
359            self.clear_last_result_payload();
360            return;
361        }
362
363        let (stored, truncated) = truncate_value_to_budget(value, budget);
364        self.store_last_result_raw(stored, metadata, truncated);
365    }
366
367    /// Install an already-budgeted `$ans.last` value (caller handled truncation).
368    ///
369    /// Marks `$ans` present. Does not reset `exit_code` / `duration` / `command` (those are
370    /// updated by [`Self::snapshot_ans_repl_metadata`] at end of each REPL line).
371    pub fn store_last_result_raw(
372        &mut self,
373        value: Value,
374        metadata: Option<PipelineMetadata>,
375        truncated: bool,
376    ) {
377        self.with_last_result_slot_mut(|slot| {
378            if let Some(old) = slot.last.replace(value) {
379                drop(old);
380            }
381            slot.metadata = metadata;
382            slot.truncated = truncated;
383            slot.warn_pending = truncated;
384            // Fresh store replaces any not-yet-shown deferred warning.
385            slot.warn_deferred = false;
386            slot.present = true;
387        });
388    }
389
390    /// After a REPL user command finishes: refresh `$ans.exit_code`, `$ans.duration`,
391    /// and `$ans.command`.
392    ///
393    /// `command` is the exact reedline buffer for this line (same text history stores).
394    /// Always marks `$ans` present so every user-typed line gets exit code, duration,
395    /// and source (empty Enter / auto-cd do not call this). When `budget == 0`, also
396    /// drops `$ans.last` (and its memory) so the record is `{ exit_code, duration, command }`
397    /// without a `last` field. When budget is positive, any `.last` already stored this
398    /// line (or earlier) is kept.
399    pub fn snapshot_ans_repl_metadata(
400        &mut self,
401        engine_state: &EngineState,
402        duration: std::time::Duration,
403        command: impl Into<String>,
404    ) {
405        let budget = self.get_config(engine_state).max_last_result_size_bytes();
406        let exit_code = self
407            .get_env_var(engine_state, "LAST_EXIT_CODE")
408            .and_then(|v| v.as_int().ok())
409            .unwrap_or(0);
410        let duration_ns = i64::try_from(duration.as_nanos()).unwrap_or(i64::MAX);
411        let command = command.into();
412
413        if budget == 0 {
414            // Payload off: free `.last` memory before refreshing metadata.
415            self.clear_last_result_payload();
416        }
417
418        self.with_last_result_slot_mut(|slot| {
419            slot.exit_code = exit_code;
420            slot.duration_ns = duration_ns;
421            slot.command = command;
422            slot.present = true;
423        });
424    }
425
426    /// Pipeline metadata associated with the stored `$ans.last`, if any.
427    pub fn last_result_metadata(&self) -> Option<PipelineMetadata> {
428        self.with_last_result_slot(|slot| slot.metadata.clone())
429    }
430
431    /// Estimated memory size of the stored `$ans.last` payload (`0` if unset).
432    pub fn last_result_memory_size(&self) -> usize {
433        self.with_last_result_slot(|slot| slot.last.as_ref().map(|v| v.memory_size()).unwrap_or(0))
434    }
435
436    /// Marker key in [`PipelineMetadata::custom`] identifying pipeline data loaded from `$ans`.
437    ///
438    /// Used so IR cell-path follow only reattaches last-result metadata for `$ans.last`,
439    /// not every unrelated record field named `last`.
440    pub const ANS_LAST_RESULT_METADATA_KEY: &str = "ans_last_result";
441
442    /// Build [`PipelineData`] for `$ans`, restoring stored pipeline metadata on the record
443    /// so `$ans.last` cell-path access can reattach it (see IR `FollowCellPath`).
444    pub fn last_result_pipeline_data(&self, span: Span) -> PipelineData {
445        let mut metadata = self.last_result_metadata().unwrap_or_default();
446        // Mark so FollowCellPath can reattach payload metadata only for `$ans.*`.
447        metadata
448            .custom
449            .insert(Self::ANS_LAST_RESULT_METADATA_KEY, Value::bool(true, span));
450        let value = self
451            .assemble_ans_record(span)
452            .unwrap_or_else(|| Value::nothing(span));
453        PipelineData::value(value, Some(metadata))
454    }
455
456    /// Whether the currently stored `$ans.last` was truncated.
457    pub fn last_result_was_truncated(&self) -> bool {
458        self.with_last_result_slot(|slot| slot.truncated)
459    }
460
461    /// On `$ans` access after a truncated store: schedule a warning for after output prints.
462    ///
463    /// Does not print anything. Call [`Self::take_last_result_warn_deferred`] after display
464    /// so the truncated value is shown first, then the warning.
465    pub fn defer_last_result_truncation_warning(&self) {
466        self.with_last_result_slot_mut(|slot| {
467            if slot.warn_pending {
468                slot.warn_pending = false;
469                slot.warn_deferred = true;
470            }
471        });
472    }
473
474    /// Whether a truncation warning is waiting to be shown after print (does not clear).
475    pub fn last_result_warn_pending(&self) -> bool {
476        self.with_last_result_slot(|slot| slot.warn_pending)
477    }
478
479    /// Take the deferred truncation warning flag (clears it).
480    ///
481    /// Returns `true` once after a truncated `$ans` was accessed; intended to be called
482    /// after the pipeline has been printed so the warning appears below the data.
483    pub fn take_last_result_warn_deferred(&self) -> bool {
484        self.with_last_result_slot_mut(|slot| std::mem::take(&mut slot.warn_deferred))
485    }
486
487    /// Report a deferred last-result truncation warning, if any.
488    ///
489    /// Prefer calling this after printing so output is not scrolled away by the warning.
490    pub fn flush_last_result_truncation_warning(&self, engine_state: &EngineState, span: Span) {
491        if !self.take_last_result_warn_deferred() {
492            return;
493        }
494        let limit_bytes = self.get_config(engine_state).max_last_result_size_bytes();
495        report_shell_warning(
496            Some(self),
497            engine_state,
498            &crate::ShellWarning::LastResultTruncated {
499                span,
500                limit_bytes,
501                help: Some(format!(
502                    "Increase $env.config.max_last_result_size or use a smaller command result. Variable name is `${}`.",
503                    crate::LAST_RESULT_VAR_NAME
504                )),
505                // EveryUse: once-per-access is handled by warn_pending/warn_deferred flags.
506                report_mode: crate::ReportMode::EveryUse,
507            },
508        );
509    }
510
511    /// Lookup a variable, erroring if it is not found
512    ///
513    /// The passed-in span will be used to tag the value
514    pub fn get_var(&self, var_id: VarId, span: Span) -> Result<Value, ShellError> {
515        match self.lookup_var(var_id) {
516            Some(v) => Ok(v.with_span(span)),
517            // Unset last-result behaves like `nothing` rather than a missing variable.
518            None if var_id == LAST_VARIABLE_ID => Ok(Value::nothing(span)),
519            None => Err(ShellError::VariableNotFoundAtRuntime { span }),
520        }
521    }
522
523    /// Lookup a variable, erroring if it is not found
524    ///
525    /// While the passed-in span will be used for errors, the returned value
526    /// has the span from where it was originally defined
527    pub fn get_var_with_origin(&self, var_id: VarId, span: Span) -> Result<Value, ShellError> {
528        match self.lookup_var(var_id) {
529            Some(v) => Ok(v),
530            None => {
531                if var_id == NU_VARIABLE_ID || var_id == ENV_VARIABLE_ID {
532                    return Err(ShellError::Generic(GenericError::new(
533                        "Built-in variables `$env` and `$nu` have no metadata",
534                        "no metadata available",
535                        span,
536                    )));
537                }
538                Err(ShellError::VariableNotFoundAtRuntime { span })
539            }
540        }
541    }
542
543    /// Get the local config if set, otherwise the config from the engine state.
544    ///
545    /// This is the canonical way to get [`Config`] when [`Stack`] is available.
546    pub fn get_config(&self, engine_state: &EngineState) -> Arc<Config> {
547        self.config
548            .clone()
549            .unwrap_or_else(|| engine_state.config.clone())
550    }
551
552    /// Update the local config with the config stored in the `config` environment variable. Run
553    /// this after assigning to `$env.config`.
554    ///
555    /// The config will be updated with successfully parsed values even if an error occurs.
556    pub fn update_config(&mut self, engine_state: &EngineState) -> Result<(), ShellError> {
557        if let Some(value) = self.get_env_var(engine_state, "config") {
558            let old = self.get_config(engine_state);
559            let mut config = (*old).clone();
560            let result = config.update_from_value_with_options(
561                &old,
562                value,
563                engine_state.history_locked_after_startup,
564            );
565            // The config value is modified by the update, so we should add it again
566            let name = self.get_env_var_name(engine_state, "config").into_owned();
567            self.add_env_var(name, config.clone().into_value(value.span()));
568            self.config = Some(config.into());
569            if let Some(warning) = result? {
570                report_shell_warning(Some(self), engine_state, &warning);
571            }
572        } else {
573            self.config = None;
574        }
575        Ok(())
576    }
577
578    pub fn add_var(&mut self, var_id: VarId, value: Value) {
579        //self.vars.insert(var_id, value);
580        for (id, val) in &mut self.vars {
581            if *id == var_id {
582                *val = value;
583                return;
584            }
585        }
586        self.vars.push((var_id, value));
587    }
588
589    /// Return a mutable reference to a variable's value for in-place mutation.
590    ///
591    /// Looks up the variable in the current stack frame first. If not found, pulls it
592    /// from the parent chain into the current frame (cloning it once). This enables
593    /// zero-clone mutation for local `mut` variables: use `get_var_mut` + mutate instead
594    /// of `lookup_var` (clone) + mutate + `add_var` (move back).
595    pub fn get_var_mut(&mut self, var_id: VarId) -> Option<&mut Value> {
596        // Use index-based access to avoid conflicting mutable borrows
597        if let Some(pos) = self.vars.iter().position(|(id, _)| var_id == *id) {
598            return Some(&mut self.vars[pos].1);
599        }
600        // Check parent chain
601        if let Some(parent) = &self.parent_stack
602            && !self.parent_deletions.contains(&var_id)
603        {
604            let value = parent.lookup_var(var_id)?;
605            self.vars.push((var_id, value));
606            return self.vars.last_mut().map(|(_, val)| val);
607        }
608        None
609    }
610
611    /// Upsert a cell path on a variable in place (shared by AST and IR assignment paths).
612    ///
613    /// Errors with [`ShellError::VariableNotFoundAtRuntime`] if the variable is not on
614    /// this stack or its parent chain.
615    pub fn upsert_var_cell_path(
616        &mut self,
617        var_id: VarId,
618        members: &[PathMember],
619        new_value: Value,
620        span: Span,
621    ) -> Result<(), ShellError> {
622        let value = self
623            .get_var_mut(var_id)
624            .ok_or(ShellError::VariableNotFoundAtRuntime { span })?;
625        value.upsert_data_at_cell_path(members, new_value)
626    }
627
628    pub fn remove_var(&mut self, var_id: VarId) {
629        for (idx, (id, _)) in self.vars.iter().enumerate() {
630            if *id == var_id {
631                self.vars.remove(idx);
632                break;
633            }
634        }
635        // even if we did have it in the original layer, we need to make sure to remove it here
636        // as well (since the previous update might have simply hid the parent value)
637        if self.parent_stack.is_some() {
638            self.parent_deletions.push(var_id);
639        }
640        self.deletions.push(var_id);
641    }
642
643    pub fn add_env_var(&mut self, var: String, value: Value) {
644        if let Some(last_overlay) = self.active_overlays.last().cloned() {
645            let env_name = EnvName::from(var);
646            self.clear_env_var_marks_in_active_overlay(&last_overlay, &env_name);
647
648            if let Some(scope) = self.env_vars.last_mut() {
649                let scope = Arc::make_mut(scope);
650                if let Some(env_vars) = scope.get_mut(&last_overlay) {
651                    env_vars.insert(env_name, value);
652                } else {
653                    scope.insert(last_overlay, [(env_name, value)].into_iter().collect());
654                }
655            } else {
656                self.env_vars.push(Arc::new(
657                    [(last_overlay, [(env_name, value)].into_iter().collect())]
658                        .into_iter()
659                        .collect(),
660                ));
661            }
662        } else {
663            // TODO: Remove panic
664            panic!("internal error: no active overlay");
665        }
666    }
667
668    fn clear_env_var_marks_in_active_overlay(&mut self, overlay: &str, env_name: &EnvName) {
669        if let Some(env_hidden) = Arc::make_mut(&mut self.env_hidden).get_mut(overlay) {
670            // Re-assigning re-activates a previously hidden env var in this overlay.
671            env_hidden.remove(env_name);
672        }
673
674        if let Some(hide_history) = Arc::make_mut(&mut self.env_hide_history).get_mut(overlay) {
675            hide_history.remove(env_name);
676        }
677    }
678
679    pub fn set_last_exit_code(&mut self, code: i32, span: Span) {
680        self.add_env_var("LAST_EXIT_CODE".into(), Value::int(code.into(), span));
681    }
682
683    pub fn set_last_error(&mut self, error: &ShellError) {
684        if let Some(code) = error.external_exit_code() {
685            self.set_last_exit_code(code.item, code.span);
686        } else if let Some(code) = error.exit_code() {
687            self.set_last_exit_code(code, Span::unknown());
688        }
689    }
690
691    pub fn last_overlay_name(&self) -> Result<String, ShellError> {
692        self.active_overlays
693            .last()
694            .cloned()
695            .ok_or_else(|| ShellError::NushellFailed {
696                msg: "No active overlay".into(),
697            })
698    }
699
700    /// Like [`captures_to_stack_preserve_out_dest`], but sets the new scope up to collect output into a Value.
701    pub fn captures_to_stack(&self, captures: Vec<(VarId, Value)>) -> Stack {
702        self.captures_to_stack_preserve_out_dest(captures)
703            .collect_value()
704    }
705
706    /// Creates a derived stack for a new scope, with the given captures.
707    ///
708    /// The caller is retained as [`Self::parent_stack`] so outer variables remain visible to
709    /// `scope variables` (and other stack lookups that walk parents). Captured values are still
710    /// copied onto this stack for isolation of the closure’s own locals.
711    ///
712    /// Every closure call builds its stack here, so this is where a closure call adds one to
713    /// [`Self::recursion_count`].
714    pub fn captures_to_stack_preserve_out_dest(&self, captures: Vec<(VarId, Value)>) -> Stack {
715        let mut env_vars = self.env_vars.clone();
716        env_vars.push(Arc::new(HashMap::new()));
717
718        Stack {
719            vars: captures,
720            env_vars,
721            env_hidden: self.env_hidden.clone(),
722            env_hide_history: self.env_hide_history.clone(),
723            active_overlays: self.active_overlays.clone(),
724            arguments: ArgumentStack::new(),
725            error_handlers: ErrorHandlerStack::new(),
726            // A closure body is a nested call like a custom command body, so it counts toward
727            // the recursion limit. Stack overflows are not recoverable in Rust.
728            recursion_count: self.recursion_count + 1,
729            // Keep the caller as parent so global/outer locals stay nameable for `scope`
730            // (values are still resolved via the parent chain when not captured).
731            parent_stack: Some(Arc::new(self.clone())),
732            parent_deletions: vec![],
733            deletions: vec![],
734            config: self.config.clone(),
735            out_dest: self.out_dest.clone(),
736            suppress_stdin: self.suppress_stdin,
737            // Inherit caller block bindings so nested closures still see outer local defs.
738            active_scope_bindings: self.active_scope_bindings.clone(),
739            ir_scope_regions: vec![],
740            ir_instruction_index: None,
741            // Share last-result so closures can still read `$ans`.
742            last_result: self.last_result.clone(),
743        }
744    }
745
746    pub fn gather_captures(&self, engine_state: &EngineState, captures: &[(VarId, Span)]) -> Stack {
747        let mut vars = Vec::with_capacity(captures.len());
748
749        let fake_span = Span::new(0, 0);
750
751        for (capture, _) in captures {
752            // Note: this assumes we have calculated captures correctly and that commands
753            // that take in a var decl will manually set this into scope when running the blocks
754            if let Ok(value) = self.get_var(*capture, fake_span) {
755                vars.push((*capture, value));
756            } else if let Some(const_val) = &engine_state.get_var(*capture).const_val {
757                vars.push((*capture, const_val.clone()));
758            }
759        }
760
761        let mut env_vars = self.env_vars.clone();
762        env_vars.push(Arc::new(HashMap::new()));
763
764        Stack {
765            vars,
766            env_vars,
767            env_hidden: self.env_hidden.clone(),
768            env_hide_history: self.env_hide_history.clone(),
769            active_overlays: self.active_overlays.clone(),
770            arguments: ArgumentStack::new(),
771            error_handlers: ErrorHandlerStack::new(),
772            recursion_count: self.recursion_count,
773            parent_stack: Some(Arc::new(self.clone())),
774            parent_deletions: vec![],
775            deletions: vec![],
776            config: self.config.clone(),
777            out_dest: self.out_dest.clone(),
778            suppress_stdin: self.suppress_stdin,
779            // Inherit caller block bindings so nested closures still see outer local defs.
780            active_scope_bindings: self.active_scope_bindings.clone(),
781            ir_scope_regions: vec![],
782            ir_instruction_index: None,
783            // Share last-result so closures can still read `$ans`.
784            last_result: self.last_result.clone(),
785        }
786    }
787
788    /// Flatten the env var scope frames into one frame
789    pub fn get_env_vars(&self, engine_state: &EngineState) -> HashMap<String, Value> {
790        let mut result = HashMap::new();
791
792        for active_overlay in self.active_overlays.iter() {
793            if let Some(env_vars) = engine_state.env_vars.get(active_overlay) {
794                result.extend(
795                    env_vars
796                        .iter()
797                        .filter(|(k, _)| {
798                            if let Some(env_hidden) = self.env_hidden.get(active_overlay) {
799                                !env_hidden.contains(*k)
800                            } else {
801                                // nothing has been hidden in this overlay
802                                true
803                            }
804                        })
805                        .map(|(k, v)| (k.as_str().to_string(), v.clone()))
806                        .collect::<HashMap<String, Value>>(),
807                );
808            }
809        }
810
811        result.extend(self.get_stack_env_vars());
812
813        result
814    }
815
816    /// Get flattened environment variables only from the stack
817    pub fn get_stack_env_vars(&self) -> HashMap<String, Value> {
818        let mut result = HashMap::new();
819
820        for scope in &self.env_vars {
821            for active_overlay in self.active_overlays.iter() {
822                if let Some(env_vars) = scope.get(active_overlay) {
823                    result.extend(
824                        env_vars
825                            .iter()
826                            .map(|(k, v)| (k.as_str().to_string(), v.clone())),
827                    );
828                }
829            }
830        }
831
832        result
833    }
834
835    /// Get flattened environment variables only from the stack and one overlay
836    pub fn get_stack_overlay_env_vars(&self, overlay_name: &str) -> HashMap<String, Value> {
837        let mut result = HashMap::new();
838
839        for scope in &self.env_vars {
840            if let Some(active_overlay) = self.active_overlays.iter().find(|n| n == &overlay_name)
841                && let Some(env_vars) = scope.get(active_overlay)
842            {
843                result.extend(
844                    env_vars
845                        .iter()
846                        .map(|(k, v)| (k.as_str().to_string(), v.clone())),
847                );
848            }
849        }
850
851        result
852    }
853
854    /// Get hidden envs, but without envs defined previously in `excluded_overlay_name`.
855    pub fn get_hidden_env_vars(
856        &self,
857        excluded_overlay_name: &str,
858        engine_state: &EngineState,
859    ) -> HashMap<String, Value> {
860        let mut result = HashMap::new();
861
862        for overlay_name in self.active_overlays.iter().rev() {
863            if overlay_name == excluded_overlay_name {
864                continue;
865            }
866            if let Some(env_names) = self.env_hidden.get(overlay_name) {
867                for n in env_names {
868                    if result.contains_key(n.as_str()) {
869                        continue;
870                    }
871                    // get env value.
872                    if let Some(Some(v)) = engine_state
873                        .env_vars
874                        .get(overlay_name)
875                        .map(|env_vars| env_vars.get(n))
876                    {
877                        result.insert(n.as_str().to_string(), v.clone());
878                    }
879                }
880            }
881        }
882        result
883    }
884
885    /// Same as get_env_vars, but returns only the names as a HashSet
886    pub fn get_env_var_names(&self, engine_state: &EngineState) -> HashSet<String> {
887        let mut result = HashSet::new();
888
889        for active_overlay in self.active_overlays.iter() {
890            if let Some(env_vars) = engine_state.env_vars.get(active_overlay) {
891                result.extend(
892                    env_vars
893                        .keys()
894                        .filter(|k| {
895                            if let Some(env_hidden) = self.env_hidden.get(active_overlay) {
896                                !env_hidden.contains(*k)
897                            } else {
898                                // nothing has been hidden in this overlay
899                                true
900                            }
901                        })
902                        .map(|k| k.as_str().to_string())
903                        .collect::<HashSet<String>>(),
904                );
905            }
906        }
907
908        for scope in &self.env_vars {
909            for active_overlay in self.active_overlays.iter() {
910                if let Some(env_vars) = scope.get(active_overlay) {
911                    result.extend(
912                        env_vars
913                            .keys()
914                            .map(|k| k.as_str().to_string())
915                            .collect::<HashSet<String>>(),
916                    );
917                }
918            }
919        }
920
921        result
922    }
923
924    /// Get an environment variable's existing spelling, if any.
925    pub fn get_env_var_name<'a>(&self, engine_state: &EngineState, name: &'a str) -> Cow<'a, str> {
926        self.env_vars
927            .iter()
928            .rev()
929            .chain(std::iter::once(&engine_state.env_vars))
930            .flat_map(|overlays| {
931                self.active_overlays
932                    .iter()
933                    .rev()
934                    .filter_map(|overlay| overlays.get(overlay))
935            })
936            .find_map(|map| {
937                if map.contains_key(&EnvName::from(name)) {
938                    map.keys()
939                        .find(|key| env_var_eq(key.as_str(), name))
940                        .map(|key| Cow::Owned(key.as_str().to_owned()))
941                } else {
942                    None
943                }
944            })
945            .unwrap_or(Cow::Borrowed(name))
946    }
947
948    pub fn get_env_var<'a>(
949        &'a self,
950        engine_state: &'a EngineState,
951        name: &str,
952    ) -> Option<&'a Value> {
953        let env_name = EnvName::from(name);
954
955        for scope in self.env_vars.iter().rev() {
956            for active_overlay in self.active_overlays.iter().rev() {
957                if let Some(env_vars) = scope.get(active_overlay)
958                    && let Some(v) = env_vars.get(&env_name)
959                {
960                    return Some(v);
961                }
962            }
963        }
964
965        for active_overlay in self.active_overlays.iter().rev() {
966            if !self.is_env_hidden_in_overlay(active_overlay, &env_name)
967                && let Some(env_vars) = engine_state.env_vars.get(active_overlay)
968                && let Some(v) = env_vars.get(&env_name)
969            {
970                return Some(v);
971            }
972        }
973        None
974    }
975
976    pub fn has_env_var(&self, engine_state: &EngineState, name: &str) -> bool {
977        let env_name = EnvName::from(name);
978
979        for scope in self.env_vars.iter().rev() {
980            for active_overlay in self.active_overlays.iter().rev() {
981                if let Some(env_vars) = scope.get(active_overlay)
982                    && env_vars.contains_key(&env_name)
983                {
984                    return true;
985                }
986            }
987        }
988
989        for active_overlay in self.active_overlays.iter().rev() {
990            if !self.is_env_hidden_in_overlay(active_overlay, &env_name)
991                && let Some(env_vars) = engine_state.env_vars.get(active_overlay)
992                && env_vars.contains_key(&env_name)
993            {
994                return true;
995            }
996        }
997
998        false
999    }
1000
1001    /// Removes `name` from the stack. If it was not on the stack and lives in `engine_state`,
1002    /// marks it hidden in `env_hidden`. Returns `true` if the variable was found and removed.
1003    ///
1004    /// Use this for temporary bookkeeping removals (e.g. `FILE_PWD`, canary variables) where
1005    /// the goal is to clean up a stack-level value without necessarily hiding the engine-state
1006    /// baseline. Use [`Self::hide_env_var`] when the intent is to make the variable invisible
1007    /// to subsequent lookups (e.g. `hide-env`).
1008    pub fn remove_env_var(&mut self, engine_state: &EngineState, name: &str) -> bool {
1009        let env_name = EnvName::from(name);
1010
1011        self.remove_env_var_from_stack(&env_name)
1012            || self.hide_engine_state_env_var(engine_state, &env_name)
1013    }
1014
1015    /// Removes `env_name` from all stack scopes and returns `true` if it was found.
1016    /// Does not affect `env_hidden`; use [`Self::hide_env_var`] for full hiding semantics.
1017    fn remove_env_var_from_stack(&mut self, env_name: &EnvName) -> bool {
1018        self.env_vars
1019            .iter_mut()
1020            .rev()
1021            .map(Arc::make_mut)
1022            .find_map(|scope| {
1023                self.active_overlays
1024                    .iter()
1025                    .rev()
1026                    .find_map(|active_overlay| scope.get_mut(active_overlay)?.remove(env_name))
1027            })
1028            .is_some()
1029    }
1030
1031    /// Marks `env_name` as hidden in `env_hidden` for the active overlay where it exists in
1032    /// `engine_state`.
1033    ///
1034    /// Returns `true` only when the baseline variable exists and was newly hidden.
1035    fn hide_engine_state_env_var(
1036        &mut self,
1037        engine_state: &EngineState,
1038        env_name: &EnvName,
1039    ) -> bool {
1040        let overlay_containing_env_var = self.active_overlays.iter().rev().find(|active_overlay| {
1041            engine_state
1042                .env_vars
1043                .get(active_overlay.as_str())
1044                .is_some_and(|env_vars| env_vars.contains_key(env_name))
1045        });
1046
1047        let Some(overlay_containing_env_var) = overlay_containing_env_var else {
1048            return false;
1049        };
1050
1051        let env_hidden = Arc::make_mut(&mut self.env_hidden);
1052
1053        if env_hidden
1054            .get(overlay_containing_env_var.as_str())
1055            .is_some_and(|hidden_vars| hidden_vars.contains(env_name))
1056        {
1057            return false;
1058        }
1059
1060        env_hidden
1061            .entry(overlay_containing_env_var.clone())
1062            .or_default()
1063            .insert(env_name.clone());
1064        true
1065    }
1066
1067    /// Records that `env_name` has been hidden in the active overlay and returns `false` if it
1068    /// was already recorded as hidden there.
1069    fn record_env_var_hide_in_active_overlay(&mut self, env_name: &EnvName) -> bool {
1070        let Some(active_overlay) = self.active_overlays.last().cloned() else {
1071            return false;
1072        };
1073
1074        Arc::make_mut(&mut self.env_hide_history)
1075            .entry(active_overlay)
1076            .or_default()
1077            .insert(env_name.clone())
1078    }
1079
1080    fn is_env_var_hide_recorded(&self, env_name: &EnvName) -> bool {
1081        self.active_overlays
1082            .iter()
1083            .rev()
1084            .filter_map(|overlay| self.env_hide_history.get(overlay))
1085            .any(|hidden_vars| hidden_vars.contains(env_name))
1086    }
1087
1088    fn is_env_hidden_in_overlay(&self, overlay: &str, env_name: &EnvName) -> bool {
1089        self.env_hidden
1090            .get(overlay)
1091            .is_some_and(|hidden_vars| hidden_vars.contains(env_name))
1092    }
1093
1094    /// Returns `true` if `name` was hidden in this stack context (e.g. by `hide-env`), either by
1095    /// masking an `engine_state` baseline value or by removing a stack-level value.
1096    ///
1097    /// A variable that was re-added after being hidden is still reported as hidden here, so only
1098    /// use this after a failed lookup to distinguish "hidden" from "never set".
1099    pub fn is_env_var_hidden(&self, name: &str) -> bool {
1100        let env_name = EnvName::from(name);
1101
1102        self.active_overlays
1103            .iter()
1104            .rev()
1105            .any(|overlay| self.is_env_hidden_in_overlay(overlay, &env_name))
1106            || self.is_env_var_hide_recorded(&env_name)
1107    }
1108
1109    /// Hides `name` so it is no longer visible to subsequent lookups. Removes it from the stack
1110    /// and, if no stack shadowing remains, also marks the `engine_state` baseline as hidden in
1111    /// `env_hidden`. Returns `true` if the variable was found.
1112    ///
1113    /// This is the correct method for `hide-env` and `redirect_env`; it ensures that a variable
1114    /// set in engine_state (from a previous REPL merge) cannot be seen after hiding even when a
1115    /// stack-level override (e.g. an empty-string assignment) was present at hide time.
1116    pub fn hide_env_var(&mut self, engine_state: &EngineState, name: &str) -> bool {
1117        let env_name = EnvName::from(name);
1118
1119        // Re-hiding the same env var in the same scope should report not found.
1120        if self.is_env_var_hide_recorded(&env_name) {
1121            return false;
1122        }
1123
1124        if self.remove_env_var_from_stack(&env_name) {
1125            self.record_env_var_hide_in_active_overlay(&env_name);
1126
1127            if !self.has_env_var_in_stack(&env_name) {
1128                self.hide_engine_state_env_var(engine_state, &env_name);
1129            }
1130            return true;
1131        }
1132
1133        if self.hide_engine_state_env_var(engine_state, &env_name) {
1134            self.record_env_var_hide_in_active_overlay(&env_name);
1135            return true;
1136        }
1137
1138        false
1139    }
1140
1141    /// Returns `true` if `name` exists in any stack scope (without consulting `engine_state`).
1142    fn has_env_var_in_stack(&self, name: &EnvName) -> bool {
1143        self.env_vars.iter().rev().any(|scope| {
1144            self.active_overlays
1145                .iter()
1146                .rev()
1147                .filter_map(|active_overlay| scope.get(active_overlay))
1148                .any(|env_vars| env_vars.contains_key(name))
1149        })
1150    }
1151
1152    pub fn has_env_overlay(&self, name: &str, engine_state: &EngineState) -> bool {
1153        for scope in self.env_vars.iter().rev() {
1154            if scope.contains_key(name) {
1155                return true;
1156            }
1157        }
1158
1159        engine_state.env_vars.contains_key(name)
1160    }
1161
1162    pub fn is_overlay_active(&self, name: &str) -> bool {
1163        self.active_overlays.iter().any(|n| n == name)
1164    }
1165
1166    pub fn add_overlay(&mut self, name: String) {
1167        self.active_overlays.retain(|o| o != &name);
1168        self.active_overlays.push(name);
1169    }
1170
1171    pub fn remove_overlay(&mut self, name: &str) {
1172        self.active_overlays.retain(|o| o != name);
1173    }
1174
1175    /// Returns the [`OutDest`] to use for the current command's stdout.
1176    ///
1177    /// This will be the pipe redirection if one is set,
1178    /// otherwise it will be the current file redirection,
1179    /// otherwise it will be the process's stdout indicated by [`OutDest::Inherit`].
1180    pub fn stdout(&self) -> &OutDest {
1181        self.out_dest.stdout()
1182    }
1183
1184    /// Returns the [`OutDest`] to use for the current command's stderr.
1185    ///
1186    /// This will be the pipe redirection if one is set,
1187    /// otherwise it will be the current file redirection,
1188    /// otherwise it will be the process's stderr indicated by [`OutDest::Inherit`].
1189    pub fn stderr(&self) -> &OutDest {
1190        self.out_dest.stderr()
1191    }
1192
1193    /// Returns the [`OutDest`] of the pipe redirection applied to the current command's stdout.
1194    pub fn pipe_stdout(&self) -> Option<&OutDest> {
1195        self.out_dest.pipe_stdout.as_ref()
1196    }
1197
1198    /// Returns the [`OutDest`] of the pipe redirection applied to the current command's stderr.
1199    pub fn pipe_stderr(&self) -> Option<&OutDest> {
1200        self.out_dest.pipe_stderr.as_ref()
1201    }
1202
1203    /// Returns the stdout destination of the innermost active custom-command invocation, if any.
1204    ///
1205    /// This is the destination of that command's *return value*. It stays stable even when
1206    /// intermediate expressions temporarily set [`OutDest::Value`] (e.g. `if (…)`), so callers
1207    /// can answer "where does *this command* go?" from anywhere in the body.
1208    ///
1209    /// See also [`Self::is_stdout_redirected`] and [`StackWithInvocation`].
1210    pub fn invocation_stdout(&self) -> Option<&OutDest> {
1211        self.out_dest.invocation_stdout.last()
1212    }
1213
1214    /// Whether the current custom command's return value is redirected away from display.
1215    ///
1216    /// Uses the active [`Self::invocation_stdout`] frame when inside a custom command so the
1217    /// answer is stable across nested `if` / `let` collection. Outside a custom command, falls
1218    /// back to [`Self::stdout`].
1219    ///
1220    /// Semantics match [`OutDest::is_redirected`] (only [`OutDest::Print`] is not redirected).
1221    /// This is the engine-side helper behind the `is-redirected` command.
1222    #[must_use]
1223    pub fn is_stdout_redirected(&self) -> bool {
1224        self.invocation_stdout()
1225            .unwrap_or_else(|| self.stdout())
1226            .is_redirected()
1227    }
1228
1229    /// Wrap this stack with an invocation-stdout frame for a custom command about to run.
1230    ///
1231    /// Push the destination of the call's *return value* (typically
1232    /// `caller_stack.stdout().clone()` after redirections are applied). The frame is popped when
1233    /// the returned [`StackWithInvocation`] is dropped.
1234    ///
1235    /// # Why a separate frame?
1236    ///
1237    /// Intermediate evaluation sets [`OutDest::Value`] via [`Self::start_collect_value`]. Without
1238    /// an invocation frame, queries like `is-redirected` inside `if (…)` would always see
1239    /// `Value` and report redirected—even when the enclosing custom command's result is printed.
1240    pub fn with_invocation_stdout(self, dest: OutDest) -> StackWithInvocation {
1241        StackWithInvocation::new(self, dest)
1242    }
1243
1244    /// Temporarily set the pipe stdout redirection to [`OutDest::Value`].
1245    ///
1246    /// This is used before evaluating an expression into a `Value`.
1247    pub fn start_collect_value(&mut self) -> StackCollectValueGuard<'_> {
1248        StackCollectValueGuard::new(self)
1249    }
1250
1251    /// Temporarily use the output redirections in the parent scope.
1252    ///
1253    /// This is used before evaluating an argument to a call.
1254    pub fn use_call_arg_out_dest(&mut self) -> StackCallArgGuard<'_> {
1255        StackCallArgGuard::new(self)
1256    }
1257
1258    /// Temporarily apply redirections to stdout and/or stderr.
1259    pub fn push_redirection(
1260        &mut self,
1261        stdout: Option<Redirection>,
1262        stderr: Option<Redirection>,
1263    ) -> StackIoGuard<'_> {
1264        StackIoGuard::new(self, stdout, stderr)
1265    }
1266
1267    /// Mark stdout for the last command as [`OutDest::Value`].
1268    ///
1269    /// This will irreversibly alter the output redirections, and so it only makes sense to use this on an owned `Stack`
1270    /// (which is why this function does not take `&mut self`).
1271    ///
1272    /// See [`Stack::start_collect_value`] which can temporarily set stdout as [`OutDest::Value`] for a mutable `Stack` reference.
1273    pub fn collect_value(mut self) -> Self {
1274        self.out_dest.pipe_stdout = Some(OutDest::Value);
1275        self.out_dest.pipe_stderr = None;
1276        self
1277    }
1278
1279    /// Mark both stdout and stderr for the last command as [`OutDest::Value`].
1280    ///
1281    /// This captures all output (stdout and stderr) instead of letting it inherit
1282    /// to the process's terminal. Useful for programmatic contexts like MCP servers
1283    /// where all output must be captured and returned.
1284    ///
1285    /// This will irreversibly alter the output redirections, and so it only makes sense to use this on an owned `Stack`
1286    /// (which is why this function does not take `&mut self`).
1287    pub fn capture_all(mut self) -> Self {
1288        self.out_dest.pipe_stdout = Some(OutDest::Value);
1289        self.out_dest.pipe_stderr = Some(OutDest::Value);
1290        self
1291    }
1292
1293    /// Clears any pipe and file redirections and resets stdout and stderr to [`OutDest::Inherit`].
1294    ///
1295    /// This will irreversibly reset the output redirections, and so it only makes sense to use this on an owned `Stack`
1296    /// (which is why this function does not take `&mut self`).
1297    pub fn reset_out_dest(mut self) -> Self {
1298        self.out_dest = StackOutDest::new();
1299        self
1300    }
1301
1302    /// Redirects stdout and stderr to [`OutDest::Null`], discarding all output.
1303    ///
1304    /// Use this for background evaluation tasks (e.g., completion) that must
1305    /// never write to the terminal while reedline owns it.
1306    pub fn suppress_output(mut self) -> Self {
1307        self.out_dest.stdout = OutDest::Null;
1308        self.out_dest.stderr = OutDest::Null;
1309        self
1310    }
1311
1312    /// Causes external processes spawned from this stack to detach from the
1313    /// controlling terminal. Empty input also receives `/dev/null` for stdin
1314    /// instead of inheriting the terminal.
1315    ///
1316    /// Use this together with [`suppress_output`](Self::suppress_output) for
1317    /// background tasks (e.g. completion threads).  Without it, subprocesses
1318    /// spawned by closure-based completers (carapace, fish_complete, etc.)
1319    /// inherit the live terminal fd and can race with reedline's reads,
1320    /// causing `Input/output error` (EIO). Piped stdin (candidate lists for
1321    /// `fzf`) is still detached so the child cannot open `/dev/tty`.
1322    pub fn suppress_stdin(mut self) -> Self {
1323        self.suppress_stdin = true;
1324        self
1325    }
1326
1327    /// Error if this stack is detached from the controlling terminal (see
1328    /// [`suppress_stdin`](Self::suppress_stdin), set on completion threads). Commands that grab
1329    /// the terminal (`input`, `input list`, `input listen`, `term query`) call this first so
1330    /// they decline instead of racing reedline for it; completers turn the error into a
1331    /// fallback. `span` points at the offending call.
1332    pub fn require_stdin(&self, span: Span) -> Result<(), ShellError> {
1333        if self.suppress_stdin {
1334            Err(ShellError::Generic(
1335                GenericError::new(
1336                    "Interactive input is unavailable in this context",
1337                    "this command reads from the terminal",
1338                    span,
1339                )
1340                .with_help(
1341                    "this stack is detached from the terminal (completion worker or MCP), so \
1342                     interactive commands like `input`, `input list`, `input listen`, and \
1343                     `term query` cannot run here",
1344                ),
1345            ))
1346        } else {
1347            Ok(())
1348        }
1349    }
1350
1351    /// Clears any pipe redirections, keeping the current stdout and stderr.
1352    ///
1353    /// This will irreversibly reset some of the output redirections, and so it only makes sense to use this on an owned `Stack`
1354    /// (which is why this function does not take `&mut self`).
1355    pub fn reset_pipes(mut self) -> Self {
1356        self.out_dest.pipe_stdout = None;
1357        self.out_dest.pipe_stderr = None;
1358        self
1359    }
1360
1361    /// Replaces the default stdout of the stack with a given file.
1362    ///
1363    /// This method configures the default stdout to redirect to a specified file.
1364    /// It is primarily useful for applications using `nu` as a language, where the stdout of
1365    /// external commands that are not explicitly piped can be redirected to a file.
1366    ///
1367    /// # Using Pipes
1368    ///
1369    /// For use in third-party applications pipes might be very useful as they allow using the
1370    /// stdout of external commands for different uses.
1371    /// For example the [`os_pipe`](https://docs.rs/os_pipe) crate provides an elegant way to
1372    /// access the stdout.
1373    ///
1374    /// ```
1375    /// # use std::{fs::File, io::{self, Read}, thread, error};
1376    /// # use nu_protocol::engine::Stack;
1377    /// #
1378    /// let (mut reader, writer) = os_pipe::pipe().unwrap();
1379    /// // Use a thread to avoid blocking the execution of the called command.
1380    /// let reader = thread::spawn(move || {
1381    ///     let mut buf: Vec<u8> = Vec::new();
1382    ///     reader.read_to_end(&mut buf)?;
1383    ///     Ok::<_, io::Error>(buf)
1384    /// });
1385    ///
1386    /// #[cfg(windows)]
1387    /// let file = std::os::windows::io::OwnedHandle::from(writer).into();
1388    /// #[cfg(unix)]
1389    /// let file = std::os::unix::io::OwnedFd::from(writer).into();
1390    ///
1391    /// let stack = Stack::new().stdout_file(file);
1392    ///
1393    /// // Execute some nu code.
1394    ///
1395    /// drop(stack); // drop the stack so that the writer will be dropped too
1396    /// let buf = reader.join().unwrap().unwrap();
1397    /// // Do with your buffer whatever you want.
1398    /// ```
1399    pub fn stdout_file(mut self, file: File) -> Self {
1400        self.out_dest.stdout = OutDest::File(Arc::new(file));
1401        self
1402    }
1403
1404    /// Replaces the default stderr of the stack with a given file.
1405    ///
1406    /// For more info, see [`stdout_file`](Self::stdout_file).
1407    pub fn stderr_file(mut self, file: File) -> Self {
1408        self.out_dest.stderr = OutDest::File(Arc::new(file));
1409        self
1410    }
1411
1412    /// Set the PWD environment variable to `path`.
1413    ///
1414    /// This method accepts `path` with trailing slashes, but they're removed
1415    /// before writing the value into PWD.
1416    pub fn set_cwd(&mut self, path: impl AsRef<std::path::Path>) -> Result<(), ShellError> {
1417        // Helper function to create a simple generic error.
1418        // Its messages are not especially helpful, but these errors don't occur often, so it's probably fine.
1419        fn error(msg: &str) -> Result<(), ShellError> {
1420            Err(ShellError::Generic(GenericError::new_internal(
1421                msg.to_string(),
1422                "",
1423            )))
1424        }
1425
1426        let path = path.as_ref();
1427
1428        if !path.is_absolute() {
1429            if let Some(Component::Prefix(_)) = path.components().next() {
1430                return Err(ShellError::Generic(
1431                    GenericError::new_internal("Cannot set $env.PWD to a prefix-only path", "")
1432                        .with_help(format!(
1433                            "Try to use {}{MAIN_SEPARATOR} instead",
1434                            path.display()
1435                        )),
1436                ));
1437            }
1438
1439            error("Cannot set $env.PWD to a non-absolute path")
1440        } else if !path.exists() {
1441            error("Cannot set $env.PWD to a non-existent directory")
1442        } else if !path.is_dir() {
1443            error("Cannot set $env.PWD to a non-directory")
1444        } else {
1445            // Strip trailing slashes, if any.
1446            let path = nu_path::strip_trailing_slash(path);
1447            let value = Value::string(path.to_string_lossy(), Span::unknown());
1448            self.add_env_var("PWD".into(), value);
1449            Ok(())
1450        }
1451    }
1452}
1453
1454#[cfg(test)]
1455mod test {
1456    use std::sync::Arc;
1457
1458    use crate::{Span, Value, VarId, engine::EngineState};
1459
1460    use super::Stack;
1461
1462    #[test]
1463    fn test_children_see_inner_values() {
1464        let mut original = Stack::new();
1465        original.add_var(VarId::new(0), Value::test_string("hello"));
1466
1467        let cloned = Stack::with_parent(Arc::new(original));
1468        assert_eq!(
1469            cloned.get_var(VarId::new(0), Span::test_data()),
1470            Ok(Value::test_string("hello"))
1471        );
1472    }
1473
1474    #[test]
1475    fn test_children_dont_see_deleted_values() {
1476        let mut original = Stack::new();
1477        original.add_var(VarId::new(0), Value::test_string("hello"));
1478
1479        let mut cloned = Stack::with_parent(Arc::new(original));
1480        cloned.remove_var(VarId::new(0));
1481
1482        assert_eq!(
1483            cloned.get_var(VarId::new(0), Span::test_data()),
1484            Err(crate::ShellError::VariableNotFoundAtRuntime {
1485                span: Span::test_data()
1486            })
1487        );
1488    }
1489
1490    #[test]
1491    fn test_children_changes_override_parent() {
1492        let mut original = Stack::new();
1493        original.add_var(VarId::new(0), Value::test_string("hello"));
1494
1495        let mut cloned = Stack::with_parent(Arc::new(original));
1496        cloned.add_var(VarId::new(0), Value::test_string("there"));
1497        assert_eq!(
1498            cloned.get_var(VarId::new(0), Span::test_data()),
1499            Ok(Value::test_string("there"))
1500        );
1501
1502        cloned.remove_var(VarId::new(0));
1503        // the underlying value shouldn't magically re-appear
1504        assert_eq!(
1505            cloned.get_var(VarId::new(0), Span::test_data()),
1506            Err(crate::ShellError::VariableNotFoundAtRuntime {
1507                span: Span::test_data()
1508            })
1509        );
1510    }
1511    #[test]
1512    fn test_children_changes_persist_in_offspring() {
1513        let mut original = Stack::new();
1514        original.add_var(VarId::new(0), Value::test_string("hello"));
1515
1516        let mut cloned = Stack::with_parent(Arc::new(original));
1517        cloned.add_var(VarId::new(1), Value::test_string("there"));
1518
1519        cloned.remove_var(VarId::new(0));
1520        let cloned = Stack::with_parent(Arc::new(cloned));
1521
1522        assert_eq!(
1523            cloned.get_var(VarId::new(0), Span::test_data()),
1524            Err(crate::ShellError::VariableNotFoundAtRuntime {
1525                span: Span::test_data()
1526            })
1527        );
1528
1529        assert_eq!(
1530            cloned.get_var(VarId::new(1), Span::test_data()),
1531            Ok(Value::test_string("there"))
1532        );
1533    }
1534
1535    #[test]
1536    fn test_merging_children_back_to_parent() {
1537        let mut original = Stack::new();
1538        let engine_state = EngineState::new();
1539        original.add_var(VarId::new(0), Value::test_string("hello"));
1540
1541        let original_arc = Arc::new(original);
1542        let mut cloned = Stack::with_parent(original_arc.clone());
1543        cloned.add_var(VarId::new(1), Value::test_string("there"));
1544
1545        cloned.remove_var(VarId::new(0));
1546
1547        cloned.add_env_var(
1548            "ADDED_IN_CHILD".to_string(),
1549            Value::test_string("New Env Var"),
1550        );
1551
1552        let original = Stack::with_changes_from_child(original_arc, cloned);
1553
1554        assert_eq!(
1555            original.get_var(VarId::new(0), Span::test_data()),
1556            Err(crate::ShellError::VariableNotFoundAtRuntime {
1557                span: Span::test_data()
1558            })
1559        );
1560
1561        assert_eq!(
1562            original.get_var(VarId::new(1), Span::test_data()),
1563            Ok(Value::test_string("there"))
1564        );
1565
1566        assert_eq!(
1567            original
1568                .get_env_var(&engine_state, "ADDED_IN_CHILD")
1569                .cloned(),
1570            Some(Value::test_string("New Env Var")),
1571        );
1572    }
1573
1574    #[test]
1575    fn test_get_var_mut_local_in_place() {
1576        use crate::ast::PathMember;
1577        use crate::casing::Casing;
1578        use crate::record;
1579
1580        let mut stack = Stack::new();
1581        let var_id = VarId::new(0);
1582        stack.add_var(
1583            var_id,
1584            Value::test_record(record! { "a" => Value::test_int(1) }),
1585        );
1586
1587        let path = vec![PathMember::test_string("a", false, Casing::Sensitive)];
1588        stack
1589            .upsert_var_cell_path(var_id, &path, Value::test_int(2), Span::test_data())
1590            .expect("upsert should succeed");
1591
1592        assert_eq!(
1593            stack.get_var(var_id, Span::test_data()),
1594            Ok(Value::test_record(record! { "a" => Value::test_int(2) }))
1595        );
1596        // Still a single local binding (no extra shadow entries).
1597        assert_eq!(stack.vars.len(), 1);
1598    }
1599
1600    #[test]
1601    fn test_get_var_mut_pulls_from_parent() {
1602        use crate::ast::PathMember;
1603        use crate::casing::Casing;
1604        use crate::record;
1605
1606        let mut parent = Stack::new();
1607        let var_id = VarId::new(0);
1608        parent.add_var(
1609            var_id,
1610            Value::test_record(record! { "a" => Value::test_int(1) }),
1611        );
1612
1613        let mut child = Stack::with_parent(Arc::new(parent));
1614        assert!(child.vars.is_empty());
1615
1616        let path = vec![PathMember::test_string("a", false, Casing::Sensitive)];
1617        child
1618            .upsert_var_cell_path(var_id, &path, Value::test_int(9), Span::test_data())
1619            .expect("upsert should succeed");
1620
1621        // Value was pulled into the child frame, then mutated.
1622        assert_eq!(child.vars.len(), 1);
1623        assert_eq!(
1624            child.get_var(var_id, Span::test_data()),
1625            Ok(Value::test_record(record! { "a" => Value::test_int(9) }))
1626        );
1627
1628        // Second mutation hits the local copy.
1629        child
1630            .upsert_var_cell_path(var_id, &path, Value::test_int(10), Span::test_data())
1631            .expect("second upsert should succeed");
1632        assert_eq!(child.vars.len(), 1);
1633        assert_eq!(
1634            child.get_var(var_id, Span::test_data()),
1635            Ok(Value::test_record(record! { "a" => Value::test_int(10) }))
1636        );
1637    }
1638
1639    #[test]
1640    fn test_upsert_var_cell_path_missing_and_deleted() {
1641        use crate::ast::PathMember;
1642        use crate::casing::Casing;
1643
1644        let mut stack = Stack::new();
1645        let var_id = VarId::new(0);
1646        let path = vec![PathMember::test_string("a", false, Casing::Sensitive)];
1647
1648        assert!(matches!(
1649            stack.upsert_var_cell_path(var_id, &path, Value::test_int(1), Span::test_data()),
1650            Err(crate::ShellError::VariableNotFoundAtRuntime { .. })
1651        ));
1652
1653        let mut parent = Stack::new();
1654        parent.add_var(var_id, Value::test_int(1));
1655        let mut child = Stack::with_parent(Arc::new(parent));
1656        child.remove_var(var_id);
1657
1658        assert!(matches!(
1659            child.upsert_var_cell_path(var_id, &path, Value::test_int(2), Span::test_data()),
1660            Err(crate::ShellError::VariableNotFoundAtRuntime { .. })
1661        ));
1662        assert!(child.get_var_mut(var_id).is_none());
1663    }
1664}