depshred 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+- Interactive prompt to automatically execute `npm uninstall <pkg>` for confirmed removals.
+- Generation of `depshred-migration.md` summary reports.
+- Lockfile parsing (`package-lock.json`, `pnpm-lock.yaml`) to detect phantom dependencies.
+- Official GitHub Action (`depshred/action`) for automated pull request checks.
+- AST-powered automated code import rewriting.
+
+## [1.0.0] - 2026-10-09
+
+### Added
+- Universal dependency auditing scanning 100% of declared packages in `package.json`.
+- Native Node.js standard library replacement detection for Node 18, 20, and 22+ built-ins (`dotenv`, `uuid`, `rimraf`, `mkdirp`, `nodemon`, `axios`, `glob`, `querystring`).
+- Unused dependency detection mapping 0-import packages with copy-ready `npm uninstall` commands.
+- `package.json` script command scanning to prevent false-positive unused warnings on CLI tools.
+- Smart dormancy checking (>3 years) distinguishing self-contained zero-dependency modules from rotting software.
+- Live npm registry metadata harvesting (unpacked size, transitive dependency counts, dormancy, deprecations).
+- Zero-clutter metadata caching in OS temporary directory (`os.tmpdir()`) with 24-hour TTL.
+- CLI execution modes: default interactive terminal explorer, `--check` CI exit code mode, `--strict`, and structured `--json` output.
+- `--init-skill` command to automatically install agent vetting skills into Cursor, Copilot, Windsurf, Claude Code, Cline, and universal workspaces.
+- Multi-IDE pre-flight vetting skill catalog in `skills/` and root `SKILLS.md`.
+- Near-zero external dependencies architecture using Node.js standard library APIs and `picocolors`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 depshred 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,201 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gozajpeg/depshred/master/assets/depshred.webp" width="200" alt="depshred logo">
+</p>
 
