Public: anyone can read this; the crew can change it.

/forges says when each hosted forge was last kept, and a forge never kept is named #13997

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13833-forges-says-when-each-hosted-forge-was-l → main 3 commits fork

  • Merged. scout/13833-forges-says-when-each-hosted-forge-was-l was merged into main as 3fed3a9.

Review

Sign in to review this change.
9 files changed +137 −21
docs/features/hosted-backup.md +3 −2
@@ -16,8 +16,9 @@ Chunks are shared with the rest of the snapshot, so a forge unchanged since last
1616 ## Where it shows
1717
1818 - Backups page: how many forges the newest backup kept, and how many were left out.
19 - Resilience screen (terminal): the same line, then one line per forge: backed up H h ago, or left out and why.
20 - `/forges`: each row, "backed up H h ago".
19 - Resilience screen (terminal): the same line, then one line per forge: kept H h ago, or left out and why.
20 - `/forges`: each row, "kept <age> ago" (under an hour, hours, then days) or "never kept" when no backup holds it, or why the newest left it out.
21 - `forges` MCP tool and `GET /api/v1/forges`: the same words as `kept` on each made forge.
2122
2223 ## Restore one forge
2324
src/http/api/forges.ts +5 −4
@@ -11,7 +11,7 @@ import { listChildren } from "../../actions/spawn.ts";
1111 import { usdWords } from "../../spawn/credit.ts";
1212 import { fundingOf, fundingWords, refreshFunding } from "../../spawn/funding.ts";
1313 import { notePhase, takeSessionTime, timePhase, timePhaseAsync } from "../../core/route_timing.ts";
14 import { clientRows, listed } from "../../spawn/clients.ts";
14 import { clientRows, listedKept } from "../../spawn/clients.ts";
1515 import { previewDoor, reissueDoor, spawnDoor } from "../../spawn/door.ts";
1616 import { checkMove } from "../../spawn/move_check.ts";
1717 import { moveToCell } from "../../spawn/move_cell.ts";
@@ -77,11 +77,12 @@ export function forgeRoutes(router: Router<Handler>): void {
7777 // where it is placed.
7878 const [rows, children] = await Promise.all([clientRows(ctx.app), listChildren(ctx.app)]);
7979 const kept = new Map(children.map((c) => [c.name, c]));
80 return rows.map((row) => {
80 const all = listedKept(ctx.app, rows);
81 return rows.map((row, i) => {
8182 const c = kept.get(row.name);
8283 return c === undefined
83 ? listed(row)
84 : { ...listed(row), bodyId: c.bodyId, done: c.done, createdAt: c.createdAt, placement: c.placement, placementNote: c.placementNote, ...(c.template === undefined ? {} : { template: c.template }) };
84 ? all[i]!
85 : { ...all[i]!, bodyId: c.bodyId, done: c.done, createdAt: c.createdAt, placement: c.placement, placementNote: c.placementNote, ...(c.template === undefined ? {} : { template: c.template }) };
8586 });
8687 });
8788 return timePhase(ctx.request, "render", () => json({ items, next_cursor: null }));
src/http/mcp/tools/forges.ts +3 −3
@@ -4,7 +4,7 @@ import { REFUSED_SHOWN, listRefusals, mayReadRefusals } from "../../../core/firs
44 import { publicOrigin } from "../../../core/public_origin.ts";
55 import { scopeAllows } from "../../../core/tokens.ts";
66 import { clientLines } from "../../../spawn/client_words.ts";
7 import { clientRows, listed } from "../../../spawn/clients.ts";
7 import { clientRows, listedKept } from "../../../spawn/clients.ts";
88 import { archiveForge, archivedForges, restoreForge } from "../../../spawn/archive.ts";
99 import { CHILD_NAME } from "../../../spawn/placement.ts";
1010 import { checkMove } from "../../../spawn/move_check.ts";
@@ -16,7 +16,7 @@ const sentSays = (n: number) => (n === 0 ? "This forge has sent no forges yet."
1616
1717 export const tool: Tool = {
1818 name: "forges",
19 doc: "an admin's list of the forges sent from here: name, address, whom for, apps, claimed, stage (sent/opened/signed in/last tell; resend true when unopened 3 days: claim_link), last activity (a person or the crew, never a heartbeat), who claimed it and when, keep cost, archive reason, reachable, size, use, madeFrom; `{ forge, plan?, dryRun? }` reads a forge's plan (small|medium|large) or, with `plan`, grants it by hand; `size` workshop raises a forge; `{ forge, sandbox: true }` reads what moving a forge out of this forge's own process into a sandbox would meet (hooks, command-running keys, size) and with `dryRun: false` moves it, proven and put back on any failure (`acknowledge: true` when it was held for what its repositories hold); each forge carries `placement` and `where`; gift codes: `codes` true lists, `code` {plan, uses?, note?, expires?} makes (shown once), `revoke` id; planned unless `dryRun` is false; `archive` a name or names stops each, writes its data and ledger as one file to the backup destination, then removes it; `restore` a name brings an archived one back; `kind` refused lists the last 20 refused first asks; `kind` clients lists each client in the page's words",
19 doc: "an admin's list of the forges sent from here: name, address, whom for, apps, claimed, stage (sent/opened/signed in/last tell; resend true when unopened 3 days: claim_link), last activity (a person or the crew, never a heartbeat), who claimed it and when, kept (its newest backup's age, or never kept), keep cost, archive reason, reachable, size, use, madeFrom; `{ forge, plan?, dryRun? }` reads a forge's plan (small|medium|large) or, with `plan`, grants it by hand; `size` workshop raises a forge; `{ forge, sandbox: true }` reads what moving a forge out of this forge's own process into a sandbox would meet (hooks, command-running keys, size) and with `dryRun: false` moves it, proven and put back on any failure (`acknowledge: true` when it was held for what its repositories hold); each forge carries `placement` and `where`; gift codes: `codes` true lists, `code` {plan, uses?, note?, expires?} makes (shown once), `revoke` id; planned unless `dryRun` is false; `archive` a name or names stops each, writes its data and ledger as one file to the backup destination, then removes it; `restore` a name brings an archived one back; `kind` refused lists the last 20 refused first asks; `kind` clients lists each client in the page's words",
2020 description:
2121 "Forges sent from here (admin), clients, a forge's plan or size.",
2222 inputSchema: { type: "object", properties: { kind: { type: "string", enum: ["refused", "clients"] }, forge: { type: "string" }, plan: { type: "string" }, codes: { type: "boolean" }, code: { type: "object" }, revoke: { type: "string" }, archive: { type: ["string", "array"], items: { type: "string" } }, restore: { type: "string" }, sandbox: { type: "boolean" }, size: { type: "string" }, acknowledge: { type: "boolean" }, dryRun: { type: "boolean" } } },
@@ -109,7 +109,7 @@ export const tool: Tool = {
109109 const forges = await clientRows(ctx.app);
110110 return good({
111111 says: sentSays(forges.length),
112 forges: forges.map(listed),
112 forges: listedKept(ctx.app, forges),
113113 });
114114 },
115115 };
src/snapshot/hosted.ts +13 −6
@@ -71,7 +71,12 @@ export function hostedSources(dataDir: string): HostedSource[] {
7171 return out;
7272 }
7373
74 const hours = (ms: number): string => (ms < 3_600_000 ? "under an hour" : `${Math.floor(ms / 3_600_000)} h`);
74 /** An age in plain words: under an hour, whole hours to two days, then whole days. */
75 export function ageWords(ms: number): string {
76 if (!(ms >= 3_600_000)) return "under an hour";
77 if (ms < 48 * 3_600_000) return `${Math.floor(ms / 3_600_000)} h`;
78 return `${Math.floor(ms / 86_400_000)} days`;
79 }
7580
7681 /**
7782 * The Backups line and the Resilience screen's head: how many hosted forges the newest snapshot
@@ -85,13 +90,15 @@ export function hostedWords(hosted: readonly HostedEntry[] | undefined): string
8590 return `${kept} hosted forge${kept === 1 ? "" : "s"} in the newest backup${left > 0 ? `; ${left} left out (see the log)` : ""}.`;
8691 }
8792
88 /** What /forges says beside one forge. */
93 /**
94 * What /forges, the `forges` MCP tool and the Resilience screen say beside one forge (#13833):
95 * `kept <age> ago`, `never kept` when no backup holds it, or why the newest one left it out.
96 */
8997 export function keptWords(hosted: readonly HostedEntry[] | undefined, name: string, now: number): string {
90 if (hosted === undefined) return "not in a backup yet";
91 const h = hosted.find((e) => e.name === name);
92 if (h === undefined) return "not in the newest backup";
98 const h = hosted?.find((e) => e.name === name);
99 if (h === undefined) return "never kept";
93100 if (h.why !== undefined) return `left out of the newest backup: ${h.why}`;
94 return `backed up ${hours(now - Date.parse(h.at))} ago`;
101 return `kept ${ageWords(now - Date.parse(h.at))} ago`;
95102 }
96103
97104 const keptFile = (dataDir: string): string => join(dataDir, "snapshot", "hosted.json");
src/spawn/clients.ts +10
@@ -11,6 +11,7 @@
1111
1212 import { liveChildDisk, readMountinfo, type ChildDisk } from "./disk_mount.ts";
1313 import type { App } from "../app.ts";
14 import { keptWords, readHosted } from "../snapshot/hosted.ts";
1415 import { childDirOf, listChildren, statusTokenOf, type Child } from "../actions/spawn.ts";
1516 import { timingSafeEqual } from "node:crypto";
1617 import { statSync } from "node:fs";
@@ -841,3 +842,12 @@ export function listed(r: ClientRow): Omit<ClientRow, "billTo"> {
841842 const { billTo: _kept, ...rest } = r;
842843 return rest;
843844 }
845
846 /**
847 * The rows as `listed`, each made forge with `kept`: the words /forges says beside it (#13833),
848 * read once from the record the nightly snapshot leaves.
849 */
850 export function listedKept(app: App, rows: readonly ClientRow[], now = Date.now()): (Omit<ClientRow, "billTo"> & { kept?: string })[] {
851 const hosted = readHosted(app.config.dataDir);
852 return rows.map((r) => (r.made ? { ...listed(r), kept: keptWords(hosted, r.name, now) } : listed(r)));
853 }
test/client-list.test.ts +2 −2
@@ -240,12 +240,12 @@ describe("the client list", () => {
240240 ]);
241241 const html = (await (await list(admin)).text()).replace(/\s+/g, " ");
242242 const maria = html.slice(html.indexOf('data-forge="maria"'));
243 expect(maria.slice(0, maria.indexOf("</li>"))).toContain("<span data-backed-up>backed up 5 h ago</span>");
243 expect(maria.slice(0, maria.indexOf("</li>"))).toContain("<span data-backed-up>kept 5 h ago</span>");
244244 const lou = html.slice(html.indexOf('data-forge="lou"'));
245245 expect(lou.slice(0, lou.indexOf("</li>"))).toContain("left out of the newest backup: its database would not open");
246246 rmSync(join(dir, "snapshot", "hosted.json"));
247247 const none = (await (await list(admin)).text()).replace(/\s+/g, " ");
248 expect(none).toContain("not in a backup yet");
248 expect(none).toContain("never kept");
249249 });
250250
251251 test("the admin's page carries the forges side by side: columns, shared use, no heartbeat yet", async () => {
test/forges-kept.test.ts added +97
@@ -0,0 +1,97 @@
1 /**
2 * Each hosted forge says when a backup last kept it (#13833): `kept <age> ago`, or `never kept`,
3 * in the same words on /forges and in the `forges` MCP listing.
4 */
5 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
6 import { mkdirSync, writeFileSync } from "node:fs";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { createApp, type App } from "../src/app.ts";
11 import { createToken } from "../src/core/tokens.ts";
12 import { createUser } from "../src/core/users.ts";
13 import { serve, type Servers } from "../src/http/server.ts";
14 import { ageWords, keptWords, noteHosted } from "../src/snapshot/hosted.ts";
15 import { useChildFetch } from "../src/spawn/clients.ts";
16 import { quietLogs } from "./helpers/globals.ts";
17
18 quietLogs();
19
20 const H = 3_600_000;
21
22 test("the age is in plain words: under an hour, hours, then days", () => {
23 expect(ageWords(10 * 60_000)).toBe("under an hour");
24 expect(ageWords(-5)).toBe("under an hour");
25 expect(ageWords(NaN)).toBe("under an hour");
26 expect(ageWords(3 * H)).toBe("3 h");
27 expect(ageWords(47 * H)).toBe("47 h");
28 expect(ageWords(75 * H)).toBe("3 days");
29 });
30
31 test("a kept forge says its age; one no backup holds says never kept", () => {
32 const now = Date.parse("2026-11-16T08:00:00Z");
33 const hosted = [{ name: "kid", at: "2026-11-16T05:00:00Z", repos: 1, bytes: 9, key: "wrapped" as const }];
34 expect(keptWords(hosted, "kid", now)).toBe("kept 3 h ago");
35 expect(keptWords(hosted, "new", now)).toBe("never kept");
36 expect(keptWords(undefined, "kid", now)).toBe("never kept");
37 });
38
39 describe("on /forges and over MCP", () => {
40 let dataDir = "";
41 let app: App;
42 let servers: Servers;
43 let token = "";
44 let cookie = "";
45
46 beforeAll(async () => {
47 dataDir = await mkdtemp(join(tmpdir(), "forge-forges-kept-"));
48 app = createApp({ dataDir, port: 0 });
49 mkdirSync(join(dataDir, "spawn"), { recursive: true });
50 const send = (name: string) =>
51 writeFileSync(
52 join(dataDir, "spawn", `${name}.json`),
53 JSON.stringify({ name, bodyId: `cell-${name}`, done: true, placement: "hosted", size: "small", apps: [], forWhom: "Ann", createdAt: new Date(Date.now() - H).toISOString() }),
54 );
55 send("kept");
56 send("fresh");
57 noteHosted(dataDir, [{ name: "kept", at: new Date(Date.now() - 5 * H).toISOString(), repos: 1, bytes: 9, key: "wrapped" }]);
58 useChildFetch(app, async () => Response.json({ claimed: false, link: { state: "open", revokedAt: null, usedAt: null } }));
59 servers = await serve(app);
60 const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
61 if (!u.ok) throw new Error(u.error);
62 token = createToken(app.db, u.value.id, "admin", "admin").token;
63 const r = await fetch(`${servers.url}/signin`, {
64 method: "POST",
65 headers: { origin: servers.url },
66 body: new URLSearchParams({ username: "alice", password: "a-good-passphrase" }),
67 redirect: "manual",
68 });
69 cookie = (r.headers.get("set-cookie") ?? "").split(";")[0]!;
70 }, 60_000);
71 afterAll(async () => {
72 servers.stop();
73 app.close();
74 await rm(dataDir, { recursive: true, force: true });
75 });
76
77 test("each row of /forges says kept <age> ago or never kept, one line per row", async () => {
78 const html = (await (await fetch(`${servers.url}/forges`, { headers: { cookie } })).text()).replace(/\s+/g, " ");
79 const rowOf = (name: string) => {
80 const from = html.slice(html.indexOf(`data-forge="${name}"`));
81 return from.slice(0, from.indexOf("</li>"));
82 };
83 expect(rowOf("kept")).toContain("<span data-backed-up>kept 5 h ago</span>");
84 expect(rowOf("fresh")).toContain("<span data-backed-up>never kept</span>");
85 expect(rowOf("kept").match(/data-backed-up/g)?.length).toBe(1);
86 });
87
88 test("the forges MCP listing carries the same words", async () => {
89 const res = await fetch(`${servers.url}/mcp`, {
90 method: "POST",
91 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
92 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "forges", arguments: {} } }),
93 });
94 const forges = JSON.parse(((await res.json()) as any).result.content[0].text).forges as { name: string; kept?: string }[];
95 expect(Object.fromEntries(forges.map((f) => [f.name, f.kept]))).toEqual({ kept: "kept 5 h ago", fresh: "never kept" });
96 });
97 });
test/hosted-surfaces.test.ts +1 −1
@@ -81,6 +81,6 @@ test("the Resilience screen says it, and which forge is kept or left out", async
8181 const text = tui.screen.toText();
8282 tui.stop();
8383 expect(text).toContain("1 hosted forge in the newest backup; 1 left out");
84 expect(text).toContain("kid: backed up 2 h ago");
84 expect(text).toContain("kid: kept 2 h ago");
8585 expect(text).toContain("sad: left out of the newest backup: its database would not open");
8686 });
test/snapshot-hosted.test.ts +3 −3
@@ -121,10 +121,10 @@ describe("hosted forges in the snapshot", () => {
121121 expect(hostedWords(hosted)).toBe("1 hosted forge in the newest backup; 1 left out (see the log).");
122122 expect(hostedWords([])).toBe("No hosted forges to keep.");
123123 expect(hostedWords(undefined)).toBeUndefined();
124 expect(keptWords(hosted, "kid", now)).toBe("backed up 5 h ago");
124 expect(keptWords(hosted, "kid", now)).toBe("kept 5 h ago");
125125 expect(keptWords(hosted, "sad", now)).toBe("left out of the newest backup: x");
126 expect(keptWords(hosted, "new", now)).toBe("not in the newest backup");
127 expect(keptWords(undefined, "kid", now)).toBe("not in a backup yet");
126 expect(keptWords(hosted, "new", now)).toBe("never kept");
127 expect(keptWords(undefined, "kid", now)).toBe("never kept");
128128 });
129129
130130 test("noteHosted and readHosted round-trip, and a missing, corrupt or ill-shaped file reads as little as it can", () => {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs