disk-space-saviour 0.0.0-stage → 0.12.0

package/src/index.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Type declarations for disk-space-saviour.
+ */
+
+export type Tier = 'safe' | 'moderate' | 'aggressive';
+export type Size = number | string;
+export type Duration = number | string;
+
+export interface ScanOptions {
+  /** Directories to search for projects (default: homes and tmp dirs). */
+  roots?: string[] | string | null;
+  /** Directory depth for project search. */
+  maxDepth?: number;
+  /** Activity window: newer files are kept (`1h`). */
+  staleAge?: Duration;
+  /** Alias of `staleAge`. */
+  olderThan?: Duration;
+  /** Inactivity before whole dependency dirs become `moderate` (`30d`). */
+  inactive?: Duration;
+  /** Items smaller than this are dropped (`1M`). */
+  minSize?: Size;
+  /** Scan the host file system (`false` for Docker only). */
+  host?: boolean;
+  /** `true` requires Docker, `false` skips it, `null` uses it if reachable. */
+  docker?: boolean | null;
+  /** Docker nesting depth (1 = containers of the host daemon). */
+  dockerDepth?: number;
+  /** Container ids or names to limit Docker work to. */
+  containers?: string[] | string;
+  scanners?: Array<'projects' | 'global' | 'versions' | 'agents' | 'system'>;
+  /** Only these ecosystems, rules or kinds. */
+  only?: string[] | string;
+  /** Paths or basename globs never touched. */
+  exclude?: string[] | string;
+  includeVolumes?: boolean;
+  removeStoppedContainers?: boolean;
+  /**
+   * Stopped containers (name, id or id prefix of 12+ characters) the
+   * operator approves one by one, including ones kept for investigation.
+   */
+  removeContainers?: string[] | string;
+  /**
+   * Unused tagged images (`repo:tag`, `repo` for `:latest`, or an id prefix
+   * of 12+ characters) the operator approves one by one. No tier removes
+   * an image without it or an interactive yes.
+   */
+  removeImages?: string[] | string;
+  allowDirtyRepos?: boolean;
+  /** Exact container ids whose verified Git changes may be removed. */
+  allowDirtyContainers?: string[] | string;
+  /** Delete files directly, never through native cache commands. */
+  noNative?: boolean;
+  /** journald size to keep (`512M`). */
+  journalKeep?: Size;
+  backupDir?: string | null;
+  auditDir?: string | null;
+}
+
+export interface CleanOptions extends ScanOptions {
+  tier?: Tier;
+  dryRun?: boolean;
+  /** Interactive confirmation for items that need it. */
+  confirm?: (item: Item) => boolean | Promise<boolean>;
+  /** `false` skips writing the audit log file. */
+  audit?: boolean;
+  onEntry?: (entry: AuditEntry, item: Item) => void;
+}
+
+export interface EmergencyOptions extends CleanOptions {
+  /** Available bytes wanted, e.g. `20G`. */
+  free?: Size;
+  /** Maximum used percentage, e.g. `80%`. */
+  until?: number | string;
+  /** Volume to watch (default `/`). */
+  path?: string;
+  /** Reuse an existing scan. */
+  report?: Report;
+}
+
+export interface Action {
+  type: 'remove' | 'command' | 'docker-rm' | 'none';
+  paths?: string[];
+  argv?: string[];
+  containerId?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+export interface Item {
+  id: string;
+  env: string;
+  envLabel: string;
+  kind: string;
+  ecosystem: string;
+  rule: string;
+  description: string;
+  path: string | null;
+  paths: string[];
+  bytes: number;
+  newestMtimeMs: number;
+  tier: Tier;
+  reason: string;
+  blockers: string[];
+  requiresConfirmation: string | null;
+  parentId: string | null;
+  action: Action;
+  /** Unused tagged images (`docker-unused-image`). */
+  image?: {
+    ref: string;
+    id: string;
+    bytes: number;
+    createdAt: string | null;
+    /** Last removed container that ran this image, when dss backed it up. */
+    lastUsedBy: {
+      container: string;
+      session: string | null;
+      taskUrl: string | null;
+      finishedAt: string | null;
+    } | null;
+  };
+  [key: string]: unknown;
+}
+
+export interface Disk {
+  total?: number;
+  free: number;
+  used: number;
+  path?: string;
+}
+
+export interface EnvironmentDescriptor {
+  id: string;
+  label: string;
+  kind: 'host' | 'container';
+  depth: number;
+  chain: Array<{ containerId: string; name: string }>;
+  disk?: Disk | null;
+}
+
+export interface TierTotal {
+  items: number;
+  bytes: number;
+}
+
+export interface Report {
+  schema: number;
+  tool: 'disk-space-saviour';
+  createdAt: string;
+  durationMs: number;
+  host: { env: string; label: string; platform: string };
+  options: Record<string, unknown>;
+  environments: EnvironmentDescriptor[];
+  items: Item[];
+  /** Tier totals exclude items that need explicit consent (`consent`). */
+  totals: Record<Tier | 'blocked' | 'consent', TierTotal>;
+  docker: {
+    daemons: Array<Record<string, unknown>>;
+    containers: Array<Record<string, unknown>>;
+    hints: Array<Record<string, unknown>>;
+    volumes: Array<Record<string, unknown>>;
+  } | null;
+  errors: Array<{ env: string; scanner: string; message: string }>;
+}
+
+export interface AuditEntry {
+  id: string;
+  env: string;
+  envLabel: string;
+  rule: string;
+  tier: Tier;
+  kind: string;
+  description: string;
+  path: string | null;
+  paths: string[];
+  pathCount: number;
+  deletedPaths: string[];
+  status: 'planned' | 'removed' | 'skipped' | 'failed';
+  reason: string | null;
+  plannedBytes: number;
+  freedBytes: number;
+  durationMs: number;
+  backup?: string;
+  [key: string]: unknown;
+}
+
+export interface EnvironmentTotal {
+  label: string;
+  freedBytes: number;
+  leftBytes: number;
+  removed: number;
+  planned: number;
+  skipped: number;
+  failed: number;
+}
+
+export interface AuditLog {
+  schema: number;
+  tool: 'disk-space-saviour';
+  command: string;
+  dryRun: boolean;
+  startedAt: string;
+  finishedAt: string | null;
+  entries: AuditEntry[];
+  freedBytes: number;
+  plannedBytes: number;
+  environments: Record<string, EnvironmentTotal>;
+  file?: string;
+  goal?: { freeBytes: number | null; untilPercent: number | null };
+  goalMet?: boolean;
+  reachedTier?: Tier;
+  diskBefore?: Disk;
+  diskAfter?: Disk;
+  [key: string]: unknown;
+}
+
+export declare const TIERS: Tier[];
+
+/** Finds reclaimable space. Never deletes. */
+export declare function scan(options?: ScanOptions): Promise<Report>;
+
+/** Deletes what `options.tier` allows, re-checking every item first. */
+export declare function clean(
+  report: Report,
+  options?: CleanOptions
+): Promise<AuditLog>;
+
+/** Escalates tiers until the free-space goal is met, then stops. */
+export declare function emergency(options: EmergencyOptions): Promise<AuditLog>;
+
+export declare function formatReport(
+  report: Report,
+  options?: { verbose?: boolean }
+): string;
+export declare function formatAudit(
+  audit: AuditLog,
+  options?: { verbose?: boolean }
+): string;
+
+/** Runs the `dss` command line and resolves to its exit code. */
+export declare function runCli(
+  argv: string[],
+  deps?: { io?: object; api?: object }
+): Promise<number>;
+
+export declare function parseSize(value: string | number): number;
+export declare function parseDuration(value: string | number): number;
+export declare function parsePercent(value: string | number): number;
+export declare function formatBytes(bytes: number): string;
+export declare function formatDuration(ms: number): string;
+export declare function goalMet(
+  goal: { freeBytes: number | null; untilPercent: number | null },
+  disk: Disk
+): boolean;
+export declare function selectByTier(items: Item[], tier: Tier): Item[];
+export declare function dropNested(items: Item[]): Item[];

package/src/index.js

@@ -0,0 +1,52 @@
+/**
+ * disk-space-saviour: safely reclaims disk space on hosts, inside running
+ * containers and in nested Docker daemons.
+ *
+ * - `scan(options) → Report` never deletes anything;
+ * - `clean(report, options) → AuditLog` deletes what the tier allows;
+ * - `emergency({free, until}) → AuditLog` escalates tiers until the goal
+ *   is met.
+ */
+
+export { scan, SCANNERS, REPORT_SCHEMA, CONTAINER_ROOTS } from './scan.js';
+export {
+  clean,
+  planItems,
+  environmentTotals,
+  CONFIRMATION_FLAGS,
+} from './clean.js';
+export { emergency, goalMet, bytesNeeded, usedPercent } from './emergency.js';
+export {
+  AUDIT_SCHEMA,
+  auditDirectory,
+  backupDirectory,
+  writeAudit,
+} from './audit.js';
+export { formatReport, formatAudit, formatDisk } from './report.js';
+export { runCli, parseCli, USAGE } from './cli.js';
+export { DEFAULTS, resolveOptions, resolveGoal } from './options.js';
+export {
+  TIERS,
+  tierRank,
+  tierTotals,
+  selectByTier,
+  dropNested,
+} from './items.js';
+export {
+  parseSize,
+  parseDuration,
+  parsePercent,
+  formatBytes,
+  formatDuration,
+} from './units.js';
+export { ECOSYSTEMS, PROJECT_RULES, CACHE_RULES } from './rules/ecosystems.js';
+export { OTHER_RULES } from './rules/other.js';
+export { VERSION_RULES } from './rules/versions.js';
+export { analyzeRustProfile, findRustProfiles } from './scanners/rust.js';
+export { GitInspector } from './git.js';
+export { LivenessProbe } from './liveness.js';
+export { LocalEnv } from './env/local.js';
+export { ShellEnv } from './env/shell.js';
+export { resolveEnvironment } from './env/resolve.js';
+export { hostExecutor, containerExecutor, setTrace } from './exec.js';
+export { DockerCli, assertAllowed } from './docker/cli.js';

package/src/items.js

@@ -0,0 +1,166 @@
+/**
+ * Report item model shared by scanners, cleaner, emergency mode and output.
+ *
+ * An item is one reclaimable thing: a directory, a set of stale files, a
+ * native clean command, or a Docker object. Items with `blockers` are
+ * reported but never acted on. Items with `requiresConfirmation` need the
+ * named flag (or an interactive yes) on top of their tier being selected.
+ */
+
+export const TIERS = ['safe', 'moderate', 'aggressive'];
+
+/**
+ * @param {string} tier
+ * @returns {number} 0 for safe, 1 for moderate, 2 for aggressive
+ */
+export function tierRank(tier) {
+  const rank = TIERS.indexOf(tier);
+  if (rank === -1) {
+    throw new Error(`Unknown tier: ${tier} (expected ${TIERS.join(', ')})`);
+  }
+  return rank;
+}
+
+/**
+ * Creates an item with defaults filled in.
+ * @param {{id: string, label: string}} env
+ * @param {object} fields
+ */
+export function makeItem(env, fields) {
+  const paths = fields.paths ?? (fields.path ? [fields.path] : []);
+  const item = {
+    id: `${env.id}:${fields.rule}:${fields.path ?? fields.target ?? paths[0] ?? ''}`,
+    env: env.id,
+    envLabel: env.label,
+    kind: 'cache',
+    ecosystem: 'other',
+    rule: 'unknown',
+    description: '',
+    path: paths[0] ?? null,
+    bytes: 0,
+    newestMtimeMs: 0,
+    tier: 'safe',
+    reason: '',
+    blockers: [],
+    requiresConfirmation: null,
+    parentId: null,
+    checks: { busy: [], cwd: null, mtime: true },
+    ...fields,
+  };
+  item.paths = paths;
+  item.action ??= { type: 'remove', paths };
+  return item;
+}
+
+/**
+ * The option that approves an item, as a command-line flag. An unused image
+ * is approved one at a time with `--remove-image REF`.
+ */
+export function consentFlag(item) {
+  if (item.requiresConfirmation === 'removeImages' && item.image) {
+    return `--remove-image ${item.image.ref}`;
+  }
+  const kebab = item.requiresConfirmation.replace(
+    /[A-Z]/g,
+    (letter) => `-${letter.toLowerCase()}`
+  );
+  return `--${kebab}`;
+}
+
+/**
+ * Adds a blocker reason to an item (idempotent).
+ */
+export function block(item, reason) {
+  if (reason && !item.blockers.includes(reason)) {
+    item.blockers.push(reason);
+  }
+  return item;
+}
+
+/**
+ * Totals per tier. Each tier total includes the lower tiers, and nested
+ * items (whose parent is also counted) are not double counted.
+ * @param {object[]} items
+ */
+export function tierTotals(items) {
+  const totals = {};
+  // A tier total is what `clean --tier <tier> --yes` removes: items that
+  // need a per-object flag or an interactive yes are counted apart.
+  const sum = (selected) => ({
+    items: selected.length,
+    bytes: selected.reduce((total, item) => total + item.bytes, 0),
+  });
+  for (const tier of TIERS) {
+    totals[tier] = sum(
+      selectByTier(items, tier, (item) => !item.requiresConfirmation)
+    );
+  }
+  totals.consent = sum(
+    selectByTier(items, 'aggressive', (item) =>
+      Boolean(item.requiresConfirmation)
+    )
+  );
+  totals.blocked = {
+    items: items.filter((item) => item.blockers.length > 0).length,
+    bytes: items
+      .filter((item) => item.blockers.length > 0)
+      .reduce((sum, item) => sum + item.bytes, 0),
+  };
+  return totals;
+}
+
+function parentPath(target) {
+  let end = target.length;
+  while (end > 0 && (target[end - 1] === '/' || target[end - 1] === '\\')) {
+    end--;
+  }
+  const trimmed = target.slice(0, end);
+  const index = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+  return index > 0 ? trimmed.slice(0, index) : null;
+}
+
+/**
+ * Drops items contained in another item of the same environment: by
+ * `parentId`, or because every path lies below another item's path.
+ * @param {object[]} items
+ */
+export function dropNested(items) {
+  const ids = new Set(items.map((item) => item.id));
+  const paths = new Set(
+    items
+      .filter((item) => item.action?.type === 'remove')
+      .flatMap((item) => item.paths.map((p) => `${item.env}\0${p}`))
+  );
+  const inside = (item, target) => {
+    for (let dir = parentPath(target); dir; dir = parentPath(dir)) {
+      if (paths.has(`${item.env}\0${dir}`)) {
+        return true;
+      }
+    }
+    return false;
+  };
+  return items.filter(
+    (item) =>
+      !(item.parentId && ids.has(item.parentId)) &&
+      !(item.paths.length > 0 && item.paths.every((p) => inside(item, p)))
+  );
+}
+
+/**
+ * Items at or below `maxTier` without blockers, dropping items nested in
+ * another selected item.
+ * @param {object[]} items
+ * @param {string} maxTier
+ * @param {(item: object) => boolean} [accept] extra filter
+ */
+export function selectByTier(items, maxTier, accept = () => true) {
+  const rank = tierRank(maxTier);
+  return dropNested(
+    items.filter(
+      (item) =>
+        tierRank(item.tier) <= rank &&
+        item.blockers.length === 0 &&
+        accept(item)
+    )
+  );
+}

package/src/liveness.js

@@ -0,0 +1,190 @@
+/**
+ * Liveness checks: is anything using a path right now?
+ *
+ * Three independent signals, any of which blocks deletion:
+ * - recent writes: newest file mtime inside the stale-age window;
+ * - a relevant tool is running (by process name), optionally only when its
+ *   working directory is inside the project;
+ * - a process holds a file, working directory, or executable inside the path
+ *   (`/proc/<pid>/{fd,cwd,exe}` on Linux, `lsof` on macOS).
+ *
+ * The cleaner refreshes the probe right before acting on each item.
+ */
+
+import { isWithin } from './paths.js';
+import { formatDuration } from './units.js';
+
+const PROC_COMM_LIMIT = 15;
+
+function nameMatches(name, candidate) {
+  return (
+    name === candidate ||
+    (name.length === PROC_COMM_LIMIT &&
+      candidate.startsWith(name) &&
+      candidate.length > PROC_COMM_LIMIT)
+  );
+}
+
+/**
+ * Name of `proc` that matches one of `names`, or null. Besides the kernel
+ * name (`comm`, which programs may rename: Node.js calls its main thread
+ * `MainThread`), processes carry `aliases`: the executable and `argv[0]`
+ * base names.
+ */
+export function matchingName(proc, names) {
+  const own = [proc.name ?? '', ...(proc.aliases ?? [])];
+  for (const name of own) {
+    if (name && names.some((candidate) => nameMatches(name, candidate))) {
+      return name;
+    }
+  }
+  const commandWords = (proc.command ?? '').toLowerCase().split(/[^a-z0-9_-]+/);
+  for (const candidate of names) {
+    if (commandWords.includes(candidate.toLowerCase())) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+export class LivenessProbe {
+  /**
+   * @param {object} env environment adapter
+   * @param {{staleAgeMs: number, now?: () => number, refreshMs?: number}} options
+   */
+  constructor(env, { staleAgeMs, now = () => Date.now(), refreshMs = 2000 }) {
+    this.env = env;
+    this.staleAgeMs = staleAgeMs;
+    this.now = now;
+    this.refreshMs = refreshMs;
+    this.refreshedAt = -Infinity;
+    this.processes = [];
+    this.openPaths = null;
+    this.probeError = false;
+    this.realPaths = new Map();
+  }
+
+  async refresh(force = false) {
+    if (!force && this.now() - this.refreshedAt < this.refreshMs) {
+      return;
+    }
+    const processes = await this.env.processes().catch(() => null);
+    this.listed = processes !== null;
+    this.processes = processes ?? [];
+    this.openPaths = await this.env.openPaths().catch(() => null);
+    this.probeError =
+      (processes === null || this.openPaths === null) &&
+      (this.env.platform === 'linux' || this.env.platform === 'darwin');
+    this.refreshedAt = this.now();
+  }
+
+  /** Processes of the last refresh, or null when they could not be listed. */
+  processList() {
+    return this.listed ? this.processes : null;
+  }
+
+  /**
+   * Resolves symlinks in `paths` (cached), because processes report the
+   * paths they hold open with symlinks resolved: a scan of `/var/folders`
+   * on macOS must match `lsof` output under `/private/var/folders`.
+   * @param {string[]} paths
+   */
+  async resolve(paths) {
+    if (typeof this.env.realPath !== 'function') {
+      return;
+    }
+    for (const target of paths) {
+      if (!this.realPaths.has(target)) {
+        this.realPaths.set(target, await this.env.realPath(target));
+      }
+    }
+  }
+
+  recentWrite(newestMtimeMs) {
+    if (!newestMtimeMs || this.staleAgeMs <= 0) {
+      return null;
+    }
+    const age = this.now() - newestMtimeMs;
+    if (age < this.staleAgeMs) {
+      return `modified ${formatDuration(Math.max(age, 0))} ago, inside the ${formatDuration(this.staleAgeMs)} activity window`;
+    }
+    return null;
+  }
+
+  runningTool(names, cwd) {
+    if (!names || names.length === 0) {
+      return null;
+    }
+    const pathApi = this.env.path;
+    for (const proc of this.processes) {
+      const name = matchingName(proc, names);
+      if (!name) {
+        continue;
+      }
+      if (!cwd) {
+        return `${name} is running (pid ${proc.pid})`;
+      }
+      if (!proc.cwd) {
+        return `${name} is running (pid ${proc.pid}, working directory unknown)`;
+      }
+      if (isWithin(proc.cwd, cwd, pathApi)) {
+        return `${name} is running in ${proc.cwd} (pid ${proc.pid})`;
+      }
+    }
+    return null;
+  }
+
+  openInside(paths) {
+    if (!this.openPaths || paths.length === 0) {
+      return null;
+    }
+    const pathApi = this.env.path;
+    const targets = paths.flatMap((target) => {
+      const real = this.realPaths.get(target);
+      return real && real !== target ? [target, real] : [target];
+    });
+    for (const open of this.openPaths) {
+      for (const target of targets) {
+        if (isWithin(open, target, pathApi)) {
+          return `in use: ${open}`;
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Paths of `paths` that a process holds open, with the reason.
+   * @param {string[]} paths
+   * @returns {Map<string, string>}
+   */
+  openPathsOf(paths) {
+    const open = new Map();
+    for (const target of paths) {
+      const reason = this.openInside([target]);
+      if (reason) {
+        open.set(target, reason);
+      }
+    }
+    return open;
+  }
+
+  /**
+   * First reason the item is busy, or null when it is idle. Items with
+   * `checks.perPath` leave open files to `openPathsOf`: the caller skips
+   * those paths and keeps the item.
+   * @param {object} item
+   */
+  busyReason(item) {
+    const checks = item.checks ?? {};
+    const paths = checks.perPath ? [] : (item.paths ?? []);
+    return (
+      (this.probeError
+        ? 'cannot verify process and open-file activity'
+        : null) ??
+      (checks.mtime === false ? null : this.recentWrite(item.newestMtimeMs)) ??
+      this.runningTool(checks.busy, checks.cwd) ??
+      this.openInside(paths)
+    );
+  }
+}