cleanout 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# 🧹 cleanout
+
+> *Clean out the clutter, ship the code; one command and your project is clean.*
+
+**`cleanout`** is a lightning-fast CLI tool designed to help you quickly scan and remove unnecessary files and folders from your project directories, freeing up valuable disk space. It automatically targets `node_modules`, build outputs, and log files, while being fully configurable to suit your needs.
+
+---
+
+## ⚡ Features
+
+- **🚀 Fast & Efficient**: Rapidly scans your project to find junk files.
+- **🛡️ Safe by Default**: Always prompts for confirmation before deleting anything (unless you use `--yes`).
+- **🔍 Dry Run Mode**: Preview exactly what will be deleted without touching any files using `--dry-run`.
+- **⚙️ Highly Configurable**: Use a `cleanout.config.json` file or CLI arguments to customize what gets cleaned.
+- **🎨 Beautiful Output**: Colorful and readable CLI interface to easily understand what is using your disk space.
+
+---
+
+## 📦 Installation
+
+Since it's an NPM package, you can run it via `npx` directly, or install it globally to use anywhere on your system.
+
+**Install globally (Recommended):**
+```bash
+npm install -g cleanout
+```
+
+**Run via npx (Without installing):**
+```bash
+npx cleanout
+```
+
+---
+
+## 💻 Usage
+
+Run `cleanout` in any project directory:
+
+```bash
+cd my-project
+cleanout
+```
+
+### 🛠️ Options & Flags
+
+| Flag | Alias | Description |
+|---|---|---|
+| `--dry-run` | `-dr` | Preview actions without deleting anything. |
+| `--yes` | `-y` | Skip confirmation prompts (Warning: Deletes immediately). |
+| `--depth=<n>` | `-d` | Set maximum folder scan depth (Default: Infinity). |
+| `--include=<list>`| `-i` | Comma-separated extra patterns to clean (e.g., `dist,tmp,*.log`). |
+| `--exclude=<list>`| `-e` | Comma-separated patterns to ignore (e.g., `node_modules,build`). |
+| `--stats` | `-st` | Display folder statistics. |
+| `--help` | `-h` | Show help information. |
+
+### 💡 Examples
+
+```bash
+# Preview what would be deleted in the src folder without actually deleting it
+cleanout src --dry-run
+
+# Quick cleanup in the current directory without prompts, limiting depth to 3 levels
+cleanout . --yes --depth=3
+
+# Clean the current directory but skip node_modules and dist
+cleanout . --exclude=node_modules,dist
+
+# Also clean up *.log and tmp files
+cleanout . --include=*.log,tmp
+```
+
+---
+
+## ⚙️ Configuration (Optional)
+
+You can create a `cleanout.config.json` file in your project root to define default behaviors. 
+
+CLI arguments will always override the values in your config file.
+
+**Sample `cleanout.config.json`:**
+```json
+{
+  "dryRun": false,
+  "yes": false,
+  "depth": 5,
+  "include": [
+    "*.log",
+    "tmp",
+    ".cache"
+  ],
+  "exclude": [
+    "dist",
+    "important_logs"
+  ]
+}
+```
+
+---
+
+## 📄 License
+
+MIT © Jaswan Reddy Ch

package/cleanout.config.example.json

@@ -0,0 +1,14 @@
+{
+  "dryRun": false,
+  "yes": false,
+  "depth": 5,
+  "include": [
+    "*.log",
+    "tmp",
+    ".cache"
+  ],
+  "exclude": [
+    "dist",
+    "important_logs"
+  ]
+}

package/cleanout.config.json

@@ -0,0 +1 @@
+{}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cleanout",
+  "version": "1.0.0",
+  "description": "clean out the clutter, ship the code; one command your project is clean.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "cleanout": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cli",
+    "clean",
+    "node_modules",
+    "build",
+    "cleanup"
+  ],
+  "author": "Jaswan Reddy Ch",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaswanreddych/cleanout"
+  },
+  "bugs": {
+    "url": "https://github.com/jaswanreddych/cleanout/issues"
+  },
+  "homepage": "https://github.com/jaswanreddych/cleanout#readme"
+}

