disk-space-saviour 0.0.0-stage → 0.11.30

package/src/options.js

@@ -0,0 +1,112 @@
+/**
+ * Option defaults and normalization shared by `scan()`, `clean()` and
+ * `emergency()`. Sizes and durations accept numbers (bytes, milliseconds)
+ * or strings (`512M`, `1h`).
+ */
+
+import { parseDuration, parsePercent, parseSize } from './units.js';
+
+export const DEFAULTS = {
+  roots: null,
+  maxDepth: 6,
+  staleAge: '1h',
+  inactive: '30d',
+  minSize: '1M',
+  host: true,
+  docker: null,
+  dockerDepth: 3,
+  containers: [],
+  scanners: ['projects', 'global', 'versions', 'agents', 'system'],
+  only: [],
+  exclude: [],
+  includeVolumes: false,
+  removeStoppedContainers: false,
+  removeContainers: [],
+  removeImages: [],
+  allowDirtyRepos: false,
+  allowDirtyContainers: [],
+  noNative: false,
+  journalKeep: '512M',
+  tier: 'safe',
+  yes: false,
+  backupDir: null,
+  auditDir: null,
+};
+
+function toBytes(value) {
+  return typeof value === 'number' ? value : parseSize(value);
+}
+
+function toMs(value) {
+  return typeof value === 'number' ? value : parseDuration(value);
+}
+
+function toList(value) {
+  if (value === null || value === undefined || value === '') {
+    return [];
+  }
+  return (Array.isArray(value) ? value : [value])
+    .flatMap((entry) => String(entry).split(','))
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Normalizes user options. `olderThan` is an alias of `staleAge`.
+ * @param {object} [input]
+ * @returns {object}
+ */
+export function resolveOptions(input = {}) {
+  if (input.removeUnusedImages) {
+    throw new Error(
+      '--remove-unused-images is not supported: approve each image with --remove-image REF'
+    );
+  }
+  const merged = { ...DEFAULTS };
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) {
+      merged[key] = value;
+    }
+  }
+  const staleAge = input.olderThan ?? merged.staleAge;
+  const roots = toList(merged.roots);
+  return {
+    ...merged,
+    roots: roots.length > 0 ? roots : null,
+    maxDepth: Number(merged.maxDepth),
+    dockerDepth: Number(merged.dockerDepth),
+    staleAgeMs: toMs(staleAge),
+    inactiveMs: toMs(merged.inactive),
+    minSizeBytes: toBytes(merged.minSize),
+    journalKeepBytes: toBytes(merged.journalKeep),
+    containerFilter: toList(merged.containers),
+    allowDirtyContainers: toList(merged.allowDirtyContainers),
+    removeContainers: toList(merged.removeContainers),
+    removeImages: toList(merged.removeImages),
+    scanners: toList(merged.scanners),
+    only: toList(merged.only),
+    exclude: toList(merged.exclude),
+    now: merged.now ?? (() => Date.now()),
+  };
+}
+
+/**
+ * Parses an emergency goal: `free` (bytes to free, `20G`) and/or `until`
+ * (target used percentage, `80%`).
+ * @returns {{freeBytes: number|null, untilPercent: number|null}}
+ */
+export function resolveGoal({ free, until } = {}) {
+  const goal = {
+    freeBytes: free === undefined || free === null ? null : toBytes(free),
+    untilPercent:
+      until === undefined || until === null
+        ? null
+        : typeof until === 'number'
+          ? until
+          : parsePercent(until),
+  };
+  if (goal.freeBytes === null && goal.untilPercent === null) {
+    throw new Error('emergency needs a goal: --free <size> or --until <N%>');
+  }
+  return goal;
+}

package/src/paths.js

