Merge pull request #20 from Spacecraft-Software/tui-vim

feat(vault-tui): tui.vim — vim jump motions

Author: UnbreakableMJ

CHANGELOG.md

@@ -10,6 +10,18 @@ range may break in any release.
 
 ### Added
 
+- **`tui.vim` — vim jump motions in the TUI.** Opt-in (`vault config set tui.vim
+  true`): on top of the default `hjkl`, the browser gains `gg` (top), `G`
+  (bottom), and `Ctrl-d`/`Ctrl-u` (half-page; a fixed step — the pure-render
+  `App` has no viewport height). Because `g` becomes the `gg` prefix in vim
+  mode, the generator overlay moves from `g` to `Ctrl-g`; non-vim mode is
+  unchanged (`g` opens the generator). Read by `vault-tui` directly (not relayed
+  to the agent). New `App` motions (`move_top`/`move_bottom`/`page_up`/
+  `page_down`, reusing the focus-aware re-masking `move_*` pattern) + a `gg`
+  prefix state machine. Completes the PRD §7.1 config registry. Tested in
+  `vault-config` (round-trip / reject / not-an-agent-flag) and `vault-tui` (jump
+  + clamp + empty-list no-op + the `gg` arm/take sequence).
+
 - **`ui.reduced_motion` config key (reserved).** Completes the PRD §7.1 config
   registry with the accessibility preference to suppress animated TUI elements.
   The TUI has no animations yet (it's fully event-driven — no spinner, no

README.md

@@ -150,12 +150,19 @@ Recognised keys: `clipboard.clear_secs` (auto-clear window, `0` disables),
 `agent.idle_lock_secs` (idle-lock timeout, `0` disables),
 `agent.session_keyring` (resume across restarts; see above),
 `sync.interval_secs` (background `/sync` interval while unlocked, `0` disables),
-and `ui.reduced_motion` (suppress animated TUI elements — **reserved**: the TUI
-has no animations yet, so this records the preference for when a spinner /
-lock-countdown lands). When the CLI auto-starts the agent, the agent-side keys
-populate its launch flags (changes apply on the next agent spawn);
-`ui.reduced_motion` is read by `vault-tui` directly. Wipe the on-disk item cache
-(and drop a running agent's keys) with `vault purge`.
+`ui.reduced_motion` (suppress animated TUI elements — **reserved**: the TUI has
+no animations yet, so this records the preference for when a spinner /
+lock-countdown lands), and `tui.vim` (vim motions; see below). When the CLI
+auto-starts the agent, the agent-side keys populate its launch flags (changes
+apply on the next agent spawn); `ui.reduced_motion` and `tui.vim` are read by
+`vault-tui` directly. Wipe the on-disk item cache (and drop a running agent's
+keys) with `vault purge`.
+
+With `tui.vim` set, `vault-tui` adds vim jump motions on top of the default
+`hjkl` navigation: `gg` to the top, `G` to the bottom, and `Ctrl-d`/`Ctrl-u` for
+a half-page. Because `g` becomes the `gg` prefix, the password generator moves
+from `g` to `Ctrl-g` while vim mode is on (with it off, `g` opens the generator
+as before).
 
 With `sync.interval_secs` set, the agent re-pulls `/sync` on that cadence while
 unlocked — keeping the in-memory vault and offline cache fresh without a manual

crates/vault-config/src/lib.rs

@@ -29,6 +29,7 @@ pub const KNOWN_KEYS: &[&str] = &[
     "agent.session_keyring",
     "sync.interval_secs",
     "ui.reduced_motion",
+    "tui.vim",
 ];
 
 /// Accepted values for `clipboard.backend`.
@@ -48,6 +49,8 @@ pub struct Config {
     pub sync: SyncCfg,
     /// TUI rendering preferences.
     pub ui: UiCfg,
+    /// TUI keymap preferences.
+    pub tui: TuiCfg,
     /// Registered account profile (written by `vault register`). Skipped from
     /// the file until something is set, so an unregistered config carries no
     /// empty `[account]` table.
@@ -100,6 +103,16 @@ pub struct UiCfg {
     pub reduced_motion: Option<bool>,
 }
 
+/// `[tui]` table — TUI-only keymap preferences (read by `vault-tui` directly,
+/// never relayed to the agent).
+#[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct TuiCfg {
+    /// Enable vim-style jump motions (`gg`/`G`/`Ctrl-d`/`Ctrl-u`); the generator
+    /// overlay moves from `g` to `Ctrl-g` while on.
+    pub vim: Option<bool>,
+}
+
 /// `[account]` table — the registered account, written by `vault register`
 /// and read by `login`/`unlock` to default `server`/`email`/`device_id`.
 #[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
@@ -162,6 +175,12 @@ impl Config {
         self.ui.reduced_motion
     }
 
+    /// Effective `tui.vim`, if set.
+    #[must_use]
+    pub const fn tui_vim(&self) -> Option<bool> {
+        self.tui.vim
+    }
+
     /// The registered account profile.
     #[must_use]
     pub const fn account(&self) -> &AccountCfg {
@@ -192,6 +211,7 @@ impl Config {
             "agent.session_keyring" => Ok(self.agent.session_keyring.map(|v| v.to_string())),
             "sync.interval_secs" => Ok(self.sync.interval_secs.map(|v| v.to_string())),
             "ui.reduced_motion" => Ok(self.ui.reduced_motion.map(|v| v.to_string())),
+            "tui.vim" => Ok(self.tui.vim.map(|v| v.to_string())),
             other => Err(other.to_owned()),
         }
     }
@@ -228,6 +248,10 @@ impl Config {
                 self.ui.reduced_motion = Some(parse_bool(key, raw)?);
                 Ok(())
             }
+            "tui.vim" => {
+                self.tui.vim = Some(parse_bool(key, raw)?);
+                Ok(())
+            }
             other => Err(unknown_key(other)),
         }
     }
