disk-space-saviour 0.0.0-stage → 0.12.0

package/src/scan.js

@@ -0,0 +1,384 @@
+/**
+ * `scan(options) → Report`: finds reclaimable space on the host and, through
+ * Docker, inside running containers and nested daemons. Never deletes.
+ */
+
+import { scanDocker } from './docker/scan.js';
+import { LocalEnv } from './env/local.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, matchesGlob } from './paths.js';
+import { scanAgents } from './scanners/agents.js';
+import { scanGlobal } from './scanners/global.js';
+import { scanProjects } from './scanners/projects.js';
+import { scanSystem } from './scanners/system.js';
+import { scanVersions } from './scanners/versions.js';
+
+export const SCANNERS = {
+  projects: scanProjects,
+  global: scanGlobal,
+  versions: scanVersions,
+  agents: scanAgents,
+  system: scanSystem,
+};
+
+export const REPORT_SCHEMA = 1;
+const trustedReports = new WeakMap();
+const RESCAN_OPTIONS = new Set([
+  'roots',
+  'scanners',
+  'containers',
+  'host',
+  'docker',
+  'dockerDepth',
+  'maxDepth',
+  'staleAge',
+  'olderThan',
+  'inactive',
+  'minSize',
+  'only',
+  'exclude',
+  'includeVolumes',
+  'removeStoppedContainers',
+  'removeContainers',
+  'removeImages',
+  'allowDirtyRepos',
+  'allowDirtyContainers',
+  'noNative',
+  'journalKeep',
+  'env',
+  'now',
+]);
+
+function safetySnapshot(report) {
+  return JSON.stringify(report);
+}
+
+function sealReport(report) {
+  trustedReports.set(report, safetySnapshot(report));
+  return report;
+}
+
+/** Rebuild scanner-derived actions when a report came from JSON or changed. */
+export async function revalidateReport(saved, input = {}) {
+  if (trustedReports.get(saved) === safetySnapshot(saved)) {
+    return saved;
+  }
+  const scope = {
+    roots: saved.options?.roots,
+    scanners: saved.options?.scanners,
+    containers: saved.options?.containers,
+    host: saved.options?.host,
+    docker: saved.options?.docker,
+    dockerDepth: saved.options?.dockerDepth,
+    maxDepth: saved.options?.maxDepth,
+  };
+  for (const [key, value] of Object.entries(input)) {
+    if (RESCAN_OPTIONS.has(key) && value !== undefined && value !== null) {
+      scope[key] = value;
+    }
+  }
+  const current = await scan(scope);
+  const selected = new Set((saved.items ?? []).map((item) => item.id));
+  current.items = current.items.filter((item) => selected.has(item.id));
+  current.totals = tierTotals(current.items);
+  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)];
+}
+
+/**
+ * Builds the scanner context of one environment.
+ * @param {object} env environment adapter
+ * @param {object} options resolved options
+ * @param {{roots?: string[]|null}} [overrides]
+ */
+export async function environmentContext(env, options, overrides = {}) {
+  const liveness = new LivenessProbe(env, {
+    staleAgeMs: options.staleAgeMs,
+    now: options.now,
+  });
+  await liveness.refresh(true);
+  const homes = await env.homeDirs();
+  const tmpDirs = await env.tmpDirs();
+  const roots = overrides.roots ?? (await defaultRoots(env, homes, tmpDirs));
+  return {
+    env,
+    git: new GitInspector(env),
+    liveness,
+    now: options.now(),
+    options: { ...options, homes, tmpDirs, roots },
+  };
+}
+
+/**
+ * Runs every enabled scanner in one environment.
+ * @param {object} env
+ * @param {object} options resolved options
+ * @param {{roots?: string[]|null, errors?: object[]}} [extra]
+ * @returns {Promise<object[]>} items
+ */
+export async function scanEnvironment(env, options, extra = {}) {
+  const errors = extra.errors ?? [];
+  let context;
+  try {
+    context = await environmentContext(env, options, extra);
+  } catch (error) {
+    errors.push({ env: env.id, scanner: 'context', message: error.message });
+    return [];
+  }
+  const items = [];
+  for (const name of options.scanners) {
+    const scanner = SCANNERS[name];
+    if (!scanner) {
+      throw new Error(
+        `Unknown scanner: ${name} (expected ${Object.keys(SCANNERS).join(', ')})`
+      );
+    }
+    const started = Date.now();
+    try {
+      items.push(...(await scanner(context)));
+    } catch (error) {
+      errors.push({ env: env.id, scanner: name, message: error.message });
+    }
+    trace('scanner', name, 'in', env.id, `${Date.now() - started}ms`);
+  }
+  return items;
+}
+
+/**
+ * Container ids of the container dss itself runs in (from mount sources
+ * such as `/var/lib/docker/containers/<id>/hostname`).
+ * @returns {Promise<string[]>}
+ */
+export async function selfContainerIds(env) {
+  if (env.platform !== 'linux') {
+    return [];
+  }
+  const ids = new Set();
+  const pattern = /(?:containers\/|docker[-/])([0-9a-f]{64})/g;
+  const cgroup =
+    (await env.readText('/proc/self/cgroup').catch(() => null)) ?? '';
+  for (const match of cgroup.matchAll(pattern)) {
+    ids.add(match[1]);
+  }
+  const mounts =
+    (await env.readText('/proc/self/mountinfo').catch(() => null)) ?? '';
+  for (const line of mounts.split('\n')) {
+    const mountpoint = line.split(' ')[4];
+    if (
+      !['/etc/hostname', '/etc/hosts', '/etc/resolv.conf'].includes(mountpoint)
+    ) {
+      continue;
+    }
+    for (const match of line.matchAll(pattern)) {
+      ids.add(match[1]);
+    }
+  }
+  return [...ids];
+}
+
+function matchesOnly(item, only) {
+  return (
+    only.length === 0 ||
+    only.some(
+      (entry) =>
+        entry === item.ecosystem || entry === item.rule || entry === item.kind
+    )
+  );
+}
+
+function excluded(item, exclude, pathApi) {
+  return item.paths.some((target) =>
+    exclude.some(
+      (pattern) =>
+        isWithin(target, pattern, pathApi) ||
+        isWithin(pattern, target, pathApi) ||
+        matchesGlob(pathApi.basename(target), pattern)
+    )
+  );
+}
+
+function underDaemonRoot(item, daemons, pathApi) {
+  return daemons.some(
+    (daemon) =>
+      daemon.env === item.env &&
+      daemon.rootDir &&
+      item.action?.type === 'remove' &&
+      item.paths.some((target) => isWithin(target, daemon.rootDir, pathApi))
+  );
+}
+
+/**
+ * Applies `only`, `exclude` and `minSize`, and drops paths owned by a
+ * Docker daemon (those are reclaimed through Docker only).
+ */
+export function filterItems(items, options, daemons = [], pathApi) {
+  return items.filter(
+    (item) =>
+      item.bytes >= options.minSizeBytes &&
+      matchesOnly(item, options.only) &&
+      !excluded(item, options.exclude, pathApi) &&
+      !underDaemonRoot(item, daemons, pathApi)
+  );
+}
+
+function envDescriptor(env, depth, chain) {
+  return { id: env.id, label: env.label, kind: env.kind, depth, chain };
+}
+
+async function withDisk(env, descriptor) {
+  const target = env.platform === 'win32' ? env.currentHome : '/';
+  const disk = await env.diskUsage(target).catch(() => null);
+  return { ...descriptor, disk: disk ? { path: target, ...disk } : null };
+}
+
+async function dockerSection(env, options, errors) {
+  if (options.docker === false) {
+    return null;
+  }
+  const hostRecord = {
+    env,
+    executor: env.executor ?? hostExecutor(),
+    chain: [],
+  };
+  try {
+    const result = await scanDocker(
+      hostRecord,
+      { ...options, selfContainerIds: await selfContainerIds(env) },
+      (inner) => scanEnvironment(inner, options, { errors })
+    );
+    if (options.docker === true && result.daemons.length === 0) {
+      errors.push({
+        env: env.id,
+        scanner: 'docker',
+        message: 'no reachable Docker daemon',
+      });
+    }
+    return result;
+  } catch (error) {
+    errors.push({ env: env.id, scanner: 'docker', message: error.message });
+    return null;
+  }
+}
+
+/**
+ * Scans and returns a report. Nothing is modified.
+ * @param {object} [input] options, see ./options.js; `host: false` skips the
+ *   host file system (Docker only); `env` injects the host environment
+ *   adapter (tests).
+ * @returns {Promise<object>} report
+ */
+function blockMountedHostItems(items, mounts, pathApi) {
+  for (const item of items) {
+    if (item.action?.type !== 'remove') {
+      continue;
+    }
+    for (const mount of mounts) {
+      if (
+        item.paths.some(
+          (target) =>
+            isWithin(target, mount.source, pathApi) ||
+            isWithin(mount.source, target, pathApi)
+        )
+      ) {
+        block(item, `bind-mounted by running container ${mount.containerId}`);
+      }
+    }
+  }
+}
+
+export async function scan(input = {}) {
+  const options = resolveOptions(input);
+  const env = input.env ?? new LocalEnv();
+  const startedAt = options.now();
+  const errors = [];
+  const hostItems =
+    options.host === false
+      ? []
+      : await scanEnvironment(env, options, { roots: options.roots, errors });
+  const docker = await dockerSection(env, options, errors);
+  blockMountedHostItems(hostItems, docker?.bindMounts ?? [], env.path);
+  const items = filterItems(
+    [...hostItems, ...(docker?.items ?? [])],
+    options,
+    docker?.daemons ?? [],
+    env.path
+  );
+  const environments = [envDescriptor(env, 0, [])];
+  for (const inner of docker?.environments ?? []) {
+    environments.push(inner);
+  }
+  environments[0] = await withDisk(env, environments[0]);
+  return buildReport({
+    options,
+    env,
+    items,
+    environments,
+    docker,
+    errors,
+    startedAt,
+  });
+}
+
+function reportOptions(options) {
+  const serializable = { ...options };
+  delete serializable.now;
+  delete serializable.env;
+  return serializable;
+}
+
+/**
+ * Assembles the JSON-serializable report.
+ */
+export function buildReport({
+  options,
+  env,
+  items,
+  environments,
+  docker,
+  errors,
+  startedAt,
+}) {
+  return sealReport({
+    schema: REPORT_SCHEMA,
+    tool: 'disk-space-saviour',
+    createdAt: new Date(options.now()).toISOString(),
+    durationMs: options.now() - startedAt,
+    host: { env: env.id, label: env.label, platform: env.platform },
+    options: reportOptions(options),
+    environments,
+    items,
+    totals: tierTotals(items),
+    docker: docker
+      ? {
+          daemons: docker.daemons,
+          containers: docker.containers,
+          hints: docker.hints,
+          volumes: docker.volumes,
+        }
+      : null,
+    errors,
+  });
+}

