devkill 0.12.2

package/lib/core/interfaces/folder.interface.d.ts

@@ -0,0 +1,89 @@
+/** Unit for representing file/directory sizes. */
+export type SizeUnit = 'bytes';
+/** Options soported for the sortBy scan option. */
+export type SortBy = 'path' | 'size' | 'age';
+/**
+ * Analysis of potential risks associated with deleting a directory.
+ */
+export interface RiskAnalysis {
+    /** Whether the directory is considered sensitive or risky to delete. */
+    isSensitive: boolean;
+    /** Human-readable reason for the risk assessment. */
+    reason?: string;
+}
+/**
+ * Represents a folder found during the scan process.
+ */
+export interface ScanFoundFolder {
+    /** Full path to the found folder. */
+    path: string;
+    /** Optional risk analysis for the folder. */
+    riskAnalysis?: RiskAnalysis;
+}
+/**
+ * Configuration options for scanning directories.
+ */
+export interface ScanOptions {
+    /** Target directories to scan for matching folders. */
+    targets: string[];
+    /** Array of directory paths to exclude from the scan. */
+    exclude?: string[];
+    /** Criteria for sorting scan results. */
+    sortBy?: SortBy;
+    /** Whether to perform risk analysis on found directories. Default: true. */
+    performRiskAnalysis?: boolean;
+}
+/**
+ * Options for calculating directory size.
+ */
+export interface GetSizeOptions {
+    /** Unit to return the size in. Default: bytes. */
+    unit?: SizeUnit;
+}
+/**
+ * Result of a directory size calculation.
+ */
+export interface GetSizeResult {
+    /** Size value in the specified unit. Default: bytes. */
+    size: number;
+    /** Unit of the size measurement. */
+    unit: SizeUnit;
+}
+/**
+ * Options for finding the newest file in a directory.
+ */
+export type GetNewestFileOptions = {};
+/**
+ * Information about the most recently modified file in a directory.
+ */
+export interface GetNewestFileResult {
+    /** Full path to the newest file. */
+    path: string;
+    /** Name of the newest file. */
+    name: string;
+    /** Unix timestamp of the file's last modification. */
+    timestamp: number;
+}
+/**
+ * Options for directory deletion operations.
+ */
+export interface DeleteOptions {
+    /** If true, simulate deletion without actually removing files. */
+    dryRun?: boolean;
+}
+/**
+ * Result of a directory deletion operation.
+ */
+export interface DeleteResult {
+    /** Path that was attempted to be deleted. */
+    path: string;
+    /** Whether the deletion was successful. */
+    success: boolean;
+    /** Error information if deletion failed. */
+    error?: {
+        /** Human-readable error message. */
+        message: string;
+        /** Error code if available. */
+        code?: string;
+    };
+}

package/lib/core/interfaces/folder.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=folder.interface.js.map

package/lib/core/interfaces/folder.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder.interface.js","sourceRoot":"","sources":["../../../src/core/interfaces/folder.interface.ts"],"names":[],"mappings":""}

package/lib/core/interfaces/index.d.ts

@@ -0,0 +1,6 @@
+export * from './file-service.interface.js';
+export * from './folder.interface.js';
+export * from './services.interface.js';
+export * from './search-status.model.js';
+export * from './devkillrc-config.interface.js';
+export * from './profile.interface.js';

package/lib/core/interfaces/index.js

@@ -0,0 +1,7 @@
+export * from './file-service.interface.js';
+export * from './folder.interface.js';
+export * from './services.interface.js';
+export * from './search-status.model.js';
+export * from './devkillrc-config.interface.js';
+export * from './profile.interface.js';
+//# sourceMappingURL=index.js.map

package/lib/core/interfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/interfaces/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,wBAAwB,CAAC"}

package/lib/core/interfaces/logger-service.interface.d.ts

