# `mod scripted`

::::::{rust:module} paranoid_cli::scripted
:index: 0
:vis: pub

  :::
  Deterministic scripted driving surface for the TUI applications.
  
  Both `tui::run()` (the generator wizard) and `vault_tui::run()` (the vault
  manager) normally read real keyboard events from a `CrosstermBackend`
  terminal, which is why the only existing end-to-end coverage
  (`tests/test_tui_e2e.py`) has to fork a real PTY. That PTY layer stays as
  the sole terminal-emulation-accurate check; this module adds a second,
  deterministic path that feeds a script of key tokens straight into the
  same `App::handle_key` step function used by the real event loop, backed
  by ratatui's in-memory `TestBackend` instead of a real terminal.
  
  A scripted run is activated by setting `PARANOID_TUI_SCRIPT=<path>` before
  calling `tui::run()` or `vault_tui::run(config)`. The path must contain
  newline-delimited key tokens (see [`parse_script`]). Blank lines and lines
  starting with `#` are ignored. The run drives the real `App` — including,
  for the generator wizard, its background worker thread — and returns a
  final-frame text dump of the terminal buffer so callers can assert on
  rendered content without a PTY.
  
  # Token grammar
  
  One token per line, whitespace-trimmed:
  
  - A single printable character is sent as its own literal
    `KeyCode::Char` key event. Multi-character text is scripted as one
    character per line (there is no inline string literal).
  - `<enter>`, `<esc>`, `<tab>`, `<backspace>`, `<up>`, `<down>` map to the
    matching `KeyCode` variant.
  - `<ctrl-u>` sends `KeyCode::Char('u')` with `KeyModifiers::CONTROL`
    (matches the custom-charset / form "clear field" shortcut).
  - `<wait-idle>` does not send a key event. It repeatedly polls the app
    (worker + hardening polling, when the app exposes it) until any
    background worker thread has drained, up to a bounded timeout. Use it
    after triggering an action that spawns a worker thread (e.g. launching
    the generator audit) before scripting further keys or ending the run.
  - Blank lines and lines starting with `#` are ignored (comments).
  :::
:::{rust:use} paranoid_cli::scripted
:used_name: self

:::
:::{rust:use} paranoid_cli
:used_name: crate

:::
:::{rust:use} ratatui::Terminal
:used_name: Terminal

:::
:::{rust:use} ratatui::backend::TestBackend
:used_name: TestBackend

:::
:::{rust:use} std::env
:used_name: env

:::
:::{rust:use} std::fs
:used_name: fs

:::
:::{rust:use} std::path::Path
:used_name: Path

:::
:::{rust:use} std::path::PathBuf
:used_name: PathBuf

:::
:::{rust:use} std::time::Duration
:used_name: Duration

:::
:::{rust:use} std::time::Instant
:used_name: Instant

:::
:::{rust:use} crossterm::event::KeyCode
:used_name: KeyCode

:::
:::{rust:use} crossterm::event::KeyEvent
:used_name: KeyEvent

:::
:::{rust:use} crossterm::event::KeyModifiers
:used_name: KeyModifiers

:::

:::{rubric} Variables
:::

