Lavisys/mailsweep
2
0
Fork 0
Code Issues 2 Pull requests Projects Releases 7 Packages Wiki Activity Actions
Page: ADR 0003 prune legacy script shims
Pages
0001 deepen classification safety auditor 0002 deepen rules registry 0003 prune legacy script shims 0004 decouple rfc codecs from mailbox gateway 0005 collapse workflow into mailbox pipeline 0006 decouple gateway orchestration into pipeline 0007 incremental scan cache and progress feedback 0008 port mailsweep to synchronous rust 0009 retire python baseline and complete rust cutover 0010 automated multi platform forgejo release workflow ADR 0001 deepen classification safety auditor ADR 0002 deepen rules registry ADR 0003 prune legacy script shims ADR 0004 decouple rfc codecs from mailbox gateway ADR 0005 collapse workflow into mailbox pipeline ADR 0006 decouple gateway orchestration into pipeline ADR 0007 incremental scan cache and progress feedback ADR 0008 port mailsweep to synchronous rust ADR 0009 retire python baseline and complete rust cutover ADR 0010 automated multi platform forgejo release workflow ADRs CLI Reference Domain Context FAQ Home Internals Python API Rules Schema Rust API
1 ADR 0003 prune legacy script shims
MailSweep Doc Bot edited this page 2026-08-24 02:23:29 +00:00
Table of Contents

3. Prune Shallow Legacy Script Shims in Favor of Unified CLI

Date: 2026-08-24

Status

Accepted

Context

MailSweep provides a unified command line interface (mailsweep / src/mailsweep/cli.py) and standard module execution (python -m mailsweep).

Previously, eight root-level script shims (scan_mailbox.py, classify_and_plan.py, backup_emails.py, clean_mailbox.py, restore_selected_emails.py, deep_audit.py, rules_updater.py, unsubscribe_hub.py) were maintained in the repository root for backwards compatibility. Each file was a shallow 10-line pass-through modifying sys.argv and delegating to mailsweep.cli:main.

Maintaining these shims introduced architectural drawbacks:

  1. Scattered root entrypoint surface area confusing both human maintainers and AI navigability.
  2. Redundant pass-through layers violating the deletion test (deleting the shims concentrates execution in the canonical CLI without moving complexity).
  3. Divergent invocation patterns across documentation and tooling.

Decision

We pruned all eight root script shims and standardized all CLI execution on the canonical mailsweep package interface:

  1. Root Script Removal:

    • Deleted scan_mailbox.py, classify_and_plan.py, backup_emails.py, clean_mailbox.py, restore_selected_emails.py, deep_audit.py, rules_updater.py, and unsubscribe_hub.py.

  2. Standardized Execution Surface:

    • Standardized documentation and command examples on uv run mailsweep <subcommand> (e.g. mailsweep scan, mailsweep plan, mailsweep backup, mailsweep clean, mailsweep restore, mailsweep audit, mailsweep unsubscribe, mailsweep rules).
    • python -m mailsweep <subcommand> remains supported via src/mailsweep/__main__.py.
    • mailsweep console script remains registered in pyproject.toml.

  3. Domain Vocabulary & Locality:

    • Maintained all programmatic domain module interfaces (MailboxGateway, ClassificationEngine, SafetyAuditor, BackupArchive, UnsubscribeHub, RulesRegistry) untouched for zero-dependency library consumers.

Consequences

  • Clean root directory structure with zero shallow wrapper scripts.
  • Single canonical entrypoint for CLI execution, documentation, and automated tooling.
  • Full test suite and programmatic API capabilities remain 100% intact.

📬 MailSweep Wiki