@git.zone/tsdisk 1.1.0

package/ts/tsdisk.cli.ts

@@ -0,0 +1,1719 @@
+import * as plugins from './tsdisk.plugins.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import {
+  classifyToolCachePath,
+  parseToolCacheMarker,
+  toolCacheMarkerFile,
+  type IToolCacheFinding,
+  type IToolCacheMarker,
+} from './tsdisk.toolcaches.js';
+
+interface ICommandResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+interface IRunOptions {
+  asRoot?: boolean;
+  asTargetUser?: boolean;
+  timeoutSeconds?: number;
+}
+
+export interface IRuntimeContext {
+  runningAsRoot: boolean;
+  sudoAvailable: boolean;
+  sudoChecked: boolean;
+  targetUser: string;
+  targetUid: string;
+  targetHome: string;
+  targetRuntimeDir: string;
+  dockerTimeoutSeconds: number;
+  duTimeoutSeconds: number;
+  ncduTimeoutSeconds: number;
+}
+
+interface IDuEntry {
+  bytes: number;
+  path: string;
+}
+
+interface INcduInsight {
+  bytes: number;
+  path: string;
+  type: 'directory' | 'file';
+  readError: boolean;
+  excluded?: string;
+}
+
+interface INcduParseResult {
+  rootBytes: number;
+  insights: INcduInsight[];
+}
+
+export interface IWorkspaceScanOptions {
+  maxDepth: number;
+  timeoutMs: number;
+  maxEntries: number;
+}
+
+const decoder = new TextDecoder();
+const maxCapturedOutputBytes = 64 * 1024 * 1024;
+const ncduInsightLimit = 30;
+const toolCacheSizingLimit = 500;
+const toolCacheSizingTimeoutMs = 45_000;
+
+function section(title: string) {
+  console.log(`\n=== ${title} ===`);
+}
+
+function subsection(title: string) {
+  console.log(`\n--- ${title} ---`);
+}
+
+function progress(message: string) {
+  console.log(`[tsdisk] ${message}`);
+}
+
+function parsePositiveInteger(value: string | undefined, fallback: number): number {
+  if (!value) {
+    return fallback;
+  }
+
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function decodeOutput(output: Uint8Array): string {
+  return decoder.decode(output);
+}
+
+function firstLines(text: string, maxLines = 8): string {
+  return text.trim().split(/\r?\n/).slice(0, maxLines).join('\n');
+}
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) {
+    return 'n/a';
+  }
+
+  const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+  let value = bytes;
+  let unitIndex = 0;
+
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value = value / 1024;
+    unitIndex++;
+  }
+
+  const decimals = unitIndex === 0 || value >= 100 ? 0 : value >= 10 ? 1 : 2;
+  return `${value.toFixed(decimals)} ${units[unitIndex]}`;
+}
+
+function printSizeLine(label: string, bytes: number) {
+  console.log(`${formatBytes(bytes).padStart(10)}  ${label}`);
+}
+
+function isTruthy(value: string | undefined): boolean {
+  const normalized = value?.toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'y';
+}
+
+async function promptYesNo(question: string, defaultYes = false): Promise<boolean> {
+  const suffix = defaultYes ? '[Y/n]' : '[y/N]';
+  const readline = plugins.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = (await readline.question(`${question} ${suffix} `)).trim().toLowerCase();
+    if (!answer) {
+      return defaultYes;
+    }
+
+    return answer === 'y' || answer === 'yes';
+  } catch {
+    return defaultYes;
+  } finally {
+    readline.close();
+  }
+}
+
+export function parseDuOutput(output: string): IDuEntry[] {
+  const entries: IDuEntry[] = [];
+
+  for (const line of output.trim().split(/\r?\n/)) {
+    const match = line.match(/^(\d+)\s+(.+)$/);
+    if (!match) {
+      continue;
+    }
+
+    entries.push({
+      bytes: Number(match[1]),
+      path: match[2],
+    });
+  }
+
+  return entries;
+}
+
+interface ICaptureState {
+  bytes: number;
+  chunks: Uint8Array[];
+  truncated: boolean;
+}
+
+function createCaptureState(): ICaptureState {
+  return {
+    bytes: 0,
+    chunks: [],
+    truncated: false,
+  };
+}
+
+function captureOutputChunk(state: ICaptureState, chunk: Uint8Array) {
+  if (state.bytes >= maxCapturedOutputBytes) {
+    state.truncated = true;
+    return;
+  }
+
+  const remainingBytes = maxCapturedOutputBytes - state.bytes;
+  if (chunk.byteLength > remainingBytes) {
+    state.chunks.push(chunk.subarray(0, remainingBytes));
+    state.bytes += remainingBytes;
+    state.truncated = true;
+    return;
+  }
+
+  state.chunks.push(chunk);
+  state.bytes += chunk.byteLength;
+}
+
+function capturedOutput(state: ICaptureState): string {
+  return decodeOutput(Buffer.concat(state.chunks));
+}
+
+function commandResultFromCapture(code: number, stdout: ICaptureState, stderr: ICaptureState): ICommandResult {
+  const result: ICommandResult = {
+    code,
+    stdout: capturedOutput(stdout),
+    stderr: capturedOutput(stderr),
+  };
+
+  const truncationMessages: string[] = [];
+  if (stdout.truncated) {
+    truncationMessages.push(`stdout truncated after ${formatBytes(maxCapturedOutputBytes)}`);
+  }
+  if (stderr.truncated) {
+    truncationMessages.push(`stderr truncated after ${formatBytes(maxCapturedOutputBytes)}`);
+  }
+  if (truncationMessages.length) {
+    result.stderr = [result.stderr.trimEnd(), `[tsdisk] ${truncationMessages.join('; ')}.`]
+      .filter(Boolean)
+      .join('\n');
+  }
+
+  return result;
+}
+
+class JsonStreamReader {
+  private buffer = '';
+  private bytesRead = 0;
+  private chunkDecoder = new TextDecoder();
+  private done = false;
+  private index = 0;
+  private iterator?: AsyncIterator<Buffer>;
+  private lastProgressBytes = 0;
+  private stream?: plugins.ReadStream;
+
+  constructor(
+    private filePath: string,
+    private totalBytes: number,
+  ) {}
+
+  async open() {
+    this.stream = plugins.createReadStream(this.filePath);
+    this.iterator = this.stream[Symbol.asyncIterator]() as AsyncIterator<Buffer>;
+  }
+
+  close() {
+    this.stream?.destroy();
+  }
+
+  private reportProgress() {
+    const interval = 512 * 1024 * 1024;
+    if (this.bytesRead - this.lastProgressBytes < interval) {
+      return;
+    }
+
+    this.lastProgressBytes = this.bytesRead;
+    progress(`Parsed ${formatBytes(this.bytesRead)} of ${formatBytes(this.totalBytes)} from ncdu export.`);
+  }
+
+  private async fillBuffer(): Promise<boolean> {
+    while (this.index >= this.buffer.length) {
+      if (this.done) {
+        return false;
+      }
+
+      if (!this.iterator) {
+        throw new Error('JSON stream reader is not open.');
+      }
+
+      const chunk = await this.iterator.next();
+      if (chunk.done) {
+        this.done = true;
+        this.buffer = this.chunkDecoder.decode();
+        this.index = 0;
+        return this.buffer.length > 0;
+      }
+
+      this.bytesRead += chunk.value.byteLength;
+      this.reportProgress();
+      this.buffer = this.chunkDecoder.decode(chunk.value, { stream: true });
+      this.index = 0;
+    }
+
+    return true;
+  }
+
+  async peek(): Promise<string | undefined> {
+    if (!(await this.fillBuffer())) {
+      return undefined;
+    }
+
+    return this.buffer[this.index];
+  }
+
+  async next(): Promise<string | undefined> {
+    const char = await this.peek();
+    if (char !== undefined) {
+      this.index++;
+    }
+
+    return char;
+  }
+
+  async skipWhitespace() {
+    while (true) {
+      const char = await this.peek();
+      if (char === undefined || !/\s/.test(char)) {
+        return;
+      }
+      this.index++;
+    }
+  }
+
+  async expect(expected: string) {
+    await this.skipWhitespace();
+    const actual = await this.next();
+    if (actual !== expected) {
+      throw new Error(`Expected JSON token ${expected}, got ${actual ?? 'EOF'}.`);
+    }
+  }
+
+  async readString(): Promise<string> {
+    await this.skipWhitespace();
+    const first = await this.next();
+    if (first !== '"') {
+      throw new Error(`Expected JSON string, got ${first ?? 'EOF'}.`);
+    }
+
+    let raw = '"';
+    let escaped = false;
+    while (true) {
+      const char = await this.next();
+      if (char === undefined) {
+        throw new Error('Unexpected EOF inside JSON string.');
+      }
+
+      raw += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === '"') {
+        return JSON.parse(raw) as string;
+      }
+    }
+  }
+
+  async readNumber(): Promise<number> {
+    await this.skipWhitespace();
+    let raw = '';
+
+    while (true) {
+      const char = await this.peek();
+      if (char === undefined || !/[0-9eE+.-]/.test(char)) {
+        break;
+      }
+
+      raw += char;
+      this.index++;
+    }
+
+    const parsed = Number(raw);
+    if (!raw || !Number.isFinite(parsed)) {
+      throw new Error(`Expected JSON number, got ${raw || 'EOF'}.`);
+    }
+
+    return parsed;
+  }
+
+  async readLiteral(expected: string) {
+    await this.skipWhitespace();
+    for (const expectedChar of expected) {
+      const actualChar = await this.next();
+      if (actualChar !== expectedChar) {
+        throw new Error(`Expected JSON literal ${expected}.`);
+      }
+    }
+  }
+
+  async skipValue() {
+    await this.skipWhitespace();
+    const char = await this.peek();
+
+    if (char === '"') {
+      await this.readString();
+      return;
+    }
+
+    if (char === '{') {
+      await this.expect('{');
+      await this.skipWhitespace();
+      if ((await this.peek()) === '}') {
+        await this.next();
+        return;
+      }
+
+      while (true) {
+        await this.readString();
+        await this.expect(':');
+        await this.skipValue();
+        await this.skipWhitespace();
+        const nextToken = await this.next();
+        if (nextToken === '}') {
+          return;
+        }
+        if (nextToken !== ',') {
+          throw new Error(`Expected JSON object separator, got ${nextToken ?? 'EOF'}.`);
+        }
+      }
+    }
+
+    if (char === '[') {
+      await this.expect('[');
+      await this.skipWhitespace();
+      if ((await this.peek()) === ']') {
+        await this.next();
+        return;
+      }
+
+      while (true) {
+        await this.skipValue();
+        await this.skipWhitespace();
+        const nextToken = await this.next();
+        if (nextToken === ']') {
+          return;
+        }
+        if (nextToken !== ',') {
+          throw new Error(`Expected JSON array separator, got ${nextToken ?? 'EOF'}.`);
+        }
+      }
+    }
+
+    if (char === 't') {
+      await this.readLiteral('true');
+      return;
+    }
+
+    if (char === 'f') {
+      await this.readLiteral('false');
+      return;
+    }
+
+    if (char === 'n') {
+      await this.readLiteral('null');
+      return;
+    }
+
+    await this.readNumber();
+  }
+}
+
+async function runBasic(command: string, args: string[]): Promise<ICommandResult> {
+  return await new Promise<ICommandResult>((resolve) => {
+    const child = plugins.spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdout = createCaptureState();
+    const stderr = createCaptureState();
+
+    child.stdout.on('data', (chunk: Uint8Array) => captureOutputChunk(stdout, chunk));
+    child.stderr.on('data', (chunk: Uint8Array) => captureOutputChunk(stderr, chunk));
+    child.on('error', (error) => {
+      resolve({
+        code: 127,
+        stdout: '',
+        stderr: error instanceof Error ? error.message : String(error),
+      });
+    });
+    child.on('close', (code) => {
+      resolve(commandResultFromCapture(code ?? 1, stdout, stderr));
+    });
+  });
+}
+
+async function runInteractive(command: string, args: string[], timeoutSeconds?: number): Promise<number> {
+  return await new Promise<number>((resolve) => {
+    const child = plugins.spawn(command, args, {
+      stdio: 'inherit',
+    });
+    let didTimeout = false;
+    let killTimeout: NodeJS.Timeout | undefined;
+    const timeout = timeoutSeconds && timeoutSeconds > 0
+      ? setTimeout(() => {
+          didTimeout = true;
+          child.kill('SIGTERM');
+          killTimeout = setTimeout(() => child.kill('SIGKILL'), 5000);
+          killTimeout.unref();
+        }, timeoutSeconds * 1000)
+      : undefined;
+    timeout?.unref();
+
+    child.on('error', (error) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      if (killTimeout) {
+        clearTimeout(killTimeout);
+      }
+      console.error(error instanceof Error ? error.message : String(error));
+      resolve(127);
+    });
+    child.on('close', (code, signal) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      if (killTimeout) {
+        clearTimeout(killTimeout);
+      }
+      if (didTimeout) {
+        resolve(124);
+        return;
+      }
+      if (code !== null) {
+        resolve(code);
+        return;
+      }
+
+      resolve(signal === 'SIGINT' ? 130 : 1);
+    });
+  });
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  const result = await runBasic('which', [command]);
+  return result.code === 0 && result.stdout.trim().length > 0;
+}
+
+async function runRootInteractive(
+  ctx: IRuntimeContext,
+  command: string,
+  args: string[],
+  timeoutSeconds?: number,
+): Promise<number> {
+  let executable = command;
+  let finalArgs = args;
+
+  if (timeoutSeconds && timeoutSeconds > 0) {
+    finalArgs = [`${timeoutSeconds}s`, command, ...args];
+    executable = 'timeout';
+  }
+  const processTimeoutSeconds = timeoutSeconds && timeoutSeconds > 0 ? timeoutSeconds + 10 : undefined;
+
+  if (ctx.runningAsRoot) {
+    return await runInteractive(executable, finalArgs, processTimeoutSeconds);
+  }
+
+  if (!(await ensureSudo(ctx))) {
+    return 1;
+  }
+
+  return await runInteractive('sudo', [executable, ...finalArgs], processTimeoutSeconds);
+}
+
+function buildTargetUserArgs(ctx: IRuntimeContext, command: string, args: string[]): string[] {
+  return [
+    '-u',
+    ctx.targetUser,
+    'env',
+    `HOME=${ctx.targetHome}`,
+    `XDG_RUNTIME_DIR=${ctx.targetRuntimeDir}`,
+    command,
+    ...args,
+  ];
+}
+
+async function runCommand(
+  ctx: IRuntimeContext,
+  command: string,
+  args: string[],
+  options: IRunOptions = {},
+): Promise<ICommandResult> {
+  let executable = command;
+  let finalArgs = [...args];
+  const env: NodeJS.ProcessEnv = {};
+
+  if (options.asRoot && !ctx.runningAsRoot) {
+    if (!ctx.sudoAvailable) {
+      return {
+        code: 1,
+        stdout: '',
+        stderr: 'sudo is unavailable; root-only check skipped',
+      };
+    }
+
+    executable = 'sudo';
+    finalArgs = ['-n', command, ...finalArgs];
+  }
+
+  if (options.asTargetUser) {
+    if (ctx.runningAsRoot && ctx.targetUser !== 'root') {
+      executable = 'sudo';
+      finalArgs = buildTargetUserArgs(ctx, command, finalArgs);
+    } else {
+      env.HOME = ctx.targetHome;
+      env.XDG_RUNTIME_DIR = ctx.targetRuntimeDir;
+    }
+  }
+
+  if (options.timeoutSeconds && options.timeoutSeconds > 0) {
+    finalArgs = [`${options.timeoutSeconds}s`, executable, ...finalArgs];
+    executable = 'timeout';
+  }
+
+  return await new Promise<ICommandResult>((resolve) => {
+    const child = plugins.spawn(executable, finalArgs, {
+      env: {
+        ...process.env,
+        ...env,
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdout = createCaptureState();
+    const stderr = createCaptureState();
+
+    child.stdout.on('data', (chunk: Uint8Array) => captureOutputChunk(stdout, chunk));
+    child.stderr.on('data', (chunk: Uint8Array) => captureOutputChunk(stderr, chunk));
+    child.on('error', (error) => {
+      resolve({
+        code: 127,
+        stdout: '',
+        stderr: error instanceof Error ? error.message : String(error),
+      });
+    });
+    child.on('close', (code) => {
+      resolve(commandResultFromCapture(code ?? 1, stdout, stderr));
+    });
+  });
+}
+
+async function initContext(): Promise<IRuntimeContext> {
+  const currentUid = (await runBasic('id', ['-u'])).stdout.trim();
+  const currentUser = (await runBasic('id', ['-un'])).stdout.trim() || process.env.USER || 'unknown';
+  const sudoUser = process.env.SUDO_USER;
+  const targetUser = sudoUser && sudoUser !== 'root' ? sudoUser : currentUser;
+  const targetUid = (await runBasic('id', ['-u', targetUser])).stdout.trim() || currentUid;
+  const passwdLine = (await runBasic('getent', ['passwd', targetUser])).stdout.trim();
+  const passwdHome = passwdLine.split(':')[5];
+  const targetHome = passwdHome || process.env.HOME || `/home/${targetUser}`;
+  const targetRuntimeDir = process.env.XDG_RUNTIME_DIR || `/run/user/${targetUid}`;
+
+  return {
+    runningAsRoot: currentUid === '0',
+    sudoAvailable: currentUid === '0',
+    sudoChecked: currentUid === '0',
+    targetUser,
+    targetUid,
+    targetHome,
+    targetRuntimeDir,
+    dockerTimeoutSeconds: parsePositiveInteger(process.env.DOCKER_TIMEOUT, 60),
+    duTimeoutSeconds: parsePositiveInteger(process.env.DU_TIMEOUT, 300),
+    ncduTimeoutSeconds: parsePositiveInteger(process.env.NCDU_TIMEOUT, 900),
+  };
+}
+
+async function ensureSudo(ctx: IRuntimeContext): Promise<boolean> {
+  if (ctx.runningAsRoot) {
+    ctx.sudoAvailable = true;
+    ctx.sudoChecked = true;
+    return true;
+  }
+
+  if (ctx.sudoChecked) {
+    return ctx.sudoAvailable;
+  }
+
+  section('Privilege Check');
+  console.log('Root filesystem checks require sudo. Requesting sudo credentials now.');
+  const code = await runInteractive('sudo', ['-v'], 60);
+  ctx.sudoChecked = true;
+  ctx.sudoAvailable = code === 0;
+
+  if (!ctx.sudoAvailable) {
+    console.log('sudo authentication failed or was cancelled; root-only checks will be skipped.');
+  }
+
+  return ctx.sudoAvailable;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await plugins.fs.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readMarkerInDirectory(pathArg: string): Promise<IToolCacheMarker | undefined> {
+  try {
+    const markerRaw = await plugins.fs.readFile(plugins.path.join(pathArg, toolCacheMarkerFile), 'utf8');
+    return parseToolCacheMarker(markerRaw);
+  } catch {
+    return undefined;
+  }
+}
+
+function shouldSkipWorkspaceDir(nameArg: string): boolean {
+  return nameArg === '.git'
+    || nameArg === 'node_modules'
+    || nameArg === 'dist_ts'
+    || nameArg === 'dist_ts_web'
+    || nameArg === 'coverage'
+    || nameArg === '.pnpm-store';
+}
+
+export async function collectToolCachePathsFromRoot(
+  rootArg: string,
+  optionsArg: IWorkspaceScanOptions,
+): Promise<IToolCacheFinding[]> {
+  const findings = new Map<string, IToolCacheFinding>();
+  const startedAt = Date.now();
+  let visitedEntries = 0;
+  let rootDev: number | undefined;
+
+  try {
+    rootDev = (await plugins.fs.stat(rootArg)).dev;
+  } catch {
+    return [];
+  }
+
+  const visit = async (dirArg: string, depthArg: number): Promise<void> => {
+    if (Date.now() - startedAt > optionsArg.timeoutMs || visitedEntries > optionsArg.maxEntries) {
+      return;
+    }
+
+    let entries;
+    try {
+      entries = await plugins.fs.readdir(dirArg, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    const marker = await readMarkerInDirectory(dirArg);
+    const markerClassification = classifyToolCachePath(dirArg, marker);
+    if (markerClassification) {
+      findings.set(plugins.path.resolve(dirArg), {
+        path: dirArg,
+        ...markerClassification,
+      });
+    }
+
+    const heuristicClassification = classifyToolCachePath(dirArg);
+    if (heuristicClassification) {
+      if (!markerClassification) {
+        findings.set(plugins.path.resolve(dirArg), {
+          path: dirArg,
+          ...heuristicClassification,
+        });
+      }
+      if (heuristicClassification.kind === 'docker-registry-cache') {
+        for (const entry of entries) {
+          if (Date.now() - startedAt > optionsArg.timeoutMs || visitedEntries > optionsArg.maxEntries) {
+            return;
+          }
+          visitedEntries++;
+          if (!entry.isDirectory()) {
+            continue;
+          }
+          const entryPath = plugins.path.join(dirArg, entry.name);
+          const entryMarker = await readMarkerInDirectory(entryPath);
+          const entryMarkerClassification = classifyToolCachePath(entryPath, entryMarker);
+          if (entryMarkerClassification) {
+            findings.set(plugins.path.resolve(entryPath), {
+              path: entryPath,
+              ...entryMarkerClassification,
+            });
+          }
+        }
+      }
+      return;
+    }
+
+    if (depthArg >= optionsArg.maxDepth) {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (Date.now() - startedAt > optionsArg.timeoutMs || visitedEntries > optionsArg.maxEntries) {
+        return;
+      }
+      visitedEntries++;
+      if (!entry.isDirectory() || shouldSkipWorkspaceDir(entry.name)) {
+        continue;
+      }
+      const entryPath = plugins.path.join(dirArg, entry.name);
+      let stat;
+      try {
+        stat = await plugins.fs.stat(entryPath);
+      } catch {
+        continue;
+      }
+      if (rootDev !== undefined && stat.dev !== rootDev) {
+        continue;
+      }
+      await visit(entryPath, depthArg + 1);
+    }
+  };
+
+  await visit(rootArg, 0);
+  return [...findings.values()];
+}
+
+async function getWorkspaceRoots(): Promise<string[]> {
+  const roots = new Set<string>();
+  if (await pathExists('/mnt/data')) {
+    roots.add('/mnt/data');
+  }
+  const cwd = process.cwd();
+  if (cwd && cwd !== '/') {
+    roots.add(cwd);
+  }
+  return [...roots];
+}
+
+export async function collectProjectToolCacheDiagnostics(ctx: IRuntimeContext): Promise<IToolCacheFinding[]> {
+  const roots = await getWorkspaceRoots();
+  const findings: IToolCacheFinding[] = [];
+  for (const root of roots) {
+    const rootFindings = await collectToolCachePathsFromRoot(root, {
+      maxDepth: 8,
+      timeoutMs: 45_000,
+      maxEntries: 50_000,
+    });
+    findings.push(...rootFindings);
+  }
+
+  const uniqueFindings = [...new Map(findings.map((finding) => [plugins.path.resolve(finding.path), finding])).values()];
+  const sizedFindings: IToolCacheFinding[] = [];
+  const sizingStartedAt = Date.now();
+  for (const [index, finding] of uniqueFindings.entries()) {
+    if (index >= toolCacheSizingLimit || Date.now() - sizingStartedAt > toolCacheSizingTimeoutMs) {
+      sizedFindings.push(finding);
+      continue;
+    }
+    const size = await readDuTotal(ctx, finding.path, ctx.sudoAvailable);
+    sizedFindings.push({
+      ...finding,
+      bytes: size?.bytes,
+    });
+  }
+
+  return sizedFindings.sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0));
+}
+
+async function printProjectToolCacheDiagnostics(ctx: IRuntimeContext) {
+  section('Project Tool Cache Diagnostics');
+  const roots = await getWorkspaceRoots();
+  if (roots.length === 0) {
+    console.log('No workspace roots found.');
+    return;
+  }
+  progress(`Scanning workspace roots: ${roots.join(', ')}`);
+  const findings = await collectProjectToolCacheDiagnostics(ctx);
+  if (findings.length === 0) {
+    console.log('No known project-local tool caches found.');
+    return;
+  }
+
+  for (const finding of findings) {
+    printSizeLine(`${finding.ownerGuess} ${finding.kind} [${finding.risk}] ${finding.path}`, finding.bytes ?? 0);
+    console.log(`           suggested: ${finding.suggestedCleanupCommand}`);
+  }
+}
+
+async function pathExistsForDu(ctx: IRuntimeContext, path: string, asRoot: boolean): Promise<boolean> {
+  if (!asRoot) {
+    return await pathExists(path);
+  }
+
+  const result = await runCommand(ctx, 'test', ['-e', path], {
+    asRoot: true,
+    timeoutSeconds: 30,
+  });
+
+  return result.code === 0;
+}
+
+async function printDiskOverview(ctx: IRuntimeContext) {
+  section('Disk Usage Overview');
+  progress('Reading filesystem usage with df.');
+  const paths = ['/'];
+
+  if (await pathExists('/mnt/data')) {
+    paths.push('/mnt/data');
+  }
+
+  const result = await runCommand(ctx, 'df', ['-B1', '-T', ...paths], { timeoutSeconds: 30 });
+  if (result.stdout.trim()) {
+    const lines = result.stdout.trim().split(/\r?\n/).slice(1);
+    for (const line of lines) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length < 7) {
+        continue;
+      }
+
+      const [filesystem, type, size, used, available, usePercent, mount] = parts;
+      console.log(
+        `${mount.padEnd(12)} ${formatBytes(Number(used))} used / ${formatBytes(Number(size))} (${usePercent} full), ${formatBytes(Number(available))} available, ${type}, ${filesystem}`,
+      );
+    }
+  } else {
+    console.log(result.stderr.trim() || 'df output unavailable');
+  }
+
+  console.log(`Inspecting user: ${ctx.targetUser}`);
+  console.log(`Home: ${ctx.targetHome}`);
+  console.log(`Docker timeout: ${ctx.dockerTimeoutSeconds}s`);
+  console.log(`du timeout: ${ctx.duTimeoutSeconds}s`);
+  console.log(`ncdu timeout: ${ctx.ncduTimeoutSeconds}s`);
+}
+
+async function readDuTree(
+  ctx: IRuntimeContext,
+  path: string,
+  depth: number,
+  asRoot: boolean,
+): Promise<{ entries: IDuEntry[]; result: ICommandResult }> {
+  const result = await runCommand(ctx, 'du', ['-xB1', '-d', String(depth), path], {
+    asRoot,
+    timeoutSeconds: ctx.duTimeoutSeconds,
+  });
+
+  return {
+    entries: parseDuOutput(result.stdout),
+    result,
+  };
+}
+
+async function readDuTotal(ctx: IRuntimeContext, path: string, asRoot: boolean): Promise<IDuEntry | undefined> {
+  const result = await runCommand(ctx, 'du', ['-sxB1', path], {
+    asRoot,
+    timeoutSeconds: ctx.duTimeoutSeconds,
+  });
+
+  return parseDuOutput(result.stdout)[0];
+}
+
+async function printDuTree(ctx: IRuntimeContext, title: string, path: string, asRoot = true) {
+  section(title);
+  progress(`Scanning ${path} with du.`);
+  const { entries, result } = await readDuTree(ctx, path, 1, asRoot);
+
+  if (!entries.length) {
+    console.log(result.stderr.trim() || `${path} unavailable`);
+    return;
+  }
+
+  const total = entries.find((entry) => entry.path === path);
+  const children = entries.filter((entry) => entry.path !== path).sort((a, b) => b.bytes - a.bytes);
+
+  if (total) {
+    printSizeLine(`${path} total`, total.bytes);
+  }
+
+  for (const entry of children) {
+    printSizeLine(entry.path, entry.bytes);
+  }
+
+  if (result.code === 124) {
+    console.log(`Timed out after ${ctx.duTimeoutSeconds}s; results may be incomplete.`);
+  } else if (result.code !== 0 && result.stderr.trim()) {
+    console.log('Partial du warnings:');
+    console.log(firstLines(result.stderr));
+  }
+}
+
+async function printKnownSizes(
+  ctx: IRuntimeContext,
+  title: string,
+  rows: Array<{ label: string; path: string; asRoot?: boolean }>,
+) {
+  section(title);
+  progress(`Checking ${rows.length} known paths.`);
+  const sizes: Array<{ label: string; path: string; asRoot?: boolean; bytes?: number }> = [];
+  for (const row of rows) {
+    const entry = await readDuTotal(ctx, row.path, row.asRoot ?? true);
+    sizes.push({ ...row, bytes: entry?.bytes });
+  }
+
+  const visibleSizes = sizes.filter((row) => typeof row.bytes === 'number').sort((a, b) => {
+    return (b.bytes ?? 0) - (a.bytes ?? 0);
+  });
+
+  if (!visibleSizes.length) {
+    console.log('No matching paths found.');
+    return;
+  }
+
+  for (const row of visibleSizes) {
+    printSizeLine(`${row.label} (${row.path})`, row.bytes ?? 0);
+  }
+}
+
+async function printConfiguredToolPaths(ctx: IRuntimeContext) {
+  section('Configured Package Cache Paths');
+  progress('Querying package manager cache configuration.');
+
+  const commands = [
+    { label: 'pnpm store path', command: 'pnpm', args: ['store', 'path'] },
+    { label: 'npm cache path', command: 'npm', args: ['config', 'get', 'cache'] },
+    { label: 'yarn cache path', command: 'yarn', args: ['cache', 'dir'] },
+  ];
+
+  let printed = false;
+  for (const item of commands) {
+    const result = await runCommand(ctx, item.command, item.args, {
+      asTargetUser: true,
+      timeoutSeconds: 30,
+    });
+    const configuredPath = result.stdout.trim().split(/\r?\n/).at(-1)?.trim();
+
+    if (!configuredPath || result.code !== 0) {
+      continue;
+    }
+
+    const entry = await readDuTotal(ctx, configuredPath, ctx.sudoAvailable);
+    if (entry) {
+      printSizeLine(`${item.label} (${configuredPath})`, entry.bytes);
+    } else {
+      console.log(`${item.label}: ${configuredPath}`);
+    }
+    printed = true;
+  }
+
+  if (!printed) {
+    console.log('No pnpm/npm/yarn cache paths could be resolved from installed commands.');
+  }
+}
+
+async function printDeletedOpenFiles(ctx: IRuntimeContext) {
+  section('Deleted Open Files');
+  progress('Checking deleted-but-open files with lsof.');
+  const result = await runCommand(ctx, 'lsof', ['-nP', '+L1'], {
+    asRoot: true,
+    timeoutSeconds: 60,
+  });
+
+  if (result.code === 127) {
+    console.log('lsof is not installed. This check finds deleted files that still consume disk space.');
+    return;
+  }
+
+  if (!result.stdout.trim()) {
+    console.log(result.stderr.trim() || 'No deleted open files reported.');
+    return;
+  }
+
+  const lines = result.stdout.trimEnd().split(/\r?\n/);
+  const maxLines = 40;
+  console.log(lines.slice(0, maxLines).join('\n'));
+  if (lines.length > maxLines) {
+    console.log(`... ${lines.length - maxLines} more lines omitted. Run: sudo lsof -nP +L1`);
+  }
+}
+
+async function printJournalUsage(ctx: IRuntimeContext) {
+  section('Journal Usage');
+  progress('Checking systemd journal disk usage.');
+  const result = await runCommand(ctx, 'journalctl', ['--disk-usage'], {
+    asRoot: true,
+    timeoutSeconds: 30,
+  });
+
+  if (result.code === 127) {
+    console.log('journalctl is not installed.');
+    return;
+  }
+
+  console.log((result.stdout.trim() || result.stderr.trim() || 'journalctl returned no output').trim());
+}
+
+function ncduPath(parentPath: string, name: string): string {
+  if (name.startsWith('/')) {
+    return name;
+  }
+
+  if (!parentPath || parentPath === '/') {
+    return `/${name}`;
+  }
+
+  return `${parentPath}/${name}`;
+}
+
+function addNcduInsight(insights: INcduInsight[], insight: INcduInsight) {
+  if (insight.path === '/' || insight.bytes <= 0) {
+    return;
+  }
+
+  insights.push(insight);
+  insights.sort((a, b) => b.bytes - a.bytes);
+  if (insights.length > ncduInsightLimit) {
+    insights.length = ncduInsightLimit;
+  }
+}
+
+async function parseNcduInfo(reader: JsonStreamReader): Promise<{
+  dsize: number;
+  excluded?: string;
+  name: string;
+  readError: boolean;
+}> {
+  let dsize = 0;
+  let excluded: string | undefined;
+  let name = 'unknown';
+  let readError = false;
+
+  await reader.expect('{');
+  await reader.skipWhitespace();
+  if ((await reader.peek()) === '}') {
+    await reader.next();
+    return { dsize, excluded, name, readError };
+  }
+
+  while (true) {
+    const key = await reader.readString();
+    await reader.expect(':');
+    await reader.skipWhitespace();
+
+    if (key === 'name') {
+      name = await reader.readString();
+    } else if (key === 'dsize') {
+      dsize = await reader.readNumber();
+    } else if (key === 'read_error') {
+      const nextToken = await reader.peek();
+      if (nextToken === 't') {
+        await reader.readLiteral('true');
+        readError = true;
+      } else if (nextToken === 'f') {
+        await reader.readLiteral('false');
+        readError = false;
+      } else {
+        await reader.skipValue();
+      }
+    } else if (key === 'excluded') {
+      excluded = await reader.readString();
+    } else {
+      await reader.skipValue();
+    }
+
+    await reader.skipWhitespace();
+    const nextToken = await reader.next();
+    if (nextToken === '}') {
+      return { dsize, excluded, name, readError };
+    }
+    if (nextToken !== ',') {
+      throw new Error(`Expected JSON object separator, got ${nextToken ?? 'EOF'}.`);
+    }
+  }
+}
+
+async function parseNcduNode(
+  reader: JsonStreamReader,
+  parentPath: string,
+  insights: INcduInsight[],
+): Promise<number> {
+  await reader.skipWhitespace();
+  const nextToken = await reader.peek();
+
+  if (nextToken === '[') {
+    await reader.expect('[');
+    const info = await parseNcduInfo(reader);
+    const path = ncduPath(parentPath, info.name);
+    let bytes = info.dsize;
+
+    await reader.skipWhitespace();
+    while ((await reader.peek()) === ',') {
+      await reader.next();
+      bytes += await parseNcduNode(reader, path, insights);
+      await reader.skipWhitespace();
+    }
+
+    await reader.expect(']');
+    addNcduInsight(insights, {
+      bytes,
+      path,
+      type: 'directory',
+      readError: info.readError,
+      excluded: info.excluded,
+    });
+
+    return bytes;
+  }
+
+  if (nextToken === '{') {
+    const info = await parseNcduInfo(reader);
+    const path = ncduPath(parentPath, info.name);
+    addNcduInsight(insights, {
+      bytes: info.dsize,
+      path,
+      type: 'file',
+      readError: info.readError,
+      excluded: info.excluded,
+    });
+
+    return info.dsize;
+  }
+
+  throw new Error(`Expected ncdu node, got ${nextToken ?? 'EOF'}.`);
+}
+
+async function parseNcduExportFile(exportPath: string): Promise<INcduParseResult> {
+  const stat = await plugins.fs.stat(exportPath);
+  const reader = new JsonStreamReader(exportPath, stat.size);
+  await reader.open();
+
+  try {
+    const insights: INcduInsight[] = [];
+    await reader.expect('[');
+    await reader.skipValue();
+    await reader.expect(',');
+    await reader.skipValue();
+    await reader.expect(',');
+    await reader.skipValue();
+    await reader.expect(',');
+    const rootBytes = await parseNcduNode(reader, '', insights);
+
+    return {
+      rootBytes,
+      insights: insights.sort((a, b) => b.bytes - a.bytes),
+    };
+  } finally {
+    reader.close();
+  }
+}
+
+async function cleanupNcduExport(ctx: IRuntimeContext, exportPath: string) {
+  if (isTruthy(process.env.TSDISK_KEEP_NCDU_EXPORT)) {
+    await runCommand(ctx, 'chown', [ctx.targetUser, exportPath], {
+      asRoot: true,
+      timeoutSeconds: 30,
+    });
+    console.log(`ncdu export file kept: ${exportPath}`);
+    console.log(`Browse it later with: ncdu -f ${exportPath}`);
+    return;
+  }
+
+  progress(`Removing temporary ncdu export ${exportPath}.`);
+  const result = await runCommand(ctx, 'rm', ['-f', exportPath], {
+    asRoot: true,
+    timeoutSeconds: 30,
+  });
+
+  if (result.code !== 0) {
+    console.log(result.stderr.trim() || `Could not remove ${exportPath}`);
+  }
+}
+
+async function ensureNcduAvailable(ctx: IRuntimeContext): Promise<boolean> {
+  if (await commandExists('ncdu')) {
+    return true;
+  }
+
+  console.log('ncdu is not installed.');
+  if (!(await commandExists('apt-get'))) {
+    console.log('apt-get is not available, so this script cannot install ncdu automatically.');
+    return false;
+  }
+
+  const envAnswer = process.env.TSDISK_INSTALL_NCDU?.toLowerCase();
+  const installRequested = isTruthy(envAnswer)
+    ? true
+    : await promptYesNo('Install ncdu now using sudo apt-get?', false);
+
+  if (!installRequested) {
+    return false;
+  }
+
+  progress('Updating apt package lists before installing ncdu.');
+  const updateCode = await runRootInteractive(ctx, 'apt-get', ['update'], ctx.ncduTimeoutSeconds);
+  if (updateCode !== 0) {
+    console.log(`apt-get update failed with exit code ${updateCode}.`);
+    return false;
+  }
+
+  progress('Installing ncdu with apt-get.');
+  const installCode = await runRootInteractive(ctx, 'apt-get', ['install', '-y', 'ncdu'], ctx.ncduTimeoutSeconds);
+  if (installCode !== 0) {
+    console.log(`apt-get install ncdu failed with exit code ${installCode}.`);
+    return false;
+  }
+
+  return await commandExists('ncdu');
+}
+
+async function runNcduExport(ctx: IRuntimeContext, exportPath: string, useIgnoreConfig: boolean): Promise<number> {
+  const args = useIgnoreConfig
+    ? ['--ignore-config', '-1', '-x', '-o', exportPath, '/']
+    : ['-1', '-x', '-o', exportPath, '/'];
+
+  return await runRootInteractive(ctx, 'ncdu', args, ctx.ncduTimeoutSeconds);
+}
+
+async function printNcduInsights(ctx: IRuntimeContext) {
+  section('ncdu Insights');
+  if (!(await ensureNcduAvailable(ctx))) {
+    console.log('Skipping ncdu export scan.');
+    return;
+  }
+
+  const exportPath = process.env.TSDISK_NCDU_EXPORT || `/tmp/tsdisk-ncdu-root-${Date.now()}.json`;
+  progress(`Running ncdu export scan of / into ${exportPath}.`);
+  let exitCode = await runNcduExport(ctx, exportPath, true);
+
+  if (exitCode !== 0 && !(await pathExists(exportPath))) {
+    progress('Retrying ncdu export without --ignore-config for older ncdu versions.');
+    exitCode = await runNcduExport(ctx, exportPath, false);
+  }
+
+  if (exitCode !== 0 && !(await pathExists(exportPath))) {
+    console.log(`ncdu export failed with exit code ${exitCode}.`);
+    return;
+  }
+
+  progress('Parsing ncdu export for largest paths.');
+  let parseResult: INcduParseResult;
+  try {
+    parseResult = await parseNcduExportFile(exportPath);
+  } catch (error) {
+    console.log(error instanceof Error ? error.message : String(error));
+    await cleanupNcduExport(ctx, exportPath);
+    return;
+  }
+
+  printSizeLine('ncdu scanned root total', parseResult.rootBytes);
+
+  const largest = parseResult.insights.filter((entry) => entry.path !== '/' && entry.bytes > 0).slice(0, ncduInsightLimit);
+  if (!largest.length) {
+    console.log('No non-root ncdu entries found.');
+  } else {
+    console.log('Largest paths from ncdu export:');
+    for (const entry of largest) {
+      const suffix = [entry.type, entry.readError ? 'read_error' : '', entry.excluded ? `excluded:${entry.excluded}` : '']
+        .filter(Boolean)
+        .join(', ');
+      printSizeLine(`${entry.path}${suffix ? ` (${suffix})` : ''}`, entry.bytes);
+    }
+  }
+
+  await cleanupNcduExport(ctx, exportPath);
+}
+
+async function printSpecializedToolHints() {
+  section('Specialized Disk Tools');
+  const tools = ['ncdu', 'gdu', 'dua', 'dust'];
+  const available: string[] = [];
+
+  for (const tool of tools) {
+    if (await commandExists(tool)) {
+      available.push(tool);
+    }
+  }
+
+  if (available.length) {
+    console.log(`Installed scanner tools: ${available.join(', ')}`);
+  } else {
+    console.log('No ncdu/gdu/dua/dust scanner is currently installed.');
+  }
+
+  console.log('Best interactive scanner: sudo ncdu -x /');
+  console.log('Exportable scan: sudo ncdu -x -o /tmp/root-ncdu.json / && ncdu -f /tmp/root-ncdu.json');
+  console.log('df/du mismatch check: sudo lsof -nP +L1');
+}
+
+async function runDocker(ctx: IRuntimeContext, args: string[], timeoutSeconds = ctx.dockerTimeoutSeconds) {
+  return await runCommand(ctx, 'docker', args, {
+    asTargetUser: true,
+    timeoutSeconds,
+  });
+}
+
+function parseDockerInspect(stdoutArg: string): any[] {
+  if (!stdoutArg.trim()) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(stdoutArg);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+async function inspectDockerObjects(ctx: IRuntimeContext, dockerContext: string, idsArg: string[]): Promise<any[]> {
+  if (idsArg.length === 0) {
+    return [];
+  }
+  const result = await runDocker(ctx, ['--context', dockerContext, 'inspect', ...idsArg], 30);
+  return parseDockerInspect(result.stdout);
+}
+
+async function printDockerTsdockerRegistryContainers(ctx: IRuntimeContext, dockerContext: string) {
+  const result = await runDocker(ctx, [
+    '--context',
+    dockerContext,
+    'ps',
+    '-a',
+    '--filter',
+    'name=tsdocker-registry-',
+    '--format',
+    '{{.ID}}',
+  ], 30);
+  const ids = result.stdout.trim().split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const containers = await inspectDockerObjects(ctx, dockerContext, ids);
+  const stopped = containers.filter((container) => container.State?.Status !== 'running');
+  if (stopped.length === 0) {
+    return;
+  }
+
+  subsection(`Stopped tsdocker registry containers: ${dockerContext}`);
+  for (const container of stopped) {
+    const name = String(container.Name || '').replace(/^\//, '');
+    const labels = container.Config?.Labels || {};
+    const cachePath = labels['git.zone.cache-path'] || 'unlabeled cache path';
+    const mounts = (container.Mounts || []).map((mount: any) => mount.Source).filter(Boolean).join(', ');
+    console.log(`${container.Id.slice(0, 12)} ${name} ${container.State?.Status} cache=${cachePath} mounts=${mounts || 'none'}`);
+    console.log('           suggested: tsdocker prune --apply (labeled containers only)');
+  }
+}
+
+async function printDockerBuildxZeroLinkVolumes(ctx: IRuntimeContext, dockerContext: string) {
+  const volumeList = await runDocker(ctx, ['--context', dockerContext, 'volume', 'ls', '--format', '{{.Name}}'], 30);
+  const names = volumeList.stdout.trim().split(/\r?\n/).map((line) => line.trim()).filter((name) => {
+    return /^buildx_buildkit_.+_state$/.test(name) || name.includes('buildkit');
+  });
+  if (names.length === 0) {
+    return;
+  }
+  const volumes = await inspectDockerObjects(ctx, dockerContext, names);
+  const zeroLinkVolumes = volumes.filter((volume) => volume.UsageData?.RefCount === 0);
+  if (zeroLinkVolumes.length === 0) {
+    return;
+  }
+
+  subsection(`Docker buildx zero-link volumes: ${dockerContext}`);
+  for (const volume of zeroLinkVolumes) {
+    console.log(`${volume.Name} mountpoint=${volume.Mountpoint || 'unknown'} refCount=0`);
+    console.log('           suggested: report-only; review builder state before docker volume rm');
+  }
+}
+
+async function getDockerContexts(ctx: IRuntimeContext): Promise<string[]> {
+  const result = await runDocker(ctx, ['context', 'ls', '--format', '{{.Name}}'], 30);
+  return result.stdout.trim().split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+
+async function getDockerEndpoint(ctx: IRuntimeContext, dockerContext: string): Promise<string> {
+  const jsonResult = await runDocker(ctx, [
+    'context',
+    'inspect',
+    dockerContext,
+    '--format',
+    '{{json .Endpoints.docker.Host}}',
+  ], 30);
+  const raw = jsonResult.stdout.trim();
+
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed === 'string') {
+        return parsed;
+      }
+    } catch {
+      return raw;
+    }
+  }
+
+  const plainResult = await runDocker(ctx, [
+    'context',
+    'inspect',
+    dockerContext,
+    '--format',
+    '{{.Endpoints.docker.Host}}',
+  ], 30);
+  return plainResult.stdout.trim();
+}
+
+async function printDockerContextDetails(ctx: IRuntimeContext, dockerContext: string) {
+  subsection(`Docker context: ${dockerContext}`);
+  progress(`Inspecting Docker context ${dockerContext}.`);
+
+  const endpoint = await getDockerEndpoint(ctx, dockerContext);
+  if (endpoint) {
+    console.log(`Endpoint: ${endpoint}`);
+  }
+
+  const info = await runDocker(ctx, ['--context', dockerContext, 'info', '--format', '{{.DockerRootDir}}']);
+  const dockerRoot = info.stdout.trim();
+
+  if (!dockerRoot) {
+    console.log(info.stderr.trim() || `DockerRootDir unavailable or timed out after ${ctx.dockerTimeoutSeconds}s`);
+    return;
+  }
+
+  console.log(`DockerRootDir: ${dockerRoot}`);
+
+  const systemDf = await runDocker(ctx, ['--context', dockerContext, 'system', 'df']);
+  if (systemDf.stdout.trim()) {
+    console.log(systemDf.stdout.trimEnd());
+  } else {
+    console.log(systemDf.stderr.trim() || `docker system df unavailable or timed out after ${ctx.dockerTimeoutSeconds}s`);
+  }
+
+  await printDockerTsdockerRegistryContainers(ctx, dockerContext);
+  await printDockerBuildxZeroLinkVolumes(ctx, dockerContext);
+
+  const isLocalEndpoint = !endpoint || endpoint.startsWith('unix://');
+  if (!isLocalEndpoint) {
+    console.log('Skipping local du for this context because the Docker endpoint is not local.');
+    return;
+  }
+
+  const duAsRoot = ctx.sudoAvailable;
+
+  if (!(await pathExistsForDu(ctx, dockerRoot, duAsRoot))) {
+    console.log('Skipping local du because DockerRootDir does not exist on this filesystem.');
+    return;
+  }
+
+  const dockerRootTotal = await readDuTotal(ctx, dockerRoot, duAsRoot);
+  if (dockerRootTotal) {
+    printSizeLine('Docker root local size', dockerRootTotal.bytes);
+  }
+
+  const { entries, result } = await readDuTree(ctx, dockerRoot, 1, duAsRoot);
+  const children = entries.filter((entry) => entry.path !== dockerRoot).sort((a, b) => b.bytes - a.bytes);
+
+  if (children.length) {
+    subsection(`Docker root breakdown: ${dockerContext}`);
+    for (const entry of children) {
+      printSizeLine(entry.path, entry.bytes);
+    }
+  }
+
+  if (result.code !== 0 && result.stderr.trim()) {
+    console.log('Partial Docker root du warnings:');
+    console.log(firstLines(result.stderr));
+  }
+
+  const volumePath = `${dockerRoot}/volumes`;
+  if (await pathExistsForDu(ctx, volumePath, duAsRoot)) {
+    const volumeTree = await readDuTree(ctx, volumePath, 1, duAsRoot);
+    const volumes = volumeTree.entries.filter((entry) => entry.path !== volumePath).sort((a, b) => b.bytes - a.bytes);
+
+    if (volumes.length) {
+      subsection(`Docker volume sizes: ${dockerContext}`);
+      for (const volume of volumes) {
+        printSizeLine(volume.path, volume.bytes);
+      }
+    }
+  }
+
+  const buildkitPath = `${dockerRoot}/buildkit`;
+  if (await pathExistsForDu(ctx, buildkitPath, duAsRoot)) {
+    const buildkitTree = await readDuTree(ctx, buildkitPath, 1, duAsRoot);
+    const buildkitEntries = buildkitTree.entries.filter((entry) => entry.path !== buildkitPath).sort((a, b) => b.bytes - a.bytes);
+
+    if (buildkitEntries.length) {
+      subsection(`Docker buildkit sizes: ${dockerContext}`);
+      for (const entry of buildkitEntries) {
+        printSizeLine(entry.path, entry.bytes);
+      }
+    }
+  }
+}
+
+async function printDockerContexts(ctx: IRuntimeContext) {
+  section('Docker Contexts');
+  progress('Listing Docker contexts and daemon usage.');
+  const version = await runDocker(ctx, ['--version'], 15);
+  if (version.code === 127) {
+    console.log('docker command not found');
+    return;
+  }
+
+  const contextList = await runDocker(ctx, ['context', 'ls'], 30);
+  if (contextList.stdout.trim()) {
+    console.log(contextList.stdout.trimEnd());
+  } else if (contextList.stderr.trim()) {
+    console.log(contextList.stderr.trim());
+  }
+
+  const contexts = await getDockerContexts(ctx);
+  if (!contexts.length) {
+    console.log(`No Docker contexts found for ${ctx.targetUser}.`);
+    return;
+  }
+
+  for (const dockerContext of contexts) {
+    await printDockerContextDetails(ctx, dockerContext);
+  }
+}
+
+function printCleanupHints(ctx: IRuntimeContext) {
+  section('Cleanup Commands To Consider');
+  console.log('Review first. Docker volume prune can delete database or build data stored in volumes.');
+  console.log('docker --context rootless system prune -a');
+  console.log('docker --context rootless builder prune -a');
+  console.log('docker --context rootless volume prune');
+  console.log('docker --context default system prune -a');
+  console.log('docker --context default builder prune -a');
+  console.log('docker --context default volume prune');
+  console.log(`rm -rf "${ctx.targetHome}/.cache/puppeteer" "${ctx.targetHome}/.cache/uv" "${ctx.targetHome}/.cache/deno" "${ctx.targetHome}/.cache/ms-playwright" "${ctx.targetHome}/.cache/yarn" "${ctx.targetHome}/.cache/pnpm" "${ctx.targetHome}/.cache/Cypress" "${ctx.targetHome}/.cache/mongodb-binaries"`);
+  console.log('pnpm store prune');
+  console.log('npm cache clean --force');
+  console.log(`# Review before deleting VS Code data: "${ctx.targetHome}/.vscode-server" "${ctx.targetHome}/.vscode" "${ctx.targetHome}/.config/Code"`);
+}
+
+function printHelp() {
+  console.log(`@git.zone/tsdisk v${commitinfo.version}`);
+  console.log('');
+  console.log('Usage:');
+  console.log('  tsdisk                 Run the disk usage diagnostic scan');
+  console.log('  tsdisk --json          Print project tool-cache diagnostics as JSON');
+  console.log('  tsdisk --help          Show this help');
+  console.log('  tsdisk --version       Show the version');
+  console.log('');
+  console.log('Environment:');
+  console.log('  DOCKER_TIMEOUT=<s>             Docker command timeout, default 60');
+  console.log('  DU_TIMEOUT=<s>                 du command timeout, default 300');
+  console.log('  NCDU_TIMEOUT=<s>               ncdu export timeout, default 900');
+  console.log('  TSDISK_NCDU_EXPORT=<path>      ncdu export path, default /tmp/tsdisk-ncdu-root-*.json');
+  console.log('  TSDISK_KEEP_NCDU_EXPORT=true   Keep the ncdu export after parsing');
+  console.log('  TSDISK_INSTALL_NCDU=true       Install ncdu with apt-get if missing');
+}
+
+export async function main() {
+  const ctx = await initContext();
+
+  await printDiskOverview(ctx);
+  await ensureSudo(ctx);
+  await printNcduInsights(ctx);
+
+  await printDuTree(ctx, 'Top-Level Root Breakdown', '/', true);
+  await printKnownSizes(ctx, 'Known Root Areas', [
+    { label: 'home', path: '/home' },
+    { label: 'var', path: '/var' },
+    { label: 'usr', path: '/usr' },
+    { label: 'opt', path: '/opt' },
+    { label: 'root', path: '/root' },
+    { label: 'target home', path: ctx.targetHome },
+  ]);
+
+  await printDuTree(ctx, 'Target Home Breakdown', ctx.targetHome, true);
+  await printDuTree(ctx, 'Target Local Share Breakdown', `${ctx.targetHome}/.local/share`, true);
+  await printDuTree(ctx, 'Target Cache Breakdown', `${ctx.targetHome}/.cache`, true);
+  await printConfiguredToolPaths(ctx);
+  await printProjectToolCacheDiagnostics(ctx);
+  await printKnownSizes(ctx, 'Known User Caches', [
+    { label: 'rootless Docker data', path: `${ctx.targetHome}/.local/share/docker` },
+    { label: 'pnpm store', path: `${ctx.targetHome}/.local/share/pnpm` },
+    { label: 'pnpm cache', path: `${ctx.targetHome}/.cache/pnpm` },
+    { label: 'legacy pnpm store', path: `${ctx.targetHome}/.pnpm-store` },
+    { label: 'npm directory', path: `${ctx.targetHome}/.npm` },
+    { label: 'npm content cache', path: `${ctx.targetHome}/.npm/_cacache` },
+    { label: 'node-gyp cache', path: `${ctx.targetHome}/.cache/node-gyp` },
+    { label: 'corepack cache', path: `${ctx.targetHome}/.cache/node/corepack` },
+    { label: 'Puppeteer Chrome', path: `${ctx.targetHome}/.cache/puppeteer` },
+    { label: 'Playwright browsers', path: `${ctx.targetHome}/.cache/ms-playwright` },
+    { label: 'Deno cache', path: `${ctx.targetHome}/.cache/deno` },
+    { label: 'uv Python cache', path: `${ctx.targetHome}/.cache/uv` },
+    { label: 'Yarn cache', path: `${ctx.targetHome}/.cache/yarn` },
+    { label: 'Cypress', path: `${ctx.targetHome}/.cache/Cypress` },
+    { label: 'MongoDB binaries', path: `${ctx.targetHome}/.cache/mongodb-binaries` },
+    { label: 'VS Code Server', path: `${ctx.targetHome}/.vscode-server` },
+    { label: 'VS Code Server extensions', path: `${ctx.targetHome}/.vscode-server/extensions` },
+    { label: 'VS Code Server binaries', path: `${ctx.targetHome}/.vscode-server/bin` },
+    { label: 'VS Code user data', path: `${ctx.targetHome}/.vscode` },
+    { label: 'VS Code local extensions', path: `${ctx.targetHome}/.vscode/extensions` },
+    { label: 'VS Code config', path: `${ctx.targetHome}/.config/Code` },
+    { label: 'VS Code workspace storage', path: `${ctx.targetHome}/.config/Code/User/workspaceStorage` },
+    { label: 'VS Code cached data', path: `${ctx.targetHome}/.config/Code/CachedData` },
+    { label: 'VS Code extension VSIX cache', path: `${ctx.targetHome}/.config/Code/CachedExtensionVSIXs` },
+    { label: 'VS Code service worker cache', path: `${ctx.targetHome}/.config/Code/Service Worker/CacheStorage` },
+    { label: 'Rust toolchains', path: `${ctx.targetHome}/.rustup` },
+  ]);
+
+  await printDuTree(ctx, 'Var Breakdown', '/var', true);
+  await printDuTree(ctx, 'Var Lib Breakdown', '/var/lib', true);
+  await printKnownSizes(ctx, 'Known System Data', [
+    { label: 'root Docker data', path: '/var/lib/docker' },
+    { label: 'containerd', path: '/var/lib/containerd' },
+    { label: 'onebox', path: '/var/lib/onebox' },
+    { label: 'ClickHouse data', path: '/var/lib/onebox/clickhouse' },
+    { label: 'libvirt', path: '/var/lib/libvirt' },
+    { label: 'snapd', path: '/var/lib/snapd' },
+    { label: 'system logs', path: '/var/log' },
+  ]);
+
+  await printJournalUsage(ctx);
+  await printDeletedOpenFiles(ctx);
+  await printDockerContexts(ctx);
+  await printSpecializedToolHints();
+  printCleanupHints(ctx);
+}
+
+export async function runCli(args = process.argv.slice(2)) {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(commitinfo.version);
+    return;
+  }
+
+  if (args.includes('--json')) {
+    try {
+      const ctx = await initContext();
+      const findings = await collectProjectToolCacheDiagnostics(ctx);
+      console.log(JSON.stringify({ toolCaches: findings }, null, 2));
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  try {
+    await main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}