@@ -0,0 +1,182 @@
+/**
+ * Path helpers shared by the local and remote (container) environments.
+ */
+
+const globCache = new Map();
+
+/**
+ * Converts a basename glob (`*`, `?`, `[...]`) to a RegExp.
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+export function globToRegExp(glob) {
+  let cached = globCache.get(glob);
+  if (!cached) {
+    let source = '';
+    for (const char of glob) {
+      if (char === '*') {
+        source += '[^/\\\\]*';
+      } else if (char === '?') {
+        source += '[^/\\\\]';
+      } else if (char === '[' || char === ']') {
+        source += char;
+      } else {
+        source += char.replace(/[.+^${}()|\\]/g, '\\$&');
+      }
+    }
+    cached = new RegExp(`^${source}$`);
+    globCache.set(glob, cached);
+  }
+  return cached;
+}
+
+/**
+ * @param {string} name
+ * @param {string} glob
+ */
+export function matchesGlob(name, glob) {
+  return globToRegExp(glob).test(name);
+}
+
+/**
+ * Whether `child` equals `parent` or lies below it.
+ * @param {string} child
+ * @param {string} parent
+ * @param {{sep: string}} pathApi node:path flavour used by the environment
+ */
+export function isWithin(child, parent, pathApi) {
+  if (!child || !parent) {
+    return false;
+  }
+  const normalize = (value) =>
+    pathApi.sep === '\\' ? value.toLowerCase() : value;
+  const c = normalize(pathApi.resolve(child));
+  const p = normalize(pathApi.resolve(parent));
+  if (c === p) {
+    return true;
+  }
+  const prefix = p.endsWith(pathApi.sep) ? p : p + pathApi.sep;
+  return c.startsWith(prefix);
+}
+
+/**
+ * Expands `~` and `{VAR}` tokens of a rule path for one home directory.
+ * Returns null when a referenced variable is not set.
+ * @param {string} pattern
+ * @param {{home: string, vars?: Record<string,string|undefined>, pathApi: object}} context
+ */
+export function expandRulePath(pattern, { home, vars = {}, pathApi }) {
+  let missing = false;
+  let expanded = pattern.replace(/\{([A-Z_]+)\}/g, (_, name) => {
+    const value = vars[name];
+    if (!value) {
+      missing = true;
+      return '';
+    }
+    return value;
+  });
+  if (missing) {
+    return null;
+  }
+  if (expanded === '~') {
+    expanded = home;
+  } else if (expanded.startsWith('~/')) {
+    expanded = pathApi.join(home, expanded.slice(2));
+  }
+  return pathApi.normalize(expanded);
+}
+
+/**
+ * Expands glob segments (`*`) in an absolute path by listing directories.
+ * @param {object} env environment adapter
+ * @param {string} pattern absolute path that may contain glob segments
+ * @returns {Promise<string[]>}
+ */
+export async function expandGlobPath(env, pattern) {
+  return (await expandGlobPaths(env, [pattern])).get(pattern) ?? [];
+}
+
+const GLOB_CHARS = /[*?[]/;
+
+async function listDirs(env, dirs) {
+  if (typeof env.listMany === 'function') {
+    return env.listMany(dirs);
+  }
+  const listings = await Promise.all(dirs.map((dir) => env.list(dir)));
+  return new Map(dirs.map((dir, index) => [dir, listings[index]]));
+}
+
+/**
+ * Paths among `targets` that exist, checked in one batch when the
+ * environment supports it.
+ * @returns {Promise<Set<string>>}
+ */
+export async function existingPaths(env, targets) {
+  if (typeof env.existsMany === 'function') {
+    return env.existsMany(targets);
+  }
+  const flags = await Promise.all(targets.map((target) => env.exists(target)));
+  return new Set(targets.filter((_, index) => flags[index]));
+}
+
+function globState(pathApi, pattern) {
+  if (!GLOB_CHARS.test(pattern)) {
+    return { pattern, segments: [], current: [pattern] };
+  }
+  const root = pathApi.parse(pattern).root;
+  const segments = pattern
+    .slice(root.length)
+    .split(/[\\/]+/)
+    .filter(Boolean);
+  return { pattern, segments, current: [root] };
+}
+
+function advance(state, segment, listings, pathApi) {
+  if (!GLOB_CHARS.test(segment)) {
+    return state.current.map((base) => pathApi.join(base, segment));
+  }
+  return state.current.flatMap((base) =>
+    (listings.get(base) ?? [])
+      .filter((entry) => matchesGlob(entry.name, segment))
+      .map((entry) => pathApi.join(base, entry.name))
+  );
+}
+
+/**
+ * Expands many absolute path patterns (glob segments allowed) with one
+ * listing round per path depth and one existence check.
+ * @param {object} env environment adapter
+ * @param {string[]} patterns
+ * @returns {Promise<Map<string, string[]>>} existing matches per pattern
+ */
+export async function expandGlobPaths(env, patterns) {
+  const pathApi = env.path;
+  const states = [...new Set(patterns)].map((p) => globState(pathApi, p));
+  for (let step = 0; ; step++) {
+    const active = states.filter(
+      (state) => step < state.segments.length && state.current.length > 0
+    );
+    if (active.length === 0) {
+      break;
+    }
+    const toList = new Set(
+      active
+        .filter((state) => GLOB_CHARS.test(state.segments[step]))
+        .flatMap((state) => state.current)
+    );
+    const listings =
+      toList.size > 0 ? await listDirs(env, [...toList]) : new Map();
+    for (const state of active) {
+      state.current = advance(state, state.segments[step], listings, pathApi);
+    }
+  }
+  const existing = await existingPaths(env, [
+    ...new Set(states.flatMap((state) => state.current)),
+  ]);
+  return new Map(
+    states.map((state) => [
+      state.pattern,
+      state.current.filter((target) => existing.has(target)),
+    ])
+  );
+}

package/src/report.js

@@ -0,0 +1,373 @@
+/**
+ * Human-readable rendering of scan reports and audit logs. The JSON forms
+ * (`--json`) are the report and audit objects themselves.
+ */
+
+import { TIERS, consentFlag } from './items.js';
+import { formatBytes } from './units.js';
+
+const DEFAULT_LIMIT = 25;
+
+function plural(count, noun) {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+function manyEnvironments(report) {
+  return new Set(report.items.map((item) => item.env)).size > 1;
+}
+
+function pad(text, width) {
+  return String(text).padStart(width);
+}
+
+function percentUsed(disk) {
+  const total = disk.used + disk.free;
+  return total > 0 ? Math.round((disk.used / total) * 100) : 0;
+}
+
+/**
+ * One line describing the free space of a volume.
+ */
+export function formatDisk(disk, label = '') {
+  if (!disk) {
+    return `${label}free space unknown`;
+  }
+  const where = disk.path ? `${disk.path}: ` : '';
+  return `${label}${where}${formatBytes(disk.free)} free of ${formatBytes(
+    disk.used + disk.free
+  )} (${percentUsed(disk)}% used)`;
+}
+
+function itemLocation(item) {
+  if (item.path) {
+    const more = item.paths.length > 1 ? ` (+${item.paths.length - 1})` : '';
+    return `${item.path}${more}`;
+  }
+  return item.description;
+}
+
+function itemLine(item, showEnv) {
+  const env = showEnv ? `[${item.envLabel}] ` : '';
+  const confirm = item.requiresConfirmation
+    ? `  (needs ${consentFlag(item)})`
+    : '';
+  return `  ${pad(formatBytes(item.bytes), 10)}  ${env}${item.rule}  ${itemLocation(item)}${confirm}`;
+}
+
+function limited(lines, limit) {
+  if (lines.length <= limit) {
+    return lines;
+  }
+  return [
+    ...lines.slice(0, limit),
+    `  … ${lines.length - limit} more (use --verbose or --json)`,
+  ];
+}
+
+function tierSection(report, tier, options) {
+  const items = report.items
+    .filter((item) => item.tier === tier && item.blockers.length === 0)
+    .sort((a, b) => b.bytes - a.bytes);
+  if (items.length === 0) {
+    return [];
+  }
+  const showEnv = manyEnvironments(report);
+  const bytes = items.reduce((sum, item) => sum + item.bytes, 0);
+  return [
+    '',
+    `${tier.toUpperCase()}  ${plural(items.length, 'item')}, ${formatBytes(bytes)}`,
+    ...limited(
+      items.map((item) => itemLine(item, showEnv)),
+      options.limit
+    ),
+  ];
+}
+
+function blockedSection(report, options) {
+  const items = report.items.filter((item) => item.blockers.length > 0);
+  if (items.length === 0) {
+    return [];
+  }
+  const lines = [];
+  for (const item of items.sort((a, b) => b.bytes - a.bytes)) {
+    lines.push(itemLine(item, manyEnvironments(report)));
+    for (const blocker of item.blockers) {
+      lines.push(`      blocked: ${blocker}`);
+    }
+  }
+  return [
+    '',
+    `BLOCKED  ${plural(items.length, 'item')} (kept)`,
+    ...limited(lines, options.limit * 2),
+  ];
+}
+
+function repoSummary(repo) {
+  if (repo.error) {
+    return `${repo.root}: ${repo.error}`;
+  }
+  const parts = [];
+  if (repo.dirty) {
+    parts.push(`${repo.dirty} uncommitted`);
+  }
+  if (repo.unpushed) {
+    parts.push(`${repo.unpushed} unpushed`);
+  }
+  if (repo.stashes) {
+    parts.push(`${repo.stashes} stashed`);
+  }
+  return `${repo.root}: ${parts.length > 0 ? parts.join(', ') : 'clean and pushed'}`;
+}
+
+/** Exit code, OOM flag, end time and task of a stopped container. */
+function endedLine(owner) {
+  if (!owner || owner.exitCode === null || owner.exitCode === undefined) {
+    return null;
+  }
+  const parts = [
+    `exit ${owner.exitCode}${owner.exitReason ? ` (${owner.exitReason})` : ''}`,
+  ];
+  if (owner.oomKilled) {
+    parts.push('OOM killed');
+  }
+  if (owner.finishedAt) {
+    parts.push(`ended ${owner.finishedAt}`);
+  }
+  if (owner.taskUrl) {
+    parts.push(`task ${owner.taskUrl}`);
+  }
+  return parts.join(', ');
+}
+
+function containerLines(container, stoppedItems) {
+  const session = container.owner?.session
+    ? `session ${container.owner.session}`
+    : 'no session label';
+  const scanned = container.scanned ? ', scanned via exec' : '';
+  const lines = [
+    `  ${container.name} (${container.id.slice(0, 12)}) ${container.state}, ${container.image}, ${formatBytes(container.bytes)} written, ${session}${scanned}`,
+  ];
+  if (container.note) {
+    lines.push(`      ${container.note}`);
+  }
+  const ended = endedLine(container.owner);
+  if (ended) {
+    lines.push(`      ${ended}`);
+  }
+  const item = stoppedItems.get(container.id);
+  if (item?.container?.investigation) {
+    lines.push(`      ${item.container.investigation}`);
+  }
+  for (const repo of item?.container?.repos ?? []) {
+    lines.push(`      git ${repoSummary(repo)}`);
+  }
+  return lines;
+}
+
+function lastUseText(user) {
+  if (!user) {
+    return 'last use unknown';
+  }
+  const details = [
+    user.session && `session ${user.session}`,
+    user.taskUrl && `task ${user.taskUrl}`,
+    user.finishedAt && `ended ${user.finishedAt}`,
+  ].filter(Boolean);
+  const more = details.length > 0 ? ` (${details.join(', ')})` : '';
+  return `last used by container ${user.container}${more}`;
+}
+
+/** Size, creation date, last user and the flag of an unused image. */
+function imageLine(item) {
+  const { image } = item;
+  const created = image.createdAt ? `created ${image.createdAt}, ` : '';
+  const consent = item.requiresConfirmation
+    ? `, needs ${consentFlag(item)}`
+    : '';
+  return `  image ${image.ref} (${String(image.id)
+    .replace(/^sha256:/, '')
+    .slice(
+      0,
+      12
+    )}) unused, ${formatBytes(image.bytes)}, ${created}${lastUseText(image.lastUsedBy)}${consent}`;
+}
+
+function dockerSection(report) {
+  const docker = report.docker;
+  if (!docker || docker.daemons.length === 0) {
+    return [];
+  }
+  const stoppedItems = new Map(
+    report.items
+      .filter((item) => item.container)
+      .map((item) => [item.container.id, item])
+  );
+  const lines = ['', 'DOCKER'];
+  for (const daemon of docker.daemons) {
+    lines.push(
+      `  daemon ${daemon.name} (depth ${daemon.depth}, ${daemon.serverVersion}, ${daemon.driver}) via ${daemon.env}`
+    );
+  }
+  for (const container of docker.containers) {
+    lines.push(...containerLines(container, stoppedItems));
+  }
+  for (const item of report.items.filter((entry) => entry.image)) {
+    lines.push(imageLine(item));
+  }
+  for (const hint of docker.hints ?? []) {
+    lines.push(
+      `  hint ${hint.image}: ${formatBytes(hint.bytes)} layer, ${hint.hint}`
+    );
+  }
+  for (const volume of docker.volumes ?? []) {
+    lines.push(
+      `  volume ${volume.name}: ${formatBytes(volume.bytes)}, ${volume.note}`
+    );
+  }
+  return lines;
+}
+
+function totalsSection(report) {
+  const parts = TIERS.map(
+    (tier) => `${tier} ${formatBytes(report.totals[tier].bytes)}`
+  );
+  return [
+    '',
+    `Reclaimable (cumulative): ${parts.join(' · ')}; blocked ${formatBytes(report.totals.blocked.bytes)}`,
+  ];
+}
+
+function errorsSection(errors) {
+  if (!errors || errors.length === 0) {
+    return [];
+  }
+  return [
+    '',
+    'ERRORS',
+    ...errors.map(
+      (error) => `  ${error.env} ${error.scanner}: ${error.message}`
+    ),
+  ];
+}
+
+/**
+ * Renders a scan report.
+ * @param {object} report
+ * @param {{verbose?: boolean}} [options]
+ * @returns {string}
+ */
+export function formatReport(report, options = {}) {
+  const limit = options.verbose ? Infinity : DEFAULT_LIMIT;
+  const host = report.environments[0];
+  const lines = [
+    `disk-space-saviour scan of ${host.label} in ${(report.durationMs / 1000).toFixed(1)}s (report only, nothing was deleted)`,
+    formatDisk(host.disk),
+  ];
+  for (const tier of TIERS) {
+    lines.push(...tierSection(report, tier, { limit }));
+  }
+  lines.push(...blockedSection(report, { limit }));
+  lines.push(...dockerSection(report));
+  lines.push(...errorsSection(report.errors));
+  lines.push(...totalsSection(report));
+  return lines.join('\n');
+}
+
+function entryLine(entry) {
+  const bytes =
+    entry.status === 'removed' ? entry.freedBytes : entry.plannedBytes;
+  const size = entry.status === 'skipped' ? '' : formatBytes(bytes ?? 0);
+  const reason = entry.reason ? `  (${entry.reason})` : '';
+  const location = entry.path ?? entry.description;
+  return `  ${entry.status.padEnd(7)} ${pad(size, 10)}  ${entry.rule}  ${location}${reason}`;
+}
+
+function statusCounts(env) {
+  return ['removed', 'planned', 'skipped', 'failed']
+    .filter((status) => env[status] > 0)
+    .map((status) => `${env[status]} ${status}`)
+    .join(', ');
+}
+
+function environmentLines(environments) {
+  return Object.values(environments ?? {}).map(
+    (env) =>
+      `  ${env.label}: freed ${formatBytes(env.freedBytes)}, left ${formatBytes(env.leftBytes)} (${statusCounts(env)})`
+  );
+}
+
+/**
+ * Whether the watched long-running processes survived, per environment.
+ */
+function healthLines(records) {
+  const lines = (records ?? []).map((record) => {
+    if (record.stopped) {
+      return `  ${record.envLabel}: STOPPED cleaning: ${record.stopped}`;
+    }
+    if (!record.available) {
+      return `  ${record.envLabel}: processes could not be listed`;
+    }
+    return `  ${record.envLabel}: ${record.watched.length} watched processes still running`;
+  });
+  return lines.length > 0 ? ['', 'Task health:', ...lines] : [];
+}
+
+function emergencyLines(audit) {
+  if (audit.command !== 'emergency') {
+    return [];
+  }
+  const goal = [
+    audit.goal.freeBytes === null
+      ? null
+      : `${formatBytes(audit.goal.freeBytes)} free`,
+    audit.goal.untilPercent === null
+      ? null
+      : `at most ${audit.goal.untilPercent}% used`,
+  ]
+    .filter(Boolean)
+    .join(' and ');
+  return [
+    `goal: ${goal} on ${audit.path}`,
+    formatDisk(audit.diskBefore, 'before: '),
+    formatDisk(
+      audit.diskAfter,
+      audit.dryRun ? 'after (estimated): ' : 'after: '
+    ),
+    `goal ${audit.goalMet ? 'met' : 'NOT met'}, highest tier used: ${audit.reachedTier ?? 'none'}`,
+  ];
+}
+
+/**
+ * Renders the audit log of `clean` or `emergency`.
+ * @param {object} audit
+ * @param {{verbose?: boolean}} [options]
+ */
+export function formatAudit(audit, options = {}) {
+  const limit = options.verbose ? Infinity : DEFAULT_LIMIT * 2;
+  const mode = audit.dryRun ? 'dry run, nothing was deleted' : 'deleting';
+  const shown = options.verbose
+    ? audit.entries
+    : audit.entries.filter((entry) => entry.status !== 'skipped');
+  const hidden = audit.entries.length - shown.length;
+  const lines = [
+    `disk-space-saviour ${audit.command} (${mode})`,
+    ...emergencyLines(audit),
+    '',
+    ...limited(shown.map(entryLine), limit),
+  ];
+  if (hidden > 0) {
+    lines.push(`  ${hidden} skipped (use --verbose to list them)`);
+  }
+  lines.push('', 'Per environment:', ...environmentLines(audit.environments));
+  lines.push(...healthLines(audit.health));
+  lines.push(
+    '',
+    audit.dryRun
+      ? `Would free ${formatBytes(audit.plannedBytes)} (run with --yes to delete)`
+      : `Freed ${formatBytes(audit.freedBytes)}`
+  );
+  if (audit.file) {
+    lines.push(`Audit log: ${audit.file}`);
+  }
+  return lines.join('\n');
+}