@@ -0,0 +1,59 @@
+import type { Observable } from 'rxjs';
+/**
+ * Represents an individual entry in the log.
+ */
+export interface LogEntry {
+    type: 'info' | 'warn' | 'error';
+    timestamp: number;
+    message: string;
+}
+/**
+ * Interface for a logging service that allows logging messages
+ * of different types, retrieving them, and saving them to a file.
+ */
+export interface ILoggerService {
+    /**
+     * Logs an info message.
+     * @param message The message to log.
+     */
+    info(message: string): void;
+    /**
+     * Logs a warning message.
+     * @param message The message to log.
+     */
+    warn(message: string): void;
+    /**
+     * Logs an error message.
+     * @param message The message to log.
+     */
+    error(message: string): void;
+    /**
+     * Gets log entries filtered by type.
+     * @param type The type of entries to retrieve ('all', 'info', 'warn', 'error'). Default is 'all'.
+     * @returns An array of log entries.
+     */
+    get(type?: 'all' | 'info' | 'warn' | 'error'): LogEntry[];
+    /**
+     * Gets an Observable that emits the full array of log entries whenever it changes.
+     * @returns An Observable of an array of log entries.
+     */
+    getLog$(): Observable<LogEntry[]>;
+    /**
+     * Gets an Observable that emits log entries filtered by type whenever they change.
+     * @param type The type of entries to retrieve ('all', 'info', 'warn', 'error'). Default is 'all'.
+     * @returns An Observable of an array of log entries.
+     */
+    getLogByType$(type?: 'all' | 'info' | 'warn' | 'error'): Observable<LogEntry[]>;
+    /**
+     * Saves the current log content to a specified file.
+     * Rotates the log file if one with the same name already exists.
+     * @param path The full path of the file where the log will be saved.
+     */
+    saveToFile(path: string): void;
+    /**
+     * Suggests a default file path to save the log,
+     * usually in the system's temporary directory.
+     * @returns The suggested file path.
+     */
+    getSuggestLogFilePath(): string;
+}

package/lib/core/interfaces/logger-service.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=logger-service.interface.js.map

package/lib/core/interfaces/logger-service.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-service.interface.js","sourceRoot":"","sources":["../../../src/core/interfaces/logger-service.interface.ts"],"names":[],"mappings":""}

package/lib/core/interfaces/npkill.interface.d.ts

@@ -0,0 +1,78 @@
+import { Observable } from 'rxjs';
+import { ScanFoundFolder, GetNewestFileResult, GetSizeOptions, GetSizeResult, ScanOptions, DeleteResult, DeleteOptions } from './folder.interface.js';
+import { LogEntry } from '@core/interfaces/logger-service.interface.js';
+export type ProfileFilterType = 'base' | 'user' | 'all';
+/**
+ * Result of validating a root folder path.
+ */
+export interface IsValidRootFolderResult {
+    /** Whether the folder is valid as a root. */
+    isValid: boolean;
+    /** Reason for invalidity, if not valid. */
+    invalidReason?: string;
+}
+/**
+ * Npkill is a powerful search engine that allows you to scan the file system
+ * for specified directories. It also allows you to perform operations on them
+ * in order to clean them up.
+ */
+export interface NpkillInterface {
+    /**
+     * Starts the recursive search from the specified directory.
+     * @param rootPath Root directory to scan from.
+     * @param options Optional scan options.
+     * @returns Observable that emits the results that are found in real time.
+     */
+    startScan$(rootPath: string, options?: ScanOptions): Observable<ScanFoundFolder>;
+    /**
+     * Stops the current scan if any.
+     *
+     * Frees resources and terminates the observable returned by `startScan$`.
+     */
+    stopScan(): void;
+    /**
+     * Returns the total size of the contents of a directory.
+     * @param path Path to the directory.
+     * @param options Optional size options.
+     * @returns Observable that outputs a value with the result of the operation.
+     */
+    getSize$(path: string, options?: GetSizeOptions): Observable<GetSizeResult>;
+    /**
+     * Retrieves the most recently modified file (the one with the latest
+     * modification timestamp) within a given directory and its subdirectories,
+     * recursively.
+     * @param path Path to the directory.
+     * @returns Observable that outputs a value with the result of the
+     * operation. May return null if no files exist or the most recent file
+     * cannot be determined.
+     */
+    getNewestFile$(path: string): Observable<GetNewestFileResult | null>;
+    /**
+     * Deletes the specified directory. For security purposes, this directory
+     * must be contained within the `target` path defined when initiating the scan
+     * with `startScan$` or throw an exception.
+     * @param path Path to delete.
+     * @param options Optional delete options.
+     * @returns Observable emitting the delete result.
+     * @throws Error if the path is not within the target directory.
+     */
+    delete$(path: string, options?: DeleteOptions): Observable<DeleteResult>;
+    /**
+     * Gets the log stream generated by npkill.
+     * @returns Observable emitting an array of log entries.
+     */
+    getLogs$(): Observable<LogEntry[]>;
+    /**
+     * Checks if a given route has problems initiating a scan. Validates that the
+     * path belongs to a directory, that the directory exists and that there are
+     * no permissions issues.
+     * @param path Path to validate.
+     * @returns Result of validation.
+     */
+    isValidRootFolder(path: string): IsValidRootFolderResult;
+    /**
+     * Get the current version of npkill.
+     * @returns Version string defined in npkill's package.json.
+     */
+    getVersion(): string;
+}

