Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

17.8 KB
Raw Blame
/**
 * `penguin storage`, driven through `cli()` in-process against the fake server's storage
 * report.
 *
 * The command's contract is small and entirely about what it *shows*, because it can cause
 * nothing else: the class table accounts for the ledger, the candidate list spells out why
 * each row is there, `--top` folds the tail instead of hiding it, and the output says in so
 * many words that nothing is removed without an approval. The last case pins that: after a
 * run, the only request the fake saw was the read-only GET — a command that could clean
 * something up would have to send something else.
 */
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { StoragePlanView, StorageReport } from "@adelie/server/api";
import { cli } from "../src/index.js";
import { FakeServer } from "./fake-server.js";

const GB = 1024 * 1024 * 1024;

let server: FakeServer;
let uninstall: () => void;
let stdout: string[];
let stderr: string[];
let scratch: string;
let outSpy: { mockRestore(): void };
let errSpy: { mockRestore(): void };

beforeEach(() => {
  server = new FakeServer();
  uninstall = server.install();
  scratch = fs.mkdtempSync(path.join(os.tmpdir(), "penguin-storage-cli-"));
  stdout = [];
  stderr = [];
  outSpy = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
    stdout.push(String(chunk));
    return true;
  });
  errSpy = vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
    stderr.push(String(chunk));
    return true;
  });
});
afterEach(() => {
  outSpy.mockRestore();
  errSpy.mockRestore();
  uninstall();
  fs.rmSync(scratch, { recursive: true, force: true });
});

const out = () => stdout.join("");
const err = () => stderr.join("");

/** A ledger with one row of every kind the command has a branch for. */
function report(over: Partial<StorageReport> = {}): StorageReport {
  return {
    root: "/home/user/.adelie/data",
    scannedAt: "2026-10-10T12:00:00.000Z",
    totalBytes: 6 * GB,
    classes: [
      {
        class: "protected",
        bytes: 20 * 1024 * 1024,
        files: 1269,
        entries: 43,
        candidateEntries: 0,
        candidateBytes: 0,
      },
      {
        class: "shared_env",
        bytes: 3 * GB,
        files: 101755,
        entries: 28,
        candidateEntries: 0,
        candidateBytes: 0,
      },
      {
        class: "session_drafts",
        bytes: 1.4 * GB,
        files: 56181,
        entries: 282,
        candidateEntries: 1,
        candidateBytes: 3_300_000,
      },
      {
        class: "tmp_workspaces",
        bytes: 564 * 1024 * 1024,
        files: 23731,
        entries: 83,
        candidateEntries: 26,
        candidateBytes: 146 * 1024 * 1024,
      },
      {
        class: "database",
        bytes: 23 * 1024 * 1024,
        files: 3,
        entries: 3,
        candidateEntries: 0,
        candidateBytes: 0,
      },
    ],
    candidates: [
      {
        path: "proj/agents/default_agent/workspaces/tmp-8e8a3ace",
        class: "tmp_workspaces",
        bytes: 138 * 1024 * 1024,
        files: 120,
        lastModifiedAt: "2026-09-01T04:05:06.000Z",
        referenced: false,
        rules: ["unreferenced"],
      },
      {
        path: "proj/agents/default_agent/scratchpad/session-2026-09-01-00-00-00-aaaaaaaa",
        class: "session_drafts",
        bytes: 3_300_000,
        files: 4,
        lastModifiedAt: null,
        referenced: false,
        rules: ["orphan"],
      },
      {
        path: "proj/agents/default_agent/workspaces/tmp-00000000",
        class: "tmp_workspaces",
        bytes: 0,
        files: 0,
        lastModifiedAt: "2026-10-09T00:00:00.000Z",
        referenced: false,
        rules: ["empty", "unreferenced"],
      },
    ],
    sharedEnvGroups: [
      {
        kind: "name",
        key: "csumail",
        members: [
          "proj/agents/default_agent/shared_env/csu-mail",
          "proj/agents/default_agent/shared_env/csumail",
        ],
        bytes: 88 * 1024 * 1024,
      },
    ],
    disk: { freeBytes: 8 * GB, totalBytes: 49 * GB },
    unreadable: [],
    ...over,
  };
}

