refactor(frecency): make the ux the same as history, expose history-size to cli

Author: lalvarezt

.config/config.toml

@@ -28,6 +28,17 @@ history_size = 200
 # When false: history navigation is scoped to the current channel
 global_history = false
 
+# Frecency settings
+# ----------------
+# Maximum number of entries to keep in the frecency list (default: 0)
+# Enable frecency (frequency + recency) scoring to boost previously selected entries
+# Set to 0 to disable frecency functionality entirely
+frecency_size = 0
+# Whether to use global frecency across all channels (default: false)
+# When true: frecency scoring considers selections from all channels
+# When false: frecency scoring is scoped to the current channel
+global_frecency = false
+
 [ui]
 # How much space to allocate for the UI (in percentage of the screen)
 # ┌─────────────────────────┐

docs/01-Users/09-cli.md

@@ -465,6 +465,16 @@ minimum height is ensured (set by default at 15 lines)
 
 ### 📚 History Options
 
+#### `--history-size <SIZE>`
+
+**Purpose**: Set the maximum number of entries to track in search history
+
+- **Both Modes**: Same behavior
+- **Default**: 100 (from configuration)
+- **Range**: 0 to disable, positive integers to enable
+- **Use Case**: When set to a positive value, enables search history that tracks recent queries. When set to 0, search history is disabled
+- **Example**: `tv files --history-size 50`
+
 #### `--global-history`
 
 **Purpose**: Enables global history for the current session
@@ -476,23 +486,24 @@ minimum height is ensured (set by default at 15 lines)
 
 ### 🎯 Frecency Options
 
-#### `--frecency`
+#### `--frecency-size <SIZE>`
 
-**Purpose**: Enable frecency scoring to boost previously selected entries
+**Purpose**: Set the maximum number of entries to track in frecency scoring
 
 - **Both Modes**: Same behavior
-- **Default**: Disabled
-- **Use Case**: When enabled, entries that were previously selected will be ranked higher in the results list based on frequency of use and recency of access
-- **Example**: `tv files --frecency`
+- **Default**: 0 (frecency disabled)
+- **Range**: 0 to disable, positive integers to enable
+- **Use Case**: When set to a positive value, enables frecency scoring that boosts frequently used entries. When set to 0, frecency is disabled
+- **Example**: `tv files --frecency-size 100`
 
 #### `--global-frecency`
 
 **Purpose**: Use global frecency across all channels instead of channel-specific frecency
 
-- **Both Modes**: This flag only works when `--frecency` is enabled
+- **Both Modes**: Same behavior
 - **Default**: Channel-specific frecency (scoped to current channel)
 - **Use Case**: When enabled, frecency scoring will consider selections from all channels. When disabled (default), frecency is scoped to the current channel
-- **Example**: `tv files --frecency --global-frecency`
+- **Example**: `tv files --global-frecency`
 
 ### 🔧 Special Mode Options
 

man/tv.1

@@ -4,7 +4,7 @@
 .SH NAME
 television \- Cross\-platform, fast and extensible general purpose fuzzy finder TUI.
 .SH SYNOPSIS
