102 lines
4.3 KiB
Markdown
102 lines
4.3 KiB
Markdown
# Librarian
|
|
|
|
A from-scratch file explorer for Windows 11, written in Rust with the
|
|
[Iced](https://iced.rs) GUI toolkit. The goal is native-Explorer feature parity
|
|
with better performance and none of the legacy bloat.
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- **Tabbed browsing** — multiple folder tabs, each with its own navigation
|
|
history, view mode, scroll position, column layout, and search state.
|
|
- **Recursive search** — fast file search powered by an external
|
|
[ripgrep](https://github.com/BurntSushi/ripgrep) process, with **Name** and
|
|
**Contents** modes and results that stream in as they are found.
|
|
- **Details view with smart columns** — resizable, drag-to-size columns that
|
|
auto-fit to their content via exact text measurement, with widths remembered
|
|
per folder.
|
|
- **Icons & thumbnails** — a grid view backed by shell-extracted icons and
|
|
thumbnails, loaded off the UI thread so scrolling stays smooth.
|
|
- **Folder tree** — an expandable navigation tree in the left pane.
|
|
- **WSL browsing** — a "Linux" group that lists your installed WSL distros and
|
|
browses their filesystems over `\\wsl.localhost\<distro>`.
|
|
- **Standard navigation** — This PC / drives, known folders, back / forward / up,
|
|
an editable address bar, and live refresh on disk changes.
|
|
- **Built-in file operations** — copy, move, rename, delete-to-Recycle-Bin, and
|
|
open-with-default-app, routed through the Windows shell.
|
|
|
|
## Architecture
|
|
|
|
Librarian is a Cargo workspace of three crates, layered so that all `unsafe`
|
|
Win32/COM code is isolated and the domain logic stays portable and testable:
|
|
|
|
| Crate | Responsibility |
|
|
| --- | --- |
|
|
| [`librarian-core`](crates/librarian-core) | OS-agnostic domain logic: the model (entries, locations, history), directory enumeration, sorting, and search matching. No `unsafe`, no UI. |
|
|
| [`librarian-win`](crates/librarian-win) | All Windows shell integration — icons, thumbnails, `IFileOperation`, drives, known folders, WSL discovery — behind safe wrappers. Owns a dedicated COM single-threaded-apartment (STA) worker thread. UI-free (returns plain RGBA/data). |
|
|
| [`librarian-app`](crates/librarian-app) | The Iced `librarian` binary: the GUI, view model, and message loop. |
|
|
|
|
Recursive search shells out to `rg.exe` rather than re-implementing traversal;
|
|
the process is spawned with an argv array (never a shell string) so search
|
|
queries can't be interpreted as command flags.
|
|
|
|
Packaging is intentionally **out of scope** for this repo: it ships a
|
|
relocatable `librarian.exe` plus a reusable core library, and is meant to be
|
|
deployed by a separate installer project.
|
|
|
|
## Building
|
|
|
|
Requires a recent stable Rust toolchain (edition 2024, Rust ≥ 1.94) on Windows.
|
|
|
|
```powershell
|
|
# Build everything
|
|
cargo build --workspace
|
|
|
|
# Run the app
|
|
cargo run -p librarian-app
|
|
|
|
# Optimized build
|
|
cargo build --release -p librarian-app
|
|
```
|
|
|
|
The release binary lands at `target/release/librarian.exe` and is relocatable.
|
|
|
|
### Search setup (ripgrep)
|
|
|
|
Search requires `rg.exe`. At runtime Librarian looks for it next to its own
|
|
executable, then on `PATH`, then in the common winget/scoop/chocolatey
|
|
locations. If you don't already have ripgrep, the helper script provisions a
|
|
per-user copy:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\install-ripgrep.ps1
|
|
```
|
|
|
|
See [`scripts/README.md`](scripts/README.md) for options (pinning a version,
|
|
installing alongside the app, skipping the PATH update).
|
|
|
|
## Development
|
|
|
|
```powershell
|
|
cargo test --workspace --all-targets # unit tests
|
|
cargo clippy --workspace --all-targets # lints
|
|
cargo fmt --all --check # formatting
|
|
```
|
|
|
|
CI ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) runs the test suite
|
|
on `windows-2025` for every push and pull request to `main`. Releases are built
|
|
on demand via [`release.yml`](.github/workflows/release.yml), which produces
|
|
`librarian.exe` and a SHA256 checksum.
|
|
|
|
Notable engineering notes and reviews live in [`docs/`](docs):
|
|
|
|
- [`debug_log.md`](docs/debug_log.md) — running log of notable bug fixes.
|
|
- [`phase2_simplify_review.md`](docs/phase2_simplify_review.md) — code-quality pass.
|
|
- [`crash_class_review_filepilot.md`](docs/crash_class_review_filepilot.md) —
|
|
defensive review against a known file-explorer crash class.
|
|
|
|
## License
|
|
|
|
Licensed under the [GNU Affero General Public License v3.0](LICENSE).
|