@tukuyomil032/broom 1.0.0

package/dist/utils/debug.js

@@ -0,0 +1,119 @@
+/**
+ * Debug utilities for Broom CLI
+ */
+import chalk from 'chalk';
+let debugMode = false;
+/**
+ * Enable debug mode
+ */
+export function enableDebug() {
+    debugMode = true;
+}
+/**
+ * Disable debug mode
+ */
+export function disableDebug() {
+    debugMode = false;
+}
+/**
+ * Check if debug mode is enabled
+ */
+export function isDebugEnabled() {
+    return debugMode;
+}
+/**
+ * Log debug message
+ */
+export function debug(message, ...args) {
+    if (!debugMode) {
+        return;
+    }
+    const timestamp = new Date().toISOString().split('T')[1].slice(0, 12);
+    console.log(chalk.dim(`[${timestamp}] `) + chalk.magenta('[DEBUG] ') + message, ...args);
+}
+/**
+ * Log debug object
+ */
+export function debugObj(label, obj) {
+    if (!debugMode) {
+        return;
+    }
+    const timestamp = new Date().toISOString().split('T')[1].slice(0, 12);
+    console.log(chalk.dim(`[${timestamp}] `) + chalk.magenta('[DEBUG] ') + chalk.cyan(label + ':'));
+    console.log(JSON.stringify(obj, null, 2));
+}
+/**
+ * Log debug section header
+ */
+export function debugSection(title) {
+    if (!debugMode) {
+        return;
+    }
+    console.log();
+    console.log(chalk.magenta('━'.repeat(60)));
+    console.log(chalk.magenta.bold(`[DEBUG] ${title}`));
+    console.log(chalk.magenta('━'.repeat(60)));
+}
+/**
+ * Log debug timing
+ */
+export function debugTime(label) {
+    if (!debugMode) {
+        return () => { };
+    }
+    const start = performance.now();
+    debug(`Starting: ${label}`);
+    return () => {
+        const duration = performance.now() - start;
+        debug(`Completed: ${label} (${duration.toFixed(2)}ms)`);
+    };
+}
+/**
+ * Debug wrapper for async functions
+ */
+export async function debugAsync(label, fn) {
+    const end = debugTime(label);
+    try {
+        const result = await fn();
+        end();
+        return result;
+    }
+    catch (error) {
+        debug(`Error in ${label}: ${error}`);
+        throw error;
+    }
+}
+/**
+ * Log file operation
+ */
+export function debugFile(operation, path, details) {
+    if (!debugMode) {
+        return;
+    }
+    const opColors = {
+        scan: chalk.blue,
+        read: chalk.cyan,
+        write: chalk.yellow,
+        delete: chalk.red,
+        skip: chalk.gray,
+    };
+    const colorFn = opColors[operation.toLowerCase()] || chalk.white;
+    const detailsStr = details ? chalk.dim(` (${details})`) : '';
+    debug(`${colorFn(operation.toUpperCase().padEnd(6))} ${path}${detailsStr}`);
+}
+/**
+ * Log risk level info
+ */
+export function debugRisk(path, level, reason) {
+    if (!debugMode) {
+        return;
+    }
+    const colors = {
+        safe: chalk.green,
+        moderate: chalk.yellow,
+        risky: chalk.red,
+    };
+    const colorFn = colors[level];
+    const reasonStr = reason ? chalk.dim(` - ${reason}`) : '';
+    debug(`Risk: ${colorFn(level.toUpperCase())} ${path}${reasonStr}`);
+}

package/dist/utils/fs.js

