Drive Rescue Assistant

Drive Rescue Assistant is a local-first, cross-platform external drive rescue tool. It helps inspect removable drives, explain likely read/write problems, and extract readable files into a normal folder without modifying the source drive.

The current v0.9 release-candidate build is intentionally conservative:

• Scan mounted drives.
• Inspect one drive or mount path.
• Detect common read-only and backup-drive conditions.
• Copy readable files out to another destination.
• Support dry-run extraction previews.
• Produce local reports.
• Show current-file progress, elapsed time, and estimated remaining time.
• Check destination space before copying.
• Cancel safely without presenting an incomplete ZIP as finished.
• Continue past individual unreadable files and report them clearly.
• Separate OS-protected locations from genuinely unreadable files.
• Explain macOS Full Disk Access failures before creating an empty report.
• Produce an explicitly exported safe diagnostic without paths, filenames, or hashes.
• Avoid delete, format, repair, repartition, force-mount, or permission-bypass operations.
• Use one source-to-destination workflow for connected drives and manually selected folders.
• Show destination format, free space, and writable state before previewing.
• Warn when source and destination are on the same storage device.
• Group previewed files by folder, with search and selected-size totals before copying.
• Allow an opt-in My Drives list on macOS; it is local to that Mac, stores no file contents, and never guesses a drive identity after reconnection.

Reliable Rescue in v0.5 adds optional SHA-256 verification for folder copies. Verified file digests are written only to the local extraction report. Folder output also records an atomic local recovery manifest so matching completed files can be resumed after interruption. ZIP verification and resume are not enabled yet. Existing destination files default to Skip; Keep Both uses a recovered filename, while Replace must be chosen explicitly. If a source or destination disconnects, extraction stops before the missing mount path can point to another disk; reconnect the same drive and run again with Resume enabled. FAT32 destinations block selected files larger than 4 GB and warn about ZIP or filename compatibility risks. Preview labels distinguish new files, existing destination paths, and manifest-backed copies already recovered; already-recovered files are deselected by default.

v0.5.2 adds a source-access preflight, plain-language Full Disk Access guidance on macOS, separate protected-item totals, bounded failure details, and a privacy-safe support diagnostic alongside the full local report. The full report remains local and may contain filenames; the safe diagnostic does not.

Supported Platforms

• macOS: diskutil, mount, and Time Machine hints.
• Windows: PowerShell Get-Volume/Get-Disk where available.
• Linux: lsblk, findmnt, and common mount metadata.

Each platform has its own adapter under src/drive_rescue/platforms/.

Quick Start

Requires Python 3.10 or newer.

python3 -m drive_rescue scan
python3 -m drive_rescue inspect /Volumes/MyBackup
python3 -m drive_rescue extract /Volumes/MyBackup --to ./recovered --dry-run
python3 -m drive_rescue extract /Volumes/MyBackup --to ./recovered
python3 -m drive_rescue extract /Volumes/MyBackup --to ./recovered --verify-copies
python3 -m drive_rescue extract /Volumes/MyBackup --to ./recovered --resume
python3 -m drive_rescue extract /Volumes/MyBackup --to ./recovered --conflict rename

For local development from the repo root:

python3 -m pip install -e .
drive-rescue scan

Run tests without extra dependencies:

PYTHONPATH=src python3 -m unittest discover -s tests

Mac App

The repo includes a SwiftUI macOS interface with both SwiftPM and Xcode entrypoints.

swift build
xcodebuild -project DriveRescueAssistant.xcodeproj -scheme DriveRescueAssistant -destination "platform=macOS,arch=arm64" build
./script/build_and_run.sh

The app keeps the same safety model as the CLI: scan, inspect, preview extraction, and extract readable files. It does not delete, repair, format, or force-mount drives.

Preview and extraction can be limited to all files, documents, photos, videos, audio, or archives. The app can also write matched files into a ZIP archive to save destination space. Folder extraction can optionally verify each copied file with SHA-256 and resume matching completed files from a local recovery manifest; these options are unavailable when ZIP output is selected.

v0.6 uses one Copy Readable Files workspace. Selecting a connected drive fills the source, while Choose Drive or Folder supports camera cards and ordinary folders without introducing a separate mode. Files copy directly from source to destination without being staged on the Mac.

v0.7 makes the preview easier to work through: files are grouped by folder, searchable, and can be selected by folder or individually. An unmounted partition is shown as an unknown filesystem unless the operating system has confirmed it. In particular, Linux/NAS partitions are kept in a read-only, no-repair state rather than being mislabelled as a usable FAT/MS-DOS volume.

Use DriveRescueAssistant.xcodeproj for signing, Archive, asset catalog work, and future App Store preparation.

Packaged Mac builds include a universal self-contained extraction engine, so testers do not need to install Python separately.

For a Developer ID-signed direct-download package and Apple's notarization workflow, see docs/MACOS_SIGNING_NOTARIZATION.md and run:

./script/package_macos_release.sh

Friend Testing

To create a Mac package that can be uploaded to a GitHub Release:

./script/package_friend_test.sh

The package is written to dist/friend-test/DriveRescueAssistant-mac-friend-test.zip. Include docs/FRIEND_TEST_GUIDE.md and docs/GITHUB_RELEASE_TESTING.md when preparing a test release.

Windows and Linux friend-test packages are built automatically by .github/workflows/desktop-release.yml. Push a prerelease tag such as v0.9.0-rc.1 to create a GitHub Release containing:

• DriveRescueAssistant-windows-x64.zip
• DriveRescueAssistant-linux-x64.tar.gz

Both desktop packages are self-contained and do not require Python. Their shared GUI supports detected-drive selection, source/destination folder pickers, file-type filters, individual preview selection, and optional ZIP extraction.

The same workflow also produces a private GitHub Actions artifact named MicrosoftStorePackage. Its .msixupload file uses the reserved Partner Center identity and is intended for Store submission, not public direct installation. The Xcode project includes a sandboxed Store configuration for validation; it is not submission-ready until the bundled extraction helper passes sandbox runtime testing. See docs/WINDOWS_STORE_SUBMISSION.md and docs/store/apple-app-store.md.

Safety Promise

Drive Rescue Assistant is extraction-first. It does not erase, format, repartition, force-mount, or delete files in V1. If a drive looks damaged or read-only, the tool recommends copying readable data out before any repair attempt.

Recovered personal files and real scan logs should not be committed to GitHub.

Repo Layout

src/drive_rescue/
  cli.py
  core/
  platforms/
docs/
  DESIGN_SPEC.md
  SAFETY.md
  PLATFORM_SUPPORT.md
  store/
tests/

Store Readiness

The GitHub CLI can be more technical, but any Apple App Store or Google Play version should use a stricter permission model, system file pickers, clear privacy wording, and no destructive disk operations by default. See docs/store/.

For the full Apple/Google store and cross-platform release plan, see docs/STORE_AND_PLATFORM_PLAN.md.

Mac App Direction

The preferred interface is simple, functional, and minimalist: a native macOS app with a connected-drive sidebar, a clear drive summary, one primary extraction path, and plain safety notes. See docs/MAC_APP_UI.md.

Troubleshooting Direction

Drive diagnosis should explain older Mac backup disks calmly. Apple Partition Map and tiny legacy Apple driver partitions can be normal on old WD drives; failed HFS+ verification with Invalid extent entry points to filesystem corruption. See docs/TROUBLESHOOTING.md.