package/src/commands/cleanout.js

@@ -0,0 +1,72 @@
+import fs from "fs"
+import { c } from "../constants/color.js"
+import { getSize, scan } from "../utils/scanner.js"
+import { confirm, printDone, printDryRun, printEmptyMatches, printMatches, printStats } from "../utils/ui.js"
+
+export async function cleanout(targetDir, config) {
+    const { dryRun, yes, stats, depth, include, exclude } = config
+
+    const matches = await scan(targetDir, depth, include, exclude)
+
+    for (const item of matches) {
+        item['size'] = await getSize(item.path)
+    }
+
+    if (!(matches.length)) {
+        printEmptyMatches()
+        return
+    }
+
+    let grandTotal = 0
+    const groupMatches = new Map()
+
+    for (const item of matches) {
+        const category = item.category
+        if (!(groupMatches.has(category))) {
+            groupMatches.set(category, {
+                category: category,
+                color: item.color,
+                items: [],
+                total: 0
+            })
+        }
+
+        const entry = groupMatches.get(category)
+        entry.items.push(item)
+        entry.total += item.size
+        grandTotal += item.size
+    }
+
+    const result = [...groupMatches.values()]
+    printMatches(result, grandTotal)
+
+    if (stats) {
+        printStats()
+        return
+    }
+
+    if (dryRun) {
+        printDryRun()
+        return
+    }
+
+    if (!yes) {
+        const confirmation = await confirm(`Are you sure you want to clean all the files and folders (${matches.length})?`)
+        if (!confirmation) {
+            console.log(`Operation cancelled (No files/folders are untouched) `)
+            return
+        }
+    }
+
+    let space = 0
+    for (const item of matches) {
+        try {
+            fs.rmSync(item.path, { recursive: true, force: true })
+            space += item.size
+        } catch (error) {
+            console.log(`${c.red}✖ failed to delete ${item.path}: ${error.message}${c.reset}`)
+        }
+    }
+
+    printDone(space)
+}

package/src/constants/color.js

@@ -0,0 +1,15 @@
+export const c = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+    white: '\x1b[97m',
+    error: "\x1b[31m",
+    success: "\x1b[32m",
+    info: "\x1b[33m",
+    warning: "\x1b[33m",
+}

package/src/constants/common.js

@@ -0,0 +1,57 @@
+export const EXAMPLES = [
+    {
+        cmd: "cleanout",
+        desc: "Scan current directory",
+    },
+    {
+        cmd: "cleanout src --dry-run",
+        desc: "Preview cleanup without deleting files",
+    },
+    {
+        cmd: "cleanout . --yes --depth=3",
+        desc: "Quick cleanup with depth limit",
+    },
+    {
+        cmd: "cleanout . --exclude=node_modules,dist",
+        desc: "Skip build folders",
+    },
+    {
+        cmd: "cleanout . --include=*.log,tmp",
+        desc: "Include extra cleanup patterns",
+    }
+];
+
+export const OPTIONS = [
+    {
+        flags: "-h, --help",
+        desc: "Show help information",
+    },
+    {
+        flags: "-v, --version",
+        desc: "Show current version",
+    },
+    {
+        flags: "-dr, --dry-run",
+        desc: "Preview actions without deleting files",
+    },
+    {
+        flags: "-y, --yes",
+        desc: "Skip confirmation prompts",
+    },
+    {
+        flags: "-st, --stats",
+        desc: "Display folder statistics",
+    },
+    {
+        flags: "-d, --depth=<number>",
+        desc: "Maximum folder scan depth (Default: Infinity)",
+    },
+    {
+        flags: "-i, --include=<list>",
+        desc: "Additional patterns to include (e.g. dist,tmp,*.log)",
+    },
+    {
+        flags: "-e, --exclude=<list>",
+        desc: "Patterns to ignore (e.g. node_modules,build,vendor)",
+    }
+];

