disk-space-saviour 0.13.1 → 0.15.1

package/src/cli.js

@@ -54,6 +54,7 @@ Consent:
   -y, --yes                  delete without asking (non-interactive use)
   --dry-run                  never delete, show the plan
   --remove-stopped-containers  allow docker rm of verified stopped containers
+  --investigation-max-age AGE  lift investigation holds older than AGE (opt-in)
   --remove-container ID|NAME  remove this stopped container, even one kept
                              for investigation (repeat)
   --remove-image REF         remove this unused image (repo:tag or id;
@@ -94,6 +95,7 @@ const OPTIONS = {
   yes: { type: 'boolean', short: 'y' },
   'dry-run': { type: 'boolean' },
   'remove-stopped-containers': { type: 'boolean' },
+  'investigation-max-age': { type: 'string' },
   'remove-container': { type: 'string', multiple: true },
   'remove-image': { type: 'string', multiple: true },
   'remove-unused-images': { type: 'boolean' },
@@ -168,6 +170,7 @@ export function toOptions(values, paths = []) {
     until: values.until,
     path: values.path,
     removeStoppedContainers: values['remove-stopped-containers'],
+    investigationMaxAge: values['investigation-max-age'],
     removeContainers: values['remove-container'],
     removeImages: values['remove-image'],
     includeVolumes: values['include-volumes'],
@@ -240,6 +243,7 @@ export function scanAudit(report) {
       totals: report.totals,
       environments: report.environments.map((env) => env.id),
       errors: report.errors,
+      items: report.items,
     },
     entries: report.items.map((item) => ({
       id: item.id,
@@ -301,7 +305,7 @@ class Cli {
         'Run `dss clean --tier safe` to see the plan, add --yes to delete.',
       ].join('\n')
     );
-    return 0;
+    return report.errors.length > 0 ? 1 : 0;
   }
 
   async loadReport(options, values) {
@@ -362,7 +366,10 @@ class Cli {
     this.print(values, audit, () =>
       formatAudit(audit, { verbose: values.verbose })
     );
-    return audit.entries.some((entry) => entry.status === 'failed') ? 1 : 0;
+    return audit.aborted ||
+      audit.entries.some((entry) => entry.status === 'failed')
+      ? 1
+      : 0;
   }
 
   async emergency(options, values) {
@@ -431,6 +438,9 @@ export async function runCli(argv, deps = {}) {
       setTrace(true);
     }
     const options = dropUndefined(toOptions(values, paths));
+    if (deps.signal) {
+      options.signal = deps.signal;
+    }
     return await dispatch(
       new Cli(io, deps.api ?? API),
       command,

package/src/docker/cli.js

@@ -8,6 +8,7 @@
  */
 
 import { pipeInto } from '../exec.js';
+import { diffSnapshot } from './snapshots.js';
 
 const DECIMAL_UNITS = {
   b: 1,
@@ -208,11 +209,29 @@ export class DockerCli {
   }
 
   async containers() {
+    const output = await this.json([
+      'ps',
+      '--all',
+      '--no-trunc',
+      '--format',
+      '{{.ID}}\\t{{.Names}}\\t{{.State}}\\t{{.Status}}\\t{{.Image}}',
+    ]);
+    return output
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        const [ID, Names, State, Status, Image] = line.split('\t');
+        return { ID, Names, State, Status, Image };
+      });
+  }
+
+  async images() {
     return jsonLines(
       await this.json([
-        'ps',
+        'image',
+        'ls',
         '--all',
-        '--size',
         '--no-trunc',
         '--format',
         '{{json .}}',
@@ -220,6 +239,16 @@ export class DockerCli {
     );
   }
 
+  async containerSize(id) {
+    const [entry] = JSON.parse(
+      await this.json(['inspect', '--type', 'container', '--size', id])
+    );
+    if (!Number.isFinite(entry?.SizeRw) || entry.SizeRw < 0) {
+      throw new Error(`size unknown for container ${id}`);
+    }
+    return { bytes: entry.SizeRw, virtualBytes: entry.SizeRootFs ?? 0 };
+  }
+
   async inspect(ids) {
     if (ids.length === 0) {
       return [];
@@ -240,9 +269,8 @@ export class DockerCli {
     }
   }
 
-  async diff(id) {
-    const result = await this.run(['diff', id]);
-    return result.code === 0 ? result.stdout : null;
+  diff(id, options) {
+    return diffSnapshot(this, id, options);
   }
 
   /** Check a small file in a stopped container without starting it. */

package/src/docker/containers.js

@@ -14,6 +14,7 @@ import path from 'node:path';
 
 import { GitInspector, stateBlockers } from '../git.js';
 import { LocalEnv } from '../env/local.js';
+import { trace } from '../exec.js';
 import { repoRootsFromDiff } from './cli.js';
 
 export const COPY_EXCLUDES = [
@@ -95,8 +96,7 @@ export function ownerOf(ps, inspected) {
   return {
     name,
     image: ps.Image,
-    command: ps.Command ? ps.Command.replace(/^"|"$/g, '') : null,
-    createdAt: ps.CreatedAt ?? null,
+    ...containerMetadata(ps, inspected),
     finishedAt: inspected?.State?.FinishedAt ?? null,
     exitCode: typeof state?.ExitCode === 'number' ? state.ExitCode : null,
     oomKilled: Boolean(state?.OOMKilled),
@@ -108,6 +108,18 @@ export function ownerOf(ps, inspected) {
   };
 }
 
+function containerMetadata(ps, inspected) {
+  return {
+    command: ps.Command
+      ? ps.Command.replace(/^"|"$/g, '')
+      : [
+          ...(inspected?.Config?.Entrypoint ?? []),
+          ...(inspected?.Config?.Cmd ?? []),
+        ].join(' ') || null,
+    createdAt: ps.CreatedAt ?? inspected?.Created ?? null,
+  };
+}
+
 /** Counters and flags such as `1` or `true` are not session ids. */
 function sessionLike(value) {
   const text = String(value).trim();
@@ -180,10 +192,28 @@ export function containerNamed(names, id, name) {
   );
 }
 
+export function investigationExpired(state, options = {}) {
+  const age = options.investigationMaxAgeMs;
+  const finished = Date.parse(state?.FinishedAt);
+  return (
+    age !== null &&
+    age !== undefined &&
+    Number.isFinite(age) &&
+    age >= 0 &&
+    Number.isFinite(finished) &&
+    finished > 0 &&
+    (options.now?.() ?? Date.now()) - finished >= age
+  );
+}
+
 /** Blocker of a container kept for investigation that was not named. */
 export function investigationBlocker(state, id, name, options = {}) {
   const reason = investigationReason(state);
-  if (!reason || containerNamed(options.removeContainers, id, name)) {
+  if (
+    !reason ||
+    investigationExpired(state, options) ||
+    containerNamed(options.removeContainers, id, name)
+  ) {
     return null;
   }
   return `${reason}; remove it only with --remove-container ${id.slice(0, SHORT_ID)}`;
@@ -294,20 +324,36 @@ function excludedWorkBlockers(checked, changed, blockers) {
 }
 
 export async function containerGitState(docker, id, options = {}) {
-  const diff = await docker.diff(id);
+  try {
+    return await inspectContainerGitState(docker, id, options);
+  } catch (error) {
+    trace('container Git inspection failed', id, error.stack ?? error.message);
+    return {
+      repos: [],
+      blockers: [`cannot verify Git work in the container: ${error.message}`],
+    };
+  }
+}
+
+async function inspectContainerGitState(docker, id, options) {
+  const diff = await docker.diff(id, { fresh: options.fresh });
   if (diff === null) {
     return {
       repos: [],
       blockers: ['cannot list the writable layer (`docker diff` failed)'],
     };
   }
-  const roots = new Set(repoRootsFromDiff(diff));
+  const relevantDiff = diff
+    .split('\n')
+    .filter((line) => !excludedRepoPath(line.slice(2)))
+    .join('\n');
+  const roots = new Set(repoRootsFromDiff(relevantDiff));
   const maxRepos = options.maxRepos ?? DEFAULT_MAX_REPOS;
   const blockers = [];
   if (roots.has('/')) {
     blockers.push('the container root is a Git repository');
   }
-  const changed = diff
+  const changed = relevantDiff
     .split('\n')
     .map((line) => /^[ACD] (\/.+)$/.exec(line.trim())?.[1])
     .filter(Boolean);
@@ -324,7 +370,9 @@ export async function containerGitState(docker, id, options = {}) {
     return { repos, blockers };
   }
   // `docker cp` copies to this machine, so Git always runs locally.
-  const git = new GitInspector(options.env ?? new LocalEnv());
+  const git = new GitInspector(options.env ?? new LocalEnv(), {
+    recognizePreserved: true,
+  });
   for (const root of checked) {
     const state = await copyAndCheck(docker, id, root, git);
     repos.push(state);
@@ -332,3 +380,11 @@ export async function containerGitState(docker, id, options = {}) {
   }
   return { repos, blockers };
 }
+
+function excludedRepoPath(target) {
+  return (
+    /^\/var\/lib\/docker\/(?:overlay2|fuse-overlayfs|btrfs|containerd)\//.test(
+      target
+    ) || /\/\.codex\/(?:.*\/)?\.tmp\/plugins[^/]*(?:\/|$)/.test(target)
+  );
+}

package/src/docker/scan.js

@@ -27,7 +27,6 @@ import { block, makeItem } from '../items.js';
 import { DockerCli, parseDockerSize } from './cli.js';
 import {
   containerGitState,
-  containerNamed,
   gitBlockersForRemoval,
   investigationBlocker,
   isHostBindSource,
@@ -67,7 +66,9 @@ function daemonItems(daemon, verbose, df, options, users) {
   const unused = images.filter((image) => image.Containers === '0');
   const dangling = unused.filter((image) => image.Tag === '<none>');
   const danglingBytes = dangling.reduce(
-    (sum, image) => sum + parseDockerSize(image.UniqueSize ?? image.Size),
+    (sum, image) =>
+      sum +
+      (image.sizeUnknown ? 0 : parseDockerSize(image.UniqueSize ?? image.Size)),
     0
   );
   const measure = { volume: daemon.rootDir, parse: 'docker' };
@@ -80,6 +81,7 @@ function daemonItems(daemon, verbose, df, options, users) {
         description: `${dangling.length} dangling Docker images`,
         target: `daemon:${daemon.id}:dangling`,
         bytes: danglingBytes,
+        sizeUnknown: dangling.some((image) => image.sizeUnknown),
         reason: 'untagged images no container uses',
         action: {
           type: 'command',
@@ -121,7 +123,9 @@ function daemonItems(daemon, verbose, df, options, users) {
   }
   for (const image of taggedImages(unused)) {
     const name = `${image.Repository}:${image.Tag}`;
-    const bytes = parseDockerSize(image.UniqueSize ?? image.Size);
+    const bytes = image.sizeUnknown
+      ? 0
+      : parseDockerSize(image.UniqueSize ?? image.Size);
     const summary = { ref: name, id: image.ID };
     items.push(
       makeItem(env, {
@@ -131,6 +135,7 @@ function daemonItems(daemon, verbose, df, options, users) {
         description: `unused Docker image ${name}`,
         target: `daemon:${daemon.id}:image:${image.ID}`,
         bytes,
+        sizeUnknown: Boolean(image.sizeUnknown),
         tier: 'moderate',
         reason: 'no container uses it; remove it only after deciding per image',
         requiresConfirmation: 'removeImages',
@@ -256,7 +261,7 @@ export async function imageHints(docker, verbose) {
 }
 
 async function stoppedItem(daemon, ps, inspected, options) {
-  const sizes = containerSizes(ps.Size);
+  const sizes = ps.sizes ?? { bytes: 0, virtualBytes: 0 };
   const owner = ownerOf(ps, inspected);
   const kept = investigationBlocker(
     inspected?.State,
@@ -271,6 +276,7 @@ async function stoppedItem(daemon, ps, inspected, options) {
     description: `stopped container ${owner.name} (${ps.Image})`,
     target: `daemon:${daemon.id}:container:${ps.ID}`,
     bytes: sizes.bytes,
+    sizeUnknown: ps.sizeUnknown ?? false,
     tier: 'moderate',
     reason: 'stopped container, its writable layer is deleted by `docker rm`',
     requiresConfirmation: 'removeStoppedContainers',
@@ -280,6 +286,8 @@ async function stoppedItem(daemon, ps, inspected, options) {
       state: ps.State,
       owner,
       investigation: kept,
+      pinnedImage: ps.pinnedImage ?? null,
+      sizeUnknown: ps.sizeUnknown ?? false,
     },
     action: {
       type: 'docker-rm',
@@ -293,32 +301,65 @@ async function stoppedItem(daemon, ps, inspected, options) {
   if (kept) {
     block(item, kept);
   }
-  if (
-    options.removeStoppedContainers ||
-    containerNamed(options.removeContainers, ps.ID, owner.name)
-  ) {
-    const git = await containerGitState(daemon.docker, ps.ID);
-    item.container.repos = git.repos;
-    item.container.gitBlockers = git.blockers;
-    gitBlockersForRemoval(git, ps.ID, options).forEach((reason) =>
-      block(item, reason)
-    );
-  } else {
-    item.container.repos = [];
-    item.container.gitBlockers = [];
-    item.container.gitCheckDeferred = true;
-  }
+  const git = await containerGitState(daemon.docker, ps.ID);
+  item.container.repos = git.repos;
+  item.container.gitBlockers = git.blockers;
+  gitBlockersForRemoval(git, ps.ID, options).forEach((reason) =>
+    block(item, reason)
+  );
   return item;
 }
 
-function matchesFilter(ps, filters) {
-  if (!filters || filters.length === 0) {
-    return true;
+export function selectContainers(rows, filters = []) {
+  if (!filters.length) {
+    return { ids: new Set(rows.map((row) => row.ID)), errors: [] };
+  }
+  const ids = new Set();
+  const errors = [];
+  for (const filter of filters) {
+    const exact = rows.filter(
+      (row) =>
+        row.ID === filter ||
+        String(row.Names ?? '')
+          .split(',')
+          .includes(filter)
+    );
+    const matches = exact.length
+      ? exact
+      : rows.filter(
+          (row) =>
+            row.ID.startsWith(filter) ||
+            String(row.Names ?? '')
+              .split(',')
+              .some((name) => name.startsWith(filter))
+        );
+    if (matches.length === 1) {
+      ids.add(matches[0].ID);
+    } else {
+      errors.push(
+        `container filter ${filter}: ${matches.length ? `ambiguous (${matches.length} matches)` : 'no matching container'}`
+      );
+    }
   }
-  const names = String(ps.Names ?? '').split(',');
-  return filters.some(
-    (filter) => ps.ID.startsWith(filter) || names.includes(filter)
+  return { ids, errors };
+}
+
+function pinnedImage(ps, all, inspected, inventory) {
+  const imageId = inspected.get(ps.ID)?.Image;
+  const image = (inventory.Images ?? []).find(
+    (row) => row.ID === imageId || `${row.Repository}:${row.Tag}` === ps.Image
+  );
+  const users = all.filter((row) =>
+    imageId ? inspected.get(row.ID)?.Image === imageId : row.Image === ps.Image
   );
+  return image && users.length === 1 && STOPPED.has(ps.State)
+    ? {
+        ref: ps.Image,
+        id: image.ID,
+        bytes: parseDockerSize(image.UniqueSize),
+        sizeUnknown: !image.UniqueSize,
+      }
+    : null;
 }
 
 class DockerScan {
@@ -334,6 +375,7 @@ class DockerScan {
       hints: [],
       bindMounts: [],
       volumes: [],
+      errors: [],
     };
   }
 
@@ -356,8 +398,59 @@ class DockerScan {
       depth,
       rootDir: info.DockerRootDir ?? null,
     };
-    const df = await docker.systemDf();
-    const verbose = await docker.systemDfVerbose();
+    // Discover without a global writable-layer walk. Size failures must
+    // never discard the object list or prevent nested daemon discovery.
+    const all = await this.bestEffort(
+      record.env.id,
+      () => docker.containers(),
+      []
+    );
+    const images = await this.bestEffort(
+      record.env.id,
+      () => docker.images(),
+      []
+    );
+    const inspected = new Map(
+      (
+        await this.bestEffort(
+          record.env.id,
+          () => docker.inspect(all.map((ps) => ps.ID)),
+          []
+        )
+      ).map((c) => [c.Id, c])
+    );
+    const df = await this.bestEffort(
+      record.env.id,
+      () => docker.systemDf(),
+      []
+    );
+    const verbose = await this.bestEffort(
+      record.env.id,
+      () => docker.systemDfVerbose(),
+      null
+    );
+    const inventory = verbose ?? {
+      Images: images.map((image) => ({
+        ...image,
+        Containers: String(
+          all.filter(
+            (ps) =>
+              inspected.get(ps.ID)?.Image === image.ID ||
+              ps.Image === `${image.Repository}:${image.Tag}`
+          ).length
+        ),
+        sizeUnknown: true,
+      })),
+    };
+    for (const ps of all) {
+      ps.sizes = await this.bestEffort(
+        record.env.id,
+        () => docker.containerSize(ps.ID),
+        null
+      );
+      ps.sizeUnknown = ps.sizes === null;
+      ps.pinnedImage = pinnedImage(ps, all, inspected, inventory);
+    }
     this.result.daemons.push({
       id,
       env: record.env.id,
@@ -378,15 +471,15 @@ class DockerScan {
     this.result.items.push(
       ...daemonItems(
         daemon,
-        verbose,
+        inventory,
         df,
         this.options,
-        await this.users(verbose)
+        await this.users(inventory)
       )
     );
     if (this.options.includeVolumes) {
       this.result.volumes.push(
-        ...(verbose.Volumes ?? [])
+        ...(inventory.Volumes ?? [])
           .filter((volume) => volume.Links === '0')
           .map((volume) => ({
             daemon: id,
@@ -396,8 +489,8 @@ class DockerScan {
           }))
       );
     }
-    this.result.hints.push(...(await imageHints(docker, verbose)));
-    await this.containers(daemon, record, depth, inherited);
+    this.result.hints.push(...(await imageHints(docker, inventory)));
+    await this.containers(daemon, record, depth, inherited, all, inspected);
   }
 
   /** Last users of images, read once and only when an image needs them. */
@@ -412,14 +505,21 @@ class DockerScan {
     return this.lastUsers;
   }
 
-  async containers(daemon, record, depth, inherited) {
-    const all = await daemon.docker.containers();
-    const inspected = new Map(
-      (await daemon.docker.inspect(all.map((ps) => ps.ID))).map((c) => [
-        c.Id,
-        c,
-      ])
-    );
+  async bestEffort(env, operation, fallback) {
+    let error;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        return await operation();
+      } catch (caught) {
+        error = caught;
+        trace('Docker inspection retry', env, error.message);
+      }
+    }
+    this.result.errors.push({ env, scanner: 'docker', message: error.message });
+    return fallback;
+  }
+
+  async containers(daemon, record, depth, inherited, all, inspected) {
     if (record.env.kind === 'host') {
       for (const ps of all.filter((row) => row.State === 'running')) {
         for (const mount of inspected.get(ps.ID)?.Mounts ?? []) {
@@ -432,9 +532,19 @@ class DockerScan {
         }
       }
     }
+    const selection = selectContainers(
+      all,
+      inherited ? [] : this.options.containerFilter
+    );
+    this.result.errors.push(
+      ...selection.errors.map((message) => ({
+        env: record.env.id,
+        scanner: 'docker',
+        message,
+      }))
+    );
     for (const ps of all) {
-      const selected =
-        inherited || matchesFilter(ps, this.options.containerFilter);
+      const selected = selection.ids.has(ps.ID);
       if (!selected) {
         continue;
       }
@@ -443,7 +553,7 @@ class DockerScan {
   }
 
   async container(daemon, record, depth, ps, inspected) {
-    const sizes = containerSizes(ps.Size);
+    const sizes = ps.sizes ?? { bytes: 0, virtualBytes: 0 };
     const owner = ownerOf(ps, inspected);
     const entry = {
       id: ps.ID,
@@ -455,6 +565,8 @@ class DockerScan {
       daemonEnv: record.env.id,
       depth,
       bytes: sizes.bytes,
+      sizeUnknown: ps.sizeUnknown,
+      pinnedImage: ps.pinnedImage ?? null,
       virtualBytes: sizes.virtualBytes,
       owner,
       env: null,
@@ -480,10 +592,10 @@ class DockerScan {
       entry.note = `state ${ps.State}, left alone`;
       return;
     }
-    await this.running(record, depth, ps, entry);
+    await this.running(record, depth, ps, entry, inspected);
   }
 
-  async running(record, depth, ps, entry) {
+  async running(record, depth, ps, entry, inspected) {
     const label = `${record.env.label}/${entry.name}`;
     const executor = containerExecutor(record.executor, ps.ID, { label });
     const env = new ShellEnv(executor, {
@@ -491,6 +603,7 @@ class DockerScan {
       label,
       kind: 'container',
     });
+    env.writableLayer.inspected = inspected;
     const probe = await executor.run(['sh', '-c', 'true'], {
       timeoutMs: 30000,
     });
@@ -510,7 +623,15 @@ class DockerScan {
     });
     this.result.items.push(...(await this.scanEnvironment(env)));
     if (await env.which('docker')) {
-      await this.daemon({ env, executor, chain }, depth, true);
+      try {
+        await this.daemon({ env, executor, chain }, depth, true);
+      } catch (error) {
+        this.result.errors.push({
+          env: env.id,
+          scanner: 'docker',
+          message: error.message,
+        });
+      }
     }
   }
 }
@@ -523,6 +644,9 @@ class DockerScan {
  */
 export async function scanDocker(hostRecord, options, scanEnvironment) {
   const scan = new DockerScan(options, scanEnvironment);
+  if (options.docker === false) {
+    return scan.result;
+  }
   if (!(await hostRecord.env.which('docker'))) {
     return scan.result;
   }

package/src/docker/snapshots.js

@@ -0,0 +1,65 @@
+/** One bounded, serialized change snapshot per executor/container per run. */
+import { trace } from '../exec.js';
+let queue = Promise.resolve();
+const snapshots = new WeakMap();
+export function resetDiffSnapshots(executor) {
+  snapshots.delete(executor);
+}
+export function diffSnapshot(docker, id, { fresh = false } = {}) {
+  const executor = docker.executor;
+  if (!snapshots.has(executor)) {
+    snapshots.set(executor, new Map());
+  }
+  const registry = snapshots.get(executor);
+  if (fresh) {
+    // Safety checks before container removal must see newly copied Git work.
+    registry.delete(id);
+  }
+  if (!registry.has(id)) {
+    const acquire = async () => {
+      const memory = await executor
+        .run(['cat', '/proc/meminfo'])
+        .catch(() => null);
+      let available =
+        Number(/^MemAvailable:\s+(\d+)/m.exec(memory?.stdout ?? '')?.[1]) *
+        1024;
+      const cgroup = await executor
+        .run([
+          'cat',
+          '/sys/fs/cgroup/memory.max',
+          '/sys/fs/cgroup/memory.current',
+        ])
+        .catch(() => null);
+      const [limit, used] = (cgroup?.stdout ?? '')
+        .trim()
+        .split(/\s+/)
+        .map(Number);
+      if (Number.isFinite(limit) && limit > 0 && Number.isFinite(used)) {
+        available = Math.min(available, Math.max(0, limit - used));
+      }
+      if (!available || available < 512 * 1024 ** 2) {
+        trace(
+          'skipping docker diff: memory headroom unavailable or below 512 MiB',
+          id
+        );
+        return null;
+      }
+      trace('docker diff snapshot', id, '(concurrency 1)');
+      const result = await docker.run(['diff', id], {
+        maxCaptureBytes: 8 * 1024 ** 2,
+      });
+      return result.code === 0 &&
+        !result.truncated &&
+        result.stdout.split('\n').length <= 100000
+        ? result.stdout
+        : null;
+    };
+    const pending = queue.then(acquire, acquire);
+    queue = pending.then(
+      () => {},
+      () => {}
+    );
+    registry.set(id, pending);
+  }
+  return registry.get(id);
+}