# 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)** is the active/default frontend.
- Status: **Alpha / MVP in progress**.
- Core workflow already works for browsing, filtering, and writing outputs.

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

## Quick Start

### Requirements

- Python **3.13+**
- [uv](https://docs.astral.sh/uv/)

### Install and Run

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

For platform notes and troubleshooting, 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 (today)

- Browser filtering: name pattern + type
- `rename_pattern` (label in UI: Rename)
- `image_transform` (unified image operation)
- `unarchive`
- `create_archive`
- `save_to`

## Release Scope (Milestone 2)

This release targets a stable MVP flow:

- browse files/folders,
- chain supported operations in panes,
- execute and inspect intermediate results,
- write final output with `save_to`,
- restore or clear last session snapshot on startup.

## Known Limitations

- Cache strategy still needs the planned metadata/content split refactor.
- Workflow/session JSON schema is currently version `1` and intended for same-version app usage.
- Advanced graph editing, plugins, and remote filesystems are not part of this release.
- Very large directories and heavy transforms may still require manual pacing.

## 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
