Contributing

Development setup

Install Python 3.10 or later and uv, then clone the repository.

git clone https://github.com/CoffeesoftDotDev/archivist.git
Set-Location archivist

# Run from the working tree
uv run archivist --parent-folder "C:\photos"

# Show module help
uv run python -m archivist --help

# Run the tests
uv run pytest

The first uv run creates .venv and installs the development dependency group.

Tests and isolation

The pytest fixtures keep runs isolated by:

  • Clearing ARCHIVIST_* variables

  • Blocking the real Recycle Bin

  • Closing log files before temporary folders are removed

  • Providing helpers for sample ZIPs, files, listings, and reports

Architecture

Package

Responsibility

cli

Options, prompts, entry point, and exit codes

workflow

Builds and runs the ordered processing steps

services

ZIP extraction and metadata cleanup

utils

Filesystem helpers and removal strategies

core

Configuration and logging shared across layers

Dependencies flow downward from cli to workflow, services, and utils. Every layer can use core.

Continuous integration

CI runs the locked test suite on Windows and Ubuntu with Python 3.10 and 3.13. It also builds the Docker image and verifies preview and apply runs as the non-root user.

uv run --locked pytest

MCP and local integration

The MCP guide records the v0.3 consumer contract, startup configuration, immutable source-pinning procedure and acceptance checklist. Keep tool schemas generated from the implementation, not copied into examples. The examples\copilot directory contains the session-only plugin/agent/skill and launcher tests; do not install it in user configuration as part of validation.

Hosted Windows/Linux MCP startup evidence and a human release decision remain separate gates. The existing CLI must still work without the optional MCP SDK.

Contributor reference

The repository guide covers adding options and workflow steps, debugging in VS Code, dependency locking, and release versioning.