disk-space-saviour 0.22.0 → 0.23.0

package/src/mac-apps.js

@@ -0,0 +1,286 @@
+/** Explicit macOS application removal and conservative leftover inventory. */
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { LocalEnv } from './env/local.js';
+import { LivenessProbe } from './liveness.js';
+import { parseBundleIdentifier } from './app-owners.js';
+import { runProcess } from './exec.js';
+import { startAudit, writeAudit } from './audit.js';
+
+const TRASH = `ObjC.import('Foundation');
+function run(args) {
+ const url = $.NSURL.fileURLWithPath(args[0]);
+ if (!$.NSFileManager.defaultManager.trashItemAtURLResultingItemURLError(url, null, null))
+   throw new Error('macOS refused the Trash operation');
+ return 'In Trash';
+}`;
+
+export async function appIdentity(target, home = os.homedir()) {
+  const full = path.resolve(target);
+  const allowed = ['/Applications', path.join(home, 'Applications')].map(
+    (root) => path.resolve(root)
+  );
+  if (
+    !allowed.some((root) => full.startsWith(`${root}${path.sep}`)) ||
+    !full.endsWith('.app')
+  ) {
+    throw new Error(
+      'Select an explicit .app inside /Applications or ~/Applications'
+    );
+  }
+  if ((await fs.realpath(full)) !== full) {
+    throw new Error('Symlinked app paths are not supported');
+  }
+  if (
+    full
+      .split(path.sep)
+      .slice(0, -1)
+      .some((part) => part.endsWith('.app'))
+  ) {
+    throw new Error(
+      'Nested application components cannot be removed separately'
+    );
+  }
+  const stats = await fs.lstat(full);
+  if (!stats.isDirectory()) {
+    throw new Error('Application must be a directory');
+  }
+  const plist = await runProcess([
+    '/usr/bin/plutil',
+    '-convert',
+    'xml1',
+    '-o',
+    '-',
+    path.join(full, 'Contents/Info.plist'),
+  ]);
+  const id = parseBundleIdentifier(plist.stdout);
+  if (plist.code || !id) {
+    throw new Error('Application identity cannot be verified');
+  }
+  return {
+    path: full,
+    id,
+    device: stats.dev,
+    inode: stats.ino,
+    webApp: plist.stdout.includes('CrAppModeShortcutID'),
+    hasReceipt: await fs
+      .access(path.join(full, 'Contents/_MASReceipt/receipt'))
+      .then(
+        () => true,
+        () => false
+      ),
+  };
+}
+
+export function leftoverCategory(kind) {
+  return ['Caches', 'Logs'].includes(kind)
+    ? 'disposable-after-activity-check'
+    : 'user-decision';
+}
+
+async function installedIds(root, ids, errors, depth = 0) {
+  if (depth > 4) {
+    return;
+  }
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const full = path.join(root, entry.name);
+    if (entry.name.endsWith('.app')) {
+      try {
+        const result = await runProcess([
+          '/usr/bin/plutil',
+          '-convert',
+          'xml1',
+          '-o',
+          '-',
+          path.join(full, 'Contents/Info.plist'),
+        ]);
+        const id = parseBundleIdentifier(result.stdout);
+        if (!id) {
+          throw new Error('Unreadable app identity');
+        }
+        ids.add(id);
+      } catch {
+        errors.push(`Cannot inventory ${full}`);
+      }
+    } else {
+      await installedIds(full, ids, errors, depth + 1);
+    }
+  }
+}
+
+export async function appLeftovers(home = os.homedir()) {
+  const ids = new Set();
+  const errors = [];
+  for (const root of [
+    '/Applications',
+    '/System/Applications',
+    path.join(home, 'Applications'),
+  ]) {
+    try {
+      await installedIds(root, ids, errors);
+    } catch (error) {
+      errors.push(`${root}: ${error.message}`);
+    }
+  }
+  const items = [];
+  for (const kind of [
+    'Caches',
+    'Logs',
+    'Application Support',
+    'Containers',
+    'Group Containers',
+    'Preferences',
+    'Saved Application State',
+  ]) {
+    const root = path.join(home, 'Library', kind);
+    const entries = await fs.readdir(root).catch(() => []);
+    for (const name of entries) {
+      const id = name.replace(/\.(plist|savedState)$/, '');
+      if (
+        (kind !== 'Logs' &&
+          !/^(?:com|org|net|io|dev|ai|app|at|ru|us|notion)\.[a-zA-Z0-9_.-]+$/.test(
+            id
+          )) ||
+        id.startsWith('com.apple.')
+      ) {
+        continue;
+      }
+      if (
+        [...ids].some(
+          (installed) =>
+            installed === id ||
+            installed.startsWith(`${id}.`) ||
+            id.startsWith(`${installed}.`)
+        )
+      ) {
+        continue;
+      }
+      items.push({
+        path: path.join(root, name),
+        category: leftoverCategory(kind),
+        status: 'possible-leftover',
+        reason:
+          'No matching bundle in standard application folders; app may be elsewhere or ownership shared',
+        automaticDeletion: false,
+      });
+    }
+  }
+  return {
+    items,
+    errors,
+    note: 'Read-only candidates, not proof of uninstall. Logs can contain diagnostic history. No support data is automatically removed.',
+  };
+}
+
+async function trashApp(identity) {
+  const fresh = await appIdentity(identity.path);
+  if (
+    fresh.inode !== identity.inode ||
+    fresh.device !== identity.device ||
+    fresh.id !== identity.id
+  ) {
+    throw new Error('Application changed during removal');
+  }
+  const env = new LocalEnv();
+  const probe = new LivenessProbe(env, { staleAgeMs: 0 });
+  await probe.refresh(true);
+  await probe.resolve([identity.path]);
+  const blocker = probe.busyReason({
+    paths: [identity.path],
+    checks: { mtime: false },
+  });
+  if (blocker) {
+    throw new Error(blocker);
+  }
+  const result = await runProcess([
+    '/usr/bin/osascript',
+    '-l',
+    'JavaScript',
+    '-e',
+    TRASH,
+    identity.path,
+  ]);
+  if (result.code) {
+    throw new Error(result.stderr || 'macOS Trash operation failed');
+  }
+  if (
+    await fs.lstat(identity.path).then(
+      () => true,
+      () => false
+    )
+  ) {
+    throw new Error('Trash operation did not remove the original path');
+  }
+  return result.stdout.trim();
+}
+
+function removalDryRun(values) {
+  return !values.yes || Boolean(values['dry-run']);
+}
+
+export async function runApps(argv, io, signal) {
+  if (process.platform !== 'darwin') {
+    throw new Error('apps is currently macOS-only');
+  }
+  const { positionals, values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      yes: { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
+      'launcher-only': { type: 'boolean' },
+      json: { type: 'boolean' },
+      'audit-dir': { type: 'string' },
+    },
+  });
+  const [command, ...targets] = positionals;
+  if (command === 'leftovers') {
+    io.stdout(JSON.stringify(await appLeftovers(), null, 2));
+    return 0;
+  }
+  if (command !== 'remove' || !targets.length) {
+    throw new Error(
+      'Use apps remove /absolute/App.app [--yes] [--launcher-only], or apps leftovers'
+    );
+  }
+  const audit = startAudit('apps-remove', {
+    dryRun: removalDryRun(values),
+  });
+  for (const target of targets) {
+    if (signal?.aborted) {
+      throw new Error('Aborted');
+    }
+    try {
+      const identity = await appIdentity(target);
+      if (identity.hasReceipt) {
+        throw new Error('App Store app: use the macOS uninstall flow');
+      }
+      if (identity.webApp && !values['launcher-only']) {
+        throw new Error(
+          'Use Chrome > chrome://apps > Uninstall first; --launcher-only explicitly permits the Trash fallback, preserving browser data and registration'
+        );
+      }
+      const destination = audit.dryRun ? null : await trashApp(identity);
+      audit.entries.push({
+        ...identity,
+        status: audit.dryRun ? 'would-trash' : 'trashed',
+        destination,
+      });
+    } catch (error) {
+      audit.entries.push({
+        path: target,
+        status: 'blocked',
+        reason: error.message,
+      });
+    }
+  }
+  const file = await writeAudit(audit, { auditDir: values['audit-dir'] });
+  io.stdout(JSON.stringify({ ...audit, auditFile: file }, null, 2));
+  return audit.entries.some((entry) => entry.status === 'blocked') ? 1 : 0;
+}