-\fBtelevision\fR [\fB\-\-preview\-offset\fR] [\fB\-\-no\-preview\fR] [\fB\-\-hide\-preview\fR] [\fB\-\-show\-preview\fR] [\fB\-\-no\-status\-bar\fR] [\fB\-\-hide\-status\-bar\fR] [\fB\-\-show\-status\-bar\fR] [\fB\-t\fR|\fB\-\-tick\-rate\fR] [\fB\-\-watch\fR] [\fB\-k\fR|\fB\-\-keybindings\fR] [\fB\-\-expect\fR] [\fB\-i\fR|\fB\-\-input\fR] [\fB\-\-input\-header\fR] [\fB\-\-input\-prompt\fR] [\fB\-\-input\-border\fR] [\fB\-\-input\-padding\fR] [\fB\-\-preview\-header\fR] [\fB\-\-preview\-footer\fR] [\fB\-\-preview\-border\fR] [\fB\-\-preview\-padding\fR] [\fB\-\-hide\-preview\-scrollbar\fR] [\fB\-s\fR|\fB\-\-source\-command\fR] [\fB\-\-ansi\fR] [\fB\-\-source\-display\fR] [\fB\-\-source\-output\fR] [\fB\-\-results\-border\fR] [\fB\-\-results\-padding\fR] [\fB\-\-source\-entry\-delimiter\fR] [\fB\-p\fR|\fB\-\-preview\-command\fR] [\fB\-\-cache\-preview\fR] [\fB\-\-layout\fR] [\fB\-\-autocomplete\-prompt\fR] [\fB\-\-exact\fR] [\fB\-\-select\-1\fR] [\fB\-\-take\-1\fR] [\fB\-\-take\-1\-fast\fR] [\fB\-\-no\-remote\fR] [\fB\-\-hide\-remote\fR] [\fB\-\-show\-remote\fR] [\fB\-\-no\-help\-panel\fR] [\fB\-\-hide\-help\-panel\fR] [\fB\-\-show\-help\-panel\fR] [\fB\-\-ui\-scale\fR] [\fB\-\-preview\-size\fR] [\fB\-\-config\-file\fR] [\fB\-\-cable\-dir\fR] [\fB\-\-global\-history\fR] [\fB\-\-frecency\fR] [\fB\-\-global\-frecency\fR] [\fB\-\-height\fR] [\fB\-\-width\fR] [\fB\-\-inline\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICHANNEL\fR] [\fIPATH\fR] [\fIsubcommands\fR]
+\fBtelevision\fR [\fB\-\-preview\-offset\fR] [\fB\-\-no\-preview\fR] [\fB\-\-hide\-preview\fR] [\fB\-\-show\-preview\fR] [\fB\-\-no\-status\-bar\fR] [\fB\-\-hide\-status\-bar\fR] [\fB\-\-show\-status\-bar\fR] [\fB\-t\fR|\fB\-\-tick\-rate\fR] [\fB\-\-watch\fR] [\fB\-k\fR|\fB\-\-keybindings\fR] [\fB\-\-expect\fR] [\fB\-i\fR|\fB\-\-input\fR] [\fB\-\-input\-header\fR] [\fB\-\-input\-prompt\fR] [\fB\-\-input\-border\fR] [\fB\-\-input\-padding\fR] [\fB\-\-preview\-header\fR] [\fB\-\-preview\-footer\fR] [\fB\-\-preview\-border\fR] [\fB\-\-preview\-padding\fR] [\fB\-\-hide\-preview\-scrollbar\fR] [\fB\-s\fR|\fB\-\-source\-command\fR] [\fB\-\-ansi\fR] [\fB\-\-source\-display\fR] [\fB\-\-source\-output\fR] [\fB\-\-results\-border\fR] [\fB\-\-results\-padding\fR] [\fB\-\-source\-entry\-delimiter\fR] [\fB\-p\fR|\fB\-\-preview\-command\fR] [\fB\-\-cache\-preview\fR] [\fB\-\-layout\fR] [\fB\-\-autocomplete\-prompt\fR] [\fB\-\-exact\fR] [\fB\-\-select\-1\fR] [\fB\-\-take\-1\fR] [\fB\-\-take\-1\-fast\fR] [\fB\-\-no\-remote\fR] [\fB\-\-hide\-remote\fR] [\fB\-\-show\-remote\fR] [\fB\-\-no\-help\-panel\fR] [\fB\-\-hide\-help\-panel\fR] [\fB\-\-show\-help\-panel\fR] [\fB\-\-ui\-scale\fR] [\fB\-\-preview\-size\fR] [\fB\-\-config\-file\fR] [\fB\-\-cable\-dir\fR] [\fB\-\-history\-size\fR] [\fB\-\-global\-history\fR] [\fB\-\-global\-frecency\fR] [\fB\-\-frecency\-size\fR] [\fB\-\-height\fR] [\fB\-\-width\fR] [\fB\-\-inline\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICHANNEL\fR] [\fIPATH\fR] [\fIsubcommands\fR]
 .SH DESCRIPTION
 Cross\-platform, fast and extensible general purpose fuzzy finder TUI.
 .SH OPTIONS
