disk-space-saviour 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.20.0
+
+### Minor Changes
+
+- Clean every installed Chromium on-device AI model, including the current
+  version and the classifier model, in Chrome, Chromium and Edge. The browser
+  downloads a model again when a page uses its built-in AI; a loaded model or a
+  download in progress keeps it in place.
+
+  Keep a Claude Code version while its lock file names a running session or
+  cannot be read, and recheck locks, globally installed packages and other
+  version blockers right before deleting a toolchain version.
+
+  `--only` also targets a single item by its id and the items inside a path or
+  matching a glob. A run limited to global cache rules or their items scans only
+  those rules and skips project discovery.
+
+  A run limited to toolchain version rules, such as `--only claude-code-versions`,
+  scans only those rules and skips project discovery.
+
 ## 0.19.0
 
 ### Minor Changes

package/README.md

@@ -68,8 +68,13 @@ dss docker scan|clean [--container ID] [--recursive]
 
 Run `dss --help` for every option. The most useful ones:
 
-- `--only NAME` limits a run to an ecosystem, rule or kind (`--only rust`,
-  `--only npm-cache`, `--only docker-stopped-container`).
+- `--only NAME|ID|PATH` limits a run to an ecosystem, rule or kind
+  (`--only rust`, `--only npm-cache`, `--only docker-stopped-container`), a
+  single item by its JSON `id`, or the items inside a path or matching a glob
+  (`--only ~/Library/Caches/Codex`, `--only '**/Crashpad/*'`). A path never
+  widens to the item holding it. When every entry names a cache or
+  toolchain version rule or one of its items, only those rules are scanned,
+  so `dss clean --only openai-app-caches --yes` takes seconds.
 - `--exclude PATH|GLOB` prunes matching paths and descendants before reading
   them. Patterns containing separators match full paths and their ancestors;
   other patterns also match ancestor basenames.
@@ -110,8 +115,8 @@ LibreWolf, Waterfox, Zen and Floorp, IDE caches (JetBrains, VS Code, Cursor,
 Windsurf, Qoder), AI agent caches and logs, the Discord cache, macOS app
 updates staged by Sparkle and Squirrel, package manager archives, trash, crash
 reports, core dumps and journald logs. Application downloads are covered too:
-Chrome bundle clones left by exited browsers, superseded Chrome on-device
-models, Google Updater installers, ChatGPT Atlas and Codex app caches,
+Chrome bundle clones left by exited browsers, Chromium on-device AI models
+(downloaded again when a page uses built-in AI), Google Updater installers, ChatGPT Atlas and Codex app caches,
 Electron and electron-builder archives, the Bun transpiler cache, Docker
 Desktop and Warp staged updates (kept while the app runs), Zed language
 servers, tree-sitter toolchains, Codex plugin staging, the Clang module cache
@@ -145,7 +150,10 @@ is needed. Agent scratch cleanup requires inactivity and Git safety checks.
   version holding globally installed npm packages or pyenv virtual
   environments is blocked; bundled `npm`/`corepack` and use-m caches
   (`<name>-v-<version>`) are reinstalled on demand and do not count.
-  Container paths are checked individually before each bounded deletion batch.
+  A Claude Code version stays while a running session uses it: its
+  executable is open, or its `~/.local/state/claude/locks/<version>.lock`
+  names a live process or cannot be read. All of this is checked again right
+  before each version is deleted. Container paths are checked individually before each bounded deletion batch.
 - **Rust builds are pruned in two parts.** `cargo-superseded` removes
   older hashes of a unit (`.rlib`, `.rmeta`, `.so`/`.dylib`/`.a`,
   `build/*`, `.fingerprint`) that a newer build replaced, but never while

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "disk-space-saviour",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Safely reclaims disk space: caches and build outputs of 20+ ecosystems, forgotten projects, and Docker (running, stopped and nested containers), with an emergency mode",
   "type": "module",
   "main": "src/index.js",

package/src/clean.js

@@ -403,9 +403,16 @@ export class Cleaner {
         },
         { rules: [rule] }
       );
