projclean 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alexjcm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# projclean
+
+![NPM Version](https://img.shields.io/npm/v/projclean?style=for-the-badge&logo=npm)
+![NPM Downloads](https://img.shields.io/npm/dm/projclean?style=for-the-badge&logo=npm)
+![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
+![React](https://img.shields.io/badge/React_19-20232A?style=for-the-badge&logo=react&logoColor=61DAFB)
+
+![Gradle](https://img.shields.io/badge/Gradle-02303A?style=for-the-badge&logo=gradle&logoColor=white)
+![Maven](https://img.shields.io/badge/Maven-C71A36?style=for-the-badge&logo=apachemaven&logoColor=white)
+
+Interactive TUI to reclaim disk space by finding and cleaning `build/` (Gradle) and `target/` (Maven) folders across all your JVM projects. Scans up to 8 directory levels deep from your home directory.
+
+## Features
+
+- **Fast parallel scanning** — uses `fast-glob` with up to 8 levels deep from `~/`, skipping irrelevant folders (`node_modules`, `.git`, `build`, `target`).
+- **Safety validation** — verifies standard JVM build artifacts before marking a folder for deletion, preventing accidental removal of non-JVM `build/` directories.
+- **Multi-module aware** — consolidates multi-module Gradle/Maven projects (JAR, WAR, EAR, etc.) into a single entry showing accurate module count and combined size.
+- **Concurrent size calculation** — folder sizes are computed in parallel with up to 16 concurrent I/O workers while the TUI is already interactive.
+- **Clean interactive TUI** — keyboard-driven list with selection, bulk operations, and a confirmation dialog before any deletion.
+
+## Requirements
+
+- Node.js >= 24
+
+## Usage
+
+```bash
+npx projclean
+```
+
+Or install globally:
+
+```bash
+npm install -g projclean
+projclean
+```
+
+## Key Bindings
+
+| Key | Action |
+|-----|--------|
+| `↑` / `k` | Move cursor up |
+| `↓` / `j` | Move cursor down |
+| `g` / `G` | Jump to top / bottom of list |
+| `SPACE` | Select / deselect (advances cursor) |
+| `ENTER` | Select / deselect (stays on row) |
+| `a` | Select / deselect all projects |
+| `D` | Delete selected projects |
+| `Q` / `ESC` | Quit |
+
+## Running Locally
+
+```bash
+git clone https://github.com/alexjcm/projclean.git
+cd projclean
+npm install
+npm run dev
+```
+
+## Building
+
+```bash
+npm run build
+```
+
+Compiles TypeScript to `dist/` and marks the output as executable. Test locally with:
+
+```bash
+npm link
+projclean
+```
+
+## Future Enhancements
+
+- [ ] Support for other ecosystems (Node.js `node_modules`, Python `__pycache__`, etc.)
+- [ ] iOS project cleanup (`DerivedData`)
+- [ ] Filter / search by project name

package/dist/core/cleaner.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises';
+import { CONCURRENCY } from './constants.js';
+function getActionableMessage(code) {
+    switch (code) {
+        case 'EACCES':
+            return 'No permission to delete. Run with sudo or adjust folder permissions.';
+        case 'EPERM':
+        case 'EBUSY':
+            return 'Folder is in use by another process. Close IDE or run: ./gradlew --stop';
+        case 'ENOENT':
+            return 'Folder no longer exists — probably deleted earlier.';
+        default:
+            return `Unknown error (${code}). Check system logs.`;
+    }
+}
+/**
+ * Deletes the build folders of the given projects.
+ */
+export async function cleanProjects(projects) {
+    const results = [];
+    let index = 0;
+    const workers = Array.from({ length: Math.min(CONCURRENCY, projects.length) }).map(async () => {
+        while (index < projects.length) {
+            const project = projects[index++];
+            if (!project)
+                continue; // TS safety
+            try {
+                const paths = [...project.submoduleBuildPaths];
+                if (project.buildPath !== null) {
+                    paths.push(project.buildPath);
+                }
+                await Promise.all(paths.map(p => fs.rm(p, { recursive: true, force: true })));
+                results.push({
+                    project,
+                    freed: project.size, // Assuming we trust the snapshot sized before cleaning
+                });
+            }
+            catch (err) {
+                let code = 'ENOENT'; // fallback
+                if (err instanceof Error && 'code' in err && typeof err.code === 'string') {
+                    // Coerce to known code or default message
+                    const c = err.code;
+                    if (['EACCES', 'EPERM', 'EBUSY', 'ENOENT'].includes(c)) {
+                        code = c;
+                    }
+                }
+                results.push({
+                    project,
+                    freed: null,
+                    error: {
+                        code,
+                        message: getActionableMessage(code)
+                    }
+                });
+            }
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

package/dist/core/constants.js

@@ -0,0 +1,41 @@
+/**
+ * Maximum directory depth to scan from the user's home directory.
+ */
+export const SCAN_DEPTH = 8;
+/**
+ * Registry of supported build systems. Order determines precedence.
+ */
+export const SUPPORTED_BUILD_SYSTEMS = [
+    {
+        type: 'gradle',
+        primaryIndicator: 'build.gradle',
+        alternativeIndicators: ['build.gradle.kts'],
+        outputDir: 'build',
+    },
+    {
+        type: 'maven',
+        primaryIndicator: 'pom.xml',
+        outputDir: 'target',
+    },
+];
+/**
+ * Maximum number of concurrent I/O operations during folder size calculation.
+ */
+export const CONCURRENCY = 16;
+/**
+ * Directory names to skip entirely during the recursive scan.
+ */
+export const IGNORED_DIRS = new Set([
+    '.git',
+    '.idea',
+    '.vscode',
+    'node_modules',
+    'target',
+    'build',
+]);
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    FATAL_ERROR: 1,
+    INVALID_ARGUMENT: 2,
+    SIGINT: 130,
+};

package/dist/core/detector.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizePath, toBuildPath } from './paths.js';
+import { SUPPORTED_BUILD_SYSTEMS } from './constants.js';
+/**
+ * Verifies if a directory contains standard JVM build output subdirectories.
+ * This is a "strict" check to prevent accidental deletion of non-JVM folders.
+ */
+async function isJVMBuildFolder(dir, type) {
+    const subdirs = type === 'gradle'
+        ? ['classes', 'libs', 'resources', 'tmp', 'kotlin', 'reports', 'intermediates', 'outputs', 'test-results', 'generated']
+        : ['classes', 'generated-sources', 'maven-status', 'surefire-reports', 'maven-archiver', 'test-classes'];
+    // Run all access checks in parallel — resolves as soon as the first one succeeds.
+    try {
+        await Promise.any(subdirs.map((sub) => fs.access(path.join(dir, sub))));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Attempts to classify and validate a directory as a JVM project.
+ */
+export async function detectProject(dir) {
+    let buildType = null;
+    for (const system of SUPPORTED_BUILD_SYSTEMS) {
+        const indicators = [system.primaryIndicator, ...(system.alternativeIndicators ?? [])];
+        try {
+            await Promise.any(indicators.map((ind) => fs.access(path.join(dir, ind))));
+            buildType = system.type;
+            break;
+        }
+        catch {
+            // None of this system's indicators exist — try next
+        }
+    }
+    if (buildType === null)
+        return null;
+    // Validate build folder existence AND standard contents (safety first!)
+    const expectedBuildPath = toBuildPath(dir, buildType);
+    let buildPath = null;
+    try {
+        await fs.access(expectedBuildPath);
+        if (await isJVMBuildFolder(expectedBuildPath, buildType)) {
+            buildPath = expectedBuildPath;
+        }
+    }
+    catch {
+        // build folder does not exist — buildPath stays null
+    }
+    return {
+        id: normalizePath(dir),
+        rootPath: normalizePath(dir),
+        buildPath,
+        buildType,
+        submoduleBuildPaths: [],
+        size: null,
+    };
+}

package/dist/core/paths.js

@@ -0,0 +1,35 @@
+import os from 'node:os';
+import path from 'node:path';
+import { SUPPORTED_BUILD_SYSTEMS } from './constants.js';
+/**
+ * Returns the user's home directory as the root for scanning,
+ * with separators normalized to forward slashes.
+ */
+export function resolveScanRoot() {
+    return normalizePath(os.homedir());
+}
+/**
+ * Normalizes path separators to forward slashes for consistent
+ * internal storage and fast-glob patterns.
+ */
+export function normalizePath(p) {
+    return path.normalize(p).replaceAll(path.sep, '/');
+}
+/**
+ * Replaces the home directory prefix with '~' if the path is inside it.
+ */
+export function replaceHomeWithTilde(p) {
+    const home = os.homedir().replaceAll(path.sep, '/');
+    const normalized = normalizePath(p);
+    return normalized.startsWith(home)
+        ? `~${normalized.slice(home.length)}`
+        : normalized;
+}
+/**
+ * Constructs the absolute path to the build output folder of a project.
+ */
+export function toBuildPath(projectRoot, type) {
+    const config = SUPPORTED_BUILD_SYSTEMS.find((s) => s.type === type);
+    const folder = config?.outputDir ?? 'build';
+    return normalizePath(path.join(projectRoot, folder));
+}

package/dist/core/scanner.js

@@ -0,0 +1,92 @@
+import EventEmitter from 'node:events';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { resolveScanRoot, normalizePath } from './paths.js';
+import { detectProject } from './detector.js';
+import { SCAN_DEPTH, IGNORED_DIRS, SUPPORTED_BUILD_SYSTEMS } from './constants.js';
+/**
+ * Scans the user's home directory for JVM projects with existing build folders.
+ */
+export class Scanner extends EventEmitter {
+    async scan() {
+        const root = resolveScanRoot();
+        const ignore = [...IGNORED_DIRS].map((d) => `**/${d}/**`);
+        const patterns = SUPPORTED_BUILD_SYSTEMS.flatMap((sys) => {
+            const indicators = [sys.primaryIndicator, ...(sys.alternativeIndicators ?? [])];
+            return indicators.map((ind) => `${root}/**/${ind}`);
+        });
+        try {
+            const files = await fg(patterns, {
+                onlyFiles: true,
+                deep: SCAN_DEPTH,
+                ignore,
+                suppressErrors: true,
+            });
+            // Deduplicate directories (a project may have both build.gradle and build.gradle.kts)
+            const candidateDirs = [
+                ...new Set(files.map((f) => normalizePath(path.dirname(f)))),
+            ];
+            // Sort by path so that parent directories always come before their children.
+            candidateDirs.sort();
+            const roots = new Map();
+            const emittedIds = new Set();
+            const BATCH_SIZE = 10;
+            for (let i = 0; i < candidateDirs.length; i += BATCH_SIZE) {
+                const batch = candidateDirs.slice(i, i + BATCH_SIZE);
+                const results = await Promise.all(batch.map((dir) => detectProject(dir)));
+                for (const project of results) {
+                    if (!project)
+                        continue;
+                    // Find the nearest registered ancestor — O(depth) path-segment walk
+                    // instead of O(n_roots) linear scan across all known roots.
+                    const parent = (() => {
+                        const segments = project.rootPath.split('/');
+                        for (let i = segments.length - 1; i > 0; i--) {
+                            const candidate = segments.slice(0, i).join('/');
+                            const root = roots.get(candidate);
+                            if (root !== undefined)
+                                return root;
+                        }
+                        return undefined;
+                    })();
+                    if (parent !== undefined) {
+                        if (project.buildPath !== null) {
+                            // Deduplicate build paths within a project
+                            if (!parent.submoduleBuildPaths.includes(project.buildPath)) {
+                                parent.submoduleBuildPaths.push(project.buildPath);
+                            }
+                            if (emittedIds.has(parent.id)) {
+                                this.emit('submodule', {
+                                    parentId: parent.id,
+                                    buildPath: project.buildPath,
+                                });
+                            }
+                            else {
+                                // Parent was staged but not emitted yet; now it has a reason to exist!
+                                emittedIds.add(parent.id);
+                                this.emit('project', { ...parent, submoduleBuildPaths: [...parent.submoduleBuildPaths] });
+                            }
+                        }
+                    }
+                    else {
+                        // This is a potential root
+                        const newRoot = { ...project, submoduleBuildPaths: [] };
+                        roots.set(newRoot.id, newRoot);
+                        if (newRoot.buildPath !== null) {
+                            emittedIds.add(newRoot.id);
+                            this.emit('project', { ...newRoot });
+                        }
+                    }
+                }
+                // Give the UI a chance to render before the next batch
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+        catch (error) {
+            this.emit('error', error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            this.emit('done');
+        }
+    }
+}

package/dist/core/size.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CONCURRENCY } from './constants.js';
+/**
+ * Calculates the total size of a directory recursively.
+ * Handles missing permissions gracefully by ignoring restricted folders.
+ *
+ * @param dirPath Absolute path to the directory
+ * @returns Total size in bytes, or null if the base directory is inaccessible
+ */
+export async function calculateSize(dirPath) {
+    try {
+        const stats = await fs.stat(dirPath);
+        if (!stats.isDirectory()) {
+            return stats.size;
+        }
+    }
+    catch (error) {
+        if (isSystemError(error) && ['EACCES', 'EPERM', 'ENOENT', 'EBUSY'].includes(error.code)) {
+            return null;
+        }
+        throw error;
+    }
+    let totalSize = 0;
+    const dirQueue = [dirPath];
+    let activeWorkers = 0;
+    return new Promise((resolve, reject) => {
+        let hasError = false;
+        const processQueue = () => {
+            if (hasError)
+                return;
+            if (dirQueue.length === 0 && activeWorkers === 0) {
+                resolve(totalSize);
+                return;
+            }
+            while (dirQueue.length > 0 && activeWorkers < CONCURRENCY) {
+                const currentDir = dirQueue.shift();
+                activeWorkers++;
+                processDirectory(currentDir).finally(() => {
+                    activeWorkers--;
+                    processQueue();
+                });
+            }
+        };
+        const processDirectory = async (dir) => {
+            try {
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    const entryPath = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        dirQueue.push(entryPath);
+                    }
+                    else {
+                        // Using stat for accurate size, or assuming file size is small enough
+                        // For extreme speed, we could skip stat for files, or just stat files concurrently too
+                        try {
+                            const fileStat = await fs.stat(entryPath);
+                            totalSize += fileStat.size;
+                        }
+                        catch (err) {
+                            if (isSystemError(err) && ['EACCES', 'EPERM', 'ENOENT'].includes(err.code))
+                                continue;
+                            throw err;
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (isSystemError(err) && ['EACCES', 'EPERM', 'ENOENT'].includes(err.code)) {
+                    return;
+                }
+                hasError = true;
+                reject(err);
+            }
+        };
+        processQueue();
+    });
+}
+function isSystemError(err) {
+    return err instanceof Error && 'code' in err && typeof err.code === 'string';
+}

package/dist/core/types.js

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

package/dist/index.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import util from 'node:util';
+import React from 'react';
+import { render } from 'ink';
+import { App } from './ui/App.js';
+import { logger } from './ui/logger.js';
+import { EXIT_CODES } from './core/constants.js';
+import { formatBytes } from './utils/format.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function getVersion() {
+    try {
+        const pkgPath = path.join(__dirname, '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        return pkg.version || '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function printHelp() {
+    const v = getVersion();
+    console.log(`
+  projclean v${v}
+
+  Interactive CLI to detect and clean Maven target/ and Gradle build/ folders.
+  Scans up to 6 levels deep from your home directory to find valid JVM projects.
+
+  Usage:
+    projclean
+
+  Flags:
+    --version     Print version and exit
+    --help        Print this help message and exit
+
+  Shortcuts (when running):
+    ↑/k, ↓/j      Navigate project list
+    g / G          Jump to top / bottom
+    SPACE          Select/Deselect project (advances cursor)
+    ENTER          Select/Deselect project (stays on row)
+    a              Select/Deselect all projects
+    D              Initiate deletion of selected projects
+    Q, ESC         Quit the application
+  `);
+}
+function checkNodeVersion() {
+    const v = process.versions.node;
+    const major = parseInt(v.split('.')[0] || '0', 10);
+    if (major < 24) {
+        logger.error(`This CLI requires Node.js 24 or higher. You are using v${v}`);
+        process.exit(EXIT_CODES.FATAL_ERROR);
+    }
+}
+async function main() {
+    let values;
+    try {
+        const parsed = util.parseArgs({
+            options: {
+                version: { type: 'boolean', short: 'v' },
+                help: { type: 'boolean', short: 'h' },
+            },
+            strict: true,
+        });
+        values = parsed.values;
+    }
+    catch (err) {
+        logger.error('Invalid argument.', err);
+        process.exit(EXIT_CODES.INVALID_ARGUMENT);
+    }
+    if (values.version) {
+        logger.info(`projclean v${getVersion()}`);
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    if (values.help) {
+        printHelp();
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    checkNodeVersion();
+    // Track cumulative space freed across the session
+    let totalFreedInSession = 0;
+    const handleSpaceFreed = (bytes) => {
+        totalFreedInSession += bytes;
+    };
+    const { waitUntilExit } = render(React.createElement(App, { onSpaceFreed: handleSpaceFreed }), {
+        exitOnCtrlC: false,
+    });
+    await waitUntilExit();
+    console.log(`\n  Space released: ${formatBytes(totalFreedInSession)}\n`);
+    process.on('exit', () => {
+        process.stdout.write('\x1B[?25h');
+    });
+}
+main().catch((err) => {
+    logger.error('Unexpected fatal error', err);
+    process.exit(EXIT_CODES.FATAL_ERROR);
+});

package/dist/ui/App.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React, { useState, useEffect, useMemo, useCallback } from 'react';
+import { Box, Static, Text, useApp, useInput } from 'ink';
+import { Spinner } from '@inkjs/ui';
+import { Scanner } from '../core/scanner.js';
+import { calculateSize } from '../core/size.js';
+import { cleanProjects } from '../core/cleaner.js';
+import { EXIT_CODES } from '../core/constants.js';
+import { ProjectList } from './ProjectList.js';
+import { StatusBar } from './StatusBar.js';
+import { ConfirmDialog } from './ConfirmDialog.js';
+import { formatBytes } from '../utils/format.js';
+export const App = ({ onSpaceFreed }) => {
+    const { exit } = useApp();
+    const [projects, setProjects] = useState([]);
+    const [scanStatus, setScanStatus] = useState('scanning');
+    const [selectedIds, setSelectedIds] = useState(new Set());
+    const [confirmOpen, setConfirmOpen] = useState(false);
+    const [cleanResults, setCleanResults] = useState([]);
+    const [isCleaning, setIsCleaning] = useState(false);
+    useEffect(() => {
+        const scanner = new Scanner();
+        scanner.on('project', (project) => {
+            setProjects((prev) => {
+                const exists = prev.some((p) => p.id === project.id);
+                if (exists)
+                    return prev;
+                return [...prev, project];
+            });
+            // Calculate size for the project's own build folder
+            if (project.buildPath !== null) {
+                calculateSize(project.buildPath)
+                    .then((size) => {
+                    setProjects((prev) => prev.map((p) => p.id === project.id ? { ...p, size: (p.size ?? 0) + (size ?? 0) } : p));
+                })
+                    .catch((err) => {
+                    const msg = `Failed to size root for ${project.rootPath}`;
+                    import('./logger.js').then(({ logger }) => logger.error(msg, err));
+                    setProjects((prev) => prev.map((p) => (p.id === project.id ? { ...p, size: p.size ?? 0 } : p)));
+                });
+            }
+            // ALSO calculate size for any submodules already present
+            for (const subPath of project.submoduleBuildPaths) {
+                calculateSize(subPath)
+                    .then((size) => {
+                    setProjects((prev) => prev.map((p) => p.id === project.id ? { ...p, size: (p.size ?? 0) + (size ?? 0) } : p));
+                })
+                    .catch((err) => {
+                    const msg = `Failed to size initial submodule ${subPath} of ${project.id}`;
+                    import('./logger.js').then(({ logger }) => logger.error(msg, err));
+                    setProjects((prev) => prev.map((p) => (p.id === project.id ? { ...p, size: p.size ?? 0 } : p)));
+                });
+            }
+        });
+        scanner.on('submodule', ({ parentId, buildPath }) => {
+            setProjects((prev) => prev.map((p) => p.id === parentId
+                ? { ...p, submoduleBuildPaths: [...p.submoduleBuildPaths, buildPath] }
+                : p));
+            // Start size calculation for the new submodule
+            calculateSize(buildPath)
+                .then((size) => {
+                setProjects((prev) => prev.map((p) => p.id === parentId ? { ...p, size: (p.size ?? 0) + (size ?? 0) } : p));
+            })
+                .catch((err) => {
+                const msg = `Failed to size submodule ${buildPath} of ${parentId}`;
+                import('./logger.js').then(({ logger }) => logger.error(msg, err));
+                setProjects((prev) => prev.map((p) => (p.id === parentId ? { ...p, size: p.size ?? 0 } : p)));
+            });
+        });
+        scanner.on('done', () => {
+            setScanStatus('done');
+        });
+        scanner.on('error', (_err) => {
+            setScanStatus('done');
+        });
+        scanner.scan();
+        return () => {
+            scanner.removeAllListeners();
+        };
+    }, []);
+    // Global Ctrl+C handler
+    useInput((input, key) => {
+        if (key.ctrl && input === 'c') {
+            process.exitCode = EXIT_CODES.SIGINT;
+            exit();
+        }
+    });
+    // Handlers
+    const handleToggleSelection = useCallback((id) => {
+        setSelectedIds((prev) => {
+            const next = new Set(prev);
+            if (next.has(id))
+                next.delete(id);
+            else
+                next.add(id);
+            return next;
+        });
+    }, []);
+    const handleToggleAll = useCallback(() => {
+        setSelectedIds((prev) => {
+            if (prev.size === projects.length && projects.length > 0) {
+                return new Set(); // Deselect all
+            }
+            return new Set(projects.map((p) => p.id)); // Select all
+        });
+    }, [projects]);
+    const handleDeleteRequested = useCallback(() => {
+        if (selectedIds.size > 0) {
+            setConfirmOpen(true);
+        }
+    }, [selectedIds.size]);
+    const handleConfirmCancel = useCallback(() => {
+        setConfirmOpen(false);
+    }, []);
+    const handleConfirmAccept = useCallback(async () => {
+        setConfirmOpen(false);
+        setIsCleaning(true);
+        const selectedProjects = projects.filter((p) => selectedIds.has(p.id));
+        const results = await cleanProjects(selectedProjects);
+        // Calculate total freed in this batch and report it to the caller
+        const freedInBatch = results.reduce((acc, r) => acc + (r.freed ?? 0), 0);
+        onSpaceFreed(freedInBatch);
+        // Append to static logs with a unique key to prevent Ink duplicate key warnings
+        const resultsWithKeys = results.map(r => ({ ...r, uniqueKey: r.project.id + '-' + Math.random().toString(36).substring(2) }));
+        setCleanResults(prev => [...prev, ...resultsWithKeys]);
+        // Remove successful ones from the list
+        const successIds = new Set(results.filter(r => r.freed !== null).map(r => r.project.id));
+        setProjects(prev => prev.filter(p => !successIds.has(p.id)));
+        setSelectedIds(prev => {
+            const next = new Set(prev);
+            for (const id of successIds) {
+                next.delete(id);
+            }
+            return next;
+        });
+        setIsCleaning(false);
+    }, [projects, selectedIds, onSpaceFreed]);
+    // Derived state
+    const totalSelectedSpace = useMemo(() => {
+        let total = 0;
+        for (const p of projects) {
+            if (selectedIds.has(p.id) && p.size !== null) {
+                total += p.size;
+            }
+        }
+        return total;
+    }, [projects, selectedIds]);
+    const totalLiberableSpace = useMemo(() => {
+        return projects.reduce((acc, p) => acc + (p.size ?? 0), 0);
+    }, [projects]);
+    // If cleaning is completely done and Ink is unmounting, we just show the static results
+    return (_jsxs(_Fragment, { children: [_jsx(Static, { items: cleanResults, children: (result) => {
+                    if (result.error) {
+                        return (_jsxs(Box, { children: [_jsx(Box, { width: 3, children: _jsx(Text, { color: "red", children: "\u2716" }) }), _jsx(Box, { children: _jsxs(Text, { color: "red", wrap: "truncate-end", children: [result.project.buildPath ?? result.project.rootPath, ": ", result.error.message] }) })] }, result.uniqueKey));
+                    }
+                    return (_jsxs(Box, { children: [_jsx(Box, { width: 3, children: _jsx(Text, { color: "green", children: "\u2714" }) }), _jsx(Box, { width: 15, children: _jsx(Text, { dimColor: true, children: formatBytes(result.freed ?? 0) }) }), _jsx(Box, { children: _jsx(Text, { wrap: "truncate-end", children: result.project.buildPath ?? result.project.rootPath }) })] }, result.uniqueKey));
+                } }), isCleaning ? (_jsx(Box, { marginTop: 1, paddingX: 2, children: _jsx(Spinner, { label: "Cleaning selected projects\u2026" }) })) : (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(ProjectList, { projects: projects, status: scanStatus, selectedIds: selectedIds, onToggleSelection: handleToggleSelection, onToggleAll: handleToggleAll, onDeleteRequested: handleDeleteRequested, isActive: !confirmOpen, totalLiberable: totalLiberableSpace }), _jsx(ConfirmDialog, { isOpen: confirmOpen, selectedCount: selectedIds.size, totalSpace: totalSelectedSpace, onConfirm: handleConfirmAccept, onCancel: handleConfirmCancel }), _jsx(StatusBar, { selectedSpace: totalSelectedSpace, confirmOpen: confirmOpen })] }))] }));
+};

package/dist/ui/ConfirmDialog.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+import { formatBytes } from '../utils/format.js';
+export const ConfirmDialog = ({ isOpen, selectedCount, totalSpace, onConfirm, onCancel, }) => {
+    useInput((input, key) => {
+        if (key.return) {
+            onConfirm();
+        }
+        else if (key.escape || input.toLowerCase() === 'q' || input.toLowerCase() === 'n') {
+            onCancel();
+        }
+        else if (input.toLowerCase() === 'y') {
+            onConfirm();
+        }
+    }, { isActive: isOpen });
+    if (!isOpen) {
+        return null;
+    }
+    return (_jsxs(Box, { marginTop: 1, paddingX: 1, paddingY: 0, borderStyle: "round", borderColor: "yellow", flexDirection: "column", children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: "yellow", children: "\u26A0" }), _jsxs(Text, { children: ["Delete build folders of", ' ', _jsx(Text, { bold: true, color: "white", children: selectedCount }), selectedCount === 1 ? ' project' : ' projects', "?", ' ', _jsxs(Text, { dimColor: true, children: ["(", formatBytes(totalSpace), ")"] })] })] }), _jsxs(Box, { marginLeft: 2, children: [_jsx(Text, { bold: true, color: "green", children: "Y/Enter" }), _jsx(Text, { dimColor: true, children: " to confirm  " }), _jsx(Text, { bold: true, color: "red", children: "N/Esc" }), _jsx(Text, { dimColor: true, children: " to cancel" })] })] }));
+};

package/dist/ui/ProjectItem.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text } from 'ink';
+import { Spinner } from '@inkjs/ui';
+import { formatBytes } from '../utils/format.js';
+import { replaceHomeWithTilde } from '../core/paths.js';
+import { COL_CHECK, COL_MODULES, COL_SIZE } from './columns.js';
+export const ProjectItem = ({ project, isSelected, isFocused, maxPathWidth, }) => {
+    const isMaven = project.buildType === 'maven';
+    const typeLabel = isMaven ? 'M' : 'G';
+    const typeColor = isMaven ? 'cyan' : 'green';
+    const rowColor = isSelected ? 'green' : (isFocused ? 'white' : undefined);
+    const moduleCount = project.submoduleBuildPaths.length + (project.buildPath ? 1 : 0);
+    return (_jsxs(Box, { children: [_jsx(Box, { width: COL_CHECK, flexShrink: 0, children: _jsx(Text, { color: isSelected ? 'green' : (isFocused ? 'white' : undefined), bold: isSelected || isFocused, children: isSelected ? '● ' : (isFocused ? '› ' : '○ ') }) }), _jsxs(Box, { width: maxPathWidth, flexGrow: 1, marginRight: 2, flexDirection: "row", children: [_jsx(Text, { dimColor: !isFocused && !isSelected, underline: isFocused, color: rowColor, wrap: "truncate-end", bold: isSelected, children: replaceHomeWithTilde(project.rootPath) }), _jsx(Text, { color: isSelected ? 'green' : typeColor, dimColor: !isFocused && !isSelected, bold: true, children: `  (${typeLabel})` })] }), _jsx(Box, { width: COL_MODULES, flexShrink: 0, marginRight: 1, children: moduleCount > 1 && (_jsx(Text, { dimColor: !isSelected, color: isSelected ? 'green' : 'cyan', children: `${moduleCount} mods` })) }), _jsx(Box, { width: COL_SIZE, flexShrink: 0, justifyContent: "flex-end", children: project.size === null ? (_jsxs(Box, { flexDirection: "row", gap: 1, children: [_jsx(Spinner, { type: "dots" }), _jsx(Text, { color: "yellow", children: "sizing" })] })) : (_jsx(Text, { color: rowColor, dimColor: !isFocused && !isSelected, children: formatBytes(project.size) })) })] }));
+};

package/dist/ui/ProjectList.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useState } from 'react';
+import { Box, Text, useInput, useApp, useStdout } from 'ink';
+import { Spinner } from '@inkjs/ui';
+import { ProjectItem } from './ProjectItem.js';
+import { formatBytes } from '../utils/format.js';
+import { EXIT_CODES } from '../core/constants.js';
+import { calcPathWidth } from './columns.js';
+export const ProjectList = ({ projects, status, selectedIds, onToggleSelection, onToggleAll, onDeleteRequested, isActive, totalLiberable, }) => {
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const rows = stdout?.rows ?? 24;
+    const columns = stdout?.columns ?? 80;
+    const [cursor, setCursor] = useState(0);
+    // Compute once here and pass down — avoids N useStdout listeners in ProjectItem rows.
+    const maxPathWidth = calcPathWidth(columns);
+    // Maximum number of items to display on screen
+    const visibleCount = Math.max(5, rows - 10);
+    const activeCursor = projects.length === 0 ? 0 : Math.min(cursor, projects.length - 1);
+    useInput((input, key) => {
+        if (projects.length === 0 && input !== 'q')
+            return;
+        if (key.upArrow || input === 'k') {
+            setCursor((c) => Math.max(0, c - 1));
+        }
+        else if (key.downArrow || input === 'j') {
+            setCursor((c) => Math.min(projects.length - 1, c + 1));
+        }
+        else if (input === 'g') {
+            setCursor(0);
+        }
+        else if (input === 'G') {
+            setCursor(projects.length - 1);
+        }
+        else if (input === ' ' || key.return) {
+            const p = projects[activeCursor];
+            if (p)
+                onToggleSelection(p.id);
+            if (input === ' ') {
+                setCursor((c) => Math.min(projects.length - 1, c + 1));
+            }
+        }
+        else if (input === 'a') {
+            onToggleAll();
+        }
+        else if (input === 'd' || input === 'D') {
+            if (selectedIds.size > 0) {
+                onDeleteRequested();
+            }
+        }
+        else if (input === 'q' || input === 'Q') {
+            process.exitCode = EXIT_CODES.SUCCESS;
+            exit();
+        }
+    }, { isActive: isActive });
+    // Calculate slice of projects to display
+    let startIndex = 0;
+    if (projects.length > visibleCount) {
+        // Keep cursor roughly in the middle if possible
+        startIndex = Math.max(0, activeCursor - Math.floor(visibleCount / 2));
+        // Don't scroll past the bottom
+        if (startIndex + visibleCount > projects.length) {
+            startIndex = projects.length - visibleCount;
+        }
+    }
+    const visibleProjects = projects.slice(startIndex, startIndex + visibleCount);
+    const isScanning = status === 'scanning';
+    // Only show total once at least one size has been resolved
+    const showTotal = totalLiberable > 0;
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Box, { paddingX: 1, marginBottom: 1, children: projects.length === 0 && isScanning ? (_jsx(Box, { marginLeft: 1, children: _jsx(Spinner, { label: "Scanning for Gradle/Maven projects..." }) })) : projects.length === 0 && status === 'done' ? (_jsx(Box, { borderStyle: "round", borderColor: "yellow", padding: 1, width: "100%", children: _jsx(Text, { color: "yellow", children: "No cleanable JVM projects found in home directory." }) })) : (_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", flexGrow: 1, children: [_jsxs(Box, { children: [_jsxs(Text, { bold: true, children: ["Found ", projects.length, " ", projects.length === 1 ? 'project' : 'projects'] }), isScanning && (_jsx(Box, { marginLeft: 2, children: _jsx(Spinner, { label: "Scanning..." }) }))] }), showTotal && (_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "Total Liberable: " }), _jsx(Text, { color: "cyan", bold: true, children: formatBytes(totalLiberable) })] }))] })) }), projects.length > 0 && (_jsxs(Box, { paddingX: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: 3 }), _jsx(Box, { width: maxPathWidth, flexGrow: 1, marginRight: 2, children: _jsx(Text, { color: "gray", bold: true, children: "PROJECT (TYPE)" }) }), _jsx(Box, { width: 8, marginRight: 1, children: _jsx(Text, { color: "gray", bold: true, children: "MODULES" }) }), _jsx(Box, { width: 15, justifyContent: "flex-end", children: _jsx(Text, { color: "gray", bold: true, children: "SIZE" }) })] }), _jsx(Box, { marginTop: 0, marginBottom: 0, children: _jsx(Text, { dimColor: true, children: "─".repeat(Math.min(columns - 2, 100)) }) })] })), _jsx(Box, { flexDirection: "column", paddingX: 1, minHeight: visibleCount, children: visibleProjects.map((project, i) => {
+                    const globalIndex = startIndex + i;
+                    return (_jsx(ProjectItem, { project: project, isSelected: selectedIds.has(project.id), isFocused: isActive && globalIndex === activeCursor, maxPathWidth: maxPathWidth }, project.id));
+                }) })] }));
+};