@@ -0,0 +1,283 @@
+/**
+ * File system utilities for Broom CLI
+ */
+import { stat, readdir, rm, access, lstat, unlink } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+// Protected system paths that should NEVER be deleted
+const PROTECTED_PATHS = [
+    '/System',
+    '/usr',
+    '/bin',
+    '/sbin',
+    '/etc',
+    '/var/log',
+    '/var/db',
+    '/var/root',
+    '/private/var/db',
+    '/private/var/root',
+    '/Library/Apple',
+    '/Applications/Utilities',
+];
+// Excluded paths (iCloud Drive, etc.)
+const EXCLUDED_PATHS = ['iCloud Drive', 'Mobile Documents', '.Trash'];
+// Allowed cache/temp paths
+const ALLOWED_PATHS = [
+    '/tmp',
+    '/private/tmp',
+    '/var/tmp',
+    '/private/var/tmp',
+    '/var/folders',
+    '/private/var/folders',
+];
+/**
+ * Check if a path should be excluded from scanning
+ */
+export function isExcludedPath(path) {
+    const normalizedPath = path.toLowerCase();
+    for (const excluded of EXCLUDED_PATHS) {
+        if (normalizedPath.includes(excluded.toLowerCase())) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if a path is a protected system path
+ */
+export function isProtectedPath(path) {
+    const normalizedPath = resolve(path);
+    // Check allowed paths first
+    for (const allowed of ALLOWED_PATHS) {
+        if (normalizedPath.startsWith(allowed)) {
+            return false;
+        }
+    }
+    // Check protected paths
+    for (const protected_ of PROTECTED_PATHS) {
+        if (normalizedPath === protected_ || normalizedPath.startsWith(protected_ + '/')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if a path exists
+ */
+export function exists(path) {
+    return existsSync(path);
+}
+/**
+ * Check if a path exists (async)
+ */
+export async function existsAsync(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get file/directory size recursively
+ * Uses 'du' command for efficiency on large directories
+ */
+export async function getSize(path) {
+    try {
+        const stats = await stat(path);
+        if (stats.isFile()) {
+            return stats.size;
+        }
+        if (stats.isDirectory()) {
+            // Use du command for efficient directory size calculation
+            try {
+                const { stdout } = await execAsync(`du -sk "${path}" 2>/dev/null || echo "0"`);
+                const sizeKb = parseInt(stdout.split('\t')[0], 10);
+                return isNaN(sizeKb) ? 0 : sizeKb * 1024;
+            }
+            catch {
+                // Fallback to recursive calculation for small directories
+                return getSizeRecursive(path);
+            }
+        }
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Recursive size calculation (fallback)
+ */
+async function getSizeRecursive(path, depth = 0, maxDepth = 5) {
+    if (depth > maxDepth) {
+        return 0; // Limit recursion depth
+    }
+    try {
+        const stats = await stat(path);
+        if (stats.isFile()) {
+            return stats.size;
+        }
+        if (stats.isDirectory()) {
+            const files = await readdir(path);
+            let total = 0;
+            // Process in batches to avoid memory issues
+            for (const file of files) {
+                total += await getSizeRecursive(join(path, file), depth + 1, maxDepth);
+            }
+            return total;
+        }
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Format bytes to human-readable string
+ */
+export function formatSize(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(2)} ${units[unitIndex]}`;
+}
+/**
+ * Get all files in a directory (non-recursive)
+ */
+export async function getFilesInDirectory(path) {
+    try {
+        if (!exists(path)) {
+            return [];
+        }
+        const stats = await stat(path);
+        if (!stats.isDirectory()) {
+            return [];
+        }
+        const files = await readdir(path);
+        return files.map((file) => join(path, file));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check if path is a directory
+ */
+export async function isDirectory(path) {
+    try {
+        const stats = await stat(path);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove a file or directory
+ */
+export async function remove(path) {
+    if (isProtectedPath(path)) {
+        throw new Error(`Cannot remove protected path: ${path}`);
+    }
+    try {
+        await rm(path, { recursive: true, force: true });
+    }
+    catch (error) {
+        throw new Error(`Failed to remove ${path}: ${error.message}`);
+    }
+}
+/**
+ * Remove a single item
+ */
+export async function removeItem(path, dryRun = false) {
+    if (isProtectedPath(path)) {
+        return false;
+    }
+    if (dryRun) {
+        return true;
+    }
+    try {
+        const stats = await lstat(path);
+        if (stats.isSymbolicLink()) {
+            await unlink(path);
+        }
+        else {
+            await rm(path, { recursive: true, force: true });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove multiple items
+ */
+export async function removeItems(items, dryRun = false, onProgress) {
+    let success = 0;
+    let failed = 0;
+    let freedSpace = 0;
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (onProgress) {
+            onProgress(i + 1, items.length, item);
+        }
+        const removed = await removeItem(item.path, dryRun);
+        if (removed) {
+            success++;
+            freedSpace += item.size;
+        }
+        else {
+            failed++;
+        }
+    }
+    return { success, failed, freedSpace };
+}
+/**
+ * Create a cleanable item from a path
+ */
+export async function createCleanableItem(path) {
+    try {
+        if (!exists(path)) {
+            return null;
+        }
+        const stats = await stat(path);
+        const size = await getSize(path);
+        const name = path.split('/').pop() || path;
+        return {
+            path,
+            size,
+            name,
+            isDirectory: stats.isDirectory(),
+            modifiedAt: stats.mtime,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get home directory
+ */
+export function getHomeDir() {
+    return homedir();
+}
+/**
+ * Expand ~ to home directory
+ */
+export function expandPath(path) {
+    if (path.startsWith('~')) {
+        return path.replace('~', homedir());
+    }
+    return path;
+}

package/dist/utils/help.js

@@ -0,0 +1,265 @@
+/**
+ * Custom help utilities for enhanced command option display
+ */
+import chalk from 'chalk';
+/**
+ * Analyze option to determine its type and properties
+ */
+function analyzeOption(option) {
+    const flags = option.flags;
+    const description = option.description || '';
+    let type = 'boolean';
+    let required = false;
+    if (flags.includes('<') && flags.includes('>')) {
+        required = true;
+        const argMatch = flags.match(/<([^>]+)>/);
+        const argName = argMatch ? argMatch[1] : '';
+        if (argName.toLowerCase().includes('number') ||
+            argName.toLowerCase().includes('count') ||
+            argName.toLowerCase().includes('seconds') ||
+            argName.toLowerCase().includes('interval') ||
+            argName.toLowerCase().includes('depth') ||
+            argName.toLowerCase().includes('limit')) {
+            type = 'number';
+        }
+        else {
+            type = 'string';
+        }
+    }
+    else if (flags.includes('[') && flags.includes(']')) {
+        required = false;
+        const argMatch = flags.match(/\[([^\]]+)\]/);
+        const argName = argMatch ? argMatch[1] : '';
+        if (argName.toLowerCase().includes('number') ||
+            argName.toLowerCase().includes('count') ||
+            argName.toLowerCase().includes('seconds') ||
+            argName.toLowerCase().includes('interval') ||
+            argName.toLowerCase().includes('depth') ||
+            argName.toLowerCase().includes('limit')) {
+            type = 'number';
+        }
+        else {
+            type = 'string';
+        }
+    }
+    return {
+        flags,
+        description,
+        type,
+        required,
+        defaultValue: option.defaultValue?.toString(),
+    };
+}
+/**
+ * Strip ANSI codes to get actual visual length
+ */
+function getVisualLength(str) {
+    return str.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+/**
+ * Generate formatted options table with perfect alignment
+ */
+export function generateOptionsTable(command) {
+    const options = command.options;
+    if (options.length === 0) {
+        return chalk.dim('  No options available.');
+    }
+    const optionInfos = options.map(analyzeOption);
+    const flagWidth = 24;
+    const typeWidth = 10;
+    const reqWidth = 10;
+    const descWidth = 49;
+    let output = '\n';
+    // Calculate border length
+    const borderLength = flagWidth + typeWidth + reqWidth + descWidth + 3;
+    // Top border
+    output += '  ' + '─'.repeat(borderLength) + '\n';
+    // Header
+    output +=
+        '  ' +
+            'FLAG'.padEnd(flagWidth) +
+            'TYPE'.padEnd(typeWidth) +
+            'REQUIRED'.padEnd(reqWidth) +
+            'DESCRIPTION'.padEnd(descWidth) +
+            '\n';
+    // Header separator
+    output += '  ' + '─'.repeat(borderLength) + '\n';
+    // Data rows
+    for (const info of optionInfos) {
+        const desc = info.description + (info.defaultValue ? ` (default: ${info.defaultValue})` : '');
+        const truncDesc = desc.length > descWidth - 2 ? desc.substring(0, descWidth - 5) + '...' : desc;
+        const flagCell = chalk.cyan(info.flags);
+        const typeCell = getTypeColor(info.type);
+        const reqCell = info.required ? chalk.red('Yes') : chalk.green('No');
+        const descCell = truncDesc;
+        const flagPad = flagWidth - getVisualLength(flagCell);
+        const typePad = typeWidth - getVisualLength(typeCell);
+        const reqPad = reqWidth - getVisualLength(reqCell);
+        const descPad = descWidth - getVisualLength(descCell);
+        output +=
+            '  ' +
+                flagCell +
+                ' '.repeat(Math.max(0, flagPad)) +
+                typeCell +
+                ' '.repeat(Math.max(0, typePad)) +
+                reqCell +
+                ' '.repeat(Math.max(0, reqPad)) +
+                descCell +
+                ' '.repeat(Math.max(0, descPad)) +
+                '\n';
+    }
+    // Bottom border
+    output += '  ' + '─'.repeat(borderLength) + '\n';
+    return output;
+}
+/**
+ * Get colored type string
+ */
+function getTypeColor(type) {
+    switch (type) {
+        case 'boolean':
+            return chalk.green('boolean');
+        case 'string':
+            return chalk.blue('string');
+        case 'number':
+            return chalk.yellow('number');
+        default:
+            return chalk.white('unknown');
+    }
+}
+/**
+ * Enhanced help formatter that includes options table
+ */
+export function formatCommandHelp(command) {
+    const name = command.name();
+    const description = command.description();
+    const usage = command.usage();
+    const args = command.args;
+    let help = '';
+    help += chalk.bold('Usage: ') + `${name} ${usage || '[options]'}\n\n`;
+    if (description) {
+        help += description + '\n\n';
+    }
+    if (args.length > 0) {
+        help += chalk.bold('Arguments:\n');
+        for (const arg of args) {
+            const argName = arg.name || arg;
+            const argDesc = arg.description || '';
+            const required = `[${argName}]`;
+            help += `  ${required.padEnd(20)} ${argDesc}\n`;
+        }
+        help += '\n';
+    }
+    help += generateOptionsTable(command);
+    const examples = getExamplesFromDescription(description);
+    if (examples.length > 0) {
+        help += '\n' + chalk.bold('Examples:\n');
+        examples.forEach((example) => {
+            help += `  ${chalk.dim('$')} ${chalk.cyan(example)}\n`;
+        });
+    }
+    return help;
+}
+/**
+ * Extract examples from command description
+ */
+function getExamplesFromDescription(description) {
+    if (!description) {
+        return [];
+    }
+    const examples = [];
+    if (description.includes('cleanup') || description.includes('clean')) {
+        examples.push('broom clean --dry-run', 'broom clean --all', 'broom clean --debug');
+    }
+    if (description.includes('uninstall') || description.includes('remove')) {
+        examples.push('broom uninstall --dry-run', 'broom uninstall --debug');
+    }
+    if (description.includes('optimize') || description.includes('maintenance')) {
+        examples.push('broom optimize --all', 'broom optimize --dry-run');
+    }
+    if (description.includes('analyze')) {
+        examples.push('broom analyze ~/Downloads', 'broom analyze --depth 2');
+    }
+    if (description.includes('status') || description.includes('monitor')) {
+        examples.push('broom status', 'broom status --interval 5');
+    }
+    return examples;
+}
+/**
+ * Apply custom help formatting to a command
+ */
+export function enhanceCommandHelp(command) {
+    command.configureHelp({
+        formatHelp: () => formatCommandHelp(command),
+    });
+    return command;
+}
+/**
+ * Global options information for main help
+ */
+export function getGlobalOptionsTable() {
+    const globalOptions = [
+        {
+            flags: '-v, --version',
+            description: 'Output the current version',
+            type: 'boolean',
+            required: false,
+        },
+        {
+            flags: '--debug',
+            description: 'Enable debug mode with detailed logs',
+            type: 'boolean',
+            required: false,
+        },
+        {
+            flags: '-h, --help',
+            description: 'Display help for command',
+            type: 'boolean',
+            required: false,
+        },
+    ];
+    const flagWidth = 24;
+    const typeWidth = 10;
+    const reqWidth = 10;
+    const descWidth = 49;
+    let output = '\n';
+    // Calculate border length
+    const borderLength = flagWidth + typeWidth + reqWidth + descWidth + 3;
+    // Top border
+    output += '  ' + '─'.repeat(borderLength) + '\n';
+    // Header
+    output +=
+        '  ' +
+            'FLAG'.padEnd(flagWidth) +
+            'TYPE'.padEnd(typeWidth) +
+            'REQUIRED'.padEnd(reqWidth) +
+            'DESCRIPTION'.padEnd(descWidth) +
+            '\n';
+    // Header separator
+    output += '  ' + '─'.repeat(borderLength) + '\n';
+    // Data rows
+    for (const option of globalOptions) {
+        const flagCell = chalk.cyan(option.flags);
+        const typeCell = getTypeColor(option.type);
+        const reqCell = option.required ? chalk.red('Yes') : chalk.green('No');
+        const descCell = option.description;
+        const flagPad = flagWidth - getVisualLength(flagCell);
+        const typePad = typeWidth - getVisualLength(typeCell);
+        const reqPad = reqWidth - getVisualLength(reqCell);
+        const descPad = descWidth - getVisualLength(descCell);
+        output +=
+            '  ' +
+                flagCell +
+                ' '.repeat(Math.max(0, flagPad)) +
+                typeCell +
+                ' '.repeat(Math.max(0, typePad)) +
+                reqCell +
+                ' '.repeat(Math.max(0, reqPad)) +
+                descCell +
+                ' '.repeat(Math.max(0, descPad)) +
+                '\n';
+    }
+    // Bottom border
+    output += '  ' + '─'.repeat(borderLength) + '\n';
+    return output;
+}

package/dist/utils/index.js

@@ -0,0 +1,6 @@
+/**
+ * Utils module exports
+ */
+export * from './fs.js';
+export * from './paths.js';
+export * from './config.js';