@git.zone/tsdisk 1.1.0 → 1.3.0

package/ts/tsdisk.cli.ts

@@ -1,26 +1,32 @@
 import * as plugins from './tsdisk.plugins.js';
 import { commitinfo } from './00_commitinfo_data.js';
+import { scanWorkspace, type IWorkspaceScanOptions, type IScanIssue } from './tsdisk.scan.js';
+import { parseCliOptions, createCleanupPlan, type ICliOptions } from './tsdisk.cleanup.js';
+import { measureDiskUsage, normalizeScanRoots, type IUsageReport } from './tsdisk.usage.js';
+import { DiskProgressReporter, estimateReclaimableSpace, formatBytes, type IDiskProgress } from './tsdisk.progress.js';
+export { formatBytes } from './tsdisk.progress.js';
+export type { IWorkspaceScanOptions } from './tsdisk.scan.js';
 import {
   classifyToolCachePath,
-  parseToolCacheMarker,
-  toolCacheMarkerFile,
   type IToolCacheFinding,
-  type IToolCacheMarker,
 } from './tsdisk.toolcaches.js';
 
 interface ICommandResult {
   code: number;
   stdout: string;
   stderr: string;
+  truncated?: boolean;
 }
 
 interface IRunOptions {
   asRoot?: boolean;
   asTargetUser?: boolean;
   timeoutSeconds?: number;
+  cwd?: string;
 }
 
 export interface IRuntimeContext {
+  onProgress?: (progress: Partial<IDiskProgress>) => void;
   runningAsRoot: boolean;
   sudoAvailable: boolean;
   sudoChecked: boolean;
@@ -51,11 +57,6 @@ interface INcduParseResult {
   insights: INcduInsight[];
 }
 
-export interface IWorkspaceScanOptions {
-  maxDepth: number;
-  timeoutMs: number;
-  maxEntries: number;
-}
 
 const decoder = new TextDecoder();
 const maxCapturedOutputBytes = 64 * 1024 * 1024;
@@ -92,24 +93,6 @@ 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}`);
 }
@@ -209,6 +192,7 @@ function commandResultFromCapture(code: number, stdout: ICaptureState, stderr: I
     truncationMessages.push(`stderr truncated after ${formatBytes(maxCapturedOutputBytes)}`);
   }
   if (truncationMessages.length) {
+    result.truncated = true;
     result.stderr = [result.stderr.trimEnd(), `[tsdisk] ${truncationMessages.join('; ')}.`]
       .filter(Boolean)
       .join('\n');
@@ -525,6 +509,7 @@ async function runRootInteractive(
   args: string[],
   timeoutSeconds?: number,
 ): Promise<number> {
+  ctx.onProgress?.({ stage: `${command} ${args.slice(0, 3).join(' ')}` });
   let executable = command;
   let finalArgs = args;
 
@@ -563,6 +548,7 @@ async function runCommand(
   args: string[],
   options: IRunOptions = {},
 ): Promise<ICommandResult> {
+  ctx.onProgress?.({ stage: `${command} ${args.slice(0, 3).join(' ')}` });
   let executable = command;
   let finalArgs = [...args];
   const env: NodeJS.ProcessEnv = {};
@@ -591,12 +577,13 @@ async function runCommand(
   }
 
   if (options.timeoutSeconds && options.timeoutSeconds > 0) {
-    finalArgs = [`${options.timeoutSeconds}s`, executable, ...finalArgs];
+    finalArgs = ['--kill-after=5s', `${options.timeoutSeconds}s`, executable, ...finalArgs];
     executable = 'timeout';
   }
 
   return await new Promise<ICommandResult>((resolve) => {
     const child = plugins.spawn(executable, finalArgs, {
+      cwd: options.cwd,
       env: {
         ...process.env,
         ...env,
@@ -679,119 +666,8 @@ async function pathExists(path: string): Promise<boolean> {
   }
 }
 
-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()];
+export async function collectToolCachePathsFromRoot(root: string, options: IWorkspaceScanOptions): Promise<IToolCacheFinding[]> {
+  return (await scanWorkspace(root, options)).findings;
 }
 
 async function getWorkspaceRoots(): Promise<string[]> {
@@ -803,57 +679,46 @@ async function getWorkspaceRoots(): Promise<string[]> {
   if (cwd && cwd !== '/') {
     roots.add(cwd);
   }
-  return [...roots];
+  return await normalizeScanRoots([...roots]);
 }
 
-export async function collectProjectToolCacheDiagnostics(ctx: IRuntimeContext): Promise<IToolCacheFinding[]> {
-  const roots = await getWorkspaceRoots();
+export async function collectProjectToolCacheReport(ctx: IRuntimeContext, roots?: string[]) {
   const findings: IToolCacheFinding[] = [];
-  for (const root of roots) {
-    const rootFindings = await collectToolCachePathsFromRoot(root, {
-      maxDepth: 8,
-      timeoutMs: 45_000,
-      maxEntries: 50_000,
+  const issues: IScanIssue[] = [];
+  const issueCounts: Partial<Record<IScanIssue['reason'], number>> = {};
+  const usagePriorityPaths: string[] = [];
+  const scanRoots = await normalizeScanRoots(roots?.length ? roots : await getWorkspaceRoots());
+  for (const root of scanRoots) {
+    const result = await scanWorkspace(root, { maxDepth: 8, timeoutMs: 45_000, maxEntries: 50_000,
+      onProgress: (partial) => ctx.onProgress?.({ stage: `discovering ${root}`, cacheCount: findings.length + partial.findings.length, reclaim: estimateReclaimableSpace([...findings, ...partial.findings]) }),
     });
-    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);
+    findings.push(...result.findings);
+    usagePriorityPaths.push(...result.usagePriorityPaths);
+    issues.push(...result.issues);
+    for (const [reason, count] of Object.entries(result.issueCounts)) issueCounts[reason] = (issueCounts[reason] ?? 0) + count;
+  }
+  const unique = [...new Map(findings.map((finding) => [plugins.path.resolve(finding.path), finding])).values()];
+  const deadline = Date.now() + toolCacheSizingTimeoutMs;
+  for (const [index, finding] of unique.entries()) {
+    if (index >= toolCacheSizingLimit || Date.now() >= deadline) {
+      issues.push({ path: finding.path, reason: 'size-unavailable', detail: 'Sizing budget exhausted.' });
       continue;
     }
-    const size = await readDuTotal(ctx, finding.path, ctx.sudoAvailable);
-    sizedFindings.push({
-      ...finding,
-      bytes: size?.bytes,
+    const result = await runCommand(ctx, 'du', ['-sx', '--block-size=1', '--', finding.path], {
+      asRoot: ctx.sudoAvailable, timeoutSeconds: Math.max(1, Math.min(ctx.duTimeoutSeconds, Math.floor((deadline - Date.now()) / 1000))),
     });
+    const size = result.code === 0 ? parseDuOutput(result.stdout)[0] : undefined;
+    if (size) finding.bytes = size.bytes;
+    else issues.push({ path: finding.path, reason: 'size-unavailable', detail: result.stderr.trim() || 'du failed or returned no size.' });
+    ctx.onProgress?.({ cacheCount: unique.length, reclaim: estimateReclaimableSpace(unique) });
   }
-
-  return sizedFindings.sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0));
+  issueCounts['size-unavailable'] = issues.filter((issue) => issue.reason === 'size-unavailable').length;
+  ctx.onProgress?.({ cacheCount: unique.length, reclaim: estimateReclaimableSpace(unique) });
+  return { roots: scanRoots, toolCaches: unique.sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0)), usagePriorityPaths, issues, issueCounts, complete: issues.length === 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}`);
-  }
+export async function collectProjectToolCacheDiagnostics(ctx: IRuntimeContext): Promise<IToolCacheFinding[]> {
+  return (await collectProjectToolCacheReport(ctx)).toolCaches;
 }
 
 async function pathExistsForDu(ctx: IRuntimeContext, path: string, asRoot: boolean): Promise<boolean> {
@@ -1604,7 +1469,16 @@ function printHelp() {
   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 scan [--root PATH] [--json]  Bounded diagnostics; repeat --root for multiple workspaces');
+  console.log('  tsdisk --json          Full diagnostic report including toolCaches, sections, and scan issues');
+  console.log('  tsdisk cleanup [--root PROJECT] [--only rust,docker,pnpm] [--days 14]');
+  console.log('                         Preview owning-tool cleanup; defaults to rust,docker in the current project');
+  console.log('  tsdisk cleanup --apply [--yes]     Execute after review; JSON/noninteractive execution requires --yes');
+  console.log('  --dry-run              Explicit cleanup preview; cannot be combined with --apply');
+  console.log('  Cleanup uses project-installed tsrust/tsdocker and pnpm store prune, without sudo or raw cache deletion.');
+  console.log('  --days applies only to Rust targets. Docker uses its owner checks; pnpm uses reference tracking.');
+  console.log('  scan exit codes: 0 complete, 2 incomplete, 1 invalid input/failure.');
+  console.log('  Live progress updates every 5 seconds (stderr with --json). Potential cleanup requires owner review.');
   console.log('  tsdisk --help          Show this help');
   console.log('  tsdisk --version       Show the version');
   console.log('');
@@ -1619,8 +1493,19 @@ function printHelp() {
 
 export async function main() {
   const ctx = await initContext();
+  const reporter = new DiskProgressReporter((line) => console.log(line));
+  ctx.onProgress = (update) => reporter.update(update);
+  reporter.start();
+  try { await runHumanReport(ctx); }
+  finally { reporter.stop(); }
+}
 
+async function runHumanReport(ctx: IRuntimeContext) {
   await printDiskOverview(ctx);
+  const caches = await collectProjectToolCacheReport(ctx);
+  const usage = await collectWorkspaceUsage(ctx, caches);
+  printWorkspaceUsage(usage);
+  console.log(`Potential cleanup: ${formatBytes(estimateReclaimableSpace(caches.toolCaches).candidateBytes)} of cache candidates; owner review required. Confirmed reclaimable: unknown.`);
   await ensureSudo(ctx);
   await printNcduInsights(ctx);
 
@@ -1638,7 +1523,9 @@ export async function main() {
   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);
+  section('Project Tool Cache Diagnostics');
+  for (const cache of caches.toolCaches) console.log(`${cache.bytes === undefined ? 'unknown' : formatBytes(cache.bytes)}  ${JSON.stringify(cache.path)}\n  ${cache.suggestedCleanupCommand}`);
+  if (!caches.complete) console.log(`Discovery incomplete: ${JSON.stringify(caches.issueCounts)}`);
   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` },
@@ -1687,30 +1574,160 @@ export async function main() {
   printCleanupHints(ctx);
 }
 
-export async function runCli(args = process.argv.slice(2)) {
-  if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
-    return;
-  }
+export interface IDiagnosticSection {
+  name: string;
+  kind?: 'command' | 'derived';
+  derivedFrom?: 'usage.entries';
+  command: string;
+  args: string[];
+  result: ICommandResult;
+  complete: boolean;
+}
 
-  if (args.includes('--version') || args.includes('-v')) {
-    console.log(commitinfo.version);
-    return;
+export function diagnosticCommandComplete(command: string, result: ICommandResult): boolean {
+  return !result.truncated && !result.stderr.trim() && (result.code === 0 || (command === 'lsof' && result.code === 1));
+}
+
+async function collectWorkspaceUsage(ctx: IRuntimeContext, caches: Awaited<ReturnType<typeof collectProjectToolCacheReport>>) {
+  ctx.onProgress?.({ stage: 'measuring workspace files and directories' });
+  const usage = await measureDiskUsage(caches.roots, {
+    timeoutSeconds: ctx.duTimeoutSeconds,
+    trackedPaths: caches.toolCaches.map((finding) => finding.path),
+    priorityPaths: caches.usagePriorityPaths,
+    onProgress: (partial) => ctx.onProgress?.({
+      stage: 'measuring workspace files and directories', measuredBytes: partial.measuredBytes,
+      largest: partial.snapshot().filter((entry) => !caches.roots.includes(entry.path)).slice(0, 3),
+    }),
+  });
+  return usage;
+}
+
+function printWorkspaceUsage(usage: IUsageReport) {
+  section(`Workspace Disk Usage (${usage.complete ? 'complete' : 'partial; + means a lower bound'})`);
+  for (const entry of usage.entries.slice(0, 30)) console.log(`${formatBytes(entry.bytes)}${entry.complete ? '' : '+'}  ${JSON.stringify(entry.path)}`);
+  if (usage.stderr) console.log(firstLines(usage.stderr));
+}
+
+export async function collectDiskReport(ctx: IRuntimeContext, roots?: string[]) {
+  const caches = await collectProjectToolCacheReport(ctx, roots);
+  const usage = await collectWorkspaceUsage(ctx, caches);
+  const reclaim = estimateReclaimableSpace(caches.toolCaches);
+  const sections: IDiagnosticSection[] = [];
+  const deadline = Date.now() + 120_000;
+  const inspect = async (name: string, command: string, args: string[]) => {
+    const result = Date.now() >= deadline
+      ? { code: 124, stdout: '', stderr: 'Diagnostic command budget exhausted.' }
+      : await runCommand(ctx, command, args, { timeoutSeconds: Math.max(1, Math.min(15, Math.floor((deadline - Date.now()) / 1000))) });
+    const complete = diagnosticCommandComplete(command, result);
+    sections.push({ name, kind: 'command', command, args, result, complete });
+    return result;
+  };
+  await inspect('filesystems', 'df', ['-hT']);
+  await inspect('mounts', 'findmnt', ['--json']);
+  for (const root of caches.roots) {
+    const entries = usage.entries.filter((entry) => entry.path === root || entry.path.startsWith(root === '/' ? '/' : `${root}/`));
+    const truncated = entries.length > 100;
+    sections.push({ name: `workspace:${root}`, kind: 'derived', derivedFrom: 'usage.entries', command: 'usage-summary', args: [], complete: usage.complete && !truncated,
+      result: { code: usage.code, stderr: usage.stderr, truncated, stdout: entries.slice(0, 100).map((entry) => `${entry.bytes}\t${entry.path}\n`).join('') },
+    });
+  }
+  for (const path of ['/', ctx.targetHome, `${ctx.targetHome}/.cache`, `${ctx.targetHome}/.local/share`, '/var', '/var/lib']) {
+    await inspect(`usage:${path}`, 'du', ['-x', '--max-depth=1', '--block-size=1', '--', path]);
+  }
+  await inspect('pnpm-store', 'pnpm', ['store', 'path']);
+  await inspect('journal', 'journalctl', ['--disk-usage']);
+  await inspect('deleted-open-files', 'lsof', ['-nP', '+L1']);
+  const contexts = await inspect('docker-contexts', 'docker', ['context', 'ls', '--format', '{{.Name}}']);
+  if (contexts.code === 0) {
+    for (const context of contexts.stdout.trim().split(/\r?\n/).filter(Boolean)) {
+      await inspect(`docker:${context}`, 'docker', ['--context', context, 'system', 'df', '-v']);
+    }
   }
+  return { schemaVersion: 1, generatedAt: new Date().toISOString(), ...caches, usage, reclaim, sections, complete: caches.complete && usage.complete && sections.every((section) => section.complete) };
+}
 
-  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;
+async function runCleanup(options: ICliOptions) {
+  const plan = await createCleanupPlan(options);
+  const ctx = await initContext();
+  const previews: Array<{ action: number; result: ICommandResult }> = [];
+  const results: Array<{ action: number; result: ICommandResult }> = [];
+  const print = () => {
+    if (options.json) console.log(JSON.stringify({ ...plan, previews, results }, null, 2));
+    else {
+      console.log(plan.dryRun ? 'Cleanup preview (no deletion)' : 'Cleanup plan');
+      plan.actions.forEach((action, index) => {
+        console.log(`[${index + 1}] ${action.category}: ${action.cwd}`);
+        console.log(`    ${action.scope}`);
+        console.log(`    command: ${JSON.stringify([action.command, ...action.applyArgs])}`);
+        if (action.blocked) console.log(`    blocked: ${action.blocked}`);
+      });
+      for (const item of [...previews, ...results]) {
+        console.log(`[${item.action + 1}] exit ${item.result.code}`);
+        if (item.result.stdout) console.log(item.result.stdout.trimEnd());
+        if (item.result.stderr) console.error(item.result.stderr.trimEnd());
+      }
     }
+  };
+  if (options.apply && options.json && !options.yes) throw new Error('JSON cleanup requires --apply --yes to execute.');
+  // Complete all previews before any apply command. Missing tools and failed previews block the batch.
+  for (const [index, action] of plan.actions.entries()) {
+    if (action.blocked) continue;
+    const result = await runCommand(ctx, action.command, action.previewArgs ?? ['store', 'path'], { cwd: action.cwd, timeoutSeconds: 120 });
+    previews.push({ action: index, result });
+  }
+  if (plan.actions.some((action) => action.blocked) || previews.some((preview) => preview.result.code !== 0 || preview.result.truncated)) {
+    print();
+    process.exitCode = 1;
     return;
   }
+  if (!options.apply) { print(); return; }
+  if (!options.json) print();
+  if (!options.yes) {
+    if (!process.stdin.isTTY) throw new Error('Noninteractive cleanup requires --apply --yes.');
+    if (!await promptYesNo('Run the listed owning-tool cleanup commands?', false)) return;
+  }
+  for (const [index, action] of plan.actions.entries()) {
+    const result = await runCommand(ctx, action.command, action.applyArgs, { cwd: action.cwd, timeoutSeconds: 240 });
+    results.push({ action: index, result });
+    if (result.code !== 0) { process.exitCode = 1; break; }
+  }
+  // JSON emits one complete document; text can show the plan before confirmation.
+  if (options.json) print();
+  else {
+    for (const item of results) {
+      console.log(`[${item.action + 1}] cleanup exit ${item.result.code}`);
+      if (item.result.stdout) console.log(item.result.stdout.trimEnd());
+      if (item.result.stderr) console.error(item.result.stderr.trimEnd());
+    }
+  }
+}
 
+export async function runCli(args = process.argv.slice(2)) {
   try {
+    const options = parseCliOptions(args);
+    if (options.command === 'help') { printHelp(); return; }
+    if (options.command === 'version') { console.log(commitinfo.version); return; }
+    if (options.command === 'cleanup') { await runCleanup(options); return; }
+    if (options.command === 'scan') {
+      const reporter = new DiskProgressReporter((line) => options.json ? process.stderr.write(`${line}\n`) : console.log(line));
+      const ctx = await initContext();
+      ctx.onProgress = (update) => reporter.update(update);
+      reporter.start();
+      let report: Awaited<ReturnType<typeof collectDiskReport>>;
+      try { report = await collectDiskReport(ctx, options.roots); }
+      finally { reporter.stop(); }
+      if (options.json) console.log(JSON.stringify(report, null, 2));
+      else {
+        console.log(`Scan ${report.complete ? 'complete' : 'incomplete'}: ${report.toolCaches.length} tool caches`);
+        printWorkspaceUsage(report.usage);
+        console.log(`Potential cleanup: ${formatBytes(report.reclaim.candidateBytes)} (${report.reclaim.unknownSizeCount} caches unsized); owner review required. Confirmed reclaimable: unknown.`);
+        for (const finding of report.toolCaches) console.log(`${finding.bytes === undefined ? 'unknown' : formatBytes(finding.bytes)}  [${finding.risk}] ${finding.path}\n  ${finding.suggestedCleanupCommand}`);
+        for (const issue of report.issues) console.log(`${issue.reason}: ${issue.path}: ${issue.detail}`);
+        for (const section of report.sections) console.log(`\n${section.name} [${section.complete ? 'complete' : 'incomplete'}]\n${section.result.stdout}${section.result.stderr}`);
+      }
+      if (!report.complete) process.exitCode = 2;
+      return;
+    }
     await main();
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));

package/ts/tsdisk.plugins.ts

@@ -1,11 +1,12 @@
 // node native
 import { spawn } from 'node:child_process';
-import { createReadStream, type ReadStream } from 'node:fs';
+import { constants, createReadStream, type ReadStream } from 'node:fs';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 
 export {
+  constants,
   createInterface,
   createReadStream,
   fs,

package/ts/tsdisk.progress.ts

@@ -0,0 +1,78 @@
+import { containsPath, type IUsageEntry } from './tsdisk.usage.js';
+import type { IToolCacheFinding } from './tsdisk.toolcaches.js';
+
+export interface IReclaimEstimate {
+  candidateBytes: number;
+  unknownSizeCount: number;
+  protectedCount: number;
+  confirmedReclaimableBytes: null;
+  status: 'owner-review-required';
+}
+
+/** Do not sum parents and children, or treat a protected descendant as removable. */
+export function estimateReclaimableSpace(findings: IToolCacheFinding[]): IReclaimEstimate {
+  const protectedPaths = findings.filter((finding) => finding.marker?.safeToPrune === false).map((finding) => finding.path);
+  const candidates = findings.filter((finding) => !protectedPaths.some((path) => containsPath(path, finding.path) || containsPath(finding.path, path)));
+  const selected: IToolCacheFinding[] = [];
+  for (const finding of [...candidates].sort((a, b) => a.path.length - b.path.length)) {
+    if (finding.bytes === undefined || selected.some((parent) => containsPath(parent.path, finding.path))) continue;
+    selected.push(finding);
+  }
+  return {
+    candidateBytes: selected.reduce((sum, finding) => sum + (finding.bytes ?? 0), 0),
+    unknownSizeCount: candidates.filter((finding) => finding.bytes === undefined).length,
+    protectedCount: protectedPaths.length,
+    confirmedReclaimableBytes: null,
+    status: 'owner-review-required',
+  };
+}
+
+export interface IDiskProgress {
+  stage: string;
+  cacheCount: number;
+  measuredBytes: number;
+  reclaim: IReclaimEstimate;
+  largest: IUsageEntry[];
+}
+
+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 index = 0;
+  while (value >= 1024 && index < units.length - 1) { value /= 1024; index++; }
+  return `${value.toFixed(index === 0 || value >= 100 ? 0 : value >= 10 ? 1 : 2)} ${units[index]}`;
+}
+
+/** Timer ownership is explicit; callers stop it in finally even on failure. */
+export class DiskProgressReporter {
+  private timer?: ReturnType<typeof setInterval>;
+  private startedAt = Date.now();
+  private state: IDiskProgress = { stage: 'starting', cacheCount: 0, measuredBytes: 0, reclaim: estimateReclaimableSpace([]), largest: [] };
+
+  constructor(private write: (line: string) => void) {}
+
+  public update(update: Partial<IDiskProgress>) { Object.assign(this.state, update); }
+
+  public start() {
+    if (this.timer) return;
+    this.startedAt = Date.now();
+    this.print();
+    this.timer = setInterval(() => this.print(), 5000);
+    this.timer.unref();
+  }
+
+  private print() {
+    const state = this.state;
+    const top = state.largest.slice(0, 3).map((entry) => `${formatBytes(entry.bytes)}${entry.complete ? '' : '+'} ${JSON.stringify(entry.path)}`).join('; ');
+    this.write(`[tsdisk ${Math.floor((Date.now() - this.startedAt) / 1000)}s] ${state.stage} | measured ${formatBytes(state.measuredBytes)} | ${state.cacheCount} caches | potential cleanup ${formatBytes(state.reclaim.candidateBytes)} (owner review; ${state.reclaim.unknownSizeCount} unsized) | confirmed reclaimable: unknown${top ? ` | largest: ${top}` : ''}`);
+  }
+
+  public stop(stage = 'finished') {
+    if (!this.timer) return;
+    clearInterval(this.timer);
+    this.timer = undefined;
+    this.state.stage = stage;
+    this.print();
+  }
+}