Struct App 

pub struct App {

    pub screen: Screen,
    pub top_page: TopPage,
    pub running: bool,
    pub status_center: StatusCenter,
    pub search: SearchState,
    pub reload: ReloadState,
    pub conflict: ConflictState,
    pub tags: TagState,
    pub history: ConnectionHistory,
    pub vault: VaultState,
    pub update: UpdateState,
    pub bw_session: Option<String>,
    pub file_browser_state: FileBrowserState,
    pub file_browser_session: Option<FileBrowserSession>,
    pub demo_mode: bool,
    pub jump: Option<JumpState>,
    /* private fields */
}

Main application state.

Fields

screen: Screen

Currently rendered screen identifier; navigation only, never carries state heaps.

top_page: TopPage

Top-level page (Hosts, Tunnels, Containers). Selected by Tab/Shift+Tab in the navigation bar. Independent of screen, which tracks overlays.

running: bool

App lifecycle flag; flip to false to exit the event loop.

status_center: StatusCenter

Toast queue, sticky messages, status routing.

search: SearchState

Host-list incremental search query and matched hits.

reload: ReloadState

Reload-from-disk state when ~/.ssh/config changes externally.

conflict: ConflictState

Conflict detection when an external edit clashes with our pending write.

tags: TagState

Tag library and per-host tag mappings.

history: ConnectionHistory

Connection history persisted to ~/.purple/history.

vault: VaultState

Vault SSH certificate cache and signing run state.

update: UpdateState

Self-update polling and badge state.

bw_session: Option<String>

askpass session token; not Keys-tab state.

file_browser_state: FileBrowserState

Persistent per-host last-visited paths; always present.

file_browser_session: Option<FileBrowserSession>

Per-host overlay session; Some when the file browser is open.

demo_mode: bool

Demo mode: all mutations are in-memory only, no disk writes.

jump: Option<JumpState>

Jump state. Some when the jump bar is open.

Implementations

impl App

pub fn clear_form_mtime(&mut self)

Clear form mtime state (call on form cancel or successful submit).

pub fn capture_form_mtime(&mut self)

Capture config and Include file mtimes when opening a host form.

pub fn capture_provider_form_mtime(&mut self)

Capture ~/.purple/providers mtime when opening a provider form.

pub fn capture_form_baseline(&mut self)

Capture a baseline snapshot of the host form for dirty-check on Esc.

pub fn host_form_is_dirty(&self) -> bool

Check if the host form has been modified since baseline was captured.

pub fn close_host_form(&mut self)

Tear down host form state and return to the host list. Flush runs last because flush_pending_vault_write no-ops while a form is open.

pub fn close_host_form_after_save(&mut self, target_alias: &str)

Close the host form and select the just-saved host. Use after a successful submit.

pub fn close_provider_form(&mut self)

Tear down provider form state and return to the providers list. Same shape as close_host_form; provider forms have no per-save selection.

pub fn close_tunnel_form(&mut self, return_to: Screen)

Tear down tunnel form state and return to the caller’s screen. The return target varies (host detail overlay, tunnels overview, picker), so the caller passes it.

pub fn close_snippet_form(&mut self, target_aliases: Vec<String>)

Tear down snippet form state and return to the snippet picker for the given targets. Snippet forms intentionally skip clear_form_mtime; no mtime is captured on snippet form open.

pub fn open_host_add_form(&mut self)

Open a blank host add form. Mirror is close_host_form.

pub fn open_host_pattern_add_form(&mut self)

Open a blank pattern add form. Shares Screen::AddHost; the form constructor distinguishes pattern vs host entries internally.

pub fn open_host_edit_form( &mut self, host: HostEntry, stale_hint: Option<String>, ) -> bool

Open the host edit form for host. Returns false (without changing screen) if the host lives in an Include file or its raw entry cannot be located. The caller computes stale_hint because it is derived from handler-local provider-display logic.

pub fn open_host_pattern_edit_form(&mut self, pattern: &PatternEntry)

Open an edit form for an existing pattern entry.

pub fn open_tunnel_add_form(&mut self, alias: String)