package/src/options.js

@@ -8,6 +8,7 @@ import { parseDuration, parsePercent, parseSize } from './units.js';
 
 export const DEFAULTS = {
   roots: null,
+  containerRoots: null,
   maxDepth: 6,
   staleAge: '1h',
   inactive: '30d',
@@ -78,9 +79,11 @@ export function resolveOptions(input = {}) {
     throw new Error('scanBudget must be a positive finite duration');
   }
   const roots = toList(merged.roots);
+  const containerRoots = toList(merged.containerRoots);
   return {
     ...merged,
     roots: roots.length > 0 ? roots : null,
+    containerRoots: containerRoots.length > 0 ? containerRoots : null,
     maxDepth: Number(merged.maxDepth),
     dockerDepth: Number(merged.dockerDepth),
     staleAgeMs: toMs(staleAge),

package/src/report.js

@@ -438,7 +438,8 @@ function holderLine(holder) {
       `${change > 0 ? '+' : '-'}${formatBytes(Math.abs(change))} since ${new Date(holder.growth.since).toISOString()}`
     );
   }
-  return `${holder.pid} ${holder.command}: ${details.join(', ')}`;
+  const self = holder.self ? ' (this dss run)' : '';
+  return `${holder.pid} ${holder.command}${self}: ${details.join(', ')}`;
 }
 
 function swapLines(swap) {
@@ -454,6 +455,18 @@ function swapLines(swap) {
   ];
 }
 