-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.
+<h1 align="center">depshred</h1>
+
+<p align="center">
+  <em>Clean up your node_modules. Stop installing stuff Node already has.</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/run_with-npx_depshred-111111?style=flat-square" alt="Run with npx">
+  <img src="https://img.shields.io/badge/node.js-18%2B_%7C_20%2B_%7C_22%2B-111111?style=flat-square" alt="Node Support">
+  <img src="https://img.shields.io/badge/version-1.0.1-111111?style=flat-square" alt="version 1.0.0">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
+</p>
+
+---
+
+Ever look at your `node_modules` folder and wonder why it takes up half your hard drive?
+
+When you follow tutorials or ask AI to write code, it is super easy to end up with 30 different packages installed for things modern Node can already do by itself. Stuff like `dotenv`, `uuid`, or `rimraf` do not need to be in your project anymore. Node already knows how to do all of that.
+
+`depshred` looks through your project, finds packages you do not actually need, and shows you how to swap them for simple code that comes with Node.
+
+---
+
+## Quick start
+
+You do not even need to install anything first. Just open your terminal inside your project folder and run:
+
+```bash
+npx depshred
+```
+
+If your project lives in another folder, just tell it where:
+
+```bash
+npx depshred ./path/to/your-project
+```
+
+Using pnpm or bun instead of npm? That works too:
+
+```bash
+pnpm dlx depshred
+bunx depshred
+```
+
+---
+
+## What it looks like
+
+Here is what you see when you run it in your terminal:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gozajpeg/depshred/master/assets/view01.webp" width="100%" alt="depshred terminal interface">
+</p>
+
+You get an easy list you can move through with your arrow keys:
+
+```text
++--------------------------------------------------------------------------+
+| depshred v1.0.1 (Node v20.12.0)                                          |
+| Target: ./my-project                                                     |
++--------------------------------------------------------------------------+
+| Total Scanned: 24 dependencies                                           |
+|                                                                          |
+| [CRITICAL] 2 packages have native Node.js replacements (saves ~182 KB)   |
+| [UNUSED]   1 package has 0 imports (run: npm uninstall rimraf)           |
+| [WARN]     1 package is dormant >3y (0 sub-deps, self-contained)         |
+| [OK]       20 packages are lean and actively maintained                  |
++--------------------------------------------------------------------------+
+
+Select a dependency to inspect (Use arrow keys, Enter to inspect):
+  > [CRITICAL] dotenv    Native Node.js built-in available (saves ~72 KB)
+    [CRITICAL] uuid      Native Node.js built-in available (saves ~110 KB)
+    [UNUSED]   rimraf    0 imports found in project source code
+    [WARN]     ms        Dormant >3 years | 0 sub-dependencies (self-contained)
+    [OK]       fastify   Active, schema-compiled and lean
+```
+
+---
+
+## What it checks for
+
+When you run `depshred`, it checks three main things:
+
+1. **Stuff Node already has built in**
+Do you really need `dotenv` when Node can load `.env` files on its own? Do you need `uuid` when Node has `crypto.randomUUID()`? `depshred` finds every file and exact line number where you use these, and shows you the quick built-in way to replace them.
+
+2. **Packages you installed but never use**
+Ever ran `npm install` for a test or a guide, forgot about it, and left it sitting in your `package.json`? `depshred` scans your whole project. If you never imported it anywhere, it tells you straight up: `npm uninstall <package>`.
+
+3. **Old or abandoned packages**
+It checks npm to see how big each package is and whether anyone has touched it in the last 3 years. If a package is small, has zero other packages inside it, and just works, `depshred` lets you know so you do not have to worry.
+
+```text
+                    Your package.json
+                            |
+         +------------------+------------------+
+         |                  |                  |
+         v                  v                  v
+ 1. Already in Node?   2. Used in code?   3. npm check
+ (dotenv, uuid, etc.)  (0 imports found)  (file size, age)
+         |                  |                  |
+         v                  v                  v
+ Use Node built-ins      Safe to delete    Good to know
+ (saves disk space)     (npm uninstall)   (see how big it is)
+```
+
+---
+
+## Extra options
+
+Need to run it inside a script or change how it works? Here are the flags you can use:
+
+| Flag | What it does |
+| :--- | :--- |
+| `--check` | Checks your project and stops with an error if it finds bad or useless packages. Great for GitHub Actions. |
+| `--strict` | Like `--check`, but also stops on small warnings. |
+| `--json` | Prints results as JSON so you can read them with code. |
+| `--no-interactive` | Skips the arrow-key menu and just prints a plain table. |
+| `--path <folder>` | Checks a different folder instead of where you are right now. |
+| `--dormant-years <num>` | How many years without updates before calling a package old (defaults to 3). |
+| `--ignore <names>` | Comma-separated names of packages you want to skip. |
+| `--init-skill [app]` | Adds instructions to your AI editor so it stops installing packages you do not need. |
+| `--help`, `-h` | Shows all available flags. |
+| `--version`, `-v` | Shows the version number. |
+
+---
+
+## Teach your AI editor to stop installing junk
+
+If you use AI coding tools like Cursor, Claude, Windsurf, or GitHub Copilot, you have probably seen them run `npm install` for every single little thing. Most of the time, Node already has what they are trying to download.
+
+You can teach your AI helper to check first before installing:
+
+```bash
+# Pick your editor from a menu:
+npx depshred --init-skill
+
+# Or pick your editor directly:
+npx depshred --init-skill cursor       # For Cursor (.cursor/rules)
+npx depshred --init-skill copilot      # For GitHub Copilot (.github)
+npx depshred --init-skill windsurf     # For Windsurf (.windsurf/rules)
+npx depshred --init-skill claude       # For Claude Code (CLAUDE.md)
+npx depshred --init-skill cline        # For Cline (.clinerules)
+npx depshred --init-skill antigravity  # For Antigravity (.agents/skills)
+npx depshred --init-skill agents       # For general agents (AGENTS.md)
+npx depshred --init-skill all          # Sets up all of them at once
+```
+
+Want to see all the skill files and how they work? Check out [SKILLS.md](SKILLS.md).
+
+---
+
+## Save your settings
+
+If there is a package you want `depshred` to leave alone, you can save your preferences right inside your `package.json`:
+
+```json
+{
+  "depshred": {
+    "ignore": ["fast-deep-equal"],
+    "dormantYears": 4
+  }
+}
+```
+
+---
+
+## What projects work with it?
+
+Pretty much any modern Node.js project:
+
+- **Any framework:** Express, Fastify, Next.js, NestJS, Koa, or plain Node scripts.
+- **Any module style:** Both `import` (ES Modules) and `require` (CommonJS).
+- **JavaScript and TypeScript:** `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs`.
+- **Projects with multiple folders:** Works with monorepos using the `--path` flag.
+
+---
+
+## Questions you might have
+
+**Does it change my code automatically?**  
+No. `depshred` never touches your code behind your back. It shows you the file, the line number, and the built-in Node replacement. You decide what to change and when.
+
+**Does it need a database or send my code to some server?**  
+No. Everything runs right on your computer. It only talks to the public npm website to check package sizes and update dates. It saves that info in your computer's temporary folder for a day so it stays fast.
+
+**What if an old package works fine and does not need updates?**  
+Not every old package is broken. Some small tools are simply finished and do not need changes. `depshred` checks if the package has zero sub-packages. If it is small and self-contained, it gives you a soft heads-up, not a red error. You can also add it to your ignore list.
+
+**Does it work with Python or Go?**  
+No, this is built only for Node.js and npm projects.
+
+---
+
+## License
+
+[MIT](LICENSE).