describe("penguin storage", () => {
  it("prints the ledger: a header with the volume, one row per class, candidates with their rule", async () => {
    server.storage = report();
    expect(await cli(["storage"])).toBe(0);

    const text = out();
    expect(text).toContain("Data root /home/user/.adelie/data · ledger total 6GB");
    expect(text).toContain("8GB free of 49GB (84% used)");
    // Class rows, translated, with the candidate cell for the two classes that have one.
    expect(text).toMatch(/user data\s+20MB\s+1269\s+43\s+-/);
    expect(text).toMatch(/tool environments\s+3GB\s+101755\s+28\s+-/);
    expect(text).toMatch(/session drafts\s+1.4GB\s+56181\s+282\s+1 \(3.1MB\)/);
    expect(text).toMatch(/temp workspaces\s+564MB\s+23731\s+83\s+26 \(146MB\)/);
    // The candidate rows: path, size, why, and the cost sentence before anyone picks.
    expect(text).toContain("proj/agents/default_agent/workspaces/tmp-8e8a3ace");
    expect(text).toContain("2026-09-01 04:05");
    expect(text).toContain("unreferenced");
    expect(text).toContain("session gone");
    expect(text).toContain("empty, unreferenced");
    expect(text).toContain("unknown"); // a candidate with no readable mtime says so
    expect(text).toContain("What clearing each class costs");
    // Duplicated environments are reported, not proposed.
    expect(text).toContain("same name (csumail): 2 environments, 88MB together");
    expect(text).toContain("proj/agents/default_agent/shared_env/csu-mail");
    // And the one sentence that keeps this a report while the mode is off.
    expect(text).toContain("Read-only report: cleanup mode is off");
    expect(text).toContain("nothing runs on a timer");
  });

  it("warns about low free space without implying the command will act", async () => {
    server.storage = report({ disk: { freeBytes: 3 * GB, totalBytes: 49 * GB } });
    expect(await cli(["storage"])).toBe(0);
    expect(out()).toContain("Low on space: 3GB free.");
    expect(out()).toContain("none of them is removed until you approve a specific list");
  });

  it("folds the tail of the candidate list behind --top, and --top 0 prints every row", async () => {
    server.storage = report();
    expect(await cli(["storage", "--top", "2"])).toBe(0);
    expect(out()).toContain("… and 1 more (raise --top, or --top 0 for all).");
    expect(out()).not.toContain("tmp-00000000");

    stdout = [];
    expect(await cli(["storage", "--top", "0"])).toBe(0);
    expect(out()).toContain("tmp-00000000");
    expect(out()).not.toContain("raise --top");
  });

  it("refuses a bad --top before it reaches the server", async () => {
    server.storage = report();
    expect(await cli(["storage", "--top", "three"])).toBe(1);
    expect(err()).toContain('Invalid --top value "three"');
    expect(server.requests).toEqual([]);
  });

  it("prints the report verbatim under --json", async () => {
    server.storage = report();
    expect(await cli(["storage", "--json"])).toBe(0);
    expect(JSON.parse(out())).toEqual({ report: server.storage });
  });

  it("says nothing about which classes exist when the scan could not read part of the root", async () => {
    server.storage = report({
      unreadable: ["/home/user/.adelie/data/proj/agents/a/scratchpad/sealed"],
    });
    expect(await cli(["storage"])).toBe(0);
    expect(out()).toContain(
      "Could not be read (so the totals above are a floor, not a measurement):",
    );
    expect(out()).toContain("scratchpad/sealed");
  });

  it("reads the report and the mode, and writes nothing", async () => {
    server.storage = report();
    expect(await cli(["storage"])).toBe(0);
    // Two GETs, no POST, no PUT: the bare command reports, and the only thing it learns beyond
    // the ledger is whether cleanup mode is on, which decides its closing sentence.
    expect(server.requests.map((r) => `${r.method} ${r.path}`)).toEqual([
      "GET /api/admin/storage",
      "GET /api/admin/storage/settings",
    ]);
  });

  it("closes the report with the next step once the cleanup mode is on", async () => {
    server.storage = report();
    server.storageSettings = { enabled: true, trashTtlDays: 14, pins: [] };
    expect(await cli(["storage"])).toBe(0);
    expect(out()).toContain("Cleanup mode is on.");
    expect(out()).toContain("penguin storage apply <planId> --path <path>");
    expect(out()).not.toContain("cleanup mode is off");
  });

  it("reports a server that has no report to give", async () => {
    server.storage = null;
    expect(await cli(["storage"])).toBe(1);
    expect(err()).toContain("No fake storage report.");
  });
});

const TMP = "proj/agents/default_agent/workspaces/tmp-8e8a3ace";
const DRAFT = "proj/agents/default_agent/scratchpad/session-2026-09-01-00-00-00-aaaaaaaa";

/** A bill with one entry this version may move and one it only reports, like a real one. */
function planView(over: Partial<StoragePlanView> = {}): StoragePlanView {
  return {
    id: "2026-10-10-13-05-22-4f2a",
    root: "/home/user/.adelie/data",
    createdAt: "2026-10-10T13:05:22.000Z",
    expiresAt: "2026-10-11T13:05:22.000Z",
    fingerprint: "0123456789abcdef0123456789abcdef",
    totalBytes: 138 * 1024 * 1024,
    entries: [
      {
        path: TMP,
        class: "tmp_workspaces",
        bytes: 138 * 1024 * 1024,
        files: 120,
        lastModifiedAt: "2026-09-01T04:05:06.000Z",
        rules: ["unreferenced"],
        fingerprint: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        executable: true,
      },
      {
        path: DRAFT,
        class: "session_drafts",
        bytes: 3_300_000,
        files: 4,
        lastModifiedAt: null,
        rules: ["orphan"],
        fingerprint: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        executable: false,
      },
    ],
    excluded: [],
    executableClasses: ["tmp_workspaces"],
    appliedAt: null,
    appliedPaths: [],
    usable: true,
    expired: false,
    ...over,
  };
}

/**
 * The reviewed cleanup at the command line: scan, read a bill back, apply a selection, and
 * empty the trash. Every case here is about the instruction the CLI sends or refuses to send —
 * the fake server records the requests, and the assertions read them — because that is what a
 * CLI can get wrong about a destructive operation: naming the wrong paths, or sending none.
 */
