Add bookmark system

Author: andornaut

README.md

@@ -13,6 +13,7 @@ FileCTRL is a light, opinionated, responsive, theme-able, and simple Text User I
 - File operations: chmod, create directory, and [copy/cut paste across instances/windows](#copy--paste)
 - Go to path with path completion suggestions
 - Recursive search
+- [Bookmarks](#bookmarks) - save and quickly return to frequently-used folders
 - Responsive layout: adapts columns and content to small and large terminal windows
 
 ## Installation
@@ -82,6 +83,22 @@ Mark files to apply bulk operations (chmod, copy, cut, delete) to multiple items
 - <kbd>Esc</kbd> clears all marks and exits range mode
 - Marks and clipboard are mutually exclusive -marking clears the clipboard
 
+### Bookmarks
+
+Bookmarks are symlinks to folders, stored in a `bookmarks/` directory beside
+the resolved config file (e.g. `~/.config/filectrl/bookmarks/`, or
+`<dir>/bookmarks/` when `--config <dir>/config.toml` is used).
+
+- <kbd>B</kbd> adds a bookmark for the **current directory**. A prompt asks for
+  the bookmark name, defaulting to the current directory's name. Names must be
+  unique, cannot be empty, and cannot contain a path separator.
+- <kbd>'</kbd> or <kbd>&#96;</kbd> shows all bookmarks in the table. This is an
+  ephemeral view (the breadcrumbs show `[Bookmarks]`); press <kbd>Esc</kbd> to
+  return to the previous directory.
+- Opening a bookmark navigates to the linked folder.
+- Bookmarks can be renamed (<kbd>r</kbd>) or deleted (<kbd>d</kbd>) like regular
+  files; this renames/deletes the symlink, never the target folder.
+
 ### Default keybindings
 
 All keybindings can be [customized](#customizing-keybindings).
@@ -110,12 +127,14 @@ Create directory | <kbd>c</kbd>
 Delete | <kbd>d</kbd>/<kbd>Delete</kbd>
 Filter | <kbd>f</kbd>/<kbd>\</kbd>
 Search | <kbd>/</kbd>
+Add bookmark | <kbd>B</kbd> (Uppercase)
+Show bookmarks | <kbd>'</kbd>/<kbd>&#96;</kbd>
 Refresh | <kbd>Ctrl</kbd>+<kbd>r</kbd>/<kbd>F5</kbd>
 Sort by name, modified, size | <kbd>n</kbd>, <kbd>m</kbd>, <kbd>s</kbd>
 Toggle show hidden files | <kbd>.</kbd>
 Cancel file or search operations | <kbd>K</kbd> (Uppercase)
 Clear alerts, progress | <kbd>Ctrl</kbd>+<kbd>a</kbd>, <kbd>Ctrl</kbd>+<kbd>p</kbd>
-Clear clipboard/filter/marks/search | <kbd>Esc</kbd>
+Clear clipboard/filter/marks/search, exit bookmarks view | <kbd>Esc</kbd>
 Toggle help | <kbd>?</kbd>
 Quit | <kbd>q</kbd>
 
@@ -244,7 +263,7 @@ Section | Description
 `prompt` | Input prompt (`cursor`, `input`, `label`, `selected`)
 `scrollbar` | Scrollbar (`ends`, `thumb`, `track`, plus `show_ends` boolean)
 `status` | Status bar (`detail`, `label`)
-`table` | File table (`body`, `header`, `header_sorted`, `selected`, `marked`, `delete`)
+`table` | File table (`body`, `header`, `header_sorted`, `selected`, `marked`, `delete`, `bookmark`)
 
 #### LS_COLORS integration
 

src/app/config.rs

@@ -65,6 +65,7 @@ struct RawConfig {
 }
 
 pub struct Config {
+    pub config_dir: PathBuf,
     pub file_system: FileSystemConfig,
     pub is_truecolor: bool,
     pub keybindings: KeyBindings,
@@ -164,7 +165,13 @@ impl Config {
         // CLI --include paths are merged last, so they take precedence over everything
         value = merge_include_paths(value, include_paths)?;
 
-        Self::parse_value(value)
+        Self::parse_value(value, config_dir)
+    }
+
+    /// The directory containing the resolved config file. Bookmarks live in a
+    /// `bookmarks/` subdirectory beside it.
+    pub fn bookmarks_dir(&self) -> PathBuf {
+        self.config_dir.join("bookmarks")
     }
 
     /// Resolves the config's `include_files` array into absolute-or-relative
@@ -203,7 +210,11 @@ impl Config {
             .collect()
     }
 
-    fn parse_value(value: Value) -> Result<Self> {
+    fn parse_value(value: Value, config_dir: Option<PathBuf>) -> Result<Self> {
+        let config_dir = config_dir
+            .or_else(|| Self::default_config_dir().ok())
+            .unwrap_or_default();
+
         let raw: RawConfig = value
             .try_into()
             .map_err(|error| anyhow!("Cannot deserialize config: {error}"))?;
@@ -217,6 +228,7 @@ impl Config {
         let keybindings = KeyBindings::new(&raw.keybindings)?;
 
         let mut config = Config {
+            config_dir,
             file_system: raw.file_system,
             is_truecolor: false,
             keybindings,

src/app/config/default_config.toml

@@ -42,6 +42,7 @@ sort_directories_first = true
 # and modifier prefixes ("Ctrl+c", "Ctrl+Shift+a").
 [keybindings]
 # Normal mode
+add_bookmark = "B"
 back = ["h", "b", "Backspace"]
 cancel_task = "K"
 chmod = "P"
@@ -66,6 +67,7 @@ range_mark = "V"
 refresh = ["Ctrl+r", "F5"]
 rename = ["r", "F2"]
 search = "/"
+show_bookmarks = ["'", "`"]
 select_first = ["g", "^"]
 select_last = ["G", "$"]
 select_middle = "z"

src/app/config/default_theme.toml

@@ -228,6 +228,11 @@ fg = "#DDDCCC"
 bg = "#423F2E"
 fg = "#DDDCCC"
 
+[theme.table.bookmark]
+bg = "#423F2E"
+fg = "#E0A85C" # Amber
+modifiers = ["bold"]
+
 [theme.table.delete]
 bg = "#d2bb84" # Tan
 fg = "#24201A"
@@ -479,6 +484,11 @@ fg = "253" # #dadada
 bg = "237" # #3a3a3a
 fg = "253" # #dadada
 
+[theme256.table.bookmark]
+bg = "237" # #3a3a3a
+fg = "179" # #d7af5f - amber
+modifiers = ["bold"]
+
 [theme256.table.delete]
 bg = "180" # #d7af87 - tan (approx #d2bb84)
 fg = "235" # #262626

src/app/config/keybindings.rs

@@ -46,13 +46,15 @@ pub enum Action {
     Paste,
 
     // File operations
+    AddBookmark,
     Chmod,
     CreateDirectory,
     Delete,
     Filter,
     Goto,
     Rename,
     Search,
+    ShowBookmarks,
 
     // Sort
     SortByModified,
@@ -151,6 +153,7 @@ keybindings! {
     normal {
         back => Back,
         go_to_previous_directory => GoToPreviousDirectory,
+        add_bookmark => AddBookmark,
         cancel_task => CancelTask,
         chmod => Chmod,
         clear_alerts => ClearAlerts,
@@ -173,6 +176,7 @@ keybindings! {
         refresh => Refresh,
         rename => Rename,
         search => Search,
+        show_bookmarks => ShowBookmarks,
         select_first => SelectFirst,
         select_last => SelectLast,
         select_middle => SelectMiddle,

src/app/config/theme.rs

@@ -276,6 +276,8 @@ impl ScrollbarConfig {
 pub struct Table {
     body: StyleConfig,
     #[serde(default)]
+    bookmark: StyleConfig,
+    #[serde(default)]
     delete: StyleConfig,
     header: StyleConfig,
     header_sorted: StyleConfig,
@@ -286,6 +288,7 @@ pub struct Table {
 
 impl Table {
     style_getter!(body);
+    style_getter!(bookmark);
     style_getter!(delete);
     style_getter!(header);
     style_getter!(header_sorted);

src/command.rs

@@ -24,6 +24,10 @@ pub enum PromptAction {
         paths: Vec<PathInfo>,
         mode: String,
     },
+    AddBookmark {
+        directory: PathInfo,
+        name: String,
+    },
     #[default]
     CreateDirectory,
     Delete(usize),
@@ -77,6 +81,14 @@ pub enum Command {
         srcs: Vec<PathInfo>,
         dest: PathInfo,
     },
+    AddBookmark {
+        directory: PathInfo,
+        name: String,
+    },
+    ShowBookmarks, // Intent: resolved by FileSystem into ShowedBookmarks
+    ShowedBookmarks {
+        bookmarks: Vec<PathInfo>,
+    },
     CreateDirectory(String),
     Delete(Vec<PathInfo>),
     Move {

src/file_system.rs

@@ -259,6 +259,39 @@ impl FileSystem {
         self.refresh()
     }
 
+    fn add_bookmark(&mut self, target: &PathInfo, name: &str) -> CommandResult {
+        match operations::add_bookmark(target, name) {
+            Err(error) => Command::AlertError(error.to_string()).into(),
+            Ok(_) => Command::AlertInfo(format!("Bookmark {name:?} added")).into(),
+        }
+    }
+
+    /// Read every entry in the bookmarks directory and send them as a single
+    /// batch. Synchronous: one small directory of symlinks, no streaming.
+    fn show_bookmarks(&self) {
+        let dir = Config::global().bookmarks_dir();
+        if let Err(error) = fs::create_dir_all(&dir) {
+            let _ = self.command_tx.send(Command::AlertError(format!(
+                "Cannot create bookmarks directory {dir:?}: {error}"
+            )));
+            return;
+        }
+        match fs::read_dir(&dir) {
+            Ok(entries) => {
+                let bookmarks: Vec<PathInfo> = entries
+                    .flatten()
+                    .filter_map(|entry| PathInfo::try_from(&entry.path()).ok())
+                    .collect();
+                let _ = self.command_tx.send(Command::ShowedBookmarks { bookmarks });
+            }
+            Err(error) => {
+                let _ = self.command_tx.send(Command::AlertError(format!(
+                    "Cannot read bookmarks directory {dir:?}: {error}"
+                )));
+            }
+        }
+    }
+
     fn create_directory(&mut self, name: &str) -> CommandResult {
         match operations::create_directory(self.current_directory(), name) {
             Err(error) => anyhow!("Failed to create directory {name:?}: {error}").into(),

src/file_system/handler.rs

@@ -11,6 +11,11 @@ impl CommandHandler for FileSystem {
                 self.cancel_search();
                 CommandResult::NotHandled
             }
+            Command::AddBookmark { directory, name } => self.add_bookmark(directory, name),
+            Command::ShowBookmarks => {
+                self.show_bookmarks();
+                CommandResult::Handled
+            }
             Command::Chmod { paths, mode } => self.chmod(paths, mode),
             Command::CreateDirectory(name) => self.create_directory(name),
             Command::Copy { srcs, dest } => {

src/file_system/operations.rs

@@ -12,7 +12,7 @@ use anyhow::{Result, anyhow};
 use log::{info, warn};
 
 use super::path_info::PathInfo;
-use crate::command::Command;
+use crate::{app::config::Config, command::Command};
 
 pub(super) fn cd(directory: &PathInfo) -> Result<(Vec<PathInfo>, usize)> {
     info!("Changing directory to {directory:?}");
@@ -75,6 +75,29 @@ pub(super) fn chmod(path: &PathInfo, mode: u32) -> Result<()> {
     Ok(())
 }
 
+pub(super) fn add_bookmark(target: &PathInfo, name: &str) -> Result<()> {
+    let name = name.trim();
+    if name.is_empty() {
+        return Err(anyhow!("Bookmark name cannot be empty"));
+    }
+    if name.contains(std::path::MAIN_SEPARATOR) {
+        return Err(anyhow!(
+            "Bookmark name cannot contain {:?}",
+            std::path::MAIN_SEPARATOR
+        ));
+    }
+    let dir = Config::global().bookmarks_dir();
+    fs::create_dir_all(&dir)?;
+    let link = dir.join(name);
+    // Reject duplicates, including a pre-existing broken symlink.
+    if link.symlink_metadata().is_ok() {
+        return Err(anyhow!("A bookmark named {name:?} already exists"));
+    }
+    info!("Creating bookmark {link:?} -> {:?}", target.path);
+    std::os::unix::fs::symlink(&target.path, &link)?;
+    Ok(())
+}
+
 pub(super) fn create_directory(parent: &PathInfo, name: &str) -> Result<()> {
     let path = parent.as_path().join(name);
     info!("Creating directory {path:?}");