commandertui 1.0.0__tar.gz

commandertui-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,173 @@
+# 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/commandertui/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

commandertui-1.0.0/commandertui/app.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import os
+
+from textual.app import App
+
+from .boot import BootScreen
+from .main_screen import MainScreen
+from .theme import css_for
+
+
+class CommanderApp(App):
+    """Owns only the screen stack. All pane behavior lives in MainScreen --
+    see its docstring for why that split matters for key bindings.
+    """
+
+    CSS = css_for("green")
+
+    def __init__(self, left_path: str | None = None, right_path: str | None = None) -> None:
+        super().__init__()
+        self.left_path = os.path.abspath(left_path or os.path.expanduser("~"))
+        self.right_path = os.path.abspath(right_path or os.path.expanduser("~"))
+
+    def on_mount(self) -> None:
+        self.push_screen(MainScreen(self.left_path, self.right_path))
+        self.push_screen(BootScreen())
+
+    # Convenience passthroughs so existing tests/tools that poke at the app
+    # directly (e.g. app._panel("left")) keep working without knowing about
+    # the MainScreen split.
+    def _panel(self, side: str):
+        return self.main_screen._panel(side)
+
+    @property
+    def main_screen(self) -> MainScreen:
+        return next(s for s in self.screen_stack if isinstance(s, MainScreen))
+
+    @property
+    def active_side(self) -> str:
+        return self.main_screen.active_side

commandertui-1.0.0/commandertui/ascii_font.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+# A minimal 5x5 block-letter font, just enough for "COMMANDER". Handwritten
+# once here rather than pulled from a figlet dependency -- it's nine glyphs,
+# not worth a library.
+_FONT: dict[str, list[str]] = {
+    "A": [" ### ", "#   #", "#####", "#   #", "#   #"],
+    "C": [" ####", "#    ", "#    ", "#    ", " ####"],
+    "D": ["#### ", "#   #", "#   #", "#   #", "#### "],
+    "E": ["#####", "#    ", "#### ", "#    ", "#####"],
+    "M": ["#   #", "## ##", "# # #", "#   #", "#   #"],
+    "N": ["#   #", "##  #", "# # #", "#  ##", "#   #"],
+    "O": [" ### ", "#   #", "#   #", "#   #", " ### "],
+    "R": ["#### ", "#   #", "#### ", "#  # ", "#   #"],
+}
+
+BLOCK = "█"  # solid block, swapped in for the '#' placeholders above
+
+
+def banner(word: str, gap: int = 1) -> str:
+    """Render `word` as 5 lines of block letters."""
+    letters = [_FONT[ch] for ch in word.upper()]
+    sep = " " * gap
+    rows = []
+    for row_index in range(5):
+        rows.append(sep.join(letter[row_index] for letter in letters).replace("#", BLOCK))
+    return "\n".join(rows)

