Update dependencies and enhance logging functionality

- Added the `dirs` crate version 6.0.0 to manage directory paths more effectively.
- Introduced a new `write_log_header` function to standardize log file headers, including project and command details.
- Updated logging path to use the home directory for log storage, improving accessibility.
- Adjusted documentation to reflect the new logging path format.

These changes aim to improve the logging system's clarity and maintainability while ensuring proper directory management.

Cargo.lock

@@ -200,6 +200,7 @@ dependencies = [
  "crossbeam-channel",
  "csv",
  "data-encoding",
+ "dirs 6.0.0",
  "embed-resource",
  "filetime",
  "flate2",

Cargo.toml

@@ -109,6 +109,7 @@ clap_complete = "4"
 profiling = "1.0.17"
 yaml-rust2 = "0.11.0"
 data-encoding = "2.10.0"
+dirs = "6"
 pathdiff = "0.2.3"
 
 blake3 = "1.8.3"

src/logging.rs

@@ -32,6 +32,27 @@ fn session_log_filename(command_name: &str) -> String {
     )
 }
 
+fn write_log_header(file: &mut std::fs::File, command_name: &str, project_dir: Option<&Path>) {
+    let now = time::OffsetDateTime::now_utc();
+    let version = env!("CARGO_PKG_VERSION");
+    let project = project_dir
+        .map(|p| p.display().to_string())
+        .unwrap_or_else(|| "none".into());
+    let cwd = std::env::current_dir()
+        .map(|p| p.display().to_string())
+        .unwrap_or_else(|_| "unknown".into());
+
+    let _ = writeln!(
+        file,
+        "=== Atlas v{version} ===\n\
+         Command: {command_name}\n\
+         Project: {project}\n\
+         Working dir: {cwd}\n\
+         Started: {now}\n\
+         ==="
+    );
+}
+
 pub fn init_logging(
     verbosity: u8,
     color: ColorChoice,
@@ -66,8 +87,8 @@ pub fn init_logging(
 
     let mut file_guard: Option<tracing_appender::non_blocking::WorkerGuard> = None;
 
-    let file_layer = if let (Some(dir), Some(level)) = (project_dir, file_log_level) {
+    let file_layer = if let (Some(level), Some(home)) = (file_log_level, dirs::home_dir()) {
-        let log_dir = dir.join(".atlas").join("logs");
+        let log_dir = home.join(".atlas").join("logs");
 
         match std::fs::create_dir_all(&log_dir) {
             Ok(()) => {
@@ -81,7 +102,9 @@ pub fn init_logging(
                     .append(true)
                     .open(&log_path)
                 {
-                    Ok(file) => {
+                    Ok(mut file) => {
+                        write_log_header(&mut file, command_name, project_dir);
+
                         let (non_blocking, guard) = tracing_appender::non_blocking(file);
                         file_guard = Some(guard);
 

src/project.rs

@@ -142,7 +142,7 @@ pub struct Project {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ignore_hidden_services: Option<bool>,
 
-    /// Controls the log level for file-based logging to `.atlas/logs/`.
+    /// Controls the log level for file-based logging to `~/.atlas/logs/`.
     /// Values: "trace" (default), "debug", "info", "warn", "error", "none".
     /// When "none", file logging is disabled entirely.
     #[serde(skip_serializing_if = "Option::is_none")]