commandertui 1.0.0__py3-none-any.whl

commandertui/widgets.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import os
+from datetime import datetime
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.reactive import reactive
+from textual.widgets import DataTable, Static
+
+PARENT_MARK = ".."
+
+
+def _human_size(n: int) -> str:
+    size = float(n)
+    for unit in ("B", "K", "M", "G", "T"):
+        if size < 1024 or unit == "T":
+            return f"{size:.0f}{unit}" if unit == "B" else f"{size:.1f}{unit}"
+        size /= 1024
+    return f"{size:.1f}T"
+
+
+class FilePanel(Vertical):
+    """One side of the dual-pane view: a single-directory listing you can
+    navigate, mark entries in, and read the current path from.
+    """
+
+    path: reactive[str] = reactive(os.path.expanduser("~"))
+    active: reactive[bool] = reactive(False)
+    show_hidden: reactive[bool] = reactive(False)
+
+    def __init__(self, start_path: str, side: str, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.side = side  # "left" | "right"
+        self.marked: set[str] = set()
+        self.path = os.path.abspath(start_path)
+        self._rows: list[tuple[str, bool]] = []  # (name, is_dir), in display order
+
+    def compose(self) -> ComposeResult:
+        yield Static(self.path, id=f"{self.side}-pathbar", classes="pathbar")
+        table = DataTable(id=f"{self.side}-table", cursor_type="row")
+        table.add_columns(" ", "Name", "Size", "Modified")
+        yield table
+
+    def on_mount(self) -> None:
+        self.refresh_listing()
+
+    def watch_active(self, active: bool) -> None:
+        bar = self.query_one(f"#{self.side}-pathbar", Static)
+        bar.set_class(active, "active")
+
+    def refresh_listing(self) -> None:
+        table = self.query_one(f"#{self.side}-table", DataTable)
+        table.clear()
+        self._rows = []
+
+        entries: list[os.DirEntry] = []
+        try:
+            with os.scandir(self.path) as it:
+                entries = sorted(
+                    (e for e in it if self.show_hidden or not e.name.startswith(".")),
+                    key=lambda e: (not e.is_dir(), e.name.lower()),
+                )
+        except (PermissionError, FileNotFoundError):
+            pass
+
+        if os.path.dirname(self.path) != self.path:
+            table.add_row("", PARENT_MARK, "", "", key=PARENT_MARK)
+            self._rows.append((PARENT_MARK, True))
+
+        for entry in entries:
+            try:
+                stat = entry.stat(follow_symlinks=False)
+            except (PermissionError, FileNotFoundError):
+                continue
+            is_dir = entry.is_dir(follow_symlinks=False)
+            mark = "*" if entry.path in self.marked else ""
+            size = "<DIR>" if is_dir else _human_size(stat.st_size)
+            mtime = datetime.fromtimestamp(stat.st_mtime).strftime("%Y-%m-%d %H:%M")
+            display_name = f"{entry.name}/" if is_dir else entry.name
+            table.add_row(mark, display_name, size, mtime, key=entry.name)
+            self._rows.append((entry.name, is_dir))
+
+        bar = self.query_one(f"#{self.side}-pathbar", Static)
+        bar.update(self.path)
+
+    def selected_name(self) -> str | None:
+        table = self.query_one(f"#{self.side}-table", DataTable)
+        if table.row_count == 0:
+            return None
+        row_key = table.coordinate_to_cell_key(table.cursor_coordinate).row_key
+        return row_key.value if row_key is not None else None
+
+    def enter_selected(self) -> None:
+        name = self.selected_name()
+        if name is None:
+            return
+        if name == PARENT_MARK:
+            self.path = os.path.dirname(self.path)
+        else:
+            candidate = os.path.join(self.path, name)
+            if os.path.isdir(candidate):
+                self.path = candidate
+        self.marked.clear()
+        self.refresh_listing()
+
+    def toggle_mark_selected(self) -> None:
+        name = self.selected_name()
+        if name is None or name == PARENT_MARK:
+            return
+        full = os.path.join(self.path, name)
+        if full in self.marked:
+            self.marked.discard(full)
+            mark = ""
+        else:
+            self.marked.add(full)
+            mark = "*"
+
+        # Update just the mark cell in place rather than calling
+        # refresh_listing(): rebuilding the whole table resets the cursor to
+        # row 0, so marking an item used to bounce you straight back to the
+        # top -- annoying when marking several items in a row.
+        table = self.query_one(f"#{self.side}-table", DataTable)
+        table.update_cell_at(table.cursor_coordinate._replace(column=0), mark)
+
+    def marked_or_selected(self) -> list[str]:
+        """What an action should operate on: the marked set if non-empty,
+        otherwise just whatever is under the cursor."""
+        if self.marked:
+            return sorted(self.marked)
+        name = self.selected_name()
+        if name and name != PARENT_MARK:
+            return [os.path.join(self.path, name)]
+        return []

commandertui-1.0.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: commandertui
+Version: 1.0.0
+Summary: Dual-pane retro terminal file manager: compare, sync, copy and move folders
+Author: Humberto Barchini
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/juniorbarchini-oss/commandertui
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=8.0
+Requires-Dist: send2trash>=1.8
+Dynamic: license-file
+
+# CommanderTUI
+
+Dual-pane terminal file manager: compare two folders, sync them, or move
+files/folders between them (and to USB/SMB/any mounted path) — with a
+phosphor-green 80s-terminal look and a short modem-style boot animation.
+
+Status: **v1.0.0** — 40/40 tests passing. MIT licensed.
+
+---
+
+## Why this exists
+
+A safe, simple alternative to heavier dual-pane file managers. It was
+written after an earlier attempt of the same idea had to be scrapped for
+running an unauthenticated local HTTP server. This project deliberately:
+
+- **Never opens a network port.** Pure terminal UI (Textual), no HTTP server,
+  no webview.
+- **Never does a raw `rm -rf`.** Deletes always go through the desktop trash
+  (`send2trash` → `gio trash` → manual move into `~/.local/share/Trash`, in
+  that order).
+- **Never overwrites in place.** Copies stream into a hidden `.tmp` file next
+  to the destination and are committed with `os.replace` — a crash or
+  Ctrl+C never leaves a half-written file.
+- **Never guesses on a conflict.** Two-way sync copies each side's exclusive
+  files automatically, but a file changed on *both* sides is always shown to
+  you, never auto-resolved.
+
+## Install
+
+**Arch Linux / Omarchy.** An AUR package is on the way (`yay -S commandertui`).
+Until then, build it from the `PKGBUILD` in this repo. `makepkg` pulls in
+everything it needs:
+
+```bash
+git clone https://github.com/juniorbarchini-oss/commandertui.git
+cd commandertui/packaging/arch
+makepkg -si
+```
+
+Remove it with `sudo pacman -R commandertui`.
+
+**Other distros.** It is a regular Python package (Python 3.11+):
+
+```bash
+pipx install git+https://github.com/juniorbarchini-oss/commandertui.git
+```
+
+**From a source checkout** (development):
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e . -r requirements-dev.txt
+bin/commandertui [left-dir] [right-dir]
+```
+
+## Run
+
+| Command | What it does |
+|---|---|
+| `cmdrtui` | Opens it in its own terminal window. This is also what the **CommanderTUI** app-launcher entry runs |
+| `commandertui` | Runs it inside the terminal you are in |
+| `commandertui DIR1 DIR2` | Opens with those two folders side by side |
+
+`cmdrtui` uses your desktop's default terminal (`xdg-terminal-exec`). If that
+isn't available it tries foot, alacritty, kitty and ghostty. The window
+always gets the app-id/class `commandertui`, so a window-manager rule can
+float it. It needs about 1174x637 px to fit every key hint. On Hyprland:
+
+```ini
+# hyprland.conf
+windowrulev2 = float, class:^(commandertui)$
+windowrulev2 = size 1174 637, class:^(commandertui)$
+windowrulev2 = center, class:^(commandertui)$
+```
+
+```lua
+-- Omarchy Lua config (~/.config/hypr/hyprland.lua)
+o.window("^commandertui$", { float = true, center = true, size = { 1174, 637 } })
+```
+
+## Keys
+
+| Key | Action |
+|---|---|
+| `Tab` | Switch active pane |
+| `↑`/`↓`, `Enter` | Navigate, open directory |
+| `Backspace` | Go to parent directory |
+| `Space` | Mark/unmark item under cursor |
+| `F5` | Copy marked (or item under cursor) to the other pane |
+| `F6` | Move marked to the other pane |
+| `F7` | Create a folder in the active pane |
+| `F8` / `Delete` | Delete marked (to trash) |
+| `i` | Size: file/folder count and total bytes of marked items (background, `Esc` stops it) |
+| `h` | Show/hide hidden (dot) files in both panes |
+| `p` | Places: jump to a mounted drive (USB/SMB/rclone) or saved bookmark |
+| `c` | Compare: full recursive diff between the two panes' current folders |
+| `r` | Refresh both panes |
+| `q` | Quit |
+
+While a copy/move runs, the progress window shows two bars (current file
+and whole job, by bytes) plus speed in Mb/s and time left. `Esc` asks to
+cancel: finished files stay, the file in progress is discarded (never left
+half-written), and a move never removes a source it didn't fully copy.
+
+**Places** lists only what is mounted right now: USB drives
+(`/run/media`, `/media`, `/mnt` — checked with `ismount`, so an empty
+on-demand mount point doesn't show), GVFS/Nautilus network shares, FUSE
+mounts inside `$HOME` (e.g. `rclone mount`), and saved bookmarks.
+
+Inside **Compare**:
+
+| Key | Action |
+|---|---|
+| `m` | Mirror: make right identical to left |
+| `u` | Update: copy new/changed left → right, never deletes |
+| `b` | Two-way: propagate each side's exclusive changes; conflicts (changed on both sides) are listed, never guessed |
+| `Space` | Mark a row for manual handling |
+| `c` | Copy marked rows in whichever direction they diverge |
+| `Esc` | Back to the panes |
+
+Every bulk or destructive action shows a plain-language summary (count of
+operations, total bytes) and requires `y` to confirm.
+
+## Architecture
+
+```
+commandertui/
+├── models.py          # FileEntry, DiffEntry, OperationQueue, QueuedOp
+├── scanner.py          # os.scandir recursive tree walk
+├── diff.py             # pure comparison: left-only / right-only / modified / identical
+├── plan.py              # diff -> OperationQueue (mirror / update / two-way)
+├── sync.py               # atomic copy/move (streamed, tmp+replace), checksum verify
+├── trash.py               # 3-layer safe delete (send2trash / gio trash / manual)
+├── executor.py             # runs an OperationQueue against the filesystem
+├── bookmarks.py             # detected mounts (USB/SMB/rclone) + saved places
+├── theme.py                  # green/amber phosphor palettes
+├── boot.py                    # startup "modem" reveal animation
+├── widgets.py                  # FilePanel: one pane's directory listing
+├── modals.py                    # Confirm / Places / Input / Size / Message screens
+├── progress_screen.py            # two-bar transfer progress + cancel
+├── run_queue.py                   # confirm -> run queue in a worker thread
+├── compare_screen.py              # full diff view + bulk/manual sync actions
+├── app.py                          # CommanderApp: wires panes + keybindings
+└── cli.py                           # argument parsing, entrypoint
+```
+
+## Tests
+
+```bash
+pip install -r requirements-dev.txt
+pytest
+black commandertui tests   # formatter, line length set in pyproject.toml
+```
+
+Engine (scanner/diff/plan/sync/executor) is fully unit tested against a real
+filesystem (`tmp_path`). The UI has smoke tests via Textual's `Pilot`
+(boot sequence dismisses, pane switching, mark→copy→confirm end to end).
+
+## Not in scope
+
+No file preview, no deduplication engine, no desktop GUI wrapper — those are
+different problems.
+
+## Credits
+
+Designed and tested by Humberto Barchini. The code was written together
+with [Claude](https://www.anthropic.com/claude) (Anthropic) through
+[Claude Code](https://claude.com/claude-code): **Claude Sonnet 5** built the
+first version, **Claude Opus 5.5** did most of v0.2 and the v1.0 packaging.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

commandertui-1.0.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+commandertui/__init__.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+commandertui/app.py,sha256=Y992S7qSt1q5weamKyAAh1nKeg3RDhIRMfdUt5TsDts,1284
+commandertui/ascii_font.py,sha256=4wRQ0xQ-AXFPvyayciGQvFQot-KX5K0vCuVPmY4Q63w,1098
+commandertui/bookmarks.py,sha256=dQ8xqbam3b27fu-BA0ZNaZWKY0tC5DWcltS5KAZTbWc,4719
+commandertui/boot.py,sha256=8N8GQhVk5ul2luDtAPj-IYDIzA5mk7_unGVurvmA5pY,3567
+commandertui/cli.py,sha256=gtD8Igjyp24UfLG14rjDyVUtTMvbYjjOQDjj-PNkm-E,641
+commandertui/compare_screen.py,sha256=4wyPcrQS2xhLu0miEcr4nlU26T2xWXFBGqnQZGK4ylc,5808
+commandertui/diff.py,sha256=79hnNAs1QDW7qjsWzwBtOm5faRuMbnIa4QHZsJc6FyQ,1952
+commandertui/executor.py,sha256=KF3LVa0duk5cLqG17AMtBv0gS3k3Cb8MuIr35FIqVlY,4494
+commandertui/main_screen.py,sha256=OLVBPSBPIcecOWVKqGJvZ6ov_JNWeNwk8-zboecatBg,8207
+commandertui/modals.py,sha256=Xs-vOh4-CUKa-9ScMrz90wCOqGzrygAJ6zKUG-_-IHY,7266
+commandertui/models.py,sha256=Tu5Xdf9t1NMNgoNxKSsk1onYlty2z96J48BKaXUoNH0,1536
+commandertui/plan.py,sha256=sTXxArQblKQ7paVtqjfD0PDAHha-tMtO53fWKiMnmRs,1970
+commandertui/progress_screen.py,sha256=vzo6b6Y9TFVzsporCZMEIzo-IMkOudylXGtTdHqEshU,5005
+commandertui/run_queue.py,sha256=YybH5it1FwiPPMRxUtdQu00c6vEyg19uDC3SkBY3b20,3052
+commandertui/scanner.py,sha256=ZLhN5KKbm64UNyqGGQ_Ab5W0BucKCFaJonxyz0mXwO4,3405
+commandertui/sync.py,sha256=2BcFc4-Qta1Vr9yrxke3wSwWX8gCZmBoG0hdIq_-3Ys,5216
+commandertui/theme.py,sha256=0UZYrmdhb31dHFw666Drg9dkEY2n4jwzMpLl4N3RifY,1983
+commandertui/trash.py,sha256=-tg01AqS3RBA1xBRkqg8MX6bvJlunB3sHe282ROv3zk,1458
+commandertui/widgets.py,sha256=KJdOSTBN8rdRLJh3mar44FZ4JsGWNFYTS0Uv8DpfXxM,4989
+commandertui-1.0.0.dist-info/licenses/LICENSE,sha256=_j5_t7RHiqrm0E1_eF1bAdwTIX2Q09ojfR-c2_lBfVc,1074
+commandertui-1.0.0.dist-info/METADATA,sha256=ybrb244qCLtTsvdJnKmUk2hUZfkV7gv6Pw5rD5k3eWs,7489
+commandertui-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+commandertui-1.0.0.dist-info/entry_points.txt,sha256=tILtL7qtJSstkglZFqwO6MKE8oszeuZDXU2RnEp5geU,55
+commandertui-1.0.0.dist-info/top_level.txt,sha256=2Vurq5RqhhH2b8mf9XvAdL1fsoh9ft4l6ZKn6laDB8g,13
+commandertui-1.0.0.dist-info/RECORD,,

commandertui-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

commandertui-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+commandertui = commandertui.cli:main

commandertui-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Humberto Barchini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commandertui-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+commandertui