Development

Set up a checkout

git clone https://git.hirad.it/Hirad/syncfm-core.git
cd syncfm-core
uv sync

The build backend is uv_build. Runtime code uses a src/ layout and requires Python 3.12 or newer.

Quality checks

The configured development tools are Ruff and Pyright:

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv build

Ruff targets Python 3.12, an 88-column line length, Google-style docstrings, and a broad lint rule set. Pyright runs in strict mode.

The current repository does not include an automated test suite. Changes to synchronization, persistence, recovery, or network translation should add focused tests before relying on them in production.

Architecture

Package	Responsibility
syncfm_core.models	Immutable domain models and enums
syncfm_core.protocols	Network and repository interfaces
syncfm_core.networks	pylast adapters and factory
syncfm_core.profiles	TOML profiles and keyring credentials
syncfm_core.repositories	SQLite schema and concrete persistence
syncfm_core.services	Range, snapshot, comparison, metadata, retry, submission, recovery, orchestration
syncfm_core.cli	Typer/Rich frontend
syncfm_core.application	Public composition root

The public package root re-exports the intended integration surface. Protocol-driven services make network and persistence implementations replaceable, while create_sync_service() provides the standard SQLite composition.

Build and inspect artifacts

uv build
python -m zipfile -l dist/*.whl

Before release, verify CLI help, type information, license inclusion, and installation into a clean environment.

Documentation conventions

This wiki follows Forgejo's integrated wiki structure: each page is a top-level Markdown file, Home.md is the entry page, and _Sidebar.md supplies navigation. Internal links use Forgejo page slugs such as [CLI Reference](CLI-Reference).

When behavior changes, update the task guide and API/behavior reference together so examples do not drift from implementation.