dsh-disk-cleaner 0.0.0-stage → 1.0.0

package/lib/audit.js

@@ -0,0 +1,262 @@
+/**
+ * Read-only space assessment.
+ *
+ * The catalog above can only ever *delete* from directories it already knows are caches.
+ * Most of the space on a real disk is not cache at all — it is installed programs, WSL
+ * disk images, chat-app data, Windows component store, and the user's own files. Those
+ * must never be auto-deleted, but the user still needs to see where the space went.
+ *
+ * So this module measures and reports, and exposes no deletion at all. Anything it finds
+ * is advisory: the panel shows it as a lead to investigate, not a button to press.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { drives, measurePath, scan } from './catalog.js';
+import { buildPlan } from './plan.js';
+
+const { promises: fsp } = fs;
+
+const MB = 1024 * 1024;
+
+const env = (name) => {
+  const value = process.env[name];
+  return typeof value === 'string' && value !== '' ? value : undefined;
+};
+
+const isDir = (p) => {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+const sizeOfFile = (p) => {
+  try {
+    const stat = fs.statSync(p);
+    return stat.isFile() ? stat.size : 0;
+  } catch {
+    return 0;
+  }
+};
+
+/**
+ * Each area is a category the user recognises, described by where it lives and why it is
+ * not something this plugin will remove. `group` separates the three different kinds of
+ * answer: `system` (Windows itself), `app` (installed software and its data), `personal`
+ * (the user's own files).
+ */
+const AREAS = () => {
+  const home = os.homedir();
+  const local = env('LOCALAPPDATA') ?? '';
+  const roaming = env('APPDATA') ?? '';
+  const systemDrive = env('SystemDrive') ?? 'C:';
+
+  return [
+    {
+      id: 'wsl',
+      group: 'system',
+      label: 'WSL distros (ext4.vhdx)',
+      why: 'Virtual disks grow but never shrink on their own; compacting one is a separate, deliberate operation.',
+      paths: () => virtualDisks(path.join(local, 'wsl')),
+    },
+    {
+      id: 'winsxs',
+      group: 'system',
+      label: 'Windows component store (WinSxS)',
+      why: 'Holds rollback copies of system components. Only DISM can service it, and it needs an elevated prompt.',
+      paths: () => [path.join(systemDrive + path.sep, 'Windows', 'WinSxS')],
+    },
+    {
+      id: 'system-files',
+      group: 'system',
+      label: 'Hibernation and page files',
+      why: 'Reserved by Windows at boot. Turned off through system settings, never by deleting the file.',
+      files: () => ['hiberfil.sys', 'pagefile.sys', 'swapfile.sys'].map((name) => path.join(systemDrive + path.sep, name)),
+    },
+    {
+      id: 'programs',
+      group: 'app',
+      label: 'Installed programs (user scope)',
+      why: 'Actual applications under your profile. Uninstall them, do not delete the folder.',
+      paths: () => [path.join(local, 'Programs')],
+    },
+    {
+      id: 'program-files',
+      group: 'app',
+      label: 'Installed programs (machine scope)',
+      why: 'Machine-wide applications. Uninstall through Settings.',
+      paths: () => [path.join(systemDrive + path.sep, 'Program Files'), path.join(systemDrive + path.sep, 'Program Files (x86)')],
+    },
+    {
+      id: 'downloads',
+      group: 'personal',
+      label: 'Downloads',
+      why: 'Your own files. Only you can decide what is finished with.',
+      paths: () => [path.join(home, 'Downloads')],
+    },
+    {
+      id: 'documents',
+      group: 'personal',
+      label: 'Documents',
+      why: 'Your own files.',
+      paths: () => [path.join(home, 'Documents')],
+    },
+    {
+      id: 'pictures',
+      group: 'personal',
+      label: 'Pictures',
+      why: 'Your own files.',
+      paths: () => [path.join(home, 'Pictures')],
+    },
+    {
+      id: 'videos',
+      group: 'personal',
+      label: 'Videos',
+      why: 'Your own files.',
+      paths: () => [path.join(home, 'Videos')],
+    },
+    {
+      id: 'desktop',
+      group: 'personal',
+      label: 'Desktop',
+      why: 'Your own files.',
+      paths: () => [path.join(home, 'Desktop')],
+    },
+  ];
+};
+
+/** WSL keeps one ext4.vhdx per distro, one level down under a GUID-named folder. */
+const virtualDisks = (root) => {
+  if (!isDir(root)) return [];
+  const out = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const distro = path.join(root, entry.name);
+    let inner = [];
+    try {
+      inner = fs.readdirSync(distro, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const item of inner) {
+      if (item.isFile() && item.name.toLowerCase().endsWith('.vhdx')) out.push(path.join(distro, item.name));
+    }
+  }
+  return out;
+};
+
+/**
+ * Measure every area that can be addressed at all. Areas that resolve to nothing are
+ * dropped rather than reported as zero, so the list only shows what actually exists.
+ */
+/**
+ * Long enough that returning to the panel within a normal work session is instant, short
+ * enough that a folder cleared half an hour ago does not still show its old size.
+ */
+const CACHE_TTL = 600_000;
+let cached = undefined;
+let cachedAt = 0;
+
+/**
+ * A real deletion invalidates the measurement it was based on: the panel re-assesses right
+ * after a clean, and serving the old numbers would keep recommending space already freed.
+ */
+export function invalidateAudit() {
+  cached = undefined;
+  cachedAt = 0;
+}
+
+/**
+ * Measure the whole disk's non-cache space. This is a deep walk (it takes a minute or two
+ * on a full disk), so a result is reused for a short while: the panel and the agent ask
+ * for the same picture within moments of each other, and re-walking every app folder for
+ * the second caller buys nothing.
+ */
+export async function audit() {
+  if (cached !== undefined && Date.now() - cachedAt < CACHE_TTL) return { ...cached, cached: true };
+  const [areas, largestApps, reclaimable] = await Promise.all([
+    Promise.all(AREAS().map(measureArea)),
+    largestAppDirs(),
+    scan(),
+  ]);
+  const measured = areas.filter(Boolean).sort((a, b) => b.bytes - a.bytes);
+  const plan = buildPlan({ areas: measured, largestApps, reclaimable, driveInfo: drives() });
+  cached = { areas: measured, largestApps, plan };
+  cachedAt = Date.now();
+  return { ...cached, cached: false };
+}
+
+/** Measure one area, or return null when none of its locations exist. */
+async function measureArea(area) {
+  let bytes = 0;
+  let files = 0;
+  let present = 0;
+  let first;
+
+  for (const file of area.files?.() ?? []) {
+    const size = sizeOfFile(file);
+    if (size > 0) {
+      bytes += size;
+      files += 1;
+      present += 1;
+      first ??= file;
+    }
+  }
+  for (const abs of area.paths?.() ?? []) {
+    const found = isDir(abs) ? await measurePath(abs) : { bytes: sizeOfFile(abs), files: 1 };
+    if (found.bytes <= 0 && found.files <= 0) continue;
+    bytes += found.bytes;
+    files += found.files;
+    present += 1;
+    first ??= abs;
+  }
+
+  if (present === 0) return null;
+  return { id: area.id, group: area.group, label: area.label, why: area.why, bytes, files, first };
+}
+
+/**
+ * The single biggest contributors under the two app-data roots. This is what makes the
+ * audit actionable: "3.6 GB in Roaming\kingsoft" points somewhere a Settings page does not.
+ *
+ * ponytail: the trees under the named areas (Programs, wsl, Temp, Downloads) get walked a
+ * second time here, which is most of the ~45s first-run cost. The TTL cache means only the
+ * first caller pays and every later one is instant. Measure each app-data root once into a
+ * shared map only if a cold run is still too slow to sit through.
+ */
+async function largestAppDirs() {
+  const out = [];
+  for (const [root, label] of [
+    [env('LOCALAPPDATA'), 'local'],
+    [env('APPDATA'), 'roaming'],
+  ]) {
+    if (root === undefined || !isDir(root)) continue;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    const found = await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
+        .map(async (entry) => {
+          const measured = await measurePath(path.join(root, entry.name));
+          return { scope: label, name: entry.name, bytes: measured.bytes, files: measured.files };
+        }),
+    );
+    for (const item of found) {
+      if (item.bytes >= 100 * MB) out.push(item);
+    }
+  }
+  return out.sort((a, b) => b.bytes - a.bytes).slice(0, 10);
+}

