@hunchoweb/nclean 0.1.0 → 0.1.1

package/README.md

@@ -135,6 +135,21 @@ The current working directory is the scan root. Run `nclean` inside one project
 
 Explicit paths can be absolute, relative, or home-relative (`~`). Overlapping roots are deduplicated. Filesystem roots and paths inside `node_modules` are rejected. Symlinked scan roots are rejected.
 
+### Projects, not installed tools
+
+The exclusions below are included in **0.1.1 and newer**. Users of 0.1.0 should update before scanning broad directories:
+
+```sh
+npm install --global @hunchoweb/nclean@latest
+nclean --version
+```
+
+nclean excludes hidden directories (including `.vscode`, `.cursor`, `.npm`, `.nvm`, `.cranq`, and generated `.next` folders), application bundles, operating-system application/data directories such as `Library` and `AppData`, and generated trees such as `dist`, `build`, `coverage`, and `vendor`. These exclusions apply to the full directory path, including ancestors of an explicitly selected scan root, and are checked again before deletion. `--yes` does not override them.
+
+A source project for a VS Code extension can still be cleaned when it lives in an ordinary project directory. An installed copy beneath `.vscode/extensions` cannot. Projects stored in hidden or excluded directories are intentionally ineligible; move source projects to an ordinary project directory to use nclean.
+
+A `package.json` identifies a Node.js package, but cannot prove it is a project you personally worked on. These exclusions protect known tool locations; custom installations in ordinary folders may still look like projects. Review the selection and scope scans to your source directories, such as `~/Code` or `~/Projects`.
+
 ### Partial scans
 
 Protected or unreadable folders are skipped, with a compact notice:
@@ -177,6 +192,7 @@ For a workspace, install at the workspace root when your package manager require
 **Cleanup removes only discovered, real `project/node_modules` directories.** Project folders, source, manifests, lockfiles, and `.git` are preserved.
 
 - Interactive cleanup always requires final confirmation, defaulting to No.
+- Hidden folders, installed-tool locations, app bundles, and generated trees are excluded, including when selected directly or with `--yes`.
 - `scan` and `--dry-run` never delete anything.
 - Scanning and sizing never follow symlinks or Windows directory junctions.
 - Root containment, parent directories, manifest, and directory identity are checked again before deletion.

package/dist/cleanup/remove.js

