{"id":46274466,"url":"https://github.com/hbisneto/nodemodulescleaner","last_synced_at":"2026-03-07T07:01:04.085Z","repository":{"id":341310369,"uuid":"1169651660","full_name":"hbisneto/NodeModulesCleaner","owner":"hbisneto","description":"Automatic cleanup of forgotten node_modules directories.","archived":false,"fork":false,"pushed_at":"2026-03-04T04:23:53.000Z","size":47,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T06:32:40.461Z","etag":null,"topics":["automation","cleanup","cli","directory-management","disk-space","filesystem","modules","node","python-tool"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/nodemodulescleaner/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hbisneto.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T02:00:06.000Z","updated_at":"2026-03-04T04:23:56.000Z","dependencies_parsed_at":"2026-03-05T05:00:37.659Z","dependency_job_id":null,"html_url":"https://github.com/hbisneto/NodeModulesCleaner","commit_stats":null,"previous_names":["hbisneto/nodemodulescleaner"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hbisneto/NodeModulesCleaner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hbisneto%2FNodeModulesCleaner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hbisneto%2FNodeModulesCleaner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hbisneto%2FNodeModulesCleaner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hbisneto%2FNodeModulesCleaner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hbisneto","download_url":"https://codeload.github.com/hbisneto/NodeModulesCleaner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hbisneto%2FNodeModulesCleaner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30111702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T03:40:26.266Z","status":"ssl_error","status_checked_at":"2026-03-05T03:39:15.902Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cleanup","cli","directory-management","disk-space","filesystem","modules","node","python-tool"],"created_at":"2026-03-04T04:03:30.502Z","updated_at":"2026-03-05T05:01:00.905Z","avatar_url":"https://github.com/hbisneto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NodeModulesCleaner (nmc)\n\n![CI](https://github.com/hbisneto/NodeModulesCleaner/actions/workflows/tests.yml/badge.svg)\n![License](https://img.shields.io/github/license/hbisneto/NodeModulesCleaner)\n\n[![PyPI](https://img.shields.io/pypi/v/NodeModulesCleaner?logo=python\u0026logoColor=white\u0026color=blue)](https://pypi.org/project/nodemodulescleaner/)\n[![Python](https://img.shields.io/badge/Python-%3E=3.10-blue)](https://python.org/)\n\n![Issues](https://img.shields.io/github/issues/hbisneto/NodeModulesCleaner)\n![Stars](https://img.shields.io/github/stars/hbisneto/NodeModulesCleaner?style=social)\n\n[![codecov](https://codecov.io/github/hbisneto/NodeModulesCleaner/graph/badge.svg?token=TPY9K1INYE)](https://codecov.io/github/hbisneto/NodeModulesCleaner)\n\n\n\u003e Automatic cleanup of forgotten `node_modules` directories.\n\n**NodeModulesCleaner** is a fast, safe, and practical CLI tool that helps you free up disk space by detecting and removing old and unused `node_modules` folders from your system.\n\nIt recursively scans your filesystem, identifies abandoned `node_modules` directories based on access time and size, and optionally deletes them — safely and efficiently.\n\n---\n\n## ✨ Features\n\n* 🔍 Recursive directory scanning\n* 🕒 Filter by last access time (`--days`)\n* 📦 Filter by minimum directory size (`--min-size`)\n* 🔎 Dry-run mode (preview before deleting)\n* 🤖 Non-interactive automation mode (`--yes`)\n* ⚡ Very fast (no heavy indexing or hashing)\n* 🧪 Fully testable architecture (core separated from CLI)\n* 🧩 Clean, maintainable and extensible design\n\n---\n\n## 📦 Why does this exist?\n\nJavaScript projects often accumulate **hundreds of megabytes or even gigabytes** inside `node_modules`.\n\nOver time, many of these folders become **abandoned**, consuming large amounts of disk space and slowing down backups, indexing, and file searches.\n\nThis tool helps you:\n\n* Clean forgotten dependencies\n* Reclaim disk space\n* Keep your development environment tidy\n* Automate periodic cleanup (cron jobs, CI pipelines, scripts)\n\n---\n\n## 🚀 Installation\n\n### Using pip (recommended)\n\n```bash\npip install nodemodulescleaner\n```\n\n---\n\n## ⚡ Quick Usage\n\nScan your home directory:\n\n```bash\nnmc ~\n```\n\nPreview what would be deleted:\n\n```bash\nnmc ~ --dry-run\n```\n\nDelete folders not accessed in the last 30 days and larger than 200 MB:\n\n```bash\nnmc ~ --days 30 --min-size 200\n```\n\nFully automated cleanup (no confirmation prompt):\n\n```bash\nnmc ~ --days 60 --min-size 100 -y\n```\n\n---\n\n## ⚙️ CLI Options\n\n```text\nusage: nmc [path] [options]\n\npositional arguments:\n  path                Directory to scan (default: current directory)\n\noptions:\n  --days N            Ignore node_modules accessed within the last N days (default: 30)\n  --min-size MB       Minimum size in MB (default: 0)\n  --dry-run           Simulate the cleanup without deleting anything\n  -y, --yes           Automatically confirm deletion (non-interactive mode)\n```\n\n---\n\n## 🛡️ Safety First\n\nBefore deleting anything, the tool:\n\n* Lists all matching directories\n* Shows total recoverable disk space\n* Requires explicit confirmation (unless `-y` is used)\n\nAlways test first:\n\n```bash\nnmc \u003cpath\u003e --dry-run\n```\n\n---\n\n# 🧑‍💻 Developer Guide (Dev)\n\nThis section is for contributors and developers who want to **run, test, or extend** the project.\n\n---\n\n## 📁 Project Structure\n\n```text\nnmc/\n ├── core.py     # Business logic (scan + filters + cleanup)\n ├── cli.py      # CLI interface (argparse + UX)\n └── __init__.py\n```\n\nThis separation ensures:\n\n* High testability\n* Clean architecture\n* Easy extensibility\n* Stable CLI behavior\n\n---\n\n## 🔧 Local Development Setup\n\n### 1️⃣ Clone the repository\n\n```bash\ngit clone https://github.com/hbisneto/NodeModulesCleaner.git\ncd NodeModulesCleaner\n```\n\n---\n\n### 2️⃣ Create a virtual environment\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n---\n\n### 3️⃣ Install in editable mode\n\n```bash\npip install -e .\n```\n\nThis allows immediate reflection of local code changes.\n\n---\n\n## ▶ Running Locally\n\n```bash\nnmc ~/projects --dry-run\n```\n\nor:\n\n```bash\npython -m nmc.cli ~/projects --dry-run\n```\n\n---\n\n## 🧪 Running Tests\n\n```bash\npytest -v\n```\n\nThe architecture guarantees:\n\n* No interactive input during tests\n* No filesystem pollution\n* Fully deterministic execution\n\n---\n\n## 🏗 Architecture Overview\n\n### Core Logic → `nmc/core.py`\n\nHandles:\n\n* Directory scanning\n* Filtering logic\n* Cleanup execution\n\nNo user interaction. No printing.\n\n---\n\n### CLI Interface → `nmc/cli.py`\n\nHandles:\n\n* Argument parsing\n* User prompts\n* Output formatting\n* UX flow\n\nThis separation enables:\n\n* Stable CI pipelines\n* Easy automation\n* Reliable testing\n* Low bug surface\n\n---\n\n## 🤝 Contributing\n\nContributions are very welcome!\n\nIf you'd like to help improve **NodeModulesCleaner**, please check out the open issues on GitHub:\n\n👉 https://github.com/hbisneto/NodeModulesCleaner/issues\n\nThere you will find:\n\n- 🐛 Bug reports\n- 🚀 Feature requests\n- 🧩 Planned enhancements\n- 🏗 Architecture improvements\n- 🧪 Testing and CI ideas\n\nIf you have a new idea, feel free to open a new issue or start a discussion.\n\nEvery contribution — from code to documentation, testing, or ideas — is highly appreciated! ❤️\n\n---\n\n## 📜 License\n\nMIT License — feel free to use, modify, and distribute.\n\n---\n\n## ⭐ Support\n\nIf this tool helped you, please leave a ⭐ on GitHub — it really helps!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhbisneto%2Fnodemodulescleaner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhbisneto%2Fnodemodulescleaner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhbisneto%2Fnodemodulescleaner/lists"}