Metadata-Version: 2.4
Name: sshmirror
Version: 0.1.18
Summary: SSH directory synchronization library and CLI
Author: FellowCode
License-Expression: MIT
Project-URL: Homepage, https://github.com/FellowCode/sshmirror
Project-URL: Repository, https://github.com/FellowCode/sshmirror
Project-URL: Issues, https://github.com/FellowCode/sshmirror/issues
Project-URL: Changelog, https://github.com/FellowCode/sshmirror/blob/main/CHANGELOG.md
Keywords: ssh,sync,deployment,cli,remote-files,project-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles
Requires-Dist: aioshutil
Requires-Dist: asyncssh
Requires-Dist: beartype
Requires-Dist: pydantic
Requires-Dist: PyYAML
Requires-Dist: questionary
Requires-Dist: rich
Dynamic: license-file

# SSHMirror

Sync a working directory with a remote server over SSH, inspect diffs before applying changes, and keep a lightweight local history for rollback-oriented workflows.

SSHMirror is both:

- a Python library you can import;
- a CLI you can run inside a project folder;
- a sync workflow that keeps local and remote changes inspectable.

It can also be used as a lightweight sync workflow for a shared project: multiple developers can make changes to the same remote-backed codebase and inspect differences before pulling or pushing updates.

Internet access is not required for SSHMirror itself. It only needs network access to the target SSH host or Docker host you are synchronizing with.

When you run `sshmirror` without arguments, it opens an interactive menu.
Depending on project state, the menu can include:

- `Create sshmirror.config.yml`
- `Create sshmirror.ignore.txt`
- `Initialization`
- `Pull & Push`
- `Status`
- `View current changes`
- `Versions` (`History`, `Compare`)
- `Pull only`
- `Stash changes`
- `Restore stashed changes`
- `Discard all local changes`
- `Discard selected files`
- `Downgrade remote version`
- `Test connection`
- `Exit`

## Why It Stands Out

- Preview first. Inspect current file changes and version-to-version diffs before syncing. 🔍
- Built for real SSH workflows. Passwords, SSH keys, passphrases, and ssh-agent fallback are supported. 🔐
- Keeps local state. SSHMirror stores version and migration metadata under `.sshmirror/`. 🗂️
- Works as a library or a command-line tool. 🐍
- Useful for team workflows. Several developers can work on one project and sync changes through the same remote environment. 🤝
- Optional remote container restart after sync. 🐳

## Install 🚀

```bash
pip install sshmirror
```

For local development:

```bash
pip install -e .
```

## Quick Start ⚡

1. Create a config file:

   ```bash
   sshmirror
   ```

   On first interactive launch, SSHMirror can create `sshmirror.config.yml` for you.

2. Start from this minimal config:

   ```yaml
   host: '192.168.12.22'
   port: '50022'
   username: 'root'
   localdir: '.'
   remotedir: '/app'
   author: your-name
   ```

3. Check status or connect-test before syncing:

   ```bash
   sshmirror --status
   sshmirror --test-connection
   ```

## Example Configuration ⚙️

The full example lives in [sshmirror.config.example.yml](sshmirror.config.example.yml).

Supported auth patterns:

- password auth;
- private key auth;
- private key with passphrase;
- default SSH keys or ssh-agent when no key and no password are provided.

Example with optional container restart:

```yaml
host: '192.168.12.22'
port: '50022'
username: 'root'
localdir: '.'
remotedir: '/app'
author: your-name

restart_container:
   # Optional. If omitted, host/port/username are reused from the main SSH config.
   # host: '192.168.12.22'
   # port: '23322'
   # username: user
  sudo: true
  container_name: testcontainer
```

`restart_container` connects to the Docker host where the container is running. If `host`, `port`, or `username` are not specified there, SSHMirror uses the main connection values.

## CLI Commands 🧰

```bash
sshmirror --help
```

Main non-interactive flags:

- `--status` show local and remote sync status;
- `--current-diff` inspect current local versus remote differences;
- `--version-diff` inspect changes between remote versions;
- `--pull` only pull from remote;
- `--stash-changes` stash local changes before syncing;
- `--restore-stash` restore previously stashed changes;
- `--discard` discard all local changes;
- `--discard-files <paths...>` discard only selected files;
- `--downgrade` downgrade remote version;
- `--test-connection` validate SSH access to the remote host and configured Docker host.

## Library Usage 📦

