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

The monthly statement downloads as CSV, one row per ledger entry #13992

Merged opened this

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

Merged

torque/forge:torque/13978-the-monthly-statement-downloads-as-csv-o → main 3 commits fork 2 threads · 2 unresolved

  • Merged. torque/13978-the-monthly-statement-downloads-as-csv-o was merged into main as 43fda34.

Review

Sign in to review this change.
7 files changed +298 −6
docs/features/statement.md +7
@@ -18,6 +18,11 @@ The total is the unrounded sum, rounded once to the cent.
1818 - **Read it** at `GET /api/v1/repos/:owner/:name/statement?month=2026-10`;
1919 `format=csv` (or `accept: text/csv`) is the same lines as a table file.
2020 Without `month`, this month so far.
21 - **Download the ledger** at `/:owner/:name/settings/app/statement.csv?month=2026-10`
22 (the page's "CSV, every ledger entry" link): one row per ledger entry (`date,kind,amount_usd,what`),
23 then awake, storage and margin rows and a `total` row that is the page's total.
24 A field beginning `= + - @` is prefixed with `'` so a spreadsheet reads text, not a formula.
25 A bad month is 422.
2126 - **Print it** from the repository's Settings → App → Statement
2227 (`/:owner/:name/settings/app/statement`); printing hides the navigation.
2328 - **At the terminal**, open the repository and pick `owner/name — Statement`
@@ -25,3 +30,5 @@ The total is the unrounded sum, rounded once to the cent.
2530 (YYYY-MM), `[` and `]` step back and forward.
2631
2732 The repository's admins and forge admins can read it; anyone else gets a 404.
33 - **At the terminal**, `l` on the statement screen swaps the lines for the
34 ledger entries, one row per crew run (what it paid for, date, kind, cost).
src/core/statement_ledger.ts added +99
@@ -0,0 +1,99 @@
1 /**
2 * The statement as a ledger file (#13978): one CSV row per ledger entry, for
3 * an accountant who wants a file, not a page. Columns: date (UTC ISO 8601),
4 * kind, amount_usd, what.
5 *
6 * Rows, in order:
7 * - one per crew run that the month's ledger (`usage`) holds for this app,
8 * at cost: kind is what the run was for (build, plan, review, check), amount
9 * is the provider's cost in US dollars to six places, and what is the
10 * issue's title and number, or the run when it served no issue;
11 * - one each for awake time, storage and the margin on crew spend, dated the
12 * month's first day, amounts as the statement bills them (two decimals);
13 * - a `total` row carrying the statement's total, the figure the page shows.
14 *
15 * The entries at cost are unrounded; the statement rounds once, to the cent, so
16 * the rows may differ from the total by under a cent. The total row is never
17 * summed here: it is `Statement.total`, so the file and the page cannot differ.
18 *
19 * Spreadsheet injection: a text field that begins with = + - @, a tab or a
20 * carriage return is prefixed with an apostrophe (OWASP "CSV Injection"), then
21 * quoted per RFC 4180 when it holds a comma, quote or line break.
22 */
23
24 import type { Database } from "bun:sqlite";
25 import { monthRange, type Statement } from "./revenue.ts";
26
27 export interface LedgerEntry {
28 readonly at: string;
29 readonly kind: string;
30 readonly costUsd: number;
31 readonly runId: string | null;
32 readonly issueNumber: number | null;
33 readonly issueTitle: string | null;
34 }
35
36 /** The crew runs one repository's ledger holds in a month, oldest first (index `usage_repo`). */
37 export function ledgerEntries(db: Database, repoId: string, month: string): LedgerEntry[] {
38 const { from, to } = monthRange(month);
39 return db
40 .query<
41 { at: string; kind: string; cost_usd: number; run_id: string | null; number: number | null; title: string | null },
42 [string, string, string]
43 >(
44 `SELECT usage.at, usage.kind, usage.cost_usd, usage.run_id, issue.number, issue.title
45 FROM usage LEFT JOIN issue ON issue.id = usage.issue_id
46 WHERE usage.repo_id = ?1 AND usage.at >= ?2 AND usage.at < ?3
47 ORDER BY usage.at, usage.run_id`,
48 )
49 .all(repoId, from, to)
50 .map((r) => ({
51 at: r.at,
52 kind: r.kind,
53 costUsd: r.cost_usd,
54 runId: r.run_id,
55 issueNumber: r.number,
56 issueTitle: r.title,
57 }));
58 }
59
60 /** A field as one CSV cell: a leading = + - @ tab or CR defused, then quoted when it needs it. */
61 export function csvCell(value: string): string {
62 const s = /^[=+\-@\t\r]/.test(value) ? `'${value}` : value;
63 return /[",\r\n]/.test(s) ? `"${s.replaceAll('"', '""')}"` : s;
64 }
65
66 /** Cost to six places with the trailing zeros dropped, never an exponent. */
67 const money6 = (n: number): string => String(Number(n.toFixed(6)));
68
69 /**
70 * What an entry paid for: the issue's title and number (a person wrote the title; csvCell defuses
71 * it), else the run.
72 */
73 export function entryLabel(e: LedgerEntry): string {
74 return e.issueNumber === null
75 ? `Crew run${e.runId === null ? "" : ` ${e.runId}`}`
76 : `${e.issueTitle ?? ""} (#${e.issueNumber})`;
77 }
78
79 /** An entry's cost as the file prints it. */
80 export const entryAmount = money6;
81
82 export function ledgerCsv(s: Statement, entries: readonly LedgerEntry[]): string {
83 const first = s.from.slice(0, 10);
84 const rows: string[][] = [["date", "kind", "amount_usd", "what"]];
85 for (const e of entries) {
86 rows.push([e.at, e.kind, money6(e.costUsd), entryLabel(e)]);
87 }
88 const line = (what: string) => s.lines.find((l) => l.what.startsWith(what));
89 for (const [kind, prefix] of [
90 ["awake", "Awake time"],
91 ["storage", "Storage"],
92 ["margin", "Margin"],
93 ] as const) {
94 const l = line(prefix);
95 if (l) rows.push([first, kind, l.amount.toFixed(2), `${l.what}: ${l.quantity} ${l.unit} at $${l.price}`]);
96 }
97 rows.push([first, "total", s.total.toFixed(2), `Total for ${s.app}, ${s.month} (UTC)`]);
98 return rows.map((r) => r.map(csvCell).join(",")).join("\r\n") + "\r\n";
99 }
src/http/server.ts +2 −1
@@ -592,7 +592,7 @@ import { startTimers } from "../apps/timer_service.ts";
592592 import { startPullSchedule } from "../apps/pull_schedule.ts";
593593 import { startGithubPull } from "../perf/github_traffic.ts";
594594 import { appSourcesPage } from "../web/pages/sources.ts";
595 import { statementPage } from "../web/pages/statement.ts";
595 import { statementCsvDownload, statementPage } from "../web/pages/statement.ts";
596596 import { createViewWriter } from "../perf/views_store.ts";
597597 import { createReadWriter, readOf } from "../perf/reads.ts";
598598 import { parseServerTiming } from "../perf/record.ts";
@@ -1743,6 +1743,7 @@ export function buildRouter(): Router<Handler> {
17431743 router.add("GET", "/:owner/:name/settings/app", appSettingsPage);
17441744 router.add("GET", "/:owner/:name/settings/app/traffic", appSourcesPage);
17451745 router.add("GET", "/:owner/:name/settings/app/statement", statementPage);
1746 router.add("GET", "/:owner/:name/settings/app/statement.csv", statementCsvDownload);
17461747 router.add("GET", "/:owner/:name/settings/machines", machinesSettingsPage);
17471748 // The shell page; an upgrade at the same path is the socket (`machines/shell.ts`).
17481749 router.add("GET", "/:owner/:name/machines/:machine/shell", machineShellPage);
src/tui/screens/statement.ts +32 −4
@@ -6,10 +6,13 @@
66 * anyone else, were the screen reached, sees no lines.
77 *
88 * `m` types a month (YYYY-MM, UTC), `[` and `]` step a month back and
9 * forward. Read-only; amounts in US dollars.
9 * forward, `l` swaps the lines for the ledger entries (one row per crew run,
10 * as the web page's ledger CSV holds them) and back. Read-only; amounts in
11 * US dollars.
1012 */
1113
1214 import { STATEMENT_WORDS, mayReadStatement, readStatement } from "../../actions/statement.ts";
15 import { entryAmount, entryLabel, ledgerEntries, type LedgerEntry } from "../../core/statement_ledger.ts";
1316 import { monthOf, monthRange, parseMonth, type Statement } from "../../core/revenue.ts";
1417 import type { Repo } from "../../core/repos.ts";
1518 import type { Ctx, Screen } from "../app/app.ts";
@@ -44,29 +47,54 @@ export function statementRows(s: Statement): ListRow[] {
4447 ];
4548 }
4649
50 /**
51 * One row per ledger entry: what it paid for, then date, kind and cost; a month with none says so.
52 */
53 export function ledgerRows(entries: readonly LedgerEntry[]): ListRow[] {
54 if (entries.length === 0) return [{ title: "No crew runs this month", meta: "" }];
55 return entries.map((e) => ({
56 title: entryLabel(e),
57 meta: `${e.at.slice(0, 10)} ${e.kind} $${entryAmount(e.costUsd)}`,
58 }));
59 }
60
4761 export function statementScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
4862 const state = new ListState();
outdated

Both doors: a URL printed in the header is not the feature in the terminal. Show the ledger entries as rows or justify in the pull why not; it is also cut off by truncate on a narrow screen.

4963 let month: string | undefined;
64 let ledger = false;
5065 const read = () => readStatement(f.app, f.user, repo, month);
5166 const screen: Screen = {
5267 title: `${repo.ownerName}/${repo.name} — Statement`,
5368 keys: [
5469 binding(["j", "k"], "move cursor"),
5570 binding(["m"], "month"),
71 binding(["l"], "lines / ledger entries"),
5672 binding(["[", "]"], "previous/next month"),
5773 ],
5874 render(area, s) {
5975 const c = ctx.theme.c;
6076 const r = read();
6177 const [head, list] = split(area, "v", [len(1), fill(1)]);
62 const said = r.ok ? `${r.value.month} (UTC) · USD` : r.error === "bad_month" ? STATEMENT_WORDS.bad_month : "";
78 const said = r.ok
79 ? `${r.value.month} (UTC) · USD · ${ledger ? "ledger entries" : "lines"}`
80 : r.error === "bad_month" ? STATEMENT_WORDS.bad_month : "";
6381 s.text(head!.x, head!.y, truncate(said, head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
64 drawList(s, list!, c, state, r.ok ? statementRows(r.value) : []);
82 const rows = !r.ok
83 ? []
84 : ledger ? ledgerRows(ledgerEntries(f.app.db, repo.id, r.value.month)) : statementRows(r.value);
85 drawList(s, list!, c, state, rows);
6586 },
6687 key(e) {
6788 const r = read();
6889 if (!r.ok && r.error === "not_found") return false;
69 if (state.key(e, r.ok ? r.value.lines.length + 1 : 0)) return true;
90 if (e.key === "l" && r.ok) {
91 ledger = !ledger;
92 return true;
93 }
94 const count = !r.ok
95 ? 0
96 : ledger ? Math.max(1, ledgerEntries(f.app.db, repo.id, r.value.month).length) : r.value.lines.length + 1;
97 if (state.key(e, count)) return true;
7098 if ((e.key === "[" || e.key === "]") && r.ok) {
7199 const next = stepMonth(r.value.month, e.key === "]" ? 1 : -1);
72100 if (next !== undefined) month = next;
src/web/pages/statement.ts +31 −1
@@ -5,11 +5,17 @@
55 * the total, in US dollars. Printing the page prints the statement alone:
66 * the shared print rules (`style/base.ts`) hide the navigation and picker. For the
77 * repository's admins and forge admins; anyone else gets the not-found page.
8 *
9 * GET …/statement.csv?month=YYYY-MM (#13978) is the same month as a ledger
10 * file, one row per ledger entry (`core/statement_ledger.ts`), same gate, same
11 * month check (422 on a bad month), same total as the page.
812 */
913
1014 import { STATEMENT_WORDS, mayReadStatement, readStatement } from "../../actions/statement.ts";
1115 import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
1216 import type { Ctx } from "../../http/context.ts";
17 import { ledgerCsv, ledgerEntries } from "../../core/statement_ledger.ts";
18 import { securityFloor } from "../../http/respond.ts";
1319 import { loadRepo, repoNotFound } from "../chrome.ts";
1420 import { html } from "../html.ts";
1521 import { settingsPageResponse } from "./settings.ts";
@@ -74,10 +80,34 @@ export function statementPage(ctx: Ctx): Response {
7480 </tfoot>
7581 </table>
7682 </div>
77 <p class="small mt" data-statement-pick data-print-hide><a href="${api}${q}&format=csv">CSV</a> · <a href="${api}${q}">JSON</a></p>
83 <p class="small mt" data-statement-pick data-print-hide><a href="/${repo.ownerName}/${repo.name}/settings/app/statement.csv${q}" download>CSV, every ledger entry</a> · <a href="${api}${q}&format=csv">CSV, the statement's lines</a> · <a href="${api}${q}">JSON</a></p>
outdated

Principles 1 and 8: two CSV links for the same month, side by side, explain themselves twice. Keep one CSV link and name it plainly.

7884 </section>`;
7985 }
8086 const response = settingsPageResponse(ctx, repo, "app", "Statement", body, undefined, read.ok ? 200 : 422);
8187 notePhase(ctx.request, "render", performance.now() - rendering);
8288 return response;
8389 }
90
91 export function statementCsvDownload(ctx: Ctx): Response {
92 const repo = loadRepo(ctx);
93 if (!repo || !mayReadStatement(ctx.app, repo, ctx.auth.user)) return repoNotFound(ctx);
94 const asked = ctx.url.searchParams.get("month");
95 const read = readStatement(ctx.app, ctx.auth.user, repo, asked === null || asked === "" ? undefined : asked);
96 if (!read.ok) {
97 if (read.error === "not_found") return repoNotFound(ctx);
98 return securityFloor(
99 Response.json({ error: read.error, message: STATEMENT_WORDS[read.error] }, { status: 422 }),
100 );
101 }
102 const s = read.value;
103 const slug = `${repo.ownerName}-${repo.name}`.replace(/[^A-Za-z0-9._-]/g, "_");
104 return securityFloor(
105 new Response(ledgerCsv(s, ledgerEntries(ctx.app.db, repo.id, s.month)), {
106 headers: {
107 "content-type": "text/csv; charset=utf-8",
108 "content-disposition": `attachment; filename="statement-${slug}-${s.month}.csv"`,
109 "cache-control": "private, no-store",
110 },
111 }),
112 );
113 }
test/statement-csv.test.ts added +116
@@ -0,0 +1,116 @@
1 /**
2 * The statement's ledger CSV (#13978): one row per ledger entry, a total that
3 * is the page's total, a bad month refused, the gate held, and a field that
4 * begins = + - @ defused against spreadsheet injection.
5 */
6
7 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { createRepo } from "../src/actions/repos.ts";
13 import type { Repo } from "../src/core/repos.ts";
14 import { createRun } from "../src/core/runs.ts";
15 import { createIssue } from "../src/core/issues.ts";
16 import { csvCell } from "../src/core/statement_ledger.ts";
17 import { recordUsage } from "../src/core/usage.ts";
18 import { createUser, type User } from "../src/core/users.ts";
19 import { serve, type Servers } from "../src/http/server.ts";
20 import { setEconomics } from "../src/settings/economics.ts";
21
22 describe("statement ledger csv", () => {
23 let dir: string;
24 let app: App;
25 let servers: Servers;
26 let alice: User;
27 let notes: Repo;
28
29 const login = async (username: string) => {
30 const res = await fetch(`${servers.url}/signin`, {
31 method: "POST",
32 redirect: "manual",
33 headers: { "content-type": "application/x-www-form-urlencoded", origin: servers.url },
34 body: new URLSearchParams({ username, password: "a-good-passphrase" }),
35 });
36 return (res.headers.get("set-cookie") ?? "").split(";")[0] ?? "";
37 };
38 const spend = (usd: number, at: string, issueId: string | null, kind: "build" | "review" = "build") =>
39 recordUsage(app.db, {
40 runId: createRun(app.db, { repoId: notes.id, kind: "agent" }).id, repoId: notes.id, issueId, agentId: null, subscriptionId: null, kind,
41 tokensIn: 1, tokensOut: 1, costUsd: usd, wallMs: 1, outcome: "ok", at,
42 });
43
44 beforeAll(async () => {
45 dir = await mkdtemp(join(tmpdir(), "forge-statement-csv-"));
46 app = createApp({ dataDir: dir, port: 0 });
47 servers = await serve(app);
48 for (const [username, first] of [["alice", true], ["bob", false]] as const) {
49 const made = await createUser(app.db, {
50 origin: "seed", trusted: true, username, email: `${username}@forge.local`,
51 password: "a-good-passphrase", adminIfFirst: first,
52 });
53 if (!made.ok) throw new Error(made.error);
54 if (username === "alice") alice = made.value;
55 }
56 const r = await createRepo(app, alice, { name: "notes", visibility: "public" });
57 if (!r.ok) throw new Error("repo");
58 notes = r.value;
59 const evil = createIssue(app.db, { repoId: notes.id, authorId: alice.id, title: '=HYPERLINK("http://x","a,b")' });
60 if (!evil.ok) throw new Error("issue");
61 spend(50, "2026-10-10T00:00:00.000Z", evil.value.id);
62 spend(7.1, "2026-10-31T23:59:59.000Z", null, "review");
63 spend(99, "2026-11-01T00:00:00.000Z", null); // November's
64 setEconomics(app.db, { position: 50, marginPct: 20 }, alice.id);
65 });
66 afterAll(async () => {
67 await servers.stop();
68 await rm(dir, { recursive: true, force: true });
69 });
70
71 const csvUrl = (q: string) => `${servers.url}/alice/notes/settings/app/statement.csv${q}`;
72
73 test("one row per ledger entry, and the total row is the page's total", async () => {
74 const cookie = await login("alice");
75 const res = await fetch(csvUrl("?month=2026-10"), { headers: { cookie } });
76 expect(res.status).toBe(200);
77 expect(res.headers.get("content-type")).toContain("text/csv");
78 expect(res.headers.get("content-disposition")).toContain("statement-alice-notes-2026-10.csv");
79 expect(res.headers.get("x-content-type-options")).toBe("nosniff");
80 const text = await res.text();
81 const lines = text.trimEnd().split("\r\n");
82 expect(lines[0]).toBe("date,kind,amount_usd,what");
83 expect(lines[1]).toBe(`2026-10-10T00:00:00.000Z,build,50,"'=HYPERLINK(""http://x"",""a,b"") (#1)"`);
84 expect(lines[2]).toMatch(/^2026-10-31T23:59:59\.000Z,review,7\.1,Crew run [0-9a-z]+$/);
85 expect(lines.length).toBe(7);
86 const kinds = lines.slice(1).map((l) => l.split(",")[1]);
87 expect(kinds).toEqual(["build", "review", "awake", "storage", "margin", "total"]);
88
89 const page = await (await fetch(`${servers.url}/alice/notes/settings/app/statement?month=2026-10`, { headers: { cookie } })).text();
90 // 57.10 of crew + 20% margin = 68.52 (no awake time or storage in this fixture).
91 const shown = /data-total>\$([0-9.]+)</.exec(page)![1]!;
92 expect(shown).toBe("68.52");
93 expect(lines.at(-1)!.split(",")[2]).toBe(shown);
94 expect(page).toContain("statement.csv?month=2026-10");
95 });
96
97 test("a field beginning = + - @ is neutralised, and plain text is left alone", () => {
98 for (const bad of ["=1+1", "+1", "-1", "@SUM(A1)", "\tx", "\rx"]) {
99 expect(csvCell(bad).replace(/^"/, "").startsWith("'")).toBe(true);
100 }
101 expect(csvCell("Fix login")).toBe("Fix login");
102 expect(csvCell('say "hi", ok')).toBe('"say ""hi"", ok"');
103 expect(csvCell("a\nb")).toBe('"a\nb"');
104 });
105
106 test("a bad month is 422, and someone who does not administer the repository gets 404", async () => {
107 const cookie = await login("alice");
108 for (const q of ["?month=2026-13", "?month=26-10", "?month=%3Cb%3E"]) {
109 const res = await fetch(csvUrl(q), { headers: { cookie } });
110 expect(res.status).toBe(422);
111 expect(await res.text()).not.toContain("<b>");
112 }
113 expect((await fetch(csvUrl("?month=2026-10"), { headers: { cookie: await login("bob") } })).status).toBe(404);
114 expect((await fetch(csvUrl("?month=2026-10"))).status).toBe(404);
115 });
116 });
test/tui-statement.test.ts +11
@@ -93,6 +93,17 @@ describe("the terminal's statement screen", () => {
9393 expect(text).toContain("$68.40");
9494 });
9595
96 test("l lists the month's ledger entries as rows, and back to the lines", async () => {
97 const ledger = await drive(admin, [...open, "m", "2026-10", "\r", "l"]);
98 expect(ledger).toContain("ledger entries");
99 expect(ledger).toContain("Crew run");
100 expect(ledger).toContain("2026-10-10 build $50");
101 expect(ledger).not.toContain("84 awake-hour");
102 const none = await drive(admin, [...open, "m", "2026-09", "\r", "l"]);
103 expect(none).toContain("No crew runs this month");
104 expect(await drive(admin, [...open, "m", "2026-10", "\r", "l", "l"])).toContain("84 awake-hour");
105 });
106
96107 test("[ and ] step a month; a month not YYYY-MM is refused", async () => {
97108 const back = await drive(admin, [...open, "m", "2026-11", "\r", "["]);
98109 expect(back).toContain("2026-10 (UTC)");

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs