Metadata-Version: 2.4
Name: filemindr
Version: 1.1.0
Summary: Declarative local file pipelines in Python
Author: Jeferson Peter
Requires-Python: >=3.12
Requires-Dist: loguru
Requires-Dist: pydantic-settings
Requires-Dist: pyyaml
Requires-Dist: send2trash>=2.1.0
Requires-Dist: typer
Requires-Dist: watchfiles>=1.1.1
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Filemindr

Declarative local file automation using profiles.

Filemindr lets you describe what should happen to your files, not how.

You define rule pipelines in YAML, group them into profiles, and run them safely through a clean CLI.

Built as a learning and portfolio project with strong focus on:

- predictable behavior
- safety by default
- excellent CLI DX

---

## Features

- Profile-based configuration in `~/.filemindr`
- Declarative YAML rules
- Rule engine with priority, where the highest match wins
- Match by:
  - file extension
  - filename regex
  - file age with `older_than_days`
- Actions:
  - `move_to`
  - `copy_to`
  - `rename_template`
- Global and per-rule conflict policies:
  - `rename`
  - `skip`
  - `overwrite`
  - `trash`
- Dry-run mode
- Explain mode
- Watch mode
- Final summary report
- Structured logging with `INFO` and `DEBUG`
- Cross-platform support for Windows, macOS, and Linux

---

## Installation

```bash
pipx install filemindr
```

or

```bash
pip install filemindr
```

Development setup:

```bash
uv sync --extra dev
```

---

## Profiles

Instead of a single global YAML, Filemindr uses profiles.

Each profile lives in:

```text
~/.filemindr/rules/<profile>/rules.yaml
```

And all profiles are registered in:

```text
~/.filemindr/profiles.yaml
```

This allows:

- multiple setups such as `home`, `work`, or `media`
- explicit selection via CLI
- zero ambiguity about which config is running

---

## Quick Start

Create your first profile:

```bash
filemindr profile init home
```

This creates:

```text
~/.filemindr/
├── profiles.yaml
└── rules/
    └── home/
        └── rules.yaml
```

Open and edit the rules:

```bash
filemindr profile open home
```

Example `rules.yaml`:

```yaml
source: ~/Downloads
default_target: ~/Downloads/others
conflict_policy: rename

rules:
  - name: invoices
    priority: 100
    match:
      extensions: ["pdf"]
      regex: "(?i)invoice|nota|nf"
    action:
      move_to: ~/Downloads/finance/invoices

  - name: dated-pdfs
    priority: 70
    match:
      extensions: ["pdf"]
    action:
      move_to: ~/Downloads/archive/{yyyy}/{mm}
      rename_template: "{stem}_{yyyy}-{mm}{suffix}"

  - name: images
    priority: 40
    match:
      extensions: ["jpg", "png", "webp"]
    action:
      move_to: ~/Downloads/images
```

Important notes:

- Rule priority matters. If two rules match the same file, the higher priority wins.
- `rename_template` only defines the final file name, not folders.
- `move_to` and `copy_to` can use templates in the destination path.

Supported template fields:

- `{name}`
- `{stem}`
- `{suffix}`
- `{ext}`
- `{parent}`
- `{yyyy}`
- `{mm}`
- `{dd}`

Preview:

```bash
filemindr run -p home --dry-run
```

Verbose preview:

```bash
filemindr run -p home --dry-run --log-level DEBUG
```

Run:

```bash
filemindr run -p home
```

---

## Profile Commands

Create:

```bash
filemindr profile init home
```

List:

```bash
filemindr profile list
```

Show path:

```bash
filemindr profile show home
```

Open in editor:

```bash
filemindr profile open home
```

Remove completely:

```bash
filemindr profile remove home
```

---

## Watch Mode

Continuous:

```bash
filemindr watch -p home
```

Single batch:

```bash
filemindr watch -p home --once
```

---

## Explain Mode

Explain a directory:

```bash
filemindr explain -p home ~/Downloads
```

Explain a single file with spaces in the path:

```bash
filemindr explain -p home "C:\Users\you\Downloads\Day Trade-2025.pdf"
```

---

## Validate

```bash
filemindr validate -p home
```

---

## Doctor

```bash
filemindr doctor
```

---

## Conflict Policy

Supported values:

- `rename`
- `skip`
- `overwrite`
- `trash`

---

## Development

Install development dependencies:

```bash
uv sync --extra dev
```

Run tests:

```bash
uv run pytest -q
```

---

## Status

Current release line: `1.1.x`

---

## License

MIT