Open a blank tunnel add form scoped to alias. The alias is set on the screen variant so submit/cancel return to the right host context.

pub fn open_tunnel_edit_form( &mut self, alias: String, rule: &TunnelRule, editing: usize, )

Open an edit form for an existing tunnel rule. editing is the index into tunnels.list that the save path mutates.

pub fn open_snippet_add_form(&mut self, target_aliases: Vec<String>)

Open a blank snippet add form scoped to the given target aliases. No mtime capture (snippet forms have no mtime tracking).

pub fn open_snippet_edit_form( &mut self, snippet: &Snippet, target_aliases: Vec<String>, editing: usize, )

Open an edit form for an existing snippet. editing is the index into the snippet store that the save path mutates.

pub fn open_provider_form(&mut self, id: ProviderConfigId)

Open a provider form for id, populating defaults for new configs or existing data for edits. When id.label is Some("") the form opens in label-entry mode so the user types the label first.

pub fn capture_tunnel_form_baseline(&mut self)

Capture a baseline snapshot of the tunnel form for dirty-check on Esc.

pub fn tunnel_form_is_dirty(&self) -> bool

Check if the tunnel form has been modified since baseline was captured.

pub fn capture_snippet_form_baseline(&mut self)

Capture a baseline snapshot of the snippet form for dirty-check on Esc.

pub fn snippet_form_is_dirty(&self) -> bool

Check if the snippet form has been modified since baseline was captured.

pub fn capture_provider_form_baseline(&mut self)

Capture a baseline snapshot of the provider form for dirty-check on Esc.

pub fn provider_form_is_dirty(&self) -> bool

Check if the provider form has been modified since baseline was captured.

pub fn config_changed_since_form_open(&self) -> bool

Check if config or any Include file/directory has changed since the form was opened.

pub fn provider_config_changed_since_form_open(&self) -> bool

Check if ~/.purple/providers has changed since the provider form was opened.

impl App

pub fn apply_sort(&mut self)

Rebuild the display list based on the current sort mode and group_by toggle.

pub fn select_first_host(&mut self)

Select the first selectable item in the display list (always skips headers).

impl App

pub fn clear_group_filter(&mut self)

Clear group filter (Esc from filtered mode).

impl App

pub fn add_host_from_form(&mut self) -> Result<String, String>

pub fn edit_host_from_form(&mut self, old_alias: &str) -> Result<String, String>

Edit an existing host from the current form. Returns status message.

pub fn select_host_by_alias(&mut self, alias: &str)

Select a host in the display list (or filtered list) by alias.

pub fn apply_sync_result( &mut self, provider: &str, hosts: Vec<ProviderHost>, partial: bool, ) -> (String, bool, usize, usize, usize, usize)

Apply sync results from a background provider fetch. Returns (message, is_error, server_count, added, updated, stale). Caller must remove from syncing_providers.

provider is the full ProviderConfigId display string (do for bare, do:work for labeled). We look up by exact id so multi-config providers route to the correct section.

pub fn clear_stale_group_tag(&mut self) -> bool

Clear group-by-tag if the tag no longer exists in any host. Returns true if the tag was cleared.

impl App

pub fn close_password_picker(&mut self)

Close the password picker overlay.

pub fn close_key_picker(&mut self)

Close the key picker overlay.

pub fn close_proxyjump_picker(&mut self)

Close the ProxyJump picker overlay.

pub fn close_vault_role_picker(&mut self)

Close the Vault SSH role picker overlay.

pub fn close_region_picker(&mut self)

Close the provider region picker overlay.

pub fn open_password_picker(&mut self)

Open the password picker overlay focused on the first source.

pub fn open_key_picker(&mut self)

Open the key picker overlay. Rescans ~/.ssh first so the list reflects keys added since the form was opened, then selects the first key when at least one was discovered.

pub fn open_proxyjump_picker(&mut self)

Open the ProxyJump picker overlay. The opening cursor lands on the first host row rather than the first list entry, so separator/header rows above the host list do not steal initial focus.

pub fn open_vault_role_picker(&mut self)

Open the Vault SSH role picker. The caller is responsible for guarding against an empty candidate list; this method assumes at least one role and selects the first.