package/lib/core/interfaces/npkill.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=npkill.interface.js.map

package/lib/core/interfaces/npkill.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"npkill.interface.js","sourceRoot":"","sources":["../../../src/core/interfaces/npkill.interface.ts"],"names":[],"mappings":""}

package/lib/core/interfaces/npkillrc-config.interface.d.ts

@@ -0,0 +1,87 @@
+import { PROFILE } from './profile.interface.js';
+/**
+ * Represents the structure of .npkillrc configuration file.
+ * All properties are optional as users may only override specific settings.
+ */
+export interface INpkillrcConfig {
+    /**
+     * Absolute path from which the search will begin.
+     * @example "/home/user/my-projects/"
+     */
+    rootDir?: string;
+    /**
+     * Array of directory names to exclude from search.
+     * These directories and their subdirectories will be skipped.
+     * @example [".git", "important-project"]
+     */
+    exclude?: string[];
+    /**
+     * Default sort order for results.
+     * @default "none"
+     */
+    sortBy?: 'none' | 'size' | 'path' | 'age';
+    /**
+     * Unit for displaying folder sizes.
+     * - "auto": Sizes < 1024MB shown in MB, larger sizes in GB
+     * - "mb": Always show in megabytes
+     * - "gb": Always show in gigabytes
+     * @default "auto"
+     */
+    sizeUnit?: 'auto' | 'mb' | 'gb';
+    /**
+     * Exclude sensitive results.
+     * @default false
+     */
+    excludeSensitiveResults?: boolean;
+    /**
+     * Enable dry-run mode by default.
+     * When true, deletions are simulated (nothing is actually deleted).
+     * @default false
+     */
+    dryRun?: boolean;
+    /**
+     * Check for npkill updates on startup.
+     * @default true
+     */
+    checkUpdates?: boolean;
+    /**
+     * Profiles to use.
+     * @example ["node", "python"]
+     * @default ["node"]
+     */
+    defaultProfiles?: string[];
+    /**
+     * Custom profiles with specific target directories.
+     * Profile names can be used with the -p/--profiles flag.
+     * @example
+     * {
+     *   "webdev": {
+     *     "targets": ["node_modules", "dist", ".next"],
+     *     "description": "Web development artifacts"
+     *   },
+     *   "python": {
+     *     "targets": [".venv", "__pycache__"],
+     *     "description": "Python virtual environments and caches"
+     *   }
+     * }
+     */
+    profiles?: Record<string, PROFILE>;
+}
+/**
+ * Result of loading and parsing a .npkillrc configuration file.
+ */
+export interface IConfigLoadResult {
+    /**
+     * The parsed configuration, or null if loading failed.
+     */
+    config: INpkillrcConfig | null;
+    /**
+     * Path to the configuration file that was loaded or attempted to load.
+     */
+    configPath: string;
+    /**
+     * Error message if loading or parsing failed.
+     */
+    error?: string;
+}
+export declare const VALID_NPKILLRC_PROPERTIES: readonly ["rootDir", "exclude", "sortBy", "sizeUnit", "excludeSensitiveResults", "dryRun", "checkUpdates", "defaultProfiles", "profiles"];

package/lib/core/interfaces/npkillrc-config.interface.js

@@ -0,0 +1,12 @@
+export const VALID_NPKILLRC_PROPERTIES = [
+    'rootDir',
+    'exclude',
+    'sortBy',
+    'sizeUnit',
+    'excludeSensitiveResults',
+    'dryRun',
+    'checkUpdates',
+    'defaultProfiles',
+    'profiles',
+];
+//# sourceMappingURL=npkillrc-config.interface.js.map