package/SKILLS.md

@@ -0,0 +1,74 @@
+# depshred: Universal Agent Skill Catalog & Pre-Flight Vetting
+
+`depshred` provides a standardized dependency hygiene skill for AI coding agents and human developers. It enforces pre-flight vetting to prevent unnecessary `npm install` operations when Node.js natively handles the requested functionality.
+
+---
+
+## The Mandatory 4-Step Pre-Flight Vetting Order
+
+When tasked with adding functionality to a Node.js project, an agent MUST NOT blindly run `npm install <package>`. Follow this order:
+
+### Step 0: The Native Standard Library Check (Zero Packages)
+
+Before reaching for npm, verify if modern Node.js already includes this functionality natively:
+
+| Wanted Functionality | DO NOT Install | USE INSTEAD (Node Standard Library) | Minimum Node |
+| :--- | :--- | :--- | :--- |
+| Environment variables | `dotenv` | Native CLI flag `node --env-file=.env` | Node 20.6.0+ |
+| UUID generation | `uuid` | `crypto.randomUUID()` from `node:crypto` | Node 15.6.0+ |
+| Recursive folder deletion | `rimraf` | `fs.rmSync(path, { recursive: true, force: true })` | Node 14.14.0+ |
+| Recursive directory creation | `mkdirp` | `fs.mkdirSync(path, { recursive: true })` | Node 10.12.0+ |
+| Development file watching | `nodemon` | `node --watch server.js` | Node 18.11.0+ |
+| HTTP requests | `axios`, `node-fetch` | Native global `fetch()` | Node 18.0.0+ |
+| File glob matching | `glob` | `fs.globSync(pattern)` from `node:fs` | Node 22.0.0+ |
+| URL query parameters | `querystring` | `URLSearchParams` / `new URL()` | Node 10.0.0+ |
+
+If the target Node version supports the native feature, **do not install any package**. Write the native implementation directly.
+
+---
+
+### Step 1: The Existing Codebase & Unused Dependency Check
+
+Before adding any package, inspect what is already in the project:
+1. **Check for Unused Packages:** Grep `package.json` against project imports. If dead, unimported dependencies exist, flag them for cleanup rather than adding more clutter.
+2. **Reuse Existing Dependencies:** If a library is already installed (e.g. `fastify`, utility libraries), leverage its built-in modules instead of adding a competing package.
+3. **Check Internal Utilities:** Check `src/utils/` or shared helpers. Never add an external dependency for logic that already exists in the codebase.
+
+---
+
+### Step 2: Vetting New Dependencies (When an install is truly necessary)
+
+If no native API or existing helper exists, vet the candidate package before running install:
+1. **Check Maintenance & Dormancy:**
+   - Avoid packages that have not published updates in >3 years, unless they are confirmed feature-complete, zero-dependency modules (e.g. self-contained parsers).
+   - Check for official npm deprecation warnings.
+2. **Check Transitive Dependency Fan-out:** Prefer zero-dependency or single-purpose packages over monolithic bundles that pull in dozens of nested sub-dependencies.
+3. **Prefer Modern Lightweight Equivalents:**
+   - Date manipulation: Use native `Intl.DateTimeFormat`, `date-fns`, or `dayjs` over legacy `moment`.
+   - Terminal styling: Use `picocolors` (sub-7KB, zero dependencies) over heavy `chalk` chains.
+   - Utility helpers: Use native ES6+ methods (`map`, `filter`, `structuredClone`) or `es-toolkit` over monolithic `lodash`.
+   - Password hashing: Prefer native `crypto.scrypt` or pure JS `bcryptjs` over packages requiring node-gyp C++ compilation unless explicitly required for performance.
+
+---
+
+### Step 3: Post-Change Verification
+
+After adding or removing dependencies:
+1. Verify `package.json` and lockfile are clean and committed.
+2. Run project tests or `node --check` to ensure no broken imports remain.
+3. If `depshred` is available, run `npx depshred --check` to verify that no new dependency bloat or unused packages were introduced.
+
+---
+
+## Multi-IDE & Agent Export Formats
+
+For IDE-specific and agent-native configurations, use the tailored rule files located in the [`skills/`](skills/) folder:
+
+| IDE / Agent | Configuration File | Target Path in User Project |
+| :--- | :--- | :--- |
+| **Cursor** | [`skills/cursor/depshred.mdc`](skills/cursor/depshred.mdc) | `.cursor/rules/depshred.mdc` |
+| **GitHub Copilot** | [`skills/copilot/copilot-instructions.md`](skills/copilot/copilot-instructions.md) | `.github/copilot-instructions.md` |
+| **Windsurf (Codeium)** | [`skills/windsurf/depshred.md`](skills/windsurf/depshred.md) | `.windsurf/rules/depshred.md` or `.windsurfrules` |
+| **Claude Code** | [`skills/claude/CLAUDE.md`](skills/claude/CLAUDE.md) | `CLAUDE.md` |
+| **Cline / Roo Code** | [`skills/cline/.clinerules`](skills/cline/.clinerules) | `.clinerules` |
+| **Universal / Antigravity** | [`skills/depshred/SKILL.md`](skills/depshred/SKILL.md) | `.agents/skills/depshred/SKILL.md` |

