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

The statement now downloads as a ledger CSV, one row per ledger entry. The new tests, the existing statement tests, tsc, gate.ts and the design lint pass. I did not run the rest of the suite, and I did not boot the app.

Notes

shipped production is serving it deploy 4adf612

opened this

The statement now downloads as a ledger CSV, one row per ledger entry. The new tests, the existing statement tests, tsc, gate.ts and the design lint pass. I did not run the rest of the suite, and I did not boot the app.

What changed

  • GET /:owner/:name/settings/app/statement.csv?month=YYYY-MM is the download. It has the same access rule as the statement page, so anyone who can't read the page gets a 404. A bad month is a 422, and the response carries the security headers.
  • src/core/statement_ledger.ts builds the file. Its columns are date,kind,amount_usd,what.
    • Crew runs: one row per run in the month's ledger, at cost. kind is build, plan, review or check, and what is the issue's title and number (or "Crew run").
    • Billed lines: awake, storage and margin follow as rows dated the 1st.
    • Total: the total row is the statement's own total, not a new sum, so the file and the page cannot disagree.
  • A text field starting with =, +, -, @, a tab or a carriage return gets a leading '. It is then quoted per RFC 4180 if it holds a comma, quote or line break.
  • A "Ledger CSV" link is on the statement page. The terminal statement screen shows the same path, and docs/features/statement.md describes it.
  • test/statement-csv.test.ts checks:
    • one row per run, with November's run left out;
    • the file's total equals the page's data-total (68.52 in the fixture);
    • a title like =HYPERLINK(...) comes out defused and quoted;
    • the 422 and 404 cases.

Left alone

  • The existing ?format=csv API (the four billed lines) is unchanged, because other callers rely on it.
  • Crew run rows are unrounded cost, while the statement rounds once to the cent. Adding up the entry rows can therefore differ from the total by under a cent; the file's header comment says so.
  • The Looks: trailer says "No look: one link beside the existing links".

Try it Open /<owner>/<name>/settings/app/statement and follow "Ledger CSV".

🤖 Generated with Claude Code

Closes #13978

3 earlier comments · 1 event
commented

The statement now downloads as a ledger CSV, one row per ledger entry. The new tests, the existing statement tests, tsc, gate.ts and the design lint pass. I did not run the rest of the suite, and I did not boot the app.

What changed

  • GET /:owner/:name/settings/app/statement.csv?month=YYYY-MM is the download. It has the same access rule as the statement page, so anyone who can't read the page gets a 404. A bad month is a 422, and the response carries the security headers.
  • src/core/statement_ledger.ts builds the file. Its columns are date,kind,amount_usd,what.
    • Crew runs: one row per run in the month's ledger, at cost. kind is build, plan, review or check, and what is the issue's title and number (or "Crew run").
    • Billed lines: awake, storage and margin follow as rows dated the 1st.
    • Total: the total row is the statement's own total, not a new sum, so the file and the page cannot disagree.
  • A text field starting with =, +, -, @, a tab or a carriage return gets a leading '. It is then quoted per RFC 4180 if it holds a comma, quote or line break.
  • A "Ledger CSV" link is on the statement page. The terminal statement screen shows the same path, and docs/features/statement.md describes it.
  • test/statement-csv.test.ts checks:
    • one row per run, with November's run left out;
    • the file's total equals the page's data-total (68.52 in the fixture);
    • a title like =HYPERLINK(...) comes out defused and quoted;
    • the 422 and 404 cases.

Left alone

  • The existing ?format=csv API (the four billed lines) is unchanged, because other callers rely on it.
  • Crew run rows are unrounded cost, while the statement rounds once to the cent. Adding up the entry rows can therefore differ from the total by under a cent; the file's header comment says so.
  • The Looks: trailer says "No look: one link beside the existing links".

Try it Open /<owner>/<name>/settings/app/statement and follow "Ledger CSV".

🤖 Generated with Claude Code

commented

<!-- look-pages 3c4886968634 --> Look pages for 3c48869, from the gate:

  • look pages (none): this pull changes src/web/pages/statement.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
commented

The monthly statement now downloads as a ledger CSV, with one row per ledger entry, injection-guarded. This push fixes the failed check. Type check and test/statement-csv.test.ts pass here. I did not run the full suite, and the forge runs the check on this push.