@@ -2,9 +2,11 @@ import { lstat, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { assertRealPath } from '../utils/paths.js';
 import { directorySize } from '../scanner/size.js';
+import { assertProjectScope } from '../utils/project-scope.js';
 export async function removeCandidate(entry, dryRun = false) {
     if (path.basename(entry.path) !== 'node_modules' || path.dirname(entry.path) !== entry.project)
         throw new Error('Refusing to remove anything except project/node_modules.');
+    assertProjectScope(entry.project);
     if (entry.bytes === null || entry.error || entry.lastActive === null)
         throw new Error('Size or activity is unknown; refusing cleanup.');
     await assertRealPath(entry.root, entry.path);
@@ -21,6 +23,7 @@ export async function removeCandidate(entry, dryRun = false) {
     const latest = await lstat(entry.path);
     if (latest.dev !== entry.device || latest.ino !== entry.inode)
         throw new Error('node_modules changed before cleanup.');
+    assertProjectScope(entry.project);
     await rm(entry.path, { recursive: true, force: false, maxRetries: 2 });
     return measured;
 }

package/dist/cli.js

@@ -11,7 +11,7 @@ function days(value) {
 }
 const program = new Command();
 program.configureHelp({ showGlobalOptions: true });
-program.name('nclean').description('Clean up forgotten Node.js dependencies.').version('0.1.0')
+program.name('nclean').description('Clean up forgotten Node.js dependencies.').version('0.1.1')
     .argument('[paths...]', 'Directories to scan (default: current directory)')
     .option('--older-than <days>', 'Only include projects inactive for at least this many days', days)
     .option('--dry-run', 'Preview candidates; never delete anything')

package/dist/scanner/activity.js

@@ -2,6 +2,7 @@ import { opendir, lstat } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import path from 'node:path';
+import { projectScopeReason } from '../utils/project-scope.js';
 const exec = promisify(execFile);
 export const ignored = new Set(['node_modules', '.git', '.next', '.nuxt', '.cache', '.turbo', 'dist', 'build', 'coverage', 'vendor']);
 const relevant = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|json|ya?ml|toml|html|css|scss|md|graphql|prisma)$/i;
@@ -22,6 +23,8 @@ export async function lastActivity(project) {
                 continue;
             const target = path.join(folder, entry.name);
             if (entry.isDirectory()) {
+                if (projectScopeReason(target))
+                    continue;
                 // Nested projects have their own activity signals.
                 try {
                     if ((await lstat(path.join(target, 'package.json'))).isFile())

package/dist/scanner/discover.js

@@ -4,6 +4,7 @@ import { detectManager } from '../utils/package-manager.js';
 import { errorMessage } from '../utils/format.js';
 import { ignored, lastActivity } from './activity.js';
 import { directorySize } from './size.js';
+import { assertProjectScope, projectScopeReason } from '../utils/project-scope.js';
 export async function discover(roots, progress = () => { }) {
     const result = { projects: 0, entries: [], warnings: [] };
     async function walk(folder, root) {
@@ -33,7 +34,7 @@ export async function discover(roots, progress = () => { }) {
             }
             progress(`Discovering projects · ${result.projects} found`, { phase: 'discovery', projects: result.projects, folders: result.entries.length, completed: 0, total: null });
             for await (const entry of await opendir(folder)) {
-                if (entry.isDirectory() && !entry.isSymbolicLink() && !ignored.has(entry.name))
+                if (entry.isDirectory() && !entry.isSymbolicLink() && !ignored.has(entry.name) && !projectScopeReason(path.join(folder, entry.name)))
                     await walk(path.join(folder, entry.name), root);
             }
         }
@@ -41,8 +42,10 @@ export async function discover(roots, progress = () => { }) {
             result.warnings.push(`${folder}: ${errorMessage(error)}`);
         }
     }
-    for (const root of roots)
+    for (const root of roots) {
+        assertProjectScope(root);
         await walk(root, root);
+    }
     let next = 0, complete = 0;
     progress('Measuring dependencies', { phase: 'measurement', projects: result.projects, folders: result.entries.length, completed: 0, total: result.entries.length });
     async function worker() {

package/dist/utils/paths.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { lstat, realpath } from 'node:fs/promises';
 import { terminalText } from './format.js';
+import { assertProjectScope } from './project-scope.js';
 export function expandPath(input) {
     if (input === '~')
         return os.homedir();
@@ -27,6 +28,7 @@ export async function scanRoots(inputs) {
             throw new Error('Scanning the filesystem root is not supported. Choose a project directory.');
         if (canonical.split(path.sep).includes('node_modules'))
             throw new Error('Choose a project directory, not a directory inside node_modules.');
+        assertProjectScope(canonical);
         roots.push(canonical);
     }
     return [...new Set(roots)].filter(root => !roots.some(other => other !== root && within(other, root)));

package/dist/utils/project-scope.d.ts

@@ -0,0 +1,2 @@
+export declare function projectScopeReason(folder: string): string | null;
+export declare function assertProjectScope(folder: string): void;

package/dist/utils/project-scope.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+// Apply to the full path so choosing a protected subdirectory explicitly
+// cannot bypass the same exclusions used during recursive discovery.
+const generated = new Set(['node_modules', 'dist', 'build', 'coverage', 'vendor']);
+const managed = new Set(['library', 'applications', 'appdata', 'program files', 'program files (x86)', 'programdata', 'windows']);
+const systemRoots = ['/usr', '/opt', '/System', '/Applications', '/Library'];
+export function projectScopeReason(folder) {
+    const absolute = path.resolve(folder);
+    if (process.platform !== 'win32' && systemRoots.some(root => absolute === root || absolute.startsWith(`${root}/`))) {
+        return 'system or installed-software directory';
+    }
+    for (const part of absolute.split(path.sep).filter(Boolean)) {
+        if (part.startsWith('.'))
+            return 'hidden or tool-managed directory';
+        if (generated.has(part.toLowerCase()))
+            return 'dependency or generated directory';
+        if (managed.has(part.toLowerCase()) || /\.(?:app|framework|bundle)$/i.test(part))
+            return 'application or tool-managed directory';
+    }
+    return null;
+}
+export function assertProjectScope(folder) {
+    const reason = projectScopeReason(folder);
+    if (reason)
+        throw new Error(`Refusing project cleanup in a ${reason}. Choose a source project directory.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunchoweb/nclean",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Clean up forgotten Node.js dependencies.",
   "type": "module",
   "bin": {