Add FileWatcher spoon for automatic file organization

[danielo515]

FileWatcher Spoon

This PR adds a new spoon for automatic file organization based on pattern matching rules.

Features

• Automatic file organization with Lua pattern matching (case-insensitive)
• Desktop notifications when files are moved
• Automatic conflict resolution - appends numbers to duplicate filenames
• Tilde expansion support for paths (~ for home directory)
• Chainable API - all methods return the spoon object

Use Cases

• Organize downloads automatically (PDFs to Documents, images to Pictures, etc.)
• Sort screenshots from Desktop to a dedicated folder
• Project file organization by type
• Any scenario requiring automatic file sorting based on patterns

Example Usage

hs.loadSpoon("FileWatcher")

-- Watch Downloads folder and organize files
spoon.FileWatcher:watchDirectory("~/Downloads", {
  { pattern = "%.pdf$", destination = "~/Documents/PDFs" },
  { pattern = "%.jpg$", destination = "~/Pictures" },
  { pattern = "%.png$", destination = "~/Pictures" },
  { pattern = "%.zip$", destination = "~/Downloads/Archives" }
})

API Documentation

• Full API documentation included in docs.json (generated using hs -c "hs.doc.builder.genJSON(...)")
• Follows Hammerspoon Spoon conventions
• Includes :init(), :start(), :stop(), :watchDirectory(), :stopWatching(), and :stopAllWatchers() methods

Testing

Tested on macOS with various file types and patterns. Files are moved correctly with proper conflict resolution and notifications.

[muescha]

I would do it in a more generic way:

• Matchers:
  • PatternMatcher: checks whether a filename matches a regex
  • DateMatcher: checks for some date
• Actions:
  • FileMover
  • FileRenamer
  • ...

This makes it more extensible and open to additional options in the future:

spoon.FileWatcher:watchDirectory("~/Downloads", {
  { 
  	PatternMatcher("%.pdf$"), 
  	ActionRenameAs("{currentDate}-*"), 
  	ActionMoveTo("~/Documents/PDFs") 
  	},
  { 
  	PatternMatcher("%.png$"), 
  	ActionMoveTo("~/Pictures") 
  },
})

[danielo515]

That is indeed more flexible, but it is also (probably) harder to understand for simple users that have simple use cases.
Where are those Matchers and Actions coming from?

And, even if we agree, there isn't much interest into merging this spoon anyway. It has been sitting here for an entire year and yours is the first comment about it, so I'm not willing to put any more effort for an potential outcome of being ignored

[muescha]

These matchers and actions can be provided by the FileWatcher, and users can add their own as long as the required interfaces or parameters are available.

You are right - fewer PRs are merged in this repo. I also noticed that people publish their spoons in their own repositories (like your https://github.com/danielo515/StreamDeckButton.spoon ), so there is no need to have them in the "main default" repo.

[danielo515]

You are right - fewer PRs are merged in this repo. I also noticed that people publish their spoons in their own repositories (like your https://github.com/danielo515/StreamDeckButton.spoon ), so there is no need to have them in the "main default" repo.

Yeah, that is too bad. Given that Hammerspoon runs with user permissions and is capable of doing a lot of things, I think that a central repository where the owners audit the code is worth keeping.