@@ -263,6 +287,10 @@ impl Config {
                 self.ui.reduced_motion = None;
                 Ok(())
             }
+            "tui.vim" => {
+                self.tui.vim = None;
+                Ok(())
+            }
             other => Err(unknown_key(other)),
         }
     }
@@ -574,6 +602,24 @@ mod tests {
         assert_eq!(c.reduced_motion(), None);
     }
 
+    #[test]
+    fn tui_vim_round_trips_and_is_tui_only() {
+        let mut c = Config::default();
+        assert_eq!(c.tui_vim(), None);
+        c.set("tui.vim", "true").expect("set true");
+        assert_eq!(c.tui_vim(), Some(true));
+        assert!(
+            !agent_args(&c).contains(&OsString::from("--vim")),
+            "tui.vim must not become an agent flag"
+        );
+        let text = toml::to_string_pretty(&c).expect("serialise");
+        let back: Config = toml::from_str(&text).expect("parse");
+        assert_eq!(back.tui_vim(), Some(true));
+        assert!(c.set("tui.vim", "maybe").is_err());
+        c.unset("tui.vim").expect("unset");
+        assert_eq!(c.tui_vim(), None);
+    }
+
     #[test]
     fn sync_interval_round_trips() {
         let mut c = Config::default();

crates/vault-tui/src/app.rs

@@ -29,6 +29,11 @@ const GEN_MIN_LEN: usize = 8;
 /// own generator ceiling so saved values round-trip everywhere.
 const GEN_MAX_LEN: usize = 128;
 
+/// Rows a vim half-page motion (`Ctrl-d`/`Ctrl-u`) moves. A fixed approximation
+/// of vim's "half the window": the pure-render `App` has no viewport height, so
+/// a constant step keeps the motion useful without plumbing the pane geometry.
+const VIM_PAGE: usize = 10;
+
 /// A single-line editable text buffer with a cursor — the shared core behind
 /// the `/` search, `:` command line, and every form field. Edits happen at the
 /// cursor; `cursor` is a byte offset kept on a `char` boundary so all the
@@ -704,6 +709,10 @@ impl FormState {
 
 /// Top-level TUI state.
 #[derive(Clone, Debug)]
+#[expect(
+    clippy::struct_excessive_bools,
+    reason = "App is the TUI's flat UI-state aggregate; these are independent toggles (config prefs + transient flags), not a state machine to fold into an enum"
+)]
 pub struct App {
     /// What the screen shows.
     pub screen: Screen,
@@ -751,6 +760,11 @@ pub struct App {
     /// animations yet, so nothing reads this — it's populated from config so a
     /// future spinner / lock-countdown can honor it without re-plumbing.
     pub reduced_motion: bool,
+    /// Vim-style jump motions enabled (`tui.vim`): `gg`/`G`/`Ctrl-d`/`Ctrl-u`,
+    /// with the generator moved from `g` to `Ctrl-g`.
+    pub vim: bool,
+    /// Whether a `g` is pending the second `g` of a `gg` (vim mode only).
+    pub pending_g: bool,
     /// Set when the user asks to quit.
     pub should_quit: bool,
 }
@@ -780,6 +794,8 @@ impl App {
             toast: None,
             unlock: None,
             reduced_motion: false,
+            vim: false,
+            pending_g: false,
             should_quit: false,
         }
     }
