newt-tui 0.8.0

//! #1746 feasibility spike — can a Windows **ConPTY** back the cockpit the way
//! a unix pty backs it today?
//!
//! The unix cockpit ([`super::pty`]) swings the process's *own* fd 1/2 onto a
//! pty slave with `dup2` and reads the master **in the same process**. This
//! module tests, on a real Windows box and on CI, whether that shape is
//! reachable with ConPTY, and — crucially — whether a hosted child's *own*
//! stdout/stderr actually traverse the pseudoconsole (the earlier version of
//! this probe only ever observed conhost's init bytes, which is NOT the same
//! thing).
//!
//! ## PROVEN by the probes below
//!
//! - **In-process self-capture is impossible (Probe A).** Redirecting our own
//!   `STD_OUTPUT_HANDLE` onto a pipe makes it `FILE_TYPE_PIPE` and
//!   `GetConsoleMode` fails — `is_terminal()` flips to false, flipping the
//!   cockpit's behaviour gates. A process cannot attach itself to a ConPTY it
//!   created, so there is no `dup2`-your-own-stdout analogue.
//!
//! - **A ConPTY-hosted child's stdout AND stderr traverse the pty, and it sees
//!   a terminal (Probe B).** With the child hosted under `CreatePseudoConsole` +
//!   `PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE`, the child's own `println!`/`eprintln!`
//!   come back through the pseudoconsole output (not the parent's stdio), the
//!   child sees `is_terminal() == true` for both, and the bytes parse through
//!   the existing #1744 [`super::ansi`] scanner.
//!
//! ## The load-bearing requirement this probe discovered
//!
//! ConPTY only reassigns the child's std handles to the pty when the **host
//! presents CONSOLE std handles**. Under pipe stdio (cargo test, mintty, a
//! service) the child otherwise inherits the parent's *pipe* and never touches
//! the pty. So the host here first acquires a real console
//! (`FreeConsole`→`AllocConsole`→repoint std handles to `CONOUT$`/`CONIN$`).
//! Because that mutates process-global console state, the host runs in a
//! **separate subprocess** the test spawns — the test process is left untouched.
//! (A real `newt.exe` run interactively already owns a console; when its stdout
//! is redirected the cockpit does not engage at all — `is_terminal()` is false.)
//!
//! See `docs/decisions/windows_cockpit_conpty.md` for what this does and does
//! NOT decide about the cockpit's architecture.
//!
//! ## Why every probe is `#[ignore]`d
//!
//! These are real-resource EVIDENCE probes, not unit tests: Probe A swaps this
//! process's own global `STD_OUTPUT_HANDLE`, and Probes B/C spawn a ConPTY host
//! subprocess and touch the filesystem. In the parallel per-PR `cargo test
//! --workspace` run, Probe A's in-process handle swap corrupts libtest's own
//! stdout while the ~1300 sibling tests are mid-flight — the harness's result
//! channel dies with a `SendError` / `BrokenPipe` and the whole binary fails
//! (`#[serial]` only orders same-key tests, so it does not help here). Per the
//! testing-tiers doctrine (CLAUDE.md) such tests run single-threaded, isolated,
//! never in the per-PR parallel suite. They are therefore `#[ignore]`d — like
//! the `conpty_host`/`conpty_child` roles below — and exercised only by the
//! dedicated single-threaded CI step (`.github/workflows/ci.yml`, "ConPTY
//! feasibility probe evidence"), which passes `--include-ignored`.

#[cfg(test)]
mod probes {
    use crate::cockpit::ansi::TranscriptStream;
    use std::ffi::c_void;
    use std::io::{IsTerminal, Write};
    use windows_sys::Win32::Foundation::{CloseHandle, GetLastError, HANDLE};
    use windows_sys::Win32::Storage::FileSystem::{
        CreateFileW, GetFileType, ReadFile, FILE_SHARE_READ, FILE_SHARE_WRITE, FILE_TYPE_CHAR,
        FILE_TYPE_PIPE, OPEN_EXISTING,
    };
    use windows_sys::Win32::System::Console::{
        AllocConsole, ClosePseudoConsole, CreatePseudoConsole, FreeConsole, GetConsoleMode,
        GetStdHandle, SetStdHandle, COORD, HPCON, STD_ERROR_HANDLE, STD_INPUT_HANDLE,
        STD_OUTPUT_HANDLE,
    };
    use windows_sys::Win32::System::Pipes::CreatePipe;
    use windows_sys::Win32::System::Threading::{
        CreateProcessW, DeleteProcThreadAttributeList, GetExitCodeProcess,
        InitializeProcThreadAttributeList, UpdateProcThreadAttribute, WaitForSingleObject,
        EXTENDED_STARTUPINFO_PRESENT, INFINITE, PROCESS_INFORMATION,
        PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE, STARTUPINFOEXW,
    };

