waterplane 0.1.25 → 0.1.26

package/packages/host/dist/extensions/diskspace/host/candidates.d.mts

@@ -0,0 +1,180 @@
+import type { DiskKind, DiskProfile, DiskSide } from "../shared/wire.mjs";
+import { type Runner } from "./run.mjs";
+export interface Roots {
+    /** Which desktop this is (`index.mts` decides once). Absent = `mac`. */
+    profile?: DiskProfile;
+    /** wsl: the Windows user folder as a /mnt path (`/mnt/c/Users/me`); null when it could not be found. */
+    winHome?: string | null;
+    /** wsl: the distro's name (WSL_DISTRO_NAME), for the compact instruction. */
+    wslDistro?: string | null;
+    /** A sentence every scan repeats: why this desktop is listed more narrowly than its profile would be. */
+    profileNote?: string | null;
+    /** wsl: `powershell.exe` — the reader of Windows-side folder sizes and the fallback reader of the Windows drive's free space; null = none. */
+    psBin?: string | null;
+    /** wsl: the time bound on the one PowerShell call that sizes the Windows-side folders of a scan phase. */
+    psTimeoutMs?: number;
+    /** Tests: stands in for `run` when PowerShell is called (never a real powershell.exe in a test). */
+    psRun?: Runner;
+    /** Tests: a path's Windows form (default `winPathOf`: `/mnt/c/x` → `C:\x`). */
+    winPath?: (p: string) => string | null;
+    /** wsl: how long a %TEMP% entry must be untouched before it is offered (a week). */
+    winTempMinAgeMs: number;
+    home: string;
+    /** The code root (WATERPLANE_ROOT, else ~/dev). */
+    root: string;
+    /** `/private/tmp/claude-<uid>` on a Mac, `/tmp/claude-<uid>` on Linux. */
+    tmpRoot: string;
+    androidSdk: string;
+    duBin: string;
+    gitBin: string;
+    findBin: string;
+    /** null: no ollama on this desktop. */
+    ollamaBin: string | null;
+    duTimeoutMs: number;
+    concurrency: number;
+    walkDepth: number;
+    /** Folders the code-root walk may open before it stops (and says so). */
+    walkBudget: number;
+    tmpMinAgeMs: number;
+    largeLimitMs: number;
+    /** `find -size` argument. */
+    largeMinSize: string;
+    now: () => number;
+}
+export type Category = "cache" | "build" | "tmp" | "hf" | "ollama" | "wcache" | "wtemp" | "show" | "nm";
+export interface Candidate {
+    id: string;
+    category: Category;
+    kind: DiskKind;
+    group: string;
+    label: string;
+    /** Absent for ollama (deleted by name) and the aggregated scratchpad row. */
+    path?: string;
+    /** The aggregated scratchpad row: the folders it stands for. */
+    members?: string[];
+    ollamaName?: string;
+    ollamaId?: string;
+    /** ollama's own size text, kept for the row. */
+    sizeText?: string;
+    regen?: string;
+    mtime?: number | null;
+    note?: string;
+    /** wsl only: which disk it is on. */
+    side?: DiskSide;
+}
+export declare function idOf(category: Category, key: string): string;
+export declare function tilde(p: string, home: string): string;
+export declare const profileOf: (r: Roots) => DiskProfile;
+/** The Windows home, only on wsl. */
+export declare const winHomeOf: (r: Roots) => string | null;
+/** `/mnt/c/Users/me/x` as Windows writes it (`C:/Users/me/x`); any other path as it is. */
+export declare function driveForm(p: string): string;
+/** On wsl a group says which disk it is on; elsewhere there is one disk and it says nothing. */
+/** The disk a PATH is on under wsl: a path under /mnt/<letter>/ is that Windows drive, anything else is inside WSL. */
+export declare const sideOfPath: (p: string) => DiskSide;
+export declare function sided(r: Roots, group: string, side: DiskSide): {
+    group: string;
+    side?: DiskSide;
+};
+export interface FixedCache {
+    rel: string;
+    group: string;
+    regen: string;
+}
+/** The Mac's list (`profile: "mac"`). */
+export declare const FIXED_CACHES: readonly FixedCache[];
+/** Linux's list, and the Linux side of wsl (XDG cache folders under ~/.cache). */
+export declare const LINUX_CACHES: readonly FixedCache[];
+/** wsl's Windows side, relative to the Windows home. A `*` segment is one real folder per row. */
+export declare const WIN_CACHES: readonly FixedCache[];
+/** The home-side list for this desktop's profile. */
+export declare const cachesFor: (r: Roots) => readonly FixedCache[];
+/** Whether `rel` (already split, no empty/`.`/`..` segment) is `pattern`, a `*` matching any one segment. */
+export declare function relMatches(pattern: string, rel: readonly string[]): boolean;
+/** Every fixed cache that exists (a symlink too — `safeToRemove` is what refuses it, with words). */
+export declare function resolveCaches(r: Roots): Promise<Candidate[]>;
+/** wsl: every Windows-side fixed cache that exists; none without a Windows home. */
+export declare function resolveWinCaches(r: Roots): Promise<Candidate[]>;
+export declare const BUILD_NAMES: ReadonlySet<string>;
+export interface Walk {
+    build: string[];
+    nodeModules: string[];
+    stopped: boolean;
+    outsideGit: number;
+}
+/**
+ * Walk the code root: build output folders (not descended into) and node_modules folders (never
+ * descended into). Bounded by depth and by a folder budget, yielding as it goes — this runs in the
+ * process pumping every PTY. Symlinks are never followed.
+ */
+export declare function walkRoot(r: Roots): Promise<Walk>;
+/**
+ * ONE path checked the way `walkRoot` would have found it, without walking the code root — the
+ * fresh recompute a build-output delete runs (on a Windows-drive code root a walk takes many
+ * minutes). The path must be under the code root within the walk's depth, reached only through
+ * folders the walk descends into (no `node_modules`, `.git`, `.gradle`, `.Trash`, and no build
+ * output folder above it), named like build output, a real folder (not a link) next to a manifest,
+ * and ignored by git. Null candidate with the sentence why otherwise.
+ */
+export declare function recheckBuild(r: Roots, path: string): Promise<{
+    c: Candidate | null;
+    why?: string;
+}>;
+/** wsl: a path whose bytes are on the Windows drive — under a /mnt drive, or under the Windows home. */
+export declare function onWindowsDrive(r: Roots, p: string): boolean;
+/**
+ * The code-root walk runs only on a tap: on wsl with the code root on the Windows drive, where
+ * reading folders through WSL's drvfs is slow enough that one walk of a real code root took 29 min.
+ */
+export declare const codeOnTap: (r: Roots) => boolean;
+export declare const BUILD_REGEN = "The next build writes it again.";
+export declare function buildCandidates(r: Roots, w: Walk): Candidate[];
+export declare function nodeModulesEntries(r: Roots, w: Walk): Candidate[];
+/** The newest mtime anywhere under `dir`, or null when the folder has more than `budget` entries (then it is not "old"). */
+export declare function newestMtime(dir: string, budget?: number): Promise<number | null>;
+/** The session folders (`<tmpRoot>/<project>/<session>`) where nothing changed for `tmpMinAgeMs`. */
+export declare function oldScratchpads(r: Roots): Promise<string[]>;
+export declare const TMP_KEY = "claude-scratchpads";
+export declare function resolveTmp(r: Roots): Promise<Candidate[]>;
+export declare const winTempDir: (win: string) => string;
+/** How many %TEMP% entries one scan looks at; past it the row says so. */
+export declare const WIN_TEMP_MAX = 3000;
+export declare const WIN_TEMP_KEY = "windows-temp";
+/** Entries directly under %TEMP% (files and folders, never a symlink) where nothing changed for a week. */
+export declare function oldWinTemp(r: Roots): Promise<{
+    members: string[];
+    capped: boolean;
+}>;
+export declare function resolveWinTemp(r: Roots): Promise<Candidate[]>;
+export declare const hfHub: (r: Roots) => string;
+export declare function resolveHf(r: Roots): Promise<Candidate[]>;
+/** "18 GB" → KiB, ollama's decimal units; null when it does not parse. */
+export declare function ollamaSizeKb(text: string): number | null;
+export interface OllamaRow {
+    name: string;
+    id: string;
+    size: string;
+    modified: string;
+}
+/** `ollama list`'s table, columns split on runs of 2+ spaces. A row that does not have them is dropped. */
+export declare function parseOllamaList(out: string): OllamaRow[];
+/** An ollama tag safe to hand to `ollama rm` as one argv element. */
+export declare const OLLAMA_NAME_RE: RegExp;
+export declare function resolveOllama(r: Roots): Promise<{
+    list: Candidate[];
+    note: string | null;
+}>;
+/** wsl: the distros' virtual disks (`ext4.vhdx`), found in the two places WSL keeps them, bounded. */
+export declare function wslDisks(win: string): Promise<string[]>;
+/** The compact instruction for a WSL virtual disk, naming this distro when it is known. */
+export declare function compactHow(distro: string | null | undefined): string;
+export declare function showOnly(r: Roots): Promise<Candidate[]>;
+/** The folders the large-file find skips because a list above already covers them. */
+export declare function coveredPaths(r: Roots): string[];
+/**
+ * Null when `path` may be removed as a `c.category` candidate, else the sentence why not. The path
+ * must be absolute and lexically inside its anchor with the category's shape, must not be a symlink,
+ * and its REALPATH must be exactly the anchor's realpath joined with the same relative path — so a
+ * symlink anywhere between the anchor and the leaf (or a swapped-in one since the scan) refuses.
+ */
+export declare function safeToRemove(c: Candidate, r: Roots, path: string): Promise<string | null>;