Metadata-Version: 2.4
Name: flume-engine
Version: 1.0.1
Summary: Rule-based file operations engine for Linux
Author: Matt Woolly
License-Expression: MIT
Project-URL: Homepage, https://github.com/mattWoolly/Flume
Project-URL: Repository, https://github.com/mattWoolly/Flume
Project-URL: Issues, https://github.com/mattWoolly/Flume/issues
Project-URL: Changelog, https://github.com/mattWoolly/Flume/blob/main/CHANGELOG.md
Keywords: file-management,automation,cli,watchdog,inotify
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Desktop Environment :: File Managers
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: watchdog>=4.0
Requires-Dist: send2trash>=1.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Flume

[![CI](https://github.com/mattWoolly/Flume/actions/workflows/ci.yml/badge.svg)](https://github.com/mattWoolly/Flume/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/flume-engine)](https://pypi.org/project/flume-engine/)

A rule-based file operations engine for Linux. Define rules in YAML -- when files matching patterns appear in watched directories, Flume executes actions: move, copy, rename, convert, sync, archive, deduplicate.

Think [Hazel](https://www.noodlesoft.com/) for macOS, but CLI-first, config-driven, no AI, no cloud dependency.

## Features

- **Watch directories** for new files/folders via inotify
- **Pattern matching** with glob and regex support
- **Size filtering** -- match files by min/max size
- **Actions**: move, copy, rename, trash, run shell commands, unzip, desktop notifications
- **Rule chaining** -- output of one action feeds the next
- **One-shot or daemon mode** -- run once or watch continuously
- **Dry-run mode** -- preview what would happen without touching anything
- **Summary reports** -- export dry-run results as text, JSON, or CSV
- **Structured logging** -- every operation logged with timestamps
- **Config validation** -- catch errors before they bite

## Installation

```bash
pip install flume-engine
```

Or install from source:

```bash
git clone https://github.com/mattWoolly/Flume.git
cd Flume
pip install .
```

## Quick Start

Create `~/.config/flume/rules.yaml`:

```yaml
rules:
  - name: organize-downloads
    watch: ~/Downloads
    match:
      pattern: "*.pdf"
    actions:
      - move: ~/Documents/PDFs/
```

Then run:

```bash
# Preview what would happen
flume run --dry-run

# Run once against existing files
flume run

# Or watch continuously for new files
flume watch
```

## Configuration

Rules live in `~/.config/flume/rules.yaml`:

```yaml
rules:
  - name: archive-zips
    watch: ~/Downloads
    match:
      pattern: "*.zip"
    actions:
      - unzip:
          dest: ~/Documents/extracted/
      - trash-original: true

  - name: organize-screenshots
    watch: ~/Pictures/Screenshots
    match:
      pattern: "*.png"
    actions:
      - rename: "{date:%Y-%m-%d}_{original}"
      - move: ~/Pictures/Screenshots/organized/

  - name: large-file-alert
    watch: ~/Downloads
    match:
      pattern: "*"
      min_size: 1GB
    actions:
      - notify:
          title: "Large download"
          body: "File arrived: {name}"
          urgency: critical

  - name: cleanup-old-logs
    watch: /var/log/myapp
    match:
      pattern: "*.log"
      older_than: 30
    actions:
      - compress:
          dest: /var/log/myapp/archive/
      - trash-original: true
```

## Running as a Service

Flume ships a systemd user unit in `contrib/flume.service`. To install it:

```bash
# Copy the unit file
mkdir -p ~/.config/systemd/user
cp contrib/flume.service ~/.config/systemd/user/

# Enable and start
systemctl --user daemon-reload
systemctl --user enable flume
systemctl --user start flume

# Check status
systemctl --user status flume

# View logs
journalctl --user -u flume -f
```

This runs `flume watch` under your user session. It restarts automatically on
failure and starts on login. Make sure `flume` is installed to `~/.local/bin`
(i.e. `pip install --user -e .` or `pip install -e .` in a virtualenv on your
PATH).

To keep it running after logout (on a server, for example):

```bash
loginctl enable-linger $USER
```

## Architecture

```
flume/
  cli.py          # CLI entry point (click)
  config.py       # YAML config loading and validation
  watcher.py      # inotify filesystem watcher
  matcher.py      # Pattern/rule matching engine
  actions/        # Action implementations
    move.py
    copy.py
    rename.py
    trash.py
    unzip.py
    shell.py
    notify.py
  engine.py       # Rule execution engine
  log.py          # Structured logging
```

## Requirements

- Python 3.10+
- Linux (inotify-based; macOS/BSD support planned)

## License

MIT