    /// Selects the re-exec role. Unset = the ordinary test.
    const ROLE_ENV: &str = "NEWT_CONPTY_ROLE";
    /// Where the host writes the captured pty bytes for the parent test to read.
    const RESULT_ENV: &str = "NEWT_CONPTY_RESULT";
    /// The child echoes these to stdout / stderr, tagged with its own
    /// `is_terminal()` reading, so the parent can prove BOTH that the child saw a
    /// terminal AND that the bytes travelled through the pty.
    const OUT_MARKER: &str = "NEWT_CONPTY_STDOUT_7Z";
    const ERR_MARKER: &str = "NEWT_CONPTY_STDERR_7Z";

    fn create_pipe() -> (HANDLE, HANDLE) {
        let mut read: HANDLE = std::ptr::null_mut();
        let mut write: HANDLE = std::ptr::null_mut();
        // SAFETY: CreatePipe fills two handles we own; null attributes = default.
        let ok = unsafe { CreatePipe(&mut read, &mut write, std::ptr::null(), 0) };
        assert!(ok != 0, "CreatePipe failed: {}", last_error());
        (read, write)
    }

    fn last_error() -> u32 {
        // SAFETY: GetLastError reads thread-local state, no pointers.
        unsafe { GetLastError() }
    }

    fn close(h: HANDLE) {
        if !h.is_null() {
            // SAFETY: closing a handle we own.
            unsafe {
                CloseHandle(h);
            }
        }
    }

    /// Blocking read of a handle until EOF.
    fn read_to_end(handle: HANDLE) -> Vec<u8> {
        let mut out = Vec::new();
        let mut buf = [0u8; 4096];
        loop {
            let mut n: u32 = 0;
            // SAFETY: read into a buffer we own from a handle we own.
            let ok = unsafe {
                ReadFile(
                    handle,
                    buf.as_mut_ptr(),
                    buf.len() as u32,
                    &mut n,
                    std::ptr::null_mut(),
                )
            };
            if ok == 0 || n == 0 {
                break;
            }
            out.extend_from_slice(&buf[..n as usize]);
        }
        out
    }

    /// Open a console pseudo-file (`CONOUT$` / `CONIN$`) as a HANDLE.
    fn open_con(name: &str) -> HANDLE {
        let wide: Vec<u16> = name.encode_utf16().chain(std::iter::once(0)).collect();
        // SAFETY: CreateFileW on a console alias, sharing read+write.
        unsafe {
            CreateFileW(
                wide.as_ptr(),
                0xC000_0000, // GENERIC_READ | GENERIC_WRITE
                FILE_SHARE_READ | FILE_SHARE_WRITE,
                std::ptr::null(),
                OPEN_EXISTING,
                0,
                std::ptr::null_mut(),
            )
        }
    }

    fn self_exe() -> std::path::PathBuf {
        std::env::current_exe().expect("current_exe")
    }

    fn result_path() -> std::path::PathBuf {
        std::env::temp_dir().join("newt_conpty_probe_result.bin")
    }

