Merge pull request #39 from umpire274/v0.8.3

V0.8.3

Author: umpire274

CHANGELOG.md

@@ -1,27 +1,107 @@
 # Changelog
 
+## [0.8.3] – Unreleased
+
+### ✨ New features
+
+- **Import data from JSON and CSV files**
+    - New `import` command to insert events into the database from external sources.
+    - Supported formats:
+        - `JSON` (flexible structures: root array, `{ days: [...] }`, `{ holidays: [...] }`)
+        - `CSV` (with header row).
+    - Supported options:
+        - `--file <path>`: input file
+        - `--format <json|csv>` (default: `json`)
+        - `--dry-run`: simulate the import without modifying the database
+        - `--replace`: overwrite existing conflicting data
+        - `--source`: logical label describing the data origin
+
+- **National holidays support**
+    - Added new position `NationalHoliday`.
+    - National holidays:
+        - do **not** affect the user vacation balance
+        - are compatible with automatic/preventive imports (e.g. yearly calendars).
+
+- **Preventive holiday import**
+    - Allows preparing JSON/CSV files with annual holidays and importing them in advance.
+    - Reduces manual errors and forgotten entries.
+
+---
+
+### 🔧 Improvements
+
+- **Enhanced data source tracking**
+    - The `source` field of imported events now automatically includes the input format  
+      (e.g. `import (from json)`, `import (from csv)`).
+
+- **`meta` field support for imported events**
+    - Descriptive data (e.g. holiday name) is stored in the `meta` field as JSON.
+    - Example:
+      ```json
+      { "name": "New Year" }
+      ```
+
+- **Refactor of `Event::new()` constructor**
+    - The constructor now explicitly supports:
+        - `meta`
+        - `source`
+    - Clear separation between CLI-created events and imported events.
+
+- **Database query refactor**
+    - Split `db::queries` into topic-based submodules.
+    - Fixed module conflict between `queries.rs` and `queries/mod.rs`.
+
+- **Shared utilities**
+    - Added helper functions in `utils::formatting` to standardize `source` generation.
+
+---
+
+### 🛠 Fixes
+
+- Improved validation of imported records:
+    - invalid dates
+    - unsupported positions
+    - malformed rows
+- Improved import reporting:
+    - total rows
+    - imported rows
+    - skipped rows
+    - conflicts
+    - invalid rows
+
+---
+
+### 🧪 Developer notes
+
+- All import logic is isolated in the `src/import` module.
+- Full `dry-run` support for safe testing on real databases.
+- Solid foundation for future integrations (ICS calendars, APIs, external sync).
+
+---
 
 ## [0.8.2] — 2026-01-08
 
 ### ✨ Added
 
-- Added a new day position **National holiday** (**N**) to represent public holidays that do not affect personal holiday allowance. 
-- Introduced support for `--pos n` / `--pos national` in the `add` command to mark national holidays. 
+- Added a new day position **National holiday** (**N**) to represent public holidays that do not affect personal holiday
+  allowance.
+- Introduced support for `--pos n` / `--pos national` in the `add` command to mark national holidays.
 - Added idempotent database migration to extend the `events.position` CHECK constraint with the new `N` value.
 
 ### 🧠 Changed
 
-- Updated daily and compact list views to properly display **National holiday** days with neutral time and ΔWORK values. 
-- Improved semantic distinction between **Holiday** (personal leave) and **National holiday** (public holiday) in reports and summaries.
+- Updated daily and compact list views to properly display **National holiday** days with neutral time and ΔWORK values.
+- Improved semantic distinction between **Holiday** (personal leave) and **National holiday** (public holiday) in
+  reports and summaries.
 
 ### 🐞 Fixes
 
-- Ensured database migrations safely no-op when the schema is already aligned. 
+- Ensured database migrations safely no-op when the schema is already aligned.
 - Fixed SQL escaping issues in migration logging statements.
 
 ### 🧹 Internal
 
-- Extended Location enum and related parsing/formatting utilities. 
+- Extended Location enum and related parsing/formatting utilities.
 - Refined migration logging for better traceability and robustness.
 
 ---

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "rtimelogger"
-version = "0.8.2"
+version = "0.8.3"
 edition = "2024"
 authors = ["Umpire274 <umpire274@gmail.com>"]
 description = "A simple cross-platform CLI tool to track working hours, lunch breaks, and calculate surplus time"

Cargo.toml

@@ -476,6 +476,152 @@ Output path must be **absolute**.
 
 ---
 