-      if (!candidates.some((candidate) => candidate.path === item.path)) {
+      const current = candidates.find(
+        (candidate) => candidate.path === item.path
+      );
+      if (!current) {
         return `${item.path} is now current, pinned, or the newest installed version`;
       }
+      // Locks of running processes and data reinstalling would not restore.
+      if (current.blockers.length > 0) {
+        return current.blockers[0];
+      }
     }
     if (
       item.recheck?.type === 'pyenv-envs' &&

package/src/cli.js

@@ -40,7 +40,8 @@ Scope:
   --container ID|NAME        limit Docker work to these containers (repeat)
   --max-depth N              directory depth for project search (default 6)
   --scan-budget AGE          time budget per filesystem environment (2m)
-  --only NAME                only these ecosystems, rules or kinds (repeat)
+  --only NAME|ID|PATH        only these ecosystems, rules, kinds, item ids,
+                             or items inside a path or glob (repeat)
   --exclude PATH|GLOB        never touch matching paths (repeat)
   --scanner NAME             projects, global, versions, agents, system
   --min-size SIZE            ignore smaller items (default 1M)

package/src/rules/downloads.js

@@ -31,13 +31,23 @@ export const DOWNLOAD_RULES = [
   {
     id: 'chrome-on-device-models',
     ecosystem: 'browsers',
-    description: 'superseded Chrome on-device AI model versions',
+    description:
+      'Chromium on-device AI models, downloaded again when a page uses built-in AI',
+    // Every installed version matches: the component updater fetches the
+    // model again on demand. A loaded model is held open and a download in
+    // progress writes to its directory, which the open-file check and the
+    // activity window catch.
     paths: [
-      '~/Library/Application Support/Google/Chrome/OptGuideOnDeviceModel/*',
-      '~/.config/google-chrome/OptGuideOnDeviceModel/*',
-      '{LOCALAPPDATA}/Google/Chrome/User Data/OptGuideOnDeviceModel/*',
-    ],
-    versionPattern: /^(?<version>\d+(?:\.\d+){1,3})$/,
+      '~/Library/Application Support/Google/Chrome*',
+      '~/Library/Application Support/Chromium',
+      '~/Library/Application Support/Microsoft Edge*',
+      '~/.config/google-chrome*',
+      '~/.config/chromium',
+      '{LOCALAPPDATA}/Google/Chrome*/User Data',
+      '{LOCALAPPDATA}/Chromium/User Data',
+      '{LOCALAPPDATA}/Microsoft/Edge*/User Data',
+    ].map((root) => `${root}/OptGuideOnDevice*Model/*`),
+    directoryOnly: true,
     minAge: 'stale',
     busy: [],
   },

package/src/rules/versions.js

@@ -10,6 +10,9 @@
  * matches (nvm runs the newest 20.x for `20`); otherwise it keeps them all.
  * `globalPackages` blocks versions holding packages the user installed
  * globally, which reinstalling the version would not bring back.
+ * `locks` names the lock file a manager writes for each running process of
+ * a version (`{version}` is replaced); a lock naming a live process, or one
+ * that cannot be read, keeps the version.
  *
  * `versionOf(dirPath)` maps an install directory to the version string that
  * defaults and pin files are compared with (see `versionMatches`).
@@ -114,6 +117,7 @@ export const VERSION_RULES = [
     dirs: ['~/.local/share/claude/versions/*'],
     installTypes: ['file'],
     defaultLinks: ['~/.local/bin/claude'],
+    locks: '~/.local/state/claude/locks/{version}.lock',
     busy: ['claude'],
     recheck: true,
   },

package/src/scan.js

@@ -7,6 +7,7 @@ import {
   configureContainerHost,
   resetWritableLayers,
 } from './docker/writable.js';
+import path from 'node:path';
 import { setInterval, clearInterval } from 'node:timers';
 import { scanDocker } from './docker/scan.js';
 import { LocalEnv } from './env/local.js';
@@ -20,10 +21,11 @@ import { LivenessProbe } from './liveness.js';
 import { resolveOptions } from './options.js';
 import { existingPaths, isWithin, matchesExcluded } from './paths.js';
 import { scanAgents } from './scanners/agents.js';
-import { scanGlobal } from './scanners/global.js';
+import { GLOBAL_RULES, scanGlobal, targetedRules } from './scanners/global.js';
 import { scanProjects } from './scanners/projects.js';
 import { scanSystem } from './scanners/system.js';
 import { scanVersions } from './scanners/versions.js';
+import { VERSION_RULES } from './rules/versions.js';
 import { readSwap } from './swap.js';
 import {
   authenticateReport,
@@ -194,6 +196,17 @@ export async function environmentContext(env, options, overrides = {}) {
  * @param {{roots?: string[]|null, errors?: object[]}} [extra]
  * @returns {Promise<object[]>} items
  */
+/** A run limited to global or version rules skips the other scanners. */
+function selectedScanners(options) {
+  if (!targetedRules(options.only)) {
+    return options.scanners;
+  }
+  const rules = { global: GLOBAL_RULES, versions: VERSION_RULES };
+  return options.scanners.filter(
+    (name) => rules[name] && targetedRules(options.only, rules[name]).length > 0
+  );
+}
+
 export async function scanEnvironment(env, options, extra = {}) {
   const controller = new AbortController();
   const abort = () => controller.abort(options.signal.reason);
@@ -321,7 +334,7 @@ async function scanEnvironmentScoped(
   };
   context.ready = ready;
   let incomplete = false;
-  for (const name of options.scanners) {
+  for (const name of selectedScanners(options)) {
     checkSignal(env.signal);
     context.scanner = name;
     stage(name);
@@ -434,12 +447,33 @@ export async function selfContainerIds(env) {
   return [...ids];
 }
 
-function matchesOnly(item, only) {
+/**
+ * `only` entries name an ecosystem, rule, kind or item id, or a path or
+ * glob: an item matches it when each of its paths lies inside the path, or
+ * the path or one of its ancestors matches the glob.
+ */
+function matchesOnly(item, only, pathApi = path) {
   return (
     only.length === 0 ||
     only.some(
       (entry) =>
-        entry === item.ecosystem || entry === item.rule || entry === item.kind
+        [item.ecosystem, item.rule, item.kind, item.id].includes(entry) ||
+        insideOnlyPath(item, entry, pathApi)
+    )
+  );
+}
+
+function insideOnlyPath(item, entry, pathApi) {
+  const glob = /[*?[]/.test(entry);
+  if (!glob && !pathApi.isAbsolute(entry) && !path.win32.isAbsolute(entry)) {
+    return false;
+  }
+  return (
+    item.paths?.length > 0 &&
+    item.paths.every((target) =>
+      glob
+        ? matchesExcluded(target, [entry], pathApi)
+        : isWithin(target, entry, pathApi)
     )
   );
 }
@@ -476,7 +510,7 @@ export function filterItems(items, options, daemons = [], pathApi) {
         item.sizeUnknown ||
         item.imageBytes >= options.minSizeBytes ||
         item.container?.pinnedImage?.bytes >= options.minSizeBytes) &&
-      matchesOnly(item, options.only) &&
+      matchesOnly(item, options.only, pathApi) &&
       !excluded(item, options.exclude, pathApi) &&
       !underDaemonRoot(item, daemons, pathApi)
   );

package/src/scanners/global.js

@@ -9,7 +9,7 @@ import { scanItems } from '../env/scope.js';
 import { CACHE_RULES } from '../rules/ecosystems.js';
 import { OTHER_RULES } from '../rules/other.js';
 import { APP_RULES, expandChromiumCaches } from '../rules/apps.js';
-import { compareVersions } from '../rules/versions.js';
+import { VERSION_RULES, compareVersions } from '../rules/versions.js';
 import { block, makeItem } from '../items.js';
 import { expandGlobPaths, expandRulePath, isWithin } from '../paths.js';
 import { olderThan, scanTimeBusy, resolvePaths } from './common.js';
@@ -231,11 +231,32 @@ async function addBlockers(context, rule, item) {
   }
 }
 
+const namesRule = (entry, rule) =>
+  entry === rule.id || entry.includes(`:${rule.id}:`);
+
+/**
+ * Rules of `rules` that `only` entries name directly or through an item id
+ * (`env:rule:path`), when every entry names a global or version rule; null
+ * when an entry may match anything else and every rule has to run.
+ */
+export function targetedRules(only = [], rules = GLOBAL_RULES) {
+  const targetable = [...GLOBAL_RULES, ...VERSION_RULES];
+  const covered =
+    only.length > 0 &&
+    only.every((entry) => targetable.some((rule) => namesRule(entry, rule)));
+  return covered
+    ? rules.filter((rule) => only.some((entry) => namesRule(entry, rule)))
+    : null;
+}
+
 /**
  * Scans global cache and leftover locations.
  * @returns {Promise<object[]>} report items
  */
-export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
+export async function scanGlobal(
+  context,
+  { rules = targetedRules(context.options.only) ?? GLOBAL_RULES } = {}
+) {
   const { env, options } = context;
   const homes = options.homes ?? (await env.homeDirs());
   const tmpDirs = options.tmpDirs ?? (await env.tmpDirs());

package/src/scanners/versions.js

@@ -20,6 +20,7 @@ import { block, makeItem } from '../items.js';
 import { expandGlobPath, expandRulePath } from '../paths.js';
 import { scanTimeBusy, resolvePaths } from './common.js';
 import { configuredPattern } from '../env/cache-roots.js';
+import { targetedRules } from './global.js';
 
 async function installDirs(env, rule, home) {
   const dirs = [];
@@ -265,6 +266,42 @@ async function blockGlobalPackages(env, rule, dir, item) {
   }
 }
 
+/**
+ * Lock files a manager writes for every running process of a version
+ * (`rule.locks`, `{version}` replaced). A version stays while its lock names
+ * a live process, and while the lock or the process list cannot be read.
+ */
+async function blockLiveLock(context, rule, home, version, item) {
+  if (!rule.locks) {
+    return;
+  }
+  const { env } = context;
+  const file = expandRulePath(rule.locks.replace('{version}', version), {
+    home,
+    pathApi: env.path,
+  });
+  if (!(await env.exists(file))) {
+    return;
+  }
+  let pid = null;
+  try {
+    pid = JSON.parse((await env.readText(file)) ?? '').pid;
+  } catch {
+    pid = null;
+  }
+  if (!Number.isInteger(pid) || pid <= 0) {
+    block(item, `${rule.manager} lock ${file} cannot be read`);
+    return;
+  }
+  context.lockProcesses ??= env.processes().catch(() => null);
+  const processes = await context.lockProcesses;
+  if (!processes) {
+    block(item, `cannot verify the process holding ${file}`);
+  } else if (processes.some((proc) => proc.pid === pid)) {
+    block(item, `locked by running ${rule.manager} (pid ${pid}, ${file})`);
+  }
+}
+
 async function blockPyenvEnvironments(env, rule, dir, item) {
   if (rule.id !== 'pyenv-python') {
     return;
@@ -321,6 +358,7 @@ async function ruleItems(context, rule, home, pins) {
     });
     await blockPyenvEnvironments(env, rule, dir, item);
     await blockGlobalPackages(env, rule, dir, item);
+    await blockLiveLock(context, rule, home, version, item);
     const busy = await scanTimeBusy(context, item);
     if (busy) {
       block(item, `busy: ${busy}`);
@@ -334,7 +372,12 @@ async function ruleItems(context, rule, home, pins) {
  * Scans version manager installs.
  * @returns {Promise<object[]>} report items
  */
-export async function scanVersions(context, { rules = VERSION_RULES } = {}) {
+export async function scanVersions(
+  context,
+  {
+    rules = targetedRules(context.options.only, VERSION_RULES) ?? VERSION_RULES,
+  } = {}
+) {
   const { env, options } = context;
   const homes = options.homes ?? (await env.homeDirs());
   const pins = await projectPins(