:::::{rust:variable} paranoid_cli::scripted::DEFAULT_COLS
:index: 0
:vis: pub
:toc: const DEFAULT_COLS
:layout: [{"type":"keyword","value":"const"},{"type":"space"},{"type":"name","value":"DEFAULT_COLS"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"}]

  :::
  Default terminal size used for scripted runs, matching the PTY e2e layer.
  :::
:::::
:::::{rust:variable} paranoid_cli::scripted::DEFAULT_ROWS
:index: 0
:vis: pub
:toc: const DEFAULT_ROWS
:layout: [{"type":"keyword","value":"const"},{"type":"space"},{"type":"name","value":"DEFAULT_ROWS"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"}]

  :::
  :::
:::::

:::{rubric} Functions
:::

:::::{rust:function} paranoid_cli::scripted::drive
:index: 0
:vis: pub
:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"drive"},{"type":"punctuation","value":"<"},{"type":"name","value":"S"},{"type":"punctuation","value":">"},{"type":"punctuation","value":"("},{"type":"name","value":"terminal"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"Terminal","target":"Terminal"},{"type":"punctuation","value":"<"},{"type":"link","value":"TestBackend","target":"TestBackend"},{"type":"punctuation","value":">"},{"type":"punctuation","value":", "},{"type":"name","value":"tokens"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"punctuation","value":"["},{"type":"link","value":"ScriptToken","target":"ScriptToken"},{"type":"punctuation","value":"]"},{"type":"punctuation","value":", "},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"name","value":"step"},{"type":"punctuation","value":": "},{"type":"link","value":"S","target":"S"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"anyhow","target":"anyhow"},{"type":"punctuation","value":"::"},{"type":"name","value":"Result"},{"type":"punctuation","value":"<"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"punctuation","value":">"},{"type":"newline"},{"type":"keyword","value":"where"},{"type":"newline"},{"type":"indent"},{"type":"link","value":"S","target":"S"},{"type":"punctuation","value":": "},{"type":"link","value":"FnMut","target":"FnMut"},{"type":"punctuation","value":"("},{"type":"punctuation","value":"&"},{"type":"keyword","value":"mut"},{"type":"space"},{"type":"link","value":"Terminal","target":"Terminal"},{"type":"punctuation","value":"<"},{"type":"link","value":"TestBackend","target":"TestBackend"},{"type":"punctuation","value":">"},{"type":"punctuation","value":", "},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"link","value":"KeyEvent","target":"KeyEvent"},{"type":"punctuation","value":">"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"anyhow","target":"anyhow"},{"type":"punctuation","value":"::"},{"type":"name","value":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"StepOutcome","target":"StepOutcome"},{"type":"punctuation","value":">"}]

  :::
  Generic scripted-run driver shared by `tui::run_scripted` and
  `vault_tui::run_scripted`.
  
  `step` performs one iteration of the app's own event loop body: when
  `key` is `Some`, it should forward the event to the app's `handle_key`
  before polling/rendering; when `None`, it should just poll (worker /
  hardening) and render, as the real event loop does on each tick even
  without a key event.
  :::
:::::
:::::{rust:function} paranoid_cli::scripted::dump_buffer
:index: 0
:vis: pub
:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"dump_buffer"},{"type":"punctuation","value":"("},{"type":"name","value":"terminal"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"link","value":"Terminal","target":"Terminal"},{"type":"punctuation","value":"<"},{"type":"link","value":"TestBackend","target":"TestBackend"},{"type":"punctuation","value":">"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"String","target":"String"}]

  :::
  Renders the given `TestBackend` terminal buffer to a plain-text dump, one
  line per terminal row, trailing whitespace trimmed. This is the
  "final-frame" text callers assert against after a scripted run.
  :::
:::::
:::::{rust:function} paranoid_cli::scripted::is_script_active
:index: 0
:vis: pub
:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"is_script_active"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"bool","target":"bool"}]

  :::
  `true` when `PARANOID_TUI_SCRIPT` is set. A scripted run is, by
  definition, a deliberate non-interactive drive of the TUI (there is no
  real terminal to detect), so callers should treat this the same as an
  explicit `--tui` request when deciding whether to launch the TUI instead
  of the scriptable CLI/ops path.
  :::
:::::
:::::{rust:function} paranoid_cli::scripted::load_script
:index: 0
:vis: pub
:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"load_script"},{"type":"punctuation","value":"("},{"type":"name","value":"path"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"link","value":"Path","target":"Path"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"anyhow","target":"anyhow"},{"type":"punctuation","value":"::"},{"type":"name","value":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"Vec","target":"Vec"},{"type":"punctuation","value":"<"},{"type":"link","value":"ScriptToken","target":"ScriptToken"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"}]

  :::
  Loads and parses a script file.
  :::
:::::
:::::{rust:function} paranoid_cli::scripted::parse_script
:index: 0
:vis: pub
:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"parse_script"},{"type":"punctuation","value":"("},{"type":"name","value":"contents"},{"type":"punctuation","value":": "},{"type":"punctuation","value":"&"},{"type":"link","value":"str","target":"str"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"anyhow","target":"anyhow"},{"type":"punctuation","value":"::"},{"type":"name","value":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"Vec","target":"Vec"},{"type":"punctuation","value":"<"},{"type":"link","value":"ScriptToken","target":"ScriptToken"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"}]

  :::
  Parses newline-delimited key tokens into [`ScriptToken`]s. See the module
  docs for the token grammar.
  :::
:::::
:::::{rust:function} paranoid_cli::scripted::prepare_scripted_terminal
:index: 0
:vis: pub
:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"prepare_scripted_terminal"},{"type":"punctuation","value":"("},{"type":"name","value":"cols"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"},{"type":"punctuation","value":", "},{"type":"name","value":"rows"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"anyhow","target":"anyhow"},{"type":"punctuation","value":"::"},{"type":"name","value":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"link","value":"PreparedScript","target":"PreparedScript"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"}]

  :::
  Convenience for `run()` implementations: reads the script path from
  `PARANOID_TUI_SCRIPT`, builds a `TestBackend` terminal of the given size,
  and returns both plus the parsed tokens, ready to hand to [`drive`].
  :::
