add path tranfer

Author: Kanishk2207

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "filo-rs"
-version = "0.4.1"
+version = "0.4.2"
 authors = ["Kanishk <kanishk0422@gmail.com>"]
 edition = "2021"
 rust-version = "1.85"

Cargo.toml

@@ -45,6 +45,7 @@ folder_name = "Duplicates"
 # rules = [
 #   { to = "Amazon", keywords = ["amazon"] },
 #   { to = "Documents", keywords = ["invoice", "receipt", "statement"] },
+#   { to = "~/personal/kanishk-itr", to_type = "path", keywords = ["itr"] },
 # ]
 
 [rules]
@@ -71,6 +72,9 @@ Videos    = ["mp4", "mkv", "mov", "avi", "webm", "flv", "wmv", "m4v"]
 | `duplicates.action` | `"skip" \| "move"` | `"skip"` | `scan`, `preview`, `start` |
 | `duplicates.folder_name` | `string` | `"Duplicates"` | `scan`, `preview`, `start` (when `duplicates.action="move"`) |
 | `keyword_rules.rules` | `array<table>` | `[]` | `scan`, `preview`, `start` |
+| `keyword_rules.rules[].to` | `string` | (required) | `scan`, `preview`, `start` |
+| `keyword_rules.rules[].to_type` | `"folder" \| "path"` | `"folder"` | `scan`, `preview`, `start` |
+| `keyword_rules.rules[].keywords` | `array<string>` | `[]` | `scan`, `preview`, `start` |
 | `rules.<Category>` | `array<string(extension)>` | built-in per category | `scan`, `preview`, `start` |
 
 ## Detailed reference
@@ -198,13 +202,64 @@ All fields in this section are ignored unless `rename.enabled = true`.
   - Empty `to` values and empty keywords are ignored.
   - If no keyword rule matches, routing falls through to `[rules]`.
 - Rule fields:
-  - `to` (`string`): destination category/folder name.
+  - `to` (`string`): destination folder name, or path when `to_type = "path"`.
+  - `to_type` (`"folder" | "path"`): how to read `to`. See below.
   - `keywords` (`array<string>`): match keywords for that rule.
 - Example:
   `[keyword_rules]` with
   `rules = [{ to = "Documents", keywords = ["invoice", "receipt"] }]`
   routes `May_RECEIPT.png` to `Documents` with first-match precedence.
 