@@ -814,6 +830,8 @@ impl App {
             toast: None,
             unlock: None,
             reduced_motion: false,
+            vim: false,
+            pending_g: false,
             should_quit: false,
         }
     }
@@ -915,6 +933,62 @@ impl App {
         }
     }
 
+    /// Jump to the first row of the focused pane (vim `gg`).
+    pub fn move_top(&mut self) {
+        self.revealed = None;
+        match self.focus {
+            Focus::Folders => {
+                self.folder_sel = 0;
+                self.item_sel = 0;
+            }
+            Focus::Items => self.item_sel = 0,
+        }
+    }
+
+    /// Jump to the last row of the focused pane (vim `G`); no-op when empty.
+    pub fn move_bottom(&mut self) {
+        self.revealed = None;
+        match self.focus {
+            Focus::Folders => {
+                self.folder_sel = self.folders.len().saturating_sub(1);
+                self.item_sel = 0;
+            }
+            Focus::Items => self.item_sel = self.filtered().len().saturating_sub(1),
+        }
+    }
+
+    /// Move the focused selection down by a half-page (vim `Ctrl-d`), clamped.
+    pub fn page_down(&mut self) {
+        for _ in 0..VIM_PAGE {
+            self.move_down();
+        }
+    }
+
+    /// Move the focused selection up by a half-page (vim `Ctrl-u`), clamped.
+    pub fn page_up(&mut self) {
+        for _ in 0..VIM_PAGE {
+            self.move_up();
+        }
+    }
+
+    /// Arm the `gg` prefix: the next `g` jumps to the top.
+    pub const fn arm_pending_g(&mut self) {
+        self.pending_g = true;
+    }
+
+    /// Consume the `gg` prefix, returning whether a `g` was pending (and
+    /// clearing it either way).
+    pub const fn take_pending_g(&mut self) -> bool {
+        let was = self.pending_g;
+        self.pending_g = false;
+        was
+    }
+
+    /// Cancel any pending `gg` prefix (a non-`g` key was pressed).
+    pub const fn clear_pending_g(&mut self) {
+        self.pending_g = false;
+    }
+
     /// Toggle focus between the folder pane and the item list.
     pub fn focus_next(&mut self) {
         self.revealed = None;
@@ -1511,6 +1585,44 @@ mod tests {
         assert_eq!(name, "github");
     }
 
+    #[test]
+    fn vim_motions_jump_and_clamp() {
+        let entries: Vec<ListEntry> = (0..25).map(|i| entry(&format!("e{i}"), None)).collect();
+        let mut app = App::browsing(status(), entries);
+        assert_eq!(app.item_sel, 0);
+        app.move_bottom();
+        assert_eq!(app.item_sel, 24, "G lands on the last row");
+        app.move_top();
+        assert_eq!(app.item_sel, 0, "gg lands on the first row");
+        app.page_down();
+        assert_eq!(app.item_sel, VIM_PAGE, "Ctrl-d moves a half-page");
+        app.page_up();
+        assert_eq!(app.item_sel, 0, "Ctrl-u clamps at the top");
+        // page motions clamp at the bottom.
+        app.move_bottom();
+        app.page_down();
+        assert_eq!(app.item_sel, 24, "Ctrl-d clamps at the last row");
+    }
+
+    #[test]
+    fn move_bottom_on_empty_list_is_a_noop() {
+        let mut app = App::browsing(status(), vec![]);
+        app.move_bottom();
+        assert_eq!(app.item_sel, 0);
+    }
+
+    #[test]
+    fn pending_g_arms_once_then_fires() {
+        let mut app = App::browsing(status(), vec![entry("a", None)]);
+        assert!(!app.take_pending_g(), "nothing pending initially");
+        app.arm_pending_g();
+        assert!(app.take_pending_g(), "first take after arm fires gg");
+        assert!(!app.take_pending_g(), "and is cleared afterwards");
+        app.arm_pending_g();
+        app.clear_pending_g();
+        assert!(!app.take_pending_g(), "a non-g key cancels the prefix");
+    }
+
     #[test]
     fn search_edit_via_unified_path_reanchors_selection() {
         let entries = vec![entry("aa", None), entry("ab", None), entry("zz", None)];

crates/vault-tui/src/main.rs

@@ -194,12 +194,12 @@ async fn load_app(socket: &Path) -> App {
         Ok(Response::Error(err)) => App::message("Error", err.to_string(), None),
         Ok(other) => App::message("Error", format!("unexpected response: {other:?}"), None),
     };
-    // Reserved accessibility preference (`ui.reduced_motion`): record it on the
-    // App so a future animated element can honor it. No visible effect yet.
-    app.reduced_motion = vault_config::load()
-        .ok()
-        .and_then(|c| c.reduced_motion())
-        .unwrap_or(false);
+    // Apply TUI config preferences: `tui.vim` (vim motions) and the reserved
+    // `ui.reduced_motion` flag. One load, both flags.
+    if let Ok(cfg) = vault_config::load() {
+        app.vim = cfg.tui_vim().unwrap_or(false);
+        app.reduced_motion = cfg.reduced_motion().unwrap_or(false);
+    }
     app
 }
 
@@ -302,6 +302,44 @@ async fn submit_unlock(state: &mut App, socket: &Path) {
 
 /// Normal-mode keys — navigation, reveal/copy, and mode entry.
 async fn handle_normal_key(state: &mut App, key: KeyEvent, socket: &Path) {
+    // Vim mode (`tui.vim`) adds jump motions and remaps the generator to Ctrl-g
+    // so `g` can be the `gg` prefix. Intercept before the normal match (which
+    // matches `g`/`u`/`d` without checking modifiers).
+    if state.vim {
+        let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
+        match key.code {
+            KeyCode::Char('g') if !ctrl => {
+                if state.take_pending_g() {
+                    state.move_top();
+                } else {
+                    state.arm_pending_g();
+                }
+                return;
+            }
+            KeyCode::Char('g') if ctrl => {
+                state.clear_pending_g();
+                state.open_generator();
+                return;
+            }
+            KeyCode::Char('G') => {
+                state.clear_pending_g();
+                state.move_bottom();
+                return;
+            }
+            KeyCode::Char('d') if ctrl => {
+                state.clear_pending_g();
+                state.page_down();
+                return;
+            }
+            KeyCode::Char('u') if ctrl => {
+                state.clear_pending_g();
+                state.page_up();
+                return;
+            }
+            // Any other key cancels a pending `g` and falls through.
+            _ => state.clear_pending_g(),
+        }
+    }
     match key.code {
         KeyCode::Char('q') => state.quit(),
         // Esc peels back one layer: an active search filter first, then quit.