package/bin/depshred.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "depshred",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Shred dependency bloat. Embrace modern Node.",
+  "type": "module",
+  "main": "./src/cli.js",
+  "bin": {
+    "depshred": "bin/depshred.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "SKILLS.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node ./bin/depshred.js",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "dependencies",
+    "audit",
+    "bloat",
+    "unused-dependencies",
+    "cli",
+    "e18e",
+    "nodejs",
+    "npm"
+  ],
+  "author": "gozajpeg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gozajpeg/depshred.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gozajpeg/depshred/issues"
+  },
+  "homepage": "https://github.com/gozajpeg/depshred#readme",
+  "dependencies": {
+    "picocolors": "^1.1.1"
+  }
+}

package/skills/README.md

@@ -0,0 +1,22 @@
+# depshred Agent Skills & IDE Rules Catalog
+
+This directory contains pre-configured dependency hygiene and pre-flight vetting instructions formatted for all major AI coding agents and IDEs.
+
+## Supported IDEs & Agents
+
+| IDE / Agent | Configuration File | Native Location |
+| :--- | :--- | :--- |
+| **Cursor** | `skills/cursor/depshred.mdc` | `.cursor/rules/depshred.mdc` |
+| **GitHub Copilot / VS Code** | `skills/copilot/copilot-instructions.md` | `.github/copilot-instructions.md` |
+| **Windsurf (Codeium)** | `skills/windsurf/depshred.md` | `.windsurf/rules/depshred.md` or `.windsurfrules` |
+| **Claude Code (Anthropic)** | `skills/claude/CLAUDE.md` | `CLAUDE.md` |
+| **Cline / Roo Code** | `skills/cline/.clinerules` | `.clinerules` |
+| **Universal / Antigravity** | `skills/depshred/SKILL.md` | `.agents/skills/depshred/SKILL.md` |
+
+## How It Works
+
+Each configuration prevents AI agents from blindly executing `npm install <package>` by enforcing a mandatory 4-step pre-flight check:
+1. **Step 0:** Native Node.js standard library check (zero external packages).
+2. **Step 1:** Existing codebase and unused dependency inspection.
+3. **Step 2:** Vetting new dependencies (avoiding dormancy >3 years, checking sub-dependencies, preferring lightweight alternatives).
+4. **Step 3:** Post-change verification (`depshred --check`).

