Metadata-Version: 2.4
Name: synclean
Version: 0.1.0
Summary: Python project for cleaning Synapse server media using API
Author-email: Hirad <hirad@hirad.it>
License-Expression: GPL-3.0-only
Keywords: matrix,synapse,media,admin,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.2.1
Requires-Dist: colorlog>=6.10.1
Requires-Dist: dateparser>=1.2.2
Requires-Dist: platformdirs>=4.3.8
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pymysql>=1.1.2
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.32.4
Dynamic: license-file

# Synclean

Synclean is a Python library and command-line tool for inspecting and cleaning media on a Matrix Synapse homeserver. It connects to the Synapse Admin API, exposes reusable core services, and provides Click commands for common administration workflows.

The project is built for homeserver maintenance work: find the largest media consumers, inspect a user's uploads, review room media, preserve important avatar references, and run cleanup operations deliberately.

## Features

- View user details, joined rooms, avatar, media count, and media size.
- View room details, members, creator, avatar, room type, and media counts.
- Search and paginate large user and room lists.
- Inspect per-user media usage from Synapse media statistics.
- List user media by size, date, ID, or MIME type.
- Delete selected user media and room media through the Synapse Admin API.
- Purge room history using separate retention policies for bridge rooms and regular rooms.
- Import and track user avatars, room avatars, and stickers in MariaDB-backed tables.
- Manage homeserver, access token, database, ignored users, and purge settings from the CLI configuration file.

## Requirements

- Python 3.12 or newer
- A Matrix Synapse homeserver with Admin API access
- A Synapse admin access token
- MariaDB or MySQL-compatible database access for avatar and sticker tracking

## Installation

Clone the repository, then install the project and its dependencies:

```bash
git clone <repo-url>
cd Synclean
uv sync
```

If you are not using `uv`, install it with another Python package workflow:

```bash
python -m pip install -e .
```

## Configuration

Synclean stores its settings in your user config directory as `synclean/config.yaml`. On Linux this is typically:

```text
~/.config/synclean/config.yaml
```

Create or update this file with:

```bash
synclean settings
```

The configuration contains:

- `username`: the Synapse admin username used by the app
- `homeserver`: your homeserver URL, for example `https://matrix.example.com`
- `access_token`: an admin access token
- `database`: MariaDB connection settings
- `ignored_users`: users that should be ignored by cleanup-related workflows
- `room_history_purge`: retention periods for regular rooms and bridge rooms

Example:

```yaml
username: "@admin:example.com"
homeserver: "https://matrix.example.com"
access_token: "YOUR_ADMIN_ACCESS_TOKEN"
room_history_purge:
  bridge_room_policy:
    retention_period: 7
  regular_room_policy:
    retention_period: 0
ignored_users: []
database:
  name: "synclean"
  host: "127.0.0.1"
  port: 3306
  username: "synclean"
  password: "password"
user_agent: "Synclean/1.0"
```

Retention periods are stored as days. A value of `7` means Synclean will purge room history older than seven days when that policy is used.

## Running the CLI

After installation, inspect the available commands with:

```bash
synclean --help
```

Implemented command groups include:

- `user ls`, `user show`, and `user media`
- `room ls` and `room show`
- `media ls` and `media delete`
- `settings`

## Python Library

The `synclean` package can also be imported by other Python code. Core modules are organized under:

- `synclean.api`: Synapse Admin API clients and repositories
- `synclean.services`: workflows that coordinate API and database operations
- `synclean.models`: Pydantic request, response, and domain models
- `synclean.database`: MariaDB/MySQL persistence helpers

## Safety Notes

Synclean performs real administrative cleanup operations against Synapse. Deleting media and purging room history can be irreversible, depending on your server configuration and backups.

Before running deletion workflows:

- Confirm the homeserver and admin token point to the intended server.
- Review media lists and usage totals first.
- Use conservative thresholds.
- Keep backups or snapshots for important deployments.
- Be especially careful with room media deletion and history purging.

## Development

Install development dependencies:

```bash
uv sync --group dev
```

Run checks:

```bash
uv run ruff check .
uv run pyright
uv run pytest
```

Project layout:

```text
src/synclean/api/        Synapse Admin API clients and repositories
src/synclean/cli/        Click command groups
src/synclean/config/     YAML configuration loading and saving
src/synclean/database/   MariaDB persistence for avatars and stickers
src/synclean/models/     Pydantic models and domain objects
src/synclean/services/   Application service layer
src/synclean/utils/      Logging, formatting, and shared helpers
```

Build publishable artifacts with:

```bash
uv build
```

Publish them with `uv publish` after configuring the target index credentials.

## License

This project is licensed under the terms in [LICENSE](LICENSE).
