# SpaceMedic (CLI prototype)

SpaceMedic is a working, read-only diagnosis tool that turns a directory
scan into a categorized cleanup-candidate report: it walks a folder tree,
classifies every regular file into one junk-type bucket (temp files, log
files, cache-like directories, old installers/archives, old downloads, or
large media) using filename and path heuristics, and prints each
actionable category's total file count, total size, and largest
individual files, sorted so the biggest cleanup opportunity leads. It is
the "Pro" tier of the same product line as the sibling tool DrivePulse:
DrivePulse gives you a raw folder-level space map and a largest-files
list (WHERE is my space going, by folder); SpaceMedic answers a different
question — WHAT KIND of stuff is eating my space, and what's worth
looking at first — a triage view by junk-type instead of a raw file
tree. SpaceMedic is diagnosis-only by design: it has no delete, move, or
quarantine action of any kind, and never will (there is intentionally no
--apply flag). Pair its report with DupePilot (exact-duplicate detection)
or PrivacySweep (secure deletion) to actually act on what it finds. The
full SpaceMedic product concept also includes real S.M.A.R.T. disk health
telemetry; reading SMART attributes needs OS-specific, privileged
hardware access that is out of reach for a portable, dependency-free Go
CLI, so that part is not implemented here and is tracked as a roadmap
item — see ../plan.md for the full product plan.

## Build from source

Requires Go 1.24+, no external dependencies.

    go build -o spacemedic .

Cross-compile for another platform:

    GOOS=windows GOARCH=amd64 go build -o spacemedic.exe .
    GOOS=darwin  GOARCH=arm64 go build -o spacemedic .

## Usage

    spacemedic report <dir> [--installer-age 90d] [--download-age 30d]
                             [--large-media-size 500MB] [--top 10] [--json]

Walks <dir> recursively and classifies every regular file into exactly
one category, checking rules in this priority order (first match wins):

  Temp files
      Extension is .tmp or .temp, OR the filename starts with "~".

  Log files
      Extension is .log, OR the filename matches the pattern *.log.*
      (rotated logs like app.log.1, access.log.3).

  Cache-like
      The file's path has a directory segment named (case-insensitive)
      "cache", "caches", ".cache", or "tmp" — anywhere above the file,
      not just its immediate parent.

  Old installers/archives
      Extension is one of .msi, .exe, .dmg, .pkg, .zip, .tar, .tar.gz,
      .tgz, AND the file's mtime is older than --installer-age
      (default 90d).

  Old downloads
      The file's path has a directory segment named (case-insensitive)
      "download" or "downloads", AND the file's mtime is older than
      --download-age (default 30d).

  Large media
      Extension is one of .mp4, .mov, .avi, .mkv, .iso, AND the file's
      size is >= --large-media-size (default 500MB).

  Uncategorized
      Everything that didn't match a rule above. Still counted in the
      grand total, but not shown as its own actionable bucket with a
      file listing — there is nothing specific to suggest cleaning up
      here, it's just "the rest".

Age flags (--installer-age, --download-age) take a number followed by a
unit: d (24-hour day), h (hour), or m (minute) — e.g. 90d, 12h, 45m.
The size flag (--large-media-size) takes a number followed by an
optional unit: B, KB/KiB, MB/MiB, GB/GiB, TB/TiB (binary/1024-based,
case-insensitive); a bare number is treated as raw bytes.

--top N caps how many of each actionable category's largest individual
files are listed (default 10) — the category's reported file count and
total size always reflect ALL matching files, not just the ones shown.

--json prints the same category breakdown (including every top file's
path, byte size, human-readable size, and UTC mod time) as a single JSON
object instead of the human-readable report.

SpaceMedic never writes, deletes, moves, or otherwise modifies anything
in the directory it scans — it only reads file metadata (name, path,
size, modification time) to classify files. There is no destructive
action available in this tool by design.

## Prebuilt binaries

See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and
CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds —
Windows SmartScreen and macOS Gatekeeper will warn on first run, which is
expected until a code-signing certificate is in place.