commandertui-1.0.0/commandertui/bookmarks.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+
+CONFIG_DIR = os.path.expanduser("~/.config/commandertui")
+BOOKMARKS_FILE = os.path.join(CONFIG_DIR, "bookmarks.json")
+
+# Where Linux desktops mount removable/network drives.
+MOUNT_ROOTS = ("/run/media", "/media", "/mnt")
+
+# Nautilus (and GNOME apps generally) mount network shares -- SMB, FTP,
+# SFTP -- through GVFS rather than udisks2, so they never show up under
+# MOUNT_ROOTS. They land here instead, one FUSE directory per connection.
+GVFS_ROOT = f"/run/user/{os.getuid()}/gvfs"
+
+
+@dataclass(frozen=True)
+class Place:
+    label: str
+    path: str
+    kind: str  # "mounted" | "saved" | "home"
+
+
+def detect_mounted() -> list[Place]:
+    places: list[Place] = []
+    for root in MOUNT_ROOTS:
+        if not os.path.isdir(root):
+            continue
+        try:
+            for user_dir in os.scandir(root):
+                if not user_dir.is_dir():
+                    continue
+                # /run/media/<user>/<Label> vs /mnt/<Label> (no user subdir)
+                candidates = list(os.scandir(user_dir.path)) if root == "/run/media" else [user_dir]
+                for c in candidates:
+                    # An on-demand mount point (e.g. /mnt/i7server) exists as
+                    # an empty directory even when nothing is mounted there --
+                    # os.path.ismount() is what actually tells them apart.
+                    if c.is_dir() and os.path.ismount(c.path):
+                        places.append(Place(label=c.name, path=c.path, kind="mounted"))
+        except PermissionError:
+            continue
+    return places
+
+
+def _label_for_gvfs_entry(name: str) -> str:
+    """GVFS names a mount after its full connection URI, e.g.
+    'smb-share:server=192.168.1.10,share=Media' -- turn that into something
+    a human would recognize, falling back to the raw name if it's a shape
+    we don't specifically parse (sftp, ftp, google-drive, ...).
+    """
+    _scheme, _, rest = name.partition(":")
+    params = dict(pair.split("=", 1) for pair in rest.split(",") if "=" in pair)
+    share = params.get("share")
+    server = params.get("server") or params.get("host")
+    if share and server:
+        return f"{share} @ {server}"
+    return server or name
+
+
+def detect_network_mounts() -> list[Place]:
+    if not os.path.isdir(GVFS_ROOT):
+        return []
+    try:
+        return [
+            Place(label=_label_for_gvfs_entry(entry.name), path=entry.path, kind="network")
+            for entry in os.scandir(GVFS_ROOT)
+            if entry.is_dir()
+        ]
+    except PermissionError:
+        return []
+
+
+PROC_MOUNTS = "/proc/mounts"
+
+
+def _unescape_mount_path(path: str) -> str:
+    # /proc/mounts octal-escapes whitespace and backslashes in paths.
+    return path.replace("\\040", " ").replace("\\011", "\t").replace("\\012", "\n").replace("\\134", "\\")
+
+
+def detect_home_mounts() -> list[Place]:
+    """FUSE mounts inside $HOME, e.g. rclone's ~/365 and ~/GoogleDrive.
+    Read from /proc/mounts so only what is live right now shows up."""
+    home = os.path.expanduser("~")
+    try:
+        with open(PROC_MOUNTS) as f:
+            lines = f.readlines()
+    except OSError:
+        return []
+    places: list[Place] = []
+    for line in lines:
+        parts = line.split()
+        if len(parts) < 3 or not parts[2].startswith("fuse."):
+            continue
+        path = _unescape_mount_path(parts[1])
+        if path.startswith(home + os.sep):
+            places.append(Place(label=os.path.basename(path), path=path, kind=parts[2][5:]))
+    return places
+
+
+def load_saved() -> list[Place]:
+    if not os.path.isfile(BOOKMARKS_FILE):
+        return []
+    try:
+        with open(BOOKMARKS_FILE) as f:
+            data = json.load(f)
+        return [Place(label=b["label"], path=b["path"], kind="saved") for b in data]
+    except Exception:
+        return []
+
+
+def save_bookmark(label: str, path: str) -> None:
+    os.makedirs(CONFIG_DIR, exist_ok=True)
+    saved = load_saved()
+    saved = [b for b in saved if b.path != path]
+    saved.append(Place(label=label, path=path, kind="saved"))
+    with open(BOOKMARKS_FILE, "w") as f:
+        json.dump([{"label": b.label, "path": b.path} for b in saved], f, indent=2)
+
+
+def remove_bookmark(path: str) -> None:
+    saved = [b for b in load_saved() if b.path != path]
+    os.makedirs(CONFIG_DIR, exist_ok=True)
+    with open(BOOKMARKS_FILE, "w") as f:
+        json.dump([{"label": b.label, "path": b.path} for b in saved], f, indent=2)
+
+
+def all_places() -> list[Place]:
+    home = Place(label="Home", path=os.path.expanduser("~"), kind="home")
+    return [home] + detect_mounted() + detect_network_mounts() + detect_home_mounts() + load_saved()