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

The client list downloads as a CSV: who was sent a forge, when, and what happened #14742

Merged opened this

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

Merged

scout/forge:scout/14461-the-client-list-downloads-as-a-csv-who-w → main 7 commits fork 2 threads · 2 unresolved

  • Merged. scout/14461-the-client-list-downloads-as-a-csv-who-w was merged into main as 8a8826b.

Review

Sign in to review this change.
8 files changed +160 −4
docs/features/clients-csv.md added +12
@@ -0,0 +1,12 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: The client list downloads as a CSV
4 ---
5 # The client list downloads as a CSV (#14461)
6
7 `/forges/export.csv`, linked as *Download as CSV* at the foot of *Forges you sent*, serves every forge you sent as `text/csv` with the header `client, forge, sent at, state, last seen` (`clientsCsv`, `src/spawn/clients_csv.ts`). The client is who it was sent for, else who claimed it; state is the page's own wording.
8
9 - **Safe in a spreadsheet.** Written by the wallet's writer (`src/text/csv_write.ts`): a text cell starting `=`, `+`, `-`, `@`, tab or CR gets a leading `'`, and quotes are doubled.
10 - **Who.** Admins only, as the page is; anyone else gets the answer a missing page gets.
11 - **Not filtered.** It is the whole list, not the current search or state. In the terminal, `c` on the forges screen (admin) writes the same file to `exports/forges-sent.csv` under the app data directory and toasts the path.
12 - **Tests.** `bun test test/clients-csv.test.ts`.
src/http/marks/forges.json +1
@@ -4,6 +4,7 @@
44 "routes": {
55 "/forges": "admin",
66 "/forges/refused": "admin",
7 "/forges/export.csv": "open",
78 "/forges/name/:name": "open",
89 "/forges/:name/bill": "open",
910 "/forges/:name/claim-link": "open",
src/http/server.ts +2 −1
@@ -331,7 +331,7 @@ import { claimFragmentPage, claimOptions, claimRenew, claimSubmit, welcomePage,
331331 import { firstAdminOptions, firstAdminPage, firstAdminSubmit } from "../web/pages/first-admin.ts";
332332 import { familyPage } from "../web/pages/family.ts";
333333 import { forgeLinkForm, forgeLinkRevoke, forgeLinkSubmit, forgeLinkUndo, forgeArchiveConfirm, forgeArchiveSubmit, forgeRestoreSubmit, forgeRemoveConfirm, forgeRemoveSubmit, forgeStopSubmit,
334 forgeOwnCodeSubmit, forgeSizeSubmit, forgeSandboxSubmit, forgesPage } from "../web/pages/forges.ts";
334 forgeOwnCodeSubmit, forgeSizeSubmit, forgeSandboxSubmit, forgesPage, forgesCsv } from "../web/pages/forges.ts";
335335 import { billDownload } from "./api/forge_bill.ts";
336336 import { forgeRecoveryForm, forgeRecoverySubmit } from "../web/pages/forges.ts";
337337 import { forgesRefusedPage } from "../web/pages/forges-refused.ts";
@@ -977,6 +977,7 @@ export function buildRouter(): Router<Handler> {
977977 router.add("POST", "/first-admin/options", firstAdminOptions);
978978 // "+ New forge": the spawn door as a page, any signed-in person (spawn/door.ts).
979979 router.add("GET", "/forges", forgesPage);
980 router.add("GET", "/forges/export.csv", forgesCsv);
980981 router.add("GET", "/forges/refused", forgesRefusedPage);
981982 router.add("GET", "/forges/archive", forgeArchiveConfirm);
982983 router.add("POST", "/forges/archive", forgeArchiveSubmit);
src/spawn/clients_csv.ts added +27
@@ -0,0 +1,27 @@
1 /**
2 * The client list as one CSV (#14461): who was sent a forge, when, and what happened. The same
3 * rows the page shows, written by the one formula-safe writer (`text/csv_write.ts`), so a person's
4 * name starting `=` is neutralised exactly as in the wallet's CSV.
5 */
6 import { mkdirSync, writeFileSync } from "node:fs";
7 import { join } from "node:path";
8 import { toCsv } from "../text/csv_write.ts";
9 import { CLAIM_WORDS, claimState, type ClientRow } from "./clients.ts";
10
11 export const CLIENTS_CSV_HEADER = ["client", "forge", "sent at", "state", "last seen"] as const;
12
13 /** The client is who it was sent for, else whoever claimed it; empty when neither is known. */
14 export const clientsCsv = (rows: readonly ClientRow[]): string =>
15 toCsv(
16 CLIENTS_CSV_HEADER,
17 rows.map((r) => [r.for ?? r.claimedBy ?? "", r.name, r.sentAt ?? "", CLAIM_WORDS[claimState(r)], r.lastActivityAt ?? ""]),
18 );
19
20 /** The terminal's door: the same CSV written under the app's data directory; returns the path. */
21 export function writeClientsCsv(dataDir: string, rows: readonly ClientRow[]): string {
22 const dir = join(dataDir, "exports");
23 mkdirSync(dir, { recursive: true });
24 const file = join(dir, "forges-sent.csv");
25 writeFileSync(file, clientsCsv(rows));
26 return file;
27 }
src/tui/screens/forges.ts +4 −1
@@ -17,6 +17,7 @@ import { parseClientQuery, searchClients } from "../../spawn/client_search.ts";
1717 import { CLIENT_STATE_EMPTY, CLIENT_STATE_WORDS, narrowByState, nextClientState, type ClientState } from "../../spawn/client_state.ts";
1818 import { diskWords } from "../../spawn/disk_mount.ts";
1919 import { archiveForge, archivedForges, destinationWords, restoreForge } from "../../spawn/archive.ts";
20 import { writeClientsCsv } from "../../spawn/clients_csv.ts";
2021 import { claimedWords, keepWords } from "../../spawn/keep_words.ts";
2122 import { changeLink, ownCode, removeForge, resizeForge, stopForge } from "../../spawn/manage.ts";
2223 import { moveToCell } from "../../spawn/move_cell.ts";
@@ -230,7 +231,7 @@ export function forgesScreen(ctx: Ctx, rows: readonly ClientRow[], session?: Ses
230231 };
231232 const screen: Screen = {
232233 title: "Forges you sent",
233 keys: [binding(["s"], "stop"), binding(["a"], "archive"), binding(["r"], "restore"), binding(["x"], "remove"), binding(["n"], "new link"), binding(["l"], "end a link"), binding(["u"], "undo an ended link"), binding(["o"], "own code or this forge's"), binding(["m"], "move"), binding(["w"], "raise to xlarge"), binding(["f"], "state"), binding(["/"], "search"), binding(["esc"], "close")],
234 keys: [binding(["s"], "stop"), binding(["a"], "archive"), binding(["r"], "restore"), binding(["x"], "remove"), binding(["n"], "new link"), binding(["l"], "end a link"), binding(["u"], "undo an ended link"), binding(["o"], "own code or this forge's"), binding(["m"], "move"), binding(["w"], "raise to xlarge"), binding(["f"], "state"), binding(["/"], "search"), binding(["c"], "csv"), binding(["esc"], "close")],
234235 render(area, s) {
235236 const c = ctx.theme.c;
236237 const w = Math.min(100, Math.max(30, area.w - 6));
@@ -261,6 +262,8 @@ export function forgesScreen(ctx: Ctx, rows: readonly ClientRow[], session?: Ses
261262 );
262263 else if (e.key === "s" && session !== undefined)
263264 choose("Stop which forge?", (name) => void stopForge(session.app, name).then((done) => ctx.toast(done.says, done.ok ? "success" : "danger")));
outdated

Both doors: this only toasts where the CSV is on the web; it is not a terminal door. Produce the CSV from the terminal (clientsCsv is already a plain function) and say where it went.

265 else if (e.key === "c" && session !== undefined && session.user?.isAdmin === true)
266 ctx.toast(`Wrote ${String(rows.length)} forges to ${writeClientsCsv(session.app.config.dataDir, rows)}`, "success");
264267 else if (e.key === "n") newLink();
265268 else if (e.key === "l") changeOne("revoke");
266269 else if (e.key === "u") changeOne("undo");
src/web/pages/forges.ts +17 −1
@@ -28,6 +28,7 @@ import { readOwnCode } from "../../spawn/own_code.ts";
2828 import { moveToCell } from "../../spawn/move_cell.ts";
2929 import { sealedAt } from "../../spawn/sealed.ts";
3030 import { countRefusals, mayReadRefusals } from "../../core/first_ask_refusals.ts";
31 import { clientsCsv } from "../../spawn/clients_csv.ts";
3132 import { claimLinkBody } from "./new-forge.ts";
3233 import { whenWords } from "./claim.ts";
3334 import { appLinkSummary, appLinkWords } from "../../spawn/app_links.ts";
@@ -236,6 +237,21 @@ function refusedLink(ctx: Ctx): Html | null {
236237 return n === 0 ? null : html` <a href="/forges/refused">Refused first asks (${n})</a>`;
237238 }
238239
240 // GET /forges/export.csv — the client list as a download, behind the page's own gate (a missing
241 // page to anyone else).
242 export async function forgesCsv(ctx: Ctx): Promise<Response> {
243 if (!ctx.auth.user?.isAdmin) return notFoundPage(ctx);

Box 2: the route is marked admin in marks/forges.json, so non-admins are refused (403) before this handler runs and never get the missing-page answer this line intends. Make both paths give the same 404 and assert it in the test.

244 const rows = sortForges(await servedRows(ctx.app), "attention");
245 return new Response(clientsCsv(rows), {
246 headers: {
247 "content-type": "text/csv; charset=utf-8",
248 "content-disposition": 'attachment; filename="forges-sent.csv"',
249 "x-content-type-options": "nosniff",
250 "cache-control": "private, no-store",
251 },
252 });
253 }
254
239255 // GET /forges — an admin's only.
240256 export async function forgesPage(ctx: Ctx): Promise<Response> {
241257 const user = ctx.auth.user;
@@ -310,7 +326,7 @@ export async function forgesPage(ctx: Ctx): Promise<Response> {
310326 ${sealedLine(ctx)}
311327 ${archivedSection(ctx, archived)}
312328 ${await ownCodeSection(ctx)}
313 <p class="mt"><a href="/fleet/graph">Fleet graph</a> <a href="${REACH_SETTINGS}">What hosted forges may reach</a>${refusedLink(ctx)}</p>
329 <p class="mt"><a href="/fleet/graph">Fleet graph</a>${everyone.length === 0 ? null : html` <a href="/forges/export.csv" download>Download as CSV</a>`} <a href="${REACH_SETTINGS}">What hosted forges may reach</a>${refusedLink(ctx)}</p>
314330 </div>`,
315331 });
316332 notePhase(ctx.request, "render", performance.now() - rendering);
test/clients-csv.test.ts added +96
@@ -0,0 +1,96 @@
1 /** The client list downloads as a CSV (#14461). */
2
3 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
4 import { mkdtemp, rm } from "node:fs/promises";
5 import { tmpdir } from "node:os";
6 import { join } from "node:path";
7 import { createApp, type App } from "../src/app.ts";
8 import { createToken } from "../src/core/tokens.ts";
9 import { createUser } from "../src/core/users.ts";
10 import { serve, type Servers } from "../src/http/server.ts";
11 import type { ClientRow } from "../src/spawn/clients.ts";
12 import { readFileSync } from "node:fs";
13 import { CLIENTS_CSV_HEADER, clientsCsv, writeClientsCsv } from "../src/spawn/clients_csv.ts";
14 import { quietLogs } from "./helpers/globals.ts";
15
16 quietLogs();
17
18 const row = (over: Record<string, unknown>) =>
19 ({ name: "n", for: null, claimedBy: null, sentAt: null, lastActivityAt: null, made: true, claimed: false, apps: [], ...over }) as unknown as ClientRow;
20
21 describe("clientsCsv", () => {
22 test("header row, then one row per forge", () => {
23 const out = clientsCsv([row({ name: "maria", for: "Maria", sentAt: "2026-01-02T03:04:05Z", lastActivityAt: "2026-02-01T00:00:00Z", claimed: true })]);
24 expect(out.split("\r\n")[0]).toBe(CLIENTS_CSV_HEADER.join(","));
25 expect(CLIENTS_CSV_HEADER).toEqual(["client", "forge", "sent at", "state", "last seen"]);
26 expect(out.split("\r\n")[1]).toBe("Maria,maria,2026-01-02T03:04:05Z,Claimed,2026-02-01T00:00:00Z");
27 });
28 test("an injecting cell is prefixed and quotes are doubled", () => {
29 const out = clientsCsv([row({ for: '=HYPERLINK("http://x")' }), row({ for: "+1", name: "@a" }), row({ for: "-2" })]);
30 expect(out).toContain(`"'=HYPERLINK(""http://x"")"`);
31 expect(out).toContain("'+1,'@a,");
32 expect(out).toContain("'-2,");
33 });
34 });
35
36 test("the terminal door writes the file under the data directory", async () => {
37 const d = await mkdtemp(join(tmpdir(), "forge-clients-csv-tui-"));
38 try {
39 const file = writeClientsCsv(d, [row({ name: "maria", for: "Maria" })]);
40 expect(file).toBe(join(d, "exports", "forges-sent.csv"));
41 expect(readFileSync(file, "utf8")).toBe(clientsCsv([row({ name: "maria", for: "Maria" })]));
42 } finally {
43 await rm(d, { recursive: true, force: true });
44 }
45 });
46
47 describe("GET /forges/export.csv", () => {
48 let dir = "";
49 let app: App;
50 let servers: Servers;
51 const pw = "a-long-clients-csv-passphrase";
52 const signin = async (username: string) => {
53 const res = await fetch(`${servers.url}/signin`, { method: "POST", body: new URLSearchParams({ username, password: pw }), redirect: "manual" });
54 return (res.headers.get("set-cookie") ?? "").split(";")[0]!;
55 };
56 beforeAll(async () => {
57 dir = await mkdtemp(join(tmpdir(), "forge-clients-csv-"));
58 app = createApp({ dataDir: dir, url: "https://forge.test", port: 0 });
59 await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: pw, isAdmin: true });
60 await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: pw });
61 servers = await serve(app);
62 });
63 afterAll(async () => {
64 await servers.stop();
65 await rm(dir, { recursive: true, force: true });
66 });
67
68 test("an admin gets text/csv with the header", async () => {
69 const res = await fetch(`${servers.url}/forges/export.csv`, { headers: { cookie: await signin("alice") } });
70 expect(res.status).toBe(200);
71 expect(res.headers.get("content-type")).toContain("text/csv");
72 expect(await res.text()).toBe("client,forge,sent at,state,last seen\r\n");
73 });
74 test("a forge that was sent is a row, with who it was for", async () => {
75 const alice = (await createUser(app.db, { origin: "seed", trusted: true, username: "carol", email: "[email protected]", password: pw, isAdmin: true }));
76 if (!alice.ok) throw new Error("user");
77 const token = createToken(app.db, alice.value.id, "rw", "rw").token;
78 const made = await fetch(`${servers.url}/api/v1/forges`, {
79 method: "POST",
80 headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
81 body: JSON.stringify({ name: "maria", for: "Maria at the bakery", dryRun: false }),
82 });
83 expect(made.status).toBe(201);
84 const res = await fetch(`${servers.url}/forges/export.csv`, { headers: { cookie: await signin("carol") } });
85 const lines = (await res.text()).split("\r\n");
86 expect(lines[0]).toBe("client,forge,sent at,state,last seen");
87 expect(lines[1]).toMatch(/^Maria at the bakery,maria,\d{4}-/);
88 });
89 test("anyone else is refused, and gets no CSV", async () => {
90 for (const cookie of ["", await signin("bob")]) {
91 const res = await fetch(`${servers.url}/forges/export.csv`, { headers: { cookie } });
92 expect(res.status).toBe(404);
93 expect(res.headers.get("content-type")).not.toContain("text/csv");
94 }
95 });
96 });
test/design-audit.test.ts +1 −1
@@ -17,7 +17,7 @@ const doc = readFileSync("docs/design/audit.md", "utf8");
1717
1818 /** Routes that answer a file, a fragment, a redirect hop or a callback. */
1919 const NOT_PAGES =
20 /^\/(assets\/|\.well-known\/|icons\/|og\/|live\/|__forge\/|go\/|new\/issue$|events$|system\/stream$|talk\/stream$|settings\/teams\/stream$|sw\.js$|offline$|robots\.txt$|favicon\.ico$|apple-touch-icon(-precomposed)?\.png$|sitemap\.xml$|manifest\.webmanifest$|opensearch\.xml$|llms(-full)?\.txt$|openapi\.json$|releases\.json$|maintenance\.json$|changelog\.atom$|explore\.atom$|docs(\/[^/]*)?$|audit\.csv$|settings\/traffic\/scrapes\/export$|fleet\/graph\/live$|fleet\/graph\.csv$|settings\/origins\/callback$|broker\/origins\/start$|home\/archived\/|settings\/backups\/live$|api\/v1(\/|$))/;
20 /^\/(assets\/|\.well-known\/|icons\/|og\/|live\/|__forge\/|go\/|new\/issue$|events$|system\/stream$|talk\/stream$|settings\/teams\/stream$|sw\.js$|offline$|robots\.txt$|favicon\.ico$|apple-touch-icon(-precomposed)?\.png$|sitemap\.xml$|manifest\.webmanifest$|opensearch\.xml$|llms(-full)?\.txt$|openapi\.json$|releases\.json$|maintenance\.json$|changelog\.atom$|explore\.atom$|docs(\/[^/]*)?$|audit\.csv$|settings\/traffic\/scrapes\/export$|fleet\/graph\/live$|fleet\/graph\.csv$|forges\/export\.csv$|settings\/origins\/callback$|broker\/origins\/start$|home\/archived\/|settings\/backups\/live$|api\/v1(\/|$))/;
2121
2222 const getRoutes = [
2323 ...server.matchAll(/router\.add\(\s*"GET",\s*"([^"]+)"/g),

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs