@hunchoweb/nclean 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nclean contributors
+
+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

@@ -1,3 +1,245 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# nclean
+
+**Node modules cleanup, without the drama.**
+
+Find forgotten dependencies. Reclaim their space. Keep your projects.
+
+[Quick start](#quick-start) · [Commands](#commands) · [Safety](#safety) · [Development](#development)
+
+</div>
+
+```text
+                       __
+    ____     _____    / /      ____     ____     ____
+   / __ \   / ___/   / /      / __ \   / __ |   / __ \
+  / / / /  / /__    / /__    / ____/  / /_/ /  / / / /
+  /_/ /_/  \____/   \___/    \___/    \__,_/   /_/ /_/
+```
+
+Old side projects, finished client work, abandoned experiments: each can leave thousands of dependency files behind. **nclean finds `node_modules`, shows what they cost, and lets you choose what to remove.** Your source, manifests, lockfiles, and Git history stay in place.
+
+Built with TypeScript for Node.js 22+ · macOS / Linux / Windows · MIT
+
+## Quick start
+
+Install with npm (Node.js 22 or newer):
+
+```sh
+npm install --global @hunchoweb/nclean
+```
+
+Then go to a project or the directory that holds your projects:
+
+```sh
+cd ~/Code
+nclean
+```
+
+**No path required.** nclean scans the directory you ran it from, including nested projects. A path overrides that default:
+
+```sh
+nclean ~/Projects
+nclean ~/Code ~/Work
+```
+
+Update to the latest release:
+
+```sh
+npm install --global @hunchoweb/nclean
+```
+
+To build from source or contribute, follow [Development](#development).
+
+## The experience
+
+1. Discover projects in the current directory.
+2. Measure dependencies with a live progress bar.
+3. Select folders in a bordered, keyboard-driven list.
+4. Review the selection and confirm with **Yes**.
+5. See the measured space reclaimed and commands to restore dependencies.
+
+Illustrative terminal excerpt; counts and sizes depend on your projects:
+
+```text
+$ nclean --older-than 30
+
+  Scanning ~/Code...
+
+  █████████████████████░░░░░░░░░░░  66%
+
+  4/6 dependency folders measured
+
+  7 projects scanned
+  6 dependency folders found
+  4 inactive projects
+
+  4.0 MB reclaimable
+
+  Select dependencies to remove
+
+  ┌───────────────────────────────────────────────────────────────┐
+  │     Project                      Size   Inactive   PM         │
+  ├───────────────────────────────────────────────────────────────┤
+  │ › ● monorepo/apps/web          1.0 MB        70d   npm        │
+  │   ● shelf                      1.0 MB        47d   pnpm       │
+  │   ○ old-client                 1.0 MB        3mo   npm        │
+  │   ○ design-system              1.0 MB        60d   yarn       │
+  └───────────────────────────────────────────────────────────────┘
+
+  2 selected · 2.0 MB
+
+  [space] select     [a] all     [enter] clean     [esc] cancel
+```
+
+Use ↑/↓ to navigate. **Nothing is preselected.** Enter opens the final review; it does not immediately delete your selection. Confirmation defaults to **No**. Choose `y`, then press Enter to approve, or press Esc to cancel.
+
+During discovery, the bar moves without a percentage because the total is still unknown. Once discovery finishes, the percentage reflects completed dependency-folder measurements. Narrow terminals shorten paths and hide secondary columns.
+
+## Commands
+
+```sh
+nclean                              # Select dependencies in the current directory
+nclean scan                         # Report sizes and activity; never delete
+nclean --dry-run                    # Preview eligible folders without prompts
+nclean --older-than 30              # Show projects inactive for at least 30 days
+nclean clean --older-than 30        # Review and confirm cleanup of all matches
+nclean clean --older-than 30 --yes  # Explicitly authorize unattended cleanup
+nclean --verbose                    # Include detailed scan warnings
+nclean --help                       # Show usage and examples
+nclean --version                    # Show the installed version
+```
+
+Every scan or cleanup command accepts optional paths:
+
+```sh
+nclean scan ~/Projects
+nclean ~/Code ~/Work --older-than 60
+nclean clean ./archive --older-than 90 --dry-run
+nclean clean ./archive --older-than 90 --yes
+```
+
+| Option | Behavior |
+| --- | --- |
+| `--older-than <days>` | Include projects inactive for at least that many whole days. |
+| `--dry-run` | Preview only. No deletion, even with `--yes`. |
+| `--verbose` | Show full scan diagnostics and unreadable paths. |
+| `-y, --yes` | Skip confirmation on the explicit `clean` command only. |
+
+Options work before or after a subcommand. With no age filter, all known ages are eligible. In a noninteractive shell, the default command prints a report and deletes nothing; `clean` requires explicit `--yes` or a terminal confirmation.
+
+### Choose your scan scope
+
+The current working directory is the scan root. Run `nclean` inside one project to inspect that project and its workspaces; run it from `~/Code` to inspect projects beneath that directory. Running it from your home directory scans your home directory.
+
+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.
+
+### Partial scans
+
+Protected or unreadable folders are skipped, with a compact notice:
+
+```text
+  Partial scan · 12 folders skipped (12 access denied).
+  Use --verbose for details. Accessible projects are still shown.
+```
+
+Use `nclean scan --verbose` for the detailed paths. A partial scan does not claim your whole directory is clean. Unknown activity or unreadable size excludes a dependency folder from cleanup.
+
+## How inactivity works
+
+A project contains a regular `package.json`. nclean estimates its last activity using the **newest** of:
+
+- The latest Git commit affecting the project, when Git is available.
+- Manifest and lockfile modification times.
+- Relevant source and configuration modification times, including JS, TS, Vue, Svelte, Astro, styles, Markdown, JSON, YAML, and Prisma files.
+
+Dependency timestamps do not determine inactivity. Generated directories such as `dist`, `build`, `.next`, and `coverage`, along with `.git` internals, are excluded. Nested workspace projects are inspected separately; a parent's Git history can conservatively keep that parent active.
+
+This is an estimate. A fresh checkout may look active, while simply opening or reading a project does not update its activity. When activity cannot be read reliably, nclean marks it **unknown** and skips cleanup.
+
+## Restore dependencies
+
+Run the detected package manager's install command in the project directory. nclean groups the restore instructions after cleanup.
+
+| Lockfile | Restore command |
+| --- | --- |
+| `package-lock.json` / `npm-shrinkwrap.json` | `npm install` |
+| `pnpm-lock.yaml` | `pnpm install` |
+| `yarn.lock` | `yarn install` |
+| `bun.lock` / `bun.lockb` | `bun install` |
+| No lockfile | `npm install` |
+
+For a workspace, install at the workspace root when your package manager requires it. If multiple lockfiles exist, detection prefers pnpm, yarn, bun, then npm.
+
+## Safety
+
+**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.
+- `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.
+- Unreadable or unknown entries are excluded. Removal failures are reported while other selected entries continue.
+- Dependencies inside an already discovered `node_modules` are counted within that tree rather than reported again.
+
+A normal project can reinstall dependencies from its manifest and lockfile. **Local edits or manually placed files inside `node_modules` may not be recoverable.** Without a lockfile, reinstalling may resolve different versions.
+
+Sizes are logical file bytes. Symlinks are skipped and hard links count once per dependency directory. Successful removals are measured again before deletion; failed or partial removals do not contribute to the success total. Physical free space can differ because of shared hard links, compression, allocation, sparse files, and snapshots.
+
+Avoid installing dependencies or replacing directories during cleanup. Portable Node APIs cannot make path checks and recursive removal atomic against concurrent directory replacement.
+
+Exit code `1` indicates scan warnings, invalid input, or cleanup failures. Normal reports, empty results, dry runs, and declined confirmation return `0`.
+
+## Development
+
+```sh
+npm install
+npm run dev -- --dry-run
+npm run build
+npm link
+npm test
+npm run lint
+```
+
+The source is strict TypeScript and ESM. Directory listings are streamed; up to four projects are measured concurrently. Git checks have a timeout. `lint` performs TypeScript checking; tests use isolated temporary directories to exercise discovery, activity, sizing, paths, symlinks, cleanup, prompts, progress, and diagnostics.
+
+### Record a demo
+
+```sh
+npm run build
+npm run demo:setup
+```
+
+The script creates fake projects in a fresh temporary directory, with npm, pnpm, yarn, bun, a nested project, and different activity ages. Each fake dependency folder contains 1 MB. Copy the printed directory, then:
+
+```sh
+cd <printed-directory>
+nclean --older-than 30
+```
+
+If you have not run `npm link`, use the absolute path to `dist/cli.js`. Run `npm run demo:setup` again for a fresh fixture after cleanup.
+
+### Contribute
+
+Keep changes focused on Node.js dependency cleanup. For bugs, include a reproduction or temporary-directory test. Run the build, tests, and type check before opening a pull request. Cross-platform testing reports are welcome.
+
+### Publish
+
+Maintainers publish `@hunchoweb/nclean` as a public package to the npm registry. The executable remains `nclean`. Sign in with an npm account that has publishing access:
+
+```sh
+npm login --registry=https://registry.npmjs.org/
+npm whoami
+npm view @hunchoweb/nclean name version
+npm pack --dry-run
+npm publish --access public
+```
+
+An `E404` from the name lookup means no public package was found; npm decides whether the name can be claimed when publishing. Publishing runs the tests and type check, and packing builds automatically. Complete npm's authentication and two-factor prompts when requested.
+
+The package includes compiled `dist/` files, the README, the MIT license, and package metadata. Runtime dependencies are installed by npm; users do not need TypeScript or a repository checkout. Test the packed tarball in an isolated install before releasing. For subsequent releases, bump the package version and CLI version together; npm does not allow reusing a published version.
+
+## License
+
+[MIT](LICENSE) © nclean contributors

package/dist/cleanup/remove.d.ts

@@ -0,0 +1,2 @@
+import type { Candidate } from '../types.js';
+export declare function removeCandidate(entry: Candidate, dryRun?: boolean): Promise<number>;

package/dist/cleanup/remove.js

@@ -0,0 +1,26 @@
+import { lstat, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { assertRealPath } from '../utils/paths.js';
+import { directorySize } from '../scanner/size.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.');
+    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);
+    const manifest = await lstat(path.join(entry.project, 'package.json'));
+    if (!manifest.isFile() || manifest.isSymbolicLink())
+        throw new Error('Project manifest is missing or changed.');
+    const stat = await lstat(entry.path);
+    if (stat.dev !== entry.device || stat.ino !== entry.inode)
+        throw new Error('node_modules changed since scanning; scan again.');
+    if (dryRun)
+        return 0;
+    const measured = await directorySize(entry.path);
+    await assertRealPath(entry.root, entry.path);
+    const latest = await lstat(entry.path);
+    if (latest.dev !== entry.device || latest.ino !== entry.inode)
+        throw new Error('node_modules changed before cleanup.');
+    await rm(entry.path, { recursive: true, force: false, maxRetries: 2 });
+    return measured;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError } from 'commander';
+import { scan } from './commands/scan.js';
+import { clean } from './commands/clean.js';
+import { banner, table, message } from './ui/output.js';
+import { errorMessage, terminalText } from './utils/format.js';
+function days(value) {
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+        throw new InvalidArgumentError('Use a non-negative whole number of days, e.g. 30.');
+    return Number(value);
+}
+const program = new Command();
+program.configureHelp({ showGlobalOptions: true });
+program.name('nclean').description('Clean up forgotten Node.js dependencies.').version('0.1.0')
+    .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')
+    .option('--verbose', 'Show detailed scan warnings and unreadable paths')
+    .addHelpText('after', `\nExamples:\n  nclean                             Select dependencies in the current directory\n  nclean ~/Projects ~/Code           Scan specific directories\n  nclean --dry-run --older-than 30    Preview old dependencies\n  nclean scan ~/Projects             Report only\n  nclean clean ~/Projects --older-than 30\n  nclean clean ~/Projects --older-than 30 --yes\n\nWithout paths, scans the current directory and nested projects.\nIncludes all ages unless --older-than is set; nothing is preselected.\nCleanup always requires confirmation unless clean --yes is explicit.\nSizes are file bytes, not a guarantee of physical free disk space.\n`)
+    .action(async (paths, options) => {
+    banner();
+    const result = await scan(paths, options);
+    if (result.entries.length)
+        await clean(result.entries, options, true);
+});
+program.command('scan').description('Find dependencies and report their sizes without deleting')
+    .argument('[paths...]', 'Directories to scan (default: current directory)')
+    .action(async (paths, _options, command) => {
+    banner();
+    const result = await scan(paths, command.optsWithGlobals());
+    if (result.entries.length)
+        table(result.entries);
+});
+program.command('clean').description('Print matching directories and confirm bulk deletion')
+    .argument('[paths...]', 'Directories to scan (default: current directory)')
+    .option('-y, --yes', 'Explicitly authorize deletion without a prompt')
+    .action(async (paths, _options, command) => {
+    banner();
+    const options = command.optsWithGlobals();
+    const result = await scan(paths, options);
+    if (result.entries.length)
+        await clean(result.entries, options, false);
+});
+try {
+    await program.parseAsync();
+}
+catch (error) {
+    const name = error instanceof Error ? error.name : '';
+    if (['ExitPromptError', 'AbortPromptError', 'AbortError'].includes(name))
+        message('CANCELLED', 'Nothing further was deleted.');
+    else {
+        console.error(`Error: ${terminalText(errorMessage(error))}`);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/clean.d.ts

@@ -0,0 +1,2 @@
+import type { Candidate, Options } from '../types.js';
+export declare function clean(entries: Candidate[], options: Options, interactiveSelection: boolean): Promise<void>;

package/dist/commands/clean.js

@@ -0,0 +1,67 @@
+import { removeCandidate } from '../cleanup/remove.js';
+import { plan, restores, table, message, note, cleanupComplete, deletionFailure } from '../ui/output.js';
+import { selectEntries, confirmCleanup, isInteractive } from '../ui/interactive.js';
+import { errorMessage } from '../utils/format.js';
+import { startCleanupProgress } from '../ui/progress.js';
+export async function clean(entries, options, interactiveSelection) {
+    const eligible = entries.filter(entry => entry.bytes !== null && entry.lastActive !== null && !entry.error);
+    const skipped = entries.length - eligible.length;
+    if (skipped)
+        note(`Skipping ${skipped} directories with unknown activity or unreadable size.`);
+    if (options.dryRun) {
+        table(entries);
+        message('DRY RUN', `${eligible.length} eligible ${eligible.length === 1 ? 'directory' : 'directories'}. Nothing was deleted.`);
+        return;
+    }
+    if (!eligible.length) {
+        message('NOTHING TO CLEAN', 'No directories eligible for cleanup.');
+        return;
+    }
+    if (interactiveSelection && !isInteractive()) {
+        table(entries);
+        note('Selection requires an interactive terminal. Nothing was deleted.');
+        note('For scripts: nclean clean <path> --older-than 30 --yes');
+        console.log();
+        return;
+    }
+    const selected = interactiveSelection ? await selectEntries(eligible) : eligible;
+    if (!selected.length) {
+        message('CANCELLED', 'Nothing selected. Nothing was deleted.');
+        return;
+    }
+    plan(selected);
+    // --yes is only honored by the explicit clean command.
+    if (!options.yes || interactiveSelection) {
+        if (!isInteractive())
+            throw new Error('Confirmation requires an interactive terminal. Review with --dry-run, or explicitly use clean --yes. Nothing was deleted.');
+        if (!await confirmCleanup()) {
+            message('CANCELLED', 'Nothing was deleted.');
+            return;
+        }
+    }
+    const removed = [];
+    const failures = [];
+    let bytes = 0;
+    const progress = startCleanupProgress(selected.length);
+    try {
+        for (const entry of selected) {
+            try {
+                bytes += await removeCandidate(entry);
+                removed.push(entry);
+            }
+            catch (error) {
+                process.exitCode = 1;
+                failures.push({ entry, reason: errorMessage(error) });
+            }
+            progress.update(removed.length + failures.length, failures.length);
+        }
+    }
+    finally {
+        progress.stop();
+    }
+    cleanupComplete(removed, bytes, failures.length);
+    for (const failure of failures)
+        deletionFailure(failure.entry, selected, failure.reason);
+    if (removed.length)
+        restores(removed);
+}

package/dist/commands/scan.d.ts

@@ -0,0 +1,2 @@
+import type { Options, ScanResult } from '../types.js';
+export declare function scan(inputs: string[], options: Options): Promise<ScanResult>;

package/dist/commands/scan.js

@@ -0,0 +1,44 @@
+import { scanRoots } from '../utils/paths.js';
+import { discover } from '../scanner/discover.js';
+import { oldEnough } from '../utils/format.js';
+import { scanning, scanComplete, message, note } from '../ui/output.js';
+import { startScanProgress } from '../ui/progress.js';
+import { scanDiagnostics } from '../ui/diagnostics.js';
+export async function scan(inputs, options) {
+    const roots = await scanRoots(inputs);
+    scanning(roots);
+    const progress = startScanProgress();
+    let result;
+    try {
+        result = await discover(roots, (_message, state) => progress.update(state));
+    }
+    finally {
+        progress.stop();
+    }
+    const folderCount = result.entries.length;
+    const diagnostics = scanDiagnostics(result.warnings, result.entries, options.verbose);
+    if (diagnostics) {
+        console.error(diagnostics);
+        process.exitCode = 1;
+    }
+    if (options.olderThan !== undefined) {
+        const unknown = result.entries.filter(entry => entry.lastActive === null).length;
+        result.entries = result.entries.filter(entry => oldEnough(entry.lastActive, options.olderThan));
+        if (unknown)
+            note(`Skipped ${unknown} ${unknown === 1 ? 'directory' : 'directories'} with unknown activity.`);
+    }
+    scanComplete(result.projects, folderCount, result.entries, options.olderThan !== undefined);
+    if (!result.projects && result.warnings.length)
+        message('SCAN INCOMPLETE', 'No Node.js projects found in the accessible folders.', 'Try a specific project directory: nclean ~/Projects');
+    else if (!result.projects)
+        message('NO NODE PROJECTS FOUND', "We couldn't find any package.json files here.", 'Try: nclean ~/Projects');
+    else if (!folderCount && result.warnings.length)
+        message('SCAN INCOMPLETE', 'No dependency folders found in the accessible projects.', 'Skipped folders could not be checked.');
+    else if (!folderCount)
+        message('ALL CLEAN', 'No node_modules directories found.\nNothing to remove.');
+    else if (!result.entries.length && result.warnings.length)
+        message('NO MATCHES IN SCANNED FOLDERS', 'No inactive node_modules found in the accessible projects.', 'Skipped folders could not be checked.');
+    else if (!result.entries.length)
+        message('ALL CLEAN', 'No inactive node_modules found.\nNothing to remove.', 'Tip: try --older-than 7 to find recently inactive projects.');
+    return result;
+}

package/dist/scanner/activity.d.ts

@@ -0,0 +1,2 @@
+export declare const ignored: Set<string>;
+export declare function lastActivity(project: string): Promise<number | null>;

package/dist/scanner/activity.js

@@ -0,0 +1,51 @@
+import { opendir, lstat } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+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;
+export async function lastActivity(project) {
+    let newest = null;
+    const record = (stamp) => { newest = Math.max(newest ?? 0, stamp); };
+    try {
+        const { stdout } = await exec('git', ['-C', project, 'log', '-1', '--format=%ct', '--', '.'], { timeout: 3000, maxBuffer: 4096, windowsHide: true });
+        const stamp = Number(stdout.trim()) * 1000;
+        if (stdout.trim() && Number.isFinite(stamp) && stamp > 0)
+            record(stamp);
+    }
+    catch { /* Git is optional; filesystem signals remain usable. */ }
+    let reliable = true;
+    async function walk(folder) {
+        for await (const entry of await opendir(folder)) {
+            if (entry.isSymbolicLink() || ignored.has(entry.name))
+                continue;
+            const target = path.join(folder, entry.name);
+            if (entry.isDirectory()) {
+                // Nested projects have their own activity signals.
+                try {
+                    if ((await lstat(path.join(target, 'package.json'))).isFile())
+                        continue;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                await walk(target);
+            }
+            else if (entry.isFile() && (relevant.test(entry.name) || /^(?:yarn\.lock|bun\.lockb?|npm-shrinkwrap\.json)$/.test(entry.name))) {
+                const stat = await lstat(target);
+                if (stat.isFile())
+                    record(stat.mtimeMs);
+            }
+        }
+    }
+    try {
+        await walk(project);
+    }
+    catch {
+        reliable = false;
+    }
+    // Incomplete signals must never make a project appear safely inactive.
+    return reliable ? newest : null;
+}

package/dist/scanner/discover.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult, ScanProgress } from '../types.js';
+export declare function discover(roots: string[], progress?: (message: string, state: ScanProgress) => void): Promise<ScanResult>;

package/dist/scanner/discover.js

@@ -0,0 +1,65 @@
+import { opendir, lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { detectManager } from '../utils/package-manager.js';
+import { errorMessage } from '../utils/format.js';
+import { ignored, lastActivity } from './activity.js';
+import { directorySize } from './size.js';
+export async function discover(roots, progress = () => { }) {
+    const result = { projects: 0, entries: [], warnings: [] };
+    async function walk(folder, root) {
+        try {
+            let isProject = false;
+            try {
+                isProject = (await lstat(path.join(folder, 'package.json'))).isFile();
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (isProject) {
+                result.projects++;
+                try {
+                    const modules = path.join(folder, 'node_modules');
+                    const stat = await lstat(modules);
+                    if (stat.isSymbolicLink())
+                        result.warnings.push(`Skipped symlink: ${modules}`);
+                    else if (stat.isDirectory())
+                        result.entries.push({ project: folder, path: modules, root, manager: 'npm', lastActive: null, bytes: null, device: stat.dev, inode: stat.ino, error: null });
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+            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))
+                    await walk(path.join(folder, entry.name), root);
+            }
+        }
+        catch (error) {
+            result.warnings.push(`${folder}: ${errorMessage(error)}`);
+        }
+    }
+    for (const root of roots)
+        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() {
+        while (next < result.entries.length) {
+            const entry = result.entries[next++];
+            try {
+                entry.manager = await detectManager(entry.project);
+                entry.lastActive = await lastActivity(entry.project);
+                entry.bytes = await directorySize(entry.path);
+            }
+            catch (error) {
+                entry.error = errorMessage(error);
+            }
+            progress(`Measuring dependencies · ${++complete}/${result.entries.length}`, { phase: 'measurement', projects: result.projects, folders: result.entries.length, completed: complete, total: result.entries.length });
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(4, result.entries.length) }, worker));
+    result.entries.sort((a, b) => (b.bytes ?? -1) - (a.bytes ?? -1));
+    return result;
+}

package/dist/scanner/size.d.ts

@@ -0,0 +1 @@
+export declare function directorySize(directory: string): Promise<number>;

package/dist/scanner/size.js

@@ -0,0 +1,29 @@
+import { opendir, lstat } from 'node:fs/promises';
+import path from 'node:path';
+// One streamed walk per worker. Links are measured as links, never followed.
+export async function directorySize(directory) {
+    let bytes = 0;
+    const seen = new Set();
+    async function walk(folder) {
+        for await (const entry of await opendir(folder)) {
+            const target = path.join(folder, entry.name);
+            const stat = await lstat(target);
+            if (stat.isSymbolicLink())
+                continue;
+            if (stat.isDirectory())
+                await walk(target);
+            else if (stat.isFile()) {
+                const key = `${stat.dev}:${stat.ino}`;
+                if (stat.ino !== 0 && seen.has(key))
+                    continue;
+                seen.add(key);
+                bytes += stat.size;
+            }
+        }
+    }
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('Expected a real directory.');
+    await walk(directory);
+    return bytes;
+}