pub fn open_region_picker(&mut self)

Open the provider region picker overlay with the cursor on the first row. Region picker uses a cursor: usize rather than a ratatui ListState because its rows are a synthetic flat array.

impl App

pub fn start_search(&mut self)

Enter search mode.

pub fn start_search_with(&mut self, query: &str)

Start search with an initial query (for positional arg).

pub fn cancel_search(&mut self)

Cancel search mode and restore normal view.

pub fn apply_filter(&mut self)

Apply the current search query to filter hosts.

pub fn filtered_snippet_indices(&self) -> Vec<usize>

Return indices of snippets matching the search query.

impl App

pub fn set_screen(&mut self, screen: Screen)

Transition to a new screen. Logs the transition at debug level for support-bundle traceability. Callers should prefer this over direct app.screen = ... assignment.

pub fn cycle_top_page_next(&mut self)

Cycle to the next top page. Logs the transition so Tab-cycle confusion (“I keep landing on the wrong page after Tab”) leaves a breadcrumb in ~/.purple/purple.log. Callers should prefer this over direct app.top_page = app.top_page.next() assignment.

pub fn cycle_top_page_prev(&mut self)

Cycle to the previous top page. See cycle_top_page_next.

pub fn selected_host_index(&self) -> Option<usize>

Get the host index from the currently selected display list item.

pub fn selected_host(&self) -> Option<&HostEntry>

Get the currently selected host entry.

pub fn selected_pattern(&self) -> Option<&PatternEntry>

Get the currently selected pattern entry (if a pattern is selected).

pub fn is_pattern_selected(&self) -> bool

Check if the currently selected item is a pattern.

pub fn select_prev(&mut self)

Move selection up, skipping group headers.

pub fn select_next(&mut self)

Move selection down, skipping group headers.

pub fn page_down_host(&mut self)

Page down in the host list, skipping group headers when ungrouped.

pub fn page_up_host(&mut self)

Page up in the host list, skipping group headers.

pub fn scan_keys(&mut self)

pub fn select_prev_key(&mut self)

Move key list selection up.

pub fn select_next_key(&mut self)

Move key list selection down.

pub fn select_prev_picker_key(&mut self)

Move key picker selection up.

pub fn select_next_picker_key(&mut self)

Move key picker selection down.

pub fn select_prev_password_source(&mut self)

Move password picker selection up.

pub fn select_next_password_source(&mut self)

Move password picker selection down.

pub fn proxyjump_candidates(&self) -> Vec<ProxyJumpCandidate>

Get hosts available as ProxyJump targets (excludes the host being edited), ranked so likely jump hosts appear on top. Ranking combines three signals: usage count as ProxyJump on other hosts, alias or hostname matching a jump-host keyword (jump, bastion, gateway, proxy, gw), and sharing the last two domain labels with the hostname of the host being edited. Items with a non-zero score are grouped in a “suggested” section above a visual Separator. The remaining items are listed alphabetically below. If no item scores, the full list is alphabetical with no separator.

pub fn proxyjump_first_host_index(&self) -> Option<usize>

Find the first selectable (non-separator) index in the ProxyJump picker, or None if the list has no hosts.

pub fn select_prev_proxyjump(&mut self)

Move proxyjump picker selection up, skipping separators.

pub fn select_next_proxyjump(&mut self)

Move proxyjump picker selection down, skipping separators.

pub fn vault_role_candidates(&self) -> Vec<String>

Collect unique Vault SSH roles from all hosts and providers, sorted.

pub fn select_prev_vault_role(&mut self)

Move vault role picker selection up.

pub fn select_next_vault_role(&mut self)

Move vault role picker selection down.

pub fn collect_unique_tags(&self) -> Vec<String>

Collect all unique tags from hosts, sorted alphabetically.

pub fn open_bulk_tag_editor(&mut self) -> bool

Open the bulk tag editor for every host currently in multi_select. Returns false (and leaves the screen untouched) when the selection is empty or contains only pattern entries — callers can then fall back to single-host tag editing or show a status message.

