✨ feat: add expected income feature with budget warnings

Implement comprehensive expected income system allowing users to:
- Set expected income per budget period
- Receive warnings when budgeted amounts exceed expected income
- View income vs budget comparisons in CLI and TUI
- Manage income expectations through new CLI commands

Includes models, storage, services, CLI integration, and TUI updates

Author: KayleeBeyene

INCOME_FEATURE_IMPLEMENTATION.md

@@ -39,6 +39,7 @@ pub enum EntityType {
     BudgetAllocation,
     BudgetTarget,
     Payee,
+    IncomeExpectation,
 }
 
 impl std::fmt::Display for EntityType {
@@ -51,6 +52,7 @@ impl std::fmt::Display for EntityType {
             EntityType::BudgetAllocation => write!(f, "BudgetAllocation"),
             EntityType::BudgetTarget => write!(f, "BudgetTarget"),
             EntityType::Payee => write!(f, "Payee"),
+            EntityType::IncomeExpectation => write!(f, "IncomeExpectation"),
         }
     }
 }

src/audit/entry.rs

@@ -0,0 +1,191 @@
+//! Income CLI commands
+//!
+//! Implements CLI commands for managing expected income per budget period.
+
+use clap::Subcommand;
+
+use crate::config::settings::Settings;
+use crate::error::{EnvelopeError, EnvelopeResult};
+use crate::models::Money;
+use crate::services::{BudgetService, IncomeService, PeriodService};
+use crate::storage::Storage;
+
+/// Income subcommands
+#[derive(Subcommand)]
+pub enum IncomeCommands {
+    /// Set expected income for a period
+    Set {
+        /// Expected income amount (e.g., "5000" or "5000.00")
+        amount: String,
+
+        /// Budget period (e.g., "2025-01" for January 2025)
+        #[arg(short, long)]
+        period: Option<String>,
+
+        /// Notes about this income expectation
+        #[arg(short, long)]
+        notes: Option<String>,
+    },
+
+    /// Show expected income for a period
+    Show {
+        /// Budget period (defaults to current month)
+        #[arg(short, long)]
+        period: Option<String>,
+    },
+
+    /// Remove expected income for a period
+    Remove {
+        /// Budget period
+        #[arg(short, long)]
+        period: Option<String>,
+    },
+
+    /// Compare expected income vs budgeted amounts
+    Compare {
+        /// Budget period (defaults to current month)
+        #[arg(short, long)]
+        period: Option<String>,
+    },
+}
+
+/// Handle an income command
+pub fn handle_income_command(
+    storage: &Storage,
+    settings: &Settings,
+    cmd: IncomeCommands,
+) -> EnvelopeResult<()> {
+    let period_service = PeriodService::new(settings);
+    let income_service = IncomeService::new(storage);
+    let budget_service = BudgetService::new(storage);
+
+    match cmd {
+        IncomeCommands::Set {
+            amount,
+            period,
+            notes,
+        } => {
+            let period = period_service.parse_or_current(period.as_deref())?;
+            let amount = Money::parse(&amount)
+                .map_err(|e| EnvelopeError::Validation(format!("Invalid amount: {}", e)))?;
+            let friendly = period_service.format_period_friendly(&period);
+
+            let expectation = income_service.set_expected_income(&period, amount, notes)?;
+
+            println!(
+                "Set expected income for {} to {}",
+                friendly, expectation.expected_amount
+            );
+
+            // Show comparison if budget exists
+            if let Some(overage) = budget_service.is_over_expected_income(&period)? {
+                println!(
+                    "Warning: You're budgeting {} more than expected income!",
+                    overage
+                );
+            } else if let Some(remaining) =
+                budget_service.get_remaining_to_budget_from_income(&period)?
+            {
+                if remaining.is_positive() {
+                    println!("Remaining to budget from income: {}", remaining);
+                } else {
+                    println!("Budget matches expected income.");
+                }
+            }
+        }
+
+        IncomeCommands::Show { period } => {
+            let period = period_service.parse_or_current(period.as_deref())?;
+            let friendly = period_service.format_period_friendly(&period);
+
+            if let Some(expectation) = income_service.get_income_expectation(&period) {
+                println!("Expected Income for {}", friendly);
+                println!("{}", "-".repeat(40));
+                println!("Amount: {}", expectation.expected_amount);
+                if !expectation.notes.is_empty() {
+                    println!("Notes:  {}", expectation.notes);
+                }
+
+                // Show budget comparison
+                let overview = budget_service.get_budget_overview(&period)?;
+                println!();
+                println!("Budget Comparison:");
+                println!("  Expected Income:  {}", expectation.expected_amount);
+                println!("  Total Budgeted:   {}", overview.total_budgeted);
+
+                let diff = expectation.expected_amount - overview.total_budgeted;
+                if diff.is_negative() {
+                    println!("  Over Budget:      {} ⚠", diff.abs());
+                } else {
+                    println!("  Remaining:        {} ✓", diff);
+                }
+            } else {
+                println!("No expected income set for {}", friendly);
+                println!("Use 'envelope income set <amount>' to set expected income.");
+            }
+        }
+
+        IncomeCommands::Remove { period } => {
+            let period = period_service.parse_or_current(period.as_deref())?;
+            let friendly = period_service.format_period_friendly(&period);
+
+            if income_service.delete_expected_income(&period)? {
+                println!("Removed expected income for {}", friendly);
+            } else {
+                println!("No expected income was set for {}", friendly);
+            }
+        }
+
+        IncomeCommands::Compare { period } => {
+            let period = period_service.parse_or_current(period.as_deref())?;
+            let friendly = period_service.format_period_friendly(&period);
+            let overview = budget_service.get_budget_overview(&period)?;
+
+            println!("Income vs Budget Comparison for {}", friendly);
+            println!("{}", "=".repeat(50));
+
+            if let Some(expectation) = income_service.get_income_expectation(&period) {
+                println!("Expected Income:     {:>12}", expectation.expected_amount);
+                println!("Total Budgeted:      {:>12}", overview.total_budgeted);
+                println!("{}", "-".repeat(50));
+
+                let diff = expectation.expected_amount - overview.total_budgeted;
+                if diff.is_negative() {
+                    println!("OVER BUDGET:         {:>12} ⚠", diff.abs());
+                    println!();
+                    println!("Warning: You're budgeting more than you expect to earn!");
+                    println!("Consider reducing budget allocations or increasing expected income.");
+                } else if diff.is_zero() {
+                    println!("Remaining to Budget: {:>12} ✓", diff);
+                    println!();
+                    println!("Your budget exactly matches expected income.");
+                } else {
+                    println!("Remaining to Budget: {:>12} ✓", diff);
+                    println!();
+                    println!("You have {} available to budget.", diff);
+                }
+
+                // Show additional info
+                if !expectation.notes.is_empty() {
+                    println!();
+                    println!("Notes: {}", expectation.notes);
+                }
+            } else {
+                println!("Expected Income:     Not set");
+                println!("Total Budgeted:      {:>12}", overview.total_budgeted);
+                println!();
+                println!("Tip: Set expected income with 'envelope income set <amount>'");
+            }
+
+            // Show available to budget (from account balances)
+            println!();
+            println!("{}", "-".repeat(50));
+            println!(
+                "Available to Budget (from accounts): {:>12}",
+                overview.available_to_budget
+            );
+        }
+    }
+
+    Ok(())
+}