package/dist/ui/StatusBar.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text } from 'ink';
+import { formatBytes } from '../utils/format.js';
+export const StatusBar = ({ selectedSpace, confirmOpen }) => {
+    return (_jsx(Box, { marginTop: 1, flexDirection: "column", children: _jsxs(Box, { paddingX: 1, backgroundColor: "gray", children: [_jsx(Box, { flexGrow: 1, gap: 2, children: _jsxs(Box, { children: [_jsx(Text, { color: "black", bold: true, children: ' Selected: ' }), _jsx(Text, { color: "green", bold: true, children: formatBytes(selectedSpace) })] }) }), _jsx(Box, { children: confirmOpen ? (_jsx(Text, { color: "black", dimColor: true, children: "Waiting for confirmation\u2026" })) : (_jsxs(Text, { color: "black", children: [_jsx(Text, { bold: true, children: "\u2191\u2193/jk" }), " move \u2022 ", _jsx(Text, { bold: true, children: "g/G" }), " top/bottom \u2022", ' ', _jsx(Text, { bold: true, children: "SPACE" }), " select \u2022 ", _jsx(Text, { bold: true, children: "a" }), " all \u2022", ' ', _jsx(Text, { bold: true, children: "D" }), " delete \u2022 ", _jsx(Text, { bold: true, children: "Q" }), " quit"] })) })] }) }));
+};

