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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13833-forges-says-when-each-hosted-forge-was-l → main 3 commits fork
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 | ||
| 16 | 16 | ## Where it shows |
| 17 | 17 | |
| 18 | 18 | - 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. | |
| 21 | 22 | |
| 22 | 23 | ## Restore one forge |
| 23 | 24 |
src/http/api/forges.ts +5 −4
| @@ -11,7 +11,7 @@ import { listChildren } from "../../actions/spawn.ts"; | ||
| 11 | 11 | import { usdWords } from "../../spawn/credit.ts"; |
| 12 | 12 | import { fundingOf, fundingWords, refreshFunding } from "../../spawn/funding.ts"; |
| 13 | 13 | 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"; | |
| 15 | 15 | import { previewDoor, reissueDoor, spawnDoor } from "../../spawn/door.ts"; |
| 16 | 16 | import { checkMove } from "../../spawn/move_check.ts"; |
| 17 | 17 | import { moveToCell } from "../../spawn/move_cell.ts"; |
| @@ -77,11 +77,12 @@ export function forgeRoutes(router: Router<Handler>): void { | ||
| 77 | 77 | // where it is placed. |
| 78 | 78 | const [rows, children] = await Promise.all([clientRows(ctx.app), listChildren(ctx.app)]); |
| 79 | 79 | 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) => { | |
| 81 | 82 | const c = kept.get(row.name); |
| 82 | 83 | 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 }) }; | |
| 85 | 86 | }); |
| 86 | 87 | }); |
| 87 | 88 | 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 | ||
| 4 | 4 | import { publicOrigin } from "../../../core/public_origin.ts"; |
| 5 | 5 | import { scopeAllows } from "../../../core/tokens.ts"; |
| 6 | 6 | import { clientLines } from "../../../spawn/client_words.ts"; |
| 7 | import { clientRows, listed } from "../../../spawn/clients.ts"; | |
| 7 | import { clientRows, listedKept } from "../../../spawn/clients.ts"; | |
| 8 | 8 | import { archiveForge, archivedForges, restoreForge } from "../../../spawn/archive.ts"; |
| 9 | 9 | import { CHILD_NAME } from "../../../spawn/placement.ts"; |
| 10 | 10 | import { checkMove } from "../../../spawn/move_check.ts"; |
| @@ -16,7 +16,7 @@ const sentSays = (n: number) => (n === 0 ? "This forge has sent no forges yet." | ||
| 16 | 16 | |
| 17 | 17 | export const tool: Tool = { |
| 18 | 18 | 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", | |
| 20 | 20 | description: |
| 21 | 21 | "Forges sent from here (admin), clients, a forge's plan or size.", |
| 22 | 22 | 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 = { | ||
| 109 | 109 | const forges = await clientRows(ctx.app); |
| 110 | 110 | return good({ |
| 111 | 111 | says: sentSays(forges.length), |
| 112 | forges: forges.map(listed), | |
| 112 | forges: listedKept(ctx.app, forges), | |
| 113 | 113 | }); |
| 114 | 114 | }, |
| 115 | 115 | }; |
src/snapshot/hosted.ts +13 −6
| @@ -71,7 +71,12 @@ export function hostedSources(dataDir: string): HostedSource[] { | ||
| 71 | 71 | return out; |
| 72 | 72 | } |
| 73 | 73 | |
| 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 | } | |
| 75 | 80 | |
| 76 | 81 | /** |
| 77 | 82 | * 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 | ||
| 85 | 90 | return `${kept} hosted forge${kept === 1 ? "" : "s"} in the newest backup${left > 0 ? `; ${left} left out (see the log)` : ""}.`; |
| 86 | 91 | } |
| 87 | 92 | |
| 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 | */ | |
| 89 | 97 | 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"; | |
| 93 | 100 | 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`; | |
| 95 | 102 | } |
| 96 | 103 | |
| 97 | 104 | const keptFile = (dataDir: string): string => join(dataDir, "snapshot", "hosted.json"); |
src/spawn/clients.ts +10
| @@ -11,6 +11,7 @@ | ||
| 11 | 11 | |
| 12 | 12 | import { liveChildDisk, readMountinfo, type ChildDisk } from "./disk_mount.ts"; |
| 13 | 13 | import type { App } from "../app.ts"; |
| 14 | import { keptWords, readHosted } from "../snapshot/hosted.ts"; | |
| 14 | 15 | import { childDirOf, listChildren, statusTokenOf, type Child } from "../actions/spawn.ts"; |
| 15 | 16 | import { timingSafeEqual } from "node:crypto"; |
| 16 | 17 | import { statSync } from "node:fs"; |
| @@ -841,3 +842,12 @@ export function listed(r: ClientRow): Omit<ClientRow, "billTo"> { | ||
| 841 | 842 | const { billTo: _kept, ...rest } = r; |
| 842 | 843 | return rest; |
| 843 | 844 | } |
| 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", () => { | ||
| 240 | 240 | ]); |
| 241 | 241 | const html = (await (await list(admin)).text()).replace(/\s+/g, " "); |
| 242 | 242 | 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>"); | |
| 244 | 244 | const lou = html.slice(html.indexOf('data-forge="lou"')); |
| 245 | 245 | expect(lou.slice(0, lou.indexOf("</li>"))).toContain("left out of the newest backup: its database would not open"); |
| 246 | 246 | rmSync(join(dir, "snapshot", "hosted.json")); |
| 247 | 247 | 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"); | |
| 249 | 249 | }); |
| 250 | 250 | |
| 251 | 251 | 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 | ||
| 81 | 81 | const text = tui.screen.toText(); |
| 82 | 82 | tui.stop(); |
| 83 | 83 | 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"); | |
| 85 | 85 | expect(text).toContain("sad: left out of the newest backup: its database would not open"); |
| 86 | 86 | }); |
test/snapshot-hosted.test.ts +3 −3
| @@ -121,10 +121,10 @@ describe("hosted forges in the snapshot", () => { | ||
| 121 | 121 | expect(hostedWords(hosted)).toBe("1 hosted forge in the newest backup; 1 left out (see the log)."); |
| 122 | 122 | expect(hostedWords([])).toBe("No hosted forges to keep."); |
| 123 | 123 | 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"); | |
| 125 | 125 | 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"); | |
| 128 | 128 | }); |
| 129 | 129 | |
| 130 | 130 | test("noteHosted and readHosted round-trip, and a missing, corrupt or ill-shaped file reads as little as it can", () => { |
new above
offline