Metadata-Version: 2.4
Name: disk-coldstore
Version: 0.1.0
Summary: Tiered laptop storage reclaimer: find junk, LZX-compress cool folders, 7z-archive cold ones — all reversible.
Author-email: Arya <arya1262023@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Arya-126/coldstore
Project-URL: Repository, https://github.com/Arya-126/coldstore
Project-URL: Issues, https://github.com/Arya-126/coldstore/issues
Keywords: storage,disk-space,compression,7z,lzx,ntfs,windows,cleanup,archive
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: send2trash>=1.8
Requires-Dist: py7zr>=0.20
Dynamic: license-file

# ColdStore

Tiered laptop storage reclaimer for Windows. Point it at a folder, get an
honest, categorized plan of what can be freed, then apply the plan — every
action is journaled and reversible.

## What it does

Three tiers, safest first:

| Tier | Trigger | Action | Reversible via |
| :--- | :--- | :--- | :--- |
| **JUNK** | Regenerable folders (`node_modules`, `.venv`, `__pycache__`, browser caches, `Temp`) or app caches | Send to Recycle Bin | Restore via Shell.Application COM |
| **COOL** | Not accessed in 30+ days, non-media content | NTFS/LZX compress in place with `compact.exe` | `compact /u /s /a /i /exe` |
| **COLD** | Not accessed in 180+ days | 7z archive; original folder replaced with a `.coldstore` stub file | `coldstore restore <stub>` |

Bonus: bit-exact **JPEG -> JPEG XL** lossless transcode using
[libjxl](https://github.com/libjxl/libjxl) — reversible to the byte-identical
original JPEG.

## Install

```bash
pip install coldstore
```

Optional external tools that unlock extra performance / features:

- **[7-Zip](https://www.7-zip.org/)** — if `7z.exe` is on PATH, cold archiving
  uses the native binary (much faster on large folders). Otherwise the pure-Python
  `py7zr` fallback is used automatically.
- **[libjxl](https://github.com/libjxl/libjxl/releases)** — `cjxl.exe` /
  `djxl.exe` on PATH enable the bit-exact JPEG -> JXL media tier.

## Usage

```
coldstore scan     <path>                         # dry-run report of reclaimable space
coldstore analyze  <path> [--tree]                # WizTree-style disk analysis
coldstore apply    <path> --junk --cool --cold    # do the work
coldstore restore  <stub.coldstore>               # restore an archived folder
coldstore undo     --last N | --entry K           # undo previous actions
coldstore journal  [--limit N]                    # timeline of everything done

coldstore gui                                     # graphical interface
coldstore register [--uninstall]                  # register .coldstore file association
coldstore schedule --target <path> --cadence weekly

coldstore media scan|apply|restore  <path>        # bit-exact JPEG <-> JXL
```

Recommended first run — read-only, no changes:

```powershell
coldstore analyze  C:\Users\%USERNAME% --tree --tree-depth 4 --tree-min-share 1
coldstore scan     C:\Users\%USERNAME% --min-size-mb 100
```

Then, when you're ready to actually reclaim space:

```powershell
coldstore apply    C:\Users\%USERNAME% --min-size-mb 100 --junk --cool --cold
```

Every action is written to `%USERPROFILE%\.coldstore\actions.jsonl`. To undo
anything:

```powershell
coldstore journal --limit 20
coldstore undo --entry 14
```

## How the tiers avoid overlap

If a folder qualifies as COOL/COLD but contains a JUNK sub-folder, the
container's projection subtracts the JUNK bytes before estimating savings. The
report therefore never double-counts across tiers.

## Safety

- Every action is journaled with before/after bytes.
- JUNK goes to the Recycle Bin (never hard-deleted).
- COLD archives are integrity-verified with `7z t` (or py7zr's `testzip`)
  before the original folder is removed.
- OneDrive cloud-placeholder files are detected via `GetFileAttributesW` (real
  attribute check, not a path heuristic) and excluded by default.
- Never touches `C:\Windows`, `Program Files`, `ProgramData`, or the Recycle Bin.

## Requirements

- Windows 10 1607+ (LZX compression) or Windows 11
- Python 3.10+
- NTFS filesystem for the COOL tier

## License

MIT