src/cli/income.rs

@@ -10,6 +10,7 @@ pub mod category;
 pub mod encrypt;
 pub mod export;
 pub mod import;
+pub mod income;
 pub mod payee;
 pub mod reconcile;
 pub mod report;
@@ -24,6 +25,7 @@ pub use category::{handle_category_command, CategoryCommands};
 pub use encrypt::{handle_encrypt_command, EncryptCommands};
 pub use export::{handle_export_command, ExportCommands};
 pub use import::handle_import_command;
+pub use income::{handle_income_command, IncomeCommands};
 pub use payee::{handle_payee_command, PayeeCommands};
 pub use reconcile::{handle_reconcile_command, ReconcileCommands};
 pub use report::{handle_report_command, ReportCommands};

src/cli/mod.rs

@@ -105,6 +105,11 @@ impl EnvelopePaths {
         self.data_dir().join("targets.json")
     }
 
+    /// Get the path to income.json (income expectations)
+    pub fn income_file(&self) -> PathBuf {
+        self.data_dir().join("income.json")
+    }
+
     /// Ensure all required directories exist
     ///
     /// Creates:

src/config/paths.rs

@@ -77,6 +77,10 @@ pub enum EnvelopeError {
     /// TUI errors
     #[error("TUI error: {0}")]
     Tui(String),
+
+    /// Income expectation errors
+    #[error("Income error: {0}")]
+    Income(String),
 }
 
 impl EnvelopeError {
@@ -174,6 +178,7 @@ impl EnvelopeError {
             }
             Self::Storage(msg) => format!("Storage error: {}", msg),
             Self::Tui(msg) => format!("Display error: {}", msg),
+            Self::Income(msg) => msg.clone(),
         }
     }
 