package/src/scanners/agents.js

@@ -0,0 +1,166 @@
+/**
+ * Snapshot stores of AI coding agents built on the opencode storage layout
+ * (`@link-assistant/agent`, opencode).
+ *
+ * `<data>/snapshot/<projectId>/` is a bare Git object store with a full copy
+ * of the project's worktree, keyed by the project's root commit.
+ * `<data>/storage/project/<projectId>.json` records the project's
+ * `worktree`. Tasks that run the agent in throwaway checkouts leave one
+ * store per checkout behind (link-assistant/hive-mind#2186).
+ *
+ * - worktree recorded and gone: retained because the snapshot may be the only
+ *   remaining copy of uncommitted work;
+ * - no project record and idle for the activity window: `moderate`;
+ * - worktree still present: kept;
+ * - the newest store is always kept.
+ *
+ * Running agents do not block: a store is only written by the agent working
+ * in its worktree, so recent writes and open files are the liveness signal
+ * (the same rule the agent's own `Project.prune()` uses).
+ */
+
+import { block, makeItem } from '../items.js';
+import { listMany, olderThan, scanTimeBusy } from './common.js';
+
+export const AGENT_APPS = [
+  { id: 'link-assistant-agent', name: '@link-assistant/agent' },
+  { id: 'opencode', name: 'opencode' },
+];
+
+function dataDirs(env, home) {
+  const dirs = [env.path.join(home, '.local', 'share')];
+  const xdg = env.vars?.XDG_DATA_HOME;
+  if (home === env.currentHome && xdg && !dirs.includes(xdg)) {
+    dirs.push(xdg);
+  }
+  return dirs;
+}
+
+/**
+ * Reads the recorded worktree from a project record.
+ * @returns {string|null}
+ */
+export function recordedWorktree(text) {
+  try {
+    const worktree = JSON.parse(text ?? '').worktree;
+    return typeof worktree === 'string' && worktree ? worktree : null;
+  } catch {
+    return null;
+  }
+}
+
+async function snapshotStates(env, root) {
+  const snapshotDir = env.path.join(root, 'snapshot');
+  const projectDir = env.path.join(root, 'storage', 'project');
+  const listings = await listMany(env, [snapshotDir, projectDir]);
+  const stores = (listings.get(snapshotDir) ?? []).filter(
+    (entry) => entry.type === 'dir'
+  );
+  if (stores.length === 0) {
+    return [];
+  }
+  const records = new Set(
+    (listings.get(projectDir) ?? []).map((entry) => entry.name)
+  );
+  const recordPath = (id) => env.path.join(projectDir, `${id}.json`);
+  const heads = await env.readHeads(
+    stores
+      .filter((entry) => records.has(`${entry.name}.json`))
+      .map((entry) => recordPath(entry.name)),
+    65536
+  );
+  const states = [];
+  for (const entry of stores) {
+    const record = heads.get(recordPath(entry.name));
+    const worktree = record === undefined ? null : recordedWorktree(record);
+    states.push({
+      entry,
+      hasRecord: record !== undefined,
+      worktree,
+      worktreeExists: worktree ? await env.exists(worktree) : false,
+    });
+  }
+  return states;
+}
+
+function classify(context, state, usage) {
+  if (state.worktreeExists) {
+    return null;
+  }
+  if (state.hasRecord && state.worktree) {
+    return null;
+  }
+  if (olderThan(context, usage.newestMtimeMs, context.options.staleAgeMs)) {
+    return {
+      tier: 'moderate',
+      reason: 'no project record points at this store and it is idle',
+    };
+  }
+  return null;
+}
+
+async function appItems(context, app, root) {
+  const { env } = context;
+  const states = await snapshotStates(env, root);
+  if (states.length === 0) {
+    return [];
+  }
+  const usages = await env.usageMany(states.map((s) => s.entry.path));
+  const newest = states
+    .map((state) => ({
+      state,
+      mtimeMs: usages.get(state.entry.path)?.newestMtimeMs ?? 0,
+    }))
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)[0].state;
+  const items = [];
+  for (const state of states) {
+    const usage = usages.get(state.entry.path);
+    const verdict =
+      state === newest || !usage ? null : classify(context, state, usage);
+    if (!verdict) {
+      continue;
+    }
+    const item = makeItem(env, {
+      rule: 'agent-snapshot',
+      kind: 'agent-state',
+      ecosystem: 'agents',
+      description: `${app.name} snapshot store ${state.entry.name}`,
+      path: state.entry.path,
+      bytes: usage.bytes,
+      newestMtimeMs: usage.newestMtimeMs,
+      worktree: state.worktree,
+      ...verdict,
+      checks: { busy: [], cwd: null, mtime: true },
+    });
+    const busy = scanTimeBusy(context, item);
+    if (busy) {
+      block(item, `busy: ${busy}`);
+    }
+    items.push(item);
+  }
+  return items;
+}
+
+/**
+ * Scans agent snapshot stores of every home.
+ * @returns {Promise<object[]>} report items
+ */
+export async function scanAgents(context, { apps = AGENT_APPS } = {}) {
+  const { env, options } = context;
+  const homes = options.homes ?? (await env.homeDirs());
+  const items = [];
+  const seen = new Set();
+  for (const home of homes) {
+    for (const dataDir of dataDirs(env, home)) {
+      for (const app of apps) {
+        const root = env.path.join(dataDir, app.id);
+        if (seen.has(root)) {
+          continue;
+        }
+        seen.add(root);
+        items.push(...(await appItems(context, app, root)));
+      }
+    }
+  }
+  return items;
+}