+/** Requested roots that were not searched, so coverage gaps are visible. */
+function scopeLines(env) {
+  const skipped = (env.scope?.roots ?? []).filter(
+    (root) =>
+      ['roots', 'container-roots'].includes(root.source) &&
+      !['searched', 'pending'].includes(root.status)
+  );
+  return skipped.map(
+    (root) => `  ${env.label}: root ${root.path} ${root.status}`
+  );
+}
+
 function environmentStatusLines(env) {
   const lines = [];
   if (env.layerSource) {
@@ -469,6 +482,7 @@ function environmentStatusLines(env) {
   if (env.hint) {
     lines.push(`  ${env.label}: ${env.hint}`);
   }
+  lines.push(...scopeLines(env));
   return lines;
 }
 
@@ -617,7 +631,9 @@ export function formatAudit(audit, options = {}) {
       ...conditionsSection(audit.blocked, options).slice(2)
     );
   }
-  if (audit.file) {
+  if (audit.auditError) {
+    lines.push(`Audit log: not written (${audit.auditError.message})`);
+  } else if (audit.file) {
     lines.push(`Audit log: ${audit.file}`);
   }
   return lines.join('\n');

package/src/rules/downloads.js

@@ -184,4 +184,31 @@ export const DOWNLOAD_RULES = [
     ],
     minAge: 'stale',
   },
+  {
+    id: 'crashpad-pending-reports',
+    ecosystem: 'system',
+    description:
+      'Chromium and Electron app crash reports never sent: after a month no app uploads them',
+    tier: 'moderate',
+    aggregate: true,
+    paths: [
+      '~/Library/Application Support/*/Crashpad/pending/*',
+      ...['Google', 'Yandex', 'BraveSoftware'].map(
+        (vendor) =>
+          `~/Library/Application Support/${vendor}/*/Crashpad/pending/*`
+      ),
+      '~/.config/*/Crashpad/pending/*',
+    ],
+    minAge: 'inactive',
+  },
+  {
+    id: 'gh-run-log-cache',
+    ecosystem: 'system',
+    description:
+      'GitHub CLI cached workflow run logs: gh downloads them again while GitHub keeps them',
+    tier: 'moderate',
+    aggregate: true,
+    paths: ['~/.cache/gh/run-log-*.zip'],
+    minAge: 'stale',
+  },
 ];

package/src/rules/other.js

@@ -414,6 +414,15 @@ export const OTHER_RULES = [
     aggregate: true,
     paths: ['~/Library/Logs/DiagnosticReports/*'],
   },