package/skills/agents/AGENTS.md

@@ -0,0 +1,57 @@
+# depshred: AI Coding Agent Operating Instructions
+
+This file instructs AI coding agents (Claude, Cursor, Copilot, Antigravity, OpenHands, Devin) on how to work on and maintain the `depshred` codebase.
+
+---
+
+## 1. Architecture & Design Principles
+
+* **Pure Node.js ES Modules:** `"type": "module"`. No CommonJS, no Babel, no TypeScript compilation step.
+* **Zero Build Step:** Code in `src/` runs directly in Node.js.
+* **Near-Zero External Dependencies:** Only `picocolors` is allowed in `dependencies`. Never add external dependencies for tasks that the Node.js standard library handles.
+* **Standard Library First:**
+  * CLI options: `node:util.parseArgs`
+  * File walking & reading: `node:fs` / `node:fs/promises`
+  * Path resolution: `node:path`
+  * OS temporary caching: `node:os` (`tmpdir()`)
+  * UUID & hashing: `node:crypto`
+  * Networking: Native global `fetch()`
+  * Testing: Native `node:test` (`node --test`)
+* **Zero Emojis:** Strictly zero emojis across all code, terminal output, and documentation files.
+
+---
+
+## 2. Essential Commands
+
+* **Run CLI locally:** `node ./bin/depshred.js`
+* **Run Self-Audit:** `node ./bin/depshred.js --check`
+* **Run Test Suite:** `npm test` or `node --test test/*.test.js`
+* **Test Fixtures:** `node ./bin/depshred.js ./test/fixtures/legacy-app --check`
+
+---
+
+## 3. Mandatory Pre-Flight Dependency Vetting Order
+
+When asked to add functionality to this or any Node.js project, NEVER blindly run `npm install <package>`. Follow this 4-step order:
+
+### Step 0: The Native Standard Library Check
+Before reaching for npm, verify if modern Node.js already includes this natively:
+- `dotenv` -> Native CLI flag `node --env-file=.env` (Node 20.6.0+)
+- `uuid` -> Native `crypto.randomUUID()` (Node 15.6.0+)
+- `rimraf` -> Native `fs.rmSync(path, { recursive: true, force: true })` (Node 14.14.0+)
+- `mkdirp` -> Native `fs.mkdirSync(path, { recursive: true })` (Node 10.12.0+)
+- `nodemon` -> Native file watcher `node --watch server.js` (Node 18.11.0+)
+- `axios` / `node-fetch` -> Native global `fetch()` (Node 18.0.0+)
+- `glob` -> Native `fs.globSync(pattern)` (Node 22.0.0+)
+- `querystring` -> Native `URLSearchParams` / `new URL()` (Node 10.0.0+)
+
+### Step 1: Existing Codebase Check
+Check `package.json` and internal utilities in `src/` before adding any new package.
+
+### Step 2: Vetting New Dependencies
+- Avoid packages with no updates in >3 years unless confirmed zero-dependency, feature-complete modules.
+- Prefer lightweight alternatives (`picocolors` over `chalk`, `dayjs` over `moment`).
+
+### Step 3: Post-Change Verification
+- Run tests: `npm test`.
+- Verify clean audit: `node ./bin/depshred.js --check`.