    /// Probe A: the only in-process "capture my own stdout" primitive is a pipe,
    /// and a pipe is not a console — so `is_terminal()` would flip, exactly as a
    /// pipe would on unix. The unix in-process fd-swap has no Windows analogue.
    #[serial_test::serial(tty_arbiter)]
    #[ignore = "real-resource evidence probe: swaps this process's global STD_OUTPUT_HANDLE, so it must run single-threaded in the dedicated CI step, not the parallel workspace suite"]
    #[test]
    fn probe_a_pipe_stdout_is_not_a_console() {
        let (read, write) = create_pipe();
        // SAFETY: save the real stdout, point it at the pipe, restore after.
        let saved = unsafe { GetStdHandle(STD_OUTPUT_HANDLE) };
        let set = unsafe { SetStdHandle(STD_OUTPUT_HANDLE, write) };
        assert!(set != 0, "SetStdHandle failed: {}", last_error());
        // SAFETY: GetFileType / GetConsoleMode on the pipe write end we own.
        let file_type = unsafe { GetFileType(write) };
        let mut mode = 0u32;
        let console_ok = unsafe { GetConsoleMode(write, &mut mode) };
        // SAFETY: put the real stdout handle back before asserting.
        unsafe {
            SetStdHandle(STD_OUTPUT_HANDLE, saved);
        }
        close(read);
        close(write);

        assert_eq!(
            file_type, FILE_TYPE_PIPE,
            "a redirected-to-pipe stdout is a pipe, not FILE_TYPE_CHAR ({FILE_TYPE_CHAR})"
        );
        assert_eq!(
            console_ok, 0,
            "GetConsoleMode must FAIL on a pipe — is_terminal() would be false"
        );
    }

    /// Probe B: a ConPTY-hosted child's OWN stdout AND stderr traverse the
    /// pseudoconsole, and it sees a terminal. The host (which mutates
    /// process-global console state) runs in a spawned subprocess so this test
    /// process is untouched; it captures the pty bytes to a file we read here.
    /// Then those exact bytes go through the existing #1744 scanner.
    #[serial_test::serial(tty_arbiter)]
    #[ignore = "real-resource evidence probe: spawns a ConPTY host subprocess, so it must run single-threaded in the dedicated CI step, not the parallel workspace suite"]
    #[test]
    fn probe_b_child_stdout_and_stderr_traverse_the_conpty() {
        let result = result_path();
        let _ = std::fs::remove_file(&result);

        // Spawn the host role. Its stdout/stderr are irrelevant (it detaches its
        // console); it writes the captured pty bytes to RESULT.
        let status = std::process::Command::new(self_exe())
            .args([
                "--exact",
                "cockpit::conpty_probe::probes::conpty_host",
                "--ignored",
                "--nocapture",
                "--test-threads=1",
            ])
            .env(ROLE_ENV, "host")
            .env(RESULT_ENV, &result)
            .status()
            .expect("spawn conpty host");
        assert!(status.success(), "host subprocess failed: {status:?}");

        let rendered = std::fs::read(&result).expect("host wrote no result file");
        let _ = std::fs::remove_file(&result);
        // The host prepends one ASCII status line, then the raw pty bytes.
        let split = rendered.iter().position(|&b| b == b'\n').unwrap_or(0);
        let header = String::from_utf8_lossy(&rendered[..split]).into_owned();
        let pty = &rendered[(split + 1).min(rendered.len())..];
        let text = String::from_utf8_lossy(pty);

        // If a runner cannot give the host a real console (AllocConsole), the
        // child can't be bound to the pty — skip rather than fail a spurious
        // red; the traversal is PROVEN wherever a console is available (locally
        // and on runners that grant one). The assertion below still fires
        // whenever setup succeeded, so a real regression is caught.
        if !header.contains("allocated=true") {
            eprintln!(
                "probe_b: host could not acquire a console on this runner ({header}); \
                 pty-traversal assertion skipped"
            );
            return;
        }

        // The child's OWN output — stdout and stderr, each tagged with its
        // is_terminal reading — must have come back THROUGH the pty.
        let want_out = format!("{OUT_MARKER}[tty=true]");
        let want_err = format!("{ERR_MARKER}[tty=true]");
        assert!(
            text.contains(&want_out),
            "child stdout must traverse the ConPTY as a terminal.\nheader: {header}\npty: {text:?}"
        );
        assert!(
            text.contains(&want_err),
            "child stderr must traverse the ConPTY as a terminal.\nheader: {header}\npty: {text:?}"
        );

        // Reuse proof: the real pty bytes parse through the #1744 scanner (odd
        // chunking exercises the escape/UTF-8 carry), the child's lines surface,
        // and the #3 allowlist drops the pseudoconsole's own private modes.
        let mut stream = TranscriptStream::new();
        let mut lines: Vec<String> = Vec::new();
        let mut passthrough: Vec<u8> = Vec::new();
        for chunk in pty.chunks(7) {
            let d = stream.feed(chunk);
            lines.extend(
                d.lines
                    .iter()
                    .map(|l| String::from_utf8_lossy(l).into_owned()),
            );
            passthrough.extend(d.passthrough);
        }
        lines.push(String::from_utf8_lossy(stream.partial()).into_owned());
        assert!(
            lines.iter().any(|l| l.contains(OUT_MARKER)),
            "ansi::TranscriptStream should surface the child's stdout line; got {lines:?}"
        );
        let pass = String::from_utf8_lossy(&passthrough);
        for banned in ["9001", "1004", "?25", "1049", "2004", "?7h", "?7l"] {
            assert!(
                !pass.contains(banned),
                "the #3 allowlist must drop the pseudoconsole's {banned} mode; passthrough={pass:?}"
            );
        }
    }

