cfc-corrupted-file-cleaner 0.1.2

Corrupted File Cleaner: scan, preview, quarantine, and manage potentially corrupted or encrypted files.

Corrupted File Cleaner (cfc)

Scan, preview, quarantine, hash, and audit potentially corrupted or encrypted files. User-trust focused: safe defaults, reversible actions, transparent logging, and manifest-based auditing.

Key Features

• Multi-format detectors: Images, Text, PDF, OOXML (docx/xlsx/pptx), MP3
• Parallel scanning with progress + live counts
• Action modes: Preview (safe) / Quarantine / Delete (recycle bin)
• SHA-256 hashing & manifest snapshot (post-action)
• Rich GUI preview: image thumbnail, text snippet, hex dump fallback
• CLI headless mode for automation
• JSONL logging (scan.log) + analytics tool
• Externalized localization (English / Türkçe / Kurdî) with hot reload
• Plugin architecture (drop in detectors_plugins/*.py)

Install

Development (editable):

pip install -e .

Standard (from a built distribution / PyPI once published):

pip install cfc-corrupted-file-cleaner

Launch

GUI:

cfc-gui

or:

python -m cfc.gui

CLI:

cfc-scan C:\data --mode preview --hash --manifest --jsonl scan.log

Console Tools

Command	Purpose
cfc-gui	Launch desktop UI
cfc-scan	Headless scan (see --help)
cfc-analyze	Summarize JSONL log
cfc-manifest-diff	Compare two manifests
cfc-restore	Restore quarantined files from a manifest
cfc-locale-validate	Report missing/extra translation keys
cfc-locale-template	Generate union-of-keys template

Typical GUI Workflow

1. Select folder
2. Choose file types & keep Action Mode = Preview initially
3. (Optional) enable Hashes / Manifest
4. Scan → inspect reasons (single click previews, double click opens)
5. Switch to Quarantine or Delete only after review
6. Export report / use manifest and logs for audit

Manifest

Written after actions so paths reflect quarantine moves. Includes schema_version, counts, per-item path, kind, reason, size, hash (if enabled). schema_version (currently "1.0") allows future evolution without breaking tooling.

Example snippet:

{
	"schema_version": "1.0",
	"generated": "2025-01-01T12:00:00Z",
	"root": "C:/data",
	"action_mode": "quarantine",
	"counts": {"scanned": 1200, "corrupted": 4, "encrypted": 2},
	"items": [
		{"path": "C:/data/_quarantine/img/bad1.jpg", "kind": "corrupted", "reason": "image decode failed", "size": 10234, "hash": "...sha256..."}
	]
}

Diff two manifests:

cfc-manifest-diff manifest_old.json manifest_new.json

Quarantine & Restore

Corrupted files move under _quarantine/ preserving relative structure with collision-safe renaming. Restore:

cfc-restore manifest_20250101_120000.json --quarantine-root C:\data\_quarantine

Localization

Packaged default locales are bundled (English / Türkçe / Kurdî). To override or add a language, create a ./locales/ directory alongside where you run the app and drop xx.json there—those files override packaged ones. Hot reload picks up changes within ~1.5s. Validate:

cfc-locale-validate

Template:

cfc-locale-template locales/template_all_keys.json

Plugins

Create a folder detectors_plugins/ and add e.g. mydet.py:

from pathlib import Path
from cfc.detectors import DetectionResult

class MyDetector:
		name = 'xyz'
		extensions = {'.xyz'}
		def analyze(self, path: Path):
				# simple heuristic
				return DetectionResult(path, 'ok')

DETECTORS = [MyDetector()]

Extensions auto-loaded at startup.

CLI Highlights

cfc-scan C:\data --types .jpg .png .pdf --mode quarantine --hash --manifest --export report.txt --jsonl scan.log

Important flags: --mode, --hash, --manifest, --export, --jsonl, --types.

Logging & Analytics

Each detection appended to scan.log (JSONL). Summarize:

cfc-analyze scan.log

Testing

Run tests:

python -m unittest -v

Safety Guidelines

• Always start in Preview
• Review reasons before irreversible actions
• Keep manifests + _quarantine/ until confident
• Encrypted files are never deleted automatically

Roadmap (Shortlist)

• User home plugin directory (~/.cfc/plugins / %APPDATA%/cfc/plugins)
• Additional detectors (archives, video containers)
• Incremental cache (mtime/size/hash) for faster rescans
• Extended preview (scrollable hex/text) & accessibility improvements

Contributing

See CONTRIBUTING.md. PRs welcome.

License

MIT (see LICENSE).