package/skills/antigravity/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: depshred
+description: Pre-installation dependency hygiene and vetting for Node.js. Forces agents to check for native Node.js standard library built-ins, existing project utilities, and lightweight alternatives before running npm install or yarn/pnpm add.
+---
+
+# depshred: Agent Dependency Hygiene & Pre-Flight Vetting
+
+When an agent is tasked with adding functionality to a Node.js project, it MUST NOT blindly run `npm install <package>`. Follow this mandatory 4-step pre-flight vetting order:
+
+---
+
+## Step 0: The Native Standard Library Check (Zero Packages)
+
+Before reaching for npm, verify if modern Node.js already includes this functionality natively:
+
+| Wanted Functionality | DO NOT Install | USE INSTEAD (Node Standard Library) | Minimum Node |
+| :--- | :--- | :--- | :--- |
+| Environment variables | `dotenv` | Native CLI flag `node --env-file=.env` | Node 20.6.0+ |
+| UUID generation | `uuid` | `crypto.randomUUID()` from `node:crypto` | Node 15.6.0+ |
+| Recursive folder deletion | `rimraf` | `fs.rmSync(path, { recursive: true, force: true })` | Node 14.14.0+ |
+| Recursive directory creation | `mkdirp` | `fs.mkdirSync(path, { recursive: true })` | Node 10.12.0+ |
+| Development file watching | `nodemon` | `node --watch server.js` | Node 18.11.0+ |
+| HTTP requests | `axios`, `node-fetch` | Native global `fetch()` | Node 18.0.0+ |
+| File glob matching | `glob` | `fs.globSync(pattern)` from `node:fs` | Node 22.0.0+ |
+| URL query parameters | `querystring` | `URLSearchParams` / `new URL()` | Node 10.0.0+ |
+
+If the target Node version supports the native feature, **do not install any package**. Write the native implementation directly.
+
+---
+
+## Step 1: The Existing Codebase & Unused Dependency Check
+
+Before adding any package, inspect what is already in the project:
+1. **Check for Unused Packages:** Grep `package.json` against project imports. If dead, unimported dependencies exist, note them for cleanup rather than adding more clutter.
+2. **Reuse Existing Dependencies:** If a library is already installed (e.g. `fastify`, utility libraries), leverage its built-in modules instead of adding a competing package.
+3. **Check Internal Utilities:** Check `src/utils/` or shared helpers. Never add an external dependency for logic that already exists in the codebase.
+
+---
+
+## Step 2: Vetting New Dependencies (When an install is truly necessary)
+
+If no native API or existing helper exists, vet the candidate package before running install:
+1. **Check Maintenance & Dormancy:**
+   - Avoid packages that have not published updates in >3 years, unless they are confirmed feature-complete, zero-dependency modules (e.g. self-contained parsers).
+   - Check for official npm deprecation warnings.
+2. **Check Transitive Dependency Fan-out:** Prefer zero-dependency or single-purpose packages over monolithic bundles that pull in dozens of nested sub-dependencies.
+3. **Prefer Modern Lightweight Equivalents:**
+   - Date manipulation: Use native `Intl.DateTimeFormat`, `date-fns`, or `dayjs` over legacy `moment`.
+   - Terminal styling: Use `picocolors` (sub-7KB, zero dependencies) over heavy `chalk` chains.
+   - Utility helpers: Use native ES6+ methods (`map`, `filter`, `structuredClone`) or `es-toolkit` over monolithic `lodash`.
+   - Password hashing: Prefer native `crypto.scrypt` or pure JS `bcryptjs` over packages requiring node-gyp C++ compilation unless explicitly required for performance.
+
+---
+
+## Step 3: Post-Change Verification
+
+After adding or removing dependencies:
+1. Verify `package.json` and lockfile are clean and committed.
+2. Run project tests or `node --check` to ensure no broken imports remain.
+3. If `depshred` is available, run `npx depshred --check` to verify that no new dependency bloat or unused packages were introduced.