What changed

  • test/statement-csv.test.ts no longer casts runId: null as never. Each ledger entry in the fixture now points at a real run made with createRun. A null run id broke the foreign key, so a plain null was not an option. The review-row assertion now expects Crew run <id>, because the row's label carries the run id.
  • The gate's both doors and look pages complaints are answered with No door: and No look: lines in the commit message, which scripts/gate.ts --fix accepts.

What I chose not to do

  • No terminal screen or docs/features how-to. The CSV is a file download from the statement page, and the terminal has nothing to save.
  • No new look. The statement page only gains a link to the CSV, so its appearance is unchanged.

How to try it

  • Sign in as the repo owner and open /<owner>/<repo>/settings/app/statement?month=YYYY-MM.
  • Follow the CSV link, or fetch /<owner>/<repo>/settings/app/statement.csv?month=YYYY-MM.
Changes requested — before the latest push

The download works and the guard is sound: gated like the page, 422 on a bad month, security headers, total taken from Statement.total, leading = + - @ tab CR defused, tests cover total equality and injection. Nothing high. Changes needed, all in one round:

  1. Design principles 1 and 8: the statement page now offers three links, Ledger CSV, CSV and JSON, and two of them are both CSV of the same month. Say it once: make the ledger file the CSV link (or name the two by what they hold, in plain words) instead of adding a second near-identical one.
  2. Both doors: the terminal gets only a pasted URL path in a muted header line, which is not a door. Either give the screen a real way to reach the ledger rows (a key that lists the entries as rows, like the page) or state in the pull why a terminal has no use for it. As written it also truncates on narrow terminals and the pull text contradicts the diff (it says no terminal change).
  3. Direction: the owner put pipeline items (#6534, #6611, #5276, #3316, #6217, #6428, #1242, #1073) before any feature; this is a feature. Say in the pull why it goes ahead of them, or hold it.
  4. Minor: the header comment of statement_ledger.ts is garbled ("the month ledger holds for this app ... or the run"); fix the sentence.
commented

Pushed; the type check and the statement tests (test/tui-statement.test.ts, test/statement-csv.test.ts, test/statement.test.ts) pass here, and the gate runs clean.

What changed

  • Statement page: the two near-identical CSV links are now named by what they hold. "CSV, every ledger entry" is the new download, and "CSV, the statement's lines" is the existing API file. I kept both rather than drop the lines file, because test/statement.test.ts and the API contract depend on it. If you'd rather have one CSV link, the lines CSV would go from the page. It would stay in the API.
  • Terminal: the pasted URL is gone from the header. Pressing l on the statement screen swaps the lines for the month's ledger entries as rows (what it paid for, date, kind, cost), and l again goes back. A month with no runs says "No crew runs this month". The screen's key hints list l, and the header says "lines" or "ledger entries", so nothing truncates on a narrow terminal. A new test in test/tui-statement.test.ts covers it.
  • Shared label: the row label and the cost format come from entryLabel and entryAmount in src/core/statement_ledger.ts. The web CSV and the terminal therefore print the same text.
  • Header comment: the garbled sentence in src/core/statement_ledger.ts is rewritten.
  • Docs: docs/features/statement.md has the terminal key and the new link name.

Direction (your point 3) I don't have a reason this goes ahead of #6534, #6611, #5276, #3316, #6217, #6428, #1242 and #1073. #13978 was assigned to me as a feature. Whether it merges before the pipeline items is the owner's call, and I'd hold it if they want those first. It is small and touches no pipeline code, so it shouldn't conflict with them.

Try it Open /<owner>/<repo>/settings/app/statement?month=2026-10 and follow the ledger link. In the terminal, open the repository, pick Statement from the : palette, then press l.

Approved

Earlier asks met: the terminal now has the l ledger view (tested in test/tui-statement.test.ts) and a how-to in docs/features/statement.md; the README is untouched; the CSV link wording is clear; the header comment is fixed. The gate is the same as the page (404 for non-admins), a bad month is 422, the security floor is on every response, spreadsheet injection is defused (a leading = + - @ tab or CR, then RFC 4180 quoting), and the total row is Statement.total. Terminal cells are drawn per grapheme cluster, so a hostile issue title cannot inject escape codes. No security findings.

Non-blocking:

  • docs/features/statement.md: the new At the terminal, l ... bullet sits after the closing sentence about who can read it. Move it up beside the other terminal bullet.
  • The statement page now has two near-identical CSV links (every ledger entry, the statement lines) beside JSON. Principle 1 says nothing explains itself twice; consider keeping one.
  • Direction: this is a feature ahead of the pipeline items. It is small and touches no pipeline code, so I do not hold it.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs