@bli-cockpit/cli 0.2.94 → 0.2.95

package/dist/disk-usage.js

@@ -9,7 +9,7 @@
  * The collector staged raw evidence, uploaded it, committed it, and then kept
  * the local copy forever.
  *
- * Nothing here deletes anything. This module answers ONE question per file —
+ * Nothing here deletes anything. This family answers ONE question per file —
  * "does a ledger on this machine say these bytes are durable remotely?" — and
  * the answer has three values, not two, because the honest third one is what
  * the same probe turned up:
@@ -45,401 +45,38 @@
  *
  * Metadata only: pack ids, pack-relative paths, byte counts, hashes, reason
  * labels. Never a person's absolute path and never a byte of content.
- */
-import crypto from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { readRawEvidenceCursor } from "./cursors/raw-evidence-cursor.js";
-import { readReconcileCursor, } from "./cursors/raw-evidence-reconcile-cursor.js";
-import { describeError } from "./health-detail.js";
-import { rotatedLogFootprint } from "./log-rotation.js";
-import { readRawEvidenceStagingState } from "./raw-evidence-staging.js";
-/** Bytes this inventory may spend hashing files no manifest names. */
-export const UNNAMED_FILE_HASH_BUDGET_BYTES = 256 * 1024 * 1024;
-/** Directory name of the staged raw-evidence tree under the state directory. */
-export const RAW_EVIDENCE_DIR = "raw-evidence";
-/** One-off evidence vaults a person made by hand; named, never auto-deleted. */
-export const MANUAL_VAULT_PREFIX = "manual-study-evidence-vault-";
-/**
- * Everything on this machine Cockpit put there, in one read. Used by the sync
- * tick's prune, by `cockpit clean` and by `cockpit doctor`'s disk row, so all
- * three quote the same numbers rather than three near-misses.
- */
-export async function readDiskFootprint(paths, now = new Date()) {
-    return {
-        staging: await readStagingInventory(paths, now),
-        logs: await rotatedLogFootprint(paths),
-        spool_bytes: await directoryBytes(paths.spool_dir),
-        vaults: await readManualVaults(paths),
-    };
-}
-export async function readStagingInventory(paths, now = new Date()) {
-    const root = path.join(paths.state_dir, RAW_EVIDENCE_DIR);
-    const ledger = await readCommitLedger(paths);
-    const reconciled = await readReconcileLedger(paths);
-    const stagedAt = await readStagedAtIndex(paths);
-    const entries = await fs
-        .readdir(root, { withFileTypes: true })
-        .catch(() => []);
-    const inventory = emptyStagingInventory();
-    const budget = { remaining: UNNAMED_FILE_HASH_BUDGET_BYTES };
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const dir = path.join(root, entry.name);
-        if (entry.name.startsWith(".staging-")) {
-            inventory.orphan_staging_dirs += 1;
-            inventory.orphan_staging_bytes += await directoryBytes(dir);
-            continue;
-        }
-        if (!entry.name.startsWith("work-"))
-            continue;
-        const pack = await readPack(dir, entry.name, {
-            ledger,
-            reconciled,
-            stagedAt,
-            now,
-            budget,
-        });
-        inventory.packs.push(pack);
-        accumulatePack(inventory, pack);
-    }
-    rankUncommittedReasons(inventory);
-    return inventory;
-}
-/**
- * The commit record, read from the one place that writes it: the raw-evidence
- * cursor's `objects` map (`upload.ts` → `markObjectCommitted`, only ever for an
- * outcome that was not `upload_failed`).
- */
-async function readCommitLedger(paths) {
-    const cursor = await readRawEvidenceCursor(paths);
-    const committed = new Map();
-    let oldest = null;
-    for (const [hash, entry] of Object.entries(cursor.objects)) {
-        committed.set(hash, entry.committed_at);
-        if (!oldest || entry.committed_at.localeCompare(oldest) < 0) {
-            oldest = entry.committed_at;
-        }
-    }
-    return { committed, reachesBackTo: oldest };
-}
-/** `pack_id/relative_path` → when this machine staged those bytes. */
-async function readStagedAtIndex(paths) {
-    const staging = await readRawEvidenceStagingState(paths.state_dir);
-    const index = new Map();
-    for (const entry of Object.values(staging.staged)) {
-        index.set(`${entry.pack_id}/${entry.relative_path}`, entry.staged_at);
-    }
-    return index;
-}
-/**
- * The reconcile cursor as a lookup map. Read alongside the commit ledger so an
- * object the server confirmed committed classifies exactly like one this
- * machine's own ledger still remembers.
- */
-async function readReconcileLedger(paths) {
-    const cursor = await readReconcileCursor(paths);
-    return new Map(Object.entries(cursor.results));
-}
-async function readPack(dir, packId, options) {
-    const manifest = await readManifestIndex(dir);
-    const pack = {
-        pack_id: packId,
-        objects: [],
-        manifest_bytes: 0,
-        manifest_present: manifest !== null,
-    };
-    for (const relative of await listPackFiles(dir)) {
-        // One stat, two facts: how big the staged copy is and WHEN it was written.
-        // The mtime is the only unfalsifiable record of how long undelivered
-        // evidence has been sitting here (BLI-3797) — every other timestamp on the
-        // machine records when something last had an opinion about it.
-        const info = await fs.stat(path.join(dir, relative)).catch(() => null);
-        const size = info?.isFile() ? info.size : 0;
-        if (relative === "manifest.json") {
-            pack.manifest_bytes += size;
-            continue;
-        }
-        const stagedOnDiskAt = info && Number.isFinite(info.mtimeMs)
-            ? new Date(info.mtimeMs).toISOString()
-            : null;
-        pack.objects.push(await classifyObject(dir, packId, relative, size, manifest, {
-            ...options,
-            stagedOnDiskAt,
-        }));
-    }
-    return pack;
-}
-async function classifyObject(dir, packId, relative, size, manifest, options) {
-    const hash = manifest?.get(relative) ??
-        (await hashUnnamedFile(path.join(dir, relative), size, options.budget));
-    const stagedAt = options.stagedAt.get(`${packId}/${relative}`) ?? null;
-    const committedAt = hash ? options.ledger.committed.get(hash) : undefined;
-    const base = {
-        pack_id: packId,
-        relative_path: relative,
-        byte_size: size,
-        staged_on_disk_at: options.stagedOnDiskAt,
-        disk_age_ms: ageMs(options.stagedOnDiskAt, options.now),
-    };
-    if (committedAt) {
-        return {
-            ...base,
-            content_hash: hash ?? null,
-            state: "committed",
-            reason: "committed_in_ledger",
-            decided_at: committedAt,
-            age_ms: ageMs(committedAt, options.now),
-        };
-    }
-    if (hash) {
-        const reconciled = options.reconciled.get(hash);
-        if (reconciled) {
-            return classifyFromReconcileAnswer(base, hash, reconciled, options.now);
-        }
-    }
-    const unknownReason = unknownStateReason(hash, manifest, stagedAt, options);
-    return {
-        ...base,
-        content_hash: hash ?? null,
-        state: unknownReason ? "unknown" : "uncommitted",
-        reason: unknownReason ?? "absent_from_ledger",
-        decided_at: stagedAt,
-        age_ms: ageMs(stagedAt, options.now),
-    };
-}
-/**
- * The server's own answer for this hash, already on disk from an earlier
- * `cockpit clean --reconcile` run. This takes priority over
- * `unknownStateReason`'s guesswork about the LOCAL ledger's memory, because
- * the server was actually asked and actually answered.
- */
-function classifyFromReconcileAnswer(base, hash, reconciled, now) {
-    if (reconciled.verdict === "committed") {
-        const decidedAt = reconciled.server_committed_at ?? reconciled.checked_at;
-        return {
-            ...base,
-            content_hash: hash,
-            state: "committed",
-            reason: "reconciled_committed",
-            decided_at: decidedAt,
-            age_ms: ageMs(decidedAt, now),
-        };
-    }
-    return {
-        ...base,
-        content_hash: hash,
-        state: "uncommitted",
-        reason: reconciled.verdict === "not_committed"
-            ? "reconciled_not_committed"
-            : "reconciled_unknown_to_server",
-        decided_at: reconciled.checked_at,
-        age_ms: ageMs(reconciled.checked_at, now),
-    };
-}
-/**
- * Why the ledger's silence about this object is NOT the same as a "no".
  *
- * The `objects` map is capped at 5,000 rows and drops the oldest, so anything
- * staged before the oldest row it still holds is outside its memory. Saying
- * "uncommitted" there would be a claim the ledger never made.
- */
-function unknownStateReason(hash, manifest, stagedAt, options) {
-    if (!manifest)
-        return "manifest_unreadable";
-    if (!hash)
-        return "no_manifest_row";
-    const reachesBackTo = options.ledger.reachesBackTo;
-    if (!reachesBackTo)
-        return "ledger_empty";
-    if (stagedAt && stagedAt.localeCompare(reachesBackTo) < 0) {
-        return "ledger_evicted";
-    }
-    if (!stagedAt)
-        return "ledger_evicted";
-    return null;
-}
-/**
- * A file its own manifest does not name gets hashed — but only while the run's
- * byte budget lasts. Past it the object stays `unknown` and says which budget
- * ran out, because reading 20 GB to answer a housekeeping question is how the
- * old GC earned its once-a-day throttle.
- */
-async function hashUnnamedFile(file, size, budget) {
-    if (size > budget.remaining)
-        return null;
-    const bytes = await fs.readFile(file).catch(() => null);
-    if (!bytes)
-        return null;
-    budget.remaining -= bytes.byteLength;
-    return crypto.createHash("sha256").update(bytes).digest("hex");
-}
-async function readManifestIndex(dir) {
-    const raw = await fs
-        .readFile(path.join(dir, "manifest.json"), "utf8")
-        .catch(() => null);
-    if (!raw)
-        return null;
-    try {
-        const parsed = JSON.parse(raw);
-        const index = new Map();
-        for (const file of parsed.files ?? []) {
-            if (typeof file.relative_path === "string" &&
-                typeof file.content_hash_sha256 === "string" &&
-                file.content_hash_sha256.length === 64) {
-                index.set(file.relative_path, file.content_hash_sha256);
-            }
-        }
-        return index;
-    }
-    catch (error) {
-        // Named, not swallowed: an unreadable manifest turns every file in the
-        // pack into `unknown`, which is the difference between a pack that gets
-        // pruned and one that is kept forever (BLI-3238's rule, BLI-3619's cost).
-        console.error("[collector disk] pack manifest unreadable, its files cannot be classified", JSON.stringify({
-            reason: "manifest_unreadable",
-            pack_id: path.basename(dir),
-            ...describeError(error),
-        }));
-        return null;
-    }
-}
-async function listPackFiles(dir) {
-    const files = [];
-    const stack = [{ dir, prefix: "" }];
-    while (stack.length > 0) {
-        const current = stack.pop();
-        if (!current)
-            continue;
-        const entries = await fs
-            .readdir(current.dir, { withFileTypes: true })
-            .catch(() => []);
-        for (const entry of entries) {
-            const relative = current.prefix
-                ? `${current.prefix}/${entry.name}`
-                : entry.name;
-            if (entry.isDirectory()) {
-                stack.push({ dir: path.join(current.dir, entry.name), prefix: relative });
-            }
-            else if (entry.isFile()) {
-                files.push(relative);
-            }
-        }
-    }
-    return files;
-}
-async function readManualVaults(paths) {
-    const entries = await fs
-        .readdir(paths.state_dir, { withFileTypes: true })
-        .catch(() => []);
-    const vaults = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory() || !entry.name.startsWith(MANUAL_VAULT_PREFIX)) {
-            continue;
-        }
-        const dir = path.join(paths.state_dir, entry.name);
-        vaults.push({
-            name: entry.name,
-            byte_size: await directoryBytes(dir),
-            file_count: (await listPackFiles(dir)).length,
-        });
-    }
-    return vaults;
-}
-export async function directoryBytes(dir) {
-    let total = 0;
-    for (const relative of await listPackFiles(dir)) {
-        const info = await fs.stat(path.join(dir, relative)).catch(() => null);
-        total += info?.isFile() ? info.size : 0;
-    }
-    return total;
-}
-function accumulatePack(inventory, pack) {
-    inventory.pack_count += 1;
-    inventory.manifest_bytes += pack.manifest_bytes;
-    inventory.total_bytes += pack.manifest_bytes;
-    for (const object of pack.objects) {
-        inventory.object_count += 1;
-        inventory.total_bytes += object.byte_size;
-        if (object.state === "committed") {
-            inventory.committed_count += 1;
-            inventory.committed_bytes += object.byte_size;
-            continue;
-        }
-        if (object.state === "unknown") {
-            inventory.unknown_count += 1;
-            inventory.unknown_bytes += object.byte_size;
-            continue;
-        }
-        inventory.uncommitted_count += 1;
-        inventory.uncommitted_bytes += object.byte_size;
-        tallyUncommittedReason(inventory, object);
-        // The age of the BYTES, not of the answer about them (BLI-3797). Falls back
-        // to `decided_at` only when the file has no readable mtime, which is the
-        // one case where the disk itself cannot say.
-        const stagedAt = object.staged_on_disk_at ?? object.decided_at;
-        if (stagedAt &&
-            (!inventory.oldest_uncommitted_at ||
-                stagedAt.localeCompare(inventory.oldest_uncommitted_at) < 0)) {
-            inventory.oldest_uncommitted_at = stagedAt;
-        }
-    }
-}
-/**
- * One more object against its reason label. Kept as a mutable array rather than
- * a Map so the inventory stays a plain serializable value — it rides `--json`
- * output and a receipt, and a Map would silently become `{}` in both.
- */
-function tallyUncommittedReason(inventory, object) {
-    const existing = inventory.uncommitted_reasons.find((tally) => tally.reason === object.reason);
-    const tally = existing ?? {
-        reason: object.reason,
-        count: 0,
-        bytes: 0,
-        oldest_disk_age_ms: 0,
-    };
-    tally.count += 1;
-    tally.bytes += object.byte_size;
-    tally.oldest_disk_age_ms = Math.max(tally.oldest_disk_age_ms, object.disk_age_ms || object.age_ms);
-    if (!existing)
-        inventory.uncommitted_reasons.push(tally);
-}
-/**
- * Rank the reasons by BYTES, then name the biggest one.
+ * This file is the table of contents and holds no logic (BLI-3979). Each
+ * responsibility lives in a named sibling, and every public name below is
+ * still importable from `./disk-usage.js`, which is what the prune, the
+ * retention plan, `cockpit clean`, `cockpit status`, `cockpit doctor`, the
+ * heartbeat and the redelivery plan all depend on:
+ *
+ * - `disk-usage-facts.ts` — the shapes: one staged object and its reason
+ *   label, one pack, the inventory, a manual vault, the whole footprint, plus
+ *   the two directory names that decide which folders are looked at.
+ * - `disk-usage-ledger.ts` — the three records an object is classified
+ *   against, read once per run: the commit ledger and how far back its capped
+ *   memory reaches, the recorded server answers, and when each object was
+ *   staged.
+ * - `disk-usage-classify.ts` — the three-state question per file, in the order
+ *   that makes it safe: this machine's ledger, then a server answer, then the
+ *   named reason its silence has.
+ * - `disk-usage-files.ts` — the only code here that touches a file for its own
+ *   sake: the pack walk, directory bytes, the manifest index, and the budgeted
+ *   hash of a file no manifest names.
+ * - `disk-usage-totals.ts` — classified objects into the numbers a person
+ *   reads: per-state totals, the reason ranking by BYTES, and the oldest
+ *   undelivered bytes' own age.
+ * - `disk-usage-scan.ts` — the staging walk itself: `readStagingInventory`,
+ *   one pack at a time.
+ * - `disk-usage-footprint.ts` — the whole-machine read: staging plus rotated
+ *   logs, the spool and the hand-made vaults.
  *
- * Bytes, not object count, because the question the ranking answers is "what is
- * holding this laptop over its cap" — 234 objects at 1,836 MB and 17 at 81 MB
- * are not the same finding, and counting rows would have called them close.
+ * A new sibling here must also join `scripts/build-public-cli.mjs`
+ * `runtimeFiles`, or the repo tests stay green while the packed CLI breaks.
  */