    /// HOST role (spawned by `probe_b`): acquire a real console, host the child
    /// under a ConPTY, capture the pty output, write it to RESULT. No-ops unless
    /// **Probe C — is a process-global console actually required?**
    ///
    /// Probe B's host acquires one (`FreeConsole` → `AllocConsole` → repoint
    /// std handles), and its child's output reaches the pty. That establishes
    /// the configuration WORKS; it does not establish the console is NECESSARY.
    /// The two differ, and the difference decides whether a Windows cockpit has
    /// to mutate process-global console state or can stay narrower.
    ///
    /// This runs the identical host path with that ONE step removed, from a
    /// parent whose own std handles are pipes (`cargo test` stdio) — the
    /// redirected-stdio case. Process creation is already the controlled kind
    /// the question asks about: `bInheritHandles = FALSE`, a zeroed
    /// `STARTUPINFOEXW` (so NO `STARTF_USESTDHANDLES` and NULL `hStd*`), and
    /// `PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE` as the only handle source.
    ///
    /// Both outcomes are informative, so this test does not presume one. It
    /// asserts the experiment genuinely ran, then records a machine-readable
    /// verdict line for the ADR:
    ///
    /// * `traversed` — the child's stdout AND stderr came back through the pty
    ///   with `is_terminal() == true`, and did NOT appear on the host's own
    ///   inherited stdio. The console requirement is an artifact of the tested
    ///   spawn configuration.
    /// * `leaked` — the markers appeared on the host's inherited pipes, i.e.
    ///   the child took the parent's redirected handles instead of the pty.
    /// * `absent` — neither; the child produced nothing either way.
    #[ignore = "real-resource evidence probe: spawns a ConPTY host subprocess, so it must run single-threaded in the dedicated CI step, not the parallel workspace suite"]
    #[test]
    fn probe_c_is_a_process_global_console_required() {
        let result = result_path().with_extension("nocon");
        let _ = std::fs::remove_file(&result);

        // `.output()` (not `.status()`) so the host's OWN stdio is captured:
        // that is how a leak through inherited redirected handles is seen.
        let out = std::process::Command::new(self_exe())
            .args([
                "--exact",
                "cockpit::conpty_probe::probes::conpty_host",
                "--ignored",
                "--nocapture",
                "--test-threads=1",
            ])
            .env(ROLE_ENV, "host-nocon")
            .env(RESULT_ENV, &result)
            .output()
            .expect("spawn conpty host (no console)");

        let host_stdio = format!(
            "{}{}",
            String::from_utf8_lossy(&out.stdout),
            String::from_utf8_lossy(&out.stderr)
        );
        let rendered = std::fs::read(&result).unwrap_or_default();
        let _ = std::fs::remove_file(&result);
        let split = rendered.iter().position(|&b| b == b'\n').unwrap_or(0);
        let header = String::from_utf8_lossy(&rendered[..split]).into_owned();
        let pty =
            String::from_utf8_lossy(&rendered[(split + 1).min(rendered.len())..]).into_owned();

        // The experiment must have RUN, whatever it found.
        assert!(
            out.status.success(),
            "host (no console) subprocess failed: {:?}\n{host_stdio}",
            out.status
        );
        assert!(
            header.contains("allocated=false"),
            "probe C must run WITHOUT acquiring a console; header: {header:?}"
        );
        assert!(
            header.contains("created=1"),
            "the ConPTY child must have been created for the result to mean \
             anything; header: {header:?}"
        );

        let want_out = format!("{OUT_MARKER}[tty=true]");
        let want_err = format!("{ERR_MARKER}[tty=true]");
        let through_pty = pty.contains(&want_out) && pty.contains(&want_err);
        let leaked = host_stdio.contains(OUT_MARKER) || host_stdio.contains(ERR_MARKER);

        let verdict = if through_pty && !leaked {
            "traversed"
        } else if leaked {
            "leaked"
        } else {
            "absent"
        };
        // Machine-readable, for the ADR to quote rather than paraphrase.
        println!("NEWT_CONPTY_PROBE_C verdict={verdict} header={header:?}");
        println!("NEWT_CONPTY_PROBE_C pty={pty:?}");
        println!("NEWT_CONPTY_PROBE_C host_stdio_has_markers={leaked}");

        // PIN the measured result. On 2026-08-19 CI this is `leaked`: without a
        // console the child takes the parent's inherited PIPES and its output
        // never reaches the pty — the pty carries only conhost's init bytes.
        // That is what makes the ADR's console requirement PROVEN rather than
        // inferred, so it is asserted, not merely printed.
        //
        // If this ever flips to `traversed`, the console requirement has become
        // an artifact of an older Windows/toolchain and the ADR must be revised
        // — which is exactly the regression this assertion exists to catch.
        assert_eq!(
            verdict, "leaked",
            "probe C measured {verdict}, not the recorded `leaked`. Re-open the \
             console question in docs/decisions/windows_cockpit_conpty.md.\n\
             header: {header}\npty: {pty:?}"
        );

        // Teardown must be clean either way — a hung or crashing host would
        // make the verdict meaningless.
        assert!(
            header.contains("child_exit=0"),
            "the child must exit cleanly for the verdict to be trustworthy; \
             header: {header:?}"
        );
    }