:::::
:::::{rust:function} paranoid_cli::scripted::script_from_env
:index: 0
:vis: pub
:layout: [{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"script_from_env"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"Option","target":"Option"},{"type":"punctuation","value":"<"},{"type":"link","value":"anyhow","target":"anyhow"},{"type":"punctuation","value":"::"},{"type":"name","value":"Result"},{"type":"punctuation","value":"<"},{"type":"link","value":"Vec","target":"Vec"},{"type":"punctuation","value":"<"},{"type":"link","value":"ScriptToken","target":"ScriptToken"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"},{"type":"punctuation","value":">"}]

  :::
  Reads `PARANOID_TUI_SCRIPT` from the environment and, if set, parses the
  script file at that path. Returns `None` when the variable is unset so
  callers can fall back to the normal interactive event loop.
  :::
:::::

:::{rubric} Enums
:::

:::::{rust:enum} paranoid_cli::scripted::ScriptToken
:index: 1
:vis: pub
:layout: [{"type":"keyword","value":"enum"},{"type":"space"},{"type":"name","value":"ScriptToken"}]

  :::
  A single step to apply to the application under script control.
  :::
::::{rust:struct} paranoid_cli::scripted::ScriptToken::Key
:index: 2
:vis: pub
:toc: Key
:layout: [{"type":"name","value":"Key"},{"type":"punctuation","value":"("},{"type":"link","value":"KeyEvent","target":"KeyEvent"},{"type":"punctuation","value":")"}]

  :::
  Send this key event to `App::handle_key`.
  :::
::::
::::{rust:struct} paranoid_cli::scripted::ScriptToken::WaitIdle
:index: 2
:vis: pub
:toc: WaitIdle
:layout: [{"type":"name","value":"WaitIdle"}]

  :::
  Poll until any background worker has drained, or time out.
  :::
::::
:::::

:::{rubric} Structs and Unions
:::

:::::{rust:struct} paranoid_cli::scripted::PreparedScript
:index: 1
:vis: pub
:toc: struct PreparedScript
:layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"PreparedScript"}]

  :::
  A ready-to-drive scripted terminal, its parsed token script, and the
  script file path it was loaded from (for error messages).
  :::
::::{rust:variable} paranoid_cli::scripted::PreparedScript::terminal
:index: 2
:vis: pub
:toc: terminal
:layout: [{"type":"name","value":"terminal"},{"type":"punctuation","value":": "},{"type":"link","value":"Terminal","target":"Terminal"},{"type":"punctuation","value":"<"},{"type":"link","value":"TestBackend","target":"TestBackend"},{"type":"punctuation","value":">"}]

  :::
  :::
::::
::::{rust:variable} paranoid_cli::scripted::PreparedScript::tokens
:index: 2
:vis: pub
:toc: tokens
:layout: [{"type":"name","value":"tokens"},{"type":"punctuation","value":": "},{"type":"link","value":"Vec","target":"Vec"},{"type":"punctuation","value":"<"},{"type":"link","value":"ScriptToken","target":"ScriptToken"},{"type":"punctuation","value":">"}]

  :::
  :::
::::
::::{rust:variable} paranoid_cli::scripted::PreparedScript::path
:index: 2
:vis: pub
:toc: path
:layout: [{"type":"name","value":"path"},{"type":"punctuation","value":": "},{"type":"link","value":"PathBuf","target":"PathBuf"}]

  :::
  :::
::::
:::::
:::::{rust:struct} paranoid_cli::scripted::StepOutcome
:index: 1
:vis: pub
:toc: struct StepOutcome
:layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"StepOutcome"}]

  :::
  Result of a single [`drive`] step.
  :::
::::{rust:variable} paranoid_cli::scripted::StepOutcome::idle
:index: 2
:vis: pub
:toc: idle
:layout: [{"type":"name","value":"idle"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"}]

  :::
  `true` once any background work the app owns has fully drained (so
  `<wait-idle>` knows when to stop polling). Apps with no background
  work should always report `true`.
  :::
::::
::::{rust:variable} paranoid_cli::scripted::StepOutcome::quit
:index: 2
:vis: pub
:toc: quit
:layout: [{"type":"name","value":"quit"},{"type":"punctuation","value":": "},{"type":"link","value":"bool","target":"bool"}]

  :::
  `true` when the app requested to quit in response to a key event.
  Ignored for poll-only steps (`key: None`).
  :::
::::
:::::
::::::