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_*variablesBlocking the real Recycle Bin
Closing log files before temporary folders are removed
Providing helpers for sample ZIPs, files, listings, and reports
Architecture¶
Package |
Responsibility |
|---|---|
|
Options, prompts, entry point, and exit codes |
|
Builds and runs the ordered processing steps |
|
ZIP extraction and metadata cleanup |
|
Filesystem helpers and removal strategies |
|
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.