@@ -381,6 +381,13 @@ Provide a custom cable directory to use.
 
 This flag works identically in both channel mode and ad\-hoc mode.
 .TP
+\fB\-\-history\-size\fR=\fIHISTORY_SIZE\fR
+Maximum number of entries to track in search history.
+
+When set to 0, search history is disabled.
+When set to a positive value, search history is enabled and will track
+up to this many recent search queries.
+.TP
 \fB\-\-global\-history\fR
 Use global history instead of channel\-specific history.
 
@@ -389,22 +396,21 @@ This flag only works in channel mode.
 When enabled, history navigation will show entries from all channels.
 When disabled (default), history navigation is scoped to the current channel.
 .TP
-\fB\-\-frecency\fR
-Enable frecency scoring to boost previously selected entries.
-
-This flag works in both channel mode and ad\-hoc mode.
-
-When enabled, entries that were previously selected will be ranked higher
-in the results list based on frequency of use and recency of access.
-.TP
 \fB\-\-global\-frecency\fR
 Use global frecency across all channels instead of channel\-specific frecency.
 
-This flag only works when \-\-frecency is enabled.
+This flag works identically in both channel mode and ad\-hoc mode (if global is used).
 
 When enabled, frecency scoring will consider selections from all channels.
 When disabled (default), frecency is scoped to the current channel.
 .TP
+\fB\-\-frecency\-size\fR=\fIFRECENCY_SIZE\fR
+Maximum number of entries to track in frecency scoring.
+
+When set to 0 (default), frecency scoring is disabled.
+When set to a positive value, frecency scoring is enabled and will track
+up to this many frequently used entries.
+.TP
 \fB\-\-height\fR=\fIINTEGER\fR
 Height in lines for non\-fullscreen mode.
 

television/app.rs

