packagepurge 1.0.0 → 2.0.0

package/.agent/workflows/build.md

@@ -0,0 +1,58 @@
+---
+description: Build PackagePurge (Rust core + TypeScript CLI)
+---
+
+# Build PackagePurge
+
+This workflow builds both the Rust core binary and the TypeScript CLI.
+
+## Prerequisites
+
+- Node.js >= 16.0.0
+- Rust toolchain (cargo)
+- npm
+
+## Steps
+
+// turbo-all
+
+1. Install npm dependencies:
+```bash
+cd c:\Users\barne\OneDrive\Desktop\PackagePurge
+npm install
+```
+
+2. Build Rust core (release mode):
+```bash
+cd c:\Users\barne\OneDrive\Desktop\PackagePurge\core
+cargo build --release
+```
+
+3. Build TypeScript:
+```bash
+cd c:\Users\barne\OneDrive\Desktop\PackagePurge
+npx tsc
+```
+
+4. Verify CLI works:
+```bash
+cd c:\Users\barne\OneDrive\Desktop\PackagePurge
+node dist/cli/index.js --help
+```
+
+## Output
+
+After successful build:
+- Rust binary: `core/target/release/packagepurge_core.exe` (Windows) or `core/target/release/packagepurge-core` (Unix)
+- TypeScript output: `dist/` directory
+- CLI entry point: `dist/cli/index.js`
+
+## Quick Build Command
+
+For a full rebuild:
+```bash
+cd c:\Users\barne\OneDrive\Desktop\PackagePurge
+npm run build
+```
+
+This runs both `build:core` (cargo) and `tsc` sequentially.

package/.github/workflows/release.yml

@@ -0,0 +1,176 @@
+name: Build and Release
+
+on:
+    push:
+        tags:
+            - "v*"
+    workflow_dispatch:
+        inputs:
+            version:
+                description: "Version to release (e.g., 1.0.2)"
+                required: true
+                type: string
+
+env:
+    CARGO_TERM_COLOR: always
+
+jobs:
+    build:
+        name: Build ${{ matrix.target }}
+        runs-on: ${{ matrix.os }}
+        strategy:
+            fail-fast: false
+            matrix:
+                include:
+                    - target: x86_64-pc-windows-msvc
+                      os: windows-latest
+                      ext: .exe
+                      name: windows-x64
+                    - target: x86_64-unknown-linux-gnu
+                      os: ubuntu-latest
+                      ext: ""
+                      name: linux-x64
+                    - target: x86_64-apple-darwin
+                      os: macos-latest
+                      ext: ""
+                      name: macos-x64
+                    - target: aarch64-apple-darwin
+                      os: macos-latest
+                      ext: ""
+                      name: macos-arm64
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Setup Rust
+              uses: dtolnay/rust-toolchain@stable
+              with:
+                  targets: ${{ matrix.target }}
+
+            - name: Build Rust binary
+              working-directory: ./core
+              run: cargo build --release --target ${{ matrix.target }}
+
+            - name: Prepare binary (Unix)
+              if: runner.os != 'Windows'
+              run: |
+                  mkdir -p artifacts
+                  cp core/target/${{ matrix.target }}/release/packagepurge_core${{ matrix.ext }} artifacts/purge-${{ matrix.name }}${{ matrix.ext }}
+                  chmod +x artifacts/purge-${{ matrix.name }}${{ matrix.ext }}
+
+            - name: Prepare binary (Windows)
+              if: runner.os == 'Windows'
+              run: |
+                  mkdir artifacts
+                  copy core\target\${{ matrix.target }}\release\packagepurge_core${{ matrix.ext }} artifacts\purge-${{ matrix.name }}${{ matrix.ext }}
+
+            - name: Upload artifact
+              uses: actions/upload-artifact@v4
+              with:
+                  name: purge-${{ matrix.name }}
+                  path: artifacts/purge-${{ matrix.name }}${{ matrix.ext }}
+
+    release:
+        name: Create Release
+        needs: build
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Download all artifacts
+              uses: actions/download-artifact@v4
+              with:
+                  path: artifacts
+                  merge-multiple: true
+
+            - name: List artifacts
+              run: ls -la artifacts/
+
+            - name: Create checksums
+              working-directory: artifacts
+              run: |
+                  sha256sum purge-* > checksums.txt
+                  cat checksums.txt
+
+            - name: Get version
+              id: version
+              run: |
+                  if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+                    echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
+                  else
+                    echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+                  fi
+
+            - name: Create Release
+              uses: softprops/action-gh-release@v1
+              with:
+                  tag_name: v${{ steps.version.outputs.version }}
+                  name: PackagePurge v${{ steps.version.outputs.version }}
+                  draft: false
+                  prerelease: false
+                  generate_release_notes: true
+                  files: |
+                      artifacts/purge-*
+                      artifacts/checksums.txt
+                  body: |
+                      ## Installation
+
+                      ### Via npm (recommended)
+                      ```bash
+                      npm install -g packagepurge
+                      ```
+
+                      ### Download Binary
+                      Download the appropriate binary for your platform:
+                      | Platform | Binary |
+                      |----------|--------|
+                      | Windows x64 | `purge-windows-x64.exe` |
+                      | Linux x64 | `purge-linux-x64` |
+                      | macOS x64 | `purge-macos-x64` |
+                      | macOS ARM64 | `purge-macos-arm64` |
+
+                      After downloading, make it executable (Unix):
+                      ```bash
+                      chmod +x purge-linux-x64
+                      ./purge-linux-x64 --help
+                      ```
+
+                      ### Verify Download
+                      Verify your download with the checksums in `checksums.txt`.
+
+    npm-publish:
+        name: Publish to npm
+        needs: release
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "20"
+                  registry-url: "https://registry.npmjs.org"
+
+            - name: Setup Rust
+              uses: dtolnay/rust-toolchain@stable
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Build Rust core
+              working-directory: ./core
+              run: cargo build --release
+
+            - name: Build TypeScript
+              run: npx tsc
+
+            - name: Publish to npm
+              run: npm publish
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -2,92 +2,209 @@
 
 **Intelligent package manager cache cleanup service with project-aware optimization**
 
