@lowdep/dot-clean 1.0.0

package/LICENSE

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

@@ -0,0 +1,97 @@
+# dot-clean
+
+![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen) ![Node](https://img.shields.io/badge/node-%3E%3D14-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+
+
+Remove `.DS_Store`, `Thumbs.db`, `desktop.ini`, and other OS-generated junk files recursively. Optionally update `.gitignore` to prevent them coming back. Zero dependencies.
+
+---
+
+## Install
+
+```bash
+npm install -g dot-clean
+```
+
+Or without installing:
+
+```bash
+npx dot-clean
+```
+
+---
+
+## Usage
+
+```bash
+dot-clean                      # Remove macOS/Windows/Linux junk in current dir
+dot-clean ~/Documents          # Clean a specific directory
+dot-clean --dry-run            # Preview without deleting
+dot-clean --all                # Remove all categories (incl. IDE/editor files)
+dot-clean --type macos         # Only macOS junk
+dot-clean --gitignore          # Also update .gitignore
+```
+
+---
+
+## Example Output
+
+```
+dot-clean  /my-project
+  Scanning for: macos, windows, linux...
+
+  ✗ screenshots/.DS_Store       4.1 kB
+  ✗ screenshots/.DS_Store       4.1 kB
+  ✗ backup/Thumbs.db            8.0 kB
+  ✗ old-files/desktop.ini       402 B
+
+  4 items removed  (16.6 kB freed)
+```
+
+---
+
+## Categories
+
+| Category | Files removed |
+|---|---|
+| `macos` | `.DS_Store`, `__MACOSX/`, `.AppleDouble`, `.Spotlight-V100`, `.Trashes`, etc. |
+| `windows` | `Thumbs.db`, `desktop.ini`, `ehthumbs.db`, `$RECYCLE.BIN`, etc. |
+| `linux` | `.fuse_hidden*`, `.directory`, `.Trash-*`, `.nfs*` |
+| `ide` | `.idea/`, `.vscode/`, `.classpath`, `.settings/`, etc. |
+| `editor` | `*~`, `*.bak`, `*.orig`, `*.swp`, `*.tmp` |
+
+Default: `macos`, `windows`, `linux`
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--type <list>` | Comma-separated categories: `macos,windows,linux,ide,editor` |
+| `--all` | Remove all categories |
+| `--dry-run` | Show what would be removed, don't delete |
+| `--gitignore` | Update `.gitignore` to prevent future junk |
+| `--stats` | Show breakdown by category |
+
+---
+
+## License
+
+MIT
+
+---
+
+## Keywords
+
+`.DS_Store` · `Thumbs.db` · `desktop.ini` · `remove junk files` · `clean os files` · `delete ds_store` · `mac junk` · `cleanup` · `cross-platform` · `zero dependencies`
+
+---
+
+<div align="center">
+
+**Built to solve, shared to help — Rushabh Shah 🛠️✨**
+
+<sub>One of 40+ zero-dependency developer CLI tools — no <code>node_modules</code>, ever.</sub>
+
+</div>

package/bin/dot-clean.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const VERSION = '1.0.0';
+
+// ─── ANSI ─────────────────────────────────────────────────────────────────────
+const isTTY  = process.stdout.isTTY;
+const c      = (code, t) => isTTY ? `\x1b[${code}m${t}\x1b[0m` : t;
+const bold   = t => c('1',  t);
+const dim    = t => c('2',  t);
+const red    = t => c('31', t);
+const green  = t => c('32', t);
+const yellow = t => c('33', t);
+const cyan   = t => c('36', t);
+
+// ─── Junk file definitions ────────────────────────────────────────────────────
+const JUNK_FILES = {
+  macos: [
+    '.DS_Store', '.DS_Store?', '._*', '.AppleDouble', '.AppleDB',
+    '.AppleDesktop', '.com.apple.timemachineexclude',
+    '.DocumentRevisions-V100', '.fseventsd', '.Spotlight-V100',
+    '.TemporaryItems', '.Trashes', '.VolumeIcon.icns', '.apdisk',
+    '__MACOSX',
+  ],
+  windows: [
+    'Thumbs.db', 'thumbs.db', 'ehthumbs.db', 'ehthumbs_vista.db',
+    'desktop.ini', 'Desktop.ini',
+    '$RECYCLE.BIN', 'RECYCLER', 'RECYCLED',
+    '*.lnk',
+  ],
+  linux: [
+    '.fuse_hidden*', '.directory', '.Trash-*', '.nfs*',
+  ],
+  ide: [
+    '.idea', '.vscode', '*.suo', '*.ntvs*', '*.njsproj', '*.sln',
+    '.project', '.classpath', '.settings', '*.swp', '*~',
+  ],
+  editor: [
+    '*~', '.#*', '.*.swp', '.*.swo', '*.bak', '*.tmp', '*.orig',
+  ],
+};
+
+const ALL_CATEGORIES = Object.keys(JUNK_FILES);
+
+function matchesPattern(name, pattern) {
+  if (pattern.startsWith('*.')) {
+    return name.endsWith(pattern.slice(1));
+  }
+  if (pattern.endsWith('*')) {
+    return name.startsWith(pattern.slice(0, -1));
+  }
+  if (pattern.startsWith('.*')) {
+    // .something* style
+    const prefix = pattern.slice(0, -1);
+    return name.startsWith(prefix);
+  }
+  return name === pattern;
+}
+
+function shouldRemove(name, categories) {
+  for (const cat of categories) {
+    const patterns = JUNK_FILES[cat] || [];
+    for (const p of patterns) {
+      if (matchesPattern(name, p)) return { match: true, category: cat };
+    }
+  }
+  return { match: false };
+}
+
+// ─── Recursive scanner ────────────────────────────────────────────────────────
+function scan(dir, categories, results = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return results; }
+
+  for (const e of entries) {
+    const { match, category } = shouldRemove(e.name, categories);
+    const full = path.join(dir, e.name);
+
+    if (match) {
+      let size = 0;
+      try {
+        if (e.isDirectory()) {
+          size = getDirSize(full);
+          results.push({ path: full, name: e.name, category, isDir: true, size });
+        } else {
+          size = fs.statSync(full).size;
+          results.push({ path: full, name: e.name, category, isDir: false, size });
+        }
+      } catch { /* skip inaccessible */ }
+    } else if (e.isDirectory() && !e.name.startsWith('.')) {
+      scan(full, categories, results);
+    }
+  }
+
+  return results;
+}
+
+function getDirSize(dir) {
+  let total = 0;
+  try {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) total += getDirSize(full);
+      else { try { total += fs.statSync(full).size; } catch { /* skip */ } }
+    }
+  } catch { /* skip */ }
+  return total;
+}
+
+function formatSize(b) {
+  if (b < 1024)      return `${b} B`;
+  if (b < 1024 ** 2) return `${(b / 1024).toFixed(1)} kB`;
+  return `${(b / 1024 ** 2).toFixed(1)} MB`;
+}
+
+function removeRecursive(p) {
+  try {
+    if (fs.statSync(p).isDirectory()) {
+      for (const e of fs.readdirSync(p)) removeRecursive(path.join(p, e));
+      fs.rmdirSync(p);
+    } else {
+      fs.unlinkSync(p);
+    }
+    return true;
+  } catch { return false; }
+}
+
+// ─── .gitignore updater ───────────────────────────────────────────────────────
+const GITIGNORE_ENTRIES = {
+  macos:   ['# macOS', '.DS_Store', '.AppleDouble', '.AppleDB', '__MACOSX', '.Trashes', '.Spotlight-V100'],
+  windows: ['# Windows', 'Thumbs.db', 'ehthumbs.db', 'desktop.ini', '$RECYCLE.BIN'],
+  linux:   ['# Linux', '.fuse_hidden*', '.directory', '.Trash-*'],
+  editor:  ['# Editor backups', '*~', '*.bak', '*.orig', '*.swp'],
+};
+
+function updateGitignore(dir, categories) {
+  const giPath = path.join(dir, '.gitignore');
+  let existing = '';
+  try { existing = fs.readFileSync(giPath, 'utf8'); } catch { /* new file */ }
+
+  const toAdd = [];
+  for (const cat of categories) {
+    const entries = GITIGNORE_ENTRIES[cat] || [];
+    for (const entry of entries) {
+      if (!existing.includes(entry)) toAdd.push(entry);
+    }
+  }
+
+  if (!toAdd.length) {
+    console.log(dim('  .gitignore already up to date'));
+    return;
+  }
+
+  const addition = '\n' + toAdd.join('\n') + '\n';
+  fs.appendFileSync(giPath, addition);
+  console.log(green(`  Updated .gitignore with ${toAdd.filter(e => !e.startsWith('#')).length} entries`));
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+const args        = process.argv.slice(2);
+const VALUE_FLAGS  = new Set(['--type']);
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith('-')) { if (VALUE_FLAGS.has(args[i])) i++; }
+  else positional.push(args[i]);
+}
+
+function getFlag(f) {
+  const i = args.indexOf(f);
+  return i !== -1 ? args[i + 1] : null;
+}
+function hasFlag(f) { return args.includes(f); }
+
+if (hasFlag('--version') || hasFlag('-v')) {
+  console.log(`dot-clean v${VERSION}`); process.exit(0);
+}
+
+if (hasFlag('--help') || hasFlag('-h')) {
+  console.log(`
+${bold('dot-clean')} — Remove OS-generated junk files (.DS_Store, Thumbs.db, etc.)
+
+${bold('USAGE')}
+  dot-clean [dir] [options]
+
+${bold('OPTIONS')}
+  --type <list>   Categories: macos,windows,linux,ide,editor (default: macos,windows,linux)
+  --all           Remove all categories (macos,windows,linux,ide,editor)
+  --dry-run       Show what would be removed without removing
+  --gitignore     Update .gitignore to prevent future junk
+  --stats         Show category breakdown
+  --version       Show version
+
+${bold('EXAMPLES')}
+  dot-clean                       # Remove macOS/Windows/Linux junk in .
+  dot-clean ~/Desktop             # Clean a specific directory
+  dot-clean --all                 # Remove all junk including IDE/editor files
+  dot-clean --dry-run             # Preview without deleting
+  dot-clean --gitignore           # Also update .gitignore
+  dot-clean --type macos          # Only remove macOS junk
+`);
+  process.exit(0);
+}
+
+const targetDir  = path.resolve(positional[0] || '.');
+const dryRun     = hasFlag('--dry-run');
+const doGitignore = hasFlag('--gitignore');
+const showStats  = hasFlag('--stats');
+
+let categories;
+if (hasFlag('--all')) {
+  categories = ALL_CATEGORIES;
+} else if (getFlag('--type')) {
+  categories = getFlag('--type').split(',').map(s => s.trim());
+  for (const c of categories) {
+    if (!JUNK_FILES[c]) { console.error(red(`\nUnknown type: ${c}. Valid: ${ALL_CATEGORIES.join(', ')}\n`)); process.exit(1); }
+  }
+} else {
+  categories = ['macos', 'windows', 'linux'];
+}
+
+if (!fs.existsSync(targetDir)) {
+  console.error(red(`\nDirectory not found: ${targetDir}\n`)); process.exit(1);
+}
+
+console.log(`\n${bold('dot-clean')}  ${cyan(targetDir)}`);
+console.log(dim(`  Scanning for: ${categories.join(', ')}...\n`));
+
+const found = scan(targetDir, categories);
+
+if (!found.length) {
+  console.log(green('  No junk files found.\n'));
+  if (doGitignore) updateGitignore(targetDir, categories);
+  process.exit(0);
+}
+
+// Group by category for stats
+const byCat = {};
+let totalSize = 0;
+for (const f of found) {
+  if (!byCat[f.category]) byCat[f.category] = 0;
+  byCat[f.category]++;
+  totalSize += f.size;
+}
+
+// Display files
+for (const f of found) {
+  const rel    = path.relative(targetDir, f.path);
+  const sizeFmt = dim(formatSize(f.size));
+  const type   = f.isDir ? dim('/') : '';
+  if (dryRun) {
+    console.log(`  ${yellow('~')} ${rel}${type}  ${sizeFmt}`);
+  } else {
+    const ok = removeRecursive(f.path);
+    if (ok) {
+      console.log(`  ${red('✗')} ${rel}${type}  ${sizeFmt}`);
+    } else {
+      console.log(`  ${yellow('!')} ${rel}${type}  ${dim('(failed to remove)')}`);
+    }
+  }
+}
+
+console.log();
+
+if (showStats) {
+  for (const [cat, count] of Object.entries(byCat)) {
+    console.log(`  ${cat.padEnd(10)}  ${count} file(s)`);
+  }
+  console.log();
+}
+
+const action = dryRun ? 'would remove' : 'removed';
+console.log(dryRun
+  ? yellow(`  Dry run: ${found.length} item(s) ${action}  (${formatSize(totalSize)} total)`)
+  : red(`  ${found.length} item(s) ${action}  (${formatSize(totalSize)} freed)`)
+);
+
+if (doGitignore && !dryRun) {
+  console.log();
+  updateGitignore(targetDir, categories);
+}
+
+console.log();
+process.exit(0);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lowdep/dot-clean",
+  "version": "1.0.0",
+  "description": "Remove .DS_Store, Thumbs.db, desktop.ini, and other OS-generated junk files recursively — zero dependencies",
+  "bin": {
+    "dot-clean": "bin/dot-clean.js"
+  },
+  "keywords": [
+    "ds-store",
+    "thumbs-db",
+    "junk-files",
+    "cleanup",
+    "cli",
+    "macos",
+    "windows",
+    "zero-dependencies",
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    "remove junk files",
+    "clean os files",
+    "delete ds_store",
+    "mac junk",
+    "cross-platform",
+    "zero dependencies"
+  ],
+  "author": "Rushabh Shah",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "bin/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rushabh5000/dot-clean.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rushabh5000/dot-clean/issues"
+  },
+  "homepage": "https://github.com/Rushabh5000/dot-clean#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}