@@ -4,7 +4,7 @@ use crate::{
     channels::{entry::Entry, prototypes::ActionSpec},
     config::layers::LayeredConfig,
     event::{Event, EventLoop, InputEvent, Key, MouseInputEvent},
-    frecency::{DEFAULT_FRECENCY_SIZE, Frecency},
+    frecency::Frecency,
     history::History,
     render::{RenderingTask, UiState, render},
     television::{Mode, Television},
@@ -121,25 +121,20 @@ impl App {
         let television =
             Television::new(action_tx.clone(), layered_config, cable_channels);
 
+        // Initialize history
         let mut history = History::new(
             television.merged_config.history_size,
             &television.merged_config.channel_name,
             television.merged_config.global_history,
-            &television.merged_config.data_dir.clone(),
+            &television.merged_config.data_dir,
         );
         if let Err(e) = history.init() {
             error!("Failed to initialize history: {}", e);
         }
 
         // Initialize frecency
-        let frecency_size = if television.merged_config.frecency {
-            DEFAULT_FRECENCY_SIZE
-        } else {
-            0
-        };
-
         let mut frecency = Frecency::new(
-            frecency_size,
+            television.merged_config.frecency_size,
             &television.merged_config.channel_name,
             television.merged_config.global_frecency,
             &television.merged_config.data_dir,

television/cli/args.rs

@@ -505,6 +505,14 @@ pub struct Cli {
     #[arg(long, value_name = "PATH", verbatim_doc_comment, value_parser = validate_directory_path)]
     pub cable_dir: Option<String>,
 
+    /// Maximum number of entries to track in search history.
+    ///
+    /// When set to 0, search history is disabled.
+    /// When set to a positive value, search history is enabled and will track
+    /// up to this many recent search queries.
+    #[arg(long, verbatim_doc_comment)]
+    pub history_size: Option<usize>,
+
     /// Use global history instead of channel-specific history.
     ///
     /// This flag only works in channel mode.
@@ -514,24 +522,24 @@ pub struct Cli {
     #[arg(long, verbatim_doc_comment)]
     pub global_history: bool,
 
-    /// Enable frecency scoring to boost previously selected entries.
-    ///
-    /// This flag works in both channel mode and ad-hoc mode.
-    ///
-    /// When enabled, entries that were previously selected will be ranked higher
-    /// in the results list based on frequency of use and recency of access.
-    #[arg(long, verbatim_doc_comment)]
-    pub frecency: bool,
-
     /// Use global frecency across all channels instead of channel-specific frecency.
     ///
-    /// This flag only works when --frecency is enabled.
+    /// This flag works identically in both channel mode and ad-hoc mode (if global is used).
+    //  Otherwise if just works for channel mode.
     ///
     /// When enabled, frecency scoring will consider selections from all channels.
     /// When disabled (default), frecency is scoped to the current channel.
     #[arg(long, verbatim_doc_comment)]
     pub global_frecency: bool,
 
+    /// Maximum number of entries to track in frecency scoring.
+    ///
+    /// When set to 0 (default), frecency scoring is disabled.
+    /// When set to a positive value, frecency scoring is enabled and will track
+    /// up to this many frequently used entries.
+    #[arg(long, verbatim_doc_comment)]
+    pub frecency_size: Option<usize>,
+
     /// Height in lines for non-fullscreen mode.
     ///
     /// This flag works identically in both channel mode and ad-hoc mode.

television/cli/mod.rs

@@ -127,8 +127,9 @@ pub struct ChannelCli {
 #[derive(Debug, Clone, Default)]
 pub struct GlobalCli {
     pub workdir: Option<PathBuf>,
+    pub history_size: Option<usize>,
     pub global_history: bool,
-    pub frecency: bool,
+    pub frecency_size: Option<usize>,
     pub global_frecency: bool,
     pub config_file: Option<PathBuf>,
     pub cable_dir: Option<PathBuf>,
@@ -372,8 +373,9 @@ pub fn post_process(cli: Cli, readable_stdin: bool) -> PostProcessedCli {
         global: GlobalCli {
             // Workdir, global history and frecency
             workdir: working_directory,
+            history_size: cli.history_size,
             global_history: cli.global_history,
-            frecency: cli.frecency,
+            frecency_size: cli.frecency_size,
             global_frecency: cli.global_frecency,
 
             // Configuration sources

television/config/layers.rs

@@ -67,7 +67,14 @@ impl LayeredConfig {
         let data_dir = self.base_config.application.data_dir.clone();
         let default_channel =
             self.base_config.application.default_channel.clone();
-        let history_size = self.base_config.application.history_size;
+        let history_size = self
+            .global_cli
+            .history_size
+            .unwrap_or(self.base_config.application.history_size);
+        let frecency_size = self
+            .global_cli
+            .frecency_size
+            .unwrap_or(self.base_config.application.frecency_size);
         let theme = self.base_config.ui.theme.clone();
         let shell_integration_commands =
             self.base_config.shell_integration.commands.clone();
@@ -398,9 +405,6 @@ impl LayeredConfig {
         let global_history = self.global_cli.global_history
             || self.channel.history.global_mode.unwrap_or_default()
             || self.base_config.application.global_history;
-        let frecency = self.global_cli.frecency
-            || self.channel.frecency.enabled.unwrap_or_default()
-            || self.base_config.application.frecency;
         let global_frecency = self.global_cli.global_frecency
             || self.channel.frecency.global_mode.unwrap_or_default()
             || self.base_config.application.global_frecency;
@@ -428,7 +432,7 @@ impl LayeredConfig {
             default_channel,
             history_size,
             global_history,
-            frecency,
+            frecency_size,
             global_frecency,
             working_directory,
             autocomplete_prompt,
@@ -521,7 +525,7 @@ pub struct MergedConfig {
     pub default_channel: String,
     pub history_size: usize,
     pub global_history: bool,
-    pub frecency: bool,
+    pub frecency_size: usize,
     pub global_frecency: bool,
     pub working_directory: Option<PathBuf>,
     pub autocomplete_prompt: Option<String>,

television/config/mod.rs

@@ -45,9 +45,9 @@ pub struct AppConfig {
     /// Whether to use global history (all channels) or channel-specific history (default)
     #[serde(default = "default_global_history")]
     pub global_history: bool,
-    /// Whether to use frecency
-    #[serde(default = "default_frecency")]
-    pub frecency: bool,
+    /// Maximum number of entries to keep in the frecency list
+    #[serde(default = "default_frecency_size")]
+    pub frecency_size: usize,
     /// Whether to use global frecency (all channels) or channel-specific frecency (default)
     #[serde(default = "default_global_frecency")]
     pub global_frecency: bool,
@@ -62,7 +62,7 @@ impl Default for AppConfig {
             default_channel: default_channel(),
             history_size: default_history_size(),
             global_history: default_global_history(),
-            frecency: default_frecency(),
+            frecency_size: default_frecency_size(),
             global_frecency: default_global_frecency(),
         }
     }
@@ -80,8 +80,8 @@ fn default_global_history() -> bool {
     false
 }
 
-fn default_frecency() -> bool {
-    false
+fn default_frecency_size() -> usize {
+    0
 }
 
 fn default_global_frecency() -> bool {

television/frecency.rs

@@ -9,7 +9,6 @@ use tracing::debug;
 
 const FRECENCY_FILE_NAME: &str = "frecency.json";
 const SECONDS_PER_DAY: f64 = 86400.0; // 24 * 60 * 60
-pub const DEFAULT_FRECENCY_SIZE: usize = 1000;
 /// Maximum number of frecent items to prioritize in search results
 /// This ensures frequently-used items get higher priority in nucleo matching
 pub const FRECENT_ITEMS_PRIORITY_COUNT: usize = 200;

tests/cli/frecency.rs

@@ -1,4 +1,4 @@
-//! Tests for CLI frecency behavior: --frecency and --global-frecency flags.
+//! Tests for CLI frecency behavior: --global-frecency flag.
 //!
 //! These tests verify Television's frecency scoring system that boosts previously
 //! selected entries in future searches based on frequency and recency of access.
@@ -15,7 +15,8 @@ fn tv_frecency_with_data_dir(
 ) -> portable_pty::CommandBuilder {
     let mut cmd = tv_local_config_and_cable_with_args(args);
     cmd.env("TELEVISION_DATA", data_dir);
-    cmd.arg("--frecency");
+    cmd.arg("--frecency-size");
+    cmd.arg("100");
     cmd
 }
 
@@ -488,7 +489,7 @@ fn test_frecency_corrupted_file_handling() {
     }
 }
 
-/// Tests frecency without the --frecency flag to ensure it's properly disabled.
+/// Tests frecency without the --frecency-size flag to ensure it's properly disabled.
 #[test]
 fn test_frecency_disabled_behavior() {
     let temp_data = TempDataDir::init_with_empty_frecency();
@@ -497,15 +498,15 @@ fn test_frecency_disabled_behavior() {
     // Create test data
     let test_entries = ["first.txt", "second.txt", "third.txt"];
 
-    // First session: select third.txt WITHOUT --frecency flag
+    // First session: select third.txt WITHOUT --frecency-size flag
     {
         let mut tester = PtyTester::new();
         let mut cmd = tv_local_config_and_cable_with_args(&[
             "--source-command",
             &format!("printf '{}'", test_entries.join("\n")),
         ]);
         cmd.env("TELEVISION_DATA", data_dir);
-        // Note: NO --frecency flag
+        // Note: NO --frecency-size flag
 
         let mut child = tester.spawn_command_tui(cmd);
 
@@ -530,7 +531,7 @@ fn test_frecency_disabled_behavior() {
             .unwrap_or_else(|_| "[]".to_string());
         assert!(
             !frecency_content.contains("third.txt"),
-            "Frecency file should not contain selected entry when --frecency flag is not used. Content:\n{}",
+            "Frecency file should not contain selected entry when --frecency-size flag is not used. Content:\n{}",
             frecency_content
         );
     }
@@ -543,7 +544,7 @@ fn test_frecency_disabled_behavior() {
             &format!("printf '{}'", test_entries.join("\n")),
         ]);
         cmd.env("TELEVISION_DATA", data_dir);
-        // Note: Still NO --frecency flag
+        // Note: Still NO --frecency-size flag
 
         let mut child = tester.spawn_command_tui(cmd);