package/dist/ui/columns.js

@@ -0,0 +1,11 @@
+/**
+ * Column layout constants shared between ProjectList (headers)
+ * and ProjectItem (rows). Centralised here to prevent misalignment.
+ */
+export const COL_CHECK = 3;
+export const COL_MODULES = 8;
+export const COL_SIZE = 15;
+export const MIN_PATH_WIDTH = 40;
+export function calcPathWidth(terminalColumns) {
+    return Math.max(MIN_PATH_WIDTH, terminalColumns - (COL_CHECK + COL_MODULES + COL_SIZE + 5));
+}

package/dist/ui/logger.js

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+export const logger = {
+    info: (msg) => console.log(`  ${msg}`),
+    success: (msg) => console.log(`✔ ${msg}`),
+    warn: (msg) => console.warn(`⚠ ${msg}`),
+    error: (msg, err) => {
+        if (process.env['NODE_ENV'] === 'development') {
+            const logMsg = `[${new Date().toISOString()}] ✖ ${msg}${err instanceof Error ? `: ${err.message}` : ''}\n`;
+            try {
+                fs.appendFileSync('projclean.log', logMsg);
+            }
+            catch {
+                // Fallback or ignore if write fails
+            }
+        }
+        console.error(`✖ ${msg}`);
+        if (err instanceof Error)
+            console.error(`  ${err.message}`);
+    },
+};

