A local-first multi-agent app development platform, built on PenguinHarness
/**
* `penguin storage` — the data root's storage ledger, and the reviewed cleanup that reads it.
*
* penguin storage [--top <n>] [--json] [--server <url>]
* penguin storage report [--top <n>] [--json] [--server <url>]
* penguin storage scan [--json] [--server <url>]
* penguin storage plan [<planId>] [--json] [--server <url>]
* penguin storage apply <planId> (--path <path> … | --all) [--json] [--server <url>]
* penguin storage trash [list] [--json] [--server <url>]
* penguin storage trash restore <id> [--json] [--server <url>]
* penguin storage trash purge [<id>] [--json] [--server <url>]
* penguin storage mode [on|off] [--json] [--server <url>]
*
* The bare command (an alias of `report`) reports what occupies `ADELIE_HOME`: one row per class (user data, temporary
* Workspaces, Session drafts, Traces, tool environments, trash, the database, everything else),
* the entries a person could clean up, the environments that look like the same toolchain
* installed twice, and anything the scan could not read.
*
* Everything else is the design's second step, and every one of those commands is a deliberate
* act: `scan` writes a bill and moves nothing; `plan` reads one back (or lists the recent ones);
* `apply` needs a plan id **and** the paths to move, which is why there is no `--yes` anywhere
* in this file; `trash` is where a move lands, and `purge` — the only deletion — is spelled out
* separately. The cleanup mode (`mode`) is off until somebody turns it on, and with it off the
* server refuses every write, so the bare report is all this command can do.
*
* The numbers come from the server (see routes/admin-storage.ts), not from walking the disk
* here: which Sessions still exist — and therefore which temporary Workspaces and draft
* directories are still referenced — is a database question, and only the server holds the
* database. A report computed locally against a stale lock file could name a live Session's
* Workspace as unreferenced, which is exactly the mistake the whole design is built to avoid;
* and by the same rule the CLI never moves a file, it submits an approval (the server is the
* single writer).
*
* Docs: /docs/cli § "penguin storage".
*/
import type { Command } from "commander";
import type {
StorageApplyResponse,
StorageCandidate,
StoragePlanResponse,
StoragePlanView,
StoragePlansResponse,
StoragePurgeResponse,
StorageReport,
StorageReportResponse,
StorageRestoreResponse,
StorageSettingsResponse,
StorageTrashResponse,
} from "@adelie/server/api";
import { humanizeBytes } from "../render.js";
import { resolveConnection, ServerClient } from "../client.js";
import { renderTable } from "../table.js";
import type { Messages } from "../i18n.js";
/** Candidates printed before the list is folded; `--top 0` prints every one. */
const DEFAULT_TOP = 20;
/** Free-space share below which the header carries a warning. Report-only: nothing acts on it. */
const LOW_FREE_RATIO = 0.15;
function lastModified(iso: string | null, t: Messages): string {
if (iso === null) return t.storage.unknownDate();
return iso.slice(0, 16).replace("T", " ");
}
/** The candidate rows, largest first as the server already ordered them. */
function candidateRows(report: StorageReport, top: number, t: Messages): string[][] {
const shown = top === 0 ? report.candidates : report.candidates.slice(0, top);
return shown.map((candidate: StorageCandidate) => [
t.storage.className(candidate.class),
humanizeBytes(candidate.bytes),
String(candidate.files),
lastModified(candidate.lastModifiedAt, t),
candidate.rules.map((rule) => t.storage.ruleLabel(rule)).join(", "),
candidate.path,
]);
}
/** A plan's entries as a table: what it is, how big, when it last changed, and why it is on it. */
function billRows(plan: StoragePlanView, t: Messages): string[][] {
return plan.entries.map((entry) => [
t.storage.className(entry.class),
humanizeBytes(entry.bytes),
String(entry.files),
lastModified(entry.lastModifiedAt, t),
entry.rules.map((rule) => t.storage.ruleLabel(rule)).join(", "),
entry.executable ? t.storage.moveMark() : t.storage.reportOnlyMark(),
entry.path,
]);
}
/** The plan state a listing shows: open, applied, or past its day. */
function planState(plan: StoragePlanView, t: Messages): string {
if (plan.appliedAt !== null) return t.storage.planStateApplied(lastModified(plan.appliedAt, t));
if (plan.expired) return t.storage.planStateExpired(lastModified(plan.expiresAt, t));
return t.storage.planStateOpen();
}
/** One bill, rendered the same way whether it was just written or read back. */
function renderPlan(plan: StoragePlanView, t: Messages): string {
const out: string[] = [];
out.push(
t.storage.billHeading(
plan.id,
plan.entries.length,
humanizeBytes(plan.totalBytes),
lastModified(plan.expiresAt, t),
),
);
if (plan.entries.length === 0) {
out.push(t.storage.billEmpty());
} else {
out.push(
renderTable(
[
t.storage.colClass(),
t.storage.colBytes(),
t.storage.colFiles(),
t.storage.colModified(),
t.storage.colRules(),
t.storage.colExecutable(),
t.storage.colPath(),
],
billRows(plan, t),
),
);
}
if (plan.excluded.length > 0) out.push(t.storage.billExcluded(plan.excluded.length));
out.push(t.storage.billReportOnly(plan.executableClasses.map((c) => t.storage.className(c))));
out.push(plan.usable ? t.storage.billNotice(plan.id) : t.storage.billSpent(plan.id));
return `${out.join("\n")}\n`;
}
/** Commander collector for a repeatable option; one value may also list several, comma-separated. */
function collect(value: string, previous: string[]): string[] {
return [
...previous,
...value
.split(",")
.map((part) => part.trim())
.filter((p) => p !== ""),
];
}
export function registerStorageCommand(program: Command, t: Messages): void {
const storage = program.command("storage").description(t.storage.desc);
// The bare command is the report, and it is a subcommand rather than the parent's own action
// for a reason that is easy to get wrong: a parent that declares `--json` AND a subcommand
// that declares it too makes commander hand the flag to the parent, so `storage scan --json`
// would silently print the human table. With nothing on the parent, every command's options
// are its own — `storage --json` and `storage scan --json` both mean what they say.
storage
.command("report", { isDefault: true })
.description(t.storage.desc)
.option("--top <n>", t.storage.top)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (opts) => {
let top = DEFAULT_TOP;
if (opts.top !== undefined) {
const n = Number(opts.top);
if (!Number.isInteger(n) || n < 0) {
process.stderr.write(`${t.error(t.storage.topInvalid(String(opts.top)))}\n`);
process.exitCode = 1;
return;
}
top = n;
}
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const response = await client.request<StorageReportResponse>("GET", "/api/admin/storage");
// The mode decides which sentence closes the report — "there is nothing else this command
// does" or "here is the next step" — and an older server without the route simply keeps
// the report-only wording.
const mode = await client
.request<StorageSettingsResponse>("GET", "/api/admin/storage/settings")
.then((res) => res.settings.enabled)
.catch(() => false);
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(response)}\n`);
return;
}
const { report } = response;
const out = process.stdout;
if (report.disk === null) {
out.write(`${t.storage.heading(report.root, humanizeBytes(report.totalBytes), null)}\n`);
} else {
const used = report.disk.totalBytes - report.disk.freeBytes;
const ratio =
report.disk.totalBytes === 0 ? 0 : report.disk.freeBytes / report.disk.totalBytes;
out.write(
`${t.storage.heading(report.root, humanizeBytes(report.totalBytes), {
free: humanizeBytes(report.disk.freeBytes),
total: humanizeBytes(report.disk.totalBytes),
usedPercent: String(
report.disk.totalBytes === 0 ? 0 : Math.round((used / report.disk.totalBytes) * 100),
),
})}\n`,
);
if (ratio < LOW_FREE_RATIO) {
out.write(`${t.storage.lowFree(humanizeBytes(report.disk.freeBytes))}\n`);
}
}
out.write(
renderTable(
[
t.storage.colClass(),
t.storage.colBytes(),
t.storage.colFiles(),
t.storage.colEntries(),
t.storage.colCandidates(),
],
report.classes
.filter((c) => c.entries > 0 || c.class === "protected")
.map((c) => [
t.storage.className(c.class),
humanizeBytes(c.bytes),
String(c.files),
String(c.entries),
c.candidateEntries === 0
? "-"
: t.storage.candidateCell(c.candidateEntries, humanizeBytes(c.candidateBytes)),
]),
),
);
out.write(`\n${t.storage.candidatesHeading()}\n`);
if (report.candidates.length === 0) {
out.write(`${t.storage.candidatesEmpty()}\n`);
} else {
out.write(
renderTable(
[
t.storage.colClass(),
t.storage.colBytes(),
t.storage.colFiles(),
t.storage.colModified(),
t.storage.colRules(),
t.storage.colPath(),
],
candidateRows(report, top, t),
),
);
if (top !== 0 && report.candidates.length > top) {
out.write(`${t.storage.moreCandidates(report.candidates.length - top)}\n`);
}
out.write(`${t.storage.candidateCosts()}\n`);
}
if (report.sharedEnvGroups.length > 0) {
out.write(`\n${t.storage.groupsHeading()}\n`);
for (const group of report.sharedEnvGroups) {
out.write(
`${t.storage.groupLine(
t.storage.groupKind(group.kind),
group.key,
group.members.length,
humanizeBytes(group.bytes),
)}\n`,
);
out.write(` ${group.members.join("\n ")}\n`);
}
}
if (report.unreadable.length > 0) {
out.write(`\n${t.storage.unreadableHeading()}\n`);
for (const path of report.unreadable) out.write(` ${path}\n`);
}
out.write(`\n${mode ? t.storage.modeOnNotice() : t.storage.modeOffNotice()}\n`);
});
storage
.command("scan")
.description(t.storage.scanDesc)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (opts) => {
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const response = await client.request<StoragePlanResponse>(
"POST",
"/api/admin/storage/plans",
);
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(response)}\n`);
return;
}
process.stdout.write(renderPlan(response.plan, t));
});
storage
.command("plan [planId]")
.description(t.storage.planDesc)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (planId: string | undefined, opts) => {
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
if (planId !== undefined) {
const response = await client.request<StoragePlanResponse>(
"GET",
`/api/admin/storage/plans/${encodeURIComponent(planId)}`,
);
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(response)}\n`);
return;
}
process.stdout.write(renderPlan(response.plan, t));
return;
}
const response = await client.request<StoragePlansResponse>(
"GET",
"/api/admin/storage/plans",
);
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(response)}\n`);
return;
}
if (response.plans.length === 0) {
process.stdout.write(`${t.storage.plansEmpty()}\n`);
return;
}
process.stdout.write(
renderTable(
[
t.storage.colPlanId(),
t.storage.colCreated(),
t.storage.colEntries(),
t.storage.colBytes(),
t.storage.colState(),
],
response.plans.map((plan) => [
plan.id,
lastModified(plan.createdAt, t),
String(plan.entries.length),
humanizeBytes(plan.totalBytes),
planState(plan, t),
]),
),
);
});
storage
.command("apply <planId>")
.description(t.storage.applyDesc)
.option("--path <path>", t.storage.applyPath, collect, [])
.option("--all", t.storage.applyAll)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (planId: string, opts) => {
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
// A run with nothing named never reaches the server: "clean whatever you find" is exactly
// the instruction this command does not accept.
if (opts.all !== true && opts.path.length === 0) {
process.stderr.write(`${t.error(t.storage.applyNoSelection())}\n`);
process.exitCode = 1;
return;
}
// The bill is read here rather than taken from an earlier print: the fingerprint that
// authorizes the run has to be the one the server is holding now.
const plan = (
await client.request<StoragePlanResponse>(
"GET",
`/api/admin/storage/plans/${encodeURIComponent(planId)}`,
)
).plan;
const paths: string[] =
opts.all === true
? plan.entries.filter((entry) => entry.executable).map((entry) => entry.path)
: opts.path;
if (paths.length === 0) {
process.stderr.write(`${t.error(t.storage.applyNoSelection())}\n`);
process.exitCode = 1;
return;
}
const result = await client.request<StorageApplyResponse>(
"POST",
"/api/admin/storage/apply",
{
planId,
fingerprint: plan.fingerprint,
paths,
},
);
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(result)}\n`);
return;
}
const out = process.stdout;
if (result.moved.length === 0) {
out.write(`${t.storage.applyNothing()}\n`);
} else {
out.write(
`${t.storage.applyMoved(
result.moved.length,
humanizeBytes(result.freedBytes),
result.trashId ?? "",
)}\n`,
);
}
for (const failure of result.failed) {
out.write(`${t.storage.applyFailedLine(failure.path, failure.reason)}\n`);
}
});
const trash = storage.command("trash").description(t.storage.trashDesc);
trash
.command("list", { isDefault: true })
.description(t.storage.trashListDesc)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (opts) => {
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const response = await client.request<StorageTrashResponse>(
"GET",
"/api/admin/storage/trash",
);
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(response)}\n`);
return;
}
if (response.entries.length === 0) {
process.stdout.write(`${t.storage.trashEmpty()}\n`);
return;
}
process.stdout.write(
renderTable(
[
t.storage.colTrashId(),
t.storage.colCreated(),
t.storage.colItems(),
t.storage.colBytes(),
t.storage.colExpired(),
],
response.entries.map((entry) => [
entry.id,
lastModified(entry.createdAt, t),
String(entry.items.length),
humanizeBytes(entry.bytes),
entry.expired ? t.storage.expired(t.storage.trashTtlDays(response.ttlDays)) : "",
]),
),
);
for (const entry of response.entries) {
for (const item of entry.items) {
process.stdout.write(` ${entry.id} ${t.storage.className(item.class)} ${item.path}\n`);
}
}
});
trash
.command("restore <id>")
.description(t.storage.trashRestoreDesc)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (id: string, opts) => {
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const result = await client.request<StorageRestoreResponse>(
"POST",
"/api/admin/storage/trash/restore",
{ id },
);
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(result)}\n`);
return;
}
process.stdout.write(
`${t.storage.trashRestored(result.id, result.restored.length, result.remaining)}\n`,
);
for (const skip of result.skipped) {
process.stdout.write(`${t.storage.trashSkippedLine(skip.path, skip.reason)}\n`);
}
});
trash
.command("purge [id]")
.description(t.storage.trashPurgeDesc)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (id: string | undefined, opts) => {
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const result = await client.request<StoragePurgeResponse>(
"POST",
"/api/admin/storage/trash/purge",
id === undefined ? {} : { id },
);
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(result)}\n`);
return;
}
if (result.purged.length === 0) {
process.stdout.write(`${t.storage.trashPurgeNothing()}\n`);
return;
}
for (const entry of result.purged) {
process.stdout.write(
`${t.storage.trashPurgedLine(entry.id, humanizeBytes(entry.bytes))}\n`,
);
}
});
storage
.command("mode [state]")
.description(t.storage.modeDesc)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (state: string | undefined, opts) => {
if (state !== undefined && state !== "on" && state !== "off") {
process.stderr.write(`${t.error(t.storage.modeUsage())}\n`);
process.exitCode = 1;
return;
}
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const response =
state === undefined
? await client.request<StorageSettingsResponse>("GET", "/api/admin/storage/settings")
: await client.request<StorageSettingsResponse>("PUT", "/api/admin/storage/settings", {
enabled: state === "on",
});
if (opts.json === true) {
process.stdout.write(`${JSON.stringify(response)}\n`);
return;
}
const free = response.settings.trashTtlDays;
process.stdout.write(
`${
state === undefined
? t.storage.modeIs(response.settings.enabled, free, response.settings.pins.length)
: t.storage.modeSet(response.settings.enabled, free, response.settings.pins.length)
}\n`,
);
});
}