package/src/scanners/common.js

@@ -0,0 +1,38 @@
+/**
+ * Helpers shared by scanners.
+ *
+ * Every scanner receives a context:
+ * `{env, git, liveness, options, now}` where `options` holds the resolved
+ * scan options (`staleAgeMs`, `inactiveMs`, `maxDepth`, `roots`, ...).
+ */
+
+/**
+ * Lists many directories, batched when the environment supports it.
+ * @returns {Promise<Map<string, object[]>>}
+ */
+export async function listMany(env, dirs) {
+  if (typeof env.listMany === 'function') {
+    return env.listMany(dirs);
+  }
+  const listings = new Map();
+  for (const dir of dirs) {
+    listings.set(dir, await env.list(dir));
+  }
+  return listings;
+}
+
+/**
+ * Busy reason at scan time (recent writes, running tool, open files).
+ * @returns {string|null}
+ */
+export function scanTimeBusy(context, item) {
+  return context.liveness ? context.liveness.busyReason(item) : null;
+}
+
+/**
+ * Whether `now - timestamp` exceeds `windowMs` (unknown timestamps count as
+ * recent, so they are never treated as abandoned).
+ */
+export function olderThan(context, timestamp, windowMs) {
+  return Boolean(timestamp) && context.now - timestamp >= windowMs;
+}