package/lib/core/interfaces/npkillrc-config.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"npkillrc-config.interface.js","sourceRoot":"","sources":["../../../src/core/interfaces/npkillrc-config.interface.ts"],"names":[],"mappings":"AAmGA,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,SAAS;IACT,SAAS;IACT,QAAQ;IACR,UAAU;IACV,yBAAyB;IACzB,QAAQ;IACR,cAAc;IACd,iBAAiB;IACjB,UAAU;CAC2C,CAAC"}

package/lib/core/interfaces/profile.interface.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents a profile with target directories and description.
+ */
+export interface PROFILE {
+    /** Array of directory names to search for */
+    targets: string[];
+    /** Description of what this profile is for */
+    description: string;
+}

package/lib/core/interfaces/profile.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=profile.interface.js.map

package/lib/core/interfaces/profile.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.interface.js","sourceRoot":"","sources":["../../../src/core/interfaces/profile.interface.ts"],"names":[],"mappings":""}

package/lib/core/interfaces/search-status.model.d.ts

@@ -0,0 +1,35 @@
+import type { WorkerStatus } from '../services/files/files.worker.service.js';
+/**
+ * Tracks the progress and status of directory scanning operations.
+ * Maintains counters for various stages of the scan process including
+ * search tasks, statistics calculation, and deletion operations.
+ */
+export declare class ScanStatus {
+    /** Number of search tasks currently pending execution. */
+    pendingSearchTasks: number;
+    /** Number of search tasks that have been completed. */
+    completedSearchTasks: number;
+    /** Number of pending statistics calculations for found directories. */
+    pendingStatsCalculation: number;
+    /** Number of completed statistics calculations. */
+    completedStatsCalculation: number;
+    /** Total number of matching directories found during the scan. */
+    resultsFound: number;
+    /** Number of deletion operations currently pending. */
+    pendingDeletions: number;
+    /** Current status of the worker threads handling the scan. */
+    workerStatus: WorkerStatus;
+    /** Information about active worker jobs. */
+    workersJobs: any;
+    /**
+     * Records the discovery of a new matching directory.
+     * Increments result count and pending statistics calculation.
+     */
+    newResult(): void;
+    /**
+     * Records the completion of a statistics calculation.
+     * Decrements pending count and increments completed count.
+     */
+    completeStatCalculation(): void;
+    reset(): void;
+}

package/lib/core/interfaces/search-status.model.js

@@ -0,0 +1,48 @@
+/**
+ * Tracks the progress and status of directory scanning operations.
+ * Maintains counters for various stages of the scan process including
+ * search tasks, statistics calculation, and deletion operations.
+ */
+export class ScanStatus {
+    /** Number of search tasks currently pending execution. */
+    pendingSearchTasks = 0;
+    /** Number of search tasks that have been completed. */
+    completedSearchTasks = 0;
+    /** Number of pending statistics calculations for found directories. */
+    pendingStatsCalculation = 0;
+    /** Number of completed statistics calculations. */
+    completedStatsCalculation = 0;
+    /** Total number of matching directories found during the scan. */
+    resultsFound = 0;
+    /** Number of deletion operations currently pending. */
+    pendingDeletions = 0;
+    /** Current status of the worker threads handling the scan. */
+    workerStatus = 'stopped';
+    /** Information about active worker jobs. */
+    workersJobs;
+    /**
+     * Records the discovery of a new matching directory.
+     * Increments result count and pending statistics calculation.
+     */
+    newResult() {
+        this.resultsFound++;
+        this.pendingStatsCalculation++;
+    }
+    /**
+     * Records the completion of a statistics calculation.
+     * Decrements pending count and increments completed count.
+     */
+    completeStatCalculation() {
+        this.pendingStatsCalculation--;
+        this.completedStatsCalculation++;
+    }
+    reset() {
+        this.pendingSearchTasks = 0;
+        this.completedSearchTasks = 0;
+        this.pendingStatsCalculation = 0;
+        this.completedStatsCalculation = 0;
+        this.resultsFound = 0;
+        this.pendingDeletions = 0;
+    }
+}
+//# sourceMappingURL=search-status.model.js.map