Hosts that live in an Include file are still listed in aliases but get surfaced via skipped_included. bulk_tag_apply honours that split so included hosts are never mutated in place.

pub fn bulk_tag_editor_next(&mut self)

Move bulk tag editor selection down.

pub fn bulk_tag_editor_prev(&mut self)

Move bulk tag editor selection up.

pub fn bulk_tag_editor_cycle_current(&mut self)

Cycle the action on the currently selected row: Leave → AddToAll → RemoveFromAll → Leave.

pub fn bulk_tag_editor_commit_new_tag(&mut self)

Append a freshly typed tag to the row list. The new row is marked AddToAll so the user’s intent (“add this new tag to all selected hosts”) is preserved without a second keystroke. No-op for empty input or duplicate tag names.

pub fn bulk_tag_apply(&mut self) -> Result<BulkTagApplyResult, String>

Apply all pending actions from the bulk tag editor. Leaves the config untouched (and returns an error) if the write fails so the user can retry without losing state. On success, hosts are reloaded (which clears multi_select).

pub fn open_tag_picker(&mut self)

Open the tag picker overlay.

pub fn select_prev_tag(&mut self)

Move tag picker selection up.

pub fn select_next_tag(&mut self)

Move tag picker selection down.

pub fn refresh_tunnel_list(&mut self, alias: &str)

Load tunnel directives for a host alias. Uses find_tunnel_directives for Include-aware, multi-pattern host lookup.

pub fn select_prev_tunnel(&mut self)

Move tunnel list selection up.

pub fn select_next_tunnel(&mut self)

Move tunnel list selection down.

pub fn select_prev_snippet(&mut self)

Move snippet picker selection up.

pub fn select_next_snippet(&mut self)

Move snippet picker selection down.

pub fn select_next_skipping_headers(&mut self)

Poll active tunnels for exit status. Returns messages for any that exited. Move selection to the next non-header item.

pub fn select_prev_skipping_headers(&mut self)

Move selection to the previous non-header item.

impl App

pub fn new(config: SshConfigFile) -> Self

pub fn record_key_use(&mut self, alias: &str, now: u64)

Record an SSH session against alias in the activity log. Appends in memory and flushes to ~/.purple/key_activity.json. Failures during flush are logged at debug level only; an activity-log write failure must never interrupt the user’s connect flow. Caller passes now; production call sites pass key_activity::now_secs().

pub fn snapshot_alias_set(&self) -> HashSet<String>

Snapshot the alias of every host currently loaded. Used as the “before” set for queue_new_aliases_since after a reload that may have added or removed hosts.

pub fn queue_new_aliases_since(&mut self, before_aliases: &HashSet<String>)

Push aliases that are in the current host list but were NOT in before_aliases to the auto-fetch queue. Sync handlers and external-config-edit detection use this so only freshly introduced hosts trigger an initial docker ps. pre-existing cache-missing hosts are explicitly left alone.

pub fn reload_hosts(&mut self)

Reload hosts from config.

pub fn refresh_cert_cache(&mut self, alias: &str)

Synchronously re-check a host’s Vault SSH certificate and update vault.cert_cache with fresh status + on-disk mtime.

Every sign path (V-key bulk sign, host form submit, connect-time ensure_vault_ssh_if_needed, CLI) funnels through this helper so the detail panel never lies about cert state after a successful sign.

No-op in demo mode. If the host is missing, has no resolvable vault role, or the cert path cannot be resolved, any stale entry for the alias is removed to avoid showing ghost status.

pub fn is_form_open(&self) -> bool

Check whether a form screen is currently open (host or provider forms).

pub fn open_jump(&mut self, mode: JumpMode)

Open the unified jump in the given mode. Loads recents from disk and seeds the empty-query view. Recomputes hits.

pub fn recompute_jump_hits(&mut self)

Recompute the jump bar hit list against the current query. Pulls candidates from every live source and ranks them with nucleo-matcher. Preserves the previously-selected hit’s identity across the recompute so mid-typing arrow-key navigation does not jump back to row 0.

pub fn record_jump_hit(&mut self, hit: &JumpHit)