package/lib/catalog.js

@@ -0,0 +1,418 @@
+/**
+ * Known-safe cleanup targets and the two operations over them: measure and purge.
+ *
+ * Safety rules that must never be relaxed here:
+ *  - Only paths built from this catalog are ever touched. Callers select catalog ids,
+ *    never raw paths, so no user-supplied string can reach an unlink.
+ *  - A resolved target must sit inside the environment root it was built from, checked
+ *    after realpath, so a junction planted in a cache directory cannot widen the blast radius.
+ *  - Symlinks and junctions met during a walk are skipped, never followed or deleted.
+ *  - Locked or denied entries are counted as failures and the walk continues.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const { promises: fsp } = fs;
+
+const DAY = 86_400_000;
+const MAX_ENTRIES = 2_000_000;
+
+/** @typedef {{ id: string, root: string, paths: string[] }} Resolved */
+
+const env = (name) => {
+  const value = process.env[name];
+  return typeof value === 'string' && value !== '' ? value : undefined;
+};
+
+const isDir = (p) => {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+const subdirs = (parent, names) => {
+  const out = [];
+  if (!isDir(parent)) return out;
+  for (const name of names) {
+    const candidate = path.join(parent, name);
+    if (isDir(candidate)) out.push(candidate);
+  }
+  return out;
+};
+
+/**
+ * The per-account recycle bin directories on every mounted volume. Each SID directory
+ * is a real three-segment path, so purging them keeps the `tooBroad` guard intact and
+ * never reaches the $Recycle.Bin container itself.
+ */
+const recycleBins = () => {
+  const out = [];
+  for (const letter of 'CDEFGHIJKLMNOPQRSTUVWXYZ') {
+    const base = `${letter}:\\$Recycle.Bin`;
+    if (!isDir(base)) continue;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+      if (!/^S-1-5-/.test(entry.name)) continue;
+      out.push(path.join(base, entry.name));
+    }
+  }
+  return out;
+};
+
+/** Chromium-family caches live per browser profile, so they are discovered, not spelled out. */
+const browserCaches = (userData) => {
+  if (!isDir(userData)) return [];
+  const out = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(userData, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const profile = path.join(userData, entry.name);
+    out.push(...subdirs(profile, ['Cache', 'Code Cache', 'GPUCache', 'DawnCache', 'ShaderCache', 'GrShaderCache']));
+  }
+  return out;
+};
+
+/**
+ * `purge` targets drop every entry under the path. `aged` targets keep anything modified
+ * within `minAgeDays`, because those files may belong to a process that is still running.
+ *
+ * `note` says why a target carries the `caution` risk, in one stable code the UI
+ * translates: 'in-use' (a running program may hold these files), 'rebuild' (the owner
+ * regenerates them, so the first use afterwards is slower), or 'elevation' (Windows
+ * refuses an unelevated delete). Safe targets have none.
+ */
+const CATALOG = [
+  {
+    id: 'temp',
+    kind: 'aged',
+    minAgeDays: 1,
+    risk: 'caution',
+    note: 'in-use',
+    roots: ['TEMP', 'LOCALAPPDATA'],
+    paths: () => [env('TEMP'), env('TMP'), path.join(env('LOCALAPPDATA') ?? '', 'Temp')],
+  },
+  {
+    id: 'windows-temp',
+    kind: 'aged',
+    minAgeDays: 1,
+    risk: 'caution',
+    // Measured on Windows 11: this folder's ACL grants BUILTIN\Users create and delete, so an
+    // unelevated run does remove what it owns here — the real blocker is EBUSY on a file a
+    // service still holds, which the age limit already handles. Calling it `elevation` sent
+    // the user to an elevated prompt that changed nothing and hid the bytes from the plan.
+    note: 'in-use',
+    roots: [],
+    paths: () => ['C:\\Windows\\Temp'],
+  },
+  {
+    id: 'npm-cache',
+    kind: 'purge',
+    risk: 'safe',
+    roots: ['LOCALAPPDATA'],
+    paths: () => [path.join(env('LOCALAPPDATA') ?? '', 'npm-cache')],
+  },
+  {
+    id: 'pnpm-store',
+    kind: 'purge',
+    risk: 'safe',
+    roots: ['LOCALAPPDATA'],
+    paths: () => [path.join(env('LOCALAPPDATA') ?? '', 'pnpm', 'store')],
+  },
+  {
+    id: 'pip-cache',
+    kind: 'purge',
+    risk: 'safe',
+    roots: ['LOCALAPPDATA'],
+    paths: () => [path.join(env('LOCALAPPDATA') ?? '', 'pip', 'Cache')],
+  },
+  {
+    id: 'uv-cache',
+    kind: 'purge',
+    risk: 'safe',
+    roots: ['LOCALAPPDATA'],
+    paths: () => [path.join(env('LOCALAPPDATA') ?? '', 'uv', 'cache')],
+  },
+  {
+    id: 'crash-dumps',
+    kind: 'purge',
+    risk: 'safe',
+    roots: ['LOCALAPPDATA'],
+    paths: () => [path.join(env('LOCALAPPDATA') ?? '', 'CrashDumps')],
+  },
+  {
+    id: 'chrome-cache',
+    kind: 'purge',
+    risk: 'caution',
+    note: 'rebuild',
+    roots: ['LOCALAPPDATA'],
+    paths: () => browserCaches(path.join(env('LOCALAPPDATA') ?? '', 'Google', 'Chrome', 'User Data')),
+  },
+  {
+    id: 'edge-cache',
+    kind: 'purge',
+    risk: 'caution',
+    note: 'rebuild',
+    roots: ['LOCALAPPDATA'],
+    paths: () => browserCaches(path.join(env('LOCALAPPDATA') ?? '', 'Microsoft', 'Edge', 'User Data')),
+  },
+  {
+    id: 'code-cache',
+    kind: 'purge',
+    risk: 'caution',
+    note: 'rebuild',
+    roots: ['APPDATA'],
+    paths: () => subdirs(env('APPDATA') ?? '', [path.join('Code', 'Cache'), path.join('Code', 'CachedData'), path.join('Code', 'CachedExtensionVSIXs')]),
+  },
+  {
+    id: 'windows-update',
+    kind: 'purge',
+    risk: 'caution',
+    note: 'elevation',
+    roots: [],
+    paths: () => ['C:\\Windows\\SoftwareDistribution\\Download'],
+  },
+  {
+    id: 'recycle-bin',
+    kind: 'purge',
+    risk: 'safe',
+    roots: [],
+    paths: () => recycleBins(),
+  },
+  {
+    id: 'inet-cache',
+    kind: 'purge',
+    risk: 'caution',
+    note: 'rebuild',
+    roots: ['LOCALAPPDATA'],
+    paths: () => [path.join(env('LOCALAPPDATA') ?? '', 'Microsoft', 'Windows', 'INetCache')],
+  },
+];
+
+const byId = new Map(CATALOG.map((entry) => [entry.id, entry]));
+
+/** A path is refused unless it is deep enough to be a cache and not a filesystem root. */
+const tooBroad = (abs) => {
+  const parts = path.resolve(abs).split(path.sep).filter(Boolean);
+  return parts.length < 3 || /^[A-Za-z]:$/.test(path.resolve(abs));
+};
+
+const realOrSelf = (p) => {
+  try {
+    return fs.realpathSync.native(p);
+  } catch {
+    return path.resolve(p);
+  }
+};
+
+const within = (abs, root) => {
+  const a = realOrSelf(abs);
+  const r = realOrSelf(root);
+  const rel = path.relative(r, a);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+
+/** A volume such as `C:\`; anything else (including undefined) means every volume. */
+const onDrive = (abs, drive) => drive === undefined || path.parse(abs).root.toLowerCase() === drive.toLowerCase();
+
+/** Resolve catalog ids to the concrete directories that exist right now, optionally on one volume. */
+export function resolveTargets(only, drive) {
+  const selected = only === undefined ? CATALOG : CATALOG.filter((entry) => only.includes(entry.id));
+  return selected.map((entry) => {
+    const found = [];
+    for (const candidate of entry.paths()) {
+      if (typeof candidate !== 'string' || candidate === '') continue;
+      if (tooBroad(candidate)) continue;
+      if (!isDir(candidate)) continue;
+      if (!onDrive(candidate, drive)) continue;
+      const roots = entry.roots.map((name) => env(name)).filter(Boolean);
+      if (roots.length > 0 && !roots.some((root) => within(candidate, root))) continue;
+      if (!found.includes(candidate)) found.push(candidate);
+    }
+    // The volume each target sits on, so a caller can group or filter by drive.
+    const drives = [...new Set(found.map((abs) => path.parse(abs).root))];
+    return {
+      id: entry.id,
+      kind: entry.kind,
+      risk: entry.risk,
+      note: entry.note ?? '',
+      minAgeDays: entry.minAgeDays ?? 0,
+      paths: found,
+      drives,
+    };
+  });
+}
+
+export async function measurePath(abs) {
+  let bytes = 0;
+  let files = 0;
+  let seen = 0;
+  const stack = [abs];
+  while (stack.length > 0 && seen < MAX_ENTRIES) {
+    const dir = stack.pop();
+    let handle;
+    try {
+      handle = await fsp.opendir(dir);
+    } catch {
+      continue;
+    }
+    try {
+      for await (const entry of handle) {
+        seen += 1;
+        if (entry.isSymbolicLink()) continue;
+        if (entry.isDirectory()) {
+          stack.push(path.join(dir, entry.name));
+          continue;
+        }
+        if (!entry.isFile()) continue;
+        try {
+          bytes += (await fsp.stat(path.join(dir, entry.name))).size;
+          files += 1;
+        } catch {
+          /* a file that vanished or is locked contributes nothing */
+        }
+      }
+    } catch {
+      /* an unreadable directory ends this branch */
+    }
+  }
+  return { bytes, files };
+}
+
+/** Measure every resolved target concurrently, keeping the host event loop free. */
+export async function scan(only, drive) {
+  const targets = resolveTargets(only, drive);
+  const measured = await Promise.all(
+    targets.map(async (target) => {
+      let bytes = 0;
+      let files = 0;
+      for (const abs of target.paths) {
+        const size = await measurePath(abs);
+        bytes += size.bytes;
+        files += size.files;
+      }
+      return { ...target, bytes, files };
+    }),
+  );
+  return measured;
+}
+
+async function purgePath(abs, cutoff) {
+  let bytes = 0;
+  let removed = 0;
+  let failed = 0;
+  const dirs = [];
+  const stack = [abs];
+  while (stack.length > 0 && dirs.length < MAX_ENTRIES) {
+    const dir = stack.pop();
+    dirs.push(dir);
+    let handle;
+    try {
+      handle = await fsp.opendir(dir);
+    } catch {
+      failed += 1;
+      continue;
+    }
+    try {
+      for await (const entry of handle) {
+        const full = path.join(dir, entry.name);
+        if (entry.isSymbolicLink()) continue;
+        if (entry.isDirectory()) {
+          stack.push(full);
+          continue;
+        }
+        if (!entry.isFile()) continue;
+        try {
+          const stat = await fsp.stat(full);
+          if (cutoff !== undefined && stat.mtimeMs > cutoff) continue;
+          await fsp.unlink(full);
+          bytes += stat.size;
+          removed += 1;
+        } catch {
+          failed += 1;
+        }
+      }
+    } catch {
+      failed += 1;
+    }
+  }
+  // Deepest first; index 0 is the target itself, which stays as an empty directory.
+  for (let i = dirs.length - 1; i > 0; i -= 1) {
+    try {
+      await fsp.rmdir(dirs[i]);
+    } catch {
+      /* still holds a kept or undeletable file, which is expected */
+    }
+  }
+  return { bytes, removed, failed };
+}
+
+/** Delete the contents of the selected targets, or with `dryRun` only report what it would delete. */
+export async function clean(ids, options = {}) {
+  const dryRun = options.dryRun === true;
+  const targets = resolveTargets(ids, options.drive);
+  const results = [];
+  for (const target of targets) {
+    const cutoff = target.minAgeDays > 0 ? Date.now() - target.minAgeDays * DAY : undefined;
+    if (dryRun) {
+      let bytes = 0;
+      let files = 0;
+      for (const abs of target.paths) {
+        const size = await measurePath(abs);
+        bytes += size.bytes;
+        files += size.files;
+      }
+      results.push({ id: target.id, bytes, removed: files, failed: 0 });
+      continue;
+    }
+    let bytes = 0;
+    let removed = 0;
+    let failed = 0;
+    for (const abs of target.paths) {
+      if (tooBroad(abs)) {
+        failed += 1;
+        continue;
+      }
+      const outcome = await purgePath(abs, cutoff);
+      bytes += outcome.bytes;
+      removed += outcome.removed;
+      failed += outcome.failed;
+    }
+    results.push({ id: target.id, bytes, removed, failed });
+  }
+  return results;
+}
+
+/** Per-drive capacity, measured with the same call the filesystem itself answers. */
+export function drives() {
+  const out = [];
+  for (const letter of 'CDEFGHIJKLMNOPQRSTUVWXYZ') {
+    const root = `${letter}:\\`;
+    try {
+      const stat = fs.statfsSync(root);
+      const blockSize = Number(stat.bsize);
+      const total = blockSize * Number(stat.blocks);
+      const free = blockSize * Number(stat.bavail);
+      if (!Number.isFinite(total) || total <= 0) continue;
+      out.push({ root, total, free, used: total - free });
+    } catch {
+      /* no volume at this letter */
+    }
+  }
+  return out;
+}
+
+export const catalogIds = () => CATALOG.map((entry) => entry.id);
+export const hasTarget = (id) => byId.has(id);