@@ -236,6 +241,10 @@ impl EnvelopeError {
                 "Try with elevated permissions",
             ],
             Self::Tui(_) => vec!["Try resizing your terminal", "Use CLI commands instead"],
+            Self::Income(_) => vec![
+                "Check the expected income amount is positive",
+                "Run 'envelope income show' to see current income expectations",
+            ],
         }
     }
 
@@ -257,6 +266,7 @@ impl EnvelopeError {
             Self::InsufficientFunds { .. } => 13,
             Self::Storage(_) => 14,
             Self::Tui(_) => 15,
+            Self::Income(_) => 16,
         }
     }
 }

src/error.rs

@@ -3,8 +3,8 @@ use clap::{Parser, Subcommand};
 
 use envelope_cli::cli::{
     handle_account_command, handle_backup_command, handle_budget_command, handle_category_command,
-    handle_encrypt_command, handle_export_command, handle_import_command, handle_payee_command,
-    handle_reconcile_command, handle_report_command, handle_target_command,
+    handle_encrypt_command, handle_export_command, handle_import_command, handle_income_command,
+    handle_payee_command, handle_reconcile_command, handle_report_command, handle_target_command,
     handle_transaction_command, handle_transfer_command,
 };
 use envelope_cli::config::{paths::EnvelopePaths, settings::Settings};
@@ -47,6 +47,10 @@ enum Commands {
     #[command(subcommand)]
     Target(envelope_cli::cli::TargetCommands),
 
+    /// Expected income management commands
+    #[command(subcommand)]
+    Income(envelope_cli::cli::IncomeCommands),
+
     /// Backup management commands
     #[command(subcommand)]
     Backup(envelope_cli::cli::BackupCommands),
@@ -135,6 +139,9 @@ fn main() -> Result<()> {
         Some(Commands::Target(cmd)) => {
             handle_target_command(&storage, &settings, cmd)?;
         }
+        Some(Commands::Income(cmd)) => {
+            handle_income_command(&storage, &settings, cmd)?;
+        }
         Some(Commands::Backup(cmd)) => {
             handle_backup_command(&paths, &settings, cmd)?;
         }

src/main.rs

@@ -76,6 +76,7 @@ define_id!(TransactionId, "txn-");
 define_id!(CategoryId, "cat-");
 define_id!(CategoryGroupId, "grp-");
 define_id!(PayeeId, "pay-");
+define_id!(IncomeId, "inc-");
 
 #[cfg(test)]
 mod tests {