package/lib/core/interfaces/search-status.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-status.model.js","sourceRoot":"","sources":["../../../src/core/interfaces/search-status.model.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACrB,0DAA0D;IACnD,kBAAkB,GAAG,CAAC,CAAC;IAC9B,uDAAuD;IAChD,oBAAoB,GAAG,CAAC,CAAC;IAChC,uEAAuE;IAChE,uBAAuB,GAAG,CAAC,CAAC;IACnC,mDAAmD;IAC5C,yBAAyB,GAAG,CAAC,CAAC;IACrC,kEAAkE;IAC3D,YAAY,GAAG,CAAC,CAAC;IACxB,uDAAuD;IAChD,gBAAgB,GAAG,CAAC,CAAC;IAC5B,8DAA8D;IACvD,YAAY,GAAiB,SAAS,CAAC;IAC9C,4CAA4C;IACrC,WAAW,CAAC;IAEnB;;;OAGG;IACH,SAAS;QACP,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,uBAAuB,EAAE,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,uBAAuB;QACrB,IAAI,CAAC,uBAAuB,EAAE,CAAC;QAC/B,IAAI,CAAC,yBAAyB,EAAE,CAAC;IACnC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,oBAAoB,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,uBAAuB,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,yBAAyB,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/lib/core/interfaces/services.interface.d.ts

@@ -0,0 +1,26 @@
+import type { FileService, FileWorkerService } from '@core/services/files/index.js';
+import type { LoggerService } from '@core/services/logger.service.js';
+import type { ProfilesService } from '@core/services/profiles.service.js';
+import type { StreamService } from '@core/services/stream.service.js';
+import type { ResultsService } from '../../cli/services/index.js';
+import type { ScanStatus } from './search-status.model.js';
+/**
+ * Collection of all core services used by npkill.
+ * Provides centralized access to logging, file operations, streaming, and result management.
+ */
+export interface Services {
+    /** Service for logging messages and managing log output. */
+    logger: LoggerService;
+    /** Status tracker for ongoing scan operations. */
+    searchStatus: ScanStatus;
+    /** Service for file system operations and directory management. */
+    fileService: FileService;
+    /** Worker service for background file processing tasks. */
+    fileWorkerService: FileWorkerService;
+    /** Service for managing reactive streams and data flow. */
+    streamService: StreamService;
+    /** Service for managing and formatting scan results. */
+    resultsService: ResultsService;
+    /** Service for managing profiles. */
+    profilesService: ProfilesService;
+}

package/lib/core/interfaces/services.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=services.interface.js.map

package/lib/core/interfaces/services.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.interface.js","sourceRoot":"","sources":["../../../src/core/interfaces/services.interface.ts"],"names":[],"mappings":""}

package/lib/core/npkill.d.ts

@@ -0,0 +1,25 @@
+import { Observable } from 'rxjs';
+import { LoggerService } from './services/logger.service.js';
+import { Services } from './interfaces/services.interface.js';
+import { ScanFoundFolder, GetNewestFileResult, GetSizeResult, ScanOptions, DeleteOptions, DeleteResult } from './interfaces/folder.interface.js';
+import { IsValidRootFolderResult, NpkillInterface } from './interfaces/npkill.interface.js';
+import { LogEntry } from './interfaces/logger-service.interface.js';
+/**
+ * Main npkill class that implements the core directory scanning and cleanup functionality.
+ * Provides methods for recursive directory scanning, size calculation, file analysis,
+ * and safe deletion operations.
+ */
+export declare class Npkill implements NpkillInterface {
+    private readonly services;
+    constructor(customServices?: Partial<Services>);
+    private searchDuration;
+    startScan$(rootPath: string, options: ScanOptions): Observable<ScanFoundFolder>;
+    getSize$(path: string): Observable<GetSizeResult>;
+    getNewestFile$(path: string): Observable<GetNewestFileResult | null>;
+    delete$(path: string, options?: DeleteOptions): Observable<DeleteResult>;
+    getLogs$(): Observable<LogEntry[]>;
+    stopScan(): void;
+    isValidRootFolder(path: string): IsValidRootFolderResult;
+    getVersion(): string;
+    get logger(): LoggerService;
+}