+  {
+    id: 'rotated-app-logs',
+    ecosystem: 'system',
+    description:
+      'rotated app logs (warp.log.old.2, app.log.1): apps write only the current log',
+    tier: 'moderate',
+    paths: ['~/Library/Logs/*.log.*', '~/Library/Logs/*/*.log.*'],
+    minAge: 'stale',
+  },
   {
     id: 'apt-archives',
     ecosystem: 'system',

package/src/scan-state.js

@@ -98,6 +98,7 @@ export async function authenticatedReport(report, directory, now = Date.now()) {
 export function scopeKey(options) {
   const names = [
     'roots',
+    'containerRoots',
     'scanners',
     'host',
     'docker',

package/src/scan.js

@@ -13,13 +13,20 @@ import { scanDocker } from './docker/scan.js';
 import { LocalEnv } from './env/local.js';
 import { configureScanPolicy } from './env/policy.js';
 import { configureCacheRoots } from './env/cache-roots.js';
+import {
+  CONTAINER_ROOTS,
+  finishScope,
+  requestedRoots,
+  resolveRoots,
+  scanScope,
+} from './env/roots.js';
 import { checkSignal, environmentScope } from './env/scope.js';
 import { block, tierTotals } from './items.js';
 import { hostExecutor, trace } from './exec.js';
 import { GitInspector } from './git.js';
 import { LivenessProbe } from './liveness.js';
 import { resolveOptions } from './options.js';
-import { existingPaths, isWithin, matchesExcluded } from './paths.js';
+import { isWithin, matchesExcluded } from './paths.js';
 import { scanAgents } from './scanners/agents.js';
 import { GLOBAL_RULES, scanGlobal, targetedRules } from './scanners/global.js';
 import { scanProjects } from './scanners/projects.js';
@@ -50,6 +57,7 @@ const reportEnvironments = new WeakMap();
 export const scannedEnvironment = (report) => reportEnvironments.get(report);
 const RESCAN_OPTIONS = new Set([
   'roots',
+  'containerRoots',
   'scanners',
   'containers',
   'host',
@@ -120,6 +128,7 @@ export async function revalidateReport(saved, input = {}) {
   const scope = Object.fromEntries(
     [
       'roots',
+      'containerRoots',
       'scanners',
       'containers',
       'host',
@@ -140,25 +149,7 @@ export async function revalidateReport(saved, input = {}) {
   return sealReport(current);
 }
 
-/** Common project locations inside containers, scanned when present. */
-export const CONTAINER_ROOTS = [
-  '/workspace',
-  '/workspaces',
-  '/app',
-  '/src',
-  '/code',
-  '/project',
-  '/usr/src/app',
-];
-
-async function defaultRoots(env, homes, tmpDirs) {
-  const roots = [...homes, ...tmpDirs];
-  if (env.kind === 'container') {
-    const present = await existingPaths(env, CONTAINER_ROOTS);
-    roots.push(...CONTAINER_ROOTS.filter((root) => present.has(root)));
-  }
-  return [...new Set(roots)];
-}
+export { CONTAINER_ROOTS };
 
 /**
  * Builds the scanner context of one environment.
@@ -169,17 +160,25 @@ async function defaultRoots(env, homes, tmpDirs) {
 export async function environmentContext(env, options, overrides = {}) {
   await configureScanPolicy(env, {
     ...options,
-    roots: overrides.roots ?? options.roots,
+    roots: requestedRoots(env, options, overrides),
   });
   const liveness = new LivenessProbe(env, {
     staleAgeMs: options.staleAgeMs,
+    inactiveMs: options.inactiveMs,
     now: options.now,
   });
   await liveness.refresh(true);
   const homes = await env.homeDirs();
   await configureCacheRoots(env, homes);
   const tmpDirs = await env.tmpDirs();
-  const roots = overrides.roots ?? (await defaultRoots(env, homes, tmpDirs));
+  const { roots, entries } = await resolveRoots(
+    env,
+    options,
+    overrides,
+    homes,
+    tmpDirs
+  );
+  env.scanScope = scanScope(env, options, entries);
   return {
     env,
     git: new GitInspector(env),
@@ -273,6 +272,7 @@ export async function scanEnvironment(env, options, extra = {}) {
     }
     return items;
   } finally {
+    finishScope(env, selectedScanners(options).includes('projects'));
     clearTimeout(timer);
     clearInterval(interval);
     options.signal?.removeEventListener('abort', abort);
@@ -550,6 +550,7 @@ function envDescriptor(env, depth, chain) {
     chain,
     hint: env.probeHint ?? null,
     scanStatus: env.scanStatus ?? null,
+    scope: env.scanScope ?? null,
     layerSource: env.writableLayer?.source ?? null,
     timings: env.timings?.toJSON() ?? [],
   };
@@ -569,6 +570,15 @@ async function withDisk(env, descriptor, options) {
   };
 }
 
+/**
+ * Scans one running container found by the Docker walk (any depth). Roots
+ * come from `containerRoots`/`roots` via environmentContext, never from the
+ * host's resolved defaults.
+ */
+export function containerScanner(options, errors) {
+  return (inner) => scanEnvironment(inner, options, { errors });
+}
+
 async function dockerSection(env, options, errors) {
   if (options.docker === false) {
     return null;
@@ -582,7 +592,7 @@ async function dockerSection(env, options, errors) {
     const result = await scanDocker(
       hostRecord,
       { ...options, selfContainerIds: await selfContainerIds(env) },
-      (inner) => scanEnvironment(inner, options, { errors })
+      containerScanner(options, errors)
     );
     errors.push(...result.errors);
     if (options.docker === true && result.daemons.length === 0) {

package/src/scanners/agents.js

@@ -20,6 +20,7 @@ import { scanItems } from '../env/scope.js';
  * (the same rule the agent's own `Project.prune()` uses).
  */
 
+import { itemSize } from '../env/hardlinks.js';
 import { block, makeItem } from '../items.js';
 import { listMany, olderThan, scanTimeBusy } from './common.js';
 
@@ -127,7 +128,7 @@ async function appItems(context, app, root) {
       ecosystem: 'agents',
       description: `${app.name} snapshot store ${state.entry.name}`,
       path: state.entry.path,
-      bytes: usage.bytes,
+      ...itemSize([[state.entry.path, usage]]),
       newestMtimeMs: usage.newestMtimeMs,
       worktree: state.worktree,
       ...verdict,

package/src/scanners/global.js

@@ -6,6 +6,7 @@ import { checkSignal, scanItems } from '../env/scope.js';
  * ../rules/downloads.js.
  */
 
+import { itemSize } from '../env/hardlinks.js';
 import { CACHE_RULES } from '../rules/ecosystems.js';
 import { OTHER_RULES, TEMP_CLONE_RULES } from '../rules/other.js';
 import { APP_RULES, expandChromiumCaches } from '../rules/apps.js';
@@ -199,7 +200,7 @@ async function buildItem(context, rule, base, group, homes) {
     description: rule.description,
     path: paths[0],
     paths,
-    bytes: group.reduce((sum, entry) => sum + entry.usage.bytes, 0),
+    ...itemSize(group.map((entry) => [entry.path, entry.usage])),
     sizeEstimated: group.some((entry) => entry.usage.estimated),
     newestMtimeMs: Math.max(...group.map((e) => e.usage.newestMtimeMs ?? 0)),
     tier: rule.tier ?? 'safe',

package/src/scanners/node-modules.js

@@ -0,0 +1,89 @@
+/**
+ * A node_modules directory is regenerable only as far as package managers
+ * fill it. Other data kept there (verification runs, evidence, hand-made
+ * fixtures) survives no reinstall, so it keeps the whole directory.
+ */
+
+import { formatBytes } from '../units.js';
+
+/**
+ * Top-level entries package managers and the tools they run create:
+ * links, lockfile copies, store and workspace state, and caches that
+ * re-create themselves.
+ */
+const MANAGED_ENTRIES = new Set([
+  '.bin',
+  '.package-lock.json',
+  '.modules.yaml',
+  '.pnpm',
+  '.pnpm-workspace-state.json',
+  '.pnpm-workspace-state-v1.json',
+  '.yarn-state.yml',
+  '.yarn-integrity',
+  '.yarn-metadata.json',
+  '.store',
+  '.staging',
+  '.ignored',
+  '.cache',
+  '.vite',
+  '.vite-temp',
+  '.vitest',
+  '.vitest-cache',
+  '.deno',
+  '.prisma',
+  '.astro',
+  '.mf',
+  '.tmp',
+  '.DS_Store',
+]);
+
+/**
+ * Entries of `dir` no package manager installs, with their size; empty
+ * leftovers are left out.
+ * @returns {Promise<Array<{name: string, bytes: number}>>}
+ */
+export async function foreignEntries(env, dir) {
+  const candidates = [];
+  for (const entry of await env.list(dir)) {
+    if (
+      MANAGED_ENTRIES.has(entry.name) ||
+      entry.name.startsWith('@') ||
+      entry.type === 'symlink'
+    ) {
+      continue;
+    }
+    if (
+      entry.type === 'dir' &&
+      (await env.stat(env.path.join(entry.path, 'package.json')))
+    ) {
+      continue;
+    }
+    candidates.push(entry);
+  }
+  if (candidates.length === 0) {
+    return [];
+  }
+  const usages = await env.usageMany(
+    candidates.map((entry) => entry.path),
+    { cache: true }
+  );
+  return candidates
+    .map((entry) => ({ name: entry.name, usage: usages.get(entry.path) }))
+    .filter(({ usage }) => usage && (usage.files ?? 1) > 0)
+    .map(({ name, usage }) => ({ name, bytes: usage.bytes }))
+    .sort((a, b) => b.bytes - a.bytes);
+}
+
+/** Blocker naming the foreign data inside `dir`, or null. */
+export async function foreignDataBlocker(env, dir) {
+  const foreign = await foreignEntries(env, dir);
+  if (foreign.length === 0) {
+    return null;
+  }
+  const names = foreign
+    .slice(0, 3)
+    .map((entry) => `${entry.name} (${formatBytes(entry.bytes)})`)
+    .join(', ');
+  const more = foreign.length > 3 ? ` and ${foreign.length - 3} more` : '';
+  return `holds data no package manager installs: ${names}${more}; a reinstall does not re-create it, so move it out of node_modules first`;
+}