Persist a jump dispatch to the on-disk MRU log. Best-effort; a write error logs and is otherwise swallowed so user navigation is never blocked by a recents-file failure. Takes &mut self so the type system reflects that this performs I/O and mutates persistent state, even though jump::save_recents only needs &File.

pub fn flush_pending_vault_write(&mut self) -> bool

Flush a deferred vault config write if one is pending and no form is open. Returns true if a write was performed.

pub fn post_init(&mut self)

Run once after App::new: queue the upgrade toast if the user just upgraded past their last-seen version, otherwise seed the preference so the next launch is silent.

pub fn notify(&mut self, text: impl Into<String>)

User action feedback. Success toast, length-proportional timeout.

pub fn notify_error(&mut self, text: impl Into<String>)

User action error. Error toast, sticky by default, queued.

pub fn notify_background(&mut self, text: impl Into<String>)

Background event. Info footer, suppressed if sticky active.

pub fn notify_background_error(&mut self, text: impl Into<String>)

Background error. Sticky toast, bypasses sticky suppression.

pub fn notify_warning(&mut self, text: impl Into<String>)

Caution / degraded state → Warning toast (length-proportional timeout, queued). For: precondition violations (“Nothing to undo.”), validation hints (“Project ID can’t be empty.”), empty-state notices (“No stale hosts.”), stale-host warnings, deprecated config detected, partial sync results. Warnings are NOT sticky; the user acknowledges them by continuing to interact.

Use notify_error only for system-level failures (I/O, network, subprocess) that require explicit acknowledgement. Use notify_warning for everything that is “this can’t happen given current state” or “you forgot something”.

pub fn notify_progress(&mut self, text: impl Into<String>)

Long-running progress. Footer sticky, never expires automatically.

pub fn notify_sticky_error(&mut self, text: impl Into<String>)

Sticky error. Footer sticky, never expires automatically.

pub fn notify_info(&mut self, text: impl Into<String>)

Explicit info. Footer, 4s timeout, not suppressed by sticky.

pub fn tick_status(&mut self)

Tick the footer status message timer. Uses wall-clock time. Sticky/Progress messages never expire automatically.

Stays on App (not moved to StatusCenter) because expiry is suppressed while any provider sync is in flight, which requires reading self.providers.syncing.

pub fn tick_toast(&mut self)

Shim. Routes to StatusCenter::tick_toast.

pub fn check_config_changed(&mut self)

Check if config or any Include file has changed externally and reload if so. Skips reload when the user is in a form (AddHost/EditHost) to avoid overwriting in-memory config while the user is editing.

pub fn check_keys_changed(&mut self)

Detect external changes to ~/.ssh/ keys and refresh self.keys.list when something has moved. Mirrors check_config_changed for the keys tab so users see new key files (or deletions, or rotations) without pressing R. Cheap: a single dir stat plus one stat per tracked key. Called from the 4-second throttle in handle_tick.

Skips during demo mode (the demo seeds a fixed key list and never reads from disk) and when a form is open that could be mutating the same data.

pub fn external_config_changed(&self) -> bool

Non-mutating check: has the on-disk config (or any tracked Include) been modified since self.reload.last_modified was captured? Used by async write paths (e.g. the Vault SSH bulk-sign completion handler) to refuse writing when an external editor changed the file underneath us. overwriting those edits would silently discard user work. The backup-on-write mechanism in SshConfigFile::write() would still recover them, but detecting the conflict BEFORE writing is strictly better than after.

pub fn update_last_modified(&mut self)

Update the last_modified timestamp (call after writing config).

pub fn has_any_vault_role(&self) -> bool

Returns true if any host or provider has a vault role configured.

pub fn poll_tunnels(&mut self) -> Vec<(String, String, bool)>

Poll active tunnels for exit. Returns (alias, message, is_error) tuples.

pub fn refresh_tunnel_bind_ports(&mut self)

Recompute the lsof poller’s bind-port list from the current active map plus each host’s directives in the SSH config. Called after every tunnel start/stop. The poller picks up the new list on its next iteration.

Trait Implementations

impl Drop for App

Kill active tunnel processes when App is dropped (e.g. on panic).

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.