vce-shell 0.1.1

VCE Shell layer: command language, builtins, execution coordination
Documentation
//! The [`Shell`] trait: the interface every shell implementation exposes.
//!
//! The Shell layer is a command language plus execution
//! coordination. Concrete shells — Bash and Zsh on Unix, PowerShell and
//! cmd on Windows — differ in their language flavor, prompt style, and
//! builtins, but the application drives them through this trait, so a VM
//! boots into whichever shell its OS declares (or the user selects with
//! `--shell`).
//!
//! The trait is deliberately OS-agnostic: shells may sit on a Unix OS
//! ([`Bash`](crate::bash::Bash), [`Zsh`](crate::zsh::Zsh)) or on Windows
//! ([`PowerShell`](crate::powershell::PowerShell),
//! [`Cmd`](crate::cmd::Cmd)), so the application (changing from Zsh → Bash
//! changes shell behavior while preserving OS state) treats them
//! uniformly.

use engine::{Engine, Input, Output, Terminal, Timestamp, VirtualPath};
use os::ExitStatus;

/// A shell implementation.
///
/// Implementations own the session's working directory, environment, and
/// command runtime; the application owns input reading and screen state.
pub trait Shell {
    /// The shell's name (`"bash"`, `"zsh"`, `"powershell"`, ...).
    fn name(&self) -> &'static str;

    /// The engine this shell operates on.
    fn engine(&self) -> &Engine;

    /// The acting identity (used for filesystem lookups, for example tab
    /// completion).
    fn actor(&self) -> engine::ActorId;

    /// The shell environment (variables, `PATH`, `HOME`, ...).
    fn environment(&self) -> &os::Environment;

    /// The boot time of the underlying OS (used for login banners).
    fn boot_time(&self) -> Timestamp;

    /// The virtual host name (from `/etc/hostname` or the OS equivalent).
    fn hostname(&self) -> String;

    /// The current working directory.
    fn cwd(&self) -> &VirtualPath;

    /// The prompt string, ending with a trailing space.
    ///
    /// `hostname` is the virtual host name (read from `/etc/hostname` or
    /// the equivalent by the application).
    fn prompt(&self, hostname: &str) -> String;

    /// The banner printed before the first prompt, or `None` when the
    /// shell prints none. Unix shells print the `Last login` line; the
    /// Windows shells print their startup banners.
    fn banner(&self) -> Option<String>;

    /// Reports the terminal size, exported as `COLUMNS`/`LINES` so commands
    /// (for example `ls`) lay out against the live console width.
    ///
    /// The application calls this at session start and whenever the host
    /// terminal is resized.
    fn set_terminal_size(&mut self, rows: u16, cols: u16);

    /// Executes a line of shell input.
    fn execute(
        &mut self,
        line: &str,
        stdin: &mut dyn Input,
        stdout: &mut dyn Output,
        stderr: &mut dyn Output,
    ) -> ExitStatus;

    /// Executes a line with an optional terminal.
    fn execute_with_terminal(
        &mut self,
        line: &str,
        stdin: &mut dyn Input,
        stdout: &mut dyn Output,
        stderr: &mut dyn Output,
        terminal: Option<&mut dyn Terminal>,
    ) -> ExitStatus;

    /// Takes a pending session-exit request (`exit [N]`), if any.
    ///
    /// The application calls this after executing a line: when it returns
    /// `Some`, the session is over — stop reading input and use the carried
    /// status as the process exit code. This keeps exit semantics inside
    /// the shell language (`exit`, `exit 3`, scripts) instead of the
    /// application matching command strings.
    fn take_exit_status(&mut self) -> Option<ExitStatus>;

    /// The command history: exactly the lines the interactive application
    /// recorded through [`Shell::record_history`].
    fn history(&self) -> &[String];

    /// Records one completed command line.
    ///
    /// The interactive application calls this once per executed line — the
    /// whole of a multi-line construct, not its continuation chunks — so
    /// `history` and the `history` builtin show what the user actually
    /// typed. The shell owns the list; the application's prompt editor
    /// reads it for up/down-arrow recall.
    fn record_history(&mut self, line: &str);

    /// Whether the input is an incomplete construct that needs more lines
    /// (for example a here-document or an unclosed `if`).
    fn needs_continuation(&self, input: &str) -> bool {
        let _ = input;
        false
    }
}