package/src/constants/targets.js

@@ -0,0 +1,32 @@
+export const DEFAULT_TARGETS = [
+    {
+        "name": "node_modules",
+        "patterns": [
+            "node_modules"
+        ],
+        "color": "\x1b[36m"
+    },
+    {
+        "name": "Build output",
+        "patterns": [
+            "dist",
+            "build",
+            "out",
+            ".next",
+            ".nuxt",
+            ".svelte-kit",
+            ".vite",
+            "__pycache__"
+        ],
+        "color": "\x1b[33m"
+    },
+    {
+        "name": "Log files",
+        "patterns": [
+            "*.log",
+            "npm-debug.log*",
+            "yarn-error.log"
+        ],
+        "color": "\x1b[90m"
+    },
+]

package/src/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import path from "path"
+import { cleanout } from "./commands/cleanout.js"
+import { c } from "./constants/color.js"
+import { getVersion, loadConfig } from "./utils/config.js"
+import { parseArgs } from "./utils/parseArgs.js"
+import { printBanner, printHelp, printVersion } from "./utils/ui.js"
+
+async function main() {
+    const args = parseArgs(process.argv.slice(2))
+    printBanner()
+    if (args.version) {
+        printVersion(getVersion())
+        process.exit(0)
+    }
+
+    if (args.help) {
+        printHelp()
+        process.exit(0)
+    }
+
+    const targetDir = args.path !== "." ? path.resolve(args.path) : process.cwd()
+    const config = loadConfig(targetDir, args)
+    await cleanout(targetDir, config)
+    process.exit(0)
+}
+
+main().catch(err => {
+    console.log(`\n ${c.error} ${err.message} ${c.reset}\n`)
+    process.exit(1)
+})

package/src/utils/config.js

@@ -0,0 +1,42 @@
+import fs from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+
+export function getVersion() {
+    try {
+        const packagePath = fileURLToPath(new URL("../../package.json", import.meta.url))
+        const packageJSon = JSON.parse(fs.readFileSync(packagePath, "utf-8"))
+        return packageJSon.version ?? "0.0.0"
+    } catch {
+        return "0.0.0"
+    }
+}
+
+export function loadConfig(targetDir, args) {
+    const userConfigPath = path.join(targetDir, "cleanout.config.json");
+
+    let userConfig = {};
+
+    if (fs.existsSync(userConfigPath)) {
+        try {
+            userConfig = JSON.parse(
+                fs.readFileSync(userConfigPath, "utf-8")
+            );
+        } catch {
+            throw new Error("Invalid cleanout.config.json file");
+        }
+    }
+
+    return {
+        ...userConfig,
+        ...args,
+        include: [
+            ...(userConfig.include ?? []),
+            ...(args.include ?? [])
+        ],
+        exclude: [
+            ...(userConfig.exclude ?? []),
+            ...(args.exclude ?? [])
+        ]
+    };
+}

package/src/utils/helper.js

@@ -0,0 +1,29 @@
+function parseList(value) {
+    return value
+        .split(",")
+        .map(item => item.trim())
+        .filter(Boolean)
+}
+
+function requireValue(value, message) {
+    if (!value) {
+        throw new Error(message)
+    }
+    return value
+}
+
+function formatSize(bytes) {
+    try {
+        if (!Number.isInteger(bytes) || bytes < 0) {
+            return "0 b"
+        }
+        const SIZES = ["b", "kb", "mb", "gb", "tb", "pb"]
+        const i = Math.floor(Math.log(bytes) / Math.log(1024))
+        return `${(bytes / Math.pow(1024, i)).toFixed(2)} ${SIZES[i]}`
+    } catch {
+        return "0 b"
+    }
+}
+
+export { formatSize, parseList, requireValue }
+

package/src/utils/parseArgs.js

