fix(config)!: keep captured data by default for deletions and excluded chats

[GeiserX]

Two settings still deleted archived data unless the operator opted out. With LISTEN_DELETIONS=true, the default DELETION_MODE=hard removed every message deleted in Telegram, and docker-compose.yml passed hard explicitly. Adding a chat to any *_EXCLUDE_CHAT_IDS list purged its messages, media folder and avatars on the next run, with no flag and no README warning.

Fix

• DELETION_MODE defaults to soft. A processed deletion marks the message deleted and keeps it. hard still works when set explicitly, and its startup line keeps the DELETED warning. The compose default, README, .env.example and the getattr fallbacks in the listener and the sync-deletions pass all say soft now.
• New boolean EXCLUDE_DELETE_EXISTING, default false, parsed like SKIP_MEDIA_DELETE_EXISTING. When it is false an excluded chat is still skipped, but its rows and files stay. The run logs one INFO line with the count only ("N excluded chat(s) keep their archived rows and files (EXCLUDE_DELETE_EXISTING=false)"), never a chat id. When it is true the purge runs as it did before.
• The startup summary says which way exclusion goes: a warning when the flag is on, an info line when exclude lists are set and the flag is off.
• README row, .env.example block and a commented compose line for the new flag. The README row says it deletes and cannot be undone.
• The archive principle in CLAUDE.md now lists EXCLUDE_DELETE_EXISTING instead of the exclude lists, and notes that DELETION_MODE=hard is opt-in.

What it deletes / overwrites / forgets

• Deletes: nothing new. It removes two default deletion paths. Both are still reachable by setting DELETION_MODE=hard or EXCLUDE_DELETE_EXISTING=true.
• Overwrites: nothing.
• Forgets: nothing. Soft deletion keeps the row with is_deleted and deleted_at. An excluded chat keeps everything captured before it was excluded.

For a reviewer to push back on

• This changes behaviour for existing deployments. Anyone who relied on the hard default, or on exclusion reclaiming storage, has to set the flag after upgrading. The commit is marked ! with a BREAKING CHANGE footer, and the release notes should say so. The CHANGELOG entry is left for release time.
• The count line is logged where the purge used to run, right after filtering, not at the very end of the run. It still fires once per run, and it also fires on runs that stop early because nothing is left to back up.
• EXCLUDE_DELETE_EXISTING is global, like SKIP_MEDIA_DELETE_EXISTING. There is no per-account TG_ACCOUNT_<N>_ override.
• Soft-deleted messages still count in statistics, search and exports, flagged as deleted. That is existing soft-mode behaviour. Now more deployments will see it.

Tests

Full suite green: 4263 passed, 268 skipped. ruff check and ruff format --check are clean. Each new test was seen to fail under a one-line mutant and pass again after the exact line was restored: both defaults, both purge-gate branches, both summary lines, the hard warning and both getattr fallbacks.

Summary by CodeRabbit

• Behavior Changes
  • Deleted messages are now marked as deleted in the archive by default, so they remain available in statistics, search, and exports. Set DELETION_MODE=hard to permanently remove them.
  • Excluding a chat now keeps its previously archived data by default. Enable EXCLUDE_DELETE_EXISTING to remove that data.
• Documentation
  • Updated configuration guidance to explain these defaults and options.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: GeiserX/Telegram-Archive/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 2307474f-8016-4632-b6f5-c3bbea0ac51c

📥 Commits

Reviewing files that changed from the base of the PR and between ae0fbc0 and 5bcb73e.

📒 Files selected for processing (11)

• .env.example
• CLAUDE.md
• README.md
• docker-compose.yml
• src/config.py
• src/listener.py
• src/telegram_backup.py
• tests/test_config.py
• tests/test_config_bool_vocab.py
• tests/test_listener.py
• tests/test_telegram_backup_extended.py

Included review availability: Your plan provides up to 2 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Excluded chats keep existing archived data by default, with deletion controlled by EXCLUDE_DELETE_EXISTING. Telegram-deleted messages are marked deleted by default. Hard deletion remains available through explicit configuration.

Changes

Archive deletion behavior

Layer / File(s)	Summary
Excluded-chat retention and purge control .env.example, CLAUDE.md, README.md, docker-compose.yml, src/config.py, src/telegram_backup.py, tests/test_config.py, tests/test_config_bool_vocab.py, tests/test_telegram_backup_extended.py	EXCLUDE_DELETE_EXISTING defaults to false. Excluded chats keep archived rows and files unless the setting enables deletion. Configuration logs and tests cover both paths.
Soft deletion default and explicit hard mode .env.example, README.md, docker-compose.yml, src/config.py, src/listener.py, src/telegram_backup.py, tests/test_config.py, tests/test_listener.py, tests/test_telegram_backup_extended.py	Unset deletion mode now marks deleted messages instead of removing them. Explicit hard mode remains supported. Configuration, listener, backup, documentation, and tests reflect these defaults.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 5bcb7

No concrete merge-blocking defect was established. Excluded chats retain archived data by default, and unset deletion mode keeps deleted messages marked in the archive.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary behavior change: captured data remains by default for deletions and excluded chats. It is concise and specific.
Description check	✅ Passed	The description clearly explains the behavior changes, opt-in settings, breaking impact, logging behavior, documentation updates, and test results. It is mostly complete, although it does not reproduc…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 31 functions across 7 files. (4 skipped: 4…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🐳 Dev images published!

• drumsergio/telegram-archive:dev
• drumsergio/telegram-archive-viewer:dev

The dev/test instance will pick up these changes automatically (Portainer GitOps).

To test locally:

docker pull drumsergio/telegram-archive:dev
docker pull drumsergio/telegram-archive-viewer:dev

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.97%. Comparing base (ae0fbc0) to head (5bcb73e).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #477      +/-   ##
==========================================
+ Coverage   94.96%   94.97%   +0.01%     
==========================================
  Files          29       29              
  Lines       12318    12325       +7     
==========================================
+ Hits        11698    11706       +8     
+ Misses        620      619       -1     

Files with missing lines	Coverage Δ
src/config.py	94.89% <100.00%> (+0.16%)	⬆️
src/listener.py	93.54% <100.00%> (ø)
src/telegram_backup.py	95.02% <100.00%> (+<0.01%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.