package/skills/claude/CLAUDE.md

@@ -0,0 +1,55 @@
+# depshred: Agent Dependency Hygiene & Pre-Flight Vetting
+
+When an agent is tasked with adding functionality to a Node.js project, it MUST NOT blindly run `npm install <package>`. Follow this mandatory 4-step pre-flight vetting order:
+
+---
+
+## Step 0: The Native Standard Library Check (Zero Packages)
+
+Before reaching for npm, verify if modern Node.js already includes this functionality natively:
+
+| Wanted Functionality | DO NOT Install | USE INSTEAD (Node Standard Library) | Minimum Node |
+| :--- | :--- | :--- | :--- |
+| Environment variables | `dotenv` | Native CLI flag `node --env-file=.env` | Node 20.6.0+ |
+| UUID generation | `uuid` | `crypto.randomUUID()` from `node:crypto` | Node 15.6.0+ |
+| Recursive folder deletion | `rimraf` | `fs.rmSync(path, { recursive: true, force: true })` | Node 14.14.0+ |
+| Recursive directory creation | `mkdirp` | `fs.mkdirSync(path, { recursive: true })` | Node 10.12.0+ |
+| Development file watching | `nodemon` | `node --watch server.js` | Node 18.11.0+ |
+| HTTP requests | `axios`, `node-fetch` | Native global `fetch()` | Node 18.0.0+ |
+| File glob matching | `glob` | `fs.globSync(pattern)` from `node:fs` | Node 22.0.0+ |
+| URL query parameters | `querystring` | `URLSearchParams` / `new URL()` | Node 10.0.0+ |
+
+If the target Node version supports the native feature, **do not install any package**. Write the native implementation directly.
+
+---
+
+## Step 1: The Existing Codebase & Unused Dependency Check
+
+Before adding any package, inspect what is already in the project:
+1. **Check for Unused Packages:** Grep `package.json` against project imports. If dead, unimported dependencies exist, note them for cleanup rather than adding more clutter.
+2. **Reuse Existing Dependencies:** If a library is already installed (e.g. `fastify`, utility libraries), leverage its built-in modules instead of adding a competing package.
+3. **Check Internal Utilities:** Check `src/utils/` or shared helpers. Never add an external dependency for logic that already exists in the codebase.
+
+---
+
+## Step 2: Vetting New Dependencies (When an install is truly necessary)
+
+If no native API or existing helper exists, vet the candidate package before running install:
+1. **Check Maintenance & Dormancy:**
+   - Avoid packages that have not published updates in >3 years, unless they are confirmed feature-complete, zero-dependency modules (e.g. self-contained parsers).
+   - Check for official npm deprecation warnings.
+2. **Check Transitive Dependency Fan-out:** Prefer zero-dependency or single-purpose packages over monolithic bundles that pull in dozens of nested sub-dependencies.
+3. **Prefer Modern Lightweight Equivalents:**
+   - Date manipulation: Use native `Intl.DateTimeFormat`, `date-fns`, or `dayjs` over legacy `moment`.
+   - Terminal styling: Use `picocolors` (sub-7KB, zero dependencies) over heavy `chalk` chains.
+   - Utility helpers: Use native ES6+ methods (`map`, `filter`, `structuredClone`) or `es-toolkit` over monolithic `lodash`.
+   - Password hashing: Prefer native `crypto.scrypt` or pure JS `bcryptjs` over packages requiring node-gyp C++ compilation unless explicitly required for performance.
+
+---
+
+## Step 3: Post-Change Verification
+
+After adding or removing dependencies:
+1. Verify `package.json` and lockfile are clean and committed.
+2. Run project tests or `node --check` to ensure no broken imports remain.
+3. If `depshred` is available, run `npx depshred --check` to verify that no new dependency bloat or unused packages were introduced.