@@ -0,0 +1,56 @@
+import { parseList, requireValue } from "./helper.js"
+
+export function parseArgs(args) {
+    const result = {
+        path: ".",
+        dryRun: false,
+        help: false,
+        version: false,
+        yes: false,
+        stats: false,
+        depth: Infinity,
+        include: [],
+        exclude: [],
+    }
+
+    const aliases = {
+        "--dry-run": "dryRun",
+        "-dr": "dryRun",
+
+        "--help": "help",
+        "-h": "help",
+
+        "--version": "version",
+        "-v": "version",
+
+        "--yes": "yes",
+        "-y": "yes",
+
+        "--stats": "stats",
+        "-st": "stats"
+    }
+
+    for (const arg of args) {
+        if (aliases[arg]) {
+            result[aliases[arg]] = true
+        } else if (arg.startsWith("--depth") || arg.startsWith("-d")) {
+            const value = requireValue(arg.split("=")[1], "Invalid depth value")
+            const depth = parseInt(value, 10)
+            if (!Number.isInteger(depth) || depth < 1) {
+                throw new Error("Depth must be a positive integer");
+            }
+            result.depth = depth
+        } else if (arg.startsWith("--exclude") || arg.startsWith("-e")) {
+            const value = requireValue(arg?.split("=")[1], "Invalid exclude pattern");
+            result.exclude.push(...parseList(value))
+        } else if (arg.startsWith("--include") || arg.startsWith("-i")) {
+            const value = requireValue(arg?.split("=")[1], "Invalid include patterns");
+            result.include.push(...parseList(value))
+        } else if (!arg.startsWith("-")) {
+            result.path = arg.trim()
+        } else {
+            throw new Error(`Invalid argument: ${arg}. Use --help to see available options.`)
+        }
+    }
+    return result
+}

package/src/utils/scanner.js

@@ -0,0 +1,104 @@
+import { DEFAULT_TARGETS } from "../constants/targets.js";
+import { c } from "../constants/color.js";
+import fsp from "fs/promises";
+import path from "path";
+
+function globToRegex(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*");
+
+    return new RegExp(`^${escaped}$`, "i");
+}
+
+async function searchDir(dir, matchers, depth, maxDepth) {
+    if (depth > maxDepth) {
+        return [];
+    }
+
+    let entries;
+
+    try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+
+    const results = [];
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        const matched = matchers.find(({ regex }) =>
+            regex.test(entry.name)
+        );
+
+        if (matched) {
+            results.push({
+                name: entry.name,
+                path: fullPath,
+                isDirectory: entry.isDirectory(),
+                category: matched.category,
+                pattern: matched.pattern,
+                color: matched.color
+            });
+            continue;
+        }
+
+        if (entry.isDirectory()) {
+            const nestedResults = await searchDir(
+                fullPath,
+                matchers,
+                depth + 1,
+                maxDepth
+            );
+
+            results.push(...nestedResults);
+        }
+    }
+
+    return results;
+}
+
+export async function scan(targetDir, depth, include, exclude) {
+    const targets = [
+        ...DEFAULT_TARGETS,
+        {
+            name: "Custom Includes",
+            patterns: include,
+            color: c.yellow,
+        },
+    ];
+
+    const matchers = targets.flatMap(target =>
+        target.patterns
+            .filter(pattern => pattern && !exclude.includes(pattern))
+            .map(pattern => ({
+                category: target.name,
+                color: target.color,
+                pattern,
+                regex: globToRegex(pattern),
+            }))
+    );
+
+    return searchDir(
+        targetDir,
+        matchers,
+        0,
+        depth
+    );
+}
+
+export async function getSize(targetPath) {
+    try {
+        const stat = await fsp.stat(targetPath)
+        if (!stat.isDirectory()) return stat.size
+        const files = await fsp.readdir(targetPath)
+        const sizes = await Promise.all(
+            files.map(file => getSize(path.join(targetPath, file)))
+        )
+        return sizes.reduce((acc, s) => acc + s, 0)
+    } catch {
+        return 0
+    }
+}

package/src/utils/ui.js

