Metadata-Version: 2.4
Name: cascade-fm
Version: 0.2.0
Summary: A visual, pipeline-driven file manager that turns file operations into composable, repeatable workflows.
Project-URL: Homepage, https://gitlab.com/cascascade/cascade
Project-URL: Repository, https://gitlab.com/cascascade/cascade
Project-URL: Issues, https://gitlab.com/cascascade/cascade/-/issues
Project-URL: Documentation, https://gitlab.com/cascascade/cascade/-/blob/main/README.md
Author-email: ladidadida <stefan@dalada.de>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: cascache-lib>=0.1.0
Requires-Dist: pillow>=10.0
Requires-Dist: pyside6>=6.6
Description-Content-Type: text/markdown

# cascade

cascade is a visual, pipeline-driven desktop file manager.

You select files, add operations in panes from left to right, and only the final pane writes to disk.

**Think of it as Unix pipes with a face.**

## Current State

- UI: **PySide6 (Qt)** desktop application.
- Status: **Alpha** — approaching first release (Milestone 2).
- Full standard file-management workflow works end-to-end.

Project details and roadmap live in [spec/design.md](spec/design.md) and [spec/roadmap.md](spec/roadmap.md).

## Quick Start

### Linux — AppImage (recommended)

Download `cascade-x86_64.AppImage` from the [releases page](https://gitlab.com/cascascade/cascade/-/releases), then:

```bash
chmod +x cascade-x86_64.AppImage
./cascade-x86_64.AppImage
```

No Python or installation required. Works on any distro with glibc 2.17+.

### Python / uv

```bash
pip install cascade-fm   # or: uv tool install cascade-fm
cascade
```

### From source

```bash
git clone <repository-url>
cd cascade
uv sync
uv run cascade
```

For troubleshooting and platform notes, see [docs/installation.md](docs/installation.md).

## How cascade works

Pipeline model:

```text
[ Browse Files ] -> [ Filter ] -> [ Transform ] -> [ Save To ]
```

- Pane 1 is the filesystem browser.
- Each next pane applies one operation to the previous pane output.
- Executing a pane marks panes to the right as stale.
- Final output is written only by the final write operation.

## Built-in Operations

| Operation | Description |
|---|---|
| `filter_extension` / `filter_name` | Browser-side filtering by extension or name glob |
| `rename` | Plain rename, search & replace, or regex replace with capture groups |
| `save_to` | Copy files to a target directory (with conflict policy) |
| `move_to` | Move files to a target directory (with conflict policy) |
| `image_transform` | Resize, convert format, rotate, compress, strip EXIF |
| `create_archive` | Create zip / tar / tar.gz / tar.bz2 / tar.xz archives |
| `unarchive` | Extract archives (with optional single-root flatten) |
| `delete_files` | Permanently delete files with in-UI confirmation |

## Features

- **Pipeline model** — chain operations left to right; only the final pane writes to disk
- **Session restore** — reopen the last pipeline on launch (configurable: ask / auto / off)
- **Workflow save/load** — save named pipelines as JSON, reload them later
- **Preferences** — start directory, default sort order, hidden-file toggle, bookmarks, language
- **Internationalisation** — ships English and German; add custom languages via `~/.cascade/translations/`
- **Caching** — intermediate results stored in a content-addressable cache for fast re-execution

## Known Limitations

- Workflow/session JSON schema is version `1`; use the same app version that wrote the file.
- Very large directories (100k+ files) and heavy image transforms may slow the UI.
- Advanced graph editing, branch pipelines, plugins, and remote filesystems are not yet implemented.
- Language change requires an application restart to take effect.

## Development

### Setup

```bash
uv sync
```

### Test / Lint / Typecheck

```bash
# tests
uv run pytest -q

# lint
uv run ruff check src tests

# typecheck
uv run pyright
```

### Optional: task runner (`just`)

```bash
just test
just lint
just format
just typecheck
just build
```

## Build / Publish

```bash
uv run python -m build
```

Upload (maintainers):

```bash
uv run twine upload dist/*
```

## License

MIT