package/dist/utils/format.js

@@ -0,0 +1,50 @@
+const BYTES_IN_KB = 1024;
+const BYTES_IN_MB = 1024 * 1024;
+const BYTES_IN_GB = 1024 * 1024 * 1024;
+/**
+ * Converts a byte count into a human-readable string.
+ *
+ * @example
+ * formatBytes(358_400_000)  // "341.8 MB"
+ * formatBytes(2_147_483_648) // "2.0 GB"
+ * formatBytes(512)           // "512 B"
+ */
+export function formatBytes(bytes) {
+    if (bytes >= BYTES_IN_GB) {
+        return `${(bytes / BYTES_IN_GB).toFixed(1)} GB`;
+    }
+    if (bytes >= BYTES_IN_MB) {
+        return `${(bytes / BYTES_IN_MB).toFixed(1)} MB`;
+    }
+    if (bytes >= BYTES_IN_KB) {
+        return `${(bytes / BYTES_IN_KB).toFixed(1)} KB`;
+    }
+    return `${bytes} B`;
+}
+/**
+ * Truncates a path string to fit within `maxWidth` characters,
+ * always preserving the final path segment (the project folder name).
+ */
+export function truncatePath(p, maxWidth) {
+    // Normalize separators for display
+    const normalized = p.replaceAll('\\', '/');
+    if (normalized.length <= maxWidth) {
+        return normalized;
+    }
+    const segments = normalized.split('/');
+    const last = segments[segments.length - 1] ?? '';
+    const prefix = '~/…/';
+    const available = maxWidth - prefix.length - last.length;
+    if (available <= 0) {
+        return last;
+    }
+    const middle = [];
+    for (let i = segments.length - 2; i >= 0; i--) {
+        const segment = segments[i] ?? '';
+        const candidate = [segment, ...middle].join('/');
+        if (candidate.length > available)
+            break;
+        middle.unshift(segment);
+    }
+    return `${prefix}${middle.length > 0 ? middle.join('/') + '/' : ''}${last}`;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "projclean",
+  "version": "1.0.0",
+  "description": "Interactive CLI to detect and clean Gradle build/ and Maven target/ folders",
+  "author": "alexjcm",
+  "license": "MIT",
+  "homepage": "https://github.com/alexjcm/projclean#readme",
+  "type": "module",
+  "bin": {
+    "projclean": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "dev": "tsx src/index.tsx",
+    "lint": "eslint .",
+    "prebuild": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/index.js"
+  },
+  "dependencies": {
+    "@inkjs/ui": "2.0.0",
+    "fast-glob": "3.3.3",
+    "ink": "6.8.0",
+    "react": "19.2.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "@types/react": "19.2.14",
+    "eslint": "^10.1.0",
+    "globals": "^17.4.0",
+    "tsx": "^4.21.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.57.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "cli",
+    "tui",
+    "jvm",
+    "java",
+    "maven",
+    "gradle",
+    "build",
+    "clean",
+    "disk-space"
+  ],
+  "packageManager": "npm@11.4.2+sha512.f90c1ec8b207b625d6edb6693aef23dacb39c38e4217fe8c46a973f119cab392ac0de23fe3f07e583188dae9fd9108b3845ad6f525b598742bd060ebad60bff3"
+}