@@ -0,0 +1,110 @@
+import { c } from "../constants/color.js";
+import { EXAMPLES, OPTIONS } from "../constants/common.js";
+import { formatSize } from "./helper.js";
+
+function printOptions(options) {
+    const pad = Math.max(...options.map(o => o.flags.length));
+
+    for (const opt of options) {
+        const spacing = " ".repeat(pad - opt.flags.length + 2);
+
+        console.log(
+            `  ${c.yellow}${opt.flags}${c.reset}${spacing}${opt.desc}`
+        );
+    }
+}
+
+function printExamples(examples) {
+    for (const ex of examples) {
+        console.log(`  ${c.gray}${ex.cmd}${c.reset}`);
+        console.log(`    ${c.dim}${ex.desc}${c.reset}`);
+        console.log();
+    }
+}
+
+
+export function printBanner() {
+    console.log(`\n\t${c.cyan}${c.bold}cleanout${c.reset}  ${c.gray}— clean out the clutter, ship the code; one command your project is clean.${c.reset}`)
+    console.log(`\t${c.gray}${'─'.repeat(85)}${c.reset}\n`)
+}
+
+export function printVersion(version) {
+    console.log(`${c.bold}Version:${c.reset}  ${c.dim}${version}${c.reset}`)
+}
+
+export function printHelp() {
+    console.log(`
+${c.bold}Usage:${c.reset}
+  cleanout ${c.yellow}[path] [options]${c.reset}
+
+${c.bold}Description:${c.reset}
+  Clean and analyze project folders by finding unnecessary files,
+  generating statistics, and producing reports.
+
+${c.bold}Arguments:${c.reset}
+  ${c.yellow}path${c.reset}  Project directory to scan (Default: current directory)
+`);
+
+    console.log(`${c.bold}Options:${c.reset}`);
+    printOptions(OPTIONS);
+
+    console.log(`\n${c.bold}Examples:${c.reset}`);
+    printExamples(EXAMPLES);
+}
+
+export function printEmptyMatches() {
+    console.log(`${c.green}✔  Nothing found to clean!${c.reset}\n`)
+}
+
+function printCategory(group) {
+    const { category, items, color, total } = group
+    const noOfItems = items.length
+    console.log(`${color ?? c['white']}${category} (${noOfItems}) Total Size : ${formatSize(total)} ${c.reset}`)
+}
+
+function printItem(item) {
+    const { name, path, isDirectory, size } = item
+    const icon = isDirectory ? "📁" : "📄"
+    console.log(`   -> ${icon}  ${c.white}${name}${c.reset}${c.gray} (${formatSize(size)}) ${path}${c.reset}`)
+}
+
+
+function printTotal(total) {
+    console.log(`${c.bold}Total: ${c.reset} ${formatSize(total)}\n`)
+}
+
+export function printMatches(groupMatches, grandTotal) {
+    for (const group of groupMatches) {
+        printCategory(group)
+        console.log()
+        for (const item of group.items) {
+            printItem(item)
+        }
+        console.log()
+    }
+    printTotal(grandTotal)
+}
+
+export function printStats() {
+    console.log(`${c.green}This is report of scan (files or folder) found to clean up  ${c.reset}\n`)
+}
+
+export function printDryRun() {
+    console.log(`${c.green}DRY RUN - Completed (no files or folder are deleted) ${c.reset}\n`)
+}
+
+export function confirm(question) {
+    process.stdout.write(` ${c.white}${question}${c.reset} ${c.gray}(y/N)${c.reset} `)
+    return new Promise((resolve) => {
+        process.stdin.setEncoding("utf8")
+        process.stdin.once("data", (data) => {
+            const answer = data.trim().toLowerCase()
+            process.stdin.pause()
+            resolve(answer === "y" || answer === "yes")
+        })
+    })
+}
+
+export function printDone(space) {
+    console.log(`\n${c.green}${c.bold}✔  Done!${c.reset}  Total ${c.yellow}${formatSize(space)}${c.reset} freed`)
+}