@git.zone/tsdisk 1.1.0 → 1.3.0

package/dist_ts/tsdisk.usage.js

@@ -0,0 +1,194 @@
+import * as plugins from './tsdisk.plugins.js';
+export function containsPath(parent, child) {
+    const relative = plugins.path.relative(parent, child);
+    return relative === '' || (!relative.startsWith(`..${plugins.path.sep}`) && relative !== '..' && !plugins.path.isAbsolute(relative));
+}
+/** Preserve explicitly selected nested mounts; subsume overlapping roots on the same device. */
+export async function normalizeScanRoots(roots) {
+    const unique = [...new Set(roots.map((root) => plugins.path.resolve(root)))].sort((a, b) => a.length - b.length || a.localeCompare(b));
+    const accepted = [];
+    for (const path of unique) {
+        const stat = await plugins.fs.lstat(path).catch(() => undefined);
+        const real = await plugins.fs.realpath(path).catch(() => undefined);
+        const dev = stat?.isDirectory() && real === path ? stat.dev : undefined;
+        if (dev !== undefined && accepted.some((parent) => parent.dev === dev && containsPath(parent.path, path)))
+            continue;
+        accepted.push({ path, dev });
+    }
+    return accepted.map((root) => root.path);
+}
+/** GNU du emits files immediately and inclusive directory totals on completion.
+ * Reconcile each completed directory with its observed children, rather than
+ * adding inclusive totals twice. The active ancestor chain survives a timeout.
+ */
+export class UsageAccumulator {
+    roots;
+    trackedPaths;
+    priorityPaths;
+    pending = '';
+    active = new Map();
+    largest = new Map();
+    tracked = new Map();
+    minimumLargestBytes = 0;
+    operandBytes = new Map();
+    accountingRoots;
+    currentRoot;
+    measuredBytes = 0;
+    records = 0;
+    currentPath = '';
+    constructor(roots, trackedPaths = new Set(), priorityPaths = []) {
+        this.roots = roots;
+        this.trackedPaths = trackedPaths;
+        this.priorityPaths = priorityPaths;
+        this.roots = [...roots].sort((a, b) => b.length - a.length);
+        if (roots.some((root) => plugins.path.resolve(root) !== root) || priorityPaths.some((path) => !roots.some((root) => root !== path && containsPath(root, path)))) {
+            throw new Error('Usage accounting requires normalized roots and strict descendant priority paths.');
+        }
+        this.accountingRoots = [...priorityPaths, ...roots].sort((a, b) => b.length - a.length);
+        this.trackedPaths = new Set([...trackedPaths, ...roots, ...priorityPaths]);
+    }
+    consume(chunk) {
+        this.pending += chunk;
+        let start = 0;
+        for (;;) {
+            const end = this.pending.indexOf('\0', start);
+            if (end < 0)
+                break;
+            this.record(this.pending.slice(start, end));
+            start = end + 1;
+        }
+        this.pending = this.pending.slice(start);
+        if (this.pending.length > 1024 * 1024)
+            throw new Error('Invalid du record exceeds 1 MiB.');
+    }
+    record(record) {
+        const separator = record.indexOf('\t');
+        const bytes = Number(record.slice(0, separator));
+        const path = record.slice(separator + 1);
+        const matches = (candidate) => path === candidate || path.startsWith(candidate === '/' ? '/' : `${candidate}/`);
+        const root = this.currentRoot && matches(this.currentRoot) ? this.currentRoot : this.accountingRoots.find(matches);
+        if (separator < 1 || !Number.isSafeInteger(bytes) || bytes < 0 || !plugins.path.isAbsolute(path) || !root)
+            throw new Error('Invalid du output.');
+        this.records++;
+        this.currentPath = path;
+        this.currentRoot = path === root ? undefined : root;
+        const delta = bytes - (this.active.get(path) ?? 0);
+        this.active.delete(path);
+        this.measuredBytes += delta;
+        this.operandBytes.set(root, (this.operandBytes.get(root) ?? 0) + delta);
+        if (path !== root) {
+            for (let parent = plugins.path.dirname(path);; parent = plugins.path.dirname(parent)) {
+                this.active.set(parent, (this.active.get(parent) ?? 0) + delta);
+                if (parent === root)
+                    break;
+            }
+        }
+        const entry = { path, bytes, complete: true };
+        if (this.trackedPaths.has(path))
+            this.tracked.set(path, entry);
+        // Retain only the largest completed paths, not millions of file records.
+        if (this.largest.size < 100 || bytes > this.minimumLargestBytes) {
+            this.largest.set(path, entry);
+            if (this.largest.size > 100) {
+                const sorted = [...this.largest.values()].sort((a, b) => b.bytes - a.bytes);
+                this.largest = new Map(sorted.slice(0, 100).map((item) => [item.path, item]));
+            }
+            this.minimumLargestBytes = Math.min(...[...this.largest.values()].map((item) => item.bytes));
+        }
+    }
+    snapshot() {
+        const entries = new Map([...this.largest, ...this.tracked].map(([path, entry]) => [path, { ...entry }]));
+        for (const [path, bytes] of this.active)
+            entries.set(path, { path, bytes, complete: false });
+        // du charges an overlapping subtree to its first operand and omits it from
+        // later ancestor totals. Restore those inclusive totals for display only;
+        // measuredBytes remains the native, deduplicated sum of operand contributions.
+        for (const priority of this.priorityPaths) {
+            const bytes = this.operandBytes.get(priority);
+            const root = this.roots.find((candidate) => containsPath(candidate, priority));
+            if (bytes === undefined || !root)
+                continue;
+            for (let parent = plugins.path.dirname(priority);; parent = plugins.path.dirname(parent)) {
+                const entry = entries.get(parent) ?? { path: parent, bytes: 0, complete: false };
+                entry.bytes += bytes;
+                entries.set(parent, entry);
+                if (parent === root)
+                    break;
+            }
+        }
+        return [...entries.values()].sort((a, b) => b.bytes - a.bytes);
+    }
+    get endedOnRecordBoundary() { return this.pending.length === 0; }
+}
+/** One streaming native pass; no output export, no symlink traversal, no raw file content reads. */
+export async function measureDiskUsage(roots, options) {
+    if (!Number.isFinite(options.timeoutSeconds) || options.timeoutSeconds <= 0)
+        throw new Error('Invalid usage timeout.');
+    const valid = [];
+    const devices = new Map();
+    const errors = [];
+    for (const root of await normalizeScanRoots(roots)) {
+        try {
+            const stat = await plugins.fs.lstat(root);
+            if (!stat.isDirectory() || await plugins.fs.realpath(root) !== root)
+                throw new Error('Usage roots must be real directories without symlink ancestors.');
+            valid.push(root);
+            devices.set(root, stat.dev);
+        }
+        catch (error) {
+            errors.push(`${root}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const priorities = [];
+    for (const path of await normalizeScanRoots(options.priorityPaths ?? [])) {
+        const root = [...valid].reverse().find((root) => root !== path && containsPath(root, path));
+        if (!root)
+            continue;
+        const real = await plugins.fs.realpath(path).catch(() => undefined);
+        const stat = await plugins.fs.lstat(path).catch(() => undefined);
+        if (real === path && stat?.isDirectory() && stat.dev === devices.get(root))
+            priorities.push(path);
+    }
+    // Measure retained project artifacts before broad dependency/source trees.
+    // This changes order only: remaining paths are visited by the final roots.
+    priorities.sort((a, b) => b.split(plugins.path.sep).length - a.split(plugins.path.sep).length || a.localeCompare(b));
+    let argumentBytes = valid.reduce((sum, path) => sum + Buffer.byteLength(path) + 1, 0);
+    const argumentLimit = priorities.findIndex((path) => (argumentBytes += Buffer.byteLength(path) + 1) > 128 * 1024);
+    if (argumentLimit >= 0)
+        priorities.splice(argumentLimit);
+    const usage = new UsageAccumulator(valid, new Set(options.trackedPaths), priorities);
+    let stderr = errors.join('\n');
+    let malformed = false;
+    const code = valid.length ? await new Promise((resolve) => {
+        const child = plugins.spawn('timeout', ['--kill-after=5s', `${options.timeoutSeconds}s`, 'du', '-a', '-0', '-x', '-B1', '--', ...priorities, ...valid], { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, LC_ALL: 'C' } });
+        child.stdout.setEncoding('utf8');
+        let lastNotification = 0;
+        child.stdout.on('data', (chunk) => {
+            if (malformed)
+                return;
+            try {
+                usage.consume(chunk);
+                if (Date.now() - lastNotification >= 250) {
+                    options.onProgress?.(usage);
+                    lastNotification = Date.now();
+                }
+            }
+            catch (error) {
+                malformed = true;
+                stderr += `\n${error instanceof Error ? error.message : String(error)}`;
+                // Signal timeout, which forwards termination to its managed process group.
+                child.kill('SIGTERM');
+            }
+        });
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => { if (stderr.length < 65536)
+            stderr += chunk.slice(0, 65536 - stderr.length); });
+        child.on('error', (error) => { stderr += `\n${error.message}`; });
+        child.on('close', (exitCode) => resolve(exitCode ?? 1));
+    }) : 1;
+    options.onProgress?.(usage);
+    const complete = code === 0 && !stderr.trim() && !malformed && usage.endedOnRecordBoundary;
+    const entries = usage.snapshot().map((entry) => ({ ...entry, complete: entry.complete && complete }));
+    return { roots: valid, measuredBytes: usage.measuredBytes, entries, records: usage.records, complete, code, stderr };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHNkaXNrLnVzYWdlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvdHNkaXNrLnVzYWdlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0scUJBQXFCLENBQUM7QUFrQi9DLE1BQU0sVUFBVSxZQUFZLENBQUMsTUFBYyxFQUFFLEtBQWE7SUFDeEQsTUFBTSxRQUFRLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsTUFBTSxFQUFFLEtBQUssQ0FBQyxDQUFDO0lBQ3RELE9BQU8sUUFBUSxLQUFLLEVBQUUsSUFBSSxDQUFDLENBQUMsUUFBUSxDQUFDLFVBQVUsQ0FBQyxLQUFLLE9BQU8sQ0FBQyxJQUFJLENBQUMsR0FBRyxFQUFFLENBQUMsSUFBSSxRQUFRLEtBQUssSUFBSSxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQztBQUN2SSxDQUFDO0FBRUQsZ0dBQWdHO0FBQ2hHLE1BQU0sQ0FBQyxLQUFLLFVBQVUsa0JBQWtCLENBQUMsS0FBZTtJQUN0RCxNQUFNLE1BQU0sR0FBRyxDQUFDLEdBQUcsSUFBSSxHQUFHLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxDQUFDLElBQUksRUFBRSxFQUFFLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDLE1BQU0sR0FBRyxDQUFDLENBQUMsTUFBTSxJQUFJLENBQUMsQ0FBQyxhQUFhLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUN2SSxNQUFNLFFBQVEsR0FBMEMsRUFBRSxDQUFDO0lBQzNELEtBQUssTUFBTSxJQUFJLElBQUksTUFBTSxFQUFFLENBQUM7UUFDMUIsTUFBTSxJQUFJLEdBQUcsTUFBTSxPQUFPLENBQUMs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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tsdisk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": false,
   "description": "A disk usage diagnostic CLI for finding large files, caches, logs, and Docker storage.",
   "main": "dist_ts/index.js",
@@ -20,9 +20,9 @@
     "license.md"
   ],
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^25.9.3"
+    "@git.zone/tsbuild": "^4.5.0",
+    "@git.zone/tstest": "^6.1.1",
+    "@types/node": "^26.5.1"
   },
   "scripts": {
     "test": "(pnpm run build && tstest test/ --verbose)",

package/readme.md

@@ -24,9 +24,11 @@ pnpm dlx @git.zone/tsdisk
 tsdisk
 ```
 
-The tool prints a structured report covering filesystem usage, top-level `du` breakdowns, known user and system cache paths, project-local tool caches on mounted workspaces such as `/mnt/data`, systemd journal usage, deleted open files, and Docker context storage.
+The tool prints a structured report covering filesystem usage, large files and directories on mounted workspaces such as `/mnt/data`, known user and system cache paths, project-local tool caches, systemd journal usage, deleted open files, and Docker context storage. Both the default human report and `scan` print live progress every five seconds, including the current stage, discovered cache count, measured workspace bytes, potential cleanup bytes, and the largest paths found so far.
 
-It asks for `sudo` because root-owned filesystem paths and deleted open files require elevated permissions. Cleanup commands are printed as suggestions only; `tsdisk` does not delete caches or prune Docker data.
+Potential cleanup is an estimate of measured cache candidates requiring owner review, not guaranteed free space. Explicitly protected caches and overlapping parent/child candidates are excluded from that estimate. Unknown sizes are counted separately. Hardlinks or shared filesystem extents can reduce actual savings. Backups, checkpoints, and worktrees appear as large disk consumers but are never automatically classified as removable. Confirmed reclaimable bytes remain unknown until the owning tool verifies cleanup eligibility.
+
+It asks for `sudo` because root-owned filesystem paths and deleted open files require elevated permissions. The default diagnostic command does not delete caches or prune Docker data. The explicit `cleanup` command previews owning-tool cleanup and requires `--apply` to execute it.
 
 ### Project Tool Cache Diagnostics
 
@@ -34,13 +36,14 @@ It asks for `sudo` because root-owned filesystem paths and deleted open files re
 
 - Deno self-extracting staging such as `dist/binaries/.*/.deno_compile_node_modules`
 - Release binary staging under `.nogit/release-binaries/.*/.deno_compile_node_modules`
-- tsbundle temp workspaces under `.nogit/tsbundle-temp`
+- tsbundle temp workspaces under `.nogit/tsbundle-temp` and `.nogit/tsbundle-temp-*`
+- Retained Rust matrix directories and renamed legacy Docker registries (report-only)
 - tsdocker local registry caches under `.nogit/docker-registry`
 - Rust target caches under `rust/target`, `ts_rust/target`, and marked `.nogit/tsrust-target`
 - Stopped `tsdocker-registry-*` containers and their bind mounts
 - Docker buildx state volumes with zero container links, as report-only findings
 
-Marked caches using `.gitzone-tool-cache.json` are classified as tool-owned. Unmarked legacy paths are report-only and do not receive destructive cleanup commands.
+Markers identify ownership, never prove inactivity. Marked caches require review; `safeToPrune: false` remains explicitly protected. No cache finding receives a raw `rm -rf` command. Unmarked legacy paths, bundle intermediates, and retained matrix runs remain report-only. Bundle cleanup belongs to tsbundle’s own stale-workspace lifecycle.
 
 ## Environment
 
@@ -53,31 +56,53 @@ Marked caches using `.gitzone-tool-cache.json` are classified as tool-owned. Unm
 | `TSDISK_KEEP_NCDU_EXPORT` | Keep the `ncdu` export for later browsing | unset |
 | `TSDISK_INSTALL_NCDU` | Install `ncdu` with `apt-get` if missing | prompt |
 
-## Commands
+## Structured Diagnostics
 
 ```bash
+tsdisk scan --root /mnt/data/foss.global --json
+tsdisk scan --root /mnt/data/project-a --root /mnt/data/project-b
 tsdisk --json
 tsdisk --help
 tsdisk --version
 ```
 
-`tsdisk --json` prints the project tool-cache diagnostics as structured JSON:
-
-```json
-{
-  "toolCaches": [
-    {
-      "path": "/mnt/data/project/.nogit/tsbundle-temp",
-      "ownerGuess": "@git.zone/tsbundle",
-      "kind": "bundle-temp-workspace",
-      "risk": "report-only",
-      "suggestedCleanupCommand": "report-only: verify ownership before removing \"/mnt/data/project/.nogit/tsbundle-temp\"",
-      "bytes": 123456
-    }
-  ]
-}
+`scan` and `--json` run bounded, noninteractive diagnostics without requesting sudo or installing tools. `--root` selects project-cache discovery and workspace size roots; host filesystem, home/cache, journal, deleted-open-file, and Docker diagnostics are still included. Without roots, discovery uses `/mnt/data` when present and the current directory. The original `tsdisk` human report remains available.
+
+The JSON object includes `schemaVersion`, `generatedAt`, `roots`, `toolCaches`, `issues`, `issueCounts`, `usage`, `reclaim`, `sections`, and `complete`. Sections with `kind: "command"` record the executed command, arguments, exit code, stdout, stderr, and completeness. Workspace sections have `kind: "derived"`, `derivedFrom: "usage.entries"`, and `command: "usage-summary"`; their text is a compatibility summary of at most 100 retained paths, not native command output. Capped summaries set `result.truncated: true` and `complete: false`. Use `usage.entries` for structured paths and partial-size flags. Missing tools, command warnings, and insufficient permissions remain visible. JSON stdout contains exactly one document; five-second progress updates go to stderr.
+
+`usage` records measured bytes, processed record count, the largest paths, cache paths, and completeness. It streams one native `du -a -0 -x -B1` pass over the selected roots, retaining partial ancestor totals even when a large directory exceeds the time budget. Discovered `.nogit` directories are measured first, so retained checkpoints and worktrees become visible before broad dependency trees. GNU du counts overlapping operands and hardlinks once; the report reconstructs inclusive ancestor totals without adding those bytes twice. `complete: false` sizes are lower bounds; human output marks them with `+`. Inclusive parent/child sizes must not be added together. File records are consumed as they arrive rather than retained in memory or exported to disk. The native pass includes dependencies, backups, and arbitrary large files. Overlapping roots on the same device are scanned once; explicitly selected nested mounts are retained.
+
+`reclaim.candidateBytes` counts measured cache candidates without parent/child overlap; `unknownSizeCount` counts unsized candidates. `confirmedReclaimableBytes` is `null` and `status` is `owner-review-required`: discovery does not run project-installed cleanup tools or establish inactivity.
+
+Cache discovery records read failures, invalid markers, symlinks, filesystem boundaries, and exhausted depth, entry, or time budgets. Unknown sizes stay absent rather than becoming zero. Symlink roots and roots with symlink ancestors are rejected. Standard dependency and generated-code directories are intentionally excluded. Cache byte sizes are allocated disk usage, not a promise of reclaimable space: parent/child findings and hardlinks may overlap.
+
+Cache discovery visits directories breadth first, so nearby projects precede deep worktrees. It is bounded to depth 8, 50,000 directory/symlink inspections, and 45 seconds per root. Ordinary source files do not consume the directory budget; each directory listing is capped at 4,096 entries so a huge flat directory cannot starve its siblings. `issueCounts` retains totals by reason; `issues` contains at most 200 discovery examples per root, plus sizing issues. Sizing has a 45-second budget and a 500-cache limit. Workspace usage has one `DU_TIMEOUT` budget (default 300 seconds, plus five seconds for termination). Additional command diagnostics have a 120-second total budget, with at most 15 seconds per command. Discovery limits are cooperative between filesystem operations. `scan` exits `0` for a complete report, `2` for an incomplete report, or `1` for invalid input/failure. Consumers of the earlier `--json` shape can still read `toolCaches` and workspace command sections.
+
+## Cleanup
+
+```bash
+# Project paths are explicit; cleanup never recurses across a workspace.
+tsdisk cleanup --root /mnt/data/project --only=docker
+# pnpm has no prune dry-run: preview identifies its configured store.
+tsdisk cleanup --root /mnt/data/project --only=pnpm --json
+# Execute only after reviewing the command and its scope.
+tsdisk cleanup --root /mnt/data/project --only=pnpm --apply --yes
 ```
 
+Cleanup defaults to a preview of `rust,docker` for the current project. `--dry-run` explicitly selects preview mode. Repeat `--root` to select multiple projects, and use `--only=rust,docker,pnpm` to choose categories. `pnpm` is opt-in because the configured store may be shared. Tsdisk never deletes a pnpm store directory.
+
+Rust requires `@git.zone/tsrust` 1.13.2 or later; Docker requires `@git.zone/tsdocker` 3.6.0 or later. Rust and Docker use their project-installed `node_modules/.bin/tsrust` and `tsdocker`; missing tools block the batch without downloading anything. Rust previews pass `--days 14` by default; `--days N` changes only Rust retention. Docker cleanup uses the owning tool’s identity, mount, and build checks; its abandoned-container scope can span projects in the current Docker context. Registry directories are project-local. Bundle, matrix, and legacy registry findings do not become execution targets.
+
+Rust rechecks retention, markers, cache identity, and active use at execution time. Active Rust tools or inaccessible process state (including protected same-user processes) block removal. Linux tsrust builds and pruning share a cache guard.
+
+All owner previews must succeed without truncated output before any execution. `--apply` prints the plan and asks for confirmation; noninteractive or JSON execution additionally requires `--yes`. Each apply invokes the owning tool again so its safety checks run at execution time. A failed command stops subsequent actions and returns a nonzero exit code; completed actions are not rolled back. Commands time out after 120 seconds for preview or 240 seconds for apply, with a five-second termination grace period. Review owning-tool state before retrying an interrupted operation.
+
+Cleanup runs as the project owner, without sudo, and refuses filesystem roots and symlink project paths. No plans or application state are persisted. This is a Linux CLI and uses `du`, `df`, `findmnt`, and GNU `timeout` from the host.
+
+## Library API
+
+`scanWorkspace(root, { maxDepth, maxEntries, timeoutMs, onProgress? })` returns findings, issues, issue counts, usage-priority paths, completion status, and the directory/symlink inspection count. `collectProjectToolCacheReport(context, roots?)` adds sizing. `collectDiskReport(context, roots?)` adds streaming workspace usage and host command diagnostics; `context.onProgress` receives live state updates. `measureDiskUsage(roots, { timeoutSeconds, trackedPaths?, priorityPaths?, onProgress? })` performs the standalone native usage pass. Priority paths only reorder descendants on the selected filesystem; they cannot expand scan scope. `estimateReclaimableSpace(findings)` returns the conservative candidate summary. The existing classification and byte-formatting exports remain available. `parseCliOptions(args)` and `createCleanupPlan(options)` expose validated CLI options and cleanup command plans; creating a plan does not execute cleanup.
+
 ## License and Legal Information
 
 This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsdisk',
-  version: '1.1.0',
+  version: '1.3.0',
   description: 'A disk usage diagnostic CLI for finding large files, caches, logs, and Docker storage.'
 }

package/ts/index.ts

@@ -1,8 +1,17 @@
 export { commitinfo } from './00_commitinfo_data.js';
 export {
   formatBytes,
+  collectDiskReport,
+  collectProjectToolCacheReport,
+  diagnosticCommandComplete,
   main,
   parseDuOutput,
   runCli,
 } from './tsdisk.cli.js';
 export * from './tsdisk.toolcaches.js';
+export * from './tsdisk.scan.js';
+export * from './tsdisk.cleanup.js';
+export * from './tsdisk.usage.js';
+export { DiskProgressReporter, estimateReclaimableSpace } from './tsdisk.progress.js';
+export type { IDiskProgress, IReclaimEstimate } from './tsdisk.progress.js';
+export type { IRuntimeContext, IDiagnosticSection } from './tsdisk.cli.js';

package/ts/tsdisk.cleanup.ts

@@ -0,0 +1,120 @@
+import * as plugins from './tsdisk.plugins.js';
+
+export type TCleanupCategory = 'rust' | 'docker' | 'pnpm';
+
+export interface ICleanupAction {
+  category: TCleanupCategory;
+  cwd: string;
+  command: string;
+  previewArgs?: string[];
+  applyArgs: string[];
+  scope: string;
+  blocked?: string;
+}
+
+export interface ICleanupPlan {
+  dryRun: boolean;
+  actions: ICleanupAction[];
+}
+
+export interface ICliOptions {
+  command: 'diagnose' | 'scan' | 'cleanup' | 'help' | 'version';
+  roots: string[];
+  categories: TCleanupCategory[];
+  json: boolean;
+  apply: boolean;
+  yes: boolean;
+  days: number;
+}
+
+export function parseCliOptions(args: string[]): ICliOptions {
+  const options: ICliOptions = { command: 'diagnose', roots: [], categories: ['rust', 'docker'], json: false, apply: false, yes: false, days: 14 };
+  let commandSeen = false;
+  let dryRun = false;
+  let cleanupOption = false;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') { options.command = 'help'; return options; }
+    if (arg === '--version' || arg === '-v') { options.command = 'version'; return options; }
+    if (arg === 'scan' || arg === 'cleanup') {
+      if (commandSeen) throw new Error('Specify one command: scan or cleanup.');
+      options.command = arg;
+      commandSeen = true;
+    } else if (arg === '--json') options.json = true;
+    else if (arg === '--apply') { options.apply = true; cleanupOption = true; }
+    else if (arg === '--yes' || arg === '-y') { options.yes = true; cleanupOption = true; }
+    else if (arg === '--dry-run' || arg === '-n') { dryRun = true; cleanupOption = true; }
+    else if (['--root', '--only', '--days'].some((flag) => arg === flag || arg.startsWith(`${flag}=`))) {
+      const separator = arg.indexOf('=');
+      const name = separator < 0 ? arg : arg.slice(0, separator);
+      const value = separator < 0 ? args[++index] : arg.slice(separator + 1);
+      if (!value || value.startsWith('--')) throw new Error(`Missing value for ${name}.`);
+      if (name === '--root') options.roots.push(plugins.path.resolve(value));
+      else if (name === '--only') {
+        cleanupOption = true;
+        const values = value.split(',');
+        if (values.some((category) => !['rust', 'docker', 'pnpm'].includes(category))) throw new Error('Cleanup categories: rust,docker,pnpm.');
+        options.categories = [...new Set(values)] as TCleanupCategory[];
+      } else {
+        cleanupOption = true;
+        options.days = Number(value);
+        if (!Number.isSafeInteger(options.days) || options.days < 1) throw new Error('--days must be a positive integer.');
+      }
+    } else throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (cleanupOption && options.command !== 'cleanup') throw new Error('Cleanup options require the cleanup command.');
+  if (dryRun && options.apply) throw new Error('--dry-run and --apply cannot be combined.');
+  if (options.yes && !options.apply) throw new Error('--yes requires --apply.');
+  if (options.command === 'diagnose' && (options.roots.length || options.json)) options.command = 'scan';
+  options.roots = [...new Set(options.roots)];
+  return options;
+}
+
+/** Build project-scoped owner commands. No discovered marker authorizes deletion. */
+export async function createCleanupPlan(options: ICliOptions): Promise<ICleanupPlan> {
+  if (options.command !== 'cleanup') throw new Error('Cleanup command required.');
+  if (!Number.isSafeInteger(options.days) || options.days < 1) throw new Error('Invalid retention period.');
+  if (!options.categories.length || options.categories.some((category) => !['rust', 'docker', 'pnpm'].includes(category))) throw new Error('Invalid cleanup category.');
+  const plan: ICleanupPlan = { dryRun: !options.apply, actions: [] };
+  for (const root of new Set(options.roots.length ? options.roots : [process.cwd()])) {
+    const cwd = plugins.path.resolve(root);
+    const stat = await plugins.fs.lstat(cwd);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || await plugins.fs.realpath(cwd) !== cwd || cwd === plugins.path.parse(cwd).root) {
+      throw new Error(`Cleanup requires a real project directory: ${cwd}`);
+    }
+    // Running project-installed tools as root would grant project code host-wide authority.
+    if (process.getuid?.() === 0) throw new Error('Run cleanup as the project owner, without sudo.');
+    if (process.getuid && stat.uid !== process.getuid()) throw new Error(`Cleanup root is not owned by the current user: ${cwd}`);
+    for (const category of new Set(options.categories)) {
+      if (category === 'pnpm') {
+        plan.actions.push({ category, cwd, command: 'pnpm', applyArgs: ['store', 'prune'], scope: 'Prune unreferenced packages from the pnpm store configured for this project. The store may be shared. pnpm provides no prune dry-run.' });
+        continue;
+      }
+      const binary = category === 'rust' ? 'tsrust' : 'tsdocker';
+      const command = plugins.path.join(cwd, 'node_modules', '.bin', binary);
+      const args = category === 'rust' ? ['prune', '--days', String(options.days)] : ['prune'];
+      const action: ICleanupAction = {
+        category, cwd, command, previewArgs: args, applyArgs: [...args, '--apply'],
+        scope: category === 'rust'
+          ? `Project's marked managed Rust targets; newest-file retention ${options.days} days, revalidated by tsrust.`
+          : 'Project registry caches and tsdocker-owned abandoned containers in the current Docker context; container scope may include other projects. tsdocker revalidates owner identity and active mounts.',
+      };
+      try {
+        await plugins.fs.access(command, plugins.constants.X_OK);
+        const packagePath = plugins.path.join(cwd, 'node_modules', '@git.zone', binary, 'package.json');
+        const manifest = JSON.parse(await plugins.fs.readFile(packagePath, 'utf8')) as { name?: string; version?: string };
+        if (manifest.name !== `@git.zone/${binary}`) throw new Error('Unexpected owning package.');
+        const version = /^(\d+)\.(\d+)\.(\d+)$/.exec(manifest.version ?? '')?.slice(1).map(Number);
+        const minimum = category === 'docker' ? [3, 6, 0] : [1, 13, 2];
+        const different = version?.findIndex((part, index) => part !== minimum[index]);
+        if (!version || (different !== undefined && different !== -1 && version[different] < minimum[different])) {
+          action.blocked = `@git.zone/${binary} ${minimum.join('.')} or later is required for the documented prune contract.`;
+        }
+      } catch {
+        action.blocked = `Install a current @git.zone/${binary} in this project before cleanup. No tool is downloaded automatically.`;
+      }
+      plan.actions.push(action);
+    }
+  }
+  return plan;
+}