-function rankUncommittedReasons(inventory) {
-    inventory.uncommitted_reasons.sort((left, right) => right.bytes - left.bytes || right.count - left.count);
-    inventory.dominant_uncommitted_reason =
-        inventory.uncommitted_reasons[0] ?? null;
-}
-function emptyStagingInventory() {
-    return {
-        pack_count: 0,
-        object_count: 0,
-        total_bytes: 0,
-        committed_count: 0,
-        committed_bytes: 0,
-        uncommitted_count: 0,
-        uncommitted_bytes: 0,
-        oldest_uncommitted_at: null,
-        uncommitted_reasons: [],
-        dominant_uncommitted_reason: null,
-        unknown_count: 0,
-        unknown_bytes: 0,
-        manifest_bytes: 0,
-        orphan_staging_dirs: 0,
-        orphan_staging_bytes: 0,
-        packs: [],
-    };
-}
-function ageMs(at, now) {
-    if (!at)
-        return 0;
-    const parsed = Date.parse(at);
-    return Number.isFinite(parsed) ? Math.max(0, now.getTime() - parsed) : 0;
-}
+export { MANUAL_VAULT_PREFIX, RAW_EVIDENCE_DIR } from "./disk-usage-facts.js";
+export { directoryBytes, UNNAMED_FILE_HASH_BUDGET_BYTES, } from "./disk-usage-files.js";
+export { readStagingInventory } from "./disk-usage-scan.js";
+export { readDiskFootprint } from "./disk-usage-footprint.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.94",
+  "version": "0.2.95",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.24",
-    "@bli-cockpit/mcp": "0.1.27",
-    "@bli-cockpit/telemetry-core": "0.1.41"
+    "@bli-cockpit/memory-mcp": "0.1.25",
+    "@bli-cockpit/mcp": "0.1.28",
+    "@bli-cockpit/telemetry-core": "0.1.42"
   }
 }