xcfm 0.1.0__tar.gz

xcfm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Demin
+
+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.

xcfm-0.1.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: xcfm
+Version: 0.1.0
+Summary: Two-panel console file manager
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3
+Requires-Dist: google-cloud-storage
+Requires-Dist: oci
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth
+Dynamic: license-file
+
+# xc
+
+A two-panel console file manager inspired by Midnight Commander, written in Python.
+
+![xc](xc.png)
+
+## Intro
+
+The Python version of xc is a single self-contained script (`xc.py`) that runs via [uv](https://docs.astral.sh/uv/). This means:
+
+- **Zero setup** -- no virtualenv, no `pip install`, no `requirements.txt`. Just run `uv run xc.py`.
+- **Inline dependencies** -- the script header declares its own dependencies (`boto3`, `google-cloud-storage`, `oci`, `google-api-python-client`), and uv resolves and caches them automatically on the first run.
+- **Reproducible** -- uv pins the Python version (`>=3.11`) and handles isolation, so the script works the same way on any machine.
+- **Single file to deploy** -- copy `xc.py` to a server, a dotfiles repo, or a USB stick. There is nothing else to carry.
+
+### Installing uv
+
+```sh
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Homebrew
+brew install uv
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+After installing, run the file manager with:
+
+```sh
+uv run xc.py
+```
+
+The script has a shebang line, so you can rename it, make it executable, and put it on your PATH:
+
+```sh
+cp xc.py ~/.local/bin/xc
+chmod +x ~/.local/bin/xc
+xc
+```
+
+### Development
+
+The `pyproject.toml` in the repository is only used for local development tooling (e.g. `black` formatter settings). It is **not** needed to run xc -- `xc.py` is fully self-contained with its own inline dependency declarations.
+
+### Self-update
+
+To update xc to the latest version from GitHub:
+
+```sh
+xc -u
+```
+
+This fetches the latest `xc.py` from the repository, compares versions, and replaces the current binary if a newer version is available. The previous version is saved as `xc.prev` next to the executable.
+
+## User manual
+
+### Dual-panel concept
+
+xc shows two file panels side by side. One panel is **active** (highlighted border), the other is **inactive**. You navigate files in the active panel and use the inactive panel as a target for file operations like copy and move. Press `Tab` to switch the active panel. Press `h` / `l` to activate the left / right panel directly.
+
+On startup the active panel opens in the current working directory. The inactive panel restores the path from the previous session.
+
+### Navigation
+
+| Key                  | Action                                 |
+| -------------------- | -------------------------------------- |
+| `Up` / `k`           | Move cursor up                         |
+| `Down` / `j`         | Move cursor down                       |
+| `Enter`              | Enter directory or open VFS            |
+| `Backspace`          | Go to parent directory (or exit VFS)   |
+| `Left` / `Right`     | Page up / page down                    |
+| `PgUp` / `PgDn`      | Page up / page down                    |
+| `Home` / `^`         | Jump to first file                     |
+| `End` / `G`          | Jump to last file                      |
+| `Ctrl-D` / `Ctrl-U`  | Half-page down / up                    |
+| `Ctrl-L`             | Reload current directory               |
+| `Tab`                | Switch active panel                    |
+| `h` / `l`            | Activate left / right panel            |
+| `q`                  | Quit                                   |
+
+### File operations (`x`)
+
+Press `x` to open the **command** menu:
+
+| Key | Action                                                              |
+| --- | ------------------------------------------------------------------- |
+| `c` | **Copy** -- copy file or tagged files from active to inactive panel |
+| `m` | **Move** -- move (rename) file or tagged files                      |
+| `d` | **Delete** -- delete file or tagged files                           |
+| `k` | **Mkdir** -- create a new directory                                 |
+| `t` | **Touch** -- create an empty file                                   |
+| `p` | **Chmod** -- change file permissions                                |
+| `r` | **Rename** -- rename the selected file                              |
+| `g` | **Chdir** -- type a path to navigate to                             |
+
+Copy and move operations use the inactive panel's current path as the default destination. A prompt lets you edit the destination before confirming.
+
+### Tagging and group operations
+
+Press `Space` on a file to **tag** it (marked with `+`). Tagged files are used as the source for copy, move, delete, and chmod. If nothing is tagged, the operation applies to the file under the cursor.
+
+| Key     | Action                                              |
+| ------- | --------------------------------------------------- |
+| `Space` | Toggle tag on current file and move down            |
+| `+`     | Tag all files in current directory                  |
+| `_`     | Untag all                                           |
+| `i`     | Calculate sizes of tagged (or selected) directories |
+
+### Bookmarks (`b`)
+
+Press `b` to open the **bookmark** menu for quick jumps to common directories (home, desktop, downloads, etc.).
+
+### Remotes (`r`)
+
+Press `r` to open the **remote** menu. This scans `~/.xc/remotes/` for VFS config files (`.s3`, `.gcs`, `.oci`, `.gdrive`, `.ssh`) and presents them as a selector. Choosing a remote opens it on the active panel, just like pressing `Enter` on a VFS config file.
+
+This lets you keep all your remote connections in one place and access them from any directory without navigating to where the config files live.
+
+Example setup:
+
+```text
+~/.xc/remotes/
+  production.s3
+  analytics.gcs
+  storage.oci
+  shared-drive.gdrive
+  webserver.ssh
+```
+
+### Editor (`e`) and view (`v`)
+
+Press `e` to open a file in an editor, or `v` to view it. These menus launch external commands with the current file path substituted via macros (see below). On remote VFS (SSH, S3, GCS, OCI, GDrive), the file is automatically downloaded to a temp location, opened locally, and uploaded back if modified.
+
+### Running shell commands
+
+There are two command-line modes:
+
+| Key | Mode       | Behavior                                       |
+| --- | ---------- | ---------------------------------------------- |
+| `;` | **Direct** | Run a command interactively in the terminal    |
+| `:` | **Piped**  | Run a command; output is piped through `less`  |
+
+Both modes support macro expansion. The command runs in the active panel's current directory. If the command exits with a non-zero code, the error is shown in the bottom line.
+
+### Alternate screen and command output
+
+xc runs on the terminal's **alternate screen** -- the panels never mix with your shell's scroll buffer. When you run a shell command (`;` or `:`), xc temporarily switches back to the **main screen** so the command's output is preserved in the normal scroll buffer.
+
+To review previous command output without running anything:
+
+| Key              | Action                          |
+| ---------------- | ------------------------------- |
+| `Esc` `Esc`      | Switch to main screen           |
+| `Ctrl-O`         | Switch to main screen           |
+| `Esc` or `Ctrl-O` | Return to panels (main screen) |
+
+Once on the main screen you can scroll through your terminal's history as usual. Press `Esc` or `Ctrl-O` to return to the file panels.
+
+### Search (`/`)
+
+Press `/` to start an incremental search. Type characters to filter -- the cursor jumps to the first matching file. Press `Enter` to accept or `Esc` to cancel.
+
+### Grep (`s` / `S`)
+
+Press `s` for case-sensitive search or `S` for case-insensitive search. This is a two-step prompt:
+
+1. **File pattern** -- `grep in ` (or `igrep in `) appears. Enter a glob pattern to filter by filename. Leave empty to search all files.
+2. **Search string** -- `grep in *.py for ` appears. Enter the text to find. Leave empty to list files matching the pattern only.
+
+The file pattern uses Unix shell-style wildcards (matched against the filename only, not the path):
+
+| Pattern   | Meaning                                          | Example              |
+| --------- | ------------------------------------------------ | -------------------- |
+| `*`       | Matches everything                               | `*.py` -- all Python |
+| `?`       | Matches any single character                     | `?.txt` -- `a.txt`   |
+| `[seq]`   | Matches any character in *seq*                   | `[abc].py`           |
+| `[!seq]`  | Matches any character **not** in *seq*            | `[!.]cfg`            |
+
+Patterns do **not** support `**` (recursive globs) or path separators -- they match the base filename only.
+
+Search is implemented in pure Python -- no external tools required. Binary files are automatically skipped. Hidden directories (starting with `.`) are excluded. A spinner shows progress during search; press `ESC` to cancel.
+
+Results are displayed as a virtual filesystem tree (GREP) on the current panel. Navigate the results normally -- directories expand, `..` exits back to the real filesystem.
+
+Grep works only on local filesystems.
+
+### Command history (`Esc` `h`)
+
+In command-line mode (`;` or `:`), press `Esc` then `h` to open a history selector showing previously executed commands. Use `Up` / `Down` to browse, `Enter` to accept, `Esc` to cancel. History is persisted across sessions (up to 100 entries).
+
+### Customizing menus
+
+xc is a single Python script. Menus and keymaps are defined at the bottom of the file as plain data -- just edit them to add your own editors, bookmarks, or commands:
+
+```python
+app.add_menu("editor", [
+    MenuItem("v", "vi", lambda: app.action_run("vi %F")),
+    MenuItem("c", "code", lambda: app.action_run("code %F")),
+])
+```
+
+There is no config file on purpose. The script **is** the config.
+
+### Virtual filesystems
+
+Entering certain files opens them as virtual directories:
+
+| Extension                                    | VFS    | Description                         |
+| -------------------------------------------- | ------ | ----------------------------------- |
+| `.tar`, `.tar.gz`, `.tgz`, `.tar.bz2`        | TAR    | Browse tar archives                 |
+| `.zip`                                       | ZIP    | Browse zip archives                 |
+| `.gz`, `.bz2`, `.xz`, `.lzma`               | -      | View compressed single files        |
+| `.s3`                                        | S3     | Browse Amazon S3 buckets            |
+| `.gcs`                                       | GCS    | Browse Google Cloud Storage buckets |
+| `.oci`                                       | OCI    | Browse Oracle Cloud Object Storage  |
+| `.gdrive`                                    | GDrive | Browse Google Drive folders         |
+| `.ssh`                                       | SSH    | Browse remote servers over SSH      |
+
+VFS config files (`.s3`, `.gcs`, `.oci`, `.gdrive`, `.ssh`) are simple `key=value` text files. The path header shows the VFS type, e.g. `~/servers/prod.ssh (SSH)`.
+
+**S3 example** (`production.s3`):
+
+```text
+type=s3
+bucket=my-data-bucket
+AWS_PROFILE=production
+AWS_REGION=eu-west-1
+```
+
+`AWS_PROFILE` selects a named profile from `~/.aws/credentials`. You can also specify `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` inline, but using a profile is recommended. If all credentials are omitted, the default AWS credential chain is used.
+
+**GCS example** (`analytics.gcs`):
+
+```text
+type=gcs
+bucket=my-analytics-bucket
+key=service-account.json
+```
+
+The `key` path can be relative (resolved from the active panel's current directory), absolute, or use `~`, `$HOME`, or `$(HOME)` to refer to the home directory. If omitted, application default credentials are used.
+
+**OCI example** (`storage.oci`):
+
+```text
+type=oci
+bucket=my-bucket
+OCI_BUCKET_NAMESPACE=mynamespace
+OCI_USER=ocid1.user.oc1..aaa...
+OCI_FINGERPRINT=aa:bb:cc:...
+OCI_TENANCY=ocid1.tenancy.oc1..aaa...
+OCI_REGION=uk-london-1
+OCI_KEY_FILE=my-key.pem
+```
+
+`OCI_KEY_FILE` is a path to a PEM private key file. Alternatively, use `OCI_KEY_BASE64` to embed the key inline as base64. If neither is provided, the default OCI config (`~/.oci/config`) is used.
+
+**Google Drive example** (`shared.gdrive`):
+
+```text
+type=gdrive
+folder=1Z_NJ0-LAPzaO7eursL92DWPmFKQT3lpK
+key=service-account.json
+```
+
+The `folder` is the ID from the Google Drive folder URL. The `key` path points to a service account JSON credentials file (relative paths are resolved from the config file's directory). If omitted, application default credentials are used. Shared drives and folders shared from other accounts are supported.
+
+**SSH example** (`prod.ssh`):
+
+```text
+kind=ssh
+host=prod-server
+user=deploy
+identity=~/.ssh/id_ed25519
+port=22
+```
+
+Only `host` is required. All other fields are optional -- SSH will pick them up from `~/.ssh/config`. The `host` value can be an SSH config alias. The `identity` path supports `~`, `$HOME`, and `$(HOME)` prefixes.
+
+### Remote file editing
+
+The `%F` macro works transparently on remote VFS (SSH, S3, GCS, OCI, GDrive). When you run a command like `vi %F` on a remote file, xc automatically:
+
+1. Downloads the file to a local temp location
+2. Runs the command against the local copy
+3. If the command exits successfully and the file was modified, uploads it back
+
+This means editors, viewers, and any shell command work on remote files the same way as local ones.
+
+## Macros
+
+Editor, view, and shell command modes (`;` and `:`) all support macro expansion. Macros are prefixed with `%` and let you refer to the current file, directory, or tagged selection in your commands.
+
+| Macro | Description                                            |
+| ----- | ------------------------------------------------------ |
+| `%f`  | Current file name                                      |
+| `%F`  | Current file full path                                 |
+| `%x`  | Current file name without extension                    |
+| `%X`  | Current file full path without extension               |
+| `%d`  | Current directory name                                 |
+| `%D`  | Current directory full path                            |
+| `%m`  | Tagged file names (space-separated, shell-quoted)      |
+| `%M`  | Tagged file full paths (space-separated, shell-quoted) |
+| `%&`  | Run command in the background (no terminal output)     |
+
+### Quoting
+
+All macros are automatically shell-quoted. To disable quoting, prefix the macro letter with `~`:
+
+| Macro  | Description                 |
+| ------ | --------------------------- |
+| `%~f`  | File name, unquoted         |
+| `%~F`  | File path, unquoted         |
+| `%~m`  | Tagged file names, unquoted |
+| `%~M`  | Tagged file paths, unquoted |
+
+### Examples
+
+```text
+vi %F          →  vi '/home/user/hello world.txt'
+less %F        →  less '/home/user/notes.md'
+tar czf %x.tar.gz %~f  →  tar czf 'mydir.tar.gz' mydir
+echo %m        →  echo 'file1.txt' 'file2.txt'
+cp %M /tmp %&  →  cp '/home/user/a.txt' '/home/user/b.txt' /tmp  (background)
+```

xcfm-0.1.0/README.md

@@ -0,0 +1,326 @@
+# xc
+
+A two-panel console file manager inspired by Midnight Commander, written in Python.
+
+![xc](xc.png)
+
+## Intro
+
+The Python version of xc is a single self-contained script (`xc.py`) that runs via [uv](https://docs.astral.sh/uv/). This means:
+
+- **Zero setup** -- no virtualenv, no `pip install`, no `requirements.txt`. Just run `uv run xc.py`.
+- **Inline dependencies** -- the script header declares its own dependencies (`boto3`, `google-cloud-storage`, `oci`, `google-api-python-client`), and uv resolves and caches them automatically on the first run.
+- **Reproducible** -- uv pins the Python version (`>=3.11`) and handles isolation, so the script works the same way on any machine.
+- **Single file to deploy** -- copy `xc.py` to a server, a dotfiles repo, or a USB stick. There is nothing else to carry.
+
+### Installing uv
+
+```sh
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Homebrew
+brew install uv
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+After installing, run the file manager with:
+
+```sh
+uv run xc.py
+```
+
+The script has a shebang line, so you can rename it, make it executable, and put it on your PATH:
+
+```sh
+cp xc.py ~/.local/bin/xc
+chmod +x ~/.local/bin/xc
+xc
+```
+
+### Development
+
+The `pyproject.toml` in the repository is only used for local development tooling (e.g. `black` formatter settings). It is **not** needed to run xc -- `xc.py` is fully self-contained with its own inline dependency declarations.
+
+### Self-update
+
+To update xc to the latest version from GitHub:
+
+```sh
+xc -u
+```
+
+This fetches the latest `xc.py` from the repository, compares versions, and replaces the current binary if a newer version is available. The previous version is saved as `xc.prev` next to the executable.
+
+## User manual
+
+### Dual-panel concept
+
+xc shows two file panels side by side. One panel is **active** (highlighted border), the other is **inactive**. You navigate files in the active panel and use the inactive panel as a target for file operations like copy and move. Press `Tab` to switch the active panel. Press `h` / `l` to activate the left / right panel directly.
+
+On startup the active panel opens in the current working directory. The inactive panel restores the path from the previous session.
+
+### Navigation
+
+| Key                  | Action                                 |
+| -------------------- | -------------------------------------- |
+| `Up` / `k`           | Move cursor up                         |
+| `Down` / `j`         | Move cursor down                       |
+| `Enter`              | Enter directory or open VFS            |
+| `Backspace`          | Go to parent directory (or exit VFS)   |
+| `Left` / `Right`     | Page up / page down                    |
+| `PgUp` / `PgDn`      | Page up / page down                    |
+| `Home` / `^`         | Jump to first file                     |
+| `End` / `G`          | Jump to last file                      |
+| `Ctrl-D` / `Ctrl-U`  | Half-page down / up                    |
+| `Ctrl-L`             | Reload current directory               |
+| `Tab`                | Switch active panel                    |
+| `h` / `l`            | Activate left / right panel            |
+| `q`                  | Quit                                   |
+
+### File operations (`x`)
+
+Press `x` to open the **command** menu:
+
+| Key | Action                                                              |
+| --- | ------------------------------------------------------------------- |
+| `c` | **Copy** -- copy file or tagged files from active to inactive panel |
+| `m` | **Move** -- move (rename) file or tagged files                      |
+| `d` | **Delete** -- delete file or tagged files                           |
+| `k` | **Mkdir** -- create a new directory                                 |
+| `t` | **Touch** -- create an empty file                                   |
+| `p` | **Chmod** -- change file permissions                                |
+| `r` | **Rename** -- rename the selected file                              |
+| `g` | **Chdir** -- type a path to navigate to                             |
+
+Copy and move operations use the inactive panel's current path as the default destination. A prompt lets you edit the destination before confirming.
+
+### Tagging and group operations
+
+Press `Space` on a file to **tag** it (marked with `+`). Tagged files are used as the source for copy, move, delete, and chmod. If nothing is tagged, the operation applies to the file under the cursor.
+
+| Key     | Action                                              |
+| ------- | --------------------------------------------------- |
+| `Space` | Toggle tag on current file and move down            |
+| `+`     | Tag all files in current directory                  |
+| `_`     | Untag all                                           |
+| `i`     | Calculate sizes of tagged (or selected) directories |
+
+### Bookmarks (`b`)
+
+Press `b` to open the **bookmark** menu for quick jumps to common directories (home, desktop, downloads, etc.).
+
+### Remotes (`r`)
+
+Press `r` to open the **remote** menu. This scans `~/.xc/remotes/` for VFS config files (`.s3`, `.gcs`, `.oci`, `.gdrive`, `.ssh`) and presents them as a selector. Choosing a remote opens it on the active panel, just like pressing `Enter` on a VFS config file.
+
+This lets you keep all your remote connections in one place and access them from any directory without navigating to where the config files live.
+
+Example setup:
+
+```text
+~/.xc/remotes/
+  production.s3
+  analytics.gcs
+  storage.oci
+  shared-drive.gdrive
+  webserver.ssh
+```
+
+### Editor (`e`) and view (`v`)
+
+Press `e` to open a file in an editor, or `v` to view it. These menus launch external commands with the current file path substituted via macros (see below). On remote VFS (SSH, S3, GCS, OCI, GDrive), the file is automatically downloaded to a temp location, opened locally, and uploaded back if modified.
+
+### Running shell commands
+
+There are two command-line modes:
+
+| Key | Mode       | Behavior                                       |
+| --- | ---------- | ---------------------------------------------- |
+| `;` | **Direct** | Run a command interactively in the terminal    |
+| `:` | **Piped**  | Run a command; output is piped through `less`  |
+
+Both modes support macro expansion. The command runs in the active panel's current directory. If the command exits with a non-zero code, the error is shown in the bottom line.
+
+### Alternate screen and command output
+
+xc runs on the terminal's **alternate screen** -- the panels never mix with your shell's scroll buffer. When you run a shell command (`;` or `:`), xc temporarily switches back to the **main screen** so the command's output is preserved in the normal scroll buffer.
+
+To review previous command output without running anything:
+
+| Key              | Action                          |
+| ---------------- | ------------------------------- |
+| `Esc` `Esc`      | Switch to main screen           |
+| `Ctrl-O`         | Switch to main screen           |
+| `Esc` or `Ctrl-O` | Return to panels (main screen) |
+
+Once on the main screen you can scroll through your terminal's history as usual. Press `Esc` or `Ctrl-O` to return to the file panels.
+
+### Search (`/`)
+
+Press `/` to start an incremental search. Type characters to filter -- the cursor jumps to the first matching file. Press `Enter` to accept or `Esc` to cancel.
+
+### Grep (`s` / `S`)
+
+Press `s` for case-sensitive search or `S` for case-insensitive search. This is a two-step prompt:
+
+1. **File pattern** -- `grep in ` (or `igrep in `) appears. Enter a glob pattern to filter by filename. Leave empty to search all files.
+2. **Search string** -- `grep in *.py for ` appears. Enter the text to find. Leave empty to list files matching the pattern only.
+
+The file pattern uses Unix shell-style wildcards (matched against the filename only, not the path):
+
+| Pattern   | Meaning                                          | Example              |
+| --------- | ------------------------------------------------ | -------------------- |
+| `*`       | Matches everything                               | `*.py` -- all Python |
+| `?`       | Matches any single character                     | `?.txt` -- `a.txt`   |
+| `[seq]`   | Matches any character in *seq*                   | `[abc].py`           |
+| `[!seq]`  | Matches any character **not** in *seq*            | `[!.]cfg`            |
+
+Patterns do **not** support `**` (recursive globs) or path separators -- they match the base filename only.
+
+Search is implemented in pure Python -- no external tools required. Binary files are automatically skipped. Hidden directories (starting with `.`) are excluded. A spinner shows progress during search; press `ESC` to cancel.
+
+Results are displayed as a virtual filesystem tree (GREP) on the current panel. Navigate the results normally -- directories expand, `..` exits back to the real filesystem.
+
+Grep works only on local filesystems.
+
+### Command history (`Esc` `h`)
+
+In command-line mode (`;` or `:`), press `Esc` then `h` to open a history selector showing previously executed commands. Use `Up` / `Down` to browse, `Enter` to accept, `Esc` to cancel. History is persisted across sessions (up to 100 entries).
+
+### Customizing menus
+
+xc is a single Python script. Menus and keymaps are defined at the bottom of the file as plain data -- just edit them to add your own editors, bookmarks, or commands:
+
+```python
+app.add_menu("editor", [
+    MenuItem("v", "vi", lambda: app.action_run("vi %F")),
+    MenuItem("c", "code", lambda: app.action_run("code %F")),
+])
+```
+
+There is no config file on purpose. The script **is** the config.
+
+### Virtual filesystems
+
+Entering certain files opens them as virtual directories:
+
+| Extension                                    | VFS    | Description                         |
+| -------------------------------------------- | ------ | ----------------------------------- |
+| `.tar`, `.tar.gz`, `.tgz`, `.tar.bz2`        | TAR    | Browse tar archives                 |
+| `.zip`                                       | ZIP    | Browse zip archives                 |
+| `.gz`, `.bz2`, `.xz`, `.lzma`               | -      | View compressed single files        |
+| `.s3`                                        | S3     | Browse Amazon S3 buckets            |
+| `.gcs`                                       | GCS    | Browse Google Cloud Storage buckets |
+| `.oci`                                       | OCI    | Browse Oracle Cloud Object Storage  |
+| `.gdrive`                                    | GDrive | Browse Google Drive folders         |
+| `.ssh`                                       | SSH    | Browse remote servers over SSH      |
+
+VFS config files (`.s3`, `.gcs`, `.oci`, `.gdrive`, `.ssh`) are simple `key=value` text files. The path header shows the VFS type, e.g. `~/servers/prod.ssh (SSH)`.
+
+**S3 example** (`production.s3`):
+
+```text
+type=s3
+bucket=my-data-bucket
+AWS_PROFILE=production
+AWS_REGION=eu-west-1
+```
+
+`AWS_PROFILE` selects a named profile from `~/.aws/credentials`. You can also specify `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` inline, but using a profile is recommended. If all credentials are omitted, the default AWS credential chain is used.
+
+**GCS example** (`analytics.gcs`):
+
+```text
+type=gcs
+bucket=my-analytics-bucket
+key=service-account.json
+```
+
+The `key` path can be relative (resolved from the active panel's current directory), absolute, or use `~`, `$HOME`, or `$(HOME)` to refer to the home directory. If omitted, application default credentials are used.
+
+**OCI example** (`storage.oci`):
+
+```text
+type=oci
+bucket=my-bucket
+OCI_BUCKET_NAMESPACE=mynamespace
+OCI_USER=ocid1.user.oc1..aaa...
+OCI_FINGERPRINT=aa:bb:cc:...
+OCI_TENANCY=ocid1.tenancy.oc1..aaa...
+OCI_REGION=uk-london-1
+OCI_KEY_FILE=my-key.pem
+```
+
+`OCI_KEY_FILE` is a path to a PEM private key file. Alternatively, use `OCI_KEY_BASE64` to embed the key inline as base64. If neither is provided, the default OCI config (`~/.oci/config`) is used.
+
+**Google Drive example** (`shared.gdrive`):
+
+```text
+type=gdrive
+folder=1Z_NJ0-LAPzaO7eursL92DWPmFKQT3lpK
+key=service-account.json
+```
+
+The `folder` is the ID from the Google Drive folder URL. The `key` path points to a service account JSON credentials file (relative paths are resolved from the config file's directory). If omitted, application default credentials are used. Shared drives and folders shared from other accounts are supported.
+
+**SSH example** (`prod.ssh`):
+
+```text
+kind=ssh
+host=prod-server
+user=deploy
+identity=~/.ssh/id_ed25519
+port=22
+```
+
+Only `host` is required. All other fields are optional -- SSH will pick them up from `~/.ssh/config`. The `host` value can be an SSH config alias. The `identity` path supports `~`, `$HOME`, and `$(HOME)` prefixes.
+
+### Remote file editing
+
+The `%F` macro works transparently on remote VFS (SSH, S3, GCS, OCI, GDrive). When you run a command like `vi %F` on a remote file, xc automatically:
+
+1. Downloads the file to a local temp location
+2. Runs the command against the local copy
+3. If the command exits successfully and the file was modified, uploads it back
+
+This means editors, viewers, and any shell command work on remote files the same way as local ones.
+
+## Macros
+
+Editor, view, and shell command modes (`;` and `:`) all support macro expansion. Macros are prefixed with `%` and let you refer to the current file, directory, or tagged selection in your commands.
+
+| Macro | Description                                            |
+| ----- | ------------------------------------------------------ |
+| `%f`  | Current file name                                      |
+| `%F`  | Current file full path                                 |
+| `%x`  | Current file name without extension                    |
+| `%X`  | Current file full path without extension               |
+| `%d`  | Current directory name                                 |
+| `%D`  | Current directory full path                            |
+| `%m`  | Tagged file names (space-separated, shell-quoted)      |
+| `%M`  | Tagged file full paths (space-separated, shell-quoted) |
+| `%&`  | Run command in the background (no terminal output)     |
+
+### Quoting
+
+All macros are automatically shell-quoted. To disable quoting, prefix the macro letter with `~`:
+
+| Macro  | Description                 |
+| ------ | --------------------------- |
+| `%~f`  | File name, unquoted         |
+| `%~F`  | File path, unquoted         |
+| `%~m`  | Tagged file names, unquoted |
+| `%~M`  | Tagged file paths, unquoted |
+
+### Examples
+
+```text
+vi %F          →  vi '/home/user/hello world.txt'
+less %F        →  less '/home/user/notes.md'
+tar czf %x.tar.gz %~f  →  tar czf 'mydir.tar.gz' mydir
+echo %m        →  echo 'file1.txt' 'file2.txt'
+cp %M /tmp %&  →  cp '/home/user/a.txt' '/home/user/b.txt' /tmp  (background)
+```

xcfm-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "xcfm"
+version = "0.1.0"
+description = "Two-panel console file manager"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "boto3",
+    "google-cloud-storage",
+    "oci",
+    "google-api-python-client",
+    "google-auth",
+]
+
+[project.scripts]
+xcfm = "xc:entry"
+
+[tool.black]
+line-length = 80
+target-version = ["py311"]
+skip-string-normalization = true
+

xcfm-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xcfm-0.1.0/xcfm.egg-info/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: xcfm
+Version: 0.1.0
+Summary: Two-panel console file manager
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3
+Requires-Dist: google-cloud-storage
+Requires-Dist: oci
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth
+Dynamic: license-file
+
+# xc
+
+A two-panel console file manager inspired by Midnight Commander, written in Python.
+
+![xc](xc.png)
+
+## Intro
+
+The Python version of xc is a single self-contained script (`xc.py`) that runs via [uv](https://docs.astral.sh/uv/). This means:
+
+- **Zero setup** -- no virtualenv, no `pip install`, no `requirements.txt`. Just run `uv run xc.py`.
+- **Inline dependencies** -- the script header declares its own dependencies (`boto3`, `google-cloud-storage`, `oci`, `google-api-python-client`), and uv resolves and caches them automatically on the first run.
+- **Reproducible** -- uv pins the Python version (`>=3.11`) and handles isolation, so the script works the same way on any machine.
+- **Single file to deploy** -- copy `xc.py` to a server, a dotfiles repo, or a USB stick. There is nothing else to carry.
+
+### Installing uv
+
+```sh
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Homebrew
+brew install uv
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+After installing, run the file manager with:
+
+```sh
+uv run xc.py
+```
+
+The script has a shebang line, so you can rename it, make it executable, and put it on your PATH:
+
+```sh
+cp xc.py ~/.local/bin/xc
+chmod +x ~/.local/bin/xc
+xc
+```
+
+### Development
+
+The `pyproject.toml` in the repository is only used for local development tooling (e.g. `black` formatter settings). It is **not** needed to run xc -- `xc.py` is fully self-contained with its own inline dependency declarations.
+
+### Self-update
+
+To update xc to the latest version from GitHub:
+
+```sh
+xc -u
+```
+
+This fetches the latest `xc.py` from the repository, compares versions, and replaces the current binary if a newer version is available. The previous version is saved as `xc.prev` next to the executable.
+
+## User manual
+
+### Dual-panel concept
+
+xc shows two file panels side by side. One panel is **active** (highlighted border), the other is **inactive**. You navigate files in the active panel and use the inactive panel as a target for file operations like copy and move. Press `Tab` to switch the active panel. Press `h` / `l` to activate the left / right panel directly.
+
+On startup the active panel opens in the current working directory. The inactive panel restores the path from the previous session.
+
+### Navigation
+
+| Key                  | Action                                 |
+| -------------------- | -------------------------------------- |
+| `Up` / `k`           | Move cursor up                         |
+| `Down` / `j`         | Move cursor down                       |
+| `Enter`              | Enter directory or open VFS            |
+| `Backspace`          | Go to parent directory (or exit VFS)   |
+| `Left` / `Right`     | Page up / page down                    |
+| `PgUp` / `PgDn`      | Page up / page down                    |
+| `Home` / `^`         | Jump to first file                     |
+| `End` / `G`          | Jump to last file                      |
+| `Ctrl-D` / `Ctrl-U`  | Half-page down / up                    |
+| `Ctrl-L`             | Reload current directory               |
+| `Tab`                | Switch active panel                    |
+| `h` / `l`            | Activate left / right panel            |
+| `q`                  | Quit                                   |
+
+### File operations (`x`)
+
+Press `x` to open the **command** menu:
+
+| Key | Action                                                              |
+| --- | ------------------------------------------------------------------- |
+| `c` | **Copy** -- copy file or tagged files from active to inactive panel |
+| `m` | **Move** -- move (rename) file or tagged files                      |
+| `d` | **Delete** -- delete file or tagged files                           |
+| `k` | **Mkdir** -- create a new directory                                 |
+| `t` | **Touch** -- create an empty file                                   |
+| `p` | **Chmod** -- change file permissions                                |
+| `r` | **Rename** -- rename the selected file                              |
+| `g` | **Chdir** -- type a path to navigate to                             |
+
+Copy and move operations use the inactive panel's current path as the default destination. A prompt lets you edit the destination before confirming.
+
+### Tagging and group operations
+
+Press `Space` on a file to **tag** it (marked with `+`). Tagged files are used as the source for copy, move, delete, and chmod. If nothing is tagged, the operation applies to the file under the cursor.
+
+| Key     | Action                                              |
+| ------- | --------------------------------------------------- |
+| `Space` | Toggle tag on current file and move down            |
+| `+`     | Tag all files in current directory                  |
+| `_`     | Untag all                                           |
+| `i`     | Calculate sizes of tagged (or selected) directories |
+
+### Bookmarks (`b`)
+
+Press `b` to open the **bookmark** menu for quick jumps to common directories (home, desktop, downloads, etc.).
+
+### Remotes (`r`)
+
+Press `r` to open the **remote** menu. This scans `~/.xc/remotes/` for VFS config files (`.s3`, `.gcs`, `.oci`, `.gdrive`, `.ssh`) and presents them as a selector. Choosing a remote opens it on the active panel, just like pressing `Enter` on a VFS config file.
+
+This lets you keep all your remote connections in one place and access them from any directory without navigating to where the config files live.
+
+Example setup:
+
+```text
+~/.xc/remotes/
+  production.s3
+  analytics.gcs
+  storage.oci
+  shared-drive.gdrive
+  webserver.ssh
+```
+
+### Editor (`e`) and view (`v`)
+
+Press `e` to open a file in an editor, or `v` to view it. These menus launch external commands with the current file path substituted via macros (see below). On remote VFS (SSH, S3, GCS, OCI, GDrive), the file is automatically downloaded to a temp location, opened locally, and uploaded back if modified.
+
+### Running shell commands
+
+There are two command-line modes:
+
+| Key | Mode       | Behavior                                       |
+| --- | ---------- | ---------------------------------------------- |
+| `;` | **Direct** | Run a command interactively in the terminal    |
+| `:` | **Piped**  | Run a command; output is piped through `less`  |
+
+Both modes support macro expansion. The command runs in the active panel's current directory. If the command exits with a non-zero code, the error is shown in the bottom line.
+
+### Alternate screen and command output
+
+xc runs on the terminal's **alternate screen** -- the panels never mix with your shell's scroll buffer. When you run a shell command (`;` or `:`), xc temporarily switches back to the **main screen** so the command's output is preserved in the normal scroll buffer.
+
+To review previous command output without running anything:
+
+| Key              | Action                          |
+| ---------------- | ------------------------------- |
+| `Esc` `Esc`      | Switch to main screen           |
+| `Ctrl-O`         | Switch to main screen           |
+| `Esc` or `Ctrl-O` | Return to panels (main screen) |
+
+Once on the main screen you can scroll through your terminal's history as usual. Press `Esc` or `Ctrl-O` to return to the file panels.
+
+### Search (`/`)
+
+Press `/` to start an incremental search. Type characters to filter -- the cursor jumps to the first matching file. Press `Enter` to accept or `Esc` to cancel.
+
+### Grep (`s` / `S`)
+
+Press `s` for case-sensitive search or `S` for case-insensitive search. This is a two-step prompt:
+
+1. **File pattern** -- `grep in ` (or `igrep in `) appears. Enter a glob pattern to filter by filename. Leave empty to search all files.
+2. **Search string** -- `grep in *.py for ` appears. Enter the text to find. Leave empty to list files matching the pattern only.
+
+The file pattern uses Unix shell-style wildcards (matched against the filename only, not the path):
+
+| Pattern   | Meaning                                          | Example              |
+| --------- | ------------------------------------------------ | -------------------- |
+| `*`       | Matches everything                               | `*.py` -- all Python |
+| `?`       | Matches any single character                     | `?.txt` -- `a.txt`   |
+| `[seq]`   | Matches any character in *seq*                   | `[abc].py`           |
+| `[!seq]`  | Matches any character **not** in *seq*            | `[!.]cfg`            |
+
+Patterns do **not** support `**` (recursive globs) or path separators -- they match the base filename only.
+
+Search is implemented in pure Python -- no external tools required. Binary files are automatically skipped. Hidden directories (starting with `.`) are excluded. A spinner shows progress during search; press `ESC` to cancel.
+
+Results are displayed as a virtual filesystem tree (GREP) on the current panel. Navigate the results normally -- directories expand, `..` exits back to the real filesystem.
+
+Grep works only on local filesystems.
+
+### Command history (`Esc` `h`)
+
+In command-line mode (`;` or `:`), press `Esc` then `h` to open a history selector showing previously executed commands. Use `Up` / `Down` to browse, `Enter` to accept, `Esc` to cancel. History is persisted across sessions (up to 100 entries).
+
+### Customizing menus
+
+xc is a single Python script. Menus and keymaps are defined at the bottom of the file as plain data -- just edit them to add your own editors, bookmarks, or commands:
+
+```python
+app.add_menu("editor", [
+    MenuItem("v", "vi", lambda: app.action_run("vi %F")),
+    MenuItem("c", "code", lambda: app.action_run("code %F")),
+])
+```
+
+There is no config file on purpose. The script **is** the config.
+
+### Virtual filesystems
+
+Entering certain files opens them as virtual directories:
+
+| Extension                                    | VFS    | Description                         |
+| -------------------------------------------- | ------ | ----------------------------------- |
+| `.tar`, `.tar.gz`, `.tgz`, `.tar.bz2`        | TAR    | Browse tar archives                 |
+| `.zip`                                       | ZIP    | Browse zip archives                 |
+| `.gz`, `.bz2`, `.xz`, `.lzma`               | -      | View compressed single files        |
+| `.s3`                                        | S3     | Browse Amazon S3 buckets            |
+| `.gcs`                                       | GCS    | Browse Google Cloud Storage buckets |
+| `.oci`                                       | OCI    | Browse Oracle Cloud Object Storage  |
+| `.gdrive`                                    | GDrive | Browse Google Drive folders         |
+| `.ssh`                                       | SSH    | Browse remote servers over SSH      |
+
+VFS config files (`.s3`, `.gcs`, `.oci`, `.gdrive`, `.ssh`) are simple `key=value` text files. The path header shows the VFS type, e.g. `~/servers/prod.ssh (SSH)`.
+
+**S3 example** (`production.s3`):
+
+```text
+type=s3
+bucket=my-data-bucket
+AWS_PROFILE=production
+AWS_REGION=eu-west-1
+```
+
+`AWS_PROFILE` selects a named profile from `~/.aws/credentials`. You can also specify `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` inline, but using a profile is recommended. If all credentials are omitted, the default AWS credential chain is used.
+
+**GCS example** (`analytics.gcs`):
+
+```text
+type=gcs
+bucket=my-analytics-bucket
+key=service-account.json
+```
+
+The `key` path can be relative (resolved from the active panel's current directory), absolute, or use `~`, `$HOME`, or `$(HOME)` to refer to the home directory. If omitted, application default credentials are used.
+
+**OCI example** (`storage.oci`):
+
+```text
+type=oci
+bucket=my-bucket
+OCI_BUCKET_NAMESPACE=mynamespace
+OCI_USER=ocid1.user.oc1..aaa...
+OCI_FINGERPRINT=aa:bb:cc:...
+OCI_TENANCY=ocid1.tenancy.oc1..aaa...
+OCI_REGION=uk-london-1
+OCI_KEY_FILE=my-key.pem
+```
+
+`OCI_KEY_FILE` is a path to a PEM private key file. Alternatively, use `OCI_KEY_BASE64` to embed the key inline as base64. If neither is provided, the default OCI config (`~/.oci/config`) is used.
+
+**Google Drive example** (`shared.gdrive`):
+
+```text
+type=gdrive
+folder=1Z_NJ0-LAPzaO7eursL92DWPmFKQT3lpK
+key=service-account.json
+```
+
+The `folder` is the ID from the Google Drive folder URL. The `key` path points to a service account JSON credentials file (relative paths are resolved from the config file's directory). If omitted, application default credentials are used. Shared drives and folders shared from other accounts are supported.
+
+**SSH example** (`prod.ssh`):
+
+```text
+kind=ssh
+host=prod-server
+user=deploy
+identity=~/.ssh/id_ed25519
+port=22
+```
+
+Only `host` is required. All other fields are optional -- SSH will pick them up from `~/.ssh/config`. The `host` value can be an SSH config alias. The `identity` path supports `~`, `$HOME`, and `$(HOME)` prefixes.
+
+### Remote file editing
+
+The `%F` macro works transparently on remote VFS (SSH, S3, GCS, OCI, GDrive). When you run a command like `vi %F` on a remote file, xc automatically:
+
+1. Downloads the file to a local temp location
+2. Runs the command against the local copy
+3. If the command exits successfully and the file was modified, uploads it back
+
+This means editors, viewers, and any shell command work on remote files the same way as local ones.
+
+## Macros
+
+Editor, view, and shell command modes (`;` and `:`) all support macro expansion. Macros are prefixed with `%` and let you refer to the current file, directory, or tagged selection in your commands.
+
+| Macro | Description                                            |
+| ----- | ------------------------------------------------------ |
+| `%f`  | Current file name                                      |
+| `%F`  | Current file full path                                 |
+| `%x`  | Current file name without extension                    |
+| `%X`  | Current file full path without extension               |
+| `%d`  | Current directory name                                 |
+| `%D`  | Current directory full path                            |
+| `%m`  | Tagged file names (space-separated, shell-quoted)      |
+| `%M`  | Tagged file full paths (space-separated, shell-quoted) |
+| `%&`  | Run command in the background (no terminal output)     |
+
+### Quoting
+
+All macros are automatically shell-quoted. To disable quoting, prefix the macro letter with `~`:
+
+| Macro  | Description                 |
+| ------ | --------------------------- |
+| `%~f`  | File name, unquoted         |
+| `%~F`  | File path, unquoted         |
+| `%~m`  | Tagged file names, unquoted |
+| `%~M`  | Tagged file paths, unquoted |
+
+### Examples
+
+```text
+vi %F          →  vi '/home/user/hello world.txt'
+less %F        →  less '/home/user/notes.md'
+tar czf %x.tar.gz %~f  →  tar czf 'mydir.tar.gz' mydir
+echo %m        →  echo 'file1.txt' 'file2.txt'
+cp %M /tmp %&  →  cp '/home/user/a.txt' '/home/user/b.txt' /tmp  (background)
+```

xcfm-0.1.0/xcfm.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+xcfm.egg-info/PKG-INFO
+xcfm.egg-info/SOURCES.txt
+xcfm.egg-info/dependency_links.txt
+xcfm.egg-info/entry_points.txt
+xcfm.egg-info/requires.txt
+xcfm.egg-info/top_level.txt

xcfm-0.1.0/xcfm.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xcfm-0.1.0/xcfm.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+xcfm = xc:entry

xcfm-0.1.0/xcfm.egg-info/requires.txt

@@ -0,0 +1,5 @@
+boto3
+google-cloud-storage
+oci
+google-api-python-client
+google-auth

xcfm-0.1.0/xcfm.egg-info/top_level.txt

@@ -0,0 +1 @@
+remotes