package/skills/cline/.clinerules

@@ -0,0 +1,55 @@
+# depshred: Agent Dependency Hygiene & Pre-Flight Vetting
+
+When an agent is tasked with adding functionality to a Node.js project, it MUST NOT blindly run `npm install <package>`. Follow this mandatory 4-step pre-flight vetting order:
+
+---
+
+## Step 0: The Native Standard Library Check (Zero Packages)
+
+Before reaching for npm, verify if modern Node.js already includes this functionality natively:
+
+| Wanted Functionality | DO NOT Install | USE INSTEAD (Node Standard Library) | Minimum Node |
+| :--- | :--- | :--- | :--- |
+| Environment variables | `dotenv` | Native CLI flag `node --env-file=.env` | Node 20.6.0+ |
+| UUID generation | `uuid` | `crypto.randomUUID()` from `node:crypto` | Node 15.6.0+ |
+| Recursive folder deletion | `rimraf` | `fs.rmSync(path, { recursive: true, force: true })` | Node 14.14.0+ |
+| Recursive directory creation | `mkdirp` | `fs.mkdirSync(path, { recursive: true })` | Node 10.12.0+ |
+| Development file watching | `nodemon` | `node --watch server.js` | Node 18.11.0+ |
+| HTTP requests | `axios`, `node-fetch` | Native global `fetch()` | Node 18.0.0+ |
+| File glob matching | `glob` | `fs.globSync(pattern)` from `node:fs` | Node 22.0.0+ |
+| URL query parameters | `querystring` | `URLSearchParams` / `new URL()` | Node 10.0.0+ |
+
+If the target Node version supports the native feature, **do not install any package**. Write the native implementation directly.
+
+---
+
+## Step 1: The Existing Codebase & Unused Dependency Check
+
+Before adding any package, inspect what is already in the project:
+1. **Check for Unused Packages:** Grep `package.json` against project imports. If dead, unimported dependencies exist, note them for cleanup rather than adding more clutter.
+2. **Reuse Existing Dependencies:** If a library is already installed (e.g. `fastify`, utility libraries), leverage its built-in modules instead of adding a competing package.
+3. **Check Internal Utilities:** Check `src/utils/` or shared helpers. Never add an external dependency for logic that already exists in the codebase.
+
+---
+
+## Step 2: Vetting New Dependencies (When an install is truly necessary)
+
+If no native API or existing helper exists, vet the candidate package before running install:
+1. **Check Maintenance & Dormancy:**
+   - Avoid packages that have not published updates in >3 years, unless they are confirmed feature-complete, zero-dependency modules (e.g. self-contained parsers).
+   - Check for official npm deprecation warnings.
+2. **Check Transitive Dependency Fan-out:** Prefer zero-dependency or single-purpose packages over monolithic bundles that pull in dozens of nested sub-dependencies.
+3. **Prefer Modern Lightweight Equivalents:**
+   - Date manipulation: Use native `Intl.DateTimeFormat`, `date-fns`, or `dayjs` over legacy `moment`.
+   - Terminal styling: Use `picocolors` (sub-7KB, zero dependencies) over heavy `chalk` chains.
+   - Utility helpers: Use native ES6+ methods (`map`, `filter`, `structuredClone`) or `es-toolkit` over monolithic `lodash`.
+   - Password hashing: Prefer native `crypto.scrypt` or pure JS `bcryptjs` over packages requiring node-gyp C++ compilation unless explicitly required for performance.
+
+---
+
+## Step 3: Post-Change Verification
+
+After adding or removing dependencies:
+1. Verify `package.json` and lockfile are clean and committed.
+2. Run project tests or `node --check` to ensure no broken imports remain.
+3. If `depshred` is available, run `npx depshred --check` to verify that no new dependency bloat or unused packages were introduced.