```python
from sshmirror import SSHMirror, SSHMirrorConfig

mirror = SSHMirror(
    config=SSHMirrorConfig(
        host='127.0.0.1',
        port=22,
        username='root',
        localdir='.',
        remotedir='/app',
    )
)
```

The public API is exported from [sshmirror/__init__.py](sshmirror/__init__.py).

## Project Layout

```text
sshmirror/
  sshmirror/          # importable package
  tests/              # smoke tests
  pyproject.toml      # packaging metadata
  sshmirror.config.example.yml
```

## Development 🛠️

Run tests:

```bash
python -m unittest discover -s tests -p "test_*.py"
```

Build locally:

```bash
python -m build
```

## Changelog

Latest release notes live in [CHANGELOG.md](CHANGELOG.md).

## Status

This repository is structured as a Python package with a CLI entry point. If you plan to publish to PyPI, keep package metadata, README, and license in sync with actual behavior.
# Changelog

## 0.1.18

### Fixed

- Fixed a missing `uuid` import in the remote push path which caused `NameError` during metadata file creation.

## 0.1.17

### Fixed

- Moved `push` and `pull` confirmation prompts ahead of the live sync table so interactive confirmation and version description input work correctly.

## 0.1.16

### Changed

- Replaced the interactive `View version changes` menu item with a `Versions` submenu containing `History` and `Compare`.
- Added automatic previous-version diff browsing for `Versions -> History`.
- Reworked `push` and `pull` execution so the existing preview table stays on screen and the `Status` column updates live during synchronization.
- Made version descriptions mandatory during `push` instead of silently defaulting to `update`.

### Fixed

- Removed duplicate visible CLI actions for force-discarding local changes, leaving a single user-facing discard action.
- Skipped the expensive full project re-compare after a normal `push` when no sync hook commands are configured.
- Cleared the temporary `Connect to remote...` line before interactive version lists are shown.
- Adjusted version pagination controls so `Older versions` appears before the version list and `Newer versions` appears after it.
- Made remote `push` synchronization atomic by rolling back remote changes when any file sync step fails.
- Switched generated downgrade scripts to relative paths so rollback metadata no longer embeds absolute remote project paths.

## 0.1.15

### Changed

- Improved interactive version history rendering with fixed-width columns for version number, timestamp, author, uid, and message.
- Improved file change browsing so `changed`, `created`, and `deleted` entries are shown together with clearer color-coded styling.
- Improved `push` and `pull` previews with structured summary panels and color-coded action tables before confirmation.

## 0.1.14

### Changed

- Highlighted the selected base version during target version selection so the comparison source stays visible in interactive history browsing.

### Fixed

- Removed duplicated version history rendering so interactive diff browsing shows a single styled selection list instead of both a table and a separate prompt list.

## 0.1.13

### Fixed

- Fixed interactive `questionary` prompts inside async CLI flows so they no longer fail with `asyncio.run() cannot be called from a running event loop`.
- Fixed version and diff browsing prompts to run safely while the CLI event loop is active.

## 0.1.12

### Fixed

- Fixed `Ctrl+C` handling in interactive menus so cancellation exits cleanly instead of falling back to plain input.
- Fixed prompt cancellation handling for both `questionary` prompts and plain-input fallback paths.

## 0.1.11

### Changed

- Finalized interactive diff browsing so version pages open with the newest item on the current page selected by default.
- Restricted textual diff inspection to inspectable changed files only.

### Fixed

- Prevented oversized changed files from being selectable in interactive diff views.

## 0.1.10

### Changed

- Reworked `View version changes` for large version histories.
- Replaced full-history rendering with interactive paginated browsing.
- Improved version timestamp presentation in interactive history views.
- Added colored tabular rendering and numeric shortcuts for version selection.

### Added

- Added lazy remote paging for interactive version history browsing.
- Added author display in interactive version history views.
- Added a 50-character validation limit for version descriptions.

## 0.1.9

### Fixed

- Fixed sudo password authentication for `restart_container`.

### Added

- Added step-by-step Docker host diagnostics for Docker host checks.

## 0.1.8

### Fixed

- Fixed `restart_container` connection handling.

### Changed

- Removed deprecated `restart_container.user` support and standardized on `restart_container.username`.

### Added

- Added startup validation for the full configuration, including `restart_container` consistency checks.

## 0.1.7

### Changed

- Optimized local and remote scanning so ignored directories are pruned instead of scanned and filtered after traversal.

## 0.1.6

### Fixed

- Fixed postponed annotation evaluation and runtime annotation handling.