    /// invoked with `NEWT_CONPTY_ROLE=host`.
    #[ignore = "spawned by probe_b as the ConPTY host; not a standalone test"]
    #[test]
    fn conpty_host() {
        // `host` acquires a console first; `host-nocon` is the SAME code path
        // with that one step removed — the discriminating variable for whether
        // a process-global console is actually required (probe C).
        let role = std::env::var(ROLE_ENV);
        let acquire_console = match role.as_deref() {
            Ok("host") => true,
            Ok("host-nocon") => false,
            _ => return,
        };
        let result = std::env::var(RESULT_ENV).expect("RESULT path");

        // Present CONSOLE std handles to the child (see the module docs): detach
        // any existing console, take a fresh one, and repoint std handles at it.
        // SAFETY: console lifecycle on this throwaway host process.
        let allocated = unsafe {
            if !acquire_console {
                // Leave the host's std handles exactly as inherited — under
                // `cargo test` they are PIPES, i.e. the redirected-stdio case.
                false
            } else {
                FreeConsole();
                let ok = AllocConsole() != 0;
                if ok {
                    let conout = open_con("CONOUT$");
                    let conin = open_con("CONIN$");
                    SetStdHandle(STD_OUTPUT_HANDLE, conout);
                    SetStdHandle(STD_ERROR_HANDLE, conout);
                    SetStdHandle(STD_INPUT_HANDLE, conin);
                }
                ok
            }
        };

        let (in_read, in_write) = create_pipe();
        let (out_read, out_write) = create_pipe();
        let size = COORD { X: 80, Y: 24 };
        let mut hpc: HPCON = 0;
        // SAFETY: CreatePseudoConsole with pipe ends we own.
        let hr = unsafe { CreatePseudoConsole(size, in_read, out_write, 0, &mut hpc) };

        let mut attr_size: usize = 0;
        // SAFETY: size then init the attribute list; attach hpc by value (as the
        // MS ConPTY sample passes hPC).
        let (attr_list, _attr_buf) = unsafe {
            InitializeProcThreadAttributeList(std::ptr::null_mut(), 1, 0, &mut attr_size);
            let mut buf = vec![0u8; attr_size];
            let list = buf.as_mut_ptr() as *mut c_void;
            InitializeProcThreadAttributeList(list, 1, 0, &mut attr_size);
            UpdateProcThreadAttribute(
                list,
                0,
                PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE as usize,
                hpc as *const c_void,
                std::mem::size_of::<HPCON>(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
            );
            (list, buf)
        };

        let cmdline = format!(
            "\"{}\" --exact cockpit::conpty_probe::probes::conpty_child --ignored --nocapture",
            self_exe().display()
        );
        let mut cmdline_w: Vec<u16> = cmdline.encode_utf16().chain(std::iter::once(0)).collect();
        let mut si: STARTUPINFOEXW = unsafe { std::mem::zeroed() };
        si.StartupInfo.cb = std::mem::size_of::<STARTUPINFOEXW>() as u32;
        si.lpAttributeList = attr_list;
        let mut pi: PROCESS_INFORMATION = unsafe { std::mem::zeroed() };
        std::env::set_var(ROLE_ENV, "child");
        // SAFETY: CreateProcessW under the pseudoconsole; child std handles come
        // from the pty because the host now presents console handles.
        let created = unsafe {
            CreateProcessW(
                std::ptr::null(),
                cmdline_w.as_mut_ptr(),
                std::ptr::null(),
                std::ptr::null(),
                0,
                EXTENDED_STARTUPINFO_PRESENT,
                std::ptr::null(),
                std::ptr::null(),
                &si.StartupInfo,
                &mut pi,
            )
        };
        // SAFETY: drop the parent's copies of the ConPTY-owned ends.
        unsafe {
            CloseHandle(in_read);
            CloseHandle(out_write);
        }

        let out_read_val = out_read as usize;
        let reader = std::thread::spawn(move || read_to_end(out_read_val as HANDLE));
        let mut child_exit: u32 = u32::MAX;
        // SAFETY: wait for the child, read its exit, then tear the pty down.
        unsafe {
            if created != 0 {
                WaitForSingleObject(pi.hProcess, INFINITE);
                GetExitCodeProcess(pi.hProcess, &mut child_exit);
                CloseHandle(pi.hThread);
                CloseHandle(pi.hProcess);
                // The child having EXITED does not mean its bytes have reached
                // us. The pseudoconsole renders child output into the pipe
                // asynchronously, and `ClosePseudoConsole` tears that session
                // down — anything still buffered is discarded, the reader sees
                // EOF early, and the tail of the transcript vanishes. That lost
                // exactly one marker on a loaded runner: stdout arrived and
                // stderr, written last, did not.
                //
                // A short grace period lets the renderer flush what the child
                // already wrote. It bounds the wait rather than guessing: the
                // probe writes a few dozen bytes, so this is slack, not a race
                // the delay merely usually wins.
                std::thread::sleep(std::time::Duration::from_millis(500));
            }
            ClosePseudoConsole(hpc);
        }
        let rendered = reader.join().expect("reader");
        // SAFETY: cleanup.
        unsafe {
            DeleteProcThreadAttributeList(attr_list);
        }
        close(in_write);
        close(out_read);

        let mut file = Vec::new();
        file.extend_from_slice(
            format!("allocated={allocated} hr={hr} created={created} child_exit={child_exit}\n")
                .as_bytes(),
        );
        file.extend_from_slice(&rendered);
        std::fs::write(&result, file).expect("write result");
        std::process::exit(0);
    }

    /// CHILD role (spawned by the host under the ConPTY): report whether its
    /// stdout / stderr are terminals and emit unique markers on each, then exit
    /// cleanly. No-ops unless invoked with `NEWT_CONPTY_ROLE=child`.
    #[ignore = "spawned by conpty_host under the ConPTY; not a standalone test"]
    #[test]
    fn conpty_child() {
        if std::env::var(ROLE_ENV).as_deref() != Ok("child") {
            return;
        }
        let out_tty = std::io::stdout().is_terminal();
        let err_tty = std::io::stderr().is_terminal();
        print!("{OUT_MARKER}[tty={out_tty}]");
        let _ = std::io::stdout().flush();
        eprint!("{ERR_MARKER}[tty={err_tty}]");
        let _ = std::io::stderr().flush();
        std::process::exit(0);
    }
}