+#### `keyword_rules.rules[].to_type`
+
+- Type: enum string
+- Allowed values: `"folder"`, `"path"`
+- Default: `"folder"`
+- Also accepted as: `destination_type` (alias)
+- Meaning:
+  Whether the rule's `to` value is a folder name to create inside the watch
+  root, or a filesystem path of its own.
+- Runtime behavior:
+  - `"folder"`: destination is `<watch-root>/<to>/`. Unchanged historical
+    behavior, applied whenever `to_type` is absent.
+  - `"path"`: destination is `to` itself, resolved as follows:
+    1. A leading `~` (or `~\` on Windows) expands to the home directory. A
+       `~` anywhere else in the string is left literal. Environment variables
+       are never expanded.
+    2. If the result is absolute, it is used as-is.
+    3. If the result is still relative, it is joined onto the watch root —
+       so `to = "tax/2026"` from `~/Downloads` means `~/Downloads/tax/2026/`.
+  - Missing destination directories (including parents) are created on the
+    first move, not at config load.
+  - Duplicate detection, collision-safe naming, and
+    `duplicates.action = "move"` all operate on the resolved destination, so
+    duplicates land in `<resolved-path>/<duplicates.folder_name>/`.
+  - If a rule resolves to the directory the file already sits in, the file is
+    left untouched and reported as `already in place` (`keep` in `preview`).
+    This is checked against resolved paths, so symlinked and `.`-laden
+    spellings of the same directory are recognized.
+  - Only keyword rules support `to_type`. Extension rules in `[rules]` and the
+    `other_category` fallback always route to a folder under the watch root.
+- Notes:
+  - `to_type = "folder"` is never written back to disk by `filo init`, since
+    it is the default. Existing configs keep working with no edits.
+  - `~` expansion needs a discoverable home directory. If there is none, the
+    `~` stays literal and a warning is logged, which surfaces as a folder
+    actually named `~`.
+- Example:
+  ```toml
+  [keyword_rules]
+  rules = [
+    { to = "~/personal/kanishk-itr", to_type = "path", keywords = ["itr"] },
+    { to = "/mnt/archive/scans", to_type = "path", keywords = ["scan"] },
+    { to = "tax/2026", to_type = "path", keywords = ["form16"] },
+    { to = "Amazon", keywords = ["amazon"] },
+  ]
+  ```
+  Watching `~/Downloads`, `ITR-kanishk-2026.pdf` moves to
+  `~/personal/kanishk-itr/`, `form16.pdf` to `~/Downloads/tax/2026/`, and
+  `amazon-order.pdf` to `~/Downloads/Amazon/`.
+
 ### `[rules]`
 
 - Type: map/table of category name -> extension list
@@ -237,6 +292,8 @@ These are the built-in defaults used when no custom rules are set:
 - `arrange` command filters (`--keyword`, `--extension`) are CLI options, not TOML (separate from `[keyword_rules].rules`, which affects `scan`/`preview`/`start`).
 - `scan`/`preview` depth is currently top-level only.
 - `start` watcher is currently non-recursive.
+- Keyword rules match on filename keywords only. Matching a keyword *and* an extension in one rule is not expressible in TOML today; use `filo arrange -k <keyword> -e <ext> -d <path>` for that.
+- Path destinations are not watched implicitly. If you want files that land in a `to_type = "path"` destination to be organized further, add that path to `watch.folders` yourself.
 
 ## Extending this document for future TOML options
 

docs/toml-config-reference.md

@@ -51,8 +51,8 @@ later they're impossible to navigate. Manual cleanup is a chore nobody does.
 
 It is deliberately not clever. It does not look inside files, call machine
 learning models, or invent names. It routes by keyword/extension, dedupes by
-SHA-256, and moves things into subfolders. That's the whole product — and
-that's the point.
+SHA-256, and moves things into subfolders — or into any path you name. That's
+the whole product — and that's the point.
 
 ---
 
@@ -323,8 +323,11 @@ folder_name = "Duplicates"
 # Optional ordered keyword routing in one block (first match wins):
 [keyword_rules]
 rules = [
+  # Default: `to` is a folder name, created inside each watched folder.
   { to = "Amazon", keywords = ["amazon"] },
   { to = "Documents", keywords = ["invoice", "receipt", "statement"] },
+  # `to_type = "path"` sends matches to a path of your choosing instead.
+  { to = "~/personal/kanishk-itr", to_type = "path", keywords = ["itr"] },
 ]
 
 [rules]
@@ -339,6 +342,55 @@ Images    = ["jpg", "jpeg", "png", "gif", "webp", "svg", "bmp", "tiff", "heic",
 Videos    = ["mp4", "mkv", "mov", "avi", "webm", "flv", "wmv", "m4v"]
 ```
 
+### Sending matches to a path instead of a folder
+
+By default a keyword rule's `to` is a **folder name**. filo creates that
+folder inside whichever watched folder the file came from, so
+`to = "kanishk-itr"` lands files in `~/Downloads/kanishk-itr/`.
+
+Add `to_type = "path"` to the rule and `to` becomes a **path** instead, so
+matched files can leave the watched folder entirely:
+
+```toml
+[keyword_rules]
+rules = [
+  # ~/Downloads/kanishk-itr/  (folder inside the watched folder — the default)
+  { to = "kanishk-itr", keywords = ["itr"] },
+
+  # ~/personal/kanishk-itr/  (anywhere you like)
+  { to = "~/personal/kanishk-itr", to_type = "path", keywords = ["itr"] },
+]
+```
+
+`to_type` accepts exactly two values:
+
+| Value      | Meaning                                                              |
+|------------|----------------------------------------------------------------------|
+| `"folder"` | `to` is a folder name; destination is `<watched-folder>/<to>`. Default when `to_type` is omitted. |
+| `"path"`   | `to` is a path; destination is that path.                            |
+
+Details worth knowing:
+
+- **`~` expands** to your home directory, so one config works across machines
+  and users. `$HOME` and other environment variables are **not** expanded.
+- **Relative paths are anchored to the watched folder.** With
+  `to_type = "path"` and `to = "tax/2026"`, files from `~/Downloads` land in
+  `~/Downloads/tax/2026/` — which is how you nest more than one level deep.
+- **Missing folders are created** on the first move, including parents.
+- **Absolute paths work as written**, including Windows paths like
+  `C:\\Users\\you\\personal\\itr`.
+- **Every safety guarantee still applies.** Nothing is overwritten, duplicate
+  detection runs against the path destination, and duplicates land in
+  `<path>/Duplicates/` when `duplicates.action = "move"`.
+- **A rule pointing at the folder the file is already in is a no-op.** filo
+  reports it as `already in place` and leaves the file alone rather than
+  shuffling it around or treating it as a duplicate of itself.
+- Only keyword rules can target a path. Extension rules in `[rules]` always
+  route to a folder inside the watched folder.
+
+Run `filo preview` after editing rules — it prints the full destination path
+for every file, so you can confirm the routing before anything moves.
+
 ---
 
 ## Safety guarantees
@@ -377,17 +429,22 @@ stops right before any file is touched. The output looks like:
 == /Users/you/Downloads ==
   move    /Users/you/Downloads/invoice.pdf  ->  /Users/you/Downloads/Documents/invoice.pdf
   move    /Users/you/Downloads/cat.jpg      ->  /Users/you/Downloads/Images/cat.jpg
+  move    /Users/you/Downloads/ITR-2026.pdf ->  /Users/you/personal/kanishk-itr/ITR-2026.pdf
   skip    /Users/you/Downloads/cat-copy.jpg (duplicate of /Users/you/Downloads/Images/cat.jpg)
   dup ->  /Users/you/Downloads/old.pdf      ->  /Users/you/Downloads/Documents/Duplicates/old.pdf (duplicate of ...)
 
-Preview summary (4 files examined):
-  would move:               2
+Preview summary (5 files examined):
+  would move:               3
   would skip (duplicate):   1
   would move to Duplicates: 1
 
 No changes were made. Run `filo scan` to apply.
 ```
 
+Destinations are always printed in full, so a `to_type = "path"` rule shows
+exactly where the file leaves for. A file whose rule resolves to the folder it
+already sits in shows as `keep` and is counted under `already in place`.
+
 Because the planner is pure, you can:
 
 - Preview → read the plan → edit `config.toml` → preview again, risk-free.

readme.md

@@ -40,6 +40,9 @@ WATCH_B=""
 WATCH_C=""
 ARRANGE_SRC=""
 ARRANGE_DEST=""
+# Destination of a `to_type = "path"` keyword rule. Deliberately outside every
+# watched folder, and deliberately not pre-created — filo must create it.
+PATH_DEST=""
 
 log() {
   printf '\n[%s] %s\n' "$(date '+%H:%M:%S')" "$*"
@@ -161,8 +164,10 @@ backup_existing_config() {
 write_comprehensive_config() {
   local watch_a_esc
   local watch_b_esc
+  local path_dest_esc
   watch_a_esc="$(toml_escape "${WATCH_A}")"
   watch_b_esc="$(toml_escape "${WATCH_B}")"
+  path_dest_esc="$(toml_escape "${PATH_DEST}")"
 
   # Keep this section as the single source of truth for evolving feature tests.
   cat > "${CONFIG_PATH}" <<EOF
@@ -188,6 +193,11 @@ folder_name = "Duplicates"
 
 [keyword_rules]
 rules = [
+  # Absolute path destination, outside every watched folder.
+  { to = "${path_dest_esc}", to_type = "path", keywords = ["itr"] },
+  # Relative path destination, anchored to whichever folder the file came from.
+  { to = "nested/tax", to_type = "path", keywords = ["form16"] },
+  # Folder destinations (the default) must keep working unchanged.
   { to = "Amazon", keywords = ["amazon"] },
   { to = "Finance", keywords = ["invoice", "receipt", "statement"] },
   { to = "Travel", keywords = ["ticket", "boarding"] },
@@ -331,6 +341,10 @@ seed_scan_fixtures() {
   printf 'fixture-b\n' > "${WATCH_A}/Monthly_receipt.png"
   printf 'fixture-c\n' > "${WATCH_A}/plain_photo.JPG"
 
+  # Path-destination assertions (to_type = "path").
+  printf 'fixture-itr\n' > "${WATCH_A}/kanishk_itr_2026.pdf"
+  printf 'fixture-form16\n' > "${WATCH_A}/form16_summary.pdf"
+
   # Duplicate handling assertions (action = move).
   printf 'fixture-dup\n' > "${WATCH_A}/dup_source_one.pdf"
   printf 'fixture-dup\n' > "${WATCH_A}/dup_source_two.pdf"
@@ -376,6 +390,8 @@ main() {
   WATCH_C="$(cd "${WATCH_C}" && pwd -P)"
   ARRANGE_SRC="$(cd "${ARRANGE_SRC}" && pwd -P)"
   ARRANGE_DEST="$(cd "${ARRANGE_DEST}" && pwd -P)"
+  # Left uncreated on purpose: the first move must create it.
+  PATH_DEST="$(cd "${TEST_ROOT}" && pwd -P)/external_itr"
 
   log "1) Uninstall existing filo binary (if present)"
   cargo uninstall filo >/dev/null 2>&1 || true
@@ -410,6 +426,12 @@ main() {
   assert_file "${WATCH_A}/Amazon/amazon-invoice-may.pdf"
   assert_file "${WATCH_A}/Finance/monthly-receipt.png"
   assert_file "${WATCH_A}/Images/plain-photo.jpg"
+
+  # Path destinations: absolute path outside the watch root, created on demand.
+  assert_dir "${PATH_DEST}"
+  assert_file "${PATH_DEST}/kanishk-itr-2026.pdf"
+  # Relative path destination, anchored to the watched folder it came from.
+  assert_file "${WATCH_A}/nested/tax/form16-summary.pdf"
   local dup_primary_count dup_duplicate_count
   dup_primary_count="$(find "${WATCH_A}/Documents" -maxdepth 1 -type f \( -name 'dup-source-one*.pdf' -o -name 'dup-source-two*.pdf' \) | wc -l | tr -d ' ')"
   dup_duplicate_count="$(find "${WATCH_A}/Documents/Duplicates" -maxdepth 1 -type f \( -name 'dup-source-one*.pdf' -o -name 'dup-source-two*.pdf' \) | wc -l | tr -d ' ')"
@@ -467,13 +489,18 @@ main() {
   printf 'live-amazon\n' > "${WATCH_B}/amazon_invoice_live.pdf"
   printf 'live-dup\n' > "${WATCH_B}/live_dup_one.pdf"
   printf 'live-dup\n' > "${WATCH_B}/live_dup_two.pdf"
+  # Same absolute path rule, this time from the *other* watched folder.
+  printf 'live-itr\n' > "${WATCH_B}/kanishk_itr_live.pdf"
 
   generate_bulk_files "${WATCH_A}" "live_a" "${LIVE_COUNT}"
   generate_bulk_files "${WATCH_B}" "live_b" "${LIVE_COUNT}"
 
   wait_for_file "${WATCH_B}/Amazon/amazon-invoice-live.pdf" 120 || {
     die "Watcher did not route amazon_invoice_live.pdf as expected"
   }
+  wait_for_file "${PATH_DEST}/kanishk-itr-live.pdf" 120 || {
+    die "Watcher did not route kanishk_itr_live.pdf to the path destination ${PATH_DEST}"
+  }
   wait_for_match_count "${WATCH_B}/Documents" 'live-dup-*.pdf' 1 120 || {
     die "Watcher did not place any live duplicate in Documents"
   }
@@ -535,6 +562,8 @@ main() {
   assert_dir "${WATCH_B}/Amazon"
   assert_dir "${WATCH_B}/Finance"
   assert_dir "${WATCH_B}/Documents"
+  assert_dir "${PATH_DEST}"
+  assert_dir "${WATCH_A}/nested/tax"
 
   log "All comprehensive checks passed."
   printf '\nSummary:\n'

scripts/comprehensive_e2e_test.sh

@@ -16,6 +16,7 @@ pub fn run(config: &Config) -> Result<()> {
     let mut moves = 0usize;
     let mut dup_skip = 0usize;
     let mut dup_move = 0usize;
+    let mut in_place = 0usize;
     let mut errors = 0usize;
 
     for folder in &config.watch.folders {
@@ -66,6 +67,13 @@ pub fn run(config: &Config) -> Result<()> {
                         );
                         dup_move += 1;
                     }
+                    organizer::Action::AlreadyInPlace => {
+                        println!(
+                            "  keep    {}  (its rule points at the folder it is already in)",
+                            plan.source.display()
+                        );
+                        in_place += 1;
+                    }
                 },
                 Err(e) => {
                     println!("  error   {}: {}", entry.path().display(), e);
@@ -80,6 +88,9 @@ pub fn run(config: &Config) -> Result<()> {
     println!("  would move:               {}", moves);
     println!("  would skip (duplicate):   {}", dup_skip);
     println!("  would move to Duplicates: {}", dup_move);
+    if in_place > 0 {
+        println!("  already in place:         {}", in_place);
+    }
     if errors > 0 {
         println!("  errors:                   {}", errors);
     }

src/commands/preview.rs

@@ -35,6 +35,7 @@ pub fn run(config: &Config, rename_override: bool) -> Result<()> {
 
     let mut moved = 0usize;
     let mut skipped_dup = 0usize;
+    let mut in_place = 0usize;
     let mut errors = 0usize;
 
     for (root, file) in files {
@@ -48,6 +49,7 @@ pub fn run(config: &Config, rename_override: bool) -> Result<()> {
         match process_one(&root, &file, &config) {
             Ok(Outcome::Moved) => moved += 1,
             Ok(Outcome::Skipped) => skipped_dup += 1,
+            Ok(Outcome::AlreadyInPlace) => in_place += 1,
             Err(e) => {
                 // Per the safety rules, a single file error must not crash
                 // the whole run. Log and continue.
@@ -65,12 +67,16 @@ pub fn run(config: &Config, rename_override: bool) -> Result<()> {
         "Scan complete: {} moved, {} skipped (duplicates), {} errors",
         moved, skipped_dup, errors
     );
+    if in_place > 0 {
+        println!("  {} already in their destination folder", in_place);
+    }
     Ok(())
 }
 
 enum Outcome {
     Moved,
     Skipped,
+    AlreadyInPlace,
 }
 
 fn process_one(
@@ -106,6 +112,13 @@ fn process_one(
             );
             Ok(Outcome::Skipped)
         }
+        organizer::Action::AlreadyInPlace => {
+            log::info!(
+                "scan left in place: {} is already in its destination folder",
+                plan.source.display()
+            );
+            Ok(Outcome::AlreadyInPlace)
+        }
     }
 }