describe("penguin storage — the reviewed cleanup", () => {
  it("scans a bill, marks what may be moved, and points at the approval command", async () => {
    server.storageScan = planView() as unknown as Record<string, unknown>;
    expect(await cli(["storage", "scan"])).toBe(0);

    const text = out();
    expect(text).toContain("Plan 2026-10-10-13-05-22-4f2a");
    expect(text).toContain("2 entries · 138MB");
    expect(text).toMatch(/temp workspaces\s+138MB\s+120\s+2026-09-01 04:05\s+unreferenced\s+✓/);
    expect(text).toMatch(/session drafts\s+3.1MB\s+4\s+unknown\s+session gone\s+—/);
    expect(text).toContain("only moves temp workspaces");
    expect(text).toContain("Nothing has moved. Approve the entries you select:");
    expect(server.requests.map((r) => `${r.method} ${r.path}`)).toEqual([
      "POST /api/admin/storage/plans",
    ]);
  });

  it("prints the bill verbatim under --json", async () => {
    server.storageScan = planView() as unknown as Record<string, unknown>;
    expect(await cli(["storage", "scan", "--json"])).toBe(0);
    expect(JSON.parse(out())).toEqual({ plan: planView() });
  });

  it("lists the plans and reads one back by id", async () => {
    server.storageScan = planView() as unknown as Record<string, unknown>;
    await cli(["storage", "scan"]);

    stdout = [];
    expect(await cli(["storage", "plan"])).toBe(0);
    expect(out()).toContain("2026-10-10-13-05-22-4f2a");
    expect(out()).toContain("open");

    stdout = [];
    expect(await cli(["storage", "plan", "2026-10-10-13-05-22-4f2a"])).toBe(0);
    expect(out()).toContain("Nothing has moved.");
    expect(out()).toContain("valid until 2026-10-11 13:05");
  });

  it("says so when no plan has ever been written, and when an id is not a plan", async () => {
    expect(await cli(["storage", "plan"])).toBe(0);
    expect(out()).toContain("No plan has been written yet");

    stdout = [];
    expect(await cli(["storage", "plan", "2026-01-01-00-00-00-ffffff"])).toBe(1);
    expect(err()).toContain("No plan 2026-01-01-00-00-00-ffffff.");
  });

  it("applies the entries it is given, quoting the plan's own fingerprint", async () => {
    server.storageScan = planView() as unknown as Record<string, unknown>;
    server.storageApply = {
      planId: "",
      trashId: "20261010-130522",
      moved: [{ path: TMP, bytes: 138 * 1024 * 1024, files: 120 }],
      failed: [],
      freedBytes: 138 * 1024 * 1024,
    };
    expect(await cli(["storage", "apply", "2026-10-10-13-05-22-4f2a", "--path", TMP])).toBe(0);

    expect(out()).toContain("Moved 1 entry (138MB) into the trash as 20261010-130522.");
    const apply = server.requests.find((r) => r.path === "/api/admin/storage/apply");
    expect(apply?.body).toEqual({
      planId: "2026-10-10-13-05-22-4f2a",
      fingerprint: "0123456789abcdef0123456789abcdef",
      paths: [TMP],
    });
  });

  it("sends only the moveable entries under --all, and reports what could not move", async () => {
    server.storageScan = planView() as unknown as Record<string, unknown>;
    server.storageApply = {
      planId: "",
      trashId: "20261010-130522",
      moved: [],
      failed: [{ path: TMP, reason: "changed since the scan" }],
      freedBytes: 0,
    };
    expect(await cli(["storage", "apply", "2026-10-10-13-05-22-4f2a", "--all"])).toBe(0);
    const apply = server.requests.find((r) => r.path === "/api/admin/storage/apply");
    // The draft directory is on the bill but not in the selection: report-only means the CLI
    // does not offer it to the server at all.
    expect((apply?.body as { paths?: string[] })?.paths).toEqual([TMP]);
    expect(out()).toContain("Nothing was moved (see the failures above).");
    expect(out()).toContain(`not moved: ${TMP} — changed since the scan`);
  });

  it("refuses to apply without naming an entry", async () => {
    server.storageScan = planView() as unknown as Record<string, unknown>;
    expect(await cli(["storage", "apply", "2026-10-10-13-05-22-4f2a"])).toBe(1);
    expect(err()).toContain("Nothing selected");
    // Nothing was asked of the server at all: no plan was read, no approval was sent.
    expect(server.requests).toEqual([]);
  });

  it("lists the trash with what each entry holds, and says when it is empty", async () => {
    server.storageTrash = {
      entries: [
        {
          id: "20261010-130522",
          createdAt: "2026-10-10T13:05:22.000Z",
          planId: "2026-10-10-13-05-22-4f2a",
          bytes: 138 * 1024 * 1024,
          files: 120,
          items: [{ path: TMP, class: "tmp_workspaces", bytes: 138 * 1024 * 1024, files: 120 }],
          expired: true,
        },
      ],
      ttlDays: 14,
    };
    expect(await cli(["storage", "trash"])).toBe(0);
    const text = out();
    expect(text).toContain("20261010-130522");
    expect(text).toContain("past the retention (14d)");
    expect(text).toContain(`20261010-130522  temp workspaces  ${TMP}`);

    stdout = [];
    server.storageTrash = { entries: [], ttlDays: 14 };
    expect(await cli(["storage", "trash"])).toBe(0);
    expect(out()).toContain("The trash is empty.");
  });

  it("restores an entry, and names what it could not put back", async () => {
    server.storageRestore = {
      id: "",
      restored: [TMP],
      skipped: [{ path: DRAFT, reason: "target_exists" }],
      remaining: true,
    };
    expect(await cli(["storage", "trash", "restore", "20261010-130522"])).toBe(0);
    const text = out();
    expect(text).toContain("Restored 1 entry from 20261010-130522.");
    expect(text).toContain("The entry still holds what could not be put back.");
    expect(text).toContain(`not restored: ${DRAFT} — target_exists`);
    const request = server.requests.find((r) => r.path === "/api/admin/storage/trash/restore");
    expect(request?.body).toEqual({ id: "20261010-130522" });
  });

  it("purges the named entry, and says when the retention has nothing to give", async () => {
    server.storagePurge = {
      purged: [{ id: "20261010-130522", bytes: 138 * 1024 * 1024, files: 120 }],
    };
    expect(await cli(["storage", "trash", "purge", "20261010-130522"])).toBe(0);
    expect(out()).toContain("Purged 20261010-130522 (138MB).");
    expect(server.requests.find((r) => r.path === "/api/admin/storage/trash/purge")?.body).toEqual({
      id: "20261010-130522",
    });

    stdout = [];
    server.storagePurge = { purged: [] };
    expect(await cli(["storage", "trash", "purge"])).toBe(0);
    expect(out()).toContain("Nothing to purge");
    // Without an id the body is empty: the server then removes only what is past the retention.
    expect(server.requests.filter((r) => r.path.endsWith("/trash/purge")).at(-1)?.body).toEqual({});
  });

  it("shows the cleanup mode and turns it on and off", async () => {
    expect(await cli(["storage", "mode"])).toBe(0);
    expect(out()).toContain("Cleanup mode is off. Trash retention 14 days, 0 pinned path(s).");

    stdout = [];
    expect(await cli(["storage", "mode", "on"])).toBe(0);
    expect(out()).toContain("Cleanup mode is now on.");
    expect(server.requests.find((r) => r.method === "PUT")?.body).toEqual({ enabled: true });

    stdout = [];
    expect(await cli(["storage", "mode", "off"])).toBe(0);
    expect(out()).toContain("Cleanup mode is now off.");
    expect(server.storageSettings.enabled).toBe(false);
  });

  it("refuses a mode it does not know, without asking the server", async () => {
    expect(await cli(["storage", "mode", "maybe"])).toBe(1);
    expect(err()).toContain("usage: penguin storage mode [on|off]");
    expect(server.requests).toEqual([]);
  });
});