+## Import data (JSON / CSV)
+
+Starting from **v0.8.3**, rTimelogger supports importing work sessions and holidays from external files.  
+This feature is designed to simplify **preventive data entry**, especially for **national holidays**.
+
+The import system is safe by default and provides a full **dry-run mode**.
+
+---
+
+### Supported formats
+
+#### JSON
+
+Flexible JSON structures are supported. The following formats are valid:
+
+**Root object with `holidays`:**
+
+```json
+{
+  "year": 2026,
+  "holidays": [
+    {
+      "date": "2026-01-01",
+      "name": "New Year"
+    },
+    {
+      "date": "2026-01-06",
+      "name": "Epiphany"
+    }
+  ]
+}
+```
+
+**Root object with `days`:**
+
+```json
+{
+  "days": [
+    {
+      "date": "2026-05-01",
+      "position": "N",
+      "name": "Labour Day"
+    }
+  ]
+}
+```
+
+**Root array of day objects:**
+
+```json
+[
+  {
+    "date": "2026-12-25",
+    "name": "Christmas Day"
+  }
+]
+
+```
+
+**Notes**:
+
+- `position` is optional:
+    - if omitted, it defaults to `NationalHoliday`
+- `name` is optional and stored in the event `meta` field
+
+#### CSV
+
+CSV files must include a header row.
+
+Example:
+
+```csv
+date,position,name
+2026-01-01,N,New Year
+2026-01-06,N,Epiphany
+2026-04-25,N,Liberation Day
+```
+
+**Notes**:
+
+- `position` must be a valid location code (`N`, `H`, `O`, `R`, `C`, `M`)
+- name is optional
+
+### Import command
+
+```bash
+rtimelogger import --file <path> [options]
+```
+
+**Options**
+
+- `--file <path>` : Path to the input file (required)
+
+- `--format <json|csv>` : Input format (default: json)
+
+- `--dry-run` : Simulate the import without modifying the database (strongly recommended)
+
+- `--replace` : Replace existing events for conflicting dates (dangerous)
+
+- `--source <label>` : Logical label describing the origin of imported data. The final stored value will include the
+  format automatically (e.g. import (from json))
+
+### Import behavior
+
+- Only Holiday and NationalHoliday positions are accepted by default.
+- Dates with existing work events are skipped unless --replace is used.
+- Imported holidays:
+    - do **not** affect the vacation balance
+    - are treated as regular timeline entries
+
+- Each import generates a detailed summary:
+    - total rows
+    - imported
+    - skipped
+    - conflicts
+    - invalid rows
+
+### Example (dry-run)
+
+```bash
+rtimelogger import \
+  --file holidays_2026.json \
+  --format json \
+  --dry-run
+```
+
+### Example (apply import)
+
+```bash
+rtimelogger import \
+  --file holidays_2026.csv \
+  --format csv \
+  --source calendar
+```
+
+### Metadata and traceability
+
+- Imported events store additional information in the meta field (JSON).
+- The source field tracks the origin of the data:
+    - CLI entries → cli
+    - Imports → import (from json) / import (from csv)
+
+This ensures full traceability of all events.
+
+---
+
 ## 🗄️ Database utilities — `rtimelogger db`
 
 ```bash

README.md

@@ -0,0 +1,114 @@
+use std::fs;
+
+use crate::cli::parser::Commands;
+use crate::config::Config;
+use crate::errors::{AppError, AppResult};
+use crate::import::{ImportInputFormat, import_days_from_str};
+use crate::ui::messages::{info, success, warning};
+
+use crate::utils::formatting::build_import_source;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+struct ImportDayJson {
+    date: String,
+    #[serde(default)]
+    position: Option<String>,
+    #[serde(default)]
+    name: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(untagged)]
+enum ImportJsonRoot {
+    Days { days: Vec<ImportDayJson> },
+    Holidays { holidays: Vec<ImportDayJson> },
+    Array(Vec<ImportDayJson>),
+}
+
+fn normalize_json_to_days(content: &str) -> AppResult<String> {
+    let parsed: ImportJsonRoot = serde_json::from_str(content).map_err(|e| {
+        AppError::InvalidArgs(format!(
+            "Invalid JSON. Expected one of: {{\"days\":[...]}}, {{\"holidays\":[...]}}, or a root array [...]. Details: {}",
+            e
+        ))
+    })?;
+
+    let days: Vec<ImportDayJson> = match parsed {
+        ImportJsonRoot::Days { days } => days,
+        ImportJsonRoot::Holidays { holidays } => holidays,
+        ImportJsonRoot::Array(v) => v,
+    };
+
+    // Re-emit canonical shape expected by the importer: { "days": [...] }
+    serde_json::to_string(&serde_json::json!({ "days": days }))
+        .map_err(|e| AppError::Other(format!("Internal error while normalizing JSON: {}", e)))
+}
+
+pub fn handle(cmd: &Commands, cfg: &Config) -> AppResult<()> {
+    let Commands::Import {
+        file,
+        format,
+        dry_run,
+        replace,
+        source,
+    } = cmd
+    else {
+        return Ok(());
+    };
+
+    let mut content = fs::read_to_string(file)?;
+
+    let input_format = match format.to_ascii_lowercase().as_str() {
+        "json" => ImportInputFormat::Json,
+        "csv" => ImportInputFormat::Csv,
+        _ => {
+            return Err(AppError::InvalidArgs(
+                "Invalid --format. Use 'json' or 'csv'.".into(),
+            ));
+        }
+    };
+
+    // ✅ Normalize JSON shapes (days/holidays/array) into canonical {"days":[...]}
+    if matches!(input_format, ImportInputFormat::Json) {
+        content = normalize_json_to_days(&content)?;
+    }
+
+    let imp_source = build_import_source(source, format);
+
+    let report = import_days_from_str(
+        cfg,
+        &content,
+        input_format,
+        *dry_run,
+        *replace,
+        imp_source.as_str(),
+    )?;
+
+    info(format!(
+        "Import summary{}:\n- File: {}\n- Format: {}\n- Source: {}\n- Total rows: {}\n- Imported: {}\n- Skipped (already present): {}\n- Conflicts: {}\n- Invalid rows: {}",
+        if *dry_run { " (dry-run)" } else { "" },
+        file,
+        format,
+        source,
+        report.total,
+        report.imported,
+        report.skipped_existing,
+        report.conflicts,
+        report.invalid
+    ));
+
+    if report.conflicts > 0 && !*replace {
+        warning(
+            "Some dates were skipped due to existing work events. Use --replace to override (dangerous).",
+        );
+    }
+
+    if *dry_run {
+        success("Dry-run completed. No changes were applied.");
+    } else {
+        success("Import completed.");
+    }
+
+    Ok(())
+}