+[![npm version](https://badge.fury.io/js/packagepurge.svg)](https://www.npmjs.com/package/packagepurge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 PackagePurge is a comprehensive service that solves the persistent "npm hell" storage problem by intelligently managing disk space across npm, yarn, and pnpm caches while maintaining safety and project awareness.
 
-## 🎯 Core Value Proposition
+## 🎯 Features
 
-- **Intelligent Caching**: LRU-based preservation of frequently used packages
+- **Human-Readable Output**: Beautiful table format with color-coded status (JSON/YAML also available)
+- **Intelligent LRU Caching**: Size-aware preservation of frequently used packages
 - **Project-Aware Optimization**: Analyzes actual project dependencies before cleanup
 - **Multi-Manager Support**: Works with npm, yarn, and pnpm
 - **Safety-First Design**: Built-in backup and rollback mechanisms
-- **Cross-Project Deduplication**: Reduces storage by sharing common dependencies
+- **Cross-Project Deduplication**: Reduces storage by symlinking common dependencies
+- **ML-Powered Predictions**: Rule-based classifier for smart eviction decisions
 
-## 🏗️ Architecture
+## 📦 Installation
 
-### Core Components
+### Option 1: npm (Recommended)
 
-1. **Storage Scanner**: Filesystem analysis with AST/dependency graph parsing
-2. **Optimization Engine**: Rule-based and ML-driven cleanup strategies
-3. **Safety Layer**: Backup and rollback functionality
-4. **Reporting Dashboard**: Analytics with savings-to-risk ratio metrics
+```bash
+npm install -g packagepurge
+```
 
-### Technical Stack
+After installation, you can use either `purge` (recommended) or `packagepurge`:
 
-- **Core**: Rust (high-performance scanning and optimization)
-- **CLI**: TypeScript (Node.js) with Commander.js
-- **File Operations**: Rust stdlib + fs-extra for robust filesystem operations
-- **Dependency Analysis**: Custom parsers for package.json, lock files
-- **ML Component**: Rule-based classifier (extensible to actual ML models)
-- **Symlinking**: Cross-platform hard linking and symbolic links
-- **Caching**: LRU cache with ML-driven predictions
+```bash
+purge --help
+```
 
-## 📦 Installation
+### Option 2: Download Binary
+
+Download pre-built binaries from [GitHub Releases](https://github.com/Benaah/PackagePurge/releases):
+
+| Platform | Binary |
+|----------|--------|
+| Windows x64 | `purge-windows-x64.exe` |
+| Linux x64 | `purge-linux-x64` |
+| macOS x64 | `purge-macos-x64` |
+| macOS ARM64 (M1/M2) | `purge-macos-arm64` |
 
+**Linux/macOS:**
 ```bash
-npm install -g packagepurge
+# Download and make executable
+chmod +x purge-linux-x64
+sudo mv purge-linux-x64 /usr/local/bin/purge
+purge --help
+```
+
+**Windows:**
+```powershell
+# Add to PATH or run directly
+.\purge-windows-x64.exe --help
 ```
 
-## 🚀 Usage
+
+## 🚀 Quick Start
+
+```bash
+# Scan your projects for packages
+purge scan --paths ./my-project
+
+# Analyze cleanup opportunities (dry run)
+purge analyze --preserve-days 30
+
+# See what can be optimized with ML
+purge optimize --enable-ml
+```
+
+## 📖 Usage
 
 ### Scan Filesystem
+
+Scan directories to find packages and projects:
+
 ```bash
-packagepurge scan
-packagepurge scan --paths ./project1 ./project2
+# Scan current directory
+purge scan
+
+# Scan specific paths
+purge scan --paths ./project1 ./project2
+
+# Output as JSON for scripting
+purge scan --format json
+```
+
+**Sample Output:**
+```
+📦 Packages Found
+
+Package                        Version      Size       Path
+────────────────────────────────────────────────────────────────────────────────────────────────────
+react                          18.2.0       125 KB     .../node_modules/react
+lodash                         4.17.21      528 KB     .../node_modules/lodash
+typescript                     5.3.3        65.2 MB    .../node_modules/typescript
+
+📊 Total: 245 packages, 156.7 MB
+
+📁 Projects Found: 3
+   • C:\projects\my-app
+   • C:\projects\api-server
 ```
 
 ### Analyze (Dry Run)
+
+Preview what would be cleaned without making changes:
+
 ```bash
-packagepurge analyze
-packagepurge analyze --paths ./my-project --preserve-days 90
+# Analyze with default 90-day preservation
+purge analyze
+
+# Custom preservation period
+purge analyze --preserve-days 30 --paths ./my-project
+```
+
+**Sample Output:**
+```
+🧹 Cleanup Plan
+
+Orphaned (12 packages, 45.2 MB)
+────────────────────────────────────────────────────────────────────────────────
+  • old-package                      12.5 MB     .../node_modules/old-package
+  • unused-lib                       8.3 MB      .../node_modules/unused-lib
+
+Outdated (8 packages, 23.1 MB)
+────────────────────────────────────────────────────────────────────────────────
+  • stale-dependency                 5.2 MB      .../cache/stale-dep
+
+📊 Summary
+   Total packages: 20
+   Estimated savings: 68.3 MB
 ```
 
-### Optimize with ML/LRU and Symlinking
+### Optimize with ML/LRU
+
+Get intelligent cleanup recommendations:
+
 ```bash
 # Basic optimization
-packagepurge optimize
+purge optimize
 
-# With ML predictions enabled
-packagepurge optimize --enable-ml --preserve-days 90
+# With ML predictions
+purge optimize --enable-ml --preserve-days 90
 
-# With symlinking enabled
-packagepurge optimize --enable-symlinking
+# With symlinking for duplicates
+purge optimize --enable-symlinking
 
-# Full optimization with all features
-packagepurge optimize --enable-ml --enable-symlinking --lru-max-packages 2000
+# Full optimization
+purge optimize --enable-ml --enable-symlinking --lru-max-packages 2000
 ```
 
 ### Execute Symlinking
+
+Deduplicate packages across projects by creating symlinks:
+
 ```bash
-# Symlink duplicate packages across projects
-packagepurge symlink --paths ./project1 ./project2
+purge symlink --paths ./project1 ./project2
 ```
 
+> **Note (Windows)**: Symlinking requires Administrator privileges or Developer Mode enabled.
+
 ### Clean (Quarantine)
+
+Move packages to quarantine (recoverable):
+
 ```bash
 # First analyze to get targets
-packagepurge analyze > plan.json
+purge analyze --format json > plan.json
 
 # Then quarantine targets
-packagepurge clean --targets $(jq -r '.items[].target_path' plan.json)
+purge clean --targets /path/to/package1 /path/to/package2
 ```
 
 ### Rollback
+
+Restore quarantined packages:
+
 ```bash
 # Rollback latest quarantine
-packagepurge rollback --latest
+purge rollback --latest
 
 # Rollback by ID
-packagepurge rollback --id <quarantine-id>
+purge rollback --id <quarantine-id>
+```
+
+## 🎨 Output Formats
+
+PackagePurge supports three output formats:
+
+| Format | Flag | Description |
+|--------|------|-------------|
+| Table | `--format table` | Human-readable with colors (default) |
+| JSON | `--format json` | Machine-readable for scripting |
+| YAML | `--format yaml` | Alternative structured format |
+
+```bash
+# Default table output
+purge scan
+
+# JSON for piping to jq
+purge scan --format json | jq '.packages | length'
+
+# YAML output
+purge analyze --format yaml
 ```
 
 ## 🔧 Configuration
@@ -104,22 +221,71 @@ Create a `.packagepurge.json` file in your project root:
 }
 ```
 
-## 📊 Metrics
+## 🏗️ Architecture
 
-PackagePurge tracks:
-- **Disk Space Saved**: Total GB recovered
-- **Savings-to-Risk Ratio**: `Disk Space Saved / (Rollbacks + Re-installs)`
-- **Cache Hit Rate**: Percentage of packages preserved by LRU
-- **Project Coverage**: Percentage of projects analyzed
+### Technical Stack
+
+- **Core Engine**: Rust (high-performance scanning and optimization)
+- **CLI**: TypeScript (Node.js) with Commander.js
+- **LRU Cache**: Size-aware with ML-driven predictions
+- **Symlinking**: Cross-platform hard linking and symbolic links
+
+### How It Works
+
+1. **Scan**: Discovers all `node_modules` and cache directories
+2. **Analyze**: Builds dependency graph and identifies orphaned/stale packages
+3. **Optimize**: Uses LRU cache + optional ML to predict which packages to keep
+4. **Clean**: Moves targets to quarantine (reversible) or creates symlinks
+
+## 📊 Cleanup Reasons
+
+| Reason | Color | Description |
+|--------|-------|-------------|
+| Orphaned | Yellow | Not used by any project |
+| Outdated | Gray | Not accessed within preserve period |
+| ML: Unused | Magenta | ML predicts won't be needed |
+| Size Pressure | Red | Cache at capacity, evicting largest |
+| Symlink Candidate | Blue | Duplicate that can be deduplicated |
 
 ## 🛡️ Safety Features
 
-- Automatic backup creation before cleanup
-- Rollback capability for immediate restoration
-- Dry-run mode for previewing changes
-- Project dependency validation before deletion
+- **Automatic backup** before cleanup
+- **Rollback capability** for immediate restoration
+- **Dry-run mode** for previewing changes
+- **Project validation** before deletion
+- **Quarantine system** - nothing is permanently deleted immediately
+
+## 🔧 Troubleshooting
+
+### Windows Symlink Issues
+
+If symlinking fails on Windows:
+
+1. **Enable Developer Mode**: Settings → For Developers → Developer Mode: On
+2. **Or run as Administrator**
+
+### Large Scan Times
+
+For very large directories:
+
+```bash
+# Limit scan depth by specifying paths
+purge scan --paths ./specific-project
+
+# Use quiet mode to reduce output
+purge scan -q --format json
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## 📝 License
 
-MIT
+MIT © [Eng. Onyango Benard](https://github.com/Benaah)
+
+## 🔗 Links
 
+- [GitHub Repository](https://github.com/Benaah/PackagePurge)
+- [npm Package](https://www.npmjs.com/package/packagepurge)
+- [Report Issues](https://github.com/Benaah/PackagePurge/issues)

package/dist/cli/index.d.ts

@@ -1,2 +1,3 @@
+#!/usr/bin/